@json-render/devtools 0.18.0

package/dist/index.d.ts

@@ -0,0 +1,509 @@
+import { Spec, JsonPatch, Catalog, StateStore, StreamChunk } from '@json-render/core';
+
+/**
+ * Token usage metadata from an AI generation.
+ * Matches the shape used by renderers (e.g. `@json-render/react`).
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedTokens?: number;
+    cacheWriteTokens?: number;
+}
+/**
+ * A single devtools event. Events flow into the `EventStore` from framework
+ * adapters (state changes, action dispatches) and from stream taps.
+ */
+type DevtoolsEvent = {
+    kind: "spec-changed";
+    at: number;
+    spec: Spec;
+} | {
+    kind: "state-set";
+    at: number;
+    path: string;
+    prev: unknown;
+    next: unknown;
+} | {
+    kind: "action-dispatched";
+    at: number;
+    id: string;
+    name: string;
+    params?: unknown;
+} | {
+    kind: "action-settled";
+    at: number;
+    id: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+    durationMs: number;
+} | {
+    kind: "stream-patch";
+    at: number;
+    patch: JsonPatch;
+    source: "json" | "yaml";
+} | {
+    kind: "stream-text";
+    at: number;
+    text: string;
+} | {
+    kind: "stream-usage";
+    at: number;
+    usage: TokenUsage;
+} | {
+    kind: "stream-lifecycle";
+    at: number;
+    phase: "start" | "end";
+    ok?: boolean;
+};
+type DevtoolsEventKind = DevtoolsEvent["kind"];
+/**
+ * Options for creating a picker session. A picker session lets the user
+ * click an element in the host DOM to surface the matching element key
+ * in the Spec panel, and vice versa.
+ */
+interface PickerOptions {
+    /** Called when the user clicks an element with a `data-jr-key` attribute. */
+    onPick: (key: string) => void;
+    /** Called when the user exits picker mode without selecting. */
+    onCancel?: () => void;
+}
+/**
+ * Handle returned from {@link startPicker}. Call `.stop()` to tear down.
+ */
+interface PickerSession {
+    stop: () => void;
+}
+
+/**
+ * Options for {@link createEventStore}.
+ */
+interface EventStoreOptions {
+    /** Max events to retain. Older events are dropped. Default: 500. */
+    bufferSize?: number;
+}
+/**
+ * A capped, subscribable ring buffer of {@link DevtoolsEvent}s.
+ *
+ * Core to every devtools panel — all adapters push into the same store,
+ * and panel UIs subscribe for render updates.
+ */
+interface EventStore {
+    /** Append an event. May drop the oldest event if the buffer is full. */
+    push: (event: DevtoolsEvent) => void;
+    /**
+     * Current events in insertion order (oldest first). Returns a fresh
+     * array so callers can treat it as immutable.
+     */
+    snapshot: () => DevtoolsEvent[];
+    /**
+     * Register a listener invoked after every push (or `clear`). Returns
+     * an unsubscribe function. Listeners are invoked synchronously.
+     */
+    subscribe: (listener: () => void) => () => void;
+    /** Remove all events. Notifies listeners. */
+    clear: () => void;
+    /** Current event count. */
+    size: () => number;
+}
+/**
+ * Create an in-memory ring-buffered event store.
+ *
+ * @example
+ * ```ts
+ * const store = createEventStore({ bufferSize: 200 });
+ * const unsub = store.subscribe(() => render(store.snapshot()));
+ * store.push({ kind: "state-set", at: Date.now(), path: "/x", prev: 1, next: 2 });
+ * ```
+ */
+declare function createEventStore(options?: EventStoreOptions): EventStore;
+
+/**
+ * Production guard. Framework adapters short-circuit to a no-op when this
+ * returns true, so dropping `<JsonRenderDevtools />` into an app costs
+ * nothing in production builds.
+ *
+ * Tree-shaken bundlers will fold constant `process.env.NODE_ENV` checks.
+ * Consumers that run in browsers without `process` also work because the
+ * typeof check guards the access.
+ */
+declare function isProduction(): boolean;
+
+/**
+ * Where the devtools panel docks and where the floating toggle lives.
+ *
+ * - `bottom-right` (default) — panel docks to the bottom; toggle sits in the
+ *   bottom-right corner.
+ * - `bottom-left` — panel docks to the bottom; toggle sits in the bottom-left
+ *   corner. Useful when the host app already has something bottom-right.
+ * - `right` — panel docks to the right edge (full height); toggle sits in the
+ *   top-right corner. Best for app-shell layouts that already use `100vh` /
+ *   `position: fixed` at the bottom — right docking avoids the bottom edge
+ *   entirely.
+ */
+type PanelPosition = "bottom-right" | "bottom-left" | "right";
+/**
+ * A single spec available for inspection. When the host app renders one
+ * spec at a time (the common single-renderer case) this list has a single
+ * entry. Multi-renderer hosts (e.g. an AI chat where each assistant reply
+ * produces its own spec) surface every generation so the Spec tab can
+ * switch between them.
+ */
+interface SpecEntry {
+    /** Stable id, typically the message id that produced the spec. */
+    id: string;
+    /** Human-readable label shown in the generation switcher (e.g. "Generation 2"). */
+    label: string;
+    /** The spec itself. */
+    spec: Spec;
+}
+/**
+ * Context shared with every tab. Tabs read live values via getters so they
+ * always see the latest spec/state/catalog without needing to re-mount.
+ */
+interface PanelContext {
+    /** Event log shared by all panels. */
+    events: EventStore;
+    /** Returns the current (usually latest) spec or `null`. */
+    getSpec: () => Spec | null;
+    /**
+     * Optional: returns every inspectable spec on the page.
+     * Hosts with multiple concurrent renderers (e.g. a chat with one spec
+     * per assistant message) provide this so the Spec tab can offer a
+     * generation switcher. When absent, the tab falls back to `getSpec()`
+     * alone.
+     */
+    getSpecs?: () => SpecEntry[];
+    /** Returns the current catalog or `null`. */
+    getCatalog: () => Catalog | null;
+    /** Returns the live `StateStore` or `null` (only set when a provider is mounted). */
+    getStateStore: () => StateStore | null;
+    /** Start a picker session. Returns `null` if no DOM is available. */
+    startPicker?: (options: PickerOptions) => PickerSession | null;
+    /** Selection channel shared across tabs (picker <-> Spec tab). */
+    selection: SelectionBus;
+    /** Activate a specific tab by id. */
+    activateTab: (id: string) => void;
+}
+/**
+ * Bus for syncing the currently focused spec element key across tabs and the
+ * picker overlay. Tabs read the current value and subscribe to changes;
+ * anything that wants to focus an element (picker, tree click) calls `set`.
+ */
+interface SelectionBus {
+    get: () => string | null;
+    set: (key: string | null) => void;
+    subscribe: (listener: (key: string | null) => void) => () => void;
+}
+/** Create an in-memory {@link SelectionBus}. */
+declare function createSelectionBus(): SelectionBus;
+/**
+ * A tab registered with the panel. Tabs are rendered lazily — `mount` is
+ * called the first time the tab is activated, and `update` is called on
+ * every re-render request after that.
+ */
+interface TabDef {
+    /** Stable tab id used in URL hash / storage. */
+    id: string;
+    /** Short label shown in the tab strip. */
+    label: string;
+    /** Optional count badge, recomputed on every render. */
+    badge?: (ctx: PanelContext) => number | string | undefined;
+    /** Create the DOM for this tab. Called once per activation. */
+    mount: (root: HTMLElement, ctx: PanelContext) => TabInstance;
+}
+/**
+ * A live tab. `update` is called whenever an event fires or the host
+ * refreshes; `destroy` is called when the tab is unmounted.
+ */
+interface TabInstance {
+    /** Re-render with latest data. */
+    update: () => void;
+    /** Clean up subscriptions / listeners. */
+    destroy?: () => void;
+}
+/**
+ * Options for {@link createPanel}.
+ */
+interface PanelOptions {
+    /** Shared panel context. */
+    context: PanelContext;
+    /** Tabs to register. Order is preserved in the tab strip. */
+    tabs: TabDef[];
+    /** Host-document node to mount under. Default: `document.body`. */
+    host?: HTMLElement;
+    /** Position of the floating toggle button. */
+    position?: PanelPosition;
+    /** Start open. Default: `false`. */
+    initialOpen?: boolean;
+    /**
+     * Keyboard shortcut to toggle the panel, or `false` to disable.
+     * Syntax: `"mod+shift+j"` (`mod` = meta on mac, ctrl elsewhere).
+     * Default: `"mod+shift+j"`.
+     */
+    hotkey?: string | false;
+    /**
+     * Whether the panel should push the host app's content out of the way
+     * while open, by applying `padding` on `<body>` matching the panel's size.
+     *
+     * - `true` (default) — body padding is applied. Works for document-flow
+     *   layouts and `height: 100%` app shells. Modern apps that use
+     *   `height: 100vh`, `position: fixed; bottom: 0` etc. are effectively
+     *   *overlaid* by the panel because CSS can't resize `100vh`. Pair this
+     *   with `"right"` docking or opt those specific elements in via
+     *   `bottom: var(--jr-devtools-offset-bottom, 0)` /
+     *   `right: var(--jr-devtools-offset-right, 0)`.
+     * - `false` — the panel is a pure overlay. Nothing is pushed; the host
+     *   app remains visually unchanged. The CSS custom properties
+     *   `--jr-devtools-offset-bottom` / `--jr-devtools-offset-right` are
+     *   still published on `:root` so apps can reserve their own space.
+     */
+    reserveSpace?: boolean;
+    /**
+     * When `true` (default), show a toolbar button that lets the user flip
+     * the panel between bottom-dock and right-dock. The user's choice
+     * persists across reloads (localStorage key `__jr_devtools_dock`), and
+     * takes precedence over the initial `position` once set.
+     *
+     * When `false`, the dock follows `position` exactly and the toolbar
+     * button is not rendered — useful when the host app's layout only works
+     * with one dock.
+     */
+    allowDockToggle?: boolean;
+}
+/**
+ * Returned from {@link createPanel}. Controls the panel lifecycle.
+ */
+interface PanelHandle {
+    /** Show the panel. */
+    open: () => void;
+    /** Hide the panel. */
+    close: () => void;
+    /** Toggle open/closed. */
+    toggle: () => void;
+    /** True if the panel is currently open. */
+    isOpen: () => boolean;
+    /** Request that all visible tabs re-render. */
+    refresh: () => void;
+    /** Remove the panel from the DOM and clean up. */
+    destroy: () => void;
+}
+
+/**
+ * Create a devtools panel and mount it to the host document.
+ *
+ * Idempotent per-host: if a panel is already mounted under the given host,
+ * this returns that panel's handle instead of creating a duplicate.
+ */
+declare function createPanel(options: PanelOptions): PanelHandle;
+/**
+ * Mount a panel with a minimal placeholder for each tab. Useful for tests
+ * or environments where individual tab implementations aren't available.
+ *
+ * In production, consumers use {@link createPanel} with the full tab set.
+ */
+declare function createStubTab(id: string, label: string): TabDef;
+
+/**
+ * Tiny hyperscript-style helper for building DOM nodes without JSX.
+ *
+ * Keeps the vanilla-TS panel readable. Supports attributes starting with
+ * `on` as event listeners, `className`, inline `style` objects, and a mix
+ * of string / node / array children.
+ */
+type Child = Node | string | number | null | undefined | false | Child[];
+type Attrs = {
+    [key: string]: unknown;
+    className?: string;
+    style?: Partial<CSSStyleDeclaration>;
+};
+declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs?: Attrs | null, ...children: Child[]): HTMLElementTagNameMap[K];
+/** Replace the children of `parent` with `next`, clearing first. */
+declare function replaceChildren(parent: Node, ...next: Child[]): void;
+/** Render a short JSON preview that truncates long values. */
+declare function jsonPreview(value: unknown, max?: number): string;
+/** Format an absolute timestamp (ms) as `HH:MM:SS.mmm`. */
+declare function formatTime(at: number): string;
+
+/**
+ * Spec Tree tab — renders the element tree with expand/collapse, shows a
+ * one-line summary per node, and highlights structural issues from
+ * `validateSpec`. Selecting a node fills the right-hand detail pane with
+ * full props + metadata.
+ */
+declare function specTab(): TabDef;
+
+/**
+ * State Inspector tab — lists every leaf path in the state model with an
+ * inline editor. Editing a value re-parses it as JSON; if the input
+ * doesn't parse, the raw string is used. Reads a snapshot from the
+ * underlying StateStore on every render, plus on every state-set event.
+ */
+declare function stateTab(): TabDef;
+
+/**
+ * Action Log tab — chronologically ordered list of dispatched actions.
+ * Each dispatch is paired with its settle event (by `id`) to show
+ * duration + success/failure.
+ */
+declare function actionsTab(): TabDef;
+
+/**
+ * Stream Log tab — shows spec patches, text chunks, lifecycle markers,
+ * and token usage grouped by generation (lifecycle start -> end).
+ */
+declare function streamTab(): TabDef;
+
+interface CatalogField {
+    name: string;
+    type: string;
+}
+interface CatalogComponentInfo {
+    name: string;
+    description: string;
+    props: CatalogField[];
+    slots: string[];
+    events: string[];
+}
+interface CatalogActionInfo {
+    name: string;
+    description: string;
+    params: CatalogField[];
+}
+/**
+ * Catalog Browser tab — lists the components and actions declared in the
+ * attached catalog with prop/param chips, so developers can see what the
+ * AI can use.
+ */
+declare function catalogTab(): TabDef;
+/**
+ * Extract display data from a raw catalog definition. Handles both Zod v3
+ * (`_def.shape()`) and v4 (`shape` getter). Resilient to missing fields.
+ *
+ * Same logic as `apps/web/lib/render/catalog-display.ts` but lives here
+ * so framework adapters don't depend on the web app.
+ */
+declare function buildCatalogDisplayData(rawCatalogData: unknown): {
+    components: CatalogComponentInfo[];
+    actions: CatalogActionInfo[];
+};
+
+/**
+ * Picker tab — explains the DOM picker flow, starts / stops a picker
+ * session, and shows the currently selected element key. Selecting a key
+ * in the spec tab reflects here; selecting here (via click-to-pick)
+ * jumps back to the spec tab.
+ */
+declare function pickerTab(): TabDef;
+
+/**
+ * Attribute the ElementRenderer (when devtools is active) sets on each
+ * rendered element's wrapper. The picker walks up from the hovered node
+ * to the nearest ancestor bearing this attribute.
+ */
+declare const DEVTOOLS_KEY_ATTR = "data-jr-key";
+/**
+ * Start an interactive DOM picker. The user hovers or clicks any element
+ * in the page; when a click lands on (or inside) a node carrying
+ * {@link DEVTOOLS_KEY_ATTR}, `onPick` fires with that key.
+ *
+ * Returns `null` in environments without a DOM (SSR, tests).
+ *
+ * The picker paints a translucent overlay + border over the hovered
+ * element (Chrome-DevTools style). See {@link computeBounds} for the
+ * `display: contents` fallback.
+ */
+declare function startPicker(options: PickerOptions): PickerSession | null;
+/**
+ * Show (or hide) a persistent bounding-box overlay over the element
+ * identified by `key`. Pass `null` to clear the overlay.
+ *
+ * Unlike {@link highlightElement}, this does not fade out — callers are
+ * expected to clear it explicitly (typically on `mouseleave`). Safe to
+ * call repeatedly; each call cheaply repositions the single overlay.
+ */
+declare function setHoverHighlight(key: string | null): void;
+/**
+ * Look up the DOM element carrying `data-jr-key={key}`. Returns `null`
+ * when no match (spec exists but hasn't rendered, or the element is
+ * currently hidden by a visibility condition).
+ *
+ * Note: when an element appears inside a `repeat`, each repetition
+ * renders its own DOM instance with the same `data-jr-key`. Use
+ * {@link findAllElementsByKey} if you need all of them.
+ */
+declare function findElementByKey(key: string): Element | null;
+/**
+ * Return every DOM element carrying `data-jr-key={key}`. Intended for
+ * repeated spec elements (list items, grid cells…) where a single spec
+ * key renders to N DOM instances.
+ */
+declare function findAllElementsByKey(key: string): Element[];
+/**
+ * Briefly paint an outline around the DOM element for `key`, so clicking
+ * a spec-tree row in the panel flashes its position in the page.
+ *
+ * The target is often a `display: contents` wrapper, so we build the
+ * overlay from `computeBounds` (descendants' client rects) instead of
+ * using a CSS outline on the target directly.
+ */
+declare function highlightElement(key: string, durationMs?: number): void;
+
+/**
+ * A minimal shape compatible with AI SDK `UIMessage.parts[i]`. Defined
+ * locally so the devtools package has no dependency on the `ai` package.
+ */
+interface DataPart {
+    type: string;
+    text?: string;
+    data?: unknown;
+    state?: string;
+}
+/**
+ * Wrap a `ReadableStream<StreamChunk>` (e.g. the output of `pipeJsonRender`
+ * or any `TransformStream<StreamChunk, StreamChunk>`) so spec patches are
+ * mirrored into a devtools `EventStore` as they fly past.
+ *
+ * Returns the original stream unchanged — the tap just forks a copy.
+ *
+ * @example
+ * ```ts
+ * writer.merge(
+ *   tapJsonRenderStream(
+ *     pipeJsonRender(result.toUIMessageStream()),
+ *     devtoolsEventStore,
+ *   ),
+ * );
+ * ```
+ */
+declare function tapJsonRenderStream(stream: ReadableStream<StreamChunk>, events: EventStore): ReadableStream<StreamChunk>;
+/** YAML variant — identical behaviour with `source: "yaml"`. */
+declare function tapYamlStream(stream: ReadableStream<StreamChunk>, events: EventStore): ReadableStream<StreamChunk>;
+/**
+ * Client-side helper: scan a message's `parts` array for spec data parts
+ * and push matching events into the store. Use this when rendering chat
+ * UIs that use `@ai-sdk/react` `useChat` and pass in `messages`.
+ *
+ * Idempotent via `seenIds`: only parts not already recorded will emit.
+ * Returns the new `seenIds` set so callers can persist it between calls.
+ */
+declare function scanMessageParts(parts: readonly DataPart[] | undefined, events: EventStore, seen: WeakSet<object>): void;
+/**
+ * Emit a token-usage event. Called by adapters with whatever usage
+ * object their framework surfaces (AI SDK `result.usage`).
+ */
+declare function recordUsage(events: EventStore, usage: TokenUsage): void;
+/**
+ * Replay every `SPEC_DATA_PART` in `parts` and return the resulting spec,
+ * or `null` if the message has no UI. Mirrors the framework-side
+ * `buildSpecFromParts` helper but without a framework dependency — used by
+ * the devtools panel's generation switcher to reconstruct each prior
+ * assistant message's spec so the user can inspect any of them.
+ */
+declare function extractSpecFromParts(parts: readonly DataPart[] | undefined): Spec | null;
+/** Emit a pre-built devtools event. Useful for manual instrumentation. */
+declare function recordEvent(events: EventStore, event: DevtoolsEvent): void;
+
+export { DEVTOOLS_KEY_ATTR, type DevtoolsEvent, type DevtoolsEventKind, type EventStore, type EventStoreOptions, type PanelContext, type PanelHandle, type PanelOptions, type PanelPosition, type PickerOptions, type PickerSession, type SelectionBus, type SpecEntry, type TabDef, type TabInstance, type TokenUsage, actionsTab, buildCatalogDisplayData, catalogTab, createEventStore, createPanel, createSelectionBus, createStubTab, extractSpecFromParts, findAllElementsByKey, findElementByKey, formatTime, h, highlightElement, isProduction, jsonPreview, pickerTab, recordEvent, recordUsage, replaceChildren, scanMessageParts, setHoverHighlight, specTab, startPicker, stateTab, streamTab, tapJsonRenderStream, tapYamlStream };