@amg555/frameforge-mcp 2.4.10 → 2.7.0

package/plugins/video-pipeline/skills/html-renderer/references/hyperframes-motion.md

@@ -0,0 +1,208 @@
+# HyperFrames Motion Craft — Measured from Official Films
+
+Adapted from `heygen-com/hyperframes` `skills/hyperframes/references/motion.md`.
+All values measured frame-by-frame from the official HyperFrames launch films.
+
+These are defaults. A reference the user provides, or a scene that deliberately does otherwise, wins for its own beat.
+
+---
+
+## Core Motion Rules
+
+### Speed and Duration
+- **A fast move takes 0.3–0.6 s** with motion blur on its own ease, peaking at its fastest frame
+- **Motion blur**: 6–12 px on text-sized elements, 15–20 px full-frame, horizontal-only on horizontal moves
+- **Render-time blur**: `data-motion-blur="on"` on the composition root smears moving elements along their real path (opt-in)
+
+### Arrival vs Departure
+- **Arrive slow, leave clean**: long-tailed ease-outs on arrivals; landing takes longer than leaving
+- An exit is one smooth motion — never slide, stop, then leave
+- Entrances that are too snappy read as glitches; slowing by ~1 second often fixes it
+
+### Ease by Role
+
+| Role | Ease |
+|------|------|
+| Arrival / landing | `expo.out`, `power4.out` (long tail) |
+| Camera move / colour flood | `power2.inOut` (both ways) |
+| Zoom through / exit | `power3.in` (accelerates out) |
+| Rotation / progress bar | `linear` |
+
+The same `power2.out` at 0.5 s on **everything** is the flat default that makes a film feel generated.
+
+### Springs
+
+Springs are named by damping ratio:
+
+| Damping | Feel |
+|---------|------|
+| 1.0 | Never bounces — dead landing |
+| 0.7–0.85 | Reads premium |
+| 0.4–0.6 | Playful |
+| < 0.3 | Cartoon |
+
+- Position and size **may** bounce; opacity and colour **never** bounce
+- GSAP equivalents: `elastic.out(1, 0.5)` and `back.out(1.4)`
+- A closed-form spring of `t` keeps any frame renderable on its own (deterministic)
+
+```javascript
+// FrameForge engine.js — spring with damping ratio control
+spring(t, { tension: 200, friction: 20 })   // damping ≈ 0.7 (premium)
+spring(t, { tension: 300, friction: 10 })   // damping ≈ 0.3 (cartoon)
+spring(t, { tension: 120, friction: 28 })   // damping ≈ 1.0 (dead)
+```
+
+### Timing Relationships
+- **Exits are 40–50% shorter** than their entrances
+- **Overlap**: the next element starts when the previous is 30–50% done — fully sequential looks robotic, all-at-once looks cheap
+- **Stagger**: letters a frame apart, words 60–120 ms, list items 40–80 ms
+
+### Beat Grid
+- Frames per beat = `fps × 60 / BPM`
+- Compute each beat from its **index** and round it — never add rounded beats repeatedly (at 128 BPM and 30 fps that drifts 2 frames in 32 beats)
+- Cut on the beat; change the layout on the bar
+
+### Cuts
+- Cut at the **fastest frame** of a move, with matching direction and speed on both sides
+- A click into a new screen is a match cut on the click's rebound — the new screen comes in slightly large and settles
+
+---
+
+## Title Animation Patterns
+
+A landed title is **dead still** — the motion moves to the next element, the camera, or the world behind. Vary the entrance within a film.
+
+| Pattern | How |
+|---------|-----|
+| Per word blur-in | `blur(6px)` → 0 and opacity 0 → 1 in 0.13 s, 0.067 s apart, no translate |
+| Per word colour | Light grey → ink, 0.07–0.1 s apart, no position change |
+| Whole line blur | 8 px → 0 in 0.13–0.2 s |
+| Per letter name | 0.1 s apart, opacity 0.3 → 1, slight blur |
+| Slot machine | One word rolls through options, ~0.1 s a roll |
+| Behind subject | Title between the plate and a matte of the person |
+
+### Hold Times
+- A line the viewer must read holds **0.5 s + 0.3 s per word**
+- The film's last line: **at least 2 s**
+- A one- or two-word chapter line: **0.4 s**
+- Exit: blur-out and fade 0.13–0.25 s word by word, or with the scene's move
+
+### Title Sizes
+- Body: 4–9% of frame height, one or two lines
+- Quiet lines: 2.5–4% against hero words that fill 60–90% of width
+- One highlighted word in the accent colour (carries meaning)
+
+---
+
+## Rhythm
+
+| Pattern | Value |
+|---------|-------|
+| Montage cuts | Every 0.13–0.8 s |
+| Demo hold | 7–10 s while UI acts |
+| Average shot | 1.8–3 s with motion inside |
+| Pre-payoff hold | 0.3–0.75 s before the payoff |
+| Payoff speed | Normal speed (not slow) |
+
+**Continuous motion that works**: UI working, footage playing, character acting, 3D world turning, slow orbit of background stage (3–5° per second).
+
+**Defaults that look generated**:
+- Breathing/floating/pulsing loops on titles and UI
+- Titles that keep sliding or scaling after they land
+- A slow creeping scale or push late in a scene
+- Bounce on UI elements
+- Click rings
+- Every scene entering the same way
+- Every element fading and sliding up
+
+---
+
+## Transitions with a Cause
+
+Use 3–5 kinds in a film, each **caused by something on screen**. Hard cuts belong inside a scene (punch-ins); at most a third of seams between beats are hard cuts. Worlds never crossfade.
+
+| Transition | How to Build |
+|------------|-------------|
+| Zoom through a button | Camera tracks to button with blur (0.6 s), button scales from ~8% to ~250% of frame in 0.35 s, strong ease-in; its fill becomes the next frame |
+| Object becomes the world | Pill or card grows past the frame in 0.65 s ease-in-out, radius shrinks; what was around it blurs ~15 px and fades in 0.3 s; new content fades in while still growing |
+| Morph | One container widens into the next (~110 → ~880 px in 0.2 s `power3.out`) with horizontal blur 12 → 0 |
+| Carry across | Result shrinks 1 → 0.6 with blur peaking at 6 px mid-move, lands inside the next app as it builds around it |
+| Colour flood | Hero object stays while the whole ground changes colour in ~0.4 s `power2.inOut` |
+| Whip | Horizontal or vertical smear of 0.13–0.3 s; arriving element lands blurred and sharpens in ~0.13 s |
+| Iris from click | `clip-path: circle()` opens from the clicked point onto the next world in 0.15 s |
+| Dip cut | Outgoing frame darkens ~40% for 3 frames before a hard cut, so the cut reads as intentional |
+| Blur swap | Out: opacity → 0 with ~8 px blur in 0.13–0.2 s; in: blur → 0 in 0.13 s; ground never cuts |
+
+---
+
+## The Right Mechanism for Camera Moves
+
+| Request | Mechanism |
+|---------|-----------|
+| Punch-in, zoom, pan, Ken Burns, reframe | Tween `scale` and `x`/`y` on a **wrapper inside** the clip — never on the timed media element |
+| Crop or mask reveal | Tween `clip-path` or mask on an inner wrapper; source time untouched |
+| Constant speed change | `data-playback-rate` on the media (0.1–10) |
+| Speed ramp | `rate` lane in `data-automation` on the media |
+| Hold or freeze | Hold a final frame; a freeze mid-source needs a still exported first |
+
+---
+
+## Sound (HyperFrames/Earshot Standard)
+
+Sound is half of how a film feels.
+
+### The Default
+- **A film over ~15 s** that tells something gets a music bed and sounds on its visible actions — unless the person asked for silence
+- **Each storyline says its sound** in one line: the bed's feel and tempo, the one moment the music changes, which actions get effects
+
+### The Clock
+- **Narrated**: the voice is the clock — time each beat's start to its anchor word
+- **Music only**: the music is the clock — land the payoff on strong beats; cuts follow motion, not the drums
+
+### Effects: Few and Exact
+
+Every effect has a cause on screen. Too many read as a template.
+
+| Sound | Only on |
+|-------|---------|
+| click | A real cursor click on screen |
+| whoosh | A scene cut, or a large card moving fast |
+| soft key tick | Text arriving letter by letter or line by line |
+| pop | A badge, chip, or number landing |
+| riser into impact | The payoff or the mark — **once in the film** |
+
+- Sound peak lands **one frame after** its picture (light arrives before sound)
+- Each hit sits **3–6 dB over the bed**
+- Rotate 2–3 takes of a repeated sound — the same whoosh on every cut is the most common tell
+- No synthesized tones, chimes, or dings
+
+### Levels
+- Music under a voice: ~0.14 volume (≈ −17 dB relative)
+- Target loudness: **−16 to −14 LUFS** (social/web)
+- True peak: **−1 dBTP** or lower
+- Check with `npx hyperframes audio <video> --json` equivalent: use earshot `measure` or ffmpeg `-filter loudnorm`
+
+---
+
+## Common Faults and Fixes
+
+| Symptom | Cause |
+|---------|-------|
+| Blank or frozen scene | Timeline registered before async build finished, or `visibility` tweened on a `.clip` |
+| Stutter or drift between renders | Layout measured in `onUpdate`, `requestAnimationFrame`, or clock time |
+| Jump at a cut | Outgoing and incoming states differ at the seam |
+| Ease looks off at a handoff | Speeds don't match across the seam — mirror the ease (`power3.in` out, `power3.out` in) |
+
+---
+
+## Quick Reference — FrameForge Mapping
+
+| HyperFrames concept | FrameForge equivalent |
+|--------------------|-----------------------|
+| `data-start` / `data-duration` on `.clip` | `layer('id').on((t, lt, dur) => ...)` — `lt` is local time, `dur` is duration |
+| `window.__timelines["id"] = tl` | Not needed — FrameForge engine handles timeline registration |
+| GSAP `interpolate(t, frames, values, easing)` | `spring(lt, opts)`, `at(t, start, end)`, `kf(t, keyframes)` |
+| `Easing.spring({damping: 200})` | `spring(lt, { tension: 200, friction: 20 })` |
+| `data-motion-blur="on"` | `render_animation({ motionBlur: true })` (Playwright shutter) |
+| `npx hyperframes check` | `validate_storyboard({ checkDeterminism: true })` |
+| `npx hyperframes snapshot --review` | `render_animation({ mode: "review", contactSheet: true })` |

