@tribe-nest/forge 3.42.1 → 3.48.0

package/src/ui/media/hooks/useCallSignals.ts

@@ -0,0 +1,135 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useBroadcast, useMediaRoom, useRaisedHands as useRaisedHandsState, useRoomState } from "@tribe-nest/media-client/react";
+import type { RaisedHand } from "@tribe-nest/media-client";
+
+import {
+  cullReactions,
+  isKnownReaction,
+  laneFor,
+  orderHands,
+  reactionGate,
+  type FlyingReaction,
+  type ReactionEmoji,
+} from "../stage/callSignals";
+
+/**
+ * Hands and flying reactions, as the stage consumes them.
+ *
+ * The SEMANTICS live here in Forge; the transport lives in media-client.
+ * Hands are server-materialized room state (`setHand` on the wire), so this
+ * hook renders `state.raisedHands` and never keeps its own ledger: a
+ * reconnect's snapshot is the truth and there is nothing local to drift.
+ */
+
+export type RaisedHandsControls = {
+  /** Oldest first: the queue a host calls on. */
+  hands: readonly RaisedHand[];
+  myHandRaised: boolean;
+  raiseHand: () => void;
+  lowerHand: () => void;
+  /**
+   * Host courtesy controls. HONORIFIC by design: they broadcast a request
+   * and the TARGET's own client lowers its hand, because the server-held
+   * state only ever moves on its owner's verb. Any participant could send
+   * the same broadcast; the harm is a lowered hand, which is why this is
+   * acceptable, and why nothing stronger may ever be built on it.
+   */
+  lowerHandOf: (identity: string) => void;
+  lowerAll: () => void;
+};
+
+export function useRaisedHands(): RaisedHandsControls {
+  const { room } = useMediaRoom();
+  const state = useRoomState();
+  const raw = useRaisedHandsState();
+  const hands = useMemo(() => orderHands(raw), [raw]);
+  const myHandRaised = useMemo(
+    () => !!state.identity && raw.some((h) => h.identity === state.identity),
+    [raw, state.identity],
+  );
+
+  // Obey a courtesy lower-hand addressed to US (or to everyone).
+  const identityRef = useRef(state.identity);
+  identityRef.current = state.identity;
+  useBroadcast(
+    useCallback(
+      (event) => {
+        if (event.type !== "lowerHand") return;
+        const target = (event.data as { target?: unknown }).target;
+        if (target === identityRef.current || target === "all") {
+          void room?.setHandRaised(false);
+        }
+      },
+      [room],
+    ),
+  );
+
+  return {
+    hands,
+    myHandRaised,
+    raiseHand: useCallback(() => void room?.setHandRaised(true), [room]),
+    lowerHand: useCallback(() => void room?.setHandRaised(false), [room]),
+    lowerHandOf: useCallback((identity: string) => void room?.sendLowerHand(identity), [room]),
+    lowerAll: useCallback(() => void room?.sendLowerHand("all"), [room]),
+  };
+}
+
+export type FlyingReactionsControls = {
+  reactions: readonly FlyingReaction[];
+  /** Gated to one per half second; the node's rate limit is never met. */
+  sendReaction: (emoji: ReactionEmoji) => void;
+};
+
+export function useFlyingReactions(): FlyingReactionsControls {
+  const { room } = useMediaRoom();
+  const state = useRoomState();
+  const [reactions, setReactions] = useState<readonly FlyingReaction[]>([]);
+  const lastSentAt = useRef<number | null>(null);
+  const counter = useRef(0);
+  const identityRef = useRef(state.identity);
+  identityRef.current = state.identity;
+
+  const add = useCallback((emoji: ReactionEmoji, identity: string) => {
+    const id = `${identity}-${counter.current++}-${Date.now()}`;
+    setReactions((current) =>
+      cullReactions([...current, { id, emoji, identity, lane: laneFor(id), at: Date.now() }], Date.now()),
+    );
+  }, []);
+
+  useBroadcast(
+    useCallback(
+      (event) => {
+        if (event.type !== "reaction") return;
+        // Our own send already flew locally; the node echoes it back to us
+        // as the delivery mechanism, and rendering the echo doubles it.
+        if (event.identity === identityRef.current) return;
+        const emoji = (event.data as { emoji?: unknown }).emoji;
+        // The whitelist applies on RECEIPT too: a hostile peer must not fly
+        // arbitrary strings across everyone's screen.
+        if (isKnownReaction(emoji)) add(emoji, event.identity);
+      },
+      [add],
+    ),
+  );
+
+  // Cull on a slow tick only while anything is flying.
+  useEffect(() => {
+    if (reactions.length === 0) return undefined;
+    const timer = setInterval(() => setReactions((current) => cullReactions(current, Date.now())), 1000);
+    return () => clearInterval(timer);
+  }, [reactions.length > 0]);
+
+  const sendReaction = useCallback(
+    (emoji: ReactionEmoji) => {
+      const now = Date.now();
+      if (!reactionGate(lastSentAt.current, now)) return;
+      lastSentAt.current = now;
+      void room?.sendReaction({ emoji });
+      // Our own copy flies immediately; the node's echo is not waited for.
+      add(emoji, "me");
+    },
+    [room, add],
+  );
+
+  return { reactions, sendReaction };
+}

