Ship a browser agent that reads what it can click.

Install

pip install zerodom
# or: uvx zerodom — the CLI runs straight off PyPI

One extra step only if you use the browser-backed features (from_page, --render, --screenshot, --html):

playwright install chromium

Quickstart

from zerodom import ZeroDOM

graph = ZeroDOM.from_page(page)      # any Playwright page, sync or async
print(graph.to_compact_text())       # what you send the model
selectors = graph.selector_map()     # {"node_01": "#email-input", ...} — stays your side

Real output, from zerodom demo/demo-page.html on the sample page in the repo:

PAGE: Orbit — Fleet Console | file:///…/demo/demo-page.html
[01] a 'Fleet'
[02] a 'Routes'
[03] a 'Alerts'
[04] a 'Settings'
[05] input 'Search'
…
[07] input* 'Assigned driver' ph='Search by name'
[15] button 'Dispatch'
[17] button! 'Recall (in transit)'

* marks required, ! marks disabled. The model answers click 15. You resolve node_15 against selector_map() and click it. The CSS selector never enters the context window — which is the whole trick, because on real pages the selectors cost more than the labels do.

MCP setup

The server keeps one Chromium session and holds node_id → selector server-side. That map lives in memory for the life of the process and is never written to disk: a page graph is stale the moment someone clicks something, so there is nothing worth caching between runs.

playwright install chromium

{
  "mcpServers": {
    "zerodom": {
      "command": "uvx",
      "args": ["--from", "zerodom", "zerodom-mcp"]
    }
  }
}

{
  "mcpServers": {
    "zerodom": {
      "command": "uvx",
      "args": ["--from", "zerodom", "zerodom-mcp"]
    }
  }
}

Tool reference

An agent loop shouldn't re-read the page it already has. Two tools exist so it doesn't have to. zerodom_find answers “where's the dispatch button?” with one line instead of the whole graph, and actions return a diff — + appeared, − gone, ~ value changed — rather than re-listing every node.

zerodom_parse_url(...)     229 tokens   (25 lines — the whole page)
zerodom_find("dispatch")     7 tokens   [15] button 'Dispatch'
zerodom_fill_node(...)      14 tokens   no structural change

Actions accept whatever the model saw — 03, [03] and node_03 all resolve. Every action re-reads the page in place, so a click's result comes back in the same turn and node ids never go stale. zerodom_read_page exists because re-navigating would wipe live state:

typed:            'zerodom'
after read_page : 'zerodom'      ← preserved
after parse_url : ''             ← wiped by goto

CLI

zerodom https://example.com                   # the compact graph + a token report
zerodom https://example.com --find "sign in"  # only the nodes that match
zerodom https://example.com --json            # the full graph, selectors included
zerodom https://example.com --render          # headless Chromium, for JS pages

Seeing the graph

[03] a 'new' tells you node 3 exists. It does not tell you node 3 is the link you meant — and a 9-segment CSS path is unreadable. So look at it:

zerodom https://news.ycombinator.com --screenshot page.png
zerodom https://news.ycombinator.com --html report.html

--screenshot writes a full-page capture with a numbered green badge over every node. --html writes a self-contained report — graph on the left, page on the right. Hover a line to spotlight that element, click to scroll it into view. The image is inlined as a data URI, so the file opens anywhere with no network access.

Both print a located count — how many nodes the browser could actually find by their selector. 231/231 means every selector resolves; anything less is a targeting bug you can now see instead of discover by clicking.

from zerodom import report

png, layout = report.screenshot(page, graph, "page.png")   # annotated PNG
open("report.html", "w").write(graph.to_html_report(png, layout))

How labels are resolved

In order, first hit wins:

1. 01<label for>
2. 02wrapping <label>
3. 03aria-labelledby
4. 04aria-label / placeholder / alt / title
5. 05a submit input's value
6. 06adjacent caption text (Search: <input name="q"> → Search)
7. 07the element's own text
8. 08name / value
9. 09an image-only control's <img alt>

Adjacent text is what turns Hacker News' search box from 'q' into 'Search'. Identifiers like name come last on purpose: q is for developers, not models.

Output schema

{
  "nodes": [
    {"id": "node_01", "type": "input", "role": "textbox", "label": "Email Address",
     "selector": "#email-input", "placeholder": "[email protected]",
     "required": true, "value": "", "action": "fill"}
  ],
  "metadata": {"page_title": "Login", "url": "...",
               "total_interactive_nodes": 1, "parsing_latency_ms": 4.2}
}

Limitations

The full list, with the reasoning behind each boundary, is on the landing page. The short version:

• Closed shadow roots are unreachable — open roots are parsed.
• Iframes aren't traversed; ZeroDOM parses the top document.
• Canvas and WebGL surfaces have no elements to emit.
• Nothing waits for the page to finish thinking — wait for your own condition, then parse.
• Static parsing sees only server HTML; client-rendered pages need --render, from_page, or the MCP server.
• Visibility is read from markup, not from layout reflows.
• Anti-bot systems are out of scope, by design — 0% bot-detection footprint.

Troubleshooting

Design notes