@tribe-nest/forge 3.42.1 → 3.48.0

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

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+
+import type { CallTile } from "../callState";
+import { gridShape, paginate, pickDominant, presentingTile, resolveLayout, gridShapeNarrow } from "../stage/callLayout";
+
+/**
+ * The layout engine, exhaustively. The layout decides what the viewport
+ * reports, and the viewport decides what the room subscribes to, so a wrong
+ * answer here is not a cosmetic bug: it is bandwidth spent on tiles nobody
+ * sees or a face that silently never arrives.
+ */
+
+const tile = (identity: string, over: Partial<CallTile> = {}): CallTile => ({
+  key: `${identity}#camera`,
+  identity,
+  name: identity,
+  kind: "human",
+  source: "camera",
+  isSpeaking: false,
+  videoPaused: false,
+  hasAudio: true,
+  audioMuted: false,
+  videoProducerId: `v-${identity}`,
+  ...over,
+});
+
+const people = (count: number): CallTile[] => Array.from({ length: count }, (_, i) => tile(`p-${String(i).padStart(2, "0")}`));
+
+const layoutOf = (tiles: CallTile[], over: Partial<Parameters<typeof resolveLayout>[0]> = {}) =>
+  resolveLayout({
+    tiles,
+    view: "gallery",
+    page: 0,
+    pinnedKey: null,
+    dominantIdentity: null,
+    localPresenting: false,
+    ...over,
+  });
+
+describe("gridShape", () => {
+  it("keeps grids even: 2 across, then 2x2, 3x2, 4x2, never a ragged square", () => {
+    expect(gridShape(1)).toEqual({ columns: 1, rows: 1 });
+    expect(gridShape(2)).toEqual({ columns: 2, rows: 1 });
+    expect(gridShape(3)).toEqual({ columns: 2, rows: 2 });
+    expect(gridShape(4)).toEqual({ columns: 2, rows: 2 });
+    expect(gridShape(6)).toEqual({ columns: 3, rows: 2 });
+    expect(gridShape(8)).toEqual({ columns: 4, rows: 2 });
+  });
+
+  it("stacks into PORTRAITS on a phone: one column up to two people, two columns above", () => {
+    expect(gridShapeNarrow(1)).toEqual({ columns: 1, rows: 1 });
+    // The case the whole change is for: two people are ONE column, a row each,
+    // not side by side.
+    expect(gridShapeNarrow(2)).toEqual({ columns: 1, rows: 2 });
+    expect(gridShapeNarrow(3)).toEqual({ columns: 2, rows: 2 });
+    expect(gridShapeNarrow(4)).toEqual({ columns: 2, rows: 2 });
+    expect(gridShapeNarrow(5)).toEqual({ columns: 2, rows: 3 });
+  });
+});
+
+describe("paginate", () => {
+  it("pages at the size and clamps a stranded page when people leave", () => {
+    const items = ["a", "b", "c", "d", "e"];
+    expect(paginate(items, 0, 2)).toEqual({ items: ["a", "b"], page: 0, pageCount: 3 });
+    expect(paginate(items, 2, 2)).toEqual({ items: ["e"], page: 2, pageCount: 3 });
+    // The room shrank under a viewer parked on page 5: they land on the last
+    // real page rather than an empty one.
+    expect(paginate(items, 5, 2)).toEqual({ items: ["e"], page: 2, pageCount: 3 });
+    expect(paginate([], 3, 2)).toEqual({ items: [], page: 0, pageCount: 1 });
+  });
+});
+
+describe("pickDominant", () => {
+  it("holds the incumbent through the hold window, then yields", () => {
+    const speakers = [{ identity: "b", producerId: "a-b", volumeDb: -20 }];
+    // A new leader inside the hold does not take over...
+    expect(pickDominant({ speakers, previous: "a", previousSince: 1000, now: 2000, holdMs: 1500 })).toEqual({
+      identity: "a",
+      since: 1000,
+    });
+    // ...and does once the hold has run out.
+    expect(pickDominant({ speakers, previous: "a", previousSince: 1000, now: 2600, holdMs: 1500 })).toEqual({
+      identity: "b",
+      since: 2600,
+    });
+    // Silence keeps whoever was last dominant rather than emptying the stage.
+    expect(pickDominant({ speakers: [], previous: "a", previousSince: 1000, now: 9000 })).toEqual({
+      identity: "a",
+      since: 1000,
+    });
+  });
+});
+
+describe("resolveLayout", () => {
+  it("renders exactly one remote person as the duo, whatever the toggle says", () => {
+    const layout = layoutOf([tile("anna")], { view: "speaker" });
+    expect(layout.mode).toBe("duo");
+    expect(layout.pageTiles.map((t) => t.identity)).toEqual(["anna"]);
+    expect(layout.columns).toBe(2);
+  });
+
+  it("STACKS the duo on a phone: one column, a row each, never side by side", () => {
+    const layout = layoutOf([tile("anna")], { narrow: true });
+    expect(layout.mode).toBe("duo");
+    // One remote + the local self-view = two cells, stacked as portraits.
+    expect(layout.columns).toBe(1);
+    expect(layout.rows).toBe(2);
+  });
+
+  it("narrows the gallery to two columns on a phone", () => {
+    const layout = layoutOf(people(6), { narrow: true });
+    expect(layout.mode).toBe("gallery");
+    expect(layout.columns).toBe(2);
+    expect(layout.rows).toBe(3);
+  });
+
+  it("pages the gallery at 8 and reports 12 people as two pages", () => {
+    const layout = layoutOf(people(12));
+    expect(layout.mode).toBe("gallery");
+    expect(layout.pageTiles).toHaveLength(8);
+    expect(layout.pageCount).toBe(2);
+    expect(layout.columns).toBe(4);
+
+    const second = layoutOf(people(12), { page: 1 });
+    expect(second.pageTiles).toHaveLength(4);
+    expect(second.page).toBe(1);
+  });
+
+  it("forces the stage the moment ANY screen share exists, presenter named", () => {
+    const tiles = [...people(6), tile("anna", { key: "anna#screen", source: "screen", videoProducerId: "s-anna", name: "Anna" })];
+    const layout = layoutOf(tiles, { view: "gallery" });
+    expect(layout.mode).toBe("presenting");
+    expect(layout.main?.videoProducerId).toBe("s-anna");
+    expect(layout.presenter).toEqual({ identity: "anna", name: "Anna" });
+    // The rail shows 4 faces, not 8: the share suppresses camera demand,
+    // which is where the capacity saving actually comes from.
+    expect(layout.pageTiles).toHaveLength(4);
+  });
+
+  it("keeps the presenting mode for the viewer's OWN share, with no main tile", () => {
+    const layout = layoutOf(people(3), { localPresenting: true });
+    expect(layout.mode).toBe("presenting");
+    expect(layout.main).toBeUndefined();
+  });
+
+  it("puts a pinned tile on the stage ahead of the view toggle", () => {
+    const layout = layoutOf(people(5), { pinnedKey: "p-03#camera", view: "gallery" });
+    expect(layout.mode).toBe("speaker");
+    expect(layout.main?.identity).toBe("p-03");
+    expect(layout.pageTiles.some((t) => t.identity === "p-03")).toBe(false);
+  });
+
+  it("orders the speaker rail dominant-first without touching gallery order", () => {
+    const speaker = layoutOf(people(6), { view: "speaker", dominantIdentity: "p-04" });
+    expect(speaker.mode).toBe("speaker");
+    expect(speaker.main?.identity).toBe("p-04");
+
+    // The gallery does NOT reshuffle on dominance: a grid that reorders
+    // itself every time somebody talks moves people out from under the eye.
+    const gallery = layoutOf(people(6), { dominantIdentity: "p-04" });
+    expect(gallery.pageTiles.map((t) => t.identity)).toEqual(people(6).map((t) => t.identity));
+  });
+
+  it("names speakers whose tile the current page does not show", () => {
+    const tiles = people(12).map((t, i) => (i === 10 ? { ...t, isSpeaking: true } : t));
+    const layout = layoutOf(tiles, { page: 0 });
+    expect(layout.offPageSpeakerNames).toEqual(["p-10"]);
+    // On their own page they are shown, so nothing is announced.
+    expect(layoutOf(tiles, { page: 1 }).offPageSpeakerNames).toEqual([]);
+  });
+});
+
+describe("presentingTile", () => {
+  it("finds a share only when it carries video, deterministically by key", () => {
+    expect(presentingTile(people(3))).toBeUndefined();
+    const twoShares = [
+      tile("b", { key: "b#screen", source: "screen", videoProducerId: "s-b" }),
+      tile("a", { key: "a#screen", source: "screen", videoProducerId: "s-a" }),
+    ];
+    expect(presentingTile(twoShares)?.videoProducerId).toBe("s-a");
+  });
+});

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  cullReactions,
+  diffPeers,
+  isKnownReaction,
+  laneFor,
+  orderHands,
+  reactionGate,
+  unreadCount,
+  type FlyingReaction,
+} from "../stage/callSignals";
+
+describe("reactions", () => {
+  it("whitelists what may fly: a hostile peer cannot animate arbitrary text", () => {
+    expect(isKnownReaction("👏")).toBe(true);
+    expect(isKnownReaction("<script>")).toBe(false);
+    expect(isKnownReaction(42)).toBe(false);
+  });
+
+  it("gates our own sends to one per half second", () => {
+    expect(reactionGate(null, 1000)).toBe(true);
+    expect(reactionGate(1000, 1200)).toBe(false);
+    expect(reactionGate(1000, 1600)).toBe(true);
+  });
+
+  it("culls by age and caps the flood, keeping the newest", () => {
+    const flying = (id: number, at: number): FlyingReaction => ({ id: String(id), emoji: "👏", identity: "x", lane: 0, at });
+    const aged = [flying(1, 0), flying(2, 3000)];
+    expect(cullReactions(aged, 5000).map((r) => r.id)).toEqual(["2"]);
+
+    const flood = Array.from({ length: 40 }, (_, i) => flying(i, 1000));
+    const culled = cullReactions(flood, 1001, 4000, 30);
+    expect(culled).toHaveLength(30);
+    expect(culled[0]?.id).toBe("10");
+  });
+
+  it("derives a stable lane from the id, in range", () => {
+    expect(laneFor("abc")).toBe(laneFor("abc"));
+    for (const id of ["a", "bb", "ccc"]) {
+      const lane = laneFor(id);
+      expect(lane).toBeGreaterThanOrEqual(0);
+      expect(lane).toBeLessThan(1);
+    }
+  });
+});
+
+describe("orderHands", () => {
+  it("is the queue: oldest first, identity as the tiebreak", () => {
+    const ordered = orderHands([
+      { identity: "b", raisedAt: 200 },
+      { identity: "c", raisedAt: 100 },
+      { identity: "a", raisedAt: 200 },
+    ]);
+    expect(ordered.map((h) => h.identity)).toEqual(["c", "a", "b"]);
+  });
+});
+
+describe("diffPeers", () => {
+  it("reports arrivals and departures, and never the recorder", () => {
+    const before = [
+      { identity: "a", name: "Ada", kind: "human" as const },
+      { identity: "gone", kind: "human" as const },
+    ];
+    const after = [
+      { identity: "a", name: "Ada", kind: "human" as const },
+      { identity: "new", name: "Newt", kind: "human" as const },
+      { identity: "rec-1", kind: "egress" as const },
+    ];
+    expect(diffPeers(before, after)).toEqual([
+      { identity: "new", name: "Newt", kind: "joined" },
+      { identity: "gone", name: "gone", kind: "left" },
+    ]);
+  });
+});
+
+describe("unreadCount", () => {
+  it("counts by position after the watermark, whole list when never read", () => {
+    const ids = ["m1", "m2", "m3"];
+    expect(unreadCount(ids, null)).toBe(3);
+    expect(unreadCount(ids, "m2")).toBe(1);
+    expect(unreadCount(ids, "m3")).toBe(0);
+    // A watermark for a message that was deleted counts everything: honest,
+    // and self-corrects the moment the panel is opened.
+    expect(unreadCount(ids, "gone")).toBe(3);
+  });
+});

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

