@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/html-renderer/references/hyperframes-motion.md

@@ -1,208 +0,0 @@
-# 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/.agent/skills/html-renderer/references/motion-craft.md

@@ -1,92 +0,0 @@
-# Motion Craft Reference — 10 Hard Motion Craft Rules
-
-This guide defines the production motion design standards implemented across FrameForge and the HTML-as-compositor rendering pipeline.
-
----
-
-## 1. Springs, Not Linear Easing
-Real physical motion never moves at constant velocity or abrupt linear ramps. Every entrance and transition must model a damped harmonic oscillator:
-
-$$\ddot{x} + 2\zeta\omega\dot{x} + \omega^2 x = 0$$
-
-- **Default tension**: `160 - 200`
-- **Default friction**: `13 - 16`
-- **Closed-form function**: `spring(t, delay, tension, friction)` maps pure time $t$ to normalized displacement $[0, 1]$ with natural overshoot and settling.
-
----
-
-## 2. Three-Property Entrances
-Never animate a single property (such as opacity alone or scale alone). High-production visuals orchestrate three coordinated properties for every entering entity:
-1. **Scale**: $0.88 \to 1.0$ (spatial arrival)
-2. **Opacity**: $0.0 \to 1.0$ (perceptual fade)
-3. **Translation**: $Y: +40\text{px} \to 0\text{px}$ or $X: \pm 60\text{px} \to 0\text{px}$ (directional momentum)
-
----
-
-## 3. Staggered Entrance Choreography
-Never trigger all elements simultaneously. When rendering cards, list items, or diagram nodes:
-- Stagger siblings by $0.15\text{s} - 0.28\text{s}$ relative to base timestamp.
-- Hierarchy flows from primary anchor $\to$ structural components $\to$ explanatory callouts $\to$ micro-badges.
-
----
-
-## 4. Asymmetric Timing: Exits Faster Than Entrances
-- **Entrances**: Informative, welcoming, gentle settling ($0.5\text{s} - 0.8\text{s}$ duration).
-- **Exits**: Crisp, decisive, purposeful ($0.2\text{s} - 0.35\text{s}$ duration). Exits must clear the stage without lingering.
-
----
-
-## 5. Five-Layer Depth Stack
-Every scene must maintain clear atmospheric depth across 5 distinct visual layers:
-- **Layer 1: Ambient Backdrop** — Radial gradients, atmospheric tint, depth falloff.
-- **Layer 2: Environment / Context** — Architectural wainscoting, blueprint grid, floor plane, distant mountain ridges, or starry cosmos.
-- **Layer 3: Primary Visual Entity** — The core subject (doodle character, cutaway engine, split comparison cards, neural insight core, or optical loupe).
-- **Layer 4: Explanatory Callouts & Overlays** — Connecting vector lines, animated pulse packets, telemetry tags, and indicator badges.
-- **Layer 5: Foreground Framing & Vignette** — Subtle radial corner shading, specular glass arcs, or foreground foliage.
-
----
-
-## 6. Continuous Audio-Driven Camera Progression
-Scenes must never switch camera angles at arbitrary fixed timer intervals. Camera motion is a continuous parametric function of speech duration:
-
-$$p = \frac{t}{\text{DURATION}}$$
-
-- **Dynamic zoom**: $1.0 + p \times 0.08$
-- **Dynamic pan**: Organic Lissajous drift ($\sin(0.4t) \times 6\text{px}$)
-- **Cut synchronization**: Scene cuts occur strictly on spoken sentence boundaries and audio cues.
-
----
-
-## 7. Continuous Life (Zero Frozen PowerPoint Slides)
-Every frame must contain subtle life. An audience detects static images instantly:
-- Rotating gears ($t \times \omega$)
-- Oscillating telemetry needles and wave pulses
-- Flowing data packets along pipeline tracks
-- Gentle character breathing and foliage sway ($\sin(3t) \times 4\text{px}$)
-
----
-
-## 8. Hand-Drawn Boil Wobble at 12fps
-When rendering hand-drawn doodle characters and sketch line work, apply authentic 12fps line boil wobble:
-- Quantize step to 12fps: `step = Math.floor(t * 12)`
-- Use seeded deterministic trigonometric noise:
-  `Math.sin(seed * 19.37 + step * 2.41) * 2.4`
-- Never use `Math.random()` inside the render loop.
-
----
-
-## 9. Regional Typography & HarfBuzz Text Shaping
-Ensure professional typographic hierarchy:
-- Auto-detect script (Malayalam: Manjari / Gayathri / Chilanka; Devanagari: Noto Sans Devanagari; Latin: Inter / Rajdhani / Cinzel).
-- Maintain WCAG AAA contrast ratios against backgrounds.
-- Gate on-screen subtitles: display narration text only when explicitly requested in prompt.
-
----
-
-## 10. Closed-Loop Visual QA Gate
-Never deliver rendered video blind. The production harness must execute automated quality checks across 4 axes:
-1. **Content Presence**: Non-blank ($> 1.5\%$ foreground variance).
-2. **Luminance / Exposure**: Non-blown ($< 96\%$ overexposure).
-3. **Compositional Distribution**: Not corner-confined ($> 12\%$ bbox coverage).
-4. **Motion Delta Verification**: Test frame delta between $t = 30\%$ and $t = 70\%$ to guarantee continuous animation.
-

package/.agent/skills/html-renderer/references/onetake-camera.md

@@ -1,59 +0,0 @@
-# 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/.agent/skills/html-renderer/references/procedural-sfx.md

@@ -1,147 +0,0 @@
-# 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()` and `event()` functions):
-```javascript
-import { cue, event, ROOM_SFX } from './reel/engine.js';
-
-// cue() — registers in window.__cues (legacy, render.mjs live preview)
-cue('whoosh',    2.5, 0.8);
-cue('impact',   8.0, 1.0);
-cue('riser',   18.0, 0.7);
-cue('deep_boom',30.0, 0.9);
-
-// event() — registers in window.__events() and is written to out/sfx-events.json
-// by render.mjs after probe. mix_audio_pro.py reads it automatically.
-event('sfx', 2.5,  { sfxName: 'whoosh',    vol: 0.8 });
-event('sfx', 8.0,  { sfxName: 'impact',    vol: 1.0 });
-event('sfx', 30.0, { material: 'sub',      vol: 0.9 }); // OneTake ROOM_SFX → deep_boom
-
-// Then: render.mjs writes out/sfx-events.json
-// mix_audio_pro.py reads it automatically (no --sfx flags needed):
-//   uv run scripts/mix_audio_pro.py --music assets/bg.mp3 --platform youtube --room broadcast
-```
-
----
-
-## 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/.agent/skills/html-renderer/references/remotion-patterns.md

@@ -1,159 +0,0 @@
-# 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);
-```
-