@ultimat3/cli 12.0.0 → 14.0.0

package/src/e2e-dom-fixture.ts

@@ -0,0 +1,117 @@
+// 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

@@ -0,0 +1,78 @@
+// 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 { E2ePageOptions } from './e2e-page';
+import { e2ePage } from './e2e-page';
+
+export type E2eDriverOptions = E2ePageOptions;
+
+/**
+ * The three `E2eFixtures` members this driver cannot build, and why each is a REFUSAL rather than
+ * 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.
+ *
+ * All three are genuinely out of reach of the shipped port, not merely unimplemented:
+ * `CdpPageLike` (`packages/scraping/src/cdp-port.ts`) declares twelve methods and none of them is
+ * `setOfflineMode`, and a new build id is a fact about the SERVER, which no page port has ever
+ * been able to speak for.
+ */
+const refuse =
+  (name: string, needs: string): (() => Promise<void>) =>
+  () =>
+    Promise.reject(new FixtureUnavailableError({ name, needs }));
+
+/** What `e2eTest` hands its body: a real page, and three members that say what they are missing. */
+export const e2eFixtures = (page: PageLike): E2eFixtures => ({
+  page,
+  offline: refuse(
+    'offline',
+    "a CDP method for the browser's own network state — the shipped CdpPageLike has no setOfflineMode",
+  ),
+  online: refuse('online', 'the same CDP method offline() needs, in order to undo it'),
+  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` a green gate reports over.
+ *
+ * `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)));
+  });
+  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

@@ -0,0 +1,103 @@
+// 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

@@ -0,0 +1,156 @@
+// 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

@@ -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 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

@@ -0,0 +1,124 @@
+// `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 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 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>;
+}
+
+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;
+}
+
+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.
+ */
+const firstFlushExpression = (url: string): string =>
+  `(() => fetch(${JSON.stringify(url)}, { credentials: 'same-origin' })
+    .then((response) => response.body.getReader().read())
+    .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;
+  const timeout = options.timeoutMs ?? DEFAULT_E2E_TIMEOUT_MS;
+  const swTimeout = 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 }),
+  };
+}