@tribe-nest/forge 1.13.0

package/src/ui/theme/ForgeThemeProvider.tsx

@@ -0,0 +1,121 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { readableTextOn } from "./contrast";
+
+/**
+ * The theme contract the styled (Tier-2) blocks read. Forge owns this so
+ * `forge/ui` never depends on the Craft editor's `useEditorContext` (which lives
+ * in frontend-shared → would be a cycle). The Craft editor feeds its
+ * `themeSettings` in; a headless developer sets their own.
+ *
+ * Only `text` / `background` / `primary` / `cornerRadius` are required. Every
+ * other token is optional and derives a sensible fallback (see
+ * {@link resolveThemeTokens}), so richer branding is opt-in and never breaks an
+ * existing theme.
+ */
+export type ForgeTheme = {
+  colors: {
+    text: string;
+    background: string;
+    primary: string;
+    /** Text/icon color to place ON the primary (buttons etc.). The craft theme's
+     * `textPrimary`. When unset, falls back to `readableTextOn(primary)`. */
+    textPrimary?: string;
+    /** Secondary/accent color (secondary buttons, highlights). Falls back to `primary`. */
+    secondary?: string;
+    /** Card/section surface, distinct from the page `background`. Falls back to `background`. */
+    surface?: string;
+    /** Hairline/border color. Falls back to a translucent `primary`. */
+    border?: string;
+    /** Muted/subtle text (captions, meta). Falls back to a translucent `text`. */
+    muted?: string;
+  };
+  cornerRadius: number;
+  /** Body font family. */
+  fontFamily?: string;
+  /** Display/heading font family. Falls back to `fontFamily`. */
+  headingFontFamily?: string;
+};
+
+export const defaultForgeTheme: ForgeTheme = {
+  colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" },
+  cornerRadius: 8,
+};
+
+/** Append an alpha (0..1) to a 6-digit hex color; passes non-hex through unchanged. */
+const withAlpha = (hex: string, a: number) =>
+  /^#[0-9a-fA-F]{6}$/.test(hex) ? hex + Math.round(a * 255).toString(16).padStart(2, "0") : hex;
+
+export type ResolvedThemeTokens = {
+  text: string;
+  background: string;
+  primary: string;
+  textPrimary: string;
+  secondary: string;
+  surface: string;
+  border: string;
+  muted: string;
+  cornerRadius: number;
+  fontFamily?: string;
+  headingFontFamily?: string;
+};
+
+/**
+ * Resolve every theme token to a concrete value, deriving fallbacks for the
+ * optional ones. Blocks call this instead of hand-rolling `|| primary` / alpha
+ * math so the fallback rules stay in one place.
+ */
+export function resolveThemeTokens(t: ForgeTheme): ResolvedThemeTokens {
+  const c = t.colors;
+  return {
+    text: c.text,
+    background: c.background,
+    primary: c.primary,
+    textPrimary: c.textPrimary || readableTextOn(c.primary),
+    secondary: c.secondary || c.primary,
+    surface: c.surface || c.background,
+    border: c.border || withAlpha(c.primary, 0.14),
+    muted: c.muted || withAlpha(c.text, 0.6),
+    cornerRadius: t.cornerRadius,
+    fontFamily: t.fontFamily,
+    headingFontFamily: t.headingFontFamily || t.fontFamily,
+  };
+}
+
+const ForgeThemeContext = createContext<ForgeTheme | null>(null);
+
+export function ForgeThemeProvider({ theme, children }: { theme: ForgeTheme; children: ReactNode }) {
+  const r = resolveThemeTokens(theme);
+  // Publish the theme as :root CSS variables too, so plain markup + Tailwind
+  // tokens (bg-primary, text-text, bg-background) resolve to the SAME values the
+  // styled blocks read from context — one theme, everything in sync, runtime-live.
+  const css =
+    ":root{" +
+    `--forge-primary:${r.primary};` +
+    `--forge-secondary:${r.secondary};` +
+    `--forge-background:${r.background};` +
+    `--forge-surface:${r.surface};` +
+    `--forge-text:${r.text};` +
+    `--forge-text-primary:${r.textPrimary};` +
+    `--forge-muted:${r.muted};` +
+    `--forge-border:${r.border};` +
+    `--forge-radius:${r.cornerRadius}px;` +
+    (r.fontFamily ? `--forge-font:${r.fontFamily};` : "") +
+    (r.headingFontFamily ? `--forge-heading-font:${r.headingFontFamily};` : "") +
+    "}";
+  return (
+    <ForgeThemeContext.Provider value={theme}>
+      <style dangerouslySetInnerHTML={{ __html: css }} />
+      {children}
+    </ForgeThemeContext.Provider>
+  );
+}
+
+/** The active theme tokens (falls back to defaults outside a provider). */
+export function useForgeTheme(): ForgeTheme {
+  return useContext(ForgeThemeContext) ?? defaultForgeTheme;
+}
+
+/** The active theme with all optional tokens resolved to concrete values. */
+export function useThemeTokens(): ResolvedThemeTokens {
+  return resolveThemeTokens(useForgeTheme());
+}

