@tribe-nest/forge 3.59.0 → 3.61.0

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

@@ -0,0 +1,182 @@
+import { useMemo, useState } from "react";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import {
+  useCancelCommunityMembership,
+  useDowngradeCommunityMembership,
+  useMyCommunityMemberships,
+  useUndoCommunityDowngrade,
+  type PublicTier,
+} from "../../../data/queries/useCommunities";
+import { useOpenBillingPortal } from "../../../data/queries/useSubscriptions";
+import { cycleFloor, cycleIsFree, defaultCycle, type BillingCycle } from "../../format/membershipPwyw";
+import { useCommunity } from "./useCommunity";
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+/** A monthly-equivalent price, so tiers sold on different cycles still order correctly. */
+const monthlyPrice = (tier: PublicTier) => {
+  const cycle = defaultCycle(tier);
+  const floor = cycleFloor(tier, cycle);
+  return cycle === "year" ? floor / 12 : floor;
+};
+
+/**
+ * The tiers a member can move DOWN to: this community's tiers priced below the
+ * current one, excluding anything the upgrade list offers. Pure.
+ */
+export function communityDowngradeTiers(tiers: PublicTier[], currentTierId: string | null | undefined, upgradeTierIds: string[]): PublicTier[] {
+  const current = tiers.find((tier) => tier.id === currentTierId);
+  if (!current) return [];
+  const currentPrice = monthlyPrice(current);
+  return tiers.filter(
+    (tier) =>
+      tier.id !== current.id &&
+      !upgradeTierIds.includes(tier.id) &&
+      tier.joinMode !== "application" &&
+      monthlyPrice(tier) < currentPrice,
+  );
+}
+
+/** What the member pays, as far as the client can tell. */
+export interface CommunityMembershipBilling {
+  /** True when the membership is paid for (a subscription with a price). */
+  isPaid: boolean;
+  /** Per period, in `currency`. Null on a free membership, or while unknown. */
+  amount: number | null;
+  currency: string | null;
+  cycle: BillingCycle | null;
+}
+
+/**
+ * Is this membership paid for, and what does it cost? Pure.
+ *
+ * The answer comes from the member's own row in `/public/memberships/mine`
+ * (`row`), which carries the subscription's real amount and cycle: a
+ * pay-what-you-want member pays what they chose, and a member on a tier sold
+ * both ways pays the cycle they picked. Until that row arrives, the tier's own
+ * price stands in, so a free tier never flashes "Update payment method".
+ */
+export function communityMembershipBilling(
+  row: { amount: number | null; currency: string | null; billingCycle: string | null } | null | undefined,
+  tier: PublicTier | null | undefined,
+): CommunityMembershipBilling {
+  if (row) {
+    const amount = typeof row.amount === "number" && row.amount > 0 ? row.amount : null;
+    const cycle = row.billingCycle === "year" ? "year" : row.billingCycle === "month" ? "month" : null;
+    return { isPaid: amount !== null, amount, currency: amount !== null ? row.currency : null, cycle: amount !== null ? cycle : null };
+  }
+  if (!tier) return { isPaid: false, amount: null, currency: null, cycle: null };
+  const cycle = defaultCycle(tier);
+  return { isPaid: !cycleIsFree(tier, cycle), amount: null, currency: null, cycle: null };
+}
+
+/**
+ * The Membership menu inside a community: current tier, renewal date, a pending
+ * downgrade, and the actions. Cancel keeps the paid period; a downgrade takes
+ * effect at period end and can be withdrawn until then (decision 11).
+ *
+ * Cancel is two-step (`requestCancel()` then `confirmCancel()`), because a
+ * destructive action has to be confirmed and the confirmation's wording depends
+ * on state the hook owns.
+ */
+export function useCommunityMembership() {
+  const context = useOptionalCommunityContext();
+  if (!context) throw new MissingCommunityProviderError("useCommunityMembership()");
+  const community = useCommunity();
+  const ref = community.slug ?? context.slug ?? context.ref;
+  const cancel = useCancelCommunityMembership(ref);
+  const downgrade = useDowngradeCommunityMembership(ref);
+  const undo = useUndoCommunityDowngrade(ref);
+  const billingPortal = useOpenBillingPortal();
+  const mine = useMyCommunityMemberships({ enabled: !!community.membership });
+
+  const [cancelRequested, setCancelRequested] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const membership = community.membership;
+  const upgradeIds = community.upgradeTiers.map((tier) => tier.id);
+  const downgradeTiers = useMemo(
+    () => communityDowngradeTiers(community.tiers, membership?.tierId, upgradeIds),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [community.tiers, membership?.tierId, upgradeIds.join(",")],
+  );
+  const pendingDowngradeTier = membership?.pendingDowngradeTierId
+    ? (community.tiers.find((tier) => tier.id === membership.pendingDowngradeTierId) ?? {
+        id: membership.pendingDowngradeTierId,
+        name: "",
+      })
+    : null;
+
+  const mineRow = membership ? mine.data?.find((row) => row.id === membership.id) : undefined;
+  const billing = communityMembershipBilling(
+    mineRow ? { amount: mineRow.subscriptionAmount ?? null, currency: mineRow.subscriptionCurrency ?? null, billingCycle: mineRow.billingCycle ?? null } : null,
+    community.currentTier,
+  );
+
+  const run = async (action: () => Promise<unknown>) => {
+    setError(null);
+    try {
+      await action();
+      await Promise.all([community.refetch(), membership ? mine.refetch() : Promise.resolve()]);
+      return true;
+    } catch (e) {
+      setError(errMessage(e));
+      return false;
+    }
+  };
+
+  return {
+    isLoading: community.isLoading,
+    /** False for a viewer with nothing to manage here. */
+    hasMembership: !!membership,
+    membership,
+    currentTier: community.currentTier,
+    /** When the paid period ends: the renewal date, or the last day when cancelling. */
+    periodEnd: membership?.currentPeriodEnd ?? null,
+    isCancelling: !!membership?.cancelAtPeriodEnd,
+    pendingDowngradeTier,
+    downgradeTiers,
+    isPastDue: community.viewer?.state === "past_due",
+    /** Paid or free, and the price per period when the server has said. A free membership has no card to update. */
+    billing,
+    isPaid: billing.isPaid,
+    /** A higher tier exists, so the sheet offers Upgrade. */
+    hasUpgrade: community.hasUpgrade,
+    error,
+    isWorking: cancel.isPending || downgrade.isPending || undo.isPending || billingPortal.isPending,
+
+    cancelRequested,
+    /** Ask to cancel: show the confirmation, which must say the paid period is kept. */
+    requestCancel: () => {
+      setError(null);
+      setCancelRequested(true);
+    },
+    abortCancel: () => setCancelRequested(false),
+    /** Cancel for real. Access runs to the end of the paid period. */
+    confirmCancel: async () => {
+      const ok = await run(() => cancel.mutateAsync());
+      if (ok) setCancelRequested(false);
+      return ok;
+    },
+    /** The same, without the confirmation step, for a host that confirms on its own. */
+    cancel: () => run(() => cancel.mutateAsync()),
+    /** Move down to `tierId` at the end of the paid period. */
+    downgrade: (tierId: string) => run(() => downgrade.mutateAsync({ membershipTierId: tierId })),
+    /** Withdraw a pending downgrade. */
+    undoDowngrade: () => run(() => undo.mutateAsync()),
+    /**
+     * Open the provider's billing page to change the card. The server derives
+     * the customer from the session; the fan comes back to this page.
+     */
+    updateCard: async () => {
+      setError(null);
+      try {
+        const { url } = await billingPortal.mutateAsync();
+        if (typeof window !== "undefined" && url) window.location.assign(url);
+      } catch (e) {
+        setError(errMessage(e));
+      }
+    },
+  };
+}

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/useCommunityWiki.ts

