@tribe-nest/forge 3.38.0 → 3.41.1

package/src/ui/styled/broadcast/BroadcastPlayer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type ComponentType, type ReactNode } from "react";
 import { Maximize, Pause, Pin, Play, Send } from "lucide-react";
 import { io, type Socket } from "socket.io-client";
 import type { IBroadcastPass, ILiveBroadcast } from "../../../types/models";
@@ -10,18 +10,39 @@ import {
   useBroadcastComments,
   useBroadcastSessionApi,
   type BroadcastComment,
+  type BroadcastViewerCredentials,
 } from "../../../data/queries/useBroadcasts";
 import { useForgeT } from "../../../i18n";
 import { useForgeTheme } from "../../theme/ForgeThemeProvider";
+import { CallHelpHint } from "../../media/CallHelpHint";
 import { timeAgo } from "../community/util";
 import { buttonStyle } from "../Button";
 import { Loading } from "../Loading";
+import {
+  broadcastFellBack,
+  chooseBroadcastStage,
+  type BroadcastCredentialsError,
+  type BroadcastRoomState,
+} from "./broadcastStage";
+// Type-only, and it has to stay that way: the module it names imports
+// `mediasoup-client`, and a value import here would put a browser-only package
+// on the server path of every site that loads `@tribe-nest/forge/ui`. It is
+// reached through the `import()` in the effect below, which no server runs.
+import type { BroadcastRealtimeStageProps } from "./BroadcastRealtimeStage";
+import { BroadcastPollPanel } from "./BroadcastPollPanel";
+import { useBroadcastPoll } from "../../headless/broadcast/useBroadcastPoll";
+import type { BroadcastPoll } from "../../../data/queries/useBroadcasts";
 
 /** The socket messages a watching browser sends and receives. */
 const SocketEvent = {
   BroadcastChatMessage: "broadcastChatMessage",
   BroadcastJoin: "broadcastJoin",
   BroadcastPinComment: "broadcastPinComment",
+  // Server to viewer only. A vote goes over HTTP, because it needs the unique
+  // index behind it; the result comes back here to everyone watching.
+  BroadcastPollStarted: "broadcastPollStarted",
+  BroadcastPollResults: "broadcastPollResults",
+  BroadcastPollEnded: "broadcastPollEnded",
 } as const;
 
 /**
@@ -35,6 +56,26 @@ const SIMULCAST_QUALITIES = [
   { label: "forge.broadcast_player.quality_low", value: "q" },
 ] as const;
 
+/**
+ * The token endpoint's refusal, reduced to what the decision needs.
+ *
+ * Nothing here distinguishes a 409 from a 500 from a dead network, and that is
+ * the point: every one of them means this viewer is not getting into the live
+ * room, and every one of them ends with them watching the stream instead. The
+ * status and the message are carried so a site can log which it was.
+ */
+function credentialsRefusal(error: unknown): BroadcastCredentialsError {
+  const response = (error as { response?: { status?: number; data?: { reason?: unknown; message?: unknown } } } | null)
+    ?.response;
+  const status = response?.status;
+  // The 409 answers with `{ reason }` (`full` or `unavailable`); everything
+  // else on this API answers with `{ message }`. Either is worth keeping for a
+  // log, and neither changes what happens next.
+  const detail = response?.data?.reason ?? response?.data?.message;
+  const message = typeof detail === "string" ? detail : undefined;
+  return { ...(typeof status === "number" ? { status } : {}), ...(message ? { message } : {}) };
+}
+
 const newId = (): string => {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
   return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
@@ -65,15 +106,42 @@ export interface BroadcastPlayerProps {
 /**
  * The watch surface: the stream, who else is here, and the chat.
  *
- * Mounted ONLY behind a validated pass. Two playback paths, chosen by the
- * broadcast itself: a WebRTC subscription when the broadcast carries a realtime
- * config (sub-second, with a quality picker), and HLS otherwise.
+ * Mounted ONLY behind a validated pass. Three playback paths, chosen by the
+ * broadcast itself and never by the viewer:
+ *
+ * 1. **The media plane** (`realtime.available`). A v2 broadcast whose live room
+ *    is open, watched over WebRTC in well under a second. This is the path that
+ *    can be REFUSED: the room has a hard cap, so being turned away is ordinary.
+ * 2. **Cloudflare Calls** (`realtimeConfig`). The v1 realtime path, unchanged
+ *    and still carrying its quality picker, until v1 itself is retired.
+ * 3. **HLS.** Six to ten seconds behind and always available.
+ *
+ * ## Falling back is the feature, not the error path
+ *
+ * A viewer who cannot get onto the plane must end up watching the broadcast,
+ * without doing anything and without being asked anything. So every uncertain
+ * state resolves to HLS, and the four ways the plane can fail (the token
+ * endpoint answering 409, any other failure fetching one, the room closing, and
+ * the SDK giving up) all land in the same place. `chooseBroadcastStage` holds
+ * the rule and `broadcastStage.spec.ts` walks every combination of it.
+ *
+ * The one thing the viewer is told is a single line saying which stream they
+ * are on, because a stream that is suddenly eight seconds behind a chat they
+ * are reading is something a person needs an explanation for. Why it happened
+ * is behind the `?`, per the house design law.
+ *
+ * ## Why the quality picker is not on the new path
+ *
+ * The plane has no simulcast. Every viewer receives the program feed's single
+ * encoding, so High, Medium and Low would be three controls that change
+ * nothing. A control that lies about what it does is worse than no control.
  */
 export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: BroadcastPlayerProps) {
   const t = useForgeT();
   const theme = useForgeTheme();
   const { apiUrl, profileId } = useForge();
   const sessionApi = useBroadcastSessionApi();
+  const poll = useBroadcastPoll(broadcast.id);
 
   const [comments, setComments] = useState<BroadcastComment[]>([]);
   const [comment, setComment] = useState("");
@@ -92,11 +160,125 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   const [realtimeSessionId, setRealtimeSessionId] = useState<string | null>(null);
   const isSubscribingRef = useRef(false);
 
-  const isRealtime = useMemo(
-    () => !!broadcast.realtimeConfig && Object.keys(broadcast.realtimeConfig).length > 0,
-    [broadcast.realtimeConfig],
+  const realtimeAvailable = broadcast.realtime?.available === true;
+
+  /**
+   * The v1 Cloudflare path, and it yields to the plane rather than competing
+   * with it. A broadcast carries one or the other in practice; if one ever
+   * carried both, the newer plane is the one to attempt, and a plane that
+   * refuses falls back to HLS as the contract says rather than sideways into a
+   * v1 session that will not exist.
+   */
+  const isLegacyRealtime = useMemo(
+    () => !realtimeAvailable && !!broadcast.realtimeConfig && Object.keys(broadcast.realtimeConfig).length > 0,
+    [realtimeAvailable, broadcast.realtimeConfig],
   );
 
+  // ── The media plane ────────────────────────────────────────────────────────
+  const [PlaneStage, setPlaneStage] = useState<ComponentType<BroadcastRealtimeStageProps> | null>(null);
+  const [credentialsReady, setCredentialsReady] = useState(false);
+  const [credentialsError, setCredentialsError] = useState<BroadcastCredentialsError | null>(null);
+  const [roomState, setRoomState] = useState<BroadcastRoomState | undefined>(undefined);
+  /** The ticket the probe already minted, spent on the SDK's FIRST attempt. */
+  const primedCredentials = useRef<BroadcastViewerCredentials | null>(null);
+
+  // `sessionApi` is rebuilt every render, so it is read through a ref rather
+  // than depended on: as a dependency it would re-mint a ticket on every render.
+  const sessionApiRef = useRef(sessionApi);
+  sessionApiRef.current = sessionApi;
+
+  /**
+   * The pass is the credential this endpoint takes, and `sessionId` is the id
+   * the pass is known by everywhere else on this surface (it is what
+   * `validate-session` is given, and `viewer-token` validates the pass the same
+   * way before minting).
+   */
+  const passId = broadcastPass.sessionId;
+
+  const mintCredentials = useCallback(
+    () => sessionApiRef.current.viewerToken({ broadcastId: broadcast.id, ...(passId ? { passId } : {}) }),
+    [broadcast.id, passId],
+  );
+
+  /**
+   * Load the SDK and mint a ticket, together, in an effect.
+   *
+   * The effect is what makes this safe on a server: Forge renders inside
+   * TanStack Start on Cloudflare Workers, `BroadcastRealtimeStage` imports
+   * `mediasoup-client`, and an effect is code no server ever runs. Nothing on
+   * the module path of this file touches the media SDK.
+   *
+   * They are fetched together because neither is any use without the other, and
+   * because a viewer must not be moved onto the plane until BOTH are in hand:
+   * mounting the provider first would show a black rectangle for as long as the
+   * chunk took to arrive. A chunk that never arrives lands in the same `catch`
+   * as a refused ticket and falls back the same way.
+   */
+  useEffect(() => {
+    if (!realtimeAvailable) return;
+    let cancelled = false;
+
+    Promise.all([import("./BroadcastRealtimeStage"), mintCredentials()])
+      .then(([module, credentials]) => {
+        if (cancelled) return;
+        primedCredentials.current = credentials;
+        setPlaneStage(() => module.BroadcastRealtimeStage);
+        setCredentialsReady(true);
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        setCredentialsError(credentialsRefusal(error));
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [realtimeAvailable, mintCredentials]);
+
+  /**
+   * Handed to the provider, which calls it before EVERY attempt rather than
+   * once. A viewer ticket expires in ten minutes and a broadcast runs longer,
+   * so a token fetched once means the first reconnect presents a dead one.
+   *
+   * The probe's ticket is spent here on the first call, so one viewer does not
+   * mint two identities to watch one broadcast.
+   */
+  const getCredentials = useCallback(async () => {
+    const primed = primedCredentials.current;
+    primedCredentials.current = null;
+    if (primed) return primed;
+    try {
+      return await mintCredentials();
+    } catch (error) {
+      // A refusal on a reconnect says the same thing as a refusal on the first
+      // attempt: this viewer is not getting back into the room. Recording it is
+      // what moves them onto HLS instead of leaving the SDK knocking.
+      setCredentialsError(credentialsRefusal(error));
+      throw error;
+    }
+  }, [mintCredentials]);
+
+  /**
+   * Never cleared back to `undefined` when the stage unmounts, and that is
+   * load-bearing. A room that has closed is the reason we left it, so forgetting
+   * it would choose the plane again, mount the provider again, and watch it
+   * close again, for ever.
+   */
+  const handleRoomState = useCallback((next: BroadcastRoomState) => setRoomState(next), []);
+
+  const stageInput = useMemo(
+    () => ({ realtimeAvailable, credentialsReady, credentialsError, roomState }),
+    [realtimeAvailable, credentialsReady, credentialsError, roomState],
+  );
+  const stage = chooseBroadcastStage(stageInput);
+  const showPlane = stage === "realtime" && !!PlaneStage;
+  // Nothing is mounted while the ticket is in flight. `react-player` builds an
+  // hls.js instance on mount and starts fetching immediately, so rendering the
+  // HLS stage "meanwhile" made every realtime viewer download the broadcast a
+  // second time, over the CDN, for a stage that was about to be replaced.
+  const showHls = stage === "hls" && !isLegacyRealtime;
+  const fellBack = broadcastFellBack(stageInput);
+
   const { data: audienceData } = useBroadcastAudience(broadcast.id, !broadcast.endedAt);
   const { data: initialComments } = useBroadcastComments(broadcast.id);
 
@@ -113,10 +295,10 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     });
   }, [comments]);
 
-  // ── WebRTC subscription ────────────────────────────────────────────────────
+  // ── WebRTC subscription, v1 (Cloudflare Calls) ─────────────────────────────
   useEffect(() => {
     const config = broadcast.realtimeConfig;
-    if (!isRealtime || !config) return;
+    if (!isLegacyRealtime || !config) return;
     if (isSubscribingRef.current) return;
     isSubscribingRef.current = true;
 
@@ -150,6 +332,10 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
         type: local?.type,
         trackIds: config.tracks.map((track) => track.trackName),
         sessionId: config.sessionId,
+        // The pass, because subscribing IS playback: this endpoint used to
+        // take a session id and a track name from anybody and hand back the
+        // stream, which made the ticket box in front of it decoration.
+        passId,
       });
 
       setRealtimeSessionId(answer.sessionId);
@@ -166,7 +352,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     // `sessionApi` is rebuilt each render and is deliberately not a dependency:
     // including it would re-negotiate the peer connection on every render.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isRealtime, broadcast.realtimeConfig]);
+  }, [isLegacyRealtime, broadcast.realtimeConfig]);
 
   // ── Chat socket ────────────────────────────────────────────────────────────
   useEffect(() => {
@@ -187,6 +373,17 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
         setComments((prev) => [...prev, data.message]);
         return;
       }
+      if (
+        message.event === SocketEvent.BroadcastPollStarted ||
+        message.event === SocketEvent.BroadcastPollResults
+      ) {
+        poll.onPollEvent((message.data as { poll: BroadcastPoll }).poll);
+        return;
+      }
+      if (message.event === SocketEvent.BroadcastPollEnded) {
+        poll.onPollEvent(null);
+        return;
+      }
       if (message.event === SocketEvent.BroadcastPinComment) {
         const data = message.data as { broadcastId: string; comment: BroadcastComment | null };
         setPinnedComment(data.comment);
@@ -194,7 +391,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     });
 
     socketRef.current = socket;
