feat(hub): skip capabilities.build:false devframes in static builds

A devframe whose value is inherently live (terminals over PTY sessions,
the code-server process proxy, the assets manager) declares
capabilities.build: false; buildHub now honors it the way createBuild
does: the devframe is never mounted, so no dock, no SPA copy, no frame in
__index.json, and none of its RPCs join the static dump. DF8007 logs each
skip so a missing dock stays traceable. The terminals and code-server
plugins declare the capability (assets already did).

Author: antfubot

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

@@ -113,7 +113,9 @@ await buildHub({
 })
 ```
 
-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, terminals, 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. 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.
+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 stays out of the build entirely - no dock, no SPA copy, no RPCs in the dump (`DF8007` logs each skip). 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
 

docs/content/6.errors/DF8007.md

@@ -0,0 +1,34 @@
+---
+title: 'DF8007: Devframe Skipped by the Static Hub Build'
+description: 'Devframe "{name}" ({id}) declares `capabilities.build: false`, so the static hub build skips it.'
+---
+
+## Message
+
+> Devframe "`{name}`" (`{id}`) declares `capabilities.build: false`, so the static hub build skips it.
+
+## Cause
+
+A devframe whose value is inherently live - a terminal over PTY sessions, a proxy in front of a running process - declares `capabilities.build: false` on its definition. `buildHub` honors the declaration by leaving the devframe out of the static output entirely: its SPA is not copied, its dock is not registered (so it never appears in the baked `devframe:docks` shared state or `__index.json`), and its `setup(ctx)` never runs, so none of its RPCs join the static dump. This log line records each skip so a missing dock in a static build is traceable.
+
+The built-in terminals, code-server, and assets devframes declare this capability.
+
+## Example
+
+```ts
+await buildHub({
+  outDir: 'dist/__devframes',
+  devframes: [
+    createA11yDevframe(), // baked
+    createTerminalsDevframe(), // `capabilities.build: false` -> DF8007, skipped
+  ],
+})
+```
+
+## Fix
+
+Nothing to fix - this is the declared behavior. If the tool does have a meaningful baked form (its panels read from `static`/`snapshot` RPCs), drop `capabilities.build: false` from the definition so the static build includes it.
+
+## Source
+
+- [`packages/hub/src/node/install-devframe.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/install-devframe.ts): `prepareDevframe()` logs this and skips the mount for a `capabilities.build: false` definition in a `mode: 'build'` hub context.

examples/hub-vite-minimal/README.md

