@drip-apex/sdk 0.1.0

package/src/editor/controller.ts

@@ -0,0 +1,596 @@
+import { createMutationApplicationContext, type MutationApplicationContext } from "../mutate";
+import { sanitizeHtml } from "../sanitize";
+import type { Mutation } from "../types";
+import { EditorApi, EditorApiError } from "./api";
+import { ArtifactHistory, removeMutationAt, removeSelectorMutations, upsertMutation } from "./artifacts";
+import { DevicePreview } from "./device-preview";
+import {
+  cloneArtifacts,
+  EMPTY_EDITOR_ARTIFACTS,
+  type ActiveEditorSession,
+  type EditorArtifacts,
+  type EditorDeviceState,
+  type EditorState,
+} from "./types";
+
+const EDITOR_CSS_ID = "apex-editor-draft-css";
+const AUTOSAVE_MS = 700;
+const EXIT_REVOKE_TIMEOUT_MS = 1_500;
+
+export type ArtifactCommandAudit = {
+  ok: boolean;
+  mutationAudit: Array<{
+    index: number;
+    selector: string;
+    action: string;
+    beforeCount: number;
+    afterCount: number;
+    effectVerified: boolean;
+    error: string | null;
+  }>;
+  generatedSelectors: string[];
+  generatedVisibility: Array<{
+    selector: string;
+    count: number;
+    visibleCount: number;
+    matches: Array<{ text: string; visible: boolean }>;
+  }>;
+  visibleGeneratedCount: number;
+  hiddenEffectVerifiedCount: number;
+  networkRequired: boolean;
+  customJsDeferred: boolean;
+  error?: string;
+  repairHint?: string;
+};
+
+export class EditorController {
+  private state: EditorState = {
+    variation: null,
+    artifacts: cloneArtifacts(EMPTY_EDITOR_ARTIFACTS),
+    artifactsEnabled: true,
+    pickerActive: false,
+    selectedElement: null,
+    selectedSelector: null,
+    saveState: "idle",
+    saveMessage: null,
+    dock: "top",
+    canUndo: false,
+    canRedo: false,
+    jsApplied: false,
+    reloadRequired: false,
+    deviceState: "closed",
+  };
+  private readonly listeners = new Set<(state: EditorState) => void>();
+  private readonly history = new ArtifactHistory();
+  private visualContext: MutationApplicationContext | null = null;
+  private devicePreview: DevicePreview | null = null;
+  private saveTimer: ReturnType<typeof setTimeout> | null = null;
+  private saveQueue: Promise<void> = Promise.resolve();
+  private revision = 0;
+  private variationRequest = 0;
+  private readonly cleanups = new Set<() => void>();
+
+  constructor(
+    readonly session: ActiveEditorSession,
+    readonly apiOrigin: string,
+    private readonly api = new EditorApi(apiOrigin, session),
+    private readonly reload = () => location.reload(),
+  ) {}
+
+  getState(): EditorState {
+    return this.state;
+  }
+
+  subscribe(listener: (state: EditorState) => void): () => void {
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => this.listeners.delete(listener);
+  }
+
+  async initialize(): Promise<void> {
+    await this.selectVariation(this.session.initialVariationId);
+  }
+
+  async selectVariation(variationId: string): Promise<void> {
+    const request = ++this.variationRequest;
+    this.cancelSave();
+    this.patch({ saveState: "idle", saveMessage: "Loading draft..." });
+    try {
+      const loaded = await this.api.loadArtifacts(variationId);
+      if (request !== this.variationRequest) return;
+      this.history.reset();
+      this.revision += 1;
+      this.state = {
+        ...this.state,
+        variation: loaded.variation,
+        artifacts: cloneArtifacts(loaded.artifacts),
+        selectedElement: null,
+        selectedSelector: null,
+        saveState: "saved",
+        saveMessage: "Saved",
+        canUndo: false,
+        canRedo: false,
+        jsApplied: false,
+        reloadRequired: false,
+      };
+      this.applyVisualArtifacts();
+      this.emit();
+    } catch (error) {
+      if (request !== this.variationRequest) return;
+      this.patch({
+        saveState: "error",
+        saveMessage: error instanceof Error ? error.message : "Draft could not be loaded",
+      });
+    }
+  }
+
+  setPickerActive(active: boolean): void {
+    this.patch({ pickerActive: active });
+  }
+
+  selectElement(element: Element, selector: string): void {
+    this.patch({ selectedElement: element, selectedSelector: selector, pickerActive: false });
+  }
+
+  clearSelection(): void {
+    this.clearSelectedElement();
+  }
+
+  clearSelectedElement(): void {
+    this.patch({ selectedElement: null, selectedSelector: null, pickerActive: false });
+  }
+
+  removeSelector(selector: string): void {
+    this.commit(removeSelectorMutations(this.state.artifacts, selector));
+  }
+
+  removeMutation(index: number): void {
+    if (!Number.isInteger(index) || index < 0 || index >= this.state.artifacts.mutations.length) return;
+    this.commit(removeMutationAt(this.state.artifacts, index));
+  }
+
+  restoreArtifacts(artifacts: EditorArtifacts): void {
+    this.commit(cloneArtifacts(artifacts));
+  }
+
+  async extendSession(): Promise<string | null> {
+    const expiresAt = await this.api.extendSession();
+    if (expiresAt) this.session.expiresAt = expiresAt;
+    return expiresAt;
+  }
+
+  async resolveConflict(choice: "mine" | "theirs"): Promise<void> {
+    const variation = this.state.variation;
+    if (!variation || this.state.saveState !== "conflict") return;
+    if (choice === "theirs") {
+      await this.selectVariation(variation.id);
+      return;
+    }
+    try {
+      const loaded = await this.api.loadArtifacts(variation.id);
+      this.state = {
+        ...this.state,
+        variation: { ...variation, artifactHash: loaded.variation.artifactHash },
+        saveState: "idle",
+        saveMessage: "Unsaved changes",
+      };
+      this.emit();
+      await this.saveNow();
+    } catch (error) {
+      this.patch({
+        saveState: "error",
+        saveMessage: error instanceof Error ? error.message : "Draft could not be saved",
+      });
+    }
+  }
+
+  toggleArtifacts(enabled: boolean): void {
+    this.state = { ...this.state, artifactsEnabled: enabled };
+    this.applyVisualArtifacts();
+    this.devicePreview?.update(this.state.artifacts, enabled);
+    this.emit();
+  }
+
+  setDock(dock: "top" | "bottom"): void {
+    this.patch({ dock });
+  }
+
+  setText(value: string): void {
+    this.mutateSelected({ action: "setText", text: value });
+  }
+
+  setImageSource(value: string): void {
+    this.mutateSelected({ action: "attribute", attributes: { src: value } });
+  }
+
+  setStyle(name: string, value: string): void {
+    this.mutateSelected({ action: "setStyle", styles: { [name]: value } });
+  }
+
+  hideSelected(): void {
+    this.setStyle("display", "none");
+  }
+
+  removeSelected(): void {
+    this.mutateSelected({ action: "remove" });
+  }
+
+  setCustomCss(value: string): void {
+    this.commit({ ...this.state.artifacts, customCss: value });
+  }
+
+  setCustomJs(value: string): void {
+    this.commit({ ...this.state.artifacts, customJs: value }, false);
+    this.patch({ jsApplied: false });
+  }
+
+  applyCustomJs(): void {
+    const code = this.state.artifacts.customJs.trim();
+    if (!code) return;
+    try {
+      new Function(`${code}\n//# sourceURL=apex-editor-draft.js`)();
+      this.patch({
+        jsApplied: true,
+        reloadRequired: true,
+        saveMessage: "JavaScript applied. Reload required to undo.",
+      });
+    } catch (error) {
+      this.patch({
+        saveState: "error",
+        saveMessage: error instanceof Error ? error.message : "JavaScript failed",
+      });
+    }
+  }
+
+  undo(): void {
+    const previous = this.history.undo(this.state.artifacts);
+    if (previous) this.replaceFromHistory(previous);
+  }
+
+  redo(): void {
+    const next = this.history.redo(this.state.artifacts);
+    if (next) this.replaceFromHistory(next);
+  }
+
+  attachDevicePreview(devicePreview: DevicePreview): void {
+    this.devicePreview = devicePreview;
+  }
+
+  setDeviceState(deviceState: EditorDeviceState): void {
+    this.patch({ deviceState });
+  }
+
+  openDevicePreview(): void {
+    this.devicePreview?.open(
+      this.state.artifactsEnabled ? this.state.artifacts : cloneArtifacts(EMPTY_EDITOR_ARTIFACTS),
+    );
+  }
+
+  closeDevicePreview(): void {
+    this.devicePreview?.close();
+  }
+
+  addCleanup(cleanup: () => void): () => void {
+    this.cleanups.add(cleanup);
+    return () => this.cleanups.delete(cleanup);
+  }
+
+  applyCommandArtifacts(artifacts: EditorArtifacts): ArtifactCommandAudit {
+    this.visualContext?.rollback();
+    this.visualContext = null;
+    document.getElementById(EDITOR_CSS_ID)?.remove();
+    const beforeCounts = artifacts.mutations.map((mutation) => this.selectorCount(mutation.selector));
+    this.state = { ...this.state, artifactsEnabled: true };
+    this.commit(cloneArtifacts(artifacts));
+    const mutationAudit = artifacts.mutations.map((mutation, index) => {
+      const beforeCount = beforeCounts[index];
+      const afterCount = this.selectorCount(mutation.selector);
+      const effectVerified = this.verifyMutationEffect(mutation, beforeCount, afterCount);
+      return {
+        index,
+        selector: mutation.selector,
+        action: mutation.action,
+        beforeCount,
+        afterCount,
+        effectVerified,
+        error: beforeCount < 0 ? "Invalid selector" : null,
+      };
+    });
+    const generatedSelectors = Array.from(new Set(
+      artifacts.mutations
+        .filter((mutation) => mutation.action !== "remove")
+        .map((mutation) => mutation.selector),
+    ));
+    const generatedVisibility = generatedSelectors.map((selector) => {
+      const elements = this.selectorElements(selector);
+      const matches = elements.slice(0, 8).map((element) => ({
+        text: (element.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 240),
+        visible: this.isVisible(element),
+      }));
+      return {
+        selector,
+        count: elements.length,
+        visibleCount: matches.filter((match) => match.visible).length,
+        matches,
+      };
+    });
+    const failed = mutationAudit.filter((entry) => !entry.effectVerified);
+    const visibleGeneratedCount = generatedVisibility.reduce(
+      (total, entry) => total + entry.visibleCount,
+      0,
+    );
+    const networkRequired = /\b(?:fetch|XMLHttpRequest|sendBeacon)\b/.test(artifacts.customJs);
+    return {
+      ok: failed.length === 0,
+      mutationAudit,
+      generatedSelectors,
+      generatedVisibility,
+      visibleGeneratedCount,
+      hiddenEffectVerifiedCount: mutationAudit.filter(
+        (entry) => entry.action === "remove" && entry.effectVerified,
+      ).length,
+      networkRequired,
+      customJsDeferred: artifacts.customJs.trim().length > 0,
+      ...(failed.length
+        ? {
+            error: "One or more mutation selectors did not match the live page.",
+            repairHint: "Inspect the current browser snapshot, choose a selector that exists, and reapply the draft.",
+          }
+        : {}),
+    };
+  }
+
+  saveNow(): Promise<void> {
+    this.cancelSave();
+    if (!this.state.variation || this.state.saveState === "conflict") {
+      return Promise.resolve();
+    }
+    const variationId = this.state.variation.id;
+    const variationRequest = this.variationRequest;
+    const queued = this.saveQueue.then(() =>
+      this.performSave(variationId, variationRequest),
+    );
+    this.saveQueue = queued.catch(() => undefined);
+    return queued;
+  }
+
+  private async performSave(
+    variationId: string,
+    saveVariationRequest: number,
+  ): Promise<void> {
+    if (
+      saveVariationRequest !== this.variationRequest ||
+      this.state.variation?.id !== variationId ||
+      this.state.saveState === "conflict"
+    ) {
+      return;
+    }
+    const expectedHash = this.state.variation.artifactHash;
+    const snapshot = cloneArtifacts(this.state.artifacts);
+    const saveRevision = this.revision;
+    this.patch({ saveState: "saving", saveMessage: "Saving..." });
+    try {
+      const result = await this.api.saveArtifacts(variationId, snapshot, expectedHash);
+      if (saveVariationRequest !== this.variationRequest || this.state.variation?.id !== variationId) return;
+      const changedDuringSave = saveRevision !== this.revision;
+      this.state = {
+        ...this.state,
+        variation: {
+          ...this.state.variation!,
+          artifactHash: result.artifactHash,
+          reviewStatus: result.reviewStatus,
+        },
+        artifacts: changedDuringSave ? this.state.artifacts : cloneArtifacts(result.artifacts),
+        saveState: changedDuringSave ? "idle" : "saved",
+        saveMessage: changedDuringSave
+          ? "Saving latest changes..."
+          : result.warningIssues[0]?.message ?? "Saved",
+      };
+      this.emit();
+    } catch (error) {
+      if (saveVariationRequest !== this.variationRequest || this.state.variation?.id !== variationId) return;
+      if (error instanceof EditorApiError && error.status === 409) {
+        this.patch({
+          saveState: "conflict",
+          saveMessage: "Draft changed elsewhere. Reload this variation before saving.",
+        });
+      } else {
+        this.patch({
+          saveState: "error",
+          saveMessage: error instanceof Error ? error.message : "Draft could not be saved",
+        });
+      }
+    }
+  }
+
+  async exit(): Promise<void> {
+    this.cancelSave();
+    this.runCleanups();
+    this.devicePreview?.close(false);
+    this.visualContext?.rollback();
+    document.getElementById(EDITOR_CSS_ID)?.remove();
+    try {
+      window.opener?.postMessage(
+        {
+          type: "apex:editor-exited",
+          sid: this.session.sid,
+          experimentId: this.session.experimentId,
+          variationId: this.state.variation?.id ?? this.session.initialVariationId,
+        },
+        this.apiOrigin,
+      );
+    } catch {}
+    try {
+      await this.withTimeout(this.api.revoke(), EXIT_REVOKE_TIMEOUT_MS);
+    } catch {}
+    this.reload();
+  }
+
+  destroy(): void {
+    this.cancelSave();
+    this.runCleanups();
+    this.devicePreview?.close(false);
+    this.visualContext?.rollback();
+    document.getElementById(EDITOR_CSS_ID)?.remove();
+    this.listeners.clear();
+  }
+
+  private mutateSelected(input: Omit<Mutation, "selector">): void {
+    const selector = this.state.selectedSelector;
+    if (!selector) return;
+    this.commit(upsertMutation(this.state.artifacts, { ...input, selector } as Mutation));
+  }
+
+  private commit(next: EditorArtifacts, applyVisual = true): void {
+    if (this.state.saveState === "conflict") return;
+    this.history.push(this.state.artifacts);
+    this.revision += 1;
+    this.state = {
+      ...this.state,
+      artifacts: cloneArtifacts(next),
+      saveState: "idle",
+      saveMessage: "Unsaved changes",
+      canUndo: this.history.canUndo,
+      canRedo: this.history.canRedo,
+    };
+    if (applyVisual) this.applyVisualArtifacts();
+    this.devicePreview?.update(this.state.artifacts, this.state.artifactsEnabled);
+    this.emit();
+    this.scheduleSave();
+  }
+
+  private replaceFromHistory(artifacts: EditorArtifacts): void {
+    this.revision += 1;
+    this.state = {
+      ...this.state,
+      artifacts,
+      saveState: "idle",
+      saveMessage: "Unsaved changes",
+      canUndo: this.history.canUndo,
+      canRedo: this.history.canRedo,
+      jsApplied: false,
+    };
+    this.applyVisualArtifacts();
+    this.devicePreview?.update(artifacts, this.state.artifactsEnabled);
+    this.emit();
+    this.scheduleSave();
+  }
+
+  private applyVisualArtifacts(): void {
+    this.visualContext?.rollback();
+    this.visualContext = null;
+    document.getElementById(EDITOR_CSS_ID)?.remove();
+    if (!this.state.artifactsEnabled) return;
+    if (this.state.artifacts.customCss.trim()) {
+      const style = document.createElement("style");
+      style.id = EDITOR_CSS_ID;
+      style.textContent = this.state.artifacts.customCss;
+      (document.head || document.documentElement).appendChild(style);
+    }
+    this.visualContext = createMutationApplicationContext();
+    this.visualContext.apply(this.state.artifacts.mutations);
+  }
+
+  private scheduleSave(): void {
+    this.cancelSave();
+    this.saveTimer = setTimeout(() => void this.saveNow(), AUTOSAVE_MS);
+  }
+
+  private cancelSave(): void {
+    if (this.saveTimer) clearTimeout(this.saveTimer);
+    this.saveTimer = null;
+  }
+
+  private patch(patch: Partial<EditorState>): void {
+    this.state = { ...this.state, ...patch };
+    this.emit();
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) listener(this.state);
+  }
+
+  private selectorElements(selector: string): Element[] {
+    try {
+      return Array.from(document.querySelectorAll(selector));
+    } catch {
+      return [];
+    }
+  }
+
+  private selectorCount(selector: string): number {
+    try {
+      return document.querySelectorAll(selector).length;
+    } catch {
+      return -1;
+    }
+  }
+
+  private isVisible(element: Element): boolean {
+    if (!(element instanceof HTMLElement)) return true;
+    const style = getComputedStyle(element);
+    if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false;
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0 || Boolean(element.textContent?.trim());
+  }
+
+  private verifyMutationEffect(
+    mutation: Mutation,
+    beforeCount: number,
+    afterCount: number,
+  ): boolean {
+    if (beforeCount <= 0) return false;
+    if (mutation.action === "remove") return afterCount === 0;
+    const elements = this.selectorElements(mutation.selector);
+    if (!elements.length) return false;
+    if ((mutation.action === "text" || mutation.action === "setText") && typeof mutation.text === "string") {
+      return elements.every((element) => element.textContent === mutation.text);
+    }
+    if (mutation.action === "html" && typeof mutation.html === "string") {
+      const sanitizedHtml = sanitizeHtml(mutation.html);
+      return elements.every((element) => {
+        const expected = element.cloneNode(false) as Element;
+        expected.innerHTML = sanitizedHtml;
+        return element.innerHTML === expected.innerHTML;
+      });
+    }
+    if (mutation.action === "attribute") {
+      const attributes = {
+        ...(mutation.attribute ? { [mutation.attribute.name]: mutation.attribute.value } : {}),
+        ...(mutation.attributes ?? {}),
+      };
+      return elements.every((element) => Object.entries(attributes).every(
+        ([name, value]) => value === null
+          ? !element.hasAttribute(name)
+          : element.getAttribute(name) === value,
+      ));
+    }
+    if (mutation.action === "style" || mutation.action === "setStyle") {
+      return elements.every((element) => Object.entries(mutation.styles ?? {}).every(
+        ([name, value]) => (element as HTMLElement).style.getPropertyValue(
+          name.includes("-") ? name : name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`),
+        ) === value,
+      ));
+    }
+    return true;
+  }
+
+  private runCleanups(): void {
+    for (const cleanup of this.cleanups) cleanup();
+    this.cleanups.clear();
+  }
+
+  private async withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    try {
+      return await Promise.race([
+        promise,
+        new Promise<undefined>((resolve) => {
+          timer = setTimeout(() => resolve(undefined), timeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+}

package/src/editor/device-preview.test.ts

@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { DevicePreview } from "./device-preview";
+
+describe("DevicePreview", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<main id="store"><h1>Original</h1></main><div id="apex-editor-host"></div>`;
+    history.replaceState(null, "", "/products/one");
+  });
+
+  it("applies the visual draft in a 390px frame and restores the store on close", () => {
+    const frameDocument = document.implementation.createHTMLDocument("Device");
+    frameDocument.body.innerHTML = `<h1>Original</h1>`;
+    const frame = {
+      hidden: true,
+      src: "",
+      onload: null as (() => void) | null,
+      onerror: null as (() => void) | null,
+      contentDocument: frameDocument,
+      contentWindow: { location: { href: "http://localhost:3000/products/one" } },
+      removeAttribute: vi.fn(),
+    } as unknown as HTMLIFrameElement;
+    const onState = vi.fn();
+    const preview = new DevicePreview(frame, onState);
+    preview.open({
+      mutations: [{ selector: "h1", action: "setText", text: "Device draft" }],
+      customCss: "h1{color:red}",
+      customJs: "alert('not executed')",
+    });
+    expect((document.getElementById("store") as HTMLElement).style.visibility).toBe("hidden");
+    frame.onload?.(new Event("load"));
+    expect(frameDocument.querySelector("h1")?.textContent).toBe("Device draft");
+    expect(frameDocument.getElementById("apex-editor-device-css")?.textContent).toContain("color:red");
+    expect(onState).toHaveBeenCalledWith("active");
+
+    preview.close();
+    expect((document.getElementById("store") as HTMLElement).style.visibility).toBe("");
+    expect(frame.hidden).toBe(true);
+  });
+
+  it("reports inaccessible frames as blocked", () => {
+    const frame = {
+      hidden: true,
+      src: "",
+      onload: null,
+      onerror: null as (() => void) | null,
+      contentDocument: null,
+      contentWindow: null,
+      removeAttribute: vi.fn(),
+    } as unknown as HTMLIFrameElement;
+    const onState = vi.fn();
+    const preview = new DevicePreview(frame, onState);
+    preview.open({ mutations: [], customCss: "", customJs: "" });
+    expect((document.getElementById("store") as HTMLElement).style.visibility).toBe("hidden");
+    frame.onerror?.(new Event("error"));
+    expect(onState).toHaveBeenLastCalledWith("blocked");
+    expect((document.getElementById("store") as HTMLElement).style.visibility).toBe("");
+    preview.close();
+  });
+});