@tribe-nest/forge 3.35.0 → 3.36.0

package/package.json

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

package/src/data/queries/_tests/paymentFlowReturnUrl.spec.tsx

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+
+/**
+ * The way back from a Paystack payment.
+ *
+ * Four checkouts (event tickets, courses, coaching, offers) build their finalise
+ * URL from an id that does not exist until the resource is created, so they hand
+ * it to `start({ …, returnUrl })` and never as a hook option. The Paystack
+ * session was assembled from the OPTION alone, so for all four it carried no
+ * return URL: the buyer paid, the popup closed, and the helper had nowhere to
+ * send them. They were left sitting on the checkout they had just paid on, with
+ * no receipt, no confirmation and no error — while the charge itself succeeded
+ * every time.
+ *
+ * Stripe never had this: it hands its own `return_url` to `confirmPayment`.
+ *
+ * The real helper is in the path here, with only `@paystack/inline-js` faked, so
+ * this asserts the navigation a fan actually gets rather than what was passed
+ * between two of our own functions.
+ */
+
+type ResumeOptions = {
+  onSuccess?: (t: { reference?: string }) => void;
+  onCancel?: () => void;
+  onLoad?: (r: unknown) => void;
+  onError?: (e: unknown) => void;
+};
+
+let captured: ResumeOptions = {};
+
+vi.mock("@paystack/inline-js", () => ({
+  default: class FakePaystackPop {
+    resumeTransaction(_accessCode: string, options: ResumeOptions = {}) {
+      captured = options;
+      options.onLoad?.({});
+      return {};
+    }
+    cancelTransaction() {}
+  },
+}));
+
+const post = vi.fn();
+
+vi.mock("../../../provider/ForgeProvider", () => ({
+  useForge: () => ({ client: { post }, profileId: "profile-1" }),
+}));
+
+import { usePaymentFlow } from "../usePaymentFlow";
+
+const FINALISE = "https://artist.test/i/events/summer-show/finalise?orderId=order-1";
+
+const wrapper = ({ children }: { children: ReactNode }) => {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } });
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+};
+
+let location: { href: string };
+
+beforeEach(() => {
+  captured = {};
+  post.mockReset();
+  post.mockResolvedValue({
+    data: { paymentProvider: "paystack", accessCode: "ac_1", checkoutUrl: "https://checkout.paystack.com/ac_1" },
+  });
+  location = { href: "https://artist.test/i/events/summer-show" };
+  Object.defineProperty(window, "location", { value: location, writable: true, configurable: true });
+});
+
+/** A ticket checkout: nothing is known until the order exists, so nothing is static. */
+const useClickDrivenFlow = () => usePaymentFlow({ path: "/public/events/event-1/start-payment", autoStart: false });
+
+/**
+ * Pay in the popup the flow opened for itself.
+ *
+ * `usePaymentFlow` auto-opens once a charge lands, which is what the ticket
+ * checkout relies on ("Paystack redirected" is its whole payment step), so the
+ * spec waits for that rather than racing it with a hand-driven open.
+ */
+async function payInPopup(reference = "pay-uuid"): Promise<void> {
+  await waitFor(() => expect(captured.onSuccess).toBeTypeOf("function"));
+  await act(async () => {
+    captured.onSuccess?.({ reference });
+  });
+}
+
+describe("usePaymentFlow: returning from a Paystack payment", () => {
+  it("REGRESSION: sends the buyer to the finalise URL the charge was started with", async () => {
+    const { result } = renderHook(useClickDrivenFlow, { wrapper });
+
+    await act(async () => {
+      await result.current.start({ orderId: "order-1", returnUrl: FINALISE });
+    });
+
+    // The server was told where to come back to...
+    expect(post).toHaveBeenCalledWith(
+      "/public/events/event-1/start-payment",
+      expect.objectContaining({ orderId: "order-1", returnUrl: FINALISE }),
+    );
+
+    await payInPopup();
+
+    // ...and so is the buyer. Before this fix `location.href` never moved.
+    expect(location.href).toContain("/finalise");
+    expect(location.href).toContain("orderId=order-1");
+    // The two params every finalise page already reads off a hosted redirect.
+    expect(location.href).toContain("reference=pay-uuid");
+    expect(location.href).toContain("trxref=pay-uuid");
+  });
+
+  it("still honours a static returnUrl for the flows that have one up front", async () => {
+    // The cart, film rentals and payment links pass it as an option, and that
+    // path must not regress while the click-driven one is fixed.
+    const { result } = renderHook(
+      () => usePaymentFlow({ path: "/public/payment-links/link-1/start-payment", returnUrl: FINALISE, autoStart: false }),
+      { wrapper },
+    );
+
+    await act(async () => {
+      await result.current.start();
+    });
+    await payInPopup();
+
+    expect(location.href).toContain("reference=pay-uuid");
+  });
+
+  it("leaves navigation alone when the surface finalises in place", async () => {
+    // Donations show their own thank-you step, so they pass `onPaystackSuccess`
+    // and must NOT be navigated away from it.
+    const onPaystackSuccess = vi.fn();
+    const { result } = renderHook(
+      () =>
+        usePaymentFlow({ path: "/public/donations/d-1/start-payment", autoStart: false, onPaystackSuccess }),
+      { wrapper },
+    );
+
+    await act(async () => {
+      await result.current.start({ returnUrl: FINALISE });
+    });
+    await payInPopup();
+
+    expect(onPaystackSuccess).toHaveBeenCalledWith({ reference: "pay-uuid" });
+    expect(location.href).toBe("https://artist.test/i/events/summer-show");
+  });
+
+  it("carries the LATEST start's URL when a charge is re-minted", async () => {
+    // A discount code re-starts the charge. Sending the buyer to the first
+    // attempt's finalise page would land them on a different order.
+    const { result } = renderHook(useClickDrivenFlow, { wrapper });
+
+    await act(async () => {
+      await result.current.start({ orderId: "order-1", returnUrl: "https://artist.test/finalise?orderId=order-1" });
+    });
+    await act(async () => {
+      await result.current.start({ orderId: "order-2", returnUrl: "https://artist.test/finalise?orderId=order-2" });
+    });
+    await payInPopup();
+
+    expect(location.href).toContain("orderId=order-2");
+    expect(location.href).not.toContain("orderId=order-1");
+  });
+});

package/src/data/queries/usePaymentFlow.ts

