feat!: add devframe/initiate — initDevframe framework-agnostic middleware (#167)

* docs: plan for /__devframes/ standard middleware handlers

* refactor(rpc): extract transport-agnostic rpc core and reusable ws peer hooks

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.

* 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 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.

* feat(handler)!: rename to initDevframe from devframe/initiate, returning a DevframeInstance

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)

Author: antfu

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

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/DF0053.md

@@ -0,0 +1,33 @@
+---
+outline: deep
+---
+
+# DF0053: Memoized Instance Replaced
+
+## Message
+
+> initDevframe("`{id}`") replaced the live instance memoized under key "`{key}`": its options changed since the previous call.
+
+## Cause
+
+`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 { initDevframe } from 'devframe/initiate'
+
+// First evaluation:
+initDevframe(def, { key: 'devtools', ws: { port: 7811 } })
+
+// A later reload with a different port replaces the live instance:
+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 instances distinct keys.
+
+## Source
+
+- [`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.

docs/errors/DF0054.md

@@ -0,0 +1,33 @@
+---
+outline: deep
+---
+
+# DF0054: connectionMeta() Before Instance Ready
+
+## Message
+
+> connectionMeta() was called before initDevframe("`{id}`") finished initializing.
+
+## Cause
+
+`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 { initDevframe } from 'devframe/initiate'
+
+const devtools = initDevframe(def)
+devtools.connectionMeta() // ✗ throws DF0054 — init is still in flight
+
+await devtools.ready
+devtools.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
+```
+
+## Fix
+
+Await `instance.ready` (or any request through `instance.handler` — it awaits readiness internally) before reading `connectionMeta()`.
+
+## Source
+
+- [`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.

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,initiate}.ts",
         "src/adapters/mcp/index.ts",
         "src/client/index.ts",
         "src/node/index.ts",

packages/devframe/package.json

@@ -29,6 +29,7 @@
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.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",

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)