@petukhovart/agent-view 0.11.0 → 0.13.0

package/dist/server/tauri-dialog-shim.js

@@ -0,0 +1,55 @@
+/** What the arm script reports back from the page. */
+export var TauriShimResult;
+(function (TauriShimResult) {
+    TauriShimResult["Armed"] = "armed";
+    /** The window is not a Tauri webview — nothing to patch, and nothing is wrong. */
+    TauriShimResult["NoTauri"] = "no-tauri";
+})(TauriShimResult || (TauriShimResult = {}));
+const STORE_KEY = '__agentViewTauriDialog__';
+/**
+ * Tauri opens its file dialog in Rust, past the webview, so CDP cannot see it
+ * and cannot close it. The one seam is the JS side of the call:
+ * `@tauri-apps/plugin-dialog` resolves `window.__TAURI_INTERNALS__.invoke` at
+ * call time, so replacing that function answers the dialog before the Rust side
+ * ever runs. The patch survives repeated arming but not a navigation — a fresh
+ * document has a fresh `window`, and the window must be armed again.
+ */
+export function buildTauriArmScript(arm) {
+    return `(() => {
+  const internals = window.__TAURI_INTERNALS__;
+  if (!internals || typeof internals.invoke !== 'function') return ${JSON.stringify(TauriShimResult.NoTauri)};
+  let store = window[${JSON.stringify(STORE_KEY)}];
+  // Disarming a window that was never armed must not install the patch: a
+  // command whose whole purpose is to remove interference cannot add some.
+  if (!store && ${JSON.stringify(arm === null)}) return ${JSON.stringify(TauriShimResult.NoTauri)};
+  if (!store) {
+    store = window[${JSON.stringify(STORE_KEY)}] = { arm: null, fired: [] };
+    const original = internals.invoke.bind(internals);
+    internals.invoke = function (cmd, args, opts) {
+      const arm = store.arm;
+      if (arm && (cmd === 'plugin:dialog|open' || cmd === 'plugin:dialog|save')) {
+        store.arm = null;
+        store.fired.push({ ts: Date.now(), cmd: cmd, cancel: arm.kind === 'cancel' });
+        if (store.fired.length > 20) store.fired.shift();
+        if (arm.kind === 'cancel') return Promise.resolve(null);
+        const multiple = cmd === 'plugin:dialog|open' && !!(args && args.options && args.options.multiple);
+        return Promise.resolve(multiple ? arm.files : (arm.files[0] === undefined ? null : arm.files[0]));
+      }
+      return original(cmd, args, opts);
+    };
+  }
+  store.arm = ${JSON.stringify(arm)};
+  return ${JSON.stringify(TauriShimResult.Armed)};
+})()`;
+}
+export function buildTauriStatusScript() {
+    return `(() => {
+  const store = window[${JSON.stringify(STORE_KEY)}];
+  return {
+    patched: !!store,
+    armed: !!(store && store.arm),
+    fired: store ? store.fired : [],
+  };
+})()`;
+}
+//# sourceMappingURL=tauri-dialog-shim.js.map

package/dist/server/tauri-dialog-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tauri-dialog-shim.js","sourceRoot":"","sources":["../../src/server/tauri-dialog-shim.ts"],"names":[],"mappings":"AAEA,sDAAsD;AACtD,MAAM,CAAN,IAAY,eAIX;AAJD,WAAY,eAAe;IACzB,kCAAe,CAAA;IACf,kFAAkF;IAClF,uCAAoB,CAAA;AACtB,CAAC,EAJW,eAAe,KAAf,eAAe,QAI1B;AAQD,MAAM,SAAS,GAAG,0BAA0B,CAAA;AAE5C;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAA0B;IAC5D,OAAO;;qEAE4D,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,OAAO,CAAC;uBACrF,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;;;kBAG9B,IAAI,CAAC,SAAS,CAAC,GAAG,KAAK,IAAI,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,OAAO,CAAC;;qBAE5E,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;gBAe9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;WACxB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC;KAC3C,CAAA;AACL,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO;yBACgB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;;;;;;KAM7C,CAAA;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petukhovart/agent-view",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "CLI tool for visual verification of desktop apps (Electron/Tauri) via Chrome DevTools Protocol",
   "type": "module",
   "main": "dist/index.js",

package/skills/verify/SKILL.md

@@ -47,7 +47,8 @@ agent-view dom --diff                   # Lines changed since last dom call (+ a
 ### 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 click --filter "Save"        # Find element by text and click
