first-commit

skills/hyperframes/SKILL.md

@@ -0,0 +1,493 @@
+---
+name: hyperframes
+description: Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.
+triggers:
+  - "hyperframes"
+  - "html video"
+  - "video composition"
+  - "interactive video"
+  - "captions"
+  - "tts video"
+  - "kinetic typography"
+od:
+  mode: video
+  surface: video
+  scenario: video
+  preview:
+    type: html
+  design_system:
+    requires: false
+  example_prompt: |
+    A 5-second product reveal: a minimal high-end product on a clean cream
+    surface, soft side light, slow camera push-in, restrained motion, no
+    text overlays.
+---
+
+# HyperFrames
+
+HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync.
+
+## Open Design integration (load-bearing for this surface)
+
+When this skill runs inside Open Design (i.e. `$OD_PROJECT_DIR` is set), the
+output flow is fixed: only the rendered `.mp4` should land in the project
+root. Composition source files (`hyperframes.json`, `meta.json`,
+`index.html`, assets) belong inside a hidden cache directory so they don't
+clutter the user's FileViewer or the chat's "produced files" chips.
+
+**Render workflow inside OD — fast path**:
+
+For most OD requests ("test video", "5s product reveal", "demo clip"),
+do NOT write the composition HTML from scratch. Use HyperFrames'
+built-in scaffold and edit only what the prompt actually changes. The
+"author from scratch" path costs minutes of model output and silent
+chat-tool time; the scaffold path costs seconds.
+
+```bash
+# 1. Pick a hidden cache slot. Dotfile prefix → OD's project file
+#    listing skips it, so the source files never clutter the chat.
+COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
+COMP="$OD_PROJECT_DIR/$COMP_REL"
+
+# 2. Get an immediately-renderable scaffold (hyperframes.json,
+#    meta.json, index.html with GSAP CDN + window.__timelines.main
+#    already registered). This runs in your shell — pure file copy,
+#    no Chrome, no network beyond the npx cache.
+npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
+
+# 3. Edit ONLY $COMP/index.html — change `data-duration` on the root
+#    if you need a non-default length, swap the placeholder palette
+#    in <style>, add 1–3 clip <div>s for text/imagery, and append the
+#    matching GSAP tweens inside the existing
+#    `window.__timelines["main"] = gsap.timeline({paused:true})` block.
+#    Keep edits minimal; the scaffold is already valid HF.
+
+# 4. Dispatch render through the OD daemon. Do NOT run `npx hyperframes
+#    render` from this shell — the daemon runs it for you in an
+#    unsandboxed process. (Many agent CLIs, Claude Code in particular,
+#    wrap Bash in macOS sandbox-exec under which puppeteer's Chrome
+#    subprocess hangs partway through frame capture. The daemon process
+#    is unsandboxed, so renders complete reliably.)
+#
+#    The dispatcher returns within ~1s with a {taskId}; drive the
+#    render to completion by looping `od media wait <taskId>` calls.
+#    Each call long-polls up to 25s (well under your shell tool's
+#    default 30s cap) and exits 0/2/5 to signal done/running/failed.
+out=$(node "$OD_BIN" media generate \
+  --project "$OD_PROJECT_ID" \
+  --surface video \
+  --model hyperframes-html \
+  --output "<descriptive-name>.mp4" \
+  --composition-dir "$COMP_REL")
+ec=$?
+task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
+since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
+while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
+  out=$(node "$OD_BIN" media wait "$task_id" --since "$since")
+  ec=$?
+  since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
+done
+[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
+```
+
+Each `generate` and each `wait` call lasts at most ~25s, so the agent
+shell tool's default ~30s cap never fires. Progress lines from HF
+(`Capturing frame N/M`) stream to stderr live throughout the loop.
+When the render finishes, the last stdout line is
+`{"file": { "name": "<output>", "size": …, "kind": "video", … }}` —
+quote `file.name` in your reply so the user knows what was produced.
+
+**Skip the Visual Identity Gate inside OD.** The HARD-GATE section
+below (under "Approach") tells you to read DESIGN.md / visual-style.md
+or stop and ask 3 mood questions before writing any composition. That
+gate is for standalone HF projects. **OD projects already have their
+own design-system layer** — the user picked their visual direction at
+project creation time. For an OD test render, default to: dark canvas
+(#0b0b0f), one warm accent (#ffb76b), one cool accent (#7da4ff),
+restrained motion. Only ask for stylistic input if the user's prompt
+is too vague to even pick a subject (very rare).
+
+When to skip the scaffold and write from scratch: only when the user
+explicitly asks for something the blank template clearly can't host
+(e.g. multi-composition timelines, audio-reactive overlays, captions
+synced to a TTS track they've already generated). For everything else,
+init + edit is the default path.
+
+The lighter HF subcommands you CAN still run from your own shell
+(they don't need to spawn Chrome):
+
+- `npx hyperframes lint "$COMP"` — validate composition before dispatch
+- `npx hyperframes transcribe <audio>` — generate captions
+- `npx hyperframes tts <text>` — generate narration
+
+Reserve the daemon dispatch for `render`/`inspect`/`preview` (anything
+Chrome-bound).
+
+**Do NOT** call `od media generate --model hyperframes-html` — that
+dispatcher path returns a 400 (`AGENT_RENDERED`) on purpose. HyperFrames
+is rendered by you directly via npx.
+
+**Do NOT** drop `hyperframes.json` / `meta.json` / `index.html` in the
+project root; OD's file listing scans recursively and the user would see
+three unrelated files appear in the chat.
+
+For CLI options beyond `render` (lint, preview, transcribe, tts, inspect,
+benchmark) call them directly from your shell tool when the task warrants
+it (e.g., generate TTS audio into the cache before referencing it from
+the composition).
+
+## Approach
+
+Before writing HTML, think at a high level:
+
+1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.
+2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).
+3. **Timing** — which clips drive the duration, where do transitions land, what's the pacing.
+4. **Layout** — build the end-state first. See "Layout Before Animation" below.
+5. **Animate** — then add motion using the rules below.
+
+For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
+
+### Visual Identity Gate
+
+<HARD-GATE>
+Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors.
+
+Check in this order:
+
+1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints.
+2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.)
+3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns).
+4. **None of the above?** → Ask 3 questions before writing any HTML:
+   - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm)
+   - Light or dark canvas?
+   - Any specific brand colors, fonts, or visual references?
+     Then generate a minimal DESIGN.md from the answers.
+
+Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step.
+</HARD-GATE>
+
+For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like.
+
+## Layout Before Animation
+
+Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet.
+
+**Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion.
+
+### The process
+
+1. **Identify the hero frame** for each scene — the moment when the most elements are simultaneously visible. This is the layout you build.
+2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward — NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only.
+3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there.
+4. **Add exits with `gsap.to()`** — animate TO offscreen/invisible FROM the CSS position.
+
+### Example
+
+```css
+/* scene-content fills the scene, padding positions content */
+.scene-content {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  padding: 120px 160px;
+  gap: 24px;
+  box-sizing: border-box;
+}
+.title {
+  font-size: 120px;
+}
+.subtitle {
+  font-size: 42px;
+}
+/* Container fills any scene size (1920x1080, 1080x1920, etc).
+   Padding positions content. Flex + gap handles spacing. */
+```
+
+**WRONG — hardcoded dimensions and absolute positioning:**
+
+```css
+.scene-content {
+  position: absolute;
+  top: 200px;
+  left: 160px;
+  width: 1920px;
+  height: 1080px;
+  display: flex; /* ... */
+}
+```
+
+```js
+// Step 3: Animate INTO those positions
+tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
+tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
+tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
+
+// Step 4: Animate OUT from those positions
+tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
+tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
+tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
+```
+
+### When elements share space across time
+
+If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist — but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error.
+
+### What counts as intentional overlap
+
+Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap — two headlines landing on top of each other, a stat covering a label, content bleeding off-frame.
+
+## Data Attributes
+
+### All Clips
+
+| Attribute          | Required                          | Values                                                 |
+| ------------------ | --------------------------------- | ------------------------------------------------------ |
+| `id`               | Yes                               | Unique identifier                                      |
+| `data-start`       | Yes                               | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) |
+| `data-duration`    | Required for img/div/compositions | Seconds. Video/audio defaults to media duration.       |
+| `data-track-index` | Yes                               | Integer. Same-track clips cannot overlap.              |
+| `data-media-start` | No                                | Trim offset into source (seconds)                      |
+| `data-volume`      | No                                | 0-1 (default 1)                                        |
+
+`data-track-index` does **not** affect visual layering — use CSS `z-index`.
+
+### Composition Clips
+
+| Attribute                    | Required | Values                                       |
+| ---------------------------- | -------- | -------------------------------------------- |
+| `data-composition-id`        | Yes      | Unique composition ID                        |
+| `data-start`                 | Yes      | Start time (root composition: use `"0"`)     |
+| `data-duration`              | Yes      | Takes precedence over GSAP timeline duration |
+| `data-width` / `data-height` | Yes      | Pixel dimensions (1920x1080 or 1080x1920)    |
+| `data-composition-src`       | No       | Path to external HTML file                   |
+
+## Composition Structure
+
+Sub-compositions loaded via `data-composition-src` use a `<template>` wrapper. **Standalone compositions (the main index.html) do NOT use `<template>`** — they put the `data-composition-id` div directly in `<body>`. Using `<template>` on a standalone file hides all content from the browser and breaks rendering.
+
+Sub-composition structure:
+
+```html
+<template id="my-comp-template">
+  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
+    <!-- content -->
+    <style>
+      [data-composition-id="my-comp"] {
+        /* scoped styles */
+      }
+    </style>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      // tweens...
+      window.__timelines["my-comp"] = tl;
+    </script>
+  </div>
+</template>
+```
+
+Load in root: `<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>`
+
+## Video and Audio
+
+Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
+
+```html
+<video
+  id="el-v"
+  data-start="0"
+  data-duration="30"
+  data-track-index="0"
+  src="video.mp4"
+  muted
+  playsinline
+></video>
+<audio
+  id="el-a"
+  data-start="0"
+  data-duration="30"
+  data-track-index="2"
+  src="video.mp4"
+  data-volume="1"
+></audio>
+```
+
+## Timeline Contract
+
+- All timelines start `{ paused: true }` — the player controls playback
+- Register every timeline: `window.__timelines["<composition-id>"] = tl`
+- Framework auto-nests sub-timelines — do NOT manually add them
+- Duration comes from `data-duration`, not from GSAP timeline length
+- Never create empty tweens to set duration
+
+## Rules (Non-Negotiable)
+
+**Deterministic:** No `Math.random()`, `Date.now()`, or time-based logic. Use a seeded PRNG if you need pseudo-random values (e.g. mulberry32).
+
+**GSAP:** Only animate visual properties (`opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms). Do NOT animate `visibility`, `display`, or call `video.play()`/`audio.play()`.
+
+**Animation conflicts:** Never animate the same property on the same element from multiple timelines simultaneously.
+
+**No `repeat: -1`:** Infinite-repeat timelines break the capture engine. Calculate the exact repeat count from composition duration: `repeat: Math.ceil(duration / cycleDuration) - 1`.
+
+**Synchronous timeline construction:** Never build timelines inside `async`/`await`, `setTimeout`, or Promises. The capture engine reads `window.__timelines` synchronously after page load. Fonts are embedded by the compiler, so they're available immediately — no need to wait for font loading.
+
+**Never do:**
+
+1. Forget `window.__timelines` registration
+2. Use video for audio — always muted video + separate `<audio>`
+3. Nest video inside a timed div — use a non-timed wrapper
+4. Use `data-layer` (use `data-track-index`) or `data-end` (use `data-duration`)
+5. Animate video element dimensions — animate a wrapper div
+6. Call play/pause/seek on media — framework owns playback
+7. Create a top-level container without `data-composition-id`
+8. Use `repeat: -1` on any timeline or tween — always finite repeats
+9. Build timelines asynchronously (inside `async`, `setTimeout`, `Promise`)
+10. Use `gsap.set()` on clip elements from later scenes — they don't exist in the DOM at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline at or after the clip's `data-start` time instead.
+11. Use `<br>` in content text — forced line breaks don't account for actual rendered font width. Text that wraps naturally + a `<br>` produces an extra unwanted break, causing overlap. Let text wrap via `max-width` instead. Exception: short display titles where each word is deliberately on its own line (e.g., "THE\nIMMORTAL\nGAME" at 130px).
+
+## Scene Transitions (Non-Negotiable)
+
+Every multi-scene composition MUST follow ALL of these rules. Violating any one of them is a broken composition.
+
+1. **ALWAYS use transitions between scenes.** No jump cuts. No exceptions.
+2. **ALWAYS use entrance animations on every scene.** Every element animates IN via `gsap.from()`. No element may appear fully-formed. If a scene has 5 elements, it needs 5 entrance tweens.
+3. **NEVER use exit animations** except on the final scene. This means: NO `gsap.to()` that animates opacity to 0, y offscreen, scale to 0, or any other "out" animation before a transition fires. The transition IS the exit. The outgoing scene's content MUST be fully visible at the moment the transition starts.
+4. **Final scene only:** The last scene may fade elements out (e.g., fade to black). This is the ONLY scene where `gsap.to(..., { opacity: 0 })` is allowed.
+
+**WRONG — exit animation before transition:**
+
+```js
+// BANNED — this empties the scene before the transition can use it
+tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
+tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
+// transition fires on empty frame
+```
+
+**RIGHT — entrance only, transition handles exit:**
+
+```js
+// Scene 1 entrance animations
+tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
+tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
+// NO exit tweens — transition at 7.2s handles the scene change
+// Scene 2 entrance animations
+tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
+```
+
+## Animation Guardrails
+
+- Offset first animation 0.1-0.3s (not t=0)
+- Vary eases across entrance tweens — use at least 3 different eases per scene
+- Don't repeat an entrance pattern within a scene
+- Avoid full-screen linear gradients on dark backgrounds (H.264 banding — use radial or solid + localized glow)
+- 60px+ headlines, 20px+ body, 16px+ data labels for rendered video
+- `font-variant-numeric: tabular-nums` on number columns
+
+When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults.
+
+## Typography and Assets
+
+- **Fonts:** Just write the `font-family` you want in CSS — the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns.
+- Add `crossorigin="anonymous"` to external media
+- For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`
+- All files live at the project root alongside `index.html`; sub-compositions use `../`
+
+## Editing Existing Compositions
+
+- Read the full composition first — match existing fonts, colors, animation patterns
+- Only change what was requested
+- Preserve timing of unrelated clips
+
+## Output Checklist
+
+- [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass
+- [ ] `npx hyperframes inspect` passes, or every reported overflow is intentionally marked
+- [ ] Contrast warnings addressed (see Quality Checks below)
+- [ ] Layout issues addressed (see Quality Checks below)
+- [ ] Animation choreography verified (see Quality Checks below)
+
+## Quality Checks
+
+### Visual Inspect
+
+`hyperframes inspect` runs the composition in headless Chrome, seeks through the timeline, and maps visual layout issues with timestamps, selectors, bounding boxes, and fix hints. Run it after `lint` and `validate`:
+
+```bash
+npx hyperframes inspect
+npx hyperframes inspect --json
+```
+
+Failures usually mean text is spilling out of a bubble/card, a fixed-size label is clipping dynamic copy, or text has moved off the canvas. Fix by increasing container size or padding, reducing font size or letter spacing, adding a real `max-width` so text wraps inside the container, or using `window.__hyperframes.fitTextFontSize(...)` for dynamic copy.
+
+Use `--samples 15` for dense videos and `--at 1.5,4,7.25` for specific hero frames. Repeated static issues are collapsed by default to avoid flooding agent context. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.
+
+`hyperframes layout` is the compatibility alias for the same check.
+
+### Contrast
+
+`hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings:
+
+```
+⚠ WCAG AA contrast warnings (3):
+  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)
+```
+
+If warnings appear:
+
+- On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold)
+- On light backgrounds: darken it
+- Stay within the palette family — don't invent a new color, adjust the existing one
+- Re-run `hyperframes validate` until clean
+
+Use `--no-contrast` to skip if iterating rapidly and you'll check later.
+
+### Animation Map
+
+After authoring animations, run the animation map to verify choreography:
+
+```bash
+node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
+  --out <composition-dir>/.hyperframes/anim-map
+```
+
+Outputs a single `animation-map.json` with:
+
+- **Per-tween summaries**: `"#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"`
+- **ASCII timeline**: Gantt chart of all tweens across the composition duration
+- **Stagger detection**: reports actual intervals (`"3 elements stagger at 120ms"`)
+- **Dead zones**: periods over 1s with no animation — intentional hold or missing entrance?
+- **Element lifecycles**: first/last animation time, final visibility
+- **Scene snapshots**: visible element state at 5 key timestamps
+- **Flags**: `offscreen`, `collision`, `invisible`, `paced-fast` (under 0.2s), `paced-slow` (over 2s)
+
+Read the JSON. Scan summaries for anything unexpected. Check every flag — fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.
+
+Skip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.
+
+---
+
+## References (loaded on demand)
+
+- **[references/captions.md](references/captions.md)** — Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing.
+- **[references/tts.md](references/tts.md)** — Text-to-speech with Kokoro-82M. Voice selection, speed tuning, TTS+captions workflow. Read when generating narration or voiceover.
+- **[references/audio-reactive.md](references/audio-reactive.md)** — Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound.
+- **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.
+- **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text.
+- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations.
+- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md.
+- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no style is specified.
+- **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns.
+- **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns.
+- **[references/transcript-guide.md](references/transcript-guide.md)** — Transcription commands, whisper models, external APIs, troubleshooting.
+- **[references/dynamic-techniques.md](references/dynamic-techniques.md)** — Dynamic caption animation techniques (karaoke, clip-path, slam, scatter, elastic, 3D).
+
+- **[references/transitions.md](references/transitions.md)** — Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, CSS vs WebGL guidance. **Always read for multi-scene compositions** — scenes without transitions feel like jump cuts.
+  - [transitions/catalog.md](references/transitions/catalog.md) — Hard rules, scene template, and routing to per-type implementation code.
+  - Shader transitions are in `@hyperframes/shader-transitions` (`packages/shader-transitions/`) — read package source, not skill files.
+
+GSAP patterns and effects are in the `/gsap` skill.

skills/hyperframes/data-in-motion.md

@@ -0,0 +1,19 @@
+# Data in Motion
+
+Light guidance for data and stats in video compositions. The [house style](./house-style.md) handles aesthetics — this just addresses data-specific pitfalls.
+
+## Visual Continuity
+
+When successive stats belong to the same concept (Q1 → Q2 → Q3 → Q4, or three metrics for the same product), keep them in the same visual space with the same aesthetic. Only the VALUE changes. An aesthetic change should signal a new concept, not just a new number.
+
+## Numbers Need Visual Weight
+
+A number on its own floats in empty space. Pair every metric with a visual element that gives it presence — a proportional fill bar, a background color shift, a shape that represents the value, a progress ring. The visual doesn't need to be a chart — it just needs to fill the frame and make the data feel tangible rather than just text on a background.
+
+## Avoid Web Patterns
+
+- **No pie charts** — hard to compare, looks like PowerPoint
+- **No multi-axis charts** — viewer can't study intersections in a 3-second window
+- **No 6-panel dashboards** — 2-3 related metrics side-by-side is fine, 6+ is a web pattern
+- **No gridlines, tick marks, or legends** — visual noise that adds nothing in motion
+- **No chart library output** — build with GSAP + SVG/CSS, not D3 or Chart.js

skills/hyperframes/house-style.md

