@amg555/frameforge-mcp 2.7.3 → 2.7.7

package/plugins/video-pipeline/.claude-plugin/plugin.json

@@ -1,14 +1,14 @@
 {
   "name": "video-pipeline",
   "displayName": "FrameForge Video Pipeline",
-  "version": "2.7.3",
+  "version": "2.7.7",
   "description": "End-to-end AI video production. IDE writes scenes → FrameForge renders. Or: scaffold a Playwright+ffmpeg code-driven animation. Or: auto-research and script the video.",
   "skills": [
     {
       "name": "video-pipeline",
       "path": "skills/video-pipeline/SKILL.md",
       "displayName": "Video Pipeline",
-      "description": "28 MCP tools: create_video_from_script, edit_video, plan_video_edit, preview_scene, verify_scene_quality, scaffold_animation_project, render_animation, validate_storyboard, mix_audio_pro, transcribe_media, ingest_url, sync_upstream_skills, check_upstream_updates, and more."
+      "description": "34 MCP tools: create_video_from_script, edit_video, plan_video_edit, preview_scene, verify_scene_quality, scaffold_animation_project, render_animation, validate_storyboard, mix_audio_pro, transcribe_media, ingest_url, sync_upstream_skills, check_upstream_updates, list_motion_styles, get_motion_style_prompt, and more."
     },
     {
       "name": "html-renderer",

package/plugins/video-pipeline/skills/.upstream-skills.json

@@ -1,143 +1,156 @@
-{
-  "lastSync": "2026-11-11T19:56:18.351Z",
-  "repos": {
-    "hyperframes": {
-      "repo": "heygen-com/hyperframes",
-      "category": "compositor",
-      "desc": "Agent-native HTML/GSAP declarative video compositor",
-      "capabilities": [
-        "scaffold_animation_project",
-        "render_animation"
-      ],
-      "userImpact": "New compositor patterns or GSAP animation primitives available for HTML-rendered video",
-      "sha": "a243169",
-      "lastChecked": "2026-11-11T19:56:16.487Z",
-      "status": "synced"
-    },
-    "opuscar": {
-      "repo": "lemomo-ai/lemo-opuscar",
-      "category": "styles",
-      "desc": "Frontier cinematic and viral film styles catalog (12 styles)",
-      "capabilities": [
-        "plan_video_edit",
-        "edit_video",
-        "render_from_scenes"
-      ],
-      "userImpact": "New color grades or film styles available in plan_video_edit style parameter",
-      "sha": "9eb7739",
-      "lastChecked": "2026-11-11T19:56:16.692Z",
-      "status": "synced"
-    },
-    "onetake": {
-      "repo": "feitangyuan/onetake",
-      "category": "camera",
-      "desc": "Continuous single-shot camera choreography (zero-cut spline)",
-      "capabilities": [
-        "generate_scene_code",
-        "scaffold_animation_project"
-      ],
-      "userImpact": "New onetake camera transition patterns available for code-driven animation",
-      "sha": "abb6d17",
-      "lastChecked": "2026-11-11T19:56:16.855Z",
-      "status": "synced"
-    },
-    "collage-broll": {
-      "repo": "pyang5166/gbro-collage-broll",
-      "category": "broll",
-      "desc": "Editorial paper collage, halftone textures, 2.5D tilt",
-      "capabilities": [
-        "generate_scene_code",
-        "create_video_from_script"
-      ],
-      "userImpact": "New editorial collage / halftone visual templates available",
-      "sha": "a1a4ee2",
-      "lastChecked": "2026-11-11T19:56:17.057Z",
-      "status": "synced"
-    },
-    "remotion-skills": {
-      "repo": "remotion-dev/skills",
-      "category": "motion",
-      "desc": "First-party Remotion composition skills (spring physics)",
-      "capabilities": [
-        "scaffold_animation_project",
-        "render_animation"
-      ],
-      "userImpact": "New Remotion motion patterns or spring physics presets available",
-      "sha": "7e541aa",
-      "lastChecked": "2026-11-11T19:56:17.403Z",
-      "status": "synced"
-    },
-    "earshot": {
-      "repo": "Leonxlnx/earshot",
-      "category": "audio",
-      "desc": "Procedural CPU SFX synthesis and timeline sync (13-type library)",
-      "capabilities": [
-        "mix_audio_pro",
-        "create_video_from_script"
-      ],
-      "userImpact": "New procedural SFX cue types or audio sync patterns available in mix_audio_pro",
-      "sha": "4ac3d2a",
-      "lastChecked": "2026-11-11T19:56:17.839Z",
-      "status": "synced"
-    },
-    "claude-anim-base": {
-      "repo": "JohnHeibel/ClaudeAnimationBase",
-      "category": "animation",
-      "desc": "12fps hand-drawn cel boil, character emotions (Opus 5.5 patterns)",
-      "capabilities": [
-        "generate_scene_code",
-        "scaffold_animation_project"
-      ],
-      "userImpact": "New ClaudeAnimationBase patterns for 12fps organic boil or character emotion scenes",
-      "sha": "0ac8bf2",
-      "lastChecked": "2026-11-11T19:56:18.012Z",
-      "status": "synced"
-    },
-    "claude-remotion": {
-      "repo": "haidrrrry/claude-remotion-skill",
-      "category": "motion",
-      "desc": "10 hard motion craft rules, review loop, Opus 5.5 closed-loop QA",
-      "capabilities": [
-        "scaffold_animation_project",
-        "render_animation",
-        "verify_scene_quality"
-      ],
-      "userImpact": "Updated motion craft rules or QA patterns for the Opus 5.5 closed-loop correction pipeline",
-      "sha": "1dcbe5e",
-      "lastChecked": "2026-11-11T19:56:18.180Z",
-      "status": "synced"
-    },
-    "ffmpeg-skill": {
-      "repo": "kajisho5/ffmpeg-skill",
-      "category": "ffmpeg",
-      "desc": "42 typed-argparse FFmpeg tools, machine-readable contract, visual linter",
-      "capabilities": [
-        "edit_video",
-        "plan_video_edit",
-        "mix_audio_pro"
-      ],
-      "userImpact": "New FFmpeg filter patterns or video editing operations available",
-      "sha": "532cbe3",
-      "lastChecked": "2026-11-11T19:56:18.351Z",
-      "status": "synced"
-    }
-  },
-  "version": "2.7.3",
-  "updatedCount": 2,
-  "pendingUpdates": [
-    {
-      "id": "hyperframes",
-      "repo": "heygen-com/hyperframes",
-      "sha": "a243169",
-      "category": "compositor",
-      "userImpact": "New compositor patterns or GSAP animation primitives available for HTML-rendered video"
-    },
-    {
-      "id": "remotion-skills",
-      "repo": "remotion-dev/skills",
-      "sha": "7e541aa",
-      "category": "motion",
-      "userImpact": "New Remotion motion patterns or spring physics presets available"
-    }
-  ]
-}
+{
+  "lastSync": "2026-11-12T12:18:03.970Z",
+  "repos": {
+    "hyperframes": {
+      "repo": "heygen-com/hyperframes",
+      "category": "compositor",
+      "desc": "Agent-native HTML/GSAP declarative video compositor",
+      "capabilities": [
+        "scaffold_animation_project",
+        "render_animation"
+      ],
+      "userImpact": "New compositor patterns or GSAP animation primitives available for HTML-rendered video",
+      "sha": "a243169",
+      "lastChecked": "2026-11-12T12:18:02.184Z",
+      "status": "synced"
+    },
+    "opuscar": {
+      "repo": "lemomo-ai/lemo-opuscar",
+      "category": "styles",
+      "desc": "Frontier cinematic and viral film styles catalog (12 styles)",
+      "capabilities": [
+        "plan_video_edit",
+        "edit_video",
+        "render_from_scenes"
+      ],
+      "userImpact": "New color grades or film styles available in plan_video_edit style parameter",
+      "sha": "9eb7739",
+      "lastChecked": "2026-11-12T12:18:02.371Z",
+      "status": "synced"
+    },
+    "onetake": {
+      "repo": "feitangyuan/onetake",
+      "category": "camera",
+      "desc": "Continuous single-shot camera choreography (zero-cut spline)",
+      "capabilities": [
+        "generate_scene_code",
+        "scaffold_animation_project"
+      ],
+      "userImpact": "New onetake camera transition patterns available for code-driven animation",
+      "sha": "abb6d17",
+      "lastChecked": "2026-11-12T12:18:02.565Z",
+      "status": "synced"
+    },
+    "collage-broll": {
+      "repo": "pyang5166/gbro-collage-broll",
+      "category": "broll",
+      "desc": "Editorial paper collage, halftone textures, 2.5D tilt",
+      "capabilities": [
+        "generate_scene_code",
+        "create_video_from_script"
+      ],
+      "userImpact": "New editorial collage / halftone visual templates available",
+      "sha": "a1a4ee2",
+      "lastChecked": "2026-11-12T12:18:02.762Z",
+      "status": "synced"
+    },
+    "remotion-skills": {
+      "repo": "remotion-dev/skills",
+      "category": "motion",
+      "desc": "First-party Remotion composition skills (spring physics)",
+      "capabilities": [
+        "scaffold_animation_project",
+        "render_animation"
+      ],
+      "userImpact": "New Remotion motion patterns or spring physics presets available",
+      "sha": "7e541aa",
+      "lastChecked": "2026-11-12T12:18:03.021Z",
+      "status": "synced"
+    },
+    "earshot": {
+      "repo": "Leonxlnx/earshot",
+      "category": "audio",
+      "desc": "Procedural CPU SFX synthesis and timeline sync (13-type library)",
+      "capabilities": [
+        "mix_audio_pro",
+        "create_video_from_script"
+      ],
+      "userImpact": "New procedural SFX cue types or audio sync patterns available in mix_audio_pro",
+      "sha": "4ac3d2a",
+      "lastChecked": "2026-11-12T12:18:03.205Z",
+      "status": "synced"
+    },
+    "claude-anim-base": {
+      "repo": "JohnHeibel/ClaudeAnimationBase",
+      "category": "animation",
+      "desc": "12fps hand-drawn cel boil, character emotions (Opus 5.5 patterns)",
+      "capabilities": [
+        "generate_scene_code",
+        "scaffold_animation_project"
+      ],
+      "userImpact": "New ClaudeAnimationBase patterns for 12fps organic boil or character emotion scenes",
+      "sha": "0ac8bf2",
+      "lastChecked": "2026-11-12T12:18:03.388Z",
+      "status": "synced"
+    },
+    "claude-remotion": {
+      "repo": "haidrrrry/claude-remotion-skill",
+      "category": "motion",
+      "desc": "10 hard motion craft rules, review loop, Opus 5.5 closed-loop QA",
+      "capabilities": [
+        "scaffold_animation_project",
+        "render_animation",
+        "verify_scene_quality"
+      ],
+      "userImpact": "Updated motion craft rules or QA patterns for the Opus 5.5 closed-loop correction pipeline",
+      "sha": "1dcbe5e",
+      "lastChecked": "2026-11-12T12:18:03.571Z",
+      "status": "synced"
+    },
+    "ffmpeg-skill": {
+      "repo": "kajisho5/ffmpeg-skill",
+      "category": "ffmpeg",
+      "desc": "42 typed-argparse FFmpeg tools, machine-readable contract, visual linter",
+      "capabilities": [
+        "edit_video",
+        "plan_video_edit",
+        "mix_audio_pro"
+      ],
+      "userImpact": "New FFmpeg filter patterns or video editing operations available",
+      "sha": "532cbe3",
+      "lastChecked": "2026-11-12T12:18:03.766Z",
+      "status": "synced"
+    },
+    "aiinsight-shorts": {
+      "repo": "frameforge/aiinsight-shorts",
+      "category": "shorts",
+      "desc": "6-style faceless-shorts skill (Deep Dive 3D, Night File 3D, Inside Out, Stick Story, Paper Atlas, Tall Tale 3D) — canvas+three.js, Kokoro TTS, Whisper word-sync, ffmpeg MP4. By Motion Graphics / AI Insight Spot.",
+      "capabilities": [
+        "create_short",
+        "list_short_styles"
+      ],
+      "userImpact": "New faceless-shorts styles, kit components, or rendering techniques available from aiinsight-shorts upstream",
+      "sha": "v2.5.0",
+      "lastChecked": "2026-11-12T12:18:03.970Z",
+      "status": "synced"
+    }
+  },
+  "version": "2.7.7",
+  "updatedCount": 0,
+  "pendingUpdates": [
+    {
+      "id": "hyperframes",
+      "repo": "heygen-com/hyperframes",
+      "sha": "a243169",
+      "category": "compositor",
+      "userImpact": "New compositor patterns or GSAP animation primitives available for HTML-rendered video"
+    },
+    {
+      "id": "remotion-skills",
+      "repo": "remotion-dev/skills",
+      "sha": "7e541aa",
+      "category": "motion",
+      "userImpact": "New Remotion motion patterns or spring physics presets available"
+    }
+  ]
+}

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

@@ -403,9 +403,9 @@ No network requests — reads the local manifest only. Returns:
 ```json
 {
   "lastSync": "2026-11-11T20:00:00Z",
-  "manifestVersion": "2.7.3",
-  "totalRepos": 9,
-  "syncedCount": 9,
+  "manifestVersion": "2.7.7",
+  "totalRepos": 11,
+  "syncedCount": 11,
   "repos": [
     {
       "id": "hyperframes",

package/scripts/deep-validate.js

@@ -20,7 +20,7 @@ check('batch handling',              code.includes('Array.isArray(body)'));
 check('ping handler',                code.includes("method === 'ping'"));
 check('notifications/init',          code.includes("notifications/initialized"));
 check('body size limit',             code.includes('MAX_BODY_BYTES'));
-check('SERVER_INFO version 2.7.3',    code.includes("version: '2.7.3'"));
+check('SERVER_INFO version 2.7.7',    code.includes("version: '2.7.7'"));
 check('18 tools defined (incl get_job_status)', code.includes('get_job_status'));
 check('export_to_editor tool defined', code.includes('export_to_editor'));
 check('edit_video tool defined', code.includes('edit_video'));
@@ -30,6 +30,7 @@ check('verify_scene_quality tool defined', code.includes('verify_scene_quality')
 check('plan_video_edit tool defined', code.includes('plan_video_edit'));
 check('sync_upstream_skills tool defined', code.includes('sync_upstream_skills'));
 check('media-downloader exists', fs.existsSync('./src/utils/media-downloader.js'));
+check('tool-installer exists', fs.existsSync('./src/utils/tool-installer.js'));
 check('transcribe engine exists', fs.existsSync('./src/utils/transcribe.js'));
 check('sync-upstream script exists', fs.existsSync('./src/skills/sync-upstream.js'));
 check('video-editor exists', fs.existsSync('./src/video-editor/editor.js'));
@@ -367,7 +368,7 @@ check('cf-worker has checkRateLimit',   cfWorker.includes('checkRateLimit'));
 check('cf-worker hashes token (SHA-256)', cfWorker.includes('SHA-256'));
 check('cf-worker uses RATE_LIMITS KV',  cfWorker.includes('env.RATE_LIMITS'));
 check('cf-worker returns 429 on limit', cfWorker.includes('429'));
-check('cf-worker version 2.7.3',         cfWorker.includes("'2.7.3'"));
+check('cf-worker version 2.7.7',         cfWorker.includes("'2.7.7'"));
 check('wrangler.toml has kv_namespaces',fs.readFileSync('./cloudflare-mcp/wrangler.toml','utf8').includes('kv_namespaces'));
 
 // ── plugins/skills present ────────────────────────────────────────────────

package/src/audio-mixer/mixer.js

@@ -699,6 +699,75 @@ class AudioMixer {
     } catch { return []; }
   }
 
+  /**
+   * Mix SFX cues into a voice audio track (no music).
+   * Used for per-scene SFX injection before video encode.
+   * @param {string} voicePath  — input voice/narration .m4a
+   * @param {Array}  sfxCues    — [{ name, time, volume }]
+   * @param {string} outputPath — output .m4a
+   */
+  mixSfxIntoAudio(voicePath, sfxCues, outputPath) {
+    if (!Array.isArray(sfxCues) || sfxCues.length === 0) {
+      // Nothing to mix — just copy
+      const r = spawnSync('ffmpeg', ['-nostdin', '-y', '-i', voicePath, '-c', 'copy', outputPath],
+        { timeout: 30000, encoding: 'utf8' });
+      if (r.status !== 0) throw new Error(`SFX passthrough copy failed: ${(r.stderr || '').slice(-200)}`);
+      return outputPath;
+    }
+
+    const tmpDir = path.join(os.tmpdir(), `ff_sfx_${Date.now()}`);
+    fs.mkdirSync(tmpDir, { recursive: true });
+    try {
+      const durProbe = spawnSync('ffprobe', [
+        '-v', 'error', '-show_entries', 'format=duration',
+        '-of', 'default=nk=1:nw=1', voicePath,
+      ], { encoding: 'utf8', timeout: 10000 });
+      const totalDur = parseFloat((durProbe.stdout || '0').trim()) || 30;
+
+      const sfxPaths = sfxCues.map(cue => this._synthesizeSfxCue({
+        sfxName:       (cue.name || cue.sfxName || 'pop').toLowerCase().replace(/-/g, '_'),
+        cueTime:       Number(cue.time || cue.t || 0),
+        cueVol:        Number(cue.volume || cue.vol || 1.0),
+        totalDuration: totalDur,
+        tmpDir,
+      }));
+
+      // Merge all SFX into one track then amix with voice
+      let sfxTrackPath;
+      if (sfxPaths.length === 1) {
+        sfxTrackPath = sfxPaths[0];
+      } else {
+        sfxTrackPath = path.join(tmpDir, 'sfx_combined.m4a');
+        const sfxInputs = sfxPaths.flatMap(p => ['-i', p]);
+        const sfxFilter = sfxPaths.map((_, i) => `[${i}:a]`).join('') +
+          `amix=inputs=${sfxPaths.length}:duration=longest:normalize=0[sfxout]`;
+        const cr = spawnSync('ffmpeg', [
+          '-nostdin', '-y', ...sfxInputs,
+          '-filter_complex', sfxFilter, '-map', '[sfxout]',
+          '-c:a', 'aac', '-b:a', '128k', '-ar', '48000', '-ac', '2',
+          sfxTrackPath,
+        ], { encoding: 'utf8', timeout: 120000 });
+        if (cr.status !== 0) throw new Error(`SFX combine failed: ${(cr.stderr || '').slice(-200)}`);
+      }
+
+      // Mix voice + SFX
+      const mixR = spawnSync('ffmpeg', [
+        '-nostdin', '-y',
+        '-i', voicePath,
+        '-i', sfxTrackPath,
+        '-filter_complex', '[0:a][1:a]amix=inputs=2:duration=first:normalize=0[out]',
+        '-map', '[out]',
+        '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+        '-t', String(totalDur),
+        outputPath,
+      ], { timeout: 120000, encoding: 'utf8' });
+      if (mixR.status !== 0) throw new Error(`Voice+SFX mix failed: ${(mixR.stderr || '').slice(-200)}`);
+      return outputPath;
+    } finally {
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    }
+  }
+
   // ── Backward-compatible alias for older callers ──────────────────────────
   mixWithDuckingLegacy({ voicePath, musicPath = null, outputPath }) {
     return this.mixWithDucking({ voicePath, musicPath, outputPath });

package/src/cli/make.js

@@ -184,6 +184,13 @@ if (subCmd === 'setup') {
   return;
 }
 
+// 7. Dispatch to auto-installer
+if (subCmd === 'install' || subCmd === 'install-tools') {
+  const { autoInstallAll } = require('../utils/tool-installer');
+  autoInstallAll();
+  process.exit(0);
+}
+
 function parseArgs(argv) {
   const args = {
     mode: 'full-auto',
@@ -194,6 +201,7 @@ function parseArgs(argv) {
     captions: false, subtitles: false,
     scenesFile: '', scriptFile: '', mediaDir: '',
     shorts: true, dryRun: false,
+    sceneCount: null, targetDuration: null,
     noResearch: false, noScript: false, noImages: false, noTts: false, noPublish: false,
     outDir: './output', env: '.env',
   };
@@ -206,6 +214,8 @@ function parseArgs(argv) {
       case '--script-file':   args.scriptFile  = argv[++i] || '';  break;
       case '--media-dir':     args.mediaDir    = argv[++i] || '';  break;
       case '--language':      args.language    = (argv[++i] || 'en').toLowerCase(); break;
+      case '--scenes':        args.sceneCount  = parseInt(argv[++i], 10); break;
+      case '--duration':      args.targetDuration = parseFloat(argv[++i]); break;
       case '--orientation':   args.orientation = (argv[++i] || 'landscape').toLowerCase(); break;
       case '--portrait':      args.orientation = 'portrait'; break;
       case '--captions':
@@ -225,6 +235,11 @@ function parseArgs(argv) {
       case '--dry-run':       args.dryRun      = true; break;
       case '--out-dir':       args.outDir      = argv[++i] || args.outDir; break;
       case '--env':           args.env         = argv[++i] || args.env; break;
+      case '--install-tools': {
+        const { autoInstallAll } = require('../utils/tool-installer');
+        autoInstallAll();
+        break;
+      }
       case '--help': case '-h': printHelp(); process.exit(0); break;
     }
   }
@@ -432,6 +447,10 @@ async function runSingleVideo(args, topic, outDir, workflows) {
         claims:       researchResult.claims,
         topic,
         style:        args.style,
+        language:     args.language,
+        sceneCount:   args.sceneCount,
+        targetDuration: args.targetDuration,
+        format:       args.orientation === 'portrait' ? 'Shorts' : 'YouTube video',
       });
       scenes      = scriptResult.scenes;
       title       = scriptResult.title || topic;

package/src/harness/lib/browser.mjs

@@ -110,7 +110,28 @@ export async function launchHarnessBrowser(opts = {}) {
     launchOpts.executablePath = execPath;
   }
 
-  const browser = await chromium.launch(launchOpts);
+  let browser;
+  try {
+    browser = await chromium.launch(launchOpts);
+  } catch (launchErr) {
+    if ((launchErr.message || '').includes('playwright install') || (launchErr.message || '').includes('Executable')) {
+      try {
+        const { createRequire } = await import('module');
+        const req = createRequire(import.meta.url);
+        const { ensurePlaywrightChromium } = req('../../utils/tool-installer');
+        if (ensurePlaywrightChromium()) {
+          browser = await chromium.launch(launchOpts);
+        } else {
+          throw launchErr;
+        }
+      } catch (_) {
+        throw launchErr;
+      }
+    } else {
+      throw launchErr;
+    }
+  }
+
   return { browser, executablePath: execPath || 'bundled-chromium' };
 }
 

package/src/harness/lib/capture.mjs

@@ -141,10 +141,10 @@ export const VIRTUAL_CLOCK_INJECTION = `
       }
     } catch (_) {}
 
-    if (window.renderAt) {
-      await window.renderAt(t);
-    } else if (window.seek) {
+    if (window.seek) {
       await window.seek(t);
+    } else if (window.renderAt) {
+      await window.renderAt(t);
     }
     while (_timerQueue.length > 0 && _timerQueue[0].runAt <= _now) {
       const item = _timerQueue.shift();
@@ -154,11 +154,14 @@ export const VIRTUAL_CLOCK_INJECTION = `
       await document.fonts.ready;
     }
 
+    // Wait for any delayRender handles — max 3s to avoid pipeline stalls
     if (_delayHandles.size > 0) {
       const startW = _realDateNow();
-      while (_delayHandles.size > 0 && _realDateNow() - startW < 10000) {
+      while (_delayHandles.size > 0 && _realDateNow() - startW < 3000) {
         await new Promise(r => _realSetTimeout(r, 10));
       }
+      // Force-clear stale handles so we never block indefinitely
+      _delayHandles.clear();
     }
   };
 })();
@@ -194,22 +197,41 @@ export async function openPageWithVirtualClock(browserOrOpts, htmlPathArg, optsA
   return page;
 }
 
-export async function captureFrame(page, t, { type = 'image/png', quality = 0.94 } = {}) {
+export async function captureFrame(page, t, { type = 'image/png', quality = 0.94, timeoutMs = 15000 } = {}) {
+  // page.evaluate with an explicit timeout so a hung seek() never stalls the whole pipeline
   const dataUrl = await page.evaluate(async ({ time, mime, q }) => {
     await window.__seek(time);
     if (window.renderAt) {
-      return await window.renderAt(time, mime, q);
+      const res = await window.renderAt(time, mime, q);
+      if (typeof res === 'string' && res.includes(',')) return res;
+    }
+    const canvas = document.getElementById('stage') || document.querySelector('canvas');
+    if (canvas && typeof canvas.toDataURL === 'function') {
+      try {
+        return canvas.toDataURL(mime, q);
+      } catch (_) {}
     }
     return null;
-  }, { time: t, mime: type, q: quality });
+  }, { time: t, mime: type, q: quality }, { timeout: timeoutMs });
 
   if (typeof dataUrl === 'string' && dataUrl.includes(',')) {
     return Buffer.from(dataUrl.slice(dataUrl.indexOf(',') + 1), 'base64');
   }
 
   const screenshotType = type === 'image/jpeg' ? 'jpeg' : 'png';
-  return page.screenshot({
-    type: screenshotType,
-    quality: screenshotType === 'jpeg' ? Math.round(quality * 100) : undefined,
-  });
+  let lastErr;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      return await page.screenshot({
+        type: screenshotType,
+        quality: screenshotType === 'jpeg' ? Math.round(quality * 100) : undefined,
+      });
+    } catch (err) {
+      lastErr = err;
+      if (attempt < 2) {
+        await new Promise(r => setTimeout(r, 60 * (attempt + 1)));
+      }
+    }
+  }
+  throw lastErr;
 }

package/src/harness/lib/jobs.mjs

@@ -92,6 +92,9 @@ export async function renderFrameJobs({
 
   await Promise.all(
     pages.map(async (page) => {
+      // Per-frame timeout: 20s is generous for a single seek+capture at 1920×1080
+      const FRAME_TIMEOUT_MS = 20000;
+
       while (true) {
         let frameIdx;
         if (nextIdx < todo.length) {
@@ -105,7 +108,19 @@ export async function renderFrameJobs({
         const targetFile = path.join(framesDir, filename);
         const tmpFile = `${targetFile}.tmp`;
 
-        const buf = await captureFrame(page, t, { type: mimeType, quality });
+        let buf = null;
+        for (let attempt = 0; attempt < 3; attempt++) {
+          try {
+            buf = await captureFrame(page, t, { type: mimeType, quality, timeoutMs: FRAME_TIMEOUT_MS });
+            if (buf && buf.length > 500) break;
+          } catch (err) {
+            if (attempt === 2) throw err;
+            await new Promise(r => setTimeout(r, 80 * (attempt + 1)));
+          }
+        }
+        if (!buf || buf.length <= 500) {
+          throw new Error(`Frame ${frameIdx} captured corrupted or empty image (${buf ? buf.length : 0} bytes)`);
+        }
 
         // Atomic write: write to temp file then rename
         fs.writeFileSync(tmpFile, buf);