@tribe-nest/media-client 0.1.1 → 0.4.0

package/src/room/room.ts

@@ -81,17 +81,203 @@ export type MediaTrack = {
   track: MediaStreamTrack;
   /** Paused at the SOURCE, as the publisher left it. */
   paused: boolean;
+  /** The publisher's declared label, when the node relayed one. Rendering only. */
+  source?: string;
 };
 
 /** What a local track is, in the vocabulary the node checks against `publishKinds`. */
 export type LocalPublicationSource = "camera" | "microphone" | "screen";
 
+/**
+ * Every label this SDK publishes under.
+ *
+ * `program` is a COMPOSED feed rather than a device: a broadcast studio's
+ * rendered output, published so a server-side egress can restream it. It is
+ * not a capture, so it is never a "lost source" to re-offer a person after a
+ * drop, and `useLocalMedia`'s device controls never touch it. The node treats
+ * it as its track's kind (`requiredPublishKind`), so a token needs only
+ * `publishKinds: ["audio", "video"]`.
+ */
+export type PublishSourceLabel = LocalPublicationSource | "program";
+
+/**
+ * How to encode one publication, where the default is wrong.
+ *
+ * A camera takes the browser's defaults. A composed program feed does not:
+ * an RTMP restream needs H.264 (RTMP carries nothing else, and the egress
+ * copies rather than transcodes), and a 1080p canvas at the default bitrate
+ * is a smear. Both are per-publication facts, not per-room ones.
+ */
+export type PublishOptions = {
+  /** Pick this codec from the router's list. Ignored when the router lacks it. */
+  codec?: "h264" | "vp8";
+  /** Cap for the encoder, in kbit/s. Read as the TOP layer under simulcast. */
+  maxBitrateKbps?: number;
+  /**
+   * Send three spatial layers instead of one, so each consumer can be served
+   * the one its connection can carry.
+   *
+   * The choosing is not ours and does not need to be: mediasoup picks a layer
+   * per consumer from that transport's own bandwidth estimate, so a viewer on
+   * a poor line gets 360p rather than a stall, with nothing to implement on
+   * either end. What we decide is only whether the layers exist to choose
+   * from.
+   *
+   * Use it for a feed with an AUDIENCE. It is wrong for a camera in a small
+   * call, where everyone can carry the one encoding and the extra layers are
+   * encoder time spent on nobody.
+   *
+   * ## Why VP8 and not H.264
+   *
+   * Browser simulcast is reliable on VP8 and is not on H.264, where it depends
+   * on the hardware encoder and quietly degrades to one layer. A caller that
+   * needs H.264 downstream (an RTMP restream copies rather than transcodes)
+   * should publish one encoding and leave this off. The two are exclusive by
+   * design rather than by accident.
+   */
+  simulcast?: boolean;
+};
+
+/**
+ * The three layers, quarter / half / full.
+ *
+ * `scaleResolutionDownBy` rather than three bitrates, so the shape holds
+ * 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: "L1T3" },
+  { rid: "h", scaleResolutionDownBy: 2, scalabilityMode: "L1T3" },
+  { rid: "f", scaleResolutionDownBy: 1, scalabilityMode: "L1T3" },
+] as const;
+
+/**
+ * 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.
+ */
+export function spatialLayerForWidth(widthPx: number, source?: string): 0 | 1 | 2 {
+  if (source === "screen") return 2;
+  if (widthPx <= 240) return 0;
+  if (widthPx <= 480) return 1;
+  return 2;
+}
+
+/** One tile the UI is currently rendering, reported through `setViewport`. */
+export type ViewportEntry = {
+  producerId: string;
+  /** Rendered width, used to pick a simulcast layer. 0 is a valid "tiny". */
+  widthPx: number;
+};
+
+/** One rendered tile's health, local view merged with the node's answer. */
+export type TileDiagnostics = {
+  producerId: string;
+  identity: string;
+  kind: "audio" | "video";
+  source?: string;
+  /** The simulcast layer this client last ASKED for: 0 q, 1 h, 2 f. */
+  requestedLayer?: number;
+  /** What the node is actually GIVING, from its consumer's currentLayers. */
+  currentLayer?: number;
+  viewportWidthPx?: number;
+  pausedByViewport: boolean;
+  /** Decoded picture, from the browser's inbound-rtp stats. */
+  frameWidth?: number;
+  frameHeight?: number;
+  framesPerSecond?: number;
+  /** Delta-computed between successive `getDiagnostics` calls; absent on the first. */
+  bitrateKbps?: number;
+};
+
+/** The node's half of `getDiagnostics`, absent against an older node. */
+export type NodeDiagnostics = {
+  transports: { transportId: string; availableOutgoingBitrate?: number; iceState?: string; dtlsState?: string }[];
+  producers: {
+    producerId: string;
+    kind: string;
+    paused: boolean;
+    source?: string;
+    layers: { rid?: string; score: number }[];
+  }[];
+  consumers: {
+    consumerId: string;
+    producerId: string;
+    kind: string;
+    paused: boolean;
+    preferredLayers?: { spatialLayer: number; temporalLayer?: number };
+    currentLayers?: { spatialLayer: number; temporalLayer?: number };
+    score?: unknown;
+  }[];
+};
+
+export type CallDiagnostics = {
+  tiles: TileDiagnostics[];
+  /**
+   * The recv transport's congestion estimate in bits per second, from the
+   * node. THE number to look at first: every video consumer shares it, and
+   * an estimate sitting at the low hundreds of kbps in a group call is the
+   * estimator pinning everyone to the quarter layer, whatever anyone asked.
+   */
+  availableOutgoingBitrate?: number;
+  /** This participant's own publishers, per-encoding arrival scores included:
+   * a layer scored 0 is a layer the node is not receiving. */
+  localProducers?: NodeDiagnostics["producers"];
+  /** The raw node answer, for anything the shaped fields above leave out. */
+  node?: NodeDiagnostics;
+};
+
+/** How an incoming ephemeral broadcast reaches the application. */
+export type BroadcastEvent = {
+  type: string;
+  identity: string;
+  data: Record<string, unknown>;
+  /** Origin node clock. Animation ordering only. */
+  at: number;
+};
+
+/**
+ * What each layer may spend, given the caller's cap for the top one.
+ *
+ * Quarter resolution is a sixteenth of the pixels, but not a sixteenth of the
+ * bits: an encoder needs proportionally more per pixel at small sizes, and a
+ * layer starved below what its resolution costs is a layer that looks worse
+ * than it should while still being sent. A quarter and a tenth are the
+ * conventional split and are what mediasoup's own examples use.
+ */
+function simulcastEncodings(maxBitrateKbps: number | undefined): unknown[] {
+  const top = (maxBitrateKbps ?? 0) * 1000;
+  const share = [0.1, 0.25, 1];
+  return SIMULCAST_LAYERS.map((layer, index) => ({
+    ...layer,
+    ...(top ? { maxBitrate: Math.round(top * share[index]!) } : {}),
+  }));
+}
+
 export type LocalPublication = {
   producerId: string;
   kind: "audio" | "video";
-  source: LocalPublicationSource;
+  source: PublishSourceLabel;
   track: MediaStreamTrack;
   handle: MediaProducerHandle;
+  /** As given to `publish`, kept so a planned server move can republish the
+   * same encoding (codec, simulcast, bitrate) without asking anyone. */
+  options: PublishOptions;
   /**
    * Paused at the source by `setPaused`. The capture is still open and the
    * producer still exists; nothing is being sent. This is what a mute is.
@@ -121,11 +307,25 @@ export type MediaRoomOptions = {
   webSocket?: MediaWebSocketFactory;
   /**
    * How hard to try to get back in after a drop. Defaults to
-   * `DEFAULT_RECONNECT_OPTIONS`; `{ maxAttempts: 0 }` turns automatic recovery
+   * `DEFAULT_RECONNECT_OPTIONS`; `{ maxAttempts: 0 }` turns FAILURE recovery
    * off, which leaves `isRecovering` false and is what tells a UI to offer a
    * control instead of a spinner.
+   *
+   * A server-ordered drain MOVE is deliberately not a failure and happens
+   * even at `maxAttempts: 0`: the node asked to be left and named where to
+   * go, and honoring that is what keeps the call alive through a deploy.
+   * If the move's rejoin then FAILS, the off switch applies to every retry
+   * after it.
    */
   reconnect?: Partial<ReconnectOptions>;
+  /**
+   * How long a video consumer that fell out of the viewport stays PAUSED
+   * before it is closed. Pause is cheap and reversible (a page flip back
+   * costs a resume, not a consume plus a keyframe); close frees the node's
+   * consumer slot and eventually the mirror and pipe. Mirrors the
+   * `mirrorGraceMs` reasoning on the node.
+   */
+  viewportCloseGraceMs?: number;
   onLog?: (level: SignalLogLevel, message: string, detail?: unknown) => void;
 };
 
