@tribe-nest/forge 3.60.0 → 3.63.0

package/src/ui/analytics/ForgeAnalytics.tsx

@@ -1,10 +1,12 @@
 import { useEffect, useRef } from "react";
 import { useTrackEvent, newEventId } from "../../data/queries/useAnalytics";
 import { useSiteConfig } from "../../data/queries/useWebsite";
-import { initMetaPixelScoped, fireMetaEventSingle } from "../../utils/metaPixel";
+import { initMetaPixelScoped } from "../../utils/metaPixel";
+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 {
   /**
@@ -17,7 +19,7 @@ export interface ForgeAnalyticsProps {
   metaPixelId?: string;
   /** Auto-track clicks on links/buttons (and any `[data-track]` element). Default `true`. */
   trackClicks?: boolean;
-  /** Master switch — set `false` (e.g. in the editor/preview) to record nothing. Default `true`. */
+  /** Master switch: set `false` (e.g. in the editor/preview) to record nothing. Default `true`. */
   enabled?: boolean;
   /**
    * Honour the visitor's cookie choice (from `<CookieConsent />`). Default
@@ -43,7 +45,7 @@ export interface ForgeAnalyticsProps {
 }
 
 /**
- * The full resolved path the visitor is on (e.g. `/i/store/abc-123`) — never a
+ * The full resolved path the visitor is on (e.g. `/i/store/abc-123`), never a
  * route template like `store/:id`. This is the value the admin analytics "top
  * pages" report groups on (`event_data->>'pathname'`), so a code site's real
  * routes show up per-page instead of collapsed into a parameterised template.
@@ -53,12 +55,67 @@ function currentPathname(): string {
   return window.location.pathname;
 }
 
-/** Full route including query — kept alongside `pathname` for detail. */
+/** Full route including query, kept alongside `pathname` for detail. */
 function currentPage(): string {
   if (typeof window === "undefined") return "";
   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();
@@ -73,12 +130,14 @@ 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).
  *
  * Consent-aware: with `requireConsent` (default), it reads the shared cookie
- * consent — first-party analytics wait for `performance`, the Meta Pixel waits
- * for `marketing` — so pairing it with `<CookieConsent />` is GDPR-correct out
+ * consent (first-party analytics wait for `performance`, the Meta Pixel waits
+ * for `marketing`), so pairing it with `<CookieConsent />` is GDPR-correct out
  * of the box. Router-agnostic: SPA navigations are detected via the History API,
  * so it works under any router (or none). It renders nothing.
  *
@@ -93,18 +152,28 @@ export function ForgeAnalytics({
 }: ForgeAnalyticsProps) {
   const cookieless = firstPartyMode === "cookieless";
   // Resolve the pixel from the tenant's runtime settings when not explicitly
-  // passed (so changing it needs no rebuild). An explicit prop — including `""`
-  // to disable — always wins.
-  const { data: siteConfig } = useSiteConfig();
+  // passed (so changing it needs no rebuild). An explicit prop (including `""`
+  // to disable) always wins.
+  const siteConfigQuery = useSiteConfig();
+  const siteConfig = siteConfigQuery.data;
   const pixelId = metaPixelId ?? siteConfig?.metaPixelId ?? undefined;
+  // The pixel is known once it was passed, or the site config has answered.
+  // Until then Meta events fired elsewhere (a detail page mounting first) wait.
+  const pixelResolved = metaPixelId !== undefined || !!siteConfig || !siteConfigQuery.isLoading;
   const { performance: perfConsent, marketing: mktConsent } = useCookieConsent();
   // Session storage follows performance consent. In `consent` mode first-party
   // only runs with that consent, so it always stores; in `cookieless` mode it
   // runs regardless but only stores a device session once the visitor turns
-  // Performance on — otherwise it stays cookieless (backend derives the id).
+  // Performance on; otherwise it stays cookieless (backend derives the id).
   const storeSession = cookieless ? perfConsent : true;
-  const { track, trackBeacon } = useTrackEvent({ storeSession });
-  const lastPage = useRef<string | null>(null);
+  const { track, trackBeacon, apiUrl, subdomain } = useTrackEvent({ storeSession });
+  // The page the current event id belongs to, and the last page each half
+  // recorded. Tracked separately because consent (and the pixel id) arrive
+  // AFTER mount: with one shared "last page", the first-party view consumed the
+  // page and the Meta PageView for it never fired once consent loaded.
+  const pageView = useRef<{ page: string; eventId: string } | null>(null);
+  const lastFirstPartyPage = useRef<string | null>(null);
+  const lastMetaPage = useRef<string | null>(null);
   // Time on page. Pings go by beacon: most are sent as the page is hidden or
   // unloaded, which cancels an ordinary request.
   const beaconRef = useRef(trackBeacon);
@@ -118,13 +187,29 @@ export function ForgeAnalytics({
   }
 
   // Consent gates. The Meta Pixel always needs `marketing`. First-party analytics
-  // needs `performance` — UNLESS it's cookieless (stores nothing without consent),
+  // needs `performance`, UNLESS it's cookieless (stores nothing without consent),
   // in which case it's treated as essential and runs anyway. Flipping a gate to
   // `true` (visitor accepts) re-runs the effects, recording the current page.
   const firstPartyOn = enabled && (cookieless || !requireConsent || perfConsent);
   const metaOn = enabled && !!pixelId && (!requireConsent || mktConsent);
 
-  // Init the Meta pixel once (scoped — no auto PageView; we fire it ourselves so
+  // Publish the Meta policy for code outside this component (cart, checkout,
+  // detail pages, create mutations). Declared before the page-view effect so
+  // the policy is current when that effect fires.
+  const currency = siteConfig?.currency;
+  useEffect(() => {
+    setMetaPolicy({
+      pixelId: pixelId || undefined,
+      enabled,
+      requireConsent,
+      apiUrl,
+      subdomain,
+      currency,
+      resolved: pixelResolved,
+    });
+  }, [pixelId, enabled, requireConsent, apiUrl, subdomain, currency, pixelResolved]);
+
+  // Init the Meta pixel once (scoped: no auto PageView; we fire it ourselves so
   // it doesn't leak into a per-page campaign pixel).
   useEffect(() => {
     if (!metaOn || !pixelId) return;
@@ -136,18 +221,20 @@ export function ForgeAnalytics({
   // which keeps this free of any router dependency.
   useEffect(() => {
     if (typeof window === "undefined") return;
-    if (!firstPartyOn && !metaOn) return; // nothing consented yet — wait
+    if (!firstPartyOn && !metaOn) return; // nothing consented yet, wait
 
     const sendPageView = () => {
       const page = currentPage();
-      if (page === lastPage.current) return; // de-dupe repeated fires for the same URL
-      lastPage.current = page;
+      if (pageView.current?.page !== page) {
+        pageView.current = { page, eventId: newEventId() };
+        // Publish the id so a per-page <PageMetaPixel/> (and its server CAPI twin)
+        // can dedupe against the same page view.
+        setCurrentPageEventId(pageView.current.eventId);
+      }
+      const eventId = pageView.current.eventId;
 
-      const eventId = newEventId();
-      // Publish the id so a per-page <PageMetaPixel/> (and its server CAPI twin)
-      // can dedupe against the same page view.
-      setCurrentPageEventId(eventId);
-      if (firstPartyOn) {
+      if (firstPartyOn && lastFirstPartyPage.current !== page) {
+        lastFirstPartyPage.current = page;
         // Close the previous page's time before this page view is recorded, so
         // the ping lands on the page it measured.
         engagement.current?.flush();
@@ -162,14 +249,16 @@ export function ForgeAnalytics({
           eventId,
         });
       }
-      // Fire the profile pixel to ITSELF (trackSingle), and skip it on routes a
-      // campaign pixel has taken over (PageMetaPixel override). Deferred a tick
-      // so a page pixel mounting on this route can register its suppression first.
-      if (metaOn && pixelId) {
+      // Fire the profile pixel to ITSELF (trackSingle) plus its server copy,
+      // with the page view's id, and skip both on routes a campaign pixel has
+      // taken over (PageMetaPixel override; it sends its own server copy).
+      // Deferred a tick so a page pixel mounting on this route can register its
+      // suppression first.
+      if (metaOn && pixelId && lastMetaPage.current !== page) {
+        lastMetaPage.current = page;
         const path = currentPathname();
-        const pixel = pixelId;
         queueMicrotask(() => {
-          if (!isProfilePixelSuppressed(path)) fireMetaEventSingle(pixel, "PageView", {}, eventId);
+          if (!isProfilePixelSuppressed(path)) trackMeta("PageView", undefined, { eventId });
         });
       }
     };
@@ -232,7 +321,19 @@ export function ForgeAnalytics({
     };
   }, [firstPartyOn]);
 
-  // Click tracking — first-party only, one delegated listener for the document.
+  // 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;
 
@@ -246,11 +347,10 @@ export function ForgeAnalytics({
       //
       // This listener cannot know that a component already sent a richer event
       // for the same click, so without a way to stand down, anything that tracks
-      // its own clicks is counted twice. Worse than the double count: this
-      // listener's payload carries no `eventId`, so the resulting CAPI `Lead`
-      // has nothing to dedupe against, and Meta sees two conversions for one
-      // action. Any element that fires its own event must carry
-      // `data-track-skip`.
+      // its own clicks is counted twice in first-party analytics. A click is
+      // not a Meta event (components that turn one into a conversion fire it
+      // themselves, through `trackMeta` or `usePageMetaPixel`). Any element
+      // that reports its own click must carry `data-track-skip`.
       if (el.closest("[data-track-skip]")) return;
 
       const anchor = el.closest("a") as HTMLAnchorElement | null;

package/src/ui/analytics/PageMetaPixel.tsx

@@ -6,6 +6,12 @@ import {
   unsuppressProfilePixel,
 } from "../../utils/analyticsBus";
 import { useCookieConsent } from "../headless/consent/useCookieConsent";
+import { sendPageMetaEvent, type MetaCustomData } from "../../utils/metaEvents";
+import { newEventId } from "../../data/queries/useAnalytics";
+
+function currentPathname(): string {
+  return typeof window === "undefined" ? "" : window.location.pathname;
+}
 
 // useLayoutEffect warns during SSR; fall back to useEffect on the server.
 const useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
@@ -57,7 +63,11 @@ export function PageMetaPixel({
     if (!allowed || !pixelId || typeof window === "undefined") return;
     initMetaPixelScoped(pixelId);
     if (trackPageView) {
-      fireMetaEventSingle(pixelId, "PageView", {}, getCurrentPageEventId() ?? undefined);
+      // One id for the pixel and its server copy: the page view's own, so the
+      // pair dedupes on Meta.
+      const eventId = getCurrentPageEventId() ?? newEventId();
+      fireMetaEventSingle(pixelId, "PageView", {}, eventId);
+      sendPageMetaEvent({ eventName: "PageView", eventId, pathname: currentPathname() });
     }
   }, [allowed, pixelId, trackPageView]);
 
@@ -65,12 +75,14 @@ export function PageMetaPixel({
 }
 
 /**
- * Imperative companion to `<PageMetaPixel/>` — returns `fire(event, data?)` to
- * send conversion events (e.g. `Lead` on a CTA click) to the campaign pixel,
- * gated on marketing consent and reusing the current page view's event id.
+ * Imperative companion to `<PageMetaPixel/>`. Returns `fire(event, data?, eventId?)`
+ * to send a conversion event (e.g. `Lead` on a CTA click) to the campaign pixel
+ * AND its server copy, gated on marketing consent. Both halves carry one id:
+ * the one passed, else a new one per call (an action is its own event, never
+ * the page view). Returns that id.
  *
  *     const { fire } = usePageMetaPixel("123456789");
- *     <button onClick={() => fire("Lead", { content_name: "Pre-save" })}>…</button>
+ *     <button onClick={() => fire("Lead", { content_name: "Pre-save" })}>...</button>
  */
 export function usePageMetaPixel(pixelId: string, opts?: { requireConsent?: boolean }) {
   const requireConsent = opts?.requireConsent ?? true;
@@ -84,9 +96,12 @@ export function usePageMetaPixel(pixelId: string, opts?: { requireConsent?: bool
 
   return {
     allowed,
-    fire: (eventName: string, data: Record<string, unknown> = {}) => {
-      if (!allowed || !pixelId) return;
-      fireMetaEventSingle(pixelId, eventName, data, getCurrentPageEventId() ?? undefined);
+    fire: (eventName: string, data: Record<string, unknown> = {}, eventId?: string): string | undefined => {
+      if (!allowed || !pixelId) return undefined;
+      const id = eventId ?? newEventId();
+      fireMetaEventSingle(pixelId, eventName, data, id);
+      sendPageMetaEvent({ eventName, eventId: id, pathname: currentPathname(), customData: data as MetaCustomData });
+      return id;
     },
   };
 }

package/src/ui/analytics/_tests/ForgeAnalytics.meta.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";
+
+/**
+ * The page view's Meta pair: the profile pixel's PageView and its server copy
+ * (POST /public/websites/meta-event) carry the id the first-party page view
+ * already has, so Meta keeps one. Consent loads AFTER mount, which used to
+ * mean the first page never sent a Meta PageView at all.
+ */
+
+const tracked: { eventType: string; data: Record<string, unknown> }[] = [];
+let seq = 0;
+
+vi.mock("../../../data/queries/useAnalytics", () => ({
+  newEventId: () => `evt-${++seq}`,
+  useTrackEvent: () => ({
+    track: (eventType: string, data: Record<string, unknown>) => tracked.push({ eventType, data }),
+    trackBeacon: () => {},
+    apiUrl: "https://api.test",
+    subdomain: "artist",
+  }),
+}));
+vi.mock("../../../data/queries/useWebsite", () => ({
+  useSiteConfig: () => ({ data: { metaPixelId: "999", currency: "USD" }, isLoading: false }),
+}));
+
+import { ForgeAnalytics } from "../ForgeAnalytics";
+import { resetMetaPolicy } from "../../../utils/metaEvents";
+import { saveCookieConsent, GRANT_ALL, DENY_ALL } from "../../../utils/cookieConsent";
+import { suppressProfilePixel, unsuppressProfilePixel } from "../../../utils/analyticsBus";
+
+let fetchSpy: ReturnType<typeof vi.fn>;
+let fbq: ReturnType<typeof vi.fn>;
+
+const metaPosts = () =>
+  fetchSpy.mock.calls
+    .filter((c) => String(c[0]).endsWith("/public/websites/meta-event"))
+    .map((c) => JSON.parse((c[1] as RequestInit).body as string));
+
+const flush = () => act(async () => {});
+
+beforeEach(() => {
+  tracked.length = 0;
+  seq = 0;
+  resetMetaPolicy();
+  window.localStorage.clear();
+  fetchSpy = vi.fn().mockResolvedValue({ ok: true });
+  vi.stubGlobal("fetch", fetchSpy);
+  fbq = vi.fn();
+  (window as unknown as { fbq: unknown }).fbq = fbq;
+  window.history.replaceState({}, "", "/first");
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  resetMetaPolicy();
+});
+
+describe("<ForgeAnalytics /> Meta PageView", () => {
+  it("sends the pixel PageView and its server copy with the page view's id, once consent loads", async () => {
+    saveCookieConsent(GRANT_ALL);
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+
+    const pageView = tracked.find((t) => t.eventType === "page_view");
+    expect(pageView?.data.eventId).toBe("evt-1");
+    expect(metaPosts()).toEqual([
+      {
+        subdomain: "artist",
+        pixel: "profile",
+        eventName: "PageView",
+        eventId: "evt-1",
+        eventSourceUrl: "http://localhost:3000/first",
+        metaSignals: { pageUrl: "http://localhost:3000/first", marketingConsent: true },
+      },
+    ]);
+    expect(fbq).toHaveBeenCalledWith("trackSingle", "999", "PageView", {}, { eventID: "evt-1" });
+    // One first-party page view, not a second one when consent arrived.
+    expect(tracked.filter((t) => t.eventType === "page_view")).toHaveLength(1);
+  });
+
+  it("sends a fresh pair on an SPA navigation", async () => {
+    saveCookieConsent(GRANT_ALL);
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+    act(() => window.history.pushState({}, "", "/second"));
+    await flush();
+
+    expect(metaPosts().map((b) => [b.eventId, b.eventSourceUrl])).toEqual([
+      ["evt-1", "http://localhost:3000/first"],
+      ["evt-2", "http://localhost:3000/second"],
+    ]);
+  });
+
+  it("sends no server copy where a campaign pixel took the page over", async () => {
+    saveCookieConsent(GRANT_ALL);
+    suppressProfilePixel("/first");
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+    unsuppressProfilePixel("/first");
+    expect(metaPosts()).toEqual([]);
+  });
+
+  it("sends nothing to Meta when marketing was declined", async () => {
+    saveCookieConsent(DENY_ALL);
+    render(<ForgeAnalytics trackClicks={false} firstPartyMode="cookieless" />);
+    await flush();
+    expect(metaPosts()).toEqual([]);
+    expect(tracked.filter((t) => t.eventType === "page_view")).toHaveLength(1);
+  });
+
+  it("sends a plain click first-party only", async () => {
+    saveCookieConsent(GRANT_ALL);
+    const { container } = render(
+      <>
+        <ForgeAnalytics firstPartyMode="cookieless" />
+        <button type="button">Buy</button>
+      </>,
+    );
+    await flush();
+    const before = metaPosts().length;
+    act(() => container.querySelector("button")!.click());
+    await flush();
+    expect(tracked.some((t) => t.eventType === "click")).toBe(true);
+    expect(metaPosts()).toHaveLength(before);
+  });
+});

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