feat(core): data-motion-blur-phase sets when the shutter opens (#6983)

* feat(core): data-motion-blur-phase sets when the shutter opens

Page motion blur always centres the shutter on the frame. Add a phase in degrees of a
frame, -360 to 360: the window starts at t + phase / 360 / fps and lasts shutter / 360 /
fps. Unset stays centred, so a page without the attribute renders the same bytes.

Both tiers take the window from one place, shutterTimes in frames.ts.

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

* feat(core): the motion blur report carries the shutter phase

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

* chore(core): drop the phaseDeg doc comment, the comment-share ratchet may only fall

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-11-05 01:26:35 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 15b1de4aeb
commit aace91b5ec
11 changed files with 148 additions and 12 deletions
+1
View File
@@ -28,6 +28,7 @@ That is all. The same attribute drives the browser editor preview and `hyperfram
| --- | --- | --- |
| `data-motion-blur` | none | `on` enables blur. `off` opts out, on the root or on any subtree. |
| `data-motion-blur-shutter` | `240` | Shutter angle in degrees, 0–720. Larger is a longer smear. |
| `data-motion-blur-phase` | centred | When the shutter opens, in degrees of a frame, -360 to 360. The window starts at `t + phase / 360 / fps` and lasts `shutter / 360 / fps`. `0` opens on the frame, so the smear trails ahead of it; unset centres it, the same as minus half the shutter. Matches After Effects' Shutter Phase. |
| `data-motion-blur-samples` | at least 32 | A fixed number of samples per frame, 2–64. Left unset, each mover gets at least 32, and about one per 2 px of smear when that is more, so a fast move never shows steps. |
| `data-motion-blur-events` | off | `on` runs timeline callbacks (`onUpdate` and similar) while blur looks for movers, and at each sample when a callback changes an element's inline style or its box. Needed when the motion is set from a callback, such as a `render(t)` function, which blur cannot otherwise see. |
| `data-motion-blur-tier` | `auto` | `capture` or `filter` forces one of the two ways blur is drawn (below). |
+1
View File
@@ -6,6 +6,7 @@ Fast-moving elements get a shutter smear along their path. It is opt-in: nothing
- `data-motion-blur` — `on` enables blur; `off` opts out, on the root or on any subtree
- `data-motion-blur-shutter` — shutter angle in degrees, 0-720 (default: 240)
- `data-motion-blur-phase` — when the shutter opens, in degrees of a frame, -360 to 360: 0 opens on the frame (default: centred on the frame, which is minus half the shutter)
- `data-motion-blur-samples` — samples per frame, 2-64 (default: at least 32, sized to the smear)
- `data-motion-blur-events` — `on` runs timeline callbacks while blur looks for movers; needed when motion is set from a `render(t)` callback
- `data-motion-blur-tier` — `auto` (default), `capture` or `filter`
+31 -2
View File
@@ -13,6 +13,7 @@ describe("readMotionBlurSettings", () => {
expect(read({})).toEqual({
enabled: false,
shutterDeg: 240,
phaseDeg: null,
samples: null,
events: false,
tier: "auto",
@@ -24,11 +25,35 @@ describe("readMotionBlurSettings", () => {
read({
"data-motion-blur": "on",
"data-motion-blur-shutter": "360",
"data-motion-blur-phase": "-90",
"data-motion-blur-samples": "48",
"data-motion-blur-events": "on",
"data-motion-blur-tier": "capture",
}),
).toEqual({ enabled: true, shutterDeg: 360, samples: 48, events: true, tier: "capture" });
).toEqual({
enabled: true,
shutterDeg: 360,
phaseDeg: -90,
samples: 48,
events: true,
tier: "capture",
});
});
it("clamps the phase to a full turn either way", () => {
expect(read({ "data-motion-blur-phase": "720" }).phaseDeg).toBe(360);
expect(read({ "data-motion-blur-phase": "-720" }).phaseDeg).toBe(-360);
expect(read({ "data-motion-blur-phase": "360" }).phaseDeg).toBe(360);
});
it("keeps a phase of 0: it opens the shutter on the frame, which is not centred", () => {
expect(read({ "data-motion-blur-phase": "0" }).phaseDeg).toBe(0);
});
it("treats a missing, empty or unreadable phase as centred", () => {
expect(read({}).phaseDeg).toBeNull();
expect(read({ "data-motion-blur-phase": "" }).phaseDeg).toBeNull();
expect(read({ "data-motion-blur-phase": "late" }).phaseDeg).toBeNull();
});
it("clamps the shutter and the samples, and rounds the samples", () => {
@@ -58,6 +83,7 @@ describe("motionBlurAttributeEdits", () => {
const custom: MotionBlurSettings = {
enabled: true,
shutterDeg: 360,
phaseDeg: 0,
samples: 48,
events: true,
tier: "filter",
@@ -67,6 +93,7 @@ describe("motionBlurAttributeEdits", () => {
expect(motionBlurAttributeEdits(custom)).toEqual({
"data-motion-blur": "on",
"data-motion-blur-shutter": "360",
"data-motion-blur-phase": "0",
"data-motion-blur-samples": "48",
"data-motion-blur-events": "on",
"data-motion-blur-tier": "filter",
@@ -75,6 +102,7 @@ describe("motionBlurAttributeEdits", () => {
motionBlurAttributeEdits({
enabled: false,
shutterDeg: 240,
phaseDeg: null,
samples: null,
events: false,
tier: "auto",
@@ -82,6 +110,7 @@ describe("motionBlurAttributeEdits", () => {
).toEqual({
"data-motion-blur": null,
"data-motion-blur-shutter": null,
"data-motion-blur-phase": null,
"data-motion-blur-samples": null,
"data-motion-blur-events": null,
"data-motion-blur-tier": null,
@@ -97,7 +126,7 @@ describe("motionBlurAttributeEdits", () => {
it("round-trips: what it writes reads back as the same settings", () => {
for (const s of [
custom,
{ ...custom, shutterDeg: 240, samples: null, tier: "auto" as const },
{ ...custom, shutterDeg: 240, phaseDeg: null, samples: null, tier: "auto" as const },
]) {
const written = motionBlurAttributeEdits(s);
const back = readMotionBlurSettings((n) => written[n] ?? null);
+7 -1
View File
@@ -3,6 +3,7 @@
export const MOTION_BLUR_ATTR = {
enable: "data-motion-blur",
shutter: "data-motion-blur-shutter",
phase: "data-motion-blur-phase",
samples: "data-motion-blur-samples",
events: "data-motion-blur-events",
tier: "data-motion-blur-tier",
@@ -10,6 +11,7 @@ export const MOTION_BLUR_ATTR = {
export const MOTION_BLUR_LIMITS = {
shutterDeg: { min: 0, max: 720, default: 240 },
phaseDeg: { min: -360, max: 360 },
samples: { min: 2, max: 64 },
} as const;
@@ -18,6 +20,7 @@ export type MotionBlurTier = "auto" | "capture" | "filter";
export interface MotionBlurSettings {
enabled: boolean;
shutterDeg: number;
phaseDeg: number | null;
/** A fixed count per frame; null sizes it to each smear, never under 32. */
samples: number | null;
events: boolean;
@@ -34,12 +37,14 @@ function number(value: string | null): number | null {
export function readMotionBlurSettings(attr: (name: string) => string | null): MotionBlurSettings {
const shutter = number(attr(MOTION_BLUR_ATTR.shutter));
const phase = number(attr(MOTION_BLUR_ATTR.phase));
const samples = number(attr(MOTION_BLUR_ATTR.samples));
const tier = attr(MOTION_BLUR_ATTR.tier);
const { shutterDeg, samples: bounds } = MOTION_BLUR_LIMITS;
const { shutterDeg, phaseDeg, samples: bounds } = MOTION_BLUR_LIMITS;
return {
enabled: attr(MOTION_BLUR_ATTR.enable) === "on",
shutterDeg: clamp(shutter ?? shutterDeg.default, shutterDeg.min, shutterDeg.max),
phaseDeg: phase === null ? null : clamp(phase, phaseDeg.min, phaseDeg.max),
samples: samples === null ? null : Math.round(clamp(samples, bounds.min, bounds.max)),
events: attr(MOTION_BLUR_ATTR.events) === "on",
tier: tier === "capture" || tier === "filter" ? tier : "auto",
@@ -58,6 +63,7 @@ export function motionBlurAttributeEdits(
[MOTION_BLUR_ATTR.enable]: settings.enabled ? "on" : null,
[MOTION_BLUR_ATTR.shutter]:
settings.shutterDeg === shutterDeg.default ? null : String(settings.shutterDeg),
[MOTION_BLUR_ATTR.phase]: settings.phaseDeg === null ? null : String(settings.phaseDeg),
[MOTION_BLUR_ATTR.samples]: settings.samples === null ? null : String(settings.samples),
[MOTION_BLUR_ATTR.events]: settings.events ? "on" : null,
[MOTION_BLUR_ATTR.tier]: settings.tier === "auto" ? null : settings.tier,
@@ -8,7 +8,7 @@
import { swallow } from "../diagnostics";
import { scanMovers } from "./discover";
import { planFilter, type FilterPlan } from "./filterPlan";
import { readMoverFrames } from "./frames";
import { readMoverFrames, shutterTimes } from "./frames";
import { createPoseReader } from "./pose";
import type { CaptureMotionBlurHost, Config, Report, Tier } from "./tier";
@@ -186,7 +186,7 @@ export function createFilterTier(
restore: readEvents ? undefined : host.holdFrame?.(),
t,
reads: engineMode ? RENDER_READS : PREVIEW_READS,
shutterSeconds: config.shutterDeg / 360 / host.fps,
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
taps: COPIES,
frameW: width,
scene: root,
@@ -229,6 +229,7 @@ export function createFilterTier(
moverNames: movers.map((el) => `${el.tagName.toLowerCase()}${el.id ? `#${el.id}` : ""}`),
scanMs,
shutterDeg: config.shutterDeg,
phaseDeg: config.phaseDeg,
frames,
meanMs: frames ? Math.round((totalMs / frames) * 10) / 10 : 0,
failures: 0,
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { readMoverFrames } from "./frames";
import { type Affine, IDENTITY, translate } from "./pose";
import { readMoverFrames, shutterTimes } from "./frames";
import { type Affine, IDENTITY, createPoseReader, translate } from "./pose";
/** Fixed layout for jsdom: an element's offset box and its client rect. */
function laidOut(el: HTMLElement, w: number, h: number, rect: [number, number, number, number]) {
@@ -230,3 +230,49 @@ describe("readMoverFrames", () => {
expect(styles.every((s) => s === null)).toBe(true);
});
});
/** The times a frame's pose reads land on, for a shutter of `shutterDeg` at 30 fps. */
function readTimes(t: number, shutterDeg: number, phaseDeg: number | null, reads = 8): number[] {
const scene = document.createElement("div");
const mover = scene.appendChild(document.createElement("div"));
const times: number[] = [];
readMoverFrames({
movers: [mover],
reader: createPoseReader(scene, new Set()),
seek: (at) => times.push(at),
restore: () => undefined,
t,
reads,
...shutterTimes(shutterDeg, phaseDeg, 30),
taps: 4,
frameW: 100,
frameH: 100,
});
return times;
}
describe("shutter phase", () => {
it("reads exactly the times a centred shutter always read when no phase is set", () => {
const shutter = 240 / 360 / 30;
const expected = Array.from({ length: 8 }, (_, j) => 2 - shutter / 2 + (j / 7) * shutter);
expect(readTimes(2, 240, null)).toEqual(expected);
});
it("opens at the frame at phase 0 and stays open for the shutter", () => {
const times = readTimes(2, 180, 0);
expect(times[0]).toBe(2);
expect(times[times.length - 1]).toBeCloseTo(2 + 1 / 60, 10);
});
it("opens one whole frame late at phase 360", () => {
expect(readTimes(2, 299, 360)[0]).toBeCloseTo(2 + 1 / 30, 10);
});
it("matches the centred shutter when the phase is minus half the angle", () => {
expect(readTimes(2, 180, -90)).toEqual(readTimes(2, 180, null));
});
it("still never reads before the start of the timeline", () => {
expect(readTimes(0, 180, -180)[0]).toBe(0);
});
});
@@ -106,6 +106,7 @@ export interface FrameRequest {
/** Pose reads across the shutter; the taps between them are interpolated. */
reads: number;
shutterSeconds: number;
phaseSeconds: number;
/** A fixed tap count, or null to size the taps to each smear. */
taps: number | null;
/** Px each mover's box grows by on every side (its glow); none for a mover not listed. */
@@ -115,6 +116,18 @@ export interface FrameRequest {
frameH: number;
}
export function shutterTimes(
shutterDeg: number,
phaseDeg: number | null,
fps: number,
): { shutterSeconds: number; phaseSeconds: number } {
const shutterSeconds = shutterDeg / 360 / fps;
return {
shutterSeconds,
phaseSeconds: phaseDeg === null ? -shutterSeconds / 2 : phaseDeg / 360 / fps,
};
}
export function readMoverFrames(req: FrameRequest): { els: HTMLElement[]; frames: MoverFrame[] } {
const { reader: r, shutterSeconds: shutter, t, reads, seek } = req;
const visible = req.movers.filter(
@@ -122,7 +135,7 @@ export function readMoverFrames(req: FrameRequest): { els: HTMLElement[]; frames
typeof el.checkVisibility !== "function" || el.checkVisibility({ visibilityProperty: true }),
);
if (visible.length === 0 || shutter <= 0) return { els: [], frames: [] };
const start = t - shutter / 2;
const start = t + req.phaseSeconds;
const poses = visible.map((): Affine[] => []);
for (let j = 0; j < reads; j++) {
seek(Math.max(0, start + (j / (reads - 1)) * shutter));
@@ -2022,3 +2022,37 @@ describe("the movers-alone capture", () => {
expect(selecting(defs, "visible")).toBe(true);
});
});
describe("shutter phase on the root", () => {
/** The pose reads around a frame at 0.5 s: the scan's own steps are on the 1/30 grid, outside these. */
function readsAroundHalf(attrs: Record<string, string>): number[] {
installHtmlInCanvas();
const { h } = movingHost({ "data-motion-blur": "on", ...attrs });
initCaptureMotionBlur(h);
void paintCaptureMotionBlur(0.5, { engineMode: true });
return h.seek.mock.calls
.map(([t]) => Number(t))
.filter((t) => t > 0.47 && t < 0.53 && t !== 0.5);
}
it.each(["capture", "filter"])("opens the %s tier's shutter at the phase", (tier) => {
if (tier === "filter") setFilterFallbackForTests(true);
const reads = readsAroundHalf({
"data-motion-blur-shutter": "180",
"data-motion-blur-phase": "0",
"data-motion-blur-tier": tier,
});
expect(Math.min(...reads)).toBeGreaterThan(0.5);
expect(Math.max(...reads)).toBeCloseTo(0.5 + 1 / 60, 8);
});
it.each(["capture", "filter"])("keeps the %s tier centred with no phase", (tier) => {
if (tier === "filter") setFilterFallbackForTests(true);
const reads = readsAroundHalf({
"data-motion-blur-shutter": "180",
"data-motion-blur-tier": tier,
});
expect(Math.min(...reads)).toBeCloseTo(0.5 - 1 / 120, 8);
expect(Math.max(...reads)).toBeCloseTo(0.5 + 1 / 120, 8);
});
});
@@ -38,7 +38,7 @@ import { createCompositor, type MoverFrame } from "./composite";
import { readMotionBlurSettings } from "../../motionBlurSettings";
import { scanMovers } from "./discover";
import { createFilterTier } from "./filterTier";
import { readMoverFrames } from "./frames";
import { readMoverFrames, shutterTimes } from "./frames";
import { createPoseReader } from "./pose";
import {
type CaptureMotionBlurHost,
@@ -96,8 +96,8 @@ const LOG_EVERY = 25;
function readConfig(root: HTMLElement): Config | null {
const settings = readMotionBlurSettings((name) => root.getAttribute(name));
if (!settings.enabled) return null;
const { shutterDeg, samples, events, tier } = settings;
return { shutterDeg, samples, events, tier };
const { shutterDeg, phaseDeg, samples, events, tier } = settings;
return { shutterDeg, phaseDeg, samples, events, tier };
}
/** Must run before composition scripts: see `installAcceleratedCanvasTracker`. */
@@ -279,7 +279,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
restore: readEvents ? undefined : host.holdFrame?.(),
t,
reads,
shutterSeconds: config.shutterDeg / 360 / host.fps,
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
taps: config.samples,
pads,
frameW: width,
@@ -561,6 +561,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
moverNames: movers.map(describe),
scanMs,
shutterDeg: config.shutterDeg,
phaseDeg: config.phaseDeg,
frames: timings.length,
meanMs: Math.round(mean * 10) / 10,
failures,
@@ -701,6 +702,7 @@ function offReport(config: Config, why: CaptureDefect | null): Report {
moverNames: [],
scanMs: 0,
shutterDeg: config.shutterDeg,
phaseDeg: config.phaseDeg,
frames: 0,
meanMs: 0,
failures: 0,
@@ -17,6 +17,7 @@ export interface CaptureMotionBlurHost {
export interface Config {
shutterDeg: number;
phaseDeg: number | null;
samples: number | null;
events: boolean;
tier: "auto" | "capture" | "filter";
@@ -33,6 +34,7 @@ export interface Report {
moverNames: string[];
scanMs: number;
shutterDeg: number;
phaseDeg: number | null;
frames: number;
meanMs: number;
failures: number;
@@ -114,6 +114,7 @@ describe("levelOf and patchForLevel", () => {
const on = (shutterDeg: number, enabled = true) => ({
enabled,
shutterDeg,
phaseDeg: null,
samples: null,
events: false,
tier: "auto" as const,