@tribe-nest/forge 3.42.1 → 3.50.0

package/src/ui/media/stage/VideoTile.tsx

@@ -0,0 +1,232 @@
+import { memo, useMemo, type CSSProperties } from "react";
+import { Hand, MicOff, Pin, PinOff } from "lucide-react";
+import { useRemoteTrack, useSpeakers } from "@tribe-nest/media-client/react";
+
+import type { ForgeT } from "../../../i18n";
+import type { CallTile } from "../callState";
+import type { StageTokens } from "./stageTheme";
+
+/**
+ * One participant on the stage.
+ *
+ * `React.memo`, and that is load-bearing: a gallery re-renders on every room
+ * change, and eight live videos re-mounting is a visible stutter. The tile
+ * object from `callTiles` is reference-stable while nothing about the person
+ * changed, which is what makes the memo hold.
+ *
+ * The MIC METER subscribes to the speaker levels ITSELF (`<MicMeter>`), so
+ * volume ticks re-render a 20px badge and never the tile.
+ */
+
+export type VideoTileProps = {
+  tile: CallTile;
+  tokens: StageTokens;
+  t: ForgeT;
+  /** `useTileViewport().observeTile`: registers this tile's element as
+   * rendering its producer, which is what the room narrows its subscriptions
+   * and picks simulcast layers from. Memoised HERE per producer id, because a
+   * fresh ref callback per render would re-run detach/attach every render. */
+  observeTile?: (producerId: string) => (element: HTMLElement | null) => void;
+  handRaisedAt?: number;
+  pinned?: boolean;
+  onTogglePin?: () => void;
+  /** Fill the parent instead of keeping an aspect ratio (speaker main, rails). */
+  fill?: boolean;
+  aspectRatio?: number;
+  /** Screen shares letterbox (`contain`): cropping a slide loses its content,
+   * where cropping a face only loses background. */
+  contain?: boolean;
+};
+
+function VideoTileInner({
+  tile,
+  tokens,
+  t,
+  observeTile,
+  handRaisedAt,
+  pinned,
+  onTogglePin,
+  fill,
+  aspectRatio,
+  contain,
+}: VideoTileProps) {
+  // Unconditional so the hook order matches between video and no-video tiles.
+  const { track, attach } = useRemoteTrack(tile.videoProducerId ?? "");
+  const showVideo = !!tile.videoProducerId && !!track && !tile.videoPaused;
+  const observe = useMemo(
+    () => (observeTile && tile.videoProducerId ? observeTile(tile.videoProducerId) : undefined),
+    [observeTile, tile.videoProducerId],
+  );
+
+  const frame: CSSProperties = {
+    position: "relative",
+    overflow: "hidden",
+    borderRadius: tokens.cornerRadius,
+    backgroundColor: tokens.stageSurface,
+    // Speaking is the FRAME, never a reshuffle: a grid that reorders itself
+    // every time somebody says "mm" moves the person out from under the eye.
+    border: `2px solid ${tile.isSpeaking ? tokens.accent : tokens.stageBorder}`,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    boxSizing: "border-box",
+    ...(fill
+      ? { width: "100%", height: "100%", minHeight: 0 }
+      : { aspectRatio: String(aspectRatio ?? 16 / 9), maxHeight: "100%", width: "100%" }),
+  };
+
+  return (
+    <div
+      ref={observe ?? null}
+      style={frame}
+      data-testid={`tile-${tile.identity}`}
+      data-speaking={tile.isSpeaking ? "true" : "false"}
+      data-source={tile.source}
+    >
+      {showVideo ? (
+        <video
+          ref={attach}
+          autoPlay
+          playsInline
+          muted
+          style={{ width: "100%", height: "100%", objectFit: contain || tile.source === "screen" ? "contain" : "cover" }}
+        />
+      ) : (
+        <Avatar name={tile.name} tokens={tokens} />
+      )}
+
+      {handRaisedAt !== undefined && (
+        <span
+          data-testid={`hand-${tile.identity}`}
+          aria-label={t("forge.call_stage.hand_raised_by", { name: tile.name })}
+          style={{
+            position: "absolute",
+            top: "0.5rem",
+            left: "0.5rem",
+            display: "inline-flex",
+            alignItems: "center",
+            justifyContent: "center",
+            width: 26,
+            height: 26,
+            borderRadius: 9999,
+            backgroundColor: tokens.accent,
+            color: tokens.accentText,
+          }}
+        >
+          <Hand width={14} height={14} aria-hidden="true" />
+        </span>
+      )}
+
+      {onTogglePin && (
+        <button
+          type="button"
+          onClick={onTogglePin}
+          aria-label={pinned ? t("forge.call_stage.unpin") : t("forge.call_stage.pin")}
+          style={{
+            position: "absolute",
+            top: "0.5rem",
+            right: "0.5rem",
+            display: "inline-flex",
+            alignItems: "center",
+            justifyContent: "center",
+            width: 26,
+            height: 26,
+            borderRadius: 9999,
+            border: "none",
+            cursor: "pointer",
+            backgroundColor: pinned ? tokens.accent : "rgba(0,0,0,0.5)",
+            color: pinned ? tokens.accentText : tokens.stageText,
+          }}
+        >
+          {pinned ? <PinOff width={14} height={14} aria-hidden="true" /> : <Pin width={14} height={14} aria-hidden="true" />}
+        </button>
+      )}
+
+      <span
+        style={{
+          position: "absolute",
+          left: "0.5rem",
+          bottom: "0.5rem",
+          maxWidth: "calc(100% - 1rem)",
+          display: "inline-flex",
+          alignItems: "center",
+          gap: "0.3rem",
+          overflow: "hidden",
+          fontSize: "0.75rem",
+          padding: "0.125rem 0.45rem",
+          borderRadius: tokens.cornerRadius,
+          backgroundColor: "rgba(0,0,0,0.55)",
+          color: tokens.stageText,
+        }}
+      >
+        {tile.audioMuted && <MicOff width={12} height={12} aria-hidden="true" color={tokens.stageMuted} />}
+        <span style={{ overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+          {tile.source === "screen" ? t("forge.call_stage.screen_of", { name: tile.name }) : tile.name}
+          {!tile.hasAudio && <span style={{ color: tokens.stageMuted }}> {t("forge.call_stage.listening")}</span>}
+        </span>
+        {tile.hasAudio && !tile.audioMuted && <MicMeter identity={tile.identity} tokens={tokens} />}
+      </span>
+    </div>
+  );
+}
+
+export const VideoTile = memo(VideoTileInner);
+
+function Avatar({ name, tokens }: { name: string; tokens: StageTokens }) {
+  const initials = useMemo(
+    () =>
+      name
+        .split(/\s+/)
+        .map((part) => part[0] ?? "")
+        .join("")
+        .slice(0, 2)
+        .toUpperCase(),
+    [name],
+  );
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: "clamp(2.5rem, 28%, 5rem)",
+        aspectRatio: "1",
+        borderRadius: 9999,
+        backgroundColor: tokens.stageChrome,
+        color: tokens.stageText,
+        fontWeight: 600,
+        fontSize: "1rem",
+      }}
+    >
+      {initials || "?"}
+    </span>
+  );
+}
+
+/**
+ * The level meter, self-subscribed. This little component reads the speaker
+ * list so the TILE does not: levels tick a few times a second while anyone
+ * talks, and a badge re-rendering is free where a video element is not.
+ */
+export function MicMeter({ identity, tokens }: { identity: string; tokens: StageTokens }) {
+  const speakers = useSpeakers();
+  const level = speakers.find((s) => s.identity === identity)?.volumeDb;
+  // -60 dB (the node's floor) to roughly -20 (loud) mapped onto three bars.
+  const bars = level === undefined ? 0 : level >= -30 ? 3 : level >= -45 ? 2 : 1;
+  return (
+    <span aria-hidden="true" style={{ display: "inline-flex", alignItems: "flex-end", gap: 1, height: 10 }}>
+      {[1, 2, 3].map((bar) => (
+        <span
+          key={bar}
+          style={{
+            width: 3,
+            height: 3 + bar * 2,
+            borderRadius: 1,
+            backgroundColor: bars >= bar ? tokens.accent : "rgba(255,255,255,0.25)",
+          }}
+        />
+      ))}
+    </span>
+  );
+}

