@ultimat3/scraping 20.1.5 → 20.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "20.1.5",
+  "version": "20.2.0",
   "description": "Browser automation as a job: scrape() returns a JobHandle",
   "license": "MIT",
   "type": "module",
@@ -30,9 +30,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.1.5",
-    "@ultimat3/jobs": "20.1.5",
-    "@ultimat3/schema": "20.1.5",
-    "@ultimat3/storage": "20.1.5"
+    "@ultimat3/core": "20.2.0",
+    "@ultimat3/jobs": "20.2.0",
+    "@ultimat3/schema": "20.2.0",
+    "@ultimat3/storage": "20.2.0"
   }
 }

package/src/cdp-a11y.ts

@@ -0,0 +1,125 @@
+// The accessibility tree, read over a raw CDP session — the one read in this package the browser
+// library has no page method for, and the one no HTML parse can reproduce: `role` and `name` here
+// are what the BROWSER computed for a screen reader, after ARIA, after the label association,
+// after `aria-hidden` pruned the subtree. A `<div onclick>` answers no role and no name, which is
+// the finding; a fake reading `role=` off the markup would answer the attribute and miss it.
+//
+// Four protocol calls per read, each parsed with a schema and never cast: the answers are
+// somebody else's wire shapes, and a build that renames a field must refuse loudly
+// (`X_VALIDATION_FAILED`, which `cdp-target.ts`'s `guard()` passes through unlabelled).
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { parse, t } from '@ultimat3/schema';
+import type { CdpSessionLike } from './cdp-port';
+import type { AxNode } from './target';
+
+const anyString = t.string.min(0);
+
+/**
+ * CDP's `AXValue`: `{ type, value, … }`, where `value` is typed `any` on the wire. A role and a
+ * name are strings; a `value` may be a number (a slider) or a boolean (a checkbox), so every
+ * scalar is accepted and rendered to text — `AxNode.value` is what a reader is TOLD, and a reader
+ * is told text.
+ */
+const axValueSchema = t.object({
+  value: t.optional(t.union(anyString, t.number, t.boolean)),
+});
+
+const axPropertySchema = t.object({
+  name: t.string,
+  value: axValueSchema,
+});
+
+const axNodeSchema = t.object({
+  ignored: t.boolean,
+  role: t.optional(axValueSchema),
+  name: t.optional(axValueSchema),
+  description: t.optional(axValueSchema),
+  value: t.optional(axValueSchema),
+  properties: t.optional(t.array(axPropertySchema)),
+});
+
+const documentSchema = t.object({ root: t.object({ nodeId: t.number }) });
+const nodeIdsSchema = t.object({ nodeIds: t.array(t.number) });
+const describedSchema = t.object({ node: t.object({ backendNodeId: t.number }) });
+const partialTreeSchema = t.object({ nodes: t.array(axNodeSchema) });
+
+type ParsedAxValue = { readonly value?: string | number | boolean | undefined };
+type ParsedAxNode = {
+  readonly ignored: boolean;
+  readonly role?: ParsedAxValue | undefined;
+  readonly name?: ParsedAxValue | undefined;
+  readonly description?: ParsedAxValue | undefined;
+  readonly value?: ParsedAxValue | undefined;
+  readonly properties?: readonly { readonly name: string; readonly value: ParsedAxValue }[];
+};
+
+const textOf = (wrapped: ParsedAxValue | undefined): string | undefined =>
+  wrapped?.value === undefined ? undefined : String(wrapped.value);
+
+const flagOf = (node: ParsedAxNode, name: string): boolean | undefined => {
+  const found = node.properties?.find((property) => property.name === name);
+  return found === undefined ? undefined : found.value.value === true;
+};
+
+/**
+ * `nodes[0]` is the node for the element itself when `fetchRelatives` is false — CDP answers a
+ * list because the same command can walk ancestors. An EMPTY list is a real answer too: an element
+ * that never entered the tree at all (a `<template>`, a detached subtree), which is recorded as
+ * ignored with nothing computed, rather than dropped, so the count the caller gets is the count of
+ * matches and not the count of nodes the browser deigned to describe.
+ */
+const toAxNode = (raw: unknown): AxNode => {
+  const nodes = parse(
+    partialTreeSchema as unknown as StandardSchemaV1<unknown, { nodes: ParsedAxNode[] }>,
+    raw,
+  ).nodes;
+  const node = nodes[0];
+  if (node === undefined) return { role: '', name: '', ignored: true };
+  const description = textOf(node.description);
+  const value = textOf(node.value);
+  const focused = flagOf(node, 'focused');
+  const disabled = flagOf(node, 'disabled');
+  return {
+    role: textOf(node.role) ?? '',
+    name: textOf(node.name) ?? '',
+    ...(description === undefined ? {} : { description }),
+    ...(value === undefined ? {} : { value }),
+    ...(focused === undefined ? {} : { focused }),
+    ...(disabled === undefined ? {} : { disabled }),
+    ignored: node.ignored,
+  };
+};
+
+/**
+ * The accessibility node of every element `selector` matches, in document order, at most `max`.
+ *
+ * The session is the CALLER's: `cdp-target.ts` creates it and detaches it in a `finally`, so a
+ * throw from any of the four calls — a selector the browser refuses, a build whose answer does
+ * not parse — never leaves a session attached behind the page. `max` is screened by the caller
+ * too (`finiteCount`); here it is only a bound on the per-node round trips.
+ */
+export async function axNodesFor(
+  session: CdpSessionLike,
+  selector: string,
+  max: number,
+): Promise<readonly AxNode[]> {
+  const document = parse(documentSchema, await session.send('DOM.getDocument', { depth: 0 }));
+  const { nodeIds } = parse(
+    nodeIdsSchema,
+    await session.send('DOM.querySelectorAll', { nodeId: document.root.nodeId, selector }),
+  );
+  const out: AxNode[] = [];
+  for (const nodeId of nodeIds.slice(0, max)) {
+    const { node } = parse(describedSchema, await session.send('DOM.describeNode', { nodeId }));
+    out.push(
+      toAxNode(
+        await session.send('Accessibility.getPartialAXTree', {
+          backendNodeId: node.backendNodeId,
+          fetchRelatives: false,
+        }),
+      ),
+    );
+  }
+  return out;
+}

package/src/cdp-arm.ts

