fix(core): blur scan and eventful reads put back the DOM a timeline call changed (#7191)

* fix(core): blur scan and eventful reads put back the DOM a timeline call changed

With data-motion-blur-events on, the mover scan runs the timeline to the end with
callbacks on and rewinds with callbacks on. GSAP fires a tl.call on a backward
crossing too, so the rewind left the earliest call's DOM effect in place: the
callbacks fixture showed label "B" from frame 0, before its 0.5 s call.

Calls cannot be un-fired, so the scan (and eventful per-frame reads) now journal
DOM mutations with a MutationObserver, land on the frame with callbacks on as
before (keeping JS-side call parity), then undo the journal back to the
pre-scan DOM, which is what a plain seek to the frame produced.

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

* test(engine,producer): callbacks label-early pins become ordinary outside cases

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

* perf(core): the DOM undo skips attributes and text already back at their old value

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

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-11-05 06:38:51 +00:00
committed by GitHub
co-authored by Claude Sonnet 5.5
parent 060e6e4a12
commit 898d0fb00b
7 changed files with 215 additions and 222 deletions
@@ -292,6 +292,82 @@ function boxesKey(boxes: ReadonlyArray<DOMRect | undefined>): number {
return h;
}
type FirstValue = [namespace: string | null, name: string, old: string | null];
type DomJournal = { flush: () => void; undo: () => void; stop: () => void };
function journalDom(doc: Document): DomJournal {
const firstValues = new Map<Node, Map<string, FirstValue>>();
const trees: MutationRecord[] = [];
const fold = (records: MutationRecord[]): void => {
for (const r of records) {
if (r.type === "childList") {
trees.push(r);
continue;
}
const own = firstValues.get(r.target) ?? new Map<string, FirstValue>();
firstValues.set(r.target, own);
const key = `${r.attributeNamespace}:${r.attributeName}`;
if (!own.has(key)) own.set(key, [r.attributeNamespace, r.attributeName ?? "", r.oldValue]);
}
};
const observer = new MutationObserver(fold);
observer.observe(doc, {
subtree: true,
childList: true,
attributes: true,
attributeOldValue: true,
characterData: true,
characterDataOldValue: true,
});
return {
flush: () => fold(observer.takeRecords()),
stop: () => observer.disconnect(),
undo: () => {
fold(observer.takeRecords());
observer.disconnect();
for (const r of trees.reverse()) {
r.addedNodes.forEach((n) => n.parentNode === r.target && r.target.removeChild(n));
r.removedNodes.forEach((n) => r.target.insertBefore(n, r.nextSibling));
}
for (const [node, values] of firstValues) {
for (const [ns, name, old] of values.values()) {
putBack(node, ns, name, old);
}
}
},
};
}
const isElement = (node: Node): node is Element => node.nodeType === 1;
function putBack(node: Node, ns: string | null, name: string, old: string | null): void {
if (!isElement(node)) {
const text = old ?? "";
if ((node as CharacterData).data !== text) (node as CharacterData).data = text;
return;
}
if (node.getAttributeNS(ns, name) === old) return;
if (old === null) node.removeAttributeNS(ns, name);
else node.setAttributeNS(ns, name, old);
}
// A callback a loud seek fired cannot be un-fired: land with callbacks on, then put the DOM back.
export function landThenUndoDom(
seek: (t: number) => void,
doc: Document,
): Omit<DomJournal, "undo"> & { land: (t: number) => void } {
const journal = journalDom(doc);
return {
flush: journal.flush,
stop: journal.stop,
land: (t) => {
seek(t);
journal.undo();
},
};
}
/** Discovery, and whether pose reads need callbacks: when they change an element's style or box. */
export function scanMovers({
seek,
@@ -6,7 +6,7 @@
*/
import { swallow } from "../diagnostics";
import { scanMovers } from "./discover";
import { landThenUndoDom, scanMovers } from "./discover";
import { planFilter, type FilterPlan } from "./filterPlan";
import { readMoverFrames, shutterTimes } from "./frames";
import { createPoseReader } from "./pose";
@@ -123,14 +123,21 @@ export function createFilterTier(
function discover(restoreTo: number): void {
scanned = host.timeline();
const s0 = performance.now();
const found = scanMovers({
scene: root,
durationSeconds: host.durationSeconds(),
fps: host.fps,
seek: host.seek,
events: config.events,
});
seek(restoreTo);
const landing = config.events ? landThenUndoDom(seek, document) : null;
let found: ReturnType<typeof scanMovers>;
try {
found = scanMovers({
scene: root,
durationSeconds: host.durationSeconds(),
fps: host.fps,
seek: host.seek,
events: config.events,
onStep: landing?.flush,
});
(landing?.land ?? seek)(restoreTo);
} finally {
landing?.stop();
}
readEvents = found.readEvents;
movers = found.movers;
pads = found.pads;
@@ -179,19 +186,25 @@ export function createFilterTier(
function plansAt(t: number, engineMode: boolean): Array<[HTMLElement, FilterPlan]> {
if (!reader || host.timeline() !== scanned) discover(t);
if (!reader) return [];
const read = readMoverFrames({
movers,
reader,
seek: readSeek,
restore: readEvents ? undefined : host.holdFrame?.(),
t,
reads: engineMode ? RENDER_READS : PREVIEW_READS,
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
taps: COPIES,
frameW: width,
scene: root,
frameH: height,
});
const landing = readEvents ? landThenUndoDom(readSeek, document) : null;
let read: ReturnType<typeof readMoverFrames>;
try {
read = readMoverFrames({
movers,
reader,
seek: readSeek,
restore: landing?.land ?? host.holdFrame?.(),
t,
reads: engineMode ? RENDER_READS : PREVIEW_READS,
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
taps: COPIES,
frameW: width,
scene: root,
frameH: height,
});
} finally {
landing?.stop();
}
const plans: Array<[HTMLElement, FilterPlan]> = [];
read.els.forEach((el, i) => {
const frame = read.frames[i];
@@ -1,4 +1,7 @@
import gsap from "gsap";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { createGsapAdapter } from "../adapters/gsap";
import type { RuntimeTimelineLike } from "../types";
import {
type CaptureMotionBlurHost,
captureMotionBlurBusy,
@@ -169,6 +172,35 @@ function textAfterStartingAtHalf(): string {
return text;
}
function gsapCallsFilm(movesSlider = false) {
const { root, el, h } = movingHost({
"data-motion-blur": "on",
"data-motion-blur-events": "on",
"data-motion-blur-shutter": "360",
});
const label = root.appendChild(document.createElement("p"));
label.textContent = "A";
const tl = gsap.timeline({ paused: true });
tl.to(el, { x: 300, duration: 1, ease: "none" }, 0)
.call(() => void (label.textContent = "B"), [], 0.5)
.call(() => void label.classList.toggle("on"), [], 0.6);
if (movesSlider) tl.call(() => void (el.style.left = el.style.left ? "" : "40px"), [], 0.2);
const x = () => Number(gsap.getProperty(el, "x")) + (parseFloat(el.style.left) || 0);
el.getBoundingClientRect = () =>
({ left: x(), top: 0, right: x() + 10, bottom: 10, width: 10, height: 10 }) as DOMRect;
const adapter = createGsapAdapter({ getTimeline: () => tl as unknown as RuntimeTimelineLike });
const seek = vi.fn((t: number, suppressEvents: boolean) =>
adapter.seek({ time: t, suppressEvents }),
);
initCaptureMotionBlur({ ...h, seek });
const paintAt = (t: number): string => {
seek(t, false);
void paintCaptureMotionBlur(t, PLAY);
return `${label.textContent}${label.className ? ` ${label.className}` : ""}`;
};
return Object.assign(paintAt, { seek });
}
describe("opt-in and off switches", () => {
it("does nothing for a root that has not opted in", () => {
installHtmlInCanvas();
@@ -1130,6 +1162,27 @@ describe("painting", () => {
expect(textAfterStartingAtHalf()).toBe("first");
});
it.each([
[[0.3], ["A"]],
[[0.55], ["B"]],
[[0.7], ["B on"]],
[
[0.3, 0.7],
["A", "B on"],
],
])("leaves real GSAP calls' DOM as a plain seek does when painting %j", (times, shown) => {
installHtmlInCanvas();
const paintAt = gsapCallsFilm();
expect(times.map(paintAt)).toEqual(shown);
});
it("leaves a call just past the frame unfired after reads that run callbacks", () => {
installHtmlInCanvas();
const paintAt = gsapCallsFilm(true);
expect(paintAt(0.49)).toBe("A");
expect(paintAt.seek.mock.calls.some(([t, quiet]) => t > 0.5 && t < 0.51 && !quiet)).toBe(true);
});
it("fires timeline callbacks during discovery only when the root allows events", () => {
for (const events of [true, false]) {
installHtmlInCanvas();
@@ -36,7 +36,7 @@ import {
import { swallow } from "../diagnostics";
import { createCompositor, type MoverFrame } from "./composite";
import { readMotionBlurSettings } from "../../motionBlurSettings";
import { scanMovers } from "./discover";
import { landThenUndoDom, scanMovers } from "./discover";
import { createFilterTier } from "./filterTier";
import { readMoverFrames, shutterTimes } from "./frames";
import { createPoseReader } from "./pose";
@@ -258,15 +258,24 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
const duration = host.durationSeconds();
const defects = createDefectScan(root, isAccelerated);
const s0 = performance.now();
const found = scanMovers({
scene: root,
durationSeconds: duration,
fps: host.fps,
seek: host.seek,
events: config.events,
onStep: (i, steps) => defects.sample(i, steps, (i / steps) * duration),
});
seek(restoreTo);
const landing = config.events ? landThenUndoDom(seek, document) : null;
let found: ReturnType<typeof scanMovers>;
try {
found = scanMovers({
scene: root,
durationSeconds: duration,
fps: host.fps,
seek: host.seek,
events: config.events,
onStep: (i, steps) => {
landing?.flush();
defects.sample(i, steps, (i / steps) * duration);
},
});
(landing?.land ?? seek)(restoreTo);
} finally {
landing?.stop();
}
readEvents = found.readEvents;
scanDefect = defects.result();
faceNow = defects.facesNow;
@@ -279,20 +288,25 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
function frames(t: number, reads: number): { els: HTMLElement[]; frames: MoverFrame[] } {
if (!reader) return { els: [], frames: [] };
return readMoverFrames({
movers,
reader,
seek: readSeek,
restore: readEvents ? undefined : host.holdFrame?.(),
t,
reads,
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
taps: config.samples,
pads,
frameW: width,
scene: root,
frameH: height,
});
const landing = readEvents ? landThenUndoDom(readSeek, document) : null;
try {
return readMoverFrames({
movers,
reader,
seek: readSeek,
restore: landing?.land ?? host.holdFrame?.(),
t,
reads,
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
taps: config.samples,
pads,
frameW: width,
scene: root,
frameH: height,
});
} finally {
landing?.stop();
}
}
const capture = (): void => {
@@ -8,10 +8,6 @@ export const MEASURED_RENDER_NOISE = 0;
// Worst-tile MAE of the rewind mutation through the render (`callbacks`, 7 workers; caught 8 of 8 runs, always 97.02).
export const MEASURED_RENDER_REWIND_MUTATION = 97.02;
// Worst-tile MAE of each pinned known bug, where it was pinned. A pin passes only within half to double of it.
export const MEASURED_LABEL_EARLY_FRESH_PAINT = 54.3;
export const MEASURED_LABEL_EARLY_RENDER = 53.87;
export const MEASURED_INSIDE_NOISE = 10.993;
export const MEASURED_CONTENT_CUT_MUTATION = 130.129;
export const MEASURED_CLIP_PATH_MUTATION = 124.322;
@@ -3,11 +3,8 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
import {
compareTiles,
meanFrame,
tilesOutsideRegion,
trailMask,
withinSymptomBand,
type Differential,
type Rect,
type Rgba,
} from "./__fixtures__/blurDifferential.js";
import { closeTestChrome } from "./__fixtures__/loopback.js";
@@ -18,10 +15,7 @@ import {
openFixture,
} from "./__fixtures__/motionBlur/blurPage.js";
import { FIXTURES, type BlurFixture } from "./__fixtures__/motionBlur/fixtures.js";
import {
INVARIANTS,
MEASURED_LABEL_EARLY_FRESH_PAINT,
} from "./__fixtures__/motionBlur/thresholds.js";
import { INVARIANTS } from "./__fixtures__/motionBlur/thresholds.js";
const FPS = 30;
const frameTime = (n: number): number => n / FPS;
@@ -29,28 +23,7 @@ const SUB_FRAME_DIVISIONS = 24;
const SHUTTER_SECONDS = 240 / 360 / FPS;
const CASE_TIMEOUT_MS = 60_000;
interface KnownBug {
reason: string;
/** The element whose rect every bad tile must touch. */
regionId: string;
/** Worst-tile MAE of the symptom where it was pinned. */
measuredMae: number;
}
const LABEL_EARLY: KnownBug = {
reason: "callbacks shows its label B before the call that sets it",
regionId: "label",
measuredMae: MEASURED_LABEL_EARLY_FRESH_PAINT,
};
/** Cases where blur on really differs from blur off today. They pin the symptom and fail once it is fixed. */
const KNOWN_REAL_DIFFERENCES = new Map<string, KnownBug>([
["outside:callbacks@0.2", LABEL_EARLY],
["outside:callbacks@0.3", LABEL_EARLY],
["outside:callbacks@0.4", LABEL_EARLY],
]);
/** Before the label's first call: blur on gets it wrong at these frames, so they are the known-bug cases above. */
/** Before the label's first call: a regression guard that a scan leaves no call's DOM behind to show it early. */
const EXTRA_OUTSIDE_TIMES = new Map<string, readonly number[]>([
["callbacks", [frameTime(6), frameTime(9), frameTime(12)]],
]);
@@ -103,32 +76,17 @@ function firstFive(d: Differential): string {
return JSON.stringify(d.bad.slice(0, 5));
}
async function measureOutside(
browser: Browser,
f: BlurFixture,
t: number,
regionId?: string,
): Promise<{ d: Differential; region: Rect }> {
const { offFrames, region } = await onFreshPage(browser, f, "off", async (p) => ({
offFrames: await captureInOrder(p, neighbourTimes(t)),
region: await elementRect(p, regionId),
}));
async function measureOutside(browser: Browser, f: BlurFixture, t: number): Promise<Differential> {
const offFrames = await onFreshPage(browser, f, "off", (p) =>
captureInOrder(p, neighbourTimes(t)),
);
const onFrame = await onFreshPage(browser, f, "on", (p) => captureFrame(p, t));
const reference = offFrames[INVARIANTS.radiusFrames];
if (!reference) throw new Error("missing reference frame");
const d = compareTiles(reference, onFrame, trailMask(offFrames, radiusPx(f)), "outside", {
return compareTiles(reference, onFrame, trailMask(offFrames, radiusPx(f)), "outside", {
block: INVARIANTS.block,
maxMae: INVARIANTS.outsideMaxMae,
});
return { d, region };
}
async function elementRect(page: Page, id: string | undefined): Promise<Rect> {
const box = await page.evaluate((elementId) => {
const el = elementId ? document.getElementById(elementId) : null;
return el ? el.getBoundingClientRect().toJSON() : null;
}, id);
return box ?? { x: 0, y: 0, width: 0, height: 0 };
}
const caseName = (what: string, f: BlurFixture, t: number): string => `${what}: ${f.name} at ${t}`;
@@ -147,34 +105,12 @@ function fixtureNamed(name: string): BlurFixture {
return f;
}
function defineKnownBugCase(f: BlurFixture, t: number, known: KnownBug): void {
it(
`KNOWN BUG on main: ${known.reason} (outside, ${t} s)`,
async (ctx) => {
if (!supported) ctx.skip();
const { d, region } = await measureOutside(chrome(), f, t, known.regionId);
const fixed = `${known.reason}: this case pins a known bug; if it now passes, delete its \`outside:${f.name}@${t}\` entry from KNOWN_REAL_DIFFERENCES, which makes it an ordinary outside case`;
expect(d.checkedFraction).toBeGreaterThanOrEqual(INVARIANTS.minCheckedFraction);
expect(d.bad.length, fixed).toBeGreaterThan(0);
expect(
tilesOutsideRegion(d.bad, INVARIANTS.block, region, f.dpr),
`a new defect outside the ${known.regionId} rect ${JSON.stringify(region)}: ${firstFive(d)}`,
).toEqual([]);
expect(
withinSymptomBand(d.worstMae, known.measuredMae),
`the pinned symptom changed: re-measure (worst MAE ${d.worstMae.toFixed(2)}, pinned at ${known.measuredMae})`,
).toBe(true);
},
CASE_TIMEOUT_MS,
);
}
function defineOutsideCase(f: BlurFixture, t: number): void {
it(
caseName("outside the trail, blur on equals blur off", f, t),
async (ctx) => {
if (!supported) ctx.skip();
const { d } = await measureOutside(chrome(), f, t);
const d = await measureOutside(chrome(), f, t);
expect(d.bad, `${f.name} ${firstFive(d)}`).toEqual([]);
expect(d.checkedFraction).toBeGreaterThanOrEqual(INVARIANTS.minCheckedFraction);
},
@@ -249,9 +185,7 @@ function defineSubFrameCase(): void {
function defineFixtureCases(f: BlurFixture): void {
for (const t of [...f.checkpoints, ...(EXTRA_OUTSIDE_TIMES.get(f.name) ?? [])]) {
const known = KNOWN_REAL_DIFFERENCES.get(`outside:${f.name}@${t}`);
if (known) defineKnownBugCase(f, t, known);
else defineOutsideCase(f, t);
defineOutsideCase(f, t);
}
for (const t of f.moving) defineInsideCase(f, t);
}
@@ -11,12 +11,8 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { decodePng, distributeFrames, getFfmpegBinary, resolveConfig } from "@hyperframes/engine";
import {
compareTiles,
tilesOutsideRegion,
trailMask,
withinSymptomBand,
type BadBlock,
type Differential,
type Rect,
type Rgba,
} from "../../../../engine/src/services/__fixtures__/blurDifferential.js";
import {
@@ -25,7 +21,6 @@ import {
} from "../../../../engine/src/services/__fixtures__/motionBlur/fixtures.js";
import {
INVARIANTS,
MEASURED_LABEL_EARLY_RENDER,
RENDER_OUTSIDE_MAX_MAE,
} from "../../../../engine/src/services/__fixtures__/motionBlur/thresholds.js";
import { createRenderJob, executeRenderJob } from "../renderOrchestrator.js";
@@ -36,8 +31,8 @@ const HAS_FFMPEG = spawnSync(FFMPEG, ["-version"], { encoding: "utf-8" }).status
const FPS = 30;
const WORKERS = 4;
/**
* `callbacks` calls at frames 15, 16 and 30. A worker whose block starts on a call
* sees the bug only by timing; one starting strictly between the calls always does (#6967).
* `callbacks` calls at frames 15, 16 and 30. A worker whose block starts strictly between the
* calls shows any call state its scan leaves behind; one starting on a call only by timing (#6967).
* 7 workers over 60 frames start at 0, 9, 18, 27, 36, 45 and 54.
*/
const WORKERS_BY_FIXTURE = new Map<string, number>([["callbacks", 7]]);
@@ -57,57 +52,6 @@ const FIXTURE_NAMES = [
"overflow-wordmark",
] as const;
interface KnownBug {
title: string;
reason: string;
/** The element whose rect every bad tile must touch, in CSS px from the fixture's markup. */
regionId: string;
region: (f: BlurFixture) => Rect;
/** Output frames in which blur on really differs from blur off today. */
frames: (n: number) => boolean;
/** Worst-tile MAE of the symptom where it was pinned. */
measuredMae: number;
/** Set when the symptom must appear in those frames: what to edit when it no longer does. */
ifFixed?: string;
}
const markupOf = (f: BlurFixture, id: string): string =>
new RegExp(`<[^>]*id="${id}"[^>]*>`).exec(f.html("off"))?.[0] ?? "";
function cssPx(f: BlurFixture, id: string, property: string): number {
const px = new RegExp(`(?:^|[;"\\s])${property}:\\s*(-?[\\d.]+)px`).exec(markupOf(f, id))?.[1];
if (px === undefined) throw new Error(`#${id} in ${f.name} has no ${property} in px`);
return Number(px);
}
/** One glyph of the element's text: left and top from its inline style; a monospace advance is 0.6 em, a line 1.2 em. */
function glyphFromMarkup(f: BlurFixture, id: string): Rect {
const size = Number(/font:\s*\d+\s+([\d.]+)px/.exec(markupOf(f, id))?.[1]);
if (Number.isNaN(size)) throw new Error(`#${id} in ${f.name} has no font size in px`);
return { x: cssPx(f, id, "left"), y: cssPx(f, id, "top"), width: 0.6 * size, height: 1.2 * size };
}
/**
* Cases where blur on really differs from blur off today. Whatever differs must stay inside the
* pinned region and keep its measured size. A case with `ifFixed` also requires the symptom to
* appear and fails once it is fixed; the others only bound it, because it is a race.
*/
const KNOWN_REAL_DIFFERENCES = new Map<string, KnownBug>([
[
"callbacks",
{
title: "KNOWN BUG on main: callbacks shows its label B before the call that sets it",
reason: "callbacks shows its label B before the call that sets it",
regionId: "label",
region: (f) => glyphFromMarkup(f, "label"),
frames: (n) => n < 15,
measuredMae: MEASURED_LABEL_EARLY_RENDER,
ifFixed:
"delete the callbacks entry from KNOWN_REAL_DIFFERENCES; keep WORKERS_BY_FIXTURE and REQUIRED_STARTS, which make the rewind regression visible after the fix",
},
],
]);
interface Renders {
off: Rgba[];
off2: Rgba[];
@@ -210,38 +154,6 @@ function firstBad(results: readonly FrameResult[]): string {
);
}
function expectNoNewDefect(f: BlurFixture, known: KnownBug, bad: readonly BadBlock[]): void {
const region = known.region(f);
expect(
tilesOutsideRegion(bad, INVARIANTS.block, region, 1),
`a new defect outside the ${known.regionId} rect ${JSON.stringify(region)}`,
).toEqual([]);
}
function expectKnownBug(f: BlurFixture, known: KnownBug, results: readonly FrameResult[]): void {
const pinned = results.filter((x) => known.frames(x.frame));
const rest = results.filter((x) => !known.frames(x.frame));
const bad = pinned.flatMap((x) => x.outside.bad);
if (known.ifFixed) {
expect(
bad.length,
`${known.reason}: this case pins a known bug; if it now passes, ${known.ifFixed}`,
).toBeGreaterThan(0);
}
expectNoNewDefect(f, known, bad);
if (bad.length > 0) {
const worstMae = Math.max(...pinned.map((x) => x.outside.worstMae));
expect(
withinSymptomBand(worstMae, known.measuredMae),
`the pinned symptom changed: re-measure (worst MAE ${worstMae.toFixed(2)}, pinned at ${known.measuredMae})`,
).toBe(true);
}
expect(
rest.flatMap((x) => x.outside.bad),
`${f.name} outside the pinned frames ${firstBad(rest)}`,
).toEqual([]);
}
function expectEqualOutsideTrail(f: BlurFixture, results: readonly FrameResult[]): void {
expect(
results.flatMap((x) => x.outside.bad),
@@ -282,13 +194,8 @@ function defineFixtureCases(f: BlurFixture): void {
}
});
const known = KNOWN_REAL_DIFFERENCES.get(f.name);
if (known) {
it(known.title, () => expectKnownBug(f, known, results));
} else {
it("outside the trail, blur on equals blur off in every frame", () =>
expectEqualOutsideTrail(f, results));
}
it("outside the trail, blur on equals blur off in every frame", () =>
expectEqualOutsideTrail(f, results));
if (f.name === "held-card") {
it("blurs the card, so the comparison is not vacuous", () => {