feat: HyperFrames-grade video design bar — vendored craft references + catalog vocabulary (#550)

* feat(motion): demo-register visual design bar, vendored craft references, catalog vocabulary index

* fix(motion): correct design-bar composition claims after adversarial fact-check

* docs(map,rag): design-bar, vendored references, and catalog index on the video-engine surfaces

---------

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

motion/skills/references/beat-direction.md

@@ -0,0 +1,167 @@
+<!-- Vendored from https://github.com/heygen-com/hyperframes (skills/hyperframes-creative/references/beat-direction.md @ 9d148d28, Apache-2.0).
+     Reference doc hyperframes-creative.md points at for non-trivial compositions. Re-vendor when bumping @hyperframes/producer, then run make reflow-docs (prose is reflowed to house style). -->
+
+# Beat Direction
+
+How to plan and direct individual scenes (beats) in a multi-scene composition. Read before writing any multi-scene video.
+
+## Contents
+
+- Per-beat direction
+- Concept
+- Mood direction
+- Animation choreography
+- Transition
+- Depth layers
+- SFX cues
+- Rhythm planning
+- Velocity-matched transitions
+
+---
+
+## Per-Beat Direction
+
+Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:
+
+- **Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right."
+- **Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."
+
+The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.
+
+Each beat should have:
+
+### Concept
+
+The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.
+
+### Mood direction
+
+Cultural and design references, not hex codes:
+
+- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."
+- "Warm workspace. Nice notebook energy, not technical blueprint."
+- "Cinematic title sequence. The kind of opening where you lean forward."
+
+### Animation choreography
+
+Specific motion verbs per element — not "it animates in" but HOW. Verbs come from the beat's concept and content, not from an energy bucket. A wellness brand's "slow" beat might still have something that DROPS if the content is about letting go. A stats beat might FLOAT if the brand's identity is weightless.
+
+The vocabulary of motion verbs (organized by physical character, not by energy level):
+
+- **Impact / weight:** SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS, DROPS (with force)
+- **Directional / deliberate:** SLIDES, PUSHES, PULLS, WIPES, CUTS
+- **Reveals / builds:** DRAWS, FILLS, GROWS, EXPANDS, ASSEMBLES, COUNTS UP
+- **Organic / ambient:** FLOATS, DRIFTS, BREATHES, PULSES, ORBITS, MORPHS
+- **Mechanical / precise:** TYPES ON, CLICKS, LOCKS IN, SNAPS, STEPS
+
+Every element gets a verb. If you can't name the verb, the element is not yet designed. The verb should follow from the beat's concept — not from a lookup of what "high energy" or "low energy" beats use.
+
+For text elements specifically, you can name a deterministic, named effect by ID (e.g. `typewriter`, `kinetic-center-build`, `soft-blur-in`) instead of inventing timing from scratch — the 24-effect vocabulary and how to load it live in `skills/hyperframes-animation/adapters/animate-text.md`.
+
+### Transition
+
+How this beat hands off to the next. Specify the type and parameters.
+
+**When to pick which:**
+
+| Choose shader transition for                                                    | Choose CSS transition for                                                           | Choose hard cut for                                            |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing |
+| Any moment the music/VO punctuates with a downbeat or SFX hit                   | Beats that ease from one composition into the next with shared motion vocabulary    | Sequences of 3+ quick tempo-matched switches                   |
+| Brand moments where the transition itself _is_ the visual                       | Minimal/editorial pacing                                                            | Anytime a 0.3-0.8s transition would feel too slow              |
+
+Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, a CSS crossfade is fine. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) — too many flatten their impact.
+
+**Mixing shader and CSS crossfade transitions in one composition is supported.** Omit `shader` on any transition entry to get a smooth opacity crossfade — HyperShader manages all scene visibility regardless. Let HyperShader create the timeline (don't pass a pre-built `timeline:` option) and add all composition tweens to the returned `tl` after `init()`. Config snippet in `skills/hyperframes-animation/transitions/overview.md` → "CSS vs Shader".
+
+**CSS transitions** — 30+ patterns across 13 categories. Full code in `skills/hyperframes-animation/transitions/` (route via `catalog.md`). Pick based on the energy and feel:
+
+| Category           | Patterns                                                                 | Motion character                                                           |
+| ------------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| **Push / slide**   | Push slide, vertical push, elastic push, squeeze                         | Content moves through the frame as if on a continuous surface              |
+| **Scale / zoom**   | Zoom through, zoom out                                                   | Perspective shifts — moving toward or away from content                    |
+| **Radial / clip**  | Circle iris, diamond iris, diagonal split                                | Geometric reveal — content emerges or is covered by a shape                |
+| **3D**             | 3D card flip                                                             | Physical — content flips like a tangible object                            |
+| **Dissolve**       | Crossfade, blur crossfade, focus pull, color dip                         | Overlap and blend — both scenes exist simultaneously during the transition |
+| **Cover / blinds** | Staggered color blocks, horizontal blinds (6/12 strips), vertical blinds | Structural — content is sliced, layered, or covered                        |
+| **Light**          | Light leak overlays, overexposure burn, film burn                        | Organic film — light bleeds across the frame                               |
+| **Distortion**     | Glitch (CSS RGB jitter), chromatic aberration, ripple, VHS tape          | Instability — the image itself appears to malfunction                      |
+| **Blur**           | Blur through, directional blur                                           | Soft defocus — content blurs in or out                                     |
+| **Mechanical**     | Shutter (two-half), clock wipe (9-point wedge)                           | Precision — transitions with visible mechanical logic                      |
+| **Grid**           | Grid dissolve (12/120 cells)                                             | Fragmentation — the frame breaks into pieces                               |
+| **Destruction**    | Page burn (SVG clip-path + canvas rim)                                   | Dramatic decay — the previous scene is destroyed                           |
+| **Other**          | Gravity drop, morph circle                                               | Physical or shape-based motion that doesn't fit other categories           |
+
+Common quick-picks:
+
+- **Velocity-matched upward**: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out`
+- **Whip pan**: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out`
+- **Blur through**: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out`
+- **Zoom through**: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`
+- **Hard cut / smash cut**: instant, for rapid-fire sequences
+
+Timing presets: snappy (0.2s), smooth (0.4s), gentle (0.6s), dramatic (0.5s), instant (0.15s), luxe (0.7s).
+
+**Shader transitions** — 14 built-in WebGL GPU effects. Install with `npx hyperframes add <name>` (block name ≠ shader name — see `skills/hyperframes-registry/references/discovery.md`); full API in `packages/shader-transitions/README.md`.
+
+| Shader                  | Visual description                                                                             | Duration range |
+| ----------------------- | ---------------------------------------------------------------------------------------------- | -------------- |
+| **domain-warp**         | Organic FBM dissolve — both scenes warp toward each other with an accent flash at the midpoint | 0.5–0.8s       |
+| **ridged-burn**         | Multifractal mask reveals the incoming scene through a burn ramp with sparks at the edge       | 0.5–0.8s       |
+| **whip-pan**            | 10-sample horizontal motion blur + lateral crossfade — reads like a camera pan between shots   | 0.3–0.5s       |
+| **sdf-iris**            | Circle SDF expands from center, with accent-tinted glow rings at the expanding edge            | 0.5–0.7s       |
+| **ripple-waves**        | Radial standing-wave UV displacement — content ripples outward as scenes cross                 | 0.6–1.0s       |
+| **gravitational-lens**  | Pinch pull toward center + R/B chromatic separation — content bends inward then releases       | 0.6–1.0s       |
+| **cinematic-zoom**      | 12 RGB-offset radial zoom blur samples — motion streak radiating from center                   | 0.4–0.6s       |
+| **chromatic-split**     | R/B radial channel shift outward, G fixed — channels separate then rejoin                      | 0.3–0.5s       |
+| **swirl-vortex**        | CCW swirl with FBM noise — content spirals away and the new scene spirals in                   | 0.5–0.8s       |
+| **thermal-distortion**  | Vertical sine + FBM horizontal displacement — heat-haze shimmer across the frame               | 0.5–0.8s       |
+| **flash-through-white** | Fade through white midpoint — almost invisible at 0.01s, noticeable at 0.3s                    | 0.01s–0.3s     |
+| **cross-warp-morph**    | FBM vector field displaces both scenes; a third FBM biases the wipe direction                  | 0.5–0.8s       |
+| **light-leak**          | Fixed off-frame light source with exponential falloff, warmth, and a ridge flare               | 0.5–0.8s       |
+| **glitch**              | Line displacement + RGB lateral split + scan modulation + posterization + flicker              | 0.3–0.5s       |
+
+**You are not limited to what's listed here.** These are the built-in options, but you can and should:
+
+- **Write custom GLSL shaders** from scratch for unique transition effects
+- **Search online** for shader code (ShaderToy, GLSL Sandbox, GitHub) and adapt it
+- **Build custom CSS transitions** that aren't in any category — combine clip-path, transforms, filters in new ways
+- **Ask the user** to provide or find specific effects if you need something specialized
+
+If the storyboard calls for an effect that doesn't exist yet — build it. The framework renders anything a browser can run.
+
+### Depth layers
+
+What's in foreground, midground, and background. Every beat should have at least 2 layers:
+
+- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."
+
+### SFX cues
+
+What sounds at what moment:
+
+- "On the capture pulse — a soft, warm analog shutter click."
+- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."
+
+---
+
+## Rhythm Planning
+
+Before writing HTML, declare your scene rhythm: which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern — fast-fast-SLOW-fast-SHADER-hold — before implementing.
+
+**Derive the rhythm from the storyboard and the brand, not from a lookup.** A 15-second social ad for an architectural firm and a 15-second social ad for a gaming brand have different rhythms — both are 15 seconds, but one is slow-reveal-hold-CTA and the other is rapid-fire-SLAM-hook. Video type sets constraints (duration, approximate beat count); the brand and content determine whether those beats are slow or fast, sparse or dense, dramatic or controlled.
+
+Questions that drive rhythm decisions:
+
+- What emotional journey should the viewer take? Where is the peak moment?
+- Where does the narration land its heaviest emphasis? That's usually where energy should peak.
+- What does the brand's own visual pacing suggest — unhurried or urgent?
+- How many beats can the duration actually support without feeling rushed or padded?
+
+A social ad that tries to hook in 2s, showcase 3 features, and end with a CTA in 15s will feel like noise. Sometimes "hook-hold-CTA" with one strong feature is the right rhythm for 15 seconds. Name the rhythm you've planned before implementing.
+
+---
+
+## Velocity-Matched Transitions
+
+Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.

motion/skills/references/house-style.md

@@ -0,0 +1,76 @@
+<!-- Vendored from https://github.com/heygen-com/hyperframes (skills/hyperframes-creative/references/house-style.md @ 9d148d28, Apache-2.0).
+     Reference doc hyperframes-creative.md points at for non-trivial compositions. Re-vendor when bumping @hyperframes/producer, then run make reflow-docs (prose is reflowed to house style). -->
+
+# House Style
+
+Creative direction for compositions when no design spec (`frame.md` or `design.md`) is provided. These are starting points — override anything that doesn't serve the content. When a design spec exists, its brand values take precedence; house-style fills gaps.
+
+## 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 check` (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.
+
+**Decorative count vs motion count.** The "2-5 per scene" count refers to decorative _elements_. If a project's design spec says "single ambient motion per scene", it means one looping motion applied to these decoratives (a shared breath/drift/pulse) — not one element total. A scene with 4 decoratives sharing one breathing motion is correct; a scene with 1 decorative is under-dressed.
+
+## 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.

motion/skills/references/motion-principles.md

@@ -0,0 +1,153 @@
+<!-- Vendored from https://github.com/heygen-com/hyperframes (skills/hyperframes-creative/references/motion-principles.md @ 9d148d28, Apache-2.0).
+     Reference doc hyperframes-creative.md points at for non-trivial compositions. Re-vendor when bumping @hyperframes/producer, then run make reflow-docs (prose is reflowed to house style). -->
+
+# Motion Principles
+
+## Contents
+
+- Guardrails
+- What you do not do without being told
+- Visual composition
+- Image motion treatment
+- Load-bearing GSAP rules
+
+## 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).
+
+## Image Motion Treatment
+
+Never embed a raw flat image. Every image must have motion treatment:
+
+- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it.
+- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic
+- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow`
+- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax
+- **Scroll reveal**: Clip the image to a viewport window and animate `y` position
+
+## Load-Bearing GSAP Rules
+
+Rules below came out of two independent website capture builds (2026-04-20) where compositions lint-clean and still ship broken — elements that never appear, ambient motion that doesn't scrub, entrance tweens that silently kill their target. The linter cannot catch these; the rules must be followed by the author.
+
+- **No iframes for captured content.** Iframes do not seek deterministically with the timeline — the capture engine cannot scrub inside them, so they appear frozen (or blank) in the rendered output. If the source you're stylizing is a live web app, use the screenshots from `capture/` as stacked panels or layered images, not live embeds.
+
+- **Never overlap conflicting transform tweens on the same element.** Sequential, non-overlapping transform phases are valid. The dangerous case is concurrent tweens or `from()` tweens whose `immediateRender` states overwrite one another: for example, a `y` entrance plus a simultaneous `scale` Ken Burns tween on the same `<img>`. The element can remain invisible or offscreen with no lint warning. Fix the overlap in one of two ways:
+
+  ```html
+  <!-- BAD: two transforms on one element -->
+  <img class="hero" src="..." />
+  <script>
+    tl.from(".hero", { y: 50, opacity: 0, duration: 0.6 }, 0);
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // kills the entrance
+  </script>
+
+  <!-- GOOD option A: combine into one tween -->
+  <script>
+    tl.fromTo(
+      ".hero",
+      { y: 50, opacity: 0, scale: 1.0 },
+      { y: 0, opacity: 1, scale: 1.04, duration: beat, ease: "none" },
+      0,
+    );
+  </script>
+
+  <!-- GOOD option B: split across parent + child -->
+  <div class="hero-wrap"><img class="hero" src="..." /></div>
+  <script>
+    tl.fromTo(".hero-wrap", { y: 50, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6 }, 0); // entrance on parent
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // Ken Burns on child
+  </script>
+  ```
+
+- **Prefer `tl.fromTo()` over `tl.from()` inside `.clip` scenes.** `gsap.from()` sets `immediateRender: true` by default, which writes the "from" state at timeline construction — before the `.clip` scene's `data-start` is active. Elements can flash visible, start from the wrong position, or skip their entrance entirely when the scene is seeked non-linearly (which the capture engine does). Explicit `fromTo` makes the state at every timeline position deterministic:
+
+  ```js
+  // BRITTLE: immediateRender interacts badly with scene boundaries
+  tl.from(el, { opacity: 0, y: 50, duration: 0.6 }, t);
+
+  // DETERMINISTIC: state is defined at both ends, no immediateRender surprise
+  tl.fromTo(el, { opacity: 0, y: 50 }, { opacity: 1, y: 0, duration: 0.6 }, t);
+  ```
+
+- **Ambient pulses must attach to the seekable `tl`, never bare `gsap.to()`.** Auras, shimmers, gentle float loops, logo breathing — all of these must be added to the scene's timeline, not fired standalone. Standalone tweens run on wallclock time and do not scrub with the capture engine, so the effect is absent in the rendered video even though it looks correct in the studio preview:
+
+  ```js
+  // BAD: lives outside the timeline, never renders in capture
+  gsap.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 });
+
+  // GOOD: seekable, deterministic, renders
+  tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0);
+  ```
+
+- **Hard-kill exiting inner elements at a scene boundary, not the `.clip` itself.** A non-clip element or wrapper whose visibility changes at a beat boundary may need a deterministic zero-duration `tl.set()` kill after its fade, because a later tween or sibling `immediateRender` can resurrect it. This is the explicit-boundary exception to the ban on raw `visibility` tweens. HyperFrames alone controls `.clip` lifecycle; never apply this pattern to the clip container.
+
+  ```js
+  tl.to(innerEl, { opacity: 0, duration: 0.3 }, beatEnd);
+  tl.set(innerEl, { opacity: 0, visibility: "hidden" }, beatEnd + 0.3); // non-clip kill
+  ```
+
+These are the exact rules with the exact code examples — don't summarize or shorten them. They exist because compositions that lint clean still ship broken without them.

motion/skills/references/video-composition.md

@@ -0,0 +1,66 @@
+<!-- Vendored from https://github.com/heygen-com/hyperframes (skills/hyperframes-creative/references/video-composition.md @ 9d148d28, Apache-2.0).
+     Reference doc hyperframes-creative.md points at for non-trivial compositions. Re-vendor when bumping @hyperframes/producer, then run make reflow-docs (prose is reflowed to house style). -->
+
+# Video Composition
+
+Video frames are not web pages. Use these rules for design-led compositions while respecting the requested format, brand, and scope. Minimal technical compositions and intentionally sparse formats may need less detail.
+
+## The Design Spec Is Brand, Not Layout
+
+The design spec (`frame.md` or `design.md`) defines what the brand looks like: colors, fonts, personality, constraints. It does NOT define how to compose a video frame. Use brand colors at video-appropriate intensity — not at web-UI opacity.
+
+**Strict from the design spec:** hex values (including background color), font families, weight relationships, Do's and Don'ts. If the user chose a light canvas, use a light canvas. If they chose dark, use dark. Do not override their palette.
+
+**Adapt for video:** type sizes, spacing, decorative opacity, border weight, component treatments. A web UI card at `border: 1px solid #e2e3e6` with `box-shadow: 0 2px 4px rgba(0,0,0,0.06)` is invisible on video. The brand color is sacred; the application is yours.
+
+## Density
+
+Choose density from the message and format. A brand or sizzle frame often needs several visual roles to feel produced; a lower-third, logo sting, or static title may need only a few.
+
+For a scene that should feel layered, plan these roles:
+
+- **Background treatment** — radial glow, oversized ghost type, color panel, grain, grid, or an intentionally flat field justified by the concept.
+- **Midground content** — the actual message. Cards, stats, code blocks, images.
+- **Foreground accents** — dividers, labels, data bars, registration marks, monospace metadata. The details that make it feel produced, not generated.
+
+For produced marketing frames, roughly 6–10 visual roles can be a useful starting point, not a contract. Add decoration only when it reinforces hierarchy, motion, or the concept. Decorative treatment must not become new user-facing content, new scenes, or unrequested claims.
+
+## Color Presence
+
+Muted is fine. Flat is not. Every scene should have at least one color that pulls the eye.
+
+- Brand accent should be VISIBLE — not a 5% opacity glow lost in compression. 15-25% for atmospheric, full saturation for focal elements.
+- **Light canvases work differently than dark.** On dark: accent glows pop naturally. On light: use bolder borders (2px+ solid), stronger structural elements (rules, dividers), and full-saturation accent hits. Light backgrounds need texture (subtle grain, patterns) to avoid the "blank slide" feel. Don't switch to dark — make light cinematic.
+- **No full-screen linear gradients on dark backgrounds.** They band visibly under H.264 compression. Use a radial gradient, a solid fill, or solid + localized glow instead.
+- Tint neutrals toward the brand hue. Dead gray reads as undesigned.
+
+## Scale
+
+Web sizes are invisible on video. Everything scales up.
+
+| Element            | Web     | Video    |
+| ------------------ | ------- | -------- |
+| Headlines          | 32-48px | 64-120px |
+| Body text          | 14-16px | 28-42px  |
+| Labels             | 12px    | 18-24px  |
+| Decorative opacity | 3-8%    | 12-25%   |
+| Borders            | 1px     | 2-4px    |
+| Padding            | 16-32px | 60-140px |
+
+If you're writing a font-size under 24px in a video composition, justify it. If you're writing decorative opacity under 10%, it's invisible.
+
+## Motion Intensity
+
+Subtle reads as static at 30fps. Err toward more movement than feels safe.
+
+- Every decorative element should have ambient motion: breathe, drift, pulse, orbit. Static decoratives feel dead.
+- Vary motion per scene — don't repeat the same ambient pattern.
+- Scene entrances should use 3+ different eases and directions. If every element enters from `y: 30, opacity: 0`, the scene has no choreography.
+
+## Frame Composition
+
+- **Two focal points minimum.** The eye needs somewhere to travel.
+- **Fill the frame.** Hero text: 60-80% of frame width.
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web layout pattern.
+- **Split frames.** Data panel left, content right. Top bar with metadata, full-width below. Zone-based layouts over centered stacks.
+- **Structural elements.** Rules, dividers, border panels. They create visual paths and animate well (`scaleX: 0` → `1`).