@@ -0,0 +1,173 @@
+// Everything `cdpTarget()` arms on the page BEFORE its first navigation, plus the readers that
+// turn the library's `unknown` event payloads into ring entries. Split out of `cdp-target.ts` on
+// 2026-09-19 for one reason: that file stood at 478 lines against the 500-line ceiling, and the
+// three verbs `press`/`focus`/`accessibility` did not fit under it. The extraction is VERBATIM —
+// the request, console, `pageerror` and `error` handlers are the same code, one file over.
+
+import type { CdpPageLike, CdpRequestLike } from './cdp-port';
+import type { ScrapeClock } from './clock';
+import type { InterceptRules } from './intercept';
+import { interceptVerdict, refusalEntry } from './intercept';
+import type {
+  ConsoleLine,
+  ConsoleRing,
+  NetworkRing,
+  PageError,
+  PageErrorRing,
+  ResourceType,
+} from './rings';
+import { pageErrorEntry, RESOURCE_TYPES } from './rings';
+
+/** What `arm()` reads: the page it subscribes to, the rules it judges by, the clock it stamps with. */
+export interface CdpArmInit {
+  readonly page: CdpPageLike;
+  readonly rules: InterceptRules;
+  readonly clock: ScrapeClock;
+}
+
+const asResourceType = (raw: string): ResourceType =>
+  (RESOURCE_TYPES as readonly string[]).includes(raw) ? (raw as ResourceType) : 'other';
+
+/** The library's event payloads are `unknown` here — read structurally, never cast. */
+const asRequest = (payload: unknown): CdpRequestLike | undefined => {
+  if (typeof payload !== 'object' || payload === null) return undefined;
+  const candidate = payload as Partial<CdpRequestLike>;
+  return typeof candidate.url === 'function' && typeof candidate.abort === 'function'
+    ? (candidate as CdpRequestLike)
+    : undefined;
+};
+
+/**
+ * CDP's console levels, mapped onto this package's five. `warning` is the library's spelling of
+ * `warn`, `verbose` of `debug`, and everything structural (`table`, `startGroup`, `dir`) is a log
+ * line with a shape — never its own level, because `ConsoleLine.level` is what an author filters on.
+ */
+const CONSOLE_LEVELS: Readonly<Record<string, ConsoleLine['level']>> = {
+  error: 'error',
+  assert: 'error',
+  warning: 'warn',
+  warn: 'warn',
+  info: 'info',
+  debug: 'debug',
+  verbose: 'debug',
+};
+
+/**
+ * `Object.hasOwn`, never the read alone: the type word arrives off the WIRE, so
+ * `CONSOLE_LEVELS['__proto__']` answered `Object.prototype` and `['constructor']` the `Object`
+ * function — neither of which a `?? 'log'` fallback can rescue, because neither is `undefined`.
+ * `ConsoleLine.level` would then hold a value its own type says is one of five words, so the
+ * `level === 'error'` filter this ring exists for matched nothing and `JSON.stringify` dropped
+ * the field from a snapshot outright. Lowercasing is not the guard: `__proto__` and `constructor`
+ * are already lowercase. Same discriminator as `packages/flags/src/subject.ts`.
+ */
+const consoleLevel = (type: string): ConsoleLine['level'] => {
+  const word = type.toLowerCase();
+  return Object.hasOwn(CONSOLE_LEVELS, word) ? (CONSOLE_LEVELS[word] ?? 'log') : 'log';
+};
+
+/**
+ * Reads a string out of somebody else's event payload, calling an accessor THROUGH ITS OWNER.
+ *
+ * `HTTPRequest.method()` and `ConsoleMessage.type()`/`.text()` read `this` — they are methods on
+ * the library's own objects, not closures over a value. Handing the bare function to a helper
+ * (`readString(request.method)`) drops the receiver, so the accessor answers against `undefined`:
+ * on one build that throws inside the interception handler, on another it answers wrong.
+ */
+const readStringFrom = (owner: unknown, key: string): string | undefined => {
+  if (typeof owner !== 'object' || owner === null) return undefined;
+  const value = (owner as Record<string, unknown>)[key];
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'function') return undefined;
+  const answer = (value as (this: unknown) => unknown).call(owner);
+  return typeof answer === 'string' ? answer : undefined;
+};
+
+/**
+ * A `pageerror` payload, read defensively — never cast, and never assumed to be an `Error`.
+ *
+ * `readStringFrom`, the same reader the console handler uses, because the payload has the same
+ * problem: `message` and `stack` are an own property on one build and an accessor on another, and
+ * a schema parse cannot call an accessor. A page can also `throw 'a string'` or throw a frozen
+ * object with no `message` at all — both reach here, and both are recorded as SOMETHING having
+ * thrown, because an entry with a poor message is still the difference between "the island threw"
+ * and silence.
+ */
+const readPageError = (payload: unknown, at: number): PageError => {
+  if (typeof payload === 'string') return pageErrorEntry({ message: payload, at });
+  return pageErrorEntry({
+    message: readStringFrom(payload, 'message') ?? '',
+    stack: readStringFrom(payload, 'stack'),
+    at,
+  });
+};
+
+/**
+ * Everything `arm()` writes into. Named rather than positional: three rings of near-identical
+ * type plus a latch is a call site nobody can read, and swapping two of them is a mistake the
+ * compiler cannot catch.
+ */
+export interface CdpSinks {
+  readonly network: NetworkRing;
+  readonly console: ConsoleRing;
+  readonly pageErrors: PageErrorRing;
+  readonly crashed: { value: string | undefined };
+}
+
+/**
+ * Interception is armed BEFORE the first navigation and refuses at the request, not after the
+ * response — an `allowHosts` that reported afterwards would be a log line about bytes that
+ * already left the container.
+ */
+export async function arm(init: CdpArmInit, sinks: CdpSinks): Promise<void> {
+  const { network, console: console_, pageErrors, crashed } = sinks;
+  await init.page.setRequestInterception(true);
+  init.page.on('request', (payload) => {
+    const request = asRequest(payload);
+    if (request === undefined) return;
+    const url = request.url();
+    const type = asResourceType(request.resourceType());
+    // The METHOD the browser is actually sending. Recording every request as a GET made
+    // `page.network()` — which `X_SCRAPE_HTTP_FAILED`'s own fix line tells the reader to open —
+    // misreport every POST and PUT the page made.
+    const method = readStringFrom(request, 'method') ?? 'GET';
+    const verdict = interceptVerdict(url, type, init.rules);
+    const at = init.clock.now().getTime();
+    if (verdict === 'allow') {
+      network.push({ method, url, resourceType: type, at });
+      void request.continue();
+      return;
+    }
+    network.push(refusalEntry(url, type, verdict, at, method));
+    void request.abort();
+  });
+  init.page.on('console', (payload) => {
+    console_.push({
+      level: consoleLevel(readStringFrom(payload, 'type') ?? ''),
+      text: readStringFrom(payload, 'text') ?? '',
+      at: init.clock.now().getTime(),
+    });
+  });
+  /**
+   * The page threw and nothing caught it. THE gap this ring closes: a screenshot of an island
+   * that threw during hydration is a picture of the server-rendered markup, indistinguishable
+   * from a page that worked — and `console` does not carry it, because throwing calls no console
+   * method. Subscribed here, beside the others, so a target is observing before its first
+   * navigation: an exception raised during load has no second chance to be recorded.
+   *
+   * NOT the same event as `error` below, and the difference is the whole reason this is a
+   * separate handler: puppeteer's `pageerror` is "an uncaught exception happens within the page"
+   * and its `error` is "the page crashes" (`PageEvent.PageError` / `PageEvent.Error`). One is the
+   * app being broken and the session is fine; the other is the tab being gone. Recording a
+   * `pageerror` into `crashed` would make every scrape of a page with one bad island answer
+   * X_SCRAPE_PAGE_CRASHED — a code registered `terminal` — for a page still perfectly usable.
+   */
+  init.page.on('pageerror', (payload) => {
+    pageErrors.push(readPageError(payload, init.clock.now().getTime()));
+  });
+  // A renderer that dies must be a CODE, not a hang: every later call answers X_SCRAPE_PAGE_CRASHED
+  // instead of waiting out its own timeout against a tab that is gone.
+  init.page.on('error', (payload) => {
+    crashed.value = readStringFrom(payload, 'message') ?? 'renderer crashed';
+  });
+}