package/src/ui/media/hooks/useMeasuredWidth.ts

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * The rendered width of an element, tracked live.
+ *
+ * The call stage is a portable SDK component styled with INLINE styles, so it
+ * cannot lean on CSS media queries or a Tailwind breakpoint to go responsive.
+ * It also may not be the full window: it embeds inside a booking page, a modal,
+ * a split view. So the breakpoint that matters is the element's OWN width, read
+ * with a ResizeObserver, not `window.innerWidth`.
+ *
+ * Returns 0 until the first measurement (and where ResizeObserver does not
+ * exist, jsdom included), which every caller reads as "not narrow yet" so the
+ * default is the roomy desktop layout rather than a flash of the mobile one.
+ */
+export function useMeasuredWidth<T extends HTMLElement>(): [React.RefObject<T | null>, number] {
+  const ref = useRef<T | null>(null);
+  const [width, setWidth] = useState(0);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element || typeof ResizeObserver === "undefined") return undefined;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) setWidth(Math.round(entry.contentRect.width));
+    });
+    observer.observe(element);
+    // Seed synchronously so the first paint is not a frame of width 0.
+    setWidth(Math.round(element.getBoundingClientRect().width));
+    return () => observer.disconnect();
+  }, []);
+
+  return [ref, width];
+}
+
+/** Below this the stage folds the side panel into a full-screen overlay and
+ * tightens the chrome. A phone in portrait is ~360-430 CSS px; a tablet and up
+ * keeps the panel docked beside the stage. */
+export const STAGE_NARROW_MAX_PX = 600;

package/src/ui/media/index.ts

@@ -57,11 +57,29 @@ export {
   // full announcement history and deliberately keeps producers the current
   // subscribe rule bars, so that a barrier which narrows can later widen.
   useVisibleProducers,
+  // Layer-2 capacity: a custom layout that renders its own tiles must report
+  // them, or the room subscribes to the whole active set on its behalf.
+  useTileViewport,
+  useSpeakers,
   type LocalMediaControls,
   type LocalSource,
   type MediaRoomProviderProps,
+  type PublishDeviceOptions,
+  type TileViewportControls,
 } from "@tribe-nest/media-client/react";
 
