@ultimat3/cli 21.0.0 → 22.1.0

package/src/e2e-driver.ts

@@ -1,117 +0,0 @@
-// The registration. One call from an app's test preload turns the declared `page` fixture into a
-// browser-backed one and gives `e2eTest` a driver — and nothing here runs unless that call is
-// made, which is what keeps a CI box with no Chrome answering `hasE2eDriver() === false`.
-
-import { test as bunTest } from 'bun:test';
-import type { E2eBody, E2eFixtures, PageLike } from '@ultimat3/testing';
-import {
-  defineFixtures,
-  FixtureUnavailableError,
-  resetE2eDriver,
-  unavailableFixture,
-  useE2eDriver,
-} from '@ultimat3/testing';
-import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
-import { e2ePage } from './e2e-page';
-
-export interface E2eDriverOptions extends E2ePageOptions {
-  /**
-   * Switch the running app to a new build — the SERVER half no page port can speak for. Given, it
-   * becomes the `deploy` fixture's `newBuild()` and `e2eTest`'s `update()`; absent, both refuse by
-   * name. The gate's e2e preload passes the spawned app's `restart({ BUILD_ID })`.
-   */
-  readonly newBuild?: (() => Promise<void>) | undefined;
-}
-
-/**
- * A member this driver cannot build is a REFUSAL, never a no-op. A fixture that silently did
- * nothing would make the assertion after it read as proof: `offline()` followed by "the fallback
- * rendered" is the app's ONLINE page passing an offline test.
- */
-const refuse =
-  (name: string, needs: string): (() => Promise<void>) =>
-  () =>
-    Promise.reject(new FixtureUnavailableError({ name, needs }));
-
-/**
- * `offline()`/`online()` FORWARD, `As of 2026-08-27`. They refused until then on a reason the tree
- * contradicted on the day it was written: this file said `CdpPageLike`
- * (`packages/scraping/src/cdp-port.ts`) "declares twelve methods and none of them is
- * `setOfflineMode`". It declares it at line 71 — optional, guarded, with a coded
- * `X_NOT_IMPLEMENTED` in `cdp-target.ts` for a launcher that lacks it — and `page-over-target.ts`
- * exposes it as `ScrapePage.offline()`. All of that landed in **the same commit as the comment**
- * (#351), so the refusal was never true, and it is the reason issue #390 records a real browser
- * check as out of reach.
- *
- * Optional on `E2eBrowserPage` rather than required, for the reason `CdpPageLike` gives about the
- * same method: this port is the shape of somebody ELSE's object, and a six-line test double must
- * still satisfy it. Absent, the refusal stands — and now it names the method the double is missing
- * rather than a capability the framework does not have.
- */
-const networkFixtures = (browser: E2eBrowserPage): Pick<E2eFixtures, 'offline' | 'online'> => {
-  const setOffline = browser.offline?.bind(browser);
-  if (setOffline === undefined) {
-    const needs =
-      "a page whose driver implements offline(enabled) — @ultimat3/scraping's ScrapePage does; a hand-rolled E2eBrowserPage may not";
-    return { offline: refuse('offline', needs), online: refuse('online', needs) };
-  }
-  return { offline: () => setOffline(true), online: () => setOffline(false) };
-};
-
-/** What `e2eTest` hands its body: a real page, the network condition, and one honest refusal. */
-export const e2eFixtures = (
-  page: PageLike,
-  browser: E2eBrowserPage,
-  newBuild?: () => Promise<void>,
-): E2eFixtures => ({
-  page,
-  ...networkFixtures(browser),
-  // A new build id is a fact about the SERVER, which no page port can speak for — so it is
-  // forwarded when whoever spawned the app can restart it, and refused by name otherwise.
-  update:
-    newBuild ??
-    refuse(
-      'update',
-      'a second build served under a new immutable build id, which is a server fact',
-    ),
-});
-
-/**
- * Install the browser-backed driver for this process.
- *
- * Two seams, deliberately, because they are two questions. `defineFixtures({ page })` replaces the
- * declaration `driverFixtures()` registered — the ordinary way a driver arrives, last registration
- * wins — so every `test('…', async ({ page }) => …)` in the suite gets a browser. `useE2eDriver`
- * is the other half: it is what makes `hasE2eDriver()` answer true and stops `e2eTest` becoming a
- * `test.skip` — which the gate now reports as a SKIPPED step rather than the green check it
- * printed until #434, and which a repo whose `x.verify.json` names `e2e` gets red for.
- *
- * `budget` and `signIn` are deliberately NOT registered here, and `deploy` only with `newBuild`. Each needs something a
- * page cannot supply — byte counts off a built `dist/`, an app's own sign-in route, a second build
- * — so each keeps refusing with `X_TEST_FIXTURE_UNAVAILABLE` naming what it waits for.
- *
- * Returns the undo. `bun test` is one process, so a driver installed and never removed reaches
- * every later file in the run.
- */
-export function installE2eDriver(options: E2eDriverOptions): () => void {
-  const page = e2ePage(options);
-  const newBuild = options.newBuild;
-  defineFixtures({
-    page: () => page,
-    ...(newBuild === undefined ? {} : { deploy: () => ({ newBuild }) }),
-  });
-  useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page, options.page, newBuild)));
-  });
-  return () => {
-    // Both halves, because both were installed. Putting the DECLARATION back — rather than
-    // deleting the key — is what keeps a later file's `{ page }` failing as
-    // `X_TEST_FIXTURE_UNAVAILABLE` (a driver is missing) instead of `X_TEST_FIXTURE_UNKNOWN`
-    // (register it), which is the wrong instruction for a name the framework declares.
-    defineFixtures({
-      page: unavailableFixture('page'),
-      ...(newBuild === undefined ? {} : { deploy: unavailableFixture('deploy') }),
-    });
-    resetE2eDriver();
-  };
-}

