@swmansion/argent 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {
@@ -41,22 +41,29 @@
     "scripts/postinstall.cjs"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.0"
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-typescript": "^0.23.2"
+  },
+  "optionalDependencies": {
+    "electron": "^42.4.1"
   },
   "devDependencies": {
     "@argent/cli": "file:../argent-cli",
     "@argent/installer": "file:../argent-installer",
     "@argent/mcp": "file:../argent-mcp",
+    "@argent/telemetry": "file:../telemetry",
     "@argent/tools-client": "file:../argent-tools-client",
-    "@clack/prompts": "^1.1.0",
-    "@types/node": "^25.9.0",
+    "@clack/prompts": "^1.5.1",
+    "@types/node": "^25.9.3",
     "@types/semver": "^7.7.1",
-    "esbuild": "^0.28.0",
+    "esbuild": "^0.28.1",
     "picocolors": "^1.1.1",
-    "semver": "^7.7.4",
+    "posthog-node": "5.35.0",
+    "semver": "^7.8.4",
     "smol-toml": "^1.6.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.6",
+    "vitest": "^4.1.9",
     "yaml": "^2.8.3"
   }
 }

package/rules/argent.md

@@ -4,7 +4,7 @@ alwaysApply: true
 ---
 
 <description>
-Argent MCP tools are available in this project for iOS simulator and Android emulator control. Argent MCP tools are the preferred form of interaction with the application.
+If argent is installed and configured in this environment, its MCP tools are the preferred form of interaction with the application for iOS simulator, Android emulator, and Chromium (CDP) app control; otherwise see `<availability_check>` below before attempting any argent workflow. A "Chromium (CDP) app" is any Chromium runtime exposing a Chrome DevTools Protocol endpoint — an Electron app, or any Chromium-family browser (Chrome/Brave/Edge) launched with `--remote-debugging-port`; all are driven through the same tool surface and tagged `platform: "chromium"`.
 Running MCP server and managing the Argent toolkit utilises `argent` command - if asked use `argent --help` for reference.
 To check current version of MCP server run `argent --version` command.
 
@@ -17,8 +17,24 @@ Use cases:
 - Any request to execute manual QA, UI QA, or visual behavior validation for a mobile app
 - Running, debugging, or testing a React Native app (iOS or Android)
 - Profiling performance or diagnosing re-renders in a React Native app (iOS or Android)
+- Running, debugging, or testing a Chromium (CDP) app — an Electron app (boot with `boot-device` + `electronAppPath`) or a Chromium browser exposing CDP (auto-discovered on port `9222` / `ARGENT_CHROMIUM_PORTS`); on Chromium scroll with `gesture-scroll` and drag with `gesture-drag` — `gesture-swipe` is touch-only
   </description>
 
+<availability_check>
+<important>Run this check once per session, before the first argent tool call or `argent` command. Do not re-probe before later calls.</important>
+
+Confirm argent is available:
+
+1. Are `mcp__argent__*` tools in your tool list? If none are present, argent is not available.
+2. If still unsure, run `command -v argent`. A non-zero exit means the CLI is not on PATH.
+
+If argent IS available, ignore the rest of this block and follow this rule normally.
+
+If argent is ABSENT, treat it as an expected state, not an error to retry. Do not call `mcp__argent__*` tools, do not run `argent` commands, and do not attempt any argent workflow. Tell the user once, and ask if you should continue without argent:
+
+> Argent isn't installed in this environment. To enable the mobile/Chromium tooling this repo is configured for, run `npx @swmansion/argent init -y` (or `npm i -g @swmansion/argent && argent init -y`).
+> </availability_check>
+
 <tapping_rule>
 <important>**Never** derive tap coordinates from a screenshot</important>
 Before **every** tap, you MUST call a discovery tool and extract coordinates from the result. This is not optional. Preferred tools are, in order:
@@ -44,7 +60,7 @@ Before booting, running, or interacting with any app, call `list-devices` first
 Decision order:
 
 1. **Explicit user intent** - choose the user named platform or device. Look for words "simulator" and "emulator".
-2. **Prefer a running device.** iOS simulators - state `Booted` and Android devices - `state: "device"` come first in `list-devices`.
+2. **Prefer a running device.** iOS simulators - state `Booted` and Android devices - `state: "device"` come first in `list-devices`; Chromium (CDP) apps appear as `platform: "chromium"`, `state: "Running"`.
 3. **Single-platform project:** (per `argent-environment-inspector` flags `is_native_ios`/`is_native_android`, or RN with only one platform configured) → boot that platform.
    </device_selection_rule>
 
