@tribe-nest/forge 3.57.0 → 3.58.0

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

@@ -0,0 +1,271 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { translateForge, type ForgeT } from "../../../i18n";
+import type { CallStageBreakouts } from "../callBreakouts";
+import { CallSidePanel, showsRoomsTab } from "../panels/CallSidePanel";
+import type { StageTokens } from "../stage/stageTheme";
+
+/**
+ * The rooms rail, rendered against a fake adapter.
+ *
+ * Three things are worth being sure about here, and none of them is "did it
+ * render": that a call WITHOUT rooms draws exactly the two tabs it always drew,
+ * that the host's controls reach the adapter with the right arguments (an
+ * assignment sent to the wrong room is silent), and that closing every room
+ * takes a second press.
+ */
+
+afterEach(cleanup);
+
+const tokens: StageTokens = {
+  stageBg: "#0c0d10",
+  stageSurface: "#17181d",
+  stageChrome: "#1e2026",
+  stageText: "#f4f5f7",
+  stageMuted: "#9aa0ab",
+  stageBorder: "#2c2f37",
+  accent: "#0b6",
+  accentText: "#fff",
+  danger: "#c00",
+  cornerRadius: 8,
+};
+
+const t: ForgeT = (key, vars) => translateForge("en", key, vars);
+
+const adapter = (over: Partial<CallStageBreakouts> = {}): CallStageBreakouts => ({
+  ready: true,
+  canManage: false,
+  active: false,
+  current: null,
+  main: { participantCount: 0, participants: [] },
+  rooms: [],
+  pending: false,
+  create: vi.fn(async () => undefined),
+  assign: vi.fn(async () => undefined),
+  moveSelf: vi.fn(async () => undefined),
+  closeAll: vi.fn(async () => undefined),
+  refresh: vi.fn(),
+  ...over,
+});
+
+const ROOMS = [
+  {
+    publicId: "room-1",
+    name: "Room 1",
+    position: 1,
+    participantCount: 1,
+    participants: [{ identity: "anna", name: "Anna" }],
+    assigned: [
+      { identity: "anna", name: "Anna" },
+      { identity: "ben", name: "Ben" },
+    ],
+  },
+  { publicId: "room-2", name: "Room 2", position: 2, participantCount: 0, participants: [], assigned: [] },
+];
+
+const mount = (
+  props: { breakouts?: CallStageBreakouts; tab?: "chat" | "people" | "rooms"; onSelfMove?: (id: string | null) => void } = {},
+) => {
+  const onTab = vi.fn();
+  const utils = render(
+    <CallSidePanel
+      tab={props.tab ?? "rooms"}
+      onTab={onTab}
+      onClose={() => undefined}
+      tokens={tokens}
+      t={t}
+      tiles={[]}
+      hands={[]}
+      isHost={!!props.breakouts?.canManage}
+      myIdentity="host-1"
+      onLowerHand={() => undefined}
+      onLowerAll={() => undefined}
+      unread={0}
+      breakouts={props.breakouts}
+      onSelfMove={props.onSelfMove ?? (() => undefined)}
+      movePending={false}
+      moveError={null}
+    />,
+  );
+  return { ...utils, onTab };
+};
+
+describe("the rooms tab exists only when there is something behind it", () => {
+  it("draws no rooms tab and no rooms panel when the page injected no adapter", () => {
+    const { queryByText, queryByTestId, getByTestId } = mount({ breakouts: undefined, tab: "rooms" });
+    expect(showsRoomsTab(undefined)).toBe(false);
+    expect(queryByText("Rooms")).toBeNull();
+    expect(queryByTestId("call-breakouts-panel")).toBeNull();
+    // A rooms tab asked for with nothing behind it falls back to the roster.
+    expect(getByTestId("call-participants-panel")).toBeTruthy();
+  });
+
+  it("hides the tab from an attendee while no room is open, and shows it once one is", () => {
+    expect(showsRoomsTab(adapter({ canManage: false, active: false }))).toBe(false);
+    expect(showsRoomsTab(adapter({ canManage: false, active: true }))).toBe(true);
+    // The host always has it: that is where rooms get created.
+    expect(showsRoomsTab(adapter({ canManage: true, active: false }))).toBe(true);
+  });
+});
+
+describe("the host's view", () => {
+  it("offers the create form while no room is open and sends count and assignment", async () => {
+    const breakouts = adapter({ canManage: true });
+    const { getByLabelText, getByText, queryByTestId } = mount({ breakouts });
+
+    expect(queryByTestId("breakouts-close-all")).toBeNull();
+    fireEvent.change(getByLabelText("Number of rooms"), { target: { value: "3" } });
+    fireEvent.change(getByLabelText("Assign people"), { target: { value: "manual" } });
+    fireEvent.click(getByText("Create rooms"));
+
+    await waitFor(() => expect(breakouts.create).toHaveBeenCalledWith({ count: 3, assign: "manual" }));
+  });
+
+  it("refuses a count outside 1..20 without asking the server", () => {
+    const breakouts = adapter({ canManage: true });
+    const { getByLabelText, getByText } = mount({ breakouts });
+    fireEvent.change(getByLabelText("Number of rooms"), { target: { value: "21" } });
+    expect((getByText("Create rooms") as HTMLButtonElement).disabled).toBe(true);
+    fireEvent.change(getByLabelText("Number of rooms"), { target: { value: "0" } });
+    expect((getByText("Create rooms") as HTMLButtonElement).disabled).toBe(true);
+    expect(breakouts.create).not.toHaveBeenCalled();
+  });
+
+  it("lists the main room and every room with live counts, arrivals and the people on their way", () => {
+    const breakouts = adapter({
+      canManage: true,
+      active: true,
+      main: { participantCount: 2, participants: [{ identity: "host-1", name: "Host" }, { identity: "carla", name: "Carla" }] },
+      rooms: ROOMS,
+    });
+    const { getByTestId } = mount({ breakouts });
+
+    const main = getByTestId("breakouts-room-main");
+    expect(main.textContent).toContain("Main room");
+    expect(main.textContent).toContain("2 in this room");
+    expect(main.textContent).toContain("Host (you)");
+    expect(main.textContent).toContain("Carla");
+
+    const room1 = getByTestId("breakouts-room-room-1");
+    expect(room1.textContent).toContain("Room 1");
+    expect(room1.textContent).toContain("1 in this room");
+    expect(room1.textContent).toContain("Anna");
+    // Assigned, not yet arrived: listed where they are GOING, and said so.
+    expect(room1.textContent).toContain("Ben (on the way)");
+
+    expect(getByTestId("breakouts-room-room-2").textContent).toContain("Nobody here yet");
+  });
+
+  it("assigns a person through the select beside their name, and never offers one for the host themselves", async () => {
+    const breakouts = adapter({
+      canManage: true,
+      active: true,
+      main: { participantCount: 2, participants: [{ identity: "host-1", name: "Host" }, { identity: "carla", name: "Carla" }] },
+      rooms: ROOMS,
+    });
+    const { getByLabelText, queryByLabelText } = mount({ breakouts });
+
+    fireEvent.change(getByLabelText("Move Carla to a room"), { target: { value: "room-2" } });
+    await waitFor(() => expect(breakouts.assign).toHaveBeenCalledWith("carla", "room-2"));
+
+    // Back to main is `null`, not the empty string the option carries.
+    fireEvent.change(getByLabelText("Move Anna to a room"), { target: { value: "" } });
+    await waitFor(() => expect(breakouts.assign).toHaveBeenCalledWith("anna", null));
+
+    // The host moves themselves with Join, never by reassigning their own row.
+    expect(queryByLabelText("Move Host to a room")).toBeNull();
+  });
+
+  it("joins a room through the stage's self-move, and marks the room the host is in", () => {
+    const onSelfMove = vi.fn();
+    const breakouts = adapter({ canManage: true, active: true, current: { publicId: "room-1", name: "Room 1" }, rooms: ROOMS });
+    const { getByTestId, queryByTestId } = mount({ breakouts, onSelfMove });
+
+    // In Room 1: no Join for it, a marker instead; Join for the other room and
+    // Return to main for the main room.
+    expect(queryByTestId("breakouts-join-room-1")).toBeNull();
+    expect(getByTestId("breakouts-room-room-1").textContent).toContain("You are here");
+
+    fireEvent.click(getByTestId("breakouts-join-room-2"));
+    expect(onSelfMove).toHaveBeenCalledWith("room-2");
+    fireEvent.click(getByTestId("breakouts-join-main"));
+    expect(onSelfMove).toHaveBeenCalledWith(null);
+    // The panel does not touch the adapter for a self-move; the stage does.
+    expect(breakouts.moveSelf).not.toHaveBeenCalled();
+  });
+
+  it("closes every room only after the warning has been confirmed", async () => {
+    const breakouts = adapter({ canManage: true, active: true, rooms: ROOMS });
+    const { getByTestId, getByText, queryByTestId, queryByText } = mount({ breakouts });
+
+    // The warning is not on screen until the control is pressed.
+    expect(queryByText(/Everyone comes back to the main room/)).toBeNull();
+    fireEvent.click(getByTestId("breakouts-close-all"));
+    expect(breakouts.closeAll).not.toHaveBeenCalled();
+    // Visible as content: a warning about what a control is about to do is
+    // never a `?` hint.
+    expect(getByText(/Everyone comes back to the main room/)).toBeTruthy();
+
+    fireEvent.click(getByText("Keep them open"));
+    expect(breakouts.closeAll).not.toHaveBeenCalled();
+    expect(queryByTestId("breakouts-close-confirm")).toBeNull();
+
+    fireEvent.click(getByTestId("breakouts-close-all"));
+    fireEvent.click(getByTestId("breakouts-close-confirm"));
+    await waitFor(() => expect(breakouts.closeAll).toHaveBeenCalledTimes(1));
+  });
+
+  it("shows the server's own sentence when an action is refused", async () => {
+    const breakouts = adapter({
+      canManage: true,
+      create: vi.fn(async () => {
+        throw new Error("Rooms are already open.");
+      }),
+    });
+    const { getByText, getByTestId } = mount({ breakouts });
+    fireEvent.click(getByText("Create rooms"));
+    await waitFor(() => expect(getByTestId("breakouts-error").textContent).toBe("Rooms are already open."));
+  });
+
+  it("keeps the explanation behind a `?` with a name that says what it explains", async () => {
+    const { getByLabelText, queryByText } = mount({ breakouts: adapter({ canManage: true }) });
+    expect(queryByText(/Each room is a separate call/)).toBeNull();
+    fireEvent.click(getByLabelText("What happens when I create rooms?"));
+    await waitFor(() => expect(queryByText(/Each room is a separate call/)).toBeTruthy());
+  });
+});
+
+describe("the attendee's view", () => {
+  it("says where you are, lists the rooms, and offers no host control", () => {
+    const breakouts = adapter({ canManage: false, active: true, current: { publicId: "room-2", name: "Room 2" }, rooms: ROOMS });
+    const { getByTestId, queryByTestId, queryByLabelText, queryByText } = mount({ breakouts });
+
+    expect(getByTestId("breakouts-where").textContent).toBe("You are in Room 2");
+    expect(queryByText("Room 1")).toBeTruthy();
+    expect(queryByText("Main room")).toBeTruthy();
+    expect(queryByTestId("breakouts-close-all")).toBeNull();
+    expect(queryByTestId("breakouts-create")).toBeNull();
+    expect(queryByLabelText(/Move .* to a room/)).toBeNull();
+  });
+
+  it("offers Return to main room only while in a breakout, and routes it through the stage", () => {
+    const onSelfMove = vi.fn();
+    const inRoom = adapter({ canManage: false, active: true, current: { publicId: "room-2", name: "Room 2" }, rooms: ROOMS });
+    const { getByTestId, unmount } = mount({ breakouts: inRoom, onSelfMove });
+    fireEvent.click(getByTestId("breakouts-return-main"));
+    expect(onSelfMove).toHaveBeenCalledWith(null);
+    unmount();
+
+    const inMain = adapter({ canManage: false, active: true, current: null, rooms: ROOMS });
+    const { queryByTestId, getByTestId: get } = mount({ breakouts: inMain });
+    expect(queryByTestId("breakouts-return-main")).toBeNull();
+    expect(get("breakouts-where").textContent).toBe("You are in the main room");
+  });
+
+  it("says it is loading before the first describe has landed", () => {
+    const { getByText } = mount({ breakouts: adapter({ ready: false, active: true }) });
+    expect(getByText("Loading rooms…")).toBeTruthy();
+  });
+});

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

