@drip-apex/sdk 0.1.0

package/src/mutate.ts

@@ -0,0 +1,469 @@
+import { Mutation, MutationAction } from "./types";
+import { sanitizeHtml } from "./sanitize";
+import { runMuted } from "./observer-mute";
+import { resetReassertSentinel } from "./reassert-sentinel";
+import { isStrictJsPolicy } from "./js";
+
+export type ApplyOptions = {
+  root?: Document | HTMLElement;
+  onApplied?: (mutation: Mutation, element: Element, index: number) => void;
+  onMiss?: (mutation: Mutation, index: number) => void;
+};
+
+const INSERT_ATTR = "data-drip-inserted";
+
+type AttributeSnapshot = {
+  kind: "attribute";
+  element: Element;
+  values: Array<{ name: string; value: string | null }>;
+};
+
+type ContentSnapshot = {
+  kind: "content";
+  element: Element;
+  property: "innerHTML" | "textContent";
+  value: string | null;
+};
+
+type StyleSnapshot = {
+  kind: "style";
+  element: HTMLElement;
+  values: Array<{ name: string; value: string; priority: string }>;
+};
+
+type RemoveSnapshot = {
+  kind: "remove";
+  element: Element;
+  parent: Node | null;
+  nextSibling: Node | null;
+};
+
+type InsertSnapshot = {
+  kind: "insert";
+  nodes: Node[];
+};
+
+type MutationSnapshot =
+  | AttributeSnapshot
+  | ContentSnapshot
+  | StyleSnapshot
+  | RemoveSnapshot
+  | InsertSnapshot;
+
+const mutationSnapshots: MutationSnapshot[] = [];
+
+const URL_ATTRIBUTES = new Set(["href", "src", "action", "formaction", "xlink:href"]);
+const SAFE_DATA_URL_MEDIA_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/avif",
+]);
+
+export function isSafeMutationAttribute(name: string, value: string | null): boolean {
+  const normalizedName = name.trim().toLowerCase();
+  if (!normalizedName || normalizedName.startsWith("on") || normalizedName === "srcdoc") {
+    return false;
+  }
+  if (value === null || !URL_ATTRIBUTES.has(normalizedName)) return true;
+  const normalizedValue = value.replace(/[\u0000-\u0020]+/g, "").toLowerCase();
+  if (normalizedValue.startsWith("javascript:")) return false;
+  if (!normalizedValue.startsWith("data:")) return true;
+  const mediaType = normalizedValue.slice(5).split(/[;,]/, 1)[0];
+  return SAFE_DATA_URL_MEDIA_TYPES.has(mediaType);
+}
+
+function sanitizeMutationHtml(html: string): string {
+  const sanitized = sanitizeHtml(html);
+  if (!isStrictJsPolicy()) return sanitized;
+  const template = document.createElement("template");
+  template.innerHTML = sanitized;
+  for (const element of Array.from(template.content.querySelectorAll("*"))) {
+    for (const attribute of Array.from(element.attributes)) {
+      if (!isSafeMutationAttribute(attribute.name, attribute.value)) {
+        element.removeAttribute(attribute.name);
+      }
+    }
+  }
+  return template.innerHTML;
+}
+
+export function normalizeCssPropertyName(name: string): string {
+  // Prefer CSS syntax (kebab-case) because it works with:
+  // - HTMLElement.style.setProperty(...)
+  // - inline style rewriting at the edge worker
+  // But accept common JS-style camelCase keys for developer ergonomics.
+  if (!name) return name;
+  if (name.startsWith("--")) return name; // custom properties
+  if (name.includes("-")) return name; // already kebab-case
+
+  let out = name.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+  // Special-case msTransform -> -ms-transform
+  if (out.startsWith("ms-")) out = "-" + out;
+  return out;
+}
+
+export function getMutationKey(mutation: Mutation, index: number): string {
+  return (
+    mutation.action +
+    ":" +
+    index +
+    ":" +
+    (mutation.selector || "") +
+    ":" +
+    (mutation.html || mutation.text || "")
+  );
+}
+
+export function isInsertAction(action: MutationAction): boolean {
+  return action === "insertBefore" || action === "insertAfter";
+}
+
+function snapshotMutation(
+  mutation: Mutation,
+  element: Element,
+  snapshots: MutationSnapshot[] = mutationSnapshots,
+): void {
+  switch (mutation.action) {
+    case "html":
+      snapshots.push({
+        kind: "content",
+        element,
+        property: "innerHTML",
+        value: element.innerHTML,
+      });
+      break;
+    case "text":
+    case "setText":
+      snapshots.push({
+        kind: "content",
+        element,
+        property: "textContent",
+        value: element.textContent,
+      });
+      break;
+    case "attribute": {
+      const names = new Set<string>();
+      if (mutation.attribute) names.add(mutation.attribute.name);
+      if (mutation.attributes) {
+        Object.keys(mutation.attributes).forEach((name) => names.add(name));
+      }
+      snapshots.push({
+        kind: "attribute",
+        element,
+        values: Array.from(names).map((name) => ({
+          name,
+          value: element.getAttribute(name),
+        })),
+      });
+      break;
+    }
+    case "style":
+    case "setStyle": {
+      const style = (element as HTMLElement).style;
+      const names = Object.keys(mutation.styles ?? {}).map(normalizeCssPropertyName);
+      snapshots.push({
+        kind: "style",
+        element: element as HTMLElement,
+        values: names.map((name) => ({
+          name,
+          value: style.getPropertyValue(name),
+          priority: style.getPropertyPriority(name),
+        })),
+      });
+      break;
+    }
+    case "remove":
+      snapshots.push({
+        kind: "remove",
+        element,
+        parent: element.parentNode,
+        nextSibling: element.nextSibling,
+      });
+      break;
+  }
+}
+
+function restoreSnapshot(snapshot: MutationSnapshot): void {
+  switch (snapshot.kind) {
+    case "content":
+      if (snapshot.property === "innerHTML") {
+        snapshot.element.innerHTML = snapshot.value ?? "";
+      } else {
+        snapshot.element.textContent = snapshot.value;
+      }
+      break;
+    case "attribute":
+      for (const { name, value } of snapshot.values) {
+        if (value === null) snapshot.element.removeAttribute(name);
+        else snapshot.element.setAttribute(name, value);
+      }
+      break;
+    case "style":
+      for (const { name, value, priority } of snapshot.values) {
+        if (value) snapshot.element.style.setProperty(name, value, priority);
+        else snapshot.element.style.removeProperty(name);
+      }
+      break;
+    case "remove":
+      if (!snapshot.parent || snapshot.element.parentNode) return;
+      try {
+        snapshot.parent.insertBefore(snapshot.element, snapshot.nextSibling);
+      } catch {
+        snapshot.parent.appendChild(snapshot.element);
+      }
+      break;
+    case "insert":
+      for (const node of snapshot.nodes) node.parentNode?.removeChild(node);
+      break;
+  }
+}
+
+export function applyToElement(mutation: Mutation, element: Element): void {
+  switch (mutation.action) {
+    case "html":
+      if (typeof mutation.html === "string") element.innerHTML = sanitizeMutationHtml(mutation.html);
+      break;
+    case "text":
+    case "setText":
+      if (typeof mutation.text === "string") element.textContent = mutation.text;
+      break;
+    case "attribute":
+      if (mutation.attribute) {
+        if (!isStrictJsPolicy() ||
+            isSafeMutationAttribute(mutation.attribute.name, mutation.attribute.value)) {
+          if (mutation.attribute.value === null) {
+            element.removeAttribute(mutation.attribute.name);
+          } else {
+            element.setAttribute(mutation.attribute.name, mutation.attribute.value);
+          }
+        }
+      }
+      if (mutation.attributes) {
+        for (const [name, value] of Object.entries(mutation.attributes)) {
+          if (isStrictJsPolicy() && !isSafeMutationAttribute(name, value)) continue;
+          if (value === null) element.removeAttribute(name);
+          else element.setAttribute(name, value);
+        }
+      }
+      break;
+    case "style":
+    case "setStyle":
+      if (mutation.styles) {
+        for (const [name, value] of Object.entries(mutation.styles)) {
+          (element as HTMLElement).style.setProperty(
+            normalizeCssPropertyName(name),
+            value,
+          );
+        }
+      }
+      break;
+    case "remove":
+      element.remove();
+      break;
+    case "insertBefore":
+      if (typeof mutation.html === "string") {
+        element.insertAdjacentHTML("beforebegin", sanitizeMutationHtml(mutation.html));
+      }
+      break;
+    case "insertAfter":
+      if (typeof mutation.html === "string") {
+        element.insertAdjacentHTML("afterend", sanitizeMutationHtml(mutation.html));
+      }
+      break;
+  }
+}
+
+export function isInsertDuplicate(element: Element, key: string): boolean {
+  const parent = element.parentElement;
+  if (!parent) return false;
+  return Array.from(parent.querySelectorAll("[" + INSERT_ATTR + "]")).some(
+    (candidate) => candidate.getAttribute(INSERT_ATTR) === key,
+  );
+}
+
+export function markInserted(el: Element, key: string): void {
+  (el as HTMLElement).setAttribute(INSERT_ATTR, key);
+}
+
+function applyTrackedMutationWithSnapshots(
+  mutation: Mutation,
+  element: Element,
+  snapshots: MutationSnapshot[],
+  key?: string,
+): Element | null {
+  return runMuted(() => {
+    if (isInsertAction(mutation.action)) {
+      const parent = element.parentNode;
+      if (!parent || typeof mutation.html !== "string") return null;
+      const previousSibling = element.previousSibling;
+      const nextSibling = element.nextSibling;
+      applyToElement(mutation, element);
+      const insertedNodes: Node[] = [];
+      let current = mutation.action === "insertBefore"
+        ? (previousSibling ? previousSibling.nextSibling : parent.firstChild)
+        : element.nextSibling;
+      const boundary = mutation.action === "insertBefore" ? element : nextSibling;
+      while (current && current !== boundary) {
+        insertedNodes.push(current);
+        current = current.nextSibling;
+      }
+      const insertedElements = insertedNodes.filter(
+        (node): node is Element => node instanceof Element,
+      );
+      if (key) insertedElements.forEach((inserted) => markInserted(inserted, key));
+      if (insertedNodes.length) snapshots.push({ kind: "insert", nodes: insertedNodes });
+      return insertedElements[0] ?? null;
+    }
+    snapshotMutation(mutation, element, snapshots);
+    applyToElement(mutation, element);
+    return null;
+  });
+}
+
+export function applyTrackedMutation(mutation: Mutation, element: Element, key?: string): Element | null {
+  return applyTrackedMutationWithSnapshots(mutation, element, mutationSnapshots, key);
+}
+
+// Every pre-apply innerHTML captured for the element's html mutations. The
+// reassert sentinel uses these to attribute subtree changes: a framework
+// hydration revert restores one of these pre-states (the server original,
+// or — for stacked treatments — an earlier treatment's content), while
+// variant-owned widget activity produces content none of them ever had.
+export function matchesOriginalInnerHtmlSnapshot(element: Element, current: string): boolean {
+  for (const snapshot of mutationSnapshots) {
+    if (
+      snapshot.kind === "content" &&
+      snapshot.element === element &&
+      snapshot.property === "innerHTML" &&
+      typeof snapshot.value === "string"
+    ) {
+      if (snapshot.value === current) return true;
+    }
+  }
+  return false;
+}
+
+function applyMutationsWithSnapshots(
+  mutations: Mutation[],
+  options: ApplyOptions,
+  snapshots: MutationSnapshot[],
+): void {
+  const root = options.root || document;
+  mutations.forEach((mutation, index) => {
+    let elements: NodeListOf<Element>;
+    try {
+      elements = root.querySelectorAll(mutation.selector);
+    } catch {
+      options.onMiss?.(mutation, index);
+      return;
+    }
+    if (elements.length === 0) {
+      options.onMiss?.(mutation, index);
+      return;
+    }
+    elements.forEach((element) => {
+      const key = getMutationKey(mutation, index);
+      if (isInsertAction(mutation.action)) {
+        if (isInsertDuplicate(element, key)) return;
+        applyTrackedMutationWithSnapshots(mutation, element, snapshots, key);
+        options.onApplied?.(mutation, element, index);
+        return;
+      }
+      applyTrackedMutationWithSnapshots(mutation, element, snapshots, key);
+      options.onApplied?.(mutation, element, index);
+    });
+  });
+}
+
+export function applyMutations(mutations: Mutation[], options: ApplyOptions = {}): void {
+  applyMutationsWithSnapshots(mutations, options, mutationSnapshots);
+}
+
+export function reassertNonStructuralMutations(mutations: Mutation[], options: ApplyOptions = {}): void {
+  const root = options.root || document;
+  mutations.forEach((mutation, index) => {
+    if (isInsertAction(mutation.action) || mutation.action === "remove") return;
+    const elements = root.querySelectorAll(mutation.selector);
+    elements.forEach((element) => {
+      runMuted(() => applyToElement(mutation, element));
+      options.onApplied?.(mutation, element, index);
+    });
+  });
+}
+
+export function resetAppliedMutations(): void {
+  resetReassertSentinel();
+  runMuted(() => {
+    for (let i = mutationSnapshots.length - 1; i >= 0; i -= 1) {
+      restoreSnapshot(mutationSnapshots[i]);
+    }
+  });
+  mutationSnapshots.length = 0;
+}
+
+export type MutationApplicationContext = {
+  apply: (mutations: Mutation[], options?: ApplyOptions) => void;
+  rollback: () => void;
+  readonly snapshotCount: number;
+};
+
+/**
+ * Owns only the DOM snapshots created through this context. Rolling it back
+ * restores the state that existed immediately before its mutations, without
+ * touching shopper assignment mutations tracked by the main SDK runtime.
+ */
+export function createMutationApplicationContext(): MutationApplicationContext {
+  const snapshots: MutationSnapshot[] = [];
+  return {
+    apply(mutations, options = {}) {
+      applyMutationsWithSnapshots(mutations, options, snapshots);
+    },
+    rollback() {
+      runMuted(() => {
+        for (let i = snapshots.length - 1; i >= 0; i -= 1) {
+          restoreSnapshot(snapshots[i]);
+        }
+      });
+      snapshots.length = 0;
+    },
+    get snapshotCount() {
+      return snapshots.length;
+    },
+  };
+}
+
+/** @internal — exposed for unit testing only. Tree-shaken from production build. */
+export const __test = {
+  normalizeCssPropertyName,
+};
+
+export function observeSpaNavigation(onChange: () => void): () => void {
+  let lastUrl = location.href;
+  const notify = () => {
+    if (lastUrl !== location.href) {
+      lastUrl = location.href;
+      onChange();
+    }
+  };
+  const wrap = (method: "pushState" | "replaceState") => {
+    const original = history[method];
+    history[method] = function (...args: Parameters<History["pushState"]>) {
+      const ret = original.apply(this, args);
+      notify();
+      return ret;
+    };
+    return () => {
+      history[method] = original;
+    };
+  };
+  const restorePush = wrap("pushState");
+  const restoreReplace = wrap("replaceState");
+  window.addEventListener("popstate", notify);
+  return () => {
+    restorePush();
+    restoreReplace();
+    window.removeEventListener("popstate", notify);
+  };
+}

