@ultimat3/scraping 20.1.6 → 20.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "20.1.6",
+  "version": "20.2.1",
   "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.6",
-    "@ultimat3/jobs": "20.1.6",
-    "@ultimat3/schema": "20.1.6",
-    "@ultimat3/storage": "20.1.6"
+    "@ultimat3/core": "20.2.1",
+    "@ultimat3/jobs": "20.2.1",
+    "@ultimat3/schema": "20.2.1",
+    "@ultimat3/storage": "20.2.1"
   }
 }

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,21 @@ 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[];
+  /**
+   * Every expression `page.evaluateOnNewDocument()` was handed, in order — the scripts a real
+   * browser would run ahead of each document's own. Recorded, never executed: this fake has no JS
+   * engine, and a test asserts on WHAT was prepared and that it was prepared before `goto`.
+   */
+  readonly prepared: 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 +153,76 @@ 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 prepared: 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 +305,32 @@ 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();
+    },
+    evaluateOnNewDocument: (expression: string) => {
+      prepared.push(expression);
+      return Promise.resolve(undefined);
+    },
+    createCDPSession: () => {
+      sessions.created += 1;
+      return Promise.resolve(cdpSession());
+    },
     setOfflineMode: (enabled: boolean) => {
       offline = enabled;
       return Promise.resolve();
@@ -275,6 +400,10 @@ export function fakeCdpBrowser(init: FakeCdpPageInit): FakeCdpBrowser {
     get colorScheme(): string | null {
       return colorScheme;
     },
+    pressed,
+    focused,
+    prepared,
+    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,29 @@ 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>;
+  /**
+   * `page.evaluateOnNewDocument(expression)`: a script the browser runs in EVERY document this
+   * page navigates to, before any of the document's own scripts — `Page.addScriptToEvaluateOnNewDocument`
+   * under CDP. It is the only moment that beats an inlined boot script, which is what a
+   * storage-seeded theme choice needs (`ScrapePage.prepare`). The string form, for `evaluate`'s
+   * reason. OPTIONAL for `keyboard`'s reason, and refused by name when absent.
+   */
+  evaluateOnNewDocument?(expression: string): Promise<unknown>;
+  /**
+   * 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(); })()`;