@trail-cli/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,932 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/guide-loader.ts
+import { parseGuideJson } from "@trail-cli/guide-schema";
+async function loadGuide(url) {
+  let response;
+  try {
+    response = await fetch(url, { credentials: "same-origin" });
+  } catch {
+    return { success: false, kind: "network-error" };
+  }
+  if (!response.ok) {
+    return { success: false, kind: response.status === 404 ? "not-found" : "server-error" };
+  }
+  const text = await response.text();
+  const result = parseGuideJson(text);
+  if (!result.success) {
+    return { success: false, kind: "invalid", issues: result.issues };
+  }
+  return { success: true, guide: result.guide };
+}
+
+// src/session-storage.ts
+var STORAGE_KEY = "trail:checkpoint";
+function safeSessionStorage() {
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function saveCheckpoint(checkpoint) {
+  const storage = safeSessionStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(STORAGE_KEY, JSON.stringify(checkpoint));
+  } catch {
+  }
+}
+function loadCheckpoint(release, guideId) {
+  const storage = safeSessionStorage();
+  if (!storage) return null;
+  try {
+    const raw = storage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed.release === release && parsed.guideId === guideId && typeof parsed.stepIndex === "number" && Number.isInteger(parsed.stepIndex) && typeof parsed.stepId === "string") {
+      return { release, guideId, stepIndex: parsed.stepIndex, stepId: parsed.stepId };
+    }
+    storage.removeItem(STORAGE_KEY);
+    return null;
+  } catch {
+    clearCheckpoint();
+    return null;
+  }
+}
+function clearCheckpoint() {
+  const storage = safeSessionStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(STORAGE_KEY);
+  } catch {
+  }
+}
+
+// src/state.ts
+function resolveCheckpointIndex(guide, checkpoint) {
+  if (!checkpoint) return 0;
+  const index = guide.steps.findIndex((step) => step.id === checkpoint.stepId);
+  return index >= 0 ? index : null;
+}
+var GuideState = class {
+  constructor(guide, startIndex = 0) {
+    __publicField(this, "guide");
+    __publicField(this, "index");
+    this.guide = guide;
+    this.index = Math.min(Math.max(startIndex, 0), guide.steps.length - 1);
+  }
+  get currentIndex() {
+    return this.index;
+  }
+  get currentStep() {
+    return this.guide.steps[this.index];
+  }
+  get total() {
+    return this.guide.steps.length;
+  }
+  get isFirst() {
+    return this.index === 0;
+  }
+  get isLast() {
+    return this.index === this.guide.steps.length - 1;
+  }
+  next() {
+    if (this.isLast) return false;
+    this.index += 1;
+    return true;
+  }
+  back() {
+    if (this.isFirst) return false;
+    this.index -= 1;
+    return true;
+  }
+  reset() {
+    this.index = 0;
+  }
+};
+
+// src/highlight.ts
+var PADDING = 6;
+var Spotlight = class {
+  constructor(container) {
+    __publicField(this, "box");
+    __publicField(this, "blockers");
+    __publicField(this, "target", null);
+    __publicField(this, "resizeObserver", null);
+    __publicField(this, "rafHandle", null);
+    __publicField(this, "scheduleReposition", () => {
+      if (this.rafHandle !== null) return;
+      this.rafHandle = requestAnimationFrame(() => {
+        this.rafHandle = null;
+        this.reposition();
+      });
+    });
+    this.box = document.createElement("div");
+    this.box.className = "tg-spotlight";
+    this.blockers = Array.from({ length: 4 }, () => {
+      const blocker = document.createElement("div");
+      blocker.className = "tg-blocker";
+      container.appendChild(blocker);
+      return blocker;
+    });
+    container.appendChild(this.box);
+    window.addEventListener("resize", this.scheduleReposition);
+    window.addEventListener("scroll", this.scheduleReposition, true);
+  }
+  attachTo(element) {
+    this.detachObserver();
+    this.target = element;
+    this.resizeObserver = new ResizeObserver(this.scheduleReposition);
+    this.resizeObserver.observe(element);
+    this.box.style.display = "block";
+    this.blockers.forEach((blocker) => blocker.style.display = "block");
+    this.reposition();
+  }
+  hide() {
+    this.target = null;
+    this.detachObserver();
+    this.box.style.display = "none";
+    this.blockers.forEach((blocker) => blocker.style.display = "none");
+  }
+  destroy() {
+    this.hide();
+    window.removeEventListener("resize", this.scheduleReposition);
+    window.removeEventListener("scroll", this.scheduleReposition, true);
+    this.blockers.forEach((blocker) => blocker.remove());
+    this.box.remove();
+  }
+  detachObserver() {
+    var _a;
+    (_a = this.resizeObserver) == null ? void 0 : _a.disconnect();
+    this.resizeObserver = null;
+  }
+  reposition() {
+    if (!this.target) return;
+    const rect = this.target.getBoundingClientRect();
+    this.box.style.top = `${rect.top - PADDING}px`;
+    this.box.style.left = `${rect.left - PADDING}px`;
+    this.box.style.width = `${rect.width + PADDING * 2}px`;
+    this.box.style.height = `${rect.height + PADDING * 2}px`;
+    const top = Math.max(0, rect.top - PADDING);
+    const left = Math.max(0, rect.left - PADDING);
+    const right = Math.min(window.innerWidth, rect.right + PADDING);
+    const bottom = Math.min(window.innerHeight, rect.bottom + PADDING);
+    const dimensions = [
+      [0, 0, window.innerWidth, top],
+      [0, top, left, bottom - top],
+      [right, top, window.innerWidth - right, bottom - top],
+      [0, bottom, window.innerWidth, window.innerHeight - bottom]
+    ];
+    this.blockers.forEach((blocker, index) => {
+      const [blockerLeft, blockerTop, width, height] = dimensions[index];
+      Object.assign(blocker.style, {
+        left: `${blockerLeft}px`,
+        top: `${blockerTop}px`,
+        width: `${width}px`,
+        height: `${height}px`
+      });
+    });
+  }
+};
+
+// src/overlay.ts
+var STYLE_ID = "trail-sdk-styles";
+var STYLES = `
+.tg-root { position: fixed; inset: 0; z-index: 2147483647; pointer-events: none; }
+.tg-spotlight {
+  position: fixed;
+  display: none;
+  border: 2px solid #4f7cff;
+  border-radius: 6px;
+  box-shadow: 0 0 0 9999px rgba(15, 17, 26, 0.55);
+  pointer-events: none;
+  transition: top 120ms ease, left 120ms ease, width 120ms ease, height 120ms ease;
+}
+.tg-blocker { position: fixed; z-index: 0; pointer-events: auto; }
+.tg-panel {
+  position: fixed;
+  right: 20px;
+  bottom: 20px;
+  z-index: 2;
+  width: 320px;
+  max-width: calc(100vw - 40px);
+  background: #12131a;
+  color: #f4f5f7;
+  border-radius: 12px;
+  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.45);
+  padding: 16px 18px;
+  font: 14px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  pointer-events: auto;
+}
+.tg-panel-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; }
+.tg-progress-text { font-size: 12px; font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; color: #9aa1b5; }
+.tg-exit-btn {
+  background: transparent; border: none; color: #9aa1b5; font-size: 18px; line-height: 1; cursor: pointer;
+  padding: 4px; border-radius: 6px;
+}
+.tg-exit-btn:hover, .tg-exit-btn:focus-visible { color: #f4f5f7; background: rgba(255,255,255,0.08); }
+.tg-progress-bar { height: 4px; border-radius: 2px; background: rgba(255,255,255,0.12); overflow: hidden; margin-bottom: 12px; }
+.tg-progress-fill { height: 100%; background: #4f7cff; transition: width 160ms ease; }
+.tg-title { margin: 0 0 6px; font-size: 15px; font-weight: 700; }
+.tg-instruction { margin: 0 0 16px; color: #d4d7e2; white-space: pre-line; }
+.tg-panel-footer { display: flex; justify-content: space-between; gap: 8px; }
+.tg-btn {
+  appearance: none; border: 1px solid rgba(255,255,255,0.18); background: rgba(255,255,255,0.06);
+  color: #f4f5f7; padding: 8px 14px; border-radius: 8px; font-size: 13px; font-weight: 600; cursor: pointer;
+}
+.tg-btn:hover { background: rgba(255,255,255,0.14); }
+.tg-btn:focus-visible { outline: 2px solid #4f7cff; outline-offset: 2px; }
+.tg-btn:disabled { opacity: 0.4; cursor: not-allowed; }
+.tg-btn-primary { background: #4f7cff; border-color: #4f7cff; }
+.tg-btn-primary:hover { background: #3f6ce0; }
+.tg-error .tg-title { color: #ff6b6b; }
+.tg-error-detail { font-size: 12px; color: #9aa1b5; margin: -8px 0 16px; }
+`;
+function injectStyles() {
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = STYLES;
+  document.head.appendChild(style);
+}
+var FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+var Overlay = class {
+  constructor(callbacks) {
+    __publicField(this, "root");
+    __publicField(this, "panel");
+    __publicField(this, "spotlight");
+    __publicField(this, "callbacks");
+    __publicField(this, "keydownHandler", null);
+    __publicField(this, "previousBodyOverflow");
+    __publicField(this, "previouslyFocusedElement");
+    __publicField(this, "focusTarget", null);
+    injectStyles();
+    this.callbacks = callbacks;
+    this.previouslyFocusedElement = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    this.root = document.createElement("div");
+    this.root.className = "tg-root";
+    this.panel = document.createElement("div");
+    this.panel.className = "tg-panel";
+    this.panel.setAttribute("role", "dialog");
+    this.panel.setAttribute("aria-label", "Trail guide");
+    this.panel.setAttribute("aria-live", "polite");
+    this.panel.tabIndex = -1;
+    this.root.appendChild(this.panel);
+    this.spotlight = new Spotlight(this.root);
+    document.body.appendChild(this.root);
+    this.previousBodyOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    this.keydownHandler = (event) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        this.callbacks.onExit();
+        return;
+      }
+      if (event.key === "Tab") {
+        this.trapTabFocus(event);
+      }
+    };
+    document.addEventListener("keydown", this.keydownHandler, true);
+  }
+  /** Keeps focus cycling between the guided target and the panel controls. */
+  trapTabFocus(event) {
+    var _a;
+    const panelFocusable = Array.from(this.panel.querySelectorAll(FOCUSABLE_SELECTOR)).filter(
+      (el) => el.offsetParent !== null || el === document.activeElement
+    );
+    const focusTarget = this.focusTarget && this.focusTarget.isConnected && this.focusTarget.matches(FOCUSABLE_SELECTOR) && (this.focusTarget.offsetParent !== null || this.focusTarget === document.activeElement) ? this.focusTarget : null;
+    const focusable = focusTarget ? [focusTarget, ...panelFocusable] : panelFocusable;
+    if (focusable.length === 0) {
+      event.preventDefault();
+      this.focusPanel();
+      return;
+    }
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const active = document.activeElement;
+    if (active === this.panel || !focusable.includes(active)) {
+      event.preventDefault();
+      (event.shiftKey ? last : first).focus();
+      return;
+    }
+    if (focusTarget && active === focusTarget) {
+      event.preventDefault();
+      (event.shiftKey ? last : (_a = panelFocusable[0]) != null ? _a : focusTarget).focus();
+      return;
+    }
+    if (event.shiftKey && focusTarget && active === panelFocusable[0]) {
+      event.preventDefault();
+      focusTarget.focus();
+      return;
+    }
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+  renderStep(model) {
+    const progressPct = Math.round(model.stepNumber / model.totalSteps * 100);
+    this.panel.className = "tg-panel";
+    this.panel.innerHTML = `
+      <div class="tg-panel-header">
+        <span class="tg-progress-text">Step ${model.stepNumber} of ${model.totalSteps}</span>
+        <button type="button" class="tg-exit-btn" aria-label="Exit Trail guide">&times;</button>
+      </div>
+      <div class="tg-progress-bar"><div class="tg-progress-fill" style="width:${progressPct}%"></div></div>
+      <h2 class="tg-title"></h2>
+      <p class="tg-instruction"></p>
+      <div class="tg-panel-footer">
+        <button type="button" class="tg-btn tg-back-btn">Back</button>
+        <button type="button" class="tg-btn tg-btn-primary tg-next-btn"></button>
+      </div>
+    `;
+    this.panel.querySelector(".tg-title").textContent = model.title;
+    this.panel.querySelector(".tg-instruction").textContent = model.instruction;
+    const backBtn = this.panel.querySelector(".tg-back-btn");
+    backBtn.disabled = !model.canGoBack;
+    backBtn.addEventListener("click", () => this.callbacks.onBack());
+    const nextBtn = this.panel.querySelector(".tg-next-btn");
+    nextBtn.disabled = !model.canGoNext;
+    nextBtn.textContent = model.nextLabel;
+    nextBtn.addEventListener("click", () => this.callbacks.onNext());
+    this.panel.querySelector(".tg-exit-btn").addEventListener("click", () => this.callbacks.onExit());
+    this.focusPanel();
+  }
+  setFocusTarget(element) {
+    this.focusTarget = element;
+  }
+  scrollToTarget(element) {
+    document.body.style.overflow = this.previousBodyOverflow;
+    element.scrollIntoView({ behavior: "auto", block: "center", inline: "nearest" });
+    document.body.style.overflow = "hidden";
+  }
+  setNextEnabled(enabled) {
+    const nextBtn = this.panel.querySelector(".tg-next-btn");
+    if (nextBtn) nextBtn.disabled = !enabled;
+  }
+  renderLocating(model) {
+    this.spotlight.hide();
+    this.panel.className = "tg-panel";
+    this.panel.innerHTML = `
+      <div class="tg-panel-header">
+        <span class="tg-progress-text">Step ${model.stepNumber} of ${model.totalSteps}</span>
+        <button type="button" class="tg-exit-btn" aria-label="Exit Trail guide">&times;</button>
+      </div>
+      <h2 class="tg-title"></h2>
+      <p class="tg-instruction"></p>
+      <p class="tg-error-detail">Locating element on the page&hellip;</p>
+    `;
+    this.panel.querySelector(".tg-title").textContent = model.title;
+    this.panel.querySelector(".tg-instruction").textContent = model.instruction;
+    this.panel.querySelector(".tg-exit-btn").addEventListener("click", () => this.callbacks.onExit());
+    this.focusPanel();
+  }
+  renderError(model) {
+    var _a;
+    this.spotlight.hide();
+    this.panel.className = "tg-panel tg-error";
+    this.panel.innerHTML = `
+      <div class="tg-panel-header">
+        <span class="tg-progress-text">Trail</span>
+        <button type="button" class="tg-exit-btn" aria-label="Exit Trail guide">&times;</button>
+      </div>
+      <h2 class="tg-title"></h2>
+      <p class="tg-instruction"></p>
+      ${model.detail ? `<p class="tg-error-detail"></p>` : ""}
+      <div class="tg-panel-footer">
+        ${model.showRetry ? '<button type="button" class="tg-btn tg-retry-btn">Retry</button>' : "<span></span>"}
+        <button type="button" class="tg-btn tg-btn-primary tg-exit-btn2">Exit</button>
+      </div>
+    `;
+    this.panel.querySelector(".tg-title").textContent = model.title;
+    this.panel.querySelector(".tg-instruction").textContent = model.message;
+    if (model.detail) {
+      this.panel.querySelector(".tg-error-detail").textContent = model.detail;
+    }
+    this.panel.querySelector(".tg-exit-btn").addEventListener("click", () => this.callbacks.onExit());
+    this.panel.querySelector(".tg-exit-btn2").addEventListener("click", () => this.callbacks.onExit());
+    (_a = this.panel.querySelector(".tg-retry-btn")) == null ? void 0 : _a.addEventListener("click", () => this.callbacks.onRetry());
+    this.focusPanel();
+  }
+  renderComplete(title, totalSteps, onRestart) {
+    this.spotlight.hide();
+    this.panel.className = "tg-panel";
+    this.panel.innerHTML = `
+      <h2 class="tg-title">Trail Guide Complete</h2>
+      <p class="tg-instruction"></p>
+      <div class="tg-panel-footer">
+        <button type="button" class="tg-btn tg-restart-btn">Restart</button>
+        <button type="button" class="tg-btn tg-btn-primary tg-exit-btn">Exit</button>
+      </div>
+    `;
+    this.panel.querySelector(".tg-instruction").textContent = `${title} \u2014 ${totalSteps} of ${totalSteps} steps completed.`;
+    this.panel.querySelector(".tg-restart-btn").addEventListener("click", onRestart);
+    this.panel.querySelector(".tg-exit-btn").addEventListener("click", () => this.callbacks.onExit());
+    this.focusPanel();
+  }
+  focusPanel() {
+    this.panel.focus({ preventScroll: true });
+  }
+  destroy() {
+    var _a;
+    this.spotlight.destroy();
+    if (this.keydownHandler) {
+      document.removeEventListener("keydown", this.keydownHandler, true);
+    }
+    document.body.style.overflow = this.previousBodyOverflow;
+    this.root.remove();
+    if ((_a = this.previouslyFocusedElement) == null ? void 0 : _a.isConnected) {
+      this.previouslyFocusedElement.focus({ preventScroll: true });
+    }
+  }
+};
+
+// src/target-resolver.ts
+import { TARGET_STRATEGY_ORDER } from "@trail-cli/guide-schema";
+var IMPLICIT_ROLE_SELECTORS = {
+  button: 'button, input[type="button"], input[type="submit"], input[type="reset"], [role="button"]',
+  link: 'a[href], [role="link"]',
+  textbox: 'input:not([type]), input[type="text"], input[type="email"], input[type="search"], input[type="tel"], input[type="url"], input[type="password"], textarea, [role="textbox"]',
+  checkbox: 'input[type="checkbox"], [role="checkbox"]',
+  radio: 'input[type="radio"], [role="radio"]',
+  combobox: 'select, [role="combobox"]',
+  option: 'option, [role="option"]',
+  heading: 'h1, h2, h3, h4, h5, h6, [role="heading"]',
+  tab: '[role="tab"]'
+};
+function normalize(text) {
+  return (text != null ? text : "").trim().replace(/\s+/g, " ").toLowerCase();
+}
+function isVisible(el) {
+  if (!(el instanceof HTMLElement)) return false;
+  if (el.hidden) return false;
+  const style = window.getComputedStyle(el);
+  return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+}
+function cssEscape(value) {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") return CSS.escape(value);
+  return value.replace(/([^\w-])/g, "\\$1");
+}
+function accessibleName(el) {
+  const ariaLabel = el.getAttribute("aria-label");
+  if (ariaLabel) return normalize(ariaLabel);
+  const labelledBy = el.getAttribute("aria-labelledby");
+  if (labelledBy) {
+    const text = labelledBy.split(/\s+/).map((id) => {
+      var _a, _b;
+      return (_b = (_a = document.getElementById(id)) == null ? void 0 : _a.textContent) != null ? _b : "";
+    }).join(" ");
+    if (text.trim()) return normalize(text);
+  }
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    if (el.value) return normalize(el.value);
+    if (el.placeholder) return normalize(el.placeholder);
+  }
+  return normalize(el.textContent);
+}
+function findByTestId(testId) {
+  const element = document.querySelector(
+    `[data-testid="${cssEscape(testId)}"]`
+  );
+  return { strategy: "testId", detail: `[data-testid="${testId}"]`, found: !!element, element };
+}
+function findByRole(role, name) {
+  var _a, _b;
+  const selector = (_a = IMPLICIT_ROLE_SELECTORS[role]) != null ? _a : `[role="${role}"]`;
+  const candidates = Array.from(document.querySelectorAll(selector)).filter(isVisible);
+  const target = normalize(name);
+  const element = (_b = candidates.find((el) => accessibleName(el) === target)) != null ? _b : null;
+  return { strategy: "role", detail: `role="${role}" name="${name}"`, found: !!element, element };
+}
+function findByLabel(label) {
+  const target = normalize(label);
+  const labels = Array.from(document.querySelectorAll("label"));
+  for (const labelEl of labels) {
+    if (normalize(labelEl.textContent) !== target) continue;
+    const forId = labelEl.getAttribute("for");
+    if (forId) {
+      const control = document.getElementById(forId);
+      if (control instanceof HTMLElement && isVisible(control)) {
+        return { strategy: "label", detail: `label="${label}"`, found: true, element: control };
+      }
+    }
+    const nested = labelEl.querySelector("input, select, textarea");
+    if (nested && isVisible(nested)) {
+      return { strategy: "label", detail: `label="${label}"`, found: true, element: nested };
+    }
+  }
+  return { strategy: "label", detail: `label="${label}"`, found: false, element: null };
+}
+var TEXT_CANDIDATE_SELECTOR = 'button, a, [role="button"], [role="link"], input[type="submit"], input[type="button"], *';
+function findByText(text) {
+  const target = normalize(text);
+  let best = null;
+  let bestScore = Infinity;
+  for (const el of document.querySelectorAll(TEXT_CANDIDATE_SELECTOR)) {
+    if (!isVisible(el)) continue;
+    const ownText = normalize(el.textContent);
+    if (!ownText || !ownText.includes(target)) continue;
+    const score = el.children.length + ownText.length;
+    if (score < bestScore) {
+      best = el;
+      bestScore = score;
+    }
+  }
+  return { strategy: "text", detail: `text="${text}"`, found: !!best, element: best };
+}
+function findBySelector(selector) {
+  let element = null;
+  try {
+    element = document.querySelector(selector);
+  } catch {
+  }
+  return { strategy: "selector", detail: selector, found: !!element, element };
+}
+function resolveTarget(target) {
+  const attempts = [];
+  for (const strategy of TARGET_STRATEGY_ORDER) {
+    let result;
+    if (strategy === "testId" && target.testId) {
+      result = findByTestId(target.testId);
+    } else if (strategy === "role" && target.role && target.name) {
+      result = findByRole(target.role, target.name);
+    } else if (strategy === "label" && target.label) {
+      result = findByLabel(target.label);
+    } else if (strategy === "text" && target.text) {
+      result = findByText(target.text);
+    } else if (strategy === "selector" && target.selector) {
+      result = findBySelector(target.selector);
+    } else {
+      continue;
+    }
+    attempts.push({ strategy: result.strategy, detail: result.detail, found: result.found });
+    if (result.element) {
+      return { element: result.element, attempts };
+    }
+  }
+  return { element: null, attempts };
+}
+
+// src/dom-watcher.ts
+function waitForElement(resolve, options = {}) {
+  var _a, _b;
+  const timeoutMs = (_a = options.timeoutMs) != null ? _a : 1e4;
+  const root = (_b = options.root) != null ? _b : document.body;
+  let settled = false;
+  let observer = null;
+  let timer = null;
+  let rafHandle = null;
+  const cleanup = () => {
+    observer == null ? void 0 : observer.disconnect();
+    observer = null;
+    if (timer !== null) clearTimeout(timer);
+    if (rafHandle !== null) cancelAnimationFrame(rafHandle);
+  };
+  let resolvePromise;
+  const promise = new Promise((res) => {
+    resolvePromise = res;
+  });
+  const settle = (result) => {
+    if (settled) return;
+    settled = true;
+    cleanup();
+    resolvePromise(result);
+  };
+  const attempt = () => {
+    if (settled) return;
+    const element = resolve();
+    if (element) {
+      settle({ element, timedOut: false });
+    }
+  };
+  const scheduleAttempt = () => {
+    if (rafHandle !== null) return;
+    rafHandle = requestAnimationFrame(() => {
+      rafHandle = null;
+      attempt();
+    });
+  };
+  attempt();
+  if (!settled) {
+    observer = new MutationObserver(scheduleAttempt);
+    observer.observe(root, { childList: true, subtree: true, attributes: true, characterData: true });
+    timer = setTimeout(() => settle({ element: null, timedOut: true }), timeoutMs);
+  }
+  return {
+    promise,
+    cancel: () => settle({ element: null, timedOut: false })
+  };
+}
+
+// src/spa-router.ts
+var LOCATION_CHANGE_EVENT = "trail:locationchange";
+var patched = false;
+function ensurePatched() {
+  if (patched) return;
+  patched = true;
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+  history.pushState = function patchedPushState(...args) {
+    const result = originalPushState(...args);
+    window.dispatchEvent(new Event(LOCATION_CHANGE_EVENT));
+    return result;
+  };
+  history.replaceState = function patchedReplaceState(...args) {
+    const result = originalReplaceState(...args);
+    window.dispatchEvent(new Event(LOCATION_CHANGE_EVENT));
+    return result;
+  };
+  window.addEventListener("popstate", () => {
+    window.dispatchEvent(new Event(LOCATION_CHANGE_EVENT));
+  });
+}
+function onLocationChange(listener) {
+  ensurePatched();
+  window.addEventListener(LOCATION_CHANGE_EVENT, listener);
+  return () => window.removeEventListener(LOCATION_CHANGE_EVENT, listener);
+}
+
+// src/engine.ts
+var DEFAULT_TARGET_TIMEOUT_MS = 1e4;
+var TrailEngine = class {
+  constructor(options) {
+    __publicField(this, "guide");
+    __publicField(this, "release");
+    __publicField(this, "state");
+    __publicField(this, "overlay");
+    __publicField(this, "unsubscribeLocation");
+    __publicField(this, "onExitCallback");
+    __publicField(this, "cancelWait", null);
+    __publicField(this, "cancelStepCompletion", null);
+    __publicField(this, "currentStepComplete", false);
+    __publicField(this, "destroyed", false);
+    this.guide = options.guide;
+    this.release = options.release;
+    this.state = new GuideState(options.guide, options.startIndex);
+    this.onExitCallback = options.onExit;
+    this.overlay = new Overlay({
+      onNext: () => this.next(),
+      onBack: () => this.back(),
+      onExit: () => this.exit(),
+      onRetry: () => this.activateCurrentStep()
+    });
+    this.unsubscribeLocation = onLocationChange(() => {
+      if (!this.currentStepComplete) this.activateCurrentStep();
+    });
+    this.activateCurrentStep();
+  }
+  next() {
+    var _a;
+    if (this.destroyed || !this.currentStepComplete) return;
+    (_a = this.cancelWait) == null ? void 0 : _a.call(this);
+    if (this.state.isLast) {
+      this.complete();
+      return;
+    }
+    this.state.next();
+    this.activateCurrentStep();
+  }
+  back() {
+    var _a;
+    if (this.destroyed) return;
+    (_a = this.cancelWait) == null ? void 0 : _a.call(this);
+    this.state.back();
+    this.activateCurrentStep();
+  }
+  exit() {
+    var _a;
+    if (this.destroyed) return;
+    clearCheckpoint();
+    this.destroy();
+    (_a = this.onExitCallback) == null ? void 0 : _a.call(this);
+  }
+  destroy() {
+    var _a, _b;
+    if (this.destroyed) return;
+    this.destroyed = true;
+    (_a = this.cancelWait) == null ? void 0 : _a.call(this);
+    (_b = this.cancelStepCompletion) == null ? void 0 : _b.call(this);
+    this.unsubscribeLocation();
+    this.overlay.destroy();
+  }
+  persist() {
+    saveCheckpoint({
+      release: this.release,
+      guideId: this.guide.id,
+      stepIndex: this.state.currentIndex,
+      stepId: this.state.currentStep.id
+    });
+  }
+  activateCurrentStep() {
+    var _a, _b, _c;
+    if (this.destroyed) return;
+    (_a = this.cancelWait) == null ? void 0 : _a.call(this);
+    (_b = this.cancelStepCompletion) == null ? void 0 : _b.call(this);
+    this.cancelStepCompletion = null;
+    this.currentStepComplete = false;
+    this.overlay.setFocusTarget(null);
+    this.persist();
+    const step = this.state.currentStep;
+    if (step.action === "navigate") {
+      this.handleNavigateStep(step);
+      return;
+    }
+    const target = "target" in step ? step.target : void 0;
+    if (!target) {
+      this.renderReady(null, step);
+      return;
+    }
+    this.overlay.renderLocating({
+      stepNumber: this.state.currentIndex + 1,
+      totalSteps: this.state.total,
+      title: this.guide.title,
+      instruction: step.instruction
+    });
+    const timeoutMs = step.action === "wait" ? (_c = step.timeoutMs) != null ? _c : DEFAULT_TARGET_TIMEOUT_MS : DEFAULT_TARGET_TIMEOUT_MS;
+    const { promise, cancel } = waitForElement(() => resolveTarget(target).element, { timeoutMs });
+    this.cancelWait = cancel;
+    promise.then((result) => {
+      if (this.destroyed) return;
+      if (result.timedOut || !result.element) {
+        this.renderMissingTarget(step, target);
+        return;
+      }
+      this.overlay.scrollToTarget(result.element);
+      this.renderReady(result.element, step);
+    });
+  }
+  handleNavigateStep(step) {
+    const destination = new URL(step.url, window.location.origin);
+    if (window.location.pathname === destination.pathname) {
+      this.renderReady(null, step);
+      return;
+    }
+    saveCheckpoint({
+      release: this.release,
+      guideId: this.guide.id,
+      stepIndex: Math.min(this.state.currentIndex + 1, this.state.total - 1),
+      stepId: this.guide.steps[Math.min(this.state.currentIndex + 1, this.state.total - 1)].id
+    });
+    destination.searchParams.set("trail", this.guide.id);
+    destination.searchParams.set("release", this.release);
+    window.location.assign(destination.toString());
+  }
+  renderReady(element, step) {
+    this.overlay.setFocusTarget(element);
+    if (element) {
+      this.overlay.spotlight.attachTo(element);
+    } else {
+      this.overlay.spotlight.hide();
+    }
+    this.overlay.renderStep({
+      stepNumber: this.state.currentIndex + 1,
+      totalSteps: this.state.total,
+      title: this.guide.title,
+      instruction: step.instruction,
+      canGoBack: !this.state.isFirst,
+      canGoNext: this.watchStepCompletion(element, step),
+      nextLabel: this.state.isLast ? "Finish" : "Next"
+    });
+  }
+  watchStepCompletion(element, step) {
+    if (!element || step.action === "verify" || step.action === "wait" || step.action === "navigate") {
+      this.currentStepComplete = true;
+      return true;
+    }
+    const controller = new AbortController();
+    this.cancelStepCompletion = () => controller.abort();
+    const complete = () => {
+      this.currentStepComplete = true;
+      this.overlay.setNextEnabled(true);
+      if (step.autoAdvance) this.next();
+    };
+    if (step.action === "input" || step.action === "select") {
+      const isExpectedValue = () => (element instanceof HTMLInputElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement) && element.value === step.value;
+      const updateCompletion = () => {
+        if (isExpectedValue()) {
+          complete();
+          return;
+        }
+        this.currentStepComplete = false;
+        this.overlay.setNextEnabled(false);
+      };
+      element.addEventListener("input", updateCompletion, { signal: controller.signal });
+      element.addEventListener("change", updateCompletion, { signal: controller.signal });
+      const initiallyComplete = isExpectedValue();
+      this.currentStepComplete = initiallyComplete;
+      if (initiallyComplete && step.autoAdvance) {
+        queueMicrotask(() => {
+          if (!controller.signal.aborted && !this.destroyed) complete();
+        });
+      }
+      return initiallyComplete;
+    }
+    element.addEventListener("click", complete, { once: true, signal: controller.signal });
+    return false;
+  }
+  renderMissingTarget(step, target) {
+    const { attempts } = resolveTarget(target);
+    const detail = attempts.map((attempt) => `${attempt.strategy}: ${attempt.detail} \u2014 ${attempt.found ? "found" : "not found"}`).join(" | ");
+    this.overlay.renderError({
+      title: "Target Not Found",
+      message: `${step.instruction}
+
+The application element could not be located. Possible causes: wrong page, application still loading, UI changed, or the guide is outdated.`,
+      detail,
+      showRetry: true
+    });
+  }
+  complete() {
+    var _a;
+    (_a = this.cancelWait) == null ? void 0 : _a.call(this);
+    this.overlay.setFocusTarget(null);
+    clearCheckpoint();
+    this.overlay.renderComplete(this.guide.title, this.state.total, () => this.restart());
+  }
+  restart() {
+    const destination = new URL(this.guide.start.url, window.location.origin);
+    destination.searchParams.set("trail", this.guide.id);
+    destination.searchParams.set("release", this.release);
+    if (window.location.href === destination.toString()) {
+      this.state.reset();
+      this.activateCurrentStep();
+      return;
+    }
+    window.location.assign(destination.toString());
+  }
+};
+
+// src/index.ts
+function resolveGuideRequest(options) {
+  var _a, _b, _c;
+  if (options.guideUrl) {
+    const params2 = new URLSearchParams(new URL(options.guideUrl, window.location.href).search);
+    return {
+      url: options.guideUrl,
+      guideId: (_a = params2.get("trail")) != null ? _a : "unknown",
+      release: (_b = params2.get("release")) != null ? _b : "unknown"
+    };
+  }
+  const params = new URLSearchParams(window.location.search);
+  const guideId = params.get("trail");
+  const release = params.get("release");
+  if (!guideId || !release) return null;
+  const base = ((_c = options.guideBaseUrl) != null ? _c : "/guides").replace(/\/$/, "");
+  return { url: `${base}/releases/${release}/${guideId}.json`, guideId, release };
+}
+function showStandaloneError(title, message, detail) {
+  const overlay = new Overlay({
+    onNext: () => {
+    },
+    onBack: () => {
+    },
+    onRetry: () => overlay.destroy(),
+    onExit: () => overlay.destroy()
+  });
+  overlay.renderError({ title, message, detail, showRetry: false });
+}
+async function init(options = {}) {
+  var _a;
+  const request = resolveGuideRequest(options);
+  if (!request) return null;
+  const result = await loadGuide(request.url);
+  if (!result.success && result.kind === "not-found") {
+    showStandaloneError("Trail Guide Not Found", `${request.guideId}
+Release ${request.release}`);
+    return null;
+  }
+  if (!result.success && result.kind === "network-error") {
+    showStandaloneError("Unable to Load Trail Guide", "Check your network connection and try again.");
+    return null;
+  }
+  if (!result.success && result.kind === "server-error") {
+    showStandaloneError("Unable to Load Trail Guide", "The guide server returned an error. Try again later.");
+    return null;
+  }
+  if (!result.success) {
+    const detail = (_a = result.issues) == null ? void 0 : _a.map((issue) => `${issue.path}: ${issue.message}`).join(" | ");
+    showStandaloneError("Invalid Trail Guide", `${request.guideId} failed validation.`, detail);
+    return null;
+  }
+  const checkpoint = loadCheckpoint(request.release, result.guide.id);
+  const checkpointIndex = resolveCheckpointIndex(result.guide, checkpoint);
+  if (checkpoint && checkpointIndex === null) clearCheckpoint();
+  const startIndex = checkpointIndex != null ? checkpointIndex : 0;
+  return new TrailEngine({
+    guide: result.guide,
+    release: request.release,
+    startIndex
+  });
+}
+var Trail = { init };
+export {
+  Trail,
+  resolveGuideRequest
+};
+//# sourceMappingURL=index.js.map