package/src/observer-mute.test.ts

@@ -0,0 +1,88 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { registerMutedObserver, runMuted, unregisterMutedObserver } from "./observer-mute";
+
+async function deliverMutations(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe("observer mute", () => {
+  const registered: MutationObserver[] = [];
+
+  afterEach(() => {
+    registered.forEach(unregisterMutedObserver);
+    registered.length = 0;
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("discards records produced by muted writes", async () => {
+    const callback = vi.fn();
+    const observer = new MutationObserver(callback);
+    registered.push(observer);
+    registerMutedObserver(observer);
+    observer.observe(document.body, { childList: true, subtree: true });
+
+    runMuted(() => {
+      document.body.appendChild(document.createElement("div"));
+    });
+    await deliverMutations();
+
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("drains only around the outermost nested muted block", () => {
+    const observer = new MutationObserver(() => {});
+    registered.push(observer);
+    registerMutedObserver(observer);
+    const takeRecords = vi.spyOn(observer, "takeRecords");
+
+    runMuted(() => {
+      // One pre-drain at outer entry (delivering pre-existing records);
+      // nested blocks add none.
+      expect(takeRecords).toHaveBeenCalledTimes(1);
+      runMuted(() => {
+        document.body.textContent = "nested";
+      });
+      expect(takeRecords).toHaveBeenCalledTimes(1);
+    });
+
+    expect(takeRecords).toHaveBeenCalledTimes(2);
+  });
+
+  it("delivers records queued before a muted write instead of discarding them", () => {
+    const callback = vi.fn();
+    const observer = new MutationObserver(callback);
+    registered.push(observer);
+    registerMutedObserver(observer, callback);
+    observer.observe(document.body, { childList: true });
+
+    // An external storefront change lands in the same task, before the SDK
+    // write; its record is still queued when the muted write begins.
+    document.body.appendChild(document.createElement("p"));
+    runMuted(() => {
+      document.body.appendChild(document.createElement("div"));
+    });
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    const records = callback.mock.calls[0][0] as MutationRecord[];
+    expect(records).toHaveLength(1);
+    expect((records[0].addedNodes[0] as Element).tagName).toBe("P");
+  });
+
+  it("does not drain unregistered observers", async () => {
+    const callback = vi.fn();
+    const observer = new MutationObserver(callback);
+    observer.observe(document.body, { childList: true });
+
+    runMuted(() => {
+      document.body.appendChild(document.createElement("span"));
+    });
+    await deliverMutations();
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    observer.disconnect();
+  });
+});
+

package/src/observer-mute.ts

@@ -0,0 +1,45 @@
+const observers = new Map<MutationObserver, MutationCallback | undefined>();
+let muteDepth = 0;
+
+export function registerMutedObserver(
+  observer: MutationObserver,
+  callback?: MutationCallback,
+): void {
+  observers.set(observer, callback);
+}
+
+export function unregisterMutedObserver(observer: MutationObserver): void {
+  observers.delete(observer);
+}
+
+export function runMuted<T>(fn: () => T): T {
+  if (muteDepth === 0) {
+    // Deliver records queued BEFORE the muted write to their handlers: a
+    // real storefront change in the same task must not be discarded along
+    // with the SDK's own write records when the queue drains below.
+    for (const [observer, callback] of observers) {
+      try {
+        const pending = observer.takeRecords();
+        if (pending.length && callback) callback(pending, observer);
+      } catch {
+        // A disconnected or test-double observer must not block SDK writes.
+      }
+    }
+  }
+  muteDepth += 1;
+  try {
+    return fn();
+  } finally {
+    muteDepth -= 1;
+    if (muteDepth === 0) {
+      for (const observer of observers.keys()) {
+        try {
+          observer.takeRecords();
+        } catch {
+          // A disconnected or test-double observer must not block SDK writes.
+        }
+      }
+    }
+  }
+}
+

package/src/page-trigger.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { __test } from "./index";
+import { clearRuntimeSignal, getSignals } from "./signals";
+import type { PageTargetingRule } from "./types";
+
+const signal = "page.trigger.pdp_overlay";
+
+function installTrigger(triggerJs: string) {
+  const onChange = vi.fn();
+  const cleanup = __test.installPageTriggerRule({
+    id: "page_1",
+    includeRules: [{ type: "simple", pattern: "/products/*", include: true }],
+    trigger: {
+      mode: "manual-callback",
+      apiName: "pdp_overlay",
+      signal,
+      triggerJs,
+    },
+  } satisfies PageTargetingRule, onChange);
+  return { cleanup, onChange };
+}
+
+describe("Page trigger JS", () => {
+  afterEach(() => {
+    clearRuntimeSignal(signal);
+    clearRuntimeSignal("page.trigger.segment_123_pdp_overlay");
+    vi.unstubAllGlobals();
+  });
+
+  it("supports activate(), activate(true), and activate(false)", () => {
+    let trigger = installTrigger("activate();");
+    expect(getSignals()[signal]).toBe(true);
+    expect(trigger.onChange).toHaveBeenCalledTimes(1);
+    trigger.cleanup();
+
+    trigger = installTrigger("activate(true);");
+    expect(getSignals()[signal]).toBe(true);
+    expect(trigger.onChange).toHaveBeenCalledTimes(1);
+    trigger.cleanup();
+
+    trigger = installTrigger("activate(false);");
+    expect(getSignals()[signal]).toBe(false);
+    expect(trigger.onChange).toHaveBeenCalledTimes(1);
+    trigger.cleanup();
+  });
+
+  it("normalizes public API names like server-generated Page trigger signals", () => {
+    expect(__test.normalizePageApiName("123 PDP Overlay")).toBe("segment_123_pdp_overlay");
+    expect(__test.normalizePageApiName("PDP Overlay")).toBe("pdp_overlay");
+    expect(__test.normalizePageApiName("   ")).toBe("");
+    expect(__test.normalizePageApiName(null)).toBe("");
+  });
+
+  it("sets the Page trigger signal and dispatches the public API change event", () => {
+    const dispatchEvent = vi.fn();
+    vi.stubGlobal("document", { dispatchEvent });
+    vi.stubGlobal("CustomEvent", class {
+      type: string;
+      detail: unknown;
+
+      constructor(type: string, init?: { detail?: unknown }) {
+        this.type = type;
+        this.detail = init?.detail;
+      }
+    });
+
+    __test.triggerPage("123 PDP Overlay");
+    expect(getSignals()["page.trigger.segment_123_pdp_overlay"]).toBe(true);
+    expect(dispatchEvent).toHaveBeenCalledWith(expect.objectContaining({
+      type: "drip:signals-changed",
+      detail: {
+        source: "page_api",
+        apiName: "segment_123_pdp_overlay",
+        active: true,
+      },
+    }));
+
+    __test.triggerPage("123 PDP Overlay", false);
+    expect(getSignals()["page.trigger.segment_123_pdp_overlay"]).toBe(false);
+
+    __test.triggerPage("   ");
+    expect(getSignals()["page.trigger."]).toBeUndefined();
+  });
+});