@ultimat3/testing 23.0.0 → 25.0.0

package/src/cdp-launch.ts

@@ -1,38 +1,43 @@
-// One responsibility: start a Chrome in this container and hand back its DevTools endpoint and the
-// way to stop it. The connection is `cdp-connection.ts` and the page surface `cdp-e2e-page.ts`.
+// One responsibility: WHICH Chrome, with which flags, and how many starts it gets — the candidate
+// list, the launch deadline and the one relaunch. One start of the process is
+// `cdp-launch-attempt.ts`; the connection is `cdp-connection.ts`, the page `cdp-e2e-page.ts`.
 
-// why: Bun exposes no recursive-remove and no temp-root primitive, so the throwaway profile
-// directory this launcher must create and delete needs both.
-import { mkdtempSync, rmSync } from 'node:fs';
-// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
-import { tmpdir } from 'node:os';
-// why: Bun exposes no path-join primitive.
-import { join } from 'node:path';
-import type { CdpConnection } from './cdp-connection';
-import { cdpConnectOver } from './cdp-connection';
+import { finiteCount } from '@ultimat3/core';
+import type { CdpLaunchAttempt } from './cdp-errors';
 import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
-import { pipeTransport } from './cdp-pipe';
+import type { LaunchedBrowser } 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, 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;
   }
@@ -54,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',
@@ -81,130 +90,71 @@ export const chromeLaunchFlags = (profileDir: string): readonly string[] => [
   'about:blank',
 ];
 
-export interface LaunchedBrowser {
-  /** The browser's own CDP connection, over its debugging pipe. Already answering. */
-  readonly connection: CdpConnection;
-  /** Idempotent: closes the connection, kills the process, deletes the profile. */
-  close(): void;
-  /**
-   * `close()`, then resolves once the process has EXITED — SIGTERM, then SIGKILL after
-   * `CLOSE_GRACE_MS`, never waiting longer than twice that. What a suite's `afterAll` awaits: a
-   * Chrome told to die but still shutting down competes with the next suite's launch on a 4-CPU
-   * runner, and one still running keeps the test process from exiting at all. Optional so a test
-   * double of a launch need not model a process; `launchChrome` always provides it.
-   */
-  closed?(): Promise<void>;
-}
-
-export interface LaunchOptions {
-  readonly executable: string;
-  /** How long Chrome has to answer its first call, and every call's deadline after that. */
-  readonly timeoutMs: number;
-}
-
-const STDERR_TAIL_CHARS = 4_000;
-
 /**
- * Read stderr to its end for the life of the process, keeping only a bounded tail. A pipe nobody
- * reads fills, and Chrome's next stderr write then blocks the thread making it — a browser that
- * stops answering mid-run for a reason no log shows. The tail is the launch-failure diagnostics:
- * a missing library, a sandbox refusal and a bad flag are all named there and nowhere else.
+ * How long a COLD start may take before the browser is given up on. Its own number, never the
+ * per-call deadline: measured 2026-10-02 over `scaffold-smoke` on free `ubuntu-latest` runners, the
+ * first launch of a job cost 5-19 s more than a warm one in 11 green jobs, and the one red job was
+ * still printing start-up lines when a 30 s deadline killed it. Twice that, and finite: a browser
+ * that exits says so at once (its pipe closes), so only one alive and silent waits this long.
  */
-function stderrTail(stream: ReadableStream<Uint8Array>): {
-  readonly text: () => string;
-  /** Settles once the stream has ended — every byte the process wrote has been read. */
-  readonly drained: Promise<void>;
-} {
-  let text = '';
-  const drained = (async () => {
-    const decoder = new TextDecoder();
-    for await (const chunk of stream) {
-      text = (text + decoder.decode(chunk, { stream: true })).slice(-STDERR_TAIL_CHARS);
-    }
-  })().catch(() => undefined);
-  return { text: () => text, drained };
-}
+export const LAUNCH_TIMEOUT_MS = 60_000;
 
 /**
- * How long a browser that failed its first call gets to finish dying, and its stderr to finish
- * draining, before the tail is read. The pipe ending and the stderr reader reaching the last line
- * are two unordered events; read at the first, the reason a browser died was reported as "printed
- * nothing". Bounded, because a WEDGED browser neither exits nor closes stderr.
+ * Starts per launch: the first, and ONE more on a fresh profile after the first was reaped. A
+ * process start is the one step here whose failure can belong to the machine rather than the
+ * binary — and the second start of a cold binary is a warm one. Never a loop: two starts that both
+ * went unanswered are `X_CDP_LAUNCH_FAILED` carrying both.
  */