package/src/cdp-fake.ts

@@ -8,10 +8,16 @@
 //
 // Precedent: `packages/storage/src/driver-s3-fixture.ts` ships the same way.
 
-import type { CdpBrowserLike, CdpFrameLike, CdpLauncherLike, CdpPageLike } from './cdp-port';
+import type {
+  CdpBrowserLike,
+  CdpFrameLike,
+  CdpLauncherLike,
+  CdpPageLike,
+  CdpSessionLike,
+} from './cdp-port';
 import { COLOR_SCHEME_FEATURE } from './color-scheme';
 import { queryHtml } from './html-query';
-import type { ElementSnapshot, ScrapeCookie } from './target';
+import type { AxNode, ElementSnapshot, ScrapeCookie } from './target';
 
 /** The selector inside `snapshotExpression()`'s `document.querySelectorAll("…")`. */
 const selectorOf = (expression: string): string | undefined => {
@@ -54,6 +60,14 @@ export interface FakeCdpPageInit {
   readonly userAgent?: string;
   /** Selectors whose element is covered at its centre — what only a layout engine can see. */
   readonly covered?: readonly string[];
+  /**
+   * What the accessibility tree answers, BY SELECTOR — the nodes `Accessibility.getPartialAXTree`
+   * would compute for each match, in document order. Canned rather than derived from the markup,
+   * deliberately: a fake that read `role=` off the tag would be the offline driver's refusal
+   * re-implemented as a lie, and the point of this session is to exercise `cdp-a11y.ts`'s four
+   * protocol calls and its parse, not to compute a role.
+   */
+  readonly accessibility?: Readonly<Record<string, readonly AxNode[]>>;
 }
 
 type Handlers = Map<string, ((payload: unknown) => void)[]>;
@@ -77,6 +91,15 @@ export interface FakeCdpBrowser extends CdpBrowserLike {
    * something sets one, which is the launcher's own default and not a value this fake invents.
    */
   readonly colorScheme: string | null;
+  /**
+   * Every keyboard event, in order — `down Meta`, `press K`, `up Meta` — so a test asserts on the
+   * SEQUENCE a chord became: a modifier released before the key, or never released, is the defect.
+   */
+  readonly pressed: readonly string[];
+  /** Every selector `page.focus()` was handed, in order. */
+  readonly focused: readonly string[];
+  /** How many raw CDP sessions were created and how many detached — a leak is a difference. */
+  readonly sessions: { readonly created: number; readonly detached: number };
 }
 
 /** A layout box every element gets, so the CDP path exercises the fields the fake target lacks. */
@@ -124,6 +147,75 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
   const covered = new Set(init.covered ?? []);
   const storage: Record<string, string> = { ...init.storage };
   let cookies: readonly ScrapeCookie[] = init.cookies ?? [];
+  const pressed: string[] = [];
+  const focused: string[] = [];
+  const sessions = { created: 0, detached: 0 };
+  const axBySelector = init.accessibility ?? {};
+
+  /**
+   * A raw session answering the four commands `cdp-a11y.ts` sends, in CDP's own wire shapes —
+   * `{ value }` wrappers, a `properties` list — so the parse in that file is what is under test.
+   * Node ids are minted per `querySelectorAll` and looked up on the way back, which is how the
+   * real protocol addresses nodes too.
+   */
+  const cdpSession = (): CdpSessionLike => {
+    const byNodeId = new Map<number, AxNode>();
+    const wrap = (value: string | boolean | undefined): { value?: string | boolean } =>
+      value === undefined ? {} : { value };
+    return {
+      send: (method: string, params?: Record<string, unknown>) => {
+        if (method === 'DOM.getDocument') return Promise.resolve({ root: { nodeId: 1 } });
+        if (method === 'DOM.querySelectorAll') {
+          const selector = typeof params?.['selector'] === 'string' ? params['selector'] : '';
+          const nodes = Object.hasOwn(axBySelector, selector) ? (axBySelector[selector] ?? []) : [];
+          const nodeIds = nodes.map((node, index) => {
+            const nodeId = 100 + byNodeId.size + index;
+            byNodeId.set(nodeId, node);
+            return nodeId;
+          });
+          return Promise.resolve({ nodeIds });
+        }
+        if (method === 'DOM.describeNode') {
+          const nodeId = typeof params?.['nodeId'] === 'number' ? params['nodeId'] : 0;
+          return Promise.resolve({ node: { backendNodeId: nodeId * 10 } });
+        }
+        if (method === 'Accessibility.getPartialAXTree') {
+          const backend =
+            typeof params?.['backendNodeId'] === 'number' ? params['backendNodeId'] : 0;
+          const node = byNodeId.get(backend / 10);
+          if (node === undefined) return Promise.resolve({ nodes: [] });
+          const properties = [
+            ...(node.focused === undefined ? [] : [{ name: 'focused', value: wrap(node.focused) }]),
+            ...(node.disabled === undefined
+              ? []
+              : [{ name: 'disabled', value: wrap(node.disabled) }]),
+          ];
+          return Promise.resolve({
+            nodes: [
+              {
+                nodeId: `ax-${String(backend)}`,
+                ignored: node.ignored,
+                role: { type: 'role', ...wrap(node.role) },
+                name: { type: 'computedString', ...wrap(node.name) },
+                ...(node.description === undefined
+                  ? {}
+                  : { description: { type: 'computedString', value: node.description } }),
+                ...(node.value === undefined
+                  ? {}
+                  : { value: { type: 'string', value: node.value } }),
+                properties,
+              },
+            ],
+          });
+        }
+        return Promise.resolve({});
+      },
+      detach: () => {
+        sessions.detached += 1;
+        return Promise.resolve();
+      },
+    };
+  };
 
   const documentOf = (read: () => string): FakeDocument => ({ html: read, typed: new Map() });
   const pageDocument = documentOf(() => html);
@@ -206,6 +298,28 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
     screenshot: () => Promise.resolve(new Uint8Array([1, 2, 3])),
     pdf: () => Promise.resolve(new Uint8Array([4, 5])),
     setRequestInterception: () => Promise.resolve(),
+    keyboard: {
+      down: (key: string) => {
+        pressed.push(`down ${key}`);
+        return Promise.resolve();
+      },
+      up: (key: string) => {
+        pressed.push(`up ${key}`);
+        return Promise.resolve();
+      },
+      press: (key: string) => {
+        pressed.push(`press ${key}`);
+        return Promise.resolve();
+      },
+    },
+    focus: (selector: string) => {
+      focused.push(selector);
+      return Promise.resolve();
+    },
+    createCDPSession: () => {
+      sessions.created += 1;
+      return Promise.resolve(cdpSession());
+    },
     setOfflineMode: (enabled: boolean) => {
       offline = enabled;
       return Promise.resolve();
@@ -275,6 +389,9 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
     get colorScheme(): string | null {
       return colorScheme;
     },
+    pressed,
+    focused,
+    sessions,
   };
 }
 

package/src/cdp-port.ts

@@ -44,6 +44,29 @@ export interface CdpRequestLike {
   continue(): Promise<void>;
 }
 