@@ -0,0 +1,71 @@
+# House Style
+
+Creative direction for compositions when no `visual-style.md` is provided. These are starting points — override anything that doesn't serve the content.
+
+## Before Writing HTML
+
+1. **Interpret the prompt.** Generate real content. A recipe lists real ingredients. A HUD has real readouts.
+2. **Pick a palette.** Light or dark? Declare bg, fg, accent before writing code.
+3. **Pick typefaces.** Run the font discovery script in [references/typography.md](references/typography.md) — or pick a font you already know that fits the theme. The script broadens your options; it's not the only source.
+
+## Lazy Defaults to Question
+
+These patterns are AI design tells — the first thing every LLM reaches for. If you're about to use one, pause and ask: is this a deliberate choice for THIS content, or am I defaulting?
+
+- Gradient text (`background-clip: text` + gradient)
+- Left-edge accent stripes on cards/callouts
+- Cyan-on-dark / purple-to-blue gradients / neon accents
+- Pure `#000` or `#fff` (tint toward your accent hue instead)
+- Identical card grids (same-size cards repeated)
+- Everything centered with equal weight (lead the eye somewhere)
+- Banned fonts (see [references/typography.md](references/typography.md) for full list)
+
+If the content genuinely calls for one of these — centered layout for a solemn closing, cards for a real product UI mockup, a banned font because it's the perfect thematic match — use it. The goal is intentionality, not avoidance.
+
+## Color
+
+- Match light/dark to content: food, wellness, kids → light. Tech, cinema, finance → dark.
+- One accent hue. Same background across all scenes.
+- Tint neutrals toward your accent (even subtle warmth/coolness beats dead gray).
+- **Contrast:** enforced by `hyperframes validate` (WCAG AA). Text must be readable with decoratives removed.
+- Declare palette up front. Don't invent colors per-element.
+
+## Background Layer
+
+Every scene needs visual depth — persistent decorative elements that stay visible while content animates in. Without these, scenes feel empty during entrance staggering.
+
+Ideas (mix and match, 2-5 per scene):
+
+- Radial glows (accent-tinted, low opacity, breathing scale)
+- Ghost text (theme words at 3-8% opacity, very large, slow drift)
+- Accent lines (hairline rules, subtle pulse)
+- Grain/noise overlay, geometric shapes, grid patterns
+- Thematic decoratives (orbit rings for space, vinyl grooves for music, grid lines for data)
+
+All decoratives should have slow ambient GSAP animation — breathing, drift, pulse. Static decoratives feel dead.
+
+## Motion
+
+See [references/motion-principles.md](references/motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries.
+
+## Typography
+
+See [references/typography.md](references/typography.md) for full rules. Quick: 700-900 headlines / 300-400 body, serif + sans (not two sans), 60px+ headlines / 20px+ body.
+
+## Palettes
+
+Declare one background, one foreground, one accent before writing HTML.
+
+| Category          | Use for                                       | File                                                       |
+| ----------------- | --------------------------------------------- | ---------------------------------------------------------- |
+| Bold / Energetic  | Product launches, social media, announcements | [palettes/bold-energetic.md](palettes/bold-energetic.md)   |
+| Warm / Editorial  | Storytelling, documentaries, case studies     | [palettes/warm-editorial.md](palettes/warm-editorial.md)   |
+| Dark / Premium    | Tech, finance, luxury, cinematic              | [palettes/dark-premium.md](palettes/dark-premium.md)       |
+| Clean / Corporate | Explainers, tutorials, presentations          | [palettes/clean-corporate.md](palettes/clean-corporate.md) |
+| Nature / Earth    | Sustainability, outdoor, organic              | [palettes/nature-earth.md](palettes/nature-earth.md)       |
+| Neon / Electric   | Gaming, tech, nightlife                       | [palettes/neon-electric.md](palettes/neon-electric.md)     |
+| Pastel / Soft     | Fashion, beauty, lifestyle, wellness          | [palettes/pastel-soft.md](palettes/pastel-soft.md)         |
+| Jewel / Rich      | Luxury, events, sophisticated                 | [palettes/jewel-rich.md](palettes/jewel-rich.md)           |
+| Monochrome        | Dramatic, typography-focused                  | [palettes/monochrome.md](palettes/monochrome.md)           |
+
+Or derive from OKLCH — pick a hue, build bg/fg/accent at different lightnesses, tint everything toward that hue.

skills/hyperframes/palettes/bold-energetic.md

@@ -0,0 +1,14 @@
+# Bold / Energetic
+
+Product launches, social media, announcements, high-energy content.
+
+```
+#FFBE0B #FB5607 #FF006E #8338EC #3A86FF
+#F72585 #7209B7 #3A0CA3 #4361EE #4CC9F0
+#EF476F #FFD166 #06D6A0 #118AB2 #073B4C
+#FF595E #FFCA3A #8AC926 #1982C4 #6A4C93
+#9B5DE5 #F15BB5 #FEE440 #00BBF9 #00F5D4
+#390099 #9E0059 #FF0054 #FF5400 #FFBD00
+#3D348B #7678ED #F7B801 #F18701 #F35B04
+#FFBC42 #D81159 #8F2D56 #218380 #73D2DE
+```

skills/hyperframes/palettes/clean-corporate.md

@@ -0,0 +1,14 @@
+# Clean / Corporate
+
+Explainers, tutorials, presentations, professional content.
+
+```
+#FFFCF2 #CCC5B9 #403D39 #252422 #EB5E28
+#22223B #4A4E69 #9A8C98 #C9ADA7 #F2E9E4
+#3D5A80 #98C1D9 #E0FBFC #EE6C4D #293241
+#2B2D42 #8D99AE #EDF2F4 #EF233C #D90429
+#353535 #3C6E71 #FFFFFF #D9D9D9 #284B63
+#E7ECEF #274C77 #6096BA #A3CEF1 #8B8C89
+#CFDBD5 #E8EDDF #F5CB5C #242423 #333533
+#2F6690 #3A7CA5 #D9DCD6 #16425B #81C3D7
+```

skills/hyperframes/palettes/dark-premium.md

@@ -0,0 +1,14 @@
+# Dark / Premium
+
+Tech, finance, luxury, cinematic content.
+
+```
+#000000 #14213D #FCA311 #E5E5E5 #FFFFFF
+#000814 #001D3D #003566 #FFC300 #FFD60A
+#0D1B2A #1B263B #415A77 #778DA9 #E0E1DD
+#0D1321 #1D2D44 #3E5C76 #748CAB #F0EBD8
+#011627 #FDFFFC #2EC4B6 #E71D36 #FF9F1C
+#0B090A #161A1D #660708 #A4161A #E5383B
+#001427 #708D81 #F4D58D #BF0603 #8D0801
+#001524 #15616D #FFECD1 #FF7D00 #78290F
+```

skills/hyperframes/palettes/jewel-rich.md

@@ -0,0 +1,14 @@
+# Jewel / Rich
+
+Luxury, events, sophisticated, high-end content.
+
+```
+#5F0F40 #9A031E #FB8B24 #E36414 #0F4C5C
+#780000 #C1121F #FDF0D5 #003049 #669BBC
+#10002B #240046 #3C096C #5A189A #7B2CBF
+#355070 #6D597A #B56576 #E56B6F #EAAC8B
+#6F1D1B #BB9457 #432818 #99582A #FFE6A7
+#231942 #5E548E #9F86C0 #BE95C4 #E0B1CB
+#461220 #8C2F39 #B23A48 #FCB9B2 #FED0BB
+#780116 #F7B538 #DB7C26 #D8572A #C32F27
+```

skills/hyperframes/palettes/monochrome.md

@@ -0,0 +1,14 @@
+# Monochrome
+
+Dramatic, typography-focused, serious content.
+
+```
+#F8F9FA #E9ECEF #DEE2E6 #CED4DA #ADB5BD #6C757D #495057 #343A40 #212529
+#0466C8 #0353A4 #023E7D #002855 #001233
+#012A4A #013A63 #01497C #2A6F97 #468FAF #89C2D9
+#582F0E #7F4F24 #936639 #A68A64 #C2C5AA
+#463F3A #8A817C #BCB8B1 #F4F3EE #E0AFA0
+#03071E #370617 #6A040F #9D0208 #DC2F02 #F48C06 #FFBA08
+#590D22 #800F2F #A4133C #FF4D6D #FF8FA3 #FFCCD5
+#220901 #621708 #941B0C #BC3908 #F6AA1C
+```

skills/hyperframes/palettes/nature-earth.md

@@ -0,0 +1,14 @@
+# Nature / Earth
+
+Sustainability, outdoor, organic, wellness content.
+
+```
+#606C38 #283618 #FEFAE0 #DDA15E #BC6C25
+#DAD7CD #A3B18A #588157 #3A5A40 #344E41
+#386641 #6A994E #A7C957 #F2E8CF #BC4749
+#CAD2C5 #84A98C #52796F #354F52 #2F3E46
+#F0EAD2 #DDE5B6 #ADC178 #A98467 #6C584C
+#132A13 #31572C #4F772D #90A955 #ECF39E
+#6B9080 #A4C3B2 #CCE3DE #EAF4F4 #F6FFF8
+#233D4D #FE7F2D #FCCA46 #A1C181 #619B8A
+```

skills/hyperframes/palettes/neon-electric.md

@@ -0,0 +1,14 @@
+# Neon / Electric
+
+Gaming, tech, nightlife, Gen Z content.
+
+```
+#F72585 #B5179E #7209B7 #560BAD #3A0CA3
+#70D6FF #FF70A6 #FF9770 #FFD670 #E9FF70
+#7400B8 #6930C3 #5E60CE #5390D9 #48BFE3
+#0B132B #1C2541 #3A506B #5BC0BE #6FFFE9
+#540D6E #EE4266 #FFD23F #3BCEAC #0EAD69
+#2D00F7 #6A00F4 #8900F2 #A100F2 #F20089
+#FF6D00 #FF7900 #FF8500 #FF9100 #240046
+#BBFBFF #8DD8FF #4E71FF #5409DA
+```

skills/hyperframes/palettes/pastel-soft.md

@@ -0,0 +1,14 @@
+# Pastel / Soft
+
+Fashion, beauty, lifestyle, wellness content.
+
+```
+#CDB4DB #FFC8DD #FFAFCC #BDE0FE #A2D2FF
+#CCD5AE #E9EDC9 #FEFAE0 #FAEDCD #D4A373
+#FFD6FF #E7C6FF #C8B6FF #B8C0FF #BBD0FF
+#FFA69E #FAF3DD #B8F2E6 #AED9E0 #5E6472
+#EDAFB8 #F7E1D7 #DEDBD2 #B0C4B1 #4A5759
+#555B6E #89B0AE #BEE3DB #FAF9F9 #FFD6BA
+#006D77 #83C5BE #EDF6F9 #FFDDD2 #E29578
+#0081A7 #00AFB9 #FDFCDC #FED9B7 #F07167
+```

skills/hyperframes/palettes/warm-editorial.md

@@ -0,0 +1,14 @@
+# Warm / Editorial
+
+Storytelling, documentaries, case studies, narrative content.
+
+```
+#264653 #2A9D8F #E9C46A #F4A261 #E76F51
+#335C67 #FFF3B0 #E09F3E #9E2A2B #540B0E
+#F4F1DE #E07A5F #3D405B #81B29A #F2CC8F
+#F6BD60 #F7EDE2 #F5CAC3 #84A59D #F28482
+#003049 #D62828 #F77F00 #FCBF49 #EAE2B7
+#588B8B #FFFFFF #FFD5C2 #F28F3B #C8553D
+#283D3B #197278 #EDDDD4 #C44536 #772E25
+#0D3B66 #FAF0CA #F4D35E #EE964B #F95738
+```

skills/hyperframes/patterns.md

@@ -0,0 +1,118 @@
+# Composition Patterns
+
+## Picture-in-Picture (Video in a Frame)
+
+Animate a wrapper div for position/size. The video fills the wrapper. The wrapper has NO data attributes.
+
+```html
+<div
+  id="pip-frame"
+  style="position:absolute;top:0;left:0;width:1920px;height:1080px;z-index:50;overflow:hidden;"
+>
+  <video
+    id="el-video"
+    data-start="0"
+    data-duration="60"
+    data-track-index="0"
+    src="talking-head.mp4"
+    muted
+    playsinline
+  ></video>
+</div>
+```
+
+```js
+tl.to(
+  "#pip-frame",
+  { top: 700, left: 1360, width: 500, height: 280, borderRadius: 16, duration: 1 },
+  10,
+);
+tl.to("#pip-frame", { left: 40, duration: 0.6 }, 30);
+```
+
+## Title Card with Fade
+
+```html
+<div
+  id="title-card"
+  data-start="0"
+  data-duration="5"
+  data-track-index="5"
+  style="display:flex;align-items:center;justify-content:center;background:#111;z-index:60;"
+>
+  <h1 style="font-size:64px;color:#fff;opacity:0;">My Video Title</h1>
+</div>
+```
+
+```js
+tl.to("#title-card h1", { opacity: 1, duration: 0.6 }, 0.3);
+tl.to("#title-card", { opacity: 0, duration: 0.5 }, 4);
+```
+
+## Slide Show with Section Headers
+
+Use separate elements on the same track, each with its own time range. Slides auto-mount/unmount based on `data-start`/`data-duration`.
+
+```html
+<div class="slide" data-start="0" data-duration="30" data-track-index="3">...</div>
+<div class="slide" data-start="30" data-duration="25" data-track-index="3">...</div>
+<div class="slide" data-start="55" data-duration="20" data-track-index="3">...</div>
+```
+
+## Top-Level Composition Example
+
+```html
+<div
+  id="comp-1"
+  data-composition-id="my-video"
+  data-start="0"
+  data-duration="60"
+  data-width="1920"
+  data-height="1080"
+>
+  <!-- Primitive clips -->
+  <video
+    id="el-1"
+    data-start="0"
+    data-duration="10"
+    data-track-index="0"
+    src="..."
+    muted
+    playsinline
+  ></video>
+  <video
+    id="el-2"
+    data-start="el-1"
+    data-duration="8"
+    data-track-index="0"
+    src="..."
+    muted
+    playsinline
+  ></video>
+  <img id="el-3" data-start="5" data-duration="4" data-track-index="1" src="..." />
+  <audio id="el-4" data-start="0" data-duration="30" data-track-index="2" src="..." />
+
+  <!-- Sub-compositions loaded from files -->
+  <div
+    id="el-5"
+    data-composition-id="intro-anim"
+    data-composition-src="compositions/intro-anim.html"
+    data-start="0"
+    data-track-index="3"
+  ></div>
+
+  <div
+    id="el-6"
+    data-composition-id="captions"
+    data-composition-src="compositions/caption-overlay.html"
+    data-start="0"
+    data-track-index="4"
+  ></div>
+
+  <script>
+    // Just register the timeline — framework auto-nests sub-compositions
+    const tl = gsap.timeline({ paused: true });
+    window.__timelines["my-video"] = tl;
+  </script>
+</div>
+```

skills/hyperframes/references/audio-reactive.md

@@ -0,0 +1,76 @@
+# Audio-Reactive Animation
+
+Drive visuals from music, voice, or sound. Any GSAP-animatable property can respond to pre-extracted audio data.
+
+## Audio Data Format
+
+```js
+var AUDIO_DATA = {
+  fps: 30,
+  totalFrames: 900,
+  frames: [{ bands: [0.82, 0.45, 0.31, ...] }, ...]
+};
+```
+
+- `frames[i].bands[]` — frequency band amplitudes, 0-1. Index 0 = bass, higher = treble.
+- Each band normalized independently across the full track.
+
+## Mapping Audio to Visuals
+
+| Audio signal           | Visual property                   | Effect                     |
+| ---------------------- | --------------------------------- | -------------------------- |
+| Bass (bands[0])        | `scale`                           | Pulse on beat              |
+| Treble (bands[12-14])  | `textShadow`, `boxShadow`         | Glow intensity             |
+| Overall amplitude      | `opacity`, `y`, `backgroundColor` | Breathe, lift, color shift |
+| Mid-range (bands[4-8]) | `borderRadius`, `width`           | Shape morphing             |
+
+Any GSAP-tweenable property works — `clipPath`, `filter`, SVG attributes, CSS custom properties.
+
+## Content, Not Medium
+
+Audio provides **timing and intensity**. The visual vocabulary comes from the narrative.
+
+**Never add:** equalizer bars, spectrum analyzers, waveform displays, musical notes clip art, generic particle systems, rainbow color cycling, strobing white on beats, abstract pulsing orbs.
+
+**Instead:** Let content guide the visual and audio drive its behavior. Bass makes warmth _swell_. Treble sharpens _contrast_. The visual choice comes from "what does this piece feel like?"
+
+## Sampling Pattern
+
+Audio reactivity requires per-frame sampling via a `for` loop with `tl.call()`, not a single tween:
+
+```js
+// ✅ Correct — sample every frame
+for (var f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    (function (frame) {
+      return function () {
+        draw(frame);
+      };
+    })(AUDIO_DATA.frames[f]),
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+
+// ❌ Wrong — single tween, doesn't react to audio
+gsap.to(".el", { scale: 1.2, duration: totalDuration });
+```
+
+Without per-frame sampling, the composition doesn't actually react to audio.
+
+## textShadow Gotcha
+
+`textShadow` on a parent container with semi-transparent children (e.g., inactive caption words at `rgba(255,255,255,0.3)`) renders a visible glow rectangle behind all children. Fix: apply `scale` to the container for beat pulse, but apply `textShadow` to individual active words only.
+
+## Guidelines
+
+- **Subtlety for text** — 3-6% scale variation, soft glow. Heavy pulsing makes text unreadable.
+- **Go bigger on non-text** — backgrounds and shapes can handle 10-30% swings.
+- **Match the energy** — corporate = subtle; music video = dramatic.
+- **Deterministic** — pre-extracted data, no Web Audio API, no runtime analysis.
+
+## Constraints
+
+- All audio data must be pre-extracted (use `extract-audio-data.py` from the gsap skill's scripts/)
+- No `Math.random()` or `Date.now()`
+- Audio reactivity runs on the same GSAP timeline as everything else

skills/hyperframes/references/captions.md

@@ -0,0 +1,132 @@
+# Captions
+
+## Language Rule (Non-Negotiable)
+
+**Never use `.en` models unless the user explicitly states the audio is English.** `.en` models TRANSLATE non-English audio into English instead of transcribing it.
+
+1. User says the language → `--model small --language <code>` (no `.en`)
+2. User says English → `--model small.en`
+3. Language unknown → `--model small` (no `.en`, no `--language`) — auto-detects
+
+---
+
+Analyze spoken content to determine caption style. If user specifies a style, use that. Otherwise, detect tone from the transcript.
+
+## Transcript Source
+
+```json
+[
+  { "text": "Hello", "start": 0.0, "end": 0.5 },
+  { "text": "world.", "start": 0.6, "end": 1.2 }
+]
+```
+
+For transcription commands, whisper models, external APIs, see [transcript-guide.md](transcript-guide.md).
+
+## Style Detection (When No Style Specified)
+
+Read the full transcript before choosing. Four dimensions:
+
+**1. Visual feel** — corporate→clean; energetic→bold; storytelling→elegant; technical→precise; social→playful.
+
+**2. Color palette** — dark+bright for energy; muted for professional; high contrast for clarity; one accent color.
+
+**3. Font mood** — heavy/condensed for impact; clean sans for modern; rounded for friendly; serif for elegance.
+
+**4. Animation character** — scale-pop for punchy; gentle fade for calm; word-by-word for emphasis; typewriter for technical.
+
+## Per-Word Styling
+
+Scan for words deserving distinct treatment:
+
+- **Brand/product names** — larger size, unique color
+- **ALL CAPS** — scale boost, flash, accent color
+- **Numbers/statistics** — bold weight, accent color
+- **Emotional keywords** — exaggerated animation (overshoot, bounce)
+- **Call-to-action** — highlight, underline, color pop
+- **Marker highlight** — for beyond-color emphasis, see [css-patterns.md](css-patterns.md)
+
+## Script-to-Style Mapping
+
+| Tone         | Font mood                | Animation                          | Color                       | Size    |
+| ------------ | ------------------------ | ---------------------------------- | --------------------------- | ------- |
+| Hype/launch  | Heavy condensed, 800-900 | Scale-pop, back.out(1.7), 0.1-0.2s | Bright on dark              | 72-96px |
+| Corporate    | Clean sans, 600-700      | Fade+slide, power3.out, 0.3s       | White/neutral, muted accent | 56-72px |
+| Tutorial     | Mono/clean sans, 500-600 | Typewriter/fade, 0.4-0.5s          | High contrast, minimal      | 48-64px |
+| Storytelling | Serif/elegant, 400-500   | Slow fade, power2.out, 0.5-0.6s    | Warm muted tones            | 44-56px |
+| Social       | Rounded sans, 700-800    | Bounce, elastic.out, word-by-word  | Playful, colored pills      | 56-80px |
+
+## Word Grouping
+
+- **High energy:** 2-3 words. Quick turnover.
+- **Conversational:** 3-5 words. Natural phrases.
+- **Measured/calm:** 4-6 words. Longer groups.
+
+Break on sentence boundaries, 150ms+ pauses, or max word count.
+
+## Positioning
+
+- **Landscape (1920x1080):** Bottom 80-120px, centered
+- **Portrait (1080x1920):** Lower middle ~600-700px from bottom, centered
+- Never cover the subject's face
+- `position: absolute` — never relative
+- One caption group visible at a time
+
+## Text Overflow Prevention
+
+Use `window.__hyperframes.fitTextFontSize()`:
+
+```js
+var result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
+  fontFamily: "Outfit",
+  fontWeight: 900,
+  maxWidth: 1600,
+});
+el.style.fontSize = result.fontSize + "px";
+```
+
+Options: `maxWidth` (1600 landscape, 900 portrait), `baseFontSize` (78), `minFontSize` (42), `fontWeight`, `fontFamily`, `step` (2).
+
+CSS safety nets: `max-width` on container, `overflow: visible` (**not** `hidden` — hidden clips scaled emphasis words and glow effects), `position: absolute`, explicit `height`. When per-word styling uses `scale > 1.0`, compute `maxWidth = safeWidth / maxScale` to leave headroom.
+
+**Container pattern:** Full-width absolute container, centered. Do **not** use `left: 50%; transform: translateX(-50%)` — causes clipping at composition edges.
+
+## Caption Exit Guarantee
+
+Every group **must** have a hard kill after exit animation:
+
+```js
+tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
+tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end); // deterministic kill
+```
+
+Self-lint after building timeline — place **before** `window.__timelines[id] = tl` so it runs at composition init:
+
+```js
+GROUPS.forEach(function (group, gi) {
+  var el = document.getElementById("cg-" + gi);
+  if (!el) return;
+  tl.seek(group.end + 0.01);
+  var computed = window.getComputedStyle(el);
+  if (computed.opacity !== "0" && computed.visibility !== "hidden") {
+    console.warn(
+      "[caption-lint] group " + gi + " still visible at t=" + (group.end + 0.01).toFixed(2) + "s",
+    );
+  }
+});
+tl.seek(0);
+```
+
+## Further References
+
+- [dynamic-techniques.md](dynamic-techniques.md) — karaoke, clip-path reveals, slam words, scatter exits, elastic, 3D rotation
+- [transcript-guide.md](transcript-guide.md) — transcription commands, whisper models, external APIs
+- [css-patterns.md](css-patterns.md) — CSS+GSAP marker highlighting (deterministic, fully seekable)
+
+## Constraints
+
+- Deterministic. No `Math.random()`, no `Date.now()`.
+- Sync to transcript timestamps.
+- One group visible at a time.
+- Every group must have a hard `tl.set` kill at `group.end`.
+- The compiler embeds supported fonts automatically — just declare `font-family` in CSS.

skills/hyperframes/references/css-patterns.md

@@ -0,0 +1,373 @@
+# CSS Patterns for Marker Highlighting
+
+Pure CSS + GSAP implementations of all five MarkerHighlight.js drawing modes. Use these for deterministic rendering in HyperFrames compositions — no external library dependency, full GSAP timeline control.
+
+## Table of Contents
+
+- [1. Highlight Mode](#1-highlight-mode) — Yellow marker sweep behind text
+- [2. Circle Mode](#2-circle-mode) — Hand-drawn ellipse around text
+- [3. Burst Mode](#3-burst-mode) — Radiating lines from text
+- [4. Scribble Mode](#4-scribble-mode) — Chaotic scribble over text
+- [5. Sketchout Mode](#5-sketchout-mode) — Rough rectangle outline
+
+## 1. Highlight Mode
+
+Yellow marker sweep behind text. The most common mode.
+
+```html
+<span class="mh-highlight-wrap">
+  <span class="mh-highlight-bar" id="hl-1"></span>
+  <span class="mh-highlight-text">highlighted text</span>
+</span>
+```
+
+```css
+.mh-highlight-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-highlight-bar {
+  position: absolute;
+  top: 0;
+  left: -6px;
+  right: -6px;
+  bottom: 0;
+  background: #fdd835;
+  opacity: 0.35;
+  transform: scaleX(0);
+  transform-origin: left center;
+  border-radius: 3px;
+  z-index: 0;
+}
+.mh-highlight-text {
+  position: relative;
+  z-index: 1;
+}
+```
+
+```js
+// Sweep in from left
+tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
+
+// Optional: skew for hand-drawn feel
+// gsap.set("#hl-1", { skewX: -2 });
+```
+
+### Multi-line Highlight
+
+Stagger bars across multiple lines:
+
+```js
+tl.to(
+  ".mh-highlight-bar",
+  {
+    scaleX: 1,
+    duration: 0.5,
+    ease: "power2.out",
+    stagger: 0.3,
+  },
+  0.6,
+);
+```
+
+## 2. Circle Mode
+
+Hand-drawn circle around text. Use `border-radius: 50%` with a slight rotation for organic feel.
+
+```html
+<span class="mh-circle-wrap">
+  <span class="mh-circle-text" id="circle-word">IMPORTANT</span>
+  <span class="mh-circle-ring" id="circle-1"></span>
+</span>
+```
+
+```css
+.mh-circle-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-circle-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-circle-ring {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 130%;
+  height: 160%;
+  transform: translate(-50%, -50%) rotate(-3deg) scale(0);
+  border: 3px solid #e53935;
+  border-radius: 50%;
+  pointer-events: none;
+  z-index: 0;
+}
+```
+
+```js
+// Circle scales in with a wobble
+tl.to(
+  "#circle-1",
+  {
+    scale: 1,
+    rotation: -3,
+    duration: 0.6,
+    ease: "back.out(1.7)",
+    transformOrigin: "center center",
+  },
+  0.7,
+);
+```
+
+### Variations
+
+```css
+/* Tighter circle (for short words) */
+.mh-circle-ring.tight {
+  width: 150%;
+  height: 180%;
+}
+
+/* Squared circle (rounded rectangle) */
+.mh-circle-ring.rounded {
+  border-radius: 30%;
+  width: 120%;
+  height: 140%;
+}
+
+/* Ellipse (wider than tall) */
+.mh-circle-ring.ellipse {
+  width: 150%;
+  height: 130%;
+  border-radius: 50%;
+}
+```
+
+## 3. Burst Mode
+
+Radiating lines from text center. Each line is a positioned div rotated to its angle.
+
+```html
+<span class="mh-burst-wrap">
+  <span class="mh-burst-text">WOW</span>
+  <span class="mh-burst-container" id="burst-1">
+    <span class="mh-burst-line" style="--angle: 0deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 30deg; --len: 55px;"></span>
+    <span class="mh-burst-line" style="--angle: 60deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 90deg; --len: 45px;"></span>
+    <span class="mh-burst-line" style="--angle: 120deg; --len: 65px;"></span>
+    <span class="mh-burst-line" style="--angle: 150deg; --len: 75px;"></span>
+    <span class="mh-burst-line" style="--angle: 180deg; --len: 50px;"></span>
+    <span class="mh-burst-line" style="--angle: 210deg; --len: 60px;"></span>
+    <span class="mh-burst-line" style="--angle: 240deg; --len: 80px;"></span>
+    <span class="mh-burst-line" style="--angle: 270deg; --len: 40px;"></span>
+    <span class="mh-burst-line" style="--angle: 300deg; --len: 70px;"></span>
+    <span class="mh-burst-line" style="--angle: 330deg; --len: 55px;"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-burst-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-burst-text {
+  position: relative;
+  z-index: 2;
+}
+.mh-burst-container {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 0;
+  height: 0;
+  z-index: 1;
+}
+.mh-burst-line {
+  position: absolute;
+  display: block;
+  width: 3px;
+  height: var(--len);
+  background: #1e88e5;
+  left: -1.5px;
+  top: calc(-1 * var(--len));
+  transform: rotate(var(--angle));
+  transform-origin: bottom center;
+  opacity: 0;
+}
+```
+
+```js
+// All lines burst outward simultaneously with slight stagger
+tl.fromTo(
+  "#burst-1 .mh-burst-line",
+  { scaleY: 0, opacity: 0 },
+  { scaleY: 1, opacity: 1, duration: 0.4, ease: "power2.out", stagger: 0.03 },
+  0.7,
+);
+```
+
+**Vary line lengths** (40-80px range) for an organic, hand-drawn feel. Equal lengths look mechanical.
+
+## 4. Scribble Mode
+
+Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffset`.
+
+```html
+<span class="mh-scribble-wrap">
+  <span class="mh-scribble-text">underlined text</span>
+  <svg class="mh-scribble-svg" viewBox="0 0 500 24" preserveAspectRatio="none">
+    <path
+      id="scribble-1"
+      d="M0,12 Q31,0 62,12 Q93,24 125,12 Q156,0 187,12 Q218,24 250,12 Q281,0 312,12 Q343,24 375,12 Q406,0 437,12 Q468,24 500,12"
+      fill="none"
+      stroke="#FDD835"
+      stroke-width="3"
+      stroke-linecap="round"
+    />
+  </svg>
+</div>
+```
+
+```css
+.mh-scribble-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-scribble-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-scribble-svg {
+  position: absolute;
+  left: 0;
+  bottom: -6px;
+  width: 100%;
+  height: 24px;
+  z-index: 0;
+}
+```
+
+```js
+// Measure path length and set initial dash state
+var path = document.querySelector("#scribble-1");
+var len = path.getTotalLength();
+gsap.set(path, { strokeDasharray: len, strokeDashoffset: len });
+
+// Draw the line
+tl.to(
+  "#scribble-1",
+  {
+    strokeDashoffset: 0,
+    duration: 0.8,
+    ease: "power1.inOut",
+  },
+  0.7,
+);
+```
+
+### Strikethrough Variant
+
+Position the SVG at `top: 50%; transform: translateY(-50%)` instead of `bottom: -6px`.
+
+### Wavy Path Generator
+
+Scale the path's viewBox width to match text width. The wave pattern `Q x1,y1 x2,y2` alternates between `y=0` and `y=24` for a natural wobble. Adjust the control points for tighter or looser waves:
+
+- **Tight waves**: smaller x-increments (25px per half-wave)
+- **Loose waves**: larger x-increments (50px per half-wave)
+- **Amplitude**: change the y range (0-24 for standard, 0-16 for subtle)
+
+## 5. Sketchout Mode
+
+Cross-hatch lines over de-emphasized text. Multiple angled lines create a "crossed out" effect.
+
+```html
+<span class="mh-sketchout-wrap">
+  <span class="mh-sketchout-text">old price</span>
+  <span class="mh-sketchout-lines" id="sketchout-1">
+    <span class="mh-sketchout-line mh-sketchout-fwd"></span>
+    <span class="mh-sketchout-line mh-sketchout-bwd"></span>
+  </span>
+</span>
+```
+
+```css
+.mh-sketchout-wrap {
+  position: relative;
+  display: inline;
+}
+.mh-sketchout-text {
+  position: relative;
+  z-index: 0;
+}
+.mh-sketchout-lines {
+  position: absolute;
+  top: 0;
+  left: -4px;
+  right: -4px;
+  bottom: 0;
+  overflow: hidden;
+  z-index: 1;
+}
+.mh-sketchout-line {
+  position: absolute;
+  display: block;
+  top: 50%;
+  left: 0;
+  width: 100%;
+  height: 2px;
+  background: #e53935;
+  transform-origin: left center;
+  transform: scaleX(0);
+}
+.mh-sketchout-fwd {
+  transform: scaleX(0) rotate(-12deg);
+}
+.mh-sketchout-bwd {
+  transform: scaleX(0) rotate(12deg);
+}
+```
+
+```js
+// Forward slash draws first
+tl.to(
+  "#sketchout-1 .mh-sketchout-fwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.0,
+);
+
+// Backward slash follows
+tl.to(
+  "#sketchout-1 .mh-sketchout-bwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.15,
+);
+```
+
+## Combining Modes in Captions
+
+Use mode cycling for visual variety across caption groups:
+
+```js
+var MODES = ["highlight", "circle", "burst", "scribble"];
+
+GROUPS.forEach(function (group, gi) {
+  var mode = MODES[gi % MODES.length];
+  // Apply the mode's CSS pattern to emphasis words in this group
+  group.emphasisWords.forEach(function (word) {
+    applyMode(word.el, mode, tl, word.start);
+  });
+});
+```
+
+Cycle every 2-3 groups for high energy, every 3-4 for medium, every 4-5 for low.

skills/hyperframes/references/dynamic-techniques.md

@@ -0,0 +1,90 @@
+# Dynamic Caption Techniques
+
+You are here because SKILL.md told you to read this file before writing animation code. Pick your technique combination from the table below based on the energy level you detected from the transcript, then implement using standard GSAP patterns.
+
+## Technique Selection by Energy
+
+| Energy level | Highlight                             | Exit                | Cycle pattern                             |
+| ------------ | ------------------------------------- | ------------------- | ----------------------------------------- |
+| High         | Karaoke with accent glow + scale pop  | Scatter or drop     | Alternate highlight styles every 2 groups |
+| Medium-high  | Karaoke with color pop                | Scatter or collapse | Alternate every 3 groups                  |
+| Medium       | Karaoke (subtle, white only)          | Fade + slide        | Alternate every 3 groups                  |
+| Medium-low   | Karaoke (minimal scale change)        | Fade                | Single style, vary ease per group         |
+| Low          | Karaoke (warm tones, slow transition) | Collapse            | Alternate every 4 groups                  |
+
+**All energy levels use karaoke highlight as the baseline.** The difference is intensity — high energy gets accent color + glow + 15% scale pop on active words, low energy gets a gentle white shift with 3% scale.
+
+**Emphasis words always break the pattern.** When a word is flagged as emphasis (emotional keyword, ALL CAPS, brand name), give it a stronger animation than surrounding words (larger scale, accent color, overshoot ease). This creates contrast.
+
+**Marker highlight modes add a visual layer on top of karaoke.** For emphasis words that need more than color/scale, add a marker-style effect — highlight sweep, circle, burst, or scribble — using the `/marker-highlight` skill. Match mode to energy: burst for hype, circle for key terms, highlight for standard, scribble for subtle.
+
+## Audio-Reactive Captions (Mandatory for Music)
+
+**If the source audio is music (vocals over instrumentation, beats, any musical content), you MUST extract audio data and add audio-reactive animations.** This is not optional — music without audio reactivity looks disconnected. Even low-energy ballads get subtle bass pulse and treble glow.
+
+No special wiring is needed. The group loop already iterates over every caption group to build entrance, karaoke, and exit tweens. At that point, read the audio data for each group's time range and use it to modulate the group's animation intensity with regular GSAP tweens.
+
+```js
+// Load audio data inline (same pattern as TRANSCRIPT)
+var AUDIO = JSON.parse(audioDataJson); // { fps, totalFrames, frames: [{ bands: [...] }] }
+
+GROUPS.forEach(function (group, gi) {
+  var groupEl = document.getElementById("cg-" + gi);
+  if (!groupEl) return;
+
+  // Read peak energy for this group's time range
+  var startFrame = Math.floor(group.start * AUDIO.fps);
+  var endFrame = Math.min(Math.floor(group.end * AUDIO.fps), AUDIO.totalFrames - 1);
+  var peakBass = 0;
+  var peakTreble = 0;
+  for (var f = startFrame; f <= endFrame; f++) {
+    var frame = AUDIO.frames[f];
+    if (!frame) continue;
+    peakBass = Math.max(peakBass, frame.bands[0] || 0, frame.bands[1] || 0);
+    peakTreble = Math.max(peakTreble, frame.bands[6] || 0, frame.bands[7] || 0);
+  }
+
+  // Modulate entrance — louder groups enter bigger and glowier
+  tl.to(
+    groupEl,
+    {
+      scale: 1 + peakBass * 0.06,
+      textShadow:
+        "0 0 " + Math.round(peakTreble * 12) + "px rgba(255,255,255," + peakTreble * 0.4 + ")",
+      duration: 0.3,
+      ease: "power2.out",
+    },
+    group.start,
+  );
+
+  // Reset at exit so audio-driven values don't persist
+  tl.set(groupEl, { scale: 1, textShadow: "none" }, group.end - 0.15);
+});
+```
+
+This shapes the animation at build time, not playback time — no per-frame callbacks, no `tl.call()` loops, no async fetch timing issues. Loud groups come in with more weight and glow; quiet groups come in soft. The audio data modulates _how much_, the content determines _what_.
+
+Keep audio reactivity subtle — 3-6% scale variation and soft glow. Heavy pulsing makes text unreadable.
+
+To generate the audio data file:
+
+```bash
+python3 skills/gsap-effects/scripts/extract-audio-data.py audio.mp3 --fps 30 --bands 8 -o audio-data.json
+```
+
+## Combining Techniques
+
+Don't use the same highlight animation on every group — cycle through styles using the group index. Don't combine multiple competing animations on the same word at the same timestamp. Vary techniques across groups to match the content's pace changes.
+
+**Marker highlight effects** (from the `/marker-highlight` skill) layer well with karaoke — use karaoke for the word-by-word reveal, then add a marker effect on emphasis words only. For example: karaoke highlights each word in white, but brand names get a yellow highlight sweep and stats get a red circle. Cycle marker modes across groups for visual variety (see the mode-to-energy mapping in the marker-highlight skill).
+
+## Available Tools
+
+These tools are available in the HyperFrames runtime. Use them when they solve a real problem — not every composition needs all of them.
+
+| Tool                | What it does                                                              | Access                                                                                         | When it's useful                                                             |
+| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **pretext**         | Pure-arithmetic text measurement without DOM reflow. 0.0002ms per call.   | `window.__hyperframes.pretext.prepare(text, font)` / `.layout(prepared, maxWidth, lineHeight)` | Per-frame text reflow, shrinkwrap containers, computing layout before render |
+| **fitTextFontSize** | Finds the largest font size that fits text on one line. Built on pretext. | `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`             | Overflow prevention for long phrases, portrait mode, large base sizes        |
+| **audio data**      | Pre-extracted per-frame RMS energy and frequency bands.                   | Extract with `extract-audio-data.py`, load inline or via `fetch("audio-data.json")`            | Audio-reactive visuals — modulate intensity based on the music               |
+| **GSAP**            | Animation timeline with tweens and callbacks.                             | `gsap.to()`, `gsap.set()`, `tl.to()`, `tl.set()`                                               | All caption animation                                                        |

skills/hyperframes/references/motion-principles.md

@@ -0,0 +1,69 @@
+# Motion Principles
+
+## Guardrails
+
+You know these rules but you violate them. Stop.
+
+- **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.
+
+## What You Don't Do Without Being Told
+
+### Easing is emotion, not technique
+
+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 — these are not optional:**
+
+- `.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.
+
+You get this backwards constantly. Ease-in for entrances feels sluggish. Ease-out for exits feels reluctant.
+
+### Speed communicates weight
+
+- 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
+
+### Scene structure: build / breathe / resolve
+
+Every scene has three phases. You dump everything in the build and leave nothing for breathe or resolve.
+
+- **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.
+
+### Transitions are meaning
+
+- **Crossfade** = "this continues"
+- **Hard cut** = "wake up" / disruption
+- **Slow dissolve** = "drift with me"
+
+You crossfade everything. Use hard cuts for disruption and register shifts.
+
+### Choreography is hierarchy
+
+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.
+
+### Asymmetry
+
+Entrances need longer than exits. A card takes 0.4s to appear but 0.25s to disappear.
+
+## Visual Composition
+
+You build for the web. Video frames are not pages.
+
+- **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).

skills/hyperframes/references/transcript-guide.md

@@ -0,0 +1,151 @@
+# Transcript Guide
+
+## How Transcripts Are Generated
+
+`hyperframes transcribe` handles both transcription and format conversion:
+
+```bash
+# Transcribe audio/video (uses whisper.cpp locally, no API key needed)
+npx hyperframes transcribe audio.mp3
+
+# Use a larger model for better accuracy
+npx hyperframes transcribe audio.mp3 --model medium.en
+
+# Filter to English only (skips non-English speech)
+npx hyperframes transcribe audio.mp3 --language en
+
+# Import an existing transcript from another tool
+npx hyperframes transcribe captions.srt
+npx hyperframes transcribe captions.vtt
+npx hyperframes transcribe openai-response.json
+```
+
+## Supported Input Formats
+
+The CLI auto-detects and normalizes these formats:
+
+| Format                | Extension | Source                                                                      | Word-level?       |
+| --------------------- | --------- | --------------------------------------------------------------------------- | ----------------- |
+| whisper.cpp JSON      | `.json`   | `hyperframes init --video`, `hyperframes transcribe`                        | Yes               |
+| OpenAI Whisper API    | `.json`   | `openai.audio.transcriptions.create({ timestamp_granularities: ["word"] })` | Yes               |
+| SRT subtitles         | `.srt`    | Video editors, subtitle tools, YouTube                                      | No (phrase-level) |
+| VTT subtitles         | `.vtt`    | Web players, YouTube, transcription services                                | No (phrase-level) |
+| Normalized word array | `.json`   | Pre-processed by any tool                                                   | Yes               |
+
+**Word-level timestamps produce better captions.** SRT/VTT give phrase-level timing, which works but can't do per-word animation effects.
+
+## Whisper Model Guide
+
+The default model (`small.en`) balances accuracy and speed. For better results, use a larger model:
+
+| Model      | Size   | Speed    | Accuracy  | When to use                           |
+| ---------- | ------ | -------- | --------- | ------------------------------------- |
+| `tiny`     | 75 MB  | Fastest  | Low       | Quick previews, testing pipeline      |
+| `base`     | 142 MB | Fast     | Fair      | Short clips, clear audio              |
+| `small`    | 466 MB | Moderate | Good      | **Default** — good for most content   |
+| `medium`   | 1.5 GB | Slow     | Very good | Important content, noisy audio, music |
+| `large-v3` | 3.1 GB | Slowest  | Best      | Production quality                    |
+
+**Only add `.en` suffix when the user explicitly says the audio is English.** `.en` models are slightly more accurate for English but will TRANSLATE non-English audio instead of transcribing it.
+
+**Critical: `.en` models translate non-English audio into English** — they don't transcribe it. If the audio might not be English, always use a model without the `.en` suffix and pass `--language` to specify the source language. If you're unsure of the language, use `small` (not `small.en`) without `--language` — whisper will auto-detect.
+
+```bash
+# Spanish audio
+npx hyperframes transcribe audio.mp3 --model small --language es
+
+# Unknown language — let whisper auto-detect
+npx hyperframes transcribe audio.mp3 --model small
+```
+
+**Music and vocals over instrumentation**: `small.en` will misidentify lyrics — use `medium.en` as the minimum, or import lyrics manually. Even `medium.en` struggles with heavily produced tracks; for music videos, providing known lyrics as an SRT/VTT and importing with `hyperframes transcribe lyrics.srt` will always beat automated transcription.
+
+## Transcript Quality Check (Mandatory)
+
+After every transcription, **read the transcript and check for quality issues before proceeding.** Bad transcripts produce nonsensical captions. Never skip this step.
+
+### What to look for
+
+| Signal                       | Example                                | Cause                                                                        |
+| ---------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
+| Music note tokens (`♪`, `�`) | `{ "text": "♪" }` or `{ "text": "�" }` | Whisper detected music, not speech                                           |
+| Garbled / nonsense words     | "Do a chin", "Get so gay", "huh"       | Model misheard lyrics or background noise                                    |
+| Long gaps with no words      | 20+ seconds of only `♪` tokens         | Instrumental section — expected, but high ratio means speech is being missed |
+| Repeated filler              | Many "huh", "uh", "oh" entries         | Model is hallucinating on music                                              |
+| Very short word spans        | Words with `end - start < 0.05`        | Unreliable timestamp alignment                                               |
+
+### Automatic retry rules
+
+**If more than 20% of entries are `♪`/`�` tokens, or the transcript contains obvious nonsense words, the transcription failed.** Do not proceed with the bad transcript. Instead:
+
+1. **Retry with `medium.en`** if the original used `small.en` or smaller:
+   ```bash
+   npx hyperframes transcribe audio.mp3 --model medium.en
+   ```
+2. **If `medium.en` also fails** (still >20% music tokens or garbled), tell the user the audio is too noisy for local transcription and suggest:
+   - Providing lyrics manually as an SRT/VTT file
+   - Using an external API (OpenAI or Groq Whisper — see below)
+3. **Always clean the transcript** before building captions — filter out `♪`/`�` tokens and entries where `text` is a single non-word character. Only real words should reach the caption composition.
+
+### Cleaning a transcript
+
+After transcription (even with a good model), strip non-word entries:
+
+```js
+var raw = JSON.parse(transcriptJson);
+var words = raw.filter(function (w) {
+  if (!w.text || w.text.trim().length === 0) return false;
+  if (/^[♪�\u266a\u266b\u266c\u266d\u266e\u266f]+$/.test(w.text)) return false;
+  if (/^(huh|uh|um|ah|oh)$/i.test(w.text) && w.end - w.start < 0.1) return false;
+  return true;
+});
+```
+
+### When to use which model (decision tree)
+
+1. **Is this speech over silence/light background?** → `small.en` is fine
+2. **Is this speech over music, or music with vocals?** → Start with `medium.en`
+3. **Is this a produced music track (vocals + full instrumentation)?** → Start with `medium.en`, expect to need manual lyrics or an external API
+4. **Is this multilingual?** → Use `medium` or `large-v3` (no `.en` suffix)
+
+## Using External Transcription APIs
+
+For the best accuracy, use an external API and import the result:
+
+**OpenAI Whisper API** (recommended for quality):
+
+```bash
+# Generate with word timestamps, then import
+curl https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-1 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-openai.json
+
+npx hyperframes transcribe transcript-openai.json
+```
+
+**Groq Whisper API** (fast, free tier available):
+
+```bash
+curl https://api.groq.com/openai/v1/audio/transcriptions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -F file=@audio.mp3 -F model=whisper-large-v3 \
+  -F response_format=verbose_json \
+  -F "timestamp_granularities[]=word" \
+  -o transcript-groq.json
+
+npx hyperframes transcribe transcript-groq.json
+```
+
+## If No Transcript Exists
+
+1. Check the project root for `transcript.json`, `.srt`, or `.vtt` files
+2. If none found, run transcription — pick the starting model based on the content type:
+   - Speech/voiceover → `small.en`
+   - Music with vocals → `medium.en`
+   ```bash
+   npx hyperframes transcribe <audio-or-video-file> --model medium.en
+   ```
+3. **Read the transcript and run the quality check** (see above). If it fails, retry with a larger model or suggest manual lyrics.

skills/hyperframes/references/transitions.md

@@ -0,0 +1,112 @@
+# Scene Transitions
+
+A transition tells the viewer how two scenes relate. A crossfade says "this continues." A push slide says "next point." A blur crossfade says "drift with me." Choose transitions that match what the content is doing emotionally, not just technically.
+
+## Animation Rules for Multi-Scene Compositions
+
+These are non-negotiable for every multi-scene composition:
+
+1. **Every composition uses transitions.** No exceptions. Scenes without transitions feel like jump cuts.
+2. **Every scene uses entrance animations.** Elements animate IN via `gsap.from()` — opacity, position, scale, etc. No scene should pop fully-formed onto screen.
+3. **Exit animations are BANNED** except on the final scene. Do NOT use `gsap.to()` to animate elements out before a transition fires. The transition IS the exit. Outgoing scene content must be fully visible when the transition starts — the transition handles the visual handoff.
+4. **Final scene exception:** The last scene MAY fade elements out (e.g., fade to black at the end of the composition). This is the only scene where exit animations are allowed.
+
+## Energy → Primary Transition
+
+| Energy                                   | CSS Primary                  | Shader Primary                       | Accent                         | Duration  | Easing                 |
+| ---------------------------------------- | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ---------------------- |
+| **Calm** (wellness, brand story, luxury) | Blur crossfade, focus pull   | Cross-warp morph, thermal distortion | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1` |
+| **Medium** (corporate, SaaS, explainer)  | Push slide, staggered blocks | Whip pan, cinematic zoom             | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`     |
+| **High** (promos, sports, music, launch) | Zoom through, overexposure   | Ridged burn, glitch, chromatic split | 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 · **Shader:** thermal distortion, light leak, cross-warp morph                     | Soft edges, warm color washes. Nothing sharp or mechanical.                                 |
+| **Cold / clinical**      | Squeeze, zoom out, blinds, shutter, grid dissolve · **Shader:** gravitational lens                                                   | Content transforms mechanically — compressed, shrunk, sliced, gridded.                      |
+| **Editorial / magazine** | Push slide, vertical push, diagonal split, shutter · **Shader:** whip pan                                                            | Like turning a page or slicing a layout. Clean directional movement.                        |
+| **Tech / futuristic**    | Grid dissolve, staggered blocks, blinds, chromatic aberration · **Shader:** glitch, chromatic split                                  | Grid dissolve is the core "data" transition. Shader glitch adds posterization + scan lines. |
+| **Tense / edgy**         | Glitch, VHS, chromatic aberration, ripple · **Shader:** ridged burn, glitch, domain warp                                             | Instability, distortion, digital breakdown. Ridged burn adds sharp lightning-crack edges.   |
+| **Playful / fun**        | Elastic push, 3D flip, circle iris, morph circle, clock wipe · **Shader:** ripple waves, swirl vortex                                | Overshoot, bounce, rotation, expansion. Swirl vortex adds organic spiral distortion.        |
+| **Dramatic / cinematic** | Zoom through, zoom out, gravity drop, overexposure, color dip to black · **Shader:** cinematic zoom, gravitational lens, domain warp | Scale, weight, light extremes. Shader transitions add per-pixel depth.                      |
+| **Premium / luxury**     | Focus pull, blur crossfade, color dip to black · **Shader:** 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 · **Shader:** light leak                                                                      | Organic imperfection. Warm color bleeds, scan line displacement.                            |
+
+## 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    | CSS                                                            | Shader (WebGL)                                                            |
+| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Push/slide  | Push slide, vertical push, elastic push, squeeze               | Whip pan                                                                  |
+| Scale/zoom  | Zoom through, zoom out, gravity drop, 3D flip                  | Cinematic zoom, gravitational lens                                        |
+| Reveal/mask | Circle iris, diamond iris, diagonal split, clock wipe, shutter | SDF iris                                                                  |
+| Dissolve    | Crossfade, blur crossfade, focus pull, color dip               | Cross-warp morph, domain warp                                             |
+| Cover       | Staggered blocks, horizontal blinds, vertical blinds           | —                                                                         |
+| Light       | Light leak, overexposure burn, film burn                       | Light leak (shader), thermal distortion                                   |
+| Distortion  | Glitch, chromatic aberration, ripple, VHS tape                 | Glitch (shader), chromatic split, ridged burn, ripple waves, swirl vortex |
+| Pattern     | Grid dissolve, morph circle                                    | —                                                                         |
+
+## Transitions That Don't Work in CSS
+
+Avoid: star iris, tilt-shift, lens flare, hinge/door. See catalog.md for why.
+
+## CSS vs Shader
+
+CSS transitions animate scene containers with opacity, transforms, clip-path, and filters. Shader transitions composite both scene textures per-pixel on a WebGL canvas — they can warp, dissolve, and morph in ways CSS cannot.
+
+**Both are first-class options.** Shaders are provided by the `@hyperframes/shader-transitions` package — import from the package instead of writing raw GLSL. CSS transitions are simpler to set up. Choose based on the effect you want, not based on which is easier.
+
+When a composition uses shader transitions, ALL transitions in that composition should be shader-based (the WebGL canvas replaces DOM-based scene switching). Don't mix CSS and shader transitions in the same composition.
+
+## Shader-Compatible CSS Rules
+
+Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D rendering pipeline doesn't match CSS exactly. Follow these rules to avoid visible artifacts at transition boundaries:
+
+1. **No `transparent` keyword in gradients.** Canvas interpolates `transparent` as `rgba(0,0,0,0)` (black at zero alpha), creating dark fringes. Always use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`.
+2. **No gradient backgrounds on elements thinner than 4px.** Canvas can't match CSS gradient rendering on 1-2px elements. Use solid `background-color` on thin accent lines.
+3. **No CSS variables (`var()`) on elements visible during capture.** html2canvas doesn't reliably resolve custom properties. Use literal color values in inline styles.
+4. **Mark uncapturable decorative elements with `data-no-capture`.** The capture function skips these. They're present on the live DOM but absent from the shader texture. Use for elements that can't follow the rules above.
+5. **No gradient opacity below 0.15.** Gradient elements below 10% opacity render differently in canvas vs CSS. Increase to 0.15+ or use a solid color at equivalent brightness.
+6. **Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config.** The package captures scene elements via html2canvas. Both the CSS `background-color` on `.scene` and the `bgColor` config must match. Without either, the texture renders as black.
+
+These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
+
+## 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.

skills/hyperframes/references/transitions/catalog.md

@@ -0,0 +1,117 @@
+# Transition Catalog
+
+Hard rules, scene template, and routing to implementation code. Read the reference file for the transition type you need — don't load all of them.
+
+## Hard Rules (CSS)
+
+These cause real bugs if violated.
+
+**Scene visibility:** Scene 1 visible by default (no `opacity: 0`). Scenes 2+ have `opacity: 0` on the CONTAINER div. GSAP reveals them. No visibility shim (`timedEls`).
+
+**Fonts:** Just write the `font-family` you want — the compiler embeds supported fonts automatically via `@font-face` with inline data URIs. No need for `<link>` tags or `@import`. Works in all contexts including sandboxed iframes.
+
+**Element structure:** No `class="clip"` on scene divs in standalone compositions. Only the root div gets `data-composition-id`/`data-start`/`data-duration`.
+
+**Overlay elements:** Staggered blocks = full-screen 1920x1080, NOT thin strips. Glitch RGB overlays = normal blending at 35% opacity, NOT `mix-blend-mode: multiply` (invisible on dark backgrounds). Light leak overlays = larger than the frame (2400px+), never a visible shape. Overexposure = use `filter: brightness()` on the scene, not just a white overlay.
+
+**VHS tape:** Clone actual scene content with `cloneNode(true)`, NOT colored bars. Each strip: wider than frame (2020px at left:-50px). Red+blue chromatic copies at z-index above main strip. Seeded PRNG for deterministic random offsets.
+
+**Z-index:** Gravity drop, zoom out, diagonal split need outgoing scene ON TOP (`zIndex: 10`) so it exits while revealing the new scene behind (`zIndex: 1`).
+
+**Page burn:** Content burns with the page — no falling debris. Hide scene1 via `tl.set` at burn end, NEVER `onComplete` (not reversible). `onUpdate` must restore `clipPath: "none"` when `wp <= 0` for rewind support. Incoming scene fades from black at 90% through burn.
+
+**Clock wipe:** 9-point polygon with intermediate edge positions. Step through 4 quadrants with separate tweens.
+
+**Grid dissolve:** Cycle 5 palette colors per cell, not monochrome.
+
+**Blinds count by energy:** Calm: 4h/6v. Medium: 6-8h/8v. High: 12-16h/16v.
+
+**Don't use:** Star iris (polygon interpolation broken), tilt-shift (no selective CSS blur), lens flare (visible shape, not optical), hinge/door (distorts too fast).
+
+## Shader Transitions
+
+Shader setup, WebGL init, capture, and fragment shaders are handled by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). Read the package source for API details. Compositions using shaders must follow the CSS rules in [transitions.md](../transitions.md) § "Shader-Compatible CSS Rules".
+
+## Scene Template
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+        background: #000;
+        font-family: "YOUR FONT", sans-serif; /* compiler embeds supported fonts automatically */
+      }
+      .scene {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+      #scene1 {
+        z-index: 1;
+        background: #color;
+      }
+      #scene2 {
+        z-index: 2;
+        background: #color;
+        opacity: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-width="1920"
+      data-height="1080"
+      data-start="0"
+      data-duration="TOTAL"
+    >
+      <div id="scene1" class="scene"><!-- visible --></div>
+      <div id="scene2" class="scene"><!-- hidden --></div>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      // Transition code here
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+Every transition follows: position new scene → animate outgoing → swap → animate incoming → clean up overlays.
+
+## CSS Transitions
+
+All code examples use `old` for the outgoing scene-inner selector and `new` for the incoming, with `T` as the transition start time. Read the reference file for the type you need.
+
+| Type           | Transitions                                          | Reference                                  |
+| -------------- | ---------------------------------------------------- | ------------------------------------------ |
+| Push           | Push slide, vertical push, elastic push, squeeze     | [css-push.md](./css-push.md)               |
+| Radial / Shape | Circle iris, diamond iris, diagonal split            | [css-radial.md](./css-radial.md)           |
+| 3D             | 3D card flip                                         | [css-3d.md](./css-3d.md)                   |
+| Scale / Zoom   | Zoom through, zoom out                               | [css-scale.md](./css-scale.md)             |
+| Dissolve       | Crossfade, blur crossfade, focus pull, color dip     | [css-dissolve.md](./css-dissolve.md)       |
+| Cover          | Staggered blocks, horizontal blinds, vertical blinds | [css-cover.md](./css-cover.md)             |
+| Light          | Light leak, overexposure burn, film burn             | [css-light.md](./css-light.md)             |
+| Distortion     | Glitch, chromatic aberration, ripple, VHS tape       | [css-distortion.md](./css-distortion.md)   |
+| Mechanical     | Shutter, clock wipe                                  | [css-mechanical.md](./css-mechanical.md)   |
+| Grid           | Grid dissolve                                        | [css-grid.md](./css-grid.md)               |
+| Other          | Gravity drop, morph circle                           | [css-other.md](./css-other.md)             |
+| Blur           | Blur through, directional blur                       | [css-blur.md](./css-blur.md)               |
+| Destruction    | Page burn                                            | [css-destruction.md](./css-destruction.md) |
+
+## Shader Transitions
+
+WebGL shader transitions are provided by `@hyperframes/shader-transitions` (`packages/shader-transitions/`). The package handles setup, capture, WebGL init, render loop, and GSAP integration. Read the package source for available shaders and API — do not copy raw GLSL manually.

skills/hyperframes/references/transitions/css-3d.md

@@ -0,0 +1,12 @@
+## 3D
+
+### 3D Card Flip
+
+180° Y-axis rotation. Requires CSS: `backface-visibility: hidden; transform-style: preserve-3d;` on both scene-inners. Parent needs `perspective: 1200px`.
+
+```js
+tl.set(new, { rotationY: -180, opacity: 1 }, T);
+tl.to(old, { rotationY: 180, duration: 0.6, ease: "power2.inOut" }, T);
+tl.to(new, { rotationY: 0, duration: 0.6, ease: "power2.inOut" }, T);
+tl.set(old, { opacity: 0 }, T + 0.6);
+```

skills/hyperframes/references/transitions/css-blur.md

@@ -0,0 +1,51 @@
+## Blur
+
+All blur transitions scale with energy. See SKILL.md "Blur Intensity by Energy" for the full table.
+
+### Blur Through
+
+Content becomes fully abstract before resolving. The heaviest blur transition.
+
+**Calm (default for this type — it's inherently heavy):**
+
+```js
+tl.to(old, { filter: "blur(30px)", scale: 1.08, duration: 0.5, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.3, ease: "power1.in" }, T + 0.3);
+// Hold: both scenes in abstract blur state
+tl.fromTo(new,
+  { filter: "blur(30px)", scale: 0.92, opacity: 0 },
+  { filter: "blur(30px)", scale: 0.92, opacity: 1, duration: 0.2, ease: "none" }, T + 0.5);
+// Slow resolve
+tl.to(new, { filter: "blur(0px)", scale: 1, duration: 0.7, ease: "power1.out" }, T + 0.7);
+```
+
+**Medium:**
+
+```js
+tl.to(old, { filter: "blur(15px)", scale: 1.05, opacity: 0, duration: 0.4, ease: "power2.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(15px)", scale: 0.95, opacity: 0 },
+  { filter: "blur(0px)", scale: 1, opacity: 1, duration: 0.4, ease: "power2.out" }, T + 0.2);
+```
+
+### Directional Blur
+
+Blur + skew simulating motion in one direction. Scale blur and skew with energy.
+
+**Medium (default):**
+
+```js
+tl.to(old, { filter: "blur(12px)", skewX: -8, x: -200, opacity: 0, duration: 0.4, ease: "power3.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(12px)", skewX: 8, x: 200, opacity: 0 },
+  { filter: "blur(0px)", skewX: 0, x: 0, opacity: 1, duration: 0.4, ease: "power3.out" }, T + 0.15);
+```
+
+**Calm (heavier blur, gentler motion):**
+
+```js
+tl.to(old, { filter: "blur(20px)", skewX: -4, x: -100, opacity: 0, duration: 0.6, ease: "power1.in" }, T);
+tl.fromTo(new,
+  { filter: "blur(20px)", skewX: 4, x: 100, opacity: 0 },
+  { filter: "blur(0px)", skewX: 0, x: 0, opacity: 1, duration: 0.6, ease: "power1.out" }, T + 0.3);
+```

skills/hyperframes/references/transitions/css-cover.md

@@ -0,0 +1,43 @@
+## Cover
+
+### Staggered Color Blocks
+
+Full-screen (1920x1080) colored divs slide across staggered. Scene swaps while covered.
+
+**2-block** (standard):
+
+```js
+tl.set("#wipe-a", { x: -1920 }, T - 0.01);
+tl.set("#wipe-b", { x: -1920 }, T - 0.01);
+tl.to("#wipe-a", { x: 0, duration: 0.25, ease: "power3.inOut" }, T);
+tl.to("#wipe-b", { x: 0, duration: 0.25, ease: "power3.inOut" }, T + 0.06);
+tl.set(old, { opacity: 0 }, T + 0.2);
+tl.set(new, { opacity: 1 }, T + 0.2);
+tl.to("#wipe-a", { x: 1920, duration: 0.25, ease: "power3.inOut" }, T + 0.28);
+tl.to("#wipe-b", { x: 1920, duration: 0.25, ease: "power3.inOut" }, T + 0.34);
+```
+
+**5-block** (dense variant): same pattern with 5 blocks at 0.04s stagger. Use composition palette colors.
+
+### Horizontal Blinds
+
+Full-width strips slide across staggered. Each strip: `width: 1920px; height: Xpx`.
+
+**6 strips** (180px each): `0.03s` stagger
+**12 strips** (90px each): `0.018s` stagger
+
+```js
+for (var i = 0; i < N; i++) {
+  tl.set("#blind-h-" + i, { x: -1920 }, T - 0.01);
+  tl.fromTo("#blind-h-" + i, { x: -1920 }, { x: 0, duration: 0.2, ease: "power3.inOut" }, T + i * stagger);
+}
+tl.set(old, { opacity: 0 }, T + coverTime);
+tl.set(new, { opacity: 1 }, T + coverTime);
+for (var i = 0; i < N; i++) {
+  tl.to("#blind-h-" + i, { x: 1920, duration: 0.2, ease: "power3.inOut" }, T + exitStart + i * stagger);
+}
+```
+
+### Vertical Blinds
+
+Same as horizontal but strips are tall and narrow, moving on Y axis.

skills/hyperframes/references/transitions/css-destruction.md

@@ -0,0 +1,95 @@
+## Destruction
+
+### Page Burn
+
+The outgoing scene literally burns away from a corner. A fire front expands with noise-based irregular edges, a canvas draws the scorched char line at the burn boundary, and individual text characters/elements chip off and fall with gravity as the fire reaches them. The incoming scene reveals behind the burn.
+
+This transition has three systems working together:
+
+1. **Fire geometry** — a radial front expanding from a corner (e.g., bottom-right) with noise-based irregularity for organic edges
+2. **Scene clipping** — the outgoing scene uses an SVG clip-path (with `fill-rule: evenodd`) that cuts a hole matching the fire front. As the fire expands, more of the scene is clipped away. All content (text, images, lines) burns with the page — no separate debris.
+3. **Scorched edge** — a `<canvas>` overlay draws a radial gradient fringe at the fire boundary to simulate charring
+
+**When to use:** Dramatic reveals, edgy/destructive mood, gaming, cyberpunk. This is the most dramatic transition in the catalog — reserve it for hero moments.
+
+**Requirements:**
+
+- A `<canvas>` element for the burn edge overlay
+- A noise function for organic fire edge geometry
+- SVG clip-path with evenodd fill-rule for the inverted clip
+
+**Fire geometry (deterministic noise):**
+
+```js
+function noise(x) {
+  var ix = Math.floor(x),
+    fx = x - ix;
+  var a = Math.sin(ix * 127.1 + 311.7) * 43758.5453;
+  var b = Math.sin((ix + 1) * 127.1 + 311.7) * 43758.5453;
+  var t = fx * fx * (3 - 2 * fx);
+  return a - Math.floor(a) + (b - Math.floor(b) - (a - Math.floor(a))) * t;
+}
+
+function fireRadiusAtAngle(angle, progress) {
+  var base = progress * maxRadius;
+  return (
+    base +
+    noise(angle * 3 + progress * 4) * 50 +
+    noise(angle * 8 + progress * 9) * 20 +
+    noise(angle * 15 + progress * 15) * 8
+  );
+}
+```
+
+**Incoming scene timing:** The incoming scene should NOT be visible during the burn. As the fire consumes the outgoing scene, **black shows through the holes** — this is the dramatic part. The viewer watches content being destroyed against blackness.
+
+At ~90% through the burn, the incoming scene fades in SLOWLY from black — the background first, then content staggered. Use long, gentle fades (`power1.out`, 0.8-1.2s durations) so it feels like the new scene materializes from darkness, not a hard swap.
+
+```js
+// Scene 2 stays at opacity: 0 during the burn — black behind the fire
+tl.set("#s2-title", { opacity: 0 }, T);
+tl.set("#s2-subtitle", { opacity: 0 }, T);
+
+// At 90% through, scene bg fades in slowly from black
+var contentReveal = T + BURN_DURATION * 0.9;
+tl.to("#scene2", { opacity: 1, duration: 1.2, ease: "power1.out" }, contentReveal);
+
+// Content fades in staggered on top, even slower
+tl.to("#s2-title", { opacity: 1, duration: 1.0, ease: "power1.out" }, contentReveal + 0.5);
+tl.to("#s2-subtitle", { opacity: 1, duration: 0.8, ease: "power1.out" }, contentReveal + 0.7);
+```
+
+**Content burns with the page — no falling debris.** The clip-path on scene1 IS the effect — as the fire shape expands, everything behind the fire edge (text, images, lines) disappears naturally. Don't clone elements, don't create falling debris. The content is part of the page being consumed. The scorched canvas edge provides the visual char line at the burn boundary.
+
+**Hide scene1 via `tl.set` at burn end — NEVER in `onComplete`.** Using `onComplete` to hide scene1 is not reversible when scrubbing. Instead, use a `tl.set` at the exact burn end time:
+
+```js
+tl.to(
+  burnState,
+  {
+    progress: 1,
+    duration: BURN_DURATION,
+    ease: "none",
+    onUpdate: function () {
+      var wp = burnState.progress;
+      var scene1 = document.getElementById("scene1");
+      if (wp <= 0) {
+        scene1.style.clipPath = "none"; // fully visible when rewound
+      } else if (wp < 1) {
+        scene1.style.clipPath = buildClipPath(wp);
+      }
+      drawEdge(wp);
+    },
+    // NO onComplete — use tl.set instead
+  },
+  T,
+);
+
+// Hide scene1 at exact burn end — reversible via timeline
+tl.set("#scene1", { opacity: 0 }, T + BURN_DURATION);
+tl.set("#scene1", { clipPath: "none" }, T + BURN_DURATION);
+```
+
+The `onUpdate` handles clip-path and canvas edge per-frame. The `tl.set` handles the final hide — and GSAP automatically reverses it when scrubbing backward, restoring scene1 to `opacity: 1`.
+
+The `onUpdate` callback is the key — it runs every frame to advance the clip-path and canvas edge in sync with the timeline.

skills/hyperframes/references/transitions/css-dissolve.md

@@ -0,0 +1,66 @@
+## Dissolve
+
+### Crossfade
+
+Simple opacity swap. The baseline.
+
+```js
+tl.to(old, { opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "power2.inOut" }, T);
+```
+
+### Blur Crossfade
+
+Dissolve with blur + scale shift. **Scale blur amount by energy** — see SKILL.md "Blur Intensity by Energy" section. The examples below show the medium (default) version. For calm compositions, increase to 20-30px with a 0.3-0.5s hold at peak blur. For high-energy, decrease to 3-6px with no hold.
+
+**Medium (default):**
+
+```js
+tl.to(old, { filter: "blur(10px)", scale: 1.03, opacity: 0, duration: 0.5, ease: "power2.inOut" }, T);
+tl.fromTo(new,
+  { filter: "blur(10px)", scale: 0.97, opacity: 0 },
+  { filter: "blur(0px)", scale: 1, opacity: 1, duration: 0.5, ease: "power2.inOut" }, T + 0.1);
+```
+
+**Calm (wellness, luxury) — heavy blur, holds at abstract color:**
+
+```js
+tl.to(old, { filter: "blur(25px)", scale: 1.05, duration: 0.6, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.4, ease: "power1.in" }, T + 0.4);
+tl.fromTo(new,
+  { filter: "blur(25px)", scale: 0.95, opacity: 0 },
+  { filter: "blur(25px)", scale: 0.95, opacity: 1, duration: 0.3, ease: "power1.inOut" }, T + 0.5);
+tl.to(new, { filter: "blur(0px)", scale: 1, duration: 0.6, ease: "power1.out" }, T + 0.8);
+```
+
+### Focus Pull
+
+Outgoing slowly blurs while incoming fades in sharp. Depth-of-field feel. **Scale blur amount and hold duration by energy.**
+
+**Medium:**
+
+```js
+tl.to(old, { filter: "blur(15px)", duration: 0.5, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.3, ease: "power2.in" }, T + 0.25);
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.3, ease: "power2.out" }, T + 0.25);
+```
+
+**Calm — slow rack focus with long hold at peak defocus:**
+
+```js
+tl.to(old, { filter: "blur(30px)", duration: 0.8, ease: "power1.in" }, T);
+tl.to(old, { opacity: 0, duration: 0.5, ease: "power1.in" }, T + 0.6);
+tl.fromTo(new, { opacity: 0, filter: "blur(20px)" },
+  { opacity: 1, filter: "blur(20px)", duration: 0.3, ease: "power1.inOut" }, T + 0.7);
+tl.to(new, { filter: "blur(0px)", duration: 0.6, ease: "power1.out" }, T + 1.0);
+```
+
+### Color Dip
+
+Fade to solid color, hold, fade up new scene.
+
+```js
+tl.to(old, { opacity: 0, duration: 0.2, ease: "power2.in" }, T);
+// Background color shows through
+tl.fromTo(new, { opacity: 0 }, { opacity: 1, duration: 0.2, ease: "power2.out" }, T + 0.25);
+```

skills/hyperframes/references/transitions/css-distortion.md

@@ -0,0 +1,45 @@
+## Distortion
+
+### Glitch
+
+RGB-tinted overlays (NOT multiply blend — use normal blending at 35% opacity) jitter with large offsets. Scene itself also jitters.
+
+```js
+tl.set("#glitch-r", { opacity: 1, x: 40, y: -8 }, T);
+tl.set("#glitch-g", { opacity: 1, x: -30, y: 12 }, T);
+tl.set("#glitch-b", { opacity: 1, x: 15, y: -20 }, T);
+tl.set(old, { x: -15 }, T);
+// 6 jitter frames at 0.03s intervals with big offsets (±30-60px)
+// ... swap and clear at T + 0.2
+```
+
+### Chromatic Aberration
+
+RGB overlays start aligned then spread apart (±80px), scene fades, converge on new scene.
+
+```js
+tl.set("#glitch-r", { opacity: 0.6, x: 0 }, T);
+tl.set("#glitch-g", { opacity: 0.6, x: 0 }, T);
+tl.set("#glitch-b", { opacity: 0.6, x: 0 }, T);
+tl.to("#glitch-r", { x: -80, opacity: 0.8, duration: 0.3, ease: "power2.in" }, T);
+tl.to("#glitch-b", { x: 80, opacity: 0.8, duration: 0.3, ease: "power2.in" }, T);
+tl.to("#glitch-g", { y: 30, duration: 0.3, ease: "power2.in" }, T);
+// Swap at T + 0.3, converge back at T + 0.3
+```
+
+### Ripple
+
+Rapid oscillation (±30px) + scale distortion (0.97-1.03) + increasing blur. Swap at peak distortion.
+
+```js
+tl.to(old, { x: 30, scale: 1.02, duration: 0.04, ease: "none" }, T);
+tl.to(old, { x: -25, scale: 0.98, filter: "blur(4px)", duration: 0.04, ease: "none" }, T + 0.04);
+// ... more oscillations with increasing blur
+// Swap at peak, incoming stabilizes with decreasing wobble
+```
+
+### VHS Tape
+
+Clone scene into 20 horizontal strips (each 54px, clip-path'd). Each strip shifts x independently with seeded pseudo-random offsets at per-bar random intervals. Add red+blue chromatic offset copies on each strip (z-index above main, 35% opacity). Make strips wider than frame (2020px at left:-50px) so edges never show.
+
+See SKILL.md for clone-based implementation pattern.

skills/hyperframes/references/transitions/css-grid.md

@@ -0,0 +1,10 @@
+## Grid
+
+### Grid Dissolve
+
+Grid of colored cells covers the frame in a ripple from center. Scene swaps at 50% coverage. Cells fade out in ripple.
+
+**12-cell** (4x3, each 480x270): standard
+**120-cell** (12x10, each 160x108): dense variant — lower opacity (0.75), tighter ripple
+
+Cells are created dynamically in JS, sorted by distance from center for ripple stagger.

skills/hyperframes/references/transitions/css-light.md

@@ -0,0 +1,49 @@
+## Light
+
+### Light Leak
+
+Multiple warm-colored overlays wash across frame. Needs: a flat warm tint layer + 2-3 bright radial gradient divs, all larger than the frame so edges are never visible.
+
+```js
+// Warm tint washes over entire frame
+tl.to("#leak-warm", { opacity: 0.4, duration: 0.3, ease: "power1.in" }, T);
+// Bright leak elements drift in
+tl.to("#leak-1", { opacity: 0.9, x: 300, duration: 0.5, ease: "sine.inOut" }, T + 0.05);
+tl.to("#leak-2", { opacity: 0.8, x: 200, duration: 0.6, ease: "sine.inOut" }, T + 0.1);
+// Peak warmth then swap
+tl.to("#leak-warm", { opacity: 0.6, duration: 0.15, ease: "power2.in" }, T + 0.35);
+tl.set(old, { opacity: 0 }, T + 0.45);
+tl.set(new, { opacity: 1 }, T + 0.45);
+// Leak fades
+tl.to("#leak-warm", { opacity: 0, duration: 0.4, ease: "power2.out" }, T + 0.5);
+tl.to("#leak-1", { opacity: 0, x: 600, duration: 0.35, ease: "power1.out" }, T + 0.5);
+```
+
+### Overexposure Burn
+
+Scene progressively blows out to white using CSS `filter: brightness()`, then white overlay fades in. Swap at peak white. White recedes to reveal new scene.
+
+```js
+tl.to(old, { filter: "brightness(1.5)", scale: 1.03, duration: 0.2, ease: "power1.in" }, T);
+tl.to(old, { filter: "brightness(3)", scale: 1.06, duration: 0.2, ease: "power2.in" }, T + 0.2);
+tl.to("#flash-overlay", { opacity: 0.5, duration: 0.25, ease: "power1.in" }, T + 0.15);
+tl.to("#flash-overlay", { opacity: 1, duration: 0.15, ease: "power2.in" }, T + 0.4);
+tl.set(old, { opacity: 0, filter: "brightness(1)", scale: 1 }, T + 0.55);
+tl.set(new, { opacity: 1 }, T + 0.55);
+tl.to("#flash-overlay", { opacity: 0, duration: 0.35, ease: "power2.out" }, T + 0.55);
+```
+
+### Film Burn
+
+Staggered warm overlays (amber, orange, red) bleed from one edge. Each overlay is a large radial gradient div at high z-index.
+
+```js
+tl.to("#burn-a", { opacity: 1, x: -300, duration: 0.4, ease: "power1.in" }, T);
+tl.to("#burn-b", { opacity: 1, x: -500, duration: 0.5, ease: "power1.in" }, T + 0.05);
+tl.to("#burn-c", { opacity: 1, x: -200, duration: 0.45, ease: "power1.in" }, T + 0.1);
+tl.set(old, { opacity: 0 }, T + 0.35);
+tl.set(new, { opacity: 1 }, T + 0.35);
+tl.to("#burn-a", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.45);
+tl.to("#burn-b", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.5);
+tl.to("#burn-c", { opacity: 0, duration: 0.3, ease: "power2.out" }, T + 0.55);
+```

skills/hyperframes/references/transitions/css-mechanical.md

@@ -0,0 +1,30 @@
+## Mechanical
+
+### Shutter
+
+Two full-screen halves close from top and bottom, meet in the middle. Swap while closed. Open again.
+
+```js
+tl.to("#shutter-top", { y: 0, duration: 0.25, ease: "power3.in" }, T);
+tl.to("#shutter-bot", { y: 0, duration: 0.25, ease: "power3.in" }, T);
+tl.set(old, { opacity: 0 }, T + 0.25);
+tl.set(new, { opacity: 1 }, T + 0.25);
+tl.to("#shutter-top", { y: -540, duration: 0.25, ease: "power3.out" }, T + 0.3);
+tl.to("#shutter-bot", { y: 540, duration: 0.25, ease: "power3.out" }, T + 0.3);
+```
+
+### Clock Wipe
+
+Radial polygon sweep stepping through quadrants. Use 9-point polygon with intermediate edge positions for smooth sweep.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 10 }, T);
+var d = 0.1; // duration per quadrant
+tl.set(new, { clipPath: "polygon(50% 50%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%, 50% 0%)" }, T);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 50%, 100% 50%, 100% 50%, 100% 50%, 100% 50%)", duration: d, ease: "none" }, T);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 100%, 50% 100%, 50% 100%, 50% 100%, 50% 100%)", duration: d, ease: "none" }, T + d);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 100%, 50% 100%, 0% 100%, 0% 50%, 0% 50%)", duration: d, ease: "none" }, T + d*2);
+tl.to(new, { clipPath: "polygon(50% 50%, 50% 0%, 100% 0%, 100% 50%, 100% 100%, 50% 100%, 0% 100%, 0% 50%, 0% 0%)", duration: d, ease: "none" }, T + d*3);
+tl.set(new, { clipPath: "none", zIndex: "auto" }, T + d*4 + 0.02);
+tl.set(old, { opacity: 0, zIndex: "auto" }, T + d*4 + 0.02);
+```

skills/hyperframes/references/transitions/css-other.md

@@ -0,0 +1,25 @@
+## Other
+
+### Gravity Drop
+
+Old scene falls down with slight rotation. New scene was behind it. Needs z-index.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 1 }, T);
+tl.set(old, { zIndex: 10 }, T);
+tl.to(old, { y: 1200, rotation: 4, duration: 0.5, ease: "power3.in" }, T);
+tl.set(old, { opacity: 0, zIndex: "auto" }, T + 0.5);
+tl.set(new, { zIndex: "auto" }, T + 0.5);
+```
+
+### Morph Circle
+
+A circle scales up from center to fill frame (becoming the new scene's background color). New scene content fades in on top.
+
+```js
+tl.set("#morph-circle", { background: newBgColor, opacity: 1, scale: 0 }, T);
+tl.to("#morph-circle", { scale: 30, duration: 0.5, ease: "power3.in" }, T);
+tl.set(old, { opacity: 0 }, T + 0.4);
+tl.set(new, { opacity: 1 }, T + 0.4);
+tl.to("#morph-circle", { opacity: 0, duration: 0.15, ease: "power2.out" }, T + 0.5);
+```

skills/hyperframes/references/transitions/css-push.md

@@ -0,0 +1,41 @@
+## Linear / Push
+
+### Push Slide
+
+Both scenes move together — new pushes old out.
+
+```js
+tl.to(old, { x: -1920, duration: 0.5, ease: "power3.inOut" }, T);
+tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 0, duration: 0.5, ease: "power3.inOut" }, T);
+```
+
+### Vertical Push
+
+Same as push slide but vertical.
+
+```js
+tl.to(old, { y: -1080, duration: 0.5, ease: "power3.inOut" }, T);
+tl.fromTo(new, { y: 1080, opacity: 1 }, { y: 0, duration: 0.5, ease: "power3.inOut" }, T);
+```
+
+### Elastic Push
+
+Push with overshoot bounce on the incoming scene.
+
+```js
+tl.to(old, { x: -1920, duration: 0.5, ease: "power3.in" }, T);
+tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 30, duration: 0.4, ease: "power4.out" }, T + 0.1);
+tl.to(new, { x: -15, duration: 0.15, ease: "sine.inOut" }, T + 0.5);
+tl.to(new, { x: 0, duration: 0.1, ease: "sine.out" }, T + 0.65);
+```
+
+### Squeeze
+
+Old compresses, new expands from opposite side.
+
+```js
+tl.to(old, { scaleX: 0, transformOrigin: "left center", duration: 0.4, ease: "power3.inOut" }, T);
+tl.fromTo(new, { scaleX: 0, transformOrigin: "right center", opacity: 1 },
+  { scaleX: 1, duration: 0.4, ease: "power3.inOut" }, T + 0.1);
+tl.set(old, { opacity: 0 }, T + 0.5);
+```

skills/hyperframes/references/transitions/css-radial.md

@@ -0,0 +1,37 @@
+## Radial / Shape
+
+### Circle Iris
+
+Expanding circle from center reveals new scene.
+
+```js
+tl.set(new, { opacity: 1 }, T);
+tl.fromTo(new,
+  { clipPath: "circle(0% at 50% 50%)" },
+  { clipPath: "circle(75% at 50% 50%)", duration: 0.5, ease: "power2.out" }, T);
+tl.set(old, { opacity: 0 }, T + 0.5);
+```
+
+### Diamond Iris
+
+Expanding diamond shape from center.
+
+```js
+tl.set(new, { opacity: 1 }, T);
+tl.fromTo(new,
+  { clipPath: "polygon(50% 50%, 50% 50%, 50% 50%, 50% 50%)" },
+  { clipPath: "polygon(50% -20%, 120% 50%, 50% 120%, -20% 50%)", duration: 0.5, ease: "power2.out" }, T);
+tl.set(old, { opacity: 0 }, T + 0.5);
+```
+
+### Diagonal Split
+
+Old scene shrinks to a triangle in one corner.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 1 }, T);
+tl.set(old, { zIndex: 10, clipPath: "polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)" }, T);
+tl.to(old, { clipPath: "polygon(60% 0%, 100% 0%, 100% 40%, 60% 0%)", duration: 0.5, ease: "power3.inOut" }, T);
+tl.set(old, { opacity: 0, zIndex: "auto", clipPath: "none" }, T + 0.5);
+tl.set(new, { zIndex: "auto" }, T + 0.5);
+```

