@belte/belte 0.19.0

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -0,0 +1,311 @@
+import type { ServerWebSocket } from 'bun'
+import { log } from '../../shared/log.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
+import { error } from '../error.ts'
+import { json } from '../json.ts'
+import { sse } from '../sse.ts'
+import { lookupSocket } from './lookupSocket.ts'
+import { recentHistory } from './recentHistory.ts'
+import type { SocketClientFrame } from './types/SocketClientFrame.ts'
+import type { SocketRoutes } from './types/SocketRoutes.ts'
+import type { SocketServerFrame } from './types/SocketServerFrame.ts'
+
+// Reused across every inbound binary frame rather than allocated per message.
+const textDecoder = new TextDecoder()
+
+type SocketDispatcher = {
+    open(ws: ServerWebSocket<unknown>): void
+    message(ws: ServerWebSocket<unknown>, data: string | Buffer): void
+    close(ws: ServerWebSocket<unknown>): void
+    rest(req: Request, name: string): Promise<Response>
+}
+
+/*
+Per-connection state: which sockets this ws is currently subscribed to
+(at the Bun-topic level), and which `sub` ids map to which socket. One
+ws can hold multiple subs against the same socket (e.g. one with
+history, one without); the Bun-topic subscription is reference-counted
+so we only `ws.unsubscribe` when the last local sub drops.
+*/
+type ConnectionState = {
+    subToSocket: Map<string, string>
+    socketSubs: Map<string, Set<string>>
+}
+
+/*
+Bridges the framework's socket registry to a single ws per client. All
+sockets multiplex over `/__belte/sockets`. Steady-state fan-out rides
+Bun's native `server.publish('socket:<name>', frame)` so the dispatcher
+is only on the path for sub/unsub bookkeeping and client-initiated pub
+validation; the published `msg` frames go from publisher to subscribers
+without touching JS per frame.
+
+`sub` opens a subscription: history is replayed (unless the client
+passed `tail: true`) directly to this ws, then the ws is added to the
+Bun topic. `unsub` drops the local sub and unsubscribes the ws from
+the Bun topic if no other local subs remain. `pub` validates the
+socket's `allowClientPublish` policy and calls `socket.publish` —
+which fans out to in-process iterators and republishes through Bun
+to other connected clients.
+
+Module-level lookups are cached per socket name: loading a socket
+module triggers its `defineSocket` call, which inserts into the
+registry. After that the dispatcher just reads the registry.
+*/
+export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher {
+    const connections = new WeakMap<ServerWebSocket<unknown>, ConnectionState>()
+
+    const ensureLoaded = memoizeByKey((name): Promise<void> | undefined => {
+        const loader = sockets[name]
+        return loader ? loader().then(() => undefined) : undefined
+    })
+
+    function send(ws: ServerWebSocket<unknown>, frame: SocketServerFrame): void {
+        if (ws.readyState !== WebSocket.OPEN) {
+            return
+        }
+        ws.send(JSON.stringify(frame))
+    }
+
+    function addSub(state: ConnectionState, name: string, sub: string): boolean {
+        state.subToSocket.set(sub, name)
+        let subs = state.socketSubs.get(name)
+        if (!subs) {
+            subs = new Set()
+            state.socketSubs.set(name, subs)
+        }
+        const wasEmpty = subs.size === 0
+        subs.add(sub)
+        return wasEmpty
+    }
+
+    function removeSub(state: ConnectionState, sub: string): string | undefined {
+        const name = state.subToSocket.get(sub)
+        if (!name) {
+            return undefined
+        }
+        state.subToSocket.delete(sub)
+        const subs = state.socketSubs.get(name)
+        if (!subs) {
+            return undefined
+        }
+        subs.delete(sub)
+        if (subs.size === 0) {
+            state.socketSubs.delete(name)
+            return name
+        }
+        return undefined
+    }
+
+    async function handleSub(
+        ws: ServerWebSocket<unknown>,
+        state: ConnectionState,
+        frame: Extract<SocketClientFrame, { type: 'sub' }>,
+    ): Promise<void> {
+        // Reject this sub: emit the error then the terminal end frame for its id.
+        function fail(message: string): void {
+            send(ws, { type: 'err', sub: frame.sub, message })
+            send(ws, { type: 'end', sub: frame.sub })
+        }
+        const loader = ensureLoaded(frame.socket)
+        if (!loader) {
+            return fail(`[belte] no socket registered at ${frame.socket}`)
+        }
+        try {
+            await loader
+        } catch (error) {
+            log.error(error)
+            return fail(error instanceof Error ? error.message : String(error))
+        }
+        const entry = lookupSocket(frame.socket)
+        if (!entry) {
+            return fail(`[belte] socket module at ${frame.socket} did not register a Socket export`)
+        }
+        const isFirstLocalSub = addSub(state, frame.socket, frame.sub)
+        if (isFirstLocalSub) {
+            ws.subscribe(`socket:${frame.socket}`)
+        }
+        /*
+        Replay history directly to this ws via ws.send (not
+        server.publish) so other connected subscribers don't see the
+        replay. Live messages published from now on flow through the
+        Bun topic the ws just joined; clients may observe live messages
+        interleaved with the tail of history, so user payloads should
+        carry an id/timestamp when ordering matters.
+
+        `replay === undefined` means full replay (bare `for await`);
+        a number is clamped to the buffer length so the client can ask
+        for "as many as available, up to N".
+        */
+        recentHistory(entry, frame.replay).forEach((message) => {
+            send(ws, { type: 'msg', socket: frame.socket, message })
+        })
+    }
+
+    function handleUnsub(
+        ws: ServerWebSocket<unknown>,
+        state: ConnectionState,
+        frame: Extract<SocketClientFrame, { type: 'unsub' }>,
+    ): void {
+        const emptied = removeSub(state, frame.sub)
+        if (emptied) {
+            ws.unsubscribe(`socket:${emptied}`)
+        }
+        send(ws, { type: 'end', sub: frame.sub })
+    }
+
+    async function handlePub(
+        ws: ServerWebSocket<unknown>,
+        frame: Extract<SocketClientFrame, { type: 'pub' }>,
+    ): Promise<void> {
+        const loader = ensureLoaded(frame.socket)
+        if (!loader) {
+            return
+        }
+        try {
+            await loader
+        } catch (error) {
+            log.error(error)
+            return
+        }
+        const entry = lookupSocket(frame.socket)
+        if (!entry) {
+            return
+        }
+        if (!entry.allowClientPublish) {
+            /*
+            Silent drop: the publish is rejected because the topic
+            wasn't declared `{ clientPublish: true }`. Surfacing this as
+            an error per-publish would tempt apps to attempt-then-handle
+            instead of routing through an HTTP route for auth. Log it
+            once per process at debug level (out of scope here) if
+            visibility is needed.
+            */
+            return
+        }
+        /*
+        publish() runs the topic's optional Standard Schema synchronously
+        and throws on failure (see defineSocket.validateSync). The
+        dispatcher invokes us via `void handlePub(...)`, so an unhandled
+        throw would surface as an unhandled promise rejection on every
+        malformed client frame. Catch + log so a buggy client can't take
+        the process down.
+        */
+        try {
+            entry.socket.publish(frame.message)
+        } catch (error) {
+            log.error(error)
+        }
+        /*
+        ws parameter retained for future per-ws auth context (cookies on
+        upgrade) the canPublish hook would consult.
+        */
+        void ws
+    }
+
+    /*
+    HTTP face of the sockets hub at `/__belte/sockets/<name>`, for the CLI
+    and MCP (which can't speak the ws multiplex protocol):
+
+      GET  text/event-stream → live SSE stream; `?tail=N` replays the last
+           N buffered messages before tailing live (default 0 = live only).
+      GET  otherwise         → JSON array of the recent history buffer
+           (`?tail=N` caps it; default all).
+      POST                   → publish the JSON body, gated by the socket's
+           clientPublish policy and validated against its schema.
+
+    Loads the socket module on first hit (same cache the ws path uses) so
+    its defineSocket call populates the registry.
+    */
+    async function rest(req: Request, name: string): Promise<Response> {
+        const loader = ensureLoaded(name)
+        if (!loader) {
+            return error(404)
+        }
+        try {
+            await loader
+        } catch (loadError) {
+            log.error(loadError)
+            return error(500, 'socket failed to load')
+        }
+        const entry = lookupSocket(name)
+        if (!entry) {
+            return error(404)
+        }
+        const tailParam = new URL(req.url).searchParams.get('tail')
+        const count = tailParam !== null ? Number(tailParam) : undefined
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            if ((req.headers.get('accept') ?? '').includes('text/event-stream')) {
+                return sse(entry.socket.tail(count ?? 0))
+            }
+            return json(recentHistory(entry, count))
+        }
+        if (req.method === 'POST') {
+            if (!entry.allowClientPublish) {
+                return error(403, 'publishing not allowed')
+            }
+            let message: unknown
+            try {
+                message = await req.json()
+            } catch {
+                return error(400, 'body must be JSON')
+            }
+            try {
+                // publish() validates against the socket schema and throws on a bad payload.
+                entry.socket.publish(message)
+            } catch (publishError) {
+                return error(
+                    422,
+                    publishError instanceof Error ? publishError.message : String(publishError),
+                )
+            }
+            return json({ ok: true })
+        }
+        return error(405, undefined, { headers: { Allow: 'GET, POST' } })
+    }
+
+    return {
+        rest,
+
+        open(ws) {
+            connections.set(ws, { subToSocket: new Map(), socketSubs: new Map() })
+        },
+
+        message(ws, data) {
+            const state = connections.get(ws)
+            if (!state) {
+                return
+            }
+            const text = typeof data === 'string' ? data : textDecoder.decode(data)
+            let frame: SocketClientFrame
+            try {
+                frame = JSON.parse(text) as SocketClientFrame
+            } catch {
+                return
+            }
+            if (frame.type === 'sub') {
+                void handleSub(ws, state, frame)
+                return
+            }
+            if (frame.type === 'unsub') {
+                handleUnsub(ws, state, frame)
+                return
+            }
+            if (frame.type === 'pub') {
+                void handlePub(ws, frame)
+                return
+            }
+        },
+
+        close(ws) {
+            const state = connections.get(ws)
+            if (!state) {
+                return
+            }
+            connections.delete(ws)
+            for (const name of state.socketSubs.keys()) {
+                ws.unsubscribe(`socket:${name}`)
+            }
+        },
+    }
+}

