@hyperframes/producer 0.8.225 → 0.8.226

package/dist/index.js

@@ -1,9 +1,8 @@
 // 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,
@@ -24,6 +23,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,
@@ -2134,6 +2134,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);
@@ -5766,7 +5774,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 {
@@ -5819,7 +5827,8 @@ import {
 } from "@hyperframes/parsers/sub-composition-validity";
 import {
   isUnresolvedAssetPlaceholder,
-  readProjectFile
+  readProjectFile,
+  readTextFile
 } from "@hyperframes/parsers/asset-resolution";
 
 // src/services/renderMediaCollector.ts
@@ -7908,11 +7917,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();
@@ -8763,7 +8768,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,
@@ -9395,17 +9400,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((sum2, failure) => sum2 + 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;
@@ -9453,7 +9464,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) {
@@ -9532,7 +9546,8 @@ async function runExtractVideosStage(input) {
     assertNotAborted,
     materializeSymlinks,
     deferRangeExtraction,
-    urlByAbsentLocalPath
+    urlByAbsentLocalPath,
+    skipFrameExtractionIds = []
   } = input;
   const stage2Start = Date.now();
   const extractionPolicy = resolveVideoExtractionPolicy();
@@ -9603,7 +9618,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];
@@ -9699,6 +9717,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 box2 = other.getBoundingClientRect();
+      if (box2.width > 0 && box2.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";
@@ -10310,7 +10438,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,
@@ -10381,7 +10509,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));
@@ -10684,7 +10812,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,
@@ -10930,7 +11058,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) {
@@ -10943,7 +11071,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 };
 }
