@tribe-nest/forge 3.59.0 → 3.61.0

package/src/index.ts

@@ -1,8 +1,8 @@
-// Forge — the headless React SDK for TribeNest creator sites.
+// Forge: the headless React SDK for TribeNest creator sites.
 //
 // Phase 1 (the spine): client factory, root provider, core types.
 // Subsequent phases add providers (auth/cart/audio), data hooks, flow hooks,
-// headless blocks, and SEO — see docs/code-websites-initiative.md.
+// headless blocks, and SEO: see docs/code-websites-initiative.md.
 
 export { createForgeClient, getForgeWebSocketUrl } from "./client/createForgeClient";
 export type { ForgeClientOptions } from "./client/createForgeClient";
@@ -43,12 +43,12 @@ export {
 // All domain types + enums/consts (models) and WebPage.
 export * from "./types";
 
-// Providers (Phase 2 — moving from frontend-shared into Forge)
+// Providers (Phase 2: moving from frontend-shared into Forge)
 export { AudioPlayerProvider, useAudioPlayer } from "./contexts/AudioPlayerContext";
 export type { AudioTrack } from "./contexts/AudioPlayerContext";
 export { CartProvider, useCart } from "./contexts/CartContext";
 // Variant selection, shared with the Craft themes in frontend-shared the same
-// way the cart and audio player are — so a code site and a Craft site cannot
+// way the cart and audio player are: so a code site and a Craft site cannot
 // disagree about which version a buyer picked.
 export { useVariantSelection } from "./ui/headless/useVariantSelection";
 // Which version a cart line is. Exported from the package root because the
@@ -66,7 +66,7 @@ export {
 export type { AuthActions } from "./contexts/PublicAuthContext";
 export { PUBLIC_REFRESH_TOKEN_KEY, APP_REFRESH_TOKEN_KEY } from "./client/tokenStorage";
 export { safeRedirectPath } from "./utils/safeRedirect";
-// Ticket-confirmation copy decision — shared so the Forge block and the client
+// Ticket-confirmation copy decision: shared so the Forge block and the client
 // app's finalise page can never tell a refunded buyer two different stories.
 export {
   getTicketOrderOutcome,
@@ -89,7 +89,7 @@ export {
 } from "./contexts/AppAuthContext";
 export { useAppAdminGuard, type AppAdminGuardResult } from "./contexts/useAppAdminGuard";
 
-// Data hooks (React Query) — Phase 3
+// Data hooks (React Query): Phase 3
 export * from "./data/queries/useProducts";
 export * from "./data/queries/useMembership";
 export * from "./data/queries/useCourses";
@@ -138,12 +138,16 @@ export * from "./data/queries/useEngagement";
 export * from "./data/queries/usePaymentFlow";
 export * from "./data/queries/useOrders";
 export * from "./data/queries/useAuthActions";
+// Email-first sign-in (`/public/sessions/email/*`): start, verify, complete.
+export * from "./data/queries/useEmailSignIn";
 export * from "./data/queries/useCoupons";
 export * from "./data/queries/useAccountSettings";
 export * from "./data/queries/useDonations";
 export * from "./data/queries/useOffers";
 export * from "./data/queries/useShipping";
 export * from "./data/queries/useWebsite";
+// The site app's settings for this host, and the Home rule (`useAppHomeHref`).
+export * from "./data/queries/useSiteApp";
 export * from "./data/queries/useWebsiteAgent";
 export * from "./data/queries/useCurrencies";
 export * from "./data/queries/useChat";
@@ -151,19 +155,44 @@ export * from "./data/queries/useCallChat";
 export * from "./data/queries/useCallBreakouts";
 export * from "./data/queries/useAnalytics";
 export * from "./data/queries/useCommunity";
+// The community AI on the member side: its info, DM, thumbs, "catch me up".
+export * from "./data/queries/useCommunityAgent";
+// Moderation from the site: the queue, the log, and the moderator actions.
+export * from "./data/queries/useCommunityModeration";
+// The community wiki as members and visitors read it.
+export * from "./data/queries/useCommunityWiki";
+// The member directory and map.
+export * from "./data/queries/useCommunityMembers";
+// The classroom tab: the courses a community's tiers include.
+export * from "./data/queries/useCommunityClassroom";
+// The community calendar: calls, promoted events and going / not going.
+export * from "./data/queries/useCommunityCalendar";
+// Communities: the list, one community, the viewer's state in it, invites,
+// upgrades and the fan's memberships across communities.
+export * from "./data/queries/useCommunities";
+// The provider every member-content hook reads its community from.
+export {
+  CommunityProvider,
+  useCommunityContext,
+  useOptionalCommunityContext,
+  MissingCommunityProviderError,
+  type CommunityContextValue,
+  type CommunityProviderProps,
+} from "./contexts/CommunityContext";
 export * from "./data/queries/useReviews";
 export * from "./data/queries/useDocuments";
 export * from "./data/queries/useNotifications";
 export * from "./data/queries/usePWA";
 export * from "./data/queries/useCertificates";
 
-// Content layer (Phase E) — typed/editable/localizable site content
+// Content layer (Phase E): typed/editable/localizable site content
 export * from "./content";
 
 // Utils
 export * from "./utils/attribution";
 export * from "./utils/landing";
 export * from "./utils/metaPixel";
+export * from "./utils/metaEvents";
 export * from "./utils/cookieConsent";
 export * from "./utils/structuredData";
 // Paystack inline checkout: the ONE implementation of the popup, exported so a

package/src/runtime/pages.spec.ts

@@ -38,4 +38,40 @@ describe("internal page links", () => {
   it("carries every page exactly once", () => {
     expect(new Set(INTERNAL_PAGES).size).toBe(INTERNAL_PAGES.length);
   });
+
+  it("carries exactly the community pages, and none of the removed single-community ones", () => {
+    const community = INTERNAL_PAGES.filter((page) => page.startsWith("communities"));
+    expect(community).toEqual([
+      "communities",
+      "communities/$slug",
+      "communities/$slug/home",
+      "communities/$slug/home/calendar",
+      "communities/$slug/home/chat",
+      "communities/$slug/home/classroom",
+      "communities/$slug/home/collections",
+      "communities/$slug/home/collections/$collectionId",
+      "communities/$slug/home/leaderboard",
+      "communities/$slug/home/members",
+      "communities/$slug/home/moderation",
+      "communities/$slug/home/notifications",
+      "communities/$slug/home/posts",
+      "communities/$slug/home/profile/$accountId",
+      "communities/$slug/home/spaces",
+      "communities/$slug/home/spaces/$spaceId",
+      "communities/$slug/home/spaces/posts/$postId",
+      "communities/$slug/home/wiki",
+      "communities/$slug/home/wiki/$page",
+    ]);
+    const removed = INTERNAL_PAGES.filter((page) => /^(membership|members|community|chat)(\/|$)/.test(page));
+    expect(removed).toEqual([]);
+  });
+
+  it("builds community paths with the slug and recognises them", () => {
+    expect(internalPath("communities/$slug/home/spaces/posts/$postId", { slug: "fan-club", postId: "p1" })).toBe(
+      "/i/communities/fan-club/home/spaces/posts/p1",
+    );
+    expect(isInternalPage("communities/fan-club/home")).toBe(true);
+    expect(isInternalPage("members/spaces")).toBe(false);
+    expect(isInternalPage("membership/checkout")).toBe(false);
+  });
 });

package/src/runtime/pages.ts

@@ -7,9 +7,17 @@
  * for TanStack to know about. That is the reason this helper exists, and it is
  * why the build guide forbids writing an `/i/` path by hand.
  *
- * The page list is the CONTRACT between a site and the hosted pages, so it only
- * ever grows. Removing a page breaks links on sites already published, so a
- * retired page keeps its entry and redirects.
+ * The page list is the CONTRACT between a site and the hosted pages, so it
+ * normally only grows: removing a page breaks links on sites already published.
+ * The first deliberate exception is Communities (2026-09-27). A profile can now
+ * run several communities, so the single-community member pages (`membership`,
+ * `members/*`, `community/*`, `chat`) were removed with no redirects, because
+ * nobody used them yet and there is no one community they could redirect to.
+ * Every member page now lives under `communities/$slug`.
+ *
+ * The second is the client portal (2026-10-01). `work/*` and the `?tab=` form
+ * of `account` folded into one portal under `account/*`, with no redirects:
+ * every producer of those links moved in the same change.
  *
  *     <Link {...internalLink("store/$slug", { slug: product.slug })}>Buy</Link>
  *     navigate(internalLink("checkout"))
@@ -25,10 +33,30 @@ export const INTERNAL_ROUTE = "/i/$" as const;
 /** Every hosted page, by its path pattern. Generated from the route table. */
 export const INTERNAL_PAGES = [
   "account",
+  "account/activity",
+  "account/bookings",
+  "account/courses",
+  "account/documents",
+  "account/files",
+  "account/films",
+  "account/invite",
+  "account/invoices",
+  "account/memberships",
+  "account/messages",
+  "account/notifications",
+  "account/orders",
+  "account/projects",
+  "account/projects/$projectId",
+  "account/projects/$projectId/tasks/$taskId",
+  "account/saved",
+  "account/settings",
+  "account/tickets",
+  "account/time-report/$token",
+  "account/waitlist",
+  "app",
   "blog",
   "blog-category/$slug",
   "blog/$slug",
-  "chat",
   "checkout",
   "checkout/finalise",
   "checkout/resume",
@@ -37,11 +65,25 @@ export const INTERNAL_PAGES = [
   "coaching/$slug/finalise",
   "cohorts/$cohortId",
   "cohorts/$cohortId/finalise",
-  "community",
-  "community/leaderboard",
-  "community/notifications",
-  "community/posts/$postId",
-  "community/spaces/$spaceId",
+  "communities",
+  "communities/$slug",
+  "communities/$slug/home",
+  "communities/$slug/home/calendar",
+  "communities/$slug/home/chat",
+  "communities/$slug/home/classroom",
+  "communities/$slug/home/collections",
+  "communities/$slug/home/collections/$collectionId",
+  "communities/$slug/home/leaderboard",
+  "communities/$slug/home/members",
+  "communities/$slug/home/moderation",
+  "communities/$slug/home/notifications",
+  "communities/$slug/home/posts",
+  "communities/$slug/home/profile/$accountId",
+  "communities/$slug/home/spaces",
+  "communities/$slug/home/spaces/$spaceId",
+  "communities/$slug/home/spaces/posts/$postId",
+  "communities/$slug/home/wiki",
+  "communities/$slug/home/wiki/$page",
   "confirm-subscription",
   "course-access/$accessId",
   "courses",
@@ -50,6 +92,7 @@ export const INTERNAL_PAGES = [
   "courses/claim",
   "documents/$token",
   "donation",
+  "downloads/$token",
   "events",
   "events/$slug",
   "events/$slug/finalise",
@@ -65,19 +108,6 @@ export const INTERNAL_PAGES = [
   "live",
   "live/$broadcastId",
   "login",
-  "members",
-  "members/calendar",
-  "members/chat",
-  "members/collections",
-  "members/collections/$slug",
-  "members/spaces",
-  "members/spaces/$slug",
-  "members/spaces/leaderboard",
-  "members/spaces/notifications",
-  "members/spaces/profile/$accountId",
-  "members/spaces/thread/$postId",
-  "membership",
-  "membership/checkout",
   "payment-link/$paymentLinkId",
   "payment-link/$paymentLinkId/finalise",
   "podcasts",
@@ -92,11 +122,6 @@ export const INTERNAL_PAGES = [
   "store/$slug",
   "tickets/claim",
   "video-calls/$callId",
-  "work",
-  "work/accept-invite",
-  "work/projects/$projectId",
-  "work/projects/$projectId/tasks/$taskId",
-  "work/time-report/$token",
 ] as const;
 
 export type InternalPage = (typeof INTERNAL_PAGES)[number];

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

@@ -270,7 +270,7 @@ describe("buildWebManifest — name/short_name fallback chain", () => {
 describe("buildWebManifest — overrides (shortcuts) merge", () => {
   const overrides: BuildWebManifestOptions["overrides"] = {
     shortcuts: [
-      { name: "Members", short_name: "Members", url: "/i/members" },
+      { name: "Members", short_name: "Members", url: "/i/communities" },
       { name: "Account", short_name: "Account", url: "/i/account" },
     ],
   };

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

@@ -168,7 +168,7 @@ describe("forgeServiceWorkerScript — push payload contract (frozen, shared wit
           title: "New message",
           body: "hey!",
           type: "chat_message",
-          url: "/i/chat/42",
+          url: "/i/communities/fan-club/home/chat",
           profileId: "prof-1",
           channelId: "chan-9",
           icon: "https://cdn.tribenest.co/p/nova/icon-192.png",
@@ -181,7 +181,7 @@ describe("forgeServiceWorkerScript — push payload contract (frozen, shared wit
       body: "hey!",
       icon: "https://cdn.tribenest.co/p/nova/icon-192.png",
       tag: "chat-chan-9",
-      data: { url: "/i/chat/42", type: "chat_message" },
+      data: { url: "/i/communities/fan-club/home/chat", type: "chat_message" },
     });
   });
 
@@ -229,9 +229,9 @@ describe("forgeServiceWorkerScript — notificationclick", () => {
   it("focuses an existing client matching the deep-link URL", async () => {
     const { handlers, matchAll, openWindow } = loadSw();
     const focus = vi.fn(() => ({}));
-    matchAll.mockResolvedValueOnce([{ url: "https://nova.tribenest.co/i/chat/42", focus }]);
+    matchAll.mockResolvedValueOnce([{ url: "https://nova.tribenest.co/i/communities/fan-club/home/chat", focus }]);
     const close = vi.fn();
-    const event = fakeEvent({ notification: { close, data: { url: "/i/chat/42" } } });
+    const event = fakeEvent({ notification: { close, data: { url: "/i/communities/fan-club/home/chat" } } });
     handlers.notificationclick!(event);
     await event.waited;
     expect(close).toHaveBeenCalledOnce();

package/src/types/models.ts

@@ -474,6 +474,11 @@ export interface PublicAuthUser {
   updatedAt: string;
   id: string;
   membership?: Membership;
+  /**
+   * Set when this is a read-only "Preview as client" session: a creator viewing
+   * the portal as this person. Null (or absent on older APIs) otherwise.
+   */
+  preview?: { previewedByName: string; expiresAt: string } | null;
 }
 
 export type UpdateLocalUserPayload = Pick<PublicAuthUser, "firstName">;
@@ -550,6 +555,12 @@ export interface PublicAuthContextType extends PublicAuthState {
   validateLoginCredentials: (data: LoginInput & { profileId: string }) => Promise<string>;
   verifyLoginCode: (email: string, code: string, profileId: string) => Promise<{ smartLinkPath: string | undefined }>;
   resendLoginCode: (email: string) => Promise<void>;
+  /**
+   * Sign in with a session another call already minted, e.g. the email-first
+   * flow's `signed_in` answer: stores the token pair exactly as the code
+   * sign-ins do and sets the user.
+   */
+  adoptSession: (session: { token: string; refreshToken?: string; account: PublicAuthUser }) => void;
   logout: (persist?: boolean) => Promise<void>;
   updateLocalUser: (data: UpdateLocalUserPayload) => void;
   clearErrorMessage: () => void;

package/src/ui/analytics/ForgeAnalytics.tsx

@@ -1,7 +1,8 @@
 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";
@@ -17,7 +18,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 +44,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,7 +54,7 @@ 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;
@@ -77,8 +78,8 @@ function isEngaged(): boolean {
  *   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 +94,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 +129,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 +163,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 +191,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 +263,7 @@ export function ForgeAnalytics({
     };
   }, [firstPartyOn]);
 
-  // Click tracking — first-party only, one delegated listener for the document.
+  // Click tracking: first-party only, one delegated listener for the document.
   useEffect(() => {
     if (!firstPartyOn || !trackClicks || typeof document === "undefined") return;
 
@@ -246,11 +277,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;
     },
   };
 }