@tribe-nest/forge 3.61.0 → 3.64.0

package/src/server/_tests/siteBootstrap.spec.ts

@@ -129,3 +129,68 @@ describe("fetchSiteBootstrap", () => {
     expect(r.diagnostics?.probe).toBeUndefined();
   });
 });
+
+describe("fetchSiteBootstrap: the SEO record", () => {
+  const RECORD = {
+    websiteId: "w1",
+    origin: "https://clay.example",
+    isDefaultWebsite: true,
+    defaultWebsiteOrigin: "https://clay.example",
+    siteName: "Clay",
+    defaultDescription: null,
+    defaultImage: null,
+    titleTemplate: "{title} | {site}",
+    typeTemplates: {},
+    identity: null,
+    verification: {},
+    indexing: true,
+    pages: {},
+    version: "2026-10-01T00:00:00.000Z",
+  };
+
+  it("fetches it alongside the rest when a websiteId is given", async () => {
+    const seen: string[] = [];
+    stubFetch((url) => {
+      seen.push(url);
+      if (url.includes("/websites/seo")) return json(RECORD);
+      return url.includes("/content") ? json({ version: 0, defaultLocale: "en", locales: ["en"], fields: {} }) : json({});
+    });
+    const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteId: "w1", websiteVersionId: "v1" });
+    expect(seen).toContain(`${API}/public/websites/seo?websiteId=w1`);
+    expect(r.seo).toEqual(RECORD);
+    expect(r.diagnostics).toBeNull();
+  });
+
+  it("does not ask for it without a websiteId", async () => {
+    const seen: string[] = [];
+    stubFetch((url) => {
+      seen.push(url);
+      return json({ version: 0, defaultLocale: "en", locales: ["en"], fields: {} });
+    });
+    const r = await fetchSiteBootstrap({ apiUrl: API, websiteVersionId: "v1" });
+    expect(seen.some((u) => u.includes("/websites/seo"))).toBe(false);
+    expect(r.seo).toBeNull();
+  });
+
+  it("is null on a 404, a network error or a body that is not a record, and never a diagnostics failure", async () => {
+    for (const fail of [
+      () => new Response("no", { status: 404 }),
+      () => {
+        throw new TypeError("fetch failed");
+      },
+      () => json({ error: "nope" }),
+    ]) {
+      stubFetch((url) =>
+        url.includes("/websites/seo")
+          ? fail()
+          : url.includes("/content")
+            ? json({ version: 0, defaultLocale: "en", locales: ["en"], fields: {} })
+            : json({}),
+      );
+      const r = await fetchSiteBootstrap({ apiUrl: API, profileId: "p1", websiteId: "w1", websiteVersionId: "v1" });
+      expect(r.seo).toBeNull();
+      expect(r.diagnostics).toBeNull();
+      vi.unstubAllGlobals();
+    }
+  });
+});

package/src/server/index.ts

