@tribe-nest/media-client 0.2.1 → 0.4.0

package/build/room/room.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MediaRoom = void 0;
+exports.spatialLayerForWidth = spatialLayerForWidth;
 exports.connectToRoom = connectToRoom;
 const core_1 = require("../core");
 /**
@@ -10,12 +11,40 @@ const core_1 = require("../core");
  * whatever resolution the caller is publishing. The rids are the conventional
  * one-letter names every SFU and every browser log uses, which is worth more
  * than a more descriptive name nobody would recognise in a WebRTC dump.
+ *
+ * `L1T3` (three temporal layers per encoding), not `L1T1`, and the difference
+ * decides whether anyone ever LEAVES the quarter layer. The server's
+ * congestion controller only steps a consumer up when the estimate has room
+ * for the next step, and with T1 the only step that exists is a whole
+ * spatial layer's full bitrate - a cliff the estimate must clear in one
+ * probe. Temporal layers cut each spatial step into thirds, which is the
+ * conventional simulcast shape for exactly this reason. Confirmed in the
+ * field by the health panel: a big tile asking `f` and being held at `h`
+ * for a whole call.
  */
 const SIMULCAST_LAYERS = [
-    { rid: "q", scaleResolutionDownBy: 4, scalabilityMode: "L1T1" },
-    { rid: "h", scaleResolutionDownBy: 2, scalabilityMode: "L1T1" },
-    { rid: "f", scaleResolutionDownBy: 1, scalabilityMode: "L1T1" },
+    { rid: "q", scaleResolutionDownBy: 4, scalabilityMode: "L1T3" },
+    { rid: "h", scaleResolutionDownBy: 2, scalabilityMode: "L1T3" },
+    { rid: "f", scaleResolutionDownBy: 1, scalabilityMode: "L1T3" },
 ];
+/**
+ * Which simulcast layer a tile of `widthPx` deserves: 0 = q, 1 = h, 2 = f.
+ *
+ * The policy lives HERE, not on the node, because the tile width is a fact
+ * only the renderer has; the node obeys. Buckets, not a formula, so a resize
+ * only crosses a boundary occasionally and a boundary crossing is the only
+ * thing that costs a request. Screen shares always get the full layer:
+ * downscaled text is unreadable, and shares are rarely simulcast anyway.
+ */
+function spatialLayerForWidth(widthPx, source) {
+    if (source === "screen")
+        return 2;
+    if (widthPx <= 240)
+        return 0;
+    if (widthPx <= 480)
+        return 1;
+    return 2;
+}
 /**
  * What each layer may spend, given the caller's cap for the top one.
  *
@@ -50,14 +79,45 @@ class MediaRoom {
     /** Per publication: stop listening for the track ending on its own. */
     trackEndWatchers = new Map();
     listeners = new Set();
+    broadcastListeners = new Set();
     /** One in-flight subscribe per producer, so a burst of activeSpeakers frames
      * does not race itself into two consumers for one producer. */
     subscribing = new Map();
+    /**
+     * What the UI says it is rendering. `null` (never set, or cleared) is the
+     * legacy behavior: subscribe the whole active set, which is what every
+     * headless consumer (egress, harness, agents) keeps. `[]` is a hidden tab:
+     * zero video, audio untouched.
+     */
+    viewport = null;
+    viewportTimer;
+    pendingViewport;
+    /** Video consumers paused because their tile is off-viewport, each holding
+     * its close timer. Single owner of the pause/close decision. */
+    pausedByViewport = new Map();
+    /** The last spatial layer requested per producer, so a resize storm only
+     * speaks up when a bucket boundary is crossed. */
+    sentLayer = new Map();
+    /** Old-node degradation: each new verb is disabled on its first
+     * `bad_request`, never retried into the frame budget. */
+    unsupported = new Set();
     stateValue = core_1.initialRoomState;
     connection = "idle";
     lastError;
     /** Consecutive failed attempts since the last successful join. */
     reconnectAttempt = 0;
+    /** When the current OUTAGE began, for the reconnect time budget. Null while
+     * connected. The budget, not the attempt count, is what decides when a
+     * room with a person in front of it stops trying. */
+    outageStartedAt = null;
+    /**
+     * The planned-move machine. `scheduled` is the jittered wait after a
+     * `draining` frame, during which the call continues untouched; `moving`
+     * holds the STASH: the live capture tracks that survive the reconnect and
+     * are republished on the far side, which is what makes a drain smooth
+     * instead of a mute-everything drop.
+     */
+    migration = null;
     reconnectTimer;
     recovering = false;
     /** `close()` has been called. Nothing may open a socket after that. */
