hci-atrium 0.1.0

package/dist/rooms/room.js

@@ -0,0 +1,1357 @@
+/**
+ * The live room handle — pure transport over the room WebSocket. Returned by ``client.rooms.open`` /
+ * ``client.rooms.join(code)`` / the loginless {@link joinRoom}. Feature-equivalent to the Python
+ * SDK's ``Room`` (rooms.py) + ``AsyncRoom`` (aio.py), but JS needs no sync/async split — there is one
+ * API: ``room.on(...)`` registers, ``await room.request(...)`` correlates.
+ *
+ * Transport: everything rides one WebSocket (``/v1/rooms/{id}/ws``) — text signals *and* the
+ * ephemeral binary audio stream. That differs from the Python SDK (SSE receive + a REST ``/signal``
+ * POST); it's the extract-from-use path (the Player/tools already speak WS) and the only transport
+ * that carries binary. The REST ``/signal`` wire body is still the canonical cross-SDK shape
+ * ({@link ../shaping/rooms.buildRoomSignal}); the fields match field-for-field.
+ *
+ * Correlation (mirror of ``_RoomDispatcher``): dispatch starts with {@link connect}. Each inbound
+ * signal routes to the handler registered for its ``type``; a handler's return value is sent back as
+ * the response when the signal was a {@link request} (carried an ``ackId``) — so a responder writes
+ * no correlation plumbing, it just returns. Pending {@link request}s resolve by ``replyTo``.
+ *
+ * Durable & reactive surfaces (wave 2): {@link Room.record} bridges the room into a session over an
+ * SSE-observe {@link ./recorder.Recorder} (every WS send is ephemeral, so durable capture rides the
+ * observe stream); {@link Room.audioVectors} embeds the live snippet stream and {@link Room.audioScores}
+ * fuses it against named anchors for a {@link ../decider.Decider}. Still deferred to later waves: the
+ * ``offer_embeds`` / ``offer_chat`` broker protocol, and ``offerAudioCapture`` (which will bind to the
+ * active recorder via {@link Room.activeRecorders} / {@link Room.onRecordersChanged}).
+ */
+import { by, toAnchorMembers } from "../by.js";
+import { AtriumError } from "../errors.js";
+import { asError, isBrowser } from "../http.js";
+import { buildLayerClearBody, buildLayerEffectsBody, buildLayerPositionBody, buildPlayBody, buildRoomRotateCode, buildRoomSignal, buildShowBody, } from "../shaping/rooms.js";
+import { BrokerError, CAPTURE_OFFER_ROLE, CHAT_BROKER_ROLE, DEFAULT_CHAT_MAX_TOKENS, DEFAULT_MAX_ANCHORS, EMBED_BROKER_ROLE, parseAnchorDescriptor, TRANSCRIPTION_OFFER_ROLE, validateChatMessages, } from "./brokers.js";
+import { AUDIO_ROLE, AUDIO_SIGNAL, decodeAudioFrame, } from "./codec.js";
+import { OfferedCapture } from "./offer-capture.js";
+import { OfferedTranscription } from "./offer-transcription.js";
+import { parseParticipant, participantMatches, } from "./participant.js";
+import { Recorder } from "./recorder.js";
+import { AUDIO_SNIPPET_CONSUMER_ROLE, decodeAudioSnippetFrame, } from "./snippet.js";
+import { RoomEventStream, readObserveRoster } from "./sse.js";
+import { TRANSCRIBER_SOURCE, Transcriber } from "./transcriber.js";
+import { RoomSocket, } from "./transport.js";
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+// A raw audio-consumer socket ({@link Room.audioClips} / {@link Room.snippetStream}) buffers decoded
+// frames for a consumer that pulls in its own time; a slow consumer must not grow this without bound,
+// so it drops the OLDEST buffered frame past this cap (live audio favours recency — mirror of the
+// offers' per-source ClipQueue). A prompt consumer never reaches it.
+const RAW_CONSUMER_QUEUE_MAX = 32;
+function toRoomEvent(sig) {
+    return {
+        type: sig.type ?? "",
+        payload: sig.payload && typeof sig.payload === "object"
+            ? sig.payload
+            : {},
+        source: sig.source ?? null,
+        from: sig.from ?? null,
+        to: sig.to ?? null,
+        ackId: sig.ack_id ?? null,
+        replyTo: sig.reply_to ?? null,
+        ephemeral: Boolean(sig.ephemeral),
+    };
+}
+/** A random opaque id (a UUID with dashes stripped, else a time-seeded fallback) — request ack ids
+ * and dedicated-consumer socket identities. Shared with the standing offers ({@link ./standing-source}). */
+export function randomId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID().replace(/-/g, "");
+    return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+/** Open a URL in a new browser tab (``window.open``). Throws outside a browser — there is no tab to
+ * open (the SDK is browser-safe, so it guards on {@link isBrowser} rather than assume ``window``). */
+function openTab(url) {
+    if (!isBrowser() || typeof window.open !== "function") {
+        throw new Error(`cannot open a browser tab outside a browser — use the URL directly: ${url}`);
+    }
+    window.open(url, "_blank", "noopener");
+}
+export class Room {
+    id;
+    connectCode;
+    name;
+    projectId;
+    deps;
+    socket = null;
+    // The single room-level transport decision, latched at connect: true once the signal channel fell
+    // back to (or was pinned to) SSE. Binary audio is WS-only, so every audio consumer AND standing
+    // offer CONSULTS this (via requireWsAudio) and refuses fast rather than spinning a doomed WS
+    // reconnect — signals and audio agree on the environment. The latch is per-handle (a fresh Room
+    // re-probes).
+    usingSse = false;
+    connectPromise = null;
+    handlers = new Map();
+    anyHandlers = new Set();
+    pending = new Map();
+    // Terminal-end fan-out: listeners registered via `onEnd`, fired exactly once from `handleEnd`
+    // (the transport's typed classification), guarded by `ended` so a doubled transport callback or a
+    // close() racing the end can't fire them twice.
+    ended = false;
+    endListeners = new Set();
+    audioSubscribers = new Set();
+    // Audio consumption rides a DEDICATED socket that announces `role: audio-consumer`, so a producer
+    // sees demand (its broadcast gate). Opened on the first subscriber, closed on the last — mirror of
+    // the Player/tools `use-audio-signal` consumer connection.
+    audioSocket = null;
+    layerWatchers = new Set();
+    // Durable-capture recorders started by `record(into)`, plus the change-listeners a wave-4 capture
+    // offer subscribes with — the recorder-registration seam (`_notify_recorders_changed` in Python).
+    recorders = [];
+    recorderListeners = new Set();
+    // Live transcription brokers started by `transcribe()` — stopped on room close (a side effect,
+    // like `record`). Mirror of Python's `AsyncRoom._transcribers`.
+    transcribers = [];
+    // Standing-service offers (`offerTranscription` / `offerAudioCapture`) — each stopped (winding down
+    // + finalizing) on room close. Mirror of Python's `AsyncRoom._offered_services`.
+    offeredServices = [];
+    // Discoverable roles registered by a capability broker / standing offer — merged into the presence
+    // announce at connect time, so registering before connect() puts the role on the first connection.
+    brokerRoles = [];
+    constructor(deps) {
+        this.deps = deps;
+        this.id = deps.id;
+        this.connectCode = deps.connectCode;
+        this.name = deps.name ?? null;
+        this.projectId = deps.projectId ?? null;
+        if (deps.signal) {
+            if (deps.signal.aborted)
+                this.close();
+            else
+                deps.signal.addEventListener("abort", () => this.close(), { once: true });
+        }
+    }
+    /** The server-assigned connection id, or ``null`` before {@link connect} settles. */
+    get connectionId() {
+        return this.socket?.connectionId() ?? null;
+    }
+    /** The live participant roster (excludes self), from the ``ready`` snapshot + presence deltas —
+     * the raw {@link RosterEntry} view. For the parsed, query-friendly {@link Participant} (merged
+     * ``roles`` / ``name`` / ``connectedAt``) use {@link participants} / {@link has}. */
+    get presence() {
+        return this.socket?.participants() ?? [];
+    }
+    /** Open the live socket and start dispatch; resolves once the server's ``ready`` frame arrives.
+     * Idempotent — safe to call repeatedly, and every wire method calls it for you. */
+    connect() {
+        if (!this.connectPromise)
+            this.connectPromise = this.startSocket();
+        return this.connectPromise;
+    }
+    async startSocket() {
+        const mode = this.deps.transport ?? "auto";
+        if (mode === "sse") {
+            this.socket = this.makeSse();
+            this.usingSse = true;
+            return this.socket.connect();
+        }
+        // WS (preferred). In "auto" mode the socket is a *probe*: if it can't reach `ready` on the first
+        // attempt (a proxy stripping the upgrade looks exactly like this), it rejects fast instead of
+        // hanging the connect timeout, and we fall back to SSE — mirror of Python's SSE-primary path
+        // being reachable behind proxies where WS dies.
+        let wsUnavailable = false;
+        const ws = new RoomSocket({
+            roomId: this.id,
+            code: this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            identity: this.deps.identity,
+            announce: this.mergedAnnounce(),
+            reconnect: this.deps.reconnect,
+            probe: mode === "auto",
+            WebSocketCtor: this.deps.WebSocketCtor,
+            onSignal: (sig) => this.handleSignal(sig),
+            // Binary audio + the audio text signals ride the dedicated audio socket (below), never this
+            // one — so a frame isn't dispatched twice (both sockets are separate room subscribers).
+            onReady: () => this.onReady(),
+            onEnd: (reason) => this.handleEnd(reason),
+            onUnavailable: () => {
+                wsUnavailable = true;
+            },
+        });
+        this.socket = ws;
+        try {
+            await ws.connect();
+        }
+        catch (err) {
+            if (mode === "auto" && wsUnavailable) {
+                ws.close();
+                const sse = this.makeSse();
+                this.socket = sse;
+                this.usingSse = true;
+                return sse.connect();
+            }
+            throw err;
+        }
+    }
+    makeSse() {
+        return new RoomEventStream({
+            roomId: this.id,
+            code: this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            identity: this.deps.identity,
+            announce: this.mergedAnnounce(),
+            reconnect: this.deps.reconnect,
+            fetchImpl: this.deps.fetchImpl,
+            onSignal: (sig) => this.handleSignal(sig),
+            onReady: () => this.onReady(),
+            onEnd: (reason) => this.handleEnd(reason),
+        });
+    }
+    // A terminal transport end (code rotated / bad / room gone) — the socket has stopped reconnecting
+    // for good, so tear the handle down and fail any in-flight requests with the reason (rather than
+    // letting them hang until timeout). Fans the typed reason out to every `onEnd` listener exactly
+    // once (both transports funnel their connect-time and mid-session terminal ends here).
+    handleEnd(reason) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error(`room ${reason}`));
+        }
+        this.pending.clear();
+        const listeners = [...this.endListeners];
+        this.close();
+        for (const cb of listeners) {
+            try {
+                cb(reason);
+            }
+            catch (err) {
+                console.error("Atrium room: an onEnd listener failed:", err);
+            }
+        }
+    }
+    /** Register a handler for one signal type. The handler's return value auto-replies to a
+     * {@link request} (a signal carrying an ``ackId``) — so a responder just returns. */
+    on(type, handler) {
+        this.handlers.set(type, handler);
+        return this;
+    }
+    /** Register a catch-all observer invoked for **every** inbound signal (replies included) — the
+     * parity for a raw `receive()` loop (logging, inspection). Observers never auto-reply. Returns an
+     * unsubscribe function. */
+    onAny(handler) {
+        this.anyHandlers.add(handler);
+        return () => {
+            this.anyHandlers.delete(handler);
+        };
+    }
+    /** Register a callback for a **terminal** room end — the connection stopped for good with a typed
+     * {@link RoomEndReason} (``"code-rotated"`` / ``"bad-code"`` / ``"room-gone"``), on either the WS or
+     * SSE transport and whether the end is rejected at connect time or happens mid-session. Fires
+     * **exactly once** per handle; a deliberate {@link close} is not an end and never fires it. Returns
+     * an unsubscribe function. The typed reason is what a driver maps to its own UI state instead of
+     * string-matching a request's reject message. Register before {@link connect} to catch a connect-time
+     * reject. Python owes the port (``on_end``). */
+    onEnd(cb) {
+        this.endListeners.add(cb);
+        return () => {
+            this.endListeners.delete(cb);
+        };
+    }
+    /** Send a live message — fire-and-forget, never stored. ``to`` (a connection id/identity, or a
+     * list) targets peers; omit it to broadcast to everyone else. (``ephemeral`` is accepted for
+     * parity, but the WS inbound path forces ``ephemeral: false`` server-side.) */
+    async send(type, payload, opts = {}) {
+        await this.connect();
+        this.socket?.sendSignal({ type, payload, to: opts.to });
+    }
+    /** Send a request and await one reply (a peer's handler return). ``to`` targets one peer; omit it
+     * to broadcast — first matching reply wins. Rejects if no reply arrives within the timeout. */
+    request(type, payload, opts = {}) {
+        const ms = opts.timeout ?? this.deps.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        return this.connect().then(() => new Promise((resolve, reject) => {
+            const ackId = randomId();
+            const timer = setTimeout(() => {
+                this.pending.delete(ackId);
+                reject(new Error(`no response to '${type}' within ${ms}ms`));
+            }, ms);
+            this.pending.set(ackId, { resolve, reject, timer });
+            this.socket?.sendSignal({ type, payload, to: opts.to, ackId });
+        }));
+    }
+    handleSignal(sig) {
+        const event = toRoomEvent(sig);
+        // Catch-all observers (loggers/inspectors) see every inbound signal, replies included — the
+        // parity for Python's raw `receive()`. Observers never auto-reply; their return is ignored.
+        for (const cb of this.anyHandlers)
+            cb(event);
+        // A reply correlates to an in-flight request and stops here — matched or not. Mirror of
+        // aio.py's `_handle`: a `reply_to` is never dispatched to `on()` handlers.
+        if (event.replyTo != null) {
+            const p = this.pending.get(event.replyTo);
+            if (p) {
+                this.pending.delete(event.replyTo);
+                clearTimeout(p.timer);
+                p.resolve(event.payload);
+            }
+            return;
+        }
+        // Fan out to the layer-state subscribers (independent of a registered `on` handler).
+        if (event.type === "layer.state") {
+            for (const cb of this.layerWatchers)
+                cb(event.payload);
+        }
+        const handler = this.handlers.get(event.type);
+        if (!handler)
+            return;
+        Promise.resolve(handler(event))
+            .then((result) => {
+            if (event.ackId != null) {
+                // Mirror aio.py:1077 — a plain object is the reply payload as-is; anything else
+                // (a scalar, an array, null) is wrapped as `{ result }`.
+                const isPlainObject = result !== null && typeof result === "object" && !Array.isArray(result);
+                const reply = isPlainObject ? result : { result };
+                this.socket?.sendSignal({
+                    type: event.type,
+                    payload: reply,
+                    to: event.from ?? undefined,
+                    replyTo: event.ackId,
+                });
+            }
+        })
+            .catch((err) => {
+            console.error(`Atrium room handler for '${event.type}' failed:`, err);
+        });
+    }
+    handleAudioBinary(data) {
+        if (this.audioSubscribers.size === 0)
+            return;
+        const frame = decodeAudioFrame(data);
+        if (!frame)
+            return; // foreign/other binary — ignore
+        for (const cb of this.audioSubscribers)
+            cb({ kind: "frame", frame });
+    }
+    dispatchAudio(sig) {
+        if (this.audioSubscribers.size === 0)
+            return;
+        const event = toRoomEvent(sig);
+        let out = null;
+        if (event.type === AUDIO_SIGNAL.track)
+            out = { kind: "track", track: event.payload };
+        else if (event.type === AUDIO_SIGNAL.beat)
+            out = { kind: "beat", beat: event.payload };
+        else if (event.type === AUDIO_SIGNAL.announce)
+            out = { kind: "announce", announce: event.payload };
+        if (out)
+            for (const cb of this.audioSubscribers)
+                cb(out);
+    }
+    onReady() {
+        // Re-establish demand-gated subscriptions after every (re)connect (rooms have no replay).
+        if (this.layerWatchers.size > 0)
+            this.socket?.sendSignal({ type: "layer.subscribe" });
+    }
+    // ── Audio signals (consumption) ──────────────────────────────────────────
+    /**
+     * Subscribe to the room's audio-signal stream — the continuous binary loudness/spectrum frames
+     * plus the ``audio.track`` / ``audio.beat`` / ``audio.announce`` text signals a hosted Player (or
+     * any producer) broadcasts. The callback receives a discriminated {@link AudioSignal}; switch on
+     * ``.kind``. The first subscriber opens a dedicated socket that announces ``role: audio-consumer``
+     * (a producer's broadcast gate) and sends an ``audio.discover`` on every (re)connect; the last
+     * unsubscribe closes it, releasing demand. Returns an unsubscribe function.
+     */
+    audioSignals(callback) {
+        this.requireWsAudio("audioSignals");
+        this.audioSubscribers.add(callback);
+        if (!this.audioSocket)
+            this.openAudioSocket();
+        return () => {
+            this.audioSubscribers.delete(callback);
+            if (this.audioSubscribers.size === 0) {
+                this.audioSocket?.close();
+                this.audioSocket = null;
+            }
+        };
+    }
+    openAudioSocket() {
+        const socket = new RoomSocket({
+            roomId: this.id,
+            code: this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            identity: this.deps.identity,
+            // Announce audio-consumer demand so an elected producer starts broadcasting (analyzer gate).
+            announce: { ...this.deps.announce, role: AUDIO_ROLE.consumer },
+            reconnect: this.deps.reconnect,
+            WebSocketCtor: this.deps.WebSocketCtor,
+            onSignal: (sig) => this.dispatchAudio(sig),
+            onBinary: (data) => this.handleAudioBinary(data),
+            onReady: () => this.audioSocket?.sendSignal({ type: AUDIO_SIGNAL.discover, ackId: `disc-${Date.now()}` }),
+        });
+        this.audioSocket = socket;
+        void socket.connect().catch(() => { });
+    }
+    /** Refuse fast if this handle latched onto the SSE transport (the WS upgrade wasn't reachable) —
+     * binary audio is WS-only, so a doomed WS reconnect would otherwise spin forever. Consulted by every
+     * audio consumer AND, via {@link offerDeps}, every standing offer, so signals and audio stay coherent
+     * about the environment. Throws {@link AtriumError}. When the transport isn't yet decided (the main
+     * socket hasn't connected), it proceeds — the offers, which engage over an already-live signal
+     * channel, always see the settled decision. */
+    requireWsAudio(what) {
+        if (this.usingSse) {
+            throw new AtriumError(`${what} requires the WebSocket transport, but this room connection fell back to SSE ` +
+                "(the WebSocket upgrade wasn't reachable — e.g. a proxy stripping it). Binary audio is WS-only.");
+        }
+    }
+    /**
+     * Subscribe to the room's raw ``audio.snippet`` stream — the ~10s Opus windows a Player (v1) or a
+     * Capture tool (v2) shares — as an async iterator of {@link AudioClip}s. The rawest audio consumer:
+     * where a later ``audioVectors`` embeds and ``audioTranscripts`` transcribes, this hands you the
+     * bytes. Subscribing *is* the demand signal (it announces the ``audio-snippet-consumer`` role, so a
+     * producer's own default-off "Share audio clips" toggle actually captures). Break out of the
+     * ``for await`` loop (or ``return``) to end the subscription and close the socket.
+     *
+     * ``sourceName`` is resolved from the roster snapshot **at subscribe time**, so a producer that
+     * joins *after* this subscribes has ``null`` there until you re-subscribe (mirror of Python's
+     * ``audio_clips``). Binary rides the WebSocket only — a room latched to the SSE fallback throws.
+     */
+    async *audioClips() {
+        this.requireWsAudio("audioClips");
+        const queue = [];
+        let wake = null;
+        let ended = false;
+        const names = new Map();
+        let snapped = false;
+        const socket = new RoomSocket({
+            roomId: this.id,
+            code: this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            identity: `audio-clips:${randomId().slice(0, 8)}`,
+            announce: { ...this.deps.announce, role: AUDIO_SNIPPET_CONSUMER_ROLE },
+            reconnect: this.deps.reconnect,
+            WebSocketCtor: this.deps.WebSocketCtor,
+            onReady: () => {
+                // Freeze the source-name lookup at the first subscribe-time roster snapshot (the "joined
+                // after subscribe → null name" caveat) — a plain consumer socket has no live roster view.
+                if (snapped)
+                    return;
+                snapped = true;
+                for (const p of socket.participants()) {
+                    const name = p.announce?.name;
+                    names.set(p.connectionId, typeof name === "string" ? name : null);
+                }
+            },
+            onBinary: (data) => {
+                const frame = decodeAudioSnippetFrame(data);
+                if (!frame)
+                    return; // a foreign / DSP binary frame — not ours
+                if (queue.length >= RAW_CONSUMER_QUEUE_MAX)
+                    queue.shift(); // drop oldest — bound a slow consumer
+                queue.push({
+                    data: frame.data,
+                    mime: frame.mimeType,
+                    sequence: frame.sequence,
+                    windowSeconds: frame.windowSeconds,
+                    source: frame.source,
+                    sourceName: frame.source ? (names.get(frame.source) ?? null) : null,
+                });
+                wake?.();
+                wake = null;
+            },
+            onEnd: () => {
+                ended = true;
+                wake?.();
+                wake = null;
+            },
+        });
+        try {
+            try {
+                await socket.connect();
+            }
+            catch (err) {
+                // A close that raced the connect (the socket ended before ``ready``) rejects "room closed" —
+                // an expected teardown; only a genuine connect failure propagates.
+                if (!ended)
+                    throw err;
+            }
+            while (!ended) {
+                while (queue.length > 0) {
+                    yield queue.shift();
+                }
+                if (ended)
+                    break;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+            while (queue.length > 0) {
+                yield queue.shift();
+            }
+        }
+        finally {
+            socket.close();
+        }
+    }
+    // ── Durable capture (record → session) ───────────────────────────────────
+    /**
+     * Start capturing this room's live signals into a durable ``session`` — the single durable binding
+     * between a room (pure transport) and a session (an append-only log). A **side effect**: it starts
+     * immediately in the background and returns a live {@link Recorder} handle. Stop it with
+     * ``rec.stop()``, or let {@link close} (an ``await using`` room) stop it. It skips ``ephemeral``
+     * signals and presence traffic — only durable-worthy signals are recorded, each stamped with
+     * ``via`` provenance (``{ room_id, room_name, from, to }``). Mirror of Python's ``room.record``.
+     *
+     * A dropped stream reconnects with backoff (the gap is lost — rooms have no replay); only a
+     * terminal end stops it cleanly with a {@link Recorder.stoppedReason} (a code rotation, or the
+     * room being gone / its code rejected — the latter also sets {@link Recorder.error}). Needs an
+     * owned room (durable sessions require an account) — throws on a loginless {@link joinRoom} handle.
+     */
+    record(into) {
+        const rest = this.deps.rest;
+        if (!rest) {
+            throw new AtriumError("this room handle has no account credential — join(code) can only send/receive; " +
+                "record(into) needs an owned room from client.rooms");
+        }
+        const recorder = new Recorder({
+            roomId: this.id,
+            code: this.connectCode,
+            roomName: this.name,
+            baseUrl: this.deps.baseUrl,
+            rest,
+            reconnect: this.deps.reconnect,
+            fetchImpl: this.deps.fetchImpl,
+            onChange: () => {
+                void this.notifyRecordersChanged();
+            },
+        }, into);
+        this.recorders.push(recorder);
+        recorder.start();
+        return recorder;
+    }
+    /** The recorders currently running on this handle (membership **and** liveness — a stopped one no
+     * longer counts) — the source of truth a wave-4 ``offerAudioCapture`` reads for audio-capture
+     * availability, and binds its capture to the first active recorder's session. */
+    activeRecorders() {
+        return this.recorders.filter((r) => r.alive);
+    }
+    /** Register a listener fired whenever the active-recorder set changes (a {@link record} started, or
+     * a recorder stopped/terminated) — the seam a wave-4 ``offerAudioCapture`` binds to, so it can
+     * re-derive availability and disengage when the recorder it wrote under is gone. Returns an
+     * unsubscribe function. Mirror of Python's ``_notify_recorders_changed`` registration. */
+    onRecordersChanged(listener) {
+        this.recorderListeners.add(listener);
+        return () => {
+            this.recorderListeners.delete(listener);
+        };
+    }
+    async notifyRecordersChanged() {
+        // Isolate each hook — one misbehaving listener must not starve the others nor throw out of a
+        // recorder's teardown path (this fires from a recorder's terminal wind-down).
+        for (const listener of [...this.recorderListeners]) {
+            try {
+                await listener();
+            }
+            catch (err) {
+                console.error("Atrium room: a recorders-changed listener failed:", err);
+            }
+        }
+    }
+    // ── Live transcription (the transcript.* broker) ─────────────────────────
+    /**
+     * Transcribe this room's live audio into ``transcript.*`` signals — the in-room broker. Consumes the
+     * room's ``audio.snippet`` stream (announcing the snippet-consumer role, so a Player starts
+     * capturing), pushes it through the same engine as {@link ../atrium.Atrium.transcribeLive} on
+     * **your** credentials/compute, and publishes back:
+     *
+     * * ``transcript.partial`` — ``{ text }``, **ephemeral** (a live caption the recorder skips).
+     *   Wholesale-replaced — render the latest, don't append.
+     * * ``transcript.final`` — ``{ text, start, end, seq }``, durable (the {@link record} bridge persists
+     *   it — no new recording API). ``seq`` is a per-handle counter from 0; the signal's ``source`` is
+     *   ``"transcriber"``.
+     *
+     * Any consumer — including a loginless code-joined tool — just does ``room.on("transcript.final")``.
+     * Like {@link record}, it's a **side effect**: it starts immediately in the background and is stopped
+     * when the room closes, or via ``await handle.stop()`` / ``await using``. Needs an owned room
+     * (transcription runs on an account credential) — throws on a loginless {@link joinRoom} handle.
+     */
+    transcribe(opts = {}) {
+        const client = this.requireClient("transcribe()");
+        const transcriber = new Transcriber({
+            model: opts.model,
+            language: opts.language,
+            snippetBytes: (signal) => this.snippetBytesFor(signal),
+            engine: (clips, o) => client.transcribeStream(clips, {
+                model: o.model,
+                language: o.language,
+                // The producer ships Opus-in-WebM; the backend decodes each clip. Partials are published
+                // as ephemeral live captions, so the engine must surface them.
+                format: "webm",
+                partials: true,
+                skipEmpty: true,
+                signal: o.signal,
+                webSocketCtor: this.deps.WebSocketCtor,
+            }),
+            publish: (type, payload, o) => client.request(buildRoomSignal(this.id, {
+                type,
+                payload,
+                source: TRANSCRIBER_SOURCE,
+                ephemeral: o.ephemeral,
+            })),
+        });
+        this.transcribers.push(transcriber);
+        transcriber.start();
+        return transcriber;
+    }
+    // The raw snippet bytes for the transcription broker — a dedicated consumer socket, ended when the
+    // handle's stop() aborts the signal (which closes the socket).
+    async *snippetBytesFor(signal) {
+        for await (const frame of this.snippetStream(`transcriber:${randomId().slice(0, 8)}`, signal)) {
+            yield frame.data;
+        }
+    }
+    // ── Standing-service offers + capability brokers ─────────────────────────
+    /** Merge the registered broker/offer roles into the presence announce (mirror of Python's
+     * ``_events_params``) — so registering a broker before ``connect()`` rides the first connection. */
+    mergedAnnounce() {
+        if (this.brokerRoles.length === 0)
+            return this.deps.announce;
+        const merged = { ...this.deps.announce };
+        const roles = Array.isArray(merged.roles) ? [...merged.roles] : [];
+        for (const role of this.brokerRoles)
+            if (!roles.includes(role))
+                roles.push(role);
+        merged.roles = roles;
+        return merged;
+    }
+    announceRole(role) {
+        if (!this.brokerRoles.includes(role))
+            this.brokerRoles.push(role);
+    }
+    requirePreConnect() {
+        if (this.connectionId !== null) {
+            throw new AtriumError("register offer_*/offerEmbeds/offerChat before connect() — the broker role is only " +
+                "advertised when the connection opens");
+        }
+    }
+    /** The single capability-injection guard — the authed client slice (embed / chat / compare /
+     * transcribe) an owned room carries and a loginless ``join(code)`` handle lacks. Always throws
+     * {@link AtriumError} (never a bare ``Error``), so every SDK refusal is catchable under the one
+     * hierarchy. ``feature`` names the surface for the message. */
+    requireClient(feature) {
+        if (!this.deps.client) {
+            throw new AtriumError(`${feature} needs an owned room from client.rooms (open/get/join) — this handle has no ` +
+                "account credential (a loginless joinRoom can only send/receive)");
+        }
+        return this.deps.client;
+    }
+    offerDeps(client) {
+        return {
+            roomId: this.id,
+            getCode: () => this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            reconnect: this.deps.reconnect,
+            WebSocketCtor: this.deps.WebSocketCtor,
+            // The offer consults the room's latched transport decision — refuse fast on an SSE handle.
+            requireWsAudio: () => this.requireWsAudio("this standing offer"),
+            // The ``*.available`` broadcast (and per-source ``transcript.*``) ride the REST /signal POST so
+            // an ephemeral hint survives — the WS inbound path forces ``ephemeral: false``.
+            publishSignal: (type, payload, o) => client.request(buildRoomSignal(this.id, { type, payload, source: o.source, ephemeral: o.ephemeral })),
+        };
+    }
+    // Wire a peer-toggleable standing service (the third broker kind) — announce ``role`` and route the
+    // ``<name>.start`` / ``.stop`` / ``.status`` requests to ``service`` (mirror of ``_offer_service``).
+    // Engage is sender-scoped (the server-stamped ``from``) unless the payload carries ``all: true``.
+    offerService(name, role, service) {
+        this.requirePreConnect();
+        this.announceRole(role);
+        this.offeredServices.push(service);
+        this.on(`${name}.start`, async (e) => {
+            try {
+                await service.start({ source: e.from, all: Boolean(e.payload.all) });
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            return { ok: true };
+        });
+        this.on(`${name}.stop`, async (e) => {
+            try {
+                await service.stopRequest({ source: e.from, all: Boolean(e.payload.all) });
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            return { ok: true };
+        });
+        this.on(`${name}.status`, () => ({ ok: true, ...service.status() }));
+    }
+    /**
+     * Offer live transcription as a peer-toggleable standing service — a code-joined tool turns it on
+     * with a ``transcription.start`` request and off with ``transcription.stop`` (both idempotent).
+     * Announces the discoverable ``transcription-offer`` role. **Scoped, multi-source**: ``start`` /
+     * ``stop`` are scoped to the requesting connection unless the payload carries ``{ all: true }``;
+     * only armed sources are transcribed (up to ``maxSources``, default 8). While on it runs the same
+     * engine as {@link transcribe} on **your** credentials, publishing source-attributed ``transcript.*``
+     * signals. Register **before** ``connect()``; needs an owned room (throws on a loginless handle).
+     * Returns the handle (for ``handle.start({ all: true })`` from the host). Mirror of Python's
+     * ``offer_transcription``.
+     */
+    offerTranscription(opts = {}) {
+        const client = this.requireClient("offerTranscription");
+        const service = new OfferedTranscription({
+            ...this.offerDeps(client),
+            engine: (clips, o) => client.transcribeStream(clips, {
+                model: o.model,
+                language: o.language,
+                format: "webm", // the producer ships Opus-in-WebM; the backend decodes each clip
+                partials: true,
+                skipEmpty: true,
+                signal: o.signal,
+                webSocketCtor: this.deps.WebSocketCtor,
+            }),
+        }, { model: opts.model, language: opts.language, maxSources: opts.maxSources });
+        this.offerService("transcription", TRANSCRIPTION_OFFER_ROLE, service);
+        return service;
+    }
+    /**
+     * Offer audio capture as a peer-toggleable standing service — **session-less**: it writes into the
+     * **active recorder's** session ({@link record} is the single durable binding), so a ``capture.start``
+     * with no active recorder replies an error. A code-joined tool toggles it via ``capture.start`` /
+     * ``capture.stop`` (idempotent). Announces the discoverable ``capture-offer`` role. **Scoped,
+     * multi-source** (up to ``maxSources``, default 8): only armed sources are recorded; a same-name
+     * reconnect within grace resumes one file, two simultaneous same-name producers get their own files.
+     * Register **before** ``connect()``; needs an owned room (throws on a loginless handle). Returns the
+     * handle (for ``handle.start({ all: true })``). Mirror of Python's ``offer_audio_capture``.
+     */
+    offerAudioCapture(opts = {}) {
+        const client = this.requireClient("offerAudioCapture");
+        const service = new OfferedCapture({
+            ...this.offerDeps(client),
+            request: (req) => client.request(req),
+            activeRecorders: () => this.activeRecorders(),
+            onRecordersChanged: (listener) => this.onRecordersChanged(listener),
+        }, { maxSources: opts.maxSources });
+        this.offerService("capture", CAPTURE_OFFER_ROLE, service);
+        return service;
+    }
+    async resolveEmbedSpace(client, requested) {
+        const spaces = await client.library.spaces();
+        if (requested !== undefined) {
+            const matched = spaces.find((s) => s.id === requested);
+            return { space: requested, model: matched?.model ?? null };
+        }
+        const matched = spaces.find((s) => s.defaultModalities.includes("text"));
+        if (!matched) {
+            throw new AtriumError("no default text search space is configured on this deployment — the embed.resolve request " +
+                "must pass space");
+        }
+        return { space: matched.id, model: matched.model ?? null };
+    }
+    async resolveAnchorVector(client, desc, space, model, cache) {
+        const anchor = parseAnchorDescriptor(desc); // throws BrokerError on a malformed anchor
+        if (anchor.kind === "vector")
+            return [...anchor.vector];
+        if (anchor.kind === "asset") {
+            const key = `${space}|asset:${anchor.asset}:${anchor.matchBy ?? ""}`;
+            let vec = cache.get(key);
+            if (!vec) {
+                const query = { space };
+                if (anchor.matchBy !== null)
+                    query.match_by = anchor.matchBy;
+                const rows = (await client.request({
+                    method: "GET",
+                    path: `/v1/assets/${anchor.asset}/vectors`,
+                    query,
+                }));
+                const first = Array.isArray(rows) ? rows[0] : undefined;
+                if (!first || !Array.isArray(first.vector)) {
+                    throw new BrokerError(`asset '${anchor.asset}' has no stored vector in space '${space}'`);
+                }
+                vec = first.vector.map(Number);
+                cache.set(key, vec);
+            }
+            return vec;
+        }
+        if (anchor.kind === "text") {
+            const key = `${space}|text:${anchor.text}`;
+            let vec = cache.get(key);
+            if (!vec) {
+                if (model === null) {
+                    throw new BrokerError(`space '${space}' has no model configured — cannot embed text`);
+                }
+                vec = await client.embed({ text: anchor.text, model });
+                cache.set(key, vec);
+            }
+            return vec;
+        }
+        const key = `${space}|concept:${anchor.concept}:${anchor.collection ?? ""}`;
+        let vec = cache.get(key);
+        if (!vec) {
+            const query = { concept: anchor.concept, space };
+            if (anchor.collection !== null)
+                query.collection = anchor.collection;
+            const data = (await client.request({
+                method: "GET",
+                path: "/v1/library/concept-vector",
+                query,
+            }));
+            vec = data.vector.map(Number);
+            cache.set(key, vec);
+        }
+        return vec;
+    }
+    /**
+     * Handle ``embed.resolve`` requests from code-joined peers (e.g. a loginless Unity scene) — resolve
+     * named operand descriptors (``{ text }`` / ``{ concept, collection? }`` / ``{ vector }`` /
+     * ``{ asset, match_by? }``) to vectors in ONE embedding space, so a peer with no credentials can
+     * compare live signals against library concepts/text/assets. **The requester chooses the space**
+     * (omitted → the default text space). A per-anchor
+     * failure lands in ``errors`` without failing the others; a malformed / over-``maxAnchors`` request
+     * or a ``space`` outside ``spaces`` gets a whole-request ``{ error }``. Announces the discoverable
+     * ``embed-broker`` role — call before ``connect()``. Mirror of Python's ``offer_embeds``.
+     */
+    offerEmbeds(opts = {}) {
+        const client = this.requireClient("offerEmbeds");
+        this.requirePreConnect();
+        const allowed = opts.spaces ? new Set(opts.spaces) : null;
+        const maxAnchors = opts.maxAnchors ?? DEFAULT_MAX_ANCHORS;
+        const cache = new Map();
+        this.announceRole(EMBED_BROKER_ROLE);
+        this.on("embed.resolve", async (e) => {
+            const anchors = e.payload.anchors;
+            if (typeof anchors !== "object" ||
+                anchors === null ||
+                Array.isArray(anchors) ||
+                Object.keys(anchors).length === 0) {
+                return { error: "anchors must be a non-empty object" };
+            }
+            const entries = Object.entries(anchors);
+            if (entries.length > maxAnchors) {
+                return { error: `too many anchors (${entries.length} > ${maxAnchors})` };
+            }
+            const requested = typeof e.payload.space === "string" ? e.payload.space : undefined;
+            if (requested !== undefined && allowed !== null && !allowed.has(requested)) {
+                return { error: `space '${requested}' is not served by this broker` };
+            }
+            let space;
+            let model;
+            try {
+                ;
+                ({ space, model } = await this.resolveEmbedSpace(client, requested));
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            if (allowed !== null && !allowed.has(space)) {
+                return { error: `space '${space}' is not served by this broker` };
+            }
+            const vectors = {};
+            const errors = {};
+            for (const [nm, desc] of entries) {
+                try {
+                    vectors[nm] = await this.resolveAnchorVector(client, desc, space, model, cache);
+                }
+                catch (err) {
+                    errors[nm] = asError(err).message;
+                }
+            }
+            const reply = { space, vectors };
+            if (Object.keys(errors).length > 0)
+                reply.errors = errors;
+            return reply;
+        });
+    }
+    /**
+     * Handle ``chat.generate`` requests from code-joined peers — a stateless chat completion (no history
+     * broker-side), so a loginless peer gets an LLM reply without its own credentials. Reply:
+     * ``{ text, model }``, or ``{ error }`` if ``messages`` is malformed / over the payload cap. The
+     * **broker** pins ``model`` (the requester cannot choose it — cost control); ``maxTokens`` caps each
+     * reply. Announces the discoverable ``chat-broker`` role — call before ``connect()``. Every peer
+     * holding the connect code can trigger a reply on **your** billing. Mirror of Python's ``offer_chat``.
+     */
+    offerChat(opts = {}) {
+        const client = this.requireClient("offerChat");
+        this.requirePreConnect();
+        const maxTokens = opts.maxTokens ?? DEFAULT_CHAT_MAX_TOKENS;
+        this.announceRole(CHAT_BROKER_ROLE);
+        this.on("chat.generate", async (e) => {
+            let messages;
+            try {
+                messages = validateChatMessages(e.payload.messages);
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+            try {
+                const reply = await client.chat(messages, { model: opts.model, max_tokens: maxTokens });
+                return { text: reply.content, model: reply.model };
+            }
+            catch (err) {
+                return { error: asError(err).message };
+            }
+        });
+    }
+    // ── Audio embedding (vectors + reactive scores) ──────────────────────────
+    // Resolve the (space, model) pair for the audio surfaces (mirror of Python's `_resolve_audio_space`):
+    // an explicit space+model skips the lookup; otherwise the member-facing spaces list resolves the
+    // deployment's default audio space and/or reads the space's configured model.
+    async resolveAudioSpace(space, model) {
+        if (space !== undefined && model !== undefined)
+            return { space, model };
+        const spaces = await this.requireClient("audioVectors / audioScores").library.spaces();
+        let matched;
+        if (space === undefined) {
+            matched = spaces.find((s) => s.defaultModalities.includes("audio"));
+            if (!matched) {
+                throw new Error("no default audio search space is configured on this deployment — pass space to audioVectors()");
+            }
+            space = matched.id;
+        }
+        else {
+            matched = spaces.find((s) => s.id === space);
+            if (!matched)
+                throw new Error(`space '${space}' not found`);
+        }
+        return { space, model: model ?? matched?.model ?? null };
+    }
+    // A dedicated snippet-consumer socket (announcing the demand role so a producer captures), decoding
+    // its binary frames — the shared source behind audioVectors/audioScores (mirror of audioClips).
+    async *snippetStream(identity, signal) {
+        this.requireWsAudio("live audio streaming");
+        const queue = [];
+        let wake = null;
+        let ended = false;
+        const socket = new RoomSocket({
+            roomId: this.id,
+            code: this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            identity,
+            announce: { ...this.deps.announce, role: AUDIO_SNIPPET_CONSUMER_ROLE },
+            reconnect: this.deps.reconnect,
+            WebSocketCtor: this.deps.WebSocketCtor,
+            onBinary: (data) => {
+                const frame = decodeAudioSnippetFrame(data);
+                if (!frame)
+                    return; // a foreign / DSP binary frame — not ours
+                if (queue.length >= RAW_CONSUMER_QUEUE_MAX)
+                    queue.shift(); // drop oldest — bound a slow consumer
+                queue.push(frame);
+                wake?.();
+                wake = null;
+            },
+            onEnd: () => {
+                ended = true;
+                wake?.();
+                wake = null;
+            },
+        });
+        // An abort (a `transcribe()` handle's stop) closes the socket → ends this generator at once.
+        const onAbort = () => {
+            ended = true;
+            socket.close();
+            wake?.();
+            wake = null;
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort);
+        }
+        try {
+            try {
+                await socket.connect();
+            }
+            catch (err) {
+                // A pre-/mid-connect abort closed the socket → connect() rejects "room closed"; that's an
+                // expected teardown, not a failure. Only a genuine connect error (bad code) propagates.
+                if (!ended)
+                    throw err;
+            }
+            while (!ended) {
+                while (queue.length > 0)
+                    yield queue.shift();
+                if (ended)
+                    break;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+            while (queue.length > 0)
+                yield queue.shift();
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+            socket.close();
+        }
+    }
+    /**
+     * Subscribe to the room's live ``audio.snippet`` stream and embed each ~10s window, yielding an
+     * {@link AudioVector} per snippet — a live vector of "what the room sounds like right now".
+     * Subscribing *is* the demand signal (announces the ``audio-snippet-consumer`` role, so a
+     * producer's default-off "Share audio clips" toggle actually captures). Break out of the
+     * ``for await`` loop to end it. Mirror of Python's ``audio_vectors``.
+     *
+     * ``space`` pins the search space snippets are labeled with (default: the deployment's default
+     * audio space, so a no-arg vector is comparable against library-derived vectors); ``model`` the
+     * embedding model (default: the resolved space's configured model). ``relay: true`` also relays
+     * each vector into the room as an ephemeral ``audio.vector`` signal — so a loginless code-joined
+     * peer can consume the live mood vector without credentials of its own. Needs an authenticated
+     * client to embed with (throws on a loginless handle); binary rides the WebSocket only.
+     */
+    async *audioVectors(opts = {}) {
+        const client = this.requireClient("audioVectors / audioScores");
+        const { space, model } = await this.resolveAudioSpace(opts.space, opts.model);
+        if (model === null) {
+            throw new Error(`the audio search space '${space}' has no model configured — pass model to audioVectors()`);
+        }
+        for await (const frame of this.snippetStream(`audio-vectors:${randomId().slice(0, 8)}`)) {
+            const fmt = frame.mimeType.split(";")[0]?.split("/").pop();
+            const vector = await client.embed({
+                audio: new Blob([frame.data], { type: frame.mimeType }),
+                model,
+                format: fmt,
+            });
+            const vec = {
+                vector,
+                space,
+                sequence: frame.sequence,
+                windowSeconds: frame.windowSeconds,
+                timestamp: Date.now() / 1000,
+            };
+            if (opts.relay) {
+                await this.send("audio.vector", {
+                    vector: vec.vector,
+                    space: vec.space,
+                    sequence: vec.sequence,
+                    window_seconds: vec.windowSeconds,
+                    timestamp: vec.timestamp,
+                }, { ephemeral: true });
+            }
+            yield vec;
+        }
+    }
+    async preflightConceptAnchors(members, space) {
+        // Resolve every concept anchor's vector once before waiting on any frame — a typo'd/unresolvable
+        // concept fails immediately, naming the anchor, rather than surfacing mid-stream.
+        const client = this.requireClient("audioVectors / audioScores");
+        for (const [name, ops] of Object.entries(members)) {
+            for (const op of ops) {
+                if (op.kind !== "concept")
+                    continue;
+                const query = { concept: op.name, space };
+                if (op.collection !== undefined)
+                    query.collection = op.collection;
+                try {
+                    await client.request({ method: "GET", path: "/v1/library/concept-vector", query });
+                }
+                catch (err) {
+                    throw new Error(`anchor '${name}': ${err.message}`);
+                }
+            }
+        }
+    }
+    /**
+     * Fuse {@link audioVectors} with per-anchor ``library.compare`` scoring — a live "which anchor does
+     * the room sound like right now" signal. ``anchors`` maps a name to anything the ``by`` grammar
+     * accepts (a bare string / {@link "../by".Asset} / ``by.*`` marker), **or an array** of those (a
+     * few-shot category, scored as the mean of its top-``topN`` members' calibrated compare scores;
+     * default ``topN: 1`` — the nearest member wins). Each frame's anchors are scored concurrently.
+     *
+     * Each {@link ScoredAudio} carries the calibrated ``scores`` plus ``mix`` (normalized to sum 1,
+     * uniform when every score is 0 — gate on ``max(scores)`` for silence). No smoothing — ease the
+     * stream with a {@link ../decider.Decider}. ``relay: true`` forwards to {@link audioVectors} (it
+     * relays the raw ``audio.vector``, not the computed scores). Concept anchors are validated once up
+     * front (a typo raises before any frame); a mid-stream compare failure re-throws named by anchor.
+     * Mirror of Python's ``audio_scores``.
+     */
+    async *audioScores(anchors, opts = {}) {
+        const client = this.requireClient("audioVectors / audioScores");
+        const names = Object.keys(anchors);
+        const members = {};
+        for (const name of names)
+            members[name] = toAnchorMembers(anchors[name]);
+        const { space, model } = await this.resolveAudioSpace(opts.space, opts.model);
+        if (model === null) {
+            throw new Error(`the audio search space '${space}' has no model configured — pass model to audioScores()`);
+        }
+        await this.preflightConceptAnchors(members, space);
+        const topN = Math.max(1, opts.topN ?? 1);
+        for await (const vec of this.audioVectors({ space, model, relay: opts.relay })) {
+            const vectorOp = by.vector(vec.vector);
+            // Score every member of every anchor concurrently — a handful of compares is cheap vs. the ~10s
+            // window. Flatten to (name, op) pairs, then fold back into per-anchor top-N means below.
+            const flat = names.flatMap((name) => members[name].map((op) => ({ name, op })));
+            const results = await Promise.all(flat.map(async ({ name, op }) => {
+                try {
+                    const r = await client.library.compare(vectorOp, op, { space: vec.space });
+                    return r.score;
+                }
+                catch (err) {
+                    throw new Error(`anchor '${name}': ${err.message}`);
+                }
+            }));
+            const scores = {};
+            let i = 0;
+            for (const name of names) {
+                const n = members[name].length;
+                const top = results
+                    .slice(i, i + n)
+                    .sort((a, b) => b - a)
+                    .slice(0, topN);
+                scores[name] = top.reduce((a, b) => a + b, 0) / top.length;
+                i += n;
+            }
+            const total = Object.values(scores).reduce((a, b) => a + b, 0);
+            const mix = {};
+            for (const name of names) {
+                mix[name] = total > 0 ? scores[name] / total : 1 / names.length;
+            }
+            yield {
+                scores,
+                mix,
+                vector: vec.vector,
+                space: vec.space,
+                sequence: vec.sequence,
+                windowSeconds: vec.windowSeconds,
+                timestamp: vec.timestamp,
+            };
+        }
+    }
+    /**
+     * The room's current presence roster as typed {@link Participant}s (merged ``roles`` / ``name`` /
+     * ``connectedAt`` as a ``Date``). Opens one short **observe** SSE stream, reads the roster off its
+     * first ``ready`` frame, and closes — a per-web-worker, best-effort snapshot (mirror of Python's
+     * ``participants()``). Rejects if the stream is refused (a 4xx — room deleted, or a bad code).
+     */
+    async participants() {
+        const roster = await readObserveRoster({
+            roomId: this.id,
+            code: this.connectCode,
+            baseUrl: this.deps.baseUrl,
+            fetchImpl: this.deps.fetchImpl,
+        });
+        return roster.map(parseParticipant);
+    }
+    /**
+     * Is any current participant matching the given predicate connected? Sugar over
+     * {@link participants} (same best-effort per-worker caveat). Give at least one of ``role`` /
+     * ``name`` / ``identityPrefix`` — several are ANDed; ``role`` matches the merged roles, ``name``
+     * the announced name exactly, ``identityPrefix`` the identity's leading segment (a hosted Player
+     * announces ``player:web``, so ``{ identityPrefix: "player:" }`` is the launch-once guard). Throws
+     * if no predicate is given (mirror of Python's ``has()``).
+     */
+    async has(pred) {
+        if (pred.role === undefined && pred.name === undefined && pred.identityPrefix === undefined) {
+            throw new Error("has() needs at least one of role, name, or identityPrefix");
+        }
+        const roster = await this.participants();
+        return roster.some((p) => participantMatches(p, pred));
+    }
+    // ── Player controls (the `layer.*` / `play` dialect) ─────────────────────
+    /** Play a sound (or several) on a layer — the one playback verb. Per-sound options (``effects``,
+     * ``spatial`` — including its optional ``distance`` attenuation — ``delay_seconds``, ``loop`` …)
+     * ride a hand-rolled track dict and pass through untouched. */
+    async play(source, opts = {}) {
+        await this.connect();
+        this.socket?.sendSignal({ type: "play", payload: buildPlayBody({ source, ...opts }) });
+    }
+    /** Declare (or replace) the Player's layer set — idempotent. */
+    async configureLayers(layers) {
+        await this.connect();
+        this.socket?.sendSignal({ type: "layer.configure", payload: { layers } });
+    }
+    /** Fade out and empty a layer — its queue and one-shots (omit ``layer`` → ``"default"``). */
+    async clearLayer(opts = {}) {
+        await this.connect();
+        this.socket?.sendSignal({
+            type: "layer.clear",
+            payload: buildLayerClearBody(opts.layer, opts.fadeOutMs),
+        });
+    }
+    /** Fade out and empty **every** layer at once — "stop all audio" (the ``"*"`` wildcard). */
+    async clearAll(opts = {}) {
+        await this.clearLayer({ layer: "*", fadeOutMs: opts.fadeOutMs });
+    }
+    /** Set (or ramp) a layer's effects, e.g. ``{ lowpass: { hz: 700 } }`` for a backroom muffle.
+     * ``lowpass`` / ``highpass`` / ``reverb`` / ``echo`` are all live (an absent implemented key ramps
+     * back to neutral); ``layer`` may be ``"*"`` to apply to every existing layer. */
+    async setLayerEffects(layer, effects, opts = {}) {
+        await this.connect();
+        this.socket?.sendSignal({
+            type: "layer.effects",
+            payload: buildLayerEffectsBody(layer, effects, opts.fadeMs),
+        });
+    }
+    /** Set (or ramp) a layer's HRTF position — placed whole-layer in 3D over ``fadeMs`` (default 50ms
+     * to avoid zipper noise, applied Player-side). ``z`` defaults to 0. ``distance`` opts into distance
+     * attenuation (``{ model, ref, max, rolloff }``); absent → direction-only. No ``"*"`` wildcard. */
+    async setLayerPosition(layer, x, y, z = 0, opts = {}) {
+        await this.connect();
+        this.socket?.sendSignal({
+            type: "layer.position",
+            payload: buildLayerPositionBody({
+                layer,
+                x,
+                y,
+                z,
+                fadeMs: opts.fadeMs,
+                distance: opts.distance,
+            }),
+        });
+    }
+    /** Pull the Player's current layer state (a broadcast request; first Player to reply wins). */
+    async queryLayers(opts = {}) {
+        return this.request("layer.query", {}, { timeout: opts.timeout });
+    }
+    /**
+     * Subscribe to the Player's live layer state, invoking ``callback`` with each ``{ layers }``
+     * snapshot the Player pushes (every meaningful change + a ~1s heartbeat while playing). Demand-
+     * gated: the Player only broadcasts while a subscriber is present. Returns an unsubscribe function
+     * that sends ``layer.unsubscribe``.
+     */
+    watchLayers(callback) {
+        const first = this.layerWatchers.size === 0;
+        this.layerWatchers.add(callback);
+        void this.connect().then(() => {
+            if (first || this.connectionId)
+                this.socket?.sendSignal({ type: "layer.subscribe" });
+        });
+        return () => {
+            this.layerWatchers.delete(callback);
+            if (this.layerWatchers.size === 0)
+                this.socket?.sendSignal({ type: "layer.unsubscribe" });
+        };
+    }
+    /** The hosted Player's launch URL for this room (``<base>/tools/player?code=<code>``). Pure. */
+    playerUrl(opts = {}) {
+        const params = new URLSearchParams({ code: this.connectCode });
+        if (opts.analysis !== undefined)
+            params.set("analysis", opts.analysis ? "on" : "off");
+        if (opts.clips !== undefined)
+            params.set("clips", opts.clips ? "on" : "off");
+        return `${this.toolBase()}/tools/player?${params.toString()}`;
+    }
+    // ── Viewer controls (the `show` / `show.clear` dialect) ──────────────────
+    /**
+     * Show an image on the Viewer — the one display verb. Give exactly one of ``assetId`` (a stored
+     * asset) or ``url`` (any reachable image); passing both, or neither, throws. ``caption`` labels
+     * the frame; ``projection`` (``"flat"`` for a plain image, ``"360"`` for an equirectangular
+     * panorama) forces how the Viewer renders it — omit it and the Viewer's own default applies. See
+     * ``docs/reference/viewer-dialect.md``.
+     */
+    async show(opts = {}) {
+        await this.connect();
+        this.socket?.sendSignal({ type: "show", payload: buildShowBody(opts) });
+    }
+    /** Clear the Viewer — blank the frame (the ``show.clear`` verb, empty body). */
+    async clearView() {
+        await this.connect();
+        this.socket?.sendSignal({ type: "show.clear", payload: {} });
+    }
+    /** The hosted Viewer's launch URL for this room (``<base>/tools/viewer?code=<code>``). Pure. The
+     * Viewer defaults to auto-turn on; ``autoTurn`` bakes its persistent preference into the URL as
+     * ``autoturn=1``/``0`` (omitted → the Viewer's stored/default preference applies). */
+    viewerUrl(opts = {}) {
+        const params = new URLSearchParams({ code: this.connectCode });
+        if (opts.autoTurn !== undefined)
+            params.set("autoturn", opts.autoTurn ? "1" : "0");
+        return `${this.toolBase()}/tools/viewer?${params.toString()}`;
+    }
+    /** The observation dashboard's launch URL (``<base>/tools/dashboard?code=<code>``). Pure — the
+     * dashboard takes only the connect code (mirror of Python's ``dashboard_url``). */
+    dashboardUrl() {
+        return `${this.toolBase()}/tools/dashboard?${new URLSearchParams({ code: this.connectCode })}`;
+    }
+    /** Open the observation dashboard for this room in a browser tab. Always opens — it does not check
+     * presence. Throws outside a browser (there is no tab to open). */
+    openDashboard() {
+        openTab(this.dashboardUrl());
+    }
+    /** The Capture tool's launch URL for this room (``<base>/tools/capture?code=<code>``). Pure.
+     * ``name`` prefills the participant name field; ``captions`` / ``save`` pre-engage the "Live
+     * captions" / "Save recording" toggles (emitted only when truthy — else the tool's own default
+     * applies). Mirror of Python's ``capture_url``. */
+    captureUrl(opts = {}) {
+        const params = new URLSearchParams({ code: this.connectCode });
+        if (opts.name !== undefined)
+            params.set("name", opts.name);
+        if (opts.captions)
+            params.set("captions", "on");
+        if (opts.save)
+            params.set("save", "on");
+        return `${this.toolBase()}/tools/capture?${params.toString()}`;
+    }
+    /** Open the Capture tool for this room in a browser tab (see {@link captureUrl}). Always opens —
+     * it does not check presence. Throws outside a browser (there is no tab to open). */
+    openCapture(opts = {}) {
+        openTab(this.captureUrl(opts));
+    }
+    toolBase() {
+        return this.deps.baseUrl.replace(/\/+$/, "");
+    }
+    // ── Management (authenticated handles only) ──────────────────────────────
+    rest(req) {
+        if (!this.deps.rest) {
+            throw new AtriumError("this room handle has no account credential — join(code) can only send/receive");
+        }
+        return this.deps.rest(req);
+    }
+    /** Rotate the connect code (owner only); updates ``connectCode`` and returns it. */
+    async rotateCode() {
+        const data = (await this.rest(buildRoomRotateCode(this.id)));
+        this.connectCode = data.connect_code ?? this.connectCode;
+        return this.connectCode;
+    }
+    /** Delete the room for good (its connect code dies with it). */
+    async delete() {
+        await this.rest({ method: "DELETE", path: `/v1/rooms/${this.id}` });
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    /** Disconnect the socket, stop dispatch, and fail any in-flight requests — the fire-and-forget
+     * teardown. Idempotent. The synchronous state (sockets closed, requests failed, listeners cleared)
+     * settles at once; the standing offers' async wind-down (**including finalizing their open
+     * recordings**) and the transcribers' stop run in the background. To *await* that finalize — so a
+     * process exit can't drop it — use {@link closeAndFinalize} / ``await using room``. */
+    close() {
+        void this.teardown();
+    }
+    /** Await the full teardown end-to-end — every recorder/transcriber stopped and every standing offer
+     * wound down **with its open recordings finalized** — mirroring Python's awaited ``async with room``
+     * exit. Idempotent; ``await using room`` calls this. Prefer it over {@link close} when the offers'
+     * finalize POSTs must land before the process moves on. */
+    async closeAndFinalize() {
+        await this.teardown();
+    }
+    teardown() {
+        const stops = [];
+        for (const rec of this.recorders.splice(0))
+            rec.stop();
+        for (const t of this.transcribers.splice(0))
+            stops.push(t.stop().catch(() => { }));
+        for (const s of this.offeredServices.splice(0)) {
+            stops.push(Promise.resolve(s.stop()).catch(() => { }));
+            s.detach?.(); // capture unsubscribes from the recorder seam
+        }
+        this.socket?.close();
+        this.socket = null;
+        this.audioSocket?.close();
+        this.audioSocket = null;
+        this.connectPromise = null;
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error("room closed"));
+        }
+        this.pending.clear();
+        this.audioSubscribers.clear();
+        this.layerWatchers.clear();
+        return stops.length > 0 ? Promise.allSettled(stops).then(() => { }) : Promise.resolve();
+    }
+}
+if (typeof Symbol.dispose === "symbol") {
+    Room.prototype[Symbol.dispose] = function () {
+        this.close();
+    };
+}
+if (typeof Symbol.asyncDispose === "symbol") {
+    Room.prototype[Symbol.asyncDispose] = async function () {
+        await this.closeAndFinalize();
+    };
+}
+//# sourceMappingURL=room.js.map