feat(hub): expose bakeHubStatic to bake an already-mounted context

Extract buildHub's post-mount baker into a public bakeHubStatic(ctx, opts)
so a host that assembles and mounts its own hub context (Vite DevTools'
kit-augmented context, devframes mounted from Vite plugins) reuses the
exact baker instead of reimplementing it and drifting out of sync.

- bakeHubStatic bakes an already-mounted DevframeHubContext; buildHub is now
  createHubContext + mountDevframes + bakeHubStatic.
- Enumerate mounted frames via ctx.frames (HubMountedFrame), populated in
  prepareDevframe, so an externally-mounted context can emit __index.json
  and per-frame __connection.json.
- Materialize statics from ctx.views.buildStaticDirs (each entry now carries
  its resolveFrom); route page scripts through views.hostStatic so they land
  there too.
- Add a clean opt-out so the baker can write beside an app's own build output.

Author: antfubot

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

@@ -126,3 +126,5 @@ const hub = initHub({ base: DEVFRAMES_HUB_BASE, context: ctx })
 ```
 
 It then serves only hub-level endpoints and transport; serve each mounted devframe's meta from `hub.connectionMeta()` yourself.
+
+The same context works for a static build: `bakeHubStatic(ctx, { outDir, base })` from `@devframes/hub/build` bakes an already-mounted context (`buildHub` is `createHubContext` + `mountDevframes` + `bakeHubStatic`). It reads `ctx.views.buildStaticDirs` for the statics to copy and `ctx.frames` for the frames to advertise, so a host that mounted its own context reuses the exact baker rather than reimplementing it. Pass `clean: false` to bake beside an app's own build output.

docs/content/6.errors/DF8006.md

@@ -9,7 +9,7 @@ description: 'A static hub build can only write mounts under its own base: "{url
 
 ## 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`.
+`bakeHubStatic` (which `buildHub` runs) 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
 
