sitemap.xml tells search engines how to crawl your site..sightmap/ teaches coding agents how your app works.
A sightmap is YAML checked into your repo. It maps views, components, and API routes to source files, so every agent gets the same context. Agents check it against the running app to keep it current.
.sightmap/a11yuid=1_0 RootWebArea "Book a flight"
uid=1_3 textbox "Departure date"
uid=1_8 button "Previous Month"
uid=1_9 button "Next Month"
uid=1_10 generic "July 2025"
uid=1_19 gridcell "Choose Tuesday, July 1st, 2025"
uid=1_20 gridcell "Choose Wednesday, July 2nd, 2025"
uid=1_21 gridcell "Choose Thursday, July 3rd, 2025"
…28 more gridcells….sightmap/a11y[View: FlightSearch "/search"]
[Guide]
- DepartureDatePicker accepts typed YYYY-MM-DD
// skips opening the calendar
- Arrow keys navigate the grid; Enter selects; Esc closes
- Past dates render but are aria-disabled
- Range: 1st click = start, 2nd = end, 3rd resets
uid=1_0 RootWebArea "Book a flight"
uid=1_1 FlightSearchForm visible
uid=1_3 DepartureDatePicker [src: src/components/DatePicker.tsx] visible interactive
uid=1_4 date-input visible interactive
uid=1_8 prev-month visible interactive
uid=1_9 next-month visible interactive
uid=1_10 month-label "July 2025" visible
uid=1_19 day "Choose Tuesday, July 1st, 2025" visible interactive
…30 more days…Every agent working on your app starts from scratch. It greps source, guesses which components render each screen, stuggles with runtime quirks, and moves on without leaving anything behind.
Agents record what they learn in a sightmap for the next agent to use.
Views name your app's screens and routes. Components name the parts of each screen. Requests name the API routes your app calls. Define all three in YAML under .sightmap/. Sightmap-enabled tooling adds them to the agent's accessibility snapshot automatically.
A view names a screen or route. When the current URL matches, the agent sees the view name and route at the top of its snapshot.
version: 1
views:
- name: FlightSearch
route: /search
description: Primary booking flow
source: src/pages/FlightSearch.tsx
- name: BookingConfirmation
route: /bookings/*
source: src/pages/Booking.tsx[View: FlightSearch "/search"]
uid=1_0 RootWebArea "Book a flight"
uid=1_1 main visible
uid=1_2 heading "Find your flight"
…
// on /bookings/42
[View: BookingConfirmation "/bookings/42"]| Field | Type | Description |
|---|---|---|
| name required | string | Shown in the snapshot header |
| route required | string | Glob pattern. * matches one segment, ** any depth. Most specific match wins; declaration order tiebreaks. |
| description | string | Optional, not surfaced at runtime — useful for humans reading the file |
| source | string | Relative path to the source file |
| dependencies | string[] | Optional globs naming secondary files (hooks, stores, styles) whose changes should also trigger re-curation. |
| components | Component[] | View-scoped components, merged additively with globals. Accepts { $ref: Name } to reference a globally-defined component. |
| requests | Request[] | View-scoped requests, merged additively with globals |
A component gives a CSS selector a semantic name. Agents see DepartureDatePicker instead of div.react-datepicker__day in every snapshot. Record runtime quirks in the memory field.
version: 1
components:
- name: DepartureDatePicker
selector: '[data-picker="departure"]'
source: src/components/DatePicker.tsx
dependencies:
- src/components/DatePicker.module.css
- src/hooks/useDateRange.ts
memory:
- Accepts typed YYYY-MM-DD — skips the calendar
- Arrow keys navigate; Enter selects; Esc closes
- Past dates render but are aria-disabled
- Range: 1st click = start, 2nd = end, 3rd resets
children:
- name: date-input
selector: input
- name: day-grid
selector: '[role="grid"]'
- name: day
selector: '[role="gridcell"]'uid=1_3 DepartureDatePicker [src: src/components/DatePicker.tsx]
visible interactive
uid=1_4 date-input visible interactive
uid=1_11 day-grid visible
uid=1_19 day "Choose Tuesday, July 1st, 2025"
visible interactive
uid=1_20 day "Choose Wednesday, July 2nd, 2025"
visible interactive
…components: array, { $ref: SiteHeader } inserts a deep copy of a root-level component from any sightmap file. Define a header, footer, or chat widget once, then reference it from every view where it should appear. If the component is absent at runtime, drift checks can report it as attested but missing.| Field | Type | Description |
|---|---|---|
| name required | string | Replaces the generic a11y role in snapshots |
| selector required | string | string[] | CSS selector, or a list of alternatives |
| source | string | Path to the source file — rendered inline as [src: …] |
| dependencies | string[] | Optional globs naming supplementary files (styles, helpers) whose changes should trigger re-curation of this component. Curation-time metadata; not surfaced at runtime. |
| description | string | Optional, not surfaced at runtime |
| memory | string[] | Notes that appear in the [Guide] section of every matched snapshot |
| children | Component[] | Nested components; their selectors are scoped to the parent's subtree |
Requests give API endpoints semantic names and optional request and response schemas. Sightmap-enabled clients show the name, source file, description, and expected fields alongside each matching request.
version: 1
requests:
- name: SearchFlights
route: /api/flights/search
method: POST
description: Search for available flights
source: src/api/flights.ts
request:
fields:
- name: origin
type: string
description: Origin airport code
- name: destination
type: string
- name: date
type: string
description: YYYY-MM-DD
response:
fields:
- name: flights
type: array
- name: total
type: number# network list
reqid=1 SearchFlights POST /api/flights/search [200]
reqid=2 GET /assets/logo.png [200]
# network detail → reqid=1
### Sightmap: SearchFlights
Search for available flights
Source: src/api/flights.ts
Expected request fields:
- origin (string) — Origin airport code
- destination (string)
- date (string) — YYYY-MM-DD
Expected response fields:
- flights (array)
- total (number)| Field | Type | Description |
|---|---|---|
| name required | string | Shown in network list and detail output |
| route required | string | Glob pattern. Express-style :param segments convert to *. |
| method | string | Optional HTTP method filter (GET, POST, …) |
| description | string | What the endpoint does |
| source | string | Path to the source file |
| request | object | Expected payload: fields[] (name, type, description) |
| response | object | Expected response: same shape as request |
| headers | string[] | Notable header names to highlight in the detail view |
Sightmap recursively loads and merges every *.yaml and *.yml file under .sightmap/. Split definitions by feature or view, or keep everything in one file.
.sightmap/
├── components.yaml # global NavBar, Footer
├── requests.yaml # API endpoints
└── pages/
├── flights.yaml # FlightSearch view + its components
└── booking.yaml # BookingConfirmation viewSightmap names views, components, and API routes. Agents add memory notes for quirks, invariants, and shortcuts that source code does not explain. Sightmap-enabled tooling puts those notes in a [Guide] at the top of each snapshot. The next agent starts with the context the last one recorded.
version: 1
components:
- name: DepartureDatePicker
selector: '[data-picker="departure"]'
source: src/components/DatePicker.tsx
memory:
- Accepts typed YYYY-MM-DD —
skips opening the calendar entirely
- Arrow keys navigate the grid;
Enter selects; Esc closes
- Past dates render but are aria-disabled —
check before clicking
- Range: 1st click = start, 2nd = end,
3rd resets to new start[View: FlightSearch "/search"]
[Guide]
- DepartureDatePicker accepts typed YYYY-MM-DD
// skips opening the calendar entirely
- Arrow keys navigate the grid;
Enter selects; Esc closes
- Past dates render but are aria-disabled
- Range: 1st click = start, 2nd = end,
3rd resets to new start
uid=1_0 RootWebArea "Book a flight"
uid=1_3 DepartureDatePicker visible interactive
…Install the CLI, start a browser session, and have your agent map the running app into .sightmap/. Review and commit the YAML so every agent using Sightmap-enabled tooling starts with the same app context.
The sightmap CLI ships through npm as a prebuilt native binary, so you do not need Go. sightmap skills install adds the agent playbooks to your harness. .sightmap/ is plain YAML, with no framework adapter or build step.
$ npm install -g @sightmap/sightmap
$ sightmap skills install
installed 2 sightmap skill(s) → ~/.agents/skills
sightmap-authoring
sightmap-browserbrowser start launches Chrome and a corpus server that reloads YAML changes. iterate snapshots a page and scores each interactive node: named (T1), inside a named component (T2), or orphaned (T3). Repeat until there are no orphans.
$ sightmap browser start
● ready port=7891 cdp=7892 pid=52441 tab=A1B2C3D4
$ sightmap iterate 'http://localhost:3000/'
[View: Home "http://localhost:3000/"]
[Coverage] (visible only)
87 interactive · 61 direct T1 (70%) · 21 scoped T2 (24%) · 5 orphaned T3 ✗Run sightmap sel-probe '[data-testid="product-pod"]' to verify a selector before adding it.
Point your agent at the app. The bundled sightmap-authoring skill walks routes, names orphaned components, and writes .sightmap/. Review the diff before committing it. The skill checks each definition against the running app before adding it.
> Bootstrap a sightmap for this app: start a
> session, iterate the main routes, and name
> components until coverage is clean.Run sightmap validate and sightmap lint in CI. When the app changes, rerun iterate on the affected pages.