@abide/abide 0.28.0

package/src/lib/shared/writeRoutesDts.ts

@@ -0,0 +1,73 @@
+import { pageUrlForFile } from './pageUrlForFile.ts'
+import { parseRouteSegments } from './parseRouteSegments.ts'
+import { writeDts } from './writeDts.ts'
+
+/*
+Walks a `[name]` / `[...rest]` route URL and returns the param shape it
+declares. Catch-all segments map to `string` under their declared name —
+the server's toBunRoutePattern renames Bun's `*` key back to that name
+when dispatching, so the page component sees `params.rest`, not
+`params['*']`.
+*/
+function paramsForRoute(routeUrl: string): Record<string, 'string'> {
+    return Object.fromEntries(
+        parseRouteSegments(routeUrl)
+            .filter((segment) => segment.kind === 'param')
+            .map((segment) => [segment.name, 'string'] as const),
+    )
+}
+
+function renderParamsShape(shape: Record<string, 'string'>): string {
+    const keys = Object.keys(shape)
+    if (keys.length === 0) {
+        return 'Record<string, never>'
+    }
+    return `{ ${keys.map((key) => `${JSON.stringify(key)}: string`).join('; ')} }`
+}
+
+/*
+Emits a `.d.ts` that augments abide's `Routes` interface with one entry per
+page file in the project. Page picks this up as a discriminated union keyed
+on `route`, so `if (page.route === '/media/[id]') page.params.id` is typed
+automatically without consumers writing route types by hand.
+The file is written to `src/.abide/routes.d.ts` so the consumer's existing
+src tsconfig include picks it up with no extra configuration. The augmented
+module is keyed on the name the project imports abide under (`importName`),
+so the augmentation matches the consumer's `page` import whether abide is
+installed directly (`abide`) or behind an alias.
+*/
+export async function writeRoutesDts({
+    cwd,
+    pageFiles,
+    importName,
+}: {
+    cwd: string
+    pageFiles: string[]
+    importName: string
+}): Promise<void> {
+    const routes = pageFiles
+        .map((file) => ({
+            route: pageUrlForFile(file),
+            params: paramsForRoute(pageUrlForFile(file)),
+        }))
+        .toSorted((a, b) => a.route.localeCompare(b.route))
+    const entries = routes
+        .map(
+            ({ route, params }) => `        ${JSON.stringify(route)}: ${renderParamsShape(params)}`,
+        )
+        .join('\n')
+    /* Keys-only mirror for url()'s autocomplete (values unused — PathParams derives the shape). */
+    const urlKeys = routes.map(({ route }) => `        ${JSON.stringify(route)}: true`).join('\n')
+    const body = `declare module '${importName}/shared/page' {
+    interface Routes {
+${entries}
+    }
+}
+
+declare module '${importName}/shared/url' {
+    interface PageRoutes {
+${urlKeys}
+    }
+}`
+    await writeDts(cwd, 'routes', body)
+}

package/src/lib/shared/writeRpcDts.ts

@@ -0,0 +1,49 @@
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
+import { detectVerbMethod } from './detectVerbMethod.ts'
+import { fileStem } from './fileStem.ts'
+import { rpcUrlForFile } from './rpcUrlForFile.ts'
+import { writeDts } from './writeDts.ts'
+
+/*
+Emits a `.d.ts` that augments abide's `RpcRoutes` interface with one entry per
+query-carrying $rpc verb, so `url('/rpc/search', { q })` types its args against
+the verb's own signature. Only GET/DELETE/HEAD (non-body) verbs are included —
+a url() can carry a query string but not a request body, so a POST verb has no
+URL form. `RpcArgs` lifts the args type out of the verb's RemoteFunction
+(dropping the FormData upload variant); the file path resolves the export by
+its filename, the abide one-export-per-file convention. Written to
+`src/.abide/rpc.d.ts` so the consumer's src tsconfig include picks it up, keyed
+on the project's abide import name like writeRoutesDts.
+*/
+export async function writeRpcDts({
+    cwd,
+    rpcDir,
+    rpcFiles,
+    importName,
+}: {
+    cwd: string
+    rpcDir: string
+    rpcFiles: string[]
+    importName: string
+}): Promise<void> {
+    const lines = await Promise.all(
+        rpcFiles.map(async (file) => {
+            const method = detectVerbMethod(await Bun.file(`${rpcDir}/${file}`).text())
+            // A body verb's args can't ride a URL — leave it out of the url() rpc map.
+            if (!method || carriesBodyArgs(method)) {
+                return undefined
+            }
+            const importPath = `../server/rpc/${file}`
+            return `        ${JSON.stringify(rpcUrlForFile(file))}: RpcArgs<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`
+        }),
+    )
+    const entries = lines.filter((line) => line !== undefined).toSorted()
+    const body = `type RpcArgs<Fn> = Fn extends (args: infer Args) => unknown ? Exclude<Args, FormData> : never
+
+declare module '${importName}/shared/url' {
+    interface RpcRoutes {
+${entries.join('\n')}
+    }
+}`
+    await writeDts(cwd, 'rpc', body)
+}

