@greendrake/rpc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# @greendrake/rpc
+
+Client for the `@greendrake/rpc` wire format, defined below and served by [`@greendrake/rpc-server`](../rpc-server): a typed method-map facade (`RpcClient`), an HTTP transport and a reconnecting WebSocket transport with server push, the error classes both transports map response codes to, a TTL response cache, and a pluggable payload codec. Framework-free; the Vue/Pinia binding (loading state, error UX, connectivity) is `@greendrake/vue-api`, built on this package.
+
+## Install
+
+```sh
+bun add @greendrake/rpc
+```
+
+TypeScript source ships as-is (`src/main.ts` is the entry; no build step, no `.d.ts`), for Vite + Vue 3 apps written in TypeScript. The one runtime dependency, `@greendrake/util` (`NetworkError`, `Emitter`, `safeFetch`, `randomString`), installs with it.
+
+## The wire
+
+This package and `@greendrake/rpc-server` are the two ends of one format; this section defines it. It is deliberately not JSON-RPC. One request envelope, one response envelope, JSON on both transports:
+
+```ts
+interface RpcRequest {
+    method: string
+    nonce?: string // server-side dedup key; omitted on nonce-less calls
+    locale?: string // the caller's UI language tag, when a provider is configured
+    arguments?: unknown[] // omitted when empty
+    [key: string]: unknown // the WebSocket transport adds `id`
+}
+
+interface RpcResponse {
+    success: boolean
+    data?: unknown // on success
+    error?: string // the error code, on failure
+    error_details?: unknown // structured payload attached alongside the code
+}
+```
+
+The WebSocket transport puts an `id` on both directions for correlation and additionally receives server-push frames, `{ type: 'event', event, data }` and bare `{ type, data }`.
+
+`packRequest(method, args, nonce, locale?)` builds the request: a fresh random `nonce` when `nonce` is true, `arguments` only when non-empty, `locale` only when supplied. `settleResponse(response, method)` returns `data` on success or throws the mapped error (see Errors); in a Vite dev build a non-success response is also logged with `console.warn`.
+
+## Typed method map
+
+Declare the API surface once as method name → call signature; every call site infers argument and result types from it.
+
+```ts
+import { HttpTransport, RpcClient } from '@greendrake/rpc'
+
+interface Methods {
+    'user.get': (id: string) => User
+    'user.update': (args: { id: string; name: string }) => void
+    'search.things': (query: { q: string; limit?: number }) => { data: Thing[]; total: number }
+}
+
+const client = new RpcClient<Methods>(new HttpTransport({ url: 'https://api.example.com/v1/api' }))
+
+const user = await client.call('user.get', 'U1') // User
+await client.call('user.update', { id: 'U1', name: 'Ann' })
+```
+
+`new RpcClient<M>(transport, locale?)` — `locale` is `() => string | undefined`, evaluated per call, so a language switch applies from the next call. `call(method, ...args)` is the one way to invoke a method, and every request it sends carries a nonce. `MethodMap` and `MethodMapConstraint<M>` are the constraint types; a plain interface qualifies.
+
+`Transport` is one method, `send(request: RpcRequest): Promise<unknown>`, resolving to the response `data` or rejecting with a mapped error. Anything implementing it plugs into the client.
+
+## HTTP transport
+
+```ts
+import { HttpTransport } from '@greendrake/rpc'
+
+const transport = new HttpTransport({
+    url: 'https://api.example.com/v1/api',
+    headers: () => ({ authorization: `Bearer ${session.token}` }),
+    requestInit: { keepalive: true }
+})
+```
+
+`HttpTransportOptions`:
+
+- `url` — POSTed to for every call.
+- `headers?: HeadersProvider` — `() => Record<string, string>`, evaluated per request so time-variant values (tokens) are always fresh.
+- `codec?: Codec` — applied to the outbound body and the inbound response text (see Codec).
+- `requestInit?: Partial<RequestInit>` — merged into every `fetch` call.
+
+A `fetch` rejection (DNS, refused connection, offline, CORS) surfaces as `@greendrake/util`'s `NetworkError`.
+
+## WebSocket transport
+
+Two layers. `WebSocketPipe` owns the connection lifecycle and raw string frames; `WsTransport` speaks the wire format over it: id-correlated request/response, typed push subscription, and an injected auth handshake re-applied on every reconnect.
+
+```ts
+import { WebSocketPipe, WsTransport, type WsAuthStrategy } from '@greendrake/rpc'
+
+interface Pushes {
+    'thread.message': { thread_id: string; body: string }
+}
+
+const auth: WsAuthStrategy = {
+    authenticate: (send, token) => send({ method: 'auth.token', arguments: [token] }),
+    deauthenticate: send => send({ method: 'auth.logout' })
+}
+
+const transport = new WsTransport<Pushes>({
+    pipe: new WebSocketPipe({ url: 'wss://api.example.com/v1/ws' }),
+    auth
+})
+
+const off = transport.onEvent('thread.message', data => {
+    // data: Pushes['thread.message']
+})
+await transport.authenticate(session.token)
+```
+
+### WebSocketPipe
+
+`WebSocketPipeOptions`:
+
+- `url`
+- `queryAuth?: { param: string; token: string }` — a connection-level credential appended to the URL as a query parameter and resolved by the server at the handshake. Because it rides the URL, reconnects re-authenticate by themselves. For per-session, in-band auth use `WsTransport`'s `auth` instead.
+- `reconnectDelayMs?: (attempt: number) => number` — delay before reconnect attempt N (0-based, reset on a successful open). Default: a constant 3000 ms.
+
+The first attempt starts on `ensureConnected()`, which is also the eager-connect entry point. Every close — including an attempt that never opened — arms the next attempt behind its delay, until `dispose()`. `ensureConnected()` resolves when the current-or-next attempt opens and rejects with that attempt's `WebSocketClosedError` if it fails; a caller arriving after a failure awaits the upcoming attempt.
+
+Members:
+
+- `connected` — the socket is `OPEN`.
+- `send(raw)` — throws unless open.
+- `reconnectNow()` — collapses a waiting reconnect's remaining delay and attempts immediately, for a signal that connectivity is likely back (the `online` event, an app resuming from background). A no-op unless a reconnect is actually waiting.
+- `drop()` — abandons a socket whose peer is gone without a close frame: fails its in-flight calls and arms the reconnect immediately, instead of waiting out the browser's own CLOSING timeout. Not terminal.
+- `dispose()` — closes with code 1000 and stops reconnecting for good.
+
+The pipe is an `Emitter<WebSocketPipeEvents>` from `@greendrake/util`: `on('open')`, `on('close', (error: WebSocketClosedError) => …)`, `on('message', (raw: string) => …)`; `on` returns the unsubscribe function.
+
+### WsTransport
+
+`WsTransportOptions`: `pipe`, `codec?` (see Codec), `auth?: WsAuthStrategy`.
+
+`WsTransport<PEvents, PData>`: `PEvents` types the `{ type: 'event', event, data }` frames (`onEvent`), `PData` the bare `{ type, data }` frames (`onData`). Both default to an empty map, so a push surface has to be declared to subscribe. `PushMap` and `PushMapConstraint<P>` are the constraint types.
+
+- `send(request)` — awaits the connection, writes the frame with a generated `id`, resolves with the correlated response's `data`. Calls in flight when the socket closes reject with a `WebSocketClosedError` flagged `inFlight`.
+- `onEvent(event, handler)` / `onData(type, handler)` — return the unsubscribe function.
+- `authenticate(token)` — records the credential as this transport's identity and runs `auth.authenticate(send, token)` on the live socket; resolves once the server has accepted it, rejects on a refusal. The identity is re-applied on every reconnect, whether or not an earlier bind succeeded. Repeating it with the credential the live socket is already bound with joins that bind rather than sending a second frame.
+- `deauthenticate()` — forgets the identity and runs `auth.deauthenticate(send)`.
+- `connect()` — `pipe.ensureConnected()`.
+- `connected` — whether calls can currently succeed: an open socket whose identity bind has settled, not merely an open one.
+- `onConnectionChange(listener)` — one call per underlying transition, deliberately not deduplicated: consecutive `false` reports are consecutive failed attempts, which is how a consumer tells a blip from an outage. Returns the unsubscribe function.
+- `probe(method, deadlineMs = 5000)` — liveness check for a half-open socket (a backgrounded mobile app, an expired NAT mapping): sends `method` and, if nothing at all arrives on the socket before the deadline, drops it and reconnects at once. Resolves `true` when the socket is alive (any answer counts, a refusal included), `false` when it was dropped or was already down.
+
+`WsAuthStrategy` is `{ authenticate(send, token), deauthenticate(send) }`, with `send: WsSend = (payload: RpcRequest) => Promise<unknown>`. Which methods make up the handshake is application protocol; the transport owns only the lifecycle.
+
+## Live bindings
+
+`liveBinding(transport, options)` binds a view, a store or a cache to the pushes that say it changed, and returns the release function.
+
+```ts
+import { liveBinding } from '@greendrake/rpc'
+
+const release = liveBinding(transport, {
+    events: {
+        // Folded in locally: the push carries what changed.
+        'thing.changed': { when: data => data.id === shownId, apply: data => Object.assign(shown, data.thing) },
+        // No apply: the push is a signal, so it is answered by re-reading.
+        'thing.moderated': { when: data => data.id === shownId }
+    },
+    resync: async () => {
+        shown = await readThing(shownId)
+    }
+})
+```
+
+A list panel binds the same way, with an unfiltered handler and its own re-read:
+
+```ts
+const release = liveBinding(transport, {
+    events: { 'row.changed': {} },
+    resync: () => table.refresh()
+})
+```
+
+The contract:
+
+- **Relevance.** `when` decides whether a push concerns what the binding shows; omitted, every push does.
+- **Apply or resync.** `apply` folds the push in and nothing else happens. Without it the push runs `resync` — so `{}` means "every such push re-reads". A handler with neither `apply` nor a `resync` to fall back on throws at binding time.
+- **Reconnect.** `resync` also runs when the socket returns from a drop the binding witnessed: a connection has no memory, so what it missed is only recoverable by asking. The first connect after the binding is created is not a return from a drop. A binding without `resync` subscribes to nothing connection-related.
+- **Coalescing.** One `resync` at a time; pushes arriving during a run collapse into a single follow-up after it, however many there are — they ask the same question.
+- **No error policy.** The binding awaits `resync` only to know when the slot is free, and interprets neither outcome: `resync` owns its errors. It must also not be served by a response cache the missed pushes would have invalidated — invalidate the entries its read would hit, then read. (`@greendrake/vue-api`'s `bindLive` carries both rules for app code.)
+- **Release.** The returned function detaches every subscription and drops any pending follow-up; calling it twice is harmless.
+
+## Errors
+
+- `ApiError` — a business error from the server: `message` is the error code, `details` mirrors `error_details`.
+- `NotFoundError` — extends `OneOutcomeError`. `message` is `'Not found'`; `code` holds the server code it was made from, absent when the app raises one itself.
+- `OneOutcomeError` — base class for errors whose only sensible UX is a single acknowledgement, no retry. Pure data; presentation belongs to the UI layer.
+- `WebSocketClosedError` — extends `@greendrake/util`'s `NetworkError`. Carries `code`, `reason` and `wasClean` from the `CloseEvent`; `inFlight` (whether the failed request was already on the wire — one that never left is safe to re-issue, one in flight may have executed server-side with only its response lost); `isAbnormal` (anything but a clean 1000/1001 close); `asInFlight()`.
+
+Mapping rule, `makeError(code, details?)`, shared by both transports: the code `notfound` and any code ending in `_NOT_FOUND` become a `NotFoundError`; every other code becomes an `ApiError` carrying `details`. Transport failures — a `fetch` rejection, a socket closing under a call — are `NetworkError`s, so one `instanceof NetworkError` check classifies all of them.
+
+`codeOf(e)` returns the server code wherever the class keeps it (`ApiError.message`, `NotFoundError.code`) and the message for anything else. Key on it rather than on `message`, or every `*_NOT_FOUND` is missed.
+
+## Response cache
+
+`ResponseCache` is an in-memory TTL cache keyed by method + args. Only for stateless, platform-static reads — never per-user data that changes within a session.
+
+```ts
+import { ResponseCache } from '@greendrake/rpc'
+
+const cache = new ResponseCache({
+    ttl: 300, // seconds, for endpoints listed as `true`
+    endpoints: {
+        'taxonomy.tree': true,
+        'search.things': 60 // per-endpoint TTL in seconds
+    }
+})
+
+cache.get('taxonomy.tree', [{ taxonomy: 'category' }]) // { hit: boolean; data?: unknown }
+cache.set('taxonomy.tree', [{ taxonomy: 'category' }], tree) // no-op for an unlisted method
+cache.invalidate('search.things') // every entry for the method
+cache.invalidate('search.things', { q: 'x' }) // that args-key only
+cache.prime('taxonomy.tree', [{ taxonomy: 'category' }], pushed) // seed from a server push
+cache.clear() // everything, e.g. when the session identity changes
+```
+
+`ttlFor(method)` returns the seconds for a listed method, `false` otherwise. `CacheConfig` and `CacheLookup` are the config and `get` result types. `RpcClient` holds no cache; `@greendrake/vue-api`'s `ApiClient` composes one and derives its nonce rule from the same endpoint list.
+
+## Codec
+
+```ts
+interface Codec {
+    encode(s: string): string
+    decode(s: string): string
+}
+```
+
+Both transports run `encode` over the serialised request and `decode` over the raw response or frame text before parsing. `identityCodec`, the default, passes text through unchanged. Supply a custom codec through the `codec` option of either transport where the wire is obscured or encrypted.

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@greendrake/rpc",
+    "version": "0.1.0",
+    "description": "RPC client over JSON: typed method-map API, HTTP and reconnecting WebSocket transports, pluggable codec and headers, TTL response cache",
+    "license": "MIT",
+    "author": "Eugene Greendrake <eugene@greendrake.nz>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "rpc"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/rpc#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "dependencies": {
+        "@greendrake/util": "0.1.0"
+    },
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "typescript": "6.0.3"
+    }
+}