package/plugins/video-pipeline/skills/html-renderer/references/onetake-camera.md

@@ -0,0 +1,59 @@
+# OneTake Continuous Camera Choreography
+
+Derived from `feitangyuan/onetake`. Eliminates abrupt black cuts, slideshow jumps, and disconnected slide transitions.
+
+---
+
+## The OneTake Principle
+
+In standard presentation videos, scene transitions cut to black or snap immediately between unrelated slide geometries. In **OneTake**, the entire video occurs within a single, continuous, unified spatial universe:
+
+$$\text{Camera}(t) = \text{Spline}(\mathbf{P}_0, \mathbf{P}_1, \dots, \mathbf{P}_N, t)$$
+
+Every scene's starting camera transform $(\mathbf{x}, \mathbf{y}, \text{zoom})$ is identically anchored to the previous scene's terminating transform.
+
+---
+
+## 1. Unified Spatial Canvas
+
+Instead of unmounting and mounting DOM elements per scene, the entire video timeline exists on a 2.5D coordinate plane:
+
+- **Scene 1 (Hook)**: Positioned at $(0, 0)$, Zoom $= 1.0$
+- **Scene 2 (Mechanism)**: Positioned at $(1920, 0)$, Zoom $= 1.15$
+- **Scene 3 (Zoom Detail)**: Positioned at $(1920, 400)$, Zoom $= 1.80$
+- **Scene 4 (Wide Resolution)**: Positioned at $(960, 200)$, Zoom $= 0.85$
+
+---
+
+## 2. Spring-Interpolated Camera Navigation
+
+When moving from Scene $k$ to Scene $k+1$:
+1. **Never use linear interpolation**.
+2. **Use underdamped spring physics** with slight overshoot:
+   - Tension: `140`
+   - Friction: `14`
+3. **Camera Lead / Look-Ahead**:
+   $$\text{CameraTarget}(t) = \text{SubjectPos}(t) + \mathbf{v}_{\text{subject}} \times 0.25$$
+
+---
+
+## 3. Depth-Parallax Layering
+
+During continuous camera travel, layers shift at varying rates proportional to depth $z$:
+
+| Layer | Depth $z$ | Parallax Factor | Visual Content |
+|---|---|---|---|
+| Background Grid | $z = 0.2$ | $0.2 \times \Delta x$ | Blueprint grid, starfield, faint topographical lines |
+| Middle Ground | $z = 0.6$ | $0.6 \times \Delta x$ | Secondary cards, connecting vector pipes, data nodes |
+| Primary Stage | $z = 1.0$ | $1.0 \times \Delta x$ | Main subject, active text card, character avatar |
+| Foreground Overlay | $z = 1.4$ | $1.4 \times \Delta x$ | Lens vignette, framing pillars, floating particles |
+
+---
+
+## 4. Zero-Cut Scene Handshake Contract
+
+When transitioning between narrative beats:
+- The outgoing scene subject smoothly settles into a secondary supporting node (e.g., shifts left to $x = 300\text{px}$ and scales down to $0.65$).
+- The incoming scene subject enters from depth ($z = 0.5 \to 1.0$) rather than snapping onto the screen.
+- A whoosh sound effect from `Leonxlnx/earshot` fires at the exact inflection point of peak camera velocity.
+

