guideagent 0.1.0

package/README.md

@@ -0,0 +1 @@
+http://127.0.0.1:5500/guideagent/test.html 

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+interface LanguageStrings {
+    guide_label: string;
+    next_btn: string;
+    prev_btn: string;
+    finish_btn: string;
+    guide_me_btn: string;
+    guide_complete: string;
+    step_of: string;
+}
+
+interface StepTranslation {
+    title: string;
+    description: string;
+}
+interface Step {
+    selector: string;
+    order: number;
+    translations: Record<string, StepTranslation>;
+}
+
+interface GuideConfig {
+    steps: Step[];
+    language?: string;
+}
+
+declare const GuideAgent: {
+    version: string;
+    init(config: GuideConfig): void;
+    initFromUrl(configUrl: string): Promise<void>;
+    start(): void;
+    stop(): void;
+    setLang(lang: string): void;
+    getStrings(): LanguageStrings;
+    createFloatingButton(): void;
+};
+
+export { GuideAgent as default };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+interface LanguageStrings {
+    guide_label: string;
+    next_btn: string;
+    prev_btn: string;
+    finish_btn: string;
+    guide_me_btn: string;
+    guide_complete: string;
+    step_of: string;
+}
+
+interface StepTranslation {
+    title: string;
+    description: string;
+}
+interface Step {
+    selector: string;
+    order: number;
+    translations: Record<string, StepTranslation>;
+}
+
+interface GuideConfig {
+    steps: Step[];
+    language?: string;
+}
+
+declare const GuideAgent: {
+    version: string;
+    init(config: GuideConfig): void;
+    initFromUrl(configUrl: string): Promise<void>;
+    start(): void;
+    stop(): void;
+    setLang(lang: string): void;
+    getStrings(): LanguageStrings;
+    createFloatingButton(): void;
+};
+
+export { GuideAgent as default };

package/dist/index.js

