@ultimat3/testing 20.2.1 → 22.0.0

package/src/e2e-dom-fixture.ts

@@ -0,0 +1,122 @@
+// 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"]`, a trailing `:not([attr])` and any combination — every
+ * shape this driver emits (`input:not([type])` is the textbox role's untyped input).
+ */
+const SIMPLE = /^([a-zA-Z0-9*]*)((?:\[[^\]]*\])*)(?::not\(\[([^\]=]+)\]\))?$/;
+
+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;
+  const absent = parsed[3]?.trim();
+  if (absent !== undefined && node.getAttribute(absent) !== null) 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

@@ -0,0 +1,114 @@
+// 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 { E2eBrowserPage, E2ePageOptions } from './e2e-page';
+import { e2ePage } from './e2e-page';
+import { FixtureUnavailableError } from './errors';
+import { unavailableFixture } from './fixture-drivers';
+import { defineFixtures } from './fixtures';
+import type { E2eBody, E2eFixtures, PageLike } from './test-types';
+import { resetE2eDriver, useE2eDriver } from './test-types';
+
+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-error-codes.ts

@@ -0,0 +1,42 @@
+// The registry for the browser-backed e2e driver's codes: the seven `X_E2E_*` a page refuses with
+// and the four `X_CDP_*` its raw-CDP browser refuses with. Registered here, not in `errors.ts`,
+// because that catalogue sits at its ceiling; anchored by the barrel and by both constructor files.
+import { registerErrorCodes } from '@ultimat3/core';
+
+export const E2E_ERROR_CODES = [
+  'X_E2E_EVALUATE_UNSUPPORTED',
+  'X_E2E_EVALUATE_CAPTURED',
+  'X_E2E_EVALUATE_THREW',
+  'X_E2E_LOCATOR_EMPTY',
+  'X_E2E_LOCATOR_AMBIGUOUS',
+  'X_E2E_SERVICE_WORKER_ABSENT',
+  'X_E2E_APP_FAILED',
+  // Four and not one, because the four repairs differ: install a browser, read the browser's own
+  // stderr, look at the page, raise a deadline.
+  'X_CDP_BROWSER_MISSING',
+  'X_CDP_LAUNCH_FAILED',
+  'X_CDP_CALL_FAILED',
+  'X_CDP_TIMEOUT',
+] as const;
+
+export type E2eErrorCode = (typeof E2E_ERROR_CODES)[number];
+
+export const E2E_ERROR_TITLES = Object.freeze<Record<E2eErrorCode, string>>({
+  X_E2E_EVALUATE_UNSUPPORTED: 'a page.evaluate() closure cannot be sent into the browser',
+  X_E2E_EVALUATE_CAPTURED: 'a page.evaluate() closure named a binding the page does not have',
+  X_E2E_EVALUATE_THREW: 'an expression an e2e page ran threw inside the browser',
+  X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
+  X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
+  X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
+  X_E2E_APP_FAILED: 'the app an e2e run spawned did not come up',
+  X_CDP_BROWSER_MISSING: 'no Chrome or Chromium is installed for the e2e driver to launch',
+  X_CDP_LAUNCH_FAILED: 'the browser started and never announced a DevTools endpoint',
+  X_CDP_CALL_FAILED: 'the browser refused a DevTools call',
+  X_CDP_TIMEOUT: 'a DevTools call did not answer inside its deadline',
+});
+
+// Owned here and borrowed by nobody, so unconditional: a second package claiming one must fail as
+// X_ERROR_CODE_DUPLICATE rather than quietly keep whichever title registered first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(E2E_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);

package/src/e2e-errors.ts

@@ -0,0 +1,126 @@
+// 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';
+// Bare: the titles these constructors' codes render with are registered there.
+import './e2e-error-codes';
+
+/** 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;
+    /** A literal, for the one step `x dev` cannot diagnose: there being no `x` to run. */
+    readonly fix?: string | undefined;
+  }) {
+    super({
+      code: 'X_E2E_APP_FAILED',
+      cause: `${renderCauseValue(input.step)} failed for the e2e app: ${renderCauseValue(input.output)}`,
+      fix:
+        input.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

@@ -0,0 +1,157 @@
+// 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;
+  // The name is OPTIONAL: an anonymous `function (rows)` read as taking nothing without it.
+  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

@@ -0,0 +1,86 @@
+// `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 { E2eLocatorAmbiguousError, E2eLocatorEmptyError } from './e2e-errors';
+import type { E2eResolution, E2eSelection } from './e2e-selection';
+import { markSelector, selectionExpression, unmarkExpression } from './e2e-selection';
+import type { LocatorLike } from './test-types';
+
+/**
+ * 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);
+      }
+    },
+  };
+}