@petukhovart/agent-view 0.1.0 → 0.5.0

package/skills/verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify
-description: "Visual verification of desktop app UI after code changes. Use when modifying UI components, fixing visual bugs, testing user interactions, verifying layout, or when any workflow phase needs to inspect the running application. Triggers on: verify, check UI, test how it looks, visual regression, screenshot, inspect DOM."
+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 *)
 ---
 
@@ -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.
 
@@ -31,22 +31,119 @@ 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                   # Save PNG to temp dir, print path
-agent-view screenshot --window <id>     # Specific window
+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.
+**Requires `"allowEval": true` in `agent-view.config.json`** — if the call returns "eval is disabled", tell the user to add the flag rather than working around it.
+
+```bash
+agent-view eval "store.state.user.role"                       # default page target
+agent-view eval --window "Settings" "router.currentRoute.path"
+agent-view eval --target sync-worker "self.queue.length"      # SharedWorker / ServiceWorker by id or substring
+agent-view eval --await "fetch('/api/health').then(r => r.status)"
+agent-view eval --json "({ buttons: document.querySelectorAll('button').length })"
+```
+
+When to reach for `eval` instead of `dom`:
+- The truth lives in JS state, not the DOM (Pinia/Vuex/Redux/Zustand store, Vue refs, computed values, app singletons).
+- 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.
+
+```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 (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
+agent-view click --filter "Save"
+agent-view wait --filter "Saved"
+agent-view console --level error                # expect "(no console messages)"
+```
+
+Default attached target types: `page`, `shared_worker`, `service_worker` (override via `consoleTargets` in config).
+
+### Targets (`targets`)
+
+When `--window` doesn't show what you expected, or you need a worker target id for `eval`/`console`:
+
+```bash
+agent-view targets                                       # everything connectable
+agent-view targets --type shared_worker,service_worker   # filter
+agent-view targets --json                                # machine-readable
 ```
 
-### Canvas / WebGL (only when `webgl` is configured in agent-view.config.json)
+You usually don't need this — `eval --target <substring>` and `--window <name>` both do fuzzy matching. Reach for `targets` when the substring is ambiguous.
+
+### Scene / Canvas / WebGL (only when `webgl` is configured in agent-view.config.json)
 
 These commands read the scene graph from canvas-based rendering engines. Skip this section if the project has no `webgl` field in config.
 
@@ -55,9 +152,30 @@ 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
+
+Verifications cost very different amounts. Pick the cheapest tool that can actually answer the question:
+
+| 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/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
 
 ### Ad-hoc Mode (standalone)
@@ -66,10 +184,12 @@ 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**: `agent-view dom --filter "<area>"` — check structure matches expectations
-4. **Take screenshot**: `agent-view screenshot` — capture visual state
-5. **Interact if needed**: `agent-view click`/`fill` → `agent-view dom` to verify state changed
-6. **For canvas apps**: `agent-view scene --diff` to see what 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
+8. **Screenshot only for final visual confirm**: `agent-view screenshot --scale 0.5` — captures layout/styling that DOM can't reveal
 
 ### Scenario Execution Mode (from plan)
 
@@ -78,7 +198,7 @@ When UI scenarios are pre-generated (e.g., from a plan file with `## UI Scenario
 1. **Read scenario steps** with symbolic refs (`$var` notation)
 2. **Resolve each $var**: `agent-view dom --filter "<text>" --depth 3` → map to ref ID
 3. **Execute steps** sequentially: fill, click, dom --filter (verify expected outcome)
-4. **Screenshot**: capture on FAIL and at E2E scenario end — not every step
+4. **Screenshot**: `agent-view screenshot --scale 0.5` — only on FAIL and at E2E scenario end, not every step
 5. **Report per-scenario**: PASS / FAIL with reason and evidence
 
 This mode works with any workflow that generates plan files with UI scenarios.
@@ -97,4 +217,19 @@ This mode works with any workflow that generates plan files with UI scenarios.
 - **Multiwindow**: all commands support `--window` flag
 - **Output format**: plain text (DOM, scene), JSON (discover only), file path (screenshot)
 - **Lazy server**: auto-starts on first call, shuts down after 5min idle
-- **Token optimization**: always use `dom --filter` with specific text, limit `--depth` to 2-3
+
+## Token Optimization
+
+Vision tokens dominate cost. One full-res screenshot ≈ 19k tokens (1920×1080, 12 tiles).
+
+| Technique | Savings |
+|---|---|
+| `agent-view eval "expr"` for state checks | Returns one value (~50 tokens) instead of a DOM/screenshot |
+| `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?" → `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,185 @@
+---
+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
+
+## 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?
+
+Wait for the response before continuing.
+
+### 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>`
+
+## 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`