Fetching, sessions and crawl

These reach the network, so they need approval. All return one envelope — {status, url, headers, cookies, encoding} — and can extract or render inline via selectors / format: markdown|text / include_html, so you rarely need a second call to parse what you fetched. Each takes a single url or a bulk urls list.

• browser::fetch — plain HTTP, no browser. The default choice: fastest, cheapest. Safe mode uses bounded native HTTP; certified compat mode uses the frozen curl-impersonate wire behavior.
• browser::dynamic-fetch — real Chromium over CDP, for pages that need JavaScript. Supports wait_selector (+ wait_selector_state), network_idle, and a plain wait.
• browser::stealthy-fetch — same, plus masking of the automation tells a page can read. Escalate here only when dynamic-fetch is detected.
• browser::screenshot-url — page as image tiles (≤1024px wide, ≤6 tiles); says so in the caption when a page is taller than the budget.
• browser::session-open / session-fetch / session-close / session-list — keep cookies and browser state across fetches. HTTP, dynamic and stealthy types are private FIFO sessions with UUID4 hex ids; they never appear in browser::sessions::list and reject interactive ids (session-close on a tab id fails: tabs close with browser::sessions::stop). Close sessions when done.
• browser::crawl — breadth-first from start_urls, same-domain by default, capped by max_pages (20) and max_depth (2). The response holds only a ≤10-item sample; page through every item with browser::crawl::items { crawl_id: , after?, limit? } (retained in memory for 1 h, last 32 crawls). For items live while it runs, bind browser::crawl-item with { crawl_id } first, then call browser::crawl { crawl_id }; missed or dropped events (seq gaps, dropped_events) are read back with browser::crawl::items. stream_name is deprecated and ignored (a warnings entry says so).

Safe mode refuses private, loopback and cloud-metadata addresses on every one of these connections (including redirects and crawl hops). To scrape a local dev server the operator must set browser.scrapling.allow_loopback in worker config. Compat mode reproduces the Python wrapper's unrestricted network behavior and is for trusted calls.

HTML parsing — no session, no browser, no network

These take an html string and never touch Chromium. Use them on HTML from any source (a fetch body, a file, a page you already read).

• browser::extract — declarative selector list in one call: each entry names a css/xpath/regex plus optional attr/html/all, and the response is a {name: value} map. The right default when pulling several fields off one document.
• browser::css / browser::xpath — one query; first: true returns a scalar, otherwise an array. attr pulls an attribute instead of text.
• browser::regex — regex over the document's visible text.
• browser::find — element search by tag/attribute filters (+ optional text regex), BeautifulSoup-style.
• browser::find-by-text / browser::find-by-regex — find elements by their visible text. Responses carry generated css/xpath selectors for each hit, so you can feed one straight back into a query.
• browser::find-similar — give one example element, get its structural siblings. The fast path for "extract every card/row on this page" without hand-writing a selector.
• browser::describe — inspect the first match: attributes, class list, generated selectors, parent/child/sibling counts.
• browser::to-markdown — HTML → compact Markdown (or text), with an optional CSS scope and a main-content cleaner. Use it to shrink a page before putting it in context.

adaptive: true persists element identities in the configured SQLite file. Parse calls are auto-allowed, so do not assume parsing is side-effect-free when adaptive tracking is enabled. Safe mode enforces the configured database quota; compat mode preserves the Python wrapper's unbounded behavior.

Safe and compat modes

browser.scrapling.security_mode defaults to safe. Safe mode keeps SSRF, TLS, proxy, response-size, timeout, and adaptive-database policy checks; an option the safe backend cannot enforce is refused with an actionable error. Compat is eligible only on certified Linux x86_64/aarch64 builds containing the frozen curl-impersonate and Chromium artifacts. Other targets reject it, and a Tier-1 build missing an artifact reports a capability error instead of silently using the safe transport.

Every id is browser::. browser::screenshot-url screenshots a url, while browser::screenshot is the interactive-session function.

Workflow: inspect before acting

