@hyperframes/engine 0.9.13 → 0.9.14

package/dist/services/drawElementService.d.ts

@@ -207,4 +207,6 @@ export declare function produceDrawElementFrameBatch(page: Page, times: number[]
     encodeResults: Array<Promise<Buffer>>;
     failedAt: number | null;
     error?: string;
+    /** Background urls whose decode timed out during this batch. */
+    lateBackgrounds: string[];
 }>;

package/dist/services/drawElementService.js

@@ -944,7 +944,9 @@ export async function produceDrawElementFrameBatch(page, times, width, height, q
                 if (aw.__hf && typeof aw.__hf.seek === "function")
                     aw.__hf.seek(t);
                 await aw.__hfWaitForSeekCompletion?.();
-                await aw.__hfDecodeDynamicCssBackgroundImages?.();
+                const late = await aw.__hfDecodeDynamicCssBackgroundImages?.();
+                if (late?.length)
+                    (aw.__hf_css_background_late ??= []).push(...late);
                 aw.__hf3d?.update();
                 const accel = (aw.__hf_accel_canvases ?? []).filter((c) => root.contains(c));
                 for (const c of accel) {
@@ -1074,5 +1076,9 @@ export async function produceDrawElementFrameBatch(page, times, width, height, q
             }
         }
     }
-    return { encodeResults, failedAt: outcome.failedAt, error: outcome.error };
+    const lateBackgrounds = await page.evaluate(() => {
+        const w = window;
+        return w.__hf_css_background_late?.splice(0) ?? [];
+    });
+    return { encodeResults, failedAt: outcome.failedAt, error: outcome.error, lateBackgrounds };
 }

package/dist/services/frameCapture.d.ts

@@ -274,8 +274,13 @@ export declare function isDrawElementVerificationError(err: unknown): boolean;
  * undefined when the error isn't a verification failure at all.
  */
 export declare function getDrawElementVerificationDetails(err: unknown): DrawElementVerificationDetails | undefined;
