veo-sdk 0.1.0 → 0.2.1

package/dist/builder.d.ts

@@ -0,0 +1,162 @@
+import { P as PreviewGuideInput } from './guide-preview-CO5ShtNf.js';
+export { a as PreviewHandle, b as PreviewResult, c as closeGuidePreview, p as previewGuide } from './guide-preview-CO5ShtNf.js';
+
+/**
+ * Element picker — el "inspeccionar" del navegador, pero del SDK. Corre
+ * DENTRO de la app del cliente (no en el dashboard: son orígenes distintos
+ * y el dashboard no puede leer el DOM de la app). Resalta el elemento bajo
+ * el cursor, muestra su selector + dimensiones, y al hacer click captura un
+ * selector CSS estable reutilizando `buildSelectorPath` del autocapture.
+ *
+ * Es la base del builder no-code: el dashboard abre la app del cliente en
+ * modo builder, el usuario "pincha" un elemento y el selector resultante se
+ * usa como ancla de un tooltip/walkthrough. El puente con el dashboard
+ * (postMessage) es la fase siguiente; aquí exponemos el primitivo
+ * `startElementPicker(onPick)`.
+ *
+ * No usa `innerHTML` — todo por `textContent`/DOM, igual que los renderers.
+ */
+/** Datos del elemento elegido que se entregan al caller. */
+interface PickedElement {
+    /** Selector CSS estable con ancestros (lo que se guarda como ancla). */
+    selector: string;
+    /** Selector corto solo del elemento (tag + id/atributo/clases). */
+    shortSelector: string;
+    tag: string;
+    id: string | null;
+    classes: string[];
+    text: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+interface ElementPickerOptions {
+    /** Llamado al hacer click en un elemento. El picker se cierra tras esto. */
+    onPick: (picked: PickedElement) => void;
+    /** Llamado al cancelar (Esc). El picker se cierra. */
+    onCancel?: () => void;
+    /** Niveles de ancestros del selector. Default 5 (igual que autocapture). */
+    maxAncestors?: number;
+    /** Texto del banner superior. Default en español. */
+    hint?: string;
+}
+interface ElementPickerHandle {
+    /** Cierra el picker sin elegir nada. Idempotente. */
+    stop(): void;
+}
+/**
+ * Inicia el modo de selección de elementos (inspector). Resalta lo que está
+ * bajo el cursor y, al hacer click, entrega un selector CSS estable.
+ * Devuelve un handle con `stop()`. Iniciar otro picker cierra el anterior.
+ *
+ * @example
+ * ```ts
+ * import { startElementPicker } from '@veo/sdk';
+ *
+ * const picker = startElementPicker({
+ *   onPick: ({ selector }) => console.log('elegido:', selector),
+ *   onCancel: () => console.log('cancelado'),
+ * });
+ * // picker.stop() para abortar manualmente.
+ * ```
+ */
+declare function startElementPicker(options: ElementPickerOptions): ElementPickerHandle;
+/** Cierra el picker activo, si lo hay. Idempotente. */
+declare function stopElementPicker(): void;
+
+/**
+ * Contrato de mensajes del puente builder (app del cliente ↔ dashboard).
+ * Ambos lados validan `event.origin` y que `token` coincida antes de actuar.
+ *
+ * Flujo:
+ *   1. El dashboard abre la app con `?veoBuilder=<token>&veoBuilderOrigin=<origen>`.
+ *   2. La app (veo-builder.js) postea `ready` a la ventana que la abrió.
+ *   3. El dashboard manda comandos (`start-picker`, `preview`, …).
+ *   4. La app responde con eventos (`picked`, `pick-cancelled`, …).
+ */
+
+/** Eventos que la app del cliente envía al dashboard. */
+type BuilderEvent = {
+    type: 'ready';
+} | {
+    type: 'picked';
+    payload: PickedElement;
+} | {
+    type: 'pick-cancelled';
+} | {
+    type: 'closed';
+};
+/** Comandos que el dashboard envía a la app del cliente. */
+type BuilderCommand = {
+    type: 'start-picker';
+    maxAncestors?: number;
+    hint?: string;
+} | {
+    type: 'stop-picker';
+} | {
+    type: 'preview';
+    guide: PreviewGuideInput;
+} | {
+    type: 'close-preview';
+} | {
+    type: 'teardown';
+};
+
+interface BuilderModeHandle {
+    /** Desconecta el puente y limpia picker/preview. */
+    teardown(): void;
+}
+/**
+ * Inicializa el modo builder si la URL trae el token. Devuelve un handle, o
+ * `null` si no estamos en modo builder (uso normal de la app) o no hay un
+ * canal con el dashboard. Es seguro llamarla siempre.
+ */
+declare function initBuilderMode(): BuilderModeHandle | null;
+
+interface BuilderSessionOptions {
+    /** URL de la app del cliente a abrir en modo builder. */
+    appUrl: string;
+    /** Token de la sesión (idealmente emitido/firmado por el backend). */
+    token: string;
+    /** Origen al que la app debe responder. Default: `location.origin`. */
+    dashboardOrigin?: string;
+    /** La app está lista y escuchando comandos. */
+    onReady?: () => void;
+    /** El usuario eligió un elemento. */
+    onPicked?: (picked: PickedElement) => void;
+    /** El usuario canceló la selección (Esc). */
+    onCancelled?: () => void;
+    /** La app cerró el modo builder (o el popup se cerró). */
+    onClosed?: () => void;
+    /**
+     * Si se pasa, la app se embebe en este `<iframe>` (modo estudio in-app) en
+     * lugar de abrirse en un popup. El lado app ya habla con `window.parent`,
+     * así que el puente funciona igual. La sesión setea el `src` del iframe.
+     */
+    frame?: HTMLIFrameElement;
+    /** Nombre de la ventana popup. Default: `veo-builder`. */
+    windowName?: string;
+    /** Features del popup. Default: ventana de ~1280×860. */
+    windowFeatures?: string;
+}
+interface BuilderSession {
+    /** Pide a la app que entre en modo selección de elemento. */
+    startPicker(options?: {
+        maxAncestors?: number;
+        hint?: string;
+    }): void;
+    /** Cancela la selección en curso. */
+    stopPicker(): void;
+    /** Pide a la app que previsualice una guía. */
+    preview(guide: PreviewGuideInput): void;
+    /** Cierra la preview activa en la app. */
+    closePreview(): void;
+    /** Cierra el popup y desconecta el puente. */
+    close(): void;
+}
+declare function createBuilderSession(options: BuilderSessionOptions): BuilderSession;
+
+export { type BuilderCommand, type BuilderEvent, type BuilderModeHandle, type BuilderSession, type BuilderSessionOptions, type ElementPickerHandle, type ElementPickerOptions, type PickedElement, PreviewGuideInput, createBuilderSession, initBuilderMode, startElementPicker, stopElementPicker };

package/dist/builder.mjs

@@ -0,0 +1,449 @@
+import { hasWindow, hasDocument, closeGuidePreview, previewGuide, buildSelectorPath, filterHumanClasses } from './chunk-BBAA5BRS.mjs';
+export { closeGuidePreview, previewGuide } from './chunk-BBAA5BRS.mjs';
+
+// src/plugins/builder/bridge-protocol.ts
+var VEO_BUILDER_SOURCE = "veo-builder";
+var BUILDER_TOKEN_PARAM = "veoBuilder";
+var BUILDER_ORIGIN_PARAM = "veoBuilderOrigin";
+
+// src/plugins/builder/element-picker.ts
+var PICKER_Z = 2147483646;
+var PICKER_HOST_ATTR = "data-veo-picker";
+var DEFAULT_MAX_ANCESTORS = 5;
+var PICKER_STYLES = `
+:host { all: initial; }
+.veo-pick-box {
+  position: fixed;
+  z-index: ${PICKER_Z};
+  pointer-events: none;
+  box-sizing: border-box;
+  background: rgba(99, 102, 241, 0.22);
+  border: 1px dashed rgba(99, 102, 241, 0.95);
+  border-radius: 2px;
+  transition: top 60ms ease-out, left 60ms ease-out, width 60ms ease-out, height 60ms ease-out;
+}
+.veo-pick-label {
+  position: fixed;
+  z-index: ${PICKER_Z};
+  pointer-events: none;
+  max-width: 360px;
+  background: #1e1b4b;
+  color: #e0e7ff;
+  font: 12px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
+  padding: 6px 9px;
+  border-radius: 6px;
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.35);
+}
+.veo-pick-label .veo-pick-sel { color: #c7d2fe; word-break: break-all; }
+.veo-pick-label .veo-pick-dim { color: #a5b4fc; margin-top: 3px; }
+.veo-pick-hint {
+  position: fixed;
+  top: 12px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: ${PICKER_Z};
+  pointer-events: none;
+  background: #4338ca;
+  color: #fff;
+  font: 13px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  padding: 8px 14px;
+  border-radius: 999px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+}
+`;
+var ElementPicker = class {
+  constructor() {
+    this.host = null;
+    this.box = null;
+    this.label = null;
+    this.current = null;
+    this.maxAncestors = DEFAULT_MAX_ANCESTORS;
+    this.onPick = null;
+    this.onCancel = null;
+    this.onMove = (event) => {
+      const target = event.target;
+      if (!(target instanceof Element) || this.isOwn(target)) return;
+      this.current = target;
+      this.draw(target);
+    };
+    this.onClick = (event) => {
+      const target = this.current ?? (event.target instanceof Element ? event.target : null);
+      if (!target || this.isOwn(target)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      event.stopImmediatePropagation();
+      const picked = this.describe(target);
+      const cb = this.onPick;
+      this.stop();
+      cb?.(picked);
+    };
+    this.onKey = (event) => {
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      const cb = this.onCancel;
+      this.stop();
+      cb?.();
+    };
+    /** Traga mousedown/mouseup durante el picking (evita focus/active de la app). */
+    this.swallow = (event) => {
+      if (this.isOwn(event.target)) return;
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    this.reposition = () => {
+      if (this.current) this.draw(this.current);
+    };
+  }
+  start(options) {
+    this.stop();
+    this.maxAncestors = options.maxAncestors ?? DEFAULT_MAX_ANCESTORS;
+    this.onPick = options.onPick;
+    this.onCancel = options.onCancel ?? null;
+    const host = document.createElement("div");
+    host.setAttribute(PICKER_HOST_ATTR, "");
+    const shadow = host.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = PICKER_STYLES;
+    this.box = document.createElement("div");
+    this.box.className = "veo-pick-box";
+    this.box.style.display = "none";
+    this.label = document.createElement("div");
+    this.label.className = "veo-pick-label";
+    this.label.style.display = "none";
+    const hint = document.createElement("div");
+    hint.className = "veo-pick-hint";
+    hint.textContent = options.hint ?? "Seleccion\xE1 un elemento \xB7 Esc para cancelar";
+    shadow.append(style, this.box, this.label, hint);
+    document.body.appendChild(host);
+    this.host = host;
+    document.addEventListener("mousemove", this.onMove, true);
+    document.addEventListener("click", this.onClick, true);
+    document.addEventListener("mousedown", this.swallow, true);
+    document.addEventListener("mouseup", this.swallow, true);
+    document.addEventListener("keydown", this.onKey, true);
+    window.addEventListener("scroll", this.reposition, true);
+    window.addEventListener("resize", this.reposition);
+  }
+  stop() {
+    document.removeEventListener("mousemove", this.onMove, true);
+    document.removeEventListener("click", this.onClick, true);
+    document.removeEventListener("mousedown", this.swallow, true);
+    document.removeEventListener("mouseup", this.swallow, true);
+    document.removeEventListener("keydown", this.onKey, true);
+    window.removeEventListener("scroll", this.reposition, true);
+    window.removeEventListener("resize", this.reposition);
+    if (this.host?.parentNode) this.host.parentNode.removeChild(this.host);
+    this.host = null;
+    this.box = null;
+    this.label = null;
+    this.current = null;
+    this.onPick = null;
+    this.onCancel = null;
+  }
+  /** ¿Es un nodo de nuestro propio overlay? (no debe ser seleccionable). */
+  isOwn(target) {
+    return target instanceof Node && this.host !== null && this.host.contains(target);
+  }
+  /** Dibuja el recuadro de resalte y la etiqueta sobre el elemento dado. */
+  draw(element) {
+    if (!this.box || !this.label) return;
+    const rect = element.getBoundingClientRect();
+    this.box.style.display = "block";
+    this.box.style.top = `${rect.top}px`;
+    this.box.style.left = `${rect.left}px`;
+    this.box.style.width = `${rect.width}px`;
+    this.box.style.height = `${rect.height}px`;
+    const shortSel = buildSelectorPath(element, 0);
+    this.label.textContent = "";
+    const sel = document.createElement("div");
+    sel.className = "veo-pick-sel";
+    sel.textContent = shortSel;
+    const dim = document.createElement("div");
+    dim.className = "veo-pick-dim";
+    dim.textContent = `${Math.round(rect.width)} \xD7 ${Math.round(rect.height)}`;
+    this.label.append(sel, dim);
+    this.label.style.display = "block";
+    const LABEL_H = 48;
+    const placeAbove = rect.bottom + 8 + LABEL_H > window.innerHeight;
+    this.label.style.top = placeAbove ? `${Math.max(8, rect.top - LABEL_H - 8)}px` : `${rect.bottom + 8}px`;
+    this.label.style.left = `${Math.max(8, rect.left)}px`;
+  }
+  describe(element) {
+    const rect = element.getBoundingClientRect();
+    return {
+      selector: buildSelectorPath(element, this.maxAncestors),
+      shortSelector: buildSelectorPath(element, 0),
+      tag: element.tagName.toLowerCase(),
+      id: element.id || null,
+      classes: filterHumanClasses(element),
+      text: (element.textContent ?? "").trim().slice(0, 120),
+      rect: {
+        x: Math.round(rect.left),
+        y: Math.round(rect.top),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height)
+      }
+    };
+  }
+};
+var activePicker = null;
+function startElementPicker(options) {
+  if (!hasDocument()) {
+    return { stop: () => {
+    } };
+  }
+  if (!activePicker) activePicker = new ElementPicker();
+  activePicker.start(options);
+  return { stop: () => activePicker?.stop() };
+}
+function stopElementPicker() {
+  activePicker?.stop();
+}
+
+// src/plugins/builder/builder-mode.ts
+function initBuilderMode() {
+  if (!hasWindow() || !hasDocument()) return null;
+  let params;
+  try {
+    params = new URLSearchParams(window.location.search);
+  } catch {
+    return null;
+  }
+  const token = params.get(BUILDER_TOKEN_PARAM);
+  if (!token) return null;
+  const dashboardOrigin = resolveDashboardOrigin(params);
+  if (!dashboardOrigin) return null;
+  const target = resolveTarget();
+  if (!target) return null;
+  let picker = null;
+  const post = (event) => {
+    target.postMessage({ source: VEO_BUILDER_SOURCE, token, ...event }, dashboardOrigin);
+  };
+  const handleCommand = (cmd) => {
+    switch (cmd.type) {
+      case "start-picker":
+        picker?.stop();
+        picker = startElementPicker({
+          onPick: (payload) => {
+            picker = null;
+            post({ type: "picked", payload });
+          },
+          onCancel: () => {
+            picker = null;
+            post({ type: "pick-cancelled" });
+          },
+          ...cmd.maxAncestors !== void 0 ? { maxAncestors: cmd.maxAncestors } : {},
+          ...cmd.hint !== void 0 ? { hint: cmd.hint } : {}
+        });
+        break;
+      case "stop-picker":
+        picker?.stop();
+        picker = null;
+        break;
+      case "preview":
+        if (cmd.guide) void previewGuide(cmd.guide).ready;
+        break;
+      case "close-preview":
+        closeGuidePreview();
+        break;
+      case "teardown":
+        teardown();
+        break;
+    }
+  };
+  const onMessage = (event) => {
+    if (event.origin !== dashboardOrigin) return;
+    const data = event.data;
+    if (!data || data.source !== VEO_BUILDER_SOURCE || data.token !== token) return;
+    handleCommand(data);
+  };
+  const onPageHide = () => post({ type: "closed" });
+  const teardown = () => {
+    window.removeEventListener("message", onMessage);
+    window.removeEventListener("pagehide", onPageHide);
+    picker?.stop();
+    picker = null;
+    closeGuidePreview();
+    post({ type: "closed" });
+  };
+  const activate = () => {
+    window.addEventListener("message", onMessage);
+    window.addEventListener("pagehide", onPageHide);
+    post({ type: "ready" });
+  };
+  const cfg = window.__veoBuilder;
+  if (cfg?.apiKey && cfg?.apiUrl) {
+    void verifyBuilderToken(cfg.apiUrl, cfg.apiKey, token).then((ok) => {
+      if (ok) activate();
+      else if (window.console) console.warn("[veo] token de builder inv\xE1lido \u2014 modo no activado");
+    });
+  } else {
+    activate();
+  }
+  return { teardown };
+}
+async function verifyBuilderToken(apiUrl, apiKey, token) {
+  try {
+    const url = `${apiUrl.replace(/\/+$/, "")}/v1/builder/verify`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Api-Key": apiKey },
+      body: JSON.stringify({ token })
+    });
+    if (!res.ok) return true;
+    const data = await res.json().catch(() => null);
+    return data?.valid !== false;
+  } catch {
+    return true;
+  }
+}
+function resolveTarget() {
+  if (window.opener && window.opener !== window) return window.opener;
+  if (window.parent && window.parent !== window) return window.parent;
+  return null;
+}
+function resolveDashboardOrigin(params) {
+  const explicit = params.get(BUILDER_ORIGIN_PARAM);
+  if (explicit) {
+    try {
+      return new URL(explicit).origin;
+    } catch {
+      return null;
+    }
+  }
+  if (document.referrer) {
+    try {
+      return new URL(document.referrer).origin;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// src/plugins/builder/builder-session.ts
+var DEFAULT_FEATURES = "popup,width=1280,height=860";
+var POPUP_POLL_MS = 600;
+function createBuilderSession(options) {
+  if (!hasWindow()) return noopSession();
+  const dashboardOrigin = options.dashboardOrigin ?? window.location.origin;
+  const appOrigin = safeOrigin(options.appUrl);
+  const url = buildAppUrl(options.appUrl, options.token, dashboardOrigin);
+  const frame = options.frame ?? null;
+  const useFrame = frame !== null;
+  let popup = null;
+  if (useFrame) {
+    frame.src = url;
+  } else {
+    popup = window.open(
+      url,
+      options.windowName ?? "veo-builder",
+      options.windowFeatures ?? DEFAULT_FEATURES
+    );
+  }
+  const targetWindow = () => useFrame ? frame?.contentWindow ?? null : popup;
+  const post = (command) => {
+    const w = targetWindow();
+    if (!w) return;
+    if (!useFrame && popup?.closed) return;
+    w.postMessage(
+      { source: VEO_BUILDER_SOURCE, token: options.token, ...command },
+      appOrigin ?? "*"
+    );
+  };
+  let pollTimer;
+  const cleanup = () => {
+    window.removeEventListener("message", onMessage);
+    if (pollTimer !== void 0) {
+      clearInterval(pollTimer);
+      pollTimer = void 0;
+    }
+  };
+  const onMessage = (event) => {
+    if (appOrigin && event.origin !== appOrigin) return;
+    const data = event.data;
+    if (!data || data.source !== VEO_BUILDER_SOURCE || data.token !== options.token) return;
+    switch (data.type) {
+      case "ready":
+        options.onReady?.();
+        break;
+      case "picked":
+        if (data.payload) options.onPicked?.(data.payload);
+        break;
+      case "pick-cancelled":
+        options.onCancelled?.();
+        break;
+      case "closed":
+        cleanup();
+        options.onClosed?.();
+        break;
+    }
+  };
+  window.addEventListener("message", onMessage);
+  if (!useFrame) {
+    pollTimer = setInterval(() => {
+      if (popup?.closed) {
+        cleanup();
+        options.onClosed?.();
+      }
+    }, POPUP_POLL_MS);
+  }
+  return {
+    startPicker: (o) => post({
+      type: "start-picker",
+      ...o?.maxAncestors !== void 0 ? { maxAncestors: o.maxAncestors } : {},
+      ...o?.hint !== void 0 ? { hint: o.hint } : {}
+    }),
+    stopPicker: () => post({ type: "stop-picker" }),
+    preview: (guide) => post({ type: "preview", guide }),
+    closePreview: () => post({ type: "close-preview" }),
+    close: () => {
+      post({ type: "teardown" });
+      if (useFrame) {
+        if (frame) frame.src = "about:blank";
+      } else if (popup && !popup.closed) {
+        popup.close();
+      }
+      cleanup();
+    }
+  };
+}
+function buildAppUrl(appUrl, token, dashboardOrigin) {
+  try {
+    const u = new URL(appUrl, window.location.href);
+    u.searchParams.set(BUILDER_TOKEN_PARAM, token);
+    u.searchParams.set(BUILDER_ORIGIN_PARAM, dashboardOrigin);
+    return u.toString();
+  } catch {
+    return appUrl;
+  }
+}
+function safeOrigin(url) {
+  try {
+    return new URL(url, window.location.href).origin;
+  } catch {
+    return null;
+  }
+}
+function noopSession() {
+  return {
+    startPicker: () => {
+    },
+    stopPicker: () => {
+    },
+    preview: () => {
+    },
+    closePreview: () => {
+    },
+    close: () => {
+    }
+  };
+}
+
+// src/builder.ts
+initBuilderMode();
+
+export { createBuilderSession, initBuilderMode, startElementPicker, stopElementPicker };
+//# sourceMappingURL=builder.mjs.map
+//# sourceMappingURL=builder.mjs.map