@hyperframes/engine 0.8.185 → 0.8.186

package/dist/index.d.ts

@@ -58,6 +58,7 @@ export { createFileServer, type FileServerOptions, type FileServerHandle, } from
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
 export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
+export type { PageMotionBlurOff } from "./types.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, probeMediaProfile, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";

package/dist/services/frameCapture.js

@@ -13,6 +13,7 @@ import { COMPOSITION_SOURCE_URL, quantizeSeekTime, quantizeTimeToFrame, fpsToNum
 import { DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
+import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, } from "./pageMotionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
@@ -946,6 +947,7 @@ async function constructCaptureSession(input) {
             }
         }, variablesJson);
     }
+    await installPageMotionBlur(page, options);
     const browserVersion = await browser.version();
     const sessionOptions = resolveCaptureSessionOptions(options, browserVersion);
     const expectedMajor = config?.expectedChromiumMajor;
@@ -2462,6 +2464,7 @@ export async function createStaticVerificationPage(session) {
                     JSON.parse(json);
             }, variablesJson);
         }
+        await installPageMotionBlur(page, session.options);
         await page.setViewport({
             width: session.options.width,
             height: session.options.height,
@@ -3192,6 +3195,11 @@ async function captureFrameCore(session, frameIndex, time) {
         session.capturePerf.screenshotMs += screenshotMs;
         session.capturePerf.totalMs += captureTimeMs;
         session.capturePerf.frameMs.push(captureTimeMs);
+        if (session.capturePerf.frames === 1) {
+            const blur = await describePageMotionBlur(session.page).catch(() => null);
+            if (blur)
+                console.log(blur);
+        }
         // Retain this freshly-captured buffer so the following static frames can reuse it.
         if (session.staticFrames) {
             session.lastFrameBuffer = buffer;
@@ -3527,6 +3535,11 @@ export async function closeCaptureSession(session) {
         // point up to `intervalMs` earlier. Best effort; the page may be gone.
         await session.chromeMemory.sampleOnce();
     }
+    if (session.page && !session.pageReleased) {
+        const blur = await describePageMotionBlurAtEnd(session.page);
+        if (blur)
+            console.log(blur);
+    }
     // Realized static-dedup telemetry: how much the cache actually helped this
     // render (vs the prediction logged at arm time). Both capture paths
     // (sequential orchestrator + parallel workers) close their session here, so

package/dist/services/pageMotionBlur.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tells the page's capture motion blur (`data-motion-blur="on"`) to stand down, before any of
+ * its scripts run: when the engine blurs (it would average frames that are already blurred) or
+ * when the render must match a Studio preview that could not blur (`pageMotionBlur: "off"`).
+ */
+import type { Page } from "puppeteer-core";
+import type { CaptureOptions } from "../types.js";
+export declare function installPageMotionBlur(page: Pick<Page, "evaluateOnNewDocument">, options: Pick<CaptureOptions, "motionBlur" | "pageMotionBlur" | "deviceScaleFactor">): Promise<void>;
+/** One line saying what the page's blur did for this session; null when the page never asked for blur. */
+export declare function describePageMotionBlur(page: Pick<Page, "evaluate">): Promise<string | null>;
+/** The session's closing line, only when frames fell back to plain DOM: the first-frame line cannot know. */
+export declare function describePageMotionBlurAtEnd(page: Pick<Page, "evaluate">, timeoutMs?: number): Promise<string | null>;

package/dist/services/pageMotionBlur.js

@@ -0,0 +1,66 @@
+/**
+ * Tells the page's capture motion blur (`data-motion-blur="on"`) to stand down, before any of
+ * its scripts run: when the engine blurs (it would average frames that are already blurred) or
+ * when the render must match a Studio preview that could not blur (`pageMotionBlur: "off"`).
+ */
+import { PAGE_DEVICE_SCALE_GLOBAL, PAGE_MOTION_BLUR_OFF_GLOBAL, acceleratedCanvasTrackerSource, } from "@hyperframes/core";
+function pageOffReason(options) {
+    if (options.motionBlur)
+        return "engine-motion-blur";
+    if (options.pageMotionBlur === "off")
+        return "preview-unsupported";
+    return options.pageMotionBlur ?? null;
+}
+export async function installPageMotionBlur(page, options) {
+    await page.evaluateOnNewDocument(acceleratedCanvasTrackerSource());
+    const scale = options.deviceScaleFactor ?? 1;
+    if (scale > 1) {
+        await page.evaluateOnNewDocument((key, v) => {
+            window[key] = v;
+        }, PAGE_DEVICE_SCALE_GLOBAL, scale);
+    }
+    const off = pageOffReason(options);
+    if (!off)
+        return;
+    await page.evaluateOnNewDocument((key, v) => {
+        window[key] = v;
+    }, PAGE_MOTION_BLUR_OFF_GLOBAL, off);
+}
+async function readPageMotionBlur(page) {
+    return page.evaluate(() => {
+        const api = Reflect.get(window, "__hfMotionBlur");
+        const report = api && typeof api === "object" ? Reflect.get(api, "report") : null;
+        const got = typeof report === "function" ? report() : null;
+        if (!got || typeof got !== "object")
+            return null;
+        return {
+            state: String(Reflect.get(got, "state")),
+            code: String(Reflect.get(got, "reasonCode")),
+            movers: Number(Reflect.get(got, "movers")),
+            failedFrames: Number(Reflect.get(got, "failedFrames")) || 0,
+        };
+    });
+}
+const formatPageMotionBlur = (r) => `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}`;
+/** One line saying what the page's blur did for this session; null when the page never asked for blur. */
+export async function describePageMotionBlur(page) {
+    const r = await readPageMotionBlur(page);
+    return r && formatPageMotionBlur(r);
+}
+/** The session's closing line, only when frames fell back to plain DOM: the first-frame line cannot know. */
+export async function describePageMotionBlurAtEnd(page, timeoutMs = 1500) {
+    let timer;
+    const stuck = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), timeoutMs);
+    });
+    try {
+        const r = await Promise.race([readPageMotionBlur(page), stuck]);
+        return r && r.failedFrames > 0 ? `${formatPageMotionBlur(r)} (session end)` : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/types.d.ts

@@ -8,6 +8,7 @@ import type { AudioFailureDiagnostic } from "./services/audioMixer.types.js";
 import type { Fps } from "@hyperframes/core";
 import type { ChromeMemoryStats } from "./services/chromeMemorySampler.js";
 import type { MotionBlurOptions } from "./services/motionBlur.js";
+export type PageMotionBlurOff = "off" | "hdr-render" | "layered-composite" | "distributed-render";
 /**
  * Outcome of waiting for a sub-composition's GSAP timelines to register.
  * Threaded string-typed through `CapturePerfSummary` / `RenderPerfSummary` /
@@ -151,6 +152,8 @@ export interface CaptureOptions {
      * screenshot capture mode; see `services/motionBlur.ts`.
      */
     motionBlur?: MotionBlurOptions;
+    /** Why the page's capture motion blur stands down: the preview could not blur, or the route cannot host it. */
+    pageMotionBlur?: PageMotionBlurOff;
     deviceScaleFactor?: number;
     /**
      * Opt into Chrome's capture-beyond-viewport screenshot path. Leave undefined

package/package.json

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