package/src/ui/media/stage/callLayout.ts

@@ -0,0 +1,253 @@
+import type { SpeakerInfo } from "@tribe-nest/media-client";
+
+import type { CallTile } from "../callState";
+
+/**
+ * The stage's layout engine, as pure functions.
+ *
+ * Which tiles are on screen, in what arrangement, is the decision that drives
+ * everything else: the viewport report (and with it what the room subscribes
+ * to and which simulcast layer each tile pulls) is derived from what this
+ * says is rendered. So it lives here, exhaustively testable, and the
+ * components only draw its answer.
+ */
+
+/** What the person chose with the view toggle. */
+export type ViewChoice = "gallery" | "speaker";
+
+export type LayoutMode = "duo" | "gallery" | "speaker" | "presenting";
+
+/** Gallery pages at 8: an even grid that fits a laptop screen, and one under
+ * the plane's 9-video active-set cap, so every visible tile can be live. */
+export const GALLERY_PAGE_SIZE = 8;
+
+/** The presenting and speaker rails show 4 tiles, dominant speaker first. */
+export const RAIL_PAGE_SIZE = 4;
+
+export type StageLayout = {
+  mode: LayoutMode;
+  /** The big one: the share in presenting, the speaker in speaker view. */
+  main?: CallTile;
+  /** Who is presenting, when a share is on the stage. */
+  presenter?: { identity: string; name: string };
+  /** The tiles the current page renders (the rail, in speaker/presenting). */
+  pageTiles: readonly CallTile[];
+  page: number;
+  pageCount: number;
+  columns: number;
+  rows: number;
+  /** People currently speaking whose tile is NOT on this page. */
+  offPageSpeakerNames: readonly string[];
+};
+
+/**
+ * Grid shape for N tiles: even rectangles, never a ragged square.
+ *
+ * 1 = full bleed, 2 = side by side (the two-portrait duo the 1:1 case wants),
+ * 3-4 = 2x2, 5-6 = 3x2, 7-8 = 4x2. Columns cap at 4: a 14-inch screen fits
+ * four faces across before they stop being faces.
+ */
+export function gridShape(count: number): { columns: number; rows: number } {
+  if (count <= 1) return { columns: 1, rows: 1 };
+  if (count === 2) return { columns: 2, rows: 1 };
+  if (count <= 4) return { columns: 2, rows: 2 };
+  if (count <= 6) return { columns: 3, rows: 2 };
+  return { columns: 4, rows: 2 };
+}
+
+/**
+ * The same grid on a PHONE, where a face is only recognisable in PORTRAIT.
+ *
+ * A phone is tall and thin, so the desktop's wide rectangles read as a strip
+ * of letterbox slivers. One column below three people (a single stacked
+ * portrait each), two columns above that - the shape a phone actually wants,
+ * and what Zoom's mobile app does. The count still decides the shape; the
+ * device decides which shape function answers.
+ */
+export function gridShapeNarrow(count: number): { columns: number; rows: number } {
+  if (count <= 1) return { columns: 1, rows: 1 };
+  if (count === 2) return { columns: 1, rows: 2 };
+  const columns = 2;
+  return { columns, rows: Math.ceil(count / columns) };
+}
+
+/** Clamps the page so people leaving mid-call cannot strand you on an empty one. */
+export function paginate<T>(items: readonly T[], page: number, size: number): { items: readonly T[]; page: number; pageCount: number } {
+  const pageCount = Math.max(1, Math.ceil(items.length / size));
+  const clamped = Math.min(Math.max(0, page), pageCount - 1);
+  return { items: items.slice(clamped * size, clamped * size + size), page: clamped, pageCount };
+}
+
+/**
+ * The dominant speaker, held for `holdMs` so a grid does not flap on "mm".
+ *
+ * The node's ranking moves a few times a second; a layout that follows it
+ * verbatim moves the person you are looking at out from under your eye. A
+ * new leader takes over only once the incumbent's hold has run out.
+ */
+export function pickDominant(input: {
+  speakers: readonly SpeakerInfo[];
+  previous: string | null;
+  previousSince: number;
+  now: number;
+  holdMs?: number;
+}): { identity: string | null; since: number } {
+  const holdMs = input.holdMs ?? 1500;
+  const leader = input.speakers[0]?.identity ?? null;
+  if (leader === null) return { identity: input.previous, since: input.previousSince };
+  if (leader === input.previous) return { identity: input.previous, since: input.previousSince };
+  if (input.previous !== null && input.now - input.previousSince < holdMs) {
+    return { identity: input.previous, since: input.previousSince };
+  }
+  return { identity: leader, since: input.now };
+}
+
+/** The share on stage, when there is one. First by key for determinism. */
+export function presentingTile(tiles: readonly CallTile[]): CallTile | undefined {
+  return [...tiles].sort((a, b) => a.key.localeCompare(b.key)).find((t) => t.source === "screen" && !!t.videoProducerId);
+}
+
+export type ResolveLayoutInput = {
+  /** Remote tiles from `callTiles`, camera and screen slots alike. */
+  tiles: readonly CallTile[];
+  view: ViewChoice;
+  page: number;
+  /** A tile key the viewer pinned; forces speaker view on that tile. */
+  pinnedKey: string | null;
+  /** From `pickDominant`. Orders the rail and picks the speaker-view main. */
+  dominantIdentity: string | null;
+  /** THIS viewer is sharing: their own share takes the stage too. */
+  localPresenting: boolean;
+  /** The stage is phone-narrow, so tiles stack as portraits rather than
+   * sitting side by side. Defaults to false: desktop behaviour is unchanged
+   * and every existing caller that omits it gets exactly today's layout. */
+  narrow?: boolean;
+  pageSize?: number;
+  railSize?: number;
+};
+
+/**
+ * Precedence, highest first: a screen share on the stage (anyone's, including
+ * the viewer's own), then a pinned tile, then the chosen view. A duo (exactly
+ * one remote person) renders as two large portraits whatever the toggle says,
+ * because a gallery of two with a pager is a joke and Speaker view of one
+ * person is the same picture with more chrome.
+ */
+export function resolveLayout(input: ResolveLayoutInput): StageLayout {
+  const pageSize = input.pageSize ?? GALLERY_PAGE_SIZE;
+  const railSize = input.railSize ?? RAIL_PAGE_SIZE;
+  const cameraTiles = input.tiles.filter((t) => t.source === "camera");
+  const remoteIdentities = new Set(cameraTiles.map((t) => t.identity));
+
+  /** Dominant speaker first, then the existing (stable) order. Membership
+   * changes page composition; order within a page costs nothing. */
+  const byDominance = (tiles: readonly CallTile[]): CallTile[] =>
+    [...tiles].sort((a, b) => {
+      const aDominant = a.identity === input.dominantIdentity ? 0 : 1;
+      const bDominant = b.identity === input.dominantIdentity ? 0 : 1;
+      return aDominant - bDominant;
+    });
+
+  const share = presentingTile(input.tiles);
+  if (share || input.localPresenting) {
+    const rail = paginate(byDominance(cameraTiles), input.page, railSize);
+    return {
+      mode: "presenting",
+      ...(share ? { main: share, presenter: { identity: share.identity, name: share.name } } : {}),
+      pageTiles: rail.items,
+      page: rail.page,
+      pageCount: rail.pageCount,
+      columns: 1,
+      rows: rail.items.length,
+      offPageSpeakerNames: offPage(cameraTiles, rail.items, input.dominantIdentity),
+    };
+  }
+
+  const pinned = input.pinnedKey ? cameraTiles.find((t) => t.key === input.pinnedKey) : undefined;
+  if (pinned) {
+    const rest = cameraTiles.filter((t) => t.key !== pinned.key);
+    const rail = paginate(byDominance(rest), input.page, railSize);
+    return {
+      mode: "speaker",
+      main: pinned,
+      pageTiles: rail.items,
+      page: rail.page,
+      pageCount: rail.pageCount,
+      columns: rail.items.length,
+      rows: 1,
+      offPageSpeakerNames: offPage(cameraTiles, [pinned, ...rail.items], input.dominantIdentity),
+    };
+  }
+
+  if (remoteIdentities.size === 1) {
+    // ALL of their camera tiles, not the first: an older publisher can carry
+    // two unlabeled videos, and hiding one in the very layout built for
+    // looking at one person would be the wrong place to lose it.
+    //
+    // The `+1` is the local self-view's cell. On a phone the two stack as
+    // portraits (one column, a row each); on a desktop they sit side by side.
+    // Two faces side by side on a phone is the exact "looks way off" this
+    // fixes: each becomes a thin letterbox of the middle of a face.
+    const cells = cameraTiles.length + 1;
+    return {
+      mode: "duo",
+      pageTiles: cameraTiles,
+      page: 0,
+      pageCount: 1,
+      columns: input.narrow ? 1 : cells,
+      rows: input.narrow ? cells : 1,
+      offPageSpeakerNames: [],
+    };
+  }
+
+  if (input.view === "speaker" && cameraTiles.length > 0) {
+    const ordered = byDominance(cameraTiles);
+    const main = ordered[0]!;
+    const rail = paginate(
+      ordered.filter((t) => t.key !== main.key),
+      input.page,
+      railSize,
+    );
+    return {
+      mode: "speaker",
+      main,
+      pageTiles: rail.items,
+      page: rail.page,
+      pageCount: rail.pageCount,
+      columns: rail.items.length,
+      rows: 1,
+      offPageSpeakerNames: offPage(cameraTiles, [main, ...rail.items], input.dominantIdentity),
+    };
+  }
+
+  const pageResult = paginate(cameraTiles, input.page, pageSize);
+  // +1 cell for the local self-view on the first page of a small call is the
+  // component's business; the shape is for the REMOTE tiles it was given.
+  const count = Math.max(1, pageResult.items.length);
+  const shape = input.narrow ? gridShapeNarrow(count) : gridShape(count);
+  return {
+    mode: "gallery",
+    pageTiles: pageResult.items,
+    page: pageResult.page,
+    pageCount: pageResult.pageCount,
+    columns: shape.columns,
+    rows: shape.rows,
+    offPageSpeakerNames: offPage(cameraTiles, pageResult.items, input.dominantIdentity),
+  };
+}
+
+/** Names of people SPEAKING whose tile the current page does not render. */
+function offPage(
+  all: readonly CallTile[],
+  visible: readonly CallTile[],
+  dominantIdentity: string | null,
+): readonly string[] {
+  const shown = new Set(visible.map((t) => t.identity));
+  const names: string[] = [];
+  for (const tile of all) {
+    if (shown.has(tile.identity)) continue;
+    if (!tile.isSpeaking && tile.identity !== dominantIdentity) continue;
+    if (!names.includes(tile.name)) names.push(tile.name);
+  }
+  return names;
+}

