Build Vesperfall Review Assets

Create one reviewable asset pair without confusing catalog media, imported files, procedural factories, and future contracts.

Workflow

1. Inspect repository truth before choosing a model path.

• Locate shipped PNG, FBX, GLB, textures, runtime factories, and declared-but-missing paths.
• Prefer a shipped FBX/GLB when it is the actual runtime source.
• Use $img2threejs only when reconstructing from an image in code. Never relabel imported geometry as img2threejs.
• Do not claim a GLB or texture exists because code declares a future URL.

1. Produce the transparent catalog reference.

• Reuse or derive from the production portrait when it already matches the asset identity.
• Normalize catalog copies to 512×512 RGBA unless the project contract says otherwise.
• Keep transparent corners and avoid baked floor, halo, or shadow.
• Store project-bound output under public/asset-catalog/<category>/.

1. Build the live model preview.

• Put loading/model construction in a small asset-specific module.
• Preserve runtime provenance in userData: source paths or factory, action count, sockets, and review-only status.
• Attach equipment to named sockets. Keep materials, renderer, mixers, events, and animation frames disposable.
• Frame from measured bounds. Ground from foot/contact geometry, not the lowest weapon tip.

1. Pair the catalog surfaces.

• Card/grid: transparent PNG only, with no canvas.
• Selected inspector: one live model canvas plus truthful format label.
• Add a button to an isolated preview or moveset route.
• Keep fallback media visible until WebGL/model loading is ready.

1. Build the isolated review route.

• Expose the real action library when clips exist.
• Provide restart, pause/play, action selection, drag rotation, source paths, and provenance.
• For procedural motions, mark runtime, contract, and candidate actions separately.

1. Validate before committing.

• Run scripts/validate_pair.py <png> <model-source>.
• Add inventory tests for exact paths, RGBA dimensions, preview kind, and route.
• Test every motion/contact point deterministically when grounding changes with animation.
• Run build, lint, full tests, and git diff --check.
• Use the Codex in-app browser only. Verify desktop and mobile, card PNG/no canvas, inspector model/one canvas, preview navigation, grounding, scroll, overflow, broken media, and console warnings/errors.

1. Commit the narrow task and hand off its exact SHA before deployment reconciliation.

Read references/catalog-contract.md when changing catalog types, provenance language, or review-route behavior.

Required reporting

Report:

• PNG path, dimensions, and alpha status
• model source or procedural factory
• whether the model is imported, runtime procedural, or review-only reconstruction
• preview route and available actions
• test/build/browser proof
• exact commit SHA