Merge remote-tracking branch 'origin/main' into HEAD

# Conflicts:
#	skills-manifest.json

Author: jrusso1020

docs/packages/cli.mdx

@@ -542,7 +542,7 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o
     | `--snapshots` | Write overview frames (annotated with labeled finding boxes when there are errors) plus `finding-NN-<code>.png` crops |
     | `--samples` / `--at` / `--at-transitions` | Control the seek grid (default 9 samples; `--at-transitions` adds tween boundaries) |
     | `--tolerance` | Allowed overflow in px before reporting (default 2) |
-    | `--timeout` | Initial settle budget in ms (default 3000) |
+    | `--timeout` | Initial render-ready budget in ms; also raises the page-navigation budget above its 10s floor (default 3000) |
     | `--no-contrast` | Skip the WCAG audit while iterating |
     | `--strict` | Exit non-zero on warnings too (default: only errors) |
     | `--caption-zone "<x0=..;y0=..;x1=..;y1=..>"` | Opt-in band gate: flags content whose center sits inside the fractional band (optional `severity`, `seek`) |

packages/cli/src/browser/manager.test.ts

@@ -130,18 +130,25 @@ function installPuppeteerBrowsersMock(
       executablePath: string;
       path?: string;
       buildId?: string;
+      platform?: string;
     }>;
