Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
perf(cli): check splits its samples over a second Chrome when a core and memory are spare (#5896)
Miguel Ángel952c6ba1c5cd
diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.tsindex 30348fbc09..ae720610a7 100644--- a/packages/cli/src/commands/check.test.ts+++ b/packages/cli/src/commands/check.test.ts@@ -1635,6 +1635,117 @@ describe("check pipeline", () => {expect(checkExitCode(strict.report)).toBe(1);});+ it("splits samples over a helper page and returns what one page seeking every sample returns", async () => {+ const pageOfTime = () => {+ let seeked = 0;+ return fakeDriver({+ seek: vi.fn(async (time: number) => {+ seeked = time;+ }),+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),+ collectLayoutGeometry: vi.fn(async () => `geometry-${seeked}`),+ collectContrast: vi.fn(async (time: number) => ({+ entries: [contrastEntry({ ...anchor("#hero", time), ratio: 1 + time })],+ pngBase64: `${PNG_BASE64}-${time}`,+ })),+ });+ };+ const options = { ...DEFAULT_CHECK_OPTIONS, contrast: true };+ const { timings: _serialTimings, ...serial } = await runAuditGrid(+ pageOfTime(),+ options,+ noMotion(),+ );+ const primary = pageOfTime();+ const helper = pageOfTime();+ const { timings: _splitTimings, ...split } = await runAuditGrid(+ primary,+ options,+ noMotion(),+ Promise.resolve([helper]),+ );++ expect(split).toEqual(serial);+ expect(serial.layoutIssues.length).toBeGreaterThan(2);+ expect(helper.initialize).toHaveBeenCalledWith(true);+ const seeks = (driver: CheckAuditDriver) =>+ vi.mocked(driver.seek).mock.calls.map(([time]) => time);+ expect(seeks(helper).length).toBeGreaterThan(0);+ expect(seeks(primary).filter((time) => seeks(helper).includes(time))).toEqual([]);+ });++ it("redoes a crashed helper page's samples on the first page and returns the serial result", async () => {+ let helperSeeks = 0;+ const pageOfTime = (crashOnSeek?: number) => {+ let seeked = 0;+ return fakeDriver({+ markSamples: vi.fn(),+ seek: vi.fn(async (time: number) => {+ if (crashOnSeek !== undefined && ++helperSeeks === crashOnSeek)+ throw new Error("Target closed");+ await new Promise((resolve) => setImmediate(resolve));+ seeked = time;+ }),+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),+ collectLayoutGeometry: vi.fn(async () => `geometry-${seeked}`),+ });+ };+ const { timings: _serialTimings, ...serial } = await runAuditGrid(+ pageOfTime(),+ DEFAULT_CHECK_OPTIONS,+ noMotion(),+ );+ const unhandled = vi.fn();+ process.on("unhandledRejection", unhandled);+ const primary = pageOfTime();+ const helper = pageOfTime(2);+ const { timings: _splitTimings, ...split } = await runAuditGrid(+ primary,+ DEFAULT_CHECK_OPTIONS,+ noMotion(),+ Promise.resolve([helper]),+ );+ await new Promise((resolve) => setImmediate(resolve));+ process.off("unhandledRejection", unhandled);++ expect(split).toEqual(serial);+ expect(helperSeeks).toBe(2);+ expect(helper.markSamples).toHaveBeenLastCalledWith("drop");+ expect(unhandled).not.toHaveBeenCalled();+ });++ it("waits for the helper's sample in flight when the first page runs out of samples", async () => {+ const pageOfTime = (onSeek?: () => Promise<void>) =>+ fakeDriver({+ seek: vi.fn(async () => onSeek?.()),+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),+ collectLayoutGeometry: vi.fn(async () => "geometry"),+ });+ const serialPage = pageOfTime();+ const { timings: _serialTimings, ...serial } = await runAuditGrid(+ serialPage,+ DEFAULT_CHECK_OPTIONS,+ noMotion(),+ );+ const samples = vi.mocked(serialPage.seek).mock.calls.length;+ let firstPageSeeks = 0;+ let othersTaken!: () => void;+ const allOthersTaken = new Promise<void>((resolve) => (othersTaken = resolve));+ const primary = pageOfTime(async () => {+ if (++firstPageSeeks === samples - 1) setImmediate(othersTaken);+ });+ const helper = pageOfTime(() => allOthersTaken);+ const { timings: _splitTimings, ...split } = await runAuditGrid(+ primary,+ DEFAULT_CHECK_OPTIONS,+ noMotion(),+ Promise.resolve([helper]),+ );++ expect(vi.mocked(helper.seek).mock.calls).toHaveLength(1);+ expect(split).toEqual(serial);+ });+it("fails clearly without samples when no timeline duration is available, without hanging", async () => {const driver = fakeDriver({ getDuration: vi.fn(async () => 0) });await expect(runAuditGrid(driver, DEFAULT_CHECK_OPTIONS, noMotion())).rejects.toThrow(diff --git a/packages/cli/src/utils/checkBrowser.test.ts b/packages/cli/src/utils/checkBrowser.test.tsindex 2ac2369211..17467a3f6a 100644--- a/packages/cli/src/utils/checkBrowser.test.ts+++ b/packages/cli/src/utils/checkBrowser.test.ts@@ -2,7 +2,7 @@// fallow-ignore-file code-duplicationimport { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { mkdtempSync, rmSync, writeFileSync } from "node:fs";-import { tmpdir } from "node:os";+import os, { tmpdir } from "node:os";import { join } from "node:path";import {openSettledCompositionPage,@@ -19,6 +19,8 @@ import {dropFailedProxyEchoes,runBrowserCheck,collectSeekClock,+ mergeHelperDrafts,+ samplingBrowserCount,} from "./checkBrowser.js";import type { ProjectDir } from "./project.js";@@ -94,9 +96,13 @@ const PROJECT: ProjectDir = {indexPath: "/project/index.html",};-// The overlap grid logs one marker per sample; keep them out of test output.+// The overlap grid logs one marker per sample; keep them out of test output. One core keeps+// the browser pass on one page unless a test says otherwise.beforeEach(() => {vi.spyOn(console, "debug").mockImplementation(() => undefined);+ vi.spyOn(os, "availableParallelism").mockReturnValue(1);+ vi.spyOn(os, "freemem").mockReturnValue(16 * 1024 ** 3);+ vi.spyOn(process, "availableMemory").mockReturnValue(16 * 1024 ** 3);});afterEach(() => {@@ -177,6 +183,83 @@ it("carries raw browser geometry through the page driver and pipeline", async ()expect(mocks.serverClose).toHaveBeenCalledOnce();});+it("splits the samples over a second Chrome and reports what one Chrome reports", async () => {+ mountCanvasFixture(`<p id="copy" data-layout-name="copy">Hi</p>`);+ type Message = ReturnType<typeof fakeConsoleMessage>;+ const run = async (cores: number, helper: "works" | "crashes" | "never opens" = "works") => {+ vi.mocked(os.availableParallelism).mockReturnValue(cores);+ let helperSeeks = 0;+ const pages: ReturnType<typeof fakePage>[] = [];+ const helperPages = new Set<unknown>();+ const handlers = new Map<unknown, ((message: Message) => void)[]>();+ const log = (page: unknown, text: string) =>+ handlers.get(page)?.forEach((handler) => handler(fakeConsoleMessage("error", text)));+ const browser = Object.assign(Object.create(null), {+ close: vi.fn(async () => undefined),+ process: () => ({ exitCode: 0, signalCode: null }),+ });+ vi.mocked(openSettledCompositionPage).mockImplementation(+ async (_html: string, _url: string, options: OpenSettledCompositionPageOptions) => {+ const page = fakePage();+ page.on = vi.fn((event: string, handler: (message: Message) => void) => {+ if (event === "console") handlers.set(page, [...(handlers.get(page) ?? []), handler]);+ });+ const opened = pages.push(page);+ // Only the first page's open takes prelaunched Chromes.+ if (!("prelaunched" in options)) helperPages.add(page);+ if (helperPages.has(page) && helper === "never opens")+ await new Promise((_, reject) => options.signal?.addEventListener("abort", reject));+ options.onBrowser?.(browser);+ await options.beforeNavigate?.(page);+ log(page, `logged at load on page ${opened}`);+ return { page, browser, renderReadyTimedOut: false };+ },+ );+ vi.mocked(seekCompositionTimeline).mockImplementation(async (page, time) => {+ if (helperPages.has(page) && helper === "crashes" && ++helperSeeks === 2) {+ log(page, "renderer crashed");+ throw new Error("Target closed");+ }+ log(page, `seeked to ${time}`);+ });+ const result = await runBrowserCheck(+ PROJECT,+ { ...DEFAULT_CHECK_OPTIONS, contrast: false },+ { kind: "none" },+ runAuditGrid,+ );+ const seeks = vi.mocked(seekCompositionTimeline).mock.calls;+ vi.mocked(seekCompositionTimeline).mockClear();+ return {+ pages,+ seekingPages: new Set(seeks.map(([page]) => page)).size,+ messages: result.runtimeFindings.map((finding) => `${finding.time} ${finding.message}`),+ };+ };++ const serial = await run(1);+ const split = await run(4);+ expect(serial.pages).toHaveLength(1);+ expect(split.pages).toHaveLength(2);+ expect(split.seekingPages).toBe(2);+ const loads = (messages: string[]) => messages.filter((line) => line.includes("at load"));+ const sampled = (messages: string[]) => messages.filter((line) => !line.includes("at load"));+ expect(loads(serial.messages)).toHaveLength(1);+ expect(loads(split.messages)).toHaveLength(1);+ expect(sampled(split.messages)).toEqual(sampled(serial.messages));+ expect(serial.messages.length).toBeGreaterThan(3);++ const crashed = await run(4, "crashes");+ expect(crashed.seekingPages).toBe(2);+ expect(loads(crashed.messages)).toHaveLength(1);+ expect(sampled(crashed.messages)).toEqual(sampled(serial.messages));+ const unopened = await run(4, "never opens");+ expect(unopened.pages).toHaveLength(2);+ expect(unopened.seekingPages).toBe(1);+ expect(loads(unopened.messages)).toHaveLength(1);+ expect(sampled(unopened.messages)).toEqual(sampled(serial.messages));+});+it("runs the dense overlap grid in one page task, keeping each sample's time on what it logs", async () => {mountCanvasFixture(`<section data-composition-file="scenes/copy.html"><p id="copy" data-layout-name="copy">Hi</p></section>`,@@ -836,6 +919,76 @@ describe("keepBrokenImageAborts", () => {});});+describe("samplingBrowserCount", () => {+ const GB = 1024 ** 3;+ it("uses a second Chrome only with a spare core, 250 MB free each and more than one sample", () => {+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8, 16 * GB)).toBe(2);+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 3, 1 * GB)).toBe(2);+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 2, 16 * GB)).toBe(1);+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 1, 2 * GB)).toBe(1);+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8, 400 * 1024 ** 2)).toBe(1);+ expect(samplingBrowserCount({ ...DEFAULT_CHECK_OPTIONS, at: [1] }, 8, 16 * GB)).toBe(1);+ });++ it("counts a container's memory limit, not the host's free memory", () => {+ vi.mocked(os.freemem).mockReturnValue(100 * GB);+ vi.mocked(process.availableMemory).mockReturnValue(400 * 1024 ** 2);+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8)).toBe(1);+ vi.mocked(process.availableMemory).mockReturnValue(16 * GB);+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8)).toBe(2);+ });+});++describe("mergeHelperDrafts", () => {+ const draft = (message: string, time: number) =>+ ({ code: "console_error", severity: "error", message, time }) as const;+ it("orders the helper's sample-loop messages by time and drops its load and same-time repeats", () => {+ const primary = {+ drafts: [draft("load", 0), draft("at 0", 0), draft("at 2", 2), draft("dense", 0)],+ start: 1,+ end: 3,+ };+ const helper = {+ drafts: [draft("load", 0), draft("at 1", 1), draft("at 2", 2), draft("at 3", 3)],+ start: 1,+ end: 4,+ };+ expect(mergeHelperDrafts(primary, helper).map((entry) => entry.message)).toEqual([+ "load",+ "at 0",+ "at 1",+ "at 2",+ "at 3",+ "dense",+ ]);+ });++ it("orders samples the first page redid after its own later ones", () => {+ const primary = {+ drafts: [draft("load", 0), draft("at 0", 0), draft("at 2", 2), draft("at 1", 1)],+ start: 1,+ end: 4,+ };+ const dropped = { drafts: [draft("at 1", 1)], start: Infinity, end: Infinity };+ expect(mergeHelperDrafts(primary, dropped).map((entry) => entry.message)).toEqual([+ "load",+ "at 0",+ "at 1",+ "at 2",+ ]);+ });++ it("adds nothing from a helper that never sampled", () => {+ const primary = { drafts: [draft("load", 0)], start: 1, end: 1 };+ const helper = {+ drafts: [draft("load", 0)],+ start: Number.POSITIVE_INFINITY,+ end: Number.POSITIVE_INFINITY,+ };+ expect(mergeHelperDrafts(primary, helper)).toEqual(primary.drafts);+ });+});+describe("dropFailedProxyEchoes", () => {it("keeps one finding for a failed proxy and drops the preview's repeats of it", () => {const at = (code: string, message: string, url?: string) =>diff --git a/packages/cli/src/utils/checkBrowser.ts b/packages/cli/src/utils/checkBrowser.tsindex afd25868eb..6dc38db92f 100644--- a/packages/cli/src/utils/checkBrowser.ts+++ b/packages/cli/src/utils/checkBrowser.ts@@ -2,6 +2,7 @@ import type { CheckDeadline } from "./checkDeadline.js";import { BrowserCleanupError, closeManagedBrowser } from "../browser/launch.js";import { checkSnapshotDirectory } from "./checkSnapshotDirectory.js";import { mkdirSync, writeFileSync } from "node:fs";+import os from "node:os";import { join, resolve } from "node:path";import type { Browser, Page } from "puppeteer-core";import {@@ -223,18 +224,18 @@ export async function runBrowserCheck([],options.autoProxy,);- let stamp: RuntimeStamp = { time: 0 };- const clock: RuntimeClock = {- now: () => stamp,- at: (time) => {- stamp = { time };- },- during: (range) => {- stamp = { time: range[0], timeRange: range };- },- };+ const clock = createRuntimeClock();let failure: { kind: "none" } | { kind: "failed"; error: unknown } = { kind: "none" };let chromeBrowser: import("puppeteer-core").Browser | undefined;+ const helperSession =+ samplingBrowserCount(options) > 1+ ? startHelperSession(html, server.url, options, deadline)+ : undefined;+ const helperOpen = helperSession?.opened;+ const helpers = helperOpen?.then(+ (helper) => [helper.driver],+ () => [],+ );try {const launchSettleStart = Date.now();@@ -271,14 +272,18 @@ export async function runBrowserCheck(const message = tweenTailMessage(tail);drafts.push({ code: "gsap_tween_tail", severity: "warning", message, time: tail.later.end });}- const driver = createPageDriver(page, clock);- const result = await runGrid(driver, options, motion);- const broken = await abortedImagesStillBroken(page, drafts);+ const sampleLog = sampleWindow(drafts);+ const driver = createPageDriver(page, clock, sampleLog);+ const result = await runGrid(driver, options, motion, helpers);+ helperSession?.stop();+ const helper = await helperOpen?.catch(() => undefined);+ const merged = helper ? mergeHelperDrafts(sampleLog, helper.sampleLog) : drafts;+ const broken = await abortedImagesStillBroken(page, merged);return {...result,timings: { ...result.timings, launchSettleMs },runtimeFindings: dropFailedProxyEchoes(- keepBrokenImageAborts(drafts, broken),+ keepBrokenImageAborts(merged, broken),failedPaths,).map((draft) => runtimeFinding(draft, rootAnchor)),};@@ -286,10 +291,127 @@ export async function runBrowserCheck(failure = { kind: "failed", error };throw error;} finally {- await closeCheckResources(chromeBrowser, server, failure);+ helperSession?.stop();+ await helperOpen?.catch(() => undefined);+ await closeCheckResources([chromeBrowser, helperSession?.browser()], server, failure);}}+function createRuntimeClock(): RuntimeClock {+ let stamp: RuntimeStamp = { time: 0 };+ return {+ now: () => stamp,+ at: (time) => {+ stamp = { time };+ },+ during: (range) => {+ stamp = { time: range[0], timeRange: range };+ },+ };+}++const SAMPLING_BROWSER_BYTES = 250 * 1024 * 1024;++/** Chromes the sample grid splits over: one per spare core and 250 MB free (a container's limit counts), at most 2. */+export function samplingBrowserCount(+ options: CheckOptions,+ cores = os.availableParallelism(),+ free = Math.min(os.freemem(), process.availableMemory()),+): number {+ if (options.at?.length === 1) return 1;+ return Math.max(1, Math.min(2, cores - 1, Math.floor(free / SAMPLING_BROWSER_BYTES)));+}++interface SampleWindow {+ drafts: RuntimeDraft[];+ start: number;+ end: number;+}++function sampleWindow(drafts: RuntimeDraft[]): SampleWindow {+ return { drafts, start: Number.POSITIVE_INFINITY, end: Number.POSITIVE_INFINITY };+}++interface HelperSession {+ driver: CheckAuditDriver;+ sampleLog: SampleWindow;+}++/** Opens the helper Chrome; stop() cancels an open still in flight and closes it, once its pages are unused. */+function startHelperSession(+ html: string,+ url: string,+ options: CheckOptions,+ deadline: CheckDeadline | undefined,+) {+ const abort = new AbortController();+ let browser: Browser | undefined;+ const opened = openHelperSession(html, url, options, deadline, {+ signal: deadline ? AbortSignal.any([deadline.signal, abort.signal]) : abort.signal,+ onBrowser: (launched) => {+ browser = launched;+ deadline?.ownBrowser(launched);+ },+ });+ return {+ opened,+ browser: () => browser,+ stop: () => {+ abort.abort();+ // The close is shared, so the check's cleanup awaits this same close and reports its error.+ if (browser) void closeManagedBrowser(browser).catch(() => undefined);+ },+ };+}++async function openHelperSession(+ html: string,+ url: string,+ options: CheckOptions,+ deadline: CheckDeadline | undefined,+ owner: { signal: AbortSignal; onBrowser: (browser: Browser) => void },+): Promise<HelperSession> {+ const sampleLog = sampleWindow([]);+ const clock = createRuntimeClock();+ const session = await openSettledCompositionPage(html, url, {+ navigationTimeoutMs: options.timeout,+ renderReadyTimeoutMs: options.timeout,+ renderReadyWarningSuffix: "checking the current page state",+ browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),+ signal: owner.signal,+ onBrowser: owner.onBrowser,+ beforeNavigate: async (page) => {+ wireRuntimeListeners(page, sampleLog.drafts, clock);+ await deadline?.preparePage(page);+ },+ });+ await waitForPreferredSeekTarget(session.page);+ return {+ driver: createPageDriver(session.page, clock, sampleLog),+ sampleLog,+ };+}++const draftKey = (draft: RuntimeDraft) => `${draft.code} ${draft.time} ${draft.message}`;++/**+ * The first page's drafts with the helper's sample-loop drafts merged in by time, as one page seeking every+ * sample would have logged them; the helper's load is the first page's, and what both logged at one time counts once.+ */+export function mergeHelperDrafts(primary: SampleWindow, helper: SampleWindow): RuntimeDraft[] {+ const window = ({ drafts, start, end }: SampleWindow) =>+ drafts.slice(Math.min(start, drafts.length), Math.min(end, drafts.length));+ const own = window(primary);+ const seen = new Set(own.map(draftKey));+ const extra = window(helper).filter((draft) => !seen.has(draftKey(draft)));+ const start = Math.min(primary.start, primary.drafts.length);+ return [+ ...primary.drafts.slice(0, start),+ ...[...own, ...extra].sort((a, b) => a.time - b.time),+ ...primary.drafts.slice(start + own.length),+ ];+}+/*** `check --snapshots`'s per-finding evidence crops. Opens its own session* (the main grid session already closed by the time findings are shaped) and@@ -348,17 +470,17 @@ export async function captureFindingCrops(failure = { kind: "failed", error };throw error;} finally {- await closeCheckResources(chromeBrowser, server, failure);+ await closeCheckResources([chromeBrowser], server, failure);}}async function closeCheckResources(- browser: Browser | undefined,+ browsers: (Browser | undefined)[],server: { close(): Promise<void> },failure: { kind: "none" } | { kind: "failed"; error: unknown },): Promise<void> {const cleanup = await Promise.allSettled([- browser ? closeManagedBrowser(browser) : Promise.resolve(),+ ...browsers.map((browser) => (browser ? closeManagedBrowser(browser) : Promise.resolve())),server.close(),]);const errors = cleanup@@ -585,9 +707,18 @@ function wireNetworkListeners(page: Page, drafts: RuntimeDraft[], clock: Runtime});}-function createPageDriver(page: Page, clock: RuntimeClock): CheckAuditDriver {+function createPageDriver(+ page: Page,+ clock: RuntimeClock,+ sampleLog?: SampleWindow,+): CheckAuditDriver {return {initialize: (contrast) => injectAuditScripts(page, contrast),+ markSamples: (phase) => {+ if (!sampleLog) return;+ if (phase === "drop") sampleLog.start = sampleLog.end = Number.POSITIVE_INFINITY;+ else sampleLog[phase] = sampleLog.drafts.length;+ },matchComponents: (components, findings) =>page.evaluate(matchComponentFindings, { components, findings }),getDuration: () => getCompositionDuration(page),diff --git a/packages/cli/src/utils/checkPipeline.ts b/packages/cli/src/utils/checkPipeline.tsindex 2d5efd0343..14322bc698 100644--- a/packages/cli/src/utils/checkPipeline.ts+++ b/packages/cli/src/utils/checkPipeline.ts@@ -424,18 +424,8 @@ async function collectGeometryAt(return issues;}-async function collectGridSamples(- driver: CheckAuditDriver,- options: CheckOptions,- grid: SampleGrid,- motion: MotionPlan,-): Promise<GridSamples> {- const layoutSet = new Set(grid.layoutSamples);- const motionSet = new Set(motion.times);- const contrastSet = new Set(grid.contrastSamples);- const geometryEnabled = grid.captionSamples.length > 0 || grid.frameSamples.length > 0;- const canvas = geometryEnabled ? await driver.getCanvas() : null;- const collected: GridSamples = {+function emptyGridSamples(): GridSamples {+ return {layoutIssues: [],motionFrames: [],contrastEntries: [],@@ -445,37 +435,121 @@ async function collectGridSamples(rotationSamples: [],indicatorFrames: [],};- for (const time of mergeSampleTimes(grid.layoutSamples, motion.times)) {- await driver.seek(time, contrastSet.has(time));- // Findings collected for THIS sample time, so the overview overlay (below)- // only ever annotates a frame with defects that are actually valid at- // that render time — never a stale bbox from an earlier/later sample.- const issuesAtTime: AnchoredLayoutIssue[] = [];- if (layoutSet.has(time)) {- const layoutIssues = await driver.collectLayout(time, options.tolerance, options.layout);- collected.layoutIssues.push(...layoutIssues);- issuesAtTime.push(...layoutIssues);- collected.layoutStateSignatures.push({- time,- signature: await driver.collectLayoutGeometry(),- clock: await driver.collectSeekClock(),- });- collected.rotationSamples.push(...(await driver.collectRotationSample(time)));- collected.indicatorFrames.push(await driver.collectOffPivotRotationSample(time));- }- if (canvas) {- const geometryIssues = await collectGeometryAt(driver, options, grid, canvas, time);- collected.layoutIssues.push(...geometryIssues);- issuesAtTime.push(...geometryIssues);+}++function appendGridSamples(into: GridSamples, from: GridSamples): void {+ into.layoutIssues.push(...from.layoutIssues);+ into.motionFrames.push(...from.motionFrames);+ into.contrastEntries.push(...from.contrastEntries);+ into.screenshots.push(...from.screenshots);+ // Summed over pages, so with a helper it can exceed the wall time.+ into.contrastMs += from.contrastMs;+ into.layoutStateSignatures.push(...from.layoutStateSignatures);+ into.rotationSamples.push(...from.rotationSamples);+ into.indicatorFrames.push(...from.indicatorFrames);+}++interface SampleSets {+ layout: Set<number>;+ motion: Set<number>;+ contrast: Set<number>;+ canvas: Canvas | null;+}++async function collectSampleAt(+ driver: CheckAuditDriver,+ options: CheckOptions,+ grid: SampleGrid,+ motion: MotionPlan,+ sets: SampleSets,+ time: number,+): Promise<GridSamples> {+ const collected = emptyGridSamples();+ await driver.seek(time, sets.contrast.has(time));+ // Findings collected for THIS sample time, so the overview overlay (below)+ // only ever annotates a frame with defects that are actually valid at+ // that render time — never a stale bbox from an earlier/later sample.+ const issuesAtTime: AnchoredLayoutIssue[] = [];+ if (sets.layout.has(time)) {+ const layoutIssues = await driver.collectLayout(time, options.tolerance, options.layout);+ collected.layoutIssues.push(...layoutIssues);+ issuesAtTime.push(...layoutIssues);+ collected.layoutStateSignatures.push({+ time,+ signature: await driver.collectLayoutGeometry(),+ clock: await driver.collectSeekClock(),+ });+ collected.rotationSamples.push(...(await driver.collectRotationSample(time)));+ collected.indicatorFrames.push(await driver.collectOffPivotRotationSample(time));+ }+ if (sets.canvas) {+ const geometryIssues = await collectGeometryAt(driver, options, grid, sets.canvas, time);+ collected.layoutIssues.push(...geometryIssues);+ issuesAtTime.push(...geometryIssues);+ }+ if (sets.motion.has(time)) {+ collected.motionFrames.push(+ await driver.collectMotionFrame(time, motion.selectors, motion.livenessScopes),+ );+ }+ if (sets.contrast.has(time))+ await collectContrastAt(driver, options, time, issuesAtTime, collected);+ return collected;+}++// Frames are a function of time, so a helper page that is ready takes the next unclaimed sample+// and the merge keeps the serial order. A helper only adds speed: one that fails hands its samples back.+async function collectGridSamples(+ driver: CheckAuditDriver,+ options: CheckOptions,+ grid: SampleGrid,+ motion: MotionPlan,+ helpers: Promise<CheckAuditDriver[]>,+): Promise<GridSamples> {+ const geometryEnabled = grid.captionSamples.length > 0 || grid.frameSamples.length > 0;+ const sets: SampleSets = {+ layout: new Set(grid.layoutSamples),+ motion: new Set(motion.times),+ contrast: new Set(grid.contrastSamples),+ canvas: geometryEnabled ? await driver.getCanvas() : null,+ };+ const times = mergeSampleTimes(grid.layoutSamples, motion.times);+ const pending = times.map((_, index) => index);+ const perTime: GridSamples[] = [];+ const work = async (worker: CheckAuditDriver, taken: number[] = []) => {+ for (let index = pending.shift(); index !== undefined; index = pending.shift()) {+ taken.push(index);+ const time = times[index] ?? 0;+ perTime[index] = await collectSampleAt(worker, options, grid, motion, sets, time);}- if (motionSet.has(time)) {- collected.motionFrames.push(- await driver.collectMotionFrame(time, motion.selectors, motion.livenessScopes),- );+ };+ const helpWith = async (helper: CheckAuditDriver) => {+ const taken: number[] = [];+ try {+ await helper.initialize(options.contrast);+ helper.markSamples?.("start");+ await work(helper, taken);+ helper.markSamples?.("end");+ } catch {+ helper.markSamples?.("drop");+ for (const index of taken) delete perTime[index];+ pending.push(...taken);}- if (contrastSet.has(time))- await collectContrastAt(driver, options, time, issuesAtTime, collected);- }+ };+ let firstPageDone = false;+ const running: Promise<void>[] = [];+ void helpers.then((ready) => {+ for (const helper of ready) if (!firstPageDone) running.push(helpWith(helper));+ });+ driver.markSamples?.("start");+ await work(driver);+ // A helper still opening is never waited for; one mid-sample may yet hand samples back.+ firstPageDone = true;+ await Promise.all(running);+ await work(driver);+ driver.markSamples?.("end");+ const collected = emptyGridSamples();+ for (const samples of perTime) appendGridSamples(collected, samples);await collectMotionOverlapSamples(driver, grid, collected, options.range);return collected;}@@ -1225,6 +1299,7 @@ export async function runAuditGrid(driver: CheckAuditDriver,options: CheckOptions,motion: MotionSpecResolution,+ helpers: Promise<CheckAuditDriver[]> = Promise.resolve([]),): Promise<CheckBrowserResult> {await driver.initialize(options.contrast);const grid = await buildSampleGrid(driver, options);@@ -1234,7 +1309,7 @@ export async function runAuditGrid(grid.duration,);const seekLoopStart = Date.now();- const collected = await collectGridSamples(driver, options, grid, plan);+ const collected = await collectGridSamples(driver, options, grid, plan, helpers);const seekLoopMs = Date.now() - seekLoopStart;let motionIssues = plan.preflightIssues;diff --git a/packages/cli/src/utils/checkTypes.ts b/packages/cli/src/utils/checkTypes.tsindex 9081da74d3..27938ece79 100644--- a/packages/cli/src/utils/checkTypes.ts+++ b/packages/cli/src/utils/checkTypes.ts@@ -192,6 +192,7 @@ export type MotionSpecResolution =export interface CheckAuditDriver {initialize(contrast: boolean): Promise<void>;+ markSamples?(phase: "start" | "end" | "drop"): void;matchComponents?(components: string[], findings: CheckFinding[]): Promise<boolean[]>;getDuration(): Promise<number>;/** True when the root composition explicitly declares that it is intentionally timeline-free. */@@ -272,6 +273,7 @@ export type RunAuditGrid = (driver: CheckAuditDriver,options: CheckOptions,motion: MotionSpecResolution,+ helpers?: Promise<CheckAuditDriver[]>,) => Promise<CheckBrowserResult>;export interface CheckSection<T extends CheckFinding = CheckFinding> {