pi-chrome 0.14.2 → 0.14.4

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable user-facing changes to `pi-chrome`.
+
+## 0.14.4
+
+- Sync `manifest.json` version to match `package.json` (0.14.3 shipped with stale manifest, would trigger spurious `/chrome doctor` drift warnings). No code or behavior changes.
+
+## 0.14.3
+
+- Documentation & discoverability overhaul.
+- New README: hero, alternatives comparison table, 20-tool reference grouped by job, killer recipes, architecture diagram, honest-results explainer, benchmark suite plug.
+- `docs/COMPARISON.md` — deep comparison vs Playwright / Puppeteer / Stagehand / browser-use / Selenium.
+- `docs/EXAMPLES.md` — ready-to-paste agent prompts (PR triage, Linear standup, bug repro, network forensics, multi-tab admin cross-check, etc.).
+- `docs/FAQ.md` — covers Brave/Arc, incognito, detection, banner, multi-session, CSP, file uploads, common envelope causes.
+- `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `LICENSE` added.
+- `package.json`: `homepage`, `repository`, `bugs`, expanded keywords for npm search.
+- No code changes to the tools or extension.
+
+## 0.14.2
+
+- Recover from foreign-extension input overlays so input tools don't get hijacked by other Chrome extensions.
+
+## 0.14.1
+
+- Harder `attachDebugger` retry path so trusted clicks survive transient Chrome debugger contention.
+- New `trusted.debug` diagnostic surface.
+
+## 0.14.0
+
+- Bare `/chrome` opens a `SettingsList` dialog. `space` cycles values, `enter` saves.
+
+## 0.13.0
+
+- Flattened `/chrome` tree. Cycle-on-pick for `clicks` / `quiet`. Status header at the top of the picker.
+
+## 0.12.1
+
+- Fixed anti-automation regressions across 7 benchmark challenges (`07/13/21/27/28`).
+
+## 0.12.0
+
+- Unified all slash commands under `/chrome` (`/chrome doctor`, `/chrome onboard`, `/chrome clicks`, `/chrome quiet`).
+
+## 0.11.x
+
+- Plain-English audit pass across `/chrome doctor`, `/chrome onboard`, `/chrome quiet`, README.
+- `chrome_tap` (real CDP touch events).
+- Smoother `trustedScroll`; CDP debugger auto-recovers from detach.
+- Smart-auto trusted mode default. Extension renamed to **Pi Chrome Connector**.
+- Per-event scroll delta cap so IntersectionObserver thresholds land naturally.
+
+## 0.10.x
+
+- Trusted-input mode via `chrome.debugger` (CDP) — opt-in, indistinguishable-from-human clicks/keys.
+- `chrome_key` modifiers (Cmd+V, Ctrl+Shift+Tab, etc.) for trusted chords.
+- Interactive `/chrome-trusted` picker (later folded into `/chrome`).
+
+## 0.9.x
+
+- Humanized synthetic input (pointer paths, key cadence variance).
+- Anti-automation benchmark test suite landed in `test-suite/`.
+
+## 0.8.0
+
+- `chrome_evaluate` no longer returns `null` for valid expressions — dedicated MAIN-world `evaluateInTab` pipeline with statement-mode fallback and tagged envelope for `undefined`/errors/symbols/bigints.
+- Truthful action result envelopes: `isTrusted`, `defaultPrevented`, `elementVisible`, `occludedBy`, `valueMatches`, `pageMutated`.
+- Extended `/chrome doctor`: bridge mode/URL, extension version drift, MAIN-world helper injection, `navigator.webdriver` fingerprint, CDP availability probe.
+- Removed misleading `returnByValue` param. Implemented `chrome_screenshot.fullPage` via tile stitching.
+- Autoplay-gate heuristic for `chrome_click`.
+
+## 0.7.0
+
+- Initial public `pi-chrome` release. Companion Chrome extension + local bridge + first tool set.

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to pi-chrome
+
+Thanks for considering a contribution. pi-chrome aims to be the **de-facto browser-control toolkit for Pi agents** — that means a few non-negotiables.
+
+## Non-negotiables
+
+1. **No re-login.** Every change must keep working against the user's already-signed-in Chrome profile. Anything that requires a fresh profile or extra auth steps is out of scope.
+2. **Honest result envelopes.** Every action tool returns `pageMutated`, `defaultPrevented`, `elementVisible`, `occludedBy` (when relevant), `valueMatches` (for input). Agents need to know **why** something didn't take effect.
+3. **Quiet by default, trusted by opt-in.** Synthetic DOM events first. CDP/`chrome.debugger` only when explicitly requested (`trusted: true`) or when the smart-auto heuristic detects an obvious user-activation gate.
+4. **Benchmarks gate features.** Add a page in `test-suite/` that fails before your change and passes after. We accept PRs faster when there's a green/red verdict to point at.
+
+## Local dev
+
+```bash
+# Link from a checkout
+pi install ./pi-chrome
+
+# Run the benchmark dashboard
+cd test-suite
+python3 -m http.server 8765
+# open http://127.0.0.1:8765/ in the Chrome window pi-chrome controls
+```
+
+## Adding a new tool
+
+1. Register in `extensions/chrome-profile-bridge/index.ts` (the `register*Tool` calls near line 840+).
+2. Implement the handler in `extensions/chrome-profile-bridge/browser-extension/service_worker.js`.
+3. Return a `pageMutated` + relevant fields.
+4. Add a benchmark page under `test-suite/challenges/` and a manifest entry.
+5. Update `README.md` "What an agent gets" table.
+6. Add a `CHANGELOG.md` entry.
+
+## Filing a bug
+
+Include:
+
+- `/chrome doctor` output
+- `pi-chrome` version + extension version (the `doctor` output prints both)
+- The exact tool call + the result envelope you got
+- Page URL or a minimal repro page in `test-suite/`
+
+## Releasing
+
+- Bump `package.json` version.
+- Move `CHANGELOG.md` notes from the working section to the new version header.
+- `npm publish --access public`.
+
+## Code of conduct
+
+Be kind, be precise, ship things. PRs that break the "no re-login" promise will be closed with a note explaining which non-negotiable they hit.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 pi-chrome contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,63 +1,80 @@
 # pi-chrome
 
 [![npm version](https://img.shields.io/npm/v/pi-chrome.svg)](https://www.npmjs.com/package/pi-chrome)
+[![npm downloads](https://img.shields.io/npm/dm/pi-chrome.svg)](https://www.npmjs.com/package/pi-chrome)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-Control the Chrome profile you already use from Pi.
+> **The fastest way to give a [Pi](https://pi.dev) agent your real Chrome.**
+> No CDP. No throwaway profile. No re-login. Watch it work — or run silent.
 
-`pi-chrome` gives Pi agents browser tools for your **real Chrome windows, tabs, and authenticated sessions**. It uses a companion Chrome extension instead of the Chrome DevTools Protocol (CDP), so it does not launch a throwaway debug browser profile and does not require re-signing into the apps you already have open.
+```text
+You:    "Find my open GitHub PR tab, summarize review state, and screenshot the failing CI."
+Agent:  chrome_tab(list) → chrome_snapshot(uid:…) → chrome_screenshot(...)
+        ✓ 3 reviewers, 1 change requested, CI red on iOS. Saved → .pi/chrome-screenshots/ci.png
+You:    [keeps coding — agent never asked you to log in]
+```
 
-Multiple Pi sessions can use Chrome at the same time. The first Pi session starts the local bridge; later sessions automatically detect that bridge and submit their Chrome commands through it.
+`pi-chrome` ships **20+ browser tools** for Pi agents, backed by a small MIT-licensed Chrome extension that runs inside the Chrome profile **you already use** — including every site you're already signed into.
 
-## Why try it?
+---
 
-- **Uses your existing Chrome profile** — works with the Chrome windows/tabs you are already using, including logged-in GitHub, admin dashboards, local apps, and internal tools.
-- **Watch your authenticated Chrome work** — by default, `chrome_*` tool calls focus Chrome and activate the target tab so you can see the agent inspect, navigate, click, and type in real time. Switch to silent/background mode for the whole session with `/chrome quiet`, or pass `background: true` on a single tool call when you want quiet.
-- **Full browser automation toolkit for Pi** — list/create/activate/close tabs, snapshot pages with usable CSS selectors, navigate, evaluate JavaScript, click, type, press keys, wait for page state, and capture screenshots.
-- **Built-in setup and agent guidance** — `/chrome onboard` walks users through installing the companion extension, `/chrome doctor` checks connectivity and version drift, screenshots save to disk, and the prompt primer tells agents to inspect with `chrome_snapshot` before acting and avoid destructive actions unless explicitly requested.
+## Why pi-chrome vs. everything else
 
-## Install
+|                                | **pi-chrome**                     | Playwright / Puppeteer        | CDP-based agents              | Selenium / WebDriver          |
+| ------------------------------ | --------------------------------- | ----------------------------- | ----------------------------- | ----------------------------- |
+| Uses your real signed-in Chrome | ✅ yes (extension in your profile) | ❌ throwaway profile            | ⚠️ requires `--remote-debug` | ❌ throwaway profile            |
+| Re-login required               | **Never**                         | Every run                     | Sometimes                     | Every run                     |
+| Watch agent work, live          | ✅ default; toggle quiet          | ❌ headless or new window      | ⚠️ debugger banner always     | ❌ new window                  |
+| Works on strict-CSP pages       | ✅ `new Function` MAIN-world      | ✅                             | ✅                             | ✅                             |
+| Real browser-trusted clicks     | ✅ opt-in (`chrome clicks on`)    | ✅                             | ✅                             | ✅                             |
+| Multi-session safe              | ✅ shared local bridge            | ❌ port collisions             | ❌                             | ❌                             |
+| Network/console capture         | ✅ built-in                       | ✅                             | ✅                             | ⚠️ via extensions             |
+| Honest result envelopes¹       | ✅                                 | ⚠️                            | ❌                             | ❌                             |
+| Built-in benchmark suite²      | ✅ 30+ challenges                  | n/a                           | n/a                           | n/a                           |
 
-```bash
-pi install npm:pi-chrome
-```
+¹ Every action returns `pageMutated`, `defaultPrevented`, `elementVisible`, `occludedBy`, and `valueMatches` so the agent knows when a click didn't take effect — instead of looping blindly.
+² See [`test-suite/`](./test-suite) — static pages that grade any browser-control tool on trusted clicks, pointer humanization, keyboard fidelity, drag/drop, clipboard, Shadow DOM, iframes, file uploads, network capture, and fingerprint leaks.
 
-For local development from a checkout:
+---
 
-```bash
-pi install ./pi-chrome
-```
+## What an agent gets
 
-### Why an unpacked Chrome extension?
+**20 tools**, grouped by job. Every one runs against your already-open tabs.
 
-`pi-chrome` cannot ship through the Chrome Web Store: a Web Store extension is not allowed to talk to a local bridge controlled by another tool. Instead it ships as a small, MIT-licensed unpacked extension in `extensions/chrome-profile-bridge/browser-extension/` — read the source before loading. `/chrome doctor` reports the loaded extension version and warns when it drifts from the installed `pi-chrome`.
+| Category        | Tools                                                                                          |
+| --------------- | ---------------------------------------------------------------------------------------------- |
+| **Tabs**        | `chrome_tab` (list/new/activate/close/version), `chrome_launch`                                |
+| **Inspect**     | `chrome_snapshot` (uids + selectors + text + viewport), `chrome_screenshot`, `chrome_evaluate` |
+| **Navigate**    | `chrome_navigate` (with optional `initScript` at `document_start`), `chrome_wait_for`          |
+| **Interact**    | `chrome_click`, `chrome_type`, `chrome_fill`, `chrome_key`, `chrome_hover`                     |
+| **Gesture**     | `chrome_drag` (HTML5 DataTransfer), `chrome_scroll` (wheel + momentum), `chrome_tap` (touch)   |
+| **Files**       | `chrome_upload_file` (no native picker; works with React/Vue/Angular file inputs)              |
+| **Observe**     | `chrome_list_console_messages`, `chrome_list_network_requests`, `chrome_get_network_request` (with response body) |
 
-## First-time setup
+Each tool is documented inline in Pi — agents see the parameters and the gotchas (synthetic vs. trusted, autoplay gates, file picker limits) without trial-and-error.
 
-In Pi, run:
+---
 
-```text
-/chrome onboard
+## 60-second install
+
+```bash
+pi install npm:pi-chrome
 ```
 
