Skip to content

Write HTML. Render video. Built for agents.

feat(core,producer): decide blur defects once per timeline, off on routes that cannot host it (#5990)

Vance Ingalls08c185d908d6
diff --git a/packages/core/src/htmlInCanvasDefects.test.ts b/packages/core/src/htmlInCanvasDefects.test.ts
index b7965abfdf..5a6cca81d2 100644
--- a/packages/core/src/htmlInCanvasDefects.test.ts
+++ b/packages/core/src/htmlInCanvasDefects.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import {
chromeMajor,
+ createDefectScan,
findCaptureDefect,
scanBackfaceDefect,
type DefectEnv,
@@ -30,6 +31,21 @@ const env = (over: Partial<DefectEnv> = {}): DefectEnv => ({
const code = (root: HTMLElement, e: DefectEnv) => findCaptureDefect(root, e)?.code ?? null;
+/** Every Chrome the render and preview browsers can be, and an unknown one. */
+const VERSIONS = [152, 155, 156, 157, 158, null] as const;
+
+/** The defect found with the page's user agent set to `major`. */
+function codeOn(major: number | null, root: HTMLElement, e: DefectEnv): string | null {
+ const spy = vi
+ .spyOn(window.navigator, "userAgent", "get")
+ .mockReturnValue(ua(major).navigator.userAgent);
+ try {
+ return code(root, e);
+ } finally {
+ spy.mockRestore();
+ }
+}
+
afterEach(() => {
document.body.innerHTML = document.head.innerHTML = "";
vi.unstubAllGlobals();
@@ -57,9 +73,8 @@ describe("nested-capture-canvas", () => {
it("is found on every version, in either API form", () => {
for (const attr of ["layoutsubtree", 'content="drawable"']) {
const root = mount(`<canvas ${attr}></canvas>`);
- for (const major of [152, 158, null]) {
- expect(code(root, env({ win: ua(major) }))).toBe("nested-capture-canvas");
- }
+ for (const major of VERSIONS)
+ expect(codeOn(major, root, env())).toBe("nested-capture-canvas");
}
});
});
@@ -67,57 +82,174 @@ describe("nested-capture-canvas", () => {
describe("accelerated-canvas", () => {
const gl = (root: HTMLElement) => env({ isAccelerated: (c) => root.contains(c) });
- it("applies below 157 and when the version is unknown, not from 157", () => {
+ it("applies on every version, 157 and 158 included", () => {
const root = mount("<canvas></canvas>");
- for (const major of [152, 155, null]) {
- expect(code(root, { ...gl(root), win: ua(major) })).toBe("accelerated-canvas");
+ for (const major of VERSIONS) {
+ expect(codeOn(major, root, gl(root))).toBe("accelerated-canvas");
+ }
+ });
+
+ it("finds a WebGL canvas outside the root, where a render's shader compositor puts it", () => {
+ const root = mount("");
+ const outside = document.createElement("canvas");
+ document.body.append(outside);
+ for (const major of VERSIONS) {
+ expect(codeOn(major, root, env({ isAccelerated: (c) => c === outside }))).toBe(
+ "accelerated-canvas",
+ );
}
- for (const major of [157, 158]) expect(code(root, { ...gl(root), win: ua(major) })).toBeNull();
});
it("ignores a canvas the page did not give a WebGL context", () => {
- expect(code(mount("<canvas></canvas>"), env({ win: ua(152) }))).toBeNull();
+ expect(code(mount("<canvas></canvas>"), env())).toBeNull();
});
});
describe("iframe-in-root", () => {
it("applies on every version: a reload cannot be undone", () => {
const root = mount('<div><iframe src="about:blank"></iframe></div>');
- for (const major of [152, 157, 158])
- expect(code(root, env({ win: ua(major) }))).toBe("iframe-in-root");
+ for (const major of VERSIONS) expect(codeOn(major, root, env())).toBe("iframe-in-root");
});
it("is not reported for a composition without an iframe", () => {
expect(code(mount("<div><img></div>"), env())).toBeNull();
});
+
+ it("also covers <object>, <embed> and defined custom elements, which are re-initialised too", () => {
+ customElements.define("x-defect-card", class extends HTMLElement {});
+ for (const html of ["<object></object>", "<embed>", "<x-defect-card></x-defect-card>"])
+ expect(findCaptureDefect(mount(html), env())).toMatchObject({
+ code: "iframe-in-root",
+ reason: expect.stringContaining("re-initialised when blur wraps the root"),
+ });
+ expect(code(mount("<x-defect-undefined></x-defect-undefined>"), env())).toBeNull();
+ });
+
+ it("is found by the timeline scan at any step, and says where it first appeared", () => {
+ const root = mount("");
+ const scan = createDefectScan(root, () => false);
+ scan.sample(0, 10, 0);
+ root.append(document.createElement("iframe"));
+ scan.sample(3, 10, 1.5);
+ expect(scan.result()).toMatchObject({ code: "iframe-in-root" });
+ expect(scan.result()?.reason).toContain("t=1.5s");
+ });
+});
+
+describe("facesNow: the scan's candidates, read at the current time", () => {
+ it("sees a hidden face flip into 3D after the scan, without rescanning", () => {
+ const root = mount('<div id="card" style="backface-visibility: hidden"></div>');
+ const scan = createDefectScan(root, () => false);
+ scan.sample(0, 10, 0);
+ expect(scan.facesNow()).toBe(false);
+ const card = document.getElementById("card");
+ if (card) card.style.transform = "rotateY(100deg)";
+ expect(scan.facesNow()).toBe(true);
+ if (card) card.style.transform = "none";
+ expect(scan.facesNow()).toBe(false);
+ });
+
+ it("takes in a face an animation keys, and keeps it once the animation is gone", () => {
+ const root = mount('<div style="transform-style: preserve-3d"><div id="f"></div></div>');
+ const face = root.querySelector<HTMLElement>("#f") ?? root;
+ const scan = createDefectScan(root, () => false);
+ animating(face, [{ backfaceVisibility: "hidden" }]);
+ scan.sample(0, 10, 0);
+ expect(scan.result()).toBeNull();
+ expect(scan.facesNow()).toBe(false);
+ // The rule comes after the scan read the sheets: only the animation made the face a candidate.
+ document.head.innerHTML = "<style>.hide{backface-visibility:hidden}</style>";
+ face.className = "hide";
+ expect(scan.facesNow()).toBe(true);
+ Object.assign(document, { getAnimations: () => [] });
+ scan.sample(10, 10, 1);
+ expect(scan.result()?.code).toBe("backface-visibility");
+ });
+
+ it("knows only the elements the scan's last face check found", () => {
+ const root = mount("");
+ const scan = createDefectScan(root, () => false);
+ scan.sample(0, 10, 0);
+ const late = document.createElement("div");
+ late.setAttribute("style", "backface-visibility: hidden; transform: rotateY(100deg)");
+ root.append(late);
+ expect(scan.facesNow()).toBe(false);
+ });
});
describe("root-transform", () => {
- it("applies below 157 and when the version is unknown, not from 157", () => {
+ it("applies on every version, 157 and 158 included", () => {
const root = mount("", "transform: scale(0.5)");
- expect(code(root, env({ win: ua(152) }))).toBe("root-transform");
- expect(code(root, env({ win: ua(156) }))).toBe("root-transform");
- expect(code(root, env({ win: ua(null) }))).toBe("root-transform");
- expect(code(root, env({ win: ua(157) }))).toBeNull();
- expect(code(root, env({ win: ua(158) }))).toBeNull();
+ for (const major of VERSIONS) expect(codeOn(major, root, env())).toBe("root-transform");
});
it("ignores a root without a transform", () => {
- expect(code(mount(""), env({ win: ua(152) }))).toBeNull();
+ expect(code(mount(""), env())).toBeNull();
+ });
+
+ it("ignores an identity transform, 2D or 3D, which changes nothing on screen", () => {
+ for (const t of [
+ "matrix(1, 0, 0, 1, 0, 0)",
+ "matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)",
+ ]) {
+ for (const major of VERSIONS)
+ expect(codeOn(major, mount("", `transform: ${t}`), env())).toBeNull();
+ }
+ });
+
+ it("reports a real translate, scale or rotate, 2D or 3D", () => {
+ for (const t of [
+ "translateX(3px)",
+ "scale(1.01)",
+ "rotate(1deg)",
+ "matrix(1, 0, 0, 1, 0, 2)",
+ "matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 5, 1)",
+ ]) {
+ expect(code(mount("", `transform: ${t}`), env())).toBe("root-transform");
+ }
+ });
+});
+
+describe("root individual transform properties and blend mode", () => {
+ it("reports a root moved by scale, rotate or translate, not an identity one", () => {
+ for (const t of ["scale: 0.5", "rotate: 3deg", "translate: 5px 0"])
+ expect(code(mount("", t), env())).toBe("root-transform");
+ for (const t of ["scale: 1", "rotate: 0deg", "translate: 0px"])
+ expect(code(mount("", t), env())).toBeNull();
+ });
+
+ it("reports a root mix-blend-mode other than normal", () => {
+ for (const major of VERSIONS)
+ expect(codeOn(major, mount("", "mix-blend-mode: multiply"), env())).toBe("root-blend-mode");
+ expect(code(mount("", "mix-blend-mode: normal"), env())).toBeNull();
});
});
describe("root-opacity", () => {
- it("applies from 155 and when the version is unknown, not on 152", () => {
+ it("applies on every version, 152 included", () => {
const root = mount("", "opacity: 0.5");
- expect(code(root, env({ win: ua(152) }))).toBeNull();
- expect(code(root, env({ win: ua(155) }))).toBe("root-opacity");
- expect(code(root, env({ win: ua(158) }))).toBe("root-opacity");
- expect(code(root, env({ win: ua(null) }))).toBe("root-opacity");
+ for (const major of VERSIONS) expect(codeOn(major, root, env())).toBe("root-opacity");
});
it("ignores a fully opaque root", () => {
- expect(code(mount("", "opacity: 1"), env({ win: ua(158) }))).toBeNull();
+ expect(code(mount("", "opacity: 1"), env())).toBeNull();
+ });
+});
+
+describe("no version gating", () => {
+ // Mutation guard: a defect that once applied only below 157 (or from 155) must still block on
+ // 158 (or 152). Reintroducing any from/until test on the Chrome major fails this.
+ it("blocks a WebGL canvas, a root transform and a root fade on every version alike", () => {
+ const fixtures: Array<[string, () => HTMLElement, DefectEnv]> = [
+ ["accelerated-canvas", () => mount("<canvas></canvas>"), env({ isAccelerated: () => true })],
+ ["root-transform", () => mount("", "transform: translateX(5px)"), env()],
+ ["root-opacity", () => mount("", "opacity: 0.2"), env()],
+ ];
+ for (const [expected, build, e] of fixtures) {
+ const root = build();
+ const seen = new Set(VERSIONS.map((major) => codeOn(major, root, e)));
+ expect([...seen]).toEqual([expected]);
+ }
});
});
@@ -126,8 +258,8 @@ describe("backface-visibility", () => {
it("is found on every version once the scan saw one", () => {
const root = mount("");
- for (const major of [152, 155, 157, 158, null]) {
- expect(code(root, env({ backface: true, win: ua(major) }))).toBe("backface-visibility");
+ for (const major of VERSIONS) {
+ expect(codeOn(major, root, env({ backface: true }))).toBe("backface-visibility");
}
});
@@ -138,6 +270,12 @@ describe("backface-visibility", () => {
expect(scanBackfaceDefect(root)).toBe(true);
});
+ it("scan: a face turned in 3D by the individual rotate or translate properties", () => {
+ for (const own of ["rotate: y 180deg", "rotate: 0 1 0 180deg", "translate: 0 0 10px"])
+ expect(scanBackfaceDefect(mount(`<div style="${face}; ${own}"></div>`))).toBe(true);
+ expect(scanBackfaceDefect(mount(`<div style="${face}; rotate: 90deg"></div>`))).toBe(false);
+ });
+
it("scan: a face under a perspective ancestor", () => {
const root = mount(`<div style="perspective: 800px"><div style="${face}"></div></div>`);
expect(scanBackfaceDefect(root)).toBe(true);
@@ -318,6 +456,46 @@ describe("backface-visibility rules the page reaches indirectly", () => {
describe("order", () => {
it("reports the first applicable defect", () => {
const root = mount("<canvas layoutsubtree></canvas>", "opacity: 0.5");
- expect(code(root, env({ win: ua(158), backface: true }))).toBe("nested-capture-canvas");
+ expect(code(root, env({ backface: true }))).toBe("nested-capture-canvas");
+ });
+});
+
+describe("createDefectScan", () => {
+ const face = "backface-visibility: hidden";
+ const run = (root: HTMLElement, steps: number, each?: (i: number) => void) => {
+ const scan = createDefectScan(root, () => false);
+ for (let i = 0; i <= steps; i++) {
+ each?.(i);
+ scan.sample(i, steps, i / 10);
+ }
+ return scan.result();
+ };
+
+ it("is clean for a quiet timeline", () => {
+ expect(run(mount(""), 20)).toBeNull();
+ });
+
+ it("names the defect and when it was first seen", () => {
+ const root = mount("");
+ const found = run(root, 20, (i) => {
+ if (i === 7) root.style.opacity = "0.5";
+ });
+ expect(found?.code).toBe("root-opacity");
+ expect(found?.reason).toContain("first seen at t=0.7s");
+ });
+
+ it("sees a rotation that a later step applies to a face with no 3D context at the start", () => {
+ const root = mount(`<div id="f" style="${face}"></div>`);
+ const el = root.querySelector<HTMLElement>("#f");
+ const found = run(root, 20, (i) => {
+ if (i === 12 && el) el.style.transform = "rotateY(90deg)";
+ });
+ expect(found?.code).toBe("backface-visibility");
+ expect(found?.reason).toContain("first seen at t=2.0s");
+ });
+
+ it("leaves a flat face alone however long the timeline", () => {
+ const root = mount(`<div style="${face}; transform: translateX(40px)"></div>`);
+ expect(run(root, 40)).toBeNull();
});
});
diff --git a/packages/core/src/htmlInCanvasDefects.ts b/packages/core/src/htmlInCanvasDefects.ts
index fa30b9d269..a667231eb1 100644
--- a/packages/core/src/htmlInCanvasDefects.ts
+++ b/packages/core/src/htmlInCanvasDefects.ts
@@ -17,96 +17,94 @@ export interface DefectEnv {
isAccelerated: (canvas: HTMLCanvasElement) => boolean;
/** Result of `scanBackfaceDefect`, refreshed whenever the scene is rescanned. */
backface: boolean;
- win?: UaWindow;
}
+// Every defect blocks on every Chrome version: render and preview browsers can differ.
interface Defect {
code: string;
reason: string;
- /** Chrome majors the defect applies to; null bounds are open. */
- from: number | null;
- until: number | null;
detect: (root: HTMLElement, env: DefectEnv) => boolean;
}
const hasHidden3dFace = (_root: HTMLElement, env: DefectEnv): boolean => env.backface;
+// The whole document: a render's shader-transition canvas sits in <body>, preview's in the root.
const hasAcceleratedCanvas = (root: HTMLElement, env: DefectEnv): boolean =>
- Array.from(root.querySelectorAll("canvas")).some(env.isAccelerated);
+ Array.from(root.ownerDocument.querySelectorAll("canvas")).some(env.isAccelerated);
+const IDENTITY_TRANSFORM =
+ /^matrix\(\s*1,\s*0,\s*0,\s*1,\s*0,\s*0\s*\)$|^matrix3d\(\s*1,\s*0,\s*0,\s*0,\s*0,\s*1,\s*0,\s*0,\s*0,\s*0,\s*1,\s*0,\s*0,\s*0,\s*0,\s*1\s*\)$/;
+
+const moves = (value: string | undefined, identity: number): boolean =>
+ !!value && value !== "none" && !value.split(/\s+/).every((p) => parseFloat(p) === identity);
+
+// `scale`, `rotate` and `translate` transform the root just as `transform` does.
const hasRootTransform = (root: HTMLElement): boolean => {
- const t = getComputedStyle(root).transform;
- return t !== "none" && t !== "";
+ const cs = getComputedStyle(root);
+ const t = cs.transform.trim();
+ if (moves(cs.scale, 1) || moves(cs.rotate, 0) || moves(cs.translate, 0)) return true;
+ return t !== "none" && t !== "" && !IDENTITY_TRANSFORM.test(t);
+};
+
+const hasRootBlend = (root: HTMLElement): boolean => {
+ const mode = getComputedStyle(root).mixBlendMode;
+ return !!mode && mode !== "normal";
};
const hasRootOpacity = (root: HTMLElement): boolean =>
Number.parseFloat(getComputedStyle(root).opacity) < 1;
-const hasIframe = (root: HTMLElement): boolean => root.querySelector("iframe") !== null;
+// Moving the root tears these down and starts them again: a frame reloads, a custom element reconnects.
+const hasReinitialised = (root: HTMLElement): boolean =>
+ root.querySelector("iframe, object, embed") !== null ||
+ Array.from(root.querySelectorAll("*")).some(
+ (el) => el.localName.includes("-") && customElements.get(el.localName) !== undefined,
+ );
-// Chrome <=156 captures a WebGL canvas frozen at its pre-wrap frame; 157 fixed it.
const DEFECTS: readonly Defect[] = [
{
code: "nested-capture-canvas",
reason: "the composition already uses html-in-canvas",
- from: null,
- until: null,
detect: (root) => root.querySelector(CAPTURE_CANVAS_SELECTOR) !== null,
},
{
+ // Chrome <=156 captures the canvas frozen at its pre-wrap frame; 157 fixed it.
code: "accelerated-canvas",
reason: "the composition draws a WebGL/WebGPU canvas, which html-in-canvas captures frozen",
- from: null,
- until: 157,
detect: hasAcceleratedCanvas,
},
{
code: "backface-visibility",
reason: "backface-visibility: hidden inside a 3D transform is drawn mirrored by html-in-canvas",
- from: null,
- until: null,
detect: hasHidden3dFace,
},
{
code: "iframe-in-root",
- reason: "the composition contains an <iframe>, which reloads whenever motion blur wraps it",
- from: null,
- until: null,
- detect: hasIframe,
+ reason:
+ "the composition contains an <iframe>, <object>, <embed> or custom element, which is re-initialised when blur wraps the root",
+ detect: hasReinitialised,
},
{
code: "root-transform",
- reason: "html-in-canvas ignores a transform on the composition root in this Chrome version",
- from: null,
- until: 157,
+ reason: "html-in-canvas can ignore a transform on the composition root",
detect: hasRootTransform,
},
{
code: "root-opacity",
- reason: "html-in-canvas ignores the composition root's own opacity in this Chrome version",
- from: 155,
- until: null,
+ reason: "html-in-canvas can ignore the composition root's own opacity",
detect: hasRootOpacity,
},
+ {
+ code: "root-blend-mode",
+ reason: "html-in-canvas can ignore the composition root's own mix-blend-mode",
+ detect: hasRootBlend,
+ },
];
-function applies(defect: Defect, major: number | null): boolean {
- if (major === null) return true;
- return (
- (defect.from === null || major >= defect.from) &&
- (defect.until === null || major < defect.until)
- );
-}
-
-/** The first defect that makes html-in-canvas capture this root wrongly in this browser, or null. */
+/** The first defect that makes html-in-canvas capture this root wrongly in any supported browser, or null. */
export function findCaptureDefect(root: HTMLElement, env: DefectEnv): CaptureDefect | null {
- const major = chromeMajor(env.win);
- for (const defect of DEFECTS) {
- if (applies(defect, major) && defect.detect(root, env)) {
- return { code: defect.code, reason: defect.reason };
- }
- }
- return null;
+ const defect = DEFECTS.find((d) => d.detect(root, env));
+ return defect ? { code: defect.code, reason: defect.reason } : null;
}
const FACE_3D_TRANSFORM = /perspective\(|rotate3d\(|rotate[XY]\(|matrix3d\(/;
@@ -118,8 +116,16 @@ function isHidden(cs: CSSStyleDeclaration): boolean {
);
}
+const individualTurnsIn3d = (cs: CSSStyleDeclaration): boolean =>
+ !/^(none|-?[\d.]+[a-z]+)?$/.test(cs.rotate ?? "") ||
+ (cs.translate ?? "").trim().split(/\s+/).length > 2;
+
function transformsIn3d(el: HTMLElement, cs: CSSStyleDeclaration): boolean {
- return FACE_3D_TRANSFORM.test(cs.transform) || FACE_3D_TRANSFORM.test(el.style.transform);
+ return (
+ FACE_3D_TRANSFORM.test(cs.transform) ||
+ FACE_3D_TRANSFORM.test(el.style.transform) ||
+ individualTurnsIn3d(cs)
+ );
}
function in3dContext(el: HTMLElement, root: HTMLElement): boolean {
@@ -276,14 +282,57 @@ function backfaceCandidates(root: HTMLElement, selectors: string[]): Set<HTMLEle
}
/**
- * A `backface-visibility: hidden` element in a 3D context (preserve-3d, perspective or a 3D
- * transform), which html-in-canvas draws anyway. Flat uses are a harmless performance hack.
- * Residual: a rotation that only appears later, via a tween on an element with no 3D context at
- * scan time, is not seen.
+ * Whether a `backface-visibility: hidden` element is in a 3D context right now (flat uses are
+ * harmless); call it at several timeline times to see a rotation that a later tween applies.
*/
+function createBackfaceCheck(root: HTMLElement): { scan: () => boolean; recheck: () => boolean } {
+ const selectors = hiddenSelectors();
+ let candidates = new Set<HTMLElement>();
+ const anyFace = (): boolean => {
+ for (const el of candidates) {
+ if (isHidden(getComputedStyle(el)) && in3dContext(el, root)) return true;
+ }
+ return false;
+ };
+ return {
+ scan: () => {
+ candidates = new Set([...candidates, ...backfaceCandidates(root, selectors)]);
+ return anyFace();
+ },
+ recheck: anyFace,
+ };
+}
+
export function scanBackfaceDefect(root: HTMLElement): boolean {
- for (const el of backfaceCandidates(root, hiddenSelectors())) {
- if (isHidden(getComputedStyle(el)) && in3dContext(el, root)) return true;
- }
- return false;
+ return createBackfaceCheck(root).scan();
+}
+
+const FACE_EVERY = 10;
+
+export interface DefectScan {
+ sample: (i: number, steps: number, at: number) => void;
+ result: () => CaptureDefect | null;
+ facesNow: () => boolean;
+}
+
+export function createDefectScan(
+ root: HTMLElement,
+ isAccelerated: DefectEnv["isAccelerated"],
+): DefectScan {
+ const faces = createBackfaceCheck(root);
+ let found: CaptureDefect | null = null;
+ return {
+ sample: (i, steps, at) => {
+ if (found) return;
+ const checkFaces = i % FACE_EVERY === 0 || i === steps;
+ const defect = findCaptureDefect(root, {
+ isAccelerated,
+ backface: checkFaces && faces.scan(),
+ });
+ if (defect)
+ found = { ...defect, reason: `${defect.reason} (first seen at t=${at.toFixed(1)}s)` };
+ },
+ result: () => found,
+ facesNow: faces.recheck,
+ };
}
diff --git a/packages/core/src/runtime/captureMotionBlur/discover.test.ts b/packages/core/src/runtime/captureMotionBlur/discover.test.ts
index 2d74f448b0..323ef0ffcd 100644
--- a/packages/core/src/runtime/captureMotionBlur/discover.test.ts
+++ b/packages/core/src/runtime/captureMotionBlur/discover.test.ts
@@ -41,6 +41,67 @@ describe("discoverMovers", () => {
expect(movers).toEqual([fast]);
});
+ // A 100 px jump inside one scan step at 5 s: slow to a still-style baseline, fast between two steps.
+ function jumpScene() {
+ const scene = document.createElement("div");
+ const jumper = element(scene, "jumper");
+ const seek = (t: number): void => {
+ jumper.style.transform = `translateX(${100 * Math.min(1, Math.max(0, (t - 5) / 0.04))}px)`;
+ };
+ return { scene, jumper, seek };
+ }
+
+ it("finds the same movers whatever time the scan is started at", () => {
+ const found = [0, 3, 7].map((start) => {
+ const { scene, jumper, seek } = jumpScene();
+ seek(start);
+ const { movers } = discoverMovers({ scene, durationSeconds: 10, fps: 30, seek });
+ return movers.map((m) => m === jumper);
+ });
+ expect(found).toEqual([[true], [true], [true]]);
+ });
+
+ it("does not count an ancestor's pan as a child's move when the child's style first changes", () => {
+ // A 100 x 100 camera wrapper pans 1 px/frame; a label inside it fades in at 8 s.
+ const scene = document.createElement("div");
+ scene.getBoundingClientRect = () => ({ width: 100, height: 100 }) as DOMRect;
+ const camera = element(scene, "camera", 100);
+ const label = element(camera, "label");
+ const x = (el: HTMLElement): number => parseFloat(el.style.transform.slice(11)) || 0;
+ label.getBoundingClientRect = () => {
+ const left = x(camera) + x(label);
+ return { left, top: 0, right: left + 10, bottom: 10, width: 10, height: 10 } as DOMRect;
+ };
+ const seek = (t: number): void => {
+ camera.style.transform = `translateX(${30 * t}px)`;
+ label.style.opacity = t < 8 ? "0" : "1";
+ };
+ seek(0);
+ const { movers } = discoverMovers({ scene, durationSeconds: 10, fps: 30, seek });
+ expect(movers).toEqual([]);
+ });
+
+ it("reports each scan step after its seek, in order, without seeking more", () => {
+ const { scene, seek } = setup();
+ const events: string[] = [];
+ const plain = vi.fn(seek);
+ discoverMovers({ scene, durationSeconds: 1, fps: 30, seek: plain });
+ const traced = vi.fn((t: number) => {
+ events.push(`seek ${t.toFixed(3)}`);
+ seek(t);
+ });
+ discoverMovers({
+ scene,
+ durationSeconds: 1,
+ fps: 30,
+ seek: traced,
+ onStep: (i, steps) => events.push(`step ${i}/${steps}`),
+ });
+ expect(traced.mock.calls.length).toBe(plain.mock.calls.length);
+ expect(events.slice(0, 4)).toEqual(["seek 0.000", "step 0/30", "seek 0.033", "step 1/30"]);
+ expect(events.at(-1)).toBe("step 30/30");
+ });
+
it("marks every changing element dynamic, slow and opted-out ones included", () => {
const { scene, fast, fastChild, slow, still, off, seek } = setup();
const { dynamic } = discoverMovers({ scene, durationSeconds: 1, fps: 30, seek });
diff --git a/packages/core/src/runtime/captureMotionBlur/discover.ts b/packages/core/src/runtime/captureMotionBlur/discover.ts
index dc758efde6..6276adb097 100644
--- a/packages/core/src/runtime/captureMotionBlur/discover.ts
+++ b/packages/core/src/runtime/captureMotionBlur/discover.ts
@@ -36,6 +36,7 @@ export interface DiscoverOptions {
fps: number;
/** Seek the composition (timeline + adapters) to a time. */
seek: (t: number) => void;
+ onStep?: (i: number, steps: number) => void;
}
export interface Discovery {
@@ -151,10 +152,27 @@ function edgeShift(a: DOMRect | undefined, b: DOMRect | undefined): number {
);
}
-export function discoverMovers({ scene, durationSeconds, fps, seek }: DiscoverOptions): Discovery {
+/** Boxes of `els` now, but with their inline style put back: their own change left out. */
+function rectsAtStyle(els: HTMLElement[], styles: string[]): DOMRect[] {
+ const now = els.map(styleKey);
+ els.forEach((el, i) => el.setAttribute("style", styles[i] ?? ""));
+ const rects = els.map((el) => el.getBoundingClientRect());
+ els.forEach((el, i) => el.setAttribute("style", now[i] ?? ""));
+ return rects;
+}
+
+export function discoverMovers({
+ scene,
+ durationSeconds,
+ fps,
+ seek,
+ onStep,
+}: DiscoverOptions): Discovery {
+ seek(0);
const all = [...scene.querySelectorAll("*")].filter(isHtmlElement);
const dynamic = new Set<Element>(pageAnimated(scene));
const first = all.map(styleKey);
+ const baseRects = all.map((el) => el.getBoundingClientRect());
const frames = Math.max(1, Math.round(durationSeconds * fps));
// One pass, about every other frame on a typical composition. A whip shorter than one step
// can be under-measured; ponytail: raise SCAN_STEPS if a fast move goes unblurred.
@@ -166,19 +184,35 @@ export function discoverMovers({ scene, durationSeconds, fps, seek }: DiscoverOp
const alphaCache = new Map<Bitmap, boolean>();
const sceneRect = scene.getBoundingClientRect();
const largeArea = sceneRect.width * sceneRect.height * LARGE_SHARE;
- let prev: Array<DOMRect | undefined> | null = null;
+ let prev: Array<DOMRect | undefined> = [];
for (let i = 0; i <= steps; i++) {
- seek((i / steps) * durationSeconds);
- // Rects only for elements whose style has changed; the first read flushes layout once.
+ if (i > 0) seek((i / steps) * durationSeconds);
+ onStep?.(i, steps);
+ // Rects only for elements whose style has changed; a first change is judged against its
+ // own baseline style at this time, so an ancestor's pan is not its move.
const rects: Array<DOMRect | undefined> = [];
+ const fresh: number[] = [];
all.forEach((el, j) => {
if (!dynamic.has(el) && styleKey(el) === first[j]) return;
+ if (!dynamic.has(el)) fresh.push(j);
dynamic.add(el);
rects[j] = el.getBoundingClientRect();
- if (edgeShift(prev?.[j], rects[j]) / framesPerStep < MIN_SPEED) return;
+ });
+ const away = fresh.filter(
+ (j) => edgeShift(baseRects[j], rects[j]) / framesPerStep >= MIN_SPEED,
+ );
+ const before = rectsAtStyle(
+ away.map((j) => all[j] as HTMLElement),
+ away.map((j) => first[j] ?? ""),
+ );
+ away.forEach((j, k) => {
+ prev[j] = before[k];
+ });
+ rects.forEach((box, j) => {
+ const el = all[j];
+ if (!el || edgeShift(prev[j], box) / framesPerStep < MIN_SPEED) return;
fast.add(el);
- const box = rects[j];
if (
box &&
largeArea > 0 &&
diff --git a/packages/core/src/runtime/captureMotionBlur/index.test.ts b/packages/core/src/runtime/captureMotionBlur/index.test.ts
index 7638881a1f..76454bce9b 100644
--- a/packages/core/src/runtime/captureMotionBlur/index.test.ts
+++ b/packages/core/src/runtime/captureMotionBlur/index.test.ts
@@ -177,6 +177,19 @@ describe("opt-in and off switches", () => {
expect(win.__hfMotionBlur?.report().reason).toContain("engine");
});
+ it("names a distributed render as the reason when the renderer turned blur off (R19)", () => {
+ installHtmlInCanvas();
+ win.__HF_PAGE_MOTION_BLUR_OFF__ = "distributed-render";
+ const { root, h } = movingHost();
+ initCaptureMotionBlur(h);
+ expect(paintCaptureMotionBlur(0.5, { engineMode: true })).toBeNull();
+ expect(root.parentElement).toBe(document.body);
+ expect(win.__hfMotionBlur?.report()).toMatchObject({
+ state: "off",
+ reason: "the renderer turned it off (distributed-render)",
+ });
+ });
+
it("says why it is off to a root that asked for it", () => {
initCaptureMotionBlur(host(makeRoot()));
expect(console.info).toHaveBeenCalledWith(expect.stringContaining("html-in-canvas"));
@@ -305,6 +318,172 @@ describe("opt-in and off switches", () => {
expect(win.__hfMotionBlur?.report().reason).toMatch(/backface-visibility/);
});
+ it("blocks from the first frame a root that only starts tweening later", () => {
+ installHtmlInCanvas();
+ for (const late of [
+ (root: HTMLElement) => (root.style.transform = "translateX(8px)"),
+ (root: HTMLElement) => (root.style.opacity = "0.4"),
+ ]) {
+ const { root, h } = movingHost();
+ const slide = h.seek;
+ initCaptureMotionBlur({
+ ...h,
+ seek: (t, quiet) => {
+ slide(t, quiet);
+ if (t >= 0.7) late(root);
+ else root.removeAttribute("style");
+ },
+ });
+ void paintCaptureMotionBlur(0, { engineMode: true });
+ expect(root.parentElement).toBe(document.body);
+ expect(win.__hfMotionBlur?.report()).toMatchObject({
+ state: "off",
+ reason: expect.stringMatching(/root.*first seen at t=0\.[7-9]s/),
+ });
+ resetCaptureMotionBlurForTests();
+ document.body.innerHTML = "";
+ }
+ });
+
+ it("restores the playhead after a scan that blocked", () => {
+ installHtmlInCanvas();
+ const { root, h } = movingHost();
+ initCaptureMotionBlur({
+ ...h,
+ seek: (t, quiet) => {
+ h.seek(t, quiet);
+ root.style.opacity = t > 0.5 ? "0.5" : "1";
+ },
+ });
+ void paintCaptureMotionBlur(0.25, { engineMode: true });
+ expect(h.seek.mock.calls.at(-1)?.[0]).toBeCloseTo(0.25);
+ expect(win.__hfMotionBlur?.report().state).toBe("off");
+ });
+
+ it("sees a rotation that a later tween puts on a face with no 3D context at the start", () => {
+ installHtmlInCanvas();
+ const { root, h } = movingHost();
+ const face = document.createElement("div");
+ face.setAttribute("style", "backface-visibility: hidden");
+ root.append(face);
+ initCaptureMotionBlur({
+ ...h,
+ seek: (t, quiet) => {
+ h.seek(t, quiet);
+ face.style.transform = t > 0.5 ? "rotateY(120deg)" : "none";
+ },
+ });
+ void paintCaptureMotionBlur(0, { engineMode: true });
+ expect(root.parentElement).toBe(document.body);
+ expect(win.__hfMotionBlur?.report().reason).toMatch(/backface-visibility.*first seen/);
+ });
+
+ it("keeps blurring around a flat backface-hidden element that moves in 2D", () => {
+ installHtmlInCanvas();
+ const { root, h } = movingHost();
+ const face = document.createElement("div");
+ face.setAttribute("style", "backface-visibility: hidden");
+ root.append(face);
+ initCaptureMotionBlur({
+ ...h,
+ seek: (t, quiet) => {
+ h.seek(t, quiet);
+ face.style.transform = `translateX(${t * 50}px)`;
+ },
+ });
+ void paintCaptureMotionBlur(0.5, { engineMode: true });
+ expect(root.parentElement).toBe(captureCanvas(root));
+ expect(win.__hfMotionBlur?.report().state).toBe("on");
+ });
+
+ describe("a defect the scan missed renders that frame sharp (R10)", () => {
+ const sharpLogs = () =>
+ vi.mocked(console.info).mock.calls.filter(([m]) => String(m).includes("sharp frame"));
+
+ function engineFrame(h: ReturnType<typeof movingHost>["h"], t: number) {
+ h.seek(t, true);
+ void paintCaptureMotionBlur(t, { engineMode: true });
+ }
+
+ it("a WebGL canvas that appears and goes away: sharp meanwhile, blurred again after", () => {
+ installHtmlInCanvas();
+ trackAcceleratedCanvases();
+ const { root, h } = movingHost();
+ initCaptureMotionBlur(h);
+ engineFrame(h, 0.1);
+ expect(root.parentElement?.tagName).toBe("CANVAS");
+ const late = document.createElement("canvas");
+ root.append(late);
+ late.getContext("webgl2");
+ for (const t of [0.2, 0.3, 0.4]) {
+ engineFrame(h, t);
+ expect(root.parentElement).toBe(document.body);
+ }
+ late.remove();
+ engineFrame(h, 0.5);
+ expect(root.parentElement?.tagName).toBe("CANVAS");
+ expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "on", failedFrames: 3 });
+ expect(sharpLogs()).toHaveLength(1);
+ expect(sharpLogs()[0]?.[0]).toContain("accelerated-canvas");
+ });
+
+ it("a root shake between scan samples: only the shaken frames are sharp, state stays on", () => {
+ installHtmlInCanvas();
+ const { root, h } = movingHost();
+ initCaptureMotionBlur(h);
+ engineFrame(h, 0.1);
+ const wrappedAt: Record<string, boolean> = {};
+ for (const t of [0.2, 0.25, 0.3, 0.35, 0.4]) {
+ root.style.transform = t > 0.22 && t < 0.36 ? "translate(6px, 0px)" : "";
+ engineFrame(h, t);
+ wrappedAt[t] = root.parentElement?.tagName === "CANVAS";
+ }
+ expect(wrappedAt).toEqual({ 0.2: true, 0.25: false, 0.3: false, 0.35: false, 0.4: true });
+ expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "on", failedFrames: 3 });
+ expect(sharpLogs()).toHaveLength(1);
+ });
+
+ it("a hidden face flipped between the scan's backface samples", () => {
+ installHtmlInCanvas();
+ const { root, h } = movingHost();
+ const face = document.createElement("div");
+ face.setAttribute("style", "backface-visibility: hidden");
+ root.append(face);
+ const flip = (t: number, suppress: boolean) => {
+ h.seek(t, suppress);
+ face.style.transform = t > 0.4 && t < 0.5 ? "rotateY(120deg)" : "none";
+ };
+ initCaptureMotionBlur({ ...h, seek: flip });
+ flip(0.2, true);
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(win.__hfMotionBlur?.report().state).toBe("on");
+ expect(root.parentElement?.tagName).toBe("CANVAS");
+ flip(0.45, true);
+ void paintCaptureMotionBlur(0.45, { engineMode: true });
+ expect(root.parentElement).toBe(document.body);
+ flip(0.6, true);
+ void paintCaptureMotionBlur(0.6, { engineMode: true });
+ expect(root.parentElement?.tagName).toBe("CANVAS");
+ expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "on", failedFrames: 1 });
+ expect(sharpLogs()[0]?.[0]).toContain("backface-visibility");
+ });
+
+ it("an engine frame that is sharp resolves at once and leaves the composite step idle", async () => {
+ installHtmlInCanvas();
+ trackAcceleratedCanvases();
+ const { root, h } = movingHost();
+ initCaptureMotionBlur(h);
+ engineFrame(h, 0.1);
+ const late = document.createElement("canvas");
+ root.append(late);
+ late.getContext("webgl2");
+ win.__hf_page_composite_pending = false;
+ h.seek(0.2, true);
+ await paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(win.__hf_page_composite_pending).toBe(false);
+ });
+ });
+
it("clamps the shutter angle", () => {
installHtmlInCanvas();
const root = makeRoot({ "data-motion-blur": "on", "data-motion-blur-shutter": "9999" });
@@ -813,6 +992,101 @@ describe("painting", () => {
expect(Object.keys(win.__hfMotionBlur?.report() ?? {})).toContain("failedFrames");
});
+ describe("a block that its cause can lift", () => {
+ /** A host whose root fades from 0.5 s while `fade.on`: the scan blocks it as root opacity. */
+ function fadingHost(fade: { on: boolean }, timeline: () => unknown = () => "tl") {
+ const { root, h } = movingHost();
+ const slide = h.seek;
+ const seek = vi.fn((t: number, quiet: boolean) => {
+ slide(t, quiet);
+ root.style.opacity = fade.on && t > 0.5 ? "0.5" : "1";
+ });
+ return { root, host: { ...h, seek, timeline } };
+ }
+
+ it("resumes blurring once the cause is gone and the scene is initialised again", () => {
+ installHtmlInCanvas();
+ const fade = { on: true };
+ const { root, host: h } = fadingHost(fade);
+ initCaptureMotionBlur(h);
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "off" });
+ expect(win.__hfMotionBlur?.report().reason).toMatch(/opacity/);
+ fade.on = false;
+ initCaptureMotionBlur(h);
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "on", reason: null });
+ expect(root.parentElement).toBe(captureCanvas(root));
+ });
+
+ it("blocks again, with the reason, when the cause is still there", () => {
+ installHtmlInCanvas();
+ const { root, host: h } = fadingHost({ on: true });
+ initCaptureMotionBlur(h);
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ initCaptureMotionBlur(h);
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(root.parentElement).toBe(document.body);
+ expect(win.__hfMotionBlur?.report()).toMatchObject({ state: "off" });
+ expect(win.__hfMotionBlur?.report().reason).toMatch(/opacity/);
+ });
+
+ it("re-evaluates the block when the bound timeline changes", () => {
+ installHtmlInCanvas();
+ const fade = { on: true };
+ let tl = "a";
+ const { host: h } = fadingHost(fade, () => tl);
+ initCaptureMotionBlur(h);
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(win.__hfMotionBlur?.report().state).toBe("off");
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(win.__hfMotionBlur?.report().state).toBe("off");
+ fade.on = false;
+ tl = "b";
+ void paintCaptureMotionBlur(0.2, { engineMode: true });
+ expect(win.__hfMotionBlur?.report().state).toBe("on");
+ });
+
+ it("lifts a block raised after a clean scan, too", () => {
+ installHtmlInCanvas();
+ trackAcceleratedCanvases();
+ const { root, h } = movingHost();
+ initCaptureMotionBlur(h);
+ const late = document.createElement("canvas");
+ root.append(late);
+ late.getContext("webgl");
+ void paintCaptureMotionBlur(0.5, { engineMode: true });
+ expect(win.__hfMotionBlur?.report().reason).toMatch(/WebGL/);
+ late.remove();
+ initCaptureMotionBlur(h);
+ void paintCaptureMotionBlur(0.5, PLAY);
+ captureCanvas(root).dispatchEvent(new Event("paint"));
+ expect(win.__hfMotionBlur?.report().state).toBe("on");
+ expect(captureContext()?.drawElementImage).toHaveBeenCalled();
+ });
+
+ it("keeps a capture-failure block for the life of the instance", async () => {
+ installHtmlInCanvas();
+ const { root, h } = movingHost();
+ initCaptureMotionBlur(h);
+ for (let i = 0; i < 3; i++) {
+ const done = paintCaptureMotionBlur(i / 30, PLAY);
+ captureContext()?.drawElementImage.mockImplementation(() => {
+ throw new Error("No cached paint record");
+ });
+ captureCanvas(root).dispatchEvent(new Event("paint"));
+ await done;
+ }
+ initCaptureMotionBlur(h);
+ void paintCaptureMotionBlur(0.5, PLAY);
+ expect(root.parentElement).toBe(document.body);
+ expect(win.__hfMotionBlur?.report()).toMatchObject({
+ state: "off",
+ reason: "capture failed 3 times in a row",
+ });
+ });
+ });
+
it("keeps blurring in a render after repeated capture failures, each failed frame plain DOM", async () => {
installHtmlInCanvas();
const { root, h } = movingHost();
diff --git a/packages/core/src/runtime/captureMotionBlur/index.ts b/packages/core/src/runtime/captureMotionBlur/index.ts
index aac89d9ffc..cafb88e571 100644
--- a/packages/core/src/runtime/captureMotionBlur/index.ts
+++ b/packages/core/src/runtime/captureMotionBlur/index.ts
@@ -18,7 +18,14 @@ import {
unmarkCaptured,
type HtmlInCanvasForm,
} from "../../htmlInCanvas";
-import { type DefectEnv, findCaptureDefect, scanBackfaceDefect } from "../../htmlInCanvasDefects";
+import {
+ type CaptureDefect,
+ type DefectEnv,
+ chromeMajor,
+ createDefectScan,
+ findCaptureDefect,
+ scanBackfaceDefect,
+} from "../../htmlInCanvasDefects";
import {
PAGE_DEVICE_SCALE_GLOBAL,
PAGE_MOTION_BLUR_OFF_GLOBAL,
@@ -118,9 +125,7 @@ function readConfig(root: HTMLElement): Config | null {
/** Must run before composition scripts: see `installAcceleratedCanvasTracker`. */
export const trackAcceleratedCanvases = installAcceleratedCanvasTracker;
-function defectEnv(backface: boolean): DefectEnv {
- return { isAccelerated: isAcceleratedCanvas, backface };
-}
+const isAccelerated: DefectEnv["isAccelerated"] = isAcceleratedCanvas;
function unsupportedReason(root: HTMLElement): string | null {
const off = (window as unknown as Record<string, unknown>)[PAGE_MOTION_BLUR_OFF_GLOBAL];
@@ -128,7 +133,9 @@ function unsupportedReason(root: HTMLElement): string | null {
if (!supportsCaptureMotionBlur()) {
return "html-in-canvas (drawElementImage) is unavailable in this browser";
}
- return findCaptureDefect(root, defectEnv(scanBackfaceDefect(root)))?.reason ?? null;
+ return (
+ findCaptureDefect(root, { isAccelerated, backface: scanBackfaceDefect(root) })?.reason ?? null
+ );
}
function describe(el: Element): string {
@@ -192,11 +199,15 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
let failures = 0;
let failedFrames = 0;
let disabled: string | null = null;
+ // Capture failures end blur for good; a defect block lasts until the scene is scanned again.
+ let failedForGood = false;
const timings: number[] = [];
let sampleMs = 0;
let scanMs = 0;
let scannedTimeline: unknown = undefined;
- let backface = false;
+ let scanDefect: CaptureDefect | null = null;
+ let faceNow: () => boolean = () => false;
+ const loggedBackstops = new Set<string>();
let wrapped = false;
// The output still shows the last frame of the previous wrap until this one draws.
let staleOutput = false;
@@ -247,15 +258,19 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
function discover(restoreTo: number): void {
scannedTimeline = host.timeline();
- backface = scanBackfaceDefect(root);
+ const duration = host.durationSeconds();
+ const defects = createDefectScan(root, isAccelerated);
const s0 = performance.now();
const found = discoverMovers({
scene: root,
- durationSeconds: host.durationSeconds(),
+ durationSeconds: duration,
fps: host.fps,
seek: scanSeek,
+ onStep: (i, steps) => defects.sample(i, steps, (i / steps) * duration),
});
scanSeek(restoreTo);
+ scanDefect = defects.result();
+ faceNow = defects.facesNow;
movers = found.movers;
reader = createPoseReader(root, found.dynamic);
scanMs = Math.round(performance.now() - s0);
@@ -332,7 +347,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
countFailedFrame(err instanceof Error ? err.message : String(err));
// A render never gives up mid-video: this frame shows the plain DOM, the next wraps again.
if (rendering) unwrap();
- else if (failures >= MAX_FAILURES) disable(`capture failed ${failures} times in a row`);
+ else if (failures >= MAX_FAILURES) disable(`capture failed ${failures} times in a row`, true);
}
/** This paint's half of the frame; false when the background capture is still to come. */
@@ -390,9 +405,10 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
src.addEventListener("paint", onPaint);
- function disable(reason: string): void {
+ function disable(reason: string, forGood = false): void {
if (disabled) return;
disabled = reason;
+ failedForGood = forGood;
console.warn(`[motion-blur] off: ${reason}`);
teardown();
}
@@ -402,12 +418,24 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
unwrap();
}
+ function clearDefectBlock(): void {
+ if (!disabled || failedForGood) return;
+ disabled = null;
+ reader = null;
+ src.addEventListener("paint", onPaint);
+ }
+
+ function releaseStaleBlock(): void {
+ if (disabled && host.timeline() !== scannedTimeline) clearDefectBlock();
+ }
+
/**
* Request one blurred frame at `t`; resolves once it is drawn (or given up on). A frame still
* in flight (between its two paints) is not abandoned: the request waits as the newest pending
* one. An engine frame replaces it, since the engine waits on exactly this frame.
*/
function paint(t: number, engineMode: boolean): Promise<void> {
+ releaseStaleBlock();
if (disabled) return Promise.resolve();
if (engineMode) rendering = true;
// A hidden tab paints nothing: rest on plain DOM instead of waiting on paints that never come.
@@ -443,21 +471,34 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
staleOutput = true;
}
+ /** Scan when the timeline is new; true when the scan found a defect (blur is then off). */
+ function blockedByScan(t: number): boolean {
+ if (!reader || host.timeline() !== scannedTimeline) discover(t);
+ if (scanDefect) disable(scanDefect.reason);
+ return disabled !== null;
+ }
+
+ /** The scan decided the timeline; a defect it missed makes this one frame sharp. */
+ function plainFrame(defect: CaptureDefect): Promise<void> {
+ unwrap();
+ failedFrames++;
+ if (!loggedBackstops.has(defect.code)) {
+ loggedBackstops.add(defect.code);
+ console.info(`[motion-blur] sharp frame: ${defect.code} appeared after a clean scan`);
+ }
+ return Promise.resolve();
+ }
+
function start(t: number, engineMode: boolean): Promise<void> {
try {
syncDensity();
- if (!reader || host.timeline() !== scannedTimeline) discover(t);
+ if (blockedByScan(t)) return Promise.resolve();
if (movers.length === 0) {
unwrap();
return Promise.resolve();
}
- // Checked again here, not only at init: a block's script can add its own capture canvas
- // (wrapping one inside ours hangs the renderer) or a WebGL canvas later.
- const blocked = findCaptureDefect(root, defectEnv(backface));
- if (blocked) {
- disable(blocked.reason);
- return Promise.resolve();
- }
+ const late = findCaptureDefect(root, { isAccelerated, backface: faceNow() });
+ if (late) return plainFrame(late);
wrap();
const s0 = performance.now();
const next = frames(t, engineMode ? RENDER_READS : PREVIEW_READS);
@@ -491,7 +532,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
});
} catch (err) {
swallow("runtime.captureMotionBlur.paint", err);
- disable(err instanceof Error ? err.message : String(err));
+ disable(err instanceof Error ? err.message : String(err), true);
return Promise.resolve();
}
}
@@ -537,6 +578,7 @@ function createInstance(host: CaptureMotionBlurHost, config: Config, form: HtmlI
busy: (): boolean => pending !== null,
rediscover: () => {
reader = null;
+ clearDefectBlock();
},
};
}
@@ -566,7 +608,7 @@ export function initCaptureMotionBlur(host: CaptureMotionBlurHost): void {
const form = htmlInCanvasForm();
const reason = unsupportedReason(host.root);
if (!form || reason) {
- console.info(`[motion-blur] off: ${reason}`);
+ console.info(`[motion-blur] off: ${reason} (Chrome ${chromeMajor() ?? "unknown"})`);
w.__hfMotionBlur = {
report: () => ({
state: "off",
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 36b984d745..9d5a4aac57 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -310,6 +310,7 @@ export {
export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
export { frameFileExtension } from "./services/frameCapture.js";
export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
+export type { PageMotionBlurOff } from "./types.js";
export {
assertSwiftShader,
diff --git a/packages/engine/src/services/pageMotionBlur.test.ts b/packages/engine/src/services/pageMotionBlur.test.ts
index 87e0ccaeb9..444a8e396b 100644
--- a/packages/engine/src/services/pageMotionBlur.test.ts
+++ b/packages/engine/src/services/pageMotionBlur.test.ts
@@ -30,6 +30,18 @@ describe("installPageMotionBlur", () => {
);
});
+ it("says why when the render route cannot host the blur", async () => {
+ for (const route of ["hdr-render", "layered-composite", "distributed-render"] as const) {
+ const page = fakePage();
+ await installPageMotionBlur(page, { pageMotionBlur: route });
+ expect(page.evaluateOnNewDocument).toHaveBeenCalledWith(
+ expect.any(Function),
+ PAGE_MOTION_BLUR_OFF_GLOBAL,
+ route,
+ );
+ }
+ });
+
it("tells the page the render's device scale when it is not 1", async () => {
const page = fakePage();
await installPageMotionBlur(page, { deviceScaleFactor: 2 });
diff --git a/packages/engine/src/services/pageMotionBlur.ts b/packages/engine/src/services/pageMotionBlur.ts
index ef15a7452a..4e423992ae 100644
--- a/packages/engine/src/services/pageMotionBlur.ts
+++ b/packages/engine/src/services/pageMotionBlur.ts
@@ -12,6 +12,14 @@ import {
import type { Page } from "puppeteer-core";
import type { CaptureOptions } from "../types.js";
+function pageOffReason(
+ options: Pick<CaptureOptions, "motionBlur" | "pageMotionBlur">,
+): string | null {
+ if (options.motionBlur) return "engine-motion-blur";
+ if (options.pageMotionBlur === "off") return "preview-unsupported";
+ return options.pageMotionBlur ?? null;
+}
+
export async function installPageMotionBlur(
page: Pick<Page, "evaluateOnNewDocument">,
options: Pick<CaptureOptions, "motionBlur" | "pageMotionBlur" | "deviceScaleFactor">,
@@ -27,11 +35,7 @@ export async function installPageMotionBlur(
scale,
);
}
- const off = options.motionBlur
- ? "engine-motion-blur"
- : options.pageMotionBlur === "off"
- ? "preview-unsupported"
- : null;
+ const off = pageOffReason(options);
if (!off) return;
await page.evaluateOnNewDocument(
(key: string, v: string) => {
diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts
index 873b674d3c..33bc5caa6e 100644
--- a/packages/engine/src/types.ts
+++ b/packages/engine/src/types.ts
@@ -9,6 +9,8 @@ import type { Fps } from "@hyperframes/core";
import type { ChromeMemoryStats } from "./services/chromeMemorySampler.js";
import type { MotionBlurOptions } from "./services/motionBlur.js";
+export type PageMotionBlurOff = "off" | "hdr-render" | "layered-composite" | "distributed-render";
+
/**
* Outcome of waiting for a sub-composition's GSAP timelines to register.
* Threaded string-typed through `CapturePerfSummary` / `RenderPerfSummary` /
@@ -171,7 +173,8 @@ export interface CaptureOptions {
* screenshot capture mode; see `services/motionBlur.ts`.
*/
motionBlur?: MotionBlurOptions;
- pageMotionBlur?: "off";
+ /** Why the page's capture motion blur stands down: the preview could not blur, or the route cannot host it. */
+ pageMotionBlur?: PageMotionBlurOff;
deviceScaleFactor?: number;
/**
* Opt into Chrome's capture-beyond-viewport screenshot path. Leave undefined
diff --git a/packages/producer/src/services/distributed/chunkFrames.ts b/packages/producer/src/services/distributed/chunkFrames.ts
index 4a5e5e6b34..ebc46d1578 100644
--- a/packages/producer/src/services/distributed/chunkFrames.ts
+++ b/packages/producer/src/services/distributed/chunkFrames.ts
@@ -168,6 +168,7 @@ export function buildChunkCaptureOptions(input: {
...(videoCaptureBeyondViewport !== undefined
? { captureBeyondViewport: videoCaptureBeyondViewport }
: {}),
+ pageMotionBlur: "distributed-render",
// A fixed warmup count keeps `beginFrameTimeTicks` host-independent.
lockWarmupTicks: true,
requiresWebGpu: compositionRequiresWebGpu(input.html),
diff --git a/packages/producer/src/services/distributed/plan.test.ts b/packages/producer/src/services/distributed/plan.test.ts
index c279428aab..e2472d30c5 100644
--- a/packages/producer/src/services/distributed/plan.test.ts
+++ b/packages/producer/src/services/distributed/plan.test.ts
@@ -181,6 +181,17 @@ describe("distributed synthetic render job", () => {
expect(job.config.variables).toEqual(variables);
});
+ it("turns the page's capture motion blur off for the plan probe (R19)", () => {
+ const job = buildSyntheticRenderJob({
+ fps: { num: 30, den: 1 },
+ format: "mp4",
+ quality: "high",
+ hdrMode: "force-sdr",
+ entryFile: "index.html",
+ });
+ expect(job.config.pageMotionBlur).toBe("off");
+ });
+
it("keeps the production software-GPU launch on BeginFrame control", () => {
const cfg = resolveDistributedEngineConfig({
fps: 30,
@@ -531,6 +542,28 @@ describe("resolveChunkPlan", () => {
});
});
+describe("plan() and page motion blur (R19)", () => {
+ const planCaptureMode = async (html: string, name: string) => {
+ const dir = join(runRoot, name);
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, "index.html"), html, "utf-8");
+ const planDir = join(runRoot, `${name}-plan`);
+ await plan(dir, { fps: 30, width: 320, height: 240, format: "mp4" }, planDir);
+ const meta = JSON.parse(readFileSync(join(planDir, "meta", "encoder.json"), "utf-8"));
+ return { captureMode: meta.captureMode ?? null, forceScreenshot: meta.forceScreenshot ?? null };
+ };
+
+ it("does not route a data-motion-blur composition through screenshot capture", async () => {
+ const blur = FIXTURE_HTML.replace(
+ 'data-composition-id="root"',
+ 'data-composition-id="root" data-motion-blur="on"',
+ );
+ const plain = await planCaptureMode(FIXTURE_HTML, "blur-plain");
+ const blurred = await planCaptureMode(blur, "blur-on");
+ expect(blurred).toEqual(plain);
+ }, 30_000);
+});
+
describe("buildChunkSlices", () => {
it("produces consecutive non-overlapping ranges covering all frames", () => {
const slices = buildChunkSlices(700, 3, 240);
diff --git a/packages/producer/src/services/distributed/plan.ts b/packages/producer/src/services/distributed/plan.ts
index 7fb2775440..7f9197440e 100644
--- a/packages/producer/src/services/distributed/plan.ts
+++ b/packages/producer/src/services/distributed/plan.ts
@@ -1232,6 +1232,7 @@ async function compilePlanComposition(
// the Lambda/worker filesystem won't have the same fonts installed.
allowSystemFontCapture: false,
variables: config.variables,
+ pageMotionBlur: job.config.pageMotionBlur,
});
logPlanStage(log, "compile", stageStarted);
let compiled = compileResult.compiled;
diff --git a/packages/producer/src/services/distributed/shared.ts b/packages/producer/src/services/distributed/shared.ts
index 6d5171bd0e..e9684710cd 100644
--- a/packages/producer/src/services/distributed/shared.ts
+++ b/packages/producer/src/services/distributed/shared.ts
@@ -461,6 +461,7 @@ export function buildSyntheticRenderJob(input: SyntheticRenderJobInput): RenderJ
strictness: input.strictness,
producerConfig: input.producerConfig,
variables: input.variables,
+ pageMotionBlur: "off",
};
return createRenderJob(renderConfig);
}
diff --git a/packages/producer/src/services/render/motionBlurRoute.test.ts b/packages/producer/src/services/render/motionBlurRoute.test.ts
index 79a1b206de..5efb98e691 100644
--- a/packages/producer/src/services/render/motionBlurRoute.test.ts
+++ b/packages/producer/src/services/render/motionBlurRoute.test.ts
@@ -1,7 +1,7 @@
import { describe, expect, it } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";
-import { assertMotionBlurSupported } from "./motionBlurRoute.js";
+import { assertMotionBlurSupported, pageMotionBlurForRoute } from "./motionBlurRoute.js";
describe("assertMotionBlurSupported", () => {
it("lets the SDR capture routes through", () => {
@@ -38,3 +38,34 @@ describe("assertMotionBlurSupported", () => {
);
});
});
+
+describe("pageMotionBlurForRoute", () => {
+ it("turns the page blur off for HDR content, whichever way it is composited", () => {
+ expect(pageMotionBlurForRoute({ hasHdrContent: true, useLayeredComposite: true })).toBe(
+ "hdr-render",
+ );
+ expect(pageMotionBlurForRoute({ hasHdrContent: true, useLayeredComposite: false })).toBe(
+ "hdr-render",
+ );
+ });
+
+ it("turns it off for the layered compositor even with no HDR content", () => {
+ expect(pageMotionBlurForRoute({ hasHdrContent: false, useLayeredComposite: true })).toBe(
+ "layered-composite",
+ );
+ });
+
+ it("leaves the page blur alone on the plain SDR routes", () => {
+ expect(
+ pageMotionBlurForRoute({ hasHdrContent: false, useLayeredComposite: false }),
+ ).toBeUndefined();
+ });
+
+ // Reachability: the helper is dead unless the orchestrator feeds it into the options every
+ // capture session is built from, once HDR is known and again once the layered route is.
+ it("feeds every session's capture options, after HDR and after the layered decision", () => {
+ const orchestrator = readFileSync(join(import.meta.dir, "..", "renderOrchestrator.ts"), "utf8");
+ expect(orchestrator.match(/pageMotionBlurForRoute\(/g) ?? []).toHaveLength(2);
+ expect(orchestrator).toContain("pageMotionBlur: routePageMotionBlur");
+ });
+});
diff --git a/packages/producer/src/services/render/motionBlurRoute.ts b/packages/producer/src/services/render/motionBlurRoute.ts
index 9886019548..b720b1e78f 100644
--- a/packages/producer/src/services/render/motionBlurRoute.ts
+++ b/packages/producer/src/services/render/motionBlurRoute.ts
@@ -17,7 +17,7 @@
* is a feature rather than a fix.
*/
-import type { MotionBlurOptions } from "@hyperframes/engine";
+import type { MotionBlurOptions, PageMotionBlurOff } from "@hyperframes/engine";
import type { CapturePlan } from "./capturePlan.js";
/** Why a capture route cannot honour motion blur, or null when it can. */
@@ -54,3 +54,17 @@ export function assertMotionBlurSupported(
`[MotionBlur] sub-frame motion blur is not supported on the "${route}" capture route: ${reason}`,
);
}
+
+/**
+ * Why the page's own capture blur (`data-motion-blur="on"`) must stand down on this route, or
+ * undefined when it can run. The layered compositor screenshots each DOM layer after hiding the
+ * others; blur draws the whole composition into a canvas that those hides do not reach, so a
+ * layer comes out wrong (HDR: backgrounds and overlays lost).
+ */
+export function pageMotionBlurForRoute(route: {
+ hasHdrContent: boolean;
+ useLayeredComposite: boolean;
+}): PageMotionBlurOff | undefined {
+ if (route.hasHdrContent) return "hdr-render";
+ return route.useLayeredComposite ? "layered-composite" : undefined;
+}
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 45e18c5beb..550619b47d 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -223,7 +223,7 @@ import {
resolveCaptureImageFormat,
resolveCaptureJpegQuality,
} from "./render/captureImageFormat.js";
-import { assertMotionBlurSupported } from "./render/motionBlurRoute.js";
+import { assertMotionBlurSupported, pageMotionBlurForRoute } from "./render/motionBlurRoute.js";
import { assertOutputScaleSupported } from "./render/outputScaleRoute.js";
export function sampleDirectoryBytes(dir: string): number {
@@ -3516,8 +3516,11 @@ async function executeRenderPipeline(input: {
// aspect ratio stay stable before the first injected frame. Native HDR
// videos are included for the same reason: Chrome may not decode them at
// all, while the renderer composites their extracted frames separately.
+ // Set once the route is known (HDR just below, layered after page-side compositing is decided).
+ let routePageMotionBlur: CaptureOptions["pageMotionBlur"];
const buildCaptureOptions = (): CaptureOptions => ({
...captureOptions,
+ ...(routePageMotionBlur ? { pageMotionBlur: routePageMotionBlur } : {}),
videoMetadataHints,
skipReadinessVideoIds: videoReadinessSkipIds,
subTimelineWaitMemo,
@@ -3570,6 +3573,7 @@ async function executeRenderPipeline(input: {
const nativeHdrIds = new Set([...nativeHdrVideoIds, ...nativeHdrImageIds]);
const hasHdrContent = Boolean(effectiveHdr && nativeHdrIds.size > 0);
if (hasHdrContent) assertOutputScaleSupported(deviceScaleFactor, "hdr_layered");
+ routePageMotionBlur = pageMotionBlurForRoute({ hasHdrContent, useLayeredComposite: false });
// DE priority inversion eligibility — evaluated BEFORE capture calibration
// because when every multi-worker resolution would be inverted to 1 anyway,
// the calibration stage (a throwaway Chrome launch + timeline-spread sample
@@ -4222,6 +4226,7 @@ async function executeRenderPipeline(input: {
hasShaderTransitions: compiled.hasShaderTransitions && !isGif,
isPngSequence,
});
+ routePageMotionBlur = pageMotionBlurForRoute({ hasHdrContent, useLayeredComposite });
const inversionFallback = resolveInversionRetryPlan({
deWorkerInversion,
preInversionWorkerCount: preRoutingWorkerCount,