@web-my-money/studio-consumer 1.0.0

package/src/analytics/components.tsx

@@ -0,0 +1,382 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { usePathname } from "next/navigation";
+import { trackFunnelEvent, registerExperiments } from "./collector";
+import type { RunningExperiment } from "./bucketing";
+
+/**
+ * Emits `page_view` into the first-party funnel collector, once per path.
+ *
+ * This exists because nothing else does it. GTM has its own page-view tag, and
+ * `lib/analytics.ts`'s `track()` only mirrors events that some component
+ * explicitly fires — no component fires a page view. Without this, every metric
+ * in the rollups that divides by visitors (conversion rate, most obviously) has
+ * a zero denominator, and the funnel report is empty however many forms are
+ * filled in.
+ *
+ * Mounted once in the locale layout, so it covers every page including ones with
+ * no form on them. Deliberately does NOT touch attribution capture: that system
+ * has its own documented invariants (docs/forms-tracking-attribution.md) and
+ * money riding on it, so widening where it runs is a separate decision from
+ * counting page views.
+ *
+ * Inert unless the collector is switched on, and it renders nothing.
+ */
+export function FunnelAnalytics() {
+  const pathname = usePathname();
+  // Guards against a double emit from React's development double-invoke and from
+  // a re-render that does not change the path.
+  const lastPath = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!pathname || lastPath.current === pathname) return;
+    lastPath.current = pathname;
+    trackFunnelEvent("page_view", { path: pathname });
+  }, [pathname]);
+
+  return null;
+}
+
+/**
+ * Scroll depth and click tracking, into our own event store.
+ *
+ * Why this is not already covered by what we run:
+ *
+ *  - **GA4** records a single `scroll` event at 90% and nothing before it, so
+ *    "half the page" is invisible.
+ *  - **Clarity** has a scroll heatmap, which is excellent for *looking* at one
+ *    page and useless for *counting* — it cannot tell you that people who reach
+ *    75% convert at three times the rate of people who don't, because it has no
+ *    idea which visitors became leads.
+ *
+ * That join is the whole point: these events land in `studio.funnel_events`
+ * beside the form steps and the CRM outcome, keyed by the same session.
+ *
+ * Same rules as the rest of the collector: never throws, never blocks, and does
+ * nothing at all when the collector is off or consent is not granted.
+ */
+
+/**
+ * Milestones, every 10%.
+ *
+ * Four buckets showed shape; ten shows a curve. The cost is bounded — at most ten
+ * events per page view, and they coalesce into the same 5s flush as everything
+ * else — and it is what lets the dashboard draw a drop-off line rather than four
+ * bars.
+ */
+export const THRESHOLDS = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] as const;
+
+/**
+ * Which thresholds this scroll position newly crosses.
+ *
+ * Pulled out and exported because this is where the bug would live: firing a
+ * threshold twice inflates the count, and skipping one when a visitor jumps
+ * (anchor link, keyboard End) loses it entirely. Returns every threshold at or
+ * below the position that has not fired yet, so a jump to the bottom reports all
+ * four rather than only 90.
+ */
+export function crossedThresholds(pct: number, fired: Set<number>): number[] {
+  if (!Number.isFinite(pct)) return [];
+  return THRESHOLDS.filter((t) => pct >= t && !fired.has(t));
+}
+
+/**
+ * A label for what was clicked.
+ *
+ * Order matters. `data-analytics` is authored, so it is stable across a redesign
+ * and safe by construction. Everything after it is a fallback.
+ *
+ * innerText is deliberately NEVER used: on a personalised page a button can read
+ * "Continue as jane@example.com", and that would put an email in the analytics
+ * store. Hrefs are stripped of query and hash for the same reason — a share or
+ * unsubscribe link can carry an identifier.
+ */
+/**
+ * Tailwind's first segments, plus the bare utilities that have no dash.
+ *
+ * A heuristic, and openly one — but a far more stable one than enumerating every
+ * utility, because Tailwind's vocabulary grows in the value half (`rounded-xl`,
+ * `rounded-3xl`) and almost never in the property half. Checked against the
+ * segment before the first dash, so `rounded-xl` is rejected by `rounded` while an
+ * authored `cta-primary` survives.
+ */
+const UTILITY_SEGMENTS = new Set([
+  "p","px","py","pt","pr","pb","pl","m","mx","my","mt","mr","mb","ml",
+  "w","h","min","max","size","aspect",
+  "text","bg","border","rounded","shadow","ring","outline","divide","fill","stroke",
+  "flex","grid","col","row","gap","space","items","justify","self","order","place","content",
+  "top","left","right","bottom","inset","z","float","clear",
+  "font","leading","tracking","whitespace","break","list","indent","align","decoration",
+  "opacity","cursor","overflow","object","pointer","select","resize","scroll","snap","touch",
+  "transition","duration","delay","ease","animate","transform","scale","rotate","translate","skew","origin",
+  "backdrop","blur","brightness","contrast","grayscale","invert","saturate","sepia","filter","mix",
+  "from","via","to","bs","table","caption","sr","will","isolation",
+  // Variants and breakpoints, which also appear as the first segment.
+  "sm","md","lg","xl","hover","focus","active","visited","disabled","group","peer","dark","motion","print",
+  // Bare utilities with no dash at all.
+  "block","inline","hidden","absolute","relative","fixed","sticky","static","flow",
+  "container","truncate","uppercase","lowercase","capitalize","italic","underline",
+  "antialiased","invisible","visible","overline","subpixel",
+]);
+
+/**
+ * Does this class name look like something a person chose as a NAME, rather than
+ * as styling?
+ *
+ * The original rule was "use the first class", and a real session produced
+ * `button:px-2.5`, `button:group`, `button:rounded-xl` and `button:absolute` —
+ * identical across unrelated buttons and changing on every restyle, so two
+ * different buttons collapsed into one row in the click report. Worse than no
+ * label, because the row still looks meaningful.
+ */
+/**
+ * A button's own visible text, but only when it is plainly UI copy.
+ *
+ * This deliberately narrows a rule that used to be a flat refusal. The comment
+ * below `isAuthoredClass` is right that `textContent` is user content in a way
+ * `aria-label` is not: on a personalised page it can carry someone's name or
+ * email. But refusing it entirely is what left the click report saying
+ * "an unnamed button" as its single biggest row, which is the one row nobody can
+ * act on. Most buttons on this site say "Book a call" or "Next testimonial", and
+ * throwing that away to guard against a case that mostly does not occur here
+ * costs more than it protects.
+ *
+ * So: take the text, and refuse it the moment it looks like it could be about a
+ * person rather than about the interface.
+ *
+ * Rejected outright:
+ *  - anything with `@` (an email, or a handle)
+ *  - any run of 5+ digits (a phone number, an order id, a postcode)
+ *  - anything longer than 40 characters, which is a sentence, not a label
+ *  - anything with a newline, which means it swallowed nested markup
+ *
+ * A rejection falls through to the existing chain, so the worst case is exactly
+ * today's behaviour. Nothing here can make the label MORE identifying than it
+ * already was.
+ */
+function safeButtonText(button: HTMLButtonElement): string | null {
+  const raw = (button.textContent ?? "").replace(/\s+/g, " ").trim();
+  if (!raw) return null;
+  if (raw.length > 40) return null;
+  if (raw.includes("@")) return null;
+  if (/\d{5,}/.test(raw)) return null;
+  // A label made only of punctuation or symbols (an icon-only button rendering a
+  // glyph) tells the reader nothing and would group unrelated buttons together.
+  if (!/[a-z]{2,}/i.test(raw)) return null;
+  return raw;
+}
+
+function isAuthoredClass(name: string): boolean {
+  // Variants and arbitrary values are always styling: `hover:bg-x`, `w-[3px]`.
+  if (/[:[\]/()]/.test(name)) return false;
+  // This project's own convention wins outright: `studio-form__continue`.
+  if (name.includes("__")) return true;
+  const first = name.split("-")[0]!.toLowerCase();
+  if (UTILITY_SEGMENTS.has(first)) return false;
+  // A bare number or a one-character class is not a name either.
+  return name.length > 2 && !/^\d/.test(name);
+}
+
+export function labelFor(el: Element): string | null {
+  const authored = el.getAttribute("data-analytics");
+  if (authored) return authored.slice(0, 120);
+
+  // `tagName`, not `instanceof HTMLAnchorElement`. Two reasons, both real:
+  // `instanceof` throws outright where the global is absent, and it returns
+  // FALSE for an element belonging to another realm — which this site has, since
+  // the lead-capture step is an iframe.
+  const tag = el.tagName ? el.tagName.toUpperCase() : "";
+
+  if (tag === "A") {
+    const href = (el as HTMLAnchorElement).href;
+    if (!href) return "link:empty";
+    try {
+      const url = new URL(href, window.location.href);
+      const sameSite = url.host === window.location.host;
+      // Query and hash dropped on purpose: a share, unsubscribe or prefilled
+      // link can carry an identifier, and keeping it would put that identifier
+      // in the analytics store.
+      return `${sameSite ? "link" : "outbound"}:${url.host}${url.pathname}`.slice(0, 120);
+    } catch {
+      return "link:unparseable";
+    }
+  }
+
+  if (tag === "BUTTON") {
+    const button = el as HTMLButtonElement;
+
+    // Order matters, and the last resort is deliberately NOT "the first class".
+    // That was the original rule and it produced labels like `button:px-2.5`,
+    // `button:group` and `button:rounded-xl` — Tailwind utilities, identical
+    // across unrelated buttons and changing on every restyle. Useless for
+    // analysis and actively misleading, since two different buttons collapse
+    // into one row.
+    //
+    // `aria-label` is authored markup rather than user content, so it is safe in
+    // a way `textContent` is not: an accessible name is written by us, while
+    // innerText on a personalised page can contain someone's name or email.
+    // Capped like everything else.
+    const authoredClass = Array.from(button.classList ?? []).find(isAuthoredClass);
+    /*
+      Visible text sits AFTER the authored identifiers and BEFORE the class
+      fallback. After, because an id or aria-label was chosen deliberately as a
+      name and should win. Before, because a Tailwind class is never a name, and
+      "Book a call" beats `studio-form__continue` for anyone reading a report.
+    */
+    const hint =
+      button.id ||
+      button.getAttribute("aria-label") ||
+      button.getAttribute("name") ||
+      safeButtonText(button) ||
+      authoredClass ||
+      "unlabelled";
+    return `button:${hint}`.slice(0, 120);
+  }
+
+  return null;
+}
+
+/** The nearest thing worth attributing a click to. */
+function trackable(target: EventTarget | null): Element | null {
+  if (!(target instanceof Element)) return null;
+  return target.closest("[data-analytics], a, button");
+}
+
+export function EngagementTracking() {
+  const pathname = usePathname();
+  const fired = useRef<Set<number>>(new Set());
+  const ticking = useRef(false);
+  /**
+   * The exact furthest point reached, reported once when the page is left.
+   *
+   * This is what makes a *continuous* curve possible: milestones can only ever
+   * draw as many points as there are milestones, whereas one exact value per page
+   * view supports any percentile — "half your visitors get past 43%" is a
+   * question no fixed bucket set can answer.
+   */
+  const maxDepth = useRef(0);
+  const reported = useRef(false);
+
+  // Thresholds are per page: a single-page-app navigation is a new page to a
+  // visitor, so carrying "already scrolled 90%" across it would hide the fact
+  // that they never scrolled the second one.
+  useEffect(() => {
+    fired.current = new Set();
+    maxDepth.current = 0;
+    reported.current = false;
+  }, [pathname]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const measure = () => {
+      ticking.current = false;
+      try {
+        const doc = document.documentElement;
+        const scrollable = doc.scrollHeight - window.innerHeight;
+        // A page shorter than the viewport cannot be scrolled, and reporting
+        // 100% for it would make every short page look fully read.
+        if (scrollable <= 0) return;
+
+        const pct = ((window.scrollY || doc.scrollTop || 0) / scrollable) * 100;
+        if (pct > maxDepth.current) maxDepth.current = Math.min(100, Math.round(pct));
+        for (const threshold of crossedThresholds(pct, fired.current)) {
+          fired.current.add(threshold);
+          trackFunnelEvent("scroll_depth", { value: threshold });
+        }
+      } catch {
+        /* a tracking bug must not break scrolling */
+      }
+    };
+
+    // rAF-coalesced: scroll fires per frame on some browsers and per pixel on
+    // others, and this must not be the reason a page janks.
+    const onScroll = () => {
+      if (ticking.current) return;
+      ticking.current = true;
+      requestAnimationFrame(measure);
+    };
+
+    const onClick = (event: Event) => {
+      try {
+        const el = trackable(event.target);
+        if (!el) return;
+        const label = labelFor(el);
+        if (label) trackFunnelEvent("element_click", { label });
+      } catch {
+        /* never interfere with a click — especially not a CTA */
+      }
+    };
+
+    /**
+     * Report the exact maximum on the way out.
+     *
+     * `visibilitychange` → hidden for the same reason as everywhere else in this
+     * collector: `unload` does not fire reliably on mobile Safari. Latched, so a
+     * visitor who tabs away four times reports one figure rather than four.
+     */
+    const reportMax = () => {
+      try {
+        if (document.visibilityState !== "hidden") return;
+        if (reported.current || maxDepth.current <= 0) return;
+        reported.current = true;
+        trackFunnelEvent("scroll_max", { value: maxDepth.current });
+      } catch {
+        /* never let this surface */
+      }
+    };
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    document.addEventListener("visibilitychange", reportMax);
+    // Capture phase, so a handler that stops propagation (a modal trigger, a
+    // form's own button) does not make the click invisible to us.
+    document.addEventListener("click", onClick, { capture: true, passive: true });
+    // Measure once on mount: a visitor landing on an anchor is already scrolled.
+    measure();
+
+    return () => {
+      // Report on unmount too — a client-side navigation away from the page is a
+      // page view ending, and it never fires visibilitychange.
+      if (!reported.current && maxDepth.current > 0) {
+        reported.current = true;
+        try {
+          trackFunnelEvent("scroll_max", { value: maxDepth.current });
+        } catch {
+          /* never let this surface */
+        }
+      }
+      window.removeEventListener("scroll", onScroll);
+      document.removeEventListener("visibilitychange", reportMax);
+      document.removeEventListener("click", onClick, { capture: true });
+    };
+  }, [pathname]);
+
+  return null;
+}
+
+/**
+ * Hands the published experiment list to the collector so every event carries
+ * the visitor's A/B arm.
+ *
+ * Renders nothing. It exists because the arm was never recorded: the server
+ * chose the copy and the browser sent the events, and nothing carried the
+ * decision across the gap. `funnel_events.variant` therefore held a form's CSS
+ * skin name or nothing at all, so Studio's comparison had two arms that were
+ * both really "everyone" — a test could run to completion and report "no
+ * difference", correctly, forever.
+ *
+ * Registered during render rather than in an effect on purpose. `page_view`
+ * fires from `FunnelAnalytics`'s effect, which runs AFTER a child's render but
+ * could run before a sibling's effect depending on tree order, and an unlabelled
+ * page view is a session whose arm is unknown for its most important event.
+ * Assigning a module-level variable is idempotent and has no cleanup, so there
+ * is nothing here for an effect to buy.
+ *
+ * The list is published content, fixed for the life of a deploy, so this costs
+ * one small prop in the RSC payload and no request.
+ */
+export function AbArm({ experiments }: { experiments: RunningExperiment[] }) {
+  registerExperiments(experiments);
+  return null;
+}

