@sightmap/react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fullstory, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# @sightmap/react
+
+React framework adapter for the [Sightmap](https://sightmap.org) spec.
+
+Mount one provider; an agent does the rest.
+
+## Install
+
+```bash
+pnpm add @sightmap/react @sightmap/sightmap
+```
+
+`@sightmap/sightmap` is a peer dep — installed alongside.
+
+## Use
+
+### 1. Bootstrap your `.sightmap/` from source
+
+```bash
+# scan your react-router 7 routes + data-sightmap props
+# and scaffold .sightmap/<feature>.yaml files
+pnpm sightmap-react gen
+```
+
+`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.
+
+#### First run
+
+Running `sightmap-react gen` against a project with no `.sightmap/` directory does three things:
+
+1. AST-scans your source for `data-sightmap` attributes and reads your React Router config to discover routes.
+2. Writes per-feature YAML files under `.sightmap/` (one file per feature group of routes), each seeded with:
+   - **Structural fields** the codegen owns: view name, route pattern, component selectors.
+   - **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.
+3. Prints a summary listing the views written, components linked, and the suggested first-edit targets.
+
+Re-running `gen` is idempotent: structural fields refresh from source, agent-authored fields are preserved, and the TODO scaffolding is **not** re-emitted into files that already exist (per the codegen spec in `docs/superpowers/specs/2026-05-08-react-sdk-bootstrap-codegen.md`).
+
+Two-minute walkthrough:
+
+```bash
+# In a fresh RR7 project root:
+npx sightmap-react gen
+# → wrote N file(s) (first run on empty .sightmap/)
+# → Views (N total)
+# →   views: Login, Dashboard, ...
+# → Next steps — open these files and replace the TODO blocks with real values:
+# →   - .sightmap/login.yaml
+# →   - .sightmap/dashboard.yaml
+# → Run /sightmap:audit (Claude Code plugin) to surface missing memory and broken selectors.
+
+# Open the first suggested file. Replace the commented TODO blocks with real values:
+$EDITOR .sightmap/login.yaml
+
+# Re-run any time you change routes or add data-sightmap attributes:
+npx sightmap-react gen
+# → sightmap: up to date     (or a list of structural changes only)
+```
+
+#### `--live <url>` (optional)
+
+If you have `sightmap-react`'s dev middleware running at `http://localhost:5173/__sightmap__/sightmap.json`, pass `--live <url>` to additionally fetch the runtime snapshot. Views present at runtime but not discovered by the static AST scan are surfaced as `react.live-only-view` info diagnostics — `gen` does not auto-emit YAML for them; the curator hand-authors a file per the diagnostic's hint.
+
+The static path is the source of truth for codegen. `--live` is a discovery aid, not a parallel write path.
+
+### 2. Add the Vite dev plugin (optional but recommended)
+
+```ts
+// 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(),
+  ],
+});
+```
+
+The plugin registers a `/__sightmap__/sightmap.json` endpoint in dev so the runtime provider can fetch the merged sightmap. It does **not** write to `.sightmap/` — generation is explicit (`sightmap-react gen`).
+
+### 3. Mount the provider
+
+```tsx
+// app root
+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 `window.__SIGHTMAP__` for an agent to introspect (dev by default; opt-in for prod).
+
+### 4. Let an agent curate
+
+The agent (Subtext, Claude Code, Playwright MCP, etc.) inspects the running app via `window.__SIGHTMAP__` and writes `data-sightmap="..."` props into source where it needs stable selectors. Re-run `sightmap-react gen` to refresh the structural skeleton; the agent's `memory`, intent, and request annotations survive untouched.
+
+### 5. The rest of the CLI
+
+```bash
+# rerun whenever routes or data-sightmap props change
+sightmap-react gen
+
+# CI gate: dry-run; exit 1 if .sightmap/ is out of date
+sightmap-react gen --check
+
+# print a unified diff of would-be changes; writes nothing
+sightmap-react gen --diff
+
+# validate; warns about routes with no view, drift between source and YAML
+sightmap-react validate
+```
+
+Run `sightmap-react gen --check` in CI to fail the build when routes or
+`data-sightmap` props have drifted from the committed `.sightmap/` files.
+Run `sightmap-react gen` to fix.
+
+## File layout
+
+```
+.sightmap/
+  login.yaml           # plugin-scaffolded, agent-curated: view + components for /login
+  dashboard.yaml       # plugin-scaffolded, agent-curated
+  shared.yaml          # plugin-scaffolded: cross-route components
+  extras.yaml          # agent-only: non-derivable additions
+```
+
+Plugin owns: `name`, `route`, `selector`, `children`. Agent owns: `memory`, intent, requests, and any unknown field. Smart-merge preserves agent fields, comments, and ordering.
+
+## What's in v0.1
+
+- `<SightmapProvider>` + `window.__SIGHTMAP__` (read-only basics: `walkTree`, `inspectAt`, `getCurrentView`, `getSightmap`, `match`, `findByDataSightmap`, `version`)
+- Vite dev plugin (registers `/__sightmap__/sightmap.json` middleware)
+- React-router 7 declarative-mode adapter (driven from the CLI)
+- React-router 7 framework-mode adapter (`app/routes.ts` programmatic config)
+- Smart-merge YAML writer (idempotent; preserves agent fields)
+- CLI: `gen`, `validate`
+
+### Selecting an adapter
+
+`sightmap-react gen --router <name>` accepts:
+
+- `react-router-7` — declarative `<Routes><Route />` JSX (default).
+- `react-router-7-framework` — programmatic `app/routes.ts` config using `route`, `index`, `layout`, `prefix` from `@react-router/dev/routes`.
+- `auto` — picks framework mode if `app/routes.ts` exists, else declarative.
+
+Framework-mode v0.1 limitations: hardcoded `app/` directory (custom `appDirectory` from `react-router.config.ts` is not yet honored), top-level helper identifiers only (no namespaced/aliased calls), string-literal arguments only, and no support for `flatRoutes()` filesystem-based routing.
+
+## Coming in v0.2
+
+- React-router 7 data-mode adapter
+- `flatRoutes()` filesystem-based discovery for framework mode
+- Adapters for Next.js, Remix, TanStack Router
+- Curation helpers in the runtime API: `suggestSelector`, `verifySelector`, `diff`
+- CLI: `diff`
+
+## Design
+
+- 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)
+- Bootstrap-only codegen pivot: [docs/superpowers/specs/2026-05-08-react-sdk-bootstrap-codegen.md](https://github.com/sightmap/sightmap-js/blob/main/docs/superpowers/specs/2026-05-08-react-sdk-bootstrap-codegen.md)
+
+## License
+
+MIT

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node