feat(hub): headless client host runtime that runs dock client scripts in the host page

Adopt the `@vitejs/devtools-kit` model at the framework level: instead of each
plugin shipping its own injection mechanism, the hub now ships a headless
client runtime — `createDevframeClientHost()` from `@devframes/hub/client` —
that a host page boots once. It assembles the full `DevframeClientContext`
(panel, docks, commands, when) from the hub's shared state, publishes it at
`__DEVFRAME_HUB_CLIENT_CONTEXT__`, and imports each dock entry's client script
(`action` / `custom-render` / iframe `clientScript`) into the page, handing it
a `DockClientScriptContext` with per-entry state, events, and a messages
client bridged over new `hub:messages:*` built-in RPCs.

The a11y inspector becomes the first consumer: its in-page agent is now the
a11y dock's client script (`a11yAgentBundlePath`, default-exported for the
loader), replacing the bespoke `a11yAgent()` Vite plugin and `A11Y_AGENT_PATH`
serving path introduced earlier in this branch. Both minimal hubs boot the
runtime from their existing client entry — the Vite host attaches the agent
via `/@fs/`, the Next host serves it through its catch-all route — and drop
the hand-placed script tags.

Created with the help of an agent.

Author: antfubot

AGENTS.md

@@ -4,7 +4,7 @@
 
 **`devframe`** is the framework-neutral container for one devtool integration, portable across viewers. Build a single tool (its RPC, its SPA, its diagnostics, its CLI/build/spa/embedded outputs) without caring how it'll be displayed. A devframe app runs standalone (CLI, static deploy, embedded SPA) just as well as it mounts inside a hub.
 
-**`@devframes/hub`** is the framework-neutral hub layer that sits on top of devframe and provides the multi-integration orchestration (docks, terminals, messages, commands). It does not ship UI — implementers (e.g. `@vitejs/devtools-kit`) provide their own UI on top of the hub's RPC + shared-state protocol. See `examples/minimal-vite-devframe-hub/` for a working ~120-line Vite host demonstrating the protocol end to end.
+**`@devframes/hub`** is the framework-neutral hub layer that sits on top of devframe and provides the multi-integration orchestration (docks, terminals, messages, commands). It does not ship UI — implementers (e.g. `@vitejs/devtools-kit`) provide their own UI on top of the hub's RPC + shared-state protocol. It does ship a **headless client runtime** (`createDevframeClientHost()` from `@devframes/hub/client`): booted in the host page, it assembles the shared `DevframeClientContext` (panel, docks, commands, when) and imports each dock entry's client script (`action` / `custom-render` / iframe `clientScript`) into that page — how a plugin like the a11y inspector runs code inside the page being inspected. See `examples/minimal-vite-devframe-hub/` for a working ~120-line Vite host demonstrating the protocol end to end.
 
 ## Stack & Structure
 

examples/minimal-next-devframe-hub/README.md

@@ -18,13 +18,14 @@ Open the printed URL. The dock on the left lists every mounted tool with its ico
 
 Selecting a tool loads its SPA in the stage. The bottom drawer mirrors the hub's **Commands**, **Messages**, and **Terminals** subsystems, plus a button that dispatches a command through `hub:commands:execute`.
 
-The A11y Inspector shows a live axe-core report of this hub's own page: the host serves the plugin's in-page agent bundle (`a11yAgentBundlePath`) same-origin through the catch-all route, and `app/layout.tsx` loads it into the page, so the docked panel and the agent share the origin their BroadcastChannel rides.
+The A11y Inspector shows a live axe-core report of this hub's own page: the host serves the plugin's in-page agent module (`a11yAgentBundlePath`) same-origin through the catch-all route and attaches it as the a11y dock's `clientScript`; the hub client runtime — `createDevframeClientHost()` booted in `app/page.tsx` — imports it into the page, so the docked panel and the agent share the origin their BroadcastChannel rides.
 
 ## What the example proves
 
 - `createHubContext()` boots a hub with no Vite-specific code path; a `DevframeHost` impl plugs Next specifics (static mounts, connection meta, storage, origin) in uniformly
 - `mountDevframe(ctx, def)` registers any `DevframeDefinition` as a dock and serves both its SPA and its `__connection.json`, so the embedded SPA connects straight back to the hub
 - The browser reads `devframe:docks` / `devframe:commands` shared state and dispatches commands over RPC — byte-for-byte the same protocol the Vite host speaks
