feat(seer): Add structured LLM context system for Seer Explorer

[Mihir-Mavalankar]

Adds infrastructure for Seer Explorer to read structured semantic state from the currently rendered page — without scraping the DOM.

What

Three cooperating primitives:

LLMContextProvider — drop-in root provider (mounted in the app shell). Owns a flat node registry stored in refs and exposes read/write operations via internal React context. Uses pure ref-based state — no reducer, no re-renders on registration — since consumers read data imperatively via getSnapshot().

registerLLMContext(nodeType, Component) — HOC that auto-registers a component as a named node on mount and removes it (plus all descendants) on unmount. nodeType is strictly typed (LLMContextNodeType) for typeahead and to prevent naming drift. Nesting follows React component hierarchy automatically via LLMNodeContext, which carries each component's useId()-generated node ID downward so child HOC wrappers can declare their parentId synchronously during render.

useLLMContext(data) / useLLMContext() — write and read overloads. The write overload accepts any non-undefined value (objects, arrays, strings, numbers — polymorphic) and pushes it into the nearest registered context node. The read overload returns getLLMContext(componentOnly?) for full-tree or subtree snapshots.

Named LLMContext (not SeerContext) since the system is generic and could be used by any LLM integration.

Why

Seer Explorer needs to understand what the user is currently looking at (dashboard, widgets, charts, etc.) to give grounded AI responses. This system lets any component opt in by wrapping with registerLLMContext and calling useLLMContext(data) — no manual tree wiring, no DOM inspection.

Design notes

• Flat storage, lazy tree assembly — nodes stored as Map<id, {nodeType, parentId}> in a ref; tree assembled at getSnapshot() time. Avoids ordering dependencies: a child can declare its parentId before the parent's registration effect has fired.
• Imperative ref for data — useLLMContext(data) writes to a useRef<Map> rather than dispatching state updates. This sidesteps a fundamental timing issue: child effects fire before parent effects, so data writes happen before registerNode. The ref is always read fresh at getSnapshot() time.
• Zero re-renders — the provider uses refs for all state and useCallback(fn, []) for all operations. The memoized context value is referentially stable, so neither the provider nor its consumers ever re-render from context changes.
• Strict context requirement — useLLMContextRegistry() throws if called outside the provider (which lives at the app root), treating missing context as a bug rather than silently returning undefined.
• JSON dedup with circular-reference safety — write path uses JSON.stringify equality to skip redundant writes, with a try/catch that falls back to always-write for non-serializable values.
• Cleanup on unregister — unregisterNode removes descendant entries from both the node map and the data ref so stale entries don't accumulate.

Tests

9 integration tests covering: empty state, nesting (Dashboard → Widget → Chart with full shape assertion), unmount cleanup, data updates across re-renders, non-object data types (strings, arrays, numbers), full-tree vs componentOnly subtree reads.

[github-actions]

🚨 Warning: This pull request contains Frontend and Backend changes!

It's discouraged to make changes to Sentry's Frontend and Backend in a single pull request. The Frontend and Backend are not atomically deployed. If the changes are interdependent of each other, they must be separated into two pull requests and be made forward or backwards compatible, such that the Backend or Frontend can be safely deployed independently.

Have questions? Please ask in the #discuss-dev-infra channel.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}