@ultimat3/testing 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -13,18 +13,18 @@ is its own entry point and not part of the barrel.
 | Rule | Detail |
 |---|---|
 | No mocks of the DB | clone a template database; `template-db.ts` is the only DB path |
-| No wall clock | `frozenClock` / `advanceClock`; `Date.now()` is frozen by the preload |
+| No wall clock | `withFrozenClock` / `advanceClock`; `Date.now()` is frozen by the preload |
 | Frozen ≠ different | `globalThis.Date` becomes a subclass, so `FrozenDate[Symbol.hasInstance]` brands on the `[[DateValue]]` slot — `Date.prototype.getTime.call(value)` throws or it doesn't. |
 | Slot, not prototype | the brand is cross-realm on purpose: `instanceof RealDate` misses a `node:vm` or worker Date, and `Object.prototype.toString` is spoofable by `Symbol.toStringTag: 'Date'`. Only the slot is both |
-| No unmocked egress | `sealed-network.ts` patches fetch; a miss is `X_TEST_NETWORK_SEALED` |
+| No unmocked egress | `sealed-network.ts` seals `fetch`; `sealed-sockets.ts` `WebSocket`, `Bun.connect` (not loopback); a miss is `X_TEST_NETWORK_SEALED` |
 | Self is not egress | a port core's `markListening()` announced passes through — a socket test never unseals |
-| Offline is a state, not a mock | `network.offline()` / `.drop()` fail every request as `X_TEST_NETWORK_OFFLINE`, ahead of the mocks — the app's own offline path runs |
+| Offline is a state, not a mock | `network.offline()` / `.drop()` fail every dial, loopback too, as `X_TEST_NETWORK_OFFLINE` before any mock: the app's offline path runs |
 | One way offline | the `network` fixture. `setNetworkState` is the gate's only writer and is not exported — setting it from a test body skips the fixture's disposal and leaves every later file offline |
-| The seal key is a test process's, and nobody's export | `test-seal-key.ts`: installed by the preload only when `NODE_ENV === 'test'` and neither `ULTIMATE_SECRETS_KEY` nor `.secrets.key` exists; `startE2eApp` hands it to the child by VALUE (`testSealKeyEnv`), because the spawned app is a server and must never be able to install one. The constant is module-private and off the barrel (`test-seal-key.test.ts`). Never loosen the `NODE_ENV` check: the key is public |
+| The seal key is a test process's, and nobody's export | `test-seal-key.ts`: installed by the preload only when `NODE_ENV === 'test'` and neither `ULTIMATE_SECRETS_KEY` nor `.secrets.key` exists; `startE2eApp` hands it to the child by VALUE (`testSealKeyEnv`): a spawned server must never install one. The constant is module-private and off the barrel (`test-seal-key.test.ts`). Never loosen the `NODE_ENV` check: the key is public |
 | `toEqualRow` never prints a server-only value | `matcher-row.ts` compares every OWN property (`toEqual` cannot see a `.sealed()` column — empty diff). A non-enumerable property that differs is NAMED; its value and its length stay out of the message, which lands in CI logs |
 | No retries | a flake is fixed or deleted the day it flakes; there is no `retry: 3` |
 | A mutator's `local()` runs against `memoryLocalTx()` | `local-tx.ts`: keyed rows with the record store's rules (update invents nothing, `undefined` leaves a column, rows frozen). Never a hand-rolled table per test |
-| A page test RENDERS, with no cast | `render-view.ts`: `renderRoute(module, { url, actor })` resolves `load` once and hands `meta` and the page that one object, as every render mode does; `renderView(Component, props)` is one component. `@ultimat3/render` is imported INSIDE both, never at module scope — the barrel is what a tier-0 test imports for `expect` |
+| A page test RENDERS, with no cast | `render-view.ts`: `renderRoute(module, { url, actor })` resolves `load` once and hands `meta` and the page that one object, as every render mode does; `renderView(Component, props)` is one component. `@ultimat3/render` is imported inside both, never at module scope: a tier-0 test imports this barrel |
 | `toBeUltimateError` reads THREE fields | an `X_` code plus a `cause` plus a `fix`, all through core's `stringField`. `typeof value.code === 'string'` alone passed a Node `ENOENT` |
 | One matcher WAITS, and it is `toBeVisible` | `await expect(locator).toBeVisible()` retries `isVisible()` to a budget — 5000ms every 100ms, Playwright's own default, narrowable per call. |
 | The budget is counted in LOOKS, not milliseconds | this package freezes `Date.now()`, so a deadline computed from the clock never expires and the loop spins forever. `attemptsFor(budget)` is `1 + floor(timeout / interval)` |
@@ -36,7 +36,7 @@ is its own entry point and not part of the barrel.
 | Test names | the filename picks the step; a typed helper prefixes its own name. `testName(type, name)` is for an outer `describe` only — never on the inner `test` too, the prefix would print twice |
 | One body shape, five registrars | `test` (= `fixtureTest`), `unitTest`, `contractTest`, `liveTest`, `jobTest` all take `FixtureBody` + `{ timeoutMs }`: `unitTest('…', async ({ runJobs }) => …)`. Never `describe(testName('unit', …))` + `test` to get a fixture |
 | `runJobs` says who and what | `{ actor }` is the WORKER's identity (the org stays the job's declared tenant), `{ tenantId }` the enqueuer's row; `executions[n].result` is the body's return. A fresh event bus per fixture |