+- `createDevframeClientHost()` boots the hub's framework-level client runtime in the host page: it publishes the shared client context and imports each dock's `clientScript` (here, the a11y agent) so plugins run code in the page being inspected
 
 ## Hosting built-in plugins in a bundler
 

examples/minimal-next-devframe-hub/src/client/app/layout.tsx

@@ -17,16 +17,7 @@ export default function RootLayout({ children }: { children: ReactNode }) {
       <head>
         <script dangerouslySetInnerHTML={{ __html: themeScript }} />
       </head>
-      <body>
-        {children}
-        {/*
-          Load the a11y inspector agent into the hub's own page so its docked
-          panel scans the host live. The hub serves this bundle same-origin
-          (see the agent mount in `devframe/minimal-next-devframe-hub.ts`); the
-          path mirrors the plugin's `A11Y_AGENT_PATH` constant.
-        */}
-        <script type="module" src="/__df-inject/inject.js" async />
-      </body>
+      <body>{children}</body>
     </html>
   )
 }

examples/minimal-next-devframe-hub/src/client/app/page.tsx

@@ -7,7 +7,7 @@ import type {
   DevframeMessageEntry,
   DevframeTerminalSession,
 } from '@devframes/hub/types'
-import { connectDevframe } from '@devframes/hub/client'
+import { connectDevframe, createDevframeClientHost } from '@devframes/hub/client'
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { iconClass } from './icons'
 