package/src/ResponseCache.ts

@@ -0,0 +1,96 @@
+export interface CacheConfig {
+    // Default TTL in seconds for endpoints enabled with `true`.
+    ttl: number
+    // Cached endpoints: `true` = default TTL, number = per-endpoint TTL seconds.
+    endpoints: Record<string, true | number>
+}
+
+interface CacheEntry {
+    data: unknown
+    expires: number
+}
+
+export interface CacheLookup {
+    hit: boolean
+    data?: unknown
+}
+
+// In-memory TTL response cache keyed by scope + method + args. Only for
+// stateless, platform-static reads — never per-user data that mutates
+// in-session.
+export class ResponseCache {
+    readonly #config: CacheConfig
+    readonly #scope?: () => string | undefined
+    readonly #entries = new Map<string, CacheEntry>()
+
+    // `scope` names the request property that is not an argument yet decides
+    // what comes back — the caller's UI language, which every server-resolved
+    // label in a response is written in. Answers from different scopes are
+    // different answers and are kept apart, so switching back to a language
+    // already read costs no round trip.
+    constructor(config: CacheConfig, scope?: () => string | undefined) {
+        this.#config = config
+        this.#scope = scope
+    }
+
+    // Seconds for a cached endpoint, false for an uncached one.
+    ttlFor(method: string): number | false {
+        const val = this.#config.endpoints[method]
+        if (val === undefined) return false
+        return val === true ? this.#config.ttl : val
+    }
+
+    #key(method: string, args: unknown[]): string {
+        return JSON.stringify([this.#scope?.() ?? null, method, ...args])
+    }
+
+    get(method: string, args: unknown[]): CacheLookup {
+        const entry = this.#entries.get(this.#key(method, args))
+        if (entry && Date.now() < entry.expires) {
+            return { hit: true, data: entry.data }
+        }
+        return { hit: false }
+    }
+
+    // Store a response for a cached endpoint; no-op for uncached methods so
+    // callers can set unconditionally after a read.
+    set(method: string, args: unknown[], data: unknown): void {
+        const ttl = this.ttlFor(method)
+        if (ttl === false) return
+        this.#entries.set(this.#key(method, args), { data, expires: Date.now() + ttl * 1000 })
+    }
+
+    // Drop cached responses for an endpoint. Called after a mutation so the
+    // next read reflects the change rather than a snapshot still inside its
+    // TTL. With args, only the entry for that exact args-key is dropped;
+    // without args, every entry for the method is dropped (a whole query
+    // family). Either way in every scope: what a mutation changed is the data,
+    // not the language it would be read back in.
+    invalidate(method: string, ...args: unknown[]): void {
+        const wanted = args.length ? JSON.stringify(args) : null
+        for (const key of this.#entries.keys()) {
+            const parts = JSON.parse(key) as unknown[]
+            if (parts[1] !== method) {
+                continue
+            }
+            if (wanted === null || JSON.stringify(parts.slice(2)) === wanted) {
+                this.#entries.delete(key)
+            }
+        }
+    }
+
+    // Drop everything. For the change that invalidates the whole cache at once
+    // rather than one endpoint's worth: the session identity, which every
+    // audience-dependent read here was answered under.
+    clear(): void {
+        this.#entries.clear()
+    }
+
+    // Seed the cache with a known-fresh response — a server push already
+    // carrying the full DTO a read would return — so the next read serves it
+    // without a round-trip. `args` must match the read's args so the same key
+    // is hit.
+    prime(method: string, args: unknown[], data: unknown): void {
+        this.set(method, args, data)
+    }
+}

package/src/RpcClient.ts

@@ -0,0 +1,33 @@
+import type { MethodMap, MethodMapConstraint, Transport } from './types'
+import { packRequest } from './protocol'
+
+// Typed facade over a transport: methods come from the app's declared
+// MethodMap, so arguments and results are fully inferred — no bracket-notation
+// proxies, no casts at call sites.
+//    const client = new RpcClient<Methods>(transport)
+//    const user = await client.call('user.get', id)
+export class RpcClient<M extends MethodMapConstraint<M> = MethodMap> {
+    readonly transport: Transport
+    // Supplies the caller's UI language tag per request. Evaluated per call,
+    // like HttpTransport's headers provider, so a locale switch takes effect on
+    // the next call rather than at construction.
+    readonly #locale?: () => string | undefined
+
+    constructor(transport: Transport, locale?: () => string | undefined) {
+        this.transport = transport
+        this.#locale = locale
+    }
+
+    // The one way to invoke a method; every request carries a nonce for
+    // server-side dedup. Omitting the nonce is only worth doing where a
+    // response cache needs byte-identical requests to key on, and this client
+    // holds no cache — @greendrake/vue-api's ApiClient owns that rule, derived
+    // from the single list of cacheable methods it is configured with.
+    call<K extends keyof M & string>(method: K, ...args: Parameters<M[K]>): Promise<Awaited<ReturnType<M[K]>>> {
+        return this.#invoke(true, method, args)
+    }
+
+    async #invoke<K extends keyof M & string>(nonce: boolean, method: K, args: unknown[]): Promise<Awaited<ReturnType<M[K]>>> {
+        return (await this.transport.send(packRequest(method, args, nonce, this.#locale?.()))) as Awaited<ReturnType<M[K]>>
+    }
+}

package/src/WebSocketPipe.ts

@@ -0,0 +1,191 @@
+import { Emitter } from '@greendrake/util'
+import { WebSocketClosedError } from './errors'
+
+export interface WebSocketPipeOptions {
+    url: string
+    // Connection-level credential appended to the URL as a query parameter and
+    // resolved by the server at the handshake (before the first frame). Because
+    // the token rides the URL, reconnects re-authenticate automatically. For
+    // in-band per-session auth use WsTransport's auth strategy instead.
+    queryAuth?: {
+        param: string
+        token: string
+    }
+    // Delay before reconnect attempt N (0-based, reset on successful open).
+    reconnectDelayMs?: (attempt: number) => number
+}
+
+export interface WebSocketPipeEvents {
+    open: []
+    close: [error: WebSocketClosedError]
+    message: [raw: string]
+    [key: string]: unknown[]
+}
+
+const DEFAULT_RECONNECT_DELAY_MS = 3000
+
+// Reconnecting WebSocket carrier. Owns only the connection lifecycle and raw
+// string frames — request framing, codecs and push-envelope parsing live in
+// WsTransport, above the wire.
+export class WebSocketPipe extends Emitter<WebSocketPipeEvents> {
+    readonly #url: string
+    readonly #delayMs: (attempt: number) => number
+    #ws?: WebSocket
+    #promise?: Promise<void>
+    // A reconnect waiting out its delay: the timer to cancel, and the resolver
+    // that advances the armed promise into the attempt. Set only while
+    // waiting — cleared the moment the attempt starts — so its presence is
+    // exactly the condition reconnectNow() acts on.
+    #scheduledReconnect?: { timer: ReturnType<typeof setTimeout>; start: () => void }
+    #attempt = 0
+    #disposed = false
+
+    constructor(options: WebSocketPipeOptions) {
+        super()
+        const { url, queryAuth } = options
+        this.#url = queryAuth ? `${url}${url.includes('?') ? '&' : '?'}${queryAuth.param}=${encodeURIComponent(queryAuth.token)}` : url
+        this.#delayMs = options.reconnectDelayMs ?? (() => DEFAULT_RECONNECT_DELAY_MS)
+    }
+
+    // `#promise` always tracks the current-or-next connection attempt: armed
+    // when an attempt starts, re-armed on close (pending through the reconnect
+    // delay). Awaiters of a failed attempt get its rejection (err hard), while
+    // callers arriving after the failure await the upcoming attempt instead of
+    // a stale settled promise.
+    #arm(promise: Promise<void>): Promise<void> {
+        this.#promise = promise
+        // Background attempts (auto-reconnects) can reject with no awaiter;
+        // mark the rejection handled so it doesn't surface as
+        // unhandledrejection noise. ensureConnected() callers still receive it.
+        promise.catch(() => {})
+        return promise
+    }
+
+    #connect(): Promise<void> {
+        const ws = new WebSocket(this.#url)
+        this.#ws = ws
+        ws.addEventListener('message', event => {
+            // A dropped socket may still deliver: it is disowned, not silenced.
+            if (this.#ws === ws && typeof event.data === 'string') {
+                this.emit('message', event.data)
+            }
+        })
+        return this.#arm(
+            new Promise<void>((resolve, reject) => {
+                let opened = false
+                ws.addEventListener('open', () => {
+                    opened = true
+                    this.#attempt = 0
+                    this.emit('open')
+                    resolve()
+                })
+                // The 'close' event (always emitted, and the only one carrying
+                // a code/reason — 'error' carries neither) drives three things:
+                // notify listeners so in-flight calls fail instead of hanging;
+                // reject the connect attempt if it never opened; and arm the
+                // reconnect.
+                ws.addEventListener('close', event => {
+                    // drop() disowns the socket before abandoning it, and this
+                    // fires later on the zombie: everything below already ran.
+                    if (this.#ws !== ws) {
+                        return
+                    }
+                    const closed = new WebSocketClosedError(event)
+                    this.#reportClosed(closed, opened ? undefined : reject)
+                })
+            })
+        )
+    }
+
+    // What a close means, wherever it comes from: the socket is let go, its
+    // in-flight calls fail instead of hanging, a never-opened attempt rejects,
+    // and the next attempt is armed behind its delay. Called by the socket's
+    // own close event, and by drop() for a socket whose peer will never send
+    // one. Letting go here — rather than in each caller — is what makes "no
+    // socket" mean the same thing everywhere: a closed socket left in #ws would
+    // let a later drop() run this a second time, arming a second reconnect over
+    // the first and orphaning whichever attempt loses.
+    #reportClosed(closed: WebSocketClosedError, rejectAttempt?: (e: unknown) => void): void {
+        this.#ws = undefined
+        this.emit('close', closed)
+        rejectAttempt?.(closed)
+        if (this.#disposed) {
+            return
+        }
+        const delay = this.#delayMs(this.#attempt++)
+        this.#arm(
+            new Promise<void>(res => {
+                const start = (): void => {
+                    this.#scheduledReconnect = undefined
+                    res()
+                }
+                this.#scheduledReconnect = { timer: setTimeout(start, delay), start }
+            }).then(() => this.#connect())
+        )
+    }
+
+    // Abandon a socket that cannot be trusted to close itself — one whose peer
+    // is gone without a FIN, so nothing has failed and nothing will. Closing it
+    // and waiting is not enough: the closing handshake has no one to answer it,
+    // so the browser holds the socket in CLOSING until its own timeout, and the
+    // close path — which is what fails in-flight calls and arms the reconnect —
+    // would not run until then. So the close path runs here and now — disowning
+    // the socket, which makes its later events no-ops (the handlers registered
+    // in #connect check that #ws is still theirs) — and the zombie is closed
+    // without being waited for. Unlike dispose() this is not terminal:
+    // reconnection continues. A no-op when there is no socket to abandon.
+    drop(): void {
+        const ws = this.#ws
+        if (!ws) {
+            return
+        }
+        this.#reportClosed(new WebSocketClosedError(new CloseEvent('close', { code: 1006, reason: 'dropped' })))
+        ws.close()
+    }
+
+    get connected(): boolean {
+        return this.#ws?.readyState === WebSocket.OPEN
+    }
+
+    // Collapse a reconnect's remaining delay and attempt it now — for a signal
+    // that connectivity is likely back (the device's online event, a native
+    // app resuming from background) which would otherwise be waited out. A
+    // no-op unless a reconnect is actually waiting: an attempt already in
+    // flight, an open socket, and a disposed pipe all have nothing to bring
+    // forward. The armed promise is resolved through its own path, just
+    // earlier, so awaiters are unaffected.
+    reconnectNow(): void {
+        const scheduled = this.#scheduledReconnect
+        if (!scheduled) {
+            return
+        }
+        clearTimeout(scheduled.timer)
+        scheduled.start()
+    }
+
+    // Resolves when the current-or-next connection attempt opens. Starts the
+    // first attempt if none has been made — also the eager-connect entry point.
+    ensureConnected(): Promise<void> {
+        if (this.#disposed) {
+            throw new Error('WebSocketPipe disposed')
+        }
+        return this.#promise ?? this.#connect()
+    }
+
+    send(raw: string): void {
+        if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) {
+            throw new Error('WebSocket not open — await ensureConnected() first')
+        }
+        this.#ws.send(raw)
+    }
+
+    // Deliberate teardown: closes cleanly and stops reconnecting for good.
+    dispose(): void {
+        this.#disposed = true
+        if (this.#scheduledReconnect) {
+            clearTimeout(this.#scheduledReconnect.timer)
+            this.#scheduledReconnect = undefined
+        }
+        this.#ws?.close(1000)
+    }
+}