package/src/lib/server/sockets/defineSocket.ts

@@ -0,0 +1,167 @@
+import { createPushIterator } from '../../shared/createPushIterator.ts'
+import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
+import { getActiveServer } from '../runtime/getActiveServer.ts'
+import { registerSocket } from './registerSocket.ts'
+import type { Socket } from './types/Socket.ts'
+import type { SocketOptions } from './types/SocketOptions.ts'
+
+/*
+Server-side construction of a Socket. The bundler rewrites every
+`export const NAME = socket(opts)` inside `src/server/sockets/<file>.ts` into
+`__belteDefineSocket__("<name>", opts)` so the file path becomes the
+socket's identity. Each subscriber gets its own queue + notifier, the
+optional history buffer is shared, and outbound fan-out rides Bun's
+native `server.publish` so connected ws clients are notified by the
+runtime in C rather than per-client iteration in JS.
+
+The Socket itself is the AsyncIterable: `for await (const m of chat)`
+replays the full history buffer then tails live. `chat.tail(count)`
+opens a subscription that replays the last `count` items (default `0`,
+clamped to the configured `history` max). When `ttl` is set, history
+entries older than `ttl` ms are evicted lazily on every read/append —
+no timer runs in the background. `chat.publish(m)` is isomorphic —
+called server-side it both notifies in-process iterators and broadcasts
+to remote subscribers; called client-side (via socketProxy) it sends a
+`pub` frame the dispatcher validates and forwards.
+*/
+export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<T> {
+    const historySize = opts.history ?? 0
+    const ttl = opts.ttl
+    const schema = opts.schema
+    /*
+    A schema makes the socket's payload safe to advertise to non-browser
+    surfaces, so it flips mcp/cli on by default — exposing the `tail` read
+    tool (and `publish` when clientPublish is set). Explicit `clients` wins.
+    */
+    const hasSchema = schema !== undefined
+    const clients = resolveClientFlags(opts.clients, { mcp: hasSchema, cli: hasSchema })
+    type BufferEntry = { value: T; expiresAt: number | undefined }
+    const buffer: BufferEntry[] = []
+    const subscribers = new Set<(message: T) => void>()
+    const topic = `socket:${name}`
+
+    /*
+    History entries are stored with an expiry timestamp. When `ttl` is set,
+    every read/append starts by dropping leading entries whose expiry has
+    passed — entries are appended in order so the expired prefix is
+    contiguous. No timer/setInterval is needed: expiry is lazy.
+    */
+    function pruneExpired(now: number): void {
+        if (ttl === undefined) {
+            return
+        }
+        let drop = 0
+        for (const entry of buffer) {
+            if (entry.expiresAt !== undefined && entry.expiresAt <= now) {
+                drop++
+            } else {
+                break
+            }
+        }
+        if (drop > 0) {
+            buffer.splice(0, drop)
+        }
+    }
+
+    /*
+    Active server is set once per process during createServer's boot,
+    immediately after Bun.serve resolves, and never reassigned. Resolve
+    it lazily on the first publish then keep the reference so subsequent
+    publishes skip the per-call getter.
+    */
+    let cachedServer: ReturnType<typeof getActiveServer>
+    /*
+    When a schema is attached, publish() validates synchronously and
+    throws on bad payloads. Standard Schema's validate() is generally
+    async — but for the synchronous server-side publish path we treat
+    a Promise return as a programming error (publish must be sync to
+    preserve in-process notify ordering). Schemas that need async
+    refinement should pre-validate at the call site instead.
+    */
+    function validateSync(message: T): T {
+        if (!schema) {
+            return message
+        }
+        const result = schema['~standard'].validate(message)
+        if (result instanceof Promise) {
+            throw new Error(
+                `[belte] socket "${name}" schema returned a Promise — sockets require sync validation`,
+            )
+        }
+        if (result.issues) {
+            throw new Error(
+                `[belte] socket "${name}" publish payload failed validation: ${JSON.stringify(result.issues)}`,
+            )
+        }
+        return result.value as T
+    }
+    function publish(message: T): void {
+        const validated = validateSync(message)
+        if (historySize > 0) {
+            const now = Date.now()
+            pruneExpired(now)
+            buffer.push({ value: validated, expiresAt: ttl === undefined ? undefined : now + ttl })
+            if (buffer.length > historySize) {
+                buffer.shift()
+            }
+        }
+        for (const notify of subscribers) {
+            notify(validated)
+        }
+        if (cachedServer === undefined) {
+            cachedServer = getActiveServer()
+        }
+        const server = cachedServer
+        if (server) {
+            server.publish(topic, JSON.stringify({ type: 'msg', socket: name, message: validated }))
+        }
+    }
+
+    /*
+    replay === 'all' replays the entire buffer (bare `for await`);
+    a number replays the last min(count, buffer.length) items.
+    */
+    function iterate(replay: number | 'all'): AsyncIterable<T> {
+        return {
+            [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+                let subscriber: ((message: T) => void) | undefined
+                const iter = createPushIterator<T>(() => {
+                    if (subscriber) {
+                        subscribers.delete(subscriber)
+                    }
+                })
+                pruneExpired(Date.now())
+                const replayCount =
+                    replay === 'all' ? buffer.length : Math.min(replay, buffer.length)
+                if (replayCount > 0) {
+                    const start = buffer.length - replayCount
+                    for (let index = start; index < buffer.length; index++) {
+                        iter.push((buffer[index] as BufferEntry).value)
+                    }
+                }
+                subscriber = (message: T) => iter.push(message)
+                subscribers.add(subscriber)
+                return iter
+            },
+        }
+    }
+
+    const self: Socket<T> = {
+        name,
+        clients,
+        publish,
+        tail: (count = 0) => iterate(count),
+        [Symbol.asyncIterator]: () => iterate('all')[Symbol.asyncIterator](),
+    }
+    registerSocket({
+        socket: self as Socket<unknown>,
+        allowClientPublish: opts.clientPublish ?? false,
+        schema,
+        clients,
+        snapshotHistory: () => {
+            pruneExpired(Date.now())
+            return buffer.map((entry) => entry.value)
+        },
+    })
+    return self
+}

