From c590674242606ec2b587d3e6640186007c874d4c Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 5 Aug 2026 23:56:42 +0000
Subject: [PATCH 1/4] docs: plan for /__devframes/ standard middleware handlers

---
 plans/devframes-standard-middleware.md | 183 +++++++++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 plans/devframes-standard-middleware.md

diff --git a/plans/devframes-standard-middleware.md b/plans/devframes-standard-middleware.md
new file mode 100644
index 00000000..58cb402f
--- /dev/null
+++ b/plans/devframes-standard-middleware.md
@@ -0,0 +1,183 @@
+# Plan: `/__devframes/` framework-agnostic standard middleware
+
+> Plan of record settled in a design interview on 2026-08-05. Implementation lands as a
+> 5-PR GitHub stack (bottom → top), each layer passing the full gauntlet
+> (`pnpm lint && pnpm knip && pnpm test && pnpm typecheck && pnpm build`).
+
+## Goal
+
+One web-standard handler (`(Request) => Response`, Comark-style — see
+<https://content.comark.dev/getting-started/installation#mount-the-handler>) that carries the
+entire devtools surface — mounted devframes, WS RPC, auth, MCP, embedded floating mode —
+mountable on any framework with a single catch-all route (Vite, Nitro, Hono, Next.js, Nuxt,
+SvelteKit), running on Node ≥ 20 and Bun. The hub stays headless; UI is a composable slot.
+
+## Architecture
+
+### Two `createHandler` factories, one UI slot
+
+| Import | Serves | Default base |
+|---|---|---|
+| `devframe/handler` | **One devframe**: its SPA (`distDir`; omitted → bridge mode serving only meta + WS), `__connection.json`, `__mcp`, WS RPC, auth. Own isolated context, one `def.setup(ctx)`. | `/__<id>/` (hosted rule) |
+| `@devframes/hub/handler` | **Multi-frame, headless**: shared hub context (docks/terminals/messages/commands + hub built-in RPCs + shared-state slots); every frame's `setup(ctx)` runs against it → one merged RPC registry, one WS endpoint, **one hub Auth**, one aggregate MCP. Frames auto-registered as iframe docks. | `/__devframes/` |
+
+**`DevframeHubUi` slot** (type lives in `@devframes/hub`; data-first, zero policy):
+
+```ts
+interface DevframeHubUi {
+  viewer?: { distDir: string } // standalone viewer SPA served at the namespace root
+  embedded?: { entry: string } // prebuilt bootstrap served at <base>embedded.js
+}
+```
+
+`@devframes/hub-ui` (new package) exports `createUi(options?)` — the *reference* implementation
+(a port of Vite DevTools' web components). Vite DevTools / community supply their own `ui`
+object to the same slot, reusing all infra. There is **no** `createHandler` in hub-ui.
+
+### Handler API (both factories)
+
+```ts
+const h = createHandler(defOrOptions, {
+  base?,                   // mount base; hosted default /__<id>/ (core) or /__devframes/ (hub)
+  server?,                 // sugar: node http server → shared WS upgrade at <base>__ws
+  ws?: DevframeWsOptions,  // explicit control — url > port > route (default '__ws')
+  auth?,                   // default TRUE (existing OTP/token machinery); explicit false to opt out
+  mcp?,                    // per-frame MCP (core) / aggregate MCP (hub)
+  key?,                    // globalThis memoization — HMR re-evaluation returns the live instance
+  origin?,                 // banner origin override; else derived lazily from first request
+  // hub only:
+  devframes?, context?,    // declarative list OR pre-built hub context
+  configure?,              // async (ctx) => {} for docks/commands/terminals/messages registration
+  ui?,                     // DevframeHubUi
+})
+// → { fetch(request, runtimeCtx?), nodeMiddleware, websocket, ready, context,
+//     connectionMeta(), close() }
+```
+
+- Sync factory, **eager** async init; `fetch` awaits `ready` internally.
+- `fetch` 404s inside its base; `nodeMiddleware` (connect-style) calls `next()` outside it.
+- Bun: `fetch(req, server)` second arg + exposed `websocket` hooks (crossws Bun adapter).
+- `key` memoization: a re-evaluation returns the live instance (closes/replaces it if the
+  options changed) — prevents eager side-car leaks under Next/Nitro/SvelteKit dev HMR.
+
+### WebSocket resolution (precedence)
+
+1. `ws.url` — advertise an external endpoint verbatim; the handler owns **no** transport.
+   Hosts that want the handler's RPC on their *own* WS server use the documented recipe:
+   `attachWsRpcTransport(handler.context RPC group, { server, path })` + a matching `ws`.
+2. `ws.port` — explicit side-car port.
+3. `server` — shared upgrade on the host's node http server at `<base><ws.route ?? '__ws'>`.
+4. *(default)* — **eager** auto side-car on a free port, started at handler creation so
+   `__connection.json` is stable from the first request.
+
+All four advertised consistently in `__connection.json`. The WS route unifies on **`__ws`**
+everywhere (breaking: was `__devframe_ws`), matching upstream Vite DevTools' `/__devtools/__ws`.
+
+### Path layout (hub, under base `/__devframes/`)
+
+| Path | Serves | Condition |
+|---|---|---|
+| `/` | `ui.viewer` dist, else the index document | — |
+| `__index.json` | JSON index: frame ids/bases, endpoint paths | always |
+| `embedded.js` | `ui.embedded.entry` | 404 without `ui.embedded` |
+| `__connection.json` | hub connection meta | always |
+| `__ws` | WS upgrade route (shared-server tier) | always |
+| `__client-imports.js` | dock client-script import map | always |
+| `__mcp` | **aggregate** MCP over the shared context registry | when `mcp` enabled |
+| `<id>/` | each frame's SPA + its per-frame `__connection.json` | reserved-name-validated ids |
+
+Per-frame `__mcp` exists only on the singular handler (the hub's shared context makes the
+aggregate the meaningful endpoint; tool ids are already namespaced `devframes:plugin:<slug>:*`).
+
+### Auth
+
+- Gated **by default** on both factories (existing `createInteractiveAuth` OTP + token
+  machinery; `anonymous:` pre-trust prefix; WS origin gate).
+- **Hub: a single Auth.** One `DevframeAuthHandler` owned by the hub handler, one OTP
+  handshake, one trusted-token store, enforced at the one shared transport. Mounted frames
+  have no auth of their own — trust established once covers every frame, the aggregate MCP
+  origin gate, and the hub built-ins. Iframes may arrive pre-authorized via hub-served
+  `authToken` meta or reuse the parent page's connection (`__DEVFRAME_CONNECTION__`).
+- Banner origin derived lazily from the first request (`origin` option overrides).
+
+### Embedded mode
+
+- `embedded.js` = prebuilt bundle: headless `createDevframeClientHost` + hub-ui's
+  `DockEmbedded`. **Always visible on load** — no view-mode model in hub-ui. Visibility
+  policy belongs to whoever authors the entry (Vite DevTools keeps its normal/passive/hidden
+  model in *its own* entry via its own `embedded: { entry }`). Dock-local state
+  (position/collapse) stays — component behavior, not visibility policy.
+- Base discovery from `import.meta.url`; OTP/auth UI included.
+- Injection = documented one-line `<script type="module" src="/__devframes/embedded.js">`
+  per framework. No Vite sugar plugin in this effort (deferred).
+
+### Singular vs hub mounting — what a devframe's SPA / RPC client sees
+
+The devframe's SPA and RPC client code are **byte-identical** in both cases (devframe's
+portability promise): relative assets, base from `document.baseURI`, `connectDevframe()`
+fetching `<base>__connection.json`. The differences are environmental:
+
+| What the SPA / RPC client sees | Singular (`/__git/`) | Hub (`/__devframes/git/`) |
+|---|---|---|
+| Runtime base | `/__git/` | `/__devframes/git/` (transparent to the SPA) |
+| `__connection.json` | Own meta; WS at `<base>__ws` or side-car | Per-frame meta pointing at the **shared** hub WS |
+| RPC registry | Only this frame's functions (+ `anonymous:` handshake) | Merged: all frames + hub built-ins — callable cross-frame by design |
+| Shared state | Own context's slots only | All frames' slots + hub slots |
+| Auth | Own gate, own token | **Single hub Auth** — frames delegate entirely; one handshake unlocks the namespace |
+| Hub subsystems | Absent | Present; frame is also an iframe dock |
+| MCP | `<base>__mcp`, this frame's tools | Aggregate only, at hub level |
+| Isolation | Hard (own context, own transport) | Cooperative (shared context — tools can compose) |
+
+### Migrations (same effort, public names kept)
+
+- `createDevServer` → thin node server over `createHandler` (+ port resolution, instance
+  registry, openBrowser). One wiring everywhere.
+- `viteDevBridge` → wraps the singular handler (`nodeMiddleware` + `server.httpServer` WS).
+- `@devframes/next` → reduces to memoization/re-export sugar over the handler.
+- `@devframes/nuxt` externally untouched.
+- Retire the unused `DEVFRAME_MOUNT_PATH` constant in favor of the new default-base constants.
+
+## Delivery: 5-PR GitHub stack (bottom → top, merge bottom-up)
+
+1. **`feat/handler-core`** — this plan doc; `devframe/handler`: `createHandler` (fetch/node/Bun
+   shapes, four WS resolutions, auth gate, per-frame MCP, `key` memo), `__ws` constants,
+   new `DF00xx` diagnostics + `docs/errors/` pages, vitest coverage (fetch, middleware,
+   WS tiers + meta correctness per resolution, auth gating).
+2. **`feat/handler-adapters`** — `createDevServer` / `viteDevBridge` / `@devframes/next`
+   rebuilt on the handler; api-snapshot updates.
+3. **`feat/hub-handler`** — `@devframes/hub/handler`: internal `DevframeHost` impl, frame
+   mounting at `<base><id>/`, `ui` slot + `DevframeHubUi` type, `__index.json`,
+   `__client-imports.js`, aggregate MCP, `devframes`/`context`/`configure` options,
+   `DF8xxx` diagnostics, tests incl. reserved-path guards, cross-frame RPC visibility,
+   shared-WS meta resolution from per-frame metas.
+4. **`feat/hub-ui`** — new package `@devframes/hub-ui`: full web-components port from
+   Vite DevTools (DockEmbedded, DockStandalone, floating, views, views-builtin,
+   command-palette, message, auth UI — no mode plumbing), devframe-branded
+   (`@antfu/design` tokens, Phosphor icons, named `z-*` layers), two prebuilt entries
+   (vanilla standalone viewer shell, embedded bootstrap), `createUi()`, storybook per repo
+   convention, typecheck/knip/exports wiring.
+5. **`feat/handler-examples-docs`** — migrate both reference hub examples onto the headless
+   hub handler (hand-built UIs kept as protocol demos, parity + README parity maintained);
+   new minimal `examples/nitro-devframe-hub` + `examples/hono-devframe-hub`
+   (`ui: createUi()` + script tag; Hono verified on Node **and** Bun); local `scripts/` Bun
+   smoke test (boots the Hono example on Bun: fetch + WS RPC + embedded.js); Comark-style
+   mount guides for Vite/Nitro/Hono/Next/Nuxt/SvelteKit; "Singular vs hub mounting" docs page.
+
+## Breaking changes (pre-1.0, called out in PR bodies)
+
+- Hosted default bases move under the hub base: `/__<id>/` → `<hubBase><id>/`
+  (coordinate with vite-devtools downstream).
+- WS route `__devframe_ws` → `__ws` across all adapters.
+
+## Verification items / known risks
+
+- Per-frame meta → shared `__ws` resolution (`resolveWsUrl`) — dedicated tests in PR 3.
+- Eager side-car + HMR leaks — built-in `key` memoization; all snippets set it.
+- Auth banner origin — lazy derivation from first request + `origin` override.
+- hub-ui port is the bulk of the diff (~5–8k LOC) — isolated in its own PR layer.
+
+## Non-goals
+
+Deno/Cloudflare runtimes; per-frame MCP under the hub; `__mode.json` / view-mode machinery;
+framework injection sugar (Vite plugin deferred); any UI inside `@devframes/hub`; any release
+(requires explicit human approval).

From 136c37dc5060d3ff21ccdbcd28f8136e9d0f0122 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 6 Aug 2026 00:32:15 +0000
Subject: [PATCH 2/4] refactor(rpc): extract transport-agnostic rpc core and
 reusable ws peer hooks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

createContextRpcServer owns everything about serving RPC that is
independent of how peers connect (auth wiring, session resolver,
auto-trust shim); createWsRpcPeerHooks shapes the per-peer lifecycle for
any crossws adapter. startHttpAndWs behavior is unchanged — it now
composes the two, so other transports (fetch-upgrade runtimes) can reuse
the same wiring.
---
 packages/devframe/src/node/rpc-core.ts        | 151 +++++++++++++
 packages/devframe/src/node/server.ts          | 104 ++-------
 .../devframe/src/rpc/transports/ws-server.ts  | 199 ++++++++++--------
 3 files changed, 275 insertions(+), 179 deletions(-)
 create mode 100644 packages/devframe/src/node/rpc-core.ts

diff --git a/packages/devframe/src/node/rpc-core.ts b/packages/devframe/src/node/rpc-core.ts
new file mode 100644
index 00000000..d75f2774
--- /dev/null
+++ b/packages/devframe/src/node/rpc-core.ts
@@ -0,0 +1,151 @@
+import type { BirpcGroup, EventOptions } from 'birpc'
+import type { Peer } from 'crossws'
+import type { DevframeNodeContext, DevframeNodeRpcSession, DevframeNodeRpcSessionMeta, DevframeRpcClientFunctions, DevframeRpcServerFunctions } from 'devframe/types'
+import type { DevframeAuthHandler } from './auth'
+import type { RpcFunctionsHostImpl } from './host-functions'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createRpcServer } from 'devframe/rpc/server'
+import { diagnostics } from './diagnostics'
+
+export interface CreateContextRpcServerOptions {
+  context: DevframeNodeContext
+  /** See `StartHttpAndWsOptions.auth` — same contract, transport-agnostic. */
+  auth?: boolean | DevframeAuthHandler
+  /** See `StartHttpAndWsOptions.authorize`. */
+  authorize?: (methodName: string, session: DevframeNodeRpcSession) => boolean
+  /** See `StartHttpAndWsOptions.onPeerConnect`. */
+  onPeerConnect?: (peer: Peer, session: DevframeNodeRpcSession) => void
+  /** See `StartHttpAndWsOptions.onPeerDisconnect`. */
+  onPeerDisconnect?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void
+  /** See `StartHttpAndWsOptions.rpcOptions`. */
+  rpcOptions?: Pick<
+    EventOptions<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>,
+    'onFunctionError' | 'onGeneralError'
+  >
+}
+
+export interface ContextRpcServer {
+  rpcGroup: BirpcGroup<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>
+  /** The resolved auth handler when `auth` was passed as one. */
+  authHandler?: DevframeAuthHandler
+  /**
+   * Peer lifecycle handlers to wire into a WS transport
+   * (`attachWsRpcTransport`'s `onConnected` / `onDisconnected`, or any other
+   * crossws adapter's peer hooks via `createWsRpcPeerHooks`).
+   */
+  onConnected?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void
+  onDisconnected: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void
+}
+
+/**
+ * Bind a devframe context's registered RPC functions to a birpc group,
+ * transport-agnostically — the shared core under `startHttpAndWs` (Node
+ * http + WS) and the Bun fetch-upgrade tier of `createHandler`.
+ *
+ * Owns everything about serving RPC that is independent of *how* peers
+ * connect: the auth handler's function registration, the
+ * `AsyncLocalStorage`-based session resolver (so
+ * `ctx.rpc.getCurrentRpcSession()` works inside handlers), the
+ * `authorize` gate, and the `auth: false` auto-trust handshake shim.
+ */
+export function createContextRpcServer(options: CreateContextRpcServerOptions): ContextRpcServer {
+  const { context } = options
+  const rpcHost = context.rpc as unknown as RpcFunctionsHostImpl
+
+  const asyncStorage = new AsyncLocalStorage<DevframeNodeRpcSession>()
+
+  // A full auth handler (e.g. from `createInteractiveAuth`) registers its own
+  // RPC functions and supplies both the resolver gate and the connect-time
+  // trust hook. `authorize`/`onPeerConnect` are the lower-level escape
+  // hatches for callers not using a full handler.
+  const authHandler: DevframeAuthHandler | undefined = typeof options.auth === 'object' ? options.auth : undefined
+  const effectiveAuthorize = options.authorize ?? authHandler?.authorize
+
+  if (authHandler) {
+    for (const fn of authHandler.rpcFunctions) {
+      if (!rpcHost.definitions.has(fn.name))
+        rpcHost.register(fn)
+    }
+  }
+
+  const rpcGroup = createRpcServer<DevframeRpcClientFunctions, DevframeRpcServerFunctions>(
+    rpcHost.functions,
+    {
+      rpcOptions: {
+        // Forwarded as-is so a host with its own structured diagnostics
+        // keeps seeing RPC failures; see `StartHttpAndWsOptions.rpcOptions`.
+        onFunctionError: options.rpcOptions?.onFunctionError,
+        onGeneralError: options.rpcOptions?.onGeneralError,
+        // Wrap each RPC handler in an AsyncLocalStorage context so
+        // `ctx.rpc.getCurrentRpcSession()` works inside handlers (used
+        // by streaming subscribe/unsubscribe/cancel and shared-state
+        // sync), and — when an `authorize` gate is configured — reject
+        // the call before it ever reaches the handler. Mirrors
+        // `packages/core/src/node/ws.ts`'s resolver.
+        resolver(name, fn) {
+          // eslint-disable-next-line ts/no-this-alias
+          const rpc = this
+          if (!fn)
+            return undefined
+          return async function (this: any, ...args) {
+            const meta = rpc.$meta as DevframeNodeRpcSessionMeta
+            if (effectiveAuthorize && !effectiveAuthorize(name, { meta, rpc: rpc as any }))
+              throw diagnostics.DF0036({ name })
+            return await asyncStorage.run({
+              rpc,
+              meta,
+            }, async () => {
+              return (await fn).apply(this, args)
+            })
+          }
+        },
+      },
+    },
+  )
+
+  ;(rpcHost as any)._rpcGroup = rpcGroup
+  ;(rpcHost as any)._asyncStorage = asyncStorage
+  ;(rpcHost as any)._authDisabled = options.auth === false
+
+  // The browser client unconditionally calls `anonymous:devframe:auth` on
+  // connect (see `client/rpc-ws.ts`). When `auth: false` is set on the
+  // standalone server, register a noop handler that auto-trusts so the
+  // client's hardcoded handshake succeeds. A host passing a full
+  // `DevframeAuthHandler` already registered the real handler above, and
+  // never opts into `auth: false`, so the two paths never overlap.
+  if (options.auth === false && !rpcHost.definitions.has('anonymous:devframe:auth')) {
+    rpcHost.register({
+      name: 'anonymous:devframe:auth',
+      type: 'action',
+      handler: () => {
+        const session = rpcHost.getCurrentRpcSession()
+        if (session)
+          session.meta.isTrusted = true
+        return { isTrusted: true }
+      },
+    })
+  }
+
+  const onConnected = (authHandler || options.onPeerConnect)
+    ? (peer: Peer, meta: DevframeNodeRpcSessionMeta) => {
+        const session: DevframeNodeRpcSession = {
+          meta,
+          rpc: rpcGroup.clients.find(client => (client as any).$meta === meta) as any,
+        }
+        authHandler?.onConnect(peer, session)
+        options.onPeerConnect?.(peer, session)
+      }
+    : undefined
+
+  const onDisconnected = (peer: Peer, meta: DevframeNodeRpcSessionMeta): void => {
+    options.onPeerDisconnect?.(peer, meta)
+    rpcHost._emitSessionDisconnected(meta)
+  }
+
+  return {
+    rpcGroup,
+    authHandler,
+    onConnected,
+    onDisconnected,
+  }
+}
diff --git a/packages/devframe/src/node/server.ts b/packages/devframe/src/node/server.ts
index 7e8f2025..262fa823 100644
--- a/packages/devframe/src/node/server.ts
+++ b/packages/devframe/src/node/server.ts
@@ -6,13 +6,12 @@ import type { ConnectionMeta, DevframeNodeContext, DevframeNodeRpcSession, Devfr
 import type { Server as NodeHttpServer } from 'node:http'
 import type { DevframeAuthHandler } from './auth'
 import type { RpcFunctionsHostImpl } from './host-functions'
-import { AsyncLocalStorage } from 'node:async_hooks'
 import { createServer } from 'node:http'
-import { createRpcServer } from 'devframe/rpc/server'
 import { attachWsRpcTransport } from 'devframe/rpc/transports/ws-server'
 import { H3, toNodeHandler } from 'h3'
 import { diagnostics } from './diagnostics'
 import { getInternalContext } from './hub-internals/context'
+import { createContextRpcServer } from './rpc-core'
 import { formatHostForUrl, normalizeHttpServerUrl } from './utils'
 
 export interface StartHttpAndWsOptions {
@@ -26,7 +25,7 @@ export interface StartHttpAndWsOptions {
    */
   app?: H3
   /**
-   * Bind the WS endpoint to a single upgrade route (e.g. `/__devframe_ws`) instead of
+   * Bind the WS endpoint to a single upgrade route (e.g. `/__ws`) instead of
    * claiming every upgrade on the port. This lets the socket share a server
    * with other upgrade handlers (Vite HMR, a host framework's own sockets)
    * and is what the SPA's `__connection.json` points at. When omitted, the WS
@@ -163,56 +162,16 @@ export async function startHttpAndWs(options: StartHttpAndWsOptions): Promise<St
   const httpServer = options.server ?? createServer(toNodeHandler(app))
   const rpcHost = context.rpc as unknown as RpcFunctionsHostImpl
 
-  const asyncStorage = new AsyncLocalStorage<DevframeNodeRpcSession>()
-
-  // A full auth handler (e.g. from `createInteractiveAuth`) registers its own
-  // RPC functions and supplies both the resolver gate and the connect-time
-  // trust hook. `authorize`/`onPeerConnect` are the lower-level escape
-  // hatches for callers not using a full handler.
-  const authHandler: DevframeAuthHandler | undefined = typeof options.auth === 'object' ? options.auth : undefined
-  const effectiveAuthorize = options.authorize ?? authHandler?.authorize
-
-  if (authHandler) {
-    for (const fn of authHandler.rpcFunctions) {
-      if (!rpcHost.definitions.has(fn.name))
-        rpcHost.register(fn)
-    }
-  }
-
-  const rpcGroup = createRpcServer<DevframeRpcClientFunctions, DevframeRpcServerFunctions>(
-    rpcHost.functions,
-    {
-      rpcOptions: {
-        // Forwarded as-is so a host with its own structured diagnostics
-        // keeps seeing RPC failures; see `StartHttpAndWsOptions.rpcOptions`.
-        onFunctionError: options.rpcOptions?.onFunctionError,
-        onGeneralError: options.rpcOptions?.onGeneralError,
-        // Wrap each RPC handler in an AsyncLocalStorage context so
-        // `ctx.rpc.getCurrentRpcSession()` works inside handlers (used
-        // by streaming subscribe/unsubscribe/cancel and shared-state
-        // sync), and — when an `authorize` gate is configured — reject
-        // the call before it ever reaches the handler. Mirrors
-        // `packages/core/src/node/ws.ts`'s resolver.
-        resolver(name, fn) {
-          // eslint-disable-next-line ts/no-this-alias
-          const rpc = this
-          if (!fn)
-            return undefined
-          return async function (this: any, ...args) {
-            const meta = rpc.$meta as DevframeNodeRpcSessionMeta
-            if (effectiveAuthorize && !effectiveAuthorize(name, { meta, rpc: rpc as any }))
-              throw diagnostics.DF0036({ name })
-            return await asyncStorage.run({
-              rpc,
-              meta,
-            }, async () => {
-              return (await fn).apply(this, args)
-            })
-          }
-        },
-      },
-    },
-  )
+  // Transport-agnostic RPC core: auth wiring, session resolver, and the
+  // peer lifecycle handlers the WS transport below plugs into.
+  const { rpcGroup, onConnected, onDisconnected } = createContextRpcServer({
+    context,
+    auth: options.auth,
+    authorize: options.authorize,
+    onPeerConnect: options.onPeerConnect,
+    onPeerDisconnect: options.onPeerDisconnect,
+    rpcOptions: options.rpcOptions,
+  })
 
   // A dedicated WS port (the "different port" scenario) only applies when we
   // own the HTTP server — a shared host server already dictates the port.
@@ -231,45 +190,10 @@ export async function startHttpAndWs(options: StartHttpAndWsOptions): Promise<St
     // other sockets, so leave non-matching upgrades for them.
     destroyUnmatched: ownsHttpServer,
     allowedOrigins: options.allowedOrigins,
-    onConnected: (authHandler || options.onPeerConnect)
-      ? (peer, meta) => {
-          const session: DevframeNodeRpcSession = {
-            meta,
-            rpc: rpcGroup.clients.find(client => (client as any).$meta === meta) as any,
-          }
-          authHandler?.onConnect(peer, session)
-          options.onPeerConnect?.(peer, session)
-        }
-      : undefined,
-    onDisconnected: (peer, meta) => {
-      options.onPeerDisconnect?.(peer, meta)
-      rpcHost._emitSessionDisconnected(meta)
-    },
+    onConnected,
+    onDisconnected,
   })
 
-  ;(rpcHost as any)._rpcGroup = rpcGroup
-  ;(rpcHost as any)._asyncStorage = asyncStorage
-  ;(rpcHost as any)._authDisabled = options.auth === false
-
-  // The browser client unconditionally calls `anonymous:devframe:auth` on
-  // connect (see `client/rpc-ws.ts`). When `auth: false` is set on the
-  // standalone server, register a noop handler that auto-trusts so the
-  // client's hardcoded handshake succeeds. A host passing a full
-  // `DevframeAuthHandler` already registered the real handler above, and
-  // never opts into `auth: false`, so the two paths never overlap.
-  if (options.auth === false && !rpcHost.definitions.has('anonymous:devframe:auth')) {
-    rpcHost.register({
-      name: 'anonymous:devframe:auth',
-      type: 'action',
-      handler: () => {
-        const session = rpcHost.getCurrentRpcSession()
-        if (session)
-          session.meta.isTrusted = true
-        return { isTrusted: true }
-      },
-    })
-  }
-
   // Only start listening on a server we created. A shared server is already
   // (or about to be) listening under the caller's control.
   if (ownsHttpServer) {
diff --git a/packages/devframe/src/rpc/transports/ws-server.ts b/packages/devframe/src/rpc/transports/ws-server.ts
index 3319d91c..85800c1e 100644
--- a/packages/devframe/src/rpc/transports/ws-server.ts
+++ b/packages/devframe/src/rpc/transports/ws-server.ts
@@ -1,5 +1,5 @@
 import type { BirpcGroup, ChannelOptions } from 'birpc'
-import type { Peer } from 'crossws'
+import type { Hooks, Peer } from 'crossws'
 import type { NodeAdapter } from 'crossws/adapters/node'
 import type { Buffer } from 'node:buffer'
 import type { Server as HttpServer, IncomingMessage } from 'node:http'
@@ -49,7 +49,7 @@ export interface WsRpcTransportOptions {
   /** Host for a newly-created standalone WS server. Defaults to `localhost`. */
   host?: string
   /**
-   * Restrict the WS endpoint to a single upgrade route (e.g. `/__devframe_ws`). When
+   * Restrict the WS endpoint to a single upgrade route (e.g. `/__ws`). When
    * sharing a `server`, non-matching upgrade requests are left untouched for
    * other listeners to handle, so devframe's socket can sit alongside
    * framework sockets (Vite HMR, etc.).
@@ -270,6 +270,113 @@ function routeUpgrades(
   return () => server.off('upgrade', listener)
 }
 
+/**
+ * The per-peer lifecycle hooks driving a devframe RPC WebSocket, shaped for
+ * any [crossws](https://crossws.h3.dev) adapter. {@link attachWsRpcTransport}
+ * feeds them to the Node adapter; runtime-specific attachments (e.g. Bun's
+ * fetch-upgrade adapter) reuse the same hooks so every transport speaks the
+ * identical wire protocol — one birpc channel per peer, per-method
+ * `jsonSerializable` dispatch between strict JSON and structured-clone.
+ */
+export function createWsRpcPeerHooks<
+  ClientFunctions extends object,
+  ServerFunctions extends object,
+>(
+  rpcGroup: BirpcGroup<ClientFunctions, ServerFunctions, false>,
+  options: Pick<WsRpcTransportOptions, 'onConnected' | 'onDisconnected' | 'definitions' | 'serialize' | 'deserialize'> = {},
+): Partial<Hooks> {
+  const {
+    onConnected = NOOP,
+    onDisconnected = NOOP,
+    definitions = EMPTY_DEFS,
+    serialize: serializeOverride,
+    deserialize: deserializeOverride,
+  } = options
+
+  interface PeerState {
+    meta: DevframeNodeRpcSessionMeta
+    channel: ChannelOptions
+    /** birpc's inbound-message handler, registered via the channel's `on`. */
+    onMessage?: (data: string) => void
+  }
+  const states = new WeakMap<Peer, PeerState>()
+
+  return {
+    open: (peer) => {
+      const meta: DevframeNodeRpcSessionMeta = {
+        id: sessionId++,
+        peer,
+        subscribedStates: new Set(),
+      }
+
+      // Per-connection state: maps an incoming request id to its method
+      // name so the matching outgoing response can look the method back
+      // up in `definitions` and pick the right encoder. One map per
+      // session — request-id spaces don't collide across sessions.
+      const pendingRequestMethods = new Map<string, string>()
+      const state: PeerState = { meta, channel: undefined as unknown as ChannelOptions }
+      const channel: ChannelOptions = {
+        post: (data) => {
+          peer.send(data)
+        },
+        on: (fn) => {
+          state.onMessage = fn
+        },
+        serialize: serializeOverride ?? ((msg: any): string => {
+          let method: string | undefined
+          if (msg.t === 'q') {
+            method = msg.m
+          }
+          else {
+            method = pendingRequestMethods.get(msg.i)
+            pendingRequestMethods.delete(msg.i)
+          }
+          // `jsonSerializable` constrains the return-value path (args + return).
+          // Error envelopes (`{ t: 's', i, e }`) carry a thrown value — fall back
+          // to structured-clone so they round-trip instead of crashing the serializer.
+          // Detect via `'e' in msg` so `throw undefined` still routes through SC.
+          const isErrorResponse = msg.t === 's' && 'e' in msg
+          const useJson = !isErrorResponse && !!method && definitions.get(method)?.jsonSerializable === true
+          if (useJson)
+            return strictJsonStringify(msg, method ?? '')
+          return `${STRUCTURED_CLONE_PREFIX}${structuredCloneStringify(msg)}`
+        }),
+        deserialize: deserializeOverride ?? ((raw: string): any => {
+          const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
+            ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
+            : JSON.parse(raw)
+          if (msg.t === 'q' && msg.i && msg.m)
+            pendingRequestMethods.set(msg.i, msg.m)
+          return msg
+        }),
+        meta,
+      }
+      state.channel = channel
+      states.set(peer, state)
+
+      rpcGroup.updateChannels((channels) => {
+        channels.push(channel)
+      })
+      onConnected(peer, meta)
+    },
+    message: (peer, message) => {
+      states.get(peer)?.onMessage?.(message.text())
+    },
+    close: (peer) => {
+      const state = states.get(peer)
+      if (!state)
+        return
+      states.delete(peer)
+      rpcGroup.updateChannels((channels) => {
+        const index = channels.indexOf(state.channel)
+        if (index >= 0)
+          channels.splice(index, 1)
+      })
+      onDisconnected(peer, state.meta)
+    },
+  }
+}
+
 /**
  * Attach a WebSocket transport to an existing RPC group, powered by
  * [crossws](https://crossws.h3.dev). Either attach to an existing HTTP(S)
@@ -295,96 +402,10 @@ export function attachWsRpcTransport<
     destroyUnmatched = false,
     https,
     allowedOrigins,
-    onConnected = NOOP,
-    onDisconnected = NOOP,
-    definitions = EMPTY_DEFS,
-    serialize: serializeOverride,
-    deserialize: deserializeOverride,
   } = options
 
-  interface PeerState {
-    meta: DevframeNodeRpcSessionMeta
-    channel: ChannelOptions
-    /** birpc's inbound-message handler, registered via the channel's `on`. */
-    onMessage?: (data: string) => void
-  }
-  const states = new WeakMap<Peer, PeerState>()
-
   const ws = crossws({
-    hooks: {
-      open: (peer) => {
-        const meta: DevframeNodeRpcSessionMeta = {
-          id: sessionId++,
-          peer,
-          subscribedStates: new Set(),
-        }
-
-        // Per-connection state: maps an incoming request id to its method
-        // name so the matching outgoing response can look the method back
-        // up in `definitions` and pick the right encoder. One map per
-        // session — request-id spaces don't collide across sessions.
-        const pendingRequestMethods = new Map<string, string>()
-        const state: PeerState = { meta, channel: undefined as unknown as ChannelOptions }
-        const channel: ChannelOptions = {
-          post: (data) => {
-            peer.send(data)
-          },
-          on: (fn) => {
-            state.onMessage = fn
-          },
-          serialize: serializeOverride ?? ((msg: any): string => {
-            let method: string | undefined
-            if (msg.t === 'q') {
-              method = msg.m
-            }
-            else {
-              method = pendingRequestMethods.get(msg.i)
-              pendingRequestMethods.delete(msg.i)
-            }
-            // `jsonSerializable` constrains the return-value path (args + return).
-            // Error envelopes (`{ t: 's', i, e }`) carry a thrown value — fall back
-            // to structured-clone so they round-trip instead of crashing the serializer.
-            // Detect via `'e' in msg` so `throw undefined` still routes through SC.
-            const isErrorResponse = msg.t === 's' && 'e' in msg
-            const useJson = !isErrorResponse && !!method && definitions.get(method)?.jsonSerializable === true
-            if (useJson)
-              return strictJsonStringify(msg, method ?? '')
-            return `${STRUCTURED_CLONE_PREFIX}${structuredCloneStringify(msg)}`
-          }),
-          deserialize: deserializeOverride ?? ((raw: string): any => {
-            const msg: any = raw.startsWith(STRUCTURED_CLONE_PREFIX)
-              ? structuredCloneParse(raw.slice(STRUCTURED_CLONE_PREFIX.length))
-              : JSON.parse(raw)
-            if (msg.t === 'q' && msg.i && msg.m)
-              pendingRequestMethods.set(msg.i, msg.m)
-            return msg
-          }),
-          meta,
-        }
-        state.channel = channel
-        states.set(peer, state)
-
-        rpcGroup.updateChannels((channels) => {
-          channels.push(channel)
-        })
-        onConnected(peer, meta)
-      },
-      message: (peer, message) => {
-        states.get(peer)?.onMessage?.(message.text())
-      },
-      close: (peer) => {
-        const state = states.get(peer)
-        if (!state)
-          return
-        states.delete(peer)
-        rpcGroup.updateChannels((channels) => {
-          const index = channels.indexOf(state.channel)
-          if (index >= 0)
-            channels.splice(index, 1)
-        })
-        onDisconnected(peer, state.meta)
-      },
-    },
+    hooks: createWsRpcPeerHooks(rpcGroup, options),
   })
 
   let detach = NOOP

From 0bf31cc9907146c5ee3c87edda5d668727badba7 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 6 Aug 2026 00:32:34 +0000
Subject: [PATCH 3/4] =?UTF-8?q?feat(handler):=20add=20devframe/handler=20?=
 =?UTF-8?q?=E2=80=94=20framework-agnostic=20web-standard=20middleware?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

createHandler(def) serves a devframe's whole surface — SPA,
__connection.json discovery, WebSocket RPC, auth gate (on by default),
and the optional MCP route — through one fetch handler mountable on any
framework's catch-all route, plus a connect-style nodeMiddleware and Bun
fetch-upgrade websocket hooks.

WebSocket binding resolves by precedence: ws.port (explicit side-car) >
server (shared upgrade at <base>__ws) > ws.url alone (no local
transport; external server owns it) > Bun fetch-upgrade > eager auto
side-car. ws.url always overrides the advertised endpoint (the tunnel
pattern: bind locally, advertise the relay). A key option memoizes the
handler on globalThis so HMR module re-evaluation can't leak side-cars
(DF0053 on option changes; DF0054 for connectionMeta before ready).

BREAKING CHANGE: the WS route unifies on `__ws` (was `__devframe_ws`)
across every adapter, and the unused DEVFRAME_MOUNT_PATH /
DEVFRAME_DIRNAME constants are removed.
---
 alias.ts                                      |   1 +
 docs/adapters/dev.md                          |   6 +-
 docs/errors/DF0053.md                         |  33 ++
 docs/errors/DF0054.md                         |  33 ++
 docs/guide/client.md                          |   4 +-
 docs/helpers/vite-bridge.md                   |   2 +-
 knip.jsonc                                    |   2 +-
 packages/devframe/package.json                |   1 +
 .../src/adapters/__tests__/dev.test.ts        |  18 +-
 .../src/adapters/__tests__/handler.test.ts    | 344 ++++++++++++
 packages/devframe/src/adapters/handler-bun.ts |  70 +++
 packages/devframe/src/adapters/handler.ts     | 511 ++++++++++++++++++
 .../devframe/src/client/rpc-ws-status.test.ts |   2 +-
 packages/devframe/src/client/rpc-ws.test.ts   |  16 +-
 packages/devframe/src/constants.ts            |   6 +-
 .../src/helpers/__tests__/vite.test.ts        |   4 +-
 packages/devframe/src/helpers/vite.ts         |   2 +-
 packages/devframe/src/node/diagnostics.ts     |   8 +
 packages/devframe/src/node/host-h3.ts         |   6 +-
 .../devframe/src/rpc/transports/ws.test.ts    |   4 +-
 packages/devframe/src/types/context.ts        |   4 +-
 packages/devframe/src/types/devframe.ts       |   6 +-
 packages/devframe/tsdown.config.ts            |   1 +
 packages/hub/src/client/remote.test.ts        |   8 +-
 packages/next/test/handler.test.ts            |   2 +-
 .../tsnapi/devframe/constants.snapshot.d.ts   |   3 -
 .../tsnapi/devframe/constants.snapshot.js     |   3 -
 .../tsnapi/devframe/handler.snapshot.d.ts     |  37 ++
 .../tsnapi/devframe/handler.snapshot.js       |   6 +
 .../tsnapi/devframe/node.snapshot.d.ts        |   2 +-
 .../rpc/transports/ws-server.snapshot.d.ts    |   1 +
 .../rpc/transports/ws-server.snapshot.js      |   1 +
 tsconfig.base.json                            |   3 +
 33 files changed, 1096 insertions(+), 54 deletions(-)
 create mode 100644 docs/errors/DF0053.md
 create mode 100644 docs/errors/DF0054.md
 create mode 100644 packages/devframe/src/adapters/__tests__/handler.test.ts
 create mode 100644 packages/devframe/src/adapters/handler-bun.ts
 create mode 100644 packages/devframe/src/adapters/handler.ts
 create mode 100644 tests/__snapshots__/tsnapi/devframe/handler.snapshot.d.ts
 create mode 100644 tests/__snapshots__/tsnapi/devframe/handler.snapshot.js

diff --git a/alias.ts b/alias.ts
index 305572d3..e7d9b731 100644
--- a/alias.ts
+++ b/alias.ts
@@ -40,6 +40,7 @@ export const alias = {
   'devframe/adapters/build': r('devframe/src/adapters/build.ts'),
   'devframe/helpers/vite': r('devframe/src/helpers/vite.ts'),
   'devframe/adapters/embedded': r('devframe/src/adapters/embedded.ts'),
+  'devframe/handler': r('devframe/src/adapters/handler.ts'),
   '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'),
diff --git a/docs/adapters/dev.md b/docs/adapters/dev.md
index ebc1b5ab..a15c813b 100644
--- a/docs/adapters/dev.md
+++ b/docs/adapters/dev.md
@@ -35,18 +35,18 @@ process.on('SIGINT', () => handle.close().then(() => process.exit(0)))
 
 ## WebSocket endpoint
 
-By default the RPC socket shares the HTTP server's port and binds to the `__devframe_ws` route next to `__connection.json`. The descriptor advertises a *relative* path, so the client connects to its own origin — the link follows the page through a reverse proxy that rewrites the domain, port, or subpath. Configure the three connection scenarios via `def.cli.ws` (or the `ws` call-site option):
+By default the RPC socket shares the HTTP server's port and binds to the `__ws` route next to `__connection.json`. The descriptor advertises a *relative* path, so the client connects to its own origin — the link follows the page through a reverse proxy that rewrites the domain, port, or subpath. Configure the three connection scenarios via `def.cli.ws` (or the `ws` call-site option):
 
 ```ts
 defineDevframe({
-  // 1. Same server, a custom route (default route is `__devframe_ws`):
+  // 1. Same server, a custom route (default route is `__ws`):
   cli: { ws: { route: '__sockets' } },
 
   // 2. A dedicated port on the same host:
   cli: { ws: { port: 9788 } },
 
   // 3. A remote, fully-qualified endpoint (e.g. a tunnel/relay):
-  cli: { ws: { url: 'wss://devtools.example.com/relay/__devframe_ws' } },
+  cli: { ws: { url: 'wss://devtools.example.com/relay/__ws' } },
 })
 ```
 
diff --git a/docs/errors/DF0053.md b/docs/errors/DF0053.md
new file mode 100644
index 00000000..730ce2b0
--- /dev/null
+++ b/docs/errors/DF0053.md
@@ -0,0 +1,33 @@
+---
+outline: deep
+---
+
+# DF0053: Memoized Handler Replaced
+
+## Message
+
+> createHandler("`{id}`") replaced the live handler memoized under key "`{key}`": its options changed since the previous call.
+
+## Cause
+
+`createHandler` was called with a `key` that already maps to a live handler, but the option fingerprint differs from the memoized instance's. Dev servers that re-evaluate modules on the fly (Next.js, Nitro, SvelteKit HMR) re-run `createHandler` 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 { createHandler } from 'devframe/handler'
+
+// First evaluation:
+createHandler(def, { key: 'devtools', ws: { port: 7811 } })
+
+// A later reload with a different port replaces the live instance:
+createHandler(def, { key: 'devtools', ws: { port: 7812 } }) // ⚠ DF0053
+```
+
+## Fix
+
+This is informational when you edited the options on purpose — the replacement is the intended behavior. If it fires without an intentional change, make the options stable across reloads (module-level constants rather than values recomputed per evaluation), or give genuinely different handlers distinct keys.
+
+## Source
+
+- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler` warns this before closing and replacing a memoized instance whose options fingerprint changed.
diff --git a/docs/errors/DF0054.md b/docs/errors/DF0054.md
new file mode 100644
index 00000000..a2df3ecd
--- /dev/null
+++ b/docs/errors/DF0054.md
@@ -0,0 +1,33 @@
+---
+outline: deep
+---
+
+# DF0054: connectionMeta() Before Handler Ready
+
+## Message
+
+> connectionMeta() was called before createHandler("`{id}`") finished initializing.
+
+## Cause
+
+`createHandler` is a synchronous factory that kicks off asynchronous initialization eagerly — running `def.setup`, binding the WebSocket tier, and mounting the routes. `connectionMeta()` describes the WebSocket binding, which only exists once that initialization completes; calling it earlier has nothing correct to return.
+
+## Example
+
+```ts
+import { createHandler } from 'devframe/handler'
+
+const handler = createHandler(def)
+handler.connectionMeta() // ✗ throws DF0054 — init is still in flight
+
+await handler.ready
+handler.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
+```
+
+## Fix
+
+Await `handler.ready` (or any `handler.fetch` call — it awaits readiness internally) before reading `connectionMeta()`.
+
+## Source
+
+- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler`'s `connectionMeta()` throws this while initialization is still pending.
diff --git a/docs/guide/client.md b/docs/guide/client.md
index 18c0bc2f..8b101874 100644
--- a/docs/guide/client.md
+++ b/docs/guide/client.md
@@ -229,12 +229,12 @@ With caching on, `query` / `static` function responses are memoized per argument
 
 ## Discovery (`__connection.json`)
 
-Devframe writes a JSON descriptor at `<base>/__connection.json` so the client knows where to connect. The dev server shares one port for HTTP and the WebSocket — the socket is bound to a route (`<base>__devframe_ws`) next to the meta file — and advertises it as a relative path:
+Devframe writes a JSON descriptor at `<base>/__connection.json` so the client knows where to connect. The dev server shares one port for HTTP and the WebSocket — the socket is bound to a route (`<base>__ws`) next to the meta file — and advertises it as a relative path:
 
 ```json
 {
   "backend": "websocket",
-  "websocket": { "path": "__devframe_ws" }
+  "websocket": { "path": "__ws" }
 }
 ```
 
diff --git a/docs/helpers/vite-bridge.md b/docs/helpers/vite-bridge.md
index 6eabe767..71ce2fc1 100644
--- a/docs/helpers/vite-bridge.md
+++ b/docs/helpers/vite-bridge.md
@@ -21,7 +21,7 @@ export default defineConfig({
 ## Modes
 
 - **Static mount** (default) — mounts `def.cli.distDir` at `options.base` (`/__<id>/` by default). No RPC server. Useful when you only need the SPA bundle served from a known path.
-- **Bridge mode** (`devMiddleware: true | {…}`) — skips the static mount; the host app owns the SPA. Devframe spawns a separate RPC + WS server and registers Vite middleware at `<base>__connection.json` so the host-served SPA can discover the WS endpoint. The side-car listens on its own port, so the descriptor carries that port alongside the `/__devframe_ws` route.
+- **Bridge mode** (`devMiddleware: true | {…}`) — skips the static mount; the host app owns the SPA. Devframe spawns a separate RPC + WS server and registers Vite middleware at `<base>__connection.json` so the host-served SPA can discover the WS endpoint. The side-car listens on its own port, so the descriptor carries that port alongside the `/__ws` route.
 
 To mount the RPC socket onto the Vite server's own port instead of a side-car — so it shares the origin with the app and rides through a proxy — pass an existing HTTP server and a route to [`startHttpAndWs`](/adapters/dev) via its `server` and `path` options. Devframe routes only that upgrade path and leaves the rest (Vite's HMR socket included) untouched.
 
diff --git a/knip.jsonc b/knip.jsonc
index e6c64bc5..16ae6569 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -73,7 +73,7 @@
       "entry": [
         "src/{index,constants}.ts",
         "src/helpers/vite.ts",
-        "src/adapters/{build,cac,cli,dev,embedded}.ts",
+        "src/adapters/{build,cac,cli,dev,embedded,handler}.ts",
         "src/adapters/mcp/index.ts",
         "src/client/index.ts",
         "src/node/index.ts",
diff --git a/packages/devframe/package.json b/packages/devframe/package.json
index 7e352071..5a290c6f 100644
--- a/packages/devframe/package.json
+++ b/packages/devframe/package.json
@@ -28,6 +28,7 @@
     "./adapters/mcp": "./dist/adapters/mcp.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
+    "./handler": "./dist/adapters/handler.mjs",
     "./helpers/vite": "./dist/helpers/vite.mjs",
     "./node": "./dist/node/index.mjs",
     "./node/auth": "./dist/node/auth.mjs",
diff --git a/packages/devframe/src/adapters/__tests__/dev.test.ts b/packages/devframe/src/adapters/__tests__/dev.test.ts
index 416b05a3..bca0fdb2 100644
--- a/packages/devframe/src/adapters/__tests__/dev.test.ts
+++ b/packages/devframe/src/adapters/__tests__/dev.test.ts
@@ -19,7 +19,7 @@ vi.mock('devframe/utils/open', () => ({ open: vi.fn(async () => {}) }))
 function connectWsClient(host: string, port: number, authToken?: string) {
   return createRpcClient<DevframeRpcServerFunctions, DevframeRpcClientFunctions>(
     {} as DevframeRpcClientFunctions,
-    { channel: createWsRpcChannel({ url: `ws://${host}:${port}/__devframe_ws`, authToken }) },
+    { channel: createWsRpcChannel({ url: `ws://${host}:${port}/__ws`, authToken }) },
   )
 }
 
