@hyperframes/producer 0.8.202 → 0.8.204

package/dist/public-server.js

@@ -1259,6 +1259,7 @@ function buildRenderErrorDetails(input) {
 
 // src/services/render/renderEventPublisher.ts
 import { cloneCaptureWarnings } from "@hyperframes/engine";
+var FLUSH_TIMEOUT_MS = 1e4;
 function snapshotJob(job) {
   return {
     ...job,
@@ -1288,7 +1289,15 @@ var OrderedRenderEventPublisher = class {
     });
   }
   async flush() {
-    await this.tail;
+    let timer;
+    const drained = await Promise.race([
+      this.tail.then(() => true),
+      new Promise((resolve10) => {
+        timer = setTimeout(() => resolve10(false), FLUSH_TIMEOUT_MS);
+      })
+    ]);
+    clearTimeout(timer);
+    if (!drained) this.log.warn("Render event sink did not drain; continuing without it");
   }
 };
 function publishRenderFailure(job, failure, onProgress) {
@@ -5120,6 +5129,7 @@ function shouldFallbackToScreenshotAfterCalibrationError(error) {
 // src/services/render/observability.ts
 import { createHash as createHash3 } from "node:crypto";
 import { redactTelemetryString } from "@hyperframes/core";
+import { CaptureFailure as CaptureFailure2 } from "@hyperframes/engine";
 var MAX_EVENTS = 160;
 var ALLOWED_STRING_DATA_KEYS = /* @__PURE__ */ new Set([
   "browserGpuMode",
@@ -5352,6 +5362,56 @@ function heartbeatTargetMs(index) {
   const overflow = index - HEARTBEAT_RAMP_MS.length + 1;
   return HEARTBEAT_RAMP_END_MS + overflow * HEARTBEAT_REPEAT_MS;
 }
+var RenderStageStalledError = class extends CaptureFailure2 {
+  code = "RENDER_STAGE_STALLED";
+  owner = "system";
+  retryable = false;
+  constructor(phase, silentMs, progress) {
+    super({
+      kind: "protocol_timeout",
+      message: `[Render] ${phase} stalled: no progress for ${silentMs}ms (stuck at ${progress}).`
+    });
+    this.name = "RenderStageStalledError";
+  }
+};
+var STALL_POLL_MS = 5e3;
+function watchStall(phase, rule) {
+  let last = rule.progress();
+  let budgetMs = rule.firstProgressMs;
+  let lastChangeAt = Date.now();
+  let attempt;
+  let timer;
+  const restartWindow = (ms) => {
+    last = rule.progress();
+    budgetMs = ms;
+    lastChangeAt = Date.now();
+  };
+  const tripped = new Promise((_, reject) => {
+    timer = setInterval(
+      () => {
+        const current = rule.progress();
+        if (current !== last) return restartWindow(rule.noProgressMs);
+        if (Date.now() - lastChangeAt < budgetMs) return;
+        const error = new RenderStageStalledError(phase, budgetMs, current);
+        if (attempt && !attempt.signal.aborted) {
+          attempt.abort(error);
+          return restartWindow(rule.noProgressMs);
+        }
+        clearInterval(timer);
+        reject(error);
+      },
+      Math.min(STALL_POLL_MS, rule.noProgressMs, rule.firstProgressMs)
+    );
+  });
+  const openAttempt = (parent) => {
+    attempt = new AbortController();
+    restartWindow(rule.firstProgressMs);
+    return parent ? AbortSignal.any([parent, attempt.signal]) : attempt.signal;
+  };
+  const stalledBy = () => attempt?.signal.aborted ? attempt.signal.reason : void 0;
+  return { tripped, openAttempt, stalledBy, stop: () => clearInterval(timer) };
+}
+var openUnwatchedAttempt = (parent) => parent ?? new AbortController().signal;
 async function observeRenderStage(recorder, phase, data, fn, options = {}) {
   const heartbeatMessage = options.heartbeatMessage ?? "stage still running";
   const startedAt = recorder.stageStart(phase, data);
@@ -5373,15 +5433,19 @@ async function observeRenderStage(recorder, phase, data, fn, options = {}) {
     heartbeatTimer.unref?.();
   };
   scheduleNextHeartbeat();
+  const stall = options.stall ? watchStall(phase, options.stall) : void 0;
   const clearHeartbeats = () => {
     clearTimeout(heartbeatTimer);
+    stall?.stop();
   };
   try {
-    const result = await fn();
+    const run = fn(stall?.openAttempt ?? openUnwatchedAttempt);
+    const result = await (stall ? Promise.race([run, stall.tripped]) : run);
     clearHeartbeats();
     recorder.stageEnd(phase, startedAt, data);
     return result;
-  } catch (error) {
+  } catch (caught) {
+    const error = stall?.stalledBy() ?? caught;
     clearHeartbeats();
     recorder.stageError(phase, startedAt, error, data);
     throw error;
@@ -7536,9 +7600,10 @@ async function discoverMediaFromBrowser(page) {
       const tagName = isImage ? "image" : htmlEl.tagName.toLowerCase() === "video" ? "video" : "audio";
       const id = htmlEl.getAttribute("data-hf-render-id") || htmlEl.id || (isImage ? autoImageIds.get(htmlEl) : void 0);
       if (!id) return;
-      const ownSrc = htmlEl.getAttribute("src");
-      const blankSrc = ownSrc !== null && ownSrc.trim() === "" && !htmlEl.querySelector("source[src]");
-      const src = blankSrc ? "" : htmlEl.currentSrc || htmlEl.src || ownSrc || "";
+      const resolvedSrc = htmlEl.currentSrc || htmlEl.src || htmlEl.getAttribute("src") || "";
+      const withoutQueryAndHash = (url) => url.replace(/[?#][\s\S]*$/, "");
+      const isPageItself = withoutQueryAndHash(resolvedSrc) === withoutQueryAndHash(location.href);
+      const src = isPageItself ? "" : resolvedSrc;
       const start = parseFloat(htmlEl.getAttribute("data-start") || "0");
       const endRaw = htmlEl.getAttribute("data-end");
       const durationRaw = htmlEl.getAttribute("data-duration");
@@ -9808,6 +9873,7 @@ async function runCaptureStage(input) {
       interleaveFrames: input.interleaveFrames,
       dedupPerfs,
       pageErrorLines: workerPageErrors,
+      openAttempt: input.openAttempt,
       onProgress: (progress) => {
         if (progress.latestWorkerPhase) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
@@ -9879,6 +9945,11 @@ async function runSequentialDiskCapture(input, captureOptions, captureCfg, check
   let transientRetriesUsed = 0;
   let resumeFrom = 0;
   while (true) {
+    const attempt = input.openAttempt?.();
+    const assertAttemptActive = () => {
+      assertNotAborted();
+      attempt?.throwIfAborted();
+    };
     const videoInjector = createRenderVideoFrameInjector();
     const session = probeSession ?? await createCaptureSession5(
       fileServer.url,
@@ -9894,10 +9965,10 @@ async function runSequentialDiskCapture(input, captureOptions, captureCfg, check
         probeSession = null;
       }
       await ensureSessionReady(session);
-      assertNotAborted();
+      assertAttemptActive();
       lastBrowserConsole = session.browserConsoleBuffer;
       await captureSessionFrames(session, {
-        input,
+        input: { ...input, assertNotAborted: assertAttemptActive },
         rangeStart,
         rangeEnd,
         resumeFrom,
@@ -11757,7 +11828,17 @@ function captureAttemptMadeProgress(attemptTargetFrameCount, remainingFrameCount
 function resetCaptureAttemptProgress(job) {
   job.framesRendered = 0;
 }
+var FIRST_FRAME_STALL_MS = 3e5;
+function frameStallRule(job) {
+  const noProgressMs = resolveCaptureStallTimeoutMs();
+  return {
+    progress: () => job.framesRendered ?? 0,
+    noProgressMs,
+    firstProgressMs: Math.max(FIRST_FRAME_STALL_MS, noProgressMs)
+  };
+}
 function isRecoverableParallelCaptureError(error) {
+  if (error instanceof RenderStageStalledError) return true;
   const message = normalizeErrorMessage(error);
   if (!message.includes("[Parallel] Capture failed")) return false;
   const kind = classifyCaptureFailure3(error).kind;
@@ -11820,8 +11901,10 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
       )
     ];
     options.dedupPerfs.length = 0;
+    let attemptSignal = options.abortSignal;
     try {
       for (const tasks of batches) {
+        attemptSignal = options.openAttempt?.(options.abortSignal) ?? options.abortSignal;
         const capturedBeforeBatch = countCapturedFrames(
           options.totalFrames,
           options.framesDir,
@@ -11834,7 +11917,7 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
             tasks,
             options.captureOptions,
             options.createBeforeCaptureHook,
-            options.abortSignal,
+            attemptSignal,
             options.onProgress ? (progress) => {
               options.onProgress?.({
                 ...progress,
@@ -11882,7 +11965,8 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
       currentWorkers = nextWorkers;
       missingRanges = remaining;
       attempt++;
-    } catch (error) {
+    } catch (caught) {
+      const error = attemptSignal?.aborted && !options.abortSignal?.aborted ? attemptSignal.reason : caught;
       const failure = classifyCaptureFailure3(error, { signal: options.abortSignal });
       if (failure.kind === "cancelled") {
         throw error;
@@ -13551,37 +13635,44 @@ async function executeRenderPipeline(input) {
         observability,
         "capture_hdr_layered",
         captureStageObservationData({ hasHdrContent }),
-        () => runCaptureHdrStage({
-          job,
-          cfg,
-          plan: layeredPlan,
-          log,
-          projectDir,
-          compiledDir,
-          framesDir,
-          videoOnlyPath,
-          width,
-          height,
-          totalFrames,
-          composition,
-          hasHdrContent,
-          effectiveHdr,
-          nativeHdrVideoIds,
-          nativeHdrImageIds,
-          videoTransfers,
-          imageTransfers,
-          hdrImageSrcPaths,
-          preset,
-          effectiveQuality,
-          effectiveBitrate,
-          fileServer: activeFileServer,
-          buildCaptureOptions,
-          createRenderVideoFrameInjector,
-          hdrDiagnostics,
-          abortSignal: executionSignal,
-          assertNotAborted,
-          onProgress
-        })
+        (openAttempt) => {
+          const attempt = openAttempt(executionSignal);
+          return runCaptureHdrStage({
+            job,
+            cfg,
+            plan: layeredPlan,
+            log,
+            projectDir,
+            compiledDir,
+            framesDir,
+            videoOnlyPath,
+            width,
+            height,
+            totalFrames,
+            composition,
+            hasHdrContent,
+            effectiveHdr,
+            nativeHdrVideoIds,
+            nativeHdrImageIds,
+            videoTransfers,
+            imageTransfers,
+            hdrImageSrcPaths,
+            preset,
+            effectiveQuality,
+            effectiveBitrate,
+            fileServer: activeFileServer,
+            buildCaptureOptions,
+            createRenderVideoFrameInjector,
+            hdrDiagnostics,
+            abortSignal: attempt,
+            assertNotAborted: () => {
+              assertNotAborted();
+              attempt.throwIfAborted();
+            },
+            onProgress
+          });
+        },
+        { stall: frameStallRule(job) }
       );
       lastBrowserConsole = hdrRes.lastBrowserConsole;
       layeredCaptureWarnings.push(...hdrRes.warnings);
@@ -13946,7 +14037,7 @@ async function executeRenderPipeline(input) {
           observability,
           "capture_disk",
           captureStageObservationData({ needsAlpha: diskPlan.needsAlpha }),
-          () => runCaptureStage({
+          (openAttempt) => runCaptureStage({
             fileServer: activeFileServer,
             workDir,
             framesDir,
@@ -13964,8 +14055,10 @@ async function executeRenderPipeline(input) {
             assertNotAborted,
             onProgress,
             onFrameLanded: (frame) => overlap?.onFrameLanded(frame),
-            interleaveFrames: overlap !== null
-          })
+            interleaveFrames: overlap !== null,
+            openAttempt
+          }),
+          { stall: frameStallRule(job) }
         );
         let captureRes;
         try {
@@ -14849,6 +14942,7 @@ function renderConfigFromRequest(request, runtime = {}) {
 
 // src/server.ts
 var DEFAULT_SERVER_FPS = { num: 30, den: 1 };
+var SSE_KEEPALIVE_MS = 3e4;
 var SAFE_RENDER_ERROR_CODES = /* @__PURE__ */ new Set([
   "ASSET_MEDIA_TYPE_MISMATCH",
   "NOT_MEDIA_PAYLOAD",
@@ -14856,7 +14950,8 @@ var SAFE_RENDER_ERROR_CODES = /* @__PURE__ */ new Set([
   "VIDEO_SOURCE_UNRENDERABLE",
   "VIDEO_EXTRACTION_FAILED",
   "ENCODER_INTERRUPTED",
-  "RENDER_TOO_SLOW"
+  "RENDER_TOO_SLOW",
+  "RENDER_STAGE_STALLED"
 ]);
 function extractSafeRenderErrorCode(error) {
   if (typeof error !== "object" || error === null || !("code" in error)) return void 0;
@@ -15370,15 +15465,21 @@ function createRenderHandlers(options = {}) {
           })
         });
       }
+      const reportProgress = createSseProgressReporter(stream, requestId);
+      const keepalive = setInterval(() => {
+        Promise.resolve(reportProgress(job, job.currentStage)).catch(() => {
+        });
+      }, SSE_KEEPALIVE_MS);
       const release = await renderSemaphore.acquire();
       try {
         await executeRenderJob(
           job,
           input.projectDir,
           absoluteOutputPath,
-          createSseProgressReporter(stream, requestId),
+          reportProgress,
           abortController.signal
-        );
+        ).finally(release);
+        clearInterval(keepalive);
         const fileSize = outputFileSize(absoluteOutputPath);
         const outputToken = store.register(absoluteOutputPath);
         const outputUrl = `${outputUrlPrefix}/${outputToken}`;
@@ -15398,6 +15499,7 @@ function createRenderHandlers(options = {}) {
           })
         });
       } catch (error) {
+        clearInterval(keepalive);
         await writeRenderStreamFailure({
           error,
           job,
@@ -15407,7 +15509,6 @@ function createRenderHandlers(options = {}) {
           log
         });
       } finally {
-        release();
         c.req.raw.signal.removeEventListener("abort", onRequestAbort);
         cleanupTempDir(cleanupProjectDir, log);
       }

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

@@ -115,7 +115,9 @@ export interface RenderChunkOptions {
      * this many, one browser per 20 frames; never lowers it.
      */
     maxCaptureWorkers?: number;
+    interleaveCapture?: boolean;
 }
+export declare function interleavesCapture(overlapping: boolean, options?: RenderChunkOptions): boolean;
 /** Capture browsers for a chunk: the machine-wide sizing, raised by the runtime's budget. */
 export declare function resolveChunkCaptureWorkers(framesInChunk: number, machineSized: number, maxCaptureWorkers: number | undefined): number;
 /** The frames a chunk renders: its slice, or a validated sub-range of it. */

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

@@ -1,3 +1,4 @@
+import { CaptureFailure } from "@hyperframes/engine";
 import type { ProducerLogger } from "../../logger.js";
 export type RenderObservationStatus = "start" | "end" | "error" | "checkpoint";
 export type RenderObservationValue = string | number | boolean | null;
@@ -323,5 +324,26 @@ export interface ObserveRenderStageOptions {
      * Defaults to "stage still running".
      */
     heartbeatMessage?: string;
+    stall?: StageStallRule;
 }
-export declare function observeRenderStage<T>(recorder: RenderObservabilityRecorder, phase: string, data: RenderObservationData | undefined, fn: () => Promise<T>, options?: ObserveRenderStageOptions): Promise<T>;
+/** Watches a stage's `progress()`; any change, in either direction, is progress. */
+export interface StageStallRule {
+    progress: () => number;
+    /** Allowed silence once `progress()` has changed in the current attempt. */
+    noProgressMs: number;
+    /** Allowed silence before the current attempt's first change. */
+    firstProgressMs: number;
+}
+/**
+ * Classified like the per-call protocol timeout it replaces, so the capture retry ladder retries it.
+ * Not retryable on the wire: the producer already spent its retries on it.
+ */
+export declare class RenderStageStalledError extends CaptureFailure {
+    readonly code = "RENDER_STAGE_STALLED";
+    readonly owner: "system";
+    readonly retryable: false;
+    constructor(phase: string, silentMs: number, progress: number);
+}
+/** 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;
+export declare function observeRenderStage<T>(recorder: RenderObservabilityRecorder, phase: string, data: RenderObservationData | undefined, fn: (openAttempt: OpenStallAttempt) => Promise<T>, options?: ObserveRenderStageOptions): Promise<T>;

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

@@ -35,6 +35,7 @@ import type { FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
 import { type CaptureAttemptSummary, type ProgressCallback, type RenderConfig, type RenderJob } from "../../renderOrchestrator.js";
 import type { SdrDiskCapturePlan } from "../capturePlan.js";
+import type { OpenStallAttempt } from "../observability.js";
 export interface CaptureStageInput {
     fileServer: FileServerHandle;
     workDir: string;
@@ -85,6 +86,8 @@ export interface CaptureStageInput {
     };
     onFrameLanded?: (frame: LandedFrame) => void;
     interleaveFrames?: boolean;
+    /** Each capture attempt opens one, so a stalled attempt is retried by the ladders below. */
+    openAttempt?: OpenStallAttempt;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */

package/dist/services/renderOrchestrator.d.ts

@@ -2,7 +2,7 @@ import { type CanvasResolution, type Fps, type FpsInput, type HfVfxCapture } fro
 import { type EngineConfig, type ExtractionPhaseBreakdown, type VideoFrameFormat, type CaptureOptions, type CaptureVideoMetadataHint, type CaptureSession, type BeforeCaptureHook, type ParallelProgress, type WorkerTask, type CapturePerfSummary, type CaptureWarning, type SubTimelineWaitOutcome, type WorkerSizing, type StaticVerificationOutcome, 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 } from "./render/observability.js";
+import { type RenderCaptureObservability, type RenderObservabilitySummary, type OpenStallAttempt, type StageStallRule } from "./render/observability.js";
 import { type HdrPerfSummary } from "./render/hdrPerf.js";
 export declare function sampleDirectoryBytes(dir: string): number;
 export type RenderStatus = "queued" | "preprocessing" | "rendering" | "encoding" | "assembling" | "complete" | "failed" | "cancelled";
@@ -559,6 +559,10 @@ 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. */
+export declare function frameStallRule(job: {
+    framesRendered?: number;
+}): StageStallRule;
 export declare function isRecoverableParallelCaptureError(error: unknown): boolean;
 /**
  * Turn a cryptic memory-exhaustion failure (V8 `Set maximum size exceeded`,
@@ -599,6 +603,7 @@ export declare function executeDiskCaptureWithAdaptiveRetry(options: {
     dedupPerfs: CapturePerfSummary[];
     /** Mutated in place: the workers' page-error console lines, for the render's error count. */
     pageErrorLines?: string[];
+    openAttempt?: OpenStallAttempt;
 }): Promise<CaptureAttemptSummary[]>;
 export type RenderConfigInput = Omit<RenderConfig, "fps"> & {
     fps: FpsInput;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.202",
+  "version": "0.8.204",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "0.8.202",
-    "@hyperframes/engine": "0.8.202",
-    "@hyperframes/lint": "0.8.202",
-    "@hyperframes/studio-server": "0.8.202",
-    "@hyperframes/parsers": "0.8.202"
+    "@hyperframes/engine": "0.8.204",
+    "@hyperframes/lint": "0.8.204",
+    "@hyperframes/core": "0.8.204",
+    "@hyperframes/parsers": "0.8.204",
+    "@hyperframes/studio-server": "0.8.204"
   },
   "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.202"
+    "@hyperframes/aws-lambda": "0.8.204"
   },
   "engines": {
     "node": ">=22"