@guidelytech/guide-runtime 0.7.0 → 0.9.0

package/dist/chunk-VNJPNGZ4.js

@@ -0,0 +1,301 @@
+import {
+  __publicField
+} from "./chunk-PG7CMBHD.js";
+
+// src/selectors.ts
+import { matchUrlPattern } from "@guidelytech/shared/runtime";
+function urlMatches(pattern, url) {
+  if (!pattern) return true;
+  if (matchUrlPattern(pattern, url)) return true;
+  try {
+    const u = new URL(url, "http://localhost");
+    if (!pattern.includes("?") && !pattern.includes("#")) return matchUrlPattern(pattern, u.pathname) || matchUrlPattern(pattern, u.origin + u.pathname);
+  } catch {
+  }
+  return false;
+}
+var TEXT_CANDIDATES = "button, a, [role='button'], [role='link'], [role='tab'], [role='menuitem'], h1, h2, h3, h4, h5, h6, label, summary";
+var HOST_ID = "guidely-root";
+function docOf(root) {
+  return root.nodeType === 9 ? root : root.ownerDocument;
+}
+function hasLayout(doc) {
+  const de = doc.documentElement;
+  if (!de) return false;
+  const r = de.getBoundingClientRect();
+  return r.width > 0 || r.height > 0;
+}
+function normalizeText(text) {
+  return (text || "").replace(/\s+/g, " ").trim();
+}
+function isVisible(el) {
+  if (!el.isConnected) return false;
+  const doc = el.ownerDocument;
+  const win = doc.defaultView;
+  let cur = el;
+  while (cur && cur !== doc.documentElement) {
+    if (cur.hidden) return false;
+    if (win) {
+      const cs = win.getComputedStyle(cur);
+      if (cs.display === "none" || cs.visibility === "hidden") return false;
+    }
+    cur = cur.parentElement ?? cur.getRootNode().host ?? null;
+  }
+  if (hasLayout(doc)) {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return false;
+  }
+  return true;
+}
+function isGuidelyElement(el) {
+  if (!el) return false;
+  const root = el.getRootNode();
+  if (root instanceof ShadowRoot && root.host.id === HOST_ID) return true;
+  return el.id === HOST_ID || !!el.closest?.(`#${HOST_ID}`);
+}
+function safeQueryAll(root, selector) {
+  try {
+    return Array.from(root.querySelectorAll(selector));
+  } catch {
+    return [];
+  }
+}
+function escapeCss(value) {
+  const g = globalThis;
+  if (g.CSS && typeof g.CSS.escape === "function") return g.CSS.escape(value);
+  return value.replace(/["\\]/g, "\\$&");
+}
+function queryXPath(root, expr) {
+  const doc = docOf(root);
+  const d = doc;
+  if (typeof d.evaluate !== "function") return [];
+  try {
+    const result = d.evaluate(expr, root, null, 7, null);
+    const out = [];
+    for (let i = 0; i < result.snapshotLength; i++) {
+      const n = result.snapshotItem(i);
+      if (n && n.nodeType === 1) out.push(n);
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+function queryText(root, text) {
+  const needle = normalizeText(text).toLowerCase();
+  if (!needle) return [];
+  const candidates = safeQueryAll(root, TEXT_CANDIDATES);
+  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) {
+  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)}`);
+    }
+    case "guidely-id": {
+      const id = value.startsWith("#") ? value.slice(1) : value;
+      return safeQueryAll(root, attrSelector("data-guidely-id", id));
+    }
+    case "data-attr":
+    case "aria":
+    case "css":
+      return safeQueryAll(root, value.startsWith("[") || /^[a-z*#.[]/i.test(value) ? value : `[${value}]`);
+    case "text":
+      return queryText(root, value);
+    case "xpath":
+      return queryXPath(root, value);
+    default:
+      return [];
+  }
+}
+function resolveTarget(target, root = document) {
+  const selectors = Array.isArray(target) ? target : target.selectors;
+  for (const strategy of selectors) {
+    const matches = querySelectorStrategy(strategy, root).filter((el) => !isGuidelyElement(el) && isVisible(el));
+    if (matches.length === 1) return matches[0];
+  }
+  return null;
+}
+var TargetTimeoutError = class extends Error {
+  constructor(message = "Target element not found before timeout") {
+    super(message);
+    __publicField(this, "name", "TargetTimeoutError");
+  }
+};
+function waitForTarget(target, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  const root = options.root ?? document;
+  const pollMs = Math.min(250, Math.max(16, options.pollMs ?? 250));
+  return new Promise((resolve, reject) => {
+    const immediate = resolveTarget(target, root);
+    if (immediate) return resolve(immediate);
+    if (options.signal?.aborted) return reject(new DOMException("Aborted", "AbortError"));
+    let done = false;
+    let observer = null;
+    let timer = null;
+    let timeout = null;
+    const cleanup = () => {
+      done = true;
+      observer?.disconnect();
+      if (timer) clearInterval(timer);
+      if (timeout) clearTimeout(timeout);
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+    const check = () => {
+      if (done) return;
+      const el = resolveTarget(target, root);
+      if (el) {
+        cleanup();
+        resolve(el);
+      }
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+    options.signal?.addEventListener("abort", onAbort);
+    const observeRoot = root.nodeType === 9 ? root.documentElement : root;
+    if (typeof MutationObserver !== "undefined" && observeRoot) {
+      observer = new MutationObserver(check);
+      observer.observe(observeRoot, { childList: true, subtree: true, attributes: true, attributeFilter: ["class", "style", "hidden", "id", "data-tour", "data-guidely-id", "aria-label"] });
+    }
+    timer = setInterval(check, pollMs);
+    if (timeoutMs > 0) {
+      timeout = setTimeout(() => {
+        cleanup();
+        reject(new TargetTimeoutError());
+      }, timeoutMs);
+    }
+  });
+}
+var GENERATED_ID = /(\d{4,}|:r[0-9a-z]+:|^radix-|^headlessui-|^mui-|^ember\d|^react-|^\w*-\d+$|__|^[a-f0-9]{8,}$|^svelte-)/i;
+var GENERATED_CLASS = /(^css-|^sc-|^jss\d|^svelte-|^emotion-|^chakra-|^Mui|^_|[0-9a-f]{6,}|^\w{1,2}$|^[a-z]+-\d+$|[:[\]/])/;
+var PREFERRED_DATA_ATTRS = ["data-testid", "data-tour", "data-test", "data-test-id", "data-cy", "data-qa", "data-id", "data-name", "data-guidely"];
+var IGNORED_DATA_ATTRS = /^data-(guidely-id|state|v-|reactid|react|radix|headlessui|svelte|hydrated|orientation|highlighted|focus|key|index|rbd|dnd|rk-|sveltekit)/i;
+function isStableId(id) {
+  return !!id && /^[A-Za-z][\w-]*$/.test(id) && !GENERATED_ID.test(id);
+}
+function isStableClass(cls) {
+  return !!cls && !GENERATED_CLASS.test(cls) && cls.length <= 40;
+}
+function uniqueIn(doc, selector, el) {
+  const all = safeQueryAll(doc, selector);
+  return all.length === 1 && all[0] === el;
+}
+function attrSelector(name, value) {
+  return `[${name}='${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}']`;
+}
+function cssPath(el, doc) {
+  const segments = [];
+  let cur = el;
+  while (cur && cur.nodeType === 1 && cur !== doc.body && cur !== doc.documentElement) {
+    const tag = cur.tagName.toLowerCase();
+    if (isStableId(cur.id)) {
+      segments.unshift(`#${cur.id}`);
+      break;
+    }
+    let seg = tag;
+    const parent = cur.parentElement;
+    if (parent) {
+      const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur.tagName);
+      if (sameTag.length > 1) {
+        const stableCls = Array.from(cur.classList).find((c) => isStableClass(c) && sameTag.filter((s) => s.classList.contains(c)).length === 1);
+        seg += stableCls ? `.${escapeCss(stableCls)}` : `:nth-of-type(${sameTag.indexOf(cur) + 1})`;
+      }
+    }
+    segments.unshift(seg);
+    const candidate = segments.join(" > ");
+    if (uniqueIn(doc, candidate, el)) return candidate;
+    cur = parent;
+  }
+  const full = segments.join(" > ");
+  return uniqueIn(doc, full, el) ? full : null;
+}
+function textSnapshotOf(el) {
+  const he = el;
+  const own = normalizeText(he.innerText ?? el.textContent);
+  const alt = normalizeText(el.getAttribute("aria-label") || el.getAttribute("title") || el.getAttribute("placeholder") || el.getAttribute("alt") || el.value);
+  return (own || alt).slice(0, 200);
+}
+function generateSelectors(el) {
+  const doc = el.ownerDocument;
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (s) => {
+    const k = `${s.kind}:${s.value}`;
+    if (!seen.has(k)) {
+      seen.add(k);
+      out.push(s);
+    }
+  };
+  const tag = el.tagName.toLowerCase();
+  const guidelyId = el.getAttribute("data-guidely-id");
+  if (guidelyId && uniqueIn(doc, attrSelector("data-guidely-id", guidelyId), el)) push({ kind: "guidely-id", value: guidelyId, label: `Guidely id ${guidelyId}` });
+  if (isStableId(el.id) && uniqueIn(doc, `#${escapeCss(el.id)}`, el)) push({ kind: "id", value: `#${el.id}`, label: `id ${el.id}` });
+  const dataAttrs = Array.from(el.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);
+    const ib = PREFERRED_DATA_ATTRS.indexOf(b.name);
+    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+  });
+  for (const a of dataAttrs) {
+    const sel = attrSelector(a.name, a.value);
+    if (uniqueIn(doc, sel, el)) push({ kind: "data-attr", value: sel, label: `${a.name}=${a.value}` });
+    else if (uniqueIn(doc, tag + sel, el)) push({ kind: "data-attr", value: tag + sel, label: `${a.name}=${a.value}` });
+  }
+  const aria = el.getAttribute("aria-label");
+  if (aria && aria.length <= 120) {
+    const sel = attrSelector("aria-label", aria);
+    if (uniqueIn(doc, sel, el)) push({ kind: "aria", value: sel, label: aria });
+    else if (uniqueIn(doc, tag + sel, el)) push({ kind: "aria", value: tag + sel, label: aria });
+  }
+  const name = el.getAttribute("name");
+  if (name && uniqueIn(doc, tag + attrSelector("name", name), el)) push({ kind: "css", value: tag + attrSelector("name", name), label: `${tag} name=${name}` });
+  const role = el.getAttribute("role");
+  if (role) {
+    const title = el.getAttribute("title") || el.getAttribute("aria-labelledby");
+    const sel = title ? `[role='${role}']${attrSelector(el.getAttribute("title") ? "title" : "aria-labelledby", title)}` : `[role='${role}']`;
+    if (uniqueIn(doc, sel, el)) push({ kind: "css", value: sel, label: `role ${role}` });
+  }
+  if (tag === "a") {
+    const href = el.getAttribute("href");
+    if (href && href.length <= 200 && uniqueIn(doc, `a${attrSelector("href", href)}`, el)) push({ kind: "css", value: `a${attrSelector("href", href)}`, label: `link ${href}` });
+  }
+  const path = cssPath(el, doc);
+  if (path) push({ kind: "css", value: path, label: "css path" });
+  if (/^(button|a|h[1-6]|label|summary)$/.test(tag) || role === "button" || role === "link" || role === "tab" || role === "menuitem") {
+    const text = normalizeText(el.innerText ?? el.textContent);
+    if (text && text.length <= 80) push({ kind: "text", value: text, label: `text "${text}"` });
+  }
+  return out.slice(0, 10);
+}
+function describeElement(el) {
+  const r = el.getBoundingClientRect();
+  return {
+    selectors: generateSelectors(el),
+    textSnapshot: textSnapshotOf(el),
+    rect: { x: r.x, y: r.y, width: r.width, height: r.height },
+    tag: el.tagName.toLowerCase()
+  };
+}
+
+export {
+  urlMatches,
+  normalizeText,
+  isVisible,
+  isGuidelyElement,
+  querySelectorStrategy,
+  resolveTarget,
+  TargetTimeoutError,
+  waitForTarget,
+  isStableId,
+  textSnapshotOf,
+  generateSelectors,
+  describeElement
+};
+//# sourceMappingURL=chunk-VNJPNGZ4.js.map

