@glittering0717/ai-browser 1.2.1 → 1.3.0

package/README.md

@@ -1,5 +1,9 @@
 <h1 align="center">AI Browser</h1>
 
+<p align="center">
+  <b>中文读者请看这里：<a href="README-CN.md">README-CN.md（3 分钟速读 + 中文安装指引）</a></b>
+</p>
+
 <p align="center">
   <b>A real browser whose only operator is your agent.</b><br>
   It reads pages as a semantic tree instead of screenshots, acts through trusted browser input —
@@ -11,18 +15,24 @@
   <img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue.svg">
   <img alt="Electron" src="https://img.shields.io/badge/built%20with-Electron%2033-9cf">
   <img alt="Platforms" src="https://img.shields.io/badge/platforms-macOS%20%E2%80%A2%20Linux-blueviolet">
-  <img alt="Tests" src="https://img.shields.io/badge/tests-411%20unit%20%2B%20409%20e2e-2ea043">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-658%20unit%20%2B%20447%20e2e-2ea043">
   <img alt="MCP" src="https://img.shields.io/badge/spec-MCP%20(stdio)-f5b23b">
 </p>
 
 <p align="center">
-  <em>One agent, no coordinates: open Bing → type through trusted key events (live suggestions) → scroll the results → open page 2 → back to page 1 → open the project site in a new tab → keep scrolling there. Every target was found in the semantic tree by role/label.</em><br>
-  <a href="docs/marketing/demo.gif"><img src="docs/marketing/demo.gif" alt="AI Browser demo: search, paginate, and open a website — all driven by the semantic tree" width="860"></a><br>
-  Reproduce: <code>npm start</code> then <code>node examples/demo.mjs</code>
+  <em>A noisy real-world feed (300+ accessibility nodes) becomes a typed structure — then one <code>ui.act</code> switches the feed and the tree changes with it. Every call is a raw JSON-RPC message over one WebSocket: no SDK, no coordinates.</em><br>
+  <a href="docs/marketing/demo.gif"><img src="docs/marketing/demo.gif" alt="AI Browser demo: navigate a crowded feed page, get the whole page as one semantic tree, extract typed items, and act on an element id — all over raw WebSocket JSON-RPC" width="860"></a><br>
+  Reproduce: <code>npm start</code> then <code>node examples/feed-tree.mjs</code>
+</p>
+
+<p align="center">
+  <em>Human + agent, same browser, same socket. The agent drives, then simply stops and watches; a person clicks an article in the real window, the agent notices the new tab on its next read, and continues on the page the human chose. No lock, no hand-off API.</em><br>
+  <a href="docs/marketing/demo2.gif"><img src="docs/marketing/demo2.gif" alt="Human takeover demo: the agent lists a feed and pauses; a human clicks an article in the real browser window; the agent detects the new tab and resumes scrolling on the chosen page" width="860"></a><br>
+  Try it yourself: <code>npm start</code> then <code>node examples/human-takeover.mjs</code> — click anything when it says <em>YOUR TURN</em>.
 </p>
 
 **What it is.** An Electron app that exposes its tabs over two equivalent interfaces — an MCP server
-(17 `browse_*` tools) and a raw WebSocket JSON-RPC API (`ws://localhost:9223`, methods `ui.*`). Your
+(20 `browse_*` tools) and a raw WebSocket JSON-RPC API (`ws://localhost:9223`, methods `ui.*`). Your
 agent navigates, reads a structured semantic tree (`role` / `label` / `value` / `states` / `actions`),
 and clicks or types by `data-ai-id`. There is no screenshot step and no OCR: `src/` contains no
 capture call at all.
@@ -38,11 +48,36 @@ is a conversation between the agent and the user, not a browser API.
 
 ## Install
 
-Requires **Node ≥ 18** and a desktop session (this is a GUI app).
+**Install the prebuilt package unless you have a reason not to.** Option A is one file you
+double-click: no Node.js, no dependency tree, no build step. Source install (Option C) pulls a
+~276 MB `node_modules` plus a ~100 MB Electron engine download on top — only use it when no
+package fits your platform, the package misbehaves, or you specifically need to run from source.
+
+### Option A — macOS install package (recommended)
 
