hyperframes 0.2.2 → 0.2.3-alpha.2

package/dist/skills/hyperframes/references/transitions/shader-transitions.md

@@ -0,0 +1,329 @@
+# Shader Transition Fragment Shaders
+
+Each shader below is just the GLSL fragment body. Plug it into `mkProg(H + NQ + "...")` using the setup from [shader-setup.md](./shader-setup.md).
+
+### Domain Warp Dissolve
+
+Cascaded `fbm(p + fbm(p))` — both scenes displace along the warp field in opposite directions. Iridescent cosine palette edge glow.
+
+```glsl
+// Requires: NQ + CP
+void main() {
+  vec2 q = vec2(fbm(v_uv * 3.), fbm(v_uv * 3. + vec2(5.2, 1.3)));
+  vec2 r = vec2(fbm(v_uv * 3. + q * 4. + vec2(1.7, 9.2)),
+                fbm(v_uv * 3. + q * 4. + vec2(8.3, 2.8)));
+  float n = fbm(v_uv * 3. + r * 2.);
+  vec2 warpDir = (q - .5) * .4;
+  vec4 A = texture2D(u_from, clamp(v_uv + warpDir * u_progress, 0., 1.));
+  vec4 B = texture2D(u_to, clamp(v_uv - warpDir * (1. - u_progress), 0., 1.));
+  float e = smoothstep(u_progress - .08, u_progress + .08, n);
+  float ed = abs(n - u_progress);
+  float em = smoothstep(.1, 0., ed) * (1. - step(1., u_progress));
+  vec3 ec = palette(ed * 8., vec3(.5), vec3(.5), vec3(1.), vec3(0., .33, .67));
+  gl_FragColor = vec4(mix(B, A, e).rgb + ec * em * 2., 1.);
+}
+```
+
+### Ridged Burn
+
+`abs(noise)` creates sharp lightning-crack edges. Blackbody color gradient (dark red → orange → yellow → white) + high-frequency ember sparks near the edge.
+
+```glsl
+// Requires: NQ
+float ridged(vec2 p) {
+  float v = 0., a = .5;
+  mat2 R = mat2(.8, .6, -.6, .8);
+  for (int i = 0; i < 5; i++) {
+    v += a * abs(vnoise(p) * 2. - 1.);
+    p = R * p * 2.02; a *= .5;
+  }
+  return v;
+}
+void main() {
+  vec4 A = texture2D(u_from, v_uv), B = texture2D(u_to, v_uv);
+  float n = ridged(v_uv * 4.);
+  float e = smoothstep(u_progress - .04, u_progress + .04, n);
+  float heat = smoothstep(.12, 0., abs(n - u_progress)) * (1. - step(1., u_progress));
+  vec3 burn = mix(vec3(.4, 0, 0), vec3(1, .4, 0), smoothstep(0., .25, heat));
+  burn = mix(burn, vec3(1, .85, .3), smoothstep(.25, .5, heat));
+  burn = mix(burn, vec3(1), smoothstep(.5, 1., heat));
+  float sparks = step(.92, vnoise(v_uv * 80.)) * heat * 3.;
+  gl_FragColor = vec4(mix(B, A, e).rgb + burn * heat * 3.5
+    + vec3(1., .7, .3) * sparks, 1.);
+}
+```
+
+### Whip Pan
+
+Both scenes slide horizontally in opposite directions with 10-sample directional motion blur. No noise needed.
+
+```glsl
+void main() {
+  float fromOff = u_progress * 1.5;
+  vec3 fromC = vec3(0.);
+  for (int i = 0; i < 10; i++) {
+    float f = float(i) / 10.;
+    vec2 fuv = vec2(v_uv.x + fromOff + u_progress * .08 * f, v_uv.y);
+    fromC += texture2D(u_from, clamp(fuv, 0., 1.)).rgb;
+  }
+  fromC /= 10.;
+  float toOff = (1. - u_progress) * 1.5;
+  vec3 toC = vec3(0.);
+  for (int i = 0; i < 10; i++) {
+    float f = float(i) / 10.;
+    vec2 tuv = vec2(v_uv.x - toOff - (1. - u_progress) * .08 * f, v_uv.y);
+    toC += texture2D(u_to, clamp(tuv, 0., 1.)).rgb;
+  }
+  toC /= 10.;
+  gl_FragColor = vec4(mix(fromC, toC, u_progress), 1.);
+}
+```
+
+### SDF Iris
+
+Aspect-corrected circle SDF opening from center. Triple onion ring glow.
+
+```glsl
+void main() {
+  vec4 A = texture2D(u_from, v_uv), B = texture2D(u_to, v_uv);
+  vec2 uv = (v_uv - .5) * vec2(u_resolution.x / u_resolution.y, 1.);
+  float d = length(uv);
+  float radius = u_progress * 1.2;
+  float fw = .003;
+  float edge = smoothstep(radius + fw, radius - fw, d);
+  float ring1 = exp(-abs(d - radius) * 25.);
+  float ring2 = exp(-abs(d - radius + .04) * 20.) * .5;
+  float ring3 = exp(-abs(d - radius + .08) * 15.) * .25;
+  float glow = (ring1 + ring2 + ring3) * u_progress * (1. - u_progress) * 4.;
+  gl_FragColor = vec4(mix(A, B, edge).rgb + vec3(1., .85, .6) * glow * .6, 1.);
+}
+```
+
+### Ripple Waves
+
+Exponential sine waves (`exp(sin(x)-1)`) — sharp crests, broad troughs. Both scenes ripple in opposite phases.
+
+```glsl
+void main() {
+  vec2 uv = v_uv - .5;
+  float dist = length(uv);
+  vec2 dir = normalize(uv + .001);
+  float fromAmp = u_progress * .04;
+  float fw1 = exp(sin(dist * 25. - u_progress * 12.) - 1.);
+  float fw2 = exp(sin(dist * 50. - u_progress * 18.) - 1.) * .5;
+  vec2 fromUv = clamp(v_uv + dir * (fw1 + fw2) * fromAmp, 0., 1.);
+  float toAmp = (1. - u_progress) * .04;
+  float tw1 = exp(sin(dist * 25. + u_progress * 12.) - 1.);
+  float tw2 = exp(sin(dist * 50. + u_progress * 18.) - 1.) * .5;
+  vec2 toUv = clamp(v_uv - dir * (tw1 + tw2) * toAmp, 0., 1.);
+  vec4 A = texture2D(u_from, fromUv);
+  vec4 B = texture2D(u_to, toUv);
+  float peak = fw1 * u_progress;
+  vec3 tint = vec3(.9, .95, 1.) * peak * .1;
+  gl_FragColor = vec4(mix(A.rgb + tint, B.rgb, u_progress), 1.);
+}
+```
+
+### Gravitational Lens
+
+Content warps toward gravity well with chromatic aberration + event horizon darkening. Pull is monotonic — never reverses.
+
+```glsl
+void main() {
+  vec4 B = texture2D(u_to, v_uv);
+  vec2 uv = v_uv - .5;
+  float dist = length(uv);
+  float pull = u_progress * 2.;
+  float warpStr = pull * .3 / (dist + .1);
+  vec2 warped = clamp(v_uv - uv * warpStr, 0., 1.);
+  vec4 A = texture2D(u_from, warped);
+  float horizon = smoothstep(0., .3, dist / (1. - u_progress * .85 + .001));
+  float shift = pull * .02 / (dist + .2);
+  float r = texture2D(u_from, clamp(v_uv - uv * (warpStr + shift), 0., 1.)).r;
+  float b = texture2D(u_from, clamp(v_uv - uv * (warpStr - shift), 0., 1.)).b;
+  vec3 lensed = vec3(r, A.g, b) * horizon;
+  gl_FragColor = vec4(mix(lensed, B.rgb, smoothstep(.3, .9, u_progress)), 1.);
+}
+```
+
+### Cinematic Zoom
+
+Both scenes zoom-blur in opposite directions with per-channel radial offset (chromatic aberration). From zooms outward, to zooms inward from tight.
+
+```glsl
+void main() {
+  vec2 d = v_uv - vec2(.5);
+  float fromS = u_progress * .08;
+  float toS = (1. - u_progress) * .06;
+  float fr = 0., fg = 0., fb = 0.;
+  for (int i = 0; i < 12; i++) {
+    float f = float(i) / 12.;
+    fr += texture2D(u_from, v_uv - d * (fromS * 1.06) * f).r;
+    fg += texture2D(u_from, v_uv - d * fromS * f).g;
+    fb += texture2D(u_from, v_uv - d * (fromS * .94) * f).b;
+  }
+  vec3 fromBl = vec3(fr, fg, fb) / 12.;
+  float tr = 0., tg = 0., tb = 0.;
+  for (int i = 0; i < 12; i++) {
+    float f = float(i) / 12.;
+    tr += texture2D(u_to, v_uv + d * (toS * 1.06) * f).r;
+    tg += texture2D(u_to, v_uv + d * toS * f).g;
+    tb += texture2D(u_to, v_uv + d * (toS * .94) * f).b;
+  }
+  vec3 toBl = vec3(tr, tg, tb) / 12.;
+  gl_FragColor = vec4(mix(fromBl, toBl, u_progress), 1.);
+}
+```
+
+### Chromatic Radial Split
+
+Both scenes' RGB channels separate/converge radially. From-scene splits outward, to-scene converges inward.
+
+```glsl
+void main() {
+  vec2 c = v_uv - .5;
+  float fromShift = u_progress * .06;
+  float fr = texture2D(u_from, clamp(v_uv + c * fromShift, 0., 1.)).r;
+  float fg = texture2D(u_from, v_uv).g;
+  float fb = texture2D(u_from, clamp(v_uv - c * fromShift, 0., 1.)).b;
+  vec3 fromSplit = vec3(fr, fg, fb);
+  float toShift = (1. - u_progress) * .06;
+  float tr = texture2D(u_to, clamp(v_uv - c * toShift, 0., 1.)).r;
+  float tg = texture2D(u_to, v_uv).g;
+  float tb = texture2D(u_to, clamp(v_uv + c * toShift, 0., 1.)).b;
+  vec3 toSplit = vec3(tr, tg, tb);
+  gl_FragColor = vec4(mix(fromSplit, toSplit, u_progress), 1.);
+}
+```
+
+### Glitch (shader)
+
+Scan lines + block scramble + chromatic aberration + brightness flicker + color posterization. More aggressive than the CSS glitch.
+
+```glsl
+float rand(vec2 co) {
+  return fract(sin(dot(co, vec2(12.9898, 78.233))) * 43758.5453);
+}
+void main() {
+  float inten = u_progress * (1. - u_progress) * 4.;
+  float lineY = floor(v_uv.y * 60.) / 60.;
+  float lineDisp = (rand(vec2(lineY, floor(u_progress * 17.))) - .5) * .18 * inten;
+  vec2 block = floor(v_uv * vec2(12., 8.));
+  float br = rand(block + vec2(floor(u_progress * 11.)));
+  float ba = step(.83, br) * inten;
+  vec2 bd = (vec2(rand(block * 2.1), rand(block * 3.7)) - .5) * .35 * ba;
+  vec2 uv = clamp(v_uv + vec2(lineDisp, 0.) + bd, 0., 1.);
+  float shift = inten * .035;
+  float r = texture2D(u_from, uv + vec2(shift, 0.)).r;
+  float g = texture2D(u_from, uv).g;
+  float b = texture2D(u_from, uv - vec2(shift, 0.)).b;
+  vec3 col = vec3(r, g, b);
+  col -= step(.5, fract(v_uv.y * u_resolution.y * .5)) * .05 * inten;
+  col *= 1. + (rand(vec2(floor(u_progress * 23.))) - .5) * .3 * inten;
+  float levels = mix(256., 8., inten * .5);
+  col = floor(col * levels) / levels;
+  gl_FragColor = mix(vec4(col, 1.), texture2D(u_to, v_uv), u_progress);
+}
+```
+
+### Swirl Vortex
+
+Both scenes swirl in opposite directions with FBM-warped spiral path.
+
+```glsl
+// Requires: NQ
+void main() {
+  vec2 uv = v_uv - .5;
+  float dist = length(uv);
+  float warp = fbm(v_uv * 4.) * .5;
+  float fromAng = u_progress * (1. - dist) * 10. + warp * u_progress * 3.;
+  float fs = sin(fromAng), fc = cos(fromAng);
+  vec2 fromUv = clamp(vec2(uv.x*fc - uv.y*fs, uv.x*fs + uv.y*fc) + .5, 0., 1.);
+  float toAng = -(1. - u_progress) * (1. - dist) * 10.
+    - warp * (1. - u_progress) * 3.;
+  float ts = sin(toAng), tc = cos(toAng);
+  vec2 toUv = clamp(vec2(uv.x*tc - uv.y*ts, uv.x*ts + uv.y*tc) + .5, 0., 1.);
+  vec4 A = texture2D(u_from, fromUv);
+  vec4 B = texture2D(u_to, toUv);
+  gl_FragColor = mix(A, B, u_progress);
+}
+```
+
+### Thermal Distortion
+
+FBM-driven heat shimmer rising from bottom. Warps both scenes with sine displacement modulated by noise. Slight warm overexposure haze.
+
+```glsl
+// Requires: NQ
+void main() {
+  float heat = u_progress * 1.5;
+  float yFade = smoothstep(1., 0., v_uv.y);
+  float shimmer = sin(v_uv.y * 40. + fbm(v_uv * 6.) * 8.)
+    * fbm(v_uv * 3. + vec2(0., u_progress * 2.));
+  float dispX = shimmer * heat * .03 * yFade;
+  vec2 fromUv = clamp(v_uv + vec2(dispX, 0.), 0., 1.);
+  vec4 A = texture2D(u_from, fromUv);
+  float invShimmer = sin(v_uv.y * 40. + fbm(v_uv * 6. + 3.) * 8.)
+    * fbm(v_uv * 3. + vec2(3., u_progress * 2.));
+  float dispX2 = invShimmer * (1. - u_progress) * .03 * yFade;
+  vec2 toUv = clamp(v_uv + vec2(dispX2, 0.), 0., 1.);
+  vec4 B = texture2D(u_to, toUv);
+  float haze = heat * yFade * .15 * (1. - u_progress);
+  gl_FragColor = vec4(mix(A.rgb, B.rgb, u_progress)
+    + vec3(1., .9, .7) * haze, 1.);
+}
+```
+
+### Flash Through White
+
+Both scenes brighten to white midpoint. Works on dark backgrounds where color-dip-to-black is invisible.
+
+```glsl
+void main() {
+  vec4 A = texture2D(u_from, v_uv), B = texture2D(u_to, v_uv);
+  float toWhite = smoothstep(0., .45, u_progress);
+  vec3 fromC = mix(A.rgb, vec3(1.), toWhite);
+  float fromWhite = 1. - smoothstep(.5, 1., u_progress);
+  vec3 toC = mix(B.rgb, vec3(1.), fromWhite);
+  gl_FragColor = vec4(mix(fromC, toC, smoothstep(.35, .65, u_progress)), 1.);
+}
+```
+
+### Cross-Warp Morph
+
+Both scenes displace along a shared FBM noise field in opposite directions. Noise-driven blend boundary. Neither scene just sits there.
+
+```glsl
+// Requires: NQ
+void main() {
+  vec2 disp = vec2(fbm(v_uv * 3.), fbm(v_uv * 3. + vec2(7.3, 3.7))) - .5;
+  vec2 fromUv = clamp(v_uv + disp * u_progress * .5, 0., 1.);
+  vec2 toUv = clamp(v_uv - disp * (1. - u_progress) * .5, 0., 1.);
+  vec4 A = texture2D(u_from, fromUv);
+  vec4 B = texture2D(u_to, toUv);
+  float n = fbm(v_uv * 4. + vec2(3.1, 1.7));
+  float blend = smoothstep(.4, .6, n + u_progress * 1.2 - .6);
+  gl_FragColor = mix(A, B, blend);
+}
+```
+
+### Light Leak (shader)
+
+Beer-Lambert exponential falloff + ACES tone mapping + directional flare streak. More physically accurate than the CSS overlay version.
+
+```glsl
+vec3 aces(vec3 x) {
+  return clamp((x * (2.51 * x + .03)) / (x * (2.43 * x + .59) + .14), 0., 1.);
+}
+void main() {
+  vec4 A = texture2D(u_from, v_uv), B = texture2D(u_to, v_uv);
+  vec2 lp = vec2(1.3, -.2);
+  float dist = length(v_uv - lp);
+  float leak = clamp(exp(-dist * 1.8) * u_progress * 4., 0., 1.);
+  vec3 warmColor = mix(vec3(1., .5, .15), vec3(1., .9, .75), dist * .7);
+  float flare = exp(-abs(v_uv.y - (-.2 + v_uv.x * .3)) * 15.) * leak * .3;
+  vec3 overexposed = A.rgb + warmColor * leak * 3. + vec3(1., .8, .5) * flare;
+  overexposed = aces(overexposed);
+  gl_FragColor = vec4(mix(overexposed, B.rgb, smoothstep(.15, .85, u_progress)), 1.);
+}
+```