package/plugins/video-pipeline/skills/html-renderer/references/procedural-sfx.md

@@ -0,0 +1,135 @@
+# Procedural Audio & SFX — Professional Broadcast Engineering
+
+Derived from `Leonxlnx/earshot`. Provides deterministic CPU sound-effect synthesis,
+millisecond-accurate audio-motion alignment, and a complete broadcast-grade voice chain
+for coding agents producing professional video.
+
+---
+
+## 1. Core Procedural SFX Primitives — 13-Type Library
+
+Agents synthesize or cue sound effects by semantic cue type:
+
+| Cue Type | Physical Character | Best Narrative Trigger | Duration | FFmpeg Freq |
+|---|---|---|---|---|
+| **whoosh** | Filtered pitch sweep down | Camera translation, card wipe, split transition | 400ms | 200Hz |
+| **impact** | Damped 60Hz sine + transient punch | Title punch-in, major claim reveal, beat drop | 500ms | 60Hz |
+| **pop** | Short sinusoidal chirp (600Hz) | Badge reveal, icon appearance, bullet item | 120ms | 600Hz |
+| **click** | High-frequency impulse (2.5kHz) | Kinetic letter reveal, counter tick increment | 50ms | 2500Hz |
+| **riser** | Exponential pitch sweep upward (100Hz) | Build-up to scene climax or problem resolution | 2.0s | 100Hz |
+| **chime** | UI notification bell (1200Hz) | Completion state, success, milestone reached | 350ms | 1200Hz |
+| **buzz** | Error buzzer (80Hz damped) | Rejection state, failure feedback, wrong answer | 180ms | 80Hz |
+| **tick** | Clock tick (3200Hz impulse) | Timer countdown, per-frame counter, typing | 40ms | 3200Hz |
+| **swish** | Soft page turn (350Hz sweep) | Slide reveal, soft transition, card flip | 300ms | 350Hz |
+| **punch** | Heavy sub-bass punch (45Hz) | Major beat emphasis, heroic reveal | 250ms | 45Hz |
+| **sparkle** | High sparkle (4000Hz burst) | Magic moment, aha reveal, idea appears | 200ms | 4000Hz |
+| **deep_boom** | Sub-bass cinematic boom (30Hz) | Epic reveal, cinematic opening, climax moment | 1.2s | 30Hz |
+| **transition** | Musical bridge tone (440Hz) | Scene seam smoother, narrative pivot | 600ms | 440Hz |
+
+Use via `mix_audio_pro` tool:
+```
+mix_audio_pro({
+  voicePath: ".frameforge-files/voice_0.m4a",
+  outputPath: ".frameforge-files/audio_pro.m4a",
+  sfxCues: [
+    { name: "whoosh",    time: 2.5,  volume: 0.8 },  // camera translation at t=2.5s
+    { name: "impact",   time: 8.0,  volume: 1.0 },  // title punch at t=8.0s
+    { name: "pop",      time: 12.3, volume: 0.6 },  // badge reveal at t=12.3s
+    { name: "riser",    time: 18.0, volume: 0.7 },  // build-up before climax
+    { name: "chime",    time: 25.5, volume: 0.5 },  // success state
+    { name: "deep_boom",time: 30.0, volume: 0.9 },  // epic reveal
+    { name: "sparkle",  time: 35.2, volume: 0.4 },  // aha moment
+    { name: "transition",time: 40.0, volume: 0.3 }, // scene seam
+  ],
+  // New parameters:
+  roomProfile: "cinematic",          // studio_dry | broadcast | cinematic | concert_hall | intimate
+  noiseGate: true,                   // remove breath noise between words
+  platform: "youtube",               // sets -14 LUFS automatically
+})
+```
+
+Or in `edit.js` for render-time visual sync (engine.js `cue()` function):
+```javascript
+import { cue } from './reel/engine.js';
+cue('whoosh',    2.5, 0.8);   // registered in window.__cues for render.mjs
+cue('impact',   8.0, 1.0);
+cue('riser',   18.0, 0.7);
+cue('deep_boom',30.0, 0.9);
+```
+
+---
+
+## 2. Millisecond Audio-Motion Alignment Contract
+
+Never place sound effects at arbitrary timestamps. Audio cues synchronize strictly
+with physical acceleration peaks:
+
+$$\Delta t_{\text{cue}} = t_{\text{peak velocity}} - 0.04\text{s}$$
+
+- **Perceptual Lead**: The human ear perceives sound ~40ms before visual processing finishes.
+  Placing audio 40ms ahead of the visual contact makes the impact feel physical and immediate.
+- **Sidechain Ducking**: During voiceover narration, background music ducks by -18dB and
+  SFX ducks by -6dB to maintain speech intelligibility (LUFS -14 ±1.5LU).
+
+---
+
+## 3. Professional Voice Signal Chain (10+ Year Sound Engineer Standard)
+
+The `mix_audio_pro` MCP tool and `mix_audio_pro.py` script apply the full chain:
+
+```
+Input Voice  ──►  80Hz HPF  ──►  Presence +2dB@5kHz  ──►  Air Shelf +1.5dB@12kHz
+              ──►  3:1 Compressor (-20dBFS, 5ms attack, 50ms release)
+              ──►  De-esser (6.5kHz, -3dB dynamic)
+              ──►  [Optional: Room Acoustics 0.3s RT60]
+              ──►  Sidechain Ducking (-18dB on music)
+              ──►  [Optional: Stereo Widener 1.4x M/S on music]
+              ──►  SFX Timeline Mix (40ms perceptual lead)
+              ──►  Two-Pass EBU R128 Loudnorm (-14 LUFS, ≤-1 dBTP)
+              ──►  Output: 48kHz / 192k AAC Stereo
+```
+
+### Why each stage matters (15+ year professional rationale)
+
+| Stage | Purpose | When to engage |
+|---|---|---|
+| **80Hz HPF** | Remove proximity effect, desk rumble, HVAC drone | Always on — never skip |
+| **Presence +2dB@5kHz** | Add intelligibility, cut through music bed | Always on for narration |
+| **Air Shelf +1.5dB@12kHz** | Open "air" and breathiness on voice | Always on |
+| **3:1 Compressor** | Control dynamics, keep voice at consistent level | Always on — broadcast standard |
+| **De-esser @6.5kHz** | Remove harsh sibilants ("s", "sh", "ch") | Always on for TTS/VO |
+| **Room Acoustics** | 30ms pre-delay + 0.3s RT60 aecho | Enable for cinematic narrator; disable for tutorial/VO |
+| **Sidechain Ducking** | Music auto-ducks -18dB when voice active | Any time music is present |
+| **Stereo Widener** | M/S extrastereo 1.4x on music layer only | Enable for music beds; voice stays mono-center |
+| **Two-Pass Loudnorm** | Linear EBU R128 normalization | Always — final step, never skip |
+
+---
+
+## 4. Music Bed Selection & Mood Matching
+
+For `music_mood` field in scenes and `withMusic: true` in `create_video_from_script`:
+
+| Mood | Tempo | Frequency Character | Use Case |
+|---|---|---|---|
+| `energetic` | 120–140 BPM | High energy, punchy low end | Product launches, viral reels, calls-to-action |
+| `tense` | 80–100 BPM | Staccato, minor key | Problem reveal, stakes building |
+| `calm` | 60–80 BPM | Warm pads, sparse percussion | Explanation, resolution, educational |
+| `mysterious` | 70–90 BPM | Sparse, reverb-heavy, minor | Open-question hooks, discovery reveals |
+| `dramatic` | 90–110 BPM | Orchestral swells, crescendo | Climactic moments, emotional payoff |
+| `neutral` | 100–120 BPM | Background, minimal | Default filler — prefer a named mood |
+| `humorous` | 120–160 BPM | Staccato, comedic | Comedic beats, visual gags |
+
+---
+
+## 5. Broadcast Loudness Standards Reference
+
+| Platform | Target LUFS | True Peak |
+|---|---|---|
+| YouTube | -14 LUFS | -1 dBTP |
+| Spotify Podcast | -16 LUFS | -1 dBTP |
+| Apple Podcasts | -16 LUFS | -1 dBTP |
+| Netflix / Streaming | -27 LUFS (dialogue) | -3 dBTP |
+| Broadcast (EBU R128) | -23 LUFS | -1 dBTP |
+| **FrameForge Default** | **-14 LUFS** | **-1 dBTP** |
+
+Set `targetLufs` in `mix_audio_pro` to match your delivery platform.