@@ -78,6 +138,68 @@ class MediaRoom {
      * it ended after an hour or before a socket was ever opened.
      */
     onDisconnect(cause) {
+        /**
+         * A PLANNED move's own close arrives here first. The signal stamps every
+         * client-initiated close `closed_by_client`, which without this flag
+         * would route a deliberate server move to the "call over" state; the
+         * flag was set before the close, which is what makes it trustworthy.
+         */
+        if (this.migration?.phase === "moving" && this.migration.plannedClose && !this.disposed) {
+            // Stashed HERE, at the instant the connection ends: everything the
+            // person did during the leave round trip (mute, unmute, a new share)
+            // is in the publications map now and nowhere else.
+            this.migration = { phase: "moving", stash: this.buildStash(), plannedClose: false };
+            this.lastError = { type: "draining", reconnectAfterMs: 0 };
+            this.teardownMedia({ preserveCaptures: true });
+            this.clearActiveSetState();
+            this.connection = "reconnecting";
+            this.recovering = true;
+            this.emit();
+            // The first attempt of a planned move is NOT a failure: no ladder, no
+            // attempt count, straight back through MEDIA_URL with a fresh ticket.
+            // Booked on a zero timer rather than called here: this handler runs
+            // inside the signal's own close loop, and a connect() started inside
+            // it registers its close watcher into the very Set being iterated, so
+            // the OLD socket's close would count as the NEW attempt's report. The
+            // timer also makes `close()` cancellation uniform.
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = undefined;
+                if (this.disposed)
+                    return;
+                void this.connect().catch(() => undefined);
+            }, 0);
+            return;
+        }
+        /**
+         * The server cut us at the drain deadline (or won the race with our own
+         * scheduled move). Same smooth path: stash the captures BEFORE teardown
+         * and honor the server's jittered hint before the first attempt, so a
+         * whole node's population does not land on the replacement in one burst.
+         */
+        if (cause.type === "draining" && !this.disposed && this.migration?.phase !== "moving") {
+            if (this.migration?.phase === "scheduled")
+                clearTimeout(this.migration.timer);
+            const stash = this.buildStash();
+            this.migration = { phase: "moving", stash, plannedClose: false };
+            this.lastError = cause;
+            this.teardownMedia({ preserveCaptures: true });
+            this.clearActiveSetState();
+            this.connection = "reconnecting";
+            this.recovering = true;
+            this.emit();
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = undefined;
+                if (this.disposed)
+                    return;
+                void this.connect().catch(() => undefined);
+            }, Math.max(0, cause.reconnectAfterMs));
+            return;
+        }
+        // An ORDINARY drop cancels a scheduled move: the crash path owns it now.
+        if (this.migration?.phase === "scheduled") {
+            clearTimeout(this.migration.timer);
+            this.migration = null;
+        }
         this.lastError = cause;
         // What the person was sending, before it is torn down. Recorded so the
         // screen can say so once the room is back (see `lostPublicationSources`).
@@ -90,17 +212,15 @@ class MediaRoom {
         ];
         // Before the decision, and unconditionally. The transports are dead
         // whatever happens next, and so is every capture that was feeding them.