+/**
+ * The page's keyboard — `page.keyboard` under puppeteer, a PROPERTY and not a method, which is why
+ * it is declared as one. `key` stays a bare `string`: the library's `KeyInput` union is its own
+ * vocabulary, and a launcher whose union is wider or narrower must still satisfy the port. The
+ * chord grammar is checked in `key-chord.ts` before any of these is called.
+ */
+export interface CdpKeyboardLike {
+  down(key: string): Promise<void>;
+  up(key: string): Promise<void>;
+  press(key: string): Promise<void>;
+}
+
+/**
+ * A raw protocol session — `page.createCDPSession()` under puppeteer. `method` and `params` are
+ * the wire's own shapes, restated as `string` and a plain record: the library's typed command map
+ * is the library's, and naming it here would make this file depend on somebody else's protocol
+ * tables. Every answer is `unknown` and is parsed by the caller (`cdp-a11y.ts`), never cast.
+ */
+export interface CdpSessionLike {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  detach(): Promise<void>;
+}
+
 export interface CdpPageLike {
   url(): string;
   goto(url: string, options?: { readonly timeout?: number }): Promise<unknown>;
@@ -97,6 +120,21 @@ export interface CdpPageLike {
    * the library's own types for them.
    */
   on(event: string, handler: (payload: unknown) => void): unknown;
+  /**
+   * OPTIONAL, read defensively, for `setOfflineMode`'s reason: a provider SDK or a launcher that
+   * predates the member must still satisfy the port. `cdp-target.ts` refuses BY NAME with
+   * `X_NOT_IMPLEMENTED` when a launcher lacks it — a chord on a page with no keyboard is a coded
+   * refusal, never a silent no-op that leaves a command palette closed and a test green.
+   */
+  readonly keyboard?: CdpKeyboardLike | undefined;
+  /** `page.focus(selector)`. OPTIONAL for `keyboard`'s reason, and refused by name when absent. */
+  focus?(selector: string): Promise<void>;
+  /**
+   * A raw protocol session, for the one read this package makes that the library has no method
+   * for: the accessibility tree (`Accessibility.getPartialAXTree`). OPTIONAL for `keyboard`'s
+   * reason, and refused by name when absent.
+   */
+  createCDPSession?(): Promise<CdpSessionLike>;
   frames(): readonly CdpFrameLike[];
   close(): Promise<void>;
 }

package/src/cdp-snapshot.ts

@@ -92,3 +92,14 @@ export function parseSnapshots(raw: unknown): readonly ElementSnapshot[] {
     attrs: browserRecord(attrsOf(rows[index])),
   }));
 }
+
+/**
+ * Moving focus, as an expression — for a FRAME, where the port has no `focus` method. The page
+ * target calls `page.focus()`, which the library resolves against the top-level document, so a
+ * frame's focus travels as text into the frame's own `evaluate`, exactly as `clearExpression`
+ * does. A selector matching nothing REJECTS, as `page.focus()` does — the `.focus()` call on a
+ * null match is the throw, deliberately unguarded — and `cdp-target.ts`'s `guard()` re-labels the
+ * frame's rejection the same way it re-labels any other page throw.
+ */
+export const focusExpression = (selector: string): string =>
+  `(() => { document.querySelector(${JSON.stringify(selector)}).focus(); })()`;

package/src/cdp-target.ts

@@ -5,25 +5,24 @@ import { isUltimateError } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse, t } from '@ultimat3/schema';
 import { browserRecord } from './browser-record';
-import type { CdpBrowserLike, CdpFrameLike, CdpPageLike, CdpRequestLike } from './cdp-port';
-import { clearExpression, parseSnapshots, snapshotExpression } from './cdp-snapshot';
-import type { ScrapeClock } from './clock';
+import { axNodesFor } from './cdp-a11y';
+import type { CdpArmInit } from './cdp-arm';
+import { arm } from './cdp-arm';
+import type { CdpBrowserLike, CdpFrameLike } from './cdp-port';
+import {
+  clearExpression,
+  focusExpression,
+  parseSnapshots,
+  snapshotExpression,
+} from './cdp-snapshot';
 import { type ColorScheme, colorSchemeFeatures } from './color-scheme';
 import { browserUnreachable, pageCrashed, scrapeNotImplemented } from './error-throws';
-import type { InterceptRules } from './intercept';
-import { interceptVerdict, refusalEntry } from './intercept';
-import type {
-  ConsoleLine,
-  ConsoleRing,
-  NetworkEntry,
-  NetworkRing,
-  PageError,
-  PageErrorRing,
-  ResourceType,
-} from './rings';
-import { createRing, pageErrorEntry, RESOURCE_TYPES } from './rings';
+import { parseKeyChord } from './key-chord';
+import type { ConsoleLine, NetworkEntry, PageError } from './rings';
+import { createRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 import type {
+  AxNode,
   CaptureOptions,
   FrameRef,
   GotoOptions,
@@ -49,83 +48,6 @@ const cookieSchema = t.array(
   }),
 ) as unknown as StandardSchemaV1<unknown, ScrapeCookie[]>;
 
-const asResourceType = (raw: string): ResourceType =>
-  (RESOURCE_TYPES as readonly string[]).includes(raw) ? (raw as ResourceType) : 'other';
-
-/** The library's event payloads are `unknown` here — read structurally, never cast. */
-const asRequest = (payload: unknown): CdpRequestLike | undefined => {
-  if (typeof payload !== 'object' || payload === null) return undefined;
-  const candidate = payload as Partial<CdpRequestLike>;
-  return typeof candidate.url === 'function' && typeof candidate.abort === 'function'
-    ? (candidate as CdpRequestLike)
-    : undefined;
-};
-
-/**
- * CDP's console levels, mapped onto this package's five. `warning` is the library's spelling of
- * `warn`, `verbose` of `debug`, and everything structural (`table`, `startGroup`, `dir`) is a log
- * line with a shape — never its own level, because `ConsoleLine.level` is what an author filters on.
- */
-const CONSOLE_LEVELS: Readonly<Record<string, ConsoleLine['level']>> = {
-  error: 'error',
-  assert: 'error',
-  warning: 'warn',
-  warn: 'warn',
-  info: 'info',
-  debug: 'debug',
-  verbose: 'debug',
-};
-
-/**
- * `Object.hasOwn`, never the read alone: the type word arrives off the WIRE, so
- * `CONSOLE_LEVELS['__proto__']` answered `Object.prototype` and `['constructor']` the `Object`
- * function — neither of which a `?? 'log'` fallback can rescue, because neither is `undefined`.
- * `ConsoleLine.level` would then hold a value its own type says is one of five words, so the
- * `level === 'error'` filter this ring exists for matched nothing and `JSON.stringify` dropped
- * the field from a snapshot outright. Lowercasing is not the guard: `__proto__` and `constructor`
- * are already lowercase. Same discriminator as `packages/flags/src/subject.ts`.
- */
-const consoleLevel = (type: string): ConsoleLine['level'] => {
-  const word = type.toLowerCase();
-  return Object.hasOwn(CONSOLE_LEVELS, word) ? (CONSOLE_LEVELS[word] ?? 'log') : 'log';
-};
-
-/**
- * Reads a string out of somebody else's event payload, calling an accessor THROUGH ITS OWNER.
- *
- * `HTTPRequest.method()` and `ConsoleMessage.type()`/`.text()` read `this` — they are methods on
- * the library's own objects, not closures over a value. Handing the bare function to a helper
- * (`readString(request.method)`) drops the receiver, so the accessor answers against `undefined`:
- * on one build that throws inside the interception handler, on another it answers wrong.
- */
-const readStringFrom = (owner: unknown, key: string): string | undefined => {
-  if (typeof owner !== 'object' || owner === null) return undefined;
-  const value = (owner as Record<string, unknown>)[key];
-  if (typeof value === 'string') return value;
-  if (typeof value !== 'function') return undefined;
-  const answer = (value as (this: unknown) => unknown).call(owner);
-  return typeof answer === 'string' ? answer : undefined;
-};
-
-/**
- * A `pageerror` payload, read defensively — never cast, and never assumed to be an `Error`.
- *
- * `readStringFrom`, the same reader the console handler uses, because the payload has the same
- * problem: `message` and `stack` are an own property on one build and an accessor on another, and
- * a schema parse cannot call an accessor. A page can also `throw 'a string'` or throw a frozen
- * object with no `message` at all — both reach here, and both are recorded as SOMETHING having
- * thrown, because an entry with a poor message is still the difference between "the island threw"
- * and silence.
- */
-const readPageError = (payload: unknown, at: number): PageError => {
-  if (typeof payload === 'string') return pageErrorEntry({ message: payload, at });
-  return pageErrorEntry({
-    message: readStringFrom(payload, 'message') ?? '',
-    stack: readStringFrom(payload, 'stack'),
-    at,
-  });
-};
-
 /**
  * The failures `guard()` must NOT re-label. Two codes, each because a SECOND attempt reaches the
  * identical answer — never because the error looked coded.
@@ -167,81 +89,8 @@ const isStructuralRefusal = (thrown: unknown): boolean =>
  * of three drivers a bound the other two ignore, which is precisely the divergence
  * `driver-parity.test.ts` exists to refuse. `DEFAULT_RING_CAPACITY` is the one bound.
  */
-export interface CdpTargetInit {
-  readonly page: CdpPageLike;
+export interface CdpTargetInit extends CdpArmInit {
   readonly browser: CdpBrowserLike;
-  readonly rules: InterceptRules;
-  readonly clock: ScrapeClock;
-}
-
-/**
- * Everything `arm()` writes into. Named rather than positional: three rings of near-identical
- * type plus a latch is a call site nobody can read, and swapping two of them is a mistake the
- * compiler cannot catch.
- */
-interface CdpSinks {
-  readonly network: NetworkRing;
-  readonly console: ConsoleRing;
-  readonly pageErrors: PageErrorRing;
-  readonly crashed: { value: string | undefined };
-}
-
-/**
- * Interception is armed BEFORE the first navigation and refuses at the request, not after the
- * response — an `allowHosts` that reported afterwards would be a log line about bytes that
- * already left the container.
- */
-async function arm(init: CdpTargetInit, sinks: CdpSinks): Promise<void> {
-  const { network, console: console_, pageErrors, crashed } = sinks;
-  await init.page.setRequestInterception(true);
-  init.page.on('request', (payload) => {
-    const request = asRequest(payload);
-    if (request === undefined) return;
-    const url = request.url();
-    const type = asResourceType(request.resourceType());
-    // The METHOD the browser is actually sending. Recording every request as a GET made
-    // `page.network()` — which `X_SCRAPE_HTTP_FAILED`'s own fix line tells the reader to open —
-    // misreport every POST and PUT the page made.
-    const method = readStringFrom(request, 'method') ?? 'GET';
-    const verdict = interceptVerdict(url, type, init.rules);
-    const at = init.clock.now().getTime();
-    if (verdict === 'allow') {
-      network.push({ method, url, resourceType: type, at });
-      void request.continue();
-      return;
-    }
-    network.push(refusalEntry(url, type, verdict, at, method));
-    void request.abort();
-  });
-  init.page.on('console', (payload) => {
-    console_.push({
-      level: consoleLevel(readStringFrom(payload, 'type') ?? ''),
-      text: readStringFrom(payload, 'text') ?? '',
-      at: init.clock.now().getTime(),
-    });
-  });
-  /**
-   * The page threw and nothing caught it. THE gap this ring closes: a screenshot of an island
-   * that threw during hydration is a picture of the server-rendered markup, indistinguishable
-   * from a page that worked — and `console` does not carry it, because throwing calls no console
-   * method. Subscribed here, beside the others, so a target is observing before its first
-   * navigation: an exception raised during load has no second chance to be recorded.
-   *
-   * NOT the same event as `error` below, and the difference is the whole reason this is a
-   * separate handler: puppeteer's `pageerror` is "an uncaught exception happens within the page"
-   * and its `error` is "the page crashes" (`PageEvent.PageError` / `PageEvent.Error`). One is the
-   * app being broken and the session is fine; the other is the tab being gone. Recording a
-   * `pageerror` into `crashed` would make every scrape of a page with one bad island answer
-   * X_SCRAPE_PAGE_CRASHED — a code registered `terminal` — for a page still perfectly usable.
-   */
-  init.page.on('pageerror', (payload) => {
-    pageErrors.push(readPageError(payload, init.clock.now().getTime()));
-  });
-  // A renderer that dies must be a CODE, not a hang: every later call answers X_SCRAPE_PAGE_CRASHED
-  // instead of waiting out its own timeout against a tab that is gone.
-  init.page.on('error', (payload) => {
-    crashed.value = readStringFrom(payload, 'message') ?? 'renderer crashed';
-  });
 }
 
 export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
@@ -319,7 +168,26 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         await frame.select(selector, ...values);
       }),
     evaluate: (expression) => guard('evaluate', () => frame.evaluate(expression)),
+    // The PAGE's, listed rather than inherited so the next reader sees it was decided: a browser
+    // has one keyboard, and the focused element — set with the frame's own `focus` below — is what
+    // routes the chord into the frame's document.
+    press: (chord) => parent.press(chord),
     frames: () => Promise.resolve([]),
+    focus: (selector) =>
+      guard('focus', async () => {
+        await frame.evaluate(focusExpression(selector));
+      }),
+    // `Accessibility.getPartialAXTree` is addressed by backend node id and `DOM.querySelectorAll`
+    // by a document's node id, so a frame read needs the frame's own document — a second
+    // `DOM.getDocument` scoped by frame id that `cdp-a11y.ts` does not perform. Refused by name
+    // rather than answered from the PARENT document, which is what the spread alone would do.
+    accessibility: (_selector, _max): Promise<readonly AxNode[]> =>
+      Promise.reject(
+        scrapeNotImplemented(
+          'accessibility() on a frame of the puppeteer driver',
+          'read the accessibility tree through the page — page.accessibility(selector) — which covers the top-level document only',
+        ),
+      ),
   });
 
   const target: ScrapeTarget = {
@@ -351,6 +219,59 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         await init.page.select(selector, ...values);
       }),
     evaluate: (expression) => guard('evaluate', () => init.page.evaluate(expression)),
