feat(json-render-ui): provider SPA single-view mode, theming, provider factory

Enables json-render-ui's SPA as the hub's iframe view provider:

- Single-view mode: ?view=<stateKey> renders exactly one view (no nav) — the
  shape the hub mounts as one pooled iframe per view. The index-driven
  dashboard remains for standalone use.
- Theming: follow the host color scheme via the shared devframes-color-scheme
  storage key, and the brand primary via the hub's branding.json (with a
  primary-ramp override so --devframe-primary retints the SPA). Best-effort:
  standalone use keeps the OS scheme + default palette.
- jsonRenderProvider(): a turnkey DevframeDefinition serving this SPA, for
  initHub({ viewProviders: { 'json-render': jsonRenderProvider() } }).
- Deprecate createJsonRenderDockRenderer in favor of the iframe provider.

Author: antfubot

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

@@ -38,6 +38,12 @@ export interface JsonRenderDockRendererOptions {
  * })
  * ```
  *
+ * @deprecated Prefer the iframe **view-provider** model: register
+ * {@link jsonRenderProvider} with the hub (`initHub({ viewProviders: { 'json-render':
+ * jsonRenderProvider() } })`), which renders json-render in a swappable,
+ * framework-agnostic iframe. This in-process renderer couples the renderer to a
+ * Vue host and is kept only for existing same-framework hosts.
+ *
  * 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

packages/json-render-ui/src/spa.ts

@@ -1,4 +1,5 @@
 import type { DevframeDefinition } from 'devframe/types'
+import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 
 /**
@@ -37,3 +38,35 @@ export function createJsonRenderDevframe(definition: DevframeDefinition): Devfra
     cli: { ...definition.cli, distDir: definition.cli?.distDir ?? jsonRenderSpaDir },
   }
 }
+
+/**
+ * A turnkey json-render **view provider** — a {@link DevframeDefinition} serving
+ * this package's prebuilt SPA, ready to register with a hub's view-provider
+ * slot so `json-render` docks render in an iframe:
+ *
+ * ```ts
+ * import { jsonRenderProvider } from '@devframes/json-render-ui/spa'
+ * initHub({ viewProviders: { 'json-render': jsonRenderProvider() } })
+ * ```
+ *
+ * The provider frame only serves the SPA; view specs are published by other
+ * devframes' `setup()` (via `createJsonRenderView`) into shared state the SPA
+ * reads by `stateKey`, so its own `setup` is a no-op. Any field can be
+ * overridden (id, name, port, a custom `distDir` for a community renderer, …).
+ */
+export function jsonRenderProvider(overrides: Partial<DevframeDefinition> = {}): DevframeDefinition {
+  const { version } = createRequire(import.meta.url)('../package.json') as { version: string }
+  return {
+    id: 'json-render',
+    name: 'JSON Render',
+    version,
+    packageName: '@devframes/json-render-ui',
+    homepage: 'https://github.com/devframes/devframe#readme',
+    description: 'Reference json-render view provider.',
+    icon: 'ph:layout-duotone',
+    setup: () => {},
+    ...overrides,
+    spa: { loader: 'none', ...overrides.spa },
+    cli: { ...overrides.cli, distDir: overrides.cli?.distDir ?? jsonRenderSpaDir },
+  }
+}

packages/json-render-ui/src/spa/main.ts

@@ -1,60 +1,72 @@
 import type { DevframeJsonRenderSpec, JsonRenderIndex, JsonRenderIndexEntry } from '@devframes/json-render'
+import type { DevframeRpcClient } from 'devframe/client'
+import type { Ref } from 'vue'
 import type { ActionBridgeRpc } from '../action-bridge'
 import { JSON_RENDER_INDEX_KEY } from '@devframes/json-render'
 import { connectDevframe } from 'devframe/client'
 import { computed, createApp, defineComponent, h, ref, shallowReactive, shallowRef, watch } from 'vue'
 import { JsonRenderView } from '../renderer'
+import { applyBranding, initColorScheme } from './theme'
 import 'virtual:uno.css'
 import '@antfu/design/styles.css'
+// After uno so the brand-primary override wins (see primary-ramp.css).
+import './primary-ramp.css'
 
-// Shared design tokens flip on the `.dark` class; mirror the OS preference.
-const mq = window.matchMedia('(prefers-color-scheme: dark)')
-function applyScheme(dark: boolean): void {
-  document.documentElement.classList.toggle('dark', dark)
-}
-applyScheme(mq.matches)
-mq.addEventListener('change', e => applyScheme(e.matches))
+// Follow the host's color scheme + brand primary (both best-effort standalone).
+initColorScheme()
+void applyBranding()
 
 const surface = 'flex min-h-screen items-center justify-center color-faint text-sm'
 
-async function main(): Promise<void> {
-  const root = document.getElementById('app')
-  if (!root)
-    throw new Error('#app mount node missing')
-
-  const rpc = await connectDevframe()
-  const interactive = rpc.connectionMeta.backend !== 'static'
-
-  // Discover every live view from the single view-index shared state, then
-  // subscribe to each view's own state. The author never wires a view id into
-  // the client — publishing a view is enough for it to appear here.
-  const indexState = await rpc.sharedState.get<JsonRenderIndex>(JSON_RENDER_INDEX_KEY, { initialValue: {} })
-  // Seed the current server value before mounting so an empty tree isn't
-  // mistaken for "no views" during the first round-trip.
-  if (interactive) {
-    try {
-      const value = await rpc.call('devframe:rpc:server-state:get', JSON_RENDER_INDEX_KEY)
-      if (value && typeof value === 'object')
-        indexState.mutate(() => value as JsonRenderIndex)
-    }
-    catch {
-      // Non-fatal: fall back to live 'updated' events below.
-    }
-  }
+/** Subscribe to a view's live spec, keyed by `stateKey`. */
+function subscribeSpec(
+  rpc: DevframeRpcClient,
+  stateKey: string,
+  into: (spec: DevframeJsonRenderSpec | null) => void,
+): void {
+  void rpc.sharedState
+    .get<DevframeJsonRenderSpec>(stateKey, { initialValue: null as unknown as DevframeJsonRenderSpec })
+    .then((state) => {
+      into(state.value() as DevframeJsonRenderSpec | null)
+      state.on('updated', () => into(state.value() as DevframeJsonRenderSpec | null))
+    })
+}
 
-  const indexRef = shallowRef<JsonRenderIndex>(indexState.value() as JsonRenderIndex)
-  indexState.on('updated', () => {
-    indexRef.value = indexState.value() as JsonRenderIndex
+/**
+ * Single-view mode (`?view=<stateKey>`): render exactly one view, no nav — the
+ * shape the hub's iframe view-provider mounts (one pooled iframe per view).
+ */
+function mountSingleView(root: HTMLElement, rpc: DevframeRpcClient, stateKey: string, interactive: boolean): void {
+  const spec = shallowRef<DevframeJsonRenderSpec | null | undefined>(undefined)
+  subscribeSpec(rpc, stateKey, s => (spec.value = s))
+  const App = defineComponent({
+    name: 'JsonRenderSingleView',
+    setup() {
+      return () => h('div', { class: 'min-h-screen bg-base color-base font-sans p6' }, [
+        h(JsonRenderView, {
+          spec: spec.value ?? null,
+          rpc: rpc as unknown as ActionBridgeRpc,
+          viewId: stateKey,
+          interactive,
+          loading: spec.value === undefined,
+        }),
+      ])
+    },
   })
+  createApp(App).mount(root)
+}
 
+/**
+ * Dashboard mode: discover every live view from the view index and render a
+ * segmented switcher. The standalone experience when no single view is pinned.
+ */
+function mountDashboard(root: HTMLElement, rpc: DevframeRpcClient, indexRef: Ref<JsonRenderIndex>, interactive: boolean): void {
   const App = defineComponent({
     name: 'JsonRenderSpa',
     setup() {
       const entries = computed<JsonRenderIndexEntry[]>(() =>
         Object.values(indexRef.value).sort((a, b) => a.title.localeCompare(b.title)))
 
-      // Per-view specs, keyed by stateKey. `undefined` = subscribing (loading),
-      // `null` = subscribed with no spec yet.
       const specs = shallowReactive<Record<string, DevframeJsonRenderSpec | null | undefined>>({})
       const subscribed = new Set<string>()
       const active = ref<string | null>(null)
@@ -65,14 +77,7 @@ async function main(): Promise<void> {
             continue
           subscribed.add(entry.stateKey)
           specs[entry.stateKey] = undefined
-          void rpc.sharedState
-            .get<DevframeJsonRenderSpec>(entry.stateKey, { initialValue: null as unknown as DevframeJsonRenderSpec })
-            .then((state) => {
-              specs[entry.stateKey] = state.value() as DevframeJsonRenderSpec | null
-              state.on('updated', () => {
-                specs[entry.stateKey] = state.value() as DevframeJsonRenderSpec | null
-              })
-            })
+          subscribeSpec(rpc, entry.stateKey, s => (specs[entry.stateKey] = s))
         }
         if (!active.value || !list.some(e => e.stateKey === active.value))
           active.value = list[0]?.stateKey ?? null
@@ -101,9 +106,6 @@ async function main(): Promise<void> {
 
         const activeEntry = list.find(e => e.stateKey === active.value) ?? list[0]
         const spec = specs[activeEntry.stateKey]
-
-        // A single view renders on its own — no nav. The top bar (brand +
-        // segmented view switcher) only appears once there's more than one.
         const multiple = list.length > 1
 
         return h('div', { class: 'min-h-screen bg-base color-base font-sans' }, [
@@ -131,10 +133,47 @@ async function main(): Promise<void> {
       }
     },
   })
-
   createApp(App).mount(root)
 }
 
+async function main(): Promise<void> {
+  const root = document.getElementById('app')
+  if (!root)
+    throw new Error('#app mount node missing')
+
+  const rpc = await connectDevframe()
+  const interactive = rpc.connectionMeta.backend !== 'static'
+
+  // The hub's iframe view-provider pins one view via `?view=<stateKey>`.
+  const pinned = new URLSearchParams(location.search).get('view')
+  if (pinned) {
+    mountSingleView(root, rpc, pinned, interactive)
+    return
+  }
+
+  // Dashboard: discover every live view from the single view-index shared
+  // state. The author never wires a view id into the client — publishing a
+  // view is enough for it to appear here.
+  const indexState = await rpc.sharedState.get<JsonRenderIndex>(JSON_RENDER_INDEX_KEY, { initialValue: {} })
+  if (interactive) {
+    try {
+      const value = await rpc.call('devframe:rpc:server-state:get', JSON_RENDER_INDEX_KEY)
+      if (value && typeof value === 'object')
+        indexState.mutate(() => value as JsonRenderIndex)
+    }
+    catch {
+      // Non-fatal: fall back to live 'updated' events below.
+    }
+  }
+
+  const indexRef = shallowRef<JsonRenderIndex>(indexState.value() as JsonRenderIndex)
+  indexState.on('updated', () => {
+    indexRef.value = indexState.value() as JsonRenderIndex
+  })
+
+  mountDashboard(root, rpc, indexRef, interactive)
+}
+
 main().catch((error) => {
   console.error(error)
   document.body.textContent = `Failed to start: ${(error as Error).message}`

packages/json-render-ui/src/spa/primary-ramp.css

@@ -0,0 +1,24 @@
+/*
+ * Primary color as a single overridable variable, `--devframe-primary`, so the
+ * host's brand (applied in theme.ts from branding.json) retints this provider
+ * SPA. Imported after `virtual:uno.css` so it wins over Wind4's own `:root`
+ * primary declarations. Each stop derives from `--devframe-primary` via
+ * `color-mix`; unset, the intermediate vars are guaranteed-invalid so each
+ * `--colors-primary-*` falls back to the exact devframe default hex.
+ *
+ * Mirrors the same block in `@devframes/hub-ui` (kept in sync deliberately;
+ * the two packages don't share a stylesheet).
+ */
+:root {
+  --devframe-primary-DEFAULT: var(--devframe-primary);
+  --devframe-primary-600: color-mix(in oklab, var(--devframe-primary), white 9%);
+  --devframe-primary-500: color-mix(in oklab, var(--devframe-primary), white 18%);
+  --devframe-primary-400: color-mix(in oklab, var(--devframe-primary), white 34%);
+  --devframe-primary-300: color-mix(in oklab, var(--devframe-primary), white 54%);
+
+  --colors-primary-DEFAULT: var(--devframe-primary-DEFAULT, #3a6a45);
+  --colors-primary-600: var(--devframe-primary-600, #40704b);
+  --colors-primary-500: var(--devframe-primary-500, #578861);
+  --colors-primary-400: var(--devframe-primary-400, #75a67e);
+  --colors-primary-300: var(--devframe-primary-300, #93c69d);
+}

packages/json-render-ui/src/spa/theme.ts

@@ -0,0 +1,64 @@
+// Color-scheme + brand theming for the provider SPA, shared same-origin with
+// the host. Dark/light follows the `devframes-color-scheme` localStorage key
+// (the hub writes it; falls back to the OS preference), and the brand primary
+// comes from the hub's `branding.json`. Both are best-effort: run standalone
+// (no hub, no key, no branding.json) and it simply uses the OS scheme and the
+// default devframe palette.
+
+const COLOR_SCHEME_KEY = 'devframes-color-scheme'
+type ColorSchemePreference = 'auto' | 'light' | 'dark'
+
+function readPreference(): ColorSchemePreference {
+  try {
+    const value = localStorage.getItem(COLOR_SCHEME_KEY)
+    if (value === 'light' || value === 'dark' || value === 'auto')
+      return value
+  }
+  catch {
+    // localStorage can throw in sandboxed frames — fall back to auto.
+  }
+  return 'auto'
+}
+
+/**
+ * Mirror the host's color scheme onto `.dark`, following the shared
+ * `devframes-color-scheme` key (cross-frame via `storage` events) and the OS
+ * preference when unset.
+ */
+export function initColorScheme(): void {
+  const mq = window.matchMedia('(prefers-color-scheme: dark)')
+  const apply = (): void => {
+    const preference = readPreference()
+    const dark = preference === 'auto' ? mq.matches : preference === 'dark'
+    document.documentElement.classList.toggle('dark', dark)
+  }
+  apply()
+  mq.addEventListener('change', apply)
+  window.addEventListener('storage', (e) => {
+    if (e.key === COLOR_SCHEME_KEY || e.key === null)
+      apply()
+  })
+}
+
+/**
+ * Apply the host's brand primary by fetching `branding.json` (published by the
+ * hub's `createUi({ branding })` at the hub base). The provider SPA is mounted
+ * one segment under that base (`<base><id>/`), so try one level up first, then a
+ * sibling; silently skip when unbranded.
+ */
+export async function applyBranding(): Promise<void> {
+  for (const rel of ['../branding.json', './branding.json']) {
+    try {
+      const res = await fetch(new URL(rel, document.baseURI))
+      if (!res.ok)
+        continue
+      const branding = await res.json() as { primaryColor?: string }
+      if (branding && typeof branding.primaryColor === 'string')
+        document.documentElement.style.setProperty('--devframe-primary', branding.primaryColor)
+      return
+    }
+    catch {
+      // Try the next candidate; unbranded/standalone use falls through.
+    }
+  }
+}

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

@@ -42,6 +42,7 @@ export type JsonRenderDockRenderer = (_: JsonRenderDockMountOptions) => Promise<
 export declare function createActionBridge(_: ActionBridgeRpc, _?: {
   interactive?: boolean;
 }): JsonRenderActionBridge;
+/** @deprecated */
 export declare function createJsonRenderDockRenderer(_?: JsonRenderDockRendererOptions): JsonRenderDockRenderer;
 export declare function createRenderer(_?: CreateRendererOptions): import("vue").DefineComponent<{}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
   [key: string]: any;

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

@@ -3,6 +3,7 @@
  */
 // #region Functions
 export function createActionBridge(_, _) {}
+/** @deprecated */
 export function createJsonRenderDockRenderer(_) {}
 export function createRenderer(_) {}
 export function sanitizeSpec(_, _) {}

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

@@ -3,6 +3,7 @@
  */
 // #region Functions
 export declare function createJsonRenderDevframe(_: DevframeDefinition): DevframeDefinition;
+export declare function jsonRenderProvider(_?: Partial<DevframeDefinition>): DevframeDefinition;
 // #endregion
 
 // #region Variables

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

@@ -3,6 +3,7 @@
  */
 // #region Functions
 export function createJsonRenderDevframe(_) {}
+export function jsonRenderProvider(_) {}
 // #endregion
 
 // #region Variables