@amg555/frameforge-mcp 2.4.10 → 2.7.1

package/plugins/video-pipeline/skills/html-renderer/references/character-animation.md

@@ -0,0 +1,388 @@
+# 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/plugins/video-pipeline/skills/html-renderer/references/collage-broll.md

@@ -0,0 +1,41 @@
+# 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/plugins/video-pipeline/skills/html-renderer/references/design.md

@@ -0,0 +1,217 @@
+# 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.