hyperframes 0.8.176 → 0.8.178

package/dist/{chunk-LEILKM2N.js → chunk-O7PFPCQF.js}

@@ -8,8 +8,9 @@ import {
   parseEncoderOptions
 } from "./chunk-KLIKCX6Q.js";
 import {
+  RENDER_TEMP_DIR,
   createStudioPositionSeekReapplyScript
-} from "./chunk-EOOEC32M.js";
+} from "./chunk-EVMY7IPL.js";
 import {
   GENERIC_FAMILIES,
   collectFontFamilyCustomProperties,
@@ -22,7 +23,7 @@ import {
   EncoderInterruptedError,
   encoderFailureError,
   prepareAnimatedGifInputs
-} from "./chunk-PL4WM5XE.js";
+} from "./chunk-FIAQ4J45.js";
 import {
   BROWSER_GPU_NOT_SOFTWARE,
   CaptureFailure,
@@ -151,7 +152,7 @@ import {
   validateEngineConfigSnapshot,
   verifyDiskDrawElementSamples,
   writeCapturedFrame
-} from "./chunk-YWSXFFO3.js";
+} from "./chunk-VU4JLRNH.js";
 import {
   assignBundledRuntimeCompositionIds,
   buildVariablesByCompScript,
@@ -164,7 +165,7 @@ import {
   isTemplateEntry,
   parsesAsScript,
   prepareFlattenedInnerRoot
-} from "./chunk-JNL3RMDG.js";
+} from "./chunk-PU33GPG4.js";
 import {
   LOW_MEMORY_TOTAL_MB_THRESHOLD,
   getCgroupMemoryLimitMb,
@@ -190,7 +191,7 @@ import {
   resolveAbsoluteMediaStartSeconds,
   resolveAuthoredTimingWindow,
   toFps
-} from "./chunk-VEQ7DKPG.js";
+} from "./chunk-AHS5QYKF.js";
 import {
   COMPOSITION_SOURCE_URL,
   HF_COLOR_GRADING_ATTR,
@@ -218,7 +219,7 @@ import {
   shouldClampResolvedMediaDuration,
   sourceTimeAt,
   styleElementsFor
-} from "./chunk-EEXE43II.js";
+} from "./chunk-PLNQW2C6.js";
 import {
   MAX_AUDIO_GAIN
 } from "./chunk-UJKQWGFF.js";
@@ -236,10 +237,10 @@ import {
 import {
   redactKnownPaths,
   redactTelemetryString
-} from "./chunk-T76PLPD6.js";
+} from "./chunk-634HSJ3J.js";
 import {
   chromeMajorCeiling
-} from "./chunk-TWWSYAKJ.js";
+} from "./chunk-537IYAEE.js";
 import {
   lintHyperframeHtml
 } from "./chunk-GK2FIKIQ.js";
@@ -1582,7 +1583,6 @@ import { hostname, uptime } from "os";
 import { dirname as dirname3, join as join4 } from "path";
 var OWNER_FILE = "owner.json";
 var TRANSACTION_BACKUP = "backup";
