@tribe-nest/media-client 0.2.1 → 0.4.0

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

@@ -85,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,
@@ -93,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) },
+      ],
     };
   }
 
@@ -1296,9 +1301,9 @@ describe("replaceTrack: a device switch keeps its producer", () => {
     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: "L1T1", maxBitrate: 350_000 },
-      { rid: "h", scaleResolutionDownBy: 2, scalabilityMode: "L1T1", maxBitrate: 875_000 },
-      { rid: "f", scaleResolutionDownBy: 1, scalabilityMode: "L1T1", maxBitrate: 3_500_000 },
+      { 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 },
     ]);
   });
 
@@ -1328,3 +1333,715 @@ describe("replaceTrack: a device switch keeps its producer", () => {
     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();
+  });
+});