@tribe-nest/forge 3.50.0 → 3.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.50.0",
+  "version": "3.53.0",
   "publishConfig": {
     "access": "public"
   },
@@ -17,7 +17,7 @@
     "src"
   ],
   "scripts": {
-    "build:css": "tailwindcss -i tailwind.input.css -o src/ui/styled/forge-utilities.css && node scripts/wrapForgeCss.mjs",
+    "build:css": "tailwindcss -i tailwind.input.css -o src/ui/styled/forge-utilities.css",
     "prepack": "npm run build:css",
     "check-types": "tsc --noEmit",
     "test": "vitest run",

package/src/data/queries/useCohortEnrolment.ts

@@ -0,0 +1,87 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import type { CourseBooking } from "../../types/models";
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * Buying a seat on a cohort.
+ *
+ * A DIFFERENT CHECKOUT FROM THE SELF-PACED ONE, and not by preference. A cohort
+ * is priced from its `course_pricing_plans` rows, so the buyer picks a PLAN and
+ * the plan is the price: there is no amount, no currency and no coupon field on
+ * this body. `courses.price` is 0 on every cohort course, which is exactly why
+ * the self-paced endpoint refuses one outright rather than selling it for
+ * nothing.
+ *
+ * The plan also decides whether this is one payment or several. An instalment
+ * plan takes a second consent at `start-payment` ("charge me again when nobody
+ * is here"), because instalments 2..n are taken months later by a cron.
+ */
+
+export type CreateCohortEnrolmentInput = {
+  planId: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  questionnaire?: unknown;
+  attributionRefId?: string;
+  browserSessionId?: string;
+};
+
+export type CreateCohortEnrolmentResult = {
+  bookingId: string;
+  /**
+   * The per-booking credential, returned EXACTLY ONCE and never re-readable.
+   * Every later call on this booking must present it. Persist it the instant it
+   * arrives - see `utils/bookingSecret`.
+   */
+  bookingSecret?: string;
+  cohortId: string;
+  planId: string;
+  courseId: string;
+  totalAmount: number;
+  currency: string;
+  installmentCount: number;
+  /** What is charged TODAY. Equals `totalAmount` on a single-payment plan. */
+  firstPaymentAmount: number;
+  isFree: boolean;
+};
+
+/** Reserve a seat on a cohort against one pricing plan. */
+export function useCreateCohortEnrolment(cohortId?: string) {
+  const { client, profileId } = useForge();
+
+  return useMutation<CreateCohortEnrolmentResult, unknown, CreateCohortEnrolmentInput>({
+    mutationFn: async (body) => {
+      const res = await client.post(`/public/cohorts/${cohortId}/enrollments`, {
+        profileId,
+        cohortId,
+        ...body,
+      });
+      return res.data;
+    },
+  });
+}
+
+/**
+ * Finalize a cohort enrolment (`/public/cohorts/:cohortId/finalize`).
+ *
+ * Same shape and same reasoning as the self-paced finalize: the confirmation
+ * page is reached through a provider redirect, so the caller reads the booking
+ * secret back out of `utils/bookingSecret` rather than off in-memory state.
+ */
+export function useCohortEnrolmentFinalize(cohortId?: string, bookingId?: string, bookingSecret?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<CourseBooking>({
+    queryKey: ["cohortEnrolmentStatus", profileId, bookingId],
+    queryFn: async () => {
+      const res = await client.post(`/public/cohorts/${cohortId}/finalize`, {
+        profileId,
+        bookingId,
+        bookingSecret,
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!cohortId && !!bookingId,
+  });
+}

package/src/data/queries/useMyCourses.ts

@@ -0,0 +1,42 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * The courses this fan can open on this site.
+ *
+ * `GET /public/courses/mine` resolves a grant by account OR by verified email,
+ * so a buyer who never clicked the claim link still sees what they paid for.
+ * That matters more here than anywhere: before this, a purchased course was the
+ * one thing a fan could buy and then not find, and the creator's only remedy
+ * was re-sending a claim link by hand.
+ */
+export type MyCourse = {
+  accessId: string;
+  courseId: string;
+  title: string;
+  description: string | null;
+  slug: string | null;
+  cohortId: string | null;
+  currentLessonId: string | null;
+  completedAt: string | null;
+  /** False when the claim link was never used. The course is theirs either way;
+   *  the flag exists so the UI can reassure rather than stay silent. */
+  claimed: boolean;
+  purchasedAt: string;
+};
+
+export function useMyCourses({ accountId, enabled = true }: { accountId?: string; enabled?: boolean } = {}) {
+  const { client, profileId } = useForge();
+
+  return useQuery<MyCourse[]>({
+    // `accountId` is in the key so signing out and back in as someone else
+    // cannot serve the previous fan's courses from cache.
+    queryKey: ["my-courses", accountId, profileId],
+    enabled: Boolean(accountId) && enabled,
+    queryFn: async () => {
+      const res = await client.get("/public/courses/mine", { params: { profileId } });
+      return (res.data ?? []) as MyCourse[];
+    },
+  });
+}

package/src/data/queries/useWebsiteAgent.ts

@@ -8,6 +8,8 @@ export interface WebsiteAgentConfig {
   allowAnonymous?: boolean;
   allowOrderLookup?: boolean;
   allowLeadCapture?: boolean;
+  /** Paths the widget must not appear on. "/blog/*" covers every child. */
+  excludedPaths?: string[];
 }
 
 /** Widget bootstrap config for the profile. When `enabled` is false the widget

package/src/i18n/de.json

@@ -23,6 +23,11 @@
   "forge.account_dashboard.cancelling": "Wird storniert…",
   "forge.account_dashboard.close": "Schließen",
   "forge.account_dashboard.confirm_password": "Neues Passwort bestätigen",
+  "forge.account_dashboard.courses_completed": "Abgeschlossen",
+  "forge.account_dashboard.courses_continue": "Dort weitermachen, wo du aufgehört hast",
+  "forge.account_dashboard.courses_empty": "Noch nichts hier. Gekaufte Kurse erscheinen auf dieser Seite.",
+  "forge.account_dashboard.courses_start": "Starten",
+  "forge.account_dashboard.courses_title": "Deine Kurse",
   "forge.account_dashboard.current_password": "Aktuelles Passwort",
   "forge.account_dashboard.data_export_description": "Exportiere eine Kopie deiner persönlichen Daten.",
   "forge.account_dashboard.data_section_title": "Deine Daten",
@@ -78,6 +83,7 @@
   "forge.account_dashboard.sessions_title": "Meine Sessions",
   "forge.account_dashboard.tab_account": "Konto",
   "forge.account_dashboard.tab_bookings": "Buchungen",
+  "forge.account_dashboard.tab_courses": "Kurse",
   "forge.account_dashboard.tab_membership": "Mitgliedschaft",
   "forge.account_dashboard.tab_notifications": "Mitteilungen",
   "forge.account_dashboard.tab_orders": "Bestellungen",
@@ -529,6 +535,51 @@
   "forge.coaching_detail.about_title": "Über diese Session",
   "forge.coaching_detail.duration_minutes": "{minutes} Minuten",
   "forge.coaching_detail.not_found": "Coaching-Session nicht gefunden.",
+  "forge.cohort_checkout.aria_close": "Schließen",
+  "forge.cohort_checkout.authorise_future_payments": "Autorisiere die späteren Zahlungen dieses Plans.",
+  "forge.cohort_checkout.back": "Zurück",
+  "forge.cohort_checkout.confirm_leave": "Ohne Abschluss verlassen? Dein Platz ist noch nicht reserviert.",
+  "forge.cohort_checkout.continue_to_payment": "Weiter zur Zahlung",
+  "forge.cohort_checkout.details_subtitle": "Wir senden deinen Zugang an diese Adresse.",
+  "forge.cohort_checkout.details_title": "Deine Daten",
+  "forge.cohort_checkout.due_now": "Jetzt fällig",
+  "forge.cohort_checkout.email_placeholder": "E-Mail",
+  "forge.cohort_checkout.first_name_placeholder": "Vorname",
+  "forge.cohort_checkout.installment_note": "{count} Zahlungen insgesamt, zusammen {total}.",
+  "forge.cohort_checkout.last_name_placeholder": "Nachname",
+  "forge.cohort_checkout.no_plans": "Diese Kohorte ist noch nicht zur Anmeldung geöffnet.",
+  "forge.cohort_checkout.pay": "{amount} zahlen",
+  "forge.cohort_checkout.payment_not_configured": "Zahlung ist nicht konfiguriert.",
+  "forge.cohort_checkout.payment_subtitle": "Schließe deine Anmeldung ab, um der Kohorte beizutreten.",
+  "forge.cohort_checkout.payment_title": "Zahlung",
+  "forge.cohort_checkout.plan_in_full": "Auf einmal zahlen",
+  "forge.cohort_checkout.plan_installments": "{count} Zahlungen à {amount}, alle {days} Tage",
+  "forge.cohort_checkout.plan_subtitle": "Wähle, wie du zahlen möchtest.",
+  "forge.cohort_checkout.plan_title": "Plan wählen",
+  "forge.cohort_checkout.preparing_payment": "Zahlung wird vorbereitet...",
+  "forge.cohort_checkout.tax_added": "+ {amount} Steuer",
+  "forge.cohort_checkout.title": "Anmelden",
+  "forge.cohort_checkout.trigger": "Anmelden",
+  "forge.cohort_checkout.working": "Einen Moment...",
+  "forge.cohort_confirmation.body_confirmed": "Du bist dabei, {first_name}. Bis zum Start.",
+  "forge.cohort_confirmation.body_confirmed_no_name": "Du bist dabei. Bis zum Start.",
+  "forge.cohort_confirmation.body_incomplete": "Deine Anmeldung ist {status}. Von dir wird gerade nichts weiter gebraucht.",
+  "forge.cohort_confirmation.emailed": "Wir haben die Details an {email} geschickt.",
+  "forge.cohort_confirmation.explore": "Mehr entdecken",
+  "forge.cohort_confirmation.eyebrow_action_needed": "Aktion nötig",
+  "forge.cohort_confirmation.eyebrow_confirmed": "Angemeldet",
+  "forge.cohort_confirmation.free": "Kostenlos",
+  "forge.cohort_confirmation.loading": "Anmeldung wird bestätigt...",
+  "forge.cohort_confirmation.lost_body": "Dieser Browser kennt diese Anmeldung nicht, wir können sie hier nicht anzeigen. Falls du bezahlt hast, sieh in deinen E-Mails nach der Bestätigung.",
+  "forge.cohort_confirmation.lost_restart": "Zurück zur Kohorte",
+  "forge.cohort_confirmation.lost_title": "Wir können diese Anmeldung hier nicht öffnen",
+  "forge.cohort_confirmation.not_found": "Anmeldung nicht gefunden.",
+  "forge.cohort_confirmation.not_given": "Nicht angegeben",
+  "forge.cohort_confirmation.row_paid": "Heute gezahlt",
+  "forge.cohort_confirmation.row_reference": "Referenz",
+  "forge.cohort_confirmation.row_student": "Teilnehmer",
+  "forge.cohort_confirmation.title_confirmed": "Dein Platz ist sicher",
+  "forge.cohort_confirmation.title_incomplete": "Fast geschafft",
   "forge.cohort_page.curriculum_title": "Lehrplan",
   "forge.cohort_page.date_range": "{start} bis {end}",
   "forge.cohort_page.date_tbd": "Noch offen",
@@ -1242,4 +1293,4 @@
   "forge.user_menu.create_account": "Konto erstellen",
   "forge.user_menu.log_in": "Anmelden",
   "forge.user_menu.log_out": "Abmelden"
-}
+}

package/src/i18n/en.json

@@ -23,6 +23,11 @@
   "forge.account_dashboard.cancelling": "Cancelling…",
   "forge.account_dashboard.close": "Close",
   "forge.account_dashboard.confirm_password": "Confirm new password",
+  "forge.account_dashboard.courses_completed": "Completed",
+  "forge.account_dashboard.courses_continue": "Continue where you left off",
+  "forge.account_dashboard.courses_empty": "Nothing here yet. Courses you buy appear on this page.",
+  "forge.account_dashboard.courses_start": "Start",
+  "forge.account_dashboard.courses_title": "Your courses",
   "forge.account_dashboard.current_password": "Current password",
   "forge.account_dashboard.data_export_description": "Export a copy of your personal data.",
   "forge.account_dashboard.data_section_title": "Your Data",
@@ -78,6 +83,7 @@
   "forge.account_dashboard.sessions_title": "My Sessions",
   "forge.account_dashboard.tab_account": "Account",
   "forge.account_dashboard.tab_bookings": "Bookings",
+  "forge.account_dashboard.tab_courses": "Courses",
   "forge.account_dashboard.tab_membership": "Membership",
   "forge.account_dashboard.tab_notifications": "Notifications",
   "forge.account_dashboard.tab_orders": "Orders",
@@ -529,6 +535,51 @@
   "forge.coaching_detail.about_title": "About this session",
   "forge.coaching_detail.duration_minutes": "{minutes} minutes",
   "forge.coaching_detail.not_found": "Coaching session not found.",
+  "forge.cohort_checkout.aria_close": "Close",
+  "forge.cohort_checkout.authorise_future_payments": "Authorise the later payments on this plan.",
+  "forge.cohort_checkout.back": "Back",
+  "forge.cohort_checkout.confirm_leave": "Leave without finishing? Your seat is not held yet.",
+  "forge.cohort_checkout.continue_to_payment": "Continue to payment",
+  "forge.cohort_checkout.details_subtitle": "We will send your access to this address.",
+  "forge.cohort_checkout.details_title": "Your details",
+  "forge.cohort_checkout.due_now": "Due now",
+  "forge.cohort_checkout.email_placeholder": "Email",
+  "forge.cohort_checkout.first_name_placeholder": "First name",
+  "forge.cohort_checkout.installment_note": "{count} payments in total, {total} altogether.",
+  "forge.cohort_checkout.last_name_placeholder": "Last name",
+  "forge.cohort_checkout.no_plans": "This cohort is not open for enrolment yet.",
+  "forge.cohort_checkout.pay": "Pay {amount}",
+  "forge.cohort_checkout.payment_not_configured": "Payment is not configured.",
+  "forge.cohort_checkout.payment_subtitle": "Complete your enrolment to join the cohort.",
+  "forge.cohort_checkout.payment_title": "Payment",
+  "forge.cohort_checkout.plan_in_full": "Pay in full",
+  "forge.cohort_checkout.plan_installments": "{count} payments of {amount}, every {days} days",
+  "forge.cohort_checkout.plan_subtitle": "Choose how you would like to pay.",
+  "forge.cohort_checkout.plan_title": "Choose a plan",
+  "forge.cohort_checkout.preparing_payment": "Preparing payment...",
+  "forge.cohort_checkout.tax_added": "+ {amount} tax",
+  "forge.cohort_checkout.title": "Enrol",
+  "forge.cohort_checkout.trigger": "Enrol",
+  "forge.cohort_checkout.working": "Working...",
+  "forge.cohort_confirmation.body_confirmed": "You're in, {first_name}. See you at the start.",
+  "forge.cohort_confirmation.body_confirmed_no_name": "You're in. See you at the start.",
+  "forge.cohort_confirmation.body_incomplete": "Your enrolment is {status}. Nothing else is needed from you right now.",
+  "forge.cohort_confirmation.emailed": "We've emailed the details to {email}.",
+  "forge.cohort_confirmation.explore": "Browse more",
+  "forge.cohort_confirmation.eyebrow_action_needed": "Action needed",
+  "forge.cohort_confirmation.eyebrow_confirmed": "Enrolled",
+  "forge.cohort_confirmation.free": "Free",
+  "forge.cohort_confirmation.loading": "Confirming your enrolment...",
+  "forge.cohort_confirmation.lost_body": "This browser has no record of that enrolment, so we cannot show it. If you paid, check your email for the confirmation.",
+  "forge.cohort_confirmation.lost_restart": "Back to the cohort",
+  "forge.cohort_confirmation.lost_title": "We cannot open this enrolment here",
+  "forge.cohort_confirmation.not_found": "Enrolment not found.",
+  "forge.cohort_confirmation.not_given": "Not given",
+  "forge.cohort_confirmation.row_paid": "Paid today",
+  "forge.cohort_confirmation.row_reference": "Reference",
+  "forge.cohort_confirmation.row_student": "Student",
+  "forge.cohort_confirmation.title_confirmed": "You have your seat",
+  "forge.cohort_confirmation.title_incomplete": "Almost there",
   "forge.cohort_page.curriculum_title": "Curriculum",
   "forge.cohort_page.date_range": "{start} to {end}",
   "forge.cohort_page.date_tbd": "TBD",
@@ -1242,4 +1293,4 @@
   "forge.user_menu.create_account": "Create account",
   "forge.user_menu.log_in": "Log in",
   "forge.user_menu.log_out": "Log out"
-}
+}

package/src/index.ts

@@ -109,6 +109,7 @@ export * from "./data/queries/useForms";
 export * from "./data/queries/useReplay";
 export * from "./data/queries/useCoachingAvailability";
 export * from "./data/queries/useCohortPage";
+export * from "./data/queries/useCohortEnrolment";
 export * from "./data/queries/useCourseAccess";
 // Films and series: the catalogue, one title, the buyer's library, the rental
 // money legs, and the three playback-session calls. Everything a custom viewing
@@ -120,6 +121,7 @@ export * from "./data/queries/useAccount";
 export * from "./data/queries/useMyTickets";
 export * from "./data/queries/usePassTransfers";
 export * from "./data/queries/useMyBookings";
+export * from "./data/queries/useMyCourses";
 // The member's own call calendar. Beside `useMyBookings` and `useMyTickets`
 // because it answers the same shape of question: what have I got coming up
 // with this artist, and where do I go for it.

package/src/types/models.ts

@@ -101,6 +101,26 @@ export type PaymentStartResponse = {
   shippingCosts?: { deliveryGroupId: string; amount: number; currency: string }[];
   /** Authoritative sales-tax quote for this charge (all wired pillars). */
   taxQuote?: PublicTaxQuote;
+  /**
+   * COHORT ENROLMENT ONLY: what THIS charge takes, when the plan is paid in
+   * instalments. `totalAmount` above stays the whole plan, so a checkout that
+   * shows only the total tells an instalment buyer they are about to be charged
+   * three times what they will be. Equal to `totalAmount` on a single payment.
+   */
+  installmentAmount?: number;
+  /** COHORT ENROLMENT ONLY: how many payments the chosen plan is split into. */
+  installmentCount?: number;
+  /**
+   * COHORT ENROLMENT ONLY: the SECOND consent, taken before instalment 1.
+   *
+   * Instalments 2..n are charged months later by a cron with nobody present, so
+   * the payer has to agree to be charged off-session. When Stripe needs that
+   * confirmed in the browser, `setupRequiresAction` is true and
+   * `setupClientSecret` is what confirms it. A checkout that ignores these takes
+   * the first payment and then silently fails every later one.
+   */
+  setupRequiresAction?: boolean;
+  setupClientSecret?: string | null;
   /**
    * When the reserved stock goes back on sale, ISO-8601 — the RESTARTED clock,
    * measured from the card form rather than from when the cart was assembled,

package/src/ui/headless/agent/_tests/pathExclusion.spec.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { isPathExcluded } from "../pathExclusion";
+
+/**
+ * The client half of the exclusion rule. It has to agree with the server half
+ * (`apps/backend/src/services/public/agent/pathExclusion.ts`) case for case:
+ * the server decides what gets stored, the browser decides what gets hidden,
+ * and a disagreement shows the widget on a page the artist excluded.
+ */
+describe("isPathExcluded", () => {
+  const patterns = ["/pricing", "/blog/*"];
+
+  it("shows the widget when nothing is excluded", () => {
+    expect(isPathExcluded("/pricing", [])).toBe(false);
+    expect(isPathExcluded("/pricing", undefined)).toBe(false);
+  });
+
+  it("hides it on an exactly named page", () => {
+    expect(isPathExcluded("/pricing", patterns)).toBe(true);
+  });
+
+  it("leaves a sibling that merely shares a prefix alone", () => {
+    expect(isPathExcluded("/pricing-guide", patterns)).toBe(false);
+    expect(isPathExcluded("/blogroll", patterns)).toBe(false);
+  });
+
+  it("hides it under a wildcard, index page included", () => {
+    expect(isPathExcluded("/blog", patterns)).toBe(true);
+    expect(isPathExcluded("/blog/hello", patterns)).toBe(true);
+    expect(isPathExcluded("/blog/2026/hello", patterns)).toBe(true);
+  });
+
+  it("ignores case, a trailing slash and a query string", () => {
+    expect(isPathExcluded("/Blog/Hello/", patterns)).toBe(true);
+    expect(isPathExcluded("/PRICING?ref=email", patterns)).toBe(true);
+  });
+
+  it("treats a bare /* as the whole site", () => {
+    expect(isPathExcluded("/", ["/*"])).toBe(true);
+    expect(isPathExcluded("/anything/deep", ["/*"])).toBe(true);
+  });
+
+  it("hides it on the home page only when '/' is listed", () => {
+    expect(isPathExcluded("/", ["/"])).toBe(true);
+    expect(isPathExcluded("/shop", ["/"])).toBe(false);
+  });
+
+  it("accepts a stored pattern the artist typed loosely", () => {
+    expect(isPathExcluded("/pricing", ["pricing"])).toBe(true);
+    expect(isPathExcluded("/blog/hello", ["/blog/"])).toBe(false);
+  });
+});

package/src/ui/headless/agent/_tests/useCurrentPath.spec.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useCurrentPath } from "../useCurrentPath";
+
+/**
+ * The widget hides itself per page, so it has to notice a page change. Forge
+ * has no router, and a site's in-app link is a `pushState` that fires no event
+ * of its own - which is exactly the case a `popstate`-only listener misses, and
+ * would leave the widget showing on an excluded page for the rest of the visit.
+ */
+describe("useCurrentPath", () => {
+  afterEach(() => {
+    window.history.pushState({}, "", "/");
+  });
+
+  it("reports the path the browser is on", () => {
+    window.history.pushState({}, "", "/pricing");
+    const { result } = renderHook(() => useCurrentPath());
+    expect(result.current).toBe("/pricing");
+  });
+
+  it("follows a pushState navigation, which is every in-app link", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/blog/hello");
+    });
+    expect(result.current).toBe("/blog/hello");
+  });
+
+  it("follows a replaceState navigation too", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.replaceState({}, "", "/shop");
+    });
+    expect(result.current).toBe("/shop");
+  });
+
+  it("ignores the query string, which is not part of the path", () => {
+    const { result } = renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/shop?sort=new");
+    });
+    expect(result.current).toBe("/shop");
+  });
+
+  it("leaves history working for everyone else - the wrap is additive", () => {
+    renderHook(() => useCurrentPath());
+    act(() => {
+      window.history.pushState({}, "", "/one");
+    });
+    expect(window.location.pathname).toBe("/one");
+  });
+});

