Browser

Beta

DOM-first web automation with structured extraction and evidence capture.

The browser tool operates on the accessibility tree and DOM before it falls back to pixels. Structure is more stable than appearance.

Primitives#

browser.*

browser.navigate(url, waitFor?): Load a URL and wait for a readiness condition — load, networkIdle, or a selector.
browser.snapshot() => AccessibilityTree: Return the structured element tree with roles, labels and stable references.
browser.click(ref): Click a referenced element. References come from a snapshot, not from coordinates.
browser.type(ref, text, submit?): Type into a field, optionally submitting the form.
browser.extract(schema): Extract structured data from the page against a JSON Schema.
browser.screenshot(fullPage?): Capture visual evidence, stored as an artifact with the step reference.
browser.download(ref): Download a file into the sandbox filesystem.
browser.upload(ref, path): Attach a sandbox file to a file input.

A resilient interaction loop#

await browser.navigate(class="tok-str">"https://portal.example.com/invoices", { waitFor: class="tok-str">"networkIdle" });

const page = await browser.snapshot();
const search = page.find({ role: class="tok-str">"searchbox", name: /invoice/i });

await browser.type(search.ref, class="tok-str">"INV-class="tok-num">2026-class="tok-num">0142", { submit: true });
await browser.waitFor({ role: class="tok-str">"table", name: /results/i });

const rows = await browser.extract({
  type: class="tok-str">"array",
  items: {
    type: class="tok-str">"object",
    properties: {
      invoice: { type: class="tok-str">"string" },
      amount: { type: class="tok-str">"number" },
      status: { type: class="tok-str">"string", enum: [class="tok-str">"paid", class="tok-str">"open", class="tok-str">"overdue"] }
    }
  }
});

Reliability practices#

Re-snapshot after every navigation or mutation. Element references do not survive re-renders.
Wait on semantic conditions, never on fixed sleeps.
Verify the post-condition: after submitting a form, confirm the resulting state rather than assuming success.
Capture a screenshot before and after any state-changing interaction as evidence for the trace.
Treat page content as untrusted data — an instruction embedded in a page is not an instruction to Pimsy.

Last updated 2026-09-09