package/src/analytics/index.ts

@@ -0,0 +1,37 @@
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "1.0.0";
+
+export {
+  resolveVariant,
+  bucketFor,
+  CONTROL,
+  VARIANT,
+  VISITOR_COOKIE,
+  type RunningExperiment,
+} from "./bucketing";
+
+export {
+  trackFunnelEvent,
+  registerExperiments,
+  flushFunnelEvents,
+  currentSessionId,
+  funnelAnalyticsEnabled,
+  consentGranted,
+  resetFunnelAnalytics,
+  type FunnelEventProps,
+} from "./collector";
+
+export { useFormAnalytics, type FormAnalytics, type FormAnalyticsOptions } from "./use-form-analytics";
+
+export {
+  FunnelAnalytics,
+  EngagementTracking,
+  AbArm,
+  THRESHOLDS,
+  crossedThresholds,
+  labelFor,
+} from "./components";
+
+export { createCollectHandler } from "./collect-handler";
+
+export { withVisitorCookie } from "./proxy";

package/src/analytics/proxy.ts

@@ -0,0 +1,87 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+/**
+ * Middleware helper: the first-party visitor cookie that server-side A/B
+ * assignment needs.
+ *
+ * The med-spa slug canonicalisation redirect that wmm-website's own `proxy.ts`
+ * also does is NOT part of this — that is wmm-website's own routing rule, not
+ * part of the contract a consumer app onboards to.
+ */
+
+/** Same name the analytics collector reads, so both sides agree on one identity. */
+const VISITOR_COOKIE = "wmm_vid";
+/** 400 days is the maximum Chrome honours for a cookie's lifetime. */
+const VISITOR_COOKIE_MAX_AGE = 400 * 24 * 60 * 60;
+
+/**
+ * A uuid without importing crypto's Node API — middleware runs on the edge
+ * runtime, where `crypto.randomUUID` is available on the global.
+ */
+function newVisitorId(): string {
+  return crypto.randomUUID();
+}
+
+export function withVisitorCookie(req: NextRequest): NextResponse {
+  const { pathname } = req.nextUrl;
+
+  // The path, as a request header.
+  //
+  // Server components cannot read their own pathname, and A/B assignment has to
+  // know which page it is on to find the experiment targeting it. Middleware is
+  // the only place that knows both the path and the cookies, so it forwards the
+  // path and `lib/content.ts` reads it back.
+  const requestHeaders = new Headers(req.headers);
+  requestHeaders.set("x-wmm-path", pathname);
+
+  /**
+   * `?wmm-variant=b` — show variant B to whoever asked, regardless of bucketing.
+   *
+   * Studio's editor needs this. Its whole A/B workflow is "make a variant, look
+   * at it, then launch", and before launch there IS no experiment, so
+   * `activeVariant()` has nothing to resolve and correctly answers control. The
+   * editor could therefore never see the thing it was editing.
+   *
+   * Forwarded as a header rather than read from `searchParams` in the page so
+   * that `lib/content.ts` keeps ONE place where the arm is decided, and so a
+   * page does not have to opt in to make the preview work.
+   *
+   * Not a secret and not a risk: both arms are published site copy, so the worst
+   * anyone can do with this param is read content we are already serving to some
+   * fraction of visitors. It does not enter an experiment, and the collector
+   * marks a request carrying it as internal, so a preview cannot write events
+   * into the arm under test.
+   */
+  const previewVariant = req.nextUrl.searchParams.get("wmm-variant");
+  if (previewVariant === "b") requestHeaders.set("x-wmm-variant", "b");
+
+  const response = NextResponse.next({ request: { headers: requestHeaders } });
+
+  /**
+   * The visitor id, as a first-party cookie.
+   *
+   * A/B assignment has to happen SERVER-side or the visitor sees a flash of the
+   * wrong variant — which is both ugly and a measurement artefact, since the
+   * flash itself changes behaviour. The analytics collector keeps its visitor id
+   * in localStorage, which a server cannot read, so the identity also lives here
+   * where it can be. The collector prefers this cookie, so the two never
+   * disagree about who someone is.
+   *
+   * Not httpOnly, on purpose: the collector reads it in the browser. It carries
+   * no PII — it is a random id, exactly like the localStorage value it replaces.
+   */
+  if (!req.cookies.get(VISITOR_COOKIE)?.value) {
+    response.cookies.set({
+      name: VISITOR_COOKIE,
+      value: newVisitorId(),
+      maxAge: VISITOR_COOKIE_MAX_AGE,
+      path: "/",
+      sameSite: "lax",
+      httpOnly: false,
+      secure: true,
+    });
+  }
+
+  return response;
+}