+    // `async`, and the parse OUTSIDE `guard()`: the chord is the caller's literal, not the
+    // browser's answer, so a bad one is `X_SCRAPE_KEY_INVALID` and never re-labelled "the browser
+    // went away" — and it is parsed before the keyboard is touched, because a refusal halfway
+    // through the sequence below would leave a modifier held for every later verb on this page.
+    press: async (chord: string): Promise<void> => {
+      const { modifiers, key } = parseKeyChord(chord);
+      await guard('press', async () => {
+        const keyboard = init.page.keyboard;
+        if (keyboard === undefined) {
+          throw scrapeNotImplemented(
+            'press() on a CDP page with no keyboard',
+            'upgrade the launcher to a puppeteer-core that exposes page.keyboard, or dispatch the key from the app under test instead of the browser',
+          );
+        }
+        // Down in the order written, the key, then up in REVERSE — the order a hand releases
+        // them, and the order the browser's own `press` with modifiers performs. `.call`-free:
+        // `keyboard` is read as an object and its methods are called through it.
+        for (const modifier of modifiers) await keyboard.down(modifier);
+        try {
+          await keyboard.press(key);
+        } finally {
+          for (const modifier of [...modifiers].reverse()) await keyboard.up(modifier);
+        }
+      });
+    },
+    focus: (selector: string): Promise<void> =>
+      guard('focus', async () => {
+        const focus = init.page.focus;
+        if (typeof focus !== 'function') {
+          throw scrapeNotImplemented(
+            'focus() on a CDP page with no focus() method',
+            'upgrade the launcher to a puppeteer-core that exposes page.focus(), or click the element instead',
+          );
+        }
+        // `.call`, for `setColorScheme`'s reason: the member is read off the object.
+        await focus.call(init.page, selector);
+      }),
+    accessibility: (selector: string, max: number): Promise<readonly AxNode[]> =>
+      guard('accessibility', async () => {
+        const createSession = init.page.createCDPSession;
+        if (typeof createSession !== 'function') {
+          throw scrapeNotImplemented(
+            'accessibility() on a CDP page with no createCDPSession() method',
+            'upgrade the launcher to a puppeteer-core that exposes page.createCDPSession(), or assert on the markup with page.query() — which reads attributes, not what the browser computed',
+          );
+        }
+        const session = await createSession.call(init.page);
+        try {
+          return await axNodesFor(session, selector, max);
+        } finally {
+          await session.detach();
+        }
+      }),
     setOfflineMode: (enabled: boolean): Promise<void> =>
       guard('setOfflineMode', async () => {
         const source = init.page as { setOfflineMode?: (value: boolean) => Promise<void> };

package/src/error-throws.ts

@@ -437,3 +437,17 @@ export const captureClipOnPdf = (clip: CaptureClip): ScrapeError =>
     fix: 'call page.screenshot({ clip }) for one component, or page.pdf() with no clip for the document',
     meta: { clip: { ...clip } },
   });
+
+/**
+ * A chord that cannot be pressed. Refused before ANY key goes down, which is the reason it is a
+ * parse and not a try: `press()` holds every modifier, presses the key, then releases — and a
+ * chord refused halfway through would leave `Control` held on the page for every later verb.
+ * Terminal for `X_SCRAPE_CAPTURE_INVALID`'s reason: the chord is the caller's own literal.
+ */
+export const keyInvalid = (chord: string, reason: string): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_KEY_INVALID',
+    cause: `the key chord ${JSON.stringify(chord)} ${reason}`,
+    fix: "spell the chord as zero or more of Meta, Control, Alt, Shift joined by '+' and then the key — 'Meta+K', 'Escape', 'Shift+Tab' — using the browser's own key names",
+    meta: { chord },
+  });

package/src/errors.ts

@@ -38,6 +38,7 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_SESSION_EXPIRED',
   'X_SCRAPE_PROMPT_UNANSWERED',
   'X_SCRAPE_BLOCKED',
