@tribe-nest/forge 3.59.0 → 3.60.0

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

@@ -0,0 +1,286 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { communityJoinOffer, useCommunities, useCommunity } from "../communities/useCommunity";
+import { useCommunityAbout } from "../communities/useCommunityAbout";
+import { useCommunityHome } from "../communities/useCommunityHome";
+import { toMyMembershipEntry, useMyMemberships } from "../communities/useMyMemberships";
+import { useMemberHomeNav } from "../memberHome/useMemberHomeNav";
+import {
+  COMMUNITY,
+  OTHER_COMMUNITY,
+  account,
+  calls,
+  detailRoute,
+  get,
+  installAdapter,
+  meRoute,
+  post,
+  restoreAdapter,
+  tier,
+  viewer,
+  wrapper,
+} from "./communityHarness";
+
+/**
+ * The read side of a community: the list, one community and where the viewer
+ * stands in it, the About page's one action, the home shell (reconciling a
+ * Stripe return, the upgrade opener), the nav under the community home, and
+ * the account page's memberships across communities.
+ */
+
+afterEach(restoreAdapter);
+
+const free = tier({ id: "tier-free", name: "Free" });
+const paid = tier({ id: "tier-paid", priceMonthly: 12 });
+const yearly = tier({ id: "tier-yearly", priceYearly: 60 });
+const apply = tier({ id: "tier-apply", joinMode: "application" });
+
+const member = viewer({
+  state: "member",
+  membership: { id: "m-1", tierId: "tier-paid", tierName: "Paid", status: "active", cancelAtPeriodEnd: false, currentPeriodEnd: null, pendingDowngradeTierId: null },
+  upgradeTiers: [{ id: "tier-gold", name: "Gold", priceMonthly: 30, priceYearly: null }],
+  canInteract: true,
+});
+
+describe("communityJoinOffer (the About page's Join button)", () => {
+  it("Join free when a free tier exists", () => {
+    expect(communityJoinOffer([paid, free])).toMatchObject({ kind: "free", tier: { id: "tier-free" } });
+  });
+  it("otherwise the lowest price, compared per month", () => {
+    expect(communityJoinOffer([paid, yearly])).toMatchObject({ kind: "paid", tier: { id: "tier-yearly" }, amount: 60, cycle: "year" });
+  });
+  it("Apply when every tier is apply-to-join, and nothing with no tiers", () => {
+    expect(communityJoinOffer([apply])).toMatchObject({ kind: "apply" });
+    expect(communityJoinOffer([])).toBeNull();
+  });
+});
+
+describe("useCommunities", () => {
+  it("lists the profile's communities and names the only one", async () => {
+    installAdapter([get("/public/communities", () => [COMMUNITY])]);
+    const { result } = renderHook(() => useCommunities(), { wrapper: wrapper({ community: null }) });
+    await waitFor(() => expect(result.current.communities).toHaveLength(1));
+    expect(result.current.only?.slug).toBe("fan-club");
+    expect(calls("get", "/public/communities")[0].params).toEqual({ profileId: "profile-1" });
+  });
+  it("names none when there are several", async () => {
+    installAdapter([get("/public/communities", () => [COMMUNITY, OTHER_COMMUNITY])]);
+    const { result } = renderHook(() => useCommunities(), { wrapper: wrapper({ community: null }) });
+    await waitFor(() => expect(result.current.communities).toHaveLength(2));
+    expect(result.current.only).toBeNull();
+  });
+});
+
+describe("useCommunity", () => {
+  it("an anonymous visitor: the community, its tiers, and the offer", async () => {
+    installAdapter([detailRoute(() => ({ tiers: [free, paid], viewer: viewer({ state: "anonymous" }) }))]);
+    const { result } = renderHook(() => useCommunity(), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.tiers).toHaveLength(2));
+    expect(result.current.viewer?.state).toBe("anonymous");
+    expect(result.current.isMember).toBe(false);
+    expect(result.current.joinOffer?.kind).toBe("free");
+    expect(calls("get", /\/me$/)).toHaveLength(0);
+  });
+
+  it("a signed-in member: the viewer comes from /me, with the tier and the upgrade", async () => {
+    installAdapter([meRoute(() => member), detailRoute(() => ({ tiers: [free, paid] }))]);
+    const { result } = renderHook(() => useCommunity(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.isMember).toBe(true));
+    expect(result.current.currentTier?.id).toBe("tier-paid");
+    expect(result.current.hasUpgrade).toBe(true);
+    expect(result.current.canInteract).toBe(true);
+  });
+
+  it("pending: inside, no access, with the date applied", async () => {
+    const pending = viewer({ state: "pending", application: { id: "a-1", tierId: "tier-apply", status: "pending", createdAt: "2026-09-20T00:00:00.000Z" } });
+    installAdapter([meRoute(() => pending), detailRoute(() => ({ tiers: [apply] }))]);
+    const { result } = renderHook(() => useCommunity(), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.isPending).toBe(true));
+    expect(result.current.isMember).toBe(false);
+    expect(result.current.pendingSince).toBe("2026-09-20T00:00:00.000Z");
+  });
+
+  it("an unknown community is notFound", async () => {
+    installAdapter([
+      get(/^\/public\/communities\/[^/]+$/, () => {
+        throw { status: 404 };
+      }),
+    ]);
+    const { result } = renderHook(() => useCommunity("nope"), { wrapper: wrapper({ community: null }) });
+    await waitFor(() => expect(result.current.notFound).toBe(true));
+  });
+});
+
+describe("useCommunityAbout", () => {
+  it("Join opens the sheet in place on a visitor, on the tier asked for", async () => {
+    installAdapter([detailRoute(() => ({ tiers: [free, paid] }))]);
+    const { result } = renderHook(() => useCommunityAbout({ tierId: "tier-paid" }), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.tiers).toHaveLength(2));
+    expect(result.current.action).toBe("join");
+    expect(result.current.sheetOpen).toBe(false);
+    act(() => result.current.primary());
+    expect(result.current.sheetOpen).toBe(true);
+    expect(result.current.sheetTierId).toBe("tier-paid");
+  });
+
+  it("an invite or a shareable link opens the sheet straight away", async () => {
+    installAdapter([detailRoute(() => ({ tiers: [free] }))]);
+    const invite = renderHook(() => useCommunityAbout({ invite: "tok" }), { wrapper: wrapper() });
+    const link = renderHook(() => useCommunityAbout({ join: "link" }), { wrapper: wrapper() });
+    expect(invite.result.current.sheetOpen).toBe(true);
+    expect(link.result.current.sheetOpen).toBe(true);
+  });
+
+  it("a member goes straight inside instead of Join", async () => {
+    installAdapter([meRoute(() => member), detailRoute(() => ({ tiers: [paid] }))]);
+    const navigated: string[] = [];
+    const { result } = renderHook(() => useCommunityAbout({ navigate: (href) => navigated.push(href) }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.action).toBe("enter"));
+    act(() => result.current.primary());
+    expect(navigated).toEqual(["/i/communities/fan-club/home"]);
+    expect(result.current.sheetOpen).toBe(false);
+  });
+});
+
+describe("useCommunityHome", () => {
+  it("reconciles a Stripe return once, for THIS community, inside it", async () => {
+    installAdapter([
+      post("/public/payments/subscriptions/confirm-latest", () => ({ status: "active" })),
+      meRoute(() => member),
+      detailRoute(() => ({ tiers: [paid] })),
+    ]);
+    const { result, rerender } = renderHook(() => useCommunityHome({ confirmSubscription: true }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(calls("post", "/public/payments/subscriptions/confirm-latest")).toHaveLength(1));
+    rerender();
+    expect(calls("post", "/public/payments/subscriptions/confirm-latest")).toHaveLength(1);
+    expect(calls("post", "/public/payments/subscriptions/confirm-latest")[0].body).toEqual({
+      profileId: "profile-1",
+      communityId: COMMUNITY.id,
+    });
+    await waitFor(() => expect(result.current.confirming).toBe(false));
+  });
+
+  it("REGRESSION: stops showing Confirming under React StrictMode (dev double mount)", async () => {
+    // The confirm used to report `isPending` from the mutation observer, which
+    // StrictMode's unmount and remount detaches, so the spinner never cleared
+    // although the request answered 200.
+    installAdapter([
+      post("/public/payments/subscriptions/confirm-latest", () => ({ status: "active" })),
+      meRoute(() => member),
+      detailRoute(() => ({ tiers: [paid] })),
+    ]);
+    const { result } = renderHook(() => useCommunityHome({ confirmSubscription: true }), {
+      wrapper: wrapper({ user: account() }),
+      reactStrictMode: true,
+    });
+    await waitFor(() => expect(calls("post", "/public/payments/subscriptions/confirm-latest")).toHaveLength(1));
+    await waitFor(() => expect(result.current.confirming).toBe(false));
+    expect(calls("post", "/public/payments/subscriptions/confirm-latest")).toHaveLength(1);
+  });
+
+  it("the opener every locked item uses opens the one upgrade sheet on the tier", async () => {
+    installAdapter([meRoute(() => member), detailRoute(() => ({ tiers: [paid] }))]);
+    const { result } = renderHook(() => useCommunityHome({ welcome: true }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.isMember).toBe(true));
+    expect(result.current.showUpgrade).toBe(true);
+    expect(result.current.welcomeVisible).toBe(true);
+    act(() => result.current.opener.openUpgrade("tier-gold"));
+    expect(result.current.upgradeOpen).toBe(true);
+    expect(result.current.upgradeTierId).toBe("tier-gold");
+    act(() => result.current.dismissWelcome());
+    expect(result.current.welcomeVisible).toBe(false);
+  });
+
+  it("offers Join, not Upgrade, to a visitor", async () => {
+    installAdapter([detailRoute(() => ({ tiers: [paid], viewer: viewer({ state: "anonymous" }) }))]);
+    const { result } = renderHook(() => useCommunityHome(), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.showJoin).toBe(true));
+    expect(result.current.showUpgrade).toBe(false);
+    expect(result.current.joinPath).toBe("/i/communities/fan-club");
+  });
+});
+
+describe("useMemberHomeNav", () => {
+  it("builds every tab under the community home, and none leads to the account page", async () => {
+    installAdapter([
+      get("/public/community/spaces", () => [{ id: "s-1", name: "Space", tiers: [] }]),
+      get("/public/chat/channels", () => [{ id: "c-1", name: "General", type: "public", description: null }]),
+      get("/public/post-collections", () => ({ data: [{ id: "col-1" }], total: 1, page: 1, pageSize: 10 })),
+      get("/public/scheduled-calls/mine", () => [{ id: "call-1" }]),
+    ]);
+    const { result } = renderHook(() => useMemberHomeNav({ currentPath: "/i/communities/fan-club/home/chat" }), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.isReady).toBe(true));
+    await waitFor(() => expect(result.current.visibleItems).toHaveLength(7));
+    const hrefs = Object.fromEntries(result.current.items.map((item) => [item.key, item.href]));
+    expect(hrefs).toEqual({
+      posts: "/i/communities/fan-club/home",
+      collections: "/i/communities/fan-club/home/collections",
+      spaces: "/i/communities/fan-club/home/spaces",
+      calendar: "/i/communities/fan-club/home/calendar",
+      chat: "/i/communities/fan-club/home/chat",
+      leaderboard: "/i/communities/fan-club/home/leaderboard",
+      notifications: "/i/communities/fan-club/home/notifications",
+    });
+    expect(result.current.activeKey).toBe("chat");
+    expect(JSON.stringify(result.current.items)).not.toContain("/i/account");
+  });
+
+  it("an explicit active tab wins over the path", async () => {
+    installAdapter([]);
+    const { result } = renderHook(() => useMemberHomeNav({ activeKey: "spaces", currentPath: "/elsewhere" }), { wrapper: wrapper() });
+    expect(result.current.activeKey).toBe("spaces");
+  });
+});
+
+describe("useMyMemberships", () => {
+  it("one entry per community, each opening its own community home", async () => {
+    installAdapter([
+      // The server's real envelope: `[{ community, membership }]`
+      // (services/membership/selfServe.ts `view`), never a flat row.
+      get("/public/memberships/mine", () => [
+        {
+          community: { id: COMMUNITY.id, name: "Fan Club", slug: "fan-club" },
+          membership: { id: "m-1", communityId: COMMUNITY.id, tierId: "t-1", tierName: "Free", status: "active", amount: null, currency: null },
+        },
+        {
+          community: { id: OTHER_COMMUNITY.id, name: "Producers Circle", slug: "producers" },
+          membership: {
+            id: "m-2",
+            communityId: OTHER_COMMUNITY.id,
+            tierId: "t-9",
+            tierName: "Pro",
+            status: "past_due",
+            currentPeriodEnd: "2026-10-01T00:00:00.000Z",
+            amount: 1500,
+            currency: "USD",
+          },
+        },
+      ]),
+    ]);
+    const { result } = renderHook(() => useMyMemberships(), { wrapper: wrapper({ user: account(), community: null }) });
+    await waitFor(() => expect(result.current.memberships).toHaveLength(2));
+    expect(result.current.memberships.map((m) => m.homePath)).toEqual(["/i/communities/fan-club/home", "/i/communities/producers/home"]);
+    expect(result.current.memberships[1]).toMatchObject({
+      id: "m-2",
+      tierId: "t-9",
+      tierName: "Pro",
+      periodEnd: "2026-10-01T00:00:00.000Z",
+      amount: 1500,
+      currency: "USD",
+    });
+    expect(result.current.memberships[1].access.hasAccess).toBe(true);
+    expect(result.current.memberships[1].access.paymentFailed).toBe(true);
+  });
+
+  it("asks nothing while signed out", async () => {
+    installAdapter([]);
+    renderHook(() => useMyMemberships(), { wrapper: wrapper({ community: null }) });
+    expect(calls("get", "/public/memberships/mine")).toHaveLength(0);
+  });
+
+  it("toMyMembershipEntry reads a trial", () => {
+    const future = new Date(Date.now() + 5 * 86_400_000).toISOString();
+    expect(toMyMembershipEntry({ id: "m", status: "active", trialEndsAt: future, community: { id: "c", name: "C", slug: "c" } }).inTrial).toBe(true);
+  });
+});

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