-/** Wait for inline CSS background images introduced by the latest seek. */
-export declare function decodeDynamicCssBackgroundImages(page: Page): Promise<void>;
+/** Longest the capture waits for one inline background image to decode; it is then left out. */
+export declare const BACKGROUND_DECODE_TIMEOUT_MS = 15000;
+/**
+ * Wait for inline CSS background images introduced by the latest seek.
+ * Resolves with the urls that did not settle in time: they are captured as they stand and not waited on again.
+ */
+export declare function decodeDynamicCssBackgroundImages(page: Page): Promise<string[]>;
 export declare function sanitizeDiagnosticUrl(input: string): string;
 export declare function formatNavigationFailureDiagnostic(input: {
     captureMode: CaptureMode;
@@ -450,6 +455,8 @@ export declare function pollImagesReady(page: Page, timeoutMs: number, intervalM
 export declare function waitForImagesReady(page: Page, timeoutMs: number, onUnloaded: (sources: string) => void): Promise<boolean>;
 /** @internal exported for contract testing. */
 export declare function collectMediaReadinessWarnings(page: Page, skipIds: readonly string[], timeoutMs: number): Promise<CaptureWarning[]>;
+/** Report background urls that timed out decoding; the shown url drops credentials and query. */
+export declare function recordBackgroundDecodeTimeouts(session: CaptureSession, urls: readonly string[] | undefined): void;
 export declare function recordSubTimelineWarning(session: CaptureSession, timeoutMs: number): void;
 /**
  * Build the `live_map_detected` warning for the detected map libraries.

package/dist/services/frameCapture.js

@@ -89,12 +89,19 @@ export function getDrawElementVerificationDetails(err) {
     }
     return undefined;
 }
-/** Wait for inline CSS background images introduced by the latest seek. */
+/** Longest the capture waits for one inline background image to decode; it is then left out. */
+export const BACKGROUND_DECODE_TIMEOUT_MS = 15_000;
+/**
+ * Wait for inline CSS background images introduced by the latest seek.
+ * Resolves with the urls that did not settle in time: they are captured as they stand and not waited on again.
+ */
 export async function decodeDynamicCssBackgroundImages(page) {
-    await page.evaluate(async () => {
+    return page.evaluate(async (timeoutMs) => {
         const root = globalThis;
         const decode = (root.__hfDecodeDynamicCssBackgroundImages ??= async () => {
+            const limitMs = root.__hf_css_background_timeout_ms ?? 0;
             const decoded = (root.__hf_css_background_decoded ??= new Set());
+            const timedOut = (root.__hf_css_background_timed_out ??= new Set());
             const urls = [];
             const parseBackgroundUrls = (value) => {
                 const found = [];
@@ -146,24 +153,42 @@ export async function decodeDynamicCssBackgroundImages(page) {
                 if (!backgroundImage || backgroundImage === "none")
                     continue;
                 for (const url of parseBackgroundUrls(backgroundImage)) {
-                    if (!decoded.has(url))
+                    if (!decoded.has(url) && !timedOut.has(url))
                         urls.push(url);
                 }
             }
+            const late = [];
             await Promise.all([...new Set(urls)].map(async (url) => {
                 const image = new Image();
                 image.src = url;
+                let timer;
+                const expired = new Promise((resolve) => {
+                    timer = setTimeout(() => resolve("late"), limitMs);
+                });
                 try {
-                    await image.decode();
-                    decoded.add(url);
+                    const outcome = await Promise.race([
+                        image.decode().then(() => "ready"),
+                        expired,
+                    ]);
+                    if (outcome === "ready")
+                        decoded.add(url);
+                    else {
+                        timedOut.add(url);
+                        late.push(url);
+                    }
                 }
                 catch {
                     // Keep existing capture behavior for missing assets; request diagnostics report them.
                 }
+                finally {
+                    clearTimeout(timer);
+                }
             }));
+            return late;
         });
-        await decode();
-    });
+        root.__hf_css_background_timeout_ms = timeoutMs;
+        return decode();
+    }, BACKGROUND_DECODE_TIMEOUT_MS);
 }
 // Circular buffer for browser console messages dumped on render failure diagnostics.
 // Complex compositions produce 100+ messages; 50 was too small to capture relevant errors.
@@ -251,15 +276,6 @@ export function sanitizeDiagnosticUrl(input) {
         return "data:<redacted>";
     if (input.startsWith("blob:"))
         return "blob:<redacted>";
-    if (input.startsWith("/")) {
-        try {
-            const url = new URL(input, "http://hyperframes.local");
-            return url.pathname;
-        }
-        catch {
-            return input;
-        }
-    }
     try {
         const url = new URL(input);
         url.username = "";
@@ -269,7 +285,13 @@ export function sanitizeDiagnosticUrl(input) {
         return url.toString();
     }
     catch {
-        return input;
+        // A relative reference keeps its path only, and raw input never comes back.
+        try {
+            return new URL(input, "http://hyperframes.local").pathname;
+        }
+        catch {
+            return input.split(/[?#]/, 1)[0] ?? "";
+        }
     }
 }
 export function formatNavigationFailureDiagnostic(input) {
@@ -779,7 +801,7 @@ async function finalizeDrawElementInit(session, page, logInitPhase, opts) {
     const { transparent, forceDE } = opts;
     // Install the page-local decoder before batch drawElement capture begins;
     // the batch loop re-runs it after every in-page seek.
-    await decodeDynamicCssBackgroundImages(page);
+    recordBackgroundDecodeTimeouts(session, await decodeDynamicCssBackgroundImages(page));
     // Self-verification ground truth: must run pre-injection — after the canvas
     // wraps the root, a page screenshot shows the canvas's last-drawn bitmap,
     // not the live DOM (see the Lim 6 boundary-screenshot note).
@@ -1679,6 +1701,23 @@ function recordCaptureWarnings(session, warnings) {
         console.warn(`[FrameCapture:${warning.code}] ${warning.message}`, warning.details ?? {});
     }
 }
+/** Report background urls that timed out decoding; the shown url drops credentials and query. */
+export function recordBackgroundDecodeTimeouts(session, urls) {
+    // Mocked pages answer evaluate() with undefined, so tolerate a missing list.
+    if (!urls?.length)
+        return;
+    const sources = [...new Set(urls.map(sanitizeDiagnosticUrl))].sort();
+    for (const source of sources) {
+        appendBrowserDiagnostic(session, `[FrameCapture] background image still decoding after ${BACKGROUND_DECODE_TIMEOUT_MS}ms, captured without it: ${source}`);
+    }
+    recordCaptureWarnings(session, [
+        {
+            code: "media_readiness_timeout",
+            message: `image media did not finish decoding within ${BACKGROUND_DECODE_TIMEOUT_MS}ms`,
+            details: { mediaType: "image", sources, timeoutMs: BACKGROUND_DECODE_TIMEOUT_MS },
+        },
+    ]);
+}
 export function recordSubTimelineWarning(session, timeoutMs) {
     const outcome = session.subTimelineWaitOutcome;
     if (outcome === "ready" || !outcome)
@@ -2373,7 +2412,8 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     session.captureStep = "seeking the timeline";
     const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
     session.captureStep = "decoding CSS background images";
-    await decodeDynamicCssBackgroundImages(page);
+    // Mocked pages answer evaluate() with undefined, so tolerate a missing list.
+    recordBackgroundDecodeTimeouts(session, await decodeDynamicCssBackgroundImages(page));
     const seekMs = Date.now() - seekStart;
     // Before-capture hook (e.g. video frame injection) — runs before
     // page-side compositor clones so cloneNode picks up injected <img>
@@ -3796,7 +3836,8 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
     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);
+    const { encodeResults, failedAt, error, lateBackgrounds } = await produceDrawElementFrameBatch(page, quantized, options.width, options.height, options.quality ?? 80);
+    recordBackgroundDecodeTimeouts(session, lateBackgrounds);
     // A later batch failure abandons this prefix. Its asynchronous encodes can
     // still reject while session cleanup shuts the worker down.
     for (const result of encodeResults)

package/dist/services/riskFrames.js

@@ -44,6 +44,19 @@ async function scanChunk(page, times) {
         return out;
     }, times);
 }
+/** The chunk's frames, or null once `ms` pass first: a wedged page answers only at the protocol timeout. */
+function withinBudget(work, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(null), Math.max(0, ms));
+        work.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 /**
  * Frames where a recorded effect element shows. Seeks the page forward, so use a throwaway one.
  * Null once more than `maxFrames` frames qualify, or once the whole scan would take over `budgetMs`.
@@ -56,7 +69,13 @@ export async function scanCssEffectLiveFrames(page, fps, totalFrames, maxFrames,
         const times = [];
         for (let f = from; f < to; f++)
             times.push(quantizeTimeToFrame(f / fps, fps));
-        for (const i of await scanChunk(page, times))
+        const shown = await withinBudget(scanChunk(page, times), budgetMs - (now() - started));
+        if (!shown) {
+            console.error(`[engine] fast capture: the effect scan got no answer from the page within its ` +
+                `${budgetMs / 1000} s budget (frames ${from}-${to - 1})`);
+            return null;
+        }
+        for (const i of shown)
             live.add(from + i);
         onProgress?.(to, totalFrames);
         const projectedMs = ((now() - started) / to) * totalFrames;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.9.13",
+  "version": "0.9.14",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -61,8 +61,8 @@
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
     "undici": "7.25.0",
-    "@hyperframes/parsers": "^0.9.13",
-    "@hyperframes/core": "^0.9.13"
+    "@hyperframes/parsers": "^0.9.14",
+    "@hyperframes/core": "^0.9.14"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",