@hyperframes/engine 0.7.56 → 0.7.58

package/dist/services/frameCapture.d.ts

@@ -9,7 +9,7 @@
 import { type Browser, type Page } from "puppeteer-core";
 import { type CaptureMode } from "./browserManager.js";
 import { type EngineConfig } from "../config.js";
-import type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary, SubTimelineWaitOutcome } from "../types.js";
+import type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, SubTimelineWaitOutcome } from "../types.js";
 export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
 /** Called after seeking, before screenshot. Use for video frame injection or other pre-capture work. */
 export type BeforeCaptureHook = (page: Page, time: number) => Promise<void>;
@@ -53,6 +53,8 @@ export interface CaptureSession {
     scriptLoadFailures: string[];
     /** Outcome of the sub-composition timeline wait: ready | timeout | script_failure. */
     subTimelineWaitOutcome?: SubTimelineWaitOutcome;
+    /** Structured readiness warnings surfaced to the producer's render policy. */
+    warnings: CaptureWarning[];
     initTelemetry?: {
         initDurationMs: number;
         tweenCount: number;
@@ -245,6 +247,8 @@ export declare function formatConsoleDiagnostic(type: string, text: string, loca
 export declare function pollSubCompositionTimelines(page: Page, timeoutMs: number, intervalMs?: number, getScriptLoadFailures?: () => readonly string[], scriptFailureGraceMs?: number): Promise<SubTimelineWaitOutcome>;
 /** @internal exported for unit testing only */
 export declare function pollImagesReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<boolean>;
+/** @internal exported for contract testing. */
+export declare function collectMediaReadinessWarnings(page: Page, skipIds: readonly string[], timeoutMs: number): Promise<CaptureWarning[]>;
 export declare function initializeSession(session: CaptureSession): Promise<void>;
 /**
  * Predict the dedupable (static) frame set from window.__timelines. A frame f (f>0) is

package/dist/services/frameCapture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frameCapture.d.ts","sourceRoot":"","sources":["../../src/services/frameCapture.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"frameCapture.d.ts","sourceRoot":"","sources":["../../src/services/frameCapture.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,IAAI,EAAsC,MAAM,gBAAgB,CAAC;AAM7F,OAAO,EAOL,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAqB7B,OAAO,EAAmD,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAClG,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;AAEvF,wGAAwG;AACxG,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAM1B,4FAA4F;IAC5F,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAI/B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;;;OAMG;IACH,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,sFAAsF;IACtF,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD,8EAA8E;IAC9E,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE;QACd,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB;wDACgD;QAChD,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,WAAW,EAAE,WAAW,CAAC;IACzB;;;;;OAKG;IACH,iBAAiB,EAAE,WAAW,CAAC;IAE/B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wBAAwB,EAAE,MAAM,CAAC;IACjC,uBAAuB,EAAE,MAAM,CAAC;IAChC,qFAAqF;IACrF,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/B,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC;;oFAEgF;IAChF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;mEAE+D;IAC/D,gBAAgB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC;;;6EAGyE;IACzE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;0BAMsB;IACtB,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,OAAO,EAAE,MAAM;CAQ5B;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAQpE;AAyDD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAuB3D;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACvD,WAAW,EAAE,WAAW,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,MAAM,CAOT;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,WAAW,EAAE,WAAW,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAMT;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAKT;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAMT;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,sEAAsE;IACtE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EACtB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,cAAc,CAMhB;AAsTD;;;;GAIG;AACH,wBAAsB,+BAA+B,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5F;AAGD,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,eAAe,GAAE,iBAAiB,GAAG,IAAW,EAChD,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,OAAO,CAAC,cAAc,CAAC,CAqNzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAM5F;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CAwB5C;AAyID,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAAY,EAOxB,qBAAqB,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,EAC/C,oBAAoB,GAAE,MAAc,GACnC,OAAO,CAAC,sBAAsB,CAAC,CA+EjC;AA4CD,+CAA+C;AAC/C,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAAY,GACvB,OAAO,CAAC,OAAO,CAAC,CA8BlB;AASD,+CAA+C;AAC/C,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,EAAE,CAAC,CAwD3B;AAyID,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA+X9E;AAoJD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IACT,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CA+JD;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,+BAA+B,CAC7C,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,CASV;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CAiEhE;AAoXD,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,mBAAmB,CAAC,CAI9B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CA+HnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,MAAM,EAAE,EACtB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC,CAyDvE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,KACT,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,UAAU,GAAE,MAAU,EACtB,IAAI,GAAE,MAAU,EAChB,YAAY,GAAE,yBAA4C,GACzD,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDhF;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,iBAAiB,GAAG,IAAI,GACxC,IAAI,CAsBN;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAMrF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlE;AAwGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,kBAAkB,CAmCjF;AA4BD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG/D;AA2DD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/D"}

package/dist/services/frameCapture.js

@@ -15,7 +15,7 @@ import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, r
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { detectSwiftShader, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, } from "./drawElementService.js";
 import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
-import { DEFAULT_CONFIG } from "../config.js";
+import { DEFAULT_CONFIG, applyConcreteGpuScreenshotClamp } from "../config.js";
 /**
  * drawElement self-verification failure — a captured DE frame diverged from its
  * pre-injection screenshot ground truth (or a blank frame survived a retry).
@@ -508,14 +508,28 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     // need explicit clip+scale on `Page.captureScreenshot`, so fall back to
     // the screenshot path for any DPR > 1.
     const supersampling = (options.deviceScaleFactor ?? 1) > 1;
-    const preMode = headlessShell && isLinux && !forceScreenshot && !supersampling && !drawElementTransparent
-        ? "beginframe"
-        : "screenshot";
     const requestedGpuMode = config?.browserGpuMode ?? DEFAULT_CONFIG.browserGpuMode;
     const resolvedGpuMode = await resolveBrowserGpuMode(requestedGpuMode, {
         chromePath: headlessShell ?? undefined,
         browserTimeout: config?.browserTimeout,
     });
+    // Apply the software-GPU→screenshot invariant at the concrete-resolved
+    // point too — `resolveConfig` can only see the pre-resolve `browserGpuMode`
+    // string, so `"auto"` that probes to software would otherwise slip through
+    // and launch BeginFrame + SwiftShader (the exact combination the invariant
+    // is meant to prevent). Both env and programmatic opt-outs preserved via
+    // `applyConcreteGpuScreenshotClamp` (the programmatic one carried on the
+    // config as `forceScreenshotExplicitlyOptedOut`, since at this point the
+    // boolean `forceScreenshot === false` is otherwise ambiguous between
+    // default and explicit opt-out).
+    const effectiveForceScreenshot = applyConcreteGpuScreenshotClamp(forceScreenshot, resolvedGpuMode, config);
+    const preMode = headlessShell &&
+        isLinux &&
+        !effectiveForceScreenshot &&
+        !supersampling &&
+        !drawElementTransparent
+        ? "beginframe"
+        : "screenshot";
     const chromeArgs = buildChromeArgs({ width: options.width, height: options.height, captureMode: preMode }, { ...config, browserGpuMode: resolvedGpuMode });
     const { browser, captureMode } = await acquireBrowser(chromeArgs, config);
     const page = await browser.newPage();
@@ -627,6 +641,7 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
         isInitialized: false,
         browserConsoleBuffer: [],
         scriptLoadFailures: [],
+        warnings: [],
         capturePerf: {
             frames: 0,
             seekMs: 0,
@@ -944,6 +959,87 @@ export async function pollImagesReady(page, timeoutMs, intervalMs = 100) {
     }
     return check();
 }
+/** @internal exported for contract testing. */
+export async function collectMediaReadinessWarnings(page, skipIds, timeoutMs) {
+    const snapshot = await page.evaluate((skipIdList) => {
+        const skipped = new Set(skipIdList);
+        const result = {
+            pendingImages: [],
+            failedImages: [],
+            pendingVideos: [],
+            failedVideos: [],
+        };
+        for (const img of document.querySelectorAll("img")) {
+            const src = img.getAttribute("src") || "";
+            if (!src || src.startsWith("data:"))
+                continue;
+            if (!img.complete)
+                result.pendingImages.push(img.src || src);
+            else if (img.naturalWidth <= 0)
+                result.failedImages.push(img.src || src);
+        }
+        // Browser media readiness is a frame-capture requirement only for video.
+        // Audio is extracted and mixed out of band by the producer, so an idle
+        // DOM <audio> element can legitimately remain at HAVE_NOTHING here. The
+        // producer reports actual extraction/mix failures as audio_processing_failed.
+        for (const media of document.querySelectorAll("video")) {
+            const mediaElement = media;
+            if (skipped.has(mediaElement.id))
+                continue;
+            const src = mediaElement.currentSrc || mediaElement.getAttribute("src") || "(no src)";
+            const failed = Boolean(mediaElement.error) ||
+                mediaElement.networkState === HTMLMediaElement.NETWORK_NO_SOURCE;
+            const pending = !failed && mediaElement.readyState < HTMLMediaElement.HAVE_CURRENT_DATA;
+            if (failed)
+                result.failedVideos.push(src);
+            else if (pending)
+                result.pendingVideos.push(src);
+        }
+        return result;
+    }, skipIds);
+    const warnings = [];
+    const append = (code, mediaType, sources) => {
+        if (sources.length === 0)
+            return;
+        const timedOut = code === "media_readiness_timeout";
+        warnings.push({
+            code,
+            message: timedOut
+                ? `${mediaType} media did not become capture-ready within ${timeoutMs}ms`
+                : `${mediaType} media failed to load before capture`,
+            details: { mediaType, sources: [...new Set(sources)].sort(), timeoutMs },
+        });
+    };
+    append("media_readiness_timeout", "image", snapshot.pendingImages);
+    append("media_load_failed", "image", snapshot.failedImages);
+    append("media_readiness_timeout", "video", snapshot.pendingVideos);
+    append("media_load_failed", "video", snapshot.failedVideos);
+    return warnings;
+}
+function recordCaptureWarnings(session, warnings) {
+    for (const warning of warnings) {
+        const key = `${warning.code}:${JSON.stringify(warning.details ?? {})}`;
+        if (session.warnings.some((existing) => `${existing.code}:${JSON.stringify(existing.details ?? {})}` === key)) {
+            continue;
+        }
+        session.warnings.push(warning);
+        console.warn(`[FrameCapture:${warning.code}] ${warning.message}`, warning.details ?? {});
+    }
+}
+function recordSubTimelineWarning(session, timeoutMs) {
+    if (session.subTimelineWaitOutcome === "ready" || !session.subTimelineWaitOutcome)
+        return;
+    const scriptFailure = session.subTimelineWaitOutcome === "script_failure";
+    recordCaptureWarnings(session, [
+        {
+            code: scriptFailure ? "sub_timeline_script_failure" : "sub_timeline_readiness_timeout",
+            message: scriptFailure
+                ? "A sub-composition timeline script failed to load"
+                : `Sub-composition timelines did not become ready within ${timeoutMs}ms`,
+            details: { timeoutMs },
+        },
+    ]);
+}
 // Force every successfully-loaded `<img>` to be GPU-uploaded before the first
 // frame capture. `naturalWidth > 0` means the bitmap has been decoded into
 // CPU memory, but compositor-side GPU upload can still happen lazily on first
@@ -1122,6 +1218,7 @@ export async function initializeSession(session) {
         logInitPhase("pollHfReady complete");
         session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, pageReadyTimeout, undefined, () => session.scriptLoadFailures);
         logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
+        recordSubTimelineWarning(session, pageReadyTimeout);
         await applyVideoMetadataHints(page, session.options.videoMetadataHints);
         logInitPhase("applyVideoMetadataHints complete");
         // Run independent readiness checks in parallel — videos, images, fonts,
@@ -1165,6 +1262,7 @@ export async function initializeSession(session) {
             console.warn(`[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
                 `Continuing render — affected videos will appear as blank/black frames.`);
         }
+        recordCaptureWarnings(session, await collectMediaReadinessWarnings(page, skipVideoIds, pageReadyTimeout));
         await recordSessionInitTelemetry(session, initStart);
         // drawElement or transparent-background init — runs after page is fully ready.
         await initDrawElementOrTransparentBackground(session, page, logInitPhase);
@@ -1240,6 +1338,7 @@ export async function initializeSession(session) {
     }
     session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, pageReadyTimeout, undefined, () => session.scriptLoadFailures);
     logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
+    recordSubTimelineWarning(session, pageReadyTimeout);
     await applyVideoMetadataHints(page, session.options.videoMetadataHints);
     logInitPhase("applyVideoMetadataHints complete");
     // Run independent readiness checks in parallel — videos, images, fonts,
@@ -1283,6 +1382,7 @@ export async function initializeSession(session) {
         console.warn(`[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
             `Continuing render — affected videos will appear as blank/black frames.`);
     }
+    recordCaptureWarnings(session, await collectMediaReadinessWarnings(page, bfSkipVideoIds, pageReadyTimeout));
     await recordSessionInitTelemetry(session, initStart);
     // Stop warmup, then drain the loop in BOTH modes before any further
     // BeginFrame on this session (drawElement init, the render-frame commit tick
@@ -2516,6 +2616,15 @@ export function getCapturePerfSummary(session) {
         avgScreenshotMs: Math.round(session.capturePerf.screenshotMs / frames),
         p50TotalMs: medianOf(session.capturePerf.frameMs),
         subTimelineWaitOutcome: session.subTimelineWaitOutcome,
+        warnings: session.warnings.map((warning) => ({
+            ...warning,
+            details: warning.details
+                ? {
+                    ...warning.details,
+                    sources: warning.details.sources ? [...warning.details.sources] : undefined,
+                }
+                : undefined,
+        })),
         staticDedupReused: session.staticDedupCount ?? 0,
         staticDedupEnabled: session.staticDedupEnabled ?? false,
         // armed ⟺ a non-empty static set survived verification; predicted === its size.