@@ -128,6 +144,11 @@ RECORDING & REPLAYING FLOWS
 Use skill: `argent-create-flow`
 When: A multi-step interaction sequence needs to be repeated — re-profiling after a fix, A/B comparisons, regression checks, user says "again" / "run that flow", or you worked through a complex path worth saving. Also use proactively: if you are about to repeat steps you already performed, record first, then replay.
 Prompt keywords: flow, repeat, test X times
+
+PROPOSING DESIGN VARIANTS FOR HUMAN SELECTION
+Use skill: `argent-lens`
+When: The user asks for design alternatives / options / A-B choices for a screen or component, or you have produced more than one candidate look for an element and want a human to pick before committing. Covers the build → navigate → screenshot → propose_variant loop and the single blocking await_user_selection call. (Gated behind the `argent-lens` flag, off by default — run `argent enable argent-lens` first.)
+Prompt keywords: variant, design option, alternative, A/B, "let me pick", "show me options"
 </skill_routing>
 
 <subagents>

package/scripts/postinstall.cjs

@@ -15,10 +15,14 @@ try {
   if (state && state.pid) {
     try {
       process.kill(state.pid, "SIGTERM");
-    } catch {}
+    } catch {
+      /* process already gone — nothing to kill */
+    }
   }
   fs.unlinkSync(stateFile);
