@orkestrel/browser 0.0.20 → 0.0.22

package/README.md

@@ -5,7 +5,7 @@
 > and publishes them as agent tools, an in-page face that drives a DOM document with native APIs,
 > and a Node runtime that finds, launches, and connects to the browser itself.
 
-Connect to a running browser or launch one with the `createBrowser` function, open a page, and drive it through stable element references and trusted input. Read the page as Markdown in bounded slices, and hand the whole vocabulary to an agent as `@orkestrel/tool` tools with `createBrowserToolset`. Inside a page, `createDocumentToolset` drives a DOM document with native APIs, and `createSocketCDPTransport` carries the core client over the browser's own `WebSocket`. Record a journey, one user intent kept as JSON, from a model's tool calls or a person's gestures on a page, then list, edit, replay, and forget it through the six journey tools, or compile it with `compileBrowserJourney` into a module a developer runs and customizes. Part of the `@orkestrel` line.
+Connect to a running browser or launch one with the `createBrowser` function, open a page, and drive it through stable element references and trusted input. Read the whole captured page as Markdown or plain text in bounded slices, and hand the whole vocabulary to an agent as `@orkestrel/tool` tools with `createBrowserToolset`. Inside a page, `createDocumentToolset` drives a DOM document with native APIs, and `createSocketCDPTransport` carries the core client over the browser's own `WebSocket`. Record a journey, one user intent kept as JSON, from a model's tool calls or a person's gestures on a page, then list, edit, replay, and forget it through the six journey tools, or compile it with `compileBrowserJourney` into a module a developer runs and customizes. Part of the `@orkestrel` line.
 
 ## Install
 
@@ -40,7 +40,8 @@ const [save] = await page.elements.find({ role: 'button', name: 'Save' })
 await save?.click()
 await page.wait('Saved')
 const reading = await page.read()
-reading.markdown({ limit: 4_000 }) // { text, offset, total }
+reading.markdown({ limit: 4_000 }) // { text, offset, total }; whole page by default
+reading.text({ distill: true }) // main content as plain text
 await page.screenshot({ path: 'example.png' })
 await browser.destroy()
 ```
@@ -53,7 +54,9 @@ import { createToolManager } from '@orkestrel/tool'
 
 const toolset = createBrowserToolset(page, { tools: createToolManager() })
 await toolset.start()
-await toolset.tools.execute({ id: '1', name: 'look', arguments: { what: 'the form' } })
+await toolset.tools.execute({ id: '1', name: 'look', arguments: { search: 'Email' } })
+await toolset.tools.execute({ id: '2', name: 'read', arguments: { search: 'delivery' } })
+await toolset.tools.execute({ id: '3', name: 'plain', arguments: { search: 'confirmation' } })
 await toolset.destroy()
 ```
 

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

@@ -2,7 +2,6 @@ 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';
@@ -11,6 +10,7 @@ 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 { BrowserWaitOptions } from '@orkestrel/browser';
 import type { CDPTransportEventMap } from '@orkestrel/browser';
 import type { CDPTransportInterface } from '@orkestrel/browser';
 import type { EmitterErrorHandler } from '@orkestrel/emitter';
@@ -36,6 +36,14 @@ export declare const BROWSER_CONTEXT_TARGETS: ReadonlySet<string>;
  */
 export declare const BROWSER_DOCUMENT_TIMEOUT_MS = 5000;
 
+/**
+ * Names the roles whose ARIA expansion state the DOM outline reads.
+ *
+ * @remarks
+ * The role set follows the accessibility-tree reading from Chromium 141.0.7390.37.
+ */
+export declare const BROWSER_EXPANDED_ROLES: ReadonlySet<string>;
+
 /**
  * Maps an HTML element to the ARIA role the HTML Accessibility API Mappings specification gives
  * it when it carries no `role` attribute.
@@ -58,6 +66,14 @@ export declare const BROWSER_IMPLICIT_ROLES: ReadonlyMap<string, string>;
  */
 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 roles whose selection state the DOM outline reads.
+ *
+ * @remarks
+ * The role set follows the accessibility-tree reading from Chromium 141.0.7390.37.
+ */
+export declare const BROWSER_SELECTED_ROLES: ReadonlySet<string>;
+
 /** Names the `input` type states whose value an untrusted `fill` sets as typed text. */
 export declare const BROWSER_TYPED_INPUTS: ReadonlySet<string>;
 
@@ -165,8 +181,10 @@ export declare interface BrowserDOMElementInterface extends BrowserElementInterf
  * 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
+ * carrying a `toolname` attribute renders `[tool=NAME]` after its role and name. A row carries
+ * `focused` when its element is the active element of its own document or shadow root. Rows carry
+ * pressed, expanded, and selected states through the Chromium mapping in `readBrowserStates`.
+ * 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
@@ -190,7 +208,7 @@ export declare class BrowserDOMElementManager implements BrowserElementManagerIn
     constructor(input: BrowserDOMElementManagerInput);
     outline(options?: BrowserOutlineOptions): Promise<BrowserOutline>;
     find(query: BrowserElementQuery, options?: BrowserCallOptions): Promise<readonly BrowserDOMElementInterface[]>;
