@guidelytech/sdk-core 0.5.0 → 0.6.1

package/dist/index.cjs

@@ -33,6 +33,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 var index_exports = {};
 __export(index_exports, {
   AUTHORING_PARAM: () => AUTHORING_PARAM,
+  CAPTURE_PARAM: () => import_runtime2.CAPTURE_PARAM,
   DEFAULT_API_URL: () => DEFAULT_API_URL,
   EventQueue: () => EventQueue,
   Guidely: () => Guidely,
@@ -56,9 +57,9 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_runtime11 = require("@guidelytech/shared/runtime");
-var import_guide_runtime3 = require("@guidelytech/guide-runtime");
+var import_runtime13 = require("@guidelytech/shared/runtime");
 var import_guide_runtime4 = require("@guidelytech/guide-runtime");
+var import_guide_runtime5 = require("@guidelytech/guide-runtime");
 
 // src/authoring.ts
 var import_guide_runtime = require("@guidelytech/guide-runtime");
@@ -207,8 +208,13 @@ var KEYS = {
   session: "guidely:session",
   active: "guidely:active",
   authoring: "guidely:authoring",
+  /** How-to capture session marker ({ token, … }) and its not-yet-uploaded steps. */
+  capture: "guidely:capture",
+  capturePending: "guidely:capture:pending",
   /** Messenger conversations this browser can read: [{ id, token }]. */
-  conversations: (key) => `guidely:conversations:${key}`
+  conversations: (key) => `guidely:conversations:${key}`,
+  /** Announcement ids opened in the messenger's News tab. */
+  newsSeen: (key) => `guidely:news:${key}`
 };
 
 // src/authoring.ts
@@ -440,6 +446,43 @@ var AuthoringBridge = class {
   }
 };
 
+// src/capture-token.ts
+var import_runtime2 = require("@guidelytech/shared/runtime");
+function takeCaptureToken(sessionStore) {
+  if (typeof window === "undefined") return null;
+  let token = null;
+  let authoringLink = false;
+  try {
+    const url = new URL(window.location.href);
+    token = url.searchParams.get(import_runtime2.CAPTURE_PARAM);
+    authoringLink = url.searchParams.has(AUTHORING_PARAM);
+    if (token) {
+      url.searchParams.delete(import_runtime2.CAPTURE_PARAM);
+      window.history.replaceState(window.history.state, "", url.toString());
+    }
+  } catch {
+    token = null;
+  }
+  const saved = readJson(sessionStore, KEYS.capture, null);
+  let marker = null;
+  if (token) marker = saved?.token === token ? saved : { token };
+  else if (saved?.token && !authoringLink) marker = saved;
+  if (!marker) {
+    if (saved) {
+      sessionStore.remove(KEYS.capture);
+      sessionStore.remove(KEYS.capturePending);
+    }
+    return null;
+  }
+  if (token && saved?.token !== token) sessionStore.remove(KEYS.capturePending);
+  writeJson(sessionStore, KEYS.capture, marker);
+  sessionStore.remove(KEYS.authoring);
+  return marker;
+}
+
+// src/load-capture.ts
+var loadCapture = async () => (await import("./capture.cjs")).capture;
+
 // src/autocapture.ts
 var import_guide_runtime2 = require("@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]";
@@ -701,7 +744,7 @@ var HeatmapBuffer = class {
 };
 
 // src/errors.ts
-var import_runtime4 = require("@guidelytech/shared/runtime");
+var import_runtime5 = require("@guidelytech/shared/runtime");
 var MAX_FRAMES_BYTES = 6e3;
 function fitFrames(frames) {
   const out = frames.slice(0, 30);
@@ -722,7 +765,7 @@ function exceptionFromError(error, source, handled, fallbackType = "Error") {
   return {
     type: isError && e.name || fallbackType,
     message: (isError ? e.message : describe(error)).slice(0, 1e3),
-    frames: isError ? fitFrames((0, import_runtime4.parseStack)(e.stack)) : [],
+    frames: isError ? fitFrames((0, import_runtime5.parseStack)(e.stack)) : [],
     source,
     handled
   };
@@ -869,7 +912,8 @@ var Api = class {
     const f = this.fetcher;
     if (!f) throw new Error("fetch is not available");
     const headers = { ...options.headers, "X-Guidely-Key": this.key, Accept: "application/json" };
-    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    const form = typeof FormData !== "undefined" && options.body instanceof FormData;
+    if (options.body !== void 0 && !form) headers["Content-Type"] = "application/json";
     if (options.etag) headers["If-None-Match"] = options.etag;
     const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
     const timer = ac ? setTimeout(() => ac.abort(), options.timeoutMs ?? 1e4) : null;
@@ -877,7 +921,7 @@ var Api = class {
       const res = await f(this.url(path, options.params), {
         method,
         headers,
-        body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+        body: options.body === void 0 ? void 0 : form ? options.body : JSON.stringify(options.body),
         keepalive: options.keepalive,
         signal: ac?.signal,
         credentials: "omit",
@@ -902,6 +946,10 @@ var Api = class {
   post(path, body, options) {
     return this.request("POST", path, { body, ...options });
   }
+  /** Multipart POST (file uploads). No Content-Type header: the browser adds it with the boundary. */
+  postForm(path, form, options) {
+    return this.request("POST", path, { body: form, ...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.
@@ -944,10 +992,10 @@ var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function backoffMs(attempt, baseMs = 1e3, maxMs = 3e4) {
   return Math.min(maxMs, baseMs * 2 ** Math.max(0, attempt));
 }
-async function postWithRetry(api, path, body, attempts = 3, baseMs = 500) {
+async function withRetry(send, attempts = 3, baseMs = 500) {
   for (let i = 0; i < attempts; i++) {
     try {
-      const res = await api.post(path, body);
+      const res = await send();
       if (res.ok || res.status >= 400 && res.status < 500 && res.status !== 429) return res;
     } catch {
     }
@@ -955,6 +1003,9 @@ async function postWithRetry(api, path, body, attempts = 3, baseMs = 500) {
   }
   return null;
 }
+function postWithRetry(api, path, body, attempts = 3, baseMs = 500) {
+  return withRetry(() => api.post(path, body), attempts, baseMs);
+}
 async function readEventStream(body, onEvent) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
@@ -992,6 +1043,15 @@ async function readEventStream(body, onEvent) {
 // src/messenger-api.ts
 var MAX_STORED = 50;
 var TOKEN_HEADER = "X-Guidely-Conversation";
+function pagePath(url) {
+  if (!url) return void 0;
+  try {
+    const u = new URL(url);
+    return (u.pathname + (/^#!?\//.test(u.hash) ? u.hash.split("?")[0] : "")).slice(0, 2e3);
+  } catch {
+    return void 0;
+  }
+}
 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") : [];
@@ -1066,7 +1126,7 @@ function createMessengerTransport(opts) {
       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);
+      return exchange(`/conversations/${encodeURIComponent(id)}/messages`, { message: text, pageUrl: opts.pageUrl() }, { [TOKEN_HEADER]: tokenFor(id) }, h);
     },
     async handoff(id) {
       const res = await api.post(`/conversations/${encodeURIComponent(id)}/handoff`, {}, { headers: { [TOKEN_HEADER]: tokenFor(id) } });
@@ -1086,13 +1146,98 @@ function createMessengerTransport(opts) {
       const res = await api.get(`/articles/${encodeURIComponent(id)}`);
       return res.ok && res.data ? res.data.article : null;
     },
+    async pageContent(path) {
+      const res = await api.post("/messenger/page", { anonymousId: opts.anonymousId(), userId: opts.userId(), path: path.split(/[?#]/)[0] || "/" });
+      if (!res.ok || !res.data) throw new HttpError(res.status);
+      return res.data;
+    },
     async searchArticles(q) {
       const res = await api.get("/resource-center/search", { params: { q } });
       return res.ok && res.data ? res.data.articles : [];
+    },
+    async listHowTos() {
+      const res = await api.get("/how-tos", { params: { url: pagePath(opts.pageUrl()) } });
+      if (!res.ok || !res.data) throw new HttpError(res.status);
+      return res.data;
+    },
+    async getHowTo(id) {
+      const res = await api.get(`/how-tos/${encodeURIComponent(id)}`);
+      return res.ok && res.data ? res.data.howTo : null;
     }
   };
 }
 
+// src/messenger-visitor.ts
+var import_runtime10 = require("@guidelytech/shared/runtime");
+var import_guide_runtime3 = require("@guidelytech/guide-runtime");
+var PAGE_GUIDE_KINDS = /* @__PURE__ */ new Set(["flow", "tooltip", "modal"]);
+var CATCH_ALL = /* @__PURE__ */ new Set(["", "*", "**", "/*", "/**", "/"]);
+var RESUME_WITHIN_MS = 14 * 864e5;
+var NEWS_WITHIN_MS = 90 * 864e5;
+var MAX_NEWS = 10;
+function pathOf(url) {
+  try {
+    return new URL(url, "http://x.invalid").pathname || "/";
+  } catch {
+    return null;
+  }
+}
+function targetsPage(guide, url) {
+  const c = guide.config;
+  const checks = [...c.urlPatterns, ...c.trigger.urlPattern ? [c.trigger.urlPattern] : [], ...c.trigger.type === "url_match" && c.trigger.value ? [c.trigger.value] : [], ...c.steps[0]?.url ? [c.steps[0].url] : []];
+  const specific = checks.filter((p) => !CATCH_ALL.has(p.trim()));
+  return specific.length > 0 && checks.every((p) => (0, import_guide_runtime3.urlMatches)(p, url));
+}
+function plainText(html, max = 280) {
+  const text = html.replace(/<(br|\/p|\/div|\/li|\/h[1-6])\s*\/?>/gi, " ").replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&").replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}\u2026` : text;
+}
+function buildMessengerVisitor(input) {
+  const now = input.now ?? Date.now();
+  const { guides, state } = input;
+  const done = (g) => !!state.guides[g.id]?.completedAt;
+  const pageGuides = guides.filter((g) => PAGE_GUIDE_KINDS.has(g.kind) && g.config.steps.length > 0 && !done(g) && targetsPage(g, input.url) && input.isTargeted(g)).slice(0, 3).map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind }));
+  let resumeGuide = null;
+  let resumeAt = 0;
+  for (const g of guides) {
+    const s = state.guides[g.id];
+    if (g.kind !== "flow" || !s?.lastStepId || s.completedAt || g.config.steps.length < 2) continue;
+    const at = Date.parse(s.lastShownAt ?? "");
+    if (!Number.isFinite(at) || now - at > RESUME_WITHIN_MS || at <= resumeAt) continue;
+    const stepIndex = g.config.steps.findIndex((st) => st.id === s.lastStepId);
+    if (stepIndex < 1 || !isWithinSchedule(g)) continue;
+    resumeGuide = { id: g.id, name: g.name, stepId: s.lastStepId, stepIndex, stepCount: g.config.steps.length };
+    resumeAt = at;
+  }
+  let checklist = null;
+  for (const g of guides) {
+    const tasks = g.config.checklist?.tasks;
+    if (g.kind !== "checklist" || !tasks?.length) continue;
+    const p = state.checklists[g.id];
+    if (p?.completedAt || p?.dismissedAt || !input.isAudienceTargeted(g)) continue;
+    const completed = new Set(p?.completedTaskIds ?? []);
+    const doneCount = tasks.filter((t) => completed.has(t.id)).length;
+    if (doneCount >= tasks.length) continue;
+    checklist = { id: g.id, name: g.name, done: doneCount, total: tasks.length, nextTask: tasks.find((t) => !completed.has(t.id))?.title ?? null };
+    break;
+  }
+  const seen = new Set(input.newsSeen);
+  const news = guides.filter((g) => g.kind === "announcement" && g.config.steps.length > 0 && now - Date.parse(g.publishedAt) <= NEWS_WITHIN_MS && input.isAudienceTargeted(g)).sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)).slice(0, MAX_NEWS).map((g) => {
+    const step = g.config.steps[0];
+    return {
+      id: g.id,
+      key: g.key,
+      title: step.title || g.name,
+      body: plainText(step.body ?? ""),
+      imageUrl: step.imageUrl || null,
+      publishedAt: g.publishedAt,
+      // Read once opened in the News tab, or once the announcement itself was shown.
+      unread: !seen.has(g.id) && !(state.guides[g.id]?.impressions ?? 0)
+    };
+  });
+  return { firstName: (0, import_runtime10.firstNameFromTraits)(input.traits), path: pathOf(input.url), pageGuides, resumeGuide, checklist, news };
+}
+
 // src/navigation.ts
 function watchNavigation(listener, debounceMs = 50) {
   if (typeof window === "undefined") return () => {
@@ -1311,7 +1456,7 @@ var loadRecorder = async () => (await import("./recorder.cjs")).recorder;
 
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.6.1";
 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;
@@ -1326,7 +1471,7 @@ function emptyState() {
   return { guides: {}, checklists: {}, surveysSubmitted: [], audienceIds: [] };
 }
 function newSession(now = Date.now()) {
-  return { id: `s_${(0, import_runtime11.randomId)(16)}`, startedAt: new Date(now).toISOString(), shownGuides: [], events: [], lastActivityAt: now };
+  return { id: `s_${(0, import_runtime13.randomId)(16)}`, startedAt: new Date(now).toISOString(), shownGuides: [], events: [], lastActivityAt: now };
 }
 var GuidelyClient = class _GuidelyClient {
   constructor(options) {
@@ -1362,6 +1507,9 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "firstVisit");
     __publicField(this, "lastUrl");
     __publicField(this, "authoring", null);
+    __publicField(this, "capture", null);
+    /** A capture token was found and the (lazily loaded) capture bridge is starting. */
+    __publicField(this, "captureStarting", false);
     __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);
@@ -1412,7 +1560,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_runtime11.randomId)(20)}`;
+      this.anonymousId = `anon_${(0, import_runtime13.randomId)(20)}`;
       this.store.set(KEYS.anon, this.anonymousId);
     }
     this.firstVisit = !this.store.get(KEYS.seen);
@@ -1470,10 +1618,11 @@ var GuidelyClient = class _GuidelyClient {
       this.isReady = true;
       if (this.config) this.emitter.emit("ready", this.config);
       this.resolveReady?.();
+      const capturing = !this.options.disableAuthoring && this.maybeStartCapture();
       this.renderPersistentWidgets();
       this.resumeActiveGuide();
       this.evaluate("ready");
-      if (!this.options.disableAuthoring) this.maybeStartAuthoring();
+      if (!this.options.disableAuthoring && !capturing) this.maybeStartAuthoring();
       this.pageTracker.start(location.href);
       this.touchSession();
       this.syncCapture();
@@ -1571,7 +1720,7 @@ var GuidelyClient = class _GuidelyClient {
     const refresh = setInterval(() => void this.refresh(), this.options.configRefreshMs);
     this.cleanups.push(() => clearInterval(refresh));
     const poll = setInterval(() => {
-      if (!this.isReady || !this.config || this.authoring?.isActive() || doc.visibilityState === "hidden") return;
+      if (!this.isReady || !this.config || this.editing() || doc.visibilityState === "hidden") return;
       const url = location.href;
       const ctx = this.getContext();
       for (const guide of this.config.guides) {
@@ -1629,12 +1778,14 @@ var GuidelyClient = class _GuidelyClient {
     this.cleanups.splice(0).forEach((fn) => fn());
     this.authoring?.stop();
     this.authoring = null;
+    this.capture?.destroy();
+    this.capture = null;
     this.replay?.destroy();
     this.replay = null;
     this.queue.flushSync();
     this.queue.destroy();
     this.emitter.clear();
-    (0, import_guide_runtime3.destroyHost)();
+    (0, import_guide_runtime4.destroyHost)();
     if (current === this) current = null;
   }
   // ---------------------------------------------------------------------------
@@ -1646,7 +1797,7 @@ var GuidelyClient = class _GuidelyClient {
     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_runtime11.sanitizeProperties)(this.user.traits) } });
+    this.enqueue("identify", { properties: { traits: (0, import_runtime13.sanitizeProperties)(this.user.traits) } });
     await this.syncIdentify();
     this.emitter.emit("identify", { userId: this.user.id, anonymousId: this.anonymousId });
     if (this.isReady) this.evaluate("identify");
@@ -1661,6 +1812,7 @@ var GuidelyClient = class _GuidelyClient {
     for (const [id, s] of Object.entries(data.guideState || {})) {
       const local = guides[id];
       guides[id] = {
+        ...local,
         impressions: Math.max(local?.impressions ?? 0, s.impressions ?? 0),
         completedAt: local?.completedAt ?? s.completedAt ?? null,
         dismissedAt: local?.dismissedAt ?? s.dismissedAt ?? null,
@@ -1689,6 +1841,7 @@ var GuidelyClient = class _GuidelyClient {
       const g = this.findGuide(id);
       if (w.checklist && g) w.checklist.setProgress(this.getChecklistProgress(g.id));
     });
+    this.messenger?.refresh();
   }
   /** Sets or replaces the account (company/organisation) for the current user. */
   async setAccount(account) {
@@ -1713,7 +1866,7 @@ var GuidelyClient = class _GuidelyClient {
     this.stopGuide();
     this.user = null;
     this.store.remove(KEYS.user(this.options.projectId));
-    this.anonymousId = `anon_${(0, import_runtime11.randomId)(20)}`;
+    this.anonymousId = `anon_${(0, import_runtime13.randomId)(20)}`;
     this.store.set(KEYS.anon, this.anonymousId);
     this.state = emptyState();
     this.persistState();
@@ -1755,7 +1908,7 @@ var GuidelyClient = class _GuidelyClient {
     if (this.consent === "denied" || !this.options.analytics) return null;
     if (name !== "page_leave" && name !== "heatmap") this.touchSession();
     const event = {
-      eventId: (0, import_runtime11.randomId)(24),
+      eventId: (0, import_runtime13.randomId)(24),
       name,
       occurredAt: nowIso(),
       anonymousId: this.anonymousId,
@@ -1765,7 +1918,7 @@ var GuidelyClient = class _GuidelyClient {
       url: this.collectUrls() ? location.href : void 0,
       ...extra
     };
-    if (extra.properties) event.properties = (0, import_runtime11.sanitizeProperties)(extra.properties);
+    if (extra.properties) event.properties = (0, import_runtime13.sanitizeProperties)(extra.properties);
     this.queue.enqueue(event);
     this.replay?.addCustomEvent("guidely", { name, customName: event.customName, guideId: event.guideId });
     this.emitter.emit("track", event);
@@ -1810,16 +1963,17 @@ var GuidelyClient = class _GuidelyClient {
       const st = this.active.controller.getState();
       if (st.status === "running" && !this.active.manual) {
         const g = this.active.guide;
-        if (g.config.urlPatterns.length && !g.config.urlPatterns.some((p) => (0, import_guide_runtime3.urlMatches)(p, url))) this.active.controller.destroy();
+        if (g.config.urlPatterns.length && !g.config.urlPatterns.some((p) => (0, import_guide_runtime4.urlMatches)(p, url))) this.active.controller.destroy();
       }
     }
     this.widgets.forEach((w, id) => {
       if (!w.controller || w.manual) return;
       const g = this.findGuide(id);
-      if (g?.config.urlPatterns.length && !g.config.urlPatterns.some((p) => (0, import_guide_runtime3.urlMatches)(p, url))) w.controller.destroy();
+      if (g?.config.urlPatterns.length && !g.config.urlPatterns.some((p) => (0, import_guide_runtime4.urlMatches)(p, url))) w.controller.destroy();
     });
     this.firedDelays.clear();
     if (this.isReady) this.evaluate("navigation");
+    if (changed) this.messenger?.refresh();
     if (changed) void this.queue.flush();
   }
   handleDocumentClick(e) {
@@ -1850,9 +2004,13 @@ var GuidelyClient = class _GuidelyClient {
     if (this.replay?.activeSessionId) this.replay.stop();
     this.syncReplay();
   }
-  /** Autocapture, error tracking and replay need analytics on, consent granted and no authoring session. */
+  /** Autocapture, error tracking and replay need analytics on, consent granted and no authoring or how-to capture session. */
   captureAllowed() {
-    return !this.destroyed && this.analyticsEnabled() && !this.authoring?.isActive();
+    return !this.destroyed && this.analyticsEnabled() && !this.editing();
+  }
+  /** Authoring or how-to capture is running: no guides, widgets, replay or autocapture. */
+  editing() {
+    return !!this.authoring?.isActive() || this.captureStarting || !!this.capture?.isActive();
   }
   /** A capability is on when the project enables it (absent on old servers → off) and no option turns it off. */
   autocaptureOn(key) {
@@ -1862,7 +2020,7 @@ var GuidelyClient = class _GuidelyClient {
   /** Page views on SPA navigation predate autocapture: only an explicit opt-out stops them. */
   pageviewsOn() {
     const o = this.options.autocapture;
-    return this.config?.settings?.autocapture?.pageviews !== false && o !== false && !(typeof o === "object" && o.pageviews === false) && !this.authoring?.isActive();
+    return this.config?.settings?.autocapture?.pageviews !== false && o !== false && !(typeof o === "object" && o.pageviews === false) && !this.editing();
   }
   trackPageView(url) {
     if (url === this.pageViewUrl || !this.pageviewsOn()) return;
@@ -1872,7 +2030,7 @@ var GuidelyClient = class _GuidelyClient {
     const device = detectDevice(navigator.userAgent, window.innerWidth);
     const props = { deviceType: device.type, browser: device.browser, os: device.os, screenWidth: window.screen?.width, viewportWidth: window.innerWidth };
     if (collect) {
-      props.path = pathOf(url);
+      props.path = pathOf2(url);
       props.title = (document.title || "").slice(0, 200);
       const ref = !this.session.pageViews ? externalReferrer() : void 0;
       if (ref) props.referrer = ref;
@@ -1889,7 +2047,7 @@ var GuidelyClient = class _GuidelyClient {
     if (!this.pageLeft && this.autocaptureOn("pageLeave")) {
       const info = t.leave();
       const collect = this.collectUrls();
-      this.enqueue("page_leave", { url: collect ? info.url : void 0, properties: { ...collect ? { path: pathOf(info.url) } : {}, durationMs: info.durationMs, scrollDepth: info.scrollDepth } });
+      this.enqueue("page_leave", { url: collect ? info.url : void 0, properties: { ...collect ? { path: pathOf2(info.url) } : {}, durationMs: info.durationMs, scrollDepth: info.scrollDepth } });
     }
     if (nextUrl !== null) {
       t.start(nextUrl);
@@ -1926,7 +2084,7 @@ var GuidelyClient = class _GuidelyClient {
     if (!batch || !this.captureAllowed()) return;
     const collect = this.collectUrls();
     const de = document.documentElement;
-    const properties = { path: collect ? pathOf(batch.url) : void 0, viewportWidth: window.innerWidth, viewportHeight: window.innerHeight, pageHeight: Math.max(de.scrollHeight, document.body?.scrollHeight || 0), points: batch.points };
+    const properties = { path: collect ? pathOf2(batch.url) : void 0, viewportWidth: window.innerWidth, viewportHeight: window.innerHeight, pageHeight: Math.max(de.scrollHeight, document.body?.scrollHeight || 0), points: batch.points };
     if (!collect) delete properties.path;
     this.enqueue("heatmap", { url: collect ? batch.url : void 0, properties });
   }
@@ -2005,7 +2163,7 @@ var GuidelyClient = class _GuidelyClient {
   syncReplay() {
     const cfg = this.isReady && this.captureAllowed() ? this.replayConfig() : null;
     if (cfg && this.session.replay === void 0) {
-      this.session.replay = (0, import_runtime11.rolloutBucket)(this.session.id, "replay") < cfg.sampleRate;
+      this.session.replay = (0, import_runtime13.rolloutBucket)(this.session.id, "replay") < cfg.sampleRate;
       this.persistSession();
     }
     if (!cfg || !this.session.replay) {
@@ -2100,12 +2258,12 @@ var GuidelyClient = class _GuidelyClient {
   }
   isTargeted(guide, ctx, url) {
     const c = guide.config;
-    if (c.urlPatterns.length && !c.urlPatterns.some((p) => (0, import_guide_runtime3.urlMatches)(p, url))) return false;
-    if (c.trigger.urlPattern && !(0, import_guide_runtime3.urlMatches)(c.trigger.urlPattern, url)) return false;
+    if (c.urlPatterns.length && !c.urlPatterns.some((p) => (0, import_guide_runtime4.urlMatches)(p, url))) return false;
+    if (c.trigger.urlPattern && !(0, import_guide_runtime4.urlMatches)(c.trigger.urlPattern, url)) return false;
     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_runtime11.evaluateRules)(c.targeting, ctx);
+    return (0, import_runtime13.evaluateRules)(c.targeting, ctx);
   }
   isEligible(guide, ctx, url) {
     if (!this.isTargeted(guide, ctx, url)) return false;
@@ -2123,7 +2281,7 @@ 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") && (0, import_guide_runtime3.urlMatches)(t.value, location.href);
+        return (reason === "ready" || reason === "navigation" || reason === "identify") && (0, import_guide_runtime4.urlMatches)(t.value, location.href);
       case "event":
         return reason === "event" && !!t.value && detail.eventName === t.value;
       case "element_click":
@@ -2147,7 +2305,7 @@ var GuidelyClient = class _GuidelyClient {
     }
   }
   evaluate(reason, detail = {}) {
-    if (!this.config || this.destroyed || this.authoring?.isActive()) return;
+    if (!this.config || this.destroyed || this.editing()) return;
     const url = location.href;
     const ctx = this.getContext();
     if (reason === "identify") {
@@ -2199,7 +2357,7 @@ var GuidelyClient = class _GuidelyClient {
       this.visibilityObservers.delete(guide.id);
     };
     this.visibilityObservers.set(guide.id, stop);
-    (0, import_guide_runtime3.waitForTarget)([{ kind: "css", value: selector }], { timeoutMs: 0, signal: ac.signal }).then((el) => {
+    (0, import_guide_runtime4.waitForTarget)([{ kind: "css", value: selector }], { timeoutMs: 0, signal: ac.signal }).then((el) => {
       if (ac.signal.aborted) return;
       const fire = () => {
         stop();
@@ -2292,10 +2450,10 @@ var GuidelyClient = class _GuidelyClient {
     }
   }
   showFlow(guide, manual, stepId) {
-    if (this.authoring?.isActive()) return;
+    if (this.editing()) return;
     const exclusive = isExclusiveGuide(guide);
     const entry = { guide, manual, startUrl: location.href };
-    const controller = (0, import_guide_runtime3.runGuide)(guide, {
+    const controller = (0, import_guide_runtime4.runGuide)(guide, {
       theme: this.theme(),
       ctx: () => this.getContext(),
       startAtStep: stepId,
@@ -2310,6 +2468,10 @@ var GuidelyClient = class _GuidelyClient {
         }
         if (e.name === "step_viewed" && step) {
           if (exclusive) writeJson(this.sessionStore, KEYS.active, { guideId: guide.id, stepId: step.id, manual });
+          if (guide.kind === "flow" && guide.config.steps.length > 1) {
+            this.guideState(guide.id).lastStepId = step.id;
+            this.persistState();
+          }
           this.emitter.emit("guide:step", { guide, stepId: step.id, stepIndex: e.stepIndex ?? 0 });
         }
         if (e.name === "guide_completed") {
@@ -2349,13 +2511,13 @@ var GuidelyClient = class _GuidelyClient {
     }
   }
   showChecklist(guide) {
-    if (this.authoring?.isActive()) return;
+    if (this.editing()) return;
     const config = guide.config.checklist;
     if (!config || this.widgets.has(guide.id)) return;
-    const scope = (0, import_guide_runtime4.createScope)(this.theme(), guide.config.appearance);
+    const scope = (0, import_guide_runtime5.createScope)(this.theme(), guide.config.appearance);
     const progress = this.getChecklistProgress(guide.id);
     const first = !this.state.guides[guide.id]?.impressions;
-    const widget = (0, import_guide_runtime3.renderChecklist)({
+    const widget = (0, import_guide_runtime4.renderChecklist)({
       scope: scope.el,
       config,
       progress,
@@ -2371,10 +2533,10 @@ var GuidelyClient = class _GuidelyClient {
     if (first) this.recordImpression(guide);
   }
   showSurvey(guide, manual) {
-    if (this.authoring?.isActive()) return;
+    if (this.editing()) return;
     const config = guide.config.survey;
     if (!config) return;
-    const scope = (0, import_guide_runtime4.createScope)(this.theme(), guide.config.appearance);
+    const scope = (0, import_guide_runtime5.createScope)(this.theme(), guide.config.appearance);
     const entry = { guide, manual, startUrl: location.href, scope };
     const finish = (reason) => {
       widget.destroy();
@@ -2387,13 +2549,13 @@ var GuidelyClient = class _GuidelyClient {
       }
       this.setTimer(() => this.evaluate("after_guide", { endedGuide: guide }), 0);
     };
-    const widget = (0, import_guide_runtime3.renderSurvey)({
+    const widget = (0, import_guide_runtime4.renderSurvey)({
       scope: scope.el,
       config,
       title: guide.name,
       onDismiss: () => finish(this.state.surveysSubmitted.includes(guide.id) ? "submitted" : "dismissed"),
       onSubmit: (answers) => {
-        const responseId = (0, import_runtime11.randomId)(24);
+        const responseId = (0, import_runtime13.randomId)(24);
         this.state.surveysSubmitted.push(guide.id);
         this.persistState();
         this.recordEnd(guide, "completed");
@@ -2422,7 +2584,7 @@ var GuidelyClient = class _GuidelyClient {
     }
   }
   renderPersistentWidgets() {
-    if (!this.config) return;
+    if (!this.config || this.captureStarting || this.capture?.isActive()) return;
     const rc = this.config.resourceCenter;
     if (this.config.messenger?.enabled) {
       if (this.resourceCenter) {
@@ -2435,9 +2597,9 @@ var GuidelyClient = class _GuidelyClient {
     }
     this.destroyMessenger();
     if (rc && rc.enabled && !this.resourceCenter) {
-      const scope = (0, import_guide_runtime4.createScope)(this.theme());
+      const scope = (0, import_guide_runtime5.createScope)(this.theme());
       this.resourceCenterScope = scope;
-      this.resourceCenter = (0, import_guide_runtime3.renderResourceCenter)({
+      this.resourceCenter = (0, import_guide_runtime4.renderResourceCenter)({
         scope: scope.el,
         config: rc,
         guides: this.config.guides.map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind })),
@@ -2473,7 +2635,7 @@ var GuidelyClient = class _GuidelyClient {
     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_runtime4.createScope)(this.theme());
+      const scope = (0, import_guide_runtime5.createScope)(this.theme());
       this.messengerScope = scope;
       this.messenger = renderMessenger({
         scope: scope.el,
@@ -2486,6 +2648,13 @@ var GuidelyClient = class _GuidelyClient {
           userId: () => this.user?.id || null,
           pageUrl: () => this.collectUrls() ? location.href : void 0
         }),
+        visitor: () => this.messengerVisitor(),
+        brand: { logoUrl: this.theme().logoUrl ?? null, name: this.theme().brandName ?? null },
+        onResumeGuide: (guideId, stepId) => this.startGuide(guideId, { stepId }),
+        onNewsSeen: (ids) => {
+          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,
         audienceIds: () => this.state.audienceIds,
         guides: this.config.guides.map((g) => ({ id: g.id, key: g.key, name: g.name, kind: g.kind })),
@@ -2507,6 +2676,25 @@ var GuidelyClient = class _GuidelyClient {
     });
     return this.messengerLoading;
   }
+  /** What the messenger personalises from, computed fresh on every render. */
+  messengerVisitor() {
+    const ctx = this.getContext();
+    const url = location.href;
+    const seen = readJson(this.store, KEYS.newsSeen(this.options.projectId), []);
+    return buildMessengerVisitor({
+      guides: this.config?.guides ?? [],
+      state: this.state,
+      traits: this.user?.traits,
+      url,
+      isTargeted: (g) => this.isTargeted(g, ctx, url),
+      isAudienceTargeted: (g) => {
+        if (!isWithinSchedule(g)) return false;
+        ctx.rolloutSalt = g.id;
+        return (0, import_runtime13.evaluateRules)(g.config.targeting, ctx);
+      },
+      newsSeen: Array.isArray(seen) ? seen : []
+    });
+  }
   destroyMessenger() {
     this.messenger?.destroy();
     this.messengerScope?.destroy();
@@ -2553,7 +2741,7 @@ var GuidelyClient = class _GuidelyClient {
     if (progress.completedTaskIds.includes(task.id)) return;
     progress.completedTaskIds.push(task.id);
     this.enqueue("checklist_task_completed", { guideId: guide.id, guideVersion: guide.version, properties: { taskId: task.id } });
-    const complete = (0, import_guide_runtime3.isChecklistComplete)(config, progress) && !progress.completedAt;
+    const complete = (0, import_guide_runtime4.isChecklistComplete)(config, progress) && !progress.completedAt;
     if (complete) {
       progress.completedAt = nowIso();
       this.enqueue("checklist_completed", { guideId: guide.id, guideVersion: guide.version });
@@ -2576,7 +2764,7 @@ var GuidelyClient = class _GuidelyClient {
         if (task.completion !== kind || !task.completionValue) continue;
         let hit = false;
         if (kind === "event") hit = value === task.completionValue;
-        else if (kind === "url_visited") hit = (0, import_guide_runtime3.urlMatches)(task.completionValue, value);
+        else if (kind === "url_visited") hit = (0, import_guide_runtime4.urlMatches)(task.completionValue, value);
         else if (kind === "guide_completed") hit = value.id === task.completionValue || value.key === task.completionValue;
         else if (kind === "click") {
           try {
@@ -2720,7 +2908,8 @@ var GuidelyClient = class _GuidelyClient {
       audienceIds: this.state.audienceIds,
       session: this.session,
       pendingEvents: this.queue.size,
-      authoring: !!this.authoring?.isActive()
+      authoring: !!this.authoring?.isActive(),
+      capture: !!this.capture?.isActive()
     };
   }
   // ---------------------------------------------------------------------------
@@ -2735,22 +2924,78 @@ var GuidelyClient = class _GuidelyClient {
         ctx: () => this.getContext(),
         maskSelectors: [...this.options.maskSelectors || [], ...this.config?.settings?.maskSelectors || []],
         onError: (err) => this.reportError(err),
-        onActive: (active) => {
-          this.emitter.emit("authoring", { active });
-          if (active) this.replay?.stop({ discard: true });
-          else this.syncCapture();
-          if (active) {
-            this.stopGuide();
-            this.widgets.forEach((w) => w.destroy());
-            this.widgets.clear();
-          } else this.evaluate("ready");
-        }
+        onActive: (active) => this.setEditing("authoring", active)
       });
       if (bridge.detect()) this.authoring = bridge;
     } catch (err) {
       this.reportError(err);
     }
   }
+  /** Authoring or capture started / ended: pause everything a visitor would see or be recorded by. */
+  setEditing(kind, active) {
+    this.emitter.emit(kind, { active });
+    if (active) {
+      this.replay?.stop({ discard: true });
+      this.stopGuide();
+      this.widgets.forEach((w) => w.destroy());
+      this.widgets.clear();
+      if (kind === "capture") this.hidePersistentWidgets();
+    } else {
+      this.syncCapture();
+      this.renderPersistentWidgets();
+      this.evaluate("ready");
+    }
+  }
+  hidePersistentWidgets() {
+    this.resourceCenter?.destroy();
+    this.resourceCenterScope?.destroy();
+    this.resourceCenter = null;
+    this.resourceCenterScope = null;
+    this.destroyMessenger();
+  }
+  // ---------------------------------------------------------------------------
+  // How-to capture
+  // ---------------------------------------------------------------------------
+  /**
+   * Starts how-to capture when the URL carries `guidely_capture` (or this tab is mid-recording).
+   * The bridge, toolbar and screenshot code are a separate chunk loaded only then.
+   */
+  maybeStartCapture() {
+    let marker = null;
+    try {
+      marker = takeCaptureToken(this.sessionStore);
+    } catch (err) {
+      this.reportError(err);
+    }
+    if (!marker) return false;
+    const found = marker;
+    this.captureStarting = true;
+    this.replay?.stop({ discard: true });
+    loadCapture().then(async (capture) => {
+      if (this.destroyed) return;
+      const bridge = capture.createBridge({
+        api: this.api,
+        sessionStore: this.sessionStore,
+        marker: found,
+        maskSelector: this.maskSelector(),
+        onError: (err) => this.reportError(err),
+        onActive: (active) => {
+          this.captureStarting = false;
+          this.setEditing("capture", active);
+        }
+      });
+      this.capture = bridge;
+      await bridge.start();
+    }).catch((err) => this.reportError(err)).finally(() => {
+      if (!this.captureStarting) return;
+      this.captureStarting = false;
+      if (this.destroyed) return;
+      this.syncCapture();
+      this.renderPersistentWidgets();
+      this.evaluate("ready");
+    });
+    return true;
+  }
   // ---------------------------------------------------------------------------
   // Internals
   // ---------------------------------------------------------------------------
@@ -2790,9 +3035,9 @@ var GuidelyClient = class _GuidelyClient {
 };
 var current = null;
 function webOnly(config) {
-  return config.guides.every((g) => (0, import_runtime11.supportsPlatform)(g.config, "web")) ? config : { ...config, guides: config.guides.filter((g) => (0, import_runtime11.supportsPlatform)(g.config, "web")) };
+  return config.guides.every((g) => (0, import_runtime13.supportsPlatform)(g.config, "web")) ? config : { ...config, guides: config.guides.filter((g) => (0, import_runtime13.supportsPlatform)(g.config, "web")) };
 }
-function pathOf(url) {
+function pathOf2(url) {
   try {
     return new URL(url, "http://localhost").pathname;
   } catch {
@@ -2826,6 +3071,7 @@ var index_default = Guidely;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AUTHORING_PARAM,
+  CAPTURE_PARAM,
   DEFAULT_API_URL,
   EventQueue,
   Guidely,