@@ -0,0 +1,157 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { useCommunityUpgrade } from "../communities/useCommunityUpgrade";
+import { account, calls, detailRoute, get, installAdapter, meRoute, post, restoreAdapter, tier, viewer, type Route } from "./communityHarness";
+import { wrapper } from "./communityHarness";
+
+const paystack = vi.hoisted(() => ({ open: vi.fn(async () => "opened" as const) }));
+vi.mock("../../../utils/paystackCheckout", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../utils/paystackCheckout")>()),
+  openPaystackCheckout: paystack.open,
+}));
+
+/**
+ * The upgrade sheet, on both providers. Only tiers ABOVE the current one are
+ * offered; on Stripe a `changed` answer is done with nothing to pay; a bank
+ * challenge or a Paystack upgrade (cancel and recreate, card again) is a
+ * payment step, and the sheet knows `requiresCard` BEFORE the fan confirms.
+ */
+
+const HOME = "/i/communities/fan-club/home";
+let onUpgraded: ReturnType<typeof vi.fn>;
+beforeEach(() => {
+  onUpgraded = vi.fn();
+  paystack.open.mockClear();
+});
+afterEach(restoreAdapter);
+
+const basic = tier({ id: "tier-basic", name: "Basic", priceMonthly: 5 });
+const gold = tier({ id: "tier-gold", name: "Gold", priceMonthly: 20, benefits: [{ id: "b1", title: "Live calls" }] as never });
+const platinum = tier({ id: "tier-plat", name: "Platinum", priceMonthly: 50 });
+
+const member = () =>
+  viewer({
+    state: "member",
+    membership: {
+      id: "m-1",
+      tierId: "tier-basic",
+      tierName: "Basic",
+      status: "active",
+      cancelAtPeriodEnd: false,
+      currentPeriodEnd: "2026-10-27T00:00:00.000Z",
+      pendingDowngradeTierId: null,
+    },
+    upgradeTiers: [
+      { id: "tier-gold", name: "Gold", priceMonthly: 20, priceYearly: null },
+      { id: "tier-plat", name: "Platinum", priceMonthly: 50, priceYearly: null },
+    ],
+  });
+
+const base = (extra: Route[] = [], preview = { amount: 15, currency: "USD", interval: "month", requiresCard: false, prorated: true }): Route[] => [
+  ...extra,
+  get("/public/communities/fan-club/upgrade-preview", () => preview),
+  meRoute(member),
+  detailRoute(() => ({ tiers: [basic, gold, platinum] })),
+];
+
+describe("useCommunityUpgrade", () => {
+  it("offers only the tiers above the current one, enriched with the tier's benefits", async () => {
+    installAdapter(base());
+    const { result } = renderHook(() => useCommunityUpgrade({ onUpgraded }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.options).toHaveLength(2));
+    expect(result.current.options.map((option) => option.id)).toEqual(["tier-gold", "tier-plat"]);
+    expect(result.current.options[0].tier?.benefits?.[0]?.title).toBe("Live calls");
+    expect(result.current.step).toBe("choose");
+    expect(result.current.currentTierName).toBe("Basic");
+  });
+
+  it("Stripe: previews the prorated charge, then one tap moves the plan and lands on the home", async () => {
+    installAdapter(base([post("/public/communities/fan-club/upgrade", () => ({ status: "changed", membership: null }))]));
+    const { result } = renderHook(() => useCommunityUpgrade({ onUpgraded }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.options).toHaveLength(2));
+    act(() => result.current.select("tier-gold"));
+    expect(result.current.step).toBe("confirm");
+    await waitFor(() => expect(result.current.preview?.amount).toBe(15));
+    expect(result.current.prorated).toBe(true);
+    expect(result.current.requiresCard).toBe(false);
+    expect(calls("get", "/public/communities/fan-club/upgrade-preview")[0].params).toMatchObject({ membershipTierId: "tier-gold" });
+
+    await act(async () => {
+      await result.current.upgrade();
+    });
+    expect(calls("post", "/public/communities/fan-club/upgrade")[0].body).toEqual({
+      profileId: "profile-1",
+      membershipTierId: "tier-gold",
+      returnUrl: `${window.location.origin}${HOME}?confirmSubscription=1`,
+    });
+    expect(result.current.step).toBe("done");
+    expect(onUpgraded).toHaveBeenCalledWith({ requiresConfirmation: false, path: HOME });
+  });
+
+  it("Stripe: a bank challenge is a payment step, and success lands on the home to reconcile", async () => {
+    installAdapter(
+      base([post("/public/communities/fan-club/upgrade", () => ({ status: "requires_payment", clientSecret: "pi_up_secret", membership: null }))]),
+    );
+    const { result } = renderHook(() => useCommunityUpgrade({ onUpgraded, initialTierId: "tier-plat" }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.selected?.id).toBe("tier-plat"));
+    await act(async () => {
+      await result.current.upgrade();
+    });
+    expect(result.current.step).toBe("payment");
+    expect(result.current.clientSecret).toBe("pi_up_secret");
+    expect(result.current.isPaystack).toBe(false);
+    act(() => result.current.onPaymentSucceeded());
+    expect(onUpgraded).toHaveBeenCalledWith({ requiresConfirmation: true, path: `${HOME}?confirmSubscription=1` });
+  });
+
+  it("Paystack: requiresCard is known before confirming, and the upgrade opens the new checkout", async () => {
+    installAdapter(
+      base(
+        [
+          post("/public/communities/fan-club/upgrade", () => ({
+            status: "requires_payment",
+            accessCode: "ac_up",
+            checkoutUrl: "https://paystack.test/ac_up",
+            membership: null,
+          })),
+        ],
+        { amount: 20, currency: "NGN", interval: "month", requiresCard: true, prorated: false },
+      ),
+    );
+    const { result } = renderHook(() => useCommunityUpgrade({ onUpgraded }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.options).toHaveLength(2));
+    act(() => result.current.select("tier-gold"));
+    await waitFor(() => expect(result.current.requiresCard).toBe(true));
+    expect(result.current.prorated).toBe(false);
+
+    await act(async () => {
+      await result.current.upgrade();
+    });
+    expect(result.current.step).toBe("payment");
+    expect(result.current.isPaystack).toBe(true);
+    expect(paystack.open).toHaveBeenCalledWith(
+      expect.objectContaining({ accessCode: "ac_up", returnUrl: `${window.location.origin}${HOME}?confirmSubscription=1` }),
+      expect.anything(),
+    );
+    expect(onUpgraded).not.toHaveBeenCalled();
+  });
+
+  it("a refusal is shown and nothing lands", async () => {
+    installAdapter(
+      base([
+        post("/public/communities/fan-club/upgrade", () => {
+          throw { status: 400, message: "That tier is not above yours." };
+        }),
+      ]),
+    );
+    const { result } = renderHook(() => useCommunityUpgrade({ onUpgraded, initialTierId: "tier-gold" }), { wrapper: wrapper({ user: account() }) });
+    await waitFor(() => expect(result.current.options).toHaveLength(2));
+    await act(async () => {
+      await result.current.upgrade();
+    });
+    expect(result.current.error).toBe("That tier is not above yours.");
+    expect(result.current.step).toBe("confirm");
+    expect(onUpgraded).not.toHaveBeenCalled();
+  });
+});

