@petukhovart/agent-view 0.3.0 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "agent-view",
+  "owner": {
+    "name": "PetukhovArt",
+    "url": "https://github.com/PetukhovArt"
+  },
+  "plugins": [
+    {
+      "name": "agent-view",
+      "source": "./",
+      "description": "Visual verification CLI for desktop apps (Electron/Tauri/Browser) via Chrome DevTools Protocol. Inspect DOM, interact with UI, capture screenshots, and read WebGL scene graphs."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-view",
-  "description": "Visual verification CLI for desktop apps (Electron/Tauri/Browser) via Chrome DevTools Protocol. Inspect DOM, interact with UI, capture screenshots, and read WebGL scene graphs.",
-  "version": "0.1.0",
+  "description": "Visual verification CLI for desktop apps (Electron/Tauri/Browser) via Chrome DevTools Protocol. Ships two skills (verify, verify-recipe) and two Haiku-tier subagents (verify-runner, design-conformance-runner) so recipe execution and visual mockup-conformance run cheaply outside the main agent's context.",
+  "version": "0.6.0",
   "keywords": [
     "cdp",
     "electron",

package/README.md

@@ -1,13 +1,37 @@
 # agent-view
 
-**Give your AI agent eyes and hands for desktop apps.**
+**Give your AI agent eyes and hands for complex desktop apps verification**
 
 AI coding agents can write code, run tests, and read logs — but they can't *see* what the app actually looks like. Without visual verification, an agent is essentially **coding blind** — builds pass, tests are green, but the login form is broken, the button is off-screen, or the modal never appears.
 
-agent-view bridges that gap: it connects to any Chromium-based desktop app via Chrome DevTools Protocol and lets the agent inspect the UI, take screenshots, click buttons, and fill forms.
+agent-view bridges that gap: it connects to any Chromium-based desktop app via Chrome DevTools Protocol and lets the agent inspect, interact, and verify.
 
 Built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), but works with any AI agent or automation pipeline that can call CLI commands.
 
+## 5-minute quickstart
+
+1. **[Install](#install--update)** — `npm i -g @petukhovart/agent-view` plus the Claude Code plugin.
+2. **[Enable CDP](#enabling-cdp) in your app** — one line in your Electron `main.ts`, gated to dev builds.
+3. **`agent-view init`** in your project — then add `"allowEval": true` to the generated `agent-view.config.json`.
+4. **`agent-view launch`** — starts your app and waits for CDP readiness.
+5. **In Claude Code:** describe what you want verified — see [example prompts](#recommended-workflow-with-claude-code).
+
+Each step links to the full explanation below.
+
+## What it does
+
+- **DOM accessibility tree** with ref IDs — compact, LLM-friendly, with text/role filters; `--compact` merges single-child chains for 40–60% fewer tokens, `--count` returns just the match count, `--max-lines` caps output, `--diff` emits only what changed since the last call
+- **Screenshots** — full-res PNG, scaled WebP (~3–12× fewer vision tokens), or `--crop <filter>` to a single element bounding box
+- **Interaction** — click, fill, and drag by ref or coordinates; works with Vue/React/native frameworks
+- **JS state via `eval`** — read store contents, computed values, async results without scraping the DOM
+- **Reactive state via `watch`** — stream JSON-patch diffs of any expression (store, ref, computed) until a condition is met
+- **Console capture** — `console.log/warn/error` per page and per worker, with level/since filters and `--follow --until <pattern>` for early exit on a matching log
+- **Worker access** — SharedWorker, ServiceWorker, dedicated Worker visible alongside pages; fuzzy `--target` resolution everywhere (id → title → URL)
+- **Canvas / WebGL scene graph** — PixiJS today, engine-pluggable; `--compact` mirrors the DOM mode
+- **Design-conformance verification** — pair screenshot commands with local design references (Figma export, hand-off
+  PNGs, any image on disk) inside a verify-recipe; the `design-conformance-runner` subagent reports visual deviations
+  against the mockup
+
 ## Why CLI, not MCP?
 
 Most alternatives in this space are MCP servers with 30+ tool definitions loaded into context on every session. That burns tokens before the agent even starts working.
@@ -16,68 +40,75 @@ agent-view is a CLI. One Bash call, compact text output, zero schema overhead. T
 
 And CLI works everywhere — Claude Code, Copilot, Codex, custom pipelines, CI. No MCP client required.
 
-## The feedback loop
+## Install & Update
 
-The real power isn't in individual commands — it's in the **loop**:
+### Claude Code (recommended)
 
-```
-Code → Launch → See → Verify → Fix → See again
-```
+Two steps — both required:
 
-The agent writes code, then immediately checks what the user would see. If something's wrong, it fixes and re-checks — no human needed. This catches problems that builds and tests miss: CSS regressions, broken layouts, missing error messages, silent IPC failures.
-
-## v0.3.0 — DevTools access (eval, console, workers)
-
-Beyond DOM and screenshots, v0.3.0 adds direct access to JS state and console — including SharedWorker / ServiceWorker. Useful when «what's rendered» isn't enough and you need to check what's actually in the store, in a worker, or in the console.
+```bash
+# 1. Install the plugin — adds two skills: verify (run checks against a live app) and verify-recipe (author a verification plan)
+/plugin marketplace add PetukhovArt/agent-view
+/plugin install agent-view@agent-view
 
-- `eval <expr>` — read state directly (`store.user.role`, computed values, async getters). Gated by `"allowEval": true` in config.
-- `eval --target <worker>` — same, but inside a SharedWorker / ServiceWorker / dedicated Worker.
-- `console` — capture `console.log/warn/error` per page or per worker. `--clear` for baselines, `--level` to filter.
-- `targets` — list every connectable CDP target.
+# 2. Install the CLI — the skill calls these binaries; the plugin doesn't bundle them
+npm install -g @petukhovart/agent-view
+```
 
-See [Commands](#commands) for flags. Full notes in [CHANGELOG](CHANGELOG.md).
+The plugin ships two skills. **`verify`** executes visual and runtime checks against a running app. **`verify-recipe`** generates a `.claude/verify-recipes/<slug>.md` file — a disciplined, cheapest-first command sequence for a feature or bugfix — that you or any AI agent can run later. Trigger it with phrases like "write a verify-recipe for the login fix" or "generate a verification plan for this feature".
 
-## Performance
+For Haiku-cost recipe execution and visual conformance against design mockups,
+see [Recommended workflow with Claude Code](#recommended-workflow-with-claude-code) below.
 
-AI agents run dozens of `dom → click → dom` verification cycles per session. Every millisecond compounds. agent-view v0.2.0 is built specifically for this pattern.
+Verify:
 
-### Benchmark results (Electron app, ~200 AX nodes)
+```bash
+agent-view --version   # 0.5.0+
+```
 
-| Scenario | v0.1.0 | v0.2.0 | vs Playwright* |
-|---|---|---|---|
-| `dom` cold fetch | 10ms | 2ms | ~30–80ms |
-| `dom` warm (cache hit) | 10ms | 1ms | ~30–80ms |
-| Full cycle `dom → click → dom` | 27ms | 17ms | ~75ms |
-| `click --filter "Save"` | 12ms | 17ms† | ~15–30ms |
+### Standalone CLI (any other agent, CI, or scripting)
 
-\* *Playwright estimate based on architectural analysis — no published Electron-specific benchmarks exist*
-† *queryAXTree has CDP overhead that exceeds the benefit on small DOMs; improves on large production DOMs (1000+ nodes)*
+```bash
+npm install -g @petukhovart/agent-view
+```
 
-### What makes it fast
+Everything works from this alone — `agent-view dom`, `screenshot`, `eval`, etc. Skip the plugin step.
 
-**AX tree cache (300ms TTL).** The single biggest win. When an agent calls `dom`, then immediately `click --filter`, the second fetch hits the in-process cache instead of making a CDP round-trip. Cache is invalidated aggressively — busted on every `click`, `fill`, or page navigation.
+### Update
 
-**Parallel CDP calls in click.** Previously 5 serial round-trips; now 3 parallel batches. `DOM.resolveNode` and `DOM.getBoxModel` run concurrently, then mouse events fire back-to-back without waiting for each response (the same approach Playwright uses internally).
+```bash
+# Update the CLI to the latest version
+npm update -g @petukhovart/agent-view
 
-**`Accessibility.queryAXTree` for targeted lookups.** Plain string filters (`click --filter "Save"`) and `role:name` filters (`click --filter "button:Save"`) query the browser directly instead of fetching the full tree. Falls back gracefully on older Electron versions.
+# Update the Claude Code plugin (refreshes skills from the marketplace)
+/plugin marketplace update agent-view
+/plugin install agent-view@agent-view   # re-run to pick up new skill versions
+```
 
-**Raw CDP, no relay.** No Playwright client-server relay between your agent and the browser. The server process holds the CDP WebSocket connection and reuses it across commands.
+The two are independent — bump the CLI when a new release ships features (see `CHANGELOG.md`), bump the plugin when skill instructions change.
 
 ## Enabling CDP
 
+agent-view talks to your app over Chrome DevTools Protocol. Your app must be launched with a debugging port open.
+
 ### Recommended: in code (reliable, works with any build tool)
 
-Add to your Electron main process:
+Add to your Electron main process, **before `app.whenReady()`** (top of `main.ts`/`main.js`, right after the `electron` import — switches set after the app is ready are ignored):
 
 ```js
-app.commandLine.appendSwitch('remote-debugging-port', '9222');
+import { app } from 'electron';
+
+app.commandLine.appendSwitch('remote-debugging-port', '9876');
 ```
 
-For dev-only:
+> Any free port works — `9876` is just an example. Avoid `9222` (Chrome's own default remote-debugging port) to prevent
+> collisions when Chrome is open.
+
+**Production safety:** an open CDP port in a signed/notarized build is a remote-code-execution surface. Gate it on `!app.isPackaged` so it only opens in dev:
 
 ```js
 if (!app.isPackaged) {
-  app.commandLine.appendSwitch('remote-debugging-port', '9222');
+    app.commandLine.appendSwitch('remote-debugging-port', '9876');
 }
 ```
 
@@ -85,72 +116,163 @@ if (!app.isPackaged) {
 
 ```bash
 # Plain Electron
-electron . --remote-debugging-port=9222
+electron . --remote-debugging-port=9876
 
 # electron-vite (note the -- to forward the flag past the build tool)
-npx electron-vite dev -- --remote-debugging-port=9222
+npx electron-vite dev -- --remote-debugging-port=9876
 ```
 
 ### Other runtimes
 
-| Runtime | Setup |
-|---------|-------|
-| **Tauri** | CDP via devtools configuration |
-| **Any Chromium app** | `--remote-debugging-port=9222` launch flag |
+| Runtime              | Setup                                      |
+|----------------------|--------------------------------------------|
+| **Tauri**            | CDP via devtools configuration             |
+| **Any Chromium app** | `--remote-debugging-port=9876` launch flag |
 
 ### Verify CDP is working
 
 ```bash
-curl -s http://localhost:9222/json/version
+curl -s http://localhost:9876/json/version
 ```
 
-If you see a JSON response with browser info — you're good.
+If you see a JSON response with process info — you're good.
 
-## Install
+## Quick start with Claude Code (Prompting)
 
-### As CLI tool
+Assumes the plugin and CLI are installed (see [Install & Update](#install--update)) and CDP is enabled in your app (
+see [Enabling CDP](#enabling-cdp)).
+
+**1. Generate config once:**
 
 ```bash
-npm install -g @petukhovart/agent-view
+cd your-electron-project
+agent-view init   # writes agent-view.config.json — auto-detects runtime, port, launch script, webgl engine
 ```
 
-### As Claude Code plugin
+Then open `agent-view.config.json` and add `"allowEval": true` if you want recipes to use `eval` / `watch` (most do —
+store/state assertions are 100× cheaper than DOM scraping). Off by default for security; see [Config](#config) for the
+full field list.
+
+**2. Start your app:**
 
 ```bash
-# Add marketplace (once)
-/plugin marketplace add PetukhovArt/agent-view
+agent-view launch   # uses the `launch` command from config, waits for CDP readiness, idempotent
+```
 
-# Install plugin
-/plugin install agent-view@agent-view
+(Or start it yourself with `npm run dev` etc. — `launch` is just a convenience.)
+
+**3. From Claude Code, ask for a verification:**
+
+```text
+The "Save" button on the Settings dialog stayed enabled while a save was in flight.
+I added a `saving` ref bound to :disabled. Verify it works:
+- after click, button must be disabled until network completes
+- no console errors in the flow
 ```
 
-This gives Claude the `/agent-view:verify` skill — it knows when and how to use agent-view for visual verification during development workflows.
+Claude picks the `verify` skill, runs a handful of `eval` / `dom --filter` / `console` calls against your live app,
+reports what passed and what failed. No CLI commands typed by you.
+
+For a repeatable, multi-step verification (PRD/plan-driven, with optional design-mockup conformance),
+see [Recommended workflow with Claude Code](#recommended-workflow-with-claude-code) — it's the canonical 3-phase prompt
+flow this package is built around.
 
-## Quick start
+### Without Claude Code (manual CLI / CI / other agents)
+
+If you're scripting from CI or another agent, the CLI works standalone:
 
 ```bash
-cd your-electron-project
+agent-view discover                  # List all windows (JSON)
+agent-view dom --filter "Submit"     # Accessibility tree, filtered, with ref IDs
+agent-view fill 3 "hello@example.com"
+agent-view click 7
+agent-view eval "store.state.user.role"
+agent-view screenshot --crop "Sidebar" --scale 0.5
+```
+
+Full surface in [Commands](#commands) below.
+
+## Recommended workflow with Claude Code
+
+A repeatable, token-efficient flow for "I shipped a feature/fix → confirm it actually works visually and at runtime".
+Three phases, each driven by a focused prompt.
+
+### Phase 1 — Author the verification plan (Opus / Sonnet)
 
-# 1. Generate config (auto-detects runtime, port, launch command)
-agent-view init
+Generate the recipe **once**, from a PRD / plan file / Jira ticket / commit range. The recipe is reusable — re-run after
+every iteration on the same feature.
 
-# 2. Start your app (or let agent-view do it)
-agent-view launch
+```text
+Generate a verify-recipe for the changes in commits <hash1>..<hash2>.
+Source plan: .claude/plans/2026-04-27-login-redirect.md
+Original symptom: after login, redirect went to /home instead of /dashboard.
 
-# 3. See what's on screen
-agent-view discover          # List all windows
-agent-view dom               # Accessibility tree with ref IDs
-agent-view screenshot        # PNG screenshot
+Design references (if any):
+- /abs/path/figma-exports/login-success.png    → label "post-login dashboard"
+- /abs/path/figma-exports/error-state.png      → label "invalid creds error"
+```
+
+What this triggers: the `verify-recipe` skill interviews you (if more context needed), then writes a
+`.claude/verify-recipes/<slug>.md` with `Repro Steps`, `Evidence Commands` (cheapest-first: `eval` / `dom --filter`
+before `screenshot`), `Regression Checks`, and — if you provided design refs — a `Design Conformance` table mapping
+screenshot commands to expected reference images.
+
+**Tip:** if you implemented from a Figma file via the `figma-implement-design` skill, it likely already saved exports
+somewhere on disk — pass those paths. agent-view does NOT fetch from Figma URLs; provide local files only.
 
-# 4. Interact
-agent-view click 5           # Click element by ref
-agent-view fill 3 "hello"   # Type into input
+### Phase 2 — Run the recipe (delegated to Haiku)
 
-# 5. Verify the result
-agent-view dom --filter "success"   # Check for expected element
-agent-view screenshot               # Visual confirmation
+```text
+Run the verify-recipe at .claude/verify-recipes/<slug>.md.
 ```
 
+What this triggers: the `verify` skill resolves the window via `agent-view discover`, then spawns the `verify-runner`
+subagent (Haiku) to execute every step and return a compact JSON report. If the recipe has a `Design Conformance`
+section, `design-conformance-runner` (also Haiku) runs in parallel and visually compares screenshots against the
+references.
+
+**Effect on cost:** raw output (DOM dumps, screenshots, eval values) stays in the subagent. The main agent only sees the
+merged JSON report — typically <2k tokens vs ~50k if Opus ran the recipe directly.
+
+### Phase 3 — Iterate on failures (Opus / Sonnet)
+
+The merged report lists `failed`, `requires_visual_review`, and `major_mismatch` items with one-sentence diagnoses. Hand
+any subset back to the main agent:
+
+```text
+Three steps failed in the verify run. Fix step 4 (zone filter not mutating store)
+and step 7 (selective filter heading missing). Re-run only those two steps after the fix.
+```
+
+The main agent re-runs only the failing commands itself for richer evidence, makes the fix, and re-spawns
+`verify-runner` for the targeted re-check — not the whole recipe.
+
+### One-shot prompt (when there's no plan to convert)
+
+For small fixes where you don't want a persistent recipe file:
+
+```text
+The "Save" button on the Settings dialog wasn't disabling while a save was in flight.
+I added a `saving` ref and bound it to :disabled. Verify it works:
+- after click, button must be disabled until network completes
+- no console errors
+- visual: button greys out (compare to /abs/path/saving-state.png if one is provided)
+```
+
+Claude will pick the right skill (usually `verify` ad-hoc mode), run a handful of `eval` / `dom --filter` / `console`
+calls, and only screenshot if the visual claim needs it.
+
+### Anti-patterns to avoid
+
+- "Just verify the feature" with no plan or symptom — the recipe author can't pick the cheapest signal without knowing
+  what "works" means. Give it the symptom that motivated the fix.
+- Pasting Figma URLs and expecting agent-view to download them — it won't. Export the frames you care about to PNG
+  first.
+- Running the recipe directly with Opus when a recipe file exists — that's exactly the case `verify-runner` is for.
+  Prefer Phase 2's prompt.
+- Stuffing 50 assertions into one recipe — split per-feature. A recipe should run in <2 minutes and produce a report you
+  can read in 30 seconds.
+
 ## How it works
 
 ```
@@ -161,28 +283,47 @@ A background server connects to your app's CDP port, caches sessions, and auto-s
 
 ## Config
 
-Running `agent-view init` in your project root generates `agent-view.config.json`:
+Running `agent-view init` in your project root generates `agent-view.config.json`. Minimal form:
 
 ```json
 {
   "runtime": "electron",
-  "port": 9222,
+  "port": 9876,
   "launch": "npm run dev"
 }
 ```
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `runtime` | yes | `"electron"`, `"tauri"`, or `"browser"` |
-| `port` | yes | CDP debugging port |
-| `launch` | no | Command to start the app |
-| `webgl.engine` | no | `"pixi"` (scene extractor architecture supports adding more engines) |
-| `allowEval` | no | `true` to enable `agent-view eval`. Off by default — opt-in for arbitrary JS execution |
-| `consoleBufferSize` | no | Per-target console ring capacity. Default `500` |
-| `consoleTargets` | no | Target types `agent-view console` auto-attaches to. Default `["page", "shared_worker", "service_worker"]` |
+Full form with all optional fields:
+
+```json
+{
+  "runtime": "electron",
+  "port": 9876,
+  "launch": "npm run dev",
+  "allowEval": true,
+  "webgl": {
+    "engine": "pixi"
+  },
+  "consoleBufferSize": 500,
+  "consoleTargets": ["page", "shared_worker", "service_worker"]
+}
+```
+
+| Field               | Required | Description                                                                                               |
+|---------------------|----------|-----------------------------------------------------------------------------------------------------------|
+| `runtime`           | yes      | `"electron"`, `"tauri"`, or `"browser"`                                                                   |
+| `port`              | yes      | CDP debugging port                                                                                        |
+| `launch`            | no       | Command to start the app                                                                                  |
+| `webgl.engine`      | no       | `"pixi"` (scene extractor architecture supports adding more engines)                                      |
+| `allowEval`         | no       | `true` to enable `agent-view eval` and `watch`. Off by default — opt-in for arbitrary JS execution        |
+| `consoleBufferSize` | no       | Per-target console ring capacity. Default `500`                                                           |
+| `consoleTargets`    | no       | Target types `agent-view console` auto-attaches to. Default `["page", "shared_worker", "service_worker"]` |
 
 ## Commands
 
+Every command targeting a window accepts `--window <id|title-substring>` (IDs come from `discover`). Examples below omit
+it for brevity.
+
 ### `init`
 
 Auto-generates config by reading `package.json`.
@@ -203,12 +344,22 @@ Dumps the accessibility tree in compact text format. Each element gets a session
 agent-view dom
 agent-view dom --filter "Submit"    # Filter by text/role
 agent-view dom --depth 3            # Limit tree depth
-agent-view dom --window "Settings"  # Target specific window
+agent-view dom --max-lines 200      # Hard line budget (refs for hidden nodes still stored)
 agent-view dom --text               # Fall back to DOM textContent search when AX returns no match
+agent-view dom --compact            # Merge single-child chains onto one line (saves ~40-60% tokens)
+agent-view dom --count              # Return only the count of matching nodes (e.g. "5")
+agent-view dom --filter "row" --count  # Count how many rows match
+agent-view dom --diff               # Show only lines that changed since last call
 ```
 
 When `--filter` is set, depth defaults to unlimited so deep matches aren't truncated.
 
+`--count` skips tree formatting and ref-store mutations entirely — useful for assertions like "does this section have N rows?" without the token cost of a full tree dump.
+
+`--max-lines <n>` caps the number of output lines. When the tree exceeds the budget, output is truncated after `n-1` lines and a summary tail `… M more nodes` is appended. Refs for all nodes — including those past the cutoff — are still registered in the ref store, so a follow-up `dom --filter` or `click <ref>` works without re-running.
+
+`--diff` computes a line-level diff against the previous `dom` call for the same target. The first call always returns the full tree (no prior snapshot). Subsequent calls emit only added (`+ `) and removed (`- `) lines. Returns `No changes` when the tree is identical.
+
 ### `click`
 
 Clicks a DOM element by ref ID or coordinates.
@@ -226,18 +377,40 @@ Types text into an input. Uses native value setter + dispatches input/change eve
 agent-view fill 3 "hello@example.com"
 ```
 
+### `drag`
+
+HTML5 / pointer-driven drag-and-drop via CDP `Input.dispatchMouseEvent`
+(`mousePressed` → N × `mouseMoved` → `mouseReleased`). Real mouse events, not
+synthesized JS events — works with `vue-draggable-resizable`, `react-grid-layout`,
+gridstack, kanban boards, file drop zones, map pin drags, resize handles.
+
+```bash
+agent-view drag --from 42 --to 88                   # ref → ref
+agent-view drag --from-pos 86,792 --to-pos 640,200  # coord → coord (canvas, custom DnD)
+agent-view drag --from 42 --to-pos 640,200          # mixed
+agent-view drag --from 5 --to 9 --steps 20 --hold-ms 150
+```
+
+`--steps` (default 10) controls intermediate `mouseMoved` events so libraries
+that throttle on movement deltas still see continuous motion. `--hold-ms`
+inserts a pause between press and the first move (some libs require >100ms
+for touch-style activation). `--button` accepts `left|right|middle`.
+
 ### `screenshot`
 
-Captures a screenshot, saves to temp dir, prints the file path. PNG by default; JPEG when `--scale` is set.
+Captures a screenshot, saves to temp dir, prints the file path. PNG by default; WebP (q=80) when `--scale` is set (JPEG fallback for older Chrome/Electron).
 
 ```bash
 agent-view screenshot
-agent-view screenshot --window "Settings"
-agent-view screenshot --scale 0.5             # Half-res JPEG (~3× fewer vision tokens)
-agent-view screenshot --scale 0.25            # Quarter-res JPEG (~12× fewer, 1 tile)
+agent-view screenshot --scale 0.5             # Half-res WebP (~3× fewer vision tokens)
+agent-view screenshot --scale 0.25            # Quarter-res WebP (~12× fewer, 1 tile)
+agent-view screenshot --crop "Sidebar"        # Crop to element bounding box (~12× fewer in best case)
+agent-view screenshot --crop "Chart" --scale 0.5  # Crop + scale (stacks)
 ```
 
-`--scale` accepts a factor in `(0, 1]`. CDP-side clip + JPEG encode — recommended for agent loops where vision tokens dominate cost.
+`--scale` accepts a factor in `(0, 1]`. CDP-side clip + WebP encode — recommended for agent loops where vision tokens dominate cost.
+
+`--crop <filter>` resolves a DOM element by the same filter syntax as `dom --filter`, then crops the screenshot to its bounding box before encoding. One tile (~1.6k vision tokens) instead of twelve (~19k) in the best case. If the filter matches nothing a warning is emitted to stderr and the full window is captured instead. Combines naturally with `--scale`.
 
 ### `scene`
 
@@ -248,14 +421,16 @@ agent-view scene                    # Full scene graph
 agent-view scene --diff             # Changes since last call
 agent-view scene --filter "player"  # Filter by name/type
 agent-view scene --verbose          # Extended props (alpha, scale, bounds)
+agent-view scene --compact          # Merge single-child chains onto one line
 ```
 
 ### `snap`
 
-Combined DOM + scene graph in one call. Shows DOM always; scene section appears when a WebGL engine is detected.
+Combined DOM + scene graph in one call. Shows DOM always; scene section appears when a WebGL engine is detected. Pass `--scale` to also capture a screenshot and append it as a third section.
 
 ```bash
 agent-view snap
+agent-view snap --scale 0.5   # DOM + Scene + Screenshot (path written to tmp)
 ```
 
 ### `wait`
@@ -301,85 +476,59 @@ Streams or dumps console output (`Runtime.consoleAPICalled` + `Log.entryAdded`)
 ```bash
 agent-view console                              # buffered messages since attach
 agent-view console --follow --timeout 10        # stream for 10s
-agent-view console --target IJ56KL              # restrict to one target
+agent-view console --follow --until "ready"     # exit as soon as a message contains "ready"
+agent-view console --follow --until "/error/i"  # exit on regex match (case-insensitive)
+agent-view console --target IJ56KL              # restrict to one target (exact id)
+agent-view console --target sync-worker         # restrict to one target (title/URL substring)
 agent-view console --level error,warn           # level filter
 agent-view console --since "2026-04-26T10:00:00Z"
 agent-view console --clear                      # drop in-memory ring
 ```
 
-Default attached target types: `page`, `shared_worker`, `service_worker`. Override with `consoleTargets` in config.
+`--until <pattern>` requires `--follow`. Exits as soon as a message matches the pattern (substring or `/regex/flags`). On timeout without match exits non-zero with `Timeout: pattern not seen in <N>s`.
 
-### `stop`
+`--target` resolves the same way as `eval --target`: exact id wins, then title substring, then URL substring. If no match is found, an error is returned.
 
-Stops the background lazy server.
+Default attached target types: `page`, `shared_worker`, `service_worker`. Override with `consoleTargets` in config.
 
-## Multiwindow
+### `watch`
 
-All commands accept `--window` with either an ID (from `discover`) or a window title substring:
+Polls a JS expression and streams JSON-patch (RFC 6902) diffs as it changes. Closes the "what changed between click and final state?" gap that screenshots and DOM dumps can't cover. **Requires `"allowEval": true`** (same gate as `eval`).
 
 ```bash
-agent-view dom --window "Settings"
-agent-view screenshot --window "About"
+agent-view watch "store.cart.total"                          # 250ms poll, exits at 10 changes or 30s
+agent-view watch "appState" --interval 100 --duration 60     # tighter cadence, longer window
+agent-view watch "store.status" --until "store.status === 'ready'"  # wait-for assertion
+agent-view watch "appState" --max-changes 1                  # snapshot first change after a click
+agent-view watch "appState" --json                           # NDJSON, one frame per line
 ```
 
-## Output format
-
-| Command | Format | Why |
-|---------|--------|-----|
-| `dom`, `scene`, `snap` | Plain text | LLM-friendly, minimal tokens |
-| `discover` | JSON | Machine-parseable |
-| `screenshot` | File path | Agent reads the image |
-
-## Claude Code plugin
-
-agent-view ships as a Claude Code plugin with a built-in `verify` skill. The skill teaches Claude how to use agent-view for UI verification after code changes.
-
-### Local development
+Output frames: `init` (baseline value), `diff` (RFC 6902 ops since last frame), `error`, `stop`. SIGINT exits cleanly. Snapshot size cap 256 KB — narrow the expression (e.g. `store.cart.items.length`) when watching large objects.
 
-```bash
-claude --plugin-dir /path/to/agent-view
-```
-
-The skill becomes available as `/agent-view:verify`.
+### `stop`
 
-### After npm install
+Stops the background lazy server.
 
-```bash
-# Find where the package is installed
-npm root -g
-# Use that path with --plugin-dir
-claude --plugin-dir "$(npm root -g)/agent-view"
-```
+## Performance
 
-## Example: testing a login flow
+Built for tight `dom → click → dom` loops. Typical Electron app, ~200 AX nodes:
 
-```bash
-# Start the app
-agent-view launch
-
-# See the login page
-agent-view dom --filter "login"
-# RootWebArea "My App"
-#   textbox "Email" [ref=3]
-#   textbox "Password" [ref=5]
-#   button "Sign in" [ref=7]
-
-# Fill credentials and submit
-agent-view fill 3 "admin@example.com"
-agent-view fill 5 "password123"
-agent-view click 7
+| Scenario                       | agent-view | Playwright (estimate) |
+|--------------------------------|------------|-----------------------|
+| `dom` cold fetch               | 2ms        | ~30–80ms              |
+| `dom` warm (cache hit)         | 1ms        | ~30–80ms              |
+| Full cycle `dom → click → dom` | 17ms       | ~75ms                 |
 
-# Verify — did we land on the dashboard?
-agent-view dom --depth 2
-agent-view screenshot
-```
+What makes it fast: 300ms AX-tree cache (invalidated on `click`/`fill`/navigation; cached responses prefixed with
+`[cache]`), parallel CDP calls in `click`, `Accessibility.queryAXTree` for filter lookups, and a single persistent CDP
+WebSocket reused across commands (no relay).
 
 ## Troubleshooting
 
 ### CDP not responding
 
-1. Check the port is listening: `curl -s http://localhost:9222/json/version`
-2. For electron-vite: make sure you use `--` before the flag: `npx electron-vite dev -- --remote-debugging-port=9222`
+1. Check the port is listening: `curl -s http://localhost:9876/json/version`
+2. For electron-vite: make sure you use `--` before the flag: `npx electron-vite dev -- --remote-debugging-port=9876`
 3. Restart the app — HMR doesn't restart the main process
 
 ### Stale refs after HMR