@amg555/frameforge-mcp 2.7.6 → 2.7.8

package/.agent/skills/html-renderer/references/character-animation.md

@@ -1,388 +0,0 @@
-# Character Animation — ClaudeAnimationBase Full Guide
-
-Adapted from `JohnHeibel/ClaudeAnimationBase` `ANIMATION_GUIDE.md`.
-The full hand-painted animation method for code-driven character films.
-2.9k stars. All test videos generated with Opus 5.5 on `xhigh` reasoning in Claude Code.
-
----
-
-## The Three Goals
-
-Every rule serves one of three goals:
-
-- **Handmade.** The video looks like someone painted it by hand, frame by frame — brush strokes, ink lines that boil, flat 2D, no lettering.
-- **Alive.** Something is always moving and something is always happening. Faces act instead of snapping, and characters are big enough to feel.
-- **One piece.** It's one short film, not a pile of clips. Plan it before you draw it, and link every scene to the next.
-
-Underneath all three: the viewer has to be able to follow it. **Timing (rule 4) is the rule models get wrong most often.**
-
----
-
-## The Rules
-
-### Rule 1. The Medium Is Solid: Brush Strokes, Flat 2D, Boil
-
-- **Paint with brush primitives.** Characters get flat colour plus an ink outline. Backgrounds get soft watercolour shapes.
-- **Never use plain CSS shapes** (rect, ellipse, fill): they look like 2000s Flash. Use SVG path or canvas brushwork.
-- **The linework boils.** Re-seed the PRNG 12 times a second (`BOIL = Math.floor(t * 12)`), so every drawing wobbles slightly like hand-drawn animation. That's the look — don't fight it.
-- For anything that must stay put (star positions, tuft heights), use `hash(i)` — a seeded deterministic value per element.
-- **Everything is flat 2D.** Never project 3D. Depth comes from overlap, scale, and colour (farther = smaller, bluer, paler). Never from a projection.
-- **Soft palette, no pure black or white.** Use palette ink for black, palette cream for white. Keep colours soft and harmonious.
-
-```javascript
-// PRNG boil seed — quantize to 12fps grid
-const BOIL = Math.floor(t * 12);
-function boil(seed, amplitude = 1) {
-  return Math.sin(seed * 19.37 + BOIL * 2.41) * amplitude;
-}
-// Use: stable elements use hash(i), boiling elements use boil(seed)
-function hash(i) { return Math.sin(i * 127.1 + 311.7) * 43758.5453 % 1; }
-```
-
-### Rule 2. No Text
-
-- Show it, don't write it. No captions, no titles, no labels on objects, no speech bubbles with words.
-- Character reactions are painted marks, never letters: `!`, `?`, zzz, sweat, hearts, a bulb, a rain cloud.
-- A sign that repeats the story is the classic failure. If the character holds a sign saying "I'm lost", the shot has failed. Show the character being lost: looking left, then right, the map upside down, a sweat drop.
-- If a single word is truly needed: paint it into the scene, keep it to one or two words, use it once.
-
-### Rule 3. Something Happens in Every Scene
-
-- **Every shot needs an event.** Something changes between its first frame and its last. "Character stands in a meadow being cute" is not a shot.
-- **One focal action at a time.** Stage it with a clear silhouette.
-- **Cause, then reaction.** When something happens, the character reacts: a take, an emotion change, a turn toward it.
-- **Pay it off.** Whatever you set up (a door, a sandwich, a noise) gets resolved on screen.
-
-### Rule 4. Timing: Model the Viewer
-
-Timing is where generated animation fails most often: everything moves at one brisk speed, events pile on top of each other, and moments are over before anyone understands them.
-
-**For every moment, ask: what does the viewer need to understand, and how long will that take them?**
-
-- **Write the reads.** For each shot, list in order what the viewer has to understand. Each item is a *read*. Every read needs:
-  - Time for the eye to find it
-  - Time to understand it
-  - A moment to register before the next thing starts
-  - Small, distant, fast, or subtle things take longer to find than big, central, obvious ones
-- **One read at a time.** Don't start a new read while the viewer is still taking in the last one.
-- **Fast actions, slow meanings.** A motion can be very quick if it's anticipated, but what it means needs held time.
-  - Anticipation tells the viewer where to look before the action
-  - The hold after lets them understand it
-  - Move quickly through what doesn't matter; spend time on what does
-  - That contrast between quick and held is what gives rhythm
-- **Lead the eye.** The viewer looks at whatever moves, is bright, is big, or is being looked at. Before an important read, get their eye to the right place first.
-- **Let the reads set the length.** A shot is as long as its reads need. A shot that's over too fast had its reads squeezed; a padded shot had too few reads.
-
-### Rule 5. Alive
-
-- **Nothing is ever still.** Every emotion has its own idle motion; cameras drift or push; environments are alive; linework boils.
-- **Faces act, they never snap.** Change moods through the `emotions()` system — anticipation, squint, take, overshoot around every change.
-- **Move like a cartoon, not a machine.** Every move follows classic animation principles (see below).
-- **Character is big.** In a medium shot, the character is ~20–28 units. In a close-up: 40–70. Tiny characters (< 12 units) only for wide establishing shots.
-- **Everything moves on a beat.** BPM drives every idle, bounce, and dance, so the whole film shares one pulse.
-
-### Rule 6. Transitions Always
-
-- **Every seam gets a transition**: into the first shot, between every pair of shots, out of the last.
-- Never start on a hard frame, never just stop.
-- **Pick a transition that belongs to the story**:
-  - Brush wipe (fat strokes cover the frame and drag off)
-  - Iris or shaped iris
-  - Whip pan with a smear
-  - Match cut (same shape or motion across the cut)
-  - Cut on action (cut mid-move, finish in next shot)
-  - Camera move that carries through into the next shot
-  - Fade or push from paper or black
-- A plain cut is fine only when it's on action or a deliberate smash cut.
-- **Changes inside a shot are transitions too**: emotions, turns, prop arrivals and departures — always on arcs.
-
-### Rule 7. One Piece: Vision Before Any Code
-
-- **Storyboard first**, in writing, before writing any scene code.
-- **One world.** Pick a palette and setting that carries through, with a colour arc across the video.
-- **One thread.** Story has a beginning, middle, and end. Emotional arc is planned across the whole video, not per shot.
-- **Rhyme the ending with the opening**: same place, pose, or motif — changed. Makes the film feel whole.
-- **Link scenes**: motion continues across cuts, screen direction stays consistent.
-
----
-
-## Animation Principles (The Classics Applied to Code)
-
-Motion written as code comes out mechanical: every part moves at once, on the same curve, by the same amount. These principles fix that:
-
-| Principle | How to Apply in Code |
-|-----------|---------------------|
-| **Anticipation** | Before a big move, a small move the opposite way. `jump()` builds this in. |
-| **Squash and stretch** | Bodies squash on impact, stretch when fast — keeping volume. Parameter `sq`. |
-| **Slow in, slow out** | Run progress through `easeIn()`, `easeOut()`, `backOut()` — never plain `lerp` over time |
-| **Weight** | How something starts and stops says what it weighs. Heavy = slow start, slow stop, little bounce. |
-| **Arcs** | Living things move on arcs, not lines. `arcPt(p0, p1, h, k)` |
-| **Overlapping action** | Eyes lead, body follows, arms/hats/props drag behind. Offset each part's timing from the thing it hangs off. `spring()` for the settle. |
-| **Avoid twinning** | Give one arm the action and the other something smaller. Offset timings and phases between characters. |
-| **Exaggeration** | Push poses, takes, squash, and leans further than feels natural. Subtle reads as nothing. |
-| **Strong key poses** | Each shot's storytelling poses should read as stills, with clear silhouette. |
-| **Show the thought** | A character notices, thinks, then acts. Eyes move first. |
-| **Secondary action** | Small actions that support the main one (hat bobbing, emote popping). Never compete with main action. |
-
----
-
-## Storyboard Format
-
-Write `STORYBOARD.md` before any scene code:
-
-```
-Logline: one sentence. Character wants ___, but ___, so ___.
-World: setting, palette, light, how the colour changes across the video.
-Motif: the thing that recurs and pays off.
-Character's arc: the emotion keys across the whole video.
-
-Shots:
-  A  start–end  [transition in: ___]  what's seen · the EVENT · character's reaction · camera
-     reads:  start–end  the first thing the viewer must understand
-             start–end  the next one (where is the viewer's eye when it starts?)
-             ...
-  B  start–end  [transition: ___]  ...
-  ...
-  [transition out: ___]
-```
-
-**Reads are the timing sheet.** Give each one a start and end. Make sure each has time to be found and understood. Make sure no two important reads overlap.
-
-Check the storyboard:
-- Is there an event in every shot?
-- Does every read have time to land before the next starts?
-- Is there a transition at every seam?
-- Is there any text anywhere?
-- Does the ending rhyme with the opening?
-
----
-
-## Frames Are Pure Functions of Time
-
-**The most important technical constraint:**
-
-- Frames render **in parallel and out of order**
-- A shot is `fn(t, lt, dur)` and must draw the **same frame for the same `t`**, every time
-- No state carried between frames; no counters; no `Math.random()`; no physics that integrates frame by frame
-- Compute **everything from `t`**, in closed form
-
-```javascript
-// CORRECT — pure function of lt (local time)
-layer('char').on((t, lt, dur) => {
-  const step = Math.floor(lt * 12);       // 12fps boil step
-  const bx = Math.sin(7.3 * 19.37 + step * 2.41) * 2.4;
-  const emotion = lt < 1.5 ? 'neutral' : 'happy';  // computed from lt, not state
-  return { transform: `translateX(${bx}px)` };
-});
-
-// WRONG — global state carries between frames
-let emotionState = 'neutral';  // ← never do this
-layer('char').on((t, lt, dur) => {
-  if (lt > 1.5) emotionState = 'happy';  // ← breaks determinism
-  return { emotion: emotionState };
-});
-```
-
-**Seed each animated element separately.** A moving element uses a different amount of randomness each frame, which shifts the stream for everything drawn after it. Give each element a unique seed:
-
-```javascript
-function elementBoil(seed) {
-  const step = Math.floor(t * 12);
-  return {
-    dx: Math.sin(seed * 19.37 + step * 2.41) * 2.4,
-    dy: Math.cos(seed * 11.29 + step * 1.87) * 1.8,
-    rot: Math.sin(seed * 13.71 + step * 0.79) * 1.8,
-    sc: 1.0 + Math.sin(seed * 7.11 + step * 3.14) * 0.025,
-  };
-}
-// Usage: const b = elementBoil(7.3); // seed 7.3 for this element
-```
-
----
-
-## Time and Motion Helpers
-
-```javascript
-// Progress through [a, b] → 0..1
-function seg(t, a, b) { return Math.min(1, Math.max(0, (t - a) / (b - a))); }
-
-// Keyframes — values may be arrays
-function kf(t, keys, ease = (x => x)) {
-  for (let i = 0; i < keys.length - 1; i++) {
-    const [t0, v0] = keys[i], [t1, v1] = keys[i+1];
-    if (t >= t0 && t <= t1) {
-      const p = ease(seg(t, t0, t1));
-      return Array.isArray(v0) ? v0.map((v, j) => v + (v1[j] - v) * p) : v0 + (v1 - v0) * p;
-    }
-  }
-  return keys[keys.length - 1][1];
-}
-
-// Easing
-const easeOut  = t => 1 - Math.pow(1 - t, 3);
-const easeIn   = t => t * t * t;
-const ease     = t => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
-const backOut  = t => 1 + 2.70158 * Math.pow(t - 1, 3) + 1.70158 * Math.pow(t - 1, 2);
-
-// Rhythm
-// BEAT = 60 / BPM  (seconds per beat)
-// pulse(t, k = BEAT) → 1.0 on each beat, then decays
-function pulse(t, k) { return Math.max(0, 1 - (t % k) / (k * 0.7)); }
-
-// Jump: crouch → stretch → arc → squash-land
-// Returns {dy, sq} — add to character's pose
-function jump(t, t0, t1, h) {
-  if (t < t0 || t > t1 + 0.3) return { dy: 0, sq: 0 };
-  const p = seg(t, t0, t1);
-  const arc = Math.sin(p * Math.PI);  // parabolic arc
-  const land = t > t1 ? Math.max(0, 1 - seg(t, t1, t1 + 0.3) * 3) : 0;
-  return { dy: -h * arc + land * 8, sq: -arc * 0.12 + land * 0.18 };
-}
-
-// Spring settle after an event
-function spring(t, opts = {}) {
-  const { tension = 200, friction = 20 } = opts;
-  const w = Math.sqrt(tension);
-  const zeta = friction / (2 * w);
-  if (zeta >= 1) return 1 - Math.exp(-friction * t / 2) * (1 + friction * t / 2);
-  const wd = w * Math.sqrt(1 - zeta * zeta);
-  return 1 - Math.exp(-zeta * w * t) * (Math.cos(wd * t) + (zeta * w / wd) * Math.sin(wd * t));
-}
-```
-
----
-
-## Character Emotion System
-
-31 emotions grouped by family:
-
-| Family | Emotions |
-|--------|----------|
-| **Joy** | happy, excited, laugh, love, proud, starstruck, playful, hopeful, relieved |
-| **Sly** | smug, cool, mischief, suspicious |
-| **Low** | sad, cry, bored, sleepy, ko |
-| **Hot** | angry, furious, determined, disgusted |
-| **Alarm** | scared, nervous, surprised, confused, dizzy |
-| **Mind** | neutral, thinking, idea, shy |
-
-**Emotion blending** — never snap between emotions, always blend through anticipation:
-
-```javascript
-// emotions(t, keys) — acted emotion changes
-// Around each key: squints just before, swaps face, fires a take
-function emotions(t, keys) {
-  // Find current segment
-  for (let i = keys.length - 1; i >= 0; i--) {
-    const [keyT, name, overrides = {}] = keys[i];
-    if (t >= keyT) {
-      const nextKeyT = i < keys.length - 1 ? keys[i+1][0] : Infinity;
-      const lt = t - keyT;
-      const segDur = nextKeyT - keyT;
-
-      // Anticipation squint just before transition (0.12s before)
-      const anticipation = i < keys.length - 1
-        ? Math.max(0, (t - (nextKeyT - 0.12)) / 0.12)
-        : 0;
-
-      return {
-        emotion: name,
-        squint: anticipation * 0.8,
-        take: anticipation > 0.5 ? (anticipation - 0.5) * 2 : 0,
-        ...overrides,
-      };
-    }
-  }
-  return { emotion: keys[0][1] };
-}
-```
-
----
-
-## Review Loop (Render → Look → Fix)
-
-You **cannot see motion by reading code**. Render and look at every shot:
-
-1. **Contact sheet**: every shot's first, middle, and last frames (checks the shape of the whole piece)
-2. **Strip**: every frame of a key motion — turns, takes, jumps, throws, transitions (0.1–0.15 s step)
-3. **Crop**: full-resolution detail — faces, hands, contacts, glows
-
-At each zoom level, check:
-- **Read**: is the event clear from the sheet alone? Is the character big enough? Does it separate from the background?
-- **Timing**: does every read have enough time to land?
-- **Motion**: does every move have anticipation and follow-through? Any pops or snaps?
-- **Boil**: in a strip, does stable linework match between frames? Anything still that changes every frame needs its own seed.
-- **Contacts**: do feet touch the ground? Do held things touch the arm tips?
-- **Transitions**: do the first and last 0.5 s of every shot open and close with a transition?
-- **Rules**: any text? Any 3D? Any dead stretch where nothing is happening?
-
-**Budget**: at least one sheet per shot, a strip for every key motion and transition, and a crop for every face that carries the story.
-
----
-
-## Common Failures
-
-| Failure | What it looks like |
-|---------|-------------------|
-| Signs / captions | Words anywhere on screen |
-| Dead character | Standing still, smiling, nothing happening |
-| Uniform speed | Everything at one brisk speed, events stacked |
-| Flashed moments | Moments over before viewer understands them |
-| Tiny character | Whole video with character < 12 units in a big empty landscape |
-| Snapping faces | Expression swaps from one frame to the next |
-| Mechanical motion | Linear moves, every part at once, mirrored arms |
-| Timid poses | Takes that barely read |
-| Jittery linework | Still things re-boiling because a moving element shifted the PRNG stream |
-| Hard cuts everywhere | No transitions at seams |
-| 3D rotation | `rotateY`, perspective boxes, or projected turns |
-| Digital shapes | Plain CSS shapes mixed into drawn content |
-
----
-
-## Render Pipeline
-
-```bash
-# Contact sheet: shape of the whole piece
-node render.mjs --sheet=0.1,0.8,1.6,2.4,3.1,3.9 --cols=6 --w=320 --out=out/check/sheet.jpg
-
-# Strip: every frame of a moment (turns, takes, jumps, throws)
-node render.mjs --strip=2.1:2.6 --cols=6 --w=320 --out=out/check/strip.jpg
-
-# Crop: full-resolution detail (face, hands, contacts, glows)
-node render.mjs --sheet=2.3,2.4 --crop=760,420,500,400 --w=500 --out=out/check/face.jpg
-
-# Crop following a world point through camera
-node render.mjs --strip=2.1:2.6 --crop-at=960,700,500,400 --out=out/check/feet.jpg
-
-# Final render
-node render.mjs --clip --out=out/video.mp4
-```
-
-FrameForge equivalent:
-```
-render_animation({ mode: "review", contactSheet: true, stripStart: 2.1, stripEnd: 2.6 })
-```
-
----
-
-## Linux / Headless Rendering
-
-For cloud or CI rendering without a GPU:
-
-```bash
-# Ubuntu 23.10+ blocks Chrome's sandbox
-node render.mjs --clip --out=out/video.mp4  # adds --no-sandbox automatically on Linux
-
-# Software WebGL (SwiftShader) when no GPU
-node render.mjs --soft-gl --clip --out=out/video.mp4
-
-# NVIDIA GPU on headless Linux
-node render.mjs --gpu-angle=gl-egl --clip --out=out/video.mp4
-# or: --gpu-angle=vulkan
-
-# Check which renderer each flag set gets
-node gpu_probe.mjs <chrome-path>
-
-# Playwright's Chromium is found automatically
-```
-
-FrameForge Playwright renderer handles this automatically via `--no-sandbox` on Linux.

