Skip to content
Sightmap

Changelog

What’s changed across the Sightmap spec and SDKs. Per-package canonical changelogs live alongside the source — links below each entry. For day-to-day API churn, watch GitHub releases on the SDK repo.

v0.12 — $ref component references

Section titled “v0.12 — $ref component references”

May 21, 2026

Component definitions can now be reused by reference. Any entry in a components: array — at file root, within a view, or under children: — may be a single-key { $ref: ComponentName } object that expands inline to a deep copy of the named component before matching. Names resolve against a project-wide registry built from the root-level components: of every loaded file. Definition lives in one place; a view’s components: becomes a compact, machine-readable manifest of which globals it expects to see — a signal drift-detection tooling can act on.

  • @sightmap/sightmap 0.12.0 — Schema accepts { $ref: Name } entries in any components: array. Two-pass loader: build the registry from root-level components: across all files, then expand $ref entries (deep copy via structuredClone) with cycle detection. check adds two error-severity diagnostics: ref-unresolved (unknown name) and ref-circular (self-referential chain). Dedup at match time: when a view attests a name by $ref and the same name is also a file-root global, the view-scoped expansion subsumes the global — the component appears once in the resolved output. The expanded clone carries the registry definition’s source and dependencies verbatim; a $ref is an attestation of where a component appears, not a redefinition. See Component references and SEP-0002.
  • All packages 0.12.0 — Monorepo lockstep. @sightmap/mcp, @sightmap/react, @sightmap/playwright, @sightmap/agent-browser re-vendor the schema and pick up $ref expansion via the shared kernel; no per-package surface changes beyond that.

Adopter pin. Adding $ref entries to a .sightmap/ corpus requires @sightmap/sightmap@>=0.12.0. Hosts (plugin consumers) MUST require the same. Older SDKs reject documents with $ref as schema-invalid (per the additionalProperties: false policy in spec/VERSIONING.md).

Cross-SEP interaction. Expansion uses structuredClone, so SEP-0001’s dependencies[] field is preserved transparently through $ref expansion. Both SEPs compose without special-casing.

Canonical sources:

v0.11 — dependencies[] field on views and components

Section titled “v0.11 — dependencies[] field on views and components”

May 21, 2026

Views and components gain an optional dependencies: string[] field — minimatch globs naming supplementary files (hooks, stores, style modules, helper utilities) whose changes should trigger re-curation of the entry. source remains the canonical primary binding; dependencies[] adds the secondary file-set without forcing every supplementary file into its own component entry. Purely curation-time — runtime adapters read DOM/fiber state, not source files.

  • @sightmap/sightmap 0.11.0 — Re-vendors the schema with dependencies on view and component subschemas. explain --by path <file> now consults dependencies[] globs in addition to exact source matches; hits gain a matchedBy provenance field in --json output ("source" vs "dependencies"). match --json adds a views[] array (additive alongside the existing singular view); ResolvedView and ResolvedComponent surface the optional dependencies field. check adds three diagnostics — dependencies.self-redundant (warning), dependencies.overlaps-entry (warning), and a narrowed unknown-source (warning) for zero-match globs. fmt canonicalizes dependencies[] by lexicographic sort + deduplication and positions the key after source. See Dependencies and SEP-0001.
  • All packages 0.11.0 — Monorepo lockstep across @sightmap/mcp, @sightmap/react, @sightmap/playwright, @sightmap/agent-browser. Schema re-vendor; no per-package surface changes.

Adopter pin. Adding dependencies to a .sightmap/ corpus requires @sightmap/sightmap@>=0.11.0. Hosts MUST require the same. Older SDKs reject documents with dependencies as schema-invalid.

Canonical sources:

v0.9 — Browser-driven snapshot capture

Section titled “v0.9 — Browser-driven snapshot capture”

May 13, 2026

