From a874a6324a5e3dec18ebfea426071f87a7f21373 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Fri, 6 Nov 2026 15:03:34 +0000 Subject: [PATCH] feat(core): motion blur reports what a composition holds, as counts (#7306) * feat(core): motion blur reports what a composition holds, as counts The runtime scans a composition once per blur scan, on both tiers, and reports counts of what it holds (canvases, video, frames, custom elements, clips, masks, scroll containers, 3D, blend modes, and movers that overflow, sit under other content, hold fixed children or carry pseudo-elements outside their box), plus whether pose reads need callbacks. Counts only: no ids, classes, text or URLs. The engine puts the non-zero counts on its [motion-blur] line and hands the parsed report to the perf summary; the producer aggregates workers (first report wins, failed frames sum) and the CLI sends motion_blur_* properties on render_complete, from the CLI and from Studio renders. Co-Authored-By: Claude Sonnet 5.5 * fix(cli): disclose blur counts in telemetry docs, raise inspector budget The runtime fingerprint code is bundled into @hyperframes/inspector, which puts its unpacked size 2.2 KB past the 1% tolerance. The telemetry docs now list the composition counts the CLI sends with a blur render. Co-Authored-By: Claude Sonnet 5.5 --------- Co-authored-by: Claude Sonnet 5.5 --- docs/packages/cli.mdx | 3 +- packages/cli/src/commands/render.ts | 2 + .../cli/src/server/studioRenderTelemetry.ts | 2 + packages/cli/src/telemetry/events.ts | 8 +- .../src/telemetry/renderMotionBlur.test.ts | 128 +++++++ .../cli/src/telemetry/renderMotionBlur.ts | 38 +++ packages/core/src/index.ts | 5 + packages/core/src/motionBlurFingerprint.ts | 39 +++ .../captureMotionBlur/discover.test.ts | 30 +- .../src/runtime/captureMotionBlur/discover.ts | 9 +- .../runtime/captureMotionBlur/filterTier.ts | 18 +- .../captureMotionBlur/fingerprint.test.ts | 322 ++++++++++++++++++ .../runtime/captureMotionBlur/fingerprint.ts | 133 ++++++++ .../src/runtime/captureMotionBlur/frames.ts | 12 +- .../runtime/captureMotionBlur/index.test.ts | 17 + .../src/runtime/captureMotionBlur/index.ts | 10 + .../src/runtime/captureMotionBlur/tier.ts | 3 + packages/engine/src/index.ts | 2 +- packages/engine/src/services/frameCapture.ts | 15 +- .../src/services/pageMotionBlur.test.ts | 153 ++++++++- .../engine/src/services/pageMotionBlur.ts | 76 ++++- packages/engine/src/types.ts | 12 +- .../render/perfSummary-motionBlur.test.ts | 110 ++++++ .../src/services/render/perfSummary.ts | 16 + .../src/services/renderOrchestrator.ts | 2 + scripts/package-size-budgets.json | 2 +- 26 files changed, 1139 insertions(+), 28 deletions(-) create mode 100644 packages/cli/src/telemetry/renderMotionBlur.test.ts create mode 100644 packages/cli/src/telemetry/renderMotionBlur.ts create mode 100644 packages/core/src/motionBlurFingerprint.ts create mode 100644 packages/core/src/runtime/captureMotionBlur/fingerprint.test.ts create mode 100644 packages/core/src/runtime/captureMotionBlur/fingerprint.ts create mode 100644 packages/producer/src/services/render/perfSummary-motionBlur.test.ts 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,