@orkestrel/browser 0.0.18 → 0.0.20

package/dist/src/browser/index.d.ts

@@ -0,0 +1,841 @@
+import type { BrowserCallOptions } from '@orkestrel/browser';
+import type { BrowserElementInterface } from '@orkestrel/browser';
+import type { BrowserElementManagerInterface } from '@orkestrel/browser';
+import type { BrowserElementQuery } from '@orkestrel/browser';
+import type { BrowserElementWaitOptions } from '@orkestrel/browser';
+import type { BrowserEpochFunction } from '@orkestrel/browser';
+import type { BrowserOutline } from '@orkestrel/browser';
+import type { BrowserOutlineOptions } from '@orkestrel/browser';
+import type { BrowserReadingInput } from '@orkestrel/browser';
+import type { BrowserReadingInterface } from '@orkestrel/browser';
+import type { BrowserToolsetInterface } from '@orkestrel/browser';
+import type { BrowserToolsetOptions } from '@orkestrel/browser';
+import type { BrowserViewInterface } from '@orkestrel/browser';
+import type { CDPTransportEventMap } from '@orkestrel/browser';
+import type { CDPTransportInterface } from '@orkestrel/browser';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+
+/**
+ * Names the ARIA roles whose accessible name the accessible-name computation takes from the
+ * element's content when no attribute or label names it.
+ */
+export declare const BROWSER_CONTENT_NAMED_ROLES: ReadonlySet<string>;
+
+/**
+ * Names the link and form targets that navigate the current browsing context or one of its
+ * ancestors. `_blank` opens another browsing context, and any other name targets the browsing
+ * context carrying that name, which `matchesBrowserPopup` resolves.
+ */
+export declare const BROWSER_CONTEXT_TARGETS: ReadonlySet<string>;
+
+/**
+ * Sets the default `wait` deadline for DOM waits in a browser document toolset, `5_000`
+ * milliseconds.
+ */
+export declare const BROWSER_DOCUMENT_TIMEOUT_MS = 5000;
+
+/**
+ * Maps an HTML element to the ARIA role the HTML Accessibility API Mappings specification gives
+ * it when it carries no `role` attribute.
+ *
+ * @remarks
+ * A key is a lowercase element name, or `input:` followed by the input's `type` state. An element
+ * whose mapping depends on more than its name — `a` and `area` without `href`, `select` with
+ * `multiple` or a `size` above 1, an `img` with an empty `alt`, a scoped `header` or `footer`, a
+ * `section` or `form` without an accessible name, and a text input with a `list` — is resolved
+ * by `computeBrowserRole` before this table is read. An element or input state the mapping gives
+ * no role has no entry.
+ */
+export declare const BROWSER_IMPLICIT_ROLES: ReadonlyMap<string, string>;
+
+/**
+ * Selects the HTML interactive content a click inside a `label` can land on without activating
+ * the label, as the HTML interactive-content category lists it: `a` with `href`, `audio` and
+ * `video` with `controls`, `button`, `details`, `embed`, `iframe`, `img` with `usemap` or
+ * `controls`, `input` other than `hidden`, `label`, `select`, and `textarea`.
+ */
+export declare const BROWSER_INTERACTIVE_CONTENT = "a[href], audio[controls], button, details, embed, iframe, img[usemap], img[controls], input:not([type=\"hidden\" i]), label, select, textarea, video[controls]";
+
+/** Names the `input` type states whose value an untrusted `fill` sets as typed text. */
+export declare const BROWSER_TYPED_INPUTS: ReadonlySet<string>;
+
+/**
+ * Configures a toolset that drives one browser document.
+ *
+ * @remarks
+ * - `document` and `own` — the driven document and the admission of the realm's own document, as
+ *   {@link BrowserDOMViewOptions} describes them
+ * - `source` — a source of page tools, such as `@orkestrel/mcp`'s model context bridge; the
+ *   toolset adopts its tools and re-adopts on its `change`. Default: no page tools
+ * - `tools`, `limit`, `journeys`, `on`, and `error` — as {@link BrowserToolsetOptions}
+ *   describes them
+ */
+export declare interface BrowserDocumentToolsetOptions extends BrowserDOMViewOptions, Pick<BrowserToolsetOptions, 'on' | 'error' | 'tools' | 'source' | 'limit' | 'journeys'> {
+}
+
+/**
+ * Drives a referenced element of a DOM document without trusted input.
+ *
+ * @remarks
+ * `click` runs `HTMLElement.click()`; `fill` and `select` set the control through its native
+ * prototype setter and dispatch `input` and `change`, and `fill` refuses `UNKNOWN` an element
+ * that is not a text control and a read-only one; `submit` runs `form.requestSubmit()` and
+ * observes the outcome through a `submit` listener registered across the call. Each action
+ * refuses with a `BrowserElementError` naming the reason: `DISABLED` for a disabled control,
+ * `HIDDEN` for an element that does not render, and `UNTRUSTED` for what an untrusted event
+ * cannot do, which is a click or submission that opens another browsing context, a click that
+ * opens a file chooser, and typing into a contenteditable element. A click that activates a
+ * `label`, on the label itself or on a descendant that `matchesBrowserActivation` admits, is
+ * judged by the label's control as well: a disabled control refuses `DISABLED`, and a file input
+ * refuses `UNTRUSTED` as a direct click on it does. A click on an interactive descendant of a
+ * label keeps only its own checks. `role` and `name` read the description the latest outline or
+ * query that encountered the element captured, so a change to the element shows after the next
+ * capture, and a dropped reference keeps its last capture. Every action on an element removed
+ * from its document, collected, or held across a navigation reports `GONE`.
+ *
+ * @example
+ * ```ts
+ * const view = createBrowserDOMView({ document: frame.contentDocument })
+ * await view.elements.outline()
+ * await view.elements.element('e1')?.click()
+ * ```
+ */
+export declare class BrowserDOMElement implements BrowserDOMElementInterface {
+    #private;
+    constructor(input: BrowserDOMElementInput);
+    get reference(): string;
+    get role(): string;
+    get name(): string;
+    click(options?: BrowserCallOptions): Promise<void>;
+    fill(value: string, options?: BrowserCallOptions): Promise<void>;
+    select(values: readonly string[], options?: BrowserCallOptions): Promise<void>;
+    focus(options?: BrowserCallOptions): Promise<void>;
+    read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
+    submit(options?: BrowserCallOptions): Promise<void>;
+}
+
+/**
+ * Binds a DOM element to its reference and the manager that minted it.
+ *
+ * @remarks
+ * - `reference` — the reference the manager minted for the element
+ * - `description` — returns the role and accessible name the latest capture that encountered
+ *   the element recorded; after the manager drops the reference it keeps returning that capture
+ * - `node` — a weak reference to the element the reference names, so a removed element can be
+ *   collected; an element that no longer dereferences reports `GONE`
+ * - `current` — true while the manager still holds the reference; false otherwise
+ * - `navigation` — reads the epoch of the element's own document, which every reading records;
+ *   it advances when that document or the view's document navigates
+ */
+export declare interface BrowserDOMElementInput {
+    readonly reference: string;
+    readonly description: () => Pick<BrowserElementInterface, 'role' | 'name'>;
+    readonly node: WeakRef<Element>;
+    readonly current: () => boolean;
+    readonly navigation: BrowserEpochFunction;
+}
+
+/**
+ * Provides DOM actions through a stable element reference, without trusted input.
+ *
+ * @remarks
+ * No action grants user activation, and every event an action dispatches itself carries
+ * `isTrusted` `false`. `submit` submits the element's form through `requestSubmit()`, passing the
+ * element as the submitter when it is a submit button; the `submit` event that call fires is
+ * generated by the browser and carries `isTrusted` `true`.
+ */
+export declare interface BrowserDOMElementInterface extends BrowserElementInterface {
+}
+
+/**
+ * Outlines a DOM document from its elements and binds stable references to the interactive ones.
+ *
+ * @remarks
+ * Rows come in document order from a `TreeWalker` over the flat tree: an open shadow root
+ * contributes its rows in place of its host's children, a `slot` its assigned nodes, and a
+ * same-origin `iframe` its document's rows, while a cross-origin one renders
+ * `iframe "NAME" (cross-origin, not readable)`. An element that `matchesBrowserHidden` reports is
+ * omitted with its subtree, a scope root in such a subtree yields no row, and an element that
+ * `matchesBrowserInvisible` reports yields no row of its own. An element whose role
+ * `BROWSER_INTERACTIVE_ROLES` names receives a reference bound through a `WeakRef`, which never
+ * changes while the manager holds it, and a reference number is never reused. Every outline or
+ * query that encounters a bound element records its role and name afresh, and the element's
+ * wrapper reports that latest capture, also after the manager drops the reference. A reference
+ * and a reading from any walked document record that document's epoch, which advances on its own
+ * navigation events and on the view's; that document's `pagehide` drops its references. A form
+ * carrying a `toolname` attribute renders `[tool=NAME]` after its role and name. A `select` row
+ * is followed by one `option` row per option, named by its label. Whitespace between two texts of
+ * one block renders as one space, as a rendered `br` between them does, and texts with neither
+ * between them stay joined. A CSS query
+ * searches the document the view drives, not its child documents or shadow trees. After the
+ * input's `signal` aborts, `outline`, `find`, and `wait` reject with its reason.
+ *
+ * `wait` parks a `BrowserDOMWait` bound to the view's lifetime over every root that
+ * `collectBrowserRoots` reaches from its scope, reconciled at every observed mutation and frame
+ * `load`. A shadow root attached after the wait began is a declared limit: the wait discovers it
+ * at the next observed mutation or `load`, so a match inserted there with no other observed
+ * change is not seen before the deadline.
+ *
+ * @example
+ * ```ts
+ * const view = createBrowserDOMView({ document: frame.contentDocument })
+ * const outline = await view.elements.outline()
+ * const [save] = await view.elements.find({ role: 'button', name: 'save' })
+ * ```
+ */
+export declare class BrowserDOMElementManager implements BrowserElementManagerInterface<BrowserDOMElementInterface> {
+    #private;
+    constructor(input: BrowserDOMElementManagerInput);
+    outline(options?: BrowserOutlineOptions): Promise<BrowserOutline>;
+    find(query: BrowserElementQuery, options?: BrowserCallOptions): Promise<readonly BrowserDOMElementInterface[]>;
+    wait(query: BrowserElementQuery, options?: BrowserElementWaitOptions): Promise<readonly BrowserDOMElementInterface[]>;
+    element(reference: string): BrowserDOMElementInterface | undefined;
+    elements(): readonly BrowserDOMElementInterface[];
+    clear(): void;
+}
+
+/**
+ * Binds a DOM element manager to the view that owns it.
+ *
+ * @remarks
+ * - `document` — returns the document the view drives at the moment of the call
+ * - `navigation` — reads the view's navigation epoch, which every reading records
+ * - `signal` — the view's lifetime; it aborts when the view is destroyed, every wait and
+ *   navigation listener the manager starts ends with it, and after it aborts `outline`, `find`,
+ *   and `wait` reject with its reason
+ */
+export declare interface BrowserDOMElementManagerInput {
+    readonly document: () => Document;
+    readonly navigation: BrowserEpochFunction;
+    readonly signal: AbortSignal;
+}
+
+/**
+ * Reads and drives a DOM document from a realm that can reach it, without trusted input.
+ *
+ * @remarks
+ * The view follows the window of the document it was given, so after that window navigates it
+ * drives the window's next document. A reading records the view's navigation epoch, and reports
+ * stale after the epoch advances. The epoch advances on the Navigation API's `navigatesuccess`
+ * where the window has that API, on `popstate` and `hashchange` where it does not, on `pagehide`,
+ * and when the window's document changes. A `pushState` in a window without the Navigation API
+ * fires none of those events, so a reading there stays current across it. A cross-document
+ * navigation also clears every element reference. `destroy()` releases the listeners and every
+ * reference, and fails every pending wait with a `BrowserError` coded
+ * `BROWSER_DOCUMENT_DESTROYED`; after it, `title()`, `read()`, `wait()`, and the element manager's
+ * `outline()`, `find()`, and `wait()` reject with that error, and a second `destroy()` does
+ * nothing more. `trusted` is `false`: no action grants user activation, and
+ * every event the view's actions dispatch themselves carries `isTrusted` `false`. The `submit`
+ * event that `requestSubmit()` fires during a `submit` is generated by the browser and carries
+ * `isTrusted` `true`.
+ *
+ * @example
+ * ```ts
+ * const view = createBrowserDOMView({ document: frame.contentDocument })
+ * const reading = await view.read()
+ * reading.text().text
+ * ```
+ */
+export declare class BrowserDOMView implements BrowserDOMViewInterface {
+    #private;
+    constructor(options: BrowserDOMViewOptions);
+    get url(): string;
+    get trusted(): boolean;
+    get elements(): BrowserElementManagerInterface<BrowserDOMElementInterface>;
+    title(options?: BrowserCallOptions): Promise<string>;
+    read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
+    wait(text: string, options?: BrowserCallOptions): Promise<void>;
+    destroy(): void;
+}
+
+/** Provides the document operations of a view that drives a DOM document in its own realm. */
+export declare interface BrowserDOMViewInterface extends BrowserViewInterface {
+    readonly elements: BrowserElementManagerInterface<BrowserDOMElementInterface>;
+    /** Releases the navigation listeners and every element reference. */
+    destroy(): void;
+}
+
+/**
+ * Configures a view that drives one browser document.
+ *
+ * @remarks
+ * - `document` — the document the view reads and acts on; the view follows its window, so a
+ *   navigation of that window moves the view to the window's next document
+ * - `own` — if `true`, admits the realm's own `globalThis.document`; if `false`, refuses it,
+ *   because an action that navigates the realm's own document cannot return. Default: `false`
+ */
+export declare interface BrowserDOMViewOptions {
+    readonly document: Document;
+    readonly own?: boolean;
+}
+
+/**
+ * Parks one condition on DOM mutations until it holds, with one deadline and no other timer.
+ *
+ * @remarks
+ * The wait observes every root `roots` returns, each through a `MutationObserver` of that root's
+ * realm, and re-reads the roots after every mutation batch and every capture-phase `load` in an
+ * observed root: a same-origin frame or an open shadow root that appears joins the observation,
+ * and a root that departed (a replaced frame document, a removed shadow root) leaves it, with its
+ * observer disconnected and its `load` listener removed. The check runs before the wait parks and
+ * again after every subscription, and no check runs once the deadline, counted from `start`, has
+ * passed, which the wait reads again after `roots` returns. The wait settles one time: on the
+ * check's first value, on the signal's abort with its reason, at the deadline with
+ * `BROWSER_WAIT_TIMEOUT`, on a `pagehide` in the first root's window with `GONE`, or with whatever
+ * the check or the roots function throws. A signal that aborts while `check` or `roots` runs
+ * settles the wait with its reason, and wins over a value that same check returns. Settlement
+ * disconnects every observer and removes every listener synchronously, so a mutation queued
+ * before it runs no check, and a `roots` or `check` that settles the wait from inside leaves no
+ * observer, listener, or further check behind.
+ *
+ * A shadow root attached after the wait began is a declared limit: attaching one fires no
+ * mutation record and no event, so the wait discovers it at the next mutation or `load` it
+ * observes, and a match inserted into it with no other observed change is not seen before the
+ * deadline. The wait never polls to close that gap.
+ *
+ * @example
+ * ```ts
+ * const ready = await new BrowserDOMWait({
+ * 	roots: () => [document],
+ * 	check: () => document.querySelector('#ready') ?? undefined,
+ * 	timeout: 1_000,
+ * 	start: performance.now(),
+ * 	subject: 'Ready wait',
+ * }).execute()
+ * ```
+ */
+export declare class BrowserDOMWait<T> implements BrowserDOMWaitInterface<T> {
+    #private;
+    constructor(wait: BrowserMutationWait<T>);
+    get roots(): readonly Node[];
+    execute(): Promise<T>;
+}
+
+/** Settles one wait parked on DOM mutations. */
+export declare interface BrowserDOMWaitInterface<T> {
+    /** The roots the wait observes at this moment; empty before it parks and after it settles. */
+    readonly roots: readonly Node[];
+    /**
+     * Resolves the first value the check returns other than `undefined`, then releases every
+     * observer, the deadline timer, and every listener.
+     */
+    execute(): Promise<T>;
+}
+
+/**
+ * Describes one wait parked on DOM mutations.
+ *
+ * @remarks
+ * - `roots` — returns the documents and shadow roots whose mutations re-run the check; the wait
+ *   re-reads it after every mutation batch and every `load` in an observed root, observing the
+ *   roots that appeared and releasing the ones that departed, and a `pagehide` in the first
+ *   root's window fails the wait
+ * - `check` — returns the value the wait settles on, or `undefined` to keep waiting
+ * - `timeout` — ms from `start` before the wait fails
+ * - `start` — the `now()` reading the deadline counts from, taken when the calling method was
+ *   entered
+ * - `now` — reads the clock every remaining-budget calculation uses, the deadline timer's delay
+ *   included; it shares its time origin with `start`. Default: `performance.now()`
+ * - `signal` — aborts the wait with the signal's reason
+ * - `subject` — names the wait in its timeout message
+ */
+export declare interface BrowserMutationWait<T> {
+    readonly roots: () => readonly Node[];
+    readonly check: () => T | undefined;
+    readonly timeout: number;
+    readonly start: number;
+    readonly now?: () => number;
+    readonly signal?: AbortSignal | undefined;
+    readonly subject: string;
+}
+
+/**
+ * Carries the accessible-name traversal context.
+ *
+ * @remarks
+ * - `hidden` — if `true`, admits hidden and invisible content, as the hidden-reference exception
+ *   does for a hidden element that `aria-labelledby` references; if `false`, omits it.
+ *   Default: `false`
+ * - `target` — the element whose name is computed; an embedded control that is the target
+ *   contributes nothing, and any other embedded control contributes its value
+ */
+export declare interface BrowserNameContext {
+    readonly hidden?: boolean;
+    readonly target?: Element;
+}
+
+/**
+ * Collects the tree roots a wait observes under a node: the node's own root, then every open
+ * shadow root and every same-origin frame document at or beneath it, recursively.
+ *
+ * @param root - The document, shadow root, or element to collect under
+ * @returns The roots, the node's own root first; a cross-origin frame contributes none
+ *
+ * @example
+ * ```ts
+ * collectBrowserRoots(document) // [document, ...each open shadow root and frame document]
+ * ```
+ */
+export declare function collectBrowserRoots(root: Document | ShadowRoot | Element): readonly Node[];
+
+/**
+ * Computes the text one node contributes to an accessible name: its own text alternative, or its
+ * content.
+ *
+ * @remarks
+ * A text node contributes its data unless its parent is invisible; a parent without a box of its
+ * own, such as a `slot` or a `display: contents` element, is not invisible. An element
+ * contributes nothing when it is hidden or is a `script` or `style`, and an element that
+ * `matchesBrowserInvisible` reports contributes only what its content contributes, never its
+ * value, `aria-label`, `alt`, or `title`. The context's `hidden` admits both. An embedded control
+ * that is not the context's `target` contributes its value: a text field or a range its `value`,
+ * a `select` its selected options' labels; a password field and the target itself contribute
+ * nothing. Any other element contributes its `aria-label`, the `alt` of an image, or its content
+ * through `readBrowserContent`, and its `title` when those are empty.
+ *
+ * @param node - The node whose contribution is computed
+ * @param context - The traversal context. Default: no hidden content and no target
+ * @returns The untrimmed contribution
+ *
+ * @example
+ * ```ts
+ * const image = document.createElement('img')
+ * image.alt = 'Save'
+ * computeBrowserAlternative(image) // 'Save'
+ * ```
+ */
+export declare function computeBrowserAlternative(node: Node, context?: BrowserNameContext): string;
+
+/**
+ * Computes the accessible name of an element, trimmed and whitespace-collapsed.
+ *
+ * @remarks
+ * The steps follow the accessible-name computation, first match wins: the elements
+ * that `aria-labelledby` references in the element's own tree, each through
+ * `computeBrowserAlternative` with hidden content admitted when the referenced element is itself
+ * hidden (`matchesBrowserOmitted` or `matchesBrowserInvisible`), `aria-label`, the `label` of an
+ * `option`, the value of an `input` button, the `alt` of an
+ * image, the text of every associated `label`, the element's own content for a role in
+ * `BROWSER_CONTENT_NAMED_ROLES`, then the `title` attribute, then the `placeholder` of a text
+ * control. Every traversal carries the element as its `target`, so an embedded control
+ * contributes its value unless it is the element being named. The `title` step follows content because a tooltip names an element only when nothing
+ * else does.
+ *
+ * @param element - The element to name
+ * @param role - The element's role. Default: `computeBrowserRole(element)`
+ * @returns The name, or the empty string when no step names the element
+ *
+ * @example
+ * ```ts
+ * const button = document.createElement('button')
+ * button.textContent = ' Save  draft '
+ * computeBrowserName(button) // 'Save draft'
+ * ```
+ */
+export declare function computeBrowserName(element: Element, role?: string | undefined): string;
+
+/**
+ * Computes the ARIA role of an element from its `role` attribute or its implicit mapping.
+ *
+ * @remarks
+ * The explicit role is the first token of the `role` attribute, with `presentation` folded into
+ * its synonym `none`. Without one, the role follows the HTML Accessibility API Mappings
+ * specification through `BROWSER_IMPLICIT_ROLES`, after the element-specific conditions that
+ * table cannot express: a link needs `href`, a `select` with `multiple` or a `size` above 1 is a
+ * `listbox`, an `img` with an empty `alt` is `none`, a `header` or `footer` inside sectioning
+ * content has no landmark role, a `section` or `form` needs an accessible name, a text input with
+ * a `list` is a `combobox`, and a `th` with `scope="row"` is a `rowheader`.
+ *
+ * @param element - The element to classify
+ * @returns The role, or `undefined` when the element maps to no role
+ *
+ * @example
+ * ```ts
+ * const input = document.createElement('input')
+ * input.type = 'checkbox'
+ * computeBrowserRole(input) // 'checkbox'
+ * ```
+ */
+export declare function computeBrowserRole(element: Element): string | undefined;
+
+/**
+ * Computes the text an element's content contributes to an accessible name, in the flat tree,
+ * trimmed and whitespace-collapsed.
+ *
+ * @remarks
+ * The text is what `readBrowserContent` reads, normalized.
+ *
+ * @param root - The element or shadow root whose content is read
+ * @param context - The traversal context. Default: no hidden content and no target
+ * @returns The trimmed, whitespace-collapsed text
+ *
+ * @example
+ * ```ts
+ * const link = document.createElement('a')
+ * link.innerHTML = '<div>Cars</div><div>Search the fleet</div>'
+ * document.body.append(link)
+ * computeBrowserText(link) // 'Cars Search the fleet'
+ * ```
+ */
+export declare function computeBrowserText(root: Element | ShadowRoot, context?: BrowserNameContext): string;
+
+/**
+ * Creates a view that reads and drives a DOM document without trusted input.
+ *
+ * @param options - The driven document, and `own` to admit the realm's own document
+ * @returns A {@link BrowserDOMViewInterface} over the document's window
+ * @throws Thrown when `document` is not a document attached to a window, with the code
+ * `BROWSER_DOCUMENT`, and when it is `globalThis.document` without `own: true`, with the code
+ * `BROWSER_DOCUMENT_OWN`.
+ *
+ * @example
+ * ```ts
+ * const frame = document.createElement('iframe')
+ * document.body.append(frame)
+ * const view = createBrowserDOMView({ document: frame.contentDocument })
+ * await view.elements.outline() // { text: 'page "" about:blank\n(0 of 0 elements)', … }
+ * ```
+ */
+export declare function createBrowserDOMView(options: BrowserDOMViewOptions): BrowserDOMViewInterface;
+
+/**
+ * Creates a `BrowserToolsetInterface` that publishes the five view tools over a DOM document and
+ * adopts a source's page tools beside them.
+ *
+ * @remarks
+ * The toolset runs over a view {@link createBrowserDOMView} creates for `document`, so it
+ * advertises `look`, `read`, `click`, `type`, and `wait`, and a click or type receipt ends with
+ * ` (untrusted event)`. `source` supplies page tools, which the toolset adopts during `start()`
+ * and again on every `change`; `toolset.native` never includes them, so publishing it to a
+ * registry leaves that registry's own tools alone. The view belongs to the toolset: `destroy()`
+ * removes the toolset's tools, then destroys the view, which releases its listeners and fails
+ * its pending waits, and a construction that throws destroys the view before it rethrows.
+ * `journeys` adds `record`, `save`, `journeys`, `edit`, and `replay` at construction; a replay
+ * runs the steps the document placement executes.
+ *
+ * @param options - The driven document, `own`, the page-tool source, the manager, the bound, the
+ * journey stores, and the emitter hooks
+ * @returns A {@link BrowserToolsetInterface} whose `view` drives the document
+ * @throws Thrown when `document` is not a document attached to a window, with the code
+ * `BROWSER_DOCUMENT`, when it is `globalThis.document` without `own: true`, with the code
+ * `BROWSER_DOCUMENT_OWN`, and when `limit` is not a positive integer.
+ *
+ * @example
+ * ```ts
+ * const toolset = createDocumentToolset({ document: frame.contentDocument, source: bridge })
+ * await toolset.start()
+ * await toolset.tools.execute({ id: '1', name: 'look', arguments: { what: 'form' } })
+ * ```
+ */
+export declare function createDocumentToolset(options: BrowserDocumentToolsetOptions): BrowserToolsetInterface;
+
+/**
+ * Creates a CDP transport over the browser's native `WebSocket`.
+ *
+ * @param options - The CDP WebSocket debugger URL, the opening deadline, and emitter hooks
+ * @returns A {@link CDPTransportInterface} a `CDPClient` sends and receives frames over
+ *
+ * @example
+ * ```ts
+ * const client = createCDPClient({
+ * 	transport: createSocketCDPTransport({ url: 'ws://127.0.0.1:9222/devtools/browser/abc' }),
+ * })
+ * await client.connect()
+ * ```
+ */
+export declare function createSocketCDPTransport(options: SocketCDPTransportOptions): CDPTransportInterface;
+
+/**
+ * Narrows a value to a `Document` attached to a window.
+ *
+ * @param value - The value to test
+ * @returns `true` for an object that is a `Document` with a `defaultView`, otherwise `false`
+ */
+export declare function isBrowserDocument(value: unknown): value is Document;
+
+/**
+ * Subscribes one listener to a window's navigation events until a signal aborts.
+ *
+ * @remarks
+ * The listener receives the Navigation API's `navigatesuccess` where the window has that API, and
+ * `popstate` and `hashchange` where it does not, plus `pagehide` in both cases. A `pushState` in a
+ * window without the Navigation API fires none of those events.
+ *
+ * @param window - The window whose navigation events are observed
+ * @param listener - Receives each event; `event.type` tells an unload from a same-document
+ * navigation
+ * @param signal - Removes every subscription when it aborts
+ *
+ * @example
+ * ```ts
+ * const release = new AbortController()
+ * listenBrowserNavigation(frame.contentWindow, (event) => console.log(event.type), release.signal)
+ * ```
+ */
+export declare function listenBrowserNavigation(window: Window, listener: (event: Event) => void, signal: AbortSignal): void;
+
+/**
+ * Checks whether a click on an element activates the `label` that contains it, following the
+ * HTML label activation rule.
+ *
+ * @remarks
+ * The click activates the label when the target is the label itself, or when no element on the
+ * path from the target up to the label, the target included, matches
+ * `BROWSER_INTERACTIVE_CONTENT`.
+ *
+ * @param target - The element the click lands on
+ * @param label - The label that contains the target, or the target itself
+ * @returns True if the click activates the label; false otherwise
+ *
+ * @example
+ * ```ts
+ * const label = document.createElement('label')
+ * label.innerHTML = '<a href="#help">Help</a> <span>Photo</span>'
+ * matchesBrowserActivation(label.querySelector('a'), label) // false
+ * matchesBrowserActivation(label.querySelector('span'), label) // true
+ * ```
+ */
+export declare function matchesBrowserActivation(target: Element, label: Element): boolean;
+
+/**
+ * Checks whether an element starts a block of its own, the unit that separates runs of text.
+ *
+ * @param element - The element to test
+ * @returns True if the element is a `br`, or its computed `display` is neither inline-level,
+ * `contents`, nor `none`; false otherwise
+ *
+ * @example
+ * ```ts
+ * const paragraph = document.createElement('p')
+ * document.body.append(paragraph)
+ * matchesBrowserBlock(paragraph) // true
+ * ```
+ */
+export declare function matchesBrowserBlock(element: Element): boolean;
+
+/**
+ * Checks whether an element and its subtree are hidden from the rendered page.
+ *
+ * @param element - The element to test
+ * @returns True if the element carries `hidden` or `aria-hidden="true"`, or its computed
+ * `display` is `none`; false otherwise
+ *
+ * @example
+ * ```ts
+ * const note = document.createElement('p')
+ * note.hidden = true
+ * matchesBrowserHidden(note) // true
+ * ```
+ */
+export declare function matchesBrowserHidden(element: Element): boolean;
+
+/**
+ * Checks whether an element renders nothing visible of its own.
+ *
+ * @remarks
+ * An element whose computed `visibility` is `hidden` or `collapse` is invisible. An element with
+ * `display: contents` has no box of its own but renders its descendants, so it is not invisible.
+ * Any other element is invisible when `checkVisibility` with `visibilityProperty` and
+ * `contentVisibilityAuto` reports it, which covers an element without a box and one skipped by
+ * `content-visibility: auto`. A descendant can still be visible, so the rule omits the element's
+ * own row and text and keeps its subtree. An `option` or `optgroup` inside a `select` is
+ * invisible where the `select` is, because a drop-down renders its options outside the page's
+ * boxes. Zero-size and off-screen elements stay visible. An
+ * element in a document without a window is never invisible, because nothing renders it.
+ *
+ * @param element - The element to test
+ * @returns True if the element renders nothing visible of its own; false otherwise
+ *
+ * @example
+ * ```ts
+ * const button = document.createElement('button')
+ * button.style.visibility = 'hidden'
+ * document.body.append(button)
+ * matchesBrowserInvisible(button) // true
+ * ```
+ */
+export declare function matchesBrowserInvisible(element: Element): boolean;
+
+/**
+ * Checks whether an element sits in an omitted subtree: the element or a flat-tree ancestor that
+ * `readBrowserParent` reaches matches `matchesBrowserHidden`, through assigned slots, shadow
+ * hosts, and the frame elements of same-origin documents.
+ *
+ * @param element - The element to test
+ * @returns True if the element or an ancestor is hidden; false otherwise
+ *
+ * @example
+ * ```ts
+ * const section = document.createElement('section')
+ * section.hidden = true
+ * const button = section.appendChild(document.createElement('button'))
+ * matchesBrowserOmitted(button) // true
+ * ```
+ */
+export declare function matchesBrowserOmitted(element: Element): boolean;
+
+/**
+ * Checks whether activating an element opens another browsing context.
+ *
+ * @remarks
+ * A link with `href` navigates its `target`, and a form, or a submit button inside one, navigates
+ * the submitter's `formtarget` or the form's `target`; either falls back to the target of the
+ * document's `base` element. `_blank` opens another context, and a target in
+ * `BROWSER_CONTEXT_TARGETS` does not. A name reuses the browsing context carrying it when the
+ * element's window, an ancestor window, or a frame element in one of their documents carries it,
+ * and opens another context otherwise; an ancestor this realm cannot read is skipped.
+ *
+ * @param element - The element an untrusted activation would target
+ * @returns True if the activation opens another browsing context; false otherwise, including
+ * for an element whose activation navigates nothing
+ *
+ * @example
+ * ```ts
+ * const link = document.createElement('a')
+ * link.href = '/cars'
+ * link.target = '_blank'
+ * matchesBrowserPopup(link) // true
+ * ```
+ */
+export declare function matchesBrowserPopup(element: Element): boolean;
+
+/**
+ * Reads the nearest block container of an element, the unit that separates runs of text.
+ *
+ * @param element - The element to start from, or `null` for a node without a parent element
+ * @param root - The node that bounds the search
+ * @returns The nearest inclusive ancestor, below `root`, that `matchesBrowserBlock` reports;
+ * `root` when none is
+ *
+ * @example
+ * ```ts
+ * const strong = document.createElement('strong')
+ * const paragraph = document.createElement('p')
+ * paragraph.append(strong)
+ * document.body.append(paragraph)
+ * readBrowserBlock(strong, document.body) // paragraph
+ * ```
+ */
+export declare function readBrowserBlock(element: Element | null, root: Node): Node;
+
+/**
+ * Reads the URL, title, and serialized markup a DOM reading is built from, refusing a capture
+ * over the result limit before any parse.
+ *
+ * @remarks
+ * The measure is the length of `JSON.stringify({ url, title, html })`, the form the CDP capture
+ * guard compares with `BROWSER_RESULT_LIMIT`, so a character JSON escapes counts as its escape
+ * sequence. A reading a caller builds with `createBrowserReading` passes through no limit.
+ *
+ * @param node - The element whose `outerHTML` is captured; its owner document supplies `URL`
+ * and `title`
+ * @returns The capture's `url`, `title`, and `html`
+ * @throws Thrown as a `BrowserResultLimitError` when the serialized capture is longer than
+ * `BROWSER_RESULT_LIMIT` characters, with `length` and `limit` in its context.
+ */
+export declare function readBrowserCapture(node: Element): BrowserReadingInput;
+
+/**
+ * Reads the untrimmed text an element's content contributes to an accessible name, in the flat
+ * tree.
+ *
+ * @remarks
+ * The content is the open shadow root's children for a shadow host, the flattened assigned nodes
+ * for a `slot`, and the child nodes otherwise. Each child contributes what
+ * `computeBrowserAlternative` returns for it, and a child that `matchesBrowserBlock` reports is
+ * set apart from its neighbours by a space. Whitespace at the edges of an inline child is kept,
+ * so `<b>Go </b>home` reads `Go home`.
+ *
+ * @param root - The element or shadow root whose content is read
+ * @param context - The traversal context. Default: no hidden content and no target
+ * @returns The untrimmed text
+ *
+ * @example
+ * ```ts
+ * const label = document.createElement('span')
+ * label.innerHTML = '<b>Go </b>home'
+ * document.body.append(label)
+ * readBrowserContent(label) // 'Go home'
+ * ```
+ */
+export declare function readBrowserContent(root: Element | ShadowRoot, context?: BrowserNameContext): string;
+
+/**
+ * Reads an element's parent in the flat tree: the slot it is assigned to in an open shadow root,
+ * its parent element, the host of the open shadow root it sits at the top of, or the frame
+ * element of its same-origin document.
+ *
+ * @param element - The element whose parent is read
+ * @returns The parent, or `null` at the top of a top-level or cross-origin-framed document
+ *
+ * @example
+ * ```ts
+ * readBrowserParent(document.body) // document.documentElement
+ * readBrowserParent(document.documentElement) // null in a top-level document
+ * ```
+ */
+export declare function readBrowserParent(element: Element): Element | null;
+
+/**
+ * Moves a tree walker past the subtree of its current node.
+ *
+ * @param walker - The walker to move; its root bounds the move
+ * @returns The first node after the subtree in document order, or `null` when the walk is done
+ *
+ * @example
+ * ```ts
+ * const walker = document.createTreeWalker(document.body)
+ * walker.nextNode()
+ * skipBrowserSubtree(walker) // the first node after the body's first child and its descendants
+ * ```
+ */
+export declare function skipBrowserSubtree(walker: TreeWalker): Node | null;
+
+/**
+ * Provides a raw CDP text transport over the browser's native `WebSocket`.
+ *
+ * @remarks
+ * `start()` resolves on the socket's `open` event and rejects with a `BrowserConnectionError`
+ * carrying `url` for a URL whose scheme is not `ws:` or `wss:`, for a URL the `WebSocket`
+ * constructor refuses (one with a fragment), for a socket that fails or closes before it opens,
+ * and at the `timeout` deadline. Concurrent and repeated `start()` and `close()`
+ * calls share their active transition, and a later `start()` opens a fresh socket after the
+ * prior one closes. A close the remote end initiates emits `close`. The driven Chromium must
+ * allow the caller's origin through `--remote-allow-origins`.
+ *
+ * @example
+ * ```ts
+ * const transport = new SocketCDPTransport({ url: 'ws://127.0.0.1:9222/devtools/browser/abc' })
+ * await transport.start()
+ * await transport.close()
+ * ```
+ */
+export declare class SocketCDPTransport implements CDPTransportInterface {
+    #private;
+    constructor(options: SocketCDPTransportOptions);
+    get emitter(): EmitterInterface<CDPTransportEventMap>;
+    start(): Promise<void>;
+    send(data: string): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Configures a CDP transport over the browser's `WebSocket`.
+ *
+ * @remarks
+ * - `url` — the CDP WebSocket debugger URL, with a `ws:` or `wss:` scheme
+ * - `timeout` — ms before an opening handshake fails. Default: `BROWSER_DEFAULT_TIMEOUT_MS`
+ *
+ * The driven Chromium must be started with `--remote-allow-origins` naming the caller's origin;
+ * otherwise it refuses the handshake and `start` rejects.
+ */
+export declare interface SocketCDPTransportOptions {
+    readonly on?: EmitterHooks<CDPTransportEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly url: string;
+    readonly timeout?: number;
+}
+
+export { }