@drip-apex/sdk 0.1.0

package/src/heatmap.test.ts

@@ -0,0 +1,305 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { startHeatmapCapture } from "./heatmap";
+import type { Assignment, Experiment } from "./types";
+
+const assignment: Assignment = {
+  experimentId: "exp_1",
+  variationId: "var_1",
+  index: 0,
+  mutations: [],
+  isControl: false,
+  hashValue: "hash_1",
+};
+
+function experiment(
+  capture: NonNullable<Experiment["behaviorCapture"]>,
+): Experiment {
+  return {
+    id: "exp_1",
+    behaviorCapture: {
+      enabled: true,
+      sampleRate: 1,
+      clicks: false,
+      scrolls: false,
+      moves: true,
+      ...capture,
+    },
+    variations: [],
+  };
+}
+
+function setVisibility(value: "visible" | "hidden") {
+  Object.defineProperty(document, "visibilityState", {
+    configurable: true,
+    value,
+  });
+}
+
+function dispatchPointer(clientX: number, pageY: number) {
+  const event = new MouseEvent("pointermove", {
+    bubbles: true,
+    clientX,
+    clientY: Math.min(pageY, window.innerHeight - 1),
+  });
+  Object.defineProperty(event, "pageY", { configurable: true, value: pageY });
+  document.dispatchEvent(event);
+}
+
+function dispatchClick(target: Element, pageX: number, pageY: number) {
+  const event = new MouseEvent("click", {
+    bubbles: true,
+    clientX: pageX,
+    clientY: pageY,
+  });
+  Object.defineProperty(event, "pageX", { configurable: true, value: pageX });
+  Object.defineProperty(event, "pageY", { configurable: true, value: pageY });
+  target.dispatchEvent(event);
+}
+
+describe("startHeatmapCapture", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-07-10T12:00:00.000Z"));
+    sessionStorage.clear();
+    history.replaceState({}, "", "/products/example");
+    setVisibility("visible");
+    Object.defineProperty(window, "innerWidth", { configurable: true, value: 1_000 });
+    Object.defineProperty(window, "innerHeight", { configurable: true, value: 800 });
+    Object.defineProperty(window, "scrollX", { configurable: true, value: 0 });
+    Object.defineProperty(window, "scrollY", { configurable: true, value: 0 });
+    Object.defineProperty(document.body, "scrollHeight", {
+      configurable: true,
+      value: 2_000,
+    });
+    Object.defineProperty(document.documentElement, "scrollHeight", {
+      configurable: true,
+      value: 2_000,
+    });
+    document.body.replaceChildren();
+  });
+
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("accumulates dwell in five-percent document-relative buckets", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({})],
+      track,
+    );
+
+    dispatchPointer(250, 500);
+    vi.advanceTimersByTime(1_000);
+    controller.stop();
+
+    expect(track).toHaveBeenCalledWith(
+      "heatmap_move",
+      expect.objectContaining({
+        path: "/products/example",
+        page_url: "http://localhost:3000/products/example",
+        sample_ms: 1_000,
+        points: "25:25:1000",
+      }),
+      "exp_1",
+      "var_1",
+    );
+  });
+
+  it("encodes highest-dwell points first and stays under the worker string cap", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({})],
+      track,
+    );
+
+    dispatchPointer(1, 1);
+    vi.advanceTimersByTime(1_200);
+    for (let index = 1; index <= 180; index += 1) {
+      const xBucket = index % 20;
+      const yBucket = Math.floor(index / 20);
+      dispatchPointer(xBucket * 50 + 1, yBucket * 100 + 1);
+      vi.advanceTimersByTime(200);
+    }
+    controller.stop();
+
+    const moveCall = track.mock.calls.find(([type]) => type === "heatmap_move");
+    expect(moveCall).toBeDefined();
+    const points = moveCall?.[1].points as string;
+    expect(points.length).toBeLessThanOrEqual(900);
+    expect(points.split(";")[0]).toBe("0:0:1200");
+  });
+
+  it("flushes and resets buffers when the document becomes hidden", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({})],
+      track,
+    );
+
+    dispatchPointer(100, 200);
+    vi.advanceTimersByTime(1_000);
+    setVisibility("hidden");
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    setVisibility("visible");
+    dispatchPointer(800, 1_600);
+    vi.advanceTimersByTime(1_000);
+    controller.stop();
+
+    const points = track.mock.calls
+      .filter(([type]) => type === "heatmap_move")
+      .map(([, payload]) => payload.points);
+    expect(points).toEqual(["10:10:1000", "80:80:1000"]);
+  });
+
+  it("flushes the old page on SPA navigation and starts a fresh page buffer", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({})],
+      track,
+    );
+
+    dispatchPointer(100, 200);
+    vi.advanceTimersByTime(1_000);
+    history.pushState({}, "", "/collections/new");
+    vi.advanceTimersByTime(200);
+    dispatchPointer(800, 1_600);
+    vi.advanceTimersByTime(1_000);
+    controller.stop();
+
+    const moves = track.mock.calls.filter(([type]) => type === "heatmap_move");
+    expect(moves).toHaveLength(2);
+    expect(moves[0][1]).toMatchObject({
+      path: "/products/example",
+      page_url: "http://localhost:3000/products/example",
+      points: "10:10:1000",
+    });
+    expect(moves[1][1]).toMatchObject({
+      path: "/collections/new",
+      page_url: "http://localhost:3000/collections/new",
+      points: "80:80:1000",
+    });
+  });
+
+  it("drops movement buffers below one second of dwell", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({})],
+      track,
+    );
+
+    dispatchPointer(250, 500);
+    vi.advanceTimersByTime(800);
+    controller.stop();
+
+    expect(track.mock.calls.some(([type]) => type === "heatmap_move")).toBe(false);
+  });
+
+  it("does not start movement capture when moves are disabled", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({ moves: false })],
+      track,
+    );
+
+    dispatchPointer(250, 500);
+    vi.advanceTimersByTime(2_000);
+    controller.stop();
+
+    expect(track.mock.calls.some(([type]) => type === "heatmap_move")).toBe(false);
+  });
+
+  it("recomputes movement capture when assignments are refreshed", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({ moves: false })],
+      track,
+    );
+
+    controller.update([assignment], [experiment({ moves: true })]);
+    dispatchPointer(250, 500);
+    vi.advanceTimersByTime(1_000);
+    controller.stop();
+
+    expect(track.mock.calls.filter(([type]) => type === "heatmap_move")).toHaveLength(1);
+  });
+
+  it("marks the third fast clustered click as rage", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({ clicks: true, moves: false })],
+      track,
+    );
+    const button = document.createElement("button");
+    button.textContent = "Buy";
+    document.body.append(button);
+
+    dispatchClick(button, 100, 100);
+    vi.advanceTimersByTime(150);
+    dispatchClick(button, 108, 104);
+    vi.advanceTimersByTime(150);
+    dispatchClick(button, 96, 102);
+    controller.stop();
+
+    const clicks = track.mock.calls.filter(([type]) => type === "heatmap_click");
+    expect(clicks).toHaveLength(3);
+    expect(clicks[0][1]).not.toHaveProperty("rage");
+    expect(clicks[1][1]).not.toHaveProperty("rage");
+    expect(clicks[2][1]).toHaveProperty("rage", 1);
+  });
+
+  it("does not flag clicks that are spatially spread out", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({ clicks: true, moves: false })],
+      track,
+    );
+    const button = document.createElement("button");
+    document.body.append(button);
+
+    dispatchClick(button, 100, 100);
+    vi.advanceTimersByTime(150);
+    dispatchClick(button, 200, 200);
+    vi.advanceTimersByTime(150);
+    dispatchClick(button, 100, 100);
+    controller.stop();
+
+    const clicks = track.mock.calls.filter(([type]) => type === "heatmap_click");
+    expect(clicks.every(([, payload]) => !("rage" in payload))).toBe(true);
+  });
+
+  it("does not flag clustered clicks outside the rage window", () => {
+    const track = vi.fn();
+    const controller = startHeatmapCapture(
+      [assignment],
+      [experiment({ clicks: true, moves: false })],
+      track,
+    );
+    const button = document.createElement("button");
+    document.body.append(button);
+
+    dispatchClick(button, 100, 100);
+    vi.advanceTimersByTime(1_201);
+    dispatchClick(button, 104, 102);
+    vi.advanceTimersByTime(1_201);
+    dispatchClick(button, 98, 99);
+    controller.stop();
+
+    const clicks = track.mock.calls.filter(([type]) => type === "heatmap_click");
+    expect(clicks.every(([, payload]) => !("rage" in payload))).toBe(true);
+  });
+});

