freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.2

package/dist/assets/design/skills/hyperframes-animation/references/motion-blur.md

@@ -0,0 +1,133 @@
+# Motion blur — shutter smear on any animated element
+
+## Read this part before you blur anything
+
+Blur is not polish. It is the smear a real shutter leaves while the subject
+crosses the frame, so it only reads as correct when the subject crosses enough
+of the frame to have smeared. Applied to motion that was never fast enough, it
+reads as a soft, cheap render: the eye sees mush where it expected an edge.
+
+Do not blur:
+
+| Case                                             | Why                                                                                                    | Do instead                          |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------- |
+| Travel under about one element-width per frame   | The copies pile up inside the element's own silhouette, so the result is a softer element, not a smear | Leave it sharp                      |
+| A fade, a color change, a blur-in, a filter beat | Nothing reaches `transform`, so there is no trajectory to integrate and no smear to draw               | Leave it sharp                      |
+| Text meant to be read at that moment             | A smeared word is an unreadable word, which is usually the opposite of the brief                       | Blur the approach, land sharp, hold |
+| A slow drift, a parallax layer, a breathing loop | Below the half-pixel deadband it renders sharp anyway; above it, it looks like a mistake               | Leave it sharp                      |
+| The whole scene, or a container of many elements | Cost is the copies of an entire subtree, and a container that never moves smears nothing inside it     | Point it at the element that moves  |
+
+Blur the beats that snap: a slam, a whip, a hard cut in position, a spin, a
+scale punch. One to three of them in a composition, not every tween.
+
+## Two routes, and they are not interchangeable
+
+| Route                                   | What it is                                                                                                       | Use when                                                                                                             |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| The `motion-blur` registry component    | A DOM shutter synthesised in the page: N+1 additively blended copies of the element along its sampled trajectory | You want the smear visible in the preview, on selected elements, authored per element                                |
+| The engine's `motionBlur` render option | The renderer integrates real sub-frame samples of the whole frame                                                | You want every moving thing smeared, including canvas, video and transformed ancestors, and only in the final render |
+
+The component smears what a `transform` can express, on the elements you mark.
+The engine smears the frame. The component is the one an agent authors; the
+engine option is a render-time decision and shows nothing in a preview.
+
+## The contract: one attribute
+
+Paste the component's snippet into the composition, then mark the element:
+
+```html
+<div id="root" data-composition-id="hero" data-duration="4" data-fps="30">
+  <div id="slam" data-hf-motion-blur></div>
+  <div id="title" data-hf-motion-blur='{"shutterAngle": 360}'></div>
+</div>
+```
+
+Nothing to call and no ordering to get right. A marked element is attached as
+soon as its composition's timeline is registered, and the registry is also
+polled for about eight seconds after load, so a composition that mounts
+asynchronously is picked up too. An element takes the timeline registered under
+the `data-composition-id` of its nearest ancestor carrying that attribute, so a
+sub-composition's targets follow that sub-composition.
+
+Empty attribute means defaults. Any other value must parse as a JSON object, so
+it needs double quotes on the keys. A value that parses to something else,
+`null` or a bare number, warns and is skipped rather than quietly taken as
+defaults.
+
+`attachMotionBlur(target, timeline, options)` is for an element created later
+than that window. It has an ordering contract, after every tween so the
+timeline's final duration is known, and getting it wrong is silent. For markup
+that is already in the document, use the attribute.
+
+## Options
+
+| Option            | Default                                                      | Meaning                                                                                                                                                |
+| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `shutterAngle`    | 720                                                          | Degrees of the frame interval the shutter is open. 720 is two frames, measured off a real After Effects export. 360 is one frame. 0 disables the smear |
+| `shutterPhase`    | -360                                                         | Degrees the window start sits from the frame time. -360 centres the window on the frame                                                                |
+| `samplesPerFrame` | 16                                                           | Sub-intervals of the window, so this many plus one copies, each at 1 over this many opacity. Max 64                                                    |
+| `fps`             | the `data-fps` of the target's own composition root, else 30 | Composition frame rate. Pass it explicitly when rendering with an fps override                                                                         |
+
+A key that is none of these four, and a value that is not a finite number, are
+both refused by name rather than read as defaults. `{"shutterAngle": "720deg"}`
+is a refusal, not a 720 degree shutter.
+
+There is no axis, no strength and no radius. The smear is the trajectory,
+integrated; its extent is speed times shutter time and is not a free parameter.
+A template that passes `axis`, `blurMax` or `blurScale` carries an older fork of
+this snippet and its options do nothing in the current one.
+
+## The failure modes are all silent
+
+Every one of these renders a plausible-looking sharp element and reports
+nothing except where noted:
+
+| Symptom                                                                  | Cause                                                                                                               | Fix                                                                                  |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Console warns that no composition registered a timeline for an element   | The element is outside every `data-composition-id`, or that composition never registers a timeline                  | Put it inside the composition's root, or register the timeline                       |
+| Console warns the attribute is not JSON                                  | Single quotes, unquoted keys, a trailing comma                                                                      | Double-quoted JSON, or an empty attribute for defaults                               |
+| Console warns the attribute is not a JSON object                         | `null`, a bare number, a quoted string, an array                                                                    | An object, or an empty attribute for defaults                                        |
+| Console warns the attribute names no such option                         | A misspelled key, for example `samplesperframe`                                                                     | Use one of the four names above, case-sensitive                                      |
+| Console warns the attribute needs a number for an option                 | A quoted or unit-suffixed value, for example `"720deg"`                                                             | A bare JSON number                                                                   |
+| Console warns it cannot blur a target inside another target              | Both an element and one of its ancestors carry the attribute                                                        | Mark one of them, the one that moves                                                 |
+| Console warns one call cannot blur compositions at different frame rates | One `attachMotionBlur` call named elements in two compositions whose `data-fps` differ                              | One call per composition                                                             |
+| Console warns a second timeline registered for an element                | The same `data-composition-id` key was registered twice with different timelines; the copies still follow the first | Register once per composition                                                        |
+| No smear, no warning                                                     | The beat animates `left`, `top`, `width` or `height`; the snippet reads the resolved `transform`                    | Animate `x`, `y`, `scale`, `rotation`                                                |
+| No smear on a container's children                                       | The marked element does not move; its children do                                                                   | Mark the elements that move                                                          |
+| A smear that lags the element                                            | A transformed ancestor is doing the moving                                                                          | Move the element itself, or use the engine route                                     |
+| Blur only on the first frame, or never in a preview                      | The host never seeks the timeline                                                                                   | HyperFrames seeks every frame; a paused timeline nobody seeks shows nothing          |
+| A smear left behind in the old parent                                    | The target was reparented after attaching; the group stays where it was inserted and is never moved                 | Do not reparent a blurred element. Animate `x`/`y` instead, or attach after the move |
+| A selector stops matching after attaching                                | A copy keeps the element's classes, because a class rule is the only thing that can style a copy's pseudo-elements  | Address the element by id or by reference, never by a class a copy also carries      |
+
+## Cost
+
+Each target costs N+1 copies of its whole subtree. Those are restyled on attach
+and on resize, and re-transformed every frame, and the timeline is seeked N+1
+times per frame to sample the trajectory. At the default 16 that is 17 copies
+and 17 seeks per target per frame. Three marked elements is fine. Thirty is a
+different render.
+
+Drop `samplesPerFrame` before you drop the effect: 8 halves the cost and the
+staircase is still smooth on a fast beat.
+
+## The numbers, so you can argue with them
+
+The defaults are measured against a 1920x1080 30 fps After Effects export of
+translating text, not chosen. In that export the outermost trailing copy sits
+exactly at the previous frame's position and the outermost leading copy exactly
+at the next frame's, with 8 evenly spaced copies between on each side: a window
+of two frames, phase minus one frame, 16 sub-intervals. The staircase across a
+stroke steps by 0.063 plus or minus 0.002 of the sharp text intensity, a flat
+1/16 per copy with no taper toward the window edges. Triangle weighting scores
+1.6 dB worse against the same export.
+
+Per-beat PSNR against that reference, sharp render versus this component:
+translate +3.38 dB, scale +0.62, rotate X +0.43, rotate Y +0.84, rotate Z
++1.15. A beat that only scales or only rotates smears, which the earlier
+SVG-filter stage could not do.
+
+## See also
+
+`../../registry/components/motion-blur/motion-blur.html` is the snippet and its
+full header. `shutter-slam` is the same model as an installable component: the
+After Effects reference case, six beats, elastic to the container.

