@ultimat3/cli 20.2.1 → 22.0.0

package/src/cdp-launch.ts

@@ -1,139 +0,0 @@
-// 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`.
-
-// 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 { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
-
-/**
- * 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**.
- */
-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',
-];
-
-/** The first candidate that exists, or `undefined`. An absent browser is a SKIP, never a failure. */
-export async function findChrome(
-  env: Readonly<Record<string, string | undefined>>,
-): Promise<string | undefined> {
-  const declared = env[CHROME_PATH_ENV];
-  const candidates = declared === undefined || declared === '' ? CHROME_CANDIDATES : [declared];
-  for (const candidate of candidates) {
-    if (await Bun.file(candidate).exists()) return candidate;
-  }
-  return undefined;
-}
-
-/**
- * The two flags a CONTAINER needs, regardless of which process launches Chrome: the sandbox needs
- * privileges CI (and an Ubuntu 23.10+ host with AppArmor's unprivileged-user-namespace restriction
- * — Chrome exits "No usable sandbox" there with neither) does not grant, and `/dev/shm` is 64 MB in
- * a default container, which crashes the renderer on any real page.
- *
- * Exported so `browser-launcher.ts`'s `appBrowser` — a DIFFERENT launch path, `puppeteer-core`'s
- * own `launch()` rather than the `Bun.spawn` below — passes the SAME two, rather than a second
- * list that agrees today and drifts the next time either changes. `x shot` had neither before this
- * export existed, so a box where `x verify`'s e2e gate ran green could not run `x shot` at all.
- */
-export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disable-dev-shm-usage'];
-
-/**
- * The flags, and every one of them earns its line.
- *
- * `--headless=new` is Chrome's own headless rather than the retired shim. `--remote-debugging-port=0`
- * asks the OS for a free port, so two suites on one machine never collide — the port is read back
- * off stderr, which is the only place Chrome states the one it took. A throwaway `--user-data-dir`
- * because a run sharing a profile with a real browser inherits its cookies and locks its files.
- */
-const flags = (profileDir: string): readonly string[] => [
-  '--headless=new',
-  '--remote-debugging-port=0',
-  `--user-data-dir=${profileDir}`,
-  ...CONTAINER_CHROME_ARGS,
-  '--disable-gpu',
-  // Nothing here should reach the network on its own account, and a first-run bubble or an update
-  // check is a page load the test did not ask for.
-  '--no-first-run',
-  '--no-default-browser-check',
-  '--disable-extensions',
-  'about:blank',
-];
-
-const ENDPOINT = /DevTools listening on (ws:\/\/\S+)/;
-
-export interface LaunchedBrowser {
-  readonly endpoint: string;
-  /** Idempotent: killing a dead process and deleting a gone directory are both no-ops. */
-  close(): void;
-}
-
-export interface LaunchOptions {
-  readonly executable: string;
-  /** How long Chrome has to announce its endpoint before this gives up and kills it. */
-  readonly timeoutMs: number;
-}
-
-/**
- * Chrome announces `DevTools listening on ws://…` on **stderr**, once, before it is usable. Reading
- * it there rather than polling `/json/version` is what makes `--remote-debugging-port=0` safe: with
- * a random port there is no URL to poll until Chrome has said which one it took.
- */
-export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrowser> {
-  const profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
-  const child = Bun.spawn([options.executable, ...flags(profileDir)], {
-    stderr: 'pipe',
-    stdout: 'ignore',
-  });
-  const close = (): void => {
-    child.kill();
-    rmSync(profileDir, { recursive: true, force: true });
-  };
-
-  const reader = (child.stderr as ReadableStream<Uint8Array>).getReader();
-  const decoder = new TextDecoder();
-  let seen = '';
-  const deadline = Bun.nanoseconds() + options.timeoutMs * 1_000_000;
-  try {
-    while (Bun.nanoseconds() < deadline) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      seen += decoder.decode(value, { stream: true });
-      const found = ENDPOINT.exec(seen);
-      if (found?.[1] !== undefined) return { endpoint: found[1], close };
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  close();
-  // Chrome's own stderr is the actionable half — a missing library, a sandbox refusal, a bad flag
-  // are all named there — so it is reported rather than "the launch failed".
-  throw new CdpLaunchFailedError({
-    executable: options.executable,
-    detail:
-      seen.trim() === ''
-        ? 'it printed nothing before the deadline'
-        : seen.trim().split('\n').slice(-3).join(' | '),
-  });
-}
-
-/** `findChrome` then `launchChrome`. Refuses by name when there is no browser to drive. */
-export async function launchFoundChrome(
-  env: Readonly<Record<string, string | undefined>>,
-  timeoutMs: number,
-): Promise<LaunchedBrowser> {
-  const executable = await findChrome(env);
-  if (executable === undefined) throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
-  return launchChrome({ executable, timeoutMs });
-}

package/src/e2e-dom-fixture.ts

@@ -1,117 +0,0 @@
-// A document small enough to hold in a test and real enough to RUN the driver's own in-page
-// expressions. Without it every claim about `getByRole` and `getByText` would be an assertion
-// about a string, and a string that never executes cannot be wrong about a page.
-//
-// Its own file, the pattern `dev-roles-fixture.ts` and `policy-fixture.ts` already set here.
-
-/** One element. `attrs` is data, so every read of it goes through `Object.hasOwn` below. */
-export interface FakeE2eElement {
-  readonly tag: string;
-  readonly attrs: Readonly<Record<string, string>>;
-  readonly text?: string;
-  readonly children?: readonly FakeE2eElement[];
-  /** What `getComputedStyle` answers. Absent is the browser's own default — visible. */
-  readonly style?: { display?: string; visibility?: string; opacity?: string };
-}
-
-interface Node {
-  tagName: string;
-  textContent: string;
-  readonly attributes: Record<string, string>;
-  readonly descendants: Node[];
-  readonly style: { display: string; visibility: string; opacity: string };
-  getAttribute(name: string): string | null;
-  setAttribute(name: string, value: string): void;
-  removeAttribute(name: string): void;
-  contains(other: Node): boolean;
-}
-
-const textOf = (element: FakeE2eElement): string =>
-  [element.text ?? '', ...(element.children ?? []).map(textOf)]
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-function build(element: FakeE2eElement): Node {
-  const attributes: Record<string, string> = { ...element.attrs };
-  const children = (element.children ?? []).map(build);
-  const descendants = children.flatMap((child) => [child, ...child.descendants]);
-  const node: Node = {
-    tagName: element.tag.toUpperCase(),
-    textContent: textOf(element),
-    attributes,
-    descendants,
-    style: {
-      display: element.style?.display ?? 'block',
-      visibility: element.style?.visibility ?? 'visible',
-      opacity: element.style?.opacity ?? '1',
-    },
-    getAttribute: (name) => (Object.hasOwn(attributes, name) ? (attributes[name] as string) : null),
-    setAttribute: (name, value) => {
-      attributes[name] = value;
-    },
-    removeAttribute: (name) => {
-      delete attributes[name];
-    },
-    contains: (other) => descendants.includes(other),
-  };
-  return node;
-}
-
-/** `tag`, `*`, `[attr]`, `[attr="value"]` and any combination — every shape this driver emits. */
-const SIMPLE = /^([a-zA-Z0-9*]*)((?:\[[^\]]*\])*)$/;
-
-function matchesSimple(node: Node, selector: string): boolean {
-  const parsed = SIMPLE.exec(selector.trim());
-  if (parsed === null) return false;
-  const tag = parsed[1] ?? '';
-  if (tag !== '' && tag !== '*' && tag.toUpperCase() !== node.tagName) return false;
-  for (const clause of (parsed[2] ?? '').matchAll(/\[([^\]=]+)(?:=("[^"]*"|[^\]]*))?\]/g)) {
-    const name = (clause[1] ?? '').trim();
-    const held = node.getAttribute(name);
-    if (held === null) return false;
-    const raw = clause[2];
-    if (raw !== undefined && held !== raw.replace(/^"|"$/g, '')) return false;
-  }
-  return true;
-}
-
-const matches = (node: Node, selector: string): boolean =>
-  selector.split(',').some((part) => part.trim() !== '' && matchesSimple(node, part));
-
-/**
- * The globals a driver expression names, bound to one tree. `getComputedStyle` and `document` are
- * handed in as arguments rather than assigned to `globalThis`: a test that installed a fake
- * `document` on the process would leak it into every later file in the run.
- */
-export function fakeE2eDocument(root: FakeE2eElement): Readonly<Record<string, unknown>> {
-  const rootNode = build(root);
-  const all = [rootNode, ...rootNode.descendants];
-  return {
-    document: {
-      querySelectorAll: (selector: string): Node[] => all.filter((node) => matches(node, selector)),
-      querySelector: (selector: string): Node | null =>
-        all.find((node) => matches(node, selector)) ?? null,
-      getElementById: (id: string): Node | null =>
-        all.find((node) => node.getAttribute('id') === id) ?? null,
-    },
-    getComputedStyle: (node: Node) => node.style,
-  };
-}
-
-/**
- * Run an expression the driver built, in THIS process, against a stubbed global scope.
- *
- * `new Function` and not `eval`: the body evaluates with no access to this module's scope, so a
- * name the expression does not receive as a parameter is genuinely free — which is exactly the
- * `ReferenceError` a captured closure produces in a real browser, and the thing the evaluate
- * wrapper has to be proved against.
- */
-export async function runInFakePage(
-  expression: string,
-  globals: Readonly<Record<string, unknown>> = {},
-): Promise<unknown> {
-  const names = Object.keys(globals);
-  const body = new Function(...names, `return (${expression});`) as (...args: unknown[]) => unknown;
-  return await body(...names.map((name) => globals[name]));
-}

package/src/e2e-driver.ts

@@ -1,97 +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 type E2eDriverOptions = E2ePageOptions;
-
-/**
- * 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): E2eFixtures => ({
-  page,
-  ...networkFixtures(browser),
-  // The one that is still genuinely out of reach, and it is not a port gap: a new build id is a
-  // fact about the SERVER, which no page port has ever been able to speak for.
-  update: 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`, `signIn` and `deploy` are deliberately NOT registered here. 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);
-  defineFixtures({ page: () => page });
-  useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page, options.page)));
-  });
-  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') });
-    resetE2eDriver();
-  };
-}

package/src/e2e-errors.ts

@@ -1,103 +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`,
-    });
-  }
-}

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(),
-  });
-}