@tribe-nest/forge 3.4.0 → 3.11.0

package/src/types/models.ts

@@ -238,13 +238,38 @@ export type MembershipTier = {
   cancellationMessageContent?: string | null;
 };
 
+/**
+ * The server's access + billing decision, shipped with every membership.
+ *
+ * Read this through `getMembershipAccess()` rather than destructuring it — the
+ * helper handles a server that predates the block, and is the single place any
+ * surface is allowed to answer "does this grant access".
+ */
+export interface MembershipAccess {
+  hasAccess: boolean;
+  billingState: "active" | "ending" | "past_due" | "grace" | "pending" | "ended";
+  paymentFailed: boolean;
+  graceUntil: string | null;
+  pastDueAt: string | null;
+  cancelAtPeriodEnd: boolean;
+}
+
 export interface Membership {
   id: string;
   membershipTierId: string;
   profilePaymentSubscriptionId?: string;
   paymentProviderSubscriptionId?: string;
   endDate: string;
+  /**
+   * Raw lifecycle status. **Do not compare this to `"active"` to decide access
+   * or to label the membership** — `past_due` and `grace` still grant access.
+   * Use `getMembershipAccess(membership)` / `getMembershipStatusMessage()`.
+   */
   status: string;
+  access?: MembershipAccess;
+  cancelAtPeriodEnd?: boolean;
+  graceUntil?: string | null;
+  pastDueAt?: string | null;
   membershipTier: MembershipTier;
   startDate: string;
   subscriptionAmount: number;
@@ -752,6 +777,31 @@ export type QuestionnaireQuestion = {
   optional?: boolean;
 };
 
+/**
+ * S.6 — the cancellation terms a buyer is entitled to read BEFORE they pay.
+ *
+ * Two endpoints return this shape and they answer different questions:
+ *  - `GET /public/coaching/products/:id` → the product's LIVE policy, i.e. "what
+ *    would I be agreeing to". Show it on the storefront.
+ *  - `POST …/booking/reserve` → the SNAPSHOT written onto the booking, i.e.
+ *    "what did I agree to". Show it from the details step onwards, because an
+ *    operator editing the policy mid-checkout must not move the terms under a
+ *    buyer who already holds the hour.
+ *
+ * `description` is rendered SERVER-side by the shared `describeCancellationPolicy`
+ * so the sentence at checkout is byte-identical to the one in the buyer's portal.
+ * It is `null` when the seller configured no policy — render nothing rather than
+ * inventing a right, and note that "no policy" is a different fact from `none`.
+ */
+export type CancellationTermsView = {
+  policy: "none" | "until" | "anytime" | null;
+  cutoffHours: number | null;
+  /** The seller's own free text, when they wrote any. */
+  terms: string | null;
+  /** One ready-made sentence, or null when there is no policy at all. */
+  description: string | null;
+};
+
 export type CoachingProduct = {
   id: string;
   title: string;
@@ -773,6 +823,8 @@ export type CoachingProduct = {
   questionnaire?: QuestionnaireQuestion[];
   /** Rating aggregate — present on the detail endpoint, null until first published review. */
   reviewAggregate?: IReviewAggregate | null;
+  /** The seller's CURRENT cancellation terms — present on the detail endpoint only. */
+  cancellation?: CancellationTermsView | null;
 };
 
 export type PublicCourseLesson = {
@@ -847,6 +899,29 @@ export type PodcastShow = {
 
 // ---- Events ------------------------------------------------------------------
 
+/**
+ * The artist's booking fee, RESOLVED — what `GET /public/events/:id` publishes
+ * so a storefront can quote the real price before the buyer commits.
+ *
+ * The fee is charged per ORDER (`total_amount` goes up by it), and until this
+ * shipped no buyer-facing surface mentioned it anywhere.
+ *
+ * These are NOT the event's raw `ticketFeeCents` / `ticketFeeBps` columns. Those
+ * are `null` whenever the event inherits the artist's default — the ordinary
+ * case — so reading them shows no fee while one is being charged. The server
+ * merges the event's override over the profile default and sends the result.
+ */
+export interface IBookingFee {
+  /** The flat part per ORDER, in major units of `currency`. */
+  feeAmount: number;
+  /** The percentage of the discounted subtotal, in basis points. 2.5% = 250. */
+  feeBps: number;
+  /** The artist's currency — the one ticket prices and `feeAmount` are in. */
+  currency: string;
+  /** 100, or 1 for a zero-decimal currency (JPY). The percentage rounds to it. */
+  minorUnitFactor: number;
+}
+
 export interface IEvent {
   id: string;
   profileId: string;
@@ -896,6 +971,77 @@ export interface IEvent {
   tickets: ITicket[];
   media: IMedia[];
   slug: string;
+  /**
+   * The booking fee this event's buyers will be charged, already resolved.
+   *
+   * Optional because the detail endpoint composes it and the LIST endpoint does
+   * not — no list surface quotes a ticket price, so there is no figure there for
+   * a buyer to mistake for a final one. A page reached through `useEvents()`
+   * must not assume it is present.
+   */
+  bookingFee?: IBookingFee | null;
+}
+
+// ---- Event series ------------------------------------------------------------
+
+/**
+ * One date within a series, as `GET /public/event-series/:slug` returns it.
+ *
+ * DELIBERATELY not `IEvent`. A series page lists dates; it does not sell them —
+ * the buyer follows a date through to `/events/:slug`, which is the page that
+ * carries tickets, the questionnaire, terms and the checkout. Restating the
+ * narrow shape here keeps that boundary visible: if a field is missing from
+ * this type, the series endpoint does not publish it, and adding it is a
+ * decision made on the server first.
+ */
+export interface IEventSeriesDate {
+  id: string;
+  title: string;
+  /** Links through to the event page — `/events/:slug`. */
+  slug: string;
+  dateTime: string;
+  endDateTime: string | null;
+  doorsOpenAt: string | null;
+  timezone?: string;
+  type: "physical" | "virtual" | "hybrid" | string;
+  /**
+   * A `cancelled` date STAYS in this list — a ticket-holder following their
+   * link must learn why rather than meet a 404 — so any renderer MUST mark it
+   * rather than assume every entry is going ahead.
+   */
+  status: "scheduled" | "on_sale" | "sold_out" | "cancelled" | "completed";
+  cancelledAt: string | null;
+  cancellationReason: string | null;
+  address?: {
+    name?: string;
+    street?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zipCode?: string;
+  };
+}
+
+/**
+ * A NAMED, multi-date event series.
+ *
+ * Every event on the platform belongs to a series (a one-off show is a series
+ * of one), but only a series that a human NAMED and that holds at least two
+ * publicly-visible dates has a page. Everything else 404s from the API, so this
+ * type never describes a container-of-one and a renderer never has to ask.
+ */
+export interface IEventSeries {
+  id: string;
+  title: string;
+  slug: string;
+  description: string | null;
+  /** The publicly-visible dates, ordered by `dateTime`, earliest first. */
+  events: IEventSeriesDate[];
+  media: IMedia[];
+  /** `events.length`, derived server-side off the SAME list — they cannot disagree. */
+  dateCount: number;
+  firstDateTime: string | null;
+  lastDateTime: string | null;
 }
 
 export type ITicket = {

package/src/ui/format/bookingFee.ts

@@ -0,0 +1,98 @@
+import type { IBookingFee } from "../../types/models";
+
+/**
+ * The artist's booking fee, as a buyer-facing surface has to show it.
+ *
+ * ## Why this file exists
+ *
+ * The fee was CHARGED and displayed nowhere. `createOrder` raised the order
+ * total by it and no storefront on either rendering stack said a word, so the
+ * buyer met it for the first time on the card statement. That is not only
+ * unfair, it is regulated — FTC junk-fee rules, CMA guidance and the EU
+ * price-indication rules all require a mandatory charge to be visible BEFORE
+ * the buyer commits.
+ *
+ * ## What is safe to compute here, and what is not
+ *
+ * The RESOLUTION — the event's override merged over the artist's profile
+ * default, `null` meaning "inherit" and `0` meaning "deliberately zero" — is NOT
+ * done here. It happens once on the server and arrives already resolved on
+ * `IEvent.bookingFee`. Reimplementing it on two separate rendering stacks is
+ * exactly how a displayed fee drifts away from a charged one, and the raw
+ * columns are `null` in the ordinary inheriting case, so a client reading them
+ * would show no fee at all.
+ *
+ * What is left is the arithmetic, and it is deterministic: a flat part plus a
+ * percentage of the subtotal, rounded to the currency's minor unit. The factor
+ * comes down in the payload precisely so no storefront needs its own copy of
+ * the zero-decimal currency list to round the way the server rounds.
+ *
+ * ## This is still an ESTIMATE
+ *
+ * It exists to keep the running total honest while the buyer is still choosing
+ * quantities, when no order exists and the server has no figure to give. The
+ * moment an order is created, `POST /public/events/:id/orders` returns the
+ * `feeAmount` it actually wrote, and THAT is what the payment step shows. The
+ * two agree by construction; if the artist changes their fee mid-session, the
+ * server's number is the one the buyer sees before paying.
+ *
+ * Mirrors `computeBookingFee` in `apps/backend/src/db/types/bookingFee.ts`.
+ */
+export function computeBookingFeeAmount(input: {
+  /** The DISCOUNTED subtotal, in major units of the artist's currency. */
+  subtotal: number;
+  fee: IBookingFee | null | undefined;
+}): number {
+  const { subtotal, fee } = input;
+  if (!fee) return 0;
+
+  /**
+   * A free order pays nothing — the flat part included.
+   *
+   * A comp, a members' freebie or a giveaway must not be shown a booking fee,
+   * because it is not charged one. The server takes the same branch, so showing
+   * one here would be a line the buyer is never billed for.
+   */
+  if (subtotal <= 0) return 0;
+
+  const factor = fee.minorUnitFactor > 0 ? fee.minorUnitFactor : 100;
+  const subtotalMinor = Math.round(subtotal * factor);
+  const percentMinor = Math.round((subtotalMinor * fee.feeBps) / 10_000);
+  const flatMinor = Math.round(fee.feeAmount * factor);
+
+  return Math.max(0, flatMinor + percentMinor) / factor;
+}
+
+/**
+ * Whether this artist charges a booking fee at all.
+ *
+ * The payload is always present so a surface can rely on its shape, which means
+ * "no fee" arrives as zeros rather than as an absent object. A storefront that
+ * rendered those zeros would print a "+$0.00 booking fee" line — inventing a
+ * charge that does not exist and implying one might appear later. There is
+ * nothing to disclose when nothing is charged, so every surface suppresses the
+ * line on this.
+ */
+export function hasBookingFee(fee: IBookingFee | null | undefined): boolean {
+  return !!fee && (fee.feeAmount > 0 || fee.feeBps > 0);
+}
+
+/**
+ * The fee rule in words, for a price that is quoted WITHOUT a cart behind it.
+ *
+ * An event page saying "From $25" is a price a buyer can reasonably read as
+ * final, but there is no selection yet, so there is no amount — only the rule.
+ * Naming it ("+ $1.50 booking fee", "+ 2.5% booking fee") is what stops the
+ * quoted figure from being the whole story. Returns `null` when there is no fee,
+ * so the caller renders nothing.
+ */
+export function describeBookingFee(
+  fee: IBookingFee | null | undefined,
+  formatAmount: (amount: number) => string,
+): string | null {
+  if (!hasBookingFee(fee)) return null;
+  const parts: string[] = [];
+  if (fee!.feeAmount > 0) parts.push(formatAmount(fee!.feeAmount));
+  if (fee!.feeBps > 0) parts.push(`${+(fee!.feeBps / 100).toFixed(2)}%`);
+  return `+ ${parts.join(" + ")} booking fee`;
+}

package/src/ui/headless/coaching/useCoachingBooking.ts

@@ -11,6 +11,7 @@ import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { useCouponField, type CouponQuoteFn } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
+import type { CancellationTermsView } from "../../../types/models";
 
 export type CoachingBookingStep = "slot" | "details" | "payment";
 
@@ -88,6 +89,13 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /**
+   * S.6 — the terms this buyer actually agreed to, as snapshotted onto the
+   * booking at reserve. Held separately from `product.cancellation` (the
+   * seller's live setting) because they can diverge the moment the operator
+   * edits the policy while the hour is held, and only this copy governs.
+   */
+  const [agreedCancellation, setAgreedCancellation] = useState<CancellationTermsView | null>(null);
   // Epoch ms when the current slot hold expires (null when nothing is held).
   const [reservationExpiresAt, setReservationExpiresAt] = useState<number | null>(null);
 
@@ -153,6 +161,7 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
       if (bookingId) await unreserve.mutateAsync({ bookingId }).catch(() => undefined);
       const data = await reserve.mutateAsync({ slotId: selectedSlotId });
       setBookingId(data.bookingId);
+      setAgreedCancellation(data.cancellation ?? null);
       setReservationExpiresAt(Date.now() + RESERVATION_HOLD_MS);
       setStep("details");
     } catch (e) {
@@ -171,6 +180,9 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setBookingId(null);
     setSelectedSlotId(null);
     setReservationExpiresAt(null);
+    // The agreed terms belonged to a booking that no longer exists — the next
+    // reserve snapshots afresh, and may snapshot something different.
+    setAgreedCancellation(null);
     // The quote belonged to a booking that no longer exists — keeping it would
     // show a discount against a price nothing has agreed to.
     coupon.reset();
@@ -234,6 +246,13 @@ export function useCoachingBooking(slug?: string, opts: UseCoachingBookingOption
     setStep,
     selectedSlotId,
     bookingId,
+    /**
+     * The cancellation terms in force for THIS checkout (S.6): the booking's
+     * snapshot once a slot is held, the product's live policy before that. Never
+     * both — a surface rendering `product.cancellation` after the reserve would
+     * show the buyer terms other than the ones they are bound by.
+     */
+    cancellation: agreedCancellation ?? product?.cancellation ?? null,
     selectSlot,
     reserveSelected,
     reservationExpiresAt,

package/src/ui/headless/event/useEventCheckout.ts

@@ -4,6 +4,7 @@ import { useCart } from "../../../contexts/CartContext";
 import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { useCouponField } from "../coupon/useCouponField";
+import { computeBookingFeeAmount } from "../../format/bookingFee";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -47,6 +48,14 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /**
+   * The booking fee the SERVER charged, once an order exists.
+   *
+   * Kept separately from the coupon quote because it is not a discount concern:
+   * it is the one figure on the payment screen that the client must never
+   * compute for itself, since it is the number on the card.
+   */
+  const [serverFeeAmount, setServerFeeAmount] = useState<number | null>(null);
 
   /**
    * Discount code — STAGED, not quoted.
@@ -71,6 +80,29 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     [selectedTickets],
   );
 
+  /**
+   * The artist's booking fee (1.4) — the thing the buyer was charged and never
+   * told about, on any surface, on either rendering stack.
+   *
+   * Resolved by the server (`event.bookingFee`), because the event's own
+   * `ticketFeeCents`/`ticketFeeBps` are `null` whenever it inherits the artist's
+   * default, and that is the ordinary case.
+   */
+  const bookingFee = event?.bookingFee ?? null;
+
+  /**
+   * The fee to SHOW, in the artist's currency.
+   *
+   * Once an order exists the server has told us what it charged, and that wins
+   * outright — a locally derived figure on the payment screen is how a displayed
+   * total drifts from a billed one. Before then there is no order to ask, so the
+   * running total carries an estimate off the resolved rule; it keeps the "Total"
+   * honest while the buyer is still choosing quantities, which is precisely when
+   * the disclosure has to happen.
+   */
+  const bookingFeeAmount =
+    serverFeeAmount ?? computeBookingFeeAmount({ subtotal: totalAmount, fee: bookingFee });
+
   // Keep only positive quantities in state — a ticket dropped to 0 is removed
   // entirely, so `items` never carries a 0-quantity entry (the orders endpoint
   // rejects those with "quantity must be positive").
@@ -151,6 +183,11 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
         couponId: data.couponId ?? null,
         appliedCoupons: data.appliedCoupons ?? [],
       });
+      // From here on the fee on screen is the fee on the card. `?? 0` rather
+      // than `?? null`: the response always carries it, and a free order
+      // legitimately reports 0 — falling back to the estimate there would put a
+      // fee on a comp.
+      setServerFeeAmount(data.feeAmount ?? 0);
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, data.orderId)}`;
       setReturnUrl(ru);
@@ -185,6 +222,10 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     // The started payment described the DISCOUNTED order; leaving it would keep
     // the reduced total on screen after the discount is gone.
     flow.reset();
+    // Same reason: the abandoned order's fee was a percentage of the DISCOUNTED
+    // subtotal, so keeping it would understate the fee on the fresh, full-price
+    // order the next `continueToPayment` creates.
+    setServerFeeAmount(null);
     setStep("details");
   };
 
@@ -199,9 +240,27 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     // The server's figure wins the moment there is one: start-payment first,
     // then the order response (which is already net of any discount), and only
     // the locally summed ticket prices before either exists.
-    totalAmount: flow.result?.totalAmount ?? coupon.quote?.totalAmount ?? totalAmount,
-    /** GROSS ticket total, before any discount. */
+    //
+    // Both server figures already INCLUDE the booking fee — `total_amount` has
+    // always been raised by it. The local sum did not, which is what made the
+    // pre-payment "Total" a number the buyer would not be charged; the estimated
+    // fee is added so the figure on screen means what it says.
+    totalAmount:
+      flow.result?.totalAmount ?? coupon.quote?.totalAmount ?? totalAmount + bookingFeeAmount,
+    /** GROSS ticket total, before any discount OR booking fee. */
     subTotal: coupon.quote?.subTotal ?? totalAmount,
+    /**
+     * The resolved fee RULE, for surfaces that quote a price with no cart behind
+     * it (an event page's "From $25"). `null` when the artist charges none.
+     */
+    bookingFee,
+    /**
+     * The fee for THIS selection — the server's own number once an order exists,
+     * an estimate off the rule before that. Zero when nothing is charged, which
+     * is what every surface checks before drawing the line: a "+$0.00 booking
+     * fee" row invents a charge that does not exist.
+     */
+    bookingFeeAmount,
     /** Discount code state + the server's quote. See `useCouponField`. */
     coupon,
     clearCoupon,

package/src/ui/headless/membership/MembershipGate.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { getMembershipAccess } from "../../../utils/membershipAccess";
 
 export interface MembershipGateState {
   hasAccess: boolean;
@@ -28,10 +29,14 @@ export interface MembershipGateProps {
 export function MembershipGate({ tiers, access, children, fallback }: MembershipGateProps) {
   const { user, isAuthenticated } = usePublicAuth();
   const membership = user?.membership;
-  const activeMembership = !!membership && membership.status === "active";
+  // The SERVER's access decision, not a `status === "active"` compare. That
+  // compare locked out members in `past_due`/`grace` — states the backend
+  // deliberately keeps access through — so a card that bounced cost them the
+  // content they were still paying for.
+  const membershipGrantsAccess = getMembershipAccess(membership).hasAccess;
   const tierAllows = !tiers?.length || (membership ? tiers.includes(membership.membershipTierId) : false);
 
-  const hasAccess = access ?? (activeMembership && tierAllows);
+  const hasAccess = access ?? (membershipGrantsAccess && tierAllows);
 
   if (hasAccess) return <>{children}</>;
   if (typeof fallback === "function") return <>{fallback({ hasAccess, isAuthenticated })}</>;

package/src/ui/index.ts

@@ -72,10 +72,18 @@ export { MembershipTiers, type MembershipTiersProps } from "./styled/MembershipT
 export { EventsList, type EventsListProps } from "./styled/EventsList";
 export { EventTickets, type EventTicketsProps } from "./styled/EventTickets";
 export { EventCountdown, type EventCountdownProps } from "./styled/EventCountdown";
+export { EventWaitlist, type EventWaitlistProps, formatCountdown } from "./styled/EventWaitlist";
 export { EventDetail, type EventDetailProps } from "./styled/EventDetail";
+// Phase 5 — the page for a NAMED, multi-date series. The API refuses anything
+// else, so this component never has to decide whether a series is publishable.
+export { EventSeriesDetail, type EventSeriesDetailProps } from "./styled/EventSeriesDetail";
 export { AddToCalendar, type AddToCalendarProps } from "./styled/AddToCalendar";
+export { WalletPassButtons, type WalletPassButtonsProps } from "./styled/WalletPassButtons";
 export { CoachingBooking, type CoachingBookingProps } from "./styled/CoachingBooking";
 export { CoachingDetail, type CoachingDetailProps } from "./styled/CoachingDetail";
+// S.6 — the buyer-facing cancellation policy block. Exported so a code site that
+// lays out its own booking page still has ONE renderer for these terms.
+export { CancellationTerms, type CancellationTermsProps } from "./styled/CancellationTerms";
 export { CourseCheckout, type CourseCheckoutProps } from "./styled/CourseCheckout";
 export { CourseDetail, type CourseDetailProps } from "./styled/CourseDetail";
 export { PostsFeed, type PostsFeedProps } from "./styled/PostsFeed";
@@ -85,6 +93,12 @@ export { SignupForm, type SignupFormProps } from "./styled/SignupForm";
 export { ForgotPasswordForm, type ForgotPasswordFormProps } from "./styled/ForgotPasswordForm";
 export { ResetPasswordForm, type ResetPasswordFormProps } from "./styled/ResetPasswordForm";
 export { AccountDashboard, type AccountDashboardProps, type AccountTabKey, ACCOUNT_TABS } from "./styled/AccountDashboard";
+export {
+  TicketTransferPanel,
+  type TicketTransferPanelProps,
+  ClaimTicketTransfer,
+  type ClaimTicketTransferProps,
+} from "./styled/TicketTransfer";
 export { AudioPlayer, type AudioPlayerProps } from "./styled/AudioPlayer";
 export { ForgeAnalytics, type ForgeAnalyticsProps } from "./analytics/ForgeAnalytics";
 export { PageMetaPixel, usePageMetaPixel, type PageMetaPixelProps } from "./analytics/PageMetaPixel";
@@ -134,6 +148,10 @@ export { DonationPage, type DonationPageProps } from "./styled/DonationPage";
 export { ReviewsSection, StarRow, type ReviewsSectionProps } from "./styled/ReviewsSection";
 export { ReviewForm, type ReviewFormProps } from "./styled/ReviewForm";
 export { PriceDisplay, priceTaxCaption, summarizeTaxQuote, type PriceDisplayProps } from "./format/PriceDisplay";
+// The artist's booking fee, for a site rendering its own ticket UI rather than
+// the styled blocks. Resolution stays on the server (`IEvent.bookingFee`); these
+// only do the arithmetic and the wording.
+export { computeBookingFeeAmount, hasBookingFee, describeBookingFee } from "./format/bookingFee";
 export { usePricesIncludeTax } from "../data/queries/useWebsite";
 
 // PWA (installable code sites) — SW registration + install/push UX (Tier 2).
@@ -141,6 +159,17 @@ export { PwaRegistration, type PwaRegistrationProps } from "./styled/PwaRegistra
 export { InstallBanner, type InstallBannerProps } from "./styled/InstallBanner";
 // The single root component — providers + audio + analytics + PWA + consent in one.
 export { TribeNestApp, type TribeNestAppProps } from "./shell/TribeNestApp";
+// The SSR-bootstrap failure banner + its gating. Exported so a bespoke shell that
+// doesn't use <TribeNestApp> can still fail loudly instead of silently rendering
+// Forge's defaults when the API is unreachable.
+export { PreviewDiagnostics } from "./shell/PreviewDiagnostics";
+export {
+  previewDiagnosticsEnabled,
+  resolvePreviewDiagnostics,
+  previewDiagnosticsMessage,
+  type PreviewDiagnosticsMessage,
+} from "./shell/diagnosticsGating";
+export type { ApiProbeResult, ForgeSsrDiagnostics, SsrFetchFailure } from "../types/diagnostics";
 export { PushOptIn, type PushOptInProps } from "./styled/PushOptIn";
 
 // Community (forum) styled blocks.

package/src/ui/shell/PoweredBy.tsx

@@ -1,7 +1,6 @@
+import { useForge } from "../../provider/ForgeProvider";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
-
-/** Where the badge points. utm params so the referral traffic is attributable. */
-const HREF = "https://tribenest.co/?utm_source=powered_by&utm_medium=badge&utm_campaign=creator_site";
+import { poweredByHref } from "./shellGating";
 
 export interface PoweredByProps {
   /** Live released build only — see `shellPoweredByEnabled`. */
@@ -27,7 +26,10 @@ export interface PoweredByProps {
  */
 export function PoweredBy({ enabled = true }: PoweredByProps) {
   const t = useThemeTokens();
+  const { subdomain, profileId, appId } = useForge();
   if (!enabled) return null;
+  // Tagged from the identity ForgeProvider was built with — see `poweredByHref`.
+  const href = poweredByHref({ subdomain, profileId, appId });
   return (
     <div
       style={{
@@ -39,7 +41,7 @@ export function PoweredBy({ enabled = true }: PoweredByProps) {
       }}
     >
       <a
-        href={HREF}
+        href={href}
         target="_blank"
         // nofollow: the same link on every site we host is exactly the pattern
         // Google reads as a link scheme. Drop it if the SEO value is judged

package/src/ui/shell/PreviewDiagnostics.tsx

@@ -0,0 +1,80 @@
+import { useState } from "react";
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
+import { previewDiagnosticsMessage } from "./diagnosticsGating";
+
+/**
+ * The loud failure. Rendered by `<TribeNestApp>` in the builder preview and on
+ * review Workers — never on the live published site (see
+ * `previewDiagnosticsEnabled`).
+ *
+ * EVERY COLOR HERE IS A LITERAL, on purpose. This banner announces that the
+ * theme could not be fetched, so it cannot itself be themed: `var(--forge-*)`
+ * would resolve to the very fallbacks it is warning about, and on a dark-ish
+ * default it could render invisible. It is also the one component that must
+ * survive a totally broken render, so it takes nothing from context.
+ */
+export function PreviewDiagnostics({ diagnostics }: { diagnostics: ForgeSsrDiagnostics }) {
+  const [open, setOpen] = useState(false);
+  const msg = previewDiagnosticsMessage(diagnostics);
+
+  return (
+    <div
+      role="alert"
+      style={{
+        position: "fixed",
+        top: 0,
+        left: 0,
+        right: 0,
+        // Above anything a site can reasonably stack, including sticky navs.
+        zIndex: 2147483000,
+        background: "#7f1d1d",
+        color: "#fef2f2",
+        borderBottom: "1px solid #dc2626",
+        fontFamily:
+          'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+        fontSize: 13,
+        lineHeight: 1.45,
+        boxShadow: "0 2px 12px rgba(0,0,0,0.35)",
+      }}
+    >
+      <div style={{ maxWidth: 900, margin: "0 auto", padding: "10px 14px" }}>
+        <div style={{ display: "flex", alignItems: "flex-start", gap: 10 }}>
+          <span aria-hidden style={{ fontSize: 15, lineHeight: 1.3 }}>
+            ⚠️
+          </span>
+          <div style={{ flex: 1, minWidth: 0 }}>
+            <strong style={{ fontWeight: 700 }}>{msg.title}</strong>
+            <div style={{ marginTop: 3, color: "#fecaca" }}>{msg.consequence}</div>
+          </div>
+          <button
+            type="button"
+            onClick={() => setOpen((v) => !v)}
+            aria-expanded={open}
+            style={{
+              flexShrink: 0,
+              background: "transparent",
+              border: "1px solid #f87171",
+              borderRadius: 6,
+              color: "#fef2f2",
+              cursor: "pointer",
+              fontSize: 12,
+              padding: "3px 9px",
+            }}
+          >
+            {open ? "Hide" : "Details"}
+          </button>
+        </div>
+
+        {open && (
+          <ul style={{ margin: "9px 0 0", padding: "0 0 0 26px", color: "#fecaca" }}>
+            {msg.details.map((line) => (
+              <li key={line} style={{ marginTop: 2, wordBreak: "break-word" }}>
+                {line}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}