-Pi first shows setup instructions and waits for confirmation. Press Enter to continue. On macOS it will:
+Then in Pi:
 
-- open `chrome://extensions`
-- reveal the bundled `browser-extension` folder in Finder
-- copy the extension folder path to your clipboard
+```text
+/chrome onboard
+```
 
-Then in Chrome:
+On macOS this opens `chrome://extensions`, reveals the bundled `browser-extension/` folder in Finder, and copies its path to your clipboard. In Chrome: **Developer mode** → **Load unpacked** → paste the path. Done.
 
-1. Enable **Developer mode**.
-2. Click **Load unpacked**.
-3. Select the revealed/copied `browser-extension` folder.
-4. Return to Pi and run:
+Verify:
 
 ```text
 /chrome doctor
 ```
 
-Expected output:
-
 ```text
 Performing Chrome bridge health check
 pi-chrome v<version>
@@ -65,122 +82,198 @@ pi-chrome v<version>
 ✓ Companion Chrome extension responding (ID: <chrome-extension-id>, ext v<version>)
 ```
 
-## Click modes
-
-pi-chrome can drive Chrome two ways:
+---
 
-- **Quiet clicks** — fast and unobtrusive. They work on most sites, but some pages (sign-in flows, copy-to-clipboard buttons, file pickers, autoplay videos, fullscreen, paywalls) ignore them because they don't look like a real human action.
-- **Real-looking clicks** — indistinguishable from a person clicking. They unlock the cases above, but Chrome shows a *"Pi Chrome Connector started debugging this browser"* banner at the top of every tab pi-chrome touches while it's working.
-
-Pick a mode with `/chrome clicks`:
+## Try this in 30 seconds after install
 
 ```text
-/chrome clicks auto     # default; quiet by default, real-looking only when needed
-/chrome clicks off      # always quiet, no banner ever
-/chrome clicks on       # always real-looking, banner stays up the whole session
-/chrome clicks status   # show the current mode
+Use chrome_tab list to find my GitHub notifications tab.
+chrome_snapshot it, then write a 5-bullet triage:
+which PRs need my review today, sorted by staleness.
+Do not click anything yet.
 ```
 
