> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sightmap.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Sightmap Views: Routes, Specificity, and Scoping

> Define named screens with URL route patterns and deterministic specificity rules.

A view is a named screen in the app, identified by a URL route. Components and requests nested under a view apply only when that view is active.

```yaml theme={null}
version: 1

views:
  - name: FlightSearch
    route: /search
    description: Main search page with date and origin/destination pickers
    source: src/pages/FlightSearch.tsx
    components:
      - name: DepartureDatePicker
        selector: '[data-picker="departure"]'
    requests:
      - name: SearchFlights
        route: /api/flights/search
        method: POST
```

`name` and `route` are required. `url` gives the view a representative URL — a concrete address that resolves to it — which tooling uses to navigate to the view (coverage reporting, bulk capture, and probing); a file-level `url` supplies a default for views that omit their own. `description` records the view's purpose, and `source` links it to a source file. See [Schema reference](/reference/schema#view) for every field.

## Route matching

Routes use glob patterns against the URL pathname.

* `*` matches exactly one path segment: `/users/*` matches `/users/42`, not `/users/42/edit`.
* `**` matches any depth of segments: `/admin/**` matches `/admin`, `/admin/users`, and `/admin/users/42/edit`.
* Literal segments match themselves.
* Matching is case-sensitive. Query strings and fragments are ignored. Trailing slashes are normalized away before matching.

For requests, Express-style `:param` segments are normalized to `*`, so `/api/users/:id/orders` and `/api/users/*/orders` are equivalent. See [Requests](/spec/requests).

## Most specific wins

When more than one view route matches a URL, the route with the highest specificity score wins. Declaration order breaks ties between routes with equal scores.

Specificity is the sum of per-segment scores:

| Segment                | Score |
| ---------------------- | ----- |
| Literal (e.g. `users`) | 3     |
| `:param` (e.g. `:id`)  | 2     |
| `*` (single segment)   | 1     |
| `**` or empty          | 0     |

The root route `/` scores `1` — more specific than any wildcard-only pattern. When two routes score equal, the **first declared** view wins.

```yaml theme={null}
views:
  - name: UserProfile
    route: /users/*        # score 3+1 = 4
  - name: UserAdmin
    route: /users/admin    # score 3+3 = 6
```

`/users/admin` matches both routes and resolves to `UserAdmin`. `/users/42` matches only `UserProfile`.

<Note>
  This specificity rule applies only to views. Every matching request applies. See [Requests](/spec/requests#all-matches-apply).
</Note>

## Scoped vs global

Components and requests can live at the file root or nested inside a view.

* **Global** (file root): matched against every view.
* **View-scoped** (inside a view): matched only when that view is active.
* **Additive**: a view receives its scoped definitions and all globals. A view-scoped `$ref` subsumes a global component with the same name for that view.

```yaml theme={null}
components:
  - name: Navigation                # global — matched on every view
    selector: 'nav[data-component="Navigation"]'

views:
  - name: Dashboard
    route: /dashboard
    components:
      - name: DashboardLayout       # scoped — only on /dashboard
        selector: '[data-component="DashboardLayout"]'
```

<Warning>
  View names should be unique across the sightmap. Runtime behavior is implementation-defined when two files define the same view name. Conforming implementations SHOULD emit a warning.
</Warning>

## Dependencies

`source` names the view's primary file. List supplementary files, such as feature-specific hooks, stores, and CSS modules, under `dependencies`. Reverse-lookup tools can then associate changes to those files with the view:

```yaml theme={null}
views:
  - name: FlightSearch
    route: /search
    source: src/pages/FlightSearch.tsx
    dependencies:
      - src/hooks/useFlightSearch.ts
      - src/stores/flightFilterStore.ts
```

`dependencies` is curation-time metadata. Each string is a project-root-anchored minimatch glob; prefix it with `!` to negate it. Runtime consumers MUST NOT add page-load cost based on this field. See the [schema reference](/reference/schema#dependencies) for usage rules and diagnostics.

## Next

[Components](/spec/components) covers selector strings, arrays, and nesting rules. [Requests](/spec/requests) covers method filters and route normalization.