Skip to main content
A sightmap is a directory of YAML files at the root of a project, under .sightmap/. It describes the app’s views, components, and requests, with optional memory entries that carry notes agents can use at runtime. These pages explain the format. The Schema reference provides the field-by-field contract and is generated from the canonical spec.

​
What’s in a sightmap

Four kinds of definitions, all optional:

Views

Named screens identified by URL routes.

Components

Named DOM subtrees identified by CSS selectors.

Requests

Named API endpoints identified by route patterns.

Memory

Short freeform notes attached to any of the above.
Every *.yaml and *.yml file under .sightmap/ is discovered recursively and merged. The directory layout is for authors; it has no semantic meaning.

​
Top-level fields

Every file begins with version: 1. All other top-level keys are optional.
components and requests at the file root are global and match against every view. Nest them inside a view to limit them to that view. Scoped definitions are additive with globals, except that a view-scoped $ref subsumes a global component with the same name. Entries in any components: array may be $ref references to shared definitions. See Components and Requests for the matching rules.

​
Two versioning axes

The spec and the project that publishes it move independently.
  • The spec stream is the integer in the YAML version: field. It is currently 1 and changes only when the format has a breaking change.
  • The project semver describes how settled stream 1 is. It is currently 0.1.0. Before 1.0.0, the spec may be tightened or clarified in place. Project releases are published on GitHub Releases. After 1.0.0, the rules in Versioning become commitments.
We aim to keep the spec at stream 1 for a long time. A version: 2 would mean a new spec/v2/ directory and a real, accepted breaking change.

​
A small example

.sightmap/home.yaml
This file defines one view and one view-scoped component. Other files can add views, nested components, glob routes, requests, and memory entries.
Quote attribute selectors so YAML parses them as strings: selector: '[data-component="X"]'. Unquoted, the brackets are read as a YAML flow sequence and the entry fails validation.

​
Next

Start with Views for routes and view-level structure, then Components for selector semantics. The full schema reference, including every field on every type, is in Schema reference.