@@ -4,7 +4,7 @@ import type { ProducerEntry } from "@tribe-nest/media-client";
 import type { Peer } from "@tribe-nest/media-protocol";
 
 import { FORGE_LOCALES, getForgeMessages, translateForge } from "../../../i18n";
-import { callHeadCount, callStatus, callTiles, canPublishSource, remoteAudioProducerIds } from "../callState";
+import { callHeadCount, callStatus, callTiles, canPublishSource, remoteAudioProducerIds, stageNotice } from "../callState";
 
 /**
  * The two decisions a call screen gets wrong.
@@ -497,3 +497,95 @@ describe("canPublishSource", () => {
     expect(canPublishSource({ ...noPresenting, publishKinds: ["audio", "video"] }, "screen")).toBe(false);
   });
 });
+
+describe("stageNotice: the ONE decision for the centre of the stage", () => {
+  const status = (over: Partial<import("../callState").CallStatus> = {}): import("../callState").CallStatus => ({
+    tone: "live",
+    headlineKey: "forge.call_stage.status_connected",
+    canRetry: false,
+    ...over,
+  });
+
+  it("shows JOINING while connecting, never a not-connected error", () => {
+    // The user-reported bug: the joining state used to read as an error.
+    const notice = stageNotice({
+      status: status({ tone: "connecting", headlineKey: "forge.call_stage.status_connecting" }),
+      remoteCount: 0,
+      everSawPeers: false,
+    });
+    expect(notice?.kind).toBe("joining");
+    expect(notice?.canRetry).toBe(false);
+  });
+
+  it("separates the room that has not started from the one that just emptied", () => {
+    expect(stageNotice({ status: status(), remoteCount: 0, everSawPeers: false })?.kind).toBe("waiting");
+    expect(stageNotice({ status: status(), remoteCount: 0, everSawPeers: true })?.kind).toBe("everyone_left");
+    expect(stageNotice({ status: status(), remoteCount: 2, everSawPeers: true })).toBeNull();
+  });
+
+  it("moves terminal states to the centre, carrying the server's sentence verbatim", () => {
+    const failed = stageNotice({
+      status: status({ tone: "failed", headlineKey: "forge.call_stage.status_refused", detailText: "unauthorized", canRetry: true }),
+      remoteCount: 3,
+      everSawPeers: true,
+    });
+    expect(failed).toMatchObject({ kind: "failed", detailText: "unauthorized", canRetry: true });
+
+    const ended = stageNotice({
+      status: status({ tone: "ended", headlineKey: "forge.call_stage.status_ended", detailText: "the host ended it" }),
+      remoteCount: 3,
+      everSawPeers: true,
+    });
+    expect(ended).toMatchObject({ kind: "ended", detailText: "the host ended it", canRetry: false });
+  });
+
+  it("keeps the stage for a RECONNECT with people on it: the pill handles it", () => {
+    expect(
+      stageNotice({
+        status: status({ tone: "reconnecting", headlineKey: "forge.call_stage.status_reconnecting" }),
+        remoteCount: 2,
+        everSawPeers: true,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("tiles carry their source, and a share never displaces the face", () => {
+  it("gives a screen sharer a camera slot AND a screen slot", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [{ identity: "anna", name: "Anna", kind: "human" }],
+      producers: [
+        { producerId: "v-1", identity: "anna", kind: "video", paused: false, source: "camera" },
+        { producerId: "s-1", identity: "anna", kind: "video", paused: false, source: "screen" },
+        { producerId: "a-1", identity: "anna", kind: "audio", paused: false },
+      ],
+      activeSpeakers: [],
+    });
+    expect(tiles.map((t) => ({ key: t.key, source: t.source }))).toEqual([
+      { key: "anna#camera", source: "camera" },
+      { key: "anna#screen", source: "screen" },
+    ]);
+  });
+
+  it("keeps the camera SLOT when only a share is up, so the person still has a face tile", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [{ identity: "anna", name: "Anna", kind: "human" }],
+      producers: [{ producerId: "s-1", identity: "anna", kind: "video", paused: false, source: "screen" }],
+      activeSpeakers: [],
+    });
+    expect(tiles.map((t) => t.key)).toEqual(["anna#camera", "anna#screen"]);
+    expect(tiles[0]?.videoProducerId).toBeUndefined();
+  });
+
+  it("reports a mute honestly: audio published, every producer paused", () => {
+    const tiles = callTiles({
+      identity: "me",
+      peers: [{ identity: "anna", name: "Anna", kind: "human" }],
+      producers: [{ producerId: "a-1", identity: "anna", kind: "audio", paused: true }],
+      activeSpeakers: [],
+    });
+    expect(tiles[0]).toMatchObject({ hasAudio: true, audioMuted: true });
+  });
+});

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

@@ -83,7 +83,7 @@ export class FakeSocket {
   }
 }
 
-export type FakeProducer = { producerId: string; identity: string; kind: "audio" | "video" };
+export type FakeProducer = { producerId: string; identity: string; kind: "audio" | "video"; source?: string };
 
 export type FakeNodeOptions = {
   identity?: string;
@@ -91,6 +91,8 @@ export type FakeNodeOptions = {
   producers?: FakeProducer[];
   recording?: boolean;
   grants?: Record<string, unknown>;
+  /** Hands already up in the join snapshot: a reconnect or a late join. */
+  raisedHands?: { identity: string; raisedAt: number }[];
   /** Refuse the join with this code instead of accepting it. */
   refuseWith?: string;
 };
