@hyperframes/producer 0.8.177 → 0.8.178

package/dist/distributed.d.ts

@@ -29,8 +29,8 @@
  * No networking, no AWS SDK, no Temporal SDK — those live in adapter
  * packages. This module is library code only.
  */
-export { buildChunkSlices, measurePlanDirBytes, plan, rejectUnsupportedDistributedFormat, resolveChunkPlan, type DistributedRenderConfig, type PlanResult, DEFAULT_CHUNK_SIZE, DEFAULT_MAX_PARALLEL_CHUNKS, MIN_CHUNK_SIZE, PLAN_DIR_SIZE_LIMIT_BYTES, PLAN_PROJECT_DIR_SKIP_SEGMENTS, CHUNK_EXCEEDS_WORKER_TIMEOUT, ChunkExceedsWorkerTimeoutError, FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED, FormatNotSupportedInDistributedError, PLAN_TOO_LARGE, PlanTooLargeError, } from "./services/distributed/plan.js";
-export { createPlanV2FromExecutionPlan, createPlanV2FromV1, getPlanV2ExecutionPlanHash, listPlanV2ArtifactsForTarget, materializePlanV2Target, planV2, planV2WithPublisher, publishPlanV2FromExecutionPlan, publishPlanV2FromV1, readPlanV2Manifest, validatePlanV2MaterializedTarget, PLAN_V2_INTEGRITY_UNRECOVERABLE, PLAN_V2_MATERIALIZATION_MARKER, PlanV2IntegrityError, type PlanV2Artifact, type PlanV2Limitations, type PlanV2Manifest, type PlanV2MaterializationResult, type PlanV2MaterializationTarget, type PlanV2Result, type PlanV2WithPublisherOptions, } from "./services/distributed/planV2.js";
+export { buildChunkSlices, measurePlanDirBytes, plan, rejectUnsupportedDistributedFormat, resolveChunkPlan, type DistributedRenderConfig, type PlanResult, type RemoteProjectFile, DEFAULT_CHUNK_SIZE, DEFAULT_MAX_PARALLEL_CHUNKS, MIN_CHUNK_SIZE, PLAN_DIR_SIZE_LIMIT_BYTES, PLAN_PROJECT_DIR_SKIP_SEGMENTS, CHUNK_EXCEEDS_WORKER_TIMEOUT, ChunkExceedsWorkerTimeoutError, FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED, FormatNotSupportedInDistributedError, PLAN_TOO_LARGE, PlanTooLargeError, } from "./services/distributed/plan.js";
+export { createPlanV2FromExecutionPlan, createPlanV2FromV1, getPlanV2ExecutionPlanHash, isPlanV2DeferredSourceArtifact, listPlanV2ArtifactsForTarget, materializePlanV2Target, planV2, planV2WithPublisher, publishPlanV2FromExecutionPlan, publishPlanV2FromV1, readPlanV2Manifest, validatePlanV2MaterializedTarget, PLAN_V2_INTEGRITY_UNRECOVERABLE, PLAN_V2_MATERIALIZATION_MARKER, PlanV2IntegrityError, type PlanV2Artifact, type PlanV2Limitations, type PlanV2Manifest, type PlanV2MaterializeOptions, type PlanV2MaterializationResult, type PlanV2MaterializationTarget, type PlanV2RemoteSources, type PlanV2Result, type PlanV2WithPublisherOptions, } from "./services/distributed/planV2.js";
 export { LocalPlanV2ArtifactPublisher, type LocalPlanV2ArtifactPublisherOptions, type PlanV2ArtifactPublisher, type PlanV2PublishBlob, } from "./services/distributed/planV2Publisher.js";
 export { assembleV2, renderChunkV2 } from "./services/distributed/planV2Execution.js";
 export { applyRuntimeEnvSnapshot, readWebGlVendorInfoFromCanvas, renderChunk, type ChunkRenderer, type ChunkResult, type EffectiveChunkResult, FFMPEG_VERSION_MISMATCH, INVALID_VIDEO_METADATA, PLAN_HASH_MISMATCH, RenderChunkValidationError, } from "./services/distributed/renderChunk.js";
@@ -38,7 +38,7 @@ export { assemble, chunksAreStitchedMp4, type AssembleResult, } from "./services
 export { muxChunkWithAudio } from "./services/distributed/chunkAudio.js";
 export { buildStitchedHeader, readMp4Layout, type Mp4Layout, type ReadRange, } from "./services/distributed/mp4Stitch.js";
 export { InvalidConfigError, type SerializableDistributedRenderConfig, validateDistributedRenderConfig, validateVariablesPayload, } from "./services/distributed/renderConfigValidation.js";