+  'X_SCRAPE_KEY_INVALID',
 ] as const;
 
 /**
@@ -89,6 +90,7 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
   X_SCRAPE_SESSION_EXPIRED: 'the restored session is no longer valid and nothing can renew it',
   X_SCRAPE_PROMPT_UNANSWERED: 'a login step asked for a code and nothing answered',
   X_SCRAPE_BLOCKED: 'the site refused this client — the identity is spent',
+  X_SCRAPE_KEY_INVALID: 'the key chord names no key a browser can press',
 };
 
 // One unconditional call, so a second package claiming one of these codes throws
@@ -186,6 +188,10 @@ export const SCRAPE_ERROR_RETRY = {
   X_SCRAPE_AUTH_FAILED: 'terminal',
   X_SCRAPE_SESSION_EXPIRED: 'terminal',
   X_SCRAPE_PROMPT_UNANSWERED: 'terminal',
+  // A declaration error, for `X_SCRAPE_CAPTURE_INVALID`'s reason: the chord is the caller's own
+  // literal, attempt 2 passes the identical string, and a retry is a browser launch for no chance
+  // of a different parse. Refused before any key goes down, so no modifier is left held.
+  X_SCRAPE_KEY_INVALID: 'terminal',
 } as const satisfies Readonly<Record<ScrapeOwnedErrorCode, 'retryable' | 'terminal'>>;
 
 registerErrorRetry(SCRAPE_ERROR_RETRY);

package/src/html-target.ts

@@ -19,6 +19,7 @@ import { queryHtml } from './html-query';
 import { markupRequests } from './html-requests';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict, refusalEntry } from './intercept';
+import { parseKeyChord } from './key-chord';
 import type { PageRecording } from './recording';
 import { splitDownload } from './recording';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
@@ -26,6 +27,7 @@ import { createRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 import { EMPTY_SESSION } from './session-state';
 import type {
+  AxNode,
   CaptureOptions,
   ElementSnapshot,
   FrameRef,
@@ -296,6 +298,12 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
       type: (selector, text) => typeIn(document, selector, text),
       clear: (selector) => setIn(document, selector, ''),
       select: (selector, values) => setIn(document, selector, values[0] ?? ''),
+      // The frame's OWN document, for `click`'s reason: inheriting `base.focus` would refuse a
+      // selector that exists only in the frame, and accept one that exists only in the parent.
+      async focus(selector: string): Promise<void> {
+        const element = await atIn(document, selector, 0);
+        if (element === undefined) throw fixtureMissing(`${url} ${selector}`, init.source);
+      },
       frames: () => Promise.resolve([]),
     };
   };
@@ -326,6 +334,35 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     clear: (selector: string): Promise<void> => setIn(pageDocument, selector, ''),
     select: (selector: string, values: readonly string[]): Promise<void> =>
       setIn(pageDocument, selector, values[0] ?? ''),
+    /**
+     * PARSED and then resolved, for `setColorScheme`'s reason and not `setOfflineMode`'s. There is
+     * no JS engine here, so no `keydown` listener can hear the chord — but the one thing this
+     * driver CAN be wrong about, the chord's spelling, is checked by the same `parseKeyChord` the
+     * real driver runs, so `'Ctrl+K'` is `X_SCRAPE_KEY_INVALID` offline exactly as it is live. What
+     * it cannot prove is that the page reacted; a test that needs that runs on `localBrowser()`.
+     */
+    press(chord: string): Promise<void> {
+      live();
+      parseKeyChord(chord);
+      return Promise.resolve();
+    },
+    /** The selector must exist, as `click` requires — a focus on nothing is a fixture gap. */
+    async focus(selector: string): Promise<void> {
+      const element = await at(selector, 0);
+      if (element === undefined) throw fixtureMissing(`${page.url} ${selector}`, init.source);
+    },
+    /**
+     * REFUSED, and `async` so it REJECTS. No accessibility engine runs here, and the honest
+     * alternative — reading `role=` and `aria-label=` off the markup — is the defect the read
+     * exists to catch: a `<div onclick>` has no computed role, and a fake that answered the
+     * attribute would pass every test against the element a screen reader cannot reach.
+     */
+    async accessibility(_selector: string, _max: number): Promise<readonly AxNode[]> {
+      throw scrapeNotImplemented(
+        `accessibility() on the ${init.driver} driver`,
+        'run this assertion on localBrowser()/remoteBrowser(), whose accessibility() reads the tree the browser computed — an offline driver parses markup and computes no role',
+      );
+    },
     evaluate(expression: string): Promise<unknown> {
       live();
       const answer = recorded(page.evaluate, expression);

package/src/index.ts

@@ -21,15 +21,23 @@ export { burnSession, createPrompt, ensureAuthenticated, restorableSession } fro
 export { browserRecord } from './browser-record';
 export type { CaptureClip, CaptureFraming } from './capture-clip';
 export { assertCaptureFraming } from './capture-clip';
+export { axNodesFor } from './cdp-a11y';
 export type {
   CdpBrowserLike,
   CdpFrameLike,
+  CdpKeyboardLike,
   CdpLauncherLike,
   CdpPageLike,
   CdpRequestLike,
   CdpScreenshotOptions,
+  CdpSessionLike,
 } from './cdp-port';
-export { clearExpression, parseSnapshots, snapshotExpression } from './cdp-snapshot';
+export {
+  clearExpression,
+  focusExpression,
+  parseSnapshots,
+  snapshotExpression,
+} from './cdp-snapshot';
 export type { CdpTargetInit } from './cdp-target';
 export { CDP_DRIVER, cdpTarget } from './cdp-target';
 export type { Deadline, ScrapeClock, TestScrapeClock } from './clock';
@@ -62,6 +70,7 @@ export {
   fixtureStale,
   hostBlocked,
   httpFailed,
+  keyInvalid,
   notActionable,
   outputInvalid,
   pageCrashed,
@@ -117,9 +126,12 @@ export type { RedirectHop } from './http-redirect';
 export { MAX_REDIRECT_HOPS, redirectHop } from './http-redirect';
 export type { InterceptRules, InterceptVerdict } from './intercept';
 export { interceptVerdict, refusalEntry } from './intercept';
+export type { KeyChord, KeyModifier } from './key-chord';
+export { KEY_MODIFIERS, parseKeyChord } from './key-chord';
 export type { OfflineSessionInit } from './offline-session';
 export { openOfflineSession } from './offline-session';
 export type {
+  AccessibilityOptions,
   CaptureRequest,
   DownloadRequest,
   ElementValue,
@@ -127,6 +139,7 @@ export type {
   ScrapePage,
   WaitOptions,
 } from './page';
+export { DEFAULT_ACCESSIBILITY_MAX } from './page';
 export type { PageContext } from './page-over-target';
 export { pageOverTarget } from './page-over-target';
 export type { Pacer } from './rate';
@@ -197,6 +210,7 @@ export {
   storageSessionStore,
 } from './session-state';
 export type {
+  AxNode,
   CaptureOptions,
   ElementBox,
   ElementSnapshot,

package/src/key-chord.ts

@@ -0,0 +1,60 @@
+// A key chord, parsed ONCE and refused before any key goes down.
+//
+// `'Meta+K'` is the spelling every scraper in the audit wrote by hand, and every one of them split
+// on `+` and handed the pieces to the browser unchecked — so `'Ctrl+K'` held nothing (the browser
+// knows `Control`, not `Ctrl`), pressed `K`, and the test went green with the palette closed. The
+// grammar is small enough to state in full: zero or more modifiers, joined by `+`, then one key,
+// spelled the way the browser spells it. The parse is the whole check, and it runs on every driver
+// — an offline driver has no keyboard, but it can still tell a caller the chord is wrong.
+
+import { keyInvalid } from './error-throws';
+
+/** The four modifiers a browser holds, under the names the browser's own keyboard uses. */
+export const KEY_MODIFIERS = ['Meta', 'Control', 'Alt', 'Shift'] as const;
+
+export type KeyModifier = (typeof KEY_MODIFIERS)[number];
+
+export interface KeyChord {
+  /** In the order written, which is the order they go down; they come up in reverse. */
+  readonly modifiers: readonly KeyModifier[];
+  /** The browser's own key name — `K`, `Enter`, `Escape`, `ArrowDown`. Never empty. */
+  readonly key: string;
+}
+
+const isModifier = (word: string): word is KeyModifier =>
+  (KEY_MODIFIERS as readonly string[]).includes(word);
+
+/**
+ * `'Meta+K'` → `{ modifiers: ['Meta'], key: 'K' }`. Refuses, with `X_SCRAPE_KEY_INVALID`, an
+ * unknown modifier, an empty key, a trailing `+`, and a modifier written twice — each is a chord
+ * the browser would hold and release differently from what the caller meant, and a chord is the
+ * caller's own literal, so the refusal is terminal.
+ *
+ * The literal `+` key has no spelling in this grammar: `'+'` splits to nothing. Type it with
+ * `page.type()`, which is what a character is for; a chord is for a key the page listens to.
+ */
+export function parseKeyChord(chord: string): KeyChord {
+  if (chord === '') throw keyInvalid(chord, 'is empty, so there is no key to press');
+  const parts = chord.split('+');
+  const key = parts.at(-1) ?? '';
+  if (key === '') {
+    throw keyInvalid(
+      chord,
+      "ends in '+', so it names modifiers and no key — the last segment is the key to press",
+    );
+  }
+  const modifiers: KeyModifier[] = [];
+  for (const word of parts.slice(0, -1)) {
+    if (!isModifier(word)) {
+      throw keyInvalid(
+        chord,
+        `names ${JSON.stringify(word)} as a modifier, and the browser holds only ${KEY_MODIFIERS.join(', ')}`,
+      );
+    }
+    if (modifiers.includes(word)) {
+      throw keyInvalid(chord, `holds ${word} twice, and a key held twice comes up once`);
+    }
+    modifiers.push(word);
+  }
+  return { modifiers, key };
+}

package/src/page-over-target.ts

@@ -4,7 +4,7 @@
 // driver a test uses and the driver production uses.
 
 import type { Secret } from '@ultimat3/core';
-import { isSecret, revealSecret } from '@ultimat3/core';
+import { finiteCount, isSecret, revealSecret } from '@ultimat3/core';
 import type { ActionabilityState } from './actionability';
 import { awaitActionable } from './actionability';
 import { assertCaptureFraming } from './capture-clip';
@@ -14,6 +14,7 @@ import type { ColorScheme } from './color-scheme';
 import { hostBlocked, secretExposed, selectorMissing } from './error-throws';
 import { hostDecision } from './hosts';
 import type {
+  AccessibilityOptions,
   CaptureRequest,
   DownloadRequest,
   ElementValue,
@@ -21,10 +22,12 @@ import type {
   ScrapePage,
   WaitOptions,
 } from './page';
+import { DEFAULT_ACCESSIBILITY_MAX } from './page';
 import type { RobotsGate } from './robots';
 import type { ScrapeSecrets } from './secrets';
 import { safeConsole, safeHtml, safeNetwork, safePageErrors } from './secrets';
 import type {
+  AxNode,
   CaptureOptions,
   ElementSnapshot,
   ScrapeCookie,
@@ -131,6 +134,28 @@ function frameOver(
       await wait(selector, options, 'actionable');
       await (await resolve()).select(selector, values);
     },
+    // `actionable`, like `click`: focus moved to a hidden or disabled control is focus the page
+    // will not keep, and the chord that follows lands on the body.
+    async focus(selector, options): Promise<void> {
+      await wait(selector, options, 'actionable');
+      await (await resolve()).focus(selector);
+    },
+    // `async`, for `download()`'s reason: a third-party target that throws synchronously from a
+    // promise-typed method must still reach the caller's `.catch()`.
+    async press(chord): Promise<void> {
+      await (await resolve()).press(chord);
+    },
+    async accessibility(selector, options?: AccessibilityOptions): Promise<readonly AxNode[]> {
+      // Screened, never `??`-defaulted alone: `NaN` is not nullish, and `slice(0, NaN)` is
+      // `slice(0, 0)` — an empty answer that reads as "nothing matched" (`finiteCount`, core).
+      const max = finiteCount(
+        'page.accessibility()',
+        'max',
+        options?.max ?? DEFAULT_ACCESSIBILITY_MAX,
+        1,
+      );
+      return await (await resolve()).accessibility(selector, max);
+    },
     // Resolved through `resolve()` like every other verb, which is what makes a FRAME's `query`
     // read the frame's document: `resolve` is `resolveChild` there, and both drivers override
     // `query` on the frame target. A forward that reached for a captured page target instead

package/src/page.ts

@@ -13,7 +13,7 @@ import type { CaptureFraming } from './capture-clip';
 import type { ColorScheme } from './color-scheme';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
 import type { SessionSnapshot } from './session-state';
-import type { ElementSnapshot, ScrapeCookie, ScrapeDownloadFile } from './target';
+import type { AxNode, ElementSnapshot, ScrapeCookie, ScrapeDownloadFile } from './target';
 
 export interface WaitOptions {
   readonly state?: ActionabilityState | undefined;
@@ -21,6 +21,13 @@ export interface WaitOptions {
   readonly timeout?: number | undefined;
 }
 
+/** How many matches `accessibility()` describes. A bound, because each match is a round trip. */
+export interface AccessibilityOptions {
+  readonly max?: number | undefined;
+}
+
+export const DEFAULT_ACCESSIBILITY_MAX = 25;
+
 export interface ElementValue {
   readonly tag: string;
   readonly text: string;
@@ -49,6 +56,28 @@ export interface ScrapeFrame {
   /** Clears first, then types — the spelling a login form wants. */
   fill(selector: string, text: string | Secret, options?: WaitOptions): Promise<void>;
   select(selector: string, values: readonly string[], options?: WaitOptions): Promise<void>;
+  /**
+   * Waits for the element to be actionable, then moves focus to it — the setup for a `press()`,
+   * and the half of keyboard navigation a click cannot stand in for.
+   */
+  focus(selector: string, options?: WaitOptions): Promise<void>;
+  /**
+   * A key chord on whatever holds focus: `'Meta+K'`, `'Escape'`, `'Shift+Tab'`, `'Enter'`.
+   * Modifiers are `Meta`, `Control`, `Alt`, `Shift`, in the browser's own spelling — `'Ctrl+K'`
+   * is `X_SCRAPE_KEY_INVALID` on every driver, offline included, because the parse is the one
+   * thing an offline driver can be wrong about. The browser has ONE keyboard, so a chord pressed
+   * through a frame handle reaches whichever element that frame's `focus()` put focus on.
+   */
+  press(chord: string): Promise<void>;
+  /**
+   * What a screen reader is told about each match — the browser's computed role and name, after
+   * ARIA and label association, which `query()` cannot answer from attributes. At most
+   * `options.max` (default `DEFAULT_ACCESSIBILITY_MAX`) nodes, in document order. Refused with
+   * `X_NOT_IMPLEMENTED` on a driver with no accessibility engine — an offline driver, or a frame
+   * of the real one — never answered from the markup: a `<div onclick>` computing no role IS the
+   * finding, and a fake reading `role=` off the tag would hide it.
+   */
+  accessibility(selector: string, options?: AccessibilityOptions): Promise<readonly AxNode[]>;
   /**
    * Every match, as SNAPSHOTS — `visible`, `enabled` and (on a driver with a layout engine) the
    * box and hit-target, which `values()` projects away.

package/src/target.ts

@@ -47,6 +47,24 @@ export interface ElementSnapshot {
   readonly hitTarget?: boolean | undefined;
 }
 
+/**
+ * One node of the browser's accessibility tree, as of one observation — what a screen reader is
+ * told about an element, which is a different fact from what `ElementSnapshot` says about its
+ * markup. `role` and `name` are always answered, `''` when the browser computed nothing: absent is
+ * a real answer for a `<div>`, and a fabricated `generic` would hide the elements a reader cannot
+ * name. A VALUE, like `ElementSnapshot`: it cannot go stale behind the caller's back, only old.
+ */
+export interface AxNode {
+  readonly role: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly value?: string | undefined;
+  readonly focused?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  /** Pruned from the tree a reader walks — `aria-hidden`, or a wrapper with nothing to say. */
+  readonly ignored: boolean;
+}
+
 export interface ScrapeCookie {
   readonly name: string;
   readonly value: string;
@@ -133,6 +151,25 @@ export interface ScrapeTarget {
   select(selector: string, values: readonly string[]): Promise<void>;
   /** The expression runs in the page. The result is `unknown` and is parsed by the caller. */
   evaluate(expression: string): Promise<unknown>;
+  /**
+   * A key chord — `'Meta+K'`, `'Escape'`, `'Shift+Tab'` — pressed on whatever holds focus. The
+   * PAGE's keyboard, on a frame target too: a browser has one keyboard, and the focused element
+   * is what decides which document hears it. REQUIRED here where `CdpPageLike.keyboard` is
+   * optional, for `setOfflineMode`'s reason: the asymmetry is the enforcement. A driver with no
+   * keyboard still PARSES the chord (`key-chord.ts`) and then resolves — the refusal an offline
+   * driver can give is the one it does give.
+   */
+  press(chord: string): Promise<void>;
+  /** Moves focus to the first match. Refused when nothing matches. */
+  focus(selector: string): Promise<void>;
+  /**
+   * The accessibility node of every match, bounded by `max` — the browser's own computed role and
+   * name, which no HTML parse can reproduce. REQUIRED for `press`'s reason, and a driver with no
+   * accessibility engine answers `X_NOT_IMPLEMENTED`, never an invented role: a fake that read
+   * `role="button"` off the markup would pass a test against a `<div onclick>` a reader cannot
+   * reach, which is the exact defect this read exists to catch.
+   */
+  accessibility(selector: string, max: number): Promise<readonly AxNode[]>;
   /**
    * The browser goes offline, or comes back. REQUIRED on this port where it is optional on
    * `CdpPageLike`, and the asymmetry is the enforcement: a driver author gets a type error naming