package/src/lib/shared/writeTestRpcDts.ts

@@ -0,0 +1,45 @@
+import { commandNameForUrl } from './commandNameForUrl.ts'
+import { fileStem } from './fileStem.ts'
+import { rpcUrlForFile } from './rpcUrlForFile.ts'
+import { writeDts } from './writeDts.ts'
+
+/*
+Emits a `.d.ts` that augments createTestApp's `RpcClient` interface with one
+entry per $rpc verb, keyed by command name (the same key `app.rpc.<name>`
+resolves at runtime). Each entry lifts the verb's args + resolved return out of
+its RemoteFunction so `app.rpc.getProduct({ id })` types against the verb's own
+signature — args in, decoded body out, plus `.raw` for the Response. `RpcArgs`
+drops the FormData upload variant exactly as writeRpcDts does; `RpcReturn`
+reads the resolved body type. Written to `src/.abide/testRpc.d.ts` so the
+consumer's src tsconfig include picks it up, keyed on the project's abide
+import name.
+*/
+export async function writeTestRpcDts({
+    cwd,
+    rpcFiles,
+    importName,
+}: {
+    cwd: string
+    rpcFiles: string[]
+    importName: string
+}): Promise<void> {
+    const entries = rpcFiles
+        .map((file) => {
+            const name = commandNameForUrl(rpcUrlForFile(file))
+            const importPath = `../server/rpc/${file}`
+            return `        ${JSON.stringify(name)}: RpcInvoker<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`
+        })
+        .toSorted()
+    const body = `type RpcArgs<Fn> = Fn extends (args: infer Args) => unknown ? Exclude<Args, FormData> : never
+type RpcReturn<Fn> = Fn extends (...args: never[]) => Promise<infer Return> ? Return : never
+type RpcInvoker<Fn> = ((args?: RpcArgs<Fn>) => Promise<RpcReturn<Fn>>) & {
+    raw: (args?: RpcArgs<Fn>) => Promise<Response>
+}
+
+declare module '${importName}/test/createTestApp' {
+    interface RpcClient {
+${entries.join('\n')}
+    }
+}`
+    await writeDts(cwd, 'testRpc', body)
+}

package/src/lib/shared/writeTestSocketsDts.ts

@@ -0,0 +1,34 @@
+import { fileStem } from './fileStem.ts'
+import { socketNameForFile } from './socketNameForFile.ts'
+import { writeDts } from './writeDts.ts'
+
+/*
+Emits a `.d.ts` that augments createTestApp's `SocketClient` interface with one
+entry per $socket, keyed by socket name (the same key `app.sockets.<name>`
+resolves at runtime). The `socket(...)` helper statically returns `Socket<T>`,
+so each entry is the export's own type directly — `app.sockets.chat` types as
+`Socket<ChatMessage>`, iterable for the live stream with `.tail`/`.publish`.
+Written to `src/.abide/testSockets.d.ts` like its rpc sibling.
+*/
+export async function writeTestSocketsDts({
+    cwd,
+    socketFiles,
+    importName,
+}: {
+    cwd: string
+    socketFiles: string[]
+    importName: string
+}): Promise<void> {
+    const entries = socketFiles
+        .map((file) => {
+            const importPath = `../server/sockets/${file}`
+            return `        ${JSON.stringify(socketNameForFile(file))}: typeof import(${JSON.stringify(importPath)}).${fileStem(file)}`
+        })
+        .toSorted()
+    const body = `declare module '${importName}/test/createTestApp' {
+    interface SocketClient {
+${entries.join('\n')}
+    }
+}`
+    await writeDts(cwd, 'testSockets', body)
+}

package/src/lib/test/assertAgentFrameConformance.ts