-    wait(query: BrowserElementQuery, options?: BrowserElementWaitOptions): Promise<readonly BrowserDOMElementInterface[]>;
+    wait(query: BrowserElementQuery, options?: BrowserWaitOptions): Promise<readonly BrowserDOMElementInterface[]>;
     element(reference: string): BrowserDOMElementInterface | undefined;
     elements(): readonly BrowserDOMElementInterface[];
     clear(): void;
@@ -246,7 +264,7 @@ export declare class BrowserDOMView implements BrowserDOMViewInterface {
     get elements(): BrowserElementManagerInterface<BrowserDOMElementInterface>;
     title(options?: BrowserCallOptions): Promise<string>;
     read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
-    wait(text: string, options?: BrowserCallOptions): Promise<void>;
+    wait(text: string, options?: BrowserWaitOptions): Promise<void>;
     destroy(): void;
 }
 
@@ -272,14 +290,15 @@ export declare interface BrowserDOMViewOptions {
 }
 
 /**
- * Parks one condition on DOM mutations until it holds, with one deadline and no other timer.
+ * Parks one condition on DOM mutations and finished transitions and animations until it holds, with one deadline and coalesced wake tasks.
  *
  * @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,
+ * realm, and re-reads the roots after every mutation batch, every capture-phase `load`, and
+ * the task after a `BROWSER_WAIT_EVENTS` event 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
+ * observer disconnected and its listeners 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
@@ -291,9 +310,9 @@ export declare interface BrowserDOMViewOptions {
  * 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.
+ * mutation record and no event, so the wait discovers it at the next mutation batch, `load`,
+ * or `BROWSER_WAIT_EVENTS` event 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
@@ -313,7 +332,7 @@ export declare class BrowserDOMWait<T> implements BrowserDOMWaitInterface<T> {
     execute(): Promise<T>;
 }
 
-/** Settles one wait parked on DOM mutations. */
+/** Settles one wait parked on DOM mutations and finished transitions and animations. */
 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[];
@@ -325,11 +344,11 @@ export declare interface BrowserDOMWaitInterface<T> {
 }
 
 /**
- * Describes one wait parked on DOM mutations.
+ * Describes one wait parked on DOM mutations and finished transitions and animations.
  *
  * @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
+ *   re-reads it after every mutation batch, every `load`, and every `BROWSER_WAIT_EVENTS` event 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
@@ -506,7 +525,7 @@ export declare function createBrowserDOMView(options: BrowserDOMViewOptions): Br
  *
  * @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
+ * advertises `look`, `read`, `plain`, `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()`
@@ -526,7 +545,7 @@ export declare function createBrowserDOMView(options: BrowserDOMViewOptions): Br
  * ```ts
  * const toolset = createDocumentToolset({ document: frame.contentDocument, source: bridge })
  * await toolset.start()
- * await toolset.tools.execute({ id: '1', name: 'look', arguments: { what: 'form' } })
+ * await toolset.tools.execute({ id: '1', name: 'look', arguments: { search: 'form' } })
  * ```
  */
 export declare function createDocumentToolset(options: BrowserDocumentToolsetOptions): BrowserToolsetInterface;
@@ -721,15 +740,16 @@ export declare function matchesBrowserPopup(element: Element): boolean;
 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
+ * Reads the URL, title, and rendered 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.
+ * {@link BrowserReadingInput} defines the inert capture, lowering, redaction, and limits.
  *
- * @param node - The element whose `outerHTML` is captured; its owner document supplies `URL`
+ * @param node - The root whose rendered markup 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
@@ -778,6 +798,44 @@ export declare function readBrowserContent(root: Element | ShadowRoot, context?:
  */
 export declare function readBrowserParent(element: Element): Element | null;
 
+/**
+ * Reads the pressed, expanded, and selected states the DOM outline assigns to an element's role.
+ *
+ * @remarks
+ * Only buttons carry pressed state. Expansion follows `BROWSER_EXPANDED_ROLES`, with native
+ * single selects always collapsed. Selection follows `BROWSER_SELECTED_ROLES`: an ARIA token
+ * overrides native option selectedness, and other elements without a token omit selection. Tokens are not
+ * trimmed; values other than `false` are true, except the pressed token `mixed`.
+ *
+ * @param element - The element whose attributes and native state are read
+ * @param role - Its computed accessibility role
+ * @returns Present states, including false, with pressed represented as a tristate string
+ *
+ * @example
+ * ```ts
+ * const button = document.createElement('button')
+ * button.setAttribute('aria-pressed', 'mixed')
+ * readBrowserStates(button, 'button') // { pressed: 'mixed' }
+ * ```
+ */
+export declare function readBrowserStates(element: Element, role: string): Readonly<Record<string, string | boolean>>;
+
+/**
+ * Reads a lowercased ARIA token, preserving whitespace and treating empty or undefined tokens as absent.
+ *
+ * @param element - The element carrying the attribute
+ * @param attribute - The ARIA attribute name
+ * @returns The lowercased token, or `undefined` for a missing, empty, or `undefined` attribute
+ *
+ * @example
+ * ```ts
+ * const button = document.createElement('button')
+ * button.setAttribute('aria-pressed', 'TRUE')
+ * readBrowserToken(button, 'aria-pressed') // 'true'
+ * ```
+ */
+export declare function readBrowserToken(element: Element, attribute: string): string | undefined;
+
 /**
  * Moves a tree walker past the subtree of its current node.
  *