package/src/WsTransport.ts

@@ -0,0 +1,305 @@
+import { randomString } from '@greendrake/util'
+import { identityCodec } from './types'
+import type { Codec, RpcRequest, RpcResponse, Transport } from './types'
+import { settleResponse } from './protocol'
+import type { WebSocketPipe } from './WebSocketPipe'
+
+export type WsSend = (payload: RpcRequest) => Promise<unknown>
+
+// The over-the-wire authentication handshake (which methods to call, the
+// argument shape) is application protocol, not transport, so it is injected
+// rather than hardcoded here. The transport owns only the generic lifecycle:
+// caching the credential and re-applying it whenever the socket (re)connects.
+// Apps with no per-session auth simply omit the strategy (or use the pipe's
+// queryAuth for connection-level credentials).
+export interface WsAuthStrategy {
+    authenticate(send: WsSend, token: string): Promise<unknown>
+    deauthenticate(send: WsSend): Promise<unknown>
+}
+
+// App-declared server-push surface: name → payload type.
+//    interface Pushes { 'threads.updated': ThreadsPatch }
+export type PushMap = Record<string, unknown>
+
+export type PushMapConstraint<P> = Record<keyof P, unknown>
+
+interface WsResponseFrame extends RpcResponse {
+    id: string
+}
+
+interface PushFrame {
+    type: string
+    event?: string
+    data?: unknown
+}
+
+export interface WsTransportOptions {
+    pipe: WebSocketPipe
+    codec?: Codec
+    auth?: WsAuthStrategy
+}
+
+// How long a liveness probe waits for an answer before calling the socket dead.
+// A deadline on a network response, not a wait for something to happen: the
+// probe exists precisely because a half-open socket produces no event to wait
+// for.
+const DEFAULT_PROBE_DEADLINE_MS = 5000
+
+interface PendingCall {
+    settle(frame: WsResponseFrame): void
+    fail(error: Error): void
+}
+
+// The wire format over a WebSocketPipe: id-correlated request/response, typed
+// server-push subscription, injected auth re-applied on every (re)connect.
+// PEvents types `{type:'event', event, data}` frames; PData types the bare
+// `{type, data}` frames some backends push. Both default to uncallable-empty —
+// an app must declare its push surface to subscribe.
+export class WsTransport<PEvents extends PushMapConstraint<PEvents> = Record<never, never>, PData extends PushMapConstraint<PData> = Record<never, never>> implements Transport {
+    readonly pipe: WebSocketPipe
+    readonly #codec: Codec
+    readonly #auth?: WsAuthStrategy
+    // Who this transport is to be bound as — cached the moment the credential
+    // is handed over, not once a bind succeeds. It states what every
+    // connection of this transport should authenticate as, independently of
+    // whether any single attempt got through, so a refused or interrupted bind
+    // still re-applies on the next reconnect.
+    #token: string | null = null
+    // The bind issued for the live socket: the credential it carries and its
+    // outcome. Dropped when that socket goes (or the identity is released), so
+    // each connection binds exactly once — authenticate() and the reconnect
+    // handler converge on this record rather than both putting an auth frame
+    // on the same socket.
+    #binding?: { token: string; done: Promise<unknown> }
+    // In-flight calls keyed by request id. A dropped socket never delivers
+    // their responses, so they are failed explicitly on close.
+    readonly #pending = new Map<string, PendingCall>()
+    readonly #eventHandlers = new Map<string, Set<(data: never) => void>>()
+    readonly #dataHandlers = new Map<string, Set<(data: never) => void>>()
+    // Whether calls can currently succeed — an open socket that has finished
+    // binding its identity, not merely an open one. See the 'open' handler.
+    #ready = false
+    // Bumped on every open and every close, so work deferred across one of
+    // those events can tell whether the connection it belongs to is still the
+    // live one.
+    #connectionEpoch = 0
+    // Bumped on every frame the socket delivers, whatever it carries: the one
+    // piece of evidence that distinguishes a live connection from a half-open
+    // one. Read by probe() across its deadline.
+    #framesReceived = 0
+    readonly #connectionListeners = new Set<(connected: boolean) => void>()
+
+    constructor(options: WsTransportOptions) {
+        this.pipe = options.pipe
+        this.#codec = options.codec ?? identityCodec
+        this.#auth = options.auth
+        this.pipe.on('message', raw => this.#onRaw(raw))
+        // Bind the identity on every (re)connect so a dropped socket comes
+        // back as the same user, and withhold the readiness report until that
+        // bind settles. A consumer resuming calls on a bare 'open' would race
+        // the bind frame — the loser comes back UNAUTHENTICATED, which an app
+        // reasonably reads as a lost session, so a blip could log the user
+        // out. Settled either way is enough: a *refused* bind means the
+        // session is genuinely gone, and a resumed call surfacing that is the
+        // correct outcome. Fire-and-forget otherwise: no caller awaits a
+        // reconnect's bind, and an authenticate() joined to this same record
+        // still receives it.
+        this.pipe.on('open', () => {
+            const epoch = ++this.#connectionEpoch
+            if (!this.#token) {
+                this.#reportConnection(true)
+                return
+            }
+            void this.#bind(this.#token)
+                .catch(() => {})
+                .then(() => {
+                    // A bind settling after its socket has gone must not
+                    // report a connection that no longer exists; whatever
+                    // replaced it reports for itself.
+                    if (this.#connectionEpoch === epoch) {
+                        this.#reportConnection(true)
+                    }
+                })
+        })
+        // Fail anything in flight when the socket closes: its response can
+        // never arrive, so the call would otherwise hang forever (and the UI
+        // awaiting it with it). The close error carries the code/reason; the
+        // swept calls get the in-flight attribution, while the error as
+        // emitted (and as ensureConnected rejects with) stays unflagged —
+        // those requests never reached the wire.
+        this.pipe.on('close', error => {
+            this.#connectionEpoch++
+            // The bind belonged to the socket that just went; the next open
+            // issues a fresh one.
+            this.#binding = undefined
+            const pending = [...this.#pending.values()]
+            this.#pending.clear()
+            this.#reportConnection(false)
+            pending.forEach(call => call.fail(error.asInFlight()))
+        })
+    }
+
+    // Ask the server whether this socket is still a socket. A connection torn
+    // down without a FIN — a backgrounded mobile app, an idle NAT mapping
+    // expiring — stays OPEN to the browser: no close event, so nothing fails,
+    // nothing reconnects, and calls made on it hang. `method` is the app's
+    // cheapest round trip; an answer means live, silence past the deadline
+    // means the socket is abandoned and reconnected, which puts the normal
+    // close/reconnect path (and whatever the app hangs off it) back in charge.
+    //
+    // Resolves true when the socket is alive. Nothing to probe when the
+    // transport is already down: a reconnect is in flight and will report for
+    // itself.
+    async probe(method: string, deadlineMs = DEFAULT_PROBE_DEADLINE_MS): Promise<boolean> {
+        if (!this.connected) {
+            return false
+        }
+        const mark = this.#framesReceived
+        let timer: ReturnType<typeof setTimeout> | undefined
+        const expiry = new Promise<false>(resolve => {
+            timer = setTimeout(() => resolve(false), deadlineMs)
+        })
+        try {
+            const answered = await Promise.race([this.send({ method }).then(() => true), expiry])
+            if (answered) {
+                return true
+            }
+        } catch {
+            // A refusal is an answer: the socket carried it.
+            return true
+        } finally {
+            clearTimeout(timer)
+        }
+        // What the deadline is really on is silence, not this one answer: the
+        // frames share an ordered connection, so a slow link transferring a
+        // large page ahead of the probe can outlast the deadline on a socket
+        // that is demonstrably delivering. Anything received since the probe
+        // went out settles the question the probe was asking, and killing a
+        // working socket is not a free retry — it fails every call in flight,
+        // each of which then surfaces as a failure the user did not cause.
+        if (this.#framesReceived !== mark) {
+            return true
+        }
+        this.pipe.drop()
+        this.pipe.reconnectNow()
+        return false
+    }
+
+    // Whether calls can currently succeed. Together with onConnectionChange,
+    // this is the connectivity oracle an app hands to its UX layer.
+    get connected(): boolean {
+        return this.#ready
+    }
+
+    // Connection transitions, one call per underlying event and deliberately
+    // NOT deduplicated: consecutive `false` reports are consecutive failed
+    // attempts, which is how a consumer tells a blip from a real outage.
+    onConnectionChange(listener: (connected: boolean) => void): () => void {
+        this.#connectionListeners.add(listener)
+        return () => {
+            this.#connectionListeners.delete(listener)
+        }
+    }
+
+    #reportConnection(connected: boolean): void {
+        this.#ready = connected
+        this.#connectionListeners.forEach(listener => listener(connected))
+    }
+
+    connect(): Promise<void> {
+        return this.pipe.ensureConnected()
+    }
+
+    #onRaw(raw: string): void {
+        this.#framesReceived++
+        const frame = JSON.parse(this.#codec.decode(raw)) as WsResponseFrame | PushFrame
+        if ('id' in frame && typeof frame.id === 'string') {
+            const pending = this.#pending.get(frame.id)
+            if (pending) {
+                this.#pending.delete(frame.id)
+                pending.settle(frame as WsResponseFrame)
+            }
+            return
+        }
+        const push = frame as PushFrame
+        if (push.type === 'event' && typeof push.event === 'string') {
+            this.#dispatch(this.#eventHandlers, push.event, push.data)
+        } else if (push.type && push.type !== 'response') {
+            this.#dispatch(this.#dataHandlers, push.type, push.data)
+        }
+    }
+
+    #dispatch(handlers: Map<string, Set<(data: never) => void>>, key: string, data: unknown): void {
+        handlers.get(key)?.forEach(handler => (handler as (d: unknown) => void)(data))
+    }
+
+    #subscribe(handlers: Map<string, Set<(data: never) => void>>, key: string, handler: (data: never) => void): () => void {
+        let set = handlers.get(key)
+        if (!set) {
+            set = new Set()
+            handlers.set(key, set)
+        }
+        set.add(handler)
+        return () => {
+            set.delete(handler)
+        }
+    }
+
+    // Subscribe to `{type:'event', event: name}` server pushes.
+    onEvent<K extends keyof PEvents & string>(event: K, handler: (data: PEvents[K]) => void): () => void {
+        return this.#subscribe(this.#eventHandlers, event, handler)
+    }
+
+    // Subscribe to bare `{type: name}` server pushes.
+    onData<K extends keyof PData & string>(type: K, handler: (data: PData[K]) => void): () => void {
+        return this.#subscribe(this.#dataHandlers, type, handler)
+    }
+
+    async send(request: RpcRequest): Promise<unknown> {
+        await this.pipe.ensureConnected()
+        return new Promise((resolve, reject) => {
+            const id = randomString('rpc-')
+            this.#pending.set(id, {
+                settle: frame => {
+                    try {
+                        resolve(settleResponse(frame, request.method))
+                    } catch (e) {
+                        reject(e)
+                    }
+                },
+                fail: reject
+            })
+            this.pipe.send(this.#codec.encode(JSON.stringify({ id, ...request })))
+        })
+    }
+
+    // Binds the connection to `token`, resolving once the server has accepted
+    // it. Cheap to repeat: naming the credential the live socket is already
+    // bound with joins that bind instead of issuing a second one — which is
+    // what a boot does, the session store binding on token receipt and the
+    // bootstrap then awaiting the same identity.
+    async authenticate(token: string): Promise<void> {
+        this.#token = token
+        await this.#bind(token)
+    }
+
+    async deauthenticate(): Promise<void> {
+        this.#token = null
+        // The socket is no longer bound to anyone, so a later authenticate()
+        // with that same credential must issue a real bind, not join the one
+        // this call is undoing.
+        this.#binding = undefined
+        await this.#auth?.deauthenticate(payload => this.send(payload))
+    }
+
+    #bind(token: string): Promise<unknown> {
+        if (this.#binding?.token !== token) {
+            // send() waits for the socket itself, so this is safe to issue
+            // while the handshake is still in flight: the frame goes out when
+            // it opens, by which point the 'open' handler finds this record
+            // already standing and adds nothing.
+            this.#binding = { token, done: this.#auth?.authenticate(payload => this.send(payload), token) ?? Promise.resolve() }
+        }
+        return this.#binding.done
+    }
+}