package/dist/assets/design/skills/hyperframes-animation/rules/3d-camera-flight.md

@@ -0,0 +1,180 @@
+---
+name: 3d-camera-flight
+description: Perspective camera FLIGHT through a 3D-laid-out world — one static perspective stage + preserve-3d world whose pose (translate3d + rotateX/rotateY) is tweened leg-by-leg from a single camera state object. Dive into an angled grid, tilt-to-flatten pull-back, continuous flight past standing cards, decelerate-into-focus. Hard power4.out landings, power2.inOut repositioning; DoF via depth-of-field-blur on non-focal planes.
+metadata:
+  tags: camera, 3d, flight, perspective, preserve-3d, rotateX, rotateY, translateZ, dive, tilt, world, cinematic
+---
+
+# 3D Camera Flight
+
+Every other camera rule here is a **2D camera**: [viewport-change.md](viewport-change.md), [multi-phase-camera.md](multi-phase-camera.md), and [coordinate-target-zoom.md](coordinate-target-zoom.md) simulate the camera with `scale` + `translate` on a flat wrapper — the lens never tilts, and there is no depth axis to travel along. [3d-page-scroll.md](3d-page-scroll.md) is a **static tilt**: one angle held all scene while content scrolls inside. This rule is the missing camera that _flies_ — dives into an angled grid, pulls back while the world rotates flat, streaks past standing cards, decelerates out of a blur into focus: a **perspective camera traveling with `rotateX` / `rotateY` / `translateZ` through a 3D-laid-out world**, under the same single-camera discipline as `viewport-change`: **one perspective wrapper, one camera state object, one transform writer**, every leg a sequenced tween on that state.
+
+## How It Works
+
+Five layers, strictly separated:
+
+1. **The lens** — `perspective: PERSPECTIVE_PX` on a static `.stage` wrapper. Set once, never tweened, never moved. Changing perspective mid-shot reads as the lens itself warping, not the camera moving.
+2. **The world** — a `.world` div with `transform-style: preserve-3d`, laid out at final 1× size: the ground surface (grid, form card, canvas) as flat DOM, optional **props** (a giant date number, a floating label) at static `translateZ(PROP_Z)` offsets so travel produces parallax, and **standing cards** counter-tilted to face the camera at their landing pose.
+3. **The camera state** — a single object `cam = { x, y, z, rx, ry }` (the world's pose), written to `world.style.transform` by ONE function, `applyCamera()`, in a **fixed order**: `translate3d(x, y, z) rotateX(rx) rotateY(ry)`. With translate composed _outside_ the rotations, `x`/`y`/`z` always move the world along **screen axes** no matter how it is currently tilted — pan is always sideways, `z` is always toward/away from the lens. Put the rotations first and every leg's numbers change meaning as the tilt changes.
+4. **The legs** — sequential tweens on `cam`, each one camera move: dive in (`power4.out` — violent arrival, sharp settle), tilt-to-flatten pull-back (`power2.inOut` — a repositioning, no slam), lateral flight, final dive. Camera intent inverts onto the world pose exactly as in `viewport-change`: camera flies **in** → world `z` **increases** (comes toward the lens); camera pans **right** → world `x` **negative**; camera tilts **down** over the surface → world `rx` **positive** (far edge tips away).
+5. **Depth cues** — DoF via [depth-of-field-blur.md](depth-of-field-blur.md) `--dof` tweens on the **non-focal planes** (cards, props — leaf elements, never the world itself), and velocity blur on travel legs via [motion-blur-streak.md](motion-blur-streak.md)'s Camera-Travel Carve-Out — applied to the **stage**, never the world (a `filter` on a `preserve-3d` element flattens it).
+
+Landing poses are **authored, not derived**: set `cam` to candidate values at design time, call `applyCamera()`, screenshot, adjust, bake the numbers as constants. There is no counter-translate formula to get wrong in 3D — the pose IS the design decision. Never measure per-frame (`getBoundingClientRect` in `onUpdate` desyncs under parallel frame sampling), and don't hand-derive 3D projections — your eye at design time beats the math.
+
+## Recipe
+
+```html
+<!-- The lens: static perspective, nothing else. -->
+<div class="stage">
+  <!-- The world: preserve-3d, laid out at final 1× size; the camera flies by
+       tweening THIS element's pose. Travel legs push content past the frame
+       edges by design — hence data-layout-allow-overflow. -->
+  <div class="world" id="world" data-layout-allow-overflow>
+    <div class="surface">
+      <div class="grid">{gridCells}</div>
+      <div class="card layer" id="card-a" data-depth="0">{cardA}</div>
+      <div class="card layer" id="card-b" data-depth="0">{cardB}</div>
+    </div>
+    <!-- Foreground props float at PROP_Z for parallax; they blur and fly past,
+         never carry a read. -->
+    <div class="prop layer" data-depth="2" style="--px: PROP_X; --py: PROP_Y">{propGlyph}</div>
+  </div>
+</div>
+```
+
+```css
+.scene {
+  overflow: hidden; /* travel legs push world content past the frame on purpose */
+  background: {sceneBg}; /* the void the flight exposes at frame edges — must be a
+     designed surface (deep brand color / soft gradient), never default white */
+}
+.stage {
+  position: absolute;
+  inset: 0;
+  perspective: PERSPECTIVE_PX; /* THE LENS — static, never tweened */
+  /* travel blur (motion-blur-streak carve-out) attaches HERE, never on .world */
+}
+.world {
+  position: absolute;
+  inset: 0;
+  transform-style: preserve-3d;
+  transform-origin: 50% 50%;
+  will-change: transform;
+  /* keep CLEAN: no filter, opacity < 1, overflow, clip-path, or mask — each
+     flattens preserve-3d. Background on .scene, blur on .stage or leaf cards. */
+}
+.surface {
+  position: absolute;
+  inset: WORLD_INSET; /* world runs larger than the frame so travel has runway */
+  transform-style: preserve-3d;
+}
+.prop {
+  position: absolute;
+  left: var(--px);
+  top: var(--py);
+  /* static world-space pose; counter-tilt faces the camera at the dive pose */
+  transform: translateZ(PROP_Z) rotateX(PROP_COUNTER_TILT);
+}
+.layer {
+  --dof: 0px; /* DoF channel per depth-of-field-blur — leaf elements only */
+  filter: blur(var(--dof));
+  will-change: filter;
+}
+```
+
+```js
+const world = document.getElementById("world");
+
+// Camera state — the ONLY source of truth for the world's pose. Every leg
+// tweens this object; nothing else touches world.style.transform.
+const cam = { x: 0, y: 0, z: WIDE_Z, rx: 0, ry: 0 };
+
+function applyCamera() {
+  // Fixed order: translate OUTSIDE the rotations → x/y/z stay screen-aligned
+  // at any tilt. Changing this order changes what every baked pose means.
+  world.style.transform = `translate3d(${cam.x}px, ${cam.y}px, ${cam.z}px) rotateX(${cam.rx}deg) rotateY(${cam.ry}deg)`;
+}
+applyCamera(); // seed frame 0 so a seek to t=0 renders the opening pose
+
+// ── LEG 1 — DIVE IN: wide establishing pose → angled close-up on card A.
+// fromTo states the opening pose explicitly; power4.out = violent arrival,
+// razor-sharp settle. Travel blur: motion-blur-streak carve-out on .stage.
+const DIVE_POSE = { x: DIVE_X, y: DIVE_Y, z: DIVE_Z, rx: DIVE_RX, ry: DIVE_RY };
+tl.fromTo(
+  cam,
+  { x: 0, y: 0, z: WIDE_Z, rx: 0, ry: 0 },
+  { ...DIVE_POSE, duration: DIVE_DUR, ease: "power4.out", onUpdate: applyCamera },
+  DIVE_AT,
+);
+// Decelerate-INTO-FOCUS: non-focal planes' --dof ramps to BLUR_PER_DEPTH × data-depth
+// on the SAME window/ease (depth-of-field-blur focal pull); card A stays at --dof: 0.
+
+// ── LEG 2 — TILT-TO-FLATTEN PULL-BACK: every channel returns to neutral on ONE
+// power2.inOut tween — a reposition, not a slam. DoF releases on the same window
+// so the flat overview arrives fully crisp.
+const FLAT_POSE = { x: 0, y: 0, z: 0, rx: 0, ry: 0 };
+tl.to(
+  cam,
+  { ...FLAT_POSE, duration: FLATTEN_DUR, ease: "power2.inOut", onUpdate: applyCamera },
+  FLATTEN_AT,
+);
+tl.to(".layer", { "--dof": "0px", duration: FLATTEN_DUR, ease: "power2.inOut" }, FLATTEN_AT);
+
+// ── LEG 3 — LATERAL FLIGHT: screen-aligned pan (translate is outside the
+// rotations, so x is a pure sideways move even mid-tilt).
+tl.to(cam, { x: PAN_X, duration: PAN_DUR, ease: "power2.inOut", onUpdate: applyCamera }, PAN_AT);
+
+// ── LEG 4 — FINAL DIVE onto card B: same grammar as leg 1; card A racks OUT of
+// focus as card B racks in (depth-of-field-blur rack, shared window).
+const LAND_POSE = { x: LAND_X, y: LAND_Y, z: LAND_Z, rx: LAND_RX, ry: LAND_RY };
+tl.to(
+  cam,
+  { ...LAND_POSE, duration: LAND_DUR, ease: "power4.out", onUpdate: applyCamera },
+  LAND_AT,
+);
+tl.to("#card-a", { "--dof": `${MAX_BLUR}px`, duration: LAND_DUR, ease: "power4.out" }, LAND_AT);
+tl.to("#card-b", { "--dof": "0px", duration: LAND_DUR, ease: "power4.out" }, LAND_AT);
+// Landing dwell: ≥1 s of stillness on card B — unless ending held mid-dive.
+```
+
+## Variations
+
+- **Continuous flight past standing cards** — one long leg instead of dive-land-dive: sustained `z` + `x` travel (2–4 s, `power2.inOut` / `power1.inOut` near-constant cruise) through a corridor of cards and props at staggered `PROP_Z`. Parallax does the work — near props streak past while far ones crawl. Keep ONE plane sharp at a time via staggered `--dof` tweens. Props crossing the camera plane (`cam.z + PROP_Z` approaching `PERSPECTIVE_PX`) blow up to fill the frame and vanish — that IS the fly-past; never let a focal card cross it.
+- **End held mid-dive** — give the final leg a window that overruns the composition (`LAND_AT + LAND_DUR > data-duration`); the last frame holds mid-tween — still traveling, blur not fully resolved. Seek-safe by construction (a seek to the last frame lands at a deterministic pose); don't fake it with a shorter leg plus a manual offset. Use when the brief wants momentum at the cut, not rest.
+- **Whip sweep** — the heavily motion-blurred lateral whip that resolves into the next region: leg 3 driven by [nudge-curve.md](nudge-curve.md)'s three-phase chain (burst-dominant) on `cam.x`, with [motion-blur-streak.md](motion-blur-streak.md)'s Camera-Travel Carve-Out on the same window — blur ramps through the ramp-in, rides the burst at peak, resolves to 0 through the `power4.out` tail. Full recipe in that carve-out.
+- **Hold drift (the hold never dies)** — between legs, fold `multi-phase-camera`-style micro-drift **through the same writer**: a driver tween writes tiny `dx`/`dy`/`drx` into a `drift` object and `applyCamera()` composes `cam.x + drift.dx`, `cam.rx + drift.drx`, etc. Never let drift write `world.style.transform` itself — two writers on one transform is the classic camera bug. Amplitudes per `multi-phase-camera` (2–8 px), rotation drift ≤ 0.5°.
+
+## Values
+
+| token                     | range                                                            | notes                                                                                                                                                                                     |
+| ------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PERSPECTIVE_PX            | 700–1400 px (moving cam best 800–1200)                           | smaller = wilder foreshortening, more violent dives; larger = near-orthographic, the flight flattens                                                                                      |
+| WORLD_INSET               | −50% to −150% per side                                           | world 2–4× the frame so lateral legs have runway                                                                                                                                          |
+| PROP_Z                    | 80–300 px                                                        | higher = stronger parallax, earlier fly-past                                                                                                                                              |
+| PROP_COUNTER_TILT         | ≈ `-LAND_RX` of the leg that reads it                            | author by eye and bake                                                                                                                                                                    |
+| DIVE_RX / LAND_RX         | 30–55°                                                           | "angled grid" starts ~30°; \|rx\| ≤ ~65°, \|ry\| ≤ ~30° — beyond that flat planes go edge-on, text unreadable                                                                             |
+| DIVE_Z / LAND_Z           | 300–700 px at PERSPECTIVE_PX ≈ 1000                              | **Z budget**: `cam.z + PROP_Z ≤ ~0.6 × PERSPECTIVE_PX` for readable content — near the perspective distance, scale blows toward infinity and elements invert/vanish past the camera plane |
+| WIDE_Z                    | −100 to −400 px                                                  | negative z = world pushed away = camera wide                                                                                                                                              |
+| DIVE_X/Y, LAND_X/Y        | read off a screenshot at the baked tilt                          | screen-aligned (translate outside rotations)                                                                                                                                              |
+| DIVE_DUR / LAND_DUR       | 0.6–1.0 s                                                        | commitment, not a polite zoom; under 0.5 s reads as a cut                                                                                                                                 |
+| FLATTEN_DUR               | 1.2–2.0 s                                                        | the repositioning is the breath between dives                                                                                                                                             |
+| PAN_DUR                   | 0.8–1.5 s plain; 0.5–0.8 s whip                                  |                                                                                                                                                                                           |
+| Ease law                  | `power4.out` dives/landings; `power2.inOut` repositioning/cruise | spring/back on a camera reads as the world wobbling on a string; four identical pushes read as a slideshow — vary the leg verbs                                                           |
+| Holds                     | ≥ 0.8 s between legs; final dwell ≥ 1 s                          | unless ending held mid-dive                                                                                                                                                               |
+| BLUR_PER_DEPTH / MAX_BLUR | per [depth-of-field-blur.md](depth-of-field-blur.md)             | 3–6 px per step, terminal 8–24 px, leaf elements only; travel-blur peak per [motion-blur-streak.md](motion-blur-streak.md) (~18–20 px full-frame, on `.stage`)                            |
+
+## Critical Constraints
+
+- **One lens, one state, one writer** — `perspective` on the static `.stage` only (never on `.world`, never tweened, never a second perspective wrapper inside); every leg tweens the single `cam` object; only `applyCamera()` writes the transform — drift folds into the same writer via additive state. Two writers (or a second transform sneaking in via CSS) is the classic broken-camera bug, five channels of it here.
+- **Fixed transform order: translate outside the rotations** — `translate3d(x,y,z) rotateX() rotateY()`. Reorder it and every pose you authored silently means something else.
+- **Keep the world CLEAN** — `filter`, `opacity < 1`, `overflow` other than `visible`, `clip-path`, or `mask` on `.world` (or any intermediate wrapper) forces used `transform-style: flat` and collapses every `translateZ` in the scene. Travel blur goes on `.stage`; DoF on leaf cards; fades on children; background on `.scene`. `transform-style: preserve-3d` on `.world` and every intermediate wrapper between it and 3D-positioned children.
+- **Camera intent inverts onto the world** — fly in = world z up, pan right = world x negative, tilt down = world rx positive. Same sign law as `viewport-change`, two more axes to get right.
+- **Poses authored and baked** — never measured per-frame, never hand-derived projections.
+- **First leg is a `fromTo`** AND `applyCamera()` runs once at setup — a seek to t=0 must render the exact establishing pose.
+- **Z budget** — only sacrificial props may cross the camera plane.
+- **Reads happen at landings** — angled, blurred, flying text is texture; anything the viewer must read gets a near-flat pose or a sharp held close-up ≥ 1 s (the tilt-to-flatten leg exists to hand the surface over for reading).
+- **`overflow: hidden` on `.scene` + `data-layout-allow-overflow` on `.world`** — travel legs deliberately push panels past the frame; without the pairing, `check` reports `container_overflow` for every region the flight leaves behind.
+
+## See also
+
+[viewport-change.md](viewport-change.md) (2D counterpart, same single-writer law — right when the shot never tilts) · [multi-phase-camera.md](multi-phase-camera.md) (leg-sequencing grammar + hold micro-drift) · [coordinate-target-zoom.md](coordinate-target-zoom.md) (aim math for a flat-hold zoom while `rx`/`ry` are 0) · [depth-of-field-blur.md](depth-of-field-blur.md) (non-focal defocus / racks) · [motion-blur-streak.md](motion-blur-streak.md) (travel blur on the stage) · [nudge-curve.md](nudge-curve.md) (whip-sweep burst tuning) · [3d-page-scroll.md](3d-page-scroll.md) (static-tilt cousin — camera should NOT travel) · [orbit-3d-entry.md](orbit-3d-entry.md) / [depth-scatter-assemble.md](depth-scatter-assemble.md) (elements moving under a still camera — the inverse; don't run both on one beat). Capability background: `../techniques.md` § CSS 3D Transforms.

package/dist/assets/design/skills/hyperframes-animation/rules/3d-page-scroll.md

@@ -0,0 +1,135 @@
+---
+name: 3d-page-scroll
+description: Full webpage rendered as tilted 3D card that scrolls to reveal specific sections.
+metadata:
+  tags: 3d, page, scroll, webpage, tilt, product-demo, perspective
+---
+
+# 3D Page Scroll
+
+A webpage (or long content) presented as a tilted 3D card. Spring-eased scroll reveals specific sections while the static 3D perspective adds physical depth. (For a camera that actually travels/tilts, see [3d-camera-flight.md](3d-camera-flight.md) — this rule's tilt never moves.)
+
+## How It Works
+
+Two independent transforms combine:
+
+1. **3D tilt** — static `rotateY` + `rotateX` with `perspective` on the card. The angle does **not** change during the scene.
+2. **Scroll** — the content inside the card translates vertically (`y` in GSAP) within a clipped container; spring-like deceleration via `power3.out` / `power4.out`.
+
+Optional: **spotlight overlay** — a radial-gradient mask dims everything except a focal region after the scroll lands. It sits above the scrolling content, fixed relative to the card, never inside `.page-content`.
+
+## Recipe
+
+```html
+<div class="tilt-card">
+  <div class="page-content">
+    <!-- Full {Brand} webpage recreation, taller than the card so scrolling
+         matters. Each section is REAL DOM, not a screenshot — screenshots
+         can't be individually highlighted or scrolled-to with precision. -->
+    <section class="page-hero">{heroContents}</section>
+    <section class="page-features">{featuresContents}</section>
+    <section class="page-target" id="target-section">{targetContents}</section>
+    <section class="page-cta">{ctaContents}</section>
+  </div>
+  <div class="spotlight"></div>
+</div>
+```
+
+```css
+.tilt-card {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  /* tilt + perspective in CSS only if no other transform tween touches this
+     element — if GSAP also tweens scale on .tilt-card, set the tilt via
+     gsap.set() instead to avoid matrix overwrites */
+  transform: translate(-50%, -50%) perspective({perspectivePx}) rotateY({tiltYDeg}) rotateX({tiltXDeg});
+  transform-style: preserve-3d;
+  width: {cardWidth};
+  height: {cardHeight};
+  border-radius: 24px;
+  background: {cardBackgroundColor};
+  overflow: hidden; /* clip the scrolling content at the rounded corners */
+  /* shadow X-offset sign must match tiltY sign (negative tiltY ⇒ positive X) */
+  box-shadow: 40px 30px 80px rgba(0, 0, 0, 0.45);
+}
+.page-content {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  /* height intrinsic from sections — taller than the card */
+}
+.spotlight {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  opacity: 0;
+  background: radial-gradient(ellipse 60% 35% at 50% 50%, transparent 50%, {spotlightDimColor} 100%);
+}
+```
+
+```js
+// SCROLL_DISTANCE is measured at design time from the real page layout
+// (top of .page-content origin to vertical center of #target-section,
+// accounting for card height) — NOT a free tunable.
+tl.to(
+  ".page-content",
+  { y: -SCROLL_DISTANCE, duration: SCROLL_DUR, ease: "power3.out" },
+  SCROLL_AT,
+);
+
+// Spotlight fades in on the target after the scroll settles.
+tl.to(
+  ".spotlight",
+  { opacity: 1, duration: SPOTLIGHT_FADE_DUR, ease: "power1.inOut" },
+  SPOTLIGHT_AT,
+);
+```
+
+## Variations
+
+**Multi-step scroll (scroll → pause → scroll)** — multiple `y:` tweens at different positions. Distances are both measured from the `.page-content` origin (NOT delta from the previous step); GSAP composes successive `y:` tweens on the same property, each starting from the value the previous one left:
+
+```js
+tl.to(
+  ".page-content",
+  { y: -SCROLL_DISTANCE_A, duration: SCROLL_DUR, ease: "power3.out" },
+  SCROLL_AT_A,
+);
+tl.to(
+  ".page-content",
+  { y: -SCROLL_DISTANCE_B, duration: SCROLL_DUR, ease: "power3.out" },
+  SCROLL_AT_B,
+);
+// SCROLL_AT_A + SCROLL_DUR ≤ SCROLL_AT_B — the two scrolls must not fight for y
+```
+
+## Values
+
+| token              | range / rule                                                              | notes                                                                                 |
+| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| tiltYDeg           | −12 to −4 (left-leaning) or 4 to 12                                       | bigger = more dramatic 3D; near 0 collapses to a flat panel                           |
+| tiltXDeg           | 0–6                                                                       | positive tilts the top edge away                                                      |
+| perspectivePx      | 800–2000 px                                                               | smaller = more foreshortening; larger = nearly orthographic                           |
+| cardWidth / Height | card height < total content height                                        | otherwise the scroll has nothing to reveal                                            |
+| sectionHeight      | Σ heights ≥ cardHeight + SCROLL_DISTANCE                                  | so the target section lands within frame                                              |
+| SCROLL_AT          | ≥ end of prior tweens on `.page-content`                                  |                                                                                       |
+| SCROLL_DUR         | 0.8–1.8 s                                                                 | shorter feels like a hard cut; longer feels programmatic                              |
+| SCROLL_DISTANCE    | measured from the layout                                                  | from actual cumulative section heights — never estimated; don't overshoot content end |
+| SPOTLIGHT_AT       | ≥ SCROLL_AT + SCROLL_DUR (or slightly earlier)                            | spotlight reveals the freshly-arrived section                                         |
+| SPOTLIGHT_FADE_DUR | 0.4–0.8 s                                                                 |                                                                                       |
+| Ease               | `power3.out` default; `power4.out` momentum; `power2.inOut` cinematic pan | pick ONE for all scrolls in the scene — mixing easings reads as jerky                 |
+
+## Critical Constraints
+
+- **Tilt is static** — the card holds its angle the whole scene.
+- **Shadow direction matches tilt** — a left-leaning card casts shadow to the right (positive X offset); mismatch breaks the 3D illusion.
+- **Page content is real HTML, not a screenshot**; scroll distances come from the real layout geometry.
+- **`overflow: hidden` + `transform-style: preserve-3d` on `.tilt-card`** — clip at the rounded corners; preserve-3d for any 3D children / clean perspective composition.
+- **Spotlight is an overlay above the scrolling content**, never inside `.page-content`.
+- **Same easing across a multi-phase scroll**, and non-overlapping scroll windows.
+
+## See also
+
+[asr-keyword-glow.md](asr-keyword-glow.md) (on-page keyword highlight synced to VO) · [multi-phase-camera.md](multi-phase-camera.md) (camera zoom while the page scrolls) · [cursor-click-ripple.md](cursor-click-ripple.md) (cursor lands in the scrolled-into-view section) · [3d-camera-flight.md](3d-camera-flight.md) (when the camera itself should travel).

package/dist/assets/design/skills/hyperframes-animation/rules/3d-text-depth-layers.md

@@ -0,0 +1,128 @@
+---
+name: 3d-text-depth-layers
+description: Multiple offset text layers create a stacked 3D shadow / extrusion effect on large typography — more impactful than CSS text-shadow because each layer is a full DOM element.
+metadata:
+  tags: text, 3d, depth, layers, shadow, typography, stacked, extrusion
+---
+
+# 3D Text Depth Layers
+
+The same text rendered N times at increasing offsets — back layers translucent, front layer full opacity and brand color — creates a physical "stacked extrusion" depth illusion on large typography. Distinct from `text-shadow` (which can't have per-layer hue / opacity / animation): each layer is a real DOM element.
+
+## How It Works
+
+A build script appends `LAYER_COUNT` copies back-to-front; each back layer sits at `translate(i × OFFSET_X, i × OFFSET_Y)` with alpha stepping down per layer, while the front copy (`i = 0`) is `position: relative` so it defines the container size (back layers stack absolutely behind it). The default entrance cascades the layers' fades back-to-front while a proxy tween grows the offsets from 0 → full, so the depth "builds forward" and lands as the last layer fades in.
+
+## Recipe
+
+```html
+<!-- inside a standard scene clip (hyperframes-core) -->
+<div class="depth-stack">
+  <!-- layers injected by script — LAYER_COUNT copies of {label} -->
+</div>
+```
+
+```css
+.depth-stack {
+  position: relative; /* front layer defines size; back layers stack behind */
+}
+.depth-text {
+  font-weight: 900; /* black weight — thin text loses the illusion */
+  font-size: HERO_FONT_SIZE;
+  letter-spacing: HERO_LETTER_SPACING;
+  line-height: 1;
+  color: {frontColor};
+}
+.depth-text.is-back {
+  position: absolute;
+  top: 0;
+  left: 0;
+  pointer-events: none; /* decorative */
+}
+.depth-text.is-front {
+  position: relative;
+  z-index: 10;
+}
+```
+
+```js
+const stack = document.querySelector(".depth-stack");
+
+// Build back-to-front so the FRONT (i=0) is appended LAST
+for (let i = LAYER_COUNT - 1; i >= 0; i--) {
+  const el = document.createElement("div");
+  el.className = "depth-text " + (i === 0 ? "is-front" : "is-back");
+  el.textContent = "{label}";
+  if (i > 0) {
+    const alpha = Math.max(BACK_ALPHA_MAX - i * BACK_ALPHA_STEP, BACK_ALPHA_MIN);
+    el.style.color = `rgba({backHueRGB}, ${alpha})`; // rgba in color, NOT element opacity
+    el.style.transform = `translate(${i * OFFSET_X}px, ${i * OFFSET_Y}px)`;
+  }
+  el.dataset.layer = String(i);
+  stack.appendChild(el);
+}
+
+// Cascade entry — back layers fade in first, building forward
+stack.querySelectorAll(".depth-text").forEach((el) => {
+  const i = Number(el.dataset.layer);
+  const finalAlpha = i === 0 ? 1 : Math.max(BACK_ALPHA_MAX - i * BACK_ALPHA_STEP, BACK_ALPHA_MIN);
+  tl.fromTo(
+    el,
+    { opacity: 0 },
+    { opacity: finalAlpha, duration: LAYER_FADE_DUR, ease: "power2.out" },
+    LAYER_CASCADE_START + (LAYER_COUNT - 1 - i) * LAYER_CASCADE_STEP,
+  );
+});
+
+// Depth grows on entry — offsets interpolate 0 → full
+const depthState = { p: 0 };
+tl.to(
+  depthState,
+  {
+    p: 1,
+    duration: DEPTH_GROW_DUR,
+    ease: "power2.out",
+    onUpdate: () => {
+      stack.querySelectorAll(".depth-text.is-back").forEach((el) => {
+        const i = Number(el.dataset.layer);
+        el.style.transform = `translate(${i * OFFSET_X * depthState.p}px, ${i * OFFSET_Y * depthState.p}px)`;
+      });
+    },
+  },
+  LAYER_CASCADE_START, // align with the cascade so depth lands as the last layer fades in
+);
+```
+
+## Variations
+
+- **Static depth** (single hero shot) — render all layers at final positions from t=0; optionally fade the whole stack in with a subtle scale (0.94–0.98 → 1, 0.5–0.8s).
+- **Dynamic depth pulse** — after the grow completes, modulate the offsets with a sine multiplier `1 + sin(p) × BEAT_AMP` (BEAT_AMP 0.2–0.6; one beat per 0.7–1.5s reads as a heartbeat).
+- **Color-shift back layers** — instead of fading to translucent, step hue/lightness per layer: `hsla(HUE_BASE − i × HUE_STEP, SAT_PCT%, LIGHT_BASE − i × LIGHT_STEP%, 1)` (HUE_STEP 4–12°; larger reads as glitch). Depth reads as a colored cast shadow.
+
+## Values
+
+| token               | range                    | notes                                                                  |
+| ------------------- | ------------------------ | ---------------------------------------------------------------------- |
+| LAYER_COUNT         | 4–6                      | <4 doesn't read as 3D; >6 clutters on tight kerning                    |
+| OFFSET_X / OFFSET_Y | 1–3px each               | >4px reads as glitch / chromatic aberration, not depth                 |
+| BACK_ALPHA_MAX      | 0.6–0.85                 | nearest back layer; >0.9 fights the front for dominance                |
+| BACK_ALPHA_STEP     | 0.08–0.15                | small = soft gradient; large = discrete plates                         |
+| BACK_ALPHA_MIN      | 0.1–0.2                  | floor — below 0.1 the deepest layer vanishes on dark backgrounds       |
+| HERO_FONT_SIZE      | 60px min; 200–340px hero | thin/small text loses the layered illusion                             |
+| HERO_LETTER_SPACING | −0.03em–0                | tighter makes offsets read as depth, not repetition                    |
+| LAYER_CASCADE_STEP  | 0.04–0.10s               | smaller ≈ simultaneous; larger feels stepped                           |
+| LAYER_FADE_DUR      | 0.3–0.6s                 | per-layer fade                                                         |
+| DEPTH_GROW_DUR      | 0.4–0.8s                 | ≈ `LAYER_FADE_DUR × LAYER_COUNT / 2` so depth lands with the last fade |
+
+## Critical Constraints
+
+- **Offset direction implies light direction** — `(+x, +y)` = light upper-left, `(-x, +y)` = upper-right; one sign convention for the whole composition.
+- **Back layers translucent OR darker — never more saturated than the front** (reads as a halo, not depth).
+- **Set back-layer color via `rgba()` in `color`, not element `opacity`** — opacity fades the whole rendered glyph including any shadow.
+- **Front layer `position: relative` defines container size**; back layers absolute with `pointer-events: none`; offsets via `transform: translate()`, never `top`/`left`.
+- **No CSS `text-shadow` alongside layered depth** — they compound and over-extrude.
+- **No per-letter animation on top of the stack** — hacker-flip / typewriter over 6-layer depth is chaos; drop to 2–3 layers or apply depth only to the static post-reveal state.
+
+## See also
+
+`counting-dynamic-scale` (counter rendered with depth layers) · `sine-wave-loop` (idle breathing on the front layer post-reveal) · `center-outward-expansion` (depth-stacked wordmark after the burst lands).