@@ -0,0 +1,73 @@
+import type { AgentFrame } from '../server/agent.ts'
+
+/*
+Collects an engine's frame stream and asserts the neutral AgentFrame contract
+every provider engine must satisfy, throwing a plain Error (test-framework
+agnostic) on the first violation:
+
+  - the stream ends with exactly one `done` frame and yields nothing after it
+  - every `tool_use` is answered by exactly one `tool_result` carrying the
+    same id and name, in use-then-result order
+  - no `tool_result` arrives for an unannounced id
+  - text deltas are strings
+
+Returns the collected frames plus the `done` frame so a scenario can layer
+its provider-specific assertions on top. This is the conformance seam: one
+suite of invariants, N engine adapters run against it.
+*/
+// @readme plumbing
+export async function assertAgentFrameConformance(
+    stream: AsyncIterable<AgentFrame>,
+): Promise<{ frames: AgentFrame[]; done: Extract<AgentFrame, { type: 'done' }> }> {
+    const frames: AgentFrame[] = []
+    for await (const frame of stream) {
+        frames.push(frame)
+    }
+    if (frames.length === 0) {
+        throw new Error('conformance: engine yielded no frames — expected at least a done frame')
+    }
+
+    const doneIndexes = frames.flatMap((frame, index) => (frame.type === 'done' ? [index] : []))
+    if (doneIndexes.length !== 1) {
+        throw new Error(`conformance: expected exactly one done frame, saw ${doneIndexes.length}`)
+    }
+    if (doneIndexes[0] !== frames.length - 1) {
+        throw new Error(
+            `conformance: frames continued after done (done at ${doneIndexes[0]} of ${frames.length - 1})`,
+        )
+    }
+
+    const openToolUses = new Map<string, string>()
+    for (const [index, frame] of frames.entries()) {
+        if (frame.type === 'text' && typeof frame.delta !== 'string') {
+            throw new Error(`conformance: text frame at ${index} has a non-string delta`)
+        }
+        if (frame.type === 'tool_use') {
+            if (openToolUses.has(frame.id)) {
+                throw new Error(`conformance: duplicate tool_use id ${frame.id} at ${index}`)
+            }
+            openToolUses.set(frame.id, frame.name)
+        }
+        if (frame.type === 'tool_result') {
+            const expectedName = openToolUses.get(frame.id)
+            if (expectedName === undefined) {
+                throw new Error(
+                    `conformance: tool_result at ${index} answers unannounced id ${frame.id}`,
+                )
+            }
+            if (frame.name !== expectedName) {
+                throw new Error(
+                    `conformance: tool_result at ${index} names ${frame.name}, tool_use said ${expectedName}`,
+                )
+            }
+            openToolUses.delete(frame.id)
+        }
+    }
+    if (openToolUses.size > 0) {
+        const unanswered = Array.from(openToolUses.keys()).join(', ')
+        throw new Error(`conformance: tool_use without a tool_result: ${unanswered}`)
+    }
+
+    const done = frames[frames.length - 1] as Extract<AgentFrame, { type: 'done' }>
+    return { frames, done }
+}

package/src/lib/test/createScriptedSurface.ts

@@ -0,0 +1,45 @@
+import type { ToolResult } from '../mcp/mcpSurface.ts'
+import type { AgentSurface } from '../server/agent.ts'
+
+type ScriptedTool = {
+    name: string
+    description?: string
+    inputSchema?: Record<string, unknown>
+    /* Result handed back to the engine; throw to simulate a failed dispatch. */
+    result: (args: Record<string, unknown> | undefined) => ToolResult
+}
+
+type RecordedCall = { name: string; args: Record<string, unknown> | undefined }
+
+/*
+A scripted AgentSurface for engine tests: declarative tool stubs in, an MCP
+surface out, with every `call` recorded so a test can assert exactly which
+tools an engine dispatched and with what arguments. Prompts and resources are
+empty — engines must tolerate an app exposing none.
+*/
+// @readme plumbing
+export function createScriptedSurface(
+    tools: ScriptedTool[] = [],
+): AgentSurface & { calls: RecordedCall[] } {
+    const calls: RecordedCall[] = []
+    return {
+        calls,
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description ?? tool.name,
+            inputSchema: tool.inputSchema ?? { type: 'object' },
+        })),
+        async call(name, args) {
+            calls.push({ name, args })
+            const tool = tools.find((candidate) => candidate.name === name)
+            if (!tool) {
+                return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true }
+            }
+            return tool.result(args)
+        },
+        prompts: [],
+        getPrompt: () => [],
+        listResources: async () => [],
+        readResource: async () => undefined,
+    }
+}

