AGENTS.md@packages/deck3d/src/ir git:20260929.4aa0939A

Immutable. This exact content never changes and is served at /api/v1/blob/36c2908465525579.

# DOX — packages/deck3d/src/ir

| File | Purpose |
|------|---------|
| `AGENTS.md` | This file. |
| `schema.json` | Deck IR JSON Schema (draft-07), `description` on every field. Enforces `additionalProperties:false` everywhere (unknown-key rejection) and the single `overrides` grammar. Source of truth for `validate` and the generated field reference. Grew: `defaults.autoStyle`, palette enum ×10, derived `diagram.kind` ×12 + shared `diagramData` (`values ≥ 0`), `overrides.slides[].diagram.kind` restricted to BUILT kinds (no `flowchart`/`sequence`) + `data`, and an `effectRef` union that requires `sha256` for `local:` ids and forbids it otherwise. `defaults.floor` (`mirror` | `water`, deck-scope like `mirrorFloor`) selects the floor surface. `defaults.reflectBackdrop` (boolean, default true, deck-scope) puts backdrop-layer geometry back in the floor reflection. `defaults.floorMatte` (number 0-1, default 0, deck-scope) is floor roughness: 0 mirror, 1 fully scattered; `defaults.floorReflectivity` (number 0-1, default 1, deck-scope) is reflection STRENGTH, fading into the floor colour — `mirrorFloor:false` remains the hard off switch that also skips the reflector pass. NOT in `DECK_DEFAULTS` (like `floor`/`reflectBackdrop`) — seeding it would rewrite `defaults` in every committed `deck.json`. `defaults.titleEdge` (`none` | `contrast`, also per-slide) draws a contour on extruded glyph side walls. See change: deck3d-cinematic-worlds. Adds `defaults.layout`/`defaults.rail`/`defaults.spacing`, per-slide `layout`+`cardOffset` (also in `overrides.slides[<id>]`); `rail`/`spacing` deck-level only. See change: deck3d-cinematic-worlds. | `overrides.slides[id]` now $refs the deck look knobs (`bloom`/`rimLight`/`fog`/`floor`/`mirrorFloor`/`reflectBackdrop`/`floorMatte`/`floorReflectivity`/`softShadows`/`envReflections`/`depthRelief`/`extrudeDepth`/`colors`/`durationSec`) so the two scopes cannot drift; `rail`/`spacing` stay deck-only (they position every anchor). The runtime always supported per-slide values — `effective()` is `{...defaults, ...slide}` — only the schema rejected them, so the configurator could export an unrenderable deck. See change: deck3d-cinematic-worlds.
| `types.ts` | TypeScript mirror of `schema.json` (DeckIR, Defaults, Slide, Diagram, Overrides, and the render-only Merged* view). Adds `BuiltDiagramKind`, `DiagramData`, `EffectRef.sha256`, `Defaults.autoStyle`, `Defaults.reflectBackdrop`, `Defaults.floorMatte`, `Defaults.floorReflectivity`; `MergedDeck` carries render-only `overriddenKeys` + `derivedHash` for the configurator. See change: deck3d-cinematic-worlds. Adds `Layout`, `Rail`, `CardOffset`. See change: deck3d-cinematic-worlds. |
| `ids.ts` | Stable id derivation: `slugify`/`foldAscii`, `parseHeading` (`{#pin}`), `assignSlideIds` (`-<ordinal>` collisions), `edgeId` (`<from>-><to>#<k>`), `messageId` (`m<i>`). Ids come from author source, never render counters. |
| `hash.ts` | Canonical JSON (sorted keys) + sha256; `computeDerivedHash` over `defaults`+`slides` so `validate` can detect edits made outside `overrides`. |
| `defaults.ts` | `DECK_DEFAULTS` (mirrors the schema `default` keywords; `camera.distance` 9) + `resolveDefaults`, so a bare deck is fully specified and `derivedHash` is stable. |
| `merge.ts` | The override merge grammar: objects deep-merge, arrays replace, and `diagram.data` replaces as a whole object (`isAtomic`, applies at any depth so `overrides apply` inherits it). See change: deck3d-cinematic-worlds. `applyOverrides` returns a fresh merged view; `findOrphanOverrides`/`orphanOverridePath` keep vanished targets inert + warned. |
| `validate.ts` | Ajv schema validation (schema read via `pkgRoot()/src/ir/schema.json`) + derived-data referential integrity (errors) + orphan overrides and derivedHash mismatch (warnings). `formatPath` renders ajv pointers as the `overrides` grammar (`overrides.slides["arch"].camera.distance`); an all-digit segment under a non-map parent renders as an array index (`…data.values[1]`). `ValidateOptions.deckDir` enables `local:` referent resolution (file/hash/card/kind/size). See change: deck3d-cinematic-worlds. |
| `field-reference.ts` | Walks the schema (read via `pkgRoot()/src/ir/schema.json`) into flat `FieldRow`s and renders `reference/ir-fields.md`; used by `scripts/gen-ir-fields.ts` and its test. |