@drip-apex/sdk 0.1.0

package/src/devtools.ts

@@ -0,0 +1,582 @@
+/**
+ * Drip SDK Devtools Overlay
+ *
+ * Enable via: `?drip_devtools=1`, `?drip_debug=1`, or `localStorage.drip_devtools=1`
+ *
+ * Renders a draggable panel (shadow DOM) showing:
+ * - Active experiments and assignments
+ * - Targeting evaluation results
+ * - Event log (assignments, mutations, goals, tracking)
+ * - Force variation controls
+ * - Performance timings
+ */
+
+import type { ActivationGateDiagnostic, Assignment, Experiment, SdkDiagnostics } from "./types";
+
+// ---------------------------------------------------------------------------
+// Event log
+// ---------------------------------------------------------------------------
+
+export interface DevtoolsEvent {
+  ts: number;
+  type: string;
+  label: string;
+  detail?: Record<string, unknown>;
+}
+
+const eventLog: DevtoolsEvent[] = [];
+const MAX_LOG_ENTRIES = 200;
+const eventListeners = new Set<(event: DevtoolsEvent) => void>();
+
+export function logDevtoolsEvent(
+  type: string,
+  label: string,
+  detail?: Record<string, unknown>,
+): void {
+  const event = { ts: Date.now(), type, label, detail };
+  eventLog.push(event);
+  if (eventLog.length > MAX_LOG_ENTRIES) eventLog.shift();
+  for (const listener of eventListeners) {
+    try {
+      listener(event);
+    } catch {
+      // Devtools listeners must not affect SDK runtime behavior.
+    }
+  }
+  // Notify mounted devtools
+  if (panelInstance) panelInstance.refresh();
+}
+
+export function subscribeDevtoolsEvents(listener: (event: DevtoolsEvent) => void): () => void {
+  eventListeners.add(listener);
+  return () => {
+    eventListeners.delete(listener);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+export function isDevtoolsEnabled(): boolean {
+  try {
+    if (typeof URLSearchParams !== "undefined") {
+      const params = new URLSearchParams(location.search);
+      if (params.get("drip_devtools") === "1") return true;
+      if (params.get("drip_debug") === "1") return true;
+      if (params.get("apex_debug") === "1") return true;
+    }
+    if (typeof localStorage !== "undefined") {
+      return localStorage.getItem("drip_devtools") === "1";
+    }
+  } catch {
+    // ignore
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Panel instance
+// ---------------------------------------------------------------------------
+
+let panelInstance: DevtoolsPanel | null = null;
+
+interface MountOptions {
+  experiments: Experiment[];
+  assignments: Assignment[];
+  diagnostics?: SdkDiagnostics | null;
+  forceMap: Record<string, string> | null;
+  onForceVariation: (experimentId: string, variationId: string) => void;
+}
+
+export function mountDevtools(opts: MountOptions): void {
+  if (panelInstance) {
+    panelInstance.update(opts);
+    return;
+  }
+  panelInstance = new DevtoolsPanel(opts);
+}
+
+export function unmountDevtools(): void {
+  if (panelInstance) {
+    panelInstance.destroy();
+    panelInstance = null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Panel implementation
+// ---------------------------------------------------------------------------
+
+class DevtoolsPanel {
+  private host: HTMLElement;
+  private shadow: ShadowRoot;
+  private opts: MountOptions;
+  private collapsed = false;
+  private activeTab: "sequence" | "assignments" | "log" | "force" = "sequence";
+  private dragState: { startX: number; startY: number; offsetX: number; offsetY: number } | null = null;
+
+  constructor(opts: MountOptions) {
+    this.opts = opts;
+    this.host = document.createElement("div");
+    this.host.id = "drip-devtools-host";
+    this.shadow = this.host.attachShadow({ mode: "closed" });
+    document.body.appendChild(this.host);
+    this.render();
+    this.attachDrag();
+  }
+
+  update(opts: MountOptions): void {
+    this.opts = opts;
+    this.render();
+  }
+
+  refresh(): void {
+    this.render();
+  }
+
+  destroy(): void {
+    this.host.remove();
+  }
+
+  private render(): void {
+    const { experiments, assignments, diagnostics, forceMap } = this.opts;
+
+    this.shadow.innerHTML = `
+      <style>${PANEL_CSS}</style>
+      <div class="dt-panel" id="dt-panel">
+        <div class="dt-header" id="dt-header">
+          <span class="dt-title">Drip Devtools</span>
+          <span class="dt-badge">${assignments.length} active</span>
+          <button class="dt-btn dt-toggle" id="dt-toggle">${this.collapsed ? "+" : "−"}</button>
+        </div>
+        ${this.collapsed ? "" : `
+        <div class="dt-tabs">
+          <button class="dt-tab ${this.activeTab === "sequence" ? "active" : ""}" data-tab="sequence">Sequence</button>
+          <button class="dt-tab ${this.activeTab === "assignments" ? "active" : ""}" data-tab="assignments">Assignments</button>
+          <button class="dt-tab ${this.activeTab === "log" ? "active" : ""}" data-tab="log">Log (${eventLog.length})</button>
+          <button class="dt-tab ${this.activeTab === "force" ? "active" : ""}" data-tab="force">Force</button>
+        </div>
+        <div class="dt-body">
+          ${this.renderTabContent(experiments, assignments, diagnostics ?? null, forceMap)}
+        </div>
+        `}
+      </div>
+    `;
+
+    // Bind events
+    this.shadow.getElementById("dt-toggle")?.addEventListener("click", () => {
+      this.collapsed = !this.collapsed;
+      this.render();
+    });
+
+    this.shadow.querySelectorAll(".dt-tab").forEach((tab) => {
+      tab.addEventListener("click", () => {
+        this.activeTab = (tab as HTMLElement).dataset.tab as typeof this.activeTab;
+        this.render();
+      });
+    });
+
+    // Force variation selects
+    this.shadow.querySelectorAll<HTMLSelectElement>(".dt-force-select").forEach((select) => {
+      select.addEventListener("change", () => {
+        const expId = select.dataset.expId!;
+        const varId = select.value;
+        if (varId) this.opts.onForceVariation(expId, varId);
+      });
+    });
+  }
+
+  private renderTabContent(
+    experiments: Experiment[],
+    assignments: Assignment[],
+    diagnostics: SdkDiagnostics | null,
+    forceMap: Record<string, string> | null,
+  ): string {
+    switch (this.activeTab) {
+      case "sequence":
+        return this.renderSequence(diagnostics);
+      case "assignments":
+        return this.renderAssignments(assignments);
+      case "log":
+        return this.renderLog();
+      case "force":
+        return this.renderForce(experiments, forceMap);
+    }
+  }
+
+  private renderSequence(diagnostics: SdkDiagnostics | null): string {
+    if (!diagnostics) return `<div class="dt-empty">No diagnostics available</div>`;
+    const project = diagnostics.activation.project.gates;
+    const experiments = diagnostics.activation.experiments;
+    return `
+      <div class="dt-section-title">Project</div>
+      <div class="dt-card">${project.map((gate) => this.renderGate(gate)).join("")}</div>
+      <div class="dt-section-title">Experiments</div>
+      ${experiments.length === 0
+        ? `<div class="dt-empty compact">No experiment sequence yet</div>`
+        : experiments.map((experiment) => `
+          <div class="dt-card">
+            <div class="dt-card-title">${esc(experiment.experimentName || experiment.experimentId)}</div>
+            <div class="dt-card-row"><span>Status:</span> <span class="dt-status dt-status-${experiment.status}">${esc(experiment.status)}</span></div>
+            ${experiment.assignedVariationId
+              ? `<div class="dt-card-row"><span>Variation:</span> <span>${esc(experiment.assignedVariationId)}</span></div>`
+              : `<div class="dt-card-row"><span>Reason:</span> <span>${esc(experiment.reason || "not_assigned")}</span></div>`}
+            <div class="dt-gates">${experiment.gates.map((gate) => this.renderGate(gate)).join("")}</div>
+          </div>
+        `).join("")}
+    `;
+  }
+
+  private renderGate(gate: ActivationGateDiagnostic): string {
+    return `
+      <div class="dt-gate">
+        <span class="dt-dot dt-dot-${gate.status}"></span>
+        <span class="dt-gate-label">${esc(gate.label)}</span>
+        <span class="dt-gate-reason">${esc(gate.reason || gate.status)}</span>
+      </div>
+    `;
+  }
+
+  private renderAssignments(assignments: Assignment[]): string {
+    if (assignments.length === 0) {
+      return `<div class="dt-empty">No active assignments</div>`;
+    }
+    return assignments
+      .map(
+        (a) => `
+      <div class="dt-card">
+        <div class="dt-card-title">${esc(a.experimentId)}</div>
+        <div class="dt-card-row"><span>Variation:</span> <span>${esc(a.variationId)}</span></div>
+        <div class="dt-card-row"><span>Index:</span> <span>${a.index}</span></div>
+        <div class="dt-card-row"><span>Control:</span> <span>${a.isControl ? "Yes" : "No"}</span></div>
+        <div class="dt-card-row"><span>Mutations:</span> <span>${a.mutations.length}</span></div>
+        <div class="dt-card-row"><span>CSS:</span> <span>${a.css ? "Yes" : "No"}</span></div>
+        <div class="dt-card-row"><span>JS:</span> <span>${a.js ? "Yes" : "No"}</span></div>
+        <div class="dt-card-row"><span>External CSS:</span> <span>${a.externalCssUrl ? "Yes" : "No"}</span></div>
+        <div class="dt-card-row"><span>External JS:</span> <span>${a.externalJsUrl ? "Yes" : "No"}</span></div>
+        <div class="dt-card-row"><span>Harness:</span> <span>${a.harnessSession ? `v${a.harnessSession.version ?? 0}` : "No"}</span></div>
+      </div>
+    `,
+      )
+      .join("");
+  }
+
+  private renderLog(): string {
+    if (eventLog.length === 0) {
+      return `<div class="dt-empty">No events logged yet</div>`;
+    }
+    const entries = [...eventLog].reverse().slice(0, 50);
+    return `<div class="dt-log">${entries
+      .map(
+        (e) => `<div class="dt-log-entry">
+        <span class="dt-log-time">${new Date(e.ts).toLocaleTimeString()}</span>
+        <span class="dt-log-type dt-type-${e.type}">${esc(e.type)}</span>
+        <span class="dt-log-label">${esc(e.label)}</span>
+      </div>`,
+      )
+      .join("")}</div>`;
+  }
+
+  private renderForce(
+    experiments: Experiment[],
+    forceMap: Record<string, string> | null,
+  ): string {
+    if (experiments.length === 0) {
+      return `<div class="dt-empty">No experiments available</div>`;
+    }
+    return experiments
+      .map(
+        (exp) => `
+      <div class="dt-card">
+        <div class="dt-card-title">${esc(exp.id)}</div>
+        <select class="dt-force-select" data-exp-id="${esc(exp.id)}">
+          <option value="">— Natural assignment —</option>
+          ${exp.variations
+            .map(
+              (v, i) =>
+                `<option value="${esc(v.id)}" ${forceMap?.[exp.id] === v.id ? "selected" : ""}>${esc(v.id)}${v.isControl ? " (control)" : ""} — ${(v.weight * 100).toFixed(0)}%</option>`,
+            )
+            .join("")}
+        </select>
+      </div>
+    `,
+      )
+      .join("");
+  }
+
+  private attachDrag(): void {
+    const header = () => this.shadow.getElementById("dt-header");
+    const panel = () => this.shadow.getElementById("dt-panel");
+
+    const onMouseDown = (e: MouseEvent) => {
+      const p = panel();
+      if (!p) return;
+      const rect = p.getBoundingClientRect();
+      this.dragState = {
+        startX: e.clientX,
+        startY: e.clientY,
+        offsetX: rect.left,
+        offsetY: rect.top,
+      };
+      e.preventDefault();
+    };
+
+    const onMouseMove = (e: MouseEvent) => {
+      if (!this.dragState) return;
+      const p = panel();
+      if (!p) return;
+      const dx = e.clientX - this.dragState.startX;
+      const dy = e.clientY - this.dragState.startY;
+      p.style.left = `${this.dragState.offsetX + dx}px`;
+      p.style.top = `${this.dragState.offsetY + dy}px`;
+      p.style.right = "auto";
+      p.style.bottom = "auto";
+    };
+
+    const onMouseUp = () => {
+      this.dragState = null;
+    };
+
+    // Use capturing on the host document to ensure drag works even outside shadow
+    const attachHeader = () => {
+      const h = header();
+      if (h) h.addEventListener("mousedown", onMouseDown);
+    };
+    attachHeader();
+
+    // Re-attach after renders
+    const origRender = this.render.bind(this);
+    this.render = () => {
+      origRender();
+      attachHeader();
+    };
+
+    document.addEventListener("mousemove", onMouseMove);
+    document.addEventListener("mouseup", onMouseUp);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTML escaping
+// ---------------------------------------------------------------------------
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+// ---------------------------------------------------------------------------
+// Panel CSS
+// ---------------------------------------------------------------------------
+
+const PANEL_CSS = `
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+
+  .dt-panel {
+    position: fixed;
+    bottom: 16px;
+    right: 16px;
+    width: 340px;
+    max-height: 480px;
+    background: #1a1a2e;
+    border: 1px solid #333;
+    border-radius: 8px;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    font-size: 12px;
+    color: #e0e0e0;
+    z-index: 2147483647;
+    box-shadow: 0 4px 24px rgba(0,0,0,0.5);
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+
+  .dt-header {
+    display: flex;
+    align-items: center;
+    padding: 8px 12px;
+    background: #16213e;
+    cursor: move;
+    user-select: none;
+    border-bottom: 1px solid #333;
+  }
+
+  .dt-title {
+    font-weight: 600;
+    font-size: 13px;
+    color: #fff;
+    flex: 1;
+  }
+
+  .dt-badge {
+    background: #0f3460;
+    color: #e0e0e0;
+    padding: 2px 8px;
+    border-radius: 10px;
+    font-size: 10px;
+    margin-right: 8px;
+  }
+
+  .dt-btn {
+    background: none;
+    border: none;
+    color: #aaa;
+    cursor: pointer;
+    font-size: 16px;
+    line-height: 1;
+    padding: 2px 6px;
+  }
+  .dt-btn:hover { color: #fff; }
+
+  .dt-tabs {
+    display: flex;
+    border-bottom: 1px solid #333;
+  }
+
+  .dt-tab {
+    flex: 1;
+    padding: 6px 8px;
+    background: none;
+    border: none;
+    color: #888;
+    cursor: pointer;
+    font-size: 11px;
+    text-align: center;
+    border-bottom: 2px solid transparent;
+  }
+  .dt-tab:hover { color: #ccc; }
+  .dt-tab.active { color: #53c1de; border-bottom-color: #53c1de; }
+
+  .dt-body {
+    overflow-y: auto;
+    max-height: 360px;
+    padding: 8px;
+  }
+
+  .dt-empty {
+    text-align: center;
+    color: #666;
+    padding: 24px;
+  }
+  .dt-empty.compact { padding: 12px; }
+
+  .dt-section-title {
+    color: #888;
+    font-size: 10px;
+    font-weight: 700;
+    letter-spacing: 0.04em;
+    margin: 4px 2px 6px;
+    text-transform: uppercase;
+  }
+
+  .dt-card {
+    background: #16213e;
+    border-radius: 6px;
+    padding: 8px 10px;
+    margin-bottom: 6px;
+  }
+
+  .dt-card-title {
+    font-weight: 600;
+    color: #fff;
+    margin-bottom: 4px;
+    font-size: 12px;
+  }
+
+  .dt-card-row {
+    display: flex;
+    justify-content: space-between;
+    padding: 1px 0;
+    color: #aaa;
+    font-size: 11px;
+  }
+  .dt-card-row span:last-child { color: #e0e0e0; }
+
+  .dt-status {
+    border-radius: 3px;
+    font-size: 10px;
+    padding: 1px 5px;
+    text-transform: uppercase;
+  }
+  .dt-status-passed { background: #166534; color: #dcfce7 !important; }
+  .dt-status-failed { background: #7f1d1d; color: #fee2e2 !important; }
+  .dt-status-skipped { background: #334155; color: #e2e8f0 !important; }
+
+  .dt-gates {
+    margin-top: 6px;
+    border-top: 1px solid rgba(255,255,255,0.08);
+    padding-top: 5px;
+  }
+
+  .dt-gate {
+    display: grid;
+    grid-template-columns: 10px minmax(86px, 1fr) minmax(0, 1fr);
+    align-items: center;
+    gap: 6px;
+    padding: 3px 0;
+    color: #b8c1d1;
+    font-size: 11px;
+  }
+
+  .dt-dot {
+    width: 7px;
+    height: 7px;
+    border-radius: 999px;
+    display: inline-block;
+  }
+  .dt-dot-passed { background: #22c55e; }
+  .dt-dot-failed { background: #ef4444; }
+  .dt-dot-skipped { background: #64748b; }
+  .dt-gate-label { color: #e5e7eb; }
+  .dt-gate-reason {
+    color: #8b95a7;
+    overflow: hidden;
+    text-align: right;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .dt-force-select {
+    width: 100%;
+    margin-top: 6px;
+    padding: 4px 8px;
+    background: #0f3460;
+    border: 1px solid #444;
+    color: #e0e0e0;
+    border-radius: 4px;
+    font-size: 11px;
+  }
+
+  .dt-log {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+
+  .dt-log-entry {
+    display: flex;
+    gap: 6px;
+    padding: 3px 4px;
+    border-radius: 3px;
+    font-size: 11px;
+    line-height: 1.4;
+  }
+  .dt-log-entry:hover { background: rgba(255,255,255,0.03); }
+
+  .dt-log-time { color: #666; flex-shrink: 0; font-family: monospace; }
+  .dt-log-type { flex-shrink: 0; font-weight: 600; text-transform: uppercase; font-size: 9px; padding: 1px 4px; border-radius: 3px; }
+  .dt-log-label { color: #ccc; }
+
+  .dt-type-init { background: #1a6; color: #fff; }
+  .dt-type-eval { background: #36a; color: #fff; }
+  .dt-type-apply { background: #a63; color: #fff; }
+  .dt-type-track { background: #63a; color: #fff; }
+  .dt-type-goal { background: #a36; color: #fff; }
+  .dt-type-qa { background: #3aa; color: #fff; }
+  .dt-type-guard { background: #666; color: #fff; }
+  .dt-type-tracker { background: #636; color: #fff; }
+`;

package/src/dom-trigger.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+class FakeElement {
+  constructor(
+    private readonly id: string,
+    private readonly inQaAssistantHost = false,
+  ) {}
+
+  getAttribute(name: string): string | null {
+    return name === "id" ? this.id : null;
+  }
+
+  closest(selector: string): FakeElement | null {
+    return this.inQaAssistantHost && selector.includes("#drip-qa-assistant-host") ? this : null;
+  }
+}
+
+describe("observeDomChanges", () => {
+  const originalDocument = (globalThis as any).document;
+  const originalElement = (globalThis as any).Element;
+  const originalMutationObserver = (globalThis as any).MutationObserver;
+  const originalWindow = (globalThis as any).window;
+  let mutationCallback: MutationCallback | null = null;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    (globalThis as any).Element = FakeElement;
+    (globalThis as any).document = {
+      documentElement: new FakeElement("html"),
+    };
+    (globalThis as any).window = {
+      clearTimeout,
+      setTimeout,
+    };
+    (globalThis as any).MutationObserver = class MutationObserver {
+      constructor(callback: MutationCallback) {
+        mutationCallback = callback;
+      }
+
+      observe = vi.fn();
+      disconnect = vi.fn();
+    };
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    (globalThis as any).document = originalDocument;
+    (globalThis as any).Element = originalElement;
+    (globalThis as any).MutationObserver = originalMutationObserver;
+    (globalThis as any).window = originalWindow;
+    mutationCallback = null;
+  });
+
+  it("ignores mutations inside the QA Assistant host", async () => {
+    const observer = vi.fn();
+    const { observeDomChanges } = await import("./dom-trigger");
+    observeDomChanges(observer, 25);
+
+    mutationCallback?.([
+      {
+        addedNodes: [new FakeElement("assistant-button", true)],
+        type: "childList",
+      } as unknown as MutationRecord,
+    ], {} as MutationObserver);
+    vi.advanceTimersByTime(25);
+
+    expect(observer).not.toHaveBeenCalled();
+  });
+});

package/src/dom-trigger.ts

@@ -0,0 +1,55 @@
+import { registerMutedObserver, unregisterMutedObserver } from "./observer-mute";
+
+type DomChangeObserver = () => void;
+
+const QA_ASSISTANT_HOST_SELECTOR = "#" + ["drip", "qa", "assistant", "host"].join("-");
+const APEX_HOST_SELECTOR = ["#drip-qa-toolbar", QA_ASSISTANT_HOST_SELECTOR, "#drip-devtools-host"].join(",");
+
+function isApexNode(node: Node): boolean {
+  if (!(node instanceof Element)) return false;
+  const id = node.getAttribute("id") || "";
+  return id.startsWith("drip-") || node.closest?.(APEX_HOST_SELECTOR) != null;
+}
+
+export function observeDomChanges(
+  observer: DomChangeObserver,
+  debounceMs = 250,
+): () => void {
+  if (typeof MutationObserver === "undefined" || !document.documentElement) {
+    return () => {};
+  }
+
+  let timer: number | null = null;
+  const schedule = () => {
+    if (timer !== null) window.clearTimeout(timer);
+    timer = window.setTimeout(() => {
+      timer = null;
+      observer();
+    }, debounceMs);
+  };
+
+  const onRecords: MutationCallback = (mutations) => {
+    const relevant = mutations.some((mutation) => {
+      if (mutation.type === "attributes") {
+        return mutation.target instanceof Element && !isApexNode(mutation.target);
+      }
+      return Array.from(mutation.addedNodes).some((node) => !isApexNode(node));
+    });
+    if (relevant) schedule();
+  };
+  const mutationObserver = new MutationObserver(onRecords);
+
+  registerMutedObserver(mutationObserver, onRecords);
+  mutationObserver.observe(document.documentElement, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["class", "style", "hidden", "aria-hidden"],
+  });
+
+  return () => {
+    if (timer !== null) window.clearTimeout(timer);
+    mutationObserver.disconnect();
+    unregisterMutedObserver(mutationObserver);
+  };
+}