@hyperframes/producer 0.9.4 → 0.9.6

package/dist/index.js

@@ -1,3 +1,11 @@
+// src/index.ts
+import {
+  REFERENCE_BACKGROUND_FIELD as REFERENCE_BACKGROUND_FIELD7,
+  referenceBackgroundResult as referenceBackgroundResult9,
+  createReferenceBackgroundRecorder as createReferenceBackgroundRecorder3,
+  readReferenceBackground as readReferenceBackground2
+} from "@hyperframes/engine";
+
 // src/services/renderOrchestrator.ts
 import { audioFailureDiagnostics as audioFailureDiagnostics2 } from "@hyperframes/engine";
 import {
@@ -56,6 +64,10 @@ import {
   augmentProtocolTimeoutError,
   augmentPageNavigationTimeoutError
 } from "@hyperframes/engine";
+import {
+  referenceBackgroundResult,
+  createReferenceBackgroundRecorder
+} from "@hyperframes/engine";
 import { join as join28, dirname as dirname12, resolve as resolve8 } from "path";
 import { totalmem as totalmem2 } from "node:os";
 import { randomUUID } from "crypto";
@@ -8801,6 +8813,7 @@ async function runProbeStage(input) {
       const motionBlur = job.config.motionBlur;
       const captureFormat = resolveCaptureImageFormat({ needsAlpha, motionBlur });
       const captureOpts = {
+        recordReferenceBackground: input.recordReferenceBackground,
         width,
         height,
         fps: job.config.fps,
@@ -12479,6 +12492,17 @@ function applyRenderWarningPolicy(job, captureWarnings, log = defaultLogger) {
     throw new RenderQualityError(job.warnings);
   }
 }
+var stopPrepSessionOnScriptFailure = (options) => ({
+  ...options,
+  onSubTimelineScriptFailure: () => {
+    throw new Error("a composition script failed, so this preparation session stops");
+  }
+});
+var surfaceScriptFailure = (error, job) => error instanceof RenderQualityError || error instanceof RenderCancelledError || !job.warnings?.some((warning) => warning.code === "sub_timeline_script_failure") ? error : new RenderQualityError(job.warnings);
+var withScriptFailureStop = (options, job, log) => ({
+  ...options,
+  onSubTimelineScriptFailure: (warnings) => applyRenderWarningPolicy(job, warnings, log)
+});
 var RenderCancelledError = class extends Error {
   reason;
   constructor(message = "render_cancelled", reason = "aborted") {
@@ -12846,6 +12870,7 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
 }
 function createRenderJob(config) {
   return {
+    ...referenceBackgroundResult(void 0),
     id: randomUUID(),
     config: {
       ...config,
@@ -13611,6 +13636,9 @@ async function executeRenderPipeline(input) {
       cfg.protocolTimeout = scaledProtocolTimeout;
       updateCaptureObservability({ protocolTimeoutMs: scaledProtocolTimeout });
     }
+    const recordReferenceBackground = createReferenceBackgroundRecorder(
+      (result) => Object.assign(job, result)
+    );
     const subTimelineWaitMemo = {};
     const probeResult = await observeRenderStage(
       observability,
@@ -13631,7 +13659,8 @@ async function executeRenderPipeline(input) {
         height,
         needsAlpha,
         deviceScaleFactor,
-        subTimelineWaitMemo
+        subTimelineWaitMemo,
+        recordReferenceBackground
       }),
       // Browser probe is pre-capture; report `browser calibrating` so a
       // slow probe (~64s SwiftShader warm-up on Windows was the reported
@@ -13887,6 +13916,7 @@ async function executeRenderPipeline(input) {
     let routePageMotionBlur;
     const buildCaptureOptions = () => ({
       ...captureOptions,
+      recordReferenceBackground,
       ...routePageMotionBlur ? { pageMotionBlur: routePageMotionBlur } : {},
       videoMetadataHints,
       skipReadinessVideoIds: videoReadinessSkipIds,
@@ -13919,6 +13949,8 @@ async function executeRenderPipeline(input) {
         });
       }
     });
+    const buildPrepCaptureOptions = () => stopPrepSessionOnScriptFailure(buildCaptureOptions());
+    const buildWorkerCaptureOptions = () => withScriptFailureStop(buildCaptureOptions(), job, log);
     const createRenderVideoFrameInjector = () => createVideoFrameInjector(frameLookup, frameCacheOptions(cfg, workerCount));
     let captureCalibration;
     const htmlInCanvasDetected = compiled.renderModeHints.reasons.some(
@@ -14022,7 +14054,7 @@ async function executeRenderPipeline(input) {
         probeSession = await createCaptureSession8(
           activeFileServer.url,
           framesDir,
-          buildCaptureOptions(),
+          buildPrepCaptureOptions(),
           null,
           { ...cfg, forceScreenshot: captureForceScreenshot }
         );
@@ -14105,7 +14137,7 @@ async function executeRenderPipeline(input) {
           totalFrames,
           forceScreenshot: captureForceScreenshot,
           probeSession,
-          buildCaptureOptions,
+          buildCaptureOptions: buildPrepCaptureOptions,
           createRenderVideoFrameInjector,
           assertNotAborted
         }),
@@ -14577,7 +14609,7 @@ async function executeRenderPipeline(input) {
             effectiveBitrate,
             deliveryEncoder,
             fileServer: activeFileServer,
-            buildCaptureOptions,
+            buildCaptureOptions: buildWorkerCaptureOptions,
             createRenderVideoFrameInjector,
             hdrDiagnostics,
             abortSignal: attempt,
@@ -14695,7 +14727,7 @@ async function executeRenderPipeline(input) {
                 // Each segment sets its own GOP (at most the interval); hls never reaches this route.
                 ...deliveryEncoder
               },
-              buildCaptureOptions,
+              buildCaptureOptions: buildWorkerCaptureOptions,
               createRenderVideoFrameInjector,
               abortSignal: executionSignal,
               assertNotAborted,
@@ -14843,7 +14875,7 @@ async function executeRenderPipeline(input) {
                 // encoder's open-GOP output untouched.
                 ...deliveryEncoder
               },
-              buildCaptureOptions,
+              buildCaptureOptions: buildWorkerCaptureOptions,
               createRenderVideoFrameInjector,
               abortSignal: executionSignal,
               assertNotAborted,
@@ -15028,7 +15060,7 @@ async function executeRenderPipeline(input) {
             probeSession,
             captureAttempts,
             dedupPerfs,
-            buildCaptureOptions,
+            buildCaptureOptions: buildWorkerCaptureOptions,
             createRenderVideoFrameInjector,
             abortSignal: executionSignal,
             assertNotAborted,
@@ -15261,7 +15293,7 @@ async function executeRenderPipeline(input) {
     await eventPublisher.flush();
   } catch (caught) {
     await pendingAudio;
-    const error = tooSlowError ?? caught;
+    const error = surfaceScriptFailure(tooSlowError ?? caught, job);
     if (!tooSlowError && (error instanceof RenderCancelledError || executionSignal?.aborted)) {
       job.error = error instanceof Error ? error.message : "render_cancelled";
       updateJobStatus(job, "cancelled", "Render cancelled", job.progress, onProgress);
@@ -15353,8 +15385,12 @@ async function executeRenderPipeline(input) {
 }
 
 // src/services/distributed/renderSpan.ts
+import {
+  REFERENCE_BACKGROUND_FIELD as REFERENCE_BACKGROUND_FIELD4,
+  referenceBackgroundResult as referenceBackgroundResult6
+} from "@hyperframes/engine";
 import { mkdirSync as mkdirSync18, mkdtempSync as mkdtempSync7, readFileSync as readFileSync13, rmSync as rmSync16 } from "node:fs";
-import { join as join41 } from "node:path";
+import { join as join42 } from "node:path";
 import { tmpdir as tmpdir4 } from "node:os";
 
 // src/services/distributed/mp4Stitch.ts
@@ -15741,6 +15777,11 @@ async function writeStitchedMp4(chunkPaths, outputPath, audioPath) {
 }
 
 // src/services/distributed/plan.ts
+import {
+  REFERENCE_BACKGROUND_FIELD as REFERENCE_BACKGROUND_FIELD2,
+  referenceBackgroundResult as referenceBackgroundResult4,
+  createReferenceBackgroundRecorder as createReferenceBackgroundRecorder2
+} from "@hyperframes/engine";
 import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframes/engine";
 import {
   copyFileSync as copyFileSync6,
@@ -15751,7 +15792,7 @@ import {
   rmSync as rmSync12,
   writeFileSync as writeFileSync9
 } from "node:fs";
-import { extname as extname6, isAbsolute as isAbsolute3, join as join36, relative as relative5, sep as sep2 } from "node:path";
+import { extname as extname6, isAbsolute as isAbsolute3, join as join37, relative as relative5, sep as sep2 } from "node:path";
 import {
   fpsToNumber as fpsToNumber9,
   HF_COLOR_GRADING_ATTR as HF_COLOR_GRADING_ATTR2
@@ -16396,9 +16437,69 @@ function buildWeightedChunkSlices(weights, chunkCount, minFrames, maxFrames) {
   return slices;
 }
 
+// src/services/render/planReferenceBackground.ts
+import { join as join33 } from "node:path";
+import {
+  closeCaptureSession as closeCaptureSession10,
+  createCaptureSession as createCaptureSession10,
+  readReferenceBackground,
+  referenceBackgroundResult as referenceBackgroundResult2
+} from "@hyperframes/engine";
+async function readPlanReferenceBackground(input) {
+  let server;
+  let session;
+  try {
+    server = await createFileServer({
+      projectDir: input.projectDir,
+      compiledDir: join33(input.workDir, "compiled"),
+      port: 0,
+      preHeadScripts: [VIRTUAL_TIME_SHIM],
+      fps: input.options.fps
+    });
+    session = await createCaptureSession10(
+      server.url,
+      join33(input.workDir, "reference"),
+      {
+        ...input.options,
+        requiresWebGpu: false
+      },
+      null,
+      {
+        ...input.cfg,
+        forceScreenshot: true,
+        useDrawElement: false,
+        enablePageSideCompositing: false
+      }
+    );
+    const page = session.page;
+    await page.goto(`${server.url}/index.html`, {
+      waitUntil: "domcontentloaded",
+      timeout: input.cfg.pageNavigationTimeout
+    });
+    await page.evaluate("window.__hfFlushSync?.()");
+    await page.waitForFunction(
+      '!!(window.__hf && typeof window.__hf.seek === "function" && window.__hf.duration > 0)',
+      { timeout: input.cfg.playerReadyTimeout, polling: 100 }
+    );
+    return referenceBackgroundResult2(await readReferenceBackground(page));
+  } catch (error) {
+    input.log.debug("Reference background unavailable", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return referenceBackgroundResult2(void 0);
+  } finally {
+    if (session) await closeCaptureSession10(session).catch(() => void 0);
+    if (server) closeFileServerSafely(server, "reference background", input.log);
+  }
+}
+
 // src/services/render/stages/freezePlan.ts
 import { existsSync as existsSync21, mkdirSync as mkdirSync12, readFileSync as readFileSync9, readdirSync as readdirSync7, writeFileSync as writeFileSync7 } from "node:fs";
-import { join as join33, relative as relative3, resolve as resolve9 } from "node:path";
+import { join as join34, relative as relative3, resolve as resolve9 } from "node:path";
+import {
+  REFERENCE_BACKGROUND_FIELD,
+  referenceBackgroundResult as referenceBackgroundResult3
+} from "@hyperframes/engine";
 
 // src/services/distributed/planProtocol.ts
 var PLAN_SCHEMA_VERSION = 1;
@@ -16612,7 +16713,7 @@ function listPlanFiles(planDir) {
   function walk(dir) {
     const entries = readdirSync7(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const full = join33(dir, entry.name);
+      const full = join34(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
       } else if (entry.isFile()) {
@@ -16653,15 +16754,15 @@ var PLAN_REMOTE_FILES_RELATIVE_PATH = "meta/remote-files.json";
 function writePlanRemoteFiles(planDir, files) {
   if (files.length === 0) return;
   const sorted = [...files].sort((a, b) => a.path < b.path ? -1 : 1);
-  writeFileSync7(join33(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH), JSON.stringify(sorted), "utf-8");
+  writeFileSync7(join34(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH), JSON.stringify(sorted), "utf-8");
 }
 function readPlanRemoteFiles(planDir) {
-  const path = join33(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
+  const path = join34(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
   return existsSync21(path) ? JSON.parse(readFileSync9(path, "utf-8")) : [];
 }
 function recomputePlanHashFromPlanDir(planDir, digests) {
-  const planJsonPath = join33(planDir, "plan.json");
-  const encoderJsonPath = join33(planDir, "meta", "encoder.json");
+  const planJsonPath = join34(planDir, "plan.json");
+  const encoderJsonPath = join34(planDir, "meta", "encoder.json");
   if (!existsSync21(planJsonPath)) {
     throw new Error(`[freezePlan] plan.json missing: ${planJsonPath}`);
   }
@@ -16698,18 +16799,18 @@ async function freezePlan(input) {
   if (!existsSync21(planDir)) {
     throw new Error(`[freezePlan] planDir does not exist: ${planDir}`);
   }
-  const metaDir = join33(planDir, "meta");
+  const metaDir = join34(planDir, "meta");
   if (!existsSync21(metaDir)) mkdirSync12(metaDir, { recursive: true });
   writeFileSync7(
-    join33(metaDir, "composition.json"),
+    join34(metaDir, "composition.json"),
     `${JSON.stringify(composition, null, 2)}
 `,
     "utf-8"
   );
   const encoderForCanonical = stripUndefined(encoder);
   const encoderConfigCanonicalJson = canonicalJsonStringify(encoderForCanonical);
-  writeFileSync7(join33(metaDir, "encoder.json"), encoderConfigCanonicalJson, "utf-8");
-  writeFileSync7(join33(metaDir, "chunks.json"), `${JSON.stringify(chunks, null, 2)}
+  writeFileSync7(join34(metaDir, "encoder.json"), encoderConfigCanonicalJson, "utf-8");
+  writeFileSync7(join34(metaDir, "chunks.json"), `${JSON.stringify(chunks, null, 2)}
 `, "utf-8");
   const { compositionHtml, assets } = collectPlanAssetShas(planDir, digests);
   const planHash = computePlanHash({
@@ -16722,6 +16823,7 @@ async function freezePlan(input) {
     dimensions
   });
   const planJson = {
+    ...referenceBackgroundResult3(composition[REFERENCE_BACKGROUND_FIELD]),
     protocol: PLAN_PROTOCOL_V1,
     planHash,
     producerVersion,
@@ -16733,7 +16835,7 @@ async function freezePlan(input) {
     duration: durationSeconds,
     hasAudio
   };
-  const planJsonPath = join33(planDir, "plan.json");
+  const planJsonPath = join34(planDir, "plan.json");
   writeFileSync7(planJsonPath, `${JSON.stringify(planJson, null, 2)}
 `, "utf-8");
   return { planJsonPath, planHash };
@@ -16777,7 +16879,7 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
 // src/services/distributed/chunkAudio.ts
 import { closeSync as closeSync6, existsSync as existsSync22, ftruncateSync, mkdirSync as mkdirSync13, openSync as openSync6, readFileSync as readFileSync10 } from "node:fs";
 import { writeFileSync as writeFileSync8, writeSync } from "node:fs";
-import { join as join34 } from "node:path";
+import { join as join35 } from "node:path";
 import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure4, runFfmpeg as runFfmpeg7 } from "@hyperframes/engine";
 function audioCutForChunk(grid, chunks, index, fps) {
   const firstPacketAt = (frame) => Math.min(
@@ -16865,7 +16967,7 @@ async function writeChunkAudioSlices(input) {
   });
   const bytes = readFileSync10(input.audioPath);
   const layout = { sizeBytes: bytes.length, payloadStart, payloadEnd, partStarts: {} };
-  mkdirSync13(join34(input.planDir, SLICE_DIR), { recursive: true });
+  mkdirSync13(join35(input.planDir, SLICE_DIR), { recursive: true });
   input.chunks.forEach((_, index) => {
     const cut = audioCutForChunk(grid, input.chunks, index, input.fps);
     if (!cut) return;
@@ -16873,17 +16975,17 @@ async function writeChunkAudioSlices(input) {
     const start = offsets[cut.firstPacket];
     layout.partStarts[index] = start;
     const end = offsets[last] + track.sizes[last];
-    writeFileSync8(join34(input.planDir, chunkAudioSlicePath(index)), bytes.subarray(start, end));
+    writeFileSync8(join35(input.planDir, chunkAudioSlicePath(index)), bytes.subarray(start, end));
   });
   const frame = [bytes.subarray(0, payloadStart), bytes.subarray(payloadEnd)];
-  writeFileSync8(join34(input.planDir, SLICE_FRAME), Buffer.concat(frame));
-  writeFileSync8(join34(input.planDir, SLICE_LAYOUT), JSON.stringify(layout));
+  writeFileSync8(join35(input.planDir, SLICE_FRAME), Buffer.concat(frame));
+  writeFileSync8(join35(input.planDir, SLICE_LAYOUT), JSON.stringify(layout));
 }
 function chunkAudioSource(planDir, chunkIndex, scratchPath) {
-  const layoutPath = join34(planDir, SLICE_LAYOUT);
+  const layoutPath = join35(planDir, SLICE_LAYOUT);
   if (!existsSync22(layoutPath)) return resolvePlanAudioPath(planDir);
   const layout = JSON.parse(readFileSync10(layoutPath, "utf-8"));
-  const frame = readFileSync10(join34(planDir, SLICE_FRAME));
+  const frame = readFileSync10(join35(planDir, SLICE_FRAME));
   const fd = openSync6(scratchPath, "w");
   try {
     writeSync(fd, frame, 0, layout.payloadStart, 0);
@@ -16896,7 +16998,7 @@ function chunkAudioSource(planDir, chunkIndex, scratchPath) {
     );
     const start = layout.partStarts[chunkIndex];
     if (start !== void 0) {
-      const part = readFileSync10(join34(planDir, chunkAudioSlicePath(chunkIndex)));
+      const part = readFileSync10(join35(planDir, chunkAudioSlicePath(chunkIndex)));
       writeSync(fd, part, 0, part.length, start);
     }
     ftruncateSync(fd, layout.sizeBytes);
@@ -16952,7 +17054,7 @@ async function muxChunkWithAudio(input) {
 // src/services/distributed/planSize.ts
 import { createHash as createHash9 } from "node:crypto";
 import { lstatSync as lstatSync2, readdirSync as readdirSync8 } from "node:fs";
-import { extname as extname5, join as join35, relative as relative4 } from "node:path";
+import { extname as extname5, join as join36, relative as relative4 } from "node:path";
 var MAX_TOP_COMPONENTS = 10;
 var SOURCE_MEDIA_EXTENSIONS = /* @__PURE__ */ new Set([
   ".aac",
@@ -17064,7 +17166,7 @@ function walkRegularFiles(dir, visit) {
     return;
   }
   for (const entry of entries) {
-    const full = join35(dir, entry.name);
+    const full = join36(dir, entry.name);
     if (entry.isDirectory()) {
       walkRegularFiles(full, visit);
     } else if (entry.isFile()) {
@@ -17276,13 +17378,13 @@ function assertPositiveInteger2(name, value) {
 }
 var FREEZE_OWNED_PLAN_FILES = [
   "plan.json",
-  join36("meta", "composition.json"),
-  join36("meta", "encoder.json"),
-  join36("meta", "chunks.json")
+  join37("meta", "composition.json"),
+  join37("meta", "encoder.json"),
+  join37("meta", "chunks.json")
 ];
 function removeFreezeOwnedPlanFiles(planDir) {
   for (const relativePath of FREEZE_OWNED_PLAN_FILES) {
-    rmSync12(join36(planDir, relativePath), { force: true });
+    rmSync12(join37(planDir, relativePath), { force: true });
   }
 }
 function buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize) {
@@ -17437,19 +17539,19 @@ function createVideoSourceShipper(input) {
     const known = shipped.get(srcPath);
     if (known) return known;
     const stagedRel = pathInside(input.workVideoFramesDir, srcPath);
-    const current = stagedRel === null ? srcPath : join36(input.planDir, "video-frames", stagedRel);
+    const current = stagedRel === null ? srcPath : join37(input.planDir, "video-frames", stagedRel);
     let result = null;
     for (const root of stagedRel === null ? [input.workCompiledDir, input.projectDir] : []) {
       const rel = pathInside(root, srcPath);
-      if (rel !== null && (existsSync23(join36(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
+      if (rel !== null && (existsSync23(join37(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
         result = ["compiled", ...rel.split(sep2)].join("/");
         break;
       }
     }
     if (result === null) {
       result = `video-sources/${shipped.size}${extname6(current)}`;
-      const destination = join36(input.planDir, ...result.split("/"));
-      mkdirSync14(join36(input.planDir, "video-sources"), { recursive: true });
+      const destination = join37(input.planDir, ...result.split("/"));
+      mkdirSync14(join37(input.planDir, "video-sources"), { recursive: true });
       try {
         linkSync(current, destination);
       } catch {
@@ -17498,14 +17600,14 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     variables: config.variables
   });
   const entryFile = config.entryFile ?? "index.html";
-  const htmlPath = join36(projectDir, entryFile);
+  const htmlPath = join37(projectDir, entryFile);
   if (!existsSync23(htmlPath)) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
-  const workDir = join36(planDir, ".plan-work");
+  const workDir = join37(planDir, ".plan-work");
   rmSync12(workDir, { recursive: true, force: true });
   mkdirSync14(workDir, { recursive: true });
-  const compiledDir = join36(workDir, "compiled");
+  const compiledDir = join37(workDir, "compiled");
   mkdirSync14(compiledDir, { recursive: true });
   let stageStarted = Date.now();
   cpSync2(projectDir, compiledDir, {
@@ -17519,10 +17621,10 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     }
   });
   logPlanStage(log, "copy", stageStarted);
-  const finalCompiledDir = join36(planDir, "compiled");
+  const finalCompiledDir = join37(planDir, "compiled");
   const needsAlpha = outputNeedsAlpha(config.format);
   const remoteFiles = Object.entries(options.remoteFiles ?? {});
-  const remoteLocalPath = (rel) => join36(projectDir, ...rel.split("/"));
+  const remoteLocalPath = (rel) => join37(projectDir, ...rel.split("/"));
   for (const [, file] of remoteFiles) {
     declareContentAddressedUrl(file.url, file.sha256);
     if (file.probeFactsUrl) declareProbeFactsUrl(file.url, file.probeFactsUrl);
@@ -17572,6 +17674,9 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   }
   stageStarted = Date.now();
   const probeResult = await runProbeStage({
+    recordReferenceBackground: createReferenceBackgroundRecorder2(
+      (result) => Object.assign(job, result)
+    ),
     projectDir,
     workDir,
     job,
@@ -17589,6 +17694,21 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     subTimelineWaitMemo: {}
   });
   logPlanStage(log, "probe", stageStarted);
+  if (!probeResult.probeSession) {
+    stageStarted = Date.now();
+    Object.assign(
+      job,
+      await readPlanReferenceBackground({
+        projectDir,
+        workDir,
+        cfg,
+        log,
+        options: { width, height, fps: job.config.fps, variables: job.config.variables }
+      })
+    );
+    assertNotAborted();
+    logPlanStage(log, "reference_background", stageStarted);
+  }
   compiled = probeResult.compiled;
   job.duration = probeResult.duration;
   job.totalFrames = probeResult.totalFrames;
@@ -17601,8 +17721,8 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   if (probeResult.fileServer) closeFileServerSafely(probeResult.fileServer, "plan", log);
   if (probeResult.probeSession) {
     try {
-      const { closeCaptureSession: closeCaptureSession12 } = await import("@hyperframes/engine");
-      await closeCaptureSession12(probeResult.probeSession);
+      const { closeCaptureSession: closeCaptureSession13 } = await import("@hyperframes/engine");
+      await closeCaptureSession13(probeResult.probeSession);
     } catch (err) {
       log.warn("[plan] probe session close failed", {
         error: err instanceof Error ? err.message : String(err)
@@ -17708,10 +17828,10 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   let stageStarted = Date.now();
   const extractResult = await extractPlanVideos(c, options.deferVideoExtraction);
   logPlanStage(log, "extract", stageStarted);
-  const stagedVideoFrames = join36(compiledDir, "__hyperframes_video_frames");
-  const videoFramesDst = join36(planDir, "video-frames");
+  const stagedVideoFrames = join37(compiledDir, "__hyperframes_video_frames");
+  const videoFramesDst = join37(planDir, "video-frames");
   if (existsSync23(videoFramesDst)) rmSync12(videoFramesDst, { recursive: true, force: true });
-  const videoSourcesDir = join36(planDir, "video-sources");
+  const videoSourcesDir = join37(planDir, "video-sources");
   rmSync12(videoSourcesDir, { recursive: true, force: true });
   if (existsSync23(stagedVideoFrames)) {
     renameWithRetry8(stagedVideoFrames, videoFramesDst);
@@ -17748,7 +17868,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
       };
     })
   });
-  mkdirSync14(join36(planDir, "meta"), { recursive: true });
+  mkdirSync14(join37(planDir, "meta"), { recursive: true });
   writePlanRemoteFiles(
     planDir,
     remoteFiles.map(([rel, { sha256, sizeBytes }]) => ({
@@ -17758,7 +17878,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     }))
   );
   writeFileSync9(
-    join36(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
+    join37(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
     JSON.stringify(planVideosJson, null, 2),
     "utf-8"
   );
@@ -17837,7 +17957,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   if (audioResult?.audioError) {
     applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);
   }
-  const planAudioPath = join36(planDir, PLAN_AUDIO_RELATIVE_PATH);
+  const planAudioPath = join37(planDir, PLAN_AUDIO_RELATIVE_PATH);
   if (audioResult?.hasAudio && existsSync23(audioResult.audioOutputPath)) {
     renameWithRetry8(audioResult.audioOutputPath, planAudioPath);
   }
@@ -17870,6 +17990,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     separateAudio
   });
   const compositionJson = {
+    ...referenceBackgroundResult4(job[REFERENCE_BACKGROUND_FIELD2]),
     durationSeconds: job.duration ?? 0,
     width,
     height,
@@ -17925,6 +18046,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     log
   });
   return {
+    ...referenceBackgroundResult4(job[REFERENCE_BACKGROUND_FIELD2]),
     executionPlanDir: planDir,
     executionPlanHash: planHash,
     chunkCount,
@@ -17940,6 +18062,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
 async function plan(projectDir, config, planDir, options = {}) {
   const executionPlan = await buildLocalExecutionPlan(projectDir, config, planDir, options);
   return {
+    ...referenceBackgroundResult4(executionPlan[REFERENCE_BACKGROUND_FIELD2]),
     planDir: executionPlan.executionPlanDir,
     planProtocol: PLAN_PROTOCOL_V1,
     planHash: executionPlan.executionPlanHash,
@@ -17958,14 +18081,14 @@ async function plan(projectDir, config, planDir, options = {}) {
 import { randomBytes } from "node:crypto";
 import { existsSync as existsSync26, 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 join40 } from "node:path";
+import { join as join41 } from "node:path";
 import {
   assertSwiftShader,
   BROWSER_GPU_NOT_SOFTWARE as BROWSER_GPU_NOT_SOFTWARE4,
   calculateOptimalWorkers as calculateOptimalWorkers2,
   classifyCaptureFailure as classifyCaptureFailure4,
-  closeCaptureSession as closeCaptureSession10,
-  createCaptureSession as createCaptureSession10,
+  closeCaptureSession as closeCaptureSession11,
+  createCaptureSession as createCaptureSession11,
   createFrameLookupTable as createFrameLookupTable5,
   deriveBeginFrameProbeTimeTicks as deriveBeginFrameProbeTimeTicks2,
   getEncoderPreset as getEncoderPreset5,
@@ -17977,6 +18100,10 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/distributed/planV2.ts
+import {
+  REFERENCE_BACKGROUND_FIELD as REFERENCE_BACKGROUND_FIELD3,
+  referenceBackgroundResult as referenceBackgroundResult5
+} from "@hyperframes/engine";
 import {
   copyFileSync as copyFileSync8,
   existsSync as existsSync25,
@@ -17990,7 +18117,7 @@ import {
   writeFileSync as writeFileSync11
 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
-import { dirname as dirname16, isAbsolute as isAbsolute4, join as join39, relative as relative6, resolve as resolve10, sep as sep3 } from "node:path";
+import { dirname as dirname16, isAbsolute as isAbsolute4, join as join40, relative as relative6, resolve as resolve10, sep as sep3 } from "node:path";
 import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
 import { createFrameLookupTable as createFrameLookupTable4, renameWithRetry as renameWithRetry10 } from "@hyperframes/engine";
 
@@ -18006,7 +18133,7 @@ import {
   writeFileSync as writeFileSync10
 } from "node:fs";
 import { renameWithRetry as renameWithRetry9 } from "@hyperframes/engine";
-import { dirname as dirname15, join as join38 } from "node:path";
+import { dirname as dirname15, join as join39 } from "node:path";
 
 // src/services/distributed/planV2Errors.ts
 var PLAN_V2_INTEGRITY_UNRECOVERABLE = "PLAN_V2_INTEGRITY_UNRECOVERABLE";
@@ -18021,7 +18148,7 @@ var PlanV2IntegrityError = class extends Error {
 };
 
 // src/services/distributed/planV2Layout.ts
-import { join as join37 } from "node:path";
+import { join as join38 } from "node:path";
 var SHA256_PATTERN = /^[0-9a-f]{64}$/;
 function assertPlanV2Sha256(value, field) {
   if (typeof value !== "string" || !SHA256_PATTERN.test(value)) {
@@ -18031,7 +18158,7 @@ function assertPlanV2Sha256(value, field) {
 }
 function planV2BlobPath(root, sha256) {
   const digest = assertPlanV2Sha256(sha256, "artifact sha256");
-  return join37(root, "artifacts", "sha256", digest.slice(0, 2), digest);
+  return join38(root, "artifacts", "sha256", digest.slice(0, 2), digest);
 }
 
 // src/services/distributed/planV2Publisher.ts
@@ -18072,7 +18199,7 @@ var LocalPlanV2ArtifactPublisher = class {
     this.destinationDir = destinationDir;
     this.#linkFile = options.linkFile ?? linkSync2;
     mkdirSync15(dirname15(destinationDir), { recursive: true });
-    this.temporaryDir = mkdtempSync5(join38(dirname15(destinationDir), ".plan-v2-publish-"));
+    this.temporaryDir = mkdtempSync5(join39(dirname15(destinationDir), ".plan-v2-publish-"));
   }
   async putBlob(blob) {
     const digest = assertPlanV2Sha256(blob.sha256, "published blob sha256");
@@ -18085,8 +18212,8 @@ var LocalPlanV2ArtifactPublisher = class {
     const destinationPath = planV2BlobPath(this.temporaryDir, digest);
     if (existsSync24(destinationPath)) return;
     mkdirSync15(dirname15(destinationPath), { recursive: true });
-    const stagingDir = mkdtempSync5(join38(dirname15(destinationPath), ".plan-v2-blob-"));
-    const temporaryPath = join38(stagingDir, "blob");
+    const stagingDir = mkdtempSync5(join39(dirname15(destinationPath), ".plan-v2-blob-"));
+    const temporaryPath = join39(stagingDir, "blob");
     try {
       try {
         this.#linkFile(blob.sourcePath, temporaryPath);
@@ -18107,7 +18234,7 @@ var LocalPlanV2ArtifactPublisher = class {
         );
       }
     }
-    writeFileSync10(join38(this.temporaryDir, "plan.json"), manifestBytes, "utf-8");
+    writeFileSync10(join39(this.temporaryDir, "plan.json"), manifestBytes, "utf-8");
     renameWithRetry9(this.temporaryDir, this.destinationDir);
     this.#committed = true;
   }
@@ -18152,7 +18279,7 @@ function listFiles(root) {
   const rootResolved = resolve10(root);
   function walk(dir) {
     for (const entry of readdirSync9(dir, { withFileTypes: true })) {
-      const absolutePath = join39(dir, entry.name);
+      const absolutePath = join40(dir, entry.name);
       if (entry.isDirectory()) {
         walk(absolutePath);
       } else if (entry.isFile()) {
@@ -18179,13 +18306,13 @@ function assertValidExtractionCacheCompleteSentinel(path) {
   }
 }
 function validateExtractionCacheCompleteSentinels(executionPlanDir) {
-  const videoRoot = join39(executionPlanDir, "video-frames");
+  const videoRoot = join40(executionPlanDir, "video-frames");
   if (!existsSync25(videoRoot)) return;
   for (const videoEntry of readdirSync9(videoRoot, { withFileTypes: true })) {
     if (!videoEntry.isDirectory()) continue;
-    const videoDir = join39(videoRoot, videoEntry.name);
+    const videoDir = join40(videoRoot, videoEntry.name);
     if (readdirSync9(videoDir).includes(EXTRACTION_CACHE_COMPLETE_SENTINEL)) {
-      const sentinelPath = join39(videoDir, EXTRACTION_CACHE_COMPLETE_SENTINEL);
+      const sentinelPath = join40(videoDir, EXTRACTION_CACHE_COMPLETE_SENTINEL);
       assertValidExtractionCacheCompleteSentinel(sentinelPath);
     }
   }
@@ -18232,7 +18359,7 @@ function listVideoFramePaths(executionPlanDir, videos) {
     if (video.deferredRange) {
       const framePaths2 = /* @__PURE__ */ new Map();
       for (let index = 0; index < video.totalFrames; index++) {
-        framePaths2.set(index, join39(outputDir, String(index)));
+        framePaths2.set(index, join40(outputDir, String(index)));
       }
       return { ...video, outputDir, framePaths: framePaths2, ownedByLookup: false };
     }
@@ -18240,7 +18367,7 @@ function listVideoFramePaths(executionPlanDir, videos) {
     const framePaths = /* @__PURE__ */ new Map();
     for (const frameName of frameNames) {
       if (frameName === EXTRACTION_CACHE_COMPLETE_SENTINEL) {
-        assertValidExtractionCacheCompleteSentinel(join39(outputDir, frameName));
+        assertValidExtractionCacheCompleteSentinel(join40(outputDir, frameName));
         continue;
       }
       const match = /(\d+)(?=\.[^.]+$)/.exec(frameName);
@@ -18259,7 +18386,7 @@ function listVideoFramePaths(executionPlanDir, videos) {
           `duplicate extracted frame index ${frameIndex} in ${outputDir}`
         );
       }
-      framePaths.set(frameIndex, join39(outputDir, frameName));
+      framePaths.set(frameIndex, join40(outputDir, frameName));
     }
     return {
       ...video,
@@ -18280,7 +18407,7 @@ function parsePlanVideosJson2(value) {
   }
 }
 function materializeExtractedVideoDirectories(planDir) {
-  const videosPath = join39(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
+  const videosPath = join40(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   if (!existsSync25(videosPath)) return;
   const videos = parsePlanVideosJson2(readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH));
   for (const video of videos.extracted) {
@@ -18314,13 +18441,13 @@ function parseChunkSlices(value) {
   });
 }
 function buildVideoChunkDependencies(executionPlanDir, dimensions) {
-  const videoRoot = join39(executionPlanDir, "video-frames");
+  const videoRoot = join40(executionPlanDir, "video-frames");
   const hasExtractedFrames = existsSync25(videoRoot) && listFiles(videoRoot).length > 0;
-  const videosPath = join39(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
+  const videosPath = join40(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   if (!existsSync25(videosPath)) {
     return hasExtractedFrames ? { mode: "full-source-pack", dependencies: null } : { mode: "exact-rendered-frames", dependencies: /* @__PURE__ */ new Map() };
   }
-  const chunksPath = join39(executionPlanDir, "meta", "chunks.json");
+  const chunksPath = join40(executionPlanDir, "meta", "chunks.json");
   const videos = readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH);
   const chunks = readJsonFile(chunksPath, "meta/chunks.json");
   const parsedVideos = parsePlanVideosJson2(videos);
@@ -18376,8 +18503,8 @@ function computeManifestHash(manifest) {
 function writeBlob(sourcePath, destinationPath) {
   if (existsSync25(destinationPath)) return;
   mkdirSync16(dirname16(destinationPath), { recursive: true });
-  const temporaryDir = mkdtempSync6(join39(dirname16(destinationPath), ".plan-v2-blob-"));
-  const temporaryPath = join39(temporaryDir, "blob");
+  const temporaryDir = mkdtempSync6(join40(dirname16(destinationPath), ".plan-v2-blob-"));
+  const temporaryPath = join40(temporaryDir, "blob");
   try {
     copyFileSync8(sourcePath, temporaryPath);
     renameWithRetry10(temporaryPath, destinationPath);
@@ -18413,7 +18540,7 @@ async function putTasks(tasks) {
   if (failure) throw failure.reason;
 }
 function buildPlanV2Publication(executionPlanDir, digests) {
-  const executionPlanPath = join39(executionPlanDir, "plan.json");
+  const executionPlanPath = join40(executionPlanDir, "plan.json");
   if (!existsSync25(executionPlanPath)) {
     throw new PlanV2IntegrityError(`execution plan is missing plan.json: ${executionPlanPath}`);
   }
@@ -18441,7 +18568,7 @@ function buildPlanV2Publication(executionPlanDir, digests) {
   }
   validateExtractionCacheCompleteSentinels(executionPlanDir);
   const videoDependencyPlan = buildVideoChunkDependencies(executionPlanDir, dimensions);
-  const encoder = readJsonFile(join39(executionPlanDir, "meta", "encoder.json"), "meta/encoder.json");
+  const encoder = readJsonFile(join40(executionPlanDir, "meta", "encoder.json"), "meta/encoder.json");
   const files = listFiles(executionPlanDir);
   const chunkAudio = !isRecord3(encoder) || encoder.chunksCarryAudio !== true ? "none" : files.some((file) => chunkAudioSliceTarget(file.path) !== null) ? "sliced" : "whole";
   for (const file of files) {
@@ -18502,13 +18629,13 @@ function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
     throw new PlanV2IntegrityError("a local plan v2 directory cannot reference remote files");
   }
   mkdirSync16(dirname16(planV2Dir), { recursive: true });
-  const tempDir = mkdtempSync6(join39(dirname16(planV2Dir), ".plan-v2-build-"));
+  const tempDir = mkdtempSync6(join40(dirname16(planV2Dir), ".plan-v2-build-"));
   try {
     for (const blob of publication.blobs) {
       writeBlob(blob.sourcePath, planV2BlobPath(tempDir, blob.sha256));
     }
     writeFileSync11(
-      join39(tempDir, "plan.json"),
+      join40(tempDir, "plan.json"),
       canonicalJsonStringify(publication.manifest),
       "utf-8"
     );
@@ -18549,7 +18676,7 @@ async function publishExecutionPlan(executionPlanDir, publisher, { digests, log
   }
 }
 async function planV2WithPublisher(projectDir, config, publisher, options = {}) {
-  const stagingRoot = mkdtempSync6(join39(options.stagingParentDir ?? tmpdir3(), ".execution-plan-"));
+  const stagingRoot = mkdtempSync6(join40(options.stagingParentDir ?? tmpdir3(), ".execution-plan-"));
   const digests = /* @__PURE__ */ new Map();
   try {
     await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
@@ -18560,7 +18687,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
       // artifactTargets ships every compiled/ file to all chunks, so each is in the manifest.
       whileAudioMixes: () => putBlobs(
         publisher,
-        listFiles(join39(stagingRoot, "compiled")).map(
+        listFiles(join40(stagingRoot, "compiled")).map(
           (file) => publishBlobFor(file.absolutePath, digests)
         )
       ),
@@ -18590,9 +18717,14 @@ async function planV2(projectDir, config, planV2Dir) {
   return resultFromManifest(planV2Dir, manifest);
 }
 function resultFromManifest(planV2Dir, manifest) {
+  const artifact = manifest.artifacts.find((entry) => entry.path === "plan.json");
+  const executionPlan = artifact ? readJsonFile(verifyBlob(planV2Dir, artifact), "execution plan.json") : null;
   return {
+    ...referenceBackgroundResult5(
+      isRecord3(executionPlan) ? executionPlan[REFERENCE_BACKGROUND_FIELD3] : void 0
+    ),
     planDir: planV2Dir,
-    manifestPath: join39(planV2Dir, "plan.json"),
+    manifestPath: join40(planV2Dir, "plan.json"),
     planProtocol: PLAN_PROTOCOL_V2,
     planHash: manifest.planHash,
     sourcePlanV1Hash: getPlanV2ExecutionPlanHash(manifest),
@@ -18728,7 +18860,7 @@ function parsePlanV2Manifest(value) {
   return parsed;
 }
 function readPlanV2Manifest(planV2Dir) {
-  const manifestPath = join39(planV2Dir, "plan.json");
+  const manifestPath = join40(planV2Dir, "plan.json");
   if (!existsSync25(manifestPath)) {
     throw new PlanV2IntegrityError(`missing v2 manifest: ${manifestPath}`);
   }
@@ -18774,16 +18906,16 @@ function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}
     sourcePath: verifyBlob(planV2Dir, artifact)
   }));
   mkdirSync16(dirname16(destinationDir), { recursive: true });
-  const tempDir = mkdtempSync6(join39(dirname16(destinationDir), ".plan-v2-materialize-"));
+  const tempDir = mkdtempSync6(join40(dirname16(destinationDir), ".plan-v2-materialize-"));
   try {
     for (const { artifact, sourcePath } of verified) {
-      const destinationPath = join39(tempDir, ...artifact.path.split("/"));
+      const destinationPath = join40(tempDir, ...artifact.path.split("/"));
       mkdirSync16(dirname16(destinationPath), { recursive: true });
       copyFileSync8(sourcePath, destinationPath);
     }
     if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
     writeFileSync11(
-      join39(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
+      join40(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
       canonicalJsonStringify({
         manifest,
         target,
@@ -18806,7 +18938,7 @@ function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}
     // Join the artifact's OWN name, not the current constant: a plan written
     // before the container change carries the legacy name, and materializing it
     // under the new one would point at a file that was never written.
-    audioPath: target.role === "assembler" ? audioArtifact ? join39(destinationDir, audioArtifact.path) : null : null
+    audioPath: target.role === "assembler" ? audioArtifact ? join40(destinationDir, audioArtifact.path) : null : null
   };
 }
 function assertRemoteSources(remoteSources, artifacts) {
@@ -18825,7 +18957,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
   return readValidatedPlanV2Materialization(planDir, expectedTarget)?.manifest ?? null;
 }
 function readValidatedPlanV2Materialization(planDir, expectedTarget) {
-  const markerPath = join39(planDir, PLAN_V2_MATERIALIZATION_MARKER);
+  const markerPath = join40(planDir, PLAN_V2_MATERIALIZATION_MARKER);
   if (!existsSync25(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
   if (!isRecord3(marker) || !isRecord3(marker.manifest) || !isRecord3(marker.target)) {
@@ -18843,7 +18975,7 @@ function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   assertRemoteSources(remoteSources, required);
   for (const artifact of required) {
     if (Object.hasOwn(remoteSources, artifact.path)) continue;
-    const path = join39(planDir, ...artifact.path.split("/"));
+    const path = join40(planDir, ...artifact.path.split("/"));
     if (!existsSync25(path) || statSync10(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
         `materialized artifact missing or truncated: ${artifact.path}`
@@ -18890,10 +19022,10 @@ function resolveChunkFrameRange(slice, chunkIndex, frameRange) {
   return { startFrame, endFrame };
 }
 var distributedCaptureSessionDependencies = {
-  createCaptureSession: createCaptureSession10,
+  createCaptureSession: createCaptureSession11,
   assertSwiftShader,
   initializeSession: initializeSession10,
-  closeCaptureSession: closeCaptureSession10,
+  closeCaptureSession: closeCaptureSession11,
   readWebGlVendorInfo: readWebGlVendorInfoFromCanvas
 };
 async function createVerifiedDistributedCaptureSession(serverUrl, framesDir, captureOptions, cfg, dependencies = distributedCaptureSessionDependencies) {
@@ -18964,7 +19096,7 @@ function hashChunkOutput(outputPath, kind) {
   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(readFileSync12(join40(outputPath, name)))}`
+    (name) => `${name}\0${sha256Hex(readFileSync12(join41(outputPath, name)))}`
   );
   return sha256Hex(lines.join("\0"));
 }
@@ -18981,9 +19113,9 @@ function resolveLockedVp9CpuUsed(lockedEncoder) {
 async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const start = Date.now();
   const log = defaultLogger;
-  const planJsonPath = join40(planDir, "plan.json");
-  const encoderJsonPath = join40(planDir, "meta", "encoder.json");
-  const chunksJsonPath = join40(planDir, "meta", "chunks.json");
+  const planJsonPath = join41(planDir, "plan.json");
+  const encoderJsonPath = join41(planDir, "meta", "encoder.json");
+  const chunksJsonPath = join41(planDir, "meta", "chunks.json");
   if (!existsSync26(planJsonPath)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
@@ -19009,7 +19141,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   }
   const encoder = JSON.parse(readFileSync12(encoderJsonPath, "utf-8"));
   const chunks = JSON.parse(readFileSync12(chunksJsonPath, "utf-8"));
-  const videosJsonPath = join40(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
+  const videosJsonPath = join41(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   let planVideos = null;
   if (existsSync26(videosJsonPath)) {
     try {
@@ -19041,7 +19173,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   }
   const range = resolveChunkFrameRange(slice, chunkIndex, options?.frameRange);
   const framesInChunk = range.endFrame - range.startFrame;
-  const compiledDir = join40(planDir, "compiled");
+  const compiledDir = join41(planDir, "compiled");
   if (!existsSync26(compiledDir)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
@@ -19099,7 +19231,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     };
     const workDir = `${outputChunkPath}.work.${process.pid}.${randomBytes(4).toString("hex")}`;
     mkdirSync17(workDir, { recursive: true });
-    const framesDir = join40(workDir, "captured-frames");
+    const framesDir = join41(workDir, "captured-frames");
     mkdirSync17(framesDir, { recursive: true });
     const videoFramesDir = `${workDir}.video-frames`;
     const chunkFrameNumbers = Array.from({ length: framesInChunk }, (_, i) => range.startFrame + i);
@@ -19124,7 +19256,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       dimensions: plan2.dimensions,
       encoder,
       videoCount: planVideos?.videos.length ?? 0,
-      html: readFileSync12(join40(compiledDir, "index.html"), "utf-8"),
+      html: readFileSync12(join41(compiledDir, "index.html"), "utf-8"),
       // The plan ships a deferred source only to chunks that show it; don't wait on the rest.
       skipReadinessVideoIds: deferredVideos.filter(
         (video) => !shownFrames.get(video.videoId)?.size || remoteVideoIds.has(video.videoId)
@@ -19195,7 +19327,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
             "[renderChunk] BeginFrame liveness probe failed; using screenshot capture for the entire chunk",
             { chunkIndex }
           );
-          await closeCaptureSession10(session).catch(() => {
+          await closeCaptureSession11(session).catch(() => {
           });
           session = null;
           const screenshotBootStarted = Date.now();
@@ -19294,7 +19426,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       if (isPngSequence) {
         if (!existsSync26(outputChunkPath)) mkdirSync17(outputChunkPath, { recursive: true });
       } else {
-        const outDir = join40(outputChunkPath, "..");
+        const outDir = join41(outputChunkPath, "..");
         if (!existsSync26(outDir)) mkdirSync17(outDir, { recursive: true });
       }
       const encodeInput = {
@@ -19468,7 +19600,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       });
       if (session) {
         try {
-          await closeCaptureSession10(session);
+          await closeCaptureSession11(session);
         } catch (err) {
           log.warn("[renderChunk] error closing capture session in finally", {
             error: err instanceof Error ? err.message : String(err)
@@ -19568,10 +19700,10 @@ async function renderSpan(projectDir, config, span, outputPath) {
   if (config.cfr === true) {
     throw new RenderSpanUnsupportedError("--start/--end cannot be combined with a cfr re-encode.");
   }
-  const workDir = mkdtempSync7(join41(tmpdir4(), "hf-render-span-"));
+  const workDir = mkdtempSync7(join42(tmpdir4(), "hf-render-span-"));
   try {
-    const planDir = join41(workDir, "plan");
-    const partsDir = join41(workDir, "parts");
+    const planDir = join42(workDir, "plan");
+    const partsDir = join42(workDir, "parts");
     mkdirSync18(partsDir, { recursive: true });
     const planned = await plan(
       projectDir,
@@ -19586,7 +19718,7 @@ async function renderSpan(projectDir, config, span, outputPath) {
       planned.totalFrames
     );
     const slices = JSON.parse(
-      readFileSync13(join41(planDir, "meta", "chunks.json"), "utf-8")
+      readFileSync13(join42(planDir, "meta", "chunks.json"), "utf-8")
     );
     const parts = [];
     for (const slice of slices) {
@@ -19596,13 +19728,18 @@ async function renderSpan(projectDir, config, span, outputPath) {
       };
       if (range.endFrame <= range.startFrame) continue;
       throwIfAborted(config.abortSignal);
-      const part = join41(partsDir, `part-${String(parts.length).padStart(4, "0")}.mp4`);
+      const part = join42(partsDir, `part-${String(parts.length).padStart(4, "0")}.mp4`);
       await renderChunk(planDir, slice.index, part, { frameRange: range });
       parts.push(part);
     }
     throwIfAborted(config.abortSignal);
     await writeStitchedMp4(parts, outputPath);
-    return { startFrame, endFrame, framesEncoded: endFrame - startFrame };
+    return {
+      ...referenceBackgroundResult6(planned[REFERENCE_BACKGROUND_FIELD4]),
+      startFrame,
+      endFrame,
+      framesEncoded: endFrame - startFrame
+    };
   } finally {
     rmSync16(workDir, { recursive: true, force: true });
   }
@@ -20167,9 +20304,9 @@ function renderRequestFromDistributedConfig(input) {
 
 // src/services/frameCapture.ts
 import {
-  createCaptureSession as createCaptureSession11,
+  createCaptureSession as createCaptureSession12,
   initializeSession as initializeSession11,
-  closeCaptureSession as closeCaptureSession11,
+  closeCaptureSession as closeCaptureSession12,
   captureFrame as captureFrame2,
   captureFrameToBuffer as captureFrameToBuffer4,
   getCompositionDuration as getCompositionDuration2,
@@ -20197,14 +20334,18 @@ import {
   rmSync as rmSync17,
   createReadStream as createReadStream5
 } from "node:fs";
-import { resolve as resolve12, dirname as dirname18, join as join44 } from "node:path";
+import { resolve as resolve12, dirname as dirname18, join as join45 } from "node:path";
 import { tmpdir as tmpdir5 } from "node:os";
 import { parseArgs } from "node:util";
 import crypto from "node:crypto";
 import { Hono as Hono2 } from "hono";
 import { streamSSE } from "hono/streaming";
 import { serve as serve2 } from "@hono/node-server";
-import { fetchPublicHttpsText as fetchPublicHttpsText2 } from "@hyperframes/engine";
+import {
+  fetchPublicHttpsText as fetchPublicHttpsText2,
+  REFERENCE_BACKGROUND_FIELD as REFERENCE_BACKGROUND_FIELD5,
+  referenceBackgroundResult as referenceBackgroundResult7
+} from "@hyperframes/engine";
 
 // src/services/hyperframeLint.ts
 import {
@@ -20216,7 +20357,7 @@ import {
   closeSync as closeSync7,
   constants as constants3
 } from "node:fs";
-import { resolve as resolve11, join as join42, relative as relative7, isAbsolute as isAbsolute5, sep as sep4 } from "node:path";
+import { resolve as resolve11, join as join43, relative as relative7, isAbsolute as isAbsolute5, sep as sep4 } from "node:path";
 import { lintHyperframeHtml } from "@hyperframes/lint";
 function isStringRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -20284,7 +20425,7 @@ function readProjectEntryFile(projectDir, preferredEntryFile) {
     }
   }
   return {
-    error: `No HTML entry file found in project directory: ${join42(absProjectDir, preferredEntryFile || "index.html")}`
+    error: `No HTML entry file found in project directory: ${join43(absProjectDir, preferredEntryFile || "index.html")}`
   };
 }
 function prepareHyperframeLintBody(body) {
@@ -20330,7 +20471,7 @@ async function runHyperframeLint(prepared) {
 // src/services/healthWorker.ts
 import { Worker as Worker2 } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
-import { dirname as dirname17, join as join43 } from "node:path";
+import { dirname as dirname17, join as join44 } from "node:path";
 import { existsSync as existsSync28 } from "node:fs";
 var DEFAULT_HEALTH_PORT = 9848;
 async function startHealthWorker(options = {}) {
@@ -20406,7 +20547,7 @@ function defaultLogger2() {
 }
 function resolveWorkerEntry2() {
   const here = dirname17(fileURLToPath6(import.meta.url));
-  const candidates = [join43(here, "healthWorkerThread.js"), join43(here, "healthWorkerThread.ts")];
+  const candidates = [join44(here, "healthWorkerThread.js"), join44(here, "healthWorkerThread.ts")];
   for (const candidate of candidates) {
     if (existsSync28(candidate)) return candidate;
   }
@@ -20617,8 +20758,8 @@ async function resolveInlineRenderHtml(body) {
 }
 function materializeInlineProject(html, options) {
   const tempRoot = process.env.PRODUCER_TMP_PROJECT_DIR || tmpdir5();
-  const tempProjectDir = mkdtempSync8(join44(tempRoot, "producer-project-"));
-  writeFileSync13(join44(tempProjectDir, "index.html"), html, "utf-8");
+  const tempProjectDir = mkdtempSync8(join45(tempRoot, "producer-project-"));
+  writeFileSync13(join45(tempProjectDir, "index.html"), html, "utf-8");
   return {
     prepared: {
       input: { projectDir: tempProjectDir, ...options },
@@ -20875,6 +21016,7 @@ function createRenderHandlers(options = {}) {
         outputUrl,
         fileSize,
         durationMs,
+        ...referenceBackgroundResult7(job[REFERENCE_BACKGROUND_FIELD5]),
         videoDurationSeconds: job.duration ?? null,
         outcome: job.outcome ?? "completed",
         warnings: job.warnings,
@@ -20962,6 +21104,7 @@ function createRenderHandlers(options = {}) {
             outputToken,
             outputUrl,
             fileSize,
+            ...referenceBackgroundResult7(job[REFERENCE_BACKGROUND_FIELD5]),
             videoDurationSeconds: job.duration ?? null,
             outcome: job.outcome ?? "completed",
             warnings: job.warnings,
@@ -21087,9 +21230,13 @@ import { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes
 // src/services/distributed/planV2Execution.ts
 import { mkdtempSync as mkdtempSync10, rmSync as rmSync19 } from "node:fs";
 import { tmpdir as tmpdir6 } from "node:os";
-import { join as join46 } from "node:path";
+import { join as join47 } from "node:path";
 
 // src/services/distributed/assemble.ts
+import {
+  REFERENCE_BACKGROUND_FIELD as REFERENCE_BACKGROUND_FIELD6,
+  referenceBackgroundResult as referenceBackgroundResult8
+} from "@hyperframes/engine";
 import {
   cpSync as cpSync3,
   existsSync as existsSync30,
@@ -21101,7 +21248,7 @@ import {
   statSync as statSync13,
   writeFileSync as writeFileSync14
 } from "node:fs";
-import { dirname as dirname19, join as join45 } from "node:path";
+import { dirname as dirname19, join as join46 } from "node:path";
 import {
   appendRateCapArgs as appendRateCapArgs2,
   appendRenderProvenanceArgs as appendRenderProvenanceArgs2,
@@ -21129,12 +21276,16 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   const plan2 = readAssemblePlan(planDir, chunkOutputs);
   const chunkPaths = chunkOutputs.flat();
   if (plan2.dimensions.format === "png-sequence") {
-    return mergePngFrameDirs(chunkPaths, outputPath, plan2.totalFrames, audioPath, start);
+    return {
+      ...mergePngFrameDirs(chunkPaths, outputPath, plan2.totalFrames, audioPath, start),
+      ...referenceBackgroundResult8(plan2[REFERENCE_BACKGROUND_FIELD6])
+    };
   }
   if (chunksAreStitchedMp4(planDir, cfr)) {
     const separateAudio = stitchesSeparateAudio(planDir) && audioPath !== null;
     await writeStitchedMp4(chunkPaths, outputPath, separateAudio ? audioPath : void 0);
     return {
+      ...referenceBackgroundResult8(plan2[REFERENCE_BACKGROUND_FIELD6]),
       outputPath,
       durationMs: Date.now() - start,
       framesEncoded: plan2.totalFrames,
@@ -21166,7 +21317,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   };
   try {
     const videoSources = cfrEncoder ? [await reencodeCfr(ctx, chunkPaths, cfrEncoder)] : chunkPaths;
-    const finalPath = join45(workDir, `output.${format}`);
+    const finalPath = join46(workDir, `output.${format}`);
     const audio = audioPath !== null && existsSync30(audioPath) ? audioPath : null;
     await writeJoined(ctx, videoSources, audio, finalPath);
     renameWithRetry11(finalPath, outputPath);
@@ -21187,6 +21338,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   }
   const fileSize = existsSync30(outputPath) ? statSync13(outputPath).size : 0;
   return {
+    ...referenceBackgroundResult8(plan2[REFERENCE_BACKGROUND_FIELD6]),
     outputPath,
     durationMs: Date.now() - start,
     framesEncoded: plan2.totalFrames,
@@ -21194,8 +21346,8 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   };
 }
 function readAssemblePlan(planDir, chunkPaths) {
-  const planJsonPath = join45(planDir, "plan.json");
-  const chunksJsonPath = join45(planDir, "meta", "chunks.json");
+  const planJsonPath = join46(planDir, "plan.json");
+  const chunksJsonPath = join46(planDir, "meta", "chunks.json");
   if (!existsSync30(planJsonPath)) {
     throw new Error(`[assemble] planDir missing plan.json: ${planJsonPath}`);
   }
@@ -21246,7 +21398,7 @@ function cfrEncodeArgs(inputArgs, encoder, fpsArg) {
   return args;
 }
 async function reencodeCfr(ctx, chunkPaths, encoder) {
-  const cfrOutputPath = join45(ctx.workDir, `cfr.${ctx.format}`);
+  const cfrOutputPath = join46(ctx.workDir, `cfr.${ctx.format}`);
   const cfrArgs = cfrEncodeArgs(videoInputArgs(ctx, chunkPaths), encoder, ctx.fpsArg);
   appendRenderProvenanceArgs2(cfrArgs, cfrOutputPath);
   cfrArgs.push("-y", cfrOutputPath);
@@ -21273,7 +21425,7 @@ async function writeJoined(ctx, videoSources, audioPath, finalPath) {
     );
     return;
   }
-  const paddedAudioPath = join45(ctx.workDir, "audio-padded.m4a");
+  const paddedAudioPath = join46(ctx.workDir, "audio-padded.m4a");
   const padTrimResult = await ctx.timed(
     "audioMs",
     () => padOrTrimAudioToVideoFrameCount({
@@ -21313,7 +21465,7 @@ async function writeJoined(ctx, videoSources, audioPath, finalPath) {
   }
 }
 function concatDemuxerInput(chunkPaths, workDir, fpsArg) {
-  const listPath = join45(workDir, "concat-list.txt");
+  const listPath = join46(workDir, "concat-list.txt");
   const body = chunkPaths.map((path) => `file '${path.replace(/'/g, "'\\''")}'`).join("\n");
   writeFileSync14(listPath, `${body}
 `, "utf-8");
@@ -21351,11 +21503,11 @@ function stitchesSeparateAudio(planDir) {
   return lockedAudio(planDir).separateAudio === true;
 }
 function planFormat(planDir) {
-  const plan2 = JSON.parse(readFileSync15(join45(planDir, "plan.json"), "utf-8"));
+  const plan2 = JSON.parse(readFileSync15(join46(planDir, "plan.json"), "utf-8"));
   return plan2.dimensions.format;
 }
 function lockedAudio(planDir) {
-  const encoderJsonPath = join45(planDir, "meta", "encoder.json");
+  const encoderJsonPath = join46(planDir, "meta", "encoder.json");
   if (!existsSync30(encoderJsonPath)) return {};
   return JSON.parse(readFileSync15(encoderJsonPath, "utf-8"));
 }
@@ -21365,7 +21517,7 @@ function readCfrEncoder(planDir, format) {
       `[assemble] cfr=true is only supported for format="mp4" (got "${format}"). Stream-copy paths for webm and mov already produce exact avg_frame_rate; cfr re-encode is not needed.`
     );
   }
-  const encoderJsonPath = join45(planDir, "meta", "encoder.json");
+  const encoderJsonPath = join46(planDir, "meta", "encoder.json");
   if (!existsSync30(encoderJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
   }
@@ -21392,8 +21544,8 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
       throw new Error(`[assemble] png-sequence chunk has no frames: ${chunkDir}`);
     }
     for (const frame of frames) {
-      const dst = join45(outputPath, formatExportFrameName(globalIdx, "png"));
-      cpSync3(join45(chunkDir, frame), dst);
+      const dst = join46(outputPath, formatExportFrameName(globalIdx, "png"));
+      cpSync3(join46(chunkDir, frame), dst);
       globalIdx += 1;
     }
   }
@@ -21403,13 +21555,13 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
     );
   }
   if (audioPath !== null && existsSync30(audioPath)) {
-    const sidecar = join45(outputPath, MIXED_AUDIO_FILENAME4);
+    const sidecar = join46(outputPath, MIXED_AUDIO_FILENAME4);
     cpSync3(audioPath, sidecar);
   }
   let fileSize = 0;
   for (const name of readdirSync11(outputPath)) {
     try {
-      fileSize += statSync13(join45(outputPath, name)).size;
+      fileSize += statSync13(join46(outputPath, name)).size;
     } catch {
     }
   }
@@ -21423,8 +21575,8 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
 
 // src/services/distributed/planV2Execution.ts
 async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath, options) {
-  const workRoot = mkdtempSync10(join46(tmpdir6(), "hf-plan-v2-chunk-"));
-  const materializedPlanDir = join46(workRoot, "plan");
+  const workRoot = mkdtempSync10(join47(tmpdir6(), "hf-plan-v2-chunk-"));
+  const materializedPlanDir = join47(workRoot, "plan");
   try {
     materializePlanV2Target(planV2Dir, { role: "chunk", chunkIndex }, materializedPlanDir);
     return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath, options);
@@ -21433,8 +21585,8 @@ async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath, options) {
   }
 }
 async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
-  const workRoot = mkdtempSync10(join46(tmpdir6(), "hf-plan-v2-assembler-"));
-  const materializedPlanDir = join46(workRoot, "plan");
+  const workRoot = mkdtempSync10(join47(tmpdir6(), "hf-plan-v2-assembler-"));
+  const materializedPlanDir = join47(workRoot, "plan");
   try {
     const materialized = materializePlanV2Target(
       planV2Dir,
@@ -21477,6 +21629,7 @@ export {
   PLAN_V2_SCHEMA_VERSION,
   PlanProtocolUnsupportedError,
   PlanV2IntegrityError,
+  REFERENCE_BACKGROUND_FIELD7 as REFERENCE_BACKGROUND_FIELD,
   RENDER_JOB_DIR,
   RENDER_REQUEST_VERSION,
   RenderCancelledError,
@@ -21487,14 +21640,15 @@ export {
   assembleV2,
   captureFrame2 as captureFrame,
   captureFrameToBuffer4 as captureFrameToBuffer,
-  closeCaptureSession11 as closeCaptureSession,
+  closeCaptureSession12 as closeCaptureSession,
   collectRenderMedia,
-  createCaptureSession11 as createCaptureSession,
+  createCaptureSession12 as createCaptureSession,
   createConsoleLogger,
   createFileServer,
   createOwnedRenderDir,
   createPlanV2FromExecutionPlan,
   createProducerApp,
+  createReferenceBackgroundRecorder3 as createReferenceBackgroundRecorder,
   createRenderHandlers,
   createRenderJob,
   createRenderRequest,
@@ -21527,6 +21681,8 @@ export {
   publishPlanV2FromExecutionPlan,
   quantizeTimeToFrame,
   readPlanV2Manifest,
+  readReferenceBackground2 as readReferenceBackground,
+  referenceBackgroundResult9 as referenceBackgroundResult,
   renderChunk,
   renderChunkV2,
   renderConfigFromRequest,