package/src/lib/test/createTestApp.ts

@@ -0,0 +1,203 @@
+import type { Server } from 'bun'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import * as appMod from '../../_virtual/app.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { appInfo } from '../../_virtual/app-info.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { assets } from '../../_virtual/assets.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import cliProgramName from '../../_virtual/cli-name.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { layouts } from '../../_virtual/layouts.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import mcp from '../../_virtual/mcp.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { mcpResources } from '../../_virtual/mcp-resources.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { pages } from '../../_virtual/pages.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { prompts } from '../../_virtual/prompts.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { publicAssets } from '../../_virtual/public-assets.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { rpc } from '../../_virtual/rpc.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { shell } from '../../_virtual/shell.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { sockets } from '../../_virtual/sockets.ts'
+import { verbRegistry } from '../server/rpc/verbRegistry.ts'
+import { createServer } from '../server/runtime/createServer.ts'
+import { ensureRegistriesLoaded } from '../server/runtime/registryManifests.ts'
+import { requestContext } from '../server/runtime/requestContext.ts'
+import { resolvePageSnapshot } from '../server/runtime/resolvePageSnapshot.ts'
+import { serverSlot } from '../server/runtime/serverSlot.ts'
+import type { Socket } from '../server/sockets/types/Socket.ts'
+import { baseSlot } from '../shared/baseSlot.ts'
+import { buildRpcProxy } from '../shared/buildRpcProxy.ts'
+import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
+import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
+import { createCacheStore } from '../shared/createCacheStore.ts'
+import { globalCacheStoreSlot } from '../shared/globalCacheStoreSlot.ts'
+import { HEALTH_PATH } from '../shared/HEALTH_PATH.ts'
+import { pageSlot } from '../shared/pageSlot.ts'
+import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
+import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+import { createTestSocketChannel } from './createTestSocketChannel.ts'
+
+/*
+Augmentable verb/socket maps for `app.rpc.<verb>` / `app.sockets.<name>`. The
+build's writeTestRpcDts / writeTestSocketsDts emit one entry per verb/socket
+(into src/.abide/), so the keys + signatures are the project's real surface
+with no imports. Empty here; types arrive once the app has been built. Mirrors
+url's RpcRoutes / health's AppHealthMap.
+*/
+// @readme testing
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated testRpc.d.ts
+export interface RpcClient {}
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated testSockets.d.ts
+export interface SocketClient {}
+
+/* The booted app under test. Every named subsystem is reachable as the verb
+   you call, the socket you iterate, or a path you fetch — over the real
+   server, so the full pipeline (CSRF, cookies, base path) runs. */
+export type TestApp = {
+    /* The kernel-assigned origin, e.g. http://localhost:51234. */
+    origin: string
+    /* fetch against the app: prefixes the kernel-assigned origin, so you pass a
+       route-space path (`/products/1`), not the wire URL. The booted server
+       matches routes at raw paths — the APP_URL mount base is stripped by an
+       external proxy in production, absent here — so paths carry no base. */
+    fetch: (path: string, init?: RequestInit) => Promise<Response>
+    /* Verb calls over HTTP, keyed by command name: `app.rpc.getProduct({ id })`. */
+    rpc: RpcClient
+    /* Sockets keyed by name: `app.sockets.ticker` is the Socket — iterate it for
+       the live stream, `.tail(n)` to seed, `.publish(m)` to send. */
+    sockets: SocketClient
+    /* The /__abide/health payload, decoded. */
+    health: () => Promise<unknown>
+    /* Stops the server, releases the port, restores every touched slot. */
+    stop: () => Promise<void>
+    /* `await using app = await createTestApp()` — disposal runs stop(), so a
+       thrown assertion still releases the port and restores the slots rather
+       than leaking the request-scope/cache/page resolvers into the next file. */
+    [Symbol.asyncDispose]: () => Promise<void>
+}
+
+/*
+Boots the real app on an ephemeral port — the same wiring serverEntry performs,
+minus the standalone-binary env layers. Imports the framework's virtual
+manifests (resolved by abideResolverPlugin, registered via `abide/preload`
+in the consumer's bunfig), so the routes, verbs, and sockets are the project's
+real surface, not a fixture. Pass nothing: `await createTestApp()` is the app
+exactly as `bun start` would serve it.
+
+Slots are saved and restored around the boot so a suite tears down without
+leaking the request-scope/cache/page resolvers into the next test file.
+*/
+export async function createTestApp(): Promise<TestApp> {
+    const previous = {
+        cacheResolver: cacheStoreSlot.resolver,
+        globalResolver: globalCacheStoreSlot.resolver,
+        pageResolver: pageSlot.resolver,
+        baseResolver: baseSlot.resolver,
+        activeServer: serverSlot.active,
+    }
+
+    cacheStoreSlot.resolver = () => requestContext.getStore()?.cache
+    const globalStore = createCacheStore()
+    globalCacheStoreSlot.resolver = () => globalStore
+    pageSlot.resolver = resolvePageSnapshot
+
+    /* Eager env validation, exactly as serverEntry: a top-level env(schema) in
+       src/server/config.ts fails the boot loudly here rather than lazily. No-op
+       when the file is absent. */
+    // @ts-expect-error virtual module resolved by abideResolverPlugin
+    await import('../../_virtual/config.ts')
+
+    const server: Server<unknown> = await createServer({
+        pages,
+        layouts,
+        rpc,
+        sockets,
+        prompts,
+        shell,
+        app: appMod,
+        assets,
+        publicAssets,
+        mcpResources,
+        mcp,
+        cliProgramName,
+        appInfo,
+        port: 0,
+    })
+
+    const origin = `http://localhost:${server.port}`
+
+    function appFetch(path: string, init?: RequestInit): Promise<Response> {
+        return fetch(`${origin}${path}`, init)
+    }
+
+    /* Verb modules loaded once so the registry holds every RemoteFunction; the
+       proxy maps command name → an HTTP call against the booted server. */
+    await ensureRegistriesLoaded()
+    const remotes = new Map<string, RemoteFunction<unknown, unknown>>(
+        Array.from(verbRegistry.values()).map((entry) => [
+            commandNameForUrl(entry.remote.url),
+            entry.remote,
+        ]),
+    )
+
+    function send(remote: RemoteFunction<unknown, unknown>, args: unknown): Promise<Response> {
+        /* Same-origin Origin header so the CSRF gate admits mutating verbs; the
+           server serves verbs at their raw url (no mount base applied here). */
+        const request = buildRpcRequest({
+            method: remote.method,
+            url: remote.url,
+            args,
+            baseUrl: `${origin}/`,
+            headers: new Headers({ origin }),
+        })
+        return fetch(request)
+    }
+
+    const rpcClient = buildRpcProxy<RpcClient>((name) => {
+        const remote = remotes.get(name)
+        return remote ? (args) => send(remote, args) : undefined
+    })
+
+    /* One ws to the booted multiplex, dialed lazily on first socket access so a
+       suite touching no socket holds no connection. http→ws, raw path. */
+    const wsUrl = `${origin.replace(/^http/, 'ws')}${SOCKETS_PATH}`
+    let channel: ReturnType<typeof createTestSocketChannel> | undefined
+    const socketNames = new Set(Object.keys(sockets as Record<string, unknown>))
+    const socketClient = new Proxy({} as Record<string, Socket<unknown>>, {
+        get(_target, prop): Socket<unknown> | undefined {
+            if (typeof prop !== 'string' || !socketNames.has(prop)) {
+                return undefined
+            }
+            channel ??= createTestSocketChannel(wsUrl)
+            return channel.socket(prop)
+        },
+    })
+
+    async function stop(): Promise<void> {
+        channel?.close()
+        server.stop(true)
+        cacheStoreSlot.resolver = previous.cacheResolver
+        globalCacheStoreSlot.resolver = previous.globalResolver
+        pageSlot.resolver = previous.pageResolver
+        baseSlot.resolver = previous.baseResolver
+        serverSlot.active = previous.activeServer
+    }
+
+    return {
+        origin,
+        fetch: appFetch,
+        rpc: rpcClient,
+        sockets: socketClient as unknown as SocketClient,
+        health: () => appFetch(HEALTH_PATH).then((response) => response.json()),
+        stop,
+        [Symbol.asyncDispose]: stop,
+    }
+}