package/src/errors.ts

@@ -0,0 +1,84 @@
+import { NetworkError } from '@greendrake/util'
+
+// An error whose only sensible UX is a single acknowledgement (no retry).
+// Pure data — presentation (toasts, dismiss handlers) belongs to the UI layer.
+export class OneOutcomeError extends Error {}
+
+export class NotFoundError extends OneOutcomeError {
+    // The backend code this was made from, when there was one. makeError folds
+    // every `*_NOT_FOUND` code into this class, and the message is display
+    // text rather than the code, so without carrying it here the code would be
+    // gone — leaving anything that matches on codes (session teardown, the
+    // bubbled-error list) unable to see a `*_NOT_FOUND` at all. Absent when the
+    // app raises a not-found of its own, from a route that resolved to nothing.
+    readonly code?: string
+
+    constructor(code?: string) {
+        super('Not found')
+        this.name = 'NotFoundError'
+        this.code = code
+    }
+}
+
+// The backend error code behind an error, wherever its class keeps it: an
+// ApiError's message IS its code, a NotFoundError holds it apart because its
+// message is display text. Anything else answers with its message, which simply
+// matches no code. The one way to key on a code — matching `message` directly
+// silently misses every `*_NOT_FOUND`.
+export const codeOf = (e: Error): string => (e instanceof NotFoundError ? (e.code ?? '') : e.message)
+
+// A backend business error: `message` is the error code, `details` mirrors the
+// response's `error_details` payload (the structured data a handler attaches
+// alongside a code, e.g. the conflicting user's id on OAUTH_ALREADY_LINKED).
+export class ApiError extends Error {
+    readonly details?: unknown
+
+    constructor(code: string, details?: unknown) {
+        super(code)
+        this.name = 'ApiError'
+        this.details = details
+    }
+}
+
+// Rejection value for a WebSocket that closes before it opens, or that closes
+// while calls are in flight. Carries the CloseEvent fields so a drop is
+// diagnosable (which close code, was it clean) instead of surfacing as a bare,
+// contentless DOM Event. Extends NetworkError: a transport condition,
+// classified alongside HTTP fetch failures by one instanceof check.
+export class WebSocketClosedError extends NetworkError {
+    readonly code: number
+    readonly reason: string
+    readonly wasClean: boolean
+    // Whether the request this error failed was already on the wire when the
+    // socket went. A request that never left cannot have had an effect and is
+    // always safe to re-issue; one that was in flight may have executed
+    // server-side with only its response lost, so re-issuing it is a decision
+    // for the caller (see ApiClient's offline park).
+    readonly inFlight: boolean
+    readonly #event: CloseEvent
+
+    constructor(event: CloseEvent, inFlight = false) {
+        super(`WebSocket closed (code ${event.code}${event.reason ? `, ${event.reason}` : ''}, clean=${event.wasClean})`)
+        this.name = 'WebSocketClosedError'
+        this.code = event.code
+        this.reason = event.reason
+        this.wasClean = event.wasClean
+        this.inFlight = inFlight
+        this.#event = event
+    }
+
+    // The same close, attributed to a request that was already on the wire.
+    // A separate instance rather than a mutation: the emitted error is shared
+    // by every close listener, and only the swept calls carry the flag.
+    asInFlight(): WebSocketClosedError {
+        return new WebSocketClosedError(this.#event, true)
+    }
+
+    // An unexpected drop worth reporting, vs the clean close a normal
+    // navigation or logout produces (mere operational noise). 1000 = normal,
+    // 1001 = going away; anything else — 1006 (abnormal, no close frame),
+    // 1011/1012/1013 (server error / restart / overload) — is unexpected.
+    get isAbnormal(): boolean {
+        return !this.wasClean || ![1000, 1001].includes(this.code)
+    }
+}

package/src/http.ts

@@ -0,0 +1,34 @@
+import { safeFetch } from '@greendrake/util'
+import { identityCodec } from './types'
+import type { Codec, HeadersProvider, RpcRequest, RpcResponse, Transport } from './types'
+import { settleResponse } from './protocol'
+
+export interface HttpTransportOptions {
+    url: string
+    codec?: Codec
+    headers?: HeadersProvider
+    // Merged into every request — e.g. { keepalive: true } for fire-and-forget
+    // calls that must survive page unload.
+    requestInit?: Partial<RequestInit>
+}
+
+export class HttpTransport implements Transport {
+    readonly #options: HttpTransportOptions
+    readonly #codec: Codec
+
+    constructor(options: HttpTransportOptions) {
+        this.#options = options
+        this.#codec = options.codec ?? identityCodec
+    }
+
+    async send(request: RpcRequest): Promise<unknown> {
+        const response = await safeFetch(this.#options.url, {
+            ...this.#options.requestInit,
+            method: 'POST',
+            headers: this.#options.headers?.(),
+            body: this.#codec.encode(JSON.stringify(request))
+        })
+        const text = this.#codec.decode(await response.text())
+        return settleResponse(JSON.parse(text) as RpcResponse, request.method)
+    }
+}

