@tribe-nest/forge 3.2.0 → 3.9.0

package/src/ui/headless/course/useCourseCheckout.ts

@@ -1,7 +1,8 @@
-import { useState } from "react";
+import { useCallback, useRef, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
-import { useGetCourse, useCreateCourseBooking } from "../../../data/queries/useCourses";
+import { useGetCourse, useCreateCourseBooking, useUpdateCourseBooking } from "../../../data/queries/useCourses";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { useCouponField, type CouponQuoteFn } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -21,8 +22,15 @@ const errMessage = (e: unknown) =>
 
 /**
  * Headless course purchase: buyer details → payment. Composes `useGetCourse`,
- * `useCreateCourseBooking`, `usePaymentFlow`. Free courses skip payment and
- * redirect to the finalise page. Finalize via `useCourseBookingFinalize`.
+ * `useCreateCourseBooking`, `useUpdateCourseBooking`, `usePaymentFlow`. Free
+ * courses skip payment and redirect to the finalise page. Finalize via
+ * `useCourseBookingFinalize`.
+ *
+ * `POST /public/courses/:id/bookings` takes NO coupon code — the course pillar
+ * accepts one only on `booking/update`, which exists to be called repeatedly and
+ * re-derives the gross price from the course each time. So a booking is created
+ * as soon as the buyer applies a code, and reused from then on. A buyer who
+ * never touches the discount field takes exactly the path this hook always took.
  */
 export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions = {}) {
   const { user } = usePublicAuth();
@@ -30,6 +38,7 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
   const { data: course, isLoading } = useGetCourse(slug);
   const courseId = course?.id;
   const createBooking = useCreateCourseBooking(courseId);
+  const updateBooking = useUpdateCourseBooking(courseId);
   const flow = usePaymentFlow({ path: `/public/courses/${courseId}/start-payment`, autoStart: false });
 
   const [step, setStep] = useState<CourseCheckoutStep>("details");
@@ -39,10 +48,58 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /** The booking created for quoting, reused so a code never mints a second one. */
+  const bookingIdRef = useRef<string | null>(null);
 
   const finalisePath =
     opts.finalisePath ?? ((s, bookingId) => `/i/courses/${s}/finalise?bookingId=${bookingId}`);
 
+  const requireBuyerDetails = () => {
+    if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      throw new Error("Enter your name and a valid email before applying a code.");
+    }
+  };
+
+  /** Create the booking once; every later call reuses it. */
+  const ensureBooking = async (): Promise<string> => {
+    if (bookingIdRef.current) return bookingIdRef.current;
+    const created = await createBooking.mutateAsync({
+      email,
+      firstName,
+      lastName,
+      questionnaire,
+      attributionRefId: readAttributionRef() ?? undefined,
+      ...(readLanding() ?? {}),
+    });
+    bookingIdRef.current = created.bookingId;
+    return created.bookingId;
+  };
+
+  /**
+   * `confirmIfFree` is false here on purpose: quoting a code must never be able
+   * to complete an enrollment. Only "Continue" confirms.
+   */
+  const quoteCoupon: CouponQuoteFn = useCallback(
+    async (code) => {
+      if (!courseId) throw new Error("This course is not available.");
+      requireBuyerDetails();
+      const bookingId = await ensureBooking();
+      return updateBooking.mutateAsync({
+        bookingId,
+        email,
+        firstName,
+        lastName,
+        confirmIfFree: false,
+        questionnaire,
+        couponCode: code ?? undefined,
+      });
+    },
+    // `createBooking`/`updateBooking` are stable react-query mutation objects.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [courseId, firstName, lastName, email, questionnaire],
+  );
+  const coupon = useCouponField(quoteCoupon);
+
   const continueToPayment = async () => {
     setError(null);
     if (!slug || !courseId) return;
@@ -51,27 +108,56 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
       return;
     }
     try {
-      const data = await createBooking.mutateAsync({
-        email,
-        firstName,
-        lastName,
-        questionnaire,
-        attributionRefId: readAttributionRef() ?? undefined,
-        ...(readLanding() ?? {}),
-      });
+      // A discount can only be recorded through `booking/update`, so any buyer
+      // who touched the code field settles through that endpoint. Everyone else
+      // keeps the original create-only path, unchanged.
+      const usesCoupon = !!coupon.submittedCode || !!bookingIdRef.current;
+      let bookingId: string;
+      let isFree: boolean;
+
+      if (usesCoupon) {
+        bookingId = await ensureBooking();
+        const updated = await updateBooking.mutateAsync({
+          bookingId,
+          email,
+          firstName,
+          lastName,
+          confirmIfFree: true,
+          questionnaire,
+          couponCode: coupon.submittedCode,
+        });
+        coupon.record(updated);
+        isFree = updated.isConfirmed;
+      } else {
+        const data = await createBooking.mutateAsync({
+          email,
+          firstName,
+          lastName,
+          questionnaire,
+          attributionRefId: readAttributionRef() ?? undefined,
+          ...(readLanding() ?? {}),
+        });
+        bookingIdRef.current = data.bookingId;
+        bookingId = data.bookingId;
+        isFree = !!data.isFree;
+      }
+
       const origin = typeof window !== "undefined" ? window.location.origin : "";
-      const ru = `${origin}${finalisePath(slug, data.bookingId)}`;
+      const ru = `${origin}${finalisePath(slug, bookingId)}`;
       setReturnUrl(ru);
-      if (data.isFree) {
-        if (opts.onComplete) opts.onComplete({ slug, bookingId: data.bookingId });
+      if (isFree) {
+        if (opts.onComplete) opts.onComplete({ slug, bookingId });
         else if (typeof window !== "undefined") window.location.href = ru;
         return;
       }
-      const result = await flow.start({ bookingId: data.bookingId, returnUrl: ru });
+      const result = await flow.start({ bookingId, returnUrl: ru });
       if (result.provider && result.provider !== "stripe") return;
       setStep("payment");
     } catch (e) {
-      setError(errMessage(e));
+      // With a code entered, the API's rejection reason belongs at the field the
+      // buyer used, not in the generic error slot.
+      if (coupon.submittedCode) coupon.fail(e);
+      else setError(errMessage(e));
     }
   };
 
