Author a Sightmap Against the Running App

A sightmap is written against the rendered app. Source code can suggest names and file paths, but the live page proves whether a route or selector matches. In a typical workflow, an agent drafts the YAML and a human reviews the diff.

Before you start

Complete Install and Quickstart first. You need:

The sightmap CLI and sightmap-authoring skill.
A running copy of the web app.
A .sightmap/ directory in the project.

The agent drives Chrome through the CLI, applies the corpus to the live DOM, and reads back which interactive nodes remain unnamed.

Run the edit-verify loop

The commands below are what the agent runs through the sightmap-authoring skill; you review the diff before it lands. The agent works through one route at a time.

Start a session

cd my-app
sightmap browser start --url 'https://example.com/products'

The agent starts the session with browser start, which launches Chrome and the corpus server. The server reloads the YAML whenever the agent changes it.

Iterate a page

The agent runs snapshot --coverage with the page URL:

sightmap snapshot --coverage --url 'https://example.com/products'

[View: ProductListPage]
route: /products/**

[Coverage] (visible only)
87 interactive · 21 direct T1 (24%) · 61 scoped T2 (70%) · 5 orphaned T3 ✗

Unlabeled clusters:
  5× button (no text)
       inside: div[data-testid="product-pod"]
       → [data-testid="product-pod"] button

Coverage assigns every interactive node a tier:

Tier	Meaning	Goal
T1 direct	The node itself matched a component selector	Maximize
T2 scoped	Unnamed, but inside a matched ancestor	Acceptable when tight
T3 orphaned	No matched ancestor at any depth	Must reach 0

snapshot --coverage prints coverage and groups T3 nodes by a suggested selector, suppressing the full tree. Drop the --coverage flag for the full annotated tree, or use sightmap capture to save the page into its view set.

Verify the suggested selector

The agent probes the suggested selector against the live page before adding it to YAML:

sightmap sel-probe -- '[data-testid="product-pod"] button'

sel-probe reports the match count, key attributes, and parent chain for each match — the agent checks that the count and matched elements are what it intended.See Selector tools for live and offline checks, and Selectors for selector strategy.

Name what's unnamed

The agent adds the component to the matching view:

.sightmap/views/products.yaml

version: 1

views:
  - name: ProductListPage
    route: /products/**
    components:
      - name: ProductCard
        selector: '[data-testid="product-pod"]'
        children:
          - name: AddToCartButton
            selector: 'button[data-testid="atc"]'

It validates after each edit:

sightmap validate

The running session picks up the change without a restart.See Components for the complete component format.

Repeat

The agent re-runs snapshot --coverage and works through the remaining T3 clusters. A route reaches the baseline when coverage reports 0 orphaned T3 ✓. Then it reviews the T2 scopes.

For a new page, sightmap suggest --exclude-known finds source-controlled selector hooks, sightmap discover lists the site’s URL patterns, and sightmap inspect prints the raw DOM tree.

Review T2 scopes

Zero T3 means every interactive node has a named ancestor. It does not mean every node has enough identity. A T2-tight scope has one unnamed interactive child under a named component. Its role and accessible name may be enough to identify it. A T2-loose scope has several unnamed interactive children under the same component, which makes attribution ambiguous. The agent runs sightmap snapshot --trace to inspect those scopes and adds child components where stable selectors exist. If a third-party widget or generated markup has no stable selector, it records that limitation in memory. See Coverage for the complete T1, T2, and T3 model.

Promote shared components

After mapping several routes, use saved captures to find components that recur:

sightmap multi-coverage

The matrix shows which components appear in each view. Move a component to the root components: collection when it should match every view, such as the site header or consent banner. Keep feature-specific components inside their view. See Coverage for capture requirements and the full cross-view report.

Validate and maintain the corpus

Run the structural and style checks before committing:

sightmap validate
sightmap lint

Keep the corpus current as the app changes:

Have your agent re-run snapshot --coverage on affected pages. Coverage exposes new orphaned nodes while existing selectors and memory remain in the corpus.
Remove stale selectors and memory. If you can fix a documented quirk in the app, fix it and delete the note.
Run sightmap validate and sightmap lint in CI.
If you maintain saved view sets, refresh them with sightmap capture --all, then run sightmap report.

See View sets for representative URLs, capture storage, and pruning.

Hand-authoring

You can write .sightmap/ as plain YAML without the CLI. The JSON Schema validates the files, and the spec defines each field. The CLI and authoring skill add live verification to that editing process. Use the CLI reference for commands and flags, or read the full sightmap-authoring skill for the agent playbook.

Get started

Concepts

Authoring

Author a Sightmap Against the Running App

Before you start

Run the edit-verify loop

Review T2 scopes

Promote shared components

Validate and maintain the corpus

Hand-authoring

​Before you start

​Run the edit-verify loop

​Review T2 scopes

​Promote shared components

​Validate and maintain the corpus

​Hand-authoring

Before you start

Run the edit-verify loop

Review T2 scopes

Promote shared components

Validate and maintain the corpus

Hand-authoring