@petukhovart/agent-view 0.3.0 → 0.6.0

package/skills/verify/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: verify
-description: "Visual + runtime verification of desktop apps via Chrome DevTools Protocol. Use when modifying UI components, fixing visual bugs, testing user interactions, verifying layout, or when any workflow phase needs to inspect the running application — DOM, screenshots, scene graph, runtime state in pages and SharedWorkers/ServiceWorkers, or console errors. Triggers on: verify, check UI, test how it looks, visual regression, screenshot, inspect DOM, check store/state, read worker, console errors, runtime check, eval in page."
-allowed-tools: Bash(agent-view *), Bash(rtk agent-view *)
+description: "Visual + runtime verification of desktop apps via Chrome DevTools Protocol. Use when modifying UI components, fixing visual bugs, testing user interactions, verifying layout, or when any workflow phase needs to inspect the running application — DOM, screenshots, scene graph, runtime state in pages and SharedWorkers/ServiceWorkers, console errors, or reactive-state diffs over time. Triggers on: verify, check UI, test how it looks, visual regression, screenshot, inspect DOM, check store/state, watch state changes, what changed after click, wait until state, read worker, console errors, runtime check, eval in page."
+allowed-tools: Bash(agent-view *)
 ---
 
 # Visual Verification with agent-view
@@ -12,7 +12,7 @@ You have access to `agent-view` CLI for inspecting and interacting with desktop
 
 The target project must have:
 1. `agent-view.config.json` in project root (run `agent-view init` to generate)
-2. CDP enabled in the app (e.g. `--remote-debugging-port=9222` for Electron)
+2. CDP enabled in the app (e.g. `--remote-debugging-port=9876` for Electron — avoid `9222`, it's Chrome's own default and collides when Chrome is open)
 
 If config is missing, run `agent-view init` first.
 
@@ -27,26 +27,46 @@ agent-view stop                        # Stop the lazy server
 
 ### DOM Inspection
 ```bash
-rtk agent-view dom                          # DOM accessibility tree (default window)
-rtk agent-view dom --window <id|name>       # Specific window
-rtk agent-view dom --filter "button"        # Filter by text/role
-rtk agent-view dom --depth 3                # Limit tree depth
+agent-view dom                          # DOM accessibility tree (default window)
+agent-view dom --window <id|name>       # Specific window
+agent-view dom --filter "button"        # Filter by text/role
+agent-view dom --depth 3                # Limit tree depth
+agent-view dom --compact                # Merge single-child chains onto one line (~40-60% fewer tokens)
+agent-view dom --count                      # Count of all visible nodes (single integer line)
+agent-view dom --filter "row" --count       # Count matching nodes — e.g. "does this table have 5 rows?"
+agent-view dom --max-lines 200          # Hard line budget; refs for truncated nodes still stored
+agent-view dom --diff                   # Lines changed since last dom call (+ added / - removed)
 ```
 
+`--count` skips tree output and ref mutations — cheapest way to assert "element exists N times" without loading the full tree into context.
+
 ### Interaction
 ```bash
 agent-view click <ref>                  # Click element by ref from dom output
 agent-view click --pos 100,200          # Click by coordinates (for canvas)
 agent-view fill <ref> "text"            # Type into input field
+agent-view drag --from <ref> --to <ref>          # Drag element to another element by ref
+agent-view drag --from-pos 50,80 --to-pos 200,300  # Drag by coordinates (for canvas / Pixi)
+agent-view drag --from <ref> --to <ref> --steps 25 --hold-ms 60  # Smoother movement, longer hold
 ```
 
