@hyperframes/producer 0.8.207 → 0.8.208

package/dist/index.js

@@ -9256,10 +9256,11 @@ var VideoExtractionStageError = class extends Error {
       kind: failure.kind,
       affectedElementCount: failure.count
     }))
-  )) {
+  ), ffmpegReason) {
     const total = failures.reduce((sum2, failure) => sum2 + failure.count, 0);
     const breakdown = failures.map((failure) => `${failure.kind}=${failure.count}`).join(",");
-    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]`);
+    const reason = ffmpegReason ? `: ffmpeg said: ${ffmpegReason}` : "";
+    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]${reason}`);
     this.code = code;
     this.retryable = retryable;
     this.failures = failures;
@@ -9306,7 +9307,8 @@ function buildVideoExtractionStageError(result) {
     retryable ? "VIDEO_EXTRACTION_FAILED" : "VIDEO_SOURCE_UNRENDERABLE",
     retryable,
     failures,
-    extractionFailureMetadataFromResult(result)
+    extractionFailureMetadataFromResult(result),
+    result.errors.find((failure) => failure.ffmpegReason)?.ffmpegReason
   );
 }
 function buildHdrProbeStageError(failures) {
@@ -10303,6 +10305,7 @@ async function runCaptureStage(input) {
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       openAttempt: input.openAttempt,
+      verifyFirstSession: input.verifyFirstSession,
       onProgress: (progress) => {
         if (progress.latestWorkerPhase) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
@@ -12362,7 +12365,8 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
               });
             } : void 0,
             void 0,
-            options.cfg
+            options.cfg,
+            { verifyFirstSession: options.verifyFirstSession }
           );
           pushWorkerDedupPerfs(workerResults, options.dedupPerfs);
           if (options.pageErrorLines) pushWorkerPageErrors(workerResults, options.pageErrorLines);
@@ -20245,16 +20249,18 @@ function observedChunkCaptureMode(perfs) {
   }
   return mode;
 }