-        this.teardownMedia();
-        // The active set was an instruction about consumers on THIS connection,
-        // and those are gone. Left standing, it would be mistaken by the next
-        // `joined` for a set the new node had sent ahead of the snapshot.
-        if (this.stateValue.activeSpeakers.length > 0) {
-            this.stateValue = { ...this.stateValue, activeSpeakers: [] };
-        }
+        // A failed MOVE attempt keeps preserving: the stash is the captures, and
+        // it is stopped only when the recovery gives up for good.
+        this.teardownMedia({ preserveCaptures: this.migration?.phase === "moving" });
+        this.clearActiveSetState();
         // `disposed` as well as the cause: `close()` is a client close whatever the
         // socket's own account of it, and a room that has been closed must never
         // report itself as coming back.
         if (cause.type === "closed_by_client" || this.disposed) {
+            this.stopStash();
             this.connection = "closed";
             this.recovering = false;
             this.emit();
@@ -110,8 +230,72 @@ class MediaRoom {
             this.lostSources = wasPublishing;
         this.connection = "reconnecting";
         this.recovering = this.scheduleReconnect(cause);
+        if (!this.recovering) {
+            // Read BEFORE stopStash, which clears the migration as it stops it.
+            const wasMoving = this.migration?.phase === "moving";
+            this.stopStash();
+            // A MOVE that dies for good is reported as the move failing, not as
+            // whatever refusal happened to end it: the person was in a working
+            // call that a deploy interrupted, and "Could not move you" with a
+            // retry is the honest account of that. The refusal itself still went
+            // to the log via scheduleReconnect's decision line.
+            if (wasMoving)
+                this.lastError = { type: "draining", reconnectAfterMs: 0 };
+        }
         this.emit();
     }
+    /**
+     * The active set was an instruction about consumers on the connection that
+     * just ended. Left standing, it would be mistaken by the next `joined` for
+     * a set the new node had sent ahead of the snapshot. The split, the levels
+     * and the enforcement flag go with it.
+     */
+    clearActiveSetState() {
+        if (this.stateValue.activeSpeakers.length > 0 ||
+            this.stateValue.activeAudio.length > 0 ||
+            this.stateValue.activeVideo.length > 0 ||
+            this.stateValue.speakers.length > 0) {
+            this.stateValue = {
+                ...this.stateValue,
+                activeSpeakers: [],
+                activeAudio: [],
+                activeVideo: [],
+                speakers: [],
+                activeSetEnforced: false,
+            };
+        }
+    }
+    /** The captures a move was carrying, for the republish on the far side.
+     * Program feeds are excluded exactly as they are from `lostSources`. */
+    buildStash() {
+        return [...this.publications.values()]
+            .filter((p) => p.source !== "program")
+            .map((p) => ({ track: p.track, kind: p.kind, source: p.source, paused: p.paused, options: p.options }));
+    }
+    /**
+     * A move that is over, one way or the other. On failure the stashed
+     * captures are STOPPED and surfaced as lost sources: the camera light must
+     * never outlive both its session and its migration, and from here the UX
+     * is exactly the ordinary-drop one, a person and a button.
+     */
+    stopStash() {
+        const migration = this.migration;
+        if (migration?.phase === "scheduled") {
+            clearTimeout(migration.timer);
+            this.migration = null;
+            return;
+        }
+        if (migration?.phase !== "moving")
+            return;
+        const sources = new Set();
+        for (const item of migration.stash) {
+            item.track.stop();
+            sources.add(item.source);
+        }
+        if (sources.size > 0)
+            this.lostSources = [...sources];
+        this.migration = null;
+    }
     get state() {
         return this.stateValue;
     }
@@ -175,6 +359,90 @@ class MediaRoom {
     get lostPublicationSources() {
         return this.lostSources;
     }
+    /**
+     * Why does the call look the way it looks, answered without
+     * webrtc-internals: per tile, the layer this client ASKED for, the layer
+     * the node is GIVING, and the picture the browser is decoding; plus the
+     * node's congestion estimate and this side's own publish health. Built for
+     * polling (a diagnostics HUD calls it once a second); bitrate is computed
+     * from the byte delta between calls. Degrades gracefully everywhere: an
+     * old node contributes nothing, a fake device without stats contributes
+     * nothing, and the local half always answers.
+     */
+    async getDiagnostics() {
+        const node = ((await this.requestOptional({ method: "diagnostics" })) ?? undefined);
+        // Defensive throughout: the verb is optional, and an old or odd node can
+        // answer with any shape (an empty object included). A diagnostics call
+        // must never be the thing that throws in a call.
+        const nodeByProducer = new Map((node?.consumers ?? []).map((c) => [c.producerId, c]));
+        const tiles = [];
+        for (const [producerId, consumer] of this.consumers) {
+            const entry = this.stateValue.producers.find((p) => p.producerId === producerId);
+            const width = this.viewportWidth(producerId);
+            const fromNode = nodeByProducer.get(producerId);
+            const inbound = await this.inboundStats(producerId, consumer);
+            tiles.push({
+                producerId,
+                identity: entry?.identity ?? "",
+                kind: consumer.kind,
+                ...(entry?.source ? { source: entry.source } : {}),
+                ...(this.sentLayer.has(producerId) ? { requestedLayer: this.sentLayer.get(producerId) } : {}),
+                ...(fromNode?.currentLayers ? { currentLayer: fromNode.currentLayers.spatialLayer } : {}),
+                ...(width !== undefined ? { viewportWidthPx: width } : {}),
+                pausedByViewport: this.pausedByViewport.has(producerId),
+                ...inbound,
+            });
+        }
+        const estimate = (node?.transports ?? []).find((t) => typeof t.availableOutgoingBitrate === "number");
+        return {
+            tiles,
+            ...(estimate ? { availableOutgoingBitrate: estimate.availableOutgoingBitrate } : {}),
+            ...(node?.producers?.length ? { localProducers: node.producers } : {}),
+            ...(node ? { node } : {}),
+        };
+    }
+    /** Byte counters from the previous `getDiagnostics`, for the bitrate delta. */
+    statsBaseline = new Map();
+    async inboundStats(producerId, consumer) {
+        if (!consumer.getStats)
+            return {};
+        let report;
+        try {
+            report = await consumer.getStats();
+        }
+        catch {
+            return {};
+        }
+        // An RTCStatsReport is a map; anything iterable of stats objects works.
+        const entries = [];
+        const iterable = report;
+        if (typeof iterable?.values === "function") {
+            for (const value of iterable.values())
+                entries.push(value);
+        }
+        else if (Array.isArray(report)) {
+            for (const value of report)
+                entries.push(value);
+        }
+        const inbound = entries.find((e) => e["type"] === "inbound-rtp");
+        if (!inbound)
+            return {};
+        const out = {
+            ...(typeof inbound["frameWidth"] === "number" ? { frameWidth: inbound["frameWidth"] } : {}),
+            ...(typeof inbound["frameHeight"] === "number" ? { frameHeight: inbound["frameHeight"] } : {}),
+            ...(typeof inbound["framesPerSecond"] === "number" ? { framesPerSecond: inbound["framesPerSecond"] } : {}),
+        };
+        const bytes = inbound["bytesReceived"];
+        if (typeof bytes === "number") {
+            const now = Date.now();
+            const baseline = this.statsBaseline.get(producerId);
+            this.statsBaseline.set(producerId, { bytes, at: now });
+            if (baseline && now > baseline.at && bytes >= baseline.bytes) {
+                out.bitrateKbps = Math.round(((bytes - baseline.bytes) * 8) / (now - baseline.at));
+            }
+        }
+        return out;
+    }
     /** Subscribe to changes. Returns an unsubscribe. */
     onChange(listener) {
         this.listeners.add(listener);
@@ -191,8 +459,10 @@ class MediaRoom {
         this.cancelReconnect();
         // A retry is not a first connection, and saying "Connecting to the call"
         // over a call somebody is already in reads as though they had been thrown
-        // out of it.
-        this.connection = this.reconnectAttempt > 0 ? "reconnecting" : "connecting";
+        // out of it. A planned MOVE is the same case with `reconnectAttempt`
+        // still 0: the person is mid-call, so the word is "reconnecting".
+        this.connection =
+            this.reconnectAttempt > 0 || this.migration?.phase === "moving" ? "reconnecting" : "connecting";
         this.emit();
         // A failed attempt normally reports itself through `signal.onClose`, which
         // routes to `onDisconnect`. This watches for that report so a rejection
@@ -228,14 +498,57 @@ class MediaRoom {
         // A successful join resets the ladder: an hour-long call that drops once
         // should not start at a 30-second delay because of a blip at minute two.
         this.reconnectAttempt = 0;
+        this.outageStartedAt = null;
         this.recovering = false;
         this.emit();
         if (this.options.autoSubscribe !== false)
             await this.syncSubscriptions();
+        // The far side of a planned move: the same capture tracks, republished
+        // with the same sources and options, nobody pressing anything. This is
+        // what "smooth" means; a drain used to be a mute-everything drop.
+        if (this.migration?.phase === "moving") {
+            const stash = this.migration.stash;
+            this.migration = null;
+            await this.restoreStash(stash);
+        }
+    }
+    async restoreStash(stash) {
+        const lost = new Set();
+        for (const item of stash) {
+            if (item.track.readyState !== "live") {
+                // The capture ended during the move (a camera unplugged, a share the
+                // browser's own bar stopped). Honest answer: the ordinary lost-source
+                // offer, a person and a button.
+                lost.add(item.source);
+                continue;
+            }
+            try {
+                const publication = await this.publish(item.track, item.source, item.options);
+                // Republished PAUSED state follows within one round trip. The wire
+                // has no start-paused on produce, so a muted mic is briefly live at
+                // the producer level; the capture was live locally the whole time.
+                if (item.paused)
+                    await this.setPaused(publication.producerId, true);
+            }
+            catch {
+                item.track.stop();
+                lost.add(item.source);
+            }
+        }
+        if (lost.size > 0) {
+            this.lostSources = [...new Set([...this.lostSources, ...lost])];
+            this.emit();
+        }
     }
     async close() {
         this.disposed = true;
         this.cancelReconnect();
+        // A capture must never outlive both its session and its migration.
+        this.stopStash();
+        if (this.viewportTimer) {
+            clearTimeout(this.viewportTimer);
+            this.viewportTimer = undefined;
+        }
         this.recovering = false;
         this.connection = "closed";
         this.lostSources = NO_SOURCES;
@@ -263,9 +576,16 @@ class MediaRoom {
     scheduleReconnect(cause) {
         if (this.disposed)
             return false;
+        // The room opts into the TIME budget: a person is in front of this
+        // surface, and "Connection lost" over a node that restarts in ninety
+        // seconds is the failure the budget exists for. Headless callers keep
+        // the attempts-only policy by never passing a clock.
+        if (this.outageStartedAt === null)
+            this.outageStartedAt = Date.now();
         const decision = (0, core_1.decideReconnect)({
             cause,
             attempt: this.reconnectAttempt,
+            elapsedMs: Date.now() - this.outageStartedAt,
             ...(this.options.reconnect ? { options: this.options.reconnect } : {}),
         });
         if (decision.action === "stop") {
@@ -307,12 +627,21 @@ class MediaRoom {
         if (!this.device.canProduce(kind)) {
             throw new Error(`this browser cannot produce ${kind}`);
         }
+        // The documented VP8-only exclusivity, enforced instead of conventional.
+        // H.264 simulcast depends on the hardware encoder and quietly degrades to
+        // one layer; sending the encodings anyway would claim layers that do not
+        // exist and a consumer's setPreferredLayers would silently do nothing.
+        let simulcast = options.simulcast ?? false;
+        if (simulcast && options.codec === "h264") {
+            this.options.onLog?.("warn", "simulcast dropped: it is unreliable on h264, publish vp8 or one encoding");
+            simulcast = false;
+        }
         const transport = await this.ensureSendTransport();
         const handle = await transport.produce({
             track,
             appData: { source },
             ...(options.codec ? { codec: options.codec } : {}),
-            ...(options.simulcast
+            ...(simulcast
                 ? { encodings: simulcastEncodings(options.maxBitrateKbps) }
                 : options.maxBitrateKbps
                     ? { encodings: [{ maxBitrate: options.maxBitrateKbps * 1000 }] }
@@ -326,6 +655,7 @@ class MediaRoom {
             source,
             track,
             handle,
+            options,
             paused: false,
         };
         this.publications.set(handle.id, publication);
@@ -426,21 +756,178 @@ class MediaRoom {
      * are the same thing and this needs no special case.
      */
     async syncSubscriptions() {
-        const wanted = new Set(this.stateValue.activeSpeakers);
+        const state = this.stateValue;
+        // AUDIO NEVER NARROWS BY VIEWPORT. You must hear people you cannot see.
+        // This asymmetry is deliberate; do not tidy it into symmetry. Only the
+        // video half of the set is intersected with what the UI reports visible.
+        // The reducer always derives the split (an unknown-kind id lands on the
+        // audio side), so the two halves together ARE the active set.
+        const audioWanted = new Set(state.activeAudio);
+        const videoAllowed = new Set(state.activeVideo);
+        const videoWanted = this.viewport === null
+            ? videoAllowed
+            : new Set(this.viewport.map((e) => e.producerId).filter((id) => videoAllowed.has(id)));
+        // NEVER wider than the node's set: the node refuses a consume outside it,
+        // and a subset of the shared set is what keeps the pipe math bounded.
+        const wanted = new Set([...audioWanted, ...videoWanted]);
+        const allowed = new Set([...audioWanted, ...videoAllowed]);
         for (const [producerId, consumer] of this.consumers) {
-            if (wanted.has(producerId))
+            if (wanted.has(producerId)) {
+                this.cancelViewportPause(producerId, consumer);
                 continue;
-            // Dropped rather than paused. A consumer the node has moved out of the
-            // active set is one it may refuse to keep feeding, and holding it costs
-            // the node a consumer object for a tile nobody is looking at.
-            consumer.close();
-            this.consumers.delete(producerId);
-            this.tracksByProducer.delete(producerId);
-            await this.signal.request({ method: "closeConsumer", consumerId: consumer.id }).catch(() => undefined);
+            }
+            if (!allowed.has(producerId)) {
+                // Out of the ACTIVE SET entirely: dropped rather than paused, today's
+                // semantics. The node may refuse to keep feeding it, and holding it
+                // costs the node a consumer object for a tile nobody may render.
+                this.dropConsumer(producerId, consumer);
+                await this.signal.request({ method: "closeConsumer", consumerId: consumer.id }).catch(() => undefined);
+                continue;
+            }
+            // In the set but off the viewport: pause now, close after the grace.
+            this.beginViewportPause(producerId, consumer);
         }
         await Promise.all([...wanted].map((producerId) => this.subscribe(producerId)));
+        if (this.viewport !== null)
+            this.applyPreferredLayers();
         this.emit();
     }
+    /**
+     * Tell the room what the UI is rendering: which producers, at what width.
+     *
+     * Debounced inside the room (a scroll fires many times), trailing 150ms.
+     * Never call this from a headless consumer; not calling it IS the legacy
+     * subscribe-the-whole-set behavior.
+     */
+    setViewport(entries) {
+        // The FIRST report commits at once: a debounce there would let the join's
+        // first active-set frame subscribe the whole set 150ms before the
+        // narrowing arrived, which is the cost this API exists to avoid. Updates
+        // (scroll, resize) debounce.
+        if (this.viewport === null) {
+            this.viewport = entries;
+            void this.syncSubscriptions().catch((err) => this.options.onLog?.("warn", "viewport sync failed", err));
+            return;
+        }
+        this.pendingViewport = entries;
+        if (this.viewportTimer)
+            return;
+        this.viewportTimer = setTimeout(() => {
+            this.viewportTimer = undefined;
+            const pending = this.pendingViewport;
+            this.pendingViewport = undefined;
+            if (pending === undefined)
+                return;
+            this.viewport = pending;
+            void this.syncSubscriptions().catch((err) => this.options.onLog?.("warn", "viewport sync failed", err));
+        }, 150);
+    }
+    /** Back to the legacy behavior: subscribe the whole active set. */
+    clearViewport() {
+        if (this.viewportTimer) {
+            clearTimeout(this.viewportTimer);
+            this.viewportTimer = undefined;
+        }
+        this.pendingViewport = undefined;
+        if (this.viewport === null)
+            return;
+        this.viewport = null;
+        void this.syncSubscriptions().catch((err) => this.options.onLog?.("warn", "viewport sync failed", err));
+    }
+    /** The width the UI reported for a producer's tile, if it reported one. */
+    viewportWidth(producerId) {
+        return this.viewport?.find((e) => e.producerId === producerId)?.widthPx;
+    }
+    dropConsumer(producerId, consumer) {
+        consumer.close();
+        this.consumers.delete(producerId);
+        this.tracksByProducer.delete(producerId);
+        this.sentLayer.delete(producerId);
+        this.statsBaseline.delete(producerId);
+        const timer = this.pausedByViewport.get(producerId);
+        if (timer)
+            clearTimeout(timer);
+        this.pausedByViewport.delete(producerId);
+    }
+    beginViewportPause(producerId, consumer) {
+        if (this.pausedByViewport.has(producerId))
+            return;
+        // Local pause detaches nothing on its own; the server-side pause is what
+        // stops the RTP. An old node refuses the verb, which degrades to
+        // local-pause-only, and the grace close still frees everything.
+        consumer.pause();
+        void this.requestOptional({ method: "pauseConsumer", consumerId: consumer.id });
+        const timer = setTimeout(() => {
+            // Re-checked at fire time: a flip back cancels the timer, but a timer
+            // racing its own cancellation must not close a tile somebody is watching.
+            if (!this.pausedByViewport.has(producerId))
+                return;
+            this.pausedByViewport.delete(producerId);
+            const current = this.consumers.get(producerId);
+            if (!current)
+                return;
+            this.dropConsumer(producerId, current);
+            void this.signal.request({ method: "closeConsumer", consumerId: current.id }).catch(() => undefined);
+            this.emit();
+        }, this.options.viewportCloseGraceMs ?? 10_000);
+        this.pausedByViewport.set(producerId, timer);
+    }
+    cancelViewportPause(producerId, consumer) {
+        const timer = this.pausedByViewport.get(producerId);
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        this.pausedByViewport.delete(producerId);
+        consumer.resume();
+        void this.requestOptional({ method: "resumeConsumer", consumerId: consumer.id });
+        // A resumed video consumer shows garbage until an I-frame arrives. Ask,
+        // rather than waiting out the encoder's own schedule.
+        if (consumer.kind === "video") {
+            void this.signal.request({ method: "requestKeyFrame", consumerId: consumer.id }).catch(() => undefined);
+        }
+    }
+    /**
+     * Bring every live video consumer onto the layer its reported width implies.
+     * Bucket-change only: the last sent layer is remembered, so a resize storm
+     * costs nothing until a boundary is crossed. A layer change keeps the
+     * consumer, the pipe and the SSRC, which is what makes page flips instant.
+     */
+    applyPreferredLayers() {
+        for (const [producerId, consumer] of this.consumers) {
+            if (consumer.kind !== "video" || this.pausedByViewport.has(producerId))
+                continue;
+            const width = this.viewportWidth(producerId);
+            if (width === undefined)
+                continue;
+            const entry = this.stateValue.producers.find((p) => p.producerId === producerId);
+            const layer = spatialLayerForWidth(width, entry?.source);
+            if (this.sentLayer.get(producerId) === layer)
+                continue;
+            this.sentLayer.set(producerId, layer);
+            void this.requestOptional({ method: "setPreferredLayers", consumerId: consumer.id, spatialLayer: layer });
+        }
+    }
+    /**
+     * A request an OLD node may not understand. Disabled for the session on the
+     * first `bad_request` rather than retried: a retry loop meets the node's
+     * frame budget, and the frame budget closes sockets.
+     */
+    async requestOptional(frame) {
+        if (this.unsupported.has(frame.method))
+            return undefined;
+        try {
+            return await this.signal.request(frame);
+        }
+        catch (error) {
+            if (error.code === "bad_request") {
+                this.unsupported.add(frame.method);
+                this.options.onLog?.("warn", `${frame.method} is not supported by this node, feature disabled`);
+                return undefined;
+            }
+            this.options.onLog?.("warn", `${frame.method} failed`, error);
+            return undefined;
+        }
+    }
     async subscribe(producerId) {
         if (this.consumers.has(producerId))
             return;
@@ -458,11 +945,19 @@ class MediaRoom {
         if (!entry)
             return;
         const transport = await this.ensureRecvTransport();
+        // The layer the tile's reported width implies, asked for from the FIRST
+        // frame. Advisory: a non-simulcast producer has no layers, and an older
+        // node strips the key.
+        const width = entry.kind === "video" ? this.viewportWidth(producerId) : undefined;
+        const layer = width === undefined ? undefined : spatialLayerForWidth(width, entry.source);
+        if (layer !== undefined)
+            this.sentLayer.set(producerId, layer);
         const response = (await this.signal.request({
             method: "consume",
             transportId: transport.id,
             producerId,
             rtpCapabilities: this.device.rtpCapabilities,
+            ...(layer !== undefined ? { preferredLayers: { spatialLayer: layer } } : {}),
         }));
         const consumer = await transport.consume({
             id: response.consumerId,
@@ -487,6 +982,86 @@ class MediaRoom {
         this.emit();
     }
     // -------------------------------------------------------------------------
+    // ephemeral signals: reactions, hands
+    // -------------------------------------------------------------------------
+    /**
+     * Send an ephemeral, unstored fan-out to the room: a flying reaction, a
+     * courtesy lower-hand. Grant-gated on the node (`canPublishData`) and
+     * rate-limited there; NOT a chat transport, and nothing durable may be
+     * derived from one.
+     */
+    async sendReaction(data) {
+        await this.requestOptional({ method: "broadcast", type: "reaction", data });
+    }
+    /**
+     * Ask another participant to lower their hand. Honorific by design: the
+     * TARGET's client obeys by calling `setHandRaised(false)` itself; the
+     * server-held hand state only ever moves on its owner's verb.
+     */
+    async sendLowerHand(target) {
+        await this.requestOptional({ method: "broadcast", type: "lowerHand", data: { target } });
+    }
+    /**
+     * Raise or lower this participant's own hand. Server-materialized room
+     * state: it survives reconnects and appears in late joiners' snapshots, so
+     * `state.raisedHands` is the truth to render, not the reply.
+     */
+    async setHandRaised(raised) {
+        await this.requestOptional({ method: "setHand", raised });
+    }
+    /**
+     * Incoming broadcasts, as EVENTS rather than state: a reaction is an
+     * animation, and holding a list of them in `RoomState` would make every
+     * emoji a whole-room re-render. Unknown types included; ignore what you
+     * do not recognize.
+     */
+    onBroadcast(listener) {
+        this.broadcastListeners.add(listener);
+        return () => this.broadcastListeners.delete(listener);
+    }
+    // -------------------------------------------------------------------------
+    // the planned move
+    // -------------------------------------------------------------------------
+    /**
+     * The node asked to be left, with a jittered window. THE fix for the drain
+     * experience: this frame used to be recorded and ignored, so the "told,
+     * not cut" design never executed and everyone was cut at the deadline.
+     * The call continues untouched during the wait; the UI is not told.
+     */
+    onDrainingFrame(reconnectAfterMs) {
+        if (this.disposed || this.migration !== null)
+            return;
+        if (this.connection !== "connected")
+            return;
+        const timer = setTimeout(() => this.beginPlannedMove(), Math.max(0, reconnectAfterMs));
+        this.migration = { phase: "scheduled", timer };
+    }
+    beginPlannedMove() {
+        if (this.migration?.phase !== "scheduled")
+            return;
+        if (this.connection !== "connected" || this.disposed) {
+            // A real drop got here first; its path owns the recovery.
+            this.migration = null;
+            return;
+        }
+        /**
+         * The stash is NOT built here. `leave()` below is a full round trip (up
+         * to the request timeout against a busy node), and the person can mute,
+         * unmute, start or stop a capture the whole time: a stash taken now
+         * republishes a mic they have since muted, and a share they started in
+         * the window would be orphaned with its light on. The close handler
+         * builds the stash at the moment the connection actually ends, when the
+         * publications map is the truth.
+         */
+        this.migration = { phase: "moving", stash: NO_STASH, plannedClose: true };
+        /**
+         * `leave()`, not a bare close: the leave request makes the OLD node tear
+         * our participant record down synchronously, so the rejoin seconds later
+         * cannot meet its own ghost and be refused `duplicate_identity`.
+         */
+        void this.signal.leave().catch(() => undefined);
+    }
+    // -------------------------------------------------------------------------
     // transports
     // -------------------------------------------------------------------------
     /**
@@ -573,6 +1148,19 @@ class MediaRoom {
         this.stateValue = next;
         if (frame.event === "joined")
             this.grantsValue = frame.grants ?? this.grantsValue;
+        if (frame.event === "draining")
+            this.onDrainingFrame(frame.reconnectAfterMs);
+        if (frame.event === "broadcast") {
+            const event = { type: frame.type, identity: frame.identity, data: frame.data, at: frame.at };
+            for (const listener of this.broadcastListeners) {
+                try {
+                    listener(event);
+                }
+                catch {
+                    // One listener throwing must not stop the others from being told.
+                }
+            }
+        }
         if (frame.event === "producerClosed") {
             const consumer = this.consumers.get(frame.producerId);
             consumer?.close();
@@ -605,17 +1193,30 @@ class MediaRoom {
      * node tears the session down on close anyway. Ending one publication on a
      * LIVE connection is `unpublish`, which does tell it.
      */
-    teardownMedia() {
+    teardownMedia(options = {}) {
         for (const consumer of this.consumers.values())
             consumer.close();
         this.consumers.clear();
         this.tracksByProducer.clear();
+        // Viewport pause bookkeeping belongs to the consumers that just closed.
+        // The viewport ITSELF is kept: it is the UI's statement about what it
+        // renders, and it applies to the next connection unchanged.
+        for (const timer of this.pausedByViewport.values())
+            clearTimeout(timer);
+        this.pausedByViewport.clear();
+        this.sentLayer.clear();
+        this.statsBaseline.clear();
         for (const detach of this.trackEndWatchers.values())
             detach();
         this.trackEndWatchers.clear();
         for (const publication of this.publications.values()) {
             publication.handle.close();
-            publication.track.stop();
+            // A PLANNED move keeps the captures: the stash holds the same track
+            // objects and republishes them on the far side, so the camera light
+            // never blinks for a server deploy. Every other teardown stops them,
+            // for the privacy reasons the docblock above states.
+            if (!options.preserveCaptures)
+                publication.track.stop();
         }
         this.publications.clear();
         for (const slot of Object.values(this.transports)) {
@@ -645,6 +1246,8 @@ class MediaRoom {
 }
 exports.MediaRoom = MediaRoom;
 const NO_SOURCES = [];
+/** Placeholder until the close handler builds the real stash. */
+const NO_STASH = [];
 /**
  * Call `onEnded` when a track ends on its own, and return the detach.
  *