@tribe-nest/forge 3.26.0 → 3.31.0

package/src/ui/media/callState.ts

@@ -0,0 +1,341 @@
+import type { ConnectionState, DisconnectCause, ProducerEntry, RoomState } from "@tribe-nest/media-client";
+import {
+  mayPublish,
+  type MediaGrants,
+  type ParticipantKind,
+  type Peer,
+  type PublishSource,
+} from "@tribe-nest/media-protocol";
+
+/**
+ * The call UI's decisions, as pure functions.
+ *
+ * Everything a call screen has to work out from room state lives here rather
+ * than inside a component, because these are the parts that are worth being
+ * sure about and a component is the hardest place to be sure about anything.
+ * Two of them have a specific failure they exist to prevent.
+ *
+ * ## The grid must not collapse
+ *
+ * `callTiles` derives one tile per PARTICIPANT, never one tile per video
+ * stream. A participant with the camera off is an ordinary state, not an
+ * absence: they are still in the room, still speaking, still someone the other
+ * side has to be able to see listed. The commonest bug in this kind of
+ * component is a grid built by mapping over video tracks, which quietly drops
+ * everybody who is not publishing video and re-flows the whole layout the
+ * moment one person turns a camera off.
+ *
+ * ## The connection state must be honest
+ *
+ * `callStatus` maps the room's own five states onto something a person can act
+ * on, and it deliberately keeps "reconnecting" and "failed" apart. A spinner
+ * that means both is a spinner that means nothing: one is worth waiting
+ * through, the other is worth pressing a button about, and only the UI can say
+ * which because only the UI is being looked at.
+ */
+
+/** 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
+   * producer id: a camera going on and off must change what a tile shows, not
+   * unmount and remount the tile.
+   */
+  key: string;
+  identity: string;
+  /** What to print. The peer's name when it has one, else its identity, which
+   * at least tells two unnamed participants apart. */
+  name: string;
+  kind: ParticipantKind;
+  /** 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". */
+  videoProducerId?: string;
+  /** The publisher paused it at source. Their choice, and shown as such. */
+  videoPaused: boolean;
+  /** They are publishing audio at all. A room can be joined listen-only. */
+  hasAudio: boolean;
+};
+
+export type CallTileInput = {
+  /** Our own identity, so we are not drawn twice: self is the local preview. */
+  identity: string | null;
+  peers: readonly Peer[];
+  producers: readonly ProducerEntry[];
+  /** Producer ids, as the node sent them. Not identities. */
+  activeSpeakers: readonly string[];
+};
+
+const displayName = (identity: string, name?: string): string => {
+  const trimmed = name?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : identity;
+};
+
+/**
+ * Every participant, once, plus an extra tile for each additional video stream.
+ *
+ * A participant publishing both a camera and a screen has two video producers
+ * and the wire does not label which is which (`source` travels in the
+ * publisher's `appData`, and the node does not echo it). So the second stream
+ * gets its own tile under the same name rather than being guessed at, and
+ * neither one replaces the other: a shared screen must never take the place of
+ * the face that is talking over it.
+ *
+ * ## The recorder is not a participant
+ *
+ * A recording joins the room as a real peer with `kind: "egress"`, so a grid
+ * that maps over `peers` draws a third tile called something like `egress-9f2c`
+ * in a 1:1 session and the head count says three. That happens at exactly the
+ * moment a coach is most likely to be reading the head count, and the thing it
+ * would be telling them (somebody is recording) is already said properly by
+ * `<RecordingIndicator>`, in words, as content. So `egress` is the one kind
+ * that gets no tile. Every other kind is somebody or something a person is
+ * actually talking to - a dial-in caller, an agent - and belongs on screen.
+ */
+export function callTiles(input: CallTileInput): readonly CallTile[] {
+  const speaking = new Set(input.activeSpeakers);
+  const tiles: CallTile[] = [];
+  const recorders = new Set(input.peers.filter((p) => p.kind === "egress").map((p) => p.identity));
+
+  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));
+
+    if (videos.length === 0) {
+      tiles.push({ key: `${identity}#0`, identity, name, kind, isSpeaking, videoPaused: false, hasAudio });
+      return;
+    }
+    videos.forEach((video, index) => {
+      tiles.push({
+        key: `${identity}#${index}`,
+        identity,
+        name,
+        kind,
+        isSpeaking,
+        videoProducerId: video.producerId,
+        videoPaused: video.paused,
+        hasAudio,
+      });
+    });
+  };
+
+  const seen = new Set<string>();
+  for (const peer of input.peers) {
+    if (peer.identity === input.identity) continue;
+    if (peer.kind === "egress") continue;
+    if (seen.has(peer.identity)) continue;
+    seen.add(peer.identity);
+    push(peer.identity, displayName(peer.identity, peer.name), peer.kind);
+  }
+
+  /**
+   * Producers whose peer we have not been told about yet.
+   *
+   * `producerAppeared` and `peerJoined` are separate frames with no ordering
+   * guarantee, so for a frame or two a stream can exist with nobody to hang it
+   * on. Dropping it would blank a tile that has media in it; drawing it under
+   * the identity is honest and self-corrects on the next frame.
+   */
+  for (const producer of input.producers) {
+    if (producer.identity === input.identity) continue;
+    if (recorders.has(producer.identity)) continue;
+    if (seen.has(producer.identity)) continue;
+    seen.add(producer.identity);
+    push(producer.identity, producer.identity, "human");
+  }
+
+  return tiles;
+}
+
+/**
+ * How many people are in this call, counting the viewer.
+ *
+ * Derived from the tiles' IDENTITIES rather than from how many tiles there are,
+ * because those are different numbers by design: `callTiles` gives a screen
+ * sharer two tiles, one for their face and one for what they are presenting.
+ * Counting tiles therefore announced a third person in the room the instant a
+ * coach shared their screen, which is the one moment a two-person call is
+ * certain to have a second video stream.
+ *
+ * This number is the one thing on the screen a person uses to answer "has my
+ * client actually arrived", so it counts people or it should not be shown.
+ */
+export function callHeadCount(tiles: readonly CallTile[]): number {
+  // +1 for the viewer, who is the local preview and never has a tile here.
+  return new Set(tiles.map((tile) => tile.identity)).size + 1;
+}
+
+/** Remote audio has to be attached to an element or the call is silent. */
+export function remoteAudioProducerIds(input: {
+  identity: string | null;
+  producers: readonly ProducerEntry[];
+}): readonly string[] {
+  return input.producers.filter((p) => p.kind === "audio" && p.identity !== input.identity).map((p) => p.producerId);
+}
+
+export type CallStatusTone = "connecting" | "live" | "reconnecting" | "ended" | "failed";
+
+export type CallStatus = {
+  tone: CallStatusTone;
+  /** Always shown. Connection state is CONTENT, never a help hint. */
+  headline: string;
+  /** The server's own words when it has any. Shown verbatim rather than
+   * translated into a friendlier lie. */
+  detail?: string;
+  /** Is pressing something the right response? Only when waiting will not fix it. */
+  canRetry: boolean;
+};
+
+export type CallStatusInput = {
+  connectionState: ConnectionState;
+  error: DisconnectCause | undefined;
+  /** The ROOM's own phase. `closed` means the node said so, on a live socket. */
+  phase?: RoomState["phase"];
+  closedReason?: string | null;
+  /**
+   * Has the SDK actually booked another attempt?
+   *
+   * `connectionState` is `reconnecting` both while one is in flight and after
+   * the policy has given up, so without this the screen promises a recovery
+   * that may not be happening. Defaults to false, which is the safe reading: it
+   * offers a control rather than a spinner.
+   */
+  recovering?: boolean;
+};
+
+/**
+ * The room's states, told honestly.
+ *
+ * `reconnecting` is the room's state for BOTH "the socket dropped and we are
+ * coming back" and "the node refused us", because the signal client reports one
+ * close path. They are completely different things to a person sitting in front
+ * of it, and the cause is what separates them, so the cause is read here rather
+ * than being flattened into a spinner.
+ *
+ * `phase` is read as well as `connectionState`, and it is not redundant: a
+ * `roomClosed` frame arrives on a socket that is still open, so the connection
+ * is "connected" for as long as it takes the node to hang up. Reading only the
+ * connection would show "Connected" over a call that has ended, which is the
+ * one thing on this list a person would act on wrongly.
+ *
+ * `recovering` is read for the same reason and it is the other half of being
+ * honest. "Moving you to another server" and "Connection lost, reconnecting"
+ * are both PROMISES, and a promise only one side of the SDK is keeping is a
+ * spinner over a call that is finished: the person waits, because the screen
+ * told them to, and the way back into a paid hour turns out to be working out
+ * for themselves that they should reload the page. When nothing is coming, the
+ * words change and a control appears.
+ */
+export function callStatus(input: CallStatusInput): CallStatus {
+  const { connectionState, error } = input;
+  const recovering = input.recovering ?? false;
+
+  if (input.phase === "closed") {
+    return {
+      tone: "ended",
+      headline: "The call has ended",
+      ...(input.closedReason ? { detail: input.closedReason } : {}),
+      canRetry: false,
+    };
+  }
+
+  if (connectionState === "connected") return { tone: "live", headline: "Connected", canRetry: false };
+
+  if (connectionState === "idle" || connectionState === "connecting") {
+    return { tone: "connecting", headline: "Connecting to the call", canRetry: false };
+  }
+
+  if (connectionState === "closed") {
+    if (error?.type === "room_closed") {
+      return { tone: "ended", headline: "The call has ended", detail: error.reason, canRetry: false };
+    }
+    return { tone: "ended", headline: "You have left the call", canRetry: false };
+  }
+
+  // Everything below is `reconnecting`, where the cause is the whole story.
+  switch (error?.type) {
+    case "refused":
+      return {
+        tone: "failed",
+        headline: "Could not join this call",
+        detail: error.message ?? error.code,
+        canRetry: true,
+      };
+    case "room_closed":
+      return { tone: "ended", headline: "The call has ended", detail: error.reason, canRetry: false };
+    case "draining":
+      // A drain is the node asking to be left, so the move is the SDK's job and
+      // a button would only get in its way - as long as the move is actually
+      // happening. When it is not, this is the worst screen on the list: an
+      // ordinary deploy would otherwise end every call on that node under a
+      // spinner saying nobody was dropped.
+      return recovering
+        ? {
+            tone: "reconnecting",
+            headline: "Moving you to another server",
+            detail: "This takes a few seconds and nobody else is dropped.",
+            canRetry: false,
+          }
+        : {
+            tone: "failed",
+            headline: "Could not move you to another server",
+            detail: "Nobody else was dropped. Try again to rejoin.",
+            canRetry: true,
+          };
+    case "closed_by_client":
+      return { tone: "ended", headline: "You have left the call", canRetry: false };
+    default:
+      return recovering
+        ? {
+            tone: "reconnecting",
+            headline: "Connection lost, reconnecting",
+            detail: "Everyone else is still in the call.",
+            canRetry: true,
+          }
+        : {
+            tone: "failed",
+            headline: "Connection lost",
+            detail: "Everyone else is still in the call. Try again to rejoin.",
+            canRetry: true,
+          };
+  }
+}
+
+/**
+ * What a control publishes, in the vocabulary the SDK sends.
+ *
+ * The SOURCE, not the grant's kind, and the difference is the whole point:
+ * `room.publish(track, source)` puts one of these three words on the wire and
+ * the node decides against it. A control asking about "audio" would be asking
+ * a question no publish ever asks.
+ *
+ * Re-exported from the protocol rather than restated, because a second list of
+ * the same three words is a second list that can drift from the one the node
+ * reads.
+ */
+export type { PublishSource };
+
+/**
+ * Should this control be drawn at all?
+ *
+ * A UI hint and nothing more. The node checks the same grant on the publish
+ * itself and its answer is the one that counts, so hiding a button here is
+ * about not offering something that will be refused, never about enforcing
+ * anything. `publishKinds` absent means every kind, which is what the protocol
+ * says and what the node does.
+ *
+ * `mayPublish` is the protocol's own function, the same one the node calls, and
+ * that is deliberate rather than tidy. A grant is written in kinds ("audio",
+ * "video", "screen") and a publish declares a source ("microphone", "camera",
+ * "screen"), so a second copy of the translation living here is a second copy
+ * that can disagree with the node - and a button offered for a publish that is
+ * about to be refused is worse than no button at all.
+ *
+ * The track kind is implied by the source, because these three are the only
+ * sources this UI has: a microphone is audio and the other two are video.
+ */
+export function canPublishSource(grants: MediaGrants | undefined, source: PublishSource): boolean {
+  return mayPublish(grants, { source, trackKind: source === "microphone" ? "audio" : "video" });
+}

