@hyperframes/engine 0.7.42 → 0.7.44

package/dist/services/frameCapture.js

@@ -270,6 +270,32 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
                 await armStaticDedup(session, page, logInitPhase);
             }
         }
+        // Capability gate: `canvas.drawElementImage` is an unlaunched Blink feature
+        // that only exists on recent Dev/Canary Chrome builds (~151+); it is absent
+        // from Stable and from most pinned/system Chrome installs. The
+        // `--enable-features=CanvasDrawElement` flag no-ops silently on a build that
+        // doesn't implement it, so without this probe the first drawElementImage()
+        // call throws `TypeError: ... is not a function` deep inside the capture
+        // loop and takes the whole render down instead of falling back (HF#2060).
+        // Cheap (no paint-wait) and must run before any other drawElement work.
+        // Not gated by forceDE (HF_FORCE_DRAWELEMENT, an R&D knob that bypasses the
+        // quality gates below to measure raw damage) — there's no "forced but
+        // degraded" mode for a method that doesn't exist, only a crash, so this
+        // always routes to the fallback instead.
+        const supportsDrawElement = await page.evaluate(() => {
+            const c = document.createElement("canvas");
+            const ctx = c.getContext("2d");
+            return (typeof ctx?.drawElementImage === "function");
+        });
+        if (!supportsDrawElement) {
+            session.deGateReason = "unsupported_chrome";
+            console.log(`[engine] fast capture: falling back to ${session.launchCaptureMode} capture — ` +
+                "this Chrome build does not implement canvas.drawElementImage (Dev/Canary-only " +
+                "feature, ~151+); run `hyperframes browser ensure --force` to fetch a supported " +
+                "build, or set HYPERFRAMES_BROWSER_PATH to one.");
+            await routeToFallback();
+            return;
+        }
         // SwiftShader gate: drawElement's only advantage is skipping the GPU→CPU
         // screenshot-readback IPC. On a software rasterizer (Docker/CI, no GPU) both
         // paths block on identical software raster, so drawElement is parity-or-slower
@@ -600,6 +626,7 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
         onBeforeCapture,
         isInitialized: false,
         browserConsoleBuffer: [],
+        scriptLoadFailures: [],
         capturePerf: {
             frames: 0,
             seekMs: 0,
@@ -663,16 +690,6 @@ export function formatConsoleDiagnostic(type, text, locationUrl) {
                 : "[Browser]";
     return { text: `${prefix} ${text}`, suppressHostLog: false };
 }
-async function pollPageExpression(page, expression, timeoutMs, intervalMs = 100) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        const ready = Boolean(await page.evaluate(expression));
-        if (ready)
-            return true;
-        await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    }
-    return Boolean(await page.evaluate(expression));
-}
 const HF_READY_DIAGNOSTIC_EXPR = `(function() {
   var hf = window.__hf;
   var player = window.__player;
@@ -773,7 +790,14 @@ async function pollHfReady(page, timeoutMs, intervalMs = 100) {
         `  State: __hf=${diag.hasHf}, seek=${diag.hasSeek}, player=${diag.hasPlayer}, ` +
         `renderReady=${diag.renderReady}, duration=${diag.duration}`);
 }
-async function pollSubCompositionTimelines(page, timeoutMs, intervalMs = 150) {
+export async function pollSubCompositionTimelines(page, timeoutMs, intervalMs = 150, 
+// Fail-fast hook: when a SCRIPT resource failed to load (404 / request
+// failure), the timeline registration it carried can never arrive — the
+// full-timeout wait buys nothing (measured: a 705-render spike at the 45s
+// setup bucket in 30 days of wild local renders, ~1% of renders, each also
+// shipping silently-broken animations). Once failures are present the poll
+// is cut to `scriptFailureGraceMs` from its start.
+getScriptLoadFailures, scriptFailureGraceMs = 2_000) {
     // Hosts may opt out of the timeline wait with `data-no-timeline` —
     // compositions driven purely by CSS animations / rAF (the render-compat
     // contract) never register window.__timelines[id], and without the opt-out
@@ -790,7 +814,28 @@ async function pollSubCompositionTimelines(page, timeoutMs, intervalMs = 150) {
     }
     return true;
   })()`;
