hci-atrium 0.1.0

package/dist/rooms/transport-shared.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The machinery shared by the two room transports — the WebSocket ({@link ./transport.RoomSocket})
+ * and the SSE-receive stream ({@link ./sse.RoomEventStream}). Their reconnect *state machines* stay
+ * distinct (WS reconnects via a scheduled timer, SSE via an in-loop backoff), but the genuinely
+ * common parts — the reconnect/timeout constants, the exponential-backoff formula, and the
+ * ``connect()`` ready-waiter bookkeeping — live here so they can't drift apart.
+ */
+/** Backoff floor / ceiling (ms) and the ``connect()`` readiness budget — one source of truth for both
+ * transports (they were duplicated constants before). */
+export declare const RECONNECT_MIN_MS = 500;
+export declare const RECONNECT_MAX_MS = 5000;
+export declare const CONNECT_TIMEOUT_MS = 30000;
+/** The exponential-backoff delay for the ``attempt``-th reconnect (0-based), capped at
+ * {@link RECONNECT_MAX_MS}. */
+export declare function backoffDelay(attempt: number): number;
+/**
+ * The ``connect()`` ready-waiter set both transports keep: each pending ``connect()`` pushes a
+ * ``{resolve, reject}`` pair; the first ``ready`` frame resolves them all, a terminal end / timeout
+ * rejects them all. Draining-then-firing (swap the list out before invoking) keeps a re-entrant
+ * ``connect()`` from a callback safe.
+ */
+export declare class ReadyWaiters {
+    private waiters;
+    add(resolve: () => void, reject: (e: Error) => void): void;
+    resolveAll(): void;
+    rejectAll(error: Error): void;
+}
+//# sourceMappingURL=transport-shared.d.ts.map

package/dist/rooms/transport-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-shared.d.ts","sourceRoot":"","sources":["../../src/rooms/transport-shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;yDACyD;AACzD,eAAO,MAAM,gBAAgB,MAAM,CAAA;AACnC,eAAO,MAAM,gBAAgB,OAAO,CAAA;AACpC,eAAO,MAAM,kBAAkB,QAAS,CAAA;AAExC;+BAC+B;AAC/B,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAiE;IAEhF,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAI1D,UAAU,IAAI,IAAI;IAMlB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAK9B"}

package/dist/rooms/transport-shared.js

@@ -0,0 +1,42 @@
+/**
+ * The machinery shared by the two room transports — the WebSocket ({@link ./transport.RoomSocket})
+ * and the SSE-receive stream ({@link ./sse.RoomEventStream}). Their reconnect *state machines* stay
+ * distinct (WS reconnects via a scheduled timer, SSE via an in-loop backoff), but the genuinely
+ * common parts — the reconnect/timeout constants, the exponential-backoff formula, and the
+ * ``connect()`` ready-waiter bookkeeping — live here so they can't drift apart.
+ */
+/** Backoff floor / ceiling (ms) and the ``connect()`` readiness budget — one source of truth for both
+ * transports (they were duplicated constants before). */
+export const RECONNECT_MIN_MS = 500;
+export const RECONNECT_MAX_MS = 5000;
+export const CONNECT_TIMEOUT_MS = 30_000;
+/** The exponential-backoff delay for the ``attempt``-th reconnect (0-based), capped at
+ * {@link RECONNECT_MAX_MS}. */
+export function backoffDelay(attempt) {
+    return Math.min(RECONNECT_MIN_MS * 2 ** attempt, RECONNECT_MAX_MS);
+}
+/**
+ * The ``connect()`` ready-waiter set both transports keep: each pending ``connect()`` pushes a
+ * ``{resolve, reject}`` pair; the first ``ready`` frame resolves them all, a terminal end / timeout
+ * rejects them all. Draining-then-firing (swap the list out before invoking) keeps a re-entrant
+ * ``connect()`` from a callback safe.
+ */
+export class ReadyWaiters {
+    waiters = [];
+    add(resolve, reject) {
+        this.waiters.push({ resolve, reject });
+    }
+    resolveAll() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const w of waiters)
+            w.resolve();
+    }
+    rejectAll(error) {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const w of waiters)
+            w.reject(error);
+    }
+}
+//# sourceMappingURL=transport-shared.js.map

