@tribe-nest/forge 3.38.0 → 3.41.1

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

@@ -0,0 +1,260 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Maximize, Volume2, VolumeX } from "lucide-react";
+
+import type { MediaRoomCredentials } from "@tribe-nest/media-client";
+import {
+  MediaRoomProvider,
+  useMediaRoom,
+  useRemoteTrack,
+  useRoomState,
+  useVisibleProducers,
+} from "@tribe-nest/media-client/react";
+
+import { useForgeT } from "../../../i18n";
+import { useForgeTheme } from "../../theme/ForgeThemeProvider";
+import { Loading } from "../Loading";
+import { programTracks, type BroadcastRoomState } from "./broadcastStage";
+
+/**
+ * A live broadcast, received over the platform's own media plane.
+ *
+ * ## Why this is its own file, and why nothing imports it directly
+ *
+ * `@tribe-nest/media-client/react` pulls in `mediasoup-client`, which touches
+ * `RTCPeerConnection` at module scope and does not exist on a server. Forge
+ * renders inside TanStack Start on Cloudflare Workers, and `BroadcastPlayer`
+ * lives in the `./ui` entry that every site loads on every page, so a static
+ * import of the SDK from the player would put a browser-only module on the
+ * server path of sites that have never held a broadcast. So the player reaches
+ * this file through a dynamic `import()` fired from an effect, which is code
+ * that cannot run anywhere but a browser. `./media` (the coaching call surface)
+ * is a separate entry that a site opts into, which is why it may import the SDK
+ * at module scope and this may not.
+ *
+ * ## What it renders
+ *
+ * One publisher, `program:<broadcastId>`, with one video producer and one audio
+ * producer. The viewer's token can subscribe to that identity and nothing else,
+ * so the producers this sees ARE the broadcast (see `programTracks`).
+ *
+ * ## Sound is a toggle, and play/pause is not offered
+ *
+ * The picture starts on its own, muted, because a muted autoplay is the one
+ * thing every browser allows without a gesture and a viewer who has arrived at
+ * a live stream should see it. Sound needs the gesture, so it gets the control.
+ *
+ * What it deliberately does NOT get is a pause button. There is nothing to
+ * resume: this is a subscription to what is happening now, so a "pause" is a
+ * mute plus a blank screen plus a lie about being able to go back. The HLS
+ * stage keeps its transport controls because there the buffer makes them true.
+ *
+ * There is no quality selector either. The plane has no simulcast: every viewer
+ * receives the program feed's single encoding, so a picker offering High,
+ * Medium and Low would be three buttons that all do the same nothing.
+ */
+
+export type BroadcastRealtimeStageProps = {
+  /**
+   * Called before EVERY attempt, not once, which is why it is a callback. A
+   * viewer credential expires in ten minutes and a broadcast runs for longer,
+   * so a token fetched once means the first reconnect presents a dead one.
+   */
+  getCredentials: () => Promise<MediaRoomCredentials>;
+  /**
+   * The room, reported upward on every change.
+   *
+   * The decision to fall back to HLS is made by the PLAYER, above the provider,
+   * because falling back means unmounting the provider and a component cannot
+   * unmount itself. So this reports and the player decides, and there is one
+   * `chooseBroadcastStage` rather than one here and another one up there.
+   */
+  onRoomState: (state: BroadcastRoomState) => void;
+};
+
+export function BroadcastRealtimeStage({ getCredentials, onRoomState }: BroadcastRealtimeStageProps) {
+  return (
+    <MediaRoomProvider getCredentials={getCredentials} autoSubscribe>
+      <ProgramStage onRoomState={onRoomState} />
+    </MediaRoomProvider>
+  );
+}
+
+function ProgramStage({ onRoomState }: { onRoomState: (state: BroadcastRoomState) => void }) {
+  const t = useForgeT();
+  const theme = useForgeTheme();
+  const { connectionState, error, recovering } = useMediaRoom();
+  const state = useRoomState();
+  const producers = useVisibleProducers();
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [soundOn, setSoundOn] = useState(false);
+  const [showControls, setShowControls] = useState(false);
+
+  // Memoised on the room's own snapshot, which is a stable reference while
+  // nothing has changed. Rebuilding it per render is what turns a stage into a
+  // component that re-renders per frame.
+  const tracks = useMemo(() => programTracks(producers), [producers]);
+  const { track, attach } = useRemoteTrack(tracks.videoProducerId ?? "");
+  const hasPicture = !!tracks.videoProducerId && !!track && !tracks.videoPaused;
+
+  useEffect(() => {
+    onRoomState({ connectionState, phase: state.phase, recovering, ...(error ? { error } : {}) });
+  }, [onRoomState, connectionState, state.phase, recovering, error]);
+
+  const toggleFullscreen = () => {
+    if (!containerRef.current) return;
+    if (document.fullscreenElement) void document.exitFullscreen();
+    else void containerRef.current.requestFullscreen();
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="broadcast-plane-stage"
+      onMouseEnter={() => setShowControls(true)}
+      onMouseLeave={() => setShowControls(false)}
+      // The ratio is on BOTH this box and the video inside it, and that is not
+      // redundancy for its own sake. The container's ratio is what guarantees
+      // the panel has a height at all, including before a single frame has
+      // arrived; removing it once collapsed the stage and the chat beside it
+      // rode up into the gap. The video's own ratio (below) is what keeps that
+      // height still while simulcast changes the resolution underneath it.
+      // They compute to the same box, so nothing fights.
+      style={{ aspectRatio: "16 / 9", position: "relative", background: "#000", lineHeight: 0 }}
+    >
+      {/*
+        Muted, always, and that is not the sound control. The audio arrives as
+        its own producer on its own element, so a viewer who unmuted THIS would
+        hear nothing and conclude the stream is silent.
+      */}
+      {/*
+        The RATIO is on the video itself, which is what keeps the box still.
+
+        Simulcast changes the incoming resolution underneath us as the node
+        moves a viewer between layers (1080p to 540p to 270p). A replaced
+        element takes its box partly from the track's intrinsic size, and
+        `height: 100%` did not save it: a percentage height needs a definite
+        parent height, and one derived from the container's own `aspect-ratio`
+        is not reliably that. So the element fell back to intrinsic height and
+        the whole panel jumped on every layer switch, at the one moment a
+        viewer should notice nothing.
+
+        `aspect-ratio` on the element with `height: auto` overrides the
+        intrinsic ratio outright: the box is 16/9 of whatever width it is
+        given, whatever arrives on the wire. `height: 100%` is deliberately
+        NOT used, because that is the thing that failed.
+      */}
+      <video
+        ref={attach}
+        autoPlay
+        playsInline
+        muted
+        style={{ display: "block", width: "100%", height: "auto", aspectRatio: "16 / 9", objectFit: "contain" }}
+      />
+
+      {tracks.audioProducerIds.map((producerId) => (
+        <ProgramAudio key={producerId} producerId={producerId} soundOn={soundOn} />
+      ))}
+
+      {!hasPicture && (
+        <div
+          style={{
+            position: "absolute",
+            top: "50%",
+            left: "50%",
+            transform: "translate(-50%, -50%)",
+            pointerEvents: "none",
+          }}
+        >
+          <Loading />
+        </div>
+      )}
+
+      {hasPicture && (
+        <button
+          type="button"
+          onClick={() => setSoundOn((was) => !was)}
+          aria-label={soundOn ? t("forge.broadcast_player.sound_off") : t("forge.broadcast_player.sound_on")}
+          style={{
+            position: "absolute",
+            bottom: 16,
+            left: 16,
+            padding: 8,
+            borderRadius: theme.cornerRadius,
+            border: "none",
+            cursor: "pointer",
+            background: "rgba(0, 0, 0, 0.5)",
+            color: "#ffffff",
+            zIndex: 1,
+            // Kept on screen while the sound is off, because it is the control
+            // a viewer arriving at a silent stream is looking for. Once the
+            // sound is on it behaves like the rest of the chrome.
+            opacity: soundOn && !showControls ? 0 : 1,
+            transition: "opacity 150ms",
+          }}
+        >
+          {soundOn ? <Volume2 size={20} /> : <VolumeX size={20} />}
+        </button>
+      )}
+
+      {hasPicture && (
+        <button
+          type="button"
+          onClick={toggleFullscreen}
+          aria-label={t("forge.broadcast_player.fullscreen")}
+          style={{
+            position: "absolute",
+            bottom: 16,
+            right: 16,
+            padding: 8,
+            borderRadius: theme.cornerRadius,
+            border: "none",
+            cursor: "pointer",
+            background: "rgba(0, 0, 0, 0.5)",
+            color: "#ffffff",
+            zIndex: 1,
+          }}
+        >
+          <Maximize size={20} />
+        </button>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The program's audio, attached and never drawn.
+ *
+ * Held on its own element rather than on the `<video>`, because the two arrive
+ * as separate producers and the video element is muted for good (see above).
+ *
+ * `play()` is called from an effect rather than through `autoPlay` so that a
+ * producer arriving AFTER the viewer turned the sound on is audible too: an
+ * `autoPlay` attribute is read when the element mounts, and a track that lands
+ * later would leave a broadcast playing in silence with the speaker icon on.
+ * The rejection is swallowed on purpose: a browser refusing to play unprompted
+ * audio is the ordinary case this control exists to get past, not an error.
+ */
+function ProgramAudio({ producerId, soundOn }: { producerId: string; soundOn: boolean }) {
+  const { track, attach } = useRemoteTrack(producerId);
+  const elementRef = useRef<HTMLAudioElement | null>(null);
+
+  const setElement = useCallback(
+    (element: HTMLAudioElement | null) => {
+      elementRef.current = element;
+      attach(element);
+    },
+    [attach],
+  );
+
+  useEffect(() => {
+    const element = elementRef.current;
+    if (!element) return;
+    if (soundOn) void element.play().catch(() => undefined);
+    else element.pause();
+  }, [soundOn, track]);
+
+  return <audio ref={setElement} style={{ display: "none" }} />;
+}
+
+export default BroadcastRealtimeStage;

package/src/ui/styled/broadcast/broadcastStage.ts

@@ -0,0 +1,189 @@
+import type { ConnectionState, DisconnectCause, ProducerEntry, RoomState } from "@tribe-nest/media-client";
+
+/**
+ * Which stage a live broadcast plays on, as pure functions.
+ *
+ * A v2 broadcast can be watched two ways. The platform's own media plane
+ * carries it over WebRTC in well under a second, and HLS carries it to
+ * everybody else six to ten seconds behind. The plane is the better picture and
+ * it is also the one with a hard cap on it (`STREAM_V2_REALTIME_VIEWER_CAP`,
+ * 100 by default), so being turned away from it is an ORDINARY outcome rather
+ * than an error, and the viewer who is turned away must simply end up watching
+ * the stream.
+ *
+ * That is the whole reason this is a pure function in its own file. The choice
+ * is made from four independent signals arriving at four different times (what
+ * the broadcast advertises, what the token endpoint answered, what the SDK is
+ * doing, and whether the room is still open), and a rule assembled inline out
+ * of four `if`s inside a component is a rule nobody can test and everybody
+ * edits. `callState.ts` splits the call screen's decisions out for the same
+ * reason.
+ *
+ * ## The bias, stated once
+ *
+ * Every uncertain state resolves to `hls`. A viewer on HLS is watching the
+ * broadcast a few seconds late; a viewer left on a realtime stage that is not
+ * going to connect is watching a black rectangle. Those are not comparable
+ * failures, so the ambiguity is spent in the direction that always shows a
+ * picture.
+ */
+
+/** `realtime` is the media plane. `hls` is the stream everybody can always watch. */
+/**
+ * Which stage the player shows.
+ *
+ * `pending` is the state between "this broadcast offers realtime" and knowing
+ * whether this viewer gets it. It draws nothing on purpose: the alternative
+ * was showing HLS meanwhile, and an HLS engine starts fetching the moment it
+ * mounts, so a realtime viewer pulled segments they would never watch.
+ */
+export type BroadcastStage = "realtime" | "hls" | "pending";
+
+/**
+ * The viewer-token endpoint said no.
+ *
+ * `409` is the designed refusal (the room is full, realtime is off, or nothing
+ * is live) and it is not special-cased below: a refusal is a refusal, and a
+ * network failure with no status at all falls back exactly the same way. The
+ * status is carried so a caller can log which one happened, never so this
+ * function can treat one as recoverable.
+ */
+export type BroadcastCredentialsError = {
+  /** The HTTP status when the server answered at all. Absent on a network failure. */
+  status?: number;
+  message?: string;
+};
+
+/** What the SDK says about the live room. Absent until the provider is mounted. */
+export type BroadcastRoomState = {
+  connectionState: ConnectionState;
+  /** The ROOM's phase. `closed` means the node said so, on a socket still open. */
+  phase: RoomState["phase"];
+  /**
+   * Is another attempt actually booked?
+   *
+   * `connectionState` is `reconnecting` both while the SDK is coming back and
+   * after its policy has given up, so without this a broadcast whose room died
+   * would sit on a frozen frame for ever rather than falling back.
+   */
+  recovering: boolean;
+  error?: DisconnectCause;
+};
+
+export type BroadcastStageInput = {
+  /** `broadcast.realtime.available`, as the public read reported it. */
+  realtimeAvailable: boolean;
+  /** A viewer credential has been minted. Nothing is mounted before it has. */
+  credentialsReady: boolean;
+  /** The refusal, when the fetch failed. `null` while it has not. */
+  credentialsError: BroadcastCredentialsError | null;
+  roomState?: BroadcastRoomState;
+};
+
+/**
+ * Is the realtime attempt over, as opposed to merely in progress?
+ *
+ * A drop that the SDK is recovering from is NOT over: it holds the last frame
+ * for a second or two and comes back, and tearing the room down to swap in an
+ * HLS player would turn a blink into a restart. A drain is the same, as long as
+ * the move is really happening. Everything else on this list is finished:
+ * refused, the room closed, the socket closed for good, or the reconnect policy
+ * exhausted with nothing booked.
+ */
+function realtimeIsOver(roomState: BroadcastRoomState | undefined): boolean {
+  if (!roomState) return false;
+  if (roomState.phase === "closed") return true;
+  if (roomState.connectionState === "closed") return true;
+  if (roomState.error?.type === "refused") return true;
+  if (roomState.error?.type === "room_closed") return true;
+  return roomState.connectionState === "reconnecting" && !roomState.recovering;
+}
+
+/**
+ * The stage to render right now.
+ *
+ * Read in order, and the order is the safety property: nothing reaches the
+ * realtime branch until the broadcast has offered it, a credential has actually
+ * been minted, and the room is still alive.
+ */
+export function chooseBroadcastStage(input: BroadcastStageInput): BroadcastStage {
+  if (!input.realtimeAvailable) return "hls";
+  if (input.credentialsError) return "hls";
+  // PENDING, not "hls". Answering "hls" here mounted the HLS engine for the
+  // moment the ticket was in flight, and an HLS engine does not idle: it
+  // fetched the playlist and started pulling segments for a stage that was
+  // about to be replaced, so a realtime viewer downloaded the broadcast twice.
+  // Nothing is drawn until the answer is known.
+  if (!input.credentialsReady) return "pending";
+  if (realtimeIsOver(input.roomState)) return "hls";
+  return "realtime";
+}
+
+/**
+ * Did this viewer come DOWN to HLS, or were they always going to be here?
+ *
+ * The distinction is the whole content of the line the player shows. A
+ * broadcast that never offered realtime has nothing to explain, and a page that
+ * says "watching the standard stream" on every ordinary stream is a page that
+ * has taught its viewers to ignore the one time it matters.
+ *
+ * A token fetch still in flight is deliberately NOT a fallback. It resolves in
+ * a moment, and announcing a fallback that is about to be withdrawn is a line
+ * that flickers on every single load.
+ */
+export function broadcastFellBack(input: BroadcastStageInput): boolean {
+  if (!input.realtimeAvailable) return false;
+  if (input.credentialsError) return true;
+  if (!input.credentialsReady) return false;
+  return realtimeIsOver(input.roomState);
+}
+
+/** The one program feed, split into the elements that carry it. */
+export type BroadcastProgramTracks = {
+  /** Attach with `useRemoteTrack`. Absent means no video has arrived yet. */
+  videoProducerId?: string;
+  /** The publisher paused it at source. Their choice, not a failure. */
+  videoPaused: boolean;
+  /** The one program soundtrack. An array because it may legitimately be empty. */
+  audioProducerIds: readonly string[];
+};
+
+/**
+ * What to render out of the producers this viewer may actually receive.
+ *
+ * The live room holds exactly one publisher, `program:<broadcastId>`, with one
+ * video producer and one audio producer, and a viewer token's subscribe rule
+ * names that identity and nothing else. So there is no filtering to do here and
+ * deliberately none attempted: re-deriving the identity in the browser would
+ * give a second answer to a question the node has already answered, and the
+ * wrong answer is a black stage on a broadcast that is playing perfectly.
+ *
+ * The FIRST video is taken rather than the last. A studio that briefly
+ * republishes leaves two announced for a frame or two, and picking the newer
+ * one would swap the element's stream under a viewer mid-sentence.
+ *
+ * Audio is returned as a list rather than as one id because the cost of being
+ * wrong is asymmetric: a spare `<audio>` with no track attached does nothing at
+ * all, and a missed one is a broadcast with no sound.
+ */
+export function programTracks(producers: readonly ProducerEntry[]): BroadcastProgramTracks {
+  const video = producers.find((producer) => producer.kind === "video");
+  const audio = producers.filter((producer) => producer.kind === "audio");
+  return {
+    ...(video ? { videoProducerId: video.producerId } : {}),
+    videoPaused: video?.paused ?? false,
+    // ONE, deliberately, not every audio producer in the room.
+    //
+    // A broadcast has a single soundtrack: the studio's mix, published once by
+    // the program feed. If the room ever holds two (a republish after a
+    // reconnect racing the old producer's teardown), playing both is never the
+    // right answer, so the newer publication wins and the stale one is dropped
+    // rather than mixed in.
+    //
+    // This is a guard, not the fix for the doubled audio that was reported
+    // during the build: THAT was the player mounting the HLS stage while the
+    // viewer ticket was still in flight, so the same broadcast arrived twice,
+    // seconds apart, over two transports. See `chooseBroadcastStage`.
+    audioProducerIds: audio.length > 0 ? [audio[audio.length - 1]!.producerId] : [],
+  };
+}

package/src/ui/styled/broadcast/pollResults.ts

@@ -0,0 +1,66 @@
+/**
+ * Poll tallies as the studio, the stage overlay and the player all render them.
+ *
+ * One function because three surfaces show the same numbers, and three
+ * roundings of the same votes would disagree with each other on screen.
+ */
+
+export type PollLike = {
+  totalVotes: number;
+  options: Array<{ id: string; label: string; voteCount: number }>;
+};
+
+export type PollResult = {
+  id: string;
+  label: string;
+  voteCount: number;
+  /** 0..100, integer. */
+  percent: number;
+};
+
+/**
+ * Percentages that add up to 100.
+ *
+ * Rounding each share on its own is what usually goes wrong: three options on
+ * one vote each show as 33% three times and a viewer reads 99, and 1/3 + 2/3
+ * shows as 33 + 67 only by luck. This uses largest remainder, so the displayed
+ * numbers sum to exactly 100 whenever anybody has voted at all.
+ *
+ * With no votes every option is 0, NOT an even split. A poll that has just
+ * opened showing "50% / 50%" claims two votes that were never cast.
+ */
+export function pollPercentages(poll: PollLike): PollResult[] {
+  const options = poll.options ?? [];
+  const total = options.reduce((sum, option) => sum + option.voteCount, 0);
+  if (total <= 0) {
+    return options.map((option) => ({ ...option, percent: 0 }));
+  }
+
+  const exact = options.map((option) => {
+    const share = (option.voteCount / total) * 100;
+    return { option, floor: Math.floor(share), remainder: share - Math.floor(share) };
+  });
+
+  let left = 100 - exact.reduce((sum, entry) => sum + entry.floor, 0);
+  // Biggest remainder first; a tie goes to the option with more votes, then to
+  // the one listed first, so the same tally always renders the same way.
+  const order = [...exact].sort(
+    (a, b) =>
+      b.remainder - a.remainder ||
+      b.option.voteCount - a.option.voteCount ||
+      options.indexOf(a.option) - options.indexOf(b.option),
+  );
+  const bonus = new Set<string>();
+  for (const entry of order) {
+    if (left <= 0) break;
+    bonus.add(entry.option.id);
+    left--;
+  }
+
+  return exact.map(({ option, floor }) => ({
+    id: option.id,
+    label: option.label,
+    voteCount: option.voteCount,
+    percent: floor + (bonus.has(option.id) ? 1 : 0),
+  }));
+}