@@ -57,6 +57,11 @@ export default function Page() {
         rpcRef.current = rpc
         setStatus({ text: `Connected: backend=${rpc.connectionMeta.backend}`, kind: 'ready' })
 
+        // Boot the framework-level client host: it builds the shared client
+        // context and imports each dock's client script into this page — e.g.
+        // the a11y inspector's in-page agent, which then scans this hub live.
+        const clientHost = await createDevframeClientHost({ rpc })
+
         const docksState = await rpc.sharedState.get<DevframeDockEntry[]>(
           'devframe:docks',
           { initialValue: [] },
@@ -97,7 +102,10 @@ export default function Page() {
           void refreshTerminals()
         }, 2000)
 
-        cleanup = () => window.clearInterval(interval)
+        cleanup = () => {
+          window.clearInterval(interval)
+          clientHost.dispose()
+        }
       }
       catch (err) {
         if (!cancelled)

examples/minimal-next-devframe-hub/src/client/devframe/minimal-next-devframe-hub.ts

@@ -40,19 +40,35 @@ async function loadBuiltinPlugins(): Promise<DevframeDefinition[]> {
   return mods.map(mod => mod.default as DevframeDefinition)
 }
 
+/** URL base the a11y agent module is served under (same-origin, catch-all route). */
+const A11Y_AGENT_MOUNT_BASE = '/__df-a11y-agent/'
+
+interface A11yAgentMount {
+  /** The a11y devframe's dock id — the dock the client script attaches to. */
+  dockId: string
+  /** On-disk directory holding the built agent module. */
+  dir: string
+  /** Same-origin URL of the agent module, importable by the hub client runtime. */
+  importFrom: string
+}
+
 /**
- * Locate the a11y inspector's in-page **agent** bundle so the hub can serve it
- * same-origin (see `app/layout.tsx`, which loads it into the host page). Loaded
- * through the same bundler-ignored dynamic `import()` as the plugins, since the
- * package resolves its `dist` via `import.meta.url`. Returns the conventional
- * URL path and the on-disk directory to mount, or `null` if unavailable.
+ * Locate the a11y inspector's in-page **agent** module so the hub can serve it
+ * same-origin and attach it to the a11y dock as its client script — the hub
+ * client runtime (booted in `app/page.tsx`) imports it into the host page,
+ * where it scans this hub live. Loaded through the same bundler-ignored dynamic
+ * `import()` as the plugins, since the package resolves its `dist` via
+ * `import.meta.url`. Returns `null` if unavailable.
  */
-async function loadA11yAgentMount(): Promise<{ base: string, dir: string } | null> {
+async function loadA11yAgentMount(): Promise<A11yAgentMount | null> {
   try {
     const mod = await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/plugin-a11y')
-    const path = mod.A11Y_AGENT_PATH as string
     const bundle = mod.a11yAgentBundlePath as string
-    return { base: path.slice(0, path.lastIndexOf('/') + 1), dir: dirname(bundle) }
+    return {
+      dockId: (mod.default as DevframeDefinition).id,
+      dir: dirname(bundle),
+      importFrom: `${A11Y_AGENT_MOUNT_BASE}inject.js`,
+    }
   }
   catch {
     return null
@@ -197,17 +213,21 @@ export async function minimalNextDevframeHub(
     description: `Side-car WS on port ${port}. ${devframes.length} devframe(s) registered.`,
   })
 
-  for (const def of devframes) {
-    await mountDevframe(context, def)
-  }
-
-  // Serve the a11y inspector agent same-origin so the hub's own page (which
-  // loads it via app/layout.tsx) is scanned live by the docked panel. The
-  // catch-all route serves this mount; the panel iframe and the agent share
-  // the origin, so their BroadcastChannel connects.
+  // Serve the a11y inspector's in-page agent same-origin (via the catch-all
+  // route) and attach it to the a11y dock as its client script. The hub client
+  // runtime booted in `app/page.tsx` imports it into the host page, where it
+  // scans this hub live; the panel iframe shares the origin, so their
+  // BroadcastChannel connects.
   const a11yAgent = await loadA11yAgentMount()
   if (a11yAgent)
-    host.mountStatic(a11yAgent.base, a11yAgent.dir)
+    host.mountStatic(A11Y_AGENT_MOUNT_BASE, a11yAgent.dir)
+
+  for (const def of devframes) {
+    const clientScript = a11yAgent && def.id === a11yAgent.dockId
+      ? { importFrom: a11yAgent.importFrom }
+      : undefined
+    await mountDevframe(context, def, clientScript ? { dock: { clientScript } } : undefined)
+  }
 
   const started = await startHttpAndWs({
     context,

examples/minimal-vite-devframe-hub/README.md

@@ -18,14 +18,15 @@ Open the printed URL. The dock on the left lists every mounted tool with its ico
 
 Selecting a tool loads its SPA in the stage. The bottom drawer mirrors the hub's **Commands**, **Messages**, and **Terminals** subsystems, plus a button that dispatches a command through `hub:commands:execute`.
 
-The A11y Inspector shows a live axe-core report of this hub's own page: `a11yAgent()` (in `vite.config.ts`) serves the plugin's in-page agent and injects it into `index.html`, so the docked panel and the agent share the Vite origin their BroadcastChannel rides. Hover a violation to ring the offending element in the hub UI.
+The A11y Inspector shows a live axe-core report of this hub's own page. `vite.config.ts` attaches the plugin's in-page agent as the a11y dock's `clientScript` (served via `/@fs/`), and the hub client runtime — `createDevframeClientHost()` booted in `src/client/main.ts` — imports it into the host page. Panel and agent share the Vite origin their BroadcastChannel rides; hover a violation to ring the offending element in the hub UI.
 
 ## What the example proves
 
 - `createHubContext()` boots a hub with no Vite-specific code path; a `DevframeHost` impl plugs framework specifics (static mounts, connection meta, storage, origin) in uniformly
 - `mountDevframe(ctx, def)` registers any `DevframeDefinition` as a dock and serves both its SPA and its `__connection.json`, so the embedded SPA connects straight back to the hub
 - Real integrations work end to end through the mount path — the inspector lists every plugin's RPC functions live, terminals stream over the hub, and code-server launches an authenticated editor
 - The browser reads `devframe:docks` / `devframe:commands` shared state and dispatches commands over RPC — no hub classes imported on the client
+- `createDevframeClientHost()` boots the hub's framework-level client runtime in the host page: it publishes the shared client context and imports each dock's `clientScript` (here, the a11y agent) so plugins run code in the page being inspected
 
 ## Build your own
 
@@ -36,7 +37,7 @@ The dock UI is plain DOM in `src/client/`. To skin your own viewer, read the sam
 | File | Role |
 |---|---|
 | `src/minimal-vite-devframe-hub.ts` | The Vite host — hub context, static + connection-meta mounts, side-car WS |
-| `vite.config.ts` | Mounts the built-in plugins via the host's `devframes` option; adds `a11yAgent()` to load the a11y agent into the host page |
+| `vite.config.ts` | Mounts the built-in plugins via the host's `devframes` option; attaches the a11y agent as its dock's `clientScript` |
 | `src/client/main.ts` | The browser UI that consumes the hub protocol |
 | `src/client/icons.ts` | Offline Phosphor icons for the dock |
 | `index.html` | The UI shell |

examples/minimal-vite-devframe-hub/src/client/main.ts

@@ -4,7 +4,7 @@ import type {
   DevframeMessageEntry,
   DevframeTerminalSession,
 } from '@devframes/hub/types'
-import { connectDevframe } from '@devframes/hub/client'
+import { connectDevframe, createDevframeClientHost } from '@devframes/hub/client'
 import { iconClass } from './icons'
 import 'virtual:uno.css'
 import '@antfu/design/styles.css'
@@ -53,6 +53,12 @@ async function main() {
   const rpc = await connectDevframe({ baseURL: HUB_BASE })
   setStatus(`Connected · backend=${rpc.connectionMeta.backend}`, 'ready')
 
+  // Boot the framework-level client host: it builds the shared client context
+  // and imports each dock's client script into this page — e.g. the a11y
+  // inspector's in-page agent, which then scans this host live. The dock UI
+  // below still reads the same shared state directly.
+  await createDevframeClientHost({ rpc })
+
   // 1. Docks — read from `devframe:docks` shared state.
   const docks = await rpc.sharedState.get<DevframeDockEntry[]>(
     'devframe:docks',

examples/minimal-vite-devframe-hub/src/minimal-vite-devframe-hub.ts

@@ -1,4 +1,5 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
+import type { ClientScriptEntry } from '@devframes/hub/types'
 import type { DevframeDefinition, DevframeHost } from 'devframe/types'
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite'
 import { homedir } from 'node:os'
@@ -17,6 +18,12 @@ export interface MinimalViteDevframeHubOptions {
   port?: number
   /** Devframes to mount as docks. */
   devframes?: DevframeDefinition[]
+  /**
+   * Per-dock client scripts, keyed by devframe id. Attached to the mounted
+   * iframe dock so the hub client runtime imports them into the host page
+   * (e.g. the a11y inspector's in-page agent).
+   */
+  clientScripts?: Record<string, ClientScriptEntry>
 }
 
 // Minimal hub-local RPCs — used by the UI for read-side data. A more
@@ -142,7 +149,8 @@ export function minimalViteDevframeHub(options: MinimalViteDevframeHubOptions =
       })
 
       for (const def of options.devframes ?? []) {
-        await mountDevframe(context, def)
+        const clientScript = options.clientScripts?.[def.id]
+        await mountDevframe(context, def, clientScript ? { dock: { clientScript } } : undefined)
       }
 
       started = await startHttpAndWs({

examples/minimal-vite-devframe-hub/vite.config.ts

@@ -1,5 +1,4 @@
-import a11yDevframe from '@devframes/plugin-a11y'
-import { a11yAgent } from '@devframes/plugin-a11y/vite'
+import a11yDevframe, { a11yAgentBundlePath } from '@devframes/plugin-a11y'
 import codeServerDevframe from '@devframes/plugin-code-server'
 import gitDevframe from '@devframes/plugin-git'
 import inspectDevframe from '@devframes/plugin-inspect'
@@ -15,10 +14,6 @@ export default defineConfig({
   resolve: { alias },
   plugins: [
     UnoCSS(),
-    // Load the a11y inspector agent into this hub's own page so its docked
-    // panel scans the host live. The panel (mounted below) and this agent
-    // share the Vite origin, so their BroadcastChannel connects.
-    a11yAgent(),
     minimalViteDevframeHub({
       devframes: [
         demoDevframe,
@@ -31,6 +26,13 @@ export default defineConfig({
         inspectDevframe,
         a11yDevframe,
       ],
+      // Attach the a11y inspector's in-page agent as its dock's client script.
+      // The hub client runtime (booted in src/client/main.ts) imports it into
+      // this page so the docked panel scans the host live — no bespoke
+      // injection plugin needed. `/@fs/` lets Vite serve the built module.
+      clientScripts: {
+        [a11yDevframe.id]: { importFrom: `/@fs/${a11yAgentBundlePath}` },
+      },
     }),
   ],
 })