@tribe-nest/forge 3.29.0 → 3.31.0

package/src/ui/format/_tests/pwyw.spec.ts

@@ -1,13 +1,6 @@
 import { describe, it, expect } from "vitest";
 import type { ITicket } from "../../../types/models";
-import {
-  clampChosenAmount,
-  isPayWhatYouWant,
-  pwywDefaultAmount,
-  pwywMaximum,
-  resolveUnitPrice,
-  ticketSubtotals,
-} from "../pwyw";
+import { checkoutAmounts, clampChosenAmount, isPayWhatYouWant, pwywDefaultAmount, pwywMaximum, resolveUnitPrice, ticketSubtotals } from "../pwyw";
 
 /**
  * The pay-what-you-want arithmetic shared by BOTH storefront stacks (Forge and
@@ -155,3 +148,67 @@ describe("pwyw helpers", () => {
     });
   });
 });
+
+describe("what actually gets sent as `amounts`", () => {
+  /**
+   * The server takes `amounts` as `z.number().positive()`. A zero answers
+   * `amounts.<id>: Amount must be a positive number` and the checkout fails
+   * outright, so a free pay-what-you-like ticket could not be bought at all.
+   * These assert the PAYLOAD rather than the displayed price, which is why the
+   * existing subtotal tests could not see it.
+   */
+  const pwyw = (over: Partial<ITicket> = {}): ITicket =>
+    ({ id: "t1", price: 0, payWhatYouWant: true, ...over }) as ITicket;
+
+  it("sends NOTHING for a free pay-what-you-like tier the buyer left alone", () => {
+    // The reported failure. Floor 0, no suggestion, so both the default and the
+    // clamp hand back 0.
+    const sent = checkoutAmounts({ tickets: [pwyw()], quantities: { t1: 1 }, chosen: {} });
+
+    expect(sent).toEqual({});
+    expect(Object.values(sent).every((v) => v > 0)).toBe(true);
+  });
+
+  it("sends nothing when the buyer TYPES a zero on a free tier", () => {
+    const sent = checkoutAmounts({ tickets: [pwyw()], quantities: { t1: 1 }, chosen: { t1: 0 } });
+    expect(sent).toEqual({});
+  });
+
+  it("still sends a real amount on a free tier when the buyer chooses to pay", () => {
+    // Omitting must not mean "never send"; a free tier is exactly where a
+    // voluntary payment matters most.
+    const sent = checkoutAmounts({ tickets: [pwyw()], quantities: { t1: 1 }, chosen: { t1: 15 } });
+    expect(sent).toEqual({ t1: 15 });
+  });
+
+  it("sends the floor on a PAID tier, which is positive and therefore legal", () => {
+    const sent = checkoutAmounts({
+      tickets: [pwyw({ price: 10 })],
+      quantities: { t1: 1 },
+      chosen: { t1: 4 },
+    });
+    // Clamped up to the floor rather than dropped: 10 is a positive number and
+    // says something true.
+    expect(sent).toEqual({ t1: 10 });
+  });
+
+  it("ignores a tier with no quantity, and a tier that is not PWYW", () => {
+    const sent = checkoutAmounts({
+      tickets: [pwyw({ id: "none" }), { id: "fixed", price: 20, payWhatYouWant: false } as ITicket],
+      quantities: { none: 0, fixed: 2 },
+      chosen: { none: 50, fixed: 99 },
+    });
+    expect(sent).toEqual({});
+  });
+
+  it("never emits a non-positive value for any mix of tiers", () => {
+    const sent = checkoutAmounts({
+      tickets: [pwyw({ id: "free" }), pwyw({ id: "paid", price: 12 })],
+      quantities: { free: 1, paid: 1 },
+      chosen: {},
+    });
+
+    expect(sent).toEqual({ paid: 12 });
+    expect(Object.values(sent).some((v) => v <= 0)).toBe(false);
+  });
+});

package/src/ui/format/membershipPwyw.ts

