Skip to content

Commit aace91b

Browse files
vanceingallsclaude
andauthored
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 <[email protected]> * feat(core): the motion blur report carries the shutter phase Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * chore(core): drop the phaseDeg doc comment, the comment-share ratchet may only fall Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 15b1de4 commit aace91b

11 files changed

Lines changed: 148 additions & 12 deletions

File tree

‎docs/guides/motion-blur.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ That is all. The same attribute drives the browser editor preview and `hyperfram
2828
| --- | --- | --- |
2929
| `data-motion-blur` | none | `on` enables blur. `off` opts out, on the root or on any subtree. |
3030
| `data-motion-blur-shutter` | `240` | Shutter angle in degrees, 0–720. Larger is a longer smear. |
31+
| `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. |
3132
| `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. |
3233
| `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. |
3334
| `data-motion-blur-tier` | `auto` | `capture` or `filter` forces one of the two ways blur is drawn (below). |

‎packages/cli/src/docs/motion-blur.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Fast-moving elements get a shutter smear along their path. It is opt-in: nothing
66

77
- `data-motion-blur` — `on` enables blur; `off` opts out, on the root or on any subtree
88
- `data-motion-blur-shutter` — shutter angle in degrees, 0-720 (default: 240)
9+
- `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)
910
- `data-motion-blur-samples` — samples per frame, 2-64 (default: at least 32, sized to the smear)
1011
- `data-motion-blur-events` — `on` runs timeline callbacks while blur looks for movers; needed when motion is set from a `render(t)` callback
1112
- `data-motion-blur-tier` — `auto` (default), `capture` or `filter`

‎packages/core/src/motionBlurSettings.test.ts‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ describe("readMotionBlurSettings", () => {
1313
expect(read({})).toEqual({
1414
enabled: false,
1515
shutterDeg: 240,
16+
phaseDeg: null,
1617
samples: null,
1718
events: false,
1819
tier: "auto",
@@ -24,11 +25,35 @@ describe("readMotionBlurSettings", () => {
2425
read({
2526
"data-motion-blur": "on",
2627
"data-motion-blur-shutter": "360",
28+
"data-motion-blur-phase": "-90",
2729
"data-motion-blur-samples": "48",
2830
"data-motion-blur-events": "on",
2931
"data-motion-blur-tier": "capture",
3032
}),
31-
).toEqual({ enabled: true, shutterDeg: 360, samples: 48, events: true, tier: "capture" });
33+
).toEqual({
34+
enabled: true,
35+
shutterDeg: 360,
36+
phaseDeg: -90,
37+
samples: 48,
38+
events: true,
39+
tier: "capture",
40+
});
41+
});
42+
43+
it("clamps the phase to a full turn either way", () => {
44+
expect(read({ "data-motion-blur-phase": "720" }).phaseDeg).toBe(360);
45+
expect(read({ "data-motion-blur-phase": "-720" }).phaseDeg).toBe(-360);
46+
expect(read({ "data-motion-blur-phase": "360" }).phaseDeg).toBe(360);
47+
});
48+
49+
it("keeps a phase of 0: it opens the shutter on the frame, which is not centred", () => {
50+
expect(read({ "data-motion-blur-phase": "0" }).phaseDeg).toBe(0);
51+
});
52+
53+
it("treats a missing, empty or unreadable phase as centred", () => {
54+
expect(read({}).phaseDeg).toBeNull();
55+
expect(read({ "data-motion-blur-phase": "" }).phaseDeg).toBeNull();
56+
expect(read({ "data-motion-blur-phase": "late" }).phaseDeg).toBeNull();
3257
});
3358

3459
it("clamps the shutter and the samples, and rounds the samples", () => {
@@ -58,6 +83,7 @@ describe("motionBlurAttributeEdits", () => {
5883
const custom: MotionBlurSettings = {
5984
enabled: true,
6085
shutterDeg: 360,
86+
phaseDeg: 0,
6187
samples: 48,
6288
events: true,
6389
tier: "filter",
@@ -67,6 +93,7 @@ describe("motionBlurAttributeEdits", () => {
6793
expect(motionBlurAttributeEdits(custom)).toEqual({
6894
"data-motion-blur": "on",
6995
"data-motion-blur-shutter": "360",
96+
"data-motion-blur-phase": "0",
7097
"data-motion-blur-samples": "48",
7198
"data-motion-blur-events": "on",
7299
"data-motion-blur-tier": "filter",
@@ -75,13 +102,15 @@ describe("motionBlurAttributeEdits", () => {
75102
motionBlurAttributeEdits({
76103
enabled: false,
77104
shutterDeg: 240,
105+
phaseDeg: null,
78106
samples: null,
79107
events: false,
80108
tier: "auto",
81109
}),
82110
).toEqual({
83111
"data-motion-blur": null,
84112
"data-motion-blur-shutter": null,
113+
"data-motion-blur-phase": null,
85114
"data-motion-blur-samples": null,
86115
"data-motion-blur-events": null,
87116
"data-motion-blur-tier": null,
@@ -97,7 +126,7 @@ describe("motionBlurAttributeEdits", () => {
97126
it("round-trips: what it writes reads back as the same settings", () => {
98127
for (const s of [
99128
custom,
100-
{ ...custom, shutterDeg: 240, samples: null, tier: "auto" as const },
129+
{ ...custom, shutterDeg: 240, phaseDeg: null, samples: null, tier: "auto" as const },
101130
]) {
102131
const written = motionBlurAttributeEdits(s);
103132
const back = readMotionBlurSettings((n) => written[n] ?? null);

‎packages/core/src/motionBlurSettings.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,15 @@
33
export const MOTION_BLUR_ATTR = {
44
enable: "data-motion-blur",
55
shutter: "data-motion-blur-shutter",
6+
phase: "data-motion-blur-phase",
67
samples: "data-motion-blur-samples",
78
events: "data-motion-blur-events",
89
tier: "data-motion-blur-tier",
910
} as const;
1011

1112
export const MOTION_BLUR_LIMITS = {
1213
shutterDeg: { min: 0, max: 720, default: 240 },
14+
phaseDeg: { min: -360, max: 360 },
1315
samples: { min: 2, max: 64 },
1416
} as const;
1517

@@ -18,6 +20,7 @@ export type MotionBlurTier = "auto" | "capture" | "filter";
1820
export interface MotionBlurSettings {
1921
enabled: boolean;
2022
shutterDeg: number;
23+
phaseDeg: number | null;
2124
/** A fixed count per frame; null sizes it to each smear, never under 32. */
2225
samples: number | null;
2326
events: boolean;
@@ -34,12 +37,14 @@ function number(value: string | null): number | null {
3437

3538
export function readMotionBlurSettings(attr: (name: string) => string | null): MotionBlurSettings {
3639
const shutter = number(attr(MOTION_BLUR_ATTR.shutter));
40+
const phase = number(attr(MOTION_BLUR_ATTR.phase));
3741
const samples = number(attr(MOTION_BLUR_ATTR.samples));
3842
const tier = attr(MOTION_BLUR_ATTR.tier);
39-
const { shutterDeg, samples: bounds } = MOTION_BLUR_LIMITS;
43+
const { shutterDeg, phaseDeg, samples: bounds } = MOTION_BLUR_LIMITS;
4044
return {
4145
enabled: attr(MOTION_BLUR_ATTR.enable) === "on",
4246
shutterDeg: clamp(shutter ?? shutterDeg.default, shutterDeg.min, shutterDeg.max),
47+
phaseDeg: phase === null ? null : clamp(phase, phaseDeg.min, phaseDeg.max),
4348
samples: samples === null ? null : Math.round(clamp(samples, bounds.min, bounds.max)),
4449
events: attr(MOTION_BLUR_ATTR.events) === "on",
4550
tier: tier === "capture" || tier === "filter" ? tier : "auto",
@@ -58,6 +63,7 @@ export function motionBlurAttributeEdits(
5863
[MOTION_BLUR_ATTR.enable]: settings.enabled ? "on" : null,
5964
[MOTION_BLUR_ATTR.shutter]:
6065
settings.shutterDeg === shutterDeg.default ? null : String(settings.shutterDeg),
66+
[MOTION_BLUR_ATTR.phase]: settings.phaseDeg === null ? null : String(settings.phaseDeg),
6167
[MOTION_BLUR_ATTR.samples]: settings.samples === null ? null : String(settings.samples),
6268
[MOTION_BLUR_ATTR.events]: settings.events ? "on" : null,
6369
[MOTION_BLUR_ATTR.tier]: settings.tier === "auto" ? null : settings.tier,

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
import { swallow } from "../diagnostics";
99
import { scanMovers } from "./discover";
1010
import { planFilter, type FilterPlan } from "./filterPlan";
11-
import { readMoverFrames } from "./frames";
11+
import { readMoverFrames, shutterTimes } from "./frames";
1212
import { createPoseReader } from "./pose";
1313
import type { CaptureMotionBlurHost, Config, Report, Tier } from "./tier";
1414

@@ -186,7 +186,7 @@ export function createFilterTier(
186186
restore: readEvents ? undefined : host.holdFrame?.(),
187187
t,
188188
reads: engineMode ? RENDER_READS : PREVIEW_READS,
189-
shutterSeconds: config.shutterDeg / 360 / host.fps,
189+
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
190190
taps: COPIES,
191191
frameW: width,
192192
scene: root,
@@ -229,6 +229,7 @@ export function createFilterTier(
229229
moverNames: movers.map((el) => `${el.tagName.toLowerCase()}${el.id ? `#${el.id}` : ""}`),
230230
scanMs,
231231
shutterDeg: config.shutterDeg,
232+
phaseDeg: config.phaseDeg,
232233
frames,
233234
meanMs: frames ? Math.round((totalMs / frames) * 10) / 10 : 0,
234235
failures: 0,

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

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { afterEach, beforeEach, describe, expect, it } from "vitest";
2-
import { readMoverFrames } from "./frames";
3-
import { type Affine, IDENTITY, translate } from "./pose";
2+
import { readMoverFrames, shutterTimes } from "./frames";
3+
import { type Affine, IDENTITY, createPoseReader, translate } from "./pose";
44

55
/** Fixed layout for jsdom: an element's offset box and its client rect. */
66
function laidOut(el: HTMLElement, w: number, h: number, rect: [number, number, number, number]) {
@@ -230,3 +230,49 @@ describe("readMoverFrames", () => {
230230
expect(styles.every((s) => s === null)).toBe(true);
231231
});
232232
});
233+
234+
/** The times a frame's pose reads land on, for a shutter of `shutterDeg` at 30 fps. */
235+
function readTimes(t: number, shutterDeg: number, phaseDeg: number | null, reads = 8): number[] {
236+
const scene = document.createElement("div");
237+
const mover = scene.appendChild(document.createElement("div"));
238+
const times: number[] = [];
239+
readMoverFrames({
240+
movers: [mover],
241+
reader: createPoseReader(scene, new Set()),
242+
seek: (at) => times.push(at),
243+
restore: () => undefined,
244+
t,
245+
reads,
246+
...shutterTimes(shutterDeg, phaseDeg, 30),
247+
taps: 4,
248+
frameW: 100,
249+
frameH: 100,
250+
});
251+
return times;
252+
}
253+
254+
describe("shutter phase", () => {
255+
it("reads exactly the times a centred shutter always read when no phase is set", () => {
256+
const shutter = 240 / 360 / 30;
257+
const expected = Array.from({ length: 8 }, (_, j) => 2 - shutter / 2 + (j / 7) * shutter);
258+
expect(readTimes(2, 240, null)).toEqual(expected);
259+
});
260+
261+
it("opens at the frame at phase 0 and stays open for the shutter", () => {
262+
const times = readTimes(2, 180, 0);
263+
expect(times[0]).toBe(2);
264+
expect(times[times.length - 1]).toBeCloseTo(2 + 1 / 60, 10);
265+
});
266+
267+
it("opens one whole frame late at phase 360", () => {
268+
expect(readTimes(2, 299, 360)[0]).toBeCloseTo(2 + 1 / 30, 10);
269+
});
270+
271+
it("matches the centred shutter when the phase is minus half the angle", () => {
272+
expect(readTimes(2, 180, -90)).toEqual(readTimes(2, 180, null));
273+
});
274+
275+
it("still never reads before the start of the timeline", () => {
276+
expect(readTimes(0, 180, -180)[0]).toBe(0);
277+
});
278+
});

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

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ export interface FrameRequest {
106106
/** Pose reads across the shutter; the taps between them are interpolated. */
107107
reads: number;
108108
shutterSeconds: number;
109+
phaseSeconds: number;
109110
/** A fixed tap count, or null to size the taps to each smear. */
110111
taps: number | null;
111112
/** Px each mover's box grows by on every side (its glow); none for a mover not listed. */
@@ -115,14 +116,26 @@ export interface FrameRequest {
115116
frameH: number;
116117
}
117118

119+
export function shutterTimes(
120+
shutterDeg: number,
121+
phaseDeg: number | null,
122+
fps: number,
123+
): { shutterSeconds: number; phaseSeconds: number } {
124+
const shutterSeconds = shutterDeg / 360 / fps;
125+
return {
126+
shutterSeconds,
127+
phaseSeconds: phaseDeg === null ? -shutterSeconds / 2 : phaseDeg / 360 / fps,
128+
};
129+
}
130+
118131
export function readMoverFrames(req: FrameRequest): { els: HTMLElement[]; frames: MoverFrame[] } {
119132
const { reader: r, shutterSeconds: shutter, t, reads, seek } = req;
120133
const visible = req.movers.filter(
121134
(el) =>
122135
typeof el.checkVisibility !== "function" || el.checkVisibility({ visibilityProperty: true }),
123136
);
124137
if (visible.length === 0 || shutter <= 0) return { els: [], frames: [] };
125-
const start = t - shutter / 2;
138+
const start = t + req.phaseSeconds;
126139
const poses = visible.map((): Affine[] => []);
127140
for (let j = 0; j < reads; j++) {
128141
seek(Math.max(0, start + (j / (reads - 1)) * shutter));

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2022,3 +2022,37 @@ describe("the movers-alone capture", () => {
20222022
expect(selecting(defs, "visible")).toBe(true);
20232023
});
20242024
});
2025+
2026+
describe("shutter phase on the root", () => {
2027+
/** The pose reads around a frame at 0.5 s: the scan's own steps are on the 1/30 grid, outside these. */
2028+
function readsAroundHalf(attrs: Record<string, string>): number[] {
2029+
installHtmlInCanvas();
2030+
const { h } = movingHost({ "data-motion-blur": "on", ...attrs });
2031+
initCaptureMotionBlur(h);
2032+
void paintCaptureMotionBlur(0.5, { engineMode: true });
2033+
return h.seek.mock.calls
2034+
.map(([t]) => Number(t))
2035+
.filter((t) => t > 0.47 && t < 0.53 && t !== 0.5);
2036+
}
2037+
2038+
it.each(["capture", "filter"])("opens the %s tier's shutter at the phase", (tier) => {
2039+
if (tier === "filter") setFilterFallbackForTests(true);
2040+
const reads = readsAroundHalf({
2041+
"data-motion-blur-shutter": "180",
2042+
"data-motion-blur-phase": "0",
2043+
"data-motion-blur-tier": tier,
2044+
});
2045+
expect(Math.min(...reads)).toBeGreaterThan(0.5);
2046+
expect(Math.max(...reads)).toBeCloseTo(0.5 + 1 / 60, 8);
2047+
});
2048+
2049+
it.each(["capture", "filter"])("keeps the %s tier centred with no phase", (tier) => {
2050+
if (tier === "filter") setFilterFallbackForTests(true);
2051+
const reads = readsAroundHalf({
2052+
"data-motion-blur-shutter": "180",
2053+
"data-motion-blur-tier": tier,
2054+
});
2055+
expect(Math.min(...reads)).toBeCloseTo(0.5 - 1 / 120, 8);
2056+
expect(Math.max(...reads)).toBeCloseTo(0.5 + 1 / 120, 8);
2057+
});
2058+
});

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

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ import { createCompositor, type MoverFrame } from "./composite";
3838
import { readMotionBlurSettings } from "../../motionBlurSettings";
3939
import { scanMovers } from "./discover";
4040
import { createFilterTier } from "./filterTier";
41-
import { readMoverFrames } from "./frames";
41+
import { readMoverFrames, shutterTimes } from "./frames";
4242
import { createPoseReader } from "./pose";
4343
import {
4444
type CaptureMotionBlurHost,
@@ -96,8 +96,8 @@ const LOG_EVERY = 25;
9696
function readConfig(root: HTMLElement): Config | null {
9797
const settings = readMotionBlurSettings((name) => root.getAttribute(name));
9898
if (!settings.enabled) return null;
99-
const { shutterDeg, samples, events, tier } = settings;
100-
return { shutterDeg, samples, events, tier };
99+
const { shutterDeg, phaseDeg, samples, events, tier } = settings;
100+
return { shutterDeg, phaseDeg, samples, events, tier };
101101
}
102102

103103
/** Must run before composition scripts: see `installAcceleratedCanvasTracker`. */
@@ -279,7 +279,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
279279
restore: readEvents ? undefined : host.holdFrame?.(),
280280
t,
281281
reads,
282-
shutterSeconds: config.shutterDeg / 360 / host.fps,
282+
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
283283
taps: config.samples,
284284
pads,
285285
frameW: width,
@@ -561,6 +561,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
561561
moverNames: movers.map(describe),
562562
scanMs,
563563
shutterDeg: config.shutterDeg,
564+
phaseDeg: config.phaseDeg,
564565
frames: timings.length,
565566
meanMs: Math.round(mean * 10) / 10,
566567
failures,
@@ -701,6 +702,7 @@ function offReport(config: Config, why: CaptureDefect | null): Report {
701702
moverNames: [],
702703
scanMs: 0,
703704
shutterDeg: config.shutterDeg,
705+
phaseDeg: config.phaseDeg,
704706
frames: 0,
705707
meanMs: 0,
706708
failures: 0,

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ export interface CaptureMotionBlurHost {
1717

1818
export interface Config {
1919
shutterDeg: number;
20+
phaseDeg: number | null;
2021
samples: number | null;
2122
events: boolean;
2223
tier: "auto" | "capture" | "filter";
@@ -33,6 +34,7 @@ export interface Report {
3334
moverNames: string[];
3435
scanMs: number;
3536
shutterDeg: number;
37+
phaseDeg: number | null;
3638
frames: number;
3739
meanMs: number;
3840
failures: number;

0 commit comments

Comments
 (0)