@drip-apex/sdk 0.1.0

package/src/reassert-sentinel.ts

@@ -0,0 +1,191 @@
+import type { Mutation } from "./types";
+import { matchesOriginalInnerHtmlSnapshot, normalizeCssPropertyName } from "./mutate";
+import { registerMutedObserver, runMuted, unregisterMutedObserver } from "./observer-mute";
+
+type Entry = {
+  el: Element;
+  mutation: Mutation;
+  experimentId?: string;
+  variationId?: string;
+  appliedAt: number;
+  apply: (element: Element, mutation: Mutation) => void;
+  times: number[];
+  stopped: boolean;
+  appliedNodes?: ChildNode[];
+  appliedStyles?: Array<[string, string]>;
+};
+
+type TreatedRoot = {
+  entries: Entry[];
+  observer: MutationObserver;
+};
+
+// For html treatments, remember the nodes the treatment put in place and
+// attribute subtree changes: a framework hydration revert either replaces
+// them wholesale or restores the pre-treatment original content in place
+// (React/Vue reconciliation), while variant-owned widget activity (a
+// carousel adding slides, a countdown updating text, variation JS appending
+// state) evolves the applied content into something the original never had.
+// Wholesale replaces reassert at any time; in-place full restores reassert
+// within the hydration window; everything else is treated as variant-owned.
+// Partial in-place patches that do not restore the full original are not
+// separable from widget writes — sites that hit that corner integrate via
+// the drip:hydrated event / hold() API.
+const IN_PLACE_REVERT_WINDOW_MS = 10_000;
+
+function captureAppliedNodes(entry: Entry): void {
+  if (entry.mutation.action === "html") {
+    entry.appliedNodes = Array.from(entry.el.childNodes);
+  } else if (entry.mutation.action === "style" || entry.mutation.action === "setStyle") {
+    const style = (entry.el as HTMLElement).style;
+    entry.appliedStyles = Object.keys(entry.mutation.styles ?? {}).map((name) => [
+      name = normalizeCssPropertyName(name),
+      style.getPropertyValue(name),
+    ]);
+  }
+}
+
+function variantContentSurvives(entry: Entry, needsDeepCheck: boolean): boolean {
+  const surviving = (entry.appliedNodes ?? []).some(
+    (node) => node.isConnected && entry.el.contains(node),
+  );
+  if (!surviving) return false;
+  if (Date.now() - entry.appliedAt > IN_PLACE_REVERT_WINDOW_MS) return true;
+  if (!needsDeepCheck) return true;
+  // Any captured pre-state counts as a revert target: the server original,
+  // or — with stacked html treatments — an earlier treatment's content.
+  return !matchesOriginalInnerHtmlSnapshot(entry.el, entry.el.innerHTML);
+}
+
+const pending = new Set<Entry>();
+const deepChecks = new Set<Entry>();
+const roots = new Map<Element, TreatedRoot>();
+let frame: number | null = null;
+
+function perf(): Record<string, unknown> | null {
+  if (typeof window === "undefined") return null;
+  const target = window as Window & { __dripPerf?: Record<string, unknown> };
+  return target.__dripPerf = target.__dripPerf ?? {};
+}
+
+function matches(entry: Entry, record: MutationRecord): boolean {
+  if (!entry.el.isConnected) return false;
+  const action = entry.mutation.action;
+  if (action === "style" || action === "setStyle") {
+    if (record.type !== "attributes" || record.target !== entry.el || record.attributeName !== "style") return false;
+    const style = (entry.el as HTMLElement).style;
+    return entry.appliedStyles!.some(
+      ([name, value]) => style.getPropertyValue(name) !== value,
+    );
+  }
+  if (action === "attribute") {
+    if (record.type !== "attributes" || record.target !== entry.el || !record.attributeName) return false;
+    const expected = record.attributeName === entry.mutation.attribute?.name
+      ? entry.mutation.attribute.value
+      : entry.mutation.attributes?.[record.attributeName];
+    return expected !== undefined && entry.el.getAttribute(record.attributeName) !== expected;
+  }
+  if (action === "html") return true;
+  return record.type !== "attributes" && entry.el.textContent !== entry.mutation.text;
+}
+
+function markPending(entry: Entry): void {
+  pending.add(entry);
+  if (entry.mutation.action === "html") deepChecks.add(entry);
+}
+
+function schedule(): void {
+  if (frame !== null) return;
+  frame = requestAnimationFrame(() => {
+    frame = null;
+    const now = Date.now();
+    for (const entry of pending) {
+      if (entry.stopped) continue;
+      entry.times = entry.times.filter((at) => now - at < 10_000);
+      if (entry.times.length === 12) {
+        entry.stopped = true;
+        const metrics = perf();
+        if (metrics) metrics.reassert_loop_detected = true;
+        continue;
+      }
+      if (entry.mutation.action === "html" && variantContentSurvives(entry, deepChecks.has(entry))) {
+        // The change came from inside the still-applied treatment; erasing
+        // it would destroy legitimate widget state. Track the evolved
+        // subtree instead of reasserting the original static HTML.
+        captureAppliedNodes(entry);
+        continue;
+      }
+      entry.times.push(now);
+      runMuted(() => entry.apply(entry.el, entry.mutation));
+      captureAppliedNodes(entry);
+      const metrics = perf();
+      if (metrics) metrics.reapply_count = (Number(metrics.reapply_count) || 0) + 1;
+      if (entry.mutation.action === "html") {
+        document.dispatchEvent(new CustomEvent("drip:mutation-reapplied", { detail: {
+          experimentId: entry.experimentId,
+          variationId: entry.variationId,
+          selector: entry.mutation.selector,
+          action: entry.mutation.action,
+        } }));
+      }
+    }
+    pending.clear();
+    deepChecks.clear();
+  });
+}
+
+function observe(element: Element): void {
+  if (typeof MutationObserver === "undefined" || roots.has(element)) return;
+  for (const [treatedRoot, { observer }] of roots) {
+    if (treatedRoot.isConnected) continue;
+    observer.disconnect();
+    unregisterMutedObserver(observer);
+    roots.delete(treatedRoot);
+  }
+  const entries: Entry[] = [];
+  const onRecords: MutationCallback = (records) => {
+    for (const record of records) {
+      for (const entry of entries) {
+        if (!entry.stopped && matches(entry, record)) markPending(entry);
+      }
+    }
+    if (pending.size) schedule();
+  };
+  const observer = new MutationObserver(onRecords);
+  roots.set(element, { entries, observer });
+  registerMutedObserver(observer, onRecords);
+  observer.observe(element, { attributes: true, characterData: true, childList: true, subtree: true });
+}
+
+export function trackAppliedMutation(
+  element: Element,
+  mutation: Mutation,
+  context: { experimentId?: string; variationId?: string },
+  apply: (element: Element, mutation: Mutation) => void,
+): void {
+  if (mutation.action === "remove" || mutation.action === "insertBefore" || mutation.action === "insertAfter") return;
+  observe(element);
+  const entries = roots.get(element)?.entries;
+  if (!entries) return;
+  const existing = entries.find((entry) => entry.mutation === mutation);
+  if (existing) {
+    Object.assign(existing, context, { appliedAt: Date.now(), apply });
+    captureAppliedNodes(existing);
+  } else {
+    const entry: Entry = { el: element, mutation, ...context, appliedAt: Date.now(), apply, times: [], stopped: false };
+    captureAppliedNodes(entry);
+    entries.push(entry);
+  }
+}
+
+export function resetReassertSentinel(): void {
+  if (frame !== null) cancelAnimationFrame(frame);
+  frame = null;
+  pending.clear();
+  deepChecks.clear();
+  for (const { observer } of roots.values()) {
+    observer.disconnect();
+    unregisterMutedObserver(observer);
+  }
+  roots.clear();
+}

