@tribe-nest/forge 3.29.0 → 3.34.0

package/src/ui/media/_tests/callState.spec.ts

@@ -0,0 +1,499 @@
+import { describe, expect, it } from "vitest";
+
+import type { ProducerEntry } from "@tribe-nest/media-client";
+import type { Peer } from "@tribe-nest/media-protocol";
+
+import { FORGE_LOCALES, getForgeMessages, translateForge } from "../../../i18n";
+import { callHeadCount, callStatus, callTiles, canPublishSource, remoteAudioProducerIds } from "../callState";
+
+/**
+ * The two decisions a call screen gets wrong.
+ *
+ * Both of them are invisible in a component test that only checks "did it
+ * render", and both of them are the difference between a call that works and a
+ * call that looks broken while working perfectly.
+ */
+
+const peer = (identity: string, name?: string): Peer => ({
+  identity,
+  kind: "human",
+  ...(name === undefined ? {} : { name }),
+});
+
+/** The recording process, which joins the room as a real peer. */
+const recorder = (identity: string): Peer => ({ identity, kind: "egress" });
+
+const producer = (producerId: string, identity: string, kind: "audio" | "video", paused = false): ProducerEntry => ({
+  producerId,
+  identity,
+  kind,
+  paused,
+});
+
+describe("callTiles keeps the grid from collapsing", () => {
+  it("draws a tile for somebody with NO video at all", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("anna", "Anna")],
+      producers: [producer("p-audio", "anna", "audio")],
+      activeSpeakers: [],
+    });
+
+    // The whole point. A participant with the camera off has not left the room,
+    // and a grid built by mapping over video tracks drops them silently.
+    expect(tiles).toHaveLength(1);
+    expect(tiles[0]!.name).toBe("Anna");
+    expect(tiles[0]!.videoProducerId).toBeUndefined();
+    expect(tiles[0]!.hasAudio).toBe(true);
+  });
+
+  it("keeps the SAME number of tiles when a camera goes off", () => {
+    const peers = [peer("anna", "Anna"), peer("ben", "Ben")];
+    const withCamera = callTiles({
+      identity: "me",
+      peers,
+      producers: [producer("p-anna-video", "anna", "video"), producer("p-ben-audio", "ben", "audio")],
+      activeSpeakers: [],
+    });
+    const cameraOff = callTiles({
+      identity: "me",
+      peers,
+      producers: [producer("p-ben-audio", "ben", "audio")],
+      activeSpeakers: [],
+    });
+
+    expect(withCamera).toHaveLength(2);
+    // Two before, two after. This is the assertion that fails on the bug.
+    expect(cameraOff).toHaveLength(2);
+    expect(cameraOff.map((t) => t.identity)).toEqual(["anna", "ben"]);
+    // And the key is unchanged, so React updates the tile rather than
+    // unmounting and remounting it under the viewer's eyes.
+    expect(cameraOff[0]!.key).toBe(withCamera[0]!.key);
+  });
+
+  it("never draws the local participant, who has their own preview", () => {
+    const tiles = callTiles({
+      identity: "me",
+      // The node may or may not include us in `peers`; both have to be safe.
+      peers: [peer("me", "Me"), peer("anna", "Anna")],
+      producers: [producer("p-mine", "me", "video")],
+      activeSpeakers: [],
+    });
+
+    expect(tiles.map((t) => t.identity)).toEqual(["anna"]);
+  });
+
+  it("gives a second video stream its own tile rather than replacing the face", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("anna", "Anna")],
+      producers: [producer("p-cam", "anna", "video"), producer("p-screen", "anna", "video")],
+      activeSpeakers: [],
+    });
+
+    expect(tiles).toHaveLength(2);
+    expect(tiles.map((t) => t.videoProducerId)).toEqual(["p-cam", "p-screen"]);
+    // Same person, so the same name on both. The wire does not label which is
+    // the screen, so neither does this.
+    expect(tiles.every((t) => t.name === "Anna")).toBe(true);
+    expect(new Set(tiles.map((t) => t.key)).size).toBe(2);
+  });
+
+  it("draws a stream whose peer frame has not arrived yet", () => {
+    // `producerAppeared` and `peerJoined` have no ordering guarantee. Dropping
+    // the stream would blank a tile that has media in it.
+    const tiles = callTiles({
+      identity: "me",
+      peers: [],
+      producers: [producer("p-early", "carla", "video")],
+      activeSpeakers: [],
+    });
+
+    expect(tiles).toHaveLength(1);
+    expect(tiles[0]!.identity).toBe("carla");
+    expect(tiles[0]!.videoProducerId).toBe("p-early");
+  });
+
+  it("falls back to the identity, which tells two unnamed people apart", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("guest-1"), peer("guest-2", "   ")],
+      producers: [],
+      activeSpeakers: [],
+    });
+
+    expect(tiles.map((t) => t.name)).toEqual(["guest-1", "guest-2"]);
+  });
+
+  it("marks the speaker from the node's producer ids, not from identities", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("anna", "Anna"), peer("ben", "Ben")],
+      producers: [
+        producer("p-anna-audio", "anna", "audio"),
+        producer("p-anna-video", "anna", "video"),
+        producer("p-ben-audio", "ben", "audio"),
+      ],
+      // The node sends PRODUCER ids. Matching these against identities would
+      // light up nobody, and the indication would simply never appear.
+      activeSpeakers: ["p-anna-audio"],
+    });
+
+    expect(tiles.find((t) => t.identity === "anna")!.isSpeaking).toBe(true);
+    expect(tiles.find((t) => t.identity === "ben")!.isSpeaking).toBe(false);
+  });
+
+  it("carries the publisher's own pause through", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("anna", "Anna")],
+      producers: [producer("p-cam", "anna", "video", true)],
+      activeSpeakers: [],
+    });
+
+    expect(tiles[0]!.videoPaused).toBe(true);
+  });
+});
+
+describe("callHeadCount counts PEOPLE, not tiles", () => {
+  it("does not gain a person when somebody shares their screen", () => {
+    // A coach and a client: two people. The coach shares a screen, which by
+    // `callTiles`' own design gives them a second tile, and a count taken from
+    // `tiles.length` announced a third party in a two-person call at exactly
+    // the moment a coaching call is most likely to have one.
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("anna", "Anna")],
+      producers: [producer("p-cam", "anna", "video"), producer("p-screen", "anna", "video")],
+      activeSpeakers: [],
+    });
+
+    expect(tiles).toHaveLength(2);
+    expect(callHeadCount(tiles)).toBe(2);
+  });
+
+  it("counts everyone once, including the viewer, and the viewer alone in an empty room", () => {
+    expect(callHeadCount([])).toBe(1);
+
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("anna", "Anna"), peer("ben", "Ben")],
+      producers: [producer("p-anna-audio", "anna", "audio"), producer("p-ben-video", "ben", "video")],
+      activeSpeakers: [],
+    });
+
+    expect(callHeadCount(tiles)).toBe(3);
+  });
+
+  /**
+   * The recorder is not somebody who arrived.
+   *
+   * A recording joins as a real peer with `kind: "egress"`, so a grid built
+   * from `peers` drew a third tile called `egress-9f2c` in a 1:1 session and
+   * the header read "In this call: 3" - at exactly the moment a coach is most
+   * likely to be reading that number, and it is the number they use to answer
+   * "has my client actually arrived". `<RecordingIndicator>` already says the
+   * true thing, in words, as content.
+   */
+  it("does not count the recording as a person in the room", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [peer("anna", "Anna"), recorder("egress-9f2c")],
+      producers: [producer("p-anna-audio", "anna", "audio")],
+      activeSpeakers: [],
+    });
+
+    expect(tiles.map((t) => t.identity)).toEqual(["anna"]);
+    // A coach and their client. Two.
+    expect(callHeadCount(tiles)).toBe(2);
+  });
+
+  it("keeps a dial-in caller and an agent, which are somebody to talk to", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [
+        { identity: "+4915112345678", kind: "sip" },
+        { identity: "notetaker", kind: "agent", name: "Notes" },
+      ],
+      producers: [],
+      activeSpeakers: [],
+    });
+
+    // Only `egress` is excluded, and only because it is a recorder rather than
+    // a participant. Dropping every non-human would hide a caller who dialled in.
+    expect(tiles.map((t) => t.identity)).toEqual(["+4915112345678", "notetaker"]);
+    expect(callHeadCount(tiles)).toBe(3);
+  });
+});
+
+describe("remoteAudioProducerIds", () => {
+  it("takes everyone else's audio and none of our own", () => {
+    const ids = remoteAudioProducerIds({
+      identity: "me",
+      producers: [
+        producer("p-mine", "me", "audio"),
+        producer("p-anna", "anna", "audio"),
+        producer("p-anna-video", "anna", "video"),
+      ],
+    });
+
+    // Our own audio played back is a feedback loop, and a video producer
+    // attached to an `<audio>` element is silence.
+    expect(ids).toEqual(["p-anna"]);
+  });
+});
+
+describe("callStatus is honest about what is happening", () => {
+  it("separates a reconnect from a refusal", () => {
+    const dropped = callStatus({
+      connectionState: "reconnecting",
+      error: { type: "socket_closed", code: 1006 },
+      recovering: true,
+    });
+    const refused = callStatus({ connectionState: "reconnecting", error: { type: "refused", code: "unauthorized" } });
+
+    // The room reports ONE state for both. They are completely different things
+    // to the person looking at the screen: one is worth waiting through, the
+    // other is worth pressing a button about.
+    expect(dropped.tone).toBe("reconnecting");
+    expect(refused.tone).toBe("failed");
+    expect(dropped.headlineKey).not.toBe(refused.headlineKey);
+  });
+
+  it("shows the server's own words for a refusal rather than a friendly lie", () => {
+    // As TEXT, not as a key: a refusal is the one thing on the screen that must
+    // never be put through a translator, because the server's sentence is the
+    // reason and a friendlier version of it is a lie about why.
+    const refusedByCode = callStatus({
+      connectionState: "reconnecting",
+      error: { type: "refused", code: "room_closed" },
+    });
+    expect(refusedByCode.detailText).toBe("room_closed");
+    expect(refusedByCode.detailKey).toBeUndefined();
+    expect(
+      callStatus({
+        connectionState: "reconnecting",
+        error: { type: "refused", code: "unauthorized", message: "this session has ended" },
+      }).detailText,
+    ).toBe("this session has ended");
+  });
+
+  /**
+   * Keys, not sentences. `callStatus` has no locale, and every English string
+   * it used to return was rendered as-is on sites whose every other word was
+   * German. What it names has to exist in every bundle, or a German visitor
+   * reads a raw dotted key at the one moment they are being told the call is
+   * over.
+   */
+  it("names copy by key, and every key it can produce exists in every bundle", () => {
+    const seen = new Set<string>();
+    const inputs: Parameters<typeof callStatus>[0][] = [
+      { connectionState: "idle", error: undefined },
+      { connectionState: "connecting", error: undefined },
+      { connectionState: "connected", error: undefined },
+      { connectionState: "connected", error: undefined, phase: "closed" },
+      { connectionState: "closed", error: { type: "closed_by_client" } },
+      { connectionState: "closed", error: { type: "room_closed", reason: "x" } },
+      { connectionState: "reconnecting", error: { type: "refused", code: "unauthorized" } },
+      { connectionState: "reconnecting", error: { type: "room_closed", reason: "x" } },
+      { connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 1 }, recovering: true },
+      { connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 1 } },
+      { connectionState: "reconnecting", error: { type: "closed_by_client" } },
+      { connectionState: "reconnecting", error: { type: "socket_closed" }, recovering: true },
+      { connectionState: "reconnecting", error: { type: "socket_closed" } },
+    ];
+    for (const input of inputs) {
+      const status = callStatus(input);
+      seen.add(status.headlineKey);
+      if (status.detailKey) seen.add(status.detailKey);
+    }
+    for (const locale of FORGE_LOCALES) {
+      const bundle = getForgeMessages(locale);
+      const missing = [...seen].filter((key) => !key.startsWith("forge.call_stage.") || bundle[key] === undefined);
+      expect(missing, `${locale} is missing: ${missing.join(", ")}`).toEqual([]);
+    }
+    // And translated English reads as the sentences the screen specs assert on.
+    expect(translateForge("en", callStatus({ connectionState: "connected", error: undefined }).headlineKey)).toBe(
+      "Connected",
+    );
+  });
+
+  it("does not offer a retry for something retrying cannot fix", () => {
+    expect(callStatus({ connectionState: "connected", error: undefined }).canRetry).toBe(false);
+    expect(callStatus({ connectionState: "connecting", error: undefined }).canRetry).toBe(false);
+    expect(callStatus({ connectionState: "closed", error: { type: "closed_by_client" } }).canRetry).toBe(false);
+    expect(
+      callStatus({ connectionState: "reconnecting", error: { type: "room_closed", reason: "host ended" } }).canRetry,
+    ).toBe(false);
+    // A node moving us off itself reconnects on its own; a button would be a
+    // second connect racing the first. WHILE it is actually moving us: the
+    // promise and the control are two halves of one decision.
+    expect(
+      callStatus({
+        connectionState: "reconnecting",
+        error: { type: "draining", reconnectAfterMs: 500 },
+        recovering: true,
+      }).canRetry,
+    ).toBe(false);
+  });
+
+  /**
+   * A spinner is a promise, and it has to be one somebody is keeping.
+   *
+   * "Moving you to another server" and "Connection lost, reconnecting" both say
+   * "wait, this is being handled". Said over a stack where nothing is coming
+   * back, they are the worst screen in the product: an ordinary deploy drains a
+   * node, everyone on it reads that nobody was dropped, and the only way back
+   * into a paid coaching hour is working out for yourself that you should
+   * reload the page. So when `recovering` is false, the words change and a
+   * control appears.
+   */
+  describe("it does not promise a recovery that is not happening", () => {
+    it("offers a way back when a drain has nowhere to move you to", () => {
+      const moving = callStatus({
+        connectionState: "reconnecting",
+        error: { type: "draining", reconnectAfterMs: 500 },
+        recovering: true,
+      });
+      const stranded = callStatus({
+        connectionState: "reconnecting",
+        error: { type: "draining", reconnectAfterMs: 500 },
+      });
+
+      expect(moving.tone).toBe("reconnecting");
+      expect(moving.canRetry).toBe(false);
+      // The one the review found: a spinner, no control, and no second socket
+      // ever opened.
+      expect(stranded.tone).toBe("failed");
+      expect(stranded.canRetry).toBe(true);
+      expect(stranded.headlineKey).not.toBe(moving.headlineKey);
+    });
+
+    it("stops saying `reconnecting` about a dropped socket nothing is retrying", () => {
+      const retrying = callStatus({
+        connectionState: "reconnecting",
+        error: { type: "socket_closed", code: 1006 },
+        recovering: true,
+      });
+      const givenUp = callStatus({ connectionState: "reconnecting", error: { type: "socket_closed", code: 1006 } });
+
+      expect(translateForge("en", retrying.headlineKey)).toBe("Connection lost, reconnecting");
+      expect(translateForge("en", givenUp.headlineKey)).toBe("Connection lost");
+      expect(givenUp.tone).toBe("failed");
+      expect(givenUp.canRetry).toBe(true);
+    });
+
+    it("reads an absent `recovering` as nothing coming, which is the safe way round", () => {
+      // A caller that has not been taught about it gets a control rather than a
+      // spinner. The wrong answer offers a button somebody did not need; the
+      // other wrong answer strands them under a promise.
+      expect(callStatus({ connectionState: "reconnecting", error: undefined }).canRetry).toBe(true);
+      expect(callStatus({ connectionState: "reconnecting", error: undefined }).tone).toBe("failed");
+    });
+  });
+
+  it("offers a retry when only a fresh ticket will do", () => {
+    // A join ticket expires in minutes, and an expired one comes back as
+    // `unauthorized`; a refusal is very often just that, and `retry()`
+    // re-fetches through `getCredentials`.
+    expect(
+      callStatus({ connectionState: "reconnecting", error: { type: "refused", code: "unauthorized" } }).canRetry,
+    ).toBe(true);
+    expect(callStatus({ connectionState: "reconnecting", error: undefined }).canRetry).toBe(true);
+  });
+
+  it("says the call ended when the room closed, on either connection state", () => {
+    for (const connectionState of ["closed", "reconnecting"] as const) {
+      const status = callStatus({ connectionState, error: { type: "room_closed", reason: "the host ended it" } });
+      expect(status.tone).toBe("ended");
+      expect(status.detailText).toBe("the host ended it");
+    }
+  });
+
+  it("says the call ended the moment the ROOM says so, on a socket still open", () => {
+    // A `roomClosed` frame arrives on a live socket, so the connection is still
+    // "connected" until the node hangs up. Reading only the connection would
+    // show "Connected" over a call that has ended, and that is the one entry on
+    // this list somebody would act on wrongly.
+    const status = callStatus({
+      connectionState: "connected",
+      error: undefined,
+      phase: "closed",
+      closedReason: "the host ended it",
+    });
+
+    expect(status.tone).toBe("ended");
+    expect(status.detailText).toBe("the host ended it");
+  });
+
+  it("is live only when the room says connected", () => {
+    expect(callStatus({ connectionState: "connected", error: undefined }).tone).toBe("live");
+    expect(callStatus({ connectionState: "connected", error: undefined, phase: "joined" }).tone).toBe("live");
+    expect(callStatus({ connectionState: "idle", error: undefined }).tone).toBe("connecting");
+  });
+});
+
+describe("canPublishSource", () => {
+  const sources = ["microphone", "camera", "screen"] as const;
+
+  it("offers nothing without canPublish", () => {
+    for (const source of sources) {
+      expect(canPublishSource({ canPublish: false, canSubscribe: true, canPublishData: false }, source)).toBe(false);
+      expect(canPublishSource(undefined, source)).toBe(false);
+    }
+  });
+
+  it("treats an absent publishKinds as every kind, which is what the node does", () => {
+    const grants = { canPublish: true, canSubscribe: true, canPublishData: false };
+    for (const source of sources) {
+      expect(canPublishSource(grants, source)).toBe(true);
+    }
+  });
+
+  /**
+   * The SOURCES a control publishes, against the KINDS a grant lists.
+   *
+   * These are two vocabularies and they agree on one word. Asking this function
+   * about "audio" - as the buttons used to - is asking about something no
+   * publish ever declares, so it answered a question the node was never going
+   * to be asked: a booking token minted `["audio", "video", "screen"]` drew a
+   * microphone button and a camera button, and the node refused both, because
+   * what reached it was "microphone" and "camera".
+   */
+  it("offers the microphone and camera a booking token was minted for", () => {
+    const booking = {
+      canPublish: true,
+      canSubscribe: true,
+      canPublishData: false,
+      publishKinds: ["audio", "video", "screen"] as const,
+    };
+
+    for (const source of sources) {
+      expect(canPublishSource({ ...booking, publishKinds: [...booking.publishKinds] }, source)).toBe(true);
+    }
+  });
+
+  it("honours a narrowed publishKinds", () => {
+    const listenAndTalk = {
+      canPublish: true,
+      canSubscribe: true,
+      canPublishData: false,
+      publishKinds: ["audio"] as const,
+    };
+
+    expect(canPublishSource({ ...listenAndTalk, publishKinds: ["audio"] }, "microphone")).toBe(true);
+    expect(canPublishSource({ ...listenAndTalk, publishKinds: ["audio"] }, "camera")).toBe(false);
+    expect(canPublishSource({ ...listenAndTalk, publishKinds: ["audio"] }, "screen")).toBe(false);
+  });
+
+  it("does not offer a screen share on a token granted audio and video", () => {
+    const noPresenting = {
+      canPublish: true,
+      canSubscribe: true,
+      canPublishData: false,
+    };
+
+    expect(canPublishSource({ ...noPresenting, publishKinds: ["audio", "video"] }, "camera")).toBe(true);
+    expect(canPublishSource({ ...noPresenting, publishKinds: ["audio", "video"] }, "screen")).toBe(false);
+  });
+});