@@ -90,10 +176,19 @@ export function useCourseCheckout(slug?: string, opts: UseCourseCheckoutOptions
     setQuestionnaire,
     continueToPayment,
     clientSecret: flow.clientSecret,
+    // The booking quote WINS over start-payment: every `continueToPayment`
+    // re-quotes before starting the payment, and applying or removing a code
+    // re-quotes again — so the quote is never staler, and preferring the
+    // payment result would leave a removed discount on screen.
+    totalAmount: coupon.quote?.totalAmount ?? flow.result?.totalAmount ?? (course ? Number(course.price) : undefined),
+    /** GROSS course price, before any discount. */
+    subTotal: coupon.quote?.subTotal ?? (course ? Number(course.price) : undefined),
+    /** Discount code state + the server's quote. See `useCouponField`. */
+    coupon,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     returnUrl,
-    isProcessing: createBooking.isPending || flow.isStarting,
+    isProcessing: createBooking.isPending || updateBooking.isPending || flow.isStarting,
     error,
   };
 }

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

@@ -3,6 +3,7 @@ import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import { useCart } from "../../../contexts/CartContext";
 import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { useCouponField } from "../coupon/useCouponField";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -47,6 +48,19 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
 
+  /**
+   * Discount code — STAGED, not quoted.
+   *
+   * Tickets have no apply-coupon endpoint and no quote endpoint: `POST
+   * /public/events/:id/orders` is what redeems a code, and it creates the order
+   * row. Pricing a code by calling it would leave a real abandoned order (and a
+   * released inventory hold) behind every keystroke, so no quote function is
+   * passed here. The code rides along on `continueToPayment`, and the order
+   * response — which carries `subTotal`, `discountAmount` and every applied
+   * coupon — is recorded as the quote.
+   */
+  const coupon = useCouponField();
+
   const totalAmount = useMemo(() => {
     if (!event) return 0;
     return event.tickets.reduce((sum, t) => sum + t.price * (selectedTickets[t.id] ?? 0), 0);
@@ -124,9 +138,19 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
         firstName,
         lastName,
         questionnaire,
+        couponCode: coupon.submittedCode,
         attributionRefId: readAttributionRef() ?? undefined,
         ...(readLanding() ?? {}),
       });
