@hyperframes/producer 0.8.221 → 0.8.223

package/dist/public-server.js

@@ -1103,6 +1103,21 @@ function reportFrameProgress(job, stage, progress, onProgress, done, total) {
     total
   });
 }
+var lastExtractReportAt = /* @__PURE__ */ new WeakMap();
+function reportExtractProgress(job, done, total, onProgress) {
+  if (total <= 0) return;
+  const frames = Math.min(done, total);
+  reportThrottled(
+    lastExtractReportAt,
+    job,
+    "Extracting video frames",
+    10 + 10 * frames / total,
+    onProgress,
+    frames === total,
+    { code: "extract_video", done: frames, total },
+    "preprocessing"
+  );
+}
 var lastEncodeReportAt = /* @__PURE__ */ new WeakMap();
 function reportEncodeProgress(job, done, total, onProgress, from) {
   if (total <= 0) return;
@@ -1134,6 +1149,14 @@ function reportAssembleProgress(job, done, total, onProgress) {
   );
 }
 var workerPhasesByJob = /* @__PURE__ */ new WeakMap();
+function forgetWorkerPhases(job) {
+  workerPhasesByJob.delete(job);
+}
+function describeWorkerPhases(job) {
+  const phases = workerPhasesByJob.get(job);
+  if (!phases?.size) return void 0;
+  return `Last phase per worker: ${[...phases].map(([id, phase]) => `worker ${id} ${phase}`).join(", ")}.`;
+}
 function reportWorkerStartup(job, progress, onProgress) {
   const phase = progress.latestWorkerPhase;
   if (!phase) return;
@@ -2215,6 +2238,11 @@ function aggregateChromeMemory(perfs) {
     samples: sampled.reduce((sum, p) => sum + (p.chromeMemorySamples ?? 0), 0)
   };
 }
+function frameWeightedAvgMs(perfs, avgOf) {
+  const frames = perfs.reduce((sum, p) => sum + p.frames, 0);
+  if (frames === 0) return void 0;
+  return Math.round(perfs.reduce((sum, p) => sum + avgOf(p) * p.frames, 0) / frames);
+}
 function aggregateDedup(perfs) {
   if (perfs.length === 0) return void 0;
   const armed = perfs.some((p) => p.staticDedupArmed);
@@ -2313,6 +2341,10 @@ function buildRenderPerfSummary(input) {
       if (withSamples.length === 0) return void 0;
       return withSamples.reduce((a, b) => b.frames > a.frames ? b : a).p50TotalMs;
     })(),
+    captureSeekAvgMs: frameWeightedAvgMs(input.dedupPerfs, (p) => p.avgSeekMs),
+    captureBeforeCaptureAvgMs: frameWeightedAvgMs(input.dedupPerfs, (p) => p.avgBeforeCaptureMs),
+    captureScreenshotAvgMs: frameWeightedAvgMs(input.dedupPerfs, (p) => p.avgScreenshotMs),
+    encoderWaitAvgMs: input.perfStages.encoderDrainWaitMs !== void 0 && input.totalFrames > 0 ? Math.round(input.perfStages.encoderDrainWaitMs / input.totalFrames) : void 0,
     peakRssMb: Math.round(input.peakRssBytes / (1024 * 1024)),
     peakHeapUsedMb: Math.round(input.peakHeapUsedBytes / (1024 * 1024)),
     staticDedup: aggregateDedup(input.dedupPerfs),
