@kibee/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1831 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BookmarkMemory: () => BookmarkMemory,
+  BridgeClient: () => BridgeClient,
+  FlowController: () => FlowController,
+  HighlightRenderer: () => HighlightRenderer,
+  KiBeeApiClient: () => KiBeeApiClient,
+  KiBeeClient: () => KiBeeClient,
+  Locator: () => Locator,
+  TargetRegistry: () => TargetRegistry
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api/KiBeeApiClient.ts
+var KiBeeApiClient = class {
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl;
+    this.options = options;
+  }
+  baseUrl;
+  options;
+  async fetchFlow(id) {
+    return this.request(`/flows/${id}`);
+  }
+  async startSession(input) {
+    return this.request("/sessions", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async resolveIntent(input) {
+    return this.request("/intent/resolve", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async resolveRecovery(input) {
+    return this.request("/recovery/resolve", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  async trackEvent(event) {
+    await this.request("/events", {
+      method: "POST",
+      body: JSON.stringify(event)
+    });
+  }
+  /**
+   * Unified visitor poll. One round-trip pulls messages + pending pushes
+   * + mode + friction. Replaces the previous fetchVisitorMessages +
+   * /admin/sessions/:id/pending pair for visitors using publishable-key
+   * auth. The legacy fetchVisitorMessages remains for shipped SDK
+   * builds that haven't been updated yet.
+   */
+  async fetchVisitorSync(sessionId, since) {
+    const params = new URLSearchParams({ sessionId });
+    if (since) params.set("since", since);
+    return this.request(`/v1/visitor/sync?${params.toString()}`);
+  }
+  /**
+   * Legacy split poll — kept for backward compat. Prefer fetchVisitorSync.
+   */
+  async fetchVisitorMessages(sessionId, since) {
+    const params = new URLSearchParams({ sessionId });
+    if (since) params.set("since", since);
+    return this.request(`/v1/visitor/messages?${params.toString()}`);
+  }
+  /**
+   * Visitor (or distress detector) requests a human. Sets
+   * `requested_human_at`, generates an AI summary for the agent, and lights
+   * up the "Needs help" badge in admin Hive.
+   */
+  async escalateToHuman(sessionId) {
+    await this.request("/v1/visitor/escalate", {
+      method: "POST",
+      body: JSON.stringify({ sessionId })
+    });
+  }
+  /**
+   * Open the visitor's per-session SSE stream. EventSource can't pass auth
+   * headers, so the publishable key + websiteId ride along as query params.
+   * Caller wires `onmessage` and is responsible for re-opening on disconnect.
+   *
+   * Returns null when EventSource isn't available (older browsers / strict
+   * proxies) — caller falls back to polling `fetchVisitorMessages`.
+   */
+  openVisitorStream(sessionId) {
+    if (typeof EventSource === "undefined") return null;
+    const websiteId = this.options.websiteId;
+    const token = this.options.publicKey;
+    if (!websiteId || !token) return null;
+    const params = new URLSearchParams({
+      sessionId,
+      websiteId,
+      // The token query param is necessary because EventSource doesn't accept
+      // headers. The query string is logged on the server but the token never
+      // shows up in `logRequest` (the visitor stream is special-cased there).
+      token
+    });
+    return new EventSource(`${this.baseUrl}/v1/visitor/stream?${params.toString()}`);
+  }
+  buildHeaders(extra) {
+    const headers = {
+      "content-type": "application/json",
+      ...extra
+    };
+    if (this.options.websiteId && this.options.publicKey) {
+      headers["x-kibee-website-id"] = this.options.websiteId;
+      headers.authorization = `Bearer ${this.options.publicKey}`;
+    } else if (this.options.legacyApiKey) {
+      headers["x-kibee-key"] = this.options.legacyApiKey;
+    }
+    return headers;
+  }
+  async request(path, init = {}) {
+    const headers = this.buildHeaders(init.headers);
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...init,
+      headers,
+      cache: "no-store"
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(body || `Request failed: ${response.status}`);
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return await response.json();
+  }
+};
+
+// src/bridge/BridgeClient.ts
+var import_contracts = require("@kibee/contracts");
+var BridgeClient = class {
+  ws = null;
+  handlers = /* @__PURE__ */ new Map();
+  opts;
+  state = "disconnected";
+  heartbeatTimer;
+  lastPongAt = 0;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  on(eventType, handler) {
+    const list = this.handlers.get(eventType) ?? [];
+    list.push(handler);
+    this.handlers.set(eventType, list);
+    return () => {
+      const next = (this.handlers.get(eventType) ?? []).filter(
+        (h) => h !== handler
+      );
+      this.handlers.set(eventType, next);
+    };
+  }
+  async connect() {
+    const { token } = await this.opts.tokenFetcher();
+    const urlWithToken = `${this.opts.bridgeUrl}?token=${encodeURIComponent(token)}`;
+    const ws = new WebSocket(urlWithToken);
+    this.ws = ws;
+    await new Promise((resolve, reject) => {
+      ws.addEventListener("open", () => resolve());
+      ws.addEventListener("error", (e) => reject(e));
+    });
+    ws.addEventListener("message", (e) => {
+      this.lastPongAt = Date.now();
+      let parsed;
+      try {
+        parsed = JSON.parse(typeof e.data === "string" ? e.data : "");
+      } catch {
+        return;
+      }
+      if (!(0, import_contracts.isBridgeEnvelope)(parsed)) return;
+      const list = this.handlers.get(parsed.type) ?? [];
+      list.forEach((fn) => fn(parsed));
+    });
+    this.send({
+      v: 1,
+      source: this.opts.source,
+      target: "broadcast",
+      tenantId: null,
+      workspaceId: null,
+      visitorId: this.opts.visitorId,
+      sessionId: null,
+      type: "presence:hello",
+      ts: Date.now(),
+      payload: {}
+    });
+    this.startHeartbeat();
+  }
+  startHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    this.lastPongAt = Date.now();
+    this.heartbeatTimer = setInterval(() => {
+      if (this.ws?.readyState === 1) {
+        try {
+          this.ws.send(
+            JSON.stringify({
+              v: 1,
+              source: this.opts.source,
+              target: "broadcast",
+              tenantId: null,
+              workspaceId: null,
+              visitorId: this.opts.visitorId,
+              sessionId: null,
+              type: "presence:hello",
+              ts: Date.now(),
+              payload: { ping: true }
+            })
+          );
+        } catch {
+        }
+      }
+      if (Date.now() - this.lastPongAt > 12e3) {
+        this.markDegraded();
+      }
+    }, 1e4);
+  }
+  markDegraded() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent("kibee-bridge-degraded"));
+    }
+    this.state = "disconnected";
+    this.ws?.close();
+  }
+  send(envelope) {
+    if (!this.ws) throw new Error("BridgeClient: not connected");
+    const OPEN = this.ws.constructor.OPEN;
+    if (this.ws.readyState !== OPEN) return;
+    this.ws.send(JSON.stringify(envelope));
+  }
+  close() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    if (!this.ws) return;
+    try {
+      this.send({
+        v: 1,
+        source: this.opts.source,
+        target: "broadcast",
+        tenantId: null,
+        workspaceId: null,
+        visitorId: this.opts.visitorId,
+        sessionId: null,
+        type: "presence:bye",
+        ts: Date.now(),
+        payload: {}
+      });
+    } catch {
+    }
+    this.ws.close();
+    this.ws = null;
+    this.state = "disconnected";
+  }
+  /**
+   * Wraps `connect()` with exponential backoff. Defaults: 10 attempts,
+   * 1s base, 30s cap (delays: 1s, 2s, 4s, 8s, 16s, 30s, 30s, ...). Adds
+   * 0–20% jitter per attempt.
+   *
+   * On success, `state` is `connected` and the method resolves.
+   * After `maxAttempts` failures, `state` is `failed` and the last error
+   * is re-thrown.
+   *
+   * `connect()` itself remains a single-attempt method so existing callers
+   * are unaffected.
+   */
+  async connectWithReconnect(opts = {}) {
+    const max = opts.maxAttempts ?? 10;
+    const base = opts.baseDelayMs ?? 1e3;
+    const cap = opts.capDelayMs ?? 3e4;
+    let attempt = 0;
+    while (true) {
+      try {
+        this.state = "connecting";
+        await this.connect();
+        this.state = "connected";
+        return;
+      } catch (err) {
+        attempt += 1;
+        if (attempt >= max) {
+          this.state = "failed";
+          throw err;
+        }
+        const delay = Math.min(cap, base * Math.pow(2, attempt - 1));
+        const jitter = delay * 0.2 * Math.random();
+        await new Promise((r) => setTimeout(r, delay + jitter));
+      }
+    }
+  }
+};
+
+// src/controllers/BookmarkMemory.ts
+var BookmarkMemory = class {
+  storageKey = "kibee:bookmarks";
+  list() {
+    return this.read();
+  }
+  create(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const bookmark = {
+      id: this.generateId(),
+      kind: input.kind,
+      label: input.label,
+      note: input.note,
+      pageUrl: window.location.href,
+      pageTitle: document.title,
+      target: input.target,
+      metadata: input.metadata,
+      createdAt: now,
+      updatedAt: now
+    };
+    const current = this.read();
+    current.push(bookmark);
+    this.write(current);
+    return bookmark;
+  }
+  update(id, patch) {
+    const current = this.read();
+    const index = current.findIndex((x) => x.id === id);
+    if (index === -1) return null;
+    current[index] = {
+      ...current[index],
+      ...patch,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.write(current);
+    return current[index];
+  }
+  remove(id) {
+    const current = this.read().filter((x) => x.id !== id);
+    this.write(current);
+  }
+  findByPage(url = window.location.href) {
+    return this.read().filter((x) => x.pageUrl === url);
+  }
+  read() {
+    try {
+      const raw = localStorage.getItem(this.storageKey);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+  write(value) {
+    localStorage.setItem(this.storageKey, JSON.stringify(value));
+  }
+  generateId() {
+    return `fbm_${Math.random().toString(36).slice(2, 10)}`;
+  }
+};
+
+// src/controllers/FlowController.ts
+var FlowController = class {
+  constructor(bee, locator, highlight, bookmarks = new BookmarkMemory(), onCommand) {
+    this.bee = bee;
+    this.locator = locator;
+    this.highlight = highlight;
+    this.bookmarks = bookmarks;
+    this.onCommand = onCommand;
+  }
+  bee;
+  locator;
+  highlight;
+  bookmarks;
+  onCommand;
+  async init() {
+    this.highlight.mount();
+    await this.bee.dock();
+  }
+  async runFlow(flow) {
+    await this.bee.undock();
+    if (flow.introMessage) {
+      this.bee.speak(flow.introMessage);
+    }
+    for (const command of flow.steps) {
+      this.onCommand?.(command, "started");
+      const success = await this.execute(command);
+      this.onCommand?.(
+        command,
+        success ? "completed" : "missing_target"
+      );
+    }
+  }
+  /**
+   * Interactive step-through mode: bee flies to each `fly_to` step and shows
+   * prev / next buttons in the tooltip so the user controls the pace.
+   */
+  async runInteractiveFlow(flow) {
+    const guidedSteps = flow.steps.filter(
+      (s) => s.type === "fly_to"
+    );
+    if (guidedSteps.length === 0) {
+      await this.runFlow(flow);
+      return;
+    }
+    await this.bee.undock();
+    const showStep = async (index) => {
+      const step = guidedSteps[index];
+      const isFirst = index === 0;
+      const isLast = index === guidedSteps.length - 1;
+      await this.guideTo(
+        step.target,
+        step.message,
+        step.highlight,
+        step.moveTo,
+        {
+          onPrev: isFirst ? null : () => {
+            void showStep(index - 1);
+          },
+          onNext: isLast ? () => {
+            this.clearFocus();
+          } : () => {
+            void showStep(index + 1);
+          },
+          stepLabel: `${index + 1} / ${guidedSteps.length}`
+        }
+      );
+    };
+    await showStep(0);
+  }
+  clearFocus() {
+    this.highlight.hide();
+    this.bee.hideMessage();
+    this.bee.hideActions();
+    this.bee.setState("idle");
+    void this.bee.dock();
+  }
+  async createHoneyBookmark(label, target, note) {
+    return this.createBookmark("honey", label, target, note);
+  }
+  async createStingBookmark(label, target, note) {
+    return this.createBookmark("sting", label, target, note);
+  }
+  listBookmarks() {
+    return this.bookmarks.list();
+  }
+  getPageBookmarks() {
+    return this.bookmarks.findByPage();
+  }
+  async revisitBookmark(bookmark) {
+    const kindMessage = bookmark.kind === "honey" ? `Here\u2019s your honey mark: ${bookmark.label}` : `Here\u2019s your sting mark: ${bookmark.label}`;
+    await this.guideTo(
+      bookmark.target,
+      bookmark.note ? `${kindMessage}. ${bookmark.note}` : kindMessage,
+      bookmark.kind === "honey" ? "soft" : "ring"
+    );
+  }
+  removeBookmark(id) {
+    this.bookmarks.remove(id);
+  }
+  async execute(command) {
+    switch (command.type) {
+      case "speak":
+        this.bee.speak(command.message);
+        return true;
+      case "celebrate":
+        this.bee.setState("celebrating");
+        if (command.message) {
+          this.bee.speak(command.message);
+        }
+        return true;
+      case "end_flow":
+        if (command.message) {
+          this.bee.speak(command.message);
+        }
+        if (command.status === "completed") {
+          this.bee.setState("celebrating");
+          await this.finishAndDock(860);
+        } else {
+          this.bee.setState("idle");
+          await this.bee.dock();
+        }
+        this.highlight.hide();
+        return true;
+      case "highlight": {
+        const resolved = this.locator.resolve(command.target);
+        if (!resolved) {
+          this.notifyMissingTarget();
+          return false;
+        }
+        this.highlight.show(resolved.rect, command.variant ?? "pulse");
+        return true;
+      }
+      case "fly_to":
+        return this.guideTo(command.target, command.message, command.highlight, command.moveTo);
+      case "wait_for_click": {
+        const resolved = this.locator.resolve(command.target);
+        if (!resolved) {
+          this.notifyMissingTarget();
+          return false;
+        }
+        await this.waitForClick(resolved.element, command.timeoutMs ?? 2e4);
+        return true;
+      }
+      case "wait_for_input": {
+        const resolved = this.locator.resolve(command.target);
+        if (!resolved) {
+          this.notifyMissingTarget();
+          return false;
+        }
+        await this.waitForInput(resolved.element, command.timeoutMs ?? 2e4);
+        return true;
+      }
+      default:
+        return false;
+    }
+  }
+  async createBookmark(kind, label, target, note) {
+    const resolved = this.locator.resolve(target);
+    if (!resolved) {
+      this.bee.setState("thinking");
+      this.bee.speak("I couldn\u2019t save that spot because I couldn\u2019t find it.");
+      void this.finishAndDock(900);
+      return null;
+    }
+    const bookmark = this.bookmarks.create({
+      kind,
+      label,
+      note,
+      target
+    });
+    const placement = this.resolveGuidePlacement(resolved.rect);
+    await this.bee.moveTo(resolved.rect.right, resolved.rect.top, placement.moveTo);
+    this.bee.setState("celebrating");
+    this.bee.speak(
+      kind === "honey" ? `Saved bookmark: ${label}` : `Issue flagged: ${label}`,
+      placement.speak
+    );
+    await this.finishInPlace(920);
+    return bookmark;
+  }
+  async guideTo(target, message, highlight, moveTo, navOptions) {
+    await this.bee.undock();
+    const resolved = this.locator.resolve(target);
+    if (!resolved) {
+      this.notifyMissingTarget();
+      return false;
+    }
+    this.locator.scrollIntoView(target);
+    await this.delay(350);
+    const fresh = this.locator.resolve(target);
+    if (!fresh) {
+      this.notifyMissingTarget();
+      return false;
+    }
+    if (highlight) {
+      this.highlight.show(fresh.rect, highlight);
+    }
+    const anchorX = fresh.rect.right;
+    const anchorY = fresh.rect.top;
+    const placement = this.resolveGuidePlacement(fresh.rect, moveTo);
+    await this.bee.moveTo(anchorX, anchorY, {
+      ...placement.moveTo,
+      offsetX: placement.moveTo.offsetX ?? 16,
+      offsetY: placement.moveTo.offsetY ?? -18
+    });
+    if (message) {
+      this.bee.speak(message, { ...placement.speak, ...navOptions });
+    }
+    if (!navOptions) {
+      this.bee.showActions((choice) => {
+        if (choice === "honey") {
+          void this.createHoneyBookmark("Quick honey", target, message);
+        } else {
+          void this.createStingBookmark("Quick sting", target, message);
+        }
+        this.bee.hideActions();
+      });
+    }
+    return true;
+  }
+  waitForClick(el, timeoutMs) {
+    return new Promise((resolve) => {
+      let finished = false;
+      const cleanup = () => {
+        el.removeEventListener("click", onClick);
+        clearTimeout(timer);
+      };
+      const onClick = () => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        resolve();
+      };
+      const timer = window.setTimeout(() => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        resolve();
+      }, timeoutMs);
+      el.addEventListener("click", onClick, { once: true });
+    });
+  }
+  waitForInput(el, timeoutMs) {
+    return new Promise((resolve) => {
+      let finished = false;
+      const cleanup = () => {
+        el.removeEventListener("input", onInput);
+        el.removeEventListener("change", onInput);
+        clearTimeout(timer);
+      };
+      const onInput = () => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        resolve();
+      };
+      const timer = window.setTimeout(() => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        resolve();
+      }, timeoutMs);
+      el.addEventListener("input", onInput, { once: true });
+      el.addEventListener("change", onInput, { once: true });
+    });
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  resolveGuidePlacement(rect, overrides) {
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    const anchorX = rect.right;
+    const anchorY = rect.top;
+    const side = this.pickGuideSide(rect, viewportWidth, viewportHeight);
+    const base = this.resolveTopRightBeeOffset(rect, side, viewportWidth, viewportHeight);
+    const offsetX = overrides?.offsetX ?? base.offsetX;
+    const offsetY = overrides?.offsetY ?? base.offsetY;
+    const beeX = anchorX + offsetX;
+    const beeY = anchorY + offsetY;
+    const tooltip = this.resolveTooltipPosition(
+      side,
+      beeX,
+      beeY,
+      viewportWidth,
+      viewportHeight,
+      rect
+    );
+    return {
+      moveTo: {
+        ...overrides,
+        offsetX,
+        offsetY
+      },
+      speak: {
+        ...tooltip
+      }
+    };
+  }
+  pickGuideSide(rect, viewportWidth, viewportHeight) {
+    const space = {
+      left: rect.left,
+      right: viewportWidth - rect.right,
+      top: rect.top,
+      bottom: viewportHeight - rect.bottom
+    };
+    const wideTarget = rect.width > viewportWidth * 0.32;
+    const tallTarget = rect.height > 140;
+    if (wideTarget || tallTarget) {
+      if (Math.max(space.left, space.right) >= 180) {
+        return space.left >= space.right ? "left" : "right";
+      }
+      if (space.top >= space.bottom) {
+        return "top";
+      }
+      return "bottom";
+    }
+    if (space.right >= 320) return "right";
+    if (space.left >= 320) return "left";
+    if (space.top >= 220) return "top";
+    if (space.bottom >= 220) return "bottom";
+    return Object.entries(space).sort((a, b) => b[1] - a[1])[0]?.[0] ?? "right";
+  }
+  resolveTopRightBeeOffset(rect, _side, viewportWidth, viewportHeight) {
+    const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+    const beeX = clamp(rect.right + 24, 88, viewportWidth - 88);
+    const beeY = clamp(rect.top - 28, 64, viewportHeight - 96);
+    return {
+      offsetX: beeX - rect.right,
+      offsetY: beeY - rect.top
+    };
+  }
+  /** Area of intersection of two axis-aligned rectangles (px²). */
+  rectOverlapArea(a, b) {
+    const w = Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left));
+    const h = Math.max(0, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top));
+    return w * h;
+  }
+  /**
+   * Place the speech bubble with a healthy gap from the bee and pick left-vs-right
+   * by scoring overlap with the bee body and the highlighted target.
+   */
+  resolveTooltipPosition(side, beeX, beeY, viewportWidth, viewportHeight, targetRect) {
+    const tooltipWidth = viewportWidth < 1100 ? 220 : 260;
+    const EST_H = 132;
+    const CLEAR = 56;
+    const BEE_R = 44;
+    const M = 16;
+    const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+    const beeBox = {
+      left: beeX - BEE_R,
+      right: beeX + BEE_R,
+      top: beeY - BEE_R,
+      bottom: beeY + BEE_R
+    };
+    const targetBox = {
+      left: targetRect.left,
+      top: targetRect.top,
+      right: targetRect.right,
+      bottom: targetRect.bottom
+    };
+    const tooltipBox = (xRaw, y2) => {
+      const x2 = clamp(xRaw, M, viewportWidth - tooltipWidth - M);
+      const top = y2 - EST_H / 2;
+      const bottom = y2 + EST_H / 2;
+      return {
+        left: x2,
+        right: x2 + tooltipWidth,
+        top,
+        bottom
+      };
+    };
+    const scoreHorizontal = (xRaw, y2) => {
+      const t = tooltipBox(xRaw, y2);
+      const beeOverlap = this.rectOverlapArea(t, beeBox);
+      const targetOverlap = this.rectOverlapArea(t, targetBox);
+      const clampDelta = Math.abs(
+        clamp(xRaw, M, viewportWidth - tooltipWidth - M) - xRaw
+      );
+      return beeOverlap * 8e3 + targetOverlap * 4 + clampDelta * 2;
+    };
+    let x;
+    let y;
+    let arrowEdge;
+    if (side === "top") {
+      x = beeX - tooltipWidth * 0.56;
+      y = beeY - 56;
+      arrowEdge = "bottom";
+    } else if (side === "bottom") {
+      x = beeX - tooltipWidth * 0.48;
+      y = beeY + 26;
+      arrowEdge = "top";
+    } else {
+      const yH = beeY - 6;
+      const xLeft = beeX - tooltipWidth - CLEAR;
+      const xRight = beeX + CLEAR;
+      const sL = scoreHorizontal(xLeft, yH);
+      const sR = scoreHorizontal(xRight, yH);
+      const preferLeftOfBee = side === "left";
+      const tieEps = 500;
+      if (sL + tieEps < sR) {
+        x = xLeft;
+        y = yH;
+        arrowEdge = "right";
+      } else if (sR + tieEps < sL) {
+        x = xRight;
+        y = yH;
+        arrowEdge = "left";
+      } else if (preferLeftOfBee) {
+        x = xLeft;
+        y = yH;
+        arrowEdge = "right";
+      } else {
+        x = xRight;
+        y = yH;
+        arrowEdge = "left";
+      }
+    }
+    return {
+      x: clamp(x, M, viewportWidth - tooltipWidth - M),
+      y: clamp(y, 64, viewportHeight - 64),
+      maxWidth: tooltipWidth,
+      arrowEdge
+    };
+  }
+  notifyMissingTarget() {
+    this.bee.setState("thinking");
+    this.bee.speak("I couldn't find that spot on this page.");
+    void this.finishAndDock(1e3);
+  }
+  async finishAndDock(delayMs) {
+    await this.delay(delayMs);
+    this.bee.hideActions();
+    this.bee.setState("idle");
+    await this.bee.dock();
+  }
+  /** Like finishAndDock but without docking — bee stays wherever it landed. */
+  async finishInPlace(delayMs) {
+    await this.delay(delayMs);
+    this.bee.hideActions();
+    this.bee.setState("idle");
+  }
+};
+
+// src/dom/captureContext.ts
+var MAX_TEXT = 80;
+var MAX_PROXIMITY_PX = 240;
+var INTERACTIVE_SELECTOR = 'a[href], button, input, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [role="radio"], [role="switch"], [contenteditable=""], [contenteditable="true"], [data-kibee-id]';
+function shortText(s) {
+  if (!s) return null;
+  const cleaned = s.replace(/\s+/g, " ").trim();
+  if (!cleaned) return null;
+  return cleaned.length > MAX_TEXT ? cleaned.slice(0, MAX_TEXT - 1) + "\u2026" : cleaned;
+}
+function visibleText(el) {
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    return shortText(el.placeholder || el.getAttribute("aria-label"));
+  }
+  if (el instanceof HTMLSelectElement) {
+    return shortText(el.getAttribute("aria-label"));
+  }
+  return shortText(el.textContent);
+}
+function elementRect(el) {
+  const r = el.getBoundingClientRect();
+  return { x: r.left, y: r.top, width: r.width, height: r.height };
+}
+function distanceToCentre(rect, x, y) {
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  return Math.hypot(cx - x, cy - y);
+}
+function selectorPath(target) {
+  const segments = [];
+  let el = target;
+  for (let i = 0; i < 6 && el && el !== document.body; i++) {
+    const tag = el.tagName.toLowerCase();
+    let seg = tag;
+    if (el.id) {
+      seg += `#${el.id}`;
+      segments.unshift(seg);
+      break;
+    }
+    const cls = (el.getAttribute("class") || "").split(/\s+/).filter((c) => c && !c.startsWith("kibee-")).slice(0, 2).join(".");
+    if (cls) seg += `.${cls}`;
+    segments.unshift(seg);
+    el = el.parentElement;
+  }
+  return segments.join(" > ");
+}
+function describeNearest(el, beeX, beeY) {
+  return {
+    tag: el.tagName.toLowerCase(),
+    text: visibleText(el),
+    role: el.getAttribute("role") || null,
+    kibeeId: el.getAttribute("data-kibee-id"),
+    testId: el.getAttribute("data-testid"),
+    domId: el.id || null,
+    selectorPath: selectorPath(el),
+    distancePx: Math.round(distanceToCentre(el.getBoundingClientRect(), beeX, beeY)),
+    rect: elementRect(el)
+  };
+}
+function findNearestInteractive(beeX, beeY) {
+  const stack = document.elementsFromPoint?.(beeX, beeY) ?? [];
+  for (const el of stack) {
+    if (el.matches?.(INTERACTIVE_SELECTOR)) return el;
+    const closest = el.closest?.(INTERACTIVE_SELECTOR);
+    if (closest) return closest;
+  }
+  let best = null;
+  const candidates = document.querySelectorAll(INTERACTIVE_SELECTOR);
+  for (const el of candidates) {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) continue;
+    if (r.bottom < 0 || r.top > window.innerHeight) continue;
+    if (r.right < 0 || r.left > window.innerWidth) continue;
+    const dist = distanceToCentre(r, beeX, beeY);
+    if (dist > MAX_PROXIMITY_PX) continue;
+    if (!best || dist < best.dist) best = { el, dist };
+  }
+  return best?.el ?? null;
+}
+function sampleNearbyText(beeX, beeY) {
+  const snippets = [];
+  const seen = /* @__PURE__ */ new Set();
+  const candidates = document.querySelectorAll(
+    "h1, h2, h3, h4, p, label, span, li, td, th, button"
+  );
+  for (const el of candidates) {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) continue;
+    const dist = distanceToCentre(r, beeX, beeY);
+    if (dist > MAX_PROXIMITY_PX) continue;
+    const t = visibleText(el);
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    snippets.push(t);
+    if (snippets.length >= 6) break;
+  }
+  return snippets;
+}
+function captureContext(input) {
+  const { beeX, beeY } = input;
+  const nearest = findNearestInteractive(beeX, beeY);
+  return {
+    pathname: location.pathname,
+    search: location.search,
+    hash: location.hash,
+    title: shortText(document.title) ?? "",
+    beePosition: { x: Math.round(beeX), y: Math.round(beeY) },
+    viewport: {
+      width: window.innerWidth,
+      height: window.innerHeight,
+      dpr: window.devicePixelRatio || 1
+    },
+    scroll: { x: window.scrollX, y: window.scrollY },
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    nearestElement: nearest ? describeNearest(nearest, beeX, beeY) : null,
+    nearbyText: sampleNearbyText(beeX, beeY)
+  };
+}
+
+// src/dom/Locator.ts
+var Locator = class {
+  resolve(target) {
+    const element = this.findElement(target);
+    if (!element) return null;
+    const rect = element.getBoundingClientRect();
+    return {
+      element,
+      rect,
+      centerX: rect.left + rect.width / 2,
+      centerY: rect.top + rect.height / 2
+    };
+  }
+  findElement(target) {
+    if (target.selector) {
+      const el = document.querySelector(target.selector);
+      if (el instanceof HTMLElement) return el;
+    }
+    const kibeeId = target.kibeeId ?? target.beeId;
+    if (kibeeId) {
+      const el = document.querySelector(`[data-kibee-id="${kibeeId}"]`);
+      if (el instanceof HTMLElement) return el;
+    }
+    if (target.textHints?.length) {
+      const candidates = Array.from(
+        document.querySelectorAll(
+          "button, a, input, textarea, select, [role='button'], [data-kibee-id]"
+        )
+      );
+      for (const node of candidates) {
+        if (!(node instanceof HTMLElement)) continue;
+        const text = this.getSearchableText(node).toLowerCase();
+        const matched = target.textHints.some(
+          (hint) => text.includes(hint.toLowerCase())
+        );
+        if (matched) return node;
+      }
+    }
+    return null;
+  }
+  scrollIntoView(target, behavior = "smooth") {
+    const resolved = this.resolve(target);
+    if (!resolved) return;
+    resolved.element.scrollIntoView({
+      behavior,
+      block: "center",
+      inline: "center"
+    });
+  }
+  getSearchableText(el) {
+    const bits = [
+      el.textContent ?? "",
+      el.getAttribute("aria-label") ?? "",
+      el.getAttribute("placeholder") ?? "",
+      el.getAttribute("title") ?? "",
+      el.getAttribute("data-kibee-id") ?? ""
+    ];
+    return bits.join(" ").trim();
+  }
+};
+
+// src/dom/TargetRegistry.ts
+var TargetRegistry = class {
+  targets = [];
+  set(targets) {
+    this.targets = [...targets];
+  }
+  list() {
+    return [...this.targets];
+  }
+  getVisibleTargets(doc = document) {
+    return this.targets.reduce((visible, target) => {
+      const kibeeId = target.target.kibeeId ?? target.target.beeId;
+      const node = kibeeId && doc.querySelector(`[data-kibee-id="${kibeeId}"]`) || (target.target.selector ? doc.querySelector(target.target.selector) : null);
+      if (!node) return visible;
+      const matchedText = [
+        node.textContent ?? "",
+        node.getAttribute("aria-label") ?? "",
+        node.getAttribute("placeholder") ?? ""
+      ].join(" ").trim();
+      visible.push({
+        ...target,
+        matchedText
+      });
+      return visible;
+    }, []);
+  }
+};
+
+// src/renderers/HighlightRenderer.ts
+var HighlightRenderer = class {
+  el = null;
+  mount(container = document.body) {
+    if (this.el) return;
+    this.el = document.createElement("div");
+    this.el.className = "kibee-highlight kibee-highlight--hidden";
+    container.appendChild(this.el);
+  }
+  show(rect, variant = "pulse") {
+    if (!this.el) return;
+    this.el.className = `kibee-highlight kibee-highlight--${variant}`;
+    this.el.style.left = `${rect.left - 6}px`;
+    this.el.style.top = `${rect.top - 6}px`;
+    this.el.style.width = `${rect.width + 12}px`;
+    this.el.style.height = `${rect.height + 12}px`;
+  }
+  hide() {
+    if (!this.el) return;
+    this.el.className = "kibee-highlight kibee-highlight--hidden";
+  }
+  destroy() {
+    if (!this.el) return;
+    this.el.remove();
+    this.el = null;
+  }
+};
+
+// src/KiBeeClient.ts
+var VISITOR_ID_KEY = "kibee:visitor_id";
+function getOrCreateVisitorId() {
+  if (typeof window === "undefined") return `srv_${Date.now()}`;
+  try {
+    const existing = localStorage.getItem(VISITOR_ID_KEY);
+    if (existing) return existing;
+    const id = typeof crypto !== "undefined" && crypto.randomUUID ? `kv_${crypto.randomUUID()}` : `kv_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    localStorage.setItem(VISITOR_ID_KEY, id);
+    return id;
+  } catch {
+    return `kv_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+}
+var KiBeeClient = class {
+  constructor(options) {
+    this.options = options;
+    this.visitorId = options.visitorId ?? getOrCreateVisitorId();
+    this.mountContainer = options.mountContainer;
+    const websiteId = options.websiteId;
+    let publicKey = options.publicKey;
+    if (!publicKey && options.apiKey) {
+      publicKey = options.apiKey;
+      if (typeof console !== "undefined") {
+        console.warn(
+          "[KiBee] `apiKey` option is deprecated \u2014 use `publicKey` instead. Removed in v1.0."
+        );
+      }
+    }
+    const isProd = typeof process !== "undefined" && typeof process.env !== "undefined" && process.env.NODE_ENV === "production";
+    if (isProd && (!websiteId || !publicKey)) {
+      throw new Error(
+        "[KiBee] Missing websiteId or publicKey. Get yours from your KiBee admin dashboard \u2192 Settings \u2192 Setup & Integration."
+      );
+    }
+    if (!isProd && (!websiteId || !publicKey) && typeof console !== "undefined") {
+      console.warn(
+        "[KiBee] Running in dev mode without websiteId \u2014 set websiteId and publicKey for production."
+      );
+    }
+    this.api = new KiBeeApiClient(
+      options.apiBaseUrl ?? "https://api.kibee.ai",
+      {
+        websiteId,
+        publicKey
+      }
+    );
+    this.controller = new FlowController(
+      this.options.renderer,
+      this.locator,
+      this.highlight,
+      this.bookmarks,
+      (command, phase) => {
+        void this.track("command_transition", {
+          commandType: command.type,
+          phase
+        });
+      }
+    );
+    if (options.useBridge && options.apiToken) {
+      const apiToken = options.apiToken;
+      const apiBase = options.apiBaseUrl ?? "";
+      const bridgeVisitorId = this.visitorId;
+      const bridgeUrl = apiBase.replace(/^http/, "ws") + "/v1/bridge";
+      this.bridgeClient = new BridgeClient({
+        bridgeUrl,
+        source: "web",
+        visitorId: bridgeVisitorId,
+        tokenFetcher: async () => {
+          const res = await fetch(`${apiBase}/v1/bridge/token`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${apiToken}` }
+          });
+          if (!res.ok) {
+            throw new Error(`bridge token fetch failed: ${res.status}`);
+          }
+          return res.json();
+        }
+      });
+      if (typeof window !== "undefined") {
+        this.bridgeUnsubscribes.push(
+          this.bridgeClient.on("presence:hello", (env) => {
+            window.dispatchEvent(
+              new CustomEvent("kibee-bridge-presence", {
+                detail: { source: env.source, present: true }
+              })
+            );
+          })
+        );
+        this.bridgeUnsubscribes.push(
+          this.bridgeClient.on("presence:bye", (env) => {
+            window.dispatchEvent(
+              new CustomEvent("kibee-bridge-presence", {
+                detail: { source: env.source, present: false }
+              })
+            );
+          })
+        );
+      }
+      this.bridgeUnsubscribes.push(
+        this.bridgeClient.on("flow:handoff", (envelope) => {
+          const payload = envelope.payload;
+          const flowId = payload != null && typeof payload === "object" && "flowId" in payload && typeof payload.flowId === "string" ? payload.flowId : void 0;
+          if (!flowId || flowId.length === 0) return;
+          void this.runFlowFromHandoff(flowId).catch((err) => {
+            console.warn("[kibee-sdk] flow:handoff run failed", err);
+          });
+        })
+      );
+      this.bridgeUnsubscribes.push(
+        this.bridgeClient.on("voice:state", (envelope) => {
+          const payload = envelope.payload;
+          const stateStr = payload != null && typeof payload === "object" && "state" in payload && typeof payload.state === "string" ? payload.state : void 0;
+          if (typeof stateStr !== "string") return;
+          if (envelope.source === "web") return;
+          this.otherSurfaceListening = stateStr === "listening";
+          if (typeof window !== "undefined") {
+            window.dispatchEvent(
+              new CustomEvent("kibee-voice-state", {
+                detail: { source: envelope.source, state: stateStr }
+              })
+            );
+          }
+        })
+      );
+    }
+  }
+  options;
+  api;
+  locator = new Locator();
+  highlight = new HighlightRenderer();
+  bookmarks = new BookmarkMemory();
+  registry = new TargetRegistry();
+  controller;
+  initPromise = null;
+  mountContainer;
+  currentPageId = "landing";
+  currentSession = null;
+  currentFlowId;
+  adminSyncTimer = null;
+  /** Polling cadence when SSE is unavailable / closed — the visitor
+   *  experience depends on this for new admin messages, so it stays
+   *  tight (5s default; afforestation passes 2.5s). */
+  fastPollInterval = 5e3;
+  /** Cadence when SSE is healthy. Polling becomes a heartbeat — it only
+   *  needs to catch state SSE doesn't push (friction score, pending
+   *  pushes) and recover any messages we somehow missed. */
+  slowPollInterval = 3e4;
+  presenceSessionPromise = null;
+  /** EventSource subscription for the per-session visitor stream. */
+  visitorStream = null;
+  /** Last-seen message timestamp for the polling fallback `?since=`. */
+  lastVisitorMessageAt = null;
+  /** Set of message ids the SDK has emitted to the panel — dedupes when a
+   *  message arrives via SSE *and* a subsequent poll. */
+  seenMessageIds = /* @__PURE__ */ new Set();
+  /** Distress signals tracker. Reset on a high-confidence resolve so the
+   *  bee doesn't nag if the visitor recovers on their own. */
+  consecutiveLowConfidence = 0;
+  lastDistressPromptAt = 0;
+  /** Current chat mode mirrored from the server. The panel reads this to
+   *  hide the "talk to a human" chip when an agent is on. */
+  chatMode = "ai";
+  /** Mirror of whether the host's chat panel is currently visible. The
+   *  panel dispatches kibee-panel-open / -close — we listen so we can
+   *  decide whether to surface an inbound admin message as a bee tooltip
+   *  (panel closed → speak it so the visitor notices) or stay quiet
+   *  (panel open → the thread already shows it; tooltip would dupe). */
+  panelOpen = false;
+  /** S3 T5: optional cross-surface bridge client. Initialized only when
+   *  `useBridge: true` AND `apiToken` are passed at construction. */
+  bridgeClient;
+  /** S4 T4: unsubscribes for handlers registered against `bridgeClient`. Drained
+   *  in `destroy()` so we don't leave dangling handlers if a host swaps clients. */
+  bridgeUnsubscribes = [];
+  /** S4 T4: in-flight `flow:handoff` flowIds. Guards against the same flow being
+   *  started twice if duplicate envelopes arrive (e.g. retried publish). */
+  inflightHandoffFlowIds = /* @__PURE__ */ new Set();
+  /** S4 T7: mirrors whether another surface (extension/desktop) is currently
+   *  holding the listening floor (announced via `voice:state` over the bridge).
+   *  The SDK has no built-in voice listening UI today — voice is host-implemented
+   *  — so this is exposed as a flag + a `kibee-voice-state` CustomEvent that hosts
+   *  can subscribe to in order to suppress their own listening indicator. */
+  otherSurfaceListening = false;
+  visitorId;
+  /**
+   * Connects to the cross-surface bridge (`/v1/bridge`). No-op when
+   * `useBridge` was false or `apiToken` was missing at construction.
+   */
+  async connectBridge() {
+    if (!this.bridgeClient) return;
+    await this.bridgeClient.connect();
+  }
+  /**
+   * Register a handler for inbound bridge envelopes of a specific type.
+   * Returns an unsubscribe function. No-op (returns a noop unsubscribe)
+   * when the bridge isn't initialized.
+   */
+  onBridgeEvent(type, handler) {
+    if (!this.bridgeClient) {
+      return () => {
+      };
+    }
+    return this.bridgeClient.on(type, handler);
+  }
+  /**
+   * S4 T6: ask another surface (typically `desktop`) to point its on-screen
+   * bee at a global screen coordinate. No-op when the bridge isn't wired
+   * (`useBridge: false` or `apiToken` missing) — the caller doesn't need
+   * to feature-detect.
+   *
+   * `tenantId`, `workspaceId`, and `visitorId` set here are advisory: the
+   * broker overwrites identity fields with JWT-derived values on receipt
+   * (S2 T2 invariant). `source: "web"` is hardcoded because the SDK ships
+   * web-only by default; the broker also enforces source against the
+   * value bound at WS handshake.
+   */
+  async requestPointTo(coord) {
+    if (!this.bridgeClient) return;
+    const envelope = {
+      v: 1,
+      source: "web",
+      target: "desktop",
+      tenantId: null,
+      workspaceId: null,
+      visitorId: this.visitorId,
+      sessionId: this.currentSession?.id ?? null,
+      type: "pointer:show",
+      ts: Date.now(),
+      payload: coord
+    };
+    this.bridgeClient.send(envelope);
+  }
+  async init() {
+    if (this.initPromise) return this.initPromise;
+    if (typeof window !== "undefined") {
+      window.addEventListener("kibee-panel-open", () => {
+        this.panelOpen = true;
+      });
+      window.addEventListener("kibee-panel-close", () => {
+        this.panelOpen = false;
+      });
+    }
+    this.initPromise = (async () => {
+      await this.options.renderer.mount(this.mountContainer);
+      await this.controller.init();
+      this.options.renderer.showActions((choice) => {
+        const kind = choice === "honey" ? "honey" : "sting";
+        const baseLabel = choice === "honey" ? "Bookmarked" : "Friction point";
+        const beePos = this.options.renderer.getBeePosition?.() ?? { x: 0, y: 0 };
+        const context = captureContext({ beeX: beePos.x, beeY: beePos.y });
+        const promptMessage = choice === "honey" ? "What's worth coming back to?" : "What felt rough? (one line is plenty)";
+        const placeholder = choice === "honey" ? 'e.g. "Pricing examples table"' : 'e.g. "Filter resets on back-nav"';
+        void this.options.renderer.prompt(promptMessage, { placeholder }).then((userNote) => {
+          const note = userNote && userNote.length > 0 ? userNote : choice === "honey" ? "User bookmarked this page" : "User flagged friction on this page";
+          const nearText = context.nearestElement?.text;
+          const label = nearText ? `${baseLabel}: ${nearText}` : baseLabel;
+          const bookmark = this.bookmarks.create({
+            kind,
+            label,
+            target: { kibeeId: this.currentPageId },
+            note,
+            metadata: {
+              userNoteProvided: typeof userNote === "string" && userNote.length > 0,
+              context
+            }
+          });
+          if (bookmark) {
+            this.options.renderer.speak(
+              choice === "honey" ? "Saved! This page is bookmarked." : "Noted! This friction point has been recorded."
+            );
+            void this.track("bookmark_saved", {
+              kind,
+              label,
+              hasUserNote: typeof userNote === "string" && userNote.length > 0,
+              pathname: context.pathname,
+              nearestTag: context.nearestElement?.tag ?? null,
+              nearestKibeeId: context.nearestElement?.kibeeId ?? null
+            });
+          }
+        });
+      });
+      await this.track("runtime_initialized");
+    })();
+    return this.initPromise;
+  }
+  identifyPage(pageId, metadata) {
+    this.currentPageId = pageId;
+    void this.track("page_identified", metadata);
+    void this.ensurePresenceSession();
+  }
+  registerTargets(targets) {
+    this.registry.set(targets);
+    void this.track("targets_registered", {
+      count: targets.length,
+      targetIds: targets.map((target) => target.id)
+    });
+  }
+  getRegisteredTargets() {
+    return this.registry.list();
+  }
+  async runFlow(flowOrId) {
+    await this.init();
+    let flow;
+    try {
+      flow = typeof flowOrId === "string" ? await this.api.fetchFlow(flowOrId) : flowOrId;
+    } catch {
+      this.options.renderer.setState("thinking");
+      this.options.renderer.speak(
+        "KiBee can't reach the orchestration API right now. Start the API service to run guided flows."
+      );
+      throw new Error("Unable to fetch KiBee flow definition.");
+    }
+    this.currentFlowId = flow.id;
+    this.currentSession = await this.startSession(flow.id);
+    await this.track("flow_started", {
+      flowId: flow.id,
+      title: flow.title,
+      goal: flow.goal
+    });
+    await this.controller.runFlow(flow);
+    this.currentSession = this.currentSession ? {
+      ...this.currentSession,
+      status: "completed",
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    } : null;
+    await this.track("flow_completed", {
+      flowId: flow.id,
+      title: flow.title
+    });
+    return flow;
+  }
+  /**
+   * Run a flow in interactive step-through mode: the bee tooltip shows
+   * prev / next buttons so the user controls the pace instead of
+   * auto-advancing on click/input events.
+   */
+  async runInteractiveFlow(flowOrId) {
+    await this.init();
+    let flow;
+    try {
+      flow = typeof flowOrId === "string" ? await this.api.fetchFlow(flowOrId) : flowOrId;
+    } catch {
+      this.options.renderer.setState("thinking");
+      this.options.renderer.speak(
+        "KiBee can't reach the orchestration API right now. Start the API service to run guided flows."
+      );
+      throw new Error("Unable to fetch KiBee flow definition.");
+    }
+    this.currentFlowId = flow.id;
+    this.currentSession = await this.startSession(flow.id);
+    await this.track("flow_started", {
+      flowId: flow.id,
+      title: flow.title,
+      goal: flow.goal,
+      mode: "interactive"
+    });
+    await this.controller.runInteractiveFlow(flow);
+    return flow;
+  }
+  async ask(input) {
+    await this.init();
+    this.options.renderer.setState("thinking");
+    let match;
+    try {
+      match = await this.api.resolveIntent({
+        input,
+        pageId: this.currentPageId,
+        visibleTargets: this.registry.getVisibleTargets(),
+        sessionId: this.currentSession?.id
+      });
+    } catch {
+      this.options.renderer.speak(
+        "KiBee can't resolve intent while the API is offline."
+      );
+      throw new Error("Unable to resolve KiBee intent.");
+    }
+    if (match.message) {
+      this.options.renderer.speak(match.message);
+    }
+    await this.track("intent_resolved", {
+      input,
+      flowId: match.flowId ?? void 0,
+      confidence: match.confidence
+    });
+    if (match.flowId) {
+      await this.runFlow(match.flowId);
+    }
+    return match;
+  }
+  /**
+   * Visitor-facing chat send. Wraps `ask()` so the rule-matched answer
+   * still drives flows when intent is clear, but ALSO:
+   *   - emits a `kibee-message-received` event for each customer + ai
+   *     message so the panel renders them as bubbles even before the SSE
+   *     stream catches up
+   *   - tracks distress signals (low confidence streaks, "human"
+   *     keywords) and dispatches `kibee-distress-detected` so the panel
+   *     can surface the inline "want a teammate?" prompt
+   */
+  async send(input) {
+    if (!input.trim()) return;
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(
+        new CustomEvent("kibee-message-received", {
+          detail: {
+            id: `local-${Date.now()}`,
+            sender: "customer",
+            text: input,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            optimistic: true
+          }
+        })
+      );
+    }
+    if (/\b(human|agent|support|talk to (someone|person))\b/i.test(input)) {
+      void this.requestHumanFromKeyword();
+    }
+    const match = await this.ask(input);
+    if (match.confidence < 0.35) {
+      this.consecutiveLowConfidence += 1;
+      if (this.consecutiveLowConfidence >= 2 && this.shouldShowDistressPrompt()) {
+        this.dispatchDistressPrompt("low_confidence_streak");
+      }
+    } else if (match.confidence >= 0.55) {
+      this.consecutiveLowConfidence = 0;
+    }
+  }
+  /**
+   * Visitor-initiated escalation. Called by the panel's "Talk to a human"
+   * chip and by the inline distress prompt's "Yes please" button.
+   */
+  async escalateToHuman() {
+    if (!this.currentSession) return;
+    try {
+      await this.api.escalateToHuman(this.currentSession.id);
+      if (typeof window !== "undefined") {
+        window.dispatchEvent(
+          new CustomEvent("kibee-escalated", { detail: { sessionId: this.currentSession.id } })
+        );
+      }
+    } catch {
+    }
+  }
+  /**
+   * Surface an incoming agent / AI message as a bee speech bubble when the
+   * panel is closed, so a passive visitor sees that someone replied. The
+   * panel-open path stays quiet because the panel thread already shows the
+   * message — speaking would dupe it.
+   *
+   * Skipped for `customer` (the visitor's own echoed message) and `system`
+   * (admin annotations like "Sahil joined the conversation" — visible only
+   * inside the panel).
+   */
+  maybeSpeakIncomingMessage(msg) {
+    if (this.panelOpen) return;
+    if (msg.sender !== "agent" && msg.sender !== "ai") return;
+    if (!msg.text) return;
+    try {
+      this.options.renderer.speak(msg.text, { maxWidth: 280 });
+    } catch {
+    }
+  }
+  shouldShowDistressPrompt() {
+    if (this.chatMode === "human") return false;
+    return Date.now() - this.lastDistressPromptAt > 9e4;
+  }
+  dispatchDistressPrompt(reason) {
+    this.lastDistressPromptAt = Date.now();
+    if (typeof window === "undefined") return;
+    window.dispatchEvent(
+      new CustomEvent("kibee-distress-detected", { detail: { reason } })
+    );
+  }
+  async requestHumanFromKeyword() {
+    if (this.chatMode === "human") return;
+    if (this.shouldShowDistressPrompt()) {
+      this.dispatchDistressPrompt("keyword");
+    }
+  }
+  async saveHoney(label, target, note) {
+    await this.init();
+    const bookmark = await this.controller.createHoneyBookmark(label, target, note);
+    if (bookmark) {
+      await this.track("bookmark_saved", {
+        kind: "honey",
+        label
+      });
+    }
+    return bookmark;
+  }
+  async saveSting(label, target, note) {
+    await this.init();
+    const bookmark = await this.controller.createStingBookmark(label, target, note);
+    if (bookmark) {
+      await this.track("bookmark_saved", {
+        kind: "sting",
+        label
+      });
+    }
+    return bookmark;
+  }
+  listBookmarks() {
+    return this.controller.listBookmarks();
+  }
+  removeBookmark(id) {
+    this.controller.removeBookmark(id);
+  }
+  async revisitBookmark(bookmark) {
+    await this.controller.revisitBookmark(bookmark);
+  }
+  clearFocus() {
+    this.controller.clearFocus();
+  }
+  /**
+   * When true, the dock button toggles the in-app assistant (kibee-assist-toggle)
+   * instead of immediately undocking the bee.
+   */
+  setDockAssistPanel(enabled) {
+    this.options.renderer.setDockClickBehavior(
+      enabled ? "assist-panel" : "undock"
+    );
+  }
+  async track(type, metadata) {
+    const event = {
+      type,
+      pageId: this.currentPageId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      visitorId: this.visitorId,
+      sessionId: this.currentSession?.id,
+      flowId: this.currentFlowId,
+      metadata
+    };
+    this.options.onEvent?.(event);
+    try {
+      await this.api.trackEvent({ event });
+    } catch {
+    }
+  }
+  /** Returns the dock's current screen position (center of the dock button) */
+  getDockPosition() {
+    return this.options.renderer.getDockScreenPosition();
+  }
+  /**
+   * Polls the API for admin-pushed flows/targets AND drains new chat
+   * messages on the same tick. Also opens the per-session visitor SSE
+   * stream so messages arrive in real time when the network supports it
+   * (polling stays as a guaranteed-delivery backstop).
+   *
+   * Call after init() and startSession() to enable admin push support.
+   *
+   * Cadence is SSE-aware: when the visitor stream is OPEN (realtime is
+   * delivering messages), polling backs off to a 30s heartbeat — just
+   * enough to catch state the SSE channel can't push (e.g. friction
+   * score, drained pending pushes). On SSE error/close the interval
+   * snaps back to `intervalMs` so polling carries the load until SSE
+   * reconnects.
+   *
+   * The single `/v1/visitor/sync` endpoint returns messages + pending
+   * pushes + mode + friction in one round-trip, so each tick is one
+   * request instead of two.
+   */
+  enableAdminSync(intervalMs = 5e3) {
+    this.disableAdminSync();
+    this.fastPollInterval = intervalMs;
+    void this.pollVisitorSync();
+    this.armSyncTimer();
+    this.openVisitorStream();
+  }
+  disableAdminSync() {
+    if (this.adminSyncTimer) {
+      clearInterval(this.adminSyncTimer);
+      this.adminSyncTimer = null;
+    }
+    if (this.visitorStream) {
+      this.visitorStream.close();
+      this.visitorStream = null;
+    }
+  }
+  /** (Re)arm the polling interval based on current SSE health. Called
+   *  whenever SSE state changes (open / error) so the interval reflects
+   *  reality without dropping a tick. */
+  armSyncTimer() {
+    if (this.adminSyncTimer) {
+      clearInterval(this.adminSyncTimer);
+      this.adminSyncTimer = null;
+    }
+    const healthy = this.visitorStream?.readyState === 1;
+    const ms = healthy ? this.slowPollInterval : this.fastPollInterval;
+    this.adminSyncTimer = setInterval(() => {
+      void this.pollVisitorSync();
+    }, ms);
+  }
+  /**
+   * Single visitor poll. Drains pending flow pushes (admin → SDK) AND
+   * sucks in new chat messages in one HTTP request. Always runs alongside
+   * SSE so a missed event during network blips eventually shows up;
+   * `seenMessageIds` dedupes anything SSE already delivered.
+   */
+  async pollVisitorSync() {
+    if (!this.currentSession) return;
+    try {
+      const data = await this.api.fetchVisitorSync(
+        this.currentSession.id,
+        this.lastVisitorMessageAt
+      );
+      this.handleVisitorPoll(data);
+      for (const push of data.pendingPushes) {
+        if (push.flowId) {
+          const flow = await this.api.fetchFlow(push.flowId);
+          if (flow) await this.runFlow(flow);
+        }
+      }
+    } catch {
+    }
+  }
+  handleVisitorPoll(data) {
+    if (typeof window === "undefined") return;
+    if (data.mode !== this.chatMode) {
+      this.chatMode = data.mode;
+      window.dispatchEvent(
+        new CustomEvent("kibee-mode-changed", {
+          detail: { mode: data.mode, hasAgent: data.hasAgent }
+        })
+      );
+    }
+    for (const msg of data.messages) {
+      if (this.seenMessageIds.has(msg.id)) continue;
+      this.seenMessageIds.add(msg.id);
+      window.dispatchEvent(new CustomEvent("kibee-message-received", { detail: msg }));
+      this.maybeSpeakIncomingMessage(msg);
+    }
+    if (data.lastMessageAt) {
+      this.lastVisitorMessageAt = data.lastMessageAt;
+    }
+    if (data.frictionScore > 120 && this.shouldShowDistressPrompt()) {
+      window.dispatchEvent(
+        new CustomEvent("kibee-friction-high", {
+          detail: { score: data.frictionScore, pageId: this.currentPageId }
+        })
+      );
+    }
+  }
+  openVisitorStream() {
+    if (!this.currentSession || this.visitorStream) return;
+    const stream = this.api.openVisitorStream(this.currentSession.id);
+    if (!stream) return;
+    stream.onopen = () => {
+      this.armSyncTimer();
+    };
+    stream.onmessage = (ev) => {
+      try {
+        const event = JSON.parse(ev.data);
+        if (event.type === "message_sent") {
+          const msg = event.payload;
+          if (msg && msg.id && !this.seenMessageIds.has(msg.id)) {
+            this.seenMessageIds.add(msg.id);
+            this.lastVisitorMessageAt = msg.timestamp;
+            if (typeof window !== "undefined") {
+              window.dispatchEvent(new CustomEvent("kibee-message-received", { detail: msg }));
+            }
+            this.maybeSpeakIncomingMessage(msg);
+          }
+        } else if (event.type === "session_mode_changed") {
+          const payload = event.payload;
+          if (payload.mode !== this.chatMode) {
+            this.chatMode = payload.mode;
+            if (typeof window !== "undefined") {
+              window.dispatchEvent(
+                new CustomEvent("kibee-mode-changed", { detail: payload })
+              );
+            }
+          }
+        }
+      } catch {
+      }
+    };
+    stream.onerror = () => {
+      if (stream.readyState === 2) {
+        stream.close();
+        this.visitorStream = null;
+      }
+      this.armSyncTimer();
+    };
+    this.visitorStream = stream;
+  }
+  destroy() {
+    for (const unsubscribe of this.bridgeUnsubscribes) {
+      try {
+        unsubscribe();
+      } catch {
+      }
+    }
+    this.bridgeUnsubscribes = [];
+    this.inflightHandoffFlowIds.clear();
+    this.bridgeClient?.close();
+    this.bridgeClient = void 0;
+    this.disableAdminSync();
+    this.options.renderer.destroy();
+    this.clearFocus();
+  }
+  /**
+   * S4 T4: run a flow handed off via the bridge. Wraps `runFlow(flowId)` with
+   * an in-flight guard so duplicate `flow:handoff` envelopes for the same
+   * flowId (e.g. retried publish) don't start two concurrent runs.
+   */
+  async runFlowFromHandoff(flowId) {
+    if (this.inflightHandoffFlowIds.has(flowId)) return;
+    if (!this.bridgeClient) return;
+    this.inflightHandoffFlowIds.add(flowId);
+    try {
+      await this.runFlow(flowId);
+    } finally {
+      this.inflightHandoffFlowIds.delete(flowId);
+    }
+  }
+  async startSession(flowId) {
+    try {
+      return await this.api.startSession({
+        visitorId: this.visitorId,
+        pageId: this.currentPageId,
+        flowId
+      });
+    } catch {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      return {
+        id: `local_${Math.random().toString(36).slice(2, 10)}`,
+        visitorId: this.visitorId,
+        pageId: this.currentPageId,
+        flowId,
+        currentStepIndex: 0,
+        status: "active",
+        startedAt: now,
+        updatedAt: now
+      };
+    }
+  }
+  /**
+   * Creates a server session once the page is known so admin "Visitors" and
+   * analytics can attach to a real `sessionId` (not only when a flow runs).
+   */
+  async ensurePresenceSession() {
+    if (this.currentSession?.status === "active") return;
+    if (this.presenceSessionPromise) {
+      await this.presenceSessionPromise;
+      return;
+    }
+    this.presenceSessionPromise = (async () => {
+      await this.init();
+      if (this.currentSession?.status === "active") return;
+      this.currentSession = await this.startSession(void 0);
+    })().finally(() => {
+      this.presenceSessionPromise = null;
+    });
+    await this.presenceSessionPromise;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BookmarkMemory,
+  BridgeClient,
+  FlowController,
+  HighlightRenderer,
+  KiBeeApiClient,
+  KiBeeClient,
+  Locator,
+  TargetRegistry
+});