Skip to content
Registry

browser

v0.2.1-experimental

A browser on the iii bus - shared Chromium with persistent, restorable tabs and incognito tabs. Navigate, act, read the page console, pick elements. Also parses HTML natively without a browser (browser::* - css/xpath/regex, element search, markdown).

license: Apache-2.0automationbrowsercdpchromiumextractionparsingscrapingweb

Install

bash
iii trigger compose::add worker=browser@0.2.1-experimental

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions31

browser::act

Function

Interact with the page: click (left/right/middle, single or double), hover, type, press, or scroll. Address elements with a [ref=eN] handle from browser::snapshot (or a pick), or raw viewport coordinates.

Request
  • actionstringrequired

    `click`, `hover`, `type`, `press`, or `scroll`.

  • buttonstring

    Mouse button for `click`: `left` (default), `right`, or `middle`.

  • click_countinteger· uint32min 0

    Clicks in the gesture: 2 double-clicks (`click` only, default 1).

  • delta_ynumber· double

    Scroll distance in pixels; positive scrolls down (`scroll`).

  • keystring

    Key name for `press`: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown.

  • refstring

    Element ref from `browser::snapshot` (`e3`) or `browser::picked` (`p1`). Refs die on navigation; re-snapshot after.

  • session_idstringrequired
  • textstring

    Text to insert (`type`).

  • xnumber· double

    Viewport x, when acting by coordinates instead of ref.

  • ynumber· double

    Viewport y, when acting by coordinates instead of ref.

Response
  • detailstringrequired

    What was done, for the transcript.

  • okbooleanrequired

browser::console::read

Function

Read the session's captured console: console.* calls, uncaught exceptions, and browser-level log entries. Filter with pattern/level and page with since_seq instead of dumping everything.

Request
  • levelstring

    Only entries at this level: `log`, `info`, `warning`, `error`, `debug`, `exception`. `error` also matches `exception`.

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to entry text. Use it: dumping an unfiltered console wastes the caller's context.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • levelstringrequired

      `log`, `info`, `warning`, `error`, `debug`, or `exception`.

    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • sourcestring

      `url:line` of the emitting frame, when known.

    • textstringrequired
    • timestampinteger· int64required
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::doctor

Function

Read-only environment diagnostics: which Chromium the worker would launch, its version, session capacity, and any degraded capability with how to enable it. Never starts a browser.

Request
Empty object
Response
  • active_sessionsinteger· uint64requiredmin 0
  • allowed_schemesstring[]required
  • attach_enabledbooleanrequired

    Whether attach mode is enabled (allow_attach).

  • chromium_pathstring
  • chromium_versionstring
  • headless_defaultbooleanrequired
  • issuesobject[]required
    • enable_howstringrequired
    • whatstringrequired
  • max_sessionsinteger· uint64requiredmin 0
  • okbooleanrequired

    True when sessions can start right now.

  • recording_availablebooleanrequired

    Whether ffmpeg is on PATH, which browser::recording requires.

browser::dom::read

Function

Read the DOM as a tree of tags with id/class and refs. Structure-oriented complement to browser::snapshot; read deep subtrees by passing a ref.

Request
  • depthinteger· uint32min 0

    Levels of children to include (default 3).

  • refstring

    Subtree root from an earlier ref (`e3`/`p1`) or dom node. Omit for the document root.

  • session_idstringrequired
Response
  • rootobjectrequired

    One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.

    • child_countinteger· uint32requiredmin 0

      Total children in the document, which may exceed `children` returned at this depth.

    • childrenunknown[]
    • classesstring
    • idstring
    • refstringrequired
    • tagstringrequired

      Lowercase tag (`div`, `button`) or node name (`#text`).

    • textstring

      Trimmed text content for text nodes.

  • truncatedbooleanrequired

    True when the node cap cut the tree short; read a subtree via `ref`.

browser::evaluate

Function

Evaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.

Request
  • expressionstringrequired

    JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on evaluation; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`.

  • okbooleanrequired
  • valueunknown

    JSON completion value when `ok`.

browser::execute

Function

Run a multi-step async JavaScript script in the page: top-level await and return work, with log(...), sleep(ms), waitFor(selector), and a state object that persists across execute calls for the session. One call replaces a chain of act/evaluate round-trips; returns { result, logs, state }.

Request
  • codestringrequired

    Async JavaScript body run in the page. Top-level `await` and `return` work. In scope: `state` (JSON object persisted across execute calls for the session), `log(...)` (collected into the response), `sleep(ms)`, and `waitFor(selector, { timeout })`. Return plain JSON.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the run; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`. A "context destroyed" error usually means the script navigated; split the script at the navigation.

  • logsstring[]required

    `log(...)` output collected during the run, in order.

  • okbooleanrequired
  • resultunknown

    The script's return value when `ok`.

  • stateunknownrequired

    Session state after the run; the next execute call sees this as `state`.