1. Read first; act on refs from the latest read, never from memory of an earlier one. For forms and controls, browser::elements is the cheap read; browser::snapshot shows the whole structure. Refs die on navigation, so a stale ref fails with an error instead of clicking the wrong element.
2. After an action that changes the page, re-read with browser::elements (or browser::snapshot { diff: true }, which returns only added and removed lines). Set a native with act select, not a script.
   Use browser::execute when a step needs waiting or several dependent reads and writes; use browser::act for single trusted input events (in-page script clicks are not trusted events).
   Pure inspection tasks (audits, scraping a logged-in page you must not touch) belong in a read_only: true session.
   When a flow hits a step only a human can do (CAPTCHA, 2FA, payment confirmation), call browser::handoff and wait, rather than trying to automate it. After it returns confirmed, re-read the page and verify the step actually landed — a human clicking Continue is not proof the step succeeded.

   Workflow: drive a goal with browser::run

   A multi-step form or flow is one call instead of an act/read round trip per click:

   1. browser::run { session_id, goal, inputs }: state the end state in goal ("logged in: the dashboard shows"), not the clicks, and give every value to type in inputs (email, password or the field labels work). Values go to the page only; the judge sees the keys. The run waits for the requests each click starts, so the page it returns is the outcome.
   2. done: the judge chose it and a separate "is the goal complete on this page?" check agreed (fields filled but not saved do not pass). Still check page (the final table) against the goal before you report success; the judge's done is not proof (a login can end on "invalid password"). page.busy means it was still loading. needs_text: type the named field with browser::act or rerun with that input. blocked/stalled/max_steps: read steps (each has error when an action was refused) and continue by hand.
   3. judge_unavailable: no judge worker is deployed (or it is failing and paused for 30 s). Drive the same flow with browser::elements + browser::act; page already holds the table.

   Do not use run for destructive actions; they need the two-phase approval below.

   Workflow: destructive UI actions

   For destructive page actions (deleting records, cancelling subscriptions) use two phases, never one script:

   1. Discovery: read candidates and return their exact stable text or ids for the user to approve. Do not act in this call.
   2. Action: operate only on the approved identifiers, read any confirmation dialog text, and abort unless it matches the approved action.

   Keeping context small

   Browser outputs are large and land in the transcript, so a few careless reads fill the context window and force a compaction. Read economically:

   • Prefer browser::snapshot (a compact text outline) over browser::screenshot (a whole image) for reading a page; take a screenshot only when layout or rendering is the actual question.
   • Filter every read instead of dumping: browser::console::read takes pattern/level, browser::network::read takes failed_only, and both page with since_seq so a follow-up read returns only what is new.
   • On a big page, read a subtree: pass a ref to browser::dom::read rather than snapshotting the whole document repeatedly.
   • Reuse one session across steps and browser::sessions::stop it when done; do not re-snapshot after every action, only after the page actually changed.

   Reactive triggers

   Bind a browser::* trigger when another function should react to session activity as it happens instead of polling the read functions. The types: browser::session-started, browser::session-stopped, browser::navigated, browser::console-event (one captured entry per firing; high volume), browser::picked (a human picked an element in the console UI; the payload carries a ref that browser::act accepts directly), and browser::handoff-requested (a session is paused waiting for a human; the console surfaces it beside the live viewport). browser::crawl-item is the one non-session type: one event per crawled page of a browser::crawl, filtered by crawl_id instead of session_id.

   If you just ran browser::navigate yourself, its return value already tells you the outcome; bind triggers when a different worker needs to observe sessions it does not drive.

   How to bind

   1. Register a handler: registerFunction('mywatcher::on-console', handler).
   2. Register the trigger:

   iii.registerTrigger({
     type: 'browser::console-event',
     function_id: 'mywatcher::on-console',
     config: { session_id: 'b1' },
   })

   Every session browser::* binding accepts the optional session_id equality filter; omit it to receive events for all sessions (browser::crawl-item takes crawl_id instead). browser::console-event fires per entry, so filter by session and treat browser::console::read as the durable record. For event payload shapes, call get function info on the trigger type.

   Search the registry

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