From aace91b5ec0d937772f66ab06e63c5755e579646 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 5 Nov 2026 01:26:35 +0000 Subject: [PATCH] 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 * feat(core): the motion blur report carries the shutter phase Co-Authored-By: Claude Sonnet 5.5 * chore(core): drop the phaseDeg doc comment, the comment-share ratchet may only fall Co-Authored-By: Claude Sonnet 5.5 --------- Co-authored-by: Claude Opus 5.5 --- docs/guides/motion-blur.mdx | 1 + packages/cli/src/docs/motion-blur.md | 1 + packages/core/src/motionBlurSettings.test.ts | 33 +++++++++++- packages/core/src/motionBlurSettings.ts | 8 ++- .../runtime/captureMotionBlur/filterTier.ts | 5 +- .../runtime/captureMotionBlur/frames.test.ts | 50 ++++++++++++++++++- .../src/runtime/captureMotionBlur/frames.ts | 15 +++++- .../runtime/captureMotionBlur/index.test.ts | 34 +++++++++++++ .../src/runtime/captureMotionBlur/index.ts | 10 ++-- .../src/runtime/captureMotionBlur/tier.ts | 2 + .../panels/motionBlurPanelModel.test.ts | 1 + 11 files changed, 148 insertions(+), 12 deletions(-) diff --git a/docs/guides/motion-blur.mdx b/docs/guides/motion-blur.mdx index 4289b18500..3e70a27f1a 100644 --- a/docs/guides/motion-blur.mdx +++ b/docs/guides/motion-blur.mdx @@ -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). | diff --git a/packages/cli/src/docs/motion-blur.md b/packages/cli/src/docs/motion-blur.md index 1eaccd4030..2e8a2737b9 100644 --- a/packages/cli/src/docs/motion-blur.md +++ b/packages/cli/src/docs/motion-blur.md @@ -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` diff --git a/packages/core/src/motionBlurSettings.test.ts b/packages/core/src/motionBlurSettings.test.ts index 2f3e1f0398..e5f4212dd4 100644 --- a/packages/core/src/motionBlurSettings.test.ts +++ b/packages/core/src/motionBlurSettings.test.ts @@ -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); diff --git a/packages/core/src/motionBlurSettings.ts b/packages/core/src/motionBlurSettings.ts index c02f946785..19f9f1a8b6 100644 --- a/packages/core/src/motionBlurSettings.ts +++ b/packages/core/src/motionBlurSettings.ts @@ -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, diff --git a/packages/core/src/runtime/captureMotionBlur/filterTier.ts b/packages/core/src/runtime/captureMotionBlur/filterTier.ts index 61e68e7ce2..daca77bc78 100644 --- a/packages/core/src/runtime/captureMotionBlur/filterTier.ts +++ b/packages/core/src/runtime/captureMotionBlur/filterTier.ts @@ -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, diff --git a/packages/core/src/runtime/captureMotionBlur/frames.test.ts b/packages/core/src/runtime/captureMotionBlur/frames.test.ts index 979fae0379..1d13dbeb14 100644 --- a/packages/core/src/runtime/captureMotionBlur/frames.test.ts +++ b/packages/core/src/runtime/captureMotionBlur/frames.test.ts @@ -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); + }); +}); diff --git a/packages/core/src/runtime/captureMotionBlur/frames.ts b/packages/core/src/runtime/captureMotionBlur/frames.ts index c577673471..bf5d76f42f 100644 --- a/packages/core/src/runtime/captureMotionBlur/frames.ts +++ b/packages/core/src/runtime/captureMotionBlur/frames.ts @@ -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)); diff --git a/packages/core/src/runtime/captureMotionBlur/index.test.ts b/packages/core/src/runtime/captureMotionBlur/index.test.ts index 150b142768..ee62e308b1 100644 --- a/packages/core/src/runtime/captureMotionBlur/index.test.ts +++ b/packages/core/src/runtime/captureMotionBlur/index.test.ts @@ -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): 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); + }); +}); diff --git a/packages/core/src/runtime/captureMotionBlur/index.ts b/packages/core/src/runtime/captureMotionBlur/index.ts index 3285eb8579..e7fbd10b44 100644 --- a/packages/core/src/runtime/captureMotionBlur/index.ts +++ b/packages/core/src/runtime/captureMotionBlur/index.ts @@ -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, diff --git a/packages/core/src/runtime/captureMotionBlur/tier.ts b/packages/core/src/runtime/captureMotionBlur/tier.ts index 04e0a315b9..4da2f9cd83 100644 --- a/packages/core/src/runtime/captureMotionBlur/tier.ts +++ b/packages/core/src/runtime/captureMotionBlur/tier.ts @@ -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; diff --git a/packages/studio/src/components/panels/motionBlurPanelModel.test.ts b/packages/studio/src/components/panels/motionBlurPanelModel.test.ts index 414b414a63..ea6678a81e 100644 --- a/packages/studio/src/components/panels/motionBlurPanelModel.test.ts +++ b/packages/studio/src/components/panels/motionBlurPanelModel.test.ts @@ -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,