package/src/ui/headless/auth/useSignupForm.ts

@@ -17,7 +17,7 @@ export interface UseSignupFormOptions {
  * Headless account signup. Bring your own UI (or use the styled <SignupForm>).
  *
  * TWO STEPS: `submit()` creates the account and the platform emails a 6-digit
- * code — no session yet. `awaitingCode` then flips true; collect the code into
+ * code: no session yet. `awaitingCode` then flips true; collect the code into
  * `code` and call `submitCode()`, which signs the fan in and fires `onSuccess`.
  * Render the code input whenever `awaitingCode` is true.
  */
@@ -69,7 +69,7 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
         acceptedTerms: true,
         acceptedPrivacy: true,
       });
-      // No session yet — the emailed code is the next step.
+      // No session yet: the emailed code is the next step.
       setAwaitingCode(true);
     } catch (e) {
       setError(msg(e) || "Could not create your account.");
@@ -104,6 +104,13 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
     }
   };
 
+  /** Leave the code step to correct the details (a mistyped email). */
+  const editDetails = () => {
+    setAwaitingCode(false);
+    setCode("");
+    setError(null);
+  };
+
   /** Re-send a code (throttled to one per 60s server-side). */
   const resendCode = async () => {
     setError(null);
@@ -146,5 +153,6 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
     setCode,
     submitCode,
     resendCode,
+    editDetails,
   };
 }