package/dist/rooms/transport-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-shared.js","sourceRoot":"","sources":["../../src/rooms/transport-shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;yDACyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAA;AACnC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAA;AACpC,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAExC;+BAC+B;AAC/B,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,gBAAgB,GAAG,CAAC,IAAI,OAAO,EAAE,gBAAgB,CAAC,CAAA;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACf,OAAO,GAA+D,EAAE,CAAA;IAEhF,GAAG,CAAC,OAAmB,EAAE,MAA0B;QACjD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;IACxC,CAAC;IAED,UAAU;QACR,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QAC5B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;QACjB,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,CAAC,CAAC,OAAO,EAAE,CAAA;IACtC,CAAC;IAED,SAAS,CAAC,KAAY;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QAC5B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;QACjB,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC1C,CAAC;CACF"}

package/dist/rooms/transport.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The room's live WebSocket transport — extracted from the Player/tools client
+ * (``tools/src/lib/room-ws.ts``) and reshaped for the SDK. One socket carries both text signals
+ * (JSON) and the ephemeral binary audio stream, matching the server's ``/v1/rooms/{id}/ws`` route.
+ *
+ * Wire contract (server ``src/atrium/sessions/router.py``):
+ *   • connect: ``ws(s)://…/v1/rooms/{id}/ws?code=…&identity=…&announce={json}`` (code-auth only —
+ *     the WS route authorizes by connect code, never a bearer, so a host uses its own room's code).
+ *   • inbound (server→client): ``{"kind":"ready", connection_id, participants}`` then
+ *     ``{"kind":"signal", signal}`` text frames + raw binary frames; ``{"kind":"error", detail}`` on
+ *     a rejected send.
+ *   • outbound (client→server): ``{"kind":"signal", type, payload, to?, include_self?, source?,
+ *     ack_id?, reply_to?}`` text frames; a raw binary frame broadcasts ephemerally to the room's
+ *     other subscribers (the sender excluded). The server stamps ``from`` and owns ``connection_id``;
+ *     everything a room carries is ephemeral (durable capture is a session's job).
+ *
+ * Unlike the tools copy this takes an already-resolved ``roomId`` (the Room resolved the code) and an
+ * injectable ``WebSocket`` constructor so the dispatch/correlation layer can be unit-tested against a
+ * scripted fake socket.
+ */
+/** An inbound room signal (``item.signal`` from the server), snake_case as the server serializes it. */
+export interface RoomSignal {
+    type?: string;
+    payload?: unknown;
+    source?: string | null;
+    from?: string | null;
+    to?: string | string[] | null;
+    ack_id?: string | null;
+    reply_to?: string | null;
+    ephemeral?: boolean;
+    origin?: string;
+}
+/** The wire body of an outbound ``{"kind":"signal", …}`` frame (fields the server's WS recv reads). */
+export interface OutboundSignal {
+    type: string;
+    payload?: unknown;
+    to?: string | string[];
+    includeSelf?: boolean;
+    source?: string;
+    ackId?: string;
+    replyTo?: string;
+}
+/** A live room roster entry — the raw item ``room.presence`` yields, as carried in the ``ready``
+ * snapshot and ``presence.join`` payloads. The parsed, query-friendly view (``name`` / merged
+ * ``roles`` / ``connectedAt`` as a ``Date``) is {@link ./participant.Participant}, behind
+ * ``room.participants()`` / ``room.has()``. */
+export interface RosterEntry {
+    connectionId: string;
+    identity?: string | null;
+    announce?: Record<string, unknown>;
+    /** When this connection joined (ISO 8601). With eternal connections, apps that care can tell a
+     * fresh joiner from a week-old tab; most won't need it. */
+    connectedAt?: string | null;
+}
+/**
+ * The transport contract shared by the WebSocket ({@link RoomSocket}) and the SSE-receive +
+ * POST-send ({@link ./sse.RoomEventStream}) room channels — the two interchangeable ways a
+ * {@link ./room.Room} carries text signals. WS also carries the ephemeral binary audio stream; SSE
+ * is signals-only (``sendBinary`` is a no-op there — audio consumers stay WS-only).
+ */
+export interface RoomTransport {
+    connect(): Promise<void>;
+    sendSignal(sig: OutboundSignal): void;
+    sendBinary(data: ArrayBuffer): void;
+    close(): void;
+    connectionId(): string | null;
+    participants(): RosterEntry[];
+}
+/** The minimal ``WebSocket`` surface the transport uses — the browser/Node global satisfies it, and a
+ * test can supply a scripted fake. */
+export interface WebSocketLike {
+    binaryType: string;
+    readyState: number;
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+}
+export type WebSocketCtor = new (url: string) => WebSocketLike;
+/** Why a room connection ended for good — no reconnect recovers. */
+export type RoomEndReason = "code-rotated" | "bad-code" | "room-gone";
+export interface RoomSocketHandlers {
+    /** An inbound text signal (already parsed from the ``{"kind":"signal"}`` envelope). May return a
+     * promise — the SSE transport **awaits** it inline in its read loop, so a consumer (the recorder)
+     * gets Python-style backpressure: the next frame isn't read until this settles. A rejection there
+     * is treated as a transient stream drop (backoff + reconnect). The WS transport ignores the return
+     * (its consumers are synchronous). */
+    onSignal?: (signal: RoomSignal) => void | Promise<void>;
+    /** A raw inbound binary frame (the audio stream). */
+    onBinary?: (data: ArrayBuffer) => void;
+    /** Every (re)open, with the freshly minted connection id — re-send anything the room needs. */
+    onReady?: (connectionId: string) => void;
+    /** The roster changed (seeded from ``ready``, updated by presence deltas; excludes self). */
+    onParticipants?: (participants: RosterEntry[]) => void;
+    /** A server ``{"kind":"error"}`` frame (reserved type, oversized binary, …). */
+    onError?: (detail: string) => void;
+    /** A terminal, identifiable end (code rotated / bad / room gone) — the socket stops reconnecting. */
+    onEnd?: (reason: RoomEndReason) => void;
+    /** The socket failed to reach ``ready`` on its first attempt (a proxy stripping the WS upgrade
+     * looks like this) — the {@link ./room.Room} fallback probe switches to SSE. Set only when
+     * ``probe`` is true; when it fires the socket stops (no reconnect) and {@link connect} rejects. */
+    onUnavailable?: () => void;
+}
+export interface RoomSocketOptions extends RoomSocketHandlers {
+    roomId: string;
+    /** Connect code — the WS route's only auth. A host passes its own room's code. */
+    code: string;
+    /** The instance base URL (http/https); the socket derives ws/wss from it. */
+    baseUrl: string;
+    identity?: string;
+    announce?: Record<string, unknown>;
+    /** Reconnect on unexpected close (default true). */
+    reconnect?: boolean;
+    /** Probe mode: if the first connect fails before ``ready`` (non-terminal), fire
+     * {@link RoomSocketHandlers.onUnavailable} and stop instead of reconnecting — so the Room can
+     * fall back to SSE fast rather than hang the full connect timeout on a WS-stripping proxy. */
+    probe?: boolean;
+    /** Injected ``WebSocket`` constructor (defaults to the runtime global) — the test seam. */
+    WebSocketCtor?: WebSocketCtor;
+}
+/**
+ * A single logical room connection with transparent reconnect. {@link connect} resolves once the
+ * server's first ``ready`` frame arrives (so ``connectionId`` is known); after that, drops reconnect
+ * with backoff until {@link close}. Sends while the socket is momentarily down are dropped (rooms
+ * have no replay) — re-emit inside {@link RoomSocketHandlers.onReady} for reliability.
+ */
+export declare class RoomSocket implements RoomTransport {
+    private readonly opts;
+    private ws;
+    private connId;
+    private closed;
+    private attempt;
+    private retryTimer;
+    private roster;
+    private readonly readyWaiters;
+    private everReady;
+    private terminal;
+    private rotationSeen;
+    private readonly Ctor;
+    constructor(opts: RoomSocketOptions);
+    /** The current connection id, or ``null`` before the first ``ready``. */
+    connectionId(): string | null;
+    /** The current participant roster (excludes self), maintained from ``ready`` + presence deltas. */
+    participants(): RosterEntry[];
+    /** Open the socket and resolve once it's live (the server's ``ready`` frame arrived). Idempotent. */
+    connect(): Promise<void>;
+    /** Send a text signal. Dropped (no-op) while the socket is not open. */
+    sendSignal(sig: OutboundSignal): void;
+    /** Send a raw binary frame (ephemeral, broadcast to others). Dropped while not open. */
+    sendBinary(data: ArrayBuffer): void;
+    /** Close the socket and stop reconnecting (idempotent). */
+    close(): void;
+    private open;
+    private scheduleReconnect;
+    private updateRoster;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/rooms/transport.d.ts.map

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

package/dist/rooms/transport.js

@@ -0,0 +1,258 @@
+/**
+ * The room's live WebSocket transport — extracted from the Player/tools client
+ * (``tools/src/lib/room-ws.ts``) and reshaped for the SDK. One socket carries both text signals
+ * (JSON) and the ephemeral binary audio stream, matching the server's ``/v1/rooms/{id}/ws`` route.
+ *
+ * Wire contract (server ``src/atrium/sessions/router.py``):
+ *   • connect: ``ws(s)://…/v1/rooms/{id}/ws?code=…&identity=…&announce={json}`` (code-auth only —
+ *     the WS route authorizes by connect code, never a bearer, so a host uses its own room's code).
+ *   • inbound (server→client): ``{"kind":"ready", connection_id, participants}`` then
+ *     ``{"kind":"signal", signal}`` text frames + raw binary frames; ``{"kind":"error", detail}`` on
+ *     a rejected send.
+ *   • outbound (client→server): ``{"kind":"signal", type, payload, to?, include_self?, source?,
+ *     ack_id?, reply_to?}`` text frames; a raw binary frame broadcasts ephemerally to the room's
+ *     other subscribers (the sender excluded). The server stamps ``from`` and owns ``connection_id``;
+ *     everything a room carries is ephemeral (durable capture is a session's job).
+ *
+ * Unlike the tools copy this takes an already-resolved ``roomId`` (the Room resolved the code) and an
+ * injectable ``WebSocket`` constructor so the dispatch/correlation layer can be unit-tested against a
+ * scripted fake socket.
+ */
+import { backoffDelay, CONNECT_TIMEOUT_MS, ReadyWaiters } from "./transport-shared.js";
+const WS_OPEN = 1; // WebSocket.OPEN — hardcoded so we don't touch a possibly-absent global constant.
+// Terminal WS close codes the server uses for a connection it will never welcome back on this code —
+// no reconnect recovers, so we stop and surface *why* (mirror of the tools ``room-ws.ts`` client).
+// An endless retry loop on a dead code would otherwise hammer the server's per-IP attempt limiter.
+const CLOSE_CODE_ROTATED = 4410; // the connect code was rotated (advance-signalled by room.code_rotated)
+const CLOSE_BAD_CODE = 4403; // the connect code was rejected (bad/expired)
+const CLOSE_ROOM_GONE = 4404; // the room no longer exists
+function wsUrl(baseUrl, roomId, params) {
+    const base = baseUrl.replace(/^http/, "ws").replace(/\/+$/, "");
+    return `${base}/v1/rooms/${roomId}/ws?${params.toString()}`;
+}
+/**
+ * A single logical room connection with transparent reconnect. {@link connect} resolves once the
+ * server's first ``ready`` frame arrives (so ``connectionId`` is known); after that, drops reconnect
+ * with backoff until {@link close}. Sends while the socket is momentarily down are dropped (rooms
+ * have no replay) — re-emit inside {@link RoomSocketHandlers.onReady} for reliability.
+ */
+export class RoomSocket {
+    opts;
+    ws = null;
+    connId = null;
+    closed = false;
+    attempt = 0;
+    retryTimer = null;
+    roster = [];
+    readyWaiters = new ReadyWaiters();
+    everReady = false;
+    // A terminal failure (rotated / bad / gone code) was seen — never reconnect again.
+    terminal = false;
+    // A room.code_rotated signal arrived — classify the following close as rotation even if its 4410
+    // close code is lost in transit.
+    rotationSeen = false;
+    Ctor;
+    constructor(opts) {
+        this.opts = opts;
+        const Ctor = opts.WebSocketCtor ?? globalThis.WebSocket;
+        if (!Ctor) {
+            throw new Error("Atrium rooms: no WebSocket implementation — pass { WebSocketCtor } (Node <22 has none global)");
+        }
+        this.Ctor = Ctor;
+    }
+    /** The current connection id, or ``null`` before the first ``ready``. */
+    connectionId() {
+        return this.connId;
+    }
+    /** The current participant roster (excludes self), maintained from ``ready`` + presence deltas. */
+    participants() {
+        return [...this.roster];
+    }
+    /** Open the socket and resolve once it's live (the server's ``ready`` frame arrived). Idempotent. */
+    connect() {
+        if (this.everReady && this.ws)
+            return Promise.resolve();
+        // A closed socket never reopens — reject at once rather than call ``open()`` (which early-returns
+        // on ``closed`` without resolving a waiter, hanging the full CONNECT_TIMEOUT). This is the
+        // connect-after-close race: an abort fired ``close()`` just before a consumer awaits ``connect()``.
+        if (this.closed)
+            return Promise.reject(new Error("room closed"));
+        const promise = new Promise((resolve, reject) => {
+            this.readyWaiters.add(resolve, reject);
+        });
+        if (!this.ws) {
+            // A drop may have scheduled a reconnect; clear it so we don't open a second socket (this
+            // manual open supersedes the pending retry).
+            if (this.retryTimer) {
+                clearTimeout(this.retryTimer);
+                this.retryTimer = null;
+            }
+            this.open();
+            const timer = setTimeout(() => {
+                this.readyWaiters.rejectAll(new Error(`room stream not ready within ${CONNECT_TIMEOUT_MS / 1000}s`));
+            }, CONNECT_TIMEOUT_MS);
+            // Clear the timeout when the promise settles either way.
+            void promise.finally(() => clearTimeout(timer)).catch(() => { });
+        }
+        return promise;
+    }
+    /** Send a text signal. Dropped (no-op) while the socket is not open. */
+    sendSignal(sig) {
+        if (!this.ws || this.ws.readyState !== WS_OPEN)
+            return;
+        const frame = {
+            kind: "signal",
+            type: sig.type,
+            payload: sig.payload ?? {},
+        };
+        if (sig.to !== undefined)
+            frame.to = sig.to;
+        if (sig.includeSelf)
+            frame.include_self = true;
+        if (sig.source !== undefined)
+            frame.source = sig.source;
+        if (sig.ackId !== undefined)
+            frame.ack_id = sig.ackId;
+        if (sig.replyTo !== undefined)
+            frame.reply_to = sig.replyTo;
+        this.ws.send(JSON.stringify(frame));
+    }
+    /** Send a raw binary frame (ephemeral, broadcast to others). Dropped while not open. */
+    sendBinary(data) {
+        if (!this.ws || this.ws.readyState !== WS_OPEN)
+            return;
+        this.ws.send(data);
+    }
+    /** Close the socket and stop reconnecting (idempotent). */
+    close() {
+        this.closed = true;
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        this.retryTimer = null;
+        this.ws?.close();
+        this.ws = null;
+        this.readyWaiters.rejectAll(new Error("room closed"));
+    }
+    open() {
+        if (this.closed)
+            return;
+        const params = new URLSearchParams({ code: this.opts.code });
+        if (this.opts.identity)
+            params.set("identity", this.opts.identity);
+        if (this.opts.announce)
+            params.set("announce", JSON.stringify(this.opts.announce));
+        const sock = new this.Ctor(wsUrl(this.opts.baseUrl, this.opts.roomId, params));
+        sock.binaryType = "arraybuffer";
+        this.ws = sock;
+        sock.onmessage = (ev) => {
+            if (typeof ev.data !== "string") {
+                this.opts.onBinary?.(ev.data);
+                return;
+            }
+            let msg;
+            try {
+                msg = JSON.parse(ev.data);
+            }
+            catch {
+                return;
+            }
+            if (msg.kind === "ready") {
+                this.connId = msg.connection_id ?? null;
+                this.attempt = 0;
+                this.everReady = true;
+                this.roster = (msg.participants ?? []).map((p) => ({
+                    connectionId: p.connection_id,
+                    identity: p.identity,
+                    announce: p.announce,
+                    connectedAt: p.connected_at,
+                }));
+                this.opts.onParticipants?.(this.participants());
+                this.readyWaiters.resolveAll();
+                if (this.connId)
+                    this.opts.onReady?.(this.connId);
+            }
+            else if (msg.kind === "signal" && msg.signal) {
+                // Advance notice of an imminent code rotation — mark it so the following close is classified
+                // as a rotation even if the 4410 close code is lost.
+                if (msg.signal.type === "room.code_rotated")
+                    this.rotationSeen = true;
+                this.updateRoster(msg.signal);
+                this.opts.onSignal?.(msg.signal);
+            }
+            else if (msg.kind === "error") {
+                this.opts.onError?.(msg.detail ?? "error");
+            }
+        };
+        sock.onclose = (ev) => {
+            if (this.ws === sock)
+                this.ws = null;
+            if (this.closed)
+                return;
+            const code = ev?.code;
+            const reason = code === CLOSE_CODE_ROTATED || this.rotationSeen
+                ? "code-rotated"
+                : code === CLOSE_BAD_CODE
+                    ? "bad-code"
+                    : code === CLOSE_ROOM_GONE
+                        ? "room-gone"
+                        : null;
+            if (reason) {
+                // Terminal: stop reconnecting for good and surface the reason. A pending connect() that never
+                // reached `ready` rejects identifiably; a live handle learns via onEnd.
+                this.terminal = true;
+                if (!this.everReady)
+                    this.readyWaiters.rejectAll(new Error(`room connection ended: ${reason}`));
+                this.opts.onEnd?.(reason);
+                return;
+            }
+            if (this.opts.probe && !this.everReady) {
+                // The WS never came up on the fallback probe (a proxy stripping the upgrade looks exactly
+                // like this — an abnormal close before ready). Don't retry: signal unavailability so the Room
+                // switches to SSE, and reject the pending connect rather than hang the full connect timeout.
+                this.terminal = true;
+                this.opts.onUnavailable?.();
+                this.readyWaiters.rejectAll(new Error("room websocket unavailable"));
+                return;
+            }
+            this.scheduleReconnect();
+        };
+        // onerror is followed by onclose; let onclose drive the retry so we don't double-schedule.
+        sock.onerror = () => { };
+    }
+    scheduleReconnect() {
+        if (this.closed || this.terminal || this.opts.reconnect === false) {
+            // No reconnect and never became ready → fail any pending connect().
+            if (!this.everReady)
+                this.readyWaiters.rejectAll(new Error("room connection closed before ready"));
+            return;
+        }
+        const delay = backoffDelay(this.attempt);
+        this.attempt += 1;
+        this.retryTimer = setTimeout(() => this.open(), delay);
+    }
+    // Apply a presence delta to the roster (dedupe by connection id; tolerate unknown leaves).
+    updateRoster(sig) {
+        const p = sig.payload;
+        if (sig.type === "presence.join") {
+            if (p?.connection_id && !this.roster.some((x) => x.connectionId === p.connection_id)) {
+                this.roster = [
+                    ...this.roster,
+                    {
+                        connectionId: p.connection_id,
+                        identity: p.identity,
+                        announce: p.announce,
+                        connectedAt: p.connected_at,
+                    },
+                ];
+                this.opts.onParticipants?.(this.participants());
+            }
+        }
+        else if (sig.type === "presence.leave") {
+            if (p?.connection_id && this.roster.some((x) => x.connectionId === p.connection_id)) {
+                this.roster = this.roster.filter((x) => x.connectionId !== p.connection_id);
+                this.opts.onParticipants?.(this.participants());
+            }
+        }
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/rooms/transport.js.map

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

package/dist/shaping/assets.d.ts

@@ -0,0 +1,42 @@
+/** Asset list / get / upload request shaping (mirror of ``_shaping`` asset helpers). */
+import type { FileSource } from "../files.js";
+import { type ShapedRequest } from "./request.js";
+export interface BuildAssetListInput {
+    modality?: string;
+    contentKind?: string[];
+    limit: number;
+    cursor?: string;
+    project?: string;
+    collection?: string;
+}
+/** Build a ``GET /v1/assets`` listing request. The scope is already resolved. */
+export declare function buildAssetList(input: BuildAssetListInput): ShapedRequest;
+/** Build a ``GET /v1/assets/{id}`` request. ``collection`` is already resolved. */
+export declare function buildAssetGet(assetId: string, opts?: {
+    collection?: string;
+}): ShapedRequest;
+export interface BuildUploadInput {
+    file: FileSource;
+    modality?: string;
+    description?: string;
+    collection?: string;
+}
+/** Build a ``GET /v1/assets/{id}/vectors`` request (public by-id). ``space`` (one or a list) is
+ * already resolved; a list rides as repeated ``space=`` query params. */
+export declare function buildAssetVectors(assetId: string, opts?: {
+    space?: string | string[];
+    matchBy?: string;
+}): ShapedRequest;
+/** Build a ``GET /v1/assets/{id}/segments`` request (public by-id). */
+export declare function buildAssetSegments(assetId: string): ShapedRequest;
+/** Build a ``GET /v1/assets/{id}/index`` request (authenticated, visibility-scoped). */
+export declare function buildAssetIndex(assetId: string): ShapedRequest;
+/** Build a ``POST /v1/library/vectors`` bulk request. ``space`` (one or a list) is already
+ * resolved. */
+export declare function buildBulkVectors(ids: string[], input: {
+    space: string | string[];
+    matchBy?: string;
+}): ShapedRequest;
+/** Build a ``POST /v1/assets`` upload request. ``collection`` is already resolved. */
+export declare function buildUpload(input: BuildUploadInput): ShapedRequest;
+//# sourceMappingURL=assets.d.ts.map

package/dist/shaping/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/shaping/assets.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAE7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,aAAa,CAaxE;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,aAAa,CAMhG;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;yEACyE;AACzE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,aAAa,CAaf;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAEjE;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAE9D;AAED;eACe;AACf,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EAAE,EACb,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,aAAa,CAMf;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CAgBlE"}

package/dist/shaping/assets.js

@@ -0,0 +1,77 @@
+/** Asset list / get / upload request shaping (mirror of ``_shaping`` asset helpers). */
+import { applyScope } from "./request.js";
+/** Build a ``GET /v1/assets`` listing request. The scope is already resolved. */
+export function buildAssetList(input) {
+    const query = { limit: input.limit };
+    if (input.cursor !== undefined) {
+        query.cursor = input.cursor;
+    }
+    if (input.modality !== undefined) {
+        query.all_kinds = [input.modality];
+    }
+    if (input.contentKind?.length) {
+        query.content_kind = input.contentKind;
+    }
+    applyScope(query, input.project, input.collection);
+    return { method: "GET", path: "/v1/assets", query };
+}
+/** Build a ``GET /v1/assets/{id}`` request. ``collection`` is already resolved. */
+export function buildAssetGet(assetId, opts = {}) {
+    const req = { method: "GET", path: `/v1/assets/${assetId}` };
+    if (opts.collection !== undefined) {
+        req.query = { collection: opts.collection };
+    }
+    return req;
+}
+/** Build a ``GET /v1/assets/{id}/vectors`` request (public by-id). ``space`` (one or a list) is
+ * already resolved; a list rides as repeated ``space=`` query params. */
+export function buildAssetVectors(assetId, opts = {}) {
+    const query = {};
+    if (opts.space !== undefined) {
+        query.space = opts.space;
+    }
+    if (opts.matchBy !== undefined) {
+        query.match_by = opts.matchBy;
+    }
+    const req = { method: "GET", path: `/v1/assets/${assetId}/vectors` };
+    if (Object.keys(query).length) {
+        req.query = query;
+    }
+    return req;
+}
+/** Build a ``GET /v1/assets/{id}/segments`` request (public by-id). */
+export function buildAssetSegments(assetId) {
+    return { method: "GET", path: `/v1/assets/${assetId}/segments` };
+}
+/** Build a ``GET /v1/assets/{id}/index`` request (authenticated, visibility-scoped). */
+export function buildAssetIndex(assetId) {
+    return { method: "GET", path: `/v1/assets/${assetId}/index` };
+}
+/** Build a ``POST /v1/library/vectors`` bulk request. ``space`` (one or a list) is already
+ * resolved. */
+export function buildBulkVectors(ids, input) {
+    const body = { ids, space: input.space };
+    if (input.matchBy !== undefined) {
+        body.match_by = input.matchBy;
+    }
+    return { method: "POST", path: "/v1/library/vectors", json: body };
+}
+/** Build a ``POST /v1/assets`` upload request. ``collection`` is already resolved. */
+export function buildUpload(input) {
+    const fields = {};
+    if (input.modality !== undefined) {
+        fields.modality = input.modality;
+    }
+    if (input.description !== undefined) {
+        fields.description = input.description;
+    }
+    if (input.collection !== undefined) {
+        fields.collection = input.collection;
+    }
+    return {
+        method: "POST",
+        path: "/v1/assets",
+        multipart: { fields, files: { file: { source: input.file } } },
+    };
+}
+//# sourceMappingURL=assets.js.map