feat(handler)!: rename to initDevframe returning a DevframeInstance

The factory is named for the instance it initiates (define → init
pairing with defineDevframe), and the web-standard request handler is
reached as 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.

- createHandler → initDevframe; CreateHandlerOptions → InitDevframeOptions
- DevframeHandler → DevframeInstance; fetch → handler
- diagnostics/docs updated (DF0053/DF0054 wording)

Author: antfubot

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/handler'
 
 // 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/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `initDevframe` warns this before closing and replacing a memoized instance whose options fingerprint changed.

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/handler'
 
-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/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `initDevframe`'s `connectionMeta()` throws this while initialization is still pending.

packages/devframe/src/adapters/__tests__/handler.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 '../handler'
 
 const HANDSHAKE = { authToken: '', ua: 'test', origin: 'http://localhost' }
 
@@ -43,43 +43,43 @@ 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',
       ws: { port: wsPort },
     })
 
     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',
         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'))
+      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,27 +141,27 @@ 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,
     })
     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,87 +212,87 @@ 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' },
     })
     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()
     }
   })
 
   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()
     }
   })
 })