veo-sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,2528 @@
+import { computePosition, offset, flip, shift } from '@floating-ui/dom';
+
+// src/contract/v1.ts
+var SDK_VERSION = "0.0.1";
+var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
+var DEFAULT_FLUSH_BATCH_SIZE = 20;
+
+// src/utils/safe-env.ts
+function hasWindow() {
+  return typeof window !== "undefined";
+}
+function hasDocument() {
+  return typeof document !== "undefined";
+}
+function hasLocalStorage() {
+  try {
+    if (typeof localStorage === "undefined") return false;
+    const testKey = "__veo_test__";
+    localStorage.setItem(testKey, "1");
+    localStorage.removeItem(testKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasNavigatorSendBeacon() {
+  return typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function";
+}
+
+// src/utils/uuid.ts
+function uuidv7() {
+  const timestamp = Date.now();
+  const timeHex = timestamp.toString(16).padStart(12, "0");
+  const random = new Uint8Array(10);
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(random);
+  } else {
+    for (let i = 0; i < random.length; i++) {
+      random[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  random[0] = (random[0] ?? 0) & 15 | 112;
+  random[2] = (random[2] ?? 0) & 63 | 128;
+  const hex = Array.from(random, (b) => b.toString(16).padStart(2, "0")).join("");
+  return [
+    timeHex.slice(0, 8),
+    timeHex.slice(8, 12),
+    hex.slice(0, 4),
+    hex.slice(4, 8),
+    hex.slice(8, 20)
+  ].join("-");
+}
+
+// src/core/queue.ts
+var RETRY_MAX_DELAY_MS = 3e4;
+var Queue = class {
+  constructor(config) {
+    this.config = config;
+    this.buffer = [];
+    this.timer = null;
+    this.flushing = false;
+    this.retryCount = 0;
+    this.retryTimer = null;
+    this.startTimer();
+  }
+  /** Encola un evento; dispara flush si se alcanza `batchSize`. */
+  add(item) {
+    this.buffer.push(item);
+    if (this.buffer.length >= this.config.batchSize) {
+      void this.flush();
+    }
+  }
+  /** Flush manual vía `fetch`. Resuelve cuando termina (los retries son diferidos). */
+  async flush() {
+    if (this.flushing || this.buffer.length === 0) return;
+    this.flushing = true;
+    const batch = this.buffer.splice(0, this.buffer.length);
+    try {
+      await this.config.transport.send("/v1/events", { events: batch });
+      this.retryCount = 0;
+    } catch (error) {
+      this.buffer.unshift(...batch);
+      this.scheduleRetry();
+      this.config.onError?.(error);
+    } finally {
+      this.flushing = false;
+    }
+  }
+  /** Flush síncrono vía `sendBeacon`, para `pagehide`/`visibilitychange`. */
+  flushBeacon() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0, this.buffer.length);
+    const success = this.config.transport.sendBeacon("/v1/events", { events: batch });
+    if (!success) {
+      this.buffer.unshift(...batch);
+    }
+  }
+  /** Detiene timers internos. Llamar al destruir el cliente. */
+  destroy() {
+    if (this.timer) clearInterval(this.timer);
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.timer = null;
+    this.retryTimer = null;
+  }
+  startTimer() {
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.config.flushIntervalMs);
+  }
+  scheduleRetry() {
+    const maxRetries = this.config.maxRetries ?? 3;
+    if (this.retryCount >= maxRetries) {
+      this.retryCount = 0;
+      return;
+    }
+    this.retryCount++;
+    const delayMs = Math.min(1e3 * 2 ** (this.retryCount - 1), RETRY_MAX_DELAY_MS);
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.retryTimer = setTimeout(() => {
+      void this.flush();
+    }, delayMs);
+  }
+};
+
+// src/core/session.ts
+var ANONYMOUS_ID_KEY = "anonymous_user_id";
+var END_USER_ID_KEY = "end_user_id";
+var SESSION_ID_KEY = "session_id";
+var SESSION_LAST_ACTIVE_KEY = "session_last_active";
+var SESSION_TIMEOUT_MS = 30 * 60 * 1e3;
+var Session = class {
+  constructor(storage) {
+    this.storage = storage;
+    this._endUserId = null;
+    this._anonymousId = this.loadOrCreateAnonymousId();
+    this._sessionId = this.loadOrCreateSession();
+    this._endUserId = this.storage.get(END_USER_ID_KEY);
+  }
+  get anonymousId() {
+    return this._anonymousId;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  get endUserId() {
+    return this._endUserId;
+  }
+  /** ID a usar como visitor en eventos (end_user_id si está identificado, si no anonymous). */
+  get effectiveUserId() {
+    return this._endUserId ?? this._anonymousId;
+  }
+  setEndUserId(id) {
+    this._endUserId = id;
+    this.storage.set(END_USER_ID_KEY, id);
+  }
+  /** Renueva el timestamp de actividad. Si pasaron > 30 min, genera nueva sesión. */
+  touch() {
+    const lastActive = this.storage.get(SESSION_LAST_ACTIVE_KEY);
+    const now = Date.now();
+    if (lastActive && now - Number.parseInt(lastActive, 10) > SESSION_TIMEOUT_MS) {
+      this._sessionId = uuidv7();
+      this.storage.set(SESSION_ID_KEY, this._sessionId);
+    }
+    this.storage.set(SESSION_LAST_ACTIVE_KEY, String(now));
+  }
+  /** Limpia la identidad (reset) pero conserva el anonymous_id. */
+  reset() {
+    this._endUserId = null;
+    this.storage.remove(END_USER_ID_KEY);
+    this._sessionId = uuidv7();
+    this.storage.set(SESSION_ID_KEY, this._sessionId);
+    this.storage.set(SESSION_LAST_ACTIVE_KEY, String(Date.now()));
+  }
+  loadOrCreateAnonymousId() {
+    let id = this.storage.get(ANONYMOUS_ID_KEY);
+    if (!id) {
+      id = uuidv7();
+      this.storage.set(ANONYMOUS_ID_KEY, id);
+    }
+    return id;
+  }
+  loadOrCreateSession() {
+    const existing = this.storage.get(SESSION_ID_KEY);
+    const lastActive = this.storage.get(SESSION_LAST_ACTIVE_KEY);
+    if (existing && lastActive) {
+      const elapsed = Date.now() - Number.parseInt(lastActive, 10);
+      if (elapsed < SESSION_TIMEOUT_MS) {
+        return existing;
+      }
+    }
+    const newId = uuidv7();
+    this.storage.set(SESSION_ID_KEY, newId);
+    this.storage.set(SESSION_LAST_ACTIVE_KEY, String(Date.now()));
+    return newId;
+  }
+};
+
+// src/core/storage.ts
+var STORAGE_PREFIX = "veo:";
+var ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1e3;
+var LocalStorageAdapter = class {
+  get(key) {
+    return localStorage.getItem(STORAGE_PREFIX + key);
+  }
+  set(key, value) {
+    try {
+      localStorage.setItem(STORAGE_PREFIX + key, value);
+    } catch {
+    }
+  }
+  remove(key) {
+    localStorage.removeItem(STORAGE_PREFIX + key);
+  }
+  clear() {
+    const toRemove = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(STORAGE_PREFIX)) toRemove.push(key);
+    }
+    for (const key of toRemove) localStorage.removeItem(key);
+  }
+};
+function readCookies() {
+  const raw = document.cookie;
+  return raw === "" ? [] : raw.split("; ");
+}
+var CookieAdapter = class {
+  get(key) {
+    const name = `${STORAGE_PREFIX}${key}=`;
+    for (const cookie of readCookies()) {
+      if (cookie.startsWith(name)) {
+        return decodeURIComponent(cookie.slice(name.length));
+      }
+    }
+    return null;
+  }
+  set(key, value, options) {
+    const maxAgeSec = Math.floor((options?.ttlMs ?? ONE_YEAR_MS) / 1e3);
+    const secure = typeof location !== "undefined" && location.protocol === "https:" ? "; Secure" : "";
+    document.cookie = `${STORAGE_PREFIX}${key}=${encodeURIComponent(
+      value
+    )}; Path=/; Max-Age=${maxAgeSec}; SameSite=Lax${secure}`;
+  }
+  remove(key) {
+    document.cookie = `${STORAGE_PREFIX}${key}=; Path=/; Max-Age=0; SameSite=Lax`;
+  }
+  clear() {
+    for (const cookie of readCookies()) {
+      const eq = cookie.indexOf("=");
+      const name = eq === -1 ? cookie : cookie.slice(0, eq);
+      if (name.startsWith(STORAGE_PREFIX)) {
+        this.remove(name.slice(STORAGE_PREFIX.length));
+      }
+    }
+  }
+};
+var MemoryAdapter = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    return this.store.get(key) ?? null;
+  }
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  remove(key) {
+    this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+function createStorage(preferred = "localStorage") {
+  if (preferred === "localStorage" && hasLocalStorage()) return new LocalStorageAdapter();
+  if (preferred === "cookie" && hasDocument()) return new CookieAdapter();
+  if (preferred === "memory") return new MemoryAdapter();
+  if (hasLocalStorage()) return new LocalStorageAdapter();
+  if (hasDocument()) return new CookieAdapter();
+  return new MemoryAdapter();
+}
+
+// src/core/transport.ts
+var TransportError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "TransportError";
+  }
+};
+var Transport = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Envío normal con `fetch`. Lanza `TransportError` si la respuesta no es OK. */
+  async send(path, body) {
+    const url = `${this.config.apiUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 1e4);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Api-Key": this.config.apiKey,
+          "X-Sdk-Version": this.config.sdkVersion
+        },
+        body: JSON.stringify(body),
+        keepalive: true,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new TransportError(`HTTP ${response.status}`, response.status);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Envío con `navigator.sendBeacon`. Fire-and-forget, pensado para `pagehide`.
+   * Como sendBeacon no admite headers, la API key viaja por query string.
+   */
+  sendBeacon(path, body) {
+    if (!hasNavigatorSendBeacon()) return false;
+    const url = new URL(`${this.config.apiUrl}${path}`);
+    url.searchParams.set("key", this.config.apiKey);
+    url.searchParams.set("v", this.config.sdkVersion);
+    const blob = new Blob([JSON.stringify(body)], { type: "application/json" });
+    return navigator.sendBeacon(url.toString(), blob);
+  }
+};
+
+// src/core/client.ts
+var ORGANIZATION_ID_KEY = "organization_id";
+var END_USER_ID_KEY2 = "end_user_id";
+var IDENTIFY_SIG_KEY = "identify_signature";
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const entries = Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`);
+  return `{${entries.join(",")}}`;
+}
+var Client = class {
+  constructor(config) {
+    this.config = config;
+    this.plugins = [];
+    this.currentOrganizationId = null;
+    this.listeners = {
+      pageview: /* @__PURE__ */ new Set(),
+      identify: /* @__PURE__ */ new Set()
+    };
+    if (!config.apiKey) throw new Error("apiKey is required");
+    if (!config.apiUrl) throw new Error("apiUrl is required");
+    this.storage = createStorage(config.storage ?? "localStorage");
+    this.session = new Session(this.storage);
+    this.transport = new Transport({
+      apiKey: config.apiKey,
+      apiUrl: config.apiUrl.replace(/\/$/, ""),
+      sdkVersion: SDK_VERSION
+    });
+    this.queue = new Queue({
+      transport: this.transport,
+      flushIntervalMs: config.flushInterval ?? DEFAULT_FLUSH_INTERVAL_MS,
+      batchSize: config.flushBatchSize ?? DEFAULT_FLUSH_BATCH_SIZE,
+      onError: (err) => {
+        if (config.debug) console.error("[veo] flush error:", err);
+      }
+    });
+    const persistedUserId = this.storage.get(END_USER_ID_KEY2);
+    if (persistedUserId) this.session.setEndUserId(persistedUserId);
+    const persistedOrgId = this.storage.get(ORGANIZATION_ID_KEY);
+    if (persistedOrgId) this.currentOrganizationId = persistedOrgId;
+    this.setupUnloadHandlers();
+    if (config.debug) {
+      console.log("[veo] initialized", {
+        anonymousId: this.session.anonymousId,
+        sessionId: this.session.sessionId,
+        endUserId: this.session.endUserId
+      });
+    }
+  }
+  identify(payload) {
+    const { visitor, organization } = payload;
+    const signature = stableStringify({
+      id: visitor.id,
+      traits: visitor.traits ?? {},
+      org: organization ? { id: organization.id, attributes: organization.attributes ?? {} } : null
+    });
+    if (this.session.endUserId === visitor.id && this.storage.get(IDENTIFY_SIG_KEY) === signature) {
+      if (this.config.debug) console.debug("[veo] identify: sin cambios, omitido");
+      return;
+    }
+    const previousAnonymousId = this.session.endUserId === null ? this.session.anonymousId : void 0;
+    this.session.setEndUserId(visitor.id);
+    if (organization) {
+      this.currentOrganizationId = organization.id;
+      this.storage.set(ORGANIZATION_ID_KEY, organization.id);
+    }
+    const endUser = {
+      id: visitor.id,
+      traits: visitor.traits ?? {},
+      ...previousAnonymousId !== void 0 ? { anonymousId: previousAnonymousId } : {}
+    };
+    const body = {
+      endUser,
+      ...organization ? { organization: { id: organization.id, attributes: organization.attributes ?? {} } } : {}
+    };
+    void this.transport.send("/v1/identify", body).catch((err) => {
+      if (this.config.debug) console.error("[veo] identify failed:", err);
+    });
+    this.enqueue({
+      actionType: "identify",
+      actionProperties: {
+        traits: visitor.traits,
+        organizationAttributes: organization?.attributes
+      }
+    });
+    this.storage.set(IDENTIFY_SIG_KEY, signature);
+    this.emit("identify", { endUserId: visitor.id, sessionId: this.session.sessionId });
+  }
+  track(name, properties) {
+    if (!name || typeof name !== "string") {
+      if (this.config.debug) console.error("[veo] track: name is required");
+      return;
+    }
+    this.enqueue({
+      actionType: "track",
+      actionName: name,
+      ...properties !== void 0 ? { actionProperties: properties } : {}
+    });
+  }
+  pageview(path) {
+    if (!hasDocument()) return;
+    const url = window.location.href;
+    const pagePath = path ?? window.location.pathname;
+    this.enqueue({
+      actionType: "pageview",
+      pageUrl: url,
+      pagePath,
+      pageTitle: document.title,
+      pageReferrer: document.referrer
+    });
+    this.emit("pageview", {
+      url,
+      path: pagePath,
+      sessionId: this.session.sessionId,
+      endUserId: this.session.endUserId
+    });
+  }
+  reset() {
+    this.session.reset();
+    this.currentOrganizationId = null;
+    this.storage.remove(ORGANIZATION_ID_KEY);
+    this.storage.remove(END_USER_ID_KEY2);
+    this.storage.remove(IDENTIFY_SIG_KEY);
+  }
+  flush() {
+    return this.queue.flush();
+  }
+  use(plugin) {
+    this.plugins.push(plugin);
+    plugin.install(this);
+    return this;
+  }
+  getEndUserId() {
+    return this.session.endUserId;
+  }
+  getSessionId() {
+    return this.session.sessionId;
+  }
+  /**
+   * Suscribe `listener` a `event`. Devuelve una función para desuscribir.
+   * Los errores en listeners se logean en debug mode pero NO se propagan
+   * (un plugin no debe poder romper a otro).
+   */
+  on(event, listener) {
+    this.listeners[event].add(listener);
+    return () => {
+      this.listeners[event].delete(listener);
+    };
+  }
+  emit(event, payload) {
+    for (const listener of this.listeners[event]) {
+      try {
+        listener(payload);
+      } catch (err) {
+        if (this.config.debug) console.error(`[veo] listener for '${event}' failed:`, err);
+      }
+    }
+  }
+  /**
+   * Construye el evento completo y lo agrega a la queue. Omite los campos
+   * opcionales no definidos (exigido por `exactOptionalPropertyTypes`).
+   * @internal
+   */
+  enqueue(input) {
+    this.session.touch();
+    const organizationId = this.currentOrganizationId ?? void 0;
+    const pageUrl = input.pageUrl ?? (hasWindow() ? window.location.href : void 0);
+    const pagePath = input.pagePath ?? (hasWindow() ? window.location.pathname : void 0);
+    const pageTitle = input.pageTitle ?? (hasDocument() ? document.title : void 0);
+    const pageReferrer = input.pageReferrer ?? (hasDocument() ? document.referrer : void 0);
+    const event = {
+      actionId: uuidv7(),
+      endUserId: this.session.effectiveUserId,
+      sessionId: this.session.sessionId,
+      actionType: input.actionType,
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...organizationId !== void 0 ? { organizationId } : {},
+      ...input.actionName !== void 0 ? { actionName: input.actionName } : {},
+      ...pageUrl !== void 0 ? { pageUrl } : {},
+      ...pagePath !== void 0 ? { pagePath } : {},
+      ...pageTitle !== void 0 ? { pageTitle } : {},
+      ...pageReferrer !== void 0 ? { pageReferrer } : {},
+      ...input.actionProperties !== void 0 ? { actionProperties: input.actionProperties } : {}
+    };
+    this.queue.add(event);
+  }
+  setupUnloadHandlers() {
+    if (!hasWindow()) return;
+    window.addEventListener("pagehide", () => this.queue.flushBeacon());
+    window.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") {
+        this.queue.flushBeacon();
+      }
+    });
+  }
+};
+
+// src/plugins/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
+
+// src/plugins/autocapture/constants.ts
+var DEFAULT_AUTOCAPTURE_CONFIG = {
+  enabled: true,
+  captureClicks: true,
+  captureSubmits: true,
+  captureChanges: true,
+  maskAllInputs: true,
+  maskAllText: false,
+  throttleMs: 100,
+  maxTextLength: 200,
+  captureElementMetadata: true,
+  captureAncestors: 5
+};
+var MAX_ANCESTORS = 10;
+var ALWAYS_BLOCK_SELECTORS = [
+  "[data-veo-ignore]",
+  ".veo-ignore",
+  // Inputs sensibles
+  'input[type="password"]',
+  'input[type="email"]',
+  'input[type="tel"]',
+  'input[type="hidden"]',
+  // Datos de tarjeta
+  '[autocomplete="cc-number"]',
+  '[autocomplete="cc-csc"]',
+  '[autocomplete="cc-exp"]',
+  '[autocomplete="cc-name"]',
+  // Otros campos sensibles típicos
+  '[name*="password" i]',
+  '[name*="ssn" i]',
+  '[name*="credit" i]',
+  '[name*="card" i]',
+  '[id*="password" i]',
+  '[id*="ssn" i]'
+];
+var SENSITIVE_ATTRIBUTES = ["value", "data-credit-card", "data-ssn", "data-password"];
+var PRIORITY_ATTRIBUTES = [
+  "id",
+  "name",
+  "type",
+  "role",
+  "href",
+  "data-action",
+  "data-veo-tag",
+  "data-testid",
+  "aria-label",
+  "aria-labelledby"
+];
+var HASHED_CLASS_PATTERNS = [
+  /^css-[a-z0-9]{4,}$/i,
+  // emotion, styled-components nuevas
+  /^_[a-z0-9]+_[a-z0-9]{4,}_\d+$/,
+  // CSS Modules con hash
+  /^[a-z]{2,4}-[a-z0-9]{6,}$/i,
+  // Tailwind JIT (a veces)
+  /^[a-f0-9]{6,}$/i,
+  // hashes hex puros
+  /^sc-[a-z0-9]+$/i
+  // styled-components legacy
+];
+
+// src/plugins/autocapture/pii-guard.ts
+function isElementBlocked(element, extraBlockSelectors = []) {
+  const allBlockers = [...ALWAYS_BLOCK_SELECTORS, ...extraBlockSelectors];
+  let current = element;
+  while (current && current !== document.documentElement) {
+    for (const selector of allBlockers) {
+      try {
+        if (current.matches(selector)) return true;
+      } catch {
+      }
+    }
+    current = current.parentElement;
+  }
+  return false;
+}
+function isSensitiveAttribute(attrName) {
+  const lower = attrName.toLowerCase();
+  return SENSITIVE_ATTRIBUTES.includes(lower) || /password|secret|token|ssn|credit/i.test(attrName);
+}
+function safeGetText(element, maxLength, mask) {
+  if (mask) return "";
+  const tagName = element.tagName.toLowerCase();
+  if (tagName === "input" || tagName === "textarea") return "";
+  const raw = (element instanceof HTMLElement ? element.innerText : "") || element.textContent || "";
+  const trimmed = raw.trim().replace(/\s+/g, " ");
+  return trimmed.length > maxLength ? `${trimmed.slice(0, maxLength)}\u2026` : trimmed;
+}
+
+// src/plugins/autocapture/selector-builder.ts
+function isHashedClass(className) {
+  return HASHED_CLASS_PATTERNS.some((pattern) => pattern.test(className));
+}
+function filterHumanClasses(element) {
+  return Array.from(element.classList).filter((c) => !isHashedClass(c) && c.length < 64);
+}
+var STABLE_ATTRIBUTES = [
+  "data-testid",
+  "data-test",
+  "data-cy",
+  "name",
+  "aria-label",
+  "placeholder",
+  "alt",
+  "title",
+  // `href` identifica muy bien a los links (`<a>`), un target frecuente de
+  // autocapture; va después de los atributos semánticos pero antes de los
+  // genéricos. Valores largos (URLs absolutas con query) se descartan por
+  // MAX_ATTR_VALUE_LENGTH.
+  "href",
+  "role",
+  "type"
+];
+var MAX_ATTR_VALUE_LENGTH = 100;
+function cssEscape(value) {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  return value.replace(/[!"#$%&'()*+,./:;<=>?@[\\\]^`{|}~]/g, "\\$&");
+}
+function escapeAttrValue(value) {
+  return value.replace(/[\\"]/g, "\\$&");
+}
+function stableAttributeSelector(element, tag) {
+  for (const attr of STABLE_ATTRIBUTES) {
+    const value = element.getAttribute(attr);
+    if (value && value.length > 0 && value.length <= MAX_ATTR_VALUE_LENGTH) {
+      return `${tag}[${attr}="${escapeAttrValue(value)}"]`;
+    }
+  }
+  return null;
+}
+function buildElementSelector(element) {
+  const tag = element.tagName.toLowerCase();
+  const veoTag = element.getAttribute("data-veo-tag");
+  if (veoTag) {
+    return `${tag}[data-veo-tag="${escapeAttrValue(veoTag)}"]`;
+  }
+  if (element.id) {
+    const classes2 = filterHumanClasses(element);
+    const classPart2 = classes2.length > 0 ? `.${classes2.map(cssEscape).join(".")}` : "";
+    return `${tag}#${cssEscape(element.id)}${classPart2}`;
+  }
+  const attrSelector = stableAttributeSelector(element, tag);
+  if (attrSelector) return attrSelector;
+  const classes = filterHumanClasses(element);
+  const classPart = classes.length > 0 ? `.${classes.map(cssEscape).join(".")}` : "";
+  return `${tag}${classPart}`;
+}
+function buildSelectorPath(element, maxAncestors = 5) {
+  const parts = [];
+  let current = element;
+  let depth = 0;
+  while (current && current !== document.documentElement && depth <= maxAncestors) {
+    parts.unshift(buildElementSelector(current));
+    current = current.parentElement;
+    depth++;
+  }
+  return parts.join(" > ");
+}
+
+// src/plugins/autocapture/element-serializer.ts
+function extractPriorityAttributes(element) {
+  const result = {};
+  for (const attrName of PRIORITY_ATTRIBUTES) {
+    const value = element.getAttribute(attrName);
+    if (value !== null && !isSensitiveAttribute(attrName) && value.length < 256) {
+      result[attrName] = value;
+    }
+  }
+  return result;
+}
+function serializeElement(element, config) {
+  const rect = element.getBoundingClientRect();
+  return {
+    tag: element.tagName.toLowerCase(),
+    id: element.id || null,
+    classes: filterHumanClasses(element),
+    text: safeGetText(element, config.maxTextLength, config.maskAllText),
+    attributes: config.captureElementMetadata ? extractPriorityAttributes(element) : {},
+    position: {
+      x: Math.round(rect.left + window.scrollX),
+      y: Math.round(rect.top + window.scrollY),
+      w: Math.round(rect.width),
+      h: Math.round(rect.height)
+    }
+  };
+}
+function serializeAncestors(element, maxDepth) {
+  const ancestors = [];
+  let current = element.parentElement;
+  let depth = 0;
+  while (current && current !== document.documentElement && depth < maxDepth) {
+    ancestors.push({
+      tag: current.tagName.toLowerCase(),
+      id: current.id || null,
+      classes: filterHumanClasses(current),
+      veoTag: current.getAttribute("data-veo-tag") || null
+    });
+    current = current.parentElement;
+    depth++;
+  }
+  return ancestors;
+}
+function buildAutocapturePayload(eventType, element, config) {
+  return {
+    $event_type: eventType,
+    $element: serializeElement(element, config),
+    $ancestors: serializeAncestors(element, config.captureAncestors),
+    $selector_path: buildSelectorPath(element, config.captureAncestors),
+    $page_url: window.location.href,
+    $page_path: window.location.pathname
+  };
+}
+
+// src/plugins/autocapture/throttle.ts
+var ElementThrottle = class {
+  constructor(windowMs) {
+    this.windowMs = windowMs;
+    this.lastFired = /* @__PURE__ */ new WeakMap();
+  }
+  /** Devuelve true si el elemento puede emitir ahora (y registra el disparo). */
+  shouldFire(element) {
+    const now = Date.now();
+    const last = this.lastFired.get(element) ?? 0;
+    if (now - last < this.windowMs) return false;
+    this.lastFired.set(element, now);
+    return true;
+  }
+};
+
+// src/plugins/autocapture/dom-listener.ts
+var DomListener = class {
+  constructor(client, config) {
+    this.client = client;
+    this.cleanups = [];
+    const d = DEFAULT_AUTOCAPTURE_CONFIG;
+    this.config = {
+      enabled: config.enabled ?? d.enabled,
+      captureClicks: config.captureClicks ?? d.captureClicks,
+      captureSubmits: config.captureSubmits ?? d.captureSubmits,
+      captureChanges: config.captureChanges ?? d.captureChanges,
+      maskAllInputs: config.maskAllInputs ?? d.maskAllInputs,
+      maskAllText: config.maskAllText ?? d.maskAllText,
+      blockSelectors: config.blockSelectors ?? [],
+      throttleMs: config.throttleMs ?? d.throttleMs,
+      maxTextLength: config.maxTextLength ?? d.maxTextLength,
+      captureElementMetadata: config.captureElementMetadata ?? d.captureElementMetadata,
+      captureAncestors: Math.min(config.captureAncestors ?? d.captureAncestors, MAX_ANCESTORS)
+    };
+    this.throttle = new ElementThrottle(this.config.throttleMs);
+  }
+  install() {
+    if (!hasDocument() || !this.config.enabled) return;
+    if (this.config.captureClicks) this.attach("click", (e) => this.handleClick(e));
+    if (this.config.captureSubmits) this.attach("submit", (e) => this.handleSubmit(e), true);
+    if (this.config.captureChanges) this.attach("change", (e) => this.handleChange(e), true);
+  }
+  destroy() {
+    for (const cleanup of this.cleanups) cleanup();
+    this.cleanups = [];
+  }
+  attach(eventName, handler, useCapture = false) {
+    const listener = (e) => {
+      if (!e.isTrusted) return;
+      try {
+        handler(e);
+      } catch {
+      }
+    };
+    document.addEventListener(eventName, listener, useCapture);
+    this.cleanups.push(() => document.removeEventListener(eventName, listener, useCapture));
+  }
+  handleClick(event) {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    const meaningful = this.findMeaningfulAncestor(target);
+    if (!meaningful) return;
+    if (isElementBlocked(meaningful, this.config.blockSelectors)) return;
+    if (!this.throttle.shouldFire(meaningful)) return;
+    this.emit("click", meaningful);
+  }
+  handleSubmit(event) {
+    const target = event.target;
+    if (!(target instanceof Element) || target.tagName.toLowerCase() !== "form") return;
+    if (isElementBlocked(target, this.config.blockSelectors)) return;
+    if (!this.throttle.shouldFire(target)) return;
+    this.emit("submit", target);
+  }
+  handleChange(event) {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    const tag = target.tagName.toLowerCase();
+    if (tag !== "select" && tag !== "input" && tag !== "textarea") return;
+    if (target instanceof HTMLInputElement && target.type !== "checkbox" && target.type !== "radio") {
+      return;
+    }
+    if (isElementBlocked(target, this.config.blockSelectors)) return;
+    if (!this.throttle.shouldFire(target)) return;
+    this.emit("change", target);
+  }
+  /** Busca hacia arriba un ancestro "interactivo". Devuelve null si no hay ninguno. */
+  findMeaningfulAncestor(element) {
+    let current = element;
+    let depth = 0;
+    while (current && current !== document.documentElement && depth < 5) {
+      const tag = current.tagName.toLowerCase();
+      const isInteractive = tag === "button" || tag === "a" || tag === "input" || tag === "select" || tag === "textarea" || current.hasAttribute("data-veo-tag") || current.hasAttribute("role") || current.hasAttribute("onclick") || current instanceof HTMLElement && current.style.cursor === "pointer";
+      if (isInteractive) return current;
+      current = current.parentElement;
+      depth++;
+    }
+    return null;
+  }
+  emit(eventType, element) {
+    const payload = buildAutocapturePayload(eventType, element, this.config);
+    this.client.track("$autocapture", payload);
+  }
+};
+
+// src/plugins/autocapture/index.ts
+function autocapturePlugin(config = {}) {
+  let listener = null;
+  return definePlugin({
+    name: "autocapture",
+    install(client) {
+      listener = new DomListener(client, config);
+      listener.install();
+    },
+    destroy() {
+      listener?.destroy();
+      listener = null;
+    }
+  });
+}
+
+// src/plugins/guides/constants.ts
+var GUIDE_Z_INDEX = 2147483640;
+var DEFAULT_ANCHOR_WAIT_MS = 5e3;
+var SAFE_URL_PROTOCOLS = ["http:", "https:"];
+var GUIDE_HOST_ATTR = "data-veo-guide";
+var FREQUENCY_CACHE_KEY_PREFIX = "veo:freq:";
+var DEFAULT_TRACKER_FLUSH_INTERVAL_MS = 3e3;
+var DEFAULT_TRACKER_BATCH_SIZE = 5;
+var DEFAULT_TRACKER_MAX_RETRIES = 3;
+var FREQUENCY_CACHE_MAX_ENTRIES = 500;
+var FREQUENCY_CACHE_TTL_MS = 90 * 24 * 60 * 60 * 1e3;
+var WALKTHROUGH_STATE_KEY_PREFIX = "veo:walkthrough_state:";
+var WALKTHROUGH_ABANDONMENT_TIMEOUT_MS = 30 * 60 * 1e3;
+var WALKTHROUGH_STEP_SELECTOR_TIMEOUT_MS = 5e3;
+
+// src/plugins/guides/guide-frequency-cache.ts
+var STATUS_PRIORITY = {
+  shown: 1,
+  dismissed: 2,
+  completed: 2
+};
+function namespaceFromApiKey(apiKey) {
+  return apiKey.slice(-16) || "default";
+}
+var GuideFrequencyCache = class {
+  constructor(namespace) {
+    this.storageKey = `${FREQUENCY_CACHE_KEY_PREFIX}${namespace}`;
+    this.cache = this.load();
+    this.prune();
+  }
+  /**
+   * Decide si una guía debe filtrarse localmente antes de pintarla.
+   *
+   *   - `every_visit` / `always` → nunca filtra (siempre re-pinta).
+   *   - `once` → cualquier entry registrada filtra.
+   *   - `until_dismissed` → solo si `status === 'dismissed'`.
+   */
+  shouldFilter(guideId, displayFrequency) {
+    if (displayFrequency === "every_visit" || displayFrequency === "always") return false;
+    const entry = this.cache.get(guideId);
+    if (!entry) return false;
+    if (displayFrequency === "once") return true;
+    if (displayFrequency === "until_dismissed") return entry.status === "dismissed";
+    return false;
+  }
+  /**
+   * Registra/actualiza la entry de una guía. Nunca degrada un estado más
+   * fuerte (no convierte `dismissed` en `shown` por un re-render). Persiste
+   * cada llamada — escribir a localStorage es lo bastante barato.
+   */
+  record(guideId, status) {
+    const existing = this.cache.get(guideId);
+    if (existing && STATUS_PRIORITY[status] < STATUS_PRIORITY[existing.status]) {
+      return;
+    }
+    this.cache.set(guideId, {
+      guideId,
+      status,
+      lastInteractionAt: Date.now()
+    });
+    this.persist();
+  }
+  /** Limpia el cache (botón "reset" del demo, tests). */
+  clear() {
+    this.cache.clear();
+    this.persist();
+  }
+  /** Útil para debugging — devuelve un snapshot. */
+  snapshot() {
+    return Array.from(this.cache.values());
+  }
+  /**
+   * Limpia entries expiradas por TTL y, si aún excede el límite, descarta
+   * las más viejas hasta caber. Se ejecuta una vez en el constructor; no
+   * vale la pena correrlo a cada lectura.
+   */
+  prune() {
+    const now = Date.now();
+    let mutated = false;
+    for (const [id, entry] of this.cache) {
+      if (now - entry.lastInteractionAt > FREQUENCY_CACHE_TTL_MS) {
+        this.cache.delete(id);
+        mutated = true;
+      }
+    }
+    if (this.cache.size > FREQUENCY_CACHE_MAX_ENTRIES) {
+      const sorted = Array.from(this.cache.entries()).sort(
+        (a, b) => a[1].lastInteractionAt - b[1].lastInteractionAt
+      );
+      const excess = this.cache.size - FREQUENCY_CACHE_MAX_ENTRIES;
+      for (let i = 0; i < excess; i++) {
+        const tuple = sorted[i];
+        if (tuple) this.cache.delete(tuple[0]);
+      }
+      mutated = true;
+    }
+    if (mutated) this.persist();
+  }
+  load() {
+    if (typeof localStorage === "undefined") return /* @__PURE__ */ new Map();
+    try {
+      const raw = localStorage.getItem(this.storageKey);
+      if (!raw) return /* @__PURE__ */ new Map();
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) return /* @__PURE__ */ new Map();
+      const entries = [];
+      for (const item of parsed) {
+        if (item && typeof item === "object" && typeof item.guideId === "string" && typeof item.lastInteractionAt === "number" && ["shown", "dismissed", "completed"].includes(item.status)) {
+          const e = item;
+          entries.push([e.guideId, e]);
+        }
+      }
+      return new Map(entries);
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  persist() {
+    if (typeof localStorage === "undefined") return;
+    try {
+      const serialized = JSON.stringify(Array.from(this.cache.values()));
+      localStorage.setItem(this.storageKey, serialized);
+    } catch {
+    }
+  }
+};
+
+// src/plugins/guides/guide-resolver-client.ts
+var GuideResolverClient = class {
+  constructor(apiUrl, apiKey, debug = false) {
+    this.apiUrl = apiUrl;
+    this.apiKey = apiKey;
+    this.debug = debug;
+  }
+  async resolve(endUserId, pageUrl) {
+    const params = new URLSearchParams({ endUserId, pageUrl });
+    let response;
+    try {
+      response = await fetch(`${this.apiUrl}/v1/guides/resolve?${params.toString()}`, {
+        method: "GET",
+        headers: { "X-Api-Key": this.apiKey },
+        credentials: "omit"
+      });
+    } catch (err) {
+      if (this.debug) console.error("[veo] guides resolve fetch failed:", err);
+      return [];
+    }
+    if (!response.ok) {
+      if (this.debug) console.warn("[veo] guides resolve HTTP", response.status);
+      return [];
+    }
+    try {
+      const data = await response.json();
+      return Array.isArray(data.guides) ? data.guides : [];
+    } catch (err) {
+      if (this.debug) console.error("[veo] guides resolve parse failed:", err);
+      return [];
+    }
+  }
+  /**
+   * Trae una guía específica por ID, sin pasar por la lógica de
+   * activación. La usa el controller para resumir un walkthrough entre
+   * páginas: el `resolve` no devuelve la guía si la URL actual no
+   * matchea, pero el walkthrough activo debe poder consultarla igual.
+   *
+   * El endpoint backend (`GET /v1/guides/:guideId`) devuelve `GuideResponse`,
+   * un superset de `ResolvedGuide` con campos de audit. Acá descartamos los
+   * extra y nos quedamos con el shape que el resto del SDK ya consume.
+   *
+   * Devuelve `null` en cualquier error (404, red, parse) — el caller debe
+   * tratarlo como "guía ya no existe" y cancelar el walkthrough limpiamente.
+   */
+  async fetchById(guideId) {
+    let response;
+    try {
+      response = await fetch(`${this.apiUrl}/v1/guides/${encodeURIComponent(guideId)}`, {
+        method: "GET",
+        headers: { "X-Api-Key": this.apiKey },
+        credentials: "omit"
+      });
+    } catch (err) {
+      if (this.debug) console.error("[veo] guides fetchById network failed:", err);
+      return null;
+    }
+    if (!response.ok) {
+      if (this.debug) console.warn("[veo] guides fetchById HTTP", response.status);
+      return null;
+    }
+    try {
+      const data = await response.json();
+      if (typeof data.guideId !== "string" || typeof data.guideName !== "string" || typeof data.guideType !== "string" || !Array.isArray(data.guideSteps) || !data.activationRules || typeof data.displayFrequency !== "string" || typeof data.displayPriority !== "number") {
+        if (this.debug) console.warn("[veo] guides fetchById: unexpected shape");
+        return null;
+      }
+      return {
+        guideId: data.guideId,
+        guideName: data.guideName,
+        guideType: data.guideType,
+        guideSteps: data.guideSteps,
+        activationRules: data.activationRules,
+        displayFrequency: data.displayFrequency,
+        displayPriority: data.displayPriority
+      };
+    } catch (err) {
+      if (this.debug) console.error("[veo] guides fetchById parse failed:", err);
+      return null;
+    }
+  }
+};
+
+// src/plugins/guides/guide-tracker-client.ts
+function toWire(payload) {
+  const wire = {
+    endUserId: payload.endUserId,
+    interactionType: payload.action
+  };
+  if (payload.sessionId) wire.sessionId = payload.sessionId;
+  if (typeof payload.stepIndex === "number") wire.stepPosition = payload.stepIndex;
+  if (payload.pageUrl) wire.pageUrl = payload.pageUrl;
+  if (payload.pagePath) wire.pagePath = payload.pagePath;
+  return wire;
+}
+var GuideTrackerClient = class {
+  constructor(apiUrl, apiKey) {
+    this.apiUrl = apiUrl;
+    this.apiKey = apiKey;
+  }
+  async send(request) {
+    const url = this.buildUrl(request.guideId);
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "X-Api-Key": this.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(toWire(request.payload)),
+      credentials: "omit"
+    });
+    if (!response.ok) {
+      throw new Error(`guide interaction send failed: HTTP ${response.status}`);
+    }
+  }
+  /**
+   * Envío "fire-and-forget" en pagehide. Devuelve `false` si el navegador
+   * no acepta el beacon (cola llena, no soportado) — en ese caso la queue
+   * sabrá que perdió el envío.
+   */
+  sendBeacon(request) {
+    if (typeof navigator === "undefined" || typeof navigator.sendBeacon !== "function") {
+      return false;
+    }
+    const url = `${this.buildUrl(request.guideId)}?key=${encodeURIComponent(this.apiKey)}`;
+    const blob = new Blob([JSON.stringify(toWire(request.payload))], {
+      type: "application/json"
+    });
+    try {
+      return navigator.sendBeacon(url, blob);
+    } catch {
+      return false;
+    }
+  }
+  buildUrl(guideId) {
+    return `${this.apiUrl}/v1/guides/${encodeURIComponent(guideId)}/interactions`;
+  }
+};
+
+// src/plugins/guides/guide-tracker-queue.ts
+var GuideTrackerQueue = class {
+  constructor(config) {
+    this.config = config;
+    this.buffer = [];
+    this.timer = null;
+    this.flushing = false;
+    this.unloadCleanup = null;
+    this.startTimer();
+    this.installUnloadHandler();
+  }
+  /** Tamaño actual del buffer (útil para debug/stats en el demo). */
+  get size() {
+    return this.buffer.length;
+  }
+  /**
+   * Encola una interaction. Si el buffer alcanza `batchSize`, dispara
+   * `flush()` inmediato.
+   */
+  enqueue(request) {
+    this.buffer.push({
+      guideId: request.guideId,
+      payload: request.payload,
+      attempts: 0,
+      enqueuedAt: Date.now()
+    });
+    if (this.buffer.length >= this.config.batchSize) {
+      void this.flush();
+    }
+  }
+  /**
+   * Envía todo el buffer en paralelo. Items que fallan vuelven al buffer
+   * si todavía tienen reintentos disponibles. Idempotente con respecto a
+   * flushes concurrentes (el segundo es un no-op).
+   */
+  async flush() {
+    if (this.flushing || this.buffer.length === 0) return;
+    this.flushing = true;
+    const batch = this.buffer.splice(0, this.buffer.length);
+    const results = await Promise.allSettled(
+      batch.map(
+        (item) => this.config.client.send({ guideId: item.guideId, payload: item.payload })
+      )
+    );
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      const item = batch[i];
+      if (!result || !item) continue;
+      if (result.status === "fulfilled") continue;
+      item.attempts += 1;
+      if (item.attempts < this.config.maxRetries) {
+        this.buffer.push(item);
+      } else {
+        this.safeOnError(result.reason, item);
+      }
+    }
+    this.flushing = false;
+  }
+  /**
+   * Drena el buffer vía `sendBeacon`. Síncrono, sin retry. Para pagehide.
+   */
+  flushBeacon() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0, this.buffer.length);
+    for (const item of batch) {
+      this.config.client.sendBeacon({ guideId: item.guideId, payload: item.payload });
+    }
+  }
+  destroy() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.unloadCleanup?.();
+    this.unloadCleanup = null;
+  }
+  startTimer() {
+    if (typeof window === "undefined") return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.config.flushIntervalMs);
+  }
+  installUnloadHandler() {
+    if (typeof window === "undefined") return;
+    const onPagehide = () => this.flushBeacon();
+    const onVisibility = () => {
+      if (document.visibilityState === "hidden") this.flushBeacon();
+    };
+    window.addEventListener("pagehide", onPagehide);
+    window.addEventListener("visibilitychange", onVisibility);
+    this.unloadCleanup = () => {
+      window.removeEventListener("pagehide", onPagehide);
+      window.removeEventListener("visibilitychange", onVisibility);
+    };
+  }
+  safeOnError(reason, item) {
+    if (!this.config.onError) return;
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    try {
+      this.config.onError(error, item);
+    } catch {
+    }
+  }
+};
+
+// src/plugins/guides/block-builder.ts
+function buildStepContent(step, doc, callbacks) {
+  const container = doc.createElement("div");
+  container.className = "veo-guide-content";
+  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-guide-actions";
+  if (typeof step.ctaText === "string" && step.ctaText) {
+    const cta = doc.createElement("button");
+    cta.type = "button";
+    cta.className = "veo-guide-cta";
+    cta.textContent = step.ctaText;
+    cta.addEventListener("click", () => {
+      const action = step.ctaAction ?? "dismiss";
+      const ctaUrl = readCtaUrl(step);
+      callbacks.onCtaClick(action, ctaUrl);
+    });
+    actions.appendChild(cta);
+  }
+  container.appendChild(actions);
+  const closeBtn = doc.createElement("button");
+  closeBtn.type = "button";
+  closeBtn.className = "veo-guide-close";
+  closeBtn.setAttribute("aria-label", "Cerrar");
+  closeBtn.textContent = "\xD7";
+  closeBtn.addEventListener("click", () => callbacks.onDismiss());
+  container.appendChild(closeBtn);
+  return container;
+}
+function isSafeUrl(url) {
+  if (typeof url !== "string" || url.length === 0) return false;
+  try {
+    const base = typeof window !== "undefined" ? window.location.href : "http://localhost/";
+    const parsed = new URL(url, base);
+    return SAFE_URL_PROTOCOLS.includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}
+function readCtaUrl(step) {
+  const candidate = step.style?.ctaUrl;
+  if (typeof candidate !== "string") return void 0;
+  return isSafeUrl(candidate) ? candidate : void 0;
+}
+
+// src/plugins/guides/styles.ts
+var GUIDE_STYLES = `
+:host {
+  --veo-primary: #4f46e5;
+  --veo-text: #1f2937;
+  --veo-text-secondary: #4b5563;
+  --veo-bg: #ffffff;
+  --veo-radius: 12px;
+  --veo-shadow: 0 20px 60px rgba(0, 0, 0, 0.25);
+  all: initial;
+}
+* { box-sizing: border-box; font-family: -apple-system, system-ui, "Segoe UI", Roboto, sans-serif; }
+
+.veo-modal-overlay {
+  position: fixed; inset: 0;
+  background: rgba(15, 15, 30, 0.45);
+  display: flex; align-items: center; justify-content: center;
+  z-index: ${GUIDE_Z_INDEX};
+  animation: veo-fade-in 180ms ease-out;
+}
+.veo-modal-card {
+  background: var(--veo-bg);
+  border-radius: var(--veo-radius);
+  padding: 24px 28px;
+  max-width: 420px; width: 90%;
+  position: relative;
+  box-shadow: var(--veo-shadow);
+  animation: veo-slide-up 220ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.veo-banner {
+  position: fixed; left: 0; right: 0;
+  background: var(--veo-bg);
+  padding: 14px 20px;
+  z-index: ${GUIDE_Z_INDEX};
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.12);
+  animation: veo-slide-down 200ms ease-out;
+}
+.veo-banner-top { top: 0; }
+.veo-banner-bottom { bottom: 0; }
+
+.veo-tooltip {
+  position: absolute;
+  background: var(--veo-bg);
+  border-radius: var(--veo-radius);
+  padding: 14px 16px;
+  max-width: 300px;
+  z-index: ${GUIDE_Z_INDEX};
+  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.18);
+  animation: veo-fade-in 150ms ease-out;
+}
+
+.veo-guide-content {
+  position: relative;
+  display: flex; flex-direction: column;
+}
+.veo-guide-image {
+  display: block; width: 100%; max-height: 180px;
+  object-fit: cover; border-radius: 8px;
+  margin-bottom: 12px;
+}
+.veo-guide-title {
+  font-size: 18px; font-weight: 600; line-height: 1.3;
+  margin: 0 0 6px; color: var(--veo-text);
+}
+.veo-guide-text {
+  font-size: 14px; line-height: 1.5;
+  margin: 0 0 16px; color: var(--veo-text-secondary);
+}
+.veo-guide-actions {
+  display: flex; gap: 8px; justify-content: flex-end;
+}
+.veo-guide-cta {
+  background: var(--veo-primary); color: #fff; border: none;
+  padding: 9px 18px; border-radius: 8px;
+  font-size: 14px; font-weight: 500; cursor: pointer;
+  transition: opacity 120ms ease;
+}
+.veo-guide-cta:hover { opacity: 0.9; }
+.veo-guide-cta:active { transform: translateY(1px); }
+.veo-guide-close {
+  position: absolute; top: -6px; right: -6px;
+  width: 24px; height: 24px;
+  background: none; border: none;
+  font-size: 22px; line-height: 1;
+  cursor: pointer; color: #9ca3af; padding: 0;
+}
+.veo-guide-close:hover { color: var(--veo-text); }
+
+.veo-walkthrough {
+  position: absolute;
+  background: var(--veo-bg);
+  border-radius: var(--veo-radius);
+  padding: 16px;
+  max-width: 340px;
+  z-index: ${GUIDE_Z_INDEX};
+  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.2);
+  animation: veo-fade-in 150ms ease-out;
+}
+.veo-walkthrough-counter {
+  font-size: 11px; color: #9ca3af;
+  margin-bottom: 8px; letter-spacing: 0.02em;
+}
+.veo-walkthrough-progress {
+  display: flex; gap: 4px;
+  margin-bottom: 12px;
+}
+.veo-walkthrough-progress-dot {
+  width: 8px; height: 8px;
+  border-radius: 50%;
+  background: #e5e7eb;
+  transition: background 200ms ease;
+}
+.veo-walkthrough-progress-dot.active { background: var(--veo-primary); }
+.veo-walkthrough-progress-dot.completed { background: var(--veo-primary); opacity: 0.5; }
+.veo-walkthrough-actions {
+  display: flex; align-items: center;
+  margin-top: 16px; gap: 8px;
+}
+.veo-walkthrough-actions-right {
+  display: flex; gap: 8px;
+  margin-left: auto;
+}
+.veo-walkthrough-btn-secondary {
+  background: transparent; color: #6b7280;
+  border: 1px solid #e5e7eb;
+  padding: 8px 16px; border-radius: 8px;
+  font-size: 13px; cursor: pointer;
+  transition: background 120ms ease;
+}
+.veo-walkthrough-btn-secondary:hover { background: #f9fafb; }
+.veo-walkthrough-skip {
+  background: transparent; color: #9ca3af;
+  border: none; padding: 4px 8px;
+  font-size: 12px; cursor: pointer;
+}
+.veo-walkthrough-skip:hover { color: var(--veo-text); }
+
+.veo-custom-floating {
+  position: fixed;
+  z-index: ${GUIDE_Z_INDEX};
+  max-width: calc(100vw - 16px);
+  max-height: calc(100vh - 16px);
+  animation: veo-fade-in 160ms ease;
+}
+.veo-custom-anchored {
+  position: fixed;
+  top: 0; left: 0;
+  z-index: ${GUIDE_Z_INDEX};
+  max-width: calc(100vw - 16px);
+  animation: veo-fade-in 160ms ease;
+}
+.veo-custom-frame {
+  display: block;
+  border: 0;
+  width: 360px;
+  background: transparent;
+  color-scheme: normal;
+}
+
+@keyframes veo-fade-in { from { opacity: 0; } to { opacity: 1; } }
+@keyframes veo-slide-up {
+  from { transform: translateY(10px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+@keyframes veo-slide-down {
+  from { transform: translateY(-10px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+`;
+
+// src/plugins/guides/renderers/base-renderer.ts
+var BaseRenderer = class {
+  constructor() {
+    this.host = null;
+    this.shadow = null;
+    this.cleanups = [];
+  }
+  /**
+   * Crea un `<div data-veo-guide>` adjunto a `document.body`, le adjunta
+   * un ShadowRoot abierto e inyecta los estilos. Retorna el nodo raíz
+   * donde la subclase puede insertar el contenido específico.
+   */
+  createHost() {
+    const host = document.createElement("div");
+    host.setAttribute(GUIDE_HOST_ATTR, "");
+    const shadow = host.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = GUIDE_STYLES;
+    shadow.appendChild(style);
+    const root = document.createElement("div");
+    shadow.appendChild(root);
+    document.body.appendChild(host);
+    this.host = host;
+    this.shadow = shadow;
+    return { host, shadow, root };
+  }
+  /**
+   * Registra una función a ejecutar en `destroy()`. Útil para limpiar
+   * listeners globales (scroll, resize) o intervalos.
+   */
+  registerCleanup(fn) {
+    this.cleanups.push(fn);
+  }
+  /** 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/banner-renderer.ts
+var BannerRenderer = class extends BaseRenderer {
+  render(context) {
+    const step = context.guide.guideSteps[0];
+    if (!step) return;
+    const { root } = this.createHost();
+    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: 0,
+        action
+      });
+      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);
+      },
+      onDismiss: () => dismiss("dismissed")
+    });
+    banner.appendChild(content);
+    root.appendChild(banner);
+    context.onInteraction({
+      guideId: context.guide.guideId,
+      stepIndex: 0,
+      action: "shown"
+    });
+  }
+};
+
+// 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/renderers/custom-renderer.ts
+var DEFAULT_PLACEMENT = { mode: "floating", position: "bottom-right" };
+var DEFAULT_OFFSET = 16;
+var DEFAULT_WIDTH = 360;
+var CustomRenderer = class extends BaseRenderer {
+  async render(context) {
+    const step = context.guide.guideSteps[0];
+    if (!step || typeof step.html !== "string" || step.html.length === 0) return;
+    const placement = step.placement ?? DEFAULT_PLACEMENT;
+    let anchor = null;
+    if (placement.mode === "anchored") {
+      const selector = placement.selector ?? step.selector ?? context.guide.activationRules.selector;
+      if (typeof selector !== "string" || selector.length === 0) return;
+      anchor = await waitForElement(selector);
+      if (!anchor) return;
+    }
+    const { root } = this.createHost();
+    const doc = root.ownerDocument ?? document;
+    const wrapper = doc.createElement("div");
+    wrapper.className = placement.mode === "anchored" ? "veo-custom-anchored" : "veo-custom-floating";
+    const iframe = doc.createElement("iframe");
+    iframe.className = "veo-custom-frame";
+    iframe.setAttribute("sandbox", "allow-scripts");
+    iframe.setAttribute("title", context.guide.guideName || "Veo");
+    iframe.style.width = toCssSize(placement.width ?? DEFAULT_WIDTH);
+    const hasFixedHeight = placement.height !== void 0 && placement.height !== null;
+    if (hasFixedHeight) {
+      iframe.style.height = toCssSize(placement.height);
+    }
+    const token = uuidv7();
+    iframe.srcdoc = buildSrcdoc(step.html, step.css ?? "", step.js ?? "", token);
+    wrapper.appendChild(iframe);
+    root.appendChild(wrapper);
+    if (placement.mode === "floating") {
+      applyFloatingPosition(wrapper, placement);
+    } else if (anchor) {
+      this.registerCleanup(await this.setupAnchoredPosition(anchor, wrapper, placement));
+    }
+    const close = () => context.onClose();
+    const onMessage = (event) => {
+      if (event.source !== iframe.contentWindow) return;
+      const data = event.data;
+      if (!data || typeof data !== "object" || data.__veo !== token) return;
+      switch (data.type) {
+        case "dismiss":
+          context.onInteraction({
+            guideId: context.guide.guideId,
+            stepIndex: 0,
+            action: "dismissed"
+          });
+          close();
+          break;
+        case "cta":
+          context.onInteraction({
+            guideId: context.guide.guideId,
+            stepIndex: 0,
+            action: "cta_clicked"
+          });
+          if (typeof data.url === "string" && isSafeUrl(data.url)) {
+            window.open(data.url, "_blank", "noopener,noreferrer");
+          }
+          if (data.close !== false) close();
+          break;
+        case "navigate":
+          if (typeof data.url === "string" && isSafeUrl(data.url)) {
+            window.location.assign(data.url);
+          }
+          break;
+        case "track":
+          if (typeof data.name === "string" && context.onTrack) {
+            context.onTrack(data.name, isRecord(data.props) ? data.props : void 0);
+          }
+          break;
+        case "resize":
+          if (!hasFixedHeight && typeof data.height === "number" && data.height > 0) {
+            iframe.style.height = `${Math.ceil(data.height)}px`;
+          }
+          break;
+      }
+    };
+    window.addEventListener("message", onMessage);
+    this.registerCleanup(() => window.removeEventListener("message", onMessage));
+    context.onInteraction({ guideId: context.guide.guideId, stepIndex: 0, action: "shown" });
+  }
+  async setupAnchoredPosition(anchor, wrapper, placement) {
+    const side = placement.side ?? "bottom";
+    const update = async () => {
+      const { x, y } = await computePosition(anchor, wrapper, {
+        placement: side,
+        strategy: "fixed",
+        middleware: [offset(placement.offsetY ?? 8), flip(), shift({ padding: 8 })]
+      });
+      wrapper.style.left = `${x}px`;
+      wrapper.style.top = `${y}px`;
+    };
+    await update();
+    const reposition = () => {
+      void update();
+    };
+    window.addEventListener("scroll", reposition, true);
+    window.addEventListener("resize", reposition);
+    return () => {
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition);
+    };
+  }
+};
+function toCssSize(value) {
+  return typeof value === "number" ? `${value}px` : value;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function applyFloatingPosition(wrapper, placement) {
+  const position = placement.position ?? "bottom-right";
+  const ox = `${placement.offsetX ?? DEFAULT_OFFSET}px`;
+  const oy = `${placement.offsetY ?? DEFAULT_OFFSET}px`;
+  const s = wrapper.style;
+  if (position === "center") {
+    s.top = "50%";
+    s.left = "50%";
+    s.transform = "translate(-50%, -50%)";
+    return;
+  }
+  const [vertical, horizontal] = position.split("-");
+  if (vertical === "top") s.top = oy;
+  else s.bottom = oy;
+  if (horizontal === "left") {
+    s.left = ox;
+  } else if (horizontal === "right") {
+    s.right = ox;
+  } else {
+    s.left = "50%";
+    s.transform = "translateX(-50%)";
+  }
+}
+function buildSrcdoc(html, css, js, token) {
+  const bridge = `(function(){var T=${JSON.stringify(token)};function P(m){m.__veo=T;parent.postMessage(m,'*');}window.veo={dismiss:function(){P({type:'dismiss'});},cta:function(u){P({type:'cta',url:u});},track:function(n,p){P({type:'track',name:n,props:p||{}});},navigate:function(u){P({type:'navigate',url:u});}};function H(){P({type:'resize',height:Math.ceil(document.documentElement.scrollHeight)});}window.addEventListener('load',H);try{if(typeof ResizeObserver!=='undefined'){new ResizeObserver(H).observe(document.documentElement);}}catch(e){}})();`;
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><style>html,body{margin:0;padding:0;background:transparent;}</style><style>${escapeClosing(css, "style")}</style></head><body>${html}<script>${bridge}</script>` + (js ? `<script>${escapeClosing(js, "script")}</script>` : "") + "</body></html>";
+}
+function escapeClosing(code, tag) {
+  const rx = tag === "script" ? /<\/script/gi : /<\/style/gi;
+  return code.replace(rx, `<\\/${tag}`);
+}
+
+// src/plugins/guides/renderers/modal-renderer.ts
+var ModalRenderer = class extends BaseRenderer {
+  render(context) {
+    const step = context.guide.guideSteps[0];
+    if (!step) return;
+    const { root } = this.createHost();
+    const ownerDocument = root.ownerDocument ?? document;
+    const overlay = ownerDocument.createElement("div");
+    overlay.className = "veo-modal-overlay";
+    const card = ownerDocument.createElement("div");
+    card.className = "veo-modal-card";
+    const dismiss = (action, ctaUrl) => {
+      context.onInteraction({
+        guideId: context.guide.guideId,
+        stepIndex: 0,
+        action
+      });
+      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);
+      },
+      onDismiss: () => dismiss("dismissed")
+    });
+    card.appendChild(content);
+    overlay.appendChild(card);
+    root.appendChild(overlay);
+    overlay.addEventListener("click", (e) => {
+      if (e.target === overlay) dismiss("dismissed");
+    });
+    const onKey = (e) => {
+      if (e.key === "Escape") dismiss("dismissed");
+    };
+    document.addEventListener("keydown", onKey);
+    this.registerCleanup(() => document.removeEventListener("keydown", onKey));
+    context.onInteraction({
+      guideId: context.guide.guideId,
+      stepIndex: 0,
+      action: "shown"
+    });
+  }
+};
+var TooltipRenderer = class extends BaseRenderer {
+  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 { root } = this.createHost();
+    const ownerDocument = root.ownerDocument ?? document;
+    const tooltip = ownerDocument.createElement("div");
+    tooltip.className = "veo-tooltip";
+    const dismiss = (action, ctaUrl) => {
+      context.onInteraction({
+        guideId: context.guide.guideId,
+        stepIndex: 0,
+        action
+      });
+      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);
+      },
+      onDismiss: () => dismiss("dismissed")
+    });
+    tooltip.appendChild(content);
+    root.appendChild(tooltip);
+    const updatePosition = async () => {
+      const { x, y } = await computePosition(anchor, tooltip, {
+        placement: "bottom",
+        middleware: [offset(8), flip(), shift({ padding: 8 })]
+      });
+      tooltip.style.left = `${x}px`;
+      tooltip.style.top = `${y}px`;
+    };
+    await updatePosition();
+    const reposition = () => {
+      void updatePosition();
+    };
+    window.addEventListener("scroll", reposition, true);
+    window.addEventListener("resize", reposition);
+    this.registerCleanup(() => {
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition);
+    });
+    context.onInteraction({
+      guideId: context.guide.guideId,
+      stepIndex: 0,
+      action: "shown"
+    });
+  }
+};
+
+// 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);
+  return container;
+}
+
+// src/plugins/guides/renderers/walkthrough-renderer.ts
+var WalkthroughRenderer = class extends BaseRenderer {
+  async render(context) {
+    const step = context.guide.guideSteps[context.currentStepIndex];
+    if (!step) return false;
+    const selector = step.selector ?? context.guide.activationRules.selector;
+    if (typeof selector !== "string" || selector.length === 0) return false;
+    const anchor = await waitForElement(selector, WALKTHROUGH_STEP_SELECTOR_TIMEOUT_MS);
+    if (!anchor) return false;
+    const { root } = this.createHost();
+    const ownerDocument = root.ownerDocument ?? document;
+    const tooltip = ownerDocument.createElement("div");
+    tooltip.className = "veo-walkthrough";
+    const content = buildWalkthroughStepContent(
+      step,
+      context.currentStepIndex,
+      context.guide.guideSteps.length,
+      ownerDocument,
+      context.callbacks
+    );
+    tooltip.appendChild(content);
+    root.appendChild(tooltip);
+    const updatePosition = async () => {
+      const { x, y } = await computePosition(anchor, tooltip, {
+        placement: "bottom",
+        middleware: [offset(8), flip(), shift({ padding: 8 })]
+      });
+      tooltip.style.left = `${x}px`;
+      tooltip.style.top = `${y}px`;
+    };
+    await updatePosition();
+    const reposition = () => {
+      void updatePosition();
+    };
+    window.addEventListener("scroll", reposition, true);
+    window.addEventListener("resize", reposition);
+    this.registerCleanup(() => {
+      window.removeEventListener("scroll", reposition, true);
+      window.removeEventListener("resize", reposition);
+    });
+    return true;
+  }
+};
+
+// src/plugins/guides/walkthrough-state.ts
+var WalkthroughStateManager = class {
+  constructor(namespace) {
+    this.state = null;
+    this.storageKey = `${WALKTHROUGH_STATE_KEY_PREFIX}${namespace}`;
+    this.state = this.load();
+    if (this.state && this.isAbandoned(this.state)) {
+      this.clear();
+    }
+  }
+  /**
+   * Estado del walkthrough activo. Devuelve `null` si no hay ninguno o si
+   * el último progreso fue hace más del timeout (en ese caso también
+   * limpia el storage como side-effect).
+   */
+  current() {
+    if (!this.state) return null;
+    if (this.isAbandoned(this.state)) {
+      this.clear();
+      return null;
+    }
+    return this.state;
+  }
+  /** Atajo legible para el controller. */
+  hasActive() {
+    return this.current() !== null;
+  }
+  /**
+   * Inicia un nuevo walkthrough en step 0. Sobreescribe cualquier estado
+   * previo — los callers (controller) son responsables de verificar
+   * `hasActive()` antes si necesitan exclusividad.
+   */
+  start(guideId, totalSteps) {
+    const now = Date.now();
+    this.state = {
+      guideId,
+      totalSteps,
+      currentStepIndex: 0,
+      startedAt: now,
+      lastProgressAt: now
+    };
+    this.persist();
+    return this.state;
+  }
+  /**
+   * Avanza al siguiente step. Si el step resultante excede `totalSteps`,
+   * devuelve `null` y NO toca el estado — el controller debe interpretar
+   * eso como "ya estamos en el último, no hay próximo" y disparar
+   * `complete` vía el handler del botón "Finalizar".
+   */
+  advance() {
+    if (!this.state) return null;
+    const next = this.state.currentStepIndex + 1;
+    if (next >= this.state.totalSteps) return null;
+    this.state = {
+      ...this.state,
+      currentStepIndex: next,
+      lastProgressAt: Date.now()
+    };
+    this.persist();
+    return this.state;
+  }
+  /**
+   * Retrocede al step anterior. En step 0 no hace nada y devuelve el
+   * estado tal cual (el botón "Atrás" no debería estar visible en el
+   * primer step, pero por defensa el manager también lo guard-ea).
+   */
+  back() {
+    if (!this.state) return null;
+    if (this.state.currentStepIndex === 0) return this.state;
+    this.state = {
+      ...this.state,
+      currentStepIndex: this.state.currentStepIndex - 1,
+      lastProgressAt: Date.now()
+    };
+    this.persist();
+    return this.state;
+  }
+  /** Limpia el estado activo (skip, complete, abandono, guía borrada). */
+  clear() {
+    this.state = null;
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.removeItem(this.storageKey);
+    } catch {
+    }
+  }
+  isAbandoned(state) {
+    return Date.now() - state.lastProgressAt > WALKTHROUGH_ABANDONMENT_TIMEOUT_MS;
+  }
+  load() {
+    if (typeof localStorage === "undefined") return null;
+    try {
+      const raw = localStorage.getItem(this.storageKey);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object") return null;
+      const candidate = parsed;
+      if (typeof candidate.guideId !== "string" || typeof candidate.totalSteps !== "number" || typeof candidate.currentStepIndex !== "number" || typeof candidate.startedAt !== "number" || typeof candidate.lastProgressAt !== "number") {
+        return null;
+      }
+      return candidate;
+    } catch {
+      return null;
+    }
+  }
+  persist() {
+    if (typeof localStorage === "undefined" || !this.state) return;
+    try {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.state));
+    } catch {
+    }
+  }
+};
+
+// src/plugins/guides/guides-controller.ts
+var STATUS_BY_ACTION = {
+  shown: "shown",
+  dismissed: "dismissed",
+  cta_clicked: null,
+  step_advanced: null,
+  step_back: null,
+  completed: "completed"
+};
+var GuidesController = class {
+  constructor(client, config) {
+    this.client = client;
+    this.activeRenderers = /* @__PURE__ */ new Set();
+    this.dispatched = /* @__PURE__ */ new Set();
+    this.activeWalkthroughRenderer = null;
+    this.activeWalkthroughGuide = null;
+    this.debug = config.debug === true;
+    this.resolver = config.resolver ?? new GuideResolverClient(config.apiUrl, config.apiKey, this.debug);
+    if (config.trackerQueue) {
+      this.trackerQueue = config.trackerQueue;
+    } else {
+      const httpClient = new GuideTrackerClient(config.apiUrl, config.apiKey);
+      this.trackerQueue = new GuideTrackerQueue({
+        client: httpClient,
+        flushIntervalMs: DEFAULT_TRACKER_FLUSH_INTERVAL_MS,
+        batchSize: DEFAULT_TRACKER_BATCH_SIZE,
+        maxRetries: DEFAULT_TRACKER_MAX_RETRIES,
+        onError: (err, item) => {
+          if (this.debug) {
+            console.warn(
+              `[veo] dropped guide interaction after retries: guideId=${item.guideId} action=${item.payload.action}`,
+              err
+            );
+          }
+        }
+      });
+    }
+    const namespace = namespaceFromApiKey(config.apiKey);
+    this.frequencyCache = config.frequencyCache ?? new GuideFrequencyCache(namespace);
+    this.walkthroughState = config.walkthroughState ?? new WalkthroughStateManager(namespace);
+  }
+  /** Cuántas interactions hay pendientes de envío. Útil para debug en demo. */
+  get pendingInteractions() {
+    return this.trackerQueue.size;
+  }
+  /** Limpia el cache local (botón "reset" del demo, tests). */
+  clearFrequencyCache() {
+    this.frequencyCache.clear();
+  }
+  /** Limpia el walkthrough activo (debug del demo). */
+  clearWalkthroughState() {
+    this.tearDownWalkthrough();
+  }
+  /** Punto de entrada principal. Llamado en cada pageview/identify. */
+  async checkGuides(pageUrl, sessionId) {
+    const endUserId = this.client.getEndUserId();
+    if (!endUserId) {
+      if (this.debug) console.log("[veo] guides: skipped, no endUserId yet");
+      return;
+    }
+    if (await this.tryResumeWalkthrough(endUserId, sessionId, pageUrl)) {
+      return;
+    }
+    let guides;
+    try {
+      guides = await this.resolver.resolve(endUserId, pageUrl);
+    } catch (err) {
+      if (this.debug) console.error("[veo] guides resolver threw:", err);
+      return;
+    }
+    if (this.debug) console.log(`[veo] guides: ${guides.length} eligible at ${pageUrl}`);
+    for (const guide of guides) {
+      if (this.frequencyCache.shouldFilter(guide.guideId, guide.displayFrequency)) {
+        if (this.debug) console.log(`[veo] guides: filtered locally guideId=${guide.guideId}`);
+        continue;
+      }
+      if (guide.guideType === "walkthrough" && guide.guideSteps.length > 1) {
+        if (this.walkthroughState.hasActive()) {
+          if (this.debug)
+            console.log(`[veo] guides: walkthrough ${guide.guideId} skipped (another active)`);
+          continue;
+        }
+        await this.startWalkthrough(guide, endUserId, sessionId, pageUrl);
+        continue;
+      }
+      this.runSingleStepRender(guide, sessionId, pageUrl);
+    }
+  }
+  /** Cierra todas las guías activas, limpia cache de dispatch y para timers. */
+  destroy() {
+    for (const renderer of this.activeRenderers) {
+      try {
+        renderer.destroy();
+      } catch (err) {
+        if (this.debug) console.error("[veo] renderer destroy failed:", err);
+      }
+    }
+    this.activeRenderers.clear();
+    if (this.activeWalkthroughRenderer) {
+      try {
+        this.activeWalkthroughRenderer.destroy();
+      } catch {
+      }
+      this.activeWalkthroughRenderer = null;
+      this.activeWalkthroughGuide = null;
+    }
+    this.dispatched.clear();
+    this.trackerQueue.destroy();
+  }
+  runSingleStepRender(guide, sessionId, pageUrl) {
+    const renderer = this.createSingleStepRenderer(guide.guideType);
+    if (!renderer) return;
+    const delayMs = guide.activationRules.delayMs ?? 0;
+    window.setTimeout(
+      () => this.mountSingleStepRenderer(guide, renderer, sessionId, pageUrl),
+      delayMs
+    );
+  }
+  mountSingleStepRenderer(guide, renderer, sessionId, pageUrl) {
+    this.activeRenderers.add(renderer);
+    const onClose = () => {
+      renderer.destroy();
+      this.activeRenderers.delete(renderer);
+    };
+    const onInteraction = (event) => {
+      this.handleInteraction(guide, sessionId, pageUrl, event);
+    };
+    const onTrack = (eventName, properties) => {
+      this.client.track(eventName, properties);
+    };
+    try {
+      void renderer.render({ guide, onInteraction, onClose, onTrack });
+    } catch (err) {
+      if (this.debug) console.error("[veo] renderer.render threw:", err);
+      this.activeRenderers.delete(renderer);
+    }
+  }
+  /**
+   * Si hay un walkthrough persistido, intenta pintar el step actual en
+   * la página actual. Retorna `true` si lo intentó (sea éxito o cancel),
+   * `false` si no había walkthrough activo.
+   *
+   * Cancela limpiamente (sin enviar `dismissed` falso) cuando:
+   *   - La guía fue eliminada en el backend (404 → `fetchById` devuelve null).
+   *   - La guía cambió de tipo y ya no es walkthrough.
+   *   - El selector del step actual no aparece dentro del timeout.
+   */
+  async tryResumeWalkthrough(endUserId, sessionId, pageUrl) {
+    const state = this.walkthroughState.current();
+    if (!state) return false;
+    const guide = await this.resolver.fetchById(state.guideId);
+    if (!guide || guide.guideType !== "walkthrough") {
+      if (this.debug)
+        console.log(`[veo] guides: walkthrough ${state.guideId} no longer available, cleaning up`);
+      this.tearDownWalkthrough();
+      return true;
+    }
+    const stepIndex = Math.min(state.currentStepIndex, guide.guideSteps.length - 1);
+    await this.renderWalkthroughStep(guide, stepIndex, endUserId, sessionId, pageUrl);
+    return true;
+  }
+  async startWalkthrough(guide, endUserId, sessionId, pageUrl) {
+    this.walkthroughState.start(guide.guideId, guide.guideSteps.length);
+    const rendered = await this.renderWalkthroughStep(guide, 0, endUserId, sessionId, pageUrl);
+    if (!rendered) return;
+    this.enqueueInteractionOnce(guide.guideId, endUserId, sessionId, pageUrl, "shown", 0);
+    this.frequencyCache.record(guide.guideId, "shown");
+  }
+  /**
+   * Pinta el step indicado. Reusa la guía (no fetcha): el caller debe
+   * traerla. Retorna `true` si el render fue exitoso. En caso contrario
+   * ya disparó el teardown — el caller no debe seguir reportando.
+   */
+  async renderWalkthroughStep(guide, stepIndex, endUserId, sessionId, pageUrl) {
+    if (this.activeWalkthroughRenderer) {
+      this.activeWalkthroughRenderer.destroy();
+      this.activeWalkthroughRenderer = null;
+    }
+    const renderer = new WalkthroughRenderer();
+    this.activeWalkthroughGuide = guide;
+    const callbacks = {
+      onNext: () => this.handleWalkthroughNext(endUserId, sessionId, pageUrl),
+      onBack: () => this.handleWalkthroughBack(endUserId, sessionId, pageUrl),
+      onSkip: () => this.handleWalkthroughSkip(endUserId, sessionId, pageUrl),
+      onComplete: () => this.handleWalkthroughComplete(endUserId, sessionId, pageUrl)
+    };
+    let success = false;
+    try {
+      success = await renderer.render({ guide, currentStepIndex: stepIndex, callbacks });
+    } catch (err) {
+      if (this.debug) console.error("[veo] walkthrough renderer threw:", err);
+    }
+    if (!success) {
+      if (this.debug)
+        console.warn(
+          `[veo] walkthrough ${guide.guideId} step ${stepIndex} could not render, cancelling`
+        );
+      this.tearDownWalkthrough();
+      return false;
+    }
+    this.activeWalkthroughRenderer = renderer;
+    return true;
+  }
+  handleWalkthroughNext(endUserId, sessionId, pageUrl) {
+    const guide = this.activeWalkthroughGuide;
+    if (!guide) return;
+    const newState = this.walkthroughState.advance();
+    if (!newState) {
+      this.handleWalkthroughComplete(endUserId, sessionId, pageUrl);
+      return;
+    }
+    this.enqueueInteraction(
+      guide.guideId,
+      endUserId,
+      sessionId,
+      pageUrl,
+      "step_advanced",
+      newState.currentStepIndex
+    );
+    void this.renderWalkthroughStep(
+      guide,
+      newState.currentStepIndex,
+      endUserId,
+      sessionId,
+      pageUrl
+    );
+  }
+  handleWalkthroughBack(endUserId, sessionId, pageUrl) {
+    const guide = this.activeWalkthroughGuide;
+    if (!guide) return;
+    const state = this.walkthroughState.current();
+    if (!state || state.currentStepIndex === 0) return;
+    const newState = this.walkthroughState.back();
+    if (!newState) return;
+    this.enqueueInteraction(
+      guide.guideId,
+      endUserId,
+      sessionId,
+      pageUrl,
+      "step_back",
+      newState.currentStepIndex
+    );
+    void this.renderWalkthroughStep(
+      guide,
+      newState.currentStepIndex,
+      endUserId,
+      sessionId,
+      pageUrl
+    );
+  }
+  handleWalkthroughSkip(endUserId, sessionId, pageUrl) {
+    const guide = this.activeWalkthroughGuide;
+    const state = this.walkthroughState.current();
+    if (!guide || !state) return;
+    this.enqueueInteraction(
+      guide.guideId,
+      endUserId,
+      sessionId,
+      pageUrl,
+      "dismissed",
+      state.currentStepIndex
+    );
+    this.frequencyCache.record(guide.guideId, "dismissed");
+    this.tearDownWalkthrough();
+  }
+  handleWalkthroughComplete(endUserId, sessionId, pageUrl) {
+    const guide = this.activeWalkthroughGuide;
+    const state = this.walkthroughState.current();
+    if (!guide || !state) return;
+    this.enqueueInteraction(
+      guide.guideId,
+      endUserId,
+      sessionId,
+      pageUrl,
+      "completed",
+      state.currentStepIndex
+    );
+    this.frequencyCache.record(guide.guideId, "completed");
+    this.tearDownWalkthrough();
+  }
+  tearDownWalkthrough() {
+    if (this.activeWalkthroughRenderer) {
+      try {
+        this.activeWalkthroughRenderer.destroy();
+      } catch {
+      }
+    }
+    this.activeWalkthroughRenderer = null;
+    this.activeWalkthroughGuide = null;
+    this.walkthroughState.clear();
+  }
+  /**
+   * Tras cada interaction single-step:
+   *   1. dedupe (no enviar 2× la misma `(guideId, action)` por sesión)
+   *   2. actualizar el cache local si corresponde
+   *   3. encolar el POST
+   *
+   * El endUserId se lee del client EN ESTE MOMENTO (no en el render),
+   * por si el usuario se identificó después de que la guía apareció.
+   */
+  handleInteraction(guide, sessionId, pageUrl, event) {
+    const dedupKey = `${guide.guideId}:${event.action}`;
+    if (this.dispatched.has(dedupKey)) {
+      if (this.debug) console.log(`[veo] guides: dedup hit ${dedupKey}`);
+      return;
+    }
+    this.dispatched.add(dedupKey);
+    const cacheStatus = STATUS_BY_ACTION[event.action];
+    if (cacheStatus) this.frequencyCache.record(guide.guideId, cacheStatus);
+    const endUserId = this.client.getEndUserId();
+    if (!endUserId) {
+      if (this.debug)
+        console.warn("[veo] guides: interaction without endUserId \u2014 skipping enqueue");
+      return;
+    }
+    this.trackerQueue.enqueue({
+      guideId: guide.guideId,
+      payload: {
+        endUserId,
+        sessionId,
+        action: event.action,
+        stepIndex: event.stepIndex,
+        pageUrl,
+        pagePath: extractPath(pageUrl)
+      }
+    });
+  }
+  /**
+   * Encola una interacción de walkthrough SIN pasar por el dedup set.
+   * Acciones como `step_advanced` se repiten naturalmente (cada next es
+   * una navegación distinta) y deduplicarlas perdería datos.
+   */
+  enqueueInteraction(guideId, endUserId, sessionId, pageUrl, action, stepIndex) {
+    this.trackerQueue.enqueue({
+      guideId,
+      payload: {
+        endUserId,
+        sessionId,
+        action,
+        stepIndex,
+        pageUrl,
+        pagePath: extractPath(pageUrl)
+      }
+    });
+  }
+  /**
+   * Encola con dedup por sesión del SDK. Para `shown` del primer step:
+   * no queremos re-emitirlo si el usuario navega entre dos páginas que
+   * matchean el mismo step.
+   */
+  enqueueInteractionOnce(guideId, endUserId, sessionId, pageUrl, action, stepIndex) {
+    const dedupKey = `${guideId}:${action}:${stepIndex}`;
+    if (this.dispatched.has(dedupKey)) return;
+    this.dispatched.add(dedupKey);
+    this.enqueueInteraction(guideId, endUserId, sessionId, pageUrl, action, stepIndex);
+  }
+  createSingleStepRenderer(type) {
+    switch (type) {
+      case "modal":
+        return new ModalRenderer();
+      case "banner":
+        return new BannerRenderer();
+      case "tooltip":
+        return new TooltipRenderer();
+      case "custom":
+        return new CustomRenderer();
+      case "walkthrough":
+        return null;
+    }
+  }
+};
+function extractPath(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return "/";
+  }
+}
+
+// src/plugins/guides/index.ts
+function guidesPlugin(config) {
+  return definePlugin({
+    name: "guides",
+    install(client) {
+      if (!hasWindow()) return;
+      const controller = new GuidesController(client, config);
+      window.__veoGuides = { controller };
+      client.on("identify", ({ sessionId }) => {
+        void controller.checkGuides(window.location.href, sessionId);
+      });
+      client.on("pageview", ({ url, sessionId }) => {
+        void controller.checkGuides(url, sessionId);
+      });
+    }
+  });
+}
+
+// src/plugins/spa-router.ts
+function spaRouterPlugin() {
+  return definePlugin({
+    name: "spa-router",
+    install(client) {
+      if (!hasWindow()) return;
+      client.pageview();
+      const fire = () => {
+        queueMicrotask(() => client.pageview());
+      };
+      const origPushState = window.history.pushState;
+      const origReplaceState = window.history.replaceState;
+      window.history.pushState = function(...args) {
+        origPushState.apply(this, args);
+        fire();
+      };
+      window.history.replaceState = function(...args) {
+        origReplaceState.apply(this, args);
+        fire();
+      };
+      window.addEventListener("popstate", fire);
+      window.addEventListener("hashchange", fire);
+    }
+  });
+}
+
+// src/index.ts
+function init(config) {
+  const client = new Client(config);
+  client.use(spaRouterPlugin());
+  if (config.autocapture !== false) {
+    const autocaptureConfig = typeof config.autocapture === "object" ? config.autocapture : {};
+    client.use(autocapturePlugin(autocaptureConfig));
+  }
+  if (config.guides === true) {
+    client.use(
+      guidesPlugin({
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+        ...config.debug !== void 0 ? { debug: config.debug } : {}
+      })
+    );
+  }
+  if (typeof window !== "undefined") {
+    const stub = window.veo;
+    const pending = stub?._q ?? [];
+    window.veo = client;
+    for (const entry of pending) {
+      const [method, args] = entry;
+      if (method === "init") continue;
+      const fn = client[method];
+      if (typeof fn === "function") {
+        try {
+          fn.apply(client, Array.from(args));
+        } catch (err) {
+          if (config.debug) console.error("[veo] drain error:", err);
+        }
+      }
+    }
+  }
+  return client;
+}
+
+export { Client, SDK_VERSION, autocapturePlugin, definePlugin, guidesPlugin, init, spaRouterPlugin };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map