@hyperframes/engine 0.8.146 → 0.8.147

package/dist/services/frameCapture.d.ts

@@ -20,6 +20,8 @@ export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSum
  * `heldVideoTime` (motion-blur samples only) is the output frame's time: a video on screen at
  * both times shows its frame for `heldVideoTime`, so footage does not smear. */
 export type BeforeCaptureHook = (page: Page, time: number, heldVideoTime?: number) => Promise<void>;
+/** The per-frame wait a capture is in, worded for the stall error a user reads. */
+type CaptureStep = "seeking the timeline" | "decoding CSS background images" | "injecting video frames" | "waiting for page seek handlers" | "loading color-grading LUTs" | "compositing the page" | "capturing the frame";
 export interface CaptureSession {
     browser: Browser;
     /** Exact ownership token for this browser acquisition. */
@@ -202,6 +204,7 @@ export interface CaptureSession {
      * retries via screenshot.
      */
     deFrameTimeouts?: number;
+    captureStep?: CaptureStep;
     /**
      * drawElement init passed every gate but stopped before verification +
      * canvas injection: the session has no video-frame injector yet (probe

package/dist/services/frameCapture.js

@@ -2040,7 +2040,9 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     assertVfxIntact(session);
     const quantizedTime = quantizeSeekTime(time, fpsToNumber(options.fps), seekOptions?.subFrameDivisions);
     const seekStart = Date.now();
+    session.captureStep = "seeking the timeline";
     const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
+    session.captureStep = "decoding CSS background images";
     await decodeDynamicCssBackgroundImages(page);
     const seekMs = Date.now() - seekStart;
     // Before-capture hook (e.g. video frame injection) — runs before
@@ -2048,9 +2050,12 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     // replacements for <video> elements.
     const beforeCaptureStart = Date.now();
     if (session.onBeforeCapture) {
+        session.captureStep = "injecting video frames";
         await session.onBeforeCapture(page, quantizedTime, heldVideoTime);
     }
+    session.captureStep = "waiting for page seek handlers";
     await waitForPendingSeekCompletion(page);
+    session.captureStep = "loading color-grading LUTs";
     await page.evaluate(async () => {
         const runtime = window.__hf?.colorGrading;
         await runtime?.waitForActiveLuts?.();
@@ -2063,6 +2068,7 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     if (hasPendingComposite &&
         session.captureMode !== "beginframe" &&
         session.captureMode !== "drawelement") {
+        session.captureStep = "compositing the page";
         await page.evaluate(async () => {
             const w = window;
             if (typeof w.__hf_page_composite_prepare === "function") {
@@ -2082,6 +2088,7 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
             }
         });
     }
+    session.captureStep = "capturing the frame";
     return { quantizedTime, seekMs, beforeCaptureMs };
 }
 // ── Static-frame dedup (default-on, opt-out HF_STATIC_DEDUP=false) ─────────────
@@ -3095,12 +3102,14 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
     const fps = fpsToNumber(session.options.fps);
     const frameTime = quantizeSeekTime(absFrameIndex / fps, fps);
     const eventfulSeekStart = Date.now();
+    session.captureStep = "seeking the timeline";
     await seekPageTimeline(session.page, frameTime, undefined);
     const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
     if (session.onBeforeCapture) {
         // The injector copies a video's own style only when its frame changes: inject at frameTime
         // first so the held frame carries frameTime's style, not the first sample's.
         const injectStart = Date.now();
+        session.captureStep = "injecting video frames";
         await session.onBeforeCapture(session.page, frameTime, frameTime);
         totals.beforeCaptureMs += Date.now() - injectStart;
     }
@@ -3125,6 +3134,7 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
         accumulator.add(sample.buffer);
     }
     const restoreSeekStart = Date.now();
+    session.captureStep = "seeking the timeline";
     await seekPageTimeline(session.page, frameTime, { suppressEvents: true });
     totals.seekMs += Date.now() - restoreSeekStart;
     const blended = accumulator.finish();
@@ -3396,6 +3406,7 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
     const startTime = Date.now();
     const fps = fpsToNumber(options.fps);
     const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
+    session.captureStep = "capturing the frame";
     const { encodeResults, failedAt, error } = await produceDrawElementFrameBatch(page, quantized, options.width, options.height, options.quality ?? 80);
     // A later batch failure abandons this prefix. Its asynchronous encodes can
     // still reject while session cleanup shuts the worker down.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.146",
+  "version": "0.8.147",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -46,8 +46,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.146",
-    "@hyperframes/parsers": "^0.8.146"
+    "@hyperframes/core": "^0.8.147",
+    "@hyperframes/parsers": "^0.8.147"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",