veo-sdk 0.2.1 → 0.3.2

package/README.md

@@ -50,6 +50,42 @@ Cargá `veo.js` desde unpkg y llamá `init` en el `onload` del `<script>`
 para no romperte con un release futuro. También por jsDelivr:
 `https://cdn.jsdelivr.net/npm/veo-sdk@0.2.1/dist/veo.js`.
 
+## Editor visual de guías (modo builder)
+
+El dashboard de Veo puede abrir tu app en un editor visual para diseñar guías
+sobre ella (elegir el elemento ancla, previsualizar). Para eso abre tu app en un
+`<iframe>` con `?veoBuilder=<token>` y necesita cargar el bundle del builder
+(`veo-builder.js`) para hacer el handshake. Solo se descarga cuando la URL trae
+ese token: **tus usuarios finales nunca lo cargan**.
+
+### CDN (`<script>`)
+
+Funciona sin configurar nada: el SDK deriva la URL de `veo-builder.js` a partir
+del `<script>` que cargó `veo.js`.
+
+### Bundler (Next / Vite / React)
+
+Funciona sin configurar nada: con `init({ guides: true })` el SDK carga el
+builder con un `import()` dinámico cuando la app se abre con `?veoBuilder`. Tu
+bundler lo code-splitea, así que **no se descarga para tus usuarios finales** y
+**no tenés que copiar `veo-builder.js` ni setear `builderUrl`**.
+
+```ts
+init({ apiKey: 'pk_xxx', guides: true });
+```
+
+> `builderUrl` sigue disponible como override manual (CDN propio, CSP estricto),
+> pero ya no hace falta.
+
+### App con login (Supabase, Clerk, …)
+
+Si tu app tiene login, el editor no puede autenticarse dentro del iframe (Google
+OAuth = 403, cookies de terceros). Para diseñar sobre páginas protegidas hace
+falta un **"modo diseño"** en tu app: dejar que Veo la embeba + entrar como
+usuario demo. El SDK trae los helpers (`veoBuilderProxy`, `ensureVeoDesignSession`
+en `veo-sdk/next`) y la **receta completa con Supabase** (2 archivos, copiable)
+está en **[`docs/integrations/visual-editor-embed.md`](./docs/integrations/visual-editor-embed.md)**.
+
 ## API
 
 (En desarrollo. Implementación completa en sprints siguientes.)

package/dist/builder-AGIBF67L.mjs

@@ -0,0 +1,5 @@
+export { createBuilderSession, initBuilderMode, startElementPicker, stopElementPicker } from './chunk-7FVIFPGF.mjs';
+import './chunk-GHP7ZJCW.mjs';
+import './chunk-PTG3BTJE.mjs';
+//# sourceMappingURL=builder-AGIBF67L.mjs.map
+//# sourceMappingURL=builder-AGIBF67L.mjs.map

package/dist/builder-AGIBF67L.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"builder-AGIBF67L.mjs"}

package/dist/builder.cjs

@@ -10,6 +10,62 @@ function hasDocument() {
   return typeof document !== "undefined";
 }
 
