dreative 0.5.0 → 0.5.2

package/skill/dreative/schemas/plan.schema.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dreative.local/schemas/plan.schema.json",
+  "title": "Dreative Multi-Page Direct Design Plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "request", "createdAt", "tier", "depth", "skills", "skillPolicy", "designRead", "pages", "preservationManifest", "decisionLedger"],
+  "properties": {
+    "version": { "const": 2 },
+    "doctrineVersion": { "const": 2 },
+    "request": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "tier": { "enum": ["solid", "premium", "expressive", "award"] },
+    "depth": { "enum": ["restyle", "relayout", "restructure", "reimagine"] },
+    "skills": { "$ref": "#/$defs/skillList" },
+    "skillPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "global", "routingApproved", "userAssignments"],
+      "properties": {
+        "mode": { "const": "hybrid" },
+        "global": { "$ref": "#/$defs/skillList" },
+        "routingApproved": { "const": true },
+        "userAssignments": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["pageId", "skills"],
+            "properties": {
+              "pageId": { "type": "string", "minLength": 1 },
+              "skills": { "$ref": "#/$defs/treatmentList" }
+            }
+          }
+        }
+      }
+    },
+    "designRead": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["register", "concept", "signature"],
+      "properties": {
+        "register": { "type": "string", "minLength": 1 },
+        "concept": { "type": "string", "minLength": 1 },
+        "signature": { "type": "string", "minLength": 1 }
+      }
+    },
+    "implementationStartedAt": { "type": "string", "format": "date-time" },
+    "ruleExceptions": { "type": "array", "items": { "$ref": "#/$defs/ruleException" } },
+    "creativeStrategy": { "$ref": "#/$defs/creativeStrategy" },
+    "fontDecision": { "$ref": "#/$defs/fontDecision" },
+    "experimentalPlan": { "$ref": "#/$defs/experimentalPlan" },
+    "conceptExploration": { "$ref": "#/$defs/conceptExploration" },
+    "recipeAccess": { "type": "array", "items": { "$ref": "#/$defs/recipeAccess" } },
+    "pages": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/page" } },
+    "preservationManifest": { "type": "string", "minLength": 1 },
+    "decisionLedger": { "type": "string", "minLength": 1 }
+  },
+  "$defs": {
+    "skill": { "enum": ["ux", "mobile", "refined", "motion", "interaction", "media", "3d", "immersive", "cinematic", "experimental"] },
+    "skillList": {
+      "type": "array",
+      "uniqueItems": true,
+      "allOf": [{ "contains": { "const": "ux" } }, { "contains": { "const": "mobile" } }],
+      "items": { "$ref": "#/$defs/skill" }
+    },
+    "treatmentList": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/skill" }
+    },
+    "status": { "enum": ["planned", "shipped", "fallback", "cut"] },
+    "ruleException": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ruleId", "decision", "declaredAt", "reason", "alternative", "successCriteria", "evidenceIds"],
+      "properties": {
+        "ruleId": { "type": "string", "minLength": 1 },
+        "decision": { "const": "substituted" },
+        "declaredAt": { "type": "string", "format": "date-time" },
+        "reason": { "type": "string", "minLength": 20 },
+        "alternative": { "type": "string", "minLength": 30 },
+        "successCriteria": { "type": "array", "minItems": 2, "items": { "type": "string", "minLength": 12 } },
+        "evidenceIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "creativeStrategy": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "mechanisms", "drivers"],
+          "properties": {
+            "path": { "const": "diversity" },
+            "mechanisms": { "type": "array", "minItems": 4, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+            "drivers": { "type": "array", "minItems": 3, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "signatureMechanism", "states", "secondaryMechanisms", "drivers"],
+          "properties": {
+            "path": { "const": "development" },
+            "signatureMechanism": { "type": "string", "minLength": 1 },
+            "states": { "type": "array", "minItems": 3, "uniqueItems": true, "items": { "type": "string", "minLength": 12 } },
+            "secondaryMechanisms": { "type": "array", "minItems": 2, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+            "drivers": { "type": "array", "minItems": 2, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+          }
+        }
+      ]
+    },
+    "fontDecision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["selected", "candidates", "recentDisplayFonts"],
+      "properties": {
+        "selected": { "type": "string", "minLength": 1 },
+        "candidates": {
+          "type": "array",
+          "minItems": 3,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "reflex", "rationale"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "reflex": { "type": "boolean" },
+              "rationale": { "type": "string", "minLength": 12 }
+            }
+          }
+        },
+        "recentDisplayFonts": { "type": "array", "maxItems": 3, "items": { "type": "string" } },
+        "reasonKinds": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": ["existing-brand", "design-system-metrics", "product-register", "supplied-reference", "language-coverage", "variable-font-capability", "performance", "physical-editorial-historical-reference"]
+          }
+        },
+        "justification": { "type": "string", "minLength": 20 },
+        "repeatJustification": { "type": "string", "minLength": 20 }
+      }
+    },
+    "experimentalPlan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["majorSectionIds", "candidates"],
+      "properties": {
+        "majorSectionIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "sectionId", "idea", "selected"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "sectionId": { "type": "string", "minLength": 1 },
+              "idea": { "type": "string", "minLength": 20 },
+              "selected": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "conceptExploration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["recordedAt", "concepts"],
+      "properties": {
+        "recordedAt": { "type": "string", "format": "date-time" },
+        "concepts": {
+          "type": "array",
+          "minItems": 3,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "concept", "brandConnection"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "concept": { "type": "string", "minLength": 20 },
+              "brandConnection": { "type": "string", "minLength": 20 }
+            }
+          }
+        }
+      }
+    },
+    "recipeAccess": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file", "loadedAt", "purpose"],
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "loadedAt": { "type": "string", "format": "date-time" },
+        "purpose": { "enum": ["feasibility", "implementation", "performance", "fallback", "concept-repair"] }
+      }
+    },
+    "asset": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "path", "purpose", "status"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "minLength": 1 },
+        "purpose": { "type": "string", "minLength": 1 },
+        "status": { "$ref": "#/$defs/status" },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "layoutFamily", "skills", "interactions", "mobile", "fallback", "verification", "assets", "status"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "layoutFamily": { "type": "string", "minLength": 1 },
+        "skills": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/skill" } },
+        "interactions": { "type": "array", "items": { "type": "string" } },
+        "mobile": { "type": "string", "minLength": 1 },
+        "fallback": { "type": "string", "minLength": 1 },
+        "verification": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "assets": { "type": "array", "items": { "$ref": "#/$defs/asset" } },
+        "status": { "$ref": "#/$defs/status" },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "page": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "skills", "sections"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "skills": { "$ref": "#/$defs/skillList" },
+        "sections": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/section" } }
+      }
+    }
+  }
+}