package/src/lib/test/createTestSocketChannel.ts

@@ -0,0 +1,142 @@
+import type { Socket } from '../server/sockets/types/Socket.ts'
+import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
+import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
+import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
+import type { SocketChannel } from '../shared/types/SocketChannel.ts'
+import type { SocketSubCallbacks } from '../shared/types/SocketSubCallbacks.ts'
+
+/*
+Test-side substitute for the browser socketChannel: one ws to the booted
+server's multiplex, speaking the same SocketClientFrame/SocketServerFrame
+protocol. Stripped of the browser channel's reconnect/backoff/visibility
+machinery — a test owns the connection lifecycle through `close()`, so a drop
+is teardown, not something to recover from. Frames sent before the ws opens
+queue and flush on open, the one piece of timing a test can't sidestep.
+
+Implements SocketChannel (subscribe/unsubscribe/publish), so `socket(name)`
+hands its sockets to the same buildSocketOverChannel the browser socketProxy
+uses — the Socket<T> surface can't drift between the test path and production.
+*/
+export function createTestSocketChannel(wsUrl: string): {
+    socket: <T>(name: string) => Socket<T>
+    close: () => void
+    /* `using channel = createTestSocketChannel(url)` — disposal closes the ws. */
+    [Symbol.dispose]: () => void
+} {
+    const subs = new Map<string, { socket: string; callbacks: SocketSubCallbacks }>()
+    const subsBySocket = new Map<string, Set<string>>()
+    let pendingSends: string[] = []
+
+    const ws = new WebSocket(wsUrl)
+
+    function flushPending(): void {
+        if (ws.readyState !== WebSocket.OPEN) {
+            return
+        }
+        for (const message of pendingSends) {
+            ws.send(message)
+        }
+        pendingSends = []
+    }
+
+    function send(frame: SocketClientFrame): void {
+        const message = JSON.stringify(frame)
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(message)
+            return
+        }
+        pendingSends.push(message)
+    }
+
+    function dropSub(id: string): void {
+        const entry = subs.get(id)
+        if (!entry) {
+            return
+        }
+        subs.delete(id)
+        const set = subsBySocket.get(entry.socket)
+        if (set) {
+            set.delete(id)
+            if (set.size === 0) {
+                subsBySocket.delete(entry.socket)
+            }
+        }
+    }
+
+    ws.addEventListener('open', flushPending)
+    ws.addEventListener('message', (event) => {
+        let frame: SocketServerFrame
+        try {
+            frame = JSON.parse(event.data as string) as SocketServerFrame
+        } catch {
+            return
+        }
+        if (frame.type === 'msg') {
+            const targets = subsBySocket.get(frame.socket)
+            if (!targets) {
+                return
+            }
+            for (const subId of targets) {
+                subs.get(subId)?.callbacks.onMessage(frame.message)
+            }
+            return
+        }
+        if (frame.type === 'replay') {
+            subs.get(frame.sub)?.callbacks.onReplay(frame.messages)
+            return
+        }
+        const sub = subs.get(frame.sub)
+        if (!sub) {
+            return
+        }
+        dropSub(frame.sub)
+        if (frame.type === 'end') {
+            sub.callbacks.onEnd()
+        } else {
+            sub.callbacks.onError(frame.message)
+        }
+    })
+    /* A drop after subs are live is unexpected; surface it so iterators unblock
+       instead of awaiting a frame that never comes. Idempotent — the first of
+       error/close clears subs, the second finds none. error covers a failed
+       handshake (no open, no clean close) that close alone would miss. */
+    function disconnectAll(): void {
+        const active = [...subs.values()]
+        subs.clear()
+        subsBySocket.clear()
+        for (const sub of active) {
+            sub.callbacks.onDisconnect()
+        }
+    }
+    ws.addEventListener('close', disconnectAll)
+    ws.addEventListener('error', disconnectAll)
+
+    const channel: SocketChannel = {
+        subscribe(id, socket, replay, callbacks) {
+            subs.set(id, { socket, callbacks })
+            let set = subsBySocket.get(socket)
+            if (!set) {
+                set = new Set()
+                subsBySocket.set(socket, set)
+            }
+            set.add(id)
+            send({ type: 'sub', sub: id, socket, replay })
+        },
+        unsubscribe(id) {
+            if (!subs.has(id)) {
+                return
+            }
+            dropSub(id)
+            send({ type: 'unsub', sub: id })
+        },
+        publish: (socket, message) => send({ type: 'pub', socket, message }),
+    }
+
+    /* Same Socket<T> builder the browser proxy uses, over this test channel. */
+    function socket<T>(name: string): Socket<T> {
+        return buildSocketOverChannel<T>(name, () => channel)
+    }
+
+    const close = () => ws.close()
+    return { socket, close, [Symbol.dispose]: close }
+}