-export { hashProjectDir } from "./services/distributed/projectHash.js";
+export { hashProjectDir, listSiteFiles } from "./services/distributed/projectHash.js";
 export { CURRENT_PLAN_PROTOCOL, DISTRIBUTED_RENDER_CAPABILITIES, getDistributedRenderCapabilities, PLAN_ARTIFACT_LAYOUT, PLAN_HASH_SCHEMA, PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2, PLAN_PROTOCOL_UNSUPPORTED, PLAN_SCHEMA_VERSION, PLAN_V2_ARTIFACT_LAYOUT, PLAN_V2_HASH_SCHEMA, PLAN_V2_SCHEMA_VERSION, PlanProtocolUnsupportedError, readPlanProtocol, readPlanProtocolV1, type DistributedRenderCapabilities, type PlanProtocolConsumerCapabilities, type PlanProtocolDescriptor, type PlanProtocolV1Descriptor, type PlanProtocolV2Descriptor, type SupportedPlanProtocolDescriptor, } from "./services/distributed/planProtocol.js";
 export { PlanVideosMetadataError, type DistributedFormat } from "./services/distributed/shared.js";
 export { isPlanAudioArtifactPath, PLAN_AUDIO_LEGACY_RELATIVE_PATH, PLAN_AUDIO_RELATIVE_PATH, resolvePlanAudioPath, } from "./services/distributed/shared.js";

package/dist/distributed.js

@@ -1148,6 +1148,9 @@ import {
   extractAudioMetadata
 } from "@hyperframes/engine";
 
+// src/services/render/renderDirOwner.ts
+import { RENDER_TEMP_DIR } from "@hyperframes/core/project-folders";
+
 // src/services/render/capturePlan.ts
 function assertWorkerCount(workerCount) {
   if (!Number.isInteger(workerCount) || workerCount < 1) {
@@ -2337,7 +2340,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 (!existsSync6(downloadDir)) mkdirSync4(downloadDir, { recursive: true });
@@ -2351,8 +2354,9 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
   } else {
     filePath = decodedUrlPath(src);
     if (!filePath.startsWith("/")) filePath = join5(baseDir, filePath);
+    filePath = urlByAbsentLocalPath?.get(filePath) ?? filePath;
   }
-  if (!existsSync6(filePath)) {
+  if (!isHttpUrl(filePath) && !existsSync6(filePath)) {
     return { duration: null, resolvedPath: filePath };
   }
   const withSrcContext = (error) => {
@@ -2415,7 +2419,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
@@ -2431,7 +2435,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log) {
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        urlByAbsentLocalPath
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -2473,7 +2478,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]");
@@ -2499,13 +2504,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
       const { html: compiledSub } = await compileHtmlFile(
         item.rawSubHtml,
         dirname4(item.filePath),
-        downloadDir
+        downloadDir,
+        void 0,
+        urlByAbsentLocalPath
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
-        item.nestedVisited
+        item.nestedVisited,
+        urlByAbsentLocalPath
       );
       return {
         srcPath: item.srcPath,
@@ -3263,9 +3271,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,
@@ -3761,6 +3776,7 @@ async function runCompileStage(input) {
     allowSystemFontCapture,
     abortSignal,
     variables: input.variables,
+    urlByAbsentLocalPath: input.urlByAbsentLocalPath,
     animatedGifCacheDir: cfg.extractCacheDir ? join6(cfg.extractCacheDir, "animated-gif") : void 0,
     ffmpegProcessTimeout: cfg.ffmpegProcessTimeout
   });
@@ -4759,7 +4775,8 @@ async function runExtractVideosStage(input) {
     abortSignal,
     assertNotAborted,
     materializeSymlinks,
-    deferRangeExtraction
+    deferRangeExtraction,
+    urlByAbsentLocalPath
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -4853,7 +4870,8 @@ async function runExtractVideosStage(input) {
         maxTransientRetries: extractionPolicy.maxTransientRetries,
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
         deferRangeExtraction,
-        contentKeyedDirs: [join8(compiledDir, REMOTE_MEDIA_SUBDIR)]
+        contentKeyedDirs: [join8(compiledDir, REMOTE_MEDIA_SUBDIR)],
+        urlByAbsentLocalPath
       },
       abortSignal,
       cfg,
@@ -4936,6 +4954,7 @@ async function runAudioStage(input) {
     audioGain,
     audios,
     masterFxChain,
+    urlByAbsentLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -4955,7 +4974,7 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain },
+        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
         compiledDir
       );
     } catch (err) {
@@ -6833,6 +6852,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,
@@ -6841,6 +6862,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,
@@ -6868,8 +6902,9 @@ async function extractDeferredVideoFramesForChunk(input) {
         return { ...video, outputDir, framePaths: /* @__PURE__ */ new Map(), ownedByLookup: false };
       }
       const range = video.deferredRange;
-      const sourcePath = join16(input.planDir, ...range.sourcePath.split("/"));
-      if (!existsSync12(sourcePath)) {
+      const remoteUrl = remoteSources[range.sourcePath];
+      const sourcePath = remoteUrl ?? join16(input.planDir, ...range.sourcePath.split("/"));
+      if (remoteUrl === void 0 && !existsSync12(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -7209,6 +7244,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);
+  writeFileSync4(join18(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH), JSON.stringify(sorted), "utf-8");
+}
+function readPlanRemoteFiles(planDir) {
+  const path = join18(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
+  return existsSync13(path) ? JSON.parse(readFileSync8(path, "utf-8")) : [];
+}
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join18(planDir, "plan.json");
   const encoderJsonPath = join18(planDir, "meta", "encoder.json");
@@ -7794,7 +7839,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 && existsSync14(join20(input.planDir, "compiled", rel))) {
+      if (rel !== null && (existsSync14(join20(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
         result = ["compiled", ...rel.split(sep2)].join("/");
         break;
       }
@@ -7872,8 +7917,17 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "copy", stageStarted);
   const finalCompiledDir = join20(planDir, "compiled");
   const needsAlpha = outputNeedsAlpha(config.format);
+  const remoteFiles = Object.entries(options.remoteFiles ?? {});
+  const remoteLocalPath = (rel) => join20(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,
@@ -7961,7 +8015,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;
@@ -7984,7 +8039,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"],
@@ -7994,17 +8050,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) } } : {}
+      };
+    })
   });
   mkdirSync8(join20(planDir, "meta"), { recursive: true });