-For a one-off call, pass `trusted: true` (or `false`) on `chrome_click`, `chrome_type`, `chrome_fill`, `chrome_key`, `chrome_hover`, `chrome_drag`, or `chrome_scroll`. The per-call value wins over the global mode.
+You'll watch the agent jump to your GitHub tab and read the page — using **your** session, **your** filters, **your** orgs.
 
-First time you update pi-chrome to a version that supports real-looking clicks, Chrome will ask you to re-approve the extension. Open `chrome://extensions` and accept the new permission once.
+---
 
-## Background mode
+## Killer recipes (copy-paste into Pi)
 
-By default, `chrome_*` tools focus Chrome and activate the target tab so you can watch the agent work — great for demos, pair-driving, debugging, and first-time confidence that things are happening.
+Each one assumes tabs you already have open + accounts you're already signed into.
 
-When you want quiet (planner / audit / worker sessions running alongside your editor), turn background mode on for the whole Pi session:
+**PR triage**
+> Use chrome_tab list to find my GitHub notifications tab, snapshot it, summarize PRs needing my review.
 
-```text
-/chrome quiet          # toggle
-/chrome quiet on       # explicit
-/chrome quiet off      # explicit
-```
+**Linear standup**
+> Open my Linear current cycle in the active tab, snapshot it, write a 5-bullet standup.
 
-For a single tool call, the agent can pass `background: true` directly. The per-call value always wins over the session toggle.
+**Bug repro with evidence**
+> Open the staging app I'm already signed into, reproduce \<bug>, save a screenshot of each step under `./repro/`.
 
-## Quick demo prompts
+**Form auto-fill (no submit)**
+> Open the vendor portal, fill the new-vendor form from this JSON, stop before submit.
 
-After setup, try one of these in Pi:
+**Admin cross-check**
+> Across my Stripe / Postmark / our admin tabs, find any user where state disagrees.
 
-Silent inspection (no Chrome interruption):
+**Local dev visual diff**
+> Snapshot `localhost:3000` and the staging URL of the same page; tell me what's visually different.
 
-```text
-Inspect my active GitHub tab with chrome_snapshot using background:true and summarize the PR state without focusing Chrome.
+**Auth-only data pull**
+> Open my analytics dashboard tab and `chrome_evaluate` to extract today's KPIs from page state.
+
+**Network forensics**
+> Reproduce the checkout bug, then use `chrome_list_network_requests` to find the failing call and dump its response body.
+
+**File upload through React**
+> Open the photo uploader, `chrome_upload_file` with `./fixtures/sample.png`, confirm preview rendered.
+
+---
+
+## Architecture
+
+```
+  ┌──────────────────────┐                         ┌──────────────────────────┐
+  │  Pi agent (terminal) │  ─── http://127.0.0.1:17318 ─→  │ Chrome extension     │
+  │  chrome_* tools      │                         │ (your real profile)      │
+  └──────────┬───────────┘                         └─────────┬────────────────┘
+             │ same machine                                  │
+             ▼                                               ▼
+   Other Pi sessions                              Tabs you already have open
+   share the same bridge                          (signed in to GitHub,
+   automatically                                   Linear, Stripe, etc.)
 ```
 
-Existing authenticated tab:
+Multiple Pi sessions (planner / worker / audit) can all drive the same Chrome at once. The first session opens the local bridge; later sessions detect it and pipe their commands through.
+
+---
+
+## Click & input modes
+
+`pi-chrome` can drive Chrome two ways:
+
+- **Quiet** — synthetic DOM events. Fast, no UI banners. Drives React/Vue/Angular state. Won't satisfy autoplay, clipboard, file picker, fullscreen, or user-activation gates.
+- **Trusted** — `chrome.debugger` / CDP under the hood. Indistinguishable from a person clicking. Shows Chrome's *"Pi Chrome Connector started debugging this browser"* banner while active.
 
 ```text