@@ -11504,7 +11632,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);
@@ -11661,10 +11789,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
@@ -11758,7 +11886,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);
@@ -11791,11 +11919,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,
@@ -11956,7 +12084,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(
@@ -11967,7 +12095,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}`
@@ -12348,7 +12476,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) {
@@ -12473,7 +12601,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;
 }
@@ -13136,7 +13264,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;
@@ -13277,7 +13405,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 });
     }
@@ -13307,21 +13435,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
       );
@@ -13484,6 +13612,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"
     });
@@ -13499,6 +13663,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.
@@ -13617,7 +13782,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"
     });
@@ -13643,8 +13808,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,
@@ -13941,6 +14107,7 @@ async function executeRenderPipeline(input) {
         }
       }
     );
+    if (videoLayer) workerCount = 1;
     const preRoutingWorkerCount = workerCount;
     if (deParallelRouterEligible && workerCount > 1) {
       deParallelRouter = "routed";
@@ -14606,6 +14773,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
@@ -14936,12 +15104,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
@@ -15017,7 +15185,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);
       }
@@ -15077,7 +15245,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
@@ -15123,7 +15291,7 @@ async function executeRenderPipeline(input) {
 }
 
 // src/services/distributed/renderSpan.ts
-import { mkdirSync as mkdirSync18, mkdtempSync as mkdtempSync7, readFileSync as readFileSync15, rmSync as rmSync16 } from "node:fs";
+import { mkdirSync as mkdirSync18, mkdtempSync as mkdtempSync7, readFileSync as readFileSync13, rmSync as rmSync16 } from "node:fs";
 import { join as join40 } from "node:path";
 import { tmpdir as tmpdir4 } from "node:os";
 
@@ -15515,7 +15683,7 @@ import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframe
 import {
   copyFileSync as copyFileSync6,
   cpSync as cpSync2,
-  existsSync as existsSync21,
+  existsSync as existsSync22,
   linkSync,
   mkdirSync as mkdirSync14,
   rmSync as rmSync12,
@@ -15546,7 +15714,7 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/distributed/chunkFrames.ts
-import { existsSync as existsSync18, readdirSync as readdirSync6 } from "node:fs";
+import { existsSync as existsSync19, readdirSync as readdirSync6 } from "node:fs";
 import { extname as extname4, join as join30 } from "node:path";
 import {
   compositionRequiresWebGpu as compositionRequiresWebGpu3,
@@ -15558,7 +15726,7 @@ import {
 // src/services/distributed/shared.ts
 import { execFile as execFileCallback } from "node:child_process";
 import { dirname as dirname13, join as join29 } from "node:path";
-import { existsSync as existsSync17, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync18, readFileSync as readFileSync8 } from "node:fs";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { promisify as promisify2 } from "node:util";
 import {
@@ -15574,7 +15742,7 @@ function isPlanAudioArtifactPath(path) {
 function resolvePlanAudioPath(planDir) {
   for (const name of [PLAN_AUDIO_RELATIVE_PATH, PLAN_AUDIO_LEGACY_RELATIVE_PATH]) {
     const candidate = join29(planDir, name);
-    if (existsSync17(candidate)) return candidate;
+    if (existsSync18(candidate)) return candidate;
   }
   return null;
 }
@@ -15835,9 +16003,9 @@ function readProducerVersion() {
   let current = startDir;
   for (let i = 0; i < 10; i++) {
     const candidate = join29(current, "package.json");
-    if (existsSync17(candidate)) {
+    if (existsSync18(candidate)) {
       try {
-        const pkg = JSON.parse(readFileSync10(candidate, "utf-8"));
+        const pkg = JSON.parse(readFileSync8(candidate, "utf-8"));
         if (pkg.name === "@hyperframes/producer" && typeof pkg.version === "string") {
           cachedProducerVersion = pkg.version;
           return pkg.version;
@@ -15889,7 +16057,7 @@ function rebuildExtractedFramesFromPlanDir(planDir, videos, indexMode = "dense-v
   const result = [];
   for (const v of videos) {
     const outputDir = join30(planDir, "video-frames", v.videoId);
-    if (!existsSync18(outputDir)) {
+    if (!existsSync19(outputDir)) {
       throw new Error(
         `[renderChunk] planDir missing extracted video frames for ${JSON.stringify(v.videoId)}: ${outputDir} not present. plan() should have written frames here; the planDir is malformed.`
       );
@@ -16005,7 +16173,7 @@ async function extractDeferredVideoFramesForChunk(input) {
       const range = video.deferredRange;
       const remoteUrl = remoteSources[range.sourcePath];
       const sourcePath = remoteUrl ?? join30(input.planDir, ...range.sourcePath.split("/"));
-      if (remoteUrl === void 0 && !existsSync18(sourcePath)) {
+      if (remoteUrl === void 0 && !existsSync19(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -16167,7 +16335,7 @@ function buildWeightedChunkSlices(weights, chunkCount, minFrames, maxFrames) {
 }
 
 // src/services/render/stages/freezePlan.ts
-import { existsSync as existsSync19, mkdirSync as mkdirSync12, readFileSync as readFileSync11, readdirSync as readdirSync7, writeFileSync as writeFileSync7 } from "node:fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync12, readFileSync as readFileSync9, readdirSync as readdirSync7, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join32, relative as relative3, resolve as resolve9 } from "node:path";
 
 // src/services/distributed/planProtocol.ts
@@ -16361,7 +16529,7 @@ function planFileSha256(absolutePath, digests) {
   return sha256;
 }
 async function prehashPlanFiles(dir, digests) {
-  if (!existsSync19(dir)) return;
+  if (!existsSync20(dir)) return;
   for (const { absolutePath } of listPlanFiles(dir)) {
     if (!digests.has(absolutePath)) digests.set(absolutePath, await sha256FileAsync(absolutePath));
   }
@@ -16407,7 +16575,7 @@ function collectPlanAssetShas(planDir, digests) {
   const assets = [];
   for (const file of files) {
     if (file.planRelativePath === COMPILED_INDEX_RELATIVE_PATH) {
-      compositionHtml = readFileSync11(file.absolutePath);
+      compositionHtml = readFileSync9(file.absolutePath);
       continue;
     }
     if (HASH_EXCLUDED_PLAN_FILES.has(file.planRelativePath)) continue;
@@ -16431,19 +16599,19 @@ function writePlanRemoteFiles(planDir, files) {
 }
 function readPlanRemoteFiles(planDir) {
   const path = join32(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
-  return existsSync19(path) ? JSON.parse(readFileSync11(path, "utf-8")) : [];
+  return existsSync20(path) ? JSON.parse(readFileSync9(path, "utf-8")) : [];
 }
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join32(planDir, "plan.json");
   const encoderJsonPath = join32(planDir, "meta", "encoder.json");
-  if (!existsSync19(planJsonPath)) {
+  if (!existsSync20(planJsonPath)) {
     throw new Error(`[freezePlan] plan.json missing: ${planJsonPath}`);
   }
-  if (!existsSync19(encoderJsonPath)) {
+  if (!existsSync20(encoderJsonPath)) {
     throw new Error(`[freezePlan] meta/encoder.json missing: ${encoderJsonPath}`);
   }
-  const planJson = JSON.parse(readFileSync11(planJsonPath, "utf-8"));
-  const encoderConfigCanonicalJson = readFileSync11(encoderJsonPath, "utf-8");
+  const planJson = JSON.parse(readFileSync9(planJsonPath, "utf-8"));
+  const encoderConfigCanonicalJson = readFileSync9(encoderJsonPath, "utf-8");
   const { compositionHtml, assets } = collectPlanAssetShas(planDir, digests);
   return computePlanHash({
     compositionHtml,
@@ -16469,11 +16637,11 @@ async function freezePlan(input) {
     hasAudio,
     digests
   } = input;
-  if (!existsSync19(planDir)) {
+  if (!existsSync20(planDir)) {
     throw new Error(`[freezePlan] planDir does not exist: ${planDir}`);
   }
   const metaDir = join32(planDir, "meta");
-  if (!existsSync19(metaDir)) mkdirSync12(metaDir, { recursive: true });
+  if (!existsSync20(metaDir)) mkdirSync12(metaDir, { recursive: true });
   writeFileSync7(
     join32(metaDir, "composition.json"),
     `${JSON.stringify(composition, null, 2)}