@@ -63,10 +63,32 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
     onError: opts.onPaystackError,
   };
 
+  /**
+   * The return URL the charge was actually STARTED with.
+   *
+   * Click-driven flows (event tickets, courses, coaching, offers) build their
+   * finalise URL from an id that does not exist until the resource is created,
+   * so they pass it in the `start()` override and never as a hook option. The
+   * Paystack session was read from the OPTION alone, so for all four it was
+   * `undefined`: the fan paid, the popup closed, `openPaystackCheckout` had
+   * nowhere to send them, and they sat on the checkout they had just paid on
+   * with no receipt and no confirmation. The charge was fine every time; only
+   * the way back was missing. Stripe was unaffected because it hands its own
+   * `return_url` to `confirmPayment`.
+   *
+   * A ref rather than state: it is read when the popup is opened, never
+   * rendered, and a re-render on every start would re-run the auto-open effect.
+   */
+  const startedReturnUrlRef = useRef<string | undefined>(undefined);
+
   const mutation = useMutation<PaymentFlowResult, unknown, Record<string, unknown> | undefined>({
     mutationFn: async (override) => {
       // override wins — click-driven flows pass a just-created orderId/returnUrl.
-      const res = await client.post(path as string, { ...body, profileId, returnUrl, ...(override ?? {}) });
+      const payload = { ...body, profileId, returnUrl, ...(override ?? {}) };
+      // Whatever the server was told, byte for byte. Resolving it any other way
+      // is how these two drift apart again.
+      startedReturnUrlRef.current = (payload.returnUrl as string | undefined) || undefined;
+      const res = await client.post(path as string, payload);
       const data = res.data as PaymentStartResponse;
       const provider = (data.paymentProvider ?? data.paymentProviderName) as PaymentProviderName | undefined;
       return { ...data, provider };
@@ -88,8 +110,11 @@ export function usePaymentFlow(opts: UsePaymentFlowOptions) {
    * session, which is what makes "closed it by accident" recoverable.
    */
   const openPaystack = useCallback(async (): Promise<PaystackCheckoutOutcome> => {
-    if (!hasPaystackSession(session)) return "unavailable";
-    return openPaystackCheckout(session, {
+    // The URL the charge was started with wins over the static option: for a
+    // click-driven flow it is the only one there has ever been.
+    const active = { ...session, returnUrl: startedReturnUrlRef.current ?? session.returnUrl };
+    if (!hasPaystackSession(active)) return "unavailable";
+    return openPaystackCheckout(active, {
       onSuccess: handlersRef.current.onSuccess,
       onDismiss: handlersRef.current.onDismiss,
       onError: handlersRef.current.onError,

package/src/i18n/de.json

@@ -62,6 +62,7 @@
   "forge.account_dashboard.profile_section_title": "Profilangaben",
   "forge.account_dashboard.profile_update_error": "Profil konnte nicht aktualisiert werden.",
   "forge.account_dashboard.profile_update_success": "Profil aktualisiert.",
+  "forge.account_dashboard.rentals_title": "Meine Ausleihen",
   "forge.account_dashboard.request_deletion": "Kontolöschung beantragen",
   "forge.account_dashboard.reschedule": "Verschieben",
   "forge.account_dashboard.reschedule_empty": "In den nächsten zwei Wochen sind keine anderen Zeiten frei.",
@@ -80,6 +81,7 @@
   "forge.account_dashboard.tab_membership": "Mitgliedschaft",
   "forge.account_dashboard.tab_notifications": "Mitteilungen",
   "forge.account_dashboard.tab_orders": "Bestellungen",
+  "forge.account_dashboard.tab_rentals": "Ausleihen",
   "forge.account_dashboard.tab_saved": "Gespeichert",
   "forge.account_dashboard.tab_tickets": "Tickets",
   "forge.account_dashboard.tab_waitlist": "Warteliste",

package/src/i18n/en.json

@@ -62,6 +62,7 @@
   "forge.account_dashboard.profile_section_title": "Profile Information",
   "forge.account_dashboard.profile_update_error": "Failed to update profile.",
   "forge.account_dashboard.profile_update_success": "Profile updated.",
+  "forge.account_dashboard.rentals_title": "My Rentals",
   "forge.account_dashboard.request_deletion": "Request Account Deletion",
   "forge.account_dashboard.reschedule": "Reschedule",
   "forge.account_dashboard.reschedule_empty": "No other times are open in the next two weeks.",
@@ -80,6 +81,7 @@
   "forge.account_dashboard.tab_membership": "Membership",
   "forge.account_dashboard.tab_notifications": "Notifications",
   "forge.account_dashboard.tab_orders": "Orders",
+  "forge.account_dashboard.tab_rentals": "Rentals",
   "forge.account_dashboard.tab_saved": "Saved",
   "forge.account_dashboard.tab_tickets": "Tickets",
   "forge.account_dashboard.tab_waitlist": "Waitlist",

package/src/ui/headless/_tests/dialogPaystackStandDown.spec.tsx

@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, render, fireEvent } from "@testing-library/react";
+
+/**
+ * The bug this file exists for: a fan on a code website could not pay with
+ * Paystack from inside a dialog.
+ *
+ * Paystack appends its checkout overlay to `document.body`. A modal Radix
+ * dialog sets `pointer-events: none` on that same body and traps focus inside
+ * its own content, so the popup arrives on top of the page, looks completely
+ * normal, and eats every click and keystroke aimed at it. The fan sees the card
+ * form and cannot type in it. Event tickets, courses, coaching, films,
+ * donations and offers all open the popup from inside one of these dialogs, so
+ * every one of them was unpayable on Paystack.
+ *
+ * It went unnoticed because the only inline-checkout UI coverage was the
+ * payment-link page, which is a plain page with no dialog on it.
+ *
+ * jsdom rather than `renderToStaticMarkup`: the whole behaviour is mount
+ * effects (Radix writes the body style on mount and restores it on unmount), so
+ * there is nothing to assert without a real DOM lifecycle.
+ */
+
+type ResumeOptions = {
+  onSuccess?: (t: { reference?: string }) => void;
+  onCancel?: () => void;
+  onLoad?: (r: unknown) => void;
+  onError?: (e: unknown) => void;
+};
+
+let captured: ResumeOptions = {};
+
+vi.mock("@paystack/inline-js", () => ({
+  default: class FakePaystackPop {
+    resumeTransaction(_accessCode: string, options: ResumeOptions = {}) {
+      captured = options;
+      options.onLoad?.({});
+      return {};
+    }
+    cancelTransaction() {}
+  },
+}));
+
+import { openPaystackCheckout } from "../../../utils/paystackCheckout";
+import { DialogRoot, DialogPortal, DialogOverlay, DialogContent, DialogTitle } from "../dialog";
+
+/** jsdom refuses real navigation, so `location` is replaced with a plain bag. */
+beforeEach(() => {
+  captured = {};
+  Object.defineProperty(window, "location", {
+    value: { href: "https://artist.test/tickets" },
+    writable: true,
+    configurable: true,
+  });
+});
+
+function Checkout({ open, onOpenChange }: { open: boolean; onOpenChange?: (next: boolean) => void }) {
+  return (
+    <DialogRoot open={open} onOpenChange={onOpenChange}>
+      <DialogPortal>
+        <DialogOverlay />
+        <DialogContent aria-describedby={undefined}>
+          <DialogTitle>Tickets</DialogTitle>
+          <button type="button">Pay</button>
+        </DialogContent>
+      </DialogPortal>
+    </DialogRoot>
+  );
+}
+
+/**
+ * Open the popup the way a pay button does, and leave it open.
+ *
+ * The attempt is handed back inside an object rather than as the promise
+ * itself: `await` flattens a promise returned from an async function, and this
+ * one deliberately does not settle until the fan acts.
+ */
+async function openPopup(): Promise<{ attempt: Promise<unknown> }> {
+  let attempt: Promise<unknown> = Promise.resolve();
+  await act(async () => {
+    attempt = openPaystackCheckout({ accessCode: "ac_1", checkoutUrl: "https://checkout.paystack.com/abc" });
+    // Let the dynamic import of the SDK land.
+    await Promise.resolve();
+    await Promise.resolve();
+  });
+  return { attempt };
+}
+
+/** Close the popup and let the attempt finish, as a dismissal does. */
+async function dismissPopup(attempt: Promise<unknown>): Promise<void> {
+  await act(async () => {
+    captured.onCancel?.();
+    await attempt;
+  });
+}
+
+describe("the dialog and the Paystack popup", () => {
+  it("locks the page while it is an ordinary modal", () => {
+    // The baseline, asserted so the rest of this file cannot pass by the
+    // dialog simply never being modal in the first place.
+    render(<Checkout open />);
+
+    expect(document.body.style.pointerEvents).toBe("none");
+  });
+
+  it("REGRESSION: releases the page the moment the popup opens", async () => {
+    render(<Checkout open />);
+    expect(document.body.style.pointerEvents).toBe("none");
+
+    const { attempt } = await openPopup();
+
+    // The fan can now reach the card form. This one assertion is the bug.
+    expect(document.body.style.pointerEvents).not.toBe("none");
+
+    await dismissPopup(attempt);
+  });
+
+  it("stays out of the way after a dismissal rather than remounting the checkout under the fan", async () => {
+    // Radix renders modal and non-modal content as different components, so
+    // flipping back would remount everything inside the dialog in front of
+    // somebody who just closed the popup and is about to try again.
+    render(<Checkout open />);
+    const { attempt } = await openPopup();
+
+    await dismissPopup(attempt);
+
+    expect(document.body.style.pointerEvents).not.toBe("none");
+  });
+
+  it("is a normal modal again the next time it opens", async () => {
+    // Closed by its owner setting `open` to false, with no `onOpenChange` in
+    // sight. That is how the ticket modal closes when a buyer sends their
+    // selection to the cart, and watching only `onOpenChange` left those
+    // dialogs non-modal for the rest of the visit.
+    const { rerender } = render(<Checkout open />);
+    const { attempt } = await openPopup();
+    await dismissPopup(attempt);
+
+    await act(async () => {
+      rerender(<Checkout open={false} />);
+    });
+    await act(async () => {
+      rerender(<Checkout open />);
+    });
+
+    expect(document.body.style.pointerEvents).toBe("none");
+  });
+
+  it("REGRESSION: Escape closes the payment window, not the checkout behind it", async () => {
+    // Non-modal dialogs still dismiss on Escape, and a fan pressing it means
+    // "close Paystack". Taking the checkout down with it loses the order.
+    const onOpenChange = vi.fn();
+    render(<Checkout open onOpenChange={onOpenChange} />);
+    const { attempt } = await openPopup();
+
+    await act(async () => {
+      fireEvent.keyDown(document, { key: "Escape" });
+    });
+
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+
+    await dismissPopup(attempt);
+  });
+
+  it("REGRESSION: a click on Paystack's own backdrop does not close the checkout", async () => {
+    // Paystack's overlay is a node in THIS document, outside the dialog
+    // content, so a non-modal dialog reads a tap beside the card form as an
+    // outside interaction and dismisses.
+    const onOpenChange = vi.fn();
+    render(<Checkout open onOpenChange={onOpenChange} />);
+    const { attempt } = await openPopup();
+
+    const backdrop = document.createElement("div");
+    document.body.appendChild(backdrop);
+    await act(async () => {
+      fireEvent.pointerDown(backdrop);
+      fireEvent.mouseDown(backdrop);
+    });
+
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+
+    await dismissPopup(attempt);
+  });
+});

package/src/ui/headless/dialog.tsx

@@ -1,14 +1,149 @@
-// Unstyled dialog primitives — thin re-export of Radix Dialog so the headless
+// Unstyled dialog primitives — a thin wrapper over Radix Dialog so the headless
 // blocks get portal + focus-trap + a11y + keyboard for free, with zero styling.
-export {
-  Root as DialogRoot,
+//
+// Thin, but no longer a bare re-export: `DialogRoot` and `DialogContent` stand
+// down while a Paystack popup is on screen. See `usePaystackPopupOpen` below
+// for why that is not optional.
+import * as React from "react";
+import {
+  Root,
   Trigger as DialogTrigger,
   Portal as DialogPortal,
   Overlay as DialogOverlay,
-  Content as DialogContent,
+  Content,
   Close as DialogClose,
   Title as DialogTitle,
   Description as DialogDescription,
 } from "@radix-ui/react-dialog";
+import { isPaystackPopupOpen, subscribeToPaystackPopup } from "../../utils/paystackCheckout";
 
+export { DialogTrigger, DialogPortal, DialogOverlay, DialogClose, DialogTitle, DialogDescription };
 export { Slot } from "@radix-ui/react-slot";
+
+/**
+ * Is Paystack's popup on screen right now?
+ *
+ * Exported for a site that builds its own dialog instead of using these
+ * primitives: the popup lives on `document.body`, so ANY modal layer that locks
+ * the page will lock the popup out with it.
+ */
+export function usePaystackPopupOpen(): boolean {
+  return React.useSyncExternalStore(
+    subscribeToPaystackPopup,
+    isPaystackPopupOpen,
+    // SSR: no popup can be open on the server, and guessing "yes" would render
+    // a non-modal dialog that turns modal on hydration.
+    () => false,
+  );
+}
+
+/**
+ * The dialog root, which STOPS BEING MODAL once a Paystack popup opens inside
+ * it.
+ *
+ * A modal Radix dialog sets `pointer-events: none` on `document.body` and traps
+ * focus in its own content. Paystack appends its overlay to the body, outside
+ * that content, so both of those apply to the popup: the fan sees the card form
+ * on top of everything, clicks it, and nothing happens — the dialog they opened
+ * it from is eating every event. Every Paystack pillar on a code website (event
+ * tickets, courses, coaching, films, donations, offers) opens the popup from
+ * inside one of these, so all six were unpayable.
+ *
+ * Non-modal content drops both behaviours, which is exactly the amount of
+ * getting-out-of-the-way required, and the popup's own overlay is still on top
+ * of the page at a z-index nothing here competes with.
+ *
+ * ## Why it does not switch back when the popup closes
+ *
+ * Radix renders modal and non-modal content as DIFFERENT components, so
+ * flipping the flag remounts everything inside the dialog. Once is free: the
+ * popup is covering the screen at that moment and the pillar hooks that hold
+ * the checkout state live OUTSIDE the dialog content. Flipping back on dismissal
+ * would remount a second time in front of the fan, resetting whatever they had
+ * typed into the step they are looking at. So the dialog stays non-modal until
+ * it CLOSES, and opens modal again next time.
+ *
+ * A host that passes `modal={false}` keeps it: this only ever removes modality.
+ */
+export function DialogRoot({
+  modal,
+  open,
+  onOpenChange,
+  ...props
+}: React.ComponentProps<typeof Root>): React.ReactElement {
+  const popupOpen = usePaystackPopupOpen();
+  const [stoodDown, setStoodDown] = React.useState(false);
+
+  React.useEffect(() => {
+    if (popupOpen) setStoodDown(true);
+  }, [popupOpen]);
+
+  /**
+   * Closing ends the stand-down, so the NEXT time this dialog opens it is an
+   * ordinary modal again.
+   *
+   * Both routes are covered on purpose. A CONTROLLED dialog can be closed by
+   * its owner setting `open` to false without `onOpenChange` ever firing (the
+   * ticket modal does exactly that when the buyer sends a selection to the
+   * cart), and an UNCONTROLLED one has no `open` prop to watch.
+   */
+  React.useEffect(() => {
+    if (open === false) setStoodDown(false);
+  }, [open]);
+
+  return (
+    <Root
+      {...props}
+      open={open}
+      modal={modal === false ? false : !stoodDown}
+      onOpenChange={(next) => {
+        if (!next) setStoodDown(false);
+        onOpenChange?.(next);
+      }}
+    />
+  );
+}
+
+/**
+ * The dialog body, which refuses to fight the Paystack popup for focus or for
+ * the fan's clicks.
+ *
+ * Three defaults have to be suspended while the popup is up, and all three are
+ * the dialog doing its job in a situation where its job is wrong:
+ *
+ *  - **Auto-focus on open.** A non-modal remount focuses its first control,
+ *    which would yank the caret out of the card field the fan is typing in.
+ *  - **Dismiss on outside interaction.** Paystack's backdrop is a click in THIS
+ *    document, outside this content, so closing the popup by tapping beside it
+ *    would take the checkout down with it.
+ *  - **Dismiss on Escape.** Same thing with the key that means "close the
+ *    payment window".
+ *
+ * Each host handler still runs; the suspension is applied after it, so a
+ * surface that wants its own behaviour keeps it everywhere except here.
+ */
+export const DialogContent = React.forwardRef<
+  React.ElementRef<typeof Content>,
+  React.ComponentPropsWithoutRef<typeof Content>
+>(function DialogContent({ onOpenAutoFocus, onInteractOutside, onEscapeKeyDown, ...props }, ref) {
+  const popupOpen = usePaystackPopupOpen();
+
+  return (
+    <Content
+      {...props}
+      ref={ref}
+      onOpenAutoFocus={(event) => {
+        onOpenAutoFocus?.(event);
+        if (popupOpen) event.preventDefault();
+      }}
+      onInteractOutside={(event) => {
+        onInteractOutside?.(event);
+        if (popupOpen) event.preventDefault();
+      }}
+      onEscapeKeyDown={(event) => {
+        onEscapeKeyDown?.(event);
+        if (popupOpen) event.preventDefault();
+      }}
+    />
+  );
+});

package/src/ui/index.ts

@@ -200,7 +200,10 @@ export { CourseAccess, type CourseAccessProps } from "./styled/CourseAccess";
 // 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";
+// `FilmRentalList` is the library WITHOUT its page heading: the rows on their
+// own, for a surface that supplies its own title (the account dashboard's
+// Rentals tab does exactly this). Same rows, same live/expired rule.
+export { FilmLibrary, FilmRentalList, type FilmLibraryProps, type FilmRentalListProps } 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";

package/src/ui/styled/AccountDashboard.tsx

@@ -18,6 +18,7 @@ import {
   useSavedPosts,
   useNotificationPreferences,
   useUpdateNotificationPreference,
+  useMyFilmRentals,
   useCancelMembership,
   useMembershipAccess,
   useOpenBillingPortal,
@@ -42,6 +43,7 @@ import { AddToCalendar } from "./AddToCalendar";
 import { WalletPassButtons } from "./WalletPassButtons";
 import { TicketTransferPanel } from "./TicketTransfer";
 import { CartLineOptions } from "./CartLineOptions";
+import { FilmRentalList } from "./FilmLibrary";
 
 export const ACCOUNT_TABS = [
   "membership",
@@ -54,6 +56,13 @@ export const ACCOUNT_TABS = [
   // "order" — the Orders tab covers product orders only — so it needs its own
   // tab or it is unreachable, which is what it was.
   "bookings",
+  // Films and series this fan has rented. Next to the other purchase surfaces
+  // because it answers the same question they do: what did I buy from this
+  // artist, and can I use it right now?
+  //
+  // Drawn only when the fan actually holds a rental (see `visibleTabs`), so the
+  // tab does not appear on the account page of every site that never sells one.
+  "rentals",
   "saved",
   "account",
   "notifications",
@@ -70,6 +79,7 @@ const TAB_LABEL_KEYS: Record<AccountTabKey, string> = {
   tickets: "forge.account_dashboard.tab_tickets",
   waitlist: "forge.account_dashboard.tab_waitlist",
   bookings: "forge.account_dashboard.tab_bookings",
+  rentals: "forge.account_dashboard.tab_rentals",
   saved: "forge.account_dashboard.tab_saved",
   account: "forge.account_dashboard.tab_account",
   notifications: "forge.account_dashboard.tab_notifications",
@@ -98,6 +108,15 @@ export interface AccountDashboardProps {
    * member a room they get bounced out of, which is worse than no link at all.
    */
   onNavigateCommunity?: () => void;
+  /**
+   * Navigate to a film route from the Rentals tab (watch, resume, rent again).
+   *
+   * Takes the href rather than being one callback per destination, because a
+   * rental row points at a title AND at the episode the fan got to, so the
+   * target is data rather than a fixed page. Left out, the row falls back to a
+   * full-page visit, which works on any site and is merely slower.
+   */
+  onNavigateFilm?: (href: string) => void;
   /**
    * Optional currency formatter override. Defaults to Forge's `useFormatCurrency`
    * (which honors the visitor's selected currency + tenant exchange rates), so the
@@ -164,6 +183,7 @@ interface TabContext {
   currency?: string;
   onNavigateMembership?: () => void;
   onNavigateCommunity?: () => void;
+  onNavigateFilm?: (href: string) => void;
 }
 
 // ---- page -------------------------------------------------------------------
@@ -178,6 +198,7 @@ export function AccountDashboard({
   onTabChange,
   onNavigateMembership,
   onNavigateCommunity,
+  onNavigateFilm,
   formatAmount,
   formatDate,
   currency,
@@ -188,6 +209,17 @@ export function AccountDashboard({
   const { t } = useCardStyles();
   const tr = useForgeT();
   const { data: siteConfig } = useSiteConfig();
+  /**
+   * Does this fan hold any rental at all? That is the whole gate on the Rentals
+   * tab, on the same principle as the community link above: the server's own
+   * answer decides, and a surface with nothing behind it is not drawn.
+   *
+   * Film rentals are off by default and per profile, so on most sites this read
+   * comes back empty for ever and the tab never appears. It is the SAME query
+   * `FilmRentalList` runs inside the tab (same key, same arguments), so
+   * react-query serves both from one request rather than two.
+   */
+  const { data: rentals } = useMyFilmRentals(user?.id);
 
   const fmtAmount = useAmountFormatter(formatAmount);
   const fmtDate = formatDate ?? defaultFormatDate;
@@ -200,8 +232,18 @@ export function AccountDashboard({
     currency: currency ?? siteConfig?.currency,
     onNavigateMembership,
     onNavigateCommunity,
+    onNavigateFilm,
   };
 
+  /**
+   * The strip hides Rentals until there is something in it. The one exception
+   * is the tab currently being shown, so a link straight to `?tab=rentals` (a
+   * receipt email, a bookmark) does not land on a page whose strip disowns the
+   * panel underneath it.
+   */
+  const hasRentals = (rentals?.total ?? 0) > 0;
+  const visibleTabs = ACCOUNT_TABS.filter((key) => key !== "rentals" || hasRentals || tab === "rentals");
+
   if (!user) return <Loading fullPage />;
 
   return (
@@ -222,7 +264,7 @@ export function AccountDashboard({
       </div>
 
       <div style={{ display: "flex", gap: 8, flexWrap: "wrap", marginBottom: 24 }}>
-        {ACCOUNT_TABS.map((tabKey) => (
+        {visibleTabs.map((tabKey) => (
           <button
             key={tabKey}
             onClick={() => onTabChange?.(tabKey)}
@@ -247,6 +289,7 @@ export function AccountDashboard({
       {tab === "tickets" && <TicketsTab ctx={ctx} />}
       {tab === "waitlist" && <WaitlistTab ctx={ctx} />}
       {tab === "bookings" && <BookingsTab ctx={ctx} />}
+      {tab === "rentals" && <RentalsTab ctx={ctx} />}
       {tab === "saved" && <SavedTab />}
       {tab === "account" && <AccountTab ctx={ctx} />}
       {tab === "notifications" && <NotificationsTab />}
@@ -1286,6 +1329,35 @@ function RescheduleSlotPicker({ booking, onDone }: { booking: MyBooking; onDone:
   );
 }
 
+// ---- Rentals tab ------------------------------------------------------------
+
+/**
+ * Films and series this fan has rented, live and expired.
+ *
+ * `/i/films/library` already answered this, and nothing on the account page led
+ * to it: a fan who rented a film found their tickets, their orders and their
+ * sessions here and no sign that the rental existed. This is that page's list,
+ * rendered in the tab strip where a buyer looks for a purchase.
+ *
+ * The affordance per row comes from the SERVER's `isLive`, not from arithmetic
+ * repeated here: a running window offers Watch (Resume, when there is progress
+ * to resume), and a window that has closed or been refunded offers Rent again.
+ * That decision lives in one place, `FilmRentalList`, and both surfaces read it.
+ */
+function RentalsTab({ ctx }: { ctx: TabContext }) {
+  const { t, card } = useCardStyles();
+  const tr = useForgeT();
+
+  return (
+    <div style={card}>
+      <h2 style={{ fontSize: 18, fontWeight: 700, marginBottom: 16, fontFamily: t.headingFontFamily }}>
+        {tr("forge.account_dashboard.rentals_title")}
+      </h2>
+      <FilmRentalList navigate={ctx.onNavigateFilm} />
+    </div>
+  );
+}
+
 // ---- Orders tab -------------------------------------------------------------
 
 function OrdersTab({ ctx }: { ctx: TabContext }) {

package/src/ui/styled/FilmLibrary.tsx

@@ -11,7 +11,7 @@ import {
 } from "../../data/queries/useFilms";
 import { useForgeT, type ForgeT } from "../../i18n";
 
-export interface FilmLibraryProps {
+export interface FilmRentalListProps {
   /** Where films live. Default `/i/films`. */
   basePath?: string;
   /** SPA navigation adapter. Defaults to a full-page visit. */
@@ -20,27 +20,30 @@ export interface FilmLibraryProps {
   style?: CSSProperties;
 }
 
+/** The page takes exactly what the list takes: it adds a heading, nothing else. */
+export type FilmLibraryProps = FilmRentalListProps;
+
 /**
- * The fan's own rentals: what is running, what has not been started, and what
- * has run out.
+ * The rentals themselves, with no page furniture around them.
  *
- * Expired rentals are here deliberately. The library is where a fan re-rents,
- * and a rental that vanishes on expiry reads as "you were robbed" rather than
- * "that ended" - so an expired row keeps its title, states plainly that the
- * window closed, and offers the way back.
+ * Split out of `FilmLibrary` so the account dashboard's Rentals tab renders the
+ * SAME rows as `/i/films/library` rather than a second implementation of "is
+ * this window still open". Two answers to that question is one answer too many:
+ * the divergent copy would appear on whichever surface was edited second, and
+ * the fan would be told two different things about the same rental.
  *
- * A row states one fact the reader must act on, so it stays visible rather than
- * going behind a `?`: how long is left. There is no "what was bought" line any
- * more, because a rental is always the whole title and the title is the row.
+ * It fetches its own data. `useMyFilmRentals` is keyed on the account, so a host
+ * that already read it (the dashboard does, to decide whether to draw the tab at
+ * all) shares one request through react-query rather than making a second.
  */
-export function FilmLibrary({ basePath = "/i/films", navigate, className, style }: FilmLibraryProps) {
+export function FilmRentalList({ basePath = "/i/films", navigate, className, style }: FilmRentalListProps) {
   const t = useForgeT();
   const tokens = useThemeTokens();
   const { user, isInitialized } = usePublicAuth();
   const { data, isLoading } = useMyFilmRentals(user?.id);
   const go = navigate ?? ((href: string) => window.location.assign(href));
 
-  if (!isInitialized || isLoading) return <Loading fullPage />;
+  if (!isInitialized || isLoading) return <Loading />;
 
   const rentals = data?.data ?? [];
 
@@ -61,23 +64,11 @@ export function FilmLibrary({ basePath = "/i/films", navigate, className, style
         display: "flex",
         flexDirection: "column",
         gap: 16,
-        maxWidth: 900,
-        margin: "0 auto",
         color: tokens.text,
         fontFamily: tokens.fontFamily,
         ...style,
       }}
     >
-      <h1
-        style={{
-          fontSize: 24,
-          fontWeight: 800,
-          fontFamily: tokens.headingFontFamily || tokens.fontFamily,
-        }}
-      >
-        {t("forge.film_library.heading")}
-      </h1>
-
       {rentals.length === 0 && (
         <div style={notice}>
           <p style={{ marginBottom: 12 }}>{t("forge.film_library.empty")}</p>
@@ -107,6 +98,52 @@ export function FilmLibrary({ basePath = "/i/films", navigate, className, style
   );
 }
 
+/**
+ * The fan's own rentals as a PAGE: what is running, what has not been started,
+ * and what has run out.
+ *
+ * Expired rentals are here deliberately. The library is where a fan re-rents,
+ * and a rental that vanishes on expiry reads as "you were robbed" rather than
+ * "that ended" - so an expired row keeps its title, states plainly that the
+ * window closed, and offers the way back.
+ *
+ * A row states one fact the reader must act on, so it stays visible rather than
+ * going behind a `?`: how long is left. There is no "what was bought" line any
+ * more, because a rental is always the whole title and the title is the row.
+ */
+export function FilmLibrary({ basePath, navigate, className, style }: FilmLibraryProps) {
+  const t = useForgeT();
+  const tokens = useThemeTokens();
+
+  return (
+    <div
+      className={className}
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 16,
+        maxWidth: 900,
+        margin: "0 auto",
+        color: tokens.text,
+        fontFamily: tokens.fontFamily,
+        ...style,
+      }}
+    >
+      <h1
+        style={{
+          fontSize: 24,
+          fontWeight: 800,
+          fontFamily: tokens.headingFontFamily || tokens.fontFamily,
+        }}
+      >
+        {t("forge.film_library.heading")}
+      </h1>
+
+      <FilmRentalList basePath={basePath} navigate={navigate} />
+    </div>
+  );
+}
+
 /** Where the fan got to in the episode they should resume, or null. */
 function resumeTarget(rental: MyFilmRental): { episodeId: string; entry: FilmWatchProgressEntry } | null {
   // The furthest-along INCOMPLETE episode: resuming a finished one is how a

package/src/ui/styled/_tests/AccountDashboardRentals.spec.tsx

@@ -0,0 +1,200 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import type { MyFilmRental } from "../../../data/queries/useFilms";
+import { AccountDashboard, type AccountTabKey } from "../AccountDashboard";
+
+/**
+ * Rentals on the account page.
+ *
+ * A fan who rented a film could find their tickets, their orders and their
+ * coaching sessions on this page and no trace of the rental - `/i/films/library`
+ * held it, and nothing on the account page pointed there. So the tab exists, and
+ * these are the two things it must get right:
+ *
+ *   LIVE     - the window is open, so the row offers the way in (Resume when
+ *              there is progress to resume, Watch otherwise).
+ *   NOT LIVE - expired or refunded, so the row offers Rent again and NOT a
+ *              Watch button that leads to a player which would refuse them.
+ *
+ * `isLive` is the SERVER's answer (`msRemaining`, `expiresAt`, `revokedAt` are
+ * all decided there). Nothing here recomputes it, and these specs assert the
+ * rendering of that flag rather than any clock arithmetic in the browser.
+ *
+ * Rendered through `react-dom/server`, like the community spec beside it: no
+ * DOM and no effects, so the rentals query is SEEDED into the react-query cache
+ * rather than mocked. That keeps the real `useMyFilmRentals` in the path, and a
+ * rename of its query key fails here.
+ */
+
+const PROFILE_ID = "profile-1";
+const ACCOUNT_ID = "account-1";
+
+/** The key `useMyFilmRentals(accountId)` reads, at its default page and limit. */
+const RENTALS_KEY = ["my-film-rentals", ACCOUNT_ID, PROFILE_ID, 1, 20];
+
+const rental = (overrides: Partial<MyFilmRental> = {}): MyFilmRental => ({
+  id: "rental-1",
+  filmId: "film-1",
+  status: "active",
+  amountCents: 500,
+  currency: "USD",
+  rentalDurationHours: 48,
+  rentalOptionId: "option-1",
+  paidAt: "2026-08-01T00:00:00.000Z",
+  startBy: "2026-09-01T00:00:00.000Z",
+  firstPlayedAt: "2026-08-02T00:00:00.000Z",
+  expiresAt: "2026-08-04T00:00:00.000Z",
+  refundedAt: null,
+  revokedAt: null,
+  isLive: true,
+  msRemaining: 3 * 3600_000,
+  windowMs: 48 * 3600_000,
+  film: {
+    id: "film-1",
+    title: "The Long Goodbye",
+    slug: "the-long-goodbye",
+    kind: "film",
+    status: "published",
+    archivedAt: null,
+    cover: null,
+  },
+  progress: [],
+  ...overrides,
+});
+
+const fan = {
+  id: ACCOUNT_ID,
+  email: "fan@example.com",
+  firstName: "Fan",
+  lastName: "Person",
+  kind: "fan",
+  status: "active",
+  createdAt: "2026-01-01T00:00:00.000Z",
+  updatedAt: "2026-01-01T00:00:00.000Z",
+  membership: null,
+};
+
+function render(opts: { rentals: MyFilmRental[] | null; tab?: AccountTabKey }): string {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  if (opts.rentals) {
+    queryClient.setQueryData(RENTALS_KEY, {
+      data: opts.rentals,
+      total: opts.rentals.length,
+      page: 1,
+      limit: 20,
+    });
+  }
+
+  return renderToStaticMarkup(
+    <QueryClientProvider client={queryClient}>
+      <ForgeClientProvider apiUrl="http://api.test" profileId={PROFILE_ID}>
+        <PublicAuthContext.Provider
+          value={
+            {
+              user: fan,
+              isInitialized: true,
+              currencies: null,
+              userSelectedCurrency: "USD",
+              logout: () => {},
+            } as never
+          }
+        >
+          <ForgeThemeProvider
+            theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}
+          >
+            <AccountDashboard tab={opts.tab ?? "rentals"} onNavigateMembership={() => {}} />
+          </ForgeThemeProvider>
+        </PublicAuthContext.Provider>
+      </ForgeClientProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("AccountDashboard: the fan's rentals", () => {
+  it("REGRESSION: a running rental is reachable from the account page", () => {
+    // The gap this closes. The rental existed, the player existed, and the
+    // account page mentioned neither.
+    const html = render({ rentals: [rental()] });
+
+    expect(html).toContain("Rentals");
+    expect(html).toContain("The Long Goodbye");
+    expect(html).toContain("Watch");
+    // The window is state the fan acts on, so it is on the row rather than
+    // behind a `?`.
+    expect(html).toContain("3h 0m left");
+    expect(html).not.toContain("Rent again");
+  });
+
+  it("offers to resume the episode the fan stopped in the middle of", () => {
+    const html = render({
+      rentals: [rental({ progress: [{ episodeId: "episode-1", positionSec: 900, completedAt: null }] })],
+    });
+
+    expect(html).toContain("Resume");
+  });
+
+  it("REGRESSION: an expired rental offers Rent again, never Watch", () => {
+    // Drawing Watch here walks the fan into a player that refuses them: the
+    // window is the server's to judge and it has closed.
+    const html = render({
+      rentals: [rental({ isLive: false, msRemaining: 0, expiresAt: "2026-08-04T00:00:00.000Z" })],
+    });
+
+    expect(html).toContain("Rent again");
+    expect(html).toContain("Your window has closed.");
+    expect(html).not.toContain(">Watch<");
+    expect(html).not.toContain(">Resume<");
+  });
+
+  it("says a refunded rental was refunded rather than that it ran out", () => {
+    // Two different things happened, and "your window has closed" over a refund
+    // reads as the artist keeping the money.
+    const html = render({
+      rentals: [rental({ isLive: false, msRemaining: null, refundedAt: "2026-08-03T00:00:00.000Z" })],
+    });
+
+    expect(html).toContain("Refunded.");
+    expect(html).toContain("Rent again");
+  });
+
+  it("keeps a rental that has not been started apart from one that is running", () => {
+    // The clock starts at first play, so this fan has lost nothing by waiting.
+    // Saying "0m left" here would be a lie that costs them the film.
+    const html = render({ rentals: [rental({ firstPlayedAt: null, msRemaining: null, expiresAt: null })] });
+
+    expect(html).toContain("Not started.");
+    expect(html).toContain("Watch");
+  });
+
+  it("does not draw the tab on a site where this fan holds no rental", () => {
+    // Film rentals are off by default and per profile. An always-empty tab on
+    // every account page is noise on every site that never sells one.
+    const html = render({ rentals: [], tab: "membership" });
+
+    expect(html).not.toContain("Rentals");
+    // The rest of the strip is untouched, so this is the one tab missing rather
+    // than the dashboard failing to draw.
+    expect(html).toContain("Tickets");
+  });
+
+  it("stays quiet while the rentals query has not answered yet", () => {
+    // First paint has no cached answer. Drawing the tab on a guess flashes it
+    // and then withdraws it from fans who never rented anything.
+    const html = render({ rentals: null, tab: "membership" });
+
+    expect(html).not.toContain("Rentals");
+  });
+
+  it("keeps the tab drawn when it is the one being shown, even with nothing in it", () => {
+    // A receipt email links straight at `?tab=rentals`. A strip that disowns the
+    // panel underneath it is worse than an empty tab.
+    const html = render({ rentals: [], tab: "rentals" });
+
+    expect(html).toContain("Rentals");
+    expect(html).toContain("You have not rented anything yet.");
+  });
+});

package/src/ui/styled/forge-utilities.css

@@ -84,6 +84,9 @@
     .order-1 {
       order: 1;
     }
+    .order-2 {
+      order: 2;
+    }
     .container {
       width: 100%;
       @media (width >= 40rem) {

package/src/utils/_tests/paystackCheckout.spec.ts

@@ -48,7 +48,12 @@ vi.mock("@paystack/inline-js", () => {
 
 // Imported after the mock is registered (vitest hoists `vi.mock`, so a plain
 // top-level import would be fine; this is only for readability).
-import { openPaystackCheckout, paystackReturnUrl, hasPaystackSession } from "../paystackCheckout";
+import {
+  openPaystackCheckout,
+  paystackReturnUrl,
+  hasPaystackSession,
+  isPaystackPopupOpen,
+} from "../paystackCheckout";
 
 const HOSTED = "https://checkout.paystack.com/abc123";
 const RETURN = "https://artist.test/checkout/finalise?orderId=order-1";
@@ -264,3 +269,79 @@ describe("openPaystackCheckout", () => {
     expect(location.href).toBe("https://artist.test/checkout");
   });
 });
+
+/**
+ * The popup says when it is up, so the dialog it was opened from can stand
+ * down (`ui/headless/dialog.tsx`).
+ *
+ * A flag left stuck ON is worse than no flag: every dialog on the site would
+ * stay non-modal for the rest of the session. So each terminal outcome is
+ * asserted separately rather than trusting one shared teardown.
+ */
+describe("openPaystackCheckout popup state", () => {
+  it("is closed before anything is opened", () => {
+    expect(isPaystackPopupOpen()).toBe(false);
+  });
+
+  it("is open while the fan is deciding, and closed again once they pay", async () => {
+    let captured: ResumeOptions = {};
+    resumeBehaviour = (_code, options) => {
+      captured = options;
+      options.onLoad?.({});
+    };
+
+    const pending = openPaystackCheckout({ accessCode: "ac_1", checkoutUrl: HOSTED, returnUrl: RETURN });
+    await vi.advanceTimersByTimeAsync(0);
+
+    // The card form is on screen: the dialog behind it must not be holding the
+    // page's pointer events hostage.
+    expect(isPaystackPopupOpen()).toBe(true);
+
+    captured.onSuccess?.({ reference: "pay-uuid" });
+    await pending;
+
+    expect(isPaystackPopupOpen()).toBe(false);
+  });
+
+  it("closes on a dismissal, so the fan gets a normal dialog back", async () => {
+    resumeBehaviour = (_code, options) => {
+      options.onLoad?.({});
+      options.onCancel?.();
+    };
+
+    await openPaystackCheckout({ accessCode: "ac_1", checkoutUrl: HOSTED, returnUrl: RETURN });
+
+    expect(isPaystackPopupOpen()).toBe(false);
+  });
+
+  it("closes on a provider failure", async () => {
+    resumeBehaviour = (_code, options) => {
+      options.onLoad?.({});
+      options.onError?.({ message: "Card declined" });
+    };
+
+    await openPaystackCheckout({ accessCode: "ac_1", checkoutUrl: HOSTED }, { onError: vi.fn() });
+
+    expect(isPaystackPopupOpen()).toBe(false);
+  });
+
+  it("closes when the popup never appears and the fan is sent to the hosted page", async () => {
+    resumeBehaviour = () => {};
+
+    const pending = openPaystackCheckout({ accessCode: "ac_1", checkoutUrl: HOSTED, returnUrl: RETURN });
+    await vi.advanceTimersByTimeAsync(5000);
+    await pending;
+
+    expect(isPaystackPopupOpen()).toBe(false);
+  });
+
+  it("closes when resumeTransaction throws before the popup exists", async () => {
+    resumeBehaviour = () => {
+      throw new Error("popup blew up");
+    };
+
+    await openPaystackCheckout({ accessCode: "ac_1", checkoutUrl: HOSTED, returnUrl: RETURN });
+
+    expect(isPaystackPopupOpen()).toBe(false);
+  });
+});

package/src/utils/paystackCheckout.ts

@@ -129,6 +129,45 @@ const modalIsPresent = (): boolean => {
   });
 };
 
+/**
+ * Is a Paystack popup on screen right now?
+ *
+ * Paystack appends its overlay to `document.body`, which puts it OUTSIDE any
+ * dialog the pay button was rendered in. A modal dialog is built to make
+ * exactly that unreachable: Radix sets `pointer-events: none` on the body and
+ * traps focus inside its own content, so the popup renders on top, looks
+ * usable, and swallows every click. A fan on a code website could not pay for
+ * tickets, a course, a coaching slot, a film, a donation or an offer, because
+ * all six open Paystack from inside a dialog.
+ *
+ * So the popup announces itself and the dialog primitives get out of the way
+ * (`ui/headless/dialog.tsx`). It is published from HERE rather than from a
+ * React module because this file is the one funnel every pillar already goes
+ * through, and a second place that knows when the popup is up is a second place
+ * to forget to clear it.
+ */
+let popupOpen = false;
+const popupListeners = new Set<() => void>();
+
+/** For `useSyncExternalStore`, and for anything else that needs the answer now. */
+export function isPaystackPopupOpen(): boolean {
+  return popupOpen;
+}
+
+/** Subscribe to popup open/close. Returns the unsubscribe. */
+export function subscribeToPaystackPopup(listener: () => void): () => void {
+  popupListeners.add(listener);
+  return () => {
+    popupListeners.delete(listener);
+  };
+}
+
+const setPopupOpen = (next: boolean): void => {
+  if (popupOpen === next) return;
+  popupOpen = next;
+  for (const listener of popupListeners) listener();
+};
+
 const errorMessageOf = (error: unknown): string | undefined => {
   if (typeof error === "string") return error;
   const message = (error as { message?: unknown } | null)?.message;
@@ -222,6 +261,10 @@ export async function openPaystackCheckout(
       if (settled) return false;
       settled = true;
       stopWatching();
+      // Every terminal outcome passes through here, which is what makes "the
+      // popup is up" impossible to leave stuck on: paid, dismissed, failed and
+      // fell-back-to-the-hosted-page all clear it.
+      setPopupOpen(false);
       resolve(outcome);
       return true;
     };
@@ -237,6 +280,10 @@ export async function openPaystackCheckout(
     };
 
     try {
+      // Announced BEFORE the iframe exists, not on `onLoad`. The dialog around
+      // the pay button has to have released the page by the time the popup is
+      // painted, and a fan taps the first card field the instant they see it.
+      setPopupOpen(true);
       new PaystackPop().resumeTransaction(accessCode, {
         onSuccess: (transaction) => succeed(transaction ?? {}),
         // Closing the popup leaves the charge exactly where it was. Nothing is