browser::frame

Function

Internal: newest screencast frame, or nothing when since_frame is still current. No capture round-trip; poll fast. Not an agent function.

Request
  • session_idstringrequired
  • since_frameinteger· uint64min 0

    Frame cursor from the previous read; when the newest frame still has this seq the response omits `frame` (nothing changed, nothing to redraw).

Response
  • activebooleanrequired

    False when no screencast is running (call screencast::start first).

  • framestring

    Base64 JPEG of the newest frame; absent when `since_frame` is still current or no frame has arrived yet.

  • frame_seqinteger· uint64requiredmin 0
  • heightinteger· uint32requiredmin 0

    Page-viewport height the frame maps to.

  • timestampinteger· int64required
  • widthinteger· uint32requiredmin 0

    Page-viewport width the frame maps to (input coordinate space).

browser::handoff

Function

Pause a session for a step only a human can do (CAPTCHA, 2FA, payment): show an in-page continue banner and block until the human clicks it, a browser::handoff::confirm call resolves it, or the timeout elapses. Human acknowledgment is not proof — verify the expected page state after it returns.

Request
  • instructionsstringrequired

    What the human must do before the call continues. Shown in the in-page banner and the handoff-requested event.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Give up after this long and return with `via: "timeout"`. Defaults to the config default; clamped to `max_timeout_ms`. Set generously; a human is slow.

Response
  • confirmedbooleanrequired

    True when a human confirmed; false when the wait timed out.

  • handoff_idstringrequired
  • urlstringrequired

    The page URL when the wait ended, so the caller can verify the step actually landed (human acknowledgment is not proof).

  • viastringrequired

    How the confirmation arrived: `in_page`, `confirm_call`, or `timeout`.

browser::handoff::confirm

Function

Resolve a paused browser::handoff by handoff_id, or the one pending handoff for a session_id. The console calls this when the human confirms outside the page.

Request
  • handoff_idstring

    Confirm a specific handoff by id. Omit to confirm the one pending handoff for `session_id`.

  • session_idstring
Response
  • handoff_idstring
  • okbooleanrequired

    True when a pending handoff matched and was resolved.

browser::history

Function

Go back, go forward, or reload the session's page. Back/forward at the history edge is a no-op with moved=false.

Request
  • actionstringrequired

    `back`, `forward`, or `reload`.

  • session_idstringrequired
Response
  • movedbooleanrequired

    False when back/forward had no entry to move to.

  • okbooleanrequired
  • urlstringrequired

    URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.

browser::navigate

Function

Navigate a session to a URL and wait for the page to load. Element refs from earlier snapshots are invalidated by navigation.

Request
  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the navigation wait; clamped to `max_timeout_ms`.

  • urlstringrequired

    Absolute URL; scheme must be on the configured allowlist.

Response
  • okbooleanrequired
  • timed_outbooleanrequired

    True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.

  • titlestring
  • urlstringrequired

    URL after redirects.

browser::network::read

Function

Read the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.

Request
  • failed_onlyboolean

    Only failed requests (network error or status >= 400).

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to the request URL.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • errorstring
    • failedbooleanrequired
    • methodstringrequired
    • mime_typestring
    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • statusinteger· int64
    • timestampinteger· int64required
    • urlstringrequired
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::on-config-change

Function

Internal: reload browser settings from the authoritative configuration on change.

Request
Empty object
Response
  • okbooleanrequired

browser::pick::hint

Function

Internal: element preview at a viewport point (tag, id, classes, bounds) so the console UI can draw a hover highlight in pick mode. Not an agent function.

Request
  • session_idstringrequired
  • xnumber· doublerequired

    Viewport x of the cursor.

  • ynumber· doublerequired

    Viewport y of the cursor.

Response
  • boundsany of

    Viewport-space box to draw the highlight over.

    any of (2)
    Variant 1
    • heightnumber· doublerequired
    • widthnumber· doublerequired
    • xnumber· doublerequired
    • ynumber· doublerequired
    Variant 2
    valuenull
  • classesstring
  • hitbooleanrequired

    False when no element sits at the point.

  • idstring
  • tagstring

    Lowercase tag name.