+      // What the server actually charged and why — including any AUTOMATIC
+      // discount the buyer never asked for, which nothing else would reveal.
+      coupon.record({
+        subTotal: data.subTotal ?? data.totalAmount ?? totalAmount,
+        totalAmount: data.totalAmount ?? totalAmount,
+        discountAmount: data.discountAmount ?? 0,
+        couponId: data.couponId ?? null,
+        appliedCoupons: data.appliedCoupons ?? [],
+      });
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, data.orderId)}`;
       setReturnUrl(ru);
@@ -141,10 +165,29 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       if (result.provider && result.provider !== "stripe") return; // Paystack redirected
       setStep("payment");
     } catch (e) {
-      setError(errMessage(e));
+      // A refused code fails the whole request, so with one entered the message
+      // belongs next to the field the buyer just used. The message is the API's
+      // own — "This coupon has expired", "…does not reach this coupon's minimum
+      // spend" — never a house "invalid code" that hides which it was.
+      if (coupon.submittedCode) coupon.fail(e);
+      else setError(errMessage(e));
     }
   };
 
+  /**
+   * Drop the code and go back to re-enter details. There is nothing to un-apply
+   * server-side: the order was created WITH the discount and is simply left
+   * behind, exactly as pressing "Back" already does. The next
+   * `continueToPayment` creates a fresh, undiscounted order.
+   */
+  const clearCoupon = () => {
+    coupon.reset();
+    // The started payment described the DISCOUNTED order; leaving it would keep
+    // the reduced total on screen after the discount is gone.
+    flow.reset();
+    setStep("details");
+  };
+
   return {
     event,
     isLoading,
@@ -153,7 +196,15 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     selectedTickets,
     setTicketQty,
     ticketCount,
-    totalAmount: flow.result?.totalAmount ?? totalAmount,
+    // 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. */
+    subTotal: coupon.quote?.subTotal ?? totalAmount,
+    /** Discount code state + the server's quote. See `useCouponField`. */
+    coupon,
+    clearCoupon,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     firstName,

package/src/ui/headless/index.ts

@@ -23,6 +23,13 @@ export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
 // 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, type UseEventCheckoutOptions, type EventCheckoutStep } from "./event/useEventCheckout";
+export {
+  useCouponField,
+  apiErrorMessage,
+  couponFailureMessage,
+  type CouponField,
+  type CouponQuoteFn,
+} from "./coupon/useCouponField";
 export { useCourseCheckout, type UseCourseCheckoutOptions, type CourseCheckoutStep } from "./course/useCourseCheckout";
 export {
   useCoachingBooking,
@@ -43,6 +50,14 @@ export { useMessageThread, type UseMessageThreadResult } from "./chat/useMessage
 export { useChatAttachmentUpload, type PendingAttachment } from "./chat/useChatAttachmentUpload";
 export { attachmentKind, formatBytes, type AttachmentKind } from "./chat/attachmentKind";
 export { useCookieConsent, type UseCookieConsentResult } from "./consent/useCookieConsent";
+export {
+  useAddToCalendar,
+  buildAddToCalendarLinks,
+  toUtcBasic,
+  stripHtml,
+  type AddToCalendarInput,
+  type AddToCalendarLinks,
+} from "./calendar/useAddToCalendar";
 
 export { usePodcastPlayer, type UsePodcastPlayerOptions, type PodcastPlayerState } from "./podcast/usePodcastPlayer";
 

package/src/ui/index.ts

@@ -45,6 +45,12 @@ export {
 export { DonationButton, type DonationButtonProps } from "./styled/DonationButton";
 export { OfferButton, type OfferButtonProps } from "./styled/OfferButton";
 export { Checkout, type CheckoutProps } from "./styled/Checkout";
+export {
+  DiscountCodeField,
+  type DiscountCodeFieldProps,
+  DiscountSummaryLines,
+  type DiscountSummaryLinesProps,
+} from "./styled/DiscountCode";
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
 export { Cart, type CartProps } from "./styled/Cart";
@@ -66,7 +72,10 @@ 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";
+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";
 export { CourseCheckout, type CourseCheckoutProps } from "./styled/CourseCheckout";
@@ -78,6 +87,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 +149,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

@@ -0,0 +1,62 @@
+import { useForge } from "../../provider/ForgeProvider";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { poweredByHref } from "./shellGating";
+
+export interface PoweredByProps {
+  /** Live released build only — see `shellPoweredByEnabled`. */
+  enabled?: boolean;
+}
+
+/**
+ * The "Powered by TribeNest" line every released site and app carries.
+ *
+ * Rendered by `TribeNestApp` after the page tree, so it lands BELOW the tenant's
+ * own footer and needs no edit to the tenant-owned `__root.tsx` — a Forge bump
+ * distributes it to every existing site. Both starters (`apps/site-starter` and
+ * `apps/app-starter`) wrap in `TribeNestApp`, so websites and mini-apps are
+ * covered by the same component.
+ *
+ * Deliberately NOT a prop on `TribeNestApp`: the tenant owns `__root.tsx`, so an
+ * opt-out prop is an opt-out. Removal is a server-side decision instead —
+ * `siteConfig.hideTribeNestBadge`, which is how a white-label plan entitlement
+ * will switch it off without waiting for a Forge release to propagate.
+ *
+ * Styled from theme tokens and kept in the normal document flow (not fixed), so
+ * it inherits the site's palette and never collides with the pinned AudioPlayer.
+ */
+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={{
+        display: "flex",
+        justifyContent: "center",
+        padding: "14px 16px",
+        borderTop: `1px solid ${t.border}`,
+        background: t.background,
+      }}
+    >
+      <a
+        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
+        // worth that risk — it is a one-word change.
+        rel="noopener noreferrer nofollow"
+        style={{
+          fontSize: 12,
+          lineHeight: 1,
+          color: t.muted,
+          textDecoration: "none",
+          letterSpacing: 0.2,
+        }}
+      >
+        Powered by <span style={{ fontWeight: 600 }}>TribeNest</span>
+      </a>
+    </div>
+  );
+}

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>
+  );
+}

package/src/ui/shell/TribeNestApp.tsx

@@ -6,7 +6,12 @@ import { PwaRegistration } from "../styled/PwaRegistration";
 import { InstallBanner } from "../styled/InstallBanner";
 import { CookieConsent } from "../styled/CookieConsent";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
-import { shellPwaEnabled } from "./shellGating";
+import { useInitialSiteConfig } from "../../provider/SiteConfigProvider";
+import { PoweredBy } from "./PoweredBy";
+import { PreviewDiagnostics } from "./PreviewDiagnostics";
+import { shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
+import { previewDiagnosticsEnabled, resolvePreviewDiagnostics } from "./diagnosticsGating";
+import type { ForgeSsrDiagnostics } from "../../types/diagnostics";
 import { captureAttributionRefFromUrl, readAttributionRef } from "../../utils/attribution";
 import { captureLandingFromUrl, postLandingBeacon } from "../../utils/landing";
 
@@ -36,6 +41,13 @@ export interface TribeNestAppProps extends Omit<ForgeProviderProps, "children">
   state?: "draft" | "published";
   /** Href for the client-injected manifest link fallback. */
   manifestHref?: string;
+  /**
+   * What failed while bootstrapping this render, from `fetchSiteBootstrap`.
+   * Surfaced as a banner in the editor preview / review Workers only. Optional:
+   * a shell that still calls `fetchContentDocument`/`fetchSiteConfig` separately
+   * gets a less detailed banner inferred from a null `initialSiteConfig`.
+   */
+  diagnostics?: ForgeSsrDiagnostics | null;
   /** Turn individual shell concerns off (all default on). */
   analytics?: boolean;
   pwa?: boolean;
@@ -65,6 +77,15 @@ function PwaHeadClient({ enabled, manifestHref }: { enabled: boolean; manifestHr
   return null;
 }
 
+// Reads the server-supplied site config, so the white-label entitlement can turn
+// the badge off without a Forge release. Must live INSIDE ForgeProvider (that is
+// what mounts SiteConfigProvider), hence a component rather than a call in the
+// TribeNestApp body.
+function PoweredByGate({ editable, state }: { editable?: boolean; state?: "draft" | "published" }) {
+  const siteConfig = useInitialSiteConfig();
+  return <PoweredBy enabled={shellPoweredByEnabled({ editable, state, hideBadge: siteConfig?.hideTribeNestBadge })} />;
+}
+
 /**
  * The single root component for a TribeNest code website. Wrap the page tree once
  * — it owns the whole provider tree (via `ForgeProvider`) PLUS the global shell
@@ -89,6 +110,7 @@ export function TribeNestApp({
   editable,
   state,
   manifestHref = "/manifest.webmanifest",
+  diagnostics,
   analytics = true,
   pwa = true,
   cookieConsent = true,
@@ -97,9 +119,25 @@ export function TribeNestApp({
   // Register the SW + offer install only on the live published site — never in
   // the HMR editor or on a preview-<versionId>.* review Worker (state="draft").
   const pwaEnabled = shellPwaEnabled({ pwa, editable, state });
+  // A failed SSR bootstrap renders a complete-looking page built entirely from
+  // fallbacks — indistinguishable from an unconfigured site. Say so, where the
+  // people who can fix it are looking.
+  const ssrFailure = previewDiagnosticsEnabled({ editable, state })
+    ? resolvePreviewDiagnostics({
+        diagnostics,
+        profileId: forgeProps.profileId,
+        siteConfig: forgeProps.initialSiteConfig,
+        apiUrl: forgeProps.apiUrl,
+      })
+    : null;
   return (
     <ForgeProvider editable={editable} {...forgeProps}>
+      {/* First in the tree: it must render even if everything below it doesn't. */}
+      {ssrFailure && <PreviewDiagnostics diagnostics={ssrFailure} />}
       {children}
+      {/* "Powered by TribeNest" — last in the page flow, so it sits below the
+          tenant's own footer. Released builds only (live + published). */}
+      <PoweredByGate editable={editable} state={state} />
       {/* Global playback bar — self-pins to the viewport bottom, renders nothing
           until a track loads. */}
       <AudioPlayer />