-| A `runJobs` pass is a real worker's `tick()` | `fixture-jobs.ts` builds an unstarted `createWorker` per pass, so admission runs: `concurrency` waits and `whenBusy: 'fail'` refuses (`X_JOB_KEY_BUSY`) exactly as in a fleet. Never `executeJob` on a bare `claim()`. The lease and slot renew every 1 ms of TEST time (`RENEW_MS`, `frozen-scheduler.ts` on `onClockMoved`), never on a wall-clock interval: cancel, `clock.advance(1)`, and the body hears `X_JOB_LEASE_LOST` — no hand-built worker |
+| A `runJobs` pass is a real worker's `tick()` | `fixture-jobs.ts` builds an unstarted `jobWorker` per pass, so admission runs: `concurrency` waits and `whenBusy: 'fail'` refuses (`X_JOB_KEY_BUSY`) exactly as in a fleet. Never `executeJob` on a bare `claim()`. The lease and slot renew every 1 ms of TEST time (`RENEW_MS`, `frozen-scheduler.ts` on `onClockMoved`), never on a wall-clock interval: cancel, `clock.advance(1)`, and the body hears `X_JOB_LEASE_LOST` — no hand-built worker |
 | Per-test state is `per-test-reset.ts` | the app preload's `beforeEach` resets the jobs event bus — only when `@ultimat3/jobs` is already loaded, so a core test never loads it |
 | An island test is `describeIslandState` | one block per declared state: mounted in `beforeAll` (60 s), disposed in `afterAll`, one build per file. `mountIslandState` + `using` for one test's own mount; an undeclared id is `X_TEST_ISLAND_STATE_UNKNOWN` |
 | An authenticator is tested with `authRequest()` | the hook's own two arguments, real — never `as unknown as Parameters<…>` |
@@ -74,7 +74,7 @@ is its own entry point and not part of the barrel.
 | A boot that rejects is its own teardown | `acquireWorkerDatabase`, `seed` or `boot` throwing returns no `BootedHarness`, so no caller can ever reach `close()` |
 | A found template is not a migrated one | `template-db.ts` tolerates "already exists" for the `CREATE DATABASE` alone. `config.migrate` runs unconditionally; drop + clone hold the same lock |
 | Fixture teardown | a fixture that installs process-global state (the ambient job or mail driver) implements `Symbol.dispose` / `Symbol.asyncDispose` and restores what was there |
-| Building one by hand | `createRunJobs()` outside a fixture body is not disposed for you — dispose it in `afterEach`, or the next file inherits your queue and your event bus |
+| Building one by hand | `testJobs()` outside a fixture body is not disposed for you — dispose it in `afterEach`, or the next file inherits your queue and your event bus |
 | Factory strategy | an association is built with the strategy that asked for it: `build()` never reaches a database, `create()` writes the parent first. Never a third strategy |
 | One write seam | `usePersister` is the only place `create()` writes. A factory that took a repo argument would put the seam at every call site |
 | Factory seeds | derived from the table name unless given, so two entities never draw the same uuid stream. `reset()` cascades into associated parents — a half-reset row is worse than none |
@@ -83,10 +83,10 @@ is its own entry point and not part of the barrel.
 | An island needs a BUILDER, not an import | `buildIslands` is `@ultimat3/cli`'s and both packages are tier 5; the one declared edge is `cli → testing`, so the reverse is a `bun run boundaries` failure. |
 | `mountIsland` AWAITS `mount` | `IslandEntry['mount']` returns `unknown`, not `void`, and the call is awaited |
 | Dispose STOPS the island, then restores the globals | when `mount` resolved to a function, `[Symbol.dispose]` calls it BEFORE `restore()` |
-| The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. `packages/ui/src/fake-dom.ts` is a second one for keyboard code, and `ui -> testing` is upward, so it is not a copy to collapse. `bun test` has no DOM and no DOM library may be added |
+| The micro-DOM is the fixture's, once **for islands** | `island-dom.ts`. `packages/ui/src/fake-dom-fixture.ts` is a second one for keyboard code, and `ui -> testing` is upward: not a copy to collapse. `bun test` has no DOM and no DOM library may be added |
 | `style` and `classList` RECORD | `FakeStyle` is one declaration map behind all four spellings compiled Solid uses (static attribute, `setProperty`, `cssText`, `removeAttribute`), so a test can assert the component set `--form-gap` |
 | `classList` is the class attribute | not a list of its own, so `classList.toggle` — which the compiler emits INLINE for `classList={{ … }}`, no runtime helper between — and `className` can never answer one element two ways. |
-| A `document` listener is the documentElement's | no bubbling: `document.addEventListener` registers on `documentElement`, and `fire(mounted.documentElement, 'keydown', …)` drives it. One handler per type, last wins |
+| A `document` listener is the documentElement's | no bubbling: `document.addEventListener` registers on `documentElement`, and `fire(mounted.documentElement, 'keydown', …)` drives it. Every listener per type runs; removal is by function identity |
 | `querySelector` skips `this` | descendants only, as the DOM's does. Matching the element it is called on made a host `<div>` answer `find('div')` with the container the test built rather than the markup the island rendered |
 | The selector grammar is SMALL and REFUSES | `island-selector.ts`: compounds of tag, `#id`, `.class`, `[attr]`, `[attr="value"]`, joined by space or `>`. Anything else is `X_TEST_ISLAND_SELECTOR_UNSUPPORTED` with the offset, never an empty answer |
 | The box is 0 until a test writes it | `clientHeight`, `scrollTop`, `scrollHeight` and the rest are writable numbers, default 0; `getBoundingClientRect()` derives from the offset box |
