json-render

The @json-render/devtools package provides the following core capabilities:

• Event store: A capped ring buffer providing push, subscribe, snapshot, and clear methods.
• Panel: A shadow-DOM-isolated drawer containing six tabs: Spec, State, Actions, Stream, Catalog, and Pick.
• Stream taps: Utilities to wrap pipeJsonRender or YAML transforms, allowing patches to be mirrored into the event store.
• Picker: A DOM overlay that enables mapping clicked elements back to their corresponding spec keys using the data-jr-key attribute.

The @json-render/remotion package allows you to turn JSON timeline specifications into video compositions using Remotion. It provides a Renderer component that acts as the main composition engine, a set of standard video components (like TitleCard and TypingText), and utilities for handling transitions.

import { Renderer } from '@json-render/remotion';
// Use Renderer as the component for Remotion's Player or within a Remotion project

The @json-render/devtools package provides the framework-agnostic core for the json-render devtools, including the vanilla TS panel UI, event store, DOM picker, and stream tap utilities.

Note for most users: You likely do not need to import from this package directly. Instead, install the adapter that matches your renderer (e.g., @json-render/devtools-react, @json-render/devtools-vue, etc.) and use the <JsonRenderDevtools /> component. This core package is a dependency for all framework-specific adapters.

The Stripe App examples are organized into three main components:

• api/: A Next.js server that provides the /api/generate endpoint used for AI-powered UI generation via json-render.
• drawer-app/: A standard Stripe App designed to render within the Dashboard drawer (sidebar).
• fullpage-app/: A Stripe App that utilizes FullPageView for a full-page experience (requires Stripe alpha access).

SpecStream is a JSONL-based (JSON Lines) streaming format used by json-render to progressively build a UI specification. Instead of sending a single large JSON object, the stream consists of individual JSON patch operations that incrementally update the spec. This allows the UI to render components as they are being generated by an AI.

Each line in the stream is a valid JSON object representing an operation.

{"op":"add","path":"/root","value":"root"}
{"op":"add","path":"/elements/root","value":{"type":"Card","props":{"title":"Dashboard"},"children":["metric-1","metric-2"]}}
{"op":"add","path":"/elements/metric-1","value":{"type":"Metric","props":{"label":"Revenue"}}}

A schema defines the JSON structure and validation rules for your UI specifications. It acts as the 'grammar' for your UI, dictating how elements are organized and how they interact with data and actions. A schema typically encompasses four key areas:

1. Element structure: How components are nested and referenced.
2. Property types: The expected shape of props for each component.
3. Data binding syntax: How to reference dynamic data within props.
4. Action format: How user interactions (like clicks or navigation) are defined.

While the Schema defines the structure (the grammar), the Catalog defines the available components and their props (the vocabulary).

A Catalog acts as the vocabulary for your UI, serving as a guardrail for what an AI can generate. While a schema defines the grammar (the structure of specifications), the catalog defines the available components, actions, and functions.

A catalog includes:

• Components: UI elements the AI can create, including their props and optional slots.
• Actions: Operations that the AI can trigger.
• Functions: Custom validation or transformation functions.

A Spec (specification) is a JSON document that describes a UI. It uses components from a component catalog and can optionally follow a specific schema.

Because json-render is schema-agnostic, you can define your own JSON structure, but common patterns include:

• AI Generation: Real-time generation by LLMs.
• Storage: Storing specs in a database.
• Streaming: Progressive streaming from a server.
• Hand-authoring: Writing specs manually as JSON files.

A registry maps your catalog definitions (which define what can be generated) to platform-specific implementations (which define how it is rendered).

Each package in the json-render ecosystem uses a specific schema that determines the shape of its registry:

• @json-render/react: Maps to React elements and action handlers.
• @json-render/react-native: Maps to React Native elements and action handlers.
• @json-render/react-email: Maps to React Email / HTML components.
• @json-render/remotion: Maps to video clip components, transitions, and effects.

To create an AI-powered chat where the assistant emits both text and JSON patches, use the pipeJsonRender utility on the server.

1. Server-side: Use pipeJsonRender to split the agent's stream into data-spec parts (RFC 6902 JSON patches) and plain text parts.
2. Client-side: Use the useJsonRenderMessage hook to re-assemble these parts, allowing the UI to render the conversational text alongside the inline spec.

Example Prompt Pattern: The agent should be instructed to write a conversational reply followed by a spec fence containing the JSON patches.