+var PROBE_SELECTED_SCREENSHOT = "[renderChunk] probe selected screenshot capture";
 function shouldRetryChunkCaptureWithScreenshot(error) {
   const failure = classifyCaptureFailure4(error);
   if (failure.kind === "cancelled" || failure.kind === "memory_exhaustion") return false;
-  return /HeadlessExperimental\.beginFrame/i.test(failure.message) || /beginFrame probe timeout/i.test(failure.message) || /Another frame is pending|Frame still pending/i.test(failure.message);
+  return /HeadlessExperimental\.beginFrame/i.test(failure.message) || /beginFrame probe timeout/i.test(failure.message) || failure.message.includes(PROBE_SELECTED_SCREENSHOT) || /Another frame is pending|Frame still pending/i.test(failure.message);
 }
 async function runCaptureWithScreenshotFallback(input) {
   try {
     return await input.run(input.forceScreenshot);
   } catch (error) {
-    if (input.forceScreenshot || !shouldRetryChunkCaptureWithScreenshot(error)) throw error;
+    if (input.forceScreenshot || await input.canRetry?.() === false) throw error;
+    if (!shouldRetryChunkCaptureWithScreenshot(error)) throw error;
     input.onFallback?.(error);
     await input.resetForScreenshotRetry();
     return await input.run(true);
@@ -20463,7 +20469,24 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     let extraction;
     const overlap = { current: null };
     try {
-      if (chunkWorkerCount === 1 || !forceScreenshotForChunk) {
+      const verifyInWorker = chunkWorkerCount > 1 && !forceScreenshotForChunk;
+      let boxesMeasured;
+      let boxesFailed;
+      const boxesReady = new Promise((resolve13, reject) => {
+        boxesMeasured = resolve13;
+        boxesFailed = reject;
+      });
+      boxesReady.catch(() => {
+      });
+      const measureBoxes = async (page) => {
+        shownBoxes = await measureVideoShownBoxes(
+          page,
+          [...shownFrames.keys()],
+          chunkFrameNumbers.map((frame) => frame * chunkFps.den / chunkFps.num)
+        );
+        boxesMeasured();
+      };
+      if (chunkWorkerCount === 1) {
         const bootStarted = Date.now();
         session = await createVerifiedDistributedCaptureSession(
           fileServer.url,
@@ -20472,11 +20495,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           cfg
         );
         sessionBootMs = Date.now() - bootStarted;
-        shownBoxes = await measureVideoShownBoxes(
-          session.page,
-          [...shownFrames.keys()],
-          chunkFrameNumbers.map((frame) => frame * chunkFps.den / chunkFps.num)
-        );
+        await measureBoxes(session.page);
         const browserSelectedScreenshot = session.launchCaptureMode === "screenshot";
         const beginFrameStalled = !browserSelectedScreenshot && await beginFrameSessionNeedsScreenshotFallback(session);
         if (browserSelectedScreenshot) {
@@ -20485,10 +20504,6 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
             "[renderChunk] Browser capability probe selected screenshot capture for the entire chunk",
             { chunkIndex }
           );
-          if (chunkWorkerCount > 1) {
-            await closeCaptureSession11(session);
-            session = null;
-          }
         } else if (beginFrameStalled) {
           forceScreenshotForChunk = true;
           log.warn(
@@ -20498,41 +20513,66 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           await closeCaptureSession11(session).catch(() => {
           });
           session = null;
-          if (chunkWorkerCount === 1) {
-            const screenshotBootStarted = Date.now();
-            const screenshotCfg = {
-              ...cfg,
-              forceScreenshot: true,
-              forceScreenshotExplicitlyOptedOut: false
-            };
-            session = await createVerifiedDistributedCaptureSession(
-              fileServer.url,
-              framesDir,
-              captureOptions,
-              screenshotCfg
+          const screenshotBootStarted = Date.now();
+          const screenshotCfg = {
+            ...cfg,
+            forceScreenshot: true,
+            forceScreenshotExplicitlyOptedOut: false
+          };
+          session = await createVerifiedDistributedCaptureSession(
+            fileServer.url,
+            framesDir,
+            captureOptions,
+            screenshotCfg
+          );
+          sessionBootMs += Date.now() - screenshotBootStarted;
+        }
+      } else if (!verifyInWorker) {
+        boxesMeasured();
+      }
+      let verification;
+      const verifyFirstWorker = (first) => verification ??= (async () => {
+        sessionBootMs = Date.now() - verifyStarted;
+        try {
+          await measureBoxes(first.page);
+          const selectedScreenshot = first.launchCaptureMode === "screenshot";
+          if (selectedScreenshot || await beginFrameSessionNeedsScreenshotFallback(first)) {
+            forceScreenshotForChunk = true;
+            log.warn(
+              selectedScreenshot ? "[renderChunk] Browser capability probe selected screenshot capture for the entire chunk" : "[renderChunk] BeginFrame liveness probe failed; using screenshot capture for the entire chunk",
+              { chunkIndex }
             );
-            sessionBootMs += Date.now() - screenshotBootStarted;
+            throw new Error(PROBE_SELECTED_SCREENSHOT);
           }
-        } else if (chunkWorkerCount > 1) {
-          await closeCaptureSession11(session);
-          session = null;
+        } catch (error) {
+          if (!forceScreenshotForChunk) {
+            verifyFailure = error;
+            boxesFailed(error);
+          }
+          throw error;
         }
-      }
-      const extractStarted = Date.now();
-      const deferredVideoFrames = planVideos ? extractDeferredVideoFramesForChunk({
-        planDir,
-        planVideos,
-        frames: chunkFrameNumbers,
-        fps: chunkFps,
-        outputRoot: videoFramesDir,
-        cfg,
-        remoteSources,
-        shownBoxes
-      }).then((frames) => {
-        videoExtractMs = Date.now() - extractStarted;
-        return frames;
-      }) : Promise.resolve([]);
+      })();
+      let verifyStarted = 0;
+      let verifyFailure;
+      const deferredVideoFrames = planVideos ? boxesReady.then(() => {
+        const extractStarted = Date.now();
+        return extractDeferredVideoFramesForChunk({
+          planDir,
+          planVideos,
+          frames: chunkFrameNumbers,
+          fps: chunkFps,
+          outputRoot: videoFramesDir,
+          cfg,
+          remoteSources,
+          shownBoxes
+        }).then((frames) => {
+          videoExtractMs = Date.now() - extractStarted;
+          return frames;
+        });
+      }) : boxesReady.then(() => []);
       extraction = deferredVideoFrames;
+      deferredVideoFrames.catch(() => {
+      });
       const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? deferredVideoFrames.then(
         (deferred) => createFrameLookupTable5(
           planVideos.videos,
@@ -20611,6 +20651,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       const captureStarted = Date.now();
       captureMode = await runCaptureWithScreenshotFallback({
         forceScreenshot: forceScreenshotForChunk,
+        canRetry: () => verifyFailure === void 0,
         // fallow-ignore-next-line complexity
         run: async (forceScreenshot) => {
           const captureCfg = cfg.forceScreenshot === forceScreenshot ? cfg : {
@@ -20640,6 +20681,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           }
           const captureSession = session;
           session = null;
+          verifyStarted = Date.now();
           overlap.current = canEncodeWhileCapturing(encodeInput, chunkWorkerCount, cpus3().length) ? encodeWhileCapturing(encodeInput, framesInChunk) : null;
           await observeRenderStage(
             new RenderObservabilityRecorder({ pipelineStartMs: start, log }),
@@ -20667,7 +20709,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
               frameRange: range,
               onFrameLanded: (frame) => overlap.current?.onFrameLanded(frame),
               interleaveFrames: interleavesCapture(overlap.current !== null, options),
-              openAttempt
+              openAttempt,
+              verifyFirstSession: forceScreenshot || !verifyInWorker ? void 0 : verifyFirstWorker
             }),
             { stall: frameStallRule(job) }
           ).catch(async (captureError) => {
@@ -20679,6 +20722,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         },
         resetForScreenshotRetry: () => {
           rmSync17(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+          boxesMeasured();
           mkdirSync19(framesDir, { recursive: true });
           capturePerfs.length = 0;
           captureAttempts.length = 0;
@@ -20694,6 +20738,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           );
         }
       }).catch(async (captureError) => {
+        if (verifyFailure !== void 0) throw verifyFailure;
+        boxesFailed(captureError);
         await deferredVideoFrames;
         throw captureError;
       });

package/dist/public-server.js

@@ -9242,10 +9242,11 @@ var VideoExtractionStageError = class extends Error {
       kind: failure.kind,
       affectedElementCount: failure.count
     }))
-  )) {
+  ), ffmpegReason) {
     const total = failures.reduce((sum, failure) => sum + failure.count, 0);
     const breakdown = failures.map((failure) => `${failure.kind}=${failure.count}`).join(",");
-    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]`);
+    const reason = ffmpegReason ? `: ffmpeg said: ${ffmpegReason}` : "";
+    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]${reason}`);
     this.code = code;
     this.retryable = retryable;
     this.failures = failures;
@@ -9287,7 +9288,8 @@ function buildVideoExtractionStageError(result) {
     retryable ? "VIDEO_EXTRACTION_FAILED" : "VIDEO_SOURCE_UNRENDERABLE",
     retryable,
     failures,
-    extractionFailureMetadataFromResult(result)
+    extractionFailureMetadataFromResult(result),
+    result.errors.find((failure) => failure.ffmpegReason)?.ffmpegReason
   );
 }
 function buildHdrProbeStageError(failures) {
@@ -10284,6 +10286,7 @@ async function runCaptureStage(input) {
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       openAttempt: input.openAttempt,
+      verifyFirstSession: input.verifyFirstSession,
       onProgress: (progress) => {
         if (progress.latestWorkerPhase) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
@@ -12343,7 +12346,8 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
               });
             } : void 0,
             void 0,