sightmap_runtime_snapshot gains two new capture modes alongside the existing endpoint mode. The new browser mode drives a live browser through the @playwright/mcp passthrough — pre-navigate addInitScript installs the bippy hook before React’s first commit, so the agent can capture snapshots from any React app, including non-Vite projects, apps without @sightmap/react, and static first-paint apps. The new literal mode accepts pre-captured snapshots from any source (Subtext’s live-eval-script, devtools paste, CI capture).

  • @sightmap/mcp 0.9.0 — sightmap_runtime_snapshot accepts three source.kind discriminants:
    • { kind: "endpoint", url } — HTTP GET against the Vite plugin endpoint (existing).
    • { kind: "browser", url, routes?, inject? } — drives @playwright/mcp (requires @playwright/mcp >= 0.0.75). The bippy IIFE + bootstrap pre-navigate-inject via PLAYWRIGHT_MCP_INIT_SCRIPT; post-navigate browser_evaluate remains as a fallback.
    • { kind: "literal", snapshot } — accepts and validates a pre-captured snapshot from any source.
  • All packages 0.9.0 — Test/docs follow-up to the v0.8 pivot. @sightmap/mcp adds server-level callTool() integration coverage for the 7 pivot-era curation tools. @sightmap/react closes SightmapProvider and Vite-plugin coverage gaps. @sightmap/sightmap README scrubbed of the removed --no-codegen flag and codegen-in-init paragraph. Six pre-pivot specs/plans get a SUPERSEDED banner pointing at the 2026-05-13 pivot doc. No runtime behavior changes outside @sightmap/mcp.

Canonical sources:

v0.8 — Codegen retirement, runtime introspection, agent-led curation

Section titled “v0.8 — Codegen retirement, runtime introspection, agent-led curation”

May 13, 2026

The architectural pivot. sightmap-react gen and the static AST adapters retire. .sightmap/ becomes the curated authority — agent-authored against a live runtime, not derived from source. The bridge is <SightmapProvider>’s bippy-backed fiber-tree, exposed via the Vite plugin and consumed by MCP. The curation surface widens to match: full view CRUD, plus a proposal staging family that lets agents batch observations during exploration and commit them atomically. There is no gen --check replacement, by design — static drift detection would require re-introducing the adapters we just removed.

  • @sightmap/react 0.8.0 — Runtime introspection lands; static codegen retires. <SightmapProvider> installs a bippy-backed hook at module init, walks the live React fiber tree, and exposes window.__sightmap__.snapshot() (lowercase, used by the runtime snapshot endpoint) alongside window.__SIGHTMAP__ (uppercase, the agent introspection surface — getCurrentView, match, walkTree, inspectAt, findByDataSightmap). New Vite plugin endpoint /__sightmap__/snapshot.json caches POSTed snapshots and serves them on GET. New autoInject option on sightmap() prepends the runtime import to the app entry. Selector ranker: data-sightmap > data-testid > ARIA > semantic > id. Portal-aware fiber walker attributes host elements without bleeding through React portals. Removed: rr7DeclarativeAdapter, rr7FrameworkAdapter, the sightmap-react CLI (gen, validate), the orchestrator, smart-merge, and TODO scaffolding. See @sightmap/react.
  • @sightmap/sightmap 0.8.0 — sightmap init no longer runs codegen. The codegen invocation in runFreshFrameworkSetup is removed and the --no-codegen flag retires (no longer applies). The SightmapProvider codemod stays — the provider IS the runtime hook. init --manual now writes pre/post lint hooks into the project’s .claude/settings.json so agents get immediate feedback (sightmap check --json before view-YAML writes, sightmap audit --json after). Outro message redirects users to pnpm dev and /sightmap:bootstrap for population. See @sightmap/cli.
  • @sightmap/mcp 0.8.0 — Curation surface widens: sightmap_update_view accepts structural patches (name, route, components) in addition to semantic ones (backward-compatible). New sightmap_add_view and sightmap_delete_view complete view CRUD. New sightmap_runtime_snapshot fetches the live fiber-tree from the React Vite plugin endpoint. New proposal staging family: sightmap_propose_view, sightmap_propose_component, sightmap_review_proposals, sightmap_commit_proposals — lets agents annotate observations during exploration and batch them into atomic YAML writes. The codegen-owned partition framing (“Component/route/selector edits are NOT supported here”) is removed from tool descriptions: agents own the full corpus; the linter + hooks keep things on rails. See @sightmap/mcp.

Canonical sources:

v0.7.1 — Security hardening

Section titled “v0.7.1 — Security hardening”

May 13, 2026