package/src/e2e-errors.ts

@@ -1,117 +0,0 @@
-// One constructor per way the browser-backed e2e page refuses. Every cause below quotes a value
-// that came out of a BROWSER or out of a test's own `toString()`, so every one of them is
-// rendered rather than interpolated.
-
-import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
-import type { E2eSelection } from './e2e-selection';
-import { selectionCall } from './e2e-selection';
-
-/** A page URL is uncontrolled text; a fix line has to parse after one lands inside it. */
-const URL_PLACEHOLDER = '<the url the cause names>';
-
-/**
- * The closure never left the test process. `PageLike.evaluate` takes a function and CDP takes a
- * string, so the only thing that can cross is `Function.prototype.toString()` — and a function
- * with no readable source, or one expecting an argument nothing in the page will pass, has no
- * honest string form at all.
- */
-export class E2eEvaluateUnsupportedError extends UltimateError {
-  constructor(input: { readonly reason: string; readonly source: string }) {
-    super({
-      code: 'X_E2E_EVALUATE_UNSUPPORTED',
-      cause: `page.evaluate() was given a function that ${input.reason}: ${renderCauseValue(input.source)}`,
-      fix: 'page.evaluate(() => document.title)   # a zero-parameter arrow whose body names only page globals',
-    });
-  }
-}
-
-/**
- * The closure crossed and then named something the page has never heard of. This is the failure
- * the whole `evaluate` seam is built around: `const wanted = 3; page.evaluate(() => rows === wanted)`
- * sends the source, so the page receives the NAME `wanted` and a `ReferenceError`. Reported with
- * the binding's own name, because "it threw in the browser" sends the reader to the app.
- */
-export class E2eEvaluateCapturedError extends UltimateError {
-  constructor(input: { readonly binding: string; readonly source: string }) {
-    const binding = renderFixLiteral(input.binding, '<the binding the cause names>');
-    super({
-      code: 'X_E2E_EVALUATE_CAPTURED',
-      cause: `page.evaluate() ran ${renderCauseValue(input.source)} in the browser and ${renderCauseValue(input.binding)} is not defined there — a closure sends its source, never its scope`,
-      fix: `page.evaluate(() => document.querySelectorAll("script[src]").length)   # write the value into the closure literally; the page has no binding named ${binding}`,
-    });
-  }
-}
-
-/**
- * The expression ran and the PAGE threw — the app's own failure, not the driver's. Kept apart from
- * the two above so the reader is sent to the app rather than to the test's closure.
- */
-export class E2eEvaluateThrewError extends UltimateError {
-  constructor(input: { readonly thrown: string; readonly url: string }) {
-    super({
-      code: 'X_E2E_EVALUATE_THREW',
-      cause: `the expression page.evaluate() ran threw inside the browser: ${renderCauseValue(input.thrown)}`,
-      fix: `x dev — then open ${renderFixLiteral(input.url, URL_PLACEHOLDER)} and run the same expression in the console; the throw is the page's`,
-    });
-  }
-}
-
-/**
- * Nothing matched. The fix is the retrying assertion and not a longer sleep: `toBeVisible()` looks
- * again to a budget, while `click()` resolves the selection once — so a test that raced the render
- * is asserting in the wrong order rather than waiting for the wrong length of time.
- */
-export class E2eLocatorEmptyError extends UltimateError {
-  constructor(input: { readonly selection: E2eSelection; readonly url: string }) {
-    const call = selectionCall(input.selection);
-    super({
-      code: 'X_E2E_LOCATOR_EMPTY',
-      cause: `${call} matched no element on ${renderCauseValue(input.url)}`,
-      fix: `await expect(${call}).toBeVisible() before acting on it — that assertion retries to a budget, click() resolves once`,
-    });
-  }
-}
-
-/**
- * More than one matched and the caller asked to ACT. Never raised by `count()` or `isVisible()`:
- * an assertion handed an ambiguous locator has an answer, and refusing there would turn a question
- * into a crash. A click has no such answer — one of them is about to be pressed.
- */
-export class E2eLocatorAmbiguousError extends UltimateError {
-  constructor(input: { readonly selection: E2eSelection; readonly count: number }) {
-    const call = selectionCall(input.selection);
-    super({
-      code: 'X_E2E_LOCATOR_AMBIGUOUS',
-      cause: `${call} matched ${String(input.count)} elements and click() presses exactly one`,
-      fix: `${call}.first().click()   # or narrow the selection until it matches one element`,
-    });
-  }
-}
-
-/**
- * `waitForServiceWorker()` gave up. Bounded IN THE PAGE rather than here: an unbounded wait is a
- * 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 }) {
-    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`,
-    });
-  }
-}
-
-/**
- * The app an e2e run spawns (`e2e-app.ts`) did not come up: its reset, its seed, or its boot. The
- * cause carries that process's own output, rendered, because it is the only place the reason is.
- */
-export class E2eAppFailedError extends UltimateError {
-  constructor(input: { readonly step: string; readonly output: string }) {
-    super({
-      code: 'X_E2E_APP_FAILED',
-      cause: `${renderCauseValue(input.step)} failed for the e2e app: ${renderCauseValue(input.output)}`,
-      fix: 'x dev --json   # boot the same app by hand and read why it would not start; the e2e run used a throwaway ULTIMATE_STATE_DIR, so your own .x is untouched',
-    });
-  }
-}

