@ultimat3/scraping 20.1.6 → 20.2.1

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.
@@ -125,6 +154,18 @@ export interface ScrapePage extends ScrapeFrame {
    * method, which is a fact about the build rather than about the driver.
    */
   colorScheme(scheme: ColorScheme): Promise<void>;
+  /**
+   * A script the browser runs in EVERY document this page navigates to, BEFORE the document's
+   * own scripts — the one moment that beats an inlined boot script. Call it before `goto()`: what
+   * it seeds (a `localStorage` key a boot reads, a flag a component checks) is then in place for
+   * the first script the page executes, where an `evaluate()` after navigation is one boot too
+   * late. Same string discipline as `evaluate()`: an expression, never a closure.
+   *
+   * ACCEPTED on every driver, for `colorScheme()`'s reason: the offline drivers run no scripts,
+   * so nothing there could be wrong about it. `X_NOT_IMPLEMENTED` is reserved for a LAUNCHER
+   * that lacks the method, which is a fact about the build rather than about the driver.
+   */
+  prepare(expression: string): Promise<void>;
   /**
    * The handoff, made explicit: what the HTTP leg will send, as a value an author can inspect and
    * a fixture can assert on. `http` uses it automatically — this is for seeing what carried over.

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
@@ -164,6 +201,20 @@ export interface ScrapeTarget {
    * so a driver that dropped the preference fails a test rather than passing every one.
    */
   setColorScheme(scheme: ColorScheme): Promise<void>;
+  /**
+   * A script every document this target navigates to runs BEFORE its own — the browser's
+   * `evaluateOnNewDocument`. REQUIRED here where `CdpPageLike.evaluateOnNewDocument` is optional,
+   * for `setOfflineMode`'s reason: the asymmetry is the enforcement, and a launcher without the
+   * method is `X_NOT_IMPLEMENTED`.
+   *
+   * A DRIVER WITH NO JS ENGINE ACCEPTS IT, for `setColorScheme`'s reason and not
+   * `setOfflineMode`'s: the offline drivers execute nothing, so there is no document script for
+   * the expression to run ahead of and no assertion a resolved promise could let through — a
+   * seeded `localStorage` key is the INPUT to a boot script this driver never runs. Refusing
+   * would make `x shot` and every `ui.*` tool untestable on a machine with no Chrome, and the
+   * outcome it would protect does not exist here. The call is still checked for a closed target.
+   */
+  prepare(expression: string): Promise<void>;
   screenshot(options: CaptureOptions): Promise<Uint8Array>;
   pdf(options: CaptureOptions): Promise<Uint8Array>;
   cookies(): Promise<readonly ScrapeCookie[]>;