@@ -0,0 +1,266 @@
+import { useMemo, useState } from "react";
+import { useCommunityUpgradeOpener, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { isNotFound } from "../../../data/queries/useCommunities";
+import {
+  useCommunityWikiMediaUrl,
+  useCommunityWikiPageContent,
+  useCommunityWikiPages,
+  type CommunityWikiPageSummary,
+} from "../../../data/queries/useCommunityWiki";
+import type { LexicalNodeJson } from "../community/lexical";
+import { communityAboutPath } from "./paths";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+/** How a wiki image's `src` is shown, if at all. */
+export type WikiImageSource = { kind: "url"; url: string } | { kind: "private"; mediaId: string } | null;
+
+const PRIVATE_MEDIA_PREFIX = "kbmedia:";
+const MEDIA_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * Read a Knowledge Base image's `src`. A plain http(s) address (or a site
+ * path) is shown as it is. `kbmedia:<id>` is a PRIVATE image, shown through a
+ * short-lived signed read that only a viewer of the page can get. Anything
+ * else is never rendered: not `javascript:`, not `data:`, not a malformed id.
+ */
+export function wikiImageSource(src: unknown): WikiImageSource {
+  if (typeof src !== "string") return null;
+  const value = src.trim();
+  if (/^https?:\/\//i.test(value) || (value.startsWith("/") && !value.startsWith("//")))
+    return { kind: "url", url: value };
+  if (value.startsWith(PRIVATE_MEDIA_PREFIX)) {
+    const mediaId = value.slice(PRIVATE_MEDIA_PREFIX.length);
+    return MEDIA_ID.test(mediaId) ? { kind: "private", mediaId } : null;
+  }
+  return null;
+}
+
+export type WikiMediaImageStatus = "loading" | "ready" | "unavailable";
+
+/**
+ * Where a private image stands, from the signed-read request and the addresses
+ * the browser failed to load. The first failure (usually an expired address)
+ * asks for a fresh one; once that re-request has been made
+ * (`retriedAfterFailure`), a failed address reads as unavailable, so a broken
+ * file cannot loop.
+ */
+export function wikiMediaImageStatus(input: {
+  isLoading: boolean;
+  isError: boolean;
+  url: string | null;
+  failedUrls: ReadonlySet<string>;
+  retriedAfterFailure: boolean;
+}): WikiMediaImageStatus {
+  if (input.isError) return "unavailable";
+  if (!input.url) return input.isLoading ? "loading" : "unavailable";
+  if (input.failedUrls.has(input.url)) return input.retriedAfterFailure ? "unavailable" : "loading";
+  return "ready";
+}
+
+/** One entry of a page's table of contents. `id` is the heading's anchor. */
+export interface CommunityWikiTocEntry {
+  id: string;
+  text: string;
+  /** 1 for h1 through 6 for h6. */
+  level: number;
+}
+
+/** A table of contents is shown once a page has this many headings. */
+export const WIKI_TOC_MIN_HEADINGS = 2;
+
+/**
+ * The page list split the way a renderer draws it: every page in order, the
+ * ones this viewer can open, and the ones listed but locked to a tier they do
+ * not have. `publicOnly` keeps just the public pages (the About page, which a
+ * visitor and a member see alike).
+ */
+export function shapeWikiList(pages: CommunityWikiPageSummary[] | undefined, opts: { publicOnly?: boolean } = {}) {
+  const all = (Array.isArray(pages) ? pages : []).filter((page) => !opts.publicOnly || page.isPublic);
+  return {
+    all,
+    readable: all.filter((page) => !page.locked),
+    locked: all.filter((page) => page.locked),
+  };
+}
+
+/**
+ * What opens a locked page, for the copy beside it: the level the member has
+ * not reached yet (null when the level is not what is missing) and the names
+ * of the tiers that open it (empty when none are named).
+ */
+export function wikiUnlockParts(page: Pick<CommunityWikiPageSummary, "unlockLevel" | "unlockTiers">): {
+  level: number | null;
+  tiers: string;
+} {
+  const level = typeof page.unlockLevel === "number" && page.unlockLevel > 0 ? page.unlockLevel : null;
+  const tiers = (page.unlockTiers ?? []).map((tier) => tier.name).filter(Boolean).join(", ");
+  return { level, tiers };
+}
+
+/**
+ * The page the Wiki tab opens on when the address names none: the first page
+ * this viewer can read, in the wiki's order. Null when every page is locked or
+ * there are none.
+ */
+export function defaultWikiPageSlug(pages: CommunityWikiPageSummary[] | undefined): string | null {
+  return (Array.isArray(pages) ? pages : []).find((page) => !page.locked)?.slug ?? null;
+}
+
+/**
+ * Lexical JSON as a root node. The Knowledge Base stores the editor state as an
+ * object, but a string of JSON is accepted too, so a page never renders empty
+ * because of how its content was serialised.
+ */
+export function parseWikiContent(content: unknown): { root: LexicalNodeJson } | null {
+  let value = content;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (!value || typeof value !== "object") return null;
+  const maybe = value as { root?: LexicalNodeJson; children?: LexicalNodeJson[] };
+  if (maybe.root && typeof maybe.root === "object") return { root: maybe.root };
+  if (Array.isArray(maybe.children)) return { root: maybe as LexicalNodeJson };
+  return null;
+}
+
+/** The plain text of a node and everything under it. */
+export function lexicalNodeText(node: LexicalNodeJson): string {
+  if (typeof node.text === "string") return node.text;
+  return (node.children ?? []).map(lexicalNodeText).join("");
+}
+
+/** A URL-safe anchor for a heading ("Getting started!" to "getting-started"). */
+export function wikiHeadingSlug(text: string): string {
+  const slug = text
+    .normalize("NFKD")
+    // Drop the accents NFKD split off ("Über" to "Uber").
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "section";
+}
+
+/**
+ * The table of contents: every top-level heading in document order, each with
+ * a unique anchor (a repeated title gets `-2`, `-3`). The renderer gives the
+ * headings these same ids in the same order, which is why both read the root's
+ * direct children only. Empty headings are skipped.
+ */
+export function extractWikiToc(content: unknown): CommunityWikiTocEntry[] {
+  const parsed = parseWikiContent(content);
+  if (!parsed) return [];
+  const used = new Map<string, number>();
+  const toc: CommunityWikiTocEntry[] = [];
+  for (const node of parsed.root.children ?? []) {
+    if (node.type !== "heading") continue;
+    const text = lexicalNodeText(node).trim();
+    if (!text) continue;
+    const base = wikiHeadingSlug(text);
+    const seen = used.get(base) ?? 0;
+    used.set(base, seen + 1);
+    const tag = typeof node.tag === "string" ? node.tag : "h2";
+    const level = Math.min(6, Math.max(1, Number(tag.replace(/^h/, "")) || 2));
+    toc.push({ id: seen ? `${base}-${seen + 1}` : base, text, level });
+  }
+  return toc;
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+/**
+ * A PRIVATE wiki image (`kbmedia:<id>`) on the page `pageSlug`: its signed
+ * address, re-requested before it expires, and again once if the browser
+ * fails to load it (`onImageError`). Only the wiki page view uses this: posts
+ * never carry private Knowledge Base media.
+ */
+export function useWikiMediaImage(pageSlug: string | undefined, mediaId: string | undefined) {
+  const query = useCommunityWikiMediaUrl(pageSlug, mediaId);
+  const [failedUrls, setFailedUrls] = useState<ReadonlySet<string>>(() => new Set());
+  const [retriedAfterFailure, setRetriedAfterFailure] = useState(false);
+  const url = query.data?.url ?? null;
+  const status = wikiMediaImageStatus({
+    isLoading: query.isLoading || query.isFetching,
+    isError: query.isError,
+    url,
+    failedUrls,
+    retriedAfterFailure,
+  });
+
+  return {
+    status,
+    url: status === "ready" ? url : null,
+    /** Call from the <img>'s onError: an expired address is replaced once. */
+    onImageError: () => {
+      if (!url || failedUrls.has(url)) return;
+      setFailedUrls((prev) => new Set(prev).add(url));
+      if (retriedAfterFailure) return;
+      void query.refetch().finally(() => setRetriedAfterFailure(true));
+    },
+  };
+}
+
+export interface UseCommunityWikiOptions {
+  /** Keep only the public pages (the About page). */
+  publicOnly?: boolean;
+  enabled?: boolean;
+}
+
+/**
+ * Headless wiki page list for the surrounding community: every page this
+ * viewer may see, the readable and locked ones, the page to open by default,
+ * and how to unlock a locked one. `unlock` opens the community's upgrade sheet
+ * with the page's first unlocking tier when a community home provides one;
+ * otherwise `unlockHref` is the About page with that tier preselected.
+ */
+export function useCommunityWiki(opts: UseCommunityWikiOptions = {}) {
+  const community = useOptionalCommunityContext();
+  const opener = useCommunityUpgradeOpener();
+  const query = useCommunityWikiPages({ enabled: opts.enabled });
+  const shaped = useMemo(
+    () => shapeWikiList(query.data, { publicOnly: opts.publicOnly }),
+    [query.data, opts.publicOnly],
+  );
+
+  return {
+    pages: shaped.all,
+    readablePages: shaped.readable,
+    lockedPages: shaped.locked,
+    /** The page to open when the address names none. */
+    defaultSlug: defaultWikiPageSlug(shaped.all),
+    isLoading: query.isLoading,
+    isError: query.isError && !isNotFound(query.error),
+    /** Open the upgrade sheet for a locked page, when a community home provides one. */
+    unlock: opener ? (page: CommunityWikiPageSummary) => opener.openUpgrade(page.unlockTiers[0]?.id ?? null) : null,
+    /** Where a locked page's upgrade leads when no upgrade sheet is on hand. */
+    unlockHref: (page: CommunityWikiPageSummary) =>
+      community?.slug ? communityAboutPath(community.slug, { tier: page.unlockTiers[0]?.id }) : null,
+  };
+}
+
+/**
+ * Headless wiki page: its content (parsed), the table of contents and whether
+ * to show it, and `notFound` when this viewer may not read the page (locked,
+ * hidden or gone: the server does not say which, by design).
+ */
+export function useCommunityWikiPage(pageSlug: string | undefined, opts: { enabled?: boolean } = {}) {
+  const query = useCommunityWikiPageContent(pageSlug, opts);
+  const content = useMemo(() => parseWikiContent(query.data?.content), [query.data]);
+  const toc = useMemo(() => extractWikiToc(content), [content]);
+  return {
+    page: query.data ?? null,
+    content,
+    toc,
+    showToc: toc.length >= WIKI_TOC_MIN_HEADINGS,
+    /** Anchor ids for the page's headings, in order, for the renderer. */
+    headingIds: toc.map((entry) => entry.id),
+    isLoading: query.isLoading,
+    notFound: isNotFound(query.error),
+    isError: query.isError && !isNotFound(query.error),
+  };
+}