+/**
+ * Hands and flying reactions, with the stage's semantics (queue order, the
+ * courtesy lower-hand, the whitelist and the send gate). The raw wire hook
+ * is `useBroadcast` in the SDK; a site should not need it.
+ */
+export {
+  useFlyingReactions,
+  useRaisedHands,
+  type FlyingReactionsControls,
+  type RaisedHandsControls,
+} from "./hooks/useCallSignals";
+
 export type {
   ConnectionState,
   DisconnectCause,
@@ -92,7 +110,29 @@ export type { MediaGrants, Peer, SubscribeRule } from "@tribe-nest/media-protoco
  * that separates "reconnecting" from "refused" rather than showing one spinner
  * for both.
  */
-export { CallStage, type CallStageProps } from "./CallStage";
+export {
+  CallStage,
+  type CallStageMediaDefaults,
+  type CallStageProps,
+  type CallStageRecording,
+} from "./CallStage";
+
+/**
+ * The green room: device check and join-muted toggles BEFORE anything
+ * connects. Pages mount this in place of `MediaRoomProvider` and mount the
+ * provider (with `mediaDefaults` on the stage) only on its `onJoin`.
+ */
+export { PreJoin, type PreJoinProps, type PreJoinSettings } from "./PreJoin";
+
+/**
+ * The chat adapter's shape, injected per surface. The stage never touches a
+ * socket or an HTTP client; each surface composes its own lane's hooks into
+ * this and hands it over as the `chat` prop.
+ */
+export type { CallChatMessage, CallStageChat } from "./callChat";
+
+/** The reaction vocabulary, shared by the picker and the receive whitelist. */
+export { REACTION_EMOJI, type ReactionEmoji } from "./stage/callSignals";
 
 /**
  * What a call page shows OUTSIDE the window, when there is nothing to connect

package/src/ui/media/panels/CallChatPanel.tsx

@@ -0,0 +1,200 @@
+import { useEffect, useRef, useState } from "react";
+import { SendHorizontal, SmilePlus } from "lucide-react";
+
+import type { ForgeT } from "../../../i18n";
+import type { CallStageChat } from "../callChat";
+import { REACTION_EMOJI } from "../stage/callSignals";
+import type { StageTokens } from "../stage/stageTheme";
+
+/**
+ * The in-call chat rail.
+ *
+ * Deliberately its OWN bubbles and composer rather than the shared
+ * `MessageBubble`/`ChatComposer`: those read Forge's theme and data contexts
+ * (attachment uploads run through `useForge()`), and the admin dashboard
+ * mounts neither. Everything this panel touches arrives through the
+ * `CallStageChat` adapter, which is what lets one stage serve three
+ * differently-authenticated surfaces. Text only, on purpose: an attachment
+ * picker is a lane-specific feature the adapter can grow later.
+ */
+export function CallChatPanel({ chat, tokens, t }: { chat: CallStageChat; tokens: StageTokens; t: ForgeT }) {
+  const [draft, setDraft] = useState("");
+  const [pickerFor, setPickerFor] = useState<string | null>(null);
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const stickToBottom = useRef(true);
+
+  // Follow new messages only while the person is AT the bottom; scrolling up
+  // to read history must not be yanked back down by every arrival.
+  useEffect(() => {
+    const element = scrollRef.current;
+    if (element && stickToBottom.current) element.scrollTop = element.scrollHeight;
+  }, [chat.messages.length]);
+
+  const send = () => {
+    const text = draft.trim();
+    if (!text) return;
+    chat.sendMessage(text);
+    setDraft("");
+    stickToBottom.current = true;
+  };
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", flex: 1, minHeight: 0 }}>
+      <div
+        ref={scrollRef}
+        data-testid="call-chat-messages"
+        onScroll={(event) => {
+          const element = event.currentTarget;
+          stickToBottom.current = element.scrollHeight - element.scrollTop - element.clientHeight < 40;
+        }}
+        style={{ flex: 1, minHeight: 0, overflowY: "auto", padding: "0.75rem", display: "flex", flexDirection: "column", gap: "0.625rem" }}
+      >
+        {!chat.ready && <span style={{ fontSize: "0.8125rem", color: tokens.stageMuted }}>{t("forge.call_stage.chat_loading")}</span>}
+        {chat.ready && chat.messages.length === 0 && (
+          <span style={{ fontSize: "0.8125rem", color: tokens.stageMuted }}>{t("forge.call_stage.chat_empty")}</span>
+        )}
+        {chat.messages.map((message) => {
+          const mine = !!chat.currentSenderKey && message.senderKey === chat.currentSenderKey;
+          return (
+            <div key={message.id} style={{ alignSelf: mine ? "flex-end" : "flex-start", maxWidth: "85%" }}>
+              {!mine && <div style={{ fontSize: "0.6875rem", color: tokens.stageMuted, marginBottom: 2 }}>{message.senderName}</div>}
+              <div
+                style={{
+                  position: "relative",
+                  padding: "0.4rem 0.65rem",
+                  borderRadius: tokens.cornerRadius,
+                  backgroundColor: mine ? tokens.accent : tokens.stageChrome,
+                  color: mine ? tokens.accentText : tokens.stageText,
+                  fontSize: "0.8125rem",
+                  whiteSpace: "pre-wrap",
+                  wordBreak: "break-word",
+                }}
+              >
+                {message.content}
+                <button
+                  type="button"
+                  onClick={() => setPickerFor((current) => (current === message.id ? null : message.id))}
+                  aria-label={t("forge.call_stage.react_to_message")}
+                  style={{
+                    position: "absolute",
+                    top: -8,
+                    ...(mine ? { left: -8 } : { right: -8 }),
+                    width: 20,
+                    height: 20,
+                    display: "inline-flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    borderRadius: 9999,
+                    border: `1px solid ${tokens.stageBorder}`,
+                    backgroundColor: tokens.stageSurface,
+                    color: tokens.stageMuted,
+                    cursor: "pointer",
+                  }}
+                >
+                  <SmilePlus width={11} height={11} aria-hidden="true" />
+                </button>
+              </div>
+              {pickerFor === message.id && (
+                <div style={{ display: "flex", gap: "0.25rem", marginTop: 3 }}>
+                  {REACTION_EMOJI.map((emoji) => (
+                    <button
+                      key={emoji}
+                      type="button"
+                      onClick={() => {
+                        chat.reactToMessage(message.id, emoji);
+                        setPickerFor(null);
+                      }}
+                      style={{ border: "none", background: "transparent", cursor: "pointer", fontSize: "1rem", padding: 0 }}
+                    >
+                      {emoji}
+                    </button>
+                  ))}
+                </div>
+              )}
+              {message.reactions.length > 0 && (
+                <div style={{ display: "flex", gap: "0.25rem", marginTop: 3, flexWrap: "wrap" }}>
+                  {message.reactions.map((reaction) => (
+                    <button
+                      key={reaction.emoji}
+                      type="button"
+                      onClick={() => chat.reactToMessage(message.id, reaction.emoji)}
+                      aria-pressed={reaction.reactedByMe}
+                      style={{
+                        display: "inline-flex",
+                        alignItems: "center",
+                        gap: "0.2rem",
+                        fontSize: "0.6875rem",
+                        padding: "0.05rem 0.375rem",
+                        borderRadius: 9999,
+                        border: `1px solid ${reaction.reactedByMe ? tokens.accent : tokens.stageBorder}`,
+                        backgroundColor: reaction.reactedByMe ? tokens.accent : "transparent",
+                        color: reaction.reactedByMe ? tokens.accentText : tokens.stageText,
+                        cursor: "pointer",
+                      }}
+                    >
+                      {reaction.emoji} {reaction.count}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+          );
+        })}
+        {chat.typingNames.length > 0 && (
+          <span style={{ fontSize: "0.6875rem", color: tokens.stageMuted }}>
+            {t("forge.call_stage.chat_typing", { name: chat.typingNames[0] ?? "" })}
+          </span>
+        )}
+      </div>
+
+      <div style={{ display: "flex", gap: "0.375rem", padding: "0.5rem", borderTop: `1px solid ${tokens.stageBorder}` }}>
+        <input
+          value={draft}
+          onChange={(event) => {
+            setDraft(event.target.value);
+            chat.onTyping?.();
+          }}
+          onKeyDown={(event) => {
+            if (event.key === "Enter" && !event.shiftKey) {
+              event.preventDefault();
+              send();
+            }
+          }}
+          placeholder={t("forge.call_stage.chat_placeholder")}
+          disabled={!chat.ready}
+          style={{
+            flex: 1,
+            minWidth: 0,
+            padding: "0.45rem 0.6rem",
+            borderRadius: tokens.cornerRadius,
+            border: `1px solid ${tokens.stageBorder}`,
+            backgroundColor: tokens.stageBg,
+            color: tokens.stageText,
+            font: "inherit",
+            fontSize: "0.8125rem",
+            outline: "none",
+          }}
+        />
+        <button
+          type="button"
+          onClick={send}
+          disabled={!chat.ready || !draft.trim()}
+          aria-label={t("forge.call_stage.chat_send")}
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            justifyContent: "center",
+            width: 34,
+            borderRadius: tokens.cornerRadius,
+            border: "none",
+            backgroundColor: draft.trim() ? tokens.accent : tokens.stageChrome,
+            color: draft.trim() ? tokens.accentText : tokens.stageMuted,
+            cursor: draft.trim() ? "pointer" : "default",
+          }}
+        >
+          <SendHorizontal width={15} height={15} aria-hidden="true" />
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/ui/media/panels/CallParticipantsPanel.tsx

@@ -0,0 +1,125 @@
+import { Hand, MicOff, Video, VideoOff } from "lucide-react";
+import type { RaisedHand } from "@tribe-nest/media-client";
+
+import type { ForgeT } from "../../../i18n";
+import type { CallTile } from "../callState";
+import type { StageTokens } from "../stage/stageTheme";
+
+/**
+ * The roster: everyone in the call with their mic and camera state, hands
+ * FIRST and in queue order, because a host reads this list to call on the
+ * next question. The lower-hand controls are host courtesies (the target's
+ * client obeys); they render only for the host so nobody else is offered a
+ * button whose whole meaning is "I am running this call".
+ */
+export function CallParticipantsPanel({
+  tiles,
+  hands,
+  isHost,
+  myIdentity,
+  onLowerHand,
+  onLowerAll,
+  tokens,
+  t,
+}: {
+  tiles: readonly CallTile[];
+  hands: readonly RaisedHand[];
+  isHost: boolean;
+  myIdentity: string | null;
+  onLowerHand: (identity: string) => void;
+  onLowerAll: () => void;
+  tokens: StageTokens;
+  t: ForgeT;
+}) {
+  const byIdentity = new Map<string, CallTile>();
+  for (const tile of tiles) {
+    if (tile.source === "camera" && !byIdentity.has(tile.identity)) byIdentity.set(tile.identity, tile);
+  }
+  const handOrder = new Map(hands.map((hand, index) => [hand.identity, index]));
+  const people = [...byIdentity.values()].sort((a, b) => {
+    const aHand = handOrder.get(a.identity) ?? Number.MAX_SAFE_INTEGER;
+    const bHand = handOrder.get(b.identity) ?? Number.MAX_SAFE_INTEGER;
+    return aHand - bHand || a.name.localeCompare(b.name);
+  });
+
+  return (
+    <div
+      data-testid="call-participants-panel"
+      style={{ flex: 1, minHeight: 0, overflowY: "auto", display: "flex", flexDirection: "column", padding: "0.5rem" }}
+    >
+      {isHost && hands.length > 0 && (
+        <button
+          type="button"
+          onClick={onLowerAll}
+          style={{
+            alignSelf: "flex-end",
+            margin: "0.25rem",
+            padding: "0.25rem 0.6rem",
+            fontSize: "0.75rem",
+            borderRadius: tokens.cornerRadius,
+            border: `1px solid ${tokens.stageBorder}`,
+            backgroundColor: "transparent",
+            color: tokens.stageText,
+            cursor: "pointer",
+          }}
+        >
+          {t("forge.call_stage.lower_all_hands")}
+        </button>
+      )}
+      {people.map((person) => {
+        const raisedAt = hands.find((h) => h.identity === person.identity)?.raisedAt;
+        const queuePosition = handOrder.get(person.identity);
+        return (
+          <div
+            key={person.identity}
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "0.5rem",
+              padding: "0.45rem 0.5rem",
+              borderRadius: tokens.cornerRadius,
+              fontSize: "0.8125rem",
+            }}
+          >
+            {raisedAt !== undefined && (
+              <span
+                aria-label={t("forge.call_stage.hand_raised_by", { name: person.name })}
+                style={{ display: "inline-flex", alignItems: "center", gap: "0.2rem", color: tokens.accent, fontWeight: 600 }}
+              >
+                <Hand width={14} height={14} aria-hidden="true" />
+                {queuePosition !== undefined ? queuePosition + 1 : ""}
+              </span>
+            )}
+            <span style={{ flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+              {person.name}
+              {person.identity === myIdentity && <span style={{ color: tokens.stageMuted }}> {t("forge.call_stage.you_suffix")}</span>}
+            </span>
+            {(person.audioMuted || !person.hasAudio) && <MicOff width={14} height={14} aria-hidden="true" color={tokens.stageMuted} />}
+            {person.videoProducerId && !person.videoPaused ? (
+              <Video width={14} height={14} aria-hidden="true" color={tokens.stageMuted} />
+            ) : (
+              <VideoOff width={14} height={14} aria-hidden="true" color={tokens.stageMuted} />
+            )}
+            {isHost && raisedAt !== undefined && person.identity !== myIdentity && (
+              <button
+                type="button"
+                onClick={() => onLowerHand(person.identity)}
+                style={{
+                  padding: "0.15rem 0.45rem",
+                  fontSize: "0.6875rem",
+                  borderRadius: tokens.cornerRadius,
+                  border: `1px solid ${tokens.stageBorder}`,
+                  backgroundColor: "transparent",
+                  color: tokens.stageText,
+                  cursor: "pointer",
+                }}
+              >
+                {t("forge.call_stage.lower_hand_of")}
+              </button>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}