package/plugins/video-pipeline/skills/html-renderer/references/remotion-patterns.md

@@ -0,0 +1,159 @@
+# Remotion Design Patterns in FrameForge
+
+FrameForge ports Remotion's industry-standard motion primitives directly into its pure HTML/Playwright compositor. This document provides a side-by-side mapping and explains how to port Remotion code into FrameForge with zero React overhead, instant execution, and zero commercial licensing restrictions.
+
+---
+
+## 1. Architectural Comparison
+
+| Dimension | Remotion (`remotion-dev/remotion`) | FrameForge (`html-renderer`) |
+| :--- | :--- | :--- |
+| **Runtime** | React 18/19, Babel/Vite bundler | Pure ES Modules, zero build step |
+| **License** | Commercial license ($25+/dev/mo for >3 devs) | Pure MIT License |
+| **Frame Execution** | React re-renders virtual DOM per frame | Direct `seek(t)` property dispatch |
+| **Deterministic Clock** | Custom webpack injection & timing hooks | Playwright Virtual Clock injection |
+| **Cold Startup** | 3–10 seconds (bundler startup + bundle load) | Instant (<100ms native browser load) |
+| **Visual Math** | Analytical springs, noise, interpolation | 100% mathematically identical algorithms |
+
+---
+
+## 2. Concept Mapping Table
+
+| Remotion Concept | FrameForge Primitive | Signature / Usage |
+| :--- | :--- | :--- |
+| `<Composition>` | `reel(opts)` | `reel({ width: 1920, height: 1080, fps: 30, duration: 60 })` |
+| `<Sequence from={f} durationInFrames={d}>` | `sequence(from, dur, fn)` / `layer(name, { start, end })` | Scoped relative timeline window `[start, end]` |
+| `useCurrentFrame()` / `useVideoConfig()` | `(t, lt, dur)` in layer handler | `layer('x').on((t, lt, dur) => ({ ... }))` |
+| `<AbsoluteFill>` | `absoluteFill(extraStyles)` | Full-bleed absolute overlay preset |
+| `interpolate()` | `interpolate(val, inRange, outRange, opts)` | Multi-segment range mapping with clamp/identity |
+| `interpolateColors()` | `interpolateColors(val, inRange, outColors, opts)` | Gamma-corrected (2.2) perceptual color interpolation |
+| `spring()` | `spring(t, opts)` | Analytical damped harmonic oscillator ($0 \to 1$) |
+| `measureSpring()` | `measureSpring(opts)` | Closed-form settling time ($t_{\text{settle}} = -\ln(\epsilon) / (\zeta \omega)$) |
+| `delayRender()` / `continueRender()` | `window.delayRender()` / `window.continueRender()` | Async screenshot barrier awaiting textures/shaders/fonts |
+| `@remotion/noise` | `noise2D(seed, x, y)` / `noise3D(seed, x, y, z)` | Deterministic continuous gradient noise ($[-1, 1]$) |
+| `@remotion/paths` (`evolvePath`) | `evolvePath(progress, length)` | SVG `strokeDasharray` & `strokeDashoffset` calculator |
+| `@remotion/transitions` | `transition.slide()`, `.wipe()`, `.fade()`, `.flip()` | CSS transform and clip-path generators |
+| `<Loop durationInFrames={d}>` | `loopTime(t, duration)` | `t % duration` modulo loop time |
+| `@remotion/google-fonts` | `loadGoogleFont(family, opts)` | Dynamic web font loader with automatic render barrier |
+
+---
+
+## 3. Side-by-Side Implementations
+
+### A. Spring Motion with Analytical Settling Time
+
+#### Remotion:
+```tsx
+import { spring, useCurrentFrame, useVideoConfig } from 'remotion';
+
+export const MyComponent = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const progress = spring({ frame, fps, config: { damping: 200, mass: 1 } });
+  return <div style={{ transform: `scale(${progress})` }}>Hello</div>;
+};
+```
+
+#### FrameForge:
+```js
+import { layer, spring, measureSpring } from './reel/engine.js';
+
+// Precompute exact duration of entrance animation
+const settleTime = measureSpring({ tension: 200, friction: 22 }); // 0.72s
+
+layer('hero', { start: 0, end: 10 }).on((t, lt) => {
+  const s = spring(lt, { tension: 200, friction: 22 });
+  return {
+    transform: `scale(${0.85 + 0.15 * s})`,
+    opacity: s,
+  };
+});
+```
+
+---
+
+### B. Gamma-Corrected Color Blending
+
+Linear interpolation between saturated colors results in dull brown/gray midpoints. FrameForge uses Remotion's gamma-corrected linear-light transfer ($r^{2.2}$).
+
+```js
+import { layer, interpolateColors } from './reel/engine.js';
+
+layer('background').on((t) => ({
+  backgroundColor: interpolateColors(
+    t,
+    [0, 2.5, 5],
+    ['#ff0055', '#00e5ff', '#ffe600']
+  ),
+}));
+```
+
+---
+
+### C. Handheld Organic Camera Shake (`noise2D`)
+
+```js
+import { layer, noise2D } from './reel/engine.js';
+
+layer('camera').on((t) => {
+  const shakeX = noise2D('handheld', t * 2.5, 0) * 8; // +/- 8px
+  const shakeY = noise2D('handheld', 0, t * 2.5) * 6; // +/- 6px
+  const rot = noise2D('handheld', t * 1.5, 10) * 0.75; // +/- 0.75 deg
+  return {
+    transform: `translate(${shakeX}px, ${shakeY}px) rotate(${rot}deg)`,
+  };
+});
+```
+
+---
+
+### D. Path Drawing & Handwriting Reveal (`evolvePath`)
+
+```js
+import { evolvePath, spring } from './reel/engine.js';
+
+const pathEl = document.getElementById('chart-line');
+const totalLen = pathEl.getTotalLength();
+
+layer('chart', { start: 1, end: 5 }).on((t, lt) => {
+  const progress = spring(lt, { tension: 150, friction: 20 });
+  const { strokeDasharray, strokeDashoffset } = evolvePath(progress, totalLen);
+  pathEl.style.strokeDasharray = strokeDasharray;
+  pathEl.style.strokeDashoffset = strokeDashoffset;
+});
+```
+
+---
+
+### E. Transitions between Shots
+
+```js
+import { layer, transition, seg } from './reel/engine.js';
+
+// Wipe entrance over first 0.5s of shot
+layer('b-roll', { start: 5, end: 10 }).on((t, lt) => {
+  const inProgress = seg(lt, 0, 0.5);
+  return {
+    ...transition.wipe(inProgress, { direction: 'from-left' }),
+  };
+});
+```
+
+---
+
+### F. Async Texture / Shader / Font Preloading (`delayRender`)
+
+When loading remote media or compiling Three.js WebGL shaders, prevent Playwright from screenshotting prematurely:
+
+```js
+import { loadGoogleFont } from './reel/engine.js';
+
+// Automatically acquires delayRender, loads font weights, and continues render
+await loadGoogleFont('Space Grotesk', { weights: [400, 600, 700] });
+
+// Manual async assets:
+const handle = window.delayRender('loading-hdr-texture');
+const texture = await new THREE.TextureLoader().loadAsync('assets/hdr.jpg');
+window.continueRender(handle);
+```
+

