@hyperframes/producer 0.9.3 → 0.9.5

package/dist/public-server.js

@@ -17,7 +17,11 @@ 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_FIELD3,
+  referenceBackgroundResult as referenceBackgroundResult5
+} from "@hyperframes/engine";
 
 // src/services/renderOrchestrator.ts
 import { audioFailureDiagnostics as audioFailureDiagnostics2 } from "@hyperframes/engine";
@@ -77,6 +81,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";
@@ -8818,6 +8826,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,
@@ -12459,6 +12468,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") {
@@ -12826,6 +12846,7 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
 }
 function createRenderJob(config) {
   return {
+    ...referenceBackgroundResult(void 0),
     id: randomUUID(),
     config: {
       ...config,
@@ -13591,6 +13612,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,
@@ -13611,7 +13635,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
@@ -13867,6 +13892,7 @@ async function executeRenderPipeline(input) {
     let routePageMotionBlur;
     const buildCaptureOptions = () => ({
       ...captureOptions,
+      recordReferenceBackground,
       ...routePageMotionBlur ? { pageMotionBlur: routePageMotionBlur } : {},
       videoMetadataHints,
       skipReadinessVideoIds: videoReadinessSkipIds,
@@ -13899,6 +13925,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(
@@ -14002,7 +14030,7 @@ async function executeRenderPipeline(input) {
         probeSession = await createCaptureSession8(
           activeFileServer.url,
           framesDir,
-          buildCaptureOptions(),
+          buildPrepCaptureOptions(),
           null,
           { ...cfg, forceScreenshot: captureForceScreenshot }
         );
@@ -14085,7 +14113,7 @@ async function executeRenderPipeline(input) {
           totalFrames,
           forceScreenshot: captureForceScreenshot,
           probeSession,
-          buildCaptureOptions,
+          buildCaptureOptions: buildPrepCaptureOptions,
           createRenderVideoFrameInjector,
           assertNotAborted
         }),
@@ -14557,7 +14585,7 @@ async function executeRenderPipeline(input) {
             effectiveBitrate,
             deliveryEncoder,
             fileServer: activeFileServer,
-            buildCaptureOptions,
+            buildCaptureOptions: buildWorkerCaptureOptions,
             createRenderVideoFrameInjector,
             hdrDiagnostics,
             abortSignal: attempt,
@@ -14675,7 +14703,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,
@@ -14823,7 +14851,7 @@ async function executeRenderPipeline(input) {
                 // encoder's open-GOP output untouched.
                 ...deliveryEncoder
               },
-              buildCaptureOptions,
+              buildCaptureOptions: buildWorkerCaptureOptions,
               createRenderVideoFrameInjector,
               abortSignal: executionSignal,
               assertNotAborted,
@@ -15008,7 +15036,7 @@ async function executeRenderPipeline(input) {
             probeSession,
             captureAttempts,
             dedupPerfs,
-            buildCaptureOptions,
+            buildCaptureOptions: buildWorkerCaptureOptions,
             createRenderVideoFrameInjector,
             abortSignal: executionSignal,
             assertNotAborted,
@@ -15241,7 +15269,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);
@@ -15568,6 +15596,11 @@ import {
 import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
 
 // 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 { extname as extname4, isAbsolute as isAbsolute4, join as join31, relative as relative4, sep as sep3 } from "node:path";
 import {
@@ -15613,6 +15646,20 @@ var execFile = promisify2(execFileCallback);
 // src/services/distributed/chunkWeights.ts
 import { resolveFrameFormat } from "@hyperframes/engine";
 
+// src/services/render/planReferenceBackground.ts
+import {
+  closeCaptureSession as closeCaptureSession10,
+  createCaptureSession as createCaptureSession10,
+  readReferenceBackground,
+  referenceBackgroundResult as referenceBackgroundResult2
+} from "@hyperframes/engine";
+
+// src/services/render/stages/freezePlan.ts
+import {
+  REFERENCE_BACKGROUND_FIELD,
+  referenceBackgroundResult as referenceBackgroundResult3
+} from "@hyperframes/engine";
+
 // src/services/distributed/planProtocol.ts
 var PLAN_SCHEMA_VERSION = 1;
 var PLAN_ARTIFACT_LAYOUT = "plan-dir-v1";
@@ -16385,6 +16432,7 @@ function createRenderHandlers(options = {}) {
         outputUrl,
         fileSize,
         durationMs,
+        ...referenceBackgroundResult5(job[REFERENCE_BACKGROUND_FIELD3]),
         videoDurationSeconds: job.duration ?? null,
         outcome: job.outcome ?? "completed",
         warnings: job.warnings,
@@ -16472,6 +16520,7 @@ function createRenderHandlers(options = {}) {
             outputToken,
             outputUrl,
             fileSize,
+            ...referenceBackgroundResult5(job[REFERENCE_BACKGROUND_FIELD3]),
             videoDurationSeconds: job.duration ?? null,
             outcome: job.outcome ?? "completed",
             warnings: job.warnings,

package/dist/services/distributed/assemble.d.ts

@@ -1,23 +1,4 @@
-/**
- * Activity C of the distributed render pipeline.
- *
- * `assemble(planDir, chunkPaths, audioPath, outputPath)` stitches per-chunk
- * outputs into the final deliverable. For mp4 / mov / webm this is
- * `ffmpeg -f concat -c copy` (free of re-encode loss because every
- * chunk's first frame is an IDR keyframe — the chunk encoder sets
- * `lockGopForChunkConcat` to enforce this, which for libvpx-vp9 also
- * disables alt-ref frames so concat seams remain independently
- * decodable). For png-sequence chunks (each chunk is a directory of
- * frames) this is a straight directory merge with global re-numbering.
- *
- * Join, audio mux and mp4 faststart run as one ffmpeg pass over the concat
- * demuxer, so disk holds the chunks plus one output copy. Audio is first
- * pad-or-trimmed to `frameCount / fps` (frames summed over the chunks) so
- * the mux adds no drift at the end of long renders.
- *
- * Pure function over local paths. No networking. The caller is responsible
- * for moving `outputPath` to its orchestration-level storage.
- */
+import { type ReferenceBackgroundResult } from "@hyperframes/engine";
 import { type ProducerLogger } from "../../logger.js";
 import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
 /**
@@ -25,7 +6,7 @@ import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
  * (mp4/mov) or the cumulative byte total of the frame directory
  * (png-sequence).
  */
-export interface AssembleResult {
+export interface AssembleResult extends ReferenceBackgroundResult {
     outputPath: string;
     durationMs: number;
     framesEncoded: number;

package/dist/services/distributed/plan.d.ts

@@ -1,3 +1,4 @@
+import { type ReferenceBackgroundResult } from "@hyperframes/engine";
 import { type CanvasResolution, type DistributedFps } from "@hyperframes/core";
 import { type EngineConfig, type VideoFrameFormat, type ProresProfile, type AudioProcessingFailure } from "@hyperframes/engine";
 import { type ProducerLogger } from "../../logger.js";
@@ -185,7 +186,7 @@ export interface DistributedRenderConfig extends Pick<RenderRequestOptions, "pag
     variables?: Record<string, unknown>;
 }
 /** Shared local representation consumed by both distributed plan transports. */
-export interface LocalExecutionPlan {
+export interface LocalExecutionPlan extends Partial<ReferenceBackgroundResult> {
     executionPlanDir: string;
     executionPlanHash: string;
     chunkCount: number;
@@ -240,7 +241,7 @@ export declare function logPlanStage(log: ProducerLogger, stage: string, started
  * @deprecated Use `planV2()` or `planV2WithPublisher()` for new integrations.
  * The v1 result remains supported for existing transports.
  */
-export interface PlanResult {
+export interface PlanResult extends Partial<ReferenceBackgroundResult> {
     planDir: string;
     planProtocol: Readonly<PlanProtocolV1Descriptor>;
     planHash: string;

package/dist/services/distributed/planV2.d.ts

@@ -1,15 +1,4 @@
-/**
- * Content-addressed distributed plan transport.
- *
- * V2 deliberately separates transport from execution. The transport root is
- * a small immutable `plan.json` manifest plus sha256-addressed blobs. Workers
- * select and materialize only the dependencies for their role, then invoke
- * the shared execution functions on the verified local layout.
- *
- * Video-frame dependencies are derived by evaluating the engine's own
- * FrameLookupTable at every captured global frame. If legacy video metadata
- * is absent, v2 explicitly falls back to the full-source pack.
- */
+import { type ReferenceBackgroundResult } from "@hyperframes/engine";
 import { type DistributedFps } from "@hyperframes/core";
 import { type BuildLocalExecutionPlanOptions, type DistributedRenderConfig } from "./plan.js";
 import { type PlanProtocolV2Descriptor } from "./planProtocol.js";
@@ -58,7 +47,7 @@ export interface PlanV2Manifest {
 export interface PlanV2Limitations {
     readonly videoDependencyMode: "exact-rendered-frames" | "full-source-pack" | "source-extract";
 }
-export interface PlanV2Result {
+export interface PlanV2Result extends ReferenceBackgroundResult {
     readonly planDir: string;
     readonly manifestPath: string;
     readonly planProtocol: Readonly<PlanProtocolV2Descriptor>;

package/dist/services/distributed/renderSpan.d.ts

@@ -1,5 +1,6 @@
+import { type ReferenceBackgroundResult } from "@hyperframes/engine";
 import { type DistributedRenderConfig } from "./plan.js";
-export interface RenderSpanResult {
+export interface RenderSpanResult extends ReferenceBackgroundResult {
     startFrame: number;
     endFrame: number;
     framesEncoded: number;

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

@@ -0,0 +1,12 @@
+import { type CaptureOptions, type EngineConfig, type ReferenceBackgroundResult } from "@hyperframes/engine";
+import type { ProducerLogger } from "../../logger.js";
+interface PlanReferenceInput {
+    projectDir: string;
+    workDir: string;
+    cfg: EngineConfig;
+    options: CaptureOptions;
+    log: ProducerLogger;
+}
+/** Optional evidence must not add capture capabilities to a browser-free planner. */
+export declare function readPlanReferenceBackground(input: PlanReferenceInput): Promise<ReferenceBackgroundResult>;
+export {};

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

@@ -10,7 +10,7 @@
  * has in memory.
  */
 import type { Fps } from "@hyperframes/core";
-import type { ProresProfile } from "@hyperframes/engine";
+import { type ReferenceBackgroundResult, type ProresProfile } from "@hyperframes/engine";
 import type { RenderRequestOptions } from "../../../renderRequest.js";
 import { type PlanDimensions } from "./planHash.js";
 /**
@@ -78,7 +78,7 @@ export interface LockedRenderConfig extends Pick<RenderRequestOptions, "pageMoti
     chunksCarryAudio?: true;
     separateAudio?: true;
 }
-export interface CompositionMetadataJson {
+export interface CompositionMetadataJson extends Partial<ReferenceBackgroundResult> {
     durationSeconds: number;
     width: number;
     height: number;

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

@@ -1,8 +1,7 @@
 /**
  * probeStage — browser probe + recompile + media reconciliation.
  *
- * Runs only when `needsBrowser` is true (root duration unknown OR there are
- * unresolved nested compositions). Owns the `FileServerHandle` and the
+ * Runs when media discovery needs a browser. Owns the `FileServerHandle` and the
  * `CaptureSession` it creates and returns them so the sequencer can both
  * reuse them downstream (the capture stage reuses the probe session) and
  * clean them up in its `finally` block.
@@ -26,7 +25,7 @@
  *     regex, the same first-10/first-5 slicing, and the same `console.warn`
  *     prefix.
  */
-import { type CaptureSession, type CompositionLengthSource, type EngineConfig, type SubTimelineWaitMemo } from "@hyperframes/engine";
+import { type CaptureOptions, type CaptureSession, type CompositionLengthSource, type EngineConfig, type SubTimelineWaitMemo } from "@hyperframes/engine";
 import type { CompiledComposition } from "../../htmlCompiler.js";
 import { type FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
@@ -35,6 +34,7 @@ import type { RenderJob } from "../../renderOrchestrator.js";
 export interface ProbeStageInput {
     projectDir: string;
     workDir: string;
+    recordReferenceBackground?: CaptureOptions["recordReferenceBackground"];
     job: RenderJob;
     cfg: EngineConfig;
     /**

package/dist/services/renderOrchestrator.d.ts

@@ -1,5 +1,6 @@
 import { type CanvasResolution, type Fps, type FpsInput, type HfVfxCapture } from "@hyperframes/core";
 import { type EngineConfig, type ExtractionPhaseBreakdown, type VideoFrameFormat, type CaptureOptions, type CaptureVideoMetadataHint, type CaptureSession, type BeforeCaptureHook, type ProresProfile, type ParallelProgress, type WorkerTask, type CapturePerfSummary, type CaptureWarning, type SubTimelineWaitOutcome, type WorkerSizing, type StaticVerificationOutcome, explainDrawElementDisabled, type CaptureFailureKind, type MotionBlurOptions } from "@hyperframes/engine";
+import { type ReferenceBackgroundResult } from "@hyperframes/engine";
 import { type ProducerLogger } from "../logger.js";
 import { type RenderOutputFormat } from "./render/renderFormat.js";
 import { type RenderCaptureObservability, type RenderObservabilitySummary, type OpenStallAttempt, type StageStallRule } from "./render/observability.js";
@@ -429,7 +430,7 @@ export interface RenderStageProgress {
     done?: number;
     total?: number;
 }
-export interface RenderJob {
+export interface RenderJob extends Partial<ReferenceBackgroundResult> {
     id: string;
     config: RenderConfig;
     status: RenderStatus;
@@ -468,6 +469,9 @@ export declare class RenderQualityError extends Error {
     constructor(warnings: readonly RenderWarning[]);
 }
 export declare function applyRenderWarningPolicy(job: RenderJob, captureWarnings: readonly CaptureWarning[], log?: ProducerLogger): void;
+export declare const stopPrepSessionOnScriptFailure: (options: CaptureOptions) => CaptureOptions;
+export declare const surfaceScriptFailure: (error: unknown, job: RenderJob) => unknown;
+export declare const withScriptFailureStop: (options: CaptureOptions, job: RenderJob, log: ProducerLogger) => CaptureOptions;
 export declare class RenderCancelledError extends Error {
     reason: "user_cancelled" | "timeout" | "aborted";
     constructor(message?: string, reason?: "user_cancelled" | "timeout" | "aborted");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
-    "@hyperframes/engine": "0.9.3",
-    "@hyperframes/core": "0.9.3",
-    "@hyperframes/lint": "0.9.3",
-    "@hyperframes/parsers": "0.9.3",
-    "@hyperframes/studio-server": "0.9.3"
+    "@hyperframes/core": "0.9.5",
+    "@hyperframes/parsers": "0.9.5",
+    "@hyperframes/engine": "0.9.5",
+    "@hyperframes/lint": "0.9.5",
+    "@hyperframes/studio-server": "0.9.5"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
@@ -48,7 +48,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@hyperframes/aws-lambda": "0.9.3"
+    "@hyperframes/aws-lambda": "0.9.5"
   },
   "engines": {
     "node": ">=22"