feat(initiate)!: require base and expose it on the instance

Both initDevframe and initHub now take a required `base` option (the
mount path is explicit at the call site — pass DEVFRAMES_HUB_BASE for the
hub's conventional /__devframes/) and echo the normalized value back as
`instance.base`, so route guards and middleware reference it instead of
repeating the magic string.

BREAKING CHANGE: `base` is no longer optional on initDevframe/initHub.

Author: antfubot

docs/adapters/initiate.md

@@ -1,17 +1,17 @@
 # Initiate (standard middleware)
 
-Serve a devframe from inside any app that can mount a catch-all route: `initDevframe(def)` returns a live instance whose `.handler` — a web-standard `(request: Request) => Promise<Response>` — carries the whole surface (the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the auth gate, and the optional MCP route) under one mount base.
+Serve a devframe from inside any app that can mount a catch-all route: `initDevframe(def, { base })` returns a live instance whose `.handler` — a web-standard `(request: Request) => Promise<Response>` — carries the whole surface (the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the auth gate, and the optional MCP route) under one mount base.
 
 ```ts
 import { initDevframe } from 'devframe/initiate'
 import myDevframe from './devframe'
 
-const devtools = initDevframe(myDevframe, { key: 'my-tool' })
-// devtools.handler, devtools.nodeMiddleware, devtools.websocket,
+const devtools = initDevframe(myDevframe, { base: '/__my-tool/', key: 'my-tool' })
+// devtools.base, devtools.handler, devtools.nodeMiddleware, devtools.websocket,
 // devtools.ready, devtools.context, devtools.connectionMeta(), devtools.close()
 ```
 
-The factory is synchronous and initializes eagerly; `handler`/`nodeMiddleware` await readiness internally, so hosts never race the boot. The default base is the hosted rule — `def.basePath` or `/__<id>/`.
+`base` is required, so the mount path is explicit at the call site — pass the conventional `resolveBasePath(def, 'hosted')` (i.e. `def.basePath ?? /__<id>/`) if you don't want to pick one. The instance echoes the normalized value back as `devtools.base`, so route guards and middleware reference it instead of repeating the string. The factory is synchronous and initializes eagerly; `handler`/`nodeMiddleware` await readiness internally, so hosts never race the boot.
 
 ## Mount the handler
 
@@ -29,6 +29,7 @@ export default defineConfig({
     apply: 'serve',
     configureServer(server) {
       const devtools = initDevframe(myDevframe, {
+        base: '/__my-tool/',
         key: 'my-tool',
         server: server.httpServer ?? undefined,
       })
@@ -65,7 +66,7 @@ import myDevframe from '@/devframe'
 export const runtime = 'nodejs'
 export const dynamic = 'force-dynamic'
 
-const devtools = initDevframe(myDevframe, { key: 'my-tool' })
+const devtools = initDevframe(myDevframe, { base: '/__my-tool/', key: 'my-tool' })
 export const GET = devtools.handler
 ```
 
@@ -75,7 +76,8 @@ import { devtools } from '../devtools'
 
 export default defineEventHandler((event) => {
   const { pathname } = new URL(toWebRequest(event).url)
-  if (pathname === '/__my-tool' || pathname.startsWith('/__my-tool/'))
+  // `devtools.base` is the normalized mount base — no repeated string.
+  if (pathname.startsWith(devtools.base) || pathname === devtools.base.slice(0, -1))
     return devtools.handler(toWebRequest(event))
 })
 ```
@@ -85,7 +87,7 @@ export default defineEventHandler((event) => {
 import myDevframe from '$lib/devframe'
 import { initDevframe } from 'devframe/initiate'
 
-const devtools = initDevframe(myDevframe, { key: 'my-tool' })
+const devtools = initDevframe(myDevframe, { base: '/__my-tool/', key: 'my-tool' })
 export const GET = ({ request }) => devtools.handler(request)
 ```
 

docs/errors/DF0053.md

@@ -18,10 +18,10 @@ outline: deep
 import { initDevframe } from 'devframe/initiate'
 
 // First evaluation:
-initDevframe(def, { key: 'devtools', ws: { port: 7811 } })
+initDevframe(def, { base: '/__my-tool/', key: 'devtools', ws: { port: 7811 } })
 
 // A later reload with a different port replaces the live instance:
-initDevframe(def, { key: 'devtools', ws: { port: 7812 } }) // ⚠ DF0053
+initDevframe(def, { base: '/__my-tool/', key: 'devtools', ws: { port: 7812 } }) // ⚠ DF0053
 ```
 
 ## Fix

docs/errors/DF0054.md

@@ -17,7 +17,7 @@ outline: deep
 ```ts
 import { initDevframe } from 'devframe/initiate'
 
-const devtools = initDevframe(def)
+const devtools = initDevframe(def, { base: '/__my-tool/' })
 devtools.connectionMeta() // ✗ throws DF0054 — init is still in flight
 
 await devtools.ready

docs/errors/DF8000.md

@@ -18,6 +18,7 @@ outline: deep
 import { initHub } from '@devframes/hub/initiate'
 
 initHub({
+  base: '/__devframes/',
   devframes: [defineDevframe({ id: '__mcp', /* … */ })], // ✗ throws DF8000
 })
 ```

docs/errors/DF8001.md

@@ -18,10 +18,10 @@ outline: deep
 import { initHub } from '@devframes/hub/initiate'
 
 // First evaluation:
-initHub({ key: 'devtools', devframes: [git] })
+initHub({ base: '/__devframes/', key: 'devtools', devframes: [git] })
 
 // A later reload with a different frame list replaces the live instance:
-initHub({ key: 'devtools', devframes: [git, terminals] }) // ⚠ DF8001
+initHub({ base: '/__devframes/', key: 'devtools', devframes: [git, terminals] }) // ⚠ DF8001
 ```
 
 ## Fix

docs/errors/DF8002.md

@@ -16,15 +16,15 @@ outline: deep
 
 ```ts
 // ✗ Bad
-initHub({ devframes: [git], context: myCtx })
+initHub({ base: '/__devframes/', devframes: [git], context: myCtx })
 
 // ✓ Good — declarative:
-initHub({ devframes: [git] })
+initHub({ base: '/__devframes/', devframes: [git] })
 
 // ✓ Good — bring your own context:
 const ctx = await createHubContext({ host: myHost, cwd })
 await mountDevframe(ctx, git)
-initHub({ context: ctx })
+initHub({ base: '/__devframes/', context: ctx })
 ```
 
 ## Fix

docs/errors/DF8003.md

@@ -17,7 +17,7 @@ outline: deep
 ```ts
 import { initHub } from '@devframes/hub/initiate'
 
-const hub = initHub({ devframes: [git] })
+const hub = initHub({ base: '/__devframes/', devframes: [git] })
 hub.connectionMeta() // ✗ throws DF8003 — init is still in flight
 
 await hub.ready

docs/guide/hub-initiate.md

@@ -1,15 +1,16 @@
 # Serve a Hub Anywhere
 
-`initHub()` from `@devframes/hub/initiate` puts a whole multi-devframe devtools installation behind one web-standard handler: mount it on a single catch-all route and every frame, the shared RPC socket, the single auth gate, discovery, and the optional UI are live under one namespace (default `/__devframes/`).
+`initHub()` from `@devframes/hub/initiate` puts a whole multi-devframe devtools installation behind one web-standard handler: mount it on a single catch-all route and every frame, the shared RPC socket, the single auth gate, discovery, and the optional UI are live under one namespace.
 
 ```ts
 import { createUi } from '@devframes/hub-ui'
-import { initHub } from '@devframes/hub/initiate'
+import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
 import { createInspectDevframe } from '@devframes/plugin-inspect'
 import { createTerminalsDevframe } from '@devframes/plugin-terminals'
 
 export const hub = initHub({
   key: 'devtools',
+  base: DEVFRAMES_HUB_BASE, // required — the conventional `/__devframes/`
   devframes: [createInspectDevframe(), createTerminalsDevframe()],
   ui: createUi(),
   configure(ctx) {
@@ -18,7 +19,7 @@ export const hub = initHub({
 })
 ```
 
-Every mounted devframe runs its `setup()` against the **shared hub context**: one merged RPC registry (frames can call each other's functions), one shared-state store, one WebSocket transport, one Auth. The instance mirrors `initDevframe`'s surface — `handler`, `nodeMiddleware`, `websocket` (Bun), `ready`, `context`, `connectionMeta()`, `close()` — and the same mount snippets apply with the base swapped to `/__devframes/`; see [the initiate adapter](../adapters/initiate#mount-the-handler).
+`base` is required so the mount path is explicit; pass the exported `DEVFRAMES_HUB_BASE` for the conventional `/__devframes/`. The instance echoes the normalized value back as `hub.base`, so route guards and middleware reference it instead of repeating the string. Every mounted devframe runs its `setup()` against the **shared hub context**: one merged RPC registry (frames can call each other's functions), one shared-state store, one WebSocket transport, one Auth. The instance mirrors `initDevframe`'s surface — `base`, `handler`, `nodeMiddleware`, `websocket` (Bun), `ready`, `context`, `connectionMeta()`, `close()` — and the same mount snippets apply; see [the initiate adapter](../adapters/initiate#mount-the-handler).
 
 ## The namespace
 
@@ -72,7 +73,7 @@ A devframe's SPA and RPC client code are byte-identical in both cases — that i
 Hosts that assemble `createHubContext` + `mountDevframe` themselves (with their own `DevframeHost` serving the frames) pass the finished context instead of a `devframes` list:
 
 ```ts
-const hub = initHub({ context: ctx })
+const hub = initHub({ base: DEVFRAMES_HUB_BASE, context: ctx })
 ```
 
-The instance then serves the hub-level endpoints and transport only; serve each frame's meta from `hub.connectionMeta()` yourself. The two reference examples — `examples/vite-devframe-hub` and `examples/next-devframe-hub` — use the declarative mode with their own hand-built viewer UIs, and `examples/nitro-devframe-hub` / `examples/hono-devframe-hub` show the minimal `createUi()` mounts (the Hono one on Node and Bun).
+The instance then serves the hub-level endpoints and transport only; serve each frame's meta from `hub.connectionMeta()` yourself. The two reference examples — `examples/hub-vite` and `examples/hub-next` — use the declarative mode with their own hand-built viewer UIs, while the `hub-*-minimal` family (`hub-vite-minimal`, `hub-next-minimal`, `hub-nitro-minimal`, `hub-hono-minimal`, `hub-rsbuild-minimal`) shows the minimal `createUi()` mount across frameworks (the Hono one on Node and Bun).

packages/devframe/src/adapters/__tests__/initiate.test.ts

@@ -43,20 +43,15 @@ function defineTestDef(id: string) {
 
 describe('adapters/handler', () => {
   it('connectionMeta() before ready throws DF0054', () => {
-    const devtools = initDevframe(defineTestDef('handler-early'), { auth: false })
+    const devtools = initDevframe(defineTestDef('handler-early'), { base: '/__handler-early/', auth: false })
     expect(() => devtools.connectionMeta()).toThrow(/DF0054|finished initializing/)
     return devtools.close()
   })
 
   it('default tier: eager side-car — SPA, meta, and WS RPC through fetch', async () => {
     const distDir = makeTmpDist()
     const wsPort = await getPort({ port: 18110, host: '127.0.0.1' })
-    const devtools = initDevframe(defineTestDef('handler-test'), {
-      auth: false,
-      distDir,
-      host: '127.0.0.1',
-      ws: { port: wsPort },
-    })
+    const devtools = initDevframe(defineTestDef('handler-test'), { base: '/__handler-test/', auth: false, distDir, host: '127.0.0.1', ws: { port: wsPort } })
 
     try {
       await devtools.ready
@@ -102,10 +97,7 @@ describe('adapters/handler', () => {
   it('gates by default: untrusted calls reject until the OTP exchange', async () => {
     const wsPort = await getPort({ port: 18120, host: '127.0.0.1' })
     const spy = vi.spyOn(console, 'log').mockImplementation(() => {})
-    const devtools = initDevframe(defineTestDef('handler-auth'), {
-      host: '127.0.0.1',
-      ws: { port: wsPort },
-    })
+    const devtools = initDevframe(defineTestDef('handler-auth'), { base: '/__handler-auth/', host: '127.0.0.1', ws: { port: wsPort } })
 
     try {
       await devtools.ready
@@ -150,11 +142,7 @@ describe('adapters/handler', () => {
         res.end('host app')
       })
     })
-    devtoolsRef = initDevframe(defineTestDef('handler-shared'), {
-      auth: false,
-      distDir,
-      server,
-    })
+    devtoolsRef = initDevframe(defineTestDef('handler-shared'), { base: '/__handler-shared/', auth: false, distDir, server })
     await new Promise<void>(resolve => server.listen(port, host, resolve))
 
     try {
@@ -212,9 +200,7 @@ describe('adapters/handler', () => {
   })
 
   it('ws.url tier: advertises the external endpoint verbatim, owns no transport', async () => {
-    const devtools = initDevframe(defineTestDef('handler-remote'), {
-      ws: { url: 'wss://devtools.example.com/relay/__ws' },
-    })
+    const devtools = initDevframe(defineTestDef('handler-remote'), { base: '/__handler-remote/', ws: { url: 'wss://devtools.example.com/relay/__ws' } })
 
     try {
       await devtools.ready
@@ -235,11 +221,7 @@ describe('adapters/handler', () => {
     const server = createServer((req, res) => {
       devtoolsRef.nodeMiddleware(req, res)
     })
-    devtoolsRef = initDevframe(defineTestDef('handler-tunnel'), {
-      auth: false,
-      server,
-      ws: { url: 'wss://devtools.example.com/relay/__ws' },
-    })
+    devtoolsRef = initDevframe(defineTestDef('handler-tunnel'), { base: '/__handler-tunnel/', auth: false, server, ws: { url: 'wss://devtools.example.com/relay/__ws' } })
     await new Promise<void>(resolve => server.listen(port, host, resolve))
 
     try {
@@ -260,11 +242,7 @@ describe('adapters/handler', () => {
 
   it('mcp: mounts <base>__mcp and advertises it in the meta', async () => {
     const wsPort = await getPort({ port: 18140, host: '127.0.0.1' })
-    const devtools = initDevframe(defineTestDef('handler-mcp'), {
-      auth: false,
-      mcp: true,
-      ws: { port: wsPort },
-    })
+    const devtools = initDevframe(defineTestDef('handler-mcp'), { base: '/__handler-mcp/', auth: false, mcp: true, ws: { port: wsPort } })
 
     try {
       await devtools.ready
@@ -284,15 +262,15 @@ describe('adapters/handler', () => {
   it('key memoization: re-runs return the live instance; changed options replace it', async () => {
     const def = defineTestDef('handler-memo')
     const wsPort = await getPort({ port: 18150, host: '127.0.0.1' })
-    const a = initDevframe(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort } })
-    const b = initDevframe(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort } })
+    const a = initDevframe(def, { base: '/__handler-memo/', auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort } })
+    const b = initDevframe(def, { base: '/__handler-memo/', auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort } })
     expect(b).toBe(a)
 
     try {
       await a.ready
       const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
       const wsPort2 = await getPort({ port: 18151, host: '127.0.0.1' })
-      const c = initDevframe(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort2 } })
+      const c = initDevframe(def, { base: '/__handler-memo/', auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort2 } })
       try {
         expect(c).not.toBe(a)
         expect(String(warn.mock.calls)).toContain('DF0053')
@@ -323,10 +301,7 @@ describe('adapters/handler', () => {
 
   it('bridge mode: without a distDir only meta + WS are served', async () => {
     const wsPort = await getPort({ port: 18160, host: '127.0.0.1' })
-    const devtools = initDevframe(defineTestDef('handler-bridge'), {
-      auth: false,
-      ws: { port: wsPort },
-    })
+    const devtools = initDevframe(defineTestDef('handler-bridge'), { base: '/__handler-bridge/', auth: false, ws: { port: wsPort } })
 
     try {
       await devtools.ready

packages/devframe/src/adapters/initiate.ts

@@ -17,16 +17,19 @@ import { diagnostics } from '../node/diagnostics'
 import { createH3DevframeHost } from '../node/host-h3'
 import { startHttpAndWs } from '../node/server'
 import { createInteractiveAuth } from '../recipes/interactive-auth'
-import { normalizeBasePath, resolveBasePath } from './_shared'
+import { normalizeBasePath } from './_shared'
 import { resolveDevServerPort, resolveMcpConnectionMeta } from './dev'
 
 export interface InitDevframeOptions {
   /**
-   * Mount base the handler answers under. Defaults to
-   * `resolveBasePath(def, 'hosted')` (i.e. `def.basePath` or `/__<id>/`) —
-   * a handler is by definition mounted *inside* a host app's origin.
+   * Mount base the handler answers under (e.g. `/__my-tool/`) — required so
+   * the mount path is explicit at the call site. A handler is by definition
+   * mounted *inside* a host app's origin; the resolved value is echoed back
+   * as {@link DevframeInstance.base} so route/middleware code references it
+   * instead of repeating the string. `resolveBasePath(def, 'hosted')` gives
+   * the conventional `def.basePath ?? /__<id>/`.
    */
-  base?: string
+  base: string
   /**
    * Override `def.cli?.distDir`. When neither is set — or `false` is passed
    * to suppress the definition's own `distDir` — the handler runs in
@@ -154,9 +157,16 @@ export interface DevframeInstanceWebSocket {
 }
 
 export interface DevframeInstance {
+  /**
+   * The normalized mount base this instance answers under (leading and
+   * trailing slash, e.g. `/__my-tool/`). Reference it when wiring the mount
+   * — route guards, middleware path checks — instead of repeating the
+   * string literal.
+   */
+  base: string
   /**
    * Web-standard request handler — mount it on a catch-all route under
-   * {@link InitDevframeOptions.base} (Next.js route handler, SvelteKit
+   * {@link DevframeInstance.base} (Next.js route handler, SvelteKit
    * `+server.ts`, Hono `c.req.raw`, Nitro `toWebRequest(event)`, …).
    * Requests outside the base 404. Under Bun, pass the `Bun.serve` server
    * as the second argument so WS upgrade requests can be completed (an
@@ -273,7 +283,7 @@ export function getInstanceInternals(handler: object): DevframeInstanceInternals
  */
 export function initDevframe(
   def: DevframeDefinition,
-  options: InitDevframeOptions = {},
+  options: InitDevframeOptions,
 ): DevframeInstance {
   if (options.key) {
     const registry = instanceRegistry()
@@ -296,7 +306,7 @@ function instantiateDevframe(
   def: DevframeDefinition,
   options: InitDevframeOptions,
 ): DevframeInstance {
-  const base = options.base ? normalizeBasePath(options.base) : resolveBasePath(def, 'hosted')
+  const base = normalizeBasePath(options.base)
   const baseNoSlash = withoutTrailingSlash(base)
   const distDir = options.distDir === false ? undefined : options.distDir ?? def.cli?.distDir
   const app = options.app ?? new H3()
@@ -566,6 +576,7 @@ function instantiateDevframe(
   }
 
   const handler: DevframeInstance = {
+    base,
     handler: handleRequest,
     nodeMiddleware,
     websocket,