-### Option A — npx (recommended for MCP users)
+Grab `AI-Browser-<version>-arm64.dmg` from
+[GitHub Releases](https://github.com/Glittering/ai-browser/releases) (~110 MB to download,
+~245 MB on disk — most of it is the bundled Chromium engine, which *is* the product). Open the
+dmg, drag **AI Browser** to `/Applications`, launch it. Done.
 
-The package is published as [`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser); no clone needed:
+Two things to know before you download it:
+
+- **It is not notarized.** macOS Gatekeeper will refuse to open it on the first try. Right-click
+  the app → **Open**, confirm once, and it runs normally afterwards. (A paid Apple Developer
+  account is what removes this step; until then, this is the honest cost.)
+- **Only macOS `arm64` is built.** Windows and Linux have no package yet, because neither has
+  been verified on this project — see [Compatibility](#compatibility).
+
+Agents still connect through the MCP server (Option B below), and the two channels cooperate:
+when the packaged app is already running, the MCP server finds it on port 9223 and **reuses it
+instead of spawning a second copy of Electron** — one browser, one login session, whichever way
+you start it. So "package for the engine + `npx` for the MCP bridge" is the normal agent setup
+too.
+
+### Option B — npx (the agent channel)
+
+The package is published as [`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser);
+no clone needed:
 
 ```bash
 npx -y @glittering0717/ai-browser --help
@@ -54,16 +89,21 @@ To open the visible browser window directly:
 npx -y @glittering0717/ai-browser start
 ```
 
-The first launch prepares the Electron engine (~100 MB, downloaded once). npm ≥ 11 blocks
-dependency install scripts by default — the launcher detects that and runs Electron's own
-downloader itself, so nothing extra is needed. If the download from GitHub releases is slow or
-blocked (common on mainland-China networks), point it at a mirror:
+Requires **Node ≥ 18** and a desktop session (this is a GUI app). If a launch needs its own
+engine, the first run prepares it (~100 MB, downloaded once). npm ≥ 11 blocks dependency install
+scripts by default — the launcher detects that and runs Electron's own downloader itself, so
+nothing extra is needed. If the download from GitHub releases is slow or blocked (common on
+mainland-China networks), point it at a mirror:
 
 ```bash
 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npx -y @glittering0717/ai-browser start
 ```
 
-### Option B — from source
+### Option C — from source (fallback)
+
+Use this when there is no package for your platform, the package gives you trouble, or you need
+to modify the code. It is the heaviest of the three: `npm install` pulls the full dependency
+tree (~276 MB), then the Electron engine (~100 MB) on top.
 
 ```bash
 git clone https://github.com/Glittering/ai-browser.git
@@ -83,8 +123,8 @@ Or make it sticky by creating a `.npmrc` in the project root:
 electron_mirror=https://npmmirror.com/mirrors/electron/
 ```
 
-Confirm the binary actually landed before blaming anything else — a missing binary still leaves you
-with an "install that succeeded":
+Confirm the binary actually landed before blaming anything else — a missing binary still leaves
+you with an "install that succeeded":
 
 ```bash
 ls node_modules/electron/dist
@@ -99,6 +139,19 @@ npm start
 A 1280×800 window opens and the terminal prints `AI Browser WS server listening on ws://localhost:9223`.
 (The first tab opens on the default start page; ignore it and navigate away.)
 
+To build the package yourself:
+
+```bash
+npm install
+node scripts/build_dmg.cjs              # current arch
+node scripts/build_dmg.cjs --arch arm64 # or x64
+```
+
+Output lands in `dist/`. The script uses `@electron/packager` plus macOS's built-in `hdiutil`
+(no external binary downloads); the reasoning — including why `electron-builder` refuses to build
+this project — is documented in
+[`docs/DEPENDENCY_AND_DISTRIBUTION_AUDIT.md`](docs/DEPENDENCY_AND_DISTRIBUTION_AUDIT.md).
+
 ---
 
 ## Connect your agent