package/src/e2e-evaluate.ts

@@ -1,156 +0,0 @@
-// The one crossing in this driver that cannot be lossless: `PageLike.evaluate` takes a CLOSURE and
-// every browser port in the framework takes a STRING. What is supported is stated here, what is
-// not is refused by name, and a page-side throw comes back as itself rather than as a driver fault.
-
-import { renderCauseValue, stringField } from '@ultimat3/core';
-import {
-  E2eEvaluateCapturedError,
-  E2eEvaluateThrewError,
-  E2eEvaluateUnsupportedError,
-} from './e2e-errors';
-
-/** Only what this driver needs from a page, so a test proves the crossing with two methods. */
-export interface EvaluablePage {
-  evaluate(expression: string): Promise<unknown>;
-  url(): string;
-}
-
-/**
- * A function with no source. `Function.prototype.toString` answers `[native code]` for a native
- * function and for anything `.bind()` produced, so there is nothing to send and the page would be
- * asked to evaluate a syntax error.
- */
-const NATIVE = /\{\s*\[native code\]\s*\}/;
-
-/**
- * The parameter list of an arrow or a function expression, as written. `PageLike.evaluate` declares
- * `() => T`, so a declared parameter is a value the author meant to pass and cannot: nothing in
- * the page will supply it, and it would silently arrive `undefined`.
- */
-const takesParameters = (source: string): boolean => {
-  const arrow = /^(?:async\s+)?\(([^)]*)\)\s*=>/.exec(source);
-  if (arrow !== null) return arrow[1]?.trim() !== '';
-  // `x => x * 2` — a single unparenthesised parameter, which is still a parameter.
-  if (/^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(source)) return true;
-  const fn = /^(?:async\s+)?function\s*\*?\s*[A-Za-z_$][\w$]*?\s*\(([^)]*)\)/.exec(source);
-  return fn !== null && fn[1]?.trim() !== '';
-};
-
-/**
- * Is the source a standalone expression at all? A method shorthand — what `{ evaluate() {} }.evaluate`
- * stringifies to — is `evaluate() { … }`, which is legal in an object literal and a syntax error
- * anywhere else. `new Function` is the parser, and it PARSES only: nothing is called here, so no
- * page code and no test code runs in this process.
- */
-const parses = (source: string): boolean => {
-  try {
-    new Function(`"use strict"; return (${source});`);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-/**
- * The static half. Everything it refuses is refused before a byte reaches the browser, because the
- * page's own answer for each of these would be a syntax error with the driver's wrapper in it.
- */
-export function closureSource(fn: (...args: never[]) => unknown): string {
-  const source = fn.toString();
-  if (NATIVE.test(source)) {
-    throw new E2eEvaluateUnsupportedError({
-      reason: 'is native or bound, so it has no source to send',
-      source,
-    });
-  }
-  if (takesParameters(source)) {
-    throw new E2eEvaluateUnsupportedError({
-      reason: 'declares a parameter, and nothing in the page will pass one',
-      source,
-    });
-  }
-  if (!parses(source)) {
-    throw new E2eEvaluateUnsupportedError({
-      reason: 'does not stringify to an expression the browser can parse',
-      source,
-    });
-  }
-  return source;
-}
-
-/**
- * The wrapper. It CATCHES in the page and answers a value, rather than letting the throw cross the
- * wire: `@ultimat3/scraping`'s `cdp-target.ts` wraps anything its `evaluate` rejects with as
- * `X_SCRAPE_BROWSER_UNREACHABLE`, so an app error that travelled as a rejection would arrive
- * labelled a dead socket.
- *
- * `Promise.resolve().then(…)` because the closure may be async and because a `ReferenceError` for
- * a captured binding is raised when the body RUNS, not when the arrow is built.
- */
-export const evaluateExpression = (source: string): string =>
-  `(() => { const fn = (${source});
-  return Promise.resolve().then(() => fn()).then(
-    (value) => JSON.stringify({ ok: true, value: value }),
-    (error) => JSON.stringify({ ok: false, name: String(error && error.name || 'Error'), message: String(error && error.message || error) }),
-  );
-})()`;
-
-/**
- * The envelope, read by hand rather than through a schema, and the reason is `value`: it is
- * whatever the test's own closure returned, so no schema in this package can describe it and a
- * `t.object` would strip the one field the caller came for. Everything the DRIVER reads — the
- * discriminant, the error name, the message — is read defensively through core's `stringField`,
- * which is total against a getter that throws.
- *
- * A malformed answer degrades into the failure branch instead of a branch of its own: the wrapper
- * below is the only writer, so anything else is a page that shadowed `JSON.stringify`, and the
- * reader needs to see what came back either way.
- */
-type Envelope =
-  | { readonly ok: true; readonly value: unknown }
-  | { readonly ok: false; readonly name: string; readonly message: string };
-
-const decode = (raw: unknown): unknown => {
-  if (typeof raw !== 'string') return raw;
-  try {
-    return JSON.parse(raw) as unknown;
-  } catch {
-    return raw;
-  }
-};
-
-const readEnvelope = (raw: unknown): Envelope => {
-  const decoded = decode(raw);
-  if (typeof decoded === 'object' && decoded !== null) {
-    const held = decoded as { readonly ok?: unknown; readonly value?: unknown };
-    if (held.ok === true) return { ok: true, value: held.value };
-    return {
-      ok: false,
-      name: stringField(decoded, 'name') ?? 'Error',
-      message: stringField(decoded, 'message') ?? renderCauseValue(raw),
-    };
-  }
-  return { ok: false, name: 'Error', message: renderCauseValue(raw) };
-};
-
-/** V8's wording for a free identifier. The name is the whole value of the refusal it produces. */
-const NOT_DEFINED = /^([A-Za-z_$][\w$]*) is not defined$/;
-
-/**
- * Run the closure in the page and hand back what it answered.
- *
- * The cast on the way out is the generic boundary and nothing more: `evaluate<T>` is the CALLER's
- * claim about what its own closure returns, and no schema in this process can check a claim the
- * browser was never told about. Everything the driver itself reads is read above.
- */
-export async function evaluateClosure<T>(page: EvaluablePage, fn: () => T): Promise<Awaited<T>> {
-  const source = closureSource(fn);
-  const envelope = readEnvelope(await page.evaluate(evaluateExpression(source)));
-  if (envelope.ok) return envelope.value as Awaited<T>;
-  const captured = envelope.name === 'ReferenceError' ? NOT_DEFINED.exec(envelope.message) : null;
-  if (captured !== null) throw new E2eEvaluateCapturedError({ binding: captured[1] ?? '', source });
-  throw new E2eEvaluateThrewError({
-    thrown: `${envelope.name}: ${envelope.message}`,
-    url: page.url(),
-  });
-}

package/src/e2e-locator.ts

@@ -1,86 +0,0 @@
-// `LocatorLike` over a browser page: a handle that holds a SELECTION and resolves nothing until
-// something asks. One round trip per question, and no waiting of its own — `toBeVisible()` owns
-// the only retry budget in the harness and drives this by looking again.
-
-import type { LocatorLike } from '@ultimat3/testing';
-import { E2eLocatorAmbiguousError, E2eLocatorEmptyError } from './e2e-errors';
-import type { E2eResolution, E2eSelection } from './e2e-selection';
-import { markSelector, selectionExpression, unmarkExpression } from './e2e-selection';
-
-/**
- * What a locator needs from the browser. Narrower than `ScrapePage` on purpose: three methods is
- * what a test has to stand up to prove the mapping, and `click` is taken from the page rather than
- * re-derived here so the actionability wait `@ultimat3/scraping` already performs is the one that
- * runs.
- */
-export interface LocatablePage {
-  evaluate(expression: string): Promise<unknown>;
-  click(selector: string): Promise<void>;
-  url(): string;
-}
-
-const readResolution = (raw: unknown): E2eResolution => {
-  const decoded = typeof raw === 'string' ? (JSON.parse(raw) as unknown) : raw;
-  const held = decoded as { count?: unknown; visible?: unknown; marked?: unknown };
-  return {
-    count: typeof held?.count === 'number' ? held.count : 0,
-    visible: held?.visible === true,
-    marked: held?.marked === true,
-  };
-};
-
-/**
- * One mark per click, never a constant: two locators marking the same page at once would each
- * click whichever element the other had just tagged. Seeded from a counter and not from
- * `Math.random()`, which `bun run flight-copies` refuses in shipped source and which would make
- * two runs of one test address two different elements.
- */
-let marks = 0;
-const nextMark = (): string => {
-  marks += 1;
-  return `m${String(marks)}`;
-};
-
-/** Test seam: the counter is process-global, so a test that asserts a mark resets it first. */
-export const resetLocatorMarks = (): void => {
-  marks = 0;
-};
-
-/**
- * Nothing is cached. A locator taken before a navigation must address the page that is there when
- * it is USED — the same rule `ScrapeFrame` states for a frame handle — so every method below
- * re-resolves, and a handle can never go stale behind the caller's back.
- */
-export function e2eLocator(page: LocatablePage, selection: E2eSelection): LocatorLike {
-  const resolve = async (mark?: string): Promise<E2eResolution> =>
-    readResolution(await page.evaluate(selectionExpression(selection, mark)));
-
-  return {
-    count: async () => (await resolve()).count,
-    /**
-     * A point-in-time look, and deliberately not an ambiguity check: an assertion handed a locator
-     * that matched three elements has an ANSWER — was the first one visible — and a refusal there
-     * would turn `expect(...).toBeVisible()` into a crash rather than a verdict. Only `click`
-     * refuses, because only `click` has to pick one.
-     */
-    isVisible: async () => (await resolve()).visible,
-    first: () => e2eLocator(page, { ...selection, first: true }),
-    click: async () => {
-      const mark = nextMark();
-      const resolution = await resolve(mark);
-      if (resolution.count === 0) {
-        throw new E2eLocatorEmptyError({ selection, url: page.url() });
-      }
-      if (resolution.count > 1 && !selection.first) {
-        throw new E2eLocatorAmbiguousError({ selection, count: resolution.count });
-      }
-      try {
-        await page.click(markSelector(mark));
-      } finally {
-        // Best effort, and never allowed to replace the click's own failure: a click that
-        // navigated took the whole document — attribute included — with it.
-        await page.evaluate(unmarkExpression(mark)).catch(() => undefined);
-      }
-    },
-  };
-}

package/src/e2e-page.ts

@@ -1,153 +0,0 @@
-// `PageLike` over a browser page. The adapter itself: `@ultimat3/testing` declares the surface an
-// e2e test drives and `@ultimat3/scraping` owns the only driver that can drive one, and neither
-// may import the other — so the join is here, in the one package allowed to know about both.
-
-import { finiteCount } from '@ultimat3/core';
-import type { LocatorLike, PageLike } from '@ultimat3/testing';
-import { E2eServiceWorkerAbsentError } from './e2e-errors';
-import { evaluateClosure } from './e2e-evaluate';
-import { e2eLocator } from './e2e-locator';
-import type { E2eSelection } from './e2e-selection';
-
-/**
- * What this adapter needs of a browser: four required members, every one of them on `ScrapePage`.
- * Declared structurally rather than as `ScrapePage` so a test can stand one up in six lines — the
- * same bargain `cdp-port.ts` makes about puppeteer, one layer up.
- */
-export interface E2eBrowserPage {
-  url(): string;
-  goto(url: string, options?: { readonly timeout?: number | undefined }): Promise<unknown>;
-  evaluate(expression: string): Promise<unknown>;
-  click(selector: string): Promise<void>;
-  /**
-   * The browser's own network condition, which `E2eFixtures.offline()`/`online()` forward to.
-   * `ScrapePage` has it (`page-over-target.ts`), reaching `CdpPageLike.setOfflineMode` through
-   * `cdp-target.ts`'s guard.
-   *
-   * OPTIONAL for the reason the four above are structural: this port is the shape of somebody
-   * ELSE's object, and requiring it would cost every six-line double a type error for a capability
-   * a test that never goes offline does not need. Absent, `e2e-driver.ts` keeps refusing by name —
-   * a coded refusal, never a silent no-op, because an `offline()` that did nothing would let the
-   * app's ONLINE page pass an offline test.
-   */
-  offline?(enabled: boolean): Promise<void>;
-}
-
-export interface E2ePageOptions {
-  readonly page: E2eBrowserPage;
-  /** Every `goto('/feed')` in an e2e suite is app-relative; this is what makes one absolute. */
-  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. */
-  readonly serviceWorkerTimeoutMs?: number | undefined;
-}
-
-/** Named once, so both refusals below name the call an app's test preload actually makes. */
-const SUBJECT = 'installE2eDriver';
-
-export const DEFAULT_E2E_TIMEOUT_MS = 30_000;
-export const DEFAULT_SERVICE_WORKER_TIMEOUT_MS = 10_000;
-
-/** Every in-page expression here answers JSON text, for the reason `cdp-snapshot.ts` states. */
-const readField = (raw: unknown, key: string): unknown => {
-  const decoded = typeof raw === 'string' ? (JSON.parse(raw) as unknown) : raw;
-  return typeof decoded === 'object' && decoded !== null
-    ? (decoded as Record<string, unknown>)[key]
-    : undefined;
-};
-
-const TITLE = '(() => JSON.stringify({ title: document.title }))()';
-
-/**
- * The first flush, read by a `fetch` INSIDE the page after the navigation, because neither
- * `ScrapePage` nor `CdpPageLike` exposes a response body — puppeteer's `page.on('response')` is
- * not on the port and adding it would be an edit to `@ultimat3/scraping`.
- *
- * The cost, stated rather than hidden: this is a SECOND request to the same route, so what it
- * measures is that route's streaming behaviour and not the byte-for-byte first chunk the open
- * document received. It runs in the page, so it carries the page's cookies and its origin — a
- * `fetch` from the test process would carry neither. The reader is CANCELLED after that chunk: a
- * streamed response nobody pulls stays open until its last hole fills, holding one of the page's
- * six connections to its origin for the rest of the test.
- */
-const firstFlushExpression = (url: string): string =>
-  `(() => fetch(${JSON.stringify(url)}, { credentials: 'same-origin' })
-    .then((response) => { const reader = response.body.getReader(); return reader.read()
-      .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.
- */
-export function e2ePage(options: E2ePageOptions): PageLike {
-  const page = options.page;
-  // Both are screened HERE, at construction, and not where they land: `timeout` is handed to a
-  // driver that reads it as a deadline, and `swTimeout` is INTERPOLATED into the in-page source,
-  // where `setTimeout(fn, NaN)` is `setTimeout(fn, 0)` — so a NaN budget makes every
-  // `waitForServiceWorker()` refuse a worker that really did take control. A misdiagnosis reported
-  // as a test failure is worse than the failure. Floor 0, because a driver reads `timeout: 0` as
-  // "no deadline" and that is a value an app is entitled to declare.
-  const timeout = finiteCount(SUBJECT, 'timeoutMs', options.timeoutMs ?? DEFAULT_E2E_TIMEOUT_MS);
-  const swTimeout = finiteCount(
-    SUBJECT,
-    'serviceWorkerTimeoutMs',
-    options.serviceWorkerTimeoutMs ?? DEFAULT_SERVICE_WORKER_TIMEOUT_MS,
-  );
-  const absolute = (url: string): string => new URL(url, options.baseUrl).toString();
-  const locate = (selection: E2eSelection): LocatorLike => e2eLocator(page, selection);
-
-  return {
-    url: () => page.url(),
-    goto: (url) => page.goto(absolute(url), { timeout }),
-    // The page's OWN url, re-read at call time: a reload of the url the adapter was built with
-    // would navigate away from wherever the test had got to.
-    reload: () => page.goto(page.url(), { timeout }),
-    title: async () => {
-      const title = readField(await page.evaluate(TITLE), 'title');
-      return typeof title === 'string' ? title : '';
-    },
-    gotoStreamed: async (url) => {
-      const target = absolute(url);
-      await page.goto(target, { timeout });
-      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 });
-      }
-    },
-    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) =>
-      locate({
-        kind: 'role',
-        role,
-        first: false,
-        ...(roleOptions?.name === undefined ? {} : { name: roleOptions.name }),
-        ...(roleOptions?.level === undefined ? {} : { level: roleOptions.level }),
-      }),
-    getByText: (text) => locate({ kind: 'text', text, first: false }),
-  };
-}