skills/hyperframes/references/transitions/css-scale.md

@@ -0,0 +1,24 @@
+## Scale / Zoom
+
+### Zoom Through
+
+Old zooms past camera + blurs, new zooms in from behind.
+
+```js
+tl.to(old, { scale: 2.5, opacity: 0, filter: "blur(8px)", duration: 0.4, ease: "power3.in" }, T);
+tl.fromTo(new,
+  { scale: 0.5, opacity: 0, filter: "blur(8px)" },
+  { scale: 1, opacity: 1, filter: "blur(0px)", duration: 0.4, ease: "power3.out" }, T + 0.15);
+```
+
+### Zoom Out
+
+Old shrinks away, new was behind it. Needs z-index management.
+
+```js
+tl.set(new, { opacity: 1, zIndex: 1 }, T);
+tl.set(old, { zIndex: 10, transformOrigin: "50% 50%" }, T);
+tl.to(old, { scale: 0.3, opacity: 0, duration: 0.4, ease: "power3.in" }, T);
+tl.set(old, { zIndex: "auto" }, T + 0.4);
+tl.set(new, { zIndex: "auto" }, T + 0.4);
+```

skills/hyperframes/references/tts.md

@@ -0,0 +1,75 @@
+# 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).
+
+## Multilingual Phonemization
+
+Kokoro voice IDs encode language in the first letter: `a`=American English, `b`=British English, `e`=Spanish, `f`=French, `h`=Hindi, `i`=Italian, `j`=Japanese, `p`=Brazilian Portuguese, `z`=Mandarin. The CLI auto-detects the phonemizer locale from that prefix — you don't need to pass `--lang` when the voice matches the text.
+
+```bash
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav
+```
+
+Use `--lang` only to override auto-detection (e.g. stylized accents):
+
+```bash
+npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
+```
+
+Valid `--lang` codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`.
+
+Non-English phonemization requires `espeak-ng` installed system-wide (`brew install espeak-ng` on macOS, `apt-get install espeak-ng` on Debian/Ubuntu).
+
+## 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/`)

