feat(json-render): expose native rendering for browser contexts

Author: dvcolomban

alias.ts

@@ -77,6 +77,7 @@ export const alias = {
   '@devframes/vite': r('vite/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/view': r('json-render/src/node/create-view.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/hub': r('json-render-ui/src/hub.ts'),

docs/content/1.guide/21.build-your-own-json-render-frontend.md

@@ -29,7 +29,7 @@ Resolve the entry's `view`:
   it as the live spec, re-render on `'updated'`. **Unsubscribe in `dispose`.**
 - `{ spec }`: render the embedded spec directly.
 
-Detect static output via `context.rpc.connectionMeta.backend === 'static'`,
+Detect static output via `context.rpc.connectionMeta?.backend === 'static'`,
 disabling action dispatch there.
 
 ## Behavior expectations

docs/content/1.guide/8.json-render.md

@@ -167,3 +167,34 @@ for a browser-synthesized [client-only dock](/guide/client-context#client-only-d
 reference implementation.
 See [Build your own JSON-Render frontend](/guide/build-your-own-json-render-frontend)
 and the [`json-render` example](https://github.com/devframes/devframe/tree/main/examples/json-render).
+
+## Rendering with a custom RPC channel
+
+A host page can import the reference browser bundle directly. It includes its renderer and styles. TypeScript consumers also install the `@devframes/json-render`, `@devframes/hub` and `devframe` peers for the renderer declarations:
+
+```ts
+import renderer from '@devframes/json-render-ui/renderer'
+
+const mounted = await renderer({
+  entry,
+  container,
+  context: { rpc: { call, sharedState } },
+})
+
+// When the surface closes:
+mounted.dispose?.()
+```
+
+`call` and `sharedState` are native RPC members. An optional `connectionMeta.backend` marks static output. The reference implementation accepts this smaller `JsonRenderRpcContext`; a full hub client context also satisfies it. Custom `JsonRenderDockRenderer` implementations retain the full client context by default and can declare their own context type through its generic parameter.
+
+For view publication in a worker, import `createJsonRenderView` from `@devframes/json-render/view`. Its native publishing state must support `get(key, { sharedState })`. Reuse one context object for all views on that state instance. View discovery and duplicate detection belong to this context:
+
+```ts
+import { createJsonRenderView } from '@devframes/json-render/view'
+
+const context = { rpc: { sharedState } }
+const metrics = createJsonRenderView(context, { id: 'metrics', spec: metricsSpec })
+const details = createJsonRenderView(context, { id: 'details', spec: detailsSpec })
+```
+
+The node-side import and scoped node contexts use the same implementation.

packages/json-render-ui/package.json

@@ -22,6 +22,10 @@
   "exports": {
     "./hub": "./dist/hub.mjs",
     "./spa": "./dist/spa.mjs",
+    "./renderer": {
+      "types": "./dist/renderer.d.mts",
+      "default": "./dist/renderer/json-render.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -39,12 +43,16 @@
   },
   "peerDependencies": {
     "@devframes/hub": "workspace:*",
+    "@devframes/json-render": "workspace:*",
     "devframe": "workspace:*"
   },
   "peerDependenciesMeta": {
     "@devframes/hub": {
       "optional": true
     },
+    "@devframes/json-render": {
+      "optional": true
+    },
     "devframe": {
       "optional": true
     }

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

@@ -1,5 +1,5 @@
 import type { JsonRenderViewRef, Spec } from '@devframes/json-render'
-import type { JsonRenderDockRenderer } from '@devframes/json-render/hub'
+import type { JsonRenderDockRenderer, JsonRenderRpcContext } from '@devframes/json-render/hub'
 import type { ComponentRegistry } from '@json-render/vue'
 import type { ActionBridgeRpc } from './action-bridge'
 import { createApp, h, shallowRef } from 'vue'
@@ -33,7 +33,7 @@ export interface JsonRenderDockRendererOptions {
  */
 export function createJsonRenderDockRenderer(
   options: JsonRenderDockRendererOptions = {},
-): JsonRenderDockRenderer {
+): JsonRenderDockRenderer<JsonRenderRpcContext> {
   const registry = options.registry ?? baseRegistry
   return async ({ entry, container, context }) => {
     const view: JsonRenderViewRef = entry.view

packages/json-render-ui/src/renderer-module/index.ts

@@ -1,4 +1,5 @@
-import type { JsonRenderDockRenderer } from '@devframes/json-render/hub'
+import type { DockRendererInstance } from '@devframes/hub/client'
+import type { JsonRenderDockRenderer, JsonRenderRpcContext } from '@devframes/json-render/hub'
 import css from '../.generated/css'
 import { createJsonRenderDockRenderer } from '../dock-renderer'
 
@@ -32,7 +33,7 @@ const inner = createJsonRenderDockRenderer()
  * there, fully styled in a light-DOM host page and inside a viewer's shadow
  * root alike, without leaking the reset or any global rule into the page.
  */
-const jsonRenderDockRenderer: JsonRenderDockRenderer = async ({ entry, container, context }) => {
+const jsonRenderDockRenderer: JsonRenderDockRenderer<JsonRenderRpcContext> = async ({ entry, container, context }) => {
   const shadow = container.shadowRoot ?? container.attachShadow({ mode: 'open' })
   if (!shadow.querySelector(`style[${STYLE_MARKER}]`)) {
     const style = document.createElement('style')
@@ -66,7 +67,15 @@ const jsonRenderDockRenderer: JsonRenderDockRenderer = async ({ entry, container
   colorSchemeRoot.append(root)
   shadow.append(colorSchemeRoot)
 
-  const instance = await inner({ entry, container: root, context })
+  let instance: DockRendererInstance
+  try {
+    instance = await inner({ entry, container: root, context })
+  }
+  catch (error) {
+    observer.disconnect()
+    colorSchemeRoot.remove()
+    throw error
+  }
   return {
     dispose() {
       observer.disconnect()

packages/json-render-ui/tsdown.config.ts

@@ -14,7 +14,7 @@ import { defineConfig } from 'tsdown'
  * emitted `.d.mts` references the packages instead of inlining their whole
  * type graph.
  */
-export default defineConfig({
+export default defineConfig([{
   entry: {
     /**
      * Node-safe entry: the prebuilt SPA path + a devframe wiring helper.
@@ -46,4 +46,11 @@ export default defineConfig({
       '@devframes/json-render/core',
     ],
   },
-})
+}, {
+  entry: { renderer: 'src/renderer-module/index.ts' },
+  clean: false,
+  tsconfig: '../../tsconfig.base.json',
+  dts: { emitDtsOnly: true },
+  outExtensions: () => ({ dts: '.d.mts' }),
+  deps: { neverBundle: ['@devframes/json-render/hub'] },
+}])

packages/json-render/package.json

@@ -23,6 +23,7 @@
     "./core": "./dist/core.mjs",
     "./hub": "./dist/hub.mjs",
     "./node": "./dist/node/index.mjs",
+    "./view": "./dist/view.mjs",
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.mts",

packages/json-render/src/hub.ts

@@ -1,5 +1,7 @@
-import type { DockRenderer, DockRendererMountOptions } from '@devframes/hub/client'
+import type { DevframeClientContext, DockRendererInstance, DockRendererMountOptions } from '@devframes/hub/client'
 import type { DevframeDockEntryBase } from '@devframes/hub/types'
+import type { DevframeRpcClient } from 'devframe/client'
+import type { ConnectionMeta } from 'devframe/types'
 import type { JsonRenderView } from './types'
 import type { JsonRenderViewRef } from './view-ref'
 
@@ -26,12 +28,22 @@ declare module '@devframes/hub/types' {
 
 /**
  * The mount options a hub viewer hands a json-render dock renderer: the
- * hub's `DockRendererMountOptions` narrowed to the `'json-render'` entry.
+ * hub's `DockRendererMountOptions` narrowed to the `'json-render'` entry
+ * and an optional context type. Existing renderers keep the full client context.
  * This protocol package owns the renderer contract so every frontend
  * (`@devframes/json-render-ui`, a community renderer, a host page's own)
  * implements one shared shape instead of re-declaring it.
  */
-export type JsonRenderDockMountOptions = DockRendererMountOptions<DevframeJsonRenderDockEntry>
+export type JsonRenderDockMountOptions<Context = DevframeClientContext> = Omit<DockRendererMountOptions<DevframeJsonRenderDockEntry>, 'context'> & {
+  context: Context
+}
+
+/** Native RPC calls and shared state consumed by the reference JSON renderer. */
+export interface JsonRenderRpcContext {
+  rpc: Pick<DevframeRpcClient, 'call' | 'sharedState'> & {
+    connectionMeta?: Pick<ConnectionMeta, 'backend'>
+  }
+}
 
 /**
  * The renderer contract for `'json-render'` docks: a hub `DockRenderer`
@@ -41,7 +53,9 @@ export type JsonRenderDockMountOptions = DockRendererMountOptions<DevframeJsonRe
  * module registered through the hub's renderer manifest
  * (`initHub({ renderers })`).
  */
-export type JsonRenderDockRenderer = DockRenderer<DevframeJsonRenderDockEntry>
+export type JsonRenderDockRenderer<Context = DevframeClientContext> = (
+  options: JsonRenderDockMountOptions<Context>,
+) => DockRendererInstance | Promise<DockRendererInstance>
 
 /**
  * Build a `json-render` dock entry from a {@link JsonRenderView} and the dock

packages/json-render/src/node/create-view.ts

@@ -1,4 +1,4 @@
-import type { DevframeNodeContext, DevframeScopedNodeContext } from 'devframe'
+import type { RpcSharedStateHost } from 'devframe/types'
 import type { SharedState, SharedStatePatch } from 'devframe/utils/shared-state'
 import type { StandardSchemaV1 } from 'devframe/utils/simple-schema'
 import type { DevframeJsonRenderSpec, JsonRenderStatePatch, JsonRenderView } from '../types'
@@ -34,17 +34,28 @@ export interface CreateJsonRenderViewOptions<SpecType extends DevframeJsonRender
   title?: string
 }
 
-type AnyContext = DevframeNodeContext | DevframeScopedNodeContext<string>
+/** Reuse one context per native shared-state instance for view discovery and duplicate detection. */
+export interface JsonRenderViewContext {
+  rpc: { sharedState: RpcSharedStateHost }
+}
+
+/** Namespace and base shared state supplied by a scoped node context. */
+export interface JsonRenderScopedViewContext {
+  base: JsonRenderViewContext
+  namespace: string
+}
+
+type AnyContext = JsonRenderViewContext | JsonRenderScopedViewContext
 
-function isScoped(ctx: AnyContext): ctx is DevframeScopedNodeContext<string> {
+function isScoped(ctx: AnyContext): ctx is JsonRenderScopedViewContext {
   return 'base' in ctx && 'namespace' in ctx
 }
 
 // One registry of live view keys per base context, so a duplicate id within a
 // scope is caught deterministically (not left to shared-state get() returning
 // the pre-existing entry).
 const registries = new WeakMap<object, Set<string>>()
-function registryFor(ctx: DevframeNodeContext): Set<string> {
+function registryFor(ctx: JsonRenderViewContext): Set<string> {
   let set = registries.get(ctx)
   if (!set) {
     set = new Set()
@@ -57,7 +68,7 @@ function registryFor(ctx: DevframeNodeContext): Set<string> {
 // `JSON_RENDER_INDEX_KEY`, so a frontend that does not know view ids ahead of
 // time can discover every live view from a single subscription.
 const indexStates = new WeakMap<object, SharedState<JsonRenderIndex>>()
-function indexStateFor(ctx: DevframeNodeContext): SharedState<JsonRenderIndex> {
+function indexStateFor(ctx: JsonRenderViewContext): SharedState<JsonRenderIndex> {
   let state = indexStates.get(ctx)
   if (!state) {
     state = createSharedState<JsonRenderIndex>({ initialValue: {} })