@@ -30,4 +30,4 @@ await buildHub({
 
 ## 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.
+- [`packages/hub/src/node/bake.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/bake.ts): `bakeHubStatic()`'s mount-to-disk mapping throws this for any mount base outside the hub base.

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

@@ -92,8 +92,13 @@ The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/
 |---|---|
 | `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/`. |
+| `clean` | Remove `outDir` before writing. Default `true`; set `false` to bake beside an app's own build output. |
 | `pretty` | Pretty-print RPC dump JSON shards. Default `false` (minified). |
 
+## `bakeHubStatic` options
+
+`bakeHubStatic(ctx, options)` from `@devframes/hub/build` is the second half of `buildHub`: it bakes an already-mounted `DevframeHubContext` a caller assembled itself (`createHubContext` + `ctx.install`, or a framework kit's own context), reading `ctx.views.buildStaticDirs` for the statics to copy and `ctx.frames` for the frames to advertise. `buildHub` is `createHubContext` + `mountDevframes` + `bakeHubStatic`. Options: `outDir`, `base`, `ui`, `renderers`, `name`, `version`, `pretty`, and `clean`, same contracts as their `buildHub` counterparts.
+
 ## Client runtime options
 
 The options of `createDevframeClientRuntime()`: [The client runtime](/guide/client-context#the-client-runtime).

packages/devframe/src/node/host-views.ts

@@ -7,7 +7,7 @@ export class DevframeViewHost implements DevframeViewHostType {
   /**
    * @internal
    */
-  public buildStaticDirs: { baseUrl: string, source: StaticAssetsSource }[] = []
+  public buildStaticDirs: { baseUrl: string, source: StaticAssetsSource, resolveFrom?: string | null }[] = []
 
   constructor(
     public readonly context: DevframeNodeContext,
@@ -30,7 +30,7 @@ export class DevframeViewHost implements DevframeViewHostType {
       throw diagnostics.DF0008({ distDir: resolved })
     }
 
-    this.buildStaticDirs.push({ baseUrl, source })
+    this.buildStaticDirs.push({ baseUrl, source, resolveFrom: defaultResolveFrom })
     this.context.host.mountStatic(baseUrl, resolved)
   }
 }

packages/devframe/src/types/views.ts

@@ -2,9 +2,15 @@ import type { StaticAssetsSource } from './remote-assets'
 
 export interface DevframeViewHost {
   /**
+   * Static mounts registered through {@link DevframeViewHost.hostStatic}, in
+   * registration order, each carrying the `resolveFrom` base it was mounted
+   * with so a build step can re-resolve a remote source identically. A static
+   * build that assembles the context itself (rather than serving it live)
+   * copies these into its output.
+   *
    * @internal
    */
-  buildStaticDirs: { baseUrl: string, source: StaticAssetsSource }[]
+  buildStaticDirs: { baseUrl: string, source: StaticAssetsSource, resolveFrom?: string | null }[]
   /**
    * Helper to host static files
    * - In `dev` mode, it will register middleware to `viteServer.middlewares` to host the static files

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

@@ -2,9 +2,12 @@ import type { DevframeDefinition, DevframeNodeContext } from 'devframe/types'
 import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { createH3DevframeHost } from 'devframe/internal'
 import { describe, expect, it } from 'vitest'
 import { HUB_EVENTS } from '../../events'
+import { bakeHubStatic } from '../bake'
 import { buildHub } from '../build'
+import { createHubContext } from '../context'
 
 function makeDist(html: string): string {
   const dir = mkdtempSync(join(tmpdir(), 'hub-build-dist-'))
@@ -111,6 +114,56 @@ describe('buildHub', () => {
     expect(docksRecord).not.toContain('Frame live')
   })
 
+  it('keeps sibling output when clean is false', async () => {
+    const outDir = join(mkdtempSync(join(tmpdir(), 'hub-build-out-')), 'hub')
+    const appFile = join(outDir, 'app.js')
+
+    await buildHub({
+      outDir,
+      base: '/__hub/',
+      cwd: mkdtempSync(join(tmpdir(), 'hub-build-cwd-')),
+      devframes: [makeFrame('alpha', { distDir: makeDist('<h1>alpha</h1>') })],
+    })
+    writeFileSync(appFile, 'app', 'utf-8')
+
+    await buildHub({
+      outDir,
+      base: '/__hub/',
+      clean: false,
+      cwd: mkdtempSync(join(tmpdir(), 'hub-build-cwd-')),
+      devframes: [makeFrame('beta', { distDir: makeDist('<h1>beta</h1>') })],
+    })
+
+    // The pre-existing sibling file survives, and the re-bake lands beside it.
+    expect(existsSync(appFile)).toBe(true)
+    expect(readFileSync(join(outDir, 'beta/index.html'), 'utf-8')).toContain('beta')
+  })
+
+  it('bakes an externally-mounted context via bakeHubStatic', async () => {
+    const outDir = join(mkdtempSync(join(tmpdir(), 'hub-bake-out-')), 'hub')
+    const cwd = mkdtempSync(join(tmpdir(), 'hub-bake-cwd-'))
+
+    // A host assembling the context itself: create + mount via `ctx.install`,
+    // then hand the already-mounted context to the baker.
+    const host = createH3DevframeHost({ origin: 'http://localhost', appName: 'devframes', workspaceRoot: cwd, mount: () => {} })
+    const ctx = await createHubContext({ cwd, workspaceRoot: cwd, mode: 'build', host })
+    await ctx.install(makeFrame('alpha', { distDir: makeDist('<h1>alpha</h1>') }), { base: '/__hub/alpha/' })
+
+    expect(ctx.frames.map(frame => frame.id)).toEqual(['alpha'])
+
+    await bakeHubStatic(ctx, { outDir, base: '/__hub/' })
+
+    // The baker copied the SPA from `ctx.views.buildStaticDirs`, wrote the
+    // index from `ctx.frames`, and emitted the per-frame meta + shared dump.
+    expect(readFileSync(join(outDir, 'alpha/index.html'), 'utf-8')).toContain('alpha')
+    const index = JSON.parse(readFileSync(join(outDir, '__index.json'), 'utf-8'))
+    expect(index.frames.map((frame: { id: string }) => frame.id)).toEqual(['alpha'])
+    const frameMeta = JSON.parse(readFileSync(join(outDir, 'alpha/__connection.json'), 'utf-8'))
+    expect(frameMeta.baseUrl).toBe('/__hub/__connection.json')
+    const manifest = JSON.parse(readFileSync(join(outDir, '__rpc-dump/index.json'), 'utf-8'))
+    expect(manifest['alpha:probe']).toMatchObject({ type: 'static' })
+  })
+
   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/__tests__/install-devframe.test.ts

@@ -12,15 +12,25 @@ type DeepPartial<T> = { [K in keyof T]?: DeepPartial<T[K]> }
 
 function createContext(): DevframeHubContext {
   const storageDir = mkdtempSync(join(tmpdir(), 'devframe-hub-install-'))
+  const mountStatic = vi.fn()
   const partial: DeepPartial<DevframeHubContext> = {
     host: {
-      mountStatic: vi.fn(),
+      mountStatic,
       resolveOrigin: () => 'http://localhost:5173',
       getStorageDir: () => storageDir,
     },
     views: {
-      hostStatic: () => {},
+      /**
+       * Mirror the real view host: forward to `host.mountStatic` so the tests
+       * assert the static mount the same way they did before page scripts and
+       * SPAs routed through `views.hostStatic`.
+       */
+      hostStatic: vi.fn((baseUrl: string, source: unknown) => {
+        mountStatic(baseUrl, source as string)
+      }),
+      buildStaticDirs: [],
     },
+    frames: [],
     /**
      * Minimal stub, since these tests drive dock/setup wiring, not the services
      * lifecycle (the demo devframe declares none).

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, skippedInStaticBuild } from './install-devframe'
+import { prepareDevframe } from './install-devframe'
 
 /** Reserved filenames directly under the hub base; a frame id can't shadow them. */
 const RESERVED_HUB_PATHS = [
@@ -100,13 +100,13 @@ export function renderClientImportsModule(ctx: DevframeHubContext): string {
 /**
  * Pass 1: mount each devframe under `<base><id>/` (SPA, meta, iframe dock)
  * and queue its declared services, guarding the id against reserved hub
- * filenames and route-pattern characters. Returns the deferred setup thunks.
+ * filenames and route-pattern characters. Returns the deferred setup thunks;
+ * each mounted frame is recorded on `ctx.frames`.
  */
 export async function mountDevframes(
   ctx: DevframeHubContext,
   devframes: HubDevframeEntry[],
   base: string,
-  frames: { id: string, base: string, title: string }[],
   hubMcpEnabled: boolean,
 ): Promise<(() => Promise<void>)[]> {
   const setups: (() => Promise<void>)[] = []
@@ -129,10 +129,6 @@ export async function mountDevframes(
     const run = await prepareDevframe(ctx, def, { base: frameBase, ...(dock ? { dock } : {}) })
     if (run)
       setups.push(run)
-    // 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
 }