@guidelytech/sdk-core 0.1.0 → 0.2.1

package/README.md

@@ -149,8 +149,10 @@ Messages posted to the opener: `guidely:authoring-ready { sessionId, url }`, `gu
 
 | Bundle | minified | min+gz |
 |---|---|---|
-| sdk-core + guide-runtime + floating-ui + `@guidelytech/shared/runtime` (everything an app ships) | 115 kB | **35.8 kB** |
-| script-tag build `guidely.js` (authoring schemas inlined) | 215 kB | 62 kB |
+| sdk-core + guide-runtime + floating-ui + `@guidelytech/shared/runtime` (everything an app ships) | 127 kB | **39.4 kB** |
+| Scout messenger chunk (`@guidelytech/guide-runtime/messenger`, loaded on demand) | 26 kB | 8.8 kB |
+| script-tag build `guidely.js` (authoring schemas and messenger inlined) | 244 kB | ~71 kB |
 
 The SDK imports only the zod-free `@guidelytech/shared/runtime` entry; the Zod schemas are loaded
-lazily and only when the page enters authoring mode. Budget: 45 kB min+gz for the npm runtime.
+lazily and only when the page enters authoring mode. Budget: 45 kB min+gz for the npm runtime and
+15 kB for the messenger chunk.

package/dist/index.cjs

@@ -43,6 +43,7 @@ __export(index_exports, {
   SDK_VERSION: () => SDK_VERSION,
   areMutuallyExclusive: () => areMutuallyExclusive,
   buildContext: () => buildContext,
+  captureSnapshot: () => captureSnapshot,
   createGuidely: () => createGuidely,
   createStorage: () => createStorage,
   default: () => index_default,
@@ -55,13 +56,89 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_runtime5 = require("@guidelytech/shared/runtime");
+var import_runtime6 = require("@guidelytech/shared/runtime");
 var import_guide_runtime2 = require("@guidelytech/guide-runtime");
 var import_guide_runtime3 = require("@guidelytech/guide-runtime");
 
 // src/authoring.ts
 var import_guide_runtime = require("@guidelytech/guide-runtime");
 
+// src/snapshot.ts
+var MAX_SNAPSHOT_BYTES = 6 * 1024 * 1024;
+var STRIP = "script, noscript, template, #guidely-root, [data-guidely], meta[http-equiv], link[rel~='preload'], link[rel~='modulepreload'], link[rel~='prefetch'], link[rel~='manifest'], link[rel~='serviceworker']";
+function rulesText(sheet) {
+  if (!sheet) return null;
+  try {
+    return Array.from(sheet.cssRules, (r) => r.cssText).join("\n");
+  } catch {
+    return null;
+  }
+}
+function maskText(root) {
+  const walker = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    n.textContent = (n.textContent ?? "").replace(/\S/g, "\u2022");
+  }
+}
+function captureSnapshot(doc, maskSelectors, maxBytes = MAX_SNAPSHOT_BYTES) {
+  const win = doc.defaultView;
+  if (!win || !doc.documentElement) return null;
+  const clone = doc.documentElement.cloneNode(true);
+  const origStyles = doc.documentElement.querySelectorAll("style");
+  clone.querySelectorAll("style").forEach((el, i) => {
+    const css = rulesText(origStyles[i]?.sheet);
+    if (css !== null && css.length > (el.textContent ?? "").length) el.textContent = css;
+  });
+  const origFrames = doc.documentElement.querySelectorAll("iframe, canvas, video, embed, object");
+  clone.querySelectorAll("iframe, canvas, video, embed, object").forEach((el, i) => {
+    const r = origFrames[i]?.getBoundingClientRect();
+    const box = doc.createElement("div");
+    box.setAttribute("style", `${el.getAttribute("style") ?? ""};width:${r?.width ?? 0}px;height:${r?.height ?? 0}px;background:#e2e8f0;border-radius:4px`);
+    if (el.getAttribute("class")) box.setAttribute("class", el.getAttribute("class"));
+    el.replaceWith(box);
+  });
+  clone.querySelectorAll(STRIP).forEach((el) => el.remove());
+  for (const sel of maskSelectors) {
+    try {
+      clone.querySelectorAll(sel).forEach(maskText);
+    } catch {
+    }
+  }
+  clone.querySelectorAll("*").forEach((el) => {
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith("on") || (name === "href" || name === "src" || name === "action") && /^\s*javascript:/i.test(attr.value)) el.removeAttribute(attr.name);
+    }
+    if (el instanceof HTMLInputElement) {
+      el.removeAttribute("value");
+      el.removeAttribute("checked");
+    } else if (el instanceof HTMLTextAreaElement) {
+      el.textContent = "";
+    }
+    el.removeAttribute("autofocus");
+  });
+  const adopted = Array.from(doc.adoptedStyleSheets ?? []).map(rulesText).filter(Boolean).join("\n");
+  let head = clone.querySelector("head");
+  if (!head) {
+    head = doc.createElement("head");
+    clone.prepend(head);
+  }
+  if (adopted) {
+    const style = doc.createElement("style");
+    style.textContent = adopted;
+    head.append(style);
+  }
+  clone.querySelectorAll("base").forEach((el) => el.remove());
+  const base = doc.createElement("base");
+  base.setAttribute("href", doc.baseURI || win.location.href);
+  base.setAttribute("target", "_blank");
+  head.prepend(base);
+  const html = `<!DOCTYPE html>
+${clone.outerHTML}`;
+  if (html.length > maxBytes) return null;
+  return { html, url: win.location.href, title: doc.title, width: win.innerWidth, height: win.innerHeight, capturedAt: (/* @__PURE__ */ new Date()).toISOString() };
+}
+
 // src/storage.ts
 function memoryStore() {
   const map = /* @__PURE__ */ new Map();
@@ -129,7 +206,9 @@ var KEYS = {
   queue: (key) => `guidely:queue:${key}`,
   session: "guidely:session",
   active: "guidely:active",
-  authoring: "guidely:authoring"
+  authoring: "guidely:authoring",
+  /** Messenger conversations this browser can read: [{ id, token }]. */
+  conversations: (key) => `guidely:conversations:${key}`
 };
 
 // src/authoring.ts
@@ -139,6 +218,8 @@ async function loadSchemas() {
 }
 var AUTHORING_PARAM = "guidely_authoring";
 var HEARTBEAT_MS = 15e3;
+var SNAPSHOT_DEBOUNCE_MS = 800;
+var SNAPSHOT_MAX_WAIT_MS = 4e3;
 var AuthoringBridge = class {
   constructor(opts) {
     __publicField(this, "opts", opts);
@@ -149,6 +230,10 @@ var AuthoringBridge = class {
     __publicField(this, "preview", null);
     __publicField(this, "previewGuide", null);
     __publicField(this, "active", false);
+    __publicField(this, "observer", null);
+    __publicField(this, "snapshotTimer", null);
+    __publicField(this, "snapshotDue", 0);
+    __publicField(this, "lastSnapshot", "");
   }
   isActive() {
     return this.active;
@@ -204,6 +289,7 @@ var AuthoringBridge = class {
         });
       }, HEARTBEAT_MS);
       this.post({ type: "guidely:authoring-ready", sessionId: this.info.id, url: window.location.href });
+      this.watchPage();
     } catch (err) {
       this.opts.onError(err);
     }
