@hyperframes/producer 0.8.176 → 0.8.178

package/dist/index.js

@@ -1387,9 +1387,9 @@ import {
 } from "node:fs";
 import { hostname, uptime } from "node:os";
 import { dirname as dirname3, join as join4 } from "node:path";
+import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders";
 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) => {
@@ -6067,7 +6067,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 (!existsSync10(downloadDir)) mkdirSync6(downloadDir, { recursive: true });
@@ -6081,8 +6081,9 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   } else {
     filePath = decodedUrlPath(src);
     if (!filePath.startsWith("/")) filePath = join13(baseDir, filePath);
+    filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!existsSync10(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync10(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -6145,7 +6146,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
@@ -6161,7 +6162,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        urlByAbsentLocalPath
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -6203,7 +6205,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 } = parseHTML4(html);
   const compEls = document2.querySelectorAll("[data-composition-src]");
@@ -6229,13 +6231,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
       const { html: compiledSub } = await compileHtmlFile(
         item.rawSubHtml,
         dirname6(item.filePath),
-        downloadDir
+        downloadDir,
+        void 0,
+        urlByAbsentLocalPath
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
-        item.nestedVisited
+        item.nestedVisited,
+        urlByAbsentLocalPath
       );
       return {
         srcPath: item.srcPath,
@@ -6993,9 +6998,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 = inlineSubCompositions(
     fullHtml,
@@ -7491,6 +7503,7 @@ async function runCompileStage(input) {
     allowSystemFontCapture,
     abortSignal,
     variables: input.variables,
+    urlByAbsentLocalPath: input.urlByAbsentLocalPath,
     animatedGifCacheDir: cfg.extractCacheDir ? join14(cfg.extractCacheDir, "animated-gif") : void 0,
     ffmpegProcessTimeout: cfg.ffmpegProcessTimeout
   });
@@ -8489,7 +8502,8 @@ async function runExtractVideosStage(input) {
     abortSignal,
     assertNotAborted,
     materializeSymlinks,
-    deferRangeExtraction
+    deferRangeExtraction,
+    urlByAbsentLocalPath
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -8583,7 +8597,8 @@ async function runExtractVideosStage(input) {
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
         deferRangeExtraction,
-        contentKeyedDirs: [join16(compiledDir, REMOTE_MEDIA_SUBDIR)]
+        contentKeyedDirs: [join16(compiledDir, REMOTE_MEDIA_SUBDIR)],
+        urlByAbsentLocalPath
       },
       abortSignal,
       cfg,
@@ -8666,6 +8681,7 @@ async function runAudioStage(input) {
     audioGain,
     audios,
     masterFxChain,
+    urlByAbsentLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -8685,7 +8701,7 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain },
+        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
         compiledDir
       );
     } catch (err) {
@@ -13990,6 +14006,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,
@@ -13998,6 +14016,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 = createFrameLookupTable2(
     input.planVideos.videos,
@@ -14025,8 +14056,9 @@ async function extractDeferredVideoFramesForChunk(input) {
         return { ...video, outputDir, framePaths: /* @__PURE__ */ new Map(), ownedByLookup: false };
       }
       const range = video.deferredRange;
-      const sourcePath = join28(input.planDir, ...range.sourcePath.split("/"));
-      if (!existsSync18(sourcePath)) {
+      const remoteUrl = remoteSources[range.sourcePath];
+      const sourcePath = remoteUrl ?? join28(input.planDir, ...range.sourcePath.split("/"));
+      if (remoteUrl === void 0 && !existsSync18(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -14366,6 +14398,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(join30(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH), JSON.stringify(sorted), "utf-8");
+}
+function readPlanRemoteFiles(planDir) {
+  const path = join30(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
+  return existsSync19(path) ? JSON.parse(readFileSync10(path, "utf-8")) : [];
+}
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join30(planDir, "plan.json");
   const encoderJsonPath = join30(planDir, "meta", "encoder.json");
@@ -14947,7 +14989,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 && existsSync20(join32(input.planDir, "compiled", rel))) {
+      if (rel !== null && (existsSync20(join32(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
         result = ["compiled", ...rel.split(sep2)].join("/");
         break;
       }
@@ -15025,8 +15067,17 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "copy", stageStarted);
   const finalCompiledDir = join32(planDir, "compiled");
   const needsAlpha = outputNeedsAlpha(config.format);
+  const remoteFiles = Object.entries(options.remoteFiles ?? {});
+  const remoteLocalPath = (rel) => join32(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,
@@ -15114,7 +15165,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;
@@ -15137,7 +15189,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"],
@@ -15147,17 +15200,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) } } : {}
+      };
+    })
   });
   mkdirSync11(join32(planDir, "meta"), { recursive: true });
+  writePlanRemoteFiles(
+    planDir,
+    remoteFiles.map(([rel, { sha256, sizeBytes }]) => ({
+      path: `compiled/${rel}`,
+      sha256,
+      sizeBytes
+    }))
+  );
   writeFileSync7(
     join32(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
     JSON.stringify(planVideosJson, null, 2),
@@ -15172,6 +15236,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
       projectDir,
       workDir,
       compiledDir: finalCompiledDir,
+      urlByAbsentLocalPath,
       duration: audioSeconds,
       ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,
       audioGain: cfg.audioGain,
@@ -16966,17 +17031,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);
@@ -17139,14 +17207,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 };
       }
@@ -17201,6 +17272,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
@@ -17222,7 +17302,8 @@ function buildPlanV2Publication(executionPlanDir, digests) {
       ...base,
       planHash: computeManifestHash(base)
     },
-    blobs: [...blobs.values()]
+    blobs: [...blobs.values()],
+    storedBlobs: [...storedBlobs.values()]
   };
 }
 function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
