fullstorydev/subtext/sightmap-browser

Sightmap browser: observe and interact

The sightmap CLI drives a Chrome-for-Testing session and layers your .sightmap/ corpus onto the live page, so you can read page state as an annotated component tree and act on elements by their semantic component identity instead of brittle CSS. To build or maintain the corpus itself, see the sightmap-authoring skill.

What to reach for:

• `snapshot` — read page state as an annotated component tree (start here).
• interaction (click/fill/scroll/…) — drive the page by component identity.
• `browser screenshot` — visual evidence; clip to one component with --component.
• `console` / `network` — debug what the page logged and requested.
• `inspect` — raw DOM for authoring selectors (see sightmap-authoring).

Installation

Every command below needs the sightmap binary on your PATH. Check first, install only if missing — run sightmap version; if that fails, install it:

npm install -g @sightmap/sightmap                                 # recommended: global install
sightmap version                                                 # verify it's on PATH
go install github.com/sightmap/sightmap/go/cmd/sightmap@latest    # or build from source

This skill drives a multi-step browser session, so prefer a global install over npx @sightmap/sightmap <command> (which re-resolves the package on every invocation). Use npm in instructions — the published package is identical under pnpm/yarn, but npm is the safe baseline.

Session management

browser start is a long-running foreground daemon: it owns Chrome and the console/network collector for the whole session, so it holds the shell until you stop it. Every other command here is a thin client that connects to that daemon and returns immediately.

• Interactive: run start in its own terminal, drive from another.
• Scripts / agents (shells that run each command to completion): use

`sightmap browser start --detach`. It backgrounds the daemon in its own session, waits until it is serving, and returns — so it never hangs your shell, and (unlike nohup start &) the daemon survives between one-shot commands.

• A client command that hangs almost always means the daemon isn't up —

run browser status, don't wait it out.

• On a headless Linux host start auto-detects the missing display and runs

headless; if Chrome hits a sandbox restriction the error tells you to add --chrome-flag=--no-sandbox.

Reading the page: annotated snapshots

sightmap snapshot --url URL prints the page's component tree with your corpus layered on (add --coverage for a terse coverage-only view that suppresses the tree). Each line starts with a numeric component ID, then the node content:

42 [SiteHeader]
  83 [DesktopNavLink label="Explore"]
  91 link "Privacy Policy"

• `[ComponentName prop="val"]` — sightmap-matched node; role suppressed
• `role "text"` — unmatched node; role and accessible name shown
• `42` prefix — probe component ID; usable as a handle for interaction commands

Properties are sorted alphabetically. The accessible name is shown last inside brackets when not suppressed (an exact match with a property value).

If the page has 0 interactive nodes, coverage renders ∅ (not ✓) and snapshot exits non-zero — the page is blank or still loading. Wait for it with browser wait-for --selector ... (or --wait N) and re-snap before acting.

Interaction (by ID or component query)

click, fill, hover, and scroll --component-id accept either a numeric probe ID from snapshot output or a component query (see below):

Component queries (CSS-shaped, over sightmap components + extracted properties)

Probe IDs are extraction-local: they're reassigned every snapshot, so on re-rendering pages an <id> from an earlier call goes stale. A component query re-resolves against the live tree atomically (extract → match → act in one pass), so nothing goes stale. Prefer queries on dynamic pages.

• Brackets are component names; [prop op value] filters on **extracted

properties** (not raw DOM attributes). Operators: = exact, ^= prefix, *= substring, with an optional trailing i for case-insensitive.

• Whitespace is a descendant combinator; the last component is the target.

It matches at any depth (A B = a B anywhere under an A), and a predicate on an ancestor scopes the target (Row[title="…"] Star). There is no `>` child combinator — A > B is a parse error; use whitespace.

• If a query matches zero components it errors; if it matches several it

errors and prints the candidates with their distinguishing properties — add a predicate to disambiguate, or append #N. ("Several match" is an ambiguity error listing candidates, not a "no such component" error — read it and disambiguate rather than assuming the component is unreachable.)

• Robust queries need a corpus with disambiguating properties; authoring a

property like FulfillmentTileButton.label is what makes the element addressable (see the sightmap-authoring skill).

• --sightmap-dir (default .sightmap) controls which corpus resolves a query.

Console & network — the runtime view of the corpus

The browser start daemon owns the session and runs a collector that buffers console messages and network requests from every tab for the life of the session (bounded ring buffers, ~1000 of each). Read them with thin query commands — no re-attaching to Chrome, and with history the transient page commands never saw.

These are not just raw debug streams. Each captured record is matched against the corpus's requests: and messages: entries (see the sightmap-authoring skill), so every line leads with a `[MatchedName]` slot — or [--] when nothing in the corpus classified it — the way a snapshot foregrounds a node's [Component]. Matched records also trail their extracted `{name=value}` properties.

Reading the slot:

[AuraAction]         POST /aura → 200 (XHR) {first_action_state=SUCCESS}   # matched a requests: entry + extracted a body value
[AuraAction]         POST /aura → 200 (XHR) {first_action_state=ERROR}     # 200 OK, but the body says it failed — the payoff of request properties:
[--]                 GET  /favicon.ico → 200 (Image)                       # unmatched: no corpus entry, unstructured
[DeprecatedChartApi] warn  ...stackhbar.js has been deprecated             # matched a messages: entry

The [--] slot is deliberately quiet — it marks a record unclassified without drowning the matched ones.