+agent-view click --pos 100,200          # Click by coordinates — CANVAS ONLY, see below
 agent-view click <ref> --double         # Double-click (fires dblclick handlers); works with --filter / --pos too
 agent-view fill <ref> "text"            # Type into input field
 agent-view drag --from <ref> --to <ref>          # Drag element to another element by ref
@@ -61,6 +62,100 @@ ref and coordinate (e.g. `--from <ref> --to-pos 400,300`). For canvas/Pixi targe
 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.
 
+**Coordinates are a last resort.** `--pos` / `--from-pos` / `--to-pos` exist for canvas and WebGL,
+where no ref exists. On DOM the correct order is `dom --filter "<text>"` → take the `[ref=N]` →
+`click <ref>`, or `click --filter "<text>"` in one step. A coordinate pair breaks on any layout
+shift, scroll, zoom, or window resize, and it clicks whatever now sits at that point — silently.
+If you reach for `--pos` on a DOM element, first say why the ref was not usable.
+
+### Modals & file pickers (`dialog`, `upload`)
+
+A modal that agent-view cannot answer stops a run dead: the window looks frozen, every
+later command times out, and nothing says why. Two kinds, handled differently.
+
+**JS modals — `alert` / `confirm` / `prompt` / `beforeunload` — are answered for you.**
+Nothing to set up. While agent-view is attached these never block the page: the default
+standing answer is *dismiss*, and each one is recorded. `agent-view dialog` is the
+reliable place to read that record; the console feed carries the same line
+(`[agent-view] confirm auto-dismissed: <message>`) but only from the moment console
+attaches, so a modal answered before your first `console` call reaches `dialog` alone.
+
+```bash
+agent-view dialog                      # standing answer + every modal this window has seen
+agent-view dialog policy accept        # confirm() → true from now on
+agent-view dialog policy accept --text "name"   # prompt() → "name"
+agent-view dialog policy dismiss       # back to the default
+agent-view dialog dismiss              # answer one that is open right now
+agent-view dialog accept --text "x"    # …ditto, accepting
+```
+
+`dialog accept` / `dialog dismiss` exist for a modal that was already open **before**
+agent-view attached — that one produced no event, so no policy applied to it.
+
+**Native file pickers never open — you answer them in advance.** Which mechanism applies
+depends on how the app opens the picker, and `dialog arm` sets up all of them at once,
+so you do not have to know:
+
+```bash
+# The input already exists in the DOM (even hidden) — no picker at all, cheapest path
+agent-view upload --selector "#file-input" --file ./fixtures/a.png
+agent-view upload --selector "#imgs" --file ./a.png --file ./b.png   # multi-select
+agent-view upload --ref 12 --file ./a.png                            # if the AX tree exposes it
+
+# The input is created inside the click handler, or the app calls a native dialog API
+agent-view dialog arm --file ./fixtures/a.png    # then click the button that opens it
+agent-view dialog arm --cancel                   # act as if the user pressed Cancel
+agent-view dialog disarm                         # let real pickers open again
+```
+
+Rules that actually bite:
+
+- **Arm before the click.** A picker cannot be caught once it is open. `arm` is one-shot —
+  it is spent by the first picker and interception turns itself off, so a later click
+  opens a real OS dialog.
+- **Click through `agent-view click`, never `eval "el.click()"`.** Chromium refuses to
+  open a file picker without user activation, and an eval-driven click carries none: the
+  picker is silently dropped and never intercepted.
+- **Hidden inputs have no ref.** `display:none` / `v-show="false"` keeps them out of the
+  AX tree, so `dom` never prints one. Use `--selector`. `upload` has no `--filter` on
+  purpose: an accessible name lands on the label, not on the input behind it.
+- **`beforeunload` is always dismissed**, whatever the policy — accepting it navigates
+  away and loses the state you are checking.
+- Paths are resolved against your cwd and must exist — CDP accepts a bad path silently and
+  the app then reads an empty file.
+- `agent-view dialog` after the fact shows what was intercepted and what was answered.
+
+Known limits: `showOpenFilePicker()` (File System Access API) exposes no input to fill, so
+it can only be cancelled. Electron does not implement `window.prompt` at all. Native
+dialogs opened straight from an Electron **main** process (`dialog.showOpenDialog` behind
+an IPC channel) are out of reach — CDP does not see the main process.
+
+### Waiting (`wait`)
+
+```bash
+agent-view wait --filter "Saved"                    # until the text appears in the AX tree
+agent-view wait --filter "Saved" --timeout 20       # max wait in seconds (default 10)
+agent-view wait --filter "Row 5" --window "Main"    # specific window
+```
+
+Exits as soon as the element appears; exits non-zero on timeout — so `&&` after it is a real gate.
+
+**Never sleep for a fixed time.** No `sleep`, no `timeout`, no `ping -n N 127.0.0.1` as a delay
+(agents reach for `ping` when the harness blocks `sleep` — it is the same mistake in worse
+clothing). A fixed pause is either too short, and you assert against a half-rendered UI, or too
+long, and you burn wall-clock on every step. agent-view has a condition-based wait for every kind
+of signal:
+
+| You are waiting for… | Use |
+|---|---|
+| An element to render | `wait --filter "<text>"` |
+| A store/state value | `watch "<expr>" --until "<expr>"` |
+| A log line | `console --follow --until "<pattern>"` |
+| A request to fire | `network --follow --until "<url>"` |
+
+If none of these fits, poll: `dom --filter X --count` in a loop with an explicit attempt cap, and
+report how many attempts it took.
+
 ### Screenshots
 ```bash
 agent-view screenshot --scale 0.5              # Recommended: JPEG at half-res (~3× fewer vision tokens)
@@ -239,6 +334,7 @@ Verifications cost very different amounts. Pick the cheapest tool that can actua
 | 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 |
 | Does `window.X` / a globally-exposed API exist? | `eval "typeof window.X"` | DOM doesn't show JS globals; only authoritative check |
+| An element that has not rendered yet | `wait --filter "<text>"` | Exits on appearance and non-zero on timeout — a real gate, unlike a fixed pause |
 | 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 |
@@ -247,6 +343,9 @@ Verifications cost very different amounts. Pick the cheapest tool that can actua
 | 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 |
+| Selecting a file for an input that exists in the DOM | `upload --selector` | No picker opens at all; works on hidden inputs, which have no ref |
+| Selecting a file when the input appears only mid-click | `dialog arm --file` then `click` | The only way — the input does not exist before the click and is gone after |
+| The window stopped responding after a click | `dialog` | Shows whether a modal was answered, and what the app was told |
 
 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.
 
@@ -256,9 +355,25 @@ When two tools could answer the same question, prefer the one higher up the tabl
 
 A run can produce one of three outcomes per step: **pass**, **fail**, **requires_visual_review**. There is no fourth bucket called "actually fine, here's why". A failed `Expected:` line is FAIL.
 
-These heuristics catch real bugs. Skipping them is how recipes silently pass while bugs sit in plain sight in the same data:
+**How to run the commands themselves:**
+
+- **Never discard output.** No `>/dev/null`, no `2>&1` to nowhere, no `| head -1` on a command whose
+  failure you have not yet read. Every agent-view command prints either the evidence or the reason
+  it failed; a suppressed `click` that matched nothing looks exactly like a successful one.
+- **Chain with `&&`, not newlines.** Newline-separated commands keep running after a failure, so a
+  broken first step is followed by three steps acting on the wrong state. `&&` stops at the first
+  non-zero exit.
+- **One action, then one check.** `click` is not evidence. The evidence is the `dom --diff`,
+  `dom --filter … --count`, `eval`, or `console --level error` you run after it. A block of three
+  clicks in a row with no check between them proves nothing about any of them.
+- **Call the `agent-view` binary.** Install it once in the target project
+  (`pnpm add -D @petukhovart/agent-view`) and call `agent-view …` or `pnpm exec agent-view …`.
+  Do not prefix every call with `npx <package>`: it re-resolves the package on each invocation and
+  falls outside this skill's `allowed-tools`, so each call needs a fresh permission prompt.
 
-1. **A failed `Expected:` is FAIL.** If output disagrees with the expected line, mark `fail` and continue. Do not edit the expected line. Do not invent prose explanations inline ("label reuse", "convention", "recipe arithmetic off"). Justifications belong in the bug report after the run, never in the per-step log.
+These heuristics catch real bugs. Skipping them is how a run silently passes while the bug sits in plain sight in the same data:
+
+1. **A failed expectation is FAIL.** If output disagrees with what the step expected, mark `fail` and continue. Do not soften the expectation. Do not invent prose explanations inline ("label reuse", "convention", "arithmetic off"). Justifications belong in the bug report after the run, never in the per-step log.
 
 2. **UI-vs-model mismatch is the bug, not noise.** When a count or hierarchy check returns `match: false`:
    - Default hypothesis: the UI renderer is wrong.
@@ -267,29 +382,14 @@ These heuristics catch real bugs. Skipping them is how recipes silently pass whi
 
 3. **Defensive eval reads.** Every `node.field` read (e.g. `transform.x`, `transform.width`) must be sentinel-checked before being used in arithmetic. A renamed field silently returns `NaN`/`null`, which fail-passes downstream comparisons. Add `isFinite(value)` / `value !== undefined` guards inline.
 
-4. **No hardcoded literal IDs.** If a recipe contains hardcoded node-ID prefixes that don't match the current scene, the entire recipe degrades to no-op without errors. Verify at least one expected ID exists; if not, derive IDs by role at runtime and proceed with the corrected lookup. Flag the recipe as needing an ID-refresh fix.
+4. **No hardcoded literal IDs.** A hardcoded node-ID prefix that no longer matches the current scene degrades the whole check to a silent no-op. Verify at least one expected ID exists; if not, derive IDs by role at runtime and proceed with the corrected lookup, and say the plan needs an ID refresh.
 
-5. **Reload checkpoint is not optional.** If the recipe has a `## Round-Trip Checkpoint` or `## Invariants` section mentioning reload/save/persistence — run it. If it does not, but the feature mutated persisted structure — run one anyway: `agent-view eval "location.reload()"`, wait for the app to come back, re-read the structural signature, diff. Drift is a real bug, not a "fixed-up on save".
+5. **Reload checkpoint is not optional.** If the feature mutated persisted structure, run one: `agent-view eval "location.reload()"`, wait for the app to come back, re-read the structural signature, diff. Drift is a real bug, not a "fixed-up on save".
 
