@tribe-nest/forge 3.39.0 → 3.41.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.39.0",
+  "version": "3.41.1",
   "publishConfig": {
     "access": "public"
   },

package/src/data/queries/useBroadcasts.ts

@@ -181,6 +181,66 @@ export type BroadcastViewerCredentials = {
  * the SAME call to the same address. A session that is pinged on one stack and
  * not the other reports a different audience count for the same room.
  */
+export type BroadcastPollOption = { id: string; label: string; position: number; voteCount: number };
+
+export type BroadcastPoll = {
+  id: string;
+  question: string;
+  status: "draft" | "live" | "closed";
+  /**
+   * The ASKING of this question in this broadcast, which is what a vote names.
+   *
+   * A poll belongs to a stream template and can be asked again in a later
+   * broadcast; each asking has its own votes and its own one-vote-per-viewer
+   * rule. So the same question next month is a different run, and somebody who
+   * answered last month may answer again.
+   */
+  runId: string;
+  options: BroadcastPollOption[];
+  totalVotes: number;
+};
+
+/**
+ * Reading and answering the poll a broadcast is asking.
+ *
+ * Both endpoints are public and take no bearer token, like the broadcast page
+ * they belong to. The read returns only what is already on everyone's screen,
+ * and the write is identified by a key the viewer's own browser made up.
+ */
+export function useBroadcastPollApi() {
+  const { client } = useForge();
+
+  return {
+    /**
+     * The question being asked right now, or null.
+     *
+     * Fetched once when the player mounts, for the viewer who arrived in the
+     * middle of a poll. Everything after that arrives on the socket, so this is
+     * not polled: a timer would be a second, later-arriving source of truth for
+     * numbers that are already being pushed.
+     */
+    livePoll: async (broadcastId: string): Promise<BroadcastPoll | null> => {
+      const res = await client.get(`/streams/v2/public/polls/live`, { params: { broadcastId } });
+      return res.data?.poll ?? null;
+    },
+    /**
+     * One vote.
+     *
+     * `alreadyVoted` comes back true rather than an error when this viewer has
+     * already answered, which is the ordinary case for somebody with the stream
+     * open in two tabs.
+     */
+    vote: async (payload: {
+      runId: string;
+      optionId: string;
+      voterKey: string;
+    }): Promise<{ poll: BroadcastPoll; alreadyVoted: boolean }> => {
+      const res = await client.post(`/streams/v2/public/polls/vote`, payload);
+      return res.data;
+    },
+  };
+}
+
 export function useBroadcastSessionApi() {
   const { client } = useForge();
 

package/src/i18n/de.json

@@ -175,6 +175,11 @@
   "forge.broadcast_player.sound_on": "Ton einschalten",
   "forge.broadcast_player.started": "Vor {duration} gestartet",
   "forge.broadcast_player.watching_now": "{count} schauen gerade zu",
+  "forge.broadcast_poll.closed": "Umfrage beendet",
+  "forge.broadcast_poll.live": "Umfrage",
+  "forge.broadcast_poll.votes_one": "{count} Stimme",
+  "forge.broadcast_poll.votes_other": "{count} Stimmen",
+  "forge.broadcast_poll.your_vote": "(deine Stimme)",
   "forge.broadcast_ticket_purchase.buy_tickets": "Tickets kaufen",
   "forge.broadcast_ticket_purchase.from_price": "Ab {price}",
   "forge.broadcast_watch.leave": "Übertragung verlassen",

package/src/i18n/en.json

@@ -175,6 +175,11 @@
   "forge.broadcast_player.sound_on": "Turn sound on",
   "forge.broadcast_player.started": "Started {duration} ago",
   "forge.broadcast_player.watching_now": "{count} watching now",
+  "forge.broadcast_poll.closed": "Poll closed",
+  "forge.broadcast_poll.live": "Poll",
+  "forge.broadcast_poll.votes_one": "{count} vote",
+  "forge.broadcast_poll.votes_other": "{count} votes",
+  "forge.broadcast_poll.your_vote": "(your vote)",
   "forge.broadcast_ticket_purchase.buy_tickets": "Buy tickets",
   "forge.broadcast_ticket_purchase.from_price": "From {price}",
   "forge.broadcast_watch.leave": "Leave broadcast",

package/src/ui/headless/broadcast/useBroadcastPoll.ts

@@ -0,0 +1,225 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { useBroadcastPollApi, type BroadcastPoll } from "../../../data/queries/useBroadcasts";
+
+/**
+ * The poll a viewer is being asked, and their answer to it.
+ *
+ * ## Where the numbers come from
+ *
+ * One fetch when the player mounts, for somebody who arrived mid-question, and
+ * the socket for everything after. The player owns the socket (it is the same
+ * connection chat rides on), so it hands the events down here rather than this
+ * opening a second one.
+ *
+ * ## The voter key
+ *
+ * A random id kept in this browser, per site, not per broadcast: the same
+ * person watching two streams is one voter with one key, and the server's
+ * uniqueness is per POLL anyway. It identifies nobody. It exists so that
+ * pressing the button twice counts once, and it is honestly defeatable by
+ * clearing storage, which is the trade the feature was designed around.
+ *
+ * Storage can throw (a private window, a browser set to block site data), and a
+ * viewer who cannot be remembered must still be able to vote. So a failure
+ * falls back to a key held in memory for this page view.
+ */
+
+const VOTER_KEY_STORAGE = "tribenest.broadcast.voter";
+
+function randomKey(): string {
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function readVoterKey(): string {
+  if (typeof localStorage === "undefined") return randomKey();
+  try {
+    const held = localStorage.getItem(VOTER_KEY_STORAGE);
+    if (held && held.length >= 8) return held;
+    const minted = randomKey();
+    localStorage.setItem(VOTER_KEY_STORAGE, minted);
+    return minted;
+  } catch {
+    // Blocked or full. One vote per page view is worse than one per browser and
+    // much better than no vote at all.
+    return randomKey();
+  }
+}
+
+/**
+ * Which ASKINGS this browser has answered, so the UI opens on the results.
+ *
+ * Keyed by run and not by poll, which is the whole difference. A question
+ * belongs to a stream template and gets asked again - later in the same
+ * broadcast, or in next week's - and each asking has its own votes and its own
+ * one-vote rule. Keyed by poll, this remembered "you answered this question"
+ * for ever: a returning viewer met a fresh poll already showing bars and
+ * "(your vote)", with no way to take part. The server would have accepted their
+ * vote; the panel never offered it.
+ */
+const votedKey = (runId: string) => `tribenest.broadcast.voted.run.${runId}`;
+
+function readVoted(runId: string): string | null {
+  if (typeof localStorage === "undefined") return null;
+  try {
+    return localStorage.getItem(votedKey(runId));
+  } catch {
+    return null;
+  }
+}
+
+function forgetVoted(runId: string): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.removeItem(votedKey(runId));
+  } catch {
+    // Nothing to undo if it could not be written in the first place.
+  }
+}
+
+function rememberVoted(runId: string, optionId: string): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(votedKey(runId), optionId);
+  } catch {
+    // Nothing to do. The server still refuses the second vote; the viewer just
+    // sees the form again in a new tab.
+  }
+}
+
+/**
+ * What a viewer's own vote should be after a poll update arrives.
+ *
+ * This exists because of a bug that made the first click look ignored. Voting
+ * publishes results to EVERY viewer, including the one who just voted, and
+ * that push used to re-read the vote from storage. The push routinely beat the
+ * HTTP response it was caused by, storage had not been written yet, and the
+ * panel flipped back to buttons - so the viewer clicked again, and only the
+ * second click appeared to work. Their first vote had counted all along.
+ *
+ * The rule that fixes it: an update to the same ASKING never changes who this
+ * viewer voted for. Only a different asking re-reads storage.
+ *
+ * The identity is the RUN, not the poll. The same question asked again is a new
+ * asking with an empty tally that this viewer has not answered, so comparing
+ * polls would carry their old answer into it and lock them out of voting.
+ */
+export function votedOptionForIncoming(args: {
+  currentRunId: string | null;
+  incomingRunId: string | null;
+  votedOptionId: string | null;
+  /** What storage holds for the incoming asking, if anything. */
+  storedForIncoming: string | null;
+}): string | null {
+  if (!args.incomingRunId) return null;
+  if (args.incomingRunId === args.currentRunId) {
+    // Held in memory beats storage: a vote in flight is not in storage yet, and
+    // a viewer whose browser refuses storage still gets to keep their answer
+    // for as long as the page is open.
+    return args.votedOptionId ?? args.storedForIncoming;
+  }
+  return args.storedForIncoming;
+}
+
+export type BroadcastPollApi = {
+  poll: BroadcastPoll | null;
+  /** The option this browser chose, if it has voted on the current poll. */
+  votedOptionId: string | null;
+  voting: boolean;
+  error: string | null;
+  vote: (optionId: string) => void;
+  /** Feed socket payloads in. Null ends the poll. */
+  onPollEvent: (poll: BroadcastPoll | null) => void;
+};
+
+export function useBroadcastPoll(broadcastId?: string): BroadcastPollApi {
+  const api = useBroadcastPollApi();
+  const [poll, setPoll] = useState<BroadcastPoll | null>(null);
+  const [votedOptionId, setVotedOptionId] = useState<string | null>(null);
+  const [voting, setVoting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const voterKeyRef = useRef<string | null>(null);
+
+  const voterKey = () => {
+    if (!voterKeyRef.current) voterKeyRef.current = readVoterKey();
+    return voterKeyRef.current;
+  };
+
+  useEffect(() => {
+    if (!broadcastId) return;
+    let cancelled = false;
+    api
+      .livePoll(broadcastId)
+      .then((live) => {
+        if (cancelled) return;
+        setPoll(live);
+        setVotedOptionId(live?.runId ? readVoted(live.runId) : null);
+      })
+      .catch(() => {
+        // A poll that cannot be fetched is a poll the viewer does not see. It
+        // is not worth an error on a page whose job is to play a stream.
+        if (!cancelled) setPoll(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+    // The api object is rebuilt per render; the broadcast is what identifies
+    // the fetch.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [broadcastId]);
+
+  const onPollEvent = useCallback((next: BroadcastPoll | null) => {
+    setPoll((current) => {
+      setVotedOptionId((held) =>
+        votedOptionForIncoming({
+          currentRunId: current?.runId ?? null,
+          incomingRunId: next?.runId ?? null,
+          votedOptionId: held,
+          storedForIncoming: next?.runId ? readVoted(next.runId) : null,
+        }),
+      );
+      return next;
+    });
+    setError(null);
+  }, []);
+
+  const vote = useCallback(
+    (optionId: string) => {
+      const current = poll;
+      if (!current || current.status !== "live" || !current.runId || votedOptionId || voting) return;
+
+      setVoting(true);
+      setError(null);
+      // Both recorded before the request goes out, not in its `then`. The
+      // results push this vote causes routinely arrives BEFORE the response to
+      // it, and anything reading storage at that moment has to already find the
+      // vote there.
+      setVotedOptionId(optionId);
+      rememberVoted(current.runId, optionId);
+      api
+        .vote({ runId: current.runId, optionId, voterKey: voterKey() })
+        .then((result) => setPoll(result.poll))
+        .catch((err: unknown) => {
+          setVotedOptionId(null);
+          forgetVoted(current.runId);
+          const message = (err as { response?: { data?: { message?: string } } })?.response?.data?.message;
+          setError(message ?? "That vote did not go through.");
+        })
+        .finally(() => setVoting(false));
+    },
+    // `api` is rebuilt per render and holds no state of its own.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [poll, votedOptionId, voting],
+  );
+
+  return useMemo(
+    () => ({ poll, votedOptionId, voting, error, vote, onPollEvent }),
+    [poll, votedOptionId, voting, error, vote, onPollEvent],
+  );
+}

package/src/ui/index.ts

@@ -183,6 +183,10 @@ export { ReplayList, type ReplayListProps } from "./styled/ReplayList";
 export { LiveBroadcastList, type LiveBroadcastListProps } from "./styled/LiveBroadcastList";
 export { BroadcastWatch, type BroadcastWatchProps } from "./styled/BroadcastWatch";
 export { EndedBroadcast, type EndedBroadcastProps } from "./styled/broadcast/EndedBroadcast";
+// Shared with the admin studio, which renders the same tallies in its Polls
+// tab and burns them into the stage. Three surfaces, one rounding.
+export { pollPercentages, type PollLike, type PollResult } from "./styled/broadcast/pollResults";
+export { BroadcastPollPanel } from "./styled/broadcast/BroadcastPollPanel";
 export { BroadcastPassValidation, type BroadcastPassValidationProps } from "./styled/broadcast/BroadcastPassValidation";
 export { BroadcastTicketPurchase, type BroadcastTicketPurchaseProps } from "./styled/broadcast/BroadcastTicketPurchase";
 export {

package/src/ui/styled/_tests/broadcastPollVote.spec.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+
+import { votedOptionForIncoming } from "../../headless/broadcast/useBroadcastPoll";
+
+/**
+ * The rule that decides whether a viewer keeps their own vote when a poll
+ * update arrives.
+ *
+ * Reported as "I have to click twice before it records my answer". Voting
+ * pushes results to every viewer INCLUDING the one who just voted, that push
+ * routinely beat the HTTP response it was caused by, and the handler re-read
+ * the vote from storage that the response had not written yet. The panel
+ * flipped back to buttons, the viewer clicked again, and their first vote had
+ * been counted the whole time.
+ *
+ * The identity being compared is the ASKING. It was the poll once, and the
+ * second report followed: a question asked again showed a returning viewer
+ * "(your vote)" over last time's answer and refused to let them take part.
+ */
+describe("votedOptionForIncoming", () => {
+  it("keeps a vote that is still in flight when the results it caused arrive first", () => {
+    // The exact double-click bug: same poll, vote held in memory, storage not
+    // written yet. Answering null here is what sent the viewer back to the
+    // buttons.
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: "run-1",
+        votedOptionId: "option-a",
+        storedForIncoming: null,
+      }),
+    ).toBe("option-a");
+  });
+
+  it("keeps the vote through every later result push on the same poll", () => {
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: "run-1",
+        votedOptionId: "option-a",
+        storedForIncoming: "option-a",
+      }),
+    ).toBe("option-a");
+  });
+
+  it("never lets another viewer's vote overwrite this one", () => {
+    // Storage would only disagree after a stale write, but the rule has to be
+    // stated: what is held in memory for the current poll wins.
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: "run-1",
+        votedOptionId: "option-a",
+        storedForIncoming: "option-b",
+      }),
+    ).toBe("option-a");
+  });
+
+  it("recovers a vote from storage on a reload mid-poll", () => {
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: "run-1",
+        votedOptionId: null,
+        storedForIncoming: "option-a",
+      }),
+    ).toBe("option-a");
+  });
+
+  it("starts a NEW asking fresh, so the last answer does not carry over", () => {
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: "run-2",
+        votedOptionId: "option-a",
+        storedForIncoming: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("opens a new asking on its results when this browser already answered THAT asking", () => {
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: "run-2",
+        votedOptionId: null,
+        storedForIncoming: "option-x",
+      }),
+    ).toBe("option-x");
+  });
+
+  it("lets a viewer answer the same question asked again", () => {
+    // The second bug, in one assertion. The question is identical and this
+    // browser answered it last time; the ASKING is new, so the panel must open
+    // on buttons rather than on "(your vote)".
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: "run-2",
+        votedOptionId: "option-a",
+        storedForIncoming: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("clears the vote when the poll ends", () => {
+    expect(
+      votedOptionForIncoming({
+        currentRunId: "run-1",
+        incomingRunId: null,
+        votedOptionId: "option-a",
+        storedForIncoming: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("handles the first poll of the broadcast, with nothing current", () => {
+    expect(
+      votedOptionForIncoming({
+        currentRunId: null,
+        incomingRunId: "run-1",
+        votedOptionId: null,
+        storedForIncoming: null,
+      }),
+    ).toBeNull();
+  });
+});

package/src/ui/styled/_tests/pollResults.spec.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+
+import { pollPercentages, type PollLike } from "../broadcast/pollResults";
+
+const poll = (counts: number[]): PollLike => ({
+  totalVotes: counts.reduce((a, b) => a + b, 0),
+  options: counts.map((voteCount, i) => ({ id: `o${i}`, label: `Option ${i}`, voteCount })),
+});
+
+const percents = (counts: number[]) => pollPercentages(poll(counts)).map((r) => r.percent);
+
+describe("pollPercentages", () => {
+  it("shows nothing rather than an even split before anybody votes", () => {
+    // "50% / 50%" on an untouched poll claims two votes that were never cast.
+    expect(percents([0, 0])).toEqual([0, 0]);
+    expect(percents([0, 0, 0])).toEqual([0, 0, 0]);
+  });
+
+  it("adds up to 100 where naive rounding shows 99", () => {
+    // One vote each on three options: 33.33 floored three times is 99.
+    expect(percents([1, 1, 1]).reduce((a, b) => a + b, 0)).toBe(100);
+    expect(percents([1, 2]).reduce((a, b) => a + b, 0)).toBe(100);
+    expect(percents([1, 1, 1, 1, 1, 1]).reduce((a, b) => a + b, 0)).toBe(100);
+  });
+
+  it("gives the spare point to the biggest remainder", () => {
+    // 1/3 = 33.33 (remainder .33), 2/3 = 66.67 (remainder .67).
+    expect(percents([1, 2])).toEqual([33, 67]);
+  });
+
+  it("is exact when it can be", () => {
+    expect(percents([1, 1])).toEqual([50, 50]);
+    expect(percents([1, 3])).toEqual([25, 75]);
+    expect(percents([7, 3])).toEqual([70, 30]);
+  });
+
+  it("gives a unanimous poll all of it", () => {
+    expect(percents([5, 0, 0])).toEqual([100, 0, 0]);
+  });
+
+  it("breaks a remainder tie the same way every time", () => {
+    // Two options tied on both share and votes: the earlier one wins, so the
+    // overlay does not swap them between renders of an unchanged tally.
+    const first = percents([1, 1, 1]);
+    const second = percents([1, 1, 1]);
+    expect(first).toEqual(second);
+    expect(first.reduce((a, b) => a + b, 0)).toBe(100);
+  });
+
+  it("keeps the labels and the raw counts, which are shown beside the bar", () => {
+    const results = pollPercentages(poll([3, 1]));
+    expect(results.map((r) => r.label)).toEqual(["Option 0", "Option 1"]);
+    expect(results.map((r) => r.voteCount)).toEqual([3, 1]);
+  });
+
+  it("survives a poll with no options at all", () => {
+    expect(pollPercentages({ totalVotes: 0, options: [] })).toEqual([]);
+  });
+
+  it("holds up on a large tally", () => {
+    const counts = [4321, 987, 65, 4];
+    const result = percents(counts);
+    expect(result.reduce((a, b) => a + b, 0)).toBe(100);
+    expect(result[0]).toBeGreaterThan(result[1]);
+  });
+});

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

@@ -29,12 +29,20 @@ import {
 // 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;
 
 /**
@@ -133,6 +141,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   const theme = useForgeTheme();
   const { apiUrl, profileId } = useForge();
   const sessionApi = useBroadcastSessionApi();
+  const poll = useBroadcastPoll(broadcast.id);
 
   const [comments, setComments] = useState<BroadcastComment[]>([]);
   const [comment, setComment] = useState("");
@@ -364,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);
@@ -371,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;
@@ -654,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;

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),
+  }));
+}