package/src/ui/theme/contrast.ts

@@ -0,0 +1,22 @@
+// Contrast helpers so themed surfaces never hardcode "#fff" on top of an
+// arbitrary tenant color (a light primary made white text unreadable).
+
+const parseHex = (hex: string): [number, number, number] | null => {
+  let h = hex.trim().replace(/^#/, "");
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  if (h.length !== 6 || /[^0-9a-fA-F]/.test(h)) return null;
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number];
+};
+
+/**
+ * Returns a readable text color ("#111111" or "#ffffff") to place ON `bg`,
+ * chosen by perceived brightness (YIQ). Falls back to white for non-hex input.
+ * Use for any text/icon sitting on a themed fill (buttons on the primary, etc.).
+ */
+export const readableTextOn = (bg: string): string => {
+  const rgb = parseHex(bg);
+  if (!rgb) return "#ffffff";
+  const [r, g, b] = rgb;
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000;
+  return yiq >= 150 ? "#111111" : "#ffffff";
+};

package/src/utils/analyticsBus.ts

@@ -0,0 +1,31 @@
+// A tiny framework-agnostic bus so the global <ForgeAnalytics/> and any per-page
+// <PageMetaPixel/> can coordinate without prop-drilling through the router:
+//
+// - `currentPageEventId` — the event id ForgeAnalytics generated for the current
+//   page view. A page pixel reuses it so its browser event and the server-side
+//   Custom Page CAPI event dedupe on Meta (they share one event_id).
+// - suppressed paths — routes where a campaign pixel has taken over, so the
+//   global profile pixel skips its PageView there (see PageMetaPixel override).
+
+let currentPageEventId: string | null = null;
+const suppressedPaths = new Set<string>();
+
+export function setCurrentPageEventId(id: string): void {
+  currentPageEventId = id;
+}
+
+export function getCurrentPageEventId(): string | null {
+  return currentPageEventId;
+}
+
+export function suppressProfilePixel(path: string): void {
+  suppressedPaths.add(path);
+}
+
+export function unsuppressProfilePixel(path: string): void {
+  suppressedPaths.delete(path);
+}
+
+export function isProfilePixelSuppressed(path: string): boolean {
+  return suppressedPaths.has(path);
+}

package/src/utils/attribution.ts