@@ -0,0 +1,212 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+
+import { MediaRoom, type MediaDevice, type MediaTransport } from "@tribe-nest/media-client";
+import { MediaRoomProvider } from "@tribe-nest/media-client/react";
+
+import { ForgeI18nProvider } from "../../../i18n";
+import { ForgeThemeProvider, type ForgeTheme } from "../../theme/ForgeThemeProvider";
+import type { CallStageBreakouts } from "../callBreakouts";
+import { CallStage } from "../CallStage";
+import { FakeNode, settle } from "./fakeNode";
+
+/**
+ * Breakout rooms on the STAGE: the controls bar and the centre notice.
+ *
+ * `CallBreakoutsPanel.spec.tsx` covers the rail against a fake adapter; this
+ * file covers what the orchestrator adds around it, driven through a real
+ * `<MediaRoomProvider>` the way `CallStage.spec.tsx` is, because the two
+ * decisions worth pinning here (nothing drawn without the prop, and "waiting"
+ * rather than "everyone left" while rooms are open) live in the join between
+ * the room's state and the stage.
+ */
+
+afterEach(() => {
+  cleanup();
+  delete (navigator as { mediaDevices?: unknown }).mediaDevices;
+});
+
+beforeAll(() => {
+  if (!("MediaStream" in globalThis)) {
+    (globalThis as { MediaStream?: unknown }).MediaStream = class {
+      constructor(readonly tracks: unknown[] = []) {}
+    };
+  }
+});
+
+const fakeTransport = (): MediaTransport => ({
+  id: "t-1",
+  async produce() {
+    return { id: "p-local", kind: "audio", closed: false, replaceTrack: vi.fn(async () => undefined), 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(),
+});
+
+const fakeDevice = (): MediaDevice => ({
+  async load() {},
+  loaded: true,
+  rtpCapabilities: { codecs: [] } as never,
+  canProduce: () => true,
+  createSendTransport: () => fakeTransport(),
+  createRecvTransport: () => fakeTransport(),
+});
+
+const theme: ForgeTheme = { colors: { text: "#101010", background: "#fafafa", primary: "#0b6", surface: "#eeeeee" }, cornerRadius: 10 };
+
+const mount = (node: FakeNode, children: ReactNode) =>
+  render(
+    <ForgeI18nProvider locale="en">
+      <ForgeThemeProvider theme={theme}>
+        <MediaRoomProvider
+          getCredentials={() => ({ mediaUrl: "wss://media.example", token: "t" })}
+          device={fakeDevice}
+          webSocket={node.factory}
+          autoSubscribe={false}
+          reconnect={{ baseMs: 1, maxMs: 4, factor: 1, jitter: "none" }}
+        >
+          {children}
+        </MediaRoomProvider>
+      </ForgeThemeProvider>
+    </ForgeI18nProvider>,
+  );
+
+const adapter = (over: Partial<CallStageBreakouts> = {}): CallStageBreakouts => ({
+  ready: true,
+  canManage: false,
+  active: false,
+  current: null,
+  main: { participantCount: 0, participants: [] },
+  rooms: [{ publicId: "room-1", name: "Room 1", position: 1, participantCount: 0, participants: [], assigned: [] }],
+  pending: false,
+  create: vi.fn(async () => undefined),
+  assign: vi.fn(async () => undefined),
+  moveSelf: vi.fn(async () => undefined),
+  closeAll: vi.fn(async () => undefined),
+  refresh: vi.fn(),
+  ...over,
+});
+
+/**
+ * Layer B of the breakout contract ships `MediaRoom.moveTo()` and the
+ * `moveRequested` reducer case in `@tribe-nest/media-client`. The cases that
+ * need the SDK's half are skipped, not failed, until that build is in the
+ * tree; they light up on their own the moment it is.
+ */
+const sdkMoves = typeof (MediaRoom.prototype as unknown as { moveTo?: unknown }).moveTo === "function";
+
+describe("without the prop, the stage is the stage it was", () => {
+  it("draws no Rooms button, no Return to main, and no rooms tab", async () => {
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId, queryByTestId, queryByText } = mount(node, <CallStage />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    expect(queryByTestId("toggle-rooms")).toBeNull();
+    expect(queryByTestId("return-to-main")).toBeNull();
+    fireEvent.click(getByTestId("toggle-people"));
+    await waitFor(() => expect(getByTestId("call-side-panel")).toBeTruthy());
+    expect(queryByText("Rooms")).toBeNull();
+  });
+
+  it("still says everyone left when the room empties", async () => {
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId } = mount(node, <CallStage />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+    node.event({ event: "peerLeft", identity: "anna" });
+    await waitFor(() => expect(getByTestId("stage-notice-everyone_left")).toBeTruthy());
+  });
+});
+
+describe("the controls bar", () => {
+  it("offers Return to main only to somebody in a breakout room, and it writes the assignment first", async () => {
+    const breakouts = adapter({ active: true, current: { publicId: "room-1", name: "Room 1" } });
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId } = mount(node, <CallStage breakouts={breakouts} />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    fireEvent.click(getByTestId("return-to-main"));
+    // The assignment is written BEFORE the reconnect: the next ticket is
+    // minted for whatever the assignment says, so this order is the move.
+    await waitFor(() => expect(breakouts.moveSelf).toHaveBeenCalledWith(null));
+  });
+
+  it("offers no Return to main in the main room, and a Rooms button once rooms exist", async () => {
+    const breakouts = adapter({ active: true, current: null });
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId, queryByTestId } = mount(node, <CallStage breakouts={breakouts} />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    expect(queryByTestId("return-to-main")).toBeNull();
+    fireEvent.click(getByTestId("toggle-rooms"));
+    await waitFor(() => expect(getByTestId("call-breakouts-panel")).toBeTruthy());
+    expect(getByTestId("breakouts-where").textContent).toBe("You are in the main room");
+    // An attendee's list is read when the tab opens; the adapter does not poll for them.
+    expect(breakouts.refresh).toHaveBeenCalled();
+  });
+
+  it("gives the host the Rooms button before any room exists, and the create form behind it", async () => {
+    const breakouts = adapter({ canManage: true, active: false, rooms: [] });
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId } = mount(node, <CallStage breakouts={breakouts} isHost />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    fireEvent.click(getByTestId("toggle-rooms"));
+    await waitFor(() => expect(getByTestId("breakouts-create")).toBeTruthy());
+  });
+});
+
+describe("the centre of the stage while rooms are open", () => {
+  it("says WAITING, not everyone left, when the host finds an empty room", async () => {
+    const breakouts = adapter({ canManage: true, active: true, current: { publicId: "room-1", name: "Room 1" } });
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId, queryByTestId } = mount(node, <CallStage breakouts={breakouts} isHost />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    node.event({ event: "peerLeft", identity: "anna" });
+    await waitFor(() => expect(getByTestId("stage-notice-waiting")).toBeTruthy());
+    expect(queryByTestId("stage-notice-everyone_left")).toBeNull();
+  });
+
+  it.skipIf(!sdkMoves)("says where you are being moved when the node asks you to change rooms", async () => {
+    const breakouts = adapter({ active: true });
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId } = mount(node, <CallStage breakouts={breakouts} />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    node.event({ event: "moveRequested", room: "booking-1~b1", name: "Room 1" });
+
+    const notice = await waitFor(() => getByTestId("stage-notice-moving"));
+    expect(notice.textContent).toContain("Moving you to Room 1");
+    // The SDK leaves and reconnects with a fresh ticket: a SECOND socket.
+    await waitFor(() => expect(node.sockets.length).toBe(2));
+    await settle(30);
+    // Back in a room, the assignment view is re-read.
+    await waitFor(() => expect(breakouts.refresh).toHaveBeenCalled());
+  });
+
+  it.skipIf(!sdkMoves)("moves you itself after Return to main, and names the destination while it does", async () => {
+    const breakouts = adapter({ active: true, current: { publicId: "room-1", name: "Room 1" } });
+    const node = new FakeNode({ peers: [{ identity: "anna", name: "Anna" }] });
+    const { getByTestId } = mount(node, <CallStage breakouts={breakouts} />);
+    await waitFor(() => expect(getByTestId("tile-anna")).toBeTruthy());
+
+    fireEvent.click(getByTestId("return-to-main"));
+
+    const notice = await waitFor(() => getByTestId("stage-notice-moving"));
+    expect(notice.textContent).toContain("Returning you to the main room");
+    await waitFor(() => expect(node.sockets.length).toBe(2));
+    await waitFor(() => expect(breakouts.refresh).toHaveBeenCalled());
+  });
+});

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

@@ -4,7 +4,15 @@ 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, stageNotice } from "../callState";
+import {
+  breakoutMoveHeadline,
+  callHeadCount,
+  callStatus,
+  callTiles,
+  canPublishSource,
+  remoteAudioProducerIds,
+  stageNotice,
+} from "../callState";
 
 /**
  * The two decisions a call screen gets wrong.
@@ -298,6 +306,14 @@ describe("callStatus is honest about what is happening", () => {
       { connectionState: "reconnecting", error: { type: "room_closed", reason: "x" } },
       { connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 1 }, recovering: true },
       { connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 1 } },
+      // A breakout move rides the draining cause; both of its headlines must exist too.
+      {
+        connectionState: "reconnecting",
+        error: { type: "draining", reconnectAfterMs: 0 },
+        recovering: true,
+        moving: { room: "r~b2", name: "Room 2" },
+      },
+      { connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 0 }, recovering: true, moving: { room: "r", name: null } },
       { connectionState: "reconnecting", error: { type: "closed_by_client" } },
       { connectionState: "reconnecting", error: { type: "socket_closed" }, recovering: true },
       { connectionState: "reconnecting", error: { type: "socket_closed" } },
@@ -548,6 +564,92 @@ describe("stageNotice: the ONE decision for the centre of the stage", () => {
       }),
     ).toBeNull();
   });
+
+  /**
+   * Breakout rooms.
+   *
+   * A move between rooms is a leave and a reconnect, and for the second it
+   * takes the stage is empty. Read without knowing about the move, that is
+   * "everyone else has left the call" over a call nobody left, at exactly the
+   * moment the person is being sent somewhere.
+   */
+  describe("with breakout rooms", () => {
+    const reconnecting = status({ tone: "reconnecting", headlineKey: "forge.call_stage.status_moving" });
+
+    it("says where you are going, and that wins over the empty-stage notices", () => {
+      const toRoom = stageNotice({ status: reconnecting, remoteCount: 0, everSawPeers: true, moving: { room: "r~b2", name: "Room 2" } });
+      expect(toRoom).toMatchObject({
+        kind: "moving",
+        headlineKey: "forge.call_stage.breakouts.status_moving",
+        headlineVars: { room: "Room 2" },
+        canRetry: false,
+      });
+      expect(translateForge("en", toRoom!.headlineKey, toRoom!.headlineVars)).toBe("Moving you to Room 2");
+
+      // The same move while still connected (the frame landed, the leave has
+      // not finished) and while alone: the move is the truth in both.
+      expect(stageNotice({ status: status(), remoteCount: 3, everSawPeers: true, moving: { room: "r~b2", name: "Room 2" } })?.kind).toBe("moving");
+      expect(stageNotice({ status: status(), remoteCount: 0, everSawPeers: false, moving: { room: "r~b2", name: "Room 2" } })?.kind).toBe("moving");
+    });
+
+    it("says you are coming back when the move has no room name", () => {
+      const home = stageNotice({ status: reconnecting, remoteCount: 0, everSawPeers: true, moving: { room: "r", name: null } });
+      expect(home).toMatchObject({ kind: "moving", headlineKey: "forge.call_stage.breakouts.status_returning" });
+      expect(home!.headlineVars).toBeUndefined();
+      expect(translateForge("en", home!.headlineKey)).toBe("Returning you to the main room");
+    });
+
+    it("does NOT let a move hide a terminal state", () => {
+      // A move that failed (the rejoin was refused) is the thing to act on; a
+      // spinner saying "Moving you to Room 2" over it is the promise nobody
+      // is keeping.
+      const failed = stageNotice({
+        status: status({ tone: "failed", headlineKey: "forge.call_stage.status_move_failed", canRetry: true }),
+        remoteCount: 0,
+        everSawPeers: true,
+        moving: { room: "r~b2", name: "Room 2" },
+      });
+      expect(failed).toMatchObject({ kind: "failed", canRetry: true });
+      const ended = stageNotice({
+        status: status({ tone: "ended", headlineKey: "forge.call_stage.status_ended" }),
+        remoteCount: 0,
+        everSawPeers: true,
+        moving: { room: "r~b2", name: "Room 2" },
+      });
+      expect(ended?.kind).toBe("ended");
+    });
+
+    it("reads an empty stage as WAITING while rooms are open, never as everyone having left", () => {
+      // The host hopped into Room 3 before anyone arrived: the people they left
+      // in the main room are still on the call.
+      expect(stageNotice({ status: status(), remoteCount: 0, everSawPeers: true, breakoutsActive: true })?.kind).toBe("waiting");
+      // And without open rooms the old answer stands.
+      expect(stageNotice({ status: status(), remoteCount: 0, everSawPeers: true, breakoutsActive: false })?.kind).toBe("everyone_left");
+      expect(stageNotice({ status: status(), remoteCount: 0, everSawPeers: true })?.kind).toBe("everyone_left");
+      // People on stage: nothing to say, rooms or not.
+      expect(stageNotice({ status: status(), remoteCount: 1, everSawPeers: true, breakoutsActive: true })).toBeNull();
+    });
+
+    it("gives the status pill the same destination as the centre", () => {
+      // The SDK reports a breakout move with the draining cause a server drain
+      // uses, so without `moving` the pill says "Moving you to another server"
+      // about a move to Room 2.
+      const drain = callStatus({ connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 0 }, recovering: true });
+      const move = callStatus({
+        connectionState: "reconnecting",
+        error: { type: "draining", reconnectAfterMs: 0 },
+        recovering: true,
+        moving: { room: "r~b2", name: "Room 2" },
+      });
+      expect(drain.headlineKey).toBe("forge.call_stage.status_moving");
+      expect(move).toMatchObject({ tone: "reconnecting", canRetry: false, ...breakoutMoveHeadline({ room: "r~b2", name: "Room 2" }) });
+      expect(translateForge("de", move.headlineKey, move.headlineVars)).toBe("Du wirst in Room 2 verschoben");
+      // A move whose rejoin nothing is retrying is a failure like any other drain's.
+      expect(
+        callStatus({ connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 0 }, moving: { room: "r", name: null } }).tone,
+      ).toBe("failed");
+    });
+  });
 });
 
 describe("tiles carry their source, and a share never displaces the face", () => {

package/src/ui/media/callBreakouts.ts

@@ -0,0 +1,57 @@
+/**
+ * The breakout-rooms adapter the stage renders, injected like `chat`.
+ *
+ * A PROP rather than something the stage fetches, for the same reason the chat
+ * adapter is one: the three surfaces authenticate differently and the admin
+ * dashboard mounts no `ForgeProvider`, so nothing inside the stage may touch
+ * an HTTP client. The page composes its lane's hook into THIS shape;
+ * `useCallBreakouts` (public lane) is the reference implementation and admin
+ * wires `useAdminCallBreakouts` against the same shape.
+ *
+ * ## What a breakout is, from the stage's side
+ *
+ * A child room under the call's main room. The join address never changes:
+ * the SDK keeps minting on the parent's public id and the backend answers with
+ * a token for whichever room this seat is assigned to. So a move is nothing
+ * more than "write the assignment, then leave and reconnect", which is what
+ * `moveSelf` followed by `room.moveTo()` does, and why `moveSelf` resolves
+ * once the ASSIGNMENT is written rather than once the person has arrived.
+ *
+ * Nothing here decides who may do what: `canManage` is a rendering hint and
+ * the server resolves the seat again on every call. A non-host asking for a
+ * host action gets the same 404 every other refusal on the call address gives.
+ */
+export type BreakoutParticipant = { identity: string; name: string | null };
+
+export type BreakoutRoomSummary = {
+  publicId: string;
+  name: string;
+  position: number;
+  /** Live, from the plane snapshot. Host only; attendees always read 0. */
+  participantCount: number;
+  /** Live. Host only; attendees always read an empty list. */
+  participants: readonly BreakoutParticipant[];
+  /** From the assignment table: who is MEANT to be here, arrived or not. */
+  assigned: readonly BreakoutParticipant[];
+};
+
+export type CallStageBreakouts = {
+  /** False until the first describe has landed; the panel says so. */
+  ready: boolean;
+  /** This seat is the host. A rendering hint; the server decides. */
+  canManage: boolean;
+  /** Any room is open right now. */
+  active: boolean;
+  /** The room this seat is assigned to. `null` is the main room. */
+  current: { publicId: string; name: string } | null;
+  main: { participantCount: number; participants: readonly BreakoutParticipant[] };
+  rooms: readonly BreakoutRoomSummary[];
+  /** A request is in flight. Holds the controls rather than letting one be pressed twice. */
+  pending: boolean;
+  create: (input: { count: number; assign: "auto" | "manual" }) => Promise<void>;
+  assign: (identity: string, roomPublicId: string | null) => Promise<void>;
+  /** Self-move. Resolves once the ASSIGNMENT is written; the stage then calls room.moveTo(). */
+  moveSelf: (roomPublicId: string | null) => Promise<void>;
+  closeAll: () => Promise<void>;
+  refresh: () => void;
+};