@ultimat3/scraping 20.1.6 → 20.2.1

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> };
@@ -379,6 +300,18 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         // puppeteer's own `Page` needs it.
         await emulate.call(init.page, colorSchemeFeatures(scheme));
       }),
+    prepare: (expression: string): Promise<void> =>
+      guard('prepare', async () => {
+        // Read off the object and called through it, for `setColorScheme`'s reason.
+        const evaluateOnNewDocument = init.page.evaluateOnNewDocument;
+        if (typeof evaluateOnNewDocument !== 'function') {
+          throw scrapeNotImplemented(
+            'prepare() on a CDP page with no evaluateOnNewDocument() method',
+            'upgrade the launcher to a puppeteer-core that exposes page.evaluateOnNewDocument(), or seed the state from the app under test instead of the browser',
+          );
+        }
+        await evaluateOnNewDocument.call(init.page, expression);
+      }),
     screenshot: (options: CaptureOptions) =>
       guard('screenshot', async () => {
         // `fullPage` is OMITTED when a clip is given rather than sent as `false`: the two are

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);
@@ -375,6 +412,18 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
       colorScheme = scheme === 'no-preference' ? null : scheme;
       return Promise.resolve();
     },
+    /**
+     * ACCEPTED, for `setColorScheme`'s reason and not `setOfflineMode`'s. This driver parses
+     * markup and executes none of it, so there is no document script for the expression to run
+     * ahead of — and no assertion a resolved promise could let through: what a prepared script
+     * seeds is the INPUT to a boot this driver never runs. Refusing would cost `x shot` and every
+     * `ui.*` tool their unit tests on a machine with no Chrome, for an outcome that does not exist
+     * here. `live()` still refuses a closed target, which is the one thing this can be wrong about
+     * — and `async`, so that refusal REJECTS rather than escaping a caller's `.catch()`.
+     */
+    async prepare(_expression: string): Promise<void> {
+      live();
+    },
     screenshot: (options: CaptureOptions): Promise<Uint8Array> =>
       Promise.resolve(framedPng(options.clip, colorScheme)),
     pdf: (_options: CaptureOptions): Promise<Uint8Array> => Promise.resolve(FAKE_PDF),

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
@@ -249,6 +274,10 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
     async colorScheme(scheme: ColorScheme): Promise<void> {
       await target.setColorScheme(scheme);
     },
+    // `async`, for `offline()`'s reason.
+    async prepare(expression: string): Promise<void> {
+      await target.prepare(expression);
+    },
     cookies: (): Promise<readonly ScrapeCookie[]> => target.cookies(),
     session: () => target.session(),
     // Redacted BY VALUE on the way out, the same pass `html()` makes. A console line and a request