+`drag` dispatches `mousePressed` → N × `mouseMoved` → `mouseReleased` via CDP. Endpoints can mix
+ref and coordinate (e.g. `--from <ref> --to-pos 400,300`). For canvas/Pixi targets always use
+`--from-pos`/`--to-pos` — derive the centroid via `agent-view eval` from the scene graph.
+Refs are resolved fresh on each call, so window resizes between snapshots are tolerated.
+Increase `--steps` for handlers using `globalpointermove` so intermediate frames are not skipped.
+
 ### Screenshots
 ```bash
 agent-view screenshot --scale 0.5              # Recommended: JPEG at half-res (~3× fewer vision tokens)
 agent-view screenshot --scale 0.5 --window <id>  # Specific window
+agent-view screenshot --crop "Sidebar"         # Crop to element bounding box (~1.6k tokens — 12× win)
+agent-view screenshot --crop "Chart" --scale 0.5  # Crop + scale (stacks)
 agent-view screenshot                          # Full-res PNG (expensive: ~19k tokens at 1920×1080)
 ```
 
+`--crop <filter>` resolves the element with the same filter syntax as `dom --filter`, then crops the screenshot to its bounding box. Prefer `--crop` over full-window screenshots whenever you only need to inspect a specific section. Falls back to full-window with a stderr warning if the filter matches nothing.
+
 ### Runtime State (`eval`)
 
 Reads runtime values DOM/screenshot can't reveal — store contents, computed flags, worker internals.
@@ -65,6 +85,24 @@ When to reach for `eval` instead of `dom`:
 - The target is a worker (`shared_worker`, `service_worker`, `worker`) — DOM doesn't exist there.
 - You need a precise number/string answer, not a tree to scan.
 
+### Reactive State (`watch`)
+
+Streams JSON-patch diffs of an expression over time. Use when you need to see *what changed* between an action and a final state — `eval` shows the snapshot, `watch` shows the trajectory. **Requires `"allowEval": true`.**
+
+```bash
+agent-view watch "store.cart.total"                                # 250ms poll, default 10 changes or 30s
+agent-view watch "appState" --until "appState.status === 'ready'"  # wait-for-condition with diff log
+agent-view watch "store.user" --max-changes 1                      # capture exactly one change after a click
+agent-view watch "appState" --json                                 # NDJSON, machine-readable
+```
+
+When to reach for `watch` instead of `eval`:
+- Debugging "the click did X but state shows Y — what happened in between?"
+- Time-based assertions ("wait until store.status === 'ready'") — `--until` exits cleanly when truthy.
+- Confirming an action triggered the *expected* sequence of mutations, not just the final state.
+
+Output: `init` line (baseline), one line per RFC 6902 op (`replace /path old → new`, `add /items/0 ...`), final `stop` line with reason. Snapshot size cap 256 KB — narrow the expression (`store.x.y`, not `store`) for large objects.
+
 ### Console (`console`)
 
 Streams `Runtime.consoleAPICalled` + `Log.entryAdded`. Use to confirm a flow finished without errors, or to surface a specific warning after an interaction.
@@ -72,12 +110,17 @@ Streams `Runtime.consoleAPICalled` + `Log.entryAdded`. Use to confirm a flow fin
 ```bash
 agent-view console                              # buffered messages from auto-attached targets
 agent-view console --level error,warn           # filter
-agent-view console --target sync-worker         # one target
+agent-view console --target sync-worker         # one target (title/URL substring, same fuzzy semantics as eval --target)
+agent-view console --target IJ56KL              # one target (exact id)
 agent-view console --follow --timeout 10        # stream window (use sparingly — 10s of waiting)
+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 --clear                      # baseline before an interaction
 agent-view console --since "2026-04-26T10:00:00Z"
 ```
 
+`--until` requires `--follow`. Exits immediately when a message matches (substring or `/regex/flags`). On timeout without match exits non-zero.
+
 Standard pattern for "did this action error?":
 ```bash
 agent-view console --clear
@@ -109,7 +152,9 @@ agent-view scene                        # Scene graph from configured engine
 agent-view scene --filter "player"      # Filter by object name/type
 agent-view scene --verbose              # Extended props (scale, alpha, rotation)
 agent-view scene --diff                 # Changes since last call
+agent-view scene --compact              # Merge single-child chains onto one line (reduces output)
 agent-view snap                         # DOM + Scene combined
+agent-view snap --scale 0.5             # DOM + Scene + Screenshot (path appended as === Screenshot === section)
 ```
 
 ## Picking the right tool