package/dist/skills/hyperframes/references/transitions.md

@@ -0,0 +1,96 @@
+# Scene Transitions
+
+A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A flash cut says "wake up." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
+
+## Energy → Primary Transition
+
+| Energy                                   | Primary                      | Accent for key moments         | Duration  | Easing                 |
+| ---------------------------------------- | ---------------------------- | ------------------------------ | --------- | ---------------------- |
+| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |
+| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |
+| **High** (promos, sports, music, launch) | Flash cut, zoom through      | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`       |
+
+Pick ONE primary (60-70% of scene changes) + 1-2 accents. Never use a different transition for every scene.
+
+## Mood → Transition Type
+
+Think about what the transition _communicates_, not just what it looks like.
+
+| Mood                     | Transitions                                                                                                                                                           | Why it works                                                                                                            |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **Warm / inviting**      | Light leak, blur crossfade, focus pull, film burn, light leak (shader), thermal distortion                                                                            | Soft edges, warm color washes. Nothing sharp or mechanical. The transition feels like sunlight.                         |
+| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve, gravitational lens                                                                                                 | Content transforms mechanically — compressed, shrunk, sliced, gridded. Zoom out creates clinical distance. No softness. |
+| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter, whip pan                                                                                                          | Like turning a page or slicing a layout. Clean directional movement. Whip pan is a fast editorial camera move.          |
+| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration, glitch (shader), chromatic split (shader)                                                              | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines.                             |
+| **Tense / edgy**         | Glitch, VHS, chromatic aberration, flash cut, ripple, ridged burn, glitch (shader)                                                                                    | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.                               |
+| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe, ripple waves, swirl vortex                                                                              | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.                                    |
+| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, diagonal split, color dip to black, cinematic zoom (shader), gravitational lens, domain warp, flash through white | Scale, weight, light extremes. Shader transitions add per-pixel depth.                                                  |
+| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black, slow crossfade, cross-warp morph, thermal distortion                                                                  | Restraint. Cross-warp morph flows both scenes into each other organically.                                              |
+| **Retro / analog**       | Film burn, light leak, VHS, clock wipe                                                                                                                                | Organic imperfection. Warm color bleeds, scan line displacement. Clock wipe evokes broadcast TV.                        |
+
+## Narrative Position
+
+| Position                   | Use                                                                        | Why                                                   |
+| -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |
+| **Opening**                | Your most distinctive transition. Match the mood. 0.4-0.6s                 | Sets the visual language for the entire piece.        |
+| **Between related points** | Your primary transition. Consistent. 0.3s                                  | Don't distract — the content is continuing.           |
+| **Topic change**           | Something different from your primary. Staggered blocks, shutter, squeeze. | Signals "new section" — the viewer's brain resets.    |
+| **Climax / hero reveal**   | Your boldest accent. Fastest or most dramatic.                             | This is the payoff — spend your best transition here. |
+| **Wind-down**              | Return to gentle. Blur crossfade, crossfade. 0.5-0.7s                      | Let the viewer exhale after the climax.               |
+| **Outro**                  | Slowest, simplest. Crossfade, color dip to black. 0.6-1.0s                 | Closure. Don't introduce new energy at the end.       |
+
+## Blur Intensity by Energy
+
+| Energy     | Blur    | Duration | Hold at peak |
+| ---------- | ------- | -------- | ------------ |
+| **Calm**   | 20-30px | 0.8-1.2s | 0.3-0.5s     |
+| **Medium** | 8-15px  | 0.4-0.6s | 0.1-0.2s     |
+| **High**   | 3-6px   | 0.2-0.3s | 0s           |
+
+## Presets
+
+| Preset     | Duration | Easing            |
+| ---------- | -------- | ----------------- |
+| `snappy`   | 0.2s     | `power4.inOut`    |
+| `smooth`   | 0.4s     | `power2.inOut`    |
+| `gentle`   | 0.6s     | `sine.inOut`      |
+| `dramatic` | 0.5s     | `power3.in` → out |
+| `instant`  | 0.15s    | `expo.inOut`      |
+| `luxe`     | 0.7s     | `power1.inOut`    |
+
+## Implementation
+
+Read [transitions/catalog.md](transitions/catalog.md) for GSAP code and hard rules for every transition type.
+
+| Category             | Transitions                                                                                                                                                                                                           |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Content-transforming | Push slide, vertical push, elastic push, squeeze, zoom through, zoom out, gravity drop, 3D flip                                                                                                                       |
+| Reveal/mask          | Circle iris, diamond iris, diagonal split, clock wipe, shutter                                                                                                                                                        |
+| Dissolve             | Crossfade, blur crossfade, focus pull, color dip                                                                                                                                                                      |
+| Cover                | Staggered blocks, horizontal blinds, vertical blinds                                                                                                                                                                  |
+| Light                | Light leak, overexposure burn, film burn                                                                                                                                                                              |
+| Distortion           | Glitch, chromatic aberration, ripple, VHS tape                                                                                                                                                                        |
+| Pattern              | Grid dissolve                                                                                                                                                                                                         |
+| Instant              | Flash cut, morph circle                                                                                                                                                                                               |
+| Shader (WebGL)       | Domain warp, ridged burn, whip pan, SDF iris, ripple waves, gravitational lens, cinematic zoom, chromatic split, glitch, swirl vortex, thermal distortion, flash through white, cross-warp morph, light leak (shader) |
+
+## Transitions That Don't Work in CSS
+
+Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.
+
+## CSS vs Shader: When to Use Which
+
+Most compositions should use **CSS/GSAP transitions** (the other categories above). They're simpler, lighter, and handle most needs. Use **shader transitions** only when you need an effect that CSS can't achieve:
+
+| Use CSS/GSAP when                              | Use Shader when                                 |
+| ---------------------------------------------- | ----------------------------------------------- |
+| Opacity, transform, clip-path, filter effects  | Per-pixel noise dissolves, domain warping       |
+| Simple crossfades, wipes, slides               | Both scenes actively morph into each other      |
+| No images/video in scenes (text + shapes only) | Live video needs to play through the transition |
+| Quick to set up, no boilerplate                | Willing to add WebGL setup layer (~200 lines)   |
+
+Shader transitions require setup boilerplate (canvas, scene capture, WebGL init). Read [transitions/shader-setup.md](transitions/shader-setup.md) for the complete code. The fragment shaders themselves are in the Shader section of [transitions/catalog.md](transitions/catalog.md).
+
+## Visual Pattern Warning
+
+Avoid transitions that create visible repeating geometric patterns — grids of tiles, hexagonal cells, uniform dot arrays, evenly-spaced blob circles. These look cheap and artificial regardless of the math behind them. Organic noise (FBM, domain warping) is good because it's irregular. Geometric repetition is bad because the eye instantly sees the grid.

package/dist/skills/hyperframes/references/tts.md

@@ -0,0 +1,56 @@
+# Text-to-Speech
+
+Generate speech audio locally using Kokoro-82M (no API key, runs on CPU).
+
+## Voice Selection
+
+Match voice to content. Default is `af_heart`.
+
+| Content type  | Voice                 | Why                        |
+| ------------- | --------------------- | -------------------------- |
+| Product demo  | `af_heart`/`af_nova`  | Warm, professional         |
+| Tutorial      | `am_adam`/`bf_emma`   | Neutral, easy to follow    |
+| Marketing     | `af_sky`/`am_michael` | Energetic or authoritative |
+| Documentation | `bf_emma`/`bm_george` | Clear British English      |
+| Casual        | `af_heart`/`af_sky`   | Approachable, natural      |
+
+Run `npx hyperframes tts --list` for all 54 voices (8 languages).
+
+## Speed Tuning
+
+- **0.7-0.8** — Tutorial, complex content
+- **1.0** — Natural pace (default)
+- **1.1-1.2** — Intros, upbeat content
+- **1.5+** — Rarely appropriate
+
+## Usage
+
+```bash
+npx hyperframes tts "Your script here" --voice af_nova --output narration.wav
+npx hyperframes tts script.txt --voice bf_emma --output narration.wav
+```
+
+In compositions:
+
+```html
+<audio
+  id="narration"
+  data-start="0"
+  data-duration="auto"
+  data-track-index="2"
+  src="narration.wav"
+  data-volume="1"
+></audio>
+```
+
+## TTS + Captions Workflow
+
+```bash
+npx hyperframes tts script.txt --voice af_heart --output narration.wav
+npx hyperframes transcribe narration.wav  # → transcript.json with word-level timestamps
+```
+
+## Requirements
+
+- Python 3.8+ with `kokoro-onnx` and `soundfile`
+- Model downloads on first use (~311 MB + ~27 MB voices, cached in `~/.cache/hyperframes/tts/`)

package/dist/skills/hyperframes-cli/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: hyperframes-cli
+description: HyperFrames CLI tool — hyperframes init, lint, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting or validating compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.
+---
+
+# HyperFrames CLI
+
+Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.
+
+## Workflow
+
+1. **Scaffold** — `npx hyperframes init my-video`
+2. **Write** — author HTML composition (see the `hyperframes` skill)
+3. **Lint** — `npx hyperframes lint`
+4. **Preview** — `npx hyperframes preview`
+5. **Render** — `npx hyperframes render`
+
+Lint before preview — catches missing `data-composition-id`, overlapping tracks, unregistered timelines.
+
+## Scaffolding
+
+```bash
+npx hyperframes init my-video                        # interactive wizard
+npx hyperframes init my-video --template warm-grain   # pick a template
+npx hyperframes init my-video --video clip.mp4        # with video file
+npx hyperframes init my-video --audio track.mp3       # with audio file
+npx hyperframes init my-video --non-interactive       # skip prompts (CI/agents)
+```
+
+Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
+
+`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
+
+## Linting
+
+```bash
+npx hyperframes lint                  # current directory
+npx hyperframes lint ./my-project     # specific project
+npx hyperframes lint --verbose        # info-level findings
+npx hyperframes lint --json           # machine-readable
+```
+
+Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
+
+## Previewing
+
+```bash
+npx hyperframes preview                   # serve current directory
+npx hyperframes preview --port 4567       # custom port (default 3002)
+```
+
+Hot-reloads on file changes. Opens the studio in your browser automatically.
+
+## Rendering
+
+```bash
+npx hyperframes render                                # standard MP4
+npx hyperframes render --output final.mp4             # named output
+npx hyperframes render --quality draft                # fast iteration
+npx hyperframes render --fps 60 --quality high        # final delivery
+npx hyperframes render --format webm                  # transparent WebM
+npx hyperframes render --docker                       # byte-identical
+```
+
+| Flag           | Options               | Default                    | Notes                       |
+| -------------- | --------------------- | -------------------------- | --------------------------- |
+| `--output`     | path                  | renders/name_timestamp.mp4 | Output path                 |
+| `--fps`        | 24, 30, 60            | 30                         | 60fps doubles render time   |
+| `--quality`    | draft, standard, high | standard                   | draft for iterating         |
+| `--format`     | mp4, webm             | mp4                        | WebM supports transparency  |
+| `--workers`    | 1-8 or auto           | auto                       | Each spawns Chrome          |
+| `--docker`     | flag                  | off                        | Reproducible output         |
+| `--gpu`        | flag                  | off                        | GPU-accelerated encoding    |
+| `--strict`     | flag                  | off                        | Fail on lint errors         |
+| `--strict-all` | flag                  | off                        | Fail on errors AND warnings |
+
+**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
+
+## Transcription
+
+```bash
+npx hyperframes transcribe audio.mp3
+npx hyperframes transcribe video.mp4 --model medium.en --language en
+npx hyperframes transcribe subtitles.srt   # import existing
+npx hyperframes transcribe subtitles.vtt
+npx hyperframes transcribe openai-response.json
+```
+
+## Text-to-Speech
+
+```bash
+npx hyperframes tts "Text here" --voice af_nova --output narration.wav
+npx hyperframes tts script.txt --voice bf_emma
+npx hyperframes tts --list  # show all voices
+```
+
+## Troubleshooting
+
+```bash
+npx hyperframes doctor       # check environment (Chrome, FFmpeg, Node, memory)
+npx hyperframes browser      # manage bundled Chrome
+npx hyperframes info         # version and environment details
+npx hyperframes upgrade      # check for updates
+```
+
+Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
+
+## Other
+
+```bash
+npx hyperframes compositions   # list compositions in project
+npx hyperframes docs           # open documentation
+npx hyperframes benchmark .    # benchmark render performance
+```