@guidelytech/sdk-core 0.16.0 → 0.17.0

package/dist/index.js

@@ -5,24 +5,26 @@ import {
   areMutuallyExclusive,
   countsTowardThrottle,
   dismissedAfterMerge,
+  environmentFromKey,
   isExclusiveGuide,
   isFrequencyEligible,
   isThrottleEligible,
   isWithinSchedule,
   pruneLaunches
-} from "./chunk-2E2YUQAG.js";
+} from "./chunk-GFLVZRTS.js";
 import {
   Api,
   KEYS,
   __publicField,
   createStorage,
+  isServerFailure,
   postWithRetry,
   readJson,
   writeJson
 } from "./chunk-XML74K2P.js";
 
 // src/client.ts
-import { articleIdFromHref, evaluateRules, localizeGuide, localizeResourceCenter, normalizeLocale, randomId as randomId2, rolloutBucket, sanitizeProperties, supportsPlatform, visibleAnnouncements, visitorLocales } from "@guidelytech/shared/runtime";
+import { articleIdFromHref, errorFilterDrops, evaluateRules, localizeGuide, localizeResourceCenter, normalizeLocale, randomId as randomId2, rolloutBucket, sanitizeProperties, supportsPlatform, visibleAnnouncements, visitorLocales } from "@guidelytech/shared/runtime";
 import {
   closestComposed as closestComposed4,
   composedTarget,
@@ -572,10 +574,10 @@ var AuthoringBridge = class {
     this.observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
   }
   scheduleSnapshot() {
-    const now = Date.now();
-    if (!this.snapshotTimer) this.snapshotDue = now + SNAPSHOT_MAX_WAIT_MS;
+    const now3 = Date.now();
+    if (!this.snapshotTimer) this.snapshotDue = now3 + SNAPSHOT_MAX_WAIT_MS;
     else clearTimeout(this.snapshotTimer);
-    this.snapshotTimer = setTimeout(() => this.sendSnapshot(), Math.max(0, Math.min(SNAPSHOT_DEBOUNCE_MS, this.snapshotDue - now)));
+    this.snapshotTimer = setTimeout(() => this.sendSnapshot(), Math.max(0, Math.min(SNAPSHOT_DEBOUNCE_MS, this.snapshotDue - now3)));
   }
   sendSnapshot() {
     if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
@@ -880,12 +882,12 @@ function describe(value) {
   }
 }
 function exceptionFromError(error, source, handled, fallbackType = "Error") {
-  const isError = error instanceof Error || !!error && typeof error === "object" && typeof error.message === "string" && typeof error.stack === "string";
+  const isError2 = error instanceof Error || !!error && typeof error === "object" && typeof error.message === "string" && typeof error.stack === "string";
   const e = error;
   return {
-    type: isError && e.name || fallbackType,
-    message: (isError ? e.message : describe(error)).slice(0, 1e3),
-    frames: isError ? fitFrames(parseStack(e.stack)) : [],
+    type: isError2 && e.name || fallbackType,
+    message: (isError2 ? e.message : describe(error)).slice(0, 1e3),
+    frames: isError2 ? fitFrames(parseStack(e.stack)) : [],
     source,
     handled
   };
@@ -935,6 +937,222 @@ var ExceptionThrottle = class {
   }
 };
 
+// src/error-monitoring.ts
+import { MAX_BREADCRUMBS, MAX_EXCEPTION_CHAIN, normalizeTags, parseStack as parseStack2, trimExceptionDetail } from "@guidelytech/shared/runtime";
+var CONTEXT_KEYS = ["tags", "extra", "level", "fingerprint", "contexts", "user", "mechanism"];
+function splitHint(hint) {
+  const ctx = {};
+  const properties = {};
+  for (const [k, v] of Object.entries(hint ?? {})) (CONTEXT_KEYS.includes(k) ? ctx : properties)[k] = v;
+  return { ctx, properties };
+}
+var now = () => Date.now() / 1e3;
+var ErrorScope = class {
+  constructor(opts) {
+    __publicField(this, "opts", opts);
+    __publicField(this, "tags", {});
+    __publicField(this, "extra", {});
+    __publicField(this, "contexts", {});
+    __publicField(this, "user", {});
+    __publicField(this, "crumbs", []);
+  }
+  get max() {
+    return Math.max(0, Math.min(MAX_BREADCRUMBS, this.opts()?.maxBreadcrumbs ?? MAX_BREADCRUMBS));
+  }
+  addBreadcrumb(crumb, hint) {
+    let c = { timestamp: now(), ...crumb };
+    const before = this.opts()?.beforeBreadcrumb;
+    if (before) {
+      try {
+        c = before(c, hint);
+      } catch {
+      }
+    }
+    if (!c || !this.max) return;
+    this.crumbs.push(c);
+    if (this.crumbs.length > this.max) this.crumbs.splice(0, this.crumbs.length - this.max);
+  }
+  breadcrumbs() {
+    return this.crumbs.slice();
+  }
+  clear() {
+    this.tags = {};
+    this.extra = {};
+    this.contexts = {};
+    this.user = {};
+    this.crumbs = [];
+  }
+};
+function toDetailFrames(frames) {
+  const out = [];
+  for (let i = frames.length - 1; i >= 0; i--) {
+    const f = frames[i];
+    out.push({ ...f.fn ? { function: f.fn } : {}, ...f.file ? { abs_path: f.file, filename: f.file } : {}, ...f.line ? { lineno: f.line } : {}, ...f.col ? { colno: f.col } : {}, ...typeof f.inApp === "boolean" ? { in_app: f.inApp } : {} });
+  }
+  return out;
+}
+var isError = (v) => v instanceof Error || !!v && typeof v === "object" && typeof v.message === "string" && typeof v.stack === "string";
+function exceptionChain(error, main, mechanism) {
+  const chain = [{ type: main.type, value: main.message, mechanism: { type: mechanism, handled: main.handled !== false, exception_id: 0 }, stacktrace: { frames: toDetailFrames(main.frames) } }];
+  const seen = /* @__PURE__ */ new Set([error]);
+  let cur = isError(error) ? error.cause : void 0;
+  while (cur !== void 0 && cur !== null && !seen.has(cur) && chain.length < MAX_EXCEPTION_CHAIN) {
+    seen.add(cur);
+    const e = cur;
+    const id = chain.length;
+    chain.push({
+      type: isError(e) && e.name || "Error",
+      value: (isError(e) ? e.message : String(cur)).slice(0, 1e3),
+      mechanism: { type: "chained", source: "cause", handled: true, exception_id: id, parent_id: id - 1 },
+      ...isError(e) ? { stacktrace: { frames: toDetailFrames(parseStack2(e.stack, 50)) } } : {}
+    });
+    cur = isError(e) ? e.cause : void 0;
+  }
+  return chain.reverse();
+}
+var VERSION_TOKEN = { chrome: "(?:Chrome|CriOS)", edge: "Edg", firefox: "(?:Firefox|FxiOS)", safari: "Version", opera: "OPR", samsung: "SamsungBrowser", electron: "Electron" };
+var OS_VERSION = /(?:Mac OS X|Windows NT|Android|CPU (?:iPhone )?OS) ([\d._]+)/;
+var NAMES = { chrome: "Chrome", edge: "Edge", firefox: "Firefox", safari: "Safari", opera: "Opera", samsung: "Samsung Internet", electron: "Electron", ie: "Internet Explorer", macos: "macOS", windows: "Windows", ios: "iOS", android: "Android", linux: "Linux", chromeos: "Chrome OS" };
+function browserContexts(ua, device) {
+  const out = {};
+  const token = device.browser ? VERSION_TOKEN[device.browser] : void 0;
+  const v = token ? new RegExp(`${token}/([\\d.]+)`).exec(ua)?.[1] : void 0;
+  if (device.browser) out.browser = { name: NAMES[device.browser] ?? device.browser, ...v ? { version: v } : {} };
+  const ov = OS_VERSION.exec(ua)?.[1]?.replace(/_/g, ".");
+  if (device.os) out.os = { name: NAMES[device.os] ?? device.os, ...ov ? { version: ov } : {} };
+  out.device = { family: device.type === "desktop" ? "Desktop" : device.type === "tablet" ? "Tablet" : "Mobile" };
+  return out;
+}
+function buildDetail(input) {
+  const { scope, ctx } = input;
+  const contexts = { ...input.contexts, ...scope.contexts };
+  for (const [k, v] of Object.entries(ctx.contexts ?? {})) if (v) contexts[k] = v;
+  const user = { ...scope.user, ...ctx.user ?? {} };
+  const detail = {
+    level: input.level,
+    exception: { values: input.props.type === "Message" ? [] : exceptionChain(input.error, input.props, input.mechanism) },
+    breadcrumbs: { values: scope.breadcrumbs() },
+    contexts,
+    tags: normalizeTags({ ...scope.tags, ...ctx.tags ?? {} }),
+    extra: { ...scope.extra, ...ctx.extra ?? {} },
+    ...Object.keys(user).length ? { user } : {},
+    ...ctx.fingerprint?.length ? { fingerprint: ctx.fingerprint.map(String) } : {}
+  };
+  return trimExceptionDetail(detail);
+}
+var isOwnRequest = (url, apiUrl) => !!apiUrl && url.startsWith(apiUrl) && /\/api\/v1\/sdk\//.test(url);
+function breadcrumbUrl(raw) {
+  try {
+    const u = new URL(raw, typeof location !== "undefined" ? location.href : "http://localhost/");
+    return (u.origin === "null" ? u.protocol : u.origin) + u.pathname;
+  } catch {
+    return raw.replace(/[?#].*$/, "");
+  }
+}
+function describeArg(a) {
+  if (typeof a === "string") return a;
+  if (a instanceof Error) return `${a.name}: ${a.message}`;
+  try {
+    return JSON.stringify(a) ?? String(a);
+  } catch {
+    return String(a);
+  }
+}
+var XHR_INFO = "__guidelyCrumb";
+function instrumentBreadcrumbs(add, opts) {
+  let on = true;
+  const undo = [];
+  const g = globalThis;
+  if (opts.console !== false && g.console) {
+    const levels = opts.console === "all" ? ["log", "info", "warn", "error", "debug"] : ["warn", "error"];
+    for (const level of levels) {
+      const original = g.console[level];
+      if (typeof original !== "function") continue;
+      const wrapped = function(...args) {
+        if (on) {
+          try {
+            const message = args.map(describeArg).join(" ").slice(0, 1e3);
+            if (!message.startsWith("[Guidely]")) add({ category: "console", level: level === "warn" ? "warning" : level === "log" ? "info" : level, message, data: { logger: "console" } }, { event: args });
+          } catch {
+          }
+        }
+        return original.apply(this, args);
+      };
+      g.console[level] = wrapped;
+      undo.push(() => {
+        if (g.console[level] === wrapped) g.console[level] = original;
+      });
+    }
+  }
+  if (opts.http !== false && typeof g.fetch === "function") {
+    const original = g.fetch;
+    const wrapped = function(input, init) {
+      const started = Date.now();
+      let url = "";
+      let method = "GET";
+      try {
+        url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        method = (init?.method ?? (typeof input === "object" && "method" in input ? input.method : "GET")).toUpperCase();
+      } catch {
+      }
+      const p = original.call(this, input, init);
+      if (on && url && !isOwnRequest(url, opts.apiUrl)) {
+        const crumb = (status) => {
+          try {
+            add({ type: "http", category: "fetch", level: status === void 0 || status >= 500 ? "error" : status >= 400 ? "warning" : "info", data: { method, url: breadcrumbUrl(url), ...status !== void 0 ? { status_code: status } : {}, duration_ms: Date.now() - started } });
+          } catch {
+          }
+        };
+        p.then(
+          (res) => crumb(res.status),
+          () => crumb(void 0)
+        );
+      }
+      return p;
+    };
+    g.fetch = wrapped;
+    undo.push(() => {
+      if (g.fetch === wrapped) g.fetch = original;
+    });
+  }
+  const proto = opts.http !== false ? g.XMLHttpRequest?.prototype : void 0;
+  if (proto) {
+    const open = proto.open;
+    const send = proto.send;
+    const wrappedOpen = function(method, url, ...rest) {
+      try {
+        this[XHR_INFO] = { method: String(method).toUpperCase(), url: String(url) };
+      } catch {
+      }
+      return open.call(this, method, url, ...rest);
+    };
+    const wrappedSend = function(body) {
+      const info = this[XHR_INFO];
+      if (on && info && !isOwnRequest(info.url, opts.apiUrl)) {
+        const started = Date.now();
+        this.addEventListener("loadend", () => {
+          try {
+            const status = this.status || void 0;
+            add({ type: "http", category: "xhr", level: !status || status >= 500 ? "error" : status >= 400 ? "warning" : "info", data: { method: info.method, url: breadcrumbUrl(info.url), ...status ? { status_code: status } : {}, duration_ms: Date.now() - started } }, { event: this });
+          } catch {
+          }
+        });
+      }
+      return send.call(this, body);
+    };
+    proto.open = wrappedOpen;
+    proto.send = wrappedSend;
+    undo.push(() => {
+      if (proto.open === wrappedOpen) proto.open = open;
+      if (proto.send === wrappedSend) proto.send = send;
+    });
+  }
+  return () => {
+    on = false;
+    for (const u of undo) u();
+  };
+}
+
 // src/messenger-api.ts
 var MAX_STORED = 50;
 var TOKEN_HEADER = "X-Guidely-Conversation";
@@ -1123,7 +1341,7 @@ function plainText(html, max = 280) {
   return text.length > max ? `${text.slice(0, max - 1).trimEnd()}\u2026` : text;
 }
 function buildMessengerVisitor(input) {
-  const now = input.now ?? Date.now();
+  const now3 = input.now ?? Date.now();
   const { guides, state } = input;
   const done = (g) => !!state.guides[g.id]?.completedAt;
   const pageGuides = guides.filter((g) => PAGE_GUIDE_KINDS.has(g.kind) && g.config.steps.length > 0 && !done(g) && targetsPage(g, input.url) && input.isTargeted(g)).slice(0, 3).map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind }));
@@ -1133,7 +1351,7 @@ function buildMessengerVisitor(input) {
     const s = state.guides[g.id];
     if (g.kind !== "flow" || !s?.lastStepId || s.completedAt || g.config.steps.length < 2) continue;
     const at = Date.parse(s.lastShownAt ?? "");
-    if (!Number.isFinite(at) || now - at > RESUME_WITHIN_MS || at <= resumeAt) continue;
+    if (!Number.isFinite(at) || now3 - at > RESUME_WITHIN_MS || at <= resumeAt) continue;
     const stepIndex = g.config.steps.findIndex((st) => st.id === s.lastStepId);
     if (stepIndex < 1 || !isWithinSchedule(g)) continue;
     resumeGuide = { id: g.id, name: g.name, stepId: s.lastStepId, stepIndex, stepCount: g.config.steps.length };
@@ -1152,7 +1370,7 @@ function buildMessengerVisitor(input) {
     break;
   }
   const seen = new Set(input.newsSeen);
-  const news = guides.filter((g) => g.kind === "announcement" && g.config.steps.length > 0 && now - Date.parse(g.publishedAt) <= NEWS_WITHIN_MS && input.isAudienceTargeted(g)).sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)).slice(0, MAX_NEWS).map((g) => {
+  const news = guides.filter((g) => g.kind === "announcement" && g.config.steps.length > 0 && now3 - Date.parse(g.publishedAt) <= NEWS_WITHIN_MS && input.isAudienceTargeted(g)).sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)).slice(0, MAX_NEWS).map((g) => {
     const step = g.config.steps[0];
     return {
       id: g.id,
@@ -1282,19 +1500,19 @@ var PageTracker = class {
     __publicField(this, "maxScroll", 0);
   }
   /** Starts measuring a new page. */
-  start(url, now = Date.now()) {
+  start(url, now3 = Date.now()) {
     this.url = url;
     this.visibleMs = 0;
-    this.visibleSince = typeof document !== "undefined" && document.visibilityState === "hidden" ? null : now;
+    this.visibleSince = typeof document !== "undefined" && document.visibilityState === "hidden" ? null : now3;
     this.maxScroll = 0;
     this.measureScroll();
   }
   /** Pauses / resumes the visible-time clock. */
-  setHidden(hidden, now = Date.now()) {
+  setHidden(hidden, now3 = Date.now()) {
     if (hidden && this.visibleSince !== null) {
-      this.visibleMs += Math.max(0, now - this.visibleSince);
+      this.visibleMs += Math.max(0, now3 - this.visibleSince);
       this.visibleSince = null;
-    } else if (!hidden && this.visibleSince === null) this.visibleSince = now;
+    } else if (!hidden && this.visibleSince === null) this.visibleSince = now3;
   }
   measureScroll() {
     try {
@@ -1303,9 +1521,9 @@ var PageTracker = class {
     }
   }
   /** Final numbers for the current page. */
-  leave(now = Date.now()) {
+  leave(now3 = Date.now()) {
     this.measureScroll();
-    const running = this.visibleSince !== null ? Math.max(0, now - this.visibleSince) : 0;
+    const running = this.visibleSince !== null ? Math.max(0, now3 - this.visibleSince) : 0;
     return { url: this.url, durationMs: Math.round(this.visibleMs + running), scrollDepth: this.maxScroll };
   }
 };
@@ -1413,17 +1631,622 @@ function openPrototypeOverlay(testUrl, opts) {
 // src/load-recorder.ts
 var loadRecorder = async () => (await import("./recorder.js")).recorder;
 
+// src/trace-propagation.ts
+function hex(bytes) {
+  const a = new Uint8Array(bytes);
+  try {
+    crypto.getRandomValues(a);
+  } catch {
+    for (let i = 0; i < bytes; i++) a[i] = Math.floor(Math.random() * 256);
+  }
+  let out = "";
+  for (const b of a) out += (b < 16 ? "0" : "") + b.toString(16);
+  return out;
+}
+function stripUrl(url) {
+  return url.split(/[?#]/)[0];
+}
+function resolveUrl(url) {
+  try {
+    return new URL(url, location.href).href;
+  } catch {
+    return url;
+  }
+}
+function shouldPropagate(url, targets) {
+  const abs = resolveUrl(url);
+  if (!targets) {
+    try {
+      return new URL(abs).origin === location.origin;
+    } catch {
+      return false;
+    }
+  }
+  return targets.some((t) => {
+    if (typeof t === "string") return url.includes(t) || abs.includes(t);
+    t.lastIndex = 0;
+    if (t.test(url)) return true;
+    t.lastIndex = 0;
+    return t.test(abs);
+  });
+}
+function mergeBaggage(existing, ours) {
+  const kept = (existing || "").split(",").map((s) => s.trim()).filter((s) => s && !s.startsWith("sentry-"));
+  return [...kept, ours].join(",");
+}
+function traceHeaders(dsc, spanId) {
+  const flag = dsc.sampled ? "1" : "0";
+  const e = encodeURIComponent;
+  const baggage = [`sentry-trace_id=${dsc.traceId}`, `sentry-public_key=${e(dsc.publicKey)}`, dsc.release ? `sentry-release=${e(dsc.release)}` : "", dsc.environment ? `sentry-environment=${e(dsc.environment)}` : "", `sentry-sampled=${dsc.sampled}`, `sentry-sample_rate=${dsc.sampleRate}`].filter(Boolean).join(",");
+  return { "sentry-trace": `${dsc.traceId}-${spanId}-${flag}`, traceparent: `00-${dsc.traceId}-${spanId}-0${flag}`, baggage };
+}
+function httpSpanStatus(code) {
+  if (code >= 100 && code < 400) return "ok";
+  if (code >= 400 && code < 500) return { 401: "unauthenticated", 403: "permission_denied", 404: "not_found", 409: "already_exists", 413: "failed_precondition", 429: "resource_exhausted", 499: "cancelled" }[code] ?? "invalid_argument";
+  if (code >= 500 && code < 600) return { 501: "unimplemented", 503: "unavailable", 504: "deadline_exceeded" }[code] ?? "internal_error";
+  return "unknown_error";
+}
+
+// src/web-vitals.ts
+function observe(type, cb, extra = {}) {
+  try {
+    if (typeof PerformanceObserver === "undefined" || !PerformanceObserver.supportedEntryTypes?.includes(type)) return null;
+    const po = new PerformanceObserver((list) => cb(list.getEntries()));
+    po.observe({ type, buffered: true, ...extra });
+    return { take: () => cb(po.takeRecords()), stop: () => po.disconnect() };
+  } catch {
+    return null;
+  }
+}
+var newCls = () => ({ value: 0, session: 0, first: 0, last: 0 });
+function addLayoutShift(s, e) {
+  if (e.hadRecentInput) return;
+  if (s.session && e.startTime - s.last < 1e3 && e.startTime - s.first < 5e3) s.session += e.value;
+  else {
+    s.session = e.value;
+    s.first = e.startTime;
+  }
+  s.last = e.startTime;
+  if (s.session > s.value) s.value = s.session;
+}
+var newInp = () => ({ longest: [], ids: /* @__PURE__ */ new Set() });
+function addInteraction(s, e) {
+  const id = e.interactionId;
+  if (!id) return;
+  s.ids.add(id);
+  const known = s.longest.find((i) => i.id === id);
+  if (known) known.latency = Math.max(known.latency, e.duration);
+  else if (s.longest.length < 10 || e.duration > s.longest[s.longest.length - 1].latency) s.longest.push({ id, latency: e.duration });
+  else return;
+  s.longest.sort((a, b) => b.latency - a.latency);
+  s.longest.splice(10);
+}
+function inpValue(s, count = s.ids.size) {
+  if (!s.longest.length) return void 0;
+  return s.longest[Math.min(s.longest.length - 1, Math.floor(count / 50))].latency;
+}
+var ms = (value) => ({ value, unit: "millisecond" });
+var WebVitals = class {
+  constructor(nav) {
+    __publicField(this, "lcp");
+    __publicField(this, "fcp");
+    __publicField(this, "ttfb");
+    __publicField(this, "cls", newCls());
+    __publicField(this, "inp", newInp());
+    __publicField(this, "observed", []);
+    __publicField(this, "lcpFinal", false);
+    __publicField(this, "hiddenAt");
+    __publicField(this, "offs", []);
+    const activation = nav?.activationStart || 0;
+    const rel = (t) => Math.max(0, t - activation);
+    this.hiddenAt = document.visibilityState === "hidden" ? 0 : Infinity;
+    if (nav && nav.responseStart > 0) this.ttfb = rel(nav.responseStart);
+    const add = (o) => o && this.observed.push(o);
+    add(
+      observe("paint", (es) => {
+        for (const e of es) if (e.name === "first-contentful-paint" && e.startTime < this.hiddenAt) this.fcp = rel(e.startTime);
+      })
+    );
+    add(
+      observe("largest-contentful-paint", (es) => {
+        const e = es[es.length - 1];
+        if (e && !this.lcpFinal && e.startTime < this.hiddenAt) this.lcp = rel(e.startTime);
+      })
+    );
+    add(observe("layout-shift", (es) => es.forEach((e) => addLayoutShift(this.cls, e))));
+    const onEvent = (es) => es.forEach((e) => addInteraction(this.inp, e));
+    add(observe("event", onEvent, { durationThreshold: 40 }));
+    add(observe("first-input", onEvent));
+    const freeze = () => {
+      this.lcpFinal = true;
+      this.offs.splice(0).forEach((f) => f());
+    };
+    for (const type of ["keydown", "pointerdown"]) {
+      addEventListener(type, freeze, { once: true, capture: true });
+      this.offs.push(() => removeEventListener(type, freeze, { capture: true }));
+    }
+  }
+  /** The page was hidden: deliver pending entries and freeze LCP. */
+  hidden() {
+    this.observed.forEach((o) => o.take());
+    this.lcpFinal = true;
+    if (this.hiddenAt === Infinity) this.hiddenAt = performance.now();
+  }
+  /** Known at load: LCP (so far), FCP and TTFB. */
+  pageload() {
+    const m = {};
+    if (this.lcp !== void 0) m.lcp = ms(this.lcp);
+    if (this.fcp !== void 0) m.fcp = ms(this.fcp);
+    if (this.ttfb !== void 0) m.ttfb = ms(this.ttfb);
+    return m;
+  }
+  /** Known only when the page is hidden: CLS, and INP once there was an interaction. */
+  late() {
+    const count = performance.interactionCount;
+    const inp = inpValue(this.inp, count || void 0);
+    return { cls: { value: this.cls.value, unit: "" }, ...inp !== void 0 ? { inp: ms(inp) } : {} };
+  }
+  stop() {
+    this.observed.splice(0).forEach((o) => o.stop());
+    this.offs.splice(0).forEach((f) => f());
+  }
+};
+
+// src/tracing.ts
+var TRACES_SDK_NAME = "guidely.javascript";
+var MAX_SPANS = 1e3;
+var MAX_QUEUE = 20;
+var BATCH = 10;
+var now2 = () => performance.now();
+function entries(type) {
+  try {
+    return performance.getEntriesByType(type);
+  } catch {
+    return [];
+  }
+}
+function pathOf2(href) {
+  try {
+    return new URL(href).pathname || "/";
+  } catch {
+    return stripUrl(href) || "/";
+  }
+}
+function browserContext() {
+  const ua = navigator.userAgent || "";
+  const name = detectDevice(ua, 1024).browser;
+  if (!name) return void 0;
+  const token = { edge: "Edg", opera: "OPR", samsung: "SamsungBrowser", chrome: "(?:Chrome|CriOS)", firefox: "(?:Firefox|FxiOS)", safari: "Version", electron: "Electron" }[name];
+  const version = token ? new RegExp(`${token}/([\\d.]+)`).exec(ua)?.[1] : void 0;
+  return { name: name[0].toUpperCase() + name.slice(1), ...version ? { version } : {} };
+}
+function startTracer(config) {
+  if (typeof performance === "undefined" || typeof performance.now !== "function" || typeof window === "undefined") return null;
+  return new Tracer(config);
+}
+var Tracer = class {
+  constructor(o) {
+    __publicField(this, "o", o);
+    /** null until the project setting is known; then whether tracing is on for this page load. */
+    __publicField(this, "enabled", null);
+    __publicField(this, "sampled", false);
+    __publicField(this, "rate", 0);
+    __publicField(this, "txn", null);
+    __publicField(this, "pageload");
+    __publicField(this, "origin");
+    __publicField(this, "vitals");
+    __publicField(this, "longTasks", []);
+    /** Finished before sampling was decided. */
+    __publicField(this, "held", []);
+    __publicField(this, "out", []);
+    __publicField(this, "flushTimer", null);
+    __publicField(this, "cleanups", []);
+    __publicField(this, "stopped", false);
+    __publicField(this, "vitalsSent", false);
+    __publicField(this, "apiPrefix");
+    __publicField(this, "idleMs");
+    __publicField(this, "finalMs");
+    this.idleMs = o.idleMs ?? 1e3;
+    this.finalMs = o.finalMs ?? 3e4;
+    this.origin = performance.timeOrigin || Date.now() - now2();
+    this.apiPrefix = `${resolveUrl(o.apiUrl).replace(/\/+$/, "")}/api/v1/sdk/`;
+    this.vitals = new WebVitals(entries("navigation")[0]);
+    const lt = observe("longtask", (es) => {
+      for (const e of es) if (this.longTasks.length < 500) this.longTasks.push(e);
+    });
+    if (lt) this.cleanups.push(lt.stop);
+    this.instrumentFetch();
+    this.instrumentXhr();
+    this.cleanups.push(watchNavigation((href) => this.navigate(href), 0));
+    const onVisibility = () => document.visibilityState === "hidden" && this.onHide();
+    const onPageHide = () => this.onHide();
+    document.addEventListener("visibilitychange", onVisibility);
+    addEventListener("pagehide", onPageHide);
+    this.cleanups.push(() => {
+      document.removeEventListener("visibilitychange", onVisibility);
+      removeEventListener("pagehide", onPageHide);
+    });
+    const t = this.pageload = this.begin("pageload", 0);
+    const onLoad = () => setTimeout(() => {
+      t.loaded = true;
+      this.scheduleIdle(t);
+    }, 0);
+    if (document.readyState === "complete") onLoad();
+    else {
+      addEventListener("load", onLoad, { once: true });
+      this.cleanups.push(() => removeEventListener("load", onLoad));
+    }
+  }
+  /** Applies the project's `performance` setting; sampling is decided the first time it is on. */
+  configure(settings) {
+    if (this.stopped) return;
+    if (!settings?.enabled) {
+      this.enabled = false;
+      this.held = [];
+      this.out = [];
+      return this.stop();
+    }
+    if (this.enabled) return;
+    this.enabled = true;
+    const sdkRate = this.o.tracesSampleRate ?? 1;
+    this.rate = Math.max(0, Math.min((settings.sampleRate ?? 100) / 100, Number.isFinite(sdkRate) ? sdkRate : 1, 1));
+    this.sampled = Math.random() < this.rate;
+    if (!this.sampled) this.vitals.stop();
+    for (const e of this.held.splice(0)) if (this.sampled) this.enqueue(e);
+  }
+  /**
+   * The trace an error happening now belongs to (the open navigation, else the page load), so error
+   * events link to it. Null when this page load isn't traced.
+   */
+  traceContext() {
+    if (!this.enabled || !this.sampled || this.stopped) return null;
+    const t = this.txn ?? this.pageload;
+    return { traceId: t.traceId, spanId: t.spanId };
+  }
+  /** Stops tracing and sends what is queued. */
+  destroy() {
+    this.flush(true);
+    this.stop();
+  }
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    for (const t of [this.txn, this.pageload]) {
+      clearTimeout(t?.idle);
+      clearTimeout(t?.final);
+    }
+    this.vitals.stop();
+    this.cleanups.splice(0).forEach((f) => f());
+  }
+  ts(rel) {
+    return (this.origin + rel) / 1e3;
+  }
+  begin(op, start, href) {
+    const url = this.o.pageHref(href);
+    const t = { op, name: pathOf2(url), url, traceId: hex(16), spanId: hex(8), start, last: start, inflight: 0, spans: [], loaded: op !== "pageload" };
+    t.final = setTimeout(() => this.finish(t), Math.max(0, this.finalMs - (now2() - start)));
+    this.txn = t;
+    return t;
+  }
+  scheduleIdle(t) {
+    clearTimeout(t.idle);
+    if (t.done || t.inflight > 0 || !t.loaded) return;
+    t.idle = setTimeout(() => this.finish(t), this.idleMs);
+  }
+  navigate(href) {
+    if (this.stopped || pathOf2(this.o.pageHref(href)) === this.txn?.name) return;
+    if (this.txn && !this.txn.done) this.finish(this.txn);
+    this.scheduleIdle(this.begin("navigation", now2(), href));
+  }
+  onHide() {
+    if (this.stopped) return;
+    this.vitals.hidden();
+    if (this.txn && !this.txn.done) this.finish(this.txn, now2());
+    if (this.enabled && this.sampled && !this.vitalsSent) {
+      this.vitalsSent = true;
+      const at = this.ts(now2());
+      const p = this.pageload;
+      const e = this.event(p, "ui.webvitals", at, at, [], this.vitals.late());
+      e.contexts.trace.span_id = hex(8);
+      e.contexts.trace.parent_span_id = p.spanId;
+      this.enqueue(e);
+    }
+    this.flush(true);
+  }
+  /** Ends a transaction: adds the spans read from performance entries and queues (or holds) it. */
+  finish(t, endAt) {
+    if (t.done) return;
+    t.done = true;
+    clearTimeout(t.idle);
+    clearTimeout(t.final);
+    if (this.stopped || this.enabled === false || this.enabled && !this.sampled) return;
+    const until = now2();
+    const spans = t.spans;
+    const add = (op, description, start, end2, origin, data) => {
+      if (spans.length >= MAX_SPANS || !(end2 >= start) || start < t.start || start > until) return;
+      spans.push({ span_id: hex(8), parent_span_id: t.spanId, trace_id: t.traceId, op, description, start_timestamp: this.ts(start), timestamp: this.ts(end2), origin, ...data ? { data } : {} });
+    };
+    if (t.op === "pageload") {
+      const n = entries("navigation")[0];
+      if (n) {
+        const timing = (name, s, e) => s > 0 && e > 0 && add("browser", name, s, e, "auto.ui.browser.metrics");
+        timing("redirect", n.redirectStart, n.redirectEnd);
+        timing("cache", n.fetchStart, n.domainLookupStart);
+        timing("DNS", n.domainLookupStart, n.domainLookupEnd);
+        timing("connect", n.connectStart, n.connectEnd);
+        timing("TLS/SSL", n.secureConnectionStart, n.connectEnd);
+        timing("request", n.requestStart, n.responseEnd);
+        timing("response", n.responseStart, n.responseEnd);
+        timing("domContentLoadedEvent", n.domContentLoadedEventStart, n.domContentLoadedEventEnd);
+        timing("loadEvent", n.loadEventStart, n.loadEventEnd);
+      }
+    }
+    for (const e of entries("resource")) {
+      const it = e.initiatorType;
+      if (it === "fetch" || it === "xmlhttprequest" || this.own(e.name)) continue;
+      const kind = it === "script" || it === "css" || it === "link" ? it : it === "img" || it === "image" ? "img" : "other";
+      const data = { "http.response_content_length": e.encodedBodySize, "http.decoded_response_content_length": e.decodedBodySize, "http.response_transfer_size": e.transferSize };
+      if (e.renderBlockingStatus) data["resource.render_blocking_status"] = e.renderBlockingStatus;
+      add(`resource.${kind}`, stripUrl(e.name), e.startTime, e.responseEnd || e.startTime + e.duration, "auto.resource.browser.metrics", data);
+    }
+    for (const e of this.longTasks) add("ui.long-task", "Main UI thread blocked", e.startTime, e.startTime + e.duration, "auto.ui.browser.metrics");
+    for (const e of entries("mark")) add("mark", e.name, e.startTime, e.startTime, "auto.ui.browser.metrics");
+    for (const e of entries("measure")) add("measure", e.name, e.startTime, e.startTime + e.duration, "auto.ui.browser.metrics");
+    const end = endAt !== void 0 ? this.ts(endAt) : spans.reduce((m2, s) => Math.max(m2, s.timestamp), this.ts(t.last));
+    const m = t.op === "pageload" ? this.vitals.pageload() : {};
+    const event = this.event(t, t.op, this.ts(t.start), end, spans, Object.keys(m).length ? m : void 0);
+    if (this.enabled) this.enqueue(event);
+    else if (this.held.length < MAX_QUEUE) this.held.push(event);
+  }
+  event(t, op, start, end, spans, measurements) {
+    const c = this.o.context();
+    const url = c.collectUrls ? stripUrl(t.url) : void 0;
+    const browser = browserContext();
+    return {
+      type: "transaction",
+      event_id: hex(16),
+      platform: "javascript",
+      transaction: t.name,
+      transaction_info: { source: "url" },
+      start_timestamp: start,
+      timestamp: end,
+      ...c.release ? { release: c.release } : {},
+      environment: c.environment,
+      contexts: {
+        trace: { trace_id: t.traceId, span_id: t.spanId, op, status: "ok", origin: `auto.${op}.guidely` },
+        ...browser ? { browser } : {},
+        guidely: { anonymousId: c.anonymousId, sessionId: c.sessionId, ...url ? { url } : {} }
+      },
+      spans,
+      ...measurements ? { measurements } : {},
+      ...url ? { request: { url } } : {},
+      ...c.userId ? { user: { id: c.userId } } : {}
+    };
+  }
+  // --- requests ---------------------------------------------------------------------------------
+  /** A Guidely API request (never traced, never given headers). */
+  own(url) {
+    return resolveUrl(url).startsWith(this.apiPrefix);
+  }
+  startHttp(method, url, type) {
+    if (this.stopped || this.enabled === false || this.own(url)) return null;
+    const abs = resolveUrl(url);
+    const t = this.txn && !this.txn.done ? this.txn : null;
+    const spanId = hex(8);
+    let span = null;
+    if (t && (this.enabled === null || this.sampled)) {
+      const u = stripUrl(abs);
+      span = { span_id: spanId, parent_span_id: t.spanId, trace_id: t.traceId, op: "http.client", description: `${method} ${u}`, start_timestamp: this.ts(now2()), timestamp: 0, origin: "auto.http.browser", data: { "http.method": method, url: u, type } };
+      t.inflight += 1;
+      clearTimeout(t.idle);
+    }
+    return { txn: t, span, spanId, url };
+  }
+  endHttp(live, status, length) {
+    const { txn: t, span } = live;
+    if (!t || !span) return;
+    t.inflight = Math.max(0, t.inflight - 1);
+    t.last = now2();
+    span.timestamp = this.ts(t.last);
+    span.status = status ? httpSpanStatus(status) : "unknown_error";
+    if (status) span.data["http.response.status_code"] = status;
+    if (length && Number(length) >= 0) span.data["http.response_content_length"] = Number(length);
+    if (!t.done && t.spans.length < MAX_SPANS) t.spans.push(span);
+    this.scheduleIdle(t);
+  }
+  /** Trace headers for a request, or null when it must not get any (tracing undecided / off, or not a target). */
+  headers(live, baggage) {
+    if (!this.enabled || this.stopped || !shouldPropagate(live.url, this.o.tracePropagationTargets)) return null;
+    const c = this.o.context();
+    const h = traceHeaders({ traceId: (live.txn ?? this.txn ?? this.pageload).traceId, publicKey: this.o.publicKey, release: c.release, environment: c.environment, sampled: this.sampled, sampleRate: this.rate }, live.spanId);
+    return { ...h, baggage: mergeBaggage(baggage, h.baggage) };
+  }
+  instrumentFetch() {
+    const win = window;
+    const orig = win.fetch;
+    if (typeof orig !== "function") return;
+    const patched = (input, init) => {
+      let live = null;
+      try {
+        const isReq = typeof Request !== "undefined" && input instanceof Request;
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        live = this.startHttp(String(init?.method || (isReq ? input.method : "GET")).toUpperCase(), url, "fetch");
+        if (live && typeof Headers !== "undefined") {
+          const headers = new Headers(init?.headers ?? (isReq ? input.headers : void 0));
+          const add = headers.has("sentry-trace") ? null : this.headers(live, headers.get("baggage"));
+          if (add) {
+            for (const [k, v] of Object.entries(add)) if (k !== "traceparent" || !headers.has(k)) headers.set(k, v);
+            init = { ...init, headers };
+          }
+        }
+      } catch {
+      }
+      const p = orig.call(win, input, init);
+      if (live?.span) {
+        const l = live;
+        p.then(
+          (res) => this.endHttp(l, res.status, res.headers?.get?.("content-length")),
+          () => this.endHttp(l, 0)
+        );
+      }
+      return p;
+    };
+    win.fetch = patched;
+    this.cleanups.push(() => {
+      if (win.fetch === patched) win.fetch = orig;
+    });
+  }
+  instrumentXhr() {
+    const proto = typeof XMLHttpRequest !== "undefined" ? XMLHttpRequest.prototype : null;
+    if (!proto) return;
+    const { open, send, setRequestHeader } = proto;
+    const self = { startHttp: this.startHttp.bind(this), headers: this.headers.bind(this), endHttp: this.endHttp.bind(this) };
+    const meta = /* @__PURE__ */ new WeakMap();
+    const pOpen = function(method, url, ...rest) {
+      meta.set(this, { method: String(method).toUpperCase(), url: String(url), headers: {} });
+      return open.call(this, method, url, ...rest);
+    };
+    const pSetHeader = function(name, value) {
+      const m = meta.get(this);
+      if (m) m.headers[String(name).toLowerCase()] = String(value);
+      return setRequestHeader.call(this, name, value);
+    };
+    const pSend = function(body) {
+      try {
+        const m = meta.get(this);
+        const live = m ? self.startHttp(m.method, m.url, "xhr") : null;
+        if (live && m && !m.headers["sentry-trace"]) {
+          const existing = m.headers.baggage ?? null;
+          const add = self.headers(live, null);
+          if (add) {
+            setRequestHeader.call(this, "sentry-trace", add["sentry-trace"]);
+            if (!m.headers.traceparent) setRequestHeader.call(this, "traceparent", add.traceparent);
+            if (!existing?.includes("sentry-")) setRequestHeader.call(this, "baggage", add.baggage);
+          }
+        }
+        if (live?.span) this.addEventListener("loadend", () => self.endHttp(live, this.status, safeHeader(this, "content-length")), { once: true });
+      } catch {
+      }
+      return send.call(this, body);
+    };
+    proto.open = pOpen;
+    proto.setRequestHeader = pSetHeader;
+    proto.send = pSend;
+    this.cleanups.push(() => {
+      if (proto.open === pOpen) proto.open = open;
+      if (proto.setRequestHeader === pSetHeader) proto.setRequestHeader = setRequestHeader;
+      if (proto.send === pSend) proto.send = send;
+    });
+  }
+  // --- sending ----------------------------------------------------------------------------------
+  enqueue(e) {
+    this.out.push(e);
+    if (this.out.length > MAX_QUEUE) this.out.shift();
+    this.flushTimer ?? (this.flushTimer = setTimeout(() => this.flush(), this.o.flushMs ?? 1e3));
+  }
+  /** Sends queued transactions (`hide`: with `sendBeacon` / keepalive, the page is going away). */
+  flush(hide = false) {
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+    if (!this.out.length) return;
+    const allowed = this.o.allowed();
+    if (allowed === false) {
+      this.out = [];
+      return;
+    }
+    if (allowed === null) return;
+    const { api } = this.o;
+    if (!hide && !api.health.canSend()) {
+      this.flushTimer = setTimeout(() => this.flush(), api.health.waitMs());
+      return;
+    }
+    while (this.out.length) {
+      const batch = this.out.splice(0, BATCH);
+      const body = { sdk: { name: TRACES_SDK_NAME, version: this.o.sdkVersion }, transactions: batch };
+      if (hide && api.beacon("/traces", body)) continue;
+      api.post("/traces", body, { keepalive: hide }).then(
+        (res) => isServerFailure(res.status) && this.retry(batch),
+        () => this.retry(batch)
+      );
+    }
+  }
+  retry(batch) {
+    if (this.stopped) return;
+    this.out.unshift(...batch);
+    this.out.splice(MAX_QUEUE);
+    this.flushTimer ?? (this.flushTimer = setTimeout(() => this.flush(), Math.max(5e3, this.o.api.health.waitMs())));
+  }
+};
+function safeHeader(xhr, name) {
+  try {
+    return xhr.getResponseHeader(name);
+  } catch {
+    return null;
+  }
+}
+
+// src/bug-report.ts
+import { MAX_BUG_REPORT_LENGTH, MAX_BUG_REPORT_SCREENSHOT_BYTES } from "@guidelytech/shared/runtime";
+async function encodeScreenshot(s) {
+  if (!s) return null;
+  if (!(typeof Blob !== "undefined" && s instanceof Blob)) {
+    const encoded = s;
+    const data = encoded.data.replace(/^data:[^,]*,/, "");
+    if (data.length * 0.75 > MAX_BUG_REPORT_SCREENSHOT_BYTES) throw new Error("[Guidely] captureFeedback: screenshots can be up to 4 MB");
+    return { fileName: encoded.fileName || "screenshot.png", data };
+  }
+  if (s.size > MAX_BUG_REPORT_SCREENSHOT_BYTES) throw new Error("[Guidely] captureFeedback: screenshots can be up to 4 MB");
+  const dataUrl = await new Promise((resolve, reject) => {
+    const r = new FileReader();
+    r.onload = () => resolve(String(r.result));
+    r.onerror = () => reject(new Error("[Guidely] captureFeedback: the screenshot couldn't be read"));
+    r.readAsDataURL(s);
+  });
+  const name = s.name || (s.type === "image/jpeg" ? "screenshot.jpg" : "screenshot.png");
+  return { fileName: name, data: dataUrl.slice(dataUrl.indexOf(",") + 1) };
+}
+function bugReportBody(input, ctx, source, screenshot) {
+  const tags = {};
+  for (const [k, v] of Object.entries(input.tags ?? {}).slice(0, 20)) if (k && v !== void 0 && v !== null) tags[k.slice(0, 64)] = String(v).slice(0, 200);
+  const email = input.email?.trim();
+  const name = input.name?.trim();
+  const associated = input.associatedEventId ?? ctx.lastExceptionId;
+  return {
+    anonymousId: ctx.anonymousId,
+    userId: ctx.userId,
+    sessionId: ctx.sessionId,
+    message: String(input.message ?? "").trim().slice(0, MAX_BUG_REPORT_LENGTH),
+    ...email ? { email } : {},
+    ...name ? { name } : {},
+    ...associated ? { associatedEventId: associated } : {},
+    ...ctx.url ? { url: ctx.url } : {},
+    ...ctx.appVersion ? { appVersion: ctx.appVersion } : {},
+    source,
+    ...Object.keys(tags).length ? { tags } : {},
+    sdk: ctx.sdk,
+    ...screenshot ? { screenshot } : {}
+  };
+}
+async function sendBugReport(api, body) {
+  const res = await api.request("POST", "/bug-reports", { body, timeoutMs: body.screenshot ? 6e4 : 2e4 });
+  if (res.ok && res.data && "id" in res.data) return res.data;
+  if (res.status === 429) throw new Error("You've sent several reports just now. Please try again later.");
+  const message = res.data && "error" in res.data ? res.data.error?.message : null;
+  throw new Error(res.status === 400 && message ? message : "Your report couldn't be sent. Please try again.");
+}
+
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.16.0";
+var SDK_VERSION = "0.17.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) {
+function settlesWithin(promise, ms2) {
   return new Promise((resolve) => {
-    const timer = setTimeout(() => resolve(false), ms);
+    const timer = setTimeout(() => resolve(false), ms2);
     const done = () => {
       clearTimeout(timer);
       resolve(true);
@@ -1440,8 +2263,8 @@ function nowIso() {
 function emptyState() {
   return { guides: {}, checklists: {}, surveysSubmitted: [], audienceIds: [] };
 }
-function newSession(now = Date.now()) {
-  return { id: `s_${randomId2(16)}`, startedAt: new Date(now).toISOString(), shownGuides: [], events: [], lastActivityAt: now };
+function newSession(now3 = Date.now()) {
+  return { id: `s_${randomId2(16)}`, startedAt: new Date(now3).toISOString(), shownGuides: [], events: [], lastActivityAt: now3 };
 }
 var GuidelyClient = class _GuidelyClient {
   constructor(options) {
@@ -1456,6 +2279,8 @@ var GuidelyClient = class _GuidelyClient {
     /** Agent Analytics turns (agentConversation), in their own outbox. */
     __publicField(this, "agentTurns");
     __publicField(this, "config", null);
+    /** The `environment` option as passed (the resolved one is in `options.environment`). */
+    __publicField(this, "envOption");
     __publicField(this, "etag", null);
     __publicField(this, "anonymousId");
     __publicField(this, "user", null);
@@ -1497,6 +2322,11 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "exceptionThrottle", new ExceptionThrottle());
     /** Exceptions seen before the config was loaded (reported once it is known whether the server accepts them). */
     __publicField(this, "earlyExceptions", []);
+    /** The last exception this page reported, which bug reports link to by default. */
+    __publicField(this, "lastExceptionId", null);
+    __publicField(this, "bugReportDialog", null);
+    /** Tags, extra, contexts and breadcrumbs sent with every error (`setTag`, `addBreadcrumb`…). */
+    __publicField(this, "errorScope", new ErrorScope(() => this.options.errors));
     __publicField(this, "initialPageViewSent", false);
     __publicField(this, "pageViewUrl", null);
     __publicField(this, "pageLeft", false);
@@ -1508,6 +2338,8 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "locale", null);
     /** Language each shown guide was rendered in; added to its events as `locale`. */
     __publicField(this, "guideLocales", /* @__PURE__ */ new Map());
+    /** Performance tracing (`tracing` option + the project's `performance` setting); see tracing.ts. */
+    __publicField(this, "tracer");
     __publicField(this, "customListeners", /* @__PURE__ */ new Map());
     __publicField(this, "eventBus", {
       on: (name, cb) => {
@@ -1524,9 +2356,10 @@ var GuidelyClient = class _GuidelyClient {
     });
     if (!isBrowser()) throw new Error("[Guidely] createGuidely() must be called in the browser. Create the client inside useEffect / onMount, or use the framework adapters.");
     if (!options || !options.projectId) throw new Error("[Guidely] `projectId` (your environment public key, e.g. pk_dev_\u2026) is required.");
+    this.envOption = options.environment || void 0;
     this.options = {
       ...options,
-      environment: options.environment ?? (options.projectId.startsWith("pk_prod") ? "production" : options.projectId.startsWith("pk_stag") ? "staging" : "development"),
+      environment: options.environment || environmentFromKey(options.projectId),
       apiUrl: options.apiUrl ?? DEFAULT_API_URL,
       analytics: options.analytics ?? true,
       consent: options.consent ?? "granted",
@@ -1570,6 +2403,16 @@ var GuidelyClient = class _GuidelyClient {
     this.agentTurns = new AgentTurns({ api: this.api, store: this.store, storageKey: KEYS.agentOutbox(this.options.projectId), health: this.api.health, sdk: { name: SDK_NAME, version: SDK_VERSION } });
     if (options.user) this.user = { ...options.user };
     this.flags = this.createFlags(options.flags);
+    this.tracer = options.tracing === false ? null : startTracer({
+      ...typeof options.tracing === "object" ? options.tracing : {},
+      api: this.api,
+      publicKey: this.options.projectId,
+      apiUrl: this.options.apiUrl,
+      sdkVersion: SDK_VERSION,
+      pageHref: (href) => this.pageHref(href),
+      context: () => ({ anonymousId: this.anonymousId, sessionId: this.session.id, userId: this.user?.id || null, release: this.options.release || this.appVersion(), environment: this.environment, collectUrls: this.collectUrls() }),
+      allowed: () => this.consent === "pending" ? null : this.analyticsEnabled() && !this.editing()
+    });
   }
   createFlags(opts) {
     const base = { sdkKey: this.options.projectId, apiUrl: this.options.apiUrl, fetch: this.options.fetch, sdk: { name: SDK_NAME, version: SDK_VERSION } };
@@ -1624,7 +2467,7 @@ var GuidelyClient = class _GuidelyClient {
     try {
       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);
+      if (cached && cached.guides) this.useConfig(webOnly(cached));
       const before = this.config?.configVersion;
       const fresh = this.fetchConfig();
       if (!this.config) await fresh;
@@ -1653,12 +2496,22 @@ var GuidelyClient = class _GuidelyClient {
       this.resolveReady?.();
     }
   }
+  /** Environment guides and flags target: the `environment` option, else the one the loaded config names, else a guess from the key. */
+  get environment() {
+    return this.envOption ?? this.config?.environment ?? this.options.environment;
+  }
+  useConfig(config) {
+    const env = this.environment;
+    this.config = config;
+    if (this.environment !== env) this.syncFlagAttributes();
+    this.tracer?.configure(config.settings?.performance);
+  }
   async fetchConfig() {
     try {
       const res = await this.api.get("/config", { etag: this.etag, params: { platform: "web" } });
       if (res.status === 304) return true;
       if (res.ok && res.data && Array.isArray(res.data.guides)) {
-        this.config = webOnly(res.data);
+        this.useConfig(webOnly(res.data));
         this.etag = res.etag;
         writeJson(this.store, KEYS.config(this.options.projectId), res.data);
         if (res.etag) this.store.set(KEYS.etag(this.options.projectId), res.etag);
@@ -1711,9 +2564,9 @@ var GuidelyClient = class _GuidelyClient {
     };
     let lastScroll = 0;
     const onScroll = () => {
-      const now = Date.now();
-      if (now - lastScroll < 250) return;
-      lastScroll = now;
+      const now3 = Date.now();
+      if (now3 - lastScroll < 250) return;
+      lastScroll = now3;
       this.pageTracker.measureScroll();
       this.touchSession();
     };
@@ -1771,14 +2624,22 @@ var GuidelyClient = class _GuidelyClient {
   /** Uncaught errors + unhandled rejections; attached before the config loads so boot errors are kept. */
   wireErrorListeners() {
     const win = window;
-    const onError = (e) => this.captureGlobalException(errorEventToException(e));
-    const onRejection = (e) => this.captureGlobalException(rejectionToException(e));
+    const onError = (e) => this.captureGlobalException(errorEventToException(e), void 0, e.error);
+    const onRejection = (e) => this.captureGlobalException(rejectionToException(e), void 0, e.reason);
     win.addEventListener("error", onError);
     win.addEventListener("unhandledrejection", onRejection);
     this.cleanups.push(() => {
       win.removeEventListener("error", onError);
       win.removeEventListener("unhandledrejection", onRejection);
     });
+    const crumbs = this.options.errors?.breadcrumbs;
+    if (crumbs !== false) this.cleanups.push(instrumentBreadcrumbs((c, hint) => this.errorScope.addBreadcrumb(c, hint), { console: crumbs?.console, http: crumbs?.http, apiUrl: this.options.apiUrl }));
+  }
+  /** An automatic breadcrumb, unless the `errors.breadcrumbs` option turns its kind off. */
+  autoBreadcrumb(kind, crumb, hint) {
+    const o = this.options.errors?.breadcrumbs;
+    if (o === false || o && o[kind] === false) return;
+    this.errorScope.addBreadcrumb(crumb, hint === void 0 ? void 0 : { event: hint });
   }
   /** Re-fetches the published config and re-evaluates triggers. */
   async refresh() {
@@ -1826,6 +2687,7 @@ var GuidelyClient = class _GuidelyClient {
     this.queue.destroy();
     this.outbox.destroy();
     this.agentTurns.destroy();
+    this.tracer?.destroy();
     this.flags.destroy();
     this.emitter.clear();
     destroyHost();
@@ -1955,6 +2817,11 @@ var GuidelyClient = class _GuidelyClient {
   analyticsEnabled() {
     return this.options.analytics && this.consent === "granted" && (this.config?.settings?.analyticsEnabled ?? true);
   }
+  /** The host app's version (`appVersion` option), sent with every event and recording. */
+  appVersion() {
+    const v = this.options.appVersion;
+    return v === void 0 || v === null || String(v).trim() === "" ? void 0 : String(v).trim().slice(0, 200);
+  }
   collectUrls() {
     return this.config?.settings?.collectUrls ?? true;
   }
@@ -1970,12 +2837,14 @@ var GuidelyClient = class _GuidelyClient {
       accountId: this.user?.account?.id || null,
       sessionId: this.session.id,
       url: this.collectUrls() ? this.pageHref() : void 0,
+      ...this.appVersion() ? { appVersion: this.appVersion() } : {},
       ...extra
     };
     if (extra.properties) event.properties = sanitizeProperties(extra.properties);
     const locale = extra.guideId ? this.guideLocales.get(extra.guideId) : void 0;
     if (locale) event.properties = { ...event.properties ?? {}, locale };
     this.queue.enqueue(event);
+    if (name.startsWith("guide_") || name.startsWith("step_")) this.autoBreadcrumb("guides", { category: "guide", message: name, data: { guideId: event.guideId, ...event.stepIndex !== void 0 ? { stepIndex: event.stepIndex } : {} } });
     this.replay?.addCustomEvent("guidely", { name, customName: event.customName, guideId: event.guideId });
     this.emitter.emit("track", event);
     return event;
@@ -2029,6 +2898,7 @@ var GuidelyClient = class _GuidelyClient {
   handleNavigation(url, explicit = false) {
     if (this.destroyed) return;
     const changed = url !== this.lastUrl;
+    if (changed && this.lastUrl) this.autoBreadcrumb("navigation", { category: "navigation", data: this.collectUrls() ? { from: breadcrumbUrl(this.lastUrl), to: breadcrumbUrl(url) } : {} });
     this.lastUrl = url;
     if (changed) this.syncFlagAttributes();
     if (!explicit && changed) {
@@ -2057,6 +2927,7 @@ var GuidelyClient = class _GuidelyClient {
   handleDocumentClick(e) {
     const target = composedTarget(e);
     if (!target || typeof target.closest !== "function") return;
+    if (!isIgnoredElement(target)) this.autoBreadcrumb("clicks", { category: "ui.click", message: elementSelector(interactiveElement(target) ?? target) }, e);
     this.autocaptureClick(e, target);
     this.completeChecklistTasksBy("click", target);
     if (this.isReady) this.evaluate("click", { target });
@@ -2066,17 +2937,17 @@ var GuidelyClient = class _GuidelyClient {
   // ---------------------------------------------------------------------------
   /** Records activity; starts a new session after `sessionTimeoutMinutes` of inactivity or 24h. */
   touchSession() {
-    const now = Date.now();
+    const now3 = Date.now();
     const s = this.session;
     const timeout = Math.max(1, this.config?.settings?.sessionTimeoutMinutes ?? 30) * 6e4;
-    const last = s.lastActivityAt ?? now;
-    if (now - last > timeout || now - (Date.parse(s.startedAt) || now) > DAY_MS) return this.rotateSession(now);
-    if (now - (s.lastActivityAt ?? 0) < 1e3) return;
-    s.lastActivityAt = now;
+    const last = s.lastActivityAt ?? now3;
+    if (now3 - last > timeout || now3 - (Date.parse(s.startedAt) || now3) > DAY_MS) return this.rotateSession(now3);
+    if (now3 - (s.lastActivityAt ?? 0) < 1e3) return;
+    s.lastActivityAt = now3;
     this.persistSession();
   }
-  rotateSession(now) {
-    this.session = newSession(now);
+  rotateSession(now3) {
+    this.session = newSession(now3);
     this.persistSession();
     this.log("session rotated", this.session.id);
     if (this.replay?.activeSessionId) this.replay.stop();
@@ -2108,7 +2979,7 @@ var GuidelyClient = class _GuidelyClient {
     const device = detectDevice(navigator.userAgent, window.innerWidth);
     const props = { deviceType: device.type, browser: device.browser, os: device.os, screenWidth: window.screen?.width, viewportWidth: window.innerWidth };
     if (collect) {
-      props.path = pathOf2(url);
+      props.path = pathOf3(url);
       props.title = (document.title || "").slice(0, 200);
       const ref = !this.session.pageViews ? externalReferrer() : void 0;
       if (ref) props.referrer = ref;
@@ -2127,7 +2998,7 @@ var GuidelyClient = class _GuidelyClient {
     if (!this.pageLeft && this.autocaptureOn("pageLeave")) {
       const info = t.leave();
       const collect = this.collectUrls();
-      this.enqueue("page_leave", { url: collect ? info.url : void 0, properties: { ...collect ? { path: pathOf2(info.url) } : {}, durationMs: info.durationMs, scrollDepth: info.scrollDepth } });
+      this.enqueue("page_leave", { url: collect ? info.url : void 0, properties: { ...collect ? { path: pathOf3(info.url) } : {}, durationMs: info.durationMs, scrollDepth: info.scrollDepth } });
     }
     if (nextUrl !== null) {
       t.start(nextUrl);
@@ -2171,42 +3042,120 @@ var GuidelyClient = class _GuidelyClient {
     if (!batch || !this.captureAllowed()) return;
     const collect = this.collectUrls();
     const de = document.documentElement;
-    const properties = { path: collect ? pathOf2(batch.url) : void 0, viewportWidth: window.innerWidth, viewportHeight: window.innerHeight, pageHeight: Math.max(de.scrollHeight, document.body?.scrollHeight || 0), points: batch.points };
+    const properties = { path: collect ? pathOf3(batch.url) : void 0, viewportWidth: window.innerWidth, viewportHeight: window.innerHeight, pageHeight: Math.max(de.scrollHeight, document.body?.scrollHeight || 0), points: batch.points };
     if (!collect) delete properties.path;
     this.enqueue("heatmap", { url: collect ? batch.url : void 0, properties });
   }
-  captureGlobalException(props) {
+  captureGlobalException(props, detail, error) {
     if (!props || isGuidelyException(props) || this.options.captureErrors === false) return;
+    const d = detail ?? this.errorDetail(error, props, props.source === "unhandledrejection" ? "onunhandledrejection" : "onerror", {}, "error");
     if (!this.config) {
-      if (this.earlyExceptions.length < 10) this.earlyExceptions.push([props, void 0]);
+      if (this.earlyExceptions.length < 10) this.earlyExceptions.push([props, void 0, d]);
       return;
     }
-    this.sendException(props);
+    this.sendException(props, void 0, d);
   }
   /**
    * Reports a caught error as an `exception` event (`source: "manual"`, `handled: true`), grouped
-   * into an issue on the Errors page. Extra properties are attached to the occurrence. Needs the
-   * project's error tracking on (plus analytics + consent); `captureErrors: false` does not stop it.
+   * into an issue on the Errors page. The second argument takes Sentry's capture context (`tags`,
+   * `extra`, `level`, `fingerprint`, `contexts`, `user`); any other key is attached to the occurrence
+   * as a property. Needs the project's error tracking on (plus analytics + consent);
+   * `captureErrors: false` does not stop it. Returns the event id (empty when nothing is sent).
    */
-  captureException(error, properties) {
-    if (this.destroyed) return;
-    const props = exceptionFromError(error, "manual", true);
+  captureException(error, hint) {
+    if (this.destroyed) return "";
+    const { ctx, properties } = splitHint(hint);
+    const props = exceptionFromError(error, "manual", ctx.mechanism?.handled ?? true);
+    return this.captureWith(props, properties, this.errorDetail(error, props, ctx.mechanism?.type ?? "generic", ctx, ctx.level ?? "error"));
+  }
+  /** Reports a message (default level `info`) as its own issue, grouped by the message. */
+  captureMessage(message, level = "info", hint) {
+    if (this.destroyed) return "";
+    const props = { type: "Message", message: String(message).slice(0, 1e3), frames: [], source: "message", handled: true };
+    return this.captureWith(props, {}, this.errorDetail(void 0, props, "message", hint ?? {}, hint?.level ?? level));
+  }
+  captureWith(props, properties, detail) {
     if (!this.config) {
-      if (this.earlyExceptions.length < 10) this.earlyExceptions.push([props, properties]);
-      return;
+      if (this.earlyExceptions.length < 10) this.earlyExceptions.push([props, properties, detail]);
+      return "";
     }
-    this.sendException(props, properties);
+    return this.sendException(props, properties, detail);
   }
-  sendException(props, extra) {
-    if (!this.config?.settings?.errorTracking?.enabled || !this.captureAllowed() || !this.exceptionThrottle.allow(props)) return;
+  /** The `detail` of an error: scope, breadcrumbs, browser contexts and the `cause` chain. */
+  errorDetail(error, props, mechanism, ctx, level) {
+    const device = detectDevice(navigator.userAgent, window.innerWidth);
+    return buildDetail({ error, props, mechanism, scope: this.errorScope, ctx, level, contexts: browserContexts(navigator.userAgent, device) });
+  }
+  /** Adds a breadcrumb (sent with the next errors; the last 100 are kept). */
+  addBreadcrumb(crumb) {
+    if (!this.destroyed) this.errorScope.addBreadcrumb(crumb);
+  }
+  /** Tags every later error (searchable on the issue page). */
+  setTag(key, value) {
+    if (value === null || value === void 0) delete this.errorScope.tags[key];
+    else this.errorScope.tags[key] = String(value);
+  }
+  setTags(tags) {
+    for (const [k, v] of Object.entries(tags)) this.setTag(k, v);
+  }
+  /** Arbitrary data attached to every later error. */
+  setExtra(key, value) {
+    if (value === void 0) delete this.errorScope.extra[key];
+    else this.errorScope.extra[key] = value;
+  }
+  setExtras(extras) {
+    for (const [k, v] of Object.entries(extras)) this.setExtra(k, v);
+  }
+  /** A named context (`setContext("cart", { items: 3 })`) on every later error; null removes it. */
+  setContext(name, context) {
+    if (context) this.errorScope.contexts[name] = context;
+    else delete this.errorScope.contexts[name];
+  }
+  /**
+   * Sentry's `setUser`: identifies the user by `id` (like `identify`) and keeps `email` / `username`
+   * on their errors. `null` forgets the user (`reset()`).
+   */
+  setUser(user) {
+    if (!user) {
+      this.errorScope.user = {};
+      return this.reset();
+    }
+    const { id, email, username, ...traits } = user;
+    this.errorScope.user = { ...email ? { email: String(email) } : {}, ...username ? { username: String(username) } : {} };
+    if (id !== void 0 && id !== null && String(id)) void this.identify(String(id), { ...traits, ...email ? { email } : {}, ...username ? { username } : {} });
+  }
+  sendException(props, extra, detail) {
+    if (!this.config?.settings?.errorTracking?.enabled || !this.captureAllowed()) return "";
+    const o = this.options.errors;
+    const file = props.frames.find((f) => f.file)?.file;
+    if (o && errorFilterDrops({ type: props.type, message: props.message, file }, o)) return "";
+    if (o?.sampleRate !== void 0 && o.sampleRate < 1 && Math.random() >= Math.max(0, o.sampleRate)) return "";
+    if (!this.exceptionThrottle.allow(props)) return "";
     const count = this.session.exceptions ?? 0;
-    if (count >= MAX_SESSION_EXCEPTIONS) return;
-    const properties = { ...props };
+    if (count >= MAX_SESSION_EXCEPTIONS) return "";
+    const mechanism = detail?.exception?.values.at(-1)?.mechanism?.type;
+    let properties = { ...props, level: detail?.level ?? "error", platform: "javascript", ...mechanism ? { mechanism } : {} };
     if (this.options.release) properties.release = String(this.options.release).slice(0, 100);
+    const trace = this.tracer?.traceContext();
+    if (trace) Object.assign(properties, { traceId: trace.traceId, spanId: trace.spanId });
     for (const [k, v] of Object.entries(extra ?? {})) if (!(k in properties)) properties[k] = v;
-    this.enqueue("exception", { properties });
+    let d = detail;
+    if (o?.beforeSend) {
+      try {
+        const out = o.beforeSend({ properties, detail: d ?? {} });
+        if (!out) return "";
+        properties = out.properties;
+        d = out.detail;
+      } catch (err) {
+        this.reportError(err);
+      }
+    }
+    const event = this.enqueue("exception", { properties, ...d ? { detail: d } : {} });
+    if (!event) return "";
+    this.lastExceptionId = event.eventId;
     this.session.exceptions = count + 1;
     this.persistSession();
+    return event.eventId;
   }
   maskSelector() {
     return validSelectors([...DEFAULT_MASK_SELECTORS, ...this.config?.settings?.maskSelectors || [], ...this.options.maskSelectors || []]).join(",");
@@ -2240,9 +3189,9 @@ var GuidelyClient = class _GuidelyClient {
       this.trackPageView(this.pageHref());
     }
     if (this.config) {
-      for (const [props, extra] of this.earlyExceptions.splice(0)) {
-        if (props.handled) this.sendException(props, extra);
-        else this.captureGlobalException(props);
+      for (const [props, extra, detail] of this.earlyExceptions.splice(0)) {
+        if (props.handled) this.sendException(props, extra, detail);
+        else this.captureGlobalException(props, detail);
       }
     }
     this.syncReplay();
@@ -2275,7 +3224,8 @@ var GuidelyClient = class _GuidelyClient {
               url: this.collectUrls() ? this.pageHref() : void 0,
               device: { type: device.type, browser: device.browser, os: device.os },
               viewport: { width: window.innerWidth, height: window.innerHeight },
-              sdk: { name: SDK_NAME, version: SDK_VERSION }
+              sdk: { name: SDK_NAME, version: SDK_VERSION },
+              ...this.appVersion() ? { appVersion: this.appVersion() } : {}
             };
           },
           onDisabled: (sessionId) => {
@@ -2349,7 +3299,7 @@ var GuidelyClient = class _GuidelyClient {
       seenGuides: keysOf(Object.keys(guides).filter((id) => (guides[id]?.impressions ?? 0) > 0)),
       completedChecklists: keysOf(completedChecklists),
       audienceIds: this.state.audienceIds,
-      environment: this.options.environment,
+      environment: this.environment,
       platform: "web",
       ...this.options.appVersion ? { appVersion: this.options.appVersion } : {}
     });
@@ -2512,17 +3462,17 @@ var GuidelyClient = class _GuidelyClient {
         this.evaluate("visible", { guideId: guide.id });
       };
       if (typeof IntersectionObserver === "undefined") return fire();
-      io = new IntersectionObserver((entries) => {
-        if (entries.some((e) => e.isIntersecting)) fire();
+      io = new IntersectionObserver((entries2) => {
+        if (entries2.some((e) => e.isIntersecting)) fire();
       });
       io.observe(el);
     }).catch(() => stop());
   }
-  setTimer(fn, ms) {
+  setTimer(fn, ms2) {
     const t = setTimeout(() => {
       this.timers.delete(t);
       if (!this.destroyed) fn();
-    }, ms);
+    }, ms2);
     this.timers.add(t);
   }
   /** Decides whether a guide can show now, otherwise queues it. */
@@ -3127,6 +4077,49 @@ var GuidelyClient = class _GuidelyClient {
     if (!this.config?.messenger?.enabled || !this.config.messenger.ideas) return;
     void this.loadMessenger().then((m) => m?.openIdeas(requestId));
   }
+  /**
+   * Sends a bug report to Monitor → User feedback (Sentry's `captureFeedback`). It is linked to the visitor,
+   * this session's recording and, unless `associatedEventId` says otherwise, the last error this page
+   * reported. Resolves with the report's id; rejects when it can't be sent.
+   */
+  async captureFeedback(input, source = "api") {
+    if (this.destroyed) throw new Error("[Guidely] captureFeedback: the SDK was destroyed");
+    if (!input || !String(input.message ?? "").trim()) throw new Error("[Guidely] captureFeedback: message is required");
+    const screenshot = await encodeScreenshot(input.screenshot);
+    if (this.lastExceptionId) await this.queue.flush().catch(() => {
+    });
+    const body = bugReportBody(
+      input,
+      { anonymousId: this.anonymousId, userId: this.user?.id || null, sessionId: this.session.id, url: this.collectUrls() ? this.pageHref() : void 0, appVersion: this.appVersion(), lastExceptionId: this.lastExceptionId, sdk: { name: SDK_NAME, version: SDK_VERSION } },
+      source,
+      screenshot
+    );
+    return sendBugReport(this.api, body);
+  }
+  /** Opens the "Report a bug" dialog (message, name, email, a screenshot), which sends with captureFeedback. */
+  showBugReport(options = {}) {
+    if (this.destroyed || typeof document === "undefined" || this.bugReportDialog) return;
+    void import("@guidelytech/guide-runtime/bug-report").then(({ renderBugReport }) => {
+      if (this.destroyed || this.bugReportDialog) return;
+      const scope = createScope(this.theme());
+      const traits = this.user?.traits ?? {};
+      const str = (v) => typeof v === "string" ? v : void 0;
+      this.bugReportDialog = renderBugReport({
+        scope: scope.el,
+        title: options.title,
+        message: options.message,
+        name: options.name ?? str(traits.name),
+        email: options.email ?? str(traits.email),
+        onSubmit: async (i) => {
+          await this.captureFeedback({ message: i.message, name: i.name || null, email: i.email || null, screenshot: i.screenshot }, "widget");
+        },
+        onClose: () => {
+          this.bugReportDialog = null;
+          scope.destroy();
+        }
+      });
+    }).catch((err) => this.reportError(err));
+  }
   /** Opens a new messenger conversation, optionally pre-filling the message. */
   showNewMessage(text) {
     if (!this.config?.messenger?.enabled) return;
@@ -3157,12 +4150,12 @@ var GuidelyClient = class _GuidelyClient {
     const account = this.user?.account;
     return {
       url: this.pageHref(),
-      path: pathOf2(this.pageHref()),
+      path: pathOf3(this.pageHref()),
       deviceType: device.type,
       browser: device.browser,
       os: device.os,
       locale: navigator.language || void 0,
-      environment: this.options.environment,
+      environment: this.environment,
       platform: "web",
       ...this.options.appVersion ? { appVersion: this.options.appVersion } : {},
       ...this.user?.traits ?? {},
@@ -3339,7 +4332,7 @@ var current2 = null;
 function webOnly(config) {
   return config.guides.every((g) => supportsPlatform(g.config, "web")) ? config : { ...config, guides: config.guides.filter((g) => supportsPlatform(g.config, "web")) };
 }
-function pathOf2(url) {
+function pathOf3(url) {
   try {
     return new URL(url, "http://localhost").pathname;
   } catch {
@@ -3390,6 +4383,7 @@ export {
   createStorage,
   index_default as default,
   detectDevice,
+  environmentFromKey,
   isAppUrl,
   isExclusiveGuide,
   isFrequencyEligible,