Fix project structure

card-harness/README.md

@@ -0,0 +1,130 @@
+# Sanctification Card Lab
+
+Bounded Three.js proof for the card-rendering harness plan.
+
+The approved visual baseline is recorded in [`CURRENT-DEFAULTS.md`](CURRENT-DEFAULTS.md).
+
+## Included proof scope
+
+- David printed-ink, foil, and holographic presets
+- Independently selectable paper, linen, plastic, metal, and wood substrates
+- Timothy as the second-artwork fixture
+- David color-based coverage and title-panel protection without face/hand/lamb cutouts; automatic saturation/value coverage for Timothy
+- Procedural rounded-card geometry generated from shared physical dimensions
+- Deterministic linen normal map
+- Card manipulation, camera inspection, zoom, frame-rate-independent flip/reset, interruption-safe sweep, and movable lighting
+- Repeatable front, grazing-angle, edge, and back inspection poses
+- Point, directional, and spot lighting with repeatable studio, gallery, window, dramatic, and flat-review presets
+- Live light color, position, intensity, environment contribution, and exposure controls
+- Lab-mode loading of local artwork and finish-mask images without rebuilding
+- Named browser experiment saves, versioned JSON import/export, and PNG capture
+- Deterministic condition wear with substrate-aware edges, scratches, scuffs, and imperfection seeds
+- Bare Inspect mode and small Lab-mode parameter panel
+- Pack mode: a touch-responsive foil pouch with a draggable tear strip, reveal-safe ordered stack, and one-at-a-time inspection
+- Drawing-buffer resolution plus median, p95, and worst frame-time display
+
+Transform gizmos and a general timeline are intentionally deferred. The separate Flutter Scene comparison project is unchanged; Three.js remains the authoritative runtime.
+
+## Tear-open foil pack prototype
+
+Choose **Pack** in the Mode selector (expand **Controls** first on mobile).
+Drag the gold top seam **to the right**, or use **Tear open** for the same authored opening without dragging:
+
+**Sealed → progressive tear → strip curls away → mouth spreads → staggered card extraction → face-down stack → lifting → lifted → revealing → inspecting → advancing → next stack / complete.**
+
+Lifting and flipping are separate actions so the universal back can be reviewed before revealing.
+The authored order is always David / Printed ink / Linen, Timothy / Foil / Paper,
+then David / Holographic / Metal. This is not a randomized reward system.
+
+- The seam has a mouse/touch hit area at least 44 px tall. Drag distance drives tear progress monotonically: pulling back does not reseal it. A full pull completes the opening on release; a short pull holds its exact tear and **Finish opening** continues from there. The progress bar and percentage also expose the state without relying on the animation.
+- Cancellation or lost pointer capture holds a partial tear; another seam pull, **Finish opening**, or **Skip** can continue it. A second finger relinquishes the tear gesture to pinch zoom. Restart and mode changes release all captured pointers.
+- Pressing the pouch makes a small local dent that settles on release. Creases and seam crimps are deterministic, not continuously moving noise.
+- Drag to rotate and pinch or wheel to zoom during inspection. Pinch/wheel zoom also works before revealing; hidden cards cannot be manually tilted. User zoom may intentionally crop the composition.
+- Touching or zooming during a scripted transition pauses at the current pose. **Continue** resumes from that elapsed point, without snapping. A tap that interrupts motion does not also advance it.
+- **Skip** finishes only the current transition, or performs one step immediately from a resting state. It never skips an unseen card's reveal. **Restart** restores the sealed wrapper and first card.
+- Reduced-motion preference shortens each transition to 70 ms with the same state and reveal/completion ordering.
+- Switching away pauses Pack and preserves the Inspect/Lab card, camera, materials, local images and experiment settings. Returning to Pack resumes its retained state via Continue.
+
+The foil wrapper is two subdivided, joined pouch surfaces and a separate subdivided
+top ribbon. Controlled vertex deformation creates shallow creases, a travelling tear
+front, a curled detached strip, and spreading lips. Typography is printed directly
+on the sheet materials, not on an almost-coplanar label layer. There is no rigid-panel
+split, transparent cross-fade, cloth engine, or extra asset dependency.
+The pouch stays above the floor while the three cards slide upward with a small
+stagger. Only after all cards clear the mouth does the empty pouch move aside; the
+cards then settle into the existing face-down stack. Opening-only camera framing
+widens and recenters during extraction, then returns to the established stack framing.
+
+Cards use the existing procedural geometry and approved runtime shader.
+Before revealing, fronts are hidden, backs share the fixed universal material, and
+edges use a neutral paper recipe. Authored substrate edges are enabled only after
+the flip finishes. The active card lifts to a dedicated inspection plane before
+flipping or free rotation. The reserve stack stays visible, offset to the lower
+right and safely behind the active card's full corner-sweep volume. The exit
+animation also stays on that safe plane while the reserve stack recenters.
+Camera framing eases with the lift/exit so the deeper separation does not
+unexpectedly enlarge the card. The edge mesh draws only extrusion side walls, not end caps beneath the
+dedicated artwork faces, preventing depth-fighting bands at farther zoom distances.
+Pack assets are loaded separately on first entry, with retry on failure.
+
+There is no sound, haptics, particles, cloth simulation, backend, rewards persistence,
+pack progress persistence, or timeline/editor. This is a choreography proof, not an
+final pack-design or mobile performance sign-off. The approved rigid prototype and
+artifact-free card inspection are the preserved foundation; this foil treatment is
+the next review iteration. The canvas emits `packreveal`
+(one-based index and variant) and `packcomplete` (count), once per card/pack per restart.
+
+Finish and substrate are separate:
+
+- Finish controls printed ink, foil, or holographic coating.
+- Substrate controls surface roughness/microtexture, underprint response, and edge/core appearance.
+
+Paper uses fine, irregular fibers and a broad, weak highlight. Linen uses raised
+interlaced threads with small shaded recesses. Plastic has a smooth clear-coat
+highlight even in Printed ink mode. Wood uses warped longitudinal grain with
+surface relief and a restrained warm tint. Metal retains its reflective
+underprint and adds a shallow luminance-driven etch, with darker artwork
+recessed slightly more than lighter artwork. Procedural detail fades below
+pixel resolution to limit shimmer.
+The universal card back uses fixed neutral material properties so front finish
+and substrate choices do not spoil a pack reveal.
+The holo spectrum and coverage rules are independent of these substrate changes.
+Metal combined with Foil preserves the printed colors while adding restrained,
+slightly raised champagne-metal polishing over the etched steel base.
+
+## Reference
+
+`npm run assets` creates `public/reference/manifest.json`, copies the source artwork and approved reference renders, and generates the two masks and normal map. Card geometry is generated directly in Three.js from the dimensions recorded in the manifest; Blender is not required to build or run the harness. The current runtime reference revision is `runtime-look-v4-2026-09-07`, visually informed by:
+
+- `blender_prototype/premium_finishes.py`
+- `blender_prototype/card_finish_material.py`
+- `blender_prototype/render_premium_review.py`
+
+The runtime shader and geometry are runtime implementations, not a claim of pixel-identical Blender output.
+Live review removed only David's face, hand, and lamb ellipse cutouts. Color-based coverage and title-panel protection remain. Holographic color and angle response are preserved; reduced sheen applies only to foil.
+
+## Run
+
+```sh
+npm install
+npm run dev
+```
+
+Production build:
+
+```sh
+npm run build
+```
+
+The asset-generation script uses cross-platform Node APIs and works on Windows and Linux. The retained `export:blender` script is an optional reference utility and is not part of the application pipeline.
+
+## Baseline
+
+Initial development machine:
+
+- Windows
+- Intel Arc Graphics, driver `32.0.101.6737`
+- Node `24.14.1`
+- Three.js version pinned by `package-lock.json`
+
+The browser/version, viewport, drawing-buffer resolution, texture settings, and observation duration must be recorded during material approval. The on-screen frame-time display is diagnostic rather than a complete benchmark.