feat(examples): render a json-render dock in the minimal-next hub

Verify the JSON-render hub integration in the React/Next shell via registry
replacement (the path a non-Vue host uses, per the plan):

- The Next hub authors the shared minimal-json-render view on its hub context
  and projects it onto a `json-render` dock (via @devframes/json-render/hub).
- A small in-example React registry (built on @json-render/react + the shared
  @antfu/design tokens) is registered as the `json-render` renderer on the
  client host; the page mounts the active dock into a panel via the renderer
  registry. Next.js can't compile Vue SFCs, so the Vue @devframes/json-render-ui
  isn't used here — this is registry replacement.
- UnoCSS scans the new dir + safelists the badge colors.

Docs: note the json-render dock in both hub example pages and the guide.

Created with the help of an agent.

Author: antfubot

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
 

docs/guide/json-render.md

@@ -174,6 +174,10 @@ upstreamVersion }`) — no functions cross the wire. The client host disposes th
 renderer when the dock deactivates. A renderer/upstream-version mismatch logs a
 warning rather than blocking.
 
+Both hub example shells dogfood this end to end: the [Vite hub](/examples/minimal-vite-devframe-hub)
+registers `@devframes/json-render-ui` (Vue), and the [Next hub](/examples/minimal-next-devframe-hub)
+registers a small in-example React registry — the same dock, two frontends.
+
 ## Swapping the frontend
 
 A third party replaces the whole registry — pass a custom `registry` to

examples/minimal-json-render/README.md

@@ -33,3 +33,12 @@ node bin.mjs build --out-dir dist/static   # static snapshot (read-only; actions
 
 In the static build, the spec + state are snapshotted as a read-only render and
 the action bridge reports actions as unavailable — there is no live RPC.
+
+## Reused by the hub shells
+
+The view is factored into `src/dashboard.ts` and exported as
+`minimal-json-render/dashboard` (`createDashboardView(ctx)` + `dashboardSpec`),
+so the hub examples plug the very same view into their hub context and project
+it onto a `json-render` dock — the [Vite hub](../minimal-vite-devframe-hub)
+renders it with `@devframes/json-render-ui` (Vue), and the
+[Next hub](../minimal-next-devframe-hub) renders it with a small React registry.

examples/minimal-next-devframe-hub/package.json

@@ -13,14 +13,17 @@
   "dependencies": {
     "@antfu/design": "catalog:frontend",
     "@devframes/hub": "workspace:*",
+    "@devframes/json-render": "workspace:*",
     "@devframes/plugin-a11y": "workspace:*",
     "@devframes/plugin-code-server": "workspace:*",
     "@devframes/plugin-git": "workspace:*",
     "@devframes/plugin-inspect": "workspace:*",
     "@devframes/plugin-messages": "workspace:*",
     "@devframes/plugin-terminals": "workspace:*",
+    "@json-render/react": "catalog:frontend",
     "colorjs.io": "catalog:frontend",
     "devframe": "workspace:*",
+    "minimal-json-render": "workspace:*",
     "next": "catalog:frontend",
     "react": "catalog:frontend",
     "react-dom": "catalog:frontend"

examples/minimal-next-devframe-hub/src/client/app/page.tsx

@@ -9,6 +9,7 @@ import type {
 } from '@devframes/hub/types'
 import { connectDevframe, createDevframeClientHost } from '@devframes/hub/client'
 import { useEffect, useMemo, useRef, useState } from 'react'
+import { createReactJsonRenderDockRenderer } from '../json-render/dock-renderer'
 import { iconClass } from './icons'
 
 const HUB_BASE = '/__hub/'
@@ -20,11 +21,19 @@ interface Status {
 
 type IframeDock = DevframeDockEntry & { type: 'iframe', url: string }
 type TerminalSummary = Pick<DevframeTerminalSession, 'id' | 'title' | 'status' | 'description'>
+type ClientHost = Awaited<ReturnType<typeof createDevframeClientHost>>
 
 function isIframeDock(d: DevframeDockEntry): d is IframeDock {
   return d.type === 'iframe' && typeof (d as { url?: unknown }).url === 'string'
 }
 
+// A dock this shell can display: an iframe, or one with a registered renderer
+// (the json-render dock, rendered by the mini React registry).
+const RENDERER_TYPES = new Set(['json-render'])
+function isRenderableDock(d: DevframeDockEntry): boolean {
+  return isIframeDock(d) || RENDERER_TYPES.has(d.type)
+}
+
 /** Render a dock icon, falling back to the title's initial when unmapped. */
 function DockIcon({ entry }: { entry: DevframeDockEntry }) {
   const cls = iconClass(entry.icon)
@@ -43,6 +52,8 @@ export default function Page() {
   const [pingResult, setPingResult] = useState('Run ping')
   const [selectedDockId, setSelectedDockId] = useState<string | null>(null)
   const rpcRef = useRef<DevframeRpcClient | null>(null)
+  const hostRef = useRef<ClientHost | null>(null)
+  const panelRef = useRef<HTMLDivElement | null>(null)
 
   useEffect(() => {
     let cancelled = false
@@ -60,7 +71,14 @@ export default function Page() {
         // Boot the framework-level client host: it builds the shared client
         // context and imports each dock's client script into this page — e.g.
         // the a11y inspector's in-page agent, which then scans this hub live.
-        const clientHost = await createDevframeClientHost({ rpc })
+        //
+        // Register a mini React json-render renderer so the hub can display the
+        // `json-render` dock authored server-side via @devframes/json-render.
+        const clientHost = await createDevframeClientHost({
+          rpc,
+          renderers: { 'json-render': createReactJsonRenderDockRenderer() },
+        })
+        hostRef.current = clientHost
 
         const docksState = await rpc.sharedState.get<DevframeDockEntry[]>(
           'devframe:docks',
@@ -122,18 +140,41 @@ export default function Page() {
     }
   }, [])
 
-  const iframeDocks = useMemo(() => docks.filter(isIframeDock), [docks])
+  const renderableDocks = useMemo(() => docks.filter(isRenderableDock), [docks])
 
   useEffect(() => {
-    if (selectedDockId && !iframeDocks.some(d => d.id === selectedDockId)) {
+    if (selectedDockId && !renderableDocks.some(d => d.id === selectedDockId)) {
       setSelectedDockId(null)
       return
     }
-    if (!selectedDockId && iframeDocks.length > 0)
-      setSelectedDockId(iframeDocks[0].id)
-  }, [iframeDocks, selectedDockId])
+    if (!selectedDockId && renderableDocks.length > 0)
+      setSelectedDockId(renderableDocks[0].id)
+  }, [renderableDocks, selectedDockId])
 
-  const selectedDock = iframeDocks.find(d => d.id === selectedDockId) ?? null
+  const selectedDock = renderableDocks.find(d => d.id === selectedDockId) ?? null
+  const selectedIsIframe = selectedDock ? isIframeDock(selectedDock) : false
+
+  // Mount a renderer dock (json-render) into the panel via the client host's
+  // renderer registry, disposing when the selection changes. Keyed by dock id
+  // so a live view-state update (its own shared state) doesn't remount.
+  useEffect(() => {
+    const host = hostRef.current
+    const dock = selectedDock
+    const container = panelRef.current
+    if (!host || !dock || isIframeDock(dock) || !container)
+      return
+    let alive = true
+    let dispose: (() => void) | undefined
+    void host.context.renderers.mount(dock, container).then((d) => {
+      if (alive)
+        dispose = d
+      else d()
+    })
+    return () => {
+      alive = false
+      dispose?.()
+    }
+  }, [selectedDockId, selectedIsIframe])
 
   async function ping() {
     if (!rpcRef.current)
@@ -169,9 +210,9 @@ export default function Page() {
         <aside className="flex flex-col gap-0.5 of-auto border-r border-base bg-secondary p2">
           <h2 className="px2 py1 text-[0.68rem] uppercase tracking-wider color-muted">Docks</h2>
           <ul className="m0 flex flex-col list-none gap-0.5 p0">
-            {iframeDocks.length === 0
-              ? <li className="op-mute px2 text-sm">No iframe docks</li>
-              : iframeDocks.map(dock => (
+            {renderableDocks.length === 0
+              ? <li className="op-mute px2 text-sm">No docks</li>
+              : renderableDocks.map(dock => (
                   <li key={dock.id}>
                     <button
                       type="button"
@@ -188,12 +229,19 @@ export default function Page() {
         </aside>
 
         <main className="min-w-0 of-hidden bg-secondary">
-          <iframe
-            key={selectedDock?.id ?? 'none'}
-            src={selectedDock?.url ?? 'about:blank'}
-            title="Selected dock"
-            className="block h-full w-full border-0 bg-base"
-          />
+          {selectedIsIframe
+            ? (
+                <iframe
+                  key={selectedDock?.id ?? 'none'}
+                  src={(selectedDock as IframeDock | null)?.url ?? 'about:blank'}
+                  title="Selected dock"
+                  className="block h-full w-full border-0 bg-base"
+                />
+              )
+            : (
+                // Renderer docks (json-render) mount here via the client host.
+                <div key={selectedDock?.id ?? 'none'} ref={panelRef} className="h-full w-full of-auto bg-base p4" />
+              )}
         </main>
       </div>
 

examples/minimal-next-devframe-hub/src/client/devframe/minimal-next-devframe-hub.ts

@@ -5,9 +5,11 @@ import { homedir } from 'node:os'
 import process from 'node:process'
 import { defineHubRpcFunction } from '@devframes/hub'
 import { createHubContext, mountDevframe } from '@devframes/hub/node'
+import { toJsonRenderDockEntry } from '@devframes/json-render/hub'
 import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
 import { startHttpAndWs } from 'devframe/node'
 import { getPort } from 'get-port-please'
+import { createDashboardView } from 'minimal-json-render/dashboard'
 import { dirname, join } from 'pathe'
 import demoDevframe from './demo-devframe'
 import demoDevframeB from './demo-devframe-b'
@@ -243,6 +245,17 @@ export async function minimalNextDevframeHub(
     await mountDevframe(context, def, clientScript ? { dock: { clientScript } } : undefined)
   }
 
+  // Dogfood the opt-in JSON-render hub integration: author a view on the hub
+  // context and project it onto a `json-render` dock. The client (app/page.tsx)
+  // renders it with a mini React registry (registry replacement).
+  const jsonRenderView = createDashboardView(context)
+  context.docks.register(toJsonRenderDockEntry(jsonRenderView, {
+    id: 'minimal-json-render',
+    title: 'JSON Render',
+    icon: 'ph:layout-duotone',
+    category: 'app',
+  }))
+
   const started = await startHttpAndWs({
     context,
     host: hostName,

examples/minimal-next-devframe-hub/src/client/json-render/dock-renderer.tsx

@@ -0,0 +1,126 @@
+'use client'
+
+import type { JsonRenderViewRef, Spec } from '@devframes/json-render'
+import type { ComponentRegistry } from '@json-render/react'
+import type { ReactNode } from 'react'
+import { basePropSchemas, JSON_RENDER_UPSTREAM_VERSION } from '@devframes/json-render'
+import { JSONUIProvider, Renderer } from '@json-render/react'
+import { useMemo } from 'react'
+import { createRoot } from 'react-dom/client'
+import { baseReactRegistry, ERROR_COMPONENT_TYPE } from './registry'
+
+// Built-ins handled inside upstream's ActionProvider — never bridged to RPC.
+const RESERVED = new Set(['setState', 'pushState', 'removeState', 'validateForm', 'then', 'catch', 'finally'])
+
+/**
+ * The unrestricted action bridge: a spec action name is dispatched as an RPC
+ * call of the same name (per the plan). Upstream tracks per-action loading and
+ * confirmation; failures rethrow so `onError` handlers fire.
+ */
+function createActionBridge(rpc: { call: (method: string, ...args: unknown[]) => Promise<unknown> }): Record<string, (params?: Record<string, unknown>) => Promise<unknown>> {
+  const cache = new Map<string, (params?: Record<string, unknown>) => Promise<unknown>>()
+  return new Proxy({} as Record<string, (params?: Record<string, unknown>) => Promise<unknown>>, {
+    has: (_t, p) => typeof p === 'string' && !RESERVED.has(p),
+    get: (_t, prop) => {
+      if (typeof prop !== 'string' || RESERVED.has(prop))
+        return undefined
+      let fn = cache.get(prop)
+      if (!fn) {
+        fn = (params?: Record<string, unknown>) => rpc.call(prop, params)
+        cache.set(prop, fn)
+      }
+      return fn
+    },
+  })
+}
+
+/**
+ * Render-time prop validation: swap any element with invalid props for the
+ * error component, isolating one bad element instead of breaking the view.
+ */
+function sanitizeSpec(spec: Spec): Spec {
+  let changed = false
+  const elements: Spec['elements'] = {}
+  for (const [key, element] of Object.entries(spec.elements ?? {})) {
+    const schema = basePropSchemas[element.type as keyof typeof basePropSchemas]
+    if (schema) {
+      const result = schema.safeParse(element.props ?? {})
+      if (!result.success) {
+        changed = true
+        const issues = result.error.issues.map(i => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ')
+        console.warn(`[minimal-next-devframe-hub] invalid props on element "${key}" (${element.type}): ${issues}`)
+        elements[key] = { ...element, type: ERROR_COMPONENT_TYPE, props: { message: `${element.type}: ${issues}` } }
+        continue
+      }
+    }
+    elements[key] = element
+  }
+  return changed ? { ...spec, elements } : spec
+}
+
+interface JsonRenderViewProps {
+  spec: Spec | null
+  rpc: { call: (method: string, ...args: unknown[]) => Promise<unknown> }
+  registry: ComponentRegistry
+  viewId: string
+  upstreamVersion?: string
+}
+
+function JsonRenderView({ spec, rpc, registry, viewId, upstreamVersion }: JsonRenderViewProps): ReactNode {
+  const handlers = useMemo(() => createActionBridge(rpc), [rpc])
+  const effective = useMemo(() => (spec ? sanitizeSpec(spec) : null), [spec])
+  if (!spec)
+    return <div className="p4 color-faint text-sm">No view to render.</div>
+  return (
+    <JSONUIProvider
+      // Reset the provider (reseed state) only on identity/version change.
+      key={`${viewId}::${upstreamVersion ?? JSON_RENDER_UPSTREAM_VERSION}`}
+      registry={registry}
+      handlers={handlers}
+      initialState={spec.state ?? {}}
+    >
+      <Renderer spec={effective} registry={registry} />
+    </JSONUIProvider>
+  )
+}
+
+export interface ReactDockMountOptions {
+  entry: unknown
+  container: HTMLElement
+
+  context: { rpc: any }
+}
+
+/**
+ * A hub-compatible dock renderer that renders a `json-render` dock with this
+ * example's mini **React** registry (registry replacement) instead of the Vue
+ * reference frontend. Mounts a React root into the container the client host
+ * provides, subscribes to the view's shared state, and disposes cleanly.
+ */
+export function createReactJsonRenderDockRenderer() {
+  return async ({ entry, container, context }: ReactDockMountOptions): Promise<{ dispose: () => void }> => {
+    const view = (entry as { view: JsonRenderViewRef }).view
+    const rpc = context.rpc
+    const state = await rpc.sharedState.get(view.stateKey, { initialValue: null })
+    const root = createRoot(container)
+    const render = (): void => {
+      root.render(
+        <JsonRenderView
+          spec={state.value() as Spec | null}
+          rpc={rpc}
+          registry={baseReactRegistry}
+          viewId={view.stateKey}
+          upstreamVersion={view.upstreamVersion}
+        />,
+      )
+    }
+    render()
+    const off = state.on('updated', render)
+    return {
+      dispose() {
+        off()
+        root.unmount()
+      },
+    }
+  }
+}