package/.agent/skills/html-renderer/references/collage-broll.md

@@ -1,41 +0,0 @@
-# Editorial Paper Collage & Halftone B-Roll
-
-Derived from `pyang5166/gbro-collage-broll`. Converts abstract script claims and voiceover segments into premium editorial paper-collage animations.
-
----
-
-## The Three-Gate Validation Process
-
-Never generate collage visual components blindly. Follow the 3-gate rule:
-
-1. **Gate 1: Semantic Claim Extraction**
-   - Identify the primary noun and verb in the voiceover beat.
-   - Example: *"Interest rates surged to 20-year highs"* $\to$ Noun: `Central Bank / Rates`, Verb: `Surge / Escalator`.
-
-2. **Gate 2: Visual Metaphor Alignment**
-   - Match abstract concepts to tactile paper cutouts:
-     - Growth / Inflation $\to$ Stacking banknotes, inflating balloon stamp, ascending staircase.
-     - Tech / AI $\to$ Vintage computer monitor, mechanical gear cutouts, circuit blueprint overlay.
-     - Time $\to$ Torn wall calendar pages, pocket watch face, pendulum swing.
-
-3. **Gate 3: Spatial Layout & Halftone Verification**
-   - 2.5D perspective tilt (`rotateX(15deg) rotateY(-10deg)`).
-   - Halftone dot texture overlay (`radial-gradient(circle, #000 1.5px, transparent 1.5px)`).
-   - Torn paper drop shadow (`filter: drop-shadow(4px 6px 0px rgba(0,0,0,0.35))`).
-
----
-
-## 12fps Step-Stagger Entrance Contract
-
-Collage elements must feel hand-placed, not mechanically smooth:
-
-```javascript
-// Step to 12fps stop-motion cadence
-const step = Math.floor(t * 12);
-const dropProgress = Math.min(1, step / 6); // settles in 0.5s
-
-// Damped paper bounce
-const scale = 1.15 - 0.15 * dropProgress;
-const rot = -4 + Math.sin(seed * 11) * 3;
-```
-