package/src/ui/media/index.ts

@@ -0,0 +1,135 @@
+/**
+ * Forge UI - live calls.
+ *
+ * ## Where the ONE call UI lives
+ *
+ * Here. `CallStage` is built once in this package, over the hooks in
+ * `@tribe-nest/media-client/react`, and BOTH rendering surfaces render that one
+ * component: code websites import it from `@tribe-nest/forge/media`, and admin
+ * imports the same export and feeds it the dashboard's own theme tokens through
+ * `<ForgeThemeProvider>`. A second implementation would mean every fix to the
+ * ordering rules - device before transport, attach before resume, follow the
+ * active set - had to be made twice, and the second copy would be the one that
+ * drifted.
+ *
+ * The HOOKS are still pure re-exports, because the room logic belongs to the
+ * SDK and Forge has no business owning a second copy of it.
+ *
+ * ## Why a barrel at all, rather than telling sites to import the SDK
+ *
+ * The code agent builds sites from Forge's manifest, which is generated from
+ * these barrels. An export that is not in one does not exist as far as the
+ * agent is concerned, however well documented it is elsewhere. `./media` is
+ * registered in `ENTRY_SUBPATHS` in `apps/backend/src/utils/forgeManifest.ts`
+ * for exactly that reason.
+ *
+ * ## What a site actually needs to do
+ *
+ * Wrap the call in `<MediaRoomProvider>` and give it a `getCredentials`
+ * callback that fetches a fresh join ticket. It is a CALLBACK rather than a
+ * token because a ticket expires in minutes and a call lasts an hour: a token
+ * passed once means the first reconnect presents an expired one.
+ *
+ * ```tsx
+ * <MediaRoomProvider getCredentials={() => fetchJoinTicket(bookingId)}>
+ *   <CallStage />
+ * </MediaRoomProvider>
+ * ```
+ *
+ * Inside, `useParticipants()`, `useRemoteTrack(producerId)` and
+ * `useLocalMedia()` are the whole surface. Nothing here decides what a
+ * participant is allowed to do: `useGrants()` is for RENDERING - so a button
+ * that the node would refuse is not offered - and the node enforces
+ * independently. A client-side grant check is a UI hint, never the decision.
+ */
+export {
+  MediaRoomProvider,
+  useActiveSpeakers,
+  useGrants,
+  useLocalMedia,
+  useLocalPublications,
+  useMediaRoom,
+  useParticipants,
+  useRecording,
+  useRemoteTrack,
+  useRoomState,
+  // The producers a UI should RENDER: `useRoomState().producers` is the node's
+  // full announcement history and deliberately keeps producers the current
+  // subscribe rule bars, so that a barrier which narrows can later widen.
+  useVisibleProducers,
+  type LocalMediaControls,
+  type LocalSource,
+  type MediaRoomProviderProps,
+} from "@tribe-nest/media-client/react";
+
+export type {
+  ConnectionState,
+  DisconnectCause,
+  LocalPublication,
+  MediaRoom,
+  MediaTrack,
+  // `CallTileInput` is built from these, so a site laying out its own grid over
+  // `callTiles` needs them by name.
+  ProducerEntry,
+  RoomState,
+} from "@tribe-nest/media-client";
+
+export type { MediaGrants, Peer, SubscribeRule } from "@tribe-nest/media-protocol";
+
+/**
+ * The screen itself, and the decisions behind it.
+ *
+ * `CallStage` is the whole call: participant tiles with names, the local
+ * preview, mic / camera / screenshare toggles, an active-speaker indication, a
+ * leave control and an honest connection state. Mount it inside a
+ * `<MediaRoomProvider>` (or `<BookingCallProvider>`) and behind a Join control,
+ * because the provider connects on mount.
+ *
+ * `callTiles`, `callStatus` and `canPublishSource` are exported alongside it for
+ * a surface that wants a different layout over the same decisions. They are
+ * pure and they are where the two failures worth being sure about live: a grid
+ * that keeps a tile for somebody with the camera off, and a connection state
+ * that separates "reconnecting" from "refused" rather than showing one spinner
+ * for both.
+ */
+export { CallStage, type CallStageProps } from "./CallStage";
+export { CallHelpHint, type CallHelpHintProps } from "./CallHelpHint";
+export {
+  callHeadCount,
+  callStatus,
+  callTiles,
+  canPublishSource,
+  remoteAudioProducerIds,
+  type CallStatus,
+  type CallStatusInput,
+  type CallStatusTone,
+  type CallTile,
+  type CallTileInput,
+  type PublishSource,
+} from "./callState";
+
+/**
+ * Coaching sessions held on the platform's own media network.
+ *
+ * These are the ONE thing in this barrel that is not a re-export, because they
+ * are the only part that knows about a TribeNest endpoint: `BookingCallProvider`
+ * is `MediaRoomProvider` already wired to the booking credential endpoint, so a
+ * site never has to know what a join ticket is or how often to fetch one.
+ *
+ * They live in THIS barrel rather than in `./ui` for a mechanical reason: the
+ * code agent builds sites from Forge's manifest, and the manifest is generated
+ * from the registered entry points. An export outside one of them does not
+ * exist as far as the agent is concerned, however well documented it is.
+ */
+export {
+  BOOKING_CALL_CLOSES_MINUTES_AFTER,
+  BOOKING_CALL_OPENS_MINUTES_BEFORE,
+  BookingCallProvider,
+  bookingCallWindow,
+  useBookingSessionCredentials,
+  type BookingCallProviderProps,
+  type BookingCallSubject,
+  type BookingCallWindow,
+  type BookingSessionCredentials,
+  type BookingSessionRole,
+} from "./bookingSession";