@@ -26,4 +26,4 @@ pnpm --filter hub-vite-minimal build    # vite build + the baked hub -> dist/
 pnpm --filter hub-vite-minimal preview  # serve dist/ statically
 ```
 
-`build: true` on `viteDevframeHub` bakes the hub into `dist/__devframes/` and injects the `embedded.js` tag into the built HTML, so the production bundle ships the same docks against a `static` backend: the floating dock and standalone viewer boot from the baked RPC dump (each panel's snapshot reads, e.g. the Open Graph report of `defaultUrl`), while live-server tools (terminals, code-server) render their panels without a backing process.
+`build: true` on `viteDevframeHub` bakes the hub into `dist/__devframes/` and injects the `embedded.js` tag into the built HTML, so the production bundle ships the docks against a `static` backend: the floating dock and standalone viewer boot from the baked RPC dump (each panel's snapshot reads, e.g. the Open Graph report of `defaultUrl`). Inherently-live tools (terminals, code-server, assets) declare `capabilities.build: false` and stay out of the static output entirely.

packages/devframe/src/types/devframe.ts

@@ -389,10 +389,12 @@ export interface DevframeDefinition {
    * act on a `false` before doing any work:
    *
    * - `build: false`: `createCac` skips registering the `build` subcommand,
-   *   and `createBuild` refuses (throws `DF0042`) unless `{ force: true }`.
-   *   Useful for a devframe whose value is inherently live (e.g. it manages
-   *   real files on disk), so a static export would only ever produce a
-   *   broken, write-less shell of the tool.
+   *   `createBuild` refuses (throws `DF0042`) unless `{ force: true }`, and
+   *   a hub static build (`buildHub`) skips the devframe entirely - no dock,
+   *   no SPA copy, no RPCs in the dump (`DF8007` logs the skip). Useful for
+   *   a devframe whose value is inherently live (e.g. it manages real files
+   *   on disk), so a static export would only ever produce a broken,
+   *   write-less shell of the tool.
    * - `dev: false`: `createDevServer` refuses (throws `DF0058`) unless
    *   `{ force: true }`. Useful for a devframe that only makes sense as a
    *   static export (e.g. a report generator with nothing to serve live).

packages/hub/src/node/__tests__/build.test.ts

@@ -82,6 +82,35 @@ describe('buildHub', () => {
     expect(readFileSync(join(outDir, '__client-imports.js'), 'utf-8')).toContain('/__hub/alpha/__page-script/inject.js')
   })
 
+  it('skips a devframe declaring capabilities.build: false', async () => {
+    const outDir = join(mkdtempSync(join(tmpdir(), 'hub-build-out-')), 'hub')
+    const live: DevframeDefinition = {
+      ...makeFrame('live', { distDir: makeDist('<h1>live</h1>') }),
+      capabilities: { build: false },
+    }
+
+    await buildHub({
+      outDir,
+      base: '/__hub/',
+      cwd: mkdtempSync(join(tmpdir(), 'hub-build-cwd-')),
+      devframes: [makeFrame('alpha', { distDir: makeDist('<h1>alpha</h1>') }), live],
+    })
+
+    // Nothing of the skipped devframe lands in the output: no SPA, no frame
+    // entry, no RPCs in the dump, no dock in the baked shared state.
+    expect(existsSync(join(outDir, 'live'))).toBe(false)
+    const index = JSON.parse(readFileSync(join(outDir, '__index.json'), 'utf-8'))
+    expect(index.frames.map((frame: { id: string }) => frame.id)).toEqual(['alpha'])
+    const manifest = JSON.parse(readFileSync(join(outDir, '__rpc-dump/index.json'), 'utf-8'))
+    expect(manifest['live:probe']).toBeUndefined()
+    const stateEntry = manifest['devframe:rpc:server-state:get']
+    const records = (Object.values(stateEntry.records) as string[])
+      .map(path => readFileSync(join(outDir, path), 'utf-8'))
+    const docksRecord = records.find(text => text.includes(HUB_EVENTS.sharedState.docks))
+    expect(docksRecord).toContain('alpha')
+    expect(docksRecord).not.toContain('Frame live')
+  })
+
   it('rejects a mount base outside the hub base', async () => {
     const outDir = join(mkdtempSync(join(tmpdir(), 'hub-build-out-')), 'hub')
     await expect(buildHub({

packages/hub/src/node/assemble.ts

@@ -8,7 +8,7 @@ import { resolve } from 'pathe'
 import { joinURL, withTrailingSlash } from 'ufo'
 import { resolveClientModuleSpecifier } from '../client-modules'
 import { diagnostics } from './diagnostics'
-import { prepareDevframe } from './install-devframe'
+import { prepareDevframe, skippedInStaticBuild } from './install-devframe'
 
 /** Reserved filenames directly under the hub base; a frame id can't shadow them. */
 const RESERVED_HUB_PATHS = [
@@ -128,7 +128,10 @@ export async function mountDevframes(
     const run = await prepareDevframe(ctx, def, { base: frameBase, ...(dock ? { dock } : {}) })
     if (run)
       setups.push(run)
-    frames.push({ id: def.id, base: frameBase, title: def.name })
+    // A devframe skipped by the static build serves nothing, so it never
+    // joins the `__index.json` frame list either.
+    if (!skippedInStaticBuild(ctx, def))
+      frames.push({ id: def.id, base: frameBase, title: def.name })
   }
   return setups
 }

packages/hub/src/node/diagnostics.ts

@@ -38,6 +38,10 @@ export const diagnostics = defineDiagnostics({
       why: (p: { urlBase: string, base: string }) => `A static hub build can only write mounts under its own base: "${p.urlBase}" escapes "${p.base}".`,
       fix: 'buildHub maps each mount base to a directory under its `outDir`, so every mount must live under the hub base. Drop the `basePath` override (or the `ctx.install` base) that points outside it, or move the hub `base` up so it contains the mount.',
     },
+    DF8007: {
+      why: (p: { id: string, name: string }) => `Devframe "${p.name}" (${p.id}) declares \`capabilities.build: false\`, so the static hub build skips it.`,
+      fix: 'This is the declared behavior for a tool whose value is inherently live (a terminal, a process proxy): its dock, SPA, and RPCs stay out of the static output. Drop `capabilities.build: false` from the definition if the tool does have a meaningful baked form.',
+    },
     DF8100: {
       why: (p: { id: string }) => `Dock with id "${p.id}" is already registered`,
       fix: 'Use the `force` parameter to overwrite an existing registration.',

packages/hub/src/node/install-devframe.ts

@@ -109,11 +109,25 @@ async function serveDevframeAssets(
   ctx.views.hostStatic(base, typeof clientAssets === 'string' ? resolve(clientAssets) : clientAssets, d.importMetaUrl)
 }
 
+/**
+ * Whether a devframe stays out of a static hub build: `capabilities.build:
+ * false` declares its value inherently live (a terminal, a process proxy),
+ * so `buildHub` never mounts it, registers its dock, or bakes its RPCs.
+ */
+export function skippedInStaticBuild(ctx: DevframeHubContext, d: DevframeDefinition): boolean {
+  return ctx.mode === 'build' && d.capabilities?.build === false
+}
+
 export async function prepareDevframe(
   ctx: DevframeHubContext,
   d: DevframeDefinition,
   options: InstallDevframeOptions = {},
 ): Promise<(() => Promise<void>) | null> {
+  if (skippedInStaticBuild(ctx, d)) {
+    diagnostics.DF8007({ id: d.id, name: d.name }, { method: 'log' })
+    return null
+  }
+
   const strategy = d.duplicationStrategy ?? 'warn'
   const isDuplicate = ctx.docks.views.has(d.id)
 

plugins/code-server/src/index.ts

@@ -49,6 +49,12 @@ export function createCodeServerDevframe(options: CodeServerOptions = {}): Devfr
     homepage: pkg.homepage,
     description: pkg.description,
     icon: 'ph:code-duotone',
+    /**
+     * The whole surface proxies a live `code-server` process, so a static
+     * build would only produce a dead shell of the tool: `createBuild`
+     * refuses and a hub static build skips this dock.
+     */
+    capabilities: { build: false },
     /**
      * Leave undefined so `resolveBasePath` picks `/` standalone and
      * `/__<id>/` when hosted. Authors override via `options.basePath`.

plugins/terminals/src/index.ts

@@ -59,6 +59,12 @@ export function createTerminalsDevframe(options: TerminalsOptions = {}): Devfram
     homepage: pkg.homepage,
     description: pkg.description,
     icon: 'ph:terminal-window-duotone',
+    /**
+     * Terminals are inherently live (PTY sessions over the streaming
+     * channel), so a static build would only produce a dead shell of the
+     * tool: `createBuild` refuses and a hub static build skips this dock.
+     */
+    capabilities: { build: false },
     /**
      * Leave undefined so `resolveBasePath` picks `/` standalone and
      * `/__<id>/` when hosted. Authors override via `options.basePath`.