@@ -105,12 +105,12 @@ is its own entry point and not part of the barrel.
 | The island EXTENSION is not restated here | `.island.tsx` is `@ultimat3/render`'s `ISLAND_EXTENSION` and `render` is not a dependency of this package. |
 | A mount imports from its own temp DIRECTORY | `island-scratch.ts`: per mount (identical chunks stay two modules); removed on dispose, at the file boundary and in the run's `afterAll` — `exit` never fires under `bun test`. Never a `data:` URL (coverage panics past ~4 kB) |
 | Attaching a node MOVES it | `appendChild`, `insertBefore`, `replaceChild` detach it from its old parent first; `removeChild` clears `parentNode` |
-| Globals install all-or-nothing | `installGlobals` saves DESCRIPTORS, not values — a saved value cannot tell "no such global" from "a global holding `undefined`", and the teardown deleted both |
+| Globals install in layers | `island-globals.ts`: a key's real DESCRIPTOR is saved by the first live mount, restored by the last, in any dispose order |
 | Which command shards | `bun test` is one process on one database — what a scaffolded app's `test` script runs |
 
 ## The frozen instant and the seed are screened
 
-`installDeterminism({ now })`, `setFrozenClock`, `frozenClock` and `advanceClock` go through one
+`installDeterminism({ now })`, `setFrozenClock`, `withFrozenClock` and `advanceClock` go through one
 `instantMs`: an unreadable instant would make `Date.now()` answer `NaN` for every later file. The
 seed is screened too — `seed >>> 0` maps `NaN`, `0.5` and `2 ** 32` onto seed 0 silently.
 `finiteOption`/`finiteCount` from `@ultimat3/core` are the one form; `determinism-bounds.test.ts`
