@tribe-nest/media-client 0.1.1 → 0.4.0

package/src/room/_tests/room.spec.ts

@@ -26,7 +26,15 @@ import type {
 type Recorded = { calls: string[]; transports: FakeTransport[] };
 
 class FakeTransport implements MediaTransport {
-  readonly produced: { appData?: Record<string, unknown> }[] = [];
+  readonly produced: { appData?: Record<string, unknown>; codec?: "h264" | "vp8"; encodings?: unknown[] }[] = [];
+  /** Records what the room asked the sender for. */
+  readonly senderParams: Record<string, unknown> = {};
+  readonly sender = {
+    getParameters: () => ({ encodings: [] }) as unknown as RTCRtpSendParameters,
+    setParameters: async (params: RTCRtpSendParameters) => {
+      Object.assign(this.senderParams, params);
+    },
+  } as unknown as RTCRtpSender;
   readonly consumed: string[] = [];
   closed = false;
   handlers: Partial<TransportHandlers> = {};
@@ -37,8 +45,19 @@ class FakeTransport implements MediaTransport {
     private readonly recorded: Recorded,
   ) {}
 
-  async produce(input: { track: MediaStreamTrack; appData?: Record<string, unknown> }): Promise<MediaProducerHandle> {
-    this.produced.push({ ...(input.appData ? { appData: input.appData } : {}) });
+  async produce(input: {
+    track: MediaStreamTrack;
+    appData?: Record<string, unknown>;
+    encodings?: unknown[];
+    codec?: "h264" | "vp8";
+  }): Promise<MediaProducerHandle> {
+    // Recorded EXACTLY as given: a key that is absent and a key set to
+    // undefined are different things to mediasoup-client.
+    this.produced.push({
+      ...(input.appData ? { appData: input.appData } : {}),
+      ...("codec" in input ? { codec: input.codec } : {}),
+      ...("encodings" in input ? { encodings: input.encodings } : {}),
+    });
     // The real transport asks the application to tell the node, and the node's
     // answer is the producer id. Modelled, because the round trip is the thing
     // that can be got wrong.
@@ -55,6 +74,10 @@ class FakeTransport implements MediaTransport {
       pause: vi.fn(),
       resume: vi.fn(),
       close: vi.fn(),
+      replaceTrack: vi.fn(async () => undefined),
+      // A real browser producer carries one, and the program feed's
+      // degradation preference is set through it.
+      rtpSender: this.sender,
     };
   }
 
@@ -62,6 +85,7 @@ class FakeTransport implements MediaTransport {
     this.consumed.push(input.producerId);
     this.recorded.calls.push(`consume:${input.producerId}`);
     const resume = vi.fn(() => this.recorded.calls.push(`track-resume:${input.producerId}`));
+    let statBytes = 0;
     return {
       id: input.id,
       producerId: input.producerId,
@@ -70,6 +94,10 @@ class FakeTransport implements MediaTransport {
       pause: vi.fn(),
       resume,
       close: vi.fn(),
+      // 50 kilobytes more per read: two reads a second apart show 400 kbps.
+      getStats: async () => [
+        { type: "inbound-rtp", frameWidth: 320, frameHeight: 180, framesPerSecond: 24, bytesReceived: (statBytes += 50_000) },
+      ],
     };
   }
 
@@ -127,7 +155,7 @@ function fakeDevice(recorded: Recorded) {
  * the room is exercised against the same wire the signal client is.
  */
 function nodeWith(input: {
-  producers?: { producerId: string; identity: string; kind: "audio" | "video" }[];
+  producers?: { producerId: string; identity: string; kind: "audio" | "video"; source?: string }[];
   iceServers?: IceServer[];
   /**
    * Events delivered on EVERY connection after the join reply and BEFORE the
@@ -283,6 +311,39 @@ describe("rule 2: one transport per direction, created lazily", () => {
     await room.close();
   });
 
+  it("keeps the PROGRAM feed's resolution, giving up frame rate instead", async () => {
+    /**
+     * Chrome's default scales the encode down under a low bandwidth estimate
+     * or CPU pressure. For the program feed that is wrong twice: it is the
+     * broadcast itself, so 1080p arriving as 270p is the product; and the RTMP
+     * leg muxes it with `-c:v copy`, where an FLV header carries the dimensions
+     * once. A mid-stream resolution change leaves the SPS describing one size
+     * and the header another, and the player refuses it with "error #3000"
+     * while ffmpeg reports a healthy bitrate and zero dropped frames.
+     */
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(nodeWith({}), recorded, false);
+    await room.connect();
+
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "program");
+
+    const transport = recorded.transports[0] as unknown as { senderParams: Record<string, unknown> };
+    expect(transport.senderParams.degradationPreference).toBe("maintain-resolution");
+    await room.close();
+  });
+
+  it("leaves a CAMERA alone, which is better off shrinking than freezing", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(nodeWith({}), recorded, false);
+    await room.connect();
+
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "camera");
+
+    const transport = recorded.transports[0] as unknown as { senderParams: Record<string, unknown> };
+    expect(transport.senderParams.degradationPreference).toBeUndefined();
+    await room.close();
+  });
+
   it("reuses the recv transport across subscriptions", async () => {
     const recorded: Recorded = { calls: [], transports: [] };
     const server = nodeWith({
@@ -421,6 +482,48 @@ describe("rule 3: a consumer resumes only after its track exists", () => {
   });
 });
 
+/**
+ * The publisher's label reaches the tile.
+ *
+ * The node relays `appData.source` as `source` on the snapshot and on every
+ * `producerAppeared`, and the room keeps it on the entry. A consumed track
+ * carries it so a screen share, a camera and a program feed can be laid out
+ * differently; a producer the node relayed no label for carries none.
+ */
+describe("a consumed track carries the publisher's source", () => {
+  it("from the join snapshot", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [
+        { producerId: "p-a", identity: "anwalt", kind: "video", source: "screen" },
+        { producerId: "p-b", identity: "anwalt", kind: "audio" },
+      ],
+    });
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+    await room.subscribe("p-a");
+    await room.subscribe("p-b");
+
+    expect(room.tracks.find((t) => t.producerId === "p-a")).toMatchObject({ identity: "anwalt", source: "screen" });
+    expect(room.tracks.find((t) => t.producerId === "p-b")).not.toHaveProperty("source");
+    await room.close();
+  });
+
+  it("from a producerAppeared announced after the join", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    server.event({ event: "producerAppeared", producerId: "p-c", identity: "studio", kind: "video", source: "program" });
+    await flush();
+    await room.subscribe("p-c");
+
+    expect(room.tracks[0]).toMatchObject({ producerId: "p-c", identity: "studio", source: "program" });
+    await room.close();
+  });
+});
+
 describe("rule 4: autoSubscribe follows the ACTIVE SET", () => {
   it("subscribes only to what the node put in the set", async () => {
     const recorded: Recorded = { calls: [], transports: [] };
@@ -521,6 +624,53 @@ describe("publishing", () => {
   });
 });
 
+/**
+ * A publication can say how it wants to be encoded.
+ *
+ * A camera takes the browser's defaults and that is right. A composed program
+ * feed does not: an RTMP restream needs H.264, because RTMP carries nothing
+ * else and the egress copies rather than transcodes, and a 1080p canvas at the
+ * default bitrate is a smear. Both are facts about ONE publication, so they
+ * travel with the `publish` call rather than with the room.
+ */
+describe("publishing with options", () => {
+  it("passes the codec and a bitrate cap to the transport", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "program", { codec: "h264", maxBitrateKbps: 3500 });
+
+    const [produced] = recorded.transports.find((t) => t.direction === "send")!.produced;
+    expect(produced).toEqual({
+      appData: { source: "program" },
+      codec: "h264",
+      // kbit/s at the API, bit/s at the encoder. The unit is the whole bug.
+      encodings: [{ maxBitrate: 3_500_000 }],
+    });
+    // And the node still hears the label it checks grants against.
+    const produce = requestsOf(server, "produce")[0] as { appData?: { source?: string } };
+    expect(produce.appData?.source).toBe("program");
+    await room.close();
+  });
+
+  it("passes neither when no options are given, so the defaults stay the browser's", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "camera");
+
+    const [produced] = recorded.transports.find((t) => t.direction === "send")!.produced;
+    expect(produced).toEqual({ appData: { source: "camera" } });
+    expect(produced).not.toHaveProperty("codec");
+    expect(produced).not.toHaveProperty("encodings");
+    await room.close();
+  });
+});
+
 /**
  * A state called "reconnecting" has to mean something is reconnecting.
  *
@@ -974,6 +1124,31 @@ describe("publications lost to a drop", () => {
     await room.close();
   });
 
+  it("never names a program feed, which is a studio's output and not a person's capture", async () => {
+    // Nobody should be asked to "turn the program back on": it is not a
+    // device, and `useLocalMedia`'s controls never touch it. Only the camera
+    // is a lost source here, and republishing the program clears nothing.
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "camera");
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "program", { codec: "h264" });
+    server.socket.dropFromServer();
+    await flush();
+
+    await vi.waitFor(() => expect(server.sockets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    expect(room.lostPublicationSources).toEqual(["camera"]);
+
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "program", { codec: "h264" });
+    expect(room.lostPublicationSources).toEqual(["camera"]);
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "camera");
+    expect(room.lostPublicationSources).toEqual([]);
+    await room.close();
+  });
+
   it("says nothing after a leave, which lost nothing", async () => {
     const recorded: Recorded = { calls: [], transports: [] };
     const server = nodeWith({});
@@ -1095,3 +1270,778 @@ describe("pausing a publication", () => {
     await room.close();
   });
 });
+
+describe("replaceTrack: a device switch keeps its producer", () => {
+  it("swaps the capture on the handle, stops the old track, keeps the producer id", async () => {
+    const server = nodeWith({ producers: [] });
+    const room = roomFor(server, { calls: [], transports: [] });
+    await room.connect();
+    const first = { kind: "video", stop: vi.fn(), addEventListener: vi.fn(), removeEventListener: vi.fn() } as unknown as MediaStreamTrack;
+    const second = { kind: "video", stop: vi.fn(), addEventListener: vi.fn(), removeEventListener: vi.fn() } as unknown as MediaStreamTrack;
+    const published = await room.publish(first, "camera");
+
+    await room.replaceTrack(published.producerId, second);
+
+    expect(published.handle.replaceTrack).toHaveBeenCalledWith(second);
+    expect(first.stop).toHaveBeenCalled();
+    expect(second.stop).not.toHaveBeenCalled();
+    expect(room.localPublications).toHaveLength(1);
+    expect(room.localPublications[0]).toMatchObject({ producerId: published.producerId, track: second, source: "camera" });
+  });
+
+  it("publishes three layers when simulcast is asked for, splitting the caller's cap", async () => {
+    const server = nodeWith({ producers: [] });
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(server, recorded);
+    await room.connect();
+    const track = { kind: "video", stop: vi.fn(), addEventListener: vi.fn(), removeEventListener: vi.fn() } as unknown as MediaStreamTrack;
+
+    await room.publish(track, "program", { codec: "vp8", simulcast: true, maxBitrateKbps: 3500 });
+
+    const produced = recorded.transports.find((t) => t.direction === "send")!.produced[0]!;
+    expect(produced.codec).toBe("vp8");
+    expect(produced.encodings).toEqual([
+      { rid: "q", scaleResolutionDownBy: 4, scalabilityMode: "L1T3", maxBitrate: 350_000 },
+      { rid: "h", scaleResolutionDownBy: 2, scalabilityMode: "L1T3", maxBitrate: 875_000 },
+      { rid: "f", scaleResolutionDownBy: 1, scalabilityMode: "L1T3", maxBitrate: 3_500_000 },
+    ]);
+  });
+
+  it("still publishes ONE encoding when simulcast is not asked for", async () => {
+    // The small-call case: everybody can carry the one encoding, and layers
+    // nobody consumes are encoder time spent on nobody.
+    const server = nodeWith({ producers: [] });
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(server, recorded);
+    await room.connect();
+    const track = { kind: "video", stop: vi.fn(), addEventListener: vi.fn(), removeEventListener: vi.fn() } as unknown as MediaStreamTrack;
+
+    await room.publish(track, "camera", { maxBitrateKbps: 1200 });
+
+    const produced = recorded.transports.find((t) => t.direction === "send")!.produced[0]!;
+    expect(produced.encodings).toEqual([{ maxBitrate: 1_200_000 }]);
+  });
+
+  it("refuses a track of the other kind and an unknown publication", async () => {
+    const server = nodeWith({ producers: [] });
+    const room = roomFor(server, { calls: [], transports: [] });
+    await room.connect();
+    const video = { kind: "video", stop: vi.fn(), addEventListener: vi.fn(), removeEventListener: vi.fn() } as unknown as MediaStreamTrack;
+    const audio = { kind: "audio", stop: vi.fn(), addEventListener: vi.fn(), removeEventListener: vi.fn() } as unknown as MediaStreamTrack;
+    const published = await room.publish(video, "camera");
+    await expect(room.replaceTrack(published.producerId, audio)).rejects.toThrow(/cannot carry/);
+    await expect(room.replaceTrack("nope", video)).rejects.toThrow(/no such publication/);
+  });
+});
+
+/**
+ * A node whose consume replies echo the producer's REAL kind, so viewport
+ * tests get video consumers where the fixture above answers "audio" for
+ * everything.
+ */
+function kindAwareNode(input: {
+  producers: { producerId: string; identity: string; kind: "audio" | "video"; source?: string }[];
+  refuse?: (method: string) => boolean;
+}): FakeSignalServer {
+  let transportSeq = 0;
+  let consumerSeq = 0;
+  const kinds = new Map(input.producers.map((p) => [p.producerId, p.kind]));
+  const server: FakeSignalServer = new FakeSignalServer({
+    joined: {
+      identity: "me",
+      room: "matter-1",
+      routerRtpCapabilities: { codecs: [] },
+      producers: input.producers,
+      grants: { canPublish: true, canSubscribe: true, canPublishData: true },
+    },
+    onRequest: (frame, socket) => {
+      if (input.refuse?.(frame.method)) return server.fail(frame.id, "bad_request", "unknown method", socket);
+      switch (frame.method) {
+        case "createTransport":
+          return server.reply(
+            frame.id,
+            { transportId: `t-${transportSeq++}`, iceParameters: {}, iceCandidates: [], dtlsParameters: {} },
+            socket,
+          );
+        case "connectTransport":
+          return server.reply(frame.id, { connected: true }, socket);
+        case "consume":
+          return server.reply(
+            frame.id,
+            {
+              consumerId: `c-${consumerSeq++}`,
+              producerId: frame.producerId,
+              kind: kinds.get(frame.producerId) ?? "audio",
+              rtpParameters: {},
+            },
+            socket,
+          );
+        default:
+          return server.reply(frame.id, {}, socket);
+      }
+    },
+  });
+  return server;
+}
+
+const GRID = [
+  { producerId: "a-1", identity: "a", kind: "audio" as const },
+  { producerId: "v-1", identity: "a", kind: "video" as const },
+  { producerId: "v-2", identity: "b", kind: "video" as const },
+  { producerId: "v-3", identity: "c", kind: "video" as const },
+];
+const GRID_SET: EventFrame = {
+  event: "activeSpeakers",
+  producerIds: ["a-1", "v-1", "v-2", "v-3"],
+  audio: ["a-1"],
+  video: ["v-1", "v-2", "v-3"],
+};
+
+const viewportRoom = (server: FakeSignalServer, recorded: Recorded, graceMs = 150) =>
+  new MediaRoom({
+    getCredentials: () => ({ mediaUrl: "wss://media.example", token: "t" }),
+    device: () => fakeDevice(recorded),
+    webSocket: server.factory,
+    viewportCloseGraceMs: graceMs,
+  });
+
+describe("viewport narrowing (capacity layer 2)", () => {
+  it("subscribes video to the viewport's intersection with the set, and audio to ALL of it", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: GRID });
+    const room = viewportRoom(server, recorded);
+    await room.connect();
+
+    room.setViewport([{ producerId: "v-1", widthPx: 320 }]);
+    server.event(GRID_SET);
+    await vi.waitFor(() => expect(requestsOf(server, "consume")).toHaveLength(2));
+
+    // v-2 and v-3 are in the set and NOT consumed; a-1 is consumed although
+    // no viewport entry names it. Audio never narrows by viewport.
+    expect(
+      requestsOf(server, "consume")
+        .map((r) => (r as { producerId: string }).producerId)
+        .sort(),
+    ).toEqual(["a-1", "v-1"]);
+    await room.close();
+  });
+
+  it("keeps every audio consumer on an EMPTY viewport (a hidden tab hears the call)", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: GRID });
+    const room = viewportRoom(server, recorded, 100);
+    await room.connect();
+    server.event(GRID_SET);
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(4));
+
+    room.setViewport([]);
+    // Paused at once, closed after the grace; the audio consumer stays.
+    await vi.waitFor(() => expect(requestsOf(server, "closeConsumer")).toHaveLength(3));
+    expect(room.tracks.map((t) => t.producerId)).toEqual(["a-1"]);
+    expect(requestsOf(server, "pauseConsumer")).toHaveLength(3);
+    await room.close();
+  });
+
+  it("never narrows without a viewport: the legacy full-set behavior stands", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: GRID });
+    const room = viewportRoom(server, recorded);
+    await room.connect();
+    server.event(GRID_SET);
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(4));
+    expect(requestsOf(server, "pauseConsumer")).toHaveLength(0);
+    await room.close();
+  });
+
+  it("pauses immediately, and a flip back inside the grace resumes with a keyframe and NO new consume", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: GRID });
+    const room = viewportRoom(server, recorded, 60_000);
+    await room.connect();
+    room.setViewport([
+      { producerId: "v-1", widthPx: 320 },
+      { producerId: "v-2", widthPx: 320 },
+    ]);
+    server.event(GRID_SET);
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(3));
+    const consumesBefore = requestsOf(server, "consume").length;
+
+    // Page flip: v-2 scrolls off...
+    room.setViewport([{ producerId: "v-1", widthPx: 320 }]);
+    await vi.waitFor(() => expect(requestsOf(server, "pauseConsumer")).toHaveLength(1));
+    expect(requestsOf(server, "closeConsumer")).toHaveLength(0);
+
+    // ...and back, inside the generous grace.
+    room.setViewport([
+      { producerId: "v-1", widthPx: 320 },
+      { producerId: "v-2", widthPx: 320 },
+    ]);
+    await vi.waitFor(() => expect(requestsOf(server, "resumeConsumer").length).toBeGreaterThanOrEqual(4));
+    // A resumed video consumer shows garbage until an I-frame, so one is asked for.
+    expect(requestsOf(server, "requestKeyFrame")).toHaveLength(1);
+    expect(requestsOf(server, "consume")).toHaveLength(consumesBefore);
+    await room.close();
+  });
+
+  it("asks for the layer the tile width implies on consume, and switches on a bucket change without closing", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: GRID });
+    const room = viewportRoom(server, recorded);
+    await room.connect();
+    room.setViewport([{ producerId: "v-1", widthPx: 200 }]);
+    server.event(GRID_SET);
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(2));
+
+    const consume = requestsOf(server, "consume").find((r) => (r as { producerId: string }).producerId === "v-1");
+    expect((consume as { preferredLayers?: unknown }).preferredLayers).toEqual({ spatialLayer: 0 });
+
+    // A resize inside the bucket says nothing; crossing a boundary speaks once.
+    room.setViewport([{ producerId: "v-1", widthPx: 230 }]);
+    room.setViewport([{ producerId: "v-1", widthPx: 700 }]);
+    await vi.waitFor(() => expect(requestsOf(server, "setPreferredLayers")).toHaveLength(1));
+    expect(requestsOf(server, "setPreferredLayers")[0]).toMatchObject({ consumerId: expect.any(String), spatialLayer: 2 });
+    expect(requestsOf(server, "closeConsumer")).toHaveLength(0);
+    await room.close();
+  });
+
+  it("disables a verb an OLD node refuses instead of retrying into the frame budget", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: GRID, refuse: (method) => method === "pauseConsumer" });
+    const room = viewportRoom(server, recorded, 60_000);
+    await room.connect();
+    room.setViewport([{ producerId: "v-1", widthPx: 320 }, { producerId: "v-2", widthPx: 320 }]);
+    server.event(GRID_SET);
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(3));
+
+    room.setViewport([{ producerId: "v-2", widthPx: 320 }]);
+    await vi.waitFor(() => expect(requestsOf(server, "pauseConsumer")).toHaveLength(1));
+    // A second narrow does not ask again: the verb is off for the session.
+    room.setViewport([]);
+    await new Promise((r) => setTimeout(r, 250));
+    expect(requestsOf(server, "pauseConsumer")).toHaveLength(1);
+    await room.close();
+  });
+});
+
+describe("ephemeral signals: reactions and hands", () => {
+  it("sends a reaction and hears one back through onBroadcast", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: [] });
+    const room = viewportRoom(server, recorded);
+    const heard: unknown[] = [];
+    room.onBroadcast((event) => heard.push(event));
+    await room.connect();
+
+    await room.sendReaction({ emoji: "clap" });
+    expect(requestsOf(server, "broadcast")[0]).toMatchObject({ type: "reaction", data: { emoji: "clap" } });
+
+    server.event({ event: "broadcast", type: "reaction", identity: "peer-1", data: { emoji: "clap" }, at: 5 });
+    await flush();
+    expect(heard).toEqual([{ type: "reaction", identity: "peer-1", data: { emoji: "clap" }, at: 5 }]);
+    // Ephemeral means ephemeral: nothing about it lands in RoomState.
+    expect(room.state.raisedHands).toEqual([]);
+    await room.close();
+  });
+
+  it("raises a hand over the wire and renders hands from room STATE", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: [] });
+    const room = viewportRoom(server, recorded);
+    await room.connect();
+
+    await room.setHandRaised(true);
+    expect(requestsOf(server, "setHand")[0]).toMatchObject({ raised: true });
+
+    server.event({ event: "handChanged", identity: "peer-1", raisedAt: 100 });
+    server.event({ event: "handChanged", identity: "peer-0", raisedAt: 200 });
+    await flush();
+    // Oldest first: the order is the queue, not the alphabet.
+    expect(room.state.raisedHands).toEqual([
+      { identity: "peer-1", raisedAt: 100 },
+      { identity: "peer-0", raisedAt: 200 },
+    ]);
+
+    server.event({ event: "handChanged", identity: "peer-1", raisedAt: null });
+    await flush();
+    expect(room.state.raisedHands).toEqual([{ identity: "peer-0", raisedAt: 200 }]);
+    await room.close();
+  });
+
+  it("sends lowerHand as a courtesy broadcast, never as state", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: [] });
+    const room = viewportRoom(server, recorded);
+    await room.connect();
+    await room.sendLowerHand("peer-1");
+    expect(requestsOf(server, "broadcast")[0]).toMatchObject({ type: "lowerHand", data: { target: "peer-1" } });
+    await room.close();
+  });
+});
+
+describe("the simulcast/h264 exclusivity is enforced", () => {
+  it("drops simulcast for an h264 publish rather than sending layers that will not exist", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = kindAwareNode({ producers: [] });
+    const warnings: string[] = [];
+    const room = new MediaRoom({
+      getCredentials: () => ({ mediaUrl: "wss://media.example", token: "t" }),
+      device: () => fakeDevice(recorded),
+      webSocket: server.factory,
+      onLog: (level, message) => {
+        if (level === "warn") warnings.push(message);
+      },
+    });
+    await room.connect();
+
+    await room.publish(track(), "program", { simulcast: true, codec: "h264", maxBitrateKbps: 2500 });
+    const produced = recorded.transports.find((t) => t.direction === "send")!.produced[0]!;
+    expect(produced.codec).toBe("h264");
+    // ONE encoding, capped: the simulcast layers were dropped, loudly.
+    expect(produced.encodings).toEqual([{ maxBitrate: 2_500_000 }]);
+    expect(warnings.join(" ")).toMatch(/simulcast dropped/);
+    await room.close();
+  });
+});
+
+describe("the planned move: a drain is a migration, not a drop", () => {
+  /** A capture whose liveness the stash can read; `track()` has no readyState. */
+  const liveTrack = (kind: "audio" | "video" = "audio") =>
+    ({ kind, readyState: "live", stop: vi.fn() }) as unknown as MediaStreamTrack & { stop: ReturnType<typeof vi.fn> };
+
+  const movingRoom = (server: FakeSignalServer, recorded: Recorded) => {
+    const tickets: string[] = [];
+    const room = new MediaRoom({
+      getCredentials: () => {
+        tickets.push(`t-${tickets.length}`);
+        return { mediaUrl: "wss://media.example", token: tickets[tickets.length - 1]! };
+      },
+      device: () => fakeDevice(recorded),
+      webSocket: server.factory,
+      autoSubscribe: false,
+      reconnect: { baseMs: 1, maxMs: 4, factor: 1, jitter: "none", drainingRefusalFloorMs: 5 },
+    });
+    return { room, tickets };
+  };
+
+  it("moves at the hinted delay: leaves the old node, rejoins with a fresh ticket, republishes the SAME captures", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room, tickets } = movingRoom(server, recorded);
+    await room.connect();
+
+    const mic = liveTrack("audio");
+    await room.publish(mic, "microphone", { maxBitrateKbps: 64 });
+    const published = room.localPublications[0]!;
+    await room.setPaused(published.producerId, true);
+
+    server.event({ event: "draining", reconnectAfterMs: 30 });
+    // The call continues untouched during the jittered wait.
+    expect(room.connectionState).toBe("connected");
+    expect(mic.stop).not.toHaveBeenCalled();
+
+    await vi.waitFor(() => expect(tickets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+
+    // The old node was LEFT, not abandoned: the leave request is what tears
+    // our record down before the rejoin can meet its own ghost.
+    expect(requestsOf(server, "leave").length).toBe(1);
+    // The capture never stopped, and the republish carried the same source,
+    // the same options, and the same paused state.
+    expect(mic.stop).not.toHaveBeenCalled();
+    await vi.waitFor(() => expect(room.localPublications).toHaveLength(1));
+    expect(room.localPublications[0]).toMatchObject({ source: "microphone", paused: true });
+    const produces = requestsOf(server, "produce");
+    expect(produces).toHaveLength(2);
+    expect(requestsOf(server, "pauseProducer").length).toBeGreaterThanOrEqual(2);
+    // Nothing was "lost": the person is never asked to re-enable anything.
+    expect(room.lostPublicationSources).toEqual([]);
+    await room.close();
+  });
+
+  it("ignores a second draining frame: one move, however many times the node asks", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room, tickets } = movingRoom(server, recorded);
+    await room.connect();
+
+    server.event({ event: "draining", reconnectAfterMs: 40 });
+    server.event({ event: "draining", reconnectAfterMs: 1 });
+    await vi.waitFor(() => expect(tickets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    await settleMs(60);
+
+    // Had the second frame booked its own move, a third ticket would exist.
+    expect(tickets.length).toBe(2);
+    await room.close();
+  });
+
+  it("keeps the smooth path when the server CUTS at the deadline, honoring the jittered hint", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room, tickets } = movingRoom(server, recorded);
+    await room.connect();
+    const camera = liveTrack("video");
+    await room.publish(camera, "camera");
+
+    // The deadline eviction: the frame and the close arrive together.
+    const before = Date.now();
+    server.event({ event: "draining", reconnectAfterMs: 60 });
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(tickets.length).toBe(2));
+    // The first attempt waited the server's hint (not the backoff ladder).
+    expect(Date.now() - before).toBeGreaterThanOrEqual(55);
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    expect(camera.stop).not.toHaveBeenCalled();
+    await vi.waitFor(() => expect(room.localPublications).toHaveLength(1));
+    await room.close();
+  });
+
+  it("hands a capture that ENDED during the move to the lost-sources offer instead of publishing a dead track", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = movingRoom(server, recorded);
+    await room.connect();
+    const mic = liveTrack("audio");
+    await room.publish(mic, "microphone");
+
+    server.event({ event: "draining", reconnectAfterMs: 10 });
+    (mic as unknown as { readyState: string }).readyState = "ended";
+
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    await vi.waitFor(() => expect(room.lostPublicationSources).toEqual(["microphone"]));
+    expect(room.localPublications).toHaveLength(0);
+    await room.close();
+  });
+
+  it("cancels a scheduled move when the room ENDS first: the ordinary path owns the close", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room, tickets } = movingRoom(server, recorded);
+    await room.connect();
+    const mic = liveTrack("audio");
+    await room.publish(mic, "microphone");
+
+    // A move is booked, and then the HOST ends the call before it fires.
+    // (A close after a draining frame reports the draining cause and takes
+    // the smooth path by design; roomClosed is what overrides it.)
+    server.event({ event: "draining", reconnectAfterMs: 5_000 });
+    server.event({ event: "roomClosed", reason: "the host ended it" });
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(room.connectionState).toBe("reconnecting"));
+    expect(room.isRecovering).toBe(false);
+    // Ordinary end-of-call semantics exactly: the capture is stopped, and
+    // the cancelled move never books a rejoin into a finished room.
+    expect(mic.stop).toHaveBeenCalled();
+    await settleMs(30);
+    expect(tickets.length).toBe(1);
+    expect(server.sockets.length).toBe(1);
+    await room.close();
+  });
+
+  it("waits out a restarting single node: patient node_draining probes, then rejoin WITH the captures", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    // The standalone topology: MEDIA_URL is the one node, and during its
+    // restart every join is refused node_draining. The ladder must not burn
+    // out against a node that was always going to come back.
+    let refusals = 0;
+    let seq = 0;
+    const server: FakeSignalServer = new FakeSignalServer({
+      autoJoin: false,
+      onRequest: (frame, socket) => {
+        if (frame.method === "join") {
+          if (refusals > 0) {
+            refusals -= 1;
+            server.fail(frame.id, "node_draining", "restarting", socket);
+            return;
+          }
+          server.completeJoin(socket, frame.id);
+          return;
+        }
+        if (frame.method === "createTransport") {
+          server.reply(
+            frame.id,
+            { transportId: `t-${seq++}`, iceParameters: {}, iceCandidates: [], dtlsParameters: {} },
+            socket,
+          );
+          return;
+        }
+        if (frame.method === "produce") {
+          server.reply(frame.id, { producerId: `p-${seq++}` }, socket);
+          return;
+        }
+        server.reply(frame.id, {}, socket);
+      },
+    });
+    const { room, tickets } = movingRoom(server, recorded);
+    await room.connect();
+    const mic = liveTrack("audio");
+    await room.publish(mic, "microphone");
+
+    // The node announces the restart, then refuses the rejoins for a while.
+    refusals = 3;
+    server.event({ event: "draining", reconnectAfterMs: 5 });
+
+    // Refusal, refusal, refusal, success: four join tickets after the first.
+    await vi.waitFor(() => expect(tickets.length).toBe(5), { timeout: 3_000 });
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    expect(refusals).toBe(0);
+    // The whole wait happened with the captures alive; the rejoin brought
+    // them back without anybody pressing anything.
+    expect(mic.stop).not.toHaveBeenCalled();
+    await vi.waitFor(() => expect(room.localPublications).toHaveLength(1));
+    expect(room.lostPublicationSources).toEqual([]);
+    await room.close();
+  });
+
+  it("stashes at CLOSE time, so a mute during the leave round trip survives the move", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    let heldLeave: { id: number; socket: FakeSocket } | undefined;
+    const server = nodeWith({
+      intercept: (frame, socket) => {
+        // Hold the leave reply open: this is the window in which the person
+        // can still change what they are sending.
+        if (frame.method === "leave" && !heldLeave) {
+          heldLeave = { id: frame.id, socket };
+          return true;
+        }
+        return false;
+      },
+    });
+    const { room } = movingRoom(server, recorded);
+    await room.connect();
+    const mic = liveTrack("audio");
+    const published = await room.publish(mic, "microphone");
+
+    server.event({ event: "draining", reconnectAfterMs: 5 });
+    await vi.waitFor(() => expect(heldLeave).toBeDefined());
+
+    // Mid-window: the mic is muted and a SECOND capture starts.
+    await room.setPaused(published.producerId, true);
+    const camera = liveTrack("video");
+    await room.publish(camera, "camera");
+    server.reply(heldLeave!.id, {}, heldLeave!.socket);
+
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    await vi.waitFor(() => expect(room.localPublications).toHaveLength(2));
+    // The muted state and the late capture both crossed: no hot mic on the
+    // new node, no orphaned camera with its light on. (The republished pause
+    // lands one round trip after the produce, hence the wait.)
+    await vi.waitFor(() =>
+      expect(room.localPublications.find((p) => p.source === "microphone")?.paused).toBe(true),
+    );
+    expect(room.localPublications.find((p) => p.source === "camera")).toBeDefined();
+    expect(camera.stop).not.toHaveBeenCalled();
+    expect(room.lostPublicationSources).toEqual([]);
+    await room.close();
+  });
+
+  it("never says 'connecting' during a move: the person is mid-call, the word is 'reconnecting'", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = movingRoom(server, recorded);
+    await room.connect();
+
+    const states: string[] = [];
+    const stop = room.onChange(() => states.push(room.connectionState));
+    server.event({ event: "draining", reconnectAfterMs: 5 });
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    await vi.waitFor(() => expect(states).toContain("reconnecting"));
+
+    expect(states).not.toContain("connecting");
+    stop();
+    await room.close();
+  });
+
+  it("still MOVES a room whose failure recovery is off: a drain is an order, not a failure", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const tickets: string[] = [];
+    const room = new MediaRoom({
+      getCredentials: () => {
+        tickets.push(`t-${tickets.length}`);
+        return { mediaUrl: "wss://media.example", token: tickets[tickets.length - 1]! };
+      },
+      device: () => fakeDevice(recorded),
+      webSocket: server.factory,
+      autoSubscribe: false,
+      reconnect: { maxAttempts: 0 },
+    });
+    await room.connect();
+
+    server.event({ event: "draining", reconnectAfterMs: 5 });
+    await vi.waitFor(() => expect(tickets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+
+    // The move happened; a later ORDINARY drop still gets no automatic retry.
+    server.socket.dropFromServer(1006);
+    await vi.waitFor(() => expect(room.connectionState).toBe("reconnecting"));
+    expect(room.isRecovering).toBe(false);
+    await settleMs(30);
+    expect(tickets.length).toBe(2);
+    await room.close();
+  });
+
+  it("reports a move that dies for good AS a failed move, not as the refusal that ended it", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    let joins = 0;
+    const server: FakeSignalServer = new FakeSignalServer({
+      autoJoin: false,
+      onRequest: (frame, socket) => {
+        if (frame.method === "join") {
+          joins += 1;
+          if (joins > 1) {
+            server.fail(frame.id, "capacity", "the fleet is full", socket);
+            return;
+          }
+          server.completeJoin(socket, frame.id);
+          return;
+        }
+        server.reply(frame.id, {}, socket);
+      },
+    });
+    const room = new MediaRoom({
+      getCredentials: () => ({ mediaUrl: "wss://media.example", token: "t" }),
+      device: () => fakeDevice(recorded),
+      webSocket: server.factory,
+      autoSubscribe: false,
+      // Failure recovery OFF: the one refused rejoin ends the move for good.
+      reconnect: { maxAttempts: 0 },
+    });
+    await room.connect();
+
+    server.event({ event: "draining", reconnectAfterMs: 5 });
+    await vi.waitFor(() => expect(joins).toBe(2));
+    await vi.waitFor(() => expect(room.isRecovering).toBe(false));
+
+    // The screen's story is "could not move you", with a way back, because
+    // that is what happened to the PERSON; the capacity refusal is a detail.
+    expect(room.connectionState).toBe("reconnecting");
+    expect(room.error).toMatchObject({ type: "draining" });
+    await room.close();
+  });
+
+  it("stops the stashed captures when the recovery gives up for good: a light never outlives its migration", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = movingRoom(server, recorded);
+    await room.connect();
+    const mic = liveTrack("audio");
+    await room.publish(mic, "microphone");
+
+    // Move, then make every rejoin fail terminally: the room is closed by the
+    // person, which is the one unambiguous "stop everything".
+    server.event({ event: "draining", reconnectAfterMs: 5 });
+    await vi.waitFor(() => expect(requestsOf(server, "leave").length).toBe(1));
+    await room.close();
+
+    expect(mic.stop).toHaveBeenCalled();
+    expect(room.connectionState).toBe("closed");
+  });
+});
+
+/** Real-timer settle for paths whose timers are a few ms. */
+const settleMs = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+describe("getDiagnostics: the call explained without webrtc-internals", () => {
+  const nodeAnswer = {
+    transports: [{ transportId: "t-1", availableOutgoingBitrate: 600_000, iceState: "connected", dtlsState: "connected" }],
+    producers: [
+      {
+        producerId: "p-mine",
+        kind: "video",
+        paused: false,
+        source: "camera",
+        layers: [
+          { rid: "q", score: 10 },
+          { rid: "h", score: 7 },
+          { rid: "f", score: 0 },
+        ],
+      },
+    ],
+    consumers: [
+      {
+        consumerId: "c-1",
+        producerId: "p-1",
+        kind: "video",
+        paused: false,
+        preferredLayers: { spatialLayer: 2, temporalLayer: 2 },
+        currentLayers: { spatialLayer: 0, temporalLayer: 0 },
+      },
+    ],
+  };
+
+  it("merges the node's answer into the tiles: asked, given, decoded, all in one place", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [{ producerId: "p-1", identity: "a", kind: "video", source: "camera" }],
+      intercept: (frame, socket, srv) => {
+        if (frame.method !== "diagnostics") return false;
+        srv.reply(frame.id, nodeAnswer, socket);
+        return true;
+      },
+    });
+    const room = roomFor(server, recorded);
+    await room.connect();
+    room.setViewport([{ producerId: "p-1", widthPx: 900 }]);
+    server.event({ event: "activeSpeakers", producerIds: ["p-1"] });
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(1));
+
+    const first = await room.getDiagnostics();
+    const tile = first.tiles[0]!;
+    // The three-way answer on one line: this client asked full (900px tile),
+    // the node is giving quarter, and the estimate names the culprit.
+    expect(tile).toMatchObject({
+      producerId: "p-1",
+      identity: "a",
+      source: "camera",
+      requestedLayer: 2,
+      currentLayer: 0,
+      viewportWidthPx: 900,
+      frameWidth: 320,
+      frameHeight: 180,
+      framesPerSecond: 24,
+    });
+    expect(first.availableOutgoingBitrate).toBe(600_000);
+    // The publisher-side half: my own camera's f layer is not arriving.
+    expect(first.localProducers?.[0]?.layers).toEqual([
+      { rid: "q", score: 10 },
+      { rid: "h", score: 7 },
+      { rid: "f", score: 0 },
+    ]);
+    // Bitrate needs a delta, so the FIRST read has none and the second does.
+    expect(tile.bitrateKbps).toBeUndefined();
+    await settleMs(15);
+    const second = await room.getDiagnostics();
+    expect(second.tiles[0]?.bitrateKbps).toBeGreaterThan(0);
+    await room.close();
+  });
+
+  it("still answers the LOCAL half against a node too old for the verb", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [{ producerId: "p-1", identity: "a", kind: "video" }],
+      intercept: (frame, socket, srv) => {
+        if (frame.method !== "diagnostics") return false;
+        srv.fail(frame.id, "bad_request", "unknown method", socket);
+        return true;
+      },
+    });
+    const room = roomFor(server, recorded);
+    await room.connect();
+    room.setViewport([{ producerId: "p-1", widthPx: 200 }]);
+    server.event({ event: "activeSpeakers", producerIds: ["p-1"] });
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(1));
+
+    const diagnostics = await room.getDiagnostics();
+    expect(diagnostics.tiles[0]).toMatchObject({ producerId: "p-1", requestedLayer: 0, frameWidth: 320 });
+    expect(diagnostics.availableOutgoingBitrate).toBeUndefined();
+    expect(diagnostics.node).toBeUndefined();
+
+    // And the verb is remembered as unsupported: no second ask.
+    await room.getDiagnostics();
+    expect(requestsOf(server, "diagnostics")).toHaveLength(1);
+    await room.close();
+  });
+});