Sanctification/card-harness/CURRENT-DEFAULTS.md

# Sanctification Card Lab - Current Defaults

## Approved Runtime Look

- Revision: `runtime-look-v4-2026-09-07`
- Approved: September 7, 2026
- Scope: card geometry, front-face materials, substrate distinction, foil, holographic response, and current finish-mask policy
- Follow-up approval: rigid pack prototype and artifact-free individual card inspection; retained as the foundation for the foil iteration below
- Linen follow-up: `linen-relief-v1-2026-09-10`, visually approved September 10, 2026
- Metal and wood follow-up: `metal-wood-relief-v1-2026-09-10`, visually approved September 10, 2026
- Not yet approved: the new foil treatment/choreography, lighting presets, mobile performance, or wear

These values represent the current visual baseline. Changes should be deliberate and compared against this revision rather than treated as incidental shader cleanup.

The approved September 10 depth follow-ups supersede the v4 linen, metal, and wood
surface responses below: raised-looking weave, recessed metal etching, and raised
wood grain with shader parallax, including Printed ink at oblique angles.
Paper, Plastic, card geometry, backs, and renderer settings retain the v4 baseline.
This visual approval is not
a mobile performance sign-off or approval of the remaining pack choreography.

## Geometry

The card is generated procedurally at runtime. Blender and GLB files are not required.

| Property | Physical value | Runtime value |
|---|---:|---:|
| Width | 63 mm | 2.8571 scene units |
| Height | 88.2 mm | 4 scene units |
| Thickness | 0.4 mm | 0.01814 scene units |
| Corner radius | 2.8 mm | 0.12698 scene units |
| Corner segments | - | 16 |

Front and back use normalized UV coordinates with no runtime mirroring. The front, back, and edge are separate material surfaces.
The edge extrusion renders only side-wall triangles; its generated end caps are
excluded from the draw range. Front and back sit exactly at half the physical
thickness, with no almost-coplanar cap underlay or artificial depth offset.

### Reveal-Safe Card Back

The universal card back is intentionally independent from the selected front finish, substrate, finish strength, surface detail, and condition. This prevents the hidden card identity or variant from being inferred during a pack reveal.

| Property | Fixed value |
|---|---:|
| Roughness | 0.42 |
| Metalness | 0 |
| Clear coat | 0.20 |
| Clear-coat roughness | 0.24 |
| Normal map | None |

The physical edge remains substrate-aware for close inspection. Pack-opening choreography should keep the thin edge from becoming a deliberate pre-reveal inspection surface.

## Renderer

| Setting | Default |
|---|---|
| Output color space | sRGB |
| Tone mapping | ACES Filmic |
| Exposure | 1.0 |
| Pixel ratio | `min(devicePixelRatio, 2)` |
| Scene background | `#0b0e14` |
| Environment | Generated 128 px studio cube texture |

## Camera and Reset Pose

| Setting | Default |
|---|---:|
| Perspective field of view | 34 degrees |
| Near / far planes | 0.1 / 100 |
| Camera position | `(0, 0, 8.2)` |
| Orbit target | `(0, 0, 0)` |
| Orbit distance | 5-12 |
| Card rotation | `(-0.06, 0.12, 0)` radians |

Available inspection poses:

| Pose | Card rotation |
|---|---|
| Front | `(-0.06, 0.12, 0)` |
| Grazing | `(-0.14, 52 degrees, 0)` |
| Edge | `(-0.05, 90 degrees, 0)` |
| Back | `(-0.06, 180 degrees + 0.12 radians, 0)` |
| Free | Current manually controlled rotation |

Reset restores the Front pose, David, Holographic finish, Paper substrate, default surface values, default camera, and default light.

## Light

| Setting | Default |
|---|---|
| Type | Point light |
| Color | `#fff0d0` |
| Position | `(2.2, 2.5, 4.4)` |
| Shader intensity | 3.0 |
| Three.js light intensity | 34 |
| Distance / decay | 20 / 1.7 |
| Environment intensity | 0.7 |

