fix(json-render): declare renderer peer and document view ownership

Author: dvcolomban

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

@@ -170,7 +170,7 @@ and the [`json-render` example](https://github.com/devframes/devframe/tree/main/
 
 ## Rendering with a custom RPC channel
 
-A host page can import the reference browser bundle directly. It includes its renderer and styles:
+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'
@@ -187,4 +187,14 @@ 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.
+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

@@ -43,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/src/view.ts

@@ -34,7 +34,7 @@ export interface CreateJsonRenderViewOptions<SpecType extends DevframeJsonRender
   title?: string
 }
 
-/** Native shared-state publication required by a JSON view. */
+/** Reuse one context per native shared-state instance for view discovery and duplicate detection. */
 export interface JsonRenderViewContext {
   rpc: { sharedState: RpcSharedStateHost }
 }

packages/json-render/test/create-view.test.ts

@@ -59,15 +59,20 @@ describe('createJsonRenderView identity', () => {
 
 describe('createJsonRenderView state', () => {
   it('publishes and disposes through a shared-state-only context', async () => {
-    expect.assertions(3)
+    expect.assertions(5)
     const context = { rpc: { sharedState: ctx.rpc.sharedState } }
     const view = createPortableView(context, { id: 'portable', spec })
     const state = await context.rpc.sharedState.get(view.ref.stateKey)
     expect(state.value()).toEqual(spec)
+    const secondView = createPortableView(context, { id: 'second', spec })
+    const index = await context.rpc.sharedState.get(JSON_RENDER_INDEX_KEY)
+    expect(Object.keys(index.value())).toEqual([view.ref.stateKey, secondView.ref.stateKey])
+    expect(() => createPortableView(context, { id: 'portable', spec })).toThrow()
     view.patchState([{ op: 'replace', path: '/count', value: 2 }])
     expect(state.value().state).toEqual({ count: 2 })
     view.dispose()
     expect(context.rpc.sharedState.keys()).not.toContain(view.ref.stateKey)
+    secondView.dispose()
   })
 
   it('registers a shared state carrying the spec', async () => {

tests/__snapshots__/tsnapi/@devframes/json-render-ui/renderer.snapshot.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@devframes/json-render-ui/renderer`
+ */
+// #region Default Export
+declare const _default: JsonRenderDockRenderer<JsonRenderRpcContext>;
+export default _default
+// #endregion

tests/__snapshots__/tsnapi/@devframes/json-render-ui/renderer.snapshot.js

@@ -0,0 +1,7 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@devframes/json-render-ui/renderer`
+ */
+// #region Default Export
+var _default
+export default _default
+// #endregion

tests/__snapshots__/tsnapi/@devframes/json-render/hub.snapshot.d.ts

@@ -6,11 +6,18 @@ export interface DevframeJsonRenderDockEntry extends DevframeDockEntryBase {
   type: 'json-render';
   view: JsonRenderViewRef;
 }
+export interface JsonRenderRpcContext {
+  rpc: Pick<DevframeRpcClient, 'call' | 'sharedState'> & {
+    connectionMeta?: Pick<ConnectionMeta, 'backend'>;
+  };
+}
 // #endregion
 
 // #region Types
-export type JsonRenderDockMountOptions = DockRendererMountOptions<DevframeJsonRenderDockEntry>;
-export type JsonRenderDockRenderer = DockRenderer<DevframeJsonRenderDockEntry>;
+export type JsonRenderDockMountOptions<Context = DevframeClientContext> = Omit<DockRendererMountOptions<DevframeJsonRenderDockEntry>, 'context'> & {
+  context: Context;
+};
+export type JsonRenderDockRenderer<Context = DevframeClientContext> = (_: JsonRenderDockMountOptions<Context>) => DockRendererInstance | Promise<DockRendererInstance>;
 // #endregion
 
 // #region Functions

tests/__snapshots__/tsnapi/@devframes/json-render/node.snapshot.d.ts

@@ -1,24 +1,11 @@
 /**
  * Generated by tsnapi — public API snapshot of `@devframes/json-render/node`
  */
-// #region Interfaces
-export interface CreateJsonRenderViewOptions<SpecType extends DevframeJsonRenderSpec = DevframeJsonRenderSpec> {
-  id: string;
-  spec: SpecType;
-  schema?: StandardSchemaV1 | false;
-  scope?: string;
-  title?: string;
-}
-// #endregion
-
-// #region Functions
-export declare function createJsonRenderView<SpecType extends DevframeJsonRenderSpec = DevframeJsonRenderSpec>(_: AnyContext, _: CreateJsonRenderViewOptions<SpecType>): JsonRenderView<SpecType>;
-// #endregion
-
 // #region Variables
 export declare const jsonRenderDiagnostics: DevframeDiagnostics<typeof codes>;
 // #endregion
 
-// #region Referenced (internal)
-type AnyContext = DevframeNodeContext | DevframeScopedNodeContext<string>;
+// #region Other
+export { createJsonRenderView }
+export { CreateJsonRenderViewOptions }
 // #endregion

tests/__snapshots__/tsnapi/@devframes/json-render/node.snapshot.js

@@ -1,10 +1,7 @@
 /**
  * Generated by tsnapi — public API snapshot of `@devframes/json-render/node`
  */
-// #region Functions
-export function createJsonRenderView(_, _) {}
-// #endregion
-
-// #region Variables
-export var jsonRenderDiagnostics /* const */
+// #region Other
+export { createJsonRenderView }
+export { diagnostics as jsonRenderDiagnostics }
 // #endregion

tests/__snapshots__/tsnapi/@devframes/json-render/view.snapshot.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@devframes/json-render/view`
+ */
+// #region Interfaces
+export interface CreateJsonRenderViewOptions<SpecType extends DevframeJsonRenderSpec = DevframeJsonRenderSpec> {
+  id: string;
+  spec: SpecType;
+  schema?: StandardSchemaV1 | false;
+  scope?: string;
+  title?: string;
+}
+export interface JsonRenderScopedViewContext {
+  base: JsonRenderViewContext;
+  namespace: string;
+}
+export interface JsonRenderViewContext {
+  rpc: {
+    sharedState: RpcSharedStateHost;
+  };
+}
+// #endregion
+
+// #region Functions
+export declare function createJsonRenderView<SpecType extends DevframeJsonRenderSpec = DevframeJsonRenderSpec>(_: AnyContext, _: CreateJsonRenderViewOptions<SpecType>): JsonRenderView<SpecType>;
+// #endregion
+
+// #region Referenced (internal)
+type AnyContext = JsonRenderViewContext | JsonRenderScopedViewContext;
+// #endregion