@hyperframes/producer 0.9.19 → 0.9.21

package/dist/distributed.js

@@ -8,13 +8,13 @@ import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframe
 import {
   copyFileSync as copyFileSync6,
   cpSync as cpSync2,
-  existsSync as existsSync18,
+  existsSync as existsSync19,
   linkSync,
   mkdirSync as mkdirSync10,
   rmSync as rmSync7,
   writeFileSync as writeFileSync8
 } from "node:fs";
-import { extname as extname4, isAbsolute as isAbsolute3, join as join25, relative as relative5, sep as sep2 } from "node:path";
+import { extname as extname4, isAbsolute as isAbsolute3, join as join25, relative as relative5, sep as sep3 } from "node:path";
 import {
   fpsToNumber as fpsToNumber9,
   HF_COLOR_GRADING_ATTR as HF_COLOR_GRADING_ATTR2
@@ -71,7 +71,7 @@ var defaultLogger = createConsoleLogger("info");
 // src/services/renderOrchestrator.ts
 import { audioFailureDiagnostics as audioFailureDiagnostics2 } from "@hyperframes/engine";
 import {
-  existsSync as existsSync13,
+  existsSync as existsSync14,
   mkdirSync as mkdirSync6,
   readdirSync as readdirSync3,
   rmSync as rmSync5,
@@ -430,6 +430,68 @@ ${seededRandomBlock}
     }
   };
 
