@tribe-nest/forge 3.34.0 → 3.35.0

package/src/ui/headless/film/useFilmRentalFlow.ts

@@ -0,0 +1,277 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import {
+  cheapestFilmRentalOption,
+  filmRentalOptions,
+  useCreateFilmRental,
+  useFilmRentalFinalize,
+  type PublicFilmDetail,
+  type PublicFilmRental,
+  type PublicFilmRentalOption,
+} from "../../../data/queries/useFilms";
+import { filmErrorMessage, filmErrorStatus } from "../../../data/queries/useFilmPlaybackSession";
+import { filmSignInHref } from "./useFilmPlayback";
+
+/**
+ * Headless rent-a-title flow: pick a window, create the pending rental, charge
+ * for it, and reconcile it when the provider sends the fan back.
+ *
+ * A rental is always the WHOLE title. What IS chosen is the window: a title can
+ * be sold at 8 hours for less and 48 hours for more, so the flow carries a
+ * selection, defaulted to the cheapest option and settable with
+ * `selectOption(id)`.
+ *
+ * Mirrors the events pillar (create -> start-payment -> finalize) with no hold
+ * machinery, because a rental is a licence to stream and nothing is scarce.
+ *
+ * Three things this hook refuses to do, all on purpose:
+ *
+ *  - It never sends a price or a duration. It sends the OPTION ID, and the
+ *    server resolves both numbers from that row; the body is strict, so a
+ *    client that sends a figure gets a 400 rather than a quietly ignored field.
+ *    That is the fix for the client-set-price defect the 2026-06-10 audit found.
+ *    `options` carries the same numbers purely so the button can state what is
+ *    being bought before the fan pays.
+ *  - It never renders a window the fan has not been shown. The selection is
+ *    always one of `options`, and `selectedOption` is what the CTA must label
+ *    itself from: a fan who buys a ten-episode series on a 48-hour clock and
+ *    discovers it at expiry has been mis-sold.
+ *  - It never treats a rental as bought until `finalize` says so. The return leg
+ *    and the provider webhook race, and finalize is the one idempotent place
+ *    that flips the row exactly once whichever wins.
+ */
+
+export type FilmRentalStep =
+  /** Nothing started. */
+  | "browse"
+  /** A pending rental exists and Stripe needs card details in place. */
+  | "payment"
+  /** Paid and reconciled. */
+  | "rented";
+
+export interface UseFilmRentalFlowOptions {
+  /** The title being rented. The flow is inert until this arrives. */
+  film?: PublicFilmDetail | null;
+  /** Where the provider sends the fan back. Default `/i/films/:slug?rental=:rentalId`. */
+  returnPath?: (slug: string, rentalId: string) => string;
+  /**
+   * A rental id read off the return URL. When present the flow finalizes it on
+   * mount, which is what turns a provider redirect back into "you own this".
+   */
+  finalizeRentalId?: string;
+  /** Sign-in path (default `/login`; the site-starter passes `/i/login`). */
+  loginPath?: string;
+  /** Called once a rental is confirmed active, free or paid. */
+  onRented?: (rental: PublicFilmRental) => void;
+}
+
+const defaultReturnPath = (slug: string, rentalId: string) => `/i/films/${slug}?rental=${rentalId}`;
+
+export function useFilmRentalFlow(opts: UseFilmRentalFlowOptions) {
+  const { film, finalizeRentalId } = opts;
+  const { isAuthenticated, isInitialized } = usePublicAuth();
+  const filmId = film?.id;
+
+  const [step, setStep] = useState<FilmRentalStep>("browse");
+  const [rental, setRental] = useState<PublicFilmRental | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  /**
+   * Set the moment a rental is created and cleared by the effect that starts the
+   * charge. It exists because `usePaymentFlow` captures its `path` at render
+   * time, and the rental id is IN that path - calling `start()` in the same tick
+   * as `setRental` would post to the previous render's URL.
+   */
+  const [awaitingCharge, setAwaitingCharge] = useState(false);
+  /**
+   * The window the fan has picked, or null while they have not picked one.
+   *
+   * Null is not "none": it resolves to the CHEAPEST option below. A title with a
+   * single window therefore needs no picker at all and `rent()` still knows what
+   * it is buying, and a title with several defaults to the cheap one rather than
+   * to whichever the creator happened to create first.
+   */
+  const [selectedOptionId, setSelectedOptionId] = useState<string | null>(null);
+  const onRentedRef = useRef(opts.onRented);
+  onRentedRef.current = opts.onRented;
+
+  const createRental = useCreateFilmRental(filmId);
+
+  const returnPath = opts.returnPath ?? defaultReturnPath;
+  const returnUrl = useMemo(() => {
+    if (!film || !rental) return undefined;
+    const origin = typeof window === "undefined" ? "" : window.location.origin;
+    return `${origin}${returnPath(film.slug, rental.id)}`;
+  }, [film, rental, returnPath]);
+
+  const flow = usePaymentFlow({
+    path: filmId && rental ? `/public/films/${filmId}/rentals/${rental.id}/start-payment` : undefined,
+    autoStart: false,
+    returnUrl,
+  });
+
+  // Start the charge one render after the rental lands, so the path above is the
+  // new rental's. See the note on `awaitingCharge`.
+  useEffect(() => {
+    if (!awaitingCharge || !rental || !returnUrl) return;
+    if (rental.status !== "pending_payment") return;
+    setAwaitingCharge(false);
+    flow
+      .start({ returnUrl })
+      .then((result) => {
+        // Paystack drives its own modal and navigates to `returnUrl` itself.
+        // Only Stripe needs a card form drawn on this page.
+        if (!result.provider || result.provider === "stripe") setStep("payment");
+      })
+      .catch((e) => setError(filmErrorMessage(e) ?? "This rental could not be started."));
+    // `flow` is rebuilt each render; depending on it would re-fire the charge.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [awaitingCharge, rental, returnUrl]);
+
+  // ── The return leg ─────────────────────────────────────────────────────────
+  const finalize = useFilmRentalFinalize(filmId, finalizeRentalId);
+  useEffect(() => {
+    if (!finalize.data) return;
+    setRental(finalize.data);
+    if (finalize.data.status === "active") {
+      setStep("rented");
+      onRentedRef.current?.(finalize.data);
+    }
+  }, [finalize.data]);
+
+  /**
+   * The windows on sale, in the order the creator arranged them. Empty means the
+   * title is not on sale, which keeps the button off the page rather than
+   * putting a 400 behind it.
+   */
+  const options = useMemo<PublicFilmRentalOption[]>(() => filmRentalOptions(film), [film]);
+
+  /**
+   * The window that would be bought right now.
+   *
+   * Resolved rather than stored, so a selection that no longer exists (the
+   * creator archived that window while the page was open) falls back to the
+   * cheapest live one instead of sending an id the checkout would 404.
+   *
+   * ⚠️ The fallback is the CHEAPEST window, computed as such, not `options[0]`.
+   * That list is now ordered by the creator's hand, so its first row is whatever
+   * they chose to show first, and defaulting to it would pre-select a window
+   * that costs more than another on the same title.
+   */
+  const selectedOption = useMemo<PublicFilmRentalOption | null>(
+    () => options.find((option) => option.id === selectedOptionId) ?? cheapestFilmRentalOption(film) ?? null,
+    [options, selectedOptionId, film],
+  );
+
+  /**
+   * Buy it, in one window.
+   *
+   * Takes the option id explicitly so a surface can rent straight off a row
+   * without a round trip through the selection; falls back to `selectedOption`,
+   * which is what a single-window title and a picker-driven CTA both use.
+   *
+   * A price of 0 comes back already active with the receipt sent, so the free
+   * path never touches a payment provider. Everything else lands on
+   * `pending_payment` and the effect above charges it.
+   */
+  const rent = useCallback(
+    async (rentalOptionId?: string) => {
+      setError(null);
+      if (!filmId) return;
+      // Nothing on sale, or an id for a window this title does not have. Either
+      // way there is no honest charge to mint, and the server would 404.
+      const optionId = rentalOptionId ?? selectedOption?.id;
+      if (!optionId) return;
+      if (!isAuthenticated) {
+        // Renting is account-bound from day one, so there is no guest path to
+        // fall back to. Send them to sign in and bring them back HERE.
+        if (typeof window !== "undefined") {
+          const here = `${window.location.pathname}${window.location.search}`;
+          window.location.assign(filmSignInHref(opts.loginPath ?? "/login", here));
+        }
+        return;
+      }
+      try {
+        const created = await createRental.mutateAsync({ rentalOptionId: optionId });
+        setRental(created);
+        if (created.status === "active") {
+          setStep("rented");
+          onRentedRef.current?.(created);
+          return;
+        }
+        setAwaitingCharge(true);
+      } catch (e) {
+        const status = filmErrorStatus(e);
+        setError(
+          filmErrorMessage(e) ??
+            (status === 404 ? "This title is no longer available." : "This rental could not be created."),
+        );
+      }
+    },
+    // `createRental` is a stable react-query mutation object.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [filmId, isAuthenticated, opts.loginPath, selectedOption?.id],
+  );
+
+  /**
+   * Deliberately NOT memoized: it closes over `flow`, which is rebuilt every
+   * render, and a `useCallback([])` here would go on resetting the very first
+   * render's charge for ever.
+   */
+  const reset = () => {
+    setStep("browse");
+    setRental(null);
+    setError(null);
+    setAwaitingCharge(false);
+    flow.reset();
+  };
+
+  return {
+    step,
+    setStep,
+    /** The rental in flight, or the one just finalized. */
+    rental,
+    /**
+     * The rental to reason about: whatever just settled in this session, falling
+     * back to whatever the title payload arrived with.
+     *
+     * One row is the whole answer. It drives the countdown AND every per-episode
+     * affordance, because a rental on this title covers every episode of it.
+     */
+    viewerRental: rental?.status === "active" ? rental : (film?.viewerRental ?? null),
+    /** Every window on sale, cheapest first. Empty means nothing is on sale. */
+    options,
+    /** The window `rent()` would buy. Never an id the title does not carry. */
+    selectedOption,
+    /**
+     * Pick a window.
+     *
+     * Only worth drawing when there is more than one: a picker offering a choice
+     * of one is a control that cannot be used, and it makes a simple title read
+     * as a complicated one.
+     */
+    selectOption: (rentalOptionId: string) => setSelectedOptionId(rentalOptionId),
+    rent,
+    reset,
+    error,
+    isAuthenticated,
+    isInitialized,
+    isCreating: createRental.isPending,
+    isStartingPayment: flow.isStarting,
+    isFinalizing: finalize.isLoading,
+    /** STRIPE: the PaymentIntent client secret for the in-page card form. */
+    clientSecret: flow.clientSecret,
+    /** PAYSTACK: the started inline session and the way back into it after a dismissal. */
+    isPaystack: flow.isPaystack,
+    canOpenPaystack: flow.canOpenPaystack,
+    openPaystackCheckout: flow.openPaystackCheckout,
+    returnUrl,
+    /** The charged amount in MAJOR units, from the provider quote. */
+    chargeAmount: flow.result?.amount,
+    chargeCurrency: flow.result?.currency,
+    /** Authoritative sales-tax quote from start-payment, in MAJOR units. Display only. */
+    taxQuote: flow.result?.taxQuote ?? null,
+  };
+}
+
+export type FilmRentalFlowState = ReturnType<typeof useFilmRentalFlow>;

package/src/ui/headless/film/useStageFullscreen.ts

@@ -0,0 +1,156 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Fullscreen the STAGE, never the `<video>`.
+ *
+ * ## The bug this exists to close
+ *
+ * The browser puts exactly ONE element into the fullscreen layer, and the native
+ * control bar on a `<video>` fullscreens the video element itself. Everything
+ * else in the document, including a watermark drawn as a sibling over the
+ * stage, simply stops rendering. Since fullscreen is how people actually watch a
+ * film, that meant the renter-identifying overlay was absent for most of the
+ * viewing time, and a recording made in fullscreen carried no identity at all.
+ *
+ * Fullscreening the stage instead keeps the watermark in the layer, because it
+ * is a DESCENDANT of the element being promoted rather than a sibling of it.
+ *
+ * ## Why both a button and a correction
+ *
+ * `controlsList="nofullscreen"` hides the native button on Chromium (desktop and
+ * Android), so there the stage button is the only route and nothing has to be
+ * corrected. Firefox and Safari ignore `controlsList`, so their native button is
+ * still live and still targets the video. The `fullscreenchange` listener is the
+ * net under that: when the element that went fullscreen is a descendant of the
+ * stage rather than the stage itself, it swaps them.
+ *
+ * The swap is deliberately not attempted more than once per transition
+ * (`correctingRef`). A browser that refuses the re-request would otherwise have
+ * its refusal read as another stray transition, and the two would ping-pong.
+ *
+ * ## iPhone is out of reach, on purpose
+ *
+ * iOS Safari hands `<video>` fullscreen to a native OS-level player that no DOM
+ * overlay can enter, and it exposes `webkitEnterFullscreen` rather than the
+ * Fullscreen API on the element. There is no correction available: the watermark
+ * is simply absent there. `playsInline` (set by the player) is what stops iOS
+ * forcing that view on every play. The burned-in transcoder watermark still ties
+ * a leak to the film, just not to the renter, and that limit is documented
+ * rather than papered over.
+ */
+export type StageFullscreen = {
+  /** Attach to the element that should fill the screen (the one wrapping player + watermark). */
+  ref: React.RefObject<HTMLDivElement | null>;
+  isFullscreen: boolean;
+  /** True when the browser exposes the Fullscreen API at all. */
+  isSupported: boolean;
+  toggle: () => void;
+};
+
+type FullscreenCapableElement = HTMLDivElement & {
+  webkitRequestFullscreen?: () => Promise<void> | void;
+};
+
+type FullscreenCapableDocument = Document & {
+  webkitFullscreenElement?: Element | null;
+  webkitExitFullscreen?: () => Promise<void> | void;
+  webkitFullscreenEnabled?: boolean;
+};
+
+/**
+ * Asked of the DOCUMENT, never of the stage element.
+ *
+ * ⚠️ This is the shape of a bug that shipped: support was probed from
+ * `ref.current` in a mount effect, but `<FilmWatch>` returns a loading panel on
+ * its first render, so the stage did not exist yet. The probe saw `null`, latched
+ * "unsupported", and never re-ran - which hid Forge's own fullscreen button while
+ * the player had ALREADY removed the native one via `controlsList`, leaving
+ * desktop viewers with no way into fullscreen at all.
+ *
+ * `document.fullscreenEnabled` needs no element, is stable from first render, and
+ * answers the question that actually matters: is fullscreen permitted here. It is
+ * correctly false inside an iframe without `allowfullscreen`, which is a case the
+ * element probe got wrong in the other direction.
+ */
+function fullscreenPermitted(): boolean {
+  if (typeof document === "undefined") return false;
+  const doc = document as FullscreenCapableDocument;
+  return Boolean(doc.fullscreenEnabled ?? doc.webkitFullscreenEnabled ?? false);
+}
+
+function currentFullscreenElement(): Element | null {
+  if (typeof document === "undefined") return null;
+  const doc = document as FullscreenCapableDocument;
+  return doc.fullscreenElement ?? doc.webkitFullscreenElement ?? null;
+}
+
+async function exitFullscreen(): Promise<void> {
+  const doc = document as FullscreenCapableDocument;
+  if (doc.exitFullscreen) return void (await doc.exitFullscreen());
+  if (doc.webkitExitFullscreen) return void (await doc.webkitExitFullscreen());
+}
+
+async function requestFullscreen(element: FullscreenCapableElement): Promise<void> {
+  if (element.requestFullscreen) return void (await element.requestFullscreen());
+  if (element.webkitRequestFullscreen) return void (await element.webkitRequestFullscreen());
+}
+
+export function useStageFullscreen(): StageFullscreen {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  // Initialised from the document so the very first render is already correct:
+  // the button must be able to appear the moment the stage does.
+  const [isSupported, setIsSupported] = useState(fullscreenPermitted);
+  const correctingRef = useRef(false);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    setIsSupported(fullscreenPermitted());
+
+    const onChange = () => {
+      const active = currentFullscreenElement();
+      const stage = ref.current;
+      setIsFullscreen(Boolean(active) && active === stage);
+
+      if (!stage || !active || active === stage) {
+        correctingRef.current = false;
+        return;
+      }
+      // Something inside the stage went fullscreen on its own: the native
+      // control bar on the <video>. Swap it for the stage so the watermark
+      // travels with it.
+      if (!stage.contains(active) || correctingRef.current) return;
+
+      correctingRef.current = true;
+      void exitFullscreen()
+        .then(() => requestFullscreen(stage as FullscreenCapableElement))
+        .catch(() => {
+          // A browser may refuse the re-request without a fresh user gesture.
+          // Losing fullscreen is better than looping, and the fan can press the
+          // stage button, which always carries its own gesture.
+        })
+        .finally(() => {
+          correctingRef.current = false;
+        });
+    };
+
+    document.addEventListener("fullscreenchange", onChange);
+    document.addEventListener("webkitfullscreenchange", onChange);
+    return () => {
+      document.removeEventListener("fullscreenchange", onChange);
+      document.removeEventListener("webkitfullscreenchange", onChange);
+    };
+  }, []);
+
+  const toggle = useCallback(() => {
+    const stage = ref.current as FullscreenCapableElement | null;
+    if (!stage) return;
+    if (currentFullscreenElement()) {
+      void exitFullscreen().catch(() => undefined);
+      return;
+    }
+    void requestFullscreen(stage).catch(() => undefined);
+  }, []);
+
+  return { ref, isFullscreen, isSupported, toggle };
+}