-} catch {}
+} catch {
+  /* no state file or unreadable — nothing to clean up */
+}
 
 if (process.env.ARGENT_SKIP_POSTINSTALL === "1") {
   process.exit(0);

package/skills/argent-device-interact/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: argent-device-interact
-description: Interact with an iOS simulator or Android emulator using argent MCP tools. Use when tapping UI elements, performing gestures, scrolling/swiping, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots, or checking visible app state after interactions.
+description: Interact with an iOS simulator, Android emulator, or Chromium (CDP) app using argent MCP tools. Use when tapping UI elements, performing gestures, scrolling/swiping, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots, or checking visible app state after interactions.
 ---
 
 ## Unified tool surface
 
-All interaction tools below accept a `udid` parameter and auto-dispatch iOS vs Android based on its shape (UUID → iOS simulator, anything else → Android adb serial). You use the same tool names on both platforms.
+All interaction tools below accept a `udid` parameter and auto-dispatch iOS vs Android based on its shape (UUID → iOS simulator, `chromium-cdp-<port>` → Chromium (CDP) app, anything else → Android adb serial). You use the same tool names on every platform.
+
+**Chromium (CDP) app** = any Chromium runtime exposing a Chrome DevTools Protocol endpoint: an Electron app (boot it with `boot-device` + `electronAppPath`), or any Chromium-family browser (Chrome/Brave/Edge) launched with `--remote-debugging-port`. The latter is auto-discovered by `list-devices` on port `9222` plus anything in `ARGENT_CHROMIUM_PORTS`. The same describe/tap/swipe/keyboard/screenshot surface drives all of them.
+
+**Multi-tab / windows (Chromium only):** a Chromium device may have several tabs / BrowserWindows. Use `chromium-tabs` to `list` them (stable ids `t1`, `t2`, …, optional labels), open a `new` one, `select` which is active, or `close` one. Every other tool (`describe`, `gesture-tap`, `screenshot`, `debugger-evaluate`, `open-url`, …) acts on the **active** tab, so `chromium-tabs action=select` before driving a different tab. Note: a cross-process navigation (some redirects) can swap a tab's underlying CDP target — re-run `chromium-tabs action=list` to pick it up under a fresh id.
+
+**Cookies & storage (Chromium only):** `chromium-cookies` reads/writes cookies via the Network domain (so HttpOnly cookies are visible): `action=get` (optionally scoped by `url`), `set` (`name`, `value`, + `url`/`domain`, optional `secure`/`httpOnly`/`sameSite`/`expires`), `delete` (`name`), `clear` (all). `chromium-storage` reads/writes Web Storage for the active page: `store=local|session`, `action=get` (one `key` or all entries), `set`, `remove`, `clear`. Both are per-origin / active-tab. Handy for seeding auth before a flow or asserting app state after one.
 
 For platform-specific caveats (Metro `adb reverse`, locked-screen describe errors, etc.), see § 9 Platform-specific notes at the bottom.
 
@@ -13,7 +19,7 @@ For platform-specific caveats (Metro `adb reverse`, locked-screen describe error
 
 If you delegate simulator tasks to sub-agents, make sure they have MCP permissions.
 
-Use `list-devices` to get a target id. Results are tagged with `platform` (`ios` or `android`); booted/ready devices come first. Pick the first entry that matches the platform you need — if none are ready, call `boot-device` with `udid` (iOS) or `avdName` (Android). See `argent-ios-simulator-setup` / `argent-android-emulator-setup` for full setup flow.
+Use `list-devices` to get a target id. Results are tagged with `platform` (`ios`, `android`, or `chromium`); booted/ready devices come first. Pick the first entry that matches the platform you need — if none are ready, call `boot-device` with `udid` (iOS), `avdName` (Android), or `electronAppPath` (boots an Electron app as a `chromium` device). A Chromium browser already running with a CDP port shows up directly — no `boot-device` needed. See `argent-ios-simulator-setup` / `argent-android-emulator-setup` for full setup flow.
 
 **Load tool schemas before first use.** Gesture tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`) may be deferred — their parameter schemas are not loaded until fetched. Always use ToolSearch to load the schemas of all gesture tools you plan to use **before** calling any of them. If you skip this step, parameters may be coerced to strings instead of numbers, causing validation errors.
 
@@ -21,7 +27,7 @@ Use `list-devices` to get a target id. Results are tagged with `platform` (`ios`
 
 1. **Always refer to tapping_rule** from your argent.md rule before tapping.
 2. Before performing interactions, consider whether they can be **dispatched sequentially** - more on that in `run-sequence`.
-3. **Use `gesture-swipe` for lists/scrolling**, not `gesture-custom`, unless you need non-linear movement. Consider whether you need multiple swipes, if yes - use `run-sequence`.
+3. **Use `gesture-swipe` for lists/scrolling**, not `gesture-custom`, unless you need non-linear movement. On Chromium use `gesture-scroll` instead — `gesture-swipe` is touch-only. Consider whether you need multiple swipes, if yes - use `run-sequence`.
 4. **Tap a text field before typing** — on iOS try `paste` first then fall back to `keyboard`; on Android use `keyboard` directly (`paste` is iOS-only).
 5. **Coordinates are normalized** — always 0.0–1.0, not pixels.
 6. **For app navigation, prefer `describe` first.** It works on any screen without app restart. Do not navigate from screenshots on regular in-app screens unless `describe` failed to expose a reliable target. Use `native-describe-screen` only when you need app-scoped UIKit properties.
@@ -48,35 +54,37 @@ Common schemes: `messages://`, `settings://`, `maps://?q=<query>`, `tel://<numbe
 
 ## 4. Choosing the Right Tool
 
-| Action           | Tool             | Notes                                                                  |
-| ---------------- | ---------------- | ---------------------------------------------------------------------- |
-| Multiple actions | `run-sequence`   | Batch steps in one call (no intermediate screenshots)                  |
-| Open an app      | `launch-app`     | **Always — never tap home-screen icons**                               |
-| Restart an app   | `restart-app`    | Terminate and relaunch by bundle ID                                    |
-| Open URL/scheme  | `open-url`       | Web pages, deep links, URL schemes                                     |
-| Single tap       | `gesture-tap`    | Buttons, links, checkboxes                                             |
-| Scroll/swipe     | `gesture-swipe`  | Straight-line scroll or swipe                                          |
-| Long press       | `gesture-custom` | Context menus, drag start                                              |
-| Drag & drop      | `gesture-custom` | Complex drag interactions                                              |
-| Pinch/zoom       | `gesture-pinch`  | Two-finger pinch with auto-interpolation                               |
-| Rotation         | `gesture-rotate` | Two-finger rotation with auto-interpolation                            |
-| Custom gesture   | `gesture-custom` | Arbitrary touch sequences, optional interpolation                      |
-| Hardware key     | `button`         | Home, back, power, volume, appSwitch, actionButton                     |
-| Type text (fast) | `paste`          | iOS only. Form fields — uses clipboard                                 |
-| Type text        | `keyboard`       | iOS+Android. Fallback when paste fails; supports Enter, Escape, arrows |
-| Rotate device    | `rotate`         | Orientation changes                                                    |
+| Action            | Tool             | Notes                                                                  |
+| ----------------- | ---------------- | ---------------------------------------------------------------------- |
+| Multiple actions  | `run-sequence`   | Batch steps in one call (no intermediate screenshots)                  |
+| Open an app       | `launch-app`     | **Always — never tap home-screen icons**                               |
+| Restart an app    | `restart-app`    | Terminate and relaunch by bundle ID                                    |
+| Open URL/scheme   | `open-url`       | Web pages, deep links, URL schemes                                     |
+| Single tap        | `gesture-tap`    | Buttons, links, checkboxes                                             |
+| Scroll/swipe      | `gesture-swipe`  | Straight-line scroll or swipe                                          |
+| Scroll (Chromium) | `gesture-scroll` | Wheel-based; deltas are window fractions, positive deltaY = down       |
+| Drag (Chromium)   | `gesture-drag`   | Sliders, drag-and-drop, text selection                                 |
+| Long press        | `gesture-custom` | Context menus, drag start                                              |
+| Drag & drop       | `gesture-custom` | Complex drag interactions                                              |
+| Pinch/zoom        | `gesture-pinch`  | Two-finger pinch with auto-interpolation                               |
+| Rotation          | `gesture-rotate` | Two-finger rotation with auto-interpolation                            |
+| Custom gesture    | `gesture-custom` | Arbitrary touch sequences, optional interpolation                      |
+| Hardware key      | `button`         | Home, back, power, volume, appSwitch, actionButton                     |
+| Type text (fast)  | `paste`          | iOS only. Form fields — uses clipboard                                 |
+| Type text         | `keyboard`       | iOS+Android. Fallback when paste fails; supports Enter, Escape, arrows |
+| Rotate device     | `rotate`         | Orientation changes                                                    |
 
 ## 5. Finding Tap Targets
 
 IMPORTANT. When moved to a different screen after an action or do not know the coordinates of component, **always** perform proper discovery first.
 
-| App type                          | Discovery tool            | What it returns                                                                                                                                                                                                               |
-| --------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Target app discovery              | `describe`                | Accessibility element tree for the current device screen (iOS AX-service or Android uiautomator) with normalized frame coordinates. Works on any app, system dialogs, and Home screen — no app restart or `bundleId` required |
-| React Native                      | `debugger-component-tree` | React component tree with names, text, testID, and (tap: x,y)                                                                                                                                                                 |
-| App-scoped native                 | `native-describe-screen`  | Low-level app-scoped accessibility elements with normalized and raw coordinates; requires `bundleId`                                                                                                                          |
-| Permission / system modal overlay | `describe`                | `describe` detects system dialogs automatically and returns dialog buttons with tap coordinates. Fall back to `screenshot` only if `describe` does not expose the controls                                                    |
-| Final visual fallback             | `screenshot`              | Use only when discovery tools cannot inspect the current UI reliably. Do not derive routine in-app navigation targets from screenshots                                                                                        |
+| App type                          | Discovery tool            | What it returns                                                                                                                                                                                                                                     |
+| --------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Target app discovery              | `describe`                | Accessibility element tree for the current device screen (iOS AX-service, Android uiautomator, or Chromium DOM walker) with normalized frame coordinates. Works on any app, system dialogs, and Home screen — no app restart or `bundleId` required |
+| React Native                      | `debugger-component-tree` | React component tree with names, text, testID, and (tap: x,y)                                                                                                                                                                                       |
+| App-scoped native                 | `native-describe-screen`  | Low-level app-scoped accessibility elements with normalized and raw coordinates; requires `bundleId`                                                                                                                                                |
+| Permission / system modal overlay | `describe`                | `describe` detects system dialogs automatically and returns dialog buttons with tap coordinates. Fall back to `screenshot` only if `describe` does not expose the controls                                                                          |
+| Final visual fallback             | `screenshot`              | Use only when discovery tools cannot inspect the current UI reliably. Do not derive routine in-app navigation targets from screenshots                                                                                                              |
 
 Point follow-up native diagnostics after you already have a candidate point:
 

package/skills/argent-lens/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: argent-lens
+description: Propose multiple visual design variants for on-screen elements and let the human pick in the Argent Lens window. Use when the user asks for design alternatives / options / A-B choices for a screen or component, or any time you have produced more than one candidate look for an element and want a human decision before committing.
+---
+
+> **Prerequisite — feature flag.** This workflow is gated behind the `argent-lens` flag (off by default). Run `argent enable argent-lens` once before using it. If `propose_variant` / `await_user_selection` come back not-found, the flag is off — enable it and retry.
+
+## 1. Overview
+
+You implement several candidate designs, capture each one running on the device, and stage them with `propose_variant`. Each proposed element shows up as a floating card next to the live simulator stream in the Argent Lens window (a native window that opens automatically), connected by a thin line to the real element. The human picks per element, optionally pins free-form comments to elements, and presses **Complete selection**. `await_user_selection` is the single blocking call that returns their decision.
+
+**The golden rule: one variant = one real, _distinct_ screenshot.** A proposal is only useful if its `previewImage` shows the variant actually rendered on the device, captured AFTER that specific variant was applied. Never propose a variant you have not built and seen on screen, and never point two variants at the same file path — if two captures end up byte-identical you have not actually changed anything and the Argent Lens degenerates to identical thumbnails. Plan → build → navigate → screenshot → propose, repeated for every variant of every element, then await once.
+
+## 2. Tools
+
+| Tool                   | Blocking? | Purpose                                                                 |
+| ---------------------- | --------- | ----------------------------------------------------------------------- |
+| `propose_variant`      | No        | Stage ONE variant for ONE element. Call once per variant. Keep working. |
+| `await_user_selection` | Yes       | Call ONCE after every variant is staged. Parks until the human is done. |
+
+`propose_variant` params: `element` (human name), optional `match` (`{ by: "text"|"label"|"identifier"|"role", value }`), optional `udid` (the device id you captured the variants on), and `variant` (`{ name, summary, code?, filePath?, previewImage?, frame? }`). Repeated calls with the same `element` accumulate variants on that element; different `element` values create separate cards.
+
+**Always pass `udid`** (the same simulator/emulator id you screenshotted and described with). The preview window then streams _that_ device directly — the human never has to pick a simulator. Set it on the first `propose_variant` of a round; later calls may omit it (the last value wins).
+
+## 3. Workflow
+
+Resolve a simulator/emulator first (`argent-ios-simulator-setup` / `argent-android-emulator-setup`) and, for React Native, `argent-react-native-app-workflow` to run the app and reload the bundle. Argent shows the staged variants in a native preview window that opens automatically on the user's screen; you don't open or display anything yourself. Just stage variants and call `await_user_selection`, and the window appears on its own.
+
+### Step 0 — Plan the variants
+
+Decide, before touching code, exactly which elements you are redesigning and the distinct variants for each. Write them down (e.g. "Search field: Filled / Outlined / Pill" — "Primary CTA: Solid / Gradient"). Each variant must be a single, self-contained change you can apply, screenshot, and revert independently. Vague or overlapping variants produce useless proposals.
+
+### Step 1 — Get a precise matcher
+
+For each element, run `describe` (or `debugger-component-tree` for RN) on the screen where it lives and read its exact `label` / `identifier` / `role`. Pass that as `match` so the floating card's connector anchors to the right element:
+
+- Stable testID / accessibilityIdentifier → `{ by: "identifier", value: "search-input" }` (most reliable)
+- Exact a11y label → `{ by: "label", value: "Search" }`
+- Otherwise → `{ by: "text", value: "Search" }` (fuzzy contains; the default if `match` is omitted)
+
+Omitting `match` defaults to `{ by: "text", value: element }`, which is fine only when the element's visible text is unique.
+
+### Step 2 — For each variant: build → navigate → screenshot → propose
+
+Loop over every variant of every element:
+
+1. **Build the variant.** Implement that one variant in code.
+2. **Apply it on the device.** Reload the RN bundle (`debugger-reload-metro`) or rebuild as needed so the running app shows this variant.
+3. **Navigate to it.** Drive the app (`argent-device-interact`) to the screen where the element is visible — a screenshot is only meaningful if the element is actually on screen.
+4. **Screenshot.** Call `screenshot` and pass the returned file path **straight through** as `variant.previewImage`. **NEVER hand-crop, resize, re-encode, or copy the screenshot to another folder** (e.g. a `crop.py` into `/tmp/variants/`): that double-crops against the preview window's own cropping and writes the image somewhere the server won't serve it ("No preview"). Capture the whole screen — the preview window crops it for you using `variant.frame` (step 5). The path you got back must be a NEW file; if you suspect the device froze or the variant didn't apply (you see no visible change vs. the previous capture), diff with the previous path (`shasum -a 256`) before proposing — byte-identical captures mean the variant is not on screen yet. Fix that before proposing, never propose anyway.
+5. **Propose.** Call `propose_variant` with `element`, `match`, `udid` (the device you captured on), and `variant.previewImage` set to that screenshot path. The tool **auto-captures the crop frame**: it describes the device at propose time and matches the element, so each thumbnail crops to its own current layout — **as long as the variant is still on screen when you call `propose_variant`** (propose right after the screenshot, before reverting). You may pass `variant.frame` (the matched node's normalized `{x, y, width, height}` in 0..1 from a `describe` on THIS variant) to override the auto-capture — useful when the element can't stay on screen at propose time. Add `summary` (what changed and why) and `code`/`filePath` when useful.
+6. **Revert.** Roll the variant change back before building the next one — only one variant can be on screen at a time. Keep going; `propose_variant` does not block.
+
+`previewImage` accepts a local screenshot path (served from the OS temp dir / cwd), an `http(s)` URL, or a `data:` URI. A local screenshot of the real running variant is strongly preferred.
+
+### Step 3 — Await the human's decision (once)
+
+After every variant for every element is staged, call `await_user_selection` exactly once. It returns:
+
+- `{ status: "completed", selections: [{ element, chosenVariant, comment? }], unselected, annotations: [{ target, match, comment }], globalComment }` — apply `chosenVariant` for each element; skip elements in `unselected`. Treat each `annotations` entry (inspector comments the human pinned to elements) and `globalComment` as a change request.
+- `{ status: "pending", proposedElements }` — `timeoutSeconds` elapsed, not an error. Proposals are still live; call `await_user_selection` again.
+- `{ status: "no_proposals" }` — you called it before any `propose_variant`. Stage variants first.
+
+### Step 4 — Apply the outcome
+
+Implement the chosen variant for every selected element, address every annotation/comment, and report what you applied and what was skipped. If the human commented but skipped a variant, the comment still matters — act on it.
+
+## 4. Rules
+
+- **At least two variants per element.** A choice needs alternatives — every element you propose must have ≥2 distinct variants (call `propose_variant` at least twice for it). If you only have one look for an element, either produce a real alternative or don't propose that element at all; a lone variant isn't a choice.
+- **Build before you propose.** Every `previewImage` must be a screenshot of that variant actually running on the device. No mockups, no guesses, no proposing un-built ideas.
+- **Distinct screenshot per variant.** Reusing a `previewImage` path across two variants — or capturing two paths whose bytes turn out identical — defeats the whole point of the Argent Lens. If you can't produce visibly different captures (e.g. the app is read-only, accessibility is broken so you can't navigate, the bundle won't hot-reload), STOP and tell the user instead of staging duplicates.
+- **One blocking call.** `propose_variant` never blocks — stage freely. `await_user_selection` is the only call that waits, and you call it once, last.
+- **Anchor accurately.** Pull matchers from `describe`; a wrong `match` makes the card point at the wrong element or float unanchored.
+- **One variant on screen at a time.** Apply → screenshot → revert before the next variant so screenshots never bleed together.
+- **`pending` is normal.** On `pending`, just await again — proposals persist across timeouts.
+- **Re-proposing starts a fresh round.** Calling `propose_variant` after a round was consumed begins round N+1 and clears the previous round's elements; stage a full set each round.
+
+## 5. Example
+
+```
+describe { udid }                                  # read exact label/identifier
+propose_variant { element: "Search field",
+  match: { by: "identifier", value: "search-input" },
+  variant: { name: "Outlined", summary: "1pt border, transparent fill",
+             previewImage: "/var/folders/.../search-outlined.png" } }
+propose_variant { element: "Search field",
+  match: { by: "identifier", value: "search-input" },
+  variant: { name: "Pill", summary: "Fully rounded, filled grey",
+             previewImage: "/var/folders/.../search-pill.png" } }
+propose_variant { element: "Primary CTA",
+  match: { by: "label", value: "Get started" },
+  variant: { name: "Gradient", summary: "Accent gradient fill",
+             previewImage: "/var/folders/.../cta-gradient.png" } }
+await_user_selection {}                             # ONE blocking call → human picks
+→ { status: "completed",
+    selections: [ { element: "Search field", chosenVariant: { name: "Pill" } },
+                  { element: "Primary CTA",  chosenVariant: { name: "Gradient" } } ],
+    annotations: [ { target: "Tab bar", comment: "raise contrast" } ] }
+# → apply Pill + Gradient, and raise tab-bar contrast.
+```

package/skills/argent-metro-debugger/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: argent-metro-debugger
-description: Debug a React Native app via Metro CDP using argent debugger tools. Use when connecting to Metro, inspecting React components, reading console logs, or evaluating JavaScript in the app runtime.
+description: Debug a JS runtime via CDP using argent debugger tools. Primary path is React Native via Metro (iOS / Android); a subset of the tools (debugger-connect, debugger-status, debugger-evaluate, debugger-log-registry) also drive a Chromium (CDP) app's renderer (an Electron app, or any Chromium browser exposing CDP) through the same surface. Use when connecting to the runtime, inspecting React components, reading console logs, or evaluating JavaScript.
 ---
 
 ## 1. Prerequisites
 
-The debugger requires **Metro dev server running** (default `localhost:8081`) and **a React Native app connected to Metro** (at least one CDP target). Verify via `debugger-status`.
+For **React Native (iOS / Android)**: requires **Metro dev server running** (default `localhost:8081`) and **a React Native app connected to Metro** (at least one CDP target). Verify via `debugger-status`.
+
+For **Chromium (CDP)**: requires a Chromium/CDP app already available — an Electron app booted via `boot-device` with `electronAppPath`, or any Chromium browser exposing a CDP port (auto-discovered by `list-devices` on `9222` / `ARGENT_CHROMIUM_PORTS`). The debugger re-uses the page CDP session — `port` is ignored, `device_id` is the `chromium-cdp-<port>` value from `list-devices` / `boot-device`. Only `debugger-connect`, `debugger-status`, `debugger-evaluate`, `debugger-log-registry`, `view-network-logs`, and `view-network-request-details` work on Chromium (the latter two read the browser's native CDP Network recording for the active tab instead of the Metro-injected `fetch` interceptor); `debugger-component-tree`, `debugger-reload-metro`, `debugger-inspect-element`, and the `react-profiler-*` / `profiler-*` tools are RN-only and reject Chromium at the capability gate with `Tool 'X' is not supported on chromium app`.
 
 ### Android: reverse port for Metro
 
@@ -25,10 +27,10 @@ One Metro port can serve multiple connected devices (e.g. two simulators on `loc
 
 ### Connect & diagnostics
 
-| Tool               | Purpose                                                                                                                                                                                                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debugger-connect` | Connect to Metro CDP. Returns port, projectRoot, deviceName, appName, `logicalDeviceId`, isNewDebugger, connected. The returned `logicalDeviceId` is the `device_id` for every subsequent debugger/network/profiler call. |
-| `debugger-status`  | Like connect + loadedScripts, enabledDomains, sourceMapReady. **Use to diagnose.**                                                                                                                                        |
+| Tool               | Purpose                                                                                                                                                                                                                                                                                            |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugger-connect` | Connect to the JS runtime's CDP (Metro on iOS / Android; the page CDP session on Chromium). Returns port, projectRoot (empty on Chromium), deviceName, appName, `logicalDeviceId`, isNewDebugger, connected. The returned `logicalDeviceId` is the `device_id` for every subsequent debugger call. |
+| `debugger-status`  | Like connect + loadedScripts, enabledDomains, sourceMapReady (no-op on Chromium). **Use to diagnose.**                                                                                                                                                                                             |
 
 ### Reload & recovery
 
@@ -115,13 +117,13 @@ When reading from the log file:
 
 ## Quick Reference
 
-| Action                        | Tool                                                                |
-| ----------------------------- | ------------------------------------------------------------------- |
-| Diagnose / check connection   | `debugger-status`                                                   |
-| Connect to Metro CDP          | `debugger-connect`                                                  |
-| Reload JS (already connected) | `debugger-reload-metro`                                             |
-| Relaunch app on device        | `restart-app`                                                       |
-| Inspect component at point    | `debugger-inspect-element`                                          |
-| Full component tree           | `debugger-component-tree`                                           |
-| Console log overview          | `debugger-log-registry` (summary + log file path for `Grep`/`Read`) |
-| Evaluate JS                   | `debugger-evaluate`                                                 |
+| Action                            | Tool                                                                |
+| --------------------------------- | ------------------------------------------------------------------- |
+| Diagnose / check connection       | `debugger-status`                                                   |
+| Connect to CDP (Metro / Chromium) | `debugger-connect`                                                  |
+| Reload JS (already connected)     | `debugger-reload-metro`                                             |
+| Relaunch app on device            | `restart-app`                                                       |
+| Inspect component at point        | `debugger-inspect-element`                                          |
+| Full component tree               | `debugger-component-tree`                                           |
+| Console log overview              | `debugger-log-registry` (summary + log file path for `Grep`/`Read`) |
+| Evaluate JS                       | `debugger-evaluate`                                                 |

package/skills/argent-native-profiler/SKILL.md

@@ -86,14 +86,14 @@ To revisit a previous trace:
 
 Bottlenecks are categorized by severity:
 
-- **RED**: CPU functions taking >15% of total time, all UI hangs, all memory leaks. These require immediate attention.
-- **YELLOW**: CPU functions taking 5-15% of total time. Worth investigating but may be acceptable.
+- **RED**: CPU functions taking >15% of total time, all UI hangs, and **attributed** memory leaks (those with a resolved responsible frame). These require immediate attention.
+- **YELLOW**: CPU functions taking 5-15% of total time, and **unattributed** memory leaks (`<Call stack limit reached>`, no library — see the memory-leaks caveat below). Worth investigating but may be acceptable.
 
 Each bottleneck type indicates a different class of problem:
 
 - **CPU hotspots**: Native functions consuming excessive CPU time. Look for tight loops, expensive computations, or redundant work.
 - **UI hangs**: Main thread blocked long enough to cause visible jank or unresponsiveness. Often caused by synchronous I/O, heavy layout passes, or lock contention.
-- **Memory leaks**: Objects allocated but never freed. Common causes include retain cycles, unclosed resources, or forgotten observers.
+- **Memory leaks**: Objects allocated but never freed. Common causes include retain cycles, unclosed resources, or forgotten observers. Argent records via `xctrace --attach`, which has no malloc-stack history, so on the simulator most leaks come back **unattributed** (`<Call stack limit reached>`, no library) and are dominated by benign system allocations — these are reported as a low-confidence YELLOW summary, not confirmed RED leaks. For attributed stacks, capture with malloc stack logging enabled at launch.
 
 ---
 

package/skills/argent-react-native-app-workflow/SKILL.md

@@ -235,13 +235,13 @@ If the user's intent is ambiguous (run existing tests, write new tests, or find
 
 ## Related Skills
 
-| Skill                           | When to use                                                                     |
-| ------------------------------- | ------------------------------------------------------------------------------- |
-| `argent-ios-simulator-setup`    | Initial iOS simulator boot and connection setup                                 |
-| `argent-android-emulator-setup` | Initial Android emulator boot and connection setup                              |
-| `argent-device-interact`        | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator  |
-| `argent-metro-debugger`         | Full Metro CDP debugging: component inspection, console logs, JS evaluation     |
-| `argent-react-native-profiler`  | Profiling performance, finding re-render issues, CPU hotspots                   |
-| `argent-test-ui-flow`           | Interactive UI testing with automatic screenshot verification after each action |
+| Skill                           | When to use                                                                                                                                              |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `argent-ios-simulator-setup`    | Initial iOS simulator boot and connection setup                                                                                                          |
+| `argent-android-emulator-setup` | Initial Android emulator boot and connection setup                                                                                                       |
+| `argent-device-interact`        | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator                                                                           |
+| `argent-metro-debugger`         | JS-runtime CDP debugging (Metro on iOS / Android; the four ported tools also drive Chromium/CDP apps): component inspection, console logs, JS evaluation |
+| `argent-react-native-profiler`  | Profiling performance, finding re-render issues, CPU hotspots                                                                                            |
+| `argent-test-ui-flow`           | Interactive UI testing with automatic screenshot verification after each action                                                                          |
 
 Ask the user before running tests: confirm which test suite (unit, E2E, or both), whether to use existing CI commands, and whether they want you to run existing tests, write new ones, or explore test cases yourself.