@holdyapp/sdk 1.1.0 → 1.6.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ var DEFAULT_FLUSH_AT = 20;
 var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
 var MAX_QUEUE = 1e3;
 var BULK_LIMIT = 500;
+var MAX_BACKOFF_MS = 6e4;
 var HoldyCore = class {
   apiKey;
   baseUrl;
@@ -43,6 +44,9 @@ var HoldyCore = class {
   queue = [];
   timer = null;
   flushing = null;
+  retryAt = 0;
+  failures = 0;
+  warned = /* @__PURE__ */ new Set();
   userId = null;
   anonymousId = null;
   accountKey = null;
@@ -76,13 +80,14 @@ var HoldyCore = class {
       event: name,
       occurred_at: occurredAt,
       source: this.source,
+      external_id: newEventId(),
       ...userId ? { user_id: userId } : {},
       ...this.anonymousId ? { anonymous_id: this.anonymousId } : {},
       properties: properties ?? {},
       ...Object.keys(context).length > 0 ? { context } : {}
     };
     this.queue.push(event);
-    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE);
+    this.trimQueue();
     if (this.queue.length >= this.flushAt) void this.flush();
   }
   identify(userId, traits) {
@@ -95,14 +100,9 @@ var HoldyCore = class {
     this.accountKey = accountKey;
     this.track("$group", traits ?? {});
   }
-  /** Drena a fila. Nunca lança — falha re-enfileira e loga em debug. */
+  /** Drena a fila. Nunca lança — falha re-enfileira e espera antes de tentar de novo. */
   async flush() {
-    if (this.flushing) return this.flushing;
-    if (this.queue.length === 0) return;
-    this.flushing = this.drain().finally(() => {
-      this.flushing = null;
-    });
-    return this.flushing;
+    return this.startFlush(false);
   }
   /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */
   async shutdown() {
@@ -110,17 +110,42 @@ var HoldyCore = class {
       clearInterval(this.timer);
       this.timer = null;
     }
-    await this.flush();
+    await this.startFlush(true);
+  }
+  startFlush(force) {
+    if (this.flushing) return this.flushing;
+    if (this.queue.length === 0) return Promise.resolve();
+    if (!force && Date.now() < this.retryAt) return Promise.resolve();
+    this.flushing = this.drain().finally(() => {
+      this.flushing = null;
+    });
+    return this.flushing;
   }
   async drain() {
     while (this.queue.length > 0) {
       const batch = this.queue.splice(0, BULK_LIMIT);
-      const ok = await this.send(batch);
-      if (!ok) {
+      const outcome = await this.send(batch);
+      if (outcome.kind === "retry") {
         this.queue.unshift(...batch);
+        this.trimQueue();
+        this.scheduleRetry(outcome.afterMs);
         return;
       }
+      this.failures = 0;
+      this.retryAt = 0;
+    }
+  }
+  scheduleRetry(afterMs) {
+    this.failures += 1;
+    if (afterMs !== null) {
+      this.retryAt = Date.now() + afterMs;
+      return;
     }
+    const backoff = Math.min(MAX_BACKOFF_MS, 1e3 * 2 ** (this.failures - 1));
+    this.retryAt = Date.now() + backoff + Math.floor(Math.random() * backoff * 0.2);
+  }
+  trimQueue() {
+    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE);
   }
   async send(events) {
     try {
@@ -133,23 +158,38 @@ var HoldyCore = class {
         body: JSON.stringify({ events }),
         ...this.source === "sdk_web" ? { keepalive: true } : {}
       });
-      if (!res.ok) {
-        if (res.status >= 400 && res.status < 500) {
-          this.log(`bulk rejected ${res.status} \xB7 batch dropped`);
-          return true;
-        }
-        this.log(`bulk failed ${res.status} \xB7 will retry`);
-        return false;
+      if (res.ok) return { kind: "sent" };
+      if (res.status === 429) {
+        this.log("rate limited \xB7 will retry after Retry-After");
+        return { kind: "retry", afterMs: retryAfterMs(res) };
       }
-      return true;
+      if (res.status >= 500) {
+        this.log(`bulk failed ${res.status} \xB7 will retry with backoff`);
+        return { kind: "retry", afterMs: null };
+      }
+      if (res.status === 401) {
+        this.warnOnce("401", "API key inv\xE1lida ou revogada \xB7 eventos descartados. Confira a chave em Configura\xE7\xF5es \u203A SDK.");
+        return { kind: "dropped" };
+      }
+      if (res.status === 403) {
+        this.warnOnce("403", "Origem n\xE3o permitida ou chave sem escopo events:write \xB7 eventos descartados.");
+        return { kind: "dropped" };
+      }
+      this.log(`bulk rejected ${res.status} \xB7 batch dropped`);
+      return { kind: "dropped" };
     } catch (err) {
-      this.log(`bulk network error: ${err.message} \xB7 will retry`);
-      return false;
+      this.log(`bulk network error: ${err.message} \xB7 will retry with backoff`);
+      return { kind: "retry", afterMs: null };
     }
   }
   log(msg) {
     if (this.debug) console.warn(`[holdy] ${msg}`);
   }
+  warnOnce(key, msg) {
+    if (this.warned.has(key)) return;
+    this.warned.add(key);
+    console.warn(`[holdy] ${msg}`);
+  }
   /**
    * Ambiente que o SDK observa sozinho (url, referrer, browser, utm…).
    * Vazio no core; `HoldyWeb` preenche. O server não infere ambiente — não
@@ -163,12 +203,72 @@ var HoldyCore = class {
     return this.queue.length;
   }
 };
+function retryAfterMs(res) {
+  const raw = typeof res.headers?.get === "function" ? res.headers.get("Retry-After") : null;
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(MAX_BACKOFF_MS, seconds * 1e3);
+}
+function newEventId() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  const rand = () => Math.random().toString(36).slice(2, 12);
+  return `${Date.now().toString(36)}-${rand()}-${rand()}`;
+}
+
+// src/run.ts
+function newRunId() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function runEventName(name, suffix) {
+  const base = name.trim().replace(/\.$/, "");
+  return `${base || "run"}.${suffix}`;
+}
+async function withRun(track, opts, fn) {
+  if (!opts || !opts.name) throw new Error("[holdy] run: name is required");
+  const id = opts.runId && opts.runId.length > 0 ? opts.runId : newRunId();
+  const base = { ...opts.properties ?? {}, ai_run_id: id };
+  const overrides = {
+    ...opts.accountKey ? { accountKey: opts.accountKey } : {},
+    ...opts.userId ? { userId: opts.userId } : {}
+  };
+  const emit = (event, properties) => track(event, { ...base, ...properties ?? {}, ai_run_id: id }, overrides);
+  const startedAt = Date.now();
+  emit(runEventName(opts.name, "started"));
+  try {
+    const result = await fn({ id, track: emit });
+    emit(runEventName(opts.name, "completed"), { duration_ms: Date.now() - startedAt });
+    return result;
+  } catch (err) {
+    emit(runEventName(opts.name, "failed"), {
+      duration_ms: Date.now() - startedAt,
+      error: err instanceof Error ? err.name : "Error"
+    });
+    throw err;
+  }
+}
 
 // src/server.ts
 var Holdy = class extends HoldyCore {
   constructor(opts) {
     super("sdk_server", opts);
   }
+  /**
+   * Executa `fn` como UMA execução de agente: todo evento lá dentro carrega a
+   * mesma `ai_run_id`, e `<name>.started` / `.completed` / `.failed` saem
+   * sozinhos.
+   *
+   *   await holdy.run({ name: 'support_agent', accountKey: 'acme' }, async (run) => {
+   *     run.track('ticket_drafted', { ai_tokens: 1200, ai_cost_usd: 0.02 })
+   *     return resolveTicket(ticket)
+   *   })
+   */
+  run(opts, fn) {
+    return withRun((name, properties, overrides) => this.track(name, properties, overrides), opts, fn);
+  }
 };
 
 // src/auto-capture.ts