package/src/lib/server/sockets/lookupSocket.ts

@@ -0,0 +1,6 @@
+import { socketRegistry } from './socketRegistry.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+export function lookupSocket(name: string): SocketRegistryEntry | undefined {
+    return socketRegistry.get(name)
+}

package/src/lib/server/sockets/recentHistory.ts

@@ -0,0 +1,11 @@
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Recent slice of a socket's history buffer: the last `count` messages, or
+the whole buffer when `count` is undefined. Shared by the sockets HTTP
+`rest()` face and the MCP `<base>-tail` tool so the two can't drift.
+*/
+export function recentHistory(entry: SocketRegistryEntry, count: number | undefined): unknown[] {
+    const history = entry.snapshotHistory()
+    return count === undefined ? history : history.slice(Math.max(0, history.length - count))
+}

package/src/lib/server/sockets/registerSocket.ts

@@ -0,0 +1,6 @@
+import { socketRegistry } from './socketRegistry.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+export function registerSocket(entry: SocketRegistryEntry): void {
+    socketRegistry.set(entry.socket.name, entry)
+}

package/src/lib/server/sockets/socketOperations.ts

@@ -0,0 +1,35 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import type { SocketOperation } from './types/SocketOperation.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Projects a socket registry entry into the operations it exposes to the
+CLI and MCP. Single source for the naming convention (`<base>-tail` /
+`<base>-publish`), the existence rule (tail always; publish only when the
+socket allows client publishing), and each operation's HTTP face — so the
+CLI manifest builder, the MCP tool list, and the MCP tool dispatcher can't
+disagree about which operations a socket has or what they're called.
+*/
+export function socketOperations(entry: SocketRegistryEntry): SocketOperation[] {
+    const base = commandNameForUrl(entry.socket.name)
+    const restUrl = `/__belte/sockets/${entry.socket.name}`
+    const operations: SocketOperation[] = [
+        {
+            kind: 'tail',
+            name: `${base}-tail`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'GET',
+        },
+    ]
+    if (entry.allowClientPublish) {
+        operations.push({
+            kind: 'publish',
+            name: `${base}-publish`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'POST',
+        })
+    }
+    return operations
+}