@@ -145,7 +145,7 @@ lives beside the `PageLike` it implements. `cli` imports it over the declared `c
 | `e2e-dom-fixture.ts` | a document small enough to hold in a test and real enough to RUN the expressions above |
 | `cdp-browser.ts` | the two doors: `openE2eBrowserIfAvailable()` (undefined when there is no browser) and `openE2eBrowser()` (refuses by name), and the close that undoes both halves |
 | `cdp-launch.ts` | which Chrome, its flags, the launch deadline (`LAUNCH_TIMEOUT_MS`, 60 s — a cold start is not a call) and the ONE relaunch (`LAUNCH_ATTEMPTS`) |
-| `cdp-launch-attempt.ts` | one start: its own process group, the first answer over the pipe; on none, a full reap (group killed, profile removed) before the next. ONE `close()`, a promise, always awaited — no sync close |
+| `cdp-launch-attempt.ts` | one start in its own group; on no answer a full reap (group, then profile + singleton dir: `cdp-launch-profile.ts`). ONE awaited `close()` |
 | `cdp-connection.ts` | CDP over a transport — the launched Chrome's pipe (`cdp-pipe.ts`), a remote one's `WebSocket` (`cdpConnect`): reply correlation by `id`, event waiters, the per-call deadline; why one went unanswered is `cdp-wire-watch.ts` |
 | `cdp-e2e-session.ts` | the BROWSER half, `E2eSession`: every target auto-attached at browser level and PAUSED until its Network domain is on (a SharedWorker opens its socket at start-up) |
 | `cdp-e2e-page.ts` | one TAB, `E2eTab`: `E2eBrowserPage`'s five methods plus `reload`, `waitFor`, `indexedDbNames`, `close`. `offline()` forwards to the session — the switch is browser-wide |

package/README.md

@@ -10,7 +10,8 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `harness.ts` | `describeApp()` / `testApp()` — boot an app in-process with its own database |
 | `template-db.ts` | N workers, N databases, one migrated template, `CREATE DATABASE ... TEMPLATE` |
 | `determinism.ts` | frozen clock, seeded RNG, seeded uuids, `assertDeterministic` |
-| `sealed-network.ts` | any unmocked egress fails, with the URL and the mock line |
+| `sealed-network.ts` | any unmocked `fetch`, `WebSocket` or `Bun.connect` egress fails, with the URL and the line that fixes it |
+| `sealed-sockets.ts` | the `WebSocket` and `Bun.connect` patches, behind `sealed-network.ts`'s one gate |
 | `factories.ts` | `defineFactory` — seeded rows, traits, associations, `build` vs `create` |
 | `factory-registry.ts` | `factoriesFor(registry)` — one factory per entity, defaults read off column names |
 | `factory-persist.ts` | `usePersister` — the one seam `create()` writes through |
@@ -39,9 +40,9 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `island-states-resolve.ts` | a name a reader typed → the manifest it meant; a manifest → the island file it claims |
 | `framework-fixtures.ts` | registers both sets; the app registers only what it owns |
 | `registry-leak-guard.ts` | fails the run naming the FILE that left a process-global registry dirty, and restores the ones that can be restored at the same boundary |
-| `registry-snapshot.ts` | `captureProcessRegistries()` / `restoreProcessRegistries()` — the locale config, the catalogs, the permission set and the role map, put back as a file inherited them. A module-scope declaration evaluates once per process (`bun test` without `--isolate`, `As of 2026-08`), so a neighbour's `clearPermissions()` is otherwise permanent |
+| `registry-snapshot.ts` | `captureProcessRegistries()` / `restoreProcessRegistries()` — the locale config, the catalogs, the permission set, the role map, the tasks and the declared measurement actor, put back as a file inherited them. A module-scope declaration evaluates once per process (`bun test` without `--isolate`, `As of 2026-08`), so a neighbour's `clearPermissions()` is otherwise permanent |
 | `registry-isolation.ts` | `isolateEntityRegistry()` — an empty entity registry, and the process's back after. Its own entry point (`@ultimat3/testing/registry-isolation`), never the barrel: it value-imports `@ultimat3/entity`, and the barrel is what a tier-0 test imports for `expect` |
-| `quiet-logs.ts` | a green run prints the reporter and nothing else: the framework's log lines go to a sink that drops them. `LOG_LEVEL=info bun test <file>` shows them — naming `LOG_LEVEL` is the one escape hatch, and a level above `info` filters what the TERMINAL shows, never what the logger emits (below). A test asserting on log output hands `createLogger({ level, writer })` its own writer, or installs its own `setLogSink` and restores the previous one |
+| `quiet-logs.ts` | a green run prints the reporter and nothing else: the framework's log lines go to a sink that drops them. `LOG_LEVEL=info bun test <file>` shows them — naming `LOG_LEVEL` is the one escape hatch, and a level above `info` filters what the TERMINAL shows, never what the logger emits (below). A test asserting on log output hands `structuredLogger({ level, writer })` its own writer, or installs its own `setLogSink` and restores the previous one |
 | `preload.ts` | the bunfig preload that installs all of the above |
 
 ## Install
@@ -93,7 +94,7 @@ with `{ runJobs }` — never `describe(testName('unit', …))` around a bare `te
 | `network` | `offline()` · `drop()` · `online()` · `state()` over the sealed network | the preload |
 | `runJobs` | a worker: call it to enqueue+drain, then `enqueue()` `drain()` `due()` `inFlight()` `depth()` — see [below](#a-job-under-runjobs) | the preload |
 | `statements` | every statement the test issued: `all()` `count(fingerprint?)` `shapes()` — and an N+1 throws | the preload |
-| `page` | the browser: `goto` `gotoStreamed` `getByRole` `evaluate` `waitForServiceWorker` | a browser driver |
+| `page` | the browser: `goto` `gotoStreamed` `getByRole` `evaluate` `waitForServiceWorker({ timeoutMs? })` — an uncontrolled first page is reloaded once for its worker (`e2e-service-worker.ts`) | a browser driver |
 | `budget` | `jsBytes(route)` measured off the built output | a browser driver |
 | `signIn` | put the browser session in a member's shoes | a browser driver |
 | `deploy` | `newBuild()` — same app, new build id, page still open | a browser driver |
@@ -160,7 +161,7 @@ unitTest('the sweep runs as the billing worker', async ({ runJobs }) => {
 | **`{ actor }`** | on the call and on `drain()`: the identity the WORKER runs as — what an app wires through `WorkerOptions.context()`. Its org is replaced by the job's declared tenant, as a real worker's is; `tenant: 'none'` strips it. Absent is core's anonymous actor |
 | **`{ tenantId }`** | on the call and on `enqueue()`: the ENQUEUER's tenant on the row — the limiter's bucket and the dedupe namespace, the half of `handle.as(actor, input)` that reaches the queue. Never the tenant the body runs under: that is the job's own `tenant:` |
 | **one event bus per fixture** | `step.waitForEvent` reads an ambient bus that STORES; the fixture installs a fresh one and hands the process's back, so one test's `publishEvent` cannot resume the next test's run |
-| **a real worker's pass** | each round is `createWorker(...).tick()`: admission, the limiter and keyed `concurrency` (`whenBusy: 'fail'` settles `refused`, `X_JOB_KEY_BUSY`) hold exactly as in production |
+| **a real worker's pass** | each round is `jobWorker(...).tick()`: admission, the limiter and keyed `concurrency` (`whenBusy: 'fail'` settles `refused`, `X_JOB_KEY_BUSY`) hold exactly as in production |
 | **a cancel reaches a running body** | the worker renews its lease on the TEST clock — every millisecond of it — and a renewal that misses the row aborts `ctx.signal` with `X_JOB_LEASE_LOST`: start `runJobs.drain()`, cancel the row (`cancelJob(jobDriver(), id)` or the app's own action), `clock.advance(1)`, await the drain. No hand-built worker, no sleep, no wall-clock timer |
 
 ## An N+1 fails the test it happened in
@@ -283,13 +284,13 @@ Two ship, for the ports an app may implement itself — a `JobDriver` and `@ulti
 `BudgetStore`:
 
 ```ts
-import { MemoryBudgetStore } from '@ultimat3/ai';
-import { createMemoryDriver } from '@ultimat3/jobs';
+import { memoryBudgetStore } from '@ultimat3/ai';
+import { memoryJobDriver } from '@ultimat3/jobs';
 import { behavesLike, budgetStoreConformance, describe, jobDriverConformance } from '@ultimat3/testing';
 
 // The shipped ports pass; put your own driver or store where these are.
-describe('my queue', () => behavesLike(jobDriverConformance, () => createMemoryDriver()));
-describe('my budget store', () => behavesLike(budgetStoreConformance, () => new MemoryBudgetStore()));
+describe('my queue', () => behavesLike(jobDriverConformance, () => memoryJobDriver()));
+describe('my budget store', () => behavesLike(budgetStoreConformance, () => memoryBudgetStore()));
 ```
 
 | Suite | Holds a store to |
@@ -331,7 +332,7 @@ and `JEST_WORKER_ID` itself, so that precedence is load-bearing rather than defe
 
 | State | Owned by | What teardown does |
 |---|---|---|
-| the seal on `fetch` | the preload | unseals only if this boot was the one that sealed |
+| the seal on `fetch`, `WebSocket` and `Bun.connect` | the preload | unseals only if this boot was the one that sealed |
 | the frozen instant, `Math.random`, `globalThis.Date` | the preload (`ULTIMATE_TEST_NOW` / `ULTIMATE_TEST_SEED`) | `restoreCapturedDeterminism(captureDeterminism())` around the boot |
 | mocks, allow-listed hosts, the seen list | the boot | `resetNetwork()` |
 | the cloned worker database | the boot | `db.drop()`, in a `finally` — a rejecting `app.close()` reaches it |
@@ -349,11 +350,27 @@ X_TEST_NETWORK_SEALED
   fix:   mockFetch('https://api.stripe.com/v1/charges', () => new Response('{}')) — or allowHost('api.stripe.com') if it must be real
 ```
 
-A server this process booted is exempt: `createServer().start()` announces its socket through
+A server this process booted is exempt: `httpServer().start()` announces its socket through
 core's `markListening()`, so a test may call its own `handle.url()` on a kernel-assigned port with
 the seal fully on. Unsealing (`ULTIMATE_TEST_ALLOW_NET=1`) stays reserved for a deliberate live
 integration — never for a socket test.
 
+**Three dials are sealed, and only three** — `fetch`, `new WebSocket(url)` and `Bun.connect({ hostname,
+port })`, behind one gate: one allow-list (`allowHost('host[:port]')`), one offline state, one
+`requestedUrls()` record. As of 2026-10:
+
+| Dial | Refused with | Passes through |
+|---|---|---|
+| `fetch` | `X_TEST_NETWORK_SEALED` / `X_TEST_NETWORK_OFFLINE` | a mock, an allowed host, a port `markListening()` announced |
+| `new WebSocket(url)` | the same, thrown by the constructor before it dials | an allowed host, any loopback host |
+| `Bun.connect(…)` | the same, as the rejected promise | an allowed host, any loopback host, a unix socket |
+
+A socket to loopback is not egress on any port: it is how a test reaches a server it `Bun.listen`ed
+and the compose services the live suites dial. A socket test injects its transport (`connect`,
+`client`) rather than mocking the dial, so there is no `mockFetch` for one. **Not sealed:**
+`node:net`, `node:tls`, `node:http(s)`, `Bun.udpSocket` and the native clients (`Bun.sql`,
+`Bun.redis`, `Bun.S3Client`) — a test that must not reach the internet through those injects them.
+
 ## Rendering a page or a component
 
 A page is a function of props and a route is a module, so a unit test renders either in process —
@@ -391,7 +408,7 @@ unitTest('the shell keeps the page in <main>', async () => {
 | **`renderView(Component, props)`** | one component. `props` is the component's own type — a renamed prop is a compile error in the test. A component that renders an `island()` is refused here: its timing is a route's |
 | **`view.html`** | the markup as the document carries it |
 | **`view.text`** | what a reader sees: tags, `<script>` and `<style>` bodies removed, entities decoded, whitespace collapsed. Compare with `t('<key>')` — markup escapes what the catalog does not |
-| **`actor`** | `load` and the page run inside `runWithContext(createContext({ actor }))`. Without one they run outside any request context, as a static page does |
+| **`actor`** | `load` and the page run inside `runWithContext(ctxOf({ actor }))`. Without one they run outside any request context, as a static page does |
 | **the file stays `.test.ts`** | no JSX in a test: the registry-leak guard's loader covers `.test.ts` only, and children that need markup are a string |
 
 `@ultimat3/render` is imported inside the two functions, so the barrel still loads no renderer.
@@ -710,17 +727,37 @@ declared edge and the reverse is a `bun run boundaries` failure.
 
 ## Launching Chrome
 
-`launchChrome({ executable, timeoutMs, launchTimeoutMs? })` — what the `e2e` step and `x shot` both
-start a browser with. Driven over `--remote-debugging-pipe`; the first answer is readiness.
+`launchChrome({ executable, timeoutMs, launchTimeoutMs?, wire? })` — what the `e2e` step and `x shot`
+both start a browser with. Driven over `--remote-debugging-pipe`, and on Windows — where the parent
+cannot hold Chrome's fds 3 and 4 — over `--remote-debugging-port=0` and the profile's
+`DevToolsActivePort` (`wire: 'pipe' | 'port'` overrides). The first answer is readiness.
+
+`CHROME_CANDIDATES` is this platform's install list, probed after `CHROME_PATH`: the `/usr/bin` names
+on Linux, the app bundles on macOS, Chrome under `%ProgramFiles%` / `%ProgramFiles(x86)%` /
+`%LOCALAPPDATA%` then Edge (`msedge.exe`) on Windows.
 
 | Export | What it is |
 |---|---|
 | `LAUNCH_TIMEOUT_MS` | `60_000` — the first answer's deadline per start. `launchTimeoutMs` defaults to the larger of this and `timeoutMs`; every later call has `timeoutMs` |
 | `LAUNCH_ATTEMPTS` | `2` — an unanswered start is reaped and started once more on a fresh profile. Never more |
-| `CdpLaunchAttempt` | one unanswered start, in `X_CDP_LAUNCH_FAILED`'s `meta.attempts`: `why` (`deadline` \| `closed`), `waitedMs`, `exitCode` (`null` when killed), `stderr` (its last lines) |
-| `LaunchedBrowser.close()` · `E2eBrowser.close()` | THE close, a promise, always awaited: the process, its whole process group, its profile directory. There is no synchronous close |
-
-`As of 2026-10-02`.
+| `LAUNCH_BUDGET_MS` | derived: `LAUNCH_ATTEMPTS × (LAUNCH_TIMEOUT_MS + LAUNCH_REAP_MS)` — the longest a launch is designed to take, both starts and their bounded reaps |
+| `E2E_BROWSER_OPEN_MS` | derived: `LAUNCH_BUDGET_MS` + the session's two setup calls + the first tab, at `DEFAULT_CDP_TIMEOUT_MS` each. THE deadline of every `beforeAll` that opens a browser — one below it is killed by Bun before the relaunch, and `X_CDP_LAUNCH_FAILED` never names the slow step |
+| `E2E_BROWSER_CLOSE_MS` | derived: `4 × CLOSE_GRACE_MS` — SIGTERM's grace, SIGKILL's, the group reap, the profile's removal. THE deadline of an `afterAll` that closes a browser it holds (one that releases a lease takes `E2E_BROWSER_OPEN_MS`: it may await the open). At Bun's 5 s default a close cut short by the run's end left the profile half-removed in the temp root |
+| `E2E_TAB_OPEN_MS` | derived: one more `session.newTab()` — `Target.createTarget`, then its attach |
+| `E2E_GOTO_MS` | derived: one `tab.goto()` — the navigate raced by the load event, then two reads of the document |
+| `E2E_APP_START_MS` | derived: `startE2eApp()` at its default deadline — `x db reset`, `x db seed` and `/readyz` (wall-clock), each its whole 90 s, then a refused boot's stop |
+| `E2E_APP_STOP_MS` | derived: an e2e app's `stop()` — SIGTERM, the app's own drain at the defaults (readiness grace + `drain.deadlineMs`), then SIGKILL. Bounded: a wedged app no longer holds the hook forever |
+| `CdpLaunchAttempt` | one unanswered start, in `X_CDP_LAUNCH_FAILED`'s `meta.attempts`: `why` (`deadline` \| `closed` \| `spawn` — the binary could not be started at all), `waitedMs`, `exitCode` (`null` when killed), `stderr` (its last lines), `detail` (what the launcher saw end it: the refused dial and its endpoint, the call that timed out, the spawn error) |
+| `leaseE2eBrowser(key, open)` | ONE browser for every suite of the process that asks by `key`: `{ opened, release() }`, opened by the first, each suite its own tab. Closed by the last holder out — or, once a preload has called `closeE2eBrowsersAtRunEnd()`, at the run's end (Bun fires no `exit` under `bun test`, and runs one file to its end before loading the next) |
+| `LaunchedBrowser.close()` · `E2eBrowser.close()` | THE close, a promise, always awaited: the process, its whole process group (on Windows its process tree, `taskkill /T /F`), and only then its profile directory — removed again while something re-creates it, bounded — and Chrome's `com.google.Chrome.XXXXXX` singleton-socket directory beside it, when it holds nothing but singleton files. There is no synchronous close |
+
+Every hook that opens or closes a browser derives its deadline from these — the open, the close,
+the app's start or stop, plus its own steps. `e2e-browser-hooks.test.ts` reads every suite under
+`packages/*/e2e`, `examples/*/apps/*/e2e` and `dummy/*/apps/*/e2e`, follows each exported helper
+that calls an opener (`acceptanceBrowser()`) or `startE2eApp`, resolves named deadlines through
+their declarations, and refuses a literal, a missing deadline or a sum without the budget it needs.
+
+`As of 2026-10-05`.
 
 ## The one assertion that waits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -29,26 +29,26 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "24.0.0",
-    "@ultimat3/cache": "24.0.0",
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/db": "24.0.0",
-    "@ultimat3/entity": "24.0.0",
-    "@ultimat3/http": "24.0.0",
-    "@ultimat3/i18n": "24.0.0",
-    "@ultimat3/jobs": "24.0.0",
-    "@ultimat3/mail": "24.0.0",
-    "@ultimat3/policy": "24.0.0",
-    "@ultimat3/query": "24.0.0",
-    "@ultimat3/realtime": "24.0.0",
-    "@ultimat3/render": "24.0.0",
-    "@ultimat3/time": "24.0.0"
+    "@ultimat3/action": "25.1.0",
+    "@ultimat3/cache": "25.1.0",
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/db": "25.1.0",
+    "@ultimat3/entity": "25.1.0",
+    "@ultimat3/http": "25.1.0",
+    "@ultimat3/i18n": "25.1.0",
+    "@ultimat3/jobs": "25.1.0",
+    "@ultimat3/mail": "25.1.0",
+    "@ultimat3/policy": "25.1.0",
+    "@ultimat3/query": "25.1.0",
+    "@ultimat3/realtime": "25.1.0",
+    "@ultimat3/render": "25.1.0",
+    "@ultimat3/time": "25.1.0"
   }
 }

package/src/auth-request.ts

@@ -42,7 +42,7 @@ export async function authRequest(init: AuthRequestInit = {}): Promise<Parameter
     );
   }
   if (init.bearer !== undefined) headers.set('authorization', `Bearer ${init.bearer}`);
-  const ctx = http.createRequestContext({
+  const ctx = http.requestContext({
     url,
     method,
     role: 'web',

package/src/cdp-browser-lease.ts

@@ -0,0 +1,112 @@
+// One responsibility: ONE browser shared by the suites of a test process that ask for it by the
+// same key — opened by the first, a holder count per suite, closed by the last out or at the run's
+// end. Opening and closing a browser is `cdp-browser.ts`; this file only decides WHEN.
+
+import { afterAll } from 'bun:test';
+import type { E2eBrowser } from './cdp-browser';
+import { E2E_BROWSER_OPEN_MS } from './cdp-browser';
+
+export interface E2eBrowserLease {
+  /** The shared browser: opened by the first lease of its key, `undefined` with no browser here. */
+  readonly opened: Promise<E2eBrowser | undefined>;
+  /** This holder is done. Idempotent. The last one out closes it, unless the run closes it at its end. */
+  release(): Promise<void>;
+}
+
+/** Registers a hook for the end of the run — a preload's `afterAll`, which Bun runs once, last. */
+export type RunEndHook = (hook: () => Promise<void>, timeoutMs: number) => void;
+
+export interface E2eBrowserLeases {
+  lease(key: string, open: () => Promise<E2eBrowser | undefined>): E2eBrowserLease;
+  /** From a PRELOAD: keep every leased browser open until the run ends, then close each. */
+  closeAtRunEnd(after: RunEndHook): void;
+}
+
+interface Held {
+  readonly opening: Promise<E2eBrowser | undefined>;
+  holders: number;
+}
+
+/** Its open already failed in front of the holder that awaited it: the close has nothing to add. */
+const closeHeld = async (held: Held): Promise<void> => {
+  const browser = await held.opening.catch(() => undefined);
+  await browser?.close();
+};
+
+/**
+ * A fresh registry. Why the last holder alone cannot make "last" mean the last SUITE: Bun runs one
+ * test file to its end before it loads the next (measured on 1.4.2), so between two suites the
+ * count is 0; and `exit` and `beforeExit` never fire under `bun test`, so a browser kept "for the
+ * next one" past the last file is a Chrome and a profile left behind. Only a preload's `afterAll`
+ * runs after every file — under `--isolate` after each, with a fresh global, which is right too.
+ */
+export function createE2eBrowserLeases(): E2eBrowserLeases {
+  const held = new Map<string, Held>();
+  let runEnd = false;
+  return {
+    lease(key, open) {
+      let shared = held.get(key);
+      if (shared === undefined) {
+        const made: Held = { opening: open(), holders: 0 };
+        held.set(key, made);
+        // A failed open is nobody's to share: the next holder opens afresh and meets its own error.
+        made.opening.catch(() => {
+          if (held.get(key) === made) held.delete(key);
+        });
+        shared = made;
+      }
+      const mine = shared;
+      mine.holders += 1;
+      let released = false;
+      return {
+        opened: mine.opening,
+        async release() {
+          if (released) return;
+          released = true;
+          mine.holders -= 1;
+          if (mine.holders > 0 || runEnd) return;
+          if (held.get(key) === mine) held.delete(key);
+          await closeHeld(mine);
+        },
+      };
+    },
+    closeAtRunEnd(after) {
+      if (runEnd) return;
+      runEnd = true;
+      // The deadline of an open: the hook awaits one still in flight before it can close it.
+      after(async () => {
+        const open = [...held.values()];
+        held.clear();
+        for (const one of open) await closeHeld(one);
+      }, E2E_BROWSER_OPEN_MS);
+    },
+  };
+}
+
+/**
+ * On `globalThis` under one `Symbol.for` key: the preload imports this module by path and a suite
+ * through `@ultimat3/testing`, and each may hold its own copy — `e2e-browser-handle.ts`'s reason.
+ */
+const KEY = Symbol.for('ultimate.e2e.browserLeases');
+
+const processLeases = (): E2eBrowserLeases => {
+  const known = Reflect.get(globalThis, KEY) as E2eBrowserLeases | undefined;
+  if (known !== undefined) return known;
+  const made = createE2eBrowserLeases();
+  Object.defineProperty(globalThis, KEY, { value: made, configurable: true });
+  return made;
+};
+
+/**
+ * The browser the suites of this process share under `key`; call it in a `beforeAll` and
+ * `release()` in the matching `afterAll`. Without `closeE2eBrowsersAtRunEnd` in the preload the
+ * last holder out closes it, which is one browser per suite again — never one left running.
+ */
+export const leaseE2eBrowser = (
+  key: string,
+  open: () => Promise<E2eBrowser | undefined>,
+): E2eBrowserLease => processLeases().lease(key, open);
+
+/** The preload's half: `closeE2eBrowsersAtRunEnd()` once, and leased browsers live for the run. */
+export const closeE2eBrowsersAtRunEnd = (after: RunEndHook = afterAll): void =>
+  processLeases().closeAtRunEnd(after);

package/src/cdp-browser.ts

@@ -13,11 +13,52 @@ import type { E2eSession } from './cdp-e2e-session';
 import { cdpE2eSession } from './cdp-e2e-session';
 import { CdpBrowserMissingError } from './cdp-errors';
 import type { LaunchedBrowser } from './cdp-launch';
-import { CHROME_CANDIDATES, findChrome, launchChrome } from './cdp-launch';
+import { CHROME_CANDIDATES, findChrome, LAUNCH_BUDGET_MS, launchChrome } from './cdp-launch';
+import { LAUNCHED_CLOSE_MS } from './cdp-launch-attempt';
 
 /** How long a launch, a connect or a single CDP call may take. One number, three deadlines. */
 export const DEFAULT_CDP_TIMEOUT_MS = 30_000;
 
+/**
+ * Sequential deadlines `cdpE2eSession` spends before it answers — `Target.setDiscoverTargets`,
+ * then `Target.setAutoAttach` — and `newTab()` spends per tab: `Target.createTarget`, then the
+ * attach that publishes it. Counts of calls in `cdp-e2e-session.ts`, held to it by
+ * `cdp-browser.test.ts` over a fake connection.
+ */
+export const SESSION_SETUP_DEADLINES = 2;
+export const TAB_OPEN_DEADLINES = 2;
+
+/** The longest one more `session.newTab()` is designed to take, at the default per-call deadline. */
+export const E2E_TAB_OPEN_MS = TAB_OPEN_DEADLINES * DEFAULT_CDP_TIMEOUT_MS;
+
+/**
+ * The longest `openE2eBrowser()` is DESIGNED to take, at the default deadline: the whole launch
+ * budget — both starts and their reaps — then the session's setup and the first tab. THE deadline
+ * for a `beforeAll` or `afterAll` that opens or closes a browser: one below it is killed by Bun
+ * before the relaunch, and the failure that names the slow step never surfaces. Derived, never
+ * restated: `e2e-browser-hooks.test.ts` refuses a browser hook whose deadline does not start here.
+ */
+export const E2E_BROWSER_OPEN_MS =
+  LAUNCH_BUDGET_MS + SESSION_SETUP_DEADLINES * DEFAULT_CDP_TIMEOUT_MS + E2E_TAB_OPEN_MS;
+
+/**
+ * The longest `E2eBrowser.close()` is DESIGNED to take — the launched browser's close, every step
+ * bounded (`LAUNCHED_CLOSE_MS`). THE deadline for a hook that closes a browser it already holds: a
+ * hook left at Bun's 5 s default is killed mid-close, and when it is the run's last the process
+ * exits with the profile half-removed — the `x-e2e-chrome-*` directories found leaked in `/tmp`.
+ */
+export const E2E_BROWSER_CLOSE_MS = LAUNCHED_CLOSE_MS;
+
+/**
+ * Sequential deadlines one `tab.goto()` spends: the load event raced against `Page.navigate`'s
+ * reply (one deadline, two waiters), then the two reads of the document (`cdp-e2e-page.ts`). Held
+ * to the method by `cdp-browser.test.ts` over a fake connection, as the tab's count is.
+ */
+export const GOTO_DEADLINES = 3;
+
+/** The longest one `tab.goto()` is designed to take, at the default per-call deadline. */
+export const E2E_GOTO_MS = GOTO_DEADLINES * DEFAULT_CDP_TIMEOUT_MS;
+
 export interface E2eBrowser {
   /** The first tab — what `installE2eDriver({ page })` drives. */
   readonly page: E2eTab;

package/src/cdp-connection.ts

@@ -11,7 +11,7 @@
 // small ones, on Bun's native `WebSocket`, with no dependency to add to a repo whose first
 // non-negotiable is that Bun's natives replace most of them.
 
-import { assert } from '@ultimat3/core';
+import { assert, stringField } from '@ultimat3/core';
 import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
 import { wireWatch } from './cdp-wire-watch';
 
@@ -99,6 +99,16 @@ export interface CdpConnectionOptions {
   readonly timeoutMs: number;
 }
 
+/**
+ * What went wrong, in the socket's own words when it has any. Bun hands `onerror` an `ErrorEvent`
+ * whose `message` is the only place the reason lives — "Failed to connect", "Expected 101 status
+ * code" — and a refusal that drops it names the step and not the cause.
+ */
+const failure = (event: unknown, what: string): string => {
+  const message = stringField(event, 'message');
+  return message === undefined || message === '' ? what : `${what}: ${message}`;
+};
+
 /**
  * A remote browser over its WebSocket url. NOT the e2e driver's wire: measured in the dummy's
  * `offline-feed` suite on Bun 1.4.0, Bun's WebSocket client handed `onmessage` text spliced out of
@@ -125,11 +135,14 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
     };
     // `onerror` is the handshake's only until `listen` below reassigns it: a failure BEFORE open
     // has no pending call to abandon, and rejecting is the only way the caller hears about it.
-    socket.onerror = (): void => {
+    socket.onerror = (event: Event): void => {
       clearTimeout(timer);
       socket.close();
       reject(
-        new CdpCallFailedError({ method: 'connect', detail: 'the browser refused the connection' }),
+        new CdpCallFailedError({
+          method: 'connect',
+          detail: failure(event, 'the browser refused the connection'),
+        }),
       );
     };
   });
@@ -142,7 +155,8 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
         handlers.message(typeof event.data === 'string' ? event.data : '');
       };
       socket.onclose = (): void => handlers.closed('the browser closed the CDP connection');
-      socket.onerror = (): void => handlers.closed('the CDP connection failed');
+      socket.onerror = (event: Event): void =>
+        handlers.closed(failure(event, 'the CDP connection failed'));
     },
   };
   return cdpConnectOver(transport, options.timeoutMs);