-var RENDER_TEMP_DIR = /^(work-[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}|hf-render|\..+\.hf-transaction)-[A-Za-z0-9]{6}$/;
 var RENDER_JOB_DIR = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
 function pidScope() {
   const attempt = (read) => {
@@ -5756,7 +5756,7 @@ function detectShaderTransitionUsage(html) {
   }
   return false;
 }
-async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log) {
+async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath) {
   let filePath = src;
   if (isHttpUrl(src)) {
     if (!existsSync9(downloadDir)) mkdirSync5(downloadDir, { recursive: true });
@@ -5770,8 +5770,9 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   } else {
     filePath = decodedUrlPath(src);
     if (!filePath.startsWith("/")) filePath = join12(baseDir, filePath);
+    filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!existsSync9(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync9(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -5834,7 +5835,7 @@ function markInferredVariableMediaDurations(html, unresolvedMedia) {
   }
   return changed ? document2.toString() : html;
 }
-async function compileHtmlFile(html, baseDir, downloadDir, log) {
+async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocalPath) {
   const { html: staticCompiled, unresolved } = compileTimingAttrs(html);
   const mediaUnresolved = unresolved.filter(
     (el) => (el.tagName === "video" || el.tagName === "audio") && el.src
@@ -5850,7 +5851,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        urlByAbsentLocalPath
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -5892,7 +5894,7 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
   compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
   return { html: compiledHtml, unresolvedCompositions };
 }
-async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set()) {
+async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set(), urlByAbsentLocalPath) {
   const subCompositions = /* @__PURE__ */ new Map();
   const { document: document2 } = parseHTML(html);
   const compEls = document2.querySelectorAll("[data-composition-src]");
@@ -5918,13 +5920,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
       const { html: compiledSub } = await compileHtmlFile(
         item.rawSubHtml,
         dirname5(item.filePath),
-        downloadDir
+        downloadDir,
+        void 0,
+        urlByAbsentLocalPath
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
-        item.nestedVisited
+        item.nestedVisited,
+        urlByAbsentLocalPath
       );
       return {
         srcPath: item.srcPath,
@@ -6682,9 +6687,16 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
     rawHtml,
     projectDir,
     downloadDir,
-    options.log
+    options.log,
+    options.urlByAbsentLocalPath
+  );
+  const { subCompositions } = await parseSubCompositions(
+    compiledHtml,
+    projectDir,
+    downloadDir,
+    void 0,
+    options.urlByAbsentLocalPath
   );
-  const { subCompositions } = await parseSubCompositions(compiledHtml, projectDir, downloadDir);
   const fullHtml = ensureFullDocument(compiledHtml);
   const inlinedHtml = inlineSubCompositions2(
     fullHtml,
@@ -7180,6 +7192,7 @@ async function runCompileStage(input) {
     allowSystemFontCapture,
     abortSignal,
     variables: input.variables,
+    urlByAbsentLocalPath: input.urlByAbsentLocalPath,
     animatedGifCacheDir: cfg.extractCacheDir ? join13(cfg.extractCacheDir, "animated-gif") : void 0,
     ffmpegProcessTimeout: cfg.ffmpegProcessTimeout
   });
@@ -8148,7 +8161,8 @@ async function runExtractVideosStage(input) {
     abortSignal,
     assertNotAborted,
     materializeSymlinks,
-    deferRangeExtraction
+    deferRangeExtraction,
+    urlByAbsentLocalPath
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -8242,7 +8256,8 @@ async function runExtractVideosStage(input) {
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
         deferRangeExtraction,
-        contentKeyedDirs: [join15(compiledDir, REMOTE_MEDIA_SUBDIR)]
+        contentKeyedDirs: [join15(compiledDir, REMOTE_MEDIA_SUBDIR)],
+        urlByAbsentLocalPath
       },
       abortSignal,
       cfg,
@@ -8320,6 +8335,7 @@ async function runAudioStage(input) {
     audioGain,
     audios,
     masterFxChain,
+    urlByAbsentLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -8339,7 +8355,7 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain },
+        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
         compiledDir
       );
     } catch (err) {
@@ -13539,6 +13555,8 @@ function buildChunkCaptureOptions(input) {
     // The controller's snapshot, so the first capture sees the in-process renderer's `__hfVariables`.
     variables: encoder.variables,
     subTimelineWaitMemo: {},
+    skipReadinessVideoIds: input.skipReadinessVideoIds,
+    videoMetadataHints: input.videoMetadataHints,
     ...videoCaptureBeyondViewport !== void 0 ? { captureBeyondViewport: videoCaptureBeyondViewport } : {},
     // A fixed warmup count keeps `beginFrameTimeTicks` host-independent.
     lockWarmupTicks: true,
@@ -13547,6 +13565,19 @@ function buildChunkCaptureOptions(input) {
 }
 async function extractDeferredVideoFramesForChunk(input) {
   const deferred = input.planVideos.extracted.filter((video) => video.deferredRange);
+  const remoteSources = input.remoteSources ?? {};
+  for (const path of Object.keys(remoteSources)) {
+    if (!deferred.some((video) => video.deferredRange.sourcePath === path)) {
+      throw new RenderChunkValidationError(
+        MISSING_PLAN_ARTIFACT,
+        `[renderChunk] ${path} is read by URL but no deferred video uses it`
+      );
+    }
+    defaultLogger.info("[renderChunk] reading video by URL", {
+      path,
+      url: remoteSources[path].split("?")[0]
+    });
+  }
   if (deferred.length === 0) return [];
   const table = createFrameLookupTable(
     input.planVideos.videos,
@@ -13574,8 +13605,9 @@ async function extractDeferredVideoFramesForChunk(input) {
         return { ...video, outputDir, framePaths: /* @__PURE__ */ new Map(), ownedByLookup: false };
       }
       const range = video.deferredRange;
-      const sourcePath = join27(input.planDir, ...range.sourcePath.split("/"));
-      if (!existsSync17(sourcePath)) {
+      const remoteUrl = remoteSources[range.sourcePath];
+      const sourcePath = remoteUrl ?? join27(input.planDir, ...range.sourcePath.split("/"));
+      if (remoteUrl === void 0 && !existsSync17(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -13915,6 +13947,16 @@ function collectPlanAssetShas(planDir, digests) {
   }
   return { compositionHtml, assets };
 }
+var PLAN_REMOTE_FILES_RELATIVE_PATH = "meta/remote-files.json";
+function writePlanRemoteFiles(planDir, files) {
+  if (files.length === 0) return;
+  const sorted = [...files].sort((a, b) => a.path < b.path ? -1 : 1);
+  writeFileSync6(join29(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH), JSON.stringify(sorted), "utf-8");
+}
+function readPlanRemoteFiles(planDir) {
+  const path = join29(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
+  return existsSync18(path) ? JSON.parse(readFileSync9(path, "utf-8")) : [];
+}
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join29(planDir, "plan.json");
   const encoderJsonPath = join29(planDir, "meta", "encoder.json");
@@ -14496,7 +14538,7 @@ function createVideoSourceShipper(input) {
     let result = null;
     for (const root of stagedRel === null ? [input.workCompiledDir, input.projectDir] : []) {
       const rel = pathInside(root, srcPath);
-      if (rel !== null && existsSync19(join31(input.planDir, "compiled", rel))) {
+      if (rel !== null && (existsSync19(join31(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
         result = ["compiled", ...rel.split(sep2)].join("/");
         break;
       }
@@ -14574,8 +14616,17 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "copy", stageStarted);
   const finalCompiledDir = join31(planDir, "compiled");
   const needsAlpha = outputNeedsAlpha(config.format);
+  const remoteFiles = Object.entries(options.remoteFiles ?? {});
+  const remoteLocalPath = (rel) => join31(projectDir, ...rel.split("/"));
+  const urlByAbsentLocalPath = new Map(
+    remoteFiles.map(([rel, file]) => [remoteLocalPath(rel), file.url])
+  );
+  const localPathByUrl = new Map(
+    remoteFiles.map(([rel, file]) => [file.url, remoteLocalPath(rel)])
+  );
   stageStarted = Date.now();
   const compileResult = await runCompileStage({
+    urlByAbsentLocalPath,
     projectDir,
     workDir,
     htmlPath,
@@ -14635,7 +14686,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-JGPFLYBL.js");
+      const { closeCaptureSession: closeCaptureSession2 } = await import("./src-XRFOS5LP.js");
       await closeCaptureSession2(probeResult.probeSession);
     } catch (err) {
       log.warn("[plan] probe session close failed", {
@@ -14663,7 +14714,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     abortSignal,
     assertNotAborted,
     materializeSymlinks: true,
-    deferRangeExtraction: options.deferVideoExtraction
+    deferRangeExtraction: options.deferVideoExtraction,
+    urlByAbsentLocalPath
   });
   logPlanStage(log, "extract", stageStarted);
   if (extractResult.failureToEnforce) throw extractResult.failureToEnforce;
@@ -14686,7 +14738,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     planDir,
     projectDir,
     workCompiledDir: compiledDir,
-    workVideoFramesDir: stagedVideoFrames
+    workVideoFramesDir: stagedVideoFrames,
+    isRemote: (srcPath) => urlByAbsentLocalPath.has(srcPath)
   });
   const sourceRoots = [
     [stagedVideoFrames, "video-frames"],
@@ -14696,17 +14749,28 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   const planVideosJson = buildPlanVideosJson({
     videos: composition.videos,
     compositionEnd: job.duration ?? Number.NaN,
-    extracted: (extractResult.extractionResult?.extracted ?? []).map((ext) => ({
-      videoId: ext.videoId,
-      srcPath: stableSourcePath(sourceRoots, ext.srcPath),
-      framePattern: ext.framePattern,
-      fps: ext.fps,
-      totalFrames: ext.totalFrames,
-      metadata: ext.metadata,
-      ...ext.deferredRange ? { deferredRange: { ...ext.deferredRange, sourcePath: shipVideoSource(ext.srcPath) } } : {}
-    }))
+    extracted: (extractResult.extractionResult?.extracted ?? []).map((ext) => {
+      const sourcePath = localPathByUrl.get(ext.srcPath) ?? ext.srcPath;
+      return {
+        videoId: ext.videoId,
+        srcPath: stableSourcePath(sourceRoots, sourcePath),
+        framePattern: ext.framePattern,
+        fps: ext.fps,
+        totalFrames: ext.totalFrames,
+        metadata: ext.metadata,
+        ...ext.deferredRange ? { deferredRange: { ...ext.deferredRange, sourcePath: shipVideoSource(sourcePath) } } : {}
+      };
+    })
   });
   mkdirSync10(join31(planDir, "meta"), { recursive: true });
+  writePlanRemoteFiles(
+    planDir,
+    remoteFiles.map(([rel, { sha256, sizeBytes }]) => ({
+      path: `compiled/${rel}`,
+      sha256,
+      sizeBytes
+    }))
+  );
   writeFileSync7(
     join31(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
     JSON.stringify(planVideosJson, null, 2),
@@ -14721,6 +14785,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
       projectDir,
       workDir,
       compiledDir: finalCompiledDir,
+      urlByAbsentLocalPath,
       duration: audioSeconds,
       ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,
       audioGain: cfg.audioGain,
@@ -16205,7 +16270,7 @@ function startServer(options = {}) {
   });
   async function shutdown(signal) {
     log.info(`Received ${signal}, shutting down`);
-    const { drainBrowserPool } = await import("./src-JGPFLYBL.js");
+    const { drainBrowserPool } = await import("./src-XRFOS5LP.js");
     await drainBrowserPool().catch(() => {
     });
     const handle = await Promise.race([
@@ -16472,17 +16537,20 @@ function artifactTargets(path, videoDependencies, chunksCarryAudio2) {
   if (path === "plan.json" || path === "meta/chunks.json" || path === "meta/encoder.json") {
     return { chunks: "all", assembler: true };
   }
-  if (path === "meta/composition.json" || path === "meta/videos.json" || path.startsWith("compiled/")) {
-    return { chunks: "all", assembler: false };
-  }
-  if (path.startsWith("video-frames/") || path.startsWith("video-sources/")) {
+  if (path.startsWith("video-frames/") || path.startsWith("video-sources/") || path.startsWith("compiled/") && videoDependencies?.has(path)) {
     return {
       chunks: videoDependencies === null ? "all" : videoDependencies.get(path) ?? [],
       assembler: false
     };
   }
+  if (path === "meta/composition.json" || path === "meta/videos.json" || path.startsWith("compiled/")) {
+    return { chunks: "all", assembler: false };
+  }
   return { chunks: "all", assembler: true };
 }
+function isPlanV2DeferredSourceArtifact(artifact) {
+  return artifact.path.startsWith("compiled/") && artifact.chunks !== "all";
+}
 function listVideoFramePaths(executionPlanDir, videos) {
   return videos.extracted.map((video) => {
     const outputDir = resolveExtractedVideoOutputDir(executionPlanDir, video.videoId);
@@ -16645,14 +16713,17 @@ function publishBlobFor(absolutePath, digests) {
   };
 }
 async function putBlobs(publisher, blobs) {
+  await putTasks(blobs.map((blob) => () => publisher.putBlob(blob)));
+}
+async function putTasks(tasks) {
   const uploadSlots = 32;
   let next = 0;
   let failure;
   const upload = async () => {
-    while (!failure && next < blobs.length) {
-      const blob = blobs[next++];
+    while (!failure && next < tasks.length) {
+      const task = tasks[next++];
       try {
-        await publisher.putBlob(blob);
+        await task();
       } catch (reason) {
         failure ??= { reason };
       }
@@ -16707,6 +16778,15 @@ function buildPlanV2Publication(executionPlanDir, digests) {
       ...targets
     });
   }
+  const storedBlobs = /* @__PURE__ */ new Map();
+  for (const remote of readPlanRemoteFiles(executionPlanDir)) {
+    const { sha256, sizeBytes } = remote;
+    if (!blobs.has(sha256)) storedBlobs.set(sha256, { sha256, sizeBytes });
+    artifacts.push({
+      ...remote,
+      ...artifactTargets(remote.path, videoDependencyPlan.dependencies, chunksCarryAudio2)
+    });
+  }
   const base = {
     protocol: PLAN_PROTOCOL_V2,
     // Retain the established manifest key byte-for-byte. It now acts as the
@@ -16728,7 +16808,8 @@ function buildPlanV2Publication(executionPlanDir, digests) {
       ...base,
       planHash: computeManifestHash(base)
     },
-    blobs: [...blobs.values()]
+    blobs: [...blobs.values()],
+    storedBlobs: [...storedBlobs.values()]
   };
 }
 function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
@@ -16736,6 +16817,9 @@ function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publication = buildPlanV2Publication(executionPlanDir);
+  if (publication.storedBlobs.length > 0) {
+    throw new PlanV2IntegrityError("a local plan v2 directory cannot reference remote files");
+  }
   mkdirSync13(dirname14(planV2Dir), { recursive: true });
   const tempDir = mkdtempSync6(join37(dirname14(planV2Dir), ".plan-v2-build-"));
   try {
@@ -16765,8 +16849,14 @@ async function publishExecutionPlan(executionPlanDir, publisher, { digests, log
     let stageStarted = Date.now();
     const publication = buildPlanV2Publication(executionPlanDir, digests);
     logPlanStage(log, "publication", stageStarted);
+    if (publication.storedBlobs.length > 0 && !publisher.referenceStoredBlob) {
+      throw new PlanV2IntegrityError("this publisher cannot reference remote files");
+    }
     stageStarted = Date.now();
-    await putBlobs(publisher, publication.blobs);
+    await putTasks([
+      ...publication.blobs.map((blob) => () => publisher.putBlob(blob)),
+      ...publication.storedBlobs.map((blob) => () => publisher.referenceStoredBlob(blob))
+    ]);
     logPlanStage(log, "upload", stageStarted);
     stageStarted = Date.now();
     await publisher.commitManifest(canonicalJsonStringify(publication.manifest));
@@ -16790,6 +16880,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
     await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
       executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER,
       deferVideoExtraction: true,
+      remoteFiles: options.remoteFiles,
       digests,
       // artifactTargets ships every compiled/ file to all chunks, so each is in the manifest.
       whileAudioMixes: () => putBlobs(
@@ -16992,14 +17083,16 @@ function verifyBlob(planV2Dir, artifact) {
   }
   return sourcePath;
 }
-function materializePlanV2Target(planV2Dir, target, destinationDir) {
+function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
   if (existsSync24(destinationDir)) {
     throw new PlanV2IntegrityError(`materialization destination already exists: ${destinationDir}`);
   }
   const manifest = readPlanV2Manifest(planV2Dir);
   const artifacts = listPlanV2ArtifactsForTarget(manifest, target);
+  const remoteSources = options.remoteSources ?? {};
+  assertRemoteSources(remoteSources, artifacts);
   const audioArtifact = artifacts.find((artifact) => isPlanAudioArtifactPath(artifact.path));
-  const verified = artifacts.map((artifact) => ({
+  const verified = artifacts.filter((artifact) => !Object.hasOwn(remoteSources, artifact.path)).map((artifact) => ({
     artifact,
     sourcePath: verifyBlob(planV2Dir, artifact)
   }));
@@ -17014,7 +17107,11 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
     if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
     writeFileSync10(
       join37(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
-      canonicalJsonStringify({ manifest, target }),
+      canonicalJsonStringify({
+        manifest,
+        target,
+        ...Object.keys(remoteSources).length > 0 ? { remoteSources } : {}
+      }),
       "utf-8"
     );
     renameSync6(tempDir, destinationDir);
@@ -17035,7 +17132,22 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
     audioPath: target.role === "assembler" ? audioArtifact ? join37(destinationDir, audioArtifact.path) : null : null
   };
 }
+function assertRemoteSources(remoteSources, artifacts) {
+  if (!isRecord3(remoteSources)) throw new PlanV2IntegrityError("remoteSources must be an object");
+  for (const [path, url] of Object.entries(remoteSources)) {
+    const artifact = artifacts.find((candidate) => candidate.path === path);
+    if (!artifact || !isPlanV2DeferredSourceArtifact(artifact)) {
+      throw new PlanV2IntegrityError(`remote source is not a selected deferred video: ${path}`);
+    }
+    if (typeof url !== "string" || !/^https?:\/\//.test(url)) {
+      throw new PlanV2IntegrityError(`remote source for ${path} must be an http(s) URL`);
+    }
+  }
+}
 function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
+  return readValidatedPlanV2Materialization(planDir, expectedTarget)?.manifest ?? null;
+}
+function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   const markerPath = join37(planDir, PLAN_V2_MATERIALIZATION_MARKER);
   if (!existsSync24(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
@@ -17050,7 +17162,10 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
   }
   const manifest = parsePlanV2Manifest(marker.manifest);
   const required = listPlanV2ArtifactsForTarget(manifest, expectedTarget);
+  const remoteSources = marker.remoteSources ?? {};
+  assertRemoteSources(remoteSources, required);
   for (const artifact of required) {
+    if (Object.hasOwn(remoteSources, artifact.path)) continue;
     const path = join37(planDir, ...artifact.path.split("/"));
     if (!existsSync24(path) || statSync9(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
@@ -17061,7 +17176,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
       throw new PlanV2IntegrityError(`materialized artifact hash mismatch: ${artifact.path}`);
     }
   }
-  return manifest;
+  return { manifest, remoteSources };
 }
 
 // ../producer/src/services/distributed/planV2Execution.ts
@@ -17909,10 +18024,12 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
   const plan2 = JSON.parse(readFileSync13(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.chunk);
   const planHashStarted = Date.now();
-  const v2Manifest = validatePlanV2MaterializedTarget(planDir, {
+  const v2Materialization = readValidatedPlanV2Materialization(planDir, {
     role: "chunk",
     chunkIndex
   });
+  const v2Manifest = v2Materialization?.manifest ?? null;
+  const remoteSources = v2Materialization?.remoteSources ?? {};
   for (const required of [encoderJsonPath, chunksJsonPath]) {
     if (!existsSync26(required)) {
       throw new RenderChunkValidationError(
@@ -18014,6 +18131,24 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     const framesDir = join40(workDir, "captured-frames");
     mkdirSync16(framesDir, { recursive: true });
     const videoFramesDir = `${workDir}.video-frames`;
+    const deferredVideoFrames = planVideos ? await extractDeferredVideoFramesForChunk({
+      planDir,
+      planVideos,
+      frames: Array.from(
+        { length: slice.endFrame - slice.startFrame },
+        (_, i) => slice.startFrame + i
+      ),
+      fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
+      outputRoot: videoFramesDir,
+      cfg,
+      remoteSources
+    }) : [];
+    const remoteVideoIds = new Set(
+      planVideos?.extracted.filter(
+        (video) => video.deferredRange && Object.hasOwn(remoteSources, video.deferredRange.sourcePath)
+      ).map((video) => video.videoId)
+    );
+    const remoteVideos = deferredVideoFrames.filter((video) => remoteVideoIds.has(video.videoId));
     const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? createFrameLookupTable(
       planVideos.videos,
       [
@@ -18022,17 +18157,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
           planVideos.extracted.filter((video) => !video.deferredRange),
           v2Manifest === null ? "dense-v1" : "sparse-v2"
         ),
-        ...await extractDeferredVideoFramesForChunk({
-          planDir,
-          planVideos,
-          frames: Array.from(
-            { length: slice.endFrame - slice.startFrame },
-            (_, i) => slice.startFrame + i
-          ),
-          fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
-          outputRoot: videoFramesDir,
-          cfg
-        })
+        ...deferredVideoFrames
       ],
       resolveRenderFpsConfig(job.config.fps).value
     ) : null;
@@ -18050,7 +18175,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       dimensions: plan2.dimensions,
       encoder,
       videoCount: planVideos?.videos.length ?? 0,
-      html: readFileSync13(join40(compiledDir, "index.html"), "utf-8")
+      html: readFileSync13(join40(compiledDir, "index.html"), "utf-8"),
+      // The plan ships a deferred source only to chunks that show it; don't wait on the rest.
+      skipReadinessVideoIds: deferredVideoFrames.filter((video) => video.framePaths.size === 0 || remoteVideoIds.has(video.videoId)).map((video) => video.videoId),
+      videoMetadataHints: collectVideoMetadataHints(remoteVideos)
     });
     const chunkWorkerCount = calculateOptimalWorkers(framesInChunk, void 0, cfg);
     let session = null;
@@ -18369,9 +18497,9 @@ async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
 }
 
 // ../producer/src/services/distributed/projectHash.ts
-import { readdirSync as readdirSync12, readFileSync as readFileSync14 } from "fs";
+import { readdirSync as readdirSync12, readFileSync as readFileSync14, realpathSync as realpathSync2, statSync as statSync11 } from "fs";
 import { createHash as createHash7 } from "crypto";
-import { join as join42, relative as relative8 } from "path";
+import { join as join42 } from "path";
 
 export {
   createConsoleLogger,