package/src/heatmap.ts

@@ -0,0 +1,373 @@
+import type { Assignment, Experiment } from "./types";
+
+type TrackFn = (
+  type: string,
+  data: Record<string, unknown>,
+  experimentId: string,
+  variationId: string,
+) => void;
+
+type CaptureAssignment = Assignment & {
+  capture: NonNullable<Experiment["behaviorCapture"]>;
+};
+
+type HeatmapController = {
+  stop: () => void;
+  update: (assignments: Assignment[], experiments: Experiment[]) => void;
+};
+
+const SCROLL_BUCKETS = [25, 50, 75, 90, 100];
+const MOVEMENT_SAMPLE_MS = 200;
+const MOVEMENT_FLUSH_MS = 60_000;
+const MOVEMENT_GRID_SIZE = 5;
+const MOVEMENT_POINTS_MAX_LENGTH = 900;
+const MOVEMENT_MIN_DWELL_MS = 1_000;
+const RAGE_CLICK_WINDOW_MS = 1_200;
+const RAGE_CLICK_RADIUS_PX = 32;
+const RAGE_CLICK_BUFFER_SIZE = 4;
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function cleanUrl(): string {
+  return location.origin + location.pathname;
+}
+
+function stableSampleKey(assignment: Assignment): string {
+  return `drip_hm:${assignment.experimentId}:${assignment.variationId}`;
+}
+
+function sampledIn(assignment: Assignment, sampleRate: number): boolean {
+  if (sampleRate >= 1) return true;
+  if (sampleRate <= 0) return false;
+  try {
+    const key = stableSampleKey(assignment);
+    const existing = sessionStorage.getItem(key);
+    if (existing === "1") return true;
+    if (existing === "0") return false;
+    const selected = Math.random() < sampleRate;
+    sessionStorage.setItem(key, selected ? "1" : "0");
+    return selected;
+  } catch {
+    return Math.random() < sampleRate;
+  }
+}
+
+function normalizeSampleRate(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0.05;
+  return clamp(value, 0, 1);
+}
+
+function captureSelector(element: Element): string {
+  const parts: string[] = [];
+  let current: Element | null = element;
+  while (current && current !== document.documentElement && parts.length < 4) {
+    const tag = current.tagName.toLowerCase();
+    const id = current.id && /^[A-Za-z][\w-]{0,80}$/.test(current.id)
+      ? `#${current.id}`
+      : "";
+    if (id) {
+      parts.unshift(`${tag}${id}`);
+      break;
+    }
+
+    const testId =
+      current.getAttribute("data-testid") ||
+      current.getAttribute("data-test") ||
+      current.getAttribute("data-drip-id");
+    if (testId && /^[\w-]{1,80}$/.test(testId)) {
+      parts.unshift(`${tag}[data-testid="${testId}"]`);
+      break;
+    }
+
+    let nth = 1;
+    let sibling = current.previousElementSibling;
+    while (sibling) {
+      if (sibling.tagName === current.tagName) nth += 1;
+      sibling = sibling.previousElementSibling;
+    }
+    parts.unshift(`${tag}:nth-of-type(${nth})`);
+    current = current.parentElement;
+  }
+  return parts.join(" > ");
+}
+
+function safeElementText(element: Element): string {
+  const tag = element.tagName.toLowerCase();
+  if (tag === "input" || tag === "textarea" || tag === "select") return "";
+  return (element.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80);
+}
+
+function scrollPercent(): number {
+  const docHeight = Math.max(
+    document.body.scrollHeight,
+    document.documentElement.scrollHeight,
+  );
+  const viewportHeight = window.innerHeight || 1;
+  if (docHeight <= viewportHeight) return 100;
+  return Math.round(((window.scrollY + viewportHeight) / docHeight) * 100);
+}
+
+function resolveCaptureAssignments(
+  assignments: Assignment[],
+  experiments: Experiment[],
+): CaptureAssignment[] {
+  const experimentsById = new Map(experiments.map((experiment) => [experiment.id, experiment]));
+  const out: CaptureAssignment[] = [];
+  for (const assignment of assignments) {
+    const capture = experimentsById.get(assignment.experimentId)?.behaviorCapture;
+    if (!capture?.enabled) continue;
+    if (!sampledIn(assignment, normalizeSampleRate(capture.sampleRate))) continue;
+    out.push({ ...assignment, capture });
+  }
+  return out;
+}
+
+export function startHeatmapCapture(
+  assignments: Assignment[],
+  experiments: Experiment[],
+  track: TrackFn,
+): HeatmapController {
+  let active = resolveCaptureAssignments(assignments, experiments);
+  const seenScrollBuckets = new Set<string>();
+  let lastClickAt = 0;
+  let recentClicks: Array<{ x: number; y: number; t: number }> = [];
+  let lastPosition: { clientX: number; pageY: number } | null = null;
+  let movementBuckets = new Map<string, number>();
+  let bucketPageUrl = cleanUrl();
+  let movementSampleTimer: number | null = null;
+  let movementFlushTimer: number | null = null;
+
+  const movementEnabled = () =>
+    active.some((assignment) => assignment.capture.moves !== false);
+
+  const encodeMovementPoints = (buckets: Map<string, number>): string => {
+    const sorted = [...buckets.entries()].sort((a, b) => {
+      const dwellDifference = b[1] - a[1];
+      return dwellDifference !== 0 ? dwellDifference : a[0].localeCompare(b[0]);
+    });
+    const encoded: string[] = [];
+    let length = 0;
+    for (const [bucket, dwell] of sorted) {
+      const point = `${bucket}:${Math.round(dwell)}`;
+      const nextLength = length + (encoded.length > 0 ? 1 : 0) + point.length;
+      if (nextLength > MOVEMENT_POINTS_MAX_LENGTH) break;
+      encoded.push(point);
+      length = nextLength;
+    }
+    return encoded.join(";");
+  };
+
+  const flushMovement = () => {
+    if (movementBuckets.size === 0) return;
+    const buckets = movementBuckets;
+    movementBuckets = new Map();
+    const totalDwell = Math.round(
+      [...buckets.values()].reduce((sum, dwell) => sum + dwell, 0),
+    );
+    if (totalDwell < MOVEMENT_MIN_DWELL_MS) return;
+
+    const points = encodeMovementPoints(buckets);
+    if (!points) return;
+    let path = location.pathname;
+    try {
+      path = new URL(bucketPageUrl).pathname;
+    } catch {
+      // Keep the current pathname if the page URL cannot be parsed.
+    }
+    const payload = {
+      path,
+      page_url: bucketPageUrl,
+      viewport_width: window.innerWidth,
+      viewport_height: window.innerHeight,
+      document_height: Math.max(
+        document.body.scrollHeight,
+        document.documentElement.scrollHeight,
+      ),
+      sample_ms: totalDwell,
+      points,
+    };
+
+    for (const assignment of active) {
+      if (assignment.capture.moves === false) continue;
+      track("heatmap_move", payload, assignment.experimentId, assignment.variationId);
+    }
+  };
+
+  const sampleMovement = () => {
+    if (document.visibilityState !== "visible" || !lastPosition) return;
+    const currentPageUrl = cleanUrl();
+    if (currentPageUrl !== bucketPageUrl) {
+      flushMovement();
+      bucketPageUrl = currentPageUrl;
+      lastPosition = null;
+      return;
+    }
+
+    const documentHeight = Math.max(
+      1,
+      document.body.scrollHeight,
+      document.documentElement.scrollHeight,
+    );
+    const xPercent = clamp(
+      (lastPosition.clientX / Math.max(1, window.innerWidth)) * 100,
+      0,
+      99.999,
+    );
+    const yPercent = clamp(
+      (lastPosition.pageY / documentHeight) * 100,
+      0,
+      99.999,
+    );
+    const xBucket =
+      Math.floor(xPercent / MOVEMENT_GRID_SIZE) * MOVEMENT_GRID_SIZE;
+    const yBucket =
+      Math.floor(yPercent / MOVEMENT_GRID_SIZE) * MOVEMENT_GRID_SIZE;
+    const key = `${xBucket}:${yBucket}`;
+    movementBuckets.set(
+      key,
+      (movementBuckets.get(key) ?? 0) + MOVEMENT_SAMPLE_MS,
+    );
+  };
+
+  const onPointerMove = (event: PointerEvent) => {
+    lastPosition = { clientX: event.clientX, pageY: event.pageY };
+  };
+
+  const onVisibilityChange = () => {
+    if (document.visibilityState === "hidden") flushMovement();
+  };
+
+  const stopMovement = (flush: boolean) => {
+    if (flush) flushMovement();
+    if (movementSampleTimer !== null) {
+      window.clearInterval(movementSampleTimer);
+      movementSampleTimer = null;
+    }
+    if (movementFlushTimer !== null) {
+      window.clearInterval(movementFlushTimer);
+      movementFlushTimer = null;
+    }
+    document.removeEventListener("pointermove", onPointerMove);
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+    window.removeEventListener("pagehide", flushMovement);
+    lastPosition = null;
+  };
+
+  const syncMovementCapture = () => {
+    if (!movementEnabled()) {
+      stopMovement(false);
+      movementBuckets.clear();
+      return;
+    }
+    if (movementSampleTimer !== null) return;
+    bucketPageUrl = cleanUrl();
+    document.addEventListener("pointermove", onPointerMove, { passive: true });
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    window.addEventListener("pagehide", flushMovement, { passive: true });
+    movementSampleTimer = window.setInterval(sampleMovement, MOVEMENT_SAMPLE_MS);
+    movementFlushTimer = window.setInterval(flushMovement, MOVEMENT_FLUSH_MS);
+  };
+
+  const emitScroll = () => {
+    if (!active.some((assignment) => assignment.capture.scrolls !== false)) return;
+    const pct = scrollPercent();
+    const payload = {
+      path: location.pathname,
+      page_url: cleanUrl(),
+      scroll_percent: pct,
+      viewport_width: window.innerWidth,
+      viewport_height: window.innerHeight,
+      document_height: Math.max(document.body.scrollHeight, document.documentElement.scrollHeight),
+    };
+
+    for (const assignment of active) {
+      if (assignment.capture.scrolls === false) continue;
+      for (const bucket of SCROLL_BUCKETS) {
+        if (pct < bucket) continue;
+        const key = `${assignment.experimentId}:${assignment.variationId}:${cleanUrl()}:${bucket}`;
+        if (seenScrollBuckets.has(key)) continue;
+        seenScrollBuckets.add(key);
+        track(
+          "heatmap_scroll",
+          { ...payload, scroll_bucket: bucket },
+          assignment.experimentId,
+          assignment.variationId,
+        );
+      }
+    }
+  };
+
+  const onClick = (event: MouseEvent) => {
+    if (!active.some((assignment) => assignment.capture.clicks !== false)) return;
+    const now = Date.now();
+    if (now - lastClickAt < 100) return;
+    lastClickAt = now;
+
+    const target = event.target instanceof Element ? event.target : null;
+    if (!target) return;
+    const rect = target.getBoundingClientRect();
+    const pageX = event.pageX;
+    const pageY = event.pageY;
+    recentClicks = recentClicks
+      .filter((click) => now - click.t <= RAGE_CLICK_WINDOW_MS)
+      .slice(-(RAGE_CLICK_BUFFER_SIZE - 1));
+    recentClicks.push({ x: pageX, y: pageY, t: now });
+    const clusteredClicks = recentClicks.filter((click) =>
+      Math.hypot(click.x - pageX, click.y - pageY) <= RAGE_CLICK_RADIUS_PX,
+    );
+    const rage = clusteredClicks.length >= 3;
+    const payload = {
+      path: location.pathname,
+      page_url: cleanUrl(),
+      x: Math.round(pageX),
+      y: Math.round(pageY),
+      viewport_x: Math.round(event.clientX),
+      viewport_y: Math.round(event.clientY),
+      x_pct: Math.round((event.clientX / Math.max(1, window.innerWidth)) * 1000) / 10,
+      y_pct: Math.round((event.clientY / Math.max(1, window.innerHeight)) * 1000) / 10,
+      viewport_width: window.innerWidth,
+      viewport_height: window.innerHeight,
+      document_height: Math.max(document.body.scrollHeight, document.documentElement.scrollHeight),
+      selector: captureSelector(target),
+      element_tag: target.tagName.toLowerCase(),
+      element_text: safeElementText(target),
+      element_x: Math.round(rect.left + window.scrollX),
+      element_y: Math.round(rect.top + window.scrollY),
+      element_width: Math.round(rect.width),
+      element_height: Math.round(rect.height),
+      ...(rage ? { rage: 1 } : {}),
+    };
+
+    for (const assignment of active) {
+      if (assignment.capture.clicks === false) continue;
+      track("heatmap_click", payload, assignment.experimentId, assignment.variationId);
+    }
+  };
+
+  const onScroll = () => {
+    window.requestAnimationFrame(emitScroll);
+  };
+
+  document.addEventListener("click", onClick, { capture: true, passive: true });
+  window.addEventListener("scroll", onScroll, { passive: true });
+  window.addEventListener("resize", emitScroll, { passive: true });
+  window.setTimeout(emitScroll, 500);
+  syncMovementCapture();
+
+  return {
+    update(nextAssignments, nextExperiments) {
+      if (movementEnabled()) flushMovement();
+      active = resolveCaptureAssignments(nextAssignments, nextExperiments);
+      syncMovementCapture();
+      emitScroll();
+    },
+    stop() {
+      stopMovement(true);
+      document.removeEventListener("click", onClick, { capture: true });
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", emitScroll);
+    },
+  };
+}

package/src/hideflicker.ts

@@ -0,0 +1,21 @@
+/**
+ * Anti-flicker reveal module.
+ *
+ * The Worker's /s/<shopId>.js snippet injects
+ * <style id="drip-hide">…</style> as early as possible.
+ * In optimized mode this style is selector-scoped and only falls back
+ * to full-page hiding when scoped selectors are unavailable.
+ *
+ * This module provides revealAll() which the SDK calls once all mutations
+ * have been applied, making the page visible with the correct variant.
+ * A snippet safety timeout guarantees the page is always revealed even if
+ * the SDK encounters an error.
+ */
+
+const STYLE_ID = "drip-hide";
+
+/** Remove the anti-flicker style injected by the snippet */
+export function revealAll(): void {
+  const el = document.getElementById(STYLE_ID);
+  if (el) el.remove();
+}