dreative 0.5.1 → 0.5.2

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

@@ -1,267 +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.
-
-**At award-site ambition, one 3D prop is REQUIRED, not optional:** the page
-ships at least ONE dimensional prop that looks real — a rung-1 GLB or a
-rung-2 transparent-background cutout billboard (§3) of a recognizable
-subject, photoreal because it IS a photo/render, carrying the full
-dimensional kit (parallax against layers, damped ±5-10° rotation, contact
-shadow, rim light, multi-angle pseudo-orbit where it earns it) and sitting
-in a §1.5 berth. An award plan with zero 3D props is incomplete; a page
-whose only "3D" is a background shader plane does not satisfy this — the
-prop must be an OBJECT. (Abstract coded forms remain supporting-only and
-never count.)
-
-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.
-
-## 1.5 Staging: a prop gets a designed berth, never a squat
-
-Where a 3D element SITS is as much of the craft as what it is. Every 3D
-prop/canvas object gets a reserved compositional berth negotiated with the
-layout at plan time — an empty grid lane, a color-field stage, a gutter the
-type deliberately avoids — exactly like DESIGN.md §15's travel map. Hard
-rules:
-
-- **Never parked on top of other imagery.** A 3D object overlapping a
-  photograph or media plane (the floating-orb-over-the-hero-photo failure)
-  is banned UNLESS it is composited INTO that scene for real: light
-  direction, color temperature, and a contact/cast shadow all matched so it
-  reads as part of the photo, not a sticker on it. "Semi-transparent so you
-  can see the photo through it" is the sticker, not the integration.
-- **Never covering text or controls** — DESIGN.md §15's occlusion rules
-  apply at every scroll position.
-- The berth is named in the plan blueprint (which section, which lane,
-  what the type does to make room). A prop with no reserved berth doesn't
-  ship — the layout must be designed around the object, not the object
-  dropped onto a finished layout.
-- The object is anchored to its berth by scene means: grounded by shadow,
-  lit by the page's one light direction, cropped by the frame on purpose if
-  oversized. An object that just floats centered in leftover space reads as
-  clipart (see §2 grounding).
-
-## 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? Walk the realism ladder — in this order:**
-
-1. **Real GLB** the repo/user already has, or one the user can supply.
-2. **Image-billboard prop (the DEFAULT for any real-world subject).** Get
-   the object as a transparent-background cutout — generate it if an image
-   tool exists (media.md §1.5 pipeline — verify the alpha is real); with NO
-   image-gen tool, source a real photo instead (a verified stock/CDN photo of
-   the subject, matted to transparency with rembg/sharp/ImageMagick if
-   available, or a photo whose own background already matches the scene so no
-   matte is needed). Put it on a plane in the scene
-   (`transparent`, `alphaTest ~0.5`, `toneMapped: false` if pre-graded), and
-   sell the depth with scene means: parallax against other layers, damped
-   mouse/scroll rotation of ±5-10° (a flat card barely rotating reads as
-   dimensional), scroll-linked scale/drift, a soft contact shadow, and a rim
-   of scene light via a subtle additive duplicate or shader fresnel. Generate
-   2-3 angles of the same subject and crossfade/swap by scroll chapter for a
-   pseudo-orbit. This looks photoreal because it IS a photo — it beats coded
-   geometry for any organic or textured subject, every time.
-3. **Coded geometry — abstract SUPPORTING forms ONLY.** Primitives/extrusions
-   are allowed for geometry that is genuinely abstract or hard-surface-simple
-   (shader planes, ribbons, crystals, grids, a device from rounded boxes with
-   an `Html` screen) — but only in a SUPPORTING role: background surface,
-   particle field, atmosphere. **An abstract coded form may never be the
-   promoted signature object.** A floating sphere/orb/blob/torus — however
-   shader-textured, however poetic its name ("eclipse", "core", "monolith") —
-   reads to a visitor as "a stupid orb"; the signature 3D element must be a
-   RECOGNIZABLE subject a stranger names correctly: a rung-1 GLB, a rung-2
-   generated/sourced cutout billboard, or a textured mesh of a nameable thing.
-   If image-gen exists, the signature defaults to rung 2 — generate the subject
-   as a transparent cutout and sell the depth with scene means. Compositing a
-   translucent shader sphere ON TOP of a photograph is the canonical form of
-   this failure and is a ship-blocker, not a signature.
-   **Modeling an organic or richly-textured real object
-   (food, beans, plants, fabric, skin, liquid, wood…) from primitives is
-   BANNED as a visible element** — an untextured lathe/sphere "coffee bean"
-   reads as a red blob, not a bean; that failure is worse than no 3D. If a
-   realistic subject must be 3D and no GLB exists, use rung 2.
-4. **Rung 2 unreachable does NOT unlock rung 3.** The organic-subject ban is
-   unconditional — it does not relax because the environment has no image-gen
-   tool or the cutout failed. If neither a GLB nor any photo source (rung 2's
-   no-tool path) exists, the organic 3D element is CUT: replace it with an
-   abstract signature (shader plane, particles, ribbons — rung-3-legal forms)
-   or with the sourced photography itself as a scroll-reactive media plane
-   (media.md §3), and tell the user what asset would unlock the real thing.
-   (The rung-3 supporting-only restriction still applies to that replacement:
-   it demotes the moment to atmosphere; it does not mint a new hero orb.)
-   "We had no tools, so I coded the bean" is the exact failure this rung
-   exists to stop.
-
-Any coded mesh that DOES ship must carry a real material identity per
-experimental.md §1 — and texture maps can be GENERATED: prompt the image tool
-for a tileable albedo/detail texture ("seamless tileable dark roast coffee-bean
-surface texture, matte, high detail"), load it as `map` + drive `bumpMap`/
-`roughnessMap` from it. With no image tool, source a tileable texture (a real
-photo crop, a CC0 texture CDN) or build material identity in a shader
-(procedural noise-driven roughness/normal, fresnel rim, environment
-reflection). A flat-color `meshStandardMaterial` on a visible custom mesh is a
-ship-blocker, not a style — and "no image tool" is not an exemption; if no
-texture path exists, the mesh doesn't ship.
-
-**The subject test is what the element REPRESENTS, not what the code names
-it.** If the plan, copy, aria-label, or your own verify prose describes the
-mesh as a real thing ("roast core… coffee bean", "the bottle", "a leaf"), it
-IS an organic/real subject and the ban applies — renaming a sphere-bean to an
-"abstract signature" while shaping and coloring it as a bean is the exact
-rationalization this section exists to stop. And texture is MECHANICAL, not
-rhetorical: a shipped custom mesh passes only if its material provably carries
-a `map`/`normalMap`/`roughnessMap` texture or a custom shader — point to the
-line in verify.md. `meshPhysicalMaterial` with a flat `color` plus clearcoat/
-roughness numbers is untextured, whatever the verify prose calls it.
-
-## 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.
-  **Variant trick (ciaoenergy.com):** ONE model, N variants — swap only the
-  label/albedo texture (`TextureLoader`, one AVIF per flavor/colorway) on the
-  same geometry as the user browses variants, and pair each with a
-  pre-rendered background video loop. Photoreal product-line 3D for the cost
-  of one GLB. The label texture can be GENERATED (image-gen at the label's
-  unwrapped aspect) when no real artwork exists.
-- **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.