package/dist/chunk-VNJPNGZ4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/selectors.ts"],"sourcesContent":["import { matchUrlPattern } from \"@guidelytech/shared/runtime\";\nimport type { SelectorStrategy, StepTarget } from \"@guidelytech/shared\";\n\n/**\n * URL matching used for `step.url`, `urlPatterns` and `trigger.urlPattern`: a pattern matches the\n * full URL, the path+query+hash, or the bare path (so `/deals` also matches `/deals?x=1`).\n */\nexport function urlMatches(pattern: string | undefined | null, url: string): boolean {\n  if (!pattern) return true;\n  if (matchUrlPattern(pattern, url)) return true;\n  try {\n    const u = new URL(url, \"http://localhost\");\n    if (!pattern.includes(\"?\") && !pattern.includes(\"#\")) return matchUrlPattern(pattern, u.pathname) || matchUrlPattern(pattern, u.origin + u.pathname);\n  } catch {\n    /* ignore */\n  }\n  return false;\n}\n\nexport type QueryRoot = Document | DocumentFragment | Element;\n\nconst TEXT_CANDIDATES =\n  \"button, a, [role='button'], [role='link'], [role='tab'], [role='menuitem'], h1, h2, h3, h4, h5, h6, label, summary\";\n\nconst HOST_ID = \"guidely-root\";\n\nfunction docOf(root: QueryRoot): Document {\n  return root.nodeType === 9 ? (root as Document) : (root.ownerDocument as Document);\n}\n\n/** True when the environment has a layout engine (real browsers). happy-dom/jsdom report zero sizes. */\nfunction hasLayout(doc: Document): boolean {\n  const de = doc.documentElement;\n  if (!de) return false;\n  const r = de.getBoundingClientRect();\n  return r.width > 0 || r.height > 0;\n}\n\n/** Normalises whitespace in a text snippet. */\nexport function normalizeText(text: string | null | undefined): string {\n  return (text || \"\").replace(/\\s+/g, \" \").trim();\n}\n\n/** Is the element rendered (not hidden by `hidden`, `display:none`, `visibility:hidden`, or zero size)? */\nexport function isVisible(el: Element): boolean {\n  if (!el.isConnected) return false;\n  const doc = el.ownerDocument;\n  const win = doc.defaultView;\n  let cur: Element | null = el;\n  while (cur && cur !== doc.documentElement) {\n    if ((cur as HTMLElement).hidden) return false;\n    if (win) {\n      const cs = win.getComputedStyle(cur);\n      if (cs.display === \"none\" || cs.visibility === \"hidden\") return false;\n    }\n    cur = cur.parentElement ?? ((cur.getRootNode() as ShadowRoot).host as Element | undefined) ?? null;\n  }\n  if (hasLayout(doc)) {\n    const r = el.getBoundingClientRect();\n    if (r.width === 0 && r.height === 0) return false;\n  }\n  return true;\n}\n\n/** Elements that belong to Guidely's own UI are never valid targets. */\nexport function isGuidelyElement(el: Element | null): boolean {\n  if (!el) return false;\n  const root = el.getRootNode();\n  if (root instanceof ShadowRoot && root.host.id === HOST_ID) return true;\n  return el.id === HOST_ID || !!el.closest?.(`#${HOST_ID}`);\n}\n\nfunction safeQueryAll(root: QueryRoot, selector: string): Element[] {\n  try {\n    return Array.from(root.querySelectorAll(selector));\n  } catch {\n    return [];\n  }\n}\n\nfunction escapeCss(value: string): string {\n  const g = globalThis as { CSS?: { escape?: (v: string) => string } };\n  if (g.CSS && typeof g.CSS.escape === \"function\") return g.CSS.escape(value);\n  return value.replace(/[\"\\\\]/g, \"\\\\$&\");\n}\n\nfunction queryXPath(root: QueryRoot, expr: string): Element[] {\n  const doc = docOf(root);\n  const d = doc as Document & { evaluate?: Document[\"evaluate\"] };\n  if (typeof d.evaluate !== \"function\") return [];\n  try {\n    const result = d.evaluate(expr, root, null, 7 /* ORDERED_NODE_SNAPSHOT_TYPE */, null);\n    const out: Element[] = [];\n    for (let i = 0; i < result.snapshotLength; i++) {\n      const n = result.snapshotItem(i);\n      if (n && n.nodeType === 1) out.push(n as Element);\n    }\n    return out;\n  } catch {\n    return [];\n  }\n}\n\nfunction queryText(root: QueryRoot, text: string): Element[] {\n  const needle = normalizeText(text).toLowerCase();\n  if (!needle) return [];\n  const candidates = safeQueryAll(root, TEXT_CANDIDATES);\n  const exact = candidates.filter((c) => normalizeText(c.textContent).toLowerCase() === needle);\n  if (exact.length) return exact;\n  return candidates.filter((c) => normalizeText(c.textContent).toLowerCase().includes(needle));\n}\n\n/** Resolves every element matching one strategy (visible or not). */\nexport function querySelectorStrategy(strategy: SelectorStrategy, root: QueryRoot): Element[] {\n  const value = strategy.value.trim();\n  if (!value) return [];\n  switch (strategy.kind) {\n    case \"id\": {\n      const id = value.startsWith(\"#\") ? value.slice(1) : value;\n      return safeQueryAll(root, `#${escapeCss(id)}`);\n    }\n    case \"guidely-id\": {\n      const id = value.startsWith(\"#\") ? value.slice(1) : value;\n      return safeQueryAll(root, attrSelector(\"data-guidely-id\", id));\n    }\n    case \"data-attr\":\n    case \"aria\":\n    case \"css\":\n      return safeQueryAll(root, value.startsWith(\"[\") || /^[a-z*#.[]/i.test(value) ? value : `[${value}]`);\n    case \"text\":\n      return queryText(root, value);\n    case \"xpath\":\n      return queryXPath(root, value);\n    default:\n      return [];\n  }\n}\n\n/**\n * Resolves a step target by trying each strategy in order. A strategy wins only when it\n * resolves to exactly one *visible* element; otherwise the next strategy is tried.\n */\nexport function resolveTarget(target: Pick<StepTarget, \"selectors\"> | SelectorStrategy[], root: QueryRoot = document): Element | null {\n  const selectors = Array.isArray(target) ? target : target.selectors;\n  for (const strategy of selectors) {\n    const matches = querySelectorStrategy(strategy, root).filter((el) => !isGuidelyElement(el) && isVisible(el));\n    if (matches.length === 1) return matches[0] as Element;\n  }\n  return null;\n}\n\nexport interface WaitForTargetOptions {\n  /** Give up after this many milliseconds (default 5000). */\n  timeoutMs?: number;\n  /** Abort early. */\n  signal?: AbortSignal;\n  root?: QueryRoot;\n  /** Polling fallback interval (default 250ms, which is also the maximum). */\n  pollMs?: number;\n}\n\nexport class TargetTimeoutError extends Error {\n  override name = \"TargetTimeoutError\";\n  constructor(message = \"Target element not found before timeout\") {\n    super(message);\n  }\n}\n\n/**\n * Waits until `resolveTarget` finds an element. Uses a MutationObserver plus a polling fallback\n * (at most every 250ms) so visibility changes without DOM mutations are also detected.\n */\nexport function waitForTarget(target: Pick<StepTarget, \"selectors\"> | SelectorStrategy[], options: WaitForTargetOptions = {}): Promise<Element> {\n  const timeoutMs = options.timeoutMs ?? 5000;\n  const root = options.root ?? document;\n  const pollMs = Math.min(250, Math.max(16, options.pollMs ?? 250));\n  return new Promise<Element>((resolve, reject) => {\n    const immediate = resolveTarget(target, root);\n    if (immediate) return resolve(immediate);\n    if (options.signal?.aborted) return reject(new DOMException(\"Aborted\", \"AbortError\"));\n    let done = false;\n    let observer: MutationObserver | null = null;\n    let timer: ReturnType<typeof setInterval> | null = null;\n    let timeout: ReturnType<typeof setTimeout> | null = null;\n    const cleanup = () => {\n      done = true;\n      observer?.disconnect();\n      if (timer) clearInterval(timer);\n      if (timeout) clearTimeout(timeout);\n      options.signal?.removeEventListener(\"abort\", onAbort);\n    };\n    const check = () => {\n      if (done) return;\n      const el = resolveTarget(target, root);\n      if (el) {\n        cleanup();\n        resolve(el);\n      }\n    };\n    const onAbort = () => {\n      cleanup();\n      reject(new DOMException(\"Aborted\", \"AbortError\"));\n    };\n    options.signal?.addEventListener(\"abort\", onAbort);\n    const observeRoot = root.nodeType === 9 ? (root as Document).documentElement : (root as Element);\n    if (typeof MutationObserver !== \"undefined\" && observeRoot) {\n      observer = new MutationObserver(check);\n      observer.observe(observeRoot, { childList: true, subtree: true, attributes: true, attributeFilter: [\"class\", \"style\", \"hidden\", \"id\", \"data-tour\", \"data-guidely-id\", \"aria-label\"] });\n    }\n    timer = setInterval(check, pollMs);\n    if (timeoutMs > 0) {\n      timeout = setTimeout(() => {\n        cleanup();\n        reject(new TargetTimeoutError());\n      }, timeoutMs);\n    }\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Selector generation (used by the element picker)\n// ---------------------------------------------------------------------------\n\nconst GENERATED_ID = /(\\d{4,}|:r[0-9a-z]+:|^radix-|^headlessui-|^mui-|^ember\\d|^react-|^\\w*-\\d+$|__|^[a-f0-9]{8,}$|^svelte-)/i;\nconst GENERATED_CLASS = /(^css-|^sc-|^jss\\d|^svelte-|^emotion-|^chakra-|^Mui|^_|[0-9a-f]{6,}|^\\w{1,2}$|^[a-z]+-\\d+$|[:[\\]/])/;\nconst PREFERRED_DATA_ATTRS = [\"data-testid\", \"data-tour\", \"data-test\", \"data-test-id\", \"data-cy\", \"data-qa\", \"data-id\", \"data-name\", \"data-guidely\"];\nconst IGNORED_DATA_ATTRS = /^data-(guidely-id|state|v-|reactid|react|radix|headlessui|svelte|hydrated|orientation|highlighted|focus|key|index|rbd|dnd|rk-|sveltekit)/i;\n\n/** Is this id stable enough to be used as a selector (not generated by a framework)? */\nexport function isStableId(id: string): boolean {\n  return !!id && /^[A-Za-z][\\w-]*$/.test(id) && !GENERATED_ID.test(id);\n}\n\nfunction isStableClass(cls: string): boolean {\n  return !!cls && !GENERATED_CLASS.test(cls) && cls.length <= 40;\n}\n\nfunction uniqueIn(doc: Document, selector: string, el: Element): boolean {\n  const all = safeQueryAll(doc, selector);\n  return all.length === 1 && all[0] === el;\n}\n\nfunction attrSelector(name: string, value: string): string {\n  return `[${name}='${value.replace(/\\\\/g, \"\\\\\\\\\").replace(/'/g, \"\\\\'\")}']`;\n}\n\nfunction cssPath(el: Element, doc: Document): string | null {\n  const segments: string[] = [];\n  let cur: Element | null = el;\n  while (cur && cur.nodeType === 1 && cur !== doc.body && cur !== doc.documentElement) {\n    const tag = cur.tagName.toLowerCase();\n    if (isStableId(cur.id)) {\n      segments.unshift(`#${cur.id}`);\n      break;\n    }\n    let seg = tag;\n    const parent: Element | null = cur.parentElement;\n    if (parent) {\n      const sameTag = Array.from(parent.children).filter((c) => c.tagName === cur!.tagName);\n      if (sameTag.length > 1) {\n        const stableCls = Array.from(cur.classList).find((c) => isStableClass(c) && sameTag.filter((s) => s.classList.contains(c)).length === 1);\n        seg += stableCls ? `.${escapeCss(stableCls)}` : `:nth-of-type(${sameTag.indexOf(cur) + 1})`;\n      }\n    }\n    segments.unshift(seg);\n    const candidate = segments.join(\" > \");\n    if (uniqueIn(doc, candidate, el)) return candidate;\n    cur = parent;\n  }\n  const full = segments.join(\" > \");\n  return uniqueIn(doc, full, el) ? full : null;\n}\n\n/** Short human-readable text for an element, trimmed to 200 characters. */\nexport function textSnapshotOf(el: Element): string {\n  const he = el as HTMLElement;\n  const own = normalizeText(he.innerText ?? el.textContent);\n  const alt = normalizeText(el.getAttribute(\"aria-label\") || el.getAttribute(\"title\") || el.getAttribute(\"placeholder\") || el.getAttribute(\"alt\") || (el as HTMLInputElement).value);\n  return (own || alt).slice(0, 200);\n}\n\n/**\n * Generates an ordered list of selector strategies for an element, most robust first:\n * stable id → data-* attributes → aria-label → role/name → short unique CSS path → visible text.\n */\nexport function generateSelectors(el: Element): SelectorStrategy[] {\n  const doc = el.ownerDocument;\n  const out: SelectorStrategy[] = [];\n  const seen = new Set<string>();\n  const push = (s: SelectorStrategy) => {\n    const k = `${s.kind}:${s.value}`;\n    if (!seen.has(k)) {\n      seen.add(k);\n      out.push(s);\n    }\n  };\n  const tag = el.tagName.toLowerCase();\n\n  // A Guidely id is shared with the mobile apps, so it is the most portable target there is.\n  const guidelyId = el.getAttribute(\"data-guidely-id\");\n  if (guidelyId && uniqueIn(doc, attrSelector(\"data-guidely-id\", guidelyId), el)) push({ kind: \"guidely-id\", value: guidelyId, label: `Guidely id ${guidelyId}` });\n  if (isStableId(el.id) && uniqueIn(doc, `#${escapeCss(el.id)}`, el)) push({ kind: \"id\", value: `#${el.id}`, label: `id ${el.id}` });\n\n  const dataAttrs = Array.from(el.attributes).filter((a) => a.name.startsWith(\"data-\") && !IGNORED_DATA_ATTRS.test(a.name) && a.value && a.value.length <= 120 && !/\\d{5,}/.test(a.value));\n  dataAttrs.sort((a, b) => {\n    const ia = PREFERRED_DATA_ATTRS.indexOf(a.name);\n    const ib = PREFERRED_DATA_ATTRS.indexOf(b.name);\n    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);\n  });\n  for (const a of dataAttrs) {\n    const sel = attrSelector(a.name, a.value);\n    if (uniqueIn(doc, sel, el)) push({ kind: \"data-attr\", value: sel, label: `${a.name}=${a.value}` });\n    else if (uniqueIn(doc, tag + sel, el)) push({ kind: \"data-attr\", value: tag + sel, label: `${a.name}=${a.value}` });\n  }\n\n  const aria = el.getAttribute(\"aria-label\");\n  if (aria && aria.length <= 120) {\n    const sel = attrSelector(\"aria-label\", aria);\n    if (uniqueIn(doc, sel, el)) push({ kind: \"aria\", value: sel, label: aria });\n    else if (uniqueIn(doc, tag + sel, el)) push({ kind: \"aria\", value: tag + sel, label: aria });\n  }\n\n  const name = el.getAttribute(\"name\");\n  if (name && uniqueIn(doc, tag + attrSelector(\"name\", name), el)) push({ kind: \"css\", value: tag + attrSelector(\"name\", name), label: `${tag} name=${name}` });\n  const role = el.getAttribute(\"role\");\n  if (role) {\n    const title = el.getAttribute(\"title\") || el.getAttribute(\"aria-labelledby\");\n    const sel = title ? `[role='${role}']${attrSelector(el.getAttribute(\"title\") ? \"title\" : \"aria-labelledby\", title)}` : `[role='${role}']`;\n    if (uniqueIn(doc, sel, el)) push({ kind: \"css\", value: sel, label: `role ${role}` });\n  }\n  if (tag === \"a\") {\n    const href = el.getAttribute(\"href\");\n    if (href && href.length <= 200 && uniqueIn(doc, `a${attrSelector(\"href\", href)}`, el)) push({ kind: \"css\", value: `a${attrSelector(\"href\", href)}`, label: `link ${href}` });\n  }\n\n  const path = cssPath(el, doc);\n  if (path) push({ kind: \"css\", value: path, label: \"css path\" });\n\n  if (/^(button|a|h[1-6]|label|summary)$/.test(tag) || role === \"button\" || role === \"link\" || role === \"tab\" || role === \"menuitem\") {\n    const text = normalizeText((el as HTMLElement).innerText ?? el.textContent);\n    if (text && text.length <= 80) push({ kind: \"text\", value: text, label: `text \"${text}\"` });\n  }\n  return out.slice(0, 10);\n}\n\nexport interface ElementDescription {\n  selectors: SelectorStrategy[];\n  textSnapshot: string;\n  rect: { x: number; y: number; width: number; height: number };\n  tag: string;\n}\n\n/** Everything the authoring picker needs for one element. */\nexport function describeElement(el: Element): ElementDescription {\n  const r = el.getBoundingClientRect();\n  return {\n    selectors: generateSelectors(el),\n    textSnapshot: textSnapshotOf(el),\n    rect: { x: r.x, y: r.y, width: r.width, height: r.height },\n    tag: el.tagName.toLowerCase(),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -618,7 +618,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)}
@@ -1363,6 +1371,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 +1526,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;
           try {
-            if (t && typeof t.closest === "function" && t.closest(selector)) advance();
+            if (selector ? t && typeof t.closest === "function" && t.closest(selector) : t && target?.contains(t)) advance();
           } catch {
           }
         };
@@ -1551,10 +1570,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 +1596,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 +1658,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 +2167,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 +2223,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 +2238,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 +2248,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 +2271,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 +2280,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 +2292,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 +2303,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 +2385,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 +2408,7 @@ function createHelpView(options) {
     render,
     reset() {
       openSeq++;
-      active = null;
+      setActive(null);
       query = "";
       input.value = "";
       serverResults = [];
@@ -2305,6 +2417,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 +2469,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);
@@ -2542,7 +2662,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: () => {