package/plugins/video-pipeline/skills/video-pipeline/SKILL.md

@@ -26,13 +26,15 @@ IDE Agent (IBM Bob / Codex / opencode / Cursor / Windsurf / Claude Code)
     │
     ▼  Cloudflare Remote MCP (recommended) ─────────────────────────────
     │  https://video-mcp.YOUR_SUBDOMAIN.workers.dev/mcp
-    │  21 tools: create_video_from_script · edit_video · render_from_scenes
-    │            generate_scene_code · preview_scene
+    │  28 tools: create_video_from_script · edit_video · render_from_scenes
+    │            generate_scene_code · preview_scene · verify_scene_quality
     │            ingest_media · edit_scenes · render_tts · multi_voice_tts
     │            generate_scene_image · assemble_video · publish_video
     │            research_topic · write_script · external_platform_call
     │            queue_full_pipeline · get_job_status · export_to_editor
     │            scaffold_animation_project · validate_storyboard · render_animation
+    │            plan_video_edit · sync_upstream_skills · check_upstream_updates
+    │            transcribe_media · ingest_url · mix_audio_pro
     │
     ▼  OR — Local stdio / HTTP MCP ────────────────────────────────────
     │  node src/mcp-server/stdio.js   (stdio)
@@ -181,6 +183,11 @@ publish_video({ productionId, masterPath, channels: ["file"] })
 
 Use when: the user wants Remotion-style motion graphics, image gen is unavailable, or they ask for "animated video" or "make it look good". Every pixel is a pure function of time `t`.
 
