hyperframes 0.6.31 → 0.6.32

package/dist/skills/hyperframes/references/html-in-canvas-patterns.md

@@ -0,0 +1,507 @@
+# HTML-in-Canvas Patterns
+
+HyperFrames' most powerful visual capability. Capture ANY live HTML/CSS as a GPU texture, then render it through WebGL shaders, Three.js 3D scenes, or post-processing effects — at 60fps, pixel-perfect, with every CSS feature supported.
+
+**Read this file when a beat deserves cinematic treatment beyond flat GSAP animations.** Use for 1-3 hero beats per video, not every beat. The rest can use standard GSAP — the contrast between flat beats and HTML-in-Canvas beats IS part of the visual storytelling.
+
+---
+
+## Core Boilerplate (same in every HTML-in-Canvas composition)
+
+Every HTML-in-Canvas effect shares this structure. Learn this once, adapt it for any effect.
+
+```html
+<!-- 1. Source HTML — your content goes inside a layoutsubtree canvas -->
+<canvas
+  id="hic-source"
+  layoutsubtree
+  width="1920"
+  height="1080"
+  style="position:absolute;inset:0;opacity:0;"
+>
+  <div id="hic-content" style="width:1920px;height:1080px;">
+    <!-- YOUR HTML CONTENT HERE — text, images, cards, dashboards, anything -->
+  </div>
+</canvas>
+
+<!-- 2. Render target — the visible canvas that shows the effect -->
+<canvas id="hic-output" width="1920" height="1080" style="position:absolute;inset:0;"></canvas>
+```
+
+```js
+// 3. Feature detection — always check, always provide fallback
+function isHiCSupported() {
+  var tc = document.createElement("canvas");
+  if (!("layoutSubtree" in tc)) return false;
+  tc.setAttribute("layoutsubtree", "");
+  var ctx = tc.getContext("2d");
+  return ctx && typeof ctx.drawElementImage === "function";
+}
+var apiOk = isHiCSupported();
+
+// 4. Capture function — call this every frame in onUpdate
+var capCanvas = document.getElementById("hic-source");
+var capCtx = capCanvas.getContext("2d");
+function captureContent() {
+  if (apiOk) {
+    capCtx.drawElementImage(document.getElementById("hic-content"), 0, 0, 1920, 1080);
+  }
+}
+
+// 5. Drive from GSAP timeline — capture + render every frame
+tl.to(
+  proxy,
+  {
+    /* your animation properties */
+    duration: BEAT_DURATION,
+    ease: "sine.inOut",
+    onUpdate: function () {
+      captureContent();
+      // render your effect here (Three.js or WebGL2)
+    },
+  },
+  0,
+);
+```
+
+**Fallback:** When `drawElementImage` is not available (preview without Chrome flag), draw a solid-color placeholder or use Canvas 2D text. The HyperFrames renderer auto-enables the flag — the effect WILL work in the final video. See the liquid-glass block for a complete fallback example.
+
+---
+
+## Effect Catalog
+
+### 1. 3D Rotation with Bloom (Three.js)
+
+**What it looks like:** Content floats in 3D space, slowly rotating with cinematic glow around bright edges. Like a product screenshot displayed in a dark theater.
+
+**When to use:** Hero product showcase, feature reveal, CTA with premium feel.
+
+**Key Three.js components:** `PlaneGeometry` + `CanvasTexture` + `EffectComposer` + `UnrealBloomPass`
+
+```js
+// After the boilerplate above, add:
+var scene3d = new THREE.Scene();
+var camera = new THREE.PerspectiveCamera(45, 1920 / 1080, 0.1, 100);
+camera.position.set(0, 0, 4);
+
+var renderer = new THREE.WebGLRenderer({
+  canvas: document.getElementById("hic-output"),
+  antialias: true,
+  alpha: true,
+});
+renderer.setSize(1920, 1080);
+
+var texture = new THREE.CanvasTexture(capCanvas);
+var mesh = new THREE.Mesh(
+  new THREE.PlaneGeometry(3.6, 2.2),
+  new THREE.MeshBasicMaterial({ map: texture }),
+);
+scene3d.add(mesh);
+
+// Post-processing: bloom for cinematic glow.
+// EffectComposer / RenderPass / UnrealBloomPass are ES-module named imports
+// (see the import block below) — they're NOT properties of THREE in modern
+// versions. Three.js r150+ removed the UMD `examples/js/` globals.
+var composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene3d, camera));
+composer.addPass(new UnrealBloomPass(new THREE.Vector2(1920, 1080), 0.3, 0.4, 0.85));
+
+var proxy = { rotY: -0.12, zoom: 4.2 };
+tl.to(
+  proxy,
+  {
+    rotY: 0.12,
+    zoom: 3.6,
+    duration: BEAT_DURATION,
+    ease: "sine.inOut",
+    onUpdate: function () {
+      captureContent();
+      texture.needsUpdate = true;
+      mesh.rotation.y = proxy.rotY;
+      camera.position.z = proxy.zoom;
+      composer.render();
+    },
+  },
+  0,
+);
+```
+
+**Load Three.js and post-processing via ESM (use a `type="module"` script):**
+
+```html
+<script type="module">
+  import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.181.2/+esm";
+  import { EffectComposer } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/EffectComposer.js";
+  import { RenderPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/RenderPass.js";
+  import { ShaderPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/ShaderPass.js";
+  import { UnrealBloomPass } from "https://cdn.jsdelivr.net/npm/three@0.181.2/examples/jsm/postprocessing/UnrealBloomPass.js";
+  // ... rest of composition code using these imports
+</script>
+```
+
+The `examples/js/` path was removed in Three.js r152. Use `examples/jsm/` (ES modules) with `three@0.181.2` — the version used by the HyperFrames Three.js adapter.
+
+---
+
+### 2. Magnetic Cursor Distortion (Raw WebGL2)
+
+**What it looks like:** Content warps and bends toward a moving point, like a magnet pulling on pixels. Chromatic aberration splits RGB channels at the distortion site.
+
+**When to use:** Interactive feel, product demo with cursor, "look at THIS feature" moment.
+
+**Key technique:** Custom fragment shader with Gaussian warp + chromatic split. No Three.js needed — just raw WebGL2.
+
+```js
+// WebGL2 setup
+var gl = document.getElementById("hic-output").getContext("webgl2", {
+  alpha: false,
+  preserveDrawingBuffer: true,
+});
+
+// Vertex shader — full-screen quad
+var VS = `#version 300 es
+in vec2 a_pos;
+out vec2 v_uv;
+void main() {
+  v_uv = a_pos * 0.5 + 0.5;
+  gl_Position = vec4(a_pos, 0.0, 1.0);
+}`;
+
+// Fragment shader — magnetic warp + chromatic aberration
+var FS = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 fragColor;
+uniform sampler2D u_tex;
+uniform vec2 u_cursor;   // cursor position (0-1)
+uniform float u_strength; // warp strength (0-1)
+
+void main() {
+  vec2 uv = v_uv;
+  vec2 delta = uv - u_cursor;
+  float dist = length(delta);
+  float warp = u_strength * exp(-dist * dist * 8.0);
+  vec2 warped = uv - delta * warp * 0.3;
+
+  // Chromatic aberration at distortion site
+  float aberration = warp * 0.008;
+  float r = texture(u_tex, warped + vec2(aberration, 0.0)).r;
+  float g = texture(u_tex, warped).g;
+  float b = texture(u_tex, warped - vec2(aberration, 0.0)).b;
+  fragColor = vec4(r, g, b, 1.0);
+}`;
+
+// Compile, link, setup quad geometry, upload texture...
+// (See registry/blocks/vfx-magnetic/vfx-magnetic.html for complete implementation)
+
+// Drive cursor position from GSAP
+var proxy = { cx: 0.2, cy: 0.5, strength: 0.0 };
+tl.to(
+  proxy,
+  {
+    cx: 0.8,
+    cy: 0.4,
+    strength: 1.0,
+    duration: BEAT_DURATION,
+    ease: "power2.inOut",
+    onUpdate: function () {
+      captureContent();
+      // Upload texture, set uniforms, draw
+      gl.uniform2f(cursorLoc, proxy.cx, proxy.cy);
+      gl.uniform1f(strengthLoc, proxy.strength);
+      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+    },
+  },
+  0,
+);
+```
+
+---
+
+### 3. Shatter / Fragment Explosion (Three.js)
+
+**What it looks like:** Content breaks into geometric fragments that fly apart, revealing what's behind.
+
+**When to use:** Dramatic transition, "breaking free" moment, tension release.
+
+**Key technique:** Subdivide the source texture into triangle mesh fragments using BufferGeometry, then animate each fragment's position/rotation with GSAP.
+
+Study `registry/blocks/vfx-shatter/vfx-shatter.html` for the complete 1156-line implementation. The core idea:
+
+```js
+// 1. Capture content to texture (same boilerplate)
+// Seeded PRNG for determinism — Math.random() is banned
+function mulberry32(seed) {
+  return function () {
+    seed |= 0;
+    seed = (seed + 0x6d2b79f5) | 0;
+    var t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+var rng = mulberry32(42);
+
+// 2. Create N triangle fragments from the texture
+var fragments = [];
+for (var i = 0; i < NUM_FRAGMENTS; i++) {
+  var geom = new THREE.BufferGeometry();
+  var mesh = new THREE.Mesh(geom, new THREE.MeshBasicMaterial({ map: texture }));
+  scene3d.add(mesh);
+  fragments.push({ mesh: mesh, targetPos: randomExplosionVector(rng), delay: rng() * 0.5 });
+}
+
+// 3. Animate: first hold still, then EXPLODE
+tl.to({}, { duration: holdTime }, 0);
+fragments.forEach(function (frag) {
+  tl.to(
+    frag.mesh.position,
+    {
+      x: frag.targetPos.x,
+      y: frag.targetPos.y,
+      z: frag.targetPos.z,
+      duration: 0.8,
+      ease: "power3.in",
+    },
+    holdTime + frag.delay,
+  );
+  tl.to(
+    frag.mesh.rotation,
+    { x: rng() * 4, y: rng() * 4, duration: 0.8, ease: "power2.in" },
+    holdTime + frag.delay,
+  );
+});
+```
+
+---
+
+### 4. Liquid / Fluid Surface (Three.js)
+
+**What it looks like:** Content floats above a rippling liquid surface with real-time wave dynamics. Or content IS the surface, undulating like water.
+
+**When to use:** Organic/premium feel, ambient background, "living" product showcase.
+
+**Key technique:** Subdivided PlaneGeometry with vertex displacement driven by noise functions in a vertex shader.
+
+Study `registry/blocks/vfx-liquid-background/vfx-liquid-background.html` for the 1244-line implementation. Core idea:
+
+```js
+// Custom vertex shader with wave displacement
+var vertexShader = `
+  varying vec2 vUv;
+  uniform float u_time;
+  void main() {
+    vUv = uv;
+    vec3 pos = position;
+    // Sine wave displacement
+    pos.z += sin(pos.x * 3.0 + u_time * 2.0) * 0.15;
+    pos.z += cos(pos.y * 2.5 + u_time * 1.5) * 0.1;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
+  }
+`;
+
+var mesh = new THREE.Mesh(
+  new THREE.PlaneGeometry(4, 3, 64, 64), // heavily subdivided for smooth waves
+  new THREE.ShaderMaterial({
+    vertexShader: vertexShader,
+    fragmentShader: `varying vec2 vUv; uniform sampler2D u_tex;
+      void main() { gl_FragColor = texture2D(u_tex, vUv); }`,
+    uniforms: {
+      u_tex: { value: texture },
+      u_time: { value: 0 },
+    },
+  }),
+);
+```
+
+---
+
+### 5. Portal / Dimensional Reveal (Three.js)
+
+**What it looks like:** A glowing circular portal opens and content emerges through it from another dimension.
+
+**When to use:** Product reveal, "entering the app" moment, hero feature introduction.
+
+Study `registry/blocks/vfx-portal/vfx-portal.html` for the complete 863-line implementation.
+
+---
+
+## When to Use HTML-in-Canvas vs Standard GSAP
+
+| Scenario                         | Use                                  | Why                                  |
+| -------------------------------- | ------------------------------------ | ------------------------------------ |
+| Hero product screenshot showcase | HTML-in-Canvas (3D rotation + bloom) | Makes flat UI feel cinematic         |
+| Feature list / stats             | Standard GSAP                        | Content-focused, doesn't need 3D     |
+| CTA / brand reveal               | HTML-in-Canvas (portal or magnetic)  | Makes the moment memorable           |
+| Social proof / logos             | Standard GSAP                        | Orderly cascade, trust is steady     |
+| Transition between acts          | HTML-in-Canvas (shatter)             | Dramatic act break                   |
+| Background atmosphere            | HTML-in-Canvas (liquid surface)      | Premium ambient feel                 |
+| Quick feature cards              | Standard GSAP                        | Speed matters, 3D would slow it down |
+
+---
+
+## More Effects You Can Build
+
+These aren't in the VFX blocks — build them yourself from the core boilerplate + a custom fragment shader. Each effect is a single GLSL function applied to the captured texture.
+
+### 6. Noise Dissolve
+
+Content dissolves into noise particles, revealing what's behind. Great for transitions.
+
+```glsl
+// Fragment shader — noise-based dissolve
+uniform float u_progress; // 0.0 = fully visible, 1.0 = fully dissolved
+uniform sampler2D u_tex;
+
+float hash(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
+}
+
+void main() {
+  vec2 uv = v_uv;
+  float noise = hash(uv * 50.0);
+  float threshold = u_progress;
+  if (noise < threshold) {
+    // Edge glow at the dissolve boundary
+    float edge = smoothstep(threshold - 0.05, threshold, noise);
+    fragColor = vec4(1.0, 0.6, 0.2, 1.0) * (1.0 - edge); // orange edge glow
+  } else {
+    fragColor = texture(u_tex, uv);
+  }
+}
+```
+
+### 7. Holographic / Iridescent
+
+Content gets a rainbow-shifting holographic sheen that moves with time. Premium, futuristic feel.
+
+```glsl
+uniform float u_time;
+uniform sampler2D u_tex;
+
+void main() {
+  vec4 color = texture(u_tex, v_uv);
+  // Iridescent color shift based on position + time
+  float angle = v_uv.x * 6.28 + v_uv.y * 3.14 + u_time * 0.5;
+  vec3 holo = vec3(
+    sin(angle) * 0.5 + 0.5,
+    sin(angle + 2.094) * 0.5 + 0.5,
+    sin(angle + 4.189) * 0.5 + 0.5
+  );
+  // Blend holographic over content (subtle overlay)
+  fragColor = vec4(mix(color.rgb, holo, 0.15 + 0.1 * sin(u_time)), color.a);
+}
+```
+
+### 8. Scan Lines + CRT
+
+Retro CRT monitor look — scan lines, slight curvature, phosphor glow. Great for "code" or "terminal" beats.
+
+```glsl
+uniform sampler2D u_tex;
+uniform float u_time;
+
+void main() {
+  vec2 uv = v_uv;
+  // Barrel distortion (CRT curvature)
+  vec2 centered = uv - 0.5;
+  float dist = dot(centered, centered);
+  uv = uv + centered * dist * 0.15;
+
+  vec4 color = texture(u_tex, uv);
+  // Scan lines
+  float scanline = sin(uv.y * 800.0) * 0.04;
+  color.rgb -= scanline;
+  // Slight RGB offset (phosphor)
+  color.r = texture(u_tex, uv + vec2(0.001, 0.0)).r;
+  color.b = texture(u_tex, uv - vec2(0.001, 0.0)).b;
+  // Vignette
+  float vignette = 1.0 - dist * 2.0;
+  fragColor = vec4(color.rgb * vignette, 1.0);
+}
+```
+
+### 9. Frosted Glass Blur
+
+Content behind frosted glass — visible but softened, with subtle light refraction. Good for "behind the scenes" or "coming soon" moments.
+
+```glsl
+uniform sampler2D u_tex;
+uniform float u_blur; // 0.0 = clear, 1.0 = full frost
+
+void main() {
+  vec2 uv = v_uv;
+  vec4 color = vec4(0.0);
+  // Box blur with offset
+  float radius = u_blur * 0.015;
+  for (float x = -2.0; x <= 2.0; x += 1.0) {
+    for (float y = -2.0; y <= 2.0; y += 1.0) {
+      color += texture(u_tex, uv + vec2(x, y) * radius);
+    }
+  }
+  color /= 25.0;
+  // Add frost noise texture
+  float frost = fract(sin(dot(uv * 200.0, vec2(12.9898, 78.233))) * 43758.5453);
+  color.rgb += frost * 0.03 * u_blur;
+  fragColor = color;
+}
+```
+
+### 10. Pixel Sort / Glitch Art
+
+Pixels rearrange themselves in vertical or horizontal strips — digital art aesthetic. Great for tech/creative brands.
+
+```glsl
+uniform sampler2D u_tex;
+uniform float u_intensity; // 0-1
+
+void main() {
+  vec2 uv = v_uv;
+  // Random horizontal displacement per row
+  float row = floor(uv.y * 80.0);
+  float noise = fract(sin(row * 127.1) * 43758.5);
+  float displace = step(0.7, noise) * u_intensity * 0.1;
+  // Shift UV with RGB split
+  float r = texture(u_tex, uv + vec2(displace, 0.0)).r;
+  float g = texture(u_tex, uv).g;
+  float b = texture(u_tex, uv - vec2(displace * 0.5, 0.0)).b;
+  fragColor = vec4(r, g, b, 1.0);
+}
+```
+
+---
+
+## Creating ANY Custom Effect
+
+The fragment shaders above are templates. The pattern is always:
+
+1. **Capture your HTML content** with `drawElementImage` (the boilerplate at the top)
+2. **Upload the captured canvas as a WebGL texture**
+3. **Write a fragment shader** that reads from the texture and outputs modified colors
+4. **Drive shader uniforms from GSAP** via `onUpdate`
+
+Any GLSL effect from ShaderToy, The Book of Shaders, CodePen, or anywhere else can be adapted:
+
+1. Find an effect you like (search "GLSL [effect name]" or browse shadertoy.com)
+2. Copy the fragment shader
+3. Replace `iResolution` with `vec2(1920.0, 1080.0)`, `iTime` with your `u_time` uniform
+4. Add `uniform sampler2D u_tex;` for the captured content texture
+5. Wire the uniforms to GSAP proxy values
+
+**Geometry ideas beyond flat planes:**
+
+- `SphereGeometry` — content mapped onto a globe (world map, global reach)
+- `CylinderGeometry` — content on a rotating cylinder (carousel/scroll feel)
+- `TorusGeometry` — content wrapped around a ring (infinity, cycle)
+- `BoxGeometry` — content on a 3D box (product packaging, dice)
+- GLTF models — content mapped as screen texture on phone, laptop, monitor (see `vfx-iphone-device`)
+
+**Post-processing stacking** (Three.js EffectComposer):
+
+- Bloom + film grain = cinematic
+- Bloom + chromatic aberration = lens effect
+- Depth of field + vignette = focused attention
+- Film grain + scan lines = retro
+- Multiple passes stack — add as many as you want
+
+**You are not limited to the effects listed here.** If you can imagine a visual treatment, you can build it. The HTML-in-Canvas API gives you the source material (any HTML rendered as a texture), and WebGL/Three.js gives you unlimited creative control over how that material is presented.

package/dist/skills/hyperframes/references/motion-principles.md

@@ -1,82 +1,90 @@
 # Motion Principles
 
-## Guardrails
+## Common defaults that produce monoculture
 
-You know these rules but you violate them. Stop.
+These are the patterns LLMs reach for without thinking. None of them are wrong in isolation — they're wrong as defaults. If every scene of every video lands on the same easing, the same speed, and the same entrance direction, the compositions blur into one another no matter what the brand is.
 
-- **Don't use the same ease on every tween.** You default to `power2.out` on everything. Vary eases like you vary font weights — no more than 2 independent tweens with the same ease in a scene.
-- **Don't use the same speed on everything.** You default to 0.4-0.5s for everything. The slowest scene should be 3× slower than the fastest. Vary duration deliberately.
-- **Don't enter everything from the same direction.** You default to `y: 30, opacity: 0` on every element. Vary: from left, from right, from scale, opacity-only, letter-spacing.
-- **Don't use the same stagger on every scene.** Each scene needs its own rhythm.
-- **Don't use ambient zoom on every scene.** Pick different ambient motion per scene: slow pan, subtle rotation, scale push, color shift, or nothing. Stillness after motion is powerful.
-- **Don't start at t=0.** Offset the first animation 0.1-0.3s. Zero-delay feels like a jump cut.
+- **Same ease on every tween.** `power2.out` is the most common default. Aim for variety: no more than two independent tweens sharing an ease within a scene. Eases are like font weights — vary them deliberately.
+- **Same speed on every tween.** 0.4–0.5s is a common default that flattens rhythm. The slowest motion in a scene should be roughly 3× slower than the fastest. Vary duration so the eye can tell what's important.
+- **Same entrance direction.** `y: 30, opacity: 0` is the universal LLM entrance. The same scene can use entrances from left, from right, from scale, from blur, opacity-only, letter-spacing — each one says something different about the element.
+- **Same stagger across scenes.** Each scene should have its own rhythm. A 0.08s stagger in beat 1 and a 0.15s stagger in beat 2 makes the two beats feel like different moments.
+- **Ambient zoom on every scene.** Slow-scale-up is the default ambient motion and it telegraphs "LLM-generated video." Vary the ambient motion per scene: slow pan, subtle rotation, color temperature shift, gentle drift — and sometimes nothing. Stillness after motion has real weight.
+- **First animation at t=0.** Zero-delay feels like a jump cut. Offset the opening 0.1–0.3s so the scene reads as composed rather than thrown together.
 
-## What You Don't Do Without Being Told
+## Easing is emotion, not technique
 
-### Easing is emotion, not technique
+The motion is the verb. The easing is the adverb. A slide-in with `expo.out` feels confident. With `sine.inOut`, dreamy. With `elastic.out`, playful. Same motion, three different meanings. Choose the adverb deliberately.
 
-The transition is the verb. The easing is the adverb. A slide-in with `expo.out` = confident. With `sine.inOut` = dreamy. With `elastic.out` = playful. Same motion, different meaning. Choose the adverb deliberately.
+**Direction rules:**
 
-**Direction rules — these are not optional:**
+- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is the default for entrances.
+- `.in` for elements leaving. Starts slow, accelerates away. Sends them off with momentum.
+- `.inOut` for elements moving between positions, neither entering nor leaving the scene.
 
-- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is your default.
-- `.in` for elements leaving. Starts slow, accelerates away. Throws them off.
-- `.inOut` for elements moving between positions.
+Ease-in on an entrance feels sluggish. Ease-out on an exit feels reluctant. These are the most common reversals and they're worth checking your work against.
 
-You get this backwards constantly. Ease-in for entrances feels sluggish. Ease-out for exits feels reluctant.
+## Speed expresses weight
 
-### Speed communicates weight
+Duration is one of the most direct ways a composition communicates what it values. Faster motion reads as confident, urgent, kinetic — it gives the viewer less time to study what's happening, which means the work has to land in fewer frames. Slower motion reads as deliberate, considered, weighty — the viewer has time to take in the element, which means each element has to earn that attention.
 
-- Fast (0.15-0.3s) — energy, urgency, confidence
-- Medium (0.3-0.5s) — professional, most content
-- Slow (0.5-0.8s) — gravity, luxury, contemplation
-- Very slow (0.8-2.0s) — cinematic, emotional, atmospheric
+Useful calibration ranges (not prescriptions — what a duration _expresses_ depends on what surrounds it):
 
-### Scene structure: build / breathe / resolve
+- **0.15–0.3s** — quick, percussive, kinetic. The motion reads as something happening _to_ the frame.
+- **0.3–0.5s** — comfortable, professional. The motion reads as composed and reliable.
+- **0.5–0.8s** — deliberate. The motion has visible weight and asks for attention.
+- **0.8s+** — atmospheric. The motion becomes part of what the scene _is_, not something happening within it.
 
-Every scene has three phases. You dump everything in the build and leave nothing for breathe or resolve.
+A composition that uses only one of these ranges feels one-note. Mix them — a scene where the headline takes 0.7s to settle and the supporting details land in 0.25s creates contrast that reinforces hierarchy without needing different colors or sizes.
 
-- **Build (0-30%)** — elements enter, staggered. Don't dump everything at once.
-- **Breathe (30-70%)** — content visible, alive with ONE ambient motion.
-- **Resolve (70-100%)** — exit or decisive end. Exits are faster than entrances.
+## Scene structure: build, breathe, resolve
 
-### Transitions are meaning
+Every scene has three phases. The most common failure is dumping everything into the build and leaving nothing for the other two.
 
-- **Crossfade** = "this continues"
-- **Hard cut** = "wake up" / disruption
-- **Slow dissolve** = "drift with me"
+- **Build (0–30%)** — elements enter, staggered. Not all at once.
+- **Breathe (30–70%)** — content visible, alive with one ambient motion. The viewer reads, registers, settles.
+- **Resolve (70–100%)** — exit or decisive end. Exits are faster than entrances (see Asymmetry below).
 
-You crossfade everything. Use hard cuts for disruption and register shifts.
+A scene that's all build feels like a slideshow. A scene with no breathe phase doesn't let the content land.
 
-### Choreography is hierarchy
+## Transitions carry meaning
 
-The element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for completion — overlap entries. Total stagger sequence under 500ms regardless of item count.
+The transition type tells the viewer how two scenes relate:
 
-### Asymmetry
+- **Crossfade** — "this continues." Connective tissue between related ideas.
+- **Hard cut** — "wake up" or a register shift. Disruption, surprise, percussive emphasis.
+- **Slow dissolve** — "drift with me." Atmospheric, meditative, between-thoughts.
 
-Entrances need longer than exits. A card takes 0.4s to appear but 0.25s to disappear.
+Crossfade is the default and it's defensible most of the time. The thing to watch for is using it for everything — when every transition is a crossfade, the viewer stops registering scene changes as meaningful. Hard cuts and slow dissolves are tools for the moments where the change in scene _is_ the message.
 
-## Visual Composition
+## Choreography is hierarchy
 
-You build for the web. Video frames are not pages.
+The element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for one entrance to complete before starting the next — overlap entries. Total stagger sequence under 500ms regardless of item count keeps the scene from feeling like a slow drip.
 
-- **Two focal points minimum per scene.** The eye needs somewhere to travel. Never a single text block floating in empty space.
-- **Fill the frame.** Hero text: 60-80% of width. You will try to use web-sized elements. Don't.
-- **Three layers minimum per scene.** Background treatment (glow, oversized faded type, color panel). Foreground content. Accent elements (dividers, labels, data bars).
-- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid #000 reads as "nothing loaded."
-- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern.
-- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks.
-- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0).
+## Asymmetry between entrances and exits
 
-## Image Motion Treatment
+Entrances need longer than exits. A card might take 0.4s to appear but 0.25s to disappear — entrances build presence, exits remove it, and remove takes less time than build.
 
-Never embed a raw flat image. Every image must have motion treatment:
+## Visual composition
 
-- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it.
-- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic
-- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow`
-- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax
-- **Scroll reveal**: Clip the image to a viewport window and animate `y` position
+Video frames are not web pages. Web layout patterns that work on a scrollable page often look broken in a fixed-frame composition.
+
+- **Two focal points minimum per scene.** The eye needs somewhere to travel. A single text block floating in empty space reads as unfinished.
+- **Fill the frame.** Hero text typically wants 60–80% of frame width. Web type sizes — 16px body, 32px headlines — disappear at video distance.
+- **Three layers minimum.** Background treatment (glow, oversized faded type, color panel), foreground content, accent elements (dividers, labels, data bars). A scene with only one layer reads flat.
+- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid `#000` reads as "nothing loaded."
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern that looks lost on a 16:9 canvas.
+- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts beat centered stacks.
+- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (`scaleX` from 0).
+
+## Image motion treatment
+
+Embedded images shouldn't sit flat — every image earns some motion treatment:
+
+- **Perspective tilt** — `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` plus a `box-shadow` creates depth. Do NOT use CSS `transform: perspective(...)`; GSAP will overwrite it.
+- **Slow zoom (Ken Burns)** — GSAP `scale: 1` → `1.04` over beat duration. Makes photos feel cinematic rather than pasted in.
+- **Device frame** — wrap in a laptop or phone shape using `border-radius` and `box-shadow`.
+- **Floating UI** — extract a key element and animate it at a different z-depth for parallax.
+- **Scroll reveal** — clip the image to a viewport window and animate `y` position.
 
 ## Load-Bearing GSAP Rules
 
@@ -132,7 +140,7 @@ Rules below came out of two independent website-to-hyperframes builds (2026-04-2
   tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0);
   ```
 
-- **Hard-kill every scene boundary, not just captions.** The caption hard-kill rule above generalizes: any element whose visibility changes at a beat boundary needs a deterministic `tl.set()` kill after its fade, because later tweens on the same element (or `immediateRender` from a sibling tween) can resurrect it. Apply to every element with an exit animation:
+- **Hard-kill every scene boundary, not just captions.** The same hard-kill pattern from `captions.md` generalizes to all elements with exit animations: any element whose visibility changes at a beat boundary needs a deterministic `tl.set()` kill after its fade, because later tweens on the same element (or `immediateRender` from a sibling tween) can resurrect it. Apply to every element with an exit animation:
 
   ```js
   tl.to(el, { opacity: 0, duration: 0.3 }, beatEnd);