+    browserPlatform?: string;
     installedInHfCacheError?: Error;
     installResult?: { executablePath: string };
     installImpl?: () => Promise<{ executablePath: string }>;
   } = {},
 ) {
   vi.doMock("@puppeteer/browsers", () => ({
     Browser: { CHROMEHEADLESSSHELL: "chrome-headless-shell" },
-    detectBrowserPlatform: () => "linux",
+    detectBrowserPlatform: () => opts.browserPlatform ?? "linux",
     getInstalledBrowsers: opts.installedInHfCacheError
       ? vi.fn().mockRejectedValue(opts.installedInHfCacheError)
-      : vi.fn().mockResolvedValue(opts.installedInHfCache ?? []),
+      : vi.fn().mockResolvedValue(
+          (opts.installedInHfCache ?? []).map((browser) => ({
+            platform: opts.browserPlatform ?? "linux",
+            ...browser,
+          })),
+        ),
     install: vi
       .fn()
       .mockImplementation(
@@ -222,6 +229,41 @@ describe("findBrowser — cache resolution", () => {
     expect(result).toEqual({ executablePath: SYSTEM_CHROME, source: "system" });
   });
 
+  it("ignores a current-version HyperFrames cache entry for another platform", async () => {
+    Object.defineProperty(process, "platform", { value: "darwin", configurable: true });
+    Object.defineProperty(process, "arch", { value: "arm64", configurable: true });
+    const macArm64Binary = join(
+      HF_CACHE,
+      "chrome-headless-shell",
+      "mac_arm-131.0.6778.85",
+      "chrome-headless-shell-mac-arm64",
+      "chrome-headless-shell",
+    );
+    installFsMocks({ existing: new Set([HF_CACHE, HF_BINARY, macArm64Binary]) });
+    installPuppeteerBrowsersMock({
+      browserPlatform: "mac_arm",
+      installedInHfCache: [
+        {
+          browser: "chrome-headless-shell",
+          executablePath: HF_BINARY,
+          buildId: CHROME_VERSION,
+          platform: "linux",
+        },
+        {
+          browser: "chrome-headless-shell",
+          executablePath: macArm64Binary,
+          buildId: CHROME_VERSION,
+          platform: "mac_arm",
+        },
+      ],
+    });
+
+    const { findBrowser } = await import("./manager.js");
+    const result = await findBrowser();
+
+    expect(result).toEqual({ executablePath: macArm64Binary, source: "cache" });
+  });
+
   it("re-downloads when the hyperframes cache manifest points at a missing binary", async () => {
     const redownloadedBinary = join(
       HF_CACHE,
@@ -492,6 +534,91 @@ describe("findBrowser — cache resolution", () => {
     expect(result).toEqual({ executablePath: PUPPETEER_BINARY, source: "cache" });
   });
 
+  it.each([
+    {
+      hostPlatform: "darwin",
+      hostArch: "arm64",
+      expectedDirectory: "chrome-headless-shell-mac-arm64",
+      expectedExecutable: "chrome-headless-shell",
+    },
+    {
+      hostPlatform: "darwin",
+      hostArch: "x64",
+      expectedDirectory: "chrome-headless-shell-mac-x64",
+      expectedExecutable: "chrome-headless-shell",
+    },
+    {
+      hostPlatform: "linux",
+      hostArch: "x64",
+      expectedDirectory: "chrome-headless-shell-linux64",
+      expectedExecutable: "chrome-headless-shell",
+    },
+    {
+      hostPlatform: "win32",
+      hostArch: "ia32",
+      expectedDirectory: "chrome-headless-shell-win32",
+      expectedExecutable: "chrome-headless-shell.exe",
+    },
+    {
+      hostPlatform: "win32",
+      hostArch: "x64",
+      expectedDirectory: "chrome-headless-shell-win64",
+      expectedExecutable: "chrome-headless-shell.exe",
+    },
+  ])(
+    "selects only the host-compatible cached shell on $hostPlatform/$hostArch when every platform is present",
+    async ({ hostPlatform, hostArch, expectedDirectory, expectedExecutable }) => {
+      Object.defineProperty(process, "platform", { value: hostPlatform, configurable: true });
+      Object.defineProperty(process, "arch", { value: hostArch, configurable: true });
+      const version = "host-148.0.7778.97";
+      const candidates = [
+        ["chrome-headless-shell-linux64", "chrome-headless-shell"],
+        ["chrome-headless-shell-mac-arm64", "chrome-headless-shell"],
+        ["chrome-headless-shell-mac-x64", "chrome-headless-shell"],
+        ["chrome-headless-shell-win32", "chrome-headless-shell.exe"],
+        ["chrome-headless-shell-win64", "chrome-headless-shell.exe"],
+      ] as const;
+      const binaries = candidates.map(([directory, executable]) =>
+        join(PUPPETEER_CACHE, version, directory, executable),
+      );
+      const expectedBinary = join(PUPPETEER_CACHE, version, expectedDirectory, expectedExecutable);
+      installFsMocks({
+        existing: new Set([PUPPETEER_CACHE, ...binaries]),
+        dirs: { [PUPPETEER_CACHE]: [version] },
+      });
+      installPuppeteerBrowsersMock();
+
+      const { findBrowser } = await import("./manager.js");
+      const result = await findBrowser();
+
+      expect(result).toEqual({ executablePath: expectedBinary, source: "cache" });
+    },
+  );
+
+  it.each([
+    { hostPlatform: "linux", hostArch: "arm64" },
+    { hostPlatform: "win32", hostArch: "arm64" },
+  ])(
+    "does not select a foreign cached shell on unsupported $hostPlatform/$hostArch",
+    async ({ hostPlatform, hostArch }) => {
+      Object.defineProperty(process, "platform", { value: hostPlatform, configurable: true });
+      Object.defineProperty(process, "arch", { value: hostArch, configurable: true });
+      const version = "host-148.0.7778.97";
+      const binaries = [
+        join(PUPPETEER_CACHE, version, "chrome-headless-shell-linux64", "chrome-headless-shell"),
+        join(PUPPETEER_CACHE, version, "chrome-headless-shell-win64", "chrome-headless-shell.exe"),
+      ];
+      installFsMocks({
+        existing: new Set([PUPPETEER_CACHE, ...binaries]),
+        dirs: { [PUPPETEER_CACHE]: [version] },
+      });
+      installPuppeteerBrowsersMock();
+
+      const { findBrowser } = await import("./manager.js");
+      await expect(findBrowser()).resolves.toBeUndefined();
+    },
+  );
+
   it("prefers the puppeteer cache over the hyperframes cache when BOTH are populated", async () => {
     // The HF cache is pinned to `CHROME_VERSION` (131-era) which lags upstream
     // by many releases. The engine's `resolveHeadlessShellPath` scans the

packages/cli/src/browser/manager.ts

@@ -282,7 +282,7 @@ function findFromEnv(): BrowserResult | undefined {
  */
 async function findFromHyperframesCache(): Promise<CacheLookupResult> {
   if (!existsSync(CACHE_DIR)) return {};
-  const { Browser, getInstalledBrowsers } = await loadPuppeteerBrowsers();
+  const { Browser, detectBrowserPlatform, getInstalledBrowsers } = await loadPuppeteerBrowsers();
   // A corrupt cache (stub file where a browser dir is expected, malformed
   // metadata) makes getInstalledBrowsers throw. Treat that as "no cached
   // browser" so resolution falls through to system/download instead of
@@ -302,9 +302,14 @@ async function findFromHyperframesCache(): Promise<CacheLookupResult> {
   // an older hyperframes version (this pin has moved 131 → 151 → 152 across
   // releases) must NOT satisfy resolution, or an upgrade silently keeps
   // running whatever build happened to be cached instead of ever fetching
-  // the version this release actually needs (HF#2060 review).
+  // the version this release actually needs (HF#2060 review). Match platform
+  // as well so a shared/migrated cache cannot return a foreign executable.
+  const hostPlatform = detectBrowserPlatform();
   const match = installed.find(
-    (b) => b.browser === Browser.CHROMEHEADLESSSHELL && b.buildId === CHROME_VERSION,
+    (b) =>
+      b.browser === Browser.CHROMEHEADLESSSHELL &&
+      b.buildId === CHROME_VERSION &&
+      b.platform === hostPlatform,
   );
   if (match && existsSync(match.executablePath)) {
     return { result: { executablePath: match.executablePath, source: "cache" } };
@@ -383,8 +388,33 @@ function compareVersionDirsDescending(a: string, b: string): number {
   return 0;
 }
 
+const CACHED_HEADLESS_SHELL_EXECUTABLES: Readonly<
+  Record<string, readonly [directory: string, executable: string]>
+> = {
+  "darwin/arm64": ["chrome-headless-shell-mac-arm64", "chrome-headless-shell"],
+  "darwin/x64": ["chrome-headless-shell-mac-x64", "chrome-headless-shell"],
+  "linux/x64": ["chrome-headless-shell-linux64", "chrome-headless-shell"],
+  "win32/ia32": ["chrome-headless-shell-win32", "chrome-headless-shell.exe"],
+  "win32/x64": ["chrome-headless-shell-win64", "chrome-headless-shell.exe"],
+};
+
+function cachedHeadlessShellExecutable(
+  hostPlatform = process.platform,
+  hostArch = process.arch,
+): readonly [directory: string, executable: string] | undefined {
+  // Chrome for Testing cache entries are host-specific. Resolve exactly one
+  // platform/architecture directory so a foreign binary cannot win by probe order.
+  // Chrome for Testing does not publish Linux ARM64 binaries. Windows ARM64 can
+  // emulate x64 only on supported Windows 11 builds, which this platform/arch-only
+  // resolver cannot prove, so both hosts deliberately fall through to system
+  // browser discovery instead of attempting a potentially foreign cached binary.
+  return CACHED_HEADLESS_SHELL_EXECUTABLES[`${hostPlatform}/${hostArch}`];
+}
+
 function findFromPuppeteerCache(): BrowserResult | undefined {
   if (!existsSync(PUPPETEER_CACHE_DIR)) return undefined;
+  const executable = cachedHeadlessShellExecutable();
+  if (!executable) return undefined;
   let versions: string[];
   try {
     // Numeric semver-style sort, newest first. Lexicographic `.sort().reverse()`
@@ -399,26 +429,9 @@ function findFromPuppeteerCache(): BrowserResult | undefined {
     // Same shape as `resolveHeadlessShellPath` in engine/browserManager.ts —
     // keep them aligned. If puppeteer ever changes the on-disk layout the two
     // need to move together.
-    const candidates = [
-      join(PUPPETEER_CACHE_DIR, version, "chrome-headless-shell-linux64", "chrome-headless-shell"),
-      join(
-        PUPPETEER_CACHE_DIR,
-        version,
-        "chrome-headless-shell-mac-arm64",
-        "chrome-headless-shell",
-      ),
-      join(PUPPETEER_CACHE_DIR, version, "chrome-headless-shell-mac-x64", "chrome-headless-shell"),
-      join(
-        PUPPETEER_CACHE_DIR,
-        version,
-        "chrome-headless-shell-win64",
-        "chrome-headless-shell.exe",
-      ),
-    ];
-    for (const binary of candidates) {
-      if (existsSync(binary)) {
-        return { executablePath: binary, source: "cache" };
-      }
+    const binary = join(PUPPETEER_CACHE_DIR, version, ...executable);
+    if (existsSync(binary)) {
+      return { executablePath: binary, source: "cache" };
     }
   }
   return undefined;

packages/cli/src/capture/captureCompositionFrame.ts

@@ -61,6 +61,9 @@ export interface SettledCompositionPage {
 }
 
 export interface OpenSettledCompositionPageOptions {
+  // Separate from the post-navigation render-ready budget. Diagnostic callers
+  // without their own navigation knob keep the historical 10-second minimum.
+  navigationTimeoutMs?: number;
   renderReadyTimeoutMs: number;
   renderReadyWarningSuffix: string;
   // Screenshot paths take the engine's software-GPU default; validate/check
@@ -182,7 +185,7 @@ export async function openSettledCompositionPage(
     await options.beforeNavigate?.(page);
     await page.goto(url, {
       waitUntil: "domcontentloaded",
-      timeout: resolveDiagnosticNavigationTimeoutMs(),
+      timeout: resolveDiagnosticNavigationTimeoutMs(process.env, options.navigationTimeoutMs),
     });
     const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
     return { browser: chromeBrowser, page, renderReadyTimedOut };

packages/cli/src/commands/check.ts

@@ -86,7 +86,8 @@ export function createCheckCommand(
       },
       timeout: {
         type: "string",
-        description: "Ms to wait for scripts and media to settle initially (default: 3000)",
+        description:
+          "Initial render-ready timeout in ms; also sets the navigation minimum (10s floor, default: 3000)",
         default: "3000",
       },
       contrast: {

packages/cli/src/utils/checkBrowser.test.ts

@@ -155,6 +155,28 @@ it("carries raw browser geometry through the page driver and pipeline", async ()
   expect(mocks.serverClose).toHaveBeenCalledOnce();
 });
 
+it("uses check --timeout for both navigation and render-ready settling", async () => {
+  mountCanvasFixture();
+  const page = fakePage();
+  installSessionMock(page);
+
+  await runBrowserCheck(
+    PROJECT,
+    { ...DEFAULT_CHECK_OPTIONS, samples: 1, contrast: false, timeout: 30_000 },
+    { kind: "none" },
+    runAuditGrid,
+  );
+
+  expect(openSettledCompositionPage).toHaveBeenCalledWith(
+    "<html></html>",
+    "http://127.0.0.1:3000",
+    expect.objectContaining({
+      navigationTimeoutMs: 30_000,
+      renderReadyTimeoutMs: 30_000,
+    }),
+  );
+});
+
 it("round-trips the browser script's raw contrast candidates back into finish", async () => {
   // The U2 regression class: Node parses prepare's candidates for reporting,
   // but must hand the UNTOUCHED objects back to __contrastAuditFinish — the

packages/cli/src/utils/checkBrowser.ts

@@ -165,6 +165,7 @@ export async function runBrowserCheck(
   try {
     const launchSettleStart = Date.now();
     const session = await openSettledCompositionPage(html, server.url, {
+      navigationTimeoutMs: options.timeout,
       renderReadyTimeoutMs: options.timeout,
       renderReadyWarningSuffix: "checking the current page state",
       browserGpuMode: resolveCliChromeGpuMode(),
@@ -225,6 +226,7 @@ export async function captureFindingCrops(
   const written: string[] = [];
   try {
     const session = await openSettledCompositionPage(html, server.url, {
+      navigationTimeoutMs: options.timeout,
       renderReadyTimeoutMs: options.timeout,
       renderReadyWarningSuffix: "capturing finding crops",
       browserGpuMode: resolveCliChromeGpuMode(),

packages/cli/src/utils/renderArgs.test.ts

@@ -118,6 +118,23 @@ describe("resolveDiagnosticNavigationTimeoutMs", () => {
       resolveDiagnosticNavigationTimeoutMs({ PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS: "invalid" }),
     ).toBe(10_000);
   });
+
+  it("raises the diagnostic navigation budget to a larger caller-provided minimum", () => {
+    expect(resolveDiagnosticNavigationTimeoutMs({}, 30_000)).toBe(30_000);
+  });
+
+  it("does not let a caller-provided minimum shorten the default budget", () => {
+    expect(resolveDiagnosticNavigationTimeoutMs({}, 3_000)).toBe(10_000);
+  });
+
+  it("does not let a caller-provided minimum shorten the environment override", () => {
+    expect(
+      resolveDiagnosticNavigationTimeoutMs(
+        { PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS: "90000" },
+        30_000,
+      ),
+    ).toBe(90_000);
+  });
 });
 
 describe("parseCompositionEntryArg", () => {

packages/cli/src/utils/renderArgs.ts

@@ -118,12 +118,20 @@ export function resolveBrowserTimeoutMsArg(raw: string | undefined): number | un
   return result.value;
 }
 
-/** Navigation budget shared by snapshot/check/inspect browser diagnostics. */
+/**
+ * Navigation budget shared by snapshot/check/inspect browser diagnostics.
+ *
+ * The environment variable remains the historical global override. Callers
+ * with their own timeout knob can supply a minimum without shortening that
+ * override or the existing 10-second default.
+ */
 export function resolveDiagnosticNavigationTimeoutMs(
   env: Record<string, string | undefined> = process.env,
+  minimumTimeoutMs = 0,
 ): number {
   const parsed = Number(env.PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 10_000;
+  const configured = Number.isFinite(parsed) && parsed > 0 ? parsed : 10_000;
+  return Math.max(configured, minimumTimeoutMs);
 }
 
 // ── --composition ──────────────────────────────────────────────────────