import { pageMetadata } from "@/lib/page-metadata"
export const metadata = pageMetadata("docs/changelog")

# Changelog

Notable changes and updates to json-render.

## v0.19.0

May 6, 2026

### New: Custom Directives API

`@json-render/core` now supports custom directives via `defineDirective`, letting you declare new JSON shapes (like `$format`, `$math`) that resolve to computed values at render time. Directives compose naturally -- nest `$format` over `$math` over `$state` and they resolve inside-out. All four renderers (React, Vue, Svelte, Solid) have built-in directive resolution.

### New: `@json-render/directives`

New package shipping seven ready-made directives: `$format` (date, currency, number, percent via `Intl`), `$math` (arithmetic and rounding), `$concat`, `$count`, `$truncate`, `$pluralize`, and `$join`. Also exports `createI18nDirective` for `$t` translation keys with interpolation, and `standardDirectives` for one-line registration.

```bash
npm install @json-render/directives
```

```tsx
import { standardDirectives } from "@json-render/directives";

const catalog = createCatalog({
  directives: standardDirectives,
  // ...
});
```

See the [Directives guide](/docs/directives) and the [API reference](/docs/api/directives) for details.

---

## v0.18.0

April 17, 2026

### New: Devtools

Five new packages for inspecting json-render apps in the browser:

- `@json-render/devtools` -- framework-agnostic core
- `@json-render/devtools-react`
- `@json-render/devtools-vue`
- `@json-render/devtools-svelte`
- `@json-render/devtools-solid`

Drop `<JsonRenderDevtools />` into your app to get a shadow-DOM-isolated panel with six tabs (Spec, State, Actions, Stream, Catalog, Pick), a DOM picker that maps clicked elements back to spec keys via `data-jr-key`, and a capped event store. Toggle with the floating button or `Cmd`/`Ctrl` + `Shift` + `J`. Tree-shakes to `null` in production.

```bash
npm install @json-render/devtools-react
```

```tsx
import { JsonRenderDevtools } from "@json-render/devtools-react";

<JsonRenderDevtools />
```

See the [Devtools guide](/docs/devtools) and the [API reference](/docs/api/devtools) for details.

### New: Devtools Example

New `examples/devtools` Next.js demo showing the full devtools panel wired up to an AI chat endpoint and a component catalog.

### New: Action Observer and Devtools Flag in Core

`@json-render/core` now exposes an action observer and a devtools enablement flag that framework adapters use to mirror actions and stream events into the panel.

### Fixed: Zod 4 Schema Formatting

`formatZodType` now correctly handles `z.record()`, `z.default()`, and `z.literal()` types from Zod 4, which previously produced incorrect or empty output in generated prompts and schemas.

---

## v0.17.0

April 10, 2026

### New: Gaussian Splatting

Added `GaussianSplat` component to `@json-render/react-three-fiber`, bringing the component count to 20. Composable with all existing R3F components (lights, controls, post-processing) via drei's Splat loader.

### New: R3F Gaussian Splatting Example

Demo app with five scenes: splat showroom, splat with primitives, multi-splat, post-processing effects, and animated floating splat.

### New: Standalone gsplat Example

Experimental demo app showcasing Gaussian Splatting with gsplat.js (no Three.js dependency), featuring scene selector, live JSON spec viewer, and progress indicator.

### Improved: AI Output Quality

Improved prompt output and schema generation for more reliable AI-generated specs.

---

## v0.16.0

March 27, 2026

### New: `@json-render/next`

Next.js renderer that turns JSON specs into full Next.js applications with routes, layouts, SSR, metadata, data loaders, and static generation. Client and server entry points at `@json-render/next` and `@json-render/next/server`. Includes built-in `Link`, `Slot`, error boundary, loading, and not-found components.

```bash
npm install @json-render/next
```

### New: `@json-render/shadcn-svelte`

Pre-built shadcn-svelte components for json-render Svelte apps. 36 components built on Svelte 5 + Tailwind CSS with state binding, validation, and action support. Server-safe catalog at `@json-render/shadcn-svelte/catalog`.