browser::pick::resolve

Function

Internal: resolve the element at a clicked viewport point and emit browser::picked. The console calls this on a pick-mode click. Not an agent function.

Request
  • session_idstringrequired
  • xnumber· doublerequired

    Viewport x of the click.

  • ynumber· doublerequired

    Viewport y of the click.

Response
  • okbooleanrequired

browser::pick::start

Function

Internal: enter pick mode so the human can select an element in the console UI. Not an agent function.

Request
  • session_idstringrequired
Response
  • okbooleanrequired

browser::pick::stop

Function

Internal: leave DevTools inspect mode without picking. Idempotent. Not an agent function.

Request
  • session_idstringrequired

    Cancelling pick mode on an unknown session succeeds.

Response
  • okbooleanrequired

browser::recording::start

Function

Record a session's live viewport to a video file (webm or mp4) by piping the screencast through ffmpeg. Turns screencast on if needed. Requires ffmpeg on PATH; browser::doctor reports whether it is available.

Request
  • formatstring

    `webm` (VP9) or `mp4` (H.264). Defaults to webm.

  • pathstringrequired

    Output file path. The extension should match `format`.

  • session_idstringrequired
Response
  • formatstringrequired
  • okbooleanrequired
  • pathstringrequired

browser::recording::stop

Function

Stop a session's recording, finalize the file, and return its path, duration, and frame count. Idempotent: stopping when nothing is recording returns ok=false.

Request
  • session_idstringrequired
Response
  • duration_msinteger· int64required

    Wall-clock duration captured, milliseconds.

  • framesinteger· uint64requiredmin 0

    Frames written to the encoder.

  • okbooleanrequired

    False when no recording was running.

  • pathstring

browser::screencast::start

Function

Internal: start pushing live viewport frames for browser::frame. Console-UI plumbing; agents use browser::screenshot. Not an agent function.

Request
  • session_idstringrequired
Response
  • okbooleanrequired

browser::screencast::stop

Function

Internal: stop the live frame push. Idempotent. Not an agent function.

Request
  • session_idstringrequired

    Stopping the screencast on an unknown session succeeds.

Response
  • okbooleanrequired

browser::screenshot

Function

Capture the session viewport as a viewable JPEG. Use browser::snapshot for machine-readable structure; screenshot when layout or rendering matters.

Request
  • full_pageboolean

    Capture the full scrollable page instead of the viewport.

  • session_idstringrequired
Response
  • contentobject[]required
    • datastring
    • mimestring
    • textstring
    • typestringrequired
  • detailsobjectrequired
    • heightinteger· uint32requiredmin 0
    • session_idstringrequired
    • urlstringrequired
    • widthinteger· uint32requiredmin 0

browser::sessions::attach

Function

Attach a session to an already-running browser over CDP (start Chrome with --remote-debugging-port). Opens a fresh tab the session owns, or adopts an existing user tab by URL substring and releases it untouched on stop. Reaches the real profile with its logins; disabled unless allow_attach is set in config.

Request
  • adopt_url_substringstring

    Adopt the existing tab whose URL contains this substring, exclusively, and release it untouched on stop. Omit to open a fresh tab the session owns and closes on stop. Must match exactly one open tab.

  • cdp_urlstringrequired

    CDP endpoint of the running browser: `http://127.0.0.1:9222` (the worker resolves the WebSocket URL from `/json/version`) or a `ws://` debugger URL directly. Start Chrome with `--remote-debugging-port=9222` to expose one.

  • read_onlyboolean

    Inspection-only session; see browser::sessions::start.

  • urlstring

    URL to open in the fresh tab (ignored when adopting). Omit for about:blank.

Response
  • adoptedbooleanrequired

    True when the session adopted an existing user tab (released, not closed, on stop); false when it opened a fresh tab it owns.

  • read_onlybooleanrequired
  • session_idstringrequired
  • urlstringrequired

browser::sessions::list

Function

List live browser sessions with their current URL and activity.

Request
Empty object
Response
  • sessionsobject[]required
    • console_entriesinteger· uint64requiredmin 0
    • created_msinteger· int64required
    • headlessbooleanrequired
    • last_used_msinteger· int64required
    • read_onlybooleanrequired
    • session_idstringrequired
    • titlestring
    • urlstringrequired

browser::sessions::start

Function