package/src/lib/server/sockets/socketRegistry.ts

@@ -0,0 +1,9 @@
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Process-wide registry of every Socket declared in the app. defineSocket
+inserts on first construction; the dispatcher reads on every `sub` /
+`pub` frame so it can find the right Socket by name and check the
+opted-in `allowClientPublish` policy.
+*/
+export const socketRegistry = new Map<string, SocketRegistryEntry>()

package/src/lib/server/sockets/types/Socket.ts

@@ -0,0 +1,21 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+
+/*
+Bidirectional named broadcast primitive. Declared once with `socket<T>()`
+inside a file under `src/server/sockets/`; the same import resolves to a server-side
+fan-out and a client-side ws proxy by build target. Iterating the socket
+opens a subscription with full history replay if the topic was declared
+with `{ history: n }`. `.tail(count)` opens one that replays the last
+`count` items (default `0`, clamped to the topic's history max) before
+tailing live. `publish` is isomorphic: server code publishes in-process
+and fans out to remote subscribers; client code sends a `pub` frame the
+dispatcher validates against the topic's `clientPublish` flag. `clients`
+exposes which adapter surfaces (browser / mcp / cli) advertise this
+socket.
+*/
+export interface Socket<T> extends AsyncIterable<T> {
+    readonly name: string
+    readonly clients: ClientFlags
+    publish(message: T): void
+    tail(count?: number): AsyncIterable<T>
+}

