@ultimat3/testing 24.0.0 → 25.1.0

package/src/cdp-launch-reap.ts

@@ -0,0 +1,68 @@
+// One responsibility: nothing of a launched browser outlives its close — on POSIX its process GROUP,
+// on Windows its process TREE — and the close waits until that is so, bounded.
+
+/** How long a closed Chrome gets to exit on SIGTERM before it is killed outright. */
+export const CLOSE_GRACE_MS = 5_000;
+
+const GROUP_POLL_MS = 10;
+
+/** Runs a command to its exit; the seam the Windows branch is asserted through on any runner. */
+export type RunCommand = (argv: readonly string[]) => Promise<number>;
+
+const runQuiet: RunCommand = (argv) =>
+  // Bounded: taskkill ends a tree in well under a second; a stuck one must not stall `close()`.
+  Bun.spawn([...argv], { stdio: ['ignore', 'ignore', 'ignore'], timeout: 10_000 }).exited;
+
+/**
+ * `/T` takes every process the browser started — renderer, GPU, network, crashpad — and `/F` does
+ * not ask: a tree kill is the last step of a close, after the graceful one had its chance.
+ */
+export const taskkillArgv = (pid: number): readonly string[] => [
+  'taskkill',
+  '/T',
+  '/F',
+  '/PID',
+  String(pid),
+];
+
+const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
+  Promise.race([work, Bun.sleep(ms)]);
+
+/**
+ * Kill whatever is left of the browser's process group and wait until the group is EMPTY — the
+ * condition, asked of the kernel, not a pause: signal 0 to a group with no member throws. Bounded
+ * by `CLOSE_GRACE_MS` for a container whose init never reaps a zombie — on the monotonic clock,
+ * not a count of sleeps: a loaded runner oversleeps every 10 ms, and the close's designed bound
+ * (`LAUNCHED_CLOSE_MS`) is what a hook deadline is derived from.
+ */
+async function reapGroup(pgid: number): Promise<void> {
+  const until = performance.now() + CLOSE_GRACE_MS;
+  try {
+    process.kill(-pgid, 'SIGKILL');
+    while (performance.now() < until) {
+      await Bun.sleep(GROUP_POLL_MS);
+      process.kill(-pgid, 0);
+    }
+  } catch {
+    // ESRCH: nothing is left in the group, which is the answer being waited for.
+  }
+}
+
+/**
+ * Everything the browser `pid` started, gone. On Windows `process.kill(-pgid)` is no call at all —
+ * there is no process group, and the browser's children hold the profile's files open — so the
+ * tree is walked by `taskkill`, which must run while the browser is still ALIVE: its children are
+ * found by parent pid, and a dead parent's children are nobody's.
+ */
+export async function killTree(
+  pid: number,
+  platform: string = process.platform,
+  run: RunCommand = runQuiet,
+): Promise<void> {
+  if (platform !== 'win32') return reapGroup(pid);
+  try {
+    await within(CLOSE_GRACE_MS, run(taskkillArgv(pid)));
+  } catch {
+    // No taskkill, or a tree already gone (exit 128): litter at worst, never the close's verdict.
+  }
+}

package/src/cdp-launch-wire.ts

