@sightmap/react

@sightmap/react is the React adapter — runtime only. It ships a provider, a Vite plugin, and a runtime introspection hook. It is the bridge between a running React app and an agent that authors .sightmap/.

It does not generate .sightmap/ files. Curation is agent-driven through @sightmap/mcp or the Claude Code plugin, reconciled against the live runtime snapshot this package exposes.

Install

pnpm add @sightmap/react @sightmap/sightmap

@sightmap/sightmap is a peer dep — installed alongside.

What it ships

Three entry points:

Import	What it gives you
`@sightmap/react`	`<SightmapProvider>` — loads the merged sightmap and installs the runtime hooks on `window.__sightmap__` (bippy `.snapshot()`) and `window.__SIGHTMAP__` (agent introspection).
`@sightmap/react/vite`	The Vite plugin — serves `/__sightmap__/snapshot.json` in dev with a live fiber-tree snapshot the agent can fetch.
`@sightmap/react/runtime-types`	TypeScript types for the runtime snapshot — `SightmapSnapshot`, `CandidateSelector`, `SelectorSource`.

No CLI. No bin entry. The package is purely a runtime.

Mount the provider

import { SightmapProvider } from "@sightmap/react";

export function App() {
  return (
    <SightmapProvider runtimeIntrospection="dev">
      <YourApp />
    </SightmapProvider>
  );
}

The provider:

Loads the merged sightmap from /__sightmap__/sightmap.json in dev (or a static /sightmap.json in prod).
Installs two browser-global hooks:
- window.__sightmap__.snapshot() — bippy-backed fiber-tree snapshot. This is what sightmap_runtime_snapshot reads through the Vite plugin endpoint.
- window.__SIGHTMAP__ — the agent introspection surface: getCurrentView(), match(req), walkTree(opts), inspectAt(x, y), findByDataSightmap(name), plus version() for SDK + spec versions.

runtimeIntrospection accepts three values:

"dev" (default) — installs the hook in development only.
"enabled" — installs the hook in every build, including production.
"off" — never install.

If you ran sightmap init (see @sightmap/sightmap), the provider was wrapped around your app entry by codemod — no manual mounting needed.

Vite plugin

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { sightmap } from "@sightmap/react/vite";

export default defineConfig({
  plugins: [react(), sightmap()],
});

The plugin registers two dev-server endpoints:

GET /__sightmap__/sightmap.json — the merged corpus from .sightmap/, served to the provider.
POST/GET /__sightmap__/snapshot.json — the live runtime snapshot. The provider POSTs the current fiber-tree (via bippy); the agent fetches it via sightmap_runtime_snapshot to discover routes, components, and selector candidates.

The plugin never writes to .sightmap/. Authorship is agent-driven.

`data-sightmap` attributes

data-sightmap is the most stable selector signal the runtime can pick up. When the fiber walker proposes a selector for a component, it ranks candidates:

data-sightmap > data-testid > ARIA roles + names > semantic tags > element ids

<button data-sightmap="LoginButton" onClick={signIn}>
  Sign in
</button>

If no stable candidate exists for a component the agent wants to track, the bootstrap flow will propose adding data-sightmap to source — that’s the agent’s path to selector stability when the JSX doesn’t already provide one.

How `.sightmap/` gets populated

Through an agent, against the live runtime. The canonical loop:

sightmap init scaffolds an empty .sightmap/app.yaml and codemods the provider into your app entry.
Start your dev server. The Vite plugin begins serving the live snapshot.
Run the bootstrap skill (Claude Code plugin) or call the MCP proposal tools directly. The agent walks routes, fetches sightmap_runtime_snapshot, proposes views and components with sightmap_propose_view / sightmap_propose_component, then commits the batch with sightmap_commit_proposals.

End to end in the quickstart.

Drift discovery

There is no gen --check equivalent — by design. .sightmap/ is curated authority, not a generated artifact, so static source-vs-yaml drift detection would require re-introducing the framework-shape AST adapters that v0.6 deleted.

Drift discovery happens at agent-driven moments:

Re-run the bootstrap skill. Existing entries are preserved; new routes and components surface as proposals.
/sightmap:reflect (Claude Code plugin) nudges when source files containing data-sightmap markers have been edited.
The PostToolUse audit hook surfaces cross-file inconsistencies after any MCP write to .sightmap/.

For corpus-level checks (schema, key ordering, cross-file references, duplicates), run sightmap check — it validates .sightmap/ against itself, not against React source.