package/src/ui/headless/communities/CommunityGate.tsx

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+import { useOptionalCommunityContext, MissingCommunityProviderError } from "../../../contexts/CommunityContext";
+import type { CommunityViewerState } from "../../../data/queries/useCommunities";
+import { useCommunity, viewerHasAccess } from "./useCommunity";
+
+export interface CommunityGateState {
+  hasAccess: boolean;
+  /** Anonymous visitors see the fallback too; this tells a sign-in prompt from an upgrade prompt. */
+  isAuthenticated: boolean;
+  /** Where the viewer stands in THIS community. */
+  viewerState: CommunityViewerState["state"] | null;
+  /** The tiers that unlock the content, as given. */
+  tiers: string[];
+}
+
+export interface CommunityGateProps {
+  /**
+   * Tier ids (of THIS community) that unlock the content. Omitted or empty:
+   * any active member of this community. Never "a member of anything on the
+   * profile": a membership in another community of the same creator unlocks
+   * nothing here.
+   */
+  tiers?: string[];
+  /** Override the decision, e.g. with a server-computed `hasAccess` on the item. */
+  access?: boolean;
+  children: ReactNode;
+  /** Rendered when locked: a node, or a render function given the gate state. */
+  fallback?: ReactNode | ((state: CommunityGateState) => ReactNode);
+  /** Rendered while the viewer is loading. Default nothing, so locked content never flashes. */
+  loading?: ReactNode;
+}
+
+/**
+ * The gate's rule, pure: an active membership IN THIS COMMUNITY, on one of
+ * `tiers` when tiers are named. `past_due` keeps access through the grace
+ * window, exactly as the server does.
+ */
+export function communityGateAllows(
+  viewer: Pick<CommunityViewerState, "state" | "membership"> | null | undefined,
+  tiers?: string[],
+): boolean {
+  if (!viewerHasAccess(viewer)) return false;
+  if (!tiers?.length) return true;
+  return !!viewer?.membership && tiers.includes(viewer.membership.tierId);
+}
+
+/**
+ * Headless access gate for member content (replaces `MembershipGate`). Renders
+ * children when the viewer has access to the surrounding community's content,
+ * otherwise the fallback. Must sit inside `<CommunityProvider>`.
+ */
+export function CommunityGate({ tiers, access, children, fallback, loading }: CommunityGateProps) {
+  if (!useOptionalCommunityContext()) throw new MissingCommunityProviderError("<CommunityGate>");
+  const community = useCommunity();
+  const viewer = community.viewer;
+  if (access === undefined && community.isLoading) return <>{loading ?? null}</>;
+  const hasAccess = access ?? communityGateAllows(viewer, tiers);
+  if (hasAccess) return <>{children}</>;
+  const state: CommunityGateState = {
+    hasAccess,
+    isAuthenticated: !!viewer && viewer.state !== "anonymous",
+    viewerState: viewer?.state ?? null,
+    tiers: tiers ?? [],
+  };
+  if (typeof fallback === "function") return <>{fallback(state)}</>;
+  return <>{fallback ?? null}</>;
+}

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

