Skip to content
Sightmap

The Spec

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 are the readable walk-through. The exhaustive field-by-field contract lives in the Schema reference and is mirrored verbatim from the canonical schema.

What’s in a sightmap

Section titled “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

Section titled “Top-level fields”

Every file begins with version: 1. All other top-level keys are optional.

version: 1
memory:      # string[] — file-level notes
views:       # View[]
components:  # Component[] — global, matched on every view
requests:    # Request[] — global, matched on every view

components and requests at the file root are global — matched against every view. Nest them inside a view to scope. Scoped definitions are additive with globals. See Components and Requests for the matching rules.

Two versioning axes

Section titled “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 bumps only on breaking changes to the format.
  • The project semver (in package.json) describes how settled stream 1 is. It is currently 0.1.0 — pre-1.0, so we may tighten or clarify the spec in place. After 1.0.0 the rules in VERSIONING.md 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

Section titled “A small example”
.sightmap/home.yaml
version: 1


views:
  - name: Home
    route: /
    components:
      - name: SearchBox
        selector: '[data-component="SearchBox"]'

That is the smallest file that does anything useful. Everything else in this section is layered onto this shape: more views, nested components, glob routes, request definitions, and memory entries.

Next

Section titled “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.