@hyperframes/producer 0.9.19 → 0.9.21

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 // src/services/renderOrchestrator.ts
 import { audioFailureDiagnostics as audioFailureDiagnostics2 } from "@hyperframes/engine";
 import {
-  existsSync as existsSync20,
+  existsSync as existsSync21,
   mkdirSync as mkdirSync12,
   readdirSync as readdirSync6,
   rmSync as rmSync12,
@@ -410,6 +410,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,
@@ -419,8 +481,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() {
@@ -918,7 +982,7 @@ function resolveDeliveryEncoderOptions(config) {
 import {
   copyFileSync,
   cpSync,
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdirSync,
   rmSync,
   symlinkSync,
@@ -938,7 +1002,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");
@@ -976,6 +1042,13 @@ function resolveRenderPaths(projectDir, outputPath, rendersDir = DEFAULT_RENDERS
   const absoluteOutputPath = nodeResolve(resolvedOutputPath);
   return { absoluteProjectDir, absoluteOutputPath };
 }
+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;
@@ -1179,7 +1252,7 @@ var materializePathModule = {
   isAbsolute
 };
 var materializeFileSystem = {
-  existsSync: existsSync3,
+  existsSync: existsSync4,
   mkdirSync,
   symlinkSync,
   cpSync,
@@ -1481,7 +1554,7 @@ var RenderExecutionContext = class {
 };
 
 // src/services/render/artifactTransaction.ts
-import { closeSync as closeSync2, existsSync as existsSync5, fstatSync as fstatSync2, openSync as openSync2, readSync, readdirSync as readdirSync2, rmSync as rmSync3 } from "node:fs";
+import { closeSync as closeSync2, existsSync as existsSync6, fstatSync as fstatSync2, openSync as openSync2, readSync, readdirSync as readdirSync2, rmSync as rmSync3 } from "node:fs";
 import { basename as basename3, dirname as dirname4, extname as extname2, join as join5, resolve as resolve4 } from "node:path";
 import { HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, renameWithRetry } from "@hyperframes/engine";
 
@@ -1494,7 +1567,7 @@ import {
 
 // src/services/render/renderDirOwner.ts
 import {
-  existsSync as existsSync4,
+  existsSync as existsSync5,
   lstatSync,
   mkdtempSync,
   readFileSync as readFileSync2,
@@ -1570,7 +1643,7 @@ function newestWriteMs(path) {
 }
 function isAbandoned(dir, ownerlessIdleMs, now) {
   try {
-    if (!lstatSync(dir).isDirectory() || existsSync4(join4(dir, TRANSACTION_BACKUP))) return false;
+    if (!lstatSync(dir).isDirectory() || existsSync5(join4(dir, TRANSACTION_BACKUP))) return false;
     const owner = ownerState(dir);
     if (owner === "gone") return true;
     return owner === "none" && ownerlessIdleMs !== void 0 && now - newestWriteMs(dir) >= ownerlessIdleMs;
@@ -1602,7 +1675,7 @@ function createRenderWorkDir(prefix, outputDir) {
 
 // src/services/render/artifactTransaction.ts
 var defaultFileSystem = {
-  existsSync: existsSync5,
+  existsSync: existsSync6,
   renameSync: (source, destination) => renameWithRetry(source, destination),
   rmSync: rmSync3
 };
@@ -1756,7 +1829,7 @@ var ArtifactTransaction = class {
   async assertDirectoryExpectation(expected, files) {
     for (const required of expected.requiredFiles ?? []) {
       const path = join5(this.stagingPath, required);
-      if (!existsSync5(path)) {
+      if (!existsSync6(path)) {
         throw new Error(`Render artifact directory is missing ${required}: ${this.stagingPath}`);
       }
       assertReadableNonEmptyFile(path);
@@ -2005,7 +2078,7 @@ function replanAfterFailure(plan2, failure) {
 }
 
 // src/services/render/stages/captureSegmentedStage.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, rmSync as rmSync6, statSync as statSync3 } from "node:fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, rmSync as rmSync6, statSync as statSync3 } from "node:fs";
 import { join as join10 } from "node:path";
 import {
   captureFrameToBuffer as captureFrameToBuffer2,
@@ -2302,6 +2375,19 @@ function aggregateBeginFrameReuse(perfs) {
   if (noDamageFrames + hasDamageFrames === 0) return void 0;
   return { noDamageFrames, hasDamageFrames };
 }
+function aggregateMotionBlur(perfs) {
+  const ran = perfs.flatMap((p) => p.motionBlur ?? []).filter((m) => m.tier || m.failedFrames > 0);
+  const first = ran[0];
+  if (!first) return void 0;
+  return {
+    tier: first.tier ?? ran.find((m) => m.tier)?.tier ?? null,
+    reasonCode: first.reasonCode,
+    movers: first.movers,
+    failedFrames: ran.reduce((sum2, m) => sum2 + m.failedFrames, 0),
+    readEvents: ran.some((m) => m.readEvents),
+    fingerprint: ran.find((m) => m.fingerprint)?.fingerprint ?? null
+  };
+}
 function buildRenderPerfSummary(input) {
   return {
     renderId: input.job.id,
@@ -2352,6 +2438,7 @@ function buildRenderPerfSummary(input) {
     staticDedup: aggregateDedup(input.dedupPerfs),
     chromeMemory: aggregateChromeMemory(input.dedupPerfs),
     beginFrameReuse: aggregateBeginFrameReuse(input.dedupPerfs),
+    motionBlur: aggregateMotionBlur(input.dedupPerfs),
     drawElement: aggregateDrawElement(
       input.dedupPerfs,
       input.drawElement ?? { selfVerifyFallback: false }
@@ -3826,6 +3913,21 @@ function raceAgainstStall(promise, deadlineMs, input, signal) {
     );
   });
 }
+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
+  );
+}
 function createDrainFrameGuard(args) {
   const { log, stats, frameTime } = args;
   const verifyMinDb = resolveDeVerifyMinDb();
@@ -4298,14 +4400,11 @@ async function runCaptureStreamingStage(input) {
       let resumes = 0;
       for (; ; ) {
         const videoInjector = createRenderVideoFrameInjector();
-        const initStallMs = Math.max(SESSION_INIT_STALL_MS, resolveCaptureStallTimeoutMs());
-        const setup = createStallClock();
-        const withinInitBudget = (work, stalled) => raceAgainstStall(
-          work,
-          initStallMs - setup.idle(0),
-          { session: stalled, frameIndex: resume.from, totalFrames, stallTimeoutMs: initStallMs },
+        const withinInitBudget = createSessionInitBudget({
+          frameIndex: resume.from,
+          totalFrames,
           abortSignal
-        );
+        });
         const openSession = async () => {
           const opening = createCaptureSession(
             fileServer.url,
@@ -4583,7 +4682,7 @@ async function captureSegmentToEncoder(ctx, segment) {
       path: segmentPath,
       // Recorded so resume can prove the file on disk is the one that
       // finished; absent only in unit tests, whose fake encoder writes none.
-      bytes: existsSync6(segmentPath) ? statSync3(segmentPath).size : 0
+      bytes: existsSync7(segmentPath) ? statSync3(segmentPath).size : 0
     });
     return encodeResult;
   } finally {
@@ -4613,14 +4712,29 @@ function defaultSessionFactory(input) {
         });
         probeSession = null;
       }
-      const session = probeSession ?? await openSegmentedSession(input, injector);
+      const withinInitBudget = createSessionInitBudget({
+        frameIndex: input.job.framesRendered ?? 0,
+        totalFrames: input.totalFrames,
+        abortSignal: input.abortSignal
+      });
+      const openSession = async () => {
+        const opening = openSegmentedSession(input, injector);
+        try {
+          return await withinInitBudget(opening, OPENING_CAPTURE_SESSION);
+        } catch (error) {
+          void opening.then(closeCaptureSession2, () => {
+          });
+          throw error;
+        }
+      };
+      const session = probeSession ?? await openSession();
       if (probeSession) {
         openSegmentedSessionReuse(input, probeSession, injector);
         probeSession = null;
       }
       try {
-        if (!session.isInitialized) await initializeSession2(session);
-        await completeDeferredDrawElementInit2(session);
+        if (!session.isInitialized) await withinInitBudget(initializeSession2(session), session);
+        await withinInitBudget(completeDeferredDrawElementInit2(session), session);
       } catch (error) {
         await closeCaptureSession2(session).catch(() => {
         });
@@ -5552,7 +5666,7 @@ function trackSegmentFramePeak(frames, rootDir, onPeak) {
 
 // src/services/render/segmentManifest.ts
 import { createHash as createHash2 } from "node:crypto";
-import { existsSync as existsSync7, mkdirSync as mkdirSync6, readFileSync as readFileSync4, statSync as statSync5, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync4, statSync as statSync5, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join15 } from "node:path";
 import { renameWithRetry as renameWithRetry2 } from "@hyperframes/engine";
 var MANIFEST_FILENAME = "segments.json";
@@ -5600,7 +5714,7 @@ function isManifest(value) {
 }
 function readSegmentManifest(segmentDir) {
   const path = join15(segmentDir, MANIFEST_FILENAME);
-  if (!existsSync7(path)) return null;
+  if (!existsSync8(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync4(path, "utf-8"));
     return isManifest(parsed) ? parsed : null;
@@ -5629,7 +5743,7 @@ async function validateCompletedSegments(manifest, expectedHash, probeFrames) {
   const ok = /* @__PURE__ */ new Set();
   if (manifest.planHash !== expectedHash) return ok;
   for (const entry of manifest.completed) {
-    if (!existsSync7(entry.path)) continue;
+    if (!existsSync8(entry.path)) continue;
     const size = statSync5(entry.path).size;
     if (size <= 0 || size !== entry.bytes) continue;
     const frames = await probeFrames(entry.path);
@@ -5769,7 +5883,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
@@ -6208,17 +6322,17 @@ function countAuthoredTimedClips(html) {
 }
 
 // src/services/render/stages/compileStage.ts
-import { existsSync as existsSync11, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync12, writeFileSync as writeFileSync5 } from "node:fs";
 import { join as join19 } 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 createHash6 } from "node:crypto";
-import { createReadStream as createReadStream2, existsSync as existsSync10, mkdirSync as mkdirSync9, readFileSync as readFileSync7 } from "fs";
-import { join as join18, dirname as dirname8, resolve as resolve7, basename as basename4, relative as relative2 } from "path";
+import { createReadStream as createReadStream2, existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync7 } from "fs";
+import { join as join18, dirname as dirname8, resolve as resolve7, basename as basename4, relative as relative2, sep as sep2 } from "path";
 import { parseHTML as parseHTML5 } from "linkedom";
 import {
   COMPOSITION_SOURCE_URL,
@@ -6464,7 +6578,7 @@ import {
 
 // src/services/animatedGifPrep.ts
 import { createHash as createHash4 } from "node:crypto";
-import { copyFileSync as copyFileSync2, existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync5, rmSync as rmSync9, statSync as statSync6 } from "node:fs";
+import { copyFileSync as copyFileSync2, existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync5, rmSync as rmSync9, statSync as statSync6 } from "node:fs";
 import { dirname as dirname6, isAbsolute as isAbsolute2, join as join16, resolve as resolve5 } from "node:path";
 import { parseHTML as parseHTML3 } from "linkedom";
 import { parseAnimatedGifMetadata } from "@hyperframes/core";
@@ -6503,14 +6617,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 && existsSync8(mapped)) return mapped;
+  if (mapped && existsSync9(mapped)) return mapped;
   if (isHttpUrl(trimmed)) return null;
   const projectRelative = basePath.startsWith("/") ? basePath.slice(1) : basePath;
   const candidates = [
     isAbsolute2(basePath) ? basePath : resolve5(options.projectDir, projectRelative),
     resolve5(options.downloadDir, normalizedBase)
   ];
-  return candidates.find((candidate) => existsSync8(candidate)) ?? null;
+  return candidates.find((candidate) => existsSync9(candidate)) ?? null;
 }
 function isUsableFile(path) {
   try {
@@ -6621,10 +6735,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 (!existsSync8(dirname6(input.cachePath))) {
+  if (!existsSync9(dirname6(input.cachePath))) {
     mkdirSync7(dirname6(input.cachePath), { recursive: true });
   }
-  if (!existsSync8(dirname6(input.outputPath))) {
+  if (!existsSync9(dirname6(input.outputPath))) {
     mkdirSync7(dirname6(input.outputPath), { recursive: true });
   }
   if (!isUsableFile(input.cachePath)) {
@@ -7099,7 +7213,7 @@ import { createStudioPositionSeekReapplyScript } from "@hyperframes/studio-serve
 import { getPositionEditsRenderScript } from "@hyperframes/core/runtime/position-edits-render";
 
 // src/services/assetMediaType.ts
-import { existsSync as existsSync9 } from "node:fs";
+import { existsSync as existsSync10 } from "node:fs";
 import {
   fingerprintElementId,
   isNotMediaPayload,
@@ -7172,7 +7286,7 @@ async function preflightCompositionAssetMediaTypes(input) {
       input.projectDir,
       input.compiledDir
     );
-    if (!existsSync9(resolvedPath)) continue;
+    if (!existsSync10(resolvedPath)) continue;
     byPath.set(resolvedPath, [...byPath.get(resolvedPath) ?? [], reference]);
   }
   const mismatches = [];
@@ -7260,6 +7374,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]")];
@@ -7268,7 +7390,11 @@ function assertSubCompositionsUsable(html, projectDir, visited = /* @__PURE__ */
     const srcPath = el.getAttribute("data-composition-src");
     if (!srcPath) continue;
     if (isUnresolvedAssetPlaceholder(srcPath)) continue;
-    const filePath = resolve7(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") {
@@ -7414,7 +7540,7 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   let filePath = src;
   if (isHttpUrl(src)) {
     const remoteDir = join18(downloadDir, REMOTE_MEDIA_SUBDIR);
-    if (!existsSync10(remoteDir)) mkdirSync9(remoteDir, { recursive: true });
+    if (!existsSync11(remoteDir)) mkdirSync9(remoteDir, { recursive: true });
     try {
       filePath = await downloadToTemp(src, remoteDir, void 0, void 0, void 0, {
         onTelemetry: logRemoteDownloadTelemetry
@@ -7423,11 +7549,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 = join18(baseDir, filePath);
     filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!isHttpUrl(filePath) && !existsSync10(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync11(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -7568,7 +7694,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 = resolve7(projectDir, srcPath);
+    const filePath = resolveCompositionSrc(projectDir, srcPath);
+    if (filePath === null) continue;
     if (visited.has(filePath)) {
       continue;
     }
@@ -7576,7 +7703,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 });
@@ -7764,8 +7891,9 @@ function inlineSubCompositions(html, subCompositions, projectDir, variableOverri
       resolveHtml: (srcPath) => {
         let compHtml = subCompositions.get(srcPath) || null;
         if (!compHtml) {
-          const read = readProjectFile(resolve7(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);
           }
         }
@@ -7774,7 +7902,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) => existsSync10(resolve7(projectDir, path)),
+      assetExists: (path) => existsSync11(resolve7(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
@@ -7965,7 +8093,7 @@ function collectExternalAssets(html, projectDir) {
     if (isPathInside2(absPath, absProjectDir)) {
       return null;
     }
-    if (!existsSync10(absPath)) return null;
+    if (!existsSync11(absPath)) return null;
     const safeKey = toExternalAssetKey(absPath);
     externalAssets.set(safeKey, absPath);
     return safeKey;
@@ -8015,7 +8143,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 (!existsSync10(remoteDir)) mkdirSync9(remoteDir, { recursive: true });
+  if (!existsSync11(remoteDir)) mkdirSync9(remoteDir, { recursive: true });
   const urlToLocal = /* @__PURE__ */ new Map();
   await Promise.all(
     [...urlSet].map(async (url) => {
@@ -8197,14 +8325,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 = resolve7(projectDir, decodedUrlPath(href).replace(/^(?:\.?\/)+/, ""));
-    if (!isPathInside2(sheet, projectDir) || !existsSync10(sheet)) continue;
+    const sheet = resolve7(projectDir, decodedUrlPath2(href).replace(/^(?:\.?\/)+/, ""));
+    if (!isPathInside2(sheet, projectDir) || !existsSync11(sheet)) continue;
     for (const face of extractFontFaceBlocks(readFileSync7(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("/") ? resolve7(projectDir, `.${path}`) : resolve7(dirname8(sheet), path);
-        return isPathInside2(file, projectDir) && existsSync10(file);
+        return isPathInside2(file, projectDir) && existsSync11(file);
       });
       if (family && shipsFile) families.push(family);
     }
@@ -8342,7 +8470,7 @@ function renderGsapDist() {
 }
 function rewriteUnresolvableGsapToCdn(html, projectDir, compSrcPath) {
   let gsapDist;
-  const exists = (path) => existsSync10(resolve7(projectDir, path));
+  const exists = (path) => existsSync11(resolve7(projectDir, path));
   return html.replace(
     /(<script\b[^>]*\bsrc=["'])([^"']*gsap[^"']*\/dist\/([^"']+))(["'][^>]*>)/gi,
     (full, prefix, src, file, suffix) => {
@@ -8359,7 +8487,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) => existsSync10(resolve7(projectDir, path));
+  const assetExists = (path) => existsSync11(resolve7(projectDir, path));
   rewriteAssetPaths(
     document2.querySelectorAll("[src], [href], [srcset]"),
     entryPath,
@@ -8381,7 +8509,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(
@@ -8926,7 +9057,7 @@ function resolveEntryHtmlPath(input) {
   const rawEntry = readTextFile2(htmlPath);
   if (entryFile === "index.html" || !isTemplateEntry(rawEntry)) return htmlPath;
   const projectIndexPath = join19(projectDir, "index.html");
-  if (!existsSync11(projectIndexPath)) {
+  if (!existsSync12(projectIndexPath)) {
     throw new Error(
       `Template entry file "${entryFile}" requires a project index.html to extract its render shell.`
     );
@@ -9792,7 +9923,7 @@ function validateDistributedDuration(input) {
 }
 
 // src/services/render/stages/extractVideosStage.ts
-import { existsSync as existsSync12 } from "node:fs";
+import { existsSync as existsSync13 } from "node:fs";
 import { join as join21 } from "node:path";
 import {
   classifyVideoExtractionError,
@@ -10067,7 +10198,7 @@ async function runExtractVideosStage(input) {
     const probeFailures = await Promise.all(
       composition.videos.map(async (v) => {
         const videoPath = resolveProjectRelativeSrc3(v.src, projectDir, compiledDir);
-        if (!existsSync12(videoPath)) return null;
+        if (!existsSync13(videoPath)) return null;
         try {
           const attempted = extractionPolicy.maxTransientRetries === 0 ? { result: await extractMediaMetadata3(videoPath), retries: 0 } : await runVideoExtractionWithRetry2(() => extractMediaMetadata3(videoPath), {
             signal: abortSignal,
@@ -10105,7 +10236,7 @@ async function runExtractVideosStage(input) {
     const probed = await Promise.all(
       composition.images.map(async (img) => {
         const imgPath = resolveProjectRelativeSrc3(img.src, projectDir, compiledDir);
-        if (!existsSync12(imgPath)) return null;
+        if (!existsSync13(imgPath)) return null;
         const colorSpace = await probeColorSpaceSafely(imgPath, log);
         if (isHdrColorSpace2(colorSpace)) {
           nativeHdrImageIds.add(img.id);
@@ -10225,7 +10356,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) && !existsSync12(readFrom)) return null;
+      if (!isHttpUrl2(readFrom) && !existsSync13(readFrom)) return null;
       const metadata = await extractMediaMetadata3(readFrom);
       const window2 = await resolveFinalFrameExtractionWindow2(
         readFrom,
@@ -10245,7 +10376,7 @@ async function appendVideoAudioFromProbe(input) {
 }
 
 // src/services/render/videoLayerPassthroughPlan.ts
-import { existsSync as existsSync13 } from "node:fs";
+import { existsSync as existsSync14 } from "node:fs";
 import {
   buildVideoLayerInput,
   isHttpUrl as isHttpUrl3,
@@ -10313,7 +10444,7 @@ async function planVideoLayerPassthrough(input) {
   const { video } = q;
   if (isHttpUrl3(video.src)) return { reason: "remote_source" };
   const path = resolveProjectRelativeSrc4(video.src, input.projectDir, input.compiledDir);
-  if (!existsSync13(path)) return { reason: "source_missing" };
+  if (!existsSync14(path)) return { reason: "source_missing" };
   const layout = await probeVideoLayout(input.page, video.id, input.canvas, input.duration);
   if ("reason" in layout) return layout;
   const layer = await buildVideoLayerInput(
@@ -10328,7 +10459,7 @@ async function planVideoLayerPassthrough(input) {
 }
 
 // src/services/render/stages/audioStage.ts
-import { existsSync as existsSync15 } from "node:fs";
+import { existsSync as existsSync16 } from "node:fs";
 import { join as join24 } from "node:path";
 import {
   MIXED_AUDIO_FILENAME,
@@ -10339,7 +10470,7 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/render/audioDeliveryLimit.ts
-import { existsSync as existsSync14 } from "node:fs";
+import { existsSync as existsSync15 } from "node:fs";
 import { dirname as dirname10, join as join23 } from "node:path";
 import {
   applyAudioFxChain,
@@ -10848,7 +10979,7 @@ async function limitDeliveryPeaks(input, deps = {
   applyChain: applyAudioFxChain,
   encode: encodeAac2,
   rename: renameWithRetry6,
-  sourceExists: existsSync14
+  sourceExists: existsSync15
 }) {
   const { audioPath, sourcePath, signal, timeoutMs } = input;
   if (!deps.sourceExists(sourcePath)) return { success: true };
@@ -10943,7 +11074,7 @@ async function runAudioStageScoped(input) {
       );
       audioLoweredDb = guard.loweredDb;
       input.log?.info("[audio] phases", { ...result.audioPhaseMs, guard: Date.now() - guardStart });
-      if (input.keepDeliverySource && !guard.sourceStale && existsSync15(pcmSourcePath)) {
+      if (input.keepDeliverySource && !guard.sourceStale && existsSync16(pcmSourcePath)) {
         deliverySourcePath = pcmSourcePath;
       }
     }
@@ -11071,7 +11202,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
 }
 
 // src/services/render/stages/captureStage.ts
-import { existsSync as existsSync16, readdirSync as readdirSync4, statfsSync as statfsSync2 } from "node:fs";
+import { existsSync as existsSync17, readdirSync as readdirSync4, statfsSync as statfsSync2 } from "node:fs";
 import { join as join25 } from "node:path";
 import {
   classifyCaptureFailure as classifyCaptureFailure2,
@@ -11142,7 +11273,7 @@ function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis, remed
 }
 function measureCaptureFrameBytes(workDir, framesDir) {
   let total = sampleDirectoryBytes(framesDir);
-  if (!existsSync16(workDir)) return total;
+  if (!existsSync17(workDir)) return total;
   for (const attempt of readdirSync4(workDir)) {
     if (/^retry-\d+-batch-\d+-worker-\d+$/.test(attempt)) {
       total += sampleDirectoryBytes(join25(workDir, attempt));
@@ -11327,7 +11458,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, {
@@ -11379,13 +11514,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 }) {
@@ -11445,7 +11580,7 @@ async function captureSessionFrames(session, { input, rangeStart, rangeEnd, resu
 }
 
 // src/services/render/stages/captureHdrStage.ts
-import { existsSync as existsSync18, mkdirSync as mkdirSync10 } from "node:fs";
+import { existsSync as existsSync19, mkdirSync as mkdirSync10 } from "node:fs";
 import { join as join29 } from "node:path";
 import {
   closeCaptureSession as closeCaptureSession7,
@@ -11691,7 +11826,7 @@ import { Worker } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
 import { dirname as dirname11, join as join27 } from "node:path";
 import { createRequire } from "node:module";
-import { existsSync as existsSync17 } from "node:fs";
+import { existsSync as existsSync18 } from "node:fs";
 import { cpus as cpus2 } from "node:os";
 function resolveWorkerEntry(explicit) {
   if (explicit && explicit.length > 0) {
@@ -11704,7 +11839,7 @@ function resolveWorkerEntry(explicit) {
   }
   const moduleDir = dirname11(fileURLToPath3(import.meta.url));
   const jsPath = join27(moduleDir, "shaderTransitionWorker.js");
-  if (existsSync17(jsPath)) return { path: jsPath, isTs: false };
+  if (existsSync18(jsPath)) return { path: jsPath, isTs: false };
   const tsPath = join27(moduleDir, "shaderTransitionWorker.ts");
   return { path: tsPath, isTs: true };
 }
@@ -12265,7 +12400,7 @@ async function runCaptureHdrStage(input) {
       }
       const debugDumpEnabled = process.env.KEEP_TEMP === "1";
       const debugDumpDir = debugDumpEnabled ? join29(framesDir, "debug-composite") : null;
-      if (debugDumpDir && !existsSync18(debugDumpDir)) {
+      if (debugDumpDir && !existsSync19(debugDumpDir)) {
         mkdirSync10(debugDumpDir, { recursive: true });
       }
       const compositeTransfer = resolveCompositeTransfer(hasHdrContent, effectiveHdr);
@@ -12422,7 +12557,7 @@ async function runCaptureHdrStage(input) {
 // src/services/render/stages/encodeStage.ts
 import {
   copyFileSync as copyFileSync4,
-  existsSync as existsSync19,
+  existsSync as existsSync20,
   mkdirSync as mkdirSync11,
   readdirSync as readdirSync5,
   readFileSync as readFileSync8,
@@ -12556,7 +12691,7 @@ async function encodeGifFromDir(framesDir, framePattern, outputPath, input) {
       const failure = await reencodeWithClearedWholeFrames(argsInput, run, startTime);
       if (failure) return failure;
     }
-    const fileSize = existsSync19(outputPath) ? statSync8(outputPath).size : 0;
+    const fileSize = existsSync20(outputPath) ? statSync8(outputPath).size : 0;
     return {
       success: true,
       outputPath,
@@ -12717,7 +12852,7 @@ async function runEncodeStage(input) {
   const stage5Start = Date.now();
   if (isPngSequence) {
     const encoded = startEncodeProgress(job, "Writing PNG sequence", onProgress);
-    if (!existsSync19(outputPath)) mkdirSync11(outputPath, { recursive: true });
+    if (!existsSync20(outputPath)) mkdirSync11(outputPath, { recursive: true });
     const captured = readdirSync5(framesDir).filter((name) => name.endsWith(".png")).sort();
     if (captured.length === 0) {
       throw new Error(
@@ -12728,7 +12863,7 @@ async function runEncodeStage(input) {
       const dst = join30(outputPath, formatExportFrameName(i, "png"));
       copyFileSync4(join30(framesDir, name), dst);
     });
-    if (hasAudio && audioOutputPath && existsSync19(audioOutputPath)) {
+    if (hasAudio && audioOutputPath && existsSync20(audioOutputPath)) {
       copyFileSync4(audioOutputPath, join30(outputPath, MIXED_AUDIO_FILENAME2));
       log.info(
         `[Render] png-sequence: ${MIXED_AUDIO_FILENAME2} sidecar written to ${outputPath}/${MIXED_AUDIO_FILENAME2}`
@@ -13117,7 +13252,7 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   let rangeStart = null;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join31(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    const missing = !existsSync20(framePath) || statSync9(framePath).size <= 8;
+    const missing = !existsSync21(framePath) || statSync9(framePath).size <= 8;
     if (missing && rangeStart === null) {
       rangeStart = frameIndex;
     } else if (!missing && rangeStart !== null) {
@@ -13242,7 +13377,7 @@ function countCapturedFrames(totalFrames, framesDir, frameExt) {
   let captured = 0;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join31(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    if (existsSync20(framePath)) captured++;
+    if (existsSync21(framePath)) captured++;
   }
   return captured;
 }
@@ -13907,7 +14042,7 @@ async function executeRenderJob(job, projectDir, outputPath, progressSink, abort
   validateDeliveryEncoderConfig(job.config);
   const debugDir = resolveRenderDebugDir();
   const outputDir = dirname13(outputPath);
-  if (!existsSync20(outputDir)) mkdirSync12(outputDir, { recursive: true });
+  if (!existsSync21(outputDir)) mkdirSync12(outputDir, { recursive: true });
   const workDir = job.config.debug ? join31(debugDir, job.id) : createRenderWorkDir(resolveRenderWorkDirPrefix(outputPath, job.id), outputDir);
   const pipelineStart = Date.now();
   const baseLog = job.config.logger ?? defaultLogger;
@@ -14049,7 +14184,7 @@ async function executeRenderPipeline(input) {
     job.startedAt = /* @__PURE__ */ new Date();
     assertNotAborted();
     assertConfiguredFfmpegBinariesExist();
-    if (!existsSync20(workDir)) mkdirSync12(workDir, { recursive: true });
+    if (!existsSync21(workDir)) mkdirSync12(workDir, { recursive: true });
     if (job.config.debug) {
       log.info("[Render] Debug artifacts enabled", { workDir, logPath });
     }
@@ -14079,7 +14214,7 @@ async function executeRenderPipeline(input) {
     });
     const entryFile = job.config.entryFile || "index.html";
     const htmlPath = join31(projectDir, entryFile);
-    if (!existsSync20(htmlPath)) {
+    if (!existsSync21(htmlPath)) {
       throw new Error(`Entry file not found: ${htmlPath}`);
     }
     assertNotAborted();
@@ -14394,9 +14529,11 @@ async function executeRenderPipeline(input) {
     );
     pendingAudio = audioStage.catch(() => void 0);
     const stage4Start = Date.now();
-    updateJobStatus(job, "rendering", "Starting frame capture", 25, onProgress, {
+    const EFFECT_SCAN_STAGE = "Checking effects";
+    const startingFrameCapture = () => updateJobStatus(job, "rendering", "Starting frame capture", 25, onProgress, {
       code: "start_browsers"
     });
+    startingFrameCapture();
     if (!fileServer) {
       const fileServerStart = observability.stageStart("file_server", { reused: false });
       try {
@@ -14421,7 +14558,7 @@ async function executeRenderPipeline(input) {
       throw new Error("File server failed to initialize before frame capture");
     }
     const framesDir = join31(workDir, "captured-frames");
-    if (!existsSync20(framesDir)) mkdirSync12(framesDir, { recursive: true });
+    if (!existsSync21(framesDir)) mkdirSync12(framesDir, { recursive: true });
     updateJobStatus(job, "rendering", "Checking browser GPU", 25, onProgress, {
       code: "start_browsers"
     });
@@ -14429,6 +14566,7 @@ async function executeRenderPipeline(input) {
       chromePath: resolveHeadlessShellPath(cfg),
       browserTimeout: cfg.browserTimeout
     });
+    startingFrameCapture();
     captureForceScreenshot = applyConcreteGpuScreenshotClamp(
       captureForceScreenshot,
       resolvedBrowserGpuMode,
@@ -14477,10 +14615,13 @@ async function executeRenderPipeline(input) {
       onEffectScanProgress: (scanned, total) => updateJobStatus(
         job,
         "rendering",
-        `Checking effects, ${scanned} of ${total} frames`,
+        `${EFFECT_SCAN_STAGE}, ${scanned} of ${total} frames`,
         25,
         onProgress
       ),
+      onEffectScanEnd: () => {
+        if (job.currentStage.startsWith(EFFECT_SCAN_STAGE)) startingFrameCapture();
+      },
       requiresWebGpu: compositionRequiresWebGpu2(compiled.html),
       // Live route for Chrome memory (spec §5 Phase −1). The aggregate route
       // through CapturePerfSummary only exists on success; a mid-capture
@@ -14748,6 +14889,7 @@ async function executeRenderPipeline(input) {
       } finally {
         calibrationFrames?.release();
       }
+      startingFrameCapture();
       captureCalibration = outcome.calibration;
       calibrationEvaluateTimedOut = outcome.calibrationEvaluateTimedOut;
       captureForceScreenshot = outcome.forceScreenshot;
@@ -15806,7 +15948,7 @@ async function executeRenderPipeline(input) {
       })
     );
     const totalElapsed = Date.now() - pipelineStart;
-    const tmpPeakBytes = existsSync20(workDir) ? sampleDirectoryBytes(workDir) : 0;
+    const tmpPeakBytes = existsSync21(workDir) ? sampleDirectoryBytes(workDir) : 0;
     recordTransientRetryObservability();
     observability.checkpoint("pipeline", "artifact validated", { totalElapsedMs: totalElapsed });
     const observabilitySummary = observability.summary({
@@ -15887,7 +16029,7 @@ async function executeRenderPipeline(input) {
       }
     }
     if (job.config.debug) {
-      if (!isPngSequence && !isHls && existsSync20(stagedOutputPath)) {
+      if (!isPngSequence && !isHls && existsSync21(stagedOutputPath)) {
         const debugOutput = join31(workDir, `output${videoExt}`);
         copyFileSync5(stagedOutputPath, debugOutput);
       }
@@ -16399,13 +16541,13 @@ import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframe
 import {
   copyFileSync as copyFileSync6,
   cpSync as cpSync2,
-  existsSync as existsSync25,
+  existsSync as existsSync26,
   linkSync,
   mkdirSync as mkdirSync16,
   rmSync as rmSync14,
   writeFileSync as writeFileSync10
 } from "node:fs";
-import { extname as extname6, isAbsolute as isAbsolute3, join as join40, relative as relative5, sep as sep2 } from "node:path";
+import { extname as extname6, isAbsolute as isAbsolute3, join as join40, relative as relative5, sep as sep3 } from "node:path";
 import {
   fpsToNumber as fpsToNumber9,
   HF_COLOR_GRADING_ATTR as HF_COLOR_GRADING_ATTR2
@@ -16430,7 +16572,7 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/distributed/chunkFrames.ts
-import { existsSync as existsSync22, readdirSync as readdirSync7 } from "node:fs";
+import { existsSync as existsSync23, readdirSync as readdirSync7 } from "node:fs";
 import { extname as extname4, join as join34 } from "node:path";
 import {
   compositionRequiresWebGpu as compositionRequiresWebGpu3,
@@ -16440,7 +16582,7 @@ import {
 // src/services/distributed/shared.ts
 import { execFile as execFileCallback } from "node:child_process";
 import { dirname as dirname15, join as join33 } from "node:path";
-import { existsSync as existsSync21, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync22, readFileSync as readFileSync9 } from "node:fs";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { promisify as promisify2 } from "node:util";
 import {
@@ -16456,7 +16598,7 @@ function isPlanAudioArtifactPath(path) {
 function resolvePlanAudioPath(planDir) {
   for (const name of [PLAN_AUDIO_RELATIVE_PATH, PLAN_AUDIO_LEGACY_RELATIVE_PATH]) {
     const candidate = join33(planDir, name);
-    if (existsSync21(candidate)) return candidate;
+    if (existsSync22(candidate)) return candidate;
   }
   return null;
 }
@@ -16717,7 +16859,7 @@ function readProducerVersion() {
   let current = startDir;
   for (let i = 0; i < 10; i++) {
     const candidate = join33(current, "package.json");
-    if (existsSync21(candidate)) {
+    if (existsSync22(candidate)) {
       try {
         const pkg = JSON.parse(readFileSync9(candidate, "utf-8"));
         if (pkg.name === "@hyperframes/producer" && typeof pkg.version === "string") {
@@ -16771,7 +16913,7 @@ function rebuildExtractedFramesFromPlanDir(planDir, videos, indexMode = "dense-v
   const result = [];
   for (const v of videos) {
     const outputDir = join34(planDir, "video-frames", v.videoId);
-    if (!existsSync22(outputDir)) {
+    if (!existsSync23(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.`
       );
@@ -16870,7 +17012,7 @@ async function extractDeferredVideoFramesForChunk(input) {
       const range = planned.get(video.videoId).deferredRange;
       const remoteUrl = remoteSources[range.sourcePath];
       const sourcePath = remoteUrl ?? join34(input.planDir, ...range.sourcePath.split("/"));
-      if (remoteUrl === void 0 && !existsSync22(sourcePath)) {
+      if (remoteUrl === void 0 && !existsSync23(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -17070,7 +17212,7 @@ async function readPlanReferenceBackground(input) {
 }
 
 // src/services/render/stages/freezePlan.ts
-import { existsSync as existsSync23, mkdirSync as mkdirSync14, readFileSync as readFileSync10, readdirSync as readdirSync8, writeFileSync as writeFileSync8 } from "node:fs";
+import { existsSync as existsSync24, mkdirSync as mkdirSync14, readFileSync as readFileSync10, readdirSync as readdirSync8, writeFileSync as writeFileSync8 } from "node:fs";
 import { join as join37, relative as relative3, resolve as resolve9 } from "node:path";
 import {
   REFERENCE_BACKGROUND_FIELD,
@@ -17264,7 +17406,7 @@ function planFileSha256(absolutePath, digests) {
   return sha256;
 }
 async function prehashPlanFiles(dir, digests) {
-  if (!existsSync23(dir)) return;
+  if (!existsSync24(dir)) return;
   for (const { absolutePath } of listPlanFiles(dir)) {
     if (!digests.has(absolutePath)) digests.set(absolutePath, await sha256FileAsync(absolutePath));
   }
@@ -17334,15 +17476,15 @@ function writePlanRemoteFiles(planDir, files) {
 }
 function readPlanRemoteFiles(planDir) {
   const path = join37(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
-  return existsSync23(path) ? JSON.parse(readFileSync10(path, "utf-8")) : [];
+  return existsSync24(path) ? JSON.parse(readFileSync10(path, "utf-8")) : [];
 }
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join37(planDir, "plan.json");
   const encoderJsonPath = join37(planDir, "meta", "encoder.json");
-  if (!existsSync23(planJsonPath)) {
+  if (!existsSync24(planJsonPath)) {
     throw new Error(`[freezePlan] plan.json missing: ${planJsonPath}`);
   }
-  if (!existsSync23(encoderJsonPath)) {
+  if (!existsSync24(encoderJsonPath)) {
     throw new Error(`[freezePlan] meta/encoder.json missing: ${encoderJsonPath}`);
   }
   const planJson = JSON.parse(readFileSync10(planJsonPath, "utf-8"));
@@ -17372,11 +17514,11 @@ async function freezePlan(input) {
     hasAudio,
     digests
   } = input;
-  if (!existsSync23(planDir)) {
+  if (!existsSync24(planDir)) {
     throw new Error(`[freezePlan] planDir does not exist: ${planDir}`);
   }
   const metaDir = join37(planDir, "meta");
-  if (!existsSync23(metaDir)) mkdirSync14(metaDir, { recursive: true });
+  if (!existsSync24(metaDir)) mkdirSync14(metaDir, { recursive: true });
   writeFileSync8(
     join37(metaDir, "composition.json"),
     `${JSON.stringify(composition, null, 2)}
@@ -17453,7 +17595,7 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
 }
 
 // src/services/distributed/chunkAudio.ts
-import { closeSync as closeSync6, existsSync as existsSync24, ftruncateSync, mkdirSync as mkdirSync15, openSync as openSync6, readFileSync as readFileSync11 } from "node:fs";
+import { closeSync as closeSync6, existsSync as existsSync25, ftruncateSync, mkdirSync as mkdirSync15, openSync as openSync6, readFileSync as readFileSync11 } from "node:fs";
 import { writeFileSync as writeFileSync9, writeSync } from "node:fs";
 import { join as join38 } from "node:path";
 import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure4, runFfmpeg as runFfmpeg7 } from "@hyperframes/engine";
@@ -17559,7 +17701,7 @@ async function writeChunkAudioSlices(input) {
 }
 function chunkAudioSource(planDir, chunkIndex, scratchPath) {
   const layoutPath = join38(planDir, SLICE_LAYOUT);
-  if (!existsSync24(layoutPath)) return resolvePlanAudioPath(planDir);
+  if (!existsSync25(layoutPath)) return resolvePlanAudioPath(planDir);
   const layout = JSON.parse(readFileSync11(layoutPath, "utf-8"));
   const frame = readFileSync11(join38(planDir, SLICE_FRAME));
   const fd = openSync6(scratchPath, "w");
@@ -17928,7 +18070,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) {
   assertPositiveInteger2("totalFrames", totalFrames);
   assertPositiveInteger2("maxParallelChunks", maxParallelChunks);
   if (configChunkSize !== void 0) {
@@ -17937,7 +18079,11 @@ function resolveChunkPlan(totalFrames, configChunkSize, maxParallelChunks, targe
   if (targetChunkFrames !== void 0) {
     assertPositiveInteger2("targetChunkFrames", targetChunkFrames);
   }
-  const autoSizeParallel = targetChunkFrames === void 0 ? maxParallelChunks : Math.min(maxParallelChunks, Math.max(1, Math.ceil(totalFrames / targetChunkFrames)));
+  assertPositiveInteger2("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));
@@ -18105,7 +18251,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;
 }
@@ -18119,8 +18265,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 && (existsSync25(join40(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
-        result = ["compiled", ...rel.split(sep2)].join("/");
+      if (rel !== null && (existsSync26(join40(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
+        result = ["compiled", ...rel.split(sep3)].join("/");
         break;
       }
     }
@@ -18147,7 +18293,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     useGpu: false,
     browserGpuMode: "software"
   });
-  if (!existsSync25(planDir)) mkdirSync16(planDir, { recursive: true });
+  if (!existsSync26(planDir)) mkdirSync16(planDir, { recursive: true });
   const log = config.logger ?? defaultLogger;
   const sizeLimitBytes = options.executionPlanSizeLimitBytes ?? config.planDirSizeLimitBytes ?? PLAN_DIR_SIZE_LIMIT_BYTES;
   const abortSignal = config.abortSignal;
@@ -18177,7 +18323,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   });
   const entryFile = config.entryFile ?? "index.html";
   const htmlPath = join40(projectDir, entryFile);
-  if (!existsSync25(htmlPath)) {
+  if (!existsSync26(htmlPath)) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
   const workDir = join40(planDir, ".plan-work");
@@ -18192,7 +18338,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);
     }
   });
@@ -18405,15 +18551,15 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "extract", stageStarted);
   const stagedVideoFrames = join40(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join40(planDir, "video-frames");
-  if (existsSync25(videoFramesDst)) rmSync14(videoFramesDst, { recursive: true, force: true });
+  if (existsSync26(videoFramesDst)) rmSync14(videoFramesDst, { recursive: true, force: true });
   const videoSourcesDir = join40(planDir, "video-sources");
   rmSync14(videoSourcesDir, { recursive: true, force: true });
-  if (existsSync25(stagedVideoFrames)) {
+  if (existsSync26(stagedVideoFrames)) {
     renameWithRetry8(stagedVideoFrames, videoFramesDst);
   } else {
     mkdirSync16(videoFramesDst, { recursive: true });
   }
-  if (existsSync25(finalCompiledDir)) rmSync14(finalCompiledDir, { recursive: true, force: true });
+  if (existsSync26(finalCompiledDir)) rmSync14(finalCompiledDir, { recursive: true, force: true });
   renameWithRetry8(compiledDir, finalCompiledDir);
   const shipVideoSource = createVideoSourceShipper({
     planDir,
@@ -18516,7 +18662,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     totalFrames,
     config.chunkSize,
     maxParallel,
-    config.targetChunkFrames
+    config.targetChunkFrames,
+    config.minParallelChunks
   );
   const chunks = buildPlanChunkSlices(
     frameWeights,
@@ -18533,10 +18680,10 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);
   }
   const planAudioPath = join40(planDir, PLAN_AUDIO_RELATIVE_PATH);
-  if (audioResult?.hasAudio && existsSync25(audioResult.audioOutputPath)) {
+  if (audioResult?.hasAudio && existsSync26(audioResult.audioOutputPath)) {
     renameWithRetry8(audioResult.audioOutputPath, planAudioPath);
   }
-  if (chunksCarryAudio && existsSync25(planAudioPath)) {
+  if (chunksCarryAudio && existsSync26(planAudioPath)) {
     if (options.sliceChunkAudio) {
       stageStarted = Date.now();
       await writeChunkAudioSlices({
@@ -18654,7 +18801,7 @@ async function plan(projectDir, config, planDir, options = {}) {
 
 // src/services/distributed/renderChunk.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync28, mkdirSync as mkdirSync19, readFileSync as readFileSync13, readdirSync as readdirSync11, rmSync as rmSync17, writeFileSync as writeFileSync13 } from "node:fs";
+import { existsSync as existsSync29, mkdirSync as mkdirSync19, readFileSync as readFileSync13, readdirSync as readdirSync11, rmSync as rmSync17, writeFileSync as writeFileSync13 } from "node:fs";
 import { cpus as cpus3 } from "node:os";
 import { join as join44 } from "node:path";
 import {
@@ -18681,7 +18828,7 @@ import {
 } from "@hyperframes/engine";
 import {
   copyFileSync as copyFileSync8,
-  existsSync as existsSync27,
+  existsSync as existsSync28,
   lstatSync as lstatSync3,
   mkdirSync as mkdirSync18,
   mkdtempSync as mkdtempSync6,
@@ -18692,14 +18839,14 @@ import {
   writeFileSync as writeFileSync12
 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
-import { dirname as dirname17, isAbsolute as isAbsolute4, join as join43, relative as relative6, resolve as resolve10, sep as sep3 } from "node:path";
+import { dirname as dirname17, isAbsolute as isAbsolute4, join as join43, relative as relative6, resolve as resolve10, 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 existsSync26,
+  existsSync as existsSync27,
   linkSync as linkSync2,
   mkdirSync as mkdirSync17,
   mkdtempSync as mkdtempSync5,
@@ -18768,7 +18915,7 @@ var LocalPlanV2ArtifactPublisher = class {
   #linkFile;
   #committed = false;
   constructor(destinationDir, options = {}) {
-    if (existsSync26(destinationDir)) {
+    if (existsSync27(destinationDir)) {
       throw new PlanV2IntegrityError(`output directory already exists: ${destinationDir}`);
     }
     this.destinationDir = destinationDir;
@@ -18785,7 +18932,7 @@ var LocalPlanV2ArtifactPublisher = class {
       );
     }
     const destinationPath = planV2BlobPath(this.temporaryDir, digest);
-    if (existsSync26(destinationPath)) return;
+    if (existsSync27(destinationPath)) return;
     mkdirSync17(dirname16(destinationPath), { recursive: true });
     const stagingDir = mkdtempSync5(join42(dirname16(destinationPath), ".plan-v2-blob-"));
     const temporaryPath = join42(stagingDir, "blob");
@@ -18803,7 +18950,7 @@ var LocalPlanV2ArtifactPublisher = class {
   }
   async commitManifest(manifestBytes) {
     for (const digest of new Set(manifestDigests(manifestBytes))) {
-      if (!existsSync26(planV2BlobPath(this.temporaryDir, digest))) {
+      if (!existsSync27(planV2BlobPath(this.temporaryDir, digest))) {
         throw new PlanV2IntegrityError(
           `cannot commit manifest before referenced blob is durable: ${digest}`
         );
@@ -18859,7 +19006,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 {
@@ -18882,7 +19029,7 @@ function assertValidExtractionCacheCompleteSentinel(path) {
 }
 function validateExtractionCacheCompleteSentinels(executionPlanDir) {
   const videoRoot = join43(executionPlanDir, "video-frames");
-  if (!existsSync27(videoRoot)) return;
+  if (!existsSync28(videoRoot)) return;
   for (const videoEntry of readdirSync10(videoRoot, { withFileTypes: true })) {
     if (!videoEntry.isDirectory()) continue;
     const videoDir = join43(videoRoot, videoEntry.name);
@@ -18899,7 +19046,7 @@ function isExtractionCacheCompleteSentinelPath(path) {
 function resolveExtractedVideoOutputDir(planDir, videoId) {
   const videoRoot = resolve10(planDir, "video-frames");
   const outputDir = resolve10(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;
@@ -18983,7 +19130,7 @@ function parsePlanVideosJson2(value) {
 }
 function materializeExtractedVideoDirectories(planDir) {
   const videosPath = join43(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync27(videosPath)) return;
+  if (!existsSync28(videosPath)) return;
   const videos = parsePlanVideosJson2(readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH));
   for (const video of videos.extracted) {
     mkdirSync18(resolveExtractedVideoOutputDir(planDir, video.videoId), { recursive: true });
@@ -19017,9 +19164,9 @@ function parseChunkSlices(value) {
 }
 function buildVideoChunkDependencies(executionPlanDir, dimensions) {
   const videoRoot = join43(executionPlanDir, "video-frames");
-  const hasExtractedFrames = existsSync27(videoRoot) && listFiles(videoRoot).length > 0;
+  const hasExtractedFrames = existsSync28(videoRoot) && listFiles(videoRoot).length > 0;
   const videosPath = join43(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync27(videosPath)) {
+  if (!existsSync28(videosPath)) {
     return hasExtractedFrames ? { mode: "full-source-pack", dependencies: null } : { mode: "exact-rendered-frames", dependencies: /* @__PURE__ */ new Map() };
   }
   const chunksPath = join43(executionPlanDir, "meta", "chunks.json");
@@ -19059,7 +19206,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(resolve10(input.executionPlanDir), payload.framePath).split(sep3).join("/");
+        const path = input.deferredSources.get(videoId) ?? relative6(resolve10(input.executionPlanDir), payload.framePath).split(sep4).join("/");
         assertSafeRelativePath(path);
         const indexes = mutable.get(path) ?? /* @__PURE__ */ new Set();
         indexes.add(chunk.index);
@@ -19076,7 +19223,7 @@ function computeManifestHash(manifest) {
   return sha256Hex(`${PLAN_V2_HASH_PREFIX}${canonicalJsonStringify(manifestPayload(manifest))}`);
 }
 function writeBlob(sourcePath, destinationPath) {
-  if (existsSync27(destinationPath)) return;
+  if (existsSync28(destinationPath)) return;
   mkdirSync18(dirname17(destinationPath), { recursive: true });
   const temporaryDir = mkdtempSync6(join43(dirname17(destinationPath), ".plan-v2-blob-"));
   const temporaryPath = join43(temporaryDir, "blob");
@@ -19116,7 +19263,7 @@ async function putTasks(tasks) {
 }
 function buildPlanV2Publication(executionPlanDir, digests) {
   const executionPlanPath = join43(executionPlanDir, "plan.json");
-  if (!existsSync27(executionPlanPath)) {
+  if (!existsSync28(executionPlanPath)) {
     throw new PlanV2IntegrityError(`execution plan is missing plan.json: ${executionPlanPath}`);
   }
   const executionPlanValue = readJsonFile(executionPlanPath, "execution plan.json");
@@ -19196,7 +19343,7 @@ function buildPlanV2Publication(executionPlanDir, digests) {
   };
 }
 function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
-  if (existsSync27(planV2Dir)) {
+  if (existsSync28(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publication = buildPlanV2Publication(executionPlanDir);
@@ -19282,7 +19429,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
   }
 }
 async function planV2(projectDir, config, planV2Dir) {
-  if (existsSync27(planV2Dir)) {
+  if (existsSync28(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publisher = new LocalPlanV2ArtifactPublisher(planV2Dir);
@@ -19436,7 +19583,7 @@ function parsePlanV2Manifest(value) {
 }
 function readPlanV2Manifest(planV2Dir) {
   const manifestPath = join43(planV2Dir, "plan.json");
-  if (!existsSync27(manifestPath)) {
+  if (!existsSync28(manifestPath)) {
     throw new PlanV2IntegrityError(`missing v2 manifest: ${manifestPath}`);
   }
   const value = readJsonFile(manifestPath, "v2 manifest");
@@ -19455,7 +19602,7 @@ function listPlanV2ArtifactsForTarget(manifest, target) {
 }
 function verifyBlob(planV2Dir, artifact) {
   const sourcePath = planV2BlobPath(planV2Dir, artifact.sha256);
-  if (!existsSync27(sourcePath)) {
+  if (!existsSync28(sourcePath)) {
     throw new PlanV2IntegrityError(`missing content-addressed artifact ${artifact.sha256}`);
   }
   const stats = statSync11(sourcePath);
@@ -19468,7 +19615,7 @@ function verifyBlob(planV2Dir, artifact) {
   return sourcePath;
 }
 function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
-  if (existsSync27(destinationDir)) {
+  if (existsSync28(destinationDir)) {
     throw new PlanV2IntegrityError(`materialization destination already exists: ${destinationDir}`);
   }
   const manifest = readPlanV2Manifest(planV2Dir);
@@ -19533,7 +19680,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
 }
 function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   const markerPath = join43(planDir, PLAN_V2_MATERIALIZATION_MARKER);
-  if (!existsSync27(markerPath)) return null;
+  if (!existsSync28(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
   if (!isRecord3(marker) || !isRecord3(marker.manifest) || !isRecord3(marker.target)) {
     throw new PlanV2IntegrityError("malformed materialization marker");
@@ -19551,7 +19698,7 @@ function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   for (const artifact of required) {
     if (Object.hasOwn(remoteSources, artifact.path)) continue;
     const path = join43(planDir, ...artifact.path.split("/"));
-    if (!existsSync27(path) || statSync11(path).size !== artifact.sizeBytes) {
+    if (!existsSync28(path) || statSync11(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
         `materialized artifact missing or truncated: ${artifact.path}`
       );
@@ -19651,12 +19798,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;
@@ -19691,7 +19849,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const planJsonPath = join44(planDir, "plan.json");
   const encoderJsonPath = join44(planDir, "meta", "encoder.json");
   const chunksJsonPath = join44(planDir, "meta", "chunks.json");
-  if (!existsSync28(planJsonPath)) {
+  if (!existsSync29(planJsonPath)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir is missing required artifact: ${planJsonPath}`
@@ -19707,7 +19865,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const v2Manifest = v2Materialization?.manifest ?? null;
   const remoteSources = v2Materialization?.remoteSources ?? {};
   for (const required of [encoderJsonPath, chunksJsonPath]) {
-    if (!existsSync28(required)) {
+    if (!existsSync29(required)) {
       throw new RenderChunkValidationError(
         MISSING_PLAN_ARTIFACT,
         `[renderChunk] planDir is missing required artifact: ${required}`
@@ -19718,7 +19876,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const chunks = JSON.parse(readFileSync13(chunksJsonPath, "utf-8"));
   const videosJsonPath = join44(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   let planVideos = null;
-  if (existsSync28(videosJsonPath)) {
+  if (existsSync29(videosJsonPath)) {
     try {
       planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync13(videosJsonPath, "utf-8")));
     } catch (err) {
@@ -19749,7 +19907,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const range = resolveChunkFrameRange(slice, chunkIndex, options?.frameRange);
   const framesInChunk = range.endFrame - range.startFrame;
   const compiledDir = join44(planDir, "compiled");
-  if (!existsSync28(compiledDir)) {
+  if (!existsSync29(compiledDir)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir missing compiled/ directory: ${compiledDir}`
@@ -19999,10 +20157,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 (!existsSync28(outputChunkPath)) mkdirSync19(outputChunkPath, { recursive: true });
+        if (!existsSync29(outputChunkPath)) mkdirSync19(outputChunkPath, { recursive: true });
       } else {
         const outDir = join44(outputChunkPath, "..");
-        if (!existsSync28(outDir)) mkdirSync19(outDir, { recursive: true });
+        if (!existsSync29(outDir)) mkdirSync19(outDir, { recursive: true });
       }
       const encodeInput = {
         job,
@@ -20509,6 +20667,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)) {
@@ -20678,6 +20850,7 @@ function assertDistributedOptions(value) {
     "chunkSize",
     "maxParallelChunks",
     "targetChunkFrames",
+    "minParallelChunks",
     "planDirSizeLimitBytes"
   ]) {
     assertOptionalInteger(value, field, 1);
@@ -20817,6 +20990,7 @@ function distributedConfigFromRequest(request, runtime = {}) {
     chunkSize: distributed.chunkSize,
     maxParallelChunks: distributed.maxParallelChunks,
     targetChunkFrames: distributed.targetChunkFrames,
+    minParallelChunks: distributed.minParallelChunks,
     runtimeCap: distributed.runtimeCap,
     rejectOnSystemFonts: distributed.rejectOnSystemFonts,
     failClosedFontFetch: distributed.failClosedFontFetch,
@@ -20844,6 +21018,7 @@ function renderRequestFromDistributedConfig(input) {
     ...optionalProperty("chunkSize", config.chunkSize),
     ...optionalProperty("maxParallelChunks", config.maxParallelChunks),
     ...optionalProperty("targetChunkFrames", config.targetChunkFrames),
+    ...optionalProperty("minParallelChunks", config.minParallelChunks),
     ...optionalProperty("runtimeCap", config.runtimeCap),
     ...optionalProperty("rejectOnSystemFonts", config.rejectOnSystemFonts),
     ...optionalProperty("failClosedFontFetch", config.failClosedFontFetch),
@@ -20902,7 +21077,7 @@ import {
 
 // src/server.ts
 import {
-  existsSync as existsSync31,
+  existsSync as existsSync32,
   mkdirSync as mkdirSync21,
   statSync as statSync13,
   mkdtempSync as mkdtempSync8,
@@ -20925,7 +21100,7 @@ import {
 
 // src/services/hyperframeLint.ts
 import {
-  existsSync as existsSync29,
+  existsSync as existsSync30,
   readFileSync as readFileSync15,
   statSync as statSync12,
   openSync as openSync7,
@@ -20933,7 +21108,7 @@ import {
   closeSync as closeSync7,
   constants as constants3
 } from "node:fs";
-import { resolve as resolve11, join as join46, relative as relative7, isAbsolute as isAbsolute5, sep as sep4 } from "node:path";
+import { resolve as resolve11, join as join46, relative as relative7, isAbsolute as isAbsolute5, sep as sep5 } from "node:path";
 import { lintHyperframeHtml } from "@hyperframes/lint";
 function isStringRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -20979,7 +21154,7 @@ function readEntryHtml(filePath) {
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
   const absProjectDir = resolve11(projectDir);
-  if (!existsSync29(absProjectDir) || !statSync12(absProjectDir).isDirectory()) {
+  if (!existsSync30(absProjectDir) || !statSync12(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entryCandidates = [preferredEntryFile, "index.html", "src/index.html"].filter(
@@ -20988,7 +21163,7 @@ function readProjectEntryFile(projectDir, preferredEntryFile) {
   for (const entryFile of entryCandidates) {
     const absoluteEntryPath = resolve11(absProjectDir, entryFile);
     const entryRelativePath = relative7(absProjectDir, absoluteEntryPath);
-    if (entryRelativePath === ".." || entryRelativePath.startsWith(`..${sep4}`) || isAbsolute5(entryRelativePath)) {
+    if (entryRelativePath === ".." || entryRelativePath.startsWith(`..${sep5}`) || isAbsolute5(entryRelativePath)) {
       return { error: `Entry file must stay inside project directory: ${entryFile}` };
     }
     const html = readEntryHtml(absoluteEntryPath);
@@ -21048,7 +21223,7 @@ async function runHyperframeLint(prepared) {
 import { Worker as Worker2 } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
 import { dirname as dirname18, join as join47 } from "node:path";
-import { existsSync as existsSync30 } from "node:fs";
+import { existsSync as existsSync31 } from "node:fs";
 var DEFAULT_HEALTH_PORT = 9848;
 async function startHealthWorker(options = {}) {
   const log = options.logger ?? defaultLogger2();
@@ -21125,7 +21300,7 @@ function resolveWorkerEntry2() {
   const here = dirname18(fileURLToPath6(import.meta.url));
   const candidates = [join47(here, "healthWorkerThread.js"), join47(here, "healthWorkerThread.ts")];
   for (const candidate of candidates) {
-    if (existsSync30(candidate)) return candidate;
+    if (existsSync31(candidate)) return candidate;
   }
   return void 0;
 }
@@ -21271,7 +21446,7 @@ function resolvePreparedRenderOutput(prepared, rendersDir, log) {
   const { input, cleanupProjectDir } = prepared;
   const absoluteOutputPath = resolveOutputPath(input.projectDir, input.outputPath, rendersDir, log);
   const outputDir = dirname19(absoluteOutputPath);
-  if (!existsSync31(outputDir)) mkdirSync21(outputDir, { recursive: true });
+  if (!existsSync32(outputDir)) mkdirSync21(outputDir, { recursive: true });
   return { input, cleanupProjectDir, absoluteOutputPath };
 }
 function validateRenderOverrides(body) {
@@ -21312,11 +21487,11 @@ function prepareProjectDirectory(projectDir, options) {
   const candidate = nonEmptyString(projectDir);
   if (!candidate) return null;
   const absProjectDir = resolve12(candidate);
-  if (!existsSync31(absProjectDir) || !statSync13(absProjectDir).isDirectory()) {
+  if (!existsSync32(absProjectDir) || !statSync13(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entry = options.entryFile || "index.html";
-  if (!existsSync31(resolve12(absProjectDir, entry))) {
+  if (!existsSync32(resolve12(absProjectDir, entry))) {
     return { error: `Entry file "${entry}" not found in project directory: ${absProjectDir}` };
   }
   return { prepared: { input: { projectDir: absProjectDir, ...options } } };
@@ -21408,7 +21583,7 @@ function cleanupTempDir(dir, log) {
   }
 }
 function outputFileSize(path) {
-  return existsSync31(path) ? statSync13(path).size : 0;
+  return existsSync32(path) ? statSync13(path).size : 0;
 }
 function createBlockingProgressReporter(log, requestId) {
   let lastLoggedPct = -10;
@@ -21712,7 +21887,7 @@ function createRenderHandlers(options = {}) {
     if (!artifact) {
       return c.json({ success: false, error: "Output artifact not found or expired" }, 404);
     }
-    if (!existsSync31(artifact.path)) {
+    if (!existsSync32(artifact.path)) {
       store.delete(token);
       return c.json({ success: false, error: "Output artifact file missing" }, 404);
     }
@@ -21818,7 +21993,7 @@ import {
 } from "@hyperframes/engine";
 import {
   cpSync as cpSync3,
-  existsSync as existsSync32,
+  existsSync as existsSync33,
   mkdirSync as mkdirSync22,
   mkdtempSync as mkdtempSync9,
   readFileSync as readFileSync16,
@@ -21873,7 +22048,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   }
   const format = plan2.dimensions.format;
   const cfrEncoder = cfr ? readCfrEncoder(planDir, format) : null;
-  if (!existsSync32(dirname20(outputPath))) {
+  if (!existsSync33(dirname20(outputPath))) {
     mkdirSync22(dirname20(outputPath), { recursive: true });
   }
   const workDir = mkdtempSync9(`${outputPath}.assemble-work-`);
@@ -21897,7 +22072,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   try {
     const videoSources = cfrEncoder ? [await reencodeCfr(ctx, chunkPaths, cfrEncoder)] : chunkPaths;
     const finalPath = join49(workDir, `output.${format}`);
-    const audio = audioPath !== null && existsSync32(audioPath) ? audioPath : null;
+    const audio = audioPath !== null && existsSync33(audioPath) ? audioPath : null;
     await writeJoined(ctx, videoSources, audio, finalPath);
     renameWithRetry11(finalPath, outputPath);
     log.info("[assemble] stage timings", {
@@ -21915,7 +22090,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
       });
     }
   }
-  const fileSize = existsSync32(outputPath) ? statSync14(outputPath).size : 0;
+  const fileSize = existsSync33(outputPath) ? statSync14(outputPath).size : 0;
   return {
     ...referenceBackgroundResult8(plan2[REFERENCE_BACKGROUND_FIELD6]),
     outputPath,
@@ -21927,13 +22102,13 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
 function readAssemblePlan(planDir, chunkPaths) {
   const planJsonPath = join49(planDir, "plan.json");
   const chunksJsonPath = join49(planDir, "meta", "chunks.json");
-  if (!existsSync32(planJsonPath)) {
+  if (!existsSync33(planJsonPath)) {
     throw new Error(`[assemble] planDir missing plan.json: ${planJsonPath}`);
   }
   const plan2 = JSON.parse(readFileSync16(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.assembler);
   validatePlanV2MaterializedTarget(planDir, { role: "assembler" });
-  if (!existsSync32(chunksJsonPath)) {
+  if (!existsSync33(chunksJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/chunks.json: ${chunksJsonPath}`);
   }
   const chunks = JSON.parse(readFileSync16(chunksJsonPath, "utf-8"));
@@ -21948,7 +22123,7 @@ function readAssemblePlan(planDir, chunkPaths) {
     }
   }
   for (const path of chunkPaths.flat()) {
-    if (!existsSync32(path)) {
+    if (!existsSync33(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
   }
@@ -22087,7 +22262,7 @@ function planFormat(planDir) {
 }
 function lockedAudio(planDir) {
   const encoderJsonPath = join49(planDir, "meta", "encoder.json");
-  if (!existsSync32(encoderJsonPath)) return {};
+  if (!existsSync33(encoderJsonPath)) return {};
   return JSON.parse(readFileSync16(encoderJsonPath, "utf-8"));
 }
 function readCfrEncoder(planDir, format) {
@@ -22097,7 +22272,7 @@ function readCfrEncoder(planDir, format) {
     );
   }
   const encoderJsonPath = join49(planDir, "meta", "encoder.json");
-  if (!existsSync32(encoderJsonPath)) {
+  if (!existsSync33(encoderJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
   }
   const encoderJson = JSON.parse(readFileSync16(encoderJsonPath, "utf-8"));
@@ -22109,7 +22284,7 @@ function readCfrEncoder(planDir, format) {
   return encoderJson;
 }
 function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, startTimeMs) {
-  if (existsSync32(outputPath)) rmSync20(outputPath, { recursive: true, force: true });
+  if (existsSync33(outputPath)) rmSync20(outputPath, { recursive: true, force: true });
   mkdirSync22(outputPath, { recursive: true });
   let globalIdx = 0;
   for (const chunkDir of chunkPaths) {
@@ -22133,7 +22308,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 && existsSync32(audioPath)) {
+  if (audioPath !== null && existsSync33(audioPath)) {
     const sidecar = join49(outputPath, MIXED_AUDIO_FILENAME4);
     cpSync3(audioPath, sidecar);
   }