refactor(devframe)!: relocate json-render from devframe to devtools-kit (#327)

antfu · claude · web-flow · commit fdb319303a53 · 2026-05-11T10:37:29.000+09:00
JSON-render is a hub-layer concern: the spec is rendered by the
Vite DevTools component catalog, the renderer handle is only
consumable via a `DevToolsViewJsonRender` dock entry (kit type),
and every example pairs `createJsonRenderer` with
`ctx.docks.register({ type: 'json-render', ui })`. Move types,
factory, and `defineJsonRenderSpec` to `@vitejs/devtools-kit` so
the API lives in the package that owns the runtime contract;
`DevToolsNodeContext` is now framework-neutral as intended.

BREAKING: `ctx.createJsonRenderer` is no longer on
`DevToolsNodeContext`; use `KitNodeContext` (passed to
`Plugin.devtools.setup` and `createPluginFromDevframe`'s
`options.setup`). All in-repo consumers already run under kit.

Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -49,8 +49,8 @@ flowchart TD
 
 ## Architecture
 
-- **Devframe context** (`devframe/packages/devframe/src/node/context.ts`): `createHostContext` returns a `DevToolsNodeContext` carrying `rpc`, `views` (HTTP file-serving via `hostStatic`), `diagnostics`, `agent`, plus `cwd`/`workspaceRoot`/`mode`/`host`/`createJsonRenderer`. No docks, no terminals.
-- **Kit context** (`packages/kit/src/node/context.ts`): `createKitContext` wraps `createHostContext` and attaches the four hub hosts — `docks`, `terminals`, `messages`, `commands`. Optionally surfaces `viteConfig`/`viteServer` when mounted inside Vite DevTools. Wires the `'devframe:docks'` / `'devframe:commands'` shared-state sync.
+- **Devframe context** (`devframe/packages/devframe/src/node/context.ts`): `createHostContext` returns a `DevToolsNodeContext` carrying `rpc`, `views` (HTTP file-serving via `hostStatic`), `diagnostics`, `agent`, plus `cwd`/`workspaceRoot`/`mode`/`host`. No docks, no terminals, no json-render.
+- **Kit context** (`packages/kit/src/node/context.ts`): `createKitContext` wraps `createHostContext` and attaches the four hub hosts — `docks`, `terminals`, `messages`, `commands` — plus the `createJsonRenderer` factory. Optionally surfaces `viteConfig`/`viteServer` when mounted inside Vite DevTools. Wires the `'devframe:docks'` / `'devframe:commands'` shared-state sync.
 - **Bridge** (`packages/kit/src/node/create-plugin-from-devframe.ts`): `createPluginFromDevframe(d, opts?)` returns `PluginWithDevTools`; in its `setup`, mounts the SPA via `views.hostStatic`, auto-registers an iframe dock entry from `id`/`name`/`icon`/`basePath`, runs `d.setup(ctx)` for the devframe-level wiring, then runs `opts.setup?.(ctx)` for kit-only extensions.
 - **Vite DevTools entry** (`packages/core/src/node/context.ts`): `createDevToolsContext` calls `createKitContext`, registers Vite-specific commands (`vite:open-in-editor`, `vite:open-in-finder`), then scans Vite plugins for `.devtools.setup` hooks (which now receive the kit-augmented context).
 - **Client context**: webcomponents/Nuxt UI state (`packages/core/src/client/webcomponents/state/*`) — dock entries, panels, RPC client. Two modes: `embedded` (overlay in host app) and `standalone` (independent page).
diff --git a/devframe/docs/guide/devtool-definition.md b/devframe/docs/guide/devtool-definition.md
@@ -81,12 +81,10 @@ interface DevToolsNodeContext {
   views: DevToolsViewHost // static file hosting (`hostStatic`)
   diagnostics: DevToolsDiagnosticsHost
   agent: DevToolsAgentHost // experimental
-
-  createJsonRenderer: (spec) => JsonRenderer
 }
 ```
 
-Hub-level subsystems — `docks`, `terminals`, `messages`, `commands` — live on the kit-augmented context owned by `@vitejs/devtools-kit`. A devframe app that wants to register kit-only behavior does so through the optional `setup` hook on `createPluginFromDevframe`.
+Hub-level subsystems — `docks`, `terminals`, `messages`, `commands`, `createJsonRenderer` — live on the kit-augmented context owned by `@vitejs/devtools-kit`. A devframe app that wants to register kit-only behavior does so through the optional `setup` hook on `createPluginFromDevframe`.
 
 Each host has a dedicated page:
 - [RPC](./rpc) — `ctx.rpc`
diff --git a/devframe/packages/devframe/src/define.ts b/devframe/packages/devframe/src/define.ts
@@ -1,8 +1,4 @@
-import type { DevToolsNodeContext, JsonRenderSpec } from 'devframe/types'
+import type { DevToolsNodeContext } from 'devframe/types'
 import { createDefineWrapperWithContext } from 'devframe/rpc'
 
 export const defineRpcFunction = createDefineWrapperWithContext<DevToolsNodeContext>()
-
-export function defineJsonRenderSpec(spec: JsonRenderSpec): JsonRenderSpec {
-  return spec
-}
diff --git a/devframe/packages/devframe/src/node/context.ts b/devframe/packages/devframe/src/node/context.ts
@@ -1,5 +1,5 @@
 import type { RpcFunctionDefinitionAny } from 'devframe/rpc'
-import type { DevToolsHost, DevToolsNodeContext, JsonRenderer, JsonRenderSpec } from 'devframe/types'
+import type { DevToolsHost, DevToolsNodeContext } from 'devframe/types'
 import { diagnostics as rpcDiagnostics } from '../rpc/diagnostics'
 import { diagnostics as devframeDiagnostics } from './diagnostics'
 import { DevToolsAgentHost } from './host-agent'
@@ -24,8 +24,8 @@ export interface CreateHostContextOptions {
 /**
  * Framework-neutral core of the DevTools node context. Wires the RPC
  * host, view (HTTP file-serving) host, diagnostics, and agent
- * subsystems plus the JSON-render factory. Hub-level subsystems
- * (`docks`, `terminals`, `messages`, `commands`) are owned by
+ * subsystems. Hub-level subsystems (`docks`, `terminals`, `messages`,
+ * `commands`, `createJsonRenderer`) are owned by
  * `@vitejs/devtools-kit` — its `createKitContext` wraps this and
  * attaches them when the devtool is mounted into a multi-integration
  * hub.
@@ -42,7 +42,6 @@ export async function createHostContext(options: CreateHostContextOptions): Prom
     views: undefined!,
     diagnostics: undefined!,
     agent: undefined!,
-    createJsonRenderer: undefined!,
   } as unknown as DevToolsNodeContext
 
   const rpcHost = new RpcFunctionsHost(context)
@@ -58,28 +57,6 @@ export async function createHostContext(options: CreateHostContextOptions): Prom
   const agentHost = new DevToolsAgentHost(context)
   context.agent = agentHost
 
-  let jrCounter = 0
-  context.createJsonRenderer = (initialSpec: JsonRenderSpec): JsonRenderer => {
-    const stateKey = `devframe:json-render:${jrCounter++}`
-    const statePromise = rpcHost.sharedState.get(stateKey as any, {
-      initialValue: initialSpec as any,
-    })
-
-    return {
-      _stateKey: stateKey,
-      async updateSpec(spec) {
-        const state = await statePromise
-        state.mutate(() => spec as any)
-      },
-      async updateState(newState) {
-        const state = await statePromise
-        state.mutate((draft: any) => {
-          draft.state = { ...draft.state, ...newState }
-        })
-      },
-    }
-  }
-
   // Auto-register devframe's own agent introspection RPCs. These power
   // the MCP adapter and any future agent CLI. They are not themselves
   // agent-exposed (no `agent` field).
diff --git a/devframe/packages/devframe/src/types/context.ts b/devframe/packages/devframe/src/types/context.ts
@@ -1,7 +1,6 @@
 import type { DevToolsAgentHost } from './agent'
 import type { DevToolsDiagnosticsHost } from './diagnostics'
 import type { DevToolsHost } from './host'
-import type { JsonRenderer, JsonRenderSpec } from './json-render'
 import type { DevToolsViewHost } from './views'
 
 export interface DevToolsCapabilities {
@@ -52,10 +51,6 @@ export interface DevToolsNodeContext {
    * @experimental
    */
   agent: DevToolsAgentHost
-  /**
-   * Create a JsonRenderer handle for building json-render powered UIs.
-   */
-  createJsonRenderer: (spec: JsonRenderSpec) => JsonRenderer
 }
 
 export interface ConnectionMeta {
diff --git a/devframe/packages/devframe/src/types/index.ts b/devframe/packages/devframe/src/types/index.ts
@@ -4,7 +4,6 @@ export * from './devtool'
 export * from './diagnostics'
 export * from './events'
 export * from './host'
-export * from './json-render'
 export * from './rpc'
 export * from './rpc-augments'
 export * from './utils'
diff --git a/devframe/skills/devframe/SKILL.md b/devframe/skills/devframe/SKILL.md
@@ -86,7 +86,7 @@ See `templates/counter-devtool.ts` for a runnable counter example, `templates/sp
 | `ctx.host` | Runtime abstraction — `mountStatic`, `resolveOrigin`, `getStorageDir` |
 | `ctx.mode` | `'dev'` or `'build'` — gate setup work per runtime |
 
-> Hub-only hosts (`ctx.docks`, `ctx.terminals`, `ctx.messages`, `ctx.commands`) only exist when the devtool is mounted into Vite DevTools via `createPluginFromDevframe`. See the [`vite-devtools-kit` skill](../../skills/vite-devtools-kit) for those.
+> Hub-only hosts (`ctx.docks`, `ctx.terminals`, `ctx.messages`, `ctx.commands`, `ctx.createJsonRenderer`) only exist when the devtool is mounted into Vite DevTools via `createPluginFromDevframe`. See the [`vite-devtools-kit` skill](../../skills/vite-devtools-kit) for those.
 
 ## RPC contracts
 
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts b/devframe/tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts
@@ -1,10 +1,6 @@
 /**
  * Generated by tsnapi — public API snapshot of `devframe`
  */
-// #region Functions
-export declare function defineJsonRenderSpec(_: JsonRenderSpec): JsonRenderSpec;
-// #endregion
-
 // #region Variables
 export declare const defineRpcFunction: <NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends RpcArgsSchema | undefined = undefined, const RS extends RpcReturnSchema | undefined = undefined>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevToolsNodeContext>) => RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevToolsNodeContext>;
 // #endregion