Eleven Dependabot alerts cleared. Tar (path traversal, symlink poisoning, APFS race) and Vite path-traversal advisories resolved via dependency bumps. No published-surface change.

  • @sightmap/sightmap 0.7.1 — pacote ^18.0.6 → ^21.1.0, pulling tar 6.2.1 → 7.5.15 transitively. Pacote API surface (pacote.tarball.stream, pacote.manifest) unchanged across the 18→21 majors; affects the sightmap init plugin-tarball install path only. Workspace devDeps: vite ^5.4.0 → ^7.0.0 (vite 5.x has no back-ported fix), vitest ^2.1.9 → ^3.0.0 (required because vitest 2.x’s vite-node uses a vite-5-incompatible SSR transform).

Canonical sources:

v0.7 — @sightmap/agent-browser + matcher specificity

Section titled “v0.7 — @sightmap/agent-browser + matcher specificity”

May 13, 2026

A sightmap-aware wrapper for Vercel’s agent-browser CLI joins the playwright wrapper as a no-MCP path for shell-invocation agents. Route matching aligns with the lint rules: most-specific match wins, with declaration order as a tiebreak (was first-match-wins).

  • @sightmap/agent-browser 0.7.0 — New package. CLI wrapper around agent-browser with sightmap-aware snapshot, match, act, network commands plus passthrough. JSON-first parsing of agent-browser --json envelopes — cleaner than the text-framing parser the playwright wrapper uses. Works above any provider (Browserless, Browserbase, Kernel, AgentCore, BrowserUse) via -p <provider> flowing through passthrough at zero wrapper overhead. @sightmap/plugin separately gains a SessionStart hook that surfaces sightmap-agent-browser (and sightmap-playwright) when on PATH. See @sightmap/agent-browser.
  • @sightmap/sightmap 0.7.0 — Matcher switches from first-match-wins to most-specific-match-wins. resolveByUrl now scores every matching view via the new exported routeSpecificity helper (literal=3, :param=2, *=1, **/empty=0) and keeps the highest scorer; ties fall back to declaration order. The lint rule (route-shadowing) already assumed specificity semantics — the two halves of the package previously disagreed silently. Breaking for corpora where a wildcard view sorted alphabetically before a more specific static route — those calls (match("/install") etc.) previously returned the wildcard view and its memory/intent; they now return the specific view, as agents expect.
  • @sightmap/mcp 0.7.0, @sightmap/playwright 0.7.0, @sightmap/react 0.7.0 — Monorepo lockstep. sightmap_match and sightmap_check tool outputs change shape to reflect the new resolution; no source changes in the MCP package itself.

Canonical sources:

v0.6 — Engine extraction + @sightmap/playwright

Section titled “v0.6 — Engine extraction + @sightmap/playwright”

May 13, 2026

The enrichment kernel — snapshot enrichment, sightmap-aware act resolution, network-request annotation, in-page eval builder — moves from @sightmap/mcp into @sightmap/sightmap as a reusable engine. A new sibling package, @sightmap/playwright, wraps @playwright/cli with the same enriched commands as MCP, no protocol overhead.

  • @sightmap/sightmap 0.6.0 — New exports: enrichSnapshot, resolveSightmapAct, annotateNetworkRequests, buildInPageEvalFunction, plus types (EnrichedSnapshot, InPageSightmapMatch, BoundingRect, SightmapSnapshotComponent, ResolveSightmapActInput/Result, ParsedNetworkRequest, AnnotatedNetworkRequest). Same semantics as the prior MCP internals; now reusable for tool builders integrating sightmap into IDEs, CI checks, or custom workflows.
  • @sightmap/playwright 0.6.0 — New package. CLI wrapper around @playwright/cli with sightmap-aware snapshot, match, act, network commands plus passthrough. Same enrichment kernel as @sightmap/mcp. The no-MCP path for browser-driven introspection. See @sightmap/playwright.
  • @sightmap/mcp 0.6.0 — Internal refactor to consume the extracted engine. Public CLI and tool surface unchanged. --curate-only becomes the documented path for Subtext-style consumers driving their own browser.

Canonical sources:

v0.5 — Init UX polish + opt-in provider codemod

Section titled “v0.5 — Init UX polish + opt-in provider codemod”

May 12, 2026

