sightmap suggest finds stable hooks on the live page. sightmap gap lists interactive nodes that the corpus does not cover and suggests selectors when it can. sightmap sel-probe checks a selector against the live page, while sightmap sel-check checks one against a saved snapshot.
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 for elements with a data-testid or data-component attribute. It prints one selector per unique attribute value, along with a match count and text sample, sorted by match count from highest to lowest.
Pass --exclude-known to hide candidates already covered by a global component selector. Pass --group to organize the remaining candidates by their nearest known ancestor component. Grouping uses the newest .snap.tree.json in the current directory when available, or matches the live tree if no snapshot is found. Use --snap to select a specific tree file.
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 with no matched ancestor at any depth. It groups them by role, text, and nearest stable-anchor ancestor. A cluster with a stable-anchor ancestor includes a → selector suggestion.
With --scope COMPONENT, the command reports unmatched interactive nodes (T2) inside that component’s matched subtree. 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 details for up to --max matches: element identity, role, text, key attributes, and five levels of parent context. Parents that match a global component are annotated with ★ ComponentName. A nearest component line summarizes the global component ancestors of the returned matches.
-- separator before the selector is recommended: selectors can start with - and would otherwise be misinterpreted as flags.
With --all, the command navigates to the corpus’s snapshot targets. A view with no snapshots: entries contributes its top-level url:. Otherwise, each snapshots[].url contributes a target and falls back to the top-level url: when omitted. The command prints a match count for each target. Use this check before promoting a view component to the global components: collection. It waits at least 0.5 seconds after each navigation; increase --wait for pages that need more time.
Flags:
--all variant prints one line per view URL:
matches: count, sel-probe runs the same selector through the offline matcher that snapshot, coverage, and capture use, and prints its count. When the two disagree it emits a ⚠ offline/live divergence warning with a hint — typically the selector targets nodes the offline tree doesn’t carry (a subtree hidden at capture time, or content that only appears after an interaction). Trust the offline count: that is what the corpus sees. This makes “probe before you write YAML” honest rather than a source of false confidence.
sel-probe exits 0 when the selector matches nothing because matches: 0 is a valid diagnostic result. Use sel-check when automation needs a non-zero exit code for zero matches. Match counts are capped by --max, including with --all; raise the limit when you need the full count. sel-probe also does not create transient UI state. Open a menu or focus an input with a browser interaction before probing elements that only exist in that state.sightmap sel-check
Evaluates a CSS selector against a saved .snap.tree.json file without a browser session. Pass either the .snap path, which resolves to the sibling .snap.tree.json, or the tree file itself. Matching applies the last simple selector in the chain to every node in the tree. It checks whether the target element exists without enforcing the ancestor chain.
The command exits 1 when the selector matches zero nodes. You can use that exit code to check a known selector against a saved snapshot in automation.
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 before writing the selector to YAML.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 the global
components: collection, run sightmap sel-probe --all -- 'selector' across the declared view URLs. Use sightmap sel-check to check the selector against saved snapshots.