feat(handler): add devframe/handler — framework-agnostic web-standard middleware

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 tiers resolve by precedence: ws.url (external, advertise-only)
> ws.port (explicit side-car) > server (shared upgrade at <base>__ws) >
Bun fetch-upgrade > eager auto side-car. A key option memoizes the
handler on globalThis so HMR module re-evaluation can't leak side-cars.

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.

Author: antfubot

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'),

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' } },
 })
 ```
 

docs/errors/DF0052.md

@@ -0,0 +1,37 @@
+---
+outline: deep
+---
+
+# DF0052: Conflicting WebSocket Bindings on createHandler
+
+## Message
+
+> createHandler("`{id}`") received \`ws.url\` alongside \`server\`/\`ws.port\` — the external URL wins and no local WebSocket transport is started.
+
+## Cause
+
+`createHandler` resolves its WebSocket tier in precedence order — `ws.url` (advertise an external endpoint verbatim) > `ws.port` (explicit side-car port) > `server` (shared upgrade on the host's HTTP server) > the eager auto side-car. Passing `ws.url` together with `server` or `ws.port` is contradictory: the external URL is advertised, and the other bindings are ignored — the handler starts no transport of its own in that tier.
+
+## Example
+
+```ts
+import { createHandler } from 'devframe/handler'
+
+// ✗ Bad — the server is never used for devframe's socket:
+const handler = createHandler(def, {
+  server: httpServer,
+  ws: { url: 'wss://relay.example.com/__ws' },
+})
+
+// ✓ Good — pick exactly one binding:
+const shared = createHandler(def, { server: httpServer })
+const external = createHandler(def, { ws: { url: 'wss://relay.example.com/__ws' } })
+```
+
+## Fix
+
+Pass exactly one WebSocket binding: `ws.url` when a server you run yourself owns the RPC endpoint (wire the handler's `context` into it via `startHttpAndWs`), `ws.port` for an explicit side-car port, or `server` to share the host HTTP server's port. Drop the extras.
+
+## Source
+
+- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler`'s WebSocket tier resolution warns this when `ws.url` shadows another binding.

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.

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.

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" }
 }
 ```
 

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.
 

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",

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",

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