+> **Model effort (Opus 5.5 / Claude Code):**
+> - Beat sheet + first scene authorship → `effort: xhigh`
+> - Storyboard review, strip-range patches, encode-only runs → `effort: medium`
+> - `tool_choice` must be `auto` (forced tool use not supported in Opus 5.5)
+
 > **Beat sheet gate:** Reply with a beat sheet and 4 keyframe descriptions first. Stop. Wait for approval before writing any scene code.
 
 ```
@@ -214,6 +221,16 @@ render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "crop",
 // 7. Full render (only after stills pass)
 render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "full",
                    audioPath: ".frameforge-files/voice_0.m4a" })
+
+// 8. Closed-loop QA fix protocol (mandatory — Opus 5.5 / Claude Code pattern)
+render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "quality" })
+// Returns: { passed, overallScore, worstFrames: [{time, score, issues}] }
+// If passed: false → fix loop (max 3 rounds):
+//   1. Read worstFrames[].  2. Patch edit.js for those timestamps only.
+//   3. render_animation({ mode: "strip", timestamps: [failingT - 0.5, failingT + 0.5] })
+//   4. render_animation({ mode: "quality" })
+//   5. Repeat until passed or 3 rounds — then escalate to user.
+// Never re-render full film to fix one timestamp. Use strip only.
 ```
 
 Requires one-time: `cd <outDir> && npm install playwright && npx playwright install chromium`