@@ -64,7 +64,7 @@ describe('adapters/dev', () => {
       const meta = await res.json()
       // Proxy-safe: the WS endpoint is advertised as a same-origin route
       // relative to `__connection.json`, never a baked-in host/port.
-      expect(meta).toEqual({ backend: 'websocket', websocket: { path: '__devframe_ws' } })
+      expect(meta).toEqual({ backend: 'websocket', websocket: { path: '__ws' } })
     }
     finally {
       await handle.close()
@@ -129,7 +129,7 @@ describe('adapters/dev', () => {
 
     try {
       // Connects on the bound route.
-      const ok = new WebSocket(`ws://${host}:${port}/__devframe_ws`)
+      const ok = new WebSocket(`ws://${host}:${port}/__ws`)
       await expect(new Promise((resolve, reject) => {
         ok.on('open', () => resolve('open'))
         ok.on('error', reject)
@@ -205,11 +205,11 @@ describe('adapters/dev', () => {
       const meta = await (await fetch(`http://${host}:${port}/__connection.json`)).json()
       expect(meta).toEqual({
         backend: 'websocket',
-        websocket: { port: wsPort, path: '__devframe_ws' },
+        websocket: { port: wsPort, path: '__ws' },
       })
 
       // The socket is reachable on its own port, rooted at `/<route>`.
-      const ok = new WebSocket(`ws://${host}:${wsPort}/__devframe_ws`)
+      const ok = new WebSocket(`ws://${host}:${wsPort}/__ws`)
       await expect(new Promise((resolve, reject) => {
         ok.on('open', () => resolve('open'))
         ok.on('error', reject)
@@ -234,7 +234,7 @@ describe('adapters/dev', () => {
       homepage: 'https://example.test',
       description: 'Test devframe.',
       setup: () => {},
-      cli: { ws: { url: 'wss://devtools.example.com/relay/__devframe_ws' } },
+      cli: { ws: { url: 'wss://devtools.example.com/relay/__ws' } },
     })
     const host = '127.0.0.1'
     const port = await getPort({ port: 19860, host })
@@ -244,7 +244,7 @@ describe('adapters/dev', () => {
       const meta = await (await fetch(`http://${host}:${port}/__connection.json`)).json()
       expect(meta).toEqual({
         backend: 'websocket',
-        websocket: 'wss://devtools.example.com/relay/__devframe_ws',
+        websocket: 'wss://devtools.example.com/relay/__ws',
       })
     }
     finally {
@@ -276,7 +276,7 @@ describe('adapters/dev', () => {
       const res = await fetch(`http://${host}:${port}/__connection.json`)
       expect(res.ok).toBe(true)
       const meta = await res.json()
-      expect(meta).toEqual({ backend: 'websocket', websocket: { path: '__devframe_ws' } })
+      expect(meta).toEqual({ backend: 'websocket', websocket: { path: '__ws' } })
 
       // The SPA mount is absent — without a distDir, no static handler
       // is wired, so the basePath returns a 404 from h3 instead of an
@@ -559,7 +559,7 @@ describe('adapters/dev', () => {
     })
 
     try {
-      const ws = new WebSocket(`ws://${host}:${port}/__devframe_ws`)
+      const ws = new WebSocket(`ws://${host}:${port}/__ws`)
       await new Promise<void>((resolve, reject) => {
         ws.on('open', () => resolve())
         ws.on('error', reject)
diff --git a/packages/devframe/src/adapters/__tests__/handler.test.ts b/packages/devframe/src/adapters/__tests__/handler.test.ts
new file mode 100644
index 00000000..ce2bba98
--- /dev/null
+++ b/packages/devframe/src/adapters/__tests__/handler.test.ts
@@ -0,0 +1,344 @@
+import type { DevframeNodeContext, DevframeRpcClientFunctions, DevframeRpcServerFunctions } from '../../types'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createRpcClient } from 'devframe/rpc/client'
+import { createWsRpcChannel } from 'devframe/rpc/transports/ws-client'
+import { getPort } from 'get-port-please'
+import { describe, expect, it, vi } from 'vitest'
+import { WebSocket } from 'ws'
+import { getTempAuthCode } from '../../node/auth/state'
+import { defineDevframe } from '../../types/devframe'
+import { createHandler } from '../handler'
+
+const HANDSHAKE = { authToken: '', ua: 'test', origin: 'http://localhost' }
+
+function connectWsClient(url: string, authToken?: string) {
+  return createRpcClient<DevframeRpcServerFunctions, DevframeRpcClientFunctions>(
+    {} as DevframeRpcClientFunctions,
+    { channel: createWsRpcChannel({ url, authToken }) },
+  )
+}
+
+function makeTmpDist(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'devframe-handler-'))
+  writeFileSync(join(dir, 'index.html'), '<!doctype html><title>handler test</title>', 'utf-8')
+  return dir
+}
+
+function defineTestDef(id: string) {
+  return defineDevframe({
+    id,
+    name: 'Handler Test',
+    version: '0.0.0',
+    packageName: 'devframe-handler-test',
+    homepage: 'https://example.test',
+    description: 'Test devframe.',
+    setup: (ctx: DevframeNodeContext) => {
+      ctx.rpc.register({ name: 'test:probe', type: 'query', handler: () => 'ok' })
+    },
+  })
+}
+
+describe('adapters/handler', () => {
+  it('connectionMeta() before ready throws DF0054', () => {
+    const handler = createHandler(defineTestDef('handler-early'), { auth: false })
+    expect(() => handler.connectionMeta()).toThrow(/DF0054|finished initializing/)
+    return handler.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 handler = createHandler(defineTestDef('handler-test'), {
+      auth: false,
+      distDir,
+      host: '127.0.0.1',
+      ws: { port: wsPort },
+    })
+
+    try {
+      await handler.ready
+      // The advertised meta carries the side-car port with the unified route.
+      expect(handler.connectionMeta()).toEqual({
+        backend: 'websocket',
+        websocket: { port: wsPort, path: '__ws' },
+      })
+
+      // Hosted default base: /__<id>/.
+      const index = await handler.fetch(new Request('http://localhost:3000/__handler-test/'))
+      expect(index.status).toBe(200)
+      expect(await index.text()).toContain('handler test')
+
+      const metaRes = await handler.fetch(new Request('http://localhost:3000/__handler-test/__connection.json'))
+      expect(metaRes.status).toBe(200)
+      expect(await metaRes.json()).toEqual({
+        backend: 'websocket',
+        websocket: { port: wsPort, path: '__ws' },
+      })
+
+      // Outside the base — and inside it on a miss — the fetch surface 404s.
+      const outside = await handler.fetch(new Request('http://localhost:3000/app'))
+      expect(outside.status).toBe(404)
+
+      // RPC round-trips against the side-car.
+      const client = connectWsClient(`ws://127.0.0.1:${wsPort}/__ws`)
+      await expect(client.$call('test:probe' as any)).resolves.toBe('ok')
+      client.$close()
+    }
+    finally {
+      await handler.close()
+    }
+
+    // Teardown is real: the side-car no longer accepts connections.
+    const gone = new WebSocket(`ws://127.0.0.1:${wsPort}/__ws`)
+    await expect(new Promise((resolve, reject) => {
+      gone.on('open', () => reject(new Error('should not connect after close')))
+      gone.on('error', () => resolve('closed'))
+    })).resolves.toBe('closed')
+  })
+
+  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 handler = createHandler(defineTestDef('handler-auth'), {
+      host: '127.0.0.1',
+      ws: { port: wsPort },
+    })
+
+    try {
+      await handler.ready
+      // The banner waits for the public origin: unknown until a request
+      // arrives, then printed exactly once (the magic link points at the
+      // origin the handler is actually mounted on).
+      expect(spy).not.toHaveBeenCalled()
+      await handler.fetch(new Request('http://localhost:4321/__handler-auth/__connection.json'))
+      expect(spy).toHaveBeenCalledTimes(1)
+      expect(String(spy.mock.calls[0])).toContain('http://localhost:4321')
+      await handler.fetch(new Request('http://localhost:4321/__handler-auth/__connection.json'))
+      expect(spy).toHaveBeenCalledTimes(1)
+
+      const client = connectWsClient(`ws://127.0.0.1:${wsPort}/__ws`)
+      const handshake = await client.$call('anonymous:devframe:auth' as any, HANDSHAKE)
+      expect(handshake).toEqual({ isTrusted: false })
+      await expect(client.$call('test:probe' as any)).rejects.toThrow()
+
+      const code = getTempAuthCode()
+      const exchange = await client.$call('anonymous:devframe:auth:exchange' as any, { code, ua: 'test', origin: 'http://localhost' }) as { authToken: string | null }
+      expect(exchange.authToken).toBeTruthy()
+      await expect(client.$call('test:probe' as any)).resolves.toBe('ok')
+      client.$close()
+    }
+    finally {
+      spy.mockRestore()
+      await handler.close()
+    }
+  })
+
+  it('shared-server tier: nodeMiddleware + upgrade at <base>__ws on the host server', async () => {
+    const distDir = makeTmpDist()
+    const host = '127.0.0.1'
+    const port = await getPort({ port: 18130, host })
+
+    let handlerRef!: ReturnType<typeof createHandler>
+    const server = createServer((req, res) => {
+      // The middleware self-filters by base; everything else stays the
+      // host app's.
+      handlerRef.nodeMiddleware(req, res, () => {
+        res.statusCode = 418
+        res.end('host app')
+      })
+    })
+    handlerRef = createHandler(defineTestDef('handler-shared'), {
+      auth: false,
+      distDir,
+      server,
+    })
+    await new Promise<void>(resolve => server.listen(port, host, resolve))
+
+    try {
+      await handlerRef.ready
+      // Zero extra ports: the meta advertises a same-origin relative route,
+      // resolved against __connection.json's own URL.
+      expect(handlerRef.connectionMeta()).toEqual({
+        backend: 'websocket',
+        websocket: { path: '__ws' },
+      })
+
+      const index = await fetch(`http://${host}:${port}/__handler-shared/`)
+      expect(index.status).toBe(200)
+      expect(await index.text()).toContain('handler test')
+
+      const meta = await (await fetch(`http://${host}:${port}/__handler-shared/__connection.json`)).json()
+      expect(meta).toEqual({ backend: 'websocket', websocket: { path: '__ws' } })
+
+      // Outside the base, next() ran and the host app answered.
+      const outside = await fetch(`http://${host}:${port}/app`)
+      expect(outside.status).toBe(418)
+      expect(await outside.text()).toBe('host app')
+
+      // The WS upgrade is bound on the host server at <base>__ws.
+      const client = connectWsClient(`ws://${host}:${port}/__handler-shared/__ws`)
+      await expect(client.$call('test:probe' as any)).resolves.toBe('ok')
+      client.$close()
+
+      // Off-route upgrades are left alone for the host's own sockets to
+      // claim (never upgraded by devframe on a shared server).
+      const off = new WebSocket(`ws://${host}:${port}/other-socket`)
+      const offOpened = await new Promise<boolean>((resolve) => {
+        const timer = setTimeout(resolve, 300, false)
+        off.on('open', () => {
+          clearTimeout(timer)
+          resolve(true)
+        })
+        off.on('error', () => {
+          clearTimeout(timer)
+          resolve(false)
+        })
+      })
+      off.terminate()
+      expect(offOpened).toBe(false)
+    }
+    finally {
+      await handlerRef.close()
+      // Fire-and-forget teardown for the host-owned test server: the
+      // deliberately dangling off-route upgrade socket sits outside the
+      // http server's tracked connections, so a graceful close never
+      // settles. The handler already detached; the port frees on close.
+      server.close()
+      server.closeAllConnections()
+    }
+  })
+
+  it('ws.url tier: advertises the external endpoint verbatim, owns no transport', async () => {
+    const handler = createHandler(defineTestDef('handler-remote'), {
+      ws: { url: 'wss://devtools.example.com/relay/__ws' },
+    })
+
+    try {
+      await handler.ready
+      expect(handler.connectionMeta()).toEqual({
+        backend: 'websocket',
+        websocket: 'wss://devtools.example.com/relay/__ws',
+      })
+    }
+    finally {
+      await handler.close()
+    }
+  })
+
+  it('tunnel pattern: ws.url with a server binds locally, advertises the relay', async () => {
+    const host = '127.0.0.1'
+    const port = await getPort({ port: 18170, host })
+    let handlerRef!: ReturnType<typeof createHandler>
+    const server = createServer((req, res) => {
+      handlerRef.nodeMiddleware(req, res)
+    })
+    handlerRef = createHandler(defineTestDef('handler-tunnel'), {
+      auth: false,
+      server,
+      ws: { url: 'wss://devtools.example.com/relay/__ws' },
+    })
+    await new Promise<void>(resolve => server.listen(port, host, resolve))
+
+    try {
+      await handlerRef.ready
+      // The browser is told to dial the relay…
+      expect(handlerRef.connectionMeta().websocket).toBe('wss://devtools.example.com/relay/__ws')
+      // …while the local socket keeps serving (the relay's forward target).
+      const client = connectWsClient(`ws://${host}:${port}/__handler-tunnel/__ws`)
+      await expect(client.$call('test:probe' as any)).resolves.toBe('ok')
+      client.$close()
+    }
+    finally {
+      await handlerRef.close()
+      server.close()
+      server.closeAllConnections()
+    }
+  })
+
+  it('mcp: mounts <base>__mcp and advertises it in the meta', async () => {
+    const wsPort = await getPort({ port: 18140, host: '127.0.0.1' })
+    const handler = createHandler(defineTestDef('handler-mcp'), {
+      auth: false,
+      mcp: true,
+      ws: { port: wsPort },
+    })
+
+    try {
+      await handler.ready
+      expect(handler.connectionMeta().mcp).toEqual({ path: '__mcp' })
+      // The route is mounted: a bare GET is answered by the MCP transport
+      // (405 for a session-less GET), not the 404 an unmounted path gets.
+      const res = await handler.fetch(new Request('http://localhost:3000/__handler-mcp/__mcp', {
+        headers: { origin: 'http://localhost:3000' },
+      }))
+      expect(res.status).not.toBe(404)
+    }
+    finally {
+      await handler.close()
+    }
+  })
+
+  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 = createHandler(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort } })
+    const b = createHandler(def, { 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 = createHandler(def, { 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')
+        await c.ready
+        expect(c.connectionMeta()).toEqual({
+          backend: 'websocket',
+          websocket: { port: wsPort2, path: '__ws' },
+        })
+
+        // The replaced instance's side-car was closed.
+        await vi.waitFor(async () => {
+          const gone = new WebSocket(`ws://127.0.0.1:${wsPort}/__ws`)
+          await expect(new Promise((resolve, reject) => {
+            gone.on('open', () => reject(new Error('old side-car still accepting')))
+            gone.on('error', () => resolve('closed'))
+          })).resolves.toBe('closed')
+        })
+      }
+      finally {
+        warn.mockRestore()
+        await c.close()
+      }
+    }
+    finally {
+      await a.close()
+    }
+  })
+
+  it('bridge mode: without a distDir only meta + WS are served', async () => {
+    const wsPort = await getPort({ port: 18160, host: '127.0.0.1' })
+    const handler = createHandler(defineTestDef('handler-bridge'), {
+      auth: false,
+      ws: { port: wsPort },
+    })
+
+    try {
+      await handler.ready
+      const meta = await handler.fetch(new Request('http://localhost:3000/__handler-bridge/__connection.json'))
+      expect(meta.status).toBe(200)
+      // No SPA mount: the base itself is a miss, normalized to a bare 404.
+      const spa = await handler.fetch(new Request('http://localhost:3000/__handler-bridge/'))
+      expect(spa.status).toBe(404)
+      expect(await spa.text()).toBe('')
+    }
+    finally {
+      await handler.close()
+    }
+  })
+})
diff --git a/packages/devframe/src/adapters/handler-bun.ts b/packages/devframe/src/adapters/handler-bun.ts
new file mode 100644
index 00000000..1954df45
--- /dev/null
+++ b/packages/devframe/src/adapters/handler-bun.ts
@@ -0,0 +1,70 @@
+import type { WsOriginRegistry } from 'devframe/rpc/transports/ws-server'
+import type { ContextRpcServer } from '../node/rpc-core'
+import { createWsRpcPeerHooks, isAllowedOrigin } from 'devframe/rpc/transports/ws-server'
+
+export interface AttachBunWsTransportOptions {
+  /** Same contract as `WsRpcTransportOptions.allowedOrigins`. */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false
+}
+
+/**
+ * Structural view of the Bun `Bun.serve({ websocket })` handler object the
+ * crossws Bun adapter produces — typed loosely so devframe carries no
+ * dependency on Bun's own types.
+ */
+interface BunWsTierWebSocket {
+  open?: (ws: unknown) => unknown
+  message: (ws: unknown, message: unknown) => unknown
+  close?: (ws: unknown, code?: number, reason?: string) => unknown
+  drain?: (ws: unknown) => unknown
+}
+
+export interface BunWsTier {
+  /** Complete a WS upgrade request — `Bun.serve`'s server as 2nd argument. */
+  handleUpgrade: (request: Request, server: unknown) => Promise<Response | undefined>
+  /** The handlers to spread into `Bun.serve({ websocket })`. */
+  websocket: BunWsTierWebSocket
+  close: () => Promise<void>
+}
+
+/**
+ * The Bun fetch-upgrade WebSocket tier for `createHandler` — the same RPC
+ * peer wiring as `attachWsRpcTransport`, driven by crossws's Bun adapter so
+ * upgrades complete through `fetch(request, server)` on the app's own
+ * origin, with no side-car server. Loaded dynamically so the Bun adapter
+ * never enters a Node-only bundle path.
+ */
+export async function attachBunWsTransport(
+  core: ContextRpcServer,
+  options: AttachBunWsTransportOptions = {},
+): Promise<BunWsTier> {
+  const { default: bunAdapter } = await import('crossws/adapters/bun')
+  const { allowedOrigins } = options
+
+  const ws = bunAdapter({
+    hooks: {
+      ...createWsRpcPeerHooks(core.rpcGroup, {
+        onConnected: core.onConnected,
+        onDisconnected: core.onDisconnected,
+      }),
+      // The same origin policy `routeUpgrades` applies for the Node
+      // transport, enforced at the upgrade hook since Bun upgrades arrive
+      // as fetch requests rather than `upgrade` socket events.
+      upgrade(request) {
+        const origin = request.headers.get('origin') ?? undefined
+        const allowed = allowedOrigins && !Array.isArray(allowedOrigins)
+          ? (allowedOrigins as WsOriginRegistry).isAllowed(origin)
+          : isAllowedOrigin(origin, (allowedOrigins as readonly string[] | false | undefined) || [])
+        if (allowedOrigins !== false && !allowed)
+          return new Response('Forbidden', { status: 403 })
+      },
+    },
+  })
+
+  return {
+    handleUpgrade: (request, server) =>
+      ws.handleUpgrade(request, server as Parameters<typeof ws.handleUpgrade>[1]),
+    websocket: ws.websocket as unknown as BunWsTierWebSocket,
+    close: () => ws.close(),
+  }
+}
diff --git a/packages/devframe/src/adapters/handler.ts b/packages/devframe/src/adapters/handler.ts
new file mode 100644
index 00000000..dc418dbd
--- /dev/null
+++ b/packages/devframe/src/adapters/handler.ts
@@ -0,0 +1,511 @@
+import type { WsOriginRegistry } from 'devframe/rpc/transports/ws-server'
+import type { ConnectionMeta, DevframeNodeContext } from 'devframe/types'
+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 { DevframeDefinition, DevframeSetupInfo, DevframeWsOptions, McpRouteOptions } from '../types/devframe'
+import type { BunWsTier } from './handler-bun'
+import process from 'node:process'
+import { mountStaticHandler } from 'devframe/utils/serve-static'
+import { H3, toNodeHandler } from 'h3'
+import { resolve } from 'pathe'
+import { joinURL, withLeadingSlash, withoutLeadingSlash, withoutTrailingSlash } from 'ufo'
+import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_WS_ROUTE } from '../constants'
+import { createHostContext } from '../node/context'
+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 { resolveDevServerPort, resolveMcpConnectionMeta } from './dev'
+
+export interface CreateHandlerOptions {
+  /**
+   * 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.
+   */
+  base?: string
+  /**
+   * Override `def.cli?.distDir`. When neither is set the handler runs in
+   * **bridge mode** — only `__connection.json`, the WS endpoint, and the MCP
+   * route (when enabled) are served; the SPA is hosted elsewhere.
+   */
+  distDir?: string
+  /**
+   * Share the host's `node:http` server for the WebSocket RPC endpoint: the
+   * upgrade listener binds to `<base>__ws` on this server, so no extra port
+   * is needed and the socket follows the app through proxies/HTTPS. When
+   * omitted (and no `ws.url`/`ws.port` is given), an **eager side-car**
+   * WebSocket server starts on its own port at handler creation. Under Bun,
+   * the default is the fetch-upgrade tier instead — no side-car; pass the
+   * `Bun.serve` server as `fetch`'s second argument and wire
+   * {@link DevframeHandler.websocket}.
+   */
+  server?: NodeHttpServer
+  /**
+   * Explicit control over how the browser reaches the RPC WebSocket —
+   * advertised in `__connection.json`. Precedence `url` > `port` > `route`
+   * (see {@link DevframeWsOptions}). `url` controls the *advertisement*
+   * only: the browser dials it verbatim (a tunnel/relay). The local
+   * binding still follows `server`/`ws.port` when given — the tunnel
+   * pattern, where the relay forwards to the locally-bound socket — and
+   * when neither is given, the handler starts **no transport of its own**
+   * (run `startHttpAndWs({ context, server, path })` against
+   * {@link DevframeHandler.context} to serve RPC from your own server).
+   */
+  ws?: DevframeWsOptions
+  /**
+   * Bind host for a side-car WebSocket server (default: `def.cli?.host ??
+   * 'localhost'`). Irrelevant for the `server` / `ws.url` / Bun tiers.
+   */
+  host?: string
+  /**
+   * Authentication for the RPC endpoint. A handler mounted inside an app
+   * server is reachable by anything that can open its socket, so it **gates
+   * by default**: when unset (or `true`), devframe's interactive OTP handler
+   * is wired and its code/link banner prints once the public origin is known
+   * (derived from the first request, or `origin`). Pass a
+   * {@link DevframeAuthHandler} for a custom scheme, or `false` to opt out
+   * for a single-user localhost setup that owns the trust boundary another
+   * way. Ignored for the `ws.url` tier — the server behind that URL owns auth.
+   */
+  auth?: boolean | DevframeAuthHandler
+  /**
+   * Expose a route-based MCP server (Streamable-HTTP) at `<base>__mcp` and
+   * advertise it in `__connection.json`. Overrides `def.cli?.mcp`;
+   * `undefined` falls through to it. See {@link McpRouteOptions}.
+   */
+  mcp?: boolean | McpRouteOptions
+  /**
+   * Memoize the handler on `globalThis` under this key. Dev servers that
+   * re-evaluate modules on the fly (Next.js, Nitro, SvelteKit HMR) re-run
+   * `createHandler` on every reload — without a key each run would leak an
+   * eager side-car WebSocket server. With a key, a re-run returns the live
+   * instance; if the options changed, the old instance is closed and
+   * replaced (reported as `DF0053`).
+   */
+  key?: string
+  /**
+   * Public origin the host app is reachable at (e.g. `http://localhost:3000`).
+   * When omitted, it is derived lazily from the first request the handler
+   * serves — used for the auth banner's magic link and absolute dock URLs.
+   */
+  origin?: string
+  /** Parsed flag bag forwarded to `def.setup(ctx, { flags })`. */
+  flags?: Record<string, unknown>
+  /**
+   * Extra origins to accept on the WS upgrade beyond the loopback default.
+   * Add your LAN/tunnel origin here when reaching the tool from another
+   * host. Pass `false` to disable origin checking entirely (not
+   * recommended). Default: loopback-only.
+   */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false
+}
+
+/**
+ * Bun `Bun.serve({ websocket })` handlers, delegating to the handler's
+ * WebSocket transport. Only active under Bun (the fetch-upgrade tier);
+ * inert no-ops elsewhere. Typed structurally so devframe carries no
+ * dependency on Bun's types — cast to Bun's `WebSocketHandler` at the
+ * `Bun.serve` call site if your host file typechecks against `bun-types`.
+ */
+export interface DevframeHandlerWebSocket {
+  open: (ws: unknown) => void
+  message: (ws: unknown, message: unknown) => void
+  close: (ws: unknown, code?: number, reason?: string) => void
+  drain: (ws: unknown) => void
+}
+
+export interface DevframeHandler {
+  /**
+   * Web-standard request handler — mount it on a catch-all route under
+   * {@link CreateHandlerOptions.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
+   * upgraded request resolves to `undefined` per Bun's contract, typed as
+   * `Response` for drop-in route-handler compatibility).
+   */
+  fetch: (request: Request, server?: unknown) => Promise<Response>
+  /**
+   * Connect/Express-style middleware over the same surface — for
+   * `viteServer.middlewares.use(handler.nodeMiddleware)` or any other
+   * node middleware stack. Mount it un-prefixed: paths outside the base
+   * call `next()` so the rest of the stack keeps working.
+   */
+  nodeMiddleware: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void
+  /** See {@link DevframeHandlerWebSocket}. */
+  websocket: DevframeHandlerWebSocket
+  /**
+   * Resolves once `def.setup` has run and the WebSocket binding is live.
+   * `fetch`/`nodeMiddleware` await it internally, so hosts never race
+   * initialization — await it yourself only when you need the timing.
+   */
+  ready: Promise<void>
+  /** The node context, once initialized — for advanced wiring (own WS transport, extra RPC registration). */
+  context: Promise<DevframeNodeContext>
+  /**
+   * The `ConnectionMeta` this handler serves at `<base>__connection.json`.
+   * Only readable after initialization (`DF0054` otherwise).
+   */
+  connectionMeta: () => ConnectionMeta
+  /** Tear down: WS transport/side-car, MCP sessions, memo-registry entry. */
+  close: () => Promise<void>
+}
+
+interface HandlerRegistryEntry {
+  hash: string
+  handler: DevframeHandler
+}
+
+const REGISTRY_KEY = Symbol.for('devframe:handler-registry')
+
+function handlerRegistry(): Map<string, HandlerRegistryEntry> {
+  const holder = globalThis as { [REGISTRY_KEY]?: Map<string, HandlerRegistryEntry> }
+  holder[REGISTRY_KEY] ??= new Map()
+  return holder[REGISTRY_KEY]
+}
+
+/**
+ * Fingerprint the option surface that changes a handler's observable
+ * behavior, for `key` memoization. Non-serializable options (a custom auth
+ * handler, the shared server) participate as identity markers only — a new
+ * object on every module re-evaluation would defeat memoization, which is
+ * exactly the scenario `key` exists for.
+ */
+function optionsHash(def: DevframeDefinition, options: CreateHandlerOptions): string {
+  return JSON.stringify({
+    id: def.id,
+    base: options.base,
+    distDir: options.distDir,
+    host: options.host,
+    origin: options.origin,
+    ws: options.ws,
+    server: options.server != null,
+    auth: typeof options.auth === 'object' ? 'custom' : options.auth,
+    mcp: options.mcp,
+    allowedOrigins: Array.isArray(options.allowedOrigins) ? options.allowedOrigins : typeof options.allowedOrigins,
+    cwd: process.cwd(),
+  })
+}
+
+/** Compare two URL paths ignoring a trailing slash. */
+function samePath(a: string, b: string): boolean {
+  return withoutTrailingSlash(a) === withoutTrailingSlash(b)
+}
+
+/**
+ * Serve a devframe through one framework-agnostic, web-standard handler —
+ * the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the
+ * auth gate, and the optional MCP route, all under a single mount base.
+ * Mount `fetch` on any framework's catch-all route (or `nodeMiddleware` on
+ * a connect stack) and the devframe is live inside that app.
+ *
+ * The factory is synchronous and kicks off initialization eagerly;
+ * `fetch`/`nodeMiddleware` await readiness internally. How the WebSocket is
+ * bound resolves in precedence order — `ws.url` (external, advertise-only)
+ * > `ws.port` (explicit side-car) > `server` (shared upgrade at
+ * `<base>__ws`) > Bun fetch-upgrade (under Bun) > an eager side-car on a
+ * free port — and `__connection.json` reflects whichever tier is active.
+ */
+export function createHandler(
+  def: DevframeDefinition,
+  options: CreateHandlerOptions = {},
+): DevframeHandler {
+  if (options.key) {
+    const registry = handlerRegistry()
+    const hash = optionsHash(def, options)
+    const existing = registry.get(options.key)
+    if (existing) {
+      if (existing.hash === hash)
+        return existing.handler
+      diagnostics.DF0053({ key: options.key, id: def.id })
+      void existing.handler.close().catch(() => {})
+    }
+    const handler = instantiateHandler(def, options)
+    registry.set(options.key, { hash, handler })
+    return handler
+  }
+  return instantiateHandler(def, options)
+}
+
+function instantiateHandler(
+  def: DevframeDefinition,
+  options: CreateHandlerOptions,
+): DevframeHandler {
+  const base = options.base ? normalizeBasePath(options.base) : resolveBasePath(def, 'hosted')
+  const baseNoSlash = withoutTrailingSlash(base)
+  const distDir = options.distDir ?? def.cli?.distDir
+  const app = new H3()
+
+  // The public origin is often unknowable at creation (the host app owns the
+  // listener) — derive it from the first request and let the auth banner
+  // wait for it, unless the caller pinned one.
+  let resolvedOrigin: string | undefined = options.origin
+  let authHandler: DevframeAuthHandler | undefined
+  let bannerPrinted = false
+  function maybePrintBanner(): void {
+    if (bannerPrinted || !authHandler || !resolvedOrigin)
+      return
+    bannerPrinted = true
+    authHandler.printBanner()
+  }
+  function noteOrigin(origin: string): void {
+    resolvedOrigin ??= origin
+    maybePrintBanner()
+  }
+
+  let meta: ConnectionMeta | undefined
+  let started: StartedServer | undefined
+  let bunTier: BunWsTier | undefined
+  let bunUpgradePath: string | undefined
+  let mcpDispose: (() => Promise<void>) | undefined
+  let ctx: DevframeNodeContext
+
+  async function init(): Promise<void> {
+    const host = createH3DevframeHost({
+      origin: () => resolvedOrigin ?? 'http://localhost',
+      appName: def.id,
+      mount: (mountBase, dir) => {
+        mountStaticHandler(app, mountBase, dir)
+      },
+    })
+    ctx = await createHostContext({
+      cwd: process.cwd(),
+      mode: 'dev',
+      host,
+    })
+    const setupInfo: DevframeSetupInfo = { flags: options.flags ?? {} }
+    await def.setup(ctx, setupInfo)
+
+    // Route-based MCP server (opt-in). Mounted before the SPA static
+    // catch-all so the exact `<base>__mcp` route wins, and advertised in
+    // `__connection.json`. The MCP SDK stays an optional peer — its code is
+    // only pulled in (dynamically) when the route is enabled.
+    const mcpOption = options.mcp ?? def.cli?.mcp
+    const mcpMeta = resolveMcpConnectionMeta(def, mcpOption)
+    if (mcpMeta) {
+      const mcpConfig = mcpOption === true || mcpOption === undefined ? {} : mcpOption as McpRouteOptions
+      const mcpPath = joinURL(base, mcpMeta.path)
+      let mountMcpHttp: typeof import('./mcp/http').mountMcpHttp
+      try {
+        ;({ mountMcpHttp } = await import('./mcp/http'))
+      }
+      catch (error) {
+        const reason = error instanceof Error ? error.message : String(error)
+        throw diagnostics.DF0017({ transport: 'http', reason, cause: error })
+      }
+      const mounted = mountMcpHttp(app, ctx, mcpPath, {
+        serverName: `${def.id} (devframe)`,
+        serverVersion: def.version ?? '0.0.0',
+        exposeSharedState: true,
+        allowedOrigins: mcpConfig.allowedOrigins,
+      })
+      mcpDispose = mounted.dispose
+    }
+
+    // WebSocket binding resolution — explicit `ws.port` side-car > shared
+    // `server` > Bun fetch-upgrade > eager auto side-car; `ws.url`, when
+    // set, overrides only the *advertised* endpoint (the tunnel pattern:
+    // the relay forwards to whatever local binding the rest configured),
+    // and suppresses the default binding entirely when no explicit
+    // `server`/`ws.port` is given (an external server owns the transport).
+    const ws = options.ws ?? def.cli?.ws ?? {}
+    const route = withoutLeadingSlash(ws.route ?? DEVFRAME_WS_ROUTE)
+
+    // Auth resolution mirrors `createDevServer`: gate by default, explicit
+    // `false` opts out, a handler object installs a custom scheme.
+    const authOption = options.auth !== undefined ? options.auth : def.cli?.auth
+    let resolvedAuth: boolean | DevframeAuthHandler
+    if (authOption === false) {
+      resolvedAuth = false
+    }
+    else if (typeof authOption === 'object') {
+      authHandler = authOption
+      resolvedAuth = authOption
+    }
+    else {
+      authHandler = createInteractiveAuth(ctx)
+      resolvedAuth = authHandler
+    }
+
+    let websocketMeta: ConnectionMeta['websocket']
+    if (ws.port != null) {
+      // Explicit side-car port.
+      const sidecarHost = options.host ?? def.cli?.host ?? 'localhost'
+      started = await startHttpAndWs({
+        context: ctx,
+        host: sidecarHost,
+        port: ws.port,
+        path: withLeadingSlash(route),
+        auth: resolvedAuth,
+        allowedOrigins: options.allowedOrigins,
+      })
+      websocketMeta = { port: started.port, path: route }
+    }
+    else if (options.server) {
+      // Shared upgrade on the host's own server at `<base><route>` — zero
+      // extra ports, proxy/HTTPS friendly.
+      started = await startHttpAndWs({
+        context: ctx,
+        port: 0,
+        server: options.server,
+        path: joinURL(base, route),
+        auth: resolvedAuth,
+        allowedOrigins: options.allowedOrigins,
+      })
+      websocketMeta = { path: route }
+    }
+    else if (ws.url) {
+      // Advertise-only: an external server owns transport and auth.
+      authHandler = undefined
+      websocketMeta = ws.url
+    }
+    else if (typeof (globalThis as any).Bun === 'undefined') {
+      // Eager auto side-car on a free port — the default when no host
+      // server is shared (and we're not under Bun).
+      const sidecarHost = options.host ?? def.cli?.host ?? 'localhost'
+      const port = await resolveDevServerPort(def, { host: sidecarHost })
+      started = await startHttpAndWs({
+        context: ctx,
+        host: sidecarHost,
+        port,
+        path: withLeadingSlash(route),
+        auth: resolvedAuth,
+        allowedOrigins: options.allowedOrigins,
+      })
+      websocketMeta = { port: started.port, path: route }
+    }
+    else {
+      // Bun fetch-upgrade — same-origin upgrades completed through
+      // `fetch(request, server)`, handlers exposed via `websocket`.
+      const { attachBunWsTransport } = await import('./handler-bun')
+      const { createContextRpcServer } = await import('../node/rpc-core')
+      const core = createContextRpcServer({ context: ctx, auth: resolvedAuth })
+      bunTier = await attachBunWsTransport(core, { allowedOrigins: options.allowedOrigins })
+      bunUpgradePath = joinURL(base, route)
+      websocketMeta = { path: route }
+    }
+    // The tunnel pattern: `ws.url` overrides the advertisement while the
+    // local binding above keeps serving (the relay forwards to it).
+    if (ws.url)
+      websocketMeta = ws.url
+
+    // Discovery meta before the SPA mount so its SPA-fallback can't swallow
+    // the route; both sit at the SPA root for relative `./__connection.json`
+    // fetches.
+    meta = {
+      backend: 'websocket',
+      websocket: websocketMeta,
+      ...(mcpMeta ? { mcp: mcpMeta } : {}),
+    }
+    app.use(joinURL(base, DEVFRAME_CONNECTION_META_FILENAME), () => meta)
+
+    if (distDir)
+      mountStaticHandler(app, base, resolve(distDir))
+
+    // A pinned origin means the banner needn't wait for a first request.
+    maybePrintBanner()
+  }
+
+  const initPromise = init()
+  // Surface init failures through `ready`/`fetch`, never as an unhandled
+  // rejection from the eager kick-off.
+  initPromise.catch(() => {})
+  const contextPromise = initPromise.then(() => ctx)
+  contextPromise.catch(() => {})
+
+  async function fetch(request: Request, server?: unknown): Promise<Response> {
+    await initPromise
+    const url = new URL(request.url)
+    noteOrigin(url.origin)
+    if (bunTier && samePath(url.pathname, bunUpgradePath!)
+      && request.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+      if (!server) {
+        return new Response(
+          'Upgrade Required: pass the Bun server as the second argument to handler.fetch(request, server)',
+          { status: 426 },
+        )
+      }
+      // An upgraded request resolves to `undefined` per Bun's contract; the
+      // cast keeps `fetch` drop-in assignable to route handlers that expect
+      // a `Response`.
+      return await bunTier.handleUpgrade(request, server) as Response
+    }
+    const response = await app.fetch(request)
+    // Normalize a miss to a bare 404: an unmounted path falls through to
+    // h3's default JSON-error handler, but for an asset host a body-less
+    // 404 is cleaner and matches a plain static server.
+    if (response.status === 404)
+      return new Response(null, { status: 404 })
+    return response
+  }
+
+  const nodeHandler = toNodeHandler(app)
+  function nodeMiddleware(req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void): void {
+    let pathname = req.url ?? '/'
+    try {
+      pathname = new URL(pathname, 'http://localhost').pathname
+    }
+    catch {}
+    if (!(samePath(pathname, baseNoSlash) || pathname.startsWith(base))) {
+      if (next) {
+        next()
+        return
+      }
+      res.statusCode = 404
+      res.end()
+      return
+    }
+    void initPromise
+      .then(() => {
+        const host = req.headers.host
+        if (host) {
+          const encrypted = (req.socket as { encrypted?: boolean }).encrypted
+          noteOrigin(`${encrypted ? 'https' : 'http'}://${host}`)
+        }
+        return nodeHandler(req, res)
+      })
+      .catch((err: unknown) => {
+        if (next) {
+          next(err)
+          return
+        }
+        res.statusCode = 500
+        res.end()
+      })
+  }
+
+  const websocket: DevframeHandlerWebSocket = {
+    open: ws => void bunTier?.websocket.open?.(ws),
+    message: (ws, message) => void bunTier?.websocket.message(ws, message),
+    close: (ws, code, reason) => void bunTier?.websocket.close?.(ws, code, reason),
+    drain: ws => void bunTier?.websocket.drain?.(ws),
+  }
+
+  const handler: DevframeHandler = {
+    fetch,
+    nodeMiddleware,
+    websocket,
+    ready: initPromise,
+    context: contextPromise,
+    connectionMeta: () => {
+      if (!meta)
+        throw diagnostics.DF0054({ id: def.id })
+      return meta
+    },
+    close: async () => {
+      if (options.key) {
+        const registry = handlerRegistry()
+        if (registry.get(options.key)?.handler === handler)
+          registry.delete(options.key)
+      }
+      await initPromise.catch(() => {})
+      await mcpDispose?.()
+      await started?.close()
+      await bunTier?.close()
+    },
+  }
+  return handler
+}
diff --git a/packages/devframe/src/client/rpc-ws-status.test.ts b/packages/devframe/src/client/rpc-ws-status.test.ts
index 30778623..939ef31e 100644
--- a/packages/devframe/src/client/rpc-ws-status.test.ts
+++ b/packages/devframe/src/client/rpc-ws-status.test.ts
@@ -56,7 +56,7 @@ class FakeWebSocket {
 
 const connectionMeta: ConnectionMeta = {
   backend: 'websocket',
-  websocket: { path: '__devframe_ws' },
+  websocket: { path: '__ws' },
 }
 
 function setup(callTimeout?: number) {
diff --git a/packages/devframe/src/client/rpc-ws.test.ts b/packages/devframe/src/client/rpc-ws.test.ts
index b636470c..f5c5ac58 100644
--- a/packages/devframe/src/client/rpc-ws.test.ts
+++ b/packages/devframe/src/client/rpc-ws.test.ts
@@ -27,39 +27,39 @@ const extensionLoc: WsUrlLocation = {
 describe('resolveWsUrl', () => {
   it('resolves a relative path against the meta base, same-origin', () => {
     const url = resolveWsUrl(
-      { path: '__devframe_ws' },
+      { path: '__ws' },
       'http://localhost:5173/__foo/__connection.json',
       httpLoc,
     )
-    expect(url).toBe('ws://localhost:5173/__foo/__devframe_ws')
+    expect(url).toBe('ws://localhost:5173/__foo/__ws')
   })
 
   it('follows the page origin through a proxy (host + subpath + tls)', () => {
     // The server has no idea about the proxy's host — the client reuses its own.
     const url = resolveWsUrl(
-      { path: '__devframe_ws' },
+      { path: '__ws' },
       'https://devtools.example.com/app/__foo/__connection.json',
       httpsProxyLoc,
     )
-    expect(url).toBe('wss://devtools.example.com/app/__foo/__devframe_ws')
+    expect(url).toBe('wss://devtools.example.com/app/__foo/__ws')
   })
 
   it('roots an explicit-port endpoint at the page hostname (side-car)', () => {
     const url = resolveWsUrl(
-      { port: 9777, path: '/__devframe_ws' },
+      { port: 9777, path: '/__ws' },
       'http://localhost:5173/__hub/__connection.json',
       httpLoc,
     )
-    expect(url).toBe('ws://localhost:9777/__devframe_ws')
+    expect(url).toBe('ws://localhost:9777/__ws')
   })
 
   it('honors an explicit host override', () => {
     const url = resolveWsUrl(
-      { host: 'inner:1234', path: '/__devframe_ws' },
+      { host: 'inner:1234', path: '/__ws' },
       'http://localhost:5173/__connection.json',
       httpLoc,
     )
-    expect(url).toBe('ws://inner:1234/__devframe_ws')
+    expect(url).toBe('ws://inner:1234/__ws')
   })
 
   it('keeps the legacy numeric-port form on the metadata hostname', () => {
diff --git a/packages/devframe/src/constants.ts b/packages/devframe/src/constants.ts
index fd3d32c1..c970dc51 100644
--- a/packages/devframe/src/constants.ts
+++ b/packages/devframe/src/constants.ts
@@ -1,8 +1,4 @@
 // Devframe runtime routes and static output conventions.
-export const DEVFRAME_MOUNT_PATH = '/__devframe/'
-export const DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH = '/__devframe'
-export const DEVFRAME_DIRNAME = '__devframe'
-
 export const DEVFRAME_CONNECTION_META_FILENAME = '__connection.json'
 
 /**
@@ -19,7 +15,7 @@ export const DEVFRAME_CONNECTION_KEY = '__DEVFRAME_CONNECTION__'
  * both HTTP and WS, and a host server (Vite, etc.) can mount the WS upgrade
  * handler here without colliding with its own routes (HMR, asset serving).
  */
-export const DEVFRAME_WS_ROUTE = '__devframe_ws'
+export const DEVFRAME_WS_ROUTE = '__ws'
 
 /**
  * Route the Streamable-HTTP MCP endpoint is bound to, relative to a
diff --git a/packages/devframe/src/helpers/__tests__/vite.test.ts b/packages/devframe/src/helpers/__tests__/vite.test.ts
index dae89fa6..1ca5fed2 100644
--- a/packages/devframe/src/helpers/__tests__/vite.test.ts
+++ b/packages/devframe/src/helpers/__tests__/vite.test.ts
@@ -75,7 +75,7 @@ describe('viteDevBridge (bridge mode mcp)', () => {
     expect(metaHandler).toBeDefined()
     const meta = await readJsonMiddleware(metaHandler)
     expect(meta.backend).toBe('websocket')
-    expect(meta.websocket).toEqual({ port, path: '/__devframe_ws' })
+    expect(meta.websocket).toEqual({ port, path: '/__ws' })
     expect(meta.mcp).toEqual({ port, path: '/__mcp' })
 
     // The advertised endpoint is live: a real MCP client presenting a loopback
@@ -120,7 +120,7 @@ describe('viteDevBridge (auth default)', () => {
   /** Handshake result on a fresh, unauthenticated WS connection. */
   async function handshakeIsTrusted(port: number): Promise<boolean> {
     const rpc = createRpcClient<any, any>({}, {
-      channel: createWsRpcChannel({ url: `ws://127.0.0.1:${port}/__devframe_ws` }),
+      channel: createWsRpcChannel({ url: `ws://127.0.0.1:${port}/__ws` }),
     })
     try {
       const res = await rpc.$call('anonymous:devframe:auth', { authToken: '', ua: 'test', origin: 'http://localhost' }) as { isTrusted: boolean }
diff --git a/packages/devframe/src/helpers/vite.ts b/packages/devframe/src/helpers/vite.ts
index 68f64f4a..ab951093 100644
--- a/packages/devframe/src/helpers/vite.ts
+++ b/packages/devframe/src/helpers/vite.ts
@@ -151,7 +151,7 @@ export function viteDevBridge(d: DevframeDefinition, options: ViteDevBridgeOptio
 
       // The side-car listens on its own port, so the browser must target that
       // port explicitly (it can't reach the WS on Vite's origin). The route is
-      // `/__devframe_ws` — the bridge `createDevServer` mounts the SPA at `/`, so its WS
+      // `/__ws` — the bridge `createDevServer` mounts the SPA at `/`, so its WS
       // upgrade handler is bound there. The MCP route (when enabled) lives on
       // the same side-car origin, advertised with the same explicit port.
       const mcpMeta = resolveMcpConnectionMeta(d, options.mcp, port)
diff --git a/packages/devframe/src/node/diagnostics.ts b/packages/devframe/src/node/diagnostics.ts
index f16ed74a..449f923f 100644
--- a/packages/devframe/src/node/diagnostics.ts
+++ b/packages/devframe/src/node/diagnostics.ts
@@ -116,5 +116,13 @@ export const diagnostics = defineDiagnostics({
       why: (p: { host: string, port: number, reason: string }) => `Failed to listen on ${p.host}:${p.port}: ${p.reason}`,
       fix: 'The port is likely already taken by another process (often a previous devframe instance). Free it, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `devMiddleware.port` on `viteDevBridge`. The original node error is available as `error.cause`.',
     },
+    DF0053: {
+      why: (p: { key: string, id: string }) => `createHandler("${p.id}") replaced the live handler memoized under key "${p.key}": its options changed since the previous call.`,
+      fix: 'A dev-time module reload re-ran createHandler with different options, so the old instance (and its side-car WebSocket server) was closed and a new one started. If this is unexpected, keep the options stable across reloads — or use distinct keys for genuinely different handlers.',
+    },
+    DF0054: {
+      why: (p: { id: string }) => `connectionMeta() was called before createHandler("${p.id}") finished initializing.`,
+      fix: 'Await `handler.ready` (or any `handler.fetch` call) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes.',
+    },
   },
 })
diff --git a/packages/devframe/src/node/host-h3.ts b/packages/devframe/src/node/host-h3.ts
index dcd39d40..90093c74 100644
--- a/packages/devframe/src/node/host-h3.ts
+++ b/packages/devframe/src/node/host-h3.ts
@@ -9,8 +9,10 @@ export interface CreateH3DevframeHostOptions {
   /**
    * Host the standalone server listens on, e.g. `http://localhost:9999`.
    * Consumed by `resolveOrigin` for dock entries that need an absolute URL.
+   * Pass a function for hosts that only learn their public origin later
+   * (e.g. `createHandler` derives it from the first incoming request).
    */
-  origin: string
+  origin: string | (() => string)
   /**
    * Register a static-file handler at `base` serving files from `distDir`.
    * Wired into the h3 app once the CLI adapter lands (commit 5). For now
@@ -43,7 +45,7 @@ export function createH3DevframeHost(options: CreateH3DevframeHostOptions): Devf
       return options.mount?.(base, distDir)
     },
     resolveOrigin() {
-      return options.origin
+      return typeof options.origin === 'function' ? options.origin() : options.origin
     },
     getStorageDir(scope) {
       const namespace = `.${options.appName}/devframe`
diff --git a/packages/devframe/src/rpc/transports/ws.test.ts b/packages/devframe/src/rpc/transports/ws.test.ts
index b4606146..b1f9176b 100644
--- a/packages/devframe/src/rpc/transports/ws.test.ts
+++ b/packages/devframe/src/rpc/transports/ws.test.ts
@@ -250,11 +250,11 @@ describe('devframe rpc', () => {
 
     const serverFunctions = { ping: () => 'pong' }
     const server = createRpcServer<Record<string, never>, typeof serverFunctions>(serverFunctions)
-    const { close } = attachWsRpcTransport(server, { server: httpServer, path: '/__devframe_ws' })
+    const { close } = attachWsRpcTransport(server, { server: httpServer, path: '/__ws' })
 
     try {
       const client = createRpcClient<typeof serverFunctions, Record<string, never>>({}, {
-        channel: createWsRpcChannel({ url: `ws://${HOST}:${PORT}/__devframe_ws` }),
+        channel: createWsRpcChannel({ url: `ws://${HOST}:${PORT}/__ws` }),
       })
       expect(await client.$call('ping')).toBe('pong')
 
diff --git a/packages/devframe/src/types/context.ts b/packages/devframe/src/types/context.ts
index 4a812bec..d49b304f 100644
--- a/packages/devframe/src/types/context.ts
+++ b/packages/devframe/src/types/context.ts
@@ -92,8 +92,8 @@ export interface DevframeNodeContext {
  */
 export interface ConnectionMetaWebsocket {
   /**
-   * Path to the WS endpoint. Relative paths (the default, e.g. `__devframe_ws`) are
-   * resolved against `__connection.json`'s location; absolute paths (`/__devframe_ws`)
+   * Path to the WS endpoint. Relative paths (the default, e.g. `__ws`) are
+   * resolved against `__connection.json`'s location; absolute paths (`/__ws`)
    * resolve against the page origin.
    */
   path?: string
diff --git a/packages/devframe/src/types/devframe.ts b/packages/devframe/src/types/devframe.ts
index 77dbde86..6b6bc77d 100644
--- a/packages/devframe/src/types/devframe.ts
+++ b/packages/devframe/src/types/devframe.ts
@@ -33,7 +33,7 @@ export type DevframeDuplicationStrategy = 'warn' | 'silent' | 'throw' | 'duplica
  *
  *   1. **Same server, different route** (default) — leave `port`/`url` unset.
  *      The socket shares the HTTP server's port and binds to `route`
- *      (`__devframe_ws`). The client connects to its own origin, so the link
+ *      (`__ws`). The client connects to its own origin, so the link
  *      survives a reverse proxy that rewrites the host/port/subpath.
  *
  *   2. **Different port** — set `port`. The socket binds on its own port on the
@@ -45,7 +45,7 @@ export type DevframeDuplicationStrategy = 'warn' | 'silent' | 'throw' | 'duplica
 export interface DevframeWsOptions {
   /**
    * Upgrade route segment the socket binds to and is advertised at, relative
-   * to the SPA base. Default: `__devframe_ws`.
+   * to the SPA base. Default: `__ws`.
    */
   route?: string
   /**
@@ -150,7 +150,7 @@ export interface DevframeCliOptions {
   distDir?: string
   /**
    * How the browser reaches the RPC WebSocket. Defaults to sharing the HTTP
-   * port on the `__devframe_ws` route. See {@link DevframeWsOptions} for the
+   * port on the `__ws` route. See {@link DevframeWsOptions} for the
    * different-port and remote-origin variants.
    */
   ws?: DevframeWsOptions
diff --git a/packages/devframe/tsdown.config.ts b/packages/devframe/tsdown.config.ts
index 57195d41..fd861cd3 100644
--- a/packages/devframe/tsdown.config.ts
+++ b/packages/devframe/tsdown.config.ts
@@ -106,6 +106,7 @@ const serverEntries = {
   'adapters/dev': 'src/adapters/dev.ts',
   'adapters/build': 'src/adapters/build.ts',
   'adapters/embedded': 'src/adapters/embedded.ts',
+  'adapters/handler': 'src/adapters/handler.ts',
   'adapters/mcp': 'src/adapters/mcp/index.ts',
   'cli/main': 'src/cli/main.ts',
   'helpers/vite': 'src/helpers/vite.ts',
diff --git a/packages/hub/src/client/remote.test.ts b/packages/hub/src/client/remote.test.ts
index effe14c8..c52b8b28 100644
--- a/packages/hub/src/client/remote.test.ts
+++ b/packages/hub/src/client/remote.test.ts
@@ -8,7 +8,7 @@ import {
 } from './remote'
 
 const connection: DevframeConnection = {
-  connectionMeta: { backend: 'websocket', websocket: { path: '__devframe_ws' } },
+  connectionMeta: { backend: 'websocket', websocket: { path: '__ws' } },
   metaBaseUrl: 'http://localhost:5173/__devtools/__connection.json',
   authToken: 'secret',
 }
@@ -19,7 +19,7 @@ describe('remote connection URLs', () => {
     expect(parseRemoteConnection(url)).toEqual({
       v: 1,
       backend: 'websocket',
-      websocket: 'ws://localhost:5173/__devtools/__devframe_ws',
+      websocket: 'ws://localhost:5173/__devtools/__ws',
       authToken: 'secret',
       origin: 'http://localhost:5173',
     })
@@ -39,7 +39,7 @@ describe('remote connection URLs', () => {
       {
         v: 1,
         backend: 'websocket',
-        websocket: 'ws://localhost:5173/__devtools/__devframe_ws',
+        websocket: 'ws://localhost:5173/__devtools/__ws',
         authToken: 'secret',
         origin: 'http://localhost:5173',
       },
@@ -66,7 +66,7 @@ describe('remote connection URLs', () => {
     const query = buildRemoteConnectionUrl('https://viewer.example/?tab=state#section', {
       v: 1,
       backend: 'websocket',
-      websocket: 'ws://localhost:5173/__devtools/__devframe_ws',
+      websocket: 'ws://localhost:5173/__devtools/__ws',
       authToken: 'secret',
       origin: 'http://localhost:5173',
     }, 'query')
diff --git a/packages/next/test/handler.test.ts b/packages/next/test/handler.test.ts
index 0ee5f47c..5d3f5b64 100644
--- a/packages/next/test/handler.test.ts
+++ b/packages/next/test/handler.test.ts
@@ -50,7 +50,7 @@ describe('createDevframeNextHandler', () => {
     const body = await meta.json() as { backend: string, websocket: { port: number, path: string } }
     expect(body.backend).toBe('websocket')
     expect(typeof body.websocket.port).toBe('number')
-    expect(body.websocket.path).toBe('/__devframe_ws')
+    expect(body.websocket.path).toBe('/__ws')
 
     // Unmounted base → bare 404.
     const miss = await handler.fetch(new Request(`${origin}/__other/x`))
diff --git a/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts
index 02968315..8426b32a 100644
--- a/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/devframe/constants.snapshot.d.ts
@@ -10,12 +10,9 @@ export declare const ANONYMOUS_RPC_PREFIX: string;
 export declare const DEVFRAME_AUTH_TOKEN_QUERY_PARAM: string;
 export declare const DEVFRAME_CONNECTION_KEY: string;
 export declare const DEVFRAME_CONNECTION_META_FILENAME: string;
-export declare const DEVFRAME_DIRNAME: string;
 export declare const DEVFRAME_DOCK_IMPORTS_FILENAME: string;
 export declare const DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID: string;
 export declare const DEVFRAME_MCP_ROUTE: string;
-export declare const DEVFRAME_MOUNT_PATH: string;
-export declare const DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH: string;
 export declare const DEVFRAME_OTP_URL_PARAM: string;
 export declare const DEVFRAME_RPC_DUMP_DIRNAME: string;
 export declare const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME: string;
diff --git a/tests/__snapshots__/tsnapi/devframe/constants.snapshot.js b/tests/__snapshots__/tsnapi/devframe/constants.snapshot.js
index 59c17ed9..c13e7ca8 100644
--- a/tests/__snapshots__/tsnapi/devframe/constants.snapshot.js
+++ b/tests/__snapshots__/tsnapi/devframe/constants.snapshot.js
@@ -10,12 +10,9 @@ export var ANONYMOUS_RPC_PREFIX /* const */
 export var DEVFRAME_AUTH_TOKEN_QUERY_PARAM /* const */
 export var DEVFRAME_CONNECTION_KEY /* const */
 export var DEVFRAME_CONNECTION_META_FILENAME /* const */
-export var DEVFRAME_DIRNAME /* const */
 export var DEVFRAME_DOCK_IMPORTS_FILENAME /* const */
 export var DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID /* const */
 export var DEVFRAME_MCP_ROUTE /* const */
-export var DEVFRAME_MOUNT_PATH /* const */
-export var DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH /* const */
 export var DEVFRAME_OTP_URL_PARAM /* const */
 export var DEVFRAME_RPC_DUMP_DIRNAME /* const */
 export var DEVFRAME_RPC_DUMP_MANIFEST_FILENAME /* const */
diff --git a/tests/__snapshots__/tsnapi/devframe/handler.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/handler.snapshot.d.ts
new file mode 100644
index 00000000..6f716f47
--- /dev/null
+++ b/tests/__snapshots__/tsnapi/devframe/handler.snapshot.d.ts
@@ -0,0 +1,37 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/handler`
+ */
+// #region Interfaces
+export interface CreateHandlerOptions {
+  base?: string;
+  distDir?: string;
+  server?: Server;
+  ws?: DevframeWsOptions;
+  host?: string;
+  auth?: boolean | DevframeAuthHandler;
+  mcp?: boolean | McpRouteOptions;
+  key?: string;
+  origin?: string;
+  flags?: Record<string, unknown>;
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
+}
+export interface DevframeHandler {
+  fetch: (_: Request, _?: unknown) => Promise<Response>;
+  nodeMiddleware: (_: IncomingMessage, _: ServerResponse, _?: (_?: unknown) => void) => void;
+  websocket: DevframeHandlerWebSocket;
+  ready: Promise<void>;
+  context: Promise<DevframeNodeContext>;
+  connectionMeta: () => ConnectionMeta;
+  close: () => Promise<void>;
+}
+export interface DevframeHandlerWebSocket {
+  open: (_: unknown) => void;
+  message: (_: unknown, _: unknown) => void;
+  close: (_: unknown, _?: number, _?: string) => void;
+  drain: (_: unknown) => void;
+}
+// #endregion
+
+// #region Functions
+export declare function createHandler(_: DevframeDefinition, _?: CreateHandlerOptions): DevframeHandler;
+// #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/devframe/handler.snapshot.js b/tests/__snapshots__/tsnapi/devframe/handler.snapshot.js
new file mode 100644
index 00000000..02a823f2
--- /dev/null
+++ b/tests/__snapshots__/tsnapi/devframe/handler.snapshot.js
@@ -0,0 +1,6 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/handler`
+ */
+// #region Functions
+export function createHandler(_, _) {}
+// #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts
index 406a5da9..5ee58841 100644
--- a/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts
@@ -4,7 +4,7 @@
 // #region Interfaces
 export interface CreateH3DevframeHostOptions {
   app?: unknown;
-  origin: string;
+  origin: string | (() => string);
   mount?: (_: string, _: string) => void | Promise<void>;
   appName: string;
   workspaceRoot?: string;
diff --git a/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.d.ts
index 3cd2c972..db79e248 100644
--- a/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.d.ts
@@ -5,6 +5,7 @@
 export { attachWsRpcTransport }
 export { createWsOriginRegistry }
 export { CreateWsOriginRegistryOptions }
+export { createWsRpcPeerHooks }
 export { DevframeNodeRpcSessionMeta }
 export { isAllowedOrigin }
 export { isLoopbackHostname }
diff --git a/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.js b/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.js
index ffa6f3c7..3519ab90 100644
--- a/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.js
+++ b/tests/__snapshots__/tsnapi/devframe/rpc/transports/ws-server.snapshot.js
@@ -4,6 +4,7 @@
 // #region Functions
 export function attachWsRpcTransport(_, _) {}
 export function createWsOriginRegistry(_) {}
+export function createWsRpcPeerHooks(_, _) {}
 export function isAllowedOrigin(_, _) {}
 export function isLoopbackHostname(_) {}
 // #endregion
\ No newline at end of file
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 9bcf497c..75b356f9 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -106,6 +106,9 @@
       "devframe/adapters/embedded": [
         "./packages/devframe/src/adapters/embedded.ts"
       ],
+      "devframe/handler": [
+        "./packages/devframe/src/adapters/handler.ts"
+      ],
       "devframe/adapters/mcp": [
         "./packages/devframe/src/adapters/mcp/index.ts"
       ],

From 4231c955dbdbc0be21159ee0105cbb901ddfc142 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 6 Aug 2026 01:46:14 +0000
Subject: [PATCH 4/4] feat(handler)!: rename to initDevframe from
 devframe/initiate, returning a DevframeInstance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The factory is named for the instance it initiates (define → init
pairing with defineDevframe), reached from the devframe/initiate
subpath, and the web-standard request handler is a property —
initDevframe(def).handler — matching the content.handler mounting
model, so future capabilities extend the instance object instead of
overloading a handler-named factory.

- subpath: devframe/handler → devframe/initiate (src/adapters/initiate.ts)
- createHandler → initDevframe; CreateHandlerOptions → InitDevframeOptions
- DevframeHandler → DevframeInstance; fetch → handler
- diagnostics/docs updated (DF0053/DF0054 wording)
---
 alias.ts                                      |  2 +-
 docs/errors/DF0053.md                         | 16 ++--
 docs/errors/DF0054.md                         | 20 ++---
 knip.jsonc                                    |  2 +-
 packages/devframe/package.json                |  2 +-
 .../{handler.test.ts => initiate.test.ts}     | 90 +++++++++----------
 .../{handler-bun.ts => initiate-bun.ts}       |  0
 .../src/adapters/{handler.ts => initiate.ts}  | 80 ++++++++---------
 packages/devframe/src/node/diagnostics.ts     |  8 +-
 packages/devframe/tsdown.config.ts            |  2 +-
 plans/devframes-standard-middleware.md        |  8 +-
 .../tsnapi/devframe/handler.snapshot.js       |  6 --
 ...r.snapshot.d.ts => initiate.snapshot.d.ts} | 36 ++++----
 .../tsnapi/devframe/initiate.snapshot.js      |  6 ++
 tsconfig.base.json                            |  4 +-
 15 files changed, 141 insertions(+), 141 deletions(-)
 rename packages/devframe/src/adapters/__tests__/{handler.test.ts => initiate.test.ts} (79%)
 rename packages/devframe/src/adapters/{handler-bun.ts => initiate-bun.ts} (100%)
 rename packages/devframe/src/adapters/{handler.ts => initiate.ts} (89%)
 delete mode 100644 tests/__snapshots__/tsnapi/devframe/handler.snapshot.js
 rename tests/__snapshots__/tsnapi/devframe/{handler.snapshot.d.ts => initiate.snapshot.d.ts} (66%)
 create mode 100644 tests/__snapshots__/tsnapi/devframe/initiate.snapshot.js

diff --git a/alias.ts b/alias.ts
index e7d9b731..3efeb54a 100644
--- a/alias.ts
+++ b/alias.ts
@@ -40,7 +40,7 @@ export const alias = {
   'devframe/adapters/build': r('devframe/src/adapters/build.ts'),
   'devframe/helpers/vite': r('devframe/src/helpers/vite.ts'),
   'devframe/adapters/embedded': r('devframe/src/adapters/embedded.ts'),
-  'devframe/handler': r('devframe/src/adapters/handler.ts'),
+  'devframe/initiate': r('devframe/src/adapters/initiate.ts'),
   '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'),
diff --git a/docs/errors/DF0053.md b/docs/errors/DF0053.md
index 730ce2b0..bb99b893 100644
--- a/docs/errors/DF0053.md
+++ b/docs/errors/DF0053.md
@@ -2,32 +2,32 @@
 outline: deep
 ---
 
-# DF0053: Memoized Handler Replaced
+# DF0053: Memoized Instance Replaced
 
 ## Message
 
-> createHandler("`{id}`") replaced the live handler memoized under key "`{key}`": its options changed since the previous call.
+> initDevframe("`{id}`") replaced the live instance memoized under key "`{key}`": its options changed since the previous call.
 
 ## Cause
 
-`createHandler` was called with a `key` that already maps to a live handler, but the option fingerprint differs from the memoized instance's. Dev servers that re-evaluate modules on the fly (Next.js, Nitro, SvelteKit HMR) re-run `createHandler` 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.
+`initDevframe` 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 `initDevframe` 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 { createHandler } from 'devframe/handler'
+import { initDevframe } from 'devframe/initiate'
 
 // First evaluation:
-createHandler(def, { key: 'devtools', ws: { port: 7811 } })
+initDevframe(def, { key: 'devtools', ws: { port: 7811 } })
 
 // A later reload with a different port replaces the live instance:
-createHandler(def, { key: 'devtools', ws: { port: 7812 } }) // ⚠ DF0053
+initDevframe(def, { key: 'devtools', ws: { port: 7812 } }) // ⚠ DF0053
 ```
 
 ## Fix
 
-This is informational when you edited the options on purpose — the replacement is the intended behavior. If it fires without an intentional change, make the options stable across reloads (module-level constants rather than values recomputed per evaluation), or give genuinely different handlers distinct keys.
+This is informational when you edited the options on purpose — the replacement is the intended behavior. If it fires without an intentional change, make the options stable across reloads (module-level constants rather than values recomputed per evaluation), or give genuinely different instances distinct keys.
 
 ## Source
 
-- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler` warns this before closing and replacing a memoized instance whose options fingerprint changed.
+- [`packages/devframe/src/adapters/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/initiate.ts) — `initDevframe` warns this before closing and replacing a memoized instance whose options fingerprint changed.
diff --git a/docs/errors/DF0054.md b/docs/errors/DF0054.md
index a2df3ecd..c1b1d909 100644
--- a/docs/errors/DF0054.md
+++ b/docs/errors/DF0054.md
@@ -2,32 +2,32 @@
 outline: deep
 ---
 
-# DF0054: connectionMeta() Before Handler Ready
+# DF0054: connectionMeta() Before Instance Ready
 
 ## Message
 
-> connectionMeta() was called before createHandler("`{id}`") finished initializing.
+> connectionMeta() was called before initDevframe("`{id}`") finished initializing.
 
 ## Cause
 
-`createHandler` is a synchronous factory that kicks off asynchronous initialization eagerly — running `def.setup`, binding the WebSocket tier, and mounting the routes. `connectionMeta()` describes the WebSocket binding, which only exists once that initialization completes; calling it earlier has nothing correct to return.
+`initDevframe` is a synchronous factory that kicks off asynchronous initialization eagerly — running `def.setup`, binding the WebSocket tier, and mounting the routes. `connectionMeta()` describes the WebSocket binding, which only exists once that initialization completes; calling it earlier has nothing correct to return.
 
 ## Example
 
 ```ts
-import { createHandler } from 'devframe/handler'
+import { initDevframe } from 'devframe/initiate'
 
-const handler = createHandler(def)
-handler.connectionMeta() // ✗ throws DF0054 — init is still in flight
+const devtools = initDevframe(def)
+devtools.connectionMeta() // ✗ throws DF0054 — init is still in flight
 
-await handler.ready
-handler.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
+await devtools.ready
+devtools.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
 ```
 
 ## Fix
 
-Await `handler.ready` (or any `handler.fetch` call — it awaits readiness internally) before reading `connectionMeta()`.
+Await `instance.ready` (or any request through `instance.handler` — it awaits readiness internally) before reading `connectionMeta()`.
 
 ## Source
 
-- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler`'s `connectionMeta()` throws this while initialization is still pending.
+- [`packages/devframe/src/adapters/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/initiate.ts) — `initDevframe`'s `connectionMeta()` throws this while initialization is still pending.
diff --git a/knip.jsonc b/knip.jsonc
index 16ae6569..6923fed4 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -73,7 +73,7 @@
       "entry": [
         "src/{index,constants}.ts",
         "src/helpers/vite.ts",
-        "src/adapters/{build,cac,cli,dev,embedded,handler}.ts",
+        "src/adapters/{build,cac,cli,dev,embedded,initiate}.ts",
         "src/adapters/mcp/index.ts",
         "src/client/index.ts",
         "src/node/index.ts",
diff --git a/packages/devframe/package.json b/packages/devframe/package.json
index 5a290c6f..3c75b6a3 100644
--- a/packages/devframe/package.json
+++ b/packages/devframe/package.json
@@ -28,8 +28,8 @@
     "./adapters/mcp": "./dist/adapters/mcp.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
-    "./handler": "./dist/adapters/handler.mjs",
     "./helpers/vite": "./dist/helpers/vite.mjs",
+    "./initiate": "./dist/adapters/initiate.mjs",
     "./node": "./dist/node/index.mjs",
     "./node/auth": "./dist/node/auth.mjs",
     "./node/hub-internals": "./dist/node/hub-internals.mjs",
diff --git a/packages/devframe/src/adapters/__tests__/handler.test.ts b/packages/devframe/src/adapters/__tests__/initiate.test.ts
similarity index 79%
rename from packages/devframe/src/adapters/__tests__/handler.test.ts
rename to packages/devframe/src/adapters/__tests__/initiate.test.ts
index ce2bba98..7877a23d 100644
--- a/packages/devframe/src/adapters/__tests__/handler.test.ts
+++ b/packages/devframe/src/adapters/__tests__/initiate.test.ts
@@ -10,7 +10,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { WebSocket } from 'ws'
 import { getTempAuthCode } from '../../node/auth/state'
 import { defineDevframe } from '../../types/devframe'
-import { createHandler } from '../handler'
+import { initDevframe } from '../initiate'
 
 const HANDSHAKE = { authToken: '', ua: 'test', origin: 'http://localhost' }
 
@@ -43,15 +43,15 @@ function defineTestDef(id: string) {
 
 describe('adapters/handler', () => {
   it('connectionMeta() before ready throws DF0054', () => {
-    const handler = createHandler(defineTestDef('handler-early'), { auth: false })
-    expect(() => handler.connectionMeta()).toThrow(/DF0054|finished initializing/)
-    return handler.close()
+    const devtools = initDevframe(defineTestDef('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 handler = createHandler(defineTestDef('handler-test'), {
+    const devtools = initDevframe(defineTestDef('handler-test'), {
       auth: false,
       distDir,
       host: '127.0.0.1',
@@ -59,19 +59,19 @@ describe('adapters/handler', () => {
     })
 
     try {
-      await handler.ready
+      await devtools.ready
       // The advertised meta carries the side-car port with the unified route.
-      expect(handler.connectionMeta()).toEqual({
+      expect(devtools.connectionMeta()).toEqual({
         backend: 'websocket',
         websocket: { port: wsPort, path: '__ws' },
       })
 
       // Hosted default base: /__<id>/.
-      const index = await handler.fetch(new Request('http://localhost:3000/__handler-test/'))
+      const index = await devtools.handler(new Request('http://localhost:3000/__handler-test/'))
       expect(index.status).toBe(200)
       expect(await index.text()).toContain('handler test')
 
-      const metaRes = await handler.fetch(new Request('http://localhost:3000/__handler-test/__connection.json'))
+      const metaRes = await devtools.handler(new Request('http://localhost:3000/__handler-test/__connection.json'))
       expect(metaRes.status).toBe(200)
       expect(await metaRes.json()).toEqual({
         backend: 'websocket',
@@ -79,7 +79,7 @@ describe('adapters/handler', () => {
       })
 
       // Outside the base — and inside it on a miss — the fetch surface 404s.
-      const outside = await handler.fetch(new Request('http://localhost:3000/app'))
+      const outside = await devtools.handler(new Request('http://localhost:3000/app'))
       expect(outside.status).toBe(404)
 
       // RPC round-trips against the side-car.
@@ -88,7 +88,7 @@ describe('adapters/handler', () => {
       client.$close()
     }
     finally {
-      await handler.close()
+      await devtools.close()
     }
 
     // Teardown is real: the side-car no longer accepts connections.
@@ -102,21 +102,21 @@ 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 handler = createHandler(defineTestDef('handler-auth'), {
+    const devtools = initDevframe(defineTestDef('handler-auth'), {
       host: '127.0.0.1',
       ws: { port: wsPort },
     })
 
     try {
-      await handler.ready
+      await devtools.ready
       // The banner waits for the public origin: unknown until a request
       // arrives, then printed exactly once (the magic link points at the
       // origin the handler is actually mounted on).
       expect(spy).not.toHaveBeenCalled()
-      await handler.fetch(new Request('http://localhost:4321/__handler-auth/__connection.json'))
+      await devtools.handler(new Request('http://localhost:4321/__handler-auth/__connection.json'))
       expect(spy).toHaveBeenCalledTimes(1)
       expect(String(spy.mock.calls[0])).toContain('http://localhost:4321')
-      await handler.fetch(new Request('http://localhost:4321/__handler-auth/__connection.json'))
+      await devtools.handler(new Request('http://localhost:4321/__handler-auth/__connection.json'))
       expect(spy).toHaveBeenCalledTimes(1)
 
       const client = connectWsClient(`ws://127.0.0.1:${wsPort}/__ws`)
@@ -132,7 +132,7 @@ describe('adapters/handler', () => {
     }
     finally {
       spy.mockRestore()
-      await handler.close()
+      await devtools.close()
     }
   })
 
@@ -141,16 +141,16 @@ describe('adapters/handler', () => {
     const host = '127.0.0.1'
     const port = await getPort({ port: 18130, host })
 
-    let handlerRef!: ReturnType<typeof createHandler>
+    let devtoolsRef!: ReturnType<typeof initDevframe>
     const server = createServer((req, res) => {
       // The middleware self-filters by base; everything else stays the
       // host app's.
-      handlerRef.nodeMiddleware(req, res, () => {
+      devtoolsRef.nodeMiddleware(req, res, () => {
         res.statusCode = 418
         res.end('host app')
       })
     })
-    handlerRef = createHandler(defineTestDef('handler-shared'), {
+    devtoolsRef = initDevframe(defineTestDef('handler-shared'), {
       auth: false,
       distDir,
       server,
@@ -158,10 +158,10 @@ describe('adapters/handler', () => {
     await new Promise<void>(resolve => server.listen(port, host, resolve))
 
     try {
-      await handlerRef.ready
+      await devtoolsRef.ready
       // Zero extra ports: the meta advertises a same-origin relative route,
       // resolved against __connection.json's own URL.
-      expect(handlerRef.connectionMeta()).toEqual({
+      expect(devtoolsRef.connectionMeta()).toEqual({
         backend: 'websocket',
         websocket: { path: '__ws' },
       })
@@ -201,7 +201,7 @@ describe('adapters/handler', () => {
       expect(offOpened).toBe(false)
     }
     finally {
-      await handlerRef.close()
+      await devtoolsRef.close()
       // Fire-and-forget teardown for the host-owned test server: the
       // deliberately dangling off-route upgrade socket sits outside the
       // http server's tracked connections, so a graceful close never
@@ -212,30 +212,30 @@ describe('adapters/handler', () => {
   })
 
   it('ws.url tier: advertises the external endpoint verbatim, owns no transport', async () => {
-    const handler = createHandler(defineTestDef('handler-remote'), {
+    const devtools = initDevframe(defineTestDef('handler-remote'), {
       ws: { url: 'wss://devtools.example.com/relay/__ws' },
     })
 
     try {
-      await handler.ready
-      expect(handler.connectionMeta()).toEqual({
+      await devtools.ready
+      expect(devtools.connectionMeta()).toEqual({
         backend: 'websocket',
         websocket: 'wss://devtools.example.com/relay/__ws',
       })
     }
     finally {
-      await handler.close()
+      await devtools.close()
     }
   })
 
   it('tunnel pattern: ws.url with a server binds locally, advertises the relay', async () => {
     const host = '127.0.0.1'
     const port = await getPort({ port: 18170, host })
-    let handlerRef!: ReturnType<typeof createHandler>
+    let devtoolsRef!: ReturnType<typeof initDevframe>
     const server = createServer((req, res) => {
-      handlerRef.nodeMiddleware(req, res)
+      devtoolsRef.nodeMiddleware(req, res)
     })
-    handlerRef = createHandler(defineTestDef('handler-tunnel'), {
+    devtoolsRef = initDevframe(defineTestDef('handler-tunnel'), {
       auth: false,
       server,
       ws: { url: 'wss://devtools.example.com/relay/__ws' },
@@ -243,16 +243,16 @@ describe('adapters/handler', () => {
     await new Promise<void>(resolve => server.listen(port, host, resolve))
 
     try {
-      await handlerRef.ready
+      await devtoolsRef.ready
       // The browser is told to dial the relay…
-      expect(handlerRef.connectionMeta().websocket).toBe('wss://devtools.example.com/relay/__ws')
+      expect(devtoolsRef.connectionMeta().websocket).toBe('wss://devtools.example.com/relay/__ws')
       // …while the local socket keeps serving (the relay's forward target).
       const client = connectWsClient(`ws://${host}:${port}/__handler-tunnel/__ws`)
       await expect(client.$call('test:probe' as any)).resolves.toBe('ok')
       client.$close()
     }
     finally {
-      await handlerRef.close()
+      await devtoolsRef.close()
       server.close()
       server.closeAllConnections()
     }
@@ -260,39 +260,39 @@ 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 handler = createHandler(defineTestDef('handler-mcp'), {
+    const devtools = initDevframe(defineTestDef('handler-mcp'), {
       auth: false,
       mcp: true,
       ws: { port: wsPort },
     })
 
     try {
-      await handler.ready
-      expect(handler.connectionMeta().mcp).toEqual({ path: '__mcp' })
+      await devtools.ready
+      expect(devtools.connectionMeta().mcp).toEqual({ path: '__mcp' })
       // The route is mounted: a bare GET is answered by the MCP transport
       // (405 for a session-less GET), not the 404 an unmounted path gets.
-      const res = await handler.fetch(new Request('http://localhost:3000/__handler-mcp/__mcp', {
+      const res = await devtools.handler(new Request('http://localhost:3000/__handler-mcp/__mcp', {
         headers: { origin: 'http://localhost:3000' },
       }))
       expect(res.status).not.toBe(404)
     }
     finally {
-      await handler.close()
+      await devtools.close()
     }
   })
 
   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 = createHandler(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort } })
-    const b = createHandler(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort } })
+    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 } })
     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 = createHandler(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort2 } })
+      const c = initDevframe(def, { 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,22 +323,22 @@ 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 handler = createHandler(defineTestDef('handler-bridge'), {
+    const devtools = initDevframe(defineTestDef('handler-bridge'), {
       auth: false,
       ws: { port: wsPort },
     })
 
     try {
-      await handler.ready
-      const meta = await handler.fetch(new Request('http://localhost:3000/__handler-bridge/__connection.json'))
+      await devtools.ready
+      const meta = await devtools.handler(new Request('http://localhost:3000/__handler-bridge/__connection.json'))
       expect(meta.status).toBe(200)
       // No SPA mount: the base itself is a miss, normalized to a bare 404.
-      const spa = await handler.fetch(new Request('http://localhost:3000/__handler-bridge/'))
+      const spa = await devtools.handler(new Request('http://localhost:3000/__handler-bridge/'))
       expect(spa.status).toBe(404)
       expect(await spa.text()).toBe('')
     }
     finally {
-      await handler.close()
+      await devtools.close()
     }
   })
 })
diff --git a/packages/devframe/src/adapters/handler-bun.ts b/packages/devframe/src/adapters/initiate-bun.ts
similarity index 100%
rename from packages/devframe/src/adapters/handler-bun.ts
rename to packages/devframe/src/adapters/initiate-bun.ts
diff --git a/packages/devframe/src/adapters/handler.ts b/packages/devframe/src/adapters/initiate.ts
similarity index 89%
rename from packages/devframe/src/adapters/handler.ts
rename to packages/devframe/src/adapters/initiate.ts
index dc418dbd..bfc300c5 100644
--- a/packages/devframe/src/adapters/handler.ts
+++ b/packages/devframe/src/adapters/initiate.ts
@@ -4,7 +4,7 @@ import type { IncomingMessage, Server as NodeHttpServer, ServerResponse } from '
 import type { DevframeAuthHandler } from '../node/auth/handler'
 import type { StartedServer } from '../node/server'
 import type { DevframeDefinition, DevframeSetupInfo, DevframeWsOptions, McpRouteOptions } from '../types/devframe'
-import type { BunWsTier } from './handler-bun'
+import type { BunWsTier } from './initiate-bun'
 import process from 'node:process'
 import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3, toNodeHandler } from 'h3'
@@ -19,7 +19,7 @@ import { createInteractiveAuth } from '../recipes/interactive-auth'
 import { normalizeBasePath, resolveBasePath } from './_shared'
 import { resolveDevServerPort, resolveMcpConnectionMeta } from './dev'
 
-export interface CreateHandlerOptions {
+export interface InitDevframeOptions {
   /**
    * Mount base the handler answers under. Defaults to
    * `resolveBasePath(def, 'hosted')` (i.e. `def.basePath` or `/__<id>/`) —
@@ -39,8 +39,8 @@ export interface CreateHandlerOptions {
    * omitted (and no `ws.url`/`ws.port` is given), an **eager side-car**
    * WebSocket server starts on its own port at handler creation. Under Bun,
    * the default is the fetch-upgrade tier instead — no side-car; pass the
-   * `Bun.serve` server as `fetch`'s second argument and wire
-   * {@link DevframeHandler.websocket}.
+   * `Bun.serve` server as `handler`'s second argument and wire
+   * {@link DevframeInstance.websocket}.
    */
   server?: NodeHttpServer
   /**
@@ -52,7 +52,7 @@ export interface CreateHandlerOptions {
    * pattern, where the relay forwards to the locally-bound socket — and
    * when neither is given, the handler starts **no transport of its own**
    * (run `startHttpAndWs({ context, server, path })` against
-   * {@link DevframeHandler.context} to serve RPC from your own server).
+   * {@link DevframeInstance.context} to serve RPC from your own server).
    */
   ws?: DevframeWsOptions
   /**
@@ -80,7 +80,7 @@ export interface CreateHandlerOptions {
   /**
    * Memoize the handler on `globalThis` under this key. Dev servers that
    * re-evaluate modules on the fly (Next.js, Nitro, SvelteKit HMR) re-run
-   * `createHandler` on every reload — without a key each run would leak an
+   * `initDevframe` on every reload — without a key each run would leak an
    * eager side-car WebSocket server. With a key, a re-run returns the live
    * instance; if the options changed, the old instance is closed and
    * replaced (reported as `DF0053`).
@@ -110,24 +110,24 @@ export interface CreateHandlerOptions {
  * dependency on Bun's types — cast to Bun's `WebSocketHandler` at the
  * `Bun.serve` call site if your host file typechecks against `bun-types`.
  */
-export interface DevframeHandlerWebSocket {
+export interface DevframeInstanceWebSocket {
   open: (ws: unknown) => void
   message: (ws: unknown, message: unknown) => void
   close: (ws: unknown, code?: number, reason?: string) => void
   drain: (ws: unknown) => void
 }
 
-export interface DevframeHandler {
+export interface DevframeInstance {
   /**
    * Web-standard request handler — mount it on a catch-all route under
-   * {@link CreateHandlerOptions.base} (Next.js route handler, SvelteKit
+   * {@link InitDevframeOptions.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
    * upgraded request resolves to `undefined` per Bun's contract, typed as
    * `Response` for drop-in route-handler compatibility).
    */
-  fetch: (request: Request, server?: unknown) => Promise<Response>
+  handler: (request: Request, server?: unknown) => Promise<Response>
   /**
    * Connect/Express-style middleware over the same surface — for
    * `viteServer.middlewares.use(handler.nodeMiddleware)` or any other
@@ -135,11 +135,11 @@ export interface DevframeHandler {
    * call `next()` so the rest of the stack keeps working.
    */
   nodeMiddleware: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void
-  /** See {@link DevframeHandlerWebSocket}. */
-  websocket: DevframeHandlerWebSocket
+  /** See {@link DevframeInstanceWebSocket}. */
+  websocket: DevframeInstanceWebSocket
   /**
    * Resolves once `def.setup` has run and the WebSocket binding is live.
-   * `fetch`/`nodeMiddleware` await it internally, so hosts never race
+   * `handler`/`nodeMiddleware` await it internally, so hosts never race
    * initialization — await it yourself only when you need the timing.
    */
   ready: Promise<void>
@@ -154,15 +154,15 @@ export interface DevframeHandler {
   close: () => Promise<void>
 }
 
-interface HandlerRegistryEntry {
+interface InstanceRegistryEntry {
   hash: string
-  handler: DevframeHandler
+  handler: DevframeInstance
 }
 
-const REGISTRY_KEY = Symbol.for('devframe:handler-registry')
+const REGISTRY_KEY = Symbol.for('devframe:instance-registry')
 
-function handlerRegistry(): Map<string, HandlerRegistryEntry> {
-  const holder = globalThis as { [REGISTRY_KEY]?: Map<string, HandlerRegistryEntry> }
+function instanceRegistry(): Map<string, InstanceRegistryEntry> {
+  const holder = globalThis as { [REGISTRY_KEY]?: Map<string, InstanceRegistryEntry> }
   holder[REGISTRY_KEY] ??= new Map()
   return holder[REGISTRY_KEY]
 }
@@ -174,7 +174,7 @@ function handlerRegistry(): Map<string, HandlerRegistryEntry> {
  * object on every module re-evaluation would defeat memoization, which is
  * exactly the scenario `key` exists for.
  */
-function optionsHash(def: DevframeDefinition, options: CreateHandlerOptions): string {
+function optionsHash(def: DevframeDefinition, options: InitDevframeOptions): string {
   return JSON.stringify({
     id: def.id,
     base: options.base,
@@ -199,22 +199,22 @@ function samePath(a: string, b: string): boolean {
  * Serve a devframe through one framework-agnostic, web-standard handler —
  * the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the
  * auth gate, and the optional MCP route, all under a single mount base.
- * Mount `fetch` on any framework's catch-all route (or `nodeMiddleware` on
+ * Mount `handler` on any framework's catch-all route (or `nodeMiddleware` on
  * a connect stack) and the devframe is live inside that app.
  *
  * The factory is synchronous and kicks off initialization eagerly;
- * `fetch`/`nodeMiddleware` await readiness internally. How the WebSocket is
+ * `handler`/`nodeMiddleware` await readiness internally. How the WebSocket is
  * bound resolves in precedence order — `ws.url` (external, advertise-only)
  * > `ws.port` (explicit side-car) > `server` (shared upgrade at
  * `<base>__ws`) > Bun fetch-upgrade (under Bun) > an eager side-car on a
  * free port — and `__connection.json` reflects whichever tier is active.
  */
-export function createHandler(
+export function initDevframe(
   def: DevframeDefinition,
-  options: CreateHandlerOptions = {},
-): DevframeHandler {
+  options: InitDevframeOptions = {},
+): DevframeInstance {
   if (options.key) {
-    const registry = handlerRegistry()
+    const registry = instanceRegistry()
     const hash = optionsHash(def, options)
     const existing = registry.get(options.key)
     if (existing) {
@@ -223,17 +223,17 @@ export function createHandler(
       diagnostics.DF0053({ key: options.key, id: def.id })
       void existing.handler.close().catch(() => {})
     }
-    const handler = instantiateHandler(def, options)
+    const handler = instantiateDevframe(def, options)
     registry.set(options.key, { hash, handler })
     return handler
   }
-  return instantiateHandler(def, options)
+  return instantiateDevframe(def, options)
 }
 
-function instantiateHandler(
+function instantiateDevframe(
   def: DevframeDefinition,
-  options: CreateHandlerOptions,
-): DevframeHandler {
+  options: InitDevframeOptions,
+): DevframeInstance {
   const base = options.base ? normalizeBasePath(options.base) : resolveBasePath(def, 'hosted')
   const baseNoSlash = withoutTrailingSlash(base)
   const distDir = options.distDir ?? def.cli?.distDir
@@ -379,8 +379,8 @@ function instantiateHandler(
     }
     else {
       // Bun fetch-upgrade — same-origin upgrades completed through
-      // `fetch(request, server)`, handlers exposed via `websocket`.
-      const { attachBunWsTransport } = await import('./handler-bun')
+      // `handler(request, server)`, hooks exposed via `websocket`.
+      const { attachBunWsTransport } = await import('./initiate-bun')
       const { createContextRpcServer } = await import('../node/rpc-core')
       const core = createContextRpcServer({ context: ctx, auth: resolvedAuth })
       bunTier = await attachBunWsTransport(core, { allowedOrigins: options.allowedOrigins })
@@ -410,13 +410,13 @@ function instantiateHandler(
   }
 
   const initPromise = init()
-  // Surface init failures through `ready`/`fetch`, never as an unhandled
+  // Surface init failures through `ready`/`handler`, never as an unhandled
   // rejection from the eager kick-off.
   initPromise.catch(() => {})
   const contextPromise = initPromise.then(() => ctx)
   contextPromise.catch(() => {})
 
-  async function fetch(request: Request, server?: unknown): Promise<Response> {
+  async function handleRequest(request: Request, server?: unknown): Promise<Response> {
     await initPromise
     const url = new URL(request.url)
     noteOrigin(url.origin)
@@ -424,12 +424,12 @@ function instantiateHandler(
       && request.headers.get('upgrade')?.toLowerCase() === 'websocket') {
       if (!server) {
         return new Response(
-          'Upgrade Required: pass the Bun server as the second argument to handler.fetch(request, server)',
+          'Upgrade Required: pass the Bun server as the second argument to instance.handler(request, server)',
           { status: 426 },
         )
       }
       // An upgraded request resolves to `undefined` per Bun's contract; the
-      // cast keeps `fetch` drop-in assignable to route handlers that expect
+      // cast keeps `handler` drop-in assignable to route handlers that expect
       // a `Response`.
       return await bunTier.handleUpgrade(request, server) as Response
     }
@@ -477,15 +477,15 @@ function instantiateHandler(
       })
   }
 
-  const websocket: DevframeHandlerWebSocket = {
+  const websocket: DevframeInstanceWebSocket = {
     open: ws => void bunTier?.websocket.open?.(ws),
     message: (ws, message) => void bunTier?.websocket.message(ws, message),
     close: (ws, code, reason) => void bunTier?.websocket.close?.(ws, code, reason),
     drain: ws => void bunTier?.websocket.drain?.(ws),
   }
 
-  const handler: DevframeHandler = {
-    fetch,
+  const handler: DevframeInstance = {
+    handler: handleRequest,
     nodeMiddleware,
     websocket,
     ready: initPromise,
@@ -497,7 +497,7 @@ function instantiateHandler(
     },
     close: async () => {
       if (options.key) {
-        const registry = handlerRegistry()
+        const registry = instanceRegistry()
         if (registry.get(options.key)?.handler === handler)
           registry.delete(options.key)
       }
diff --git a/packages/devframe/src/node/diagnostics.ts b/packages/devframe/src/node/diagnostics.ts
index 449f923f..dd936c87 100644
--- a/packages/devframe/src/node/diagnostics.ts
+++ b/packages/devframe/src/node/diagnostics.ts
@@ -117,12 +117,12 @@ export const diagnostics = defineDiagnostics({
       fix: 'The port is likely already taken by another process (often a previous devframe instance). Free it, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `devMiddleware.port` on `viteDevBridge`. The original node error is available as `error.cause`.',
     },
     DF0053: {
-      why: (p: { key: string, id: string }) => `createHandler("${p.id}") replaced the live handler memoized under key "${p.key}": its options changed since the previous call.`,
-      fix: 'A dev-time module reload re-ran createHandler with different options, so the old instance (and its side-car WebSocket server) was closed and a new one started. If this is unexpected, keep the options stable across reloads — or use distinct keys for genuinely different handlers.',
+      why: (p: { key: string, id: string }) => `initDevframe("${p.id}") replaced the live instance memoized under key "${p.key}": its options changed since the previous call.`,
+      fix: 'A dev-time module reload re-ran initDevframe with different options, so the old instance (and its side-car WebSocket server) was closed and a new one started. If this is unexpected, keep the options stable across reloads — or use distinct keys for genuinely different instances.',
     },
     DF0054: {
-      why: (p: { id: string }) => `connectionMeta() was called before createHandler("${p.id}") finished initializing.`,
-      fix: 'Await `handler.ready` (or any `handler.fetch` call) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes.',
+      why: (p: { id: string }) => `connectionMeta() was called before initDevframe("${p.id}") finished initializing.`,
+      fix: 'Await `instance.ready` (or any request through `instance.handler`) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes.',
     },
   },
 })
diff --git a/packages/devframe/tsdown.config.ts b/packages/devframe/tsdown.config.ts
index fd861cd3..70c9ee92 100644
--- a/packages/devframe/tsdown.config.ts
+++ b/packages/devframe/tsdown.config.ts
@@ -106,7 +106,7 @@ const serverEntries = {
   'adapters/dev': 'src/adapters/dev.ts',
   'adapters/build': 'src/adapters/build.ts',
   'adapters/embedded': 'src/adapters/embedded.ts',
-  'adapters/handler': 'src/adapters/handler.ts',
+  'adapters/initiate': 'src/adapters/initiate.ts',
   'adapters/mcp': 'src/adapters/mcp/index.ts',
   'cli/main': 'src/cli/main.ts',
   'helpers/vite': 'src/helpers/vite.ts',
diff --git a/plans/devframes-standard-middleware.md b/plans/devframes-standard-middleware.md
index 58cb402f..9e05262f 100644
--- a/plans/devframes-standard-middleware.md
+++ b/plans/devframes-standard-middleware.md
@@ -18,8 +18,8 @@ SvelteKit), running on Node ≥ 20 and Bun. The hub stays headless; UI is a comp
 
 | Import | Serves | Default base |
 |---|---|---|
-| `devframe/handler` | **One devframe**: its SPA (`distDir`; omitted → bridge mode serving only meta + WS), `__connection.json`, `__mcp`, WS RPC, auth. Own isolated context, one `def.setup(ctx)`. | `/__<id>/` (hosted rule) |
-| `@devframes/hub/handler` | **Multi-frame, headless**: shared hub context (docks/terminals/messages/commands + hub built-in RPCs + shared-state slots); every frame's `setup(ctx)` runs against it → one merged RPC registry, one WS endpoint, **one hub Auth**, one aggregate MCP. Frames auto-registered as iframe docks. | `/__devframes/` |
+| `devframe/initiate` | **One devframe**: its SPA (`distDir`; omitted → bridge mode serving only meta + WS), `__connection.json`, `__mcp`, WS RPC, auth. Own isolated context, one `def.setup(ctx)`. | `/__<id>/` (hosted rule) |
+| `@devframes/hub/initiate` | **Multi-frame, headless**: shared hub context (docks/terminals/messages/commands + hub built-in RPCs + shared-state slots); every frame's `setup(ctx)` runs against it → one merged RPC registry, one WS endpoint, **one hub Auth**, one aggregate MCP. Frames auto-registered as iframe docks. | `/__devframes/` |
 
 **`DevframeHubUi` slot** (type lives in `@devframes/hub`; data-first, zero policy):
 
@@ -139,13 +139,13 @@ fetching `<base>__connection.json`. The differences are environmental:
 
 ## Delivery: 5-PR GitHub stack (bottom → top, merge bottom-up)
 
-1. **`feat/handler-core`** — this plan doc; `devframe/handler`: `createHandler` (fetch/node/Bun
+1. **`feat/handler-core`** — this plan doc; `devframe/initiate`: `createHandler` (fetch/node/Bun
    shapes, four WS resolutions, auth gate, per-frame MCP, `key` memo), `__ws` constants,
    new `DF00xx` diagnostics + `docs/errors/` pages, vitest coverage (fetch, middleware,
    WS tiers + meta correctness per resolution, auth gating).
 2. **`feat/handler-adapters`** — `createDevServer` / `viteDevBridge` / `@devframes/next`
    rebuilt on the handler; api-snapshot updates.
-3. **`feat/hub-handler`** — `@devframes/hub/handler`: internal `DevframeHost` impl, frame
+3. **`feat/hub-handler`** — `@devframes/hub/initiate`: internal `DevframeHost` impl, frame
    mounting at `<base><id>/`, `ui` slot + `DevframeHubUi` type, `__index.json`,
    `__client-imports.js`, aggregate MCP, `devframes`/`context`/`configure` options,
    `DF8xxx` diagnostics, tests incl. reserved-path guards, cross-frame RPC visibility,
diff --git a/tests/__snapshots__/tsnapi/devframe/handler.snapshot.js b/tests/__snapshots__/tsnapi/devframe/handler.snapshot.js
deleted file mode 100644
index 02a823f2..00000000
--- a/tests/__snapshots__/tsnapi/devframe/handler.snapshot.js
+++ /dev/null
@@ -1,6 +0,0 @@
-/**
- * Generated by tsnapi — public API snapshot of `devframe/handler`
- */
-// #region Functions
-export function createHandler(_, _) {}
-// #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/devframe/handler.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/initiate.snapshot.d.ts
similarity index 66%
rename from tests/__snapshots__/tsnapi/devframe/handler.snapshot.d.ts
rename to tests/__snapshots__/tsnapi/devframe/initiate.snapshot.d.ts
index 6f716f47..b9b9918e 100644
--- a/tests/__snapshots__/tsnapi/devframe/handler.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/devframe/initiate.snapshot.d.ts
@@ -1,8 +1,23 @@
 /**
- * Generated by tsnapi — public API snapshot of `devframe/handler`
+ * Generated by tsnapi — public API snapshot of `devframe/initiate`
  */
 // #region Interfaces
-export interface CreateHandlerOptions {
+export interface DevframeInstance {
+  handler: (_: Request, _?: unknown) => Promise<Response>;
+  nodeMiddleware: (_: IncomingMessage, _: ServerResponse, _?: (_?: unknown) => void) => void;
+  websocket: DevframeInstanceWebSocket;
+  ready: Promise<void>;
+  context: Promise<DevframeNodeContext>;
+  connectionMeta: () => ConnectionMeta;
+  close: () => Promise<void>;
+}
+export interface DevframeInstanceWebSocket {
+  open: (_: unknown) => void;
+  message: (_: unknown, _: unknown) => void;
+  close: (_: unknown, _?: number, _?: string) => void;
+  drain: (_: unknown) => void;
+}
+export interface InitDevframeOptions {
   base?: string;
   distDir?: string;
   server?: Server;
@@ -15,23 +30,8 @@ export interface CreateHandlerOptions {
   flags?: Record<string, unknown>;
   allowedOrigins?: readonly string[] | WsOriginRegistry | false;
 }
-export interface DevframeHandler {
-  fetch: (_: Request, _?: unknown) => Promise<Response>;
-  nodeMiddleware: (_: IncomingMessage, _: ServerResponse, _?: (_?: unknown) => void) => void;
-  websocket: DevframeHandlerWebSocket;
-  ready: Promise<void>;
-  context: Promise<DevframeNodeContext>;
-  connectionMeta: () => ConnectionMeta;
-  close: () => Promise<void>;
-}
-export interface DevframeHandlerWebSocket {
-  open: (_: unknown) => void;
-  message: (_: unknown, _: unknown) => void;
-  close: (_: unknown, _?: number, _?: string) => void;
-  drain: (_: unknown) => void;
-}
 // #endregion
 
 // #region Functions
-export declare function createHandler(_: DevframeDefinition, _?: CreateHandlerOptions): DevframeHandler;
+export declare function initDevframe(_: DevframeDefinition, _?: InitDevframeOptions): DevframeInstance;
 // #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/devframe/initiate.snapshot.js b/tests/__snapshots__/tsnapi/devframe/initiate.snapshot.js
new file mode 100644
index 00000000..8dd6bb13
--- /dev/null
+++ b/tests/__snapshots__/tsnapi/devframe/initiate.snapshot.js
@@ -0,0 +1,6 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/initiate`
+ */
+// #region Functions
+export function initDevframe(_, _) {}
+// #endregion
\ No newline at end of file
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 75b356f9..ba637775 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -106,8 +106,8 @@
       "devframe/adapters/embedded": [
         "./packages/devframe/src/adapters/embedded.ts"
       ],
-      "devframe/handler": [
-        "./packages/devframe/src/adapters/handler.ts"
+      "devframe/initiate": [
+        "./packages/devframe/src/adapters/initiate.ts"
       ],
       "devframe/adapters/mcp": [
         "./packages/devframe/src/adapters/mcp/index.ts"