@@ -119,24 +164,48 @@ Verifications cost very different amounts. Pick the cheapest tool that can actua
 | The question is about… | Use | Why |
 |---|---|---|
 | Element existence / text / role | `dom --filter` | Cheapest, structured, no vision tokens |
+| Count of matching elements | `dom --filter X --count` | Single integer, no tree output, no ref mutations |
 | App state, store contents, computed values | `eval "expr"` | DOM doesn't expose JS state; reading the tree to infer it is wasteful and unreliable |
+| State *trajectory* — what changed during/after an action | `watch "expr" --until …` or `--max-changes 1` | `eval` shows the final snapshot only; `watch` shows the diffs in order |
 | Worker logic (SharedWorker / ServiceWorker) | `eval --target <name>` | Workers have no DOM at all |
 | Did the last action throw or warn? | `console --clear` before, `console --level error,warn` after | Catches errors that don't surface in the DOM |
-| Layout, spacing, visual regression | `screenshot --scale 0.5` | The only tool that sees pixels — but expensive (~6k tokens), use last |
+| Layout/visual of a specific element | `screenshot --crop "<element>"` | ~1.6k tokens (1 tile) — crops to bounding box, massive token win |
+| Layout, spacing, full-window visual regression | `screenshot --scale 0.5` | The only tool that sees pixels — but expensive (~6k tokens), use last |
 | Canvas/WebGL scene contents | `scene --diff` | DOM is empty for canvas apps |
+| What DOM nodes changed after an interaction | `dom --diff` | Returns only `+`/`-` lines; much cheaper than re-reading the full tree |
 
 When two tools could answer the same question, prefer the one higher up the table. A common mistake is screenshotting to check "is the count = 5?" when `eval "store.counter"` returns the number directly for ~50 tokens.
 
 ## Verification Workflow
 
+### Recipe Execution Mode (preferred when a recipe exists)
+
+If the developer points you at a `.claude/verify-recipes/<slug>.md` file, OR you discover one matching the current task via `ls .claude/verify-recipes/`, **delegate execution to the `verify-runner` subagent** instead of running commands yourself.
+
+Why: recipe execution is mechanical (run commands, compare to `Expected:`, report). It does not need Opus-level reasoning, but the raw output (DOM dumps, screenshots, eval results) easily exceeds 30k tokens of context noise. Delegating to a Haiku subagent keeps your context clean and cuts cost ~10×.
+
+How to delegate:
+
+1. Resolve the window id once: `agent-view discover` → pick the main window's id.
+2. Spawn `verify-runner` via the Agent tool with a prompt containing:
+   - Absolute `recipe_path`
+   - Resolved `window_id`
+   - Any extra context (e.g. "user is already logged in", "GIS widget already mounted")
+3. Wait for the JSON report. Read `summary`, `blocking_issues`, and any `failed` step diagnoses.
+4. **If `design_conformance_section: true`** in the report: also spawn `design-conformance-runner` in parallel, passing the `design_conformance_pairs` array. Merge both reports before answering the user.
+5. For `requires_visual_review` steps that have no design ref attached: open the screenshot yourself with `Read` and decide pass/fail.
+6. For `failed` steps: re-run the specific failing command yourself if you need richer evidence to diagnose. Do not re-execute the whole recipe.
+
+Output to the user: a tight summary — what passed, what failed, what needs visual review, and (if any) which design conformance issues to fix. Do not paste the raw JSON unless asked.
+
 ### Ad-hoc Mode (standalone)
 
 After making code changes:
 
 1. **Determine affected areas** from git diff
 2. **Ensure app is running**: `agent-view launch` or `agent-view discover`