@@ -163,6 +165,7 @@ export class FakeNode {
       iceServers: [],
       recording: this.options.recording ?? false,
       grants: this.options.grants ?? { canPublish: true, canSubscribe: true, canPublishData: false },
+      ...(this.options.raisedHands ? { raisedHands: this.options.raisedHands } : {}),
     };
   }
 

package/src/ui/media/callChat.ts

@@ -0,0 +1,33 @@
+/**
+ * The chat adapter the stage renders, injected like `recordingControl`.
+ *
+ * A PROP rather than something the stage fetches, and the seam matters more
+ * here than anywhere: the three surfaces authenticate the platform socket
+ * differently (admin's dashboard token, the portal's public token), and the
+ * admin dashboard mounts no `ForgeProvider` at all, so nothing inside the
+ * stage may touch a socket or an HTTP client. The page composes its lane's
+ * hooks into THIS shape; `useCallChat` (public lane) is the reference
+ * implementation, and admin wires its own against the same shape.
+ */
+export type CallChatMessage = {
+  id: string;
+  content: string | null;
+  senderName: string;
+  /** Compared against `currentSenderKey` to right-align "mine". */
+  senderKey: string;
+  at: string;
+  reactions: readonly { emoji: string; count: number; reactedByMe: boolean }[];
+};
+
+export type CallStageChat = {
+  /** False while the channel is still being resolved; the panel says so. */
+  ready: boolean;
+  /** Oldest first, as a panel renders. */
+  messages: readonly CallChatMessage[];
+  sendMessage: (text: string) => void;
+  /** Toggles. The aggregate comes back over the socket for everyone. */
+  reactToMessage: (messageId: string, emoji: string) => void;
+  typingNames: readonly string[];
+  onTyping?: () => void;
+  currentSenderKey: string | null;
+};