@@ -153,16 +353,51 @@ export class MediaRoom {
   /** Per publication: stop listening for the track ending on its own. */
   private readonly trackEndWatchers = new Map<string, () => void>();
   private readonly listeners = new Set<Listener>();
+  private readonly broadcastListeners = new Set<(event: BroadcastEvent) => void>();
   /** One in-flight subscribe per producer, so a burst of activeSpeakers frames
    * does not race itself into two consumers for one producer. */
   private readonly subscribing = new Map<string, Promise<void>>();
 
+  /**
+   * 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.
+   */
+  private viewport: readonly ViewportEntry[] | null = null;
+  private viewportTimer: ReturnType<typeof setTimeout> | undefined;
+  private pendingViewport: readonly ViewportEntry[] | null | undefined;
+  /** Video consumers paused because their tile is off-viewport, each holding
+   * its close timer. Single owner of the pause/close decision. */
+  private readonly pausedByViewport = new Map<string, ReturnType<typeof setTimeout>>();
+  /** The last spatial layer requested per producer, so a resize storm only
+   * speaks up when a bucket boundary is crossed. */
+  private readonly sentLayer = new Map<string, number>();
+  /** Old-node degradation: each new verb is disabled on its first
+   * `bad_request`, never retried into the frame budget. */
+  private readonly unsupported = new Set<string>();
+
   private stateValue: RoomState = initialRoomState;
   private connection: ConnectionState = "idle";
   private lastError: DisconnectCause | undefined;
 
   /** Consecutive failed attempts since the last successful join. */
   private 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. */
+  private outageStartedAt: number | null = 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.
+   */
+  private migration:
+    | { phase: "scheduled"; timer: ReturnType<typeof setTimeout> }
+    | { phase: "moving"; stash: readonly StashedPublication[]; plannedClose: boolean }
+    | null = null;
   private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
   private recovering = false;
   /** `close()` has been called. Nothing may open a socket after that. */
@@ -185,24 +420,92 @@ export class MediaRoom {
    * it ended after an hour or before a socket was ever opened.
    */
   private onDisconnect(cause: DisconnectCause): void {
+    /**
+     * 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`).
-    const wasPublishing = [...new Set([...this.publications.values()].map((p) => p.source))];
+    // A program feed is excluded: it is a studio's output, not something a
+    // person switched on, so nobody should be asked to switch it back on.
+    const wasPublishing = [
+      ...new Set(
+        [...this.publications.values()]
+          .map((p) => p.source)
+          .filter((s): s is LocalPublicationSource => s !== "program"),
+      ),
+    ];
     // 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();
@@ -212,9 +515,75 @@ export class MediaRoom {
     if (wasPublishing.length > 0) 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.
+   */
+  private clearActiveSetState(): void {
+    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`. */
+  private buildStash(): readonly StashedPublication[] {
+    return [...this.publications.values()]
+      .filter((p): p is LocalPublication & { source: LocalPublicationSource } => 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.
+   */
+  private stopStash(): void {
+    const migration = this.migration;
+    if (migration?.phase === "scheduled") {
+      clearTimeout(migration.timer);
+      this.migration = null;
+      return;
+    }
+    if (migration?.phase !== "moving") return;
+    const sources = new Set<LocalPublicationSource>();
+    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(): RoomState {
     return this.stateValue;
   }
@@ -287,6 +656,95 @@ export class MediaRoom {
     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(): Promise<CallDiagnostics> {
+    const node = ((await this.requestOptional({ method: "diagnostics" })) ?? undefined) as
+      | NodeDiagnostics
+      | 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: TileDiagnostics[] = [];
+    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. */
+  private readonly statsBaseline = new Map<string, { bytes: number; at: number }>();
+
+  private async inboundStats(
+    producerId: string,
+    consumer: MediaConsumerHandle,
+  ): Promise<Partial<TileDiagnostics>> {
+    if (!consumer.getStats) return {};
+    let report: unknown;
+    try {
+      report = await consumer.getStats();
+    } catch {
+      return {};
+    }
+    // An RTCStatsReport is a map; anything iterable of stats objects works.
+    const entries: Record<string, unknown>[] = [];
+    const iterable = report as { values?: () => Iterable<unknown> };
+    if (typeof iterable?.values === "function") {
+      for (const value of iterable.values()) entries.push(value as Record<string, unknown>);
+    } else if (Array.isArray(report)) {
+      for (const value of report) entries.push(value as Record<string, unknown>);
+    }
+    const inbound = entries.find((e) => e["type"] === "inbound-rtp");
+    if (!inbound) return {};
+
+    const out: Partial<TileDiagnostics> = {
+      ...(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: Listener): () => void {
     this.listeners.add(listener);
@@ -305,8 +763,10 @@ export 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
@@ -343,15 +803,58 @@ export 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);
+    }
+  }
+
+  private async restoreStash(stash: readonly StashedPublication[]): Promise<void> {
+    const lost = new Set<LocalPublicationSource>();
+    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(): Promise<void> {
     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;
@@ -381,9 +884,15 @@ export class MediaRoom {
   private scheduleReconnect(cause: DisconnectCause): boolean {
     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 = decideReconnect({
       cause,
       attempt: this.reconnectAttempt,
+      elapsedMs: Date.now() - this.outageStartedAt,
       ...(this.options.reconnect ? { options: this.options.reconnect } : {}),
     });
     if (decision.action === "stop") {
@@ -422,14 +931,39 @@ export class MediaRoom {
    * `publishKinds`: a token granting audio only must not be able to publish a
    * screen share by relabelling it, and the node is where that is decided.
    */
-  async publish(track: MediaStreamTrack, source: LocalPublicationSource): Promise<LocalPublication> {
+  async publish(
+    track: MediaStreamTrack,
+    source: PublishSourceLabel,
+    options: PublishOptions = {},
+  ): Promise<LocalPublication> {
     const kind = track.kind === "audio" ? "audio" : "video";
     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 } });
+    const handle = await transport.produce({
+      track,
+      appData: { source },
+      ...(options.codec ? { codec: options.codec } : {}),
+      ...(simulcast
+        ? { encodings: simulcastEncodings(options.maxBitrateKbps) }
+        : options.maxBitrateKbps
+          ? { encodings: [{ maxBitrate: options.maxBitrateKbps * 1000 }] }
+          : {}),
+    });
+
+    if (source === "program") await keepProgramResolution(handle, this.options.onLog);
 
     const publication: LocalPublication = {
       producerId: handle.id,
@@ -437,6 +971,7 @@ export class MediaRoom {
       source,
       track,
       handle,
+      options,
       paused: false,
     };
     this.publications.set(handle.id, publication);
@@ -450,7 +985,7 @@ export class MediaRoom {
         void this.unpublish(handle.id);
       }),
     );
-    if (this.lostSources.includes(source)) {
+    if (source !== "program" && this.lostSources.includes(source)) {
       this.lostSources = this.lostSources.filter((s) => s !== source);
       if (this.lostSources.length === 0) this.lostSources = NO_SOURCES;
     }
@@ -458,6 +993,35 @@ export class MediaRoom {
     return publication;
   }
 
+  /**
+   * Swap the capture behind a publication, keeping the producer.
+   *
+   * A device change (another camera, another microphone) is this, and it is
+   * deliberately NOT unpublish plus publish: that changes the producer id,
+   * which is the key every consumer's tile and every studio's scene holds, so
+   * a switched camera vanished from the stage until somebody re-added it.
+   * The old capture is stopped here; the new one is watched for ending the
+   * same way the first was.
+   */
+  async replaceTrack(producerId: string, track: MediaStreamTrack): Promise<void> {
+    const publication = this.publications.get(producerId);
+    if (!publication) throw new Error("no such publication");
+    if (track.kind !== publication.kind) throw new Error(`a ${publication.kind} publication cannot carry ${track.kind}`);
+    if (track === publication.track) return;
+
+    await publication.handle.replaceTrack(track);
+    this.trackEndWatchers.get(producerId)?.();
+    publication.track.stop();
+    this.trackEndWatchers.set(
+      producerId,
+      whenTrackEnds(track, () => {
+        void this.unpublish(producerId);
+      }),
+    );
+    this.publications.set(producerId, { ...publication, track });
+    this.emit();
+  }
+
   async unpublish(producerId: string): Promise<void> {
     const publication = this.publications.get(producerId);
     if (!publication) return;
@@ -514,23 +1078,176 @@ export class MediaRoom {
    * are the same thing and this needs no special case.
    */
   async syncSubscriptions(): Promise<void> {
-    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)) 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 (wanted.has(producerId)) {
+        this.cancelViewportPause(producerId, consumer);
+        continue;
+      }
+      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: readonly ViewportEntry[]): void {
+    // 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(): void {
+    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. */
+  private viewportWidth(producerId: string): number | undefined {
+    return this.viewport?.find((e) => e.producerId === producerId)?.widthPx;
+  }
+
+  private dropConsumer(producerId: string, consumer: MediaConsumerHandle): void {
+    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);
+  }
+
+  private beginViewportPause(producerId: string, consumer: MediaConsumerHandle): void {
+    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);
+  }
+
+  private cancelViewportPause(producerId: string, consumer: MediaConsumerHandle): void {
+    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.
+   */
+  private applyPreferredLayers(): void {
+    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.
+   */
+  private async requestOptional(frame: { method: string } & Record<string, unknown>): Promise<unknown> {
+    if (this.unsupported.has(frame.method)) return undefined;
+    try {
+      return await this.signal.request(frame as never);
+    } catch (error) {
+      if ((error as { code?: string }).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: string): Promise<void> {
     if (this.consumers.has(producerId)) return;
     const inFlight = this.subscribing.get(producerId);
@@ -548,11 +1265,18 @@ export 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 } } : {}),
     })) as { consumerId: string; producerId: string; kind: "audio" | "video"; rtpParameters: RtpParameters };
 
     const consumer = await transport.consume({
@@ -569,6 +1293,7 @@ export class MediaRoom {
       kind: response.kind,
       track: consumer.track,
       paused: entry.paused,
+      ...(entry.source ? { source: entry.source } : {}),
     });
 
     // RULE 3: resume LAST. The node creates every consumer paused, so media
@@ -579,6 +1304,91 @@ export 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: Record<string, unknown>): Promise<void> {
+    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: string): Promise<void> {
+    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: boolean): Promise<void> {
+    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: (event: BroadcastEvent) => void): () => void {
+    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.
+   */
+  private onDrainingFrame(reconnectAfterMs: number): void {
+    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 };
+  }
+
+  private beginPlannedMove(): void {
+    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
   // -------------------------------------------------------------------------
@@ -675,6 +1485,19 @@ export class MediaRoom {
 
     if (frame.event === "joined") this.grantsValue = frame.grants ?? this.grantsValue;
 
+    if (frame.event === "draining") this.onDrainingFrame(frame.reconnectAfterMs);
+
+    if (frame.event === "broadcast") {
+      const event: BroadcastEvent = { 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();
@@ -709,16 +1532,27 @@ export class MediaRoom {
    * node tears the session down on close anyway. Ending one publication on a
    * LIVE connection is `unpublish`, which does tell it.
    */
-  private teardownMedia(): void {
+  private teardownMedia(options: { preserveCaptures?: boolean } = {}): void {
     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();
 
@@ -750,6 +1584,17 @@ export class MediaRoom {
 }
 
 const NO_SOURCES: readonly LocalPublicationSource[] = [];
+/** Placeholder until the close handler builds the real stash. */
+const NO_STASH: readonly StashedPublication[] = [];
+
+/** A live capture carried across a planned server move. */
+type StashedPublication = {
+  track: MediaStreamTrack;
+  kind: "audio" | "video";
+  source: LocalPublicationSource;
+  paused: boolean;
+  options: PublishOptions;
+};
 
 /**
  * Call `onEnded` when a track ends on its own, and return the detach.
@@ -774,3 +1619,45 @@ export async function connectToRoom(options: MediaRoomOptions): Promise<MediaRoo
   await room.connect();
   return room;
 }
+
+/**
+ * The program feed keeps its RESOLUTION and gives up frame rate instead.
+ *
+ * Chrome's default for a video sender is `balanced`, which under a low
+ * bandwidth estimate or CPU pressure scales the encode down. For a camera tile
+ * that is the right trade. For the program feed it is wrong twice over.
+ *
+ * First, this feed is the broadcast: a 1080p composite arriving at Twitch as
+ * 270p is the product, not a degraded preview. Twitch reported exactly that.
+ *
+ * Second, and worse, the RTMP leg cannot survive the CHANGE. The egress muxes
+ * the feed with `-c:v copy`, and an FLV header carries the dimensions once, at
+ * the start. When Chrome adapts resolution mid-stream the SPS changes under a
+ * header that still describes the old size, and the player refuses the stream:
+ *
+ *   Your browser encountered an error while decoding the video. (Error #3000)
+ *
+ * while ffmpeg reports `drop_frames=0`, a healthy bitrate, and an established
+ * socket. Nothing on the server can see it.
+ *
+ * `maintain-resolution` makes the encoder drop frames rather than pixels, so
+ * the SPS stays put for the life of the broadcast.
+ *
+ * Best-effort: the setting is not universally implemented, and a browser that
+ * ignores it is no worse off than before. Only the program source, because a
+ * camera is better off shrinking than freezing.
+ */
+async function keepProgramResolution(
+  handle: MediaProducerHandle,
+  onLog?: (level: "warn" | "debug", message: string, detail?: unknown) => void,
+): Promise<void> {
+  const sender = handle.rtpSender;
+  if (!sender || handle.kind !== "video") return;
+  try {
+    const params = sender.getParameters() as RTCRtpSendParameters & { degradationPreference?: string };
+    params.degradationPreference = "maintain-resolution";
+    await sender.setParameters(params);
+  } catch (err) {
+    onLog?.("warn", "could not pin the program feed's resolution", err);
+  }
+}