@tribe-nest/media-client 0.1.0 → 0.2.1

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

@@ -1,7 +1,9 @@
+import { MediaError, type EventFrame, type RequestFrame } from "@tribe-nest/media-protocol";
 import { describe, expect, it, vi } from "vitest";
 
-import { FakeSignalServer, flush } from "../../core/_tests/fakeSignalServer";
-import { MediaRoom } from "../room";
+import type { DisconnectCause } from "../../core";
+import { FakeSignalServer, flush, type FakeSocket } from "../../core/_tests/fakeSignalServer";
+import { MediaRoom, type ConnectionState } from "../room";
 import type {
   IceServer,
   MediaConsumerHandle,
@@ -24,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> = {};
@@ -35,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.
@@ -53,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,
     };
   }
 
@@ -93,7 +118,14 @@ function fakeDevice(recorded: Recorded) {
       return { codecs: [] } as never;
     },
     canProduce: () => true,
-    createSendTransport({ description, handlers }: { description: TransportDescription; iceServers: IceServer[]; handlers: TransportHandlers }) {
+    createSendTransport({
+      description,
+      handlers,
+    }: {
+      description: TransportDescription;
+      iceServers: IceServer[];
+      handlers: TransportHandlers;
+    }) {
       const transport = new FakeTransport(description.transportId, "send", recorded);
       transport.handlers = handlers;
       recorded.transports.push(transport);
@@ -118,14 +150,24 @@ 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
+   * `joined` snapshot. The contract fixes no order between `joined` and the
+   * node's first broadcasts, and a real node sends its active set the moment a
+   * participant is in the room.
+   */
+  beforeJoined?: EventFrame[];
+  /** Answers a request itself by returning true; anything else falls through to the defaults. */
+  intercept?: (frame: RequestFrame, socket: FakeSocket, server: FakeSignalServer) => boolean;
 }): FakeSignalServer {
   let transportSeq = 0;
   let producerSeq = 0;
   let consumerSeq = 0;
 
   const server: FakeSignalServer = new FakeSignalServer({
+    ...(input.beforeJoined ? { autoJoin: false } : {}),
     joined: {
       identity: "me",
       room: "matter-1",
@@ -135,6 +177,7 @@ function nodeWith(input: {
       grants: { canPublish: true, canSubscribe: true, canPublishData: false },
     },
     onRequest: (frame, socket) => {
+      if (input.intercept?.(frame, socket, server)) return;
       switch (frame.method) {
         case "createTransport":
           return server.reply(
@@ -153,6 +196,11 @@ function nodeWith(input: {
             socket,
           );
         case "join":
+          if (input.beforeJoined) {
+            server.reply(frame.id, { accepted: true }, socket);
+            for (const event of input.beforeJoined) server.event(event, socket);
+            server.event(server.joinedFrame(), socket);
+          }
           return;
         default:
           return server.reply(frame.id, {}, socket);
@@ -203,7 +251,8 @@ const recoveringRoom = (
   return { room, tickets };
 };
 
-const track = () => ({ kind: "audio", stop: vi.fn() }) as unknown as MediaStreamTrack & { stop: ReturnType<typeof vi.fn> };
+const track = () =>
+  ({ kind: "audio", stop: vi.fn() }) as unknown as MediaStreamTrack & { stop: ReturnType<typeof vi.fn> };
 
 describe("rule 1: the device loads before anything needs its capabilities", () => {
   it("loads on join, before any transport", async () => {
@@ -257,6 +306,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({
@@ -274,6 +356,92 @@ describe("rule 2: one transport per direction, created lazily", () => {
     expect(recorded.calls.filter((c) => c === "create-recv-transport")).toHaveLength(1);
     await room.close();
   });
+
+  /**
+   * "Once" under CONCURRENCY, which is the shape that actually occurs.
+   *
+   * `syncSubscriptions` fans out with `Promise.all`, so one `activeSpeakers`
+   * frame naming four producers puts four subscribes through
+   * `ensureRecvTransport` in the same tick. Checking the finished transport and
+   * then awaiting the round trip let every one of them pass the check and send
+   * its own `createTransport(recv)`. The node caps transports per session, so
+   * the burst spent the whole allowance on duplicates and the person's own
+   * Unmute was refused with `capacity` for the rest of the call.
+   */
+  it("sends ONE createTransport per direction when several subscribes and publishes land in the same tick", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [
+        { producerId: "p-a", identity: "a", kind: "audio" },
+        { producerId: "p-b", identity: "b", kind: "audio" },
+      ],
+    });
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    // Fired, not awaited in turn: all four are in flight before any reply.
+    await Promise.all([
+      room.subscribe("p-a"),
+      room.subscribe("p-b"),
+      room.publish({ kind: "audio", stop: vi.fn() } as never, "microphone"),
+      room.publish({ kind: "video", stop: vi.fn() } as never, "camera"),
+    ]);
+
+    // Asserted on the WIRE, because that is what the node counts.
+    const created = requestsOf(server, "createTransport") as { direction: "send" | "recv" }[];
+    expect(created.filter((r) => r.direction === "recv")).toHaveLength(1);
+    expect(created.filter((r) => r.direction === "send")).toHaveLength(1);
+    expect(recorded.calls.filter((c) => c === "create-recv-transport")).toHaveLength(1);
+    expect(recorded.calls.filter((c) => c === "create-send-transport")).toHaveLength(1);
+    // And everything still landed on the one transport per direction.
+    expect(room.tracks.map((t) => t.producerId).sort()).toEqual(["p-a", "p-b"]);
+    expect(room.localPublications).toHaveLength(2);
+    await room.close();
+  });
+
+  it("sends ONE createTransport(recv) for an activeSpeakers frame naming several producers", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const producers = ["p-1", "p-2", "p-3", "p-4"].map((producerId) => ({
+      producerId,
+      identity: producerId,
+      kind: "audio" as const,
+    }));
+    const server = nodeWith({ producers });
+    const room = roomFor(server, recorded);
+    await room.connect();
+
+    server.event({ event: "activeSpeakers", producerIds: producers.map((p) => p.producerId) });
+    await vi.waitFor(() => expect(room.tracks).toHaveLength(4));
+
+    expect(requestsOf(server, "createTransport")).toHaveLength(1);
+    await room.close();
+  });
+
+  it("forgets a creation the node refused, so the next caller tries again", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    let refuseNext = true;
+    const server = nodeWith({
+      producers: [{ producerId: "p-a", identity: "a", kind: "audio" }],
+      intercept: (frame, socket, srv) => {
+        if (frame.method !== "createTransport" || !refuseNext) return false;
+        refuseNext = false;
+        srv.fail(frame.id, "capacity", "no", socket);
+        return true;
+      },
+    });
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    await expect(room.subscribe("p-a")).rejects.toMatchObject({ code: "capacity" });
+    // A memo that kept the rejection would refuse every later subscribe with
+    // the same stale answer, when the node might well say yes now.
+    await room.subscribe("p-a");
+
+    expect(requestsOf(server, "createTransport")).toHaveLength(2);
+    expect(recorded.calls.filter((c) => c === "create-recv-transport")).toHaveLength(1);
+    expect(room.tracks).toHaveLength(1);
+    await room.close();
+  });
 });
 
 describe("rule 3: a consumer resumes only after its track exists", () => {
@@ -309,6 +477,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: [] };
@@ -330,10 +540,11 @@ describe("rule 4: autoSubscribe follows the ACTIVE SET", () => {
 
     // Subscribing to everything would produce one `subscription_limit` refusal
     // per producer outside the set, and show nothing for the trouble.
-    expect(requestsOf(server, "consume").map((r) => (r as { producerId: string }).producerId).sort()).toEqual([
-      "p-1",
-      "p-3",
-    ]);
+    expect(
+      requestsOf(server, "consume")
+        .map((r) => (r as { producerId: string }).producerId)
+        .sort(),
+    ).toEqual(["p-1", "p-3"]);
     await room.close();
   });
 
@@ -408,6 +619,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.
  *
@@ -513,6 +771,146 @@ describe("the room gets itself back in", () => {
   });
 });
 
+/**
+ * A ticket the room could not get is a failed attempt, not a frozen one.
+ *
+ * `getCredentials` is a network round trip to the ticket endpoint, and it
+ * fails for ordinary reasons: a 409 at the edge of the booking window because
+ * the client's clock is ahead, a 401 after the session expired, a flaky
+ * network. Before this, that rejection happened before a socket existed, so
+ * nothing ever closed, `onClose` never fired, and the room stayed on
+ * "connecting" (first join) or "reconnecting" (ladder) with no retry booked, no
+ * error to show and every later `connect()` refused as "already connecting".
+ * The screen above drew a spinner for the rest of the session.
+ */
+describe("a credential fetch that fails", () => {
+  /** A ticket endpoint that fails on the attempts named, and counts its calls. */
+  const ticketEndpoint = (failOn: number[], error: () => unknown = () => new Error("HTTP 409: window not open")) => {
+    let calls = 0;
+    return {
+      get calls() {
+        return calls;
+      },
+      getCredentials: async () => {
+        calls += 1;
+        if (failOn.includes(calls)) throw error();
+        return { mediaUrl: "wss://media.example", token: `t-${calls}` };
+      },
+    };
+  };
+
+  it("on the FIRST join surfaces the error and books a retry rather than wedging on connecting", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const tickets = ticketEndpoint([1]);
+    const { room } = recoveringRoom(server, recorded, { getCredentials: tickets.getCredentials });
+
+    await expect(room.connect()).rejects.toThrow(/HTTP 409/);
+
+    // Not "connecting": nothing is connecting. A retryable failure with a retry
+    // booked, and the cause on the room for the screen to show.
+    expect(room.connectionState).toBe("reconnecting");
+    expect(room.error).toEqual({ type: "socket_closed", reason: "HTTP 409: window not open" });
+    expect(room.isRecovering).toBe(true);
+    // No socket was ever opened for the failed attempt.
+    expect(server.sockets).toHaveLength(0);
+
+    // The booked retry fetches a FRESH ticket and gets in.
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    expect(tickets.calls).toBe(2);
+    expect(server.sockets).toHaveLength(1);
+    expect(room.error).toBeUndefined();
+    await room.close();
+  });
+
+  it("with retries off leaves the room retryable BY HAND rather than refusing the next connect", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const tickets = ticketEndpoint([1]);
+    const { room } = recoveringRoom(server, recorded, {
+      getCredentials: tickets.getCredentials,
+      reconnect: { maxAttempts: 0 },
+    });
+
+    await expect(room.connect()).rejects.toThrow(/HTTP 409/);
+    expect(room.connectionState).toBe("reconnecting");
+    expect(room.isRecovering).toBe(false);
+    expect(room.error).toMatchObject({ type: "socket_closed" });
+
+    // The person presses "Try again". Before the fix this was refused with
+    // "already connecting or connected" for the rest of the session.
+    await room.connect();
+
+    expect(room.connectionState).toBe("connected");
+    expect(room.error).toBeUndefined();
+    expect(tickets.calls).toBe(2);
+    await room.close();
+  });
+
+  it("on a LATER rung of the ladder is one failed attempt, and the ladder carries on", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const tickets = ticketEndpoint([2]);
+    const { room } = recoveringRoom(server, recorded, { getCredentials: tickets.getCredentials });
+    const seen: { connectionState: ConnectionState; error: DisconnectCause | undefined; recovering: boolean }[] = [];
+    room.onChange(() =>
+      seen.push({ connectionState: room.connectionState, error: room.error, recovering: room.isRecovering }),
+    );
+    await room.connect();
+
+    server.socket.dropFromServer();
+
+    await vi.waitFor(() => expect(server.sockets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    // Three tickets: the original, the one the endpoint refused, and the one
+    // that got back in.
+    expect(tickets.calls).toBe(3);
+    // While the endpoint was refusing, the room said so and said it was still
+    // trying, rather than sitting on the drop's cause with nothing booked.
+    expect(seen).toContainEqual({
+      connectionState: "reconnecting",
+      error: { type: "socket_closed", reason: "HTTP 409: window not open" },
+      recovering: true,
+    });
+    await room.close();
+  });
+
+  it("with a refusal the policy will not retry, shows the refusal and stops", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    // The endpoint saying "you may not join this room" is `refused`, and a
+    // terminal code is not retried: a loop against the ticket endpoint would
+    // only repeat the answer.
+    const tickets = ticketEndpoint([1, 2, 3], () => new MediaError("forbidden", "this seat is sealed"));
+    const { room } = recoveringRoom(server, recorded, { getCredentials: tickets.getCredentials });
+
+    await expect(room.connect()).rejects.toMatchObject({ code: "forbidden" });
+
+    expect(room.connectionState).toBe("reconnecting");
+    expect(room.isRecovering).toBe(false);
+    expect(room.error).toEqual({ type: "refused", code: "forbidden", message: "this seat is sealed" });
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(tickets.calls).toBe(1);
+    expect(server.sockets).toHaveLength(0);
+    await room.close();
+  });
+
+  it("does not put a live room back to connecting when connect() is called twice", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const room = roomFor(nodeWith({}), recorded, false);
+    await room.connect();
+
+    await expect(room.connect()).rejects.toThrow(/already connecting or connected/);
+
+    // The refusal is not a disconnect: the first connection is still up and the
+    // room has to keep saying so.
+    expect(room.connectionState).toBe("connected");
+    expect(room.error).toBeUndefined();
+    expect(room.state.phase).toBe("joined");
+    await room.close();
+  });
+});
+
 /**
  * The camera light goes out whenever the connection does.
  *
@@ -593,3 +991,340 @@ describe("what the room carries for rendering", () => {
     await room.close();
   });
 });
+
+/**
+ * A track that can end on its own, the way a browser's does.
+ *
+ * `MediaStreamTrack` is an `EventTarget`, and `ended` is what fires when the
+ * SOURCE goes away: the browser's own "Stop sharing" bar, a camera unplugged.
+ * It does not fire for our own `stop()`, which the fake also honours.
+ */
+const endableTrack = (kind: "audio" | "video" = "video") => {
+  const target = new EventTarget() as EventTarget & { kind: string; stop: ReturnType<typeof vi.fn> };
+  target.kind = kind;
+  target.stop = vi.fn();
+  return target as unknown as MediaStreamTrack & { stop: ReturnType<typeof vi.fn> };
+};
+
+/**
+ * The node's first active set can land BEFORE the join snapshot.
+ *
+ * The reducer used to reset `activeSpeakers` to `[]` on `joined`, so a set the
+ * node had already sent was discarded and the client consumed nothing until
+ * the next speaker change. In a quiet 1:1 call that change is the other person
+ * starting to talk, which is precisely when a missing subscription is noticed.
+ */
+describe("an active set that arrives ahead of joined", () => {
+  it("is applied once the room is in, rather than discarded", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({
+      producers: [{ producerId: "p-a", identity: "a", kind: "audio" }],
+      beforeJoined: [{ event: "activeSpeakers", producerIds: ["p-a"] }],
+    });
+    const room = roomFor(server, recorded);
+
+    await room.connect();
+
+    expect(room.state.activeSpeakers).toEqual(["p-a"]);
+    await vi.waitFor(() => expect(room.tracks.map((t) => t.producerId)).toEqual(["p-a"]));
+    await room.close();
+  });
+
+  it("does not carry a set from BEFORE a drop into the rejoin", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({ producers: [{ producerId: "p-a", identity: "a", kind: "audio" }] });
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+    server.event({ event: "activeSpeakers", producerIds: ["p-a"] });
+    await flush();
+    expect(room.state.activeSpeakers).toEqual(["p-a"]);
+
+    server.socket.dropFromServer();
+    await flush();
+    // Gone with the consumers it described. Kept, the next `joined` would read
+    // it as a set the NEW node had sent ahead of its snapshot.
+    expect(room.state.activeSpeakers).toEqual([]);
+
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    expect(room.state.activeSpeakers).toEqual([]);
+    await room.close();
+  });
+});
+
+/**
+ * Leave means leave, even while the node is asking to be left.
+ *
+ * `draining` is recorded as the terminal cause the moment the frame arrives,
+ * seconds before the node hangs up. A person who pressed Leave inside that
+ * window had their close reported as the DRAIN: the room went to
+ * "reconnecting", the policy declined because the room was disposed, and the
+ * screen read "Could not move you to another server" with a Try again, over a
+ * call they had just deliberately ended.
+ */
+describe("a close inside a drain window", () => {
+  it("is a client close, and the room stays closed", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+
+    server.event({ event: "draining", reconnectAfterMs: 5_000 });
+    await flush();
+    await room.close();
+
+    expect(room.connectionState).toBe("closed");
+    expect(room.error).toEqual({ type: "closed_by_client" });
+    expect(room.isRecovering).toBe(false);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(server.sockets).toHaveLength(1);
+  });
+});
+
+/**
+ * A recovered connection is not a recovered call: the microphone is off.
+ *
+ * The drop stops every local capture, and that is right (a camera light left
+ * on over a dead session is retained capture). What was wrong is that nothing
+ * then said so. The room came back, the screen read "Connected", the button
+ * read "Unmute", and a coach who had been talking for ten minutes was talking
+ * to nobody until the client asked whether they were still there. The room
+ * cannot republish by itself: capture is a browser permission, and turning a
+ * camera back on without a press is not this layer's decision. So it says what
+ * was lost, and stops saying it once each source is back.
+ */
+describe("publications lost to a drop", () => {
+  it("names what was being sent, and clears each source once it is republished", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+    expect(room.lostPublicationSources).toEqual([]);
+
+    await room.publish(track(), "microphone");
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "camera");
+    server.socket.dropFromServer();
+    await flush();
+    expect(room.connectionState).toBe("reconnecting");
+
+    await vi.waitFor(() => expect(server.sockets.length).toBe(2));
+    await vi.waitFor(() => expect(room.connectionState).toBe("connected"));
+    expect(room.localPublications).toHaveLength(0);
+    expect(room.lostPublicationSources).toEqual(["microphone", "camera"]);
+
+    // The person presses Unmute. The microphone is no longer lost; the camera is.
+    await room.publish(track(), "microphone");
+    expect(room.lostPublicationSources).toEqual(["camera"]);
+    await room.publish({ kind: "video", stop: vi.fn() } as never, "camera");
+    expect(room.lostPublicationSources).toEqual([]);
+    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({});
+    const { room } = recoveringRoom(server, recorded);
+    await room.connect();
+    await room.publish(track(), "microphone");
+
+    await room.close();
+
+    expect(room.lostPublicationSources).toEqual([]);
+  });
+});
+
+/**
+ * The browser can end a track without asking us.
+ *
+ * Chrome and Firefox draw their own "Stop sharing" bar over a screen share, and
+ * a camera can be unplugged. Neither goes anywhere near `unpublish`, so the
+ * node kept a producer nobody was feeding, every other participant kept a
+ * frozen tile for it, and the control above read "Stop sharing" about a share
+ * that had ended.
+ */
+describe("a track that ends on its own", () => {
+  it("is unpublished, and the node is told", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    const screen = endableTrack("video");
+    await room.publish(screen, "screen");
+    expect(room.localPublications).toHaveLength(1);
+
+    screen.dispatchEvent(new Event("ended"));
+
+    await vi.waitFor(() => expect(room.localPublications).toHaveLength(0));
+    expect(requestsOf(server, "closeProducer")).toHaveLength(1);
+    await room.close();
+  });
+
+  it("is not listened to after an ordinary unpublish or a teardown", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    const screen = endableTrack("video");
+    const publication = await room.publish(screen, "screen");
+    await room.unpublish(publication.producerId);
+    // Our own `stop()` does not fire `ended`; this is a source ending later,
+    // after the room has already let go of the track. Nothing must happen.
+    screen.dispatchEvent(new Event("ended"));
+    await flush();
+    expect(requestsOf(server, "closeProducer")).toHaveLength(1);
+
+    const camera = endableTrack("video");
+    await room.publish(camera, "camera");
+    await room.close();
+    camera.dispatchEvent(new Event("ended"));
+    await flush();
+    // Two: the ordinary unpublish above and nothing else. A watcher that
+    // outlived the teardown would have tried a third against a dead socket.
+    expect(requestsOf(server, "closeProducer")).toHaveLength(1);
+  });
+});
+
+/**
+ * Mute keeps the microphone; it does not give it back.
+ *
+ * A toggle built as unpublish-then-publish starts every unmute with
+ * `getUserMedia`, and Safari asks permission on EVERY call to it. So the room's
+ * pause is what a Mute button uses: the producer is paused, the node is told,
+ * the capture stays open, and the snapshot says which is which so a screen can
+ * draw a muted state without a second source of truth.
+ */
+describe("pausing a publication", () => {
+  it("keeps the capture and the producer, tells the node, and moves the snapshot", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+
+    const microphone = track();
+    const publication = await room.publish(microphone, "microphone");
+    const before = room.localPublications;
+    expect(before[0]?.paused).toBe(false);
+
+    await room.setPaused(publication.producerId, true);
+
+    expect(publication.handle.pause).toHaveBeenCalledTimes(1);
+    expect(microphone.stop).not.toHaveBeenCalled();
+    expect(requestsOf(server, "pauseProducer")).toHaveLength(1);
+    expect(requestsOf(server, "closeProducer")).toHaveLength(0);
+    // A NEW snapshot with the flag, so `useSyncExternalStore` sees the change.
+    expect(room.localPublications).not.toBe(before);
+    expect(room.localPublications[0]?.paused).toBe(true);
+    // And the way back asks nobody anything.
+    await room.setPaused(publication.producerId, false);
+    expect(publication.handle.resume).toHaveBeenCalledTimes(1);
+    expect(requestsOf(server, "resumeProducer")).toHaveLength(1);
+    expect(room.localPublications[0]?.paused).toBe(false);
+    await room.close();
+    // Leaving still releases the capture: pause is a mute, not a way of keeping
+    // a microphone open past the call.
+    expect(microphone.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it("is idempotent on the wire", async () => {
+    const recorded: Recorded = { calls: [], transports: [] };
+    const server = nodeWith({});
+    const room = roomFor(server, recorded, false);
+    await room.connect();
+    const publication = await room.publish(track(), "microphone");
+
+    await room.setPaused(publication.producerId, true);
+    await room.setPaused(publication.producerId, true);
+
+    expect(requestsOf(server, "pauseProducer")).toHaveLength(1);
+    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: "L1T1", maxBitrate: 350_000 },
+      { rid: "h", scaleResolutionDownBy: 2, scalabilityMode: "L1T1", maxBitrate: 875_000 },
+      { rid: "f", scaleResolutionDownBy: 1, scalabilityMode: "L1T1", 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/);
+  });
+});