@@ -4338,6 +4370,7 @@ async function runCaptureStreamingStage(input) {
     return {
       success: true,
       encodeMs: encodeResult.durationMs,
+      encoderDrainWaitMs: encodeResult.drainWaitMs,
       probeSession,
       lastBrowserConsole,
       workerCount,
@@ -4437,7 +4470,7 @@ async function captureSegment(ctx, segment) {
       // finished; absent only in unit tests, whose fake encoder writes none.
       bytes: existsSync6(segmentPath) ? statSync3(segmentPath).size : 0
     });
-    return encodeResult.durationMs;
+    return encodeResult;
   } finally {
     if (!encoderClosed) {
       await encoder.close().catch(() => {
@@ -4579,7 +4612,11 @@ async function retryAfterTargetLoss(run, worker, err, segment, segmentPath) {
   );
   run.deps.removeFile(segmentPath);
   await recycleWorkerSession(run, worker, "retry");
-  run.totals.encodeMs += await captureSegment(worker.ctx, segment);
+  addSegmentEncode(run.totals, await captureSegment(worker.ctx, segment));
+}
+function addSegmentEncode(totals, result) {
+  totals.encodeMs += result.durationMs;
+  totals.encoderDrainWaitMs += result.drainWaitMs ?? 0;
 }
 async function runOneSegment(run, worker, segment) {
   const segmentPath = segmentOutputPath(run.segmentDir, segment.index);
@@ -4591,7 +4628,7 @@ async function runOneSegment(run, worker, segment) {
     segmentIndex: segment.index
   });
   try {
-    run.totals.encodeMs += await captureSegment(worker.ctx, segment);
+    addSegmentEncode(run.totals, await captureSegment(worker.ctx, segment));
   } catch (err) {
     if (err instanceof SegmentEncoderSpawnError) return onSegmentSpawnFailure(run, err, segment);
     await retryAfterTargetLoss(run, worker, err, segment, segmentPath);
@@ -4634,7 +4671,7 @@ async function runCaptureSegmentedStage(input) {
   const run = {
     input,
     deps,
-    totals: { encodeMs: 0, segmentRetries: 0, browserRecycles: 0 },
+    totals: { encodeMs: 0, encoderDrainWaitMs: 0, segmentRetries: 0, browserRecycles: 0 },
     segments,
     pending,
     segmentDir,
@@ -4687,6 +4724,7 @@ async function runCaptureSegmentedStage(input) {
   return {
     success: true,
     encodeMs: run.totals.encodeMs,
+    encoderDrainWaitMs: run.totals.encoderDrainWaitMs,
     probeSession: null,
     lastBrowserConsole,
     workerCount: run.workerCount,
@@ -5498,16 +5536,17 @@ var RenderStageStalledError = class extends CaptureFailure2 {
   code = "RENDER_STAGE_STALLED";
   owner = "system";
   retryable = false;
-  constructor(phase, silentMs, progress) {
+  constructor(phase, silentMs, progress, detail) {
     super({
       kind: "protocol_timeout",
-      message: `[Render] ${phase} stalled: no progress for ${silentMs}ms (stuck at ${progress}).`
+      message: `[Render] ${phase} stalled: no progress for ${silentMs}ms (stuck at ${progress}).${detail ? ` ${detail}` : ""}`
     });
     this.name = "RenderStageStalledError";
   }
 };
 var STALL_POLL_MS = 5e3;
 function watchStall(phase, rule) {
+  const detail = rule.detail ?? (() => void 0);
   let last = rule.progress();
   let budgetMs = rule.firstProgressMs;
   let lastChangeAt = Date.now();
@@ -5529,7 +5568,7 @@ function watchStall(phase, rule) {
         }
         if (current !== last) return restartWindow(rule.noProgressMs);
         if (Date.now() - lastChangeAt < budgetMs) return;
-        const error = new RenderStageStalledError(phase, budgetMs, current);
+        const error = new RenderStageStalledError(phase, budgetMs, current, detail());
         if (attempt && !attempt.signal.aborted) {
           attempt.abort(error);
           return restartWindow(rule.noProgressMs);
@@ -5543,6 +5582,7 @@ function watchStall(phase, rule) {
   const openAttempt = (parent) => {
     attempt = new AbortController();
     inTail = false;
+    rule.attemptOpened?.();
     restartWindow(rule.firstProgressMs);
     return parent ? AbortSignal.any([parent, attempt.signal]) : attempt.signal;
   };
@@ -7849,7 +7889,7 @@ function rebaseDirectEntryAssetPaths(html, projectDir, htmlPath) {
   const { document: document2 } = parseHTML5(html);
   const assetExists = (path) => existsSync10(resolve7(projectDir, path));
   rewriteAssetPaths(
-    document2.querySelectorAll("[src], [href]"),
+    document2.querySelectorAll("[src], [href], [srcset]"),
     entryPath,
     (el, attr) => el.getAttribute(attr),
     (el, attr, value) => el.setAttribute(attr, value),
@@ -9531,6 +9571,8 @@ async function runExtractVideosStage(input) {
         safeVideoExtractionSourceLogMetadata(v.src)
       );
     }
+    let framesPlanned = 0;
+    let framesDone = 0;
     extractionResult = await extractAllVideoFrames(
       composition.videos,
       projectDir,
@@ -9547,7 +9589,12 @@ async function runExtractVideosStage(input) {
         collectProbeFailures: extractionPolicy.failureMode === "enforce",
         deferRangeExtraction,
         contentKeyedDirs: [join18(compiledDir, REMOTE_MEDIA_SUBDIR)],
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        onProgress: ({ planned = 0, done = 0 }) => {
+          framesPlanned += planned;
+          framesDone += done;
+          reportExtractProgress(job, framesDone, framesPlanned, input.onProgress);
+        }
       },
       abortSignal,
       cfg,
@@ -11294,6 +11341,7 @@ async function runCaptureHdrStage(input) {
   let lastBrowserConsole = [];
   let captureDurationMs = 0;
   let encodeMs = 0;
+  let encoderDrainWaitMs;
   const nativeHdrIds = /* @__PURE__ */ new Set([...nativeHdrVideoIds, ...nativeHdrImageIds]);
   log.info(
     hasHdrContent ? "[Render] HDR layered composite: z-ordered DOM + native HDR video/image layers" : "[Render] Shader transition composite: z-ordered SDR DOM layers"
@@ -11531,6 +11579,7 @@ async function runCaptureHdrStage(input) {
     reportEncodeProgress(job, totalFrames, totalFrames, onProgress, encodeFrom);
     captureDurationMs = Date.now() - stageStart;
     encodeMs = hdrEncodeResult.durationMs;
+    encoderDrainWaitMs = hdrEncodeResult.drainWaitMs;
   } catch (error) {
     lastBrowserConsole = domSession.browserConsoleBuffer;
     throw wrapCaptureStageError(error, lastBrowserConsole);
@@ -11563,6 +11612,7 @@ async function runCaptureHdrStage(input) {
     hdrPerf,
     captureDurationMs,
     encodeMs,
+    encoderDrainWaitMs,
     warnings: cloneCaptureWarnings2(domSession.warnings)
   };
 }
@@ -12355,7 +12405,9 @@ function frameStallRule(job, totalFrames) {
     noProgressMs,
     firstProgressMs: Math.max(FIRST_FRAME_STALL_MS, noProgressMs),
     complete: () => (job.framesRendered ?? 0) >= totalFrames,
-    tailMs: Math.max(TAIL_STALL_MS, noProgressMs)
+    tailMs: Math.max(TAIL_STALL_MS, noProgressMs),
+    detail: () => describeWorkerPhases(job),
+    attemptOpened: () => forgetWorkerPhases(job)
   };
 }
 function isRecoverableParallelCaptureError(error) {
@@ -12881,6 +12933,11 @@ function resolveDeSingleMinFrames(env) {
 function shouldPreferSingleWorkerDrawElement(args) {
   return args.workerCount > 1 && args.useDrawElement && !args.deCompileGate && !args.forceScreenshot && outputUsesH264Pipeline(args.outputFormat) && args.minFrames > 0 && args.totalFrames >= args.minFrames && args.singleWorkerStreamingOk && !args.layeredOrEffectRoute && !args.supersampling && !args.probeDeGated && !args.experimentalParallelDeOptIn;
 }
+function initialDeClampReason(args) {
+  if (args.useDrawElement) return void 0;
+  if (args.deCompileGate) return "compile_gate";
+  return explainDrawElementDisabled(args.config);
+}
 function probeNeedsScreenshotFrames(session) {
   return (session?.deRiskFrames?.size ?? 0) > 0;
 }
@@ -13270,11 +13327,15 @@ async function executeRenderPipeline(input) {
     perfStages.compileOnlyMs = compileResult.compileOnlyMs;
     let captureForceScreenshot = compileResult.forceScreenshot;
     const deCompileGate = compileResult.deCompileGate;
-    let deClampReason = cfg.useDrawElement ? void 0 : explainDrawElementDisabled({
-      platform: process.platform,
-      browserGpuMode: cfg.browserGpuMode,
-      workerEncode: cfg.enableDrawElementWorkerEncode,
-      chromeCeiling: chromeMajorCeiling()
+    let deClampReason = initialDeClampReason({
+      useDrawElement: cfg.useDrawElement,
+      deCompileGate,
+      config: {
+        platform: process.platform,
+        browserGpuMode: cfg.browserGpuMode,
+        workerEncode: cfg.enableDrawElementWorkerEncode,
+        chromeCeiling: chromeMajorCeiling()
+      }
     });
     let deWorkerInversion;
     let deParallelStreamForced = false;
@@ -13400,7 +13461,8 @@ async function executeRenderPipeline(input) {
         abortSignal: executionSignal,
         assertNotAborted,
         // Local staging can use links; distributed plan() alone requires real copies.
-        materializeSymlinks: false
+        materializeSymlinks: false,
+        onProgress
       })
     );
     const {
@@ -14264,6 +14326,7 @@ async function executeRenderPipeline(input) {
       perfStages.captureFrameMs = hdrRes.captureDurationMs;
       perfStages.captureSetupMs = Math.max(0, Date.now() - stage4Start - hdrRes.captureDurationMs);
       perfStages.encodeMs = hdrRes.encodeMs;
+      perfStages.encoderDrainWaitMs = hdrRes.encoderDrainWaitMs ?? 0;
     } else {
       let streamingHandled = false;
       if (capturePlan.kind === "sdr_segmented") {
@@ -14443,6 +14506,7 @@ async function executeRenderPipeline(input) {
           perfStages.captureFrameMs = Date.now() - captureFrameStart;
           perfStages.captureSetupMs = Math.max(0, perfStages.captureMs - perfStages.captureFrameMs);
           perfStages.encodeMs = segmentedRes.encodeMs;
+          perfStages.encoderDrainWaitMs = segmentedRes.encoderDrainWaitMs ?? 0;
           log.info(
             `[Render] Segmented capture complete: ${segmentedRes.segments} segment(s) concatenated.`,
             {
@@ -14620,6 +14684,7 @@ async function executeRenderPipeline(input) {
           perfStages.captureFrameMs = captureFrameMs;
           perfStages.captureSetupMs = Math.max(0, perfStages.captureMs - captureFrameMs);
           perfStages.encodeMs = streamingRes.encodeMs;
+          perfStages.encoderDrainWaitMs = streamingRes.encoderDrainWaitMs ?? 0;
         } else {
           if (capturePlan.kind === "sdr_streaming") {
             capturePlan = replanAfterFailure(capturePlan, { kind: "streaming_unavailable" });

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

@@ -0,0 +1,19 @@
+import { type DistributedRenderConfig } from "./plan.js";
+export interface RenderSpanResult {
+    startFrame: number;
+    endFrame: number;
+    framesEncoded: number;
+}
+export declare class RenderSpanUnsupportedError extends Error {
+    constructor(message: string);
+}
+/** The frames `[startFrame, endFrame)` of a `totalFrames` timeline that `[startSeconds, endSeconds)` covers. */
+export declare function spanFrameRange(startSeconds: number, endSeconds: number | undefined, fps: number, totalFrames: number): {
+    startFrame: number;
+    endFrame: number;
+};
+/** Renders `[startSeconds, endSeconds)` as a standalone mp4 from 0, with that span's audio, by chunk sub-ranges. */
+export declare function renderSpan(projectDir: string, config: DistributedRenderConfig, span: {
+    startSeconds: number;
+    endSeconds?: number;
+}, outputPath: string): Promise<RenderSpanResult>;

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

@@ -337,6 +337,8 @@ export interface StageStallRule {
     complete?: () => boolean;
     /** Allowed silence once `complete()` holds; defaults to `noProgressMs`. */
     tailMs?: number;
+    detail?: () => string | undefined;
+    attemptOpened?: () => void;
 }
 /**
  * Classified like the per-call protocol timeout it replaces, so the capture retry ladder retries it.
@@ -346,7 +348,7 @@ export declare class RenderStageStalledError extends CaptureFailure {
     readonly code = "RENDER_STAGE_STALLED";
     readonly owner: "system";
     readonly retryable: false;
-    constructor(phase: string, silentMs: number, progress: number);
+    constructor(phase: string, silentMs: number, progress: number, detail?: string);
 }
 /** Opens a capture attempt: a fresh no-progress window, and a signal the rule aborts when that window runs out. */
 export type OpenStallAttempt = (parent?: AbortSignal) => AbortSignal;

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

@@ -106,10 +106,14 @@ export declare function applyRenderModeHints(alreadyForced: boolean, compiled: C
 export declare function updateJobStatus(job: RenderJob, status: RenderStatus, stage: string, progress: number, onProgress?: ProgressCallback, stageProgress?: RenderStageProgress): void;
 /** Capture-loop progress: the first frame, the last frame, and at most four reports a second between. */
 export declare function reportFrameProgress(job: RenderJob, stage: string, progress: number, onProgress: ProgressCallback | undefined, done: number, total: number): void;
+/** Frames ffmpeg has written for the source videos, 10% to 20%. */
+export declare function reportExtractProgress(job: RenderJob, done: number, total: number, onProgress: ProgressCallback | undefined): void;
 /** Frames ffmpeg has encoded, from where capture left the bar up to 90%; same cadence as capture. */
 export declare function reportEncodeProgress(job: RenderJob, done: number, total: number, onProgress: ProgressCallback | undefined, from: number): void;
 /** Seconds of the final file written, 90% to 99%: only a complete file reaches 100. */
 export declare function reportAssembleProgress(job: RenderJob, done: number, total: number, onProgress: ProgressCallback | undefined): void;
+export declare function forgetWorkerPhases(job: object): void;
+export declare function describeWorkerPhases(job: object): string | undefined;
 /** Browser warm-up before the first frame, from the parallel workers' phase events. */
 export declare function reportWorkerStartup(job: RenderJob, progress: ParallelProgress, onProgress: ProgressCallback | undefined): void;
 /**

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

@@ -84,6 +84,7 @@ export interface CaptureHdrStageResult {
     captureDurationMs: number;
     /** ffmpeg-reported encode duration; overlapped with capture. */
     encodeMs: number;
+    encoderDrainWaitMs?: number;
     warnings: CaptureWarning[];
 }
 export declare function runCaptureHdrStage(input: CaptureHdrStageInput): Promise<CaptureHdrStageResult>;

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

@@ -75,6 +75,7 @@ export interface CaptureSegmentedStageInput {
 export type CaptureSegmentedStageResult = {
     success: true;
     encodeMs: number;
+    encoderDrainWaitMs?: number;
     probeSession: null;
     lastBrowserConsole: string[];
     workerCount: number;

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

@@ -112,6 +112,7 @@ export type CaptureStreamingStageResult = {
     success: true;
     /** Wall-clock ms for the encode phase (overlapped with capture; from the encoder's own report). */
     encodeMs: number;
+    encoderDrainWaitMs?: number;
     probeSession: CaptureSession | null;
     lastBrowserConsole: string[];
     workerCount: number;

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

@@ -30,6 +30,7 @@
 import { type CaptureVideoMetadataHint, type EngineConfig, type ExtractionResult, type FrameLookupTable, type HdrTransfer, type VideoExtractionFailureKind, type VideoColorSpace, classifyVideoExtractionError, extractAllVideoFrames } from "@hyperframes/engine";
 import { type RenderJob } from "../../renderOrchestrator.js";
 import { type CompositionMetadata } from "../shared.js";
+import type { ProgressCallback } from "../../renderOrchestrator.js";
 import type { ProducerLogger } from "../../../logger.js";
 import { type ExtractionFailureMetadataV1 } from "../extractionFailureMetadata.js";
 export interface ExtractVideosStageInput {
@@ -52,6 +53,7 @@ export interface ExtractVideosStageInput {
     materializeSymlinks?: boolean;
     deferRangeExtraction?: boolean;
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
+    onProgress?: ProgressCallback;
 }
 export interface ExtractVideosStageResult {
     /** Result of `extractAllVideoFrames`, or `null` if the composition has no videos. */

package/dist/services/renderOrchestrator.d.ts

@@ -1,5 +1,5 @@
 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, type CaptureFailureKind, type MotionBlurOptions } from "@hyperframes/engine";
+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 ProducerLogger } from "../logger.js";
 import { type RenderOutputFormat } from "./render/renderFormat.js";
 import { type RenderCaptureObservability, type RenderObservabilitySummary, type OpenStallAttempt, type StageStallRule } from "./render/observability.js";
@@ -200,6 +200,11 @@ export interface RenderPerfSummary {
      * captured the most frames when parallel workers report separately.
      */
     captureP50Ms?: number;
+    /** Per-frame capture phases, frame-weighted across sessions; encoder wait is FFmpeg back-pressure. */
+    captureSeekAvgMs?: number;
+    captureBeforeCaptureAvgMs?: number;
+    captureScreenshotAvgMs?: number;
+    encoderWaitAvgMs?: number;
     /** Worst sub-composition timeline wait outcome across sessions. */
     subTimelineWait?: SubTimelineWaitOutcome;
     capturePeakMs?: number;
@@ -875,6 +880,12 @@ export declare function shouldPreferSingleWorkerDrawElement(args: {
      */
     experimentalParallelDeOptIn: boolean;
 }): boolean;
+/** Why drawElement is off before capture; the compile stage's content gates are not config refusals. */
+export declare function initialDeClampReason(args: {
+    useDrawElement: boolean;
+    deCompileGate: string | undefined;
+    config: Parameters<typeof explainDrawElementDisabled>[0];
+}): string | undefined;
 /**
  * Plan the self-verify retry for an inverted render: the inversion bet on
  * drawElement and lost, so the re-render returns to the pre-inversion parallel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.221",
+  "version": "0.8.223",
   "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.8.221",
-    "@hyperframes/lint": "0.8.221",
-    "@hyperframes/parsers": "0.8.221",
-    "@hyperframes/studio-server": "0.8.221",
-    "@hyperframes/core": "0.8.221"
+    "@hyperframes/core": "0.8.223",
+    "@hyperframes/engine": "0.8.223",
+    "@hyperframes/lint": "0.8.223",
+    "@hyperframes/parsers": "0.8.223",
+    "@hyperframes/studio-server": "0.8.223"
   },
   "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.8.221"
+    "@hyperframes/aws-lambda": "0.8.223"
   },
   "engines": {
     "node": ">=22"