feat(json-render): support native RPC contexts in browser surfaces

Tracked in dvcol/devkit-extension#12. Preserve existing renderer context defaults, expose the prebuilt browser renderer and portable view publication, and clean up failed mounts. Scoped lint, type checks, existing renderer tests and live extension proof pass.

Author: dvcolomban

alias.ts

@@ -78,6 +78,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/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,24 @@ 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:
+
+```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` and pass `{ rpc: { sharedState } }`. Its native publishing state must support `get(key, { sharedState })`. The node-side import and scoped node contexts continue to 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": [

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-export.ts

@@ -0,0 +1,5 @@
+import type { JsonRenderDockRenderer, JsonRenderRpcContext } from '@devframes/json-render/hub'
+
+/** Self-styling browser renderer, also served by `jsonRenderUiRenderer()`. */
+declare const renderer: JsonRenderDockRenderer<JsonRenderRpcContext>
+export default renderer

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-export.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