package/src/router.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { observeRouteChanges } from "./router";
+
+describe("route observer", () => {
+  const originalWindow = (globalThis as any).window;
+  const originalLocation = (globalThis as any).location;
+  const originalHistory = (globalThis as any).history;
+  let listeners: Map<string, Set<() => void>>;
+
+  function setLocation(nextHref: string): void {
+    const parsed = new URL(nextHref);
+    (globalThis as any).location = {
+      hash: parsed.hash,
+      href: parsed.href,
+      origin: parsed.origin,
+      pathname: parsed.pathname,
+      search: parsed.search,
+    };
+  }
+
+  function dispatch(type: string): void {
+    for (const listener of listeners.get(type) ?? []) {
+      listener();
+    }
+  }
+
+  beforeEach(() => {
+    listeners = new Map();
+    setLocation("https://example.test/products/a#control");
+    (globalThis as any).history = {
+      pushState() {},
+      replaceState() {},
+    };
+    (globalThis as any).window = {
+      addEventListener(type: string, listener: () => void) {
+        const set = listeners.get(type) ?? new Set<() => void>();
+        set.add(listener);
+        listeners.set(type, set);
+      },
+      removeEventListener(type: string, listener: () => void) {
+        listeners.get(type)?.delete(listener);
+      },
+    };
+  });
+
+  afterEach(() => {
+    (globalThis as any).window = originalWindow;
+    (globalThis as any).location = originalLocation;
+    (globalThis as any).history = originalHistory;
+  });
+
+  it("observes pure hashchange events when history does not emit popstate", () => {
+    const events: Array<{
+      previousUrl: string;
+      nextUrl: string;
+      reason: string;
+    }> = [];
+    const stop = observeRouteChanges("history", (event) => {
+      events.push(event);
+    });
+
+    setLocation("https://example.test/products/a#variant");
+    dispatch("hashchange");
+
+    expect(events).toEqual([
+      {
+        previousUrl: "https://example.test/products/a#control",
+        nextUrl: "https://example.test/products/a#variant",
+        reason: "hashchange",
+      },
+    ]);
+
+    stop();
+    setLocation("https://example.test/products/a#details");
+    dispatch("hashchange");
+    expect(events).toHaveLength(1);
+  });
+});