-Use chrome_tab list to find my existing GitHub tab, chrome_snapshot it, then summarize the visible PR state. Do not click anything yet.
+/chrome clicks auto     # default: quiet, upgrade to trusted only when needed
+/chrome clicks off      # always quiet, never banner
+/chrome clicks on       # always trusted, banner stays up
+/chrome clicks status
 ```
 
-Local web app repro with screenshot:
+Per-call `trusted: true / false` on any input tool wins over the global mode.
+
+---
+
+## Background / watch modes
+
+By default, every `chrome_*` call focuses Chrome and activates the target tab so you can **watch the agent work** — invaluable for demos, debugging, and first-time confidence.
 
 ```text
-Use chrome_tab list to find my localhost app, inspect it with chrome_snapshot, navigate through the bug repro flow, and save a screenshot when you reach the broken state.
+/chrome quiet          # toggle for the whole session
+/chrome quiet on       # explicit
+/chrome quiet off      # explicit
 ```
 
-## Recipes
+Per-call `background: true` wins over the session toggle.
 
-Copy-paste these into Pi after setup. Each one uses tabs you already have open and accounts you are already signed into.
+---
 
-- **PR triage:** "Use chrome_tab list to find my GitHub notifications tab, snapshot it, and summarize PRs needing my review."
-- **Linear standup:** "Open my Linear current cycle in the active tab, snapshot it, and write me a 5-bullet standup."
-- **Bug repro with evidence:** "Open the staging app I'm already signed into, reproduce <bug>, and save a screenshot of each step under ./repro/."
-- **Form auto-fill (no submit):** "Open <vendor> portal, fill the new-vendor form from this JSON, but stop before submit."
-- **Admin cross-check:** "Across my Stripe / Postmark / our admin tabs, find any user where state disagrees."
-- **Local dev visual diff:** "Snapshot localhost:3000 and the staging URL of the same page; tell me what's visually different."
-- **Auth-only data pull:** "Open my analytics dashboard tab and chrome_evaluate to extract today's KPIs from the page state."
+## Honest results
 
-Screenshots save under `.pi/chrome-screenshots/` by default, which composes nicely with PR demo workflows.
+Most browser-automation libraries return `void` or a generic ack. `pi-chrome` returns a structured envelope on every interaction:
 
-## Diagnostics
+```text
+chrome_click(occluded-button) →
+  "Clicked el-3 — pageMutated=false; occluded by <div#overlay>"
+```
 
-- `/chrome doctor` — single command that checks connectivity and reports the loaded Chrome extension ID + version, plus a one-line fix for common setup failures (extension not loaded, bridge owner stale after `pi update`, version mismatch between pi-chrome and the loaded Chrome extension).
+```text
+chrome_type(react-input, "hello") →
+  "Typed into el-7 — valueMatches=true; pageMutated=true"
+```
 
-If the Chrome extension you have loaded is older than `pi-chrome` on disk, `/chrome doctor` will tell you to reload it from `chrome://extensions`.
+This is why agents using pi-chrome don't get stuck in retry loops on broken sites. They get the **reason** the action didn't land and can fix course in one turn.
 
-## Compose with
+---
 
-- **pi-qq** — ask side questions about what the agent saw in Chrome without polluting the main transcript: `/qq summarize what the active GitHub tab shows`.
-- **pi-bar** — watch context pressure as the agent scrapes large pages; the footer's red threshold is a clean signal to `/qq` for a recap before context overflows.
-- **PR demo skills** (such as `ios-pr-agent` / `ios-demo-record` workflows) — `chrome_screenshot` writes to `.pi/chrome-screenshots/` so you can attach images to PR descriptions or demo bundles.
+## Diagnostics
 
-## Tools
+- `/chrome doctor` — single command: connectivity, extension version, bridge owner, version drift, MAIN-world helper injection, `chrome_evaluate("1+1") === 2`, fingerprint flags.
+- `/chrome onboard` — guided first-time setup.
+- `/chrome quiet status`, `/chrome clicks status` — current modes.
 
-The package registers these Pi tools:
+If the loaded Chrome extension is older than `pi-chrome` on disk, `/chrome doctor` tells you to reload it from `chrome://extensions`.
 
-- `chrome_launch` — setup/help entry point; opens a URL if the bridge is connected
-- `chrome_tab` — list, create, activate, close, or inspect tabs
-- `chrome_snapshot` — inspect title, URL, visible text, viewport, and clickable/focusable selectors
-- `chrome_navigate` — navigate an existing tab
-- `chrome_evaluate` — evaluate JavaScript in a tab
-- `chrome_click` — click by selector or coordinates
-- `chrome_type` — type text, optionally focusing a selector first
-- `chrome_key` — send keyboard keys
-- `chrome_wait_for` — wait for a selector or expression
-- `chrome_screenshot` — capture viewport screenshots to disk
+---
 
-These tools are especially useful for authenticated web app debugging, repro flows, admin workflows, visual checks, and inspecting local development pages without rebuilding login state.
+## Composes with
 