-6. **Recipe-stated invariants run first or fail closed.** If the recipe has an `## Invariants` section, execute those steps before the action-specific evidence commands. A failed invariant is FAIL for that invariant *and* a flag on the rest of the run — keep running the remaining steps, tag them as "trust-impaired until invariant restored".
+6. **Invariants run first or fail closed.** When the plan states invariants, execute those steps before the action-specific checks. A failed invariant is FAIL for that invariant *and* a flag on the rest of the run — keep running the remaining steps, tag them as "trust-impaired until invariant restored".
 
 7. **Never claim a `window.*` API is missing without `eval`.** Before reporting "API not exposed" / "global X doesn't exist" / "the host doesn't expose Y", you MUST run `agent-view eval "typeof window.X"` and report the literal result (`"undefined"` / `"object"` / `"function"`). DOM scraping cannot answer this question — globals are not in the AX tree. If `eval` returns `"undefined"`, the API really is absent from the main world; if it returns anything else, the API is reachable and your earlier conclusion was wrong. No exceptions, no "I checked the source code instead".
 
-### Recipe Execution Mode (when a recipe file exists)
-
-If the developer points you at a `.claude/verify-recipes/<slug>.md` file, or one is discoverable via `ls .claude/verify-recipes/`, execute it inline yourself — **no subagent**.
-
-1. `Read` the recipe.
-2. If it has a `## Repro Steps` section, follow them — log in, navigate, set up data — using `agent-view` commands. Modern recipes (0.6+) may have `## Manual Preconditions` / `## Bringup` / `## Machine Preconditions` instead; treat those as documentation describing the expected state and execute the actions inline. There is no formal DSL — read what the section says and do it.
-3. Resolve the window id once with `agent-view discover` if you need `--window`.
-4. **If the recipe has an `## Invariants` section, run those steps first.** A failed invariant is FAIL — record it, then continue to evidence commands but tag subsequent results as "trust-impaired" until the invariant is restored.
-5. Run each `## Evidence Commands` subsection in order. Compare output to its `Expected:` line. Mark each as `pass` / `fail` / `requires_visual_review`. **Follow the Execution discipline above** — particularly rules 1 and 2.
-6. After 2–3 consecutive failures, stop and flag the recipe as likely stale. Distinguish "recipe stale" (hardcoded IDs no longer match) from "feature broken" (invariants violated on a current scene).
-7. Run `## Regression Checks`.
-8. **Run the round-trip checkpoint** (discipline rule 5) — either the recipe's section or, if absent and the feature is persistent, an ad-hoc reload check.
-9. If a `## Design Conformance` section is present, run the inline workflow below.
-10. Report a tight summary: passed / failed / visual-review counts plus one-liner per failure, and **any invariant violations called out separately**. Don't paste raw stdout unless asked.
-
 ### Ad-hoc Mode (standalone)
 
 After making code changes:
@@ -315,9 +415,15 @@ When UI scenarios are pre-generated (e.g., from a plan file with `## UI Scenario
 
 This mode works with any workflow that generates plan files with UI scenarios.
 
+### Reporting
+
+Run the whole thing inline — **no subagent**. Resolve the window id once with `agent-view discover` if you need `--window`.
+
+Report a tight summary: passed / failed / visual-review counts, one line per failure, invariant violations called out separately. Don't paste raw stdout unless asked. After 2–3 consecutive failures, stop and distinguish "the plan is stale" (hardcoded IDs no longer match the current UI) from "the feature is broken" (invariants violated on a current scene) — they need opposite fixes.
+
 ### Design Conformance (inline)
 
-When a recipe contains a `## Design Conformance` table — `(label, screenshot command, expected reference path)` rows — execute it yourself, no subagent.
+When you are given `(label, screenshot command, expected reference path)` rows — from a plan, or from the developer directly — execute them yourself, no subagent.
 
 For each row:
 1. Run the screenshot command (capture the saved file path from stdout).
@@ -330,7 +436,7 @@ Tolerance default: a designer's code-review level — flag what they'd notice, i
 ## Resilience
 
 - **Stale refs:** After HMR, navigation, or state change — re-run `dom` for fresh refs before interacting
-- **Element not found:** Wait 2s, retry once (render delay after HMR). If still missing — report FAIL
+- **Element not found:** `agent-view wait --filter "<text>" --timeout 5` (covers the render delay after HMR). If it times out — report FAIL. Do not insert a blind pause and retry.
 - **CDP disconnect:** Run `agent-view discover` to check. If no windows — `agent-view launch` (auto-starts Electron/Browser/Tauri). On `PORT_CONFLICT` — surface PID/process and ask user.
 - **`CDP_TIMEOUT` error:** the command hit the server-side deadline; cached CDP sessions for that port were dropped, so retry once. Repeated timeouts mean the app's DevTools endpoint is wedged — restart the app.
 - **Max retries per command:** 2. After that — SKIP scenario step with warning

package/skills/verify-recipe/SKILL.md

@@ -1,286 +0,0 @@
----
-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 (rigor edition)
-
-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.
-
-This edition is hardened against the failure mode of "construction-validated only" recipes that pass while real bugs sit in plain sight in the same data. See `## Bug-class invariants` and `## Discipline rules`.
-
-## 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.
-- **POSITIVE-CASE ASSERTIONS** — what "pass" looks like for each command.
-- **BUG-CLASS INVARIANTS** *(required)* — properties that must hold across all states the recipe touches, not just the action-result state.
-- **ROUND-TRIP CHECKPOINT** *(required when the feature touches persistence or mutable structure)* — a save-and-reload (or equivalent) comparison.
-- **REGRESSION CHECKS** — adjacent paths that must not have broken.
-- **DESIGN CONFORMANCE** *(optional)* — reference image comparisons.
-
-Create the directory if missing: `mkdir -p .claude/verify-recipes`
-
-## Methodology
-
-Frame the recipe with **hard-debug** discipline: REPRO → narrowed signal → minimize scope → root-cause check → fix verification.
-
-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).
-6. **Construction-only verification is not enough.** For any non-trivial feature, add invariant checks (see next section) and a round-trip checkpoint.
-
-## Bug-class invariants (required section in every recipe)
-
-The recipe must include an `## Invariants` section listing properties that hold *regardless of how state was reached*. These catch bugs that construction-only tests cannot see, because the bug lives in the gap between what the model says and what the user sees / what persistence preserves.
-
-Pick at least one invariant from each applicable class. Skip a class only if it provably cannot apply to the feature.
-
-### Class A — UI ≡ Model
-For every visible representation of state (tree, list, panel, breadcrumb, overlay, badge, count):
-- **Count parity:** `count(DOM rows of kind X) === count(model nodes of kind X)`.
-- **Hierarchy parity:** for any parent/child relationship the model expresses, the DOM must mirror it. A flat-rendered DOM of a nested model is a UI bug, not a model bug.
-- **Text parity:** the label shown in the UI for a node must equal `model.get(nodeId).name` (or whichever field the UI claims to display).
-
-Encode this as a single `eval` that returns a JSON struct so a single failed comparison is unambiguous:
-
-```bash
-agent-view eval "var model=<source-of-truth>;var dom=<measurement>;JSON.stringify({modelCount:model.size, domCount:dom.length, match:model.size===dom.length})"
-```
-
-If `match: false` — that is a FAIL. Do not rationalize a DOM/model count mismatch as "label reuse" or "the breadcrumb counts too" without confirming the matched elements' bounding boxes and DOM ancestry first.
-
-### Class B — Round-trip
-For any feature that creates / mutates persisted structure:
-- `state ≡ deserialize(serialize(state))` (model survives save→load with bit-identical structure for the projected fields).
-- `world(child) === origWorld(child)` immediately after a wrap/unwrap action (the wrapping must not silently shift the wrapped element).
-- Reloading the page (`agent-view eval "location.reload()"`) and re-reading the same state must produce an identical signature.
-
-A round-trip discrepancy that the save serializer silently "fixes" is a model bug, not a save-format bug. Live-vs-persisted divergence between actions and reloads is a class-B failure even if save/load round-trips cleanly with itself.
-
-### Class C — Reversibility & identity
-- Every user-facing command produces exactly one `commandHistory` entry (`canUndo→true`; one `undo()` fully reverses).
-- `undo` then `redo` produces an identical state to "do once".
-- The set of nodes after `do → undo → redo` equals the set after one `do`. Compare full IDs, not counts — a swap of one node for another with the same name is a real bug.
-
-### Class D — No phantom state
-- For each visible entity the user can interact with, there exists exactly one corresponding model node.
-- For each model node, there exists at most one corresponding UI entity in each view.
-- An entity that appears in two views (e.g. tree and canvas) must have the same identity in both (the same `nodeId` resolves both).
-
-This class is the one most often missed. Verify it explicitly when the feature changes structure.
-
-### Class E — Config conformance (rendering vs. configured constraint)
-
-Class A compares model to DOM. Class E compares the **rendered output** (DOM bounds, canvas geometry, computed styles, layout sizes) to an **explicit configuration value** the system declares it must respect. This is the home for invariants that have no DOM counterpart to diff against — they assert against a config the user (or product) chose.
-
-Typical examples — adapt names to the project:
-
-- **Snap/grid:** every shape's bounding box must satisfy `x % gridSize === 0` (and same for `y / width / height`). Read `gridSize` from the live config (`store.gridSettings.gridSize`, `theme.grid.size`, `viewport.snap`, …); do not hardcode.
-- **Viewport bounds:** elements declared "viewport-contained" must have `getBoundingClientRect()` within the viewport rect.
-- **Z-order / layering:** elements declared "above modals" must have computed `z-index` above the modal's. Compare against the configured layer table, not a literal number.
-- **Spacing / density tokens:** if the design system declares a spacing scale, computed `margin` / `padding` must be a multiple of the base token.
-- **Theme tokens:** computed colors / fonts must match the active theme's declared values, not literal hex codes.
-
-Generic helper shape:
-
-```bash
-agent-view eval "var cfg=<read live config value>; var items=<measure rendered items>; var off=items.filter(function(it){return !<conforms(it, cfg)>}); JSON.stringify({cfg:cfg, total:items.length, offCount:off.length, sample:off.slice(0,3)})"
-```
-
-Expected: `offCount: 0`. A non-zero count means the renderer ignored a config the system promised to honor — that is a real bug class, even if the model is internally consistent and round-trips cleanly. Bugs of the form "element is half a pixel off the grid", "modal renders behind the toast", "freshly-created group is not snapped" all live here and fall between the other classes.
-
-When generating recipes, ask: *what config values does this feature claim to respect?* Each one is one Class-E invariant. If the answer is "none" — say so explicitly in the recipe, so a future reader doesn't wonder why the class is absent.
-
-## Discipline rules
-
-These rules govern how the recipe is *executed* — they must appear verbatim in the recipe's `## Discipline` section so the executor cannot forget them.
-
-1. **A failed `Expected:` line is FAIL, not "actually fine".** Rationalizations belong in the bug report after the run, not inline in the run log. If the actual output disagrees with the expected line, mark `FAIL` and continue to the next step; do not edit the expected line, do not invent a "label reuse" or "convention" explanation that makes the discrepancy disappear from the count.
-
-2. **Prefer model-vs-DOM mismatches as the bug, not as noise.** When a Class-A invariant fails, the default hypothesis is "the UI renderer is wrong", not "the DOM filter matched something extra". To rule out the latter, query bounding boxes and ancestor chains for every match; if the matches turn out to be sibling rows in the same list, the renderer is the bug.
-
-3. **Defensive eval reads.** Every read of `node.transform.x` (or any model field) must include a sentinel: `isFinite(value)` or `value !== undefined`. A silent `NaN`/`null` from a renamed field looks like a real `0` in arithmetic and will fail-pass the assertion.
-
-4. **No hardcoded literal IDs.** All node IDs in evals must be resolved by role at runtime (e.g. "the first group at root", "the line at root not inside any group"). Hardcoded prefixes silently degrade the recipe to no-op when the scene differs.
-
-5. **The reload checkpoint is not optional.** For any recipe that touches mutable structure, include at least one `location.reload()` between an action and a re-measurement. Compare the projected signature before and after; differences are real bugs, not "fixed-up on save".
-
-6. **Compose, do not narrate.** Final report is `pass / fail / requires_visual_review` counts plus one-line failure reasons. Do not paste raw stdout. Do not include prose justifications in the per-step output.
-
-7. **`requires_visual_review` is an executor verdict, not an authoring shortcut.** When generating the recipe, draft every step so it executes through `agent-view`. Do not write `requires_visual_review` as the planned status of a step just because the path looks tricky (event delegation, canvas hit-test, file dialog, etc.) — first encode the cheapest sub-check that *can* run programmatically (e.g. "no console error during the action", "model state changed", "command history advanced by one"). The `requires_visual_review` label is set by the *executor* at run time, only after at least one genuine attempt to drive the action via agent-view failed for a reason they record. Authoring the recipe with `requires_visual_review` prebaked is what lets real regressions sit unobserved.
-
-## 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 |
-| Count of matching elements | `agent-view dom --filter X --count` | Single integer, zero tree 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 |
-| Did this action throw or warn silently? | `agent-view console --clear` before, `agent-view console --level error,warn` after | Catches uncaught exceptions invisible to DOM |
-| Layout, spacing, visual regression | `agent-view screenshot --scale 0.5` | Last resort — only tool that sees pixels (~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. Single legitimate exception: `## Design Conformance`.
-- Inventing design reference paths (`.figma-refs/...`) when the developer did not provide them.
-- **Treating SG (or any model layer) as the sole source of truth.** Model is one of several representations; the bug may live in the gap between model and UI. The recipe must check the gap explicitly.
-
-## Workflow
-
-### Step 1 — gather context
-
-Ask in plain text (no tool calls yet):
-
-1. What was shipped or fixed?
-2. What was the original symptom or expected behavior?
-3. Any known failure mode or edge case to cover?
-4. Does this feature touch persisted structure (YAML, IndexedDB, server)? If yes → mandatory round-trip section.
-5. Which views render this state (tree, panel, list, canvas, breadcrumb)? Each named view → one UI-≡-Model invariant in Class A.
-6. Which **configured constraints** does this feature claim to respect (grid/snap, viewport, z-order/layer table, spacing tokens, theme tokens, density)? Each named constraint → one Class-E invariant. If none — say so explicitly.
-7. *(Optional)* Local design reference images? Local files only.
-
-Wait for the response before continuing.
-
-### Step 2 — derive invariants before drafting commands
-
-Before writing any `agent-view` call, list the invariants the feature must satisfy. For each, write one sentence in the form:
-> "After any sequence of allowed actions, `<measurable property>` must hold."
-
-This list seeds the `## Invariants` section. If you cannot articulate three invariants for a non-trivial feature, the feature is under-specified — ask the developer for clarification.
-
-### Step 3 — draft the recipe
-
-```markdown
-# Verify: <feature or fix name>
-
-Generated: <date>
-Scope: <one sentence>
-
-## Repro Steps
-1. <Exact starting state>
-2. <Action(s) that trigger the behavior under test>
-
-## Narrowed Signal
-`<agent-view command>` must return `<expected value>`.
-
-## Invariants
-<!-- Required. List each invariant the feature must maintain. -->
-
-- **A1 (UI≡Model — <view name>):** `<eval expression that returns {model: N, dom: M, match: bool}>` must return `match: true`.
-- **A2 (Hierarchy):** For each model node with `parentId === X`, its UI row must be a DOM-descendant of the UI row of `X`.
-- **B1 (Round-trip):** After `location.reload()`, the projected signature `<projection>` is identical to the pre-reload signature.
-- **B2 (No silent wrap-shift):** After `<wrap-creating action>`, `getWorldTransform(child).x === origWorldX(child)` for every wrapped child.
-- **C1 (Single undo):** After `<action>`, `commandHistory.canUndo === true` and one `undo()` produces a signature identical to the pre-action signature.
-- **D1 (No phantoms):** For each visible UI row of kind `<X>`, there exists exactly one model node it resolves to via its `nodeId` data-attribute (or the equivalent identifier).
-- **E1 (Config conformance — <constraint name>):** Every rendered `<entity>` must satisfy `<conforms(rendered, configValue)>`, where `<configValue>` is read live from `<config source>` (do not hardcode). `offCount: 0` is required.
-
-## Discipline
-
-1. A failed `Expected:` line is FAIL, not "actually fine".
-2. UI-vs-model mismatches are the bug; confirm by ancestry/bbox before dismissing.
-3. Every `node.field` read in eval must be sentinel-checked (`isFinite` / `!== undefined`).
-4. No hardcoded literal IDs; resolve by role at runtime.
-5. Reload checkpoint is mandatory when the feature touches mutable structure.
-6. Report `pass / fail / requires_visual_review` per step; failure prose belongs in the bug report only.
-7. Do not pre-bake `requires_visual_review` as the planned status of a step. Every step ships with an executable `agent-view` path (at minimum a console-error gate around the action). The executor sets `requires_visual_review` only after a real attempt fails for a recorded reason.
-
-## Evidence Commands
-
-### 0. Setup — capture baseline signature
-```bash
-agent-view eval "<signature expression — projection of all structural fields>"
-```
-Stash the output as `BASELINE_SIG`.
-
-### 1. <What this proves>
-```bash
-agent-view <command>
-```
-Expected: <concrete criterion>
-Cost: ~<N> tokens
-
-### 2. ... (one per action / invariant pair)
-
-### N. Round-trip checkpoint (if applicable)
-```bash
-agent-view eval "location.reload()"
-# wait for app to come back
-agent-view eval "<same signature expression as step 0>"
-```
-Expected: identical to `BASELINE_SIG` after the action's expected effect is accounted for. Diff any drift.
-
-## Positive-Case Assertions
-- [ ] <criterion>
-
-## Regression Checks
-- [ ] <adjacent flow> — `agent-view <command>` → `<expected>`
-
-## Design Conformance
-<!-- Optional. Include ONLY if developer provided design refs. -->
-
-| Step Label | Screenshot Command | Expected Reference |
-|---|---|---|
-| <area name> | `agent-view screenshot --crop "<area>" --scale 0.5` | `<absolute path>` |
-
-Tolerance: `normal`.
-
-## Anti-patterns avoided
-- <recipe-specific traps>
-```
-
-### Step 4 — save the file
-
-Determine a kebab-slug. Save to `.claude/verify-recipes/<slug>.md`. Create the directory first.
-
-Confirm the path to the developer.
-
-## Worked example: "added group component to scene editor"
-
-**Developer input:**
-> Added a group component that wraps multiple scene elements. Ctrl+G groups selected elements; Ctrl+Shift+G ungroups. Groups appear in the left tree panel as collapsible nodes. Groups are persisted in YAML.
-
-**Recipe excerpt (Invariants + Round-trip — the parts that catch the bugs construction-only recipes miss):**
-
-```markdown
-## Invariants
-
-- **A1 (UI≡Model, tree count):**
-  ```
-  agent-view eval "var sg=window.__editorCore.sceneGraph;var modelCount=0;sg.nodes.forEach(function(n){if(n.componentType==='group')modelCount++});var domCount=[...document.querySelectorAll('[role=treeitem]')].filter(function(e){return e.textContent.includes('Группа')}).length;JSON.stringify({modelCount:modelCount, domCount:domCount, match:modelCount===domCount})"
-  ```
-  must return `match: true`.
-
-- **A2 (Tree hierarchy):**
-  ```
-  agent-view eval "var sg=window.__editorCore.sceneGraph;var violations=[];sg.nodes.forEach(function(n,id){if(n.componentType==='group'){n.childrenIds.forEach(function(cid){var domChild=document.querySelector('[data-node-id=\"'+cid+'\"]');var domParent=document.querySelector('[data-node-id=\"'+id+'\"]');if(domChild&&domParent&&!domParent.contains(domChild))violations.push({c:cid,p:id})})}});JSON.stringify({violations:violations.length})"
-  ```
-  must return `violations: 0`.
-
-- **B1 (Round-trip after Ctrl+G + reload):**
-  Capture signature, dispatch Ctrl+G, capture signature, reload, capture signature. The post-reload signature must equal the post-Ctrl+G signature *projected to the persisted fields*. Drift in `transform.x` of any wrapped child means the wrap path did not normalize coords.
-
-- **B2 (No silent wrap-shift):**
-  Before Ctrl+G: capture `getWorldTransform(child).x` for each leaf. After Ctrl+G: re-capture. Difference must be 0 (within float epsilon). Non-zero means the wrap action shifted the child in world space — a regression.
-
-- **C1 (Single undo):**
-  After Ctrl+G, `commandHistory.canUndo === true`. After one `undo()`, signature equals pre-Ctrl+G signature exactly.
-
-- **D1 (No phantom group rows):**
-  Same eval as A1; if the result is `modelCount: 1, domCount: 2`, that is a phantom-row bug. Confirm by `agent-view eval "[...document.querySelectorAll('span')].filter(e=>e.textContent==='Группа'&&e.children.length===0).map(e=>{var r=e.getBoundingClientRect();return{x:r.x,y:r.y}})"` — two adjacent rows in the same column = phantom.
-```
-
-This single example pair (A1 + D1 + B1 + B2) catches the three bugs from the 4.7 grouping session that the construction-only recipes missed.