feat(hub): static hub builds with buildHub (#339)

Author: antfubot

alias.ts

@@ -48,6 +48,7 @@ export const alias = {
   'devframe/adapters/embedded': r('devframe/src/adapters/embedded.ts'),
   'devframe/initiate': r('devframe/src/adapters/initiate.ts'),
   'devframe/adapters/mcp': r('devframe/src/adapters/mcp/index.ts'),
+  '@devframes/hub/build': r('hub/src/node/build.ts'),
   '@devframes/hub/client': r('hub/src/client/index.ts'),
   '@devframes/hub/constants': r('hub/src/constants.ts'),
   '@devframes/hub/initiate': r('hub/src/node/initiate.ts'),

docs/content/1.guide/18.hub-initiate.md

@@ -99,6 +99,24 @@ A devframe's SPA and RPC client are byte-identical in both cases; only the envir
 | MCP | `<base>__mcp`, this devframe's tools | the hub-level aggregate |
 | Isolation | hard (own context, own transport) | cooperative (shared context) |
 
+## Static builds
+
+`buildHub()` from `@devframes/hub/build` is the hub counterpart of the [build adapter](/adapters/build): it bakes the whole hub into a directory any static file server can serve. Each devframe's SPA is copied to `<outDir>/<id>/` (absolute-path page scripts alongside at `<id>/__page-script/`), the UI slot's viewer and `embedded.js` next to them, and `__connection.json` (`backend: 'static'`) plus a shared [RPC dump](/adapters/build) at the hub base, with a snapshot of every shared-state key (docks, commands, renderer manifest) baked in - so `createDevframeClientRuntime()` and every panel boot from the dump with no live server.
+
+```ts
+import { buildHub } from '@devframes/hub/build'
+
+await buildHub({
+  outDir: 'dist/__devframes', // corresponds to `base` at serve time
+  devframes: [createA11yDevframe(), createMessagesDevframe()],
+  ui: createUi(),
+})
+```
+
+Browser-side tools keep working in full: a page script still loads into the host page and talks to its panel over the [in-page channel](/guide/in-page-channel) (the a11y inspector scans a production app exactly as it does in dev). Reads resolve from the baked dump (`static`/`snapshot` RPCs, shared-state snapshots); live writes (messages, command execution) have no server, so the browser clients degrade to local no-ops, and a panel's dock-activation deep links ride a same-origin `BroadcastChannel` instead of the RPC relay.
+
+A devframe whose value is inherently live declares `capabilities.build: false` and silently stays out of the build entirely - no dock, no SPA copy, no RPCs in the dump. The built-in terminals, code-server, and assets devframes declare it, so a hub mounting every built-in bakes only the tools that mean something statically. See the [buildHub options](/references/hub-api#buildhub-options) reference, and [`examples/a11y-messages-playground`](https://github.com/devframes/devframe/tree/main/examples/a11y-messages-playground) for a Vite host whose `vite build` output ships the hub.
+
 ## Bring your own context
 
 Host frameworks that assemble `createHubContext` + `ctx.install` themselves pass the context instead of a `devframes` list:

docs/content/2.adapters/4.build.md

@@ -28,3 +28,5 @@ await createBuild(myDevframe, {
 | `pretty` | `false` | Pretty-print dump JSON. |
 
 The RPC client runs read-only. For a custom URL base, build with relative asset paths (`vite.base: './'`).
+
+`buildHub()` from `@devframes/hub/build` produces the same kind of deploy for a whole hub: [Static builds](/guide/hub-initiate#static-builds).

docs/content/3.frameworks/1.vite.md

@@ -63,3 +63,5 @@ export default defineConfig({
 ```
 
 Pass `ui` to swap the hub UI provider, `ui: false` for headless (via `@devframes/vite/hub/client`'s `mountDevframeHubClient()`). Vite DevTools (`@vitejs/devtools-kit`) supports this natively; recommended once (`{ quiet: true }` to silence).
+
+`build: true` also bakes the hub into `vite build` output: [`buildHub`](/guide/hub-initiate#static-builds) writes the static hub subtree into `<outDir><base>` and the UI's `embedded.js` tag is injected into the built HTML, so the deployed app ships working devtools against a `static` backend (baked reads, no live server).

docs/content/6.errors/DF8005.md

@@ -30,4 +30,4 @@ initHub({
 
 ## Source
 
-- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `initHub()` emits this while mounting each devframe when the hub turned MCP off but the devframe requests one.
+- [`packages/hub/src/node/assemble.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/assemble.ts): `mountDevframes()` emits this while mounting each devframe when the hub turned MCP off but the devframe requests one.

docs/content/6.errors/DF8006.md

@@ -0,0 +1,33 @@
+---
+title: 'DF8006: Static Build Mount Escapes the Hub Base'
+description: 'A static hub build can only write mounts under its own base: "{urlBase}" escapes "{base}".'
+---
+
+## Message
+
+> A static hub build can only write mounts under its own base: "`{urlBase}`" escapes "`{base}`"
+
+## Cause
+
+`buildHub` maps every mounted URL base to a directory under its `outDir` (which corresponds to the hub `base` at serve time), so a mount whose base lies outside the hub base has no on-disk location in the output. This happens when a devframe is installed with an explicit base outside the hub base, e.g. `ctx.install(devframe, { base: '/elsewhere/' })` from `configure`.
+
+## Example
+
+```ts
+await buildHub({
+  outDir: 'dist/__devframes',
+  async configure(ctx) {
+    // ✗ Bad: `/tools/x/` is not under the `/__devframes/` hub base
+    await ctx.install(myDevframe, { base: '/tools/x/' })
+  },
+})
+```
+
+## Fix
+
+- Drop the `base` override so the devframe mounts at `<hub base><id>/`, or point it somewhere under the hub base.
+- Or move the hub `base` up (e.g. `base: '/'`) so it contains every mount.
+
+## Source
+
+- [`packages/hub/src/node/build.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/build.ts): `buildHub()`'s mount-to-disk mapping throws this for any mount base outside the hub base.

docs/content/8.references/3.events.md

@@ -66,6 +66,14 @@ A hub-aware RPC client reads or subscribes via `rpc.client.register(...)`; the [
 | `devframe:user-settings` | shared state | Persisted project-scope hub settings (`DevframeDocksUserSettings`). |
 | `devframe:terminals` | streaming channel | Live terminal output stream, keyed by session id. |
 
+### Same-origin `BroadcastChannel`s
+
+Used on a `static` backend, where no live server can relay a client's request to its sibling browsing contexts.
+
+| Name | Posted by | Carries |
+|---|---|---|
+| `devframe:docks:activate` | a panel iframe (e.g. the messages panel's activate actions) | The `{ dockId, params? }` activation; the client runtime in the host page switches the dock locally. |
+
 ## Core devframe events
 
 This map covers notifications only; request/response RPC endpoints (`devframe:rpc:server-state:*`, `devframe:streaming:subscribe`, `anonymous:devframe:auth`, …) are typed in `types/rpc-augments.ts`, not events.

docs/content/8.references/6.hub-api.md

@@ -84,6 +84,16 @@ What `initHub()` serves under its `base`: [The namespace](/guide/hub-initiate#th
 | `__client-imports.js` | dock client-script import map for hub UI providers |
 | `__mcp` | aggregate MCP endpoint over the tool registry (`mcp: 'auto'` default: mounted once agent tools exist) |
 
+## `buildHub` options
+
+The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/hub-initiate#static-builds). `devframes`, `services`, `rpcDeclarations`, `configure`, `ui`, `renderers`, `name`, `version`, `cwd`, and `getStorageDir` carry the same contracts as their `initHub` counterparts.
+
+| Option | Purpose |
+|---|---|
+| `outDir` | Output directory for the hub subtree; corresponds to `base` at serve time (build `base: '/__devframes/'` into `dist/__devframes`). |
+| `base` | Mount base baked into every absolute URL the build emits. Default `/__devframes/`. |
+| `pretty` | Pretty-print RPC dump JSON shards. Default `false` (minified). |
+
 ## Client runtime options
 
 The options of `createDevframeClientRuntime()`: [The client runtime](/guide/client-context#the-client-runtime).

examples/a11y-messages-playground/README.md

@@ -21,6 +21,22 @@ The `dev` script builds the workspace first (the a11y page-script bundle and bot
 devframe SPAs must exist), then starts Vite bound to `0.0.0.0`. Open the printed
 URL.
 
+## Production build
+
+```sh
+pnpm --filter a11y-messages-playground build    # vite build + buildHub -> dist/
+pnpm --filter a11y-messages-playground preview  # serve dist/ statically
+```
+
+`vite build` bakes the whole hub into `dist/__hub/` via `buildHub()` from
+`@devframes/hub/build`: both devframe SPAs, the a11y page-script bundle, a
+`backend: 'static'` connection meta, and the RPC dump (shared-state snapshots,
+the a11y config, the baked messages feed). Served from any static file server,
+the production page boots the client runtime against the static backend - the
+a11y inspector scans the built app over the in-page channel exactly as in dev,
+and the baked message's **Open a11y inspector** action still switches docks
+(riding a same-origin `BroadcastChannel` instead of the RPC relay).
+
 ## What you'll see
 
 The window is split in two:

examples/a11y-messages-playground/package.json

@@ -8,6 +8,7 @@
   "scripts": {
     "dev": "pnpm -C ../.. run build && vite --host",
     "build": "vite build",
+    "preview": "vite preview --host",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {