feat(json-render)!: accept an inline spec in the view ref; drop upstreamVersion

The `json-render` dock's `view` field now accepts either `{ stateKey }`
(subscribe to a live shared state) or `{ spec }` (an inline spec rendered
directly), so a client host can synthesize a view entirely in the browser
with no shared-state round-trip. Both dock renderers (Vue + the example's
React registry) render the inline spec statically and keep subscribing for
the shared-state variant.

Removes the `upstreamVersion` field and the `JSON_RENDER_UPSTREAM_VERSION`
export along with the renderer's version-mismatch warning, simplifying the
serializable view contract.

BREAKING CHANGE: `JsonRenderViewRef` no longer carries `upstreamVersion`;
`JSON_RENDER_UPSTREAM_VERSION` and the `JsonRenderView` `upstreamVersion`
prop are removed.

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 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.
+- [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.
 
 ## 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 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.
+- [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.
 
 ## Run it
 

docs/guide/client-context.md

@@ -90,24 +90,22 @@ 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:
+A client-only dock can render a [JSON-render](./json-render) view the page authors itself. Carry the spec **inline** in the dock's `view` — no shared state, no server round-trip — and register a `json-render` dock. 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
-})
+const 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 },
+  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).
+
 ## 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:

docs/guide/json-render.md

@@ -129,7 +129,6 @@ its SPA. Connect, read the view's shared state, and render it with
 `JsonRenderView`:
 
 ```ts
-import { JSON_RENDER_UPSTREAM_VERSION } from '@devframes/json-render'
 import { JsonRenderView } from '@devframes/json-render-ui'
 import { connectDevframe } from 'devframe/client'
 import { createApp, h, shallowRef } from 'vue'
@@ -145,7 +144,6 @@ createApp({
   render: () => h(JsonRenderView, {
     spec: spec.value,
     rpc,
-    upstreamVersion: JSON_RENDER_UPSTREAM_VERSION,
     interactive: rpc.connectionMeta.backend !== 'static',
   }),
 }).mount('#app')
@@ -205,10 +203,13 @@ const host = await createDevframeClientHost({
 const dispose = await host.context.renderers.mount(entry, container)
 ```
 
-The dock carries only a serializable `JsonRenderViewRef` (`{ stateKey,
-upstreamVersion }`) — no functions cross the wire. The client host disposes the
-renderer when the dock deactivates. A renderer/upstream-version mismatch logs a
-warning rather than blocking.
+The dock carries only a serializable `JsonRenderViewRef` — no functions cross
+the wire. It comes in two shapes: `{ stateKey }` points the client at a live
+shared state to subscribe to (what `createJsonRenderView` produces), while
+`{ spec }` embeds the whole spec inline, so a client can synthesize a view in
+the browser and render it with no shared state at all (see [client-only
+docks](./client-context#client-only-docks)). The client host disposes the
+renderer when the dock deactivates.
 
 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)

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

@@ -11,7 +11,6 @@ import type {
 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'
@@ -59,11 +58,6 @@ 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
@@ -170,22 +164,18 @@ export default function Page() {
         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),
-        })
+        // 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.
         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 },
+          view: { spec: createClientMetricsSpec(clientHost.context.clientType) },
           category: 'app',
         }, true)
 

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

@@ -3,7 +3,7 @@
 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 { basePropSchemas } from '@devframes/json-render'
 import { JSONUIProvider, Renderer } from '@json-render/react'
 import { useMemo } from 'react'
 import { createRoot } from 'react-dom/client'
@@ -63,18 +63,17 @@ interface JsonRenderViewProps {
   rpc: { call: (method: string, ...args: unknown[]) => Promise<unknown> }
   registry: ComponentRegistry
   viewId: string
-  upstreamVersion?: string
 }
 