skills/hyperframes/references/typography.md

@@ -0,0 +1,175 @@
+# Typography
+
+The compiler embeds supported fonts — just write `font-family` in CSS.
+
+## Banned
+
+Training-data defaults that every LLM reaches for. These produce monoculture across compositions.
+
+Inter, Roboto, Open Sans, Noto Sans, Arimo, Lato, Source Sans, PT Sans, Nunito, Poppins, Outfit, Sora, Playfair Display, Cormorant Garamond, Bodoni Moda, EB Garamond, Cinzel, Prata, Syne
+
+**Syne in particular** is the most overused "distinctive" display font. It is an instant AI design tell.
+
+## Guardrails
+
+You know these rules but you violate them. Stop.
+
+- **Don't pair two sans-serifs.** You do this constantly — one for headlines, one for body. Cross the boundary: serif + sans, or sans + mono.
+- **One expressive font per scene.** You pick two interesting fonts trying to make it "better." One performs, one recedes.
+- **Weight contrast must be extreme.** You default to 400 vs 700. Video needs 300 vs 900. The difference must be visible in motion at a glance.
+- **Video sizes, not web sizes.** Body: 20px minimum. Headlines: 60px+. Data labels: 16px. You will try to use 14px. Don't.
+
+## What You Don't Do Without Being Told
+
+- **Tension should mean something.** Don't pattern-match pairings. Ask WHY these two fonts disagree. The pairing should embody the content's contradiction — mechanical vs human, public vs private, institutional vs personal. If you can't articulate the tension, it's arbitrary.
+- **Register switching.** Assign different fonts to different communicative modes — one voice for statements, another for data, another for attribution. Not hierarchy on a page. Voices in a conversation.
+- **Tension can live inside a single font.** A font that looks familiar but is secretly strange creates tension with the viewer's expectations, not with another font.
+- **One variable changed = dramatic contrast.** Same letterforms, monospaced vs proportional. Same family at different optical sizes. Changing only rhythm while everything else stays constant.
+- **Double personality works.** Two expressive fonts can coexist if they share an attitude (both irreverent, both precise) even when their forms are completely different.
+- **Time is hierarchy.** The first element to appear is the most important. In video, sequence replaces position.
+- **Motion is typography.** How a word enters carries as much meaning as the font. A 0.1s slam vs a 2s fade — same font, completely different message.
+- **Fixed reading time.** 3 seconds on screen = must be readable in 2. Fewer words, larger type.
+- **Tracking tighter than web.** -0.03em to -0.05em on display sizes. Video encoding compresses letter detail.
+
+## Finding Fonts
+
+Don't default to what you know. If the content is luxury, a grotesque sans might create more tension than the expected Didone serif. Decide the register first, then search.
+
+Save this script to `/tmp/fontquery.py` and run with `curl -s 'https://fonts.google.com/metadata/fonts' > /tmp/gfonts.json && python3 /tmp/fontquery.py /tmp/gfonts.json`:
+
+```python
+import json, sys, random
+from collections import OrderedDict
+
+random.seed()  # true random each run
+
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+fonts = data.get("familyMetadataList", [])
+
+ban = {"Inter","Roboto","Open Sans","Noto Sans","Lato","Poppins","Source Sans 3",
+       "PT Sans","Nunito","Outfit","Sora","Playfair Display","Cormorant Garamond",
+       "Bodoni Moda","EB Garamond","Cinzel","Prata","Arimo","Source Sans Pro","Syne"}
+skip_pfx = ("Roboto","Noto ","Google Sans","Bpmf","Playwrite","Anek","BIZ ",
+            "Nanum","Shippori","Sawarabi","Zen ","Kaisei","Kiwi ","Yuji ","Radio ")
+
+def ok(f):
+    if f["family"] in ban: return False
+    if any(f["family"].startswith(b) for b in skip_pfx): return False
+    if "latin" not in (f.get("subsets") or []): return False
+    return True
+
+seen = set()
+R = OrderedDict()
+
+# Trending Sans — recent (2022+), popular (<300)
+R["Trending Sans"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") in ("Sans Serif","Display") and f.get("dateAdded","") >= "2022-01-01" and f.get("popularity",9999) < 300:
+        R["Trending Sans"].append(f); seen.add(f["family"])
+
+# Trending Serif — recent (2018+), popular (<600)
+R["Trending Serif"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") == "Serif" and f.get("dateAdded","") >= "2018-01-01" and f.get("popularity",9999) < 600:
+        R["Trending Serif"].append(f); seen.add(f["family"])
+
+# Monospace — recent (2018+), popular (<600)
+R["Monospace"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") == "Monospace" and f.get("dateAdded","") >= "2018-01-01" and f.get("popularity",9999) < 600:
+        R["Monospace"].append(f); seen.add(f["family"])
+
+# Impact & Condensed — heavy display fonts with 800+ weight
+R["Impact & Condensed"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    has_heavy = any(k in list(f.get("fonts",{}).keys()) for k in ("800","900"))
+    is_display = f.get("category") in ("Sans Serif","Display")
+    if has_heavy and is_display and f.get("popularity",9999) < 400:
+        R["Impact & Condensed"].append(f); seen.add(f["family"])
+
+# Script & Handwriting — popular (<300)
+R["Script & Handwriting"] = []
+for f in fonts:
+    if not ok(f) or f["family"] in seen: continue
+    if f.get("category") == "Handwriting" and f.get("popularity",9999) < 300:
+        R["Script & Handwriting"].append(f); seen.add(f["family"])
+
+
+# Randomize the top 5 in each category so the LLM doesn't always pick the same first result
+for cat in R:
+    R[cat].sort(key=lambda x: x.get("popularity",9999))
+    top5 = R[cat][:5]
+    rest = R[cat][5:]
+    random.shuffle(top5)
+    R[cat] = top5 + rest
+limits = {"Trending Sans":15,"Trending Serif":12,"Monospace":8,
+          "Impact & Condensed":12,"Script & Handwriting":10}
+for cat in R:
+    items = R[cat][:limits.get(cat,10)]
+    if not items: continue
+    print(f"--- {cat} ({len(items)}) ---")
+    for ff in items:
+        var = "VAR" if ff.get("axes") else "   "
+        print(f'  {ff.get("popularity"):4d} | {var} | {ff["family"]}')
+    print()
+```
+
+Five categories: trending sans, trending serif, monospace, impact/condensed, script/handwriting. All dynamically filtered from Google Fonts metadata — no hardcoded font names. Cross classification boundaries when pairing.
+
+## Selection Thinking
+
+Don't pick fonts by category reflex (editorial → serif, tech → mono, modern → geometric sans). That's pattern matching, not design.
+
+1. **Name the register.** What voice is the content speaking in? Institutional authority? Personal confession? Technical precision? Casual irreverence? The register narrows the field more than the category.
+2. **Think physically.** Imagine the font as a physical object the brand could ship — a museum exhibit caption, a hand-painted shop sign, a 1970s mainframe terminal manual, a fabric label inside a coat, a children's book printed on cheap newsprint, a tax form. Whichever physical object fits the register is pointing at the right _kind_ of typeface.
+3. **Reject your first instinct.** The first font that feels right is usually your training-data default for that register. If you picked it last time too, find something else.
+4. **Cross-check the assumption.** An editorial brief does NOT need a serif. A technical brief does NOT need a sans. A children's product does NOT need a rounded display font. The most distinctive choice often contradicts the category expectation.
+
+## Similar-Font Pairing
+
+Never pair two fonts that are similar but not identical — two geometric sans-serifs, two transitional serifs, two humanist sans. They create visual friction without clear hierarchy. The viewer senses something is "off" but can't articulate it. Either use one font at two weights, or pair fonts that contrast on multiple axes: serif + sans, condensed + wide, geometric + humanist.
+
+## Dark Backgrounds
+
+Light text on dark backgrounds creates two optical illusions you need to compensate for:
+
+- **Increased apparent weight.** Light-on-dark reads heavier than dark-on-light at the same `font-weight`. Use 350 instead of 400 for body text. Headlines are less affected because size compensates.
+- **Tighter apparent spacing.** Light halos around letterforms reduce perceived gaps. Increase `line-height` by 0.05-0.1 beyond your light-background value. For display sizes, add 0.01em `letter-spacing` to counteract.
+
+## OpenType Features for Data
+
+Most fonts ship with OpenType features that are off by default. Turn them on for data compositions:
+
+```css
+/* Tabular numbers — digits align vertically in columns */
+.stat-value,
+.timer,
+.data-column {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Diagonal fractions — renders 1/2 as ½ */
+.recipe-amount,
+.ratio {
+  font-variant-numeric: diagonal-fractions;
+}
+
+/* Small caps for abbreviations — less visual shouting */
+.abbreviation,
+.unit {
+  font-variant-caps: all-small-caps;
+}
+
+/* Disable ligatures in code — fi, fl, ffi should stay separate */
+code,
+.code {
+  font-variant-ligatures: none;
+}
+```
+
+`tabular-nums` is essential any time numbers are stacked vertically — stat callouts, timers, scoreboards, data tables. Without it, digits have proportional widths and columns don't align.

