veo-sdk 0.2.1 → 0.3.0

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-UEGKG2UR.mjs

@@ -0,0 +1,5 @@
+export { createBuilderSession, initBuilderMode, startElementPicker, stopElementPicker } from './chunk-66UQ474G.mjs';
+import './chunk-CI7NWEH2.mjs';
+import './chunk-JIU5JLI3.mjs';
+//# sourceMappingURL=builder-UEGKG2UR.mjs.map
+//# sourceMappingURL=builder-UEGKG2UR.mjs.map

package/dist/builder-UEGKG2UR.mjs.map

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

package/dist/builder.cjs

@@ -10,6 +10,67 @@ function hasDocument() {
   return typeof document !== "undefined";
 }
 
+// src/core/builder-constants.ts
+var BUILDER_TOKEN_PARAM = "veoBuilder";
+var BUILDER_ORIGIN_PARAM = "veoBuilderOrigin";
+
+// src/core/builder-token.ts
+var TOKEN_KEY = "veo:builder_token";
+var ORIGIN_KEY = "veo:builder_origin";
+function session() {
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function urlParams() {
+  try {
+    return new URLSearchParams(window.location.search);
+  } catch {
+    return null;
+  }
+}
+function resolveBuilderToken() {
+  if (!hasWindow()) return null;
+  const params = urlParams();
+  const fromUrl = params?.get(BUILDER_TOKEN_PARAM);
+  if (fromUrl) {
+    const store = session();
+    try {
+      store?.setItem(TOKEN_KEY, fromUrl);
+      const origin = params?.get(BUILDER_ORIGIN_PARAM);
+      if (origin) store?.setItem(ORIGIN_KEY, origin);
+    } catch {
+    }
+    return fromUrl;
+  }
+  try {
+    return session()?.getItem(TOKEN_KEY) ?? null;
+  } catch {
+    return null;
+  }
+}
+function resolveBuilderOrigin() {
+  if (!hasWindow()) return null;
+  const fromUrl = urlParams()?.get(BUILDER_ORIGIN_PARAM);
+  if (fromUrl) return fromUrl;
+  try {
+    return session()?.getItem(ORIGIN_KEY) ?? null;
+  } catch {
+    return null;
+  }
+}
+function clearBuilderToken() {
+  if (!hasWindow()) return;
+  try {
+    const store = session();
+    store?.removeItem(TOKEN_KEY);
+    store?.removeItem(ORIGIN_KEY);
+  } catch {
+  }
+}
+
 // src/plugins/guides/constants.ts
 var GUIDE_Z_INDEX = 2147483640;
 var DEFAULT_ANCHOR_WAIT_MS = 5e3;
@@ -1535,8 +1596,6 @@ 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/autocapture/constants.ts
 var HASHED_CLASS_PATTERNS = [
@@ -1822,15 +1881,9 @@ 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);
+  const token = resolveBuilderToken();
   if (!token) return null;
-  const dashboardOrigin = resolveDashboardOrigin(params);
+  const dashboardOrigin = resolveDashboardOrigin();
   if (!dashboardOrigin) return null;
   const target = resolveTarget();
   if (!target) return null;
@@ -1883,6 +1936,7 @@ function initBuilderMode() {
     picker?.stop();
     picker = null;
     closeGuidePreview();
+    clearBuilderToken();
     post({ type: "closed" });
   };
   const activate = () => {
@@ -1921,16 +1975,16 @@ 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() {
+  const stored = resolveBuilderOrigin();
+  if (stored) {
     try {
-      return new URL(explicit).origin;
+      return new URL(stored).origin;
     } catch {
       return null;
     }
   }
-  if (document.referrer) {
+  if (hasDocument() && document.referrer) {
     try {
       return new URL(document.referrer).origin;
     } catch {