@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/video-pipeline/assets/project/reel/virtual-clock.js

@@ -1,168 +0,0 @@
-/**
- * virtual-clock.js — FrameForge Deterministic Virtual Clock Shim
- *
- * Intercepts browser timing primitives to enable frame-exact, deterministic
- * time control for headless video rendering.
- *
- * Laws enforced:
- *   1. Read time, not frames (seek(t) is absolute time in seconds).
- *   2. Seed everything (Math.random replaced with seeded PRNG).
- *   3. No integrating physics (timers scheduled along virtual timeline).
- *   4. Await document.fonts.ready before resolving seek().
- */
-(() => {
-  let virtualTime = 0;
-  const rafCallbacks = new Map();
-  let rafIdCounter = 0;
-  const timeoutQueue = [];
-  let timeoutIdCounter = 0;
-  const _realDateNow = Date.now;
-  const _realSetTimeout = window.setTimeout;
-  const startDate = _realDateNow();
-
-  window.__playwright = true;
-
-  // 1. Hijack performance.now & Date
-  window.performance.now = () => virtualTime;
-  const OriginalDate = window.Date;
-  class VirtualDate extends OriginalDate {
-    constructor(...args) {
-      if (args.length === 0) {
-        super(startDate + virtualTime);
-      } else {
-        super(...args);
-      }
-    }
-    static now() {
-      return Math.floor(startDate + virtualTime);
-    }
-  }
-  window.Date = VirtualDate;
-
-  // 2. Hijack requestAnimationFrame & cancelAnimationFrame
-  window.requestAnimationFrame = (callback) => {
-    const id = ++rafIdCounter;
-    rafCallbacks.set(id, callback);
-    return id;
-  };
-  window.cancelAnimationFrame = (id) => {
-    rafCallbacks.delete(id);
-  };
-
-  // 3. Hijack setTimeout / clearTimeout / setInterval / clearInterval
-  window.setTimeout = (callback, delay = 0, ...args) => {
-    const id = ++timeoutIdCounter;
-    timeoutQueue.push({ id, runAt: virtualTime + Math.max(0, delay), callback, args, repeat: 0 });
-    timeoutQueue.sort((a, b) => a.runAt - b.runAt);
-    return id;
-  };
-  window.clearTimeout = (id) => {
-    const idx = timeoutQueue.findIndex(item => item.id === id);
-    if (idx !== -1) timeoutQueue.splice(idx, 1);
-  };
-  window.setInterval = (callback, interval = 0, ...args) => {
-    const id = ++timeoutIdCounter;
-    const step = Math.max(16, interval);
-    timeoutQueue.push({ id, runAt: virtualTime + step, callback, args, repeat: step });
-    timeoutQueue.sort((a, b) => a.runAt - b.runAt);
-    return id;
-  };
-  window.clearInterval = (id) => {
-    const idx = timeoutQueue.findIndex(item => item.id === id);
-    if (idx !== -1) timeoutQueue.splice(idx, 1);
-  };
-
-  // 4. Seeded PRNG replacement for Math.random()
-  // CRITICAL: re-derive seed from virtualTime on every call so that seek(t) gives
-  // the SAME random sequence regardless of how many frames were rendered before it.
-  // This matches the harness-injected shim in capture.mjs and ensures dev-preview
-  // mode is deterministic even without Playwright in the loop.
-  window.Math.random = () => {
-    let s = (0x2F6E2B1 ^ Math.imul(Math.floor(virtualTime), 0x9E3779B9)) | 0;
-    s = (s + 0x6D2B79F5) | 0;
-    let x = Math.imul(s ^ (s >>> 15), 1 | s);
-    x = (x + Math.imul(x ^ (x >>> 7), 61 | x)) ^ x;
-    return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
-  };
-
-  // 4b. Remotion-pattern delayRender / continueRender async barrier
-  const delayRenderHandles = new Set();
-  let delayRenderCounter = 0;
-  window.delayRender = (label = 'asset') => {
-    const id = ++delayRenderCounter;
-    delayRenderHandles.add(id);
-    return id;
-  };
-  window.continueRender = (id) => {
-    delayRenderHandles.delete(id);
-  };
-  window.cancelRender = (err) => {
-    console.error("Render cancelled:", err);
-  };
-
-  // 5. Global seek contract
-  window.seek = async (tSeconds) => {
-    virtualTime = tSeconds * 1000;
-    seed = (0x2F6E2B1 ^ Math.imul(Math.floor(tSeconds * 1000), 0x9E3779B9)) | 0;
-
-    // Flush due timeouts
-    while (timeoutQueue.length > 0 && timeoutQueue[0].runAt <= virtualTime) {
-      const item = timeoutQueue.shift();
-      try {
-        item.callback(...item.args);
-      } catch (err) {
-        console.error("VirtualClock Timeout Error:", err);
-      }
-      if (item.repeat > 0) {
-        item.runAt = virtualTime + item.repeat;
-        timeoutQueue.push(item);
-        timeoutQueue.sort((a, b) => a.runAt - b.runAt);
-      }
-    }
-
-    // Flush current RAF callbacks
-    const currentRafs = Array.from(rafCallbacks.values());
-    rafCallbacks.clear();
-    for (const cb of currentRafs) {
-      try {
-        cb(virtualTime);
-      } catch (err) {
-        console.error("VirtualClock RAF Error:", err);
-      }
-    }
-
-    // Pause & seek CSS animations
-    try {
-      if (document.getAnimations) {
-        document.getAnimations().forEach(a => {
-          if (a.playState !== 'paused') a.pause();
-          a.currentTime = virtualTime;
-        });
-      }
-    } catch (_) {}
-
-    // Custom scene render hook if exposed
-    if (typeof window.renderFrame === "function") {
-      await window.renderFrame(tSeconds);
-    }
-
-    // Await font readiness
-    if (document.fonts && document.fonts.ready) {
-      await document.fonts.ready;
-    }
-
-    // Await all async delayRender handles before resolving seek
-    if (delayRenderHandles.size > 0) {
-      const startW = _realDateNow();
-      while (delayRenderHandles.size > 0 && _realDateNow() - startW < 10000) {
-        await new Promise(r => _realSetTimeout(r, 10));
-      }
-    }
-  };
-
-  // Bridge for renderer
-  window.__seek = window.seek;
-
-  window.__VIRTUAL_CLOCK_INSTALLED__ = true;
-})();
-