Start an interactive Chromium session and return its session_id. Sessions keep console and network history; stop them with browser::sessions::stop when done.

Request
  • headfulboolean

    Force a visible window for this session, overriding the configured `headless` default.

  • read_onlyboolean

    Inspection-only session: act, evaluate, execute, and styles::write are rejected while navigation, snapshots, reads, and screenshots work. Immutable for the session's lifetime.

  • urlstring

    URL to open immediately. Omit to start on about:blank.

Response
  • headlessbooleanrequired
  • read_onlybooleanrequired
  • session_idstringrequired

    Pass this to every other browser function.

  • urlstringrequired

browser::sessions::stop

Function

Stop a browser session and its Chromium process. Idempotent: stopping an unknown or already-stopped session succeeds with was_running=false.

Request
  • session_idstringrequired

    Session to stop. Stopping an unknown or already-stopped id succeeds.

Response
  • okbooleanrequired
  • was_runningbooleanrequired

    False when the session was already gone.

browser::snapshot

Function

Read the page as an accessibility-tree outline. Lines carry [ref=eN] handles that browser::act accepts; refs stay valid until the next navigation. Prefer this over browser::screenshot; it is cheaper and machine-readable.

Request
  • diffboolean

    Return only what changed since this session's previous snapshot instead of the full outline. Falls back to a full snapshot when there is no baseline (first snapshot, or first after a navigation).

  • session_idstringrequired
Response
  • diffany of

    Present when the caller asked for `diff: true` and a baseline existed. Covers only the emitted nodes of both snapshots; check `truncated` before trusting it as a complete change set.

    any of (2)
    Variant 1
    • addedstring[]required
    • removedstring[]required
    • unchangedinteger· uint64requiredmin 0
    Variant 2
    valuenull
  • generationinteger· uint64requiredmin 0

    Document generation the refs belong to; navigation advances it and kills every ref from earlier generations.

  • titlestring
  • treestringrequired

    Indented outline; lines carry `[ref=eN]` handles for `browser::act`. Empty when `diff` is populated.

  • truncatedbooleanrequired

    True when the tree hit `max_snapshot_nodes` and was cut short. Also the signal that a `diff` may be incomplete: the diff is computed over emitted nodes only, so when either snapshot was truncated a node that was emitted before and capped out now can show up in `removed` even though it still exists (and vice versa for `added`).

  • urlstringrequired

browser::styles::read

Function

Read an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.

Request
  • propertiesstring[]

    Computed property names to return. Omit for a curated design-panel set; pass `["*"]` for every computed property.

  • refstringrequired

    Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.

  • session_idstringrequired
Response
  • inline_stylestring

    The element's inline `style` attribute, when present.

  • propertiesobject[]required
    • namestringrequired
    • valuestringrequired
  • refstringrequired

browser::styles::write

Function

Set one inline CSS property on an element, live in the page. Visual experiment only: the page's source files are untouched, and the edit dies with the next navigation.

Request
  • importantboolean

    Apply with `!important`.

  • propertystringrequired

    CSS property name (`background-color`).

  • refstringrequired

    Element ref to edit.

  • session_idstringrequired
  • valuestringrequired

    CSS value (`#101418`). Empty string removes the inline property.

Response
  • inline_stylestringrequired

    The element's inline `style` attribute after the edit.

  • okbooleanrequired

browser::tabs::list

Function

List the open tabs of a running browser reachable at a CDP endpoint (url, title, and whether a session already adopted each). Read-only; adopt one with browser::sessions::attach.

Request
  • cdp_urlstringrequired

    CDP endpoint of the running browser, as in browser::sessions::attach.

Response
  • tabsobject[]required
    • adoptedbooleanrequired

      True when a session already adopted this tab; it cannot be adopted again until that session stops.

    • titlestring
    • urlstringrequired

browser::ui-content

Function

Serve the browser worker's injected console UI assets (content function for its console:script / console:style triggers).

Request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

Triggers7

browser::console-event

Trigger

A console/log/exception entry was captured on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::handoff-requested

Trigger

A session is paused waiting for a human to complete a step (CAPTCHA, 2FA, payment).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::navigated

Trigger

The session's page committed a navigation.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::network-event

Trigger

A network request was captured (completed or failed) on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::picked

Trigger

The human picked an element in inspect mode.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-started

Trigger

A Chromium session is up and ready.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-stopped

Trigger

A Chromium session ended (stopped, idle, or crashed).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

Search the registry

Find workers, kits and executables, or jump to a page.