package/src/ui/media/callState.ts

@@ -37,9 +37,10 @@ import {
 /** One rendered tile. A tile with no `videoProducerId` is NORMAL, not broken. */
 export type CallTile = {
   /**
-   * React key. Deliberately the participant plus an ORDINAL rather than the
+   * React key. Deliberately the participant plus a SLOT rather than the
    * producer id: a camera going on and off must change what a tile shows, not
-   * unmount and remount the tile.
+   * unmount and remount the tile. The camera slot exists whether or not a
+   * camera producer does; the screen slot appears with the share.
    */
   key: string;
   identity: string;
@@ -47,6 +48,13 @@ export type CallTile = {
    * at least tells two unnamed participants apart. */
   name: string;
   kind: ParticipantKind;
+  /**
+   * What this tile IS: the person, or what they are presenting. From the
+   * producer's declared `source` label, which the wire now carries; the two
+   * are laid out completely differently (a share takes the stage, a face
+   * takes a grid cell) and nothing else tells them apart.
+   */
+  source: "camera" | "screen";
   /** The node put one of this participant's audio producers in the active set. */
   isSpeaking: boolean;
   /** Attach this with `useRemoteTrack`. Absent means "no camera", not "error". */
@@ -55,6 +63,8 @@ export type CallTile = {
   videoPaused: boolean;
   /** They are publishing audio at all. A room can be joined listen-only. */
   hasAudio: boolean;
+  /** Audio published but paused at source: muted, and shown as such. */
+  audioMuted: boolean;
 };
 
 export type CallTileInput = {
@@ -100,23 +110,60 @@ export function callTiles(input: CallTileInput): readonly CallTile[] {
   const push = (identity: string, name: string, kind: ParticipantKind) => {
     const mine = input.producers.filter((p) => p.identity === identity);
     const videos = mine.filter((p) => p.kind === "video");
-    const hasAudio = mine.some((p) => p.kind === "audio");
-    const isSpeaking = mine.some((p) => p.kind === "audio" && speaking.has(p.producerId));
+    const audios = mine.filter((p) => p.kind === "audio");
+    const hasAudio = audios.length > 0;
+    const audioMuted = hasAudio && audios.every((p) => p.paused);
+    const isSpeaking = audios.some((p) => speaking.has(p.producerId));
+
+    // The label decides the slot. An unlabeled video (an older publisher) is
+    // read as a camera, which is what it almost always is and the harmless
+    // reading when it is not.
+    const cameras = videos.filter((p) => p.source !== "screen");
+    const screens = videos.filter((p) => p.source === "screen");
 
-    if (videos.length === 0) {
-      tiles.push({ key: `${identity}#0`, identity, name, kind, isSpeaking, videoPaused: false, hasAudio });
-      return;
+    // The camera slot ALWAYS exists, video or not, so a share never takes the
+    // place of the face talking over it and a camera toggle never remounts
+    // the tile. Extra cameras (rare, but the wire allows them) get ordinals.
+    cameras.forEach((video, index) => {
+      tiles.push({
+        key: index === 0 ? `${identity}#camera` : `${identity}#camera${index + 1}`,
+        identity,
+        name,
+        kind,
+        source: "camera",
+        isSpeaking,
+        videoProducerId: video.producerId,
+        videoPaused: video.paused,
+        hasAudio,
+        audioMuted,
+      });
+    });
+    if (cameras.length === 0) {
+      tiles.push({
+        key: `${identity}#camera`,
+        identity,
+        name,
+        kind,
+        source: "camera",
+        isSpeaking,
+        videoPaused: false,
+        hasAudio,
+        audioMuted,
+      });
     }
-    videos.forEach((video, index) => {
+
+    screens.forEach((video, index) => {
       tiles.push({
-        key: `${identity}#${index}`,
+        key: index === 0 ? `${identity}#screen` : `${identity}#screen${index + 1}`,
         identity,
         name,
         kind,
+        source: "screen",
         isSpeaking,
         videoProducerId: video.producerId,
         videoPaused: video.paused,
         hasAudio,
+        audioMuted,
       });
     });
   };
@@ -358,3 +405,72 @@ export type { PublishSource };
 export function canPublishSource(grants: MediaGrants | undefined, source: PublishSource): boolean {
   return mayPublish(grants, { source, trackKind: source === "microphone" ? "audio" : "video" });
 }
+
+export type StageNoticeKind = "joining" | "waiting" | "everyone_left" | "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;
+  detailKey?: string;
+  /** The server's own sentence, verbatim, exactly as the status line shows it. */
+  detailText?: string;
+  canRetry: boolean;
+};
+
+/**
+ * The ONE decision for what the centre of the stage says.
+ *
+ * The user-reported bugs this consolidates: the joining state used to show
+ * "not connected" (the local preview's caption leaking into an empty room),
+ * and errors rendered in the top corner where a person staring at a dead
+ * stage never looks. Terminal states (ended, failed) belong in the CENTRE;
+ * 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.
+ */
+export function stageNotice(input: {
+  status: CallStatus;
+  /** Remote PEOPLE on stage (identities, not tiles). */
+  remoteCount: number;
+  /** Has anyone else ever been here this session? Separates the room that has
+   * not started from the room that just emptied. */
+  everSawPeers: 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") {
+    return {
+      kind: "ended",
+      headlineKey: status.headlineKey,
+      ...(status.detailKey ? { detailKey: status.detailKey } : {}),
+      ...(status.detailText ? { detailText: status.detailText } : {}),
+      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,
+    };
+  }
+  // Live or reconnecting: the stage stands. Only an EMPTY one says anything.
+  if (input.remoteCount === 0) {
+    return input.everSawPeers
+      ? { kind: "everyone_left", headlineKey: "forge.call_stage.everyone_left", canRetry: false }
+      : {
+          kind: "waiting",
+          headlineKey: "forge.call_stage.waiting_for_others",
+          detailKey: "forge.call_stage.waiting_for_others_detail",
+          canRetry: false,
+        };
+  }
+  return null;
+}