package/skill/dreative/schemas/verify.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dreative.local/schemas/verify.schema.json",
+  "title": "Dreative Verification Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generatedAt", "evidence"],
+  "properties": {
+    "version": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "criterion", "status", "evidence", "proof"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "criterion": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["pass", "fail", "not-applicable"] },
+          "evidence": { "type": "string", "minLength": 1 },
+          "proof": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["timestamp"],
+            "properties": {
+              "timestamp": { "type": "string", "format": "date-time" },
+              "artifactPath": { "type": "string", "minLength": 1 },
+              "viewport": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["width", "height"],
+                "properties": {
+                  "width": { "type": "number", "exclusiveMinimum": 0 },
+                  "height": { "type": "number", "exclusiveMinimum": 0 },
+                  "dpr": { "type": "number", "exclusiveMinimum": 0 }
+                }
+              },
+              "command": { "type": "string", "minLength": 1 },
+              "exitCode": { "type": "integer" },
+              "consoleErrorCount": { "type": "integer", "minimum": 0 },
+              "testedUrl": { "type": "string", "minLength": 1 },
+              "averageFps": { "type": "number", "exclusiveMinimum": 0 },
+              "maxFrameTimeMs": { "type": "number", "minimum": 0 },
+              "playwrightTestId": { "type": "string", "minLength": 1 }
+            },
+            "anyOf": [
+              { "required": ["artifactPath"] },
+              { "required": ["command", "exitCode"] },
+              { "required": ["consoleErrorCount"] },
+              { "required": ["testedUrl"] },
+              { "required": ["averageFps"] },
+              { "required": ["maxFrameTimeMs"] },
+              { "required": ["playwrightTestId"] }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/skill/dreative/skills/3d.md

@@ -1,157 +1,94 @@
-# Dreative Specialist Skill — 3D, WebGL & Shaders
-
-Load this file when `plan.skills` includes `3d`, or the brief/prompt mentions 3D,
-WebGL, three.js, shaders, particles, globes, or point clouds. DESIGN.md still
-governs everything around the canvas (layout, color, type, motion budgets).
-Integrating 3D usually changes component structure (canvas placement, lazy
-boundaries, scroll wrappers) — when it does, follow DESIGN.md §11's
-transformation-depth ladder: offer the restructure, then do it for real.
-
-## 0. Does 3D earn its place?
-
-3D is the most expensive pixel on the web — in bytes, battery, and attention.
-It earns its place when the SUBJECT is spatial (a physical product, a device, a
-map/globe, an environment, data with real dimensionality) or when the brand brief
-explicitly buys a signature 3D moment. It does not earn its place as ambient
-decoration: a random floating torus/blob behind hero text is the 3D equivalent of
-the gradient blob — banned as a default reach. One 3D moment per page; make it the
-signature element (DESIGN.md §2) or don't ship it.
-
-Cheaper substitutes to consider first: CSS 3D transforms (`perspective` +
-`rotateX/Y` on real DOM — free, accessible, great for cards/mockups/tilt), a
-pre-rendered video/image sequence scrubbed on scroll, or a Lottie/Rive vector
-animation. If the object never needs live lighting or user-driven rotation,
-pre-render it — and if a video-generation tool exists in the environment
-(PLAN.md §1's probe), a generated loop or frame sequence (media.md §1) is
-usually the strongest pre-render source.
-
-## 1. Stack
-
-- **React app → React Three Fiber (`@react-three/fiber`) + `@react-three/drei`.**
-  Never hand-roll a three.js imperative setup inside React. Drei gives you 80%:
-  `Environment`, `ContactShadows`, `Float`, `ScrollControls`, `Html`, `Text`,
-  `useGLTF`, `MeshTransmissionMaterial`, `Center`, `Bounds`.
-- **Non-React → three.js** with a small render-loop module; or **OGL** when the
-  scene is one shader plane and three.js is overkill.
-- Post-processing via `@react-three/postprocessing` (Bloom, DoF, Noise) — 1-2
-  effects max; the stacked-postFX look reads as demo-scene, not product.
-- Physics only if interaction demands it (`@react-three/rapier`).
-
-Lazy-load the entire 3D bundle (`next/dynamic` / `React.lazy`) with an SSR-off
-canvas and a styled poster fallback. Three.js must never be in the critical path.
-
-## 2. Scene fundamentals (where amateur scenes fail)
-
-- **Lighting is the craft.** Default: `<Environment preset="studio"|"city">` for
-  image-based lighting + ONE key directional light for shadows. Ambient light
-  alone = flat plastic. Match light temperature to the page palette.
-- **Color management:** renderer defaults in modern three are correct
-  (`outputColorSpace: SRGBColorSpace`, `ACESFilmicToneMapping`) — don't disable
-  them; DO set `toneMappingExposure` deliberately. Convert hex from the page
-  palette with `new THREE.Color(hex)` — scene colors and page colors must read as
-  one system.
-- **Ground the object:** `<ContactShadows opacity={0.4} blur={2.5}>` or a real
-  shadow plane. Floating unanchored objects read as clipart.
-- Camera: 35-50° FOV for product shots (85°+ distorts); frame with
-  `<Bounds fit clip>` or `<Center>`; subtle idle via `<Float>` or damped
-  mouse-parallax (`useFrame` + `THREE.MathUtils.damp`), amplitude ≤ 3°.
-- Materials: `meshStandardMaterial`/`meshPhysicalMaterial` with `roughness`/
-  `metalness` chosen from the real object; `MeshTransmissionMaterial` for glass
-  (expensive — one object max). Untextured default-gray = unfinished.
-
-## 3. Models
-
-- glTF/GLB only, Draco or Meshopt compressed (`gltf-transform optimize in.glb
-  out.glb --compress draco`). Budget: hero model ≤ 2-3 MB, ≤ 100k triangles.
-- `useGLTF.preload(url)`; wrap in `<Suspense>` with a poster (not a spinner).
-- No model available? Build from primitives + good materials/lighting (a laptop
-  from rounded boxes with an `Html` screen reads better than a bad download), or
-  tell the user what asset is needed — never ship an unrelated placeholder model.
-
-## 4. Shaders (the highest-leverage 100 lines)
-
-A fullscreen/plane fragment shader is the cheapest way to a signature visual:
-animated gradient meshes, flowfields, displacement on hover, image transitions.
-
-- Structure: `shaderMaterial` (drei) with `uTime`, `uMouse`, `uResolution`,
-  palette colors as `uColorA/B/C` uniforms fed FROM the page palette.
-- Vocabulary: fbm/simplex noise for organic movement (inline a noise fn; don't
-  import a library for it), `smoothstep` for banding-free ramps, domain warping
-  (`noise(p + noise(p))`) for the expensive look, `mix()` between palette colors
-  only — never rainbow hue-rotation.
-- Displace vertices in the vertex shader for cloth/terrain/blob effects; compute
-  normals or fake lighting with the noise derivative.
-- Animate `uTime` at 0.05-0.2 speed; slow reads as premium, fast as screensaver.
-- Image effects: sample two textures + a noise mask for transitions; barrel/flow
-  distortion on scroll velocity for editorial galleries.
-
-## 4.5 Media in the scene (images & video as textures)
-
-The other half of shader craft: real page media rendered THROUGH WebGL so
-effects can touch it (the unseen.co gallery mechanic — full pattern in
-`skills/media.md` §3):
-
-- **DOM-synced media planes**: the page's `<img>`/`<video>` elements stay in
-  the DOM (a11y/layout/fallback, `opacity: 0` never `display:none`) while
-  textured planes copy their `getBoundingClientRect()` per rAF (lerped).
-  One scene owns ALL planes — never a canvas per image.
-- **Video textures**: `new THREE.VideoTexture(videoEl)` with the element
-  `muted playsinline` and playing; `texture.colorSpace = SRGBColorSpace`;
-  generated seamless loops (media.md §1) make the best texture sources —
-  a pre-rendered loop as a texture often beats a live sim for cost.
-- Effects on media planes: hover ripple/lens (damped `uMouse` + radial UV
-  displacement), velocity stretch + RGB split (clamped, damped decay),
-  noise-mask dissolves between textures (§4), subtle vertex curvature for
-  the floating-paper look.
-- Failure path is wired, not theoretical: WebGL missing/lost or
-  reduced-motion → un-hide the DOM media (`opacity: 1`). Verify it fires.
-
-## 5. Particles and points
-
-Points/instancing, never meshes-per-particle: `<Points>` + `BufferAttribute`
-positions animated in a shader (`uTime` in the vertex shader), or
-`<Instances>`/`InstancedMesh` for repeated geometry (≤ ~10k instances). Counts:
-2-5k points desktop, halve on mobile. Particle color from the page palette at 1-2
-hues; size attenuation on; additive blending only on dark surfaces.
-
-## 6. Scroll- and layout-integration
-
-- Canvas placement: either a bounded block IN the layout (preferred — it composes
-  with the grid) or a full-bleed fixed background with content scrolling over.
-  Full-page persistent canvases with DOM scrolled on top: use drei
-  `ScrollControls` + `<Scroll html>` so 3D and DOM share one scroll.
-- Scroll-linked 3D: map scroll progress (Motion `useScroll` / ScrollTrigger /
-  drei `useScroll`) to camera position along a path or object rotation — damped
-  (`damp3`, `dampE`), never raw-set per frame.
-- DOM/3D registration (labels pinned to model parts): drei `<Html transform
-  occlude>`; keep text as real DOM for accessibility, never texture-baked type.
-- The block's `data-dreative-id` goes on the wrapper div around the Canvas.
-
-## 7. Performance & fallbacks (ship-blockers)
-
-- `<Canvas dpr={[1, 2]}>` (cap device pixel ratio), `frameloop="demand"` +
-  `invalidate()` for static-until-interacted scenes; pause the loop when the
-  canvas leaves the viewport (IntersectionObserver) and on `document.hidden`.
-- One `useFrame` per concern; no allocations inside it (reuse vectors created
-  outside). Dispose on unmount (R3F handles it; imperative three must
-  `dispose()` geometries/materials/textures).
-- Mobile: halve particle counts, drop post-processing, consider a poster image
-  below 768px — a janky 3D hero is worse than none.
-- `prefers-reduced-motion`: stop idle rotation/particle drift; render one static
-  well-lit frame (`frameloop="demand"` makes this free).
-- WebGL unavailable/context-lost → the poster fallback, never a blank block.
-- Keyboard/screen-reader: canvas gets `role="img"` + `aria-label`; any 3D-driven
-  interaction has a DOM equivalent.
-
-## 8. Recipes
-
-- **Product hero**: GLB + `Environment` + key light + `ContactShadows`, `Float`
-  idle, damped mouse parallax, scroll scrubs a 90° orbit. Poster until loaded.
-- **Gradient-mesh hero background**: one plane, fbm + domain-warp fragment shader
-  mixing 3 palette colors, `uTime` 0.08, `uMouse` warps locally. ~120 lines, no
-  model, no lighting — the best effort/impact ratio in this file.
-- **Point-cloud globe**: sphere-distributed points, shader-animated shimmer,
-  arcs as `TubeGeometry`/fat lines between coords, slow idle rotation, drag to
-  spin (damped).
-- **Scroll story**: `ScrollControls pages={4}` + camera on a `CatmullRomCurve3`
-  path, DOM copy in `<Scroll html>`, one damped lookAt target per section.
+# Dreative Specialist Skill — 3D, WebGL & Shaders
+
+## Contract
+
+Follow `../references/SKILL_CONTRACT.md`. Dependencies: `ux`, `mobile`; add
+`motion` when scroll/time drives the scene. Deliver a named spatial purpose,
+asset/material source, staged berth, budgets, semantic/poster fallback, and
+runtime evidence.
+
+Load for real spatial subjects, WebGL, three.js/R3F, shaders, particles, globes,
+or a plan-defined dimensional signature. 3D is expensive in bytes, battery, and
+attention; it must serve the subject or concept.
+
+## 0. Explore before recipes
+
+Record three original brand-native spatial concepts before opening
+`../recipes/3d-recipes.md`. Begin with subject, spatial purpose, recurrence,
+interaction, and berth—not a primitive or shader technique.
+
+## 1. Hard gates
+
+- **No coded organic subjects (`3d.noCodedOrganic`).** Food, plants, fabric,
+  skin, liquid, wood, or other richly textured real objects never ship as crude
+  primitives. Use a real GLB, photoreal cutout, sourced photo, or cut the object.
+- WebGL/context loss/loading/low power/mobile/reduced motion always has a real
+  poster or DOM fallback (`effects.runtimeFallback`, `motion.reducedMotion`).
+- Canvas and traveling objects never cover content or controls; pointer events
+  and keyboard paths remain intact (`spatial.noOcclusion`, `ux.functional`).
+- Text remains semantic DOM, not texture-baked. Content is visible without 3D.
+- Models/textures/materials named as shipped assets exist and are tracked.
+- Verification proves a live context/draw, interaction, performance, and
+  fallback behavior with structured evidence.
+
+## 2. Award spatial signature
+
+`award.spatialSignature` requires one unmistakable dimensional or spatial
+signature with depth, recurrence, input response, and visual dominance on
+desktop and mobile.
+
+The proven default is:
+
+1. a recognizable real GLB; or
+2. a photoreal transparent cutout billboard staged with parallax, restrained
+   rotation, contact shadow, rim light, and—when useful—multiple angles.
+
+This default exists because dogfood coded/shader hero objects repeatedly read as
+generic demos. Valid registered alternatives include spatial typography,
+layered photographic depth, a persistent interactive scene instrument, or a
+data-driven spatial structure that meets declared observable criteria.
+
+A generic orb, blob, sphere, torus, or untextured coded form remains invalid as
+a signature. `3d.signatureRecognizable` permits a brand-native abstract
+instrument only when it has a nameable function, material identity, recurrence,
+and input response; ambient decoration does not qualify.
+
+## 3. Staging and material
+
+Every object gets a planned berth: section/lane, space reserved by type/layout,
+crop, light direction, shadow/ground, travel states, and hidden states when no
+safe berth exists. It never floats over other imagery unless genuinely
+composited with matched light and cast/contact shadow.
+
+Realism comes from material and light, not geometry count:
+
+- environment/IBL plus one coherent key direction;
+- deliberate exposure/color management;
+- contact/cast shadow or defensible weightlessness;
+- texture/normal/roughness or a custom procedural shader for visible coded
+  geometry;
+- camera FOV/framing appropriate to the subject;
+- damped input and subtle idle behavior.
+
+## 4. Architecture
+
+React uses R3F + drei unless the existing stack strongly dictates otherwise;
+one simple shader plane may use OGL/three.js. Lazy-load the whole spatial bundle
+outside the critical path. One scene owns related planes/objects. Reuse vectors
+and buffers; avoid allocations in render loops.
+
+Models use optimized GLB/glTF with measured bytes/triangles and a poster during
+load. Particles use points/instancing, not mesh-per-particle. DOM-synced media
+planes keep semantic source media for layout and fallback.
+
+## 5. Performance and verification
+
+- Cap DPR and complexity; pause off-screen/hidden work.
+- Mobile reduces particles/post effects or uses a purpose-designed poster.
+- Reduced motion renders a stable, intentional frame.
+- Dispose imperative resources and test route transitions/context restoration.
+- Record transferred weight, frame-time/FPS sample, context/draw evidence,
+  object/material identity, desktop/mobile screenshots, input response, and
+  poster/context-loss fallback.
+
+Recipe reference: `../recipes/3d-recipes.md`, after concept exploration only.