@ourroadmaps/web-sdk 0.3.0

package/dist/chunk-XFAAEDJK.js

@@ -0,0 +1,1251 @@
+import { __publicField } from './chunk-V6TY7KAL.js';
+
+// src/overlay/targeting.ts
+function isSelectorTarget(target) {
+  return typeof target === "object" && "selector" in target;
+}
+function isCursorTarget(target) {
+  return typeof target === "object" && "cursor" in target && target.cursor === true;
+}
+function isCoordinates(target) {
+  return typeof target === "object" && "x" in target && "y" in target && !("selector" in target);
+}
+function resolveElement(target) {
+  if (isSelectorTarget(target)) {
+    return document.querySelector(target.selector);
+  }
+  return null;
+}
+function getAnchorPosition(rect, anchor = "center") {
+  switch (anchor) {
+    case "top":
+      return { x: rect.left + rect.width / 2, y: rect.top };
+    case "bottom":
+      return { x: rect.left + rect.width / 2, y: rect.bottom };
+    case "left":
+      return { x: rect.left, y: rect.top + rect.height / 2 };
+    case "right":
+      return { x: rect.right, y: rect.top + rect.height / 2 };
+    case "top-left":
+      return { x: rect.left, y: rect.top };
+    case "top-right":
+      return { x: rect.right, y: rect.top };
+    case "bottom-left":
+      return { x: rect.left, y: rect.bottom };
+    case "bottom-right":
+      return { x: rect.right, y: rect.bottom };
+    case "center":
+      return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+  }
+}
+function resolveCoordinates(target, cursorPosition) {
+  if (isCoordinates(target)) {
+    return target;
+  }
+  if (isCursorTarget(target)) {
+    return cursorPosition;
+  }
+  if (isSelectorTarget(target)) {
+    const element = document.querySelector(target.selector);
+    if (!element) {
+      return target.fallback ?? null;
+    }
+    const rect = element.getBoundingClientRect();
+    const position = getAnchorPosition(rect, target.anchor);
+    if (target.offset) {
+      position.x += target.offset.x;
+      position.y += target.offset.y;
+    }
+    return position;
+  }
+  return null;
+}
+function isInViewport(element) {
+  const rect = element.getBoundingClientRect();
+  return rect.top >= 0 && rect.left >= 0 && rect.bottom <= window.innerHeight && rect.right <= window.innerWidth;
+}
+
+// src/overlay/animations.ts
+var DURATIONS = {
+  cursorMove: 600,
+  cursorClick: 150,
+  clickRipple: 400,
+  annotationIn: 200,
+  annotationOut: 150,
+  scrollPause: 300
+};
+var EASINGS = {
+  easeOut: "cubic-bezier(0, 0, 0.2, 1)",
+  easeInOut: "cubic-bezier(0.4, 0, 0.2, 1)",
+  linear: "linear"
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function fadeInKeyframes() {
+  return [
+    { opacity: 0, transform: "scale(0.9)" },
+    { opacity: 1, transform: "scale(1)" }
+  ];
+}
+function fadeOutKeyframes() {
+  return [{ opacity: 1 }, { opacity: 0 }];
+}
+
+// src/overlay/annotations/Base.ts
+var BaseAnnotation = class {
+  constructor(id, config, container, reducedMotion) {
+    __publicField(this, "id");
+    __publicField(this, "config");
+    __publicField(this, "element", null);
+    __publicField(this, "container");
+    __publicField(this, "reducedMotion");
+    __publicField(this, "hideTimeout", null);
+    __publicField(this, "currentAnimation", null);
+    this.id = id;
+    this.config = config;
+    this.container = container;
+    this.reducedMotion = reducedMotion;
+  }
+  /**
+   * Render the annotation with animation
+   */
+  async show() {
+    if (this.config.delay && this.config.delay > 0) {
+      await new Promise((r) => setTimeout(r, this.config.delay));
+    }
+    this.element = this.createElement();
+    if (this.config.color) {
+      this.element.style.setProperty("--annotation-color", this.config.color);
+    }
+    this.container.appendChild(this.element);
+    const duration = this.reducedMotion ? 1 : DURATIONS.annotationIn;
+    this.currentAnimation = this.element.animate(fadeInKeyframes(), {
+      duration,
+      easing: EASINGS.easeOut,
+      fill: "forwards"
+    });
+    await this.currentAnimation.finished;
+    this.currentAnimation = null;
+    if (this.config.duration && this.config.duration > 0) {
+      this.hideTimeout = setTimeout(() => this.hide(), this.config.duration);
+    }
+  }
+  /**
+   * Hide and remove the annotation
+   */
+  async hide() {
+    if (this.hideTimeout) {
+      clearTimeout(this.hideTimeout);
+      this.hideTimeout = null;
+    }
+    if (!this.element) return;
+    const duration = this.reducedMotion ? 1 : DURATIONS.annotationOut;
+    this.currentAnimation = this.element.animate(fadeOutKeyframes(), {
+      duration,
+      easing: EASINGS.linear,
+      fill: "forwards"
+    });
+    await this.currentAnimation.finished;
+    this.currentAnimation = null;
+    this.element.remove();
+    this.element = null;
+  }
+  /**
+   * Cancel any running animations
+   */
+  cancelAnimations() {
+    this.currentAnimation?.cancel();
+    this.currentAnimation = null;
+  }
+  /**
+   * Clean up resources
+   */
+  destroy() {
+    if (this.hideTimeout) {
+      clearTimeout(this.hideTimeout);
+    }
+    this.cancelAnimations();
+    this.element?.remove();
+  }
+};
+
+// src/overlay/annotations/Arrow.ts
+var ARROWHEAD_LENGTH = 12;
+var ARROWHEAD_WIDTH = 8;
+var Arrow = class extends BaseAnnotation {
+  constructor(id, config, container, reducedMotion, cursorPosition) {
+    super(id, config, container, reducedMotion);
+    __publicField(this, "cursorPosition");
+    __publicField(this, "pathElement", null);
+    __publicField(this, "markerDef", null);
+    this.cursorPosition = cursorPosition;
+  }
+  createElement() {
+    const g = document.createElementNS("http://www.w3.org/2000/svg", "g");
+    g.classList.add("arrow");
+    const markerId = `arrowhead-${this.id}`;
+    this.markerDef = document.createElementNS("http://www.w3.org/2000/svg", "defs");
+    const marker = document.createElementNS("http://www.w3.org/2000/svg", "marker");
+    marker.setAttribute("id", markerId);
+    marker.setAttribute("markerWidth", String(ARROWHEAD_LENGTH));
+    marker.setAttribute("markerHeight", String(ARROWHEAD_WIDTH));
+    marker.setAttribute("refX", String(ARROWHEAD_LENGTH));
+    marker.setAttribute("refY", String(ARROWHEAD_WIDTH / 2));
+    marker.setAttribute("orient", "auto");
+    marker.setAttribute("markerUnits", "userSpaceOnUse");
+    const polygon = document.createElementNS("http://www.w3.org/2000/svg", "polygon");
+    polygon.setAttribute(
+      "points",
+      `0,0 ${ARROWHEAD_LENGTH},${ARROWHEAD_WIDTH / 2} 0,${ARROWHEAD_WIDTH}`
+    );
+    polygon.setAttribute("fill", "currentColor");
+    marker.appendChild(polygon);
+    this.markerDef.appendChild(marker);
+    g.appendChild(this.markerDef);
+    this.pathElement = document.createElementNS("http://www.w3.org/2000/svg", "path");
+    this.pathElement.setAttribute("marker-end", `url(#${markerId})`);
+    this.pathElement.setAttribute("fill", "none");
+    this.pathElement.setAttribute("stroke", "currentColor");
+    g.appendChild(this.pathElement);
+    return g;
+  }
+  /**
+   * Update the cursor position for relative positioning
+   */
+  setCursorPosition(coords) {
+    this.cursorPosition = coords;
+    if (this.element) {
+      this.updatePosition();
+    }
+  }
+  resolveTargetPoint(target) {
+    if (isCoordinates(target)) {
+      return resolveCoordinates(target, this.cursorPosition);
+    }
+    if (isCursorTarget(target)) {
+      return this.cursorPosition;
+    }
+    if (isSelectorTarget(target)) {
+      const element = document.querySelector(target.selector);
+      if (!element) {
+        return target.fallback ?? null;
+      }
+      const rect = element.getBoundingClientRect();
+      return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+    }
+    return null;
+  }
+  updatePosition() {
+    if (!this.pathElement) return;
+    const from = this.config.from;
+    const to = this.config.to;
+    const startPoint = this.resolveTargetPoint(from);
+    const endPoint = this.resolveTargetPoint(to);
+    if (!startPoint || !endPoint) return;
+    const d = `M ${startPoint.x} ${startPoint.y} L ${endPoint.x} ${endPoint.y}`;
+    this.pathElement.setAttribute("d", d);
+  }
+  async show() {
+    await super.show();
+    this.updatePosition();
+  }
+  destroy() {
+    this.pathElement = null;
+    this.markerDef = null;
+    super.destroy();
+  }
+};
+
+// src/overlay/annotations/Badge.ts
+var Badge = class extends BaseAnnotation {
+  constructor(id, config, container, reducedMotion, cursorPosition) {
+    super(id, config, container, reducedMotion);
+    __publicField(this, "cursorPosition");
+    this.cursorPosition = cursorPosition;
+  }
+  createElement() {
+    const badge = document.createElement("div");
+    badge.className = "badge";
+    badge.textContent = String(this.config.number);
+    const coords = resolveCoordinates(this.config.target, this.cursorPosition);
+    if (coords) {
+      badge.style.left = `${coords.x}px`;
+      badge.style.top = `${coords.y}px`;
+    }
+    return badge;
+  }
+};
+
+// src/overlay/annotations/Box.ts
+var DEFAULT_PADDING = 4;
+var DEFAULT_RADIUS = 4;
+var Box = class extends BaseAnnotation {
+  constructor(id, config, container, reducedMotion, cursorPosition) {
+    super(id, config, container, reducedMotion);
+    __publicField(this, "cursorPosition");
+    this.cursorPosition = cursorPosition;
+  }
+  createElement() {
+    const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+    rect.classList.add("box");
+    rect.setAttribute("rx", String(DEFAULT_RADIUS));
+    rect.setAttribute("ry", String(DEFAULT_RADIUS));
+    if (this.config.dashed) {
+      rect.setAttribute("stroke-dasharray", "8 4");
+    }
+    return rect;
+  }
+  /**
+   * Update the cursor position for relative positioning
+   */
+  setCursorPosition(coords) {
+    this.cursorPosition = coords;
+    if (this.element) {
+      this.updatePosition();
+    }
+  }
+  updatePosition() {
+    if (!this.element) return;
+    const rect = this.element;
+    const target = this.config.target;
+    const padding = this.config.padding ?? DEFAULT_PADDING;
+    let bounds;
+    if (isSelectorTarget(target)) {
+      const el = document.querySelector(target.selector);
+      if (!el) return;
+      bounds = el.getBoundingClientRect();
+    } else if (isCoordinates(target)) {
+      const resolved = resolveCoordinates(target, this.cursorPosition);
+      if (!resolved) return;
+      const width = this.config.size?.width ?? 100;
+      const height = this.config.size?.height ?? 100;
+      bounds = new DOMRect(resolved.x, resolved.y, width, height);
+    } else {
+      return;
+    }
+    rect.setAttribute("x", String(bounds.left - padding));
+    rect.setAttribute("y", String(bounds.top - padding));
+    rect.setAttribute("width", String(bounds.width + padding * 2));
+    rect.setAttribute("height", String(bounds.height + padding * 2));
+  }
+  async show() {
+    await super.show();
+    this.updatePosition();
+  }
+};
+
+// src/overlay/annotations/Circle.ts
+var DEFAULT_PADDING2 = 4;
+var Circle = class extends BaseAnnotation {
+  constructor(id, config, container, reducedMotion, cursorPosition) {
+    super(id, config, container, reducedMotion);
+    __publicField(this, "cursorPosition");
+    this.cursorPosition = cursorPosition;
+  }
+  createElement() {
+    const ellipse = document.createElementNS("http://www.w3.org/2000/svg", "ellipse");
+    ellipse.classList.add("circle");
+    return ellipse;
+  }
+  /**
+   * Update the cursor position for relative positioning
+   */
+  setCursorPosition(coords) {
+    this.cursorPosition = coords;
+    if (this.element) {
+      this.updatePosition();
+    }
+  }
+  updatePosition() {
+    if (!this.element) return;
+    const ellipse = this.element;
+    const target = this.config.target;
+    const padding = this.config.padding ?? DEFAULT_PADDING2;
+    let bounds;
+    if (isSelectorTarget(target)) {
+      const el = document.querySelector(target.selector);
+      if (!el) return;
+      bounds = el.getBoundingClientRect();
+    } else if (isCoordinates(target)) {
+      const resolved = resolveCoordinates(target, this.cursorPosition);
+      if (!resolved) return;
+      const width = this.config.size?.width ?? 100;
+      const height = this.config.size?.height ?? 100;
+      bounds = new DOMRect(resolved.x, resolved.y, width, height);
+    } else {
+      return;
+    }
+    const cx = bounds.left + bounds.width / 2;
+    const cy = bounds.top + bounds.height / 2;
+    const rx = bounds.width / 2 + padding;
+    const ry = bounds.height / 2 + padding;
+    ellipse.setAttribute("cx", String(cx));
+    ellipse.setAttribute("cy", String(cy));
+    ellipse.setAttribute("rx", String(rx));
+    ellipse.setAttribute("ry", String(ry));
+  }
+  async show() {
+    await super.show();
+    this.updatePosition();
+  }
+};
+
+// src/overlay/annotations/Label.ts
+var DEFAULT_GAP = 8;
+var Label = class extends BaseAnnotation {
+  constructor(id, config, container, reducedMotion, cursorPosition) {
+    super(id, config, container, reducedMotion);
+    __publicField(this, "cursorPosition");
+    this.cursorPosition = cursorPosition;
+  }
+  createElement() {
+    const el = document.createElement("div");
+    el.className = "label";
+    el.textContent = this.config.text;
+    return el;
+  }
+  /**
+   * Update the cursor position for relative positioning
+   */
+  setCursorPosition(coords) {
+    this.cursorPosition = coords;
+    if (this.element) {
+      this.updatePosition();
+    }
+  }
+  updatePosition() {
+    if (!this.element) return;
+    const target = this.config.target;
+    const position = this.config.position || "top";
+    const gap = this.config.gap ?? DEFAULT_GAP;
+    let anchorRect;
+    if (isCursorTarget(target)) {
+      if (!this.cursorPosition) return;
+      anchorRect = new DOMRect(this.cursorPosition.x, this.cursorPosition.y, 0, 0);
+    } else if (isCoordinates(target)) {
+      const resolved = resolveCoordinates(target, this.cursorPosition);
+      if (!resolved) return;
+      anchorRect = new DOMRect(resolved.x, resolved.y, 0, 0);
+    } else if (isSelectorTarget(target)) {
+      const el = document.querySelector(target.selector);
+      if (!el) return;
+      anchorRect = el.getBoundingClientRect();
+    } else {
+      return;
+    }
+    const coords = this.calculatePosition(anchorRect, position, gap);
+    this.element.style.left = `${coords.x}px`;
+    this.element.style.top = `${coords.y}px`;
+    this.element.style.transform = this.getTransform(position);
+  }
+  calculatePosition(rect, position, gap) {
+    const centerX = rect.left + rect.width / 2;
+    const centerY = rect.top + rect.height / 2;
+    switch (position) {
+      case "top":
+        return { x: centerX, y: rect.top - gap };
+      case "top-left":
+        return { x: rect.left, y: rect.top - gap };
+      case "top-right":
+        return { x: rect.right, y: rect.top - gap };
+      case "bottom":
+        return { x: centerX, y: rect.bottom + gap };
+      case "bottom-left":
+        return { x: rect.left, y: rect.bottom + gap };
+      case "bottom-right":
+        return { x: rect.right, y: rect.bottom + gap };
+      case "left":
+        return { x: rect.left - gap, y: centerY };
+      case "right":
+        return { x: rect.right + gap, y: centerY };
+      default:
+        return { x: centerX, y: rect.top - gap };
+    }
+  }
+  getTransform(position) {
+    switch (position) {
+      case "top":
+      case "bottom":
+        return "translate(-50%, -100%)";
+      case "top-left":
+      case "bottom-left":
+        return "translate(0, -100%)";
+      case "top-right":
+      case "bottom-right":
+        return "translate(-100%, -100%)";
+      case "left":
+        return "translate(-100%, -50%)";
+      case "right":
+        return "translate(0, -50%)";
+      default:
+        return "translate(-50%, -100%)";
+    }
+  }
+  async show() {
+    await super.show();
+    this.updatePosition();
+  }
+};
+
+// src/overlay/AnnotationManager.ts
+var idCounter = 0;
+function generateId() {
+  return `ann-${++idCounter}`;
+}
+var AnnotationManager = class {
+  constructor(config, domContainer, svgContainer, reducedMotion, getCursorPosition) {
+    __publicField(this, "config");
+    __publicField(this, "domContainer");
+    __publicField(this, "svgContainer");
+    __publicField(this, "annotations", /* @__PURE__ */ new Map());
+    __publicField(this, "reducedMotion");
+    __publicField(this, "getCursorPosition");
+    this.config = config;
+    this.domContainer = domContainer;
+    this.svgContainer = svgContainer;
+    this.reducedMotion = reducedMotion;
+    this.getCursorPosition = getCursorPosition;
+  }
+  get activeIds() {
+    return Array.from(this.annotations.keys());
+  }
+  show(input) {
+    if (Array.isArray(input)) {
+      return input.map((a) => this.showOne(a));
+    }
+    return this.showOne(input);
+  }
+  showOne(annotation) {
+    const id = annotation.id ?? generateId();
+    const cursorPos = this.getCursorPosition();
+    const annotationWithDefaults = {
+      ...annotation,
+      color: annotation.color ?? this.config.color
+    };
+    let instance;
+    switch (annotation.type) {
+      case "arrow":
+        instance = new Arrow(
+          id,
+          annotationWithDefaults,
+          this.svgContainer,
+          // SVG for arrows
+          this.reducedMotion,
+          cursorPos
+        );
+        break;
+      case "badge":
+        instance = new Badge(
+          id,
+          annotationWithDefaults,
+          this.domContainer,
+          this.reducedMotion,
+          cursorPos
+        );
+        break;
+      case "box":
+        instance = new Box(
+          id,
+          annotationWithDefaults,
+          this.svgContainer,
+          // SVG for boxes
+          this.reducedMotion,
+          cursorPos
+        );
+        break;
+      case "circle":
+        instance = new Circle(
+          id,
+          annotationWithDefaults,
+          this.svgContainer,
+          // SVG for circles
+          this.reducedMotion,
+          cursorPos
+        );
+        break;
+      case "label":
+        instance = new Label(
+          id,
+          annotationWithDefaults,
+          this.domContainer,
+          this.reducedMotion,
+          cursorPos
+        );
+        break;
+      default:
+        throw new Error(`Unknown annotation type: ${annotation.type}`);
+    }
+    this.annotations.set(id, instance);
+    instance.show();
+    return id;
+  }
+  hide(input) {
+    const ids = Array.isArray(input) ? input : [input];
+    for (const id of ids) {
+      const annotation = this.annotations.get(id);
+      if (annotation) {
+        annotation.hide();
+        this.annotations.delete(id);
+      }
+    }
+  }
+  hideAll() {
+    for (const annotation of this.annotations.values()) {
+      annotation.hide();
+    }
+    this.annotations.clear();
+  }
+  // Convenience methods
+  arrow(from, to, options) {
+    return this.show({ type: "arrow", from, to, ...options });
+  }
+  badge(target, number, options) {
+    return this.show({ type: "badge", target, number, ...options });
+  }
+  box(target, options) {
+    return this.show({ type: "box", target, ...options });
+  }
+  circle(target, options) {
+    return this.show({ type: "circle", target, ...options });
+  }
+  label(target, text, options) {
+    return this.show({ type: "label", target, text, ...options });
+  }
+  cancelAllAnimations() {
+    for (const annotation of this.annotations.values()) {
+      annotation.cancelAnimations();
+    }
+  }
+  destroy() {
+    for (const annotation of this.annotations.values()) {
+      annotation.destroy();
+    }
+    this.annotations.clear();
+  }
+};
+
+// src/shared/colors.ts
+function hexToRgb(hex) {
+  const cleaned = hex.replace("#", "");
+  const bigint = parseInt(cleaned, 16);
+  return [bigint >> 16 & 255, bigint >> 8 & 255, bigint & 255];
+}
+function getLuminance(hex) {
+  const [r, g, b] = hexToRgb(hex).map((c) => {
+    const sRGB = c / 255;
+    return sRGB <= 0.03928 ? sRGB / 12.92 : ((sRGB + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function getContrastColor(hex) {
+  return getLuminance(hex) > 0.5 ? "black" : "white";
+}
+
+// src/overlay/scroller.ts
+async function scrollIntoViewIfNeeded(element) {
+  const rect = element.getBoundingClientRect();
+  const isFullyVisible = rect.top >= 0 && rect.left >= 0 && rect.bottom <= window.innerHeight && rect.right <= window.innerWidth;
+  if (isFullyVisible) {
+    return;
+  }
+  return new Promise((resolve) => {
+    element.scrollIntoView({
+      behavior: "smooth",
+      block: "center",
+      inline: "center"
+    });
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0];
+        if (entry?.isIntersecting) {
+          observer.disconnect();
+          resolve();
+        }
+      },
+      { threshold: 0.5 }
+    );
+    observer.observe(element);
+    setTimeout(() => {
+      observer.disconnect();
+      resolve();
+    }, 1e3);
+  });
+}
+
+// src/overlay/Cursor.ts
+var CURSOR_ARROW_SVG = `<svg class="cursor-arrow" viewBox="0 0 24 24">
+  <path d="M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a.5.5 0 0 1 .35-.15h6.87a.5.5 0 0 0 .35-.85L6.35 2.85a.5.5 0 0 0-.85.36Z"/>
+</svg>`;
+var Cursor = class {
+  constructor(container, reducedMotion) {
+    __publicField(this, "container");
+    __publicField(this, "element");
+    __publicField(this, "labelElement");
+    __publicField(this, "rippleElement");
+    __publicField(this, "currentAnimation", null);
+    __publicField(this, "activeRipples", /* @__PURE__ */ new Set());
+    __publicField(this, "_position", null);
+    __publicField(this, "_isVisible", true);
+    __publicField(this, "reducedMotion");
+    this.container = container;
+    this.reducedMotion = reducedMotion;
+    this.element = document.createElement("div");
+    this.element.className = "cursor";
+    this.element.innerHTML = `${CURSOR_ARROW_SVG}<div class="cursor-label">Guide</div>`;
+    this.labelElement = this.element.querySelector(".cursor-label");
+    this.rippleElement = document.createElement("div");
+    this.rippleElement.className = "click-ripple";
+    container.appendChild(this.element);
+    container.appendChild(this.rippleElement);
+  }
+  get position() {
+    return this._position;
+  }
+  get isVisible() {
+    return this._isVisible;
+  }
+  show() {
+    this._isVisible = true;
+    this.element.classList.remove("hidden");
+  }
+  hide() {
+    this._isVisible = false;
+    this.element.classList.add("hidden");
+  }
+  setName(name) {
+    this.labelElement.textContent = name;
+  }
+  setColor(color) {
+    this.element.style.setProperty("--cursor-color", color);
+    this.element.style.setProperty("--cursor-text-color", getContrastColor(color));
+  }
+  async moveTo(target, options) {
+    const el = resolveElement(target);
+    if (el && !isInViewport(el)) {
+      await scrollIntoViewIfNeeded(el);
+      await delay(DURATIONS.scrollPause);
+    }
+    const coords = resolveCoordinates(target, this._position);
+    if (!coords) {
+      console.warn("[Overlay] Target not found:", target);
+      return;
+    }
+    this.currentAnimation?.cancel();
+    const duration = this.reducedMotion ? 1 : options?.duration ?? DURATIONS.cursorMove;
+    const from = this._position ?? coords;
+    this.currentAnimation = this.element.animate(
+      [
+        { transform: `translate(${from.x}px, ${from.y}px)` },
+        { transform: `translate(${coords.x}px, ${coords.y}px)` }
+      ],
+      { duration, easing: EASINGS.easeInOut, fill: "forwards" }
+    );
+    try {
+      await this.currentAnimation.finished;
+      this._position = coords;
+    } catch {
+    } finally {
+      this.currentAnimation = null;
+    }
+  }
+  async click(target) {
+    if (target) {
+      await this.moveTo(target);
+    }
+    if (!this._position) return;
+    const duration = this.reducedMotion ? 1 : DURATIONS.cursorClick;
+    const pressAnimation = this.element.animate(
+      [
+        { transform: `translate(${this._position.x}px, ${this._position.y}px) scale(1)` },
+        { transform: `translate(${this._position.x}px, ${this._position.y}px) scale(0.85)` },
+        { transform: `translate(${this._position.x}px, ${this._position.y}px) scale(1)` }
+      ],
+      { duration, easing: EASINGS.easeOut }
+    );
+    this.showRipple(this._position);
+    await pressAnimation.finished;
+  }
+  showRipple(position) {
+    const ripple = this.rippleElement.cloneNode();
+    ripple.style.left = `${position.x}px`;
+    ripple.style.top = `${position.y}px`;
+    this.container.appendChild(ripple);
+    this.activeRipples.add(ripple);
+    const duration = this.reducedMotion ? 1 : DURATIONS.clickRipple;
+    const animation = ripple.animate(
+      [
+        { opacity: 0.4, transform: "translate(-50%, -50%) scale(0)" },
+        { opacity: 0, transform: "translate(-50%, -50%) scale(2)" }
+      ],
+      { duration, easing: EASINGS.easeOut }
+    );
+    animation.onfinish = () => {
+      ripple.remove();
+      this.activeRipples.delete(ripple);
+    };
+  }
+  cancelAnimations() {
+    this.currentAnimation?.cancel();
+    this.currentAnimation = null;
+    for (const r of this.activeRipples) {
+      r.remove();
+    }
+    this.activeRipples.clear();
+  }
+  destroy() {
+    this.cancelAnimations();
+    this.element.remove();
+    this.rippleElement.remove();
+  }
+};
+
+// src/overlay/styles.ts
+var OVERLAY_STYLES = `
+:host {
+  all: initial;
+}
+
+.overlay-container {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: var(--overlay-z-index, 9999);
+  overflow: hidden;
+}
+
+/* Cursor */
+.cursor {
+  position: absolute;
+  display: flex;
+  align-items: flex-start;
+  gap: 2px;
+  filter: drop-shadow(0 2px 4px rgba(0,0,0,0.2));
+  will-change: transform;
+  transition: opacity 0.15s ease-out;
+}
+
+.cursor.hidden {
+  opacity: 0;
+  pointer-events: none;
+}
+
+.cursor-arrow {
+  width: 20px;
+  height: 20px;
+  fill: var(--cursor-color, #3B82F6);
+}
+
+.cursor-label {
+  background: var(--cursor-color, #3B82F6);
+  color: var(--cursor-text-color, white);
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 12px;
+  font-weight: 500;
+  padding: 4px 8px;
+  border-radius: 4px;
+  white-space: nowrap;
+  margin-top: 12px;
+}
+
+/* Click Ripple */
+.click-ripple {
+  position: absolute;
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  background: var(--cursor-color, #3B82F6);
+  opacity: 0;
+  transform: translate(-50%, -50%) scale(0);
+  pointer-events: none;
+}
+
+/* Annotations SVG Layer */
+.annotations-svg {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+
+/* Annotations DOM Layer */
+.annotations-dom {
+  position: absolute;
+  inset: 0;
+}
+
+/* Badge */
+.badge {
+  position: absolute;
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  background: var(--annotation-color, #EF4444);
+  color: white;
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 14px;
+  font-weight: 600;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transform: translate(-50%, -50%);
+}
+
+/* Label */
+.label {
+  position: absolute;
+  background: var(--annotation-color, #EF4444);
+  color: white;
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 14px;
+  font-weight: 500;
+  padding: 6px 12px;
+  border-radius: 6px;
+  max-width: 280px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+}
+
+/* Note: Box, Circle, and Arrow annotations use SVG elements
+   styled via attributes, not CSS classes */
+
+/* Reduced Motion */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+`;
+
+// src/overlay/Timeline.ts
+var Timeline = class {
+  constructor(cursor, annotations, callbacks) {
+    __publicField(this, "cursor");
+    __publicField(this, "annotations");
+    __publicField(this, "callbacks");
+    __publicField(this, "isRunning", false);
+    __publicField(this, "currentIndex", 0);
+    __publicField(this, "abortController", null);
+    this.cursor = cursor;
+    this.annotations = annotations;
+    this.callbacks = callbacks;
+  }
+  get running() {
+    return this.isRunning;
+  }
+  get actionIndex() {
+    return this.isRunning ? this.currentIndex : null;
+  }
+  async play(script) {
+    if (this.isRunning) {
+      console.warn("[Overlay] Stopping current playback to start new script");
+      this.stop();
+    }
+    this.isRunning = true;
+    this.currentIndex = 0;
+    this.abortController = new AbortController();
+    if (script.cursor) {
+      if (script.cursor.name) this.cursor.setName(script.cursor.name);
+      if (script.cursor.color) this.cursor.setColor(script.cursor.color);
+      if (script.cursor.visible === false) this.cursor.hide();
+      else this.cursor.show();
+    }
+    this.callbacks.onStart();
+    try {
+      for (let i = 0; i < script.actions.length; i++) {
+        if (!this.isRunning) break;
+        this.currentIndex = i;
+        const action = script.actions[i];
+        this.callbacks.onAction(action, i, "start");
+        try {
+          await this.executeAction(action);
+        } catch (err) {
+          if (err instanceof Error && err.name === "AbortError") {
+            break;
+          }
+          this.callbacks.onError(err, action);
+        }
+        this.callbacks.onAction(action, i, "complete");
+      }
+      if (this.isRunning) {
+        this.callbacks.onComplete();
+      }
+    } finally {
+      this.isRunning = false;
+      this.abortController = null;
+    }
+  }
+  stop() {
+    if (!this.isRunning) return;
+    this.isRunning = false;
+    this.abortController?.abort();
+    this.cursor.cancelAnimations();
+    this.annotations.cancelAllAnimations();
+    this.callbacks.onStop();
+  }
+  async executeAction(action) {
+    switch (action.type) {
+      case "move":
+        await this.executeMove(action);
+        break;
+      case "click":
+        await this.executeClick(action);
+        break;
+      case "wait":
+        await this.executeWait(action);
+        break;
+      case "setCursor":
+        this.executeSetCursor(action);
+        break;
+      case "showAnnotations":
+        this.executeShowAnnotations(action);
+        break;
+      case "hideAnnotations":
+        this.executeHideAnnotations(action);
+        break;
+      default:
+        console.warn("[Overlay] Unknown action type:", action.type);
+    }
+  }
+  async executeMove(action) {
+    await this.cursor.moveTo(action.target, { duration: action.duration });
+    if (action.showAnnotations) {
+      this.annotations.show(action.showAnnotations);
+    }
+  }
+  async executeClick(action) {
+    await this.cursor.click(action.target);
+  }
+  async executeWait(action) {
+    await delay(action.duration);
+  }
+  executeSetCursor(action) {
+    if (action.visible !== void 0) {
+      if (action.visible) this.cursor.show();
+      else this.cursor.hide();
+    }
+    if (action.name) this.cursor.setName(action.name);
+    if (action.color) this.cursor.setColor(action.color);
+  }
+  executeShowAnnotations(action) {
+    this.annotations.show(action.annotations);
+  }
+  executeHideAnnotations(action) {
+    if (action.ids) {
+      this.annotations.hide(action.ids);
+    } else {
+      this.annotations.hideAll();
+    }
+  }
+  destroy() {
+    this.stop();
+  }
+};
+
+// src/overlay/Overlay.ts
+var DEFAULT_CURSOR_COLOR = "#3B82F6";
+var DEFAULT_ANNOTATION_COLOR = "#EF4444";
+var DEFAULT_Z_INDEX = 9999;
+var _Overlay = class _Overlay {
+  constructor(options = {}) {
+    __publicField(this, "root");
+    __publicField(this, "shadow");
+    __publicField(this, "container");
+    __publicField(this, "svgContainer");
+    __publicField(this, "domContainer");
+    __publicField(this, "_cursor");
+    __publicField(this, "_annotations");
+    __publicField(this, "timeline");
+    __publicField(this, "reducedMotion");
+    __publicField(this, "motionQuery");
+    __publicField(this, "eventHandlers", /* @__PURE__ */ new Map());
+    __publicField(this, "_isDestroyed", false);
+    // Note: Reduced motion preference is checked at construction time for cursor/annotations.
+    // This handler updates our flag but doesn't propagate to already-constructed components.
+    // This is acceptable since reduced motion is typically set before page interaction.
+    __publicField(this, "handleMotionChange", (e) => {
+      this.reducedMotion = e.matches;
+    });
+    const parentContainer = options.container ?? document.body;
+    const zIndex = options.zIndex ?? DEFAULT_Z_INDEX;
+    this.motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    this.reducedMotion = this.motionQuery.matches;
+    this.motionQuery.addEventListener("change", this.handleMotionChange);
+    this.root = document.createElement("div");
+    this.root.id = "ourroadmaps-overlay";
+    this.shadow = this.root.attachShadow({ mode: "open" });
+    const styleEl = document.createElement("style");
+    styleEl.textContent = OVERLAY_STYLES;
+    this.shadow.appendChild(styleEl);
+    this.container = document.createElement("div");
+    this.container.className = "overlay-container";
+    this.container.style.setProperty("--overlay-z-index", String(zIndex));
+    this.shadow.appendChild(this.container);
+    this.svgContainer = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    this.svgContainer.setAttribute("class", "annotations-svg");
+    this.container.appendChild(this.svgContainer);
+    this.domContainer = document.createElement("div");
+    this.domContainer.className = "annotations-dom";
+    this.container.appendChild(this.domContainer);
+    const cursorConfig = {
+      name: options.cursor?.name ?? "Guide",
+      color: options.cursor?.color ?? DEFAULT_CURSOR_COLOR,
+      visible: options.cursor?.visible ?? true
+    };
+    this._cursor = new Cursor(this.container, this.reducedMotion);
+    this._cursor.setName(cursorConfig.name);
+    this._cursor.setColor(cursorConfig.color);
+    if (!cursorConfig.visible) this._cursor.hide();
+    const annotationsConfig = {
+      color: options.annotations?.color ?? DEFAULT_ANNOTATION_COLOR,
+      strokeWidth: options.annotations?.strokeWidth ?? 3
+    };
+    this._annotations = new AnnotationManager(
+      annotationsConfig,
+      this.domContainer,
+      this.svgContainer,
+      this.reducedMotion,
+      () => this._cursor.position
+    );
+    this.timeline = new Timeline(this._cursor, this._annotations, {
+      onStart: () => this.emit("start"),
+      onComplete: () => this.emit("complete"),
+      onStop: () => this.emit("stop"),
+      onError: (error, action) => {
+        this.emit("error", {
+          code: "ANIMATION_FAILED",
+          message: error.message,
+          action
+        });
+      },
+      onAction: (action, index, phase) => this.emit("action", action, index, phase)
+    });
+    parentContainer.appendChild(this.root);
+  }
+  // Controller interface
+  get cursor() {
+    return this._cursor;
+  }
+  get annotations() {
+    return this._annotations;
+  }
+  get isPlaying() {
+    return this.timeline.running;
+  }
+  get currentActionIndex() {
+    return this.timeline.actionIndex;
+  }
+  get isDestroyed() {
+    return this._isDestroyed;
+  }
+  validateAction(action, index) {
+    const errors = [];
+    if (!action || typeof action !== "object") {
+      errors.push(`Action ${index} must be an object`);
+      return errors;
+    }
+    const a = action;
+    if (!_Overlay.VALID_ACTION_TYPES.includes(a.type)) {
+      errors.push(`Action ${index} has invalid type: ${a.type}`);
+    }
+    if (a.type === "wait" && typeof a.duration !== "number") {
+      errors.push(`Wait action ${index} must have a numeric duration`);
+    }
+    if (a.type === "move" && !a.target) {
+      errors.push(`Move action ${index} must have a target`);
+    }
+    return errors;
+  }
+  validate(script) {
+    const errors = [];
+    const warnings = [];
+    if (!script || typeof script !== "object") {
+      errors.push("Script must be an object");
+      return { valid: false, errors, warnings };
+    }
+    const s = script;
+    if (s.version !== 1) {
+      errors.push("Script version must be 1");
+    }
+    if (!Array.isArray(s.actions)) {
+      errors.push("Script must have an actions array");
+    } else {
+      for (let i = 0; i < s.actions.length; i++) {
+        errors.push(...this.validateAction(s.actions[i], i));
+      }
+    }
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+  async play(script) {
+    if (this._isDestroyed) {
+      throw new Error("Overlay has been destroyed");
+    }
+    const validation = this.validate(script);
+    if (!validation.valid) {
+      throw new Error(`Invalid script: ${validation.errors.join(", ")}`);
+    }
+    await this.timeline.play(script);
+  }
+  stop() {
+    this.timeline.stop();
+  }
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventHandlers.get(event).add(handler);
+    return () => {
+      this.eventHandlers.get(event)?.delete(handler);
+    };
+  }
+  emit(event, ...args) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          ;
+          handler(...args);
+        } catch (err) {
+          console.error(`[Overlay] Error in ${event} handler:`, err);
+        }
+      }
+    }
+  }
+  destroy() {
+    if (this._isDestroyed) return;
+    this._isDestroyed = true;
+    this.timeline.destroy();
+    this._cursor.destroy();
+    this._annotations.destroy();
+    this.motionQuery.removeEventListener("change", this.handleMotionChange);
+    this.eventHandlers.clear();
+    this.root.remove();
+  }
+};
+__publicField(_Overlay, "VALID_ACTION_TYPES", [
+  "move",
+  "click",
+  "wait",
+  "setCursor",
+  "showAnnotations",
+  "hideAnnotations"
+]);
+var Overlay = _Overlay;
+
+// src/overlay/index.ts
+function createOverlay(options) {
+  return new Overlay(options);
+}
+
+export { Overlay, createOverlay };
+//# sourceMappingURL=chunk-XFAAEDJK.js.map
+//# sourceMappingURL=chunk-XFAAEDJK.js.map