@@ -0,0 +1,171 @@
+// One responsibility: the WIRE a launched Chrome is driven over, per platform — its debugging pipe
+// (fds 3 and 4) where the parent can hold those fds, else a loopback port the browser picks and
+// announces in its profile's `DevToolsActivePort`. Spawning and reaping are `cdp-launch-attempt.ts`.
+
+// why: Bun exposes no path-join primitive; the announcement file lives in the profile directory.
+import { join } from 'node:path';
+import { renderThrowable, stringField } from '@ultimat3/core';
+import type { CdpConnection } from './cdp-connection';
+import { cdpConnect, cdpConnectOver } from './cdp-connection';
+import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+import { pipeTransport } from './cdp-pipe';
+
+/**
+ * `pipe` everywhere Bun hands the parent the child's extra fds as descriptors, which is POSIX: no
+ * port, so two suites on one machine never collide and nothing else can drive the browser.
+ * `port` on Windows, where those fds are not descriptors `Bun.file` can open: Chrome binds a
+ * loopback port of its own choosing (`=0`, so never a collision either) and writes it down.
+ */
+export type CdpWire = 'pipe' | 'port';
+
+export const defaultWire = (platform: string): CdpWire => (platform === 'win32' ? 'port' : 'pipe');
+
+/** The one flag that differs between the two wires. */
+export const wireFlag = (wire: CdpWire): string =>
+  wire === 'pipe' ? '--remote-debugging-pipe' : '--remote-debugging-port=0';
+
+/** Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies — pipe wire only. */
+const PIPE_STDIO = ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] as const;
+const PORT_STDIO = ['ignore', 'ignore', 'pipe'] as const;
+export const wireStdio = (wire: CdpWire): typeof PIPE_STDIO | typeof PORT_STDIO =>
+  wire === 'pipe' ? PIPE_STDIO : PORT_STDIO;
+
+/** The pipe wire over a spawned child's fds 3 and 4. Answers nothing until the first `send`. */
+export function pipeConnection(stdio: unknown, timeoutMs: number): CdpConnection {
+  const [, , , toBrowser, fromBrowser] = stdio as readonly number[];
+  const sink = Bun.file(toBrowser ?? -1).writer();
+  return cdpConnectOver(
+    pipeTransport({
+      write: (bytes) => {
+        sink.write(bytes);
+        void sink.flush();
+      },
+      read: Bun.file(fromBrowser ?? -1).stream(),
+      end: () => {
+        void Promise.resolve(sink.end()).catch(() => undefined);
+      },
+    }),
+    timeoutMs,
+  );
+}
+
+export const DEVTOOLS_ACTIVE_PORT = 'DevToolsActivePort';
+
+/**
+ * `<port>\n/devtools/browser/<id>\n` → the browser's WebSocket url, or `undefined` while the file is
+ * still half-written. Loopback by address, never `localhost`, which may resolve to `::1` first
+ * while Chrome listens on IPv4.
+ */
+export function devToolsEndpoint(text: string): string | undefined {
+  const [port, path] = text.split(/\r?\n/);
+  if (port === undefined || !/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65_535) {
+    return undefined;
+  }
+  if (path === undefined || !/^\/devtools\/browser\/[\w-]+$/.test(path)) return undefined;
+  return `ws://127.0.0.1:${port}${path}`;
+}
+
+const ANNOUNCE_POLL_MS = 25;
+
+/**
+ * Dial, inside what is left of the LAUNCH deadline — `cdpConnect`'s own deadline is the per-call one
+ * the connection keeps afterwards, so it cannot also be the launch's. A dial that loses the race
+ * and connects later is closed, never left holding a socket nobody reads.
+ */
+async function dialWithin(
+  endpoint: string,
+  leftMs: number,
+  timeoutMs: number,
+): Promise<CdpConnection> {
+  const dialing = cdpConnect({ endpoint, timeoutMs });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new CdpTimeoutError({ method: 'connect', timeoutMs: leftMs })),
+      leftMs,
+    );
+  });
+  try {
+    return await Promise.race([dialing, late]);
+  } catch (error) {
+    void dialing.then((connection) => connection.close()).catch(() => undefined);
+    // A timeout stays one — the launcher reads it as the deadline. Any other refusal names the
+    // endpoint it was for: the browser announced it, so the dial is the step that failed.
+    if (error instanceof CdpTimeoutError) throw error;
+    throw new CdpCallFailedError({
+      method: `connect ${endpoint}`,
+      detail: renderThrowable(error),
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface PortConnectionInput {
+  readonly profileDir: string;
+  /** True once the browser process has exited — it will never write the file then. */
+  readonly exited: () => boolean;
+  /** How long the browser has to announce itself AND accept the connection, from now. */
+  readonly deadlineMs: number;
+  /** Every call's deadline once connected. */
+  readonly timeoutMs: number;
+  /**
+   * How the announcement is read — `Bun.file(path).text()` unless a test hands a reader that
+   * refuses the way Windows does, which no Linux file system can be made to.
+   */
+  readonly readText?: ((path: string) => Promise<string>) | undefined;
+}
+
+/**
+ * The read errors that mean "not announced YET", never "the launch failed": `ENOENT`, the file
+ * gone between the existence check and the read, and `EBUSY`, which is how Bun reports a Windows
+ * sharing violation — Chrome writes `DevToolsActivePort` in place and holds it open without read
+ * sharing while it does. Seen on windows-latest (PR #668): "DevTools listening" on stderr, the file
+ * present, the read refused, and the launch reported `closed` with the browser alive.
+ */
+const NOT_YET = new Set(['ENOENT', 'EBUSY']);
+
+const readFile = (path: string): Promise<string> => Bun.file(path).text();
+
+/** The announcement's text, or `undefined` while its writer still holds it. */
+async function readAnnouncement(
+  path: string,
+  read: (path: string) => Promise<string>,
+): Promise<string | undefined> {
+  try {
+    return await read(path);
+  } catch (error) {
+    if (NOT_YET.has(stringField(error, 'code') ?? '')) return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The port wire: wait for the profile's `DevToolsActivePort`, then dial it. A browser that exits
+ * first is a CLOSED launch and one still silent at the deadline a TIMED-OUT one — the same two
+ * answers the pipe gives, so the launcher's failure report reads alike on either wire.
+ */
+export async function portConnection(input: PortConnectionInput): Promise<CdpConnection> {
+  const path = join(input.profileDir, DEVTOOLS_ACTIVE_PORT);
+  const began = performance.now();
+  for (;;) {
+    // A FRESH handle per look: a `BunFile` that once answered "absent" keeps answering it (measured
+    // on Bun 1.4.2 — `exists()` false and `text()` empty after the file was written).
+    const text = (await Bun.file(path).exists())
+      ? await readAnnouncement(path, input.readText ?? readFile)
+      : undefined;
+    const endpoint = text === undefined ? undefined : devToolsEndpoint(text);
+    const left = input.deadlineMs - (performance.now() - began);
+    if (endpoint !== undefined) return dialWithin(endpoint, Math.max(1, left), input.timeoutMs);
+    if (input.exited()) {
+      throw new CdpCallFailedError({
+        method: 'the launch',
+        detail: `the browser exited before it wrote ${DEVTOOLS_ACTIVE_PORT}`,
+      });
+    }
+    if (left <= 0) {
+      throw new CdpTimeoutError({ method: DEVTOOLS_ACTIVE_PORT, timeoutMs: input.deadlineMs });
+    }
+    await Bun.sleep(Math.min(ANNOUNCE_POLL_MS, left));
+  }
+}

package/src/cdp-launch.ts

@@ -6,31 +6,38 @@ import { finiteCount } from '@ultimat3/core';
 import type { CdpLaunchAttempt } from './cdp-errors';
 import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
 import type { LaunchedBrowser } from './cdp-launch-attempt';
-import { launchAttempt } from './cdp-launch-attempt';
+import { LAUNCH_REAP_MS, launchAttempt } from './cdp-launch-attempt';
+import { chromeCandidates } from './cdp-launch-candidates';
+import type { CdpWire } from './cdp-launch-wire';
+import { defaultWire, wireFlag } from './cdp-launch-wire';
 
 export type { LaunchedBrowser } from './cdp-launch-attempt';
-export { CLOSE_GRACE_MS } from './cdp-launch-attempt';
+export { CLOSE_GRACE_MS, LAUNCH_REAP_MS } from './cdp-launch-attempt';
+export { chromeCandidates } from './cdp-launch-candidates';
+export type { CdpWire } from './cdp-launch-wire';
+export { defaultWire } from './cdp-launch-wire';
 
 /**
  * Where a Chrome is, in the order worth trying. `CHROME_PATH` first because it is the operator's
- * answer and the only one that can be right on a machine none of the rest describes; the two
- * `/usr/bin` names after it are what GitHub-hosted `ubuntu-latest` ships, which is what lets the
- * browser-backed suite run in CI with **no download step and no new dependency**.
+ * answer and the only one that can be right on a machine none of the rest describes; after it, the
+ * install locations of THIS platform (`cdp-launch-candidates.ts`) — on Linux the `/usr/bin` names
+ * GitHub-hosted `ubuntu-latest` ships, which is what lets the browser-backed suite run in CI with
+ * **no download step and no new dependency**; on Windows Chrome and Edge; on macOS the app bundles.
  */
 export const CHROME_PATH_ENV = 'CHROME_PATH';
-export const CHROME_CANDIDATES: readonly string[] = [
-  '/usr/bin/google-chrome',
-  '/usr/bin/google-chrome-stable',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-];
+export const CHROME_CANDIDATES: readonly string[] = chromeCandidates(process.platform, process.env);
 
-/** The first candidate that exists, or `undefined`. An absent browser is a SKIP, never a failure. */
+/**
+ * The first candidate that exists, or `undefined`. An absent browser is a SKIP, never a failure.
+ * `platform` is a parameter so the Windows and macOS lists are asserted on a Linux runner too.
+ */
 export async function findChrome(
   env: Readonly<Record<string, string | undefined>>,
+  platform: string = process.platform,
 ): Promise<string | undefined> {
   const declared = env[CHROME_PATH_ENV];
-  const candidates = declared === undefined || declared === '' ? CHROME_CANDIDATES : [declared];
+  const candidates =
+    declared === undefined || declared === '' ? chromeCandidates(platform, env) : [declared];
   for (const candidate of candidates) {
     if (await Bun.file(candidate).exists()) return candidate;
   }
@@ -52,15 +59,19 @@ export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disa
 /**
  * The flags, and every one of them earns its line.
  *
- * `--headless=new` is Chrome's own headless rather than the retired shim. `--remote-debugging-pipe`
- * is the wire (`cdp-pipe.ts` says why it is not the WebSocket): no port, so two suites on one
- * machine can never collide, and nothing but this process can drive the browser. A throwaway
- * `--user-data-dir` because a run sharing a profile with a real browser inherits its cookies and
- * locks its files.
+ * `--headless=new` is Chrome's own headless rather than the retired shim. The wire flag is
+ * `--remote-debugging-pipe` wherever the pipe can be held (`cdp-pipe.ts` says why it is not the
+ * WebSocket): no port, so two suites on one machine can never collide, and nothing but this process
+ * can drive the browser — and `--remote-debugging-port=0` on Windows (`cdp-launch-wire.ts`). A
+ * throwaway `--user-data-dir` because a run sharing a profile with a real browser inherits its
+ * cookies and locks its files.
  */
-export const chromeLaunchFlags = (profileDir: string): readonly string[] => [
+export const chromeLaunchFlags = (
+  profileDir: string,
+  wire: CdpWire = defaultWire(process.platform),
+): readonly string[] => [
   '--headless=new',
-  '--remote-debugging-pipe',
+  wireFlag(wire),
   `--user-data-dir=${profileDir}`,
   ...CONTAINER_CHROME_ARGS,
   '--disable-gpu',
@@ -96,12 +107,22 @@ export const LAUNCH_TIMEOUT_MS = 60_000;
  */
 export const LAUNCH_ATTEMPTS = 2;
 
+/**
+ * The longest `launchChrome` is DESIGNED to take, for any `timeoutMs` up to `LAUNCH_TIMEOUT_MS`:
+ * every start given its whole deadline, each failed one its bounded reap. A hook that wraps a launch
+ * and gives it less is killed by Bun before the relaunch, and the `X_CDP_LAUNCH_FAILED` that would
+ * have named the slow step never surfaces — the shape of four CI flakes (plan 101, F1).
+ */
+export const LAUNCH_BUDGET_MS = LAUNCH_ATTEMPTS * (LAUNCH_TIMEOUT_MS + LAUNCH_REAP_MS);
+
 export interface LaunchOptions {
   readonly executable: string;
   /** Every CDP call's deadline once the browser is up. */
   readonly timeoutMs: number;
   /** The first answer's deadline, per start. Defaults to the larger of `timeoutMs` and `LAUNCH_TIMEOUT_MS`. */
   readonly launchTimeoutMs?: number | undefined;
+  /** The wire. Defaults to this platform's (`defaultWire`): the pipe, and on Windows the port. */
+  readonly wire?: CdpWire | undefined;
 }
 
 /**
@@ -117,11 +138,13 @@ export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrow
     options.launchTimeoutMs ?? Math.max(options.timeoutMs, LAUNCH_TIMEOUT_MS),
     1,
   );
+  const wire = options.wire ?? defaultWire(process.platform);
   const failures: CdpLaunchAttempt[] = [];
   while (failures.length < LAUNCH_ATTEMPTS) {
     const started = await launchAttempt({
       executable: options.executable,
-      flags: chromeLaunchFlags,
+      flags: (profileDir) => chromeLaunchFlags(profileDir, wire),
+      wire,
       timeoutMs: options.timeoutMs,
       launchTimeoutMs,
     });
@@ -140,6 +163,8 @@ export async function launchFoundChrome(
   timeoutMs: number,
 ): Promise<LaunchedBrowser> {
   const executable = await findChrome(env);
-  if (executable === undefined) throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+  if (executable === undefined) {
+    throw new CdpBrowserMissingError({ tried: chromeCandidates(process.platform, env) });
+  }
   return launchChrome({ executable, timeoutMs });
 }

package/src/define-island-states.ts

@@ -3,12 +3,14 @@
 // applies are `island-states-check.ts`. Every default a declaration leaves out is resolved HERE, so
 // nothing downstream has to decide what an absent viewport or an absent theme list meant.
 
+import { decodeRecordEnvelope, encodeRecordEnvelope, isUltimateError } from '@ultimat3/core';
 import { DEFAULT_NOW } from './determinism';
 import {
   IslandStateDuplicateError,
   IslandStateIdInvalidError,
   IslandStateInstantInvalidError,
   IslandStateJsonInvalidError,
+  IslandStateRecordsInvalidError,
   IslandStateStubInvalidError,
   IslandStatesEmptyError,
   IslandStateZoneInvalidError,
@@ -18,6 +20,7 @@ import type {
   IslandStateDecl,
   IslandStatesDecl,
   IslandStatesManifest,
+  IslandStubResponse,
   IslandTheme,
   IslandViewport,
 } from './island-states';
@@ -101,14 +104,7 @@ function normalizeState(
     if (!isStubMatch(stub.match)) {
       throw new IslandStateStubInvalidError({ island: decl.island, match: stub.match });
     }
-    if (stub.respond.kind !== 'json') continue;
-    const bodyFault = jsonFault(
-      stub.respond.body,
-      `state "${state.id}" routes[${index}].respond.body`,
-    );
-    if (bodyFault !== undefined) {
-      throw new IslandStateJsonInvalidError({ island: decl.island, ...bodyFault });
-    }
+    checkStubBody(decl.island, stub.respond, `state "${state.id}" routes[${index}].respond`);
   }
 
   return {
@@ -122,6 +118,49 @@ function normalizeState(
   };
 }
 
+type RecordsStub = Extract<IslandStubResponse, { kind: 'records' }>;
+
+/**
+ * The envelope the harness will send, through core's own pair: `encodeRecordEnvelope` builds it
+ * (as `island-harness-script.ts` does) and `decodeRecordEnvelope` is the client's own reader, so a
+ * stub is held to exactly what the page store will accept — never to a copy of that rule.
+ */
+function envelopeFault(respond: RecordsStub): string | undefined {
+  try {
+    decodeRecordEnvelope(encodeRecordEnvelope(respond.data, respond.records, respond.removed));
+    return undefined;
+  } catch (error) {
+    if (!isUltimateError(error)) throw error;
+    return error.cause;
+  }
+}
+
+/** A stub's answer survives the JSON trip, and a `records` one is an envelope the store adopts. */
+function checkStubBody(island: string, respond: IslandStubResponse, path: string): void {
+  if (respond.kind !== 'json' && respond.kind !== 'records') return;
+  const parts: readonly (readonly [string, unknown])[] =
+    respond.kind === 'json'
+      ? [['body', respond.body]]
+      : [
+          ['data', respond.data],
+          ['records', respond.records],
+          ['removed', respond.removed ?? null],
+        ];
+  for (const [member, value] of parts) {
+    const fault = jsonFault(value, `${path}.${member}`);
+    if (fault !== undefined) throw new IslandStateJsonInvalidError({ island, ...fault });
+  }
+  if (respond.kind !== 'records') return;
+  const fault = envelopeFault(respond);
+  if (fault !== undefined) {
+    throw new IslandStateRecordsInvalidError({
+      island,
+      path,
+      reason: `is not a records envelope (${fault})`,
+    });
+  }
+}
+
 /**
  * Declare the states one island can be photographed in. Validated here rather than by the command
  * that takes the pictures, because a manifest that is only checked at capture time is a manifest

package/src/determinism.ts

@@ -191,10 +191,10 @@ export function setFrozenClock(now: string | number): void {
 }
 
 /** Run `body` with the clock frozen at `now`, then restore whatever was there before. */
-export async function frozenClock<T>(now: string, body: () => T | Promise<T>): Promise<T> {
+export async function withFrozenClock<T>(now: string, body: () => T | Promise<T>): Promise<T> {
   // Resolved before `previous` is spent: a refusal here must not run the body and must not leave
   // the outer instant behind a `finally` that restores something already overwritten.
-  const at = instantMs('frozenClock', now);
+  const at = instantMs('withFrozenClock', now);
   const previous = frozenAt;
   frozenAt = at;
   // Both moves announced, as `setFrozenClock` announces one: the frozen scheduler renews leases on

package/src/e2e-app.ts

@@ -11,10 +11,11 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
 import type { E2eAppMode } from './e2e-spawn';
-import { inherited, refuse, spawnE2eApp, xBin } from './e2e-spawn';
+import { E2E_APP_STOP_MS, inherited, READY_PROBE_MS, refuse, spawnE2eApp, xBin } from './e2e-spawn';
 import { testSealKeyEnv } from './test-seal-key';
 
 export type { E2eAppMode } from './e2e-spawn';
+export { E2E_APP_STOP_MS } from './e2e-spawn';
 
 export interface StartE2eAppOptions {
   /** The app root — the directory holding `app.config.ts`. */
@@ -52,6 +53,18 @@ export interface E2eApp {
 
 const DEFAULT_READY_TIMEOUT_MS = 90_000;
 
+/** Sequential steps `startE2eApp` bounds at `DEFAULT_READY_TIMEOUT_MS`: `x db reset`, `x db seed`, `/readyz`. */
+const START_PHASES = 3;
+
+/**
+ * The longest `startE2eApp()` is DESIGNED to take, at its default deadline: the reset, the seed and
+ * the readiness wait each given the whole of it, the one probe that may straddle the end, and the
+ * bounded stop of an app that never got ready. THE deadline a hook that boots an e2e app derives
+ * from — with `E2E_BROWSER_OPEN_MS` beside it when the same hook opens a browser.
+ */
+export const E2E_APP_START_MS =
+  START_PHASES * DEFAULT_READY_TIMEOUT_MS + READY_PROBE_MS + E2E_APP_STOP_MS;
+
 function x(bin: string, args: readonly string[], root: string, env: Record<string, string>): void {
   const run = Bun.spawnSync(['bun', bin, ...args], {
     cwd: root,

package/src/e2e-errors.ts

@@ -95,11 +95,22 @@ export class E2eLocatorAmbiguousError extends UltimateError {
  * test that hangs, and CI then reports a runner timeout with no assertion anywhere in it.
  */
 export class E2eServiceWorkerAbsentError extends UltimateError {
-  constructor(input: { readonly url: string; readonly timeoutMs: number }) {
+  constructor(input: {
+    readonly url: string;
+    readonly timeoutMs: number;
+    /**
+     * True when a worker was ACTIVE and the page was reloaded once for it to answer — a first
+     * page `clients.claim()` missed (#678) — and the reload was not controlled either.
+     */
+    readonly reloaded?: boolean | undefined;
+  }) {
     super({
       code: 'X_E2E_SERVICE_WORKER_ABSENT',
-      cause: `no service worker took control of ${renderCauseValue(input.url)} within ${String(input.timeoutMs)}ms`,
-      fix: `x build --target static — the worker is generated by the pwa build; then confirm the route at ${renderFixLiteral(input.url, URL_PLACEHOLDER)} registers it`,
+      cause:
+        input.reloaded === true
+          ? `a service worker is active for ${renderCauseValue(input.url)} but did not control it, even reloaded once, within ${String(input.timeoutMs)}ms`
+          : `no service worker took control of ${renderCauseValue(input.url)} within ${String(input.timeoutMs)}ms`,
+      fix: `x build --target static — the worker is generated by the pwa build; then confirm the route at ${renderFixLiteral(input.url, URL_PLACEHOLDER)} registers it, or raise this call's budget: await page.waitForServiceWorker({ timeoutMs: 30_000 })`,
     });
   }
 }

package/src/e2e-locale.ts

@@ -1,30 +1,21 @@
-// The locale an e2e run's browser asks for: the app's own `defaultLocale`, read off `app.config.ts`
-// the way the CLI reads its other boot facts. `@ultimat3/testing` sits below `@ultimat3/cli`, so the
-// file name and the export name are restated here rather than imported from it.
-
-import { join } from 'node:path'; // why: Bun ships no path join.
-
-/** The app root's config module and the export holding the config — `x new` writes both. */
-const APP_CONFIG_FILE = 'app.config.ts';
-const APP_CONFIG_EXPORT = 'config';
+// The locale an e2e run's browser asks for: the default the app's `defineCatalogs()` declared —
+// the one place an app names its locales since 25.0.0 (`app.config.ts`'s `defaultLocale` and
+// `locales` keys were deleted). Read through `@ultimat3/i18n/app-catalogs`, the one reader the CLI
+// shares; what is this file's own is the answer to a module that will not load.
 
 /**
- * The app's `defaultLocale`, or `undefined` when it cannot be read — and then nothing is pinned.
- * Never a guessed `en`: pinning the wrong language would make every run photograph and assert on a
- * page no visitor at the unprefixed URL sees, which is worse than the runner's own Chrome locale.
- * The import runs the config module, which may validate an environment this process lacks.
+ * The app's default locale, or `undefined` when it cannot be read — and then nothing is pinned.
+ * Never a guessed `en`: `loadAppCatalogs` answers only when a `defineCatalogs()` was declared.
+ * Pinning the wrong language would make every run photograph and assert on a page no visitor at
+ * the unprefixed URL sees. The import runs the app's module, which may validate an environment
+ * this process lacks — so a module that throws is "nothing pinned", never a failed run.
  */
 export async function e2eDefaultLocale(root: string): Promise<string | undefined> {
-  const path = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(path).exists())) return undefined;
-  let module: Record<string, unknown>;
+  // Dynamic, like every non-core dependency of this package: only the e2e preload pays for it.
+  const { loadAppCatalogs } = await import('@ultimat3/i18n/app-catalogs');
   try {
-    module = (await import(path)) as Record<string, unknown>;
+    return (await loadAppCatalogs(root))?.defaultLocale;
   } catch {
     return undefined;
   }
-  const config = Object.hasOwn(module, APP_CONFIG_EXPORT) ? module[APP_CONFIG_EXPORT] : undefined;
-  if (typeof config !== 'object' || config === null) return undefined;
-  const locale = (config as Record<string, unknown>)['defaultLocale'];
-  return typeof locale === 'string' && locale !== '' ? locale : undefined;
 }

package/src/e2e-page.ts

@@ -3,10 +3,10 @@
 // may import the other — so the join is here, in the one package allowed to know about both.
 
 import { finiteCount } from '@ultimat3/core';
-import { E2eServiceWorkerAbsentError } from './e2e-errors';
 import { evaluateClosure } from './e2e-evaluate';
 import { e2eLocator } from './e2e-locator';
 import type { E2eSelection } from './e2e-selection';
+import { callBudget, waitForServiceWorker } from './e2e-service-worker';
 import type { LocatorLike, PageLike } from './test-types';
 
 /**
@@ -39,7 +39,10 @@ export interface E2ePageOptions {
   readonly baseUrl: string;
   /** Per-navigation deadline, handed to the driver rather than enforced here. */
   readonly timeoutMs?: number | undefined;
-  /** How long `waitForServiceWorker()` waits before refusing. Bounded IN THE PAGE. */
+  /**
+   * How long `waitForServiceWorker()` waits before refusing, the handover reload included. Bounded
+   * IN THE PAGE. One test raises its own with `waitForServiceWorker({ timeoutMs })`.
+   */
   readonly serviceWorkerTimeoutMs?: number | undefined;
 }
 
@@ -77,24 +80,6 @@ const firstFlushExpression = (url: string): string =>
       .then((chunk) => { reader.cancel().catch(() => {}); return chunk; }); })
     .then((chunk) => JSON.stringify({ html: new TextDecoder().decode(chunk.value || new Uint8Array()) })))()`;
 
-/**
- * `ready` alone is not control: a first load activates a worker that is not yet the page's
- * controller, and an offline assertion made in that window tests nothing. So this waits for
- * `controllerchange` too — an EVENT, not a poll, so the harness still has exactly one retry loop.
- */
-const serviceWorkerExpression = (timeoutMs: number): string =>
-  `(() => {
-  if (!navigator.serviceWorker) return JSON.stringify({ controlled: false });
-  const controlled = new Promise((resolve) => {
-    if (navigator.serviceWorker.controller) { resolve(true); return; }
-    navigator.serviceWorker.addEventListener('controllerchange', () => resolve(true), { once: true });
-  });
-  const deadline = new Promise((resolve) => setTimeout(() => resolve(false), ${String(timeoutMs)}));
-  return Promise.race([navigator.serviceWorker.ready.then(() => controlled), deadline])
-    .catch(() => false)
-    .then((ok) => JSON.stringify({ controlled: ok === true }));
-})()`;
-
 /**
  * The adapter. Every member re-reads the live page: a `PageLike` handed to a test outlives every
  * navigation the test makes, so nothing here may capture a URL, a document or an element.
@@ -132,12 +117,13 @@ export function e2ePage(options: E2ePageOptions): PageLike {
       const html = readField(await page.evaluate(firstFlushExpression(target)), 'html');
       return { html: typeof html === 'string' ? html : '' };
     },
-    waitForServiceWorker: async () => {
-      const raw = await page.evaluate(serviceWorkerExpression(swTimeout));
-      if (readField(raw, 'controlled') !== true) {
-        throw new E2eServiceWorkerAbsentError({ url: page.url(), timeoutMs: swTimeout });
-      }
-    },
+    // The handover is `e2e-service-worker.ts`'s: an unclaimed first page is reloaded once (#678).
+    waitForServiceWorker: async (waitOptions) =>
+      waitForServiceWorker({
+        page,
+        timeoutMs: callBudget(swTimeout, waitOptions?.timeoutMs),
+        navigationTimeoutMs: timeout,
+      }),
     evaluate: <T>(fn: () => T): Promise<T> => evaluateClosure(page, fn) as unknown as Promise<T>,
     locator: (selector) => locate({ kind: 'css', selector, first: false }),
     getByRole: (role, roleOptions) =>