veo-sdk 0.3.16 → 0.4.1

package/dist/builder.cjs

@@ -20,7 +20,7 @@ var BUILDER_GUIDE_PARAM = "veoGuide";
 // src/core/builder-token.ts
 var CTX_KEY = "veo:builder_ctx";
 var LS_PREFIX = "veo:builder_ctx:";
-var PERSIST_TTL_MS = 12 * 60 * 60 * 1e3;
+var PERSIST_TTL_MS = 30 * 60 * 1e3;
 function session() {
   try {
     return window.sessionStorage;
@@ -83,7 +83,11 @@ function readFreshFromLocal() {
 }
 function urlParams() {
   try {
-    return new URLSearchParams(window.location.search);
+    const search = new URLSearchParams(window.location.search);
+    if (search.get(BUILDER_TOKEN_PARAM)) return search;
+    const hash = window.location.hash.replace(/^#/, "");
+    if (hash.includes(`${BUILDER_TOKEN_PARAM}=`)) return new URLSearchParams(hash);
+    return search;
   } catch {
     return null;
   }
@@ -142,6 +146,112 @@ var SAFE_URL_PROTOCOLS = ["http:", "https:"];
 var GUIDE_HOST_ATTR = "data-veo-guide";
 var WALKTHROUGH_STEP_SELECTOR_TIMEOUT_MS = 5e3;
 
+// src/plugins/guides/rich-text.ts
+var ALLOWED_TAGS = {
+  P: "p",
+  BR: "br",
+  STRONG: "strong",
+  B: "strong",
+  EM: "em",
+  I: "em",
+  U: "u",
+  S: "s",
+  UL: "ul",
+  OL: "ol",
+  LI: "li",
+  A: "a"
+};
+var DROP_TAGS = /* @__PURE__ */ new Set([
+  "SCRIPT",
+  "STYLE",
+  "TEMPLATE",
+  "IFRAME",
+  "OBJECT",
+  "EMBED",
+  "NOSCRIPT",
+  "TITLE",
+  "TEXTAREA",
+  "SELECT",
+  "SVG",
+  "MATH"
+]);
+var MAX_INPUT_LEN = 16 * 1024;
+var MAX_DEPTH = 20;
+var MAX_NODES = 1e3;
+function renderRichText(html, doc) {
+  const fragment = doc.createDocumentFragment();
+  if (typeof html !== "string" || html.length === 0) return fragment;
+  let parsed;
+  try {
+    parsed = new DOMParser().parseFromString(
+      html.length > MAX_INPUT_LEN ? html.slice(0, MAX_INPUT_LEN) : html,
+      "text/html"
+    );
+  } catch {
+    fragment.appendChild(doc.createTextNode(html));
+    return fragment;
+  }
+  const budget = { nodes: 0, exceeded: false };
+  for (const child of Array.from(parsed.body.childNodes)) {
+    const rebuilt = rebuildNode(child, doc, 0, budget);
+    if (rebuilt) fragment.appendChild(rebuilt);
+  }
+  if (budget.exceeded) {
+    const plain = doc.createDocumentFragment();
+    plain.appendChild(doc.createTextNode(parsed.body.textContent ?? ""));
+    return plain;
+  }
+  return fragment;
+}
+function rebuildNode(node, doc, depth, budget) {
+  if (budget.exceeded) return null;
+  if (++budget.nodes > MAX_NODES || depth > MAX_DEPTH) {
+    budget.exceeded = true;
+    return null;
+  }
+  if (node.nodeType === Node.TEXT_NODE) {
+    return doc.createTextNode(node.textContent ?? "");
+  }
+  if (node.nodeType !== Node.ELEMENT_NODE) return null;
+  const el = node;
+  if (DROP_TAGS.has(el.tagName)) return null;
+  const mapped = ALLOWED_TAGS[el.tagName];
+  if (!mapped) {
+    const frag = doc.createDocumentFragment();
+    for (const child of Array.from(el.childNodes)) {
+      const rebuilt2 = rebuildNode(child, doc, depth + 1, budget);
+      if (rebuilt2) frag.appendChild(rebuilt2);
+    }
+    return frag;
+  }
+  if (mapped === "a") {
+    const href = el.getAttribute("href") ?? "";
+    if (!isSafeUrl(href)) {
+      const frag = doc.createDocumentFragment();
+      for (const child of Array.from(el.childNodes)) {
+        const rebuilt2 = rebuildNode(child, doc, depth + 1, budget);
+        if (rebuilt2) frag.appendChild(rebuilt2);
+      }
+      return frag;
+    }
+    const a = doc.createElement("a");
+    a.setAttribute("href", href);
+    a.setAttribute("target", "_blank");
+    a.setAttribute("rel", "noopener noreferrer nofollow");
+    for (const child of Array.from(el.childNodes)) {
+      const rebuilt2 = rebuildNode(child, doc, depth + 1, budget);
+      if (rebuilt2) a.appendChild(rebuilt2);
+    }
+    return a;
+  }
+  const rebuilt = doc.createElement(mapped);
+  for (const child of Array.from(el.childNodes)) {
+    const childNode = rebuildNode(child, doc, depth + 1, budget);
+    if (childNode) rebuilt.appendChild(childNode);
+  }
+  return rebuilt;
+}
+
 // src/plugins/guides/block-builder.ts
 function buildStepContent(step, doc, callbacks) {
   const container = doc.createElement("div");
@@ -236,9 +346,13 @@ function buildContentBlock(block, doc) {
       return el;
     }
     case "text": {
-      const el = doc.createElement("p");
+      const el = doc.createElement("div");
       el.className = "veo-guide-text";
-      el.textContent = typeof block.text === "string" ? block.text : "";
+      if (typeof block.html === "string" && block.html) {
+        el.appendChild(renderRichText(block.html, doc));
+      } else {
+        el.textContent = typeof block.text === "string" ? block.text : "";
+      }
       applyBlockStyle(el, block.style, "text");
       return el;
     }
@@ -264,7 +378,11 @@ function buildButtonBlock(block, doc, callbacks) {
   btn.addEventListener("click", () => {
     const action = block.action ?? "dismiss";
     const url = action === "url" && typeof block.url === "string" && isSafeUrl(block.url) ? block.url : void 0;
-    callbacks.onCtaClick(action, url);
+    const meta = {
+      ...typeof block.id === "string" && block.id ? { buttonId: block.id } : {},
+      ...typeof block.text === "string" && block.text ? { buttonText: block.text } : {}
+    };
+    callbacks.onCtaClick(action, url, Object.keys(meta).length ? meta : void 0);
   });
   return btn;
 }
@@ -279,6 +397,10 @@ function clampNum(n, min, max) {
 function applyBlockStyle(el, style, kind) {
   if (!style || typeof style !== "object") return;
   const s = style;
+  if (kind === "image" && s.bleed === true) {
+    el.classList.add("veo-guide-image--bleed");
+    return;
+  }
   const align = typeof s.align === "string" ? s.align : null;
   if (align && (align === "left" || align === "center" || align === "right")) {
     if (kind === "text") el.style.textAlign = align;
@@ -326,78 +448,6 @@ function readCtaUrl(step) {
   return isSafeUrl(candidate) ? candidate : void 0;
 }
 
-// src/plugins/guides/walkthrough-block-builder.ts
-function buildWalkthroughStepContent(step, stepIndex, totalSteps, doc, callbacks) {
-  const container = doc.createElement("div");
-  container.className = "veo-guide-content";
-  const counter = doc.createElement("div");
-  counter.className = "veo-walkthrough-counter";
-  counter.textContent = `Paso ${stepIndex + 1} de ${totalSteps}`;
-  container.appendChild(counter);
-  const progress = doc.createElement("div");
-  progress.className = "veo-walkthrough-progress";
-  for (let i = 0; i < totalSteps; i++) {
-    const dot = doc.createElement("span");
-    dot.className = "veo-walkthrough-progress-dot";
-    if (i < stepIndex) dot.classList.add("completed");
-    if (i === stepIndex) dot.classList.add("active");
-    progress.appendChild(dot);
-  }
-  container.appendChild(progress);
-  if (typeof step.imageUrl === "string" && step.imageUrl && isSafeUrl(step.imageUrl)) {
-    const img = doc.createElement("img");
-    img.className = "veo-guide-image";
-    img.src = step.imageUrl;
-    img.alt = typeof step.title === "string" ? step.title : "";
-    container.appendChild(img);
-  }
-  if (typeof step.title === "string" && step.title) {
-    const heading = doc.createElement("h2");
-    heading.className = "veo-guide-title";
-    heading.textContent = step.title;
-    container.appendChild(heading);
-  }
-  if (typeof step.content === "string" && step.content) {
-    const paragraph = doc.createElement("p");
-    paragraph.className = "veo-guide-text";
-    paragraph.textContent = step.content;
-    container.appendChild(paragraph);
-  }
-  const actions = doc.createElement("div");
-  actions.className = "veo-walkthrough-actions";
-  const skipBtn = doc.createElement("button");
-  skipBtn.type = "button";
-  skipBtn.className = "veo-walkthrough-skip";
-  skipBtn.textContent = "Omitir";
-  skipBtn.addEventListener("click", () => callbacks.onSkip());
-  actions.appendChild(skipBtn);
-  const rightGroup = doc.createElement("div");
-  rightGroup.className = "veo-walkthrough-actions-right";
-  if (stepIndex > 0) {
-    const backBtn = doc.createElement("button");
-    backBtn.type = "button";
-    backBtn.className = "veo-walkthrough-btn-secondary";
-    backBtn.textContent = "Atr\xE1s";
-    backBtn.addEventListener("click", () => callbacks.onBack());
-    rightGroup.appendChild(backBtn);
-  }
-  const isLastStep = stepIndex === totalSteps - 1;
-  const primaryBtn = doc.createElement("button");
-  primaryBtn.type = "button";
-  primaryBtn.className = "veo-guide-cta";
-  const defaultLabel = isLastStep ? "Finalizar" : "Siguiente";
-  primaryBtn.textContent = typeof step.ctaText === "string" && step.ctaText ? step.ctaText : defaultLabel;
-  primaryBtn.addEventListener("click", () => {
-    if (isLastStep) callbacks.onComplete();
-    else callbacks.onNext();
-  });
-  rightGroup.appendChild(primaryBtn);
-  actions.appendChild(rightGroup);
-  container.appendChild(actions);
-  container.appendChild(createCloseButton(doc, () => callbacks.onSkip()));
-  return container;
-}
-
 // src/plugins/guides/guide-design.ts
 var DARK_THEME = {
   "--veo-bg": "#1f2937",
@@ -470,6 +520,9 @@ function applyDesignVars(host, style) {
   if (typeof s.width === "number" && Number.isFinite(s.width)) {
     host.style.setProperty("--veo-width", `${clamp(s.width, 220, 720)}px`);
   }
+  if (typeof s.height === "number" && Number.isFinite(s.height)) {
+    host.style.setProperty("--veo-min-h", `${clamp(s.height, 120, 900)}px`);
+  }
   if (s.align === "left" || s.align === "center" || s.align === "right") {
     host.style.setProperty("--veo-actions-justify", ALIGN_JUSTIFY[s.align]);
   }
@@ -555,6 +608,68 @@ function applyElementVars(host, prefix, raw) {
   }
 }
 
+// src/plugins/guides/inline-host.ts
+function readInlinePosition(style) {
+  const p = style?.inlinePosition;
+  return p === "before" || p === "prepend" || p === "append" ? p : "after";
+}
+function insertHost(anchor, host, position) {
+  switch (position) {
+    case "before":
+      anchor.before(host);
+      break;
+    case "after":
+      anchor.after(host);
+      break;
+    case "prepend":
+      anchor.prepend(host);
+      break;
+    case "append":
+      anchor.append(host);
+      break;
+  }
+}
+function keepHostAttached(host, selector, position) {
+  const id = window.setInterval(() => {
+    if (host.isConnected) return;
+    const anchor = document.querySelector(selector);
+    if (anchor) insertHost(anchor, host, position);
+  }, 1e3);
+  return () => window.clearInterval(id);
+}
+
+// src/plugins/guides/wait-for-element.ts
+function waitForElement(selector, timeoutMs = DEFAULT_ANCHOR_WAIT_MS) {
+  return new Promise((resolve) => {
+    const safeQuery = () => {
+      try {
+        return document.querySelector(selector);
+      } catch {
+        return null;
+      }
+    };
+    const existing = safeQuery();
+    if (existing) {
+      resolve(existing);
+      return;
+    }
+    let resolved = false;
+    const finish = (el) => {
+      if (resolved) return;
+      resolved = true;
+      observer.disconnect();
+      clearTimeout(timer);
+      resolve(el);
+    };
+    const observer = new MutationObserver(() => {
+      const el = safeQuery();
+      if (el) finish(el);
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    const timer = setTimeout(() => finish(null), timeoutMs);
+  });
+}
+
 // src/plugins/guides/styles.ts
 var GUIDE_STYLES = `
 :host {
@@ -576,6 +691,13 @@ var GUIDE_STYLES = `
   z-index: ${GUIDE_Z_INDEX};
   animation: veo-fade-in 180ms ease-out;
 }
+/* Sin backdrop (style.backdrop === false): la app queda usable detr\xE1s; solo la
+   tarjeta captura el mouse. El click-en-backdrop deja de cerrar (no hay backdrop). */
+.veo-modal-overlay--none {
+  background: transparent;
+  pointer-events: none;
+}
+.veo-modal-overlay--none .veo-modal-card { pointer-events: auto; }
 /*
  * Posici\xF3n libre/preset: --veo-pos-x/y son porcentajes (default 50% = centro).
  * El truco translate(-pos) alinea la MISMA fracci\xF3n de la tarjeta con esa
@@ -592,6 +714,7 @@ var GUIDE_STYLES = `
   border: var(--veo-border-width, 0) solid var(--veo-border-color, transparent);
   padding: var(--veo-pad, 24px);
   max-width: var(--veo-width); width: 90%;
+  min-height: var(--veo-min-h, auto);
   box-shadow: var(--veo-shadow);
   animation: veo-fade-in 180ms ease-out;
 }
@@ -607,6 +730,14 @@ var GUIDE_STYLES = `
 }
 .veo-banner-top { top: 0; }
 .veo-banner-bottom { bottom: 0; }
+/* Banner EMBEBIDO en un contenedor (step.selector): fluye dentro del contenedor
+   y empuja su contenido, en vez de flotar fijo sobre la pantalla. */
+.veo-banner-embedded {
+  position: static;
+  left: auto; right: auto;
+  width: 100%;
+  border-radius: var(--veo-radius, 0);
+}
 
 .veo-tooltip {
   position: absolute;
@@ -660,6 +791,21 @@ var GUIDE_STYLES = `
   border-radius: var(--veo-image-radius, 8px);
   margin: var(--veo-image-mt, 0) 0 var(--veo-image-mb, 12px);
 }
+/* Imagen A SANGRE: rompe el padding de la tarjeta y ocupa el ancho completo
+   (hero estilo anuncio). Como primer bloque, hereda el redondeo superior. */
+.veo-guide-image--bleed {
+  width: calc(100% + var(--veo-pad, 24px) * 2);
+  max-width: none;
+  max-height: 280px;
+  align-self: auto;
+  border-radius: 0;
+  margin: 0 calc(var(--veo-pad, 24px) * -1) 12px;
+}
+.veo-guide-content > .veo-guide-image--bleed:first-child {
+  margin-top: calc(var(--veo-pad, 24px) * -1);
+  border-radius: calc(var(--veo-radius, 12px) - var(--veo-border-width, 0px))
+    calc(var(--veo-radius, 12px) - var(--veo-border-width, 0px)) 0 0;
+}
 .veo-guide-title {
   font-size: var(--veo-title-size, 18px); font-weight: 600; line-height: 1.3;
   text-align: var(--veo-title-align, left);
@@ -672,6 +818,18 @@ var GUIDE_STYLES = `
   margin: var(--veo-text-mt, 0) 0 var(--veo-text-mb, 16px);
   color: var(--veo-text-color, var(--veo-text-secondary));
 }
+/* Rich text dentro de un bloque de texto (p/listas/links/\xE9nfasis). */
+.veo-guide-text p { margin: 0 0 8px; }
+.veo-guide-text p:last-child { margin-bottom: 0; }
+.veo-guide-text ul, .veo-guide-text ol { margin: 0 0 8px; padding-left: 20px; }
+.veo-guide-text ul { list-style: disc; }
+.veo-guide-text ol { list-style: decimal; }
+.veo-guide-text li { margin: 2px 0; display: list-item; }
+.veo-guide-text a { color: var(--veo-primary); text-decoration: underline; cursor: pointer; }
+.veo-guide-text strong { font-weight: 600; }
+.veo-guide-text em { font-style: italic; }
+.veo-guide-text u { text-decoration: underline; }
+.veo-guide-text s { text-decoration: line-through; }
 .veo-guide-actions {
   display: flex; gap: 8px; justify-content: var(--veo-actions-justify);
 }
@@ -810,6 +968,44 @@ var GUIDE_STYLES = `
 }
 .veo-walkthrough-skip:hover { color: var(--veo-text); }
 
+/* \u2500\u2500 Badge (elemento inyectado junto al ancla que abre un tooltip) \u2500\u2500 */
+.veo-badge {
+  display: inline-flex; align-items: center; justify-content: center;
+  border: none; padding: 0; margin: 0 4px;
+  background: none; cursor: pointer;
+  line-height: 1; vertical-align: middle;
+  font-family: inherit;
+}
+.veo-badge:focus-visible { outline: 2px solid var(--veo-primary); outline-offset: 2px; }
+.veo-badge--icon {
+  border-radius: 50%;
+  background: color-mix(in srgb, var(--veo-primary) 14%, transparent);
+  color: var(--veo-primary);
+  font-weight: 600;
+}
+.veo-badge--dot {
+  border-radius: 50%;
+  background: var(--veo-primary);
+  animation: veo-badge-pulse 2s ease-out infinite;
+}
+.veo-badge--pill {
+  border-radius: 999px;
+  background: var(--veo-primary);
+  color: #fff;
+  font-weight: 600;
+  padding: 3px 9px;
+  white-space: nowrap;
+}
+.veo-badge--image img { display: block; border-radius: 4px; object-fit: cover; }
+/* El tooltip del badge usa strategy fixed (el host vive dentro del flujo del
+   cliente; un absoluto se recortar\xEDa con overflow de ancestros). */
+.veo-badge-tooltip { position: fixed; }
+@keyframes veo-badge-pulse {
+  0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--veo-primary) 45%, transparent); }
+  70% { box-shadow: 0 0 0 7px transparent; }
+  100% { box-shadow: 0 0 0 0 transparent; }
+}
+
 .veo-custom-floating {
   position: fixed;
   z-index: ${GUIDE_Z_INDEX};
@@ -905,52 +1101,412 @@ var BaseRenderer = class {
     this.shadow = shadow;
     return { host, shadow, root };
   }
-  /**
-   * Aplica la tematización por datos del step (`step.style`) como variables
-   * CSS sobre el host. Llamar tras `createHost()`. No-op si no hay host o
-   * style. Ver `guide-design.ts`.
-   */
-  applyDesign(style) {
-    if (this.host) applyDesignVars(this.host, style);
+  /**
+   * Aplica la tematización por datos del step (`step.style`) como variables
+   * CSS sobre el host. Llamar tras `createHost()`. No-op si no hay host o
+   * style. Ver `guide-design.ts`.
+   */
+  applyDesign(style) {
+    if (this.host) applyDesignVars(this.host, style);
+  }
+  /**
+   * Registra una función a ejecutar en `destroy()`. Útil para limpiar
+   * listeners globales (scroll, resize) o intervalos.
+   */
+  registerCleanup(fn) {
+    this.cleanups.push(fn);
+  }
+  /**
+   * Host de la guía montada (o `null` si aún no se montó / ya se destruyó).
+   * Lo usa el modo builder para adjuntar manipulación directa (drag/resize)
+   * sobre el shadow root abierto sin tocar los renderers.
+   */
+  hostElement() {
+    return this.host;
+  }
+  /** Remueve el host del DOM y corre todas las funciones de cleanup. */
+  destroy() {
+    for (const fn of this.cleanups) {
+      try {
+        fn();
+      } catch {
+      }
+    }
+    this.cleanups = [];
+    if (this.host?.parentNode) {
+      this.host.parentNode.removeChild(this.host);
+    }
+    this.host = null;
+    this.shadow = null;
+  }
+};
+
+// src/plugins/guides/renderers/floating-arrow.ts
+var STATIC_SIDE = {
+  top: "bottom",
+  bottom: "top",
+  left: "right",
+  right: "left"
+};
+function positionArrow(arrowEl, placement, data) {
+  const side = STATIC_SIDE[placement.split("-")[0] ?? "bottom"] ?? "top";
+  for (const prop of ["top", "bottom", "left", "right"]) {
+    arrowEl.style.setProperty(prop, "");
+  }
+  if (data?.x != null) arrowEl.style.setProperty("left", `${data.x}px`);
+  if (data?.y != null) arrowEl.style.setProperty("top", `${data.y}px`);
+  arrowEl.style.setProperty(side, "-6px");
+}
+
+// src/plugins/guides/renderers/badge-renderer.ts
+var HOVER_CLOSE_DELAY_MS = 150;
+var BadgeRenderer = class extends BaseRenderer {
+  constructor() {
+    super(...arguments);
+    this.tooltip = null;
+    this.arrowEl = null;
+    this.badgeBtn = null;
+    this.open = false;
+    this.shownEmitted = false;
+    this.trigger = "hover";
+    this.side = "top";
+    this.closeTimer = null;
+    this.stopFloat = null;
+  }
+  async render(context) {
+    const step = context.guide.guideSteps[0];
+    if (!step) return;
+    const selector = step.selector ?? context.guide.activationRules.selector;
+    if (typeof selector !== "string" || selector.length === 0) return;
+    const anchor = await waitForElement(selector);
+    if (!anchor) return;
+    const { host, root } = this.createHost();
+    const ownerDocument = root.ownerDocument ?? document;
+    this.applyDesign(step.style);
+    this.trigger = step.style?.badgeTrigger === "click" ? "click" : "hover";
+    const rawSide = step.style?.tooltipPlacement;
+    this.side = rawSide === "bottom" || rawSide === "left" || rawSide === "right" ? rawSide : "top";
+    const position = readInlinePosition(step.style);
+    host.style.display = "inline-flex";
+    host.style.verticalAlign = "middle";
+    const badge = buildBadgeElement(readBadgeConfig(step), ownerDocument);
+    root.appendChild(badge);
+    this.badgeBtn = badge;
+    insertHost(anchor, host, position);
+    this.registerCleanup(keepHostAttached(host, selector, position));
+    const tooltip = ownerDocument.createElement("div");
+    tooltip.className = "veo-tooltip veo-badge-tooltip";
+    tooltip.style.display = "none";
+    const emit = (action, meta) => {
+      context.onInteraction({
+        guideId: context.guide.guideId,
+        stepIndex: 0,
+        action,
+        ...meta ? { metadata: meta } : {}
+      });
+    };
+    const buildTooltipContent = (s) => buildStepContent(s, ownerDocument, {
+      onCtaClick: (action, url, meta) => {
+        emit("cta_clicked", meta);
+        if (action === "url" && url) window.open(url, "_blank", "noopener,noreferrer");
+        if (action === "dismiss") {
+          emit("dismissed");
+          context.onClose();
+          return;
+        }
+        this.closeTooltip();
+      },
+      onDismiss: () => {
+        emit("dismissed");
+        context.onClose();
+      }
+    });
+    const content = buildTooltipContent(step);
+    tooltip.appendChild(content);
+    const arrowEl = ownerDocument.createElement("div");
+    arrowEl.className = "veo-tooltip-arrow";
+    tooltip.appendChild(arrowEl);
+    root.appendChild(tooltip);
+    this.tooltip = tooltip;
+    this.arrowEl = arrowEl;
+    this.liveContainer = tooltip;
+    this.liveContent = content;
+    this.liveKey = this.liveKeyOf(step);
+    this.liveBuild = buildTooltipContent;
+    const openNow = () => {
+      this.cancelClose();
+      if (!this.open) {
+        this.openTooltip(badge);
+        if (!this.shownEmitted) {
+          this.shownEmitted = true;
+          emit("shown");
+        }
+      }
+    };
+    if (this.trigger === "hover") {
+      const scheduleClose = () => {
+        this.cancelClose();
+        this.closeTimer = window.setTimeout(() => this.closeTooltip(), HOVER_CLOSE_DELAY_MS);
+      };
+      badge.addEventListener("mouseenter", openNow);
+      badge.addEventListener("focus", openNow);
+      badge.addEventListener("mouseleave", scheduleClose);
+      badge.addEventListener("blur", scheduleClose);
+      tooltip.addEventListener("mouseenter", () => this.cancelClose());
+      tooltip.addEventListener("mouseleave", scheduleClose);
+    } else {
+      badge.addEventListener("click", () => {
+        if (this.open) this.closeTooltip();
+        else openNow();
+      });
+      const onDocClick = (e) => {
+        if (!this.open) return;
+        if (e.composedPath().includes(host)) return;
+        this.closeTooltip();
+      };
+      document.addEventListener("click", onDocClick, true);
+      this.registerCleanup(() => document.removeEventListener("click", onDocClick, true));
+    }
+    const onKey = (e) => {
+      if (e.key === "Escape" && this.open) this.closeTooltip();
+    };
+    document.addEventListener("keydown", onKey);
+    this.registerCleanup(() => document.removeEventListener("keydown", onKey));
+    if (context.isPreview) openNow();
+  }
+  /** Cambiar de ancla/posición/trigger requiere re-montar y re-cablear. */
+  liveKeyOf(step) {
+    const selector = step.selector ?? "";
+    const position = readInlinePosition(step.style);
+    const trigger = step.style?.badgeTrigger === "click" ? "click" : "hover";
+    return `${selector}|${position}|${trigger}`;
+  }
+  onLiveUpdate(step) {
+    if (this.badgeBtn) {
+      const doc = this.badgeBtn.ownerDocument;
+      const next = buildBadgeElement(readBadgeConfig(step), doc);
+      this.badgeBtn.className = next.className;
+      this.badgeBtn.setAttribute("style", next.getAttribute("style") ?? "");
+      this.badgeBtn.replaceChildren(...Array.from(next.childNodes));
+    }
+    const rawSide = step.style?.tooltipPlacement;
+    this.side = rawSide === "bottom" || rawSide === "left" || rawSide === "right" ? rawSide : "top";
+    if (this.open && this.badgeBtn) this.position(this.badgeBtn);
+  }
+  destroy() {
+    this.cancelClose();
+    this.stopFloat?.();
+    this.stopFloat = null;
+    this.tooltip = null;
+    this.arrowEl = null;
+    this.badgeBtn = null;
+    this.open = false;
+    super.destroy();
+  }
+  openTooltip(badge) {
+    if (!this.tooltip) return;
+    this.tooltip.style.display = "block";
+    this.open = true;
+    void this.position(badge);
+    const reposition = () => {
+      void this.position(badge);
+    };
+    window.addEventListener("scroll", reposition, true);
+    window.addEventListener("resize", reposition);
+    this.stopFloat = () => {
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition);
+    };
+  }
+  closeTooltip() {
+    this.cancelClose();
+    if (!this.tooltip || !this.open) return;
+    this.tooltip.style.display = "none";
+    this.open = false;
+    this.stopFloat?.();
+    this.stopFloat = null;
+  }
+  cancelClose() {
+    if (this.closeTimer !== null) {
+      window.clearTimeout(this.closeTimer);
+      this.closeTimer = null;
+    }
+  }
+  async position(badge) {
+    const tooltip = this.tooltip;
+    const arrowEl = this.arrowEl;
+    if (!tooltip || !arrowEl) return;
+    const { x, y, placement, middlewareData } = await dom.computePosition(badge, tooltip, {
+      strategy: "fixed",
+      placement: this.side,
+      middleware: [dom.offset(8), dom.flip(), dom.shift({ padding: 8 }), dom.arrow({ element: arrowEl })]
+    });
+    tooltip.style.left = `${x}px`;
+    tooltip.style.top = `${y}px`;
+    positionArrow(arrowEl, placement, middlewareData.arrow);
+  }
+};
+function readBadgeConfig(step) {
+  const raw = step.style?.badge;
+  if (!raw || typeof raw !== "object") return { kind: "icon" };
+  const b = raw;
+  const kind = b.kind === "dot" || b.kind === "pill" || b.kind === "image" || b.kind === "icon" ? b.kind : "icon";
+  return {
+    kind,
+    icon: typeof b.icon === "string" ? b.icon : null,
+    text: typeof b.text === "string" ? b.text : null,
+    imageUrl: typeof b.imageUrl === "string" ? b.imageUrl : null,
+    color: typeof b.color === "string" && COLOR_RE.test(b.color.trim()) ? b.color.trim() : null,
+    size: typeof b.size === "number" && Number.isFinite(b.size) ? b.size : null
+  };
+}
+function clamp2(n, min, max) {
+  return Math.min(max, Math.max(min, n));
+}
+function buildBadgeElement(config, doc) {
+  const btn = doc.createElement("button");
+  btn.type = "button";
+  btn.className = `veo-badge veo-badge--${config.kind}`;
+  btn.setAttribute("aria-label", "M\xE1s informaci\xF3n");
+  const size = clamp2(config.size ?? 18, 8, 48);
+  switch (config.kind) {
+    case "dot":
+      btn.style.width = `${size}px`;
+      btn.style.height = `${size}px`;
+      if (config.color) btn.style.background = config.color;
+      break;
+    case "pill": {
+      btn.textContent = config.text?.slice(0, 24) || "Nuevo";
+      btn.style.fontSize = `${clamp2(Math.round(size * 0.62), 8, 24)}px`;
+      if (config.color) btn.style.background = config.color;
+      break;
+    }
+    case "image": {
+      if (config.imageUrl && isSafeUrl(config.imageUrl)) {
+        const img = doc.createElement("img");
+        img.src = config.imageUrl;
+        img.alt = "";
+        img.style.width = `${size}px`;
+        img.style.height = `${size}px`;
+        btn.appendChild(img);
+      } else {
+        btn.className = "veo-badge veo-badge--icon";
+        btn.textContent = "?";
+        btn.style.width = `${size}px`;
+        btn.style.height = `${size}px`;
+        btn.style.fontSize = `${clamp2(Math.round(size * 0.62), 8, 32)}px`;
+      }
+      break;
+    }
+    default: {
+      btn.textContent = (config.icon || "\u2139\uFE0F").slice(0, 4);
+      btn.style.width = `${size}px`;
+      btn.style.height = `${size}px`;
+      btn.style.fontSize = `${clamp2(Math.round(size * 0.62), 8, 32)}px`;
+      if (config.color) btn.style.color = config.color;
+      break;
+    }
+  }
+  return btn;
+}
+
+// src/plugins/guides/walkthrough-block-builder.ts
+function buildWalkthroughStepContent(step, stepIndex, totalSteps, doc, callbacks) {
+  const container = doc.createElement("div");
+  container.className = "veo-guide-content";
+  const counter = doc.createElement("div");
+  counter.className = "veo-walkthrough-counter";
+  counter.textContent = `Paso ${stepIndex + 1} de ${totalSteps}`;
+  container.appendChild(counter);
+  const progress = doc.createElement("div");
+  progress.className = "veo-walkthrough-progress";
+  for (let i = 0; i < totalSteps; i++) {
+    const dot = doc.createElement("span");
+    dot.className = "veo-walkthrough-progress-dot";
+    if (i < stepIndex) dot.classList.add("completed");
+    if (i === stepIndex) dot.classList.add("active");
+    progress.appendChild(dot);
+  }
+  container.appendChild(progress);
+  if (typeof step.imageUrl === "string" && step.imageUrl && isSafeUrl(step.imageUrl)) {
+    const img = doc.createElement("img");
+    img.className = "veo-guide-image";
+    img.src = step.imageUrl;
+    img.alt = typeof step.title === "string" ? step.title : "";
+    container.appendChild(img);
+  }
+  if (typeof step.title === "string" && step.title) {
+    const heading = doc.createElement("h2");
+    heading.className = "veo-guide-title";
+    heading.textContent = step.title;
+    container.appendChild(heading);
   }
-  /**
-   * Registra una función a ejecutar en `destroy()`. Útil para limpiar
-   * listeners globales (scroll, resize) o intervalos.
-   */
-  registerCleanup(fn) {
-    this.cleanups.push(fn);
+  if (typeof step.content === "string" && step.content) {
+    const paragraph = doc.createElement("p");
+    paragraph.className = "veo-guide-text";
+    paragraph.textContent = step.content;
+    container.appendChild(paragraph);
   }
-  /** Remueve el host del DOM y corre todas las funciones de cleanup. */
-  destroy() {
-    for (const fn of this.cleanups) {
-      try {
-        fn();
-      } catch {
-      }
-    }
-    this.cleanups = [];
-    if (this.host?.parentNode) {
-      this.host.parentNode.removeChild(this.host);
-    }
-    this.host = null;
-    this.shadow = null;
+  const actions = doc.createElement("div");
+  actions.className = "veo-walkthrough-actions";
+  const skipBtn = doc.createElement("button");
+  skipBtn.type = "button";
+  skipBtn.className = "veo-walkthrough-skip";
+  skipBtn.textContent = "Omitir";
+  skipBtn.addEventListener("click", () => callbacks.onSkip());
+  actions.appendChild(skipBtn);
+  const rightGroup = doc.createElement("div");
+  rightGroup.className = "veo-walkthrough-actions-right";
+  if (stepIndex > 0) {
+    const backBtn = doc.createElement("button");
+    backBtn.type = "button";
+    backBtn.className = "veo-walkthrough-btn-secondary";
+    backBtn.textContent = "Atr\xE1s";
+    backBtn.addEventListener("click", () => callbacks.onBack());
+    rightGroup.appendChild(backBtn);
   }
-};
+  const isLastStep = stepIndex === totalSteps - 1;
+  const primaryBtn = doc.createElement("button");
+  primaryBtn.type = "button";
+  primaryBtn.className = "veo-guide-cta";
+  const defaultLabel = isLastStep ? "Finalizar" : "Siguiente";
+  primaryBtn.textContent = typeof step.ctaText === "string" && step.ctaText ? step.ctaText : defaultLabel;
+  primaryBtn.addEventListener("click", () => {
+    if (isLastStep) callbacks.onComplete();
+    else callbacks.onNext();
+  });
+  rightGroup.appendChild(primaryBtn);
+  actions.appendChild(rightGroup);
+  container.appendChild(actions);
+  container.appendChild(createCloseButton(doc, () => callbacks.onSkip()));
+  return container;
+}
 
 // src/plugins/guides/renderers/banner-renderer.ts
 var BannerRenderer = class extends BaseRenderer {
-  render(context) {
+  async render(context) {
     const idx = context.nav?.stepIndex ?? 0;
     const step = context.guide.guideSteps[idx];
     if (!step) return;
-    const { root } = this.createHost();
+    const position = step.style?.position === "bottom" ? "bottom" : "top";
+    const selector = context.nav ? null : step.selector?.trim() ?? null;
+    let anchor = null;
+    if (selector) {
+      anchor = await waitForElement(selector);
+      if (!anchor) return;
+    }
+    const { host, root } = this.createHost();
     this.applyDesign(step.style);
     const ownerDocument = root.ownerDocument ?? document;
-    const position = step.style?.position === "bottom" ? "bottom" : "top";
     const banner = ownerDocument.createElement("div");
-    banner.className = `veo-banner veo-banner-${position}`;
-    const dismiss = (action, ctaUrl) => {
-      context.onInteraction({ guideId: context.guide.guideId, stepIndex: idx, action });
+    banner.className = bannerClassOf(position, Boolean(anchor));
+    const dismiss = (action, ctaUrl, meta) => {
+      context.onInteraction({
+        guideId: context.guide.guideId,
+        stepIndex: idx,
+        action,
+        ...meta ? { metadata: meta } : {}
+      });
       if (ctaUrl) window.open(ctaUrl, "_blank", "noopener,noreferrer");
       context.onClose();
     };
@@ -961,59 +1517,45 @@ var BannerRenderer = class extends BaseRenderer {
       ownerDocument,
       context.nav.callbacks
     ) : buildStepContent(step, ownerDocument, {
-      onCtaClick: (action, url) => dismiss("cta_clicked", action === "url" ? url : void 0),
+      onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
       onDismiss: () => dismiss("dismissed")
     });
     banner.appendChild(content);
     root.appendChild(banner);
+    if (selector && anchor) {
+      host.style.display = "block";
+      const insertAt = position === "top" ? "prepend" : "append";
+      insertHost(anchor, host, insertAt);
+      this.registerCleanup(keepHostAttached(host, selector, insertAt));
+    }
     if (!context.nav) {
       this.liveContainer = banner;
       this.liveContent = content;
       this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-        onCtaClick: (action, url) => dismiss("cta_clicked", action === "url" ? url : void 0),
+        onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
         onDismiss: () => dismiss("dismissed")
       });
+      this.liveKey = this.liveKeyOf(step);
       context.onInteraction({ guideId: context.guide.guideId, stepIndex: 0, action: "shown" });
     }
   }
+  /** Cambiar de contenedor o de top/bottom embebido requiere re-insertar → remontar. */
+  liveKeyOf(step) {
+    const selector = step.selector?.trim() ?? "";
+    if (!selector) return "";
+    const position = step.style?.position === "bottom" ? "bottom" : "top";
+    return `${selector}|${position}`;
+  }
   onLiveUpdate(step) {
     if (this.liveContainer) {
       const position = step.style?.position === "bottom" ? "bottom" : "top";
-      this.liveContainer.className = `veo-banner veo-banner-${position}`;
+      const embedded = Boolean(step.selector?.trim());
+      this.liveContainer.className = bannerClassOf(position, embedded);
     }
   }
 };
-
-// src/plugins/guides/wait-for-element.ts
-function waitForElement(selector, timeoutMs = DEFAULT_ANCHOR_WAIT_MS) {
-  return new Promise((resolve) => {
-    const safeQuery = () => {
-      try {
-        return document.querySelector(selector);
-      } catch {
-        return null;
-      }
-    };
-    const existing = safeQuery();
-    if (existing) {
-      resolve(existing);
-      return;
-    }
-    let resolved = false;
-    const finish = (el) => {
-      if (resolved) return;
-      resolved = true;
-      observer.disconnect();
-      clearTimeout(timer);
-      resolve(el);
-    };
-    const observer = new MutationObserver(() => {
-      const el = safeQuery();
-      if (el) finish(el);
-    });
-    observer.observe(document.body, { childList: true, subtree: true });
-    const timer = setTimeout(() => finish(null), timeoutMs);
-  });
+function bannerClassOf(position, embedded) {
+  return embedded ? "veo-banner veo-banner-embedded" : `veo-banner veo-banner-${position}`;
 }
 
 // src/utils/uuid.ts
@@ -1548,36 +2090,6 @@ var FormRenderer = class extends BaseRenderer {
   }
 };
 
-// src/plugins/guides/inline-host.ts
-function readInlinePosition(style) {
-  const p = style?.inlinePosition;
-  return p === "before" || p === "prepend" || p === "append" ? p : "after";
-}
-function insertHost(anchor, host, position) {
-  switch (position) {
-    case "before":
-      anchor.before(host);
-      break;
-    case "after":
-      anchor.after(host);
-      break;
-    case "prepend":
-      anchor.prepend(host);
-      break;
-    case "append":
-      anchor.append(host);
-      break;
-  }
-}
-function keepHostAttached(host, selector, position) {
-  const id = window.setInterval(() => {
-    if (host.isConnected) return;
-    const anchor = document.querySelector(selector);
-    if (anchor) insertHost(anchor, host, position);
-  }, 1e3);
-  return () => window.clearInterval(id);
-}
-
 // src/plugins/guides/renderers/inline-custom-renderer.ts
 var InlineCustomRenderer = class extends BaseRenderer {
   async render(context) {
@@ -1645,13 +2157,18 @@ var InlineRenderer = class extends BaseRenderer {
     const ownerDocument = root.ownerDocument ?? document;
     const card = ownerDocument.createElement("div");
     card.className = "veo-inline";
-    const dismiss = (action, ctaUrl) => {
-      context.onInteraction({ guideId: context.guide.guideId, stepIndex: 0, action });
+    const dismiss = (action, ctaUrl, meta) => {
+      context.onInteraction({
+        guideId: context.guide.guideId,
+        stepIndex: 0,
+        action,
+        ...meta ? { metadata: meta } : {}
+      });
       if (ctaUrl) window.open(ctaUrl, "_blank", "noopener,noreferrer");
       context.onClose();
     };
     const content = buildStepContent(step, ownerDocument, {
-      onCtaClick: (action, url) => dismiss("cta_clicked", action === "url" ? url : void 0),
+      onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
       onDismiss: () => dismiss("dismissed")
     });
     card.appendChild(content);
@@ -1660,7 +2177,7 @@ var InlineRenderer = class extends BaseRenderer {
     this.liveContent = content;
     this.liveKey = `${selector}|${position}`;
     this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-      onCtaClick: (action, url) => dismiss("cta_clicked", action === "url" ? url : void 0),
+      onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
       onDismiss: () => dismiss("dismissed")
     });
     context.onInteraction({ guideId: context.guide.guideId, stepIndex: 0, action: "shown" });
@@ -1671,7 +2188,14 @@ var InlineRenderer = class extends BaseRenderer {
 };
 
 // src/plugins/guides/renderers/modal-renderer.ts
+function overlayClassOf(step) {
+  return step.style?.backdrop === false ? "veo-modal-overlay veo-modal-overlay--none" : "veo-modal-overlay";
+}
 var ModalRenderer = class extends BaseRenderer {
+  constructor() {
+    super(...arguments);
+    this.overlay = null;
+  }
   render(context) {
     const idx = context.nav?.stepIndex ?? 0;
     const step = context.guide.guideSteps[idx];
@@ -1680,11 +2204,17 @@ var ModalRenderer = class extends BaseRenderer {
     this.applyDesign(step.style);
     const ownerDocument = root.ownerDocument ?? document;
     const overlay = ownerDocument.createElement("div");
-    overlay.className = "veo-modal-overlay";
+    overlay.className = overlayClassOf(step);
+    this.overlay = overlay;
     const card = ownerDocument.createElement("div");
     card.className = "veo-modal-card";
-    const dismiss = (action, ctaUrl) => {
-      context.onInteraction({ guideId: context.guide.guideId, stepIndex: idx, action });
+    const dismiss = (action, ctaUrl, meta) => {
+      context.onInteraction({
+        guideId: context.guide.guideId,
+        stepIndex: idx,
+        action,
+        ...meta ? { metadata: meta } : {}
+      });
       if (ctaUrl) window.open(ctaUrl, "_blank", "noopener,noreferrer");
       context.onClose();
     };
@@ -1699,7 +2229,7 @@ var ModalRenderer = class extends BaseRenderer {
       ownerDocument,
       context.nav.callbacks
     ) : buildStepContent(step, ownerDocument, {
-      onCtaClick: (action, url) => dismiss("cta_clicked", action === "url" ? url : void 0),
+      onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
       onDismiss: () => dismiss("dismissed")
     });
     card.appendChild(content);
@@ -1709,7 +2239,7 @@ var ModalRenderer = class extends BaseRenderer {
       this.liveContainer = card;
       this.liveContent = content;
       this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-        onCtaClick: (action, url) => dismiss("cta_clicked", action === "url" ? url : void 0),
+        onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
         onDismiss: () => dismiss("dismissed")
       });
     }
@@ -1725,26 +2255,14 @@ var ModalRenderer = class extends BaseRenderer {
       context.onInteraction({ guideId: context.guide.guideId, stepIndex: 0, action: "shown" });
     }
   }
-};
-
-// src/plugins/guides/renderers/floating-arrow.ts
-var STATIC_SIDE = {
-  top: "bottom",
-  bottom: "top",
-  left: "right",
-  right: "left"
-};
-function positionArrow(arrowEl, placement, data) {
-  const side = STATIC_SIDE[placement.split("-")[0] ?? "bottom"] ?? "top";
-  for (const prop of ["top", "bottom", "left", "right"]) {
-    arrowEl.style.setProperty(prop, "");
+  onLiveUpdate(step) {
+    if (this.overlay) this.overlay.className = overlayClassOf(step);
   }
-  if (data?.x != null) arrowEl.style.setProperty("left", `${data.x}px`);
-  if (data?.y != null) arrowEl.style.setProperty("top", `${data.y}px`);
-  arrowEl.style.setProperty(side, "-6px");
-}
-
-// src/plugins/guides/renderers/tooltip-renderer.ts
+  destroy() {
+    this.overlay = null;
+    super.destroy();
+  }
+};
 var TooltipRenderer = class extends BaseRenderer {
   constructor() {
     super(...arguments);
@@ -1766,18 +2284,19 @@ var TooltipRenderer = class extends BaseRenderer {
     const ownerDocument = root.ownerDocument ?? document;
     const tooltip = ownerDocument.createElement("div");
     tooltip.className = "veo-tooltip";
-    const dismiss = (action, ctaUrl) => {
+    const dismiss = (action, ctaUrl, meta) => {
       context.onInteraction({
         guideId: context.guide.guideId,
         stepIndex: 0,
-        action
+        action,
+        ...meta ? { metadata: meta } : {}
       });
       if (ctaUrl) window.open(ctaUrl, "_blank", "noopener,noreferrer");
       context.onClose();
     };
     const content = buildStepContent(step, ownerDocument, {
-      onCtaClick: (action, url) => {
-        dismiss("cta_clicked", action === "url" ? url : void 0);
+      onCtaClick: (action, url, meta) => {
+        dismiss("cta_clicked", action === "url" ? url : void 0, meta);
       },
       onDismiss: () => dismiss("dismissed")
     });
@@ -1810,7 +2329,7 @@ var TooltipRenderer = class extends BaseRenderer {
     this.liveContent = content;
     this.liveKey = selector;
     this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-      onCtaClick: (action, url) => dismiss("cta_clicked", action === "url" ? url : void 0),
+      onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
       onDismiss: () => dismiss("dismissed")
     });
     context.onInteraction({
@@ -1894,14 +2413,26 @@ var GuidePreviewController = class {
     const nextStep = input.guideSteps[0];
     if (this.singleStep && this.input && input.guideType === this.input.guideType && input.guideType !== "walkthrough" && nextStep && this.singleStep.updateStep(nextStep)) {
       this.input = input;
-      return { close: () => this.close(), ready: Promise.resolve({ rendered: true }) };
+      return {
+        close: () => this.close(),
+        ready: Promise.resolve({ rendered: true }),
+        host: () => this.activeHost()
+      };
     }
     this.close();
     this.input = input;
     const guide = normalize(input);
     const start = typeof input.startStepIndex === "number" ? input.startStepIndex : 0;
     const ready = guide.guideType === "walkthrough" ? this.startWalkthrough(guide, start) : this.renderSingleStep(guide);
-    return { close: () => this.close(), ready };
+    return { close: () => this.close(), ready, host: () => this.activeHost() };
+  }
+  /** Host de la guía montada (single-step o paso de walkthrough activo). */
+  activeHost() {
+    if (this.singleStep) return this.singleStep.hostElement();
+    if (this.walkthrough instanceof BaseRenderer) {
+      return this.walkthrough.hostElement();
+    }
+    return null;
   }
   close() {
     if (this.singleStep) {
@@ -2022,7 +2553,7 @@ var activeController = null;
 function previewGuide(input) {
   if (!hasDocument()) {
     return { close: () => {
-    }, ready: Promise.resolve({ rendered: false }) };
+    }, ready: Promise.resolve({ rendered: false }), host: () => null };
   }
   if (!activeController) activeController = new GuidePreviewController();
   return activeController.preview(input);
@@ -2065,6 +2596,8 @@ function createSingleStepRenderer(type) {
       return new FormRenderer();
     case "inline-form":
       return new InlineFormRenderer();
+    case "badge":
+      return new BadgeRenderer();
     case "walkthrough":
       return null;
   }
@@ -2170,8 +2703,8 @@ function injectBuilderPanel(opts) {
     const ot = top;
     iframe.style.pointerEvents = "none";
     const move = (ev) => {
-      left = clamp2(ol + (ev.clientX - sx), 0, Math.max(0, window.innerWidth - card.offsetWidth));
-      top = clamp2(ot + (ev.clientY - sy), 0, Math.max(0, window.innerHeight - 40));
+      left = clamp3(ol + (ev.clientX - sx), 0, Math.max(0, window.innerWidth - card.offsetWidth));
+      top = clamp3(ot + (ev.clientY - sy), 0, Math.max(0, window.innerHeight - 40));
       card.style.left = `${left}px`;
       card.style.top = `${top}px`;
     };
@@ -2192,8 +2725,8 @@ function injectBuilderPanel(opts) {
     const sh = card.offsetHeight;
     iframe.style.pointerEvents = "none";
     const move = (ev) => {
-      card.style.width = `${clamp2(sw + (ev.clientX - sx), MIN_W, window.innerWidth)}px`;
-      card.style.height = `${clamp2(sh + (ev.clientY - sy), MIN_H, window.innerHeight)}px`;
+      card.style.width = `${clamp3(sw + (ev.clientX - sx), MIN_W, window.innerWidth)}px`;
+      card.style.height = `${clamp3(sh + (ev.clientY - sy), MIN_H, window.innerHeight)}px`;
     };
     const up = () => {
       window.removeEventListener("mousemove", move);
@@ -2212,7 +2745,7 @@ function injectBuilderPanel(opts) {
     }
   };
 }
-function clamp2(v, min, max) {
+function clamp3(v, min, max) {
   return Math.min(Math.max(v, min), max);
 }
 function buildPanelUrl(opts) {
@@ -2264,6 +2797,237 @@ var PANEL_CSS = `
 }
 `;
 
+// src/plugins/builder/design-manipulator.ts
+var MIN_W2 = 220;
+var MAX_W = 720;
+var MIN_H2 = 120;
+var MAX_H = 900;
+var EDGE = 8;
+var RESIZE_DIRS = ["n", "s", "e", "w", "ne", "nw", "se", "sw"];
+var MANIPULATOR_CSS = `
+.veo-mnp-card {
+  outline: 1.5px dashed rgba(255, 91, 53, 0.75);
+  outline-offset: 2px;
+}
+.veo-mnp-card:hover { cursor: move; }
+.veo-mnp-handle {
+  position: absolute;
+  z-index: 10;
+  background: transparent;
+}
+.veo-mnp-handle::after {
+  content: '';
+  position: absolute;
+  width: 8px; height: 8px;
+  background: #fff;
+  border: 1.5px solid rgba(255, 91, 53, 0.9);
+  border-radius: 2px;
+  top: 50%; left: 50%;
+  transform: translate(-50%, -50%);
+  opacity: 0;
+  transition: opacity 100ms ease;
+}
+.veo-mnp-card:hover .veo-mnp-handle::after,
+.veo-mnp-handle:hover::after { opacity: 1; }
+.veo-mnp-n  { top: -${EDGE / 2}px; left: ${EDGE}px; right: ${EDGE}px; height: ${EDGE}px; cursor: ns-resize; }
+.veo-mnp-s  { bottom: -${EDGE / 2}px; left: ${EDGE}px; right: ${EDGE}px; height: ${EDGE}px; cursor: ns-resize; }
+.veo-mnp-e  { right: -${EDGE / 2}px; top: ${EDGE}px; bottom: ${EDGE}px; width: ${EDGE}px; cursor: ew-resize; }
+.veo-mnp-w  { left: -${EDGE / 2}px; top: ${EDGE}px; bottom: ${EDGE}px; width: ${EDGE}px; cursor: ew-resize; }
+.veo-mnp-ne { top: -${EDGE / 2}px; right: -${EDGE / 2}px; width: ${EDGE * 1.5}px; height: ${EDGE * 1.5}px; cursor: nesw-resize; }
+.veo-mnp-nw { top: -${EDGE / 2}px; left: -${EDGE / 2}px; width: ${EDGE * 1.5}px; height: ${EDGE * 1.5}px; cursor: nwse-resize; }
+.veo-mnp-se { bottom: -${EDGE / 2}px; right: -${EDGE / 2}px; width: ${EDGE * 1.5}px; height: ${EDGE * 1.5}px; cursor: nwse-resize; }
+.veo-mnp-sw { bottom: -${EDGE / 2}px; left: -${EDGE / 2}px; width: ${EDGE * 1.5}px; height: ${EDGE * 1.5}px; cursor: nesw-resize; }
+.veo-mnp-banner { outline: 1.5px dashed rgba(255, 91, 53, 0.75); outline-offset: -2px; cursor: grab; }
+.veo-mnp-banner:active { cursor: grabbing; }
+`;
+function clamp4(v, min, max) {
+  return Math.min(Math.max(v, min), max);
+}
+function round3(v) {
+  return Math.round(v * 1e3) / 1e3;
+}
+function isInteractive(target) {
+  return Boolean(
+    target instanceof Element && target.closest("button, a, input, textarea, select, label")
+  );
+}
+function attachDesignManipulator(opts) {
+  const shadow = opts.host.shadowRoot;
+  if (!shadow) return null;
+  const card = shadow.querySelector(".veo-modal-card");
+  if (card) return attachModal(opts, shadow, card);
+  const banner = shadow.querySelector(".veo-banner");
+  if (banner && !banner.classList.contains("veo-banner-embedded")) {
+    return attachBanner(opts, shadow, banner);
+  }
+  return null;
+}
+function attachModal(opts, shadow, card) {
+  if (card.dataset.veoManipulated === "1") return null;
+  card.dataset.veoManipulated = "1";
+  card.classList.add("veo-mnp-card");
+  const doc = card.ownerDocument;
+  const style = doc.createElement("style");
+  style.textContent = MANIPULATOR_CSS;
+  shadow.appendChild(style);
+  const handles = [];
+  for (const dir of RESIZE_DIRS) {
+    const h = doc.createElement("div");
+    h.className = `veo-mnp-handle veo-mnp-${dir}`;
+    h.dataset.veoDir = dir;
+    card.appendChild(h);
+    handles.push(h);
+  }
+  let dragging = false;
+  let detached = false;
+  let patch = {};
+  const setVars = (v) => {
+    const host = opts.host;
+    if (v.px !== void 0) host.style.setProperty("--veo-pos-x", `${v.px * 100}%`);
+    if (v.py !== void 0) host.style.setProperty("--veo-pos-y", `${v.py * 100}%`);
+    if (v.w !== void 0) host.style.setProperty("--veo-width", `${v.w}px`);
+    if (v.h !== void 0) host.style.setProperty("--veo-min-h", `${v.h}px`);
+  };
+  const startGesture = (e, apply) => {
+    e.preventDefault();
+    e.stopPropagation();
+    dragging = true;
+    patch = {};
+    const start = card.getBoundingClientRect();
+    const sx = e.clientX;
+    const sy = e.clientY;
+    let raf = 0;
+    let lastEv = null;
+    const flush = () => {
+      raf = 0;
+      if (!lastEv) return;
+      const next = apply(lastEv.clientX - sx, lastEv.clientY - sy, start);
+      patch = { ...patch, ...next };
+      setVars({
+        ...next.posX !== void 0 ? { px: next.posX } : {},
+        ...next.posY !== void 0 ? { py: next.posY } : {},
+        ...next.width !== void 0 ? { w: next.width } : {},
+        ...next.height !== void 0 ? { h: next.height } : {}
+      });
+    };
+    const move = (ev) => {
+      lastEv = ev;
+      if (typeof window.requestAnimationFrame !== "function") flush();
+      else if (!raf) raf = window.requestAnimationFrame(flush);
+    };
+    const up = () => {
+      window.removeEventListener("mousemove", move);
+      window.removeEventListener("mouseup", up);
+      if (raf) window.cancelAnimationFrame(raf);
+      flush();
+      dragging = false;
+      if (Object.keys(patch).length > 0 && !detached) {
+        opts.onCommit({ stepIndex: opts.stepIndex, style: patch });
+      }
+      opts.onGestureEnd?.();
+    };
+    window.addEventListener("mousemove", move);
+    window.addEventListener("mouseup", up);
+  };
+  const posXFor = (left, w) => {
+    const span = window.innerWidth - w;
+    return span <= 0 ? 0.5 : round3(clamp4(left / span, 0, 1));
+  };
+  const posYFor = (top, h) => {
+    const span = window.innerHeight - h;
+    return span <= 0 ? 0.5 : round3(clamp4(top / span, 0, 1));
+  };
+  const onCardDown = (e) => {
+    if (isInteractive(e.target)) return;
+    if (e.target instanceof Element && e.target.closest(".veo-mnp-handle")) return;
+    startGesture(e, (dx, dy, start) => ({
+      posX: posXFor(start.left + dx, start.width),
+      posY: posYFor(start.top + dy, start.height)
+    }));
+  };
+  const onHandleDown = (e) => {
+    const dir = e.currentTarget.dataset.veoDir;
+    startGesture(e, (dx, dy, start) => {
+      const out = {};
+      if (dir.includes("e")) out.width = Math.round(clamp4(start.width + dx, MIN_W2, MAX_W));
+      if (dir.includes("w")) {
+        out.width = Math.round(clamp4(start.width - dx, MIN_W2, MAX_W));
+        out.posX = posXFor(start.right - out.width, out.width);
+      }
+      if (dir.includes("s")) out.height = Math.round(clamp4(start.height + dy, MIN_H2, MAX_H));
+      if (dir.includes("n")) {
+        out.height = Math.round(clamp4(start.height - dy, MIN_H2, MAX_H));
+        out.posY = posYFor(start.bottom - out.height, out.height);
+      }
+      return out;
+    });
+  };
+  card.addEventListener("mousedown", onCardDown);
+  for (const h of handles) h.addEventListener("mousedown", onHandleDown);
+  return {
+    isDragging: () => dragging,
+    detach: () => {
+      if (detached) return;
+      detached = true;
+      card.removeEventListener("mousedown", onCardDown);
+      for (const h of handles) h.remove();
+      style.remove();
+      card.classList.remove("veo-mnp-card");
+      delete card.dataset.veoManipulated;
+    }
+  };
+}
+function attachBanner(opts, shadow, banner) {
+  if (banner.dataset.veoManipulated === "1") return null;
+  banner.dataset.veoManipulated = "1";
+  banner.classList.add("veo-mnp-banner");
+  const doc = banner.ownerDocument;
+  const style = doc.createElement("style");
+  style.textContent = MANIPULATOR_CSS;
+  shadow.appendChild(style);
+  let dragging = false;
+  let detached = false;
+  const positionOf = () => banner.classList.contains("veo-banner-bottom") ? "bottom" : "top";
+  const onDown = (e) => {
+    if (isInteractive(e.target)) return;
+    e.preventDefault();
+    dragging = true;
+    const startPos = positionOf();
+    let current = startPos;
+    const move = (ev) => {
+      const next = ev.clientY < window.innerHeight / 2 ? "top" : "bottom";
+      if (next !== current) {
+        current = next;
+        banner.classList.remove("veo-banner-top", "veo-banner-bottom");
+        banner.classList.add(`veo-banner-${next}`);
+      }
+    };
+    const up = () => {
+      window.removeEventListener("mousemove", move);
+      window.removeEventListener("mouseup", up);
+      dragging = false;
+      if (current !== startPos && !detached) {
+        opts.onCommit({ stepIndex: opts.stepIndex, style: { position: current } });
+      }
+      opts.onGestureEnd?.();
+    };
+    window.addEventListener("mousemove", move);
+    window.addEventListener("mouseup", up);
+  };
+  banner.addEventListener("mousedown", onDown);
+  return {
+    isDragging: () => dragging,
+    detach: () => {
+      if (detached) return;
+      detached = true;
+      banner.removeEventListener("mousedown", onDown);
+      style.remove();
+      banner.classList.remove("veo-mnp-banner");
+      delete banner.dataset.veoManipulated;
+    }
+  };
+}
+
 // src/plugins/autocapture/constants.ts
 var HASHED_CLASS_PATTERNS = [
   /^css-[a-z0-9]{4,}$/i,
@@ -2556,10 +3320,35 @@ function initBuilderMode() {
   let picker = null;
   let panel = null;
   let staticTarget = null;
+  let manipulator = null;
+  let pendingPreview = null;
   const getTarget = () => panel ? panel.target() : staticTarget;
   const post = (event) => {
     getTarget()?.postMessage({ source: VEO_BUILDER_SOURCE, token, ...event }, dashboardOrigin);
   };
+  const applyPreview = (cmd) => {
+    manipulator?.detach();
+    manipulator = null;
+    const handle = previewGuide(cmd.guide);
+    if (!cmd.editable) return;
+    void handle.ready.then((result) => {
+      if (!result.rendered) return;
+      const host = handle.host();
+      if (!host) return;
+      manipulator = attachDesignManipulator({
+        host,
+        guideType: cmd.guide.guideType,
+        stepIndex: cmd.guide.startStepIndex ?? 0,
+        onCommit: (payload) => post({ type: "design-updated", payload }),
+        onGestureEnd: () => {
+          if (!pendingPreview) return;
+          const queued = pendingPreview;
+          pendingPreview = null;
+          applyPreview(queued);
+        }
+      });
+    });
+  };
   const handleCommand = (cmd) => {
     switch (cmd.type) {
       case "panel-ready":
@@ -2585,9 +3374,14 @@ function initBuilderMode() {
         picker = null;
         break;
       case "preview":
-        if (cmd.guide) void previewGuide(cmd.guide).ready;
+        if (!cmd.guide) break;
+        if (manipulator?.isDragging()) pendingPreview = cmd;
+        else applyPreview(cmd);
         break;
       case "close-preview":
+        manipulator?.detach();
+        manipulator = null;
+        pendingPreview = null;
         closeGuidePreview();
         break;
       case "teardown":
@@ -2607,6 +3401,9 @@ function initBuilderMode() {
     window.removeEventListener("pagehide", onPageHide);
     picker?.stop();
     picker = null;
+    manipulator?.detach();
+    manipulator = null;
+    pendingPreview = null;
     closeGuidePreview();
     post({ type: "closed" });
     panel?.teardown();