Skip to content

Commit 6ae6059

Browse files
vanceingallsclaude
andcommitted
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 <[email protected]>
1 parent 41b7aee commit 6ae6059

24 files changed

Lines changed: 1136 additions & 26 deletions

‎packages/cli/src/commands/render.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@ import {
9393
type RenderEnvironmentTelemetryPayload,
9494
} from "../telemetry/events.js";
9595
import { maybePromptRenderFeedback } from "../telemetry/feedback.js";
96+
import { renderMotionBlurTelemetryPayload } from "../telemetry/renderMotionBlur.js";
9697
import {
9798
readConfigFresh,
9899
releaseDeParallelRouterLatch,
@@ -1991,6 +1992,7 @@ function trackRenderMetrics(
19911992
catalogUsage: options.catalogUsage,
19921993
...renderOutputShapeTelemetryPayload(options),
19931994
...renderEnvironmentTelemetryPayload(options),
1995+
...renderMotionBlurTelemetryPayload(perf?.motionBlur),
19941996
chromeBrowserRssPeakMb: perf?.chromeMemory?.browserRssPeakMb,
19951997
chromeRendererRssPeakMb: perf?.chromeMemory?.rendererRssPeakMb,
19961998
chromeRssLastMb: perf?.chromeMemory?.rssLastMb,

‎packages/cli/src/server/studioRenderTelemetry.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import type { CanvasResolution, Fps } from "@hyperframes/core";
1111
import { fpsToNumber } from "@hyperframes/core";
1212
import type { RenderJob, RenderPerfSummary } from "@hyperframes/producer";
1313
import { trackRenderComplete, trackRenderError } from "../telemetry/events.js";
14+
import { renderMotionBlurTelemetryPayload } from "../telemetry/renderMotionBlur.js";
1415
import {
1516
renderJobObservabilityTelemetryPayload,
1617
renderObservabilityTelemetryPayload,
@@ -109,6 +110,7 @@ function perfPayload(
109110
...stagesPayload(perf.stages),
110111
...extractPayload(perf.videoExtractBreakdown),
111112
...renderObservabilityTelemetryPayload(perf.observability),
113+
...renderMotionBlurTelemetryPayload(perf.motionBlur),
112114
};
113115
}
114116

‎packages/cli/src/telemetry/events.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ import { flush, shouldTrack, trackEvent } from "./client.js";
88
import { readConfig } from "./config.js";
99
import { getPowerState } from "./system.js";
1010
import type { RenderCpuTelemetryPayload } from "./renderCpu.js";
11+
import {
12+
type RenderMotionBlurTelemetryPayload,
13+
renderMotionBlurEventProperties,
14+
} from "./renderMotionBlur.js";
1115
import { CliRuntimeError } from "../utils/commandResult.js";
1216

1317
// Power state is volatile (a laptop docks/undocks mid-session), so it is
@@ -488,7 +492,8 @@ export function trackRenderComplete(
488492
} & RenderObservabilityTelemetryPayload &
489493
RenderOutputShapeTelemetryPayload &
490494
RenderEnvironmentTelemetryPayload &
491-
RenderCpuTelemetryPayload,
495+
RenderCpuTelemetryPayload &
496+
RenderMotionBlurTelemetryPayload,
492497
): void {
493498
trackEvent(
494499
"render_complete",
@@ -614,6 +619,7 @@ export function trackRenderComplete(
614619
...renderOutputShapeEventProperties(props),
615620
...renderEnvironmentEventProperties(props),
616621
...renderCpuEventProperties(props),
622+
...renderMotionBlurEventProperties(props),
617623
composition_duration_ms: props.compositionDurationMs,
618624
composition_width: props.compositionWidth,
619625
composition_height: props.compositionHeight,
Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
import { beforeEach, describe, expect, it, vi } from "vitest";
2+
import type { PageMotionBlurSummary } from "@hyperframes/engine";
3+
4+
const trackEvent = vi.fn();
5+
vi.mock("./client.js", () => ({
6+
trackEvent: (...args: unknown[]) => trackEvent(...args),
7+
flush: () => Promise.resolve(),
8+
shouldTrack: () => true,
9+
}));
10+
vi.mock("./system.js", async () => ({
11+
...(await vi.importActual<typeof import("./system.js")>("./system.js")),
12+
getPowerState: () => ({ on_battery: false, low_power_mode: false }),
13+
}));
14+
15+
const { trackRenderComplete } = await import("./events.js");
16+
const { renderMotionBlurEventProperties, renderMotionBlurTelemetryPayload } =
17+
await import("./renderMotionBlur.js");
18+
19+
const fingerprint = (over: Partial<NonNullable<PageMotionBlurSummary["fingerprint"]>>) => ({
20+
canvas2d: 0,
21+
webgl: 0,
22+
video: 0,
23+
iframe: 0,
24+
customElement: 0,
25+
svgClip: 0,
26+
mask: 0,
27+
scrollContainer: 0,
28+
threeD: 0,
29+
overflowingMover: 0,
30+
frontOfMover: 0,
31+
blendMode: 0,
32+
fixedInMover: 0,
33+
pseudoOutside: 0,
34+
...over,
35+
});
36+
37+
const blur = (over: Partial<PageMotionBlurSummary> = {}): PageMotionBlurSummary => ({
38+
tier: "filter",
39+
reasonCode: "accelerated-canvas",
40+
movers: 4,
41+
failedFrames: 0,
42+
readEvents: false,
43+
fingerprint: fingerprint({}),
44+
...over,
45+
});
46+
47+
const complete = (motionBlur: PageMotionBlurSummary | undefined) => {
48+
trackRenderComplete({
49+
durationMs: 1,
50+
fps: 30,
51+
quality: "draft",
52+
docker: false,
53+
gpu: false,
54+
...renderMotionBlurTelemetryPayload(motionBlur),
55+
});
56+
return trackEvent.mock.calls[0]?.[1] as Record<string, unknown>;
57+
};
58+
59+
describe("render_complete motion blur properties", () => {
60+
beforeEach(() => trackEvent.mockClear());
61+
62+
it("sends the tier, movers, failed frames and one property per non-zero count", () => {
63+
const props = complete(
64+
blur({
65+
failedFrames: 7,
66+
fingerprint: fingerprint({ webgl: 1, overflowingMover: 3, canvas2d: 2 }),
67+
}),
68+
);
69+
expect(props).toMatchObject({
70+
motion_blur_tier: "filter",
71+
motion_blur_movers: 4,
72+
motion_blur_failed_frames: 7,
73+
motion_blur_fp_canvas2d: 2,
74+
motion_blur_fp_webgl: 1,
75+
motion_blur_fp_overflowing_mover: 3,
76+
});
77+
const keys = Object.keys(props).filter((k) => k.startsWith("motion_blur_"));
78+
expect(keys.sort()).toEqual([
79+
"motion_blur_failed_frames",
80+
"motion_blur_fp_canvas2d",
81+
"motion_blur_fp_overflowing_mover",
82+
"motion_blur_fp_webgl",
83+
"motion_blur_movers",
84+
"motion_blur_tier",
85+
]);
86+
});
87+
88+
it("sends nothing when blur was never on", () => {
89+
const sent = Object.entries(complete(undefined)).filter(
90+
([key, value]) => key.startsWith("motion_blur_") && value !== undefined,
91+
);
92+
expect(sent).toEqual([]);
93+
});
94+
95+
it("sends failed frames for a blur that ended before it named a tier, and no zero counts", () => {
96+
const props = renderMotionBlurEventProperties(
97+
renderMotionBlurTelemetryPayload(blur({ tier: null, failedFrames: 5, fingerprint: null })),
98+
);
99+
expect(props).toEqual({
100+
motion_blur_tier: undefined,
101+
motion_blur_movers: 4,
102+
motion_blur_failed_frames: 5,
103+
});
104+
});
105+
106+
it("names every count the runtime can report, in snake case", () => {
107+
const all = Object.fromEntries(
108+
Object.keys(fingerprint({})).map((field) => [field, 1]),
109+
) as ReturnType<typeof fingerprint>;
110+
const props = renderMotionBlurEventProperties({ motionBlurFingerprint: all });
111+
expect(Object.keys(props).filter((k) => k.startsWith("motion_blur_fp_"))).toEqual([
112+
"motion_blur_fp_canvas2d",
113+
"motion_blur_fp_webgl",
114+
"motion_blur_fp_video",
115+
"motion_blur_fp_iframe",
116+
"motion_blur_fp_custom_element",
117+
"motion_blur_fp_svg_clip",
118+
"motion_blur_fp_mask",
119+
"motion_blur_fp_scroll_container",
120+
"motion_blur_fp_three_d",
121+
"motion_blur_fp_overflowing_mover",
122+
"motion_blur_fp_front_of_mover",
123+
"motion_blur_fp_blend_mode",
124+
"motion_blur_fp_fixed_in_mover",
125+
"motion_blur_fp_pseudo_outside",
126+
]);
127+
});
128+
});
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
import { MOTION_BLUR_FINGERPRINT_FIELDS, type MotionBlurFingerprint } from "@hyperframes/core";
2+
import type { PageMotionBlurSummary } from "@hyperframes/engine";
3+
4+
export interface RenderMotionBlurTelemetryPayload {
5+
motionBlurTier?: string;
6+
motionBlurMovers?: number;
7+
motionBlurFailedFrames?: number;
8+
motionBlurFingerprint?: MotionBlurFingerprint;
9+
}
10+
11+
export function renderMotionBlurTelemetryPayload(
12+
motionBlur: PageMotionBlurSummary | undefined,
13+
): RenderMotionBlurTelemetryPayload {
14+
if (!motionBlur) return {};
15+
return {
16+
motionBlurTier: motionBlur.tier ?? undefined,
17+
motionBlurMovers: motionBlur.movers,
18+
motionBlurFailedFrames: motionBlur.failedFrames,
19+
motionBlurFingerprint: motionBlur.fingerprint ?? undefined,
20+
};
21+
}
22+
23+
const snake = (field: string): string => field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
24+
25+
export function renderMotionBlurEventProperties(
26+
props: RenderMotionBlurTelemetryPayload,
27+
): Record<string, string | number | undefined> {
28+
const counts = MOTION_BLUR_FINGERPRINT_FIELDS.flatMap((field) => {
29+
const count = props.motionBlurFingerprint?.[field];
30+
return count ? [[`motion_blur_fp_${snake(field)}`, count] as const] : [];
31+
});
32+
return {
33+
motion_blur_tier: props.motionBlurTier,
34+
motion_blur_movers: props.motionBlurMovers,
35+
motion_blur_failed_frames: props.motionBlurFailedFrames,
36+
...Object.fromEntries(counts),
37+
};
38+
}

‎packages/core/src/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -485,3 +485,8 @@ export {
485485
PAGE_MOTION_BLUR_OFF_GLOBAL,
486486
acceleratedCanvasTrackerSource,
487487
} from "./pageMotionBlur.js";
488+
export {
489+
MOTION_BLUR_FINGERPRINT_FIELDS,
490+
type MotionBlurFingerprint,
491+
type MotionBlurFingerprintField,
492+
} from "./motionBlurFingerprint.js";
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
export const MOTION_BLUR_FINGERPRINT_FIELDS = [
2+
"canvas2d",
3+
"webgl",
4+
"video",
5+
"iframe",
6+
"customElement",
7+
"svgClip",
8+
"mask",
9+
"scrollContainer",
10+
"threeD",
11+
"overflowingMover",
12+
"frontOfMover",
13+
"blendMode",
14+
"fixedInMover",
15+
"pseudoOutside",
16+
] as const;
17+
18+
export type MotionBlurFingerprintField = (typeof MOTION_BLUR_FINGERPRINT_FIELDS)[number];
19+
20+
export type MotionBlurFingerprint = Record<MotionBlurFingerprintField, number>;
21+
22+
export function emptyMotionBlurFingerprint(): MotionBlurFingerprint {
23+
return {
24+
canvas2d: 0,
25+
webgl: 0,
26+
video: 0,
27+
iframe: 0,
28+
customElement: 0,
29+
svgClip: 0,
30+
mask: 0,
31+
scrollContainer: 0,
32+
threeD: 0,
33+
overflowingMover: 0,
34+
frontOfMover: 0,
35+
blendMode: 0,
36+
fixedInMover: 0,
37+
pseudoOutside: 0,
38+
};
39+
}

‎packages/core/src/runtime/captureMotionBlur/discover.test.ts‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { afterEach, describe, expect, it, vi } from "vitest";
2-
import { discoverMovers } from "./discover";
2+
import { discoverMovers, scanMovers } from "./discover";
33

44
// jsdom lays nothing out: each element's rect follows the x its fake timeline writes.
55
function element(parent: Element, id: string, size = 10, tag = "div"): HTMLElement {
@@ -41,6 +41,34 @@ describe("discoverMovers", () => {
4141
expect(movers).toEqual([fast]);
4242
});
4343

44+
it("hands the fast elements to onFast at every step, with the pose of that step applied", () => {
45+
const { scene, fast, seek } = setup();
46+
const seen: Array<[number, boolean, string]> = [];
47+
discoverMovers({
48+
scene,
49+
durationSeconds: 1,
50+
fps: 30,
51+
seek,
52+
onFast: (i, _steps, set) => seen.push([i, set.has(fast), fast.style.transform]),
53+
});
54+
expect(seen.map(([i]) => i)).toEqual(Array.from({ length: 31 }, (_, i) => i));
55+
expect(seen.at(-1)).toEqual([30, true, "translateX(300px)"]);
56+
});
57+
58+
it("samples a scan once through onFast, even when it runs the extra passes that read events", () => {
59+
const { scene, seek } = setup();
60+
const steps: number[] = [];
61+
scanMovers({
62+
scene,
63+
durationSeconds: 1,
64+
fps: 30,
65+
seek: (t) => seek(t),
66+
events: true,
67+
onFast: (i) => steps.push(i),
68+
});
69+
expect(steps).toHaveLength(31);
70+
});
71+
4472
// A 100 px jump inside one scan step at 5 s: slow to a still-style baseline, fast between two steps.
4573
function jumpScene() {
4674
const scene = document.createElement("div");

‎packages/core/src/runtime/captureMotionBlur/discover.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ export interface DiscoverOptions {
3838
/** Seek the composition (timeline + adapters) to a time. */
3939
seek: (t: number) => void;
4040
onStep?: (i: number, steps: number) => void;
41+
onFast?: (i: number, steps: number, fast: ReadonlySet<HTMLElement>) => void;
4142
onStepBoxes?: (i: number, boxes: ReadonlyArray<DOMRect | undefined>) => void;
4243
}
4344

@@ -171,6 +172,7 @@ export function discoverMovers({
171172
fps,
172173
seek,
173174
onStep,
175+
onFast,
174176
onStepBoxes,
175177
}: DiscoverOptions): Discovery {
176178
seek(0);
@@ -232,6 +234,7 @@ export function discoverMovers({
232234
)
233235
seeThrough.add(el);
234236
});
237+
onFast?.(i, steps, fast);
235238
// Style reads up the chain are the costly part; every 10th step is enough to see a 3D turn.
236239
if (i % 10 === 0 || i === steps) {
237240
for (const el of fast) {
@@ -285,17 +288,21 @@ export function scanMovers({
285288
seek,
286289
events,
287290
onStep,
291+
onFast,
288292
...scan
289293
}: ScanOptions): Discovery & { readEvents: boolean } {
290294
const quiet = (t: number): void => seek(t, true);
291295
const rewindThroughEveryCall = (): void => seek(0, false);
292-
if (!events) return { ...discoverMovers({ ...scan, seek: quiet, onStep }), readEvents: false };
296+
if (!events) {
297+
return { ...discoverMovers({ ...scan, seek: quiet, onStep, onFast }), readEvents: false };
298+
}
293299
// Loud first: run after the silent scan, it starts at the end and fires a one-off call once more.
294300
const loud: number[] = [];
295301
const found = discoverMovers({
296302
...scan,
297303
seek: (t) => seek(t, false),
298304
onStep,
305+
onFast,
299306
onStepBoxes: (i, boxes) => {
300307
loud[i] = boxesKey(boxes);
301308
},

0 commit comments

Comments
 (0)