docs(examples): register a client-only json-render dock in the hub examples

Author: antfubot

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

@@ -16,6 +16,7 @@ Package: `minimal-next-devframe-hub` · framework: **React (Next.js)**
 - 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.
+- [Client-only docks](/guide/client-context#client-only-docks) the page registers itself with `context.docks.register()`: an iframe dock rendered from a Blob URL, and a `json-render` dock whose spec is authored in the browser and seeded into a client-local shared state — rendered by the same React registry as the server-authored view, yet never syncing to the hub or other viewers.
 
 ## Run it
 

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

@@ -16,6 +16,7 @@ Package: `minimal-vite-devframe-hub` · framework: **Vanilla TypeScript (Vite)**
 - 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 })`).
+- [Client-only docks](/guide/client-context#client-only-docks) the page registers itself with `context.docks.register()`: an iframe dock rendered from a Blob URL, and a `json-render` dock whose spec is authored in the browser and seeded into a client-local shared state — rendered by the same renderer as the server-authored view, yet never syncing to the hub or other viewers.
 
 ## Run it
 

docs/guide/client-context.md

@@ -90,6 +90,24 @@ handle.dispose() // remove it
 
 Client-only docks merge into the same `docks.entries` list, group, select, and load their client scripts exactly like server docks — they just never sync to the hub or other viewers. A client dock sharing an id with a server dock overrides it locally. `ctx.docks.update(entry)` replaces a previously registered client dock wholesale. Registering an id that a client dock already owns throws unless you pass `register(entry, true)`.
 
+A client-only dock can render a [JSON-render](./json-render) view the page authors itself. Seed the spec as this client's local value for the dock's `stateKey` — passing only `initialValue` and never mutating it keeps the spec local to this page — then register a `json-render` dock pointing at that key. With a `json-render` renderer registered at boot, it renders through the same path as a server-authored view:
+
+```ts
+import { JSON_RENDER_UPSTREAM_VERSION } from '@devframes/json-render'
+
+await ctx.rpc.sharedState.get('client:json-render:metrics', {
+  initialValue: spec, // a DevframeJsonRenderSpec built in the browser
+})
+
+ctx.docks.register({
+  id: 'client-metrics',
+  title: 'Client Metrics',
+  icon: 'ph:gauge-duotone',
+  type: 'json-render',
+  view: { stateKey: 'client:json-render:metrics', upstreamVersion: JSON_RENDER_UPSTREAM_VERSION },
+})
+```
+
 ## Dock client scripts
 
 A dock entry declares its client script as a `ClientScriptEntry` — `{ importFrom, importName? }`, where `importName` defaults to `'default'`. The field depends on the entry kind:

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

@@ -8,7 +8,10 @@ import type {
   DevframeTerminalSession,
   DevframeViewIframe,
 } from '@devframes/hub/types'
+import type { DevframeJsonRenderSpec } from '@devframes/json-render'
+import type { DevframeJsonRenderDockEntry } from '@devframes/json-render/hub'
 import { connectDevframe, createDevframeClientHost } from '@devframes/hub/client'
+import { JSON_RENDER_UPSTREAM_VERSION } from '@devframes/json-render'
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { createReactJsonRenderDockRenderer } from '../json-render/dock-renderer'
 import { iconClass } from './icons'
@@ -56,6 +59,52 @@ function createClientNotesUrl(): string {
   return URL.createObjectURL(new Blob([html], { type: 'text/html' }))
 }
 
+// The shared-state key the client-only json-render dock renders from. It uses a
+// `client:` prefix rather than the server's `devframe:json-render:<scope>:<id>`
+// namespace to signal it is authored here, not by a node `createJsonRenderView`.
+const CLIENT_JSON_RENDER_KEY = 'client:json-render:metrics'
+
+// A json-render spec synthesized entirely in the browser — the client-only
+// counterpart to a server-authored view. It reads real values captured from the
+// page at registration time and uses the same base-catalog components the hub's
+// server view does, rendered here by the mini React registry.
+function createClientMetricsSpec(clientType: string): DevframeJsonRenderSpec {
+  return {
+    root: 'root',
+    elements: {
+      root: { type: 'Stack', props: { gap: 14 }, children: ['head', 'about', 'env'] },
+      head: { type: 'Stack', props: { direction: 'row', gap: 8, align: 'center' }, children: ['icon', 'title', 'badge'] },
+      icon: { type: 'Icon', props: { name: 'ph:gauge-duotone', size: 22 }, children: [] },
+      title: { type: 'Text', props: { text: 'Client Metrics', variant: 'heading' }, children: [] },
+      badge: { type: 'Badge', props: { text: 'client-only', variant: 'info' }, children: [] },
+      about: { type: 'Card', props: { title: 'About this dock' }, children: ['aboutText'] },
+      aboutText: {
+        type: 'Text',
+        props: {
+          text: 'This json-render view was authored in the browser and seeded into a client-local shared state — it never reaches the hub server or other viewers, yet renders through the same dock renderer as a server-authored view.',
+          variant: 'body',
+          color: 'muted',
+        },
+        children: [],
+      },
+      env: { type: 'Card', props: { title: 'Environment' }, children: ['envTable'] },
+      envTable: {
+        type: 'KeyValueTable',
+        props: {
+          data: {
+            clientType,
+            language: navigator.language,
+            viewport: `${window.innerWidth}×${window.innerHeight}`,
+            online: navigator.onLine ? 'yes' : 'no',
+          },
+        },
+        children: [],
+      },
+    },
+    state: {},
+  }
+}
+
 /** Render a dock icon, falling back to the title's initial when unmapped. */
 function DockIcon({ entry }: { entry: DevframeDockEntry }) {
   const cls = iconClass(entry.icon)
@@ -120,6 +169,26 @@ export default function Page() {
         // Patch it in place with the returned handle (the id is immutable).
         clientDock.update({ badge: clientHost.context.clientType })
 
+        // Register a second client-only dock — this one a *json-render* view the
+        // page authors itself, the richer sibling of the iframe dock above.
+        // First seed the spec as this client's local value for the dock's
+        // `stateKey`: because we only pass `initialValue` and never mutate it,
+        // the spec stays local to this page — it never syncs to the hub server
+        // or other viewers. The `json-render` dock renderer registered above
+        // then reads that same state and renders it with the mini React
+        // registry. `force` lets React StrictMode re-run this effect safely.
+        await rpc.sharedState.get<DevframeJsonRenderSpec>(CLIENT_JSON_RENDER_KEY, {
+          initialValue: createClientMetricsSpec(clientHost.context.clientType),
+        })
+        const clientJsonRenderDock = clientHost.context.docks.register<DevframeJsonRenderDockEntry>({
+          id: 'client-metrics',
+          title: 'Client Metrics',
+          icon: 'ph:gauge-duotone',
+          type: 'json-render',
+          view: { stateKey: CLIENT_JSON_RENDER_KEY, upstreamVersion: JSON_RENDER_UPSTREAM_VERSION },
+          category: 'app',
+        }, true)
+
         const docksState = await rpc.sharedState.get<DevframeDockEntry[]>(
           'devframe:docks',
           { initialValue: [] },
@@ -165,8 +234,9 @@ export default function Page() {
 
         cleanup = () => {
           window.clearInterval(interval)
-          // Remove the client-only dock, then tear down the host.
+          // Remove the client-only docks, then tear down the host.
           clientDock.dispose()
+          clientJsonRenderDock.dispose()
           clientHost.dispose()
         }
       }

examples/minimal-vite-devframe-hub/src/client/main.ts

@@ -5,7 +5,10 @@ import type {
   DevframeTerminalSession,
   DevframeViewIframe,
 } from '@devframes/hub/types'
+import type { DevframeJsonRenderSpec } from '@devframes/json-render'
+import type { DevframeJsonRenderDockEntry } from '@devframes/json-render/hub'
 import { connectDevframe, createDevframeClientHost } from '@devframes/hub/client'
+import { JSON_RENDER_UPSTREAM_VERSION } from '@devframes/json-render'
 import { createJsonRenderDockRenderer } from '@devframes/json-render-ui'
 import { iconClass } from './icons'
 import 'virtual:uno.css'
@@ -80,6 +83,52 @@ function createClientNotesUrl(): string {
   return URL.createObjectURL(new Blob([html], { type: 'text/html' }))
 }
 
+// The shared-state key the client-only json-render dock renders from. It uses a
+// `client:` prefix rather than the server's `devframe:json-render:<scope>:<id>`
+// namespace to signal it is authored here, not by a node `createJsonRenderView`.
+const CLIENT_JSON_RENDER_KEY = 'client:json-render:metrics'
+
+// A json-render spec synthesized entirely in the browser — the client-only
+// counterpart to a server-authored view. It reads real values captured from the
+// page at registration time and uses the same base-catalog components the hub's
+// server view does, rendered by the very same `createJsonRenderDockRenderer`.
+function createClientMetricsSpec(clientType: string): DevframeJsonRenderSpec {
+  return {
+    root: 'root',
+    elements: {
+      root: { type: 'Stack', props: { gap: 14 }, children: ['head', 'about', 'env'] },
+      head: { type: 'Stack', props: { direction: 'row', gap: 8, align: 'center' }, children: ['icon', 'title', 'badge'] },
+      icon: { type: 'Icon', props: { name: 'ph:gauge-duotone', size: 22 }, children: [] },
+      title: { type: 'Text', props: { text: 'Client Metrics', variant: 'heading' }, children: [] },
+      badge: { type: 'Badge', props: { text: 'client-only', variant: 'info' }, children: [] },
+      about: { type: 'Card', props: { title: 'About this dock' }, children: ['aboutText'] },
+      aboutText: {
+        type: 'Text',
+        props: {
+          text: 'This json-render view was authored in the browser and seeded into a client-local shared state — it never reaches the hub server or other viewers, yet renders through the same dock renderer as a server-authored view.',
+          variant: 'body',
+          color: 'muted',
+        },
+        children: [],
+      },
+      env: { type: 'Card', props: { title: 'Environment' }, children: ['envTable'] },
+      envTable: {
+        type: 'KeyValueTable',
+        props: {
+          data: {
+            clientType,
+            language: navigator.language,
+            viewport: `${window.innerWidth}×${window.innerHeight}`,
+            online: navigator.onLine ? 'yes' : 'no',
+          },
+        },
+        children: [],
+      },
+    },
+    state: {},
+  }
+}
+
 async function main() {
   setStatus('Connecting…')
 
@@ -115,6 +164,24 @@ async function main() {
   // `clientDock.dispose()` to remove it from the merged list again.
   clientDock.update({ badge: host.context.clientType })
 
+  // Register a second client-only dock — this one a *json-render* view the page
+  // authors itself, the richer sibling of the iframe dock above. First seed the
+  // spec as this client's local value for the dock's `stateKey`: because we only
+  // pass `initialValue` and never mutate it, the spec stays local to this page —
+  // it never syncs to the hub server or other viewers. The `json-render` dock
+  // renderer registered above then reads that same state and renders it.
+  await rpc.sharedState.get<DevframeJsonRenderSpec>(CLIENT_JSON_RENDER_KEY, {
+    initialValue: createClientMetricsSpec(host.context.clientType),
+  })
+  host.context.docks.register<DevframeJsonRenderDockEntry>({
+    id: 'client-metrics',
+    title: 'Client Metrics',
+    icon: 'ph:gauge-duotone',
+    type: 'json-render',
+    view: { stateKey: CLIENT_JSON_RENDER_KEY, upstreamVersion: JSON_RENDER_UPSTREAM_VERSION },
+    category: 'app',
+  })
+
   // 1. Docks — the merged list from the client host: server docks (projected
   // from `devframe:docks` shared state) plus the client-only dock above. We
   // still subscribe to the shared state to re-render when server docks change.