feat: JSON-render packages (@devframes/json-render + @devframes/json-render-ui) (#116)

Co-authored-by: Anthony Fu <github@antfu.me>

Author: antfubot

alias.ts

@@ -46,6 +46,13 @@ export const alias = {
   '@devframes/hub': r('hub/src/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
   '@devframes/nuxt': r('nuxt/src/index.ts'),
+  '@devframes/json-render/core': r('json-render/src/core.ts'),
+  '@devframes/json-render/hub': r('json-render/src/hub.ts'),
+  '@devframes/json-render/node': r('json-render/src/node/index.ts'),
+  '@devframes/json-render': r('json-render/src/index.ts'),
+  '@devframes/json-render-ui/components': r('json-render-ui/src/components/index.ts'),
+  '@devframes/json-render-ui': r('json-render-ui/src/index.ts'),
+  'minimal-json-render/dashboard': fileURLToPath(new URL('./examples/minimal-json-render/src/dashboard.ts', import.meta.url)),
   '@devframes/plugin-code-server/client': p('code-server/src/client/index.ts'),
   '@devframes/plugin-code-server/node': p('code-server/src/node/index.ts'),
   '@devframes/plugin-code-server/constants': p('code-server/src/constants.ts'),

docs/.vitepress/config.ts

@@ -24,6 +24,7 @@ function guideItems(prefix: string) {
     { text: 'Cross-Plugin Services', link: `${prefix}/guide/services` },
     { text: 'RPC', link: `${prefix}/guide/rpc` },
     { text: 'Shared State', link: `${prefix}/guide/shared-state` },
+    { text: 'JSON-Render', link: `${prefix}/guide/json-render` },
     { text: 'Streaming', link: `${prefix}/guide/streaming` },
     { text: 'When Clauses', link: `${prefix}/guide/when-clauses` },
     { text: 'Structured Diagnostics', link: `${prefix}/guide/diagnostics` },
@@ -77,6 +78,7 @@ function examplesItems(prefix: string) {
     { text: 'Overview', link: `${prefix}/examples/` },
     { text: 'Built with Devframe', link: `${prefix}/examples/built-with` },
     { text: 'files-inspector', link: `${prefix}/examples/files-inspector` },
+    { text: 'minimal-json-render', link: `${prefix}/examples/minimal-json-render` },
     { text: 'streaming-chat', link: `${prefix}/examples/streaming-chat` },
     { text: 'next-runtime-snapshot', link: `${prefix}/examples/next-runtime-snapshot` },
     { text: 'minimal-vite-devframe-hub', link: `${prefix}/examples/minimal-vite-devframe-hub` },

docs/errors/DF0038.md

@@ -0,0 +1,37 @@
+---
+outline: deep
+---
+
+# DF0038: Invalid JSON-Render Element Props
+
+## Message
+
+> JSON-render view "`{id}`" received invalid props on element "`{key}`": `{issues}`
+
+## Cause
+
+`@devframes/json-render` validates every element's props against the base catalog's per-component Zod schema at spec ingress (`createJsonRenderView` / `view.update`). Upstream `@json-render/core` only checks component *names*, so this per-component prop check is the one validation Devframes adds. An element whose props don't match its component's schema is rejected here rather than failing silently at render.
+
+## Example
+
+```ts
+// ✗ Bad — `variant` is not one of the Button variants
+createJsonRenderView(ctx, {
+  id: 'toolbar',
+  spec: { root: 'a', elements: { a: { type: 'Button', props: { variant: 'nope' }, children: [] } } },
+})
+
+// ✓ Good
+createJsonRenderView(ctx, {
+  id: 'toolbar',
+  spec: { root: 'a', elements: { a: { type: 'Button', props: { variant: 'primary', label: 'Save' }, children: [] } } },
+})
+```
+
+## Fix
+
+Match the element props to the base catalog's prop schema for that component. Dynamic `$state` / `$bindState` expressions are accepted wherever a scalar prop is expected, so a valid binding never triggers this.
+
+## Source
+
+- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts) — `validateElementProps()` throws this at ingress and on `update`.

docs/errors/DF0039.md

@@ -0,0 +1,34 @@
+---
+outline: deep
+---
+
+# DF0039: Duplicate JSON-Render View
+
+## Message
+
+> A JSON-render view with id "`{id}`" already exists in scope "`{scope}`".
+
+## Cause
+
+Each JSON-render view has a stable, author-supplied id that forms its shared-state key `devframe:json-render:<scope>:<id>`. Ids must be unique within a scope so the client keeps a stable subscription across reconnects. Creating a second view with the same id in the same scope throws instead of clobbering the first.
+
+## Example
+
+```ts
+// ✗ Bad — same id twice in the same scope
+createJsonRenderView(ctx, { id: 'metrics', spec })
+createJsonRenderView(ctx, { id: 'metrics', spec }) // DF0039
+
+// ✓ Good — dispose the previous view first, or use a distinct id
+const view = createJsonRenderView(ctx, { id: 'metrics', spec })
+view.dispose()
+createJsonRenderView(ctx, { id: 'metrics', spec })
+```
+
+## Fix
+
+Give each view a stable id unique within its scope, or dispose the previous view before recreating it. Scope defaults to the context namespace (or `global`); pass `scope` to isolate ids explicitly.
+
+## Source
+
+- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts) — `createJsonRenderView()` throws this when the scoped id is already live.

docs/errors/DF0040.md

@@ -0,0 +1,29 @@
+---
+outline: deep
+---
+
+# DF0040: JSON-Render View Used After Disposal
+
+## Message
+
+> JSON-render view "`{id}`" was used after it was disposed.
+
+## Cause
+
+`view.dispose()` unregisters the view's shared state and its broadcast listeners. Calling `update` or `patchState` on a disposed handle is a lifecycle bug — the shared state it targeted no longer exists.
+
+## Example
+
+```ts
+const view = createJsonRenderView(ctx, { id: 'metrics', spec })
+view.dispose()
+view.update(nextSpec) // DF0040
+```
+
+## Fix
+
+Create a fresh view with `createJsonRenderView` instead of reusing a disposed handle. The id is free to reuse once disposed.
+
+## Source
+
+- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts) — `update` / `patchState` throw this after `dispose()`.

docs/errors/DF0041.md

@@ -0,0 +1,33 @@
+---
+outline: deep
+---
+
+# DF0041: JSON-Render Spec Is Not JSON-Serializable
+
+## Message
+
+> JSON-render view "`{id}`" spec is not JSON-serializable: `{reason}`
+
+## Cause
+
+Specs and state travel across the RPC / static boundary as strict JSON. A spec containing functions, symbols, class instances, `Map`/`Set`, or circular references cannot cross that boundary, so it is rejected at ingress.
+
+## Example
+
+```ts
+// ✗ Bad — circular reference
+const spec: any = { root: 'a', elements: {} }
+spec.self = spec
+createJsonRenderView(ctx, { id: 'x', spec }) // DF0041
+
+// ✓ Good — plain JSON data
+createJsonRenderView(ctx, { id: 'x', spec: { root: 'a', elements: { a: { type: 'Text', props: { text: 'hi' }, children: [] } } } })
+```
+
+## Fix
+
+Keep specs and state strict JSON — remove functions, symbols, class instances, `Map`/`Set`, or circular references.
+
+## Source
+
+- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts) — `assertJsonSerializable()` throws this at ingress and on `update`.

docs/examples/index.md

@@ -9,6 +9,7 @@ End-to-end examples that exercise the full adapter surface, each a runnable app
 | Example | UI framework | What it shows |
 |---------|--------------|---------------|
 | [files-inspector](./files-inspector) | Preact | Lists files in the cwd via RPC; exercises the CLI dev / build / spa surfaces. |
+| [minimal-json-render](./minimal-json-render) | Vue | A server-authored JSON-render view rendered by `@devframes/json-render-ui`, with live state and an action bridge. |
 | [streaming-chat](./streaming-chat) | Preact | Streams synthetic chat tokens server → client, with history kept in shared state. |
 | [next-runtime-snapshot](./next-runtime-snapshot) | React (Next.js) | A Next.js App Router SPA over RPC, surfacing the host Node runtime. |
 | [minimal-vite-devframe-hub](./minimal-vite-devframe-hub) | Vanilla TypeScript (Vite) | A ~120-line Vite host wiring `@devframes/hub` end to end. |

docs/examples/minimal-json-render.md

@@ -0,0 +1,41 @@
+---
+outline: deep
+---
+
+# minimal-json-render
+
+A standalone devframe that serves a **JSON-render view**: the server authors an
+`@json-render/core` spec once, and the browser renders it with the official
+`@devframes/json-render-ui` Vue frontend.
+
+Package: `minimal-json-render` · framework: **Vue + Vite**
+
+## What it shows
+
+- **`createJsonRenderView`** — registers the spec as shared state, validates
+  element props at ingress, and returns a handle with `update` / `patchState` /
+  `dispose`.
+- **Live state** — the server ticks `uptime` every second via `patchState`, so
+  the view updates without replacing the whole spec.
+- **Action bridge** — the `Refresh` button's `press` action is dispatched as an
+  RPC call of the same name; the handler bumps a counter and patches state, with
+  per-action loading and error surfacing.
+- **Standalone rendering** — the app supplies the frontend lib
+  (`@devframes/json-render-ui`); devframe serves the SPA, which subscribes to
+  the view's shared state and renders it with `JsonRenderView`.
+- **Static output** — `cli:build` snapshots the spec + state as a read-only
+  render; the action bridge reports actions as unavailable (no live RPC).
+
+## Run it
+
+```sh
+pnpm --filter minimal-json-render dev         # CLI dev server (live RPC)
+pnpm --filter minimal-json-render build       # build the Vue client
+pnpm --filter minimal-json-render cli:build   # static deploy → dist/static
+```
+
+The dev server serves the SPA at `/__minimal-json-render/`.
+
+## Source
+
+[`examples/minimal-json-render`](https://github.com/devframes/devframe/tree/main/examples/minimal-json-render)

docs/examples/minimal-next-devframe-hub.md

@@ -15,6 +15,7 @@ Package: `minimal-next-devframe-hub` · framework: **React (Next.js)**
 - `mountDevframe(ctx, def)` registers any `DevframeDefinition` as a dock.
 - The built-in `hub:commands:execute` RPC dispatches any registered server command, regardless of how the host was constructed.
 - The browser-side `connectDevframe({ baseURL: '/__hub/' })` discovers the WS endpoint via the Next route handler at `/__hub/__connection.json`, which starts the singleton host on demand.
+- The [JSON-render](/guide/json-render) hub integration with **registry replacement**: the host authors a view and projects it onto a `json-render` dock, and the React client renders it with a small in-example React registry (rather than the Vue `@devframes/json-render-ui`) — the path a non-Vue host uses.
 
 ## Run it
 

docs/examples/minimal-vite-devframe-hub.md

@@ -15,6 +15,7 @@ Package: `minimal-vite-devframe-hub` · framework: **Vanilla TypeScript (Vite)**
 - `mountDevframe(ctx, def)` registers any `DevframeDefinition` as a dock.
 - The built-in `hub:commands:execute` RPC dispatches any registered server command, regardless of how the host was constructed.
 - The browser-side `connectDevframe({ baseURL: '/__hub/' })` discovers the WS endpoint via the kit's `__connection.json` middleware.
+- The opt-in [JSON-render](/guide/json-render) hub integration end to end: the host authors a view on its hub context and projects it onto a `json-render` dock, and the client host renders it via `@devframes/json-render-ui` (registered through `createDevframeClientHost({ renderers })`).
 
 ## Run it