diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 075adb086b..f51a8660f4 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -2267,7 +2267,8 @@ npx hyperframes telemetry status Telemetry collects command names, render performance, render checkpoint and error names, aggregate browser diagnostic counts, browser initialization duration and tween count, aggregate video-extraction workload counts (extracted -frames, VFR preflights), example choices, the names of registry items `add` or +frames, VFR preflights), aggregate counts of what a motion-blur render's composition holds +(movers, videos, iframes, canvases, custom elements, and similar), example choices, the names of registry items `add` or Studio installs and which of the two installed them, and system info — including a coarse environment fingerprint: OS, kernel string, CPU and memory shape, sandbox runtime such as gVisor or Docker, and the _name_ of a coding agent driving the diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 9bba3e9196..e21c8514f3 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -93,6 +93,7 @@ import { type RenderEnvironmentTelemetryPayload, } from "../telemetry/events.js"; import { maybePromptRenderFeedback } from "../telemetry/feedback.js"; +import { renderMotionBlurTelemetryPayload } from "../telemetry/renderMotionBlur.js"; import { readConfigFresh, releaseDeParallelRouterLatch, @@ -1991,6 +1992,7 @@ function trackRenderMetrics( catalogUsage: options.catalogUsage, ...renderOutputShapeTelemetryPayload(options), ...renderEnvironmentTelemetryPayload(options), + ...renderMotionBlurTelemetryPayload(perf?.motionBlur), chromeBrowserRssPeakMb: perf?.chromeMemory?.browserRssPeakMb, chromeRendererRssPeakMb: perf?.chromeMemory?.rendererRssPeakMb, chromeRssLastMb: perf?.chromeMemory?.rssLastMb, diff --git a/packages/cli/src/server/studioRenderTelemetry.ts b/packages/cli/src/server/studioRenderTelemetry.ts index 458cf48429..1693163cda 100644 --- a/packages/cli/src/server/studioRenderTelemetry.ts +++ b/packages/cli/src/server/studioRenderTelemetry.ts @@ -11,6 +11,7 @@ import type { CanvasResolution, Fps } from "@hyperframes/core"; import { fpsToNumber } from "@hyperframes/core"; import type { RenderJob, RenderPerfSummary } from "@hyperframes/producer"; import { trackRenderComplete, trackRenderError } from "../telemetry/events.js"; +import { renderMotionBlurTelemetryPayload } from "../telemetry/renderMotionBlur.js"; import { renderJobObservabilityTelemetryPayload, renderObservabilityTelemetryPayload, @@ -109,6 +110,7 @@ function perfPayload( ...stagesPayload(perf.stages), ...extractPayload(perf.videoExtractBreakdown), ...renderObservabilityTelemetryPayload(perf.observability), + ...renderMotionBlurTelemetryPayload(perf.motionBlur), }; } diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts index bd967366f1..f401a27c13 100644 --- a/packages/cli/src/telemetry/events.ts +++ b/packages/cli/src/telemetry/events.ts @@ -9,6 +9,10 @@ import { flush, shouldTrack, trackEvent } from "./client.js"; import { readConfig } from "./config.js"; import { getPowerState } from "./system.js"; import type { RenderCpuTelemetryPayload } from "./renderCpu.js"; +import { + type RenderMotionBlurTelemetryPayload, + renderMotionBlurEventProperties, +} from "./renderMotionBlur.js"; import { CliRuntimeError } from "../utils/commandResult.js"; // Power state is volatile (a laptop docks/undocks mid-session), so it is @@ -489,7 +493,8 @@ export function trackRenderComplete( } & RenderObservabilityTelemetryPayload & RenderOutputShapeTelemetryPayload & RenderEnvironmentTelemetryPayload & - RenderCpuTelemetryPayload, + RenderCpuTelemetryPayload & + RenderMotionBlurTelemetryPayload, ): void { trackEvent( "render_complete", @@ -615,6 +620,7 @@ export function trackRenderComplete( ...renderOutputShapeEventProperties(props), ...renderEnvironmentEventProperties(props), ...renderCpuEventProperties(props), + ...renderMotionBlurEventProperties(props), composition_duration_ms: props.compositionDurationMs, composition_width: props.compositionWidth, composition_height: props.compositionHeight, diff --git a/packages/cli/src/telemetry/renderMotionBlur.test.ts b/packages/cli/src/telemetry/renderMotionBlur.test.ts new file mode 100644 index 0000000000..675a375d1b --- /dev/null +++ b/packages/cli/src/telemetry/renderMotionBlur.test.ts @@ -0,0 +1,128 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { PageMotionBlurSummary } from "@hyperframes/engine"; + +const trackEvent = vi.fn(); +vi.mock("./client.js", () => ({ + trackEvent: (...args: unknown[]) => trackEvent(...args), + flush: () => Promise.resolve(), + shouldTrack: () => true, +})); +vi.mock("./system.js", async () => ({ + ...(await vi.importActual("./system.js")), + getPowerState: () => ({ on_battery: false, low_power_mode: false }), +})); + +const { trackRenderComplete } = await import("./events.js"); +const { renderMotionBlurEventProperties, renderMotionBlurTelemetryPayload } = + await import("./renderMotionBlur.js"); + +const fingerprint = (over: Partial>) => ({ + canvas2d: 0, + webgl: 0, + video: 0, + iframe: 0, + customElement: 0, + svgClip: 0, + mask: 0, + scrollContainer: 0, + threeD: 0, + overflowingMover: 0, + frontOfMover: 0, + blendMode: 0, + fixedInMover: 0, + pseudoOutside: 0, + ...over, +}); + +const blur = (over: Partial = {}): PageMotionBlurSummary => ({ + tier: "filter", + reasonCode: "accelerated-canvas", + movers: 4, + failedFrames: 0, + readEvents: false, + fingerprint: fingerprint({}), + ...over, +}); + +const complete = (motionBlur: PageMotionBlurSummary | undefined) => { + trackRenderComplete({ + durationMs: 1, + fps: 30, + quality: "draft", + docker: false, + gpu: false, + ...renderMotionBlurTelemetryPayload(motionBlur), + }); + return trackEvent.mock.calls[0]?.[1] as Record; +}; + +describe("render_complete motion blur properties", () => { + beforeEach(() => trackEvent.mockClear()); + + it("sends the tier, movers, failed frames and one property per non-zero count", () => { + const props = complete( + blur({ + failedFrames: 7, + fingerprint: fingerprint({ webgl: 1, overflowingMover: 3, canvas2d: 2 }), + }), + ); + expect(props).toMatchObject({ + motion_blur_tier: "filter", + motion_blur_movers: 4, + motion_blur_failed_frames: 7, + motion_blur_fp_canvas2d: 2, + motion_blur_fp_webgl: 1, + motion_blur_fp_overflowing_mover: 3, + }); + const keys = Object.keys(props).filter((k) => k.startsWith("motion_blur_")); + expect(keys.sort()).toEqual([ + "motion_blur_failed_frames", + "motion_blur_fp_canvas2d", + "motion_blur_fp_overflowing_mover", + "motion_blur_fp_webgl", + "motion_blur_movers", + "motion_blur_tier", + ]); + }); + + it("sends nothing when blur was never on", () => { + const sent = Object.entries(complete(undefined)).filter( + ([key, value]) => key.startsWith("motion_blur_") && value !== undefined, + ); + expect(sent).toEqual([]); + }); + + it("sends failed frames for a blur that ended before it named a tier, and no zero counts", () => { + const props = renderMotionBlurEventProperties( + renderMotionBlurTelemetryPayload(blur({ tier: null, failedFrames: 5, fingerprint: null })), + ); + expect(props).toEqual({ + motion_blur_tier: undefined, + motion_blur_movers: 4, + motion_blur_failed_frames: 5, + }); + }); + + it("names every count the runtime can report, in snake case", () => { + const all = Object.fromEntries( + Object.keys(fingerprint({})).map((field) => [field, 1]), + ) as ReturnType; + const props = renderMotionBlurEventProperties({ motionBlurFingerprint: all }); + expect(Object.keys(props).filter((k) => k.startsWith("motion_blur_fp_"))).toEqual([ + "motion_blur_fp_canvas2d", + "motion_blur_fp_webgl", + "motion_blur_fp_video", + "motion_blur_fp_iframe", + "motion_blur_fp_custom_element", + "motion_blur_fp_svg_clip", + "motion_blur_fp_mask", + "motion_blur_fp_scroll_container", + "motion_blur_fp_three_d", + "motion_blur_fp_overflowing_mover", + "motion_blur_fp_front_of_mover", + "motion_blur_fp_blend_mode", + "motion_blur_fp_fixed_in_mover", + "motion_blur_fp_pseudo_outside", + ]); + }); +}); diff --git a/packages/cli/src/telemetry/renderMotionBlur.ts b/packages/cli/src/telemetry/renderMotionBlur.ts new file mode 100644 index 0000000000..6efbf4e2d2 --- /dev/null +++ b/packages/cli/src/telemetry/renderMotionBlur.ts @@ -0,0 +1,38 @@ +import { MOTION_BLUR_FINGERPRINT_FIELDS, type MotionBlurFingerprint } from "@hyperframes/core"; +import type { PageMotionBlurSummary } from "@hyperframes/engine"; + +export interface RenderMotionBlurTelemetryPayload { + motionBlurTier?: string; + motionBlurMovers?: number; + motionBlurFailedFrames?: number; + motionBlurFingerprint?: MotionBlurFingerprint; +} + +export function renderMotionBlurTelemetryPayload( + motionBlur: PageMotionBlurSummary | undefined, +): RenderMotionBlurTelemetryPayload { + if (!motionBlur) return {}; + return { + motionBlurTier: motionBlur.tier ?? undefined, + motionBlurMovers: motionBlur.movers, + motionBlurFailedFrames: motionBlur.failedFrames, + motionBlurFingerprint: motionBlur.fingerprint ?? undefined, + }; +} + +const snake = (field: string): string => field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`); + +export function renderMotionBlurEventProperties( + props: RenderMotionBlurTelemetryPayload, +): Record { + const counts = MOTION_BLUR_FINGERPRINT_FIELDS.flatMap((field) => { + const count = props.motionBlurFingerprint?.[field]; + return count ? [[`motion_blur_fp_${snake(field)}`, count] as const] : []; + }); + return { + motion_blur_tier: props.motionBlurTier, + motion_blur_movers: props.motionBlurMovers, + motion_blur_failed_frames: props.motionBlurFailedFrames, + ...Object.fromEntries(counts), + }; +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index d14eb1bc2d..e0381edf31 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -485,3 +485,8 @@ export { PAGE_MOTION_BLUR_OFF_GLOBAL, acceleratedCanvasTrackerSource, } from "./pageMotionBlur.js"; +export { + MOTION_BLUR_FINGERPRINT_FIELDS, + type MotionBlurFingerprint, + type MotionBlurFingerprintField, +} from "./motionBlurFingerprint.js"; diff --git a/packages/core/src/motionBlurFingerprint.ts b/packages/core/src/motionBlurFingerprint.ts new file mode 100644 index 0000000000..5c6b5acf64 --- /dev/null +++ b/packages/core/src/motionBlurFingerprint.ts @@ -0,0 +1,39 @@ +export const MOTION_BLUR_FINGERPRINT_FIELDS = [ + "canvas2d", + "webgl", + "video", + "iframe", + "customElement", + "svgClip", + "mask", + "scrollContainer", + "threeD", + "overflowingMover", + "frontOfMover", + "blendMode", + "fixedInMover", + "pseudoOutside", +] as const; + +export type MotionBlurFingerprintField = (typeof MOTION_BLUR_FINGERPRINT_FIELDS)[number]; + +export type MotionBlurFingerprint = Record; + +export function emptyMotionBlurFingerprint(): MotionBlurFingerprint { + return { + canvas2d: 0, + webgl: 0, + video: 0, + iframe: 0, + customElement: 0, + svgClip: 0, + mask: 0, + scrollContainer: 0, + threeD: 0, + overflowingMover: 0, + frontOfMover: 0, + blendMode: 0, + fixedInMover: 0, + pseudoOutside: 0, + }; +} diff --git a/packages/core/src/runtime/captureMotionBlur/discover.test.ts b/packages/core/src/runtime/captureMotionBlur/discover.test.ts index 323ef0ffcd..84641d63f8 100644 --- a/packages/core/src/runtime/captureMotionBlur/discover.test.ts +++ b/packages/core/src/runtime/captureMotionBlur/discover.test.ts @@ -1,5 +1,5 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import { discoverMovers } from "./discover"; +import { discoverMovers, scanMovers } from "./discover"; // jsdom lays nothing out: each element's rect follows the x its fake timeline writes. function element(parent: Element, id: string, size = 10, tag = "div"): HTMLElement { @@ -41,6 +41,34 @@ describe("discoverMovers", () => { expect(movers).toEqual([fast]); }); + it("hands the fast elements to onFast at every step, with the pose of that step applied", () => { + const { scene, fast, seek } = setup(); + const seen: Array<[number, boolean, string]> = []; + discoverMovers({ + scene, + durationSeconds: 1, + fps: 30, + seek, + onFast: (i, _steps, set) => seen.push([i, set.has(fast), fast.style.transform]), + }); + expect(seen.map(([i]) => i)).toEqual(Array.from({ length: 31 }, (_, i) => i)); + expect(seen.at(-1)).toEqual([30, true, "translateX(300px)"]); + }); + + it("samples a scan once through onFast, even when it runs the extra passes that read events", () => { + const { scene, seek } = setup(); + const steps: number[] = []; + scanMovers({ + scene, + durationSeconds: 1, + fps: 30, + seek: (t) => seek(t), + events: true, + onFast: (i) => steps.push(i), + }); + expect(steps).toHaveLength(31); + }); + // A 100 px jump inside one scan step at 5 s: slow to a still-style baseline, fast between two steps. function jumpScene() { const scene = document.createElement("div"); diff --git a/packages/core/src/runtime/captureMotionBlur/discover.ts b/packages/core/src/runtime/captureMotionBlur/discover.ts index 9c5a1e1c9d..6dac7fca9a 100644 --- a/packages/core/src/runtime/captureMotionBlur/discover.ts +++ b/packages/core/src/runtime/captureMotionBlur/discover.ts @@ -38,6 +38,7 @@ export interface DiscoverOptions { /** Seek the composition (timeline + adapters) to a time. */ seek: (t: number) => void; onStep?: (i: number, steps: number) => void; + onFast?: (i: number, steps: number, fast: ReadonlySet) => void; onStepBoxes?: (i: number, boxes: ReadonlyArray) => void; } @@ -171,6 +172,7 @@ export function discoverMovers({ fps, seek, onStep, + onFast, onStepBoxes, }: DiscoverOptions): Discovery { seek(0); @@ -232,6 +234,7 @@ export function discoverMovers({ ) seeThrough.add(el); }); + onFast?.(i, steps, fast); // Style reads up the chain are the costly part; every 10th step is enough to see a 3D turn. if (i % 10 === 0 || i === steps) { for (const el of fast) { @@ -285,17 +288,21 @@ export function scanMovers({ seek, events, onStep, + onFast, ...scan }: ScanOptions): Discovery & { readEvents: boolean } { const quiet = (t: number): void => seek(t, true); const rewindThroughEveryCall = (): void => seek(0, false); - if (!events) return { ...discoverMovers({ ...scan, seek: quiet, onStep }), readEvents: false }; + if (!events) { + return { ...discoverMovers({ ...scan, seek: quiet, onStep, onFast }), readEvents: false }; + } // Loud first: run after the silent scan, it starts at the end and fires a one-off call once more. const loud: number[] = []; const found = discoverMovers({ ...scan, seek: (t) => seek(t, false), onStep, + onFast, onStepBoxes: (i, boxes) => { loud[i] = boxesKey(boxes); }, diff --git a/packages/core/src/runtime/captureMotionBlur/filterTier.ts b/packages/core/src/runtime/captureMotionBlur/filterTier.ts index 94a135b176..374a80cf8b 100644 --- a/packages/core/src/runtime/captureMotionBlur/filterTier.ts +++ b/packages/core/src/runtime/captureMotionBlur/filterTier.ts @@ -7,9 +7,11 @@ import { swallow } from "../diagnostics"; import { scanMovers, whileCallbacksMuted } from "./discover"; +import { compositionFingerprint, coverageSampler } from "./fingerprint"; import { planFilter, type FilterPlan } from "./filterPlan"; -import { CONTENT_NODE_LIMIT, readMoverFrames, shutterTimes } from "./frames"; +import { holdsFixedChild, readMoverFrames, shutterTimes } from "./frames"; import { createPoseReader } from "./pose"; +import type { MotionBlurFingerprint } from "../../motionBlurFingerprint"; import type { CaptureMotionBlurHost, Config, Report, Tier } from "./tier"; const NS = "http://www.w3.org/2000/svg"; @@ -94,14 +96,6 @@ function aim(layer: Layer, plan: FilterPlan): void { layer.filter.setAttribute("height", h.toFixed(1)); } -function holdsFixedChild(el: HTMLElement): boolean { - const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_ELEMENT); - for (let n = 0; n < CONTENT_NODE_LIMIT && walker.nextNode(); n++) { - if (getComputedStyle(walker.currentNode as Element).position === "fixed") return true; - } - return false; -} - const CONTAINING_BLOCK_PROPERTIES = [ "transform", "translate", @@ -131,6 +125,7 @@ export function createFilterTier( const height = Number(root.getAttribute("data-height")) || root.offsetHeight; const seek = (t: number): void => host.seek(t, !config.events); let readEvents = false; + let fingerprint: MotionBlurFingerprint | null = null; const readSeek = (t: number): void => host.seek(t, !readEvents); let defs: SVGSVGElement | null = null; let movers: HTMLElement[] = []; @@ -148,6 +143,7 @@ export function createFilterTier( function discover(restoreTo: number): void { scanned = host.timeline(); + const coverage = coverageSampler(root); const s0 = performance.now(); const found = whileCallbacksMuted(host, config.events, () => { const scan = scanMovers({ @@ -156,6 +152,7 @@ export function createFilterTier( fps: host.fps, seek: host.seek, events: config.events, + onFast: coverage.sample, }); seek(restoreTo); return scan; @@ -164,6 +161,7 @@ export function createFilterTier( movers = found.movers; fixedHolders = new Set(movers.filter(holdsFixedChild)); pads = found.pads; + fingerprint = compositionFingerprint(root, movers, coverage.covered); reader = createPoseReader(root, found.dynamic); scanMs = Math.round(performance.now() - s0); } @@ -268,6 +266,8 @@ export function createFilterTier( meanMs: frames ? Math.round((totalMs / frames) * 10) / 10 : 0, failures: 0, failedFrames: 0, + fingerprint, + readEvents, }; } diff --git a/packages/core/src/runtime/captureMotionBlur/fingerprint.test.ts b/packages/core/src/runtime/captureMotionBlur/fingerprint.test.ts new file mode 100644 index 0000000000..6af52e19df --- /dev/null +++ b/packages/core/src/runtime/captureMotionBlur/fingerprint.test.ts @@ -0,0 +1,322 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { MOTION_BLUR_FINGERPRINT_FIELDS } from "../../motionBlurFingerprint"; +import { compositionFingerprint, coverageSampler } from "./fingerprint"; + +type Style = Record; +type Rect = [number, number, number, number]; + +const DEFAULTS: Style = { + clipPath: "none", + maskImage: "none", + mask: "none", + overflowX: "visible", + overflowY: "visible", + transformStyle: "flat", + perspective: "none", + mixBlendMode: "normal", + backdropFilter: "none", + pointerEvents: "auto", + position: "static", + content: "none", +}; + +const styles = new WeakMap(); +const pseudos = new WeakMap>(); + +function computed(el: Element, pseudo?: string | null): CSSStyleDeclaration { + const own = pseudo ? (pseudos.get(el)?.[pseudo] ?? {}) : (styles.get(el) ?? {}); + const all = { ...DEFAULTS, ...(pseudo ? { position: "static" } : {}), ...own }; + return { ...all, getPropertyValue: (name: string) => all[name] ?? "" } as never; +} + +function rectOf([left, top, right, bottom]: Rect): DOMRect { + return { left, top, right, bottom, width: right - left, height: bottom - top } as DOMRect; +} + +function put(parent: Element, tag: string, style: Style = {}): HTMLElement { + const el = document.createElement(tag); + parent.append(el); + styles.set(el, style); + return el; +} + +function lay(el: HTMLElement, layout: { box?: Rect; offset?: [number, number]; scroll?: Rect }) { + const def = (key: string, value: number) => + Object.defineProperty(el, key, { value, configurable: true }); + if (layout.box) el.getBoundingClientRect = () => rectOf(layout.box as Rect); + if (layout.offset) { + def("offsetWidth", layout.offset[0]); + def("offsetHeight", layout.offset[1]); + } + if (layout.scroll) { + const [sw, sh, cw, ch] = layout.scroll; + def("scrollWidth", sw); + def("scrollHeight", sh); + def("clientWidth", cw); + def("clientHeight", ch); + } +} + +const RANGE_KEYS = ["selectNodeContents", "getBoundingClientRect"] as const; +const realRange = RANGE_KEYS.map((k) => (Range.prototype as unknown as Record)[k]); +const doc = document as unknown as { elementsFromPoint?: unknown }; +const realElementsFromPoint = doc.elementsFromPoint; + +function fingerprintOf( + root: HTMLElement, + movers: HTMLElement[] = [], + covered: ReadonlySet = new Set(), +) { + return compositionFingerprint(root, movers, covered); +} + +describe("compositionFingerprint", () => { + let root: HTMLElement; + + beforeEach(() => { + vi.spyOn(window, "getComputedStyle").mockImplementation(((el: Element, p?: string | null) => + computed(el, p)) as never); + const range = Range.prototype as unknown as Record; + range.selectNodeContents = () => {}; + range.getBoundingClientRect = () => rectOf([0, 0, 0, 0]); + root = document.createElement("div"); + document.body.append(root); + }); + + afterEach(() => { + vi.restoreAllMocks(); + RANGE_KEYS.forEach((k, i) => { + (Range.prototype as unknown as Record)[k] = realRange[i]; + }); + doc.elementsFromPoint = realElementsFromPoint; + Reflect.deleteProperty(window, "__hfAcceleratedCanvases"); + document.body.innerHTML = ""; + }); + + it("counts nothing for a plain composition", () => { + put(root, "div"); + put(root, "span"); + const fp = fingerprintOf(root); + expect(Object.values(fp).every((n) => n === 0)).toBe(true); + expect(Object.keys(fp)).toEqual([...MOTION_BLUR_FINGERPRINT_FIELDS]); + }); + + it("splits canvases into 2d and WebGL, anywhere in the document", () => { + put(root, "canvas"); + const gl = put(root, "canvas"); + const overlay = put(document.body, "canvas"); + Object.defineProperty(window, "__hfAcceleratedCanvases", { + value: new WeakSet([gl, overlay]), + configurable: true, + }); + expect(fingerprintOf(root)).toMatchObject({ canvas2d: 1, webgl: 2 }); + }); + + it("counts videos, frames and custom elements", () => { + put(root, "video"); + put(root, "video"); + put(root, "iframe"); + put(root, "x-card"); + put(root, "my-widget"); + put(root, "section"); + expect(fingerprintOf(root)).toMatchObject({ video: 2, iframe: 1, customElement: 2 }); + }); + + it("counts elements clipped by an SVG clip-path, not by a shape", () => { + put(root, "div", { clipPath: "url(#c)" }); + put(root, "div", { clipPath: "circle(40%)" }); + put(root, "div"); + expect(fingerprintOf(root).svgClip).toBe(1); + }); + + it("counts an element once for mask-image or the mask shorthand", () => { + put(root, "div", { maskImage: "url(a.png)" }); + put(root, "div", { mask: "url(b.svg) center / cover" }); + put(root, "div", { maskImage: "url(c.png)", mask: "url(c.png)" }); + put(root, "div", { maskImage: "none" }); + expect(fingerprintOf(root).mask).toBe(3); + }); + + it("counts a scroll container only when its content overflows", () => { + lay(put(root, "div", { overflowY: "auto" }), { scroll: [100, 400, 100, 200] }); + lay(put(root, "div", { overflowX: "scroll" }), { scroll: [500, 50, 100, 50] }); + lay(put(root, "div", { overflowY: "auto" }), { scroll: [100, 200, 100, 200] }); + lay(put(root, "div", { overflowY: "hidden" }), { scroll: [100, 400, 100, 200] }); + lay(put(root, "div"), { scroll: [100, 400, 100, 200] }); + expect(fingerprintOf(root).scrollContainer).toBe(2); + }); + + it("counts 3D contexts: preserve-3d and perspective", () => { + put(root, "div", { transformStyle: "preserve-3d" }); + put(root, "div", { perspective: "800px" }); + put(root, "div", { perspective: "none" }); + expect(fingerprintOf(root).threeD).toBe(2); + }); + + it("counts blend modes, and a mover's backdrop-filter once", () => { + put(root, "div", { mixBlendMode: "multiply" }); + const glass = put(root, "div", { backdropFilter: "blur(8px)" }); + const both = put(root, "div", { backdropFilter: "blur(8px)", mixBlendMode: "screen" }); + put(root, "div", { backdropFilter: "blur(8px)" }); + expect(fingerprintOf(root, [glass, both]).blendMode).toBe(3); + }); + + it("counts movers whose content reaches past their box", () => { + const wide = put(root, "div"); + lay(wide, { box: [0, 0, 100, 20], offset: [100, 20], scroll: [300, 20, 100, 20] }); + const spilling = put(root, "div"); + lay(spilling, { box: [0, 0, 100, 20], offset: [100, 20] }); + lay(put(spilling, "span"), { box: [90, 0, 200, 20] }); + const clipped = put(root, "div", { overflowX: "hidden", overflowY: "hidden" }); + lay(clipped, { box: [0, 0, 100, 20], offset: [100, 20], scroll: [300, 20, 100, 20] }); + const tidy = put(root, "div"); + lay(tidy, { box: [0, 0, 100, 20], offset: [100, 20] }); + lay(put(tidy, "span"), { box: [10, 0, 60, 20] }); + expect(fingerprintOf(root, [wide, spilling, clipped, tidy]).overflowingMover).toBe(2); + }); + + it("counts a mover whose text range runs past its box", () => { + const label = put(root, "div"); + lay(label, { box: [0, 0, 100, 20], offset: [100, 20] }); + (Range.prototype as unknown as Record).getBoundingClientRect = () => + rectOf([0, 0, 260, 20]); + expect(fingerprintOf(root, [label]).overflowingMover).toBe(1); + }); + + describe("frontOfMover", () => { + function scene() { + const mover = put(root, "div"); + lay(mover, { box: [100, 50, 300, 150] }); + const child = put(mover, "span"); + const cover = put(root, "div"); + const sampler = coverageSampler(root); + const fast = new Set([mover]); + const count = () => fingerprintOf(root, [mover], sampler.covered).frontOfMover; + return { mover, child, cover, sampler, fast, count }; + } + const stack = (...els: Element[]) => vi.fn(() => els); + + it("asks what is stacked at the mover's centre, in client coordinates, every tenth step", () => { + const { mover, cover, sampler, fast, count } = scene(); + const spy = stack(cover, mover, root); + doc.elementsFromPoint = spy; + sampler.sample(5, 240, fast); + expect(spy).not.toHaveBeenCalled(); + sampler.sample(10, 240, fast); + expect(spy).toHaveBeenCalledWith(200, 100); + expect(count()).toBe(1); + }); + + it("samples a short scan every other step, so a 30-step scan is tested at 16 steps", () => { + const { mover, sampler, fast } = scene(); + const spy = stack(mover, root); + doc.elementsFromPoint = spy; + for (let step = 0; step <= 30; step++) sampler.sample(step, 30, fast); + expect(spy).toHaveBeenCalledTimes(16); + }); + + it("counts a mover that is covered only at a later step, not where the scan ends", () => { + const { mover, cover, sampler, fast, count } = scene(); + let step = 0; + doc.elementsFromPoint = vi.fn(() => (step === 30 ? [cover, mover, root] : [mover, root])); + for (step = 0; step <= 60; step += 10) sampler.sample(step, 240, fast); + expect(count()).toBe(1); + }); + + it("does not count a mover that is covered at no step", () => { + const { mover, child, sampler, fast, count } = scene(); + doc.elementsFromPoint = stack(child, mover, root); + for (let step = 0; step <= 60; step += 10) sampler.sample(step, 240, fast); + expect(count()).toBe(0); + }); + + it("does not count what lies beneath the mover, nor the tier's own canvases", () => { + const { mover, sampler, fast, count } = scene(); + const own = put(document.body, "canvas"); + own.setAttribute("data-hf-motion-blur", "out"); + doc.elementsFromPoint = stack(own, mover, root, document.body); + sampler.sample(0, 240, fast); + expect(count()).toBe(0); + }); + + it("does not count a mover that cannot be located in the stack, or a click-through mover", () => { + const { mover, cover, sampler, fast, count } = scene(); + doc.elementsFromPoint = stack(cover, root); + sampler.sample(0, 240, fast); + expect(count()).toBe(0); + styles.set(mover, { pointerEvents: "none" }); + doc.elementsFromPoint = stack(cover, mover, root); + sampler.sample(0, 240, fast); + expect(count()).toBe(0); + }); + + it("stops testing a mover once it is counted", () => { + const { mover, cover, sampler, fast } = scene(); + const spy = stack(cover, mover, root); + doc.elementsFromPoint = spy; + for (let step = 0; step <= 60; step += 10) sampler.sample(step, 240, fast); + expect(spy).toHaveBeenCalledTimes(1); + }); + + it("counts nothing where the browser has no hit testing", () => { + const { sampler, fast, count } = scene(); + doc.elementsFromPoint = undefined; + sampler.sample(0, 240, fast); + expect(count()).toBe(0); + }); + }); + + it("counts movers holding a fixed-position descendant", () => { + const holder = put(root, "div"); + put(put(holder, "div"), "div", { position: "fixed" }); + const plain = put(root, "div"); + put(plain, "div", { position: "absolute" }); + expect(fingerprintOf(root, [holder, plain]).fixedInMover).toBe(1); + }); + + it("counts movers whose ::before or ::after box leaves their own", () => { + const pseudo = (left: string) => ({ + content: '""', + position: "absolute", + left, + top: "0px", + width: "10px", + height: "10px", + }); + const out = put(root, "div"); + lay(out, { offset: [100, 20] }); + pseudos.set(out, { "::before": pseudo("-20px") }); + const trailing = put(root, "div"); + lay(trailing, { offset: [100, 20] }); + pseudos.set(trailing, { "::after": pseudo("95px") }); + const inside = put(root, "div"); + lay(inside, { offset: [100, 20] }); + pseudos.set(inside, { "::before": pseudo("10px") }); + expect(fingerprintOf(root, [out, trailing, inside]).pseudoOutside).toBe(2); + }); + + it("stops walking after a few thousand elements", () => { + for (let i = 0; i < 4200; i++) put(root, "div", { maskImage: "url(a.png)" }); + expect(fingerprintOf(root).mask).toBe(4096); + }); + + it("carries no names", () => { + root.id = "secret-root"; + root.className = "secret-class"; + const card = put(root, "div", { maskImage: "url(https://example.test/secret.png)" }); + card.id = "secret-card"; + card.className = "secret-card-class"; + card.textContent = "secret headline text"; + card.setAttribute("data-label", "secret-attribute"); + const canvas = put(root, "canvas"); + canvas.id = "secret-canvas"; + lay(card, { box: [0, 0, 10, 10] }); + const json = JSON.stringify(fingerprintOf(root, [card])); + for (const secret of ["secret", "example", "headline", "https"]) { + expect(json).not.toContain(secret); + } + const parsed: unknown = JSON.parse(json); + expect(Object.keys(parsed as object)).toEqual([...MOTION_BLUR_FINGERPRINT_FIELDS]); + expect(Object.values(parsed as object).every((n) => typeof n === "number")).toBe(true); + }); +}); diff --git a/packages/core/src/runtime/captureMotionBlur/fingerprint.ts b/packages/core/src/runtime/captureMotionBlur/fingerprint.ts new file mode 100644 index 0000000000..664f0fcc4d --- /dev/null +++ b/packages/core/src/runtime/captureMotionBlur/fingerprint.ts @@ -0,0 +1,133 @@ +import { + emptyMotionBlurFingerprint, + type MotionBlurFingerprint, + type MotionBlurFingerprintField, +} from "../../motionBlurFingerprint"; +import { isAcceleratedCanvas } from "../../pageMotionBlur"; +import { isHtmlElement } from "../domRealm"; +import { CONTENT_NODE_LIMIT, holdsFixedChild, pseudoBox, within } from "./frames"; + +const NODE_LIMIT = 4096; +const SCROLL_SLACK = 1; + +const isNone = (value: string | undefined): boolean => !value || value === "none"; + +function scrolls(overflow: string, scroll: number, client: number): boolean { + return (overflow === "auto" || overflow === "scroll") && scroll > client + SCROLL_SLACK; +} + +function tallyCanvases(root: HTMLElement, fp: MotionBlurFingerprint): void { + for (const canvas of root.ownerDocument.querySelectorAll("canvas")) { + if (isAcceleratedCanvas(canvas)) fp.webgl++; + else fp.canvas2d++; + } +} + +type ElementTest = readonly [ + MotionBlurFingerprintField, + (el: Element, cs: CSSStyleDeclaration) => boolean, +]; + +const ELEMENT_TESTS: readonly ElementTest[] = [ + ["video", (el) => el.localName === "video"], + ["iframe", (el) => el.localName === "iframe"], + ["customElement", (el) => isHtmlElement(el) && el.localName.includes("-")], + ["svgClip", (_, cs) => cs.clipPath.startsWith("url(")], + ["mask", (_, cs) => !isNone(cs.maskImage) || !isNone(cs.mask)], + [ + "scrollContainer", + (el, cs) => + scrolls(cs.overflowX, el.scrollWidth, el.clientWidth) || + scrolls(cs.overflowY, el.scrollHeight, el.clientHeight), + ], + ["threeD", (_, cs) => cs.transformStyle === "preserve-3d" || !isNone(cs.perspective)], + ["blendMode", (_, cs) => !!cs.mixBlendMode && cs.mixBlendMode !== "normal"], +]; + +function tallyElement(el: Element, fp: MotionBlurFingerprint): void { + const cs = getComputedStyle(el); + for (const [field, test] of ELEMENT_TESTS) if (test(el, cs)) fp[field]++; +} + +function pokesOut(el: HTMLElement): boolean { + const cs = getComputedStyle(el); + if (cs.overflowX !== "visible" && cs.overflowY !== "visible") return false; + if (el.scrollWidth > el.offsetWidth + SCROLL_SLACK) return true; + if (el.scrollHeight > el.offsetHeight + SCROLL_SLACK) return true; + const own = el.getBoundingClientRect(); + const outside = (r: DOMRect): boolean => r.width > 0 && r.height > 0 && !within(r, own); + const text = el.ownerDocument.createRange(); + text.selectNodeContents(el); + if (outside(text.getBoundingClientRect())) return true; + const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_ELEMENT); + for (let n = 0; n < CONTENT_NODE_LIMIT && walker.nextNode(); n++) { + if (outside((walker.currentNode as Element).getBoundingClientRect())) return true; + } + return false; +} + +function pseudoPokesOut(el: HTMLElement): boolean { + return (["::before", "::after"] as const).some((which) => { + const box = pseudoBox(el, which); + return ( + box !== null && + (box[0] < 0 || box[1] < 0 || box[2] > el.offsetWidth || box[3] > el.offsetHeight) + ); + }); +} + +const MAX_SAMPLES = 24; + +function coveredAtCentre(el: HTMLElement, root: HTMLElement): boolean { + if (typeof el.checkVisibility === "function" && !el.checkVisibility({ visibilityProperty: true })) + return false; + if (getComputedStyle(el).pointerEvents === "none") return false; + const box = el.getBoundingClientRect(); + if (!box.width || !box.height) return false; + const stack = el.ownerDocument.elementsFromPoint( + box.left + box.width / 2, + box.top + box.height / 2, + ); + const own = stack.findIndex((hit) => el.contains(hit)); + return stack.slice(0, Math.max(own, 0)).some((hit) => root.contains(hit)); +} + +export function coverageSampler(root: HTMLElement) { + const covered = new Set(); + const sample = (step: number, steps: number, fast: ReadonlySet): void => { + if ( + step % Math.ceil(steps / MAX_SAMPLES) !== 0 || + typeof root.ownerDocument.elementsFromPoint !== "function" + ) + return; + for (const el of fast) if (!covered.has(el) && coveredAtCentre(el, root)) covered.add(el); + }; + return { covered, sample }; +} + +function tallyMover(el: HTMLElement, fp: MotionBlurFingerprint): void { + const cs = getComputedStyle(el); + const backdrop = cs.backdropFilter || cs.getPropertyValue("-webkit-backdrop-filter"); + if (!isNone(backdrop) && (!cs.mixBlendMode || cs.mixBlendMode === "normal")) fp.blendMode++; + if (pokesOut(el)) fp.overflowingMover++; + if (holdsFixedChild(el)) fp.fixedInMover++; + if (pseudoPokesOut(el)) fp.pseudoOutside++; +} + +export function compositionFingerprint( + root: HTMLElement, + movers: readonly HTMLElement[], + covered: ReadonlySet = new Set(), +): MotionBlurFingerprint { + const fp = emptyMotionBlurFingerprint(); + tallyCanvases(root, fp); + const walker = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_ELEMENT); + for (let n = 0; n < NODE_LIMIT && walker.nextNode(); n++) { + tallyElement(walker.currentNode as Element, fp); + } + for (const mover of movers) { + tallyMover(mover, fp); + if (covered.has(mover)) fp.frontOfMover++; + } + return fp; +} diff --git a/packages/core/src/runtime/captureMotionBlur/frames.ts b/packages/core/src/runtime/captureMotionBlur/frames.ts index 052566e2ac..377ca33e2c 100644 --- a/packages/core/src/runtime/captureMotionBlur/frames.ts +++ b/packages/core/src/runtime/captureMotionBlur/frames.ts @@ -31,7 +31,7 @@ function clientToMover(pose: Affine, scene: HTMLElement, frameW: number): Affine const SUBPIXEL = 0.5; -const within = (r: DOMRect, o: DOMRect): boolean => +export const within = (r: DOMRect, o: DOMRect): boolean => r.left >= o.left - SUBPIXEL && r.top >= o.top - SUBPIXEL && r.right <= o.right + SUBPIXEL && @@ -53,10 +53,18 @@ function growToRect(box: Box, back: Affine, r: DOMRect): void { } } +export function holdsFixedChild(el: HTMLElement): boolean { + const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_ELEMENT); + for (let n = 0; n < CONTENT_NODE_LIMIT && walker.nextNode(); n++) { + if (getComputedStyle(walker.currentNode as Element).position === "fixed") return true; + } + return false; +} + const POSITIONED = new Set(["absolute", "fixed"]); const NO_CONTENT = new Set(["none", "normal"]); -function pseudoBox(el: HTMLElement, which: "::before" | "::after"): Box | null { +export function pseudoBox(el: HTMLElement, which: "::before" | "::after"): Box | null { const cs = getComputedStyle(el, which); if (NO_CONTENT.has(cs.content) || !POSITIONED.has(cs.position)) return null; const left = parseFloat(cs.left) + el.clientLeft; diff --git a/packages/core/src/runtime/captureMotionBlur/index.test.ts b/packages/core/src/runtime/captureMotionBlur/index.test.ts index 86b3d80045..174193cc5c 100644 --- a/packages/core/src/runtime/captureMotionBlur/index.test.ts +++ b/packages/core/src/runtime/captureMotionBlur/index.test.ts @@ -1642,6 +1642,23 @@ describe("probe", () => { expect(document.querySelector("canvas")).toBeNull(); }); + it.each(["capture", "filter"])("counts what the composition holds on the %s tier", (tier) => { + installHtmlInCanvas(); + if (tier === "filter") setFilterFallbackForTests(true); + const { root, h } = movingHost({ "data-motion-blur": "on", "data-motion-blur-tier": tier }); + root.append(document.createElement("video"), document.createElement("video")); + initCaptureMotionBlur(h); + expect(win.__hfMotionBlur?.report()).toMatchObject({ fingerprint: null, readEvents: false }); + expect(probe()).toMatchObject({ tier, fingerprint: { video: 2, webgl: 0 }, readEvents: false }); + }); + + it("carries no counts when blur stands down before any scan", () => { + win.__HF_PAGE_MOTION_BLUR_OFF__ = "hdr-render"; + const { h } = movingHost(); + initCaptureMotionBlur(h); + expect(probe()).toMatchObject({ state: "off", fingerprint: null, readEvents: false }); + }); + it("reports no movers for a composition where nothing moves", () => { installHtmlInCanvas(); initCaptureMotionBlur(host(makeRoot())); diff --git a/packages/core/src/runtime/captureMotionBlur/index.ts b/packages/core/src/runtime/captureMotionBlur/index.ts index 5255136ec7..fe423e1598 100644 --- a/packages/core/src/runtime/captureMotionBlur/index.ts +++ b/packages/core/src/runtime/captureMotionBlur/index.ts @@ -38,8 +38,10 @@ import { createCompositor, type MoverFrame } from "./composite"; import { readMotionBlurSettings } from "../../motionBlurSettings"; import { scanMovers, whileCallbacksMuted } from "./discover"; import { createFilterTier } from "./filterTier"; +import { compositionFingerprint, coverageSampler } from "./fingerprint"; import { readMoverFrames, shutterTimes } from "./frames"; import { createPoseReader } from "./pose"; +import type { MotionBlurFingerprint } from "../../motionBlurFingerprint"; import { type CaptureMotionBlurHost, type Config, @@ -193,6 +195,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI const timings: number[] = []; let sampleMs = 0; let scanMs = 0; + let fingerprint: MotionBlurFingerprint | null = null; let scannedTimeline: unknown = undefined; let scanDefect: CaptureDefect | null = null; let faceNow: () => boolean = () => false; @@ -256,6 +259,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI scannedTimeline = host.timeline(); const duration = host.durationSeconds(); const defects = createDefectScan(root, isAccelerated); + const coverage = coverageSampler(root); const s0 = performance.now(); const found = whileCallbacksMuted(host, config.events, () => { const scan = scanMovers({ @@ -265,6 +269,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI seek: host.seek, events: config.events, onStep: (i, steps) => defects.sample(i, steps, (i / steps) * duration), + onFast: coverage.sample, }); seek(restoreTo); return scan; @@ -274,6 +279,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI faceNow = defects.facesNow; movers = found.movers; pads = found.pads; + fingerprint = compositionFingerprint(root, movers, coverage.covered); reader = createPoseReader(root, found.dynamic); scanMs = Math.round(performance.now() - s0); } @@ -571,6 +577,8 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI meanMs: Math.round(mean * 10) / 10, failures, failedFrames, + fingerprint, + readEvents, }; } @@ -721,6 +729,8 @@ function offReport(config: Config, why: CaptureDefect | null): Report { meanMs: 0, failures: 0, failedFrames: 0, + fingerprint: null, + readEvents: false, }; } diff --git a/packages/core/src/runtime/captureMotionBlur/tier.ts b/packages/core/src/runtime/captureMotionBlur/tier.ts index 6a3ec44429..f04c73bc82 100644 --- a/packages/core/src/runtime/captureMotionBlur/tier.ts +++ b/packages/core/src/runtime/captureMotionBlur/tier.ts @@ -1,4 +1,5 @@ import type { CaptureDefect } from "../../htmlInCanvasDefects"; +import type { MotionBlurFingerprint } from "../../motionBlurFingerprint"; /** What the runtime drives: capture blur or the filter fallback, the same way. */ @@ -40,6 +41,8 @@ export interface Report { meanMs: number; failures: number; failedFrames: number; + fingerprint: MotionBlurFingerprint | null; + readEvents: boolean; } export interface Tier { diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts index 5ce57fada3..0d315fce12 100644 --- a/packages/engine/src/index.ts +++ b/packages/engine/src/index.ts @@ -362,7 +362,7 @@ export { frameFileExtension } from "./services/frameCapture.js"; export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThreads.js"; export { frameSequencePath } from "./services/extractedFrameIndex.js"; export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js"; -export type { PageMotionBlurOff } from "./types.js"; +export type { PageMotionBlurOff, PageMotionBlurSummary } from "./types.js"; export { assertSwiftShader, diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index 5786aaf333..6594f002ff 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -53,6 +53,7 @@ import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, + pageMotionBlurRecorder, } from "./pageMotionBlur.js"; // ── Extracted modules ─────────────────────────────────────────────────────── @@ -114,6 +115,7 @@ import type { CapturePerfSummary, CaptureWarning, HfSeekOptions, + PageMotionBlurSummary, SubTimelineWaitMemo, SubTimelineWaitOutcome, } from "../types.js"; @@ -179,6 +181,7 @@ export interface CaptureSession { lastFrameAbsoluteIndex?: number; /** Count of frames served from a reused buffer (dedup telemetry). */ staticDedupCount?: number; + pageMotionBlur?: PageMotionBlurSummary; /** Live Chrome memory sampler; started in initializeSession, stopped in closeCaptureSession. */ chromeMemory?: ChromeMemorySampler; /** @@ -4964,7 +4967,10 @@ async function captureFrameCore( session.capturePerf.totalMs += captureTimeMs; session.capturePerf.frameMs.push(captureTimeMs); if (session.capturePerf.frames === 1) { - const blur = await describePageMotionBlur(session.page).catch(() => null); + const blur = await describePageMotionBlur( + session.page, + pageMotionBlurRecorder(session), + ).catch(() => null); if (blur) console.error(blur); } @@ -5415,7 +5421,11 @@ export async function closeCaptureSession(session: CaptureSession): Promise ({ evaluateOnNewDocument: vi.fn(async () => ({ identifier: "1" })) }); @@ -118,6 +120,112 @@ describe("describePageMotionBlur", () => { vi.stubGlobal("window", {}); expect(await describePageMotionBlur(inPage)).toBeNull(); }); + + const counts = (over: Record) => ({ + canvas2d: 0, + webgl: 0, + video: 0, + iframe: 0, + customElement: 0, + svgClip: 0, + mask: 0, + scrollContainer: 0, + threeD: 0, + overflowingMover: 0, + frontOfMover: 0, + blendMode: 0, + fixedInMover: 0, + pseudoOutside: 0, + ...over, + }); + + it("lists what the composition holds, non-zero counts only, in the type's order", async () => { + vi.stubGlobal("window", { + __hfMotionBlur: { + report: () => ({ + state: "on", + tier: "filter", + reasonCode: "accelerated-canvas", + movers: 2, + readEvents: true, + fingerprint: counts({ video: 2, webgl: 1 }), + }), + }, + }); + expect(await describePageMotionBlur(inPage)).toBe( + "[motion-blur] on reasonCode=accelerated-canvas movers=2 failedFrames=0 tier=filter readEvents=true fp=webgl:1,video:2", + ); + }); + + it("leaves the line as it was when every count is zero and no events are read", async () => { + vi.stubGlobal("window", { + __hfMotionBlur: { + report: () => ({ + state: "on", + reasonCode: null, + movers: 1, + readEvents: false, + fingerprint: counts({}), + }), + }, + }); + expect(await describePageMotionBlur(inPage)).toBe( + "[motion-blur] on reasonCode=null movers=1 failedFrames=0", + ); + }); + + it("keeps only the known counts, as numbers, from whatever the page returns", async () => { + const seen: PageMotionBlurSummary[] = []; + vi.stubGlobal("window", { + __hfMotionBlur: { + report: () => ({ + state: "on", + tier: "capture", + reasonCode: null, + movers: 1, + fingerprint: { ...counts({ mask: 3 }), id: "secret", video: "many" }, + }), + }, + }); + await describePageMotionBlur(inPage, (summary) => seen.push(summary)); + expect(seen).toEqual([ + { + tier: "capture", + reasonCode: null, + movers: 1, + failedFrames: 0, + readEvents: false, + fingerprint: counts({ mask: 3 }), + }, + ]); + }); +}); + +describe("pageMotionBlurRecorder", () => { + const read = (over: Partial): PageMotionBlurSummary => ({ + tier: "filter", + reasonCode: null, + movers: 2, + failedFrames: 0, + readEvents: false, + fingerprint: null, + ...over, + }); + + it("updates one object in place and keeps the tier and counts a later read lacks", () => { + const session: { pageMotionBlur?: PageMotionBlurSummary } = {}; + const record = pageMotionBlurRecorder(session); + record(read({ fingerprint: { webgl: 1 } as never })); + const held = session.pageMotionBlur; + record(read({ tier: null, failedFrames: 3, reasonCode: "capture-failures" })); + expect(session.pageMotionBlur).toBe(held); + expect(held).toMatchObject({ + tier: "filter", + failedFrames: 3, + reasonCode: "capture-failures", + fingerprint: { webgl: 1 }, + }); + }); }); describe("describePageMotionBlurAtEnd", () => { @@ -192,4 +300,47 @@ describe("closeCaptureSession", () => { expect(stdout).not.toHaveBeenCalled(); vi.unstubAllGlobals(); }); + + it("writes the session's final failed frames into the summary a perf harvest already holds", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + vi.stubGlobal("window", { + __hfMotionBlur: { + report: () => ({ + state: "off", + reasonCode: "capture-failures", + movers: 2, + failedFrames: 5, + }), + }, + }); + const session = { + page: { evaluate: async (fn: () => unknown) => fn(), close: async () => {} }, + pageReleased: false, + browserReleased: true, + staticDedupCount: 0, + pageMotionBlur: { + tier: "capture", + reasonCode: null, + movers: 2, + failedFrames: 0, + readEvents: false, + fingerprint: null, + } as PageMotionBlurSummary, + options: {}, + warnings: [], + capturePerf: { + frames: 1, + seekMs: 0, + beforeCaptureMs: 0, + screenshotMs: 0, + totalMs: 0, + frameMs: [], + }, + }; + const harvested = getCapturePerfSummary(session as never); + expect(harvested.motionBlur?.failedFrames).toBe(0); + await closeCaptureSession(session as never); + expect(harvested.motionBlur).toMatchObject({ tier: "capture", failedFrames: 5 }); + vi.unstubAllGlobals(); + }); }); diff --git a/packages/engine/src/services/pageMotionBlur.ts b/packages/engine/src/services/pageMotionBlur.ts index d3255e2f80..5e04333f6f 100644 --- a/packages/engine/src/services/pageMotionBlur.ts +++ b/packages/engine/src/services/pageMotionBlur.ts @@ -5,12 +5,14 @@ */ import { + MOTION_BLUR_FINGERPRINT_FIELDS, PAGE_DEVICE_SCALE_GLOBAL, PAGE_MOTION_BLUR_OFF_GLOBAL, acceleratedCanvasTrackerSource, + type MotionBlurFingerprint, } from "@hyperframes/core"; import type { Page } from "puppeteer-core"; -import type { CaptureOptions } from "../types.js"; +import type { CaptureOptions, PageMotionBlurSummary } from "../types.js"; function pageOffReason( options: Pick, @@ -48,37 +50,95 @@ export async function installPageMotionBlur( interface PageMotionBlurState { state: string; - code: string; + reasonCode: string | null; movers: number; failedFrames: number; tier: string | null; + readEvents: boolean; + fingerprint: MotionBlurFingerprint | null; +} + +function parseFingerprint(raw: unknown): MotionBlurFingerprint | null { + if (!raw || typeof raw !== "object") return null; + const count = (field: string): number => Number(Reflect.get(raw, field)) || 0; + return Object.fromEntries( + MOTION_BLUR_FINGERPRINT_FIELDS.map((field) => [field, count(field)]), + ) as MotionBlurFingerprint; } async function readPageMotionBlur( page: Pick, ): Promise { - return page.evaluate(() => { + const read = await 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; const tier: unknown = Reflect.get(got, "tier"); + const reasonCode: unknown = Reflect.get(got, "reasonCode"); return { state: String(Reflect.get(got, "state")), - code: String(Reflect.get(got, "reasonCode")), + reasonCode: typeof reasonCode === "string" ? reasonCode : null, movers: Number(Reflect.get(got, "movers")), failedFrames: Number(Reflect.get(got, "failedFrames")) || 0, tier: typeof tier === "string" ? tier : null, + readEvents: Reflect.get(got, "readEvents") === true, + fingerprint: Reflect.get(got, "fingerprint") as unknown, }; }); + return read && { ...read, fingerprint: parseFingerprint(read.fingerprint) }; } -const formatPageMotionBlur = (r: PageMotionBlurState): string => - `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}${r.tier ? ` tier=${r.tier}` : ""}`; +function fingerprintCounts(fingerprint: MotionBlurFingerprint | null): string { + if (!fingerprint) return ""; + return MOTION_BLUR_FINGERPRINT_FIELDS.filter((field) => fingerprint[field] > 0) + .map((field) => `${field}:${fingerprint[field]}`) + .join(","); +} + +const formatPageMotionBlur = (r: PageMotionBlurState): string => { + const counts = fingerprintCounts(r.fingerprint); + return ( + `[motion-blur] ${r.state} reasonCode=${r.reasonCode} movers=${r.movers} failedFrames=${r.failedFrames}` + + `${r.tier ? ` tier=${r.tier}` : ""}${r.readEvents ? " readEvents=true" : ""}${counts ? ` fp=${counts}` : ""}` + ); +}; + +const summarize = (r: PageMotionBlurState): PageMotionBlurSummary => ({ + tier: r.tier === "capture" || r.tier === "filter" ? r.tier : null, + reasonCode: r.reasonCode, + movers: r.movers, + failedFrames: r.failedFrames, + readEvents: r.readEvents, + fingerprint: r.fingerprint, +}); + +export type RecordPageMotionBlur = (summary: PageMotionBlurSummary) => void; + +/** Keeps one summary object per session, updated in place, so a perf summary that holds it sees the session's last read. */ +export function pageMotionBlurRecorder(session: { + pageMotionBlur?: PageMotionBlurSummary; +}): RecordPageMotionBlur { + return (next) => { + const held = session.pageMotionBlur; + if (!held) { + session.pageMotionBlur = next; + return; + } + Object.assign(held, next, { + tier: next.tier ?? held.tier, + fingerprint: next.fingerprint ?? held.fingerprint, + }); + }; +} /** 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): Promise { +export async function describePageMotionBlur( + page: Pick, + record?: RecordPageMotionBlur, +): Promise { const r = await readPageMotionBlur(page); + if (r) record?.(summarize(r)); return r && formatPageMotionBlur(r); } @@ -86,6 +146,7 @@ export async function describePageMotionBlur(page: Pick): Prom export async function describePageMotionBlurAtEnd( page: Pick, timeoutMs = 1500, + record?: RecordPageMotionBlur, ): Promise { let timer: ReturnType | undefined; const stuck = new Promise((resolve) => { @@ -93,6 +154,7 @@ export async function describePageMotionBlurAtEnd( }); try { const r = await Promise.race([readPageMotionBlur(page), stuck]); + if (r) record?.(summarize(r)); return r && r.failedFrames > 0 ? `${formatPageMotionBlur(r)} (session end)` : null; } catch { return null; diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts index 85dca3920a..bf61deae56 100644 --- a/packages/engine/src/types.ts +++ b/packages/engine/src/types.ts @@ -6,13 +6,22 @@ */ import type { ReferenceBackground } from "./services/referenceBackground.js"; import type { AudioFailureDiagnostic } from "./services/audioMixer.types.js"; -import type { Fps } from "@hyperframes/core"; +import type { Fps, MotionBlurFingerprint } from "@hyperframes/core"; import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length"; import type { ChromeMemoryStats } from "./services/chromeMemorySampler.js"; import type { MotionBlurOptions } from "./services/motionBlur.js"; export type PageMotionBlurOff = "off" | "hdr-render" | "layered-composite" | "distributed-render"; +export interface PageMotionBlurSummary { + tier: "capture" | "filter" | null; + reasonCode: string | null; + movers: number; + failedFrames: number; + readEvents: boolean; + fingerprint: MotionBlurFingerprint | null; +} + /** * Outcome of waiting for a sub-composition's GSAP timelines to register. * Threaded string-typed through `CapturePerfSummary` / `RenderPerfSummary` / @@ -410,6 +419,7 @@ export interface CapturePerfSummary { * drawElement ran or was never attempted. */ deGateReason?: string; + motionBlur?: PageMotionBlurSummary; /** * Full-fidelity fallback trigger — the specific reason (CSS FX + property, * e.g. `filter:blur`, `filter:drop-shadow`, `backdrop-filter`, `clip-path`, diff --git a/packages/producer/src/services/render/perfSummary-motionBlur.test.ts b/packages/producer/src/services/render/perfSummary-motionBlur.test.ts new file mode 100644 index 0000000000..76a1bed688 --- /dev/null +++ b/packages/producer/src/services/render/perfSummary-motionBlur.test.ts @@ -0,0 +1,110 @@ +import { describe, it, expect } from "vitest"; +import type { CapturePerfSummary, PageMotionBlurSummary } from "@hyperframes/engine"; +import { buildRenderPerfSummary } from "./perfSummary.js"; +import { createRenderJob } from "../renderOrchestrator.js"; + +function summaryOf(dedupPerfs: CapturePerfSummary[]) { + return buildRenderPerfSummary({ + job: createRenderJob({ fps: { num: 30, den: 1 }, quality: "high" }), + workerCount: dedupPerfs.length || 1, + enableChunkedEncode: false, + chunkedEncodeSize: 0, + compositionDurationSeconds: 5, + totalFrames: 150, + outputWidth: 1920, + outputHeight: 1080, + videoCount: 0, + audioCount: 0, + totalElapsedMs: 1000, + perfStages: {}, + videoExtractBreakdown: undefined, + tmpPeakBytes: 0, + captureAttempts: [], + hdrDiagnostics: { videoExtractionFailures: 0, imageDecodeFailures: 0 }, + peakRssBytes: 0, + peakHeapUsedBytes: 0, + dedupPerfs, + gpuDisabled: false, + }); +} + +const worker = (motionBlur?: Partial): CapturePerfSummary => ({ + frames: 10, + avgTotalMs: 1, + avgSeekMs: 1, + avgBeforeCaptureMs: 0, + avgScreenshotMs: 0, + staticDedupReused: 0, + staticDedupEnabled: false, + staticDedupArmed: false, + staticDedupPredicted: 0, + motionBlur: motionBlur && { + tier: "capture", + reasonCode: null, + movers: 2, + failedFrames: 0, + readEvents: false, + fingerprint: null, + ...motionBlur, + }, +}); + +const counts = (over: Partial>) => ({ + canvas2d: 0, + webgl: 0, + video: 0, + iframe: 0, + customElement: 0, + svgClip: 0, + mask: 0, + scrollContainer: 0, + threeD: 0, + overflowingMover: 0, + frontOfMover: 0, + blendMode: 0, + fixedInMover: 0, + pseudoOutside: 0, + ...over, +}); + +describe("aggregateMotionBlur", () => { + it("is undefined when blur never ran in a session", () => { + expect(summaryOf([worker(), worker({ tier: null, movers: 0 })]).motionBlur).toBeUndefined(); + }); + + it("sums failed frames across workers and takes the rest from the first that reported", () => { + const summary = summaryOf([ + worker({ failedFrames: 4, movers: 3, fingerprint: counts({ webgl: 1 }) }), + worker({ failedFrames: 2, readEvents: true, fingerprint: counts({ video: 2 }) }), + ]); + expect(summary.motionBlur).toEqual({ + tier: "capture", + reasonCode: null, + movers: 3, + failedFrames: 6, + readEvents: true, + fingerprint: counts({ webgl: 1 }), + }); + }); + + it("skips workers that reported nothing, and keeps a fingerprint a first worker lacked", () => { + const summary = summaryOf([ + worker(), + worker({ tier: "filter", reasonCode: "accelerated-canvas" }), + worker({ tier: "filter", failedFrames: 1, fingerprint: counts({ mask: 5 }) }), + ]); + expect(summary.motionBlur).toMatchObject({ + tier: "filter", + reasonCode: "accelerated-canvas", + failedFrames: 1, + fingerprint: counts({ mask: 5 }), + }); + }); + + it("reports failed frames from a session whose blur ended before it named a tier", () => { + const summary = summaryOf([ + worker({ tier: null, failedFrames: 3, reasonCode: "capture-failures" }), + ]); + expect(summary.motionBlur).toMatchObject({ tier: null, failedFrames: 3 }); + }); +}); diff --git a/packages/producer/src/services/render/perfSummary.ts b/packages/producer/src/services/render/perfSummary.ts index 7e7e6b0dfb..688caa2429 100644 --- a/packages/producer/src/services/render/perfSummary.ts +++ b/packages/producer/src/services/render/perfSummary.ts @@ -349,6 +349,21 @@ function aggregateBeginFrameReuse( return { noDamageFrames, hasDamageFrames }; } +/** The page's blur outcome across sessions: first reported value wins, failed frames sum. */ +function aggregateMotionBlur(perfs: CapturePerfSummary[]): RenderPerfSummary["motionBlur"] { + const ran = perfs.flatMap((p) => p.motionBlur ?? []).filter((m) => m.tier || m.failedFrames > 0); + const first = ran[0]; + if (!first) return undefined; + return { + tier: first.tier ?? ran.find((m) => m.tier)?.tier ?? null, + reasonCode: first.reasonCode, + movers: first.movers, + failedFrames: ran.reduce((sum, m) => sum + m.failedFrames, 0), + readEvents: ran.some((m) => m.readEvents), + fingerprint: ran.find((m) => m.fingerprint)?.fingerprint ?? null, + }; +} + export function buildRenderPerfSummary(input: { job: RenderJob; workerCount: number; @@ -446,6 +461,7 @@ export function buildRenderPerfSummary(input: { staticDedup: aggregateDedup(input.dedupPerfs), chromeMemory: aggregateChromeMemory(input.dedupPerfs), beginFrameReuse: aggregateBeginFrameReuse(input.dedupPerfs), + motionBlur: aggregateMotionBlur(input.dedupPerfs), drawElement: aggregateDrawElement( input.dedupPerfs, input.drawElement ?? { selfVerifyFallback: false }, diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 94349c15a5..c18219a6b7 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -109,6 +109,7 @@ import { augmentPageNavigationTimeoutError, displaySize, type MotionBlurOptions, + type PageMotionBlurSummary, } from "@hyperframes/engine"; import { referenceBackgroundResult, @@ -623,6 +624,7 @@ export interface RenderPerfSummary { noDamageFrames: number; hasDamageFrames: number; }; + motionBlur?: PageMotionBlurSummary; /** * drawElement fast-capture outcome for this render (default-on release * visibility). Undefined when no capture session ran. diff --git a/scripts/package-size-budgets.json b/scripts/package-size-budgets.json index 15e6df0e6f..3d8cbd513f 100644 --- a/scripts/package-size-budgets.json +++ b/scripts/package-size-budgets.json @@ -21,7 +21,7 @@ }, "@hyperframes/inspector": { "packed": 858046, - "unpacked": 3645432 + "unpacked": 3684092 }, "@hyperframes/lint": { "packed": 191022,