@@ -0,0 +1,55 @@
+// Communities: every page of a community has a headless version (decision 14).
+// A styled component is one of these hooks plus markup and nothing else, so a
+// creator can rebuild the list, the About page, the join sheet, the pending
+// screen, the upgrade sheet and the membership menu on their own routes.
+export {
+  CommunityProvider,
+  useCommunityContext,
+  useOptionalCommunityContext,
+  isCommunityId,
+  MissingCommunityProviderError,
+  CommunityUpgradeOpenerProvider,
+  useCommunityUpgradeOpener,
+  type CommunityContextValue,
+  type CommunityProviderProps,
+  type CommunityUpgradeOpener,
+} from "../../../contexts/CommunityContext";
+export {
+  useCommunities,
+  useCommunity,
+  communityJoinOffer,
+  viewerHasAccess,
+  COMMUNITY_ACCESS_STATES,
+  type CommunityJoinOffer,
+  type UseCommunityOptions,
+} from "./useCommunity";
+export {
+  useCommunityInvite,
+  describeCommunityInvite,
+  type CommunityInviteProblem,
+  type CommunityInviteSummary,
+} from "./useCommunityInvite";
+export {
+  useCommunityJoin,
+  communityJoinStep,
+  tierHasChoice,
+  type CommunityJoinStep,
+  type CommunityJoinStepInput,
+  type UseCommunityJoinOptions,
+} from "./useCommunityJoin";
+export {
+  useCommunityUpgrade,
+  type CommunityUpgradeStep,
+  type CommunityUpgradeOption,
+  type UseCommunityUpgradeOptions,
+} from "./useCommunityUpgrade";
+export { useCommunityMembership, communityDowngradeTiers } from "./useCommunityMembership";
+export {
+  useCommunityAbout,
+  type CommunityAboutAction,
+  type UseCommunityAboutOptions,
+} from "./useCommunityAbout";
+export { useCommunityHome, type UseCommunityHomeOptions } from "./useCommunityHome";
+export { useMyMemberships, toMyMembershipEntry, type MyMembershipEntry } from "./useMyMemberships";
+export { CommunityGate, communityGateAllows, type CommunityGateProps, type CommunityGateState } from "./CommunityGate";
+export { communitiesListPath, communityAboutPath, communityHomePath } from "./paths";

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

