feat: Add @xstate/store (atom) support (#157)

* feat: add @xstate/store integration using atoms

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add README for @json-render/xstate-store

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: rename xstateStoreStateStore to xstateStore

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* README updates

* Keep naming convention

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.changeset/config.json

@@ -10,7 +10,10 @@
       "@json-render/shadcn",
       "@json-render/react-native",
       "@json-render/remotion",
-      "@json-render/codegen"
+      "@json-render/codegen",
+      "@json-render/zustand",
+      "@json-render/redux",
+      "@json-render/jotai"
     ]
   ],
   "linked": [],
@@ -18,7 +21,7 @@
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "privatePackages": {
-    "version": false,
+    "version": true,
     "tag": false
   }
 }

README.md

@@ -32,7 +32,7 @@ json-render is a **Generative UI** framework: AI generates interfaces from natur
 
 ```typescript
 import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
 import { z } from "zod";
 
 const catalog = defineCatalog(schema, {
@@ -124,7 +124,7 @@ function Dashboard({ spec }) {
 
 ```tsx
 import { defineRegistry, Renderer } from "@json-render/react";
-import { schema } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
 
 // Flat spec format (root key + elements map)
 const spec = {
@@ -152,7 +152,8 @@ const { registry } = defineRegistry(catalog, { components });
 
 ```tsx
 import { defineCatalog } from "@json-render/core";
-import { schema, defineRegistry, Renderer } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
+import { defineRegistry, Renderer } from "@json-render/react";
 import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
 import { shadcnComponents } from "@json-render/shadcn";
 

apps/web/CHANGELOG.md

@@ -0,0 +1,19 @@
+# web
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+  - @json-render/codegen@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0
+  - @json-render/codegen@0.9.0

apps/web/app/(main)/docs/a2ui/page.mdx

@@ -67,7 +67,7 @@ A2UI uses an adjacency list model - a flat list of components with ID references
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 // A2UI BoundValue schema

apps/web/app/(main)/docs/adaptive-cards/page.mdx

@@ -90,7 +90,7 @@ Define a catalog matching the Adaptive Cards element types:
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 // Common Adaptive Cards properties

apps/web/app/(main)/docs/ag-ui/page.mdx

@@ -151,7 +151,7 @@ Create a catalog for UI components that agents can render:
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 export const aguiCatalog = defineCatalog(schema, {

apps/web/app/(main)/docs/api/core/page.mdx

@@ -11,7 +11,7 @@ Creates a type-safe catalog definition with schema validation.
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 
 function defineCatalog<T extends ZodType>(
   s: T,
@@ -119,7 +119,7 @@ The schema for flat UI element trees. This is exported from @json-render/react.
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 
 // schema defines:
 // - Spec shape: { root: string, elements: Record<string, UIElement> }

apps/web/app/(main)/docs/catalog/page.mdx

@@ -19,7 +19,7 @@ A catalog is the vocabulary for your UI. While the [schema](/docs/schemas) defin
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react'; // or '@json-render/react-native'
+import { schema } from '@json-render/react/schema'; // or '@json-render/react-native/schema'
 import { z } from 'zod';
 
 const catalog = defineCatalog(schema, {

apps/web/app/(main)/docs/changelog/page.mdx

@@ -5,7 +5,17 @@ export const metadata = pageMetadata("docs/changelog")
 
 Notable changes and updates to json-render.
 
-## v0.8.0
+## v0.9.1
+
+February 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 2026
 
@@ -13,8 +23,17 @@ February 2026
 
 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:
@@ -29,6 +48,31 @@ 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 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.

apps/web/app/(main)/docs/installation/page.mdx

@@ -25,6 +25,18 @@ Requires Tailwind CSS in your project. See the [@json-render/shadcn API referenc
 
 <PackageInstall packages="@json-render/core @json-render/remotion remotion @remotion/player" />
 
+## For External State Management (Optional)
+
+If you want to wire json-render to an existing state management library instead of the built-in store, install the adapter for your library:
+
+<PackageInstall packages="@json-render/zustand" />
+
+<PackageInstall packages="@json-render/redux" />
+
+<PackageInstall packages="@json-render/jotai" />
+
+See the [Data Binding](/docs/data-binding#external-store-controlled-mode) guide for usage.
+
 ## Peer Dependencies
 
 json-render requires the following peer dependencies:

apps/web/app/(main)/docs/openapi/page.mdx

@@ -100,7 +100,7 @@ Create components that map to OpenAPI data types:
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 export const openapiCatalog = defineCatalog(schema, {

apps/web/app/(main)/docs/page.mdx

@@ -23,7 +23,7 @@ A catalog declares what AI can use: components with typed props, actions with ty
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 export const catalog = defineCatalog(schema, {

apps/web/app/(main)/docs/quick-start/page.mdx

@@ -12,7 +12,7 @@ Create a catalog that defines what components AI can use:
 ```typescript
 // lib/catalog.ts
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 export const catalog = defineCatalog(schema, {

apps/web/app/(main)/docs/registry/page.mdx

@@ -133,7 +133,7 @@ Actions are declared in your [catalog](/docs/catalog). The `@json-render/react`
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react';
+import { schema } from '@json-render/react/schema';
 import { z } from 'zod';
 
 const catalog = defineCatalog(schema, {

apps/web/app/(main)/docs/validation/page.mdx

@@ -67,7 +67,7 @@ Define custom validators in your catalog's `functions` field. The catalog itself
 
 ```typescript
 import { defineCatalog } from '@json-render/core';
-import { schema } from '@json-render/react'; // or '@json-render/react-native'
+import { schema } from '@json-render/react/schema'; // or '@json-render/react-native/schema'
 import { z } from 'zod';
 
 const catalog = defineCatalog(schema, {

apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": true,
   "license": "Apache-2.0",

examples/chat/CHANGELOG.md

@@ -0,0 +1,19 @@
+# example-chat
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/shadcn@0.9.1
+  - @json-render/core@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0
+  - @json-render/shadcn@0.9.0

examples/chat/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-chat",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": true,
   "scripts": {

examples/dashboard/CHANGELOG.md

@@ -0,0 +1,19 @@
+# example-dashboard
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+  - @json-render/codegen@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0
+  - @json-render/codegen@0.9.0

examples/dashboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-dashboard",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": true,
   "scripts": {

examples/no-ai/CHANGELOG.md

@@ -0,0 +1,19 @@
+# example-no-ai
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/shadcn@0.9.1
+  - @json-render/core@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0
+  - @json-render/shadcn@0.9.0

examples/no-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-no-ai",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": true,
   "scripts": {

examples/react-native/CHANGELOG.md

@@ -0,0 +1,17 @@
+# example-react-native
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react-native@0.9.1
+  - @json-render/core@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react-native@0.9.0

examples/react-native/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-react-native",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": true,
   "main": "expo-router/entry",
   "scripts": {

examples/react-pdf/CHANGELOG.md

@@ -0,0 +1,17 @@
+# example-react-pdf
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react-pdf@0.9.1
+  - @json-render/core@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react-pdf@0.9.0

examples/react-pdf/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-react-pdf",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": true,
   "scripts": {

examples/remotion/CHANGELOG.md

@@ -0,0 +1,16 @@
+# example-remotion
+
+## 0.1.2
+
+### Patch Changes
+
+- @json-render/core@0.9.1
+- @json-render/remotion@0.9.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/remotion@0.9.0

examples/remotion/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-remotion",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": true,
   "scripts": {

examples/stripe-app/drawer-app/CHANGELOG.md

@@ -0,0 +1,17 @@
+# com.example.json-render-demo
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0

examples/stripe-app/drawer-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.example.json-render-demo",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Test",
   "private": true,
   "license": "~~proprietary~~",

examples/stripe-app/drawer-app/src/lib/render/catalog.ts

@@ -1,5 +1,5 @@
 import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
 import { z } from "zod";
 
 /**

examples/stripe-app/fullpage-app/CHANGELOG.md

@@ -0,0 +1,17 @@
+# com.example.json-render-fullpage-demo
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0

examples/stripe-app/fullpage-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.example.json-render-fullpage-demo",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Full-page Stripe App example (alpha)",
   "private": true,
   "license": "~~proprietary~~",

examples/stripe-app/fullpage-app/src/lib/render/catalog.ts

@@ -1,5 +1,5 @@
 import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
 import { z } from "zod";
 
 /**

packages/codegen/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @json-render/codegen
 
+## 0.9.1
+
+### Patch Changes
+
+- @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+
 ## 0.8.0
 
 ### Patch Changes

packages/codegen/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/codegen",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "Utilities for generating code from json-render UI trees",
   "keywords": [

packages/core/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @json-render/core
 
+## 0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
 ## 0.8.0
 
 ### Minor Changes

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/core",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "JSON becomes real things. Define your catalog, register your components, let AI generate.",
   "keywords": [

packages/jotai/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @json-render/jotai
+
+## 0.9.1
+
+### Patch Changes
+
+- @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0

packages/jotai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/jotai",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "Jotai adapter for json-render StateStore",
   "keywords": [

packages/react-native/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @json-render/react-native
 
+## 0.9.1
+
+### Patch Changes
+
+- b103676: Fix install failure caused by `@internal/react-state` (a private workspace package) being listed as a published dependency. The internal package is now bundled into each renderer's output at build time, so consumers no longer need to resolve it from npm.
+  - @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @internal/react-state@0.8.1
+
 ## 0.8.0
 
 ### Patch Changes

packages/react-native/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/react-native",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "React Native renderer for @json-render/core. JSON becomes React Native components.",
   "keywords": [
@@ -56,10 +56,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@json-render/core": "workspace:*",
-    "@internal/react-state": "workspace:*"
+    "@json-render/core": "workspace:*"
   },
   "devDependencies": {
+    "@internal/react-state": "workspace:*",
     "@internal/typescript-config": "workspace:*",
     "@types/react": "19.2.3",
     "react-native": "0.83.1",

packages/react-native/tsup.config.ts

@@ -3,8 +3,9 @@ import { defineConfig } from "tsup";
 export default defineConfig({
   entry: ["src/index.ts", "src/schema.ts", "src/catalog.ts"],
   format: ["cjs", "esm"],
-  dts: true,
+  dts: { resolve: ["@internal/react-state"] },
   sourcemap: true,
   clean: true,
+  noExternal: ["@internal/react-state"],
   external: ["react", "react-native", "@json-render/core", "zod"],
 });

packages/react-pdf/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @json-render/react-pdf
 
+## 0.9.1
+
+### Patch Changes
+
+- b103676: Fix install failure caused by `@internal/react-state` (a private workspace package) being listed as a published dependency. The internal package is now bundled into each renderer's output at build time, so consumers no longer need to resolve it from npm.
+  - @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @internal/react-state@0.8.1
+
 ## 0.8.0
 
 ### Minor Changes

packages/react-pdf/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/react-pdf",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "React PDF renderer for @json-render/core. JSON becomes PDF documents.",
   "keywords": [
@@ -61,10 +61,10 @@
   },
   "dependencies": {
     "@json-render/core": "workspace:*",
-    "@internal/react-state": "workspace:*",
     "@react-pdf/renderer": "^4.3.2"
   },
   "devDependencies": {
+    "@internal/react-state": "workspace:*",
     "@internal/typescript-config": "workspace:*",
     "@types/react": "19.2.3",
     "tsup": "^8.0.2",

packages/react-pdf/tsup.config.ts

@@ -3,8 +3,9 @@ import { defineConfig } from "tsup";
 export default defineConfig({
   entry: ["src/index.ts", "src/server.ts", "src/catalog.ts", "src/render.tsx"],
   format: ["cjs", "esm"],
-  dts: true,
+  dts: { resolve: ["@internal/react-state"] },
   sourcemap: true,
   clean: true,
+  noExternal: ["@internal/react-state"],
   external: ["react", "@json-render/core", "@react-pdf/renderer", "zod"],
 });

packages/react-state/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @internal/react-state
+
+## 0.8.2
+
+### Patch Changes
+
+- @json-render/core@0.9.1
+
+## 0.8.1
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0

packages/react-state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@internal/react-state",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "private": true,
   "license": "Apache-2.0",
   "description": "Shared React state context for json-render renderer packages",

packages/react/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @json-render/react
 
+## 0.9.1
+
+### Patch Changes
+
+- b103676: Fix install failure caused by `@internal/react-state` (a private workspace package) being listed as a published dependency. The internal package is now bundled into each renderer's output at build time, so consumers no longer need to resolve it from npm.
+  - @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @internal/react-state@0.8.1
+
 ## 0.8.0
 
 ### Patch Changes

packages/react/README.md

@@ -14,7 +14,7 @@ npm install @json-render/react @json-render/core zod
 
 ```typescript
 import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
 import { z } from "zod";
 
 export const catalog = defineCatalog(schema, {
@@ -409,7 +409,8 @@ const systemPrompt = catalog.prompt();
 
 ```tsx
 import { defineCatalog } from "@json-render/core";
-import { schema, defineRegistry, Renderer } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
+import { defineRegistry, Renderer } from "@json-render/react";
 import { z } from "zod";
 
 const catalog = defineCatalog(schema, {

packages/react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/react",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "React renderer for @json-render/core. JSON becomes React components.",
   "keywords": [
@@ -50,10 +50,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@json-render/core": "workspace:*",
-    "@internal/react-state": "workspace:*"
+    "@json-render/core": "workspace:*"
   },
   "devDependencies": {
+    "@internal/react-state": "workspace:*",
     "@internal/typescript-config": "workspace:*",
     "@types/react": "19.2.3",
     "tsup": "^8.0.2",

packages/react/tsup.config.ts

@@ -3,8 +3,9 @@ import { defineConfig } from "tsup";
 export default defineConfig({
   entry: ["src/index.ts", "src/schema.ts"],
   format: ["cjs", "esm"],
-  dts: true,
+  dts: { resolve: ["@internal/react-state"] },
   sourcemap: true,
   clean: true,
+  noExternal: ["@internal/react-state"],
   external: ["react", "react-dom", "@json-render/core"],
 });

packages/redux/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @json-render/redux
+
+## 0.9.1
+
+### Patch Changes
+
+- @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0

packages/redux/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/redux",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "Redux adapter for json-render StateStore",
   "keywords": [

packages/remotion/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @json-render/remotion
 
+## 0.9.1
+
+### Patch Changes
+
+- @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+
 ## 0.8.0
 
 ### Patch Changes

packages/remotion/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/remotion",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "Remotion renderer for @json-render/core. JSON becomes video compositions.",
   "keywords": [

packages/shadcn/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @json-render/shadcn
 
+## 0.9.1
+
+### Patch Changes
+
+- Updated dependencies [b103676]
+  - @json-render/react@0.9.1
+  - @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0
+  - @json-render/react@0.9.0
+
 ## 0.8.0
 
 ### Patch Changes

packages/shadcn/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/shadcn",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "shadcn/ui component library for @json-render/core. JSON becomes beautiful Tailwind-styled React components.",
   "keywords": [

packages/xstate-store/README.md

@@ -0,0 +1,43 @@
+# @json-render/xstate-store
+
+[XState Store](https://stately.ai/docs/xstate-store) adapter for json-render's `StateStore` interface. Wire an `@xstate/store` atom as the state backend for json-render.
+
+## Installation
+
+```bash
+npm install @json-render/xstate-store @json-render/core @json-render/react @xstate/store
+```
+
+> [!NOTE]
+> This adapter requires `@xstate/store` v3+.
+
+## Usage
+
+```ts
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "@json-render/xstate-store";
+import { StateProvider } from "@json-render/react";
+
+// 1. Create an atom
+const uiAtom = createAtom({ count: 0 });
+
+// 2. Create the json-render StateStore adapter
+const store = xstateStoreStateStore({ atom: uiAtom });
+
+// 3. Use it
+<StateProvider store={store}>
+  {/* json-render reads/writes go through @xstate/store */}
+</StateProvider>
+```
+
+## API
+
+### `xstateStoreStateStore(options)`
+
+Creates a `StateStore` backed by an `@xstate/store` atom.
+
+#### Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `atom` | `Atom<StateModel>` | Yes | An `@xstate/store` atom (from `createAtom`) holding the json-render state model |

packages/xstate-store/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@json-render/xstate-store",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "description": "XState Store adapter for json-render StateStore",
+  "keywords": [
+    "json-render",
+    "xstate",
+    "xstate-store",
+    "state-management",
+    "adapter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/json-render.git",
+    "directory": "packages/xstate-store"
+  },
+  "homepage": "https://github.com/vercel-labs/json-render#readme",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/json-render/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@json-render/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "@xstate/store": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "workspace:*",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "@xstate/store": "^3.0.0"
+  }
+}

packages/xstate-store/src/index.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from "vitest";
+import { createAtom } from "@xstate/store";
+import { xstateStoreStateStore } from "./index";
+
+function createTestStore(initial: Record<string, unknown> = {}) {
+  const atom = createAtom<Record<string, unknown>>(initial);
+  const store = xstateStoreStateStore({ atom });
+  return { atom, store };
+}
+
+describe("xstateStoreStateStore", () => {
+  it("get/set round-trip", () => {
+    const { store } = createTestStore({ count: 0 });
+
+    expect(store.get("/count")).toBe(0);
+
+    store.set("/count", 42);
+
+    expect(store.get("/count")).toBe(42);
+    expect(store.getSnapshot().count).toBe(42);
+  });
+
+  it("update round-trip with multiple values", () => {
+    const { store } = createTestStore({});
+
+    store.update({ "/a": 1, "/b": "hello" });
+
+    expect(store.get("/a")).toBe(1);
+    expect(store.get("/b")).toBe("hello");
+    expect(store.getSnapshot()).toEqual({ a: 1, b: "hello" });
+  });
+
+  it("subscribe fires on set", () => {
+    const { store } = createTestStore({});
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.set("/x", 1);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it("subscribe fires on update", () => {
+    const { store } = createTestStore({});
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.update({ "/a": 1, "/b": 2 });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it("unsubscribe stops notifications", () => {
+    const { store } = createTestStore({});
+    const listener = vi.fn();
+    const unsub = store.subscribe(listener);
+
+    store.set("/x", 1);
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unsub();
+    store.set("/x", 2);
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it("getSnapshot immutability -- previous snapshot is not mutated", () => {
+    const { store } = createTestStore({
+      user: { name: "Alice", age: 30 },
+    });
+    const snap1 = store.getSnapshot();
+
+    store.set("/user/name", "Bob");
+    const snap2 = store.getSnapshot();
+
+    expect(snap1.user).toEqual({ name: "Alice", age: 30 });
+    expect((snap2.user as Record<string, unknown>).name).toBe("Bob");
+    expect(snap1.user).not.toBe(snap2.user);
+  });
+
+  it("structural sharing -- untouched branches keep references", () => {
+    const { store } = createTestStore({
+      a: { x: 1 },
+      b: { y: 2 },
+    });
+    const snap1 = store.getSnapshot();
+
+    store.set("/a/x", 99);
+    const snap2 = store.getSnapshot();
+
+    expect(snap2.b).toBe(snap1.b);
+    expect(snap2.a).not.toBe(snap1.a);
+  });
+
+  it("getServerSnapshot returns same as getSnapshot", () => {
+    const { store } = createTestStore({ x: 1 });
+
+    expect(store.getServerSnapshot!()).toBe(store.getSnapshot());
+
+    store.set("/x", 2);
+    expect(store.getServerSnapshot!()).toBe(store.getSnapshot());
+  });
+
+  it("set skips update when value is unchanged", () => {
+    const { store } = createTestStore({ x: 1 });
+    const snap1 = store.getSnapshot();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.set("/x", 1);
+
+    expect(listener).not.toHaveBeenCalled();
+    expect(store.getSnapshot()).toBe(snap1);
+  });
+
+  it("update skips update when no values changed", () => {
+    const { store } = createTestStore({ a: 1, b: 2 });
+    const snap1 = store.getSnapshot();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.update({ "/a": 1, "/b": 2 });
+
+    expect(listener).not.toHaveBeenCalled();
+    expect(store.getSnapshot()).toBe(snap1);
+  });
+
+  it("reads from the shared atom", () => {
+    const atom = createAtom<Record<string, unknown>>({ count: 0 });
+    const store = xstateStoreStateStore({ atom });
+
+    atom.set({ count: 99 });
+
+    expect(store.get("/count")).toBe(99);
+    expect(store.getSnapshot().count).toBe(99);
+  });
+});

packages/xstate-store/src/index.ts

@@ -0,0 +1,45 @@
+import type { StateModel, StateStore } from "@json-render/core";
+import { createStoreAdapter } from "@json-render/core/store-utils";
+import type { Atom } from "@xstate/store";
+
+export type { StateStore } from "@json-render/core";
+
+/**
+ * Options for {@link xstateStoreStateStore}.
+ */
+export interface XstateStoreStateStoreOptions {
+  /** An `@xstate/store` atom (created with `createAtom`). */
+  atom: Atom<StateModel>;
+}
+
+/**
+ * Create a {@link StateStore} backed by an `@xstate/store` atom.
+ *
+ * @example
+ * ```ts
+ * import { createAtom } from "@xstate/store";
+ * import { xstateStoreStateStore } from "@json-render/xstate-store";
+ *
+ * const uiAtom = createAtom<Record<string, unknown>>({ count: 0 });
+ *
+ * const store = xstateStoreStateStore({ atom: uiAtom });
+ *
+ * <StateProvider store={store}>...</StateProvider>
+ * ```
+ */
+export function xstateStoreStateStore(
+  options: XstateStoreStateStoreOptions,
+): StateStore {
+  const { atom } = options;
+
+  return createStoreAdapter({
+    getSnapshot: () => atom.get(),
+    setSnapshot: (next) => atom.set(next),
+    subscribe(listener) {
+      const sub = atom.subscribe(() => {
+        listener();
+      });
+      return () => sub.unsubscribe();
+    },
+  });
+}

packages/xstate-store/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@internal/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

packages/xstate-store/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: [
+    "@json-render/core",
+    "@json-render/core/store-utils",
+    "@xstate/store",
+  ],
+});

packages/zustand/CHANGELOG.md

@@ -0,0 +1,50 @@
+# @json-render/zustand
+
+## 0.9.1
+
+### Patch Changes
+
+- @json-render/core@0.9.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 1d755c1: External state store, store adapters, and bug fixes.
+
+  ### 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 for controlled mode
+  - 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: Store Adapter Packages
+  - `@json-render/zustand` — Zustand adapter for `StateStore`
+  - `@json-render/redux` — Redux / Redux Toolkit adapter for `StateStore`
+  - `@json-render/jotai` — Jotai adapter for `StateStore`
+
+  ### Changed: `onStateChange` signature updated (breaking)
+
+  The `onStateChange` callback now receives a single array of changed entries instead of being called once per path:
+
+  ```ts
+  // Before
+  onStateChange?: (path: string, value: unknown) => void
+
+  // After
+  onStateChange?: (changes: Array<{ path: string; value: unknown }>) => void
+  ```
+
+  ### Fixed
+  - Fix schema import to use server-safe `@json-render/react/schema` subpath, avoiding `createContext` crashes in Next.js App Router API routes
+  - Fix chaining actions in `@json-render/react`, `@json-render/react-native`, and `@json-render/react-pdf`
+  - Fix safely resolving inner type for Zod arrays in core schema
+
+### Patch Changes
+
+- Updated dependencies [1d755c1]
+  - @json-render/core@0.9.0

packages/zustand/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-render/zustand",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "Apache-2.0",
   "description": "Zustand adapter for json-render StateStore",
   "keywords": [

skills/json-render-react/SKILL.md

@@ -28,7 +28,8 @@ function App({ spec }) {
 
 ```typescript
 import { defineCatalog } from "@json-render/core";
-import { schema, defineRegistry } from "@json-render/react";
+import { schema } from "@json-render/react/schema";
+import { defineRegistry } from "@json-render/react";
 import { z } from "zod";
 
 // Create catalog with props schemas