package/src/ui/media/stage/callSignals.ts

@@ -0,0 +1,91 @@
+import type { RaisedHand } from "@tribe-nest/media-client";
+import type { Peer } from "@tribe-nest/media-protocol";
+
+/**
+ * The stage's ephemeral-signal arithmetic: hands, flying reactions, toasts
+ * and the unread badge. Pure, because every one of these has an edge (a
+ * burst of joins, a reaction flood, a hand queue that must not reshuffle)
+ * that is a two-line test here and a flaky screen anywhere else.
+ */
+
+/** The reactions a participant may send. A closed list on BOTH ends: the
+ * picker offers these, and incoming broadcasts outside it are dropped, so a
+ * hostile peer cannot fly arbitrary text across everyone's screen. */
+export const REACTION_EMOJI = ["👍", "👏", "❤️", "😂", "😮", "🎉"] as const;
+export type ReactionEmoji = (typeof REACTION_EMOJI)[number];
+
+export function isKnownReaction(emoji: unknown): emoji is ReactionEmoji {
+  return typeof emoji === "string" && (REACTION_EMOJI as readonly string[]).includes(emoji);
+}
+
+export type FlyingReaction = {
+  /** Unique per animation instance. */
+  id: string;
+  emoji: ReactionEmoji;
+  identity: string;
+  /** 0..1, where across the stage it rises. Derived from the id so it is
+   * stable per instance without a random source in a pure module. */
+  lane: number;
+  at: number;
+};
+
+/** Minimum ms between OUR sends. The node rate-limits too; this keeps an
+ * enthusiastic key-holder from ever meeting that refusal. */
+export const REACTION_SEND_GATE_MS = 500;
+
+export function reactionGate(lastSentAt: number | null, now: number, gateMs = REACTION_SEND_GATE_MS): boolean {
+  return lastSentAt === null || now - lastSentAt >= gateMs;
+}
+
+/** Drop reactions past their animation, and cap how many fly at once: a
+ * hundred simultaneous emoji is a denial of the actual call. Newest win. */
+export function cullReactions(list: readonly FlyingReaction[], now: number, ttlMs = 4000, max = 30): readonly FlyingReaction[] {
+  const alive = list.filter((r) => now - r.at < ttlMs);
+  return alive.length <= max ? alive : alive.slice(alive.length - max);
+}
+
+/** A stable 0..1 lane from an id, so the module needs no random source. */
+export function laneFor(id: string): number {
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) hash = (hash * 31 + id.charCodeAt(i)) >>> 0;
+  return (hash % 997) / 997;
+}
+
+/** Oldest first: the hand queue's order IS its meaning. The client re-sorts
+ * even though the wire is sorted, so a merge bug upstream cannot reorder a
+ * queue a host is calling on. */
+export function orderHands(hands: readonly RaisedHand[]): readonly RaisedHand[] {
+  return [...hands].sort((a, b) => a.raisedAt - b.raisedAt || a.identity.localeCompare(b.identity));
+}
+
+export type PeerChange = { identity: string; name: string; kind: "joined" | "left" };
+
+/**
+ * Who joined and who left between two peer snapshots, for the toasts. The
+ * caller collapses a burst; this only reports the truth of one transition.
+ */
+export function diffPeers(previous: readonly Peer[], next: readonly Peer[]): readonly PeerChange[] {
+  const before = new Map(previous.map((p) => [p.identity, p]));
+  const after = new Map(next.map((p) => [p.identity, p]));
+  const changes: PeerChange[] = [];
+  for (const peer of next) {
+    if (peer.kind === "egress") continue;
+    if (!before.has(peer.identity)) changes.push({ identity: peer.identity, name: peer.name ?? peer.identity, kind: "joined" });
+  }
+  for (const peer of previous) {
+    if (peer.kind === "egress") continue;
+    if (!after.has(peer.identity)) changes.push({ identity: peer.identity, name: peer.name ?? peer.identity, kind: "left" });
+  }
+  return changes;
+}
+
+/**
+ * Messages newer than the last one seen. Counted by position, not timestamp:
+ * ids are opaque and clocks are nobody's friend, but the list arrives in
+ * order and "seen" is a position in it.
+ */
+export function unreadCount(messageIds: readonly string[], lastSeenId: string | null): number {
+  if (lastSeenId === null) return messageIds.length;
+  const index = messageIds.lastIndexOf(lastSeenId);
+  return index === -1 ? messageIds.length : messageIds.length - index - 1;
+}