@@ -123,8 +176,9 @@ can instead point `command: "node"` at `/absolute/path/to/ai-browser/src/main/mc
 **You do not need to start the browser yourself.** On the first `browse_*` call the MCP server probes
 port 9223; if nothing is listening it spawns Electron detached and waits up to 30 seconds for the
 WebSocket server (the very first call may additionally spend time preparing the engine). If you would
-rather keep one long-lived window shared by every client, run `npx -y @glittering0717/ai-browser start`
-(or `npm start` from source) in a terminal — a second launch just focuses the existing window.
+rather keep one long-lived window shared by every client, launch the **AI Browser** app you installed
+in Option A (or run `npx -y @glittering0717/ai-browser start`, or `npm start` from source) — a second
+launch just focuses the existing window.
 
 `examples/AGENT_INSTRUCTIONS.md` has a copy-paste prompt you can drop into a `CLAUDE.md`, Cursor Rule,
 or any system prompt; it teaches the tool loop, the token-saving params, and when to ask a human.
@@ -357,7 +411,7 @@ MCP is a thin stdio adapter. Anything MCP can do is reachable directly over JSON
 | `ui.subscribe` / `ui.unsubscribe` | Event subscription; `params.events`, `"*"` for all | — (WS only — see below) |
 | `ui.downloads` | This tab's downloads with on-disk paths (`state`, `received_bytes`, `dir`) | `browse_downloads` |
 | `ui.get_focused` | The focused element subtree | — |
-| `ui.peek` | Hover a folded/hover-only affordance and return the diff, without committing | — |
+| `ui.peek` | Hover a folded/hover-only affordance and return what appeared/disappeared (`revealed` / `hidden`), without committing. Ids are real `data-ai-id`s you can hand straight to `ui.act`; `revertMs: 0` keeps the mouse there so you can click what it found | — |
 | `ui.network_body` | Response body by URL substring (`url_pattern`) | — (superseded by `browse_network`) |
 | `ui.quit` | Graceful shutdown | `browse_quit` |
 
@@ -439,7 +493,9 @@ perturbs the thing it is measuring.
 **Writing.** Actions are **trusted browser input**, not synthesized JS. The main process drives the
 page over the Chrome DevTools Protocol — `Input.dispatchMouseEvent` for clicks, and per-character
 `Input.dispatchKeyEvent` (`rawKeyDown → char → keyUp`) for typing — then validates that the click
-actually landed via `elementFromPoint`. Because the events arrive as real keyboard and mouse input,
+actually landed via `elementFromPoint` (piercing shadow roots: the plain call returns the *host* for
+anything inside a web component, which silently downgraded every such click to a synthetic one).
+Because the events arrive as real keyboard and mouse input,
 Draft.js, ProseMirror, CKEditor, Quill, and plain `<textarea>` all work through the same path without
 per-framework branches.
 
@@ -462,7 +518,9 @@ Runnable scripts live in [`examples/`](examples/) and connect straight to `ws://
 | [`AGENT_INSTRUCTIONS.md`](examples/AGENT_INSTRUCTIONS.md) | Copy-paste instructions for your agent, incl. the human hand-off protocol. |
 | [`raw-ws.mjs`](examples/raw-ws.mjs) | Smallest possible raw WebSocket client. |
 | [`read-page.mjs`](examples/read-page.mjs) | Load one page, print its interactive elements. |
+| [`feed-tree.mjs`](examples/feed-tree.mjs) | Crowded feed → typed structure → act, all over raw JSON-RPC (top demo). |
 | [`with-human.mjs`](examples/with-human.mjs) | Full flow for when a human has to step in. |
+| [`human-takeover.mjs`](examples/human-takeover.mjs) | Agent pauses, you click, agent resumes on your page (second demo). |
 
 ```bash
 node examples/read-page.mjs
@@ -551,6 +609,65 @@ not "logged in" in another:
 AI_BROWSER_USER_DATA=~/.ai-browser-work npm start
 ```
 
