@guidelytech/guide-runtime 0.8.0 → 0.10.0

package/dist/index.cjs

@@ -24,12 +24,19 @@ var src_exports = {};
 __export(src_exports, {
   DEFAULT_THEME: () => DEFAULT_THEME,
   HOST_ID: () => HOST_ID2,
+  SHADOW_SEPARATOR: () => SHADOW_SEPARATOR,
   STYLES: () => STYLES,
   TargetTimeoutError: () => TargetTimeoutError,
   anchor: () => anchor,
   applyTheme: () => applyTheme,
   buildCard: () => buildCard,
+  closestComposed: () => closestComposed,
+  componentAnchor: () => componentAnchor,
+  composedParent: () => composedParent,
+  composedTarget: () => composedTarget,
+  containsComposed: () => containsComposed,
   createScope: () => createScope,
+  deepElementFromPoint: () => deepElementFromPoint,
   describeElement: () => describeElement,
   destroyHost: () => destroyHost,
   enhancePdfViewers: () => enhancePdfViewers,
@@ -63,10 +70,12 @@ __export(src_exports, {
   sanitizeHtml: () => sanitizeHtml,
   sanitizeToFragment: () => sanitizeToFragment,
   setSanitizedHtml: () => setSanitizedHtml,
+  shadowHostChain: () => shadowHostChain,
   startAuthoring: () => startAuthoring,
   textSnapshotOf: () => textSnapshotOf,
   trackRect: () => trackRect,
   urlMatches: () => urlMatches,
+  visualRect: () => visualRect,
   waitForTarget: () => waitForTarget
 });
 module.exports = __toCommonJS(src_exports);
@@ -129,6 +138,82 @@ function safeQueryAll(root, selector) {
     return [];
   }
 }
+var SHADOW_SEPARATOR = " >>> ";
+var SHADOW_SPLIT = /\s*>>>\s*/;
+function isShadowRoot(node) {
+  return !!node && node.nodeType === 11 && !!node.host;
+}
+function shadowRootOf(el2) {
+  const root = el2.getRootNode?.();
+  return isShadowRoot(root) ? root : null;
+}
+function composedParent(el2) {
+  return el2.parentElement ?? shadowRootOf(el2)?.host ?? null;
+}
+function containsComposed(ancestor, node) {
+  let cur = node ? node.nodeType === 1 ? node : node.parentElement : null;
+  for (; cur; cur = composedParent(cur)) if (cur === ancestor) return true;
+  return false;
+}
+function composedTarget(e) {
+  const path = typeof e.composedPath === "function" ? e.composedPath() : [];
+  const first = path[0] ?? e.target;
+  if (!first) return null;
+  return first.nodeType === 1 ? first : first.parentElement;
+}
+var shadowRootCache = null;
+function shadowRootsIn(root) {
+  const cached = shadowRootCache?.get(root);
+  if (cached) return cached;
+  const out = [];
+  const visit = (scope) => {
+    const own = scope.nodeType === 1 ? scope.shadowRoot : null;
+    const hosts = own ? [scope] : [];
+    for (const el2 of safeQueryAll(scope, "*")) if (el2.shadowRoot) hosts.push(el2);
+    for (const host of hosts) {
+      if (host.id === HOST_ID || !host.shadowRoot || out.includes(host.shadowRoot)) continue;
+      out.push(host.shadowRoot);
+      visit(host.shadowRoot);
+    }
+  };
+  visit(root);
+  shadowRootCache?.set(root, out);
+  return out;
+}
+function queryAllDeep(root, selector) {
+  const out = safeQueryAll(root, selector);
+  for (const sr of shadowRootsIn(root)) out.push(...safeQueryAll(sr, selector));
+  return out;
+}
+function queryCss(root, selector, deep) {
+  if (!selector.includes(">>>")) return deep ? queryAllDeep(root, selector) : safeQueryAll(root, selector);
+  const steps = selector.split(SHADOW_SPLIT).filter(Boolean);
+  let scopes = [root];
+  let matches = [];
+  steps.forEach((step, i) => {
+    matches = Array.from(new Set(scopes.flatMap((scope) => queryAllDeep(scope, step))));
+    if (i < steps.length - 1) scopes = matches.map((el2) => el2.shadowRoot).filter((sr) => !!sr);
+  });
+  return matches;
+}
+function closestComposed(el2, selector) {
+  if (selector.includes(">>>")) {
+    const hits = new Set(queryCss(docOf(el2), selector, true));
+    for (let cur = el2; cur; cur = composedParent(cur)) if (hits.has(cur)) return cur;
+    return null;
+  }
+  for (let cur = el2; cur; cur = composedParent(cur)) if (cur.matches(selector)) return cur;
+  return null;
+}
+function deepElementFromPoint(doc, x, y) {
+  let el2 = doc.elementFromPoint(x, y);
+  while (el2?.shadowRoot && el2.id !== HOST_ID && typeof el2.shadowRoot.elementFromPoint === "function") {
+    const inner = el2.shadowRoot.elementFromPoint(x, y);
+    if (!inner || inner === el2) break;
+    el2 = inner;
+  }
+  return el2;
+}
 function escapeCss(value) {
   const g = globalThis;
   if (g.CSS && typeof g.CSS.escape === "function") return g.CSS.escape(value);
@@ -150,32 +235,32 @@ function queryXPath(root, expr) {
     return [];
   }
 }
-function queryText(root, text) {
+function queryText(root, text, deep) {
   const needle = normalizeText(text).toLowerCase();
   if (!needle) return [];
-  const candidates = safeQueryAll(root, TEXT_CANDIDATES);
+  const candidates = queryCss(root, TEXT_CANDIDATES, deep);
   const exact = candidates.filter((c) => normalizeText(c.textContent).toLowerCase() === needle);
   if (exact.length) return exact;
   return candidates.filter((c) => normalizeText(c.textContent).toLowerCase().includes(needle));
 }
-function querySelectorStrategy(strategy, root) {
+function querySelectorStrategy(strategy, root, deep = true) {
   const value = strategy.value.trim();
   if (!value) return [];
   switch (strategy.kind) {
     case "id": {
       const id = value.startsWith("#") ? value.slice(1) : value;
-      return safeQueryAll(root, `#${escapeCss(id)}`);
+      return queryCss(root, `#${escapeCss(id)}`, deep);
     }
     case "guidely-id": {
       const id = value.startsWith("#") ? value.slice(1) : value;
-      return safeQueryAll(root, attrSelector("data-guidely-id", id));
+      return queryCss(root, attrSelector("data-guidely-id", id), deep);
     }
     case "data-attr":
     case "aria":
     case "css":
-      return safeQueryAll(root, value.startsWith("[") || /^[a-z*#.[]/i.test(value) ? value : `[${value}]`);
+      return queryCss(root, value.startsWith("[") || /^[a-z*#.[]/i.test(value) ? value : `[${value}]`, deep);
     case "text":
-      return queryText(root, value);
+      return queryText(root, value, deep);
     case "xpath":
       return queryXPath(root, value);
     default:
@@ -184,11 +269,19 @@ function querySelectorStrategy(strategy, root) {
 }
 function resolveTarget(target, root = document) {
   const selectors = Array.isArray(target) ? target : target.selectors;
-  for (const strategy of selectors) {
-    const matches = querySelectorStrategy(strategy, root).filter((el2) => !isGuidelyElement(el2) && isVisible(el2));
-    if (matches.length === 1) return matches[0];
+  const visibleMatches = (strategy, deep) => querySelectorStrategy(strategy, root, deep).filter((el2) => !isGuidelyElement(el2) && isVisible(el2));
+  const outer = shadowRootCache;
+  shadowRootCache ?? (shadowRootCache = /* @__PURE__ */ new Map());
+  try {
+    for (const strategy of selectors) {
+      let matches = visibleMatches(strategy, false);
+      if (!matches.length && strategy.kind !== "xpath") matches = visibleMatches(strategy, true);
+      if (matches.length === 1) return matches[0];
+    }
+    return null;
+  } finally {
+    shadowRootCache = outer;
   }
-  return null;
 }
 var TargetTimeoutError = class extends Error {
   constructor(message = "Target element not found before timeout") {
@@ -252,14 +345,15 @@ function isStableId(id) {
 function isStableClass(cls) {
   return !!cls && !GENERATED_CLASS.test(cls) && cls.length <= 40;
 }
-function uniqueIn(doc, selector, el2) {
-  const all = safeQueryAll(doc, selector);
+function uniqueWithin(root, selector, el2) {
+  const all = safeQueryAll(root, selector);
   return all.length === 1 && all[0] === el2;
 }
 function attrSelector(name, value) {
   return `[${name}='${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}']`;
 }
-function cssPath(el2, doc) {
+function cssPath(el2, root) {
+  const doc = el2.ownerDocument;
   const segments = [];
   let cur = el2;
   while (cur && cur.nodeType === 1 && cur !== doc.body && cur !== doc.documentElement) {
@@ -279,20 +373,48 @@ function cssPath(el2, doc) {
     }
     segments.unshift(seg);
     const candidate = segments.join(" > ");
-    if (uniqueIn(doc, candidate, el2)) return candidate;
+    if (uniqueWithin(root, candidate, el2)) return candidate;
     cur = parent;
   }
   const full = segments.join(" > ");
-  return uniqueIn(doc, full, el2) ? full : null;
+  return uniqueWithin(root, full, el2) ? full : null;
+}
+function shadowHostChain(el2) {
+  const steps = [];
+  for (let root = shadowRootOf(el2); root; root = shadowRootOf(root.host)) {
+    const host = root.host;
+    const step = cssPath(host, shadowRootOf(host) ?? host.ownerDocument);
+    if (!step) return null;
+    steps.unshift(step);
+  }
+  return steps.join(SHADOW_SEPARATOR);
+}
+function selectorFor(el2, selector) {
+  const root = shadowRootOf(el2);
+  if (!root) return uniqueWithin(el2.ownerDocument, selector, el2) ? selector : null;
+  if (!uniqueWithin(root, selector, el2)) return null;
+  const doc = el2.ownerDocument;
+  const only = (sel) => {
+    const all = queryCss(doc, sel, true);
+    return all.length === 1 && all[0] === el2;
+  };
+  if (only(selector)) return selector;
+  const chain = shadowHostChain(el2);
+  const scoped = chain ? chain + SHADOW_SEPARATOR + selector : null;
+  return scoped && only(scoped) ? scoped : null;
+}
+function shadowText(el2) {
+  if (!el2.shadowRoot) return "";
+  const parts = Array.from(el2.shadowRoot.children).filter((c) => !/^(STYLE|SCRIPT|TEMPLATE)$/.test(c.tagName));
+  return normalizeText(parts.map((c) => c.innerText ?? c.textContent).join(" "));
 }
 function textSnapshotOf(el2) {
   const he = el2;
-  const own = normalizeText(he.innerText ?? el2.textContent);
+  const own = normalizeText(he.innerText ?? el2.textContent) || shadowText(el2);
   const alt = normalizeText(el2.getAttribute("aria-label") || el2.getAttribute("title") || el2.getAttribute("placeholder") || el2.getAttribute("alt") || el2.value);
   return (own || alt).slice(0, 200);
 }
 function generateSelectors(el2) {
-  const doc = el2.ownerDocument;
   const out = [];
   const seen = /* @__PURE__ */ new Set();
   const push = (s) => {
@@ -303,9 +425,15 @@ function generateSelectors(el2) {
     }
   };
   const tag = el2.tagName.toLowerCase();
+  const pushFor = (kind, selector, value, label) => {
+    const resolved = selectorFor(el2, selector);
+    if (resolved === selector) push({ kind, value, label });
+    else if (resolved) push({ kind: "css", value: resolved, label });
+    return !!resolved;
+  };
   const guidelyId = el2.getAttribute("data-guidely-id");
-  if (guidelyId && uniqueIn(doc, attrSelector("data-guidely-id", guidelyId), el2)) push({ kind: "guidely-id", value: guidelyId, label: `Guidely id ${guidelyId}` });
-  if (isStableId(el2.id) && uniqueIn(doc, `#${escapeCss(el2.id)}`, el2)) push({ kind: "id", value: `#${el2.id}`, label: `id ${el2.id}` });
+  if (guidelyId) pushFor("guidely-id", attrSelector("data-guidely-id", guidelyId), guidelyId, `Guidely id ${guidelyId}`);
+  if (isStableId(el2.id)) pushFor("id", `#${escapeCss(el2.id)}`, `#${el2.id}`, `id ${el2.id}`);
   const dataAttrs = Array.from(el2.attributes).filter((a) => a.name.startsWith("data-") && !IGNORED_DATA_ATTRS.test(a.name) && a.value && a.value.length <= 120 && !/\d{5,}/.test(a.value));
   dataAttrs.sort((a, b) => {
     const ia = PREFERRED_DATA_ATTRS.indexOf(a.name);
@@ -314,42 +442,75 @@ function generateSelectors(el2) {
   });
   for (const a of dataAttrs) {
     const sel = attrSelector(a.name, a.value);
-    if (uniqueIn(doc, sel, el2)) push({ kind: "data-attr", value: sel, label: `${a.name}=${a.value}` });
-    else if (uniqueIn(doc, tag + sel, el2)) push({ kind: "data-attr", value: tag + sel, label: `${a.name}=${a.value}` });
+    if (!pushFor("data-attr", sel, sel, `${a.name}=${a.value}`)) pushFor("data-attr", tag + sel, tag + sel, `${a.name}=${a.value}`);
   }
   const aria = el2.getAttribute("aria-label");
   if (aria && aria.length <= 120) {
     const sel = attrSelector("aria-label", aria);
-    if (uniqueIn(doc, sel, el2)) push({ kind: "aria", value: sel, label: aria });
-    else if (uniqueIn(doc, tag + sel, el2)) push({ kind: "aria", value: tag + sel, label: aria });
+    if (!pushFor("aria", sel, sel, aria)) pushFor("aria", tag + sel, tag + sel, aria);
   }
   const name = el2.getAttribute("name");
-  if (name && uniqueIn(doc, tag + attrSelector("name", name), el2)) push({ kind: "css", value: tag + attrSelector("name", name), label: `${tag} name=${name}` });
+  if (name) pushFor("css", tag + attrSelector("name", name), tag + attrSelector("name", name), `${tag} name=${name}`);
   const role = el2.getAttribute("role");
   if (role) {
     const title = el2.getAttribute("title") || el2.getAttribute("aria-labelledby");
     const sel = title ? `[role='${role}']${attrSelector(el2.getAttribute("title") ? "title" : "aria-labelledby", title)}` : `[role='${role}']`;
-    if (uniqueIn(doc, sel, el2)) push({ kind: "css", value: sel, label: `role ${role}` });
+    pushFor("css", sel, sel, `role ${role}`);
   }
   if (tag === "a") {
     const href = el2.getAttribute("href");
-    if (href && href.length <= 200 && uniqueIn(doc, `a${attrSelector("href", href)}`, el2)) push({ kind: "css", value: `a${attrSelector("href", href)}`, label: `link ${href}` });
+    if (href && href.length <= 200) pushFor("css", `a${attrSelector("href", href)}`, `a${attrSelector("href", href)}`, `link ${href}`);
   }
-  const path = cssPath(el2, doc);
-  if (path) push({ kind: "css", value: path, label: "css path" });
+  const path = cssPath(el2, shadowRootOf(el2) ?? el2.ownerDocument);
+  if (path) pushFor("css", path, path, "css path");
   if (/^(button|a|h[1-6]|label|summary)$/.test(tag) || role === "button" || role === "link" || role === "tab" || role === "menuitem") {
     const text = normalizeText(el2.innerText ?? el2.textContent);
     if (text && text.length <= 80) push({ kind: "text", value: text, label: `text "${text}"` });
   }
   return out.slice(0, 10);
 }
+function visualRect(el2) {
+  const own = el2.getBoundingClientRect();
+  if (!el2.shadowRoot) return own;
+  const boxes = [own, ...Array.from(el2.shadowRoot.children).map((c) => c.getBoundingClientRect())].filter((r) => r.width > 0 && r.height > 0);
+  if (boxes.length < 2) return boxes[0] ?? own;
+  const left = Math.min(...boxes.map((r) => r.left));
+  const top = Math.min(...boxes.map((r) => r.top));
+  const right = Math.max(...boxes.map((r) => r.right));
+  const bottom = Math.max(...boxes.map((r) => r.bottom));
+  return new DOMRect(left, top, right - left, bottom - top);
+}
+var ANCHOR_MAX_AREA_RATIO = 4;
+var CONTROL_SELECTOR = "button, a[href], input, select, textarea, [role='button'], [role='link'], [role='checkbox'], [role='radio'], [role='switch'], [role='tab'], [role='menuitem'], [role='combobox'], [role='option']";
+function componentAnchor(el2) {
+  if (!hasLayout(el2.ownerDocument)) return el2;
+  let cur = el2;
+  for (let root = shadowRootOf(cur); root; root = shadowRootOf(cur)) {
+    const host = root.host;
+    if (host.id === HOST_ID) break;
+    let control = null;
+    try {
+      control = cur.closest(CONTROL_SELECTOR);
+    } catch {
+    }
+    const r = visualRect(control ?? cur);
+    const area = r.width * r.height;
+    const h2 = visualRect(host);
+    const hostArea = h2.width * h2.height;
+    const inside = r.left >= h2.left - 1 && r.top >= h2.top - 1 && r.right <= h2.right + 1 && r.bottom <= h2.bottom + 1;
+    if (!area || !inside || hostArea > area * ANCHOR_MAX_AREA_RATIO) break;
+    cur = host;
+  }
+  return cur;
+}
 function describeElement(el2) {
-  const r = el2.getBoundingClientRect();
+  const target = componentAnchor(el2);
+  const r = visualRect(target);
   return {
-    selectors: generateSelectors(el2),
-    textSnapshot: textSnapshotOf(el2),
+    selectors: generateSelectors(target),
+    textSnapshot: textSnapshotOf(target) || textSnapshotOf(el2),
     rect: { x: r.x, y: r.y, width: r.width, height: r.height },
-    tag: el2.tagName.toLowerCase()
+    tag: target.tagName.toLowerCase()
   };
 }
 
@@ -618,7 +779,15 @@ var STYLES = `
 .g-rc-item .g-rc-title{font-weight:500}
 .g-rc-item .g-rc-sum{font-size:12px;color:var(--g-muted);margin-top:2px}
 .g-rc-item .g-rc-icon{flex:none;width:20px;text-align:center;color:var(--g-primary)}
+.g-rc-row{display:flex;align-items:center;gap:6px;padding-right:16px}
+.g-rc-row>.g-rc-item{flex:1;min-width:0;padding-right:4px}
+.g-rc-row:hover{background:var(--g-subtle)}
+.g-rc-row:hover>.g-rc-item{background:transparent}
+.g-rc-showme{flex:none;min-height:32px;padding:4px 10px;font-size:12px;white-space:nowrap}
+.g-help-showme{margin:4px 0 12px}
 .g-rc-article{padding:16px 20px}
+.g-resource-center .g-panel{transition:width .2s ease,max-height .2s ease}
+.g-resource-center .g-panel.g-panel-reading{width:min(720px,calc(100vw - 32px));max-height:calc(100vh - 100px)}
 .g-rc-back{margin-bottom:8px}
 .g-rc-empty{padding:24px 20px;color:var(--g-muted);text-align:center}
 .g-faq-a{padding:0 20px 12px 50px;font-size:13px;color:var(--g-muted)}
@@ -896,7 +1065,8 @@ function openReader(doc, block, link, pages, start) {
 
 // src/position.ts
 var import_dom = require("@floating-ui/dom");
-function anchor(reference, floating, options = {}) {
+function anchor(target, floating, options = {}) {
+  const reference = target.shadowRoot ? { getBoundingClientRect: () => visualRect(target), contextElement: target } : target;
   const placement = options.placement ?? "auto";
   const gap = options.offset ?? 10;
   const middleware = [(0, import_dom.offset)(gap + (options.arrowEl ? 4 : 0))];
@@ -949,7 +1119,7 @@ function trackRect(el2, cb) {
   let stopped = false;
   const run = () => {
     if (stopped) return;
-    cb(el2.getBoundingClientRect());
+    cb(visualRect(el2));
   };
   const schedule = () => {
     if (stopped) return;
@@ -962,6 +1132,9 @@ function trackRect(el2, cb) {
   const win = el2.ownerDocument.defaultView;
   win?.addEventListener("scroll", schedule, true);
   win?.addEventListener("resize", schedule);
+  const shadowRoots = [];
+  for (let root = el2.getRootNode(); root.nodeType === 11 && root.host; root = root.host.getRootNode()) shadowRoots.push(root);
+  for (const root of shadowRoots) root.addEventListener("scroll", schedule, true);
   let ro = null;
   if (typeof ResizeObserver !== "undefined") {
     try {
@@ -977,6 +1150,7 @@ function trackRect(el2, cb) {
     stopped = true;
     win?.removeEventListener("scroll", schedule, true);
     win?.removeEventListener("resize", schedule);
+    for (const root of shadowRoots) root.removeEventListener("scroll", schedule, true);
     ro?.disconnect();
     clearInterval(interval);
     if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(raf);
@@ -1363,6 +1537,17 @@ function isAnchoredStep(step) {
 var import_runtime5 = require("@guidelytech/shared/runtime");
 function noop() {
 }
+var escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+function navigableUrl(pattern) {
+  if (!pattern || /[*?#\s]/.test(pattern) || pattern.includes("/:")) return null;
+  if (pattern.startsWith("/") && !pattern.startsWith("//")) return pattern;
+  try {
+    const u = new URL(pattern);
+    if (typeof location !== "undefined" && u.origin === location.origin) return u.pathname;
+  } catch {
+  }
+  return null;
+}
 function runGuide(guide, options = {}) {
   const doc = options.doc ?? (options.container?.ownerDocument || document);
   const steps = guide.config.steps;
@@ -1507,15 +1692,15 @@ function runGuide(guide, options = {}) {
       onError(err);
     }
   };
-  const setupAdvance = (step) => {
+  const setupAdvance = (step, target) => {
     const modes = step.advanceOn === "any" ? ["element_click", "element_visible", "event", "delay"] : [step.advanceOn];
     for (const mode of modes) {
-      if (mode === "element_click" && step.advanceValue) {
+      if (mode === "element_click" && (step.advanceValue || target)) {
         const selector = step.advanceValue;
         const handler = (e) => {
-          const t = e.target;
+          const t = composedTarget(e);
           try {
-            if (t && typeof t.closest === "function" && t.closest(selector)) advance();
+            if (selector ? t && closestComposed(t, selector) : t && target && containsComposed(target, t)) advance();
           } catch {
           }
         };
@@ -1551,10 +1736,11 @@ function runGuide(guide, options = {}) {
   const render = (step, target, asModal = false) => {
     if (ended) return;
     status = "running";
+    const shown = !target && step.advanceOn === "element_click" && !step.advanceValue && !step.buttons.length ? { ...step, buttons: [{ id: "g-next", label: index + 1 >= total ? "Done" : "Next", action: index + 1 >= total ? "complete" : "next", variant: "primary" }] } : step;
     try {
       view = renderStep({
         scope: getScope(),
-        step,
+        step: shown,
         index,
         total,
         canGoBack: history.length > 0 || index > 0,
@@ -1576,7 +1762,43 @@ function runGuide(guide, options = {}) {
     }
     emit("step_viewed", step, index, asModal ? { fallback: "show_as_modal" } : void 0);
     announce(step.title ? `${step.title}. Step ${index + 1} of ${total}` : `Step ${index + 1} of ${total}`);
-    setupAdvance(step);
+    setupAdvance(step, target);
+  };
+  const showUrlPrompt = (step) => {
+    if (ended || status !== "waiting_url" || view) return;
+    const href = navigableUrl(step.url);
+    const where = (step.url ?? "").replace(/^https?:\/\/[^/]+/i, "") || "another page";
+    const prompt = {
+      ...step,
+      type: "modal",
+      title: "Continue on another page",
+      body: `<p>The next step${step.title ? `, <strong>${escapeHtml(step.title)}</strong>,` : ""} is on <code>${escapeHtml(where)}</code>.</p>`,
+      imageUrl: "",
+      buttons: [
+        ...href ? [{ id: "g-go", label: "Take me there", action: "url", value: href, variant: "primary" }] : [],
+        { id: "g-exit", label: "Exit", action: "dismiss", variant: href ? "secondary" : "primary" }
+      ]
+    };
+    try {
+      view = renderStep({
+        scope: getScope(),
+        step: prompt,
+        index,
+        total,
+        canGoBack: false,
+        target: null,
+        asModal: true,
+        onButton: (b) => {
+          if (b.action !== "url" || !b.value) return end("dismissed");
+          if (options.onNavigate) options.onNavigate(b.value);
+          else location.assign(b.value);
+        },
+        onClose: () => end("dismissed"),
+        announce
+      });
+    } catch (err) {
+      onError(err);
+    }
   };
   const applyFallback = (step, direction) => {
     const fallback = step.target?.fallback ?? "skip";
@@ -1602,9 +1824,18 @@ function runGuide(guide, options = {}) {
       if (nextIndex < 0) return;
       return showStep(nextIndex, direction);
     }
+    try {
+      options.onPosition?.(step.id);
+    } catch (err) {
+      onError(err);
+    }
     if (step.url && !urlMatches(step.url, currentUrl())) {
       status = "waiting_url";
       pendingIndex = i;
+      if (options.promptForUrl) {
+        const t = setTimeout(() => showUrlPrompt(step), options.urlPromptDelayMs ?? 1200);
+        stepCleanups.push(() => clearTimeout(t));
+      }
       return;
     }
     pendingIndex = -1;
@@ -2102,6 +2333,38 @@ function renderSurvey(options) {
 
 // src/help-view.ts
 var import_runtime8 = require("@guidelytech/shared/runtime");
+var SHOW_ME_KINDS = /* @__PURE__ */ new Set(["flow", "modal", "tooltip", "announcement"]);
+function startableGuide(guides, keyOrId) {
+  if (!keyOrId || !guides) return null;
+  return guides.find((g) => (g.key === keyOrId || g.id === keyOrId) && SHOW_ME_KINDS.has(g.kind)) ?? null;
+}
+function resultRow(doc, icon, title, summary, onOpen, showMe) {
+  const item = listItem(doc, icon, title, summary);
+  item.addEventListener("click", onOpen);
+  if (!showMe) return item;
+  const row = el(doc, "div", "g-rc-row");
+  const b = el(doc, "button", "g-btn g-btn-primary g-rc-showme", "\u25B6 Show me");
+  b.type = "button";
+  b.setAttribute("aria-label", `Show me: ${title}`);
+  b.addEventListener("click", showMe);
+  row.append(item, b);
+  return row;
+}
+function enhanceShowMe(root, doc, canStart, start) {
+  for (const a of Array.from(root.querySelectorAll(`a[href^="${import_runtime8.SHOW_ME_HREF_PREFIX}"]`))) {
+    const key = (0, import_runtime8.showMeKeyFromHref)(a.getAttribute("href"));
+    const holder = a.closest("p.gd-show-me") ?? a;
+    if (!key || !canStart(key)) {
+      if (holder !== a) holder.remove();
+      else a.replaceWith(doc.createTextNode(a.textContent ?? ""));
+      continue;
+    }
+    const b = el(doc, "button", "g-btn g-btn-primary g-help-showme", `\u25B6 ${(a.textContent ?? "").trim() || "Show me"}`);
+    b.type = "button";
+    b.addEventListener("click", () => start(key));
+    a.replaceWith(b);
+  }
+}
 function el(doc, tag, cls, text) {
   const e = doc.createElement(tag);
   if (cls) e.className = cls;
@@ -2126,6 +2389,11 @@ function createHelpView(options) {
   let searchSeq = 0;
   let openSeq = 0;
   let active = null;
+  const setActive = (next) => {
+    const was = !!active;
+    active = next;
+    if (was !== !!next) options.onArticleChange?.(!!next);
+  };
   const root = el(doc, "div", "g-help");
   const searchWrap = el(doc, "div", "g-rc-search");
   const input = el(doc, "input", "g-input");
@@ -2136,6 +2404,8 @@ function createHelpView(options) {
   const body = el(doc, "div", "g-panel-body");
   root.append(searchWrap, body);
   const hasBody = (a) => typeof a.body === "string" && !a.bodyOmitted;
+  const canShowMe = (key) => !!options.onShowMe && !!startableGuide(options.guides?.(), key);
+  const showMe = (key) => options.onShowMe?.(startableGuide(options.guides?.(), key)?.key ?? key);
   const openArticle = (article) => {
     if (article.externalUrl) {
       window.open(article.externalUrl, "_blank", "noopener,noreferrer");
@@ -2144,20 +2414,20 @@ function createHelpView(options) {
     }
     const seq = ++openSeq;
     if (hasBody(article) || !options.loadArticle) {
-      active = { article, loading: false };
+      setActive({ article, loading: false });
       if (hasBody(article)) options.onArticleView?.(article);
       return render();
     }
-    active = { article, loading: true };
+    setActive({ article, loading: true });
     render();
     options.loadArticle(article.id).then((full) => {
       if (seq !== openSeq || !active) return;
-      active = { article: full ?? { ...article, body: "" }, loading: false };
+      setActive({ article: full ?? { ...article, body: "" }, loading: false });
       if (full) options.onArticleView?.(full);
       render();
     }).catch(() => {
       if (seq !== openSeq || !active) return;
-      active = { article: { ...article, body: "" }, loading: false };
+      setActive({ article: { ...article, body: "" }, loading: false });
       render();
     });
   };
@@ -2167,7 +2437,7 @@ function createHelpView(options) {
     back.type = "button";
     back.addEventListener("click", () => {
       openSeq++;
-      active = null;
+      setActive(null);
       render();
     });
     const title = el(doc, "h3", "g-title", article.title);
@@ -2176,6 +2446,7 @@ function createHelpView(options) {
     else if (article.body) {
       setSanitizedHtml(content, article.body);
       enhancePdfViewers(content, doc);
+      enhanceShowMe(content, doc, canShowMe, showMe);
     } else content.appendChild(el(doc, "div", "g-rc-empty", "This article couldn't be loaded."));
     wrap.append(back, title, content);
     body.appendChild(wrap);
@@ -2187,9 +2458,9 @@ function createHelpView(options) {
     return s;
   };
   const articleButton = (a) => {
-    const b = listItem(doc, "\u{1F4C4}", a.title, a.summary);
-    b.addEventListener("click", () => openArticle(a));
-    body.appendChild(b);
+    const key = a.walkthroughs?.find(canShowMe);
+    const summary = a.hasVideo ? a.summary ? `Video \xB7 ${a.summary}` : "Video" : a.summary;
+    body.appendChild(resultRow(doc, a.hasVideo ? "\u25B6" : "\u{1F4C4}", a.title, summary, () => openArticle(a), key ? () => showMe(key) : void 0));
   };
   function render() {
     body.textContent = "";
@@ -2198,10 +2469,17 @@ function createHelpView(options) {
     const member = options.audienceIds?.() ?? [];
     const sections = (0, import_runtime8.resourceCenterSections)(data.collections, data.articles, member);
     const q = query.trim().toLowerCase();
+    if (q) {
+      const walkthroughs = (data.recommended ?? []).filter((g) => (0, import_runtime8.matchesHelpQuery)(g.name, q) && startableGuide(options.guides?.() ?? data.recommended, g.id));
+      if (walkthroughs.length) {
+        section(`Walkthroughs (${walkthroughs.length})`);
+        for (const g of walkthroughs) body.appendChild(resultRow(doc, "\u25B6", g.name, "Show me, step by step", () => options.onStartGuide?.(g.id)));
+      }
+    }
     body.append(...options.extra?.(q) ?? []);
     if (q) {
       const visible = sections.flatMap((s) => s.articles);
-      const local = visible.filter((a) => a.title.toLowerCase().includes(q) || a.summary.toLowerCase().includes(q));
+      const local = visible.filter((a) => (0, import_runtime8.matchesHelpQuery)(`${a.title} ${a.summary}`, q));
       const seen = new Set(local.map((a) => a.id));
       const hidden = new Set(data.articles.map((a) => a.id).filter((id) => !visible.some((v) => v.id === id)));
       const merged = [...local, ...serverResults.filter((a) => !seen.has(a.id) && !hidden.has(a.id) && (0, import_runtime8.isArticleListed)(data.collections, a, member))];
@@ -2273,7 +2551,7 @@ function createHelpView(options) {
   const onInput = () => {
     query = input.value;
     openSeq++;
-    active = null;
+    setActive(null);
     render();
     if (debounce) clearTimeout(debounce);
     if (!options.search || !query.trim()) {
@@ -2296,7 +2574,7 @@ function createHelpView(options) {
     render,
     reset() {
       openSeq++;
-      active = null;
+      setActive(null);
       query = "";
       input.value = "";
       serverResults = [];
@@ -2305,6 +2583,7 @@ function createHelpView(options) {
       const listed = options.data().articles.find((a) => a.id === id) ?? { id, slug: id, title: "Article", summary: "", updatedAt: "", bodyOmitted: true };
       openArticle(listed);
     },
+    isArticleOpen: () => !!active,
     focusSearch: () => input.focus?.({ preventScroll: true }),
     setQuery(q) {
       input.value = q;
@@ -2356,7 +2635,14 @@ function renderResourceCenter(options) {
     loadArticle: options.loadArticle,
     onStartGuide: options.onStartGuide,
     onOpenChecklist: options.onOpenChecklist,
-    onArticleView: options.onArticleView
+    onArticleView: options.onArticleView,
+    guides: () => guides,
+    onShowMe: (key) => {
+      setOpen(false);
+      options.onStartGuide?.(key);
+    },
+    // Articles read in a larger panel.
+    onArticleChange: (reading) => panel.classList.toggle("g-panel-reading", reading)
   });
   panel.append(head, help.el);
   root.append(launcher, panel);
@@ -2445,7 +2731,7 @@ function startAuthoring(options) {
       outline.hidden = true;
       return;
     }
-    const r = el2.getBoundingClientRect();
+    const r = visualRect(el2);
     outline.hidden = false;
     outline.classList.toggle("g-picked", picked);
     Object.assign(outline.style, { left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px` });
@@ -2453,9 +2739,9 @@ function startAuthoring(options) {
     label.style.top = r.top < 30 ? "100%" : "-24px";
   };
   const elementAt = (x, y) => {
-    const el2 = doc.elementFromPoint(x, y);
+    const el2 = deepElementFromPoint(doc, x, y);
     if (!el2 || isGuidelyElement(el2) || el2 === doc.documentElement || el2 === doc.body) return null;
-    return el2;
+    return componentAnchor(el2);
   };
   const onMove = (e) => {
     if (!picking || stopped) return;
@@ -2470,7 +2756,7 @@ function startAuthoring(options) {
   };
   const onClick = (e) => {
     if (!picking || stopped) return;
-    if (e.target && isGuidelyElement(e.target)) return;
+    if (isGuidelyElement(composedTarget(e))) return;
     const el2 = elementAt(e.clientX, e.clientY) ?? hovered;
     if (!el2) return;
     e.preventDefault();
@@ -2483,8 +2769,7 @@ function startAuthoring(options) {
   };
   const swallow = (e) => {
     if (!picking || stopped) return;
-    const t = e.target;
-    if (t && isGuidelyElement(t)) return;
+    if (isGuidelyElement(composedTarget(e))) return;
     e.preventDefault();
     e.stopPropagation();
   };
@@ -2542,7 +2827,7 @@ function previewStep(step, theme, options = {}) {
     name: "Preview",
     kind: "flow",
     version: 0,
-    config: { steps: [previewStepConfig], targeting: { id: "root", op: "and", rules: [] }, trigger: { type: "manual", delayMs: 0 }, frequency: { mode: "every_time", cooldownHours: 0, priority: 0, mutuallyExclusiveWith: [], reshowAfterDismiss: true }, appearance: options.appearance ?? { theme: "auto", animation: "fade" }, urlPatterns: [], platforms: ["web"] }
+    config: { steps: [previewStepConfig], visibility: "everyone", targeting: { id: "root", op: "and", rules: [] }, trigger: { type: "manual", delayMs: 0 }, frequency: { mode: "every_time", cooldownHours: 0, priority: 0, mutuallyExclusiveWith: [], reshowAfterDismiss: true }, appearance: options.appearance ?? { theme: "auto", animation: "fade" }, urlPatterns: [], platforms: ["web"] }
   };
   const controller = runGuide(guide, { theme, doc: options.doc, onEnd: () => options.onEnd?.(), onNavigate: () => {
   }, onAction: () => {
@@ -2555,17 +2840,15 @@ function highlightSelectors(selectors, options = {}) {
   const scope = createScope(null, { theme: "light", animation: "none" }, doc);
   const boxes = [];
   const counts = [];
-  let resolved = null;
+  const resolved = resolveTarget(selectors, doc);
   const matched = /* @__PURE__ */ new Set();
   selectors.forEach((s) => {
     const els = querySelectorStrategy(s, doc).filter((el2) => !isGuidelyElement(el2));
-    const visible = els.filter(isVisible);
     counts.push(els.length);
-    if (!resolved && visible.length === 1) resolved = visible[0];
     els.forEach((el2) => matched.add(el2));
   });
   matched.forEach((el2) => {
-    const r = el2.getBoundingClientRect();
+    const r = visualRect(el2);
     const box = doc.createElement("div");
     box.className = "g-highlight";
     Object.assign(box.style, { left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px` });
@@ -2586,12 +2869,19 @@ function highlightSelectors(selectors, options = {}) {
 0 && (module.exports = {
   DEFAULT_THEME,
   HOST_ID,
+  SHADOW_SEPARATOR,
   STYLES,
   TargetTimeoutError,
   anchor,
   applyTheme,
   buildCard,
+  closestComposed,
+  componentAnchor,
+  composedParent,
+  composedTarget,
+  containsComposed,
   createScope,
+  deepElementFromPoint,
   describeElement,
   destroyHost,
   enhancePdfViewers,
@@ -2625,10 +2915,12 @@ function highlightSelectors(selectors, options = {}) {
   sanitizeHtml,
   sanitizeToFragment,
   setSanitizedHtml,
+  shadowHostChain,
   startAuthoring,
   textSnapshotOf,
   trackRect,
   urlMatches,
+  visualRect,
   waitForTarget
 });
 //# sourceMappingURL=index.cjs.map