hci-atrium 0.3.1 → 0.4.0

package/dist/rooms/room.js

@@ -1,8 +1,9 @@
 /**
- * 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.
+ * The live room handle — pure transport over the room WebSocket, and the **participant** half of the
+ * room surface. Returned by the loginless {@link ./index.joinRoom} and by ``client.rooms.join(code)``;
+ * the host-side half lives on {@link ./owned-room.OwnedRoom}, which extends this. 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``
@@ -10,40 +11,26 @@
  * 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
+ * Correlation (mirror of ``_RoomDispatcher``): dispatch starts with {@link Room.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}).
+ * the response when the signal was a {@link Room.request} (carried an ``ackId``) — so a responder
+ * writes no correlation plumbing, it just returns. Pending requests resolve by ``replyTo``.
  */
-import { by, toAnchorMembers } from "../by.js";
-import { Dashboard } from "../dash.js";
-import { APIError, AtriumError } from "../errors.js";
-import { asError, isBrowser } from "../http.js";
-import { buildLayerClearBody, buildLayerEffectsBody, buildLayerPositionBody, buildPlayBody, buildRoomRotateCode, buildRoomSignal, buildShowBody, } from "../shaping/rooms.js";
-import { RoomTrace, summarizePlay, traced, traceEnvelope, traceStateType, } from "../trace.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 { AtriumError } from "../errors.js";
+import { isBrowser } from "../http.js";
+import { buildLayerClearBody, buildLayerConfigureBody, buildLayerEffectsBody, buildLayerPositionBody, buildPlayBody, buildShowBody, } from "../shaping/rooms.js";
+import { summarizePlay, traced } from "../trace.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;
+// A raw audio-consumer socket ({@link Room.audioClips} / {@link OwnedRoom.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.
+export const RAW_CONSUMER_QUEUE_MAX = 32;
 function toRoomEvent(sig) {
     return {
         type: sig.type ?? "",
@@ -67,7 +54,7 @@ export function randomId() {
     return Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
 /** Drop one entry from a mutable registry array (a no-op when absent / the list is undefined). */
-function remove(list, item) {
+export function remove(list, item) {
     const at = list?.indexOf(item) ?? -1;
     if (at >= 0)
         list?.splice(at, 1);
@@ -80,6 +67,16 @@ function openTab(url) {
     }
     window.open(url, "_blank", "noopener");
 }
+/**
+ * The **participant** room surface — everything a handle can do with nothing but a connect code:
+ * connect/close, send/on/onAny/request/onEnd, the presence roster, the Player + Viewer dialects,
+ * and the audio-consumption streams. This is what the loginless {@link ./index.joinRoom} returns.
+ *
+ * The host-side surfaces that genuinely need an account credential — ``record`` / ``transcribe`` /
+ * ``audioVectors`` / ``dashboard`` / ``trace`` / the standing offers / ``rotateCode`` / ``delete`` —
+ * live on {@link ./owned-room.OwnedRoom}, which ``client.rooms.open/get/list`` returns: a method you
+ * cannot call is a method you cannot see.
+ */
 export class Room {
     id;
     connectCode;
@@ -108,10 +105,9 @@ export class Room {
     // 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).
+    // Durable-capture recorders started by OwnedRoom's `record(into)` — the base holds them because
+    // `teardown` stops whatever is registered.
     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 = [];
@@ -181,7 +177,7 @@ export class Room {
             announce: this.mergedAnnounce(),
             reconnect: this.deps.reconnect,
             probe: mode === "auto",
-            WebSocketCtor: this.deps.WebSocketCtor,
+            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).
@@ -272,12 +268,22 @@ export class Room {
             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.) */
+    /**
+     * 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. ``replyTo`` answers a peer's
+     * {@link request} out-of-band — the correlation an ``on`` handler gets for free by *returning* a
+     * value.
+     *
+     * Both fields are all this carries: the room transport forces ``ephemeral: false`` on everything
+     * it accepts inbound, so a signal sent here is **durable** (a {@link OwnedRoom.record} bridge
+     * stores it), and a reply correlation needs a registered pending entry, which only
+     * {@link request} creates. An ephemeral or awaited-reply signal is {@link request} or, host-side,
+     * the REST ``/signal`` POST ({@link ../shaping/rooms.buildRoomSignal}) — what
+     * {@link OwnedRoom.dashboard} / {@link OwnedRoom.trace} publish through.
+     */
     async send(type, payload, opts = {}) {
         await this.connect();
-        this.socket?.sendSignal({ type, payload, to: opts.to });
+        this.socket?.sendSignal({ type, payload, to: opts.to, replyTo: opts.replyTo });
     }
     /** 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. */
@@ -397,7 +403,7 @@ export class Room {
             // 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,
+            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()}` }),
@@ -443,7 +449,7 @@ export class Room {
             identity: `audio-clips:${randomId().slice(0, 8)}`,
             announce: { ...this.deps.announce, role: AUDIO_SNIPPET_CONSUMER_ROLE },
             reconnect: this.deps.reconnect,
-            WebSocketCtor: this.deps.WebSocketCtor,
+            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.
@@ -506,229 +512,7 @@ export class Room {
             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");
-        }
-        // The `trace.state.recorder` line rides the same change seam, on TRANSITIONS only (the seam also
-        // fires on a no-op stop) — mirror of Python's start/stop emissions in the recorder's own task.
-        let tracedAlive = false;
-        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();
-                if (recorder.alive === tracedAlive)
-                    return;
-                tracedAlive = recorder.alive;
-                void this.traceState("recorder", tracedAlive
-                    ? `recording ${into.id}: started`
-                    : `recording ${into.id}: stopped (${recorder.events} events)`);
-            },
-        }, 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,
-            })),
-            onEnd: (err) => void this.traceState("transcriber", err ? `transcribing: failed — ${err.message}` : "transcribing: stopped"),
-        });
-        this.transcribers.push(transcriber);
-        transcriber.start();
-        void this.traceState("transcriber", `transcribing (${opts.model ?? "default"}): started`);
-        return transcriber;
-    }
-    /**
-     * Subscribe to the room's live ``audio.snippet`` stream and transcribe it, yielding a
-     * {@link ../models.Transcript} per finalized sentence — the speech-to-text sibling of
-     * {@link audioVectors}, and the *raw* counterpart of the {@link transcribe} broker (which publishes
-     * ``transcript.*`` signals for every peer instead of handing you the stream).
-     *
-     * 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 abort ``signal`` — to end the subscription and close the socket.
-     *
-     * Snippets run through the same engine as {@link ../atrium.Atrium.transcribeLive}: true streaming
-     * (per-sentence finals, plus revisable partials with ``partials``) when the backend's live route is
-     * reachable, degrading silently to per-clip batch transcription otherwise (finals only).
-     * Transcription runs on *your* credentials/compute — a rejected credential raises rather than
-     * falling back, and a loginless {@link joinRoom} handle throws.
-     *
-     * The two paths differ in one detail (mirror of Python's ``audio_transcripts``): on the **fallback**
-     * path each transcript carries its source frame's ``sequence`` / ``window_seconds`` under
-     * ``transcript.raw.snippet`` (a cheap ordering/correlation handle) and the clip's format comes from
-     * that frame's own MIME type; on the **streaming** path transcripts are per-sentence, so there is no
-     * 1:1 snippet correlation and ``raw.snippet`` is omitted (``raw`` carries ``start`` / ``end``).
-     */
-    async *audioTranscripts(opts = {}) {
-        const client = this.requireClient("audioTranscripts");
-        const skipEmpty = opts.skipEmpty ?? true;
-        // Own abort, chained to the caller's: a consumer that just `break`s out of the loop must tear the
-        // whole chain down, and JS can't cancel the engine's pending feeder `await` the way Python cancels
-        // its task — aborting closes the snippet socket, which is what unblocks it (same teardown seam as
-        // the `transcribe()` handle's stop()).
-        const ctrl = new AbortController();
-        const chain = () => ctrl.abort();
-        if (opts.signal) {
-            if (opts.signal.aborted)
-                ctrl.abort();
-            else
-                opts.signal.addEventListener("abort", chain, { once: true });
-        }
-        // One shared snippet source: the streaming path draws its bytes, the fallback its frames + their
-        // per-frame metadata. Only one of the two ever iterates it (the engine picks a path).
-        const frames = this.snippetStream(`audio-transcripts:${randomId().slice(0, 8)}`, ctrl.signal);
-        async function* snippetBytes() {
-            for await (const frame of frames)
-                yield frame.data;
-        }
-        async function* snippetFallback() {
-            for await (const frame of frames) {
-                const format = frame.mimeType.split(";")[0]?.split("/").pop();
-                let said;
-                try {
-                    said = await client.transcribe(new Blob([frame.data], { type: frame.mimeType }), {
-                        model: opts.model,
-                        language: opts.language,
-                        format,
-                    });
-                }
-                catch (err) {
-                    if (err instanceof APIError && (err.status === 401 || err.status === 403))
-                        throw err;
-                    continue; // a frame the server couldn't transcribe — skip, keep the stream alive
-                }
-                if (!said.text && skipEmpty)
-                    continue;
-                said.raw.snippet = { sequence: frame.sequence, window_seconds: frame.windowSeconds };
-                yield said;
-            }
-        }
-        const stream = client.transcribeStream(snippetBytes(), {
-            model: opts.model,
-            language: opts.language,
-            format: "webm", // the producer ships Opus-in-WebM; the backend decodes each clip
-            partials: opts.partials ?? false,
-            skipEmpty,
-            signal: ctrl.signal,
-            webSocketCtor: this.deps.WebSocketCtor,
-            fallback: snippetFallback,
-        });
-        const engine = stream[Symbol.asyncIterator]();
-        // Pulled by hand (not `yield*`) so teardown runs in the order that actually unwinds: abort the
-        // socket FIRST, then wind the engine down — `yield*` would forward the consumer's `return()`
-        // into the engine while its feeder is still parked on a snippet that will never arrive.
-        try {
-            for (;;) {
-                const next = await engine.next();
-                if (next.done)
-                    break;
-                yield next.value;
-            }
-        }
-        finally {
-            opts.signal?.removeEventListener("abort", chain);
-            ctrl.abort();
-            await engine.return?.().catch(() => { });
-        }
-    }
-    // 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 ─────────────────────────
+    // ── Presence announce (the broker/offer role seam) ───────────────────────
     /** 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() {
@@ -742,577 +526,12 @@ export class Room {
         merged.roles = roles;
         return merged;
     }
+    /** Register a discoverable role for the presence announce — what an {@link OwnedRoom}'s brokers
+     * and standing offers advertise. */
     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 })),
-            // The armed/active transition an offer broadcasts also surfaces to any room tracer (deduped
-            // with the broadcast itself) — Python's `_trace_state` call in `_StandingSource._broadcast`.
-            traceState: (label, summary, detail) => this.traceState(label, summary, detail),
-        };
-    }
-    // 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 };
-            }
-        });
-    }
-    // ── Observation dashboard + tracing (host-side helpers) ──────────────────
-    /**
-     * Build the host-side {@link ../dash.Dashboard} for this room — the live observation-dashboard
-     * state an app holds as a grid of tiles. It answers each joining ``/tools/dashboard`` with a full
-     * ``dash.snapshot`` and broadcasts ``dash.delta`` patches as things change, all **ephemeral** (the
-     * room stores nothing — the durable record is the session).
-     *
-     * Prefer this over ``new Dashboard(room)``: it publishes over the REST ``/signal`` POST, which
-     * preserves the dialect's ephemerality (the WS inbound path forces ``ephemeral: false``). Needs an
-     * owned room — throws on a loginless {@link joinRoom} handle. Mirror of Python's ``Dashboard(room)``.
-     */
-    dashboard(opts = {}) {
-        const client = this.requireClient("dashboard()");
-        return new Dashboard(this, {
-            ...opts,
-            publish: (type, payload, o) => client.request(buildRoomSignal(this.id, {
-                type,
-                payload,
-                to: o.to,
-                ephemeral: o.ephemeral,
-                connectionId: this.connectionId,
-            })),
-        });
-    }
-    /**
-     * Mirror the SDK's own activity into this room as ``trace.*`` signals — one line turns it on. The
-     * operation folds into the signal type (``label`` still rides the payload), and ephemerality is
-     * per-signal (see {@link ../trace.isTraceEphemeral}). While tracing:
-     *
-     * * **library/model calls** made through the same client (``search`` / ``searchByExamples`` /
-     *   ``enrich`` / ``play`` / ``chat``) surface a ``trace.<label>`` (``trace.library.search`` /
-     *   ``trace.chat`` / ``trace.play``) — a glanceable summary (``"rain" → 8 hits (top: Forest Rain
-     *   0.83)``) plus a capped detail (top-N results, never full payloads);
-     * * **SDK-internal state** — a recorder start/stop (with its session + event count), a transcriber
-     *   start/stop, a standing offer's armed/active roster — surfaces a ``trace.state.<label>``.
-     *
-     * Default OFF (it broadcasts app internals to anyone with the code, and it's noise on the happy
-     * path). Returns a handle: ``const t = room.trace()`` then ``t.stop()``, or ``using t =
-     * room.trace()`` for a scope; stopped when the room closes. A trace failure never breaks the traced
-     * call. ``play`` and the state seam are scoped to **this** room; client-wide calls mirror into every
-     * armed room. Needs an owned room (the client's calls are what it mirrors) — throws on a loginless
-     * handle. Mirror of Python's ``room.trace()``.
-     */
-    trace() {
-        const client = this.requireClient("trace()");
-        const handle = new RoomTrace({
-            // Trace signals ride the REST /signal POST, like the transcriber's: the WS inbound path forces
-            // `ephemeral: false`, and trace ephemerality is per-signal (a durable `trace.library.search` IS
-            // the study's record; an ephemeral `trace.play` must not double-record the play).
-            publish: (type, payload, o) => client.request(buildRoomSignal(this.id, {
-                type,
-                payload,
-                ephemeral: o.ephemeral,
-                connectionId: this.connectionId,
-            })),
-            onStop: () => {
-                remove(client.traceSinks, handle);
-                remove(this.traceHandles, handle);
-            },
-        });
-        client.traceSinks?.push(handle);
-        this.traceHandles.push(handle);
-        return handle;
-    }
-    // Emit a `trace.state.<label>` into every tracing session on this room (no-op when none — the
-    // zero-cost-when-off contract). Mirror of Python's `_trace_state`.
-    async traceState(label, summary, detail) {
-        if (this.traceHandles.length === 0)
-            return;
-        const payload = traceEnvelope(label, summary, detail);
-        for (const handle of [...this.traceHandles])
-            await handle.emit(traceStateType(label), payload);
-    }
-    // ── 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
@@ -1344,10 +563,11 @@ export class Room {
         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; put an {@link ../models.Asset} /
-     * {@link ../models.SearchHit} under that track's ``asset`` key to keep its loudness facts —
+    /** Play a sound (or several) on a layer — the one playback verb. ``source`` is an
+     * {@link ../models.Asset} / {@link ../models.SearchHit} / an id-or-URL string, a typed
+     * {@link ../shaping/rooms.PlayTrack} for the per-sound options (``effects``, ``spatial`` — including
+     * its optional ``distance`` attenuation — ``delaySeconds``, ``loop`` …), or a list of any of those.
+     * Put the asset under the track's ``asset`` key to keep its loudness facts —
      * ``{ asset: hit, gain: 2 }``. ``opts.gain`` is the same emphasis multiplier for every track that
      * doesn't carry its own: a trim **on top of** loudness normalization (``2`` ≈ +6 dB over the
      * normalized baseline), per-sound — the layers keep their own volume. */
@@ -1359,10 +579,13 @@ export class Room {
             this.socket?.sendSignal({ type: "play", payload: buildPlayBody({ source, ...opts }) });
         });
     }
-    /** Declare (or replace) the Player's layer set — idempotent. */
+    /** Declare (or replace) the Player's layer set — idempotent. Each layer is a typed
+     * {@link ../shaping/rooms.LayerDeclaration} (``{ id, label?, volume?, crossfadeMs?, effects? }``)
+     * or the dialect's own snake_case spelling; the shaping layer translates. The read-back
+     * ({@link queryLayers} / {@link watchLayers}) is still the raw wire snapshot — snake_case. */
     async configureLayers(layers) {
         await this.connect();
-        this.socket?.sendSignal({ type: "layer.configure", payload: { layers } });
+        this.socket?.sendSignal({ type: "layer.configure", payload: buildLayerConfigureBody(layers) });
     }
     /** Fade out and empty a layer — its queue and one-shots (omit ``layer`` → ``"default"``). */
     async clearLayer(opts = {}) {
@@ -1493,23 +716,6 @@ export class Room {
     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)