@@ -0,0 +1,164 @@
+import type { MembershipTier } from "../../types/models";
+
+/**
+ * Membership pricing arithmetic: which billing cycles a tier actually offers,
+ * what a pay-what-you-want cycle's floor is, and the ONE number that may be
+ * sent to `POST /public/payments/subscriptions`.
+ *
+ * ## Why this is a module and not four lines inside the hook
+ *
+ * Every rule here has a wrong-charge or a dead-end on the other side of it, and
+ * none of them is reachable from a React test without a provider tree:
+ *
+ *  - **A cycle a tier does not sell must not be selectable.** The default cycle
+ *    used to be the literal `"month"`, so a tier priced YEARLY only was read as
+ *    "no monthly price, therefore free" and activated as a free membership. The
+ *    fan got the tier and the artist got nothing.
+ *  - **The floor belongs to the CYCLE, not the tier.** `payWhatYouWantMinimum`
+ *    is the monthly floor and `payWhatYouWantYearlyMinimum` the yearly one.
+ *    Reading the monthly one on a yearly subscription understates the minimum
+ *    by a factor of twelve.
+ *  - **A zero must never be sent.** The server takes the amount as
+ *    `z.number()` and then refuses anything `<= 0` with
+ *    `amount_must_be_positive`, so a pay-what-you-want box left at its initial
+ *    0 is not "pay nothing", it is a subscribe button that always fails.
+ *
+ * ## Units
+ *
+ * Every number in and out of here is MAJOR units (19.99, not 1999) in the
+ * TENANT'S SETTLEMENT currency (`useSiteConfig().currency`), because that is
+ * what the tier rows hold and what the server converts with `toMinorUnits`.
+ * A visitor's chosen display currency converts on the way to the SCREEN and
+ * never on the way to the API: convert what is sent and the fan is charged a
+ * number nobody agreed to.
+ */
+
+export type BillingCycle = "month" | "year";
+
+/** A tier's own numbers, narrowed to what pricing needs. */
+export type PricedTier = Pick<
+  MembershipTier,
+  | "payWhatYouWant"
+  | "payWhatYouWantMinimum"
+  | "payWhatYouWantYearlyMinimum"
+  | "payWhatYouWantMaximum"
+  | "payWhatYouWantYearlyMaximum"
+  | "priceMonthly"
+  | "priceYearly"
+>;
+
+const positive = (value: number | null | undefined): number => {
+  const parsed = typeof value === "number" ? value : Number(value ?? 0);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+
+/**
+ * The lowest amount this cycle may be bought at.
+ *
+ * Pay-what-you-want: the cycle's own minimum. Fixed price: the cycle's price,
+ * which is also the only amount the server accepts (`amount !== cyclePrice`
+ * is rejected outright). 0 means "this cycle is free or not offered", which
+ * `cycleIsOffered` separates.
+ */
+export const cycleFloor = (tier: PricedTier, cycle: BillingCycle): number => {
+  if (tier.payWhatYouWant) {
+    return positive(cycle === "month" ? tier.payWhatYouWantMinimum : tier.payWhatYouWantYearlyMinimum);
+  }
+  return positive(cycle === "month" ? tier.priceMonthly : tier.priceYearly);
+};
+
+/**
+ * The operator's ceiling for a pay-what-you-want cycle, or `null` for none.
+ *
+ * Exposed for display only. It is deliberately NOT applied to the amount that
+ * is sent: neither the client app nor the server enforces a membership PWYW
+ * maximum today, and clamping here would charge less than the total the fan
+ * just read on screen.
+ */
+export const cycleCeiling = (tier: PricedTier, cycle: BillingCycle): number | null => {
+  if (!tier.payWhatYouWant) return null;
+  const raw = cycle === "month" ? tier.payWhatYouWantMaximum : tier.payWhatYouWantYearlyMaximum;
+  const value = positive(raw);
+  return value > 0 ? value : null;
+};
+
+/** Does the tier sell this cycle at all? A cycle with no price is not on offer. */
+export const cycleIsOffered = (tier: PricedTier, cycle: BillingCycle): boolean => cycleFloor(tier, cycle) > 0;
+
+/** Both answers at once, for rendering the billing-cycle radios. */
+export const offeredCycles = (tier: PricedTier): { month: boolean; year: boolean } => ({
+  month: cycleIsOffered(tier, "month"),
+  year: cycleIsOffered(tier, "year"),
+});
+
+/**
+ * The cycle a tier opens on: monthly when it is sold, otherwise yearly.
+ *
+ * A tier that sells NEITHER is a free tier, where the cycle is never sent and
+ * only decides whether the summary reads "per month" or "per year".
+ */
+export const defaultCycle = (tier: PricedTier): BillingCycle =>
+  cycleIsOffered(tier, "month") ? "month" : cycleIsOffered(tier, "year") ? "year" : "month";
+
+/**
+ * Free means free on THIS cycle: no pay-what-you-want floor and no price.
+ * A free tier is activated through `/subscriptions/free`, which takes no
+ * amount, so this is the branch that decides which endpoint is called.
+ */
+export const cycleIsFree = (tier: PricedTier, cycle: BillingCycle): boolean =>
+  !tier.payWhatYouWant && cycleFloor(tier, cycle) === 0;
+
+/** What the amount box starts at: the floor for the cycle. */
+export const defaultChosenAmount = (tier: PricedTier, cycle: BillingCycle): number =>
+  tier.payWhatYouWant ? cycleFloor(tier, cycle) : 0;
+
+/** Lift a fan-entered figure up to the floor. Never lowers it to a ceiling. */
+export const clampMembershipAmount = (tier: PricedTier, cycle: BillingCycle, chosen: number | null | undefined): number => {
+  const floor = cycleFloor(tier, cycle);
+  const parsed = typeof chosen === "number" ? chosen : Number(chosen ?? 0);
+  if (!Number.isFinite(parsed) || parsed < floor) return floor;
+  return parsed;
+};
+
+/**
+ * The number to SEND for a paid subscription, in settlement-currency major
+ * units.
+ *
+ * A fixed tier ignores `chosen` exactly as the server does, so a stale amount
+ * left in state after switching from a pay-what-you-want tier cannot change
+ * what is charged.
+ */
+export const resolveSubscriptionAmount = (
+  tier: PricedTier,
+  cycle: BillingCycle,
+  chosen: number | null | undefined,
+): number => (tier.payWhatYouWant ? clampMembershipAmount(tier, cycle, chosen) : cycleFloor(tier, cycle));
+
+/** Why an amount cannot be sent. `null` when it can. */
+export type MembershipAmountRefusal =
+  | { reason: "below_minimum"; minimum: number }
+  | { reason: "not_positive" };
+
+/**
+ * The check that runs before the request, not after the 400.
+ *
+ * Two refusals, and the second is the one that bites hardest: a
+ * pay-what-you-want box that is still on its initial 0, or one the fan cleared,
+ * resolves to 0 on a tier whose floor is 0, and the server answers
+ * `amount_must_be_positive`. Saying so here turns an unexplained failure into a
+ * field error next to the field.
+ */
+export const refuseMembershipAmount = (
+  tier: PricedTier,
+  cycle: BillingCycle,
+  chosen: number | null | undefined,
+): MembershipAmountRefusal | null => {
+  if (cycleIsFree(tier, cycle)) return null;
+  const floor = cycleFloor(tier, cycle);
+  if (tier.payWhatYouWant) {
+    const parsed = typeof chosen === "number" ? chosen : Number(chosen ?? 0);
+    if (!Number.isFinite(parsed) || parsed < floor) return { reason: "below_minimum", minimum: floor };
+  }
+  if (resolveSubscriptionAmount(tier, cycle, chosen) <= 0) return { reason: "not_positive" };
+  return null;
+};

package/src/ui/format/pwyw.ts

@@ -93,3 +93,40 @@ export function ticketSubtotals(input: {
   }
   return { paid, floor };
 }
+
+/**
+ * The `amounts` map to SEND for a selection, keyed by ticket id.
+ *
+ * Only PWYW tiers with a quantity appear, and only with a POSITIVE amount. That
+ * last rule is not a tidy-up: the server takes `amounts` as
+ * `z.number().positive()`, so a zero answers
+ *
+ *   amounts.<id>: Amount must be a positive number
+ *
+ * and the checkout fails outright. It is reachable on any PWYW tier whose floor
+ * is zero, a free "pay what you like" ticket: with no suggestion
+ * `pwywDefaultAmount` returns the floor, and `clampChosenAmount` returns the
+ * floor for anything below it, so both paths hand back 0 and the buyer cannot
+ * check out at all.
+ *
+ * Omitting the key says what the 0 was trying to say. The server reads a missing
+ * entry as `NaN`, fails `Number.isFinite`, and falls through to the tier's list
+ * price, which for such a tier IS zero.
+ */
+export function checkoutAmounts(input: {
+  tickets: ITicket[];
+  quantities: Record<string, number>;
+  /** What the buyer typed, where they typed anything. */
+  chosen: Record<string, number | null | undefined>;
+}): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const ticket of input.tickets) {
+    if (!isPayWhatYouWant(ticket) || (input.quantities[ticket.id] ?? 0) <= 0) continue;
+    const amount =
+      input.chosen[ticket.id] != null
+        ? resolveUnitPrice(ticket, input.chosen[ticket.id])
+        : pwywDefaultAmount(ticket);
+    if (amount > 0) out[ticket.id] = amount;
+  }
+  return out;
+}