-<details>
-<summary><strong>How it works (technical details)</strong></summary>
+- **[pi-qq](https://www.npmjs.com/package/pi-qq)** — `/qq summarize what the active GitHub tab shows` without polluting the main transcript.
+- **[pi-bar](https://www.npmjs.com/package/pi-bar)** — when the agent scrapes large pages, watch the context-usage segment turn yellow → red as a signal to `/qq` for a recap.
+- **PR demo skills** — screenshots write to `.pi/chrome-screenshots/` so you can attach them to PR descriptions or demo bundles.
 
-Pi starts a local bridge on `127.0.0.1:17318`. The companion Chrome extension, installed in your normal Chrome profile, polls that local bridge for commands and executes them using Chrome extension APIs.
+---
 
-If another Pi session is already running the bridge, additional Pi sessions automatically act as clients of that shared bridge. This lets planner/audit/worker sessions all use the same authenticated Chrome profile concurrently without fighting over the port.
+## Why an unpacked Chrome extension?
 
-This is intentionally different from CDP-based tools: the browser extension lives inside the profile you already use, so Pi can interact with existing tabs and authenticated page state.
+`pi-chrome` cannot ship through the Chrome Web Store — a Web Store extension cannot talk to a local bridge controlled by another tool on the same machine. So it ships as a small MIT-licensed unpacked extension in [`extensions/chrome-profile-bridge/browser-extension/`](./extensions/chrome-profile-bridge/browser-extension). **Read the source before loading.** `/chrome doctor` reports the extension version and warns when it drifts from your installed `pi-chrome`.
 
-</details>
+---
 
 ## Security model
 
-The companion Chrome extension runs in the Chrome profile where you install it and has broad tab/scripting permissions. Only install it from a package source you trust.
+The companion extension runs in the Chrome profile where you install it and has broad tab/scripting permissions. Only install it from a package source you trust.
 
-The Pi side listens on `127.0.0.1:17318` by default. Override before starting Pi with:
+The Pi side listens on `127.0.0.1:17318` by default. Override before starting Pi:
 
 ```bash
 PI_CHROME_BRIDGE_PORT=17319 pi
 ```
+
+There is no network exposure; the bridge binds to loopback only.
+
+---
+
+## Built-in benchmark suite
+
+[`test-suite/`](./test-suite) is a static page benchmark for **any** browser-control agent (not just pi-chrome). Each challenge exposes `window.__verdict` / `window.__reason` / `window.__events` and a manifest entry with expected results per mode (`synthetic`, `trusted`, `manual`).
+
+```bash
+cd test-suite && python3 -m http.server 8765
+# open http://127.0.0.1:8765/ in the Chrome window pi-chrome controls
+```
+
+Categories: `trusted-input`, `pointer-humanization`, `keyboard`, `activation-gates`, `scroll`, `drag-drop`, `clipboard`, `native-controls`, `frameworks`, `editing`, `dom-complexity`, `frames`, `files`, `observability`, `fingerprint`, `agent-safety`.
+
+If you build a competing tool, please open a PR with your scores. We benchmark in public.
+
+---
+
+## Roadmap signals
+
+`pi-chrome` is actively shipped. Things on the near roadmap:
+
+- More observability tools (DOM mutation streams, performance traces)
+- First-class iframe + Shadow-DOM uid stability across snapshots
+- Web Push & service worker introspection
+- Recorder mode that emits agent prompts from your own clicks
+
+If you want one of those next, open an issue.
+
+---
+
+## Contributing
+
+PRs welcome. The bar:
+
+1. Add a benchmark page in `test-suite/` that fails before your change and passes after.
+2. Keep `chrome_*` tool results honest — surface `pageMutated`, `valueMatches`, `defaultPrevented`, etc.
+3. Don't break the "no re-login" guarantee. Anything that requires a fresh profile is out of scope.
+
+---
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Open a GitHub issue prefixed with `[security]` at https://github.com/tianrendong/pi-packs/issues, or contact the maintainer directly if the issue is sensitive. Please do **not** include exploit details in a public issue without coordinating first.
+
+## Threat model
+
+`pi-chrome` is a developer tool you install knowingly. It is **not** designed to defend against:
+
+- Hostile pages running in your Chrome trying to detect or escape automation. (Standard browser security boundaries still apply, but a hostile page that already runs in your tab can do anything that page can already do.)
+- Other processes on your local machine. The bridge binds to `127.0.0.1:17318` (loopback only) but **does not authenticate** local callers. Any process running as your user can issue commands. If your threat model includes hostile local processes, run pi-chrome on a separate user account.
+
+`pi-chrome` **is** designed to:
+
+- Never exfiltrate page state to the network. All communication is loopback (`127.0.0.1`).
+- Surface every action with an honest result envelope so the agent can't silently do the wrong thing.
+- Require explicit opt-in for trusted-input mode (`/chrome clicks on` or `trusted: true`), which uses `chrome.debugger` and shows Chrome's banner.
+
+## The companion extension
+
+The Chrome extension under `extensions/chrome-profile-bridge/browser-extension/` runs with broad permissions: `tabs`, `scripting`, `debugger`, `webNavigation`, etc. **Only install it from a package source you trust.** Read the source before loading. Pin a known-good commit if you're security-sensitive.
+
+## Defaults
+
+- Loopback bridge only. No remote port. No telemetry.
+- Synthetic events first; trusted CDP only when explicitly enabled.
+- Quiet mode optional; tab/window focus is observable (the user can see Pi acting).
+
+## Override the port
+
+```bash
+PI_CHROME_BRIDGE_PORT=17319 pi
+```
+
+## Supported versions
+
+The latest minor on npm is supported. Security patches will be released as soon as practical.

package/docs/COMPARISON.md

@@ -0,0 +1,87 @@
+# pi-chrome vs. other browser-automation stacks
+
+This is the "should I use pi-chrome?" page. Honest comparisons. We benchmark in public — see [`../test-suite/`](../test-suite).
+
+## TL;DR
+
+| You are…                                                       | Use…                            |
+| -------------------------------------------------------------- | ------------------------------- |
+| A Pi agent operator who wants the agent to use **your real Chrome** (logged-in tabs, cookies, extensions) | **pi-chrome**                   |
+| Writing deterministic end-to-end tests in CI                   | Playwright / Cypress            |
+| Building a hosted scraping fleet on isolated profiles          | Playwright / Puppeteer / Browserless |
+| Building a "general web agent" SaaS that fetches its own pages  | browser-use / Stagehand / Skyvern    |
+| Debugging your own app from your editor without leaving your real session | **pi-chrome**                   |
+
+Different tools, different jobs. `pi-chrome` is the only one that says: *"don't make me sign in again to do work I'd do as myself."*
+
+---
+
+## Feature matrix
+
+|                                                | **pi-chrome**     | Playwright          | Puppeteer           | Stagehand           | browser-use         | Selenium            |
+| ---------------------------------------------- | ----------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| Drives your **real, signed-in** Chrome profile | ✅                | ❌ throwaway        | ❌ throwaway        | ❌ throwaway        | ❌ throwaway        | ❌ throwaway        |
+| Zero re-login                                   | ✅                | ❌                  | ❌                  | ❌                  | ❌                  | ❌                  |
+| First-class Pi tool integration                | ✅ 20 tools        | n/a                 | n/a                 | n/a                 | n/a                 | n/a                 |
+| Synthetic input (fast, no banner)               | ✅                | ❌ always trusted   | ❌                  | ❌                  | ❌                  | ❌                  |
+| Trusted (CDP) input on demand                  | ✅ opt-in          | ✅ always           | ✅ always           | ✅                  | ✅                  | ✅                  |
+| Honest result envelopes (`pageMutated`, `occludedBy`, `valueMatches`) | ✅                | ⚠️ partial          | ⚠️ partial          | ❌                  | ❌                  | ❌                  |
+| Network capture w/ response body               | ✅                | ✅                  | ✅                  | ⚠️                  | ⚠️                  | ⚠️                  |
+| Console capture                                 | ✅                | ✅                  | ✅                  | ⚠️                  | ⚠️                  | ⚠️                  |
+| Real touch events (mobile PWAs)                | ✅ `chrome_tap`    | ✅                  | ✅                  | ⚠️                  | ⚠️                  | ❌                  |
+| File upload through React/Vue controlled inputs | ✅ no native picker | ✅                  | ✅                  | ✅                  | ⚠️                  | ⚠️                  |
+| HTML5 drag/drop with `DataTransfer`            | ✅                | ✅                  | ⚠️                  | ⚠️                  | ⚠️                  | ⚠️                  |
+| Multi-session shared bridge                    | ✅                | ❌                  | ❌                  | ❌                  | ❌                  | ❌                  |
+| MIT-licensed                                   | ✅                | Apache-2            | Apache-2            | MIT                 | MIT                 | Apache-2            |
+| Watch the agent work, live                     | ✅ default         | ❌ headless / new   | ❌                  | ❌                  | ❌                  | ❌                  |
+
+---
+
+## "But Playwright has a `storageState` option"
+
+Yes — you can export cookies and replay them. In practice for agent workflows that breaks down fast:
+
+1. **OAuth + SSO** providers (Okta, Google, GitHub) often pin sessions to TLS fingerprints, device IDs, and browser-extension state that doesn't survive replay.
+2. **MFA** tokens expire. Re-prompts in the middle of an agent run = dead end.
+3. **Internal admin tools** often hard-pin to your real device for security.
+4. **Your editor / IDE / colleagues** see your real Chrome, not a hidden one. Watching an agent in a separate window is jarring.
+
+`pi-chrome` sidesteps all of this by living **inside** the Chrome profile you're already logged into. The agent operates as you, because it literally is you (in your tabs).
+
+---
+
+## "Is this safer than CDP?"
+
+It's a different security boundary, not strictly safer. Trade-offs:
+
+- **CDP-based tools** require `chrome --remote-debugging-port`. That port is unauthenticated and exposes the whole browser to any local process. Easy to misconfigure.
+- **pi-chrome** runs through an extension you install yourself with broad permissions (tabs, scripting, debugger). The bridge listens on `127.0.0.1:17318` loopback only. **Only install the bundled extension if you trust the source you got the npm package from.**
+
+If your threat model excludes extensions with broad permissions, neither approach is a fit — you want a sandboxed CI runner.
+
+---
+
+## When NOT to use pi-chrome
+
+- **Headless production scraping at scale** — you want isolated profiles, parallel containers, retries. Use Playwright or Browserless.
+- **Cross-browser testing** — pi-chrome is Chrome only by design (it's a Chrome extension). Use Playwright for Firefox/WebKit.
+- **Untrusted page execution** — same reason. Use a sandbox.
+- **You don't already use Chrome** — the whole value proposition is "your real Chrome". If your day is in Arc / Firefox / Brave, you'll get less out of it (though Brave/other Chromium browsers work fine technically).
+
+---
+
+## Reproducing this table
+
+Run [`../test-suite/`](../test-suite) against your tool of choice and open a PR with your scores. The benchmark covers:
+
+- trusted-input gates (clipboard, fullscreen, file picker, autoplay)
+- pointer humanization (entropy, paths, timing)
+- keyboard fidelity (Tab flows, modifier chords, IME)
+- React-style value tracking and contenteditable
+- Shadow DOM + iframe targeting
+- file attachment to `<input type=file>`
+- console & network observability
+- fingerprint leaks (`navigator.webdriver`, runtime flags)
+- agent-safety honeypots
+
+`window.__verdict` / `window.__reason` / `window.__events` make it deterministic for any tool to grade itself.

package/docs/EXAMPLES.md

@@ -0,0 +1,166 @@
+# pi-chrome examples
+
+Real, useful agent prompts. Drop any of these into Pi after running `/chrome onboard`. Each one uses Chrome tabs and accounts you already have.
+
+## Daily workflow
+
+### PR triage
+
+```text
+Use chrome_tab list to find my GitHub notifications tab.
+chrome_snapshot it. Group PRs by:
+  - awaiting my review
+  - blocked on me (changes requested back)
+  - mergeable (approved + green CI)
+Output a 5-bullet ranked triage. Do not click anything.
+```
+
+### Linear standup
+
+```text
+Open my Linear current cycle in the active tab.
+chrome_snapshot, then write yesterday/today/blockers
+in the exact format my standup channel uses.
+```
+
+### Slack catch-up
+
+```text
+For each unread channel in my Slack tab, chrome_snapshot,
+extract the top 3 messages that mention me or my team,
+and summarize what I missed in <100 words total.
+```
+
+## Debugging
+
+### Reproduce a customer bug with evidence
+
+```text
+1. chrome_navigate to https://staging.acme.com/orders/<id>
+2. chrome_snapshot
+3. Click "Refund" with chrome_click
+4. Use chrome_list_network_requests to capture the API call
+5. chrome_get_network_request on the failing one — give me the response body
+6. chrome_screenshot the error state to ./repro/refund-bug.png
+```
+
+### Visual diff local vs staging
+
+```text
+chrome_screenshot http://localhost:3000/pricing → ./diff/local.png
+chrome_screenshot https://staging.acme.com/pricing → ./diff/staging.png
+Then read both, describe layout differences in plain English.
+```
+
+### Console + network forensics
+
+```text
+Reproduce the checkout bug on the active tab.
+After the failure:
+  - chrome_list_console_messages
+  - chrome_list_network_requests
+Cross-reference the timestamps and tell me what broke first.
+```
+
+## Admin / ops
+
+### Multi-tab cross-check
+
+```text
+I have Stripe, Postmark, and our internal admin open in 3 tabs.
+For user <id>, chrome_snapshot each tab in turn and find
+any field where state disagrees. Output a 3-column table.
+```
+
+### Bulk gentle action (safe form-fill, no submit)
+
+```text
+Open our vendor portal "Add Vendor" form.
+For each row in ./vendors.csv:
+  - chrome_fill the form
+  - chrome_screenshot it
+  - STOP before submit
+  - chrome_evaluate "history.back()" to return to the list
+I will review screenshots and submit manually.
+```
+
+### Auth-only data pull
+
+```text
+My analytics dashboard is open and the cookie auth would die in headless mode.
+chrome_evaluate to read window.__APP_STATE__.dashboardData
+and dump today's KPIs as JSON.
+```
+
+## Demos / PRs
+
+### Capture screenshots for a PR description
+
+```text
+On localhost:3000/feature-x:
+  - empty state → ./pr/01-empty.png
+  - filled state → ./pr/02-filled.png
+  - error state (delete the API key from devtools first) → ./pr/03-error.png
+Save each with chrome_screenshot. Output a markdown block I can paste into the PR.
+```
+
+### Record a guided demo flow
+
+```text
+On my staging app:
+1. Walk the new-onboarding flow start to finish
+2. After each chrome_click or chrome_navigate, chrome_screenshot
+3. Save numbered PNGs under ./demo/
+4. Write narration captions for each step
+```
+
+## Forms with frameworks
+
+### React controlled inputs
+
+```text
+chrome_fill (not chrome_type) for React inputs — it uses the
+framework-aware native value setter so the form's state actually updates.
+After each fill, the result envelope's valueMatches=true confirms the
+component re-rendered with the new value.
+```
+
+### File upload without the native picker
+
+```text
+chrome_upload_file paths=[./fixtures/avatar.png] selector="input[type=file]"
+# No native file picker opens. Works with React/Vue/Angular controlled inputs.
+```
+
+### Drag-to-reorder lists
+
+```text
+chrome_drag fromUid=row-3 toUid=row-1
+# Fires real HTML5 dragstart/dragover/drop with a shared DataTransfer.
+```
+
+## Multi-session patterns
+
+`pi-chrome` shares one bridge across all Pi sessions on the same machine. Useful patterns:
+
+### Planner + Worker
+
+- **Planner session** stays high level: "find the bug, decide the fix."
+- **Worker session** runs the actual `chrome_*` tools.
+- Both see the same Chrome state because they're both pointing at your real profile.
+
+### Watcher
+
+A third Pi session can run `chrome_snapshot` periodically in `background: true` mode and post summaries via `pi-qq` — handy for long-running flows.
+
+## When to prefer trusted clicks
+
+Pass `trusted: true` on `chrome_click` (or run `/chrome clicks on`) when:
+
+- the click should open a file picker
+- the click should write to the clipboard or read it
+- the click should start an audio/video play
+- the click should request fullscreen / push permission
+- the page is wrapped in a strict user-activation guard (some paywalls / login flows)
+
+Everything else is faster and quieter without it.

package/docs/FAQ.md

@@ -0,0 +1,79 @@
+# pi-chrome FAQ
+
+## Does this work with Brave / Arc / Edge / Vivaldi?
+
+Yes. Any Chromium-based browser that supports unpacked extensions and the `chrome.debugger` API will work. The extension is named "Pi Chrome Connector" but the source is browser-agnostic. Firefox / WebKit are out of scope (different extension models).
+
+## Will it slow my browser down?
+
+The companion extension is idle when no Pi command is in flight. It uses Manifest V3 service worker activation, so it wakes for a request and goes back to sleep. No content script is injected globally.
+
+## Does it work in Chrome incognito?
+
+By default no — extensions need explicit "Allow in incognito" permission. Toggle it on `chrome://extensions` if you want pi-chrome to see incognito tabs. We don't recommend it for sensitive work.
+
+## Will sites detect that I'm automating?
+
+For **synthetic** (quiet) input: yes, technically. `event.isTrusted` is `false`. Most sites don't check; some anti-bot defenses do.
+
+For **trusted** (CDP) input: events are `isTrusted=true`, pointer paths are humanized, key cadence has variance. Most fingerprint-based detectors don't fire. Some specifically check for the `chrome.debugger` API attached and will show the "Chrome is being debugged" banner. That banner is the visible cost of trusted mode.
+
+The [`test-suite/`](../test-suite) grades both modes against common detection signals.
+
+## Why do I see a banner saying "Pi Chrome Connector started debugging this browser"?
+
+That's Chrome's built-in warning when an extension uses `chrome.debugger`. pi-chrome uses it only in trusted-input mode. If you don't want to see it, run `/chrome clicks off` and accept that some sign-in flows / file pickers / clipboard ops won't work.
+
+## Can a malicious page escape and access my other tabs?
+
+No — pages cannot directly talk to extensions. Commands flow agent → local bridge (`127.0.0.1:17318`) → extension → tab. The bridge binds to loopback only. The risk surface is **other local processes** that could connect to `127.0.0.1:17318` and impersonate Pi. If that's in your threat model, run pi-chrome on a separate user account.
+
+## Can multiple Pi sessions use it at once?
+
+Yes. The first session opens the local bridge; later sessions detect it and pipe their commands through the same bridge. Planner + worker + audit can all drive the same Chrome concurrently.
+
+## Why can't this be on the Chrome Web Store?
+
+Web Store extensions cannot communicate with a local process bridge controlled by another tool — Google's policy. pi-chrome must ship as an unpacked extension you load yourself. The upside: you can read the source. The downside: each Chrome update may prompt you to re-confirm.
+
+## What happens when I update pi-chrome?
+
+`/chrome doctor` will warn you if the loaded extension is older than the installed `pi-chrome`. Reload it from `chrome://extensions` to pick up the new version. Trusted-input mode in particular requires re-approving the `debugger` permission once.
+
+## What's the install footprint?
+
+- Pi side: one extension that registers ~20 tools and a few slash commands.
+- Chrome side: one unpacked extension, ~5000 LOC of plain JavaScript, no dependencies.
+
+## Can I script it without Pi?
+
+The Pi-facing tools are thin wrappers around an HTTP bridge at `127.0.0.1:17318`. You could call it directly from any process, but the API is internal and may change. If you need a stable scripting interface, file an issue and we'll consider stabilizing.
+
+## Does `chrome_evaluate` work on strict-CSP pages?
+
+Yes. The handler compiles with `new Function(...)` in the MAIN world, which works under `script-src 'self'` without `'unsafe-eval'`. Multi-statement bodies are supported via a statement-mode fallback. Exceptions are surfaced to the agent.
+
+## Why does my click return `pageMutated=false`?
+
+Either:
+- The element was occluded (look for `occludedBy: <selector>` in the envelope).
+- The click handler called `event.preventDefault()` and the page intentionally ignored it.
+- The site rejects synthetic events. Try `trusted: true` or `/chrome clicks on`.
+
+The result envelope tells you which one. **Don't blind-retry.**
+
+## Why does `chrome_type` return `valueMatches=false`?
+
+The editor rejected the synthetic input. Common culprits: contenteditable rich-text editors, native date pickers, masked-input libraries. Try `chrome_fill` (uses framework-aware native setters) or `trusted: true`.
+
+## How do I attach a file to a React file input?
+
+`chrome_upload_file` — populates `input.files` via a real `DataTransfer` and fires `input` + `change` events. It does **not** open the native file picker (no synthetic event can; that's a user-activation gate). Works with React/Vue/Angular controlled inputs.
+
+## Can it record videos?
+
+Not yet. Screenshots only. Video recording is on the roadmap.
+
+## How do I file a good bug report?
+
+Include `/chrome doctor` output, the exact tool call, and the result envelope. If the page is public, link to it; if private, distill it into a benchmark page under `test-suite/challenges/`. See [CONTRIBUTING.md](../CONTRIBUTING.md).

package/extensions/chrome-profile-bridge/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Chrome Connector",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Lets Pi control tabs in Chrome via a local connector at 127.0.0.1.",
   "permissions": ["tabs", "scripting", "storage", "activeTab", "alarms", "webNavigation", "debugger"],
   "host_permissions": ["<all_urls>", "http://127.0.0.1:17318/*"],

package/package.json

@@ -1,22 +1,55 @@
 {
 	"name": "pi-chrome",
-	"version": "0.14.2",
-	"description": "Drive your existing logged-in Chrome from Pi — no re-login, no throwaway profile, watch the agent work in real time (or toggle quiet background mode).",
+	"version": "0.14.4",
+	"description": "The de-facto browser automation toolkit for Pi agents. Drive your existing logged-in Chrome — no re-login, no throwaway profile, no CDP. 20+ tools (click, type, navigate, screenshot, network capture, file upload, drag, scroll, touch) + honest result envelopes + a built-in benchmark suite.",
 	"keywords": [
+		"pi",
 		"pi-package",
 		"pi-extension",
+		"pi-agent",
 		"chrome",
+		"chrome-extension",
 		"browser",
-		"automation",
+		"browser-automation",
+		"browser-control",
+		"web-automation",
+		"agent",
+		"ai-agent",
+		"llm-agent",
+		"llm-tools",
+		"agentic",
+		"playwright-alternative",
+		"puppeteer-alternative",
+		"selenium-alternative",
+		"cdp-alternative",
 		"authenticated-session",
 		"real-profile",
-		"web-debugging"
+		"web-debugging",
+		"web-scraping",
+		"screenshot",
+		"automation-tools",
+		"browser-use",
+		"stagehand-alternative"
 	],
 	"license": "MIT",
+	"homepage": "https://github.com/tianrendong/pi-packs/tree/main/packages/pi-chrome#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tianrendong/pi-packs.git",
+		"directory": "packages/pi-chrome"
+	},
+	"bugs": {
+		"url": "https://github.com/tianrendong/pi-packs/issues"
+	},
 	"type": "commonjs",
 	"files": [
 		"extensions",
-		"README.md"
+		"docs",
+		"README.md",
+		"CHANGELOG.md",
+		"CONTRIBUTING.md",
+		"SECURITY.md",
+		"LICENSE"
 	],
 	"pi": {
 		"extensions": [