sightmap suggest scans the live page for stable selector candidates. sightmap gap lists the interactive nodes your corpus does not yet cover, with a suggested selector for each cluster it can anchor. sightmap sel-probe validates a candidate selector against the live page. sightmap sel-check re-validates a selector offline against a saved snapshot. This page documents every selector tool.
Selector subset. Sightmap selectors support the descendant (space) and direct-child (
>) combinators only, and exactly four pseudo-classes: :not(), :is(), :where(), and :has(). Positional pseudo-classes such as :nth-child() are errors at validate time.sightmap suggest
Scans the live page — including labeled landmark and widget roles — for elements carrying a stable authoring hook (data-testid or data-component) and prints one candidate selector per unique hook, with a match count and a text sample. Candidates are sorted by match count, highest first. Reach for it when you start a fresh page and the corpus has nothing to say about it yet.
Pass --exclude-known to hide candidates already covered by a corpus selector, and --group to group the remaining candidates under their nearest known ancestor component. Grouping matches the page against the newest .snap.tree.json in the current directory; point --snap at a specific tree file to override the auto-detection.
Flags:
--group, candidates that sit inside a matched component are listed under it, so you can see which gaps belong to a component you already own:
sightmap gap
Walks the live page’s component tree and reports interactive nodes with no component context. By default it reports orphaned (T3) nodes — interactive nodes with no matched ancestor at any depth — grouped into clusters by role, text, and nearest stable-anchor ancestor. Clusters with a stable-anchor ancestor carry a → suggested selector to seed a sel-probe verification; clusters without one print no hint.
With --scope COMPONENT, the analysis inverts: instead of orphans, it reports the unmatched interactive nodes (T2) inside that component’s matched subtree — the right tool when you are tightening a loose scope. Only visible nodes are counted unless you pass --include-hidden. The command requires a .sightmap/ directory.
Flags:
✓ no orphaned interactive nodes. In scoped mode the header becomes T2 gaps in [ComponentName] — N unmatched interactive elements: and a clean result prints ✓ No T2 gaps in [ComponentName].
sightmap sel-probe
Queries the live page with a CSS selector and prints the match count plus per-match detail: element identity, role, text, key attributes, and up to five levels of parent chain. Parents that match a known corpus component are annotated with ★ ComponentName, and a nearest component summary line shows which component the matches sit inside. Run it on every selector before that selector enters YAML.
-- separator before the selector is recommended: selectors can start with - and would otherwise be misinterpreted as flags.
With --all, the command instead navigates to every view URL declared in views/*.yaml — each view’s top-level url: plus any snapshots[].url entries — and prints a per-view match count. That is the cross-page check to run before promoting a component from a view to components.yaml. It waits at least 0.5 seconds after each navigation; raise --wait for slow pages.
Flags:
--all variant prints one line per view URL:
sel-probe exits 0 even when the selector matches nothing — it is a diagnostic, and matches: 0 is a valid answer. Use sel-check when you need a non-zero exit code for automation. Also note that probing does not preserve focus state: elements that only exist while an input is focused (search autocomplete dropdowns, for example) cannot be probed this way — establish the focus state with browser eval instead.sightmap sel-check
Evaluates a CSS selector against a saved .snap.tree.json file offline — no browser session needed. Pass either the .snap path (the sibling .snap.tree.json is derived automatically) or the tree file itself. Matching applies the last simple selector in the chain to every node in the tree, so it answers “does this target element exist in the capture” rather than enforcing the full ancestor chain.
The command exits 1 when the selector matches zero nodes, which makes it a cheap regression guard: pin a known-good selector against a saved snapshot and any refactor that breaks it fails the check.
Typical flow
1
Find candidates
On a fresh page, run
sightmap suggest --exclude-known to list stable-hook selectors not yet in the corpus, or sightmap gap to see orphaned interactive nodes with → selector hints.2
Verify live
Run
sightmap sel-probe -- 'selector' and confirm the match count and parent chain are what you expect. Never write YAML from an unverified selector.3
Write the component and re-check
Add the component to
views/*.yaml (or components.yaml), run sightmap validate, then re-run the authoring loop until the page reports zero orphans.4
Cross-check before promotion
Before promoting a component to
components.yaml, run sightmap sel-probe --all -- 'selector' across every view URL, and pin the result offline with sightmap sel-check against saved snapshots.