docs(examples): make the client-only json-render dock interactive

Turns the inline client-authored view into a small interactive playground:
`$bindState` text/switch inputs write into the view's own state, `$state`
reads mirror them live, and Add / Clear buttons drive the built-in
`pushState` / `setState` actions to mutate a notes list that re-renders — all
client-side, with no server and no shared state. Applied to both the Vite
(Vue) and Next (React) hub shells.

Author: antfubot

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

@@ -16,7 +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 carried inline in the dock entry (`view: { spec }`) — rendered by the same React registry as the server-authored view, with no shared state, yet never syncing to the hub or other viewers.
+- [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 an interactive `json-render` dock whose spec is authored in the browser and carried inline in the dock entry (`view: { spec }`) — its inputs, toggles, and `pushState`/`setState` buttons drive the view's own state (no shared state, nothing synced to the hub), rendered by the same React registry as the server-authored view.
 
 ## Run it
 

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

@@ -16,7 +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 carried inline in the dock entry (`view: { spec }`) — rendered by the same renderer as the server-authored view, with no shared state, yet never syncing to the hub or other viewers.
+- [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 an interactive `json-render` dock whose spec is authored in the browser and carried inline in the dock entry (`view: { spec }`) — its inputs, toggles, and `pushState`/`setState` buttons drive the view's own state (no shared state, nothing synced to the hub), rendered by the same renderer as the server-authored view.
 
 ## Run it
 

docs/guide/client-context.md

@@ -96,15 +96,15 @@ A client-only dock can render a [JSON-render](./json-render) view the page autho
 const spec = { /* a DevframeJsonRenderSpec built in the browser */ }
 
 ctx.docks.register({
-  id: 'client-metrics',
-  title: 'Client Metrics',
-  icon: 'ph:gauge-duotone',
+  id: 'client-playground',
+  title: 'Client Playground',
+  icon: 'ph:sliders-horizontal-duotone',
   type: 'json-render',
   view: { spec },
 })
 ```
 
-The `view` field accepts either `{ spec }` (rendered inline, static) or `{ stateKey }` (subscribed to a live shared state, the shape `createJsonRenderView` produces server-side).
+The `view` field accepts either `{ spec }` (the spec rendered inline) or `{ stateKey }` (subscribed to a live shared state, the shape `createJsonRenderView` produces server-side). An inline view still runs its own state: `{ $bindState }` inputs and `{ $state }` reads work against the spec's `state`, and the built-in `setState` / `pushState` / `removeState` actions mutate it — so a client-authored view is interactive with no server and no shared state. What `{ spec }` lacks versus `{ stateKey }` is a server-driven update stream.
 
 ## Dock client scripts
 

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

@@ -58,44 +58,76 @@ function createClientNotesUrl(): string {
   return URL.createObjectURL(new Blob([html], { type: 'text/html' }))
 }
 
-// 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 {
+// An *interactive* json-render spec synthesized entirely in the browser — the
+// client-only counterpart to a server-authored view. Interactivity needs no
+// server and no shared state: `{ $bindState }` inputs write straight into the
+// view's own `state`, `{ $state }` reads mirror it live, and the buttons use the
+// framework's built-in state actions (`pushState` / `setState`) to mutate that
+// state — every change re-renders through the mini React registry.
+function createClientPlaygroundSpec(clientType: string): DevframeJsonRenderSpec {
   return {
     root: 'root',
     elements: {
-      root: { type: 'Stack', props: { gap: 14 }, children: ['head', 'about', 'env'] },
+      root: { type: 'Stack', props: { gap: 14 }, children: ['head', 'hello', 'notes', '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: [] },
+      icon: { type: 'Icon', props: { name: 'ph:sliders-horizontal-duotone', size: 22 }, children: [] },
+      title: { type: 'Text', props: { text: 'Client Playground', 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',
-        },
+
+      // ── Two-way binding: type a name, see it echoed live; toggle a switch ──
+      hello: { type: 'Card', props: { title: 'Say hello' }, children: ['helloBody'] },
+      helloBody: { type: 'Stack', props: { gap: 10 }, children: ['nameInput', 'greetRow', 'compact'] },
+      nameInput: { type: 'TextInput', props: { label: 'Your name', placeholder: 'Type your name…', value: { $bindState: '/form/name' } }, children: [] },
+      greetRow: { type: 'Stack', props: { direction: 'row', gap: 6, align: 'center' }, children: ['greetLabel', 'greetName'] },
+      greetLabel: { type: 'Text', props: { text: 'Hello,', variant: 'body', color: 'muted' }, children: [] },
+      greetName: { type: 'Text', props: { text: { $state: '/form/name' }, variant: 'body', color: 'primary' }, children: [] },
+      compact: { type: 'Switch', props: { label: 'Compact mode', value: { $bindState: '/prefs/compact' } }, children: [] },
+
+      // ── Actions mutate state → the DataTable re-renders ──
+      notes: { type: 'Card', props: { title: 'Notes' }, children: ['notesBody'] },
+      notesBody: { type: 'Stack', props: { gap: 10 }, children: ['draftRow', 'notesTable', 'clearBtn'] },
+      draftRow: { type: 'Stack', props: { direction: 'row', gap: 8, align: 'end' }, children: ['draftInput', 'addBtn'] },
+      draftInput: { type: 'TextInput', props: { label: 'New note', placeholder: 'Write something…', value: { $bindState: '/draft' } }, children: [] },
+      addBtn: {
+        type: 'Button',
+        props: { label: 'Add', variant: 'primary', icon: 'ph:plus' },
+        // Built-in `pushState`: append the typed draft to /notes, then clear the input.
+        on: { press: { action: 'pushState', params: { statePath: '/notes', value: { text: { $state: '/draft' } }, clearStatePath: '/draft' } } },
+        children: [],
+      },
+      notesTable: {
+        type: 'DataTable',
+        props: { columns: [{ key: 'text', label: 'Note' }], rows: { $state: '/notes' }, height: 160 },
+        children: [],
+      },
+      clearBtn: {
+        type: 'Button',
+        props: { label: 'Clear all', variant: 'ghost', icon: 'ph:trash' },
+        // Built-in `setState`: replace /notes with an empty array.
+        on: { press: { action: 'setState', params: { statePath: '/notes', value: [] } } },
         children: [],
       },
-      env: { type: 'Card', props: { title: 'Environment' }, children: ['envTable'] },
+
+      env: { type: 'Card', props: { title: 'Environment', collapsible: true, defaultCollapsed: true }, children: ['envTable'] },
       envTable: {
         type: 'KeyValueTable',
         props: {
           data: {
             clientType,
             language: navigator.language,
             viewport: `${window.innerWidth}×${window.innerHeight}`,
-            online: navigator.onLine ? 'yes' : 'no',
           },
         },
         children: [],
       },
     },
-    state: {},
+    state: {
+      form: { name: '' },
+      prefs: { compact: false },
+      draft: '',
+      notes: [{ text: 'Authored entirely in the browser' }],
+    },
   }
 }
 
@@ -166,16 +198,17 @@ export default function Page() {
         // Register a second client-only dock — this one a *json-render* view the
         // page authors itself, the richer sibling of the iframe dock above. Its
         // spec is carried **inline** in the dock entry (`view.spec`), so it needs
-        // no shared state at all: it lives only in this page yet renders through
-        // the same `json-render` dock renderer (the mini React registry) as a
-        // server-authored view. `force` lets React StrictMode re-run this effect
-        // safely.
+        // no shared state at all: it lives only in this page yet renders — and
+        // stays fully interactive (inputs, toggles, and buttons that mutate its
+        // state) — through the same `json-render` dock renderer (the mini React
+        // registry) as a server-authored view. `force` lets React StrictMode
+        // re-run this effect safely.
         const clientJsonRenderDock = clientHost.context.docks.register<DevframeJsonRenderDockEntry>({
-          id: 'client-metrics',
-          title: 'Client Metrics',
-          icon: 'ph:gauge-duotone',
+          id: 'client-playground',
+          title: 'Client Playground',
+          icon: 'ph:sliders-horizontal-duotone',
           type: 'json-render',
-          view: { spec: createClientMetricsSpec(clientHost.context.clientType) },
+          view: { spec: createClientPlaygroundSpec(clientHost.context.clientType) },
           category: 'app',
         }, true)
 

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

@@ -82,44 +82,76 @@ function createClientNotesUrl(): string {
   return URL.createObjectURL(new Blob([html], { type: 'text/html' }))
 }
 
-// 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 {
+// An *interactive* json-render spec synthesized entirely in the browser — the
+// client-only counterpart to a server-authored view. Interactivity needs no
+// server and no shared state: `{ $bindState }` inputs write straight into the
+// view's own `state`, `{ $state }` reads mirror it live, and the buttons use the
+// framework's built-in state actions (`pushState` / `setState`) to mutate that
+// state — every change re-renders through the same `createJsonRenderDockRenderer`.
+function createClientPlaygroundSpec(clientType: string): DevframeJsonRenderSpec {
   return {
     root: 'root',
     elements: {
-      root: { type: 'Stack', props: { gap: 14 }, children: ['head', 'about', 'env'] },
+      root: { type: 'Stack', props: { gap: 14 }, children: ['head', 'hello', 'notes', '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: [] },
+      icon: { type: 'Icon', props: { name: 'ph:sliders-horizontal-duotone', size: 22 }, children: [] },
+      title: { type: 'Text', props: { text: 'Client Playground', 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',
-        },
+
+      // ── Two-way binding: type a name, see it echoed live; toggle a switch ──
+      hello: { type: 'Card', props: { title: 'Say hello' }, children: ['helloBody'] },
+      helloBody: { type: 'Stack', props: { gap: 10 }, children: ['nameInput', 'greetRow', 'compact'] },
+      nameInput: { type: 'TextInput', props: { label: 'Your name', placeholder: 'Type your name…', value: { $bindState: '/form/name' } }, children: [] },
+      greetRow: { type: 'Stack', props: { direction: 'row', gap: 6, align: 'center' }, children: ['greetLabel', 'greetName'] },
+      greetLabel: { type: 'Text', props: { text: 'Hello,', variant: 'body', color: 'muted' }, children: [] },
+      greetName: { type: 'Text', props: { text: { $state: '/form/name' }, variant: 'body', color: 'primary' }, children: [] },
+      compact: { type: 'Switch', props: { label: 'Compact mode', value: { $bindState: '/prefs/compact' } }, children: [] },
+
+      // ── Actions mutate state → the DataTable re-renders ──
+      notes: { type: 'Card', props: { title: 'Notes' }, children: ['notesBody'] },
+      notesBody: { type: 'Stack', props: { gap: 10 }, children: ['draftRow', 'notesTable', 'clearBtn'] },
+      draftRow: { type: 'Stack', props: { direction: 'row', gap: 8, align: 'end' }, children: ['draftInput', 'addBtn'] },
+      draftInput: { type: 'TextInput', props: { label: 'New note', placeholder: 'Write something…', value: { $bindState: '/draft' } }, children: [] },
+      addBtn: {
+        type: 'Button',
+        props: { label: 'Add', variant: 'primary', icon: 'ph:plus' },
+        // Built-in `pushState`: append the typed draft to /notes, then clear the input.
+        on: { press: { action: 'pushState', params: { statePath: '/notes', value: { text: { $state: '/draft' } }, clearStatePath: '/draft' } } },
+        children: [],
+      },
+      notesTable: {
+        type: 'DataTable',
+        props: { columns: [{ key: 'text', label: 'Note' }], rows: { $state: '/notes' }, height: 160 },
+        children: [],
+      },
+      clearBtn: {
+        type: 'Button',
+        props: { label: 'Clear all', variant: 'ghost', icon: 'ph:trash' },
+        // Built-in `setState`: replace /notes with an empty array.
+        on: { press: { action: 'setState', params: { statePath: '/notes', value: [] } } },
         children: [],
       },
-      env: { type: 'Card', props: { title: 'Environment' }, children: ['envTable'] },
+
+      env: { type: 'Card', props: { title: 'Environment', collapsible: true, defaultCollapsed: true }, children: ['envTable'] },
       envTable: {
         type: 'KeyValueTable',
         props: {
           data: {
             clientType,
             language: navigator.language,
             viewport: `${window.innerWidth}×${window.innerHeight}`,
-            online: navigator.onLine ? 'yes' : 'no',
           },
         },
         children: [],
       },
     },
-    state: {},
+    state: {
+      form: { name: '' },
+      prefs: { compact: false },
+      draft: '',
+      notes: [{ text: 'Authored entirely in the browser' }],
+    },
   }
 }
 
@@ -161,14 +193,16 @@ async function main() {
   // Register a second client-only dock — this one a *json-render* view the page
   // authors itself, the richer sibling of the iframe dock above. Its spec is
   // carried **inline** in the dock entry (`view.spec`), so it needs no shared
-  // state at all: it lives only in this page yet renders through the very same
-  // `json-render` dock renderer registered above as a server-authored view.
+  // state at all: it lives only in this page yet renders — and stays fully
+  // interactive (inputs, toggles, and buttons that mutate its state) — through
+  // the very same `json-render` dock renderer registered above as a
+  // server-authored view.
   host.context.docks.register<DevframeJsonRenderDockEntry>({
-    id: 'client-metrics',
-    title: 'Client Metrics',
-    icon: 'ph:gauge-duotone',
+    id: 'client-playground',
+    title: 'Client Playground',
+    icon: 'ph:sliders-horizontal-duotone',
     type: 'json-render',
-    view: { spec: createClientMetricsSpec(host.context.clientType) },
+    view: { spec: createClientPlaygroundSpec(host.context.clientType) },
     category: 'app',
   })