skills/hyperframes/scripts/animation-map.mjs

@@ -0,0 +1,601 @@
+#!/usr/bin/env node
+// animation-map.mjs — HyperFrames animation map for agents
+//
+// Reads every GSAP timeline registered in window.__timelines, enumerates
+// tweens, samples bboxes at N points per tween, computes flags and
+// human-readable summaries. Outputs a single animation-map.json.
+//
+// Usage:
+//   node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
+//     [--frames N] [--out <dir>] [--min-duration S] [--width W] [--height H] [--fps N]
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { hyperframesPackageSpec, importPackagesOrBootstrap } from "./package-loader.mjs";
+
+const {
+  createFileServer,
+  createCaptureSession,
+  initializeSession,
+  closeCaptureSession,
+  getCompositionDuration,
+} = (
+  await importPackagesOrBootstrap(["@hyperframes/producer"], {
+    npmPackages: [hyperframesPackageSpec("@hyperframes/producer")],
+  })
+)["@hyperframes/producer"];
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.composition) die("missing <composition-dir>");
+
+const FRAMES = Number(args.frames ?? 6);
+const OUT_DIR = resolve(args.out ?? ".hyperframes/anim-map");
+const MIN_DUR = Number(args["min-duration"] ?? 0.15);
+const WIDTH = Number(args.width ?? 1920);
+const HEIGHT = Number(args.height ?? 1080);
+const FPS = Number(args.fps ?? 30);
+const COMP_DIR = resolve(args.composition);
+
+await mkdir(OUT_DIR, { recursive: true });
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+const server = await createFileServer({ projectDir: COMP_DIR, port: 0 });
+const session = await createCaptureSession(
+  server.url,
+  OUT_DIR,
+  { width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
+  null,
+);
+await initializeSession(session);
+
+try {
+  const duration = await getCompositionDuration(session);
+  const tweens = await enumerateTweens(session);
+  const kept = tweens.filter((tw) => tw.end - tw.start >= MIN_DUR);
+
+  const report = {
+    composition: COMP_DIR,
+    duration,
+    totalTweens: tweens.length,
+    mappedTweens: kept.length,
+    skippedMicroTweens: tweens.length - kept.length,
+    tweens: [],
+  };
+
+  for (let i = 0; i < kept.length; i++) {
+    const tw = kept[i];
+    const times = Array.from(
+      { length: FRAMES },
+      (_, k) => +(tw.start + ((k + 0.5) / FRAMES) * (tw.end - tw.start)).toFixed(3),
+    );
+
+    const bboxes = [];
+    for (const t of times) {
+      await seekTo(session, t);
+      const bbox = await measureTarget(session, tw.selectorHint);
+      bboxes.push({ t, ...bbox });
+    }
+
+    const animProps = tw.props.filter(
+      (p) => !["parent", "overwrite", "immediateRender", "startAt", "runBackwards"].includes(p),
+    );
+    const flags = computeFlags(tw, bboxes, { width: WIDTH, height: HEIGHT });
+    const summary = describeTween(tw, animProps, bboxes, flags);
+
+    report.tweens.push({
+      index: i + 1,
+      selector: tw.selectorHint,
+      targets: tw.targetCount,
+      props: animProps,
+      start: +tw.start.toFixed(3),
+      end: +tw.end.toFixed(3),
+      duration: +(tw.end - tw.start).toFixed(3),
+      ease: tw.ease,
+      bboxes,
+      flags,
+      summary,
+    });
+  }
+
+  markCollisions(report.tweens);
+
+  for (const tw of report.tweens) {
+    if (tw.flags.includes("collision") && !tw.summary.includes("collision")) {
+      tw.summary += " Overlaps another animated element.";
+    }
+  }
+
+  // ── Composition-level analysis ──
+  report.choreography = buildTimeline(report.tweens, duration);
+  report.density = computeDensity(report.tweens, duration);
+  report.staggers = detectStaggers(report.tweens);
+  report.elements = buildElementLifecycles(report.tweens);
+  report.deadZones = findDeadZones(report.density, duration);
+  report.snapshots = await captureSnapshots(session, report.tweens, duration);
+
+  await writeFile(join(OUT_DIR, "animation-map.json"), JSON.stringify(report, null, 2));
+
+  printSummary(report);
+} finally {
+  await closeCaptureSession(session).catch(() => {});
+  server.close();
+}
+
+// ─── Seek helper ────────────────────────────────────────────────────────────
+
+async function seekTo(session, t) {
+  await session.page.evaluate((time) => {
+    if (window.__hf && typeof window.__hf.seek === "function") {
+      window.__hf.seek(time);
+      return;
+    }
+    const tls = window.__timelines;
+    if (tls) {
+      for (const tl of Object.values(tls)) {
+        if (typeof tl.seek === "function") tl.seek(time);
+      }
+    }
+  }, t);
+  await new Promise((r) => setTimeout(r, 100));
+}
+
+// ─── Timeline introspection ──────────────────────────────────────────────────
+
+async function enumerateTweens(session) {
+  return await session.page.evaluate(() => {
+    const results = [];
+    const registry = window.__timelines || {};
+
+    const selectorOf = (el) => {
+      if (!el || !(el instanceof Element)) return null;
+      if (el.id) return `#${el.id}`;
+      const cls = [...el.classList].slice(0, 2).join(".");
+      return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();
+    };
+
+    const walk = (node, parentOffset = 0) => {
+      if (!node) return;
+      if (typeof node.getChildren === "function") {
+        const offset = parentOffset + (node.startTime?.() ?? 0);
+        for (const child of node.getChildren(true, true, true)) {
+          walk(child, offset);
+        }
+        return;
+      }
+      const targets = (node.targets?.() ?? []).filter((t) => t instanceof Element);
+      if (!targets.length) return;
+      const vars = node.vars ?? {};
+      const props = Object.keys(vars).filter(
+        (k) =>
+          ![
+            "duration",
+            "ease",
+            "delay",
+            "repeat",
+            "yoyo",
+            "onStart",
+            "onUpdate",
+            "onComplete",
+            "stagger",
+          ].includes(k),
+      );
+      const start = parentOffset + (node.startTime?.() ?? 0);
+      const end = start + (node.duration?.() ?? 0);
+      results.push({
+        selectorHint: selectorOf(targets[0]) ?? "(unknown)",
+        targetCount: targets.length,
+        props,
+        start,
+        end,
+        ease: typeof vars.ease === "string" ? vars.ease : (vars.ease?.toString?.() ?? "none"),
+      });
+    };
+
+    for (const tl of Object.values(registry)) walk(tl, 0);
+    results.sort((a, b) => a.start - b.start);
+    return results;
+  });
+}
+
+async function measureTarget(session, selector) {
+  return await session.page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    if (!el) return { x: 0, y: 0, w: 0, h: 0, missing: true };
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    return {
+      x: Math.round(r.x),
+      y: Math.round(r.y),
+      w: Math.round(r.width),
+      h: Math.round(r.height),
+      opacity: parseFloat(cs.opacity),
+      visible: cs.visibility !== "hidden" && cs.display !== "none",
+    };
+  }, selector);
+}
+
+// ─── Tween description (the key output for agents) ──────────────────────────
+
+function describeTween(tw, props, bboxes, flags) {
+  const dur = (tw.end - tw.start).toFixed(2);
+  const parts = [];
+
+  parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`);
+
+  // Movement
+  const first = bboxes[0];
+  const last = bboxes[bboxes.length - 1];
+  if (first && last) {
+    const dx = last.x - first.x;
+    const dy = last.y - first.y;
+    if (Math.abs(dx) > 3 || Math.abs(dy) > 3) {
+      const dirs = [];
+      if (Math.abs(dy) > 3) dirs.push(dy < 0 ? `${Math.abs(dy)}px up` : `${Math.abs(dy)}px down`);
+      if (Math.abs(dx) > 3)
+        dirs.push(dx < 0 ? `${Math.abs(dx)}px left` : `${Math.abs(dx)}px right`);
+      parts.push(`moves ${dirs.join(" and ")}`);
+    }
+  }
+
+  // Opacity
+  if (first && last && first.opacity !== undefined && last.opacity !== undefined) {
+    const o1 = first.opacity;
+    const o2 = last.opacity;
+    if (Math.abs(o2 - o1) > 0.1) {
+      if (o1 < 0.1 && o2 > 0.5) parts.push("fades in");
+      else if (o1 > 0.5 && o2 < 0.1) parts.push("fades out");
+      else parts.push(`opacity ${o1.toFixed(1)}→${o2.toFixed(1)}`);
+    }
+  }
+
+  // Scale (from props)
+  if (props.includes("scale") || props.includes("scaleX") || props.includes("scaleY")) {
+    parts.push("scales");
+  }
+
+  // Size changes
+  if (first && last) {
+    const dw = last.w - first.w;
+    const dh = last.h - first.h;
+    if (Math.abs(dw) > 5) parts.push(`width ${first.w}→${last.w}px`);
+    if (Math.abs(dh) > 5) parts.push(`height ${first.h}→${last.h}px`);
+  }
+
+  // Visibility
+  if (first && last && first.visible !== last.visible) {
+    parts.push(last.visible ? "becomes visible" : "becomes hidden");
+  }
+
+  // Final position
+  if (last && !last.missing) {
+    parts.push(`ends at (${last.x}, ${last.y}) ${last.w}×${last.h}px`);
+  }
+
+  // Flags
+  if (flags.length > 0) {
+    parts.push(`FLAGS: ${flags.join(", ")}`);
+  }
+
+  return parts.join(". ") + ".";
+}
+
+// ─── Flag computation ───────────────────────────────────────────────────────
+
+function computeFlags(tw, bboxes, { width, height }) {
+  const flags = [];
+  const dur = tw.end - tw.start;
+
+  if (bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate");
+
+  const anyOffscreen = bboxes.some(
+    (b) =>
+      b.x + b.w <= 0 ||
+      b.y + b.h <= 0 ||
+      b.x >= width ||
+      b.y >= height ||
+      b.x < -b.w * 0.5 ||
+      b.y < -b.h * 0.5 ||
+      b.x + b.w > width + b.w * 0.5 ||
+      b.y + b.h > height + b.h * 0.5,
+  );
+  if (anyOffscreen) flags.push("offscreen");
+
+  if (bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)) {
+    flags.push("invisible");
+  }
+
+  if (dur < 0.2 && tw.props.some((p) => ["y", "x", "opacity", "scale"].includes(p))) {
+    flags.push("paced-fast");
+  }
+  if (dur > 2.0) flags.push("paced-slow");
+
+  return flags;
+}
+
+function markCollisions(tweens) {
+  for (let i = 0; i < tweens.length; i++) {
+    for (let j = i + 1; j < tweens.length; j++) {
+      const a = tweens[i];
+      const b = tweens[j];
+      if (a.end <= b.start || b.end <= a.start) continue;
+      for (const ba of a.bboxes) {
+        const bb = b.bboxes.find((x) => Math.abs(x.t - ba.t) < 0.05);
+        if (!bb) continue;
+        const overlap = rectOverlapArea(ba, bb);
+        const aArea = ba.w * ba.h;
+        if (aArea > 0 && overlap / aArea > 0.3) {
+          if (!a.flags.includes("collision")) a.flags.push("collision");
+          if (!b.flags.includes("collision")) b.flags.push("collision");
+          break;
+        }
+      }
+    }
+  }
+}
+
+function rectOverlapArea(a, b) {
+  const x1 = Math.max(a.x, b.x);
+  const y1 = Math.max(a.y, b.y);
+  const x2 = Math.min(a.x + a.w, b.x + b.w);
+  const y2 = Math.min(a.y + a.h, b.y + b.h);
+  return Math.max(0, x2 - x1) * Math.max(0, y2 - y1);
+}
+
+// ─── Composition-level analysis ─────────────────────────────────────────────
+
+function buildTimeline(tweens, duration) {
+  const cols = 60;
+  const lines = [];
+  const secPerCol = duration / cols;
+
+  lines.push("Timeline (" + duration.toFixed(1) + "s, each char ≈ " + secPerCol.toFixed(2) + "s):");
+  lines.push("  " + "0s" + " ".repeat(cols - 8) + duration.toFixed(0) + "s");
+  lines.push("  " + "┼" + "─".repeat(cols - 1) + "┤");
+
+  for (const tw of tweens) {
+    const startCol = Math.floor(tw.start / secPerCol);
+    const endCol = Math.min(cols, Math.ceil(tw.end / secPerCol));
+    const bar =
+      " ".repeat(startCol) +
+      "█".repeat(Math.max(1, endCol - startCol)) +
+      " ".repeat(Math.max(0, cols - endCol));
+    const label = tw.selector + " " + tw.props.join("+");
+    lines.push("  " + bar + "  " + label);
+  }
+
+  return lines.join("\n");
+}
+
+function computeDensity(tweens, duration) {
+  const buckets = [];
+  for (let t = 0; t < duration; t += 0.5) {
+    const active = tweens.filter((tw) => tw.start <= t + 0.5 && tw.end >= t);
+    buckets.push({ t: +t.toFixed(1), activeTweens: active.length });
+  }
+  return buckets;
+}
+
+function findDeadZones(density, duration) {
+  const zones = [];
+  let zoneStart = null;
+  for (const d of density) {
+    if (d.activeTweens === 0) {
+      if (zoneStart === null) zoneStart = d.t;
+    } else {
+      if (zoneStart !== null) {
+        const zoneEnd = d.t;
+        if (zoneEnd - zoneStart >= 1.0) {
+          zones.push({
+            start: zoneStart,
+            end: zoneEnd,
+            duration: +(zoneEnd - zoneStart).toFixed(1),
+            note:
+              "No animation for " +
+              (zoneEnd - zoneStart).toFixed(1) +
+              "s. Intentional hold or missing entrance?",
+          });
+        }
+        zoneStart = null;
+      }
+    }
+  }
+  if (zoneStart !== null && duration - zoneStart >= 1.0) {
+    zones.push({
+      start: zoneStart,
+      end: +duration.toFixed(1),
+      duration: +(duration - zoneStart).toFixed(1),
+      note:
+        "No animation for " +
+        (duration - zoneStart).toFixed(1) +
+        "s at end. Final hold or missing outro?",
+    });
+  }
+  return zones;
+}
+
+function detectStaggers(tweens) {
+  const groups = [];
+  const used = new Set();
+
+  for (let i = 0; i < tweens.length; i++) {
+    if (used.has(i)) continue;
+    const tw = tweens[i];
+    const group = [tw];
+    used.add(i);
+
+    for (let j = i + 1; j < tweens.length; j++) {
+      if (used.has(j)) continue;
+      const other = tweens[j];
+      const sameProps = tw.props.join(",") === other.props.join(",");
+      const sameDuration = Math.abs(tw.duration - other.duration) < 0.05;
+      const closeInTime = other.start - tw.start < tw.duration * 4;
+      if (sameProps && sameDuration && closeInTime) {
+        group.push(other);
+        used.add(j);
+      }
+    }
+
+    if (group.length >= 3) {
+      const intervals = [];
+      for (let k = 1; k < group.length; k++) {
+        intervals.push(+(group[k].start - group[k - 1].start).toFixed(3));
+      }
+      const avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+      const maxDrift = Math.max(...intervals.map((iv) => Math.abs(iv - avgInterval)));
+      const consistent = maxDrift < avgInterval * 0.3;
+
+      groups.push({
+        elements: group.map((g) => g.selector),
+        props: tw.props,
+        count: group.length,
+        intervals,
+        avgInterval: +avgInterval.toFixed(3),
+        consistent,
+        note: consistent
+          ? group.length +
+            " elements stagger at " +
+            (avgInterval * 1000).toFixed(0) +
+            "ms intervals"
+          : group.length +
+            " elements stagger with uneven intervals (" +
+            intervals.map((iv) => (iv * 1000).toFixed(0) + "ms").join(", ") +
+            ")",
+      });
+    }
+  }
+
+  return groups;
+}
+
+function buildElementLifecycles(tweens) {
+  const elements = {};
+  for (const tw of tweens) {
+    const sel = tw.selector;
+    if (!elements[sel]) {
+      elements[sel] = { firstTween: tw.start, lastTween: tw.end, tweenCount: 0, props: new Set() };
+    }
+    elements[sel].firstTween = Math.min(elements[sel].firstTween, tw.start);
+    elements[sel].lastTween = Math.max(elements[sel].lastTween, tw.end);
+    elements[sel].tweenCount++;
+    tw.props.forEach((p) => elements[sel].props.add(p));
+  }
+
+  const result = {};
+  for (const [sel, data] of Object.entries(elements)) {
+    const lastBbox = findLastBbox(tweens, sel);
+    result[sel] = {
+      firstAppears: +data.firstTween.toFixed(3),
+      lastAnimates: +data.lastTween.toFixed(3),
+      tweenCount: data.tweenCount,
+      props: [...data.props],
+      endsVisible: lastBbox ? lastBbox.opacity > 0.1 && lastBbox.visible : null,
+      finalPosition: lastBbox
+        ? { x: lastBbox.x, y: lastBbox.y, w: lastBbox.w, h: lastBbox.h }
+        : null,
+    };
+  }
+  return result;
+}
+
+function findLastBbox(tweens, selector) {
+  for (let i = tweens.length - 1; i >= 0; i--) {
+    if (tweens[i].selector === selector && tweens[i].bboxes?.length > 0) {
+      return tweens[i].bboxes[tweens[i].bboxes.length - 1];
+    }
+  }
+  return null;
+}
+
+async function captureSnapshots(session, tweens, duration) {
+  const times = [0, duration * 0.25, duration * 0.5, duration * 0.75, duration - 0.1];
+  const snapshots = [];
+
+  for (const t of times) {
+    await seekTo(session, t);
+    const visible = await session.page.evaluate(() => {
+      const out = [];
+      const els = document.querySelectorAll("[id]");
+      for (const el of els) {
+        const cs = getComputedStyle(el);
+        if (cs.display === "none") continue;
+        const opacity = parseFloat(cs.opacity);
+        if (opacity < 0.01) continue;
+        const rect = el.getBoundingClientRect();
+        if (rect.width < 1 || rect.height < 1) continue;
+        out.push({
+          id: el.id,
+          x: Math.round(rect.x),
+          y: Math.round(rect.y),
+          w: Math.round(rect.width),
+          h: Math.round(rect.height),
+          opacity: +opacity.toFixed(2),
+        });
+      }
+      return out;
+    });
+
+    const activeTweens = tweens
+      .filter((tw) => tw.start <= t && tw.end >= t)
+      .map((tw) => tw.selector);
+
+    snapshots.push({
+      t: +t.toFixed(2),
+      visibleElements: visible.length,
+      animatingNow: activeTweens,
+      elements: visible,
+    });
+  }
+
+  return snapshots;
+}
+
+// ─── Output ─────────────────────────────────────────────────────────────────
+
+function printSummary(report) {
+  console.log(
+    `\nAnimation map: ${report.mappedTweens}/${report.totalTweens} tweens (skipped ${report.skippedMicroTweens} micro-tweens)`,
+  );
+
+  const flagCounts = {};
+  for (const tw of report.tweens) {
+    for (const f of tw.flags) flagCounts[f] = (flagCounts[f] ?? 0) + 1;
+  }
+  if (Object.keys(flagCounts).length > 0) {
+    for (const [f, n] of Object.entries(flagCounts)) console.log(`  ${f}: ${n}`);
+  }
+  if (report.staggers?.length > 0) {
+    console.log(`  staggers: ${report.staggers.map((s) => s.note).join("; ")}`);
+  }
+  if (report.deadZones?.length > 0) {
+    console.log(
+      `  dead zones: ${report.deadZones.map((z) => z.start + "-" + z.end + "s").join(", ")}`,
+    );
+  }
+
+  console.log(report.choreography);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  let positional = 0;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      const v = argv[i + 1]?.startsWith("--") ? true : argv[++i];
+      out[k] = v;
+    } else if (positional === 0) {
+      out.composition = a;
+      positional++;
+    }
+  }
+  return out;
+}
+
+function die(msg) {
+  console.error(`animation-map: ${msg}`);
+  process.exit(2);
+}

skills/hyperframes/scripts/contrast-report.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// contrast-report.mjs — HyperFrames contrast audit
+//
+// Reads a composition, seeks to N sample timestamps, walks the DOM for text
+// elements, measures the WCAG 2.1 contrast ratio between each element's
+// declared foreground color and the pixels behind it, and emits:
+//
+//   - contrast-report.json  (machine-readable, one entry per text element × sample)
+//   - contrast-overlay.png  (sprite grid; magenta=fail AA, yellow=pass AA only, green=AAA)
+//
+// Usage:
+//   node skills/hyperframes/scripts/contrast-report.mjs <composition-dir> \
+//     [--samples N] [--out <dir>] [--width W] [--height H] [--fps N]
+//
+// The composition directory must contain an index.html. Raw authoring HTML
+// works — the producer's file server auto-injects the runtime at serve time.
+// Exits 1 if any text element fails WCAG AA.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { hyperframesPackageSpec, importPackagesOrBootstrap } from "./package-loader.mjs";
+
+// Use the producer's file server — it auto-injects the HyperFrames runtime
+// and render-seek bridge, so raw authoring HTML works without a build step.
+const packages = await importPackagesOrBootstrap(["@hyperframes/producer", "sharp"], {
+  npmPackages: [hyperframesPackageSpec("@hyperframes/producer"), "sharp@0.34.5"],
+});
+const sharp = packages.sharp.default;
+const {
+  createFileServer,
+  createCaptureSession,
+  initializeSession,
+  closeCaptureSession,
+  captureFrameToBuffer,
+  getCompositionDuration,
+} = packages["@hyperframes/producer"];
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.composition) die("missing <composition-dir>");
+
+const SAMPLES = Number(args.samples ?? 10);
+const OUT_DIR = resolve(args.out ?? ".hyperframes/contrast");
+const WIDTH = Number(args.width ?? 1920);
+const HEIGHT = Number(args.height ?? 1080);
+const FPS = Number(args.fps ?? 30);
+const COMP_DIR = resolve(args.composition);
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+await mkdir(OUT_DIR, { recursive: true });
+
+const server = await createFileServer({ projectDir: COMP_DIR, port: 0 });
+const session = await createCaptureSession(
+  server.url,
+  OUT_DIR,
+  { width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
+  null,
+);
+await initializeSession(session);
+
+try {
+  const duration = await getCompositionDuration(session);
+  const times = Array.from(
+    { length: SAMPLES },
+    (_, i) => +(((i + 0.5) / SAMPLES) * duration).toFixed(3),
+  );
+
+  const allEntries = [];
+  const overlayFrames = [];
+
+  for (let i = 0; i < times.length; i++) {
+    const t = times[i];
+    const { buffer: pngBuf } = await captureFrameToBuffer(session, i, t);
+    const elements = await probeTextElements(session, t);
+    const annotated = await annotateFrame(pngBuf, elements);
+    overlayFrames.push({ t, png: annotated });
+    for (const el of elements) allEntries.push({ time: t, ...el });
+  }
+
+  const report = {
+    composition: COMP_DIR,
+    width: WIDTH,
+    height: HEIGHT,
+    duration,
+    samples: times,
+    entries: allEntries,
+    summary: summarize(allEntries),
+  };
+
+  await writeFile(resolve(OUT_DIR, "contrast-report.json"), JSON.stringify(report, null, 2));
+  await writeOverlaySprite(overlayFrames, resolve(OUT_DIR, "contrast-overlay.png"));
+
+  printSummary(report);
+  process.exitCode = report.summary.failAA > 0 ? 1 : 0;
+} finally {
+  await closeCaptureSession(session).catch(() => {});
+  server.close();
+}
+
+// ─── DOM probe (runs in the page) ────────────────────────────────────────────
+
+async function probeTextElements(session, _t) {
+  // `session.page` is the Puppeteer Page owned by the capture session.
+  // We pass a pure function to `evaluate`: it walks the DOM and returns
+  // enough info for us to compute a ratio in Node using the frame buffer.
+  return await session.page.evaluate(() => {
+    /** @type {Array<{selector: string, text: string, fg: [number,number,number,number], fontSize: number, fontWeight: number, bbox: {x:number,y:number,w:number,h:number}}>} */
+    const out = [];
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+    const parseColor = (c) => {
+      const m = c.match(/rgba?\(([^)]+)\)/);
+      if (!m) return [0, 0, 0, 1];
+      const parts = m[1].split(",").map((s) => parseFloat(s.trim()));
+      return [parts[0], parts[1], parts[2], parts[3] ?? 1];
+    };
+    const selectorOf = (el) => {
+      if (el.id) return `#${el.id}`;
+      const cls = [...el.classList].slice(0, 2).join(".");
+      return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();
+    };
+    let el;
+    while ((el = walker.nextNode())) {
+      // must have direct text
+      const direct = [...el.childNodes].some(
+        (n) => n.nodeType === 3 && n.textContent.trim().length,
+      );
+      if (!direct) continue;
+      const cs = getComputedStyle(el);
+      if (cs.visibility === "hidden" || cs.display === "none") continue;
+      if (parseFloat(cs.opacity) <= 0.01) continue;
+      const rect = el.getBoundingClientRect();
+      if (rect.width < 8 || rect.height < 8) continue;
+      out.push({
+        selector: selectorOf(el),
+        text: el.textContent.trim().slice(0, 60),
+        fg: parseColor(cs.color),
+        fontSize: parseFloat(cs.fontSize),
+        fontWeight: Number(cs.fontWeight) || 400,
+        bbox: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
+      });
+    }
+    return out;
+  });
+}
+
+// ─── Pixel sampling + WCAG math ──────────────────────────────────────────────
+
+async function annotateFrame(pngBuf, elements) {
+  const img = sharp(pngBuf);
+  const meta = await img.metadata();
+  const { width, height } = meta;
+  const raw = await img.ensureAlpha().raw().toBuffer();
+  const channels = 4;
+
+  const measured = [];
+  for (const el of elements) {
+    const bg = sampleRingMedian(raw, width, height, channels, el.bbox);
+    const fg = compositeOver(el.fg, bg); // flatten any alpha against measured bg
+    const ratio = wcagRatio(fg, bg);
+    const large = isLargeText(el.fontSize, el.fontWeight);
+    el.bg = bg;
+    el.ratio = +ratio.toFixed(2);
+    el.wcagAA = large ? ratio >= 3 : ratio >= 4.5;
+    el.wcagAALarge = ratio >= 3;
+    el.wcagAAA = large ? ratio >= 4.5 : ratio >= 7;
+    measured.push(el);
+  }
+
+  // Draw boxes + ratio labels as an SVG overlay (sharp composite).
+  const svg = buildOverlaySVG(measured, width, height);
+  return await sharp(pngBuf)
+    .composite([{ input: Buffer.from(svg), top: 0, left: 0 }])
+    .png()
+    .toBuffer();
+}
+
+function sampleRingMedian(raw, width, height, channels, bbox) {
+  // 4-px ring immediately outside the element bbox. Median of each channel.
+  const r = [],
+    g = [],
+    b = [];
+  const x0 = Math.max(0, Math.floor(bbox.x) - 4);
+  const x1 = Math.min(width - 1, Math.ceil(bbox.x + bbox.w) + 4);
+  const y0 = Math.max(0, Math.floor(bbox.y) - 4);
+  const y1 = Math.min(height - 1, Math.ceil(bbox.y + bbox.h) + 4);
+  const pushPixel = (x, y) => {
+    const i = (y * width + x) * channels;
+    r.push(raw[i]);
+    g.push(raw[i + 1]);
+    b.push(raw[i + 2]);
+  };
+  for (let x = x0; x <= x1; x++) {
+    pushPixel(x, y0);
+    pushPixel(x, y1);
+  }
+  for (let y = y0; y <= y1; y++) {
+    pushPixel(x0, y);
+    pushPixel(x1, y);
+  }
+  return [median(r), median(g), median(b), 1];
+}
+
+function median(arr) {
+  const s = [...arr].sort((a, b) => a - b);
+  return s[Math.floor(s.length / 2)];
+}
+
+function compositeOver([fr, fg, fb, fa], [br, bg, bb]) {
+  return [
+    Math.round(fr * fa + br * (1 - fa)),
+    Math.round(fg * fa + bg * (1 - fa)),
+    Math.round(fb * fa + bb * (1 - fa)),
+    1,
+  ];
+}
+
+function relLum([r, g, b]) {
+  const ch = (v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b);
+}
+
+function wcagRatio(a, b) {
+  const la = relLum(a);
+  const lb = relLum(b);
+  const [L1, L2] = la > lb ? [la, lb] : [lb, la];
+  return (L1 + 0.05) / (L2 + 0.05);
+}
+
+function isLargeText(fontSize, fontWeight) {
+  return fontSize >= 24 || (fontSize >= 19 && fontWeight >= 700);
+}
+
+// ─── Overlay rendering ───────────────────────────────────────────────────────
+
+function buildOverlaySVG(elements, w, h) {
+  const rects = elements
+    .map((el) => {
+      const color = !el.wcagAA ? "#ff00aa" : !el.wcagAAA ? "#ffcc00" : "#00e08a";
+      const { x, y, w: bw, h: bh } = el.bbox;
+      return `
+        <rect x="${x}" y="${y}" width="${bw}" height="${bh}"
+              fill="none" stroke="${color}" stroke-width="3"/>
+        <rect x="${x}" y="${y - 18}" width="${48}" height="16" fill="${color}"/>
+        <text x="${x + 4}" y="${y - 5}" font-family="monospace" font-size="12" fill="#000">
+          ${el.ratio.toFixed(1)}:1
+        </text>`;
+    })
+    .join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">${rects}</svg>`;
+}
+
+async function writeOverlaySprite(frames, outPath) {
+  if (!frames.length) return;
+  const cols = Math.min(frames.length, 5);
+  const rows = Math.ceil(frames.length / cols);
+  const { width, height } = await sharp(frames[0].png).metadata();
+  const scale = 0.25;
+  const cellW = Math.round(width * scale);
+  const cellH = Math.round(height * scale);
+
+  const cells = await Promise.all(
+    frames.map(async (f) => ({
+      input: await sharp(f.png).resize(cellW, cellH).png().toBuffer(),
+      time: f.t,
+    })),
+  );
+
+  const composites = cells.map((c, i) => ({
+    input: c.input,
+    top: Math.floor(i / cols) * cellH,
+    left: (i % cols) * cellW,
+  }));
+
+  await sharp({
+    create: {
+      width: cols * cellW,
+      height: rows * cellH,
+      channels: 3,
+      background: { r: 16, g: 16, b: 20 },
+    },
+  })
+    .composite(composites)
+    .png()
+    .toFile(outPath);
+}
+
+// ─── Summary ────────────────────────────────────────────────────────────────
+
+function summarize(entries) {
+  const total = entries.length;
+  const failAA = entries.filter((e) => !e.wcagAA).length;
+  const passAAonly = entries.filter((e) => e.wcagAA && !e.wcagAAA).length;
+  const passAAA = entries.filter((e) => e.wcagAAA).length;
+  return { total, failAA, passAAonly, passAAA };
+}
+
+function printSummary({ summary, entries }) {
+  const { total, failAA, passAAonly, passAAA } = summary;
+  console.log(`\nContrast report: ${total} text-element samples`);
+  console.log(`  fail WCAG AA:     ${failAA}`);
+  console.log(`  pass AA, not AAA: ${passAAonly}`);
+  console.log(`  pass AAA:         ${passAAA}`);
+  if (failAA) {
+    console.log("\nFailures:");
+    for (const e of entries.filter((x) => !x.wcagAA)) {
+      console.log(`  t=${e.time}s  ${e.selector.padEnd(24)}  ${e.ratio.toFixed(2)}:1  "${e.text}"`);
+    }
+  }
+}
+
+// ─── Utilities ──────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = {};
+  let positional = 0;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      const v = argv[i + 1]?.startsWith("--") ? true : argv[++i];
+      out[k] = v;
+    } else if (positional === 0) {
+      out.composition = a;
+      positional++;
+    }
+  }
+  return out;
+}
+
+function die(msg) {
+  console.error(`contrast-report: ${msg}`);
+  process.exit(2);
+}