Lighting presets are available for repeatable evaluation but are not yet visually approved:

| Preset | Type | Color | Position | Intensity | Environment | Exposure |
|---|---|---|---|---:|---:|---:|
| Studio | Point | `#fff0d0` | `(2.2, 2.5, 4.4)` | 3.0 | 0.70 | 1.00 |
| Warm gallery | Spot | `#ffd29a` | `(-2.8, 3.1, 4.8)` | 4.0 | 0.52 | 1.04 |
| Cool window | Directional | `#bddcff` | `(-3.4, 4.2, 5.2)` | 2.7 | 0.78 | 1.00 |
| Dramatic spot | Spot | `#ffe1ad` | `(3.6, 1.9, 3.6)` | 4.8 | 0.28 | 0.92 |
| Flat review | Directional | `#ffffff` | `(0.6, 0.8, 5.5)` | 2.25 | 1.00 | 1.00 |

Changing a light type, color, position, intensity, environment contribution, or exposure marks the lighting configuration as Custom.

## User-Facing Surface Controls

| Control | Default | Available range |
|---|---:|---:|
| Finish | Holographic | Printed ink / Foil / Holographic / Gold leaf / Frosted glass |
| Material | Paper | Paper / Linen / Metal / Wood / Leather |
| Finish strength | 0.60 | 0-1 |
| Roughness | 0.23 | 0.05-0.8 |
| Surface detail | 0.14 (Leather selection: 0.45) | 0-1.0 |
| Horizontal metal grain (Lab only) | Off (Vertical) | Off / On (Horizontal) |
| Environment intensity | 0.70 | 0-1.5 |
| Condition | 1.0 (mint) | 0-1 |
| Imperfection seed | 81251 | 1-99999 |

Finish and material are independent concepts, but combinations should exist only when they have an intentional visual interpretation.

September 12 material tuning (pending visual review): Roughness now contributes
75% of effective substrate roughness, with a 25% material bias. Every step across
`0.05-0.8` changes highlight width; the former substrate floors/ceilings are removed.
Surface detail accepts `0-1.0` in Lab and saved experiment imports. Selecting a
material restores its detail default: Leather `0.45`, all others `0.14`. Imported
experiments retain their explicit detail value (clamped only to `0-1.0`); Reset
restores Paper with detail `0.14`. Existing relief caps remain to bound parallax
and prevent extreme recesses. Random Leather pack cards also use `0.45`.


