# Editor Sample Regression Pack

> **Historical plan — not current implementation guidance.** Use the [documentation index](../../docs/README.md) for current behavior and architecture.

Date: 2026-07-13
Issue: BS-JD-501 / Gitea #32
Milestone: M5 - Regression, docs, and first-hour UX

## Goal

Ship a deterministic five-scene editor regression pack that is easy to open from the editor and
that fails headless validation when its catalog, authored data, or referenced assets drift. The pack
must cover Brush, Material, Terrain, Physics Placement, and Rendering workflows.

## Decisions

- `assets/samples/editor_samples.ron` is the conventional, versioned pack manifest. This remains a
  QA/editor convention and does not extend `ProjectSettings`.
- The manifest is parsed and validated in the `scene` crate. Editor UI and headless tooling consume
  that one representation.
- Every entry has a stable ID, label, area, project-relative `.scn.ron` path, summary, and nonempty
  operator checks. Manifest order is menu and report order.
- Exactly one entry for each required area is release-gated. Scene paths must remain regular files
  inside `assets/levels/`; traversal, absolute paths, symlink escapes, duplicates, and future schemas
  are blocking.
- Existing accepted terrain, physics-placement, and rendering fixtures remain canonical entries.
  Add dedicated brush and material scenes under `assets/levels/samples/` and strengthen weak visual
  anchors in the existing fixtures instead of duplicating them.
- `cargo validate-samples --project .` combines pack-specific structure/feature checks with the
  authoritative `validate_project` report. It verifies stable actor IDs, required area components,
  authoring-only scene documents, and referenced content.
- Terrain descriptors and their shared material layers become first-class project-validation input.
  Actor-owned invalid descriptors or missing material references are blocking findings.
- `File > Open Sample` is backed by a cached project catalog and opens through normal scene-tab I/O.
  Invalid or unavailable catalogs produce a disabled, actionable row rather than a panic.
- CI hydrates Git LFS before content validation and runs both validation commands. Packaged-runtime
  tests remain deferred by project-owner request.

## Implementation

1. Add the manifest schema, deterministic report, safe path resolver, and sample feature checks to
   `scene::sample_pack`, with malformed/missing/duplicate/path-escape fixture tests.
2. Add typed `TerrainDesc` validation and base/layer material dependency collection to authoritative
   project validation, including owner-attributed tests.
3. Add the `validate-samples` xtask binary, Cargo alias, JSON mode, stable console summary, and CI
   steps. Enable LFS hydration at checkout and verify hydrated objects.
4. Add the five-entry manifest, `brush_blockout.scn.ron`, and `material_lab.scn.ron`. Give every
   sample actor a stable `ActorId`; add visible rendering anchors and distinct physics shapes where
   the current fixtures are ambiguous.
5. Load the catalog after project startup, render `File > Open Sample` in manifest order, and route a
   selected stable ID through scene I/O. Add unknown-entry and deterministic-row tests.
6. Add a no-GPU typed-deserialization test over every manifest scene so unknown Bevy component
   registrations fail before native QA.
7. Document pack contracts, per-scene checks, release commands, and the editor workflow. Update ADR
   0028, the root README checklist/controls, editor/docs indexes, feature guides, roadmap status,
   debt audit, and production-readiness evidence.
8. Run source gates, open all five samples through the native menu, exercise one representative tool
   interaction per area, inspect logs, and attach representative native issue images when useful.

## Acceptance

- Five manifest entries cover all required areas and open through `File > Open Sample`.
- Every entry type-deserializes and has stable actor IDs plus its required authored feature.
- `validate-levels` reports terrain material dependencies and has no blocking findings.
- `validate-samples` is deterministic, CI-backed, and exits nonzero for pack or project blockers.
- Native viewport captures are nonblank, correctly framed, and free of missing-reference, hydration,
  render, or operator errors.
- Documentation gives contributors a single release-use workflow and explains every sample check.