package/plugins/video-pipeline/skills/video-pipeline/assets/project/pipeline/briefings/orchestrator.md

@@ -7,6 +7,21 @@ You are the **orchestrator**. You own the full production timeline and the final
 You spawn scene-author and diagram-author subagents, integrate their output, and run
 the verification loop.
 
+## Model effort settings (Opus 5.5 / Claude Code)
+
+Use the right effort level at each stage — wrong effort wastes cost or quality:
+
+| Stage | effort | Reason |
+|-------|--------|--------|
+| Beat sheet + storyboard authorship | `xhigh` | New creative work — maximum reasoning |
+| First-time scene code authorship | `xhigh` | New composition, determinism matters |
+| Storyboard gate review / patch | `medium` | Analytical, not creative |
+| Strip-range patch (fix failing frames) | `medium` | Targeted surgical fix |
+| Encode-only / mux-only runs | `medium` | No creative decisions |
+| Research / scripting (Path 3) | `xhigh` for first draft, `medium` for revisions |
+
+`tool_choice` must always be `auto` — forced tool use is not supported in Opus 5.5.
+
 ## Order of operations
 
 ```

package/plugins/video-pipeline/skills/video-pipeline/assets/project/pipeline/briefings/scene-author.md

@@ -22,6 +22,27 @@ assigned to you by the orchestrator. You do not edit shared helpers.
 5. If `cuePhrase()` throws a fatal error, your scene has a missing voiceover phrase.
    Fix the phrase match before returning.
 
+## Revision attempt cap — 3 maximum
+
+You have a maximum of **3 revision attempts** per chapter assignment.
+
+- Attempt 1: Initial write → storyboard still → return.
+- Attempt 2: Patch based on orchestrator review → storyboard → return.
+- Attempt 3: Final fix → storyboard → return.
+
+**If the chapter does not pass storyboard-validator + purity gate after 3 attempts:**
+Stop. Do not attempt a 4th revision. Return to the orchestrator with:
+1. The exact error message from `storyboard-validator.mjs` or `verify-purity.mjs`.
+2. The specific line(s) in your scene file you believe are responsible.
+3. What you have already tried.
+
+Unbounded revision loops are the primary driver of token waste. 3 attempts is the cap.
+
+## Model effort
+
+Use `effort: xhigh` for the initial scene authorship. Use `effort: medium` for patch revisions.
+This matches the Opus 5.5 recommended settings: `xhigh` for new creative work, `medium` for targeted fixes.
+
 ## File naming
 
 Your chapter file is: `edit_chapter_N.js` where N is your chapter number.