Leather, Gold leaf, and Frosted glass are experimental
September 11 additions awaiting visual review. They do not change the existing
default selection or approved recipes. Leather applies generic substrate
relief and edge treatments with grain suppressed over mask-protected ink; the two
new coatings follow each card's finish mask. Vellum and Pearlescent were removed
after visual review; Leather's initial aggressive grain was replaced with shallow,
softly filtered grain pending further approval.
Frosted glass is an opaque etched coating, not a transparent card material. See the
[experimental treatment descriptions](README.md#experimental-materials-and-finishes).

## Substrate Recipes

### Paper

- Roughness bias: `0.56` (`0.75 * roughness + 0.25 * bias`)
- Fiber frequency: `230 x 322`
- Relief amplitude: `0.0014 * detail`
- Broad reflection strength: `0.045`
- Edge: `#9c8c69`, roughness `0.62`, metalness `0.02`, clear coat `0.02`

### Linen

- Roughness bias: `0.70` (`0.75 * roughness + 0.25 * bias`)
- Interlaced thread frequency: `52 x 73`
- Raised weave height span: `0.010 * min(detail, 1.5)` scene units
- Analytic thread slopes keep normal response readable at oblique angles
- Two procedural weave evaluations add bounded view-dependent parallax; artwork,
  finish-mask, and wear UVs stay anchored
- Grazing denominator floor: `0.30`; detail is capped at `1.5` for linen relief
- Subpixel threads fade using screen-space derivatives
- Base reflection strength: `0.025`; broad thread-ridge highlight strength:
  `0.025 + 0.055 * grazing`, modulated by resolved ridge height and surface detail
- Edge: `#a89772`, roughness `0.78`, metalness `0`, clear coat `0`

This is shader relief, not displaced geometry: the card silhouette and physical
thickness are unchanged. The Surface detail control scales the effect, including
turning it off at zero. Printed ink retains the thread lighting without requiring
a foil finish; foil and holographic coating formulas are unchanged.

### Plastic

- Roughness bias: `0.25` (`0.75 * roughness + 0.25 * bias`)
- Dielectric Fresnel base: `0.04`
- Reflected fraction cap: `0.32`
- Direct highlight cap: `0.50`
- Edge: `#d4cab0`, roughness `0.24`, metalness `0`, clear coat `0.72`

### Metal

- Visually approved September 10, 2026
- Roughness bias: `0.20` (`0.75 * roughness + 0.25 * bias`)
- Artwork-driven etch: darker values are recessed more deeply
- Etch relief amplitude: `-0.010 * depth * min(detail, 1.5)` (previously `-0.0065`)
- Bounded predictor/corrector parallax shifts artwork and finish mask together;
  grazing denominator floor `0.35`, fading within `0.025` UV of the card edges
- Directional recess shadow strength: `0.22`, scaled by detail and local ridge depth
- Cavity shading: `0.12` on the metal underprint and `0.06` on the combined printed result
- September 12 contrast/brush tuning awaits visual review; September 10 approval
  applies to the retained etch/parallax foundation
- Color-preserving reflected ink tint: `mix((0.94, 0.97, 1.0), 0.58 + environment * 0.72, weight)`
- Reflection weight: `(0.16 + 0.22 * grazing^2) * environmentIntensity * (0.35 + 0.65 * gloss)`, capped `0.45`
- Metal underprint blend: `0.32`; reflected tint multiplies ink, preserving dark values
- Brushed-aluminum orientation: Vertical by default; Lab **Horizontal metal grain**
  toggles the prior horizontal treatment using only a boolean uniform
- Brushed-aluminum phases: `680`, `1760`, `3540` radians/UV with
  slow irregular drift; weighted `0.55 / 0.30 / 0.15` and independently filtered
- Brush relief: `0.00035 * brush * min(detail, 1.5)`; ink shading amplitude `0.075`
- Vertical swaps brush UV axes; Horizontal uses the original UVs and recipe unchanged
- Orientation affects only brush relief/shading; artwork, etch, finish mask, and text UVs retain their existing behavior
- Generic linen normal-map contribution disabled for Metal so the brush direction stays consistent
- Direct metal highlight follows roughness, with ink-dependent strength `0.08-0.28`
- Edge: `#a8adb7`, roughness `0.20`, metalness `0.86`, clear coat `0.18`

Metal + Foil is a special intentional combination:

- Preserves printed artwork colors
- Reduces etch depth beneath the foil mask by at most 25%
- Adds only `0.0005 * mask * detail` of raised relief
- Uses restrained champagne tint `#ffd694`
- Plating weight is capped at `0.34`
- Must not turn the illustration into opaque gold

Parallax and directional recess shading add depth cues beyond the stronger relief.
The September 12 underprint tuning retains colors and dark values; foil plating
also follows the Roughness control. The finish mask follows the shifted artwork.
Card thickness and geometry are unchanged.

### Wood

- Visually approved September 10, 2026
- Roughness bias: `0.48` (`0.75 * roughness + 0.25 * bias`)
- Warped longitudinal grain frequency: `170`
- Relief amplitude: `0.012 * min(detail, 1.5)` (previously `0.007 * detail`)
- Two procedural grain evaluations provide bounded parallax; grazing denominator
  floor `0.35`. Artwork stays anchored; tint and relief use the same shifted grain.
- Warm tint blend: `0.25`
- Reflection strength: `0.09`
- Edge: `#6b3f21`, roughness `0.56`, metalness `0`, clear coat `0.08`

## Finish Recipes

### Printed Ink

- Returns the substrate response without an additional coating.
- Substrate relief and reflection must remain visible.

### Foil

- Uses the finish mask as selective coverage.
- Effective finish strength: `finishStrength * 0.8`
- Maximum coating weight: `0.48`
- Coating response cap: `0.78`
- Reflection is warm and screened with the original artwork rather than replacing it.
- Reduced sheen applies only to Foil, not Holographic.

### Holographic

- Effective finish strength: `finishStrength`
- Maximum coating weight: `0.92`
- Coating response cap: `1.8`
- Spectral reflection blend: `0.72`
- Artwork-to-spectral coating blend: `0.48`
- The approved spectrum uses UV, view direction, and light direction so color shifts while the card moves.
- Do not weaken the holographic color response to solve mask problems; correct the mask instead.

## Finish Masks

### New Stained-Glass Cards — raw-ridges-v1

- Approved by the user: September 13, 2026, after comparing The Fall and Burning Bush raw-ridge Normal fixtures.
- Default scope: future stained-glass assembly; existing cards/fixtures retain their selected recipes. No migration is requested.
- Implementation: [shared production module](../tools/card-production/README.md); exact parameters are pinned in [raw-ridges-v1.json](../tools/card-production/recipes/raw-ridges-v1.json).
- Visual behavior: raw ridge confidence protects glass dividers/fine ink, with 62–90% pane coating weights. No subsequent continuity filtering, bridging or manual repair patches.
- Resolve each printing’s actual visible components before exporting its finish map. New artwork and other printings receive their own structural/static/moving-light review.
- [Approval/reference hashes](../tools/card-production/recipes/raw-ridges-v1-approval.json) and [comparison proof](../spikes/finish-mask-line-continuity-proof/raw-ridges/README.md) preserve the decision.
- Runtime shader, material coefficients, texture count and existing optional glyph-mask policy are unchanged by this production recipe.

The following entries document existing fixture recipes.

### David

- Saturation threshold: `smoothstep(0.18, 0.62)`
- Value threshold: `smoothstep(0.015, 0.16)`
- Retains soft title-panel protection.

### Timothy

- Saturation threshold: `smoothstep(0.08, 0.58)`
- Value threshold: `smoothstep(0.015, 0.16)`

All finish masks should:

- Protect critical text unless a treatment is intentionally designed for it.
- Follow compositional regions such as stained-glass panes, ornament, borders, garments, and environmental color.
- Be reviewed while the card rotates under multiple lighting angles.

## Wear and Imperfections

Wear/condition and imperfections are deferred product features. These settings document existing experimental harness behavior, not M1 requirements.

Condition uses `1.0` for mint and `0.0` for the most worn supported appearance. The approved v4 material baseline remains unchanged at the mint default.

- Edge wear uses seeded irregular width and substrate-appropriate exposed colors.
- Three deterministic fine scratches and two deterministic scuff regions are generated from the imperfection seed.
- Scratches and scuffs perturb the surface normal slightly and reduce finish coverage where the coating is damaged.
- Paper and linen expose pale fibers, plastic becomes cloudy, metal exposes brighter raw metal, and wood exposes a lighter brown layer.
- Wear remains bounded so the card artwork stays readable even at condition `0.0`.

## Local Asset Evaluation

Lab mode can replace the active artwork or finish mask with a local image through the browser file picker. Local files remain in browser memory, are not copied into the project, and are discarded when the page reloads or the selected fixture is restored. Reset restores the David reference artwork and mask.

## Experiment Snapshots

Lab mode can save named experiments in browser storage, export or import a versioned JSON snapshot, and capture the current canvas as PNG. Snapshot schema version 2 records:

- `metalBrushHorizontal`: boolean (`false` = Vertical, `true` = Horizontal), including browser saves and JSON exports; omitted fields in older experiments restore Horizontal. Reset and all pack cards use Vertical.

- Runtime-look revision and save time
- Reference fixture and custom asset filenames
- Finish, substrate, and surface controls
- Condition and imperfection seed
- Lighting preset, environment, type, color, position, intensity, and exposure
- Card rotation, camera position, and orbit target

Local image contents are intentionally not embedded in snapshots. When a snapshot records custom artwork or a custom mask, those files must be loaded again after restoring the configuration.

Schema version 1 snapshots remain loadable and restore as mint condition with seed `81251`.

## Source of Truth

- Geometry: `src/cardGeometry.ts`
- Runtime shader: `src/cardMaterial.ts`
- Scene and control defaults: `src/main.ts`
- Generated asset contract: `public/reference/manifest.json`
- Art policy: `../art-direction.md`

## Tear-Open Foil Pack (Next Review Iteration)

Pack is a third mode beside Inspect and Lab. It does not revise
`runtime-look-v4-2026-09-07`, saved experiments, or the reference asset contract.

- Controller: `src/packOpening.ts`; foil meshes: `src/foilWrapper.ts`; integration and lazy local-asset loading: `src/main.ts`.
- States: `sealed → opening → stackReady → lifting → lifted → revealing → inspecting → advancing → stackReady / complete`.
- Order: David / Printed ink / Linen; Timothy / Foil / Paper; David / Holographic / Metal. Surface defaults remain strength `0.60`, roughness `0.23`, detail `0.14`, mint condition and seed `81251`. Pack inherits the current lighting.
- Wrapper: two `64 × 80` subdivided pouch surfaces joined at their side/bottom boundaries and one `64 × 10` top ribbon, sharing horizontal samples along the attached seam. Total 21,760 triangles. Dimensions: width `3.36`, bottom `-2.24`, tear seam `1.97`, top `2.28`; center depth `-0.09`, inflated half-depth `0.37`. Surface folds are shallow deterministic UV-based displacements; contact dent is bounded to `0.045` units. Side and bottom crimps remain separated surfaces, with no overlapping cap/label meshes or transparent fades.
- Foil material: deep teal printed canvas, warm gold seam and restrained typography; standard material roughness `0.43`, metalness `0.68`, double-sided. The existing scene lighting/environment lights the foil. This is a wrapper-specific recipe, not a card-material revision.
- Opening lasts `3200 ms` from sealed (remaining duration scales with retained progress); lift `620 ms`, reveal `820 ms`, advance `650 ms`. Elapsed-time smoothstep interpolation and quaternion rotation remain unchanged for card transitions.
- Opening's eased progress intervals: tear `0–0.38`; strip detachment/curl-away `0.38–0.52`; mouth spread `0.50–0.62`; card extraction `0.62–0.826`; empty pouch exit `0.83–0.87`; stack settling `0.87–1`. Each successive card starts/ends extraction `0.018` progress later, staying at its established depth and scale. Extraction rises `4.4` units, clearing the entire pouch before its lateral exit. The wrapper never drops through the floor or crosses the inspecting card.
- Mouth lips spread in depth to a `0.64` half-opening envelope; the front lip bows down `0.28` units and the rear up `0.08`, exposing the opening without added rim layers. The released ribbon curls up/back around the moving tear front, then moves right and away before extraction begins.
- Seam input: a projected mouse/touch hit area at least `44 px` high; a rightward drag across `75%` of projected pack width (at least `80 px`) traverses a full tear. Progress is monotonic and survives partial release, pointer cancellation/lost capture and mode switches. A completed pull releases into the remaining choreography; otherwise **Finish opening** or another seam drag resumes. **Tear open** is the button/keyboard equivalent. The progress indicator exposes the tear percentage.
- Reduced motion: `70 ms` per transition, with identical resting states and event order.
- Input ownership: the Pack controller alone writes Pack transforms. Manual input pauses scripted motion without snapping; Continue resumes the elapsed transition. The seam gesture can take over a still-tearing animation at its current progress. A second touch cancels seam ownership in favor of pinch; wheel zoom releases captured gestures. Rotation is allowed only after revealing; zoom is available throughout. Press/release contact deformation is damped, except under reduced motion where it is immediate.
- Skip finishes one transition or one next resting-state step. Restart clears progress and event guards. Mode changes pause Pack while retaining the separate Inspect/Lab scene and assets.
- Hidden fronts are disabled, all backs share the universal fixed material, and hidden edges use the same mint paper recipe. Real substrate edges become visible only after the reveal finishes.
- Lift ownership: the existing stack card is the animated object, with the same root and mesh UUIDs throughout. There is no separate active-card renderer or stack placeholder. All unrevealed fronts remain disabled throughout the lift.
- Stack depth spacing: `0.055` scene units between roots at `0.88` scale, leaving approximately `0.039036` between neighboring surfaces. The current card lifts away while reserve cards ease to a visible lower-right position, preserving their depth spacing and face-down orientation.
- Inspection clearance: the full card corner-sweep radius is derived from the shared scene dimensions (approximately `2.458`). Lift finishes at local `z = max(3, radius + 0.5)` before reveal or manual rotation. With current dimensions, even the conservative full-rotation envelope stays over `0.61` units ahead of the reserve stack and over `0.60` above the floor. The opened wrapper is hidden and sits outside this envelope.
- Reserve cards remain visible through reveal, inspection, and exit. They are offset by `(1.05, -0.4, 0)` from their normal stack poses while inspecting, then recenter during advancing. The active card exits laterally on the same safe inspection plane, never diving back through the reserve stack.
- Pack uses a separate responsive 34-degree camera, fitted to the wrapper and compact bottom controls; pinch/wheel zoom spans `0.62–1.45` of its fitted distance. Opening-only framing retreats up to `8` units and raises its center `1.6` units during extraction, returning fully before stackReady. A `2.15`-unit camera retreat eases with the lift and reverses on exit to preserve the established card framing at the deeper inspection plane. One camera-update helper combines retreat, responsive fit, vertical framing, and user zoom; paused motion preserves them all. Inspect/Lab camera defaults are unchanged. Aggressive user zoom may crop the scene, as in the existing inspection flow.

No pack progress persistence, random rewards, backend, sound, haptics, particles,
cloth, or general timeline/editor are included. Deformation is an authored, reversible
evaluation of progress, not physical tearing or arbitrary cloth manipulation. The
tear itself cannot be reversed by dragging left; only Restart reseals the pack.
Wrapper art and the new foil choreography remain review-only. Desktop browser and
emulated mobile checks are not physical-device performance or touch-feel sign-off.


## Optional Text-Mask Material Protection — September 12 Trial

- Asset convention: `[image-name]-text-mask.png`, optional beside artwork and finish mask.
- Catalog `textMask` URL appears only when present; optional bytes affect the revision.
- Same artwork dimensions, fully opaque grayscale. White = protected lettering; black = retained material.
- Texture uses `NoColorSpace` and the same anisotropy/registration convention as finish data.
- Runtime sampler `textMask` plus presence flag `hasTextMask`; default is `null`/`false`.
- One optional sample at unshifted face UVs. No request or protection math when absent.
- Metal parallax relief is multiplied by `1 - protection` before artwork/mask shifting.
- Surface height, generic normal perturbation, linen slope/ridge, and finish coverage are attenuated by `1 - protection`.
- Surface normals blend toward the geometric normal; surface shade blends toward `1`.
- Protected ink lighting: `artwork * (0.32 + plainDiffuse * lightIntensity * attenuation * lightColor)`.
- The protected ink blend suppresses substrate tint/glare and Metal cavity/recess treatment; black retains the existing recipe.
- Inspect/Lab fixture switches dispose old optional maps and clear protection on unmasked cards. Local artwork replacement clears prior fixture protection.
- Pack cards retain their own optional map through lighting sync; GPU preparation uploads shared maps once. Caller owns card texture disposal.
- No font, anti-aliasing, artwork, geometry, or postprocess change is included.

The [P052 Roman Calling the Disciples trial](../spikes/calling-disciples-text-mask-proof/README.md)
uses actual lettering alpha with 12px expansion and sigma-8 feathering at the
2000px master. P052 card pixels and canonical `Matthew 4:19 • NKJV` are retained.
Automated mask/asset checks pass; this treatment awaits moving-light review.