@@ -44,9 +40,6 @@ export { EntriesToObject }
 export { EventEmitter }
 export { EventsMap }
 export { EventUnsubscribe }
-export { JsonRenderElement }
-export { JsonRenderer }
-export { JsonRenderSpec }
 export { PartialWithoutId }
 export { RpcBroadcastOptions }
 export { RpcFunctionAgentOptions }
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/index.snapshot.js b/devframe/tests/__snapshots__/tsnapi/devframe/index.snapshot.js
@@ -1,10 +1,6 @@
 /**
  * Generated by tsnapi — public API snapshot of `devframe`
  */
-// #region Functions
-export function defineJsonRenderSpec(_) {}
-// #endregion
-
 // #region Variables
 export var defineRpcFunction /* const */
 // #endregion
diff --git a/devframe/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts b/devframe/tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts
@@ -36,9 +36,6 @@ export { EntriesToObject }
 export { EventEmitter }
 export { EventsMap }
 export { EventUnsubscribe }
-export { JsonRenderElement }
-export { JsonRenderer }
-export { JsonRenderSpec }
 export { PartialWithoutId }
 export { RpcBroadcastOptions }
 export { RpcFunctionAgentOptions }
diff --git a/packages/kit/src/node/context.ts b/packages/kit/src/node/context.ts
@@ -3,6 +3,7 @@ import type { DevToolsNodeContext } from 'devframe/types'
 import type { ResolvedConfig, ViteDevServer } from 'vite'
 import type { DevToolsCommandsHost } from '../types/commands'
 import type { DevToolsDockHost } from '../types/docks'