package/src/ui/headless/index.ts

@@ -5,10 +5,7 @@ export * from "./donation";
 export * from "./offer";
 export { MembershipGate, type MembershipGateProps, type MembershipGateState } from "./membership/MembershipGate";
 // S.4 members-only gates: the notice a storefront draws BEFORE the buyer pays.
-export {
-  useMembershipGateNotice,
-  type UseMembershipGateNoticeInput,
-} from "./membership/useMembershipGateNotice";
+export { useMembershipGateNotice, type UseMembershipGateNoticeInput } from "./membership/useMembershipGateNotice";
 export { useEmailListForm, type UseEmailListFormOptions, type FormStatus } from "./forms/useEmailListForm";
 export { useContactForm } from "./forms/useContactForm";
 export { useSectionedForm } from "./forms/useSectionedForm";
@@ -24,11 +21,7 @@ export {
 } from "./checkout/useCheckout";
 // Inventory holds — the reservation a buyer is given while they pay, and the
 // 409 they get when it lapses. Shared by both rendering stacks.
-export {
-  useInventoryHold,
-  type InventoryHoldState,
-  type UseInventoryHoldOptions,
-} from "./checkout/useInventoryHold";
+export { useInventoryHold, type InventoryHoldState, type UseInventoryHoldOptions } from "./checkout/useInventoryHold";
 // Cart recovery: what a resume link does when the buyer clicks it. Shared so
 // `apps/client` and a Forge code site cannot decide differently.
 export {
@@ -139,6 +132,10 @@ export * from "./memberHome";
 export * from "./reviews";
 // Document signing (contracts / e-signature) headless primitives.
 export * from "./document";
+// Films and series headless primitives, including `<FilmWatermark>`. This is
+// the sanctioned way to build a custom player - read `useFilmPlayback`'s
+// docblock first, which says which protection layer you give up by doing so.
+export * from "./film";
 // Work (project management) client-portal headless primitives.
 export * from "./work";
 // Funnel instrumentation — wrap a multi-step flow to record step-through and

package/src/ui/index.ts

@@ -35,13 +35,7 @@ export {
   type ResolvedThemeTokens,
 } from "./theme/ForgeThemeProvider";
 export { readableTextOn } from "./theme/contrast";
-export {
-  Button,
-  buttonStyle,
-  type ButtonProps,
-  type ButtonVariant,
-  type ButtonSize,
-} from "./styled/Button";
+export { Button, buttonStyle, type ButtonProps, type ButtonVariant, type ButtonSize } from "./styled/Button";
 export {
   ForgePaymentProvider,
   usePaymentRenderer,
@@ -126,7 +120,12 @@ export { LoginForm, type LoginFormProps } from "./styled/LoginForm";
 export { SignupForm, type SignupFormProps } from "./styled/SignupForm";
 export { ForgotPasswordForm, type ForgotPasswordFormProps } from "./styled/ForgotPasswordForm";
 export { ResetPasswordForm, type ResetPasswordFormProps } from "./styled/ResetPasswordForm";
-export { AccountDashboard, type AccountDashboardProps, type AccountTabKey, ACCOUNT_TABS } from "./styled/AccountDashboard";
+export {
+  AccountDashboard,
+  type AccountDashboardProps,
+  type AccountTabKey,
+  ACCOUNT_TABS,
+} from "./styled/AccountDashboard";
 export {
   TicketTransferPanel,
   type TicketTransferPanelProps,
@@ -183,14 +182,8 @@ 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";
-export {
-  BroadcastPassValidation,
-  type BroadcastPassValidationProps,
-} from "./styled/broadcast/BroadcastPassValidation";
-export {
-  BroadcastTicketPurchase,
-  type BroadcastTicketPurchaseProps,
-} from "./styled/broadcast/BroadcastTicketPurchase";
+export { BroadcastPassValidation, type BroadcastPassValidationProps } from "./styled/broadcast/BroadcastPassValidation";
+export { BroadcastTicketPurchase, type BroadcastTicketPurchaseProps } from "./styled/broadcast/BroadcastTicketPurchase";
 export {
   BroadcastPlayer,
   type BroadcastPlayerProps,
@@ -200,6 +193,15 @@ export { ConfirmSubscription, type ConfirmSubscriptionProps } from "./styled/Con
 export { LeadMagnet, type LeadMagnetProps } from "./styled/LeadMagnet";
 export { CohortPage, type CohortPageProps } from "./styled/CohortPage";
 export { CourseAccess, type CourseAccessProps } from "./styled/CourseAccess";
+
+// Films and series (Tier 2). `FilmWatch` owns the entitlement gate, the viewer
+// overlay, the episode switcher and the clock; it takes a `renderPlayer` prop
+// because Forge ships no HLS engine. See its docblock before restyling it: the
+// five gate states each strand somebody if drawn as one of the others.
+export { FilmCatalog, rentalWindowLabel, type FilmCatalogProps } from "./styled/FilmCatalog";
+export { FilmDetail, type FilmDetailProps } from "./styled/FilmDetail";
+export { FilmLibrary, type FilmLibraryProps } from "./styled/FilmLibrary";
+export { FilmWatch, type FilmWatchProps, type FilmPlayerRenderProps } from "./styled/FilmWatch";
 export { DonationPage, type DonationPageProps } from "./styled/DonationPage";
 export { ReviewsSection, StarRow, type ReviewsSectionProps } from "./styled/ReviewsSection";
 export { ReviewForm, type ReviewFormProps } from "./styled/ReviewForm";

package/src/ui/media/CallStage.tsx

@@ -144,6 +144,24 @@ export function CallStage({ onLeave, title, aspectRatio = 16 / 9 }: CallStagePro
         backgroundColor: tokens.background,
         color: tokens.text,
         fontFamily: tokens.fontFamily,
+        /**
+         * Fill the surface rather than growing to fit the tiles.
+         *
+         * This laid out as a content-sized panel, which was right when a call
+         * was a modal and wrong the moment it became a full-screen page. With
+         * ONE participant `auto-fit` collapses the grid to a single full-width
+         * column, and a 16/9 tile at full width is taller than the viewport, so
+         * the controls were pushed off the bottom of the screen. Two people
+         * halved the width and hid the bug, which is why it only appeared to
+         * somebody sitting in a call alone.
+         *
+         * `100%` degrades to `auto` inside a parent with no height, so the
+         * embedded use (`BookingCallScreen`) is unaffected.
+         */
+        height: "100%",
+        minHeight: 0,
+        boxSizing: "border-box",
+        overflow: "hidden",
       }}
     >
       <div
@@ -174,6 +192,29 @@ export function CallStage({ onLeave, title, aspectRatio = 16 / 9 }: CallStagePro
           display: "grid",
           gridTemplateColumns: "repeat(auto-fit, minmax(12rem, 1fr))",
           gap: "0.75rem",
+          // The only part that may grow, and the only part that may scroll.
+          // `minHeight: 0` is what actually lets it shrink: a flex item defaults
+          // to `min-height: auto`, so without it the grid refuses to go below
+          // its content and pushes the controls out of the box instead.
+          flex: 1,
+          minHeight: 0,
+          overflowY: "auto",
+          /**
+           * Centred in the free space, not stacked at the top.
+           *
+           * `safe` is the load-bearing word: plain `center` centres the
+           * OVERFLOW too, so once there are more tiles than fit, the first row
+           * is pushed above the scroll origin and cannot be reached. `safe
+           * center` centres while there is room and falls back to start the
+           * moment there is not. An engine that does not understand it drops
+           * the declaration and starts at the top, which is the same fallback.
+           */
+          alignContent: "safe center",
+          // Horizontally centred too. A tile clamped by `maxHeight` shrinks its
+          // width to keep 16/9, so it no longer fills its track and would
+          // otherwise sit against the left edge. With two or more tiles each
+          // fills its track and this changes nothing.
+          justifyItems: "center",
         }}
       >
         <LocalPreview tokens={tokens} aspectRatio={aspectRatio} t={t} />
@@ -291,6 +332,10 @@ const tileFrame = (tokens: ResolvedThemeTokens, aspectRatio: number, speaking: b
   position: "relative",
   overflow: "hidden",
   aspectRatio: String(aspectRatio),
+  // A lone tile spans the whole grid, and 16/9 of a wide surface is taller than
+  // the surface. Clamping crops rather than distorts, because the video inside
+  // is `object-fit: cover`.
+  maxHeight: "100%",
   borderRadius: tokens.cornerRadius,
   backgroundColor: tokens.surface,
   // The active speaker is shown by the FRAME rather than by re-ordering the
@@ -533,7 +578,20 @@ function CallControls({
   }, [room, onLeave]);
 
   return (
-    <div style={{ display: "flex", flexWrap: "wrap", alignItems: "center", gap: "0.5rem" }}>
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        gap: "0.5rem",
+        // Pinned to the bottom of the surface. The tile grid already claims the
+        // free space with `flex: 1`, so this holds even if that ever changes:
+        // the controls are the one thing that must never move off screen,
+        // because Leave is here.
+        marginTop: "auto",
+        flexShrink: 0,
+      }}
+    >
       {canPublishSource(grants, "microphone") && (
         <button
           type="button"