package/src/liveBinding.ts

@@ -0,0 +1,117 @@
+import type { PushMapConstraint, WsTransport } from './WsTransport'
+
+// What one push means to the thing the binding keeps current.
+export interface LiveHandler<D> {
+    // Whether this push concerns what the binding shows. Omitted: every push does.
+    when?: (data: D) => boolean
+    // Folds the push in locally. Omitted: the push triggers `resync`.
+    apply?: (data: D) => void
+}
+
+export interface LiveOptions<PEvents, PData> {
+    // `{type:'event', event}` frames, subscribed via onEvent.
+    events?: { [K in keyof PEvents]?: LiveHandler<PEvents[K]> }
+    // Bare `{type, data}` frames, subscribed via onData.
+    data?: { [K in keyof PData]?: LiveHandler<PData[K]> }
+    // The full re-read of what the binding shows. Runs for a relevant push
+    // with no `apply`, and when the socket comes back from a drop — the two
+    // are the same event as far as the data is concerned, since a drop is
+    // exactly where a push goes missing.
+    //
+    // It owns its own errors: the binding awaits it only to know when the slot
+    // is free, and interprets neither outcome. It must also not be served by a
+    // response cache the missed pushes would have invalidated — invalidate,
+    // then read (see @greendrake/vue-api's bindLive, which carries that policy
+    // for app code).
+    resync?: () => Promise<unknown> | void
+}
+
+// Binds a view, store or cache to the server pushes that say it changed: each
+// push is filtered for relevance and then either folded in locally (`apply`)
+// or answered by re-reading (`resync`), and a socket that drops and returns
+// re-reads too — a connection has no memory, so whatever it missed is only
+// recoverable by asking again.
+//
+// Returns the release function; call it when what the binding keeps current
+// goes away.
+export const liveBinding = <PEvents extends PushMapConstraint<PEvents>, PData extends PushMapConstraint<PData>>(transport: WsTransport<PEvents, PData>, options: LiveOptions<PEvents, PData>): (() => void) => {
+    const { resync } = options
+    const releases: (() => void)[] = []
+    let running = false
+    let queued = false
+    let released = false
+
+    const runResync = (): void => {
+        if (!resync || released) return
+        // One re-read at a time, and at most one more behind it however many
+        // pushes land while it runs: they all ask the same question, and the
+        // answer to the last one is the answer to all of them.
+        if (running) {
+            queued = true
+            return
+        }
+        running = true
+        // `new Promise(resolve => resolve(…))` rather than Promise.resolve(…):
+        // it puts the call inside the promise, so a resync that throws
+        // synchronously becomes a rejection like any other failure instead of
+        // escaping with the slot still held — which would wedge this binding for
+        // good, and abort the transport's dispatch to every other subscriber of
+        // the same frame.
+        void new Promise(resolve => resolve(resync()))
+            // Whatever the outcome, the slot is free and a push that arrived
+            // during the run gets its re-read. The outcome itself belongs to
+            // resync — swallowed here rather than left unhandled because this
+            // runs from a subscription callback nobody awaits.
+            .catch(() => {})
+            .then(() => {
+                running = false
+                if (!queued) return
+                queued = false
+                runResync()
+            })
+    }
+
+    const attach = <P>(handlers: { [K in keyof P]?: LiveHandler<P[K]> } | undefined, subscribe: <K extends keyof P & string>(key: K, handler: (data: P[K]) => void) => () => void): (() => () => void)[] =>
+        (Object.keys(handlers ?? {}) as (keyof P & string)[]).map(key => {
+            const handler = handlers![key]!
+            if (!handler.apply && !resync) {
+                throw new Error(`liveBinding: the handler for '${key}' neither applies the push nor has a resync to answer it with`)
+            }
+            return () =>
+                subscribe(key, data => {
+                    if (handler.when && !handler.when(data)) return
+                    if (handler.apply) handler.apply(data)
+                    else runResync()
+                })
+        })
+
+    // Every handler is checked before the first subscription goes on, so a
+    // misconfigured one throws with nothing left attached behind it.
+    const subscriptions = [...attach<PEvents>(options.events, (event, handler) => transport.onEvent(event, handler)), ...attach<PData>(options.data, (type, handler) => transport.onData(type, handler))]
+    subscriptions.forEach(subscribe => releases.push(subscribe()))
+
+    if (resync) {
+        // A return from a drop this binding witnessed, not any connect: the
+        // first `true` after a boot reports the connection the binding was
+        // created for, and there is nothing yet to have missed.
+        let dropped = false
+        releases.push(
+            transport.onConnectionChange(connected => {
+                if (!connected) {
+                    dropped = true
+                    return
+                }
+                if (!dropped) return
+                dropped = false
+                runResync()
+            })
+        )
+    }
+
+    return () => {
+        released = true
+        queued = false
+        releases.forEach(release => release())
+        releases.length = 0
+    }
+}