+import type { JsonRenderer, JsonRenderSpec } from '../types/json-render'
 import type { DevToolsMessagesHost } from '../types/messages'
 import type { DevToolsTerminalHost } from '../types/terminals'
 import { createHostContext } from 'devframe/node'
@@ -15,15 +16,20 @@ import { DevToolsTerminalHost as TerminalsHostImpl } from './host-terminals'
 /**
  * Kit-augmented node context — extends devframe's framework-neutral
  * `DevToolsNodeContext` with the hub-level subsystems (`docks`,
- * `terminals`, `messages`, `commands`) that are owned by
- * `@vitejs/devtools-kit`. When kit hosts the devtool inside Vite
- * DevTools, also exposes the underlying Vite handles.
+ * `terminals`, `messages`, `commands`) and the `createJsonRenderer`
+ * factory, all owned by `@vitejs/devtools-kit`. When kit hosts the
+ * devtool inside Vite DevTools, also exposes the underlying Vite
+ * handles.
  */
 export interface KitNodeContext extends DevToolsNodeContext {
   docks: DevToolsDockHost
   terminals: DevToolsTerminalHost
   messages: DevToolsMessagesHost
   commands: DevToolsCommandsHost
+  /**
+   * Create a JsonRenderer handle for building json-render powered UIs.
+   */
+  createJsonRenderer: (spec: JsonRenderSpec) => JsonRenderer
   readonly viteConfig?: ResolvedConfig
   readonly viteServer?: ViteDevServer
 }