package/src/router.ts

@@ -0,0 +1,92 @@
+import { RouterMode } from "./types";
+
+export type RouteChangeEvent = {
+  previousUrl: string;
+  nextUrl: string;
+  reason: "pushState" | "replaceState" | "popstate" | "hashchange" | "navigation";
+};
+
+type RouteObserver = (event: RouteChangeEvent) => void;
+
+function notifyIfChanged(
+  lastUrlRef: { value: string },
+  reason: RouteChangeEvent["reason"],
+  observer: RouteObserver,
+): void {
+  const next = location.href;
+  if (next === lastUrlRef.value) return;
+  const previous = lastUrlRef.value;
+  lastUrlRef.value = next;
+  observer({ previousUrl: previous, nextUrl: next, reason });
+}
+
+function observeHistoryChanges(observer: RouteObserver, lastUrlRef: { value: string }): () => void {
+  const wrap = (method: "pushState" | "replaceState") => {
+    const original = history[method];
+    history[method] = function (...args: Parameters<History["pushState"]>) {
+      const ret = original.apply(this, args);
+      notifyIfChanged(lastUrlRef, method, observer);
+      return ret;
+    };
+    return () => {
+      history[method] = original;
+    };
+  };
+
+  const restorePush = wrap("pushState");
+  const restoreReplace = wrap("replaceState");
+  const popHandler = () => notifyIfChanged(lastUrlRef, "popstate", observer);
+  const hashHandler = () => notifyIfChanged(lastUrlRef, "hashchange", observer);
+
+  window.addEventListener("popstate", popHandler);
+  window.addEventListener("hashchange", hashHandler);
+
+  return () => {
+    restorePush();
+    restoreReplace();
+    window.removeEventListener("popstate", popHandler);
+    window.removeEventListener("hashchange", hashHandler);
+  };
+}
+
+function observeNavigationApi(observer: RouteObserver, lastUrlRef: { value: string }): () => void {
+  const w = globalThis as Record<string, unknown>;
+  const navigation = w.navigation as {
+    addEventListener?: (type: string, listener: () => void) => void;
+    removeEventListener?: (type: string, listener: () => void) => void;
+  } | undefined;
+  if (!navigation || typeof navigation.addEventListener !== "function") {
+    return () => {};
+  }
+
+  const listener = () => notifyIfChanged(lastUrlRef, "navigation", observer);
+  navigation.addEventListener("navigate", listener);
+
+  return () => {
+    if (typeof navigation.removeEventListener === "function") {
+      navigation.removeEventListener("navigate", listener);
+    }
+  };
+}
+
+export function observeRouteChanges(
+  mode: RouterMode,
+  observer: RouteObserver,
+): () => void {
+  if (mode === "none") return () => {};
+
+  const lastUrlRef = { value: location.href };
+  const cleanups: Array<() => void> = [];
+
+  if (mode === "navigation") {
+    cleanups.push(observeNavigationApi(observer, lastUrlRef));
+  }
+
+  if (mode === "history" || mode === "navigation") {
+    cleanups.push(observeHistoryChanges(observer, lastUrlRef));
+  }
+
+  return () => {
+    for (const cleanup of cleanups) cleanup();
+  };
+}

