argent-lens

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 comes 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 (non-blocking, once per variant). The Argent Lens window opens on its own and shows each element as a card beside the live device stream; the human picks per element, may pin comments, and presses Complete. await_user_selection is the single blocking call that returns their decision. Both tools' descriptions cover their parameters and return shapes.

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.

2. Workflow

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 on its screen and read its exact identifier / label / role. Prefer match: { by: "identifier", … } (stable testID), then an exact label; the default text match is fine only when the element's visible text is unique. A wrong match makes the card point at the wrong element or float unanchored.

Step 2: For each variant: build → navigate → screenshot → propose → revert

1. Build the 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 (argent-device-interact): a screenshot is only meaningful if the element is on screen.
4. Screenshot. Call screenshot and pass the returned path straight through as variant.previewImage. NEVER hand-crop, resize, re-encode, or copy the screenshot to another folder: that double-crops against the preview window's own cropping and writes the image where the server won't serve it ("No preview"). If you suspect the variant didn't apply (no visible change vs. the previous capture), compare with the previous path (shasum -a 256): byte-identical captures mean the variant is not on screen yet. Fix that; never propose anyway.
5. Propose with element, match, udid (the device you captured on) and previewImage, plus a summary and code/filePath when useful. The tool auto-captures the crop frame by describing the device at propose time, so propose right after the screenshot, while the variant is still on screen. Pass variant.frame only to override that, e.g. when the element can't stay on screen at propose time.
6. Revert the change before building the next variant.

Step 3: Await the human's decision

After every variant for every element is staged, call await_user_selection once. A pending result is normal: the proposals stay live, call it again. In an argent lens session that tool is hidden: end your turn instead, and the user's choice arrives as a message.

Step 4: Apply the outcome

Implement the chosen variant for every selected element, treat every annotation and the global comment as a change request, and report what you applied and what was skipped. If the human commented but skipped a variant, the comment still matters; act on it.

3. Rules

• One variant = one real, distinct screenshot. Every previewImage must show that variant actually running on the device, captured after it was applied: no mockups, no un-built ideas, never the same path (or byte-identical captures) for two variants. If you can't produce visibly different captures (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.
• At least two variants per element. If you only have one look for an element, produce a real alternative or don't propose that element at all; a lone variant isn't a choice.
• One variant on screen at a time. Apply → screenshot → propose → revert, so screenshots never bleed together.
• Re-proposing starts a fresh round. Calling propose_variant after a round was consumed begins the next round and clears the previous round's elements; stage a full set each round.