hyperframes 0.8.141 → 0.8.143

package/dist/{chunk-P6E4HFFU.js → chunk-6XMFEICO.js}

@@ -11,12 +11,12 @@ import {
   iterateFontFamilyDeclarations,
   normalizeSystemFontPrimaryFamilies,
   resolveFontFamilyDeclarationFamilies
-} from "./chunk-7M4KAPAA.js";
+} from "./chunk-PUGIRFPX.js";
 import {
   EncoderInterruptedError,
   encoderFailureError,
   prepareAnimatedGifInputs
-} from "./chunk-INI3TM6I.js";
+} from "./chunk-KQLGTGE5.js";
 import {
   createStudioPositionSeekReapplyScript
 } from "./chunk-KC5XXX3X.js";
@@ -79,6 +79,7 @@ import {
   extractAllVideoFrames,
   extractAudioMetadata,
   extractMediaMetadata,
+  extractVideoFramesRange,
   extractionFrameCountForDuration,
   fetchPublicHttpsText,
   fingerprintElementId,
@@ -141,7 +142,7 @@ import {
   validateEngineConfigSnapshot,
   verifyDiskDrawElementSamples,
   writeCapturedFrame
-} from "./chunk-E6SDW5FV.js";
+} from "./chunk-33RZPZ4K.js";
 import {
   assignBundledRuntimeCompositionIds,
   buildVariablesByCompScript,
@@ -151,7 +152,7 @@ import {
   ensureExternalScriptTag,
   inlineSubCompositions,
   prepareFlattenedInnerRoot
-} from "./chunk-35RSNI77.js";
+} from "./chunk-F26LCYRY.js";
 import {
   LOW_MEMORY_TOTAL_MB_THRESHOLD,
   getCgroupMemoryLimitMb,
@@ -172,18 +173,7 @@ import {
   resolveAbsoluteMediaStartSeconds,
   resolveAuthoredTimingWindow,
   toFps
-} from "./chunk-6E6CM7WS.js";
-import {
-  CANVAS_DIMENSIONS,
-  HTML_BODY_CSS_HEIGHT_FIRST_RE,
-  HTML_BODY_CSS_WIDTH_FIRST_RE,
-  VALID_CANVAS_RESOLUTIONS,
-  checkOutputResolutionCompatibility,
-  extractMediaSrcMutations,
-  isAspectAgnosticResolutionAlias,
-  normalizeResolutionFlag,
-  suggestMatchingPreset
-} from "./chunk-OZUQF4NB.js";
+} from "./chunk-4M4EC7JX.js";
 import {
   COMPOSITION_SOURCE_URL,
   HF_COLOR_GRADING_ATTR,
@@ -210,10 +200,21 @@ import {
   shouldClampResolvedMediaDuration,
   sourceTimeAt,
   styleElementsFor
-} from "./chunk-SYKKFAUW.js";
+} from "./chunk-6TPZSTCL.js";
 import {
   MAX_AUDIO_GAIN
 } from "./chunk-YA62XGXS.js";
+import {
+  CANVAS_DIMENSIONS,
+  HTML_BODY_CSS_HEIGHT_FIRST_RE,
+  HTML_BODY_CSS_WIDTH_FIRST_RE,
+  VALID_CANVAS_RESOLUTIONS,
+  checkOutputResolutionCompatibility,
+  extractMediaSrcMutations,
+  isAspectAgnosticResolutionAlias,
+  normalizeResolutionFlag,
+  suggestMatchingPreset
+} from "./chunk-MQZVBHEY.js";
 import {
   redactKnownPaths,
   redactTelemetryString
@@ -223,23 +224,26 @@ import {
 } from "./chunk-TWWSYAKJ.js";
 import {
   lintHyperframeHtml
-} from "./chunk-WY5OODN5.js";
+} from "./chunk-XONFUK3M.js";
 import {
   isUnresolvedAssetPlaceholder,
   readProjectFile,
   resolveProjectRelativeSrc
-} from "./chunk-JFKL3WAE.js";
+} from "./chunk-IWFLMU2N.js";
+import {
+  checkSubCompositionUsability
+} from "./chunk-3RM2ETQT.js";
 import {
   CSS_URL_RE,
-  checkSubCompositionUsability,
+  decodedUrlPath,
   isNonRelativeUrl,
   rewriteAssetPaths,
   rewriteCssAssetUrls,
   rewriteInlineStyleAssetUrls
-} from "./chunk-TQFG7HTI.js";
+} from "./chunk-ZLW2V65P.js";
 import {
   parseHTML
-} from "./chunk-GK4AIFIH.js";
+} from "./chunk-SDYDNHEE.js";
 import {
   TRANSITIONS,
   convertTransfer,
@@ -5691,8 +5695,9 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
     } catch {
       return { duration: null, resolvedPath: src };
     }