@@ -16549,7 +16717,7 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
 }
 
 // src/services/distributed/chunkAudio.ts
-import { closeSync as closeSync6, existsSync as existsSync20, ftruncateSync, mkdirSync as mkdirSync13, openSync as openSync6, readFileSync as readFileSync12 } from "node:fs";
+import { closeSync as closeSync6, existsSync as existsSync21, ftruncateSync, mkdirSync as mkdirSync13, openSync as openSync6, readFileSync as readFileSync10 } from "node:fs";
 import { writeFileSync as writeFileSync8, writeSync } from "node:fs";
 import { join as join33 } from "node:path";
 import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure3, runFfmpeg as runFfmpeg7 } from "@hyperframes/engine";
@@ -16637,7 +16805,7 @@ async function writeChunkAudioSlices(input) {
       offset += track.sizes[offsets.length - 1];
     }
   });
-  const bytes = readFileSync12(input.audioPath);
+  const bytes = readFileSync10(input.audioPath);
   const layout = { sizeBytes: bytes.length, payloadStart, payloadEnd, partStarts: {} };
   mkdirSync13(join33(input.planDir, SLICE_DIR), { recursive: true });
   input.chunks.forEach((_, index) => {
@@ -16655,9 +16823,9 @@ async function writeChunkAudioSlices(input) {
 }
 function chunkAudioSource(planDir, chunkIndex, scratchPath) {
   const layoutPath = join33(planDir, SLICE_LAYOUT);
-  if (!existsSync20(layoutPath)) return resolvePlanAudioPath(planDir);
-  const layout = JSON.parse(readFileSync12(layoutPath, "utf-8"));
-  const frame = readFileSync12(join33(planDir, SLICE_FRAME));
+  if (!existsSync21(layoutPath)) return resolvePlanAudioPath(planDir);
+  const layout = JSON.parse(readFileSync10(layoutPath, "utf-8"));
+  const frame = readFileSync10(join33(planDir, SLICE_FRAME));
   const fd = openSync6(scratchPath, "w");
   try {
     writeSync(fd, frame, 0, layout.payloadStart, 0);
@@ -16670,7 +16838,7 @@ function chunkAudioSource(planDir, chunkIndex, scratchPath) {
     );
     const start = layout.partStarts[chunkIndex];
     if (start !== void 0) {
-      const part = readFileSync12(join33(planDir, chunkAudioSlicePath(chunkIndex)));
+      const part = readFileSync10(join33(planDir, chunkAudioSlicePath(chunkIndex)));
       writeSync(fd, part, 0, part.length, start);
     }
     ftruncateSync(fd, layout.sizeBytes);
@@ -17215,7 +17383,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 && (existsSync21(join35(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
+      if (rel !== null && (existsSync22(join35(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
         result = ["compiled", ...rel.split(sep2)].join("/");
         break;
       }
@@ -17243,7 +17411,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     useGpu: false,
     browserGpuMode: "software"
   });
-  if (!existsSync21(planDir)) mkdirSync14(planDir, { recursive: true });
+  if (!existsSync22(planDir)) mkdirSync14(planDir, { recursive: true });
   const log = config.logger ?? defaultLogger;
   const sizeLimitBytes = options.executionPlanSizeLimitBytes ?? config.planDirSizeLimitBytes ?? PLAN_DIR_SIZE_LIMIT_BYTES;
   const abortSignal = config.abortSignal;
@@ -17273,7 +17441,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   });
   const entryFile = config.entryFile ?? "index.html";
   const htmlPath = join35(projectDir, entryFile);
-  if (!existsSync21(htmlPath)) {
+  if (!existsSync22(htmlPath)) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
   const workDir = join35(planDir, ".plan-work");
@@ -17484,15 +17652,15 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "extract", stageStarted);
   const stagedVideoFrames = join35(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join35(planDir, "video-frames");
-  if (existsSync21(videoFramesDst)) rmSync12(videoFramesDst, { recursive: true, force: true });
+  if (existsSync22(videoFramesDst)) rmSync12(videoFramesDst, { recursive: true, force: true });
   const videoSourcesDir = join35(planDir, "video-sources");
   rmSync12(videoSourcesDir, { recursive: true, force: true });
-  if (existsSync21(stagedVideoFrames)) {
+  if (existsSync22(stagedVideoFrames)) {
     renameWithRetry7(stagedVideoFrames, videoFramesDst);
   } else {
     mkdirSync14(videoFramesDst, { recursive: true });
   }
-  if (existsSync21(finalCompiledDir)) rmSync12(finalCompiledDir, { recursive: true, force: true });
+  if (existsSync22(finalCompiledDir)) rmSync12(finalCompiledDir, { recursive: true, force: true });
   renameWithRetry7(compiledDir, finalCompiledDir);
   const shipVideoSource = createVideoSourceShipper({
     planDir,
@@ -17612,10 +17780,10 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);
   }
   const planAudioPath = join35(planDir, PLAN_AUDIO_RELATIVE_PATH);
-  if (audioResult?.hasAudio && existsSync21(audioResult.audioOutputPath)) {
+  if (audioResult?.hasAudio && existsSync22(audioResult.audioOutputPath)) {
     renameWithRetry7(audioResult.audioOutputPath, planAudioPath);
   }
-  if (chunksCarryAudio && existsSync21(planAudioPath)) {
+  if (chunksCarryAudio && existsSync22(planAudioPath)) {
     if (options.sliceChunkAudio) {
       stageStarted = Date.now();
       await writeChunkAudioSlices({
@@ -17730,7 +17898,7 @@ async function plan(projectDir, config, planDir, options = {}) {
 
 // src/services/distributed/renderChunk.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync24, mkdirSync as mkdirSync17, readFileSync as readFileSync14, readdirSync as readdirSync10, rmSync as rmSync15, writeFileSync as writeFileSync12 } from "node:fs";
+import { existsSync as existsSync25, mkdirSync as mkdirSync17, readFileSync as readFileSync12, readdirSync as readdirSync10, rmSync as rmSync15, writeFileSync as writeFileSync12 } from "node:fs";
 import { cpus as cpus3 } from "node:os";
 import { join as join39 } from "node:path";
 import {
@@ -17753,11 +17921,11 @@ import {
 // src/services/distributed/planV2.ts
 import {
   copyFileSync as copyFileSync8,
-  existsSync as existsSync23,
+  existsSync as existsSync24,
   lstatSync as lstatSync3,
   mkdirSync as mkdirSync16,
   mkdtempSync as mkdtempSync6,
-  readFileSync as readFileSync13,
+  readFileSync as readFileSync11,
   readdirSync as readdirSync9,
   rmSync as rmSync14,
   statSync as statSync10,
@@ -17771,7 +17939,7 @@ import { createFrameLookupTable as createFrameLookupTable4, renameWithRetry as r
 // src/services/distributed/planV2Publisher.ts
 import {
   copyFileSync as copyFileSync7,
-  existsSync as existsSync22,
+  existsSync as existsSync23,
   linkSync as linkSync2,
   mkdirSync as mkdirSync15,
   mkdtempSync as mkdtempSync5,
@@ -17840,7 +18008,7 @@ var LocalPlanV2ArtifactPublisher = class {
   #linkFile;
   #committed = false;
   constructor(destinationDir, options = {}) {
-    if (existsSync22(destinationDir)) {
+    if (existsSync23(destinationDir)) {
       throw new PlanV2IntegrityError(`output directory already exists: ${destinationDir}`);
     }
     this.destinationDir = destinationDir;
@@ -17857,7 +18025,7 @@ var LocalPlanV2ArtifactPublisher = class {
       );
     }
     const destinationPath = planV2BlobPath(this.temporaryDir, digest);
-    if (existsSync22(destinationPath)) return;
+    if (existsSync23(destinationPath)) return;
     mkdirSync15(dirname14(destinationPath), { recursive: true });
     const stagingDir = mkdtempSync5(join37(dirname14(destinationPath), ".plan-v2-blob-"));
     const temporaryPath = join37(stagingDir, "blob");
@@ -17875,7 +18043,7 @@ var LocalPlanV2ArtifactPublisher = class {
   }
   async commitManifest(manifestBytes) {
     for (const digest of new Set(manifestDigests(manifestBytes))) {
-      if (!existsSync22(planV2BlobPath(this.temporaryDir, digest))) {
+      if (!existsSync23(planV2BlobPath(this.temporaryDir, digest))) {
         throw new PlanV2IntegrityError(
           `cannot commit manifest before referenced blob is durable: ${digest}`
         );
@@ -17906,7 +18074,7 @@ function isNonNegativeIntegerArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "number" && Number.isInteger(item) && item >= 0);
 }
 function readJsonFile(path, label) {
-  const contents = readFileSync13(path, "utf-8");
+  const contents = readFileSync11(path, "utf-8");
   try {
     const parsed = JSON.parse(contents);
     return parsed;
@@ -17954,7 +18122,7 @@ function assertValidExtractionCacheCompleteSentinel(path) {
 }
 function validateExtractionCacheCompleteSentinels(executionPlanDir) {
   const videoRoot = join38(executionPlanDir, "video-frames");
-  if (!existsSync23(videoRoot)) return;
+  if (!existsSync24(videoRoot)) return;
   for (const videoEntry of readdirSync9(videoRoot, { withFileTypes: true })) {
     if (!videoEntry.isDirectory()) continue;
     const videoDir = join38(videoRoot, videoEntry.name);
@@ -18055,7 +18223,7 @@ function parsePlanVideosJson2(value) {
 }
 function materializeExtractedVideoDirectories(planDir) {
   const videosPath = join38(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync23(videosPath)) return;
+  if (!existsSync24(videosPath)) return;
   const videos = parsePlanVideosJson2(readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH));
   for (const video of videos.extracted) {
     mkdirSync16(resolveExtractedVideoOutputDir(planDir, video.videoId), { recursive: true });
@@ -18089,9 +18257,9 @@ function parseChunkSlices(value) {
 }
 function buildVideoChunkDependencies(executionPlanDir, dimensions) {
   const videoRoot = join38(executionPlanDir, "video-frames");
-  const hasExtractedFrames = existsSync23(videoRoot) && listFiles(videoRoot).length > 0;
+  const hasExtractedFrames = existsSync24(videoRoot) && listFiles(videoRoot).length > 0;
   const videosPath = join38(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync23(videosPath)) {
+  if (!existsSync24(videosPath)) {
     return hasExtractedFrames ? { mode: "full-source-pack", dependencies: null } : { mode: "exact-rendered-frames", dependencies: /* @__PURE__ */ new Map() };
   }
   const chunksPath = join38(executionPlanDir, "meta", "chunks.json");
@@ -18148,7 +18316,7 @@ function computeManifestHash(manifest) {
   return sha256Hex(`${PLAN_V2_HASH_PREFIX}${canonicalJsonStringify(manifestPayload(manifest))}`);
 }
 function writeBlob(sourcePath, destinationPath) {
-  if (existsSync23(destinationPath)) return;
+  if (existsSync24(destinationPath)) return;
   mkdirSync16(dirname15(destinationPath), { recursive: true });
   const temporaryDir = mkdtempSync6(join38(dirname15(destinationPath), ".plan-v2-blob-"));
   const temporaryPath = join38(temporaryDir, "blob");
@@ -18188,7 +18356,7 @@ async function putTasks(tasks) {
 }
 function buildPlanV2Publication(executionPlanDir, digests) {
   const executionPlanPath = join38(executionPlanDir, "plan.json");
-  if (!existsSync23(executionPlanPath)) {
+  if (!existsSync24(executionPlanPath)) {
     throw new PlanV2IntegrityError(`execution plan is missing plan.json: ${executionPlanPath}`);
   }
   const executionPlanValue = readJsonFile(executionPlanPath, "execution plan.json");
@@ -18268,7 +18436,7 @@ function buildPlanV2Publication(executionPlanDir, digests) {
   };
 }
 function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
-  if (existsSync23(planV2Dir)) {
+  if (existsSync24(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publication = buildPlanV2Publication(executionPlanDir);
@@ -18360,7 +18528,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
   }
 }
 async function planV2(projectDir, config, planV2Dir) {
-  if (existsSync23(planV2Dir)) {
+  if (existsSync24(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publisher = new LocalPlanV2ArtifactPublisher(planV2Dir);
@@ -18509,7 +18677,7 @@ function parsePlanV2Manifest(value) {
 }
 function readPlanV2Manifest(planV2Dir) {
   const manifestPath = join38(planV2Dir, "plan.json");
-  if (!existsSync23(manifestPath)) {
+  if (!existsSync24(manifestPath)) {
     throw new PlanV2IntegrityError(`missing v2 manifest: ${manifestPath}`);
   }
   const value = readJsonFile(manifestPath, "v2 manifest");
@@ -18528,7 +18696,7 @@ function listPlanV2ArtifactsForTarget(manifest, target) {
 }
 function verifyBlob(planV2Dir, artifact) {
   const sourcePath = planV2BlobPath(planV2Dir, artifact.sha256);
-  if (!existsSync23(sourcePath)) {
+  if (!existsSync24(sourcePath)) {
     throw new PlanV2IntegrityError(`missing content-addressed artifact ${artifact.sha256}`);
   }
   const stats = statSync10(sourcePath);
@@ -18541,7 +18709,7 @@ function verifyBlob(planV2Dir, artifact) {
   return sourcePath;
 }
 function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
-  if (existsSync23(destinationDir)) {
+  if (existsSync24(destinationDir)) {
     throw new PlanV2IntegrityError(`materialization destination already exists: ${destinationDir}`);
   }
   const manifest = readPlanV2Manifest(planV2Dir);
@@ -18606,7 +18774,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
 }
 function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   const markerPath = join38(planDir, PLAN_V2_MATERIALIZATION_MARKER);
-  if (!existsSync23(markerPath)) return null;
+  if (!existsSync24(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
   if (!isRecord3(marker) || !isRecord3(marker.manifest) || !isRecord3(marker.target)) {
     throw new PlanV2IntegrityError("malformed materialization marker");
@@ -18624,7 +18792,7 @@ function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   for (const artifact of required) {
     if (Object.hasOwn(remoteSources, artifact.path)) continue;
     const path = join38(planDir, ...artifact.path.split("/"));
-    if (!existsSync23(path) || statSync10(path).size !== artifact.sizeBytes) {
+    if (!existsSync24(path) || statSync10(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
         `materialized artifact missing or truncated: ${artifact.path}`
       );
@@ -18741,10 +18909,10 @@ async function beginFrameSessionNeedsScreenshotFallback(session, probe = probeBe
   return !await probe(session.page, timeoutMs, probeTick, session.beginFrameIntervalMs);
 }
 function hashChunkOutput(outputPath, kind) {
-  if (kind === "file") return sha256Hex(readFileSync14(outputPath));
+  if (kind === "file") return sha256Hex(readFileSync12(outputPath));
   const entries = readdirSync10(outputPath).filter((name) => /\.(png|jpg|jpeg)$/i.test(name)).sort();
   const lines = entries.map(
-    (name) => `${name}\0${sha256Hex(readFileSync14(join39(outputPath, name)))}`
+    (name) => `${name}\0${sha256Hex(readFileSync12(join39(outputPath, name)))}`
   );
   return sha256Hex(lines.join("\0"));
 }
@@ -18764,13 +18932,13 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const planJsonPath = join39(planDir, "plan.json");
   const encoderJsonPath = join39(planDir, "meta", "encoder.json");
   const chunksJsonPath = join39(planDir, "meta", "chunks.json");
-  if (!existsSync24(planJsonPath)) {
+  if (!existsSync25(planJsonPath)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir is missing required artifact: ${planJsonPath}`
     );
   }
-  const plan2 = JSON.parse(readFileSync14(planJsonPath, "utf-8"));
+  const plan2 = JSON.parse(readFileSync12(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.chunk);
   const planHashStarted = Date.now();
   const v2Materialization = readValidatedPlanV2Materialization(planDir, {
@@ -18780,20 +18948,20 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const v2Manifest = v2Materialization?.manifest ?? null;
   const remoteSources = v2Materialization?.remoteSources ?? {};
   for (const required of [encoderJsonPath, chunksJsonPath]) {
-    if (!existsSync24(required)) {
+    if (!existsSync25(required)) {
       throw new RenderChunkValidationError(
         MISSING_PLAN_ARTIFACT,
         `[renderChunk] planDir is missing required artifact: ${required}`
       );
     }
   }
-  const encoder = JSON.parse(readFileSync14(encoderJsonPath, "utf-8"));
-  const chunks = JSON.parse(readFileSync14(chunksJsonPath, "utf-8"));
+  const encoder = JSON.parse(readFileSync12(encoderJsonPath, "utf-8"));
+  const chunks = JSON.parse(readFileSync12(chunksJsonPath, "utf-8"));
   const videosJsonPath = join39(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   let planVideos = null;
-  if (existsSync24(videosJsonPath)) {
+  if (existsSync25(videosJsonPath)) {
     try {
-      planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync14(videosJsonPath, "utf-8")));
+      planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync12(videosJsonPath, "utf-8")));
     } catch (err) {
       if (err instanceof RenderChunkValidationError) throw err;
       throw new RenderChunkValidationError(
@@ -18822,7 +18990,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const range = resolveChunkFrameRange(slice, chunkIndex, options?.frameRange);
   const framesInChunk = range.endFrame - range.startFrame;
   const compiledDir = join39(planDir, "compiled");
-  if (!existsSync24(compiledDir)) {
+  if (!existsSync25(compiledDir)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir missing compiled/ directory: ${compiledDir}`
@@ -18904,7 +19072,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       dimensions: plan2.dimensions,
       encoder,
       videoCount: planVideos?.videos.length ?? 0,
-      html: readFileSync14(join39(compiledDir, "index.html"), "utf-8"),
+      html: readFileSync12(join39(compiledDir, "index.html"), "utf-8"),
       // The plan ships a deferred source only to chunks that show it; don't wait on the rest.
       skipReadinessVideoIds: deferredVideos.filter(
         (video) => !shownFrames.get(video.videoId)?.size || remoteVideoIds.has(video.videoId)
@@ -19072,10 +19240,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       const effectiveBitrate = encoder.crf != null ? void 0 : encoder.bitrate;
       const videoOnlyPath = encoder.chunksCarryAudio ? `${outputChunkPath}.video.mp4` : outputChunkPath;
       if (isPngSequence) {
-        if (!existsSync24(outputChunkPath)) mkdirSync17(outputChunkPath, { recursive: true });
+        if (!existsSync25(outputChunkPath)) mkdirSync17(outputChunkPath, { recursive: true });
       } else {
         const outDir = join39(outputChunkPath, "..");
-        if (!existsSync24(outDir)) mkdirSync17(outDir, { recursive: true });
+        if (!existsSync25(outDir)) mkdirSync17(outDir, { recursive: true });
       }
       const encodeInput = {
         job,
@@ -19366,7 +19534,7 @@ async function renderSpan(projectDir, config, span, outputPath) {
       planned.totalFrames
     );
     const slices = JSON.parse(
-      readFileSync15(join40(planDir, "meta", "chunks.json"), "utf-8")
+      readFileSync13(join40(planDir, "meta", "chunks.json"), "utf-8")
     );
     const parts = [];
     for (const slice of slices) {
@@ -19969,7 +20137,7 @@ import {
 
 // src/server.ts
 import {
-  existsSync as existsSync27,
+  existsSync as existsSync28,
   mkdirSync as mkdirSync19,
   statSync as statSync12,
   mkdtempSync as mkdtempSync8,
@@ -19988,8 +20156,8 @@ import { fetchPublicHttpsText as fetchPublicHttpsText2 } from "@hyperframes/engi
 
 // src/services/hyperframeLint.ts
 import {
-  existsSync as existsSync25,
-  readFileSync as readFileSync16,
+  existsSync as existsSync26,
+  readFileSync as readFileSync14,
   statSync as statSync11,
   openSync as openSync7,
   fstatSync as fstatSync3,
@@ -20035,14 +20203,14 @@ function readEntryHtml(filePath) {
   }
   try {
     if (!fstatSync3(fd).isFile()) return null;
-    return readFileSync16(fd, "utf-8");
+    return readFileSync14(fd, "utf-8");
   } finally {
     closeSync7(fd);
   }
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
   const absProjectDir = resolve11(projectDir);
-  if (!existsSync25(absProjectDir) || !statSync11(absProjectDir).isDirectory()) {
+  if (!existsSync26(absProjectDir) || !statSync11(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entryCandidates = [preferredEntryFile, "index.html", "src/index.html"].filter(
@@ -20111,7 +20279,7 @@ async function runHyperframeLint(prepared) {
 import { Worker as Worker2 } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
 import { dirname as dirname16, join as join42 } from "node:path";
-import { existsSync as existsSync26 } from "node:fs";
+import { existsSync as existsSync27 } from "node:fs";
 var DEFAULT_HEALTH_PORT = 9848;
 async function startHealthWorker(options = {}) {
   const log = options.logger ?? defaultLogger2();
@@ -20188,7 +20356,7 @@ function resolveWorkerEntry2() {
   const here = dirname16(fileURLToPath6(import.meta.url));
   const candidates = [join42(here, "healthWorkerThread.js"), join42(here, "healthWorkerThread.ts")];
   for (const candidate of candidates) {
-    if (existsSync26(candidate)) return candidate;
+    if (existsSync27(candidate)) return candidate;
   }
   return void 0;
 }
@@ -20331,7 +20499,7 @@ function resolvePreparedRenderOutput(prepared, rendersDir, log) {
   const { input, cleanupProjectDir } = prepared;
   const absoluteOutputPath = resolveOutputPath(input.projectDir, input.outputPath, rendersDir, log);
   const outputDir = dirname17(absoluteOutputPath);
-  if (!existsSync27(outputDir)) mkdirSync19(outputDir, { recursive: true });
+  if (!existsSync28(outputDir)) mkdirSync19(outputDir, { recursive: true });
   return { input, cleanupProjectDir, absoluteOutputPath };
 }
 function validateRenderOverrides(body) {
@@ -20372,11 +20540,11 @@ function prepareProjectDirectory(projectDir, options) {
   const candidate = nonEmptyString(projectDir);
   if (!candidate) return null;
   const absProjectDir = resolve12(candidate);
-  if (!existsSync27(absProjectDir) || !statSync12(absProjectDir).isDirectory()) {
+  if (!existsSync28(absProjectDir) || !statSync12(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entry = options.entryFile || "index.html";
-  if (!existsSync27(resolve12(absProjectDir, entry))) {
+  if (!existsSync28(resolve12(absProjectDir, entry))) {
     return { error: `Entry file "${entry}" not found in project directory: ${absProjectDir}` };
   }
   return { prepared: { input: { projectDir: absProjectDir, ...options } } };
@@ -20468,7 +20636,7 @@ function cleanupTempDir(dir, log) {
   }
 }
 function outputFileSize(path) {
-  return existsSync27(path) ? statSync12(path).size : 0;
+  return existsSync28(path) ? statSync12(path).size : 0;
 }
 function createBlockingProgressReporter(log, requestId) {
   let lastLoggedPct = -10;
@@ -20770,7 +20938,7 @@ function createRenderHandlers(options = {}) {
     if (!artifact) {
       return c.json({ success: false, error: "Output artifact not found or expired" }, 404);
     }
-    if (!existsSync27(artifact.path)) {
+    if (!existsSync28(artifact.path)) {
       store.delete(token);
       return c.json({ success: false, error: "Output artifact file missing" }, 404);
     }
@@ -20872,10 +21040,10 @@ import { join as join45 } from "node:path";
 // src/services/distributed/assemble.ts
 import {
   cpSync as cpSync3,
-  existsSync as existsSync28,
+  existsSync as existsSync29,
   mkdirSync as mkdirSync20,
   mkdtempSync as mkdtempSync9,
-  readFileSync as readFileSync17,
+  readFileSync as readFileSync15,
   readdirSync as readdirSync11,
   rmSync as rmSync18,
   statSync as statSync13,
@@ -20923,7 +21091,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   }
   const format = plan2.dimensions.format;
   const cfrEncoder = cfr ? readCfrEncoder(planDir, format) : null;
-  if (!existsSync28(dirname18(outputPath))) {
+  if (!existsSync29(dirname18(outputPath))) {
     mkdirSync20(dirname18(outputPath), { recursive: true });
   }
   const workDir = mkdtempSync9(`${outputPath}.assemble-work-`);
@@ -20947,7 +21115,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   try {
     const videoSources = cfrEncoder ? [await reencodeCfr(ctx, chunkPaths, cfrEncoder)] : chunkPaths;
     const finalPath = join44(workDir, `output.${format}`);
-    const audio = audioPath !== null && existsSync28(audioPath) ? audioPath : null;
+    const audio = audioPath !== null && existsSync29(audioPath) ? audioPath : null;
     await writeJoined(ctx, videoSources, audio, finalPath);
     renameWithRetry10(finalPath, outputPath);
     log.info("[assemble] stage timings", {
@@ -20965,7 +21133,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
       });
     }
   }
-  const fileSize = existsSync28(outputPath) ? statSync13(outputPath).size : 0;
+  const fileSize = existsSync29(outputPath) ? statSync13(outputPath).size : 0;
   return {
     outputPath,
     durationMs: Date.now() - start,
@@ -20976,16 +21144,16 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
 function readAssemblePlan(planDir, chunkPaths) {
   const planJsonPath = join44(planDir, "plan.json");
   const chunksJsonPath = join44(planDir, "meta", "chunks.json");
-  if (!existsSync28(planJsonPath)) {
+  if (!existsSync29(planJsonPath)) {
     throw new Error(`[assemble] planDir missing plan.json: ${planJsonPath}`);
   }
-  const plan2 = JSON.parse(readFileSync17(planJsonPath, "utf-8"));
+  const plan2 = JSON.parse(readFileSync15(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.assembler);
   validatePlanV2MaterializedTarget(planDir, { role: "assembler" });
-  if (!existsSync28(chunksJsonPath)) {
+  if (!existsSync29(chunksJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/chunks.json: ${chunksJsonPath}`);
   }
-  const chunks = JSON.parse(readFileSync17(chunksJsonPath, "utf-8"));
+  const chunks = JSON.parse(readFileSync15(chunksJsonPath, "utf-8"));
   if (chunkPaths.length !== chunks.length) {
     throw new Error(
       `[assemble] chunkPaths length (${chunkPaths.length}) does not match chunks.json length (${chunks.length}). Adapters must pass one path per chunk, ordered by index.`
@@ -20997,7 +21165,7 @@ function readAssemblePlan(planDir, chunkPaths) {
     }
   }
   for (const path of chunkPaths.flat()) {
-    if (!existsSync28(path)) {
+    if (!existsSync29(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
   }
@@ -21131,13 +21299,13 @@ function stitchesSeparateAudio(planDir) {
   return lockedAudio(planDir).separateAudio === true;
 }
 function planFormat(planDir) {
-  const plan2 = JSON.parse(readFileSync17(join44(planDir, "plan.json"), "utf-8"));
+  const plan2 = JSON.parse(readFileSync15(join44(planDir, "plan.json"), "utf-8"));
   return plan2.dimensions.format;
 }
 function lockedAudio(planDir) {
   const encoderJsonPath = join44(planDir, "meta", "encoder.json");
-  if (!existsSync28(encoderJsonPath)) return {};
-  return JSON.parse(readFileSync17(encoderJsonPath, "utf-8"));
+  if (!existsSync29(encoderJsonPath)) return {};
+  return JSON.parse(readFileSync15(encoderJsonPath, "utf-8"));
 }
 function readCfrEncoder(planDir, format) {
   if (format !== "mp4") {
@@ -21146,10 +21314,10 @@ function readCfrEncoder(planDir, format) {
     );
   }
   const encoderJsonPath = join44(planDir, "meta", "encoder.json");
-  if (!existsSync28(encoderJsonPath)) {
+  if (!existsSync29(encoderJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
   }
-  const encoderJson = JSON.parse(readFileSync17(encoderJsonPath, "utf-8"));
+  const encoderJson = JSON.parse(readFileSync15(encoderJsonPath, "utf-8"));
   if (encoderJson.encoder === "libx265-software") {
     throw new Error(
       `[assemble] cfr=true is not yet supported with codec: "h265". The cfr re-encode pass uses libx264 and would silently transcode the h265 chunks. Either disable cfr or render with codec: "h264".`
@@ -21158,7 +21326,7 @@ function readCfrEncoder(planDir, format) {
   return encoderJson;
 }
 function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, startTimeMs) {
-  if (existsSync28(outputPath)) rmSync18(outputPath, { recursive: true, force: true });
+  if (existsSync29(outputPath)) rmSync18(outputPath, { recursive: true, force: true });
   mkdirSync20(outputPath, { recursive: true });
   let globalIdx = 0;
   for (const chunkDir of chunkPaths) {
@@ -21182,7 +21350,7 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
       `[assemble] png-sequence frame count mismatch: merged ${globalIdx} frames vs plan.totalFrames=${totalFrames}. Using on-disk count.`
     );
   }
-  if (audioPath !== null && existsSync28(audioPath)) {
+  if (audioPath !== null && existsSync29(audioPath)) {
     const sidecar = join44(outputPath, MIXED_AUDIO_FILENAME4);
     cpSync3(audioPath, sidecar);
   }