@guidelytech/sdk-core 0.5.0 → 0.6.1

package/dist/index.js

@@ -1,20 +1,22 @@
 import {
   Emitter,
   EventQueue,
-  KEYS,
   areMutuallyExclusive,
-  createStorage,
   isExclusiveGuide,
   isFrequencyEligible,
-  isWithinSchedule,
+  isWithinSchedule
+} from "./chunk-GDF6RCHQ.js";
+import {
+  KEYS,
+  createStorage,
   readJson,
   writeJson
-} from "./chunk-HLR3W63Z.js";
+} from "./chunk-CYAG6ZYX.js";
 import {
   Api,
   __publicField,
   postWithRetry
-} from "./chunk-GJT7CFAC.js";
+} from "./chunk-AKNE7D5M.js";
 
 // src/client.ts
 import { evaluateRules, randomId, rolloutBucket, sanitizeProperties, supportsPlatform } from "@guidelytech/shared/runtime";
@@ -25,7 +27,7 @@ import {
   renderResourceCenter,
   renderSurvey,
   runGuide as runGuide2,
-  urlMatches,
+  urlMatches as urlMatches2,
   waitForTarget
 } from "@guidelytech/guide-runtime";
 import { createScope } from "@guidelytech/guide-runtime";
@@ -338,6 +340,43 @@ var AuthoringBridge = class {
   }
 };
 
+// src/capture-token.ts
+import { CAPTURE_PARAM } from "@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(CAPTURE_PARAM);
+    authoringLink = url.searchParams.has(AUTHORING_PARAM);
+    if (token) {
+      url.searchParams.delete(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.js")).capture;
+
 // src/autocapture.ts
 import { isGuidelyElement, isStableId } 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]";
@@ -673,6 +712,15 @@ var ExceptionThrottle = class {
 // 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") : [];
@@ -747,7 +795,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) } });
@@ -767,13 +815,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
+import { firstNameFromTraits } from "@guidelytech/shared/runtime";
+import { urlMatches } from "@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) => 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: firstNameFromTraits(input.traits), path: pathOf(input.url), pageGuides, resumeGuide, checklist, news };
+}
+
 // src/navigation.ts
 function watchNavigation(listener, debounceMs = 50) {
   if (typeof window === "undefined") return () => {
@@ -879,7 +1012,7 @@ var loadRecorder = async () => (await import("./recorder.js")).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;
@@ -930,6 +1063,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);
@@ -1038,10 +1174,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();
@@ -1139,7 +1276,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) {
@@ -1197,6 +1334,8 @@ 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();
@@ -1229,6 +1368,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,
@@ -1257,6 +1397,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) {
@@ -1378,16 +1519,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) => urlMatches(p, url))) this.active.controller.destroy();
+        if (g.config.urlPatterns.length && !g.config.urlPatterns.some((p) => urlMatches2(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) => urlMatches(p, url))) w.controller.destroy();
+      if (g?.config.urlPatterns.length && !g.config.urlPatterns.some((p) => urlMatches2(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) {
@@ -1418,9 +1560,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) {
@@ -1430,7 +1576,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;
@@ -1440,7 +1586,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;
@@ -1457,7 +1603,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);
@@ -1494,7 +1640,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 });
   }
@@ -1668,8 +1814,8 @@ var GuidelyClient = class _GuidelyClient {
   }
   isTargeted(guide, ctx, url) {
     const c = guide.config;
-    if (c.urlPatterns.length && !c.urlPatterns.some((p) => urlMatches(p, url))) return false;
-    if (c.trigger.urlPattern && !urlMatches(c.trigger.urlPattern, url)) return false;
+    if (c.urlPatterns.length && !c.urlPatterns.some((p) => urlMatches2(p, url))) return false;
+    if (c.trigger.urlPattern && !urlMatches2(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;
@@ -1691,7 +1837,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") && urlMatches(t.value, location.href);
+        return (reason === "ready" || reason === "navigation" || reason === "identify") && urlMatches2(t.value, location.href);
       case "event":
         return reason === "event" && !!t.value && detail.eventName === t.value;
       case "element_click":
@@ -1715,7 +1861,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") {
@@ -1860,7 +2006,7 @@ 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 = runGuide2(guide, {
@@ -1878,6 +2024,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") {
@@ -1917,7 +2067,7 @@ 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 = createScope(this.theme(), guide.config.appearance);
@@ -1939,7 +2089,7 @@ 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 = createScope(this.theme(), guide.config.appearance);
@@ -1990,7 +2140,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) {
@@ -2054,6 +2204,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 })),
@@ -2075,6 +2232,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 evaluateRules(g.config.targeting, ctx);
+      },
+      newsSeen: Array.isArray(seen) ? seen : []
+    });
+  }
   destroyMessenger() {
     this.messenger?.destroy();
     this.messengerScope?.destroy();
@@ -2144,7 +2320,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 = urlMatches(task.completionValue, value);
+        else if (kind === "url_visited") hit = urlMatches2(task.completionValue, value);
         else if (kind === "guide_completed") hit = value.id === task.completionValue || value.key === task.completionValue;
         else if (kind === "click") {
           try {
@@ -2288,7 +2464,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()
     };
   }
   // ---------------------------------------------------------------------------
@@ -2303,22 +2480,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
   // ---------------------------------------------------------------------------
@@ -2360,7 +2593,7 @@ var current = null;
 function webOnly(config) {
   return config.guides.every((g) => supportsPlatform(g.config, "web")) ? config : { ...config, guides: config.guides.filter((g) => supportsPlatform(g.config, "web")) };
 }
-function pathOf(url) {
+function pathOf2(url) {
   try {
     return new URL(url, "http://localhost").pathname;
   } catch {
@@ -2393,6 +2626,7 @@ var Guidely = {
 var index_default = Guidely;
 export {
   AUTHORING_PARAM,
+  CAPTURE_PARAM,
   DEFAULT_API_URL,
   EventQueue,
   Guidely,