-  } else if (!filePath.startsWith("/")) {
-    filePath = join12(baseDir, filePath);
+  } else {
+    filePath = decodedUrlPath(src);
+    if (!filePath.startsWith("/")) filePath = join12(baseDir, filePath);
   }
   if (!existsSync9(filePath)) {
     return { duration: null, resolvedPath: filePath };
@@ -6493,7 +6498,7 @@ async function readLocalFont(absPath) {
   return { kind: "inline", buffer: Buffer.concat(chunks, totalBytes) };
 }
 async function embedLocalFontFaces(html, projectDir) {
-  const { fontToDataUri: toDataUri } = await import("./deterministicFonts-F6WIVL2W.js");
+  const { fontToDataUri: toDataUri } = await import("./deterministicFonts-U2BIMGPG.js");
   const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
   const fontFaceRe = /@font-face\s*\{([^}]*)\}/gi;
   let result = html;
@@ -8029,7 +8034,8 @@ async function runExtractVideosStage(input) {
     composition,
     abortSignal,
     assertNotAborted,
-    materializeSymlinks
+    materializeSymlinks,
+    deferRangeExtraction
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -8118,7 +8124,8 @@ async function runExtractVideosStage(input) {
         toneMapHdrToSdr: job.config.hdrMode === "force-sdr",
         timelineEnd: composition.duration,
         maxTransientRetries: extractionPolicy.maxTransientRetries,
-        collectProbeFailures: extractionPolicy.failureMode === "enforce"
+        collectProbeFailures: extractionPolicy.failureMode === "enforce",
+        deferRangeExtraction
       },
       abortSignal,
       cfg,
@@ -14319,7 +14326,7 @@ function startServer(options = {}) {
   });
   async function shutdown(signal) {
     log.info(`Received ${signal}, shutting down`);
-    const { drainBrowserPool } = await import("./src-I7UC3JTL.js");
+    const { drainBrowserPool } = await import("./src-JO5JOV7Y.js");
     await drainBrowserPool().catch(() => {
     });
     const handle = await Promise.race([
@@ -14355,8 +14362,17 @@ if (isPublicServerEntry) {
 }
 
 // ../producer/src/services/distributed/plan.ts
-import { cpSync as cpSync2, existsSync as existsSync21, mkdirSync as mkdirSync11, renameSync as renameSync4, rmSync as rmSync10, writeFileSync as writeFileSync8 } from "fs";
-import { join as join32, relative as relative6, sep as sep3 } from "path";
+import {
+  copyFileSync as copyFileSync4,
+  cpSync as cpSync2,
+  existsSync as existsSync21,
+  linkSync,
+  mkdirSync as mkdirSync11,
+  renameSync as renameSync4,
+  rmSync as rmSync10,
+  writeFileSync as writeFileSync8
+} from "fs";
+import { extname as extname5, isAbsolute as isAbsolute3, join as join32, relative as relative6, sep as sep3 } from "path";
 
 // ../producer/src/services/render/stages/freezePlan.ts
 import { existsSync as existsSync19, mkdirSync as mkdirSync10, readFileSync as readFileSync9, readdirSync as readdirSync6, writeFileSync as writeFileSync7 } from "fs";
@@ -14756,6 +14772,24 @@ function readNonNegativeInteger(value, field) {
   }
   return value;
 }
+function readDeferredFrameRange(value, field) {
+  const range = readRecord(value, field);
+  const sourcePath = readNonEmptyString(range.sourcePath, `${field}.sourcePath`);
+  if (sourcePath.startsWith("/") || sourcePath.split(/[\\/]/).some((part) => part === "..")) {
+    metadataError(`${field}.sourcePath`, "must stay inside the plan directory");
+  }
+  const durationSeconds = readFiniteNumber(range.durationSeconds, `${field}.durationSeconds`);
+  if (durationSeconds <= 0) metadataError(`${field}.durationSeconds`, "must be positive");
+  if (range.format !== "jpg" && range.format !== "png") {
+    metadataError(`${field}.format`, 'must be "jpg" or "png"');
+  }
+  return {
+    sourcePath,
+    startTime: readFiniteNumber(range.startTime, `${field}.startTime`),
+    durationSeconds,
+    format: range.format
+  };
+}
 function readRateSpec(value, field) {
   if (value === void 0) return void 0;
   if (typeof value === "number") return readFiniteNumber(value, field);
@@ -14824,7 +14858,8 @@ function parsePlanVideosJson(value) {
       framePattern: readNonEmptyString(entry.framePattern, `${field}.framePattern`),
       fps: readFiniteNumber(entry.fps, `${field}.fps`),
       totalFrames: readNonNegativeInteger(entry.totalFrames, `${field}.totalFrames`),
-      metadata: readVideoMetadata(entry.metadata, `${field}.metadata`)
+      metadata: readVideoMetadata(entry.metadata, `${field}.metadata`),
+      ...entry.deferredRange === void 0 ? {} : { deferredRange: readDeferredFrameRange(entry.deferredRange, `${field}.deferredRange`) }
     };
   });
   const videoIds = /* @__PURE__ */ new Set();
@@ -15329,6 +15364,39 @@ function resolveDistributedEngineConfig(config) {
     forceScreenshotExplicitlyOptedOut: true
   };
 }
+function pathInside(root, path) {
+  const rel = relative6(root, path);
+  return rel === "" || rel.startsWith("..") || isAbsolute3(rel) ? null : rel;
+}
+function createVideoSourceShipper(input) {
+  const shipped = /* @__PURE__ */ new Map();
+  return (srcPath) => {
+    const known = shipped.get(srcPath);
+    if (known) return known;
+    const stagedRel = pathInside(input.workVideoFramesDir, srcPath);
+    const current = stagedRel === null ? srcPath : join32(input.planDir, "video-frames", stagedRel);
+    let result = null;
+    for (const root of stagedRel === null ? [input.workCompiledDir, input.projectDir] : []) {
+      const rel = pathInside(root, srcPath);
+      if (rel !== null && existsSync21(join32(input.planDir, "compiled", rel))) {
+        result = ["compiled", ...rel.split(sep3)].join("/");
+        break;
+      }
+    }
+    if (result === null) {
+      result = `video-sources/${shipped.size}${extname5(current)}`;
+      const destination = join32(input.planDir, ...result.split("/"));
+      mkdirSync11(join32(input.planDir, "video-sources"), { recursive: true });
+      try {
+        linkSync(current, destination);
+      } catch {
+        copyFileSync4(current, destination);
+      }
+    }
+    shipped.set(srcPath, result);
+    return result;
+  };
+}
 async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, options = {}) {
   const planDir = executionPlanDir;
   rejectUnsupportedDistributedFormat(config);
@@ -15442,7 +15510,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   if (probeResult.fileServer) closeFileServerSafely(probeResult.fileServer, "plan", log);
   if (probeResult.probeSession) {
     try {
-      const { closeCaptureSession: closeCaptureSession2 } = await import("./src-I7UC3JTL.js");
+      const { closeCaptureSession: closeCaptureSession2 } = await import("./src-JO5JOV7Y.js");
       await closeCaptureSession2(probeResult.probeSession);
     } catch (err) {
       log.warn("[plan] probe session close failed", {
@@ -15465,7 +15533,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     composition,
     abortSignal,
     assertNotAborted,
-    materializeSymlinks: true
+    materializeSymlinks: true,
+    deferRangeExtraction: options.deferVideoExtraction
   });
   if (extractResult.failureToEnforce) throw extractResult.failureToEnforce;
   if (extractResult.extractionResult) {
@@ -15488,6 +15557,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   const stagedVideoFrames = join32(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join32(planDir, "video-frames");
   if (existsSync21(videoFramesDst)) rmSync10(videoFramesDst, { recursive: true, force: true });
+  rmSync10(join32(planDir, "video-sources"), { recursive: true, force: true });
   if (existsSync21(stagedVideoFrames)) {
     renameSync4(stagedVideoFrames, videoFramesDst);
   } else {
@@ -15495,6 +15565,12 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   }
   if (existsSync21(finalCompiledDir)) rmSync10(finalCompiledDir, { recursive: true, force: true });
   renameSync4(compiledDir, finalCompiledDir);
+  const shipVideoSource = createVideoSourceShipper({
+    planDir,
+    projectDir,
+    workCompiledDir: compiledDir,
+    workVideoFramesDir: stagedVideoFrames
+  });
   const planVideosJson = buildPlanVideosJson({
     videos: composition.videos,
     compositionEnd: job.duration ?? Number.NaN,
@@ -15504,7 +15580,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
       framePattern: ext.framePattern,
       fps: ext.fps,
       totalFrames: ext.totalFrames,
-      metadata: ext.metadata
+      metadata: ext.metadata,
+      ...ext.deferredRange ? { deferredRange: { ...ext.deferredRange, sourcePath: shipVideoSource(ext.srcPath) } } : {}
     }))
   });
   mkdirSync11(join32(planDir, "meta"), { recursive: true });
@@ -15624,7 +15701,7 @@ async function plan(projectDir, config, planDir) {
 // ../producer/src/services/distributed/planV2.ts
 import {
   closeSync as closeSync6,
-  copyFileSync as copyFileSync5,
+  copyFileSync as copyFileSync6,
   existsSync as existsSync23,
   lstatSync as lstatSync3,
   mkdirSync as mkdirSync13,
@@ -15640,13 +15717,13 @@ import {
 } from "fs";
 import { createHash as createHash7 } from "crypto";
 import { tmpdir as tmpdir4 } from "os";
-import { dirname as dirname14, isAbsolute as isAbsolute3, join as join35, relative as relative7, resolve as resolve10, sep as sep4 } from "path";
+import { dirname as dirname14, isAbsolute as isAbsolute4, join as join35, relative as relative7, resolve as resolve10, sep as sep4 } from "path";
 
 // ../producer/src/services/distributed/planV2Publisher.ts
 import {
-  copyFileSync as copyFileSync4,
+  copyFileSync as copyFileSync5,
   existsSync as existsSync22,
-  linkSync,
+  linkSync as linkSync2,
   mkdirSync as mkdirSync12,
   mkdtempSync as mkdtempSync5,
   renameSync as renameSync5,
@@ -15718,7 +15795,7 @@ var LocalPlanV2ArtifactPublisher = class {
       throw new PlanV2IntegrityError(`output directory already exists: ${destinationDir}`);
     }
     this.destinationDir = destinationDir;
-    this.#linkFile = options.linkFile ?? linkSync;
+    this.#linkFile = options.linkFile ?? linkSync2;
     mkdirSync12(dirname13(destinationDir), { recursive: true });
     this.temporaryDir = mkdtempSync5(join34(dirname13(destinationDir), ".plan-v2-publish-"));
   }
@@ -15740,7 +15817,7 @@ var LocalPlanV2ArtifactPublisher = class {
         this.#linkFile(blob.sourcePath, temporaryPath);
       } catch (error) {
         if (!canFallbackToCopy(error)) throw error;
-        copyFileSync4(blob.sourcePath, temporaryPath);
+        copyFileSync5(blob.sourcePath, temporaryPath);
       }
       renameSync5(temporaryPath, destinationPath);
     } finally {
@@ -15791,7 +15868,7 @@ function readJsonFile(path, label) {
 }
 function assertSafeRelativePath(path) {
   const normalized = path.split(/[\\/]+/);
-  if (path.length === 0 || isAbsolute3(path) || normalized.some((part) => part === "" || part === "." || part === "..")) {
+  if (path.length === 0 || isAbsolute4(path) || normalized.some((part) => part === "" || part === "." || part === "..")) {
     throw new PlanV2IntegrityError(`unsafe artifact path: ${JSON.stringify(path)}`);
   }
 }
@@ -15873,7 +15950,7 @@ function artifactTargets(path, videoDependencies) {
   if (path === "meta/composition.json" || path === "meta/videos.json" || path.startsWith("compiled/")) {
     return { chunks: "all", assembler: false };
   }
-  if (path.startsWith("video-frames/")) {
+  if (path.startsWith("video-frames/") || path.startsWith("video-sources/")) {
     return {
       chunks: videoDependencies === null ? "all" : videoDependencies.get(path) ?? [],
       assembler: false
@@ -15884,6 +15961,13 @@ function artifactTargets(path, videoDependencies) {
 function listVideoFramePaths(executionPlanDir, videos) {
   return videos.extracted.map((video) => {
     const outputDir = resolveExtractedVideoOutputDir(executionPlanDir, video.videoId);
+    if (video.deferredRange) {
+      const framePaths2 = /* @__PURE__ */ new Map();
+      for (let index = 0; index < video.totalFrames; index++) {
+        framePaths2.set(index, join35(outputDir, String(index)));
+      }
+      return { ...video, outputDir, framePaths: framePaths2, ownedByLookup: false };
+    }
     const frameNames = readdirSync8(outputDir).sort();
     const framePaths = /* @__PURE__ */ new Map();
     for (const frameName of frameNames) {
@@ -15976,12 +16060,31 @@ function buildVideoChunkDependencies(executionPlanDir, dimensions) {
     extracted,
     resolveRenderFpsConfig({ num: fpsNum, den: fpsDen }).value
   );
+  const deferredSources = new Map(
+    parsedVideos.extracted.flatMap(
+      (video) => video.deferredRange ? [[video.videoId, video.deferredRange.sourcePath]] : []
+    )
+  );
+  const dependencies = collectChunkVideoDependencies({
+    executionPlanDir,
+    table,
+    chunks: parsedChunks,
+    fpsNum,
+    fpsDen,
+    deferredSources
+  });
+  return {
+    mode: deferredSources.size > 0 ? "source-extract" : "exact-rendered-frames",
+    dependencies
+  };
+}
+function collectChunkVideoDependencies(input) {
   const mutable = /* @__PURE__ */ new Map();
-  for (const chunk of parsedChunks) {
+  for (const chunk of input.chunks) {
     for (let frame = chunk.startFrame; frame < chunk.endFrame; frame++) {
-      const globalTime = frame * fpsDen / fpsNum;
-      for (const payload of table.getActiveFramePayloads(globalTime).values()) {
-        const path = relative7(resolve10(executionPlanDir), payload.framePath).split(sep4).join("/");
+      const globalTime = frame * input.fpsDen / input.fpsNum;
+      for (const [videoId, payload] of input.table.getActiveFramePayloads(globalTime)) {
+        const path = input.deferredSources.get(videoId) ?? relative7(resolve10(input.executionPlanDir), payload.framePath).split(sep4).join("/");
         assertSafeRelativePath(path);
         const indexes = mutable.get(path) ?? /* @__PURE__ */ new Set();
         indexes.add(chunk.index);
@@ -15989,12 +16092,7 @@ function buildVideoChunkDependencies(executionPlanDir, dimensions) {
       }
     }
   }
-  return {
-    mode: "exact-rendered-frames",
-    dependencies: new Map(
-      [...mutable].map(([path, indexes]) => [path, [...indexes].sort((a, b) => a - b)])
-    )
-  };
+  return new Map([...mutable].map(([path, indexes]) => [path, [...indexes].sort((a, b) => a - b)]));
 }
 function manifestPayload(manifest) {
   return manifest;
@@ -16008,7 +16106,7 @@ function writeBlob(sourcePath, destinationPath) {
   const temporaryDir = mkdtempSync6(join35(dirname14(destinationPath), ".plan-v2-blob-"));
   const temporaryPath = join35(temporaryDir, "blob");
   try {
-    copyFileSync5(sourcePath, temporaryPath);
+    copyFileSync6(sourcePath, temporaryPath);
     renameSync6(temporaryPath, destinationPath);
   } finally {
     rmSync12(temporaryDir, { recursive: true, force: true });
@@ -16046,7 +16144,7 @@ function buildPlanV2Publication(executionPlanDir) {
   for (const file of listFiles(executionPlanDir)) {
     if (isExtractionCacheCompleteSentinelPath(file.path)) continue;
     const targets = artifactTargets(file.path, videoDependencyPlan.dependencies);
-    if (file.path.startsWith("video-frames/") && targets.chunks !== "all" && targets.chunks.length === 0 && !targets.assembler) {
+    if ((file.path.startsWith("video-frames/") || file.path.startsWith("video-sources/")) && targets.chunks !== "all" && targets.chunks.length === 0 && !targets.assembler) {
       continue;
     }
     const sha256 = sha256File(file.absolutePath);
@@ -16114,14 +16212,21 @@ function createPlanV2FromV1(executionPlanDir, planV2Dir) {
 async function publishPlanV2FromExecutionPlan(executionPlanDir, publisher) {
   try {
     const publication = buildPlanV2Publication(executionPlanDir);
-    const concurrency = 16;
-    for (let offset = 0; offset < publication.blobs.length; offset += concurrency) {
-      const batch = publication.blobs.slice(offset, offset + concurrency);
-      const results = await Promise.allSettled(batch.map((blob) => publisher.putBlob(blob)));
-      for (const result of results) {
-        if (result.status === "rejected") throw result.reason;
+    const uploadSlots = 32;
+    let next = 0;
+    let failure;
+    const upload = async () => {
+      while (!failure && next < publication.blobs.length) {
+        const blob = publication.blobs[next++];
+        try {
+          await publisher.putBlob(blob);
+        } catch (reason) {
+          failure ??= { reason };
+        }
       }
-    }
+    };
+    await Promise.all(Array.from({ length: uploadSlots }, upload));
+    if (failure) throw failure.reason;
     await publisher.commitManifest(canonicalJsonStringify(publication.manifest));
     return publication.manifest;
   } catch (error) {
@@ -16139,7 +16244,8 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
   const stagingRoot = mkdtempSync6(join35(options.stagingParentDir ?? tmpdir4(), ".execution-plan-"));
   try {
     await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
-      executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER
+      executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER,
+      deferVideoExtraction: true
     });
     return await publishPlanV2FromExecutionPlan(stagingRoot, publisher);
   } catch (error) {
@@ -16268,7 +16374,7 @@ function parsePlanV2Manifest(value) {
   }
   if (!paths.has("plan.json"))
     throw new PlanV2IntegrityError("manifest must include the local execution plan.json artifact");
-  if (!isRecord3(value.limitations) || value.limitations.videoDependencyMode !== "exact-rendered-frames" && value.limitations.videoDependencyMode !== "full-source-pack") {
+  if (!isRecord3(value.limitations) || value.limitations.videoDependencyMode !== "exact-rendered-frames" && value.limitations.videoDependencyMode !== "full-source-pack" && value.limitations.videoDependencyMode !== "source-extract") {
     throw new PlanV2IntegrityError("unsupported video dependency mode");
   }
   const parsed = {
@@ -16348,7 +16454,7 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
     for (const { artifact, sourcePath } of verified) {
       const destinationPath = join35(tempDir, ...artifact.path.split("/"));
       mkdirSync13(dirname14(destinationPath), { recursive: true });
-      copyFileSync5(sourcePath, destinationPath);
+      copyFileSync6(sourcePath, destinationPath);
     }
     if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
     writeFileSync10(
@@ -16662,7 +16768,7 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
 // ../producer/src/services/distributed/renderChunk.ts
 import { randomBytes } from "crypto";
 import { existsSync as existsSync25, mkdirSync as mkdirSync15, readFileSync as readFileSync13, readdirSync as readdirSync10, rmSync as rmSync14, writeFileSync as writeFileSync12 } from "fs";
-import { extname as extname5, join as join37 } from "path";
+import { extname as extname6, join as join37 } from "path";
 var FFMPEG_VERSION_MISMATCH = "FFMPEG_VERSION_MISMATCH";
 var PLAN_HASH_MISMATCH = "PLAN_HASH_MISMATCH";
 var MISSING_PLAN_ARTIFACT = "MISSING_PLAN_ARTIFACT";
@@ -16757,7 +16863,7 @@ function rebuildExtractedFramesFromPlanDir(planDir, videos, indexMode = "dense-v
         `[renderChunk] planDir missing extracted video frames for ${JSON.stringify(v.videoId)}: ${outputDir} not present. plan() should have written frames here; the planDir is malformed.`
       );
     }
-    const ext = (extname5(v.framePattern) || ".jpg").toLowerCase();
+    const ext = (extname6(v.framePattern) || ".jpg").toLowerCase();
     const frames = readdirSync10(outputDir).filter((name) => name.toLowerCase().endsWith(ext)).sort((left, right) => {
       const leftNumber = frameNumberFromFileName(left);
       const rightNumber = frameNumberFromFileName(right);
@@ -16791,6 +16897,76 @@ function rebuildExtractedFramesFromPlanDir(planDir, videos, indexMode = "dense-v
   }
   return result;
 }
+function contiguousRuns(sortedIndexes) {
+  const runs = [];
+  for (const index of sortedIndexes) {
+    const last = runs[runs.length - 1];
+    if (last && last.firstFrame + last.frames === index) last.frames++;
+    else runs.push({ firstFrame: index, frames: 1 });
+  }
+  return runs;
+}
+async function extractDeferredVideoFramesForChunk(input) {
+  const deferred = input.planVideos.extracted.filter((video) => video.deferredRange);
+  if (deferred.length === 0) return [];
+  const table = createFrameLookupTable(
+    input.planVideos.videos,
+    deferred.map((video) => ({
+      ...video,
+      outputDir: input.outputRoot,
+      framePaths: new Map(Array.from({ length: video.totalFrames }, (_, i) => [i, String(i)]))
+    })),
+    resolveRenderFpsConfig(input.fps).value
+  );
+  const shown = /* @__PURE__ */ new Map();
+  for (let frame = input.slice.startFrame; frame < input.slice.endFrame; frame++) {
+    const globalTime = frame * input.fps.den / input.fps.num;
+    for (const [videoId, payload] of table.getActiveFramePayloads(globalTime)) {
+      const indexes = shown.get(videoId) ?? /* @__PURE__ */ new Set();
+      indexes.add(payload.frameIndex);
+      shown.set(videoId, indexes);
+    }
+  }
+  return Promise.all(
+    deferred.map(async (video) => {
+      const outputDir = join37(input.outputRoot, video.videoId);
+      const indexes = [...shown.get(video.videoId) ?? []].sort((a, b) => a - b);
+      if (indexes.length === 0) {
+        return { ...video, outputDir, framePaths: /* @__PURE__ */ new Map(), ownedByLookup: false };
+      }
+      const range = video.deferredRange;
+      const sourcePath = join37(input.planDir, ...range.sourcePath.split("/"));
+      if (!existsSync25(sourcePath)) {
+        throw new RenderChunkValidationError(
+          MISSING_PLAN_ARTIFACT,
+          `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
+        );
+      }
+      const extracted = await extractVideoFramesRange(
+        sourcePath,
+        video.videoId,
+        range.startTime,
+        range.durationSeconds,
+        {
+          fps: input.fps,
+          outputDir: input.outputRoot,
+          format: range.format,
+          frameRanges: contiguousRuns(indexes)
+        },
+        void 0,
+        input.cfg
+      );
+      const missing = indexes.find((index) => !extracted.framePaths.has(index));
+      if (missing !== void 0) {
+        throw new RenderChunkValidationError(
+          INVALID_VIDEO_METADATA,
+          `[renderChunk] video ${JSON.stringify(video.videoId)} has no frame ${missing}; the plan expected ${video.totalFrames} frames from ${range.sourcePath}.`
+        );
+      }
+      return { ...video, outputDir, framePaths: extracted.framePaths, ownedByLookup: false };
+    })
+  );
+}
 function hashChunkOutput(outputPath, kind) {
   if (kind === "file") return sha256Hex(readFileSync13(outputPath));
   const entries = readdirSync10(outputPath).filter((name) => /\.(png|jpg|jpeg)$/i.test(name)).sort();
@@ -16924,23 +17100,34 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       // the software-GPU clamp so buildChromeArgs includes BeginFrameControl.
       forceScreenshotExplicitlyOptedOut: !encoder.forceScreenshot
     };
+    const workDir = `${outputChunkPath}.work.${process.pid}.${randomBytes(4).toString("hex")}`;
+    mkdirSync15(workDir, { recursive: true });
+    const framesDir = join37(workDir, "captured-frames");
+    mkdirSync15(framesDir, { recursive: true });
+    const videoFramesDir = `${workDir}.video-frames`;
     const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? createFrameLookupTable(
       planVideos.videos,
-      rebuildExtractedFramesFromPlanDir(
-        planDir,
-        planVideos.extracted,
-        v2Manifest === null ? "dense-v1" : "sparse-v2"
-      ),
+      [
+        ...rebuildExtractedFramesFromPlanDir(
+          planDir,
+          planVideos.extracted.filter((video) => !video.deferredRange),
+          v2Manifest === null ? "dense-v1" : "sparse-v2"
+        ),
+        ...await extractDeferredVideoFramesForChunk({
+          planDir,
+          planVideos,
+          slice,
+          fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
+          outputRoot: videoFramesDir,
+          cfg
+        })
+      ],
       resolveRenderFpsConfig(job.config.fps).value
     ) : null;
     const createChunkVideoFrameInjector = createChunkVideoFrameInjectorFactory(videoFrameLookup);
     const videoCaptureBeyondViewport = resolveVideoCaptureBeyondViewport(
       planVideos?.videos.length ?? 0
     );
-    const workDir = `${outputChunkPath}.work.${process.pid}.${randomBytes(4).toString("hex")}`;
-    mkdirSync15(workDir, { recursive: true });
-    const framesDir = join37(workDir, "captured-frames");
-    mkdirSync15(framesDir, { recursive: true });
     const fileServer = await createFileServer({
       projectDir: compiledDir,
       compiledDir,
@@ -17217,6 +17404,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
 `, "utf-8");
     try {
       rmSync14(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      rmSync14(videoFramesDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     } catch (err) {
       log.warn("[renderChunk] failed to remove work dir", {
         workDir,