package/src/ui/headless/agent/pathExclusion.ts

@@ -0,0 +1,53 @@
+/**
+ * Client half of the concierge's "don't appear on these pages" rule.
+ *
+ * The artist stores paths in the admin; the widget hides itself when the page
+ * it is on matches one. Two forms:
+ *   "/pricing"   - that page only
+ *   "/blog/*"    - that page AND everything under it
+ *
+ * Matching is case-insensitive and ignores a trailing slash, so "/blog",
+ * "/Blog" and "/blog/" are one page here as they are to a visitor.
+ *
+ * This must stay in step with the server half,
+ * `apps/backend/src/services/public/agent/pathExclusion.ts`, which normalises
+ * what gets stored. Kept as a copy rather than an import because Forge ships to
+ * creator sites and cannot reach into the backend.
+ */
+
+/** Reduce one stored pattern or page path to the form both sides compare. */
+function normalize(raw: string): string {
+  let path = (raw || "").trim();
+  if (!path) return "";
+  const url = /^https?:\/\/[^/]+(\/.*)?$/i.exec(path);
+  if (url) path = url[1] || "/";
+  path = path.split("#")[0].split("?")[0];
+  if (!path.startsWith("/")) path = `/${path}`;
+  path = path.replace(/\/{2,}/g, "/");
+  const wildcard = path.endsWith("/*");
+  const base = wildcard ? path.slice(0, -2) : path;
+  const cleaned = base.length > 1 ? base.replace(/\/+$/, "") : base;
+  return wildcard ? `${cleaned}/*` : cleaned || "/";
+}
+
+/** Does `path` fall under any of `patterns`? */
+export function isPathExcluded(path: string, patterns: readonly string[] | null | undefined): boolean {
+  if (!patterns || patterns.length === 0) return false;
+  const normalizedTarget = normalize(path);
+  const target = (
+    normalizedTarget.endsWith("/*") ? normalizedTarget.slice(0, -2) || "/" : normalizedTarget
+  ).toLowerCase();
+  for (const raw of patterns) {
+    const pattern = normalize(raw).toLowerCase();
+    if (!pattern) continue;
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      // "/*" alone means the whole site.
+      if (prefix === "") return true;
+      if (target === prefix || target.startsWith(`${prefix}/`)) return true;
+      continue;
+    }
+    if (target === pattern) return true;
+  }
+  return false;
+}