package/src/ui/media/_tests/fakeNode.ts

@@ -0,0 +1,178 @@
+/**
+ * An in-process media node, small enough to read in one sitting.
+ *
+ * The SDK has a fuller one (`media-client/src/core/_tests/fakeSignalServer.ts`,
+ * which validates every frame against the contract schema), and this is
+ * deliberately NOT that: it cannot be imported here. `@tribe-nest/media-client`
+ * publishes an exports map with four subpaths and none of them reaches into
+ * `src/core/_tests`, so an import of it would resolve inside this monorepo
+ * (npm workspaces symlink everything) and nowhere else. The same trap
+ * `_tests/publishedResolvability.spec.ts` exists for.
+ *
+ * What it has to do is exactly enough to get `<MediaRoomProvider>` to
+ * "connected" and then push frames at it: accept a join, answer a transport,
+ * answer a consume, and deliver whatever event a spec wants.
+ */
+
+/**
+ * Restated rather than imported: `SocketEventMap` is internal to
+ * `media-client/src/core/socket.ts` and no published subpath reaches it. The
+ * shape has to match structurally or `webSocket={node.factory}` does not
+ * type-check, which is the point of writing it out.
+ */
+type SocketEventMap = {
+  open: { type: "open" };
+  message: { type: "message"; data: unknown };
+  error: { type: "error"; error?: unknown };
+  close: { type: "close"; code?: number; reason?: string };
+};
+
+type SocketEvent = SocketEventMap[keyof SocketEventMap];
+type Listener = (event: never) => void;
+
+const OPEN = 1;
+const CLOSED = 3;
+
+export class FakeSocket {
+  readyState = 0;
+  private readonly listeners = new Map<string, Set<Listener>>();
+
+  constructor(private readonly node: FakeNode) {}
+
+  addEventListener<K extends keyof SocketEventMap>(type: K, listener: (event: SocketEventMap[K]) => void): void {
+    const set = this.listeners.get(type) ?? new Set<Listener>();
+    set.add(listener as Listener);
+    this.listeners.set(type, set);
+  }
+
+  removeEventListener<K extends keyof SocketEventMap>(type: K, listener: (event: SocketEventMap[K]) => void): void {
+    this.listeners.get(type)?.delete(listener as Listener);
+  }
+
+  send(data: string): void {
+    this.node.receive(this, JSON.parse(data) as Record<string, unknown>);
+  }
+
+  close(): void {
+    if (this.readyState === CLOSED) return;
+    this.readyState = CLOSED;
+    this.emit("close", { type: "close", code: 1000 });
+  }
+
+  open(): void {
+    this.readyState = OPEN;
+    this.emit("open", { type: "open" });
+  }
+
+  deliver(frame: unknown): void {
+    if (this.readyState !== OPEN) return;
+    this.emit("message", { type: "message", data: JSON.stringify(frame) });
+  }
+
+  /** The node going away underneath us, which is a reconnect and not a leave. */
+  drop(code = 1006): void {
+    if (this.readyState === CLOSED) return;
+    this.readyState = CLOSED;
+    this.emit("close", { type: "close", code, reason: "node closed" });
+  }
+
+  private emit(type: keyof SocketEventMap, event: SocketEvent): void {
+    for (const listener of [...(this.listeners.get(type) ?? [])]) {
+      queueMicrotask(() => (listener as (e: SocketEvent) => void)(event));
+    }
+  }
+}
+
+export type FakeProducer = { producerId: string; identity: string; kind: "audio" | "video" };
+
+export type FakeNodeOptions = {
+  identity?: string;
+  peers?: { identity: string; name?: string; kind?: "human" | "agent" | "egress" | "sip" | "ingress" }[];
+  producers?: FakeProducer[];
+  recording?: boolean;
+  grants?: Record<string, unknown>;
+  /** Refuse the join with this code instead of accepting it. */
+  refuseWith?: string;
+};
+
+export class FakeNode {
+  readonly sockets: FakeSocket[] = [];
+  readonly received: Record<string, unknown>[] = [];
+
+  constructor(private readonly options: FakeNodeOptions = {}) {}
+
+  /** Pass as `webSocket` to `<MediaRoomProvider>`. */
+  readonly factory = (): FakeSocket => {
+    const socket = new FakeSocket(this);
+    this.sockets.push(socket);
+    queueMicrotask(() => socket.open());
+    return socket;
+  };
+
+  get socket(): FakeSocket {
+    const socket = this.sockets[this.sockets.length - 1];
+    if (!socket) throw new Error("no socket has been opened");
+    return socket;
+  }
+
+  receive(socket: FakeSocket, frame: Record<string, unknown>): void {
+    this.received.push(frame);
+    const id = frame.id as number;
+
+    if (frame.method === "join") {
+      if (this.options.refuseWith) {
+        socket.deliver({ id, ok: false, code: this.options.refuseWith });
+        return;
+      }
+      socket.deliver({ id, ok: true, data: { accepted: true } });
+      socket.deliver(this.joinedFrame());
+      return;
+    }
+
+    if (frame.method === "createTransport") {
+      socket.deliver({
+        id,
+        ok: true,
+        data: { transportId: "t-1", iceParameters: {}, iceCandidates: [], dtlsParameters: {} },
+      });
+      return;
+    }
+
+    if (frame.method === "consume") {
+      const producerId = frame.producerId as string;
+      const known = (this.options.producers ?? []).find((p) => p.producerId === producerId);
+      socket.deliver({
+        id,
+        ok: true,
+        data: { consumerId: `c-${producerId}`, producerId, kind: known?.kind ?? "video", rtpParameters: {} },
+      });
+      return;
+    }
+
+    socket.deliver({ id, ok: true, data: {} });
+  }
+
+  joinedFrame(): Record<string, unknown> {
+    return {
+      event: "joined",
+      identity: this.options.identity ?? "me",
+      room: "booking-1",
+      routerRtpCapabilities: { codecs: [] },
+      peers: (this.options.peers ?? []).map((p) => ({ kind: "human", ...p })),
+      producers: this.options.producers ?? [],
+      iceServers: [],
+      recording: this.options.recording ?? false,
+      grants: this.options.grants ?? { canPublish: true, canSubscribe: true, canPublishData: false },
+    };
+  }
+
+  /** Push any event frame at the live socket. */
+  event(frame: Record<string, unknown>): void {
+    this.socket.deliver(frame);
+  }
+}
+
+/** Let the fake socket's queued microtasks land. */
+export const settle = async (ms = 150): Promise<void> => {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+};