Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(core,engine): report why blur is off, and what each render session did (#5991)
Vance Ingalls38f6e01c2be3
diff --git a/packages/core/src/runtime/captureMotionBlur/index.test.ts b/packages/core/src/runtime/captureMotionBlur/index.test.tsindex 76454bce9b..66e8105d28 100644--- a/packages/core/src/runtime/captureMotionBlur/index.test.ts+++ b/packages/core/src/runtime/captureMotionBlur/index.test.ts@@ -19,6 +19,7 @@ type Win = Window & {moverNames: string[];failedFrames: number;};+ suspend: () => void;};__hf_page_composite_pending?: boolean;__hf_page_composite_resolve?: () => boolean;@@ -187,6 +188,7 @@ describe("opt-in and off switches", () => {expect(win.__hfMotionBlur?.report()).toMatchObject({state: "off",reason: "the renderer turned it off (distributed-render)",+ reasonCode: "renderer-off",});});@@ -233,8 +235,10 @@ describe("opt-in and off switches", () => {root.append(canvas);canvas.transferControlToOffscreen();initCaptureMotionBlur(host(root));- expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "off" });- expect(win.__hfMotionBlur?.report().reason).toMatch(/WebGL/);+ expect(win.__hfMotionBlur?.report()).toMatchObject({+ state: "off",+ reasonCode: "accelerated-canvas",+ });delete (HTMLCanvasElement.prototype as unknown as Record<string, unknown>).transferControlToOffscreen;});@@ -252,24 +256,26 @@ describe("opt-in and off switches", () => {expect(win.__hfMotionBlur?.report().reason).toMatch(/WebGL/);});- it("stays off for an iframe in the root, which reloads when the root is wrapped", () => {+ it("stays off for an iframe in the root, which reloads when the root is wrapped (R9)", () => {installHtmlInCanvas();const root = makeRoot();root.append(document.createElement("iframe"));initCaptureMotionBlur(host(root));expect(root.parentElement).toBe(document.body);- expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "off" });- expect(win.__hfMotionBlur?.report().reason).toMatch(/iframe/);+ expect(win.__hfMotionBlur?.report()).toMatchObject({+ state: "off",+ reasonCode: "iframe-in-root",+ });});- it("turns off instead of wrapping when an iframe appears after init", () => {+ it("turns off instead of wrapping when an iframe appears after init (R9)", () => {installHtmlInCanvas();const { root, h } = movingHost();initCaptureMotionBlur(h);root.append(document.createElement("iframe"));void paintCaptureMotionBlur(0.5, PLAY);expect(root.parentElement).toBe(document.body);- expect(win.__hfMotionBlur?.report().reason).toMatch(/iframe/);+ expect(win.__hfMotionBlur?.report().reasonCode).toBe("iframe-in-root");});it("stays off for a hidden-backface card in a 3D context, but not for a flat one", () => {@@ -611,46 +617,6 @@ describe("wrapping", () => {expect(h.seek).not.toHaveBeenCalled();});- it("hides each move of the root from the runtime and re-seeks right after it (R9)", async () => {- installHtmlInCanvas();- const { root, h } = movingHost();- const events: string[] = [];- const base = h.seek;- const spied = {- ...h,- now: () => 0.5,- seek: (t: number, suppress: boolean) => {- base(t, suppress);- events.push(`seek:${t}:${suppress}`);- },- ignoreMutations: (write: () => void) => {- events.push("quiet:begin");- write();- events.push(`quiet:end:${root.parentElement === document.body ? "plain" : "wrapped"}`);- },- };- initCaptureMotionBlur(spied);- events.length = 0;- void paintCaptureMotionBlur(0.5, PLAY);- expect(events.slice(events.indexOf("quiet:begin")).slice(0, 3)).toEqual([- "quiet:begin",- "quiet:end:wrapped",- "seek:0.5:true",- ]);- events.length = 0;- expect(paintCaptureMotionBlur(0.5)).toBeNull(); // paused: unwraps- expect(events).toEqual(["quiet:begin", "quiet:end:plain", "seek:0.5:true"]);- });-- it("does not re-seek when there was nothing to unwrap", () => {- installHtmlInCanvas();- const { h } = movingHost();- initCaptureMotionBlur(h);- h.seek.mockClear();- expect(paintCaptureMotionBlur(0.5)).toBeNull();- expect(h.seek).not.toHaveBeenCalled();- });-it("unwraps when paused, so Studio can select inside, and wraps again on play", async () => {installHtmlInCanvas();const { root, el, h } = movingHost();@@ -968,30 +934,6 @@ describe("painting", () => {expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "off" });});- it("counts every frame that fell back to plain DOM, though the failure streak resets", async () => {- vi.useFakeTimers();- installHtmlInCanvas();- const { root, h } = movingHost();- initCaptureMotionBlur(h);- const frame = async (t: number, fails: boolean): Promise<void> => {- captureContext()?.drawElementImage.mockImplementation(() => {- if (fails) throw new Error("No cached paint record");- });- const done = paintCaptureMotionBlur(t, { engineMode: true });- releaseCaptureMotionBlurFrame();- captureCanvas(root).dispatchEvent(new Event("paint"));- captureCanvas(root).dispatchEvent(new Event("paint"));- await done;- };- await frame(0.1, true);- await frame(0.2, false);- void paintCaptureMotionBlur(0.3, { engineMode: true });- releaseCaptureMotionBlurFrame();- await vi.advanceTimersByTimeAsync(2000);- expect(win.__hfMotionBlur?.report()).toMatchObject({ failures: 0, failedFrames: 2 });- expect(Object.keys(win.__hfMotionBlur?.report() ?? {})).toContain("failedFrames");- });-describe("a block that its cause can lift", () => {/** A host whose root fades from 0.5 s while `fade.on`: the scan blocks it as root opacity. */function fadingHost(fade: { on: boolean }, timeline: () => unknown = () => "tl") {@@ -1010,12 +952,14 @@ describe("painting", () => {const { root, host: h } = fadingHost(fade);initCaptureMotionBlur(h);void paintCaptureMotionBlur(0.2, { engineMode: true });- expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "off" });- expect(win.__hfMotionBlur?.report().reason).toMatch(/opacity/);+ expect(win.__hfMotionBlur?.report()).toMatchObject({+ state: "off",+ reasonCode: "root-opacity",+ });fade.on = false;initCaptureMotionBlur(h);void paintCaptureMotionBlur(0.2, { engineMode: true });- expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "on", reason: null });+ expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "on", reasonCode: null });expect(root.parentElement).toBe(captureCanvas(root));});@@ -1027,8 +971,10 @@ describe("painting", () => {initCaptureMotionBlur(h);void paintCaptureMotionBlur(0.2, { engineMode: true });expect(root.parentElement).toBe(document.body);- expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "off" });- expect(win.__hfMotionBlur?.report().reason).toMatch(/opacity/);+ expect(win.__hfMotionBlur?.report()).toMatchObject({+ state: "off",+ reasonCode: "root-opacity",+ });});it("re-evaluates the block when the bound timeline changes", () => {@@ -1056,7 +1002,7 @@ describe("painting", () => {root.append(late);late.getContext("webgl");void paintCaptureMotionBlur(0.5, { engineMode: true });- expect(win.__hfMotionBlur?.report().reason).toMatch(/WebGL/);+ expect(win.__hfMotionBlur?.report().reasonCode).toBe("accelerated-canvas");late.remove();initCaptureMotionBlur(h);void paintCaptureMotionBlur(0.5, PLAY);@@ -1082,11 +1028,35 @@ describe("painting", () => {expect(root.parentElement).toBe(document.body);expect(win.__hfMotionBlur?.report()).toMatchObject({state: "off",- reason: "capture failed 3 times in a row",+ reasonCode: "capture-failures",});});});+ it("counts every frame that fell back to plain DOM, though the failure streak resets", async () => {+ vi.useFakeTimers();+ installHtmlInCanvas();+ const { root, h } = movingHost();+ initCaptureMotionBlur(h);+ const frame = async (t: number, fails: boolean): Promise<void> => {+ captureContext()?.drawElementImage.mockImplementation(() => {+ if (fails) throw new Error("No cached paint record");+ });+ const done = paintCaptureMotionBlur(t, { engineMode: true });+ releaseCaptureMotionBlurFrame();+ captureCanvas(root).dispatchEvent(new Event("paint"));+ captureCanvas(root).dispatchEvent(new Event("paint"));+ await done;+ };+ await frame(0.1, true);+ await frame(0.2, false);+ void paintCaptureMotionBlur(0.3, { engineMode: true });+ releaseCaptureMotionBlurFrame();+ await vi.advanceTimersByTimeAsync(2000);+ expect(win.__hfMotionBlur?.report()).toMatchObject({ failures: 0, failedFrames: 2 });+ expect(Object.keys(win.__hfMotionBlur?.report() ?? {})).toContain("failedFrames");+ });+it("keeps blurring in a render after repeated capture failures, each failed frame plain DOM", async () => {installHtmlInCanvas();const { root, h } = movingHost();@@ -1126,6 +1096,62 @@ describe("painting", () => {});});+describe("suspend (R13)", () => {+ it("unwraps a wrapped root, stops all painting, and keeps the reported decision", () => {+ installHtmlInCanvas();+ const { root, h } = movingHost();+ initCaptureMotionBlur(h);+ void paintCaptureMotionBlur(0.5, PLAY);+ expect(root.parentElement?.tagName).toBe("CANVAS");+ const before = win.__hfMotionBlur?.report();+ win.__hfMotionBlur?.suspend();+ expect(root.parentElement).toBe(document.body);+ expect(document.querySelectorAll("canvas")).toHaveLength(0);+ expect(paintCaptureMotionBlur(0.6, PLAY)).toBeNull();+ expect(paintCaptureMotionBlur(0.7, { engineMode: true })).toBeNull();+ expect(root.parentElement).toBe(document.body);+ expect(win.__hfMotionBlur?.report()).toEqual(before);+ });++ it("is idempotent, and suspends a page that has not wrapped yet", () => {+ installHtmlInCanvas();+ const { root, h } = movingHost();+ initCaptureMotionBlur(h);+ win.__hfMotionBlur?.suspend();+ h.seek.mockClear();+ win.__hfMotionBlur?.suspend();+ expect(h.seek).not.toHaveBeenCalled();+ expect(paintCaptureMotionBlur(0.5, { engineMode: true })).toBeNull();+ expect(root.parentElement).toBe(document.body);+ expect(win.__hfMotionBlur?.report().state).toBe("on");+ });++ it("outlives a re-init of the same root", () => {+ installHtmlInCanvas();+ const { root, h } = movingHost();+ initCaptureMotionBlur(h);+ win.__hfMotionBlur?.suspend();+ initCaptureMotionBlur(h);+ expect(paintCaptureMotionBlur(0.5, PLAY)).toBeNull();+ expect(root.parentElement).toBe(document.body);+ });++ it("exists, and does nothing, where blur is off", () => {+ const root = makeRoot();+ initCaptureMotionBlur(host(root));+ expect(() => win.__hfMotionBlur?.suspend()).not.toThrow();+ expect(win.__hfMotionBlur?.report().state).toBe("off");+ });++ it("lets the probe still decide after suspending", () => {+ installHtmlInCanvas();+ const { h } = movingHost();+ initCaptureMotionBlur(h);+ win.__hfMotionBlur?.suspend();+ expect(win.__hfMotionBlur?.report().state).toBe("on");+ });+});+describe("device pixel ratio", () => {it("sizes the capture and output canvases in device pixels and keeps the CSS size", () => {installHtmlInCanvas();@@ -1186,6 +1212,117 @@ describe("device pixel ratio", () => {});});+describe("probe", () => {+ const probe = () => {+ const api = win.__hfMotionBlur;+ if (!api) throw new Error("no __hfMotionBlur");+ return api.probe();+ };++ it("finds the movers without any paint, wrap or event and puts the playhead back", () => {+ installHtmlInCanvas();+ const { root, h } = movingHost();+ initCaptureMotionBlur({ ...h, now: () => 0.4 });+ expect(win.__hfMotionBlur?.report().moverNames).toEqual([]);+ const report = probe();+ expect(report).toMatchObject({+ state: "on",+ reason: null,+ reasonCode: null,+ moverNames: ["div#slider"],+ });+ expect(h.seek.mock.calls.at(-1)?.[0]).toBeCloseTo(0.4);+ expect(root.parentElement).toBe(document.body);+ expect(document.querySelector("canvas")).toBeNull();+ });++ it("reports no movers for a composition where nothing moves", () => {+ installHtmlInCanvas();+ initCaptureMotionBlur(host(makeRoot()));+ expect(probe()).toMatchObject({ state: "on", movers: 0 });+ });++ it("does not rescan on a second call, but does when the timeline changes", () => {+ installHtmlInCanvas();+ const { h } = movingHost();+ let tl = "a";+ initCaptureMotionBlur({ ...h, timeline: () => tl });+ probe();+ const seeks = h.seek.mock.calls.length;+ probe();+ expect(h.seek.mock.calls.length).toBe(seeks);+ tl = "b";+ probe();+ expect(h.seek.mock.calls.length).toBeGreaterThan(seeks);+ });++ it("reports the defect a scan finds, with its code, and a later frame stays plain", () => {+ installHtmlInCanvas();+ const { root, h } = movingHost();+ initCaptureMotionBlur({+ ...h,+ seek: (t, quiet) => {+ h.seek(t, quiet);+ root.style.opacity = t > 0.5 ? "0.5" : "1";+ },+ });+ expect(probe()).toMatchObject({ state: "off", reasonCode: "root-opacity" });+ expect(probe().reasonCode).toBe("root-opacity");+ void paintCaptureMotionBlur(0.5, { engineMode: true });+ expect(root.parentElement).toBe(document.body);+ });++ it("carries the code of a static defect and of an unsupported browser", () => {+ installHtmlInCanvas();+ const root = makeRoot();+ root.innerHTML =+ '<div style="transform-style: preserve-3d"><div style="backface-visibility: hidden"></div></div>';+ initCaptureMotionBlur(host(root));+ expect(probe()).toMatchObject({ state: "off", reasonCode: "backface-visibility" });++ resetCaptureMotionBlurForTests();+ vi.unstubAllGlobals();+ delete win.__hfMotionBlur;+ initCaptureMotionBlur(host(makeRoot()));+ expect(probe()).toMatchObject({ state: "off", reasonCode: "unsupported-browser" });+ });++ it("does not scan again once blur is off, even when a rescan was requested", () => {+ installHtmlInCanvas();+ const { h } = movingHost();+ initCaptureMotionBlur(h);+ captureContext()?.drawElementImage.mockImplementation(() => {+ throw new Error("boom");+ });+ for (let i = 0; i < 3; i++) {+ void paintCaptureMotionBlur(0.5, PLAY);+ document.querySelector("canvas")?.dispatchEvent(new Event("paint"));+ }+ initCaptureMotionBlur(h);+ const seeks = h.seek.mock.calls.length;+ expect(probe()).toMatchObject({ state: "off", reasonCode: "capture-failures" });+ expect(h.seek.mock.calls.length).toBe(seeks);+ });++ it("reports capture-failures after three failed frames", () => {+ installHtmlInCanvas();+ const { h } = movingHost();+ initCaptureMotionBlur(h);+ captureContext()?.drawElementImage.mockImplementation(() => {+ throw new Error("boom");+ });+ for (let i = 0; i < 3; i++) {+ void paintCaptureMotionBlur(0.5, PLAY);+ const canvas = document.querySelector("canvas");+ canvas?.dispatchEvent(new Event("paint"));+ }+ expect(win.__hfMotionBlur?.report()).toMatchObject({+ state: "off",+ reasonCode: "capture-failures",+ });+ });+});+describe("guards that once survived a deliberate break (T1)", () => {const frameOf = async (root: HTMLElement, t: number, fail: boolean): Promise<void> => {captureContext()?.drawElementImage.mockImplementation(() => {@@ -1207,7 +1344,7 @@ describe("guards that once survived a deliberate break (T1)", () => {await frameOf(root, 0.3, true);expect(win.__hfMotionBlur?.report()).toMatchObject({state: "off",- reason: "capture failed 3 times in a row",+ reasonCode: "capture-failures",});});@@ -1235,6 +1372,29 @@ describe("guards that once survived a deliberate break (T1)", () => {expect(times.filter((t) => t < 0)).toEqual([]);});+ it("disables once: one warning, and the first reason stays when unwrapping throws", () => {+ installHtmlInCanvas();+ const state = { fade: false, explode: false, timeline: "a" };+ const { root, h } = movingHost();+ const slide = h.seek;+ h.seek = vi.fn((t: number, quiet: boolean) => {+ if (state.explode && root.parentElement === document.body) throw new Error("seek blew up");+ slide(t, quiet);+ root.style.opacity = state.fade && t > 0.5 ? "0.5" : "1";+ });+ h.timeline = () => state.timeline;+ initCaptureMotionBlur(h);+ void paintCaptureMotionBlur(0.2, { engineMode: true });+ expect(root.parentElement).toBe(captureCanvas(root));+ Object.assign(state, { fade: true, explode: true, timeline: "b" });+ void paintCaptureMotionBlur(0.2, { engineMode: true });+ expect(console.warn).toHaveBeenCalledTimes(1);+ expect(win.__hfMotionBlur?.report()).toMatchObject({+ state: "off",+ reasonCode: "root-opacity",+ });+ });+it("removes the hide rule and both canvases on unwrap, and the movers' hide attribute", () => {installHtmlInCanvas();const { root, el, h } = movingHost();diff --git a/packages/core/src/runtime/captureMotionBlur/index.ts b/packages/core/src/runtime/captureMotionBlur/index.tsindex cafb88e571..f3b19b0d2f 100644--- a/packages/core/src/runtime/captureMotionBlur/index.ts+++ b/packages/core/src/runtime/captureMotionBlur/index.ts@@ -59,6 +59,7 @@ interface Config {interface Report {state: "on" | "off";reason: string | null;+ reasonCode: string | null;movers: number;/** The blurred elements, as `tag#id.class`, for diagnosing what was (not) picked. */moverNames: string[];@@ -76,7 +77,7 @@ type DrawElementContext = CanvasRenderingContext2D & {};type PaintCanvas = HTMLCanvasElement & { requestPaint: () => void };type CompositeWindow = Window & {- __hfMotionBlur?: { report: () => Report };+ __hfMotionBlur?: { report: () => Report; probe: () => Report; suspend: () => void };__hf_page_composite_pending?: boolean;__hf_page_composite_resolve?: () => boolean;};@@ -127,15 +128,16 @@ export const trackAcceleratedCanvases = installAcceleratedCanvasTracker;const isAccelerated: DefectEnv["isAccelerated"] = isAcceleratedCanvas;-function unsupportedReason(root: HTMLElement): string | null {+function unsupported(root: HTMLElement): CaptureDefect | null {const off = (window as unknown as Record<string, unknown>)[PAGE_MOTION_BLUR_OFF_GLOBAL];- if (off) return `the renderer turned it off (${String(off)})`;+ if (off) return { code: "renderer-off", reason: `the renderer turned it off (${String(off)})` };if (!supportsCaptureMotionBlur()) {- return "html-in-canvas (drawElementImage) is unavailable in this browser";+ return {+ code: "unsupported-browser",+ reason: "html-in-canvas (drawElementImage) is unavailable in this browser",+ };}- return (- findCaptureDefect(root, { isAccelerated, backface: scanBackfaceDefect(root) })?.reason ?? null- );+ return findCaptureDefect(root, { isAccelerated, backface: scanBackfaceDefect(root) });}function describe(el: Element): string {@@ -199,6 +201,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlIlet failures = 0;let failedFrames = 0;let disabled: string | null = null;+ let disabledCode: string | null = null;// Capture failures end blur for good; a defect block lasts until the scene is scanned again.let failedForGood = false;const timings: number[] = [];@@ -347,7 +350,8 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlIcountFailedFrame(err instanceof Error ? err.message : String(err));// A render never gives up mid-video: this frame shows the plain DOM, the next wraps again.if (rendering) unwrap();- else if (failures >= MAX_FAILURES) disable(`capture failed ${failures} times in a row`, true);+ else if (failures >= MAX_FAILURES)+ disable(`capture failed ${failures} times in a row`, "capture-failures", true);}/** This paint's half of the frame; false when the background capture is still to come. */@@ -405,9 +409,10 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlIsrc.addEventListener("paint", onPaint);- function disable(reason: string, forGood = false): void {+ function disable(reason: string, code: string, forGood = false): void {if (disabled) return;disabled = reason;+ disabledCode = code;failedForGood = forGood;console.warn(`[motion-blur] off: ${reason}`);teardown();@@ -421,6 +426,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlIfunction clearDefectBlock(): void {if (!disabled || failedForGood) return;disabled = null;+ disabledCode = null;reader = null;src.addEventListener("paint", onPaint);}@@ -474,7 +480,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI/** Scan when the timeline is new; true when the scan found a defect (blur is then off). */function blockedByScan(t: number): boolean {if (!reader || host.timeline() !== scannedTimeline) discover(t);- if (scanDefect) disable(scanDefect.reason);+ if (scanDefect) disable(scanDefect.reason, scanDefect.code);return disabled !== null;}@@ -532,7 +538,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI});} catch (err) {swallow("runtime.captureMotionBlur.paint", err);- disable(err instanceof Error ? err.message : String(err), true);+ disable(err instanceof Error ? err.message : String(err), "capture-failures", true);return Promise.resolve();}}@@ -542,6 +548,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlIreturn {state: disabled ? "off" : "on",reason: disabled,+ reasonCode: disabledCode,movers: movers.length,moverNames: movers.map(describe),scanMs,@@ -553,9 +560,16 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI};}+ function probe(): Report {+ releaseStaleBlock();+ if (!disabled) blockedByScan(host.now());+ return report();+ }+return {root,paint,+ probe,/** Paused in preview: show plain DOM so it can be selected. A render never rests. */rest: (): boolean => {if (rendering) return false;@@ -574,6 +588,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlIstep(true);},teardown,+ suspend: unwrap,report,busy: (): boolean => pending !== null,rediscover: () => {@@ -585,6 +600,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlItype Instance = ReturnType<typeof createInstance>;let instance: Instance | null = null;+let suspended = false;let priorResolver: (() => boolean) | null = null;let ourResolver: (() => boolean) | null = null;@@ -606,28 +622,33 @@ export function initCaptureMotionBlur(host: CaptureMotionBlurHost): void {return;}const form = htmlInCanvasForm();- const reason = unsupportedReason(host.root);- if (!form || reason) {+ const why = unsupported(host.root);+ if (!form || why) {+ const reason = why?.reason ?? null;console.info(`[motion-blur] off: ${reason} (Chrome ${chromeMajor() ?? "unknown"})`);- w.__hfMotionBlur = {- report: () => ({- state: "off",- reason,- movers: 0,- moverNames: [],- scanMs: 0,- shutterDeg: config.shutterDeg,- frames: 0,- meanMs: 0,- failures: 0,- failedFrames: 0,- }),- };+ const report = (): Report => ({+ state: "off",+ reason,+ reasonCode: why?.code ?? null,+ movers: 0,+ moverNames: [],+ scanMs: 0,+ shutterDeg: config.shutterDeg,+ frames: 0,+ meanMs: 0,+ failures: 0,+ failedFrames: 0,+ });+ w.__hfMotionBlur = { report, probe: report, suspend: suspendCaptureMotionBlur };return;}instance = createInstance(host, config, form);const current = instance;- w.__hfMotionBlur = { report: () => current.report() };+ w.__hfMotionBlur = {+ report: () => current.report(),+ probe: () => current.probe(),+ suspend: suspendCaptureMotionBlur,+ };}/**@@ -641,7 +662,7 @@ export function paintCaptureMotionBlur(t: number,options?: { engineMode?: boolean; playing?: boolean },): Promise<void> | null {- if (!instance) return null;+ if (!instance || suspended) return null;const engineMode = options?.engineMode === true;if (!engineMode && !options?.playing && instance.rest()) return null;const done = instance.paint(t, engineMode);@@ -678,10 +699,17 @@ function armPageComposite(): void {w.__hf_page_composite_pending = true;}+/** Stop wrapping and painting for the rest of the page's life; the reported decision stays. */+function suspendCaptureMotionBlur(): void {+ suspended = true;+ instance?.suspend();+}+/** Test-only: drop module state between cases. */export function resetCaptureMotionBlurForTests(): void {instance?.teardown();instance = null;+ suspended = false;priorResolver = null;ourResolver = null;}diff --git a/packages/engine/src/services/captureMotionBlur.pixels.browser.test.ts b/packages/engine/src/services/captureMotionBlur.pixels.browser.test.tsnew file mode 100644index 0000000000..7e2eae55ef--- /dev/null+++ b/packages/engine/src/services/captureMotionBlur.pixels.browser.test.ts@@ -0,0 +1,252 @@+import { spawnSync } from "node:child_process";+import { existsSync, readFileSync } from "node:fs";+import { resolve } from "node:path";+import puppeteer, { type Browser, type Page } from "puppeteer-core";+import { afterAll, beforeAll, describe, expect, it } from "vitest";+import { decodePng } from "../utils/alphaBlit.js";+import { resolveHeadlessShellPath } from "./browserManager.js";+import { closeTestChrome } from "./__fixtures__/loopback.js";+import { waitForPendingSeekCompletion } from "./frameCapture.js";++const RUNTIME = resolve(import.meta.dirname, "../../../core/dist/hyperframe.runtime.iife.js");+const chromePath = resolveHeadlessShellPath();+const hasBrowser =+ chromePath !== undefined &&+ existsSync(RUNTIME) &&+ spawnSync(chromePath, ["--version"]).status === 0;++const W = 320;+const H = 180;+const FPS = 30;+/** One of the 16 taps is 255 / 16: a plateau may wobble by that much. */+const TAP = 16;++interface Frame {+ width: number;+ data: Uint8Array;+}+type Win = Window & {+ __player?: { renderSeek?: (t: number) => void };+ __hf_page_composite_pending?: boolean;+ __hf_page_composite_prepare?: () => Promise<boolean>;+ __hf_page_composite_resolve?: () => boolean;+ __hfMotionBlur?: { report: () => { state: string; reasonCode: string | null; movers: number } };+};++/** 40 px box moving 60 px per frame (1800 px over the 1 s composition). */+const STYLE = `+ @keyframes run { to { transform: translateX(1800px) } }+ @keyframes flip { to { transform: rotateY(180deg) } }+ @keyframes hide { from, to { backface-visibility: hidden } }+ @keyframes blink { 0%, 44% { backface-visibility: visible } 46%, 49% { backface-visibility: hidden } 51%, 100% { backface-visibility: visible } }+ .box { position: absolute; width: 40px; height: 40px; background: #f00; animation: run 1s linear both }+`;+const BOX = `<div class="box" id="box" style="left:20px;top:20px"></div>`;+const STRIPES = `<div id="stripes" style="position:absolute;left:200px;top:100px;width:40px;height:40px;background:repeating-linear-gradient(90deg,#000 0 2px,#fff 2px 4px)"></div>`;+const CENTERED = `<div class="box" id="centered" style="left:50%;top:50%;translate:-50% -50%"></div>`;+const FLIP = `<div style="position:absolute;left:100px;top:40px;width:100px;height:100px;perspective:400px"><div id="card" style="width:100px;height:100px;background:#06c;backface-visibility:hidden;animation:flip 1s linear both"></div></div>`;++/** A card whose backface-visibility, if any, comes only from the given animation. */+const card = (animation: string, perspective = "perspective:400px") =>+ `<div style="position:absolute;left:100px;top:40px;width:100px;height:100px;${perspective}"><div id="card" style="width:100px;height:100px;background:#06c;${animation}"></div></div>`;+const WAAPI = `<script>document.getElementById("card").animate([{backfaceVisibility:"hidden"},{backfaceVisibility:"hidden"}],1000)</script>`;+const same = (a: Frame, b: Frame): boolean => Buffer.from(a.data).equals(Buffer.from(b.data));++function composition(body: string, blur: boolean): string {+ const attrs = blur ? ' data-motion-blur="on" data-motion-blur-shutter="360"' : "";+ return `<!doctype html><html><head><style>html,body{margin:0}${STYLE}</style></head><body>+ <div id="root" data-composition-id="root" data-start="0" data-duration="1" data-width="${W}" data-height="${H}"${attrs}+ style="position:relative;width:${W}px;height:${H}px;background:#fff;overflow:hidden">${body}</div></body></html>`;+}++const px = (f: Frame, x: number, y: number): [number, number, number] => {+ const i = (y * f.width + x) * 4;+ return [f.data[i] ?? 0, f.data[i + 1] ?? 0, f.data[i + 2] ?? 0];+};++/** How far a pixel is from white along white-to-red: 0 for white, 255 for pure red. */+const redness = (f: Frame, x: number, y: number): number => 255 - px(f, x, y)[1];++const row = (f: Frame, y: number): number[] =>+ Array.from({ length: W }, (_, x) => redness(f, x, y));++/** Columns that are neither the background nor the pure box colour. */+const intermediate = (values: number[]): number[] =>+ values.flatMap((v, x) => (v > 0 && v < 255 ? [x] : []));++/** Total redness: a blur spreads the box's ink along the path without adding or losing any. */+const ink = (values: number[]): number => values.reduce((s, v) => s + v, 0);++const centroid = (values: number[]): number => {+ const total = values.reduce((s, v) => s + v, 0);+ return values.reduce((s, v, x) => s + v * (x + 0.5), 0) / total;+};++describe.skipIf(!hasBrowser)("capture motion blur pixels in Chrome", () => {+ let browser: Browser;+ let supported = false;++ beforeAll(async () => {+ browser = await puppeteer.launch({+ executablePath: chromePath,+ headless: true,+ args: ["--no-sandbox", "--disable-dev-shm-usage", "--enable-features=CanvasDrawElement"],+ });+ const probe = await browser.newPage();+ supported = await probe.evaluate(+ () =>+ typeof Reflect.get(CanvasRenderingContext2D.prototype, "drawElementImage") === "function",+ );+ await probe.close();+ }, 30_000);+ afterAll(() => closeTestChrome(browser));++ async function open(body: string, blur: boolean): Promise<Page> {+ const page = await browser.newPage();+ await page.setViewport({ width: W, height: H, deviceScaleFactor: 1 });+ await page.setContent(composition(body, blur));+ await page.addScriptTag({ content: `window.__HF_EXPORT_RENDER_SEEK_CONFIG={fps:${FPS}};` });+ await page.addScriptTag({ content: readFileSync(RUNTIME, "utf8") });+ await page.waitForFunction(() => {+ const w = window as Win & { __playerReady?: boolean; __renderReady?: boolean };+ return w.__playerReady === true && w.__renderReady === true;+ });+ return page;+ }++ /** One frame the way the engine takes it: seek, wait for the page, composite, screenshot. */+ async function capture(page: Page, t: number): Promise<Frame> {+ const pending = await page.evaluate((time) => {+ const w = window as Win;+ w.__player?.renderSeek?.(time);+ return w.__hf_page_composite_pending === true;+ }, t);+ await waitForPendingSeekCompletion(page);+ if (pending) {+ await page.evaluate(async () => {+ const w = window as Win;+ await w.__hf_page_composite_prepare?.();+ });+ const cdp = await page.createCDPSession();+ await cdp.send("Page.captureScreenshot", {+ format: "jpeg",+ quality: 1,+ clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 },+ });+ await cdp.detach();+ await page.evaluate(() => (window as Win).__hf_page_composite_resolve?.());+ }+ const png = Buffer.from(await page.screenshot({ type: "png" }));+ const { width, data } = decodePng(png);+ return { width, data };+ }++ async function frameOf(body: string, blur: boolean, t: number) {+ const page = await open(body, blur);+ try {+ const frame = await capture(page, t);+ const report = await page.evaluate(() => (window as Win).__hfMotionBlur?.report() ?? null);+ return { frame, report };+ } finally {+ await page.close();+ }+ }++ const FRAME = 2 / FPS;++ it("leaves a trail along the motion line where the sharp frame has hard edges", async (ctx) => {+ if (!supported) ctx.skip();+ const blurred = await frameOf(BOX, true, FRAME);+ const sharp = await frameOf(BOX, false, FRAME);+ expect(blurred.report).toMatchObject({ state: "on", movers: 1 });++ const sharpRow = row(sharp.frame, 40);+ expect(sharpRow.filter((v) => v === 255)).toHaveLength(40);+ expect(intermediate(sharpRow)).toEqual([]);++ const trail = row(blurred.frame, 40);+ const span = intermediate(trail);+ expect(span.length).toBeGreaterThanOrEqual(40);+ const [first = 0] = span;+ const last = span[span.length - 1] ?? 0;+ expect(first).toBeLessThan(140);+ expect(last).toBeGreaterThan(180);+ const rising = trail.slice(first, 150);+ const falling = trail.slice(170, last + 1);+ expect(rising.every((v, i) => i === 0 || v >= (rising[i - 1] ?? 0) - TAP)).toBe(true);+ expect(falling.every((v, i) => i === 0 || v <= (falling[i - 1] ?? 0) + TAP)).toBe(true);+ expect(Math.max(...trail)).toBeGreaterThan(120);+ expect(Math.abs(centroid(trail) - 160)).toBeLessThan(0.5);+ expect(ink(trail) / ink(sharpRow)).toBeGreaterThan(0.97);+ expect(ink(trail) / ink(sharpRow)).toBeLessThan(1.03);+ });++ it("leaves what does not move exactly as the sharp frame has it", async (ctx) => {+ if (!supported) ctx.skip();+ const blurred = await frameOf(BOX + STRIPES, true, FRAME);+ const sharp = await frameOf(BOX + STRIPES, false, FRAME);+ expect(blurred.report).toMatchObject({ state: "on" });+ let differing = 0;+ for (let y = 100; y < 140; y++) {+ for (let x = 200; x < 240; x++) {+ if (px(blurred.frame, x, y).join() !== px(sharp.frame, x, y).join()) differing++;+ }+ }+ expect(differing).toBe(0);+ expect(new Set(Array.from({ length: 40 }, (_, x) => px(sharp.frame, 200 + x, 110)[0]))).toEqual(+ new Set([0, 255]),+ );+ });++ it("blurs a box centred with translate around where it really is", async (ctx) => {+ if (!supported) ctx.skip();+ const blurred = await frameOf(CENTERED, true, 1 / FPS);+ const sharp = await frameOf(CENTERED, false, 1 / FPS);+ const trail = row(blurred.frame, 90);+ expect(intermediate(trail).length).toBeGreaterThanOrEqual(40);+ const trueCentre = centroid(row(sharp.frame, 90));+ expect(trueCentre).toBeCloseTo(220, 0);+ expect(Math.abs(centroid(trail) - trueCentre)).toBeLessThan(0.5);+ const column = Array.from({ length: H }, (_, y) => redness(blurred.frame, 220, y));+ expect(Math.abs(centroid(column) - 90)).toBeLessThan(0.5);+ });++ it("blocks a backface-hidden card in a 3D flip and renders the plain frame", async (ctx) => {+ if (!supported) ctx.skip();+ const blurred = await frameOf(FLIP, true, 0.4);+ const sharp = await frameOf(FLIP, false, 0.4);+ expect(blurred.report).toMatchObject({ state: "off", reasonCode: "backface-visibility" });+ expect(Buffer.from(blurred.frame.data).equals(Buffer.from(sharp.frame.data))).toBe(true);+ });++ it("blocks a face whose backface-visibility only arrives through animation", async (ctx) => {+ if (!supported) ctx.skip();+ const sharp = await frameOf(BOX + card(""), false, 0.4);+ for (const body of [BOX + card("animation: hide 1s both"), BOX + card("") + WAAPI]) {+ const blurred = await frameOf(body, true, 0.4);+ expect(blurred.report).toMatchObject({ state: "off", reasonCode: "backface-visibility" });+ expect(same(blurred.frame, sharp.frame)).toBe(true);+ }+ });++ it("renders only the frame plain where an animated face flips between scan samples", async (ctx) => {+ if (!supported) ctx.skip();+ const slow = BOX.replace("top:20px", "top:20px;animation-duration:6s");+ const body = slow + card("animation: blink 1s both");+ for (const [frame, plain] of [+ [14, true],+ [5, false],+ ] as const) {+ const t = frame / FPS;+ const [blurred, sharp] = [await frameOf(body, true, t), await frameOf(body, false, t)];+ expect(blurred.report).toMatchObject({ state: "on" });+ expect(same(blurred.frame, sharp.frame)).toBe(plain);+ }+ });++ it("leaves a flat animated backface-visibility hack blurred", async (ctx) => {+ if (!supported) ctx.skip();+ const { report } = await frameOf(BOX + card("animation: hide 1s both", ""), true, 0.4);+ expect(report).toMatchObject({ state: "on", movers: 1 });+ });+});diff --git a/packages/engine/src/services/frameCapture-motionBlur.test.ts b/packages/engine/src/services/frameCapture-motionBlur.test.tsindex 8ef8aedd42..337cbb0b28 100644--- a/packages/engine/src/services/frameCapture-motionBlur.test.ts+++ b/packages/engine/src/services/frameCapture-motionBlur.test.ts@@ -635,3 +635,54 @@ describe("a stall on a motion-blurred frame names the step in progress", () => {expect(session.captureStep).toBe("capturing the frame");});});++describe("the per-session blur line", () => {+ const log = () => vi.spyOn(console, "log").mockImplementation(() => {});+ const askForBlur = (report: object) => {+ const page = (globalThis as Record<string, unknown>).window as Record<string, unknown>;+ page.__hfMotionBlur = { report: () => report };+ };++ afterEach(() => vi.restoreAllMocks());++ it("is logged once, after the session's first captured frame, from the page's report", async () => {+ const spy = log();+ askForBlur({ state: "on", reasonCode: null, movers: 4, failedFrames: 0 });+ const session = makeSession({ motionBlur: undefined });+ await captureFrameToBuffer(session, 0, 0);+ await captureFrameToBuffer(session, 1, 1 / 30);+ await captureFrameToBuffer(session, 2, 2 / 30);+ const lines = spy.mock.calls+ .map(([line]) => line)+ .filter((l) => `${l}`.includes("[motion-blur]"));+ expect(lines).toEqual(["[motion-blur] on reasonCode=null movers=4 failedFrames=0"]);+ });++ it("says why blur is off for the session", async () => {+ const spy = log();+ askForBlur({ state: "off", reasonCode: "renderer-off", movers: 0 });+ await captureFrameToBuffer(makeSession({ motionBlur: undefined }), 0, 0);+ expect(spy).toHaveBeenCalledWith(+ "[motion-blur] off reasonCode=renderer-off movers=0 failedFrames=0",+ );+ });++ it("stays silent for a page that never asked for blur, and survives a page that cannot answer", async () => {+ const spy = log();+ await captureFrameToBuffer(makeSession({ motionBlur: undefined }), 0, 0);+ const broken = makeSession({ motionBlur: undefined });+ const evaluate = broken.page.evaluate.bind(broken.page);+ Object.assign(broken.page, {+ evaluate: async (...args: Parameters<typeof evaluate>) => {+ if (String(args[0]).includes("__hfMotionBlur")) throw new Error("page is gone");+ return evaluate(...args);+ },+ });+ await expect(captureFrameToBuffer(broken, 0, 0)).resolves.toMatchObject({+ captureTimeMs: expect.any(Number),+ });+ expect(+ spy.mock.calls.map(([line]) => `${line}`).filter((l) => l.includes("[motion-blur]")),+ ).toEqual([]);+ });+});diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.tsindex 0986628af5..88586c4ea1 100644--- a/packages/engine/src/services/frameCapture.ts+++ b/packages/engine/src/services/frameCapture.ts@@ -40,7 +40,11 @@ import {resolveMotionBlurPlan,type MotionBlurPlan,} from "./motionBlur.js";-import { installPageMotionBlur } from "./pageMotionBlur.js";+import {+ describePageMotionBlur,+ describePageMotionBlurAtEnd,+ installPageMotionBlur,+} from "./pageMotionBlur.js";// ── Extracted modules ───────────────────────────────────────────────────────import {@@ -4346,6 +4350,10 @@ async function captureFrameCore(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) {@@ -4792,6 +4800,10 @@ export async function closeCaptureSession(session: CaptureSession): Promise<void// 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, sodiff --git a/packages/engine/src/services/pageMotionBlur.test.ts b/packages/engine/src/services/pageMotionBlur.test.tsindex 444a8e396b..048c024ee3 100644--- a/packages/engine/src/services/pageMotionBlur.test.ts+++ b/packages/engine/src/services/pageMotionBlur.test.ts@@ -1,10 +1,15 @@-import { describe, expect, it, vi } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";import {PAGE_DEVICE_SCALE_GLOBAL,PAGE_MOTION_BLUR_OFF_GLOBAL,acceleratedCanvasTrackerSource,} from "@hyperframes/core";-import { installPageMotionBlur } from "./pageMotionBlur";+import {+ describePageMotionBlur,+ describePageMotionBlurAtEnd,+ installPageMotionBlur,+} from "./pageMotionBlur";+import { closeCaptureSession } from "./frameCapture";const fakePage = () => ({ evaluateOnNewDocument: vi.fn(async () => ({ identifier: "1" })) });@@ -58,3 +63,115 @@ describe("installPageMotionBlur", () => {expect(page.evaluateOnNewDocument.mock.calls).toEqual([[acceleratedCanvasTrackerSource()]]);});});++describe("describePageMotionBlur", () => {+ afterEach(() => vi.unstubAllGlobals());+ // Runs the page-side function in this process, with `window` standing in for the page.+ const inPage = { evaluate: async (fn: () => unknown) => fn() } as never;++ it("summarises the runtime's report in one line", async () => {+ vi.stubGlobal("window", {+ __hfMotionBlur: { report: () => ({ state: "off", reasonCode: "renderer-off", movers: 0 }) },+ });+ expect(await describePageMotionBlur(inPage)).toBe(+ "[motion-blur] off reasonCode=renderer-off movers=0 failedFrames=0",+ );+ });++ it("reports a running blur with its movers", async () => {+ vi.stubGlobal("window", {+ __hfMotionBlur: { report: () => ({ state: "on", reasonCode: null, movers: 24 }) },+ });+ expect(await describePageMotionBlur(inPage)).toBe(+ "[motion-blur] on reasonCode=null movers=24 failedFrames=0",+ );+ });++ it('carries the frames that fell back to plain DOM, so "on" cannot hide them', async () => {+ vi.stubGlobal("window", {+ __hfMotionBlur: {+ report: () => ({ state: "on", reasonCode: null, movers: 3, failures: 0, failedFrames: 17 }),+ },+ });+ expect(await describePageMotionBlur(inPage)).toBe(+ "[motion-blur] on reasonCode=null movers=3 failedFrames=17",+ );+ });++ it("says nothing when the page never asked for blur", async () => {+ vi.stubGlobal("window", {});+ expect(await describePageMotionBlur(inPage)).toBeNull();+ });+});++describe("describePageMotionBlurAtEnd", () => {+ afterEach(() => vi.unstubAllGlobals());+ const inPage = { evaluate: async (fn: () => unknown) => fn() } as never;+ const report = (over: Record<string, unknown>) =>+ vi.stubGlobal("window", {+ __hfMotionBlur: {+ report: () => ({ state: "on", reasonCode: null, movers: 2, failedFrames: 0, ...over }),+ },+ });++ it("stays quiet for a session that blurred every frame, or never could", async () => {+ report({});+ expect(await describePageMotionBlurAtEnd(inPage)).toBeNull();+ report({ state: "off", reasonCode: "engine-motion-blur", movers: 0 });+ expect(await describePageMotionBlurAtEnd(inPage)).toBeNull();+ });++ it("says so when frames fell back to plain DOM, even though blur is still on", async () => {+ report({ failedFrames: 4 });+ expect(await describePageMotionBlurAtEnd(inPage)).toBe(+ "[motion-blur] on reasonCode=null movers=2 failedFrames=4 (session end)",+ );+ });++ it("says so when the failures ended blur", async () => {+ report({ state: "off", reasonCode: "capture-failures", failedFrames: 3 });+ expect(await describePageMotionBlurAtEnd(inPage)).toBe(+ "[motion-blur] off reasonCode=capture-failures movers=2 failedFrames=3 (session end)",+ );+ });++ it("gives up on a page that does not answer, or is gone", async () => {+ const stuck = { evaluate: () => new Promise(() => {}) } as never;+ expect(await describePageMotionBlurAtEnd(stuck, 10)).toBeNull();+ const gone = { evaluate: async () => Promise.reject(new Error("closed")) } as never;+ expect(await describePageMotionBlurAtEnd(gone)).toBeNull();+ });+});++describe("closeCaptureSession", () => {+ afterEach(() => vi.restoreAllMocks());++ it("logs the blur's closing line once, before the page closes", async () => {+ const log = vi.spyOn(console, "log").mockImplementation(() => {});+ const order: string[] = [];+ vi.stubGlobal("window", {+ __hfMotionBlur: {+ report: () => ({ state: "on", reasonCode: null, movers: 1, failedFrames: 2 }),+ },+ });+ const session = {+ page: {+ evaluate: async (fn: () => unknown) => {+ order.push("read");+ return fn();+ },+ close: async () => order.push("close"),+ },+ pageReleased: false,+ browserReleased: true,+ staticDedupCount: 0,+ };+ await closeCaptureSession(session as never);+ await closeCaptureSession(session as never);+ expect(log.mock.calls.map(([line]) => line)).toEqual([+ "[motion-blur] on reasonCode=null movers=1 failedFrames=2 (session end)",+ ]);+ expect(order).toEqual(["read", "close"]);+ vi.unstubAllGlobals();+ });+});diff --git a/packages/engine/src/services/pageMotionBlur.ts b/packages/engine/src/services/pageMotionBlur.tsindex 4e423992ae..844f5f0a55 100644--- a/packages/engine/src/services/pageMotionBlur.ts+++ b/packages/engine/src/services/pageMotionBlur.ts@@ -45,3 +45,55 @@ export async function installPageMotionBlur(off,);}++interface PageMotionBlurState {+ state: string;+ code: string;+ movers: number;+ failedFrames: number;+}++async function readPageMotionBlur(+ page: Pick<Page, "evaluate">,+): Promise<PageMotionBlurState | null> {+ return page.evaluate(() => {+ const api: unknown = Reflect.get(window, "__hfMotionBlur");+ const report: unknown = api && typeof api === "object" ? Reflect.get(api, "report") : null;+ const got: unknown = 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: PageMotionBlurState): string =>+ `[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: Pick<Page, "evaluate">): Promise<string | null> {+ 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: Pick<Page, "evaluate">,+ timeoutMs = 1500,+): Promise<string | null> {+ let timer: ReturnType<typeof setTimeout> | undefined;+ const stuck = new Promise<null>((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);+ }+}diff --git a/packages/producer/src/services/distributed/chunkFrames.test.ts b/packages/producer/src/services/distributed/chunkFrames.test.tsnew file mode 100644index 0000000000..ce1b2dc710--- /dev/null+++ b/packages/producer/src/services/distributed/chunkFrames.test.ts@@ -0,0 +1,19 @@+import { describe, expect, it } from "bun:test";+import { buildChunkCaptureOptions } from "./chunkFrames.js";++const input = {+ dimensions: { width: 320, height: 240, fpsNum: 30, fpsDen: 1, format: "mp4" as const },+ encoder: { quality: "standard" as const, deviceScaleFactor: 1, variables: undefined },+ videoCount: 0,+ html: "<html></html>",+};++describe("buildChunkCaptureOptions", () => {+ it("turns the page's capture motion blur off: a distributed render has no preview to match (R19)", () => {+ expect(buildChunkCaptureOptions(input).pageMotionBlur).toBe("distributed-render");+ });++ it("asks for no engine motion blur either", () => {+ expect(buildChunkCaptureOptions(input).motionBlur).toBeUndefined();+ });+});