package/src/lib/server/sockets/types/SocketClientFrame.ts

@@ -0,0 +1,18 @@
+/*
+Wire frame the browser sends over the multiplexed socket connection.
+`sub` opens a subscription against `socket`. The optional `replay`
+controls history: omitted = full replay (default `for await`); a
+number = at most that many trailing items (clamped server-side to the
+topic's history max). `unsub` closes one. `pub` publishes a message —
+the dispatcher checks the topic's `clientPublish` flag before fanning
+out.
+
+`sub` is the per-subscription id minted client-side; the server treats
+it as opaque and routes inbound `msg|err|end` frames back to the same
+id so one ws can multiplex many subscriptions to the same or different
+sockets.
+*/
+export type SocketClientFrame =
+    | { type: 'sub'; sub: string; socket: string; replay?: number }
+    | { type: 'unsub'; sub: string }
+    | { type: 'pub'; socket: string; message: unknown }

package/src/lib/server/sockets/types/SocketOperation.ts

@@ -0,0 +1,22 @@
+import type { HttpVerb } from '../../../shared/types/HttpVerb.ts'
+
+/*
+One operation a socket exposes to the non-browser surfaces. A socket
+always offers a `tail` (read recent / stream live) and, when
+`clientPublish` is set, a `publish` (send a message). This is the shared
+skeleton — name, kind, HTTP face — that the CLI manifest, the MCP tool
+list, and the MCP dispatcher all read instead of re-deriving the naming
+convention and existence rule independently. Each surface dresses it with
+its own presentation (descriptions, input schema, annotations).
+*/
+export type SocketOperation = {
+    kind: 'tail' | 'publish'
+    // Command/tool name: the socket's command-name base plus `-tail` / `-publish`.
+    name: string
+    // Raw socket name, for the HTTP path and human-facing descriptions.
+    socketName: string
+    // HTTP face of the operation: `/__belte/sockets/<name>`.
+    restUrl: string
+    // GET for tail, POST for publish.
+    method: HttpVerb
+}