-  }, [apiUrl, profileId, broadcast.id]);
+  }, [apiUrl, profileId, broadcast.id, poll.onPollEvent]);
 
   const sendComment = () => {
     if (!profileId || !socketRef.current || !comment.trim()) return;
@@ -213,7 +410,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   };
 
   const togglePlay = () => {
-    if (!isRealtime || !isAudioLoaded || !isVideoLoaded) return;
+    if (!isLegacyRealtime || !isAudioLoaded || !isVideoLoaded) return;
     if (isPlaying) {
       audioRef.current?.pause();
       videoRef.current?.pause();
@@ -239,6 +436,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     const videoTrack = config.tracks.find((track) => track.mid === "0");
     try {
       await sessionApi.switchQuality({
+        passId,
         track: {
           ...videoTrack,
           sessionId: realtimeSessionId,
@@ -283,7 +481,15 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
       }}
     >
       <div style={{ flex: "1 1 520px", minWidth: 0, ...panel }}>
-        {!isRealtime && (
+        {showPlane && PlaneStage && <PlaneStage getCredentials={getCredentials} onRoomState={handleRoomState} />}
+
+        {stage === "pending" && (
+          <div style={{ aspectRatio: "16/9", display: "grid", placeItems: "center" }}>
+            <Loading />
+          </div>
+        )}
+
+        {showHls && (
           <div data-testid="broadcast-hls-stage" style={{ aspectRatio: "16/9" }}>
             {renderPlayer ? (
               renderPlayer({ src: broadcast.liveUrl })
@@ -299,7 +505,34 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
           </div>
         )}
 
-        {isRealtime && (
+        {/*
+          Which stream they ended up on. This is STATE, not an explanation, so
+          it stays visible: a viewer whose picture is suddenly eight seconds
+          behind the chat beside it needs to know that before they go looking
+          for a fault. The reason it happened is help, so it is behind the `?`.
+        */}
+        {fellBack && (
+          <div
+            role="status"
+            data-testid="broadcast-fallback-notice"
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: 6,
+              padding: "8px 16px 0",
+              fontSize: 13,
+              color: theme.colors.text,
+              opacity: 0.75,
+            }}
+          >
+            <span>{t("forge.broadcast_player.fallback_notice")}</span>
+            <CallHelpHint label={t("forge.broadcast_player.fallback_help_label")}>
+              {t("forge.broadcast_player.fallback_help")}
+            </CallHelpHint>
+          </div>
+        )}
+
+        {isLegacyRealtime && (
           <div
             ref={videoContainerRef}
             data-testid="broadcast-realtime-stage"
@@ -403,7 +636,13 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
             </div>
           </div>
 
-          {isRealtime && (
+          {/*
+            v1 only. The media plane has no simulcast, so on that path these
+            four options would all resolve to the one encoding the program feed
+            publishes, and a picker that cannot change anything is a lie about
+            what the viewer is receiving.
+          */}
+          {isLegacyRealtime && (
             <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
               <label htmlFor="broadcast-quality">{t("forge.broadcast_player.quality")}</label>
               <select
@@ -435,6 +674,8 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
           {t("forge.broadcast_player.chat")}
         </p>
 
+        <BroadcastPollPanel poll={poll} />
+
         {pinnedComment && (
           <div
             data-testid="broadcast-pinned-comment"

package/src/ui/styled/broadcast/BroadcastPollPanel.tsx

@@ -0,0 +1,124 @@
+import { BarChart3 } from "lucide-react";
+
+import { useForgeT } from "../../../i18n";
+import { useForgeTheme } from "../../theme/ForgeThemeProvider";
+import { pollPercentages } from "./pollResults";
+import type { BroadcastPollApi } from "../../headless/broadcast/useBroadcastPoll";
+
+/**
+ * The poll, beside the stream.
+ *
+ * This is the interactive half of the feature. The other half is a results
+ * block composited into the video itself by the studio, which is what an
+ * audience on YouTube or Twitch sees: they get the outcome, and only viewers on
+ * the creator's own site can actually answer.
+ *
+ * ## Results are shown after voting, not before
+ *
+ * A poll that shows the tallies while you are still choosing is not measuring
+ * what the room thinks, it is measuring what the room saw the room think. So
+ * the options are buttons until this browser has answered, and bars afterwards.
+ * A closed poll goes straight to bars for everybody.
+ */
+export function BroadcastPollPanel({ poll: api }: { poll: BroadcastPollApi }) {
+  const t = useForgeT();
+  const theme = useForgeTheme();
+  const { poll, votedOptionId, voting, error } = api;
+
+  if (!poll || poll.status === "draft") return null;
+
+  const showResults = !!votedOptionId || poll.status !== "live";
+  const results = pollPercentages(poll);
+
+  return (
+    <div
+      data-testid="broadcast-poll"
+      style={{
+        margin: "8px 16px 0",
+        padding: 12,
+        backgroundColor: `${theme.colors.primary}15`,
+        border: `1px solid ${theme.colors.primary}50`,
+        borderRadius: theme.cornerRadius,
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", gap: 6, marginBottom: 8 }}>
+        <BarChart3 size={14} style={{ color: theme.colors.primary, flexShrink: 0 }} />
+        <span style={{ fontSize: 12, fontWeight: 500, color: theme.colors.primary }}>
+          {poll.status === "live" ? t("forge.broadcast_poll.live") : t("forge.broadcast_poll.closed")}
+        </span>
+      </div>
+
+      <p style={{ fontSize: 14, fontWeight: 500, marginBottom: 10 }}>{poll.question}</p>
+
+      <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+        {results.map((option) => {
+          const chosen = option.id === votedOptionId;
+
+          if (!showResults) {
+            return (
+              <button
+                key={option.id}
+                type="button"
+                disabled={voting}
+                onClick={() => api.vote(option.id)}
+                style={{
+                  textAlign: "left",
+                  padding: "8px 12px",
+                  fontSize: 14,
+                  cursor: voting ? "default" : "pointer",
+                  borderRadius: theme.cornerRadius,
+                  border: `1px solid ${theme.colors.primary}50`,
+                  background: "transparent",
+                  color: "inherit",
+                  opacity: voting ? 0.6 : 1,
+                }}
+              >
+                {option.label}
+              </button>
+            );
+          }
+
+          return (
+            <div key={option.id}>
+              <div style={{ display: "flex", justifyContent: "space-between", fontSize: 13, marginBottom: 2 }}>
+                <span style={{ fontWeight: chosen ? 600 : 400 }}>
+                  {option.label}
+                  {chosen ? ` ${t("forge.broadcast_poll.your_vote")}` : ""}
+                </span>
+                <span style={{ opacity: 0.7 }}>{option.percent}%</span>
+              </div>
+              <div
+                style={{
+                  height: 6,
+                  borderRadius: 3,
+                  overflow: "hidden",
+                  backgroundColor: `${theme.colors.primary}25`,
+                }}
+              >
+                <div
+                  style={{
+                    height: "100%",
+                    width: `${option.percent}%`,
+                    backgroundColor: theme.colors.primary,
+                    transition: "width 200ms",
+                  }}
+                />
+              </div>
+            </div>
+          );
+        })}
+      </div>
+
+      <p style={{ fontSize: 12, opacity: 0.7, marginTop: 8 }}>
+        {poll.totalVotes === 1
+          ? t("forge.broadcast_poll.votes_one", { count: poll.totalVotes })
+          : t("forge.broadcast_poll.votes_other", { count: poll.totalVotes })}
+      </p>
+
+      {/* An error the viewer has to act on (press it again), so it is visible. */}
+      {error && <p style={{ fontSize: 12, marginTop: 4, color: theme.colors.primary }}>{error}</p>}
+    </div>
+  );
+}
+
+export default BroadcastPollPanel;