package/src/ui/headless/agent/useAiAgent.ts

@@ -5,6 +5,8 @@ import {
   streamAgentMessage,
   useWebsiteAgentConfig,
 } from "../../../data/queries/useWebsiteAgent";
+import { isPathExcluded } from "./pathExclusion";
+import { useCurrentPath } from "./useCurrentPath";
 
 export interface AiAgentMessage {
   role: "user" | "assistant";
@@ -35,6 +37,7 @@ function getVisitorId(): string {
 export function useAiAgent() {
   const { apiUrl, profileId, token } = useForge();
   const config = useWebsiteAgentConfig();
+  const path = useCurrentPath();
 
   const [messages, setMessages] = useState<AiAgentMessage[]>([]);
   const [sending, setSending] = useState(false);
@@ -94,9 +97,15 @@ export function useAiAgent() {
     [apiUrl, profileId, token, visitorId, sending, ensureConversation],
   );
 
+  // The artist can keep the assistant off named pages. Checked here rather than
+  // in the widget so every UI built on this hook obeys it, including custom
+  // ones. SSR reports no path, so the widget stays hidden until the browser can
+  // say where it is - appearing and then vanishing would be worse.
+  const excluded = !path || isPathExcluded(path, config.data?.excludedPaths);
+
   return {
     config: config.data,
-    isEnabled: !!config.data?.enabled,
+    isEnabled: !!config.data?.enabled && !excluded,
     loading: config.isLoading,
     messages,
     sending,

package/src/ui/headless/agent/useCurrentPath.ts

@@ -0,0 +1,49 @@
+import { useEffect, useState } from "react";
+
+/**
+ * The browser's current path, kept up to date across client-side navigation.
+ *
+ * Forge has no router of its own and ships into sites that do, so it cannot
+ * subscribe to one. `popstate` alone misses a pushState navigation, which is
+ * every in-app link, so the two history methods are wrapped once per document
+ * to emit an event the hook listens for. The wrapping is additive: the original
+ * methods still run, and anything else that wrapped them keeps working.
+ *
+ * Returns "" during SSR, where there is no location to read.
+ */
+
+const EVENT = "forge:locationchange";
+let patched = false;
+
+function patchHistoryOnce() {
+  if (patched || typeof window === "undefined") return;
+  patched = true;
+  for (const method of ["pushState", "replaceState"] as const) {
+    const original = window.history[method];
+    window.history[method] = function patchedMethod(this: History, ...args: Parameters<History[typeof method]>) {
+      const result = original.apply(this, args);
+      window.dispatchEvent(new Event(EVENT));
+      return result;
+    };
+  }
+}
+
+export function useCurrentPath(): string {
+  const [path, setPath] = useState(() => (typeof window === "undefined" ? "" : window.location.pathname));
+
+  useEffect(() => {
+    patchHistoryOnce();
+    const update = () => setPath(window.location.pathname);
+    // A navigation that happened between first render and this effect would
+    // otherwise be missed.
+    update();
+    window.addEventListener("popstate", update);
+    window.addEventListener(EVENT, update);
+    return () => {
+      window.removeEventListener("popstate", update);
+      window.removeEventListener(EVENT, update);
+    };
+  }, []);
+
+  return path;
+}