@@ -17230,6 +17311,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");
+  }
   mkdirSync14(dirname15(planV2Dir), { recursive: true });
   const tempDir = mkdtempSync6(join38(dirname15(planV2Dir), ".plan-v2-build-"));
   try {
@@ -17259,8 +17343,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));
@@ -17284,6 +17374,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(
@@ -17486,14 +17577,16 @@ function verifyBlob(planV2Dir, artifact) {
   }
   return sourcePath;
 }
-function materializePlanV2Target(planV2Dir, target, destinationDir) {
+function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
   if (existsSync25(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)
   }));
@@ -17508,7 +17601,11 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
     if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
     writeFileSync10(
       join38(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
-      canonicalJsonStringify({ manifest, target }),
+      canonicalJsonStringify({
+        manifest,
+        target,
+        ...Object.keys(remoteSources).length > 0 ? { remoteSources } : {}
+      }),
       "utf-8"
     );
     renameSync7(tempDir, destinationDir);
@@ -17529,7 +17626,22 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
     audioPath: target.role === "assembler" ? audioArtifact ? join38(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 = join38(planDir, PLAN_V2_MATERIALIZATION_MARKER);
   if (!existsSync25(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
@@ -17544,7 +17656,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 = join38(planDir, ...artifact.path.split("/"));
     if (!existsSync25(path) || statSync10(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
@@ -17555,7 +17670,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
       throw new PlanV2IntegrityError(`materialized artifact hash mismatch: ${artifact.path}`);
     }
   }
-  return manifest;
+  return { manifest, remoteSources };
 }
 
 // src/services/distributed/planV2Execution.ts
@@ -18430,10 +18545,12 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
   const plan2 = JSON.parse(readFileSync14(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 (!existsSync27(required)) {
       throw new RenderChunkValidationError(
@@ -18535,6 +18652,24 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     const framesDir = join41(workDir, "captured-frames");
     mkdirSync17(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 ? createFrameLookupTable5(
       planVideos.videos,
       [
@@ -18543,17 +18678,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;
@@ -18571,7 +18696,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       dimensions: plan2.dimensions,
       encoder,
       videoCount: planVideos?.videos.length ?? 0,
-      html: readFileSync14(join41(compiledDir, "index.html"), "utf-8")
+      html: readFileSync14(join41(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 = calculateOptimalWorkers2(framesInChunk, void 0, cfg);
     let session = null;

package/dist/public-server.js

@@ -1407,9 +1407,9 @@ import {
 } from "node:fs";
 import { hostname, uptime } from "node:os";
 import { dirname as dirname3, join as join4 } from "node:path";
+import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders";
 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}$/;
 function pidScope() {
   const attempt = (read) => {
     try {
@@ -6086,7 +6086,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 (!existsSync10(downloadDir)) mkdirSync6(downloadDir, { recursive: true });
@@ -6100,8 +6100,9 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   } else {
     filePath = decodedUrlPath(src);
     if (!filePath.startsWith("/")) filePath = join13(baseDir, filePath);
+    filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!existsSync10(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync10(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -6164,7 +6165,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
@@ -6180,7 +6181,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        urlByAbsentLocalPath
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -6222,7 +6224,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 } = parseHTML4(html);
   const compEls = document2.querySelectorAll("[data-composition-src]");
@@ -6248,13 +6250,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
       const { html: compiledSub } = await compileHtmlFile(
         item.rawSubHtml,
         dirname6(item.filePath),
-        downloadDir
+        downloadDir,
+        void 0,
+        urlByAbsentLocalPath
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
-        item.nestedVisited
+        item.nestedVisited,
+        urlByAbsentLocalPath
       );
       return {
         srcPath: item.srcPath,
@@ -7012,9 +7017,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 = inlineSubCompositions(
     fullHtml,
@@ -7510,6 +7522,7 @@ async function runCompileStage(input) {
     allowSystemFontCapture,
     abortSignal,
     variables: input.variables,
+    urlByAbsentLocalPath: input.urlByAbsentLocalPath,
     animatedGifCacheDir: cfg.extractCacheDir ? join14(cfg.extractCacheDir, "animated-gif") : void 0,
     ffmpegProcessTimeout: cfg.ffmpegProcessTimeout
   });
@@ -8472,7 +8485,8 @@ async function runExtractVideosStage(input) {
     abortSignal,
     assertNotAborted,
     materializeSymlinks,
-    deferRangeExtraction
+    deferRangeExtraction,
+    urlByAbsentLocalPath
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -8566,7 +8580,8 @@ async function runExtractVideosStage(input) {
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
         deferRangeExtraction,
-        contentKeyedDirs: [join16(compiledDir, REMOTE_MEDIA_SUBDIR)]
+        contentKeyedDirs: [join16(compiledDir, REMOTE_MEDIA_SUBDIR)],
+        urlByAbsentLocalPath
       },
       abortSignal,
       cfg,
@@ -8649,6 +8664,7 @@ async function runAudioStage(input) {
     audioGain,
     audios,
     masterFxChain,
+    urlByAbsentLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -8668,7 +8684,7 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain },
+        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
         compiledDir
       );
     } catch (err) {