package/src/ui/headless/broadcast/_tests/broadcastState.spec.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect } from "vitest";
+import type { ILiveBroadcast, IBroadcastPass } from "../../../../types/models";
+import {
+  broadcastListStatus,
+  broadcastSessionKey,
+  hasBroadcastEnded,
+  isPassValidated,
+  minTicketPrice,
+  needsPassValidation,
+  selectBroadcastScreen,
+} from "../broadcastState";
+
+/**
+ * The rules a live-broadcast page runs on, checked without a browser.
+ *
+ * The player is deliberately not tested here: it is a video element, a WebRTC
+ * negotiation and a socket, and none of those tell you whether the right person
+ * is looking at them. These functions do.
+ */
+
+const NOW = new Date("2026-08-18T12:00:00.000Z");
+
+function broadcast(overrides: Partial<ILiveBroadcast> = {}): ILiveBroadcast {
+  return {
+    id: "b1",
+    title: "Sunday Session",
+    createdAt: "2026-08-01T00:00:00.000Z",
+    updatedAt: "2026-08-01T00:00:00.000Z",
+    profileId: "p1",
+    streamTemplateId: "st1",
+    egressId: "e1",
+    events: [],
+    event: { id: "ev1", title: "Sunday Session", description: "", isPaid: true },
+    ...overrides,
+  } as ILiveBroadcast;
+}
+
+const gate = (price = 25) =>
+  [
+    {
+      eventId: "ev1",
+      eventTitle: "Sunday Session",
+      eventTickets: [{ price } as unknown as ILiveBroadcast["events"][number]["eventTickets"][number]],
+    },
+  ] as ILiveBroadcast["events"];
+
+const pass: IBroadcastPass = { sessionId: "s1", name: "Ada", email: "ada@example.com" };
+
+describe("broadcastListStatus", () => {
+  it("calls a started, unfinished broadcast LIVE", () => {
+    const status = broadcastListStatus(broadcast({ startedAt: "2026-08-18T11:00:00.000Z" }), NOW);
+    expect(status.text).toBe("LIVE");
+  });
+
+  it("REGRESSION: LIVE wins over a start DATE that has not arrived", () => {
+    // A host who goes on early has `startedAt` set and a `startDate` still in
+    // the future. Reading the schedule first would badge a broadcast that is
+    // ON AIR as UPCOMING, and everyone waits through the show they came for.
+    const status = broadcastListStatus(
+      broadcast({ startedAt: "2026-08-18T11:00:00.000Z", startDate: "2026-08-18T20:00:00.000Z" }),
+      NOW,
+    );
+    expect(status.text).toBe("LIVE");
+  });
+
+  it("calls a future start date UPCOMING", () => {
+    expect(broadcastListStatus(broadcast({ startDate: "2026-08-18T20:00:00.000Z" }), NOW).text).toBe("UPCOMING");
+  });
+
+  it("calls a finished broadcast ENDED even though it started", () => {
+    const status = broadcastListStatus(
+      broadcast({ startedAt: "2026-08-18T10:00:00.000Z", endedAt: "2026-08-18T11:00:00.000Z" }),
+      NOW,
+    );
+    expect(status.text).toBe("ENDED");
+  });
+
+  it("calls a past start date with no start at all ENDED", () => {
+    expect(broadcastListStatus(broadcast({ startDate: "2026-08-17T20:00:00.000Z" }), NOW).text).toBe("ENDED");
+  });
+
+  it("gives the three states three different badge colours", () => {
+    const live = broadcastListStatus(broadcast({ startedAt: "2026-08-18T11:00:00.000Z" }), NOW);
+    const upcoming = broadcastListStatus(broadcast({ startDate: "2026-08-18T20:00:00.000Z" }), NOW);
+    const ended = broadcastListStatus(broadcast(), NOW);
+    expect(new Set([live.background, upcoming.background, ended.background]).size).toBe(3);
+  });
+});
+
+describe("needsPassValidation", () => {
+  it("is the linked event, and nothing else", () => {
+    expect(needsPassValidation(broadcast({ events: gate() }))).toBe(true);
+    expect(needsPassValidation(broadcast({ events: [] }))).toBe(false);
+    expect(needsPassValidation(undefined)).toBe(false);
+    expect(needsPassValidation(null)).toBe(false);
+  });
+});
+
+describe("hasBroadcastEnded", () => {
+  it("ends on the POLLED copy, which is the only thing that notices a host hanging up", () => {
+    const opened = broadcast();
+    const polled = broadcast({ endedAt: "2026-08-18T11:59:00.000Z" });
+    expect(hasBroadcastEnded(opened, polled)).toBe(true);
+  });
+
+  it("ends on the opened copy for a viewer who arrives late", () => {
+    expect(hasBroadcastEnded(broadcast({ endedAt: "2026-08-18T11:00:00.000Z" }), undefined)).toBe(true);
+  });
+
+  it("is not ended while neither copy says so", () => {
+    expect(hasBroadcastEnded(broadcast({ startedAt: "2026-08-18T11:00:00.000Z" }), broadcast())).toBe(false);
+  });
+});
+
+describe("isPassValidated", () => {
+  it("REGRESSION: a gated broadcast without a validated pass is NOT open", () => {
+    // This single expression is the paywall. False here is a paid stream
+    // playing for anybody who has the URL.
+    expect(isPassValidated(broadcast({ events: gate() }), false)).toBe(false);
+  });
+
+  it("opens a gated broadcast once the pass is validated", () => {
+    expect(isPassValidated(broadcast({ events: gate() }), true)).toBe(true);
+  });
+
+  it("lets everyone into a broadcast with no linked event", () => {
+    expect(isPassValidated(broadcast({ events: [] }), false)).toBe(true);
+  });
+});
+
+describe("minTicketPrice", () => {
+  it("takes the cheapest tier on the linked event", () => {
+    const events = [
+      {
+        eventId: "ev1",
+        eventTitle: "Sunday Session",
+        eventTickets: [{ price: 40 }, { price: 15 }, { price: 60 }],
+      },
+    ] as unknown as ILiveBroadcast["events"];
+    expect(minTicketPrice(broadcast({ events }))).toBe(15);
+  });
+
+  it("REGRESSION: says nothing rather than 'From Infinity' when the event lists no tiers", () => {
+    const events = [{ eventId: "ev1", eventTitle: "x", eventTickets: [] }] as unknown as ILiveBroadcast["events"];
+    expect(minTicketPrice(broadcast({ events }))).toBeNull();
+    expect(minTicketPrice(broadcast({ events: [] }))).toBeNull();
+    expect(minTicketPrice(undefined)).toBeNull();
+  });
+});
+
+describe("broadcastSessionKey", () => {
+  it("scopes the stored session to ONE broadcast", () => {
+    // A shared key would carry a ticket for last week's show into this week's.
+    expect(broadcastSessionKey("b1")).toBe("broadcast_b1_session_id");
+    expect(broadcastSessionKey("b1")).not.toBe(broadcastSessionKey("b2"));
+  });
+});
+
+describe("selectBroadcastScreen", () => {
+  const base = {
+    isBroadcastLoading: false,
+    isSessionLoading: false,
+    hasValidPass: false,
+    pass: null,
+  };
+
+  it("decides nothing until a stored session has been re-checked", () => {
+    const screen = selectBroadcastScreen({
+      ...base,
+      isSessionLoading: true,
+      broadcast: broadcast({ events: gate() }),
+    });
+    expect(screen).toEqual({ showLoading: true, view: "none" });
+  });
+
+  it("reports a broadcast that could not be read", () => {
+    expect(selectBroadcastScreen({ ...base, error: new Error("boom") }).view).toBe("error");
+  });
+
+  it("REGRESSION: a GATED broadcast shows the ticket box, never the player", () => {
+    const screen = selectBroadcastScreen({ ...base, broadcast: broadcast({ events: gate() }) });
+    expect(screen.view).toBe("pass");
+  });
+
+  it("plays a gated broadcast once a pass is held", () => {
+    const screen = selectBroadcastScreen({
+      ...base,
+      broadcast: broadcast({ events: gate(), startedAt: "2026-08-18T11:00:00.000Z" }),
+      hasValidPass: true,
+      pass,
+    });
+    expect(screen.view).toBe("player");
+  });
+
+  it("REGRESSION: an ENDED gated broadcast shows the ended screen, not a ticket box", () => {
+    // Asking somebody for a ticket to a stream that finished is both useless
+    // and, for anyone who then buys one, a refund.
+    const screen = selectBroadcastScreen({
+      ...base,
+      broadcast: broadcast({ events: gate() }),
+      polled: broadcast({ endedAt: "2026-08-18T11:59:00.000Z" }),
+    });
+    expect(screen.view).toBe("ended");
+  });
+
+  it("shows the ended screen to a pass holder too", () => {
+    const screen = selectBroadcastScreen({
+      ...base,
+      broadcast: broadcast({ events: gate(), endedAt: "2026-08-18T11:00:00.000Z" }),
+      hasValidPass: true,
+      pass,
+    });
+    expect(screen.view).toBe("ended");
+  });
+
+  it("keeps the spinner alongside the screen while the broadcast is still loading", () => {
+    const screen = selectBroadcastScreen({
+      ...base,
+      isBroadcastLoading: true,
+      broadcast: broadcast({ events: gate() }),
+    });
+    expect(screen).toEqual({ showLoading: true, view: "pass" });
+  });
+
+  it("draws nothing for an OPEN broadcast until a pass exists, matching apps/client", () => {
+    // Pinned, not endorsed. The player needs a pass to sign chat messages with,
+    // so a broadcast with no linked event and no stored session renders blank on
+    // both stacks. Reported alongside this port.
+    const screen = selectBroadcastScreen({
+      ...base,
+      broadcast: broadcast({ events: [], startedAt: "2026-08-18T11:00:00.000Z" }),
+    });
+    expect(screen.view).toBe("none");
+  });
+});

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

