@drip-apex/sdk 0.1.0

package/src/editor/operator.ts

@@ -0,0 +1,256 @@
+import type { Mutation } from "../types";
+import { upsertMutation } from "./artifacts";
+import type {
+  ActiveEditorSession,
+  EditorArtifacts,
+} from "./types";
+
+const MAX_CONTEXT_CHARS = 180_000;
+const MAX_CONVERSATION_MESSAGES = 12;
+const CONTEXT_SELECTORS = [
+  "main",
+  "header",
+  "footer",
+  "section",
+  "article",
+  "nav",
+  "form",
+  "h1",
+  "h2",
+  "h3",
+  "p",
+  "button",
+  "a[href]",
+  "input",
+  "select",
+  "textarea",
+  "img",
+  "[role]",
+  "[data-testid]",
+].join(",");
+
+export type EditorOperatorMessage = {
+  role: "user" | "assistant";
+  content: string;
+};
+
+export type EditorOperatorSelectedElement = {
+  selector: string;
+  tag?: string;
+  textPreview?: string;
+  alternatives?: string[];
+};
+
+export type EditorOperatorResult = {
+  artifacts: EditorArtifacts;
+  explanation: string;
+  artifactCount: number;
+  mergeStrategy: "append" | "replace";
+};
+
+function compactWhitespace(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+export function redactEditorContextUrl(value: string, baseUrl?: string): string {
+  try {
+    const url = new URL(value, baseUrl);
+    if (url.protocol === "http:" || url.protocol === "https:") {
+      url.username = "";
+      url.password = "";
+      url.search = "";
+      url.hash = "";
+      return url.toString();
+    }
+    return `${url.protocol}[redacted]`;
+  } catch {
+    return value.split(/[?#]/, 1)[0].slice(0, 500);
+  }
+}
+
+function safeAttributeEntries(element: Element): Array<[string, string]> {
+  return Array.from(element.attributes)
+    .filter(({ name }) => {
+      const lower = name.toLowerCase();
+      return (
+        lower === "id" ||
+        lower === "class" ||
+        lower === "href" ||
+        lower === "src" ||
+        lower === "alt" ||
+        lower === "title" ||
+        lower === "name" ||
+        lower === "type" ||
+        lower === "role" ||
+        lower.startsWith("aria-") ||
+        lower === "data-testid" ||
+        lower === "data-section-id" ||
+        lower === "data-product-id"
+      );
+    })
+    .map(({ name, value }) => [
+      name,
+      name.toLowerCase() === "href" || name.toLowerCase() === "src"
+        ? redactEditorContextUrl(value, element.ownerDocument.baseURI)
+        : value.slice(0, 500),
+    ]);
+}
+
+function serializeElement(element: Element): string {
+  const tag = element.tagName.toLowerCase();
+  const attributes = safeAttributeEntries(element)
+    .map(([name, value]) => `${name}=${JSON.stringify(value)}`)
+    .join(" ");
+  const text =
+    element instanceof HTMLInputElement ||
+    element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement
+      ? ""
+      : compactWhitespace(element.textContent ?? "").slice(0, 600);
+  return `<${tag}${attributes ? ` ${attributes}` : ""}>${text}</${tag}>`;
+}
+
+export function collectEditorDomContext(
+  documentLike: Document = document,
+): string {
+  const lines = [
+    `url=${redactEditorContextUrl(documentLike.location?.href ?? "")}`,
+    `title=${compactWhitespace(documentLike.title ?? "")}`,
+  ];
+  const seen = new Set<Element>();
+  for (const element of Array.from(
+    documentLike.querySelectorAll(CONTEXT_SELECTORS),
+  )) {
+    if (seen.has(element) || element.id === "apex-editor-host") continue;
+    seen.add(element);
+    lines.push(serializeElement(element));
+    if (lines.join("\n").length >= MAX_CONTEXT_CHARS) break;
+  }
+  return lines.join("\n").slice(0, MAX_CONTEXT_CHARS);
+}
+
+function parseMutation(value: unknown): Mutation | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const mutation = value as Mutation;
+  return typeof mutation.selector === "string" &&
+    typeof mutation.action === "string"
+    ? mutation
+    : null;
+}
+
+function appendCode(current: string, generated: string): string {
+  if (!generated.trim()) return current;
+  if (!current.trim()) return generated;
+  return `${current.trimEnd()}\n\n${generated.trimStart()}`;
+}
+
+export function mergeEditorOperatorArtifacts(input: {
+  current: EditorArtifacts;
+  generatedMutations: unknown;
+  generatedCss: unknown;
+  generatedJs: unknown;
+  mergeStrategy: unknown;
+}): EditorArtifacts {
+  const generated = Array.isArray(input.generatedMutations)
+    ? input.generatedMutations.map(parseMutation).filter((value): value is Mutation => Boolean(value))
+    : [];
+  const customCss =
+    typeof input.generatedCss === "string" ? input.generatedCss : "";
+  const customJs =
+    typeof input.generatedJs === "string" ? input.generatedJs : "";
+  if (input.mergeStrategy === "replace") {
+    return { mutations: generated, customCss, customJs };
+  }
+  return {
+    mutations: generated.reduce(
+      (artifacts, mutation) => upsertMutation(artifacts, mutation),
+      input.current,
+    ).mutations,
+    customCss: appendCode(input.current.customCss, customCss),
+    customJs: appendCode(input.current.customJs, customJs),
+  };
+}
+
+function errorMessage(payload: unknown, status: number): string {
+  if (payload && typeof payload === "object") {
+    const error = (payload as { error?: unknown }).error;
+    if (typeof error === "string" && error.trim()) return error.trim();
+  }
+  return `Operator request failed (${status})`;
+}
+
+export async function runEditorOperatorTurn(input: {
+  apiOrigin: string;
+  session: ActiveEditorSession;
+  variationId: string;
+  prompt: string;
+  artifacts: EditorArtifacts;
+  conversation: EditorOperatorMessage[];
+  pageContext?: string;
+  signal?: AbortSignal;
+  selectedElement?: EditorOperatorSelectedElement | null;
+  documentLike?: Document;
+  fetchImpl?: typeof fetch;
+}): Promise<EditorOperatorResult> {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const response = await fetchImpl(
+    new URL(
+      `/api/editor-sessions/${encodeURIComponent(input.session.sid)}/operator`,
+      input.apiOrigin,
+    ),
+    {
+      method: "POST",
+      credentials: "omit",
+      cache: "no-store",
+      referrerPolicy: "no-referrer",
+      signal: input.signal,
+      headers: {
+        Authorization: `Bearer ${input.session.bearer}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        prompt: input.prompt,
+        variationId: input.variationId,
+        domContext: collectEditorDomContext(input.documentLike),
+        pageContext:
+          input.pageContext ??
+          `Live merchant page: ${redactEditorContextUrl(input.session.targetUrl)}`,
+        existingMutations: input.artifacts.mutations,
+        existingCustomCss: input.artifacts.customCss,
+        existingCustomJs: input.artifacts.customJs,
+        conversation: input.conversation.slice(-MAX_CONVERSATION_MESSAGES),
+        selectedElement: input.selectedElement ?? undefined,
+      }),
+    },
+  );
+  const payload = (await response.json().catch(() => null)) as
+    | Record<string, unknown>
+    | null;
+  if (!response.ok || !payload) {
+    throw new Error(errorMessage(payload, response.status));
+  }
+  const mergeStrategy =
+    payload.mergeStrategy === "replace" ? "replace" : "append";
+  const artifacts = mergeEditorOperatorArtifacts({
+    current: input.artifacts,
+    generatedMutations: payload.mutations,
+    generatedCss: payload.customCss,
+    generatedJs: payload.customJs,
+    mergeStrategy,
+  });
+  const artifactCount =
+    (Array.isArray(payload.mutations) ? payload.mutations.length : 0) +
+    (typeof payload.customCss === "string" && payload.customCss.trim() ? 1 : 0) +
+    (typeof payload.customJs === "string" && payload.customJs.trim() ? 1 : 0);
+  return {
+    artifacts,
+    explanation:
+      typeof payload.explanation === "string" && payload.explanation.trim()
+        ? payload.explanation.trim()
+        : artifactCount
+          ? "Draft treatment created. Review the result before QA."
+          : "No draft changes were produced.",
+    artifactCount,
+    mergeStrategy,
+  };
+}

package/src/editor/picker.test.ts

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ElementPicker } from "./picker";
+
+function createPicker(onSelect = vi.fn()) {
+  const box = document.createElement("div");
+  const label = document.createElement("div");
+  document.body.append(box, label);
+  const picker = new ElementPicker(
+    { box, label },
+    onSelect,
+    vi.fn(),
+  );
+  return { picker, onSelect };
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("ElementPicker", () => {
+  it("selects elements reachable by document selectors", () => {
+    const button = document.createElement("button");
+    button.id = "buy";
+    document.body.appendChild(button);
+    const { picker, onSelect } = createPicker();
+    picker.setActive(true);
+
+    button.dispatchEvent(new MouseEvent("click", {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+    }));
+
+    expect(onSelect).toHaveBeenCalledWith(button, "#buy");
+    picker.destroy();
+  });
+
+  it("rejects elements inside a merchant shadow root", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const shadow = host.attachShadow({ mode: "open" });
+    const button = document.createElement("button");
+    button.id = "shadow-buy";
+    shadow.appendChild(button);
+    const { picker, onSelect } = createPicker();
+    picker.setActive(true);
+
+    button.dispatchEvent(new MouseEvent("click", {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+    }));
+
+    expect(onSelect).not.toHaveBeenCalled();
+    picker.destroy();
+  });
+});

package/src/editor/picker.ts

@@ -0,0 +1,152 @@
+import { elementLabel, generateDeterministicSelector } from "./selector";
+
+type PickerOverlay = {
+  box: HTMLElement;
+  label: HTMLElement;
+};
+
+function editorElement(element: Element | null): boolean {
+  return Boolean(element?.closest("#apex-editor-host"));
+}
+
+function editorEvent(event: Event): boolean {
+  return event.composedPath().some(
+    (item) => item instanceof Element && item.id === "apex-editor-host",
+  );
+}
+
+function selectableElement(element: Element): boolean {
+  return element.ownerDocument === document && element.getRootNode() === document;
+}
+
+export class ElementPicker {
+  private active = false;
+  private hovered: Element | null = null;
+  private selected: Element | null = null;
+
+  constructor(
+    private readonly overlay: PickerOverlay,
+    private readonly onSelect: (element: Element, selector: string) => void,
+    private readonly onActiveChange: (active: boolean) => void,
+    private readonly onUnsupported?: () => void,
+  ) {
+    document.addEventListener("pointermove", this.onPointerMove, true);
+    document.addEventListener("click", this.onClick, true);
+    document.addEventListener("keydown", this.onKeyDown, true);
+    window.addEventListener("scroll", this.refresh, true);
+    window.addEventListener("resize", this.refresh);
+  }
+
+  setActive(active: boolean): void {
+    this.active = active;
+    if (!active) this.hovered = null;
+    this.renderOverlay(active ? this.hovered : this.selected);
+    this.onActiveChange(active);
+  }
+
+  setSelected(element: Element | null): void {
+    this.selected = element;
+    this.renderOverlay(this.active ? this.hovered : element);
+  }
+
+  destroy(): void {
+    document.removeEventListener("pointermove", this.onPointerMove, true);
+    document.removeEventListener("click", this.onClick, true);
+    document.removeEventListener("keydown", this.onKeyDown, true);
+    window.removeEventListener("scroll", this.refresh, true);
+    window.removeEventListener("resize", this.refresh);
+  }
+
+  private onPointerMove = (event: PointerEvent) => {
+    if (!this.active) return;
+    if (editorEvent(event)) return;
+    const target = event.composedPath()[0];
+    const element = target instanceof Element ? target : null;
+    if (!element || !selectableElement(element) || editorElement(element)) return;
+    this.hovered = element;
+    this.renderOverlay(element);
+  };
+
+  private onClick = (event: MouseEvent) => {
+    if (!this.active) return;
+    if (editorEvent(event)) return;
+    const target = event.composedPath()[0];
+    const element = target instanceof Element ? target : null;
+    if (!element) return;
+    if (!selectableElement(element) || editorElement(element)) {
+      if (!editorElement(element)) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        this.onUnsupported?.();
+      }
+      return;
+    }
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    this.selected = element;
+    this.hovered = null;
+    this.active = false;
+    this.renderOverlay(element);
+    this.onSelect(element, generateDeterministicSelector(element));
+    this.onActiveChange(false);
+  };
+
+  private onKeyDown = (event: KeyboardEvent) => {
+    if (event.key === "Escape" && this.active) {
+      event.preventDefault();
+      this.setActive(false);
+      return;
+    }
+    const target = event.target;
+    if (
+      target instanceof HTMLInputElement ||
+      target instanceof HTMLTextAreaElement ||
+      target instanceof HTMLSelectElement ||
+      (target instanceof HTMLElement && target.isContentEditable)
+    ) {
+      return;
+    }
+    if (!this.selected || !["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"].includes(event.key)) {
+      return;
+    }
+    const next = event.key === "ArrowUp"
+      ? this.selected.parentElement
+      : event.key === "ArrowDown"
+        ? this.selected.firstElementChild
+        : event.key === "ArrowLeft"
+          ? this.selected.previousElementSibling
+          : this.selected.nextElementSibling;
+    if (!next || !selectableElement(next) || editorElement(next)) return;
+    event.preventDefault();
+    this.selected = next;
+    this.renderOverlay(next);
+    this.onSelect(next, generateDeterministicSelector(next));
+  };
+
+  private refresh = () => {
+    this.renderOverlay(this.active ? this.hovered : this.selected);
+  };
+
+  private renderOverlay(element: Element | null): void {
+    if (!element?.isConnected) {
+      this.overlay.box.hidden = true;
+      this.overlay.label.hidden = true;
+      return;
+    }
+    const rect = element.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) {
+      this.overlay.box.hidden = true;
+      this.overlay.label.hidden = true;
+      return;
+    }
+    this.overlay.box.hidden = false;
+    this.overlay.label.hidden = false;
+    this.overlay.box.dataset.state = this.active && element !== this.selected ? "hover" : "selected";
+    this.overlay.box.style.transform = `translate(${Math.round(rect.left)}px,${Math.round(rect.top)}px)`;
+    this.overlay.box.style.width = `${Math.round(rect.width)}px`;
+    this.overlay.box.style.height = `${Math.round(rect.height)}px`;
+    this.overlay.label.textContent = elementLabel(element);
+    const labelTop = rect.top >= 28 ? rect.top - 24 : rect.bottom + 4;
+    this.overlay.label.style.transform = `translate(${Math.max(4, Math.round(rect.left))}px,${Math.round(labelTop)}px)`;
+  }
+}

package/src/editor/selector.test.ts

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from "vitest";
+import { generateDeterministicSelector } from "./selector";
+
+describe("generateDeterministicSelector", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("prefers a stable unique id", () => {
+    document.body.innerHTML = `<main><button id="add-to-cart">Add</button></main>`;
+    const element = document.querySelector("button")!;
+    expect(generateDeterministicSelector(element)).toBe("#add-to-cart");
+  });
+
+  it("rejects volatile ids and prefers stable data attributes", () => {
+    document.body.innerHTML = `<main><button id="react-928374" data-testid="buy-button">Buy</button></main>`;
+    const element = document.querySelector("button")!;
+    expect(generateDeterministicSelector(element)).toBe('button[data-testid="buy-button"]');
+  });
+
+  it("rejects duplicate ids and returns a selector unique to the chosen element", () => {
+    document.body.innerHTML = `
+      <main>
+        <section><button id="duplicate">One</button></section>
+        <section><button id="duplicate">Two</button></section>
+      </main>`;
+    const element = document.querySelectorAll("button")[1];
+
+    const selector = generateDeterministicSelector(element);
+
+    expect(selector).not.toBe("#duplicate");
+    expect(document.querySelectorAll(selector)).toHaveLength(1);
+    expect(document.querySelector(selector)).toBe(element);
+  });
+
+  it("builds a deterministic ancestor path when direct selectors are broad", () => {
+    document.body.innerHTML = `<main><section class="product"><button>One</button></section><section class="product"><button>Two</button></section></main>`;
+    const element = document.querySelectorAll("button")[1];
+    const selector = generateDeterministicSelector(element);
+    expect(document.querySelectorAll(selector)).toHaveLength(1);
+    expect(document.querySelector(selector)).toBe(element);
+  });
+});

package/src/editor/selector.ts

@@ -0,0 +1,110 @@
+const UNSTABLE_ID = /(?:^|[-_])(react|vue|ember|svelte|uid|uuid|random|generated)[-_]?|\d{5,}/i;
+const UNSTABLE_CLASS = /^(active|current|selected|hover|focus|open|closed|js-|is-|has-)|\d{4,}/i;
+
+function escapeCss(value: string): string {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  return value.replace(/[^a-zA-Z0-9_-]/g, (character) => `\\${character}`);
+}
+
+function quotedAttribute(name: string, value: string): string {
+  return `[${name}="${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]`;
+}
+
+function isUnique(selector: string, root: ParentNode): boolean {
+  try {
+    return root.querySelectorAll(selector).length === 1;
+  } catch {
+    return false;
+  }
+}
+
+function stableId(element: Element): string | null {
+  const id = element.id.trim();
+  return id && id.length <= 80 && !UNSTABLE_ID.test(id) ? id : null;
+}
+
+function stableAttribute(element: Element): { name: string; value: string } | null {
+  const names = ["data-testid", "data-test", "data-cy", "data-drip-id", "name", "aria-label"];
+  for (const name of names) {
+    const value = element.getAttribute(name)?.trim();
+    if (value && value.length <= 120) return { name, value };
+  }
+  for (const attribute of Array.from(element.attributes)) {
+    if (
+      attribute.name.startsWith("data-") &&
+      !attribute.name.startsWith("data-react") &&
+      attribute.value &&
+      attribute.value.length <= 120 &&
+      !UNSTABLE_ID.test(attribute.value)
+    ) {
+      return { name: attribute.name, value: attribute.value };
+    }
+  }
+  return null;
+}
+
+function stableClasses(element: Element): string[] {
+  return Array.from(element.classList)
+    .filter((name) => name.length <= 64 && !UNSTABLE_CLASS.test(name))
+    .slice(0, 2);
+}
+
+function segment(element: Element, root: ParentNode): string {
+  const tag = element.tagName.toLowerCase();
+  const id = stableId(element);
+  if (id) {
+    const candidate = `#${escapeCss(id)}`;
+    if (isUnique(candidate, root)) return candidate;
+  }
+  const attribute = stableAttribute(element);
+  if (attribute) {
+    const candidate = `${tag}${quotedAttribute(attribute.name, attribute.value)}`;
+    if (isUnique(candidate, root)) return candidate;
+  }
+  const classes = stableClasses(element);
+  if (classes.length) {
+    const candidate = `${tag}.${classes.map(escapeCss).join(".")}`;
+    if (isUnique(candidate, root)) return candidate;
+  }
+  const parent = element.parentElement;
+  if (!parent) return tag;
+  const sameTag = Array.from(parent.children).filter((child) => child.tagName === element.tagName);
+  return sameTag.length > 1
+    ? `${tag}:nth-of-type(${sameTag.indexOf(element) + 1})`
+    : tag;
+}
+
+export function generateDeterministicSelector(
+  element: Element,
+  root: ParentNode = document,
+): string {
+  const ownerDocument = element.ownerDocument ?? document;
+  const id = stableId(element);
+  if (id) {
+    const candidate = `#${escapeCss(id)}`;
+    if (isUnique(candidate, root)) return candidate;
+  }
+  const direct = segment(element, root);
+  if (isUnique(direct, root)) return direct;
+
+  const parts = [direct];
+  let current = element.parentElement;
+  while (current && current !== ownerDocument.documentElement && parts.length < 5) {
+    const part = segment(current, root);
+    parts.unshift(part);
+    const candidate = parts.join(" > ");
+    if (isUnique(candidate, root)) return candidate;
+    if (part.startsWith("#")) break;
+    current = current.parentElement;
+  }
+  return parts.join(" > ");
+}
+
+export function elementLabel(element: Element): string {
+  const tag = element.tagName.toLowerCase();
+  const className = stableClasses(element)[0];
+  const rect = element.getBoundingClientRect();
+  return `${tag}${className ? `.${className}` : ""} ${Math.round(rect.width)}x${Math.round(rect.height)}`;
+}