@tribe-nest/forge 3.54.0 → 3.58.0

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;
+};

package/src/ui/media/callState.ts

@@ -241,6 +241,8 @@ export type CallStatus = {
   tone: CallStatusTone;
   /** Always shown. Connection state is CONTENT, never a help hint. `forge.call_stage.*`. */
   headlineKey: string;
+  /** Placeholders for `headlineKey` (a breakout room's name). Absent for every other headline. */
+  headlineVars?: Record<string, string | number>;
   /** Our own second line, when there is one. `forge.call_stage.*`. */
   detailKey?: string;
   /** The server's own words when it has any. Shown verbatim. */
@@ -264,11 +266,32 @@ export type CallStatusInput = {
    * offers a control rather than a spinner.
    */
   recovering?: boolean;
+  /**
+   * A breakout move in flight: the node asked this seat to change rooms
+   * (`RoomState.moving`), or the person pressed Join / Return themselves.
+   * The SDK reports the reconnect with the same `draining` cause a server
+   * drain uses, so without this the pill would say "Moving you to another
+   * server" about a move to Room 2. `name` null means back to the main room.
+   */
+  moving?: BreakoutMove | null;
 };
 
+/** What the stage knows about a move: where to, by display name when it has one. */
+export type BreakoutMove = { room: string; name: string | null };
+
 const ENDED = "forge.call_stage.status_ended";
 const LEFT = "forge.call_stage.status_left";
 
+/**
+ * The headline for a breakout move, shared by the pill and the centre notice
+ * so the two can never disagree about where somebody is going.
+ */
+export function breakoutMoveHeadline(moving: BreakoutMove): Pick<CallStatus, "headlineKey" | "headlineVars"> {
+  return moving.name === null
+    ? { headlineKey: "forge.call_stage.breakouts.status_returning" }
+    : { headlineKey: "forge.call_stage.breakouts.status_moving", headlineVars: { room: moving.name } };
+}
+
 /**
  * The room's states, told honestly.
  *
@@ -338,12 +361,19 @@ export function callStatus(input: CallStatusInput): CallStatus {
       // ordinary deploy would otherwise end every call on that node under a
       // spinner saying nobody was dropped.
       return recovering
-        ? {
-            tone: "reconnecting",
-            headlineKey: "forge.call_stage.status_moving",
-            detailKey: "forge.call_stage.status_moving_detail",
-            canRetry: false,
-          }
+        ? input.moving
+          ? {
+              tone: "reconnecting",
+              ...breakoutMoveHeadline(input.moving),
+              detailKey: "forge.call_stage.breakouts.status_moving_detail",
+              canRetry: false,
+            }
+          : {
+              tone: "reconnecting",
+              headlineKey: "forge.call_stage.status_moving",
+              detailKey: "forge.call_stage.status_moving_detail",
+              canRetry: false,
+            }
         : {
             tone: "failed",
             headlineKey: "forge.call_stage.status_move_failed",
@@ -406,13 +436,15 @@ export function canPublishSource(grants: MediaGrants | undefined, source: Publis
   return mayPublish(grants, { source, trackKind: source === "microphone" ? "audio" : "video" });
 }
 
-export type StageNoticeKind = "joining" | "waiting" | "everyone_left" | "ended" | "failed";
+export type StageNoticeKind = "joining" | "waiting" | "everyone_left" | "moving" | "ended" | "failed";
 
 export type StageNotice = {
   kind: StageNoticeKind;
   /** `forge.call_stage.*` keys. The status pill's copy is reused where the
    * meaning is the same, so the two can never say different things. */
   headlineKey: string;
+  /** Placeholders for `headlineKey`. Only a breakout move has any. */
+  headlineVars?: Record<string, string | number>;
   detailKey?: string;
   /** The server's own sentence, verbatim, exactly as the status line shows it. */
   detailText?: string;
@@ -429,6 +461,18 @@ export type StageNotice = {
  * transient ones (connecting, reconnecting) keep the top pill so the stage
  * behind them stays visible; and an empty live room says "waiting", which is
  * a state, not an error.
+ *
+ * ## Breakout rooms change two answers
+ *
+ * A MOVE between rooms is a leave and a reconnect, so for a second or two the
+ * stage is empty and reconnecting, which without `moving` reads as "everyone
+ * left". The move wins over every non-terminal notice: "Moving you to Room 2"
+ * is the truth, and a terminal state (ended, failed) still wins over it,
+ * because a move that failed is the thing to act on.
+ *
+ * And while rooms are OPEN, an empty stage is "waiting", never "everyone
+ * left": a host who hopped into Room 3 and found nobody there yet did not end
+ * the call, and the people they left in the main room are still on it.
  */
 export function stageNotice(input: {
   status: CallStatus;
@@ -437,33 +481,30 @@ export function stageNotice(input: {
   /** Has anyone else ever been here this session? Separates the room that has
    * not started from the room that just emptied. */
   everSawPeers: boolean;
+  /** A breakout move in flight (`RoomState.moving`, or the person's own press). */
+  moving?: BreakoutMove | null;
+  /** Breakout rooms are open somewhere in this call. */
+  breakoutsActive?: boolean;
 }): StageNotice | null {
   const { status } = input;
 
-  if (status.tone === "connecting") {
-    return { kind: "joining", headlineKey: "forge.call_stage.status_connecting", canRetry: false };
+  if (status.tone === "ended" || status.tone === "failed") {
+    return terminalNotice(status);
   }
-  if (status.tone === "ended") {
+  if (input.moving) {
     return {
-      kind: "ended",
-      headlineKey: status.headlineKey,
-      ...(status.detailKey ? { detailKey: status.detailKey } : {}),
-      ...(status.detailText ? { detailText: status.detailText } : {}),
+      kind: "moving",
+      ...breakoutMoveHeadline(input.moving),
+      detailKey: "forge.call_stage.breakouts.status_moving_detail",
       canRetry: false,
     };
   }
-  if (status.tone === "failed") {
-    return {
-      kind: "failed",
-      headlineKey: status.headlineKey,
-      ...(status.detailKey ? { detailKey: status.detailKey } : {}),
-      ...(status.detailText ? { detailText: status.detailText } : {}),
-      canRetry: status.canRetry,
-    };
+  if (status.tone === "connecting") {
+    return { kind: "joining", headlineKey: "forge.call_stage.status_connecting", canRetry: false };
   }
   // Live or reconnecting: the stage stands. Only an EMPTY one says anything.
   if (input.remoteCount === 0) {
-    return input.everSawPeers
+    return input.everSawPeers && !input.breakoutsActive
       ? { kind: "everyone_left", headlineKey: "forge.call_stage.everyone_left", canRetry: false }
       : {
           kind: "waiting",
@@ -474,3 +515,22 @@ export function stageNotice(input: {
   }
   return null;
 }
+
+function terminalNotice(status: CallStatus): StageNotice {
+  if (status.tone === "ended") {
+    return {
+      kind: "ended",
+      headlineKey: status.headlineKey,
+      ...(status.detailKey ? { detailKey: status.detailKey } : {}),
+      ...(status.detailText ? { detailText: status.detailText } : {}),
+      canRetry: false,
+    };
+  }
+  return {
+    kind: "failed",
+    headlineKey: status.headlineKey,
+    ...(status.detailKey ? { detailKey: status.detailKey } : {}),
+    ...(status.detailText ? { detailText: status.detailText } : {}),
+    canRetry: status.canRetry,
+  };
+}

package/src/ui/media/index.ts

@@ -49,6 +49,9 @@ export {
   useLocalMedia,
   useLocalPublications,
   useMediaRoom,
+  // A breakout move the node asked for (`moveRequested`), until the next join.
+  // `CallStage` reads it; a site laying out its own stage wants it by name.
+  useMoving,
   useParticipants,
   useRecording,
   useRemoteTrack,
@@ -131,6 +134,13 @@ export { PreJoin, type PreJoinProps, type PreJoinSettings } from "./PreJoin";
  */
 export type { CallChatMessage, CallStageChat } from "./callChat";
 
+/**
+ * The breakout-rooms adapter's shape, injected the same way as `chat`. The
+ * public lane's `useCallBreakouts` (from the root entry) produces it; admin
+ * composes its own against the dashboard's client.
+ */
+export type { BreakoutParticipant, BreakoutRoomSummary, CallStageBreakouts } from "./callBreakouts";
+
 /** The reaction vocabulary, shared by the picker and the receive whitelist. */
 export { REACTION_EMOJI, type ReactionEmoji } from "./stage/callSignals";
 
@@ -149,6 +159,7 @@ export {
   callTiles,
   canPublishSource,
   remoteAudioProducerIds,
+  type BreakoutMove,
   type CallStatus,
   type CallStatusInput,
   type CallStatusTone,