package/src/ui/shell/TribeNestApp.tsx

@@ -8,6 +8,7 @@ import { CookieConsent } from "../styled/CookieConsent";
 import { AiAgentWidget } from "../styled/AiAgentWidget";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
+import { ForgeI18nProvider } from "../../i18n";
 import { PoweredBy } from "./PoweredBy";
 import { PreviewDiagnostics } from "./PreviewDiagnostics";
 import { shellAiAgentEnabled, shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
@@ -142,33 +143,41 @@ export function TribeNestApp({
     : null;
   return (
     <ForgeProvider editable={editable} {...forgeProps}>
-      {/* First in the tree: it must render even if everything below it doesn't. */}
-      {ssrFailure && <PreviewDiagnostics diagnostics={ssrFailure} />}
-      {children}
-      {/* "Powered by TribeNest" — last in the page flow, so it sits below the
-          tenant's own footer. Released builds only (live + published). */}
-      <PoweredByGate editable={editable} state={state} />
-      {/* Global playback bar — self-pins to the viewport bottom, renders nothing
-          until a track loads. */}
-      <AudioPlayer />
-      {/* Auto page views + clicks (+ Meta Pixel, gated on marketing consent).
-          First-party runs cookieless. Off in the editor so preview isn't counted. */}
-      {analytics && <ForgeAnalytics enabled={!editable} firstPartyMode="cookieless" />}
-      {/* Ad attribution capture (tracked-link ref + first-touch landing + visit
-          beacon). Off in the editor so preview visits aren't credited. */}
-      <AttributionCapture enabled={!editable} apiUrl={forgeProps.apiUrl} profileId={forgeProps.profileId} />
-      {/* PWA — SW registration + install banner + (fallback) manifest link. */}
-      {pwa && <PwaRegistration enabled={pwaEnabled} />}
-      {pwa && <InstallBanner enabled={pwaEnabled} />}
-      {pwa && <PwaHeadClient enabled={pwaEnabled} manifestHref={manifestHref} />}
-      {/* Consent banner — shown on first visit, re-openable from anywhere via
-          useCookieConsent().reopen(). Hidden in the editor. */}
-      {cookieConsent && !editable && <CookieConsent useTribeNestPrivacy />}
-      {/* Website AI agent — floating bubble, self-hiding when the profile has no
-          agent enabled. Lives here rather than in each __root so enabling the
-          agent in admin is enough to make it appear; before this it shipped only
-          on the Craft stack and no code site ever rendered it. */}
-      {shellAiAgentEnabled({ aiAgent, editable, appId: forgeProps.appId }) && <AiAgentWidget />}
+      {/* Forge's own copy, in the site's language. Mounted here rather than in
+          each tenant's __root.tsx, so a Forge upgrade is enough to give an
+          existing site i18n. `locale` is the ForgeProvider prop the site
+          already passes (absent or unsupported resolves to English). When
+          `profile_configurations.locale` lands on SiteConfig, that becomes the
+          source and this prop stays the override. */}
+      <ForgeI18nProvider locale={forgeProps.locale}>
+        {/* First in the tree: it must render even if everything below it doesn't. */}
+        {ssrFailure && <PreviewDiagnostics diagnostics={ssrFailure} />}
+        {children}
+        {/* "Powered by TribeNest" — last in the page flow, so it sits below the
+            tenant's own footer. Released builds only (live + published). */}
+        <PoweredByGate editable={editable} state={state} />
+        {/* Global playback bar — self-pins to the viewport bottom, renders nothing
+            until a track loads. */}
+        <AudioPlayer />
+        {/* Auto page views + clicks (+ Meta Pixel, gated on marketing consent).
+            First-party runs cookieless. Off in the editor so preview isn't counted. */}
+        {analytics && <ForgeAnalytics enabled={!editable} firstPartyMode="cookieless" />}
+        {/* Ad attribution capture (tracked-link ref + first-touch landing + visit
+            beacon). Off in the editor so preview visits aren't credited. */}
+        <AttributionCapture enabled={!editable} apiUrl={forgeProps.apiUrl} profileId={forgeProps.profileId} />
+        {/* PWA — SW registration + install banner + (fallback) manifest link. */}
+        {pwa && <PwaRegistration enabled={pwaEnabled} />}
+        {pwa && <InstallBanner enabled={pwaEnabled} />}
+        {pwa && <PwaHeadClient enabled={pwaEnabled} manifestHref={manifestHref} />}
+        {/* Consent banner — shown on first visit, re-openable from anywhere via
+            useCookieConsent().reopen(). Hidden in the editor. */}
+        {cookieConsent && !editable && <CookieConsent useTribeNestPrivacy />}
+        {/* Website AI agent — floating bubble, self-hiding when the profile has no
+            agent enabled. Lives here rather than in each __root so enabling the
+            agent in admin is enough to make it appear; before this it shipped only
+            on the Craft stack and no code site ever rendered it. */}
+        {shellAiAgentEnabled({ aiAgent, editable, appId: forgeProps.appId }) && <AiAgentWidget />}
+      </ForgeI18nProvider>
     </ForgeProvider>
   );
 }