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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-11-06 15:03:34 +00:00
committed by GitHub
co-authored by Claude Sonnet 5.5
parent 4cf26b5b49
commit a874a6324a
26 changed files with 1139 additions and 28 deletions
+2 -1
View File
@@ -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
+2
View File
@@ -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,
@@ -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),
};
}
+7 -1
View File
@@ -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,
@@ -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<typeof import("./system.js")>("./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<NonNullable<PageMotionBlurSummary["fingerprint"]>>) => ({
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> = {}): 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<string, unknown>;
};
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<typeof fingerprint>;
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",
]);
});
});
@@ -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<string, string | number | undefined> {
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),
};
}
+5
View File
@@ -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";
@@ -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<MotionBlurFingerprintField, number>;
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,
};
}
@@ -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");
@@ -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<HTMLElement>) => void;
onStepBoxes?: (i: number, boxes: ReadonlyArray<DOMRect | undefined>) => 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);
},
@@ -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,
};
}
@@ -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<string, string>;
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<Element, Style>();
const pseudos = new WeakMap<Element, Record<string, Style>>();
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<string, unknown>)[k]);
const doc = document as unknown as { elementsFromPoint?: unknown };
const realElementsFromPoint = doc.elementsFromPoint;
function fingerprintOf(
root: HTMLElement,
movers: HTMLElement[] = [],
covered: ReadonlySet<HTMLElement> = 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<string, unknown>;
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<string, unknown>)[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<string, unknown>).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);
});
});
@@ -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<HTMLElement>();
const sample = (step: number, steps: number, fast: ReadonlySet<HTMLElement>): 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<HTMLElement> = 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;
}
@@ -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;
@@ -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()));
@@ -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,
};
}
@@ -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 {
+1 -1
View File
@@ -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,
+13 -2
View File
@@ -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<void
await waitForCloseWithTimeout(session.chromeMemory.sampleOnce());
}
if (session.page && !session.pageReleased) {
const blur = await describePageMotionBlurAtEnd(session.page);
const blur = await describePageMotionBlurAtEnd(
session.page,
undefined,
pageMotionBlurRecorder(session),
);
if (blur) console.error(blur);
}
// Realized static-dedup telemetry: how much the cache actually helped this
@@ -5758,6 +5768,7 @@ export function getCapturePerfSummary(session: CaptureSession): CapturePerfSumma
chromeGpuProcessSeenLastSample: session.chromeMemory?.stats().gpuProcessSeenLastSample,
chromeMemorySamples: session.chromeMemory?.stats().samples,
deGateReason: session.deGateReason,
motionBlur: session.pageMotionBlur,
deFallbackTrigger: session.deFallbackTrigger,
deWorkerEncode: session.workerEncodeEnabled ?? false,
deVerifyArmed: session.deVerifyFrames?.size ?? 0,
@@ -8,8 +8,10 @@ import {
describePageMotionBlur,
describePageMotionBlurAtEnd,
installPageMotionBlur,
pageMotionBlurRecorder,
} from "./pageMotionBlur";
import { closeCaptureSession } from "./frameCapture";
import { closeCaptureSession, getCapturePerfSummary } from "./frameCapture";
import type { PageMotionBlurSummary } from "../types";
const fakePage = () => ({ evaluateOnNewDocument: vi.fn(async () => ({ identifier: "1" })) });
@@ -118,6 +120,112 @@ describe("describePageMotionBlur", () => {
vi.stubGlobal("window", {});
expect(await describePageMotionBlur(inPage)).toBeNull();
});
const counts = (over: Record<string, number>) => ({
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>): 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();
});
});
+69 -7
View File
@@ -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<CaptureOptions, "motionBlur" | "pageMotionBlur">,
@@ -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<Page, "evaluate">,
): Promise<PageMotionBlurState | null> {
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<Page, "evaluate">): Promise<string | null> {
export async function describePageMotionBlur(
page: Pick<Page, "evaluate">,
record?: RecordPageMotionBlur,
): Promise<string | null> {
const r = await readPageMotionBlur(page);
if (r) record?.(summarize(r));
return r && formatPageMotionBlur(r);
}
@@ -86,6 +146,7 @@ export async function describePageMotionBlur(page: Pick<Page, "evaluate">): Prom
export async function describePageMotionBlurAtEnd(
page: Pick<Page, "evaluate">,
timeoutMs = 1500,
record?: RecordPageMotionBlur,
): Promise<string | null> {
let timer: ReturnType<typeof setTimeout> | undefined;
const stuck = new Promise<null>((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;
+11 -1
View File
@@ -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`,
@@ -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<PageMotionBlurSummary>): 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<NonNullable<PageMotionBlurSummary["fingerprint"]>>) => ({
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 });
});
});
@@ -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 },
@@ -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.
+1 -1
View File
@@ -21,7 +21,7 @@
},
"@hyperframes/inspector": {
"packed": 858046,
"unpacked": 3645432
"unpacked": 3684092
},
"@hyperframes/lint": {
"packed": 191022,