```bash
npm install @json-render/shadcn-svelte
```

### Improved: Release Process

Switched from Changesets to a manual single-PR release workflow with changelog markers and automatic npm publish on version bump.

---

## v0.15.0

March 23, 2026

### New: `@json-render/ink`

Terminal renderer for json-render. JSON becomes terminal UIs powered by [Ink](https://github.com/vadimdemedes/ink). Stream AI-generated specs directly to the terminal with `useUIStream`.

```bash
npm install @json-render/ink
```

### Improved: YAML Format Support in `buildUserPrompt`

`buildUserPrompt` now accepts `format` and `serializer` options, enabling YAML as a wire format alongside JSON.

---

## v0.14.0

March 13, 2026

### New: `@json-render/yaml`

YAML wire format for json-render. Includes streaming YAML parser, `yamlPrompt()` for system prompts, and AI SDK transform (`pipeYamlRender`) as a drop-in alternative to JSONL streaming. Supports four fence types: `yaml-spec`, `yaml-edit`, `yaml-patch`, and `diff`.

```bash
npm install @json-render/yaml
```

### New: Universal Edit Modes

Three strategies for multi-turn spec refinement in `@json-render/core`:

- **Patch** -- RFC 6902 JSON Patch
- **Merge** -- RFC 7396 Merge Patch
- **Diff** -- Unified diff

New `editModes` option on `buildUserPrompt()` and `PromptOptions`. New helpers: `deepMergeSpec()`, `diffToPatches()`, `buildEditUserPrompt()`, `buildEditInstructions()`, `isNonEmptySpec()`.

### Improved: Playground

Format toggle (JSONL / YAML), edit mode picker (patch / merge / diff), and token usage display with prompt caching stats.

### Improved: Prompt Caching

Generate API uses Anthropic ephemeral cache control for system prompts.

---

## v0.13.0

March 12, 2026

### New: `@json-render/solid`

SolidJS renderer for json-render. JSON becomes Solid components with reactive rendering, schema export, and full catalog support.

```bash
npm install @json-render/core @json-render/solid
```

### New: `@json-render/react-three-fiber`

React Three Fiber renderer for json-render. JSON becomes 3D scenes with 19 built-in components for meshes, lights, models, environments, text, cameras, and controls.

```bash
npm install @json-render/react-three-fiber
```

### Improved: Strict JSON Schema Mode

`catalog.jsonSchema({ strict: true })` produces a JSON Schema subset compatible with LLM structured output APIs (OpenAI, Google Gemini, Anthropic). Ensures `additionalProperties: false` on every object and all properties listed in `required`.

---

## v0.12.1

March 11, 2026

### Changed: Generation Mode Renames

Renamed generation modes from `"generate"` / `"chat"` to `"standalone"` / `"inline"`. The old names still work but emit a deprecation warning.

### Fixed: MCP React Duplicate Module Error

Resolved React duplicate module error (`useRef` returning null) in `@json-render/mcp` by adding `resolve.dedupe` Vite configuration. Added `./build-app-html` export entry point.

---

## v0.12.0

March 6, 2026

### New: `@json-render/svelte`

Svelte 5 renderer with runes-based reactivity. Full support for data binding, visibility, actions, validation, watchers, streaming, and repeat scopes. Includes `defineRegistry`, `Renderer`, `schema`, composables, and context providers.

```bash
npm install @json-render/core @json-render/svelte
```

### New: `@json-render/react-email`

React Email renderer for generating HTML and plain-text emails from JSON specs. 17 standard components (Html, Head, Body, Container, Section, Row, Column, Heading, Text, Link, Button, Image, Hr, Preview, Markdown). Server-side `renderToHtml` / `renderToPlainText` APIs.

```bash
npm install @json-render/react-email
```

### New: `@json-render/mcp`

MCP Apps integration that serves json-render UIs as interactive apps inside Claude, ChatGPT, Cursor, VS Code, and other MCP-capable clients. `createMcpApp` server factory, `useJsonRenderApp` React hook for iframes, and `buildAppHtml` utility.

```bash
npm install @json-render/mcp
```

---

## v0.11.0

February 27, 2026

### New: `@json-render/image`

Server-side image renderer powered by Satori. Turns the same `{ root, elements }` spec format into SVG or PNG output for OG images, social cards, and banners.

```bash
npm install @json-render/image
```

```typescript
import { renderToSvg, renderToPng } from "@json-render/image/render";
import { standardComponentDefinitions } from "@json-render/image/catalog";

const svg = await renderToSvg(spec, { width: 1200, height: 630 });
const png = await renderToPng(spec, { width: 1200, height: 630 });
```

9 standard components: Frame, Box, Row, Column, Heading, Text, Image, Divider, Spacer. Server-safe import path at `@json-render/image/server`.

---

## v0.10.0

February 25, 2026

### New: `@json-render/vue`

Vue 3 renderer for json-render with full feature parity with `@json-render/react`. Data binding, visibility conditions, actions, validation, repeat scopes, streaming, and external store support.

```bash
npm install @json-render/core @json-render/vue
```

```typescript
import { h } from "vue";
import { defineRegistry, Renderer } from "@json-render/vue";
import { schema } from "@json-render/vue/schema";

const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) =>
      h("div", { class: "card" }, [h("h3", null, props.title), children]),
    Button: ({ props, emit }) =>
      h("button", { onClick: () => emit("press") }, props.label),
  },
});
```

Providers: `StateProvider`, `ActionProvider`, `VisibilityProvider`, `ValidationProvider`. Composables: `useStateStore`, `useStateValue`, `useActions`, `useAction`, `useIsVisible`, `useFieldValidation`, `useBoundProp`, `useUIStream`, `useChatUI`.

See the [Vue API reference](/docs/api/vue) for details.

### New: `@json-render/xstate`

[XState Store](https://stately.ai/docs/xstate-store) (atom) adapter for json-render's `StateStore` interface. Wire an `@xstate/store` atom as the state backend for any renderer.

```bash
npm install @json-render/xstate @xstate/store
```

```typescript
import { createAtom } from "@xstate/store";
import { xstateStoreStateStore } from "@json-render/xstate";

const atom = createAtom({ count: 0 });
const store = xstateStoreStateStore({ atom });
```

Requires `@xstate/store` v3+.

### New: `$computed` and `$template` Expressions

Two new prop expression types for dynamic values:

- **`$template`** -- interpolate state values into strings: `{ "$template": "Hello, ${/user/name}!" }`
- **`$computed`** -- call registered functions: `{ "$computed": "fullName", "args": { "first": { "$state": "/form/firstName" } } }`

Register functions via the `functions` prop on `JSONUIProvider` or `createRenderer`. See [Computed Values](/docs/computed-values) for details.

### New: State Watchers

Elements can declare a `watch` field to trigger actions when state values change. Useful for cascading dependencies like country/city selects.

```json
{
  "type": "Select",
  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
  "watch": {
    "/form/country": { "action": "loadCities", "params": { "country": { "$state": "/form/country" } } }
  }
}
```

`watch` is a top-level field on elements (sibling of type/props/children), not inside props. Watchers only fire on value changes, not on initial render. See [Watchers](/docs/watchers) for details.

### New: Cross-Field Validation

New built-in validation functions for cross-field comparisons:

- `equalTo` -- alias for `matches` with clearer semantics
- `lessThan` -- value must be less than another field
- `greaterThan` -- value must be greater than another field
- `requiredIf` -- required only when a condition field is truthy

Validation check args now resolve through `resolvePropValue`, so `$state` expressions work consistently.

### New: `validateForm` Action

Built-in action (React) that validates all registered form fields at once and writes `{ valid, errors }` to state:

```json
{
  "on": {
    "press": [
      { "action": "validateForm", "params": { "statePath": "/formResult" } },
      { "action": "submitForm" }
    ]
  }
}
```

### Improved: shadcn/ui Validation

All form components now support `checks` and `validateOn` props:
- Checkbox, Radio, Switch added validation support
- `validateOn` controls timing: `"change"` (default for Select, Checkbox, Radio, Switch), `"blur"` (default for Input, Textarea), or `"submit"`

### New Examples

- **Vue example** -- standalone Vue 3 app with custom components
- **Vite Renderers** -- side-by-side React and Vue renderers with shared catalog

---

## v0.9.1

February 24, 2026

### Fixed: Install failure due to private dependency

`@json-render/react`, `@json-render/react-pdf`, and `@json-render/react-native` v0.9.0 failed to install because `@internal/react-state` (a private workspace package) was published as a dependency. The internal package is now bundled into each renderer at build time, so it no longer needs to be resolved from npm.

---

## v0.9.0

February 24, 2026

### New: External State Store

The `StateStore` interface lets you plug in your own state management (Redux, Zustand, Jotai, XState, etc.) instead of the built-in internal store. Pass a `store` prop to `StateProvider`, `JSONUIProvider`, or `createRenderer` for controlled mode.

- Added `StateStore` interface and `createStateStore()` factory to `@json-render/core`
- `StateProvider`, `JSONUIProvider`, and `createRenderer` now accept an optional `store` prop
- When `store` is provided, it becomes the single source of truth (`initialState`/`onStateChange` are ignored)
- When `store` is omitted, everything works exactly as before (fully backward compatible)
- Applied across all platform packages: react, react-native, react-pdf
- Store utilities (`createStoreAdapter`, `immutableSetByPath`, `flattenToPointers`) available via `@json-render/core/store-utils` for building custom adapters

New adapter packages: `@json-render/redux`, `@json-render/zustand`, `@json-render/jotai`.

See the [Data Binding](/docs/data-binding#external-store-controlled-mode) guide for usage.

### Changed: `onStateChange` signature updated (breaking)

The `onStateChange` callback now receives a single array of changed entries instead of being called once per path. This makes batch updates via `update()` easier to handle:

```ts
// Before
onStateChange?: (path: string, value: unknown) => void

// After
onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
```

The callback is only called when a `set()` or `update()` call actually changes the state. A `set()` call produces a single-element array; an `update()` call produces one array with all changed paths.

### Fixed: Server-safe schema import

`@json-render/react` barrel-imports React contexts that call `createContext`, which crashes in Next.js App Router API routes (RSC runtime strips `createContext`). All docs, examples, and skills now import `schema` from `@json-render/react/schema` instead of `@json-render/react`.

For combined imports, split into separate `schema` (subpath) and client API (main entry) lines:

```ts
import { schema } from "@json-render/react/schema";
import { defineRegistry, Renderer } from "@json-render/react";
```

### Fixed: Chaining actions

Fixed an issue where chaining multiple actions on the same event (e.g. `setState` followed by a custom action) did not execute all actions. Affected `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`.

### Fixed: Zod array inner type resolution

Fixed safely resolving the inner type for Zod arrays in schema introspection, preventing errors when catalog component props use `z.array()`.

---

## v0.8.0

February 20, 2026

### New: `@json-render/react-pdf`

PDF renderer for json-render, powered by [`@react-pdf/renderer`](https://react-pdf.org/). Define catalogs and registries the same way as `@json-render/react`, but output PDF documents instead of web UI.

```bash
npm install @json-render/core @json-render/react-pdf
```

```typescript
import { renderToBuffer } from "@json-render/react-pdf";
import type { Spec } from "@json-render/core";

const spec: Spec = {
  root: "doc",
  elements: {
    doc: { type: "Document", props: { title: "Invoice" }, children: ["page"] },
    page: {
      type: "Page",
      props: { size: "A4" },
      children: ["heading", "table"],
    },
    heading: {
      type: "Heading",
      props: { text: "Invoice #1234", level: "h1" },
      children: [],
    },
    table: {
      type: "Table",
      props: {
        columns: [
          { header: "Item", width: "60%" },
          { header: "Price", width: "40%", align: "right" },
        ],
        rows: [
          ["Widget A", "$10.00"],
          ["Widget B", "$25.00"],
        ],
      },
      children: [],
    },
  },
};

const buffer = await renderToBuffer(spec);
```

Server-side rendering APIs:

- `renderToBuffer(spec)` -- render to an in-memory PDF buffer
- `renderToStream(spec)` -- render to a readable stream (pipe to HTTP response)
- `renderToFile(spec, path)` -- render directly to a file

15 standard components covering document structure (Document, Page), layout (View, Row, Column), content (Heading, Text, Image, Link), data (Table, List), decorative (Divider, Spacer), and page-level (PageNumber).

Supports custom catalogs with `defineRegistry`, server-safe imports via `@json-render/react-pdf/server`, and full context support (state, visibility, actions, validation, repeat scopes).

---

## v0.7.0

February 17, 2026

### New: `@json-render/shadcn`

Pre-built [shadcn/ui](https://ui.shadcn.com/) component library for json-render. 36 components built on Radix UI + Tailwind CSS, ready to use with `defineCatalog` and `defineRegistry`.

```bash
npm install @json-render/shadcn
```

```typescript
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { defineRegistry } from "@json-render/react";
import { shadcnComponents } from "@json-render/shadcn";

const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Button: shadcnComponentDefinitions.Button,
    Input: shadcnComponentDefinitions.Input,
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Button: shadcnComponents.Button,
    Input: shadcnComponents.Input,
  },
});
```

Components include: layout (Card, Stack, Grid, Separator), navigation (Tabs, Accordion, Collapsible, Pagination), overlay (Dialog, Drawer, Tooltip, Popover, DropdownMenu), content (Heading, Text, Image, Avatar, Badge, Alert, Carousel, Table), feedback (Progress, Skeleton, Spinner), and input (Button, Link, Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Toggle, ToggleGroup, ButtonGroup).

See the [API reference](/docs/api/shadcn) for full details.

### New: Event Handles (`on()`)

Components now receive an `on(event)` function in addition to `emit(event)`. The `on()` function returns an `EventHandle` with metadata:

- `emit()` -- fire the event
- `shouldPreventDefault` -- whether any action binding requested `preventDefault`
- `bound` -- whether any handler is bound to this event

```tsx
Link: ({ props, on }) => {
  const click = on("click");
  return (
    <a href={props.href} onClick={(e) => {
      if (click.shouldPreventDefault) e.preventDefault();
      click.emit();
    }}>{props.label}</a>
  );
},
```

### New: `BaseComponentProps`

Catalog-agnostic base type for component render functions. Use when building reusable component libraries (like `@json-render/shadcn`) that are not tied to a specific catalog.

```typescript
import type { BaseComponentProps } from "@json-render/react";

const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) => (
  <div>{props.title}{children}</div>
);
```

### New: Built-in Actions in Schema

Schemas can now declare `builtInActions` -- actions that are always available at runtime and automatically injected into prompts. The React schema declares `setState`, `pushState`, and `removeState` as built-in, so they appear in prompts without needing to be listed in catalog `actions`.

### New: `preventDefault` on `ActionBinding`

Action bindings now support a `preventDefault` boolean field, allowing the LLM to request that default browser behavior (e.g. navigation on links) be prevented.

### Improved: Stream Transform Text Block Splitting

`createJsonRenderTransform()` now properly splits text blocks around spec data by emitting `text-end`/`text-start` pairs. This ensures the AI SDK creates separate text parts, preserving correct interleaving of prose and UI in `message.parts`.

### Improved: `defineRegistry` Actions Requirement

`defineRegistry` now conditionally requires the `actions` field only when the catalog declares actions. Catalogs with no actions (e.g. `actions: {}`) no longer need to pass an empty actions object.

---

## v0.6.0

February 13, 2026

### New: Chat Mode (Inline GenUI)

> **Note:** These modes were renamed in v0.12.1 — "Generate" is now "Standalone" and "Chat" is now "Inline". The old names are accepted as deprecated aliases.

json-render now supports two generation modes: **Generate** (JSONL-only, the default) and **Chat** (text + JSONL inline). Chat mode lets the AI respond conversationally with embedded UI specs, ideal for chatbots and copilot experiences.

```typescript
// Generate mode (default) — AI outputs only JSONL
const prompt = catalog.prompt();

// Chat mode — AI outputs text + JSONL inline
const chatPrompt = catalog.prompt({ mode: "chat" });
```

On the server, `pipeJsonRender()` separates text from JSONL patches in a mixed stream:

```typescript
import { pipeJsonRender } from "@json-render/core";
import { createUIMessageStream, createUIMessageStreamResponse } from "ai";

const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    writer.merge(pipeJsonRender(result.toUIMessageStream()));
  },
});
return createUIMessageStreamResponse({ stream });
```

On the client, `useJsonRenderMessage` extracts the spec and text from message parts:

```tsx
import { useJsonRenderMessage } from "@json-render/react";

function ChatMessage({ message }) {
  const { spec, text, hasSpec } = useJsonRenderMessage(message.parts);
  return (
    <div>
      {text && <Markdown>{text}</Markdown>}
      {hasSpec && <Renderer spec={spec} registry={registry} />}
    </div>
  );
}
```

### New: AI SDK Integration

First-class Vercel AI SDK support with typed data parts and stream utilities.

- `SpecDataPart` type for `data-spec` stream parts (patch, flat, nested payloads)
- `SPEC_DATA_PART` / `SPEC_DATA_PART_TYPE` constants for type-safe part filtering
- `createJsonRenderTransform()` low-level TransformStream for custom pipelines
- `createMixedStreamParser()` for parsing mixed text + JSONL streams

### New: Two-Way Binding

Props can now use `$bindState` and `$bindItem` expressions for two-way data binding. The renderer resolves bindings and passes a `bindings` map to components, enabling write-back to state without custom `valuePath` props.

```json
{
  "type": "Input",
  "props": { "label": "Email", "value": { "$bindState": "/form/email" } }
}
```

```tsx
import { useBoundProp } from "@json-render/react";

Input: ({ props, bindings }) => {
  const [value, setValue] = useBoundProp<string>(props.value, bindings?.value);
  return <input value={value ?? ""} onChange={(e) => setValue(e.target.value)} />;
}
```

### New: Expression-Based Props and Visibility

All dynamic expressions now use structured `$state`, `$item`, and `$index` objects instead of string token rewriting. This is simpler, more explicit, and works for both props and visibility conditions.

**Props:**

```json
{ "title": { "$state": "/user/name" } }
{ "label": { "$item": "title" } }
{ "position": { "$index": true } }
```

**Visibility:**

```json
{ "$state": "/isAdmin" }
{ "$state": "/role", "eq": "admin" }
[{ "$state": "/isAdmin" }, { "$state": "/feature" }]
{ "$or": [{ "$state": "/roleA" }, { "$state": "/roleB" }] }
{ "$item": "isActive" }
{ "$index": true, "gt": 0 }
```

Comparison operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `not`.

### New: React Chat Hooks

- `useChatUI()` — full chat hook with message history, streaming, and spec extraction
- `useJsonRenderMessage()` — extract spec + text from a message's parts array
- `buildSpecFromParts()` / `getTextFromParts()` — utilities for working with AI SDK message parts
- `useBoundProp()` — two-way binding hook for `$bindState` / `$bindItem`

### New: Chat Example

Full-featured chat example (`examples/chat`) with AI agent, tool calls (crypto, GitHub, Hacker News, weather, search), theme toggle, and streaming inline UI generation.

### Improved: Renderer Performance

- `ElementRenderer` is now `React.memo`'d for better performance with repeat lists
- `emit` is always defined (never `undefined`)
- Repeat scope passes the actual item object, eliminating string token rewriting

### Improved: Utilities

- `applySpecPatch()` — typed wrapper for applying a single patch to a Spec
- `nestedToFlat()` — convert nested tree specs to flat format
- `resolveBindings()` / `resolveActionParam()` — resolve binding paths and action params

### Breaking Changes

- `{ $path }` and `{ path }` replaced by `{ $state }`, `{ $item }`, `{ $index }` in props
- Visibility: `{ path }` -> `{ $state }`, `{ and/or/not }` -> `{ $and/$or }` with `not` as operator flag
- `DynamicValue`: `{ path: string }` -> `{ $state: string }`
- `repeat.path` -> `repeat.statePath`
- Action params: `path` -> `statePath` in setState action
- `actionHandlers` -> `handlers` on `JSONUIProvider` / `ActionProvider`
- `AuthState` and `{ auth }` visibility conditions removed (model auth as regular state)
- Legacy catalog API removed: `createCatalog`, `generateCatalogPrompt`, `generateSystemPrompt`
- React exports removed: `createRendererFromCatalog`, `rewriteRepeatTokens`
- Codegen: `traverseTree` -> `traverseSpec`

See the [Migration Guide](/docs/migration) for detailed upgrade instructions.

---

## v0.5.0

February 9, 2026

### New: @json-render/react-native

Full React Native renderer with 25+ standard components, data binding, visibility, actions, and dynamic props. Build AI-generated native mobile UIs with the same catalog-driven approach as web.

```tsx
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react-native/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/react-native/catalog";
import { defineRegistry, Renderer } from "@json-render/react-native";

const catalog = defineCatalog(schema, {
  components: { ...standardComponentDefinitions },
  actions: standardActionDefinitions,
});

const { registry } = defineRegistry(catalog, { components: {} });

<Renderer spec={spec} registry={registry} />
```

Includes standard components for layout (Container, Row, Column, ScrollContainer, SafeArea, Pressable, Spacer, Divider), content (Heading, Paragraph, Label, Image, Avatar, Badge, Chip), input (Button, TextInput, Switch, Checkbox, Slider, SearchBar), feedback (Spinner, ProgressBar), and composite (Card, ListItem, Modal).

### New: Event System

Components now use `emit` to fire named events instead of directly dispatching actions. The element's `on` field maps events to action bindings, decoupling component logic from action handling.

```tsx
// Component emits a named event
Button: ({ props, emit }) => (
  <button onClick={() => emit("press")}>{props.label}</button>
),

// Element spec maps events to actions
{
  "type": "Button",
  "props": { "label": "Submit" },
  "on": { "press": { "action": "submit", "params": { "formId": "main" } } }
}
```

### New: Repeat/List Rendering

Elements can now iterate over state arrays using the `repeat` field. Child elements use `{ "$item": "field" }` to read from the current item and `{ "$index": true }` for the current array index.

```json
{
  "type": "Column",
  "repeat": { "statePath": "/posts", "key": "id" },
  "children": ["post-card"]
}
```

```json
{
  "type": "Card",
  "props": { "title": { "$item": "title" } }
}
```

### New: User Prompt Builder

Build structured user prompts with optional spec refinement and state context:

```typescript
import { buildUserPrompt } from "@json-render/core";

// Fresh generation
buildUserPrompt({ prompt: "create a todo app" });

// Refinement (patch-only mode)
buildUserPrompt({ prompt: "add a toggle", currentSpec: spec });

// With runtime state
buildUserPrompt({ prompt: "show data", state: { todos: [] } });
```

### New: Spec Validation

Validate spec structure and auto-fix common issues:

```typescript
import { validateSpec, autoFixSpec } from "@json-render/core";

const { valid, issues } = validateSpec(spec);
const fixed = autoFixSpec(spec);
```

### Improved: State Management

`DataProvider` has been renamed to `StateProvider` with a clearer API. State is now a first-class part of specs. Elements can bind to state via `$state` expressions, and the built-in `setState` action updates state directly.

### Improved: AI Prompts

Schema prompts now include streaming best practices, repeat/list examples, and state patching guidance. Schemas can also define `defaultRules` that are always included in generated prompts.

### Improved: Documentation

- All documentation pages migrated to MDX
- AI-powered documentation chat
- Dynamic Open Graph images for all docs pages
- Improved playground

### Breaking Changes

- `DataProvider` renamed to `StateProvider`
- `useData` renamed to `useStateStore`, `useDataValue` to `useStateValue`, `useDataBinding` to `useStateBinding`
- `onAction` renamed to `emit` in component context
- `DataModel` type renamed to `StateModel`
- `Action` type renamed to `ActionBinding` (old name still available but deprecated)

---

## v0.4.0

February 5, 2026

### New: Custom Schema System

Create custom output formats with `defineSchema`. Each renderer now defines its own schema, enabling completely different spec formats for different use cases.

```typescript
import { defineSchema } from "@json-render/core";

const mySchema = defineSchema((s) => ({
  spec: s.object({
    pages: s.array(s.object({
      title: s.string(),
      blocks: s.array(s.ref("catalog.blocks")),
    })),
  }),
  catalog: s.object({
    blocks: s.map({ props: s.zod(), description: s.string() }),
  }),
}), {
  promptTemplate: myPromptTemplate,
});
```

### New: Component Slots

Components can now define which slots they accept. Use `["default"]` for regular children, or named slots like `["header", "footer"]` for more complex layouts.

```typescript
const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({ title: z.string() }),
      slots: ["default"],  // accepts children
      description: "A card container",
    },
    Layout: {
      props: z.object({}),
      slots: ["header", "content", "footer"],  // named slots
      description: "Page layout with header, content, footer",
    },
  },
});
```

### New: AI Prompt Generation

Catalogs now generate AI system prompts automatically with `catalog.prompt()`. The prompt includes all component definitions, props schemas, and action descriptions - ensuring the AI only generates valid specs.

```typescript
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";

const catalog = defineCatalog(schema, {
  components: { /* ... */ },
  actions: { /* ... */ },
});

// Generate system prompt for AI
const systemPrompt = catalog.prompt();

// Use with any AI SDK
const result = await streamText({
  model: "claude-haiku-4.5",
  system: systemPrompt,
  prompt: userMessage,
});
```

### New: @json-render/remotion

Generate AI-powered videos with Remotion. Define video catalogs, stream timeline specs, and render with the Remotion Player.

```tsx
import { Player } from "@remotion/player";
import { Renderer, schema, standardComponentDefinitions } from "@json-render/remotion";

const catalog = defineCatalog(schema, {
  components: standardComponentDefinitions,
  transitions: standardTransitionDefinitions,
});

<Player
  component={Renderer}
  inputProps={{ spec }}
  durationInFrames={spec.composition.durationInFrames}
  fps={spec.composition.fps}
  compositionWidth={spec.composition.width}
  compositionHeight={spec.composition.height}
/>
```

Includes 10 standard video components (TitleCard, TypingText, SplitScreen, etc.), 7 transition types, and the ClipWrapper utility for custom components.

### New: SpecStream

SpecStream is json-render's streaming format for progressively building specs from JSONL patches. The new compiler API makes it easy to process streaming AI responses.

```typescript
import { createSpecStreamCompiler } from "@json-render/core";

const compiler = createSpecStreamCompiler<MySpec>();

// Process streaming chunks
const { result, newPatches } = compiler.push(chunk);
setSpec(result); // Update UI with partial result
```

### Improved: Dashboard Example

The dashboard example is now a full-featured accounting dashboard with:

- Persistent SQLite database with Drizzle ORM
- RESTful API for customers, invoices, expenses, accounts
- Draggable widget reordering
- AI-powered widget generation with streaming
- Real data binding to database records

### Improved: Documentation

- Interactive playground for testing specs
- New guides: Custom Schema, Streaming, Code Export
- Full API reference for all packages
- Integration guides: A2UI, AG-UI, Adaptive Cards, OpenAPI

### Breaking Changes

- `UITree` type renamed to `Spec`
- Schema is now imported from renderer packages (`@json-render/react`) not core
- `defineCatalog` now requires a schema as first argument

---

## v0.3.0

January 20, 2026

Internal release with codegen foundations.

- Added `@json-render/codegen` package (spec traversal and JSX serialization)
- Configurable AI model via environment variables
- Documentation improvements and bug fixes

*Note: Only @json-render/core was published to npm for this release.*

---

## v0.2.0

January 14, 2026

Initial public release.

- Core catalog and spec types
- React renderer with contexts for data, actions, visibility
- AI prompt generation from catalogs
- Basic streaming support
- Dashboard example application