+  writePlanRemoteFiles(
+    planDir,
+    remoteFiles.map(([rel, { sha256, sizeBytes }]) => ({
+      path: `compiled/${rel}`,
+      sha256,
+      sizeBytes
+    }))
+  );
   writeFileSync5(
     join20(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
     JSON.stringify(planVideosJson, null, 2),
@@ -8019,6 +8086,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
       projectDir,
       workDir,
       compiledDir: finalCompiledDir,
+      urlByAbsentLocalPath,
       duration: audioSeconds,
       ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,
       audioGain: cfg.audioGain,
@@ -8428,17 +8496,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);
@@ -8601,14 +8672,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 };
       }
@@ -8663,6 +8737,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
@@ -8684,7 +8767,8 @@ function buildPlanV2Publication(executionPlanDir, digests) {
       ...base,
       planHash: computeManifestHash(base)
     },
-    blobs: [...blobs.values()]
+    blobs: [...blobs.values()],
+    storedBlobs: [...storedBlobs.values()]
   };
 }
 function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
@@ -8692,6 +8776,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");
+  }
   mkdirSync10(dirname10(planV2Dir), { recursive: true });
   const tempDir = mkdtempSync4(join23(dirname10(planV2Dir), ".plan-v2-build-"));
   try {
@@ -8721,8 +8808,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));
@@ -8746,6 +8839,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(
@@ -8948,14 +9042,16 @@ function verifyBlob(planV2Dir, artifact) {
   }
   return sourcePath;
 }
-function materializePlanV2Target(planV2Dir, target, destinationDir) {
+function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
   if (existsSync16(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)
   }));
