@guidelytech/sdk-core 0.10.0 → 0.11.0

package/dist/index.js

@@ -3,11 +3,14 @@ import {
   EventQueue,
   Outbox,
   areMutuallyExclusive,
+  countsTowardThrottle,
   dismissedAfterMerge,
   isExclusiveGuide,
   isFrequencyEligible,
-  isWithinSchedule
-} from "./chunk-GDJB466J.js";
+  isThrottleEligible,
+  isWithinSchedule,
+  pruneLaunches
+} from "./chunk-ZAF2KRJA.js";
 import {
   Api,
   KEYS,
@@ -16,12 +19,12 @@ import {
   postWithRetry,
   readJson,
   writeJson
-} from "./chunk-C4WWSF67.js";
+} from "./chunk-JUSM7J5N.js";
 
 // src/client.ts
-import { evaluateRules, randomId, rolloutBucket, sanitizeProperties, supportsPlatform } from "@guidelytech/shared/runtime";
+import { evaluateRules, localizeGuide, localizeResourceCenter, normalizeLocale, randomId as randomId2, rolloutBucket, sanitizeProperties, supportsPlatform, visibleAnnouncements, visitorLocales } from "@guidelytech/shared/runtime";
 import {
-  closestComposed as closestComposed3,
+  closestComposed as closestComposed4,
   composedTarget,
   destroyHost,
   isChecklistComplete,
@@ -35,8 +38,82 @@ import {
 import { createScope } from "@guidelytech/guide-runtime";
 import { createFlagsClient } from "@guidelytech/flags";
 
+// src/agent-turns.ts
+import { AGENT_TOOL_CALLS_PER_TURN, AGENT_TURN_MAX_TEXT, AGENT_TURNS_PER_BATCH, randomId } from "@guidelytech/shared/runtime";
+var PENDING_MAX = 500;
+function toolCalls(calls) {
+  if (!Array.isArray(calls)) return void 0;
+  return calls.filter((c) => !!c && typeof c.name === "string" && !!c.name).slice(0, AGENT_TOOL_CALLS_PER_TURN).map((c) => ({
+    name: c.name.slice(0, 100),
+    ...c.status === "ok" || c.status === "error" ? { status: c.status } : {},
+    ...typeof c.latencyMs === "number" && Number.isFinite(c.latencyMs) && c.latencyMs >= 0 ? { latencyMs: Math.round(c.latencyMs) } : {}
+  }));
+}
+function prepareAgentTurn(turn, identity, redact, onError) {
+  if (!turn || typeof turn !== "object" || !turn.conversationId || !turn.agentId || !turn.role) return null;
+  let out = {
+    ...turn,
+    type: "agent.conversation",
+    turnId: turn.turnId || `t_${randomId(20)}`,
+    occurredAt: turn.occurredAt || (/* @__PURE__ */ new Date()).toISOString(),
+    anonymousId: turn.anonymousId ?? identity.anonymousId,
+    userId: turn.userId !== void 0 ? turn.userId : identity.userId,
+    accountId: turn.accountId !== void 0 ? turn.accountId : identity.accountId,
+    sessionId: turn.sessionId ?? identity.sessionId
+  };
+  if (redact) {
+    try {
+      const r = redact({ ...out, toolCalls: out.toolCalls ? out.toolCalls.map((c) => ({ ...c })) : void 0, metadata: out.metadata ? { ...out.metadata } : void 0 });
+      if (!r) return null;
+      out = { ...r, type: "agent.conversation", conversationId: out.conversationId, agentId: out.agentId, turnId: out.turnId, role: out.role };
+    } catch (err) {
+      onError?.(err);
+      return null;
+    }
+  }
+  if (typeof out.text === "string" && out.text.length > AGENT_TURN_MAX_TEXT) out.text = out.text.slice(0, AGENT_TURN_MAX_TEXT);
+  if (out.text !== void 0 && typeof out.text !== "string") out.text = String(out.text);
+  const calls = toolCalls(out.toolCalls);
+  if (calls) out.toolCalls = calls;
+  else delete out.toolCalls;
+  return out;
+}
+var AgentTurns = class {
+  constructor(opts) {
+    __publicField(this, "opts", opts);
+    __publicField(this, "outbox");
+    __publicField(this, "pending", []);
+    this.outbox = new Outbox({ api: opts.api, store: opts.store, storageKey: opts.storageKey, health: opts.health, maxItems: 20, maxAgeMs: 24 * 60 * 60 * 1e3 });
+  }
+  get queued() {
+    return this.outbox.size + this.pending.length;
+  }
+  /** Queues turns to send now, or (`hold`) until consent is granted. */
+  add(turns, hold = false) {
+    if (!turns.length) return;
+    if (hold) {
+      this.pending.push(...turns);
+      if (this.pending.length > PENDING_MAX) this.pending.splice(0, this.pending.length - PENDING_MAX);
+      return;
+    }
+    for (let i = 0; i < turns.length; i += AGENT_TURNS_PER_BATCH) {
+      const batch = turns.slice(i, i + AGENT_TURNS_PER_BATCH);
+      this.outbox.add(`agent:${batch[0].turnId}`, "/agent-events", { turns: batch, sdk: this.opts.sdk });
+    }
+  }
+  /** Consent changed: granted sends what was held, anything else drops it. */
+  consentChanged(granted) {
+    const held = this.pending.splice(0);
+    if (granted) this.add(held);
+  }
+  destroy() {
+    this.pending = [];
+    this.outbox.destroy();
+  }
+};
+
 // src/authoring.ts
-import { closestComposed, highlightSelectors, previewStep, runGuide, startAuthoring } from "@guidelytech/guide-runtime";
+import { closestComposed as closestComposed3, highlightSelectors, previewStep, runGuide, startAuthoring } from "@guidelytech/guide-runtime";
 
 // src/snapshot.ts
 var MAX_SNAPSHOT_BYTES = 6 * 1024 * 1024;
@@ -114,6 +191,276 @@ ${clone.outerHTML}`;
   return { html, url: win.location.href, title: doc.title, width: win.innerWidth, height: win.innerHeight, capturedAt: (/* @__PURE__ */ new Date()).toISOString() };
 }
 
+// src/tagging.ts
+import { NOISY_DATA_ATTR as NOISY_DATA_ATTR2, SNAPSHOT_LIMITS, TAG_PROPERTY_LIMITS, featureRuleMatchesClick, pageRuleMatches, pageRulesMatch } from "@guidelytech/shared/runtime";
+import { closestComposed as closestComposed2, isStableClass, isStableId as isStableId2, querySelectorStrategy } from "@guidelytech/guide-runtime";
+
+// src/autocapture.ts
+import { closestComposed, isGuidelyElement, isStableId, SHADOW_SEPARATOR, shadowHostChain } from "@guidelytech/guide-runtime";
+var INTERACTIVE_SELECTOR = "a,button,input[type=button],input[type=submit],input[type=reset],input[type=checkbox],input[type=radio],select,summary,label,[role=button],[role=link],[role=tab],[role=menuitem],[role=checkbox],[role=switch],[role=option],[onclick],[data-guidely-track]";
+var DEFAULT_MASK_SELECTORS = ["[data-guidely-mask]", ".guidely-mask"];
+var PREFERRED_ATTRS = ["data-testid", "data-test-id", "data-test", "data-cy", "data-qa", "data-guidely-track", "data-tour"];
+var NOISY_DATA_ATTR = /^data-(state|v-|react|radix|headlessui|svelte|orientation|highlighted|focus|key|index|side|align|disabled|selected|active|open|guidely-(mask|ignore|block))/i;
+function validSelectors(list) {
+  const out = [];
+  const probe = typeof document !== "undefined" ? document.createDocumentFragment() : null;
+  for (const raw of list) {
+    const s = (raw || "").trim();
+    if (!s || out.includes(s)) continue;
+    try {
+      probe?.querySelector(s);
+      out.push(s);
+    } catch {
+    }
+  }
+  return out;
+}
+function isIgnoredElement(el) {
+  return isGuidelyElement(el) || !!closestComposed(el, "[data-guidely-ignore]");
+}
+function interactiveElement(target) {
+  try {
+    return closestComposed(target, INTERACTIVE_SELECTOR);
+  } catch {
+    return null;
+  }
+}
+function esc(value) {
+  const g = globalThis;
+  return g.CSS?.escape ? g.CSS.escape(value) : value.replace(/[^\w-]/g, (c) => `\\${c}`);
+}
+var attr = (tag, name, value) => value ? `${tag}[${name}="${value.replace(/["\\]/g, "\\$&")}"]` : `${tag}[${name}]`;
+function elementSelector(el) {
+  const own = ownSelector(el);
+  const chain = shadowHostChain(el);
+  return (chain ? chain + SHADOW_SEPARATOR + own : own).slice(0, 300);
+}
+function ownSelector(el) {
+  const tag = el.tagName.toLowerCase();
+  if (el.id && isStableId(el.id)) return `#${esc(el.id)}`;
+  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);
+  }
+  const label = el.getAttribute("aria-label");
+  if (label && label.length <= 80) return attr(tag, "aria-label", label);
+  const parts = [];
+  let cur = el;
+  while (cur && parts.length < 4) {
+    const t = cur.tagName.toLowerCase();
+    if (t === "html" || t === "body") break;
+    if (cur !== el && cur.id && isStableId(cur.id)) {
+      parts.unshift(`#${esc(cur.id)}`);
+      break;
+    }
+    const parent = cur.parentElement;
+    const node = cur;
+    const same = parent ? Array.from(parent.children).filter((c) => c.tagName === node.tagName) : [];
+    parts.unshift(same.length > 1 ? `${t}:nth-of-type(${same.indexOf(node) + 1})` : t);
+    cur = parent;
+  }
+  return parts.join(" > ") || tag;
+}
+function matches(el, selector, deep) {
+  if (!selector) return false;
+  try {
+    return !!closestComposed(el, selector) || deep && !!el.querySelector(selector);
+  } catch {
+    return false;
+  }
+}
+function elementText(el, mask, maskAll) {
+  if (maskAll || matches(el, mask, true)) return void 0;
+  const tag = el.tagName.toLowerCase();
+  let text = "";
+  if (tag === "input") {
+    if (!/^(button|submit|reset)$/i.test(el.type || "")) return void 0;
+    text = el.value;
+  } else if (tag === "select" || tag === "textarea") return void 0;
+  else text = el.innerText ?? el.textContent ?? "";
+  text = (text || el.getAttribute("aria-label") || el.getAttribute("title") || "").replace(/\s+/g, " ").trim();
+  return text ? text.slice(0, 100) : void 0;
+}
+function linkHref(el) {
+  const a = closestComposed(el, "a[href]");
+  if (!a) return void 0;
+  try {
+    const u = new URL(a.getAttribute("href") || "", location.href);
+    if (!/^https?:$/.test(u.protocol)) return void 0;
+    return u.origin === location.origin ? u.pathname : u.origin;
+  } catch {
+    return void 0;
+  }
+}
+function describeClick(el, e, opts) {
+  const props = { tag: el.tagName.toLowerCase(), selector: elementSelector(el), x: Math.round(e.pageX ?? 0) || 0, y: Math.round(e.pageY ?? 0) || 0 };
+  const text = elementText(el, opts.mask, opts.maskAll);
+  if (text) props.text = text;
+  const href = opts.collectUrls ? linkHref(el) : void 0;
+  if (href) props.href = href;
+  return props;
+}
+var RageClickDetector = class {
+  constructor(threshold = 3, windowMs = 1e3, radius = 30) {
+    __publicField(this, "threshold", threshold);
+    __publicField(this, "windowMs", windowMs);
+    __publicField(this, "radius", radius);
+    __publicField(this, "clicks", []);
+    __publicField(this, "fired", false);
+  }
+  /** Clicks in the current burst once it has fired (rage), otherwise 0. */
+  get burst() {
+    return this.fired ? this.clicks.length : 0;
+  }
+  /** Records a click; returns the click count when it completes a burst, otherwise 0. */
+  add(x, y, t) {
+    const first = this.clicks[0];
+    const last = this.clicks[this.clicks.length - 1];
+    if (!first || !last || t - last.t > this.windowMs || Math.hypot(x - first.x, y - first.y) > this.radius) {
+      this.clicks = [];
+      this.fired = false;
+    }
+    this.clicks = this.clicks.filter((c) => t - c.t <= this.windowMs);
+    this.clicks.push({ x, y, t });
+    if (this.fired || this.clicks.length < this.threshold) return 0;
+    this.fired = true;
+    return this.clicks.length;
+  }
+};
+
+// src/tagging.ts
+var TEXT_ATTRS = /* @__PURE__ */ new Set(["aria-label", "title", "alt"]);
+var SAFE_ATTRS = ["role", "name", "type", "aria-label", "title", "alt", "for"];
+var STATE_CLASS = /^(is-|has-)?(active|hover|hovered|focus|focused|focus-visible|selected|open|opened|closed|disabled|visible|hidden|show|shown|collapsed|expanded|checked|pressed|loading|current)$/i;
+function nthOfType(el) {
+  const parent = el.parentElement;
+  if (!parent) return void 0;
+  let n = 0;
+  for (const c of Array.from(parent.children)) {
+    if (c.tagName === el.tagName) n++;
+    if (c === el) return n;
+  }
+  return void 0;
+}
+function nodeOf(el, masked, featureAttribute) {
+  const node = { t: el.tagName.toLowerCase().slice(0, SNAPSHOT_LIMITS.tag) };
+  if (el.id && isStableId2(el.id) && el.id.length <= SNAPSHOT_LIMITS.id) node.id = el.id;
+  const classes = Array.from(el.classList).filter((c) => isStableClass(c) && !STATE_CLASS.test(c) && c.length <= SNAPSHOT_LIMITS.className);
+  if (classes.length) node.c = classes.slice(0, SNAPSHOT_LIMITS.classes);
+  const a = {};
+  const put = (name, value) => {
+    if (value === null || Object.keys(a).length >= SNAPSHOT_LIMITS.attrs || name in a) return;
+    if (masked && TEXT_ATTRS.has(name)) return;
+    a[name] = value.slice(0, SNAPSHOT_LIMITS.attrValue);
+  };
+  if (featureAttribute && el.hasAttribute(featureAttribute)) put(featureAttribute, el.getAttribute(featureAttribute));
+  for (const attr2 of Array.from(el.attributes)) {
+    if (attr2.name.startsWith("data-") && !NOISY_DATA_ATTR2.test(attr2.name) && attr2.value.length <= SNAPSHOT_LIMITS.attrValue) put(attr2.name, attr2.value);
+  }
+  for (const name of SAFE_ATTRS) if (el.hasAttribute(name)) put(name, el.getAttribute(name));
+  if (Object.keys(a).length) node.a = a;
+  const n = nthOfType(el);
+  if (n) node.n = n;
+  return node;
+}
+function elementSnapshot(el, opts) {
+  const masked = opts.maskAll || isMasked(el, opts.mask);
+  const snap = nodeOf(el, masked, opts.featureAttribute);
+  const p = [];
+  for (let cur = el.parentElement; cur && p.length < SNAPSHOT_LIMITS.ancestors; cur = cur.parentElement) {
+    if (cur.tagName === "BODY" || cur.tagName === "HTML") break;
+    p.push(nodeOf(cur, masked, opts.featureAttribute));
+  }
+  if (p.length) snap.p = p;
+  const h = [];
+  let root = el.getRootNode?.();
+  while (root && root.nodeType === 11 && root.host && h.length < SNAPSHOT_LIMITS.hosts) {
+    h.push(nodeOf(root.host, masked, opts.featureAttribute));
+    root = root.host.getRootNode?.();
+  }
+  if (h.length) snap.h = h;
+  return snap;
+}
+function isMasked(el, mask) {
+  if (!mask) return false;
+  try {
+    return !!closestComposed2(el, mask);
+  } catch {
+    return false;
+  }
+}
+function featureAttributeOf(target, attribute) {
+  if (!attribute) return null;
+  try {
+    const el = closestComposed2(target, `[${attribute}]`);
+    const value = el?.getAttribute(attribute)?.replace(/\s+/g, " ").trim();
+    return el && value ? { el, value: value.slice(0, 100) } : null;
+  } catch {
+    return null;
+  }
+}
+function readProperty(def, base, opts) {
+  let el = base;
+  if (def.selector) {
+    try {
+      el = querySelectorStrategy({ kind: "css", value: def.selector }, document)[0] ?? null;
+    } catch {
+      el = null;
+    }
+  }
+  if (!el) return void 0;
+  if (def.source === "attribute") {
+    const name = (def.attribute ?? "").toLowerCase();
+    if (!name || name === "value" || name.startsWith("on")) return void 0;
+    if (opts.maskAll || isMasked(el, opts.mask)) return void 0;
+    const v = el.getAttribute(name);
+    return v ? v.replace(/\s+/g, " ").trim().slice(0, TAG_PROPERTY_LIMITS.value) || void 0 : void 0;
+  }
+  return elementText(el, opts.mask, opts.maskAll);
+}
+function clickPropertyValues(config, el, click, opts) {
+  if (!config?.properties.length) return void 0;
+  const out = {};
+  const css = (selector) => {
+    try {
+      return !!closestComposed2(el, selector);
+    } catch {
+      return false;
+    }
+  };
+  const here = { url: location.href, path: location.pathname, title: document.title };
+  for (const tag of config.properties) {
+    if (tag.kind !== "feature" || !tag.featureRules) continue;
+    const rules = tag.featureRules;
+    const matches2 = (r) => featureRuleMatchesClick(r, click, css) && (!r.page?.pattern || pageRuleMatches({ type: "url", value: r.page.pattern }, here));
+    if (!rules.some((r) => !r.exclude && matches2(r)) || rules.some((r) => r.exclude && matches2(r))) continue;
+    for (const def of tag.properties) {
+      const v = readProperty(def, el, opts);
+      if (v) out[def.id] = v;
+    }
+  }
+  return Object.keys(out).length ? out : void 0;
+}
+function pagePropertyValues(config, url, opts) {
+  if (!config?.properties.length) return void 0;
+  const out = {};
+  let path = "/";
+  try {
+    path = new URL(url, location.href).pathname;
+  } catch {
+  }
+  const ctx = { url, path, title: document.title };
+  for (const tag of config.properties) {
+    if (tag.kind !== "page" || !tag.pageRules || !pageRulesMatch(tag.pageRules, ctx)) continue;
+    for (const def of tag.properties) {
+      if (!def.selector) continue;
+      const v = readProperty(def, null, opts);
+      if (v) out[def.id] = v;
+    }
+  }
+  return Object.keys(out).length ? out : void 0;
+}
+
 // src/authoring.ts
 async function loadSchemas() {
   const m = await import("@guidelytech/shared");
@@ -184,6 +531,8 @@ var AuthoringBridge = class {
       this.opts.onActive(true);
       this.session = startAuthoring({
         dashboardOrigin: this.info.dashboardOrigin,
+        // Tag mode (Pages & Features): picks become feature rules; the page itself is tagged from the dashboard.
+        message: this.info.purpose === "tag" ? "Guidely tagging \u2014 click an element to tag it as a feature \xB7 tag the page from the dashboard \xB7 Esc to finish" : void 0,
         onPick: (pick) => this.sendPick(pick),
         onExit: () => this.stop()
       });
@@ -200,7 +549,7 @@ var AuthoringBridge = class {
   masked(el) {
     return this.opts.maskSelectors.some((sel) => {
       try {
-        return !!closestComposed(el, sel);
+        return !!closestComposed3(el, sel);
       } catch {
         return false;
       }
@@ -211,6 +560,7 @@ var AuthoringBridge = class {
     const { element, ...rest } = raw;
     const pick = this.masked(element) ? { ...rest, textSnapshot: "", selectors: rest.selectors.filter((s) => s.kind !== "text") } : rest;
     pick.url = window.location.href;
+    if (this.info.purpose === "tag") pick.elementSnapshot = elementSnapshot(element, { mask: this.opts.maskSelectors.join(","), maskAll: false, featureAttribute: null });
     this.post({ type: "guidely:pick", sessionId: this.info.id, pick });
     void this.opts.api.post("/authoring/session/picks", pick, { params: { token: this.token } }).catch((err) => this.opts.onError(err));
   }
@@ -380,139 +730,6 @@ function takeCaptureToken(sessionStore) {
 // src/load-capture.ts
 var loadCapture = async () => (await import("./capture.js")).capture;
 
-// src/autocapture.ts
-import { closestComposed as closestComposed2, isGuidelyElement, isStableId, SHADOW_SEPARATOR, shadowHostChain } from "@guidelytech/guide-runtime";
-var INTERACTIVE_SELECTOR = "a,button,input[type=button],input[type=submit],input[type=reset],input[type=checkbox],input[type=radio],select,summary,label,[role=button],[role=link],[role=tab],[role=menuitem],[role=checkbox],[role=switch],[role=option],[onclick],[data-guidely-track]";
-var DEFAULT_MASK_SELECTORS = ["[data-guidely-mask]", ".guidely-mask"];
-var PREFERRED_ATTRS = ["data-testid", "data-test-id", "data-test", "data-cy", "data-qa", "data-guidely-track", "data-tour"];
-var NOISY_DATA_ATTR = /^data-(state|v-|react|radix|headlessui|svelte|orientation|highlighted|focus|key|index|side|align|disabled|selected|active|open|guidely-(mask|ignore|block))/i;
-function validSelectors(list) {
-  const out = [];
-  const probe = typeof document !== "undefined" ? document.createDocumentFragment() : null;
-  for (const raw of list) {
-    const s = (raw || "").trim();
-    if (!s || out.includes(s)) continue;
-    try {
-      probe?.querySelector(s);
-      out.push(s);
-    } catch {
-    }
-  }
-  return out;
-}
-function isIgnoredElement(el) {
-  return isGuidelyElement(el) || !!closestComposed2(el, "[data-guidely-ignore]");
-}
-function interactiveElement(target) {
-  try {
-    return closestComposed2(target, INTERACTIVE_SELECTOR);
-  } catch {
-    return null;
-  }
-}
-function esc(value) {
-  const g = globalThis;
-  return g.CSS?.escape ? g.CSS.escape(value) : value.replace(/[^\w-]/g, (c) => `\\${c}`);
-}
-var attr = (tag, name, value) => value ? `${tag}[${name}="${value.replace(/["\\]/g, "\\$&")}"]` : `${tag}[${name}]`;
-function elementSelector(el) {
-  const own = ownSelector(el);
-  const chain = shadowHostChain(el);
-  return (chain ? chain + SHADOW_SEPARATOR + own : own).slice(0, 300);
-}
-function ownSelector(el) {
-  const tag = el.tagName.toLowerCase();
-  if (el.id && isStableId(el.id)) return `#${esc(el.id)}`;
-  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);
-  }
-  const label = el.getAttribute("aria-label");
-  if (label && label.length <= 80) return attr(tag, "aria-label", label);
-  const parts = [];
-  let cur = el;
-  while (cur && parts.length < 4) {
-    const t = cur.tagName.toLowerCase();
-    if (t === "html" || t === "body") break;
-    if (cur !== el && cur.id && isStableId(cur.id)) {
-      parts.unshift(`#${esc(cur.id)}`);
-      break;
-    }
-    const parent = cur.parentElement;
-    const node = cur;
-    const same = parent ? Array.from(parent.children).filter((c) => c.tagName === node.tagName) : [];
-    parts.unshift(same.length > 1 ? `${t}:nth-of-type(${same.indexOf(node) + 1})` : t);
-    cur = parent;
-  }
-  return parts.join(" > ") || tag;
-}
-function matches(el, selector, deep) {
-  if (!selector) return false;
-  try {
-    return !!closestComposed2(el, selector) || deep && !!el.querySelector(selector);
-  } catch {
-    return false;
-  }
-}
-function elementText(el, mask, maskAll) {
-  if (maskAll || matches(el, mask, true)) return void 0;
-  const tag = el.tagName.toLowerCase();
-  let text = "";
-  if (tag === "input") {
-    if (!/^(button|submit|reset)$/i.test(el.type || "")) return void 0;
-    text = el.value;
-  } else if (tag === "select" || tag === "textarea") return void 0;
-  else text = el.innerText ?? el.textContent ?? "";
-  text = (text || el.getAttribute("aria-label") || el.getAttribute("title") || "").replace(/\s+/g, " ").trim();
-  return text ? text.slice(0, 100) : void 0;
-}
-function linkHref(el) {
-  const a = closestComposed2(el, "a[href]");
-  if (!a) return void 0;
-  try {
-    const u = new URL(a.getAttribute("href") || "", location.href);
-    if (!/^https?:$/.test(u.protocol)) return void 0;
-    return u.origin === location.origin ? u.pathname : u.origin;
-  } catch {
-    return void 0;
-  }
-}
-function describeClick(el, e, opts) {
-  const props = { tag: el.tagName.toLowerCase(), selector: elementSelector(el), x: Math.round(e.pageX ?? 0) || 0, y: Math.round(e.pageY ?? 0) || 0 };
-  const text = elementText(el, opts.mask, opts.maskAll);
-  if (text) props.text = text;
-  const href = opts.collectUrls ? linkHref(el) : void 0;
-  if (href) props.href = href;
-  return props;
-}
-var RageClickDetector = class {
-  constructor(threshold = 3, windowMs = 1e3, radius = 30) {
-    __publicField(this, "threshold", threshold);
-    __publicField(this, "windowMs", windowMs);
-    __publicField(this, "radius", radius);
-    __publicField(this, "clicks", []);
-    __publicField(this, "fired", false);
-  }
-  /** Clicks in the current burst once it has fired (rage), otherwise 0. */
-  get burst() {
-    return this.fired ? this.clicks.length : 0;
-  }
-  /** Records a click; returns the click count when it completes a burst, otherwise 0. */
-  add(x, y, t) {
-    const first = this.clicks[0];
-    const last = this.clicks[this.clicks.length - 1];
-    if (!first || !last || t - last.t > this.windowMs || Math.hypot(x - first.x, y - first.y) > this.radius) {
-      this.clicks = [];
-      this.fired = false;
-    }
-    this.clicks = this.clicks.filter((c) => t - c.t <= this.windowMs);
-    this.clicks.push({ x, y, t });
-    if (this.fired || this.clicks.length < this.threshold) return 0;
-    this.fired = true;
-    return this.clicks.length;
-  }
-};
-
 // src/context.ts
 function detectDevice(ua, width) {
   const u = ua || "";
@@ -522,7 +739,8 @@ function detectDevice(ua, width) {
   else if (width > 0 && width < 768) type = "mobile";
   else if (width > 0 && width < 1024) type = "tablet";
   let browser;
-  if (/Edg\//i.test(u)) browser = "edge";
+  if (/Electron\//i.test(u)) browser = "electron";
+  else if (/Edg\//i.test(u)) browser = "edge";
   else if (/OPR\/|Opera/i.test(u)) browser = "opera";
   else if (/SamsungBrowser/i.test(u)) browser = "samsung";
   else if (/Chrome\/|CriOS/i.test(u)) browser = "chrome";
@@ -788,6 +1006,14 @@ function createMessengerTransport(opts) {
       h.onDone(d.messages.at(-1) ?? null, d.conversation);
     } else if (!finished) h.onError("The reply was interrupted");
   }
+  async function feedback(path, body, fallback) {
+    const res = await api.post(`/feedback${path}`, { ...body, anonymousId: opts.anonymousId(), userId: opts.userId() });
+    if (!res.ok || !res.data) {
+      if (res.status === 429) throw new HttpError(429, "You're doing that a lot. Please try again in a minute.");
+      throw new HttpError(res.status, serverMessage(res.data) ?? fallback);
+    }
+    return res.data;
+  }
   return {
     async listConversations() {
       const tokens = storedConversations(store, projectId).map((c) => c.token);
@@ -824,7 +1050,8 @@ function createMessengerTransport(opts) {
       return res.data;
     },
     async getArticle(id) {
-      const res = await api.get(`/articles/${encodeURIComponent(id)}`);
+      const locale = opts.locale?.();
+      const res = await api.get(`/articles/${encodeURIComponent(id)}`, locale ? { params: { locale } } : void 0);
       return res.ok && res.data ? res.data.article : null;
     },
     async fileComplaint(input) {
@@ -854,7 +1081,19 @@ function createMessengerTransport(opts) {
     async getHowTo(id) {
       const res = await api.get(`/how-tos/${encodeURIComponent(id)}`);
       return res.ok && res.data ? res.data.howTo : null;
-    }
+    },
+    // Ideas (feature requests). The visitor's ids go in every body; the server decides what they may do.
+    listIdeas: (query) => feedback("/requests/query", query, "Ideas couldn't be loaded."),
+    getIdea: (id) => feedback(`/requests/${encodeURIComponent(id)}/view`, {}, "This idea couldn't be loaded."),
+    submitIdea: (input) => feedback("/requests", { ...input, pageUrl: opts.pageUrl() }, "Your idea couldn't be sent. Please try again."),
+    voteIdea: (id, vote) => feedback(`/requests/${encodeURIComponent(id)}/vote`, vote, "Your vote couldn't be saved."),
+    unvoteIdea: (id) => feedback(`/requests/${encodeURIComponent(id)}/unvote`, {}, "Your vote couldn't be removed."),
+    followIdea: (id, follow) => feedback(`/requests/${encodeURIComponent(id)}/follow`, { follow }, "That didn't work. Please try again."),
+    commentIdea: (id, body) => feedback(`/requests/${encodeURIComponent(id)}/comments`, { body }, "Your comment couldn't be posted."),
+    similarIdeas: async (title) => (await feedback("/similar", { title }, "Similar ideas couldn't be loaded.")).requests ?? [],
+    ideaUpdates: () => feedback("/updates", {}, "Updates couldn't be loaded."),
+    markIdeaUpdatesRead: (ids) => feedback("/updates/read", ids ? { ids } : {}, "Updates couldn't be marked read."),
+    ideaPortalLink: async () => (await feedback("/portal-link", {}, "The feedback portal couldn't be opened.")).url
   };
 }
 
@@ -984,6 +1223,48 @@ function watchNavigation(listener, debounceMs = 50) {
   };
 }
 
+// src/page-url.ts
+var WEB_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "about", "data", "blob", "javascript"]);
+function appScheme(href) {
+  let u;
+  try {
+    u = new URL(href);
+  } catch {
+    return null;
+  }
+  const scheme = u.protocol.replace(/:$/, "").toLowerCase();
+  return WEB_SCHEMES.has(scheme) ? null : { u, scheme };
+}
+function normalizeAppUrl(href) {
+  const app = appScheme(href);
+  if (!app) return href;
+  const { u, scheme } = app;
+  const host = scheme === "file" ? "app" : u.host || "app";
+  const hash = /^#!?(\/.*)$/.exec(u.hash);
+  if (hash) {
+    const route = hash[1];
+    return `${scheme}://${host}${route.startsWith("/") ? route : `/${route}`}`;
+  }
+  let path = safeDecode(u.pathname);
+  if (scheme === "file" || /\.html?$/i.test(path)) {
+    const file = path.split("/").filter(Boolean).pop() ?? "";
+    const name = file.replace(/\.html?$/i, "");
+    path = !name || name.toLowerCase() === "index" ? "/" : `/${name}`;
+  }
+  if (!path.startsWith("/")) path = `/${path}`;
+  return `${scheme}://${host}${path}${u.search}`;
+}
+function safeDecode(s) {
+  try {
+    return decodeURI(s);
+  } catch {
+    return s;
+  }
+}
+function isAppUrl(href) {
+  return appScheme(href) !== null;
+}
+
 // src/page-tracking.ts
 function scrollDepth() {
   const de = document.documentElement;
@@ -1029,12 +1310,112 @@ var PageTracker = class {
   }
 };
 
+// src/prototype-overlay.ts
+var PROTOTYPE_CLOSE_MESSAGE = "guidely:prototype:close";
+var TOKEN = /^[A-Za-z0-9_-]{16,64}$/;
+var OVERLAY_ATTR = "data-guidely-prototype-overlay";
+function matchPrototypeTestUrl(urlOrToken, apiUrl) {
+  const value = (urlOrToken || "").trim();
+  let api;
+  try {
+    api = new URL(apiUrl);
+  } catch {
+    return null;
+  }
+  if (TOKEN.test(value)) return new URL(`/validate/${value}`, api.origin);
+  let url;
+  try {
+    url = new URL(value, typeof location !== "undefined" ? location.href : api.origin);
+  } catch {
+    return null;
+  }
+  if (url.origin !== api.origin) return null;
+  const m = /^\/validate\/([^/]+)\/?$/.exec(url.pathname);
+  if (!m || !TOKEN.test(m[1])) return null;
+  return new URL(`/validate/${m[1]}`, api.origin);
+}
+var current = null;
+function openPrototypeOverlay(testUrl, opts) {
+  current?.close();
+  const doc = document;
+  const previous = doc.activeElement;
+  const src = new URL(testUrl.href);
+  const hash = new URLSearchParams();
+  hash.set("key", opts.key);
+  if (opts.anonymousId) hash.set("anon", opts.anonymousId);
+  if (opts.userId) hash.set("uid", opts.userId);
+  src.hash = hash.toString();
+  const root = doc.createElement("div");
+  root.setAttribute(OVERLAY_ATTR, "");
+  root.setAttribute("role", "dialog");
+  root.setAttribute("aria-modal", "true");
+  root.setAttribute("aria-label", "Prototype test");
+  root.style.cssText = `position:fixed;inset:0;z-index:${opts.zIndex ?? 2147483646};background:rgba(15,23,42,.55);display:flex;align-items:stretch;justify-content:center;padding:0;margin:0;`;
+  const frame = doc.createElement("iframe");
+  frame.src = src.toString();
+  frame.title = "Prototype test";
+  frame.setAttribute("allow", "fullscreen");
+  frame.setAttribute("referrerpolicy", "no-referrer");
+  frame.style.cssText = "border:0;width:100%;height:100%;background:#fff;display:block;";
+  const close = doc.createElement("button");
+  close.type = "button";
+  close.setAttribute("aria-label", "Close prototype test");
+  close.textContent = "\xD7";
+  close.style.cssText = "position:absolute;top:10px;right:10px;width:36px;height:36px;border-radius:999px;border:0;background:rgba(15,23,42,.75);color:#fff;font:600 22px/36px system-ui,sans-serif;text-align:center;cursor:pointer;padding:0;z-index:1;";
+  root.append(frame, close);
+  const overflow = doc.documentElement.style.overflow;
+  doc.documentElement.style.overflow = "hidden";
+  let closed = false;
+  const shut = () => {
+    if (closed) return;
+    closed = true;
+    window.removeEventListener("message", onMessage);
+    doc.removeEventListener("keydown", onKey, true);
+    doc.removeEventListener("focusin", onFocus, true);
+    root.remove();
+    doc.documentElement.style.overflow = overflow;
+    if (current === overlay) current = null;
+    try {
+      previous?.focus?.();
+    } catch {
+    }
+    opts.onClose?.();
+  };
+  const onMessage = (e) => {
+    if (e.origin !== testUrl.origin || e.source !== frame.contentWindow) return;
+    const data = e.data;
+    if (data && typeof data === "object" && data.type === PROTOTYPE_CLOSE_MESSAGE) shut();
+  };
+  const onKey = (e) => {
+    if (e.key === "Escape") {
+      e.preventDefault();
+      e.stopPropagation();
+      shut();
+    } else if (e.key === "Tab") {
+      e.preventDefault();
+      (doc.activeElement === close ? frame : close).focus();
+    }
+  };
+  const onFocus = (e) => {
+    if (!root.contains(e.target)) close.focus();
+  };
+  close.addEventListener("click", shut);
+  window.addEventListener("message", onMessage);
+  doc.addEventListener("keydown", onKey, true);
+  doc.addEventListener("focusin", onFocus, true);
+  doc.body.appendChild(root);
+  frame.focus();
+  const overlay = { element: root, close: shut };
+  current = overlay;
+  return overlay;
+}
+
 // src/load-recorder.ts
 var loadRecorder = async () => (await import("./recorder.js")).recorder;
 
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.10.0";
+var SDK_VERSION = "0.11.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;
@@ -1060,7 +1441,7 @@ function emptyState() {
   return { guides: {}, checklists: {}, surveysSubmitted: [], audienceIds: [] };
 }
 function newSession(now = Date.now()) {
-  return { id: `s_${randomId(16)}`, startedAt: new Date(now).toISOString(), shownGuides: [], events: [], lastActivityAt: now };
+  return { id: `s_${randomId2(16)}`, startedAt: new Date(now).toISOString(), shownGuides: [], events: [], lastActivityAt: now };
 }
 var GuidelyClient = class _GuidelyClient {
   constructor(options) {
@@ -1072,6 +1453,8 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "queue");
     /** Survey answers and guide/checklist progress, kept until the server accepts them. */
     __publicField(this, "outbox");
+    /** Agent Analytics turns (agentConversation), in their own outbox. */
+    __publicField(this, "agentTurns");
     __publicField(this, "config", null);
     __publicField(this, "etag", null);
     __publicField(this, "anonymousId");
@@ -1121,6 +1504,10 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "flags");
     /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
     __publicField(this, "exposures", /* @__PURE__ */ new Set());
+    /** Language set with `setLocale()`. */
+    __publicField(this, "locale", null);
+    /** Language each shown guide was rendered in; added to its events as `locale`. */
+    __publicField(this, "guideLocales", /* @__PURE__ */ new Map());
     __publicField(this, "customListeners", /* @__PURE__ */ new Map());
     __publicField(this, "eventBus", {
       on: (name, cb) => {
@@ -1155,7 +1542,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_${randomId(20)}`;
+      this.anonymousId = `anon_${randomId2(20)}`;
       this.store.set(KEYS.anon, this.anonymousId);
     }
     this.firstVisit = !this.store.get(KEYS.seen);
@@ -1165,7 +1552,7 @@ var GuidelyClient = class _GuidelyClient {
     const session = readJson(this.sessionStore, KEYS.session, null);
     this.session = session && session.id ? session : newSession();
     this.persistSession();
-    this.lastUrl = location.href;
+    this.lastUrl = this.pageHref();
     this.lastAudiences = new Set(this.state.audienceIds);
     this.queue = new EventQueue({
       store: this.store,
@@ -1180,6 +1567,7 @@ var GuidelyClient = class _GuidelyClient {
       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 });
+    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);
   }
@@ -1256,7 +1644,7 @@ var GuidelyClient = class _GuidelyClient {
       this.resumeActiveGuide();
       this.evaluate("ready");
       if (!this.options.disableAuthoring && !capturing) this.maybeStartAuthoring();
-      this.pageTracker.start(location.href);
+      this.pageTracker.start(this.pageHref());
       this.touchSession();
       this.syncCapture();
     } catch (err) {
@@ -1289,7 +1677,7 @@ var GuidelyClient = class _GuidelyClient {
   wireListeners() {
     const doc = document;
     const win = window;
-    this.cleanups.push(watchNavigation((url) => this.handleNavigation(url)));
+    this.cleanups.push(watchNavigation((url) => this.handleNavigation(this.pageHref(url))));
     const onClick = (e) => this.handleDocumentClick(e);
     doc.addEventListener("click", onClick, true);
     this.cleanups.push(() => doc.removeEventListener("click", onClick, true));
@@ -1310,7 +1698,7 @@ var GuidelyClient = class _GuidelyClient {
     const onPageShow = (e) => {
       if (!e.persisted || !this.pageLeft) return;
       this.pageLeft = false;
-      this.pageTracker.start(location.href);
+      this.pageTracker.start(this.pageHref());
     };
     let lastScroll = 0;
     const onScroll = () => {
@@ -1359,7 +1747,7 @@ var GuidelyClient = class _GuidelyClient {
     this.cleanups.push(() => clearInterval(refresh));
     const poll = setInterval(() => {
       if (!this.isReady || !this.config || this.editing() || doc.visibilityState === "hidden") return;
-      const url = location.href;
+      const url = this.pageHref();
       const ctx = this.getContext();
       for (const guide of this.config.guides) {
         if (guide.config.trigger.type === "element_visible" && guide.config.trigger.value) this.armVisibility(guide, ctx, url);
@@ -1428,10 +1816,11 @@ var GuidelyClient = class _GuidelyClient {
     this.queue.flushSync();
     this.queue.destroy();
     this.outbox.destroy();
+    this.agentTurns.destroy();
     this.flags.destroy();
     this.emitter.clear();
     destroyHost();
-    if (current === this) current = null;
+    if (current2 === this) current2 = null;
   }
   // ---------------------------------------------------------------------------
   // Identity
@@ -1449,7 +1838,7 @@ var GuidelyClient = class _GuidelyClient {
     if (this.isReady) this.evaluate("identify");
   }
   async syncIdentify() {
-    const body = { anonymousId: this.anonymousId, userId: this.user?.id ?? null, traits: this.user?.traits, account: this.user?.account ? { id: this.user.account.id, traits: this.user.account.traits } : null, sessionId: this.session.id, url: this.collectUrls() ? location.href : void 0 };
+    const body = { anonymousId: this.anonymousId, userId: this.user?.id ?? null, traits: this.user?.traits, account: this.user?.account ? { id: this.user.account.id, traits: this.user.account.traits } : null, sessionId: this.session.id, url: this.collectUrls() ? this.pageHref() : void 0 };
     const res = await postWithRetry(this.api, "/identify", body, 2);
     if (res?.ok && res.data) this.mergeServerState(res.data);
   }
@@ -1480,7 +1869,10 @@ var GuidelyClient = class _GuidelyClient {
       checklists,
       surveysSubmitted: Array.from(/* @__PURE__ */ new Set([...this.state.surveysSubmitted, ...data.surveysSubmitted || []])),
       audienceIds: data.audienceIds || [],
-      firstSeenAt: this.state.firstSeenAt ?? data.firstSeenAt
+      firstSeenAt: this.state.firstSeenAt ?? data.firstSeenAt,
+      // Device-local only (the server doesn't hold them).
+      ...this.state.throttle ? { throttle: this.state.throttle } : {},
+      ...this.state.announcementsSeenAt ? { announcementsSeenAt: this.state.announcementsSeenAt } : {}
     };
     if (data.firstSeenAt && Date.now() - Date.parse(data.firstSeenAt) > 6e4) this.firstVisit = false;
     this.persistState();
@@ -1516,7 +1908,7 @@ var GuidelyClient = class _GuidelyClient {
     this.stopGuide();
     this.user = null;
     this.store.remove(KEYS.user(this.options.projectId));
-    this.anonymousId = `anon_${randomId(20)}`;
+    this.anonymousId = `anon_${randomId2(20)}`;
     this.store.set(KEYS.anon, this.anonymousId);
     this.state = emptyState();
     this.persistState();
@@ -1548,6 +1940,7 @@ var GuidelyClient = class _GuidelyClient {
     if (consent === "denied") this.queue.clear();
     else if (consent === "granted") void this.queue.flush();
     if (consent !== "granted") this.replay?.stop({ discard: true });
+    if (consent !== "pending") this.agentTurns.consentChanged(consent === "granted");
     this.syncCapture();
   }
   analyticsEnabled() {
@@ -1560,17 +1953,19 @@ var GuidelyClient = class _GuidelyClient {
     if (this.consent === "denied" || !this.options.analytics) return null;
     if (name !== "page_leave" && name !== "heatmap") this.touchSession();
     const event = {
-      eventId: randomId(24),
+      eventId: randomId2(24),
       name,
       occurredAt: nowIso(),
       anonymousId: this.anonymousId,
       userId: this.user?.id || null,
       accountId: this.user?.account?.id || null,
       sessionId: this.session.id,
-      url: this.collectUrls() ? location.href : void 0,
+      url: this.collectUrls() ? this.pageHref() : void 0,
       ...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);
     this.replay?.addCustomEvent("guidely", { name, customName: event.customName, guideId: event.guideId });
     this.emitter.emit("track", event);
@@ -1594,9 +1989,30 @@ var GuidelyClient = class _GuidelyClient {
     this.completeChecklistTasksBy("event", name);
     if (this.isReady) this.evaluate("event", { eventName: name });
   }
+  /**
+   * Agent Analytics: records one or more turns of a conversation with your own AI agent or chatbot
+   * (`{ conversationId, agentId, role, text, toolCalls?, latencyMs?, outcome?, … }`). The visitor's
+   * anonymous id, user id, account id and session id are filled in, `agents.redact` from the init
+   * options runs on each turn, and turns are retried until Guidely accepts them. Returns false when
+   * nothing was queued (analytics off or consent denied, or every turn was invalid or dropped).
+   */
+  agentConversation(turns) {
+    if (this.destroyed || !this.options.analytics || this.consent === "denied" || this.config?.settings?.analyticsEnabled === false) return false;
+    const identity = { anonymousId: this.anonymousId, userId: this.user?.id || null, accountId: this.user?.account?.id || null, sessionId: this.session.id };
+    const prepared = (Array.isArray(turns) ? turns : [turns]).map((t) => prepareAgentTurn(t, identity, this.options.agents?.redact, (err) => this.reportError(err))).filter((t) => !!t);
+    if (!prepared.length) return false;
+    this.touchSession();
+    this.agentTurns.add(prepared, this.consent === "pending");
+    return true;
+  }
+  /** Alias of {@link agentConversation}. */
+  trackAgentTurn(turns) {
+    return this.agentConversation(turns);
+  }
   /** Records a page view and re-evaluates triggers. Called automatically on SPA navigation. */
-  page(url = location.href) {
+  page(href) {
     if (this.destroyed) return;
+    const url = this.pageHref(href);
     this.leavePage(url);
     this.trackPageView(url);
     this.handleNavigation(url, true);
@@ -1688,6 +2104,8 @@ var GuidelyClient = class _GuidelyClient {
       const ref = !this.session.pageViews ? externalReferrer() : void 0;
       if (ref) props.referrer = ref;
     }
+    const ep = this.captureAllowed() ? pagePropertyValues(this.config?.tagging, url, { mask: this.maskSelector(), maskAll: this.maskAllText() }) : void 0;
+    if (ep) props.ep = ep;
     this.session.pageViews = (this.session.pageViews ?? 0) + 1;
     this.persistSession();
     this.enqueue("page_view", { url: collect ? url : void 0, properties: props });
@@ -1713,13 +2131,20 @@ var GuidelyClient = class _GuidelyClient {
     const heat = this.autocaptureOn("heatmaps");
     if (!clicks && !rage && !heat || isIgnoredElement(target)) return;
     this.touchSession();
-    const el = interactiveElement(target);
+    const featureAttribute = this.config?.tagging?.featureAttribute ?? null;
+    const feature = featureAttributeOf(target, featureAttribute);
+    const el = interactiveElement(target) ?? feature?.el ?? null;
     const opts = { mask: this.maskSelector(), maskAll: this.maskAllText(), collectUrls: this.collectUrls() };
-    if (clicks && el) this.enqueue("click", { properties: { ...describeClick(el, e, opts) } });
+    const clickProps = (on) => {
+      const p = describeClick(on, e, opts);
+      const ep = clickPropertyValues(this.config?.tagging, on, p, opts);
+      return { ...p, el: elementSnapshot(on, { ...opts, featureAttribute }), ...feature ? { fa: feature.value } : {}, ...ep ? { ep } : {} };
+    };
+    if (clicks && el) this.enqueue("click", { properties: clickProps(el) });
     const count = this.rage.add(e.pageX ?? 0, e.pageY ?? 0, Date.now());
-    if (rage && count) this.enqueue("rage_click", { properties: { ...describeClick(el ?? target, e, opts), count } });
+    if (rage && count) this.enqueue("rage_click", { properties: { ...clickProps(el ?? target), count } });
     if (!heat) return;
-    const url = location.href;
+    const url = this.pageHref();
     if (this.heatmap.url !== url) this.flushHeatmap();
     if (this.heatmap.add(url, heatmapPoint(el ?? target, e, this.rage.burst > 0), this.rage.burst)) this.flushHeatmap();
   }
@@ -1727,7 +2152,7 @@ var GuidelyClient = class _GuidelyClient {
   sampleMove(e) {
     const target = composedTarget(e);
     if (document.visibilityState === "hidden" || !target?.closest || !this.autocaptureOn("mouseMovement") || isIgnoredElement(target)) return;
-    const url = location.href;
+    const url = this.pageHref();
     if (this.heatmap.url !== url) this.flushHeatmap();
     if (this.heatmap.move(url, movementBin(interactiveElement(target) ?? target, e))) this.flushHeatmap();
   }
@@ -1803,7 +2228,7 @@ var GuidelyClient = class _GuidelyClient {
     if (!this.isReady || this.destroyed) return;
     if (this.config && !this.initialPageViewSent && this.config.settings?.autocapture) {
       this.initialPageViewSent = true;
-      this.trackPageView(location.href);
+      this.trackPageView(this.pageHref());
     }
     if (this.config) {
       for (const [props, extra] of this.earlyExceptions.splice(0)) {
@@ -1838,7 +2263,7 @@ var GuidelyClient = class _GuidelyClient {
             return {
               anonymousId: this.anonymousId,
               userId: this.user?.id || null,
-              url: this.collectUrls() ? location.href : void 0,
+              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 }
@@ -1889,6 +2314,14 @@ var GuidelyClient = class _GuidelyClient {
   // ---------------------------------------------------------------------------
   // Targeting + triggers
   // ---------------------------------------------------------------------------
+  /** The page URL Guidely works with: `options.pageUrl`, else app-relative for `file:` / custom protocols (`normalizeAppUrl`). */
+  pageHref(href = location.href) {
+    try {
+      return this.options.pageUrl ? this.options.pageUrl(href) || href : normalizeAppUrl(href);
+    } catch {
+      return href;
+    }
+  }
   /** Builds the targeting context for the current moment. */
   getContext() {
     const guides = this.state.guides;
@@ -1899,7 +2332,7 @@ var GuidelyClient = class _GuidelyClient {
       userId: this.user?.id || null,
       userAttributes: this.user?.traits ?? {},
       accountAttributes: this.user?.account?.traits ?? {},
-      url: location.href,
+      url: this.pageHref(),
       firstVisit: this.firstVisit,
       eventsSeen: this.session.events,
       completedGuides: keysOf(Object.keys(guides).filter((id) => guides[id]?.completedAt)),
@@ -1908,7 +2341,8 @@ var GuidelyClient = class _GuidelyClient {
       completedChecklists: keysOf(completedChecklists),
       audienceIds: this.state.audienceIds,
       environment: this.options.environment,
-      platform: "web"
+      platform: "web",
+      ...this.options.appVersion ? { appVersion: this.options.appVersion } : {}
     });
   }
   isTargeted(guide, ctx, url) {
@@ -1920,6 +2354,52 @@ var GuidelyClient = class _GuidelyClient {
     ctx.rolloutSalt = guide.id;
     return evaluateRules(c.targeting, ctx);
   }
+  /** Guide throttling: may this guide launch automatically now? */
+  throttleAllows(guide) {
+    if (!countsTowardThrottle(guide)) return true;
+    return isThrottleEligible(this.config?.settings.throttling, this.state.throttle ?? []);
+  }
+  recordLaunch(guide, manual) {
+    if (manual || !countsTowardThrottle(guide) || !this.config?.settings.throttling?.enabled) return;
+    this.state.throttle = pruneLaunches([...this.state.throttle ?? [], nowIso()], this.config.settings.throttling);
+    this.persistState();
+  }
+  /** Guides and A/B test control groups, which are evaluated the same way but never render. */
+  candidates() {
+    const guides = this.config?.guides ?? [];
+    const holdouts = this.config?.guideHoldouts ?? [];
+    return holdouts.length ? [...guides, ...holdouts.map((h) => h.guide)] : guides;
+  }
+  holdoutFor(guide) {
+    return this.config?.guideHoldouts?.find((h) => h.guide.id === guide.id) ?? null;
+  }
+  /** The visitor's language candidates, most preferred first. */
+  locales() {
+    const nav = typeof navigator !== "undefined" ? [...navigator.languages ?? [], navigator.language] : [];
+    return visitorLocales(this.locale ?? this.options.locale, this.user?.traits, nav);
+  }
+  defaultLocale() {
+    return this.config?.settings.localization?.defaultLocale || "en";
+  }
+  /** The guide in the visitor's language (remembered so its events carry `locale`). */
+  localize(guide) {
+    const localized = localizeGuide(guide, this.locales(), this.defaultLocale());
+    this.guideLocales.set(guide.id, localized.locale);
+    return localized;
+  }
+  /**
+   * Sets the language for guides and the resource center (`null` = back to the traits / browser).
+   * Guides already on screen keep their language; the resource center re-renders.
+   */
+  setLocale(locale) {
+    this.locale = locale ? normalizeLocale(locale) || null : null;
+    if (this.resourceCenter) {
+      this.resourceCenter.destroy();
+      this.resourceCenterScope?.destroy();
+      this.resourceCenter = null;
+      this.renderPersistentWidgets();
+    }
+  }
   isEligible(guide, ctx, url) {
     if (!this.isTargeted(guide, ctx, url)) return false;
     const shownThisSession = this.session.shownGuides.includes(guide.id);
@@ -1936,13 +2416,13 @@ var GuidelyClient = class _GuidelyClient {
         if (t.delayMs > 0) return reason === "timer" && detail.guideId === guide.id;
         return reason === "ready" || reason === "navigation" || reason === "identify";
       case "url_match":
-        return (reason === "ready" || reason === "navigation" || reason === "identify") && urlMatches2(t.value, location.href);
+        return (reason === "ready" || reason === "navigation" || reason === "identify") && urlMatches2(t.value, this.pageHref());
       case "event":
         return reason === "event" && !!t.value && detail.eventName === t.value;
       case "element_click":
         if (reason !== "click" || !t.value || !detail.target) return false;
         try {
-          return !!closestComposed3(detail.target, t.value);
+          return !!closestComposed4(detail.target, t.value);
         } catch {
           return false;
         }
@@ -1961,15 +2441,15 @@ var GuidelyClient = class _GuidelyClient {
   }
   evaluate(reason, detail = {}) {
     if (!this.config || this.destroyed || this.editing()) return;
-    const url = location.href;
+    const url = this.pageHref();
     const ctx = this.getContext();
     if (reason === "identify") {
-      const current2 = new Set(this.state.audienceIds);
-      detail.newAudiences = new Set(Array.from(current2).filter((a) => !this.lastAudiences.has(a)));
-      this.lastAudiences = current2;
+      const current3 = new Set(this.state.audienceIds);
+      detail.newAudiences = new Set(Array.from(current3).filter((a) => !this.lastAudiences.has(a)));
+      this.lastAudiences = current3;
     }
     const candidates = [];
-    for (const guide of this.config.guides) {
+    for (const guide of this.candidates()) {
       const t = guide.config.trigger;
       if (detail.endedGuide && detail.endedGuide.id === guide.id) continue;
       if (reason === "ready" || reason === "navigation") {
@@ -1985,6 +2465,10 @@ var GuidelyClient = class _GuidelyClient {
       if (t.type === "page_load" && t.delayMs > 0 && reason === "timer" && detail.guideId !== guide.id) continue;
       if (!this.triggerFires(guide, reason, detail)) continue;
       if (!this.isEligible(guide, ctx, url)) continue;
+      if (!this.throttleAllows(guide)) {
+        this.log("throttled", guide.key);
+        continue;
+      }
       candidates.push(guide);
     }
     if (reason === "after_guide" || reason === "navigation") this.drainQueue(url, ctx);
@@ -2035,6 +2519,13 @@ var GuidelyClient = class _GuidelyClient {
   /** Decides whether a guide can show now, otherwise queues it. */
   tryShow(guide, url, manual) {
     if (this.destroyed) return false;
+    if (!manual && !this.throttleAllows(guide)) return false;
+    const holdout = this.holdoutFor(guide);
+    if (holdout) {
+      if (this.active && !manual) return false;
+      this.recordImpression(guide, manual);
+      return true;
+    }
     if (!isExclusiveGuide(guide)) {
       if (this.widgets.has(guide.id)) return false;
       this.show(guide, manual);
@@ -2075,14 +2566,18 @@ var GuidelyClient = class _GuidelyClient {
   guideState(id) {
     return this.state.guides[id] ?? (this.state.guides[id] = { impressions: 0 });
   }
-  recordImpression(guide) {
+  recordImpression(guide, manual = false) {
     const s = this.guideState(guide.id);
     s.impressions += 1;
     s.lastShownAt = nowIso();
     if (!this.session.shownGuides.includes(guide.id)) this.session.shownGuides.push(guide.id);
+    this.recordLaunch(guide, manual);
     this.persistState();
     this.persistSession();
-    this.syncGuideState(guide.id, { impression: true });
+    const holdout = this.holdoutFor(guide);
+    const experiment = holdout ? { id: holdout.experimentId, variantId: holdout.variantId } : guide.experiment;
+    if (experiment) this.enqueue("experiment_viewed", { properties: { guideExperimentId: experiment.id, variantId: experiment.variantId, ...holdout ? {} : { guideId: guide.id } } });
+    if (!holdout) this.syncGuideState(guide.id, { impression: true });
   }
   recordEnd(guide, reason) {
     const s = this.guideState(guide.id);
@@ -2106,13 +2601,17 @@ var GuidelyClient = class _GuidelyClient {
       this.reportError(err);
     }
   }
-  showFlow(guide, manual, stepId) {
+  showFlow(raw, manual, stepId) {
     if (this.editing()) return;
+    const guide = this.localize(raw);
     const exclusive = isExclusiveGuide(guide);
-    const entry = { guide, manual, startUrl: location.href };
+    const entry = { guide, manual, startUrl: this.pageHref() };
     const controller = runGuide2(guide, {
       theme: this.theme(),
+      // Code blocks only arrive when a workspace admin allowed them (the server strips them otherwise).
+      runCode: true,
       ctx: () => this.getContext(),
+      currentUrl: () => this.pageHref(),
       startAtStep: stepId,
       eventBus: this.eventBus,
       // Started from Help, Scout or startGuide(): steps on other pages offer to take the user there.
@@ -2126,7 +2625,7 @@ var GuidelyClient = class _GuidelyClient {
         const step = e.stepId ? guide.config.steps.find((s) => s.id === e.stepId) : void 0;
         this.enqueue(e.name, { guideId: guide.id, guideVersion: guide.version, stepId: e.stepId, stepIndex: e.stepIndex, properties: e.properties });
         if (e.name === "guide_started") {
-          this.recordImpression(guide);
+          this.recordImpression(guide, manual);
           this.emitter.emit("guide:start", guide);
         }
         if (e.name === "step_viewed" && step) {
@@ -2173,8 +2672,9 @@ var GuidelyClient = class _GuidelyClient {
       this.widgets.delete(guide.id);
     }
   }
-  showChecklist(guide) {
+  showChecklist(raw) {
     if (this.editing()) return;
+    const guide = this.localize(raw);
     const config = guide.config.checklist;
     if (!config || this.widgets.has(guide.id)) return;
     const scope = createScope(this.theme(), guide.config.appearance);
@@ -2195,12 +2695,13 @@ var GuidelyClient = class _GuidelyClient {
     }, checklist: widget, scope });
     if (first) this.recordImpression(guide);
   }
-  showSurvey(guide, manual) {
+  showSurvey(raw, manual) {
     if (this.editing()) return;
+    const guide = this.localize(raw);
     const config = guide.config.survey;
     if (!config) return;
     const scope = createScope(this.theme(), guide.config.appearance);
-    const entry = { guide, manual, startUrl: location.href, scope };
+    const entry = { guide, manual, startUrl: this.pageHref(), scope };
     const finish = (reason) => {
       widget.destroy();
       scope.destroy();
@@ -2218,7 +2719,7 @@ var GuidelyClient = class _GuidelyClient {
       title: guide.name,
       onDismiss: () => finish(this.state.surveysSubmitted.includes(guide.id) ? "submitted" : "dismissed"),
       onSubmit: (answers) => {
-        const responseId = randomId(24);
+        const responseId = randomId2(24);
         this.state.surveysSubmitted.push(guide.id);
         this.persistState();
         this.recordEnd(guide, "completed");
@@ -2231,7 +2732,7 @@ var GuidelyClient = class _GuidelyClient {
     });
     entry.survey = widget;
     this.active = entry;
-    this.recordImpression(guide);
+    this.recordImpression(guide, manual);
     this.enqueue("survey_displayed", { guideId: guide.id, guideVersion: guide.version });
     this.emitter.emit("guide:start", guide);
   }
@@ -2240,6 +2741,7 @@ var GuidelyClient = class _GuidelyClient {
   }
   navigate(url, newTab) {
     try {
+      if (this.openPrototypeTest(url)) return;
       if (newTab) window.open(url, "_blank", "noopener");
       else location.assign(url);
     } catch (err) {
@@ -2264,7 +2766,13 @@ var GuidelyClient = class _GuidelyClient {
       this.resourceCenterScope = scope;
       this.resourceCenter = renderResourceCenter({
         scope: scope.el,
-        config: rc,
+        config: localizeResourceCenter(rc, this.locales(), this.defaultLocale()),
+        evaluate: (rules) => evaluateRules(rules, this.getContext()),
+        announcementsSeenAt: () => this.state.announcementsSeenAt ?? null,
+        onAnnouncementsSeen: () => {
+          this.state.announcementsSeenAt = nowIso();
+          this.persistState();
+        },
         guides: this.config.guides.map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind })),
         search: (q) => this.searchResourceCenter(q),
         audienceIds: () => this.state.audienceIds,
@@ -2309,7 +2817,8 @@ var GuidelyClient = class _GuidelyClient {
           projectId: this.options.projectId,
           anonymousId: () => this.anonymousId,
           userId: () => this.user?.id || null,
-          pageUrl: () => this.collectUrls() ? location.href : void 0
+          pageUrl: () => this.collectUrls() ? this.pageHref() : void 0,
+          locale: () => this.rcLocale()
         }),
         visitor: () => this.messengerVisitor(),
         brand: { logoUrl: this.theme().logoUrl ?? null, name: this.theme().brandName ?? null },
@@ -2318,7 +2827,8 @@ var GuidelyClient = class _GuidelyClient {
           const seen = readJson(this.store, KEYS.newsSeen(this.options.projectId), []);
           writeJson(this.store, KEYS.newsSeen(this.options.projectId), Array.from(/* @__PURE__ */ new Set([...ids, ...Array.isArray(seen) ? seen : []])).slice(0, 200));
         },
-        resourceCenter: this.config.resourceCenter,
+        resourceCenter: this.config.resourceCenter ? localizeResourceCenter(this.config.resourceCenter, this.locales(), this.defaultLocale()) : null,
+        evaluate: (rules) => evaluateRules(rules, this.getContext()),
         audienceIds: () => this.state.audienceIds,
         guides: this.config.guides.map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind })),
         onStartGuide: (idOrKey) => this.startGuide(idOrKey),
@@ -2342,7 +2852,7 @@ var GuidelyClient = class _GuidelyClient {
   /** What the messenger personalises from, computed fresh on every render. */
   messengerVisitor() {
     const ctx = this.getContext();
-    const url = location.href;
+    const url = this.pageHref();
     const seen = readJson(this.store, KEYS.newsSeen(this.options.projectId), []);
     const visitor = buildMessengerVisitor({
       guides: this.config?.guides ?? [],
@@ -2357,7 +2867,20 @@ var GuidelyClient = class _GuidelyClient {
       },
       newsSeen: Array.isArray(seen) ? seen : []
     });
-    return { ...visitor, identified: !!this.user?.id };
+    const rc = this.config?.resourceCenter;
+    const rcNews = rc?.announcements?.length ? visibleAnnouncements(localizeResourceCenter(rc, this.locales(), this.defaultLocale()).announcements, this.state.audienceIds).map((a) => ({
+      id: `rc_${a.id}`,
+      key: a.guideId ?? "",
+      title: a.title,
+      body: plainText(a.body),
+      imageUrl: null,
+      publishedAt: a.publishedAt,
+      unread: !(Array.isArray(seen) && seen.includes(`rc_${a.id}`)),
+      articleId: a.articleId ?? null,
+      url: a.url ?? null
+    })) : [];
+    const news = rcNews.length ? [...visitor.news, ...rcNews].sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)).slice(0, 10) : visitor.news;
+    return { ...visitor, news, identified: !!this.user?.id };
   }
   destroyMessenger() {
     this.messenger?.destroy();
@@ -2365,9 +2888,17 @@ var GuidelyClient = class _GuidelyClient {
     this.messenger = null;
     this.messengerScope = null;
   }
+  /** The resource center's language for this visitor, or null for the default language. */
+  rcLocale() {
+    const rc = this.config?.resourceCenter;
+    if (!rc) return null;
+    const locale = localizeResourceCenter(rc, this.locales(), this.defaultLocale()).locale;
+    return locale.toLowerCase() === this.defaultLocale().toLowerCase() ? null : locale;
+  }
   async loadArticle(id) {
     try {
-      const res = await this.api.get(`/articles/${encodeURIComponent(id)}`);
+      const locale = this.rcLocale();
+      const res = await this.api.get(`/articles/${encodeURIComponent(id)}`, locale ? { params: { locale } } : void 0);
       return res.ok && res.data ? res.data.article : null;
     } catch {
       return null;
@@ -2432,7 +2963,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 = !!closestComposed3(value, task.completionValue);
+            hit = !!closestComposed4(value, task.completionValue);
           } catch {
             hit = false;
           }
@@ -2543,6 +3074,18 @@ var GuidelyClient = class _GuidelyClient {
   closeMessenger() {
     this.messenger?.close();
   }
+  /**
+   * Opens a Guidely prototype test (its `/validate/<token>` URL on this SDK's API origin, or the bare
+   * token) in a full-screen overlay, attributed to the current user. Returns false, doing nothing, for
+   * any other URL. Guide buttons that open a test URL use this automatically.
+   */
+  openPrototypeTest(urlOrToken) {
+    if (typeof document === "undefined") return false;
+    const url = matchPrototypeTestUrl(urlOrToken, this.options.apiUrl);
+    if (!url) return false;
+    openPrototypeOverlay(url, { key: this.options.projectId, anonymousId: this.anonymousId, userId: this.user?.id ?? null });
+    return true;
+  }
   /**
    * Opens the complaint form in the messenger, optionally with a category picked (its id from
    * Complaints → Categories). Does nothing when the project doesn't take complaints.
@@ -2551,6 +3094,14 @@ var GuidelyClient = class _GuidelyClient {
     if (!this.config?.messenger?.enabled || !this.config.messenger.complaints?.categories.length) return;
     void this.loadMessenger().then((m) => m?.openComplaint(categoryId));
   }
+  /**
+   * Opens the Ideas tab in the messenger (feature requests and voting), or one idea by its id.
+   * Does nothing when the project hasn't turned on Ideas.
+   */
+  openIdeas(requestId) {
+    if (!this.config?.messenger?.enabled || !this.config.messenger.ideas) return;
+    void this.loadMessenger().then((m) => m?.openIdeas(requestId));
+  }
   /** Opens a new messenger conversation, optionally pre-filling the message. */
   showNewMessage(text) {
     if (!this.config?.messenger?.enabled) return;
@@ -2580,14 +3131,15 @@ var GuidelyClient = class _GuidelyClient {
     const device = detectDevice(navigator.userAgent, window.innerWidth);
     const account = this.user?.account;
     return {
-      url: location.href,
-      path: location.pathname,
+      url: this.pageHref(),
+      path: pathOf2(this.pageHref()),
       deviceType: device.type,
       browser: device.browser,
       os: device.os,
       locale: navigator.language || void 0,
       environment: this.options.environment,
       platform: "web",
+      ...this.options.appVersion ? { appVersion: this.options.appVersion } : {},
       ...this.user?.traits ?? {},
       id: this.user?.id || this.anonymousId,
       anonymousId: this.anonymousId,
@@ -2747,18 +3299,18 @@ var GuidelyClient = class _GuidelyClient {
   // ---------------------------------------------------------------------------
   /** Creates (or returns the existing) client and starts initialisation. */
   static init(options) {
-    if (current && !current.destroyed && current.options.projectId === options.projectId) return current;
-    current?.destroy();
-    current = new _GuidelyClient(options);
-    void current.init();
-    return current;
+    if (current2 && !current2.destroyed && current2.options.projectId === options.projectId) return current2;
+    current2?.destroy();
+    current2 = new _GuidelyClient(options);
+    void current2.init();
+    return current2;
   }
   /** The most recently created client, if any. */
   static get() {
-    return current && !current.destroyed ? current : null;
+    return current2 && !current2.destroyed ? current2 : null;
   }
 };
-var current = null;
+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")) };
 }
@@ -2780,7 +3332,7 @@ function externalReferrer() {
 }
 function createGuidely(options) {
   const client = new GuidelyClient(options);
-  current = client;
+  current2 = client;
   void client.init();
   return client;
 }
@@ -2802,18 +3354,25 @@ export {
   GuidelyClient,
   HEARTBEAT_MS,
   KEYS,
+  PROTOTYPE_CLOSE_MESSAGE,
   SDK_NAME,
   SDK_VERSION,
   areMutuallyExclusive,
   buildContext,
   captureSnapshot,
+  countsTowardThrottle,
   createGuidely,
   createStorage,
   index_default as default,
   detectDevice,
+  isAppUrl,
   isExclusiveGuide,
   isFrequencyEligible,
+  isThrottleEligible,
   isWithinSchedule,
+  matchPrototypeTestUrl,
+  normalizeAppUrl,
+  pruneLaunches,
   watchNavigation
 };
 //# sourceMappingURL=index.js.map