skills/hyperframes/scripts/package-loader.mjs

@@ -0,0 +1,269 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { basename, delimiter, dirname, join, parse, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BOOTSTRAP_ENV = "HYPERFRAMES_SKILL_DEPS_BOOTSTRAPPED";
+const BOOTSTRAP_CONFIRM_ENV = "HYPERFRAMES_SKILL_BOOTSTRAP_DEPS";
+const NODE_MODULES_ENV = "HYPERFRAMES_SKILL_NODE_MODULES";
+
+export async function importPackagesOrBootstrap(packageNames, options = {}) {
+  const entries = new Map();
+  const missing = [];
+
+  for (const packageName of packageNames) {
+    const entry = resolvePackageEntry(packageName);
+    if (entry) entries.set(packageName, entry);
+    else missing.push(packageName);
+  }
+
+  if (missing.length > 0 && !process.env[BOOTSTRAP_ENV]) {
+    const npmPackages = options.npmPackages ?? missing;
+    assertPinnedPackageSpecs(npmPackages);
+    await confirmBootstrap(npmPackages);
+    bootstrapWithNpmInstall(npmPackages);
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      [
+        `Could not resolve required package(s): ${missing.join(", ")}`,
+        "Install them in this project, for example:",
+        `  npm install --save-dev ${packageNames.map(shellQuote).join(" ")}`,
+      ].join("\n"),
+    );
+  }
+
+  const modules = {};
+  for (const [packageName, entry] of entries) {
+    modules[packageName] = await import(pathToFileURL(entry).href);
+  }
+  return modules;
+}
+
+export function hyperframesPackageSpec(packageName) {
+  const version = readBundledHyperframesVersion();
+  if (!version) {
+    throw new Error(
+      [
+        `Could not determine the bundled HyperFrames version for ${packageName}.`,
+        "Install the package yourself or pass a pinned options.npmPackages entry.",
+      ].join("\n"),
+    );
+  }
+  return `${packageName}@${version}`;
+}
+
+function resolvePackageEntry(packageName) {
+  const bases = [process.cwd(), HERE, ...envNodeModulesDirs(), ...nodeModulesDirsFromPath()];
+
+  const seen = new Set();
+  for (const base of bases) {
+    const normalized = resolve(base);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+
+    try {
+      return createRequire(join(normalized, "__hyperframes_skill_loader__.cjs")).resolve(
+        packageName,
+      );
+    } catch {
+      const packageDir = findPackageDir(normalized, packageName);
+      const packageEntry = packageDir ? readPackageEntry(packageDir) : null;
+      if (packageEntry) return packageEntry;
+    }
+  }
+
+  return null;
+}
+
+function readBundledHyperframesVersion() {
+  for (const ancestor of ancestors(HERE)) {
+    const directVersion = readPackageVersion(join(ancestor, "package.json"));
+    if (directVersion) return directVersion;
+
+    const monorepoCliVersion = readPackageVersion(
+      join(ancestor, "packages", "cli", "package.json"),
+    );
+    if (monorepoCliVersion) return monorepoCliVersion;
+  }
+  return null;
+}
+
+function readPackageVersion(packageJsonPath) {
+  try {
+    const manifest = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (manifest.name === "hyperframes" || manifest.name === "@hyperframes/cli") {
+      return typeof manifest.version === "string" ? manifest.version : null;
+    }
+  } catch {
+    // Keep searching ancestor package manifests.
+  }
+  return null;
+}
+
+function envNodeModulesDirs() {
+  return (process.env[NODE_MODULES_ENV] ?? "").split(delimiter).filter(Boolean);
+}
+
+function nodeModulesDirsFromPath() {
+  const dirs = [];
+  for (const entry of (process.env.PATH ?? "").split(delimiter)) {
+    if (!entry.endsWith(`${join("node_modules", ".bin")}`)) continue;
+    dirs.push(dirname(entry));
+  }
+  return dirs;
+}
+
+function findPackageDir(base, packageName) {
+  const packageSegments = packageName.split("/");
+  const roots =
+    basename(base) === "node_modules"
+      ? [base]
+      : ancestors(base).map((ancestor) => join(ancestor, "node_modules"));
+
+  for (const root of roots) {
+    const packageDir = join(root, ...packageSegments);
+    if (existsSync(join(packageDir, "package.json"))) return packageDir;
+  }
+  return null;
+}
+
+function readPackageEntry(packageDir) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+    const entry = exportEntry(manifest.exports) ?? manifest.module ?? manifest.main ?? "index.js";
+    const entryPath = join(packageDir, entry);
+    return existsSync(entryPath) ? entryPath : null;
+  } catch {
+    return null;
+  }
+}
+
+function exportEntry(exports) {
+  const root =
+    typeof exports === "object" && exports !== null ? (exports["."] ?? exports) : exports;
+  if (typeof root === "string") return root;
+  if (typeof root !== "object" || root === null) return null;
+  if (typeof root.import === "string") return root.import;
+  if (typeof root.default === "string") return root.default;
+  if (typeof root.node === "string") return root.node;
+  if (typeof root.node === "object" && root.node !== null) {
+    return root.node.import ?? root.node.default ?? null;
+  }
+  return null;
+}
+
+function assertPinnedPackageSpecs(packageSpecs) {
+  const unpinned = packageSpecs.filter((spec) => !hasVersionSpec(spec));
+  if (unpinned.length === 0) return;
+  throw new Error(
+    [
+      `Refusing to bootstrap unpinned package spec(s): ${unpinned.join(", ")}`,
+      "Pass pinned npm package specs, for example:",
+      `  ${packageSpecs.map((spec) => (hasVersionSpec(spec) ? spec : `${spec}@<version>`)).join(" ")}`,
+    ].join("\n"),
+  );
+}
+
+function hasVersionSpec(packageSpec) {
+  if (packageSpec.startsWith("@")) {
+    const slash = packageSpec.indexOf("/");
+    return slash !== -1 && packageSpec.indexOf("@", slash + 1) !== -1;
+  }
+  return packageSpec.includes("@");
+}
+
+async function confirmBootstrap(packageSpecs) {
+  if (process.env[BOOTSTRAP_CONFIRM_ENV] === "1") return;
+
+  const installLine = `npm install --ignore-scripts --no-save ${packageSpecs.map(shellQuote).join(" ")}`;
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      [
+        "Required helper package(s) are missing.",
+        "To allow a one-time temporary dependency bootstrap for this run, set:",
+        `  ${BOOTSTRAP_CONFIRM_ENV}=1`,
+        "The bootstrap command will be:",
+        `  ${installLine}`,
+      ].join("\n"),
+    );
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await rl.question(
+      [
+        "HyperFrames helper package(s) are missing.",
+        `Run a temporary install with lifecycle scripts disabled?`,
+        `  ${installLine}`,
+        "Proceed? [y/N] ",
+      ].join("\n"),
+    );
+    if (!/^(y|yes)$/i.test(answer.trim())) {
+      throw new Error("Dependency bootstrap cancelled.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function ancestors(start) {
+  const dirs = [];
+  let current = resolve(start);
+  const root = parse(current).root;
+  while (current && current !== root) {
+    dirs.push(current);
+    current = dirname(current);
+  }
+  dirs.push(root);
+  return dirs;
+}
+
+function bootstrapWithNpmInstall(packageNames) {
+  const installRoot = mkdtempSync(join(tmpdir(), "hyperframes-skill-deps-"));
+  const installResult = spawnSync(
+    process.platform === "win32" ? "npm.cmd" : "npm",
+    [
+      "install",
+      "--silent",
+      "--no-audit",
+      "--no-fund",
+      "--ignore-scripts",
+      "--no-save",
+      "--prefix",
+      installRoot,
+      ...packageNames,
+    ],
+    { stdio: "inherit" },
+  );
+
+  if (installResult.error) throw installResult.error;
+  if (installResult.status !== 0) {
+    rmSync(installRoot, { recursive: true, force: true });
+    process.exit(installResult.status ?? 1);
+  }
+
+  const args = [...process.argv.slice(1)];
+  const result = spawnSync(process.execPath, args, {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      [BOOTSTRAP_ENV]: "1",
+      [NODE_MODULES_ENV]: join(installRoot, "node_modules"),
+    },
+  });
+
+  rmSync(installRoot, { recursive: true, force: true });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

skills/hyperframes/visual-styles.md

@@ -0,0 +1,211 @@
+# Visual Style Library
+
+Named visual identities for HyperFrames videos. Each style is grounded in a real graphic design tradition. Use them to give your video a specific visual personality, not just generic "clean" or "bold."
+
+**How to pick:** Match mood first, content second. Ask: _"What should the viewer FEEL?"_
+
+**How to use:** Reference the style in your scene plan. Translate the style's principles into concrete composition decisions — palette choice, font selection, entrance patterns, transition type, ambient motion feel.
+
+## Quick Reference
+
+| Style           | Mood                  | Best for                           | Primary shader                    |
+| --------------- | --------------------- | ---------------------------------- | --------------------------------- |
+| Swiss Pulse     | Clinical, precise     | SaaS, data, dev tools, metrics     | Cinematic Zoom or SDF Iris        |
+| Velvet Standard | Premium, timeless     | Luxury, enterprise, keynotes       | Cross-Warp Morph                  |
+| Deconstructed   | Industrial, raw       | Tech launches, security, punk      | Glitch or Whip Pan                |
+| Maximalist Type | Loud, kinetic         | Big announcements, launches        | Ridged Burn                       |
+| Data Drift      | Futuristic, immersive | AI, ML, cutting-edge tech          | Gravitational Lens or Domain Warp |
+| Soft Signal     | Intimate, warm        | Wellness, personal stories, brand  | Thermal Distortion                |
+| Folk Frequency  | Cultural, vivid       | Consumer apps, food, communities   | Swirl Vortex or Ripple Waves      |
+| Shadow Cut      | Dark, cinematic       | Dramatic reveals, security, exposé | Domain Warp                       |
+
+---
+
+## 1. Swiss Pulse — Josef Müller-Brockmann
+
+**Mood:** Clinical, precise | **Best for:** SaaS dashboards, developer tools, APIs, metrics
+
+- Black (`#1a1a1a`), white, ONE accent — electric blue (`#0066FF`) or amber (`#FFB300`)
+- Helvetica or Inter Bold for headlines, Regular for labels. Numbers large (80–120px)
+- Grid-locked compositions. Every element snaps to an invisible 12-column grid
+- Animated counters count up from 0. Hard cuts, no decorative transitions
+- Transitions: Cinematic Zoom or SDF Iris (precise, geometric)
+
+**GSAP signature:** `expo.out`, `power4.out`. Entries are fast and snap into place. Nothing floats.
+
+```
+Swiss Pulse: Black/white + one electric accent. Grid-locked compositions.
+Numbers dominate the frame at 80-120px. Counter animations from 0.
+Hard cuts or geometric transitions. Nothing decorative.
+```
+
+---
+
+## 2. Velvet Standard — Massimo Vignelli
+
+**Mood:** Premium, timeless | **Best for:** Luxury products, enterprise software, keynotes, investor decks
+
+- Black, white, ONE rich accent — deep navy (`#1a237e`) or gold (`#c9a84c`)
+- Thin sans-serif, ALL CAPS, wide letter-spacing (`0.15em+`)
+- Generous negative space. Symmetrical, centered, architectural precision
+- Slow, deliberate. Sequential reveals with long holds. No frantic motion
+- Transitions: Cross-Warp Morph (elegant, organic flow between scenes)
+
+**GSAP signature:** `sine.inOut`, `power1`. Nothing snaps — everything glides with intention.
+
+```
+Velvet Standard: Black, white, one rich accent. Thin ALL CAPS type with wide tracking.
+Generous negative space. Sequential reveals, long holds.
+Cross-Warp Morph transitions. Slow and deliberate — luxury takes its time.
+```
+
+---
+
+## 3. Deconstructed — Neville Brody
+
+**Mood:** Industrial, raw | **Best for:** Tech news, developer launches, security products, punk-energy reveals
+
+- Dark grey (`#1a1a1a`), rust orange (`#D4501E`), raw white (`#f0f0f0`)
+- Type at angles, overlapping edges, escaping frames. Bold industrial weight
+- Gritty textures: scan-line effects, glitch artifacts baked into the design
+- Text SLAMS and SHATTERS. Letters scramble then snap to final position
+- Transitions: Glitch shader or Whip Pan (breaks the rules, feels aggressive)
+
+**GSAP signature:** `back.out(2.5)`, `steps(8)`, `elastic.out(1.2, 0.4)`. Intentional irregularity.
+
+```
+Deconstructed: Dark grey #1a1a1a + rust orange #D4501E. Type at angles, escaping frames.
+Scan-line glitch overlays. Text SLAMS and scrambles into place.
+Glitch shader transitions. Industrial and raw — nothing should feel polished.
+```
+
+---
+
+## 4. Maximalist Type — Paula Scher
+
+**Mood:** Loud, kinetic | **Best for:** Big product launches, milestone announcements, high-energy hype videos
+
+- Bold saturated: red (`#E63946`), yellow (`#FFD60A`), black, white — maximum contrast
+- Text IS the visual. Overlapping type layers at different scales and angles, filling 50–80% of frame
+- Everything is kinetic: slamming, sliding, scaling. 2–3 second rapid-fire scenes
+- Text layered OVER footage — never empty backgrounds
+- Transitions: Ridged Burn (explosive, dramatic, impossible to ignore)
+
+**GSAP signature:** `expo.out`, `back.out(1.8)`. Fast arrivals, hard stops.
+
+```
+Maximalist Type: Red, yellow, black, white — max contrast. Text IS the visual.
+Overlapping at different scales, 50-80% of frame. Everything in motion.
+Ridged Burn transitions. No static moments — kinetic energy throughout.
+```
+
+---
+
+## 5. Data Drift — Refik Anadol
+
+**Mood:** Futuristic, immersive | **Best for:** AI products, ML platforms, data companies, speculative tech
+
+- Iridescent: deep black (`#0a0a0a`), electric purple (`#7c3aed`), cyan (`#06b6d4`)
+- Thin futuristic sans-serif — floating, weightless, minimal
+- Fluid morphing compositions. Extreme scale shifts (micro → macro)
+- Particles coalesce into numbers. Light traces data paths through the frame
+- Transitions: Gravitational Lens or Domain Warp (otherworldly distortion)
+
+**GSAP signature:** `sine.inOut`, `power2.out`. Smooth, continuous, organic. Nothing hard.
+
+```
+Data Drift: Deep black #0a0a0a with electric purple #7c3aed and cyan #06b6d4.
+Thin futuristic type, minimal text. Particles coalesce into numbers.
+Gravitational Lens or Domain Warp transitions. Fluid, immersive, otherworldly.
+```
+
+---
+
+## 6. Soft Signal — Stefan Sagmeister
+
+**Mood:** Intimate, warm | **Best for:** Wellness brands, personal stories, lifestyle products, human-centered apps
+
+- Warm amber (`#F5A623`), cream (`#FFF8EC`), dusty rose (`#C4A3A3`), sage green (`#8FAF8C`)
+- Handwritten-style or humanist serif fonts. Personal, lowercase, delicate
+- Close-up framing feel: single element fills the frame. Nothing feels corporate
+- Slow drifts and floats, never snaps. Soft organic motion throughout
+- Transitions: Thermal Distortion (warm, flowing, like heat shimmer)
+
+**GSAP signature:** `sine.inOut`, `power1.inOut`. Everything breathes.
+
+```
+Soft Signal: Warm amber, cream, dusty rose, sage green. Humanist or handwritten type.
+Single elements fill the frame — intimate, never corporate.
+Slow drifts and floats throughout. Thermal Distortion transitions.
+Nothing should feel hurried or polished.
+```
+
+---
+
+## 7. Folk Frequency — Eduardo Terrazas
+
+**Mood:** Cultural, vivid | **Best for:** Consumer apps, food platforms, community products, festive launches
+
+- Vivid folk: hot pink (`#FF1493`), cobalt blue (`#0047AB`), sun yellow (`#FFE000`), emerald (`#009B77`)
+- Bold warm rounded type. Pattern and repetition — folk art rhythm and density
+- Layered compositions with rich visual texture. Every frame feels handcrafted
+- Colorful motion: elements bounce, pop, and spin into place with joy
+- Transitions: Swirl Vortex or Ripple Waves (hypnotic, celebratory)
+
+**GSAP signature:** `back.out(1.6)`, `elastic.out(1, 0.5)`. Overshoots feel intentional.
+
+```
+Folk Frequency: Hot pink #FF1493, cobalt blue, sun yellow, emerald. Bold rounded type.
+Pattern and repetition throughout. Layered, dense, handcrafted feeling.
+Swirl Vortex or Ripple Waves transitions. Joyful, celebratory energy.
+```
+
+---
+
+## 8. Shadow Cut — Hans Hillmann
+
+**Mood:** Dark, cinematic | **Best for:** Security products, dramatic reveals, investigative content, intense launches
+
+- Near-monochrome: deep blacks (`#0a0a0a`), cold greys (`#3a3a3a`), stark white + blood red (`#C1121F`) or toxic green (`#39FF14`)
+- Sharp angular text like film noir title cards. Heavy contrast, no softness
+- Heavy shadow — elements emerge from darkness. Reveal is the narrative
+- Slow creeping push-ins, dramatic scale reveals, silence before the hit
+- Transitions: Domain Warp (dissolves reality itself before revealing the next scene)
+
+**GSAP signature:** `power4.in` for exits, `power3.out` for dramatic reveals. The pause before the hit matters.
+
+```
+Shadow Cut: Deep blacks #0a0a0a, cold greys, stark white + one accent (blood red or toxic green).
+Sharp angular type, film noir aesthetic. Elements emerge from darkness.
+Slow creeping push-ins. Domain Warp transitions. The reveal IS the story.
+```
+
+---
+
+## Mood → Style Guide
+
+| If the content feels...            | Use...          |
+| ---------------------------------- | --------------- |
+| Data-driven, analytical, technical | Swiss Pulse     |
+| Premium, enterprise, luxury        | Velvet Standard |
+| Raw, punk, aggressive, rebellious  | Deconstructed   |
+| Hype, loud, high-energy launch     | Maximalist Type |
+| AI, ML, speculative, futuristic    | Data Drift      |
+| Human, warm, personal, wellness    | Soft Signal     |
+| Cultural, fun, consumer, festive   | Folk Frequency  |
+| Dark, dramatic, intense, cinematic | Shadow Cut      |
+
+---
+
+## Creating Custom Styles
+
+These 8 styles are examples — not constraints. Create your own by:
+
+1. **Name it** after a designer, art movement, or cultural reference
+2. **Palette**: 2-3 colors max. Declare explicit hex values
+3. **Typography**: One family, two weights. State the role of each
+4. **Motion rules**: How fast? Snappy or fluid? Overshoot or precision?
+5. **Transition**: Which shader matches the energy?
+6. **What NOT to do**: 2-3 explicit anti-patterns for this style
+
+The pattern: **named style → palette → typography → motion rules → transition → avoids.**