"use client"; import { useEffect, useMemo, useRef } from "react"; import type { Catalog, Spec, StateStore } from "@json-render/core"; import { markDevtoolsActive, registerActionObserver, subscribeDevtoolsActive, } from "@json-render/core"; import { useStateStore } from "@json-render/react"; import { actionsTab, catalogTab, createEventStore, createPanel, createSelectionBus, extractSpecFromParts, highlightElement, isProduction, scanMessageParts, specTab, startPicker, stateTab, streamTab, type DevtoolsEvent, type EventStore, type PanelContext, type PanelHandle, type PanelPosition, type SpecEntry, } from "@json-render/devtools"; /** * Minimal shape of an AI SDK `UIMessage` used to capture stream events. * We only read the `parts` array, so any ai-sdk version works. */ interface ChatLikeMessage { id?: string; role?: string; parts?: Array<{ type: string; text?: string; data?: unknown }>; } /** * Walk the AI SDK message list and reconstruct the spec for every * assistant message that produced one. The resulting list powers the * Spec tab's generation switcher — when a chat has multiple assistant * turns, the user can pick any of them to inspect, not just the most * recent. Falls back to a single entry when only an explicit `spec` * prop is present and no messages were passed. */ function buildGenerationsList( messages: readonly ChatLikeMessage[] | undefined, latestSpec: Spec | null, ): SpecEntry[] { const out: SpecEntry[] = []; if (messages) { let idx = 0; for (const msg of messages) { const spec = extractSpecFromParts(msg?.parts); if (!spec || Object.keys(spec.elements).length === 0) continue; idx += 1; out.push({ id: msg?.id ?? `gen-${idx}`, label: `Generation ${idx}`, spec, }); } } if (out.length === 0 && latestSpec) { out.push({ id: "spec", label: "Current spec", spec: latestSpec }); } return out; } /** * Props for ``. */ export interface JsonRenderDevtoolsProps { /** The spec currently being rendered. Required for Spec, Pick. */ spec?: Spec | null; /** Catalog for the Catalog panel. Optional. */ catalog?: Catalog | null; /** * AI SDK `useChat` messages array. When passed, spec data parts are * scanned and streamed into the Stream panel automatically. */ messages?: readonly ChatLikeMessage[]; /** Start the panel open. Default: `false`. */ initialOpen?: boolean; /** * Where the panel docks and where the floating toggle lives. * - `"bottom-right"` (default) — bottom-docked panel, toggle bottom-right. * - `"bottom-left"` — bottom-docked panel, toggle bottom-left. * - `"right"` — right-docked panel (full height), toggle top-right. * Best for app-shell layouts that already use `100vh` or fixed bottom * elements. */ position?: PanelPosition; /** Hotkey to toggle, or `false` to disable. Default: `mod+shift+j`. */ hotkey?: string | false; /** Max events retained in the ring buffer. Default: 500. */ bufferSize?: number; /** * Whether to reserve space for the panel by applying body padding while * open. Default `true`. Set to `false` to keep the panel as a pure * overlay; the `--jr-devtools-offset-bottom` / `--jr-devtools-offset-right` * CSS custom properties are still published for apps to consume manually. */ reserveSpace?: boolean; /** * Whether to show a toolbar button that lets the user flip the panel * between bottom-dock and right-dock. Default `true`. The user's choice * persists to `localStorage` and overrides `position` on subsequent * mounts. Pass `false` to lock the dock to whatever `position` specifies. */ allowDockToggle?: boolean; /** * Optional tap: called for every devtools event. Useful if you want to * forward events to your own analytics pipeline. */ onEvent?: (evt: DevtoolsEvent) => void; } /** Controls returned from {@link useJsonRenderDevtools}. */ export interface JsonRenderDevtoolsHandle { /** Open the panel. */ open: () => void; /** Close the panel. */ close: () => void; /** Toggle open/closed. */ toggle: () => void; /** Emit a custom event into the log. */ recordEvent: (evt: DevtoolsEvent) => void; /** Clear all events. */ clear: () => void; } let globalHandle: JsonRenderDevtoolsHandle | null = null; /** * Access the running devtools from outside the React tree, if mounted. * Returns `null` in production or when no `` is live. */ export function useJsonRenderDevtools(): JsonRenderDevtoolsHandle | null { return globalHandle; } /** * Drop this component anywhere inside a `` (or renderer * that sets up state/actions contexts) to get a floating devtools panel. * * In production builds this renders `null`. */ export function JsonRenderDevtools(props: JsonRenderDevtoolsProps) { if (isProduction()) return null; // Stable refs to avoid re-mounting the panel on every render. const specRef = useRef(props.spec ?? null); specRef.current = props.spec ?? null; const catalogRef = useRef(props.catalog ?? null); catalogRef.current = props.catalog ?? null; // Latest messages live in a ref so the `getSpecs` closure captured by // the panel can read them without re-mounting when the messages change. const messagesRef = useRef( props.messages, ); messagesRef.current = props.messages; // Read the live StateStore from the json-render state context. Must be // rendered inside `` — useStateStore throws otherwise. const ctx = useStateStore(); const storeRef = useRef(null); storeRef.current = { get: ctx.get, set: ctx.set, update: ctx.update, getSnapshot: ctx.getSnapshot, // The context doesn't expose subscribe directly; the State tab // re-reads getSnapshot() on each panel refresh. A no-op here keeps // the StateStore shape satisfied for downstream consumers. subscribe: () => () => {}, }; const events = useMemo( () => createEventStore({ bufferSize: props.bufferSize }), // bufferSize changes would require a re-created buffer; acceptable. // eslint-disable-next-line react-hooks/exhaustive-deps [props.bufferSize], ); // Optional external tap. useEffect(() => { if (!props.onEvent) return; return events.subscribe(() => { const snap = events.snapshot(); const last = snap[snap.length - 1]; if (last) props.onEvent?.(last); }); }, [events, props.onEvent]); // Forward action dispatches to the panel event store. useEffect(() => { return registerActionObserver({ onDispatch(evt) { events.push({ kind: "action-dispatched", at: evt.at, id: evt.id, name: evt.name, params: evt.params, }); }, onSettle(evt) { events.push({ kind: "action-settled", at: evt.at, id: evt.id, ok: evt.ok, durationMs: evt.durationMs, result: evt.result, error: evt.error !== undefined ? String(evt.error) : undefined, }); }, }); }, [events]); // React already re-renders this component when ctx changes (via its // subscription to the state store), so we call panel.refresh on every // render. It's cheap — rendered tabs only diff their active view. useEffect(() => { handleRef.current?.refresh(); }); // Tap AI SDK message parts for stream events. const seenParts = useRef>(new WeakSet()); useEffect(() => { if (!props.messages) return; for (const msg of props.messages) { if (msg?.parts) scanMessageParts(msg.parts, events, seenParts.current); } }, [props.messages, events]); // Mount the panel once. const handleRef = useRef(null); useEffect(() => { if (handleRef.current) return; const selection = createSelectionBus(); const ctx: PanelContext = { events, getSpec: () => specRef.current, getSpecs: () => buildGenerationsList(messagesRef.current, specRef.current), getCatalog: () => catalogRef.current, getStateStore: () => storeRef.current, startPicker: (opts) => startPicker(opts), selection, // Populated by createPanel. activateTab: () => {}, }; const panel = createPanel({ context: ctx, tabs: [specTab(), stateTab(), actionsTab(), streamTab(), catalogTab()], initialOpen: props.initialOpen, position: props.position, hotkey: props.hotkey, reserveSpace: props.reserveSpace, allowDockToggle: props.allowDockToggle, }); handleRef.current = panel; // Highlight in the host DOM as the selection changes. const unsubSelection = selection.subscribe((key) => { if (key) highlightElement(key); }); globalHandle = { open: () => panel.open(), close: () => panel.close(), toggle: () => panel.toggle(), recordEvent: (evt) => events.push(evt), clear: () => events.clear(), }; const releaseActive = markDevtoolsActive(); return () => { unsubSelection(); releaseActive(); panel.destroy(); handleRef.current = null; globalHandle = null; }; }, [ events, props.initialOpen, props.position, props.hotkey, props.reserveSpace, props.allowDockToggle, ]); return null; } // Re-export core devtools types for convenience. export type { DevtoolsEvent } from "@json-render/devtools"; // Keep a silent reference to `subscribeDevtoolsActive` so bundlers don't // drop it; adapters rely on the core module-level state being loaded. void subscribeDevtoolsActive;