@guidelytech/sdk-core 0.9.0 → 0.10.0

package/dist/index.cjs

@@ -57,7 +57,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_runtime13 = require("@guidelytech/shared/runtime");
+var import_runtime15 = require("@guidelytech/shared/runtime");
 var import_guide_runtime4 = require("@guidelytech/guide-runtime");
 var import_guide_runtime5 = require("@guidelytech/guide-runtime");
 var import_flags = require("@guidelytech/flags");
@@ -206,6 +206,8 @@ var KEYS = {
   state: (key) => `guidely:state:${key}`,
   user: (key) => `guidely:user:${key}`,
   queue: (key) => `guidely:queue:${key}`,
+  /** Survey answers and guide/checklist progress not yet accepted by the server. */
+  outbox: (key) => `guidely:outbox:${key}`,
   session: "guidely:session",
   active: "guidely:active",
   authoring: "guidely:authoring",
@@ -304,7 +306,7 @@ var AuthoringBridge = class {
   masked(el) {
     return this.opts.maskSelectors.some((sel) => {
       try {
-        return !!el.closest(sel);
+        return !!(0, import_guide_runtime.closestComposed)(el, sel);
       } catch {
         return false;
       }
@@ -505,11 +507,11 @@ function validSelectors(list) {
   return out;
 }
 function isIgnoredElement(el) {
-  return (0, import_guide_runtime2.isGuidelyElement)(el) || !!el.closest("[data-guidely-ignore]");
+  return (0, import_guide_runtime2.isGuidelyElement)(el) || !!(0, import_guide_runtime2.closestComposed)(el, "[data-guidely-ignore]");
 }
 function interactiveElement(target) {
   try {
-    return target.closest(INTERACTIVE_SELECTOR);
+    return (0, import_guide_runtime2.closestComposed)(target, INTERACTIVE_SELECTOR);
   } catch {
     return null;
   }
@@ -520,14 +522,19 @@ function esc(value) {
 }
 var attr = (tag, name, value) => value ? `${tag}[${name}="${value.replace(/["\\]/g, "\\$&")}"]` : `${tag}[${name}]`;
 function elementSelector(el) {
+  const own = ownSelector(el);
+  const chain = (0, import_guide_runtime2.shadowHostChain)(el);
+  return (chain ? chain + import_guide_runtime2.SHADOW_SEPARATOR + own : own).slice(0, 300);
+}
+function ownSelector(el) {
   const tag = el.tagName.toLowerCase();
   if (el.id && (0, import_guide_runtime2.isStableId)(el.id)) return `#${esc(el.id)}`;
-  for (const name of PREFERRED_ATTRS) if (el.hasAttribute(name)) return attr(tag, name, el.getAttribute(name) || "").slice(0, 300);
+  for (const name of PREFERRED_ATTRS) if (el.hasAttribute(name)) return attr(tag, name, el.getAttribute(name) || "");
   for (const a of Array.from(el.attributes)) {
-    if (a.name.startsWith("data-") && !NOISY_DATA_ATTR.test(a.name) && a.value && a.value.length <= 60) return attr(tag, a.name, a.value).slice(0, 300);
+    if (a.name.startsWith("data-") && !NOISY_DATA_ATTR.test(a.name) && a.value && a.value.length <= 60) return attr(tag, a.name, a.value);
   }
   const label = el.getAttribute("aria-label");
-  if (label && label.length <= 80) return attr(tag, "aria-label", label).slice(0, 300);
+  if (label && label.length <= 80) return attr(tag, "aria-label", label);
   const parts = [];
   let cur = el;
   while (cur && parts.length < 4) {
@@ -543,12 +550,12 @@ function elementSelector(el) {
     parts.unshift(same.length > 1 ? `${t}:nth-of-type(${same.indexOf(node) + 1})` : t);
     cur = parent;
   }
-  return (parts.join(" > ") || tag).slice(0, 300);
+  return parts.join(" > ") || tag;
 }
 function matches(el, selector, deep) {
   if (!selector) return false;
   try {
-    return !!el.closest(selector) || deep && !!el.querySelector(selector);
+    return !!(0, import_guide_runtime2.closestComposed)(el, selector) || deep && !!el.querySelector(selector);
   } catch {
     return false;
   }
@@ -566,7 +573,7 @@ function elementText(el, mask, maskAll) {
   return text ? text.slice(0, 100) : void 0;
 }
 function linkHref(el) {
-  const a = el.closest("a[href]");
+  const a = (0, import_guide_runtime2.closestComposed)(el, "a[href]");
   if (!a) return void 0;
   try {
     const u = new URL(a.getAttribute("href") || "", location.href);
@@ -898,12 +905,108 @@ function dismissedAfterMerge(local, server) {
   return local?.dismissedAt ?? server.dismissedAt ?? null;
 }
 
+// src/health.ts
+var MAX_RETRY_AFTER_MS = 60 * 60 * 1e3;
+var OFFLINE_WAIT_MS = 3e4;
+var ServerHealth = class {
+  constructor(opts = {}) {
+    __publicField(this, "failures", 0);
+    __publicField(this, "openUntil", 0);
+    __publicField(this, "lastOkAt", 0);
+    __publicField(this, "listeners", /* @__PURE__ */ new Set());
+    __publicField(this, "threshold");
+    __publicField(this, "baseMs");
+    __publicField(this, "maxMs");
+    __publicField(this, "now");
+    __publicField(this, "random");
+    this.threshold = opts.threshold ?? 3;
+    this.baseMs = opts.baseMs ?? 5e3;
+    this.maxMs = opts.maxMs ?? 5 * 60 * 1e3;
+    this.now = opts.now ?? Date.now;
+    this.random = opts.random ?? Math.random;
+  }
+  /** The server answered (2xx, 3xx, or a 4xx other than 429): it is up. */
+  success() {
+    const wasDown = this.failures > 0 || this.openUntil > 0;
+    this.failures = 0;
+    this.openUntil = 0;
+    this.lastOkAt = this.now();
+    if (wasDown) this.notify();
+  }
+  /** The request failed or the server is overloaded. `retryAfterMs` comes from a `Retry-After` header. */
+  failure(retryAfterMs) {
+    this.failures += 1;
+    const now = this.now();
+    if (retryAfterMs != null && retryAfterMs > 0) {
+      this.openUntil = Math.max(this.openUntil, now + Math.min(retryAfterMs, MAX_RETRY_AFTER_MS));
+      return;
+    }
+    if (this.failures < this.threshold) return;
+    const cooldown = Math.min(this.maxMs, this.baseMs * 2 ** (this.failures - this.threshold));
+    this.openUntil = Math.max(this.openUntil, now + cooldown * (0.8 + this.random() * 0.4));
+  }
+  /** Milliseconds background traffic should wait before trying again (0: send now). */
+  waitMs() {
+    if (typeof navigator !== "undefined" && navigator.onLine === false) return OFFLINE_WAIT_MS;
+    return Math.max(0, this.openUntil - this.now());
+  }
+  canSend() {
+    return this.waitMs() === 0;
+  }
+  /**
+   * The last request got an answer. Unload beacons can't report back, so what they carry is only
+   * forgotten while this holds; otherwise it stays queued and is sent again (the server drops duplicates).
+   */
+  get reachable() {
+    return this.failures === 0 && this.lastOkAt > 0;
+  }
+  /** The browser came back online: end the cooldown and let queued traffic try straight away. */
+  online() {
+    this.openUntil = 0;
+    this.notify();
+  }
+  /** Called when the server answers again after failures, or the browser comes back online. */
+  onRecover(cb) {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+  notify() {
+    for (const cb of Array.from(this.listeners)) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  }
+};
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1e3;
+  const at = Date.parse(trimmed);
+  return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+function isServerFailure(status) {
+  return status === 429 || status >= 500;
+}
+
 // src/http.ts
+var STREAM_RESPONSE_TIMEOUT_MS = 3e4;
+var STREAM_IDLE_TIMEOUT_MS = 6e4;
 var Api = class {
-  constructor(baseUrl, key, fetchImpl) {
+  constructor(baseUrl, key, fetchImpl, health) {
     __publicField(this, "baseUrl", baseUrl);
     __publicField(this, "key", key);
     __publicField(this, "fetchImpl", fetchImpl);
+    /** Reachability of the API, fed by every answer (see {@link ServerHealth}). */
+    __publicField(this, "health");
+    this.health = health ?? new ServerHealth();
+  }
+  /** Feeds an answer (or a failed request, `null`) into {@link health}. */
+  observe(res) {
+    if (!res) this.health.failure();
+    else if (isServerFailure(res.status)) this.health.failure(parseRetryAfter(res.headers?.get?.("retry-after")));
+    else this.health.success();
   }
   url(path, params = {}) {
     const query = Object.entries({ key: this.key, ...params }).filter((e) => e[1] != null).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
@@ -923,15 +1026,22 @@ var Api = class {
     const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
     const timer = ac ? setTimeout(() => ac.abort(), options.timeoutMs ?? 1e4) : null;
     try {
-      const res = await f(this.url(path, options.params), {
-        method,
-        headers,
-        body: options.body === void 0 ? void 0 : form ? options.body : JSON.stringify(options.body),
-        keepalive: options.keepalive,
-        signal: ac?.signal,
-        credentials: "omit",
-        mode: "cors"
-      });
+      let res;
+      try {
+        res = await f(this.url(path, options.params), {
+          method,
+          headers,
+          body: options.body === void 0 ? void 0 : form ? options.body : JSON.stringify(options.body),
+          keepalive: options.keepalive,
+          signal: ac?.signal,
+          credentials: "omit",
+          mode: "cors"
+        });
+      } catch (err) {
+        this.observe(null);
+        throw err;
+      }
+      this.observe(res);
       let data = null;
       if (res.status !== 304 && res.status !== 204) {
         try {
@@ -957,30 +1067,53 @@ var Api = class {
   }
   /**
    * POST that may answer with server-sent events. Each event is passed to `onEvent`; a JSON answer is
-   * returned instead. No timeout: Scout replies can take a while and the server keeps the stream alive.
+   * returned instead. Scout replies can take a while, so there is no overall timeout: the response
+   * must start within 30 s and then never go quiet for more than 60 s (the server sends keepalives),
+   * otherwise the request is aborted and rejects.
    */
   async stream(path, body, onEvent, headers = {}) {
     const f = this.fetcher;
     if (!f) throw new Error("fetch is not available");
-    const res = await f(this.url(path), {
-      method: "POST",
-      headers: { ...headers, "X-Guidely-Key": this.key, Accept: "text/event-stream, application/json", "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-      credentials: "omit",
-      mode: "cors"
-    });
-    const type = res.headers?.get?.("content-type") ?? "";
-    if (!type.includes("text/event-stream") || !res.body) {
-      let data = null;
+    const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
+    let timer = null;
+    const arm = (ms) => {
+      if (!ac) return;
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => ac.abort(), ms);
+    };
+    arm(STREAM_RESPONSE_TIMEOUT_MS);
+    try {
+      let res;
       try {
-        data = await res.json();
-      } catch {
-        data = null;
+        res = await f(this.url(path), {
+          method: "POST",
+          headers: { ...headers, "X-Guidely-Key": this.key, Accept: "text/event-stream, application/json", "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+          signal: ac?.signal,
+          credentials: "omit",
+          mode: "cors"
+        });
+      } catch (err) {
+        this.observe(null);
+        throw err;
       }
-      return { status: res.status, ok: res.ok, data, etag: null };
+      this.observe(res);
+      const type = res.headers?.get?.("content-type") ?? "";
+      if (!type.includes("text/event-stream") || !res.body) {
+        let data = null;
+        try {
+          data = await res.json();
+        } catch {
+          data = null;
+        }
+        return { status: res.status, ok: res.ok, data, etag: null };
+      }
+      arm(STREAM_IDLE_TIMEOUT_MS);
+      await readEventStream(res.body, onEvent, () => arm(STREAM_IDLE_TIMEOUT_MS));
+      return { status: res.status, ok: res.ok, data: null, etag: null };
+    } finally {
+      if (timer) clearTimeout(timer);
     }
-    await readEventStream(res.body, onEvent);
-    return { status: res.status, ok: res.ok, data: null, etag: null };
   }
   /** `navigator.sendBeacon` when available (page unload); returns false when it could not be queued. */
   beacon(path, body) {
@@ -1011,7 +1144,7 @@ async function withRetry(send, attempts = 3, baseMs = 500) {
 function postWithRetry(api, path, body, attempts = 3, baseMs = 500) {
   return withRetry(() => api.post(path, body), attempts, baseMs);
 }
-async function readEventStream(body, onEvent) {
+async function readEventStream(body, onEvent, onChunk) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
@@ -1034,6 +1167,7 @@ async function readEventStream(body, onEvent) {
   };
   for (; ; ) {
     const { done, value } = await reader.read();
+    if (value) onChunk?.();
     if (value) buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, "\n");
     let sep;
     while ((sep = buffer.indexOf("\n\n")) >= 0) {
@@ -1187,7 +1321,7 @@ function createMessengerTransport(opts) {
 }
 
 // src/messenger-visitor.ts
-var import_runtime10 = require("@guidelytech/shared/runtime");
+var import_runtime11 = require("@guidelytech/shared/runtime");
 var import_guide_runtime3 = require("@guidelytech/guide-runtime");
 var PAGE_GUIDE_KINDS = /* @__PURE__ */ new Set(["flow", "tooltip", "modal"]);
 var CATCH_ALL = /* @__PURE__ */ new Set(["", "*", "**", "/*", "/**", "/"]);
@@ -1254,7 +1388,7 @@ function buildMessengerVisitor(input) {
       unread: !seen.has(g.id) && !(state.guides[g.id]?.impressions ?? 0)
     };
   });
-  return { firstName: (0, import_runtime10.firstNameFromTraits)(input.traits), path: pathOf(input.url), pageGuides, resumeGuide, checklist, news };
+  return { firstName: (0, import_runtime11.firstNameFromTraits)(input.traits), path: pathOf(input.url), pageGuides, resumeGuide, checklist, news };
 }
 
 // src/navigation.ts
@@ -1357,6 +1491,90 @@ var PageTracker = class {
   }
 };
 
+// src/outbox.ts
+var Outbox = class {
+  constructor(opts) {
+    __publicField(this, "opts", opts);
+    __publicField(this, "items");
+    __publicField(this, "sending", false);
+    __publicField(this, "attempt", 0);
+    __publicField(this, "timer", null);
+    __publicField(this, "destroyed", false);
+    __publicField(this, "offRecover");
+    __publicField(this, "maxItems");
+    __publicField(this, "maxAgeMs");
+    this.maxItems = opts.maxItems ?? 50;
+    this.maxAgeMs = opts.maxAgeMs ?? 7 * 24 * 60 * 60 * 1e3;
+    const stored = readJson(opts.store, opts.storageKey, []);
+    const cutoff = Date.now() - this.maxAgeMs;
+    this.items = Array.isArray(stored) ? stored.filter((i) => i && typeof i.path === "string" && typeof i.key === "string" && i.createdAt > cutoff).slice(-this.maxItems) : [];
+    this.offRecover = opts.health?.onRecover(() => {
+      this.attempt = 0;
+      this.retryIn(0);
+    }) ?? null;
+    if (this.items.length) this.retryIn(0);
+  }
+  get size() {
+    return this.items.length;
+  }
+  /** Queues `POST path` and sends it now (or as soon as the API is reachable). */
+  add(key, path, body) {
+    if (this.destroyed) return;
+    this.items = this.items.filter((i) => i.key !== key);
+    this.items.push({ key, path, body, createdAt: Date.now() });
+    if (this.items.length > this.maxItems) this.items.splice(0, this.items.length - this.maxItems);
+    this.persist();
+    void this.flush();
+  }
+  persist() {
+    writeJson(this.opts.store, this.opts.storageKey, this.items);
+  }
+  retryIn(ms) {
+    if (this.destroyed) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, ms);
+  }
+  /** Sends queued requests in order, one at a time. */
+  async flush() {
+    if (this.destroyed || this.sending || !this.items.length) return;
+    const wait = this.opts.health?.waitMs() ?? 0;
+    if (wait > 0) return this.retryIn(wait);
+    this.sending = true;
+    try {
+      while (this.items.length && !this.destroyed) {
+        const item = this.items[0];
+        let retry = false;
+        try {
+          const res = await this.opts.api.post(item.path, item.body);
+          retry = !res.ok && (res.status === 429 || res.status >= 500);
+        } catch (err) {
+          retry = true;
+          this.opts.onError?.(err);
+        }
+        if (retry) {
+          this.attempt += 1;
+          this.retryIn(Math.max(backoffMs(this.attempt - 1, 1e3, 6e4), this.opts.health?.waitMs() ?? 0));
+          return;
+        }
+        this.attempt = 0;
+        this.items = this.items.filter((i) => i !== item);
+        this.persist();
+      }
+    } finally {
+      this.sending = false;
+    }
+  }
+  destroy() {
+    this.destroyed = true;
+    this.offRecover?.();
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+};
+
 // src/queue.ts
 var EventQueue = class {
   constructor(opts) {
@@ -1368,17 +1586,34 @@ var EventQueue = class {
     __publicField(this, "inflightIds", /* @__PURE__ */ new Set());
     __publicField(this, "attempt", 0);
     __publicField(this, "destroyed", false);
+    __publicField(this, "offRecover", null);
     __publicField(this, "flushIntervalMs");
     __publicField(this, "maxQueue");
     __publicField(this, "batchSize");
     __publicField(this, "maxAttempts");
     this.flushIntervalMs = opts.flushIntervalMs ?? 2e3;
-    this.maxQueue = opts.maxQueue ?? 200;
+    this.maxQueue = opts.maxQueue ?? 500;
     this.batchSize = opts.batchSize ?? 50;
     this.maxAttempts = opts.maxAttempts ?? 5;
     const persisted = readJson(opts.store, opts.storageKey, []);
     if (Array.isArray(persisted)) this.events = persisted.filter((e) => e && typeof e.eventId === "string").slice(-this.maxQueue);
     if (this.events.length) this.schedule();
+    this.offRecover = opts.health?.onRecover(() => this.retryNow()) ?? null;
+  }
+  /** The API is back: drop any pending backoff and send what is queued. */
+  retryNow() {
+    if (this.destroyed) return;
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.retryTimer = null;
+    this.attempt = 0;
+    void this.flush();
+  }
+  retryIn(ms) {
+    if (this.retryTimer || this.destroyed) return;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      void this.flush();
+    }, ms);
   }
   get size() {
     return this.events.length;
@@ -1412,6 +1647,8 @@ var EventQueue = class {
       clearTimeout(this.timer);
       this.timer = null;
     }
+    const wait = this.opts.health?.waitMs() ?? 0;
+    if (wait > 0) return this.retryIn(wait);
     this.inflight = true;
     const batch = this.events.slice(0, this.batchSize);
     this.inflightIds = new Set(batch.map((e) => e.eventId));
@@ -1435,26 +1672,20 @@ var EventQueue = class {
       if (this.events.length) this.schedule();
       return;
     }
-    this.attempt += 1;
-    if (this.attempt >= this.maxAttempts) {
-      this.attempt = 0;
-      return;
-    }
-    this.retryTimer = setTimeout(() => {
-      this.retryTimer = null;
-      void this.flush();
-    }, backoffMs(this.attempt - 1));
+    this.attempt = Math.min(this.attempt + 1, this.maxAttempts);
+    const delay = this.attempt >= this.maxAttempts ? 6e4 : backoffMs(this.attempt - 1);
+    this.retryIn(Math.max(delay, this.opts.health?.waitMs() ?? 0));
   }
   /** Best-effort synchronous flush on unload using `sendBeacon`. */
   flushSync() {
     if (this.destroyed || !this.opts.enabled() || !this.opts.beacon) return;
     const batch = this.events.filter((e) => !this.inflightIds.has(e.eventId)).slice(0, this.batchSize);
     if (!batch.length) return;
-    if (this.opts.beacon(batch)) {
+    if (this.opts.beacon(batch) && (this.opts.health?.reachable ?? true)) {
       const ids = new Set(batch.map((e) => e.eventId));
       this.events = this.events.filter((e) => !ids.has(e.eventId));
-      this.persist();
     }
+    this.persist();
   }
   clear() {
     this.events = [];
@@ -1462,6 +1693,7 @@ var EventQueue = class {
   }
   destroy() {
     this.destroyed = true;
+    this.offRecover?.();
     if (this.timer) clearTimeout(this.timer);
     if (this.retryTimer) clearTimeout(this.retryTimer);
     this.timer = null;
@@ -1475,11 +1707,22 @@ var loadRecorder = async () => (await import("./recorder.cjs")).recorder;
 
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.9.0";
+var SDK_VERSION = "0.10.0";
 var DEFAULT_API_URL = "https://api.guidely.app";
 var PAGE_SCOPED = /* @__PURE__ */ new Set(["page_load", "url_match", "element_click", "element_visible", "delay"]);
 var DAY_MS = 24 * 60 * 60 * 1e3;
 var MAX_SESSION_EXCEPTIONS = 100;
+var CACHED_START_MS = 1500;
+function settlesWithin(promise, ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), ms);
+    const done = () => {
+      clearTimeout(timer);
+      resolve(true);
+    };
+    promise.then(done, done);
+  });
+}
 function isBrowser() {
   return typeof window !== "undefined" && typeof document !== "undefined";
 }
@@ -1490,7 +1733,7 @@ function emptyState() {
   return { guides: {}, checklists: {}, surveysSubmitted: [], audienceIds: [] };
 }
 function newSession(now = Date.now()) {
-  return { id: `s_${(0, import_runtime13.randomId)(16)}`, startedAt: new Date(now).toISOString(), shownGuides: [], events: [], lastActivityAt: now };
+  return { id: `s_${(0, import_runtime15.randomId)(16)}`, startedAt: new Date(now).toISOString(), shownGuides: [], events: [], lastActivityAt: now };
 }
 var GuidelyClient = class _GuidelyClient {
   constructor(options) {
@@ -1500,6 +1743,8 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "sessionStore");
     __publicField(this, "emitter");
     __publicField(this, "queue");
+    /** Survey answers and guide/checklist progress, kept until the server accepts them. */
+    __publicField(this, "outbox");
     __publicField(this, "config", null);
     __publicField(this, "etag", null);
     __publicField(this, "anonymousId");
@@ -1583,7 +1828,7 @@ var GuidelyClient = class _GuidelyClient {
     this.sessionStore = this.options.storage === "memory" ? this.store : createStorage("session");
     this.anonymousId = this.store.get(KEYS.anon) || "";
     if (!this.anonymousId) {
-      this.anonymousId = `anon_${(0, import_runtime13.randomId)(20)}`;
+      this.anonymousId = `anon_${(0, import_runtime15.randomId)(20)}`;
       this.store.set(KEYS.anon, this.anonymousId);
     }
     this.firstVisit = !this.store.get(KEYS.seen);
@@ -1599,6 +1844,7 @@ var GuidelyClient = class _GuidelyClient {
       store: this.store,
       storageKey: KEYS.queue(this.options.projectId),
       enabled: () => this.analyticsEnabled(),
+      health: this.api.health,
       send: async (events) => {
         const res = await this.api.post("/events", { events, sentAt: nowIso(), sdk: { name: SDK_NAME, version: SDK_VERSION } }, { keepalive: true });
         return { ok: res.ok, retry: !(res.status >= 400 && res.status < 500 && res.status !== 429) };
@@ -1606,6 +1852,7 @@ var GuidelyClient = class _GuidelyClient {
       beacon: (events) => this.api.beacon("/events", { events, sentAt: nowIso(), sdk: { name: SDK_NAME, version: SDK_VERSION } }),
       onError: (err) => this.reportError(err)
     });
+    this.outbox = new Outbox({ api: this.api, store: this.store, storageKey: KEYS.outbox(this.options.projectId), health: this.api.health });
     if (options.user) this.user = { ...options.user };
     this.flags = this.createFlags(options.flags);
   }
@@ -1663,12 +1910,15 @@ var GuidelyClient = class _GuidelyClient {
       const cached = readJson(this.store, KEYS.config(this.options.projectId), null);
       this.etag = this.store.get(KEYS.etag(this.options.projectId));
       if (cached && cached.guides) this.config = webOnly(cached);
-      await this.fetchConfig();
+      const before = this.config?.configVersion;
+      const fresh = this.fetchConfig();
+      if (!this.config) await fresh;
+      else if (!await settlesWithin(fresh, CACHED_START_MS)) void fresh.then(() => this.applyConfigChange(before));
       if (this.destroyed) return;
       this.wireListeners();
       if (!this.identitySettled) {
-        if (this.options.user) await this.identify(this.options.user.id, this.options.user.traits, this.options.user.account);
-        else if (this.user?.id) await this.identify(this.user.id, this.user.traits, this.user.account);
+        const known = this.options.user ?? (this.user?.id ? this.user : null);
+        if (known) await settlesWithin(this.identify(known.id, known.traits, known.account), CACHED_START_MS);
       }
       if (this.destroyed) return;
       this.isReady = true;
@@ -1773,7 +2023,12 @@ var GuidelyClient = class _GuidelyClient {
       win.removeEventListener("scroll", onScroll);
       doc.removeEventListener("keydown", onKey, true);
     });
-    const refresh = setInterval(() => void this.refresh(), this.options.configRefreshMs);
+    const refresh = setInterval(() => {
+      if (this.api.health.canSend()) void this.refresh();
+    }, this.options.configRefreshMs);
+    const onOnline = () => this.api.health.online();
+    win.addEventListener("online", onOnline);
+    this.cleanups.push(() => win.removeEventListener("online", onOnline));
     this.cleanups.push(() => clearInterval(refresh));
     const poll = setInterval(() => {
       if (!this.isReady || !this.config || this.editing() || doc.visibilityState === "hidden") return;
@@ -1806,6 +2061,11 @@ var GuidelyClient = class _GuidelyClient {
     if (this.destroyed) return;
     const before = this.config?.configVersion;
     await this.fetchConfig();
+    this.applyConfigChange(before);
+  }
+  /** Re-renders after a config change (refresh, or a config that arrived after start). */
+  applyConfigChange(before) {
+    if (this.destroyed || !this.isReady) return;
     if (this.config && this.config.configVersion !== before) {
       this.renderPersistentWidgets();
       this.evaluate("ready");
@@ -1840,6 +2100,7 @@ var GuidelyClient = class _GuidelyClient {
     this.replay = null;
     this.queue.flushSync();
     this.queue.destroy();
+    this.outbox.destroy();
     this.flags.destroy();
     this.emitter.clear();
     (0, import_guide_runtime4.destroyHost)();
@@ -1855,7 +2116,7 @@ var GuidelyClient = class _GuidelyClient {
     this.user = { id: String(userId), traits: { ...this.user?.id === String(userId) ? this.user.traits : {}, ...traits || {} }, account: account ?? (this.user?.id === String(userId) ? this.user.account : void 0) };
     writeJson(this.store, KEYS.user(this.options.projectId), this.user);
     this.syncFlagAttributes();
-    this.enqueue("identify", { properties: { traits: (0, import_runtime13.sanitizeProperties)(this.user.traits) } });
+    this.enqueue("identify", { properties: { traits: (0, import_runtime15.sanitizeProperties)(this.user.traits) } });
     await this.syncIdentify();
     this.emitter.emit("identify", { userId: this.user.id, anonymousId: this.anonymousId });
     if (this.isReady) this.evaluate("identify");
@@ -1928,7 +2189,7 @@ var GuidelyClient = class _GuidelyClient {
     this.stopGuide();
     this.user = null;
     this.store.remove(KEYS.user(this.options.projectId));
-    this.anonymousId = `anon_${(0, import_runtime13.randomId)(20)}`;
+    this.anonymousId = `anon_${(0, import_runtime15.randomId)(20)}`;
     this.store.set(KEYS.anon, this.anonymousId);
     this.state = emptyState();
     this.persistState();
@@ -1972,7 +2233,7 @@ var GuidelyClient = class _GuidelyClient {
     if (this.consent === "denied" || !this.options.analytics) return null;
     if (name !== "page_leave" && name !== "heatmap") this.touchSession();
     const event = {
-      eventId: (0, import_runtime13.randomId)(24),
+      eventId: (0, import_runtime15.randomId)(24),
       name,
       occurredAt: nowIso(),
       anonymousId: this.anonymousId,
@@ -1982,7 +2243,7 @@ var GuidelyClient = class _GuidelyClient {
       url: this.collectUrls() ? location.href : void 0,
       ...extra
     };
-    if (extra.properties) event.properties = (0, import_runtime13.sanitizeProperties)(extra.properties);
+    if (extra.properties) event.properties = (0, import_runtime15.sanitizeProperties)(extra.properties);
     this.queue.enqueue(event);
     this.replay?.addCustomEvent("guidely", { name, customName: event.customName, guideId: event.guideId });
     this.emitter.emit("track", event);
@@ -2042,7 +2303,7 @@ var GuidelyClient = class _GuidelyClient {
     if (changed) void this.queue.flush();
   }
   handleDocumentClick(e) {
-    const target = e.target;
+    const target = (0, import_guide_runtime4.composedTarget)(e);
     if (!target || typeof target.closest !== "function") return;
     this.autocaptureClick(e, target);
     this.completeChecklistTasksBy("click", target);
@@ -2137,7 +2398,7 @@ var GuidelyClient = class _GuidelyClient {
   }
   /** Bins one pointer sample into the heatmap buffer. Not session activity. */
   sampleMove(e) {
-    const target = e.target;
+    const target = (0, import_guide_runtime4.composedTarget)(e);
     if (document.visibilityState === "hidden" || !target?.closest || !this.autocaptureOn("mouseMovement") || isIgnoredElement(target)) return;
     const url = location.href;
     if (this.heatmap.url !== url) this.flushHeatmap();
@@ -2228,7 +2489,7 @@ var GuidelyClient = class _GuidelyClient {
   syncReplay() {
     const cfg = this.isReady && this.captureAllowed() ? this.replayConfig() : null;
     if (cfg && this.session.replay === void 0) {
-      this.session.replay = (0, import_runtime13.rolloutBucket)(this.session.id, "replay") < cfg.sampleRate;
+      this.session.replay = (0, import_runtime15.rolloutBucket)(this.session.id, "replay") < cfg.sampleRate;
       this.persistSession();
     }
     if (!cfg || !this.session.replay) {
@@ -2262,7 +2523,9 @@ var GuidelyClient = class _GuidelyClient {
             this.persistSession();
             this.replay?.stop({ discard: true });
           },
-          onError: (err) => this.reportError(err)
+          onError: (err) => this.reportError(err),
+          health: this.api.health,
+          stash: this.sessionStore
         });
         this.syncReplay();
       },
@@ -2328,7 +2591,7 @@ var GuidelyClient = class _GuidelyClient {
     if (!isWithinSchedule(guide)) return false;
     if (guide.kind === "survey" && (this.state.surveysSubmitted.includes(guide.id) || this.state.surveysSubmitted.includes(guide.key))) return false;
     ctx.rolloutSalt = guide.id;
-    return (0, import_runtime13.evaluateRules)(c.targeting, ctx);
+    return (0, import_runtime15.evaluateRules)(c.targeting, ctx);
   }
   isEligible(guide, ctx, url) {
     if (!this.isTargeted(guide, ctx, url)) return false;
@@ -2352,7 +2615,7 @@ var GuidelyClient = class _GuidelyClient {
       case "element_click":
         if (reason !== "click" || !t.value || !detail.target) return false;
         try {
-          return !!detail.target.closest(t.value);
+          return !!(0, import_guide_runtime4.closestComposed)(detail.target, t.value);
         } catch {
           return false;
         }
@@ -2503,7 +2766,9 @@ var GuidelyClient = class _GuidelyClient {
     if (reason === "completed") this.completeChecklistTasksBy("guide_completed", guide);
   }
   syncGuideState(guideId, update) {
-    void postWithRetry(this.api, "/guide-state", { anonymousId: this.anonymousId, userId: this.user?.id || null, updates: [{ guideId, ...update }] });
+    const body = { anonymousId: this.anonymousId, userId: this.user?.id || null, updates: [{ guideId, ...update }] };
+    if (update.impression) void postWithRetry(this.api, "/guide-state", body);
+    else this.outbox.add(`guide:${guideId}:${update.completed ? "completed" : "dismissed"}:${this.anonymousId}`, "/guide-state", body);
   }
   show(guide, manual, stepId) {
     try {
@@ -2626,12 +2891,12 @@ var GuidelyClient = class _GuidelyClient {
       title: guide.name,
       onDismiss: () => finish(this.state.surveysSubmitted.includes(guide.id) ? "submitted" : "dismissed"),
       onSubmit: (answers) => {
-        const responseId = (0, import_runtime13.randomId)(24);
+        const responseId = (0, import_runtime15.randomId)(24);
         this.state.surveysSubmitted.push(guide.id);
         this.persistState();
         this.recordEnd(guide, "completed");
         this.enqueue("survey_submitted", { guideId: guide.id, guideVersion: guide.version, properties: { responseId } });
-        void postWithRetry(this.api, `/surveys/${encodeURIComponent(guide.id)}/responses`, { anonymousId: this.anonymousId, userId: this.user?.id || null, accountId: this.user?.account?.id || null, guideVersion: guide.version, answers, responseId });
+        this.outbox.add(`survey:${responseId}`, `/surveys/${encodeURIComponent(guide.id)}/responses`, { anonymousId: this.anonymousId, userId: this.user?.id || null, accountId: this.user?.account?.id || null, guideVersion: guide.version, answers, responseId });
         this.emitter.emit("survey:submit", { guide, answers, responseId });
         this.emitter.emit("guide:complete", guide);
         widget.showThankYou();
@@ -2761,7 +3026,7 @@ var GuidelyClient = class _GuidelyClient {
       isAudienceTargeted: (g) => {
         if (!isWithinSchedule(g)) return false;
         ctx.rolloutSalt = g.id;
-        return (0, import_runtime13.evaluateRules)(g.config.targeting, ctx);
+        return (0, import_runtime15.evaluateRules)(g.config.targeting, ctx);
       },
       newsSeen: Array.isArray(seen) ? seen : []
     });
@@ -2820,7 +3085,7 @@ var GuidelyClient = class _GuidelyClient {
     }
     this.persistState();
     this.widgets.get(guide.id)?.checklist?.setProgress(this.getChecklistProgress(guide.id));
-    void postWithRetry(this.api, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, completed: !!progress.completedAt });
+    this.outbox.add(`checklist:${guide.id}:progress:${this.anonymousId}`, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, completed: !!progress.completedAt });
     this.emitter.emit("checklist:task", { guide, task, progress: this.getChecklistProgress(guide.id) });
     if (complete) {
       this.emitter.emit("checklist:complete", guide);
@@ -2840,7 +3105,7 @@ var GuidelyClient = class _GuidelyClient {
         else if (kind === "guide_completed") hit = value.id === task.completionValue || value.key === task.completionValue;
         else if (kind === "click") {
           try {
-            hit = !!value.closest(task.completionValue);
+            hit = !!(0, import_guide_runtime4.closestComposed)(value, task.completionValue);
           } catch {
             hit = false;
           }
@@ -2860,7 +3125,7 @@ var GuidelyClient = class _GuidelyClient {
     progress.dismissedAt = nowIso();
     this.persistState();
     this.enqueue("checklist_dismissed", { guideId: guide.id, guideVersion: guide.version });
-    void postWithRetry(this.api, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, dismissed: true });
+    this.outbox.add(`checklist:${guide.id}:dismissed:${this.anonymousId}`, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, dismissed: true });
     this.widgets.get(guide.id)?.destroy();
     this.widgets.delete(guide.id);
   }
@@ -3168,7 +3433,7 @@ var GuidelyClient = class _GuidelyClient {
 };
 var current = null;
 function webOnly(config) {
-  return config.guides.every((g) => (0, import_runtime13.supportsPlatform)(g.config, "web")) ? config : { ...config, guides: config.guides.filter((g) => (0, import_runtime13.supportsPlatform)(g.config, "web")) };
+  return config.guides.every((g) => (0, import_runtime15.supportsPlatform)(g.config, "web")) ? config : { ...config, guides: config.guides.filter((g) => (0, import_runtime15.supportsPlatform)(g.config, "web")) };
 }
 function pathOf2(url) {
   try {