package/.agent/skills/html-renderer/references/design.md

@@ -1,217 +0,0 @@
-# Design Reference — Layouts, Safe Zones, Type Scale, Pacing
-
-Production design rules for FrameForge HTML compositor projects.  
-These rules apply to every frame whether it is a motion graphic, explainer, reel, or short.
-
----
-
-## Canvas Formats
-
-| Format | Dimensions | Use case |
-|--------|-----------|---------|
-| Landscape | 1920 × 1080 | YouTube, presentations, explainers |
-| Portrait | 1080 × 1920 | TikTok, Instagram Reels, YouTube Shorts |
-| Square | 1080 × 1080 | Instagram feed (export crop only) |
-
-Set in `reel()`: `reel({ width: 1080, height: 1920, fps: 30, duration: 30 })`.
-
----
-
-## Safe Zones
-
-**Always keep story-critical content inside the safe zone.** Platform overlays (captions, UI chrome, handle badges) encroach from all edges.
-
-### Landscape (1920 × 1080)
-
-```
-┌────────────────────────────────────────────────────────┐
-│  80px                                              80px │  ← bleed margin
-│  ┌──────────────────────────────────────────────────┐  │
-│  │                                                  │  │
-│  │   TEXT & FOCAL CONTENT SAFE ZONE                 │  │  96px top
-│  │   1728 × 888 px (centred)                       │  │
-│  │                                                  │  │
-│  └──────────────────────────────────────────────────┘  │
-│  80px                                             120px │  ← bottom caption strip
-└────────────────────────────────────────────────────────┘
-```
-
-- **Title / headline text:** keep within x: 96–1824, y: 96–200
-- **Body / callout text:** keep within x: 96–1824, y: 200–880
-- **Caption strip:** y: 880–980 (reserved for `captions()` output)
-- **Never place story-critical text below y: 880** (platform UIs cover it)
-
-### Portrait (1080 × 1920)
-
-```
-Top safe:     y > 120    (avoid top bar + handle overlay)
-Bottom safe:  y < 1680   (avoid TikTok/Reels caption strip)
-Side safe:    x: 60–1020
-```
-
----
-
-## Five-Layer Depth Stack
-
-Every scene must maintain clear atmospheric depth. Name layers accordingly.
-
-| Z-index | Layer name | Contents |
-|---------|-----------|---------|
-| 0 | `bg` | Radial gradient, sky, atmospheric tint |
-| 1 | `env` | Grid lines, floor plane, distant elements, star field |
-| 2 | `subject` | Primary visual entity (character, diagram, device) |
-| 3 | `overlay` | Callout lines, pulse packets, data labels, badges |
-| 4 | `fg` | Vignette, glass arcs, foreground foliage, grain |
-
-In CSS: use `z-index: 0..4` on stage children or set `position: absolute` stacking order.
-
----
-
-## Type Scale
-
-### Landscape
-
-| Role | Size | Weight | Font family |
-|------|------|--------|-------------|
-| Display / hero | 96–120px | 800 | Archivo, Rajdhani, or Cinzel |
-| Headline | 64–80px | 700 | Archivo, Inter |
-| Subhead | 40–52px | 600 | Inter, Rajdhani |
-| Body | 28–36px | 400 | Inter, system-ui |
-| Caption / badge | 20–24px | 500 | Inter |
-| Fine print | 16–18px | 400 | Inter |
-
-### Portrait (scale down ~25%)
-
-| Role | Size |
-|------|------|
-| Display | 72–88px |
-| Headline | 48–60px |
-| Body | 22–28px |
-| Caption | 18–20px |
-
-### Regional stacks
-
-| Script | Primary | Fallback |
-|--------|---------|---------|
-| Malayalam | Manjari, Gayathri, Chilanka | Nirmala UI, Noto Sans Malayalam |
-| Devanagari (Hindi) | Noto Sans Devanagari | Nirmala UI |
-| Tamil | Noto Sans Tamil | Latha |
-| Telugu | Noto Sans Telugu | Gautami |
-| CJK (Chinese/Japanese/Korean) | Noto Sans CJK SC/JP/KR | system-ui |
-| Arabic | Noto Sans Arabic | Tahoma |
-| Latin | Inter, Archivo | system-ui, sans-serif |
-
-**WCAG AAA minimum contrast:** 7:1 text:background. Check with `seg()` + luminance math at every frame where background colour changes.
-
----
-
-## Pacing Rules (cuts per second)
-
-| Format | Min shot length | Max shot length | Pacing feel |
-|--------|----------------|----------------|------------|
-| Short-form reel | 1.5 s | 5 s | Fast, punchy |
-| Educational explainer | 3 s | 12 s | Measured |
-| Cinematic | 4 s | 20 s | Deliberate |
-
-**Beats per minute → cuts per minute:** For music-synced videos, place cut points on downbeats. At 120 BPM, that's every 2 seconds (or every 4 for half-time feel).
-
----
-
-## Motion Budget per Shot
-
-Keep total simultaneous animated properties per shot under these thresholds to avoid visual noise.
-
-| Properties moving at once | Perception |
-|--------------------------|-----------|
-| 1–2 | Clean, focused |
-| 3–4 | Dynamic, energetic |
-| 5–6 | Busy — only justified for reveal moments |
-| 7+ | Chaotic — avoid |
-
----
-
-## Transition Catalogue
-
-Named transitions for `STORYBOARD.md` `transition_in` / `transition_out`:
-
-| Name | Description | Duration |
-|------|-------------|---------|
-| `cut` | Instant switch | 0 s |
-| `fade-from-black` | Fade in from black | 0.5–0.8 s |
-| `fade-to-black` | Fade out to black | 0.4–0.6 s |
-| `dissolve` | Alpha crossfade | 0.3–0.5 s |
-| `wipe-left` | Wipe from right to left | 0.4 s |
-| `wipe-right` | Wipe from left to right | 0.4 s |
-| `iris-in` | Circle grows from centre | 0.6 s |
-| `iris-out` | Circle shrinks to point | 0.5 s |
-| `cross-dissolve` | Overlap dissolve | 0.4 s |
-| `push-left` | New slide pushes old left | 0.5 s |
-| `push-right` | New slide pushes old right | 0.5 s |
-| `flash` | Single white frame | 1 frame |
-| `dip-to-white` | Fade to white, then in | 0.6 s |
-
-**Rule:** Exits are always faster than entrances (motion craft rule #4).  
-For `cut`, no transition layer is needed. For all others, create a `layer('transition-out')` at the end of the outgoing shot and a `layer('transition-in')` at the start of the incoming shot.
-
----
-
-## Camera Motion Vocabulary
-
-| Keyword | Implementation |
-|---------|--------------|
-| `ken_burns` | `scale: 1.0 + p * 0.06` + subtle pan (Lissajous) |
-| `zoom_in` | `scale: 1.0 + p * 0.12`, pan to subject |
-| `zoom_out` | `scale: 1.12 - p * 0.12` |
-| `pan_left` | `translateX: p * -80px` |
-| `pan_right` | `translateX: p * 80px` |
-| `static` | No transform — for diagram / data shots |
-| `auto` | Pick from above based on `visual_description` |
-
-`p = t / REEL.duration` — normalised film progress (0 → 1).
-
-Camera never snaps. All motion is a smooth function of `p`. Cuts are handled by resetting `p` to 0 in the local shot frame (`lt`).
-
----
-
-## Colour Palette Conventions
-
-| Role | Recommendation |
-|------|---------------|
-| Background (dark) | `#0c1116` to `#111827` |
-| Background (light) | `#f8f9fa` to `#ffffff` |
-| Primary accent | Saturated, 60–70% lightness: `#3b82f6`, `#f59e0b`, `#10b981` |
-| Text on dark | `#f8fafc` (95% white) — never pure `#ffffff` (too harsh) |
-| Text on light | `#1f2328` (near black) |
-| Muted text | `#57606a` |
-| Warning / alert | `#ef4444` — use sparingly |
-
-**One palette rule:** Pick one accent colour per video. Two maximum. Three or more = visual noise.
-
----
-
-## Continuous Life Checklist
-
-Every shot must have at least one of these running at all times (motion craft rule #7):
-
-- [ ] Background gradient slowly shifting hue (`kf(t, [[0, 0], [REEL.duration, 10]])` hue offset)
-- [ ] Subtle camera drift (Lissajous pan `sin(0.4*t) * 6px`)
-- [ ] Particle system ticking (positions from `hash(i) * width`, animated by `t`)
-- [ ] Progress indicator animating (ring, bar, counter)
-- [ ] Wave / oscillation on any data element
-- [ ] Character breathing (`sin(3*t) * 4px` vertical drift)
-
-A completely frozen background for more than 3 consecutive seconds reads as a PowerPoint slide, not a video.
-
----
-
-## Closed-Loop QA Thresholds
-
-| Metric | Pass | Fail |
-|--------|------|------|
-| Content presence (foreground variance) | > 1.5% | ≤ 1.5% |
-| Overexposure (bright pixel share) | < 92% | ≥ 92% |
-| Compositional coverage (bbox area share) | > 8% | ≤ 8% |
-| Motion delta (t=30% vs t=70%) | pixels differ | identical hash |
-| Overall QA score | ≥ 7.0 / 10 | < 7.0 |
-
-Run `node scripts/harness.mjs quality` to check all five. The encode step refuses to proceed if the report is absent or failing.