-    const ready = await pollPageExpression(page, expression, timeoutMs, intervalMs);
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    let ready = false;
+    let scriptFailureBail = false;
+    for (;;) {
+        ready = Boolean(await page.evaluate(expression));
+        if (ready)
+            break;
+        const now = Date.now();
+        if (now >= deadline)
+            break;
+        const failures = getScriptLoadFailures?.() ?? [];
+        if (failures.length > 0 && now - start >= scriptFailureGraceMs) {
+            scriptFailureBail = true;
+            console.warn(`[FrameCapture] Sub-composition timeline wait cut short after ${now - start}ms: ` +
+                `script resource(s) failed to load (${failures.join(", ")}) — ` +
+                `the timeline registration they carry can never arrive. ` +
+                `Fix the script reference; the render proceeds without those animations.`);
+            break;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
     // Always force a timeline rebind once sub-composition timelines are
     // confirmed present. The previous implementation only called rebind
     // when the timeline count grew during the poll, which missed the case
@@ -804,23 +849,32 @@ async function pollSubCompositionTimelines(page, timeoutMs, intervalMs = 150) {
         window.__hfForceTimelineRebind();
       }
     })()`);
+        return "ready";
     }
-    if (!ready) {
-        const missing = await page.evaluate(`(function() {
-      var hosts = document.querySelectorAll("[data-composition-id]");
-      var timelines = window.__timelines || {};
-      var m = [];
-      for (var i = 0; i < hosts.length; i++) {
-        if (hosts[i].hasAttribute("data-no-timeline")) continue;
-        var id = hosts[i].getAttribute("data-composition-id");
-        if (id && !timelines[id]) m.push(id);
-      }
-      return m.join(", ");
-    })()`);
+    // Enumerate the still-unregistered composition ids regardless of bail
+    // reason — a script-failure bail used to skip this entirely, so a render
+    // with multiple sub-compositions only named the failed script URL(s), not
+    // which composition(s) it was still waiting on (review).
+    const missing = await page.evaluate(`(function() {
+    var hosts = document.querySelectorAll("[data-composition-id]");
+    var timelines = window.__timelines || {};
+    var m = [];
+    for (var i = 0; i < hosts.length; i++) {
+      if (hosts[i].hasAttribute("data-no-timeline")) continue;
+      var id = hosts[i].getAttribute("data-composition-id");
+      if (id && !timelines[id]) m.push(id);
+    }
+    return m.join(", ");
+  })()`);
+    if (scriptFailureBail) {
+        console.warn(`[FrameCapture] Composition(s) still waiting on the failed script: ${missing}.`);
+    }
+    else {
         console.warn(`[FrameCapture] Sub-composition timelines not registered after ${timeoutMs}ms: ${missing}. ` +
             `Compositions that load data asynchronously (e.g. fetch) must register window.__timelines[id] after setup completes. ` +
             `Compositions intentionally driven without GSAP timelines (CSS animations / rAF) can mark the host with data-no-timeline to skip this wait.`);
     }
+    return scriptFailureBail ? "script_failure" : "timeout";
 }
 async function pollVideosReady(page, skipIds, timeoutMs, intervalMs = 100) {
     const check = async () => {
@@ -965,6 +1019,15 @@ async function waitForOptionalTailwindReady(page, timeoutMs) {
         throw new Error(`[FrameCapture] window.__tailwindReady not resolved after ${timeoutMs}ms. Tailwind browser runtime must finish before frame capture starts.`);
     }
 }
+// A 4xx `response` and a `requestfailed` can both fire for the same script
+// (e.g. a `requestfailed` following the 4xx), and repeated <script> tags for
+// the same URL duplicate it further — dedupe so the fail-fast warning names
+// each failed URL once.
+function recordScriptLoadFailure(session, url) {
+    if (!session.scriptLoadFailures.includes(url)) {
+        session.scriptLoadFailures.push(url);
+    }
+}
 // fallow-ignore-next-line unit-size
 export async function initializeSession(session) {
     const { page, serverUrl } = session;
@@ -990,6 +1053,9 @@ export async function initializeSession(session) {
         appendBrowserDiagnostic(session, text);
     });
     page.on("requestfailed", (request) => {
+        if (request.resourceType() === "script") {
+            recordScriptLoadFailure(session, request.url());
+        }
         appendBrowserDiagnostic(session, formatRequestFailureDiagnostic({
             method: request.method(),
             resourceType: request.resourceType(),
@@ -1002,6 +1068,9 @@ export async function initializeSession(session) {
         if (status < 400)
             return;
         const request = response.request();
+        if (request.resourceType() === "script") {
+            recordScriptLoadFailure(session, response.url());
+        }
         appendBrowserDiagnostic(session, formatHttpErrorDiagnostic({
             method: request.method(),
             resourceType: request.resourceType(),
@@ -1051,8 +1120,8 @@ export async function initializeSession(session) {
         const pageReadyTimeout = session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
         await pollHfReady(page, pageReadyTimeout);
         logInitPhase("pollHfReady complete");
-        await pollSubCompositionTimelines(page, pageReadyTimeout);
-        logInitPhase("pollSubCompositionTimelines complete");
+        session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, pageReadyTimeout, undefined, () => session.scriptLoadFailures);
+        logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
         await applyVideoMetadataHints(page, session.options.videoMetadataHints);
         logInitPhase("applyVideoMetadataHints complete");
         // Run independent readiness checks in parallel — videos, images, fonts,
@@ -1169,8 +1238,8 @@ export async function initializeSession(session) {
         warmupState.running = false;
         throw err;
     }
-    await pollSubCompositionTimelines(page, pageReadyTimeout);
-    logInitPhase("pollSubCompositionTimelines complete");
+    session.subTimelineWaitOutcome = await pollSubCompositionTimelines(page, pageReadyTimeout, undefined, () => session.scriptLoadFailures);
+    logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
     await applyVideoMetadataHints(page, session.options.videoMetadataHints);
     logInitPhase("applyVideoMetadataHints complete");
     // Run independent readiness checks in parallel — videos, images, fonts,
@@ -1561,13 +1630,16 @@ export async function verifyStaticFramesSafe(session, page, staticFrames, fps, s
         else
             runs.push({ a: f, b: f });
     }
-    const seekCapture = async (frameIdx) => {
+    const seekToFrame = async (frameIdx) => {
         const t = quantizeTimeToFrame(frameIdx / fps, fps);
         await page.evaluate((tt) => {
             const hf = window.__hf;
             if (hf && typeof hf.seek === "function")
-                hf.seek(tt);
+                hf.seek(tt, { suppressEvents: true });
         }, t);
+    };
+    const seekCapture = async (frameIdx) => {
+        await seekToFrame(frameIdx);
         return pageScreenshotCapture(page, session.options);
     };
     // Verify EVERY run in order (no longest-first truncation that would leave runs armed
@@ -1584,26 +1656,31 @@ export async function verifyStaticFramesSafe(session, page, staticFrames, fps, s
     // thorough checking. `frames.length` approximates total interior checks; a 3x
     // margin absorbs per-run anchor overhead and the 3-point floor on short runs.
     const hardCap = Math.max(sampleCount * 8, 400, Math.ceil(frames.length / STATIC_VERIFY_REFERENCE_STRIDE) * 3 + runs.length);
-    let spent = 0;
-    for (const { a, b } of runs) {
-        const anchor = a - 1;
-        if (anchor < 0)
-            continue;
-        const anchorBuf = await seekCapture(anchor);
-        spent++;
-        for (const f of computeStaticVerificationPoints(a, b, sampleCount)) {
-            const cur = await seekCapture(f);
+    try {
+        let spent = 0;
+        for (const { a, b } of runs) {
+            const anchor = a - 1;
+            if (anchor < 0)
+                continue;
+            const anchorBuf = await seekCapture(anchor);
             spent++;
-            if (!anchorBuf.equals(cur))
-                return { badFrame: f, budgetExhausted: false };
+            for (const f of computeStaticVerificationPoints(a, b, sampleCount)) {
+                const cur = await seekCapture(f);
+                spent++;
+                if (!anchorBuf.equals(cur))
+                    return { badFrame: f, budgetExhausted: false };
+            }
+            // Budget exhausted → can't fully verify → disarm, distinct from real drift so a
+            // `verification_budget` spike in telemetry reads as "this composition has a lot
+            // of static material to verify," not "compositions are non-static."
+            if (spent > hardCap)
+                return { badFrame: a, budgetExhausted: true };
         }
-        // Budget exhausted → can't fully verify → disarm, distinct from real drift so a
-        // `verification_budget` spike in telemetry reads as "this composition has a lot
-        // of static material to verify," not "compositions are non-static."
-        if (spent > hardCap)
-            return { badFrame: a, budgetExhausted: true };
+        return null;
+    }
+    finally {
+        await seekToFrame(0).catch(() => { });
     }
-    return null;
 }
 /**
  * Arm static-frame dedup for this render (default-on; opt out with HF_STATIC_DEDUP=false).
@@ -1960,9 +2037,28 @@ export async function captureFrameToBufferPipelined(session, frameIndex, time) {
     // and skip the seek + drawElement + encode entirely. Same predicate as the serial
     // path; clip-cut frames are excluded from staticFrames so they always capture.
     if (session.staticFrames?.has(frameIndex) && session.lastEncodeResult) {
-        session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
-        session.capturePerf.frames += 1;
-        return { encodeResult: session.lastEncodeResult, captureTimeMs: Date.now() - startTime };
+        // Reuse is valid only when EVERY frame in (lastEncodeResultFrame, i] is
+        // predicted-static — then all of them (and the reused buffer) share the
+        // same pixels. Sequential capture reduces to has(i) (gap = {i}); the
+        // interleaved parallel stride makes the gap N frames wide.
+        const lastIdx = session.lastEncodeResultFrame ?? frameIndex - 1;
+        let gapStatic = true;
+        for (let j = lastIdx + 1; j <= frameIndex; j++) {
+            if (!session.staticFrames.has(j)) {
+                gapStatic = false;
+                break;
+            }
+        }
+        if (gapStatic) {
+            session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
+            session.capturePerf.frames += 1;
+            // Advance the watermark on reuse too, not just on real captures — the
+            // gap-check above starts from lastEncodeResultFrame, so leaving it
+            // pinned to the last REAL capture makes every consecutive reuse rescan
+            // an ever-widening window instead of just the one new frame (review).
+            session.lastEncodeResultFrame = frameIndex;
+            return { encodeResult: session.lastEncodeResult, captureTimeMs: Date.now() - startTime };
+        }
     }
     try {
         const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(session, frameIndex, time);
@@ -1989,8 +2085,10 @@ export async function captureFrameToBufferPipelined(session, frameIndex, time) {
                 session.capturePerf.frameMs.push(boundaryMs);
             }
             const boundaryResult = Promise.resolve(buffer);
-            if (session.staticFrames)
+            if (session.staticFrames) {
                 session.lastEncodeResult = boundaryResult;
+                session.lastEncodeResultFrame = frameIndex;
+            }
             return { encodeResult: boundaryResult, captureTimeMs: Date.now() - startTime };
         }
         // Worker-encode is gated to the macOS GPU path (beginFrameTimeTicks === 0,
@@ -2007,8 +2105,10 @@ export async function captureFrameToBufferPipelined(session, frameIndex, time) {
         session.capturePerf.totalMs += captureTimeMs;
         session.capturePerf.frameMs.push(captureTimeMs);
         // Task B: retain this encode result so a following static frame can reuse it.
-        if (session.staticFrames)
+        if (session.staticFrames) {
             session.lastEncodeResult = encodeResult;
+            session.lastEncodeResultFrame = frameIndex;
+        }
         return { encodeResult, captureTimeMs };
     }
     catch (captureError) {
@@ -2308,7 +2408,7 @@ async function captureDeVerificationFrames(session, page, logInitPhase) {
         await page.evaluate((tt) => {
             const hf = window.__hf;
             if (hf && typeof hf.seek === "function")
-                hf.seek(tt);
+                hf.seek(tt, { suppressEvents: true });
         }, t);
     };
     await seekTo(quantizeTimeToFrame(0, fps));
@@ -2364,6 +2464,7 @@ export function getCapturePerfSummary(session) {
         avgBeforeCaptureMs: Math.round(session.capturePerf.beforeCaptureMs / frames),
         avgScreenshotMs: Math.round(session.capturePerf.screenshotMs / frames),
         p50TotalMs: medianOf(session.capturePerf.frameMs),
+        subTimelineWaitOutcome: session.subTimelineWaitOutcome,
         staticDedupReused: session.staticDedupCount ?? 0,
         staticDedupEnabled: session.staticDedupEnabled ?? false,
         // armed ⟺ a non-empty static set survived verification; predicted === its size.