@sightmap/react 0.8.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -112
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# @sightmap/react
|
|
2
2
|
|
|
3
|
-
React
|
|
3
|
+
React runtime for the [Sightmap](https://sightmap.org) spec.
|
|
4
4
|
|
|
5
|
-
Mount one provider; an agent does the rest
|
|
5
|
+
Mount one provider; an agent does the rest — it introspects the live React
|
|
6
|
+
tree via [bippy](https://github.com/aidenybai/bippy) and curates the project's
|
|
7
|
+
`.sightmap/` YAML inventory through the [`@sightmap/mcp`](../mcp) tools.
|
|
6
8
|
|
|
7
9
|
## Install
|
|
8
10
|
|
|
@@ -10,60 +12,45 @@ Mount one provider; an agent does the rest.
|
|
|
10
12
|
pnpm add @sightmap/react @sightmap/sightmap
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
`@sightmap/sightmap` is a peer dep —
|
|
15
|
+
`@sightmap/sightmap` is a peer dep — install it alongside.
|
|
14
16
|
|
|
15
17
|
## Use
|
|
16
18
|
|
|
17
|
-
### 1.
|
|
19
|
+
### 1. Mount the provider
|
|
18
20
|
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
pnpm sightmap-react gen
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
`gen` walks your router config, finds any `data-sightmap="..."` props in source, and writes feature-scoped YAML files to `.sightmap/` — one per top-level route. Re-run any time routes or selectors change; agent-authored fields (`memory`, intent, requests) are preserved.
|
|
26
|
-
|
|
27
|
-
#### First run
|
|
28
|
-
|
|
29
|
-
Running `sightmap-react gen` against a project with no `.sightmap/` directory does three things:
|
|
30
|
-
|
|
31
|
-
1. AST-scans your source for `data-sightmap` attributes and reads your React Router config to discover routes.
|
|
32
|
-
2. Writes per-feature YAML files under `.sightmap/` (one file per feature group of routes), each seeded with:
|
|
33
|
-
- **Structural fields** the codegen owns: view name, route pattern, component selectors.
|
|
34
|
-
- **Commented TODO blocks** for the agent-authored fields the codegen does NOT own: `memory`, `intent`, `requests`. These are YAML comments — the file parses cleanly until you uncomment and fill them in.
|
|
35
|
-
3. Prints a summary listing the views written, components linked, and the suggested first-edit targets.
|
|
21
|
+
```tsx
|
|
22
|
+
// app entry — must import BEFORE react-dom does any work.
|
|
23
|
+
import { SightmapProvider } from "@sightmap/react";
|
|
36
24
|
|
|
37
|
-
|
|
25
|
+
export function App() {
|
|
26
|
+
return (
|
|
27
|
+
<SightmapProvider runtimeIntrospection="dev">
|
|
28
|
+
<YourApp />
|
|
29
|
+
</SightmapProvider>
|
|
30
|
+
);
|
|
31
|
+
}
|
|
32
|
+
```
|
|
38
33
|
|
|
39
|
-
|
|
34
|
+
Importing `@sightmap/react` installs a [bippy](https://github.com/aidenybai/bippy)
|
|
35
|
+
fiber-tree hook and exposes:
|
|
40
36
|
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
npx sightmap-react gen
|
|
44
|
-
# → wrote N file(s) (first run on empty .sightmap/)
|
|
45
|
-
# → Views (N total)
|
|
46
|
-
# → views: Login, Dashboard, ...
|
|
47
|
-
# → Next steps — open these files and replace the TODO blocks with real values:
|
|
48
|
-
# → - .sightmap/login.yaml
|
|
49
|
-
# → - .sightmap/dashboard.yaml
|
|
50
|
-
# → Run /sightmap:audit (Claude Code plugin) to surface missing memory and broken selectors.
|
|
51
|
-
|
|
52
|
-
# Open the first suggested file. Replace the commented TODO blocks with real values:
|
|
53
|
-
$EDITOR .sightmap/login.yaml
|
|
54
|
-
|
|
55
|
-
# Re-run any time you change routes or add data-sightmap attributes:
|
|
56
|
-
npx sightmap-react gen
|
|
57
|
-
# → sightmap: up to date (or a list of structural changes only)
|
|
37
|
+
```ts
|
|
38
|
+
window.__sightmap__ = { snapshot(): SightmapSnapshot };
|
|
58
39
|
```
|
|
59
40
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
41
|
+
The snapshot returns the live React fiber tree as a flat list of
|
|
42
|
+
`ComponentNode`s plus a ranked `CandidateSelector[]` per node (existing
|
|
43
|
+
`data-sightmap` > test-id > `role`+`aria-label` > id > synthesized) and a
|
|
44
|
+
parallel list of `data-sightmap` markers and unmarked-but-named candidates.
|
|
45
|
+
An agent (Subtext, Claude Code, a Playwright-driven MCP) reads it to plan
|
|
46
|
+
selectors and to decide which components deserve a `data-sightmap` marker.
|
|
63
47
|
|
|
64
|
-
|
|
48
|
+
`runtimeIntrospection` modes:
|
|
49
|
+
- `"dev"` (default): hook installs only when `process.env.NODE_ENV !== "production"`.
|
|
50
|
+
- `"enabled"`: install always — opt-in for prod when you want agents to drive a live app.
|
|
51
|
+
- `"off"`: do not install the hook.
|
|
65
52
|
|
|
66
|
-
### 2. Add the Vite
|
|
53
|
+
### 2. Add the Vite plugin (optional but recommended)
|
|
67
54
|
|
|
68
55
|
```ts
|
|
69
56
|
// vite.config.ts
|
|
@@ -74,99 +61,88 @@ import { sightmap } from "@sightmap/react/vite";
|
|
|
74
61
|
export default defineConfig({
|
|
75
62
|
plugins: [
|
|
76
63
|
react(),
|
|
77
|
-
sightmap(),
|
|
64
|
+
sightmap({ autoInject: true }),
|
|
78
65
|
],
|
|
79
66
|
});
|
|
80
67
|
```
|
|
81
68
|
|
|
82
|
-
The plugin
|
|
69
|
+
The plugin does two things:
|
|
83
70
|
|
|
84
|
-
|
|
71
|
+
1. Registers a dev middleware at `/__sightmap__/snapshot.json`. The browser
|
|
72
|
+
POSTs a snapshot to it during render; the MCP server's
|
|
73
|
+
`sightmap_runtime_snapshot` tool (`kind: "endpoint"`) GETs it back. This
|
|
74
|
+
is the lowest-friction way to feed snapshots to an out-of-process agent
|
|
75
|
+
that isn't driving the browser.
|
|
76
|
+
2. With `autoInject: true`, prepends `import "@sightmap/react";` to your app
|
|
77
|
+
entry (`src/main.tsx`, `app/entry.client.tsx`, etc.) so the bippy hook
|
|
78
|
+
installs before React-DOM imports. If you'd rather wire it manually, omit
|
|
79
|
+
the option and import `@sightmap/react` at the top of your entry file.
|
|
85
80
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
import { SightmapProvider } from "@sightmap/react";
|
|
81
|
+
The plugin does **not** write to `.sightmap/` — curation is agent-driven via
|
|
82
|
+
`@sightmap/mcp` and the [`sightmap` plugin](https://github.com/sightmap/plugin).
|
|
89
83
|
|
|
90
|
-
|
|
91
|
-
return (
|
|
92
|
-
<SightmapProvider runtimeIntrospection="dev">
|
|
93
|
-
<YourApp />
|
|
94
|
-
</SightmapProvider>
|
|
95
|
-
);
|
|
96
|
-
}
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
The provider:
|
|
100
|
-
- Loads the merged sightmap (from `/__sightmap__/sightmap.json` in dev, or a static `/sightmap.json` in prod).
|
|
101
|
-
- Installs `window.__SIGHTMAP__` for an agent to introspect (dev by default; opt-in for prod).
|
|
102
|
-
|
|
103
|
-
### 4. Let an agent curate
|
|
84
|
+
### 3. Let an agent curate
|
|
104
85
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
### 5. The rest of the CLI
|
|
86
|
+
After install, the fastest path is:
|
|
108
87
|
|
|
109
88
|
```bash
|
|
110
|
-
#
|
|
111
|
-
sightmap
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
sightmap-react gen --check
|
|
89
|
+
# In your project root, with .sightmap/ scaffolded by `sightmap init`:
|
|
90
|
+
# (run inside Claude Code / Cursor / Codex / opencode with the sightmap plugin installed)
|
|
91
|
+
/sightmap:bootstrap
|
|
92
|
+
```
|
|
115
93
|
|
|
116
|
-
|
|
117
|
-
sightmap
|
|
94
|
+
`/sightmap:bootstrap` walks the live app, reads the snapshot, and proposes a
|
|
95
|
+
starter `.sightmap/` inventory — view files with routes, components, ranked
|
|
96
|
+
selectors, and seed `description`/`intent`/`memory`. You confirm and the
|
|
97
|
+
plugin writes the files via the MCP curation tools.
|
|
118
98
|
|
|
119
|
-
|
|
120
|
-
sightmap-
|
|
121
|
-
|
|
99
|
+
Subsequent loops:
|
|
100
|
+
- `/sightmap:audit` — six-dimension lint of the inventory.
|
|
101
|
+
- `/sightmap:fix` — applies audit-driven patches (confirm-first; `--apply` to auto-apply).
|
|
102
|
+
- `/sightmap:reflect` — at end of turn, folds the agent's just-made source edits back into intent/memory.
|
|
122
103
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
104
|
+
You can also add `data-sightmap="ComponentName"` props to JSX wherever you
|
|
105
|
+
want stable agent-facing selectors. They bubble through the snapshot's
|
|
106
|
+
`markers` list and rank highest in selector ranking.
|
|
126
107
|
|
|
127
108
|
## File layout
|
|
128
109
|
|
|
129
110
|
```
|
|
130
111
|
.sightmap/
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
112
|
+
app.yaml # corpus-level metadata
|
|
113
|
+
login.yaml # one view per top-level route
|
|
114
|
+
dashboard.yaml
|
|
115
|
+
shared.yaml # cross-route components
|
|
135
116
|
```
|
|
136
117
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
- Vite dev plugin (registers `/__sightmap__/sightmap.json` middleware)
|
|
143
|
-
- React-router 7 declarative-mode adapter (driven from the CLI)
|
|
144
|
-
- React-router 7 framework-mode adapter (`app/routes.ts` programmatic config)
|
|
145
|
-
- Smart-merge YAML writer (idempotent; preserves agent fields)
|
|
146
|
-
- CLI: `gen`, `validate`
|
|
147
|
-
|
|
148
|
-
### Selecting an adapter
|
|
118
|
+
The agent owns every field — structural (`name`, `route`, `components`,
|
|
119
|
+
per-component `selector`/`memory`) and semantic (`description`, `intent`,
|
|
120
|
+
view-level `memory`). The hooks shipped by the sightmap plugin run
|
|
121
|
+
`sightmap check` and `sightmap audit` after each write to keep curation
|
|
122
|
+
honest.
|
|
149
123
|
|
|
150
|
-
|
|
124
|
+
## What's exported
|
|
151
125
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
126
|
+
```ts
|
|
127
|
+
// public runtime + types
|
|
128
|
+
import {
|
|
129
|
+
SightmapProvider,
|
|
130
|
+
useSightmap,
|
|
131
|
+
sightmap as sightmapVitePlugin, // also re-exported from @sightmap/react/vite
|
|
132
|
+
type SightmapSnapshot,
|
|
133
|
+
type SightmapMarker,
|
|
134
|
+
type UnmarkedCandidate,
|
|
135
|
+
type ComponentNode,
|
|
136
|
+
type CandidateSelector,
|
|
137
|
+
type SelectorStability,
|
|
138
|
+
type SelectorSource,
|
|
139
|
+
} from "@sightmap/react";
|
|
140
|
+
```
|
|
165
141
|
|
|
166
142
|
## Design
|
|
167
143
|
|
|
168
144
|
- v0 design: [docs/superpowers/specs/2026-04-26-react-sdk-design.md](https://github.com/sightmap/sightmap-js/blob/main/docs/superpowers/specs/2026-04-26-react-sdk-design.md)
|
|
169
|
-
-
|
|
145
|
+
- Codegen-to-runtime pivot: [docs/superpowers/plans/2026-05-13-codegen-to-runtime-agent-pivot.md](https://github.com/sightmap/sightmap-js/blob/main/docs/superpowers/plans/2026-05-13-codegen-to-runtime-agent-pivot.md)
|
|
170
146
|
|
|
171
147
|
## License
|
|
172
148
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sightmap/react",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"description": "React runtime for the Sightmap spec — SightmapProvider, runtime introspection hook, and Vite plugin.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
"typescript": "~5.7.3",
|
|
61
61
|
"vite": "^7.0.0",
|
|
62
62
|
"vitest": "^3.0.0",
|
|
63
|
-
"@sightmap/sightmap": "^0.
|
|
63
|
+
"@sightmap/sightmap": "^0.10.0"
|
|
64
64
|
},
|
|
65
65
|
"scripts": {
|
|
66
66
|
"build": "tsup",
|