.sightmap/ corpus, and turn the DOM into something an agent (or you) can reason about. snapshot produces the full annotated tree and saves it into the view’s view set. iterate is the fast edit-verify loop — navigate, snap, and score coverage in one step, without printing the tree. inspect drops below the sightmap layer and shows the raw DOM structure when you need to find an anchor for a new selector.
All three commands need a running browser session — start one with
sightmap browser start (see Browser session). Scoring saved captures offline is covered in Coverage commands, and how captures are organized on disk in View sets. To verify a candidate selector before writing YAML, use the selector tools.snapshot
Connects to the Chrome session, runs the component-extraction pipeline, applies the corpus, and emits an annotated ARIA tree together with coverage statistics. The output has four sections: a [View: ...] header (when the page URL matches a view’s route:), a [Guide] listing each matched component with its match count, the component tree itself, and a [Coverage] summary line. Components that matched zero nodes are listed under [Warnings].
Each tree line starts with a numeric probe ID, then the node content:
- Matched nodes render as
ID [ComponentName prop="val"]— the component name replaces the ARIA role, extracted properties are sorted alphabetically, and the accessible name appears last (suppressed when it exactly equals a property value). - Unmatched nodes render as
ID role "text"— the ARIA role and accessible name.
- View matched, no
--out— the capture is appended to the view’s set at.sightmap/snapshots/{view}/{stamp}.snapwith a sibling.snap.tree.json, subject to the novelty gate (below). On success the command prints nothing. - Explicit
--out FILE— writes exactly there. No set, no gate. - No view, no
--out— prints to stdout.
.sightmap/snapshots/plp/20260722T183502Z.snap:
Capture excerpt
snapshot keeps the capture only if it adds something structurally new relative to the set — a new component type matched, or a new orphan slot. Pure value churn (different products, prices, copy) never counts, so dynamic pages saturate instead of accumulating near-duplicates. The first capture of a view always writes; --force overrides. A skipped capture reports on stderr:
snapshot-novelty primitive.
--json vs --tree-out. These are the only JSON outputs, and both write files. --tree-out writes the raw component tree — the input the offline commands (coverage, multi-coverage, sel-check) consume; it is written automatically as the .snap.tree.json sibling whenever a capture joins a view’s set. --json writes an annotated tree — a strict superset of the raw tree that adds the matched component name, memory: notes, and extracted property values per node (fields omitted on unmatched nodes). Use --json when a downstream tool wants the sightmap layer, --tree-out when it wants the bare structure.
--all navigates to every URL declared in your views/*.yaml files — each view’s top-level url: plus any snapshots[].url variants — and appends a novelty-gated capture per target, then prints a summary:
iterate
The primary authoring loop: navigate, snap, and print coverage in one step. iterate suppresses the tree output entirely — you get the [View: ...] line, the [Coverage] summary, an Unlabeled clusters section grouping the orphaned T3 nodes with a suggested selector (the → line), and a T2 scopes breakdown of components with multiple unnamed interactive children. That makes it the fastest way to run the fix-YAML-and-recheck cycle described in the authoring workflow.
The full snap is still written — to /tmp/sightmap-iter-SLUG.snap (with a .snap.tree.json sibling), where SLUG is derived from the URL path — never to the site’s view sets. Use snapshot when you want a permanent capture.
Flags:
sel-probe before writing YAML, add the component, then run iterate again. Repeat until the coverage line reads 0 orphaned T3 ✓.
inspect
Renders the raw DOM component tree — every element with its identifying attributes, without the sightmap filtering that snapshot applies. Use it when you need to find an anchor for a new component and sel-probe already presupposes a selector.
Each line shows the probe ID, a CSS-selector-style display (tag#id[attr="value"]), and the accessible name when present. By default only the key identifying attributes appear: data-*, aria-*, role, type, href, name, for, action, src, and placeholder. Hidden nodes are marked [hidden]. Nodes already matched by a component in --sightmap-dir carry a ★ComponentName annotation, so you can see at a glance which parts of the DOM your corpus already claims.
Flags:
Typical flow
1
Start a browser session
Run
sightmap browser start from the directory containing your .sightmap/ corpus. Confirm with sightmap browser status (see Browser session).2
Iterate on one page
Run
sightmap iterate 'URL' and read the coverage line. For each unlabeled cluster, verify the suggested selector with sel-probe, add a component to your YAML, and iterate again until 0 orphaned T3 ✓.3
Inspect when you need an anchor
When no suggestion fits, run
sightmap inspect --interactive to see the raw DOM with ★ marks on already-claimed nodes, and pick a stable attribute to build the selector from.4
Refresh the view sets
Run
sightmap snapshot --all to append a novelty-gated capture for every view URL in views/*.yaml, then score them offline with the coverage commands.