@tribe-nest/forge 3.29.0 → 3.34.0

package/src/ui/media/_tests/CallStage.spec.tsx

@@ -0,0 +1,931 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { Profiler, type ReactNode } from "react";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { MediaRoomProvider, type MediaRoomProviderProps } from "@tribe-nest/media-client/react";
+import type { MediaDevice, MediaTransport } from "@tribe-nest/media-client";
+import { MediaError } from "@tribe-nest/media-protocol";
+
+import { CallStage } from "../CallStage";
+import { ForgeI18nProvider } from "../../../i18n";
+import { ForgeThemeProvider, type ForgeTheme } from "../../theme/ForgeThemeProvider";
+import { FakeNode, settle } from "./fakeNode";
+
+/**
+ * The call screen, rendered, against a real room.
+ *
+ * ## Why this counts renders
+ *
+ * `useSyncExternalStore` compares snapshots with `Object.is`, so a hook that
+ * builds a new value on every read reports a change on every check and React
+ * re-renders for ever. That bug has already shipped once in this repo (the
+ * room's `tracks` and `localPublications` getters spread a Map), and it is
+ * invisible to the type system, to a unit test and to a render assertion: a
+ * looping component renders exactly the right thing, several thousand times a
+ * second, until the tab heats up.
+ *
+ * A call screen is the worst place for it, because it reads FIVE of those hooks
+ * at once and derives arrays from all of them. So the first test here is not
+ * about what the screen shows; it is about the screen settling, and every other
+ * test in this file is worthless while that one is in doubt.
+ *
+ * ## Why it drives a real `<MediaRoomProvider>`
+ *
+ * Mocking the hooks would make the render-count test prove nothing at all: the
+ * loop lives in the join between the hooks and React, which a mock removes.
+ */
+
+afterEach(() => {
+  cleanup();
+  produced.length = 0;
+  delete (navigator as { mediaDevices?: unknown }).mediaDevices;
+});
+
+beforeAll(() => {
+  // jsdom has no `MediaStream`, and the local preview builds one to hand to a
+  // `<video>`. A two-line stand-in is enough: nothing here asserts on it, the
+  // point is that the component may construct one without throwing.
+  if (!("MediaStream" in globalThis)) {
+    (globalThis as { MediaStream?: unknown }).MediaStream = class {
+      constructor(readonly tracks: unknown[] = []) {}
+    };
+  }
+});
+
+/** Every `produce` this device is asked for, by source. Reset per test. */
+const produced: string[] = [];
+
+const fakeDevice = (): MediaDevice => ({
+  async load() {},
+  loaded: true,
+  rtpCapabilities: { codecs: [] } as never,
+  canProduce: () => true,
+  createSendTransport: () => fakeTransport(),
+  createRecvTransport: () => fakeTransport(),
+});
+
+const fakeTransport = (): MediaTransport => ({
+  id: "t-1",
+  async produce(input) {
+    produced.push(String((input.appData as { source?: string } | undefined)?.source));
+    return {
+      id: `p-local-${produced.length}`,
+      kind: "audio",
+      closed: false,
+      pause: vi.fn(),
+      resume: vi.fn(),
+      close: vi.fn(),
+    };
+  },
+  async consume(input) {
+    return {
+      id: `c-${input.producerId}`,
+      producerId: input.producerId,
+      kind: input.kind,
+      track: { kind: input.kind, stop: vi.fn() } as unknown as MediaStreamTrack,
+      pause: vi.fn(),
+      resume: vi.fn(),
+      close: vi.fn(),
+    };
+  },
+  close: vi.fn(),
+});
+
+/** Every colour in the screen comes from here. Nothing is written in the component. */
+const theme: ForgeTheme = {
+  colors: { text: "#101010", background: "#fafafa", primary: "#0b6", surface: "#eeeeee" },
+  cornerRadius: 10,
+};
+
+/**
+ * Reconnection off unless a test asks for it.
+ *
+ * The room now drives the reconnect ladder itself, so a spec that drops a
+ * socket and then asserts on the screen is racing a real recovery. `NO_RECOVERY`
+ * is the default here so that every test which is about something else stays
+ * deterministic, and the two tests that ARE about coming back turn it on and
+ * collapse the delays to something a real timer clears inside a test.
+ */
+type Recovery = NonNullable<MediaRoomProviderProps["reconnect"]>;
+const NO_RECOVERY: Recovery = { maxAttempts: 0 };
+const FAST_RECOVERY: Recovery = { baseMs: 1, maxMs: 4, factor: 1, jitter: "none" };
+
+const mount = (
+  node: FakeNode,
+  children: ReactNode,
+  options: { autoSubscribe?: boolean; reconnect?: Recovery; locale?: string } = {},
+) =>
+  render(
+    <ForgeI18nProvider locale={options.locale ?? "en"}>
+      <ForgeThemeProvider theme={theme}>
+        <MediaRoomProvider
+          getCredentials={() => ({ mediaUrl: "wss://media.example", token: "t" })}
+          device={fakeDevice}
+          webSocket={node.factory}
+          autoSubscribe={options.autoSubscribe ?? false}
+          reconnect={options.reconnect ?? NO_RECOVERY}
+        >
+          {children}
+        </MediaRoomProvider>
+      </ForgeThemeProvider>
+    </ForgeI18nProvider>,
+  );
+
+/**
+ * A permission prompt and a capture, as the browser would give them.
+ *
+ * The track is an `EventTarget`, as a real `MediaStreamTrack` is, so a spec can
+ * end it the way the browser's own "Stop sharing" bar does.
+ */
+const stubCapture = (kind: "audio" | "video" = "audio") => {
+  const target = new EventTarget() as EventTarget & { kind: string; stop: ReturnType<typeof vi.fn>; enabled: boolean };
+  target.kind = kind;
+  target.stop = vi.fn();
+  target.enabled = true;
+  const track = target as unknown as MediaStreamTrack & { stop: ReturnType<typeof vi.fn> };
+  const getUserMedia = vi.fn(async () => ({ getTracks: () => [track] }) as unknown as MediaStream);
+  Object.defineProperty(navigator, "mediaDevices", {
+    configurable: true,
+    value: { getUserMedia, getDisplayMedia: getUserMedia },
+  });
+  return { track, getUserMedia };
+};
+
+/**
+ * Commits of the WHOLE subtree, not renders of the top component.
+ *
+ * A counter in `CallStage` itself would have missed the bug this file is
+ * about. The loop lives wherever a hook is read, and the hooks are read in the
+ * tiles and the local preview as well: reintroducing the historical
+ * `[...room.localPublications]` selector spins `LocalPreview` for ever while
+ * `CallStage` renders exactly once and a per-component counter stays green.
+ * `<Profiler>` sees every commit underneath it, which is the property.
+ */
+function CountedStage({ commits }: { commits: number[] }) {
+  return (
+    <Profiler id="call" onRender={() => commits.push(1)}>
+      <CallStage />
+    </Profiler>
+  );
+}
+
+describe("the call screen settles instead of looping", () => {
+  it("commits a bounded number of times and then stops", async () => {
+    const commits: number[] = [];
+    const node = new FakeNode({
+      peers: [
+        { identity: "anna", name: "Anna" },
+        { identity: "ben", name: "Ben" },
+      ],
+      producers: [
+        { producerId: "p-anna-video", identity: "anna", kind: "video" },
+        { producerId: "p-anna-audio", identity: "anna", kind: "audio" },
+      ],
+    });
+
+    mount(node, <CountedStage commits={commits} />);
+
+    await settle();
+    const settled = commits.length;
+    // A join is a handful of state transitions. Anything near this ceiling is
+    // already a bug; a loop reaches thousands.
+    expect(settled).toBeLessThan(20);
+
+    // And it STAYS settled with nothing happening. A hook whose snapshot is
+    // rebuilt per read keeps going after everything has arrived.
+    await settle();
+    expect(commits.length).toBe(settled);
+  });
+
+  /**
+   * ## Why this measures the join as well as the churn
+   *
+   * It used to measure only the DELTA across the churn, and that made it unable
+   * to fail. Reintroducing the exact historical bug (`room.tracks` spreading
+   * the Map on every read, `attach` memoised on `[producerId]`) turned the test
+   * above red at 55 commits and left this one green: React abandons a
+   * getSnapshot loop after about fifty forced re-renders, so by the time
+   * `afterJoin` was read the loop had already run and stopped, and the delta it
+   * then measured was the delta of a tree React had given up on. A budget taken
+   * from a baseline that is itself the bug measures nothing.
+   *
+   * So the baseline is asserted, the delta is asserted, and the churn is
+   * asserted to have actually LANDED - a tree React has stopped re-rendering is
+   * also a tree that commits nothing, and would otherwise pass this by being
+   * inert.
+   */
+  it("settles again after the room changes underneath it", async () => {
+    const commits: number[] = [];
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+
+    const { getByTestId } = mount(node, <CountedStage commits={commits} />);
+    await settle();
+    const afterJoin = commits.length;
+    // The baseline has to be a settled tree, or every number below is measured
+    // against a loop that has already burnt itself out.
+    expect(afterJoin).toBeLessThan(20);
+
+    node.event({ event: "peerJoined", peer: { identity: "ben", name: "Ben", kind: "human" } });
+    node.event({ event: "producerAppeared", producerId: "p-ben", identity: "ben", kind: "audio" });
+    node.event({ event: "activeSpeakers", producerIds: ["p-ben"] });
+
+    await settle();
+    const afterChurn = commits.length;
+    // The frames reached the screen. Without this, "few commits" is satisfied
+    // by a tree that is no longer rendering at all.
+    expect(getByTestId("tile-ben")).toBeTruthy();
+    // Three frames, a small number of commits. Not "a few more than before".
+    expect(afterChurn - afterJoin).toBeLessThan(12);
+
+    await settle();
+    expect(commits.length).toBe(afterChurn);
+  });
+});
+
+describe("the grid", () => {
+  it("keeps a tile for a participant with no video", async () => {
+    const node = new FakeNode({
+      peers: [
+        { identity: "anna", name: "Anna" },
+        { identity: "ben", name: "Ben" },
+      ],
+      producers: [{ producerId: "p-anna-video", identity: "anna", kind: "video" }],
+    });
+
+    const { getByTestId, getAllByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByTestId("tile-ben")).toBeTruthy());
+    // Ben publishes nothing at all. He is still in the room, so he is still on
+    // screen, and his NAME is what the tile shows.
+    expect(getAllByText("Ben").length).toBeGreaterThan(0);
+    expect(getByTestId("tile-anna")).toBeTruthy();
+    expect(getByTestId("tile-local")).toBeTruthy();
+  });
+
+  it("does not collapse when somebody turns their camera off", async () => {
+    const node = new FakeNode({
+      peers: [
+        { identity: "anna", name: "Anna" },
+        { identity: "ben", name: "Ben" },
+      ],
+      producers: [
+        { producerId: "p-anna-video", identity: "anna", kind: "video" },
+        { producerId: "p-ben-video", identity: "ben", kind: "video" },
+      ],
+    });
+
+    const { container, getByTestId } = mount(node, <CallStage />);
+    await waitFor(() => expect(getByTestId("tile-ben")).toBeTruthy());
+    const before = container.querySelectorAll("[data-testid^='tile-']").length;
+
+    node.event({ event: "producerClosed", producerId: "p-ben-video" });
+
+    // Same tiles, one of them now showing a name instead of a picture. The bug
+    // this pins removes the tile entirely and re-flows the whole grid.
+    await settle();
+    expect(container.querySelectorAll("[data-testid^='tile-']").length).toBe(before);
+    expect(getByTestId("tile-ben")).toBeTruthy();
+  });
+
+  /**
+   * The head count is the one number a person acts on.
+   *
+   * "In this call: 2" is how a coach answers "has my client actually arrived",
+   * so it has to count PEOPLE. It was `tiles.length + 1`, and `callTiles` gives
+   * a screen sharer two tiles by design, so the moment the coach shared their
+   * screen the header announced a third party in a two-person room.
+   */
+  it("counts people, not video streams, while somebody shares a screen", async () => {
+    const node = new FakeNode({
+      peers: [{ identity: "anna", name: "Anna" }],
+      producers: [
+        { producerId: "p-anna-video", identity: "anna", kind: "video" },
+        { producerId: "p-anna-screen", identity: "anna", kind: "video" },
+      ],
+    });
+
+    const { container, getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText(/In this call:/).textContent).toBe("In this call: 2"));
+    // Two tiles for her, and still two people. The count is derived from the
+    // grid, so this pins both halves at once.
+    expect(container.querySelectorAll("[data-testid='tile-anna']").length).toBe(2);
+  });
+
+  /**
+   * The recorder joins as a real peer.
+   *
+   * `session.ts` publishes `participantJoined` for the egress process and the
+   * join snapshot carries it, 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 the one 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".
+   */
+  it("does not draw the recording as a third person in the room", async () => {
+    const node = new FakeNode({
+      recording: true,
+      peers: [
+        { identity: "anna", name: "Anna" },
+        { identity: "egress-9f2c", kind: "egress" },
+      ],
+    });
+
+    const { getByTestId, queryByTestId, getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+    expect(queryByTestId("tile-egress-9f2c")).toBeNull();
+    expect(getByText(/In this call:/).textContent).toBe("In this call: 2");
+    // The consent signal is still said, properly, in words.
+    expect(getByText("This call is being recorded")).toBeTruthy();
+  });
+
+  /**
+   * A barrier the node narrows mid-call has to reach the screen.
+   *
+   * `grantsChanged` pushes `subscribeRuleChanged`, and the reducer deliberately
+   * KEEPS the now-forbidden producers so that a rule which later widens is
+   * recoverable. Nothing cleans them up for us either: the node's
+   * `revokeNewlyForbidden` closes only producers this session had a live
+   * consumer for, so one that was announced and never consumed stays in the
+   * list for the rest of the call. A screen reading the raw list therefore
+   * keeps a tile carrying that person's identity and mounts an `<audio>` for
+   * them, and on a sealed consultation the other party's presence is most of
+   * what the barrier was hiding.
+   *
+   * The rule governs MEDIA, so this is about the media: the peer roster is the
+   * node's own account of who is in the room and is not filtered by a subscribe
+   * rule on either side.
+   */
+  it("stops rendering media the node has barred this seat from", async () => {
+    const node = new FakeNode({
+      peers: [
+        { identity: "anna", name: "Anna" },
+        { identity: "third-party", name: "Third Party" },
+      ],
+      producers: [
+        { producerId: "p-anna-audio", identity: "anna", kind: "audio" },
+        { producerId: "p-third-audio", identity: "third-party", kind: "audio" },
+        { producerId: "p-third-video", identity: "third-party", kind: "video" },
+      ],
+    });
+
+    const { container, getByTestId } = mount(node, <CallStage />, { autoSubscribe: true });
+    await waitFor(() => expect(getByTestId("tile-third-party")).toBeTruthy());
+    node.event({ event: "activeSpeakers", producerIds: ["p-anna-audio", "p-third-audio", "p-third-video"] });
+    await waitFor(() => expect(container.querySelectorAll("audio").length).toBe(2));
+    await waitFor(() => expect(container.querySelectorAll("video").length).toBe(1));
+
+    node.event({ event: "subscribeRuleChanged", subscribe: { mode: "allow", identities: ["anna"] } });
+
+    // An `<audio>` left mounted for a producer this seat may not receive is the
+    // barrier failing in the one place a person can observe it.
+    await waitFor(() => expect(container.querySelectorAll("audio").length).toBe(1));
+    expect(container.querySelectorAll("video").length).toBe(0);
+    expect(getByTestId("tile-anna")).toBeTruthy();
+  });
+
+  it("marks the active speaker without re-ordering the grid", async () => {
+    const node = new FakeNode({
+      peers: [
+        { identity: "anna", name: "Anna" },
+        { identity: "ben", name: "Ben" },
+      ],
+      producers: [
+        { producerId: "p-anna-audio", identity: "anna", kind: "audio" },
+        { producerId: "p-ben-audio", identity: "ben", kind: "audio" },
+      ],
+    });
+
+    const { container, getByTestId } = mount(node, <CallStage />);
+    await waitFor(() => expect(getByTestId("tile-ben")).toBeTruthy());
+    const order = () =>
+      [...container.querySelectorAll("[data-testid^='tile-']")].map((n) => n.getAttribute("data-testid"));
+    const before = order();
+
+    node.event({ event: "activeSpeakers", producerIds: ["p-ben-audio"] });
+
+    await waitFor(() => expect(getByTestId("tile-ben").getAttribute("data-speaking")).toBe("true"));
+    expect(getByTestId("tile-anna").getAttribute("data-speaking")).toBe("false");
+    // A grid that reshuffles on every "mm" moves the person you were watching
+    // out from under your eye.
+    expect(order()).toEqual(before);
+  });
+});
+
+/**
+ * The half of the screen that has no pixels.
+ *
+ * Nothing in this file used to look at an `<audio>` or a `<video>` element at
+ * all, and the whole media-attachment layer sat under that gap: remote audio
+ * elements were mounted the moment the node ANNOUNCED a producer, some
+ * milliseconds before the consume round trip produced a track, and their ref
+ * callback - memoised on values that never changed - was never invoked again.
+ * Every one of them kept `srcObject = null` for the whole call. Remote
+ * `<video>` carries `muted`, so there was no second audio path: the coach and
+ * the client saw each other and heard nothing, on a screen that passed every
+ * assertion here.
+ */
+describe("the audio actually reaches an element", () => {
+  it("attaches a remote track to the element that was already on the page", async () => {
+    const node = new FakeNode({
+      peers: [{ identity: "anna", name: "Anna" }],
+      producers: [{ producerId: "p-anna-audio", identity: "anna", kind: "audio" }],
+    });
+
+    // autoSubscribe on: the room follows the node's active set, so the track
+    // arrives when the node says she is speaking and not before.
+    const { container } = mount(node, <CallStage />, { autoSubscribe: true });
+
+    await waitFor(() => expect(container.querySelector("audio")).toBeTruthy());
+    const element = container.querySelector("audio") as HTMLAudioElement;
+    expect(element.srcObject).toBeNull();
+
+    node.event({ event: "activeSpeakers", producerIds: ["p-anna-audio"] });
+
+    await waitFor(() => expect((container.querySelector("audio") as HTMLAudioElement).srcObject).toBeTruthy());
+    // The SAME element, never unmounted. That is what makes this a test of the
+    // ref being re-invoked rather than of a remount happening to fix it.
+    expect(container.querySelector("audio")).toBe(element);
+  });
+
+  it("attaches a remote camera to its tile", async () => {
+    const node = new FakeNode({
+      peers: [{ identity: "anna", name: "Anna" }],
+      producers: [{ producerId: "p-anna-video", identity: "anna", kind: "video" }],
+    });
+
+    const { container, getByTestId } = mount(node, <CallStage />, { autoSubscribe: true });
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    node.event({ event: "activeSpeakers", producerIds: ["p-anna-video"] });
+
+    await waitFor(() => expect(container.querySelector("video")).toBeTruthy());
+    expect((container.querySelector("video") as HTMLVideoElement).srcObject).toBeTruthy();
+  });
+});
+
+describe("the connection state, said honestly", () => {
+  it("says it is connecting, then that it is connected", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = mount(node, <CallStage />);
+
+    expect(getByRole("status").textContent).toContain("Connecting");
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+  });
+
+  it("names a refusal and offers a retry, rather than spinning for ever", async () => {
+    const node = new FakeNode({ refuseWith: "unauthorized" });
+    const { getByRole, getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Could not join this call"));
+    // The server's own code, and a control. A spinner here is the failure: it
+    // says "wait" about something waiting will never fix.
+    expect(getByRole("status").textContent).toContain("unauthorized");
+    expect(getByText("Try again")).toBeTruthy();
+  });
+
+  /**
+   * The ticket endpoint said no BEFORE any socket existed. This used to wedge
+   * the room on "Connecting" for ever (the SDK never ran its close path for a
+   * failure with no socket), and the docblocks promising the server's refusal
+   * would be shown verbatim could not be kept. Now it is a refusal like any
+   * other: the sentence, and a control.
+   */
+  it("shows the credential endpoint's refusal verbatim, with a retry, rather than a spinner", async () => {
+    const node = new FakeNode({});
+    let attempts = 0;
+    const { getByRole, getByText } = render(
+      <ForgeThemeProvider theme={theme}>
+        <MediaRoomProvider
+          getCredentials={() => {
+            attempts += 1;
+            if (attempts === 1) {
+              throw new MediaError("bad_request", "The room opens 15 minutes before the session.");
+            }
+            return { mediaUrl: "wss://media.example", token: "t" };
+          }}
+          device={fakeDevice}
+          webSocket={node.factory}
+          autoSubscribe={false}
+          reconnect={NO_RECOVERY}
+        >
+          <CallStage />
+        </MediaRoomProvider>
+      </ForgeThemeProvider>,
+    );
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Could not join this call"));
+    expect(getByRole("status").textContent).toContain("The room opens 15 minutes before the session.");
+    expect(getByRole("status").textContent).not.toContain("Connection lost");
+
+    // And Try again is not decoration: the next attempt fetches a ticket again
+    // and gets in.
+    fireEvent.click(getByText("Try again"));
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+    expect(attempts).toBe(2);
+  });
+
+  it("says the call ended when the node closes the room", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = mount(node, <CallStage />);
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+
+    node.event({ event: "roomClosed", reason: "the host ended it" });
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("The call has ended"));
+    expect(getByRole("status").textContent).toContain("the host ended it");
+  });
+
+  it("distinguishes a dropped socket from a refusal", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = mount(node, <CallStage />);
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+
+    node.socket.drop();
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connection lost"));
+    expect(getByRole("status").textContent).not.toContain("Could not join");
+  });
+});
+
+/**
+ * A spinner is a promise, and nothing here was keeping it.
+ *
+ * `superviseConnection` - the whole reconnect policy, built and tested - had no
+ * caller outside its own spec, so a drop set the connection to `reconnecting`
+ * and no second socket was ever opened. For a plain drop the screen at least
+ * offered "Try again"; for a DRAIN it offered nothing, because a drain is
+ * supposed to be handled for you. So an ordinary deploy or scale-down ended
+ * every call on that node under the words "Moving you to another server / This
+ * takes a few seconds and nobody else is dropped", with a spinner, no control,
+ * and no way back into a paid coaching hour short of guessing that a reload
+ * would work.
+ */
+describe("the promise to come back is one somebody keeps", () => {
+  it("actually moves you when the node drains, rather than saying so", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = mount(node, <CallStage />, { reconnect: FAST_RECOVERY });
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+
+    // What a deploy sends: the node asks to be left, then closes the socket.
+    node.event({ event: "draining", reconnectAfterMs: 1 });
+    await settle(20);
+    node.socket.drop();
+
+    // A SECOND socket, through `MEDIA_URL` with a fresh ticket, and back in the
+    // call. This is what the copy on screen has been claiming all along.
+    await waitFor(() => expect(node.sockets.length).toBe(2));
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+  });
+
+  it("offers a way back when a drain has nowhere to move you to", async () => {
+    const node = new FakeNode({});
+    const { getByRole, getByText } = mount(node, <CallStage />, { reconnect: NO_RECOVERY });
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+
+    node.event({ event: "draining", reconnectAfterMs: 1 });
+    await settle(20);
+    node.socket.drop();
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Could not move you"));
+    // The control the drained case never had. Spinner plus no button is the
+    // one combination that leaves somebody sitting there.
+    expect(getByText("Try again")).toBeTruthy();
+  });
+
+  it("comes back into the call when Try again is PRESSED, not merely drawn", async () => {
+    const node = new FakeNode({});
+    const { getByRole, getByText } = mount(node, <CallStage />, { reconnect: NO_RECOVERY });
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+
+    node.socket.drop();
+    await waitFor(() => expect(getByText("Try again")).toBeTruthy());
+
+    fireEvent.click(getByText("Try again"));
+
+    // Asserting the button exists proves nothing about whether pressing it
+    // does anything, and the retry path had no test that pressed it.
+    await waitFor(() => expect(node.sockets.length).toBe(2));
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+  });
+});
+
+describe("the controls", () => {
+  it("offers only what the token was minted for", async () => {
+    const node = new FakeNode({
+      grants: { canPublish: true, canSubscribe: true, canPublishData: false, publishKinds: ["audio"] },
+    });
+    const { getByText, queryByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    // A camera the node would refuse is not a button. The node refuses it
+    // anyway; this is about not offering it.
+    expect(queryByText("Start camera")).toBeNull();
+    expect(queryByText("Share screen")).toBeNull();
+    expect(getByText("Leave")).toBeTruthy();
+  });
+
+  it("offers the microphone and camera a booking token was minted for", async () => {
+    // The grants a coaching room actually mints. The UI asks about the SOURCE
+    // it is going to publish ("microphone", "camera") rather than about the
+    // grant's own word for it, because the source is what the node decides
+    // against - and this was the one call the UI and the node did not agree on.
+    const node = new FakeNode({
+      grants: {
+        canPublish: true,
+        canSubscribe: true,
+        canPublishData: false,
+        publishKinds: ["audio", "video", "screen"],
+      },
+    });
+    const { getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    expect(getByText("Start camera")).toBeTruthy();
+    expect(getByText("Share screen")).toBeTruthy();
+  });
+
+  it("offers every control when the grants are open", async () => {
+    const node = new FakeNode({});
+    const { getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    expect(getByText("Start camera")).toBeTruthy();
+    expect(getByText("Share screen")).toBeTruthy();
+  });
+
+  it("offers nothing to publish on a listen-only seat, and still lets them leave", async () => {
+    const node = new FakeNode({ grants: { canPublish: false, canSubscribe: true, canPublishData: false } });
+    const { getByText, queryByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Leave")).toBeTruthy());
+    expect(queryByText("Unmute")).toBeNull();
+    expect(queryByText("Start camera")).toBeNull();
+  });
+});
+
+/**
+ * Every control test above asks only which buttons are DRAWN.
+ *
+ * Not one of them pressed anything, so no test exercised a publish through the
+ * UI at all, and the two defects that live in pressing were both invisible: a
+ * second press while the permission prompt is open, and a capture that outlives
+ * the call it was consented to.
+ */
+describe("the controls, pressed", () => {
+  it("publishes ONCE when Unmute is pressed twice in a row", async () => {
+    const { getUserMedia } = stubCapture();
+    const node = new FakeNode({});
+    const { getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    const button = getByText("Unmute");
+    // Which is exactly what a person does when the first press produces no
+    // visible change - and it produces none, because `getUserMedia` is showing
+    // a permission prompt and the flag the handler reads comes from the
+    // publication that only exists once the publish has resolved.
+    fireEvent.click(button);
+    fireEvent.click(button);
+
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+    await settle(30);
+    // Two producers under one identity means everybody else mounts two
+    // `<audio>` elements and hears this person doubled.
+    expect(getUserMedia).toHaveBeenCalledTimes(1);
+    expect(produced).toEqual(["microphone"]);
+  });
+
+  it("releases the microphone when the call ends underneath the person", async () => {
+    const { track } = stubCapture();
+    const node = new FakeNode({});
+    const { getByText, getByRole } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+
+    // A coach cancelling or refunding at minute ten: the room is ended on the
+    // plane and the node evicts. Nobody pressed Leave, which is the only path
+    // that used to reach `room.close()`.
+    node.event({ event: "roomClosed", reason: "the host ended it" });
+    await settle(20);
+    node.socket.drop();
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("The call has ended"));
+    // The OS recording indicator goes out. It stayed lit until the person
+    // happened to close the tab, with the button still reading "Mute" about a
+    // microphone publishing into a room that no longer existed.
+    await waitFor(() => expect(track.stop).toHaveBeenCalledTimes(1));
+    expect(getByText("Unmute")).toBeTruthy();
+  });
+});
+
+describe("the things that must stay visible", () => {
+  it("shows the recording indicator as content, not behind a hint", async () => {
+    const node = new FakeNode({ recording: true });
+    const { getByText } = mount(node, <CallStage />);
+
+    // Consent. It is never something a person has to click to find out.
+    await waitFor(() => expect(getByText("This call is being recorded")).toBeTruthy());
+  });
+
+  it("keeps explanations behind a `?` with a name that says what it explains", async () => {
+    const node = new FakeNode({});
+    const { getByLabelText, queryByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByLabelText("Why can I hear someone but not see them?")).toBeTruthy());
+    // Not on screen until asked for. A permanent paragraph on a call screen is
+    // a paragraph in the way of the call.
+    expect(queryByText(/means that person has their camera off/)).toBeNull();
+
+    fireEvent.click(getByLabelText("Why can I hear someone but not see them?"));
+    await waitFor(() => expect(queryByText(/means that person has their camera off/)).toBeTruthy());
+  });
+});
+
+/**
+ * The screen speaks the site's language.
+ *
+ * Every string on the call screen was English, written into the component,
+ * against Forge's own convention: a German site rendered a German account page
+ * with an English call in the middle of it, and `callStatus` returned sentences
+ * a translator could not reach. This pins that the SAME component, under the
+ * SAME provider every Forge component reads, is German when the site is.
+ */
+describe("the screen is translated", () => {
+  it("renders the status and the controls in the site's language", async () => {
+    const node = new FakeNode({});
+    const { getByRole, getByText, queryByText } = mount(node, <CallStage />, { locale: "de" });
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Verbunden"));
+    expect(getByText("Stummschaltung aufheben")).toBeTruthy();
+    expect(getByText("Kamera starten")).toBeTruthy();
+    expect(getByText("Verlassen")).toBeTruthy();
+    expect(getByText(/In diesem Anruf:/).textContent).toBe("In diesem Anruf: 1");
+    expect(queryByText("Unmute")).toBeNull();
+  });
+
+  it("keeps the server's own sentence verbatim inside a translated status", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = mount(node, <CallStage />, { locale: "de" });
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Verbunden"));
+
+    node.event({ event: "roomClosed", reason: "the host ended it" });
+
+    // The headline is ours and is German; the reason is the server's and is not
+    // put through a translator, because a friendlier version of a refusal is a
+    // lie about why.
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Der Anruf ist beendet"));
+    expect(getByRole("status").textContent).toContain("the host ended it");
+  });
+
+  it("falls back to English outside any i18n provider, so a site without one still gets a call", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = render(
+      <ForgeThemeProvider theme={theme}>
+        <MediaRoomProvider
+          getCredentials={() => ({ mediaUrl: "wss://media.example", token: "t" })}
+          device={fakeDevice}
+          webSocket={node.factory}
+          autoSubscribe={false}
+          reconnect={NO_RECOVERY}
+        >
+          <CallStage />
+        </MediaRoomProvider>
+      </ForgeThemeProvider>,
+    );
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+  });
+});
+
+/**
+ * Mute is a pause, not a second permission prompt.
+ *
+ * The toggles were unpublish-then-publish, and every publish starts with
+ * `getUserMedia`. Safari asks permission on EVERY call to it, so a person on an
+ * iPad was asked whether the site may use the microphone each time they
+ * unmuted. Now the first press captures and every press after that pauses or
+ * resumes the publication the room already holds.
+ */
+describe("mute and camera-off keep the capture", () => {
+  it("mutes and unmutes with ONE capture, and tells the node each time", async () => {
+    const { getUserMedia } = stubCapture();
+    const node = new FakeNode({});
+    const { getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+
+    fireEvent.click(getByText("Mute"));
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    expect(node.received.filter((f) => f.method === "pauseProducer")).toHaveLength(1);
+    // Paused, not closed: the microphone is still published, just silent.
+    expect(node.received.filter((f) => f.method === "closeProducer")).toHaveLength(0);
+
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+    expect(node.received.filter((f) => f.method === "resumeProducer")).toHaveLength(1);
+    // The whole point: one prompt for the whole call.
+    expect(getUserMedia).toHaveBeenCalledTimes(1);
+    expect(produced).toEqual(["microphone"]);
+  });
+
+  it("shows the name in the local preview while the camera is paused, and explains the light behind a ?", async () => {
+    stubCapture("video");
+    const node = new FakeNode({});
+    const { getByText, getByTestId, getByLabelText, queryByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Start camera")).toBeTruthy());
+    fireEvent.click(getByText("Start camera"));
+    await waitFor(() => expect(getByText("Stop camera")).toBeTruthy());
+    await waitFor(() => expect(getByTestId("tile-local").querySelector("video")).toBeTruthy());
+
+    fireEvent.click(getByText("Stop camera"));
+
+    // What the others see is the name, so that is what the preview shows.
+    await waitFor(() => expect(getByText("Start camera")).toBeTruthy());
+    await waitFor(() => expect(getByTestId("tile-local").querySelector("video")).toBeNull());
+    expect(node.received.filter((f) => f.method === "pauseProducer")).toHaveLength(1);
+    // The camera stays open (the light can stay on), and that is an explanation,
+    // so it lives behind a ? with a name that says what it explains.
+    expect(queryByText(/keeps the camera open/)).toBeNull();
+    fireEvent.click(getByLabelText("What does Stop camera do?"));
+    await waitFor(() => expect(queryByText(/keeps the camera open/)).toBeTruthy());
+  });
+});
+
+/**
+ * The browser can end a share without asking us.
+ *
+ * Chrome and Firefox draw their own "Stop sharing" bar over a screen share.
+ * Nothing about it went near `unpublish`, so the node kept a producer nobody
+ * was feeding, everybody else kept a frozen tile, and this button read "Stop
+ * sharing" about a share that had ended.
+ */
+describe("a screen share stopped from the browser's own bar", () => {
+  it("is unpublished, and the control follows", async () => {
+    const { track } = stubCapture("video");
+    const node = new FakeNode({});
+    const { getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Share screen")).toBeTruthy());
+    fireEvent.click(getByText("Share screen"));
+    await waitFor(() => expect(getByText("Stop sharing")).toBeTruthy());
+
+    track.dispatchEvent(new Event("ended"));
+
+    await waitFor(() => expect(getByText("Share screen")).toBeTruthy());
+    expect(node.received.filter((f) => f.method === "closeProducer")).toHaveLength(1);
+  });
+});
+
+/**
+ * A recovered connection is not a recovered microphone, and the screen says so.
+ *
+ * The drop stops every local capture (right: a light left on over a dead
+ * session is retained capture) and the SDK does not turn it back on by itself
+ * (also right: capture is a permission, and it is the person's press). What
+ * was wrong is that nothing then told them. The room came back, the status
+ * read "Connected", and a coach who had been talking for ten minutes was
+ * talking to nobody until the client asked whether they were still there.
+ */
+describe("what a drop took away is said, once the room is back", () => {
+  it("names the microphone, and stops once it is back on", async () => {
+    stubCapture();
+    const node = new FakeNode({});
+    const { getByText, getByRole, queryByText } = mount(node, <CallStage />, { reconnect: FAST_RECOVERY });
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+
+    node.socket.drop();
+
+    await waitFor(() => expect(node.sockets.length).toBe(2));
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+    // Content, not a hint: this is the thing they have to act on.
+    await waitFor(() => expect(queryByText(/Your microphone was turned off/)).toBeTruthy());
+    expect(getByText("Unmute")).toBeTruthy();
+
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+    await waitFor(() => expect(queryByText(/Your microphone was turned off/)).toBeNull());
+  });
+
+  it("says nothing after a deliberate leave", async () => {
+    stubCapture();
+    const node = new FakeNode({});
+    const { getByText, queryByText } = mount(node, <CallStage />, { reconnect: FAST_RECOVERY });
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+
+    fireEvent.click(getByText("Leave"));
+
+    await settle(30);
+    expect(queryByText(/Your microphone was turned off/)).toBeNull();
+  });
+});