The sightmap init provider-wrap step gains a three-way prompt — wrap, snippet, or skip — to reduce silent codemod failures across framework edge cases. Plus launcher detection, init-time smoke tests, and a marketplace install command fix.

  • @sightmap/sightmap 0.5.0 — sightmap init provider-codemod step is now opt-in via three-way prompt: Wrap automatically (current behavior), Show me the snippet to paste (per-framework template), or Skip. When the codemod can’t safely produce a wrap, init prints the framework-appropriate snippet inline instead of warning out. New renderProviderSnippet() helpers cover Vite/CRA, Next app/pages, React Router 7, and a generic fallback. Monorepo support: package-manager detection walks up parent directories for pnpm-lock.yaml, pnpm-workspace.yaml, yarn.lock.
  • @sightmap/sightmap 0.5.1 — Launcher detection: the MCP server entry in .mcp.json/.claude/settings.json was hardcoded to npx, which under Node 25 + npm 11 silently dies on stdin in pnpm workspaces. buildSightmapMcpServerDef now picks bunx / pnpm dlx / yarn dlx / npx -y per lockfile signals. New init-time smoke test spawns the configured MCP command and sends a JSON-RPC initialize to surface silent spawn failures with actionable warnings. New --no-smoke flag bypasses the check for CI / headless runs.
  • @sightmap/sightmap 0.5.2 — sightmap init plugin-flow command fix: prints /plugin install sightmap@sightmap (and the Codex equivalent), not the wrong sightmap@sightmap-marketplace suffix. The marketplace’s actual name in @sightmap/plugin’s .claude-plugin/marketplace.json is sightmap.

Canonical sources:

v0.4 — sightmap init (zero-to-one installer)

Section titled “v0.4 — sightmap init (zero-to-one installer)”

May 12, 2026

A single npx @sightmap/sightmap init command that takes a new adopter from zero to a working Sightmap loop. Detects your framework (React/Vite, Next App or Pages router, React Router 7), the coding-agent harness(es) in use (Claude Code, Codex, Cursor, OpenCode), and any Sightmap-aware browser MCP already installed (Subtext today; allowlist grows by PR as partnerships form). Runs framework setup (adapter install, <SightmapProvider> codemod with diff preview, codegen) and branches between a plugin path (prints copy-paste install commands per host) and a manual path (writes MCP config + copies skills/hooks/agents from the @sightmap/plugin tarball).

  • @sightmap/sightmap 0.4.0 — new sightmap init CLI subcommand. Flags: --yes, --plugin, --manual, --host, --with-browser, --curate-only, --no-codegen, --no-provider. Per-host writers for .mcp.json (Claude Code), ~/.codex/config.toml, .cursor/mcp.json, and opencode.json — each merges into existing config without clobbering other servers. The <SightmapProvider> codemod uses recast to wrap the app entry’s .render() call; always shows a diff before applying and no-ops if SightmapProvider is already present. See @sightmap/cli.
  • @sightmap/mcp 0.4.0 — new --curate-only flag that skips the upstream browser-MCP spawn and registers only the curation tools (useful when paired with an existing Sightmap-aware browser tool like Subtext). New SIGHTMAP_PLUGIN_VERSION env var startup compat check against a built-in KNOWN_INCOMPATIBLE_RANGES table — emits a soft warning for untested combinations, exits with a clear error on known-incompatible pairs. See @sightmap/mcp.
  • @sightmap/plugin 0.3.2 — repo extracted out of the sightmap-js monorepo to its own GitHub home at sightmap/plugin; the plugin now ships on its own release cadence. Adds compatibleMcpVersion to plugin.json — the single source of truth for @sightmap/mcp version pinning, consumed by sightmap init and propagated into the project’s .mcp.json. See Plugin (Claude Code).

Canonical sources:

v0.3 — sightmap fmt

Section titled “v0.3 — sightmap fmt”

May 10, 2026

