@hyperframes/producer 0.8.224 → 0.8.226

package/dist/public-server.js

@@ -2,7 +2,7 @@
 
 // src/server.ts
 import {
-  existsSync as existsSync19,
+  existsSync as existsSync20,
   mkdirSync as mkdirSync11,
   statSync as statSync10,
   mkdtempSync as mkdtempSync4,
@@ -22,9 +22,8 @@ import { fetchPublicHttpsText as fetchPublicHttpsText2 } from "@hyperframes/engi
 // src/services/renderOrchestrator.ts
 import { audioFailureDiagnostics as audioFailureDiagnostics2 } from "@hyperframes/engine";
 import {
-  existsSync as existsSync16,
+  existsSync as existsSync17,
   mkdirSync as mkdirSync10,
-  readFileSync as readFileSync9,
   readdirSync as readdirSync5,
   rmSync as rmSync10,
   statSync as statSync8,
@@ -45,6 +44,7 @@ import {
 import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
 import { extractStandaloneEntryFromIndex, isTemplateEntry } from "@hyperframes/core/compiler";
 import { HTML_BODY_CSS_HEIGHT_FIRST_RE, HTML_BODY_CSS_WIDTH_FIRST_RE } from "@hyperframes/parsers";
+import { readTextFile as readTextFile2 } from "@hyperframes/parsers/asset-resolution";
 import {
   extractMediaMetadata as extractMediaMetadata4,
   resolveConfig as resolveConfig2,
@@ -2151,6 +2151,14 @@ function pushWorkerDedupPerfs(results, sink) {
     if (r.perf) sink.push(r.perf);
   }
 }
+function capturedBeyondViewport(perfs, fallback) {
+  const used = perfs.flatMap((perf) => perf.captureBeyondViewport ?? []);
+  return used.length > 0 ? used.includes(true) : fallback;
+}
+function withCapturedBeyondViewport(capture, perfs) {
+  const used = capturedBeyondViewport(perfs, capture.captureBeyondViewport);
+  return used === void 0 ? capture : { ...capture, captureBeyondViewport: used };
+}
 function pushWorkerPageErrors(results, sink) {
   for (const result of results) {
     for (const line of result.pageErrorLines ?? []) if (!sink.includes(line)) sink.push(line);
@@ -5783,7 +5791,7 @@ import { suggestMatchingPreset } from "@hyperframes/core";
 // src/services/htmlCompiler.ts
 import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
 import { createHash as createHash6 } from "node:crypto";
-import { createReadStream as createReadStream2, existsSync as existsSync10, mkdirSync as mkdirSync7, readFileSync as readFileSync7 } from "fs";
+import { createReadStream as createReadStream2, existsSync as existsSync10, mkdirSync as mkdirSync7 } from "fs";
 import { join as join15, dirname as dirname7, resolve as resolve7, basename as basename4, relative as relative2 } from "path";
 import { parseHTML as parseHTML5 } from "linkedom";
 import {
@@ -5836,7 +5844,8 @@ import {
 } from "@hyperframes/parsers/sub-composition-validity";
 import {
   isUnresolvedAssetPlaceholder,
-  readProjectFile
+  readProjectFile,
+  readTextFile
 } from "@hyperframes/parsers/asset-resolution";
 
 // src/services/renderMediaCollector.ts
@@ -7925,11 +7934,7 @@ function rebaseDirectEntryAssetPaths(html, projectDir, htmlPath) {
   return document2.toString();
 }
 async function compileForRender(projectDir, htmlPath, downloadDir, options = {}) {
-  const entryHtml = rebaseDirectEntryAssetPaths(
-    readFileSync7(htmlPath, "utf-8"),
-    projectDir,
-    htmlPath
-  );
+  const entryHtml = rebaseDirectEntryAssetPaths(readTextFile(htmlPath), projectDir, htmlPath);
   const rawHtml = rewriteUnresolvableGsapToCdn(entryHtml, projectDir);
   assertSubCompositionsUsable(rawHtml, projectDir);
   const probes = /* @__PURE__ */ new Map();
@@ -8780,7 +8785,7 @@ async function runProbeStage(input) {
   );
   const hasVariableMedia = hasVariableBoundMedia(compiled.html, job.config.variables);
   const hasInsertedMedia = hasRuntimeMediaChanges(compiled.html);
-  const needsBrowser = probeRequiresBrowser({
+  const needsBrowser = cfg.videoLayerPassthrough || probeRequiresBrowser({
     durationSeconds: composition.duration,
     unresolvedCompositionCount: compiled.unresolvedCompositions.length,
     hasAutoStart,
@@ -9380,17 +9385,23 @@ function resolveVideoExtractionPolicy(env = process.env) {
   const maxTransientRetries = failureMode !== "off" && env.HF_VIDEO_EXTRACTION_MAX_RETRIES?.trim() === "1" ? 1 : 0;
   return { failureMode, maxTransientRetries };
 }
+var MAX_NAMED_SOURCES = 5;
 var VideoExtractionStageError = class extends Error {
   constructor(code, retryable, failures, extractionFailure = buildExtractionFailureMetadata(
     failures.map((failure) => ({
       kind: failure.kind,
       affectedElementCount: failure.count
     }))
-  ), ffmpegReason) {
+  ), ffmpegReason, sources = []) {
     const total = failures.reduce((sum, failure) => sum + failure.count, 0);
     const breakdown = failures.map((failure) => `${failure.kind}=${failure.count}`).join(",");
     const reason = ffmpegReason ? `: ffmpeg said: ${ffmpegReason}` : "";
-    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]${reason}`);
+    const shown = sources.slice(0, MAX_NAMED_SOURCES).join(", ");
+    const more = sources.length > MAX_NAMED_SOURCES ? ` and ${sources.length - MAX_NAMED_SOURCES} more` : "";
+    const files = sources.length > 0 ? ` (${shown}${more})` : "";
+    super(
+      `Video extraction failed for ${total} source(s) [${code}; ${breakdown}]${files}${reason}`
+    );
     this.code = code;
     this.retryable = retryable;
     this.failures = failures;
@@ -9433,7 +9444,10 @@ function buildVideoExtractionStageError(result) {
     retryable,
     failures,
     extractionFailureMetadataFromResult(result),
-    result.errors.find((failure) => failure.ffmpegReason)?.ffmpegReason
+    result.errors.find((failure) => failure.ffmpegReason)?.ffmpegReason,
+    [
+      ...new Set(result.errors.flatMap((failure) => failure.source ? [failure.source] : []))
+    ].sort()
   );
 }
 function buildHdrProbeStageError(failures) {
@@ -9512,7 +9526,8 @@ async function runExtractVideosStage(input) {
     assertNotAborted,
     materializeSymlinks,
     deferRangeExtraction,
-    urlByAbsentLocalPath
+    urlByAbsentLocalPath,
+    skipFrameExtractionIds = []
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -9583,7 +9598,10 @@ async function runExtractVideosStage(input) {
     );
     imageColorSpaces.push(...probed);
   }
-  if (composition.videos.length > 0) {
+  if (skipFrameExtractionIds.length > 0) {
+    await appendVideoAudioFromProbe({ projectDir, compiledDir, composition, urlByAbsentLocalPath });
+    videoReadinessSkipIds = [...skipFrameExtractionIds];
+  } else if (composition.videos.length > 0) {
     const totalVideos = composition.videos.length;
     for (let i = 0; i < totalVideos; i++) {
       const v = composition.videos[i];
@@ -9679,6 +9697,116 @@ function appendAutoDetectedVideoAudio(composition, extracted) {
     existingAudioSrcs.add(video.src);
   }
 }
+async function appendVideoAudioFromProbe(input) {
+  const { projectDir, compiledDir, composition, urlByAbsentLocalPath } = input;
+  const videos = composition.videos.filter(
+    (video) => !isVideoPastTimelineEnd(video, composition.duration)
+  );
+  const probed = await Promise.all(
+    videos.map(async (video) => {
+      const path = isHttpUrl2(video.src) ? video.src : resolveProjectRelativeSrc3(video.src, projectDir, compiledDir);
+      const readFrom = urlByAbsentLocalPath?.get(path) ?? path;
+      if (!isHttpUrl2(readFrom) && !existsSync11(readFrom)) return null;
+      const metadata = await extractMediaMetadata3(readFrom);
+      const window2 = await resolveFinalFrameExtractionWindow2(
+        readFrom,
+        video,
+        metadata,
+        resolveVideoExtractionWindow2(video, metadata, composition.duration)
+      );
+      if (window2.durationSeconds <= 0) return null;
+      rebaseVideoToWindow(video, window2);
+      return { videoId: video.id, metadata };
+    })
+  );
+  appendAutoDetectedVideoAudio(
+    composition,
+    probed.filter((entry) => entry !== null)
+  );
+}
+
+// src/services/render/videoLayerPassthroughPlan.ts
+import { existsSync as existsSync12 } from "node:fs";
+import {
+  buildVideoLayerInput,
+  isHttpUrl as isHttpUrl3,
+  qualifyVideoLayer,
+  resolveProjectRelativeSrc as resolveProjectRelativeSrc4
+} from "@hyperframes/engine";
+var SAMPLES = 9;
+function inspectVideoLayout(id, w, h, time) {
+  window.__hf?.seek?.(time);
+  const video = document.getElementById(id);
+  if (!video) return { reason: "video_missing" };
+  const r = video.getBoundingClientRect();
+  if (Math.abs(r.left) > 0.5 || Math.abs(r.top) > 0.5) return { reason: "not_full_canvas" };
+  if (Math.abs(r.width - w) > 0.5 || Math.abs(r.height - h) > 0.5) {
+    return { reason: "not_full_canvas" };
+  }
+  const painted = (s) => s.backgroundColor !== "" && s.backgroundColor !== "transparent" && s.backgroundColor !== "rgba(0, 0, 0, 0)" || s.backgroundImage !== "" && s.backgroundImage !== "none";
+  for (let e = video; e && e !== document.documentElement; ) {
+    const s = getComputedStyle(e);
+    if (s.opacity !== "1") return { reason: "opacity" };
+    if (s.transform !== "none" || s.filter !== "none") return { reason: "transform_or_filter" };
+    if (s.clipPath !== "none" || s.maskImage !== "none") return { reason: "clip_or_mask" };
+    if (s.mixBlendMode !== "normal") return { reason: "blend_mode" };
+    if (s.visibility !== "visible" || s.display === "none") return { reason: "not_shown" };
+    const cleared = e === document.body || e.hasAttribute("data-composition-id");
+    if (e !== video && painted(s) && !cleared) return { reason: "ancestor_background" };
+    e = e.parentElement;
+  }
+  for (const root of Array.from(document.querySelectorAll("[data-composition-id]"))) {
+    if (root.parentElement?.closest("[data-composition-id]") && painted(getComputedStyle(root))) {
+      return { reason: "subcomposition_background" };
+    }
+  }
+  const fitStyle = getComputedStyle(video).objectFit;
+  if (fitStyle !== "fill" && fitStyle !== "cover") return { reason: "object_fit" };
+  const own = Number.parseInt(getComputedStyle(video).zIndex, 10) || 0;
+  for (const other of Array.from(document.body.querySelectorAll("*"))) {
+    if (other === video || other.contains(video) || video.contains(other)) continue;
+    if (other.tagName === "SCRIPT" || other.tagName === "STYLE") continue;
+    const z = Number.parseInt(getComputedStyle(other).zIndex, 10) || 0;
+    const before = video.compareDocumentPosition(other) & Node.DOCUMENT_POSITION_PRECEDING;
+    if (z < own || z === own && before) {
+      const box = other.getBoundingClientRect();
+      if (box.width > 0 && box.height > 0) return { reason: "paints_under" };
+    }
+  }
+  return { fit: fitStyle === "cover" ? "cover" : "fill" };
+}
+async function probeVideoLayout(page, videoId, canvas, duration) {
+  let fit = "fill";
+  for (let i = 0; i < SAMPLES; i++) {
+    const t = duration * i / SAMPLES;
+    const seen = await page.evaluate(inspectVideoLayout, videoId, canvas.width, canvas.height, t);
+    if ("reason" in seen) return seen;
+    if (seen.fit === "cover") fit = "cover";
+  }
+  await page.evaluate(
+    () => window.__hf?.seek?.(0)
+  );
+  return { fit };
+}
+async function planVideoLayerPassthrough(input) {
+  const q = qualifyVideoLayer(input.videos, input.duration);
+  if (!q.qualifies) return { reason: q.reason };
+  const { video } = q;
+  if (isHttpUrl3(video.src)) return { reason: "remote_source" };
+  const path = resolveProjectRelativeSrc4(video.src, input.projectDir, input.compiledDir);
+  if (!existsSync12(path)) return { reason: "source_missing" };
+  const layout = await probeVideoLayout(input.page, video.id, input.canvas, input.duration);
+  if ("reason" in layout) return layout;
+  const layer = await buildVideoLayerInput(
+    path,
+    video.mediaStart,
+    input.duration,
+    input.fps,
+    input.canvas,
+    layout.fit
+  );
+  return layer ? { videoId: video.id, layer } : { reason: "source_unsupported" };
+}
 
 // src/services/render/stages/audioStage.ts
 import { join as join20 } from "node:path";
@@ -10290,7 +10418,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
 }
 
 // src/services/render/stages/captureStage.ts
-import { existsSync as existsSync12, readdirSync as readdirSync3, statfsSync as statfsSync2 } from "node:fs";
+import { existsSync as existsSync13, readdirSync as readdirSync3, statfsSync as statfsSync2 } from "node:fs";
 import { join as join21 } from "node:path";
 import {
   classifyCaptureFailure as classifyCaptureFailure2,
@@ -10361,7 +10489,7 @@ function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis, remed
 }
 function measureCaptureFrameBytes(workDir, framesDir) {
   let total = sampleDirectoryBytes(framesDir);
-  if (!existsSync12(workDir)) return total;
+  if (!existsSync13(workDir)) return total;
   for (const attempt of readdirSync3(workDir)) {
     if (/^retry-\d+-batch-\d+-worker-\d+$/.test(attempt)) {
       total += sampleDirectoryBytes(join21(workDir, attempt));
@@ -10664,7 +10792,7 @@ async function captureSessionFrames(session, { input, rangeStart, rangeEnd, resu
 }
 
 // src/services/render/stages/captureHdrStage.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync8 } from "node:fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync8 } from "node:fs";
 import { join as join25 } from "node:path";
 import {
   closeCaptureSession as closeCaptureSession7,
@@ -10910,7 +11038,7 @@ import { Worker } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
 import { dirname as dirname9, join as join23 } from "node:path";
 import { createRequire } from "node:module";
-import { existsSync as existsSync13 } from "node:fs";
+import { existsSync as existsSync14 } from "node:fs";
 import { cpus as cpus2 } from "node:os";
 function resolveWorkerEntry(explicit) {
   if (explicit && explicit.length > 0) {
@@ -10923,7 +11051,7 @@ function resolveWorkerEntry(explicit) {
   }
   const moduleDir = dirname9(fileURLToPath3(import.meta.url));
   const jsPath = join23(moduleDir, "shaderTransitionWorker.js");
-  if (existsSync13(jsPath)) return { path: jsPath, isTs: false };
+  if (existsSync14(jsPath)) return { path: jsPath, isTs: false };
   const tsPath = join23(moduleDir, "shaderTransitionWorker.ts");
   return { path: tsPath, isTs: true };
 }
@@ -11484,7 +11612,7 @@ async function runCaptureHdrStage(input) {
       }
       const debugDumpEnabled = process.env.KEEP_TEMP === "1";
       const debugDumpDir = debugDumpEnabled ? join25(framesDir, "debug-composite") : null;
-      if (debugDumpDir && !existsSync14(debugDumpDir)) {
+      if (debugDumpDir && !existsSync15(debugDumpDir)) {
         mkdirSync8(debugDumpDir, { recursive: true });
       }
       const compositeTransfer = resolveCompositeTransfer(hasHdrContent, effectiveHdr);
@@ -11641,10 +11769,10 @@ async function runCaptureHdrStage(input) {
 // src/services/render/stages/encodeStage.ts
 import {
   copyFileSync as copyFileSync4,
-  existsSync as existsSync15,
+  existsSync as existsSync16,
   mkdirSync as mkdirSync9,
   readdirSync as readdirSync4,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync7,
   rmSync as rmSync9,
   statSync as statSync7,
   writeFileSync as writeFileSync5
@@ -11738,7 +11866,7 @@ async function reencodeWithClearedWholeFrames(argsInput, run, startTime) {
     const error = formatFfmpegError(result.exitCode, result.stderr);
     return gifEncodeFailure(startTime, outputPath, error, result.failureReason);
   }
-  const gif = readFileSync8(outputPath);
+  const gif = readFileSync7(outputPath);
   if (!clearGifFramesBeforeNext(gif)) {
     const error = "[FFmpeg] GIF output could not be parsed to clear its frames";
     return gifEncodeFailure(startTime, outputPath, error);
@@ -11771,11 +11899,11 @@ async function encodeGifFromDir(framesDir, framePattern, outputPath, input) {
         return gifEncodeFailure(startTime, outputPath, error, result.failureReason);
       }
     }
-    if (input.preserveAlpha && gifClearsAfterLeavingFrameInPlace(readFileSync8(outputPath)) !== false) {
+    if (input.preserveAlpha && gifClearsAfterLeavingFrameInPlace(readFileSync7(outputPath)) !== false) {
       const failure = await reencodeWithClearedWholeFrames(argsInput, run, startTime);
       if (failure) return failure;
     }
-    const fileSize = existsSync15(outputPath) ? statSync7(outputPath).size : 0;
+    const fileSize = existsSync16(outputPath) ? statSync7(outputPath).size : 0;
     return {
       success: true,
       outputPath,
@@ -11936,7 +12064,7 @@ async function runEncodeStage(input) {
   const stage5Start = Date.now();
   if (isPngSequence) {
     const encoded = startEncodeProgress(job, "Writing PNG sequence", onProgress);
-    if (!existsSync15(outputPath)) mkdirSync9(outputPath, { recursive: true });
+    if (!existsSync16(outputPath)) mkdirSync9(outputPath, { recursive: true });
     const captured = readdirSync4(framesDir).filter((name) => name.endsWith(".png")).sort();
     if (captured.length === 0) {
       throw new Error(
@@ -11947,7 +12075,7 @@ async function runEncodeStage(input) {
       const dst = join26(outputPath, formatExportFrameName(i, "png"));
       copyFileSync4(join26(framesDir, name), dst);
     });
-    if (hasAudio && audioOutputPath && existsSync15(audioOutputPath)) {
+    if (hasAudio && audioOutputPath && existsSync16(audioOutputPath)) {
       copyFileSync4(audioOutputPath, join26(outputPath, MIXED_AUDIO_FILENAME2));
       log.info(
         `[Render] png-sequence: ${MIXED_AUDIO_FILENAME2} sidecar written to ${outputPath}/${MIXED_AUDIO_FILENAME2}`
@@ -12328,7 +12456,7 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   let rangeStart = null;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join27(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    const missing = !existsSync16(framePath) || statSync8(framePath).size <= 8;
+    const missing = !existsSync17(framePath) || statSync8(framePath).size <= 8;
     if (missing && rangeStart === null) {
       rangeStart = frameIndex;
     } else if (!missing && rangeStart !== null) {
@@ -12453,7 +12581,7 @@ function countCapturedFrames(totalFrames, framesDir, frameExt) {
   let captured = 0;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join27(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    if (existsSync16(framePath)) captured++;
+    if (existsSync17(framePath)) captured++;
   }
   return captured;
 }
@@ -13116,7 +13244,7 @@ async function executeRenderJob(job, projectDir, outputPath, progressSink, abort
   validateDeliveryEncoderConfig(job.config);
   const debugDir = resolveRenderDebugDir();
   const outputDir = dirname11(outputPath);
-  if (!existsSync16(outputDir)) mkdirSync10(outputDir, { recursive: true });
+  if (!existsSync17(outputDir)) mkdirSync10(outputDir, { recursive: true });
   const workDir = job.config.debug ? join27(debugDir, job.id) : createRenderWorkDir(resolveRenderWorkDirPrefix(outputPath, job.id), outputDir);
   const pipelineStart = Date.now();
   const baseLog = job.config.logger ?? defaultLogger;
@@ -13257,7 +13385,7 @@ async function executeRenderPipeline(input) {
     job.startedAt = /* @__PURE__ */ new Date();
     assertNotAborted();
     assertConfiguredFfmpegBinariesExist();
-    if (!existsSync16(workDir)) mkdirSync10(workDir, { recursive: true });
+    if (!existsSync17(workDir)) mkdirSync10(workDir, { recursive: true });
     if (job.config.debug) {
       log.info("[Render] Debug artifacts enabled", { workDir, logPath });
     }
@@ -13287,21 +13415,21 @@ async function executeRenderPipeline(input) {
     });
     const entryFile = job.config.entryFile || "index.html";
     let htmlPath = join27(projectDir, entryFile);
-    if (!existsSync16(htmlPath)) {
+    if (!existsSync17(htmlPath)) {
       throw new Error(`Entry file not found: ${htmlPath}`);
     }
     assertNotAborted();
-    const rawEntry = readFileSync9(htmlPath, "utf-8");
+    const rawEntry = readTextFile2(htmlPath);
     if (entryFile !== "index.html" && isTemplateEntry(rawEntry)) {
       const wrapperPath = join27(workDir, "standalone-entry.html");
       const projectIndexPath = join27(projectDir, "index.html");
-      if (!existsSync16(projectIndexPath)) {
+      if (!existsSync17(projectIndexPath)) {
         throw new Error(
           `Template entry file "${entryFile}" requires a project index.html to extract its render shell.`
         );
       }
       const standaloneHtml = extractStandaloneEntryFromIndex(
-        readFileSync9(projectIndexPath, "utf-8"),
+        readTextFile2(projectIndexPath),
         entryFile,
         rawEntry
       );
@@ -13464,6 +13592,42 @@ async function executeRenderPipeline(input) {
       compositionHash,
       beginFrameStalled: probeResult.beginFrameStalled
     });
+    let videoLayerPlan;
+    if (cfg.videoLayerPassthrough) {
+      const gates = {
+        mp4: outputFormat === "mp4",
+        software_encode: !job.config.useGpu,
+        opaque_output: !needsAlpha,
+        sdr: rendersSdrOnly(job.config, composition) || (job.config.hdrMode === void 0 || job.config.hdrMode === "auto") && composition.images.length === 0,
+        streaming: shouldUseStreamingEncode(cfg, outputFormat, 1, probeResult.duration),
+        probe_page: probeSession?.isInitialized === true
+      };
+      const failed = Object.entries(gates).find(([, ok]) => !ok)?.[0];
+      if (failed || !probeSession) {
+        log.info(`[Render] Video layer passthrough off: ${failed ?? "probe_page"}`);
+      } else {
+        videoLayerPlan = await planVideoLayerPassthrough({
+          videos: composition.videos,
+          duration: probeResult.duration,
+          fps: job.config.fps,
+          canvas: { width, height },
+          page: probeSession.page,
+          projectDir,
+          compiledDir: join27(workDir, "compiled")
+        });
+        if (videoLayerPlan.videoId === void 0) {
+          log.info(`[Render] Video layer passthrough off: ${videoLayerPlan.reason}`);
+        } else {
+          cfg.useDrawElement = false;
+          cfg.forceScreenshot = true;
+          captureForceScreenshot = true;
+          const opened = probeSession;
+          probeSession = null;
+          await closeCaptureSession8(opened);
+        }
+      }
+    }
+    const videoLayer = videoLayerPlan?.videoId === void 0 ? void 0 : videoLayerPlan;
     updateJobStatus(job, "preprocessing", "Extracting video frames", 10, onProgress, {
       code: "extract_video"
     });
@@ -13479,6 +13643,7 @@ async function executeRenderPipeline(input) {
         cfg,
         log,
         composition,
+        skipFrameExtractionIds: videoLayer ? [videoLayer.videoId] : [],
         abortSignal: executionSignal,
         assertNotAborted,
         // Local staging can use links; distributed plan() alone requires real copies.
@@ -13597,7 +13762,7 @@ async function executeRenderPipeline(input) {
       throw new Error("File server failed to initialize before frame capture");
     }
     const framesDir = join27(workDir, "captured-frames");
-    if (!existsSync16(framesDir)) mkdirSync10(framesDir, { recursive: true });
+    if (!existsSync17(framesDir)) mkdirSync10(framesDir, { recursive: true });
     updateJobStatus(job, "rendering", "Checking browser GPU", 25, onProgress, {
       code: "start_browsers"
     });
@@ -13623,8 +13788,9 @@ async function executeRenderPipeline(input) {
       width,
       height,
       fps: job.config.fps,
-      format: captureImageFormat,
-      transparent: needsAlpha,
+      format: videoLayer ? "png" : captureImageFormat,
+      transparent: needsAlpha || videoLayer !== void 0,
+      ...videoLayer ? { hiddenElementIds: [videoLayer.videoId] } : {},
       quality: captureImageFormat === "png" ? void 0 : resolveCaptureJpegQuality(job.config.quality),
       variables: job.config.variables,
       deviceScaleFactor,
@@ -13921,6 +14087,7 @@ async function executeRenderPipeline(input) {
         }
       }
     );
+    if (videoLayer) workerCount = 1;
     const preRoutingWorkerCount = workerCount;
     if (deParallelRouterEligible && workerCount > 1) {
       deParallelRouter = "routed";
@@ -14586,6 +14753,7 @@ async function executeRenderPipeline(input) {
                 vp9CpuUsed: cfg.vp9CpuUsed,
                 useGpu: job.config.useGpu,
                 imageFormat: captureOptions.format || "jpeg",
+                ...videoLayer ? { videoLayer: videoLayer.layer } : {},
                 hdr: preset.hdr,
                 // HLS only: force an IDR every `gopSize` frames so the
                 // assemble stage's `-c copy` segmentation cuts exactly on
@@ -14916,12 +15084,12 @@ async function executeRenderPipeline(input) {
       })
     );
     const totalElapsed = Date.now() - pipelineStart;
-    const tmpPeakBytes = existsSync16(workDir) ? sampleDirectoryBytes(workDir) : 0;
+    const tmpPeakBytes = existsSync17(workDir) ? sampleDirectoryBytes(workDir) : 0;
     recordTransientRetryObservability();
     observability.checkpoint("pipeline", "artifact validated", { totalElapsedMs: totalElapsed });
     const observabilitySummary = observability.summary({
       lastBrowserConsole,
-      capture: captureObservability,
+      capture: withCapturedBeyondViewport(captureObservability, dedupPerfs),
       initFallback: mergeWorkerInitObservability(dedupPerfs),
       extraction: extractionObservability,
       compositionHash
@@ -14997,7 +15165,7 @@ async function executeRenderPipeline(input) {
       }
     }
     if (job.config.debug) {
-      if (!isPngSequence && !isHls && existsSync16(stagedOutputPath)) {
+      if (!isPngSequence && !isHls && existsSync17(stagedOutputPath)) {
         const debugOutput = join27(workDir, `output${videoExt}`);
         copyFileSync5(stagedOutputPath, debugOutput);
       }
@@ -15057,7 +15225,7 @@ async function executeRenderPipeline(input) {
     const failedStage = job.currentStage || "pipeline";
     const observabilitySummary = observability.summary({
       lastBrowserConsole,
-      capture: captureObservability,
+      capture: withCapturedBeyondViewport(captureObservability, dedupPerfs),
       initFallback: mergeWorkerInitObservability(dedupPerfs),
       extraction: extractionObservability,
       compositionHash
@@ -15104,8 +15272,8 @@ async function executeRenderPipeline(input) {
 
 // src/services/hyperframeLint.ts
 import {
-  existsSync as existsSync17,
-  readFileSync as readFileSync10,
+  existsSync as existsSync18,
+  readFileSync as readFileSync8,
   statSync as statSync9,
   openSync as openSync5,
   fstatSync as fstatSync3,
@@ -15151,14 +15319,14 @@ function readEntryHtml(filePath) {
   }
   try {
     if (!fstatSync3(fd).isFile()) return null;
-    return readFileSync10(fd, "utf-8");
+    return readFileSync8(fd, "utf-8");
   } finally {
     closeSync5(fd);
   }
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
   const absProjectDir = resolve9(projectDir);
-  if (!existsSync17(absProjectDir) || !statSync9(absProjectDir).isDirectory()) {
+  if (!existsSync18(absProjectDir) || !statSync9(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entryCandidates = [preferredEntryFile, "index.html", "src/index.html"].filter(
@@ -15227,7 +15395,7 @@ async function runHyperframeLint(prepared) {
 import { Worker as Worker2 } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { dirname as dirname12, join as join29 } from "node:path";
-import { existsSync as existsSync18 } from "node:fs";
+import { existsSync as existsSync19 } from "node:fs";
 var DEFAULT_HEALTH_PORT = 9848;
 async function startHealthWorker(options = {}) {
   const log = options.logger ?? defaultLogger2();
@@ -15304,7 +15472,7 @@ function resolveWorkerEntry2() {
   const here = dirname12(fileURLToPath5(import.meta.url));
   const candidates = [join29(here, "healthWorkerThread.js"), join29(here, "healthWorkerThread.ts")];
   for (const candidate of candidates) {
-    if (existsSync18(candidate)) return candidate;
+    if (existsSync19(candidate)) return candidate;
   }
   return void 0;
 }
@@ -15831,7 +15999,7 @@ function resolvePreparedRenderOutput(prepared, rendersDir, log) {
   const { input, cleanupProjectDir } = prepared;
   const absoluteOutputPath = resolveOutputPath(input.projectDir, input.outputPath, rendersDir, log);
   const outputDir = dirname13(absoluteOutputPath);
-  if (!existsSync19(outputDir)) mkdirSync11(outputDir, { recursive: true });
+  if (!existsSync20(outputDir)) mkdirSync11(outputDir, { recursive: true });
   return { input, cleanupProjectDir, absoluteOutputPath };
 }
 function validateRenderOverrides(body) {
@@ -15872,11 +16040,11 @@ function prepareProjectDirectory(projectDir, options) {
   const candidate = nonEmptyString(projectDir);
   if (!candidate) return null;
   const absProjectDir = resolve10(candidate);
-  if (!existsSync19(absProjectDir) || !statSync10(absProjectDir).isDirectory()) {
+  if (!existsSync20(absProjectDir) || !statSync10(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entry = options.entryFile || "index.html";
-  if (!existsSync19(resolve10(absProjectDir, entry))) {
+  if (!existsSync20(resolve10(absProjectDir, entry))) {
     return { error: `Entry file "${entry}" not found in project directory: ${absProjectDir}` };
   }
   return { prepared: { input: { projectDir: absProjectDir, ...options } } };
@@ -15968,7 +16136,7 @@ function cleanupTempDir(dir, log) {
   }
 }
 function outputFileSize(path) {
-  return existsSync19(path) ? statSync10(path).size : 0;
+  return existsSync20(path) ? statSync10(path).size : 0;
 }
 function createBlockingProgressReporter(log, requestId) {
   let lastLoggedPct = -10;
@@ -16270,7 +16438,7 @@ function createRenderHandlers(options = {}) {
     if (!artifact) {
       return c.json({ success: false, error: "Output artifact not found or expired" }, 404);
     }
-    if (!existsSync19(artifact.path)) {
+    if (!existsSync20(artifact.path)) {
       store.delete(token);
       return c.json({ success: false, error: "Output artifact file missing" }, 404);
     }

package/dist/services/render/perfSummary.d.ts

@@ -7,7 +7,7 @@ import type { CapturePerfSummary, SubTimelineWaitOutcome, WorkerSizing } from "@
 import type { CaptureCalibrationSample, CaptureCostEstimate } from "./captureCost.js";
 import type { CaptureAttemptSummary, HdrDiagnostics, RenderJob, RenderPerfSummary } from "../renderOrchestrator.js";
 import { type HdrPerfCollector } from "./hdrPerf.js";
-import type { RenderObservabilitySummary } from "./observability.js";
+import type { RenderCaptureObservability, RenderObservabilitySummary } from "./observability.js";
 /**
  * Worst sub-composition timeline wait outcome across sessions: script_failure
  * > timeout > ready. Shared by the success-path perf summary and the error
@@ -24,6 +24,10 @@ export declare function worstSubTimelineWaitOutcome(perfs: CapturePerfSummary[])
 export declare function pushWorkerDedupPerfs(results: ReadonlyArray<{
     perf?: CapturePerfSummary;
 }>, sink: CapturePerfSummary[]): void;
+/** Beyond-viewport capture as the workers' sessions used it: on if any kept it, `fallback` when none reported. */
+export declare function capturedBeyondViewport(perfs: ReadonlyArray<CapturePerfSummary>, fallback: boolean | undefined): boolean | undefined;
+/** The capture facts with beyond-viewport capture as the sessions used it, on every capture path. */
+export declare function withCapturedBeyondViewport(capture: RenderCaptureObservability, perfs: ReadonlyArray<CapturePerfSummary>): RenderCaptureObservability;
 /** Adds each worker's page-error console lines to `sink`, once per distinct line. */
 export declare function pushWorkerPageErrors(results: ReadonlyArray<{
     pageErrorLines?: string[];

package/dist/services/render/stages/extractVideosStage.d.ts

@@ -52,6 +52,7 @@ export interface ExtractVideosStageInput {
      */
     materializeSymlinks?: boolean;
     deferRangeExtraction?: boolean;
+    skipFrameExtractionIds?: readonly string[];
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
     onProgress?: ProgressCallback;
 }
@@ -119,7 +120,7 @@ export declare class VideoExtractionStageError extends Error {
      * validating and applying policy to it.
      */
     readonly publicMetadata: Readonly<Record<string, unknown>>;
-    constructor(code: VideoExtractionStageErrorCode, retryable: boolean, failures: readonly VideoExtractionStageFailureSummary[], extractionFailure?: ExtractionFailureMetadataV1, ffmpegReason?: string);
+    constructor(code: VideoExtractionStageErrorCode, retryable: boolean, failures: readonly VideoExtractionStageFailureSummary[], extractionFailure?: ExtractionFailureMetadataV1, ffmpegReason?: string, sources?: readonly string[]);
 }
 export declare function assertVideoExtractionSucceeded(result: ExtractionResult): void;
 export declare function buildHdrProbeStageError(failures: readonly Pick<ReturnType<typeof classifyVideoExtractionError>, "kind" | "retryable">[]): VideoExtractionStageError;