zerodom 0.0.1__tar.gz

zerodom-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+dist/
+*.egg-info/
+
+# session transcripts and scratch captures — local only
+*-this-session-is-being-continued-from-a-previous-c.txt
+assets/screenshot.png
+# regenerable: `zerodom inspect --render --screenshot ... --html ... demo/demo-page.html`
+demo/report.html
+demo/annotated.png

zerodom-0.0.1/LICENSE

@@ -0,0 +1,95 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Syed Husnain Khalid
+
+Licensed Work:        ZeroDOM
+                      The Licensed Work is (c) 2026 Syed Husnain Khalid
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided you do not offer the Licensed Work to third
+                      parties as a hosted, managed, or embedded service where
+                      the primary value of that service is the functionality
+                      of the Licensed Work.
+
+Change Date:          2030-08-09
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor at contact@vexralabs.com.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

zerodom-0.0.1/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: zerodom
+Version: 0.0.1
+Summary: DOM-to-Interaction-Graph middleware for AI web agents
+Project-URL: Homepage, https://github.com/DevHusnainAi/zerodom
+Project-URL: Repository, https://github.com/DevHusnainAi/zerodom
+Project-URL: Issues, https://github.com/DevHusnainAi/zerodom/issues
+Author-email: Syed Husnain Khalid <contact@vexralabs.com>
+License-Expression: BUSL-1.1
+License-File: LICENSE
+Keywords: agent,browser-automation,dom,llm,mcp,playwright,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.10
+Requires-Dist: lxml
+Requires-Dist: mcp[cli]
+Requires-Dist: playwright
+Requires-Dist: tiktoken
+Description-Content-Type: text/markdown
+
+# ZeroDOM
+
+### Your agent doesn't need the DOM. It needs to know what it can click.
+
+ZeroDOM turns a bloated HTML page into a token-optimized **interaction graph** —
+the buttons, inputs and links an agent can actually act on, and nothing else.
+
+An agent driving a browser gets one of two action spaces today, and both are bad.
+**Pixels** are slow, expensive, and produce coordinates that go stale the moment
+the page scrolls. **The accessibility tree** is cheaper but enormous, and it has
+no stable handles: 102 of Hacker News' 220 actionable nodes share a
+`(role, name)` pair with another node, so there is no way to say *which* story to
+upvote.
+
+ZeroDOM is a third option — a flat list of what the page can do, where every
+entry has a stable id, and the addressing information that makes it clickable
+never enters the context window. About **10 tokens per action, on every page
+tested**.
+
+- **No LLM in the loop.** lxml in, graph out, 10–30ms, identical output every run.
+- **Selectors never enter the context window.** The model sees `[03]`; the CSS
+  path stays in `selector_map()` on your side.
+- **Nothing leaves your machine.** No telemetry, no API keys, no storage — the
+  only network traffic is the page you pointed it at.
+- **The selectors actually resolve.** Verified in a real browser: 231/231 on
+  Hacker News, where rows carry no `id` or `class` and numeric ids need escaping.
+
+## Install
+
+```bash
+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`):
+
+```bash
+playwright install chromium
+```
+
+## Quickstart
+
+```python
+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:
+
+```text
+PAGE: Orbit — Fleet Console | file:///…/demo/demo-page.html
+[01] a 'Fleet'
+[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.
+
+## Cost per action
+
+The fair comparison isn't raw HTML — nobody sends a model raw HTML. It's
+Playwright's `page.aria_snapshot(mode="ai")`, which is what Playwright MCP puts
+in a model's context.
+
+| page | ZeroDOM | ARIA |
+|---|---:|---:|
+| airbnb.com | **9.9** | 23.3 |
+| github.com/…/issues | **12.1** | 70.2 |
+| en.wikipedia.org article | **11.6** | 41.0 |
+| news.ycombinator.com | **10.2** | 47.0 |
+| developer.mozilla.org | **9.9** | 46.8 |
+
+*tokens per actionable node — measured 2026-08-03*
+
+**~10 tokens per action, flat across every page**, against 23–70 and wildly
+variable. Mean 71.0% fewer tokens than the snapshot a model actually gets, and
+93.1% against raw HTML.
+
+## MCP server
+
+```json
+{
+  "mcpServers": {
+    "zerodom": {
+      "command": "uvx",
+      "args": ["--from", "zerodom", "zerodom-mcp"]
+    }
+  }
+}
+```
+
+Goes in `claude_desktop_config.json` for Claude Desktop, or `.cursor/mcp.json`
+for Cursor.
+
+| tool | what it does |
+|---|---|
+| `zerodom_parse_url(url, verbose=False)` | navigate, return the compact graph |
+| `zerodom_read_page(verbose=False)` | re-read the live DOM **without navigating** |
+| `zerodom_find(query)` | return only the nodes matching a phrase |
+| `zerodom_click_node(node_id)` | click, then return **what changed** |
+| `zerodom_fill_node(node_id, text)` | type, then return what changed |
+
+An agent loop shouldn't re-read the page it already has. `zerodom_find` answers
+"where's the dispatch button?" in one line, and actions return a diff — `+`
+appeared, `-` gone, `~` value changed — instead of re-listing every node.
+
+## CLI
+
+```bash
+zerodom https://news.ycombinator.com          # compact graph + token savings
+zerodom https://example.com --find checkout   # only the nodes that match
+zerodom https://example.com --render          # headless Chromium, for JS-heavy pages
+zerodom https://example.com --json            # full JSON graph, selectors included
+zerodom https://example.com --html out.html   # graph beside an annotated screenshot
+```
+
+## Limitations
+
+- **Closed shadow roots** are unreachable — no browser API exposes them. Open
+  roots work.
+- **Cross-origin and same-origin iframes** are not traversed yet; only the top
+  frame is parsed.
+- **Canvas-rendered UIs** have no DOM to read. Use a vision model there.
+- **Labels come from the page**, so a hostile page can write anything into one.
+  Treat graph text as untrusted input — see SECURITY.md.
+- ZeroDOM operates on a `Page` you already control. It does not bypass bot
+  detection and makes no attempt to.
+
+## Links
+
+- **Source, full README and benchmarks:**
+  https://github.com/DevHusnainAi/zerodom
+- **Issues:** https://github.com/DevHusnainAi/zerodom/issues
+- **License:** Business Source License 1.1 — free to use, including in
+  production; you may not offer ZeroDOM itself as a hosted service. Converts to
+  Apache 2.0 on 2030-08-09.
+