A canonical-formatter CLI for .sightmap/ directories. sightmap fmt --check is CI-ready (exits 1 on non-canonical); sightmap fmt --write rewrites in place. Comment-preserving — # HEADER blocks and inline comments survive the round-trip.

  • @sightmap/sightmap 0.3.0 — new sightmap fmt [path] [--check] [--write] [--json] CLI subcommand and a sibling canonicalize(text) public API (both share canonical-form rules through a new canonical-rules module). Implements the spec’s normative canonical-formatting rules: top-level and per-entry-type key order, top-level list sort, universal string quoting (PLAIN > single > double), blank-line normalization between top-level seq entries. Three new diagnostic codes: fmt.not-canonical (warning), fmt.parse-error and fmt.schema-invalid (errors — fmt refuses to rewrite broken files). The 7 vendored fmt conformance fixtures (100–106) now assert in the test suite; previously skipped. See @sightmap/cli.
  • @sightmap/react 0.3.0 and @sightmap/mcp 0.3.0 — lockstep version bump alongside @sightmap/sightmap@0.3.0. No direct API or behavior changes; the adapter and curation tools route YAML output through format() and aren’t yet pipelined through canonicalize(). That follow-up landed on main after the 0.3.0 cut and will be in the next release.

Canonical sources:

v0.2 — Agent-driven curation

Section titled “v0.2 — Agent-driven curation”

May 10, 2026

Headline: @sightmap/mcp grows a curation tool family so an MCP-capable agent can author and refine a .sightmap/ directly — list and fetch views, run diagnostics, patch the agent-authored fields, scaffold a project. Component / route / selector edits stay owned by the React codegen flow, keeping the agent-edits-semantics / codegen-edits-structure split intact.

  • @sightmap/mcp 0.2.0 — curation tools (sightmap_list_views, sightmap_get_view, sightmap_check, sightmap_update_view, sightmap_init_project); sightmap_sep_track MCP prompt for SEP authoring (draft → spec → fixture → verify with confirmation gates); multi-app loading via repeatable --sightmap-dir. See @sightmap/mcp.
  • @sightmap/sightmap 0.2.0 — sightmap check subcommand (combines validate + lint; drives the advisory hook bundle); sightmap check-conventions for spec-repo filename rules; new format export — value-based canonical YAML writer used by sightmap_update_view and the starter scaffolder; browser-safe entry (dist/browser.js) so Vite-style bundlers don’t pull in Node-only helpers; route-shadowing lint now mirrors React Router 7 specificity rather than file/declaration order. See @sightmap/cli and @sightmap/core.
  • @sightmap/react 0.2.0 — React Router 7 framework-mode adapter (--router react-router-7-framework, or auto which picks framework-mode when app/routes.ts is present); the declarative adapter now resolves tsconfig path aliases, <Route Component={X}>, React.lazy(() => import(...)), and directory-style imports. New gen --live <url> flag merges runtime route discovery into the static AST scan. First-run polish: scaffolded TODO comments in new view files, alphabetized edit targets in the CLI summary. See @sightmap/react.
  • @sightmap/plugin 0.2.0 — two new subagents (sightmap-auditor read-only audit, sightmap-assistant write-capable) and six slash commands (/sightmap:audit, /sightmap:init, /sightmap:bootstrap, /sightmap:explain, /sightmap:fix, /sightmap:gen). Distribution is via the Claude Code marketplace; first marketplace publish is queued for v0.3. See Plugin (Claude Code).

Canonical sources:

v0.1 — Initial public release

Section titled “v0.1 — Initial public release”

May 10, 2026

The Sightmap project goes public.

  • Spec stream 1 — views, components, requests, and memory. The complete YAML format is documented in the spec and codified by sightmap.schema.json (JSON Schema setup).
  • @sightmap/sightmap 0.1.0 — library + sightmap CLI. Five commands: validate, lint, check, match, explain. Library API: parse, validate, merge, loadDirectory, match, explain, lint. See @sightmap/cli and @sightmap/core.
  • @sightmap/react 0.1.0 — React adapter. <SightmapProvider>, data-component decoration, the sightmap-react gen codegen flow, the Vite plugin. See @sightmap/react.
  • @sightmap/mcp 0.1.0 — MCP server. Browser introspection + .sightmap/ curation tools for any MCP-capable agent. See @sightmap/mcp.
  • @sightmap/plugin 0.1.0 — Claude Code plugin. SessionStart loader, PreToolUse advisory, PostToolUse validate + cascade. See Plugin (Claude Code).
  • Conformance fixtures — the language-agnostic test suite covering schema, route matching, scoping, and merge semantics. See Conformance fixtures.

Canonical sources:

Future entries will be added above this one, newest first.