@@ -0,0 +1,68 @@
+// Local helper for the link-attribution flow. The redirect handler stamps
+// `?tn_ref=<uuid>` onto the destination URL when a recipient clicks a
+// tracked link in a social DM. The root effect captures it into
+// localStorage; checkout reads it back and sends it with the order.
+//
+// 30-day TTL keeps stale refs from credit-stealing months later — covers
+// the realistic window between "user saw the DM" and "user actually buys".
+
+const STORAGE_KEY = "tn:attributionRef";
+const TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+type StoredRef = { id: string; at: number };
+
+function isStoredRef(value: unknown): value is StoredRef {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.id === "string" && typeof v.at === "number";
+}
+
+export function persistAttributionRef(id: string): void {
+  if (typeof window === "undefined") return;
+  try {
+    const payload: StoredRef = { id, at: Date.now() };
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(payload));
+  } catch {
+    // Quota / disabled storage — quietly drop. Click is still tracked
+    // server-side; only the order-attribution join is lost.
+  }
+}
+
+export function readAttributionRef(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    if (!isStoredRef(parsed)) return null;
+    if (Date.now() - parsed.at > TTL_MS) {
+      // Expired — clear so we stop attaching it to future orders.
+      window.localStorage.removeItem(STORAGE_KEY);
+      return null;
+    }
+    return parsed.id;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Captures `?tn_ref=<uuid>` from the current URL into localStorage and strips
+ * it from the visible URL so it doesn't leak through copy-paste or referer.
+ * Idempotent — safe to call on every render. Returns true when a ref was
+ * captured.
+ */
+export function captureAttributionRefFromUrl(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    const url = new URL(window.location.href);
+    const ref = url.searchParams.get("tn_ref");
+    if (!ref) return false;
+    persistAttributionRef(ref);
+    url.searchParams.delete("tn_ref");
+    window.history.replaceState({}, "", `${url.pathname}${url.search}${url.hash}`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/cookieConsent.ts

@@ -0,0 +1,83 @@
+// Cookie-consent storage + a tiny pub/sub so analytics can react the moment the
+// visitor makes a choice. Deliberately shares the platform's existing keys —
+// `cookieSettings` (localStorage) + the `cookies-consent` cookie — so a visitor's
+// decision is consistent between code sites and the CMS/Craft.js sites.
+
+export type CookieConsent = {
+  /** Strictly-necessary cookies. Always on — cannot be rejected. */
+  functional: boolean;
+  /** Analytics / performance (first-party page views + clicks). */
+  performance: boolean;
+  /** Marketing / advertising (e.g. the Meta Pixel). */
+  marketing: boolean;
+};
+
+export const COOKIE_CONSENT_KEY = "cookieSettings";
+const COOKIE_NAME = "cookies-consent";
+/** Fired on the window whenever consent is written, so live tabs re-read it. */
+export const COOKIE_CONSENT_EVENT = "forge:cookieconsent";
+
+/** The decision for a visitor who has accepted nothing yet. */
+export const DENY_ALL: CookieConsent = { functional: true, performance: false, marketing: false };
+export const GRANT_ALL: CookieConsent = { functional: true, performance: true, marketing: true };
+
+/** Read the stored consent, or `null` if the visitor hasn't decided yet. */
+export function getCookieConsent(): CookieConsent | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(COOKIE_CONSENT_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<CookieConsent>;
+    return {
+      functional: true, // always on regardless of what was stored
+      performance: !!parsed.performance,
+      marketing: !!parsed.marketing,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Persist consent to localStorage + a 1-year cookie, then notify listeners. */
+export function saveCookieConsent(consent: CookieConsent): void {
+  if (typeof window === "undefined") return;
+  const value: CookieConsent = { ...consent, functional: true };
+  try {
+    window.localStorage.setItem(COOKIE_CONSENT_KEY, JSON.stringify(value));
+    const secure = window.location.protocol === "https:" ? "; Secure" : "";
+    document.cookie = `${COOKIE_NAME}=${encodeURIComponent(JSON.stringify(value))}; path=/; max-age=31536000; SameSite=Lax${secure}`;
+  } catch {
+    // storage disabled — the event still fires so in-memory listeners update
+  }
+  window.dispatchEvent(new Event(COOKIE_CONSENT_EVENT));
+}
+
+/** Wipe the stored decision so the banner shows again, then notify listeners —
+ * so a "Cookie settings" trigger in one component re-opens a `<CookieConsent/>`
+ * rendered elsewhere (e.g. in TribeNestApp). Unlike a bare removeItem, this broadcasts. */
+export function clearCookieConsent(): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(COOKIE_CONSENT_KEY);
+    const secure = window.location.protocol === "https:" ? "; Secure" : "";
+    document.cookie = `${COOKIE_NAME}=; path=/; max-age=0; SameSite=Lax${secure}`;
+  } catch {
+    // storage disabled — the event still fires so in-memory listeners update
+  }
+  window.dispatchEvent(new Event(COOKIE_CONSENT_EVENT));
+}
+
+/** Subscribe to consent changes (this tab via the custom event, other tabs via
+ * the native `storage` event). Returns an unsubscribe fn. */
+export function onCookieConsentChange(cb: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  const onStorage = (e: StorageEvent) => {
+    if (e.key === COOKIE_CONSENT_KEY) cb();
+  };
+  window.addEventListener(COOKIE_CONSENT_EVENT, cb);
+  window.addEventListener("storage", onStorage);
+  return () => {
+    window.removeEventListener(COOKIE_CONSENT_EVENT, cb);
+    window.removeEventListener("storage", onStorage);
+  };
+}

package/src/utils/landing.ts

@@ -0,0 +1,153 @@
+// First-touch landing attribution (Shopify-style).
+//
+// The FIRST time a visitor lands on the artist's site we snapshot the full
+// query-param bag (every `utm_*`, ad click-id like `fbclid`/`gclid`/`ttclid`,
+// and any other param — verbatim) plus `document.referrer` and the landing
+// URL. Checkout reads it back and sends `landingUtm` + `referrer` with every
+// purchase, so later attribution/ROAS can tie a sale to the ad that drove it —
+// regardless of whether the ad was created on TribeNest or elsewhere.
+//
+// First-touch wins with a 30-day TTL: the very first landing is preserved for
+// 30 days, matching the tracked-link `tn:attributionRef` semantics so the two
+// attribution signals expire together. See docs/ads-attribution-initiative.md.
+
+const STORAGE_KEY = "tn:landing";
+const TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+export type LandingSnapshot = {
+  /** Full query-param bag from the first landing URL (verbatim keys). */
+  landingUtm: Record<string, string>;
+  /** document.referrer at first landing ("" when opened directly). */
+  referrer: string;
+  /** The full first-landing href, for forensics. */
+  landingUrl: string;
+  /** Capture timestamp (ms) for the TTL check. */
+  at: number;
+  /** Stable per-visitor session id — dedupes repeat beacons server-side. */
+  sessionId?: string;
+};
+
+function randomSessionId(): string {
+  try {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
+  } catch {
+    // fall through
+  }
+  return `s_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+}
+
+function isLandingSnapshot(value: unknown): value is LandingSnapshot {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.landingUtm === "object" &&
+    v.landingUtm !== null &&
+    typeof v.referrer === "string" &&
+    typeof v.at === "number"
+  );
+}
+
+/**
+ * Reads the stored first-touch snapshot if it's still within the 30-day TTL.
+ * Returns null (and clears the expired entry) otherwise.
+ */
+function readSnapshot(): LandingSnapshot | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    if (!isLandingSnapshot(parsed)) return null;
+    if (Date.now() - parsed.at > TTL_MS) {
+      window.localStorage.removeItem(STORAGE_KEY);
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Snapshots the current URL's params + referrer into localStorage on the
+ * FIRST landing only (idempotent — safe to call on every render). Does NOT
+ * strip the params from the URL: the page's own ad pixels / analytics may
+ * still need them. Returns true when a fresh snapshot was written.
+ */
+export function captureLandingFromUrl(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    // First-touch wins: never overwrite a live snapshot.
+    if (readSnapshot()) return false;
+
+    const url = new URL(window.location.href);
+    const landingUtm: Record<string, string> = {};
+    url.searchParams.forEach((value, key) => {
+      // Last value wins on duplicate keys; cap key/value length to avoid abuse.
+      if (key.length <= 128 && value.length <= 512) landingUtm[key] = value;
+    });
+
+    const snapshot: LandingSnapshot = {
+      landingUtm,
+      referrer: typeof document !== "undefined" ? document.referrer || "" : "",
+      landingUrl: window.location.href,
+      at: Date.now(),
+      sessionId: randomSessionId(),
+    };
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(snapshot));
+    return true;
+  } catch {
+    // Quota / disabled storage — quietly drop. The purchase still succeeds,
+    // only the landing attribution is lost.
+    return false;
+  }
+}
+
+/**
+ * Returns the first-touch `landingUtm` bag + `referrer` for the checkout
+ * payload, or null when nothing is stored / it expired. `landingUtm` is
+ * undefined when the bag is empty so we don't ship `{}`.
+ */
+export function readLanding(): { landingUtm?: Record<string, string>; referrer?: string } | null {
+  const snapshot = readSnapshot();
+  if (!snapshot) return null;
+  const hasParams = Object.keys(snapshot.landingUtm).length > 0;
+  return {
+    landingUtm: hasParams ? snapshot.landingUtm : undefined,
+    referrer: snapshot.referrer || undefined,
+  };
+}
+
+/**
+ * Fire-and-forget POST of the stored first-touch snapshot to the visit-level
+ * landing beacon. Records a landing_session server-side even when the visitor
+ * never buys — powering per-campaign visit counts + external click-id matching.
+ * Call ONCE on fresh capture (when captureLandingFromUrl returned true), so a
+ * visit is counted a single time within the 30-day window.
+ */
+export function postLandingBeacon(apiUrl: string, profileId: string, attributionRefId?: string): void {
+  if (typeof window === "undefined" || !apiUrl || !profileId) return;
+  const snapshot = readSnapshot();
+  if (!snapshot) return;
+  const hasParams = Object.keys(snapshot.landingUtm).length > 0;
+  // Nothing worth recording for a truly organic visit (no params, no referrer).
+  if (!hasParams && !snapshot.referrer) return;
+
+  try {
+    void fetch(`${apiUrl.replace(/\/$/, "")}/public/marketing/landing`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      keepalive: true,
+      body: JSON.stringify({
+        profileId,
+        attributionRefId,
+        sessionId: snapshot.sessionId,
+        landingUrl: snapshot.landingUrl,
+        landingUtm: hasParams ? snapshot.landingUtm : undefined,
+        referrer: snapshot.referrer || undefined,
+      }),
+    }).catch(() => {});
+  } catch {
+    // Beacon is best-effort; never disrupt the page.
+  }
+}

package/src/utils/metaPixel.ts

@@ -0,0 +1,122 @@
+// Client-side Meta pixel firing — mirror of the server-side CAPI events,
+// matched on `event_id` so Meta dedupes the pair. Backend CAPI is the source
+// of truth; this script-side firing exists to keep Meta's pixel inspector
+// happy and to capture the pre-purchase funnel events the backend doesn't see.
+//
+// Supports MULTIPLE pixels on one page (a profile-wide pixel + a per-campaign
+// pixel on a landing page). Each pixel is fired individually with `trackSingle`
+// so a PageView on one doesn't leak into the others.
+
+type MetaEventName = "PageView" | "ViewContent" | "AddToCart" | "InitiateCheckout" | "Purchase" | "Lead";
+
+// fbq is a variadic queue shim (init / track / trackSingle / …). We access it via
+// a local cast rather than a `declare global`, so Forge never conflicts with a
+// host app's own `Window.fbq` typing.
+type Fbq = (...args: any[]) => void;
+function getFbq(): Fbq | undefined {
+  return typeof window !== "undefined" ? ((window as any).fbq as Fbq | undefined) : undefined;
+}
+
+let scriptLoaded = false;
+const initedPixels = new Set<string>();
+
+// Meta pixel ids are numeric — strip anything else defensively before it reaches
+// an `fbq` call or a template.
+function cleanId(pixelId: string): string {
+  return String(pixelId).replace(/[^0-9]/g, "");
+}
+
+// Inject the Meta base shim once (defines `window.fbq` as a queue + loads
+// fbevents.js). Deliberately does NOT init a pixel or fire PageView — callers
+// do that explicitly so multi-pixel pages stay isolated.
+function loadFbevents(): void {
+  if (scriptLoaded || typeof window === "undefined") return;
+  if (getFbq()) {
+    scriptLoaded = true;
+    return;
+  }
+  const script = document.createElement("script");
+  script.async = true;
+  script.innerHTML = `
+    !function(f,b,e,v,n,t,s){
+      if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+      n.callMethod.apply(n,arguments):n.queue.push(arguments)};
+      if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
+      n.queue=[];t=b.createElement(e);t.async=!0;
+      t.src=v;s=b.getElementsByTagName(e)[0];
+      s.parentNode.insertBefore(t,s)
+    }(window, document,'script','https://connect.facebook.net/en_US/fbevents.js');
+  `;
+  document.head.appendChild(script);
+  scriptLoaded = true;
+}
+
+// Ensure a pixel is initialized exactly once. Returns the cleaned id (or "").
+function ensurePixel(pixelId: string): string {
+  const id = cleanId(pixelId);
+  if (!id || typeof window === "undefined") return id;
+  loadFbevents();
+  if (!initedPixels.has(id)) {
+    getFbq()?.("init", id);
+    initedPixels.add(id);
+  }
+  return id;
+}
+
+/**
+ * Backward-compatible init: loads the pixel and fires a PageView (to every
+ * initialized pixel, via `track`). Existing single-pixel callers rely on this.
+ * For multi-pixel pages prefer `initMetaPixelScoped` + `fireMetaEventSingle`.
+ */
+export function initMetaPixel(pixelId: string): void {
+  if (typeof window === "undefined") return;
+  const id = ensurePixel(pixelId);
+  if (id) getFbq()?.("track", "PageView");
+}
+
+/** Init a pixel WITHOUT auto-firing PageView — for multi-pixel pages where each
+ * pixel fires its own events via `fireMetaEventSingle`. */
+export function initMetaPixelScoped(pixelId: string): void {
+  if (typeof window === "undefined") return;
+  ensurePixel(pixelId);
+}
+
+/** Fire an event to ALL initialized pixels (legacy single-pixel behavior). */
+export function fireMetaEvent(
+  eventName: MetaEventName,
+  customData: Record<string, unknown> = {},
+  eventID?: string,
+): void {
+  const fbq = getFbq();
+  if (!fbq) return;
+  if (eventID) fbq("track", eventName, customData, { eventID });
+  else fbq("track", eventName, customData);
+}
+
+/** Fire an event to ONE specific pixel (`trackSingle`) — keeps a campaign pixel's
+ * events out of the profile pixel and vice-versa. */
+export function fireMetaEventSingle(
+  pixelId: string,
+  eventName: MetaEventName | string,
+  customData: Record<string, unknown> = {},
+  eventID?: string,
+): void {
+  const fbq = getFbq();
+  if (!fbq) return;
+  const id = cleanId(pixelId);
+  if (!id) return;
+  if (eventID) fbq("trackSingle", id, eventName, customData, { eventID });
+  else fbq("trackSingle", id, eventName, customData);
+}
+
+// Reads the Meta browser-set cookies so the backend CAPI request can pass them
+// through in `user_data` — that's how Meta matches browser-side and
+// server-side events to a single user.
+export function readMetaCookies(): { fbp?: string; fbc?: string } {
+  if (typeof document === "undefined") return {};
+  const match = (name: string) => {
+    const m = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+    return m ? decodeURIComponent(m[1]) : undefined;
+  };
+  return { fbp: match("_fbp"), fbc: match("_fbc") };
+}