transport-io 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 #V0ID <hey@v0id.me>
+
+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,28 @@
+# transport-io
+
+Real-time apps over WebTransport. Socket.IO's shape, on a transport with multiple streams
+and datagrams, without Socket.IO's mistakes.
+
+Framing, length prefixes, buffer accumulation, stream lifecycle and backpressure queues are
+hidden. Reliability is not: an event declares `stream` or `datagram` in the contract, and
+"this message may be dropped" is a property of your data that lives in the type system.
+
+**Full documentation, and the limitations you should read before installing, are in the
+[repository README](https://github.com/v0id-user/transport-io#readme).** The short version:
+
+- **WebTransport only.** No WebSocket fallback, deliberately — a fallback would silently
+  make the datagram lane reliable and ordered, which is a lie about your data.
+- **Chrome and Firefox.** Safari cannot talk to a quiche-backed server and is unsupported.
+- **The server needs a separate native install**, and its Linux prebuild needs glibc 2.38 —
+  no default Node `-slim` image has it, and Alpine has no prebuild at all.
+- **Each `call()` leaks ~5.95 KB of server memory**, upstream in the QUIC binding, not in
+  this library. `emit` and datagrams are flat.
+- **The protocol is v0 and unstable.** Both sides currently require an exact match.
+
+```bash
+npm install transport-io
+```
+
+A git install does not work — the repository root is a private monorepo package.
+
+MIT © #V0ID

package/dist/adapter.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The fan-out boundary. PROTOCOL.md is silent on this by design: it is our contract with
+ * a message bus, not with a peer.
+ *
+ * Rules core obeys (D40): every method is async even in memory, frames cross as bytes and
+ * never as live objects, `PeerId` is a stable cross-process string, no node assumes it
+ * knows a room's full membership, a frame for a room with no local members is dropped
+ * silently rather than erroring, and any method may reject — core degrades rather than
+ * crashing.
+ */
+export type PeerId = string;
+export type Frame = Uint8Array;
+export type Lane = 'stream' | 'datagram';
+/** The envelope carries the origin node. The frame the peer receives is not these bytes. */
+export interface RemoteEnvelope {
+    readonly room: string;
+    readonly frame: Frame;
+    readonly lane: Lane;
+    readonly nodeId: string;
+    readonly except?: readonly PeerId[];
+}
+export interface BroadcastOptions {
+    readonly lane: Lane;
+    readonly except?: readonly PeerId[];
+}
+export interface Adapter {
+    /**
+     * The node this adapter publishes as. It is the identity stamped into every
+     * `RemoteEnvelope`, and therefore the identity core dedupes against.
+     *
+     * Declared here rather than left to implementations because `Server` also has a
+     * `nodeId`, and when the two diverged the dedup guard silently never fired: a node
+     * delivered its own broadcast twice, once locally and once back off the bus. Reading
+     * both from one place makes that impossible rather than merely unlikely.
+     */
+    readonly nodeId: string;
+    join(room: string, peer: PeerId): Promise<void>;
+    leave(room: string, peer: PeerId): Promise<void>;
+    broadcast(room: string, frame: Frame, opts: BroadcastOptions): Promise<void>;
+    onRemote(cb: (envelope: RemoteEnvelope) => void): void;
+}
+/**
+ * Write-only half of the boundary, for a caller that publishes without hosting sessions.
+ * Internal in this version (D22): the interface is a design constraint, and a
+ * cross-process implementation arrives with the Redis adapter.
+ */
+export interface Publisher {
+    broadcast(room: string, frame: Frame, opts: BroadcastOptions): Promise<void>;
+}
+/** Ships in core and is the default, so installing this library needs no infrastructure. */
+/**
+ * A bus two or more `MemoryAdapter`s can share, so a single process can model several
+ * nodes. Without it `MemoryAdapter` is per-instance and two of them cannot hear each
+ * other, which is precisely why the cross-node delivery path had never executed a line.
+ */
+export declare function memoryBus(): MemoryBus;
+export interface MemoryBus {
+    readonly listeners: ((e: RemoteEnvelope) => void)[];
+}
+export declare class MemoryAdapter implements Adapter {
+    #private;
+    readonly nodeId: string;
+    constructor(nodeId: string, bus?: MemoryBus);
+    join(room: string, peer: PeerId): Promise<void>;
+    leave(room: string, peer: PeerId): Promise<void>;
+    broadcast(room: string, frame: Frame, opts: BroadcastOptions): Promise<void>;
+    onRemote(cb: (e: RemoteEnvelope) => void): void;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAA;AAC3B,MAAM,MAAM,KAAK,GAAG,UAAU,CAAA;AAC9B,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,UAAU,CAAA;AAExC,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED,MAAM,WAAW,OAAO;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5E,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI,CAAA;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7E;AAED,4FAA4F;AAC5F;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,SAAS,CAErC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC,EAAE,CAAA;CACpD;AAED,qBAAa,aAAc,YAAW,OAAO;;IAG3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB,YAAY,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,SAAuB,EAGvD;IAEK,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOpD;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrD;IAEK,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjF;IAED,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI,CAE9C;CACF"}

package/dist/adapter.js

@@ -0,0 +1,51 @@
+/** Ships in core and is the default, so installing this library needs no infrastructure. */
+/**
+ * A bus two or more `MemoryAdapter`s can share, so a single process can model several
+ * nodes. Without it `MemoryAdapter` is per-instance and two of them cannot hear each
+ * other, which is precisely why the cross-node delivery path had never executed a line.
+ */
+export function memoryBus() {
+    return { listeners: [] };
+}
+export class MemoryAdapter {
+    #rooms = new Map();
+    #bus;
+    nodeId;
+    constructor(nodeId, bus = memoryBus()) {
+        this.nodeId = nodeId;
+        this.#bus = bus;
+    }
+    async join(room, peer) {
+        let set = this.#rooms.get(room);
+        if (set === undefined) {
+            set = new Set();
+            this.#rooms.set(room, set);
+        }
+        set.add(peer);
+    }
+    async leave(room, peer) {
+        const set = this.#rooms.get(room);
+        if (set === undefined)
+            return;
+        set.delete(peer);
+        if (set.size === 0)
+            this.#rooms.delete(room);
+    }
+    async broadcast(room, frame, opts) {
+        // A single process still delivers its own publish back, because that is what a real
+        // bus does and core must dedupe rather than rely on the adapter suppressing it.
+        const envelope = {
+            room,
+            frame,
+            lane: opts.lane,
+            nodeId: this.nodeId,
+            ...(opts.except === undefined ? {} : { except: opts.except }),
+        };
+        for (const l of this.#bus.listeners)
+            l(envelope);
+    }
+    onRemote(cb) {
+        this.#bus.listeners.push(cb);
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAsDA,4FAA4F;AAC5F;;;;GAIG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;AAC1B,CAAC;AAMD,MAAM,OAAO,aAAa;IACf,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAA;IACvC,IAAI,CAAW;IACf,MAAM,CAAQ;IAEvB,YAAY,MAAc,EAAE,GAAG,GAAc,SAAS,EAAE;QACtD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAA;IACjB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,IAAY;QACnC,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC/B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;YACf,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAC5B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACf,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,IAAY;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACjC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAM;QAC7B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAChB,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC9C,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,KAAY,EAAE,IAAsB;QAChE,oFAAoF;QACpF,gFAAgF;QAChF,MAAM,QAAQ,GAAmB;YAC/B,IAAI;YACJ,KAAK;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;SAC9D,CAAA;QACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;IAClD,CAAC;IAED,QAAQ,CAAC,EAA+B;QACtC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC9B,CAAC;CACF"}

package/dist/client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Client surface.
+ *
+ * Constructible without I/O: nothing here touches `window` or `WebTransport` at module
+ * scope, so importing this on a server — which Next.js will do — is safe. Feature
+ * detection happens inside connect().
+ */
+import { type AnyMap, type CallableOf, type Contract } from './contract.ts';
+import { TransportError } from './errors.ts';
+import { type SessionStats } from './session.ts';
+import type { Connection } from './transport/types.ts';
+export type Status = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
+export interface ClientState {
+    readonly status: Status;
+    readonly sessionId: string | null;
+    readonly rooms: readonly string[];
+    readonly lastError: TransportError | null;
+}
+export interface ClientOptions<C extends Contract = Contract> {
+    /**
+     * How long to wait for the peer's handshake before giving up. The deadline covers
+     * opening the emit stream as well as the exchange, so a transport that never opens one
+     * fails here rather than hanging.
+     */
+    readonly handshakeDeadlineMs?: number;
+    readonly contract: C;
+    /** Supplied by the transport seam, so this class never imports a transport. */
+    readonly connect: () => Promise<Connection>;
+    readonly validateInbound?: boolean;
+    /** Clients stamp their own origin on outbound datagrams. */
+    readonly origin?: number;
+    /** Test seam: how a queued datagram flush is deferred. Defaults to a microtask. */
+    readonly scheduleFlush?: (flush: () => void) => void;
+    /** Test seam: the clock the TTL is measured against. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare class Client<M extends AnyMap = AnyMap> {
+    #private;
+    constructor(opts: ClientOptions);
+    /**
+     * Referentially stable until something actually changes. Returning a freshly built
+     * object on each call makes useSyncExternalStore re-render forever, which is the single
+     * most common way this shape is implemented incorrectly.
+     */
+    getSnapshot(): ClientState;
+    subscribe(listener: () => void): () => void;
+    /** Idempotent and refcounted: two components sharing a client cannot tear each other
+     *  down, which matters because React StrictMode mounts twice in development. */
+    connect(): Promise<void>;
+    disconnect(): void;
+    /** The lane comes from the contract, never from this call site. */
+    emit<K extends keyof M & string>(event: K, payload: M[K]['payload']): void;
+    on<K extends keyof M & string>(event: K, handler: (payload: M[K]['payload']) => void): () => void;
+    /** Available only on events declaring `returns`. Aborting resets the QUIC stream. */
+    call<K extends CallableOf<M> & string>(event: K, payload: M[K]['payload'], options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<M[K]['returns']>;
+    stats(): SessionStats | undefined;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,MAAM,EAAmB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAAA;CAC1C;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAErC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,mFAAmF;IACnF,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IACpD,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED,qBAAa,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;;IAc3C,YAAY,IAAI,EAAE,aAAa,EAE9B;IAED;;;;OAIG;IACH,WAAW,IAAI,WAAW,CAEzB;IAED,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAK1C;IAED;oFACgF;IAC1E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAS7B;IAED,UAAU,IAAI,IAAI,CAQjB;IAED,mEAAmE;IACnE,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAEzE;IAED,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI,GAC1C,MAAM,IAAI,CAYZ;IAED,qFAAqF;IAC/E,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,EACzC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EACxB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAE1B;IAED,KAAK,IAAI,YAAY,GAAG,SAAS,CAEhC;CAoFF"}

package/dist/client.js

@@ -0,0 +1,162 @@
+/**
+ * Client surface.
+ *
+ * Constructible without I/O: nothing here touches `window` or `WebTransport` at module
+ * scope, so importing this on a server — which Next.js will do — is safe. Feature
+ * detection happens inside connect().
+ */
+import { buildEventTable } from './contract.js';
+import { TransportError } from './errors.js';
+import { CloseCode, FrameType } from './protocol.js';
+import { Session } from './session.js';
+export class Client {
+    #opts;
+    #listeners = new Set();
+    #handlers = new Map();
+    #session;
+    #snapshot = Object.freeze({
+        status: 'idle',
+        sessionId: null,
+        rooms: [],
+        lastError: null,
+    });
+    #refs = 0;
+    #connecting;
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    /**
+     * Referentially stable until something actually changes. Returning a freshly built
+     * object on each call makes useSyncExternalStore re-render forever, which is the single
+     * most common way this shape is implemented incorrectly.
+     */
+    getSnapshot() {
+        return this.#snapshot;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** Idempotent and refcounted: two components sharing a client cannot tear each other
+     *  down, which matters because React StrictMode mounts twice in development. */
+    async connect() {
+        this.#refs++;
+        if (this.#connecting === undefined)
+            this.#connecting = this.#doConnect();
+        try {
+            await this.#connecting;
+        }
+        catch (e) {
+            this.#connecting = undefined;
+            throw e;
+        }
+    }
+    disconnect() {
+        this.#refs = Math.max(0, this.#refs - 1);
+        if (this.#refs > 0)
+            return;
+        this.#patch({ status: 'closing' });
+        this.#session?.close(CloseCode.WT_NO_ERROR, 'client disconnect');
+        this.#session = undefined;
+        this.#connecting = undefined;
+        this.#patch({ status: 'closed', sessionId: null, rooms: [] });
+    }
+    /** The lane comes from the contract, never from this call site. */
+    emit(event, payload) {
+        this.#requireSession().emit(event, payload);
+    }
+    on(event, handler) {
+        let set = this.#handlers.get(event);
+        if (set === undefined) {
+            set = new Set();
+            this.#handlers.set(event, set);
+        }
+        set.add(handler);
+        const off = this.#session?.on(event, (p) => handler(p));
+        return () => {
+            set.delete(handler);
+            off?.();
+        };
+    }
+    /** Available only on events declaring `returns`. Aborting resets the QUIC stream. */
+    async call(event, payload, options) {
+        return (await this.#requireSession().call(event, payload, options));
+    }
+    stats() {
+        return this.#session?.stats();
+    }
+    async #doConnect() {
+        this.#patch({ status: 'connecting', lastError: null });
+        try {
+            const table = await buildEventTable(this.#opts.contract);
+            const conn = await this.#opts.connect();
+            // Chrome implements neither `requireUnreliable` nor `reliability`, so `undefined`
+            // must pass or every session on the dominant browser would be refused. Only an
+            // explicit reliable-only is a lie about the datagram lane.
+            if (conn.reliability() === 'reliable-only') {
+                // §10.2 code 1006. Throwing without closing left the peer holding a session this
+                // side had already abandoned, with nothing on the wire to say why.
+                conn.close(CloseCode.WT_RELIABILITY_REFUSED, 'reliable-only transport refused');
+                throw new TransportError('WT_RELIABILITY_REFUSED', 'the session negotiated reliable-only transport', 'The datagram lane would silently become reliable and ordered. This library refuses rather than lie about your data.');
+            }
+            const session = new Session(conn, {
+                table,
+                origin: this.#opts.origin ?? 0x80000001,
+                ...(this.#opts.validateInbound === undefined
+                    ? {}
+                    : { validateInbound: this.#opts.validateInbound }),
+                ...(this.#opts.handshakeDeadlineMs === undefined
+                    ? {}
+                    : { handshakeDeadlineMs: this.#opts.handshakeDeadlineMs }),
+                ...(this.#opts.scheduleFlush === undefined
+                    ? {}
+                    : { scheduleFlush: this.#opts.scheduleFlush }),
+                ...(this.#opts.now === undefined ? {} : { now: this.#opts.now }),
+            });
+            this.#session = session;
+            for (const [event, handlers] of this.#handlers) {
+                for (const h of handlers)
+                    session.on(event, (p) => h(p));
+            }
+            session.onControl((type, body) => this.#onMembership(type, body));
+            await session.start();
+            this.#patch({ status: 'connected', sessionId: `s-${session.origin}` });
+            void conn.closed.then(() => {
+                this.#patch({ status: 'closed', sessionId: null, rooms: [] });
+            });
+        }
+        catch (e) {
+            const err = e instanceof TransportError
+                ? e
+                : new TransportError('WT_SESSION_CLOSED', String(e), 'Retry the connection.');
+            this.#patch({ status: 'closed', lastError: err });
+            throw err;
+        }
+    }
+    /** Rooms are server-authoritative, so membership only ever arrives as a notification. */
+    #onMembership(type, body) {
+        const room = body.room;
+        if (typeof room !== 'string')
+            return;
+        const rooms = new Set(this.#snapshot.rooms);
+        if (type === FrameType.JOIN)
+            rooms.add(room);
+        else
+            rooms.delete(room);
+        this.#patch({ rooms: [...rooms].sort() });
+    }
+    #requireSession() {
+        if (this.#session === undefined) {
+            throw new TransportError('WT_SESSION_CLOSED', 'not connected', 'Await connect() before emitting.');
+        }
+        return this.#session;
+    }
+    #patch(next) {
+        this.#snapshot = Object.freeze({ ...this.#snapshot, ...next });
+        for (const l of this.#listeners)
+            l();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/codec.d.ts

@@ -0,0 +1,5 @@
+export declare function encodePayload(value: unknown): Uint8Array;
+export declare function decodePayload(bytes: Uint8Array): unknown;
+/** Validate inbound only. The process that produced a payload need not check its own work. */
+export declare function validate(schema: import('./contract.ts').Schema, value: unknown): Promise<unknown>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAMA,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAmBxD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAoBxD;AAED,8FAA8F;AAC9F,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,OAAO,eAAe,EAAE,MAAM,EACtC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,OAAO,CAAC,CAgBlB"}

package/dist/codec.js

@@ -0,0 +1,47 @@
+/** JSON over UTF-8. PROTOCOL.md §5.3 — codec 0x01, the only one this version speaks. */
+import { TransportError } from './errors.js';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+export function encodePayload(value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (cause) {
+        throw new TransportError('WT_VALIDATION_FAILED', `payload is not JSON-serialisable: ${cause.message}`, 'Remove cycles, functions and BigInt from the payload, or declare a codec that supports them.');
+    }
+    if (json === undefined) {
+        throw new TransportError('WT_VALIDATION_FAILED', 'payload serialised to undefined', 'Send null rather than undefined. A zero-length frame is a protocol error.');
+    }
+    return encoder.encode(json);
+}
+export function decodePayload(bytes) {
+    let text;
+    try {
+        text = decoder.decode(bytes);
+    }
+    catch {
+        throw new TransportError('WT_PROTOCOL_ERROR', 'payload is not valid UTF-8', 'Check the sender is encoding with codec 0x01 (JSON over UTF-8).');
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new TransportError('WT_PROTOCOL_ERROR', `payload is not valid JSON: ${cause.message}`, 'Check the sender is encoding with codec 0x01 (JSON over UTF-8).');
+    }
+}
+/** Validate inbound only. The process that produced a payload need not check its own work. */
+export async function validate(schema, value) {
+    const result = await schema['~standard'].validate(value);
+    if ('issues' in result && result.issues !== undefined) {
+        const first = result.issues[0];
+        const path = first?.path
+            ?.map((p) => (typeof p === 'object' ? String(p.key) : String(p)))
+            .join('.');
+        throw new TransportError('WT_VALIDATION_FAILED', path
+            ? `field '${path}': ${first?.message ?? 'invalid'}`
+            : (first?.message ?? 'invalid payload'), 'Fix the payload to match the schema declared in the contract.');
+    }
+    return result.value;
+}
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;AACjC,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;AAEzD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,qCAAsC,KAAe,CAAC,OAAO,EAAE,EAC/D,8FAA8F,CAC/F,CAAA;IACH,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,iCAAiC,EACjC,2EAA2E,CAC5E,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,cAAc,CACtB,mBAAmB,EACnB,4BAA4B,EAC5B,iEAAiE,CAClE,CAAA;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,cAAc,CACtB,mBAAmB,EACnB,8BAA+B,KAAe,CAAC,OAAO,EAAE,EACxD,iEAAiE,CAClE,CAAA;IACH,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAsC,EACtC,KAAc;IAEd,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IACxD,IAAI,QAAQ,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QAC9B,MAAM,IAAI,GAAG,KAAK,EAAE,IAAI;YACtB,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;aAChE,IAAI,CAAC,GAAG,CAAC,CAAA;QACZ,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,IAAI;YACF,CAAC,CAAC,UAAU,IAAI,MAAM,KAAK,EAAE,OAAO,IAAI,SAAS,EAAE;YACnD,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,IAAI,iBAAiB,CAAC,EACzC,+DAA+D,CAChE,CAAA;IACH,CAAC;IACD,OAAQ,MAA6B,CAAC,KAAK,CAAA;AAC7C,CAAC"}

package/dist/contract.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The contract is the single source of truth. Reading `contract.ts` in an application
+ * tells you every event, payload and lane without reading anything else.
+ */
+import type { StandardSchemaV1, StandardTypedV1 } from '@standard-schema/spec';
+export type Lane = 'stream' | 'datagram';
+export type Schema = StandardSchemaV1;
+/**
+ * `returns` is meaningful only on the stream lane: a datagram has no response path.
+ *
+ * The `returns?: never` on the datagram branch is load-bearing, not decoration. Excess
+ * property checking against a *union* admits any property present on any member, so
+ * `{ lane: 'datagram', payload, returns }` compiled happily, `CallableOf` admitted it, and
+ * `call()` served it over a bidirectional stream. A contract that says "may be dropped"
+ * produced a guaranteed ordered message with the type system agreeing — a direct violation
+ * of D1, the first decision this project made.
+ */
+export type EventDef = {
+    readonly lane: 'datagram';
+    readonly payload: Schema;
+    readonly id?: number;
+    readonly returns?: never;
+} | {
+    readonly lane: 'stream';
+    readonly payload: Schema;
+    readonly returns?: Schema;
+    readonly id?: number;
+};
+export type Contract = Readonly<Record<string, EventDef>>;
+export type Infer<S extends StandardTypedV1> = StandardTypedV1.InferOutput<S>;
+/**
+ * The plain payload/returns map every public signature is written against, so that no
+ * method hover ever has to print a validator's internal types. See D57 — declaring
+ * `interface AppMap extends MapOf<typeof contract> {}` is what keeps hover at 126
+ * characters instead of 303.
+ */
+export type MapOf<C extends Contract> = {
+    readonly [K in keyof C]: {
+        readonly payload: Infer<C[K]['payload']>;
+        readonly returns: C[K] extends {
+            readonly returns: infer R extends Schema;
+        } ? Infer<R> : never;
+    };
+};
+export interface EventShape {
+    readonly payload: unknown;
+    readonly returns: unknown;
+}
+export type AnyMap = Readonly<Record<string, EventShape>>;
+/** Events declaring `returns`, and therefore callable. */
+export type CallableOf<M extends AnyMap> = {
+    [K in keyof M]: [M[K]['returns']] extends [never] ? never : K;
+}[keyof M];
+export declare function defineContract<const C extends Contract>(contract: C): C;
+/** A types-only schema, for inference without runtime validation. */
+export declare function type$<T>(): StandardSchemaV1<unknown, T>;
+export interface EventEntry {
+    readonly name: string;
+    readonly id: number;
+    readonly lane: Lane;
+    readonly def: EventDef;
+}
+export interface EventTable {
+    readonly entries: readonly EventEntry[];
+    byName(name: string): EventEntry | undefined;
+    byId(id: number): EventEntry | undefined;
+    /** The `[name, id, lane]` triples the handshake carries. PROTOCOL.md §4.3. */
+    wire(): readonly [string, number, Lane][];
+}
+/**
+ * PROTOCOL.md §5.4 — the first four bytes of SHA-256 of the event name, big-endian.
+ *
+ * Async because `crypto.subtle` is, and because writing SHA-256 by hand would mean typing
+ * its round constants from memory, which is the one thing D58 forbids. Both `connect()`
+ * and `listen()` are already async, so the table is built once at session start.
+ */
+export declare function eventIdOf(name: string): Promise<number>;
+export declare function buildEventTable(contract: Contract): Promise<EventTable>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -0,0 +1,54 @@
+import { TransportError } from './errors.js';
+import { EVENT_ID_NOT_APPLICABLE } from './protocol.js';
+export function defineContract(contract) {
+    return contract;
+}
+/** A types-only schema, for inference without runtime validation. */
+export function type$() {
+    return {
+        '~standard': {
+            version: 1,
+            vendor: 'transport-io',
+            validate: (value) => ({ value: value }),
+        },
+    };
+}
+/**
+ * PROTOCOL.md §5.4 — the first four bytes of SHA-256 of the event name, big-endian.
+ *
+ * Async because `crypto.subtle` is, and because writing SHA-256 by hand would mean typing
+ * its round constants from memory, which is the one thing D58 forbids. Both `connect()`
+ * and `listen()` are already async, so the table is built once at session start.
+ */
+export async function eventIdOf(name) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(name));
+    return new DataView(digest).getUint32(0, false);
+}
+export async function buildEventTable(contract) {
+    const names = Object.keys(contract).sort();
+    const entries = [];
+    const byId = new Map();
+    const byName = new Map();
+    for (const name of names) {
+        const def = contract[name];
+        const id = def.id ?? (await eventIdOf(name));
+        if (id === EVENT_ID_NOT_APPLICABLE) {
+            throw new TransportError('WT_CONTRACT_MISMATCH', `event '${name}' resolves to the reserved id 0`, 'Set an explicit `id` on this event. Zero is reserved for frames whose meaning comes from the stream.');
+        }
+        const clash = byId.get(id);
+        if (clash !== undefined) {
+            throw new TransportError('WT_CONTRACT_MISMATCH', `events '${clash.name}' and '${name}' both hash to id ${id}`, `Set an explicit \`id\` on one of them, for example { ..., id: ${id + 1} }. Do not rename your events.`);
+        }
+        const entry = { name, id, lane: def.lane, def };
+        entries.push(entry);
+        byId.set(id, entry);
+        byName.set(name, entry);
+    }
+    return {
+        entries,
+        byName: (n) => byName.get(n),
+        byId: (i) => byId.get(i),
+        wire: () => entries.map((e) => [e.name, e.id, e.lane]),
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AA2DvD,MAAM,UAAU,cAAc,CAA2B,QAAW;IAClE,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,KAAK;IACnB,OAAO;QACL,WAAW,EAAE;YACX,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,cAAc;YACtB,QAAQ,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAU,EAAE,CAAC;SACtD;KACF,CAAA;AACH,CAAC;AAmBD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY;IAC1C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACpF,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAkB;IACtD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1C,MAAM,OAAO,GAAiB,EAAE,CAAA;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAsB,CAAA;IAC1C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAA;IAE5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAa,CAAA;QACtC,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;QAC5C,IAAI,EAAE,KAAK,uBAAuB,EAAE,CAAC;YACnC,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,UAAU,IAAI,iCAAiC,EAC/C,sGAAsG,CACvG,CAAA;QACH,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,cAAc,CACtB,sBAAsB,EACtB,WAAW,KAAK,CAAC,IAAI,UAAU,IAAI,qBAAqB,EAAE,EAAE,EAC5D,iEAAiE,EAAE,GAAG,CAAC,gCAAgC,CACxG,CAAA;QACH,CAAC;QACD,MAAM,KAAK,GAAe,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,CAAA;QAC3D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACnB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;QACnB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACzB,CAAC;IAED,OAAO;QACL,OAAO;QACP,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5B,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAA2B,CAAC;KACjF,CAAA;AACH,CAAC"}