@@ -56,6 +56,8 @@ import { seoContextFromSiteConfig, type ReviewSchemaReview, type SiteSeoContext
 // each route that needs share tags.
 import { buildHeadMeta } from "../utils/headMeta";
 export type { SiteSeoContext };
+import type { SeoRecord } from "../seo/types";
+export type { SeoRecord };
 import type { SiteConfig } from "../data/queries/useWebsite";
 // Type-only, so nothing from the React data layer reaches this React-free entry.
 // Re-exported so a route loader can name the shape it got back without importing
@@ -241,20 +243,31 @@ export async function probeApi(apiUrl: string, opts?: { timeoutMs?: number }): P
 export async function fetchSiteBootstrap(opts: {
   apiUrl: string;
   profileId?: string;
+  /**
+   * The website being rendered. When given, the SEO record is fetched in the
+   * same round trip and returned as `seo`, for `siteSeoHead` / `seoHead`.
+   */
+  websiteId?: string;
   websiteVersionId?: string;
   state?: "draft" | "published";
   /** Set false to skip the reachability probe even when a fetch failed. */
   probe?: boolean;
-}): Promise<{ contentDoc: ContentDocument; siteConfig: SiteConfig | null; diagnostics: ForgeSsrDiagnostics | null }> {
-  const { apiUrl, profileId, websiteVersionId, state = "published" } = opts;
-
-  const [content, siteConfig] = await Promise.all([
+}): Promise<{
+  contentDoc: ContentDocument;
+  siteConfig: SiteConfig | null;
+  seo: SeoRecord | null;
+  diagnostics: ForgeSsrDiagnostics | null;
+}> {
+  const { apiUrl, profileId, websiteId, websiteVersionId, state = "published" } = opts;
+
+  const [content, siteConfig, seo] = await Promise.all([
     websiteVersionId
       ? getJsonResult<ContentDocument>(apiUrl, "/public/websites/content", { websiteVersionId, state })
       : Promise.resolve<JsonResult<ContentDocument>>({ ok: true, data: emptyContentDocument() }),
     profileId
       ? getJsonResult<SiteConfig>(apiUrl, "/public/websites/site-config", { profileId })
       : Promise.resolve<JsonResult<SiteConfig | null>>({ ok: true, data: null }),
+    websiteId ? fetchSeoRecordServer({ apiUrl, websiteId }) : Promise.resolve(null),
   ]);
 
   // A deploy with no version / no profile baked in isn't a failure — there was
@@ -270,10 +283,26 @@ export async function fetchSiteBootstrap(opts: {
   return {
     contentDoc: content.ok ? (content.data ?? emptyContentDocument()) : emptyContentDocument(),
     siteConfig: siteConfig.ok ? (siteConfig.data ?? null) : null,
+    // Not a diagnostics failure: a site renders correctly without it, on the
+    // code's own SEO, and an older API simply does not have the route.
+    seo,
     diagnostics,
   };
 }
 
+/**
+ * The website's SEO record (settings, templates, approved page overrides).
+ *
+ * `null` on ANY failure, including a 404 from an API that predates the route
+ * and a body that is not a record: every SEO function treats `null` as "use
+ * the code's own values", so a missing record degrades to today's tags rather
+ * than to a broken page.
+ */
+export async function fetchSeoRecordServer(opts: { apiUrl: string; websiteId: string }): Promise<SeoRecord | null> {
+  const record = await getJson<SeoRecord>(opts.apiUrl, "/public/websites/seo", { websiteId: opts.websiteId });
+  return record && typeof record === "object" && typeof record.siteName === "string" ? record : null;
+}
+
 /** Fetch a single event by id or slug for SSR. */
 /**
  * Every published event, for SSR of the events list.

package/src/server/pwa.ts

@@ -178,6 +178,13 @@ export interface BuildPwaHeadOptions {
   contentDoc?: ContentDocument | null;
   /** Where the manifest route lives (default `/manifest.webmanifest`). */
   manifestHref?: string;
+  /**
+   * The website's SEO record, as the root loader returned it. Its `siteName` is
+   * what the creator calls the site in search, so the Home Screen label uses it
+   * ahead of the site config's name (the profile's). A PWA name the creator set
+   * explicitly still wins: that is the app's own label.
+   */
+  seo?: { siteName?: string | null } | null;
 }
 
 /** A TanStack `head()`-shaped link entry. */
@@ -219,7 +226,15 @@ export function buildPwaHead(opts: BuildPwaHeadOptions): PwaHead {
     { name: "mobile-web-app-capable", content: "yes" },
     { name: "apple-mobile-web-app-capable", content: "yes" },
     { name: "apple-mobile-web-app-status-bar-style", content: "default" },
-    { name: "apple-mobile-web-app-title", content: siteConfig?.pwa?.shortName || siteConfig?.pwa?.name || siteConfig?.siteName || "App" },
+    {
+      name: "apple-mobile-web-app-title",
+      content:
+        siteConfig?.pwa?.shortName ||
+        siteConfig?.pwa?.name ||
+        opts.seo?.siteName?.trim() ||
+        siteConfig?.siteName ||
+        "App",
+    },
   ];
   return { links, metas };
 }

package/src/ui/analytics/ForgeAnalytics.tsx

@@ -6,6 +6,7 @@ import { setMetaPolicy, trackMeta } from "../../utils/metaEvents";
 import { setCurrentPageEventId, isProfilePixelSuppressed } from "../../utils/analyticsBus";
 import { useCookieConsent } from "../headless/consent/useCookieConsent";
 import { createEngagementTracker, scrollDepthOf, type EngagementTracker } from "../../utils/engagementTracker";
+import { onCLS, onINP, onLCP, type Metric } from "web-vitals";
 
 export interface ForgeAnalyticsProps {
   /**
@@ -60,6 +61,61 @@ function currentPage(): string {
   return window.location.pathname + window.location.search;
 }
 
+/**
+ * Web Vitals (LCP, INP, CLS), for the SEO tab's page speed report.
+ *
+ * `web-vitals` callbacks cannot be unregistered, so they are registered once
+ * per page load, the first time first-party analytics is allowed, and report
+ * through whichever `<ForgeAnalytics />` is mounted now (`vitalsSink`). With
+ * none mounted, or analytics switched off, a report is dropped. Observers are
+ * buffered, so a visitor who consents after the page painted still reports its
+ * LCP.
+ *
+ * Each metric instance is sent once (its first report): a page view, or a
+ * restore from the back/forward cache, which `web-vitals` treats as a new one.
+ * The path is the page the metric belongs to: the URL `web-vitals` names for
+ * it, else the page the document loaded on, since an SPA navigation does not
+ * start a new measurement.
+ */
+type VitalReport = { name: Metric["name"]; value: number; rating: Metric["rating"]; path: string };
+let vitalsSink: ((report: VitalReport) => void) | null = null;
+let vitalsRegistered = false;
+const vitalsSent = new Set<string>();
+
+function pathOfMetric(metric: Metric, loadPath: string): string {
+  try {
+    if (metric.navigationURL) return new URL(metric.navigationURL, window.location.href).pathname;
+  } catch {
+    // fall through to the page the document loaded on
+  }
+  return loadPath;
+}
+
+function registerWebVitals(): void {
+  if (vitalsRegistered || typeof window === "undefined") return;
+  vitalsRegistered = true;
+  const loadPath = currentPathname();
+  const report = (metric: Metric) => {
+    if (vitalsSent.has(metric.id) || !vitalsSink) return;
+    vitalsSent.add(metric.id);
+    vitalsSink({ name: metric.name, value: metric.value, rating: metric.rating, path: pathOfMetric(metric, loadPath) });
+  };
+  try {
+    onLCP(report);
+    onINP(report);
+    onCLS(report);
+  } catch {
+    // An unsupported browser measures nothing; never break the page for it.
+  }
+}
+
+/** For tests: forget the registration and what was sent, as a fresh page load would. */
+export function __resetWebVitalsForTests(): void {
+  vitalsSink = null;
+  vitalsRegistered = false;
+  vitalsSent.clear();
+}
+
 /** Engaged means the visitor can see the page and it has focus. */
 function isEngaged(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "visible" && document.hasFocus();
@@ -74,6 +130,8 @@ function isEngaged(): boolean {
  * - Auto click tracking on links/buttons (opt out with `trackClicks={false}`).
  * - Time on page and scroll depth, as `engagement` events (engaged time only:
  *   visible and focused).
+ * - Page speed: LCP, INP and CLS (Web Vitals), as one `web_vital` event per
+ *   metric per page view, for the SEO tab.
  * - Optional Meta Pixel: pass `metaPixelId` to init the pixel and mirror each
  *   page view as a Meta `PageView` (event-id matched for CAPI de-dup).
  *
@@ -263,6 +321,18 @@ export function ForgeAnalytics({
     };
   }, [firstPartyOn]);
 
+  // Web Vitals: first-party only, like the page views they belong to. Sent by
+  // beacon, because INP and CLS are reported as the page is hidden.
+  useEffect(() => {
+    if (!firstPartyOn || typeof window === "undefined") return;
+    const sink = (report: VitalReport) => beaconRef.current("web_vital", report);
+    vitalsSink = sink;
+    registerWebVitals();
+    return () => {
+      if (vitalsSink === sink) vitalsSink = null;
+    };
+  }, [firstPartyOn]);
+
   // Click tracking: first-party only, one delegated listener for the document.
   useEffect(() => {
     if (!firstPartyOn || !trackClicks || typeof document === "undefined") return;

package/src/ui/analytics/_tests/ForgeAnalytics.webVitals.spec.tsx

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act, cleanup } from "@testing-library/react";
+
+/**
+ * Web Vitals reporting (SEO step 4). `web-vitals` is mocked: each `onX`
+ * registration is captured so a test can fire the metric the browser would.
+ * What is asserted: one `web_vital` event per metric instance, by beacon, with
+ * `{ name, value, rating, path }`; nothing at all without first-party consent;
+ * the cookieless mode still reporting; and registration happening once per
+ * page load however often the component mounts.
+ */
+
+type Metric = {
+  name: "LCP" | "INP" | "CLS";
+  value: number;
+  rating: "good" | "needs-improvement" | "poor";
+  id: string;
+  navigationURL?: string;
+};
+const handlers: Record<string, Array<(m: Metric) => void>> = { LCP: [], INP: [], CLS: [] };
+vi.mock("web-vitals", () => ({
+  onLCP: (cb: (m: Metric) => void) => handlers.LCP.push(cb),
+  onINP: (cb: (m: Metric) => void) => handlers.INP.push(cb),
+  onCLS: (cb: (m: Metric) => void) => handlers.CLS.push(cb),
+}));
+
+const calls: { via: "track" | "beacon"; eventType: string; data: Record<string, unknown> }[] = [];
+vi.mock("../../../data/queries/useAnalytics", () => ({
+  newEventId: () => "evt",
+  useTrackEvent: () => ({
+    track: (eventType: string, data: Record<string, unknown>) => calls.push({ via: "track", eventType, data }),
+    trackBeacon: (eventType: string, data: Record<string, unknown>) => calls.push({ via: "beacon", eventType, data }),
+  }),
+}));
+vi.mock("../../../data/queries/useWebsite", () => ({ useSiteConfig: () => ({ data: undefined }) }));
+const consent = { performance: true, marketing: false };
+vi.mock("../../headless/consent/useCookieConsent", () => ({ useCookieConsent: () => consent }));
+
+import { ForgeAnalytics, __resetWebVitalsForTests } from "../ForgeAnalytics";
+
+const fire = (metric: Metric) => {
+  for (const cb of handlers[metric.name]) cb(metric);
+};
+const vitals = () => calls.filter((c) => c.eventType === "web_vital").map((c) => [c.via, c.data]);
+
+describe("<ForgeAnalytics /> web vitals", () => {
+  beforeEach(() => {
+    calls.length = 0;
+    for (const key of Object.keys(handlers)) handlers[key].length = 0;
+    consent.performance = true;
+    __resetWebVitalsForTests();
+    window.history.replaceState({}, "", "/classes?ref=x");
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("sends LCP, INP and CLS once each, by beacon, with the page the document loaded on", () => {
+    render(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(1);
+    expect(handlers.INP).toHaveLength(1);
+    expect(handlers.CLS).toHaveLength(1);
+
+    // An SPA navigation does not start a new measurement.
+    act(() => window.history.pushState({}, "", "/about"));
+    fire({ name: "LCP", value: 1820.4, rating: "good", id: "v5-lcp-1" });
+    fire({ name: "CLS", value: 0.04, rating: "good", id: "v5-cls-1" });
+    fire({ name: "INP", value: 260, rating: "needs-improvement", id: "v5-inp-1" });
+    // A later report of the same instance (CLS grows) is not sent again.
+    fire({ name: "CLS", value: 0.3, rating: "poor", id: "v5-cls-1" });
+
+    expect(vitals()).toEqual([
+      ["beacon", { name: "LCP", value: 1820.4, rating: "good", path: "/classes" }],
+      ["beacon", { name: "CLS", value: 0.04, rating: "good", path: "/classes" }],
+      ["beacon", { name: "INP", value: 260, rating: "needs-improvement", path: "/classes" }],
+    ]);
+  });
+
+  it("sends a new instance (a back/forward cache restore) with the URL web-vitals names", () => {
+    render(<ForgeAnalytics trackClicks={false} />);
+    fire({ name: "LCP", value: 900, rating: "good", id: "a" });
+    fire({ name: "LCP", value: 300, rating: "good", id: "b", navigationURL: "https://site.test/events/x?y=1" });
+    expect(vitals().map(([, data]) => (data as { path: string }).path)).toEqual(["/classes", "/events/x"]);
+  });
+
+  it("measures nothing without performance consent, and starts once it is given", () => {
+    consent.performance = false;
+    const { rerender } = render(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(0);
+    fire({ name: "LCP", value: 1000, rating: "good", id: "early" });
+    expect(vitals()).toEqual([]);
+
+    consent.performance = true;
+    rerender(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(1);
+    // The observers are buffered, so the LCP that painted before consent still reports.
+    fire({ name: "LCP", value: 1000, rating: "good", id: "early" });
+    expect(vitals()).toEqual([["beacon", { name: "LCP", value: 1000, rating: "good", path: "/classes" }]]);
+  });
+
+  it("reports in cookieless mode without performance consent", () => {
+    consent.performance = false;
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    fire({ name: "INP", value: 120, rating: "good", id: "i1" });
+    expect(vitals()).toEqual([["beacon", { name: "INP", value: 120, rating: "good", path: "/classes" }]]);
+  });
+
+  it("records nothing when disabled, and nothing after the component unmounts", () => {
+    const { unmount } = render(<ForgeAnalytics enabled={false} />);
+    expect(handlers.LCP).toHaveLength(0);
+    unmount();
+
+    const mounted = render(<ForgeAnalytics trackClicks={false} />);
+    mounted.unmount();
+    fire({ name: "LCP", value: 1000, rating: "good", id: "late" });
+    expect(vitals()).toEqual([]);
+  });
+
+  it("registers once per page load however often it mounts", () => {
+    render(<ForgeAnalytics trackClicks={false} />);
+    cleanup();
+    render(<ForgeAnalytics trackClicks={false} />);
+    expect(handlers.LCP).toHaveLength(1);
+    fire({ name: "LCP", value: 700, rating: "good", id: "once" });
+    expect(vitals()).toHaveLength(1);
+  });
+});

package/src/utils/_tests/landing.spec.ts

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from "vitest";
+import { readLanding } from "../landing";
+
+/**
+ * SEO step 6: checkout credits a sale to the page the buyer first landed on.
+ * `readLanding` is spread into every Forge checkout body, so `landingPath` riding
+ * on it is what puts the pathname on the purchase row.
+ */
+function store(snapshot: Record<string, unknown>) {
+  window.localStorage.setItem("tn:landing", JSON.stringify(snapshot));
+}
+
+describe("readLanding", () => {
+  beforeEach(() => window.localStorage.clear());
+
+  it("returns the pathname of the first landing URL, without its query", () => {
+    store({
+      landingUtm: { utm_source: "tribenest" },
+      referrer: "https://instagram.com/",
+      landingUrl: "https://clayroom.example/i/blog/first-class?utm_source=tribenest#top",
+      at: Date.now(),
+    });
+    expect(readLanding()).toEqual({
+      landingUtm: { utm_source: "tribenest" },
+      referrer: "https://instagram.com/",
+      landingPath: "/i/blog/first-class",
+    });
+  });
+
+  it("leaves landingPath undefined when the stored URL cannot be parsed", () => {
+    store({ landingUtm: {}, referrer: "", landingUrl: "not a url", at: Date.now() });
+    expect(readLanding()).toEqual({ landingUtm: undefined, referrer: undefined, landingPath: undefined });
+  });
+
+  it("returns null when nothing is stored", () => {
+    expect(readLanding()).toBeNull();
+  });
+});