feat(hub): add @devframes/hub/initiate — initHub, the headless hub behind one handler

initHub() serves the whole multi-devframe devtools surface through one
web-standard handler under a single namespace (default /__devframes/):
every mounted devframe shares one hub context (merged RPC registry,
shared state, docks/terminals/messages/commands), one WebSocket
transport, and one hub Auth; frames serve at <base><id>/ with per-frame
discovery pointing at the shared socket.

- reserved layout: __connection.json, __ws, __index.json,
  __client-imports.js, __mcp (aggregate over the shared registry),
  embedded.js; frame ids validated against it (DF8000)
- DevframeHubUi slot (pure data): ui.viewer owns the namespace root,
  ui.embedded serves the floating bootstrap at embedded.js — omitted,
  the hub stays fully headless and the root serves the index document
- assembly modes: declarative devframes list (+ configure(ctx)) or a
  pre-built context (DF8002 when both); key memoization against
  dev-reload leaks (DF8001)
- devframe: the Bun WS tier is promoted to the public
  devframe/rpc/transports/ws-bun subpath, createContextRpcServer is
  exported from devframe/node, and adapters/mcp exports mountMcpHttp —
  the primitives initHub composes
- mountDevframe now mounts a frame's connection meta before its SPA
  statics so route-ordered hosts (h3) resolve the exact meta route ahead
  of the static catch-all

Author: antfubot

alias.ts

@@ -7,6 +7,7 @@ const r = (path: string) => fileURLToPath(new URL(`./packages/${path}`, import.m
 const p = (path: string) => fileURLToPath(new URL(`./plugins/${path}`, import.meta.url))
 
 export const alias = {
+  'devframe/rpc/transports/ws-bun': r('devframe/src/rpc/transports/ws-bun.ts'),
   'devframe/rpc/transports/ws-server': r('devframe/src/rpc/transports/ws-server.ts'),
   'devframe/rpc/transports/ws-client': r('devframe/src/rpc/transports/ws-client.ts'),
   'devframe/rpc/client': r('devframe/src/rpc/client.ts'),
@@ -44,6 +45,7 @@ export const alias = {
   'devframe/adapters/mcp': r('devframe/src/adapters/mcp/index.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'),
   '@devframes/hub/node': r('hub/src/node/index.ts'),
   '@devframes/hub/types': r('hub/src/types/index.ts'),
   '@devframes/hub': r('hub/src/index.ts'),

docs/errors/DF8000.md

@@ -0,0 +1,31 @@
+---
+outline: deep
+---
+
+# DF8000: Devframe Id Collides With a Reserved Hub Path
+
+## Message
+
+> Devframe id "`{id}`" collides with a reserved hub path — it cannot be mounted directly under the hub base.
+
+## Cause
+
+`initHub` mounts every devframe at `<base><id>/`, directly under the hub base. The filenames that live at that same level — `__connection.json`, `__ws`, `__index.json`, `__client-imports.js`, `__mcp`, and `embedded.js` — are the hub protocol's own endpoints, so a devframe id equal to one of them would shadow the endpoint.
+
+## Example
+
+```ts
+import { initHub } from '@devframes/hub/initiate'
+
+initHub({
+  devframes: [defineDevframe({ id: '__mcp', /* … */ })], // ✗ throws DF8000
+})
+```
+
+## Fix
+
+Rename the devframe id, or mount it at a non-colliding path via `basePath` on the definition.
+
+## Source
+
+- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts) — `initHub` throws this while mounting the `devframes` list.

docs/errors/DF8001.md

@@ -0,0 +1,33 @@
+---
+outline: deep
+---
+
+# DF8001: Memoized Hub Instance Replaced
+
+## Message
+
+> initHub replaced the live hub instance memoized under key "`{key}`": its options changed since the previous call.
+
+## Cause
+
+`initHub` was called with a `key` that already maps to a live instance, but the option fingerprint differs from the memoized one's. Dev servers that re-evaluate modules on the fly (Next.js, Nitro, SvelteKit HMR) re-run `initHub` on every reload; the `key` memoization normally returns the live instance, but when the options genuinely changed the old instance — including its side-car WebSocket server — is closed and a fresh one starts.
+
+## Example
+
+```ts
+import { initHub } from '@devframes/hub/initiate'
+
+// First evaluation:
+initHub({ key: 'devtools', devframes: [git] })
+
+// A later reload with a different frame list replaces the live instance:
+initHub({ key: 'devtools', devframes: [git, terminals] }) // ⚠ DF8001
+```
+
+## Fix
+
+This is informational when you edited the options on purpose — the replacement is the intended behavior. If it fires without an intentional change, keep the options stable across reloads (module-level constants rather than values recomputed per evaluation), or give genuinely different hubs distinct keys.
+
+## Source
+
+- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts) — `initHub` warns this before closing and replacing a memoized instance whose options fingerprint changed.

docs/errors/DF8002.md

@@ -0,0 +1,36 @@
+---
+outline: deep
+---
+
+# DF8002: Both devframes and context Passed to initHub
+
+## Message
+
+> initHub received both `devframes` and `context` — the two assembly modes are mutually exclusive.
+
+## Cause
+
+`initHub` assembles a hub in one of two ways: **declaratively** (`devframes: [...]` — the instance creates the hub context with its own host and mounts each frame under `<base><id>/`), or **from a pre-built context** (`context: ctx` — your host already created the context and mounted the frames; the instance serves only the hub-level endpoints and transport). A `devframes` list cannot be mounted into a context whose host the instance doesn't own, so passing both is a contradiction.
+
+## Example
+
+```ts
+// ✗ Bad
+initHub({ devframes: [git], context: myCtx })
+
+// ✓ Good — declarative:
+initHub({ devframes: [git] })
+
+// ✓ Good — bring your own context:
+const ctx = await createHubContext({ host: myHost, cwd })
+await mountDevframe(ctx, git)
+initHub({ context: ctx })
+```
+
+## Fix
+
+Pick one mode. Use `configure(ctx)` on the declarative mode when you need post-mount registrations (docks, commands, terminals) on the instance-created context.
+
+## Source
+
+- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts) — `initHub` throws this during initialization when both options are present.

docs/errors/DF8003.md

@@ -0,0 +1,33 @@
+---
+outline: deep
+---
+
+# DF8003: connectionMeta() Before Hub Instance Ready
+
+## Message
+
+> connectionMeta() was called before initHub finished initializing.
+
+## Cause
+
+`initHub` is a synchronous factory that kicks off asynchronous initialization eagerly — creating the hub context, mounting every frame, and binding the WebSocket tier. `connectionMeta()` describes the WebSocket binding, which only exists once that initialization completes; calling it earlier has nothing correct to return.
+
+## Example
+
+```ts
+import { initHub } from '@devframes/hub/initiate'
+
+const hub = initHub({ devframes: [git] })
+hub.connectionMeta() // ✗ throws DF8003 — init is still in flight
+
+await hub.ready
+hub.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
+```
+
+## Fix
+
+Await `instance.ready` (or any request through `instance.handler` — it awaits readiness internally) before reading `connectionMeta()`.
+
+## Source
+
+- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts) — `initHub`'s `connectionMeta()` throws this while initialization is still pending.

knip.jsonc

@@ -81,13 +81,13 @@
         "src/recipes/{common-rpc-functions,interactive-auth,open-helpers}.ts",
         "src/rpc/{index,client,server}.ts",
         "src/rpc/dump/index.ts",
-        "src/rpc/transports/{ws-client,ws-server}.ts",
+        "src/rpc/transports/{ws-bun,ws-client,ws-server}.ts",
         "src/types/index.ts",
         "src/utils/*.ts"
       ]
     },
     "packages/hub": {
-      "entry": ["src/{index,constants}.ts", "src/{client,node,types}/index.ts"]
+      "entry": ["src/{index,constants}.ts", "src/{client,node,types}/index.ts", "src/node/initiate.ts"]
     },
     "packages/json-render": {
       // `src/node/index.ts` is already picked up via `tsdown.config.ts`

packages/devframe/package.json

@@ -40,6 +40,7 @@
     "./rpc/client": "./dist/rpc/client.mjs",
     "./rpc/dump": "./dist/rpc/dump.mjs",
     "./rpc/server": "./dist/rpc/server.mjs",
+    "./rpc/transports/ws-bun": "./dist/rpc/transports/ws-bun.mjs",
     "./rpc/transports/ws-client": "./dist/rpc/transports/ws-client.mjs",
     "./rpc/transports/ws-server": "./dist/rpc/transports/ws-server.mjs",
     "./types": "./dist/types/index.mjs",

packages/devframe/src/adapters/initiate.ts

@@ -4,8 +4,8 @@ import type { ConnectionMeta, DevframeNodeContext, DevframeNodeRpcSession, Devfr
 import type { IncomingMessage, Server as NodeHttpServer, ServerResponse } from 'node:http'
 import type { DevframeAuthHandler } from '../node/auth/handler'
 import type { StartedServer } from '../node/server'
+import type { BunWsTier } from '../rpc/transports/ws-bun'
 import type { DevframeDefinition, DevframeSetupInfo, DevframeWsOptions, McpRouteOptions } from '../types/devframe'
-import type { BunWsTier } from './initiate-bun'
 import process from 'node:process'
 import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3, toNodeHandler } from 'h3'
@@ -456,7 +456,7 @@ function instantiateDevframe(
     else {
       // Bun fetch-upgrade — same-origin upgrades completed through
       // `handler(request, server)`, hooks exposed via `websocket`.
-      const { attachBunWsTransport } = await import('./initiate-bun')
+      const { attachBunWsTransport } = await import('../rpc/transports/ws-bun')
       const { createContextRpcServer } = await import('../node/rpc-core')
       const core = createContextRpcServer({
         context: ctx,

packages/devframe/src/adapters/mcp/index.ts

@@ -23,3 +23,9 @@ export {
   type CreateMcpFetchHandlerOptions,
   type McpFetchHandler,
 } from './fetch'
+
+export {
+  type MountedMcpHttp,
+  mountMcpHttp,
+  type MountMcpHttpOptions,
+} from './http'

packages/devframe/src/node/index.ts

@@ -19,6 +19,10 @@ export * from './host-views'
 // lower-level read/probe/prune helpers stay internal to the connector.
 export { listLiveDevframeInstances, registerDevframeInstance } from './instance-registry'
 export type { DevframeInstanceRecord, DevframeInstanceRegistration } from './instance-registry'
+// The transport-agnostic RPC core is public so hosts that bind their own
+// transports (a Bun fetch-upgrade route, a custom relay) reuse the exact
+// session/auth wiring `startHttpAndWs` uses — see `createContextRpcServer`.
+export * from './rpc-core'
 export * from './rpc-shared-state'
 export * from './rpc-streaming'
 export * from './scope'