Skip to content

Write HTML. Render video. Built for agents.

fix(cli): check no longer calls films moved by SVG masks, strokes or canvas static (#5960)

Miguel Ángel0bd626825c74
diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts
index ae720610a7..15962a447a 100644
--- a/packages/cli/src/commands/check.test.ts
+++ b/packages/cli/src/commands/check.test.ts
@@ -153,6 +153,17 @@ function contrastEntry(overrides: Partial<ContrastAuditEntry> = {}): ContrastAud
};
}
+// A rendered frame that is a function of the last seek, as a seek-driven film's is.
+function framesOfSeekedTime(): Pick<CheckAuditDriver, "seek" | "captureFrame"> {
+ let seeked = 0;
+ return {
+ seek: vi.fn(async (time: number) => {
+ seeked = time;
+ }),
+ captureFrame: vi.fn(async () => `frame@${seeked}`),
+ };
+}
+
function fakeDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver {
// A distinct string per call so the frozen-sweep guard (#U10) never fires
// by accident in unrelated scenarios — tests that want it force a constant
@@ -171,6 +182,8 @@ function fakeDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver
collectLayout: vi.fn(async (_time: number, _tolerance: number) => []),
collectOverlap: vi.fn(async (_time: number) => []),
collectLayoutGeometry: vi.fn(async () => `geometry-${geometryCallCount++}`),
+ captureFrame: vi.fn(async (_scope?: string) => "frame"),
+ framesDiffer: vi.fn(async (first: string, second: string) => first !== second),
collectSeekClock: vi.fn(async () => [{ id: 1, time: 0, done: false }]),
collectRotationSample: vi.fn(async (_time: number) => []),
collectOffPivotRotationSample: vi.fn(async (time: number) => ({ time, samples: [] })),
@@ -1727,7 +1740,7 @@ describe("check pipeline", () => {
DEFAULT_CHECK_OPTIONS,
noMotion(),
);
- const samples = vi.mocked(serialPage.seek).mock.calls.length;
+ const samples = vi.mocked(serialPage.collectLayout).mock.calls.length;
let firstPageSeeks = 0;
let othersTaken!: () => void;
const allOthersTaken = new Promise<void>((resolve) => (othersTaken = resolve));
@@ -1878,6 +1891,44 @@ describe("check pipeline", () => {
expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
});
+ it.each([
+ ["a timeline that looks stuck", (_sample: number) => "frozen", true],
+ ["a still card", (_sample: number) => "frozen", false],
+ ["an audio-only sweep", (sample: number) => `still\u001f${sample}`, false],
+ ])("does not flag %s when the rendered frames differ", async (_case, geometry, stuck) => {
+ let sample = 0;
+ const driver = fakeDriver({
+ getDuration: vi.fn(async () => 6),
+ collectLayoutGeometry: vi.fn(async () => geometry(sample++)),
+ ...(stuck ? {} : { collectSeekClock: vi.fn(async () => []) }),
+ ...framesOfSeekedTime(),
+ });
+ const { report } = await runScenario(driver);
+
+ expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
+ expect(report.ok).toBe(true);
+ });
+
+ it("still warns when the frames change with the wall clock rather than the seek", async () => {
+ let frame = 0;
+ const driver = fakeDriver({
+ getDuration: vi.fn(async () => 6),
+ collectLayoutGeometry: vi.fn(async () => "frozen"),
+ collectSeekClock: vi.fn(async () => []),
+ captureFrame: vi.fn(async () => `frame${frame++}`),
+ });
+ const { report } = await runScenario(driver);
+
+ expect(sweepOf(report)).toEqual([["warning", "Nothing on screen moved under seek."]]);
+ });
+
+ it("never captures frames when the signature already moved", async () => {
+ const driver = fakeDriver({ getDuration: vi.fn(async () => 6) });
+ await runScenario(driver);
+
+ expect(driver.captureFrame).not.toHaveBeenCalled();
+ });
+
it("does not flag --at times the user picked on a still end card", async () => {
const driver = fakeDriver({
getDuration: vi.fn(async () => 53.7),
@@ -1944,6 +1995,136 @@ describe("check pipeline", () => {
expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
});
});
+
+ describe("keepsMoving frame check", () => {
+ function frozenLiveness(withinSelector?: string) {
+ const motion: MotionSpecResolution = {
+ kind: "valid",
+ path: "/project/index.motion.json",
+ spec: { assertions: [{ kind: "keepsMoving", ...(withinSelector && { withinSelector }) }] },
+ };
+ const scope = withinSelector ?? "*";
+ const overrides = {
+ getDuration: vi.fn(async () => 6),
+ collectMotionFrame: vi.fn(async (time: number) => ({
+ time,
+ data: {},
+ liveness: { [scope]: "unchanging" },
+ })),
+ };
+ return { motion, overrides };
+ }
+
+ function frozenFindings(report: CheckReport): string[] {
+ return report.motion.findings
+ .filter((finding) => finding.code === "motion_frozen")
+ .map((finding) => finding.message);
+ }
+
+ it.each([undefined, "#scene"])(
+ "does not call a scope (%s) frozen when its rendered frames keep changing",
+ async (withinSelector) => {
+ const { motion, overrides } = frozenLiveness(withinSelector);
+ let frame = 0;
+ const driver = fakeDriver({
+ ...overrides,
+ captureFrame: vi.fn(async () => `frame${frame++}`),
+ });
+ const { report } = await runScenario(driver, {}, { motion });
+
+ expect(frozenFindings(report)).toEqual([]);
+ expect(driver.captureFrame).toHaveBeenCalledWith(withinSelector);
+ // One capture per half maxStaticSec, not one per motion frame.
+ expect(vi.mocked(driver.captureFrame).mock.calls.length).toBeLessThanOrEqual(7);
+ },
+ );
+
+ async function frozenIssues(driver: CheckAuditDriver, motion: MotionSpecResolution) {
+ const result = await runAuditGrid(driver, DEFAULT_CHECK_OPTIONS, motion);
+ return result.motionIssues.map((issue) => `${issue.code} ${issue.message}`);
+ }
+
+ it("splits a frozen span where its frames change once, keeping both halves", async () => {
+ const { motion, overrides } = frozenLiveness();
+ let seeked = 0;
+ const driver = fakeDriver({
+ ...overrides,
+ seek: vi.fn(async (time: number) => {
+ seeked = time;
+ }),
+ captureFrame: vi.fn(async () => (seeked < 3 ? "before" : "after")),
+ });
+
+ expect(await frozenIssues(driver, motion)).toEqual([
+ expect.stringContaining("between 0s and 3s"),
+ expect.stringContaining("between 3s and 6s"),
+ ]);
+ });
+
+ it("keeps the second of two frozen spans that touch at a cut", async () => {
+ const motion: MotionSpecResolution = {
+ kind: "valid",
+ path: "/project/index.motion.json",
+ spec: { assertions: [{ kind: "keepsMoving" }] },
+ };
+ // A hold, a hard cut at 3 s into a second hold, then motion from 5.05 s.
+ const shot = (index: number) => (index < 60 ? "a" : index < 101 ? "b" : String(index));
+ const driver = fakeDriver({
+ getDuration: vi.fn(async () => 6),
+ collectMotionFrame: vi.fn(async (time: number) => ({
+ time,
+ data: {},
+ liveness: { "*": shot(Math.round(time * 20)) },
+ })),
+ });
+
+ expect(await frozenIssues(driver, motion)).toEqual([
+ expect.stringContaining("between 0s and 3s"),
+ expect.stringContaining("between 3s and 5.05s"),
+ ]);
+ });
+
+ it("leaves a scope that matched nothing as missing while another scope is frozen", async () => {
+ const motion: MotionSpecResolution = {
+ kind: "valid",
+ path: "/project/index.motion.json",
+ spec: {
+ assertions: [{ kind: "keepsMoving" }, { kind: "keepsMoving", withinSelector: "#typo" }],
+ },
+ };
+ const driver = fakeDriver({
+ getDuration: vi.fn(async () => 6),
+ collectMotionFrame: vi.fn(async (time: number) => ({
+ time,
+ data: {},
+ liveness: { "*": "unchanging", "#typo": "" },
+ })),
+ });
+
+ const codes = (await frozenIssues(driver, motion)).map((line) => line.split(" ")[0]);
+ expect(codes).toEqual(["motion_frozen", "motion_selector_missing"]);
+ });
+
+ it("never captures frames when the liveness already moved", async () => {
+ const motion: MotionSpecResolution = {
+ kind: "valid",
+ path: "/project/index.motion.json",
+ spec: { assertions: [{ kind: "keepsMoving" }] },
+ };
+ const driver = fakeDriver({
+ getDuration: vi.fn(async () => 6),
+ collectMotionFrame: vi.fn(async (time: number) => ({
+ time,
+ data: {},
+ liveness: { "*": String(time) },
+ })),
+ });
+ const { report } = await runScenario(driver, {}, { motion });
+
+ expect(frozenFindings(report)).toEqual([]);
+ expect(driver.captureFrame).not.toHaveBeenCalled();
+ });
+ });
});
describe("frame-check flag grammar", () => {
diff --git a/packages/cli/src/commands/motion-signature.browser.js b/packages/cli/src/commands/motion-signature.browser.js
index 97414f639a..24760de4b7 100644
--- a/packages/cli/src/commands/motion-signature.browser.js
+++ b/packages/cli/src/commands/motion-signature.browser.js
@@ -1,6 +1,7 @@
// Shared "what counts as motion" classifier, injected before layout-audit.browser.js and motion-sample.browser.js.
// The frozen-sweep guard (sweep_static) and keepsMoving liveness (motion_frozen) meet in one decision, so both
// must count the same channels as motion; only quantization differs (liveness buckets 2px and 0.08 opacity).
+// Where both read still, check asks framesDiffer below, which compares the rendered frames.
// A channel reader returns a string equal across samples iff it did not visibly change, "" when it does not apply.
(function () {
const IGNORE_TAGS = new Set(["SCRIPT", "STYLE", "TEMPLATE", "NOSCRIPT", "META", "LINK"]);
@@ -403,6 +404,56 @@
return parts.join("|");
}
+ // --- Rendered frames: the last word where DOM channels cannot see paint ------
+ // A frame moved when enough pixels changed by more than render noise (antialiasing, dither) on some channel.
+ // ponytail: fewer than FRAME_MIN_CHANGED_PIXELS changed pixels reads as still; lower it for tinier motion.
+ const FRAME_CHANNEL_NOISE = 24;
+ const FRAME_MIN_CHANGED_PIXELS = 16;
+ let reference = { png: "", pixels: null };
+
+ // Decoded in the page like the contrast pass, so no image library is needed.
+ async function framePixels(png) {
+ const image = new Image();
+ image.src = "data:image/png;base64," + png;
+ await image.decode();
+ const canvas = document.createElement("canvas");
+ canvas.width = image.naturalWidth;
+ canvas.height = image.naturalHeight;
+ const ctx2d = canvas.getContext("2d", { willReadFrequently: true });
+ ctx2d.drawImage(image, 0, 0);
+ return ctx2d.getImageData(0, 0, canvas.width, canvas.height);
+ }
+
+ function pixelChanged(a, b, i) {
+ return (
+ Math.abs(a[i] - b[i]) > FRAME_CHANNEL_NOISE ||
+ Math.abs(a[i + 1] - b[i + 1]) > FRAME_CHANNEL_NOISE ||
+ Math.abs(a[i + 2] - b[i + 2]) > FRAME_CHANNEL_NOISE
+ );
+ }
+
+ // Base64 PNG screenshots in, "did anything visible change" out. The first frame is usually a run's
+ // reference compared against many, so its decode is kept.
+ // fallow-ignore-next-line complexity
+ async function framesDiffer(first, second) {
+ if (first === second) return false;
+ if (!first || !second) return true;
+ if (reference.png !== first) reference = { png: first, pixels: await framePixels(first) };
+ return pixelsDiffer(reference.pixels, await framePixels(second));
+ }
+
+ // fallow-ignore-next-line complexity
+ function pixelsDiffer(a, b) {
+ if (a.width !== b.width || a.height !== b.height) return true;
+ let changed = 0;
+ for (let i = 0; i < a.data.length; i += 4) {
+ if (pixelChanged(a.data, b.data, i) && ++changed >= FRAME_MIN_CHANGED_PIXELS) return true;
+ }
+ return false;
+ }
+
+ window.__hyperframesFramesDiffer = framesDiffer;
+
window.__hyperframesMotionSignature = {
compositionRoot,
isVisibleElement,
diff --git a/packages/cli/src/utils/checkBrowser.test.ts b/packages/cli/src/utils/checkBrowser.test.ts
index 7b38b1ef22..aaf70343c7 100644
--- a/packages/cli/src/utils/checkBrowser.test.ts
+++ b/packages/cli/src/utils/checkBrowser.test.ts
@@ -1337,6 +1337,7 @@ function fakePage() {
return Object.assign(Object.create(null), {
on: vi.fn(),
viewport: () => ({ width: 640, height: 360 }),
+ screenshot: vi.fn(async () => "c3R1Yg=="),
addScriptTag: vi.fn(async ({ content }: { content: string }) => {
window.eval(content);
}),
diff --git a/packages/cli/src/utils/checkBrowser.ts b/packages/cli/src/utils/checkBrowser.ts
index c4c42ce8b2..35b1deece5 100644
--- a/packages/cli/src/utils/checkBrowser.ts
+++ b/packages/cli/src/utils/checkBrowser.ts
@@ -729,9 +729,9 @@ function wireNetworkListeners(page: Page, drafts: RuntimeDraft[], clock: Runtime
});
}
-function createPageDriver(
+export function createPageDriver(
page: Page,
- clock: RuntimeClock,
+ clock: RuntimeClock = createRuntimeClock(),
sampleLog?: SampleWindow,
): CheckAuditDriver {
return {
@@ -771,6 +771,15 @@ function createPageDriver(
return issues;
},
collectLayoutGeometry: () => collectLayoutGeometry(page),
+ captureFrame: (scope) => captureFrame(page, scope),
+ framesDiffer: (first, second) =>
+ page
+ .evaluate(
+ (a, b) => Reflect.apply(Reflect.get(window, "__hyperframesFramesDiffer"), window, [a, b]),
+ first,
+ second,
+ )
+ .then((differ) => differ === true),
collectSeekClock: () => collectSeekClock(page),
collectRotationSample: (time) => collectRotationSample(page, time),
collectOffPivotRotationSample: (time) => collectOffPivotRotationSample(page, time),
@@ -999,6 +1008,45 @@ async function collectOverlapGrid(page: Page, times: number[]): Promise<Anchored
);
}
+async function captureFrame(page: Page, scope?: string): Promise<string> {
+ if (!scope) return page.screenshot({ encoding: "base64", type: "png" });
+ try {
+ const box = await page.evaluate(isolateScopePaint, scope);
+ if (!box || box.width < 1 || box.height < 1) return "";
+ return await page.screenshot({ encoding: "base64", type: "png", clip: box });
+ } finally {
+ await page.evaluate(restoreScopePaint);
+ }
+}
+
+// Liveness signs only the scope's subtree, so its frame must show only that paint: anything else behind or
+// over the box (a moving background, grain) would read as the scope moving. Hidden like the contrast pass's glyphs.
+function isolateScopePaint(
+ scope: string,
+): { x: number; y: number; width: number; height: number } | null {
+ let target: Element | null = null;
+ try {
+ target = document.querySelector(scope);
+ } catch {
+ return null;
+ }
+ if (!target) return null;
+ const visibility = getComputedStyle(target).visibility;
+ target.setAttribute("data-hf-capture-scope", "");
+ const style = document.createElement("style");
+ style.id = "__hf_capture_scope_style";
+ style.textContent = `:not([data-hf-capture-scope], [data-hf-capture-scope] *) { visibility: hidden !important; }
+ [data-hf-capture-scope] { visibility: ${visibility} !important; }`;
+ document.head.append(style);
+ const rect = target.getBoundingClientRect();
+ return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+}
+
+function restoreScopePaint(): void {
+ document.getElementById("__hf_capture_scope_style")?.remove();
+ document.querySelector("[data-hf-capture-scope]")?.removeAttribute("data-hf-capture-scope");
+}
+
async function collectLayoutGeometry(page: Page): Promise<string> {
return page.evaluate(() => {
const geometry = Reflect.get(window, "__hyperframesLayoutGeometry");
diff --git a/packages/cli/src/utils/checkPipeline.ts b/packages/cli/src/utils/checkPipeline.ts
index 14322bc698..0de30ca91d 100644
--- a/packages/cli/src/utils/checkPipeline.ts
+++ b/packages/cli/src/utils/checkPipeline.ts
@@ -30,7 +30,9 @@ import {
import {
assertionTargets,
collectSamplingTargets,
+ DEFAULT_MAX_STATIC_SEC,
evaluateMotion,
+ frozenSpans,
type Canvas,
type MotionFrame,
} from "./motionAudit.js";
@@ -712,6 +714,78 @@ function detectSweepStatic(
return [];
}
+// The signature reads DOM channels, which miss paint such as SVG mask and clip contents, stroke dashes and
+// canvas or WebGL pixels. Before calling a sweep still, the rendered frames get the last word. A change counts
+// only if the first time still renders its first frame: wall-clock paint (an unregistered rAF loop) is no seek.
+async function framesMoved(driver: CheckAuditDriver, times: number[]): Promise<boolean> {
+ const [firstTime, ...rest] = times;
+ if (firstTime === undefined) return false;
+ const first = await frameAt(driver, firstTime);
+ for (const time of rest) {
+ if (!(await driver.framesDiffer(first, await frameAt(driver, time)))) continue;
+ return !(await driver.framesDiffer(first, await frameAt(driver, firstTime)));
+ }
+ return false;
+}
+
+async function frameAt(driver: CheckAuditDriver, time: number, scope?: string): Promise<string> {
+ await driver.seek(time, true);
+ return driver.captureFrame(scope);
+}
+
+// keepsMoving reads the same liveness channels, so a span it calls frozen gets the frames' word too: one capture
+// every half maxStaticSec, compared with the last capture that differed; frames up to the next capture share its mark.
+async function withFrameMotion(
+ driver: CheckAuditDriver,
+ frames: MotionFrame[],
+ assertions: MotionAssertion[],
+): Promise<MotionFrame[]> {
+ const marked = frames.map((frame) => ({ ...frame, liveness: { ...frame.liveness } }));
+ for (const assertion of assertions) {
+ if (assertion.kind !== "keepsMoving") continue;
+ const scope = assertion.withinSelector ?? "*";
+ // A scope that matched nothing stays motion_selector_missing.
+ if (frames.every((frame) => !frame.liveness[scope])) continue;
+ const maxStaticSec = assertion.maxStaticSec ?? DEFAULT_MAX_STATIC_SEC;
+ for (const span of frozenSpans(frames, scope, maxStaticSec)) {
+ const held = frames.find((frame) => frame.time === span.start)?.liveness[scope];
+ // The frame that ends a span opens the next run, so only frames still holding the span's signature belong.
+ const inSpan = marked.filter(
+ (frame, index) =>
+ frame.time >= span.start &&
+ frame.time <= span.end &&
+ frames[index]?.liveness[scope] === held,
+ );
+ await markFrameChanges(driver, inSpan, assertion.withinSelector, maxStaticSec / 2);
+ }
+ }
+ return marked;
+}
+
+async function markFrameChanges(
+ driver: CheckAuditDriver,
+ frames: MotionFrame[],
+ within: string | undefined,
+ captureEverySec: number,
+): Promise<void> {
+ const scope = within ?? "*";
+ let reference: string | undefined;
+ let mark = 0;
+ let nextCapture = Number.NEGATIVE_INFINITY;
+ for (const frame of frames) {
+ if (frame.time >= nextCapture) {
+ nextCapture = frame.time + captureEverySec;
+ const capture = await frameAt(driver, frame.time, within);
+ if (reference === undefined) reference = capture;
+ else if (await driver.framesDiffer(reference, capture)) {
+ reference = capture;
+ mark++;
+ }
+ }
+ frame.liveness[scope] = `${frame.liveness[scope] ?? ""}|frame${mark}`;
+ }
+}
+
function anAnimationIsStuck(samples: { clock: SeekClock[] }[]): boolean {
const seenById = new Map<number, SeekClock[]>();
for (const sample of samples) {
@@ -1314,22 +1388,34 @@ export async function runAuditGrid(
let motionIssues = plan.preflightIssues;
if (motion.kind === "valid" && plan.assertions.length > 0 && collected.motionFrames.length > 0) {
- const evaluated = evaluateMotion(
- collected.motionFrames,
- plan.assertions,
- await driver.getCanvas(),
- );
+ const canvas = await driver.getCanvas();
+ let evaluated = evaluateMotion(collected.motionFrames, plan.assertions, canvas);
+ if (evaluated.some((issue) => issue.code === "motion_frozen")) {
+ const frames = await withFrameMotion(driver, collected.motionFrames, plan.assertions);
+ evaluated = evaluateMotion(frames, plan.assertions, canvas);
+ }
motionIssues = [...motionIssues, ...(await driver.anchorMotionIssues(evaluated))];
}
const userPicked = new Set(grid.userPickedSamples);
- const sweepFindings = options.range
+ const sweepSamples = collected.layoutStateSignatures.filter(
+ (sample) => !userPicked.has(sample.time),
+ );
+ const sweepVerdict = options.range
? []
: detectSweepStatic(
grid.duration,
- collected.layoutStateSignatures.filter((sample) => !userPicked.has(sample.time)),
+ sweepSamples,
motionIssues,
await driver.hasNoTimelineDeclaration(),
);
+ const sweepFindings =
+ sweepVerdict.length > 0 &&
+ (await framesMoved(
+ driver,
+ sweepSamples.map((sample) => sample.time),
+ ))
+ ? []
+ : sweepVerdict;
const rotationFindings = detectRotationPivotDrift(
collected.rotationSamples,
await driver.getCanvas(),
diff --git a/packages/cli/src/utils/checkSweep.chromium.test.ts b/packages/cli/src/utils/checkSweep.chromium.test.ts
new file mode 100644
index 0000000000..ce018a6e11
--- /dev/null
+++ b/packages/cli/src/utils/checkSweep.chromium.test.ts
@@ -0,0 +1,203 @@
+// Real-Chromium pins for sweep_static and keepsMoving: paint the DOM signature cannot read must still count as motion.
+// Skipped without a local Chrome; opt-in on Windows (HYPERFRAMES_BROWSER_TESTS=1), like the other Chromium suites.
+import { existsSync } from "node:fs";
+import type { Browser, Page } from "puppeteer-core";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { findSystemBrowser } from "../browser/manager.js";
+import { createPageDriver } from "./checkBrowser.js";
+import { DEFAULT_CHECK_OPTIONS, runAuditGrid } from "./checkPipeline.js";
+import type { MotionSpecResolution } from "./checkTypes.js";
+import type { MotionAssertion } from "./motionSpec.js";
+
+function resolveExecutable(): string | undefined {
+ for (const name of ["HYPERFRAMES_BROWSER_PATH", "PUPPETEER_EXECUTABLE_PATH"]) {
+ const candidate = process.env[name];
+ if (candidate && existsSync(candidate)) return candidate;
+ }
+ return findSystemBrowser()?.executablePath;
+}
+
+const executablePath = resolveExecutable();
+const RUNS_CHROMIUM =
+ !!executablePath &&
+ (process.platform !== "win32" || process.env.HYPERFRAMES_BROWSER_TESTS === "1");
+const BROWSER_LAUNCH_TIMEOUT_MS = 120_000;
+
+// A 6 s film whose only motion is what `draw(t)` paints; `window.__hf` is the seek target check drives.
+function film(body: string, draw: string): string {
+ return `<!doctype html><html><head><style>
+ html, body { margin: 0; width: 640px; height: 360px; overflow: hidden; background: #0a0a0a; }
+ </style></head><body>
+ <div id="root" data-composition-id="main" data-duration="6" data-width="640" data-height="360">${body}</div>
+ <script>
+ const draw = (t) => { ${draw} };
+ window.__hf = { duration: 6, seek: draw };
+ draw(0);
+ </script>
+ </body></html>`;
+}
+
+const MOVING_FILMS: [string, string][] = [
+ [
+ "an SVG mask whose circle radius grows",
+ film(
+ `<svg width="640" height="360"><defs><mask id="m"><rect width="640" height="360" fill="black"/>
+ <circle id="hole" cx="320" cy="180" r="0" fill="white"/></mask></defs>
+ <rect width="640" height="360" fill="#ff5a1f" mask="url(#m)"/></svg>`,
+ `document.getElementById("hole").setAttribute("r", String(t * 60));`,
+ ),
+ ],
+ [
+ "a stroke-dashoffset line reveal",
+ film(
+ `<svg width="640" height="360"><path id="line" d="M40 180 C 200 20, 440 340, 600 180"
+ stroke="#fff" stroke-width="4" fill="none" stroke-dasharray="800" stroke-dashoffset="800"/></svg>`,
+ `document.getElementById("line").setAttribute("stroke-dashoffset", String(800 - t * 130));`,
+ ),
+ ],
+ [
+ "a thin line drawn on a 2D canvas",
+ film(
+ `<canvas id="c" width="640" height="360"></canvas>`,
+ `const ctx = document.getElementById("c").getContext("2d");
+ ctx.clearRect(0, 0, 640, 360); ctx.strokeStyle = "#4ade80"; ctx.lineWidth = 1; ctx.beginPath();
+ ctx.moveTo(40, 180); ctx.lineTo(40 + t * 90, 180 - t * 20); ctx.stroke();`,
+ ),
+ ],
+ [
+ "a WebGL canvas whose clear color fades",
+ film(
+ `<canvas id="c" width="640" height="360"></canvas>`,
+ `const gl = document.getElementById("c").getContext("webgl");
+ gl.clearColor(t / 6, 0.2, 0.4, 1); gl.clear(gl.COLOR_BUFFER_BIT);`,
+ ),
+ ],
+];
+
+const STILL_FILM = film(
+ `<h1 style="margin: 0; padding: 140px 0 0 200px; color: #fff; font: 600 48px sans-serif">Still</h1>`,
+ "",
+);
+
+describe.skipIf(!RUNS_CHROMIUM)("frozen-sweep guard in Chromium", () => {
+ let browser: Browser;
+
+ beforeAll(async () => {
+ const puppeteer = await import("puppeteer-core");
+ browser = await puppeteer.default.launch({
+ headless: true,
+ executablePath,
+ args: ["--no-sandbox", "--disable-dev-shm-usage", "--disable-gpu"],
+ });
+ }, BROWSER_LAUNCH_TIMEOUT_MS);
+
+ afterAll(async () => {
+ await browser?.close();
+ });
+
+ // A page per film: setContent keeps the window, so one film's globals would leak into the next.
+ async function onPage<T>(html: string, run: (page: Page) => Promise<T>): Promise<T> {
+ const page = await browser.newPage();
+ await page.setViewport({ width: 640, height: 360 });
+ await page.setContent(html);
+ return run(page).finally(() => page.close());
+ }
+
+ async function findings(html: string, assertions: MotionAssertion[] = []) {
+ const motion: MotionSpecResolution =
+ assertions.length > 0
+ ? { kind: "valid", path: "index.motion.json", spec: { assertions } }
+ : { kind: "none" };
+ const result = await onPage(html, (page) =>
+ runAuditGrid(createPageDriver(page), { ...DEFAULT_CHECK_OPTIONS, contrast: false }, motion),
+ );
+ const messages = (issues: { code: string; message: string }[], code: string) =>
+ issues.filter((issue) => issue.code === code).map((issue) => issue.message);
+ return {
+ sweep: messages(result.layoutIssues, "sweep_static"),
+ frozen: messages(result.motionIssues, "motion_frozen"),
+ };
+ }
+
+ it.each(MOVING_FILMS)("does not call %s static", async (_, html) => {
+ expect((await findings(html)).sweep).toEqual([]);
+ });
+
+ it.each(MOVING_FILMS)("does not call %s frozen under keepsMoving", async (_, html) => {
+ const result = await findings(html, [
+ { kind: "keepsMoving" },
+ { kind: "keepsMoving", withinSelector: "#root > :first-child" },
+ ]);
+ expect(result.frozen).toEqual([]);
+ });
+
+ it("still warns on, and keepsMoving still fails, a film where nothing on screen moves", async () => {
+ const result = await findings(STILL_FILM, [{ kind: "keepsMoving" }]);
+ expect(result.frozen).toEqual([expect.stringContaining("nothing moves between 0s and 6s")]);
+ // A motion_frozen finding already names the symptom, so the sweep guard stays quiet.
+ expect(result.sweep).toEqual([]);
+ expect((await findings(STILL_FILM)).sweep).toEqual(["Nothing on screen moved under seek."]);
+ });
+
+ it("keeps a still title frozen under keepsMoving while the background behind it moves", async () => {
+ const html = film(
+ `<div id="bg" style="position: absolute; inset: 0; background: linear-gradient(90deg, #f40, #04f)"></div>
+ <h1 id="title" style="position: absolute; left: 120px; top: 120px; margin: 0; padding: 40px;
+ color: #fff; font: 600 48px sans-serif">Still</h1>`,
+ `document.getElementById("bg").style.backgroundPosition = (t * 100) + "px 0";`,
+ );
+ const result = await findings(html, [{ kind: "keepsMoving", withinSelector: "#title" }]);
+ expect(result.frozen).toEqual([expect.stringContaining("nothing moves within #title")]);
+ });
+
+ it("still warns on a canvas that animates by the wall clock, not by the seek", async () => {
+ const html = film(
+ `<canvas id="c" width="640" height="360"></canvas>
+ <script>
+ const loop = () => {
+ const ctx = document.getElementById("c").getContext("2d");
+ ctx.fillStyle = "#000"; ctx.fillRect(0, 0, 640, 360);
+ ctx.fillStyle = "#fff"; ctx.fillRect((performance.now() / 4) % 600, 160, 40, 40);
+ requestAnimationFrame(loop);
+ };
+ loop();
+ </script>`,
+ "",
+ );
+ expect((await findings(html)).sweep).toEqual(["Nothing on screen moved under seek."]);
+ });
+
+ it("reads a still film's frames as unchanged across 10 seeks", async () => {
+ const verdicts = await onPage(STILL_FILM, async (page) => {
+ const driver = createPageDriver(page);
+ await driver.initialize(false);
+ const frames: string[] = [];
+ for (let seek = 0; seek < 10; seek++) {
+ await driver.seek(seek * 0.6, true);
+ frames.push(await driver.captureFrame());
+ }
+ return Promise.all(frames.map((frame) => driver.framesDiffer(frames[0] ?? "", frame)));
+ });
+ expect(verdicts).toEqual(Array(10).fill(false));
+ });
+
+ it.each([
+ ["one changed pixel as render noise", 1, false],
+ ["a 5x5 square as motion", 5, true],
+ ])("reads %s", async (_, size, moved) => {
+ const html = film(
+ `<canvas id="c" width="640" height="360"></canvas>`,
+ `const ctx = document.getElementById("c").getContext("2d");
+ ctx.clearRect(0, 0, 640, 360); if (t > 0) { ctx.fillStyle = "#fff"; ctx.fillRect(100, 100, ${size}, ${size}); }`,
+ );
+ const differ = await onPage(html, async (page) => {
+ const driver = createPageDriver(page);
+ await driver.initialize(false);
+ await driver.seek(0, true);
+ const before = await driver.captureFrame();
+ await driver.seek(3, true);
+ return driver.framesDiffer(before, await driver.captureFrame());
+ });
+ expect(differ).toBe(moved);
+ });
+});
diff --git a/packages/cli/src/utils/checkTypes.ts b/packages/cli/src/utils/checkTypes.ts
index 27938ece79..4c58c1fcec 100644
--- a/packages/cli/src/utils/checkTypes.ts
+++ b/packages/cli/src/utils/checkTypes.ts
@@ -215,6 +215,8 @@ export interface CheckAuditDriver {
/** Frozen-sweep guard (#U10): an opaque fingerprint of the seeked visual state, from
* motion-signature.browser.js (shared with motion-sample's liveness). Legacy name kept. */
collectLayoutGeometry(): Promise<string>;
+ captureFrame(scope?: string): Promise<string>;
+ framesDiffer(first: string, second: string): Promise<boolean>;
collectSeekClock(): Promise<SeekClock[]>;
/** rotation_pivot_drift: every rotatable element's bbox center/size/angle at
* the current seeked state. Accumulated across the grid — see checkPipeline. */
diff --git a/packages/cli/src/utils/motionAudit.ts b/packages/cli/src/utils/motionAudit.ts
index 2e5fa132dd..c6c3a83ca7 100644
--- a/packages/cli/src/utils/motionAudit.ts
+++ b/packages/cli/src/utils/motionAudit.ts
@@ -6,7 +6,7 @@ const APPEAR_OPACITY = 0.5;
/** Pixels an element may exceed the canvas edge before it counts as off-frame. */
const FRAME_TOLERANCE = 1;
/** Default longest allowed fully-static window for keepsMoving, in seconds. */
-const DEFAULT_MAX_STATIC_SEC = 2;
+export const DEFAULT_MAX_STATIC_SEC = 2;
export interface FrameSample {
rect: LayoutRect;
@@ -161,36 +161,18 @@ function staysInFrame(frames: MotionFrame[], selector: string, canvas: Canvas):
return [];
}
-function keepsMoving(
+export function frozenSpans(
frames: MotionFrame[],
- within: string | undefined,
+ scope: string,
maxStaticSec: number,
-): LayoutIssue[] {
- // "*" is reserved for whole-canvas scope; motionSpec.ts rejects it as a user-supplied withinSelector.
- const scope = within ?? "*";
- if (within && frames.every((frame) => !frame.liveness[scope])) {
- return [missingIssue(within, 0)];
- }
-
- const issues: LayoutIssue[] = [];
+): { start: number; end: number }[] {
+ const spans: { start: number; end: number }[] = [];
const first = frames[0];
- if (!first) return issues;
+ if (!first) return spans;
let runStart = first.time;
let runSig = first.liveness[scope] ?? "";
- const flush = (endTime: number) => {
- const span = endTime - runStart;
- if (span > maxStaticSec) {
- issues.push({
- code: "motion_frozen",
- severity: "error",
- time: runStart,
- selector: within ?? "composition",
- message: `nothing moves${within ? ` within ${within}` : ""} between ${round(runStart)}s and ${round(endTime)}s (${round(span)}s static) — should keep moving`,
- rect: ZERO_RECT,
- fixHint:
- "Add or extend motion so no shot freezes for this long, or shorten the static hold.",
- });
- }
+ const flush = (end: number) => {
+ if (end - runStart > maxStaticSec) spans.push({ start: runStart, end });
};
let lastTime = runStart;
@@ -204,7 +186,28 @@ function keepsMoving(
}
}
flush(lastTime);
- return issues;
+ return spans;
+}
+
+function keepsMoving(
+ frames: MotionFrame[],
+ within: string | undefined,
+ maxStaticSec: number,
+): LayoutIssue[] {
+ // "*" is reserved for whole-canvas scope; motionSpec.ts rejects it as a user-supplied withinSelector.
+ const scope = within ?? "*";
+ if (within && frames.every((frame) => !frame.liveness[scope])) {
+ return [missingIssue(within, 0)];
+ }
+ return frozenSpans(frames, scope, maxStaticSec).map(({ start, end }) => ({
+ code: "motion_frozen",
+ severity: "error",
+ time: start,
+ selector: within ?? "composition",
+ message: `nothing moves${within ? ` within ${within}` : ""} between ${round(start)}s and ${round(end)}s (${round(end - start)}s static) — should keep moving`,
+ rect: ZERO_RECT,
+ fixHint: "Add or extend motion so no shot freezes for this long, or shorten the static hold.",
+ }));
}
/**