+**A red bar appeared at the bottom of the window.** That is a main-process exception — a bug in
+AI Browser itself, not in the page you were driving. It is deliberately *not* a modal dialog: a
+native `dialog.showMessageBox` is an `NSAlert` modal loop on macOS and blocks the whole main process
+(measured: WebSocket calls got 4ms with no dialog vs **8 seconds of no response** with one), which
+turned a self-healing JS exception into "every RPC timed out". The bar shows the message and the log
+path, the process keeps running, and you can dismiss it with `×`.
+
+Every exception is appended synchronously to `~/.ai-browser/logs/error.jsonl` (2MB × 4 rolling), with
+the last 20 WebSocket calls attached so you can see *what was being done* when it broke. Read it over
+the API with `ui.errors` / `browse_errors`, or just `tail` the file. A record of `boot` without a
+matching `shutdown` means the process died hard last time.
+
+If the exception happened before any window existed, the bar has nowhere to go, so it falls back to a
+native box once (logged as `error_dialog_fallback`) rather than leaving you with a silently dead app.
+Both paths are switchable: `AI_BROWSER_ERROR_BANNER=0` disables the bar, `AI_BROWSER_ERROR_DIALOG=1`
+forces the modal box — the latter blocks the main process, so it is only for staring at a startup
+crash on purpose.
+
+### The element is clearly on the page but not in the tree
+
+Before you write a site-specific script, work down this list. The reflex — "pin it with a
+`querySelector` chain" — is what produced 142 site-specific scripts and 731 hardcoded selectors in
+this project's own history, and almost none of them turned out to be necessary.
+
+| # | Check | How | If it is the cause |
+|---|---|---|---|
+| 1 | Is it a **read-layer** gap? | `node tools/coverage_probe.cjs https://the.site/` | the tree is missing clickable elements → report it; the fix belongs in `src/preload/extractor.cjs`, not in your script |
+| 2 | Is it an **action-layer** gap? | the node is in the tree, `ui.act` fails or does nothing | the element is readable but not reachable (iframe/OOPIF, canvas, trusted input, un-mounted input) → that is a browser-side fix too |
+| 3 | Is it **timing**? | re-read the tree 2–3s later, or `wait_until` | the SPA simply had not rendered when you read it |
+| 4 | Does it only exist **while hovered**? | `ui.peek { target, revertMs: 0 }` | the affordance is hover-rendered. `peek` hovers it and returns what appeared — pass `revertMs: 0` to keep it open, then `ui.act click` the id you got back |
+| 5 | Is it **unnamed**? | `ui.peek`, or click it and read what shows up | an icon-only button the site gave no `aria-label`/`title`/`alt` cannot be named from nothing. But the panel it opens usually is named — so open it and read that instead of guessing which icon is which |
+| 6 | Only now: **pin it yourself** | a selector in *your* script | keep it in your script. Do not encode it as "how this site works" — the next site will not match |
+
+`coverage_probe` counts what a human would call click targets — elements the browser itself renders
+with a hand cursor (`cursor:pointer`), where the pointer starts (not every descendant that inherits
+it), and reports how many of them carry a `data-ai-id`:
+
+```
+$ node tools/coverage_probe.cjs https://www.csdn.net/
+可点目标（手型边界）: 257
+  ├ 自己带 data-ai-id（直接可操作）: 257 → 100%
+  ├ 被单个交互后代盖满且它在树里（壳子，点内层等价）: 0
+  ├ 祖先歧义（同一祖先下多个手型后代，点祖先指不准）: 0
+  └ 整条祖先链无 id（真看不见）: 0
+可用率（in_tree + by_desc + anc_only）: 100 % | 真缺口: 0
+```
+
+It exits non-zero below 80% so you can drop it into CI. Measured on 2026-10-17 (Baidu / Bilibili /
+CSDN): **82% / 97% / 88%** before the click-boundary fix, **100% / 100% / 100%** after, at ~40ms
+per `ui.get_tree`.
+
+Two things the numbers do **not** cover, so you do not chase them: an element the page gives no
+readable name (image-only links with no `alt` — 53% of Bilibili's clickable nodes) can never get a
+label without inventing one, and a canvas has no DOM to read at all. Those are genuine boundaries,
+not bugs. The full write-up, including why the first measurement of this was wrong by 3× (inherited
+`cursor` inflates the denominator), is in
+[`docs/AGENT_OPERABILITY_FEEDBACK.md`](docs/AGENT_OPERABILITY_FEEDBACK.md) §6.
+
+
 ---
 
 ## Test & dev
@@ -565,9 +682,11 @@ npm run value        # value truncation contract + read-only get_value — 15 ch
 npm run canvas       # canvas draw-call capture — 13 checks
 npm run modeldiff    # canvas app data-model diff (the "unchanged" false green) — 12 checks
 npm run audit        # every advertised action must exist; wait/downloads/permissions/quit — 35 checks
+npm run nav          # address bar + load-failure error page (the "white screen" report) — 19 checks
 npm run focus        # no focus stealing + full capability while backgrounded — 32 checks
 npm run interact     # trusted drag / key press / wheel (pointer gestures) — 31 checks
 npm run view         # viewport repaint + snapshot/diff verification — 28 checks
+npm run e2e:all      # 一次跑完上面全部套件（每个独立端口）+ 可信汇总 — 428 checks
 npm run realsites    # navigate/read/act against a matrix of real sites
 ```
 
@@ -575,6 +694,16 @@ All e2e suites boot a genuine Electron against offline fixtures and exit non-zer
 Together they cover what jsdom structurally cannot: preload integrity, `ui.evaluate` under a strict
 CSP, CDP click hit-testing, multi-tab lifecycle, event fan-out, and the `evaluate` guard rails.
 
+**Each suite proves it is talking to the browser it just started.** Before any assertion runs it
+calls `ui.server_info` and compares the returned `pid` against the child process it spawned; a
+mismatch aborts with exit 4 instead of quietly producing results about somebody else's instance.
+That gap was measured, not assumed: with an impostor WebSocket server holding the port, a suite
+happily sent `ui.new_tab` / `ui.evaluate` / `ui.get_tree` to it and never noticed. Repro:
+`REPRO_PORT=9799 node e2e/_repro_identity.cjs`.
+
+`npm run e2e:all` also gives every suite its own port, because they share `/tmp/ai-browser-e2e-<port>`
+as the profile and therefore Electron's single-instance lock too.
+
 They all need the WS port free — stop a running `npm start` first, or point them elsewhere:
 
 ```bash
@@ -635,7 +764,13 @@ Two things it changed in the product:
 the page through `ui.evaluate`.
 
 **`npm run network`** — that a POST can be captured with its full request body, that headers are
-redacted by default, and that bodies paginate instead of being silently truncated.
+redacted by default, and that bodies paginate instead of being silently truncated. It also pins the
+eviction rule: the retained byte budget is **global across tabs**, so a background tab quietly
+filling it used to evict the body the agent was about to read on the *active* tab — the request
+really happened and the body really was captured, it just got pushed out by someone else's noise.
+Eviction now sacrifices non-active tabs first (including the background body being stored), and
+`ui.network_configure` reports `active_tab` / `body_bytes` so a future `evicted` can be attributed
+instead of guessed at.
 
 **`npm run modeldiff`** — the suite for the one place `ui.diff` used to lie. A canvas-rendered app's
 DOM is a still photograph: dragging a node or editing a widget repaints `<canvas>` and moves

package/bin/ai-browser.cjs

@@ -19,7 +19,7 @@ const HELP = `ai-browser ${pkg.version}
 
 Usage:
   ai-browser [start]          Launch the visible AI Browser window
-  ai-browser mcp              Run the MCP stdio server (17 browse_* tools)
+  ai-browser mcp              Run the MCP stdio server (20 browse_* tools)
   ai-browser --version        Print version
   ai-browser --help           Show this help
 

package/examples/AGENT_INSTRUCTIONS.md

@@ -15,7 +15,7 @@
 ## 中文版（copy-paste）
 
 ```text
-我可以用 AI Browser 浏览网页。它提供 MCP 服务（17 个 browse_* 工具），第一次调用时会自动
+我可以用 AI Browser 浏览网页。它提供 MCP 服务（20 个 browse_* 工具），第一次调用时会自动
 拉起一个真实可见的浏览器窗口，用完调用 browse_quit 释放。页面以结构化语义树返回，不是截图。
 
 标准循环：
@@ -30,6 +30,8 @@
                                            text_contains / url_contains
 5. browse_evaluate { js }                  在页面上下文跑 JS 表达式（上限 5000 字符，
                                            禁用 process. / require / child_process）
+6. browse_errors                           出事了先看这里：主进程异常 / 崩溃 / 导航失败 /
+                                           RPC 报错的最近记录（含调用上下文与日志路径）
 
 省 token（browse_get_tree 参数）：
 - { "subset": "interactive" }  只保留可交互节点，砍掉纯布局分支 —— 默认就该带上
@@ -39,6 +41,14 @@
 验证写操作（success 不等于做成了）：browse_diff 先 snapshot 基线，写操作之后再 diff，
 verdict 显式给出 changed / unchanged。
 
+找不到元素 / 点了没反应时的排查顺序（**别一上来就写站点专用选择器**）：
+1. 重读 browse_get_tree，或先 browse_wait —— SPA 常常只是还没渲染完
+2. 节点在树里但操作失败 → 是**动作层**问题（跨进程 iframe、canvas、需要受信输入、
+   上传控件未挂载），写选择器解决不了
+3. 树里没有、页面上明明有 → 是**读层**缺口，属于浏览器该修的东西；先跑
+   tools/coverage_probe.cjs <url> 量化，再考虑绕过
+4. 以上都不成立，才在自己脚本里用选择器兜底；别把"某个站点的选择器"记成通用知识
+
 其他：browse_scroll 滚动文档（画布类页面用 browse_act 的 wheel）；browse_list_tabs /
 browse_new_tab / browse_close_tab / browse_set_active_tab 管标签页；browse_network 拉取网络
 请求（含 POST body，免订阅）；browse_capabilities 一次探明页面该走哪条路（结构化数据 /
@@ -57,7 +67,7 @@ browse_downloads 查下载文件落盘路径；browse_repaint 在窗口画面陈
 ## English (copy-paste)
 
 ```text
-I can browse the web with AI Browser. It exposes an MCP server (17 browse_* tools), auto-starts a
+I can browse the web with AI Browser. It exposes an MCP server (20 browse_* tools), auto-starts a
 real, visible browser window on my first call, and I release it with browse_quit when done. Pages come
 back as a structured semantic tree — no screenshots, no OCR.
 
@@ -82,6 +92,16 @@ Saving tokens (browse_get_tree params):
 Verifying writes (success is not evidence): browse_diff snapshots a baseline, then diffs after the
 write and returns an explicit verdict of changed / unchanged.
 
+When an element cannot be found, or a click does nothing — work down this list, do **not** reach for a
+site-specific selector first:
+1. re-read with browse_get_tree, or browse_wait — an SPA usually just has not rendered yet
+2. the node is in the tree but the action fails → an **action-layer** gap (cross-process iframe,
+   canvas, trusted input, unmounted upload input); a selector will not fix it
+3. the node is missing though the page clearly renders it → a **read-layer** gap, i.e. something the
+   browser should fix; quantify it with `tools/coverage_probe.cjs <url>` before working around it
+4. only then pin it with a selector inside your own script — and never record "the selector for site X"
+   as general knowledge
+
 Also: browse_scroll (document scrolling; use the wheel action on canvas apps); browse_list_tabs /
 browse_new_tab / browse_close_tab / browse_set_active_tab for tabs; browse_network for captured
 requests including POST bodies (no subscription); browse_capabilities to pick a route on an

package/llms-install.md

@@ -11,18 +11,28 @@ semantic tree (roles / labels / values / actions, stable `data-ai-id` per elemen
 not screenshots. Input is trusted CDP keyboard/mouse events. A human can use the
 window's mouse and keyboard at any time (login, QR scan, CAPTCHA, payment).
 
-Two equivalent interfaces: **MCP stdio** (17 `browse_*` tools) and a raw WebSocket
+Two equivalent interfaces: **MCP stdio** (20 `browse_*` tools) and a raw WebSocket
 JSON-RPC API at `ws://localhost:9223` (`ui.*` methods).
 
 ## Requirements
 
 - Node.js **≥ 18**
 - A desktop session (GUI app): macOS or Linux. Windows is experimental/untested.
-- ~100 MB for the Electron binary (prepared on first launch / `npm install`, from GitHub releases).
+- ~110 MB download for the Electron engine (prepared on first launch / `npm install`, from GitHub
+  releases); it expands to ~245 MB on disk. Do not judge the install by the download size alone.
+
+> **Installation priority.** The prebuilt macOS `.dmg` (README "Option A") is the recommended
+> install for humans: one file, no Node.js, no dependency tree. The npx path below is for agents
+> and for machines that already have Node — it is also how the MCP server gets registered, so it
+> stays necessary even when the packaged app is installed. The two cooperate: if the packaged app
+> is already running, the MCP server reuses it on port 9223 instead of downloading a second
+> Electron. Source install is the fallback — only when no package fits, the package misbehaves,
+> or the code itself needs changes; it pulls ~276 MB of dependencies plus the engine.
 
 ## Install
 
-Preferred — npm package [`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser),
+For agents (this is also the MCP bridge) — npm package
+[`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser),
 no clone needed:
 
 ```bash
@@ -80,7 +90,7 @@ call can take longer if the engine download hasn't happened yet — the progress
 A long-lived shared window is also fine — run the `start` command manually; a second launch only
 focuses the existing window (single instance lock).
 
-## The 17 tools
+## The 20 tools
 
 - `browse_navigate` — load a URL in the active or given tab.
 - `browse_get_tree` — semantic tree + context (modals, toasts, required-field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "AI-native browser — renders pixels for humans, structured semantic-tree API for agents. No screenshots, no OCR, no coordinate guessing.",
   "main": "src/main/index.js",
   "bin": {
@@ -10,6 +10,7 @@
     "bin",
     "scripts",
     "src",
+    "tools/coverage_probe.cjs",
     "examples/AGENT_INSTRUCTIONS.md",
     "examples/mcp-config.json",
     "llms-install.md",
@@ -60,22 +61,25 @@
     "canvas": "node e2e/canvas_ws.cjs",
     "focus": "node e2e/focus_ws.cjs",
     "interact": "node e2e/interact_ws.cjs",
+    "upload": "node e2e/upload_ws.cjs",
     "view": "node e2e/view_ws.cjs",
     "realsites": "node e2e/e2e_realsites.cjs",
     "realsites:meta": "vitest run tests/test_realsites_sites.js",
     "mcp": "node src/main/mcp_server.js",
     "modeldiff": "node e2e/modeldiff_ws.cjs",
-    "audit": "node e2e/audit_ws.cjs"
+    "nav": "node e2e/nav_ws.cjs",
+    "audit": "node e2e/audit_ws.cjs",
+    "e2e:all": "node e2e/run_all.cjs",
+    "coverage": "node tools/coverage_probe.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "electron": "^33.4.11",
-    "jsdom": "^29.1.1",
     "ws": "^8.0.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.45.0",
-    "playwright": "^1.45.0",
+    "@electron/packager": "^20.3.0",
+    "jsdom": "^29.1.1",
     "vitest": "^2.0.0"
   }
 }