package/src/main.ts

@@ -0,0 +1,9 @@
+export { identityCodec, type Codec, type HeadersProvider, type RpcRequest, type RpcResponse, type MethodMap, type MethodMapConstraint, type Transport } from './types'
+export { ApiError, NotFoundError, OneOutcomeError, WebSocketClosedError, codeOf } from './errors'
+export { makeError, packRequest, settleResponse } from './protocol'
+export { HttpTransport, type HttpTransportOptions } from './http'
+export { WebSocketPipe, type WebSocketPipeEvents, type WebSocketPipeOptions } from './WebSocketPipe'
+export { WsTransport, type PushMap, type PushMapConstraint, type WsAuthStrategy, type WsSend, type WsTransportOptions } from './WsTransport'
+export { liveBinding, type LiveHandler, type LiveOptions } from './liveBinding'
+export { RpcClient } from './RpcClient'
+export { ResponseCache, type CacheConfig, type CacheLookup } from './ResponseCache'

package/src/protocol.ts

@@ -0,0 +1,51 @@
+import { randomString } from '@greendrake/util'
+import { ApiError, NotFoundError } from './errors'
+import type { RpcRequest, RpcResponse } from './types'
+
+export const packRequest = (method: string, args: unknown[], nonce: boolean, locale?: string): RpcRequest => {
+    const request: RpcRequest = { method }
+    if (nonce) {
+        request.nonce = randomString()
+    }
+    if (args.length) {
+        request.arguments = args
+    }
+    if (locale) {
+        request.locale = locale
+    }
+    return request
+}
+
+// Single owner of the error-code → Error mapping shared by both transports:
+// 'notfound' / '*_NOT_FOUND' get a NotFoundError (its own toast type),
+// everything else an ApiError carrying the optional error_details payload.
+export const makeError = (code: string, details?: unknown): Error => {
+    if (code === 'notfound' || code.endsWith('_NOT_FOUND')) {
+        // The code rides along: this class is chosen for its toast, not to
+        // replace what the backend said, and a caller keying on the code
+        // (codeOf) must still find it.
+        return new NotFoundError(code)
+    }
+    return new ApiError(code, details)
+}
+
+// Dev-only diagnostic for non-success responses. These are server-returned
+// business outcomes (NOT_FOUND, INVALID_CREDENTIALS, …) the caller goes on to
+// handle — not program faults — so they log at `warn`, never `error`: a
+// handled outcome must not trip a test's console-error guard or read as a
+// malfunction in the devtools console. Guarded optional access keeps this
+// Node-safe (no import.meta.env outside Vite).
+const logIfDev = (method: string, response: RpcResponse): void => {
+    if ((import.meta as ImportMeta & { env?: { DEV?: boolean } }).env?.DEV) {
+        console.warn('[rpc]', method, response)
+    }
+}
+
+// Resolve a parsed response to its data, or throw the mapped error.
+export const settleResponse = (response: RpcResponse, method: string): unknown => {
+    if (response.success) {
+        return response.data
+    }
+    logIfDev(method, response)
+    throw makeError(response.error!, response.error_details)
+}