-3. **Inspect DOM**: `rtk agent-view dom --filter "<area>" --depth 2` — check structure matches expectations
-4. **Interact if needed**: `agent-view click`/`fill` → `rtk agent-view dom --filter` to verify state changed
+3. **Inspect DOM**: `agent-view dom --filter "<area>" --depth 2` — check structure matches expectations
+4. **Interact if needed**: `agent-view click`/`fill` → `agent-view dom --filter` to verify state changed
 5. **For canvas apps**: `agent-view scene --diff` to see what changed
 6. **For non-DOM truth** (store, computed values, worker state): `agent-view eval` — much cheaper than reading the DOM tree to infer state
 7. **After any interaction that could fail silently**: `agent-view console --level error` — catches uncaught exceptions, network failures, framework warnings
@@ -176,9 +245,11 @@ Vision tokens dominate cost. One full-res screenshot ≈ 19k tokens (1920×1080,
 | Technique | Savings |
 |---|---|
 | `agent-view eval "expr"` for state checks | Returns one value (~50 tokens) instead of a DOM/screenshot |
-| `rtk agent-view dom --filter X --depth 2` | Compresses text output via RTK |
+| `agent-view dom --filter "row" --count` | Single integer answer — zero tree tokens |
+| `agent-view dom --filter X --depth 2` | Narrow tree to relevant subtree, cap depth |
 | `agent-view screenshot --scale 0.5` | ~3× fewer vision tokens (4 tiles) |
 | `agent-view screenshot --scale 0.25` | ~12× fewer vision tokens (1 tile, ~1.6k tokens) |
+| `agent-view screenshot --crop "<element>"` | ~12× fewer in best case (1 tile) — crops to element bounding box |
 | DOM/eval-first: screenshot only for final visual confirm | Eliminates most screenshot calls |
 
-**Default rule**: if the answer is a value → `eval`; if the answer is "is element X visible/correct?" → `rtk agent-view dom --filter`; only call `screenshot --scale 0.5` for final visual proof or layout bugs that pixels alone can show.
+**Default rule**: if the answer is a value → `eval`; if the answer is "is element X visible/correct?" → `agent-view dom --filter`; if you need pixels for a specific section → `screenshot --crop "<element>"` (one tile); only call `screenshot --scale 0.5` for full-window visual proof.

package/skills/verify-recipe/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: verify-recipe
+description: "Generates a concrete, command-by-command agent-view recipe for verifying a feature or bugfix. Use when the developer wants to write a verify-recipe.md, create a verification plan, build an agent-view recipe, or produce a verify checklist for a change they shipped. Triggers on: write a verify-recipe, write verification steps, generate verify steps for the feature/bug I just shipped/fixed, make a verify-recipe.md, what should I run to verify X, create a verification plan, agent-view recipe for this fix, verify checklist for this feature. Does NOT execute the checks — it authors the plan. For running checks against a live app, use the verify skill instead."
+allowed-tools: Read, Write, Bash(agent-view *)
+---
+
+# Verification Recipe Generator
+
+You help the developer author a disciplined, cheapest-first verification recipe for a feature they shipped or a bug they fixed. You do not run the checks — you produce a `.claude/verify-recipes/<slug>.md` file that any AI coding agent can execute later.
+
+## What this produces
+
+A file at `.claude/verify-recipes/<kebab-slug>.md` containing:
+
+- **REPRO STEPS** — exact state the app must be in before checks run
+- **NARROWED SIGNAL** — the measurable indicator that proves success or failure
+- **EVIDENCE COMMANDS** — ordered `agent-view` calls, cheapest first, each annotated with what it proves
+- **POSITIVE-CASE ASSERTIONS** — what "pass" looks like for each command
+- **REGRESSION CHECKS** — adjacent paths that must not have broken
+
+Create the directory if missing: `mkdir -p .claude/verify-recipes`
+
+## Methodology
+
+Frame the recipe with **hard-debug** discipline. That skill defines the chain: REPRO → narrowed signal → minimize scope → root-cause check → fix verification. Apply the same logic here in authoring mode:
+
+1. Start from a reproducible starting state, not "open the app and poke around"
+2. Convert vague expectations ("looks right") into measurable signals ("store.user.role === 'admin'")
+3. Prefer the cheapest tool that can answer the question — a value check costs ~50 tokens, a screenshot costs ~6 000
+4. Include at least one negative-case check (the old symptom must no longer appear)
+5. Include at least one regression check (an adjacent flow must still work)
+
+## Tool-cost decision tree
+
+Pick the first row that can answer the question. Only go lower when the row above can't:
+
+| Question | Command | Why it's cheapest |
+|---|---|---|
+| Element exists / has specific text / role | `agent-view dom --filter "<text>" --depth 2` | Structured text, zero vision tokens |
+| App state, store value, computed flag | `agent-view eval "<expr>"` | Returns the value directly; DOM inference is wasteful and fragile |
+| What changed between action and final state | `agent-view watch "<expr>" --until "<condition>"` or `--max-changes 1` | `eval` shows the snapshot; `watch` shows the trajectory |
+| SharedWorker / ServiceWorker internal state | `agent-view eval --target <name> "<expr>"` | Workers have no DOM; this is the only path |
+| Did this action throw or warn silently? | `agent-view console --clear` before, `agent-view console --level error,warn` after | Catches uncaught exceptions and network failures invisible to DOM |
+| Layout, spacing, visual regression | `agent-view screenshot --scale 0.5` | Last resort — the only tool that sees pixels, but costs ~6 000 tokens |
+| Canvas / WebGL scene state | `agent-view scene --diff` | DOM is empty for canvas apps |
+
+**Anti-patterns to reject:**
+- Opening with a screenshot to "see the state" — use `dom --filter` or `eval` first
+- Using `eval` when `dom --filter` answers the question
+- Assertions that depend on transient state without `watch --until` to stabilize first
+- "Check that it looks right" — every assertion must be a concrete pass/fail criterion. The single legitimate exception is the `## Design Conformance` section, which delegates visual judgment to the design-conformance-runner subagent against an explicit reference image.
+- Inventing design reference paths (`.figma-refs/...`, `assets/mockups/...`) when the developer did not provide them. No refs → no Design Conformance section.
+
+## Workflow
+
+### Step 1 — gather context
+
+When invoked, ask the developer in plain text (no tool calls yet):
+
+1. What was shipped or fixed? (feature name or bug description)
+2. What was the original symptom or expected behavior?
+3. Any known failure mode or edge case to cover?
+4. (Optional) Are there design reference images to verify against? If yes — local path, glob, or list of files. **Only local files are supported.**
+
+Wait for the response before continuing.
+
+If the user provides design refs in step 4, store them for Step 2's optional `Design Conformance` section. If not provided, skip that section entirely — never invent a path or assume a convention.
+
+### Step 2 — draft the recipe
+
+Use the answers to produce a recipe with these sections:
+
+```markdown
+# Verify: <feature or fix name>
+
+Generated: <date>
+Scope: <one sentence describing what this covers>
+
+## Repro Steps
+1. <Exact starting state — window open, user logged in, specific route, etc.>
+2. <Action(s) that trigger the behavior under test>
+
+## Narrowed Signal
+<!-- The one measurable thing that proves it works -->
+`<agent-view command>` must return `<expected value>`.
+
+## Evidence Commands
+
+### 1. <What this proves>
+```bash
+agent-view <command>
+```
+Expected: <concrete criterion — value, text, absence of error>
+Cost: ~<N> tokens
+
+### 2. ...
+
+## Positive-Case Assertions
+- [ ] <criterion>
+- [ ] <criterion>
+
+## Regression Checks
+- [ ] <adjacent flow> — `agent-view <command>` → `<expected>`
+
+## Design Conformance
+<!-- INCLUDE THIS SECTION ONLY IF the developer provided design refs in Step 1 question 4. -->
+<!-- Each pair: a screenshot command + an absolute path to the expected reference image. -->
+<!-- The design-conformance-runner subagent reads this section, runs the screenshot commands, and visually compares against the expected refs. -->
+<!-- Do NOT invent design ref paths. Do NOT assume a convention (e.g. .figma-refs/). Use exactly what the developer provided. -->
+
+| Step Label | Screenshot Command | Expected Reference |
+|---|---|---|
+| <area name e.g. "filter panel"> | `agent-view screenshot --crop "<area>" --scale 0.5` | `<absolute path to expected PNG/JPEG>` |
+| <area name> | `agent-view screenshot --window $W --scale 0.5` | `<absolute path>` |
+
+Tolerance: `normal` (default — flag deviations a designer would notice in code review). Use `loose` only if the developer says exact pixel parity is not required.
+
+## Anti-patterns avoided
+- <note any recipe-specific traps, e.g. "state resets on reload — watch needed before dom check">
+```
+
+### Step 3 — save the file
+
+Determine a kebab-slug from the feature/fix name (e.g. `login-redirect-fix`, `cart-total-display`).
+
+Save to `.claude/verify-recipes/<slug>.md`. Create the directory first if it doesn't exist.
+
+Confirm the path to the developer.
+
+## Worked example: "fixed login redirect bug"
+
+**Developer input:**
+> Fixed a bug where after login, the redirect went to `/home` instead of `/dashboard`. Store mutation `SET_REDIRECT_PATH` was missing. No visual change — purely a routing issue.
+
+**Recipe produced:**
+
+```markdown
+# Verify: Login Redirect Fix
+
+Generated: 2026-04-27
+Scope: Confirms that a successful login routes to /dashboard, not /home, and that the store mutation fires correctly.
+
+## Repro Steps
+1. App running, user logged out, at `/login`
+2. Fill email + password, click "Sign in"
+
+## Narrowed Signal
+`agent-view eval "router.currentRoute.path"` must return `"/dashboard"`.
+
+## Evidence Commands
+
+### 0. Setup — baseline console (before any action)
+```bash
+agent-view console --clear
+```
+
+### 1. Confirm redirect target
+```bash
+agent-view fill <email-ref> "admin@example.com"
+agent-view fill <password-ref> "password"
+agent-view click <signin-ref>
+agent-view watch "router.currentRoute.path" --until "router.currentRoute.path === '/dashboard'"
+```
+Expected: `replace /  "/login" → "/dashboard"` in watch output
+Cost: ~100 tokens
+
+### 2. Confirm mutation fired
+```bash
+agent-view eval "store.state.auth.redirectPath"
+```
+Expected: `"/dashboard"` (not `"/home"`, not `null`)
+Cost: ~50 tokens
+
+### 3. No errors during login flow
+```bash
+agent-view console --level error,warn
+```
+Expected: `(no console messages)`
+Cost: ~30 tokens
+
+### 4. Regression — logout returns to /login
+```bash
+agent-view click <logout-ref>
+agent-view eval "router.currentRoute.path"
+```
+Expected: `"/login"`
+Cost: ~60 tokens
+
+## Positive-Case Assertions
+- [ ] `router.currentRoute.path` === `/dashboard` after login
+- [ ] `store.state.auth.redirectPath` === `/dashboard`
+- [ ] No console errors during the flow
+
+## Regression Checks
+- [ ] Logout → `/login` still works
+
+## Anti-patterns avoided
+- Not using screenshot to confirm route (route is a string — eval is 120× cheaper)
+- watch used before eval so route change is confirmed to have settled, not just sampled mid-transition
+```
+
+**Saved to:** `.claude/verify-recipes/login-redirect-fix.md`