ui-capture

ui-capture - Visual Capture & Reference

Capture reference screenshots and transition videos, detect transition types, and optionally capture matching implementation clips as downstream verification evidence.

Primary trigger: Capture/reference evidence from a URL. Non-goals: Do not use ui-capture as the primary mismatch diagnosis tool; hand failing validation evidence to visual-debug.

Session rule

Always use --session <project-name> with every agent-browser command.

Token rule

Pipe large eval output to a file, then Read only what you need:

agent-browser --session <s> eval "<script>" > tmp/ref/<name>.json

Never let large JSON print to stdout — it wastes tokens.

eval JSON unwrap rule

agent-browser eval returns the script's return value JSON-encoded, so a script that returns JSON.stringify(obj) writes a double-quoted JSON string to disk (e.g. "{\"sections\":[...]}"), not the object itself. Passing that file straight to jq '.sections' fails with jq: Cannot index string with string "sections".

Unwrap once before further jq work:

agent-browser --session <s> eval "(() => JSON.stringify({...}))()" > raw.json
jq -r 'fromjson' raw.json > data.json   # now a real object; pipe to jq freely

Or skip the inner JSON.stringify entirely — agent-browser eval already serializes the return value, so returning the plain object works too and avoids the unwrap step:

agent-browser --session <s> eval "(() => ({sections: [...]}))()" > data.json

When to use

• Standalone: invoke ui-capture <reference-url> [local-url] [component] (Claude slash command: /ui-capture ...)
• From ui-reverse-engineering: Phase A (reference), Phase 4 (verification) — <component> MUST be passed so output lands in tmp/ref/<component>/ where the pipeline gates look
• From orchestration workflows: when SPEC.md has reference_url

Output directory:

• <component> provided → tmp/ref/<component>/ (matches ui_clone.gate expectations — flat, no capture/ parent)
• <component> omitted → tmp/ref/capture/ (standalone usage; not gated)