package/src/types.ts

@@ -0,0 +1,56 @@
+// Single source of truth for the wire shapes. The protocol:
+// request  {method, nonce?, arguments?}  (nonce = server-side dedup key for
+//          non-idempotent calls; arguments omitted when empty)
+// response {success, data?, error?, error_details?}
+// WS adds an `id` to both directions for request/response correlation, and
+// server-push frames {type: 'event', event, data} / {type, data}.
+
+export interface RpcRequest {
+    method: string
+    nonce?: string
+    // The caller's UI language tag, when the app supplies a provider. In the
+    // envelope rather than a header: the WebSocket transport has none, and the
+    // browser cannot set any on the handshake, while every call rides that
+    // socket.
+    locale?: string
+    arguments?: unknown[]
+    [key: string]: unknown
+}
+
+export interface RpcResponse {
+    success: boolean
+    data?: unknown
+    error?: string
+    error_details?: unknown
+}
+
+// Payload codec applied to outbound request bodies and inbound response text.
+// Identity by default; an app supplies its own for an obscured or encrypted wire.
+export interface Codec {
+    encode(s: string): string
+    decode(s: string): string
+}
+
+export const identityCodec: Codec = {
+    encode: s => s,
+    decode: s => s
+}
+
+// Extra request headers, evaluated per request so time-variant values (auth
+// tokens, identity blobs) are always fresh.
+export type HeadersProvider = () => Record<string, string>
+
+// App-declared RPC surface: method name → call signature. Enables fully typed
+// client.call('user.get', id) with inferred argument and result types.
+//    interface Methods { 'user.get': (id: string) => User }
+// The `never[]` parameter constraint deliberately accepts any concrete
+// signature (contravariance) without resorting to `any`. Generic constraints
+// use the `Record<keyof M, …>` form so plain interfaces (which have no
+// implicit index signature) qualify.
+export type MethodMap = Record<string, (...args: never[]) => unknown>
+
+export type MethodMapConstraint<M> = Record<keyof M, (...args: never[]) => unknown>
+
+export interface Transport {
+    send(request: RpcRequest): Promise<unknown>
+}