Files
hyperframes/packages/cli/src/utils/checkMotionBlur.ts
T
Vance IngallsandClaude Sonnet 5.5 79b57ab12d feat: automatic tier, 240°/32 defaults, check finding, and Studio stops opting out (#6108)
* feat: check names the filter fallback, the render log names the tier, Studio stops opting out

hyperframes check reports motion_blur_filter_fallback (info) with the reason capture could not
run and the way back to it. The engine's per-session log line gains tier=, and its pixel test
covers the fallback over a WebGL page. Studio no longer sends previewMotionBlur: every Chrome
can preview blur now, through the fallback where it lacks html-in-canvas; the server still
accepts false from an older Studio.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* feat(core): blur picks the cheaper filter tier when every mover only translates

The scan now notes whether any mover turns or scales (the linear part of its transform chain
changes) and whether it already forms a stacking context while it moves. When every mover only
translates, the filter tier draws as well as capture and costs about what no blur costs: on an
8 s bench shot a render took 7.0 s against 9.9 s with capture and 7.3 s with no blur. Anything
that turns or scales, or moves without a transform, stays on capture.

data-motion-blur-tier="capture" or "filter" forces a tier. The report says which one drew
and why (translation-only, tier-attribute); hyperframes check stays quiet for those two, which
are choices, not fallbacks. The pixel tests run the shared assertions through both tiers.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(motion-blur): the two tiers, the tier attribute, and what changed in limits

The guide described blur turning off for WebGL, a root transform and similar. It now says the
filter tier draws instead, how the tier is chosen and forced, what each does with a turn or a
zoom, the measured cost of each, and which findings check emits. The skill note drops the
off-for-WebGL advice and the 1.7x figure.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* feat(core): blur defaults match a 240 degree shutter and at least 32 samples

The shutter opens 240 degrees by default (was 180) and each mover gets at least 32 taps (was
sized to the smear alone, down to 2), growing with the smear as before. These are the settings
the shutter blur Jake built uses; on the card whip the default render is now 51 dB from his
(34.6 dB at the old defaults). The guide's attribute table says so.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* chore(core): trim tier.ts comments to the ratchet

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* chore: allow deleting the Studio previewMotionBlur render test

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-23 14:20:17 -07:00

132 lines
5.4 KiB
TypeScript

import type { Page } from "puppeteer-core";
import type { CheckSeverity } from "./checkTypes.js";
/** What the core runtime's `__hfMotionBlur.probe()` reports for a root that asked for blur. */
export interface MotionBlurProbe {
state: "on" | "off";
tier: "capture" | "filter" | null;
reason: string | null;
reasonCode: string | null;
movers: number;
}
export interface MotionBlurDraft {
code: string;
severity: CheckSeverity;
message: string;
fixHint: string;
time: number;
}
const OFF_HINTS: Record<string, string> = {
"accelerated-canvas":
"html-in-canvas captures WebGL/WebGPU frozen, in sub-compositions too: render that effect separately or flatten it out of the page, or drop data-motion-blur on this composition",
"backface-visibility":
"backface-visibility: hidden inside a 3D transform is drawn mirrored; avoid the 3D flip or drop motion blur",
"iframe-in-root":
"move the <iframe>, <object>, <embed> or custom element out of the composition root (each is re-initialised when blur wraps the root), or drop motion blur",
"root-transform": "animate a child element instead of the composition root, or drop motion blur",
"root-opacity": "animate a child element instead of the composition root, or drop motion blur",
"root-blend-mode":
"set mix-blend-mode on a child element instead of the composition root, or drop motion blur",
"nested-capture-canvas":
"remove the inner <canvas layoutsubtree> / content=drawable, or drop motion blur",
};
const CHOSEN = new Set(["translation-only", "tier-attribute"]);
const GENERIC_OFF_HINT = "remove what the reason names, or drop data-motion-blur";
const ASKED = 'data-motion-blur="on" is set but';
/** The findings for one probe; null (no opt-in, or nothing to read) gives none. */
export function motionBlurDrafts(probe: MotionBlurProbe | null): MotionBlurDraft[] {
if (!probe) return [];
if (probe.reasonCode === "unsupported-browser") {
return [
{
code: "motion_blur_unverified",
severity: "info",
message: `${ASKED} the check browser cannot run capture blur, so it was drawn with the filter fallback`,
fixHint:
"the check browser has no html-in-canvas (drawElementImage); render once to see how capture blur looks",
time: 0,
},
];
}
if (probe.state === "off") {
return [
{
code: "motion_blur_off",
severity: "warning",
message: `${ASKED} blur is off: ${probe.reason ?? "unknown reason"}`,
fixHint: OFF_HINTS[probe.reasonCode ?? ""] ?? GENERIC_OFF_HINT,
time: 0,
},
];
}
if (probe.tier === "filter" && probe.movers > 0 && !CHOSEN.has(probe.reasonCode ?? "")) {
return [
{
code: "motion_blur_filter_fallback",
severity: "info",
message: `data-motion-blur="on" is drawn by the filter fallback: ${probe.reason ?? "capture blur cannot run here"}`,
fixHint: `the fallback smears movement but only softens zoom and rotation; ${OFF_HINTS[probe.reasonCode ?? ""] ?? GENERIC_OFF_HINT}`,
time: 0,
},
];
}
if (probe.movers === 0) {
return [
{
code: "motion_blur_no_movers",
severity: "info",
message: `${ASKED} nothing in the composition moves fast enough to blur, so it has no effect`,
fixHint:
'animate an element\'s transform or position by 2+ px per frame; if the motion is set from a timeline callback (onUpdate, render(t)), add data-motion-blur-events="on"; otherwise drop data-motion-blur',
time: 0,
},
];
}
return [];
}
// Serialized into the page; the guards must stay one function.
// fallow-ignore-next-line complexity
export function readMotionBlurProbe(): MotionBlurProbe | null {
const api: unknown = Reflect.get(window, "__hfMotionBlur");
if (typeof api !== "object" || api === null) return null;
const probe: unknown = Reflect.get(api, "probe");
if (typeof probe !== "function") return null;
const report: unknown = Reflect.apply(probe, api, []);
if (typeof report !== "object" || report === null) return null;
const reason: unknown = Reflect.get(report, "reason");
const code: unknown = Reflect.get(report, "reasonCode");
const movers: unknown = Reflect.get(report, "movers");
const tier: unknown = Reflect.get(report, "tier");
const suspend: unknown = Reflect.get(api, "suspend");
if (typeof suspend === "function") Reflect.apply(suspend, api, []);
return {
state: Reflect.get(report, "state") === "off" ? "off" : "on",
tier: tier === "capture" || tier === "filter" ? tier : null,
reason: typeof reason === "string" ? reason : null,
reasonCode: typeof code === "string" ? code : null,
movers: typeof movers === "number" ? movers : 0,
};
}
/** Ask the page to decide blur now. The runtime exposes the global only for a root that asked for blur. */
export async function collectMotionBlurDrafts(page: Page): Promise<MotionBlurDraft[]> {
const probe = await page.evaluate(readMotionBlurProbe).catch(() => null);
return motionBlurDrafts(probe);
}
/** The runtime also warns on the console when a scan turns blur off; the finding already says it. */
export function dropMotionBlurConsoleEcho<T extends { code: string; message: string }>(
drafts: T[],
found: MotionBlurDraft[],
): T[] {
if (found.length === 0) return drafts;
return drafts.filter(
(d) => !(d.code === "console_warning" && d.message.startsWith("[motion-blur] off:")),
);
}