-            options.cfg
+            options.cfg,
+            { verifyFirstSession: options.verifyFirstSession }
           );
           pushWorkerDedupPerfs(workerResults, options.dedupPerfs);
           if (options.pageErrorLines) pushWorkerPageErrors(workerResults, options.pageErrorLines);

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

@@ -156,6 +156,8 @@ export declare function shouldRetryChunkCaptureWithScreenshot(error: unknown): b
  */
 export declare function runCaptureWithScreenshotFallback<T>(input: {
     forceScreenshot: boolean;
+    /** A failure that is not capture's (the probe's own) is never retried. */
+    canRetry?: () => boolean | Promise<boolean>;
     run: (forceScreenshot: boolean) => Promise<T>;
     resetForScreenshotRetry: () => Promise<void> | void;
     onFallback?: (error: unknown) => void;

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

@@ -88,6 +88,7 @@ export interface CaptureStageInput {
     interleaveFrames?: boolean;
     /** Each capture attempt opens one, so a stalled attempt is retried by the ladders below. */
     openAttempt?: OpenStallAttempt;
+    verifyFirstSession?: (session: CaptureSession) => Promise<void>;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */

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

@@ -117,7 +117,7 @@ export declare class VideoExtractionStageError extends Error {
      * validating and applying policy to it.
      */
     readonly publicMetadata: Readonly<Record<string, unknown>>;
-    constructor(code: VideoExtractionStageErrorCode, retryable: boolean, failures: readonly VideoExtractionStageFailureSummary[], extractionFailure?: ExtractionFailureMetadataV1);
+    constructor(code: VideoExtractionStageErrorCode, retryable: boolean, failures: readonly VideoExtractionStageFailureSummary[], extractionFailure?: ExtractionFailureMetadataV1, ffmpegReason?: string);
 }
 export declare function assertVideoExtractionSucceeded(result: ExtractionResult): void;
 export declare function buildHdrProbeStageError(failures: readonly Pick<ReturnType<typeof classifyVideoExtractionError>, "kind" | "retryable">[]): VideoExtractionStageError;

package/dist/services/renderOrchestrator.d.ts

@@ -610,6 +610,7 @@ export declare function executeDiskCaptureWithAdaptiveRetry(options: {
     /** Mutated in place: the workers' page-error console lines, for the render's error count. */
     pageErrorLines?: string[];
     openAttempt?: OpenStallAttempt;
+    verifyFirstSession?: (session: CaptureSession) => Promise<void>;
 }): Promise<CaptureAttemptSummary[]>;
 export type RenderConfigInput = Omit<RenderConfig, "fps"> & {
     fps: FpsInput;

package/package.json

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