@hyperframes/producer 0.8.214 → 0.8.217

package/dist/public-server.js

@@ -3707,6 +3707,10 @@ function resolveCaptureStallTimeoutMs() {
   const parsed = raw ? Number(raw) : Number.NaN;
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CAPTURE_STALL_MS;
 }
+function stallBudgetMs(stallTimeoutMs, framesDone, beginFrame, cfg) {
+  const deadline = cfg.beginFrameFirstFrameDeadlineMs;
+  return beginFrame && framesDone === 0 && deadline ? Math.min(stallTimeoutMs, deadline) : stallTimeoutMs;
+}
 function captureModeLabel(mode) {
   if (mode === "drawelement") return "drawElement";
   if (mode === "beginframe") return "BeginFrame";
@@ -4079,14 +4083,20 @@ async function runCaptureStreamingStage(input) {
         const phaseDetail = (phase) => `phase=${phase.phase} frame=${phase.frameIndex ?? "n/a"} step=${phase.readStep?.() ?? "n/a"} browser=${phase.browserExecutable} version=${phase.browserVersion} CanvasDrawElement=${phase.canvasDrawElement} gpu=${phase.gpuBackend}`;
         const phaseSummary = () => [...workerPhases.entries()].sort(([left], [right]) => left - right).map(([workerId, detail]) => `worker=${workerId} ${detail}`).join("; ");
         let stalled = false;
+        const budget = () => stallBudgetMs(
+          stallTimeoutMs,
+          resumeFrom + lastCapturedFrames,
+          captureLabel === "BeginFrame",
+          cfg
+        );
         const stallTimer = setInterval(
           () => {
-            if (!watchdogArmed || Date.now() - lastProgressAt <= stallTimeoutMs) return;
+            if (!watchdogArmed || Date.now() - lastProgressAt <= budget()) return;
             stalled = true;
             const stallErr = new ParallelCaptureStallError({
               variant: "drain",
               captureLabel,
-              stallTimeoutMs,
+              stallTimeoutMs: budget(),
               lastCapturedFrames: resumeFrom + lastCapturedFrames,
               totalFrames,
               phaseSummary: phaseSummary()
@@ -4094,7 +4104,7 @@ async function runCaptureStreamingStage(input) {
             parallelReorder.abort(stallErr);
             stallController.abort();
           },
-          Math.min(stallTimeoutMs, DE_STALL_POLL_MS)
+          Math.min(budget(), DE_STALL_POLL_MS)
         );
         try {
           workerResults = await executeParallelCapture(
@@ -4175,7 +4185,7 @@ async function runCaptureStreamingStage(input) {
             throw new ParallelCaptureStallError({
               variant: "pool",
               captureLabel,
-              stallTimeoutMs,
+              stallTimeoutMs: budget(),
               lastCapturedFrames: resumeFrom + lastCapturedFrames,
               totalFrames,
               phaseSummary: phaseSummary()
@@ -4276,10 +4286,16 @@ async function runCaptureStreamingStage(input) {
           for (let i = 0; i < totalFrames; i++) {
             assertNotAborted();
             const time = i * job.config.fps.den / job.config.fps.num;
+            const budget = stallBudgetMs(
+              stallTimeoutMs,
+              i,
+              session.captureMode === "beginframe",
+              cfg
+            );
             const { buffer } = await raceAgainstStall(
               captureFrameToBuffer(session, i, time),
-              stallTimeoutMs - (Date.now() - lastProgressAt),
-              { session, frameIndex: i, totalFrames, stallTimeoutMs },
+              budget - (Date.now() - lastProgressAt),
+              { session, frameIndex: i, totalFrames, stallTimeoutMs: budget },
               abortSignal
             );
             await reorderBuffer.waitForFrame(i);
@@ -5497,6 +5513,7 @@ function watchStall(phase, rule) {
   let lastChangeAt = Date.now();
   let attempt;
   let timer;
+  let inTail = false;
   const restartWindow = (ms) => {
     last = rule.progress();
     budgetMs = ms;
@@ -5506,6 +5523,10 @@ function watchStall(phase, rule) {
     timer = setInterval(
       () => {
         const current = rule.progress();
+        if (rule.complete?.() && !inTail) {
+          inTail = true;
+          return restartWindow(rule.tailMs ?? rule.noProgressMs);
+        }
         if (current !== last) return restartWindow(rule.noProgressMs);
         if (Date.now() - lastChangeAt < budgetMs) return;
         const error = new RenderStageStalledError(phase, budgetMs, current);
@@ -5521,6 +5542,7 @@ function watchStall(phase, rule) {
   });
   const openAttempt = (parent) => {
     attempt = new AbortController();
+    inTail = false;
     restartWindow(rule.firstProgressMs);
     return parent ? AbortSignal.any([parent, attempt.signal]) : attempt.signal;
   };
@@ -8512,7 +8534,8 @@ async function runCompileStage(input) {
 }
 
 // src/services/render/stages/probeStage.ts
-import { join as join17 } from "node:path";
+import { createHash as createHash7 } from "node:crypto";
+import { basename as basename5, join as join17 } from "node:path";
 import { parseHTML as parseHTML6 } from "linkedom";
 import {
   closeCaptureSession as closeCaptureSession4,
@@ -8520,6 +8543,7 @@ import {
   createCaptureSession as createCaptureSession4,
   deriveBeginFrameProbeTimeTicks,
   getCompositionDuration,
+  getCompositionLengthSource,
   initializeSession as initializeSession4,
   isTransientBrowserError,
   probeBeginFrameLiveness,
@@ -8658,6 +8682,13 @@ function hasRuntimeMediaChanges(html) {
 function probeRequiresBrowser(args) {
   return args.durationSeconds <= 0 || args.unresolvedCompositionCount > 0 || args.hasAutoStart || args.hasScriptedAudio || args.hasVariableMedia || args.hasInsertedMedia;
 }
+function reportedLengthSource(source) {
+  if (!source) return null;
+  if (source.from !== "media") return { from: source.from };
+  const name = basename5(source.src.split(/[?#]/, 1)[0] ?? "");
+  const srcHash = createHash7("sha256").update(name).digest("hex").slice(0, 12);
+  return { from: "media", tag: source.tag, trimmed: source.trimmed, srcHash };
+}
 async function runProbeStage(input) {
   const {
     projectDir,
@@ -8679,6 +8710,7 @@ async function runProbeStage(input) {
   const probeCfg = cfg.forceScreenshot === forceScreenshot ? cfg : { ...cfg, forceScreenshot };
   let fileServer = null;
   let probeSession = null;
+  let lengthSource = input.composition.duration > 0 ? { from: "declared" } : null;
   let beginFrameStalled = false;
   let lastBrowserConsole = [];
   const probeStart = Date.now();
@@ -8840,10 +8872,12 @@ async function runProbeStage(input) {
       if (composition.duration <= 0) {
         log.info("Discovering composition duration...");
         const discoveredDuration = await getCompositionDuration(session);
+        lengthSource = reportedLengthSource(await getCompositionLengthSource(session));
         assertNotAborted();
         log.info("Probed composition duration from browser", {
           discoveredDuration,
-          staticDuration: compiled.staticDuration
+          staticDuration: compiled.staticDuration,
+          lengthSource
         });
         composition.duration = discoveredDuration;
       } else {
@@ -9132,6 +9166,7 @@ async function runProbeStage(input) {
     probeSession,
     lastBrowserConsole,
     duration,
+    lengthSource,
     totalFrames,
     browserProbeMs,
     beginFrameStalled
@@ -9619,7 +9654,7 @@ function checkedDbfs(value) {
   }
   return value;
 }
-async function scanTruePeak(audioPath, trim, timeoutMs, signal) {
+async function scanTruePeak(audioPath, trim, timeoutMs, signal, seekSeconds = 0) {
   let firstBlock;
   let laterBlocks = Number.NEGATIVE_INFINITY;
   let partialLine = "";
@@ -9635,7 +9670,21 @@ async function scanTruePeak(audioPath, trim, timeoutMs, signal) {
     }
   };
   const result = await runFfmpeg4(
-    ["-i", audioPath, "-map", "0:a:0", "-vn", "-af", `${trim}ebur128=peak=true`, "-f", "null", "-"],
+    [
+      ...seekSeconds > 0 ? ["-ss", String(seekSeconds)] : [],
+      ...[
+        "-i",
+        audioPath,
+        "-map",
+        "0:a:0",
+        "-vn",
+        "-af",
+        `${trim}ebur128=peak=true`,
+        "-f",
+        "null",
+        "-"
+      ]
+    ],
     { signal, timeout: timeoutMs, onStderr: readLines }
   );
   if (!result.success) {
@@ -9661,12 +9710,15 @@ async function measureTruePeakDbfs(audioPath, options) {
   const scans = await Promise.all(
     Array.from({ length: count }, (_, k) => {
       const start = k === 0 ? 0 : cut(k) - block;
-      const end = k === count - 1 ? "" : `:end_sample=${cut(k + 1)}`;
+      const seekSeconds = Math.max(0, Math.floor(start / sampleRate) - 1);
+      const skipped = seekSeconds * sampleRate;
+      const end = k === count - 1 ? "" : `:end_sample=${cut(k + 1) - skipped}`;
       return scanTruePeak(
         audioPath,
-        `atrim=start_sample=${start}${end},`,
+        `atrim=start_sample=${start - skipped}${end},`,
         timeoutMs,
-        segmentSignal
+        segmentSignal,
+        seekSeconds
       );
     })
   ).catch((error) => {
@@ -12295,12 +12347,15 @@ function resetCaptureAttemptProgress(job) {
   job.framesRendered = 0;
 }
 var FIRST_FRAME_STALL_MS = 3e5;
-function frameStallRule(job) {
+var TAIL_STALL_MS = FIRST_FRAME_STALL_MS;
+function frameStallRule(job, totalFrames) {
   const noProgressMs = resolveCaptureStallTimeoutMs();
   return {
     progress: () => job.framesRendered ?? 0,
     noProgressMs,
-    firstProgressMs: Math.max(FIRST_FRAME_STALL_MS, noProgressMs)
+    firstProgressMs: Math.max(FIRST_FRAME_STALL_MS, noProgressMs),
+    complete: () => (job.framesRendered ?? 0) >= totalFrames,
+    tailMs: Math.max(TAIL_STALL_MS, noProgressMs)
   };
 }
 function isRecoverableParallelCaptureError(error) {
@@ -13317,6 +13372,12 @@ async function executeRenderPipeline(input) {
     }
     observability.checkpoint("browser_probe", "duration resolved", {
       durationSeconds: probeResult.duration,
+      lengthFrom: probeResult.lengthSource?.from ?? null,
+      ...probeResult.lengthSource?.from === "media" ? {
+        lengthTag: probeResult.lengthSource.tag,
+        lengthTrimmed: probeResult.lengthSource.trimmed,
+        lengthSrcHash: probeResult.lengthSource.srcHash
+      } : {},
       totalFrames,
       compositionHash,
       beginFrameStalled: probeResult.beginFrameStalled
@@ -13502,6 +13563,14 @@ async function executeRenderPipeline(input) {
       // sample frame indices from this so they land inside the drained range.
       compositionDurationSeconds: job.duration,
       deFrameFallback: true,
+      // A line per scanned chunk, so a long effect scan reads as preparing, not as a stall.
+      onEffectScanProgress: (scanned, total) => updateJobStatus(
+        job,
+        "rendering",
+        `Checking effects, ${scanned} of ${total} frames`,
+        25,
+        onProgress
+      ),
       requiresWebGpu: compositionRequiresWebGpu2(compiled.html),
       // Live route for Chrome memory (spec §5 Phase −1). The aggregate route
       // through CapturePerfSummary only exists on success; a mid-capture
@@ -14186,7 +14255,7 @@ async function executeRenderPipeline(input) {
             onProgress
           });
         },
-        { stall: frameStallRule(job) }
+        { stall: frameStallRule(job, totalFrames) }
       );
       lastBrowserConsole = hdrRes.lastBrowserConsole;
       layeredCaptureWarnings.push(...hdrRes.warnings);
@@ -14631,7 +14700,7 @@ async function executeRenderPipeline(input) {
             interleaveFrames: overlap !== null,
             openAttempt
           }),
-          { stall: frameStallRule(job) }
+          { stall: frameStallRule(job, totalFrames) }
         );
         let captureRes;
         try {
@@ -15524,9 +15593,7 @@ function renderConfigFromRequest(request, runtime = {}) {
   };
 }
 
-// src/server.ts
-var DEFAULT_SERVER_FPS = { num: 30, den: 1 };
-var SSE_KEEPALIVE_MS = 3e4;
+// src/services/safeRenderErrorCode.ts
 var SAFE_RENDER_ERROR_CODES = /* @__PURE__ */ new Set([
   "ASSET_MEDIA_TYPE_MISMATCH",
   "HEIF_IMAGE_CONVERSION_FAILED",
@@ -15544,6 +15611,10 @@ function extractSafeRenderErrorCode(error) {
   const code = error.code;
   return typeof code === "string" && SAFE_RENDER_ERROR_CODES.has(code) ? code : void 0;
 }
+
+// src/server.ts
+var DEFAULT_SERVER_FPS = { num: 30, den: 1 };
+var SSE_KEEPALIVE_MS = 3e4;
 function extractSafeRenderErrorMetadata(error) {
   const errorCode = extractSafeRenderErrorCode(error);
   if (!errorCode || typeof error !== "object" || error === null) return void 0;

package/dist/server.d.ts

@@ -16,6 +16,8 @@ import { Hono, type Context } from "hono";
 import { type RenderConfig } from "./services/renderOrchestrator.js";
 import { type ProducerLogger } from "./logger.js";
 import { type CanvasResolution } from "@hyperframes/core";
+import { extractSafeRenderErrorCode } from "./services/safeRenderErrorCode.js";
+export { extractSafeRenderErrorCode };
 export interface HandlerOptions {
     /** Custom logger. Defaults to console-based defaultLogger. */
     logger?: ProducerLogger;
@@ -80,11 +82,6 @@ interface PreparedRenderInput {
     input: RenderInput;
     cleanupProjectDir?: string;
 }
-/**
- * Preserve only bounded producer error codes across JSON/SSE. Never derive a
- * code from the message: it may contain local paths or signed source URLs.
- */
-export declare function extractSafeRenderErrorCode(error: unknown): string | undefined;
 export interface SafeRenderErrorMetadata {
     errorCode: string;
     errorOwner?: "system" | "user";
@@ -126,4 +123,3 @@ export declare function createProducerApp(options?: HandlerOptions): Hono;
  * Start the producer HTTP server with graceful shutdown.
  */
 export declare function startServer(options?: ServerOptions): import("@hono/node-server").ServerType;
-export {};

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

@@ -333,6 +333,10 @@ export interface StageStallRule {
     noProgressMs: number;
     /** Allowed silence before the current attempt's first change. */
     firstProgressMs: number;
+    /** True once every unit of work has landed: nothing more can change `progress()`, only the tail work runs. */
+    complete?: () => boolean;
+    /** Allowed silence once `complete()` holds; defaults to `noProgressMs`. */
+    tailMs?: number;
 }
 /**
  * Classified like the per-call protocol timeout it replaces, so the capture retry ladder retries it.

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

@@ -26,7 +26,7 @@
  *     regex, the same first-10/first-5 slicing, and the same `console.warn`
  *     prefix.
  */
-import { type CaptureSession, type EngineConfig, type SubTimelineWaitMemo } from "@hyperframes/engine";
+import { 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";
@@ -67,6 +67,8 @@ export interface ProbeStageResult {
     lastBrowserConsole: string[];
     /** Composition duration (post-probe). Guaranteed > 0 — the stage throws on <= 0. */
     duration: number;
+    /** Which input set `duration`; null when the runtime did not say. */
+    lengthSource: ReportedLengthSource | null;
     totalFrames: number;
     /** Wall-clock ms for the entire probe phase (near-zero when `needsBrowser` was false). */
     browserProbeMs: number;
@@ -113,6 +115,16 @@ export declare function probeRequiresBrowser(args: {
     hasVariableMedia: boolean;
     hasInsertedMedia: boolean;
 }): boolean;
+export type ReportedLengthSource = {
+    from: Exclude<CompositionLengthSource["from"], "media">;
+} | {
+    from: "media";
+    tag: string;
+    trimmed: boolean;
+    srcHash: string;
+};
+/** The length source with a media clip's src reduced to a hash of its file name, so no path leaves the render. */
+export declare function reportedLengthSource(source: CompositionLengthSource | null): ReportedLengthSource | null;
 export declare function runProbeStage(input: ProbeStageInput): Promise<ProbeStageResult>;
 /**
  * Preview/render parity for `muted` media: the runtime keeps muted elements

package/dist/services/renderOrchestrator.d.ts

@@ -567,10 +567,11 @@ export declare function captureAttemptMadeProgress(attemptTargetFrameCount: numb
 export declare function resetCaptureAttemptProgress(job: {
     framesRendered?: number;
 }): void;
-/** The no-progress rule for capture stages that have no watchdog of their own: disk, HDR, chunk. */
+/** The no-progress rule for capture stages that have no watchdog of their own: disk, HDR, chunk. Once
+ * `totalFrames` have landed the frame count can no longer change, so the stage is judged on the tail budget. */
 export declare function frameStallRule(job: {
     framesRendered?: number;
-}): StageStallRule;
+}, totalFrames: number): StageStallRule;
 export declare function isRecoverableParallelCaptureError(error: unknown): boolean;
 /**
  * Turn a cryptic memory-exhaustion failure (V8 `Set maximum size exceeded`,

package/dist/services/safeRenderErrorCode.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Preserve only bounded producer error codes across JSON/SSE. Never derive a
+ * code from the message: it may contain local paths or signed source URLs.
+ */
+export declare function extractSafeRenderErrorCode(error: unknown): string | undefined;

package/package.json

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