@sightmap/react

React runtime for the Sightmap spec.

Mount one provider; an agent does the rest — it introspects the live React tree via bippy and curates the project's .sightmap/ YAML inventory through the @sightmap/mcp tools.

Install

pnpm add @sightmap/react @sightmap/sightmap

@sightmap/sightmap is a peer dep — install it alongside.

Use

1. Mount the provider

// app entry — must import BEFORE react-dom does any work.
import { SightmapProvider } from "@sightmap/react";

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

Importing @sightmap/react installs a bippy fiber-tree hook and exposes:

window.__sightmap__ = { snapshot(): SightmapSnapshot };

The snapshot returns the live React fiber tree as a flat list of ComponentNodes plus a ranked CandidateSelector[] per node (existing data-sightmap > test-id > role+aria-label > id > synthesized) and a parallel list of data-sightmap markers and unmarked-but-named candidates. An agent (Subtext, Claude Code, a Playwright-driven MCP) reads it to plan selectors and to decide which components deserve a data-sightmap marker.

runtimeIntrospection modes:

• "dev" (default): hook installs only when process.env.NODE_ENV !== "production".
• "enabled": install always — opt-in for prod when you want agents to drive a live app.
• "off": do not install the hook.

2. Add the Vite plugin (optional but recommended)

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

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

The plugin does two things:

1. Registers a dev middleware at /__sightmap__/snapshot.json. The browser POSTs a snapshot to it during render; the MCP server's sightmap_runtime_snapshot tool (kind: "endpoint") GETs it back. This is the lowest-friction way to feed snapshots to an out-of-process agent that isn't driving the browser.
2. With autoInject: true, prepends import "@sightmap/react"; to your app entry (src/main.tsx, app/entry.client.tsx, etc.) so the bippy hook installs before React-DOM imports. If you'd rather wire it manually, omit the option and import @sightmap/react at the top of your entry file.

The plugin does not write to .sightmap/ — curation is agent-driven via @sightmap/mcp and the sightmap plugin.

3. Let an agent curate

After install, the fastest path is:

# In your project root, with .sightmap/ scaffolded by `sightmap init`:
# (run inside Claude Code / Cursor / Codex / opencode with the sightmap plugin installed)
/sightmap:bootstrap

/sightmap:bootstrap walks the live app, reads the snapshot, and proposes a starter .sightmap/ inventory — view files with routes, components, ranked selectors, and seed description/intent/memory. You confirm and the plugin writes the files via the MCP curation tools.

Subsequent loops:

• /sightmap:audit — six-dimension lint of the inventory.
• /sightmap:fix — applies audit-driven patches (confirm-first; --apply to auto-apply).
• /sightmap:reflect — at end of turn, folds the agent's just-made source edits back into intent/memory.

You can also add data-sightmap="ComponentName" props to JSX wherever you want stable agent-facing selectors. They bubble through the snapshot's markers list and rank highest in selector ranking.

File layout

.sightmap/
  app.yaml           # corpus-level metadata
  login.yaml         # one view per top-level route
  dashboard.yaml
  shared.yaml        # cross-route components

The agent owns every field — structural (name, route, components, per-component selector/memory) and semantic (description, intent, view-level memory). The hooks shipped by the sightmap plugin run sightmap check and sightmap audit after each write to keep curation honest.

What's exported

// public runtime + types
import {
  SightmapProvider,
  useSightmap,
  sightmap as sightmapVitePlugin,    // also re-exported from @sightmap/react/vite
  type SightmapSnapshot,
  type SightmapMarker,
  type UnmarkedCandidate,
  type ComponentNode,
  type CandidateSelector,
  type SelectorStability,
  type SelectorSource,
} from "@sightmap/react";

Design

• v0 design: docs/superpowers/specs/2026-04-26-react-sdk-design.md
• Codegen-to-runtime pivot: docs/superpowers/plans/2026-05-13-codegen-to-runtime-agent-pivot.md

License

MIT