@tribe-nest/forge 3.58.0 → 3.60.0

package/src/ui/headless/communities/useCommunityUpgrade.ts

@@ -0,0 +1,213 @@
+import { useCallback, useMemo, useState } from "react";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import {
+  useCommunityUpgradePreview,
+  useInvalidateCommunities,
+  useUpgradeCommunityTier,
+  type CommunityUpgradeResult,
+  type CommunityUpgradeTier,
+  type PublicTier,
+} from "../../../data/queries/useCommunities";
+import {
+  hasPaystackSession,
+  openPaystackCheckout as openPaystackModal,
+  type PaystackCheckoutOutcome,
+  type PaystackCheckoutSession,
+} from "../../../utils/paystackCheckout";
+import { useCommunity } from "./useCommunity";
+import { communityHomePath } from "./paths";
+
+/**
+ * Where the upgrade sheet is.
+ *
+ *   choose      the tiers above the current one
+ *   confirm     one tier chosen: its price now (prorated on Stripe) or the
+ *               warning that the card is collected again (Paystack)
+ *   submitting  the upgrade request is in flight
+ *   payment     the provider needs the card: a Stripe secret to confirm, or a
+ *               Paystack checkout to open
+ *   done        upgraded
+ */
+export type CommunityUpgradeStep = "choose" | "confirm" | "submitting" | "payment" | "done";
+
+export interface UseCommunityUpgradeOptions {
+  /** Where the provider returns after a card payment. Default: the community home with `confirmSubscription=1`. */
+  returnPath?: string;
+  /**
+   * Called once the upgrade is complete. Omitted, the fan is sent to the
+   * community home (`navigate`, or a full-page visit).
+   */
+  onUpgraded?: (result: { requiresConfirmation: boolean; path: string }) => void;
+  /** The host's router, used for the default landing. */
+  navigate?: (href: string) => void;
+  /** Open with this tier chosen (a locked item's "Unlock with {tier}"). */
+  initialTierId?: string | null;
+}
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+export interface CommunityUpgradeOption extends CommunityUpgradeTier {
+  /** The full tier (benefits, description) when the community read carried it. */
+  tier: PublicTier | null;
+}
+
+/**
+ * The upgrade sheet: only the tiers ABOVE the viewer's current one in this
+ * community, the price of moving now, and `upgrade(tierId)`.
+ *
+ * Provider differences live here, not in markup:
+ *
+ * - **Stripe**: one tap on the saved card. The server swaps the price with
+ *   proration and the answer is `changed`, with nothing to pay here. If the
+ *   bank asks for authentication, the answer is `requires_payment` with a
+ *   secret to confirm.
+ * - **Paystack**: the provider cannot swap a price, so the subscription is
+ *   cancelled and recreated and the card is collected again (decision 10).
+ *   `requiresCard` is true from the preview, so the sheet says so BEFORE the fan
+ *   confirms, and the answer carries a checkout to open.
+ */
+export function useCommunityUpgrade(opts: UseCommunityUpgradeOptions = {}) {
+  const context = useOptionalCommunityContext();
+  if (!context) throw new MissingCommunityProviderError("useCommunityUpgrade()");
+  const community = useCommunity();
+  const ref = community.slug ?? context.slug ?? context.ref;
+  const slug = community.slug ?? context.slug;
+  const mutation = useUpgradeCommunityTier(ref);
+  const invalidate = useInvalidateCommunities();
+
+  const [selectedTierId, setSelectedTierId] = useState<string | null>(opts.initialTierId ?? null);
+  const [result, setResult] = useState<CommunityUpgradeResult | null>(null);
+  const [paystackSession, setPaystackSession] = useState<PaystackCheckoutSession | null>(null);
+  const [done, setDone] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const preview = useCommunityUpgradePreview(ref, selectedTierId ?? undefined);
+
+  const options: CommunityUpgradeOption[] = useMemo(
+    () =>
+      community.upgradeTiers.map((option) => ({
+        ...option,
+        tier: community.tiers.find((tier) => tier.id === option.id) ?? null,
+      })),
+    [community.upgradeTiers, community.tiers],
+  );
+  const selected = options.find((option) => option.id === selectedTierId) ?? null;
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const returnPath = opts.returnPath ?? (slug ? communityHomePath(slug, { confirmSubscription: 1 }) : "");
+  const landingPath = slug ? communityHomePath(slug) : returnPath;
+
+  const land = useCallback(
+    (requiresConfirmation: boolean) => {
+      setDone(true);
+      void invalidate();
+      const path = requiresConfirmation ? returnPath : landingPath;
+      if (opts.onUpgraded) return opts.onUpgraded({ requiresConfirmation, path });
+      if (opts.navigate) return opts.navigate(path);
+      if (typeof window !== "undefined" && path) window.location.assign(`${origin}${path}`);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [returnPath, landingPath, origin, opts.onUpgraded, opts.navigate],
+  );
+
+  const upgrade = async (tierId?: string) => {
+    const target = tierId ?? selectedTierId;
+    setError(null);
+    if (!target) {
+      setError("Choose a tier to upgrade to.");
+      return;
+    }
+    setSelectedTierId(target);
+    try {
+      const data = await mutation.mutateAsync({ membershipTierId: target, returnUrl: `${origin}${returnPath}` });
+      setResult(data);
+      if (data.status === "changed") {
+        land(false);
+        return;
+      }
+      if (data.accessCode || data.checkoutUrl) {
+        const session: PaystackCheckoutSession = {
+          accessCode: data.accessCode,
+          checkoutUrl: data.checkoutUrl,
+          returnUrl: `${origin}${returnPath}`,
+        };
+        setPaystackSession(session);
+        void openPaystackModal(session, {
+          onDismiss: () => {},
+          onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
+        });
+      }
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  const step: CommunityUpgradeStep = done
+    ? "done"
+    : mutation.isPending
+      ? "submitting"
+      : result?.status === "requires_payment" && (result.clientSecret || hasPaystackSession(paystackSession))
+        ? "payment"
+        : selectedTierId
+          ? "confirm"
+          : "choose";
+
+  return {
+    step,
+    isLoading: community.isLoading,
+    /** Only the tiers above the current one. Empty means there is nothing to upgrade to. */
+    options,
+    currentTier: community.currentTier,
+    currentTierName: community.membership?.tierName ?? null,
+    selectedTierId,
+    selected,
+    /** Pick a tier (moves to `confirm`). */
+    select: (tierId: string) => {
+      setError(null);
+      setResult(null);
+      setPaystackSession(null);
+      setSelectedTierId(tierId);
+    },
+    /** Back to the list. */
+    back: () => {
+      setError(null);
+      setResult(null);
+      setPaystackSession(null);
+      setSelectedTierId(null);
+    },
+    /** What moving now costs, once a tier is chosen. */
+    preview: preview.data ?? null,
+    previewLoading: !!selectedTierId && preview.isLoading,
+    /** True on Paystack: the card is collected again and the subscription replaced. Say so before confirming. */
+    requiresCard: preview.data?.requiresCard ?? false,
+    prorated: preview.data?.prorated ?? false,
+    upgrade,
+    isSubmitting: mutation.isPending,
+    error,
+    /** STRIPE: the secret to confirm on the payment step. */
+    clientSecret: result?.clientSecret,
+    /** PAYSTACK: the upgrade's checkout is open or can be re-opened. */
+    isPaystack: !!paystackSession,
+    canOpenPaystack: hasPaystackSession(paystackSession),
+    openPaystackCheckout: (): Promise<PaystackCheckoutOutcome> =>
+      paystackSession
+        ? openPaystackModal(paystackSession, {
+            onDismiss: () => {},
+            onError: (message) => setError(message ?? "The payment could not be completed. Please try again."),
+          })
+        : Promise.resolve("unavailable" as PaystackCheckoutOutcome),
+    /** The renderer's `returnUrl` for the payment step. */
+    returnUrl: `${origin}${returnPath}`,
+    /** Call once the card renderer reports success. Lands on the community home to reconcile. */
+    onPaymentSucceeded: () => land(true),
+    /** Clear everything, e.g. when the sheet closes. */
+    reset: () => {
+      setError(null);
+      setResult(null);
+      setPaystackSession(null);
+      setSelectedTierId(null);
+      setDone(false);
+    },
+  };
+}

package/src/ui/headless/communities/useMyMemberships.ts

@@ -0,0 +1,59 @@
+import { useMemo } from "react";
+import { useMyCommunityMemberships, type MyCommunityMembership } from "../../../data/queries/useCommunities";
+import { getMembershipAccess, type MembershipAccessSummary } from "../../../utils/membershipAccess";
+import { communityHomePath } from "./paths";
+import { isMembershipInTrial } from "../membership/membershipTrial";
+
+export interface MyMembershipEntry {
+  id: string;
+  community: { id: string; name: string; slug: string };
+  tierId: string | null;
+  tierName: string;
+  status: string;
+  access: MembershipAccessSummary;
+  /** When the paid period ends: a renewal, or the last day when cancelling. */
+  periodEnd: string | null;
+  cancelAtPeriodEnd: boolean;
+  pendingDowngradeTierId: string | null;
+  trialEndsAt: string | null;
+  /** Inside a free trial right now: nothing charged yet, the first charge on `trialEndsAt`. */
+  inTrial: boolean;
+  amount: number | null;
+  currency: string | null;
+  billingCycle: string | null;
+  /** The community home, where the fan manages this membership. */
+  homePath: string;
+}
+
+/** Normalise one `/public/memberships/mine` row. Pure, for the spec and for a custom list. */
+export function toMyMembershipEntry(row: MyCommunityMembership): MyMembershipEntry {
+  const cancelAtPeriodEnd = !!row.cancelAtPeriodEnd;
+  return {
+    id: row.id,
+    community: row.community,
+    tierId: row.tierId ?? row.membershipTierId ?? row.membershipTier?.id ?? null,
+    tierName: row.tierName ?? row.membershipTier?.name ?? "",
+    status: row.status,
+    access: getMembershipAccess({ status: row.status, cancelAtPeriodEnd }),
+    periodEnd: row.currentPeriodEnd ?? row.endDate ?? null,
+    cancelAtPeriodEnd,
+    pendingDowngradeTierId: row.pendingDowngradeTierId ?? null,
+    trialEndsAt: row.trialEndsAt ?? null,
+    inTrial: isMembershipInTrial({ trialEndsAt: row.trialEndsAt ?? null }),
+    amount: row.subscriptionAmount ?? null,
+    currency: row.subscriptionCurrency ?? null,
+    billingCycle: row.billingCycle ?? null,
+    homePath: communityHomePath(row.community.slug),
+  };
+}
+
+/**
+ * Every membership the signed-in fan holds with this creator, one per
+ * community, for the account page's "My memberships". Nothing sends a fan
+ * here: managing a membership happens inside its community.
+ */
+export function useMyMemberships() {
+  const query = useMyCommunityMemberships();
+  const memberships = useMemo(() => (query.data ?? []).map(toMyMembershipEntry), [query.data]);
+  return { memberships, isLoading: query.isLoading, isError: query.isError, refetch: query.refetch };
+}

package/src/ui/headless/community/useCommunityAttachmentUpload.ts

@@ -1,6 +1,7 @@
 import axios from "axios";
 import { useCallback, useRef, useState } from "react";
 import { useForge } from "../../../provider/ForgeProvider";
+import { useOptionalCommunityContext } from "../../../contexts/CommunityContext";
 import { attachmentKind, type AttachmentKind } from "../chat/attachmentKind";
 import type { CommunityAttachmentInput } from "../../../data/queries/useCommunity";
 
@@ -31,11 +32,14 @@ const toApiType = (kind: AttachmentKind): CommunityAttachmentInput["type"] => {
 /**
  * Headless attachment composer for community posts/replies: stage local files
  * (with previews), upload to R2 via the member-scoped presigned endpoint
- * (POST /public/community/attachments/presigned-url — same flow as chat's
+ * (POST /public/community/attachments/presigned-url: same flow as chat's
  * useChatAttachmentUpload), and hand back `CommunityAttachmentInput[]`.
  */
 export function useCommunityAttachmentUpload() {
   const { client, profileId } = useForge();
+  // The community the attachment is posted into, when there is one. Soft: the
+  // composer also serves course spaces, which belong to no community.
+  const communityId = useOptionalCommunityContext()?.communityId;
   const [pending, setPending] = useState<PendingCommunityAttachment[]>([]);
   const [error, setError] = useState<string | null>(null);
   const pendingRef = useRef<PendingCommunityAttachment[]>([]);
@@ -96,7 +100,7 @@ export function useCommunityAttachmentUpload() {
       try {
         const { data } = await client.post<{ presignedUrl: string; remoteUrl: string }>(
           "/public/community/attachments/presigned-url",
-          { fileName: item.file.name, profileId },
+          { fileName: item.file.name, profileId, ...(communityId ? { communityId } : {}) },
         );
         await axios.put(data.presignedUrl, item.file, {
           headers: { "Content-Type": item.file.type || "application/octet-stream" },
@@ -121,7 +125,7 @@ export function useCommunityAttachmentUpload() {
     }
 
     return uploaded;
-  }, [client, profileId, patch]);
+  }, [client, profileId, communityId, patch]);
 
   return {
     pending,

package/src/ui/headless/index.ts

@@ -3,7 +3,11 @@
 export * from "./dialog";
 export * from "./donation";
 export * from "./offer";
-export { MembershipGate, type MembershipGateProps, type MembershipGateState } from "./membership/MembershipGate";
+// Communities: the provider every member-content hook reads, and the headless
+// pages (list, About, join, invite, pending, upgrade, membership, gate).
+// `CommunityGate` replaces the old `MembershipGate`, whose "any membership on
+// the profile" rule is exactly what several communities make wrong.
+export * from "./communities";
 // S.4 members-only gates: the notice a storefront draws BEFORE the buyer pays.
 export { useMembershipGateNotice, type UseMembershipGateNoticeInput } from "./membership/useMembershipGateNotice";
 export { useEmailListForm, type UseEmailListFormOptions, type FormStatus } from "./forms/useEmailListForm";
@@ -27,7 +31,7 @@ export {
   type CheckoutShippingData,
   type SelectedShippingRate,
 } from "./checkout/useCheckout";
-// Inventory holds — the reservation a buyer is given while they pay, and the
+// 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";
 // Cart recovery: what a resume link does when the buyer clicks it. Shared so
@@ -58,7 +62,7 @@ export {
 export { useLoginFlow, type LoginStep } from "./auth/useLoginFlow";
 export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
 
-// Flow primitives (Part A2) — multi-step purchase/booking/subscribe/chat flows,
+// Flow primitives (Part A2): multi-step purchase/booking/subscribe/chat flows,
 // each composed from the data hooks so a creator can rebuild any page.
 export {
   useEventCheckout,
@@ -196,7 +200,7 @@ export * from "./document";
 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
+// Funnel instrumentation: wrap a multi-step flow to record step-through and
 // drop-off on the first-party analytics feed.
 export * from "./funnel";
 export * from "./useVariantSelection";

package/src/ui/headless/memberHome/index.ts

@@ -1,4 +1,4 @@
-// Unified member home (`/i/members`) — headless nav model.
+// A community's member home (`/i/communities/<slug>/home`): the headless nav model.
 export {
   useMemberHomeNav,
   type MemberHomeNavItem,

package/src/ui/headless/memberHome/useMemberHomeNav.ts

@@ -3,29 +3,34 @@ import { useGetPostCollections } from "../../../data/queries/usePostCollections"
 import { useCommunitySpaces } from "../../../data/queries/useCommunity";
 import { useChatChannels } from "../../../data/queries/useChat";
 import { useMyMembershipCalls } from "../../../data/queries/useMembershipCalls";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { internalPath } from "../../../runtime/pages";
 
-export type MemberHomeNavKey = "posts" | "collections" | "spaces" | "calendar" | "chat" | "membership";
+export type MemberHomeNavKey = "posts" | "collections" | "spaces" | "calendar" | "chat" | "leaderboard" | "notifications";
 
 export interface MemberHomeNavItem {
   key: MemberHomeNavKey;
   label: string;
   /** Absolute in-site href (already run through `buildHref` when supplied). */
   href: string;
-  /** Conditional tabs (Collections/Spaces/Calendar/Chat) are hidden until the profile has content for them. */
+  /** Conditional tabs (Collections/Spaces/Calendar/Chat/Leaderboard/Notifications) hide until the community has content for them. */
   visible: boolean;
-  /** Whether `currentPath` falls inside this tab. */
+  /** Whether `currentPath` (or `activeKey`) falls on this tab. */
   active: boolean;
-  /** True for "My membership" — a deep link out of the member home (account membership tab). */
+  /** Kept for hosts that drew an out-of-home marker. Always false: every tab is inside the community. */
   external: boolean;
 }
 
 export interface UseMemberHomeNavOptions {
   /** Current location pathname, used to compute `active`. */
   currentPath?: string;
-  /** Member home base path (default `/i/members` — identical in both renderers). */
+  /** The active tab, when the host knows it (wins over `currentPath`). */
+  activeKey?: MemberHomeNavKey | null;
+  /**
+   * Member home base path. Default: the surrounding community's home,
+   * `/i/communities/<slug>/home`.
+   */
   basePath?: string;
-  /** "My membership" target. Client: `/account?tab=membership` (default). Site-starter: `/i/account?tab=membership`. */
-  membershipHref?: string;
   /** Optional href transform (e.g. locale prefixes). Applied to every item. */
   buildHref?: (href: string) => string;
 }
@@ -36,17 +41,21 @@ const normalize = (p: string) => {
 };
 
 /**
- * Headless nav model for the unified member home (`/i/members`). Tab
- * visibility derives client-side from queries the pages already need (cache
- * shared via React Query): Posts is always visible; Collections appears when
- * the profile has any post collections; Spaces when any community spaces are
- * accessible; Chat when any chat channels are accessible; "My membership" is
- * always visible and deep-links out to the account membership tab. Hosts own
- * routing — pair with any layout via `href`/`active`.
+ * Headless nav model for a community's member home
+ * (`/i/communities/<slug>/home`). Tab visibility derives client-side from the
+ * queries the pages already need (cache shared via React Query), all scoped to
+ * the surrounding `<CommunityProvider>`: Posts is always visible; Collections
+ * when the community has any; Spaces (with its Leaderboard and Notifications)
+ * when any space is accessible; Chat when any channel is; Calendar when any
+ * call is. Billing, cancel and downgrade live in the community header's
+ * Membership menu, not here, and nothing links to the account page. Hosts own
+ * routing: pair with any layout via `href`/`active`.
  */
 export function useMemberHomeNav(opts: UseMemberHomeNavOptions = {}) {
-  const basePath = opts.basePath ?? "/i/members";
-  const membershipHref = opts.membershipHref ?? "/account?tab=membership";
+  const community = useOptionalCommunityContext();
+  if (!community) throw new MissingCommunityProviderError("useMemberHomeNav()");
+  const slug = community.slug;
+  const basePath = opts.basePath ?? (slug ? internalPath("communities/$slug/home", { slug }) : "");
   const buildHref = opts.buildHref ?? ((href: string) => href);
   const currentPath = normalize(opts.currentPath ?? "");
 
@@ -54,21 +63,12 @@ export function useMemberHomeNav(opts: UseMemberHomeNavOptions = {}) {
   const spacesQ = useCommunitySpaces();
   const channelsQ = useChatChannels();
   /**
-   * Upcoming calls this member may join. Already filtered by the server against
-   * their membership, so a non-empty list IS the visibility rule - there is no
-   * second "can they get in" check to make here, and no way for the tab to
-   * appear over an empty page.
-   */
-  /**
-   * ANY call this viewer may see, ever - not just an upcoming one.
-   *
-   * The Calendar is a month you can page backwards through, so it has something
-   * to show from the moment the creator has ever run a call. Keying the tab on
-   * upcoming calls alone hid the whole history the hour the last one ended,
-   * which is precisely when somebody goes looking for the recording.
-   *
-   * `limit: 1` because this is an existence check: the calendar fetches its own
-   * window, and the answer here is only "draw the tab or not".
+   * ANY call this viewer may see in this community, ever - not just an
+   * upcoming one. The Calendar is a month you can page backwards through, so
+   * it has something to show from the moment the creator has ever run a call.
+   * Keying the tab on upcoming calls alone hid the whole history the hour the
+   * last one ended, which is precisely when somebody goes looking for the
+   * recording. `limit: 1` because this is an existence check.
    */
   const callsQ = useMyMembershipCalls({ from: new Date(0), limit: 1 });
 
@@ -80,27 +80,29 @@ export function useMemberHomeNav(opts: UseMemberHomeNavOptions = {}) {
   const items: MemberHomeNavItem[] = useMemo(() => {
     const isUnder = (segment: string) =>
       currentPath === normalize(`${basePath}/${segment}`) || currentPath.startsWith(normalize(`${basePath}/${segment}`) + "/");
-    const defs: Array<Omit<MemberHomeNavItem, "href" | "active"> & { path: string; active: boolean }> = [
-      { key: "posts", label: "Posts", path: basePath, visible: true, external: false, active: currentPath === normalize(basePath) },
-      { key: "collections", label: "Collections", path: `${basePath}/collections`, visible: hasCollections, external: false, active: isUnder("collections") },
-      { key: "spaces", label: "Spaces", path: `${basePath}/spaces`, visible: hasSpaces, external: false, active: isUnder("spaces") },
+    const onKey = (key: MemberHomeNavKey, byPath: boolean) => (opts.activeKey !== undefined ? opts.activeKey === key : byPath);
+    const defs: Array<Omit<MemberHomeNavItem, "href"> & { path: string }> = [
+      // The home itself is the posts feed; `home/posts` is the same tab.
+      { key: "posts", label: "Posts", path: basePath, visible: true, external: false, active: onKey("posts", currentPath === normalize(basePath) || isUnder("posts")) },
+      { key: "collections", label: "Collections", path: `${basePath}/collections`, visible: hasCollections, external: false, active: onKey("collections", isUnder("collections")) },
+      { key: "spaces", label: "Spaces", path: `${basePath}/spaces`, visible: hasSpaces, external: false, active: onKey("spaces", isUnder("spaces") || isUnder("profile")) },
       // Scheduled calls. Sits above Chat because a call has a TIME on it: it is
       // the one tab whose content stops being useful if it is found late.
-      { key: "calendar", label: "Calendar", path: `${basePath}/calendar`, visible: hasCalls, external: false, active: isUnder("calendar") },
-      { key: "chat", label: "Chat", path: `${basePath}/chat`, visible: hasChannels, external: false, active: isUnder("chat") },
-      { key: "membership", label: "My membership", path: membershipHref, visible: true, external: true, active: false },
+      { key: "calendar", label: "Calendar", path: `${basePath}/calendar`, visible: hasCalls, external: false, active: onKey("calendar", isUnder("calendar")) },
+      { key: "chat", label: "Chat", path: `${basePath}/chat`, visible: hasChannels, external: false, active: onKey("chat", isUnder("chat")) },
+      { key: "leaderboard", label: "Leaderboard", path: `${basePath}/leaderboard`, visible: hasSpaces, external: false, active: onKey("leaderboard", isUnder("leaderboard")) },
+      { key: "notifications", label: "Notifications", path: `${basePath}/notifications`, visible: hasSpaces, external: false, active: onKey("notifications", isUnder("notifications")) },
     ];
     return defs.map(({ path, ...d }) => ({ ...d, href: buildHref(path) }));
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [basePath, membershipHref, currentPath, hasCollections, hasSpaces, hasCalls, hasChannels]);
+  }, [basePath, currentPath, opts.activeKey, hasCollections, hasSpaces, hasCalls, hasChannels]);
 
   return {
     items,
-    /** Visible items only — what a shell actually renders. */
+    /** Visible items only: what a shell actually renders. */
     visibleItems: items.filter((i) => i.visible),
     activeKey: items.find((i) => i.active)?.key ?? null,
     /** True once every visibility query has settled (avoids tab flash). */
-    isReady:
-      !collectionsQ.isLoading && !spacesQ.isLoading && !callsQ.isLoading && !channelsQ.isLoading,
+    isReady: !!basePath && !collectionsQ.isLoading && !spacesQ.isLoading && !callsQ.isLoading && !channelsQ.isLoading,
   };
 }

package/src/ui/headless/membership/_tests/membershipCheckoutRefetch.spec.tsx

@@ -43,6 +43,14 @@ vi.mock("../../../../data/queries/useMembership", async (importOriginal) => ({
   useConfirmMembershipApplication: () => ({ mutateAsync: vi.fn(), isPending: false }),
 }));
 
+// Outside a community there is no viewer state to read (the hook falls back to
+// `user.membership`); stubbed like the other queries, since this spec renders
+// without a Forge provider.
+vi.mock("../../../../data/queries/useCommunities", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../data/queries/useCommunities")>()),
+  useCommunityViewerState: () => ({ data: undefined, isLoading: false }),
+}));
+
 vi.mock("../../../../data/queries/useSubscriptions", async (importOriginal) => ({
   ...(await importOriginal<typeof import("../../../../data/queries/useSubscriptions")>()),
   useCreateSubscription: () => ({ mutateAsync: subscriptions.createPaid, isPending: false }),

package/src/ui/headless/membership/_tests/useMembershipCheckoutApplication.spec.tsx

@@ -87,7 +87,7 @@ beforeEach(() => {
   api.createFree.mockResolvedValue({});
   api.createPaid.mockReset();
   auth.refetchUser.mockClear();
-  window.history.replaceState(null, "", "/i/membership/checkout");
+  window.history.replaceState(null, "", "/i/communities/fan-club");
 });
 
 const onComplete = vi.fn();
@@ -214,13 +214,14 @@ describe("application tiers: subscribe() applies", () => {
 
 describe("invite tokens", () => {
   it("reads the invite off the url and forwards it to the tier list and the paid subscribe", async () => {
-    window.history.replaceState(null, "", "/i/membership/checkout?membershipTierId=tier-1&invite=tok-abc");
+    window.history.replaceState(null, "", "/i/communities/fan-club?tier=tier-1&invite=tok-abc");
     tiers = [tier({ priceMonthly: 12, joinMode: "invite" })];
     api.createPaid.mockResolvedValue({ requiresPayment: true, clientSecret: "pi_1_secret_2" });
     const { result } = renderHook(() => useMembershipCheckout({ initialTierId: "tier-1" }));
 
     expect(result.current.inviteToken).toBe("tok-abc");
-    expect(api.tiersOptions.at(-1)).toEqual({ inviteToken: "tok-abc" });
+    // `enabled` is on because this checkout was handed no tier list of its own.
+    expect(api.tiersOptions.at(-1)).toEqual({ inviteToken: "tok-abc", enabled: true });
     await act(async () => {
       await result.current.subscribe();
     });
@@ -247,7 +248,7 @@ describe("invite tokens", () => {
       await result.current.subscribe();
     });
 
-    expect(api.tiersOptions.at(-1)).toEqual({ inviteToken: null });
+    expect(api.tiersOptions.at(-1)).toEqual({ inviteToken: null, enabled: true });
     expect(api.createFree.mock.calls[0][0]).not.toHaveProperty("inviteToken");
   });
 });

package/src/ui/headless/membership/_tests/useMembershipCheckoutQuestionnaire.spec.tsx

@@ -75,7 +75,7 @@ beforeEach(() => {
   api.createFree.mockResolvedValue({});
   api.createPaid.mockReset();
   onComplete.mockClear();
-  window.history.replaceState(null, "", "/i/membership/checkout");
+  window.history.replaceState(null, "", "/i/communities/fan-club");
 });
 
 function answerRequired(result: { current: ReturnType<typeof useMembershipCheckout> }) {

package/src/ui/headless/membership/_tests/useMembershipCheckoutTrial.spec.tsx

@@ -61,7 +61,7 @@ beforeEach(() => {
   api.createPaid.mockReset();
   onComplete.mockReset();
   auth.user.membership = undefined;
-  window.history.replaceState(null, "", "/i/membership/checkout");
+  window.history.replaceState(null, "", "/i/communities/fan-club");
 });
 
 describe("useMembershipCheckout: trial exposure", () => {