+  // Timers set once rendering has started run on film time: each seek fires every timer due by then, in
+  // due order. Until a seek after the page reports ready, timers keep the wall clock: setup code waits on
+  // them while the renderer may already be seeking.
+  var rendering = false;
+  var timerQueue = [];
+  var nextTimerId = 1000000000;
+  var firingDepth = 0;
+  function addTimer(callback, delay, args, repeats) {
+    // A timer set from a firing timer waits at least 1 ms, so a zero-delay chain cannot stall a seek.
+    var ms = Math.max(firingDepth > 0 ? 1 : 0, Number(delay) || 0);
+    var entry = { id: nextTimerId++, callback: callback, args: args, due: virtualNowMs + ms, every: repeats ? Math.max(1, ms) : 0, cancelled: false };
+    timerQueue.push(entry);
+    return entry.id;
+  }
+  function cancelTimer(id) {
+    for (var i = 0; i < timerQueue.length; i++) {
+      if (timerQueue[i].id === id) {
+        timerQueue[i].cancelled = true;
+        return true;
+      }
+    }
+    return false;
+  }
+  function fireDueTimers(untilMs) {
+    // Frame times are fractional, so a timer due on a frame lands a rounding error past it; it still fires on it.
+    untilMs += 0.000001;
+    while (true) {
+      var next = null;
+      for (var i = 0; i < timerQueue.length; i++) {
+        var candidate = timerQueue[i];
+        if (!candidate.cancelled && candidate.due <= untilMs && (next === null || candidate.due < next.due)) next = candidate;
+      }
+      if (next === null) break;
+      var dueMs = next.due;
+      if (next.every) next.due += next.every;
+      else next.cancelled = true;
+      virtualNowMs = dueMs;
+      firingDepth++;
+      try {
+        next.callback.apply(window, next.args);
+      } catch (err) {
+        originalSetTimeout(function() { throw err; }, 0);
+      }
+      firingDepth--;
+    }
+    timerQueue = timerQueue.filter(function(entry) { return !entry.cancelled; });
+  }
+  window.setTimeout = function(callback, delay) {
+    if (!rendering || typeof callback !== "function") return originalSetTimeout.apply(null, arguments);
+    return addTimer(callback, delay, Array.prototype.slice.call(arguments, 2), false);
+  };
+  window.setInterval = function(callback, delay) {
+    if (!rendering || typeof callback !== "function") return originalSetInterval.apply(null, arguments);
+    return addTimer(callback, delay, Array.prototype.slice.call(arguments, 2), true);
+  };
+  window.clearTimeout = function(id) {
+    if (!cancelTimer(id)) originalClearTimeout(id);
+  };
+  window.clearInterval = function(id) {
+    if (!cancelTimer(id)) originalClearInterval(id);
+  };
+
   window.__HF_VIRTUAL_TIME__ = {
     originalSetTimeout: originalSetTimeout,
     originalClearTimeout: originalClearTimeout,
@@ -439,8 +501,10 @@ ${seededRandomBlock}
     originalCancelAnimationFrame: originalCancelAnimationFrame,
     seekToTime: function(nextTimeMs) {
       var safeTimeMs = Math.max(0, Number(nextTimeMs) || 0);
+      if (window.__renderReady === true) rendering = true;
+      ${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
       virtualNowMs = safeTimeMs;
-      ${seekToTimeReseedCall}flushAnimationFrame();
+      flushAnimationFrame();
       return virtualNowMs;
     },
     getTime: function() {
@@ -887,7 +951,7 @@ function chunkGopFrames(framesInChunk, intervalFrames) {
 import {
   copyFileSync,
   cpSync,
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdirSync,
   rmSync,
   symlinkSync,
@@ -907,7 +971,9 @@ import {
   relative as nodeRelative,
   isAbsolute as nodeIsAbsolute
 } from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
 var DEFAULT_RENDERS_DIR = process.env.PRODUCER_RENDERS_DIR ?? // fileURLToPath (not URL.pathname): on Windows .pathname is "/D:/..." which
 // resolves to a bogus renders dir.
 nodeResolve(fileURLToPath2(import.meta.url), "../../..", "renders");
@@ -938,6 +1004,13 @@ function formatCaptureFrameName(index, ext) {
 function formatExportFrameName(index, ext) {
   return `frame_${String(index + 1).padStart(6, "0")}.${ext}`;
 }
+function resolveCompositionSrc(projectDir, src) {
+  const rooted = (value) => nodeResolve(projectDir, value.replace(/^(?:\.?[\\/])+/, ""));
+  const decoded = rooted(decodedUrlPath(src));
+  if (!isPathInside2(decoded, projectDir)) return null;
+  const raw = rooted(src);
+  return !existsSync3(decoded) && isPathInside2(raw, projectDir) && existsSync3(raw) ? raw : decoded;
+}
 
 // src/services/render/shared.ts
 var BROWSER_MEDIA_EPSILON = 1e-4;
@@ -1116,7 +1189,7 @@ var materializePathModule = {
   isAbsolute
 };
 var materializeFileSystem = {
-  existsSync: existsSync3,
+  existsSync: existsSync4,
   mkdirSync,
   symlinkSync,
   cpSync,
@@ -1455,11 +1528,80 @@ function createStallClock(now = () => Date.now()) {
 
 // src/services/render/stages/captureStreamingStage.ts
 var DEFAULT_CAPTURE_STALL_MS = 6e4;
+var SESSION_INIT_STALL_MS = 3e5;
+var DE_STALL_POLL_MS = 5e3;
+var STALL_ADVICE = "Chrome stopped answering. If another app is keeping the GPU or CPU busy (a 3D render, a game, another export), let it finish or render one job at a time, then retry.";
 function resolveCaptureStallTimeoutMs() {
   const raw = process.env.HF_DE_STALL_MS ?? process.env.HF_DE_PARALLEL_STALL_MS;
   const parsed = raw ? Number(raw) : Number.NaN;
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CAPTURE_STALL_MS;
 }
+function captureModeLabel(mode) {
+  if (mode === "drawelement") return "drawElement";
+  if (mode === "beginframe") return "BeginFrame";
+  return "screenshot";
+}
+var SequentialCaptureStallError = class extends Error {
+  captureMode;
+  constructor(session, stallTimeoutMs, frameIndex, totalFrames) {
+    const step = session.captureStep ? ` while ${session.captureStep}` : "";
+    super(
+      `[Render] Sequential ${captureModeLabel(session.captureMode)} capture stalled: no frame progress for ${stallTimeoutMs}ms (stuck at frame ${frameIndex}/${totalFrames}${step}). ` + STALL_ADVICE
+    );
+    this.name = "SequentialCaptureStallError";
+    this.captureMode = session.captureMode;
+  }
+};
+function raceAgainstStall(promise, deadlineMs, input, signal) {
+  return new Promise((resolve10, reject) => {
+    const clock = createStallClock();
+    const trip = () => reject(
+      signal?.aborted ? new Error(
+        `[Render] Sequential ${captureModeLabel(input.session.captureMode)} capture aborted while a capture call was in flight (frame ${input.frameIndex}/${input.totalFrames}).`
+      ) : new SequentialCaptureStallError(
+        input.session,
+        input.stallTimeoutMs,
+        input.frameIndex,
+        input.totalFrames
+      )
+    );
+    const deadline = Math.max(0, deadlineMs);
+    let wait = Math.min(deadline, DE_STALL_POLL_MS);
+    let timer;
+    const look = () => {
+      const idle = clock.idle(wait);
+      if (idle >= deadline) return trip();
+      wait = Math.min(deadline - idle, DE_STALL_POLL_MS);
+      timer = setTimeout(look, wait);
+    };
+    timer = setTimeout(look, wait);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve10(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+function createSessionInitBudget(input) {
+  const initStallMs = Math.max(SESSION_INIT_STALL_MS, resolveCaptureStallTimeoutMs());
+  const setup = createStallClock();
+  return (work, stalled) => raceAgainstStall(
+    work,
+    initStallMs - setup.idle(0),
+    {
+      session: stalled,
+      frameIndex: input.frameIndex,
+      totalFrames: input.totalFrames,
+      stallTimeoutMs: initStallMs
+    },
+    input.abortSignal
+  );
+}
 
 // src/services/render/captureCost.ts
 import { fpsToNumber as fpsToNumber4 } from "@hyperframes/core";
@@ -1674,7 +1816,7 @@ var ALLOWED_STRING_DATA_KEYS = /* @__PURE__ */ new Set([
   "stagePhase",
   // Full-fidelity fast-capture fallback trigger — the specific reason
   // drawElement gated off ("filter:blur", "filter:drop-shadow",
-  // "backdrop-filter", "clip-path", "at_risk_timeline", "swiftshader", …).
+  // "backdrop-filter", "clip-path", "at_risk_timeline", "swiftshader", "webgl_unavailable", …).
   // Populated on the `capture_fallback_profile` checkpoint emitted by
   // `fallbackCaptureProfile.ts` when the operator opts into
   // `HF_PROFILE_FALLBACK_CAPTURE=true` so downstream metric consumers can
@@ -1993,17 +2135,17 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/render/stages/compileStage.ts
-import { existsSync as existsSync7, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync8, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join8 } from "node:path";
 import { suggestMatchingPreset } from "@hyperframes/core";
 import { extractStandaloneEntryFromIndex, isTemplateEntry } from "@hyperframes/core/compiler";
 import { readTextFile as readTextFile2 } from "@hyperframes/parsers/asset-resolution";
 
 // src/services/htmlCompiler.ts
-import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
+import { decodedUrlPath as decodedUrlPath2 } from "@hyperframes/parsers/asset-paths";
 import { createHash as createHash4 } from "node:crypto";
-import { createReadStream as createReadStream2, existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync4 } from "fs";
-import { join as join7, dirname as dirname6, resolve as resolve6, basename as basename3, relative as relative2 } from "path";
+import { createReadStream as createReadStream2, existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync4 } from "fs";
+import { join as join7, dirname as dirname6, resolve as resolve6, basename as basename3, relative as relative2, sep as sep2 } from "path";
 import { parseHTML as parseHTML5 } from "linkedom";
 import {
   COMPOSITION_SOURCE_URL,
@@ -2249,7 +2391,7 @@ import {
 
 // src/services/animatedGifPrep.ts
 import { createHash as createHash2 } from "node:crypto";
-import { copyFileSync as copyFileSync2, existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { copyFileSync as copyFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
 import { dirname as dirname4, isAbsolute as isAbsolute2, join as join5, resolve as resolve4 } from "node:path";
 import { parseHTML as parseHTML3 } from "linkedom";
 import { parseAnimatedGifMetadata } from "@hyperframes/core";
@@ -2288,14 +2430,14 @@ function resolveLocalImageSourcePath(src, options) {
   const { basePath } = splitUrlSuffix(trimmed);
   const normalizedBase = normalizeRelPath(basePath);
   const mapped = options.sourceAssets?.get(trimmed) ?? options.sourceAssets?.get(basePath) ?? options.sourceAssets?.get(normalizedBase);
-  if (mapped && existsSync4(mapped)) return mapped;
+  if (mapped && existsSync5(mapped)) return mapped;
   if (isHttpUrl(trimmed)) return null;
   const projectRelative = basePath.startsWith("/") ? basePath.slice(1) : basePath;
   const candidates = [
     isAbsolute2(basePath) ? basePath : resolve4(options.projectDir, projectRelative),
     resolve4(options.downloadDir, normalizedBase)
   ];
-  return candidates.find((candidate) => existsSync4(candidate)) ?? null;
+  return candidates.find((candidate) => existsSync5(candidate)) ?? null;
 }
 function isUsableFile(path) {
   try {
@@ -2406,10 +2548,10 @@ async function runAnimatedGifTranscode(request) {
   throw result.error ?? new Error(`Animated GIF transcode failed (${result.exitCode}): ${result.stderr.slice(-500)}`);
 }
 async function ensurePreparedWebm(input) {
-  if (!existsSync4(dirname4(input.cachePath))) {
+  if (!existsSync5(dirname4(input.cachePath))) {
     mkdirSync2(dirname4(input.cachePath), { recursive: true });
   }
-  if (!existsSync4(dirname4(input.outputPath))) {
+  if (!existsSync5(dirname4(input.outputPath))) {
     mkdirSync2(dirname4(input.outputPath), { recursive: true });
   }
   if (!isUsableFile(input.cachePath)) {
@@ -2884,7 +3026,7 @@ import { createStudioPositionSeekReapplyScript } from "@hyperframes/studio-serve
 import { getPositionEditsRenderScript } from "@hyperframes/core/runtime/position-edits-render";
 
 // src/services/assetMediaType.ts
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import {
   fingerprintElementId,
   isNotMediaPayload,
@@ -2957,7 +3099,7 @@ async function preflightCompositionAssetMediaTypes(input) {
       input.projectDir,
       input.compiledDir
     );
-    if (!existsSync5(resolvedPath)) continue;
+    if (!existsSync6(resolvedPath)) continue;
     byPath.set(resolvedPath, [...byPath.get(resolvedPath) ?? [], reference]);
   }
   const mismatches = [];
@@ -3045,6 +3187,14 @@ Check that each file referenced by data-composition-src contains valid HTML with
     this.problems = problems;
   }
 };
+function normalizeCompositionSrcs(html, projectDir) {
+  return html.replace(/(\bdata-composition-src=)(["'])([^"']*)\2/g, (whole, name, quote, value) => {
+    if (!value.includes("%") && !value.startsWith("/")) return whole;
+    const file = resolveCompositionSrc(projectDir, value);
+    if (file === null) return whole;
+    return `${name}${quote}${relative2(projectDir, file).split(sep2).join("/")}${quote}`;
+  });
+}
 function assertSubCompositionsUsable(html, projectDir, visited = /* @__PURE__ */ new Set()) {
   const { document: document2 } = parseHTML5(html);
   const hosts = [...document2.querySelectorAll("[data-composition-src]")];
@@ -3053,7 +3203,11 @@ function assertSubCompositionsUsable(html, projectDir, visited = /* @__PURE__ */
     const srcPath = el.getAttribute("data-composition-src");
     if (!srcPath) continue;
     if (isUnresolvedAssetPlaceholder(srcPath)) continue;
-    const filePath = resolve6(projectDir, srcPath);
+    const filePath = resolveCompositionSrc(projectDir, srcPath);
+    if (filePath === null) {
+      problems.push({ srcPath, detail: "it is outside the project folder" });
+      continue;
+    }
     if (visited.has(filePath)) continue;
     const read = readProjectFile(filePath);
     if (read.kind === "missing") {
@@ -3199,7 +3353,7 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   let filePath = src;
   if (isHttpUrl(src)) {
     const remoteDir = join7(downloadDir, REMOTE_MEDIA_SUBDIR);
-    if (!existsSync6(remoteDir)) mkdirSync4(remoteDir, { recursive: true });
+    if (!existsSync7(remoteDir)) mkdirSync4(remoteDir, { recursive: true });
     try {
       filePath = await downloadToTemp(src, remoteDir, void 0, void 0, void 0, {
         onTelemetry: logRemoteDownloadTelemetry
@@ -3208,11 +3362,11 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
       return { duration: null, resolvedPath: src };
     }
   } else {
-    filePath = decodedUrlPath(src);
+    filePath = decodedUrlPath2(src);
     if (!filePath.startsWith("/")) filePath = join7(baseDir, filePath);
     filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!isHttpUrl(filePath) && !existsSync6(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync7(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -3353,7 +3507,8 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
   for (const el of compEls) {
     const srcPath = el.getAttribute("data-composition-src");
     if (!srcPath) continue;
-    const filePath = resolve6(projectDir, srcPath);
+    const filePath = resolveCompositionSrc(projectDir, srcPath);
+    if (filePath === null) continue;
     if (visited.has(filePath)) {
       continue;
     }
@@ -3361,7 +3516,7 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
     if (read.kind !== "file") {
       continue;
     }
-    const rawSubHtml = read.text;
+    const rawSubHtml = normalizeCompositionSrcs(read.text, projectDir);
     const nestedVisited = new Set(visited);
     nestedVisited.add(filePath);
     workItems.push({ srcPath, filePath, rawSubHtml, nestedVisited });
@@ -3549,8 +3704,9 @@ function inlineSubCompositions(html, subCompositions, projectDir, variableOverri
       resolveHtml: (srcPath) => {
         let compHtml = subCompositions.get(srcPath) || null;
         if (!compHtml) {
-          const read = readProjectFile(resolve6(projectDir, srcPath));
-          if (read.kind === "file") {
+          const filePath = resolveCompositionSrc(projectDir, srcPath);
+          const read = filePath ? readProjectFile(filePath) : null;
+          if (read?.kind === "file") {
             compHtml = rewriteUnresolvableGsapToCdn(read.text, projectDir, srcPath);
           }
         }
@@ -3559,7 +3715,7 @@ function inlineSubCompositions(html, subCompositions, projectDir, variableOverri
       parseHtml: (htmlStr) => parseHTML5(htmlStr).document,
       // Mirrors the preview bundler: a sub-composition's SIBLING assets resolve
       // against its own directory, project-root refs stay as authored.
-      assetExists: (path) => existsSync6(resolve6(projectDir, path)),
+      assetExists: (path) => existsSync7(resolve6(projectDir, path)),
       // Preserve the authored root wrapper as a child of the host, matching
       // the preview bundler's shape (htmlBundler.ts's prepareFlattenedInnerRoot,
       // which the runtime compositionLoader mirrors with its own copy for the
@@ -3750,7 +3906,7 @@ function collectExternalAssets(html, projectDir) {
     if (isPathInside2(absPath, absProjectDir)) {
       return null;
     }
-    if (!existsSync6(absPath)) return null;
+    if (!existsSync7(absPath)) return null;
     const safeKey = toExternalAssetKey(absPath);
     externalAssets.set(safeKey, absPath);
     return safeKey;
@@ -3800,7 +3956,7 @@ var REMOTE_SOURCE_TAG_RE = /<source\b[^>]*?\bsrc\s*=\s*["'](https?:\/\/[^"']+)["
 var REMOTE_IMG_TAG_RE = /<img\b[^>]*?(?<![\w-])src\s*=\s*["'](https?:\/\/[^"']+)["'][^>]*>/gi;
 async function downloadAndRewriteUrls(urlSet, html, remoteDir, warnLabel, logLabel, extraRewrite) {
   if (urlSet.size === 0) return { html, remoteMediaAssets: /* @__PURE__ */ new Map() };
-  if (!existsSync6(remoteDir)) mkdirSync4(remoteDir, { recursive: true });
+  if (!existsSync7(remoteDir)) mkdirSync4(remoteDir, { recursive: true });
   const urlToLocal = /* @__PURE__ */ new Map();
   await Promise.all(
     [...urlSet].map(async (url) => {
@@ -3982,14 +4138,14 @@ function projectStylesheetFontFamilies(html, projectDir) {
   for (const [tag] of html.matchAll(/<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi)) {
     const href = /\bhref=["']([^"']+)["']/i.exec(tag)?.[1];
     if (!href || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href)) continue;
-    const sheet = resolve6(projectDir, decodedUrlPath(href).replace(/^(?:\.?\/)+/, ""));
-    if (!isPathInside2(sheet, projectDir) || !existsSync6(sheet)) continue;
+    const sheet = resolve6(projectDir, decodedUrlPath2(href).replace(/^(?:\.?\/)+/, ""));
+    if (!isPathInside2(sheet, projectDir) || !existsSync7(sheet)) continue;
     for (const face of extractFontFaceBlocks(readFileSync4(sheet, "utf8"))) {
       const family = /font-family\s*:\s*([^;}]+)/i.exec(face)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
       const shipsFile = [...face.matchAll(LOCAL_FONTFACE_URL_RE)].some(([, url = ""]) => {
-        const path = decodedUrlPath(url);
+        const path = decodedUrlPath2(url);
         const file = path.startsWith("/") ? resolve6(projectDir, `.${path}`) : resolve6(dirname6(sheet), path);
-        return isPathInside2(file, projectDir) && existsSync6(file);
+        return isPathInside2(file, projectDir) && existsSync7(file);
       });
       if (family && shipsFile) families.push(family);
     }
@@ -4124,7 +4280,7 @@ function renderGsapDist() {
 }
 function rewriteUnresolvableGsapToCdn(html, projectDir, compSrcPath) {
   let gsapDist;
-  const exists = (path) => existsSync6(resolve6(projectDir, path));
+  const exists = (path) => existsSync7(resolve6(projectDir, path));
   return html.replace(
     /(<script\b[^>]*\bsrc=["'])([^"']*gsap[^"']*\/dist\/([^"']+))(["'][^>]*>)/gi,
     (full, prefix, src, file, suffix) => {
@@ -4141,7 +4297,7 @@ function rebaseDirectEntryAssetPaths(html, projectDir, htmlPath) {
   const entryPath = relative2(projectDir, htmlPath).replace(/\\/g, "/");
   if (!entryPath.includes("/")) return html;
   const { document: document2 } = parseHTML5(html);
-  const assetExists = (path) => existsSync6(resolve6(projectDir, path));
+  const assetExists = (path) => existsSync7(resolve6(projectDir, path));
   rewriteAssetPaths(
     document2.querySelectorAll("[src], [href], [srcset]"),
     entryPath,
@@ -4163,7 +4319,10 @@ function rebaseDirectEntryAssetPaths(html, projectDir, htmlPath) {
 }
 async function compileForRender(projectDir, htmlPath, downloadDir, options = {}) {
   const entryHtml = rebaseDirectEntryAssetPaths(readTextFile(htmlPath), projectDir, htmlPath);
-  const rawHtml = rewriteUnresolvableGsapToCdn(entryHtml, projectDir);
+  const rawHtml = normalizeCompositionSrcs(
+    rewriteUnresolvableGsapToCdn(entryHtml, projectDir),
+    projectDir
+  );
   assertSubCompositionsUsable(rawHtml, projectDir);
   const probes = /* @__PURE__ */ new Map();
   const { html: compiledHtml, unresolvedCompositions } = await compileHtmlFile(
@@ -4708,7 +4867,7 @@ function resolveEntryHtmlPath(input) {
   const rawEntry = readTextFile2(htmlPath);
   if (entryFile === "index.html" || !isTemplateEntry(rawEntry)) return htmlPath;
   const projectIndexPath = join8(projectDir, "index.html");
-  if (!existsSync7(projectIndexPath)) {
+  if (!existsSync8(projectIndexPath)) {
     throw new Error(
       `Template entry file "${entryFile}" requires a project index.html to extract its render shell.`
     );
@@ -5574,7 +5733,7 @@ function validateDistributedDuration(input) {
 }
 
 // src/services/render/stages/extractVideosStage.ts
-import { existsSync as existsSync8 } from "node:fs";
+import { existsSync as existsSync9 } from "node:fs";
 import { join as join10 } from "node:path";
 import {
   classifyVideoExtractionError,
@@ -5849,7 +6008,7 @@ async function runExtractVideosStage(input) {
     const probeFailures = await Promise.all(
       composition.videos.map(async (v) => {
         const videoPath = resolveProjectRelativeSrc3(v.src, projectDir, compiledDir);
-        if (!existsSync8(videoPath)) return null;
+        if (!existsSync9(videoPath)) return null;
         try {
           const attempted = extractionPolicy.maxTransientRetries === 0 ? { result: await extractMediaMetadata3(videoPath), retries: 0 } : await runVideoExtractionWithRetry2(() => extractMediaMetadata3(videoPath), {
             signal: abortSignal,
@@ -5887,7 +6046,7 @@ async function runExtractVideosStage(input) {
     const probed = await Promise.all(
       composition.images.map(async (img) => {
         const imgPath = resolveProjectRelativeSrc3(img.src, projectDir, compiledDir);
-        if (!existsSync8(imgPath)) return null;
+        if (!existsSync9(imgPath)) return null;
         const colorSpace = await probeColorSpaceSafely(imgPath, log);
         if (isHdrColorSpace2(colorSpace)) {
           nativeHdrImageIds.add(img.id);
@@ -6007,7 +6166,7 @@ async function appendVideoAudioFromProbe(input) {
     videos.map(async (video) => {
       const path = isHttpUrl2(video.src) ? video.src : resolveProjectRelativeSrc3(video.src, projectDir, compiledDir);
       const readFrom = urlByAbsentLocalPath?.get(path) ?? path;
-      if (!isHttpUrl2(readFrom) && !existsSync8(readFrom)) return null;
+      if (!isHttpUrl2(readFrom) && !existsSync9(readFrom)) return null;
       const metadata = await extractMediaMetadata3(readFrom);
       const window2 = await resolveFinalFrameExtractionWindow2(
         readFrom,
@@ -6035,7 +6194,7 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/render/stages/audioStage.ts
-import { existsSync as existsSync10 } from "node:fs";
+import { existsSync as existsSync11 } from "node:fs";
 import { join as join13 } from "node:path";
 import {
   MIXED_AUDIO_FILENAME,
@@ -6046,7 +6205,7 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/render/audioDeliveryLimit.ts
-import { existsSync as existsSync9 } from "node:fs";
+import { existsSync as existsSync10 } from "node:fs";
 import { dirname as dirname8, join as join12 } from "node:path";
 import {
   applyAudioFxChain,
@@ -6555,7 +6714,7 @@ async function limitDeliveryPeaks(input, deps = {
   applyChain: applyAudioFxChain,
   encode: encodeAac2,
   rename: renameWithRetry6,
-  sourceExists: existsSync9
+  sourceExists: existsSync10
 }) {
   const { audioPath, sourcePath, signal, timeoutMs } = input;
   if (!deps.sourceExists(sourcePath)) return { success: true };
@@ -6650,7 +6809,7 @@ async function runAudioStageScoped(input) {
       );
       audioLoweredDb = guard.loweredDb;
       input.log?.info("[audio] phases", { ...result.audioPhaseMs, guard: Date.now() - guardStart });
-      if (input.keepDeliverySource && !guard.sourceStale && existsSync10(pcmSourcePath)) {
+      if (input.keepDeliverySource && !guard.sourceStale && existsSync11(pcmSourcePath)) {
         deliverySourcePath = pcmSourcePath;
       }
     }
@@ -6778,7 +6937,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
 }
 
 // src/services/render/stages/captureStage.ts
-import { existsSync as existsSync11, readdirSync, statfsSync } from "node:fs";
+import { existsSync as existsSync12, readdirSync, statfsSync } from "node:fs";
 import { join as join14 } from "node:path";
 import {
   classifyCaptureFailure as classifyCaptureFailure2,
@@ -6830,7 +6989,7 @@ function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis, remed
 }
 function measureCaptureFrameBytes(workDir, framesDir) {
   let total = sampleDirectoryBytes(framesDir);
-  if (!existsSync11(workDir)) return total;
+  if (!existsSync12(workDir)) return total;
   for (const attempt of readdirSync(workDir)) {
     if (/^retry-\d+-batch-\d+-worker-\d+$/.test(attempt)) {
       total += sampleDirectoryBytes(join14(workDir, attempt));
@@ -7015,7 +7174,11 @@ async function runSequentialDiskCapture(input, captureOptions, captureCfg, check
         prepareCaptureSessionForReuse3(session, framesDir, videoInjector);
         probeSession = null;
       }
-      await ensureSessionReady(session);
+      await ensureSessionReady(session, {
+        frameIndex: resumeFrom,
+        totalFrames,
+        abortSignal: input.abortSignal
+      });
       assertAttemptActive();
       lastBrowserConsole = session.browserConsoleBuffer;
       await captureSessionFrames(session, {
@@ -7067,13 +7230,13 @@ function planTransientResume(error, ctx) {
   if (!firstMissing) return null;
   return isTransientCaptureRetryEligible(failure.kind, missing, ctx.retriesUsed) ? firstMissing.startFrame : null;
 }
-async function ensureSessionReady(session) {
+async function ensureSessionReady(session, budget) {
   if (!session.isInitialized) {
     await initializeSession5(session);
     return;
   }
   if (process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true") {
-    await completeDeferredDrawElementInit3(session);
+    await createSessionInitBudget(budget)(completeDeferredDrawElementInit3(session), session);
   }
 }
 async function captureSessionFrames(session, { input, rangeStart, rangeEnd, resumeFrom, checkDiskProjection }) {
@@ -7167,7 +7330,7 @@ import {
 // src/services/render/stages/encodeStage.ts
 import {
   copyFileSync as copyFileSync4,
-  existsSync as existsSync12,
+  existsSync as existsSync13,
   mkdirSync as mkdirSync5,
   readdirSync as readdirSync2,
   readFileSync as readFileSync5,
@@ -7301,7 +7464,7 @@ async function encodeGifFromDir(framesDir, framePattern, outputPath, input) {
       const failure = await reencodeWithClearedWholeFrames(argsInput, run, startTime);
       if (failure) return failure;
     }
-    const fileSize = existsSync12(outputPath) ? statSync4(outputPath).size : 0;
+    const fileSize = existsSync13(outputPath) ? statSync4(outputPath).size : 0;
     return {
       success: true,
       outputPath,
@@ -7462,7 +7625,7 @@ async function runEncodeStage(input) {
   const stage5Start = Date.now();
   if (isPngSequence) {
     const encoded = startEncodeProgress(job, "Writing PNG sequence", onProgress);
-    if (!existsSync12(outputPath)) mkdirSync5(outputPath, { recursive: true });
+    if (!existsSync13(outputPath)) mkdirSync5(outputPath, { recursive: true });
     const captured = readdirSync2(framesDir).filter((name) => name.endsWith(".png")).sort();
     if (captured.length === 0) {
       throw new Error(
@@ -7473,7 +7636,7 @@ async function runEncodeStage(input) {
       const dst = join15(outputPath, formatExportFrameName(i, "png"));
       copyFileSync4(join15(framesDir, name), dst);
     });
-    if (hasAudio && audioOutputPath && existsSync12(audioOutputPath)) {
+    if (hasAudio && audioOutputPath && existsSync13(audioOutputPath)) {
       copyFileSync4(audioOutputPath, join15(outputPath, MIXED_AUDIO_FILENAME2));
       log.info(
         `[Render] png-sequence: ${MIXED_AUDIO_FILENAME2} sidecar written to ${outputPath}/${MIXED_AUDIO_FILENAME2}`
@@ -7636,7 +7799,7 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   let rangeStart = null;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join16(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    const missing = !existsSync13(framePath) || statSync5(framePath).size <= 8;
+    const missing = !existsSync14(framePath) || statSync5(framePath).size <= 8;
     if (missing && rangeStart === null) {
       rangeStart = frameIndex;
     } else if (!missing && rangeStart !== null) {
@@ -7726,7 +7889,7 @@ function countCapturedFrames(totalFrames, framesDir, frameExt) {
   let captured = 0;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join16(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    if (existsSync13(framePath)) captured++;
+    if (existsSync14(framePath)) captured++;
   }
   return captured;
 }
@@ -7953,7 +8116,7 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/distributed/chunkFrames.ts
-import { existsSync as existsSync15, readdirSync as readdirSync4 } from "node:fs";
+import { existsSync as existsSync16, readdirSync as readdirSync4 } from "node:fs";
 import { extname as extname2, join as join18 } from "node:path";
 import {
   compositionRequiresWebGpu as compositionRequiresWebGpu3,
@@ -7963,7 +8126,7 @@ import {
 // src/services/distributed/shared.ts
 import { execFile as execFileCallback } from "node:child_process";
 import { dirname as dirname11, join as join17 } from "node:path";
-import { existsSync as existsSync14, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync15, readFileSync as readFileSync6 } from "node:fs";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { promisify as promisify2 } from "node:util";
 import {
@@ -7979,7 +8142,7 @@ function isPlanAudioArtifactPath(path) {
 function resolvePlanAudioPath(planDir) {
   for (const name of [PLAN_AUDIO_RELATIVE_PATH, PLAN_AUDIO_LEGACY_RELATIVE_PATH]) {
     const candidate = join17(planDir, name);
-    if (existsSync14(candidate)) return candidate;
+    if (existsSync15(candidate)) return candidate;
   }
   return null;
 }
@@ -8240,7 +8403,7 @@ function readProducerVersion() {
   let current = startDir;
   for (let i = 0; i < 10; i++) {
     const candidate = join17(current, "package.json");
-    if (existsSync14(candidate)) {
+    if (existsSync15(candidate)) {
       try {
         const pkg = JSON.parse(readFileSync6(candidate, "utf-8"));
         if (pkg.name === "@hyperframes/producer" && typeof pkg.version === "string") {
@@ -8294,7 +8457,7 @@ function rebuildExtractedFramesFromPlanDir(planDir, videos, indexMode = "dense-v
   const result = [];
   for (const v of videos) {
     const outputDir = join18(planDir, "video-frames", v.videoId);
-    if (!existsSync15(outputDir)) {
+    if (!existsSync16(outputDir)) {
       throw new Error(
         `[renderChunk] planDir missing extracted video frames for ${JSON.stringify(v.videoId)}: ${outputDir} not present. plan() should have written frames here; the planDir is malformed.`
       );
@@ -8393,7 +8556,7 @@ async function extractDeferredVideoFramesForChunk(input) {
       const range = planned.get(video.videoId).deferredRange;
       const remoteUrl = remoteSources[range.sourcePath];
       const sourcePath = remoteUrl ?? join18(input.planDir, ...range.sourcePath.split("/"));
-      if (remoteUrl === void 0 && !existsSync15(sourcePath)) {
+      if (remoteUrl === void 0 && !existsSync16(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -8593,7 +8756,7 @@ async function readPlanReferenceBackground(input) {
 }
 
 // src/services/render/stages/freezePlan.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync7, readFileSync as readFileSync7, readdirSync as readdirSync5, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync7, readFileSync as readFileSync7, readdirSync as readdirSync5, writeFileSync as writeFileSync6 } from "node:fs";
 import { join as join21, relative as relative3, resolve as resolve8 } from "node:path";
 import {
   REFERENCE_BACKGROUND_FIELD,
@@ -8787,7 +8950,7 @@ function planFileSha256(absolutePath, digests) {
   return sha256;
 }
 async function prehashPlanFiles(dir, digests) {
-  if (!existsSync16(dir)) return;
+  if (!existsSync17(dir)) return;
   for (const { absolutePath } of listPlanFiles(dir)) {
     if (!digests.has(absolutePath)) digests.set(absolutePath, await sha256FileAsync(absolutePath));
   }
@@ -8857,15 +9020,15 @@ function writePlanRemoteFiles(planDir, files) {
 }
 function readPlanRemoteFiles(planDir) {
   const path = join21(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
-  return existsSync16(path) ? JSON.parse(readFileSync7(path, "utf-8")) : [];
+  return existsSync17(path) ? JSON.parse(readFileSync7(path, "utf-8")) : [];
 }
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join21(planDir, "plan.json");
   const encoderJsonPath = join21(planDir, "meta", "encoder.json");
-  if (!existsSync16(planJsonPath)) {
+  if (!existsSync17(planJsonPath)) {
     throw new Error(`[freezePlan] plan.json missing: ${planJsonPath}`);
   }
-  if (!existsSync16(encoderJsonPath)) {
+  if (!existsSync17(encoderJsonPath)) {
     throw new Error(`[freezePlan] meta/encoder.json missing: ${encoderJsonPath}`);
   }
   const planJson = JSON.parse(readFileSync7(planJsonPath, "utf-8"));
@@ -8895,11 +9058,11 @@ async function freezePlan(input) {
     hasAudio,
     digests
   } = input;
-  if (!existsSync16(planDir)) {
+  if (!existsSync17(planDir)) {
     throw new Error(`[freezePlan] planDir does not exist: ${planDir}`);
   }
   const metaDir = join21(planDir, "meta");
-  if (!existsSync16(metaDir)) mkdirSync7(metaDir, { recursive: true });
+  if (!existsSync17(metaDir)) mkdirSync7(metaDir, { recursive: true });
   writeFileSync6(
     join21(metaDir, "composition.json"),
     `${JSON.stringify(composition, null, 2)}
@@ -8976,7 +9139,7 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
 }
 
 // src/services/distributed/chunkAudio.ts
-import { closeSync as closeSync4, existsSync as existsSync17, ftruncateSync, mkdirSync as mkdirSync9, openSync as openSync4, readFileSync as readFileSync8 } from "node:fs";
+import { closeSync as closeSync4, existsSync as existsSync18, ftruncateSync, mkdirSync as mkdirSync9, openSync as openSync4, readFileSync as readFileSync8 } from "node:fs";
 import { writeFileSync as writeFileSync7, writeSync } from "node:fs";
 import { join as join23 } from "node:path";
 import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure4, runFfmpeg as runFfmpeg7 } from "@hyperframes/engine";
@@ -9467,7 +9630,7 @@ async function writeChunkAudioSlices(input) {
 }
 function chunkAudioSource(planDir, chunkIndex, scratchPath) {
   const layoutPath = join23(planDir, SLICE_LAYOUT);
-  if (!existsSync17(layoutPath)) return resolvePlanAudioPath(planDir);
+  if (!existsSync18(layoutPath)) return resolvePlanAudioPath(planDir);
   const layout = JSON.parse(readFileSync8(layoutPath, "utf-8"));
   const frame = readFileSync8(join23(planDir, SLICE_FRAME));
   const fd = openSync4(scratchPath, "w");
@@ -9840,7 +10003,7 @@ function assertPlanSizeWithinLimit(input) {
   });
   throw new PlanTooLargeError(breakdown.totalBytes, input.limitBytes, breakdown, input.observedAt);
 }
-function resolveChunkPlan(totalFrames, configChunkSize, maxParallelChunks, targetChunkFrames) {
+function resolveChunkPlan(totalFrames, configChunkSize, maxParallelChunks, targetChunkFrames, minParallelChunks = 1) {
   assertPositiveInteger("totalFrames", totalFrames);
   assertPositiveInteger("maxParallelChunks", maxParallelChunks);
   if (configChunkSize !== void 0) {
@@ -9849,7 +10012,11 @@ function resolveChunkPlan(totalFrames, configChunkSize, maxParallelChunks, targe
   if (targetChunkFrames !== void 0) {
     assertPositiveInteger("targetChunkFrames", targetChunkFrames);
   }
-  const autoSizeParallel = targetChunkFrames === void 0 ? maxParallelChunks : Math.min(maxParallelChunks, Math.max(1, Math.ceil(totalFrames / targetChunkFrames)));
+  assertPositiveInteger("minParallelChunks", minParallelChunks);
+  const autoSizeParallel = targetChunkFrames === void 0 ? maxParallelChunks : Math.min(
+    maxParallelChunks,
+    Math.max(minParallelChunks, Math.ceil(totalFrames / targetChunkFrames))
+  );
   const resolvedChunkSize = configChunkSize ?? Math.max(MIN_CHUNK_SIZE, Math.ceil(totalFrames / autoSizeParallel));
   const naiveCount = Math.ceil(totalFrames / resolvedChunkSize);
   const chunkCount = Math.min(maxParallelChunks, Math.max(1, naiveCount));
@@ -10017,7 +10184,7 @@ function pathInside(root, path) {
 function stableSourcePath(roots, srcPath) {
   for (const [root, prefix] of roots) {
     const rel = pathInside(root, srcPath);
-    if (rel !== null) return [prefix, ...rel.split(sep2)].filter(Boolean).join("/");
+    if (rel !== null) return [prefix, ...rel.split(sep3)].filter(Boolean).join("/");
   }
   return srcPath;
 }
@@ -10031,8 +10198,8 @@ function createVideoSourceShipper(input) {
     let result = null;
     for (const root of stagedRel === null ? [input.workCompiledDir, input.projectDir] : []) {
       const rel = pathInside(root, srcPath);
-      if (rel !== null && (existsSync18(join25(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
-        result = ["compiled", ...rel.split(sep2)].join("/");
+      if (rel !== null && (existsSync19(join25(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
+        result = ["compiled", ...rel.split(sep3)].join("/");
         break;
       }
     }
@@ -10059,7 +10226,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     useGpu: false,
     browserGpuMode: "software"
   });
-  if (!existsSync18(planDir)) mkdirSync10(planDir, { recursive: true });
+  if (!existsSync19(planDir)) mkdirSync10(planDir, { recursive: true });
   const log = config.logger ?? defaultLogger;
   const sizeLimitBytes = options.executionPlanSizeLimitBytes ?? config.planDirSizeLimitBytes ?? PLAN_DIR_SIZE_LIMIT_BYTES;
   const abortSignal = config.abortSignal;
@@ -10089,7 +10256,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   });
   const entryFile = config.entryFile ?? "index.html";
   const htmlPath = join25(projectDir, entryFile);
-  if (!existsSync18(htmlPath)) {
+  if (!existsSync19(htmlPath)) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
   const workDir = join25(planDir, ".plan-work");
@@ -10104,7 +10271,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     filter: (src) => {
       const rel = relative5(projectDir, src);
       if (rel === "" || rel.startsWith("..")) return true;
-      const firstSegment = rel.split(sep2, 1)[0];
+      const firstSegment = rel.split(sep3, 1)[0];
       return firstSegment === void 0 || !PLAN_PROJECT_DIR_SKIP_SEGMENTS.has(firstSegment);
     }
   });
@@ -10317,15 +10484,15 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "extract", stageStarted);
   const stagedVideoFrames = join25(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join25(planDir, "video-frames");
-  if (existsSync18(videoFramesDst)) rmSync7(videoFramesDst, { recursive: true, force: true });
+  if (existsSync19(videoFramesDst)) rmSync7(videoFramesDst, { recursive: true, force: true });
   const videoSourcesDir = join25(planDir, "video-sources");
   rmSync7(videoSourcesDir, { recursive: true, force: true });
-  if (existsSync18(stagedVideoFrames)) {
+  if (existsSync19(stagedVideoFrames)) {
     renameWithRetry8(stagedVideoFrames, videoFramesDst);
   } else {
     mkdirSync10(videoFramesDst, { recursive: true });
   }
-  if (existsSync18(finalCompiledDir)) rmSync7(finalCompiledDir, { recursive: true, force: true });
+  if (existsSync19(finalCompiledDir)) rmSync7(finalCompiledDir, { recursive: true, force: true });
   renameWithRetry8(compiledDir, finalCompiledDir);
   const shipVideoSource = createVideoSourceShipper({
     planDir,
@@ -10428,7 +10595,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     totalFrames,
     config.chunkSize,
     maxParallel,
-    config.targetChunkFrames
+    config.targetChunkFrames,
+    config.minParallelChunks
   );
   const chunks = buildPlanChunkSlices(
     frameWeights,
@@ -10445,10 +10613,10 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);
   }
   const planAudioPath = join25(planDir, PLAN_AUDIO_RELATIVE_PATH);
-  if (audioResult?.hasAudio && existsSync18(audioResult.audioOutputPath)) {
+  if (audioResult?.hasAudio && existsSync19(audioResult.audioOutputPath)) {
     renameWithRetry8(audioResult.audioOutputPath, planAudioPath);
   }
-  if (chunksCarryAudio && existsSync18(planAudioPath)) {
+  if (chunksCarryAudio && existsSync19(planAudioPath)) {
     if (options.sliceChunkAudio) {
       stageStarted = Date.now();
       await writeChunkAudioSlices({
@@ -10561,7 +10729,7 @@ async function buildPlanAudio(projectDir, config, workRoot, outputPath, options
     if (mixed.audioError) {
       applyDistributedAudioWarningPolicy(c.job, mixed.audioError, mixed.audioFailures, c.log);
     }
-    if (!mixed.hasAudio || !existsSync18(mixed.audioOutputPath)) return { hasAudio: false };
+    if (!mixed.hasAudio || !existsSync19(mixed.audioOutputPath)) return { hasAudio: false };
     renameWithRetry8(mixed.audioOutputPath, outputPath);
     return { hasAudio: true };
   } finally {
@@ -10576,7 +10744,7 @@ import {
 } from "@hyperframes/engine";
 import {
   copyFileSync as copyFileSync8,
-  existsSync as existsSync20,
+  existsSync as existsSync21,
   lstatSync as lstatSync2,
   mkdirSync as mkdirSync12,
   mkdtempSync as mkdtempSync4,
@@ -10587,14 +10755,14 @@ import {
   writeFileSync as writeFileSync10
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname as dirname14, isAbsolute as isAbsolute4, join as join28, relative as relative6, resolve as resolve9, sep as sep3 } from "node:path";
+import { dirname as dirname14, isAbsolute as isAbsolute4, join as join28, relative as relative6, resolve as resolve9, sep as sep4 } from "node:path";
 import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
 import { createFrameLookupTable as createFrameLookupTable5, renameWithRetry as renameWithRetry10 } from "@hyperframes/engine";
 
 // src/services/distributed/planV2Publisher.ts
 import {
   copyFileSync as copyFileSync7,
-  existsSync as existsSync19,
+  existsSync as existsSync20,
   linkSync as linkSync2,
   mkdirSync as mkdirSync11,
   mkdtempSync as mkdtempSync3,
@@ -10663,7 +10831,7 @@ var LocalPlanV2ArtifactPublisher = class {
   #linkFile;
   #committed = false;
   constructor(destinationDir, options = {}) {
-    if (existsSync19(destinationDir)) {
+    if (existsSync20(destinationDir)) {
       throw new PlanV2IntegrityError(`output directory already exists: ${destinationDir}`);
     }
     this.destinationDir = destinationDir;
@@ -10680,7 +10848,7 @@ var LocalPlanV2ArtifactPublisher = class {
       );
     }
     const destinationPath = planV2BlobPath(this.temporaryDir, digest);
-    if (existsSync19(destinationPath)) return;
+    if (existsSync20(destinationPath)) return;
     mkdirSync11(dirname13(destinationPath), { recursive: true });
     const stagingDir = mkdtempSync3(join27(dirname13(destinationPath), ".plan-v2-blob-"));
     const temporaryPath = join27(stagingDir, "blob");
@@ -10698,7 +10866,7 @@ var LocalPlanV2ArtifactPublisher = class {
   }
   async commitManifest(manifestBytes) {
     for (const digest of new Set(manifestDigests(manifestBytes))) {
-      if (!existsSync19(planV2BlobPath(this.temporaryDir, digest))) {
+      if (!existsSync20(planV2BlobPath(this.temporaryDir, digest))) {
         throw new PlanV2IntegrityError(
           `cannot commit manifest before referenced blob is durable: ${digest}`
         );
@@ -10754,7 +10922,7 @@ function listFiles(root) {
         walk(absolutePath);
       } else if (entry.isFile()) {
         files.push({
-          path: relative6(rootResolved, absolutePath).split(sep3).join("/"),
+          path: relative6(rootResolved, absolutePath).split(sep4).join("/"),
           absolutePath
         });
       } else {
@@ -10777,7 +10945,7 @@ function assertValidExtractionCacheCompleteSentinel(path) {
 }
 function validateExtractionCacheCompleteSentinels(executionPlanDir) {
   const videoRoot = join28(executionPlanDir, "video-frames");
-  if (!existsSync20(videoRoot)) return;
+  if (!existsSync21(videoRoot)) return;
   for (const videoEntry of readdirSync7(videoRoot, { withFileTypes: true })) {
     if (!videoEntry.isDirectory()) continue;
     const videoDir = join28(videoRoot, videoEntry.name);
@@ -10794,7 +10962,7 @@ function isExtractionCacheCompleteSentinelPath(path) {
 function resolveExtractedVideoOutputDir(planDir, videoId) {
   const videoRoot = resolve9(planDir, "video-frames");
   const outputDir = resolve9(videoRoot, videoId);
-  if (outputDir === videoRoot || !outputDir.startsWith(`${videoRoot}${sep3}`)) {
+  if (outputDir === videoRoot || !outputDir.startsWith(`${videoRoot}${sep4}`)) {
     throw new PlanV2IntegrityError(`unsafe extracted video id: ${JSON.stringify(videoId)}`);
   }
   return outputDir;
@@ -10878,7 +11046,7 @@ function parsePlanVideosJson2(value) {
 }
 function materializeExtractedVideoDirectories(planDir) {
   const videosPath = join28(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync20(videosPath)) return;
+  if (!existsSync21(videosPath)) return;
   const videos = parsePlanVideosJson2(readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH));
   for (const video of videos.extracted) {
     mkdirSync12(resolveExtractedVideoOutputDir(planDir, video.videoId), { recursive: true });
@@ -10912,9 +11080,9 @@ function parseChunkSlices(value) {
 }
 function buildVideoChunkDependencies(executionPlanDir, dimensions) {
   const videoRoot = join28(executionPlanDir, "video-frames");
-  const hasExtractedFrames = existsSync20(videoRoot) && listFiles(videoRoot).length > 0;
+  const hasExtractedFrames = existsSync21(videoRoot) && listFiles(videoRoot).length > 0;
   const videosPath = join28(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync20(videosPath)) {
+  if (!existsSync21(videosPath)) {
     return hasExtractedFrames ? { mode: "full-source-pack", dependencies: null } : { mode: "exact-rendered-frames", dependencies: /* @__PURE__ */ new Map() };
   }
   const chunksPath = join28(executionPlanDir, "meta", "chunks.json");
@@ -10954,7 +11122,7 @@ function collectChunkVideoDependencies(input) {
     for (let frame = chunk.startFrame; frame < chunk.endFrame; frame++) {
       const globalTime = frame * input.fpsDen / input.fpsNum;
       for (const [videoId, payload] of input.table.getActiveFramePayloads(globalTime)) {
-        const path = input.deferredSources.get(videoId) ?? relative6(resolve9(input.executionPlanDir), payload.framePath).split(sep3).join("/");
+        const path = input.deferredSources.get(videoId) ?? relative6(resolve9(input.executionPlanDir), payload.framePath).split(sep4).join("/");
         assertSafeRelativePath(path);
         const indexes = mutable.get(path) ?? /* @__PURE__ */ new Set();
         indexes.add(chunk.index);
@@ -10971,7 +11139,7 @@ function computeManifestHash(manifest) {
   return sha256Hex(`${PLAN_V2_HASH_PREFIX}${canonicalJsonStringify(manifestPayload(manifest))}`);
 }
 function writeBlob(sourcePath, destinationPath) {
-  if (existsSync20(destinationPath)) return;
+  if (existsSync21(destinationPath)) return;
   mkdirSync12(dirname14(destinationPath), { recursive: true });
   const temporaryDir = mkdtempSync4(join28(dirname14(destinationPath), ".plan-v2-blob-"));
   const temporaryPath = join28(temporaryDir, "blob");
@@ -11011,7 +11179,7 @@ async function putTasks(tasks) {
 }
 function buildPlanV2Publication(executionPlanDir, digests) {
   const executionPlanPath = join28(executionPlanDir, "plan.json");
-  if (!existsSync20(executionPlanPath)) {
+  if (!existsSync21(executionPlanPath)) {
     throw new PlanV2IntegrityError(`execution plan is missing plan.json: ${executionPlanPath}`);
   }
   const executionPlanValue = readJsonFile(executionPlanPath, "execution plan.json");
@@ -11091,7 +11259,7 @@ function buildPlanV2Publication(executionPlanDir, digests) {
   };
 }
 function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
-  if (existsSync20(planV2Dir)) {
+  if (existsSync21(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publication = buildPlanV2Publication(executionPlanDir);
@@ -11177,7 +11345,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
   }
 }
 async function planV2(projectDir, config, planV2Dir) {
-  if (existsSync20(planV2Dir)) {
+  if (existsSync21(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publisher = new LocalPlanV2ArtifactPublisher(planV2Dir);
@@ -11331,7 +11499,7 @@ function parsePlanV2Manifest(value) {
 }
 function readPlanV2Manifest(planV2Dir) {
   const manifestPath = join28(planV2Dir, "plan.json");
-  if (!existsSync20(manifestPath)) {
+  if (!existsSync21(manifestPath)) {
     throw new PlanV2IntegrityError(`missing v2 manifest: ${manifestPath}`);
   }
   const value = readJsonFile(manifestPath, "v2 manifest");
@@ -11350,7 +11518,7 @@ function listPlanV2ArtifactsForTarget(manifest, target) {
 }
 function verifyBlob(planV2Dir, artifact) {
   const sourcePath = planV2BlobPath(planV2Dir, artifact.sha256);
-  if (!existsSync20(sourcePath)) {
+  if (!existsSync21(sourcePath)) {
     throw new PlanV2IntegrityError(`missing content-addressed artifact ${artifact.sha256}`);
   }
   const stats = statSync7(sourcePath);
@@ -11363,7 +11531,7 @@ function verifyBlob(planV2Dir, artifact) {
   return sourcePath;
 }
 function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
-  if (existsSync20(destinationDir)) {
+  if (existsSync21(destinationDir)) {
     throw new PlanV2IntegrityError(`materialization destination already exists: ${destinationDir}`);
   }
   const manifest = readPlanV2Manifest(planV2Dir);
@@ -11428,7 +11596,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
 }
 function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   const markerPath = join28(planDir, PLAN_V2_MATERIALIZATION_MARKER);
-  if (!existsSync20(markerPath)) return null;
+  if (!existsSync21(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
   if (!isRecord3(marker) || !isRecord3(marker.manifest) || !isRecord3(marker.target)) {
     throw new PlanV2IntegrityError("malformed materialization marker");
@@ -11446,7 +11614,7 @@ function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   for (const artifact of required) {
     if (Object.hasOwn(remoteSources, artifact.path)) continue;
     const path = join28(planDir, ...artifact.path.split("/"));
-    if (!existsSync20(path) || statSync7(path).size !== artifact.sizeBytes) {
+    if (!existsSync21(path) || statSync7(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
         `materialized artifact missing or truncated: ${artifact.path}`
       );
@@ -11470,7 +11638,7 @@ import {
 } from "@hyperframes/engine";
 import {
   cpSync as cpSync3,
-  existsSync as existsSync21,
+  existsSync as existsSync22,
   mkdirSync as mkdirSync13,
   mkdtempSync as mkdtempSync5,
   readFileSync as readFileSync10,
@@ -11525,7 +11693,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   }
   const format = plan.dimensions.format;
   const cfrEncoder = cfr ? readCfrEncoder(planDir, format) : null;
-  if (!existsSync21(dirname15(outputPath))) {
+  if (!existsSync22(dirname15(outputPath))) {
     mkdirSync13(dirname15(outputPath), { recursive: true });
   }
   const workDir = mkdtempSync5(`${outputPath}.assemble-work-`);
@@ -11549,7 +11717,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   try {
     const videoSources = cfrEncoder ? [await reencodeCfr(ctx, chunkPaths, cfrEncoder)] : chunkPaths;
     const finalPath = join29(workDir, `output.${format}`);
-    const audio = audioPath !== null && existsSync21(audioPath) ? audioPath : null;
+    const audio = audioPath !== null && existsSync22(audioPath) ? audioPath : null;
     await writeJoined(ctx, videoSources, audio, finalPath);
     renameWithRetry11(finalPath, outputPath);
     log.info("[assemble] stage timings", {
@@ -11567,7 +11735,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
       });
     }
   }
-  const fileSize = existsSync21(outputPath) ? statSync8(outputPath).size : 0;
+  const fileSize = existsSync22(outputPath) ? statSync8(outputPath).size : 0;
   return {
     ...referenceBackgroundResult6(plan[REFERENCE_BACKGROUND_FIELD4]),
     outputPath,
@@ -11579,13 +11747,13 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
 function readAssemblePlan(planDir, chunkPaths) {
   const planJsonPath = join29(planDir, "plan.json");
   const chunksJsonPath = join29(planDir, "meta", "chunks.json");
-  if (!existsSync21(planJsonPath)) {
+  if (!existsSync22(planJsonPath)) {
     throw new Error(`[assemble] planDir missing plan.json: ${planJsonPath}`);
   }
   const plan = JSON.parse(readFileSync10(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan, DISTRIBUTED_RENDER_CAPABILITIES.roles.assembler);
   validatePlanV2MaterializedTarget(planDir, { role: "assembler" });
-  if (!existsSync21(chunksJsonPath)) {
+  if (!existsSync22(chunksJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/chunks.json: ${chunksJsonPath}`);
   }
   const chunks = JSON.parse(readFileSync10(chunksJsonPath, "utf-8"));
@@ -11600,7 +11768,7 @@ function readAssemblePlan(planDir, chunkPaths) {
     }
   }
   for (const path of chunkPaths.flat()) {
-    if (!existsSync21(path)) {
+    if (!existsSync22(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
   }
@@ -11739,7 +11907,7 @@ function planFormat(planDir) {
 }
 function lockedAudio(planDir) {
   const encoderJsonPath = join29(planDir, "meta", "encoder.json");
-  if (!existsSync21(encoderJsonPath)) return {};
+  if (!existsSync22(encoderJsonPath)) return {};
   return JSON.parse(readFileSync10(encoderJsonPath, "utf-8"));
 }
 function readCfrEncoder(planDir, format) {
@@ -11749,7 +11917,7 @@ function readCfrEncoder(planDir, format) {
     );
   }
   const encoderJsonPath = join29(planDir, "meta", "encoder.json");
-  if (!existsSync21(encoderJsonPath)) {
+  if (!existsSync22(encoderJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
   }
   const encoderJson = JSON.parse(readFileSync10(encoderJsonPath, "utf-8"));
@@ -11761,7 +11929,7 @@ function readCfrEncoder(planDir, format) {
   return encoderJson;
 }
 function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, startTimeMs) {
-  if (existsSync21(outputPath)) rmSync10(outputPath, { recursive: true, force: true });
+  if (existsSync22(outputPath)) rmSync10(outputPath, { recursive: true, force: true });
   mkdirSync13(outputPath, { recursive: true });
   let globalIdx = 0;
   for (const chunkDir of chunkPaths) {
@@ -11785,7 +11953,7 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
       `[assemble] png-sequence frame count mismatch: merged ${globalIdx} frames vs plan.totalFrames=${totalFrames}. Using on-disk count.`
     );
   }
-  if (audioPath !== null && existsSync21(audioPath)) {
+  if (audioPath !== null && existsSync22(audioPath)) {
     const sidecar = join29(outputPath, MIXED_AUDIO_FILENAME4);
     cpSync3(audioPath, sidecar);
   }
@@ -11806,7 +11974,7 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
 
 // src/services/distributed/renderChunk.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync22, mkdirSync as mkdirSync14, readFileSync as readFileSync11, readdirSync as readdirSync9, rmSync as rmSync11, writeFileSync as writeFileSync12 } from "node:fs";
+import { existsSync as existsSync23, mkdirSync as mkdirSync14, readFileSync as readFileSync11, readdirSync as readdirSync9, rmSync as rmSync11, writeFileSync as writeFileSync12 } from "node:fs";
 import { cpus } from "node:os";
 import { join as join30 } from "node:path";
 import {
@@ -11912,12 +12080,23 @@ async function runCaptureWithScreenshotFallback(input) {
   try {
     return await input.run(input.forceScreenshot);
   } catch (error) {
-    if (input.forceScreenshot || await input.canRetry?.() === false) throw error;
-    if (!shouldRetryChunkCaptureWithScreenshot(error)) throw error;
+    if (input.forceScreenshot || await input.canRetry?.() === false)
+      throw imageMissingIn(error) ?? error;
+    if (!shouldRetryChunkCaptureWithScreenshot(error)) throw imageMissingIn(error) ?? error;
     input.onFallback?.(error);
     await input.resetForScreenshotRetry();
-    return await input.run(true);
+    return await input.run(true).catch((retryError) => {
+      throw imageMissingIn(retryError) ?? retryError;
+    });
+  }
+}
+function imageMissingIn(error) {
+  let e = error;
+  for (let depth = 0; depth < 5 && typeof e === "object" && e !== null; depth++) {
+    if (e.name === "ImageMissingFromFrameError") return e;
+    e = e.cause;
   }
+  return void 0;
 }
 async function beginFrameSessionNeedsScreenshotFallback(session, probe = probeBeginFrameLiveness2) {
   if (session.launchCaptureMode !== "beginframe") return false;
@@ -11952,7 +12131,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const planJsonPath = join30(planDir, "plan.json");
   const encoderJsonPath = join30(planDir, "meta", "encoder.json");
   const chunksJsonPath = join30(planDir, "meta", "chunks.json");
-  if (!existsSync22(planJsonPath)) {
+  if (!existsSync23(planJsonPath)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir is missing required artifact: ${planJsonPath}`
@@ -11968,7 +12147,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const v2Manifest = v2Materialization?.manifest ?? null;
   const remoteSources = v2Materialization?.remoteSources ?? {};
   for (const required of [encoderJsonPath, chunksJsonPath]) {
-    if (!existsSync22(required)) {
+    if (!existsSync23(required)) {
       throw new RenderChunkValidationError(
         MISSING_PLAN_ARTIFACT,
         `[renderChunk] planDir is missing required artifact: ${required}`
@@ -11979,7 +12158,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const chunks = JSON.parse(readFileSync11(chunksJsonPath, "utf-8"));
   const videosJsonPath = join30(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   let planVideos = null;
-  if (existsSync22(videosJsonPath)) {
+  if (existsSync23(videosJsonPath)) {
     try {
       planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync11(videosJsonPath, "utf-8")));
     } catch (err) {
@@ -12010,7 +12189,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const range = resolveChunkFrameRange(slice, chunkIndex, options?.frameRange);
   const framesInChunk = range.endFrame - range.startFrame;
   const compiledDir = join30(planDir, "compiled");
-  if (!existsSync22(compiledDir)) {
+  if (!existsSync23(compiledDir)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir missing compiled/ directory: ${compiledDir}`
@@ -12260,10 +12439,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       const effectiveBitrate = encoder.crf != null ? void 0 : encoder.bitrate;
       const videoOnlyPath = encoder.chunksCarryAudio ? `${outputChunkPath}.video.mp4` : outputChunkPath;
       if (isPngSequence) {
-        if (!existsSync22(outputChunkPath)) mkdirSync14(outputChunkPath, { recursive: true });
+        if (!existsSync23(outputChunkPath)) mkdirSync14(outputChunkPath, { recursive: true });
       } else {
         const outDir = join30(outputChunkPath, "..");
-        if (!existsSync22(outDir)) mkdirSync14(outDir, { recursive: true });
+        if (!existsSync23(outDir)) mkdirSync14(outDir, { recursive: true });
       }
       const encodeInput = {
         job,
@@ -12693,6 +12872,20 @@ function validateDistributedRenderConfig(config) {
       );
     }
   }
+  if (config.minParallelChunks !== void 0) {
+    if (!Number.isInteger(config.minParallelChunks) || config.minParallelChunks < 1) {
+      throw new InvalidConfigError(
+        "config.minParallelChunks",
+        `must be a positive integer; got ${config.minParallelChunks}`
+      );
+    }
+    if (config.minParallelChunks > MAX_PARALLEL_CHUNKS_CEILING) {
+      throw new InvalidConfigError(
+        "config.minParallelChunks",
+        `must be <= ${MAX_PARALLEL_CHUNKS_CEILING}; got ${config.minParallelChunks}`
+      );
+    }
+  }
   for (const field of ["workerTimeoutSeconds", "workerConcurrency"]) {
     const value = config[field];
     if (value !== void 0 && (!Number.isInteger(value) || value < 1)) {