-function JsonRenderView({ spec, rpc, registry, viewId, upstreamVersion }: JsonRenderViewProps): ReactNode {
+function JsonRenderView({ spec, rpc, registry, viewId }: 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}`}
+      // Reset the provider (reseed state) only on identity change.
+      key={viewId}
       registry={registry}
       handlers={handlers}
       initialState={spec.state ?? {}}
@@ -95,22 +94,37 @@ export interface ReactDockMountOptions {
  * 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.
+ * provides. For a shared-state view it subscribes to the live spec; for an
+ * inline view (`entry.view.spec`) it renders the embedded spec directly, with
+ * no shared-state round-trip. Disposes cleanly either way.
  */
 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 viewId = 'stateKey' in view ? view.stateKey : ((entry as { id?: string }).id ?? 'inline')
     const root = createRoot(container)
+
+    // Inline view: render the embedded spec once, no shared state involved.
+    if ('spec' in view) {
+      root.render(
+        <JsonRenderView spec={view.spec} rpc={rpc} registry={baseReactRegistry} viewId={viewId} />,
+      )
+      return {
+        dispose() {
+          root.unmount()
+        },
+      }
+    }
+
+    const state = await rpc.sharedState.get(view.stateKey, { initialValue: null })
     const render = (): void => {
       root.render(
         <JsonRenderView
           spec={state.value() as Spec | null}
           rpc={rpc}
           registry={baseReactRegistry}
-          viewId={view.stateKey}
-          upstreamVersion={view.upstreamVersion}
+          viewId={viewId}
         />,
       )
     }

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

@@ -8,7 +8,6 @@ import type {
 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'
@@ -83,11 +82,6 @@ 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
@@ -165,20 +159,16 @@ async function main() {
   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),
-  })
+  // 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.
   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 },
+    view: { spec: createClientMetricsSpec(host.context.clientType) },
     category: 'app',
   })
 

packages/hub/src/client/__tests__/renderers.test.ts

@@ -49,7 +49,7 @@ const jsonRenderEntry = {
   title: 'Metrics',
   icon: 'ph:cube',
   type: 'json-render',
-  view: { stateKey: 'devframe:json-render:global:metrics', upstreamVersion: '0.19.0' },
+  view: { stateKey: 'devframe:json-render:global:metrics' },
 } as unknown as DevframeDockEntry
 
 const container = {} as HTMLElement

packages/json-render-ui/src/dock-renderer.ts

@@ -38,10 +38,13 @@ export interface JsonRenderDockRendererOptions {
  * })
  * ```
  *
- * It subscribes to the view's shared state (`entry.view.stateKey`), mounts a
- * Vue app rendering {@link JsonRenderView}, and disposes cleanly — unmounting
- * the app and unsubscribing the shared-state listener — when the dock
- * deactivates (the client host drives that).
+ * For a shared-state view (`entry.view.stateKey`) it subscribes to the live
+ * spec and re-renders on every update; for an inline view (`entry.view.spec`)
+ * it renders the embedded spec directly, with no shared-state round-trip — the
+ * path a client-synthesized view takes. Either way it mounts a Vue app
+ * rendering {@link JsonRenderView} and disposes cleanly — unmounting the app and
+ * unsubscribing any shared-state listener — when the dock deactivates (the
+ * client host drives that).
  */
 export function createJsonRenderDockRenderer(
   options: JsonRenderDockRendererOptions = {},
@@ -51,28 +54,34 @@ export function createJsonRenderDockRenderer(
     const view = (entry as { view: JsonRenderViewRef }).view
     const rpc = context.rpc
     const interactive = rpc.connectionMeta?.backend !== 'static'
-    const state = await rpc.sharedState.get(view.stateKey, { initialValue: null })
+    const viewId = 'stateKey' in view ? view.stateKey : ((entry as { id?: string }).id ?? 'inline')
 
-    const specRef = shallowRef<Spec | null>(state.value() as Spec | null)
-    const off = state.on('updated', () => {
+    // Inline view: render the embedded spec as-is; shared-state view: subscribe
+    // to the live spec and track updates through `specRef`.
+    const specRef = shallowRef<Spec | null>('spec' in view ? view.spec : null)
+    let off: (() => void) | undefined
+    if ('stateKey' in view) {
+      const state = await rpc.sharedState.get(view.stateKey, { initialValue: null })
       specRef.value = state.value() as Spec | null
-    })
+      off = state.on('updated', () => {
+        specRef.value = state.value() as Spec | null
+      })
+    }
 
     const app = createApp({
       render: () => h(JsonRenderView, {
         spec: specRef.value,
         rpc: rpc as ActionBridgeRpc,
         registry,
-        viewId: view.stateKey,
-        upstreamVersion: view.upstreamVersion,
+        viewId,
         interactive,
       }),
     })
     app.mount(container)
 
     return {
       dispose() {
-        off()
+        off?.()
         app.unmount()
       },
     }