Blacksite/.cursor/plans/editor_sample_regression_pack_2026-07-13.plan.md

Editor Sample Regression Pack

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.