@@ -225,6 +311,32 @@ var AuthoringBridge = class {
     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));
   }
+  /** Sends a snapshot now and again whenever the page settles after DOM changes or navigation. */
+  watchPage() {
+    this.scheduleSnapshot();
+    if (typeof MutationObserver === "undefined") return;
+    this.observer = new MutationObserver(() => this.scheduleSnapshot());
+    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;
+    else clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = setTimeout(() => this.sendSnapshot(), Math.max(0, Math.min(SNAPSHOT_DEBOUNCE_MS, this.snapshotDue - now)));
+  }
+  sendSnapshot() {
+    if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = null;
+    if (!this.info || !this.active) return;
+    try {
+      const snapshot = captureSnapshot(document, this.opts.maskSelectors);
+      if (!snapshot || snapshot.html === this.lastSnapshot) return;
+      this.lastSnapshot = snapshot.html;
+      this.post({ type: "guidely:snapshot", sessionId: this.info.id, snapshot });
+    } catch (err) {
+      this.opts.onError(err);
+    }
+  }
   post(message) {
     if (!this.info) return;
     try {
@@ -292,6 +404,10 @@ var AuthoringBridge = class {
         case "guidely:stop-preview":
           this.stopPreview();
           break;
+        case "guidely:request-snapshot":
+          this.lastSnapshot = "";
+          this.sendSnapshot();
+          break;
         case "guidely:ping":
           this.post({ type: "guidely:pong", sessionId: this.info.id, url: window.location.href });
           break;
@@ -310,6 +426,10 @@ var AuthoringBridge = class {
     if (!this.active) return;
     this.active = false;
     this.stopPreview();
+    this.observer?.disconnect();
+    this.observer = null;
+    if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = null;
     if (this.heartbeat) clearInterval(this.heartbeat);
     this.heartbeat = null;
     this.session?.stop();
@@ -478,7 +598,7 @@ var Api = class {
   async request(method, path, options = {}) {
     const f = this.fetcher;
     if (!f) throw new Error("fetch is not available");
-    const headers = { "X-Guidely-Key": this.key, Accept: "application/json" };
+    const headers = { ...options.headers, "X-Guidely-Key": this.key, Accept: "application/json" };
     if (options.body !== void 0) headers["Content-Type"] = "application/json";
     if (options.etag) headers["If-None-Match"] = options.etag;
     const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
@@ -512,6 +632,33 @@ var Api = class {
   post(path, body, options) {
     return this.request("POST", path, { body, ...options });
   }
+  /**
+   * POST that may answer with server-sent events. Each event is passed to `onEvent`; a JSON answer is
+   * returned instead. No timeout: Scout replies can take a while and the server keeps the stream alive.
+   */
+  async stream(path, body, onEvent, headers = {}) {
+    const f = this.fetcher;
+    if (!f) throw new Error("fetch is not available");
+    const res = await f(this.url(path), {
+      method: "POST",
+      headers: { ...headers, "X-Guidely-Key": this.key, Accept: "text/event-stream, application/json", "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      credentials: "omit",
+      mode: "cors"
+    });
+    const type = res.headers?.get?.("content-type") ?? "";
+    if (!type.includes("text/event-stream") || !res.body) {
+      let data = null;
+      try {
+        data = await res.json();
+      } catch {
+        data = null;
+      }
+      return { status: res.status, ok: res.ok, data, etag: null };
+    }
+    await readEventStream(res.body, onEvent);
+    return { status: res.status, ok: res.ok, data: null, etag: null };
+  }
   /** `navigator.sendBeacon` when available (page unload); returns false when it could not be queued. */
   beacon(path, body) {
     try {
@@ -538,6 +685,143 @@ async function postWithRetry(api, path, body, attempts = 3, baseMs = 500) {
   }
   return null;
 }
+async function readEventStream(body, onEvent) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const dispatch = (raw) => {
+    let event = "message";
+    const data = [];
+    for (const line of raw.split("\n")) {
+      if (!line || line.startsWith(":")) continue;
+      const i = line.indexOf(":");
+      const field = i < 0 ? line : line.slice(0, i);
+      const value = i < 0 ? "" : line.slice(i + 1).replace(/^ /, "");
+      if (field === "event") event = value;
+      else if (field === "data") data.push(value);
+    }
+    if (!data.length) return;
+    try {
+      onEvent(event, JSON.parse(data.join("\n")));
+    } catch {
+    }
+  };
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (value) buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, "\n");
+    let sep;
+    while ((sep = buffer.indexOf("\n\n")) >= 0) {
+      dispatch(buffer.slice(0, sep));
+      buffer = buffer.slice(sep + 2);
+    }
+    if (done) break;
+  }
+  if (buffer.trim()) dispatch(buffer);
+}
+
+// src/messenger-api.ts
+var MAX_STORED = 50;
+var TOKEN_HEADER = "X-Guidely-Conversation";
+function storedConversations(store, projectId) {
+  const list = readJson(store, KEYS.conversations(projectId), []);
+  return Array.isArray(list) ? list.filter((c) => c && typeof c.id === "string" && typeof c.token === "string") : [];
+}
+function forgetConversations(store, projectId) {
+  store.remove(KEYS.conversations(projectId));
+}
+var HttpError = class extends Error {
+  constructor(status) {
+    super(`Request failed (${status})`);
+    __publicField(this, "status", status);
+  }
+};
+function createMessengerTransport(opts) {
+  const { api, store, projectId } = opts;
+  const tokenFor = (id) => storedConversations(store, projectId).find((c) => c.id === id)?.token ?? "";
+  const remember = (id, token) => {
+    const rest = storedConversations(store, projectId).filter((c) => c.id !== id);
+    writeJson(store, KEYS.conversations(projectId), [{ id, token }, ...rest].slice(0, MAX_STORED));
+  };
+  const forget = (id) => writeJson(store, KEYS.conversations(projectId), storedConversations(store, projectId).filter((c) => c.id !== id));
+  async function exchange(path, body, headers, h, onStarted) {
+    let finished = false;
+    const res = await api.stream(
+      path,
+      body,
+      (event, data) => {
+        if (event === "conversation") {
+          const d = data;
+          onStarted?.(d);
+          h.onConversation?.(d.conversation);
+          d.messages.forEach((m) => h.onMessage(m));
+        } else if (event === "message") h.onMessage(data);
+        else if (event === "delta") {
+          const d = data;
+          h.onDelta(d.messageId, d.text);
+        } else if (event === "done") {
+          const d = data;
+          finished = true;
+          h.onDone(d.message, d.conversation);
+        } else if (event === "error") h.onError(data?.message ?? "Something went wrong");
+      },
+      headers
+    );
+    if (!res.ok) throw new HttpError(res.status);
+    if (res.data) {
+      const d = res.data;
+      if ("token" in d) {
+        onStarted?.(d);
+        h.onConversation?.(d.conversation);
+      }
+      d.messages.forEach((m) => h.onMessage(m));
+      h.onDone(d.messages.at(-1) ?? null, d.conversation);
+    } else if (!finished) h.onError("The reply was interrupted");
+  }
+  return {
+    async listConversations() {
+      const tokens = storedConversations(store, projectId).map((c) => c.token);
+      if (!tokens.length) return [];
+      const res = await api.post("/conversations/lookup", { tokens });
+      if (!res.ok || !res.data) throw new HttpError(res.status);
+      const known = new Set(res.data.conversations.map((c) => c.id));
+      for (const c of storedConversations(store, projectId)) if (!known.has(c.id)) forget(c.id);
+      return res.data.conversations.map(({ token: _token, ...c }) => c);
+    },
+    async loadMessages(id, since) {
+      const res = await api.get(`/conversations/${encodeURIComponent(id)}/messages`, { params: { since: since ?? void 0 }, headers: { [TOKEN_HEADER]: tokenFor(id) } });
+      if (!res.ok || !res.data) throw new HttpError(res.status);
+      return res.data;
+    },
+    start(text, h) {
+      return exchange("/conversations", { anonymousId: opts.anonymousId(), userId: opts.userId(), message: text, pageUrl: opts.pageUrl() }, {}, h, (r) => remember(r.conversation.id, r.token));
+    },
+    send(id, text, h) {
+      return exchange(`/conversations/${encodeURIComponent(id)}/messages`, { message: text }, { [TOKEN_HEADER]: tokenFor(id) }, h);
+    },
+    async handoff(id) {
+      const res = await api.post(`/conversations/${encodeURIComponent(id)}/handoff`, {}, { headers: { [TOKEN_HEADER]: tokenFor(id) } });
+      if (!res.ok || !res.data) throw new HttpError(res.status);
+      return res.data;
+    },
+    async rate(id, rating) {
+      const res = await api.post(`/conversations/${encodeURIComponent(id)}/rating`, { rating }, { headers: { [TOKEN_HEADER]: tokenFor(id) } });
+      if (!res.ok) throw new HttpError(res.status);
+    },
+    async listArticles() {
+      const res = await api.get("/articles");
+      if (!res.ok || !res.data) throw new HttpError(res.status);
+      return res.data;
+    },
+    async getArticle(id) {
+      const res = await api.get(`/articles/${encodeURIComponent(id)}`);
+      return res.ok && res.data ? res.data.article : null;
+    },
+    async searchArticles(q) {
+      const res = await api.get("/resource-center/search", { params: { q } });
+      return res.ok && res.data ? res.data.articles : [];
+    }
+  };
+}
 
 // src/navigation.ts
 function watchNavigation(listener, debounceMs = 50) {
@@ -709,7 +993,7 @@ var EventQueue = class {
 
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.1";
 var DEFAULT_API_URL = "https://api.guidely.app";
 var PAGE_SCOPED = /* @__PURE__ */ new Set(["page_load", "url_match", "element_click", "element_visible", "delay"]);
 function isBrowser() {
@@ -745,6 +1029,9 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "widgets", /* @__PURE__ */ new Map());
     __publicField(this, "resourceCenter", null);
     __publicField(this, "resourceCenterScope", null);
+    __publicField(this, "messenger", null);
+    __publicField(this, "messengerScope", null);
+    __publicField(this, "messengerLoading", null);
     __publicField(this, "cleanups", []);
     __publicField(this, "timers", /* @__PURE__ */ new Set());
     __publicField(this, "visibilityObservers", /* @__PURE__ */ new Map());
@@ -753,6 +1040,8 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "lastUrl");
     __publicField(this, "authoring", null);
     __publicField(this, "lastAudiences", /* @__PURE__ */ new Set());
+    /** Set once the app calls identify()/reset(); bootstrap then leaves identity alone instead of re-identifying. */
+    __publicField(this, "identitySettled", false);
     __publicField(this, "customListeners", /* @__PURE__ */ new Map());
     __publicField(this, "eventBus", {
       on: (name, cb) => {
@@ -787,7 +1076,7 @@ var GuidelyClient = class _GuidelyClient {
     this.sessionStore = this.options.storage === "memory" ? this.store : createStorage("session");
     this.anonymousId = this.store.get(KEYS.anon) || "";
     if (!this.anonymousId) {
-      this.anonymousId = `anon_${(0, import_runtime5.randomId)(20)}`;
+      this.anonymousId = `anon_${(0, import_runtime6.randomId)(20)}`;
       this.store.set(KEYS.anon, this.anonymousId);
     }
     this.firstVisit = !this.store.get(KEYS.seen);
@@ -795,7 +1084,7 @@ var GuidelyClient = class _GuidelyClient {
     this.state = { ...emptyState(), ...readJson(this.store, KEYS.state(this.options.projectId), {}) };
     this.user = readJson(this.store, KEYS.user(this.options.projectId), null);
     const session = readJson(this.sessionStore, KEYS.session, null);
-    this.session = session && session.id ? session : { id: `s_${(0, import_runtime5.randomId)(16)}`, startedAt: nowIso(), shownGuides: [], events: [] };
+    this.session = session && session.id ? session : { id: `s_${(0, import_runtime6.randomId)(16)}`, startedAt: nowIso(), shownGuides: [], events: [] };
     this.persistSession();
     this.lastUrl = location.href;
     this.lastAudiences = new Set(this.state.audienceIds);
@@ -836,8 +1125,10 @@ var GuidelyClient = class _GuidelyClient {
       await this.fetchConfig();
       if (this.destroyed) return;
       this.wireListeners();
-      if (this.options.user) await this.identify(this.options.user.id, this.options.user.traits, this.options.user.account);
-      else if (this.user?.id) await this.identify(this.user.id, this.user.traits, this.user.account);
+      if (!this.identitySettled) {
+        if (this.options.user) await this.identify(this.options.user.id, this.options.user.traits, this.options.user.account);
+        else if (this.user?.id) await this.identify(this.user.id, this.user.traits, this.user.account);
+      }
       if (this.destroyed) return;
       this.isReady = true;
       if (this.config) this.emitter.emit("ready", this.config);
@@ -929,6 +1220,7 @@ var GuidelyClient = class _GuidelyClient {
     this.resourceCenter?.destroy();
     this.resourceCenterScope?.destroy();
     this.resourceCenter = null;
+    this.destroyMessenger();
     this.visibilityObservers.forEach((stop) => stop());
     this.visibilityObservers.clear();
     this.timers.forEach((t) => clearTimeout(t));
@@ -948,9 +1240,10 @@ var GuidelyClient = class _GuidelyClient {
   /** Identifies the end user and loads server-held state (audiences, guide history, checklist progress). */
   async identify(userId, traits, account) {
     if (this.destroyed) return;
+    this.identitySettled = true;
     this.user = { id: String(userId), traits: { ...this.user?.id === String(userId) ? this.user.traits : {}, ...traits || {} }, account: account ?? (this.user?.id === String(userId) ? this.user.account : void 0) };
     writeJson(this.store, KEYS.user(this.options.projectId), this.user);
-    this.enqueue("identify", { properties: { traits: (0, import_runtime5.sanitizeProperties)(this.user.traits) } });
+    this.enqueue("identify", { properties: { traits: (0, import_runtime6.sanitizeProperties)(this.user.traits) } });
     await this.syncIdentify();
     this.emitter.emit("identify", { userId: this.user.id, anonymousId: this.anonymousId });
     if (this.isReady) this.evaluate("identify");
@@ -1013,20 +1306,23 @@ var GuidelyClient = class _GuidelyClient {
   }
   /** Forgets the user: new anonymous id, cleared local guide/checklist state, triggers re-evaluated. */
   reset() {
+    this.identitySettled = true;
     this.stopGuide();
     this.user = null;
     this.store.remove(KEYS.user(this.options.projectId));
-    this.anonymousId = `anon_${(0, import_runtime5.randomId)(20)}`;
+    this.anonymousId = `anon_${(0, import_runtime6.randomId)(20)}`;
     this.store.set(KEYS.anon, this.anonymousId);
     this.state = emptyState();
     this.persistState();
-    this.session = { id: `s_${(0, import_runtime5.randomId)(16)}`, startedAt: nowIso(), shownGuides: [], events: [] };
+    this.session = { id: `s_${(0, import_runtime6.randomId)(16)}`, startedAt: nowIso(), shownGuides: [], events: [] };
     this.persistSession();
     this.sessionStore.remove(KEYS.active);
     this.lastAudiences = /* @__PURE__ */ new Set();
     this.firedDelays.clear();
     this.widgets.forEach((w) => w.destroy());
     this.widgets.clear();
+    forgetConversations(this.store, this.options.projectId);
+    this.destroyMessenger();
     this.emitter.emit("identify", { userId: null, anonymousId: this.anonymousId });
     if (this.isReady) {
       this.renderPersistentWidgets();
@@ -1051,7 +1347,7 @@ var GuidelyClient = class _GuidelyClient {
   enqueue(name, extra = {}) {
     if (this.consent === "denied" || !this.options.analytics) return null;
     const event = {
-      eventId: (0, import_runtime5.randomId)(24),
+      eventId: (0, import_runtime6.randomId)(24),
       name,
       occurredAt: nowIso(),
       anonymousId: this.anonymousId,
@@ -1061,7 +1357,7 @@ var GuidelyClient = class _GuidelyClient {
       url: this.collectUrls() ? location.href : void 0,
       ...extra
     };
-    if (extra.properties) event.properties = (0, import_runtime5.sanitizeProperties)(extra.properties);
+    if (extra.properties) event.properties = (0, import_runtime6.sanitizeProperties)(extra.properties);
     this.queue.enqueue(event);
     this.emitter.emit("track", event);
     return event;
@@ -1145,7 +1441,7 @@ var GuidelyClient = class _GuidelyClient {
     if (!isWithinSchedule(guide)) return false;
     if (guide.kind === "survey" && (this.state.surveysSubmitted.includes(guide.id) || this.state.surveysSubmitted.includes(guide.key))) return false;
     ctx.rolloutSalt = guide.id;
-    return (0, import_runtime5.evaluateRules)(c.targeting, ctx);
+    return (0, import_runtime6.evaluateRules)(c.targeting, ctx);
   }
   isEligible(guide, ctx, url) {
     if (!this.isTargeted(guide, ctx, url)) return false;
@@ -1432,7 +1728,7 @@ var GuidelyClient = class _GuidelyClient {
       title: guide.name,
       onDismiss: () => finish(this.state.surveysSubmitted.includes(guide.id) ? "submitted" : "dismissed"),
       onSubmit: (answers) => {
-        const responseId = (0, import_runtime5.randomId)(24);
+        const responseId = (0, import_runtime6.randomId)(24);
         this.state.surveysSubmitted.push(guide.id);
         this.persistState();
         this.recordEnd(guide, "completed");
@@ -1463,6 +1759,16 @@ var GuidelyClient = class _GuidelyClient {
   renderPersistentWidgets() {
     if (!this.config) return;
     const rc = this.config.resourceCenter;
+    if (this.config.messenger?.enabled) {
+      if (this.resourceCenter) {
+        this.resourceCenter.destroy();
+        this.resourceCenterScope?.destroy();
+        this.resourceCenter = null;
+      }
+      if (!this.messenger) void this.loadMessenger();
+      return;
+    }
+    this.destroyMessenger();
     if (rc && rc.enabled && !this.resourceCenter) {
       const scope = (0, import_guide_runtime3.createScope)(this.theme());
       this.resourceCenterScope = scope;
@@ -1471,6 +1777,7 @@ var GuidelyClient = class _GuidelyClient {
         config: rc,
         guides: this.config.guides.map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind })),
         search: (q) => this.searchResourceCenter(q),
+        loadArticle: (id) => this.loadArticle(id),
         onStartGuide: (id) => this.startGuide(id),
         onOpenChecklist: (id) => this.openChecklist(id),
         onArticleView: (a) => this.enqueue("article_viewed", { properties: { articleId: a.id, slug: a.slug } }),
@@ -1493,6 +1800,60 @@ var GuidelyClient = class _GuidelyClient {
     if (!guide || !guide.config.steps.some((s) => s.id === saved.stepId)) return;
     this.showFlow(guide, saved.manual ?? false, saved.stepId);
   }
+  /** Loads the messenger widget on demand (it is a separate chunk) and renders it. */
+  loadMessenger() {
+    if (this.messenger) return Promise.resolve(this.messenger);
+    if (this.messengerLoading) return this.messengerLoading;
+    this.messengerLoading = import("@guidelytech/guide-runtime/messenger").then(({ renderMessenger }) => {
+      const cfg = this.config?.messenger;
+      if (this.destroyed || !this.config || !cfg?.enabled || this.messenger) return this.messenger;
+      const scope = (0, import_guide_runtime3.createScope)(this.theme());
+      this.messengerScope = scope;
+      this.messenger = renderMessenger({
+        scope: scope.el,
+        config: cfg,
+        api: createMessengerTransport({
+          api: this.api,
+          store: this.store,
+          projectId: this.options.projectId,
+          anonymousId: () => this.anonymousId,
+          userId: () => this.user?.id || null,
+          pageUrl: () => this.collectUrls() ? location.href : void 0
+        }),
+        resourceCenter: this.config.resourceCenter,
+        guides: this.config.guides.map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind })),
+        onStartGuide: (idOrKey) => this.startGuide(idOrKey),
+        onOpenChecklist: (id) => this.openChecklist(id),
+        onArticleView: (a) => this.enqueue("article_viewed", { properties: { articleId: a.id, slug: a.slug } }),
+        onOpen: () => {
+          this.enqueue("messenger_opened");
+          this.emitter.emit("messenger:open");
+        },
+        onMessage: (message, conversation) => this.emitter.emit("conversation:message", { message, conversation })
+      });
+      return this.messenger;
+    }).catch((err) => {
+      this.reportError(err);
+      return null;
+    }).finally(() => {
+      this.messengerLoading = null;
+    });
+    return this.messengerLoading;
+  }
+  destroyMessenger() {
+    this.messenger?.destroy();
+    this.messengerScope?.destroy();
+    this.messenger = null;
+    this.messengerScope = null;
+  }
+  async loadArticle(id) {
+    try {
+      const res = await this.api.get(`/articles/${encodeURIComponent(id)}`);
+      return res.ok && res.data ? res.data.article : null;
+    } catch {
+      return null;
+    }
+  }
   async searchResourceCenter(q) {
     try {
       const res = await this.api.get("/resource-center/search", { params: { q } });
@@ -1647,12 +2008,27 @@ var GuidelyClient = class _GuidelyClient {
     return !!this.state.guides[guide?.id ?? idOrKey]?.completedAt;
   }
   openResourceCenter() {
+    if (this.config?.messenger?.enabled) return this.openMessenger("help");
     if (!this.resourceCenter) this.renderPersistentWidgets();
     this.resourceCenter?.open();
   }
   closeResourceCenter() {
+    if (this.messenger) return this.closeMessenger();
     this.resourceCenter?.close();
   }
+  /** Opens the Scout messenger (when enabled for the project), optionally on a tab. */
+  openMessenger(tab) {
+    if (!this.config?.messenger?.enabled) return;
+    void this.loadMessenger().then((m) => m?.open(tab));
+  }
+  closeMessenger() {
+    this.messenger?.close();
+  }
+  /** Opens a new messenger conversation, optionally pre-filling the message. */
+  showNewMessage(text) {
+    if (!this.config?.messenger?.enabled) return;
+    void this.loadMessenger().then((m) => m?.showNewMessage(text));
+  }
   on(event, cb) {
     return this.emitter.on(event, cb);
   }
@@ -1764,7 +2140,7 @@ var Guidely = {
   init: (options) => GuidelyClient.init(options),
   get: () => GuidelyClient.get(),
   createGuidely,
-  version: "0.1.0"
+  version: SDK_VERSION
 };
 var index_default = Guidely;
 // Annotate the CommonJS export names for ESM import in node:
@@ -1780,6 +2156,7 @@ var index_default = Guidely;
   SDK_VERSION,
   areMutuallyExclusive,
   buildContext,
+  captureSnapshot,
   createGuidely,
   createStorage,
   detectDevice,