@@ -234,6 +334,415 @@ function currentPath() {
   return `${location.pathname}${location.search}${location.hash}`;
 }
 
+// src/friction.ts
+var INSTALLED_FLAG2 = "__holdy_friction__";
+var INTERACTIVE_SELECTOR = 'button, a, input, select, textarea, summary, [role="button"], [role="link"], [role="menuitem"], [role="tab"]';
+var INTERACTIVE_TAGS = /* @__PURE__ */ new Set(["button", "a", "input", "select", "textarea", "summary"]);
+var FORM_CONTROL_TAGS = /* @__PURE__ */ new Set(["input", "select", "textarea"]);
+var RageClickDetector = class {
+  constructor(threshold = 3, windowMs = 1e3, radiusPx = 30) {
+    this.threshold = threshold;
+    this.windowMs = windowMs;
+    this.radiusPx = radiusPx;
+  }
+  clicks = [];
+  push(x, y, t) {
+    this.clicks = this.clicks.filter(
+      (c) => t - c.t <= this.windowMs && Math.hypot(c.x - x, c.y - y) <= this.radiusPx
+    );
+    this.clicks.push({ x, y, t });
+    if (this.clicks.length >= this.threshold) {
+      this.clicks = [];
+      return true;
+    }
+    return false;
+  }
+};
+var NavLoopDetector = class {
+  constructor(windowMs = 6e4) {
+    this.windowMs = windowMs;
+  }
+  visits = [];
+  push(path, t) {
+    this.visits = [...this.visits, { path, t }].filter((v) => t - v.t <= this.windowMs).slice(-4);
+    if (this.visits.length < 4) return null;
+    const [a, b, c, d] = this.visits.map((v) => v.path);
+    if (a === c && b === d && a !== b) {
+      this.visits = [];
+      return { from: a, to: b };
+    }
+    return null;
+  }
+};
+function resolveInteractive(el) {
+  if (!el) return null;
+  const viaClosest = el.closest?.(INTERACTIVE_SELECTOR) ?? null;
+  if (viaClosest) return viaClosest;
+  const tag = el.tagName.toLowerCase();
+  if (INTERACTIVE_TAGS.has(tag)) return el;
+  const role = el.getAttribute("role");
+  if (role === "button" || role === "link" || role === "menuitem" || role === "tab") return el;
+  return null;
+}
+function isDeadClickTarget(el) {
+  const target = resolveInteractive(el);
+  if (!target) return false;
+  if (target.disabled === true) return true;
+  if (target.getAttribute("disabled") !== null) return true;
+  if (target.getAttribute("aria-disabled") === "true") return true;
+  const tag = target.tagName.toLowerCase();
+  if (tag === "a") {
+    const href = target.getAttribute("href");
+    if (!href || href === "#" || href.startsWith("javascript:")) return true;
+  }
+  return false;
+}
+function describeElement(el) {
+  const target = resolveInteractive(el) ?? el;
+  if (!target) return {};
+  const out = { element: target.tagName.toLowerCase() };
+  if (target.id) out.element_id = target.id;
+  const role = target.getAttribute("role");
+  if (role) out.element_role = role;
+  const label = target.getAttribute("aria-label") ?? target.textContent ?? "";
+  const text = label.replace(/\s+/g, " ").trim().slice(0, 60);
+  if (text) out.element_text = text;
+  const name = target.getAttribute("name") ?? target.getAttribute("data-testid");
+  if (name) out.element_name = name;
+  return out;
+}
+function stripRequestUrl(input, base) {
+  try {
+    const url = new URL(input, base);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return input.split("?")[0].split("#")[0];
+  }
+}
+function errorMessage(reason) {
+  if (reason instanceof Error) return reason.message;
+  if (typeof reason === "string") return reason;
+  try {
+    return JSON.stringify(reason);
+  } catch {
+    return String(reason);
+  }
+}
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && err.name === "AbortError";
+}
+function isIgnoredUrl(url, ignore) {
+  return ignore.some((prefix) => prefix.length > 0 && url.startsWith(prefix));
+}
+function registrableDomain(host) {
+  const labels = host.toLowerCase().split(".").filter(Boolean);
+  if (labels.length <= 2) return labels.join(".");
+  return labels.slice(-2).join(".");
+}
+function isFirstPartyRequest(url, pageUrl, extraOrigins = []) {
+  let target;
+  let page;
+  try {
+    target = new URL(url, pageUrl);
+    page = new URL(pageUrl);
+  } catch {
+    return true;
+  }
+  if (target.protocol !== "http:" && target.protocol !== "https:") return true;
+  if (target.host === page.host) return true;
+  if (extraOrigins.some((o) => o.length > 0 && target.origin === o)) return true;
+  const targetDomain = registrableDomain(target.hostname);
+  return targetDomain.length > 0 && targetDomain === registrableDomain(page.hostname);
+}
+function classifyRequest(outcome) {
+  if (outcome.aborted) return null;
+  if (!outcome.opaque && (outcome.status === null || outcome.status >= 400)) return "http_error";
+  return outcome.durationMs >= outcome.slowMs ? "slow_request" : null;
+}
+function documentStatus(perf) {
+  try {
+    const entry = perf?.getEntriesByType?.("navigation")?.[0];
+    const status = entry?.responseStatus;
+    return typeof status === "number" && status > 0 ? status : null;
+  } catch {
+    return null;
+  }
+}
+function formKey(form) {
+  return form.id || form.getAttribute("name") || form.getAttribute("data-testid") || stripRequestUrl(form.getAttribute("action") ?? "", location.href).replace(location.origin, "") || "form";
+}
+function currentPath2() {
+  return typeof location === "undefined" ? "/" : location.pathname || "/";
+}
+function installFrictionCapture(opts) {
+  const noop = { onNavigate: () => void 0, teardown: () => void 0 };
+  if (typeof window === "undefined" || typeof document === "undefined") return noop;
+  const w = window;
+  if (w[INSTALLED_FLAG2]) return noop;
+  w[INSTALLED_FLAG2] = true;
+  const emit = (kind, properties) => {
+    try {
+      opts.onFriction({ kind, properties: { path: currentPath2(), ...properties } });
+    } catch {
+      return;
+    }
+  };
+  const cleanups = [];
+  const rage = new RageClickDetector(opts.rageClicks, opts.rageWindowMs, opts.rageRadiusPx);
+  const navLoop = new NavLoopDetector(opts.navLoopWindowMs);
+  const slowMs = opts.slowRequestMs ?? 3e3;
+  const touched = /* @__PURE__ */ new Map();
+  const onClick = (ev) => {
+    const el = ev.target instanceof Element ? ev.target : null;
+    if (isDeadClickTarget(el)) emit("dead_click", describeElement(el));
+    if (rage.push(ev.clientX, ev.clientY, ev.timeStamp || Date.now())) {
+      emit("rage_click", describeElement(el));
+    }
+  };
+  document.addEventListener("click", onClick, true);
+  cleanups.push(() => document.removeEventListener("click", onClick, true));
+  const onError = (ev) => {
+    emit("js_error", {
+      message: String(ev.message ?? "").slice(0, 200),
+      ...ev.filename ? { source: stripRequestUrl(ev.filename, location.href) } : {},
+      ...ev.lineno ? { line: ev.lineno } : {}
+    });
+  };
+  window.addEventListener("error", onError);
+  cleanups.push(() => window.removeEventListener("error", onError));
+  const onRejection = (ev) => {
+    emit("js_error", { message: errorMessage(ev.reason).slice(0, 200), unhandled_rejection: true });
+  };
+  window.addEventListener("unhandledrejection", onRejection);
+  cleanups.push(() => window.removeEventListener("unhandledrejection", onRejection));
+  const ignore = (opts.ignoreUrls ?? []).map((url) => stripRequestUrl(url, location.href));
+  const apiOrigins = (opts.apiOrigins ?? []).map((o) => {
+    try {
+      return new URL(o, location.href).origin;
+    } catch {
+      return "";
+    }
+  });
+  const reportRequest = (url, method, started, status, flags = {}) => {
+    const target = stripRequestUrl(url, location.href);
+    if (isIgnoredUrl(target, ignore)) return;
+    if (!isFirstPartyRequest(target, location.href, apiOrigins)) return;
+    const durationMs = performance.now() - started;
+    const kind = classifyRequest({ status, durationMs, slowMs, ...flags });
+    if (!kind) return;
+    emit(kind, {
+      url: target,
+      method,
+      duration_ms: Math.round(durationMs),
+      ...flags.opaque ? {} : status !== null ? { status } : { failed: true }
+    });
+  };
+  const originalFetch = window.fetch;
+  if (typeof originalFetch === "function") {
+    const patched = async (input, init) => {
+      const started = performance.now();
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+      try {
+        const res = await originalFetch(input, init);
+        reportRequest(url, method, started, res.status, {
+          opaque: res.type === "opaque" || res.type === "opaqueredirect"
+        });
+        return res;
+      } catch (err) {
+        reportRequest(url, method, started, null, { aborted: isAbortError(err) });
+        throw err;
+      }
+    };
+    window.fetch = patched;
+    cleanups.push(() => {
+      window.fetch = originalFetch;
+    });
+  }
+  const xhrProto = typeof XMLHttpRequest === "function" ? XMLHttpRequest.prototype : null;
+  if (xhrProto) {
+    const originalOpen = xhrProto.open;
+    const originalSend = xhrProto.send;
+    const requests = /* @__PURE__ */ new WeakMap();
+    xhrProto.open = function(method, url, ...rest) {
+      requests.set(this, { method: String(method).toUpperCase(), url: String(url) });
+      return originalOpen.apply(this, [method, url, ...rest]);
+    };
+    xhrProto.send = function(body) {
+      const request = requests.get(this);
+      if (request) {
+        const started = performance.now();
+        let aborted = false;
+        this.addEventListener("abort", () => {
+          aborted = true;
+        });
+        this.addEventListener("loadend", () => {
+          reportRequest(request.url, request.method, started, this.status === 0 ? null : this.status, { aborted });
+        });
+      }
+      return originalSend.call(this, body);
+    };
+    cleanups.push(() => {
+      xhrProto.open = originalOpen;
+      xhrProto.send = originalSend;
+    });
+  }
+  const loadStatus = documentStatus(typeof performance === "undefined" ? void 0 : performance);
+  if (loadStatus !== null && loadStatus >= 400) {
+    emit("http_error", { document: true, status: loadStatus, url: stripRequestUrl(location.href) });
+  }
+  const onFocusIn = (ev) => {
+    const el = ev.target;
+    if (!el || !FORM_CONTROL_TAGS.has(el.tagName.toLowerCase())) return;
+    const form = el.form;
+    if (!form) return;
+    const entry = touched.get(form) ?? { form: formKey(form), fields: /* @__PURE__ */ new Set() };
+    const field = el.name || el.id || el.tagName.toLowerCase();
+    entry.fields.add(field);
+    touched.set(form, entry);
+  };
+  document.addEventListener("focusin", onFocusIn, true);
+  cleanups.push(() => document.removeEventListener("focusin", onFocusIn, true));
+  const onSubmit = (ev) => {
+    if (ev.target instanceof HTMLFormElement) touched.delete(ev.target);
+  };
+  document.addEventListener("submit", onSubmit, true);
+  cleanups.push(() => document.removeEventListener("submit", onSubmit, true));
+  const flushAbandons = () => {
+    for (const entry of touched.values()) {
+      emit("form_abandon", { form: entry.form, fields_touched: entry.fields.size });
+    }
+    touched.clear();
+  };
+  window.addEventListener("pagehide", flushAbandons);
+  cleanups.push(() => window.removeEventListener("pagehide", flushAbandons));
+  return {
+    onNavigate: (path) => {
+      flushAbandons();
+      const loop = navLoop.push(path, Date.now());
+      if (loop) emit("nav_loop", { from: loop.from, to: loop.to });
+    },
+    teardown: () => {
+      for (const cleanup of cleanups) cleanup();
+      touched.clear();
+      w[INSTALLED_FLAG2] = false;
+    }
+  };
+}
+
+// src/skeleton.ts
+var SKELETON_SELECTOR = 'a[href], button, input, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [role="radio"], [role="switch"], [data-testid]';
+var SKELETON_MAX_ELEMENTS = 80;
+var SKELETON_DELAY_MS = 1500;
+var SENT_STORAGE_KEY = "holdy_skeletons";
+var SENT_STORAGE_MAX = 200;
+function fnv1a(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+function attr(el, name, max) {
+  const value = el.getAttribute(name);
+  if (!value) return void 0;
+  const trimmed = value.replace(/\s+/g, " ").trim().slice(0, max);
+  return trimmed || void 0;
+}
+function isVisible(el) {
+  if (!el.getBoundingClientRect) return true;
+  const rect = el.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}
+function relativeBox(rect, viewport) {
+  const pct = (value, base) => base > 0 ? Math.max(0, Math.min(100, Math.round(value / base * 100))) : 0;
+  return [pct(rect.x, viewport.width), pct(rect.y + viewport.scrollY, viewport.height), pct(rect.width, viewport.width), pct(rect.height, viewport.height)];
+}
+function describeSkeletonElement(el, viewport) {
+  const out = { t: el.tagName.toLowerCase() };
+  const role = attr(el, "role", 40);
+  if (role) out.r = role;
+  const testid = attr(el, "data-testid", 80);
+  if (testid) out.id = testid;
+  const name = attr(el, "name", 80);
+  if (name) out.n = name;
+  const label = attr(el, "aria-label", 80);
+  if (label) out.l = label;
+  if (out.t === "input" || out.t === "button") {
+    const type = attr(el, "type", 20);
+    if (type) out.k = type.toLowerCase();
+  }
+  if (viewport && el.getBoundingClientRect) out.b = relativeBox(el.getBoundingClientRect(), viewport);
+  return out;
+}
+function collectSkeleton(root, path, viewport) {
+  const found = root.querySelectorAll(SKELETON_SELECTOR);
+  const visible = [];
+  for (let i = 0; i < found.length; i++) {
+    const el = found[i];
+    if (el.tagName.toLowerCase() === "input" && (el.getAttribute("type") ?? "").toLowerCase() === "hidden") continue;
+    if (!isVisible(el)) continue;
+    visible.push(el);
+  }
+  const elements = visible.slice(0, SKELETON_MAX_ELEMENTS).map((el) => describeSkeletonElement(el, viewport));
+  const structural = elements.map(({ b: _b, ...rest }) => rest);
+  return { path, hash: fnv1a(JSON.stringify(structural)), count: visible.length, elements };
+}
+function loadSent() {
+  try {
+    const raw = sessionStorage.getItem(SENT_STORAGE_KEY);
+    const list = raw ? JSON.parse(raw) : [];
+    return new Set(Array.isArray(list) ? list.filter((x) => typeof x === "string") : []);
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function saveSent(sent) {
+  try {
+    sessionStorage.setItem(SENT_STORAGE_KEY, JSON.stringify([...sent].slice(-SENT_STORAGE_MAX)));
+  } catch {
+    return;
+  }
+}
+function installSkeletonCapture(opts) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return { onNavigate: () => void 0, teardown: () => void 0 };
+  }
+  const delay = opts.delayMs ?? SKELETON_DELAY_MS;
+  const sent = loadSent();
+  let pending = null;
+  const capture = (path) => {
+    pending = null;
+    if (location.pathname !== path) return;
+    try {
+      const viewport = {
+        width: window.innerWidth,
+        height: Math.max(document.documentElement.scrollHeight, window.innerHeight),
+        scrollY: window.scrollY
+      };
+      const skeleton = collectSkeleton(document, path, viewport);
+      const key = `${path}:${skeleton.hash}`;
+      if (sent.has(key)) return;
+      sent.add(key);
+      saveSent(sent);
+      opts.onSkeleton(skeleton);
+    } catch {
+      return;
+    }
+  };
+  return {
+    onNavigate: (path) => {
+      if (pending) clearTimeout(pending);
+      pending = setTimeout(() => capture(path), delay);
+    },
+    teardown: () => {
+      if (pending) clearTimeout(pending);
+      pending = null;
+    }
+  };
+}
+
 // src/web-context.ts
 var UTM_KEYS = [
   "utm_source",
@@ -276,17 +785,17 @@ function parseUserAgent(ua) {
     device
   };
 }
-function readStorage(storage, key) {
+function readStorage(storage2, key) {
   try {
-    const s = storage === "session" ? sessionStorage : localStorage;
+    const s = storage2 === "session" ? sessionStorage : localStorage;
     return s.getItem(key);
   } catch {
     return null;
   }
 }
-function writeStorage(storage, key, value) {
+function writeStorage(storage2, key, value) {
   try {
-    const s = storage === "session" ? sessionStorage : localStorage;
+    const s = storage2 === "session" ? sessionStorage : localStorage;
     s.setItem(key, value);
   } catch {
   }
@@ -351,10 +860,307 @@ function buildWebContext() {
   };
 }
 
+// src/arm.ts
+function fnv1a2(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash >>> 0;
+}
+function changeBucket(changeId, accountKey) {
+  return fnv1a2(`${changeId}:${accountKey}`) % 100;
+}
+function changeArm(changeId, accountKey, holdoutPct) {
+  return changeBucket(changeId, accountKey) < holdoutPct ? "holdout" : "change";
+}
+function matchesPathTemplate(template, path) {
+  const t = template.split(/[?#]/)[0].split("/").filter(Boolean);
+  const p = path.split(/[?#]/)[0].split("/").filter(Boolean);
+  if (t.length !== p.length) return false;
+  return t.every((segment, i) => segment.startsWith(":") || segment === p[i]);
+}
+
+// src/changes.ts
+var REFRESH_MS = 5 * 60 * 1e3;
+var NAV_REFRESH_MS = 60 * 1e3;
+var SCAN_DEBOUNCE_MS = 250;
+var SEEN_KEY = "holdy_changes_seen";
+var DISMISSED_KEY = "holdy_changes_dismissed";
+var TIP_GAP_PX = 8;
+var TIP_CSS = `:host{all:initial}
+.tip{position:fixed;box-sizing:border-box;max-width:280px;padding:10px 12px;border-radius:8px;background:#111;color:#fff;font:13px/1.45 system-ui,-apple-system,sans-serif;box-shadow:0 8px 24px rgba(0,0,0,.18);pointer-events:auto;display:flex;gap:10px;align-items:flex-start}
+.tip p{margin:0;flex:1}
+.tip button{all:unset;cursor:pointer;opacity:.7;font-size:15px;line-height:1}
+.tip button:hover,.tip button:focus-visible{opacity:1}
+@media (prefers-color-scheme:dark){.tip{background:#fff;color:#111}}`;
+function normalizeText(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function parseChanges(body) {
+  const list = body?.changes;
+  return Array.isArray(list) ? list.filter(isChange) : [];
+}
+function isAnchor(value) {
+  const a = value;
+  if (a?.kind === "page") return true;
+  return (a?.kind === "selector" || a?.kind === "text") && typeof a.value === "string" && a.value.length > 0;
+}
+function isChange(value) {
+  const c = value;
+  return typeof c?.id === "string" && (c.kind === "copy" || c.kind === "guidance") && typeof c.path === "string" && isAnchor(c.anchor) && typeof c.content?.text === "string" && typeof c.holdout_pct === "number";
+}
+function changesForPage(changes, path, accountKey) {
+  if (!accountKey) return [];
+  return changes.filter((c) => matchesPathTemplate(c.path, path)).map((change) => ({ change, arm: changeArm(change.id, accountKey, change.holdout_pct) }));
+}
+function storage(kind) {
+  try {
+    return kind === "local" ? window.localStorage : window.sessionStorage;
+  } catch {
+    return void 0;
+  }
+}
+function readSet(store, key) {
+  try {
+    return new Set(JSON.parse(store?.getItem(key) ?? "[]"));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function addToSet(store, key, value) {
+  try {
+    const set = readSet(store, key);
+    set.add(value);
+    store?.setItem(key, JSON.stringify([...set].slice(-200)));
+  } catch {
+    return;
+  }
+}
+function query(selector) {
+  try {
+    return document.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+var TEXT_ANCHOR_TAGS = 'button,a,[role="button"],label,summary,h1,h2,h3,h4,li,td,th,p,span,strong';
+var TEXT_ANCHOR_SCAN_LIMIT = 3e3;
+function findByText(value) {
+  const wanted = normalizeText(value);
+  let best = null;
+  let bestLength = Number.POSITIVE_INFINITY;
+  const nodes = document.querySelectorAll(TEXT_ANCHOR_TAGS);
+  const total = Math.min(nodes.length, TEXT_ANCHOR_SCAN_LIMIT);
+  for (let i = 0; i < total; i += 1) {
+    const el = nodes[i];
+    const raw = el.textContent ?? "";
+    if (raw.length >= bestLength || normalizeText(raw) !== wanted) continue;
+    best = el;
+    bestLength = raw.length;
+  }
+  return best;
+}
+function findAnchor(anchor) {
+  if (anchor.kind === "page") return null;
+  return anchor.kind === "selector" ? query(anchor.value) : findByText(anchor.value);
+}
+function findTextNode(el, match) {
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (match(normalizeText(node.textContent ?? ""))) return node;
+  }
+  return null;
+}
+function installProductChanges(opts) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return { onNavigate: () => void 0, refresh: async () => void 0, teardown: () => void 0 };
+  }
+  let changes = [];
+  let lastFetch = 0;
+  let timer = null;
+  let root = null;
+  let host = null;
+  const copies = /* @__PURE__ */ new Map();
+  const tips = /* @__PURE__ */ new Map();
+  const log = (message) => {
+    if (opts.debug) console.warn(`[holdy] ${message}`);
+  };
+  const expose = (change, arm) => {
+    const key = `${change.id}:${arm}`;
+    const session = storage("session");
+    if (readSet(session, SEEN_KEY).has(key)) return;
+    addToSet(session, SEEN_KEY, key);
+    opts.track("$change_exposure", { change_id: change.id, arm, kind: change.kind });
+  };
+  const eligibleCopyNode = (el, change) => {
+    const expected = change.expected_text ? normalizeText(change.expected_text) : null;
+    const next = normalizeText(change.content.text);
+    return findTextNode(el, (text) => text.length > 0 && (text === next || expected === null || text === expected));
+  };
+  const applyCopy = (el, change) => {
+    const next = normalizeText(change.content.text);
+    const current = copies.get(change.id);
+    if (current && current.node.isConnected && normalizeText(current.node.textContent ?? "") === next) return true;
+    const node = eligibleCopyNode(el, change);
+    if (!node) return false;
+    const text = node.textContent ?? "";
+    if (normalizeText(text) !== next) {
+      copies.set(change.id, { node, original: text, next: change.content.text });
+      node.textContent = text.replace(text.trim(), change.content.text);
+    }
+    return true;
+  };
+  const restoreCopy = (id) => {
+    const applied = copies.get(id);
+    if (!applied) return;
+    if (applied.node.isConnected && normalizeText(applied.node.textContent ?? "") === normalizeText(applied.next)) {
+      applied.node.textContent = applied.original;
+    }
+    copies.delete(id);
+  };
+  const ensureRoot = () => {
+    if (root) return root;
+    if (!document.body) return null;
+    host = document.createElement("holdy-changes");
+    host.setAttribute("data-holdy-root", "1");
+    host.style.cssText = "position:fixed;top:0;left:0;width:0;height:0;z-index:2147483647;pointer-events:none";
+    root = host.attachShadow({ mode: "closed" });
+    const style = document.createElement("style");
+    style.textContent = TIP_CSS;
+    root.appendChild(style);
+    document.body.appendChild(host);
+    return root;
+  };
+  const showTip = (anchor, change) => {
+    if (tips.has(change.id)) return true;
+    if (readSet(storage("local"), DISMISSED_KEY).has(change.id)) return true;
+    const shadow = ensureRoot();
+    if (!shadow) return false;
+    const card = document.createElement("div");
+    card.className = "tip";
+    card.setAttribute("role", "tooltip");
+    const text = document.createElement("p");
+    text.textContent = change.content.text;
+    const close = document.createElement("button");
+    close.type = "button";
+    close.setAttribute("aria-label", "Fechar");
+    close.textContent = "\xD7";
+    card.append(text, close);
+    card.style.top = "-9999px";
+    card.style.left = "-9999px";
+    shadow.appendChild(card);
+    const remove = () => {
+      card.remove();
+      window.removeEventListener("scroll", position, true);
+      window.removeEventListener("resize", position);
+      tips.delete(change.id);
+    };
+    function position() {
+      if (!anchor) {
+        const corner = card.getBoundingClientRect();
+        card.style.top = `${Math.max(8, window.innerHeight - corner.height - 16)}px`;
+        card.style.left = `${Math.max(8, window.innerWidth - corner.width - 16)}px`;
+        return;
+      }
+      if (!anchor.isConnected) {
+        remove();
+        return;
+      }
+      const a = anchor.getBoundingClientRect();
+      const c = card.getBoundingClientRect();
+      let top = a.bottom + TIP_GAP_PX;
+      if (top + c.height > window.innerHeight - 8) top = a.top - c.height - TIP_GAP_PX;
+      const left = Math.min(Math.max(8, a.left + a.width / 2 - c.width / 2), window.innerWidth - c.width - 8);
+      card.style.top = `${Math.max(8, top)}px`;
+      card.style.left = `${Math.max(8, left)}px`;
+    }
+    close.addEventListener("click", () => {
+      addToSet(storage("local"), DISMISSED_KEY, change.id);
+      opts.track("$change_dismissed", { change_id: change.id, kind: change.kind });
+      remove();
+    });
+    tips.set(change.id, remove);
+    requestAnimationFrame(position);
+    window.addEventListener("scroll", position, true);
+    window.addEventListener("resize", position);
+    return true;
+  };
+  const scan = () => {
+    timer = null;
+    const active = changesForPage(changes, location.pathname, opts.getAccountKey());
+    const activeIds = new Set(active.map((a) => a.change.id));
+    for (const id of [...copies.keys()]) if (!activeIds.has(id)) restoreCopy(id);
+    for (const [id, remove] of [...tips]) if (!activeIds.has(id)) remove();
+    for (const { change, arm } of active) {
+      const el = findAnchor(change.anchor);
+      if (!el && change.anchor.kind !== "page") continue;
+      if (change.kind === "copy") {
+        if (!el) continue;
+        const shown = arm === "change" ? applyCopy(el, change) : eligibleCopyNode(el, change) !== null;
+        if (shown) expose(change, arm);
+      } else if (arm === "holdout" || showTip(el, change)) {
+        expose(change, arm);
+      }
+    }
+  };
+  const schedule = () => {
+    if (timer === null) timer = setTimeout(scan, SCAN_DEBOUNCE_MS);
+  };
+  const refresh = async () => {
+    lastFetch = Date.now();
+    try {
+      const res = await fetch(`${opts.baseUrl}/runtime/changes`, {
+        headers: { Authorization: `Bearer ${opts.apiKey}` }
+      });
+      if (!res.ok) {
+        log(`changes ${res.status}`);
+        return;
+      }
+      changes = parseChanges(await res.json());
+      schedule();
+    } catch (err) {
+      log(`changes network error: ${err.message}`);
+    }
+  };
+  const observer = typeof MutationObserver !== "undefined" ? new MutationObserver(() => {
+    if (changes.length > 0 || copies.size > 0 || tips.size > 0) schedule();
+  }) : null;
+  const observe = () => {
+    if (document.body) observer?.observe(document.body, { childList: true, subtree: true, characterData: true });
+  };
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", observe, { once: true });
+  else observe();
+  const interval = setInterval(() => void refresh(), REFRESH_MS);
+  void refresh();
+  return {
+    onNavigate: () => {
+      if (Date.now() - lastFetch > NAV_REFRESH_MS) void refresh();
+      schedule();
+    },
+    refresh,
+    teardown: () => {
+      clearInterval(interval);
+      if (timer !== null) clearTimeout(timer);
+      observer?.disconnect();
+      for (const id of [...copies.keys()]) restoreCopy(id);
+      for (const remove of [...tips.values()]) remove();
+      host?.remove();
+      host = null;
+      root = null;
+      changes = [];
+    }
+  };
+}
+
 // src/web.ts
 var ANON_STORAGE_KEY = "holdy_anon_id";
 var HoldyWeb = class extends HoldyCore {
   teardownAutoCapture = null;
+  friction = null;
+  changes = null;
+  skeleton = null;
   constructor(opts) {
     super("sdk_web", opts);
     this.anonymousId = resolveAnonymousId();
@@ -364,9 +1170,37 @@ var HoldyWeb = class extends HoldyCore {
         if (document.visibilityState === "hidden") void this.flush();
       });
     }
+    if (opts.friction !== false) {
+      const frictionOpts = typeof opts.friction === "object" ? opts.friction : {};
+      this.friction = installFrictionCapture({
+        ...frictionOpts,
+        ignoreUrls: [...frictionOpts.ignoreUrls ?? [], this.baseUrl],
+        onFriction: (signal) => this.track(`$${signal.kind}`, signal.properties)
+      });
+    }
+    if (opts.skeleton !== false) {
+      this.skeleton = installSkeletonCapture({
+        onSkeleton: (skeleton) => this.track("$page_skeleton", { ...skeleton })
+      });
+    }
     if (opts.autoCapture !== false) {
       this.teardownAutoCapture = installAutoCapture({
-        onNavigate: (kind) => this.page(void 0, { navigation: kind })
+        onNavigate: (kind) => {
+          this.page(void 0, { navigation: kind });
+          const path = typeof location !== "undefined" ? location.pathname : "/";
+          this.friction?.onNavigate(path);
+          this.changes?.onNavigate();
+          this.skeleton?.onNavigate(path);
+        }
+      });
+    }
+    if (opts.productChanges !== false && typeof window !== "undefined") {
+      this.changes = installProductChanges({
+        baseUrl: this.baseUrl,
+        apiKey: this.apiKey,
+        getAccountKey: () => this.accountKey,
+        track: (name, properties) => this.track(name, properties),
+        debug: opts.debug
       });
     }
   }
@@ -384,6 +1218,10 @@ var HoldyWeb = class extends HoldyCore {
       ...typeof document !== "undefined" && document.title ? { title: document.title } : {}
     });
   }
+  group(accountKey, traits) {
+    super.group(accountKey, traits);
+    this.changes?.onNavigate();
+  }
   reset() {
     this.userId = null;
     this.accountKey = null;
@@ -392,11 +1230,18 @@ var HoldyWeb = class extends HoldyCore {
     } catch {
     }
     this.anonymousId = resolveAnonymousId();
+    this.changes?.onNavigate();
   }
   /** Flush final + desinstala o auto-capture (devolve `history` ao original). */
   async shutdown() {
     this.teardownAutoCapture?.();
     this.teardownAutoCapture = null;
+    this.friction?.teardown();
+    this.friction = null;
+    this.changes?.teardown();
+    this.changes = null;
+    this.skeleton?.teardown();
+    this.skeleton = null;
     await super.shutdown();
   }
   environmentContext() {