+// src/core/builder-constants.ts
+var BUILDER_TOKEN_PARAM = "veoBuilder";
+var BUILDER_ORIGIN_PARAM = "veoBuilderOrigin";
+var BUILDER_PANEL_PARAM = "veoBuilderPanel";
+var BUILDER_PANEL_PATH_PARAM = "veoBuilderPanelPath";
+var BUILDER_GUIDE_PARAM = "veoGuide";
+
+// src/core/builder-token.ts
+var CTX_KEY = "veo:builder_ctx";
+function session() {
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function urlParams() {
+  try {
+    return new URLSearchParams(window.location.search);
+  } catch {
+    return null;
+  }
+}
+function resolveBuilderContext() {
+  if (!hasWindow()) return null;
+  const params = urlParams();
+  const fromUrl = params?.get(BUILDER_TOKEN_PARAM);
+  if (fromUrl) {
+    const ctx = {
+      token: fromUrl,
+      origin: params?.get(BUILDER_ORIGIN_PARAM) ?? null,
+      panel: params?.get(BUILDER_PANEL_PARAM) === "1",
+      guide: params?.get(BUILDER_GUIDE_PARAM) ?? null,
+      panelPath: params?.get(BUILDER_PANEL_PATH_PARAM) ?? null
+    };
+    try {
+      session()?.setItem(CTX_KEY, JSON.stringify(ctx));
+    } catch {
+    }
+    return ctx;
+  }
+  try {
+    const raw = session()?.getItem(CTX_KEY);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+function clearBuilderToken() {
+  if (!hasWindow()) return;
+  try {
+    session()?.removeItem(CTX_KEY);
+  } catch {
+  }
+}
+
 // src/plugins/guides/constants.ts
 var GUIDE_Z_INDEX = 2147483640;
 var DEFAULT_ANCHOR_WAIT_MS = 5e3;
@@ -1535,8 +1591,79 @@ function safeDestroy(renderer) {
 
 // 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/builder-panel.ts
+var DEFAULT_PANEL_PATH = "/guides/design";
+function injectBuilderPanel(opts) {
+  if (!hasWindow() || !hasDocument()) {
+    return { target: () => null, teardown: () => {
+    } };
+  }
+  const host = document.createElement("div");
+  host.setAttribute("data-veo-builder-panel", "");
+  const shadow = host.attachShadow({ mode: "open" });
+  const style = document.createElement("style");
+  style.textContent = PANEL_CSS;
+  const container = document.createElement("div");
+  container.className = "veo-panel";
+  const header = document.createElement("div");
+  header.className = "veo-panel-header";
+  const title = document.createElement("span");
+  title.className = "veo-panel-title";
+  title.textContent = "Veo \xB7 Editor";
+  const close = document.createElement("button");
+  close.className = "veo-panel-close";
+  close.type = "button";
+  close.setAttribute("aria-label", "Cerrar");
+  close.textContent = "\u2715";
+  close.addEventListener("click", () => opts.onClose());
+  header.append(title, close);
+  const iframe = document.createElement("iframe");
+  iframe.className = "veo-panel-frame";
+  iframe.title = "Editor de Veo";
+  iframe.src = buildPanelUrl(opts);
+  container.append(header, iframe);
+  shadow.append(style, container);
+  document.body.appendChild(host);
+  return {
+    target: () => iframe.contentWindow,
+    teardown: () => host.remove()
+  };
+}
+function buildPanelUrl(opts) {
+  const path = opts.panelPath ?? DEFAULT_PANEL_PATH;
+  const url = new URL(path, opts.dashboardOrigin);
+  url.searchParams.set("veoToken", opts.token);
+  url.searchParams.set("veoApp", opts.appOrigin);
+  if (opts.guide) url.searchParams.set("veoGuide", opts.guide);
+  return url.toString();
+}
+var PANEL_CSS = `
+:host { all: initial; }
+.veo-panel {
+  position: fixed; top: 0; right: 0; bottom: 0;
+  width: 420px; max-width: 100vw;
+  display: flex; flex-direction: column;
+  background: #fff;
+  box-shadow: -8px 0 30px rgba(0,0,0,0.18);
+  z-index: 2147483647;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+.veo-panel-header {
+  flex: 0 0 auto;
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 8px 12px;
+  background: #0f172a; color: #fff;
+  font-size: 13px; font-weight: 600;
+}
+.veo-panel-close {
+  border: 0; background: transparent; color: #fff;
+  font-size: 15px; cursor: pointer; line-height: 1;
+  padding: 4px 6px; border-radius: 6px;
+}
+.veo-panel-close:hover { background: rgba(255,255,255,0.15); }
+.veo-panel-frame { flex: 1 1 auto; width: 100%; border: 0; background: #fff; }
+`;
 
 // src/plugins/autocapture/constants.ts
 var HASHED_CLASS_PATTERNS = [
@@ -1822,24 +1949,23 @@ function stopElementPicker() {
 // 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);
+  const ctx = resolveBuilderContext();
+  if (!ctx) return null;
+  const token = ctx.token;
+  const dashboardOrigin = resolveDashboardOrigin(ctx.origin);
   if (!dashboardOrigin) return null;
-  const target = resolveTarget();
-  if (!target) return null;
   let picker = null;
+  let panel = null;
+  let staticTarget = null;
+  const getTarget = () => panel ? panel.target() : staticTarget;
   const post = (event) => {
-    target.postMessage({ source: VEO_BUILDER_SOURCE, token, ...event }, dashboardOrigin);
+    getTarget()?.postMessage({ source: VEO_BUILDER_SOURCE, token, ...event }, dashboardOrigin);
   };
   const handleCommand = (cmd) => {
     switch (cmd.type) {
+      case "panel-ready":
+        post({ type: "ready" });
+        break;
       case "start-picker":
         picker?.stop();
         picker = startElementPicker({
@@ -1884,11 +2010,27 @@ function initBuilderMode() {
     picker = null;
     closeGuidePreview();
     post({ type: "closed" });
+    panel?.teardown();
+    panel = null;
+    clearBuilderToken();
   };
+  if (ctx.panel) {
+    panel = injectBuilderPanel({
+      dashboardOrigin,
+      token,
+      appOrigin: window.location.origin,
+      guide: ctx.guide,
+      panelPath: ctx.panelPath,
+      onClose: () => teardown()
+    });
+  } else {
+    staticTarget = resolveTarget();
+    if (!staticTarget) return null;
+  }
   const activate = () => {
     window.addEventListener("message", onMessage);
     window.addEventListener("pagehide", onPageHide);
-    post({ type: "ready" });
+    if (!ctx.panel) post({ type: "ready" });
   };
   const cfg = window.__veoBuilder;
   if (cfg?.apiKey && cfg?.apiUrl) {
@@ -1921,16 +2063,15 @@ function resolveTarget() {
   if (window.parent && window.parent !== window) return window.parent;
   return null;
 }
-function resolveDashboardOrigin(params) {
-  const explicit = params.get(BUILDER_ORIGIN_PARAM);
-  if (explicit) {
+function resolveDashboardOrigin(originHint) {
+  if (originHint) {
     try {
-      return new URL(explicit).origin;
+      return new URL(originHint).origin;
     } catch {
       return null;
     }
   }
-  if (document.referrer) {
+  if (hasDocument() && document.referrer) {
     try {
       return new URL(document.referrer).origin;
     } catch {