package/src/lib/server/sockets/types/SocketOptions.ts

@@ -0,0 +1,22 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
+
+/*
+Server-side options passed when declaring a socket via `socket<T>(opts)`.
+History buffer (replayed on first iteration), per-frame TTL (history
+entries older than `ttl` ms are evicted before replay), and the client-
+publish gate (off by default — server-only topics ignore pub frames
+coming over the wire). Optional Standard Schema validates payloads on
+publish and gives MCP / CLI a typed payload to describe (projected via the
+schema's own `toJSONSchema()` — wrap with withJsonSchema if its library lacks
+one). `clients` controls which non-browser surfaces (mcp / cli) expose this
+socket; browser is the historical default. All server-only state the bundler
+strips out of the client stub.
+*/
+export type SocketOptions<Schema extends StandardSchemaV1 = StandardSchemaV1> = {
+    history?: number
+    ttl?: number
+    clientPublish?: boolean
+    schema?: Schema
+    clients?: Partial<ClientFlags>
+}

package/src/lib/server/sockets/types/SocketRegistryEntry.ts

@@ -0,0 +1,17 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
+import type { Socket } from './Socket.ts'
+
+/*
+Per-socket registry record. The Socket itself stays uniform between
+server and client by parking policy state (history snapshot, client
+publish gate, payload schema, client targeting) here instead of leaking
+into the public Socket shape.
+*/
+export type SocketRegistryEntry = {
+    socket: Socket<unknown>
+    allowClientPublish: boolean
+    schema: StandardSchemaV1 | undefined
+    clients: ClientFlags
+    snapshotHistory(): unknown[]
+}

package/src/lib/server/sockets/types/SocketRoutes.ts

@@ -0,0 +1,10 @@
+import type { Socket } from './Socket.ts'
+
+/*
+Manifest of socket-name → module loader. Produced by the resolver
+plugin from each `.ts` under src/server/sockets/. Each module has exactly one
+named export, a Socket whose `.name` was stamped in by the bundler
+rewrite. The dispatcher imports a module on first access and caches the
+resolved Socket against its name.
+*/
+export type SocketRoutes = Record<string, () => Promise<Record<string, Socket<unknown>>>>