package/src/ui/media/stage/callSounds.ts

@@ -0,0 +1,78 @@
+/**
+ * Join and leave chimes, synthesized. No asset, no network: two short sine
+ * envelopes from WebAudio, quiet on purpose.
+ *
+ * The AudioContext is created on first USE from a user gesture (the Join
+ * click via PreJoin, or any control press): a context created outside one is
+ * suspended by autoplay policy and every chime is silent with nothing in the
+ * console. Where the context cannot run (jsdom, an embedded surface with no
+ * gesture) every call is a no-op.
+ */
+export type CallSounds = {
+  /** Call from a user gesture, once. Safe to call repeatedly. */
+  unlock(): void;
+  join(): void;
+  leave(): void;
+  /** A hand went up somewhere in the room. Everyone's client rings it. */
+  raiseHand(): void;
+  setMuted(muted: boolean): void;
+  readonly muted: boolean;
+};
+
+export function createCallSounds(): CallSounds {
+  let context: AudioContext | null = null;
+  let muted = false;
+
+  const ensure = (): AudioContext | null => {
+    if (context) return context;
+    const Ctor =
+      typeof AudioContext !== "undefined"
+        ? AudioContext
+        : (globalThis as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+    if (!Ctor) return null;
+    try {
+      context = new Ctor();
+    } catch {
+      return null;
+    }
+    return context;
+  };
+
+  const chime = (frequencies: number[]) => {
+    if (muted) return;
+    const ctx = context;
+    if (!ctx || ctx.state !== "running") return;
+    const now = ctx.currentTime;
+    frequencies.forEach((frequency, index) => {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+      osc.type = "sine";
+      osc.frequency.value = frequency;
+      // Quiet, and enveloped: a click-free 180ms ping.
+      gain.gain.setValueAtTime(0, now + index * 0.12);
+      gain.gain.linearRampToValueAtTime(0.06, now + index * 0.12 + 0.02);
+      gain.gain.exponentialRampToValueAtTime(0.0001, now + index * 0.12 + 0.18);
+      osc.connect(gain).connect(ctx.destination);
+      osc.start(now + index * 0.12);
+      osc.stop(now + index * 0.12 + 0.2);
+    });
+  };
+
+  return {
+    unlock() {
+      const ctx = ensure();
+      if (ctx?.state === "suspended") void ctx.resume().catch(() => undefined);
+    },
+    join: () => chime([660, 880]),
+    leave: () => chime([660, 440]),
+    // A brighter, rising three-step so a raised hand is not mistaken for a
+    // join: attention, not arrival.
+    raiseHand: () => chime([784, 988, 1319]),
+    setMuted(value: boolean) {
+      muted = value;
+    },
+    get muted() {
+      return muted;
+    },
+  };
+}