package/.agent/skills/video-pipeline/references/mcp-tools.md

@@ -1,441 +0,0 @@
-# MCP Tool Reference
-
-FrameForge exposes **28 tools** on the HTTP MCP server (`http://localhost:3210`)
-and via the Cloudflare Remote MCP proxy. Any MCP-compatible client works:
-IBM Bob, Claude Code, Codex, opencode, Cursor, Windsurf, Kiro, Copilot.
-
----
-
-## Agent-first path (recommended)
-
-The IDE writes the scenes array; FrameForge renders it.
-
-### create_video_from_script
-
-```json
-{
-  "scenes": [
-    {
-      "narration": "WiFi sends data as invisible radio waves.",
-      "caption": "RADIO WAVES",
-      "visual_description": "router emitting waves, flat illustration",
-      "camera_hint": "slow_zoom_in",
-      "music_mood": "calm"
-    }
-  ],
-  "title": "How WiFi Works",
-  "skipImages": false,
-  "withMusic": true
-}
-```
-
-Returns: `{ productionId, masterPath, passed, sizeBytes, sceneCount }`
-
----
-
-## Full pipeline path
-
-### research_topic
-
-```json
-{ "topic": "How does GPS work?", "claimCount": 10, "style": "educational" }
-```
-
-### write_script
-
-```json
-{
-  "productionId": "prod-001",
-  "claims": ["..."],
-  "topic": "How does GPS work?",
-  "persona": "tech explainer",
-  "sceneCount": 15
-}
-```
-
-Returns: `{ productionId, scenes, title, description, tags, sceneCount }`
-
-### generate_scene_image
-
-```json
-{
-  "productionId": "prod-001",
-  "sceneIndex": 0,
-  "visualDescription": "router emitting waves, flat illustration",
-  "imagePath": "/optional/custom/image.png"
-}
-```
-
-Registers or generates code-driven visual card for one scene.
-
-### render_tts
-
-```json
-{
-  "productionId": "prod-001",
-  "sceneIndex": 0,
-  "text": "WiFi sends data as invisible radio waves.",
-  "voice": "en-US-GuyNeural"
-}
-```
-
-Converts scene narration text to audio using configured TTS provider.
-
-### assemble_video
-
-```json
-{
-  "productionId": "prod-001",
-  "sceneCount": 15,
-  "withMusic": true,
-  "musicVolume": 0.07
-}
-```
-
-Assembles rendered scenes into final MP4 and validates quality gate.
-
-### render_from_scenes
-
-```json
-{ "productionId": "prod-001", "skipImages": false, "withMusic": true }
-```
-
-### publish_video
-
-```json
-{
-  "productionId": "prod-001",
-  "masterPath": "/path/to/final_video.mp4",
-  "channels": ["file"],
-  "outputDir": "/path/to/output"
-}
-```
-
-Channels:
-- `file` — copy master + shorts to `outputDir` (or `N8N_FILES_DIR/published/`)
-- `webhook` — POST JSON summary to `PUBLISH_WEBHOOK_URL`
-
----
-
-## Edit path
-
-### ingest_media
-
-```json
-{ "files": ["/path/to/clip1.mp4", "/path/to/clip2.mp4"], "title": "My Video" }
-```
-
-### edit_scenes
-
-```json
-{
-  "productionId": "prod-001",
-  "edits": [{ "sceneIndex": 0, "field": "caption", "value": "NEW CAPTION" }]
-}
-```
-
----
-
-## TTS
-
-### multi_voice_tts
-
-```json
-{
-  "text": "The text to speak aloud.",
-  "outputPath": "/files-dir/voice_0.m4a",
-  "platform": "elevenlabs",
-  "voice": "your_cloned_voice_id",
-  "apiKey": "sk_..."
-}
-```
-
----
-
-## Async job control
-
-### queue_full_pipeline
-
-```json
-{
-  "topic": "Why planes avoid straight lines",
-  "style": "educational",
-  "channels": ["file"]
-}
-```
-
-Returns `{ jobId, status }` immediately. Poll `get_job_status` for completion.
-
-### get_job_status
-
-```json
-{ "jobId": "job_1234567890_abc123" }
-```
-
-Returns `{ status: "RUNNING"|"SUCCEEDED"|"FAILED", result, error }`
-
----
-
-## External platform
-
-### external_platform_call
-
-```json
-{ "action": "ingest", "files": ["/path/to/clip.mp4"] }
-```
-
-Actions: `ingest` | `render` | `status` | `download`.
-Configure with `EXTERNAL_PLATFORM_URL` + `EXTERNAL_PLATFORM_KEY` in `.env`.
-
----
-
-## Media ingestion (yt-dlp & Whisper)
-
-### ingest_url — Download from any web URL
-
-```json
-{
-  "url": "https://youtube.com/watch?v=...",
-  "format": "video",
-  "outputDir": ".frameforge-files/downloads/"
-}
-```
-
-Requires `yt-dlp` in PATH. Supports 1000+ sites. Returns `{ localPath, duration, width, height }`.
-
-### transcribe_media — Whisper word-level timestamps
-
-```json
-{
-  "mediaPath": ".frameforge-files/voice_0.m4a",
-  "model": "base",
-  "format": "all",
-  "language": "en"
-}
-```
-
-Returns `{ outputs: { ndjson, srt, json }, pauses, wordCount }`. NDJSON feeds `captions()` in engine.js.
-
----
-
-## Professional audio post-production
-
-### mix_audio_pro — 15+ year sound engineer chain
-
-```json
-{
-  "voicePath": ".frameforge-files/voice_0.m4a",
-  "outputPath": ".frameforge-files/audio_pro.m4a",
-  "musicPath": "/path/to/bg-music.mp3",
-  "platform": "youtube",
-  "roomProfile": "cinematic",
-  "noiseGate": true,
-  "stereoWiden": true,
-  "sfxCues": [
-    { "name": "whoosh",   "time": 2.5,  "volume": 0.8 },
-    { "name": "impact",   "time": 8.0,  "volume": 1.0 },
-    { "name": "riser",    "time": 18.0, "volume": 0.7 },
-    { "name": "deep_boom","time": 30.0, "volume": 0.9 },
-    { "name": "sparkle",  "time": 35.2, "volume": 0.4 }
-  ]
-}
-```
-
-Chain: noise gate → 80Hz HPF → presence EQ → de-esser → compressor → room acoustics → sidechain duck → stereo widen → SFX → EBU R128 loudnorm.
-SFX types: whoosh | impact | pop | click | riser | chime | buzz | tick | swish | punch | sparkle | deep_boom | transition
-Room profiles: studio_dry | broadcast | cinematic | concert_hall | intimate
-Platform presets: youtube (-14 LUFS) | podcast (-16) | broadcast (-23) | netflix (-27) | instagram (-14)
-
----
-
-## Video editing & planning
-
-### plan_video_edit — Plan/Approve/Render
-
-```json
-{
-  "footage": ["/path/clip1.mp4", "/path/clip2.mp4"],
-  "goal": "Create a cinematic product showcase",
-  "style": "cinematic_anamorphic",
-  "target_duration": 60,
-  "audio_path": ".frameforge-files/voice_0.m4a",
-  "music_path": "/path/to/bg.mp3"
-}
-```
-
-Style options include all lemo-opuscar film styles:
-`cinematic` | `fast_paced` | `documentary` | `vintage` | `cyberpunk` | `vibrant`
-`editorial_collage` | `retro_vhs` | `anime_action` | `sci_fi_hud` | `lofi_chill` | `minimal_monochrome`
-`cinematic_anamorphic` | `broadcast_news` | `blueprint_3d` | `film_16mm` | `product_obsidian` | `retro_vhs_80s`
-
-Returns: `{ planPath, editJsonPath, planMarkdown, editConfig }`.
-
-### edit_video — Execute planned cuts and color grading
-
-```json
-{
-  "edit_file": ".frameforge-files/edit.json",
-  "footage": ["/path/clip1.mp4", "/path/clip2.mp4"],
-  "output_path": ".frameforge-files/final_cut.mp4",
-  "cuts": [
-    { "clip": 0, "start": 0, "end": 4.5, "speed": 1.0, "color_grade": "cinematic", "transition": "fade" }
-  ],
-  "audio_path": ".frameforge-files/voice_0.m4a",
-  "music_path": "/path/to/bg.mp3",
-  "color_grade": "cinematic",
-  "auto_fit": true
-}
-```
-
-Renders frame-exact edits with FFmpeg filtergraphs, J/L-cuts, pan/zoom camera moves, and color grading.
-
-### export_to_editor — Export to Premiere Pro / DaVinci Resolve
-
-```json
-{
-  "project_dir": ".frameforge-files/project",
-  "format": "edl",
-  "output_path": ".frameforge-files/project/timeline.edl",
-  "title": "FrameForge Timeline"
-}
-```
-
-Formats: `edl` (CMX 3600), `fcpxml` (Final Cut Pro / DaVinci), `otio` (OpenTimelineIO).
-
----
-
-## Code-driven HTML animation (Claude Opus 5.5 pure-function-of-t)
-
-### scaffold_animation_project
-
-```json
-{
-  "outDir": "./my-animation",
-  "title": "Why Planets Orbit",
-  "width": 1920,
-  "height": 1080,
-  "fps": 30,
-  "scenes": [
-    { "narration": "Gravity curves spacetime.", "caption": "SPACETIME CURVATURE" }
-  ]
-}
-```
-
-Scaffolds a zero-diffusion HTML compositor project (`index.html`, `reel/engine.js`, `edit.js`, `scripts/render.mjs`).
-
-### validate_storyboard
-
-```json
-{ "storyboardPath": "./my-animation/STORYBOARD.md" }
-```
-
-Validates storyboard against 4 hard gates: event timestamps, non-overlapping reads, named transitions, no on-screen text slop.
-
-### generate_scene_code
-
-```json
-{
-  "visual_description": "Sun bending gravity grid with orbiting Earth particle trail",
-  "caption": "SPACETIME CURVATURE",
-  "style": "cosmic_space",
-  "duration": 4.0
-}
-```
-
-Generates pure mathematical `window.seek(t)` canvas animation code.
-
-### preview_scene
-
-```json
-{
-  "html": "<html>...</html>",
-  "duration": 4.0,
-  "timestamps": [0.1, 2.0, 3.9]
-}
-```
-
-Renders headless Chromium still frames (PNGs) to let the agent visually inspect layout, typography, and colors before rendering.
-
-### verify_scene_quality
-
-```json
-{
-  "htmlPath": "./my-animation/scene_1.html",
-  "duration": 4.0,
-  "sampleRate": 2
-}
-```
-
-Closed-loop QA grading (1–10 score): content presence, exposure, layout balance, motion delta. Returns worst frames for automated patch loop.
-
-### render_animation
-
-```json
-{
-  "projectDir": "./my-animation",
-  "mode": "full"
-}
-```
-
-Modes: `full` (renders MP4), `sheet` (contact sheet), `stills` (specific frames), `strip` (motion strip), `look` (pre-render linter), `quality` (QA gate), `golden` (regression diff).
-Returns `{ success, videoPath, sfxEvents }`.
-
-
-### sync_upstream_skills — Fetch new commits from 9 reference repos
-
-```json
-{ "silent": false }
-```
-
-Makes GitHub API requests. Returns `{ updatedRepos, perCategoryUpdates, lastSync }`.
-Each category update includes: `repo`, `sha`, `desc`, `userImpact`, `capabilities[]`.
-
-Tracked repos: HyperFrames, lemo-opuscar, OneTake, gbro-collage-broll, remotion-dev/skills,
-earshot, ClaudeAnimationBase, claude-remotion-skill, ffmpeg-skill.
-
-### check_upstream_updates — Fast offline manifest read
-
-```json
-{}
-```
-
-No network requests — reads the local manifest only. Returns:
-```json
-{
-  "lastSync": "2026-11-11T20:00:00Z",
-  "manifestVersion": "2.7.6",
-  "totalRepos": 11,
-  "syncedCount": 11,
-  "repos": [
-    {
-      "id": "hyperframes",
-      "repo": "heygen-com/hyperframes",
-      "category": "compositor",
-      "sha": "a1b2c3d",
-      "lastChecked": "...",
-      "userImpact": "New compositor patterns or GSAP animation primitives available"
-    }
-  ],
-  "hint": "Run sync_upstream_skills to fetch latest commits from GitHub."
-}
-```
-
-Call this to show users their current sync status without making any API calls.
-
----
-
-## Calling from any IDE
-
-Any IDE that supports MCP calls these tools via JSON-RPC:
-
-```json
-POST http://localhost:3210
-{
-  "method": "tools/call",
-  "params": {
-    "name": "create_video_from_script",
-    "arguments": { "scenes": [...] }
-  },
-  "id": 1
-}
-```

package/.agent/skills/video-pipeline/references/motion-craft.md

@@ -1,91 +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.