@@ -8970,7 +9066,11 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
     if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
     writeFileSync7(
       join23(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
-      canonicalJsonStringify({ manifest, target }),
+      canonicalJsonStringify({
+        manifest,
+        target,
+        ...Object.keys(remoteSources).length > 0 ? { remoteSources } : {}
+      }),
       "utf-8"
     );
     renameSync5(tempDir, destinationDir);
@@ -8991,7 +9091,22 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
     audioPath: target.role === "assembler" ? audioArtifact ? join23(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 = join23(planDir, PLAN_V2_MATERIALIZATION_MARKER);
   if (!existsSync16(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
@@ -9006,7 +9121,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 = join23(planDir, ...artifact.path.split("/"));
     if (!existsSync16(path) || statSync6(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
@@ -9017,7 +9135,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
       throw new PlanV2IntegrityError(`materialized artifact hash mismatch: ${artifact.path}`);
     }
   }
-  return manifest;
+  return { manifest, remoteSources };
 }
 
 // src/services/distributed/planV2Execution.ts
@@ -9892,10 +10010,12 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
   const plan2 = JSON.parse(readFileSync11(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 (!existsSync18(required)) {
       throw new RenderChunkValidationError(
@@ -9997,6 +10117,24 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     const framesDir = join26(workDir, "captured-frames");
     mkdirSync13(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,
       [
@@ -10005,17 +10143,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;
@@ -10033,7 +10161,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       dimensions: plan2.dimensions,
       encoder,
       videoCount: planVideos?.videos.length ?? 0,
-      html: readFileSync11(join26(compiledDir, "index.html"), "utf-8")
+      html: readFileSync11(join26(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;
@@ -10594,28 +10725,46 @@ function validateIntDimension(field, value) {
 }
 
 // src/services/distributed/projectHash.ts
-import { readdirSync as readdirSync10, readFileSync as readFileSync12 } from "node:fs";
+import { readdirSync as readdirSync10, readFileSync as readFileSync12, realpathSync as realpathSync2, statSync as statSync8 } from "node:fs";
 import { createHash as createHash6 } from "node:crypto";
-import { join as join28, relative as relative7 } from "node:path";
-function hashProjectDir(projectDir) {
-  const hash = createHash6("sha256");
+import { join as join28 } from "node:path";
+var SITE_ID_SCHEME = "site-v2\0";
+function listSiteFiles(projectDir) {
   const files = [];
-  function walk(dir, isRoot) {
-    for (const entry of readdirSync10(dir, { withFileTypes: true }).sort(
-      (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
-    )) {
-      if (isRoot && PLAN_PROJECT_DIR_SKIP_SEGMENTS.has(entry.name)) continue;
-      const full = join28(dir, entry.name);
-      if (entry.isDirectory()) walk(full, false);
-      else if (entry.isFile()) files.push(full);
+  const ancestors = /* @__PURE__ */ new Set([realpathSync2(projectDir)]);
+  function walk(dir, rel) {
+    for (const name of readdirSync10(dir).sort()) {
+      if (rel === "" && PLAN_PROJECT_DIR_SKIP_SEGMENTS.has(name)) continue;
+      const full = join28(dir, name);
+      const relPath = rel === "" ? name : `${rel}/${name}`;
+      let stat;
+      try {
+        stat = statSync8(full);
+      } catch (err) {
+        throw new Error(`[listSiteFiles] cannot read ${relPath} (dangling symlink?)`, {
+          cause: err
+        });
+      }
+      if (stat.isFile()) {
+        files.push(relPath);
+      } else if (stat.isDirectory()) {
+        const real = realpathSync2(full);
+        if (ancestors.has(real)) continue;
+        ancestors.add(real);
+        walk(full, relPath);
+        ancestors.delete(real);
+      }
     }
   }
-  walk(projectDir, true);
-  for (const file of files) {
-    const rel = relative7(projectDir, file).replaceAll("\\", "/");
+  walk(projectDir, "");
+  return files;
+}
+function hashProjectDir(projectDir, files = listSiteFiles(projectDir)) {
+  const hash = createHash6("sha256").update(SITE_ID_SCHEME);
+  for (const rel of files) {
     hash.update(rel);
     hash.update("\0");
-    hash.update(readFileSync12(file));
+    hash.update(readFileSync12(join28(projectDir, rel)));
   }
   return hash.digest("hex").slice(0, 16);
 }
@@ -10670,7 +10819,9 @@ export {
   getPlanV2ExecutionPlanHash,
   hashProjectDir,
   isPlanAudioArtifactPath,
+  isPlanV2DeferredSourceArtifact,
   listPlanV2ArtifactsForTarget,
+  listSiteFiles,
   materializePlanV2Target,
   measurePlanDirBytes,
   muxChunkWithAudio,

package/dist/hyperframe.manifest.json

@@ -1,7 +1,7 @@
 {
   "version": "0.1.0",
   "buildId": "dev",
-  "sha256": "231daa3aea863ffab8c1794254a07a9cfb36cbd599b0c8c7d4cb05a96818299b",
+  "sha256": "5da92c0e03e3d47df672f23707742908357e94fb7b39ed0f518d4c37400f433d",
   "artifacts": {
     "iife": "hyperframe.runtime.iife.js",
     "esm": "hyperframe.runtime.mjs"