@@ -0,0 +1,518 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/config/loader.ts
+var loader_exports = {};
+__export(loader_exports, {
+  loadConfig: () => loadConfig
+});
+async function loadConfig(configUrl) {
+  try {
+    const response = await fetch(configUrl);
+    if (!response.ok) {
+      throw new Error(
+        `GuideAgent: Failed to load config from "${configUrl}" \u2014 HTTP ${response.status}`
+      );
+    }
+    const config = await response.json();
+    if (!config.steps || !Array.isArray(config.steps)) {
+      throw new Error(
+        `GuideAgent: Invalid config \u2014 "steps" array missing in "${configUrl}"`
+      );
+    }
+    config.steps.forEach((step, index) => {
+      if (!step.selector) {
+        throw new Error(
+          `GuideAgent: Step ${index + 1} missing "selector" field`
+        );
+      }
+      if (!step.translations) {
+        throw new Error(
+          `GuideAgent: Step ${index + 1} missing "translations" field`
+        );
+      }
+      if (!step.translations["en"]) {
+        throw new Error(
+          `GuideAgent: Step ${index + 1} missing "en" translation \u2014 English is required as fallback`
+        );
+      }
+      Object.entries(step.translations).forEach(([lang, t]) => {
+        if (!t.title) {
+          throw new Error(
+            `GuideAgent: Step ${index + 1} "${lang}" translation missing "title"`
+          );
+        }
+        if (!t.description) {
+          throw new Error(
+            `GuideAgent: Step ${index + 1} "${lang}" translation missing "description"`
+          );
+        }
+      });
+    });
+    console.log(
+      `GuideAgent: Config loaded \u2705 \u2014 ${config.steps.length} steps for page "${config.page}"`
+    );
+    return config;
+  } catch (error) {
+    console.error("GuideAgent config load failed:", error);
+    throw error;
+  }
+}
+var init_loader = __esm({
+  "src/config/loader.ts"() {
+    "use strict";
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/i18n/en.json
+var en_default = {
+  guide_label: "GuideAgent",
+  next_btn: "Next \u2192",
+  prev_btn: "\u2190 Prev",
+  finish_btn: "Finish \u2713",
+  guide_me_btn: "\u{1F9ED} Guide Me",
+  guide_complete: "\u2713 Guide Complete!",
+  step_of: "Step {current} of {total}"
+};
+
+// src/i18n/ta.json
+var ta_default = {
+  guide_label: "Vazhi Kaatti",
+  next_btn: "Aduthu \u2192",
+  prev_btn: "\u2190 Munnaadi",
+  finish_btn: "Mudinthathu \u2713",
+  guide_me_btn: "\u{1F9ED} Vazhi Kaattu",
+  guide_complete: "\u2713 Vazhi Kaattal Mudinthathu!",
+  step_of: "Padi {current} / {total}"
+};
+
+// src/i18n/hi.json
+var hi_default = {
+  guide_label: "GuideAgent",
+  next_btn: "Aage \u2192",
+  prev_btn: "\u2190 Peeche",
+  finish_btn: "Khatam \u2713",
+  guide_me_btn: "\u{1F9ED} Mujhe Guide Karo",
+  guide_complete: "\u2713 Guide Poora Hua!",
+  step_of: "Kadam {current} / {total}"
+};
+
+// src/config/i18n.ts
+var languages = { en: en_default, ta: ta_default, hi: hi_default };
+var currentLang = "en";
+function setLanguage(lang) {
+  if (languages[lang]) {
+    currentLang = lang;
+    console.log(`GuideAgent: Language set to "${lang}" \u2705`);
+  } else {
+    console.warn(`GuideAgent: "${lang}" not supported \u2014 using "en"`);
+    currentLang = "en";
+  }
+}
+function getCurrentLang() {
+  return currentLang;
+}
+function getStrings() {
+  var _a;
+  return (_a = languages[currentLang]) != null ? _a : languages["en"];
+}
+function formatStep(template, current, total) {
+  return template.replace("{current}", String(current)).replace("{total}", String(total));
+}
+
+// src/renderer/highlight.ts
+var highlightBox = null;
+var overlayMask = null;
+function highlight(el) {
+  removeHighlight();
+  const rect = el.getBoundingClientRect();
+  overlayMask = document.createElement("div");
+  Object.assign(overlayMask.style, {
+    position: "fixed",
+    // fixed = stays in place even when user scrolls
+    top: "0",
+    left: "0",
+    width: "100vw",
+    // full screen width
+    height: "100vh",
+    // full screen height
+    backgroundColor: "rgba(0, 0, 0, 0.55)",
+    // semi-transparent black
+    zIndex: "9998",
+    // sits above your portfolio content
+    pointerEvents: "none"
+    // user can still interact with page behind it
+  });
+  highlightBox = document.createElement("div");
+  Object.assign(highlightBox.style, {
+    position: "fixed",
+    top: `${rect.top - 6}px`,
+    // 6px padding above element
+    left: `${rect.left - 6}px`,
+    // 6px padding left of element
+    width: `${rect.width + 12}px`,
+    // 12px wider (6px each side)
+    height: `${rect.height + 12}px`,
+    // 12px taller (6px each side)
+    border: "2px solid #6366f1",
+    // indigo border color
+    borderRadius: "8px",
+    zIndex: "9999",
+    // sits above the dark mask
+    pointerEvents: "none",
+    boxShadow: "0 0 12px rgba(99, 102, 241, 0.6)",
+    // soft glow effect
+    transition: "all 0.3s ease"
+    // smooth animation when moving steps
+  });
+  document.body.appendChild(overlayMask);
+  document.body.appendChild(highlightBox);
+}
+function removeHighlight() {
+  highlightBox == null ? void 0 : highlightBox.remove();
+  overlayMask == null ? void 0 : overlayMask.remove();
+  highlightBox = null;
+  overlayMask = null;
+}
+
+// src/renderer/tooltip.ts
+var tooltipEl = null;
+function showTooltip(el, title, description, onNext, onPrev, isFirst, isLast, currentStep, totalSteps) {
+  var _a, _b;
+  removeTooltip();
+  const s = getStrings();
+  const rect = el.getBoundingClientRect();
+  tooltipEl = document.createElement("div");
+  Object.assign(tooltipEl.style, {
+    position: "fixed",
+    zIndex: "10000",
+    background: "#1e1e2e",
+    color: "#ffffff",
+    padding: "16px 20px",
+    borderRadius: "10px",
+    width: "280px",
+    boxShadow: "0 8px 32px rgba(0,0,0,0.4)",
+    fontFamily: "sans-serif",
+    fontSize: "14px",
+    lineHeight: "1.5",
+    border: "1px solid #6366f1"
+  });
+  tooltipEl.innerHTML = `
+    <div style="
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 8px;
+    ">
+      <span style="font-size:12px; color:#a5b4fc; font-weight:600; text-transform:uppercase;">
+        ${s.guide_label}
+      </span>
+      <span style="font-size:12px; color:#64748b;">
+        ${formatStep(s.step_of, currentStep, totalSteps)}
+      </span>
+    </div>
+
+    <div style="font-size:16px; font-weight:700; margin-bottom:8px; color:#ffffff;">
+      ${title}
+    </div>
+
+    <div style="font-size:14px; color:#cbd5e1; margin-bottom:16px;">
+      ${description}
+    </div>
+
+    <div style="display:flex; gap:8px; justify-content:flex-end;">
+      ${!isFirst ? `
+        <button id="guide-prev-btn" style="
+          background:transparent; color:#a5b4fc;
+          border:1px solid #6366f1; padding:6px 14px;
+          border-radius:6px; cursor:pointer; font-size:13px;
+        ">${s.prev_btn}</button>
+      ` : ""}
+
+      <button id="guide-next-btn" style="
+        background:#6366f1; color:white; border:none;
+        padding:6px 14px; border-radius:6px; cursor:pointer;
+        font-size:13px; font-weight:600;
+      ">${isLast ? s.finish_btn : s.next_btn}</button>
+    </div>
+  `;
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  const tooltipWidth = 280;
+  const tooltipHeight = 180;
+  let top = rect.bottom + 12;
+  let left = rect.left;
+  if (top + tooltipHeight > viewportHeight) {
+    top = rect.top - tooltipHeight - 12;
+  }
+  if (top < 16) {
+    top = viewportHeight / 2 - tooltipHeight / 2;
+  }
+  if (left + tooltipWidth > viewportWidth) {
+    left = viewportWidth - tooltipWidth - 16;
+  }
+  if (left < 16) {
+    left = 16;
+  }
+  tooltipEl.style.top = `${top}px`;
+  tooltipEl.style.left = `${left}px`;
+  document.body.appendChild(tooltipEl);
+  (_a = document.getElementById("guide-next-btn")) == null ? void 0 : _a.addEventListener("click", onNext);
+  (_b = document.getElementById("guide-prev-btn")) == null ? void 0 : _b.addEventListener("click", onPrev);
+}
+function removeTooltip() {
+  tooltipEl == null ? void 0 : tooltipEl.remove();
+  tooltipEl = null;
+}
+
+// src/core/stepManager.ts
+var StepManager = class {
+  constructor(steps) {
+    this.steps = steps.sort((a, b) => a.order - b.order);
+    this.currentIndex = 0;
+  }
+  current() {
+    return this.steps[this.currentIndex];
+  }
+  next() {
+    if (this.currentIndex < this.steps.length - 1) {
+      this.currentIndex++;
+      return this.steps[this.currentIndex];
+    }
+    return null;
+  }
+  prev() {
+    if (this.currentIndex > 0) {
+      this.currentIndex--;
+      return this.steps[this.currentIndex];
+    }
+    return null;
+  }
+  reset() {
+    this.currentIndex = 0;
+  }
+  isFirst() {
+    return this.currentIndex === 0;
+  }
+  isLast() {
+    return this.currentIndex === this.steps.length - 1;
+  }
+  currentNumber() {
+    return this.currentIndex + 1;
+  }
+  totalSteps() {
+    return this.steps.length;
+  }
+};
+
+// src/core/engine.ts
+var GuideEngine = class {
+  // tracks if guide is currently running
+  constructor(config) {
+    this.active = false;
+    this.manager = new StepManager(config.steps);
+  }
+  // ─── Public API ───────────────────────────────────────────
+  start() {
+    if (this.active) this.stop();
+    this.active = true;
+    this.manager.reset();
+    this.renderStep();
+    console.log("GuideAgent \u25B6 Guide started");
+  }
+  next() {
+    if (!this.active) return;
+    const step = this.manager.next();
+    if (step) {
+      this.renderStep();
+    } else {
+      this.finish();
+    }
+  }
+  prev() {
+    if (!this.active) return;
+    const step = this.manager.prev();
+    if (step) {
+      this.renderStep();
+    }
+  }
+  stop() {
+    this.active = false;
+    removeHighlight();
+    removeTooltip();
+    console.log("GuideAgent \u25A0 Guide stopped");
+  }
+  // Add this inside GuideEngine class in engine.ts
+  // after the stop() method
+  // Loads config from a JSON file URL then starts the guide
+  async loadFromUrl(configUrl) {
+    try {
+      const { loadConfig: loadConfig2 } = await Promise.resolve().then(() => (init_loader(), loader_exports));
+      const config = await loadConfig2(configUrl);
+      this.manager = new StepManager(config.steps);
+      console.log("GuideAgent: Config loaded from URL \u2705");
+    } catch (error) {
+      console.error("GuideAgent: Could not load config:", error);
+    }
+  }
+  // ─── Private Methods ──────────────────────────────────────
+  finish() {
+    this.active = false;
+    removeHighlight();
+    removeTooltip();
+    console.log("GuideAgent \u2705 Guide complete");
+    this.showCompletionBadge();
+  }
+  renderStep() {
+    const step = this.manager.current();
+    setTimeout(() => {
+      const el = document.querySelector(step.selector);
+      if (!el) {
+        console.warn(`GuideAgent \u26A0 "${step.selector}" not found \u2014 skipping`);
+        this.next();
+        return;
+      }
+      el.scrollIntoView({ behavior: "smooth", block: "center" });
+      setTimeout(() => {
+        var _a;
+        const lang = getCurrentLang();
+        const translation = (_a = step.translations[lang]) != null ? _a : step.translations["en"];
+        highlight(el);
+        showTooltip(
+          el,
+          translation.title,
+          translation.description,
+          () => this.next(),
+          () => this.prev(),
+          this.manager.isFirst(),
+          this.manager.isLast(),
+          this.manager.currentNumber(),
+          this.manager.totalSteps()
+        );
+        console.log(
+          `GuideAgent \u2192 Step ${this.manager.currentNumber()}/${this.manager.totalSteps()} [${lang}]: ${translation.title}`
+        );
+      }, 1e3);
+    }, 300);
+  }
+  showCompletionBadge() {
+    const s = getStrings();
+    const badge = document.createElement("div");
+    Object.assign(badge.style, {
+      position: "fixed",
+      bottom: "32px",
+      left: "50%",
+      transform: "translateX(-50%)",
+      background: "#22c55e",
+      color: "white",
+      padding: "10px 24px",
+      borderRadius: "999px",
+      fontSize: "14px",
+      fontWeight: "600",
+      fontFamily: "sans-serif",
+      zIndex: "10001",
+      boxShadow: "0 4px 16px rgba(34,197,94,0.4)"
+    });
+    badge.textContent = s.guide_complete;
+    document.body.appendChild(badge);
+    setTimeout(() => badge.remove(), 2e3);
+  }
+};
+
+// src/index.ts
+var engine = null;
+var floatingBtn = null;
+var GuideAgent = {
+  version: "0.1.0",
+  init(config) {
+    engine = new GuideEngine(config);
+    this.createFloatingButton();
+    console.log("GuideAgent initialized \u2705");
+  },
+  async initFromUrl(configUrl) {
+    try {
+      const { loadConfig: loadConfig2 } = await Promise.resolve().then(() => (init_loader(), loader_exports));
+      const config = await loadConfig2(configUrl);
+      engine = new GuideEngine({ steps: config.steps });
+      this.createFloatingButton();
+      console.log("GuideAgent initialized from URL \u2705");
+    } catch (error) {
+      console.error("GuideAgent: initFromUrl failed:", error);
+    }
+  },
+  start() {
+    engine == null ? void 0 : engine.start();
+  },
+  stop() {
+    engine == null ? void 0 : engine.stop();
+  },
+  setLang(lang) {
+    setLanguage(lang);
+    if (floatingBtn) {
+      floatingBtn.textContent = getStrings().guide_me_btn;
+    }
+  },
+  // Expose getStrings so HTML can read page content keys
+  getStrings() {
+    return getStrings();
+  },
+  createFloatingButton() {
+    floatingBtn == null ? void 0 : floatingBtn.remove();
+    floatingBtn = document.createElement("button");
+    floatingBtn.textContent = getStrings().guide_me_btn;
+    Object.assign(floatingBtn.style, {
+      position: "fixed",
+      bottom: "24px",
+      right: "24px",
+      background: "#6366f1",
+      color: "white",
+      border: "none",
+      padding: "12px 20px",
+      borderRadius: "999px",
+      fontSize: "14px",
+      fontWeight: "600",
+      fontFamily: "sans-serif",
+      cursor: "pointer",
+      zIndex: "10001",
+      boxShadow: "0 4px 20px rgba(99,102,241,0.5)",
+      transition: "transform 0.2s ease"
+    });
+    floatingBtn.addEventListener("mouseenter", () => {
+      floatingBtn.style.transform = "scale(1.05)";
+    });
+    floatingBtn.addEventListener("mouseleave", () => {
+      floatingBtn.style.transform = "scale(1)";
+    });
+    floatingBtn.addEventListener("click", () => {
+      engine == null ? void 0 : engine.start();
+    });
+    document.body.appendChild(floatingBtn);
+  }
+};
+var index_default = GuideAgent;

package/dist/index.mjs

@@ -0,0 +1,429 @@
+// src/i18n/en.json
+var en_default = {
+  guide_label: "GuideAgent",
+  next_btn: "Next \u2192",
+  prev_btn: "\u2190 Prev",
+  finish_btn: "Finish \u2713",
+  guide_me_btn: "\u{1F9ED} Guide Me",
+  guide_complete: "\u2713 Guide Complete!",
+  step_of: "Step {current} of {total}"
+};
+
+// src/i18n/ta.json
+var ta_default = {
+  guide_label: "Vazhi Kaatti",
+  next_btn: "Aduthu \u2192",
+  prev_btn: "\u2190 Munnaadi",
+  finish_btn: "Mudinthathu \u2713",
+  guide_me_btn: "\u{1F9ED} Vazhi Kaattu",
+  guide_complete: "\u2713 Vazhi Kaattal Mudinthathu!",
+  step_of: "Padi {current} / {total}"
+};
+
+// src/i18n/hi.json
+var hi_default = {
+  guide_label: "GuideAgent",
+  next_btn: "Aage \u2192",
+  prev_btn: "\u2190 Peeche",
+  finish_btn: "Khatam \u2713",
+  guide_me_btn: "\u{1F9ED} Mujhe Guide Karo",
+  guide_complete: "\u2713 Guide Poora Hua!",
+  step_of: "Kadam {current} / {total}"
+};
+
+// src/config/i18n.ts
+var languages = { en: en_default, ta: ta_default, hi: hi_default };
+var currentLang = "en";
+function setLanguage(lang) {
+  if (languages[lang]) {
+    currentLang = lang;
+    console.log(`GuideAgent: Language set to "${lang}" \u2705`);
+  } else {
+    console.warn(`GuideAgent: "${lang}" not supported \u2014 using "en"`);
+    currentLang = "en";
+  }
+}
+function getCurrentLang() {
+  return currentLang;
+}
+function getStrings() {
+  var _a;
+  return (_a = languages[currentLang]) != null ? _a : languages["en"];
+}
+function formatStep(template, current, total) {
+  return template.replace("{current}", String(current)).replace("{total}", String(total));
+}
+
+// src/renderer/highlight.ts
+var highlightBox = null;
+var overlayMask = null;
+function highlight(el) {
+  removeHighlight();
+  const rect = el.getBoundingClientRect();
+  overlayMask = document.createElement("div");
+  Object.assign(overlayMask.style, {
+    position: "fixed",
+    // fixed = stays in place even when user scrolls
+    top: "0",
+    left: "0",
+    width: "100vw",
+    // full screen width
+    height: "100vh",
+    // full screen height
+    backgroundColor: "rgba(0, 0, 0, 0.55)",
+    // semi-transparent black
+    zIndex: "9998",
+    // sits above your portfolio content
+    pointerEvents: "none"
+    // user can still interact with page behind it
+  });
+  highlightBox = document.createElement("div");
+  Object.assign(highlightBox.style, {
+    position: "fixed",
+    top: `${rect.top - 6}px`,
+    // 6px padding above element
+    left: `${rect.left - 6}px`,
+    // 6px padding left of element
+    width: `${rect.width + 12}px`,
+    // 12px wider (6px each side)
+    height: `${rect.height + 12}px`,
+    // 12px taller (6px each side)
+    border: "2px solid #6366f1",
+    // indigo border color
+    borderRadius: "8px",
+    zIndex: "9999",
+    // sits above the dark mask
+    pointerEvents: "none",
+    boxShadow: "0 0 12px rgba(99, 102, 241, 0.6)",
+    // soft glow effect
+    transition: "all 0.3s ease"
+    // smooth animation when moving steps
+  });
+  document.body.appendChild(overlayMask);
+  document.body.appendChild(highlightBox);
+}
+function removeHighlight() {
+  highlightBox == null ? void 0 : highlightBox.remove();
+  overlayMask == null ? void 0 : overlayMask.remove();
+  highlightBox = null;
+  overlayMask = null;
+}
+
+// src/renderer/tooltip.ts
+var tooltipEl = null;
+function showTooltip(el, title, description, onNext, onPrev, isFirst, isLast, currentStep, totalSteps) {
+  var _a, _b;
+  removeTooltip();
+  const s = getStrings();
+  const rect = el.getBoundingClientRect();
+  tooltipEl = document.createElement("div");
+  Object.assign(tooltipEl.style, {
+    position: "fixed",
+    zIndex: "10000",
+    background: "#1e1e2e",
+    color: "#ffffff",
+    padding: "16px 20px",
+    borderRadius: "10px",
+    width: "280px",
+    boxShadow: "0 8px 32px rgba(0,0,0,0.4)",
+    fontFamily: "sans-serif",
+    fontSize: "14px",
+    lineHeight: "1.5",
+    border: "1px solid #6366f1"
+  });
+  tooltipEl.innerHTML = `
+    <div style="
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 8px;
+    ">
+      <span style="font-size:12px; color:#a5b4fc; font-weight:600; text-transform:uppercase;">
+        ${s.guide_label}
+      </span>
+      <span style="font-size:12px; color:#64748b;">
+        ${formatStep(s.step_of, currentStep, totalSteps)}
+      </span>
+    </div>
+
+    <div style="font-size:16px; font-weight:700; margin-bottom:8px; color:#ffffff;">
+      ${title}
+    </div>
+
+    <div style="font-size:14px; color:#cbd5e1; margin-bottom:16px;">
+      ${description}
+    </div>
+
+    <div style="display:flex; gap:8px; justify-content:flex-end;">
+      ${!isFirst ? `
+        <button id="guide-prev-btn" style="
+          background:transparent; color:#a5b4fc;
+          border:1px solid #6366f1; padding:6px 14px;
+          border-radius:6px; cursor:pointer; font-size:13px;
+        ">${s.prev_btn}</button>
+      ` : ""}
+
+      <button id="guide-next-btn" style="
+        background:#6366f1; color:white; border:none;
+        padding:6px 14px; border-radius:6px; cursor:pointer;
+        font-size:13px; font-weight:600;
+      ">${isLast ? s.finish_btn : s.next_btn}</button>
+    </div>
+  `;
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  const tooltipWidth = 280;
+  const tooltipHeight = 180;
+  let top = rect.bottom + 12;
+  let left = rect.left;
+  if (top + tooltipHeight > viewportHeight) {
+    top = rect.top - tooltipHeight - 12;
+  }
+  if (top < 16) {
+    top = viewportHeight / 2 - tooltipHeight / 2;
+  }
+  if (left + tooltipWidth > viewportWidth) {
+    left = viewportWidth - tooltipWidth - 16;
+  }
+  if (left < 16) {
+    left = 16;
+  }
+  tooltipEl.style.top = `${top}px`;
+  tooltipEl.style.left = `${left}px`;
+  document.body.appendChild(tooltipEl);
+  (_a = document.getElementById("guide-next-btn")) == null ? void 0 : _a.addEventListener("click", onNext);
+  (_b = document.getElementById("guide-prev-btn")) == null ? void 0 : _b.addEventListener("click", onPrev);
+}
+function removeTooltip() {
+  tooltipEl == null ? void 0 : tooltipEl.remove();
+  tooltipEl = null;
+}
+
+// src/core/stepManager.ts
+var StepManager = class {
+  constructor(steps) {
+    this.steps = steps.sort((a, b) => a.order - b.order);
+    this.currentIndex = 0;
+  }
+  current() {
+    return this.steps[this.currentIndex];
+  }
+  next() {
+    if (this.currentIndex < this.steps.length - 1) {
+      this.currentIndex++;
+      return this.steps[this.currentIndex];
+    }
+    return null;
+  }
+  prev() {
+    if (this.currentIndex > 0) {
+      this.currentIndex--;
+      return this.steps[this.currentIndex];
+    }
+    return null;
+  }
+  reset() {
+    this.currentIndex = 0;
+  }
+  isFirst() {
+    return this.currentIndex === 0;
+  }
+  isLast() {
+    return this.currentIndex === this.steps.length - 1;
+  }
+  currentNumber() {
+    return this.currentIndex + 1;
+  }
+  totalSteps() {
+    return this.steps.length;
+  }
+};
+
+// src/core/engine.ts
+var GuideEngine = class {
+  // tracks if guide is currently running
+  constructor(config) {
+    this.active = false;
+    this.manager = new StepManager(config.steps);
+  }
+  // ─── Public API ───────────────────────────────────────────
+  start() {
+    if (this.active) this.stop();
+    this.active = true;
+    this.manager.reset();
+    this.renderStep();
+    console.log("GuideAgent \u25B6 Guide started");
+  }
+  next() {
+    if (!this.active) return;
+    const step = this.manager.next();
+    if (step) {
+      this.renderStep();
+    } else {
+      this.finish();
+    }
+  }
+  prev() {
+    if (!this.active) return;
+    const step = this.manager.prev();
+    if (step) {
+      this.renderStep();
+    }
+  }
+  stop() {
+    this.active = false;
+    removeHighlight();
+    removeTooltip();
+    console.log("GuideAgent \u25A0 Guide stopped");
+  }
+  // Add this inside GuideEngine class in engine.ts
+  // after the stop() method
+  // Loads config from a JSON file URL then starts the guide
+  async loadFromUrl(configUrl) {
+    try {
+      const { loadConfig } = await import("./loader-KPVIVLN6.mjs");
+      const config = await loadConfig(configUrl);
+      this.manager = new StepManager(config.steps);
+      console.log("GuideAgent: Config loaded from URL \u2705");
+    } catch (error) {
+      console.error("GuideAgent: Could not load config:", error);
+    }
+  }
+  // ─── Private Methods ──────────────────────────────────────
+  finish() {
+    this.active = false;
+    removeHighlight();
+    removeTooltip();
+    console.log("GuideAgent \u2705 Guide complete");
+    this.showCompletionBadge();
+  }
+  renderStep() {
+    const step = this.manager.current();
+    setTimeout(() => {
+      const el = document.querySelector(step.selector);
+      if (!el) {
+        console.warn(`GuideAgent \u26A0 "${step.selector}" not found \u2014 skipping`);
+        this.next();
+        return;
+      }
+      el.scrollIntoView({ behavior: "smooth", block: "center" });
+      setTimeout(() => {
+        var _a;
+        const lang = getCurrentLang();
+        const translation = (_a = step.translations[lang]) != null ? _a : step.translations["en"];
+        highlight(el);
+        showTooltip(
+          el,
+          translation.title,
+          translation.description,
+          () => this.next(),
+          () => this.prev(),
+          this.manager.isFirst(),
+          this.manager.isLast(),
+          this.manager.currentNumber(),
+          this.manager.totalSteps()
+        );
+        console.log(
+          `GuideAgent \u2192 Step ${this.manager.currentNumber()}/${this.manager.totalSteps()} [${lang}]: ${translation.title}`
+        );
+      }, 1e3);
+    }, 300);
+  }
+  showCompletionBadge() {
+    const s = getStrings();
+    const badge = document.createElement("div");
+    Object.assign(badge.style, {
+      position: "fixed",
+      bottom: "32px",
+      left: "50%",
+      transform: "translateX(-50%)",
+      background: "#22c55e",
+      color: "white",
+      padding: "10px 24px",
+      borderRadius: "999px",
+      fontSize: "14px",
+      fontWeight: "600",
+      fontFamily: "sans-serif",
+      zIndex: "10001",
+      boxShadow: "0 4px 16px rgba(34,197,94,0.4)"
+    });
+    badge.textContent = s.guide_complete;
+    document.body.appendChild(badge);
+    setTimeout(() => badge.remove(), 2e3);
+  }
+};
+
+// src/index.ts
+var engine = null;
+var floatingBtn = null;
+var GuideAgent = {
+  version: "0.1.0",
+  init(config) {
+    engine = new GuideEngine(config);
+    this.createFloatingButton();
+    console.log("GuideAgent initialized \u2705");
+  },
+  async initFromUrl(configUrl) {
+    try {
+      const { loadConfig } = await import("./loader-KPVIVLN6.mjs");
+      const config = await loadConfig(configUrl);
+      engine = new GuideEngine({ steps: config.steps });
+      this.createFloatingButton();
+      console.log("GuideAgent initialized from URL \u2705");
+    } catch (error) {
+      console.error("GuideAgent: initFromUrl failed:", error);
+    }
+  },
+  start() {
+    engine == null ? void 0 : engine.start();
+  },
+  stop() {
+    engine == null ? void 0 : engine.stop();
+  },
+  setLang(lang) {
+    setLanguage(lang);
+    if (floatingBtn) {
+      floatingBtn.textContent = getStrings().guide_me_btn;
+    }
+  },
+  // Expose getStrings so HTML can read page content keys
+  getStrings() {
+    return getStrings();
+  },
+  createFloatingButton() {
+    floatingBtn == null ? void 0 : floatingBtn.remove();
+    floatingBtn = document.createElement("button");
+    floatingBtn.textContent = getStrings().guide_me_btn;
+    Object.assign(floatingBtn.style, {
+      position: "fixed",
+      bottom: "24px",
+      right: "24px",
+      background: "#6366f1",
+      color: "white",
+      border: "none",
+      padding: "12px 20px",
+      borderRadius: "999px",
+      fontSize: "14px",
+      fontWeight: "600",
+      fontFamily: "sans-serif",
+      cursor: "pointer",
+      zIndex: "10001",
+      boxShadow: "0 4px 20px rgba(99,102,241,0.5)",
+      transition: "transform 0.2s ease"
+    });
+    floatingBtn.addEventListener("mouseenter", () => {
+      floatingBtn.style.transform = "scale(1.05)";
+    });
+    floatingBtn.addEventListener("mouseleave", () => {
+      floatingBtn.style.transform = "scale(1)";
+    });
+    floatingBtn.addEventListener("click", () => {
+      engine == null ? void 0 : engine.start();
+    });
+    document.body.appendChild(floatingBtn);
+  }
+};
+var index_default = GuideAgent;
+export {
+  index_default as default
+};

package/dist/loader-KPVIVLN6.mjs

@@ -0,0 +1,56 @@
+// src/config/loader.ts
+async function loadConfig(configUrl) {
+  try {
+    const response = await fetch(configUrl);
+    if (!response.ok) {
+      throw new Error(
+        `GuideAgent: Failed to load config from "${configUrl}" \u2014 HTTP ${response.status}`
+      );
+    }
+    const config = await response.json();
+    if (!config.steps || !Array.isArray(config.steps)) {
+      throw new Error(
+        `GuideAgent: Invalid config \u2014 "steps" array missing in "${configUrl}"`
+      );
+    }
+    config.steps.forEach((step, index) => {
+      if (!step.selector) {
+        throw new Error(
+          `GuideAgent: Step ${index + 1} missing "selector" field`
+        );
+      }
+      if (!step.translations) {
+        throw new Error(
+          `GuideAgent: Step ${index + 1} missing "translations" field`
+        );
+      }
+      if (!step.translations["en"]) {
+        throw new Error(
+          `GuideAgent: Step ${index + 1} missing "en" translation \u2014 English is required as fallback`
+        );
+      }
+      Object.entries(step.translations).forEach(([lang, t]) => {
+        if (!t.title) {
+          throw new Error(
+            `GuideAgent: Step ${index + 1} "${lang}" translation missing "title"`
+          );
+        }
+        if (!t.description) {
+          throw new Error(
+            `GuideAgent: Step ${index + 1} "${lang}" translation missing "description"`
+          );
+        }
+      });
+    });
+    console.log(
+      `GuideAgent: Config loaded \u2705 \u2014 ${config.steps.length} steps for page "${config.page}"`
+    );
+    return config;
+  } catch (error) {
+    console.error("GuideAgent config load failed:", error);
+    throw error;
+  }
+}
+export {
+  loadConfig
+};

package/dist/loader-TLGJWSBC.mjs

@@ -0,0 +1,38 @@
+// src/config/loader.ts
+async function loadConfig(configUrl) {
+  try {
+    const response = await fetch(configUrl);
+    if (!response.ok) {
+      throw new Error(
+        `GuideAgent: Failed to load config from "${configUrl}" \u2014 HTTP ${response.status}`
+      );
+    }
+    const config = await response.json();
+    if (!config.steps || !Array.isArray(config.steps)) {
+      throw new Error(
+        `GuideAgent: Invalid config \u2014 "steps" array missing in "${configUrl}"`
+      );
+    }
+    config.steps.forEach((step, index) => {
+      if (!step.selector) {
+        throw new Error(`GuideAgent: Step ${index + 1} missing "selector" field`);
+      }
+      if (!step.title) {
+        throw new Error(`GuideAgent: Step ${index + 1} missing "title" field`);
+      }
+      if (!step.description) {
+        throw new Error(`GuideAgent: Step ${index + 1} missing "description" field`);
+      }
+    });
+    console.log(
+      `GuideAgent: Config loaded \u2705 \u2014 ${config.steps.length} steps for page "${config.page}"`
+    );
+    return config;
+  } catch (error) {
+    console.error("GuideAgent config load failed:", error);
+    throw error;
+  }
+}
+export {
+  loadConfig
+};

package/licence

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raghul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "guideagent",
+  "version": "0.1.0",
+  "description": "Contextual in-app guidance SDK for web apps — multilingual, config-driven, developer-first",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "onboarding",
+    "guide",
+    "tooltip",
+    "sdk",
+    "walkthrough",
+    "multilingual",
+    "react",
+    "flutter"
+  ],
+  "author": "Raghul <your@email.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_USERNAME/guideagent"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}