-const FAILURE_DRAIN_MS = 1_000;
+export const LAUNCH_ATTEMPTS = 2;
 
-/** How long a closed Chrome gets to exit on SIGTERM before it is killed outright. */
-export const CLOSE_GRACE_MS = 5_000;
+/**
+ * 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);
 
-const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
-  Promise.race([work, Bun.sleep(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;
+}
 
 /**
- * Start Chrome on a throwaway profile and answer once it has answered one CDP call. With a pipe
- * there is no "DevTools listening" line to wait for — the first reply IS the readiness signal, and
- * a browser that dies or stays silent before it is `X_CDP_LAUNCH_FAILED` carrying its own stderr.
+ * Start Chrome on a throwaway profile and answer once it has answered one CDP call. A browser that
+ * dies or stays silent is started once more; twice is `X_CDP_LAUNCH_FAILED` with each start's own
+ * stderr and whether it exited or was killed at the deadline.
  */
 export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrowser> {
-  const profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
-  const child = Bun.spawn([options.executable, ...chromeLaunchFlags(profileDir)], {
-    // Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies and events.
-    stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
-  });
-  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
-  const [, , , toBrowser, fromBrowser] = child.stdio as unknown as readonly number[];
-  const sink = Bun.file(toBrowser ?? -1).writer();
-  const connection = cdpConnectOver(
-    pipeTransport({
-      write: (bytes) => {
-        sink.write(bytes);
-        void sink.flush();
-      },
-      read: Bun.file(fromBrowser ?? -1).stream(),
-      end: () => {
-        void Promise.resolve(sink.end()).catch(() => undefined);
-      },
-    }),
-    options.timeoutMs,
+  // Screened: `setTimeout(fn, NaN)` fires in 1 ms, which reports a healthy browser as silent.
+  const launchTimeoutMs = finiteCount(
+    'launchChrome',
+    'launchTimeoutMs',
+    options.launchTimeoutMs ?? Math.max(options.timeoutMs, LAUNCH_TIMEOUT_MS),
+    1,
   );
-  let closed = false;
-  const close = (): void => {
-    if (closed) return;
-    closed = true;
-    connection.close();
-    child.kill();
-    rmSync(profileDir, { recursive: true, force: true });
-  };
-  let exiting: Promise<void> | undefined;
-  const closeAndWait = (): Promise<void> => {
-    close();
-    exiting ??= (async () => {
-      const exited =
-        (await within(
-          CLOSE_GRACE_MS,
-          child.exited.then(() => true),
-        )) === true;
-      if (exited) return;
-      child.kill('SIGKILL');
-      await within(CLOSE_GRACE_MS, child.exited);
-    })();
-    return exiting;
-  };
-  try {
-    await connection.send('Browser.getVersion');
-    return { connection, close, closed: closeAndWait };
-  } catch {
-    await within(FAILURE_DRAIN_MS, child.exited);
-    close();
-    await within(FAILURE_DRAIN_MS, tail.drained);
-    const seen = tail.text().trim();
-    throw new CdpLaunchFailedError({
+  const wire = options.wire ?? defaultWire(process.platform);
+  const failures: CdpLaunchAttempt[] = [];
+  while (failures.length < LAUNCH_ATTEMPTS) {
+    const started = await launchAttempt({
       executable: options.executable,
-      detail:
-        seen === ''
-          ? 'it answered no DevTools call and printed nothing before the deadline'
-          : seen.split('\n').slice(-3).join(' | '),
+      flags: (profileDir) => chromeLaunchFlags(profileDir, wire),
+      wire,
+      timeoutMs: options.timeoutMs,
+      launchTimeoutMs,
     });
+    if (started.ok) return started.browser;
+    failures.push(started.failure);
+    // A process that outlived SIGKILL's grace still holds the machine; a second beside it is the
+    // load that made the first one late.
+    if (!started.reaped) break;
   }
+  throw new CdpLaunchFailedError({ executable: options.executable, attempts: failures });
 }
 
 /** `findChrome` then `launchChrome`. Refuses by name when there is no browser to drive. */
@@ -213,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/cdp-offline-script.ts

@@ -11,7 +11,9 @@
 // `delete` away. A document Chrome DID tell (it saw `offline`) gets Chrome's own `online` event on
 // restore; one it never told gets one from `RESTORE_ONLINE`, so a page reconnects exactly once.
 
+import { stringField } from '@ultimat3/core';
 import type { CdpResult } from './cdp-connection';
+import { CdpCallFailedError } from './cdp-errors';
 
 type Send = (
   method: string,
@@ -68,9 +70,37 @@ export function offlineScripts(send: Send): OfflineScripts {
     async remove(session) {
       const identifier = held.get(session);
       if (identifier === undefined) return undefined;
-      held.delete(session);
-      await send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, session);
-      return send('Runtime.evaluate', { expression: RESTORE_ONLINE }, session);
+      // Both halves are ATTEMPTED whatever the first answers, and a refusal of either surfaces.
+      // Traced 2026-10-02: a navigation in flight made the removal answer `Script not found`, the
+      // throw skipped the restore, and the open document kept reading `navigator.onLine === false`.
+      const refused: string[] = [];
+      const attempt = async (step: string, call: () => Promise<CdpResult>): Promise<boolean> => {
+        try {
+          await call();
+          return true;
+        } catch (error) {
+          refused.push(
+            `${step}: ${stringField(error, 'cause') ?? stringField(error, 'message') ?? 'refused'}`,
+          );
+          return false;
+        }
+      };
+      const removed = await attempt('removing the first-script override', () =>
+        send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, session),
+      );
+      // Kept while the browser may still hold it: the next `remove` asks again, and `add` cannot
+      // register a second copy beside one that is still there.
+      if (removed) held.delete(session);
+      await attempt('restoring the open document', () =>
+        send('Runtime.evaluate', { expression: RESTORE_ONLINE }, session),
+      );
+      if (refused.length > 0) {
+        throw new CdpCallFailedError({
+          method: `putting navigator.onLine back on session ${session}`,
+          detail: refused.join(' · '),
+        });
+      }
+      return undefined;
     },
   };
 }

package/src/cdp-wire-watch.ts

@@ -0,0 +1,113 @@
+// One responsibility: remember what the wire did, so a call that is never answered can say WHY —
+// its target went away, frames arrived that nothing could parse, or the target simply stayed
+// silent. The connection (`cdp-connection.ts`) feeds every frame in; `CdpTimeoutError` reads it out.
+
+import type { CdpTargetGone, CdpTimeoutObservation } from './cdp-errors';
+
+/** How many of the latest frames a timeout quotes. Bounded: a busy page sends thousands. */
+export const LAST_FRAMES = 8;
+
+/** Where the wire stood when a call was sent — what "since the call" is measured from. */
+export interface WireMark {
+  readonly arrived: number;
+  readonly dropped: number;
+  readonly navigations: number;
+}
+
+export interface WireWatch {
+  /** One frame that parsed: a reply or an event. */
+  frame(frame: Record<string, unknown>): void;
+  /** One frame nothing could parse. It has no `id`, so no call can be failed with it — only counted. */
+  drop(): void;
+  mark(sessionId: string | undefined): WireMark;
+  /** What happened between `mark` and now, for the call sent on `sessionId`. */
+  observe(mark: WireMark, sessionId: string | undefined, open: boolean): CdpTimeoutObservation;
+}
+
+const text = (from: unknown, key: string): string | undefined => {
+  const value =
+    typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
+  return typeof value === 'string' ? value : undefined;
+};
+
+export function wireWatch(): WireWatch {
+  let arrived = 0;
+  let dropped = 0;
+  const last: string[] = [];
+  const targetOf = new Map<string, string>(); // sessionId → targetId
+  const gone = new Map<string, CdpTargetGone>(); // sessionId → how it went
+  const navigations = new Map<string, number>(); // sessionId → main-frame navigations
+
+  const goneTarget = (targetId: string | undefined, how: CdpTargetGone): void => {
+    for (const [session, target] of targetOf) if (target === targetId) gone.set(session, how);
+  };
+
+  /** The few events that say a session can no longer answer, or that its page was replaced. */
+  const track = (method: string, session: string | undefined, params: unknown): void => {
+    if (method === 'Target.attachedToTarget') {
+      const attached = text(params, 'sessionId');
+      const target = text(
+        (params as Record<string, unknown> | undefined)?.['targetInfo'],
+        'targetId',
+      );
+      if (attached !== undefined && target !== undefined) targetOf.set(attached, target);
+    } else if (method === 'Target.detachedFromTarget') {
+      const detached = text(params, 'sessionId');
+      if (detached !== undefined) gone.set(detached, 'detached');
+    } else if (method === 'Target.targetDestroyed') {
+      goneTarget(text(params, 'targetId'), 'destroyed');
+    } else if (method === 'Target.targetCrashed') {
+      goneTarget(text(params, 'targetId'), 'crashed');
+    } else if (method === 'Inspector.targetCrashed' && session !== undefined) {
+      gone.set(session, 'crashed');
+    } else if (method === 'Page.frameNavigated' && session !== undefined) {
+      const frame = (params as Record<string, unknown> | undefined)?.['frame'];
+      // A frame with a parent is an iframe: the document the call was sent to is still there.
+      if (text(frame, 'parentId') === undefined) {
+        navigations.set(session, (navigations.get(session) ?? 0) + 1);
+      }
+    }
+  };
+
+  const note = (label: string): void => {
+    last.push(label);
+    if (last.length > LAST_FRAMES) last.shift();
+  };
+
+  return {
+    frame(frame): void {
+      arrived += 1;
+      const session = text(frame, 'sessionId');
+      const id = frame['id'];
+      const method = text(frame, 'method');
+      if (typeof id === 'number') note(`reply ${String(id)}`);
+      else if (method === undefined) note('a frame with neither an id nor a method');
+      else {
+        note(session === undefined ? method : `${method} @${session}`);
+        track(method, session, frame['params']);
+      }
+    },
+    drop(): void {
+      dropped += 1;
+    },
+    mark: (sessionId) => ({
+      arrived,
+      dropped,
+      navigations: sessionId === undefined ? 0 : (navigations.get(sessionId) ?? 0),
+    }),
+    observe(mark, sessionId, open): CdpTimeoutObservation {
+      const since = arrived - mark.arrived;
+      return {
+        sessionId: sessionId ?? null,
+        framesArrived: since,
+        // Only frames that arrived AFTER the call: an older one says nothing about its reply.
+        lastFrames: since === 0 ? [] : last.slice(-Math.min(since, LAST_FRAMES)),
+        framesDropped: dropped - mark.dropped,
+        transportOpen: open,
+        targetGone: sessionId === undefined ? null : (gone.get(sessionId) ?? null),
+        navigations:
+          sessionId === undefined ? 0 : (navigations.get(sessionId) ?? 0) - mark.navigations,
+      };
+    },
+  };
+}

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

@@ -2,7 +2,7 @@
 // bug: a frozen clock means "advance it", a seeded RNG means "same values every run", and both are
 // restorable so a test that genuinely needs real time can opt out explicitly.
 
-import { finiteCount, finiteOption } from '@ultimat3/core';
+import { canonicalJson, finiteCount, finiteOption, renderCauseValue } from '@ultimat3/core';
 import { NondeterministicError } from './errors';
 
 export const DEFAULT_SEED = 20260101;
@@ -191,16 +191,38 @@ 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
+  // the announcement alone, so an unannounced jump is time its timers never see.
   try {
+    // Inside the `try`: a listener that throws on entry must still get the outer instant back.
+    announceMove();
     return await body();
   } finally {
     frozenAt = previous;
+    announceMove();
+  }
+}
+
+/**
+ * Core's canonical form — a BigInt, a Date, a Map have tokens of their own where `JSON.stringify`
+ * threw a bare `TypeError` or folded them to `{}` — or `undefined` for the one shape it cannot
+ * walk, a cycle, which `Bun.deepEquals` then compares instead. A top-level `undefined`, function
+ * or symbol is a token of its type.
+ */
+function comparable(value: unknown): string | undefined {
+  // Canonical JSON spells all three `null`, so `undefined` and `null` compared equal: a token each.
+  const kind = typeof value;
+  if (kind === 'undefined' || kind === 'function' || kind === 'symbol') return `<${kind}>`;
+  try {
+    return canonicalJson(value);
+  } catch {
+    return undefined;
   }
 }
 
@@ -211,8 +233,15 @@ export async function frozenClock<T>(now: string, body: () => T | Promise<T>): P
 export async function assertDeterministic<T>(what: string, body: () => T | Promise<T>): Promise<T> {
   const first = await body();
   const second = await body();
-  const a = JSON.stringify(first);
-  const b = JSON.stringify(second);
-  if (a !== b) throw new NondeterministicError({ what, first: a, second: b });
+  const a = comparable(first);
+  const b = comparable(second);
+  const same = a === undefined || b === undefined ? Bun.deepEquals(first, second) : a === b;
+  if (!same) {
+    throw new NondeterministicError({
+      what,
+      first: a ?? renderCauseValue(first),
+      second: b ?? renderCauseValue(second),
+    });
+  }
   return first;
 }

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,12 +53,27 @@ 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,
     env: { ...inherited(), ...env },
     stdout: 'pipe',
     stderr: 'pipe',
+    // Synchronous inside a test, where the test's own timeout cannot interrupt it: a hung reset is
+    // killed here and refused below with what it printed, never a suite that waits forever.
+    timeout: DEFAULT_READY_TIMEOUT_MS,
   });
   if (run.exitCode !== 0) {
     throw refuse(`x ${args.join(' ')}`, `${run.stdout.toString()}${run.stderr.toString()}`);