@tribe-nest/forge 2.2.0 → 3.4.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/headless/work/useWorkPortal.ts

@@ -1,9 +1,4 @@
-import {
-  useMutation,
-  useQuery,
-  useQueryClient,
-  type UseQueryResult,
-} from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient, type UseQueryResult } from "@tanstack/react-query";
 import { useForge } from "../../../provider/ForgeProvider";
 
 /**
@@ -113,10 +108,24 @@ export interface WorkInviteContext {
   profileName: string;
   email: string;
   firstName: string | null;
+  /**
+   * The invited address already has an account, so the invite grants portal
+   * access but cannot set a credential — render "sign in", not a password
+   * form (C10).
+   */
+  requiresExistingLogin?: boolean;
 }
 
 export interface WorkInviteAcceptResult {
-  token: string;
+  /**
+   * True when the invited address already has an account: the invite granted
+   * portal access but issued NO session, and the person signs in normally
+   * (C10). `token` is absent in that case.
+   */
+  requiresLogin?: boolean;
+  token?: string;
+  /** Rotating refresh token for the portal session (backend §7) — persist it. */
+  refreshToken?: string;
   projectId: string;
   account: { id: string; email: string; firstName: string | null; lastName: string | null };
 }
@@ -125,8 +134,7 @@ export interface WorkInviteAcceptResult {
 
 const keys = {
   projects: (profileId?: string) => ["work-portal-projects", profileId] as const,
-  report: (profileId: string | undefined, projectId: string) =>
-    ["work-portal-report", profileId, projectId] as const,
+  report: (profileId: string | undefined, projectId: string) => ["work-portal-report", profileId, projectId] as const,
   tokenReport: (token: string) => ["work-portal-token-report", token] as const,
   taskComments: (profileId: string | undefined, projectId: string, taskId: string) =>
     ["work-portal-task-comments", profileId, projectId, taskId] as const,
@@ -212,10 +220,9 @@ export function useWorkTaskComments(projectId: string, taskId: string): UseWorkT
   const query = useQuery<WorkTaskComment[]>({
     queryKey: keys.taskComments(profileId, projectId, taskId),
     queryFn: async () => {
-      const res = await client.get(
-        `/public/work/projects/${projectId}/tasks/${taskId}/comments`,
-        { params: { profileId } },
-      );
+      const res = await client.get(`/public/work/projects/${projectId}/tasks/${taskId}/comments`, {
+        params: { profileId },
+      });
       return res.data as WorkTaskComment[];
     },
     enabled: !!profileId && !!client && !!projectId && !!taskId,
@@ -255,18 +262,14 @@ export function useWorkTaskComments(projectId: string, taskId: string): UseWorkT
  * projects — GET /public/work/projects/:projectId/tasks/:taskId/attachments.
  * Tier-1 primitive: returns clean data, renders nothing.
  */
-export function useWorkTaskAttachments(
-  projectId: string,
-  taskId: string,
-): UseQueryResult<WorkTaskAttachment[]> {
+export function useWorkTaskAttachments(projectId: string, taskId: string): UseQueryResult<WorkTaskAttachment[]> {
   const { client, profileId } = useForge();
   return useQuery<WorkTaskAttachment[]>({
     queryKey: keys.taskAttachments(profileId, projectId, taskId),
     queryFn: async () => {
-      const res = await client.get(
-        `/public/work/projects/${projectId}/tasks/${taskId}/attachments`,
-        { params: { profileId } },
-      );
+      const res = await client.get(`/public/work/projects/${projectId}/tasks/${taskId}/attachments`, {
+        params: { profileId },
+      });
       return res.data as WorkTaskAttachment[];
     },
     enabled: !!profileId && !!client && !!projectId && !!taskId,

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";
@@ -67,6 +73,7 @@ export { EventsList, type EventsListProps } from "./styled/EventsList";
 export { EventTickets, type EventTicketsProps } from "./styled/EventTickets";
 export { EventCountdown, type EventCountdownProps } from "./styled/EventCountdown";
 export { EventDetail, type EventDetailProps } from "./styled/EventDetail";
+export { AddToCalendar, type AddToCalendarProps } from "./styled/AddToCalendar";
 export { CoachingBooking, type CoachingBookingProps } from "./styled/CoachingBooking";
 export { CoachingDetail, type CoachingDetailProps } from "./styled/CoachingDetail";
 export { CourseCheckout, type CourseCheckoutProps } from "./styled/CourseCheckout";

package/src/ui/shell/PoweredBy.tsx

@@ -0,0 +1,60 @@
+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";
+
+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();
+  if (!enabled) return null;
+  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/TribeNestApp.tsx

@@ -6,7 +6,9 @@ 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 { shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
 import { captureAttributionRefFromUrl, readAttributionRef } from "../../utils/attribution";
 import { captureLandingFromUrl, postLandingBeacon } from "../../utils/landing";
 
@@ -65,6 +67,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
@@ -100,6 +111,9 @@ export function TribeNestApp({
   return (
     <ForgeProvider editable={editable} {...forgeProps}>
       {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 />

package/src/ui/shell/shellGating.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { shellPwaEnabled } from "./shellGating";
+import { shellPoweredByEnabled, shellPwaEnabled } from "./shellGating";
 
 // The PWA (SW register + install prompt) must be ON only for the live published
 // site, and OFF everywhere else (editor, preview/draft), so review Workers never
@@ -26,3 +26,23 @@ describe("shellPwaEnabled", () => {
     expect(shellPwaEnabled({ editable: false, state: "published" })).toBe(true);
   });
 });
+
+// "Powered by TribeNest" ships on released builds only, and the ONLY way to
+// remove it is the server-supplied flag — there is no client-side opt-out,
+// because the tenant owns __root.tsx.
+describe("shellPoweredByEnabled", () => {
+  it("is true on a live published site", () => {
+    expect(shellPoweredByEnabled({ editable: false, state: "published" })).toBe(true);
+  });
+
+  it("is false in the editor and on draft/preview deploys", () => {
+    expect(shellPoweredByEnabled({ editable: true, state: "published" })).toBe(false);
+    expect(shellPoweredByEnabled({ editable: false, state: "draft" })).toBe(false);
+    expect(shellPoweredByEnabled({ editable: false })).toBe(false); // state undefined
+  });
+
+  it("is false only when the SERVER says to hide it", () => {
+    expect(shellPoweredByEnabled({ editable: false, state: "published", hideBadge: true })).toBe(false);
+    expect(shellPoweredByEnabled({ editable: false, state: "published", hideBadge: false })).toBe(true);
+  });
+});

package/src/ui/shell/shellGating.ts

@@ -9,3 +9,17 @@ export function shellPwaEnabled(opts: {
 }): boolean {
   return (opts.pwa ?? true) && !opts.editable && opts.state === "published";
 }
+
+// "Powered by TribeNest" shows on RELEASED builds only — the live published
+// site, never the HMR editor or a preview-<versionId>.* review Worker. Same
+// released-build test as the PWA, with one extra lever: `hideBadge` comes from
+// the server (`siteConfig.hideTribeNestBadge`), which is where a white-label
+// plan entitlement turns it off. It is deliberately not a `TribeNestApp` prop —
+// the tenant owns __root.tsx, so a prop would make the badge opt-out.
+export function shellPoweredByEnabled(opts: {
+  editable?: boolean;
+  state?: "draft" | "published";
+  hideBadge?: boolean;
+}): boolean {
+  return !opts.hideBadge && !opts.editable && opts.state === "published";
+}

package/src/ui/styled/AddToCalendar.tsx

@@ -0,0 +1,104 @@
+import { CalendarPlus } from "lucide-react";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { useAddToCalendar, type AddToCalendarInput } from "../headless/calendar/useAddToCalendar";
+
+export interface AddToCalendarProps extends AddToCalendarInput {
+  /** Heading above the provider links. Pass `null` to drop it entirely. */
+  label?: string | null;
+  /**
+   * `compact` renders a single row of small chips with no heading — for tight
+   * spots like a confirmation card. `default` renders the label + chips.
+   */
+  variant?: "default" | "compact";
+  /** Extra class(es) appended to the root element. */
+  className?: string;
+  /** Inline style merged LAST into the root element (callers can override). */
+  style?: React.CSSProperties;
+}
+
+/**
+ * "Add to calendar" — deep links that prefill Google / Outlook / Microsoft 365
+ * with the event, plus an `.ics` download when the host supplies one (that is
+ * the Apple Calendar route; there is no Apple web endpoint to link to).
+ *
+ * Purely presentational: every URL comes from `useAddToCalendar`. Renders
+ * nothing at all when the start time is missing or unparseable.
+ */
+export function AddToCalendar({
+  label = "Add to calendar",
+  variant = "default",
+  className,
+  style,
+  ...input
+}: AddToCalendarProps) {
+  const t = useThemeTokens();
+  const links = useAddToCalendar(input);
+
+  if (!links) return null;
+
+  const compact = variant === "compact";
+
+  const options: { key: string; text: string; href: string; download?: boolean }[] = [
+    { key: "google", text: "Google", href: links.google },
+    { key: "outlook", text: "Outlook", href: links.outlook },
+    { key: "office365", text: "Microsoft 365", href: links.office365 },
+  ];
+  if (links.ics) options.push({ key: "ics", text: "Apple / .ics", href: links.ics, download: true });
+
+  const chip: React.CSSProperties = {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: 6,
+    padding: compact ? "5px 10px" : "7px 12px",
+    fontSize: compact ? 12 : 13,
+    fontWeight: 600,
+    lineHeight: 1.2,
+    color: t.text,
+    textDecoration: "none",
+    border: `1px solid ${t.border}`,
+    borderRadius: t.cornerRadius,
+    background: t.surface,
+    fontFamily: t.fontFamily,
+  };
+
+  return (
+    <div
+      data-testid="add-to-calendar"
+      className={className}
+      style={{ display: "flex", flexDirection: "column", gap: compact ? 6 : 8, ...style }}
+    >
+      {label && !compact && (
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 6,
+            fontSize: 13,
+            fontWeight: 700,
+            color: t.muted,
+            fontFamily: t.fontFamily,
+          }}
+        >
+          <CalendarPlus size={15} color={t.primary} /> {label}
+        </span>
+      )}
+
+      <div style={{ display: "flex", flexWrap: "wrap", gap: 8 }}>
+        {compact && <CalendarPlus size={15} color={t.primary} style={{ alignSelf: "center" }} />}
+        {options.map((o) => (
+          <a
+            key={o.key}
+            href={o.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            data-testid={`add-to-calendar-${o.key}`}
+            {...(o.download ? { download: "" } : {})}
+            style={chip}
+          >
+            {o.text}
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+}