@@ -0,0 +1,158 @@
+import type { ILiveBroadcast, IBroadcastPass } from "../../../types/models";
+
+/**
+ * The decisions a live-broadcast page makes, with no React and no network in
+ * them: which badge a broadcast wears in the list, whether the page a viewer
+ * opened is still on, and whether they are allowed past the paywall.
+ *
+ * They are pure so both rendering stacks (apps/client and a Forge code site)
+ * can be checked against the same rules. Every one of these is a rule a wrong
+ * answer turns into either a paid broadcast given away for free, or a viewer
+ * staring at a player for a stream that ended twenty minutes ago.
+ */
+
+/** The three states a broadcast can be in, as the list badge names them. */
+export type BroadcastListStatusText = "LIVE" | "UPCOMING" | "ENDED";
+
+export interface BroadcastListStatus {
+  text: BroadcastListStatusText;
+  /** Badge background. Status colour, deliberately not a theme token: see below. */
+  background: string;
+  /** Badge foreground. */
+  color: string;
+}
+
+/**
+ * Status colours are literal rather than theme tokens on purpose. A LIVE badge
+ * is red on every streaming surface a viewer has ever used, and re-tinting it to
+ * a tenant's brand primary would make "on air" and "ended" the same colour on
+ * any site whose brand happens to be grey. Everything else on these pages
+ * (surfaces, borders, text, radius) reads from the theme.
+ */
+const STATUS_COLORS: Record<BroadcastListStatusText, { background: string; color: string }> = {
+  LIVE: { background: "#ef4444", color: "#ffffff" },
+  UPCOMING: { background: "#3b82f6", color: "#ffffff" },
+  ENDED: { background: "#6b7280", color: "#ffffff" },
+};
+
+/**
+ * Which badge a broadcast wears in the "what is on now" list.
+ *
+ * There is no status column on the row: the lifecycle is derived from the
+ * timestamps. Started and not ended is LIVE, a start date still in the future is
+ * UPCOMING, and everything else has been and gone.
+ */
+export function broadcastListStatus(broadcast: ILiveBroadcast, now: Date = new Date()): BroadcastListStatus {
+  if (broadcast.startedAt && !broadcast.endedAt) {
+    return { text: "LIVE", ...STATUS_COLORS.LIVE };
+  }
+  if (broadcast.startDate && new Date(broadcast.startDate) > now) {
+    return { text: "UPCOMING", ...STATUS_COLORS.UPCOMING };
+  }
+  return { text: "ENDED", ...STATUS_COLORS.ENDED };
+}
+
+/**
+ * Does this broadcast sit behind a ticket?
+ *
+ * A linked event IS the paywall. A broadcast with no linked event is open, and a
+ * broadcast with one is not, so this single expression is what stands between a
+ * paid stream and anyone who knows the URL.
+ */
+export function needsPassValidation(broadcast?: ILiveBroadcast | null): boolean {
+  return !!broadcast?.events?.length;
+}
+
+/**
+ * Has it ended?
+ *
+ * Two sources, because the page holds the broadcast it OPENED with and polls a
+ * second copy. The poll is the only thing that notices the host hanging up while
+ * somebody is watching, so an end seen in either copy ends the page.
+ */
+export function hasBroadcastEnded(broadcast?: ILiveBroadcast | null, polled?: ILiveBroadcast | null): boolean {
+  return !!polled?.endedAt || !!broadcast?.endedAt;
+}
+
+/**
+ * May this viewer through?
+ *
+ * An open broadcast passes everyone. A gated one passes only a viewer holding a
+ * validated pass. Note the direction of the default: when there is no gate the
+ * answer is yes, so a bug that loses the events array opens the paywall rather
+ * than closing it. That is why `needsPassValidation` reads the broadcast and
+ * never a flag the caller passes in.
+ */
+export function isPassValidated(broadcast: ILiveBroadcast | null | undefined, hasValidPass: boolean): boolean {
+  return needsPassValidation(broadcast) ? hasValidPass : true;
+}
+
+/** Where a validated session id is parked so a refresh does not re-ask for the ticket. */
+export function broadcastSessionKey(broadcastId: string): string {
+  return `broadcast_${broadcastId}_session_id`;
+}
+
+/**
+ * The cheapest ticket on the linked event, for the "from ..." line beside the
+ * buy button. `null` when the event lists no tickets at all, so the caller
+ * renders nothing rather than the word "Infinity".
+ */
+export function minTicketPrice(broadcast?: ILiveBroadcast | null): number | null {
+  const tickets = broadcast?.events?.[0]?.eventTickets;
+  if (!tickets || tickets.length === 0) return null;
+  const min = tickets.reduce((lowest, ticket) => Math.min(lowest, ticket.price), Infinity);
+  return Number.isFinite(min) ? min : null;
+}
+
+/** What the watch page puts on screen. */
+export type BroadcastView = "none" | "error" | "ended" | "player" | "pass";
+
+export interface BroadcastScreen {
+  /** The spinner. It can sit ALONGSIDE a view, exactly as the client renders it. */
+  showLoading: boolean;
+  view: BroadcastView;
+}
+
+export interface BroadcastScreenInput {
+  /** The broadcast the page opened with. */
+  broadcast?: ILiveBroadcast | null;
+  /** The polled copy, which is allowed to say only one thing: that it ended. */
+  polled?: ILiveBroadcast | null;
+  isBroadcastLoading: boolean;
+  /** Re-opening a stored session. Nothing renders until this settles. */
+  isSessionLoading: boolean;
+  error?: unknown;
+  hasValidPass: boolean;
+  pass?: IBroadcastPass | null;
+}
+
+/**
+ * The whole render decision for the watch page, in one place.
+ *
+ * Order matters and is not arbitrary. ENDED is checked before the pass, so a
+ * viewer who arrives after the stream is over gets the "it ended" screen instead
+ * of being asked for a ticket to nothing. The pass gate is checked before the
+ * player, so no frame of a gated broadcast is ever mounted for a viewer who has
+ * not presented one.
+ */
+export function selectBroadcastScreen(input: BroadcastScreenInput): BroadcastScreen {
+  const { broadcast, polled, isBroadcastLoading, isSessionLoading, error, hasValidPass, pass } = input;
+  const showLoading = isBroadcastLoading || isSessionLoading;
+
+  // Nothing at all is decided until the stored session has been re-checked:
+  // deciding early would flash the ticket box at a viewer who already has one.
+  if (isSessionLoading) return { showLoading: true, view: "none" };
+
+  if (error) return { showLoading, view: "error" };
+  if (!broadcast) return { showLoading, view: "none" };
+
+  if (hasBroadcastEnded(broadcast, polled)) return { showLoading, view: "ended" };
+
+  if (!isPassValidated(broadcast, hasValidPass)) return { showLoading, view: "pass" };
+
+  // A pass is what names the viewer in chat, so the player waits for one even on
+  // an open broadcast. Matches apps/client exactly.
+  if (pass) return { showLoading, view: "player" };
+
+  return { showLoading, view: "none" };
+}