@@ -0,0 +1,36 @@
+import { internalPath } from "../../../runtime/pages";
+
+/**
+ * The hosted community pages, as plain paths. Built through `internalPath` so a
+ * page rename is a type error here rather than a dead link on a published site.
+ *
+ * Every flow that ends (a join, a paid join's Stripe return, an upgrade, an
+ * application) lands on the community HOME, never on `/i/account`.
+ */
+
+type Query = Record<string, string | number | null | undefined>;
+
+function withQuery(path: string, query?: Query): string {
+  if (!query) return path;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null && value !== "") params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `${path}?${qs}` : path;
+}
+
+/** Every community on the profile: `/i/communities`. */
+export function communitiesListPath(): string {
+  return internalPath("communities");
+}
+
+/** A community's About page, e.g. `communityAboutPath("fan-club", { tier })`. */
+export function communityAboutPath(slug: string, query?: { invite?: string; join?: string; tier?: string }): string {
+  return withQuery(internalPath("communities/$slug", { slug }), query);
+}
+
+/** The inside of a community. `welcome=1` after a join, `confirmSubscription=1` after a Stripe return. */
+export function communityHomePath(slug: string, query?: { welcome?: 1 | "1"; confirmSubscription?: 1 | "1" }): string {
+  return withQuery(internalPath("communities/$slug/home", { slug }), query);
+}