@@ -62,6 +68,28 @@ export async function createKitContext(options: CreateKitContextOptions): Promis
 
   await docks.init()
 
+  let jrCounter = 0
+  context.createJsonRenderer = (initialSpec: JsonRenderSpec): JsonRenderer => {
+    const stateKey = `devframe:json-render:${jrCounter++}`
+    const statePromise = context.rpc.sharedState.get(stateKey as any, {
+      initialValue: initialSpec as any,
+    })
+
+    return {
+      _stateKey: stateKey,
+      async updateSpec(spec) {
+        const state = await statePromise
+        state.mutate(() => spec as any)
+      },
+      async updateState(newState) {
+        const state = await statePromise
+        state.mutate((draft: any) => {
+          draft.state = { ...draft.state, ...newState }
+        })
+      },
+    }
+  }
+
   const debounceMs = options.mode === 'build' ? 0 : 10
 
   const docksSharedState = await context.rpc.sharedState.get('devframe:docks', { initialValue: [] })
diff --git a/packages/kit/src/types/docks.ts b/packages/kit/src/types/docks.ts
@@ -1,4 +1,5 @@
 import type { ConnectionMeta, EventEmitter } from 'devframe/types'
+import type { JsonRenderer } from './json-render'
 
 export interface DevToolsDockHost {
   readonly views: Map<string, DevToolsDockUserEntry>
@@ -160,7 +161,7 @@ export interface DevToolsViewBuiltin extends DevToolsDockEntryBase {
 export interface DevToolsViewJsonRender extends DevToolsDockEntryBase {
   type: 'json-render'
   /** JsonRenderer handle created by ctx.createJsonRenderer() */
-  ui: import('devframe/types').JsonRenderer
+  ui: JsonRenderer
 }
 
 export type DevToolsDockUserEntry = DevToolsViewIframe | DevToolsViewAction | DevToolsViewCustomRender | DevToolsViewLauncher | DevToolsViewJsonRender
diff --git a/packages/kit/src/types/index.ts b/packages/kit/src/types/index.ts
@@ -5,6 +5,7 @@ export type { CreateKitContextOptions, KitNodeContext } from '../node/context'
 export type { WhenContext, WhenExpression } from '../utils/when'
 export * from './commands'
 export * from './docks'
+export * from './json-render'
 export * from './messages'
 export * from './settings'
 export * from './terminals'
@@ -34,9 +35,6 @@ export type {
   EventEmitter,
   EventsMap,
   EventUnsubscribe,
-  JsonRenderElement,
-  JsonRenderer,
-  JsonRenderSpec,
   PartialWithoutId,
   RpcBroadcastOptions,
   RpcFunctionsHost,
diff --git a/packages/kit/src/types/json-render.ts b/packages/kit/src/types/json-render.ts
diff --git a/skills/vite-devtools-kit/SKILL.md b/skills/vite-devtools-kit/SKILL.md
@@ -32,7 +32,7 @@ A DevTools plugin extends a Vite plugin with a `devtools.setup(ctx)` hook. The c
 | `ctx.rpc.streaming` | devframe | Streaming channels — chunk-style server↔client data with cancellation, replay, Web Streams interop |
 | `ctx.views` | devframe | Host static files for UI (`hostStatic(base, distDir)`) |
 | `ctx.diagnostics` | devframe | Structured diagnostics host (logs-sdk) — register custom error codes |
-| `ctx.createJsonRenderer` | devframe | Create server-side JSON render specs for zero-client-code UIs |
+| `ctx.createJsonRenderer` | **kit** | Create server-side JSON render specs for zero-client-code UIs |
 | `ctx.viteConfig` | core | Resolved Vite configuration |
 | `ctx.viteServer` | core | Dev server instance (dev mode only) |
 | `ctx.mode` | devframe | `'dev'` or `'build'` |