package/src/runtime-tools.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from "vitest";
+import { createApexRuntimeTools } from "./runtime-tools";
+
+describe("createApexRuntimeTools", () => {
+  it("runs domLoaded immediately after the document is ready", () => {
+    const callback = vi.fn();
+    const tools = createApexRuntimeTools({
+      document: { readyState: "complete" } as unknown as Document,
+    });
+
+    const cleanup = tools.domLoaded(callback);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(cleanup).not.toThrow();
+  });
+
+  it("watches dataLayer entries by object or key-value matchers", () => {
+    const windowLike = {
+      dataLayer: [{ event: "page_view", page_type: "pdp" }],
+      setTimeout,
+      clearTimeout,
+    } as unknown as Window & typeof globalThis;
+    const tools = createApexRuntimeTools({ window: windowLike });
+    const seen: unknown[] = [];
+
+    const cleanup = tools.waitForDataLayer(
+      { event: "add_to_cart" },
+      (entry) => seen.push(entry),
+      { once: false },
+    );
+    windowLike.dataLayer.push({ event: "add_to_cart", sku: "sku-1" });
+    windowLike.dataLayer.push({ event: "checkout_started" });
+    windowLike.dataLayer.push({ event: "add_to_cart", sku: "sku-2" });
+    cleanup();
+
+    expect(seen).toEqual([
+      { event: "add_to_cart", sku: "sku-1" },
+      { event: "add_to_cart", sku: "sku-2" },
+    ]);
+  });
+
+  it("normalizes gtag Arguments entries before matching and callback delivery", () => {
+    const windowLike = {
+      dataLayer: [],
+      setTimeout,
+      clearTimeout,
+    } as unknown as Window & typeof globalThis;
+    const tools = createApexRuntimeTools({ window: windowLike });
+    const seen: unknown[] = [];
+
+    tools.waitForDataLayer(
+      { event: "add_to_cart" },
+      (entry) => seen.push(entry),
+      { once: false },
+    );
+    (function (..._args: unknown[]) {
+      windowLike.dataLayer.push(arguments);
+    })("event", "add_to_cart", { currency: "EUR", value: 495 });
+    windowLike.dataLayer.push({ 0: "consent", 1: "update", 2: { event: "add_to_cart" } });
+
+    expect(seen).toEqual([{ currency: "EUR", value: 495, event: "add_to_cart" }]);
+    expect(Object.getPrototypeOf(seen[0])).toBe(Object.prototype);
+  });
+
+  it("keeps arbitrary raw-object dataLayer matching semantics", () => {
+    const windowLike = {
+      dataLayer: [{ page_type: "pdp", sku: "sku-1" }],
+      setTimeout,
+      clearTimeout,
+    } as unknown as Window & typeof globalThis;
+    const tools = createApexRuntimeTools({ window: windowLike });
+    const seen: unknown[] = [];
+
+    tools.waitForDataLayer({ page_type: "pdp" }, (entry) => seen.push(entry));
+
+    expect(seen).toEqual([{ page_type: "pdp", sku: "sku-1" }]);
+  });
+
+  it("exposes track, goals, signals, reInit, get, and redirect delegates", () => {
+    const track = vi.fn();
+    const trackGoal = vi.fn();
+    const signal = vi.fn();
+    const reInit = vi.fn(() => ["assignment"]);
+    const get = vi.fn((key: string) => (key === "experiments" ? [] : null));
+    const assign = vi.fn();
+    const tools = createApexRuntimeTools({
+      track,
+      trackGoal,
+      signal,
+      reInit,
+      get,
+      location: {
+        href: "https://store.test/products/a",
+        assign,
+      } as unknown as Location,
+    });
+
+    tools.track("custom", { ok: true });
+    tools.trackGoal("goal-1", { value: 1 });
+    tools.signal("visitor.vip", true, 7);
+    expect(tools.reInit(true)).toEqual(["assignment"]);
+    expect(tools.get("experiments")).toEqual([]);
+    tools.redirect("/cart");
+
+    expect(track).toHaveBeenCalledWith("custom", { ok: true });
+    expect(trackGoal).toHaveBeenCalledWith("goal-1", { value: 1 });
+    expect(signal).toHaveBeenCalledWith("visitor.vip", true, 7);
+    expect(reInit).toHaveBeenCalledWith(true);
+    expect(get).toHaveBeenCalledWith("experiments");
+    expect(assign).toHaveBeenCalledWith("https://store.test/cart");
+  });
+});