@kibee/renderer-three 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1875 @@
+// src/ThreeBeeRenderer.ts
+import * as THREE2 from "three";
+import { gsap } from "gsap";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+
+// src/gltf/registerPbrSpecularGlossinessGLTFPlugin.ts
+import { Color, LinearSRGBColorSpace, SRGBColorSpace } from "three";
+var EXT = "KHR_materials_pbrSpecularGlossiness";
+function registerPbrSpecularGlossinessGLTFPlugin(loader) {
+  loader.register((parser) => ({
+    name: EXT,
+    extendMaterialParams(materialIndex, materialParams) {
+      const materialDef = parser.json.materials?.[materialIndex];
+      const ext = materialDef?.extensions?.[EXT];
+      if (!ext) return Promise.resolve();
+      const pending = [];
+      if (Array.isArray(ext.diffuseFactor) && ext.diffuseFactor.length >= 3) {
+        const c = new Color().setRGB(
+          ext.diffuseFactor[0],
+          ext.diffuseFactor[1],
+          ext.diffuseFactor[2],
+          LinearSRGBColorSpace
+        );
+        materialParams.color = c;
+        if (ext.diffuseFactor[3] !== void 0) {
+          materialParams.opacity = ext.diffuseFactor[3];
+          materialParams.transparent = ext.diffuseFactor[3] < 1;
+        }
+      }
+      if (ext.diffuseTexture !== void 0) {
+        pending.push(
+          parser.assignTexture(
+            materialParams,
+            "map",
+            ext.diffuseTexture,
+            SRGBColorSpace
+          )
+        );
+      }
+      const gloss = ext.glossinessFactor ?? 1;
+      materialParams.roughness = Math.min(1, Math.max(0.04, 1 - gloss));
+      materialParams.metalness = 0;
+      return Promise.all(pending);
+    }
+  }));
+}
+
+// src/legacyBeeMaterial.ts
+import * as THREE from "three";
+function toMeshArray(node) {
+  const meshes = [];
+  node.traverse((child) => {
+    if (child instanceof THREE.Mesh) {
+      meshes.push(child);
+    }
+  });
+  return meshes;
+}
+async function applyLegacyBeeMaterialCompat(gltf) {
+  const parser = gltf.parser;
+  const materialDef = parser?.json?.materials?.[0];
+  const legacyDef = materialDef?.extensions?.KHR_materials_pbrSpecularGlossiness;
+  if (!parser?.loadTexture || !legacyDef?.diffuseTexture) {
+    return;
+  }
+  const diffuseMap = await parser.loadTexture(legacyDef.diffuseTexture.index);
+  const normalMap = materialDef?.normalTexture ? await parser.loadTexture(materialDef.normalTexture.index) : null;
+  const aoMap = materialDef?.occlusionTexture ? await parser.loadTexture(materialDef.occlusionTexture.index) : null;
+  diffuseMap.colorSpace = THREE.SRGBColorSpace;
+  const meshes = toMeshArray(gltf.scene);
+  for (const mesh of meshes) {
+    const previousMaterial = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+    const replacement = new THREE.MeshStandardMaterial({
+      map: diffuseMap,
+      normalMap,
+      aoMap,
+      roughness: 0.76,
+      metalness: 0.02,
+      transparent: true,
+      alphaTest: 0.08,
+      side: materialDef?.doubleSided ? THREE.DoubleSide : THREE.FrontSide
+    });
+    if (mesh.geometry.getAttribute("uv") && !mesh.geometry.getAttribute("uv2")) {
+      mesh.geometry.setAttribute("uv2", mesh.geometry.getAttribute("uv"));
+    }
+    mesh.material = replacement;
+    if (previousMaterial && "dispose" in previousMaterial) {
+      previousMaterial.dispose();
+    }
+  }
+}
+
+// src/ThreeBeeRenderer.ts
+var CLIP_BY_STATE = {
+  idle: "idle",
+  guiding: "hover",
+  thinking: "hover",
+  celebrating: "take_off_and_land"
+};
+var ThreeBeeRenderer = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.dockClickBehavior = options.dockClickBehavior ?? "undock";
+    this.restorePersistedDockPosition = options.restorePersistedDockPosition !== false;
+    if (this.restorePersistedDockPosition) {
+      try {
+        const saved = localStorage.getItem("kibee:dock_pos");
+        if (saved) {
+          const pos = JSON.parse(saved);
+          if (typeof pos.x === "number" && typeof pos.y === "number") {
+            this.customDockPos = pos;
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  options;
+  root;
+  canvasWrap;
+  tooltip;
+  hoverZone;
+  dockButton;
+  scene;
+  camera;
+  renderer;
+  beeGroup = new THREE2.Group();
+  visualRig = new THREE2.Group();
+  mixer = null;
+  actions = /* @__PURE__ */ new Map();
+  activeActionName = null;
+  runtimeWings = null;
+  mounted = false;
+  /** Deduplicates concurrent mount() calls (React Strict Mode, double init, etc.) */
+  mountPromise = null;
+  disposed = false;
+  animationFrameId = null;
+  clock = new THREE2.Clock();
+  state = "idle";
+  currentX = 120;
+  currentY = 120;
+  currentFacing = "right";
+  docked = true;
+  dockVisible = true;
+  hoveringHome = false;
+  reducedMotion = false;
+  renderingAvailable = false;
+  idleTween = null;
+  celebrateTween = null;
+  tooltipPulseTimer = null;
+  tooltipMessage = "";
+  actionHandler = null;
+  dockClickBehavior;
+  autoDockTimer = null;
+  customDockPos = null;
+  // Radial action buttons (individually positioned, not wrapped)
+  radialButtons = [];
+  // Drag state
+  isDragging = false;
+  dragStartX = 0;
+  dragStartY = 0;
+  dragMoved = false;
+  /** Pointer went down while docked — used to distinguish dock tap vs drag-out */
+  dragArmedFromDock = false;
+  // Debounce timer — prevents hiding buttons while cursor travels to them
+  hideButtonsTimer = null;
+  // Whether the bee is currently parked at the chat panel header
+  panelOpen = false;
+  /** When false, constructor skips LS restore and setCustomDockPosition skips LS writes by default. */
+  restorePersistedDockPosition;
+  // Tooltip nav elements (created in initDOM)
+  tooltipText;
+  tooltipNav;
+  navPrevBtn;
+  navLabel;
+  navNextBtn;
+  tooltipHasNav = false;
+  // Inline prompt (used when capturing a 1-2 line note for honey/sting)
+  tooltipPrompt;
+  tooltipPromptInput;
+  tooltipPromptSaveBtn;
+  tooltipPromptSkipBtn;
+  tooltipPromptHint;
+  tooltipPromptActive = false;
+  tooltipPromptMaxLen = 240;
+  async mount(container = document.body) {
+    if (this.mounted) return;
+    if (this.mountPromise) {
+      await this.mountPromise;
+      return;
+    }
+    this.mountPromise = this.performMount(container);
+    try {
+      await this.mountPromise;
+    } finally {
+      this.mountPromise = null;
+    }
+  }
+  async performMount(container) {
+    this.reducedMotion = this.shouldReduceMotion();
+    this.disposed = false;
+    this.createRoot(container);
+    this.createScene();
+    this.createCamera();
+    this.createRenderer();
+    this.scene.add(this.beeGroup);
+    this.beeGroup.add(this.visualRig);
+    if (this.renderingAvailable) {
+      this.createLights();
+      const loaded = await this.loadBeeModel();
+      if (!loaded) {
+        this.createFallbackBee();
+      }
+    }
+    this.resize();
+    this.initializeDockedHome();
+    if (this.renderingAvailable) {
+      this.startRenderLoop();
+    }
+    this.mounted = true;
+    document.body.dataset.kibeeRendererActive = "true";
+    this.state = "guiding";
+    this.setState("idle");
+    window.addEventListener("resize", this.handleResize, { passive: true });
+    document.addEventListener("visibilitychange", this.handleVisibilityChange);
+    window.addEventListener("pointermove", this.handlePointerMove, {
+      passive: true
+    });
+    window.addEventListener("pointerup", this.handlePointerUp);
+    window.addEventListener("kibee-panel-open", this.handlePanelOpen);
+    window.addEventListener("kibee-panel-close", this.handlePanelClose);
+  }
+  async moveTo(x, y, options = {}) {
+    const duration = options.duration ?? 0.9;
+    const offsetX = options.offsetX ?? 16;
+    const offsetY = options.offsetY ?? -18;
+    const targetX = x + offsetX;
+    const targetY = y + offsetY;
+    await this.undock();
+    this.hoveringHome = false;
+    this.applyFacing(targetX >= this.currentX ? "right" : "left");
+    this.setState("guiding");
+    return new Promise((resolve) => {
+      gsap.to(this.beeGroup.scale, {
+        x: this.getActiveScale(),
+        y: this.getActiveScale(),
+        z: this.getActiveScale(),
+        duration: 0.24,
+        ease: "power2.out",
+        overwrite: "auto"
+      });
+      gsap.to(this, {
+        currentX: targetX,
+        currentY: targetY,
+        duration,
+        ease: "power2.out",
+        overwrite: "auto",
+        onUpdate: () => {
+          this.updateBeeScreenPosition();
+          this.positionTooltipNearBee();
+        },
+        onComplete: () => {
+          this.setState("idle");
+          resolve();
+        }
+      });
+    });
+  }
+  async dock() {
+    if (!this.isDockEnabled()) return;
+    if (this.docked) return;
+    this.clearAutoDockTimer();
+    this.hideMessage();
+    this.clearHideButtonsTimer();
+    this.hideRadialButtons();
+    const dock = this.getDockCenter();
+    this.dockVisible = true;
+    this.hoveringHome = false;
+    this.stopStateTweens();
+    this.applyHomeFacing();
+    this.syncDockState();
+    if (this.reducedMotion) {
+      this.currentX = dock.x;
+      this.currentY = dock.y;
+      this.docked = true;
+      this.beeGroup.scale.setScalar(this.getDockedScale());
+      this.updateBeeScreenPosition();
+      this.syncDockState();
+      if (this.state === "idle") {
+        this.startIdleMotion();
+      }
+      return;
+    }
+    return new Promise((resolve) => {
+      gsap.timeline({
+        onComplete: () => {
+          this.currentX = dock.x;
+          this.currentY = dock.y;
+          this.docked = true;
+          this.syncDockState();
+          if (this.state === "idle") {
+            this.startIdleMotion();
+          }
+          resolve();
+        }
+      }).to(
+        this,
+        {
+          currentX: dock.x,
+          currentY: dock.y,
+          duration: 0.58,
+          ease: "power2.inOut",
+          overwrite: "auto",
+          onUpdate: () => {
+            this.updateBeeScreenPosition();
+            this.positionTooltipNearBee();
+          }
+        },
+        0
+      ).to(
+        this.beeGroup.scale,
+        {
+          x: this.getDockedScale(),
+          y: this.getDockedScale(),
+          z: this.getDockedScale(),
+          duration: 0.58,
+          ease: "power2.inOut",
+          overwrite: "auto"
+        },
+        0
+      ).to(
+        this.beeGroup.rotation,
+        {
+          z: 0.02,
+          duration: 0.2,
+          ease: "sine.out",
+          overwrite: "auto"
+        },
+        0
+      );
+    });
+  }
+  resetAutoDockTimer() {
+    if (this.autoDockTimer) clearTimeout(this.autoDockTimer);
+    this.autoDockTimer = setTimeout(() => {
+      if (!this.docked && this.state === "idle") {
+        void this.dock();
+      }
+    }, 1e4);
+  }
+  clearAutoDockTimer() {
+    if (this.autoDockTimer) {
+      clearTimeout(this.autoDockTimer);
+      this.autoDockTimer = null;
+    }
+  }
+  async undock(options = {}) {
+    if (!this.isDockEnabled()) return;
+    this.resetAutoDockTimer();
+    const hideDock = options.hideDock ?? true;
+    this.docked = false;
+    this.dockVisible = !hideDock;
+    this.hoveringHome = !hideDock;
+    this.syncDockState();
+    if (hideDock) {
+      if (this.reducedMotion) {
+        this.beeGroup.scale.setScalar(this.getActiveScale());
+        return;
+      }
+      return new Promise((resolve) => {
+        gsap.to(this.beeGroup.scale, {
+          x: this.getActiveScale(),
+          y: this.getActiveScale(),
+          z: this.getActiveScale(),
+          duration: 0.24,
+          ease: "power2.out",
+          overwrite: "auto",
+          onComplete: resolve
+        });
+      });
+    }
+    const wake = this.getWakeHoverPosition();
+    this.stopStateTweens();
+    this.applyHomeFacing();
+    if (this.reducedMotion) {
+      this.currentX = wake.x;
+      this.currentY = wake.y;
+      this.updateBeeScreenPosition();
+      this.beeGroup.scale.setScalar(this.getHomeHoverScale());
+      if (this.state === "idle") {
+        this.startIdleMotion();
+      }
+      return;
+    }
+    return new Promise((resolve) => {
+      gsap.timeline({
+        onComplete: () => {
+          this.currentX = wake.x;
+          this.currentY = wake.y;
+          if (this.state === "idle") {
+            this.startIdleMotion();
+          }
+          resolve();
+        }
+      }).to(
+        this,
+        {
+          currentX: wake.x,
+          currentY: wake.y,
+          duration: 0.36,
+          ease: "power2.out",
+          overwrite: "auto",
+          onUpdate: () => {
+            this.updateBeeScreenPosition();
+            this.positionTooltipNearBee();
+          }
+        },
+        0
+      ).to(
+        this.beeGroup.scale,
+        {
+          x: this.getHomeHoverScale(),
+          y: this.getHomeHoverScale(),
+          z: this.getHomeHoverScale(),
+          duration: 0.36,
+          ease: "power2.out",
+          overwrite: "auto"
+        },
+        0
+      );
+    });
+  }
+  isDocked() {
+    return this.docked;
+  }
+  setState(state) {
+    if (!this.mounted) return;
+    if (this.state === state) return;
+    this.state = state;
+    this.syncDockState();
+    this.stopStateTweens();
+    if (state !== "idle") {
+      this.clearHideButtonsTimer();
+      this.hideRadialButtons();
+      if (this.panelOpen) {
+        window.dispatchEvent(new CustomEvent("kibee-panel-close"));
+        this.panelOpen = false;
+      }
+    }
+    switch (state) {
+      case "idle":
+        this.startIdleMotion();
+        break;
+      case "guiding":
+        this.playClipForState("guiding");
+        gsap.to(this.beeGroup.rotation, {
+          z: this.reducedMotion ? 0.04 : 0.08,
+          duration: 0.22,
+          ease: "power1.out",
+          overwrite: "auto"
+        });
+        break;
+      case "thinking":
+        this.startThinkingMotion();
+        break;
+      case "celebrating":
+        this.startCelebrateMotion();
+        break;
+    }
+  }
+  speak(message, options = {}) {
+    if (!this.mounted) return;
+    if (this.docked) return;
+    if (this.panelOpen) {
+      this.tooltipMessage = message;
+      return;
+    }
+    this.clearTooltipPulse();
+    this.tooltipMessage = message;
+    this.tooltipText.textContent = message;
+    this.tooltip.style.display = "block";
+    this.tooltip.classList.remove("kibee-tooltip--hidden");
+    this.tooltip.classList.add("kibee-tooltip--visible");
+    const hasNav = options.onPrev !== void 0 || options.onNext !== void 0;
+    this.tooltipHasNav = hasNav;
+    if (hasNav) {
+      this.navPrevBtn.onclick = options.onPrev ?? null;
+      this.navPrevBtn.style.visibility = options.onPrev ? "visible" : "hidden";
+      this.navNextBtn.onclick = options.onNext ?? null;
+      this.navNextBtn.style.visibility = options.onNext ? "visible" : "hidden";
+      this.navLabel.textContent = options.stepLabel ?? "";
+      this.tooltipNav.style.display = "flex";
+      this.tooltip.style.pointerEvents = "auto";
+    } else {
+      this.tooltipHasNav = false;
+      this.tooltipNav.style.display = "none";
+      this.tooltip.style.pointerEvents = "";
+    }
+    if (options.maxWidth) {
+      this.tooltip.style.maxWidth = `${options.maxWidth}px`;
+    }
+    if (typeof options.x === "number" && typeof options.y === "number") {
+      this.tooltip.style.left = `${options.x}px`;
+      this.tooltip.style.top = `${options.y}px`;
+      if (options.arrowEdge) {
+        this.tooltip.dataset.arrowEdge = options.arrowEdge;
+      } else {
+        this.inferTooltipArrowEdgeForPlacedTooltip(options.x);
+      }
+    } else {
+      this.positionTooltipNearBee();
+    }
+    this.startTooltipPulse();
+  }
+  hideMessage() {
+    if (!this.mounted) return;
+    this.clearTooltipPulse();
+    this.tooltipMessage = "";
+    this.tooltip.classList.remove("kibee-tooltip--visible");
+    this.tooltip.classList.add("kibee-tooltip--hidden");
+    this.tooltip.style.display = "none";
+    this.tooltip.style.pointerEvents = "";
+    this.tooltipHasNav = false;
+    this.tooltipNav.style.display = "none";
+    this.navPrevBtn.onclick = null;
+    this.navNextBtn.onclick = null;
+    delete this.tooltip.dataset.arrowEdge;
+    this.tooltipPrompt.style.display = "none";
+    this.tooltipPromptActive = false;
+    this.tooltipPromptSaveBtn.onclick = null;
+    this.tooltipPromptSkipBtn.onclick = null;
+    this.tooltipPromptInput.value = "";
+    this.tooltip.classList.remove("kibee-tooltip--prompt");
+  }
+  /**
+   * Show an inline 1-2 line prompt inside the bee's speech bubble. Used by
+   * the bookmark + issue chips to capture a short note before saving.
+   * Resolves to the user's note (trimmed) or null if they skipped / dismissed.
+   */
+  prompt(message, options = {}) {
+    if (!this.mounted) return Promise.resolve(null);
+    return new Promise((resolve) => {
+      this.speak(message, {});
+      this.clearTooltipPulse();
+      this.tooltipHasNav = true;
+      this.tooltip.style.pointerEvents = "auto";
+      this.tooltip.classList.add("kibee-tooltip--prompt");
+      this.tooltipPrompt.style.display = "flex";
+      this.tooltipPromptActive = true;
+      this.tooltipPromptInput.value = "";
+      if (options.placeholder) {
+        this.tooltipPromptInput.placeholder = options.placeholder;
+      }
+      this.updatePromptHint();
+      this.positionTooltipNearBee();
+      const finish = (note) => {
+        if (!this.tooltipPromptActive) return;
+        this.tooltipPromptActive = false;
+        this.tooltipPromptSaveBtn.onclick = null;
+        this.tooltipPromptSkipBtn.onclick = null;
+        this.tooltipPrompt.style.display = "none";
+        this.tooltipPromptInput.value = "";
+        this.tooltip.classList.remove("kibee-tooltip--prompt");
+        resolve(note);
+      };
+      this.tooltipPromptSaveBtn.onclick = () => {
+        const value = this.tooltipPromptInput.value.trim();
+        finish(value || "");
+      };
+      this.tooltipPromptSkipBtn.onclick = () => finish(null);
+      requestAnimationFrame(() => this.tooltipPromptInput.focus());
+    });
+  }
+  /** Swap the prompt's bottom-left hint between the keyboard hint (when empty)
+   *  and a tabular char counter (once the user starts typing). */
+  updatePromptHint() {
+    const len = this.tooltipPromptInput.value.length;
+    if (len === 0) {
+      this.tooltipPromptHint.innerHTML = `<kbd>\u23CE</kbd> save \xB7 <kbd>esc</kbd> skip`;
+      return;
+    }
+    const max = this.tooltipPromptMaxLen;
+    this.tooltipPromptHint.textContent = `${len} / ${max}`;
+  }
+  inferTooltipArrowEdgeForPlacedTooltip(tooltipLeft) {
+    requestAnimationFrame(() => {
+      if (!this.tooltip || this.tooltip.style.display === "none") return;
+      const tw = this.tooltip.offsetWidth || 220;
+      const midX = tooltipLeft + tw / 2;
+      this.tooltip.dataset.arrowEdge = midX >= this.currentX ? "left" : "right";
+    });
+  }
+  showActions(handler) {
+    if (!this.mounted) return;
+    this.actionHandler = handler;
+    this.positionHoverZone();
+  }
+  hideActions() {
+    if (!this.mounted) return;
+    this.clearHideButtonsTimer();
+    this.actionHandler = null;
+    this.hideRadialButtons();
+    this.positionHoverZone();
+  }
+  resize() {
+    if (!this.root) return;
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    if (this.renderingAvailable && this.renderer && this.camera) {
+      this.renderer.setSize(width, height, false);
+      this.camera.left = 0;
+      this.camera.right = width;
+      this.camera.top = 0;
+      this.camera.bottom = height;
+      this.camera.near = -1e3;
+      this.camera.far = 1e3;
+      this.camera.position.set(0, 0, 10);
+      this.camera.lookAt(0, 0, 0);
+      this.camera.updateProjectionMatrix();
+    }
+    if (this.isDockEnabled()) {
+      if (this.docked) {
+        const dock = this.getDockCenter();
+        this.currentX = dock.x;
+        this.currentY = dock.y;
+      } else if (this.hoveringHome) {
+        const wake = this.getWakeHoverPosition();
+        this.currentX = wake.x;
+        this.currentY = wake.y;
+      }
+      this.syncDockState();
+    }
+    this.updateBeeScreenPosition();
+    this.positionTooltipNearBee();
+  }
+  setDockClickBehavior(mode) {
+    this.dockClickBehavior = mode;
+    this.updateDockAria();
+    this.syncDockState();
+  }
+  destroy() {
+    this.mountPromise = null;
+    window.removeEventListener("resize", this.handleResize);
+    document.removeEventListener("visibilitychange", this.handleVisibilityChange);
+    window.removeEventListener("pointermove", this.handlePointerMove);
+    window.removeEventListener("pointerup", this.handlePointerUp);
+    window.removeEventListener("kibee-panel-open", this.handlePanelOpen);
+    window.removeEventListener("kibee-panel-close", this.handlePanelClose);
+    delete document.body.dataset.kibeeRendererActive;
+    this.clearHideButtonsTimer();
+    this.clearAutoDockTimer();
+    this.disposed = true;
+    if (this.animationFrameId !== null) {
+      cancelAnimationFrame(this.animationFrameId);
+      this.animationFrameId = null;
+    }
+    this.stopStateTweens();
+    gsap.killTweensOf(this);
+    this.dockButton?.removeEventListener("click", this.handleDockClick);
+    if (this.renderer) {
+      this.renderer.dispose();
+    }
+    this.disposeSceneObjects();
+    if (this.root?.parentNode) {
+      this.root.parentNode.removeChild(this.root);
+    }
+    this.mounted = false;
+  }
+  createRoot(container) {
+    document.querySelectorAll(".kibee-root").forEach((el) => {
+      el.remove();
+    });
+    this.root = document.createElement("div");
+    this.root.className = "kibee-root";
+    const pos = this.options.dockPosition ?? "bottom-right";
+    if (typeof pos === "object" && "inline" in pos) {
+      this.root.classList.add("kibee-root--inline");
+    }
+    this.root.style.setProperty("--kibee-dock-size", `${this.getDockSize()}px`);
+    const cssVars = this.resolveDockCSSVars();
+    this.root.style.setProperty("--kibee-dock-right", cssVars.right);
+    this.root.style.setProperty("--kibee-dock-bottom", cssVars.bottom);
+    this.root.style.setProperty("--kibee-dock-left", cssVars.left);
+    this.root.style.setProperty("--kibee-dock-top", cssVars.top);
+    this.canvasWrap = document.createElement("div");
+    this.canvasWrap.className = "kibee-canvas-wrap";
+    this.tooltip = document.createElement("div");
+    this.tooltip.className = "kibee-tooltip";
+    this.tooltip.style.display = "none";
+    const closeBtn = document.createElement("button");
+    closeBtn.type = "button";
+    closeBtn.className = "kibee-tooltip-close";
+    closeBtn.setAttribute("aria-label", "Dismiss");
+    closeBtn.innerHTML = `<svg width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden="true"><path d="M9 1 1 9M1 1l8 8" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>`;
+    closeBtn.addEventListener("click", () => {
+      this.hideMessage();
+      void this.dock();
+    });
+    this.tooltip.appendChild(closeBtn);
+    this.tooltipText = document.createElement("div");
+    this.tooltipText.className = "kibee-tooltip-body";
+    this.tooltip.appendChild(this.tooltipText);
+    this.tooltipNav = document.createElement("div");
+    this.tooltipNav.className = "kibee-tooltip-nav";
+    this.tooltipNav.style.display = "none";
+    this.navPrevBtn = document.createElement("button");
+    this.navPrevBtn.type = "button";
+    this.navPrevBtn.className = "kibee-nav-btn";
+    this.navPrevBtn.setAttribute("aria-label", "Previous step");
+    this.navPrevBtn.innerHTML = `<svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true"><path d="M8 2 4 6l4 4" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+    this.navLabel = document.createElement("span");
+    this.navLabel.className = "kibee-nav-label";
+    this.navNextBtn = document.createElement("button");
+    this.navNextBtn.type = "button";
+    this.navNextBtn.className = "kibee-nav-btn";
+    this.navNextBtn.setAttribute("aria-label", "Next step");
+    this.navNextBtn.innerHTML = `<svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true"><path d="M4 2l4 4-4 4" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+    this.tooltipNav.appendChild(this.navPrevBtn);
+    this.tooltipNav.appendChild(this.navLabel);
+    this.tooltipNav.appendChild(this.navNextBtn);
+    this.tooltip.appendChild(this.tooltipNav);
+    this.tooltipPrompt = document.createElement("div");
+    this.tooltipPrompt.className = "kibee-tooltip-prompt";
+    this.tooltipPrompt.style.display = "none";
+    this.tooltipPromptInput = document.createElement("textarea");
+    this.tooltipPromptInput.className = "kibee-tooltip-prompt-input";
+    this.tooltipPromptInput.rows = 2;
+    this.tooltipPromptInput.maxLength = this.tooltipPromptMaxLen;
+    this.tooltipPromptInput.placeholder = "One line or two\u2026";
+    this.tooltipPromptInput.spellcheck = true;
+    this.tooltipPromptInput.addEventListener("pointerdown", (e) => e.stopPropagation());
+    this.tooltipPromptInput.addEventListener("input", () => this.updatePromptHint());
+    this.tooltipPromptInput.addEventListener("keydown", (e) => {
+      e.stopPropagation();
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        this.tooltipPromptSaveBtn.click();
+      } else if (e.key === "Escape") {
+        e.preventDefault();
+        this.tooltipPromptSkipBtn.click();
+      }
+    });
+    this.tooltipPrompt.appendChild(this.tooltipPromptInput);
+    const promptRow = document.createElement("div");
+    promptRow.className = "kibee-tooltip-prompt-row";
+    this.tooltipPromptHint = document.createElement("span");
+    this.tooltipPromptHint.className = "kibee-tooltip-prompt-hint";
+    this.tooltipPromptHint.innerHTML = `<kbd>\u23CE</kbd> save \xB7 <kbd>esc</kbd> skip`;
+    promptRow.appendChild(this.tooltipPromptHint);
+    const promptActions = document.createElement("div");
+    promptActions.className = "kibee-tooltip-prompt-actions";
+    this.tooltipPromptSkipBtn = document.createElement("button");
+    this.tooltipPromptSkipBtn.type = "button";
+    this.tooltipPromptSkipBtn.className = "kibee-tooltip-prompt-skip";
+    this.tooltipPromptSkipBtn.textContent = "Skip";
+    this.tooltipPromptSkipBtn.addEventListener("click", (e) => e.stopPropagation());
+    this.tooltipPromptSkipBtn.addEventListener("pointerdown", (e) => e.stopPropagation());
+    this.tooltipPromptSaveBtn = document.createElement("button");
+    this.tooltipPromptSaveBtn.type = "button";
+    this.tooltipPromptSaveBtn.className = "kibee-tooltip-prompt-save";
+    this.tooltipPromptSaveBtn.textContent = "Save";
+    this.tooltipPromptSaveBtn.addEventListener("click", (e) => e.stopPropagation());
+    this.tooltipPromptSaveBtn.addEventListener("pointerdown", (e) => e.stopPropagation());
+    promptActions.appendChild(this.tooltipPromptSkipBtn);
+    promptActions.appendChild(this.tooltipPromptSaveBtn);
+    promptRow.appendChild(promptActions);
+    this.tooltipPrompt.appendChild(promptRow);
+    this.tooltip.appendChild(this.tooltipPrompt);
+    const radialDefs = [
+      {
+        cls: "kibee-action--honey",
+        label: "Save bookmark",
+        name: "Bookmark",
+        icon: `<svg width="17" height="17" viewBox="0 0 13 13" fill="none" aria-hidden="true">
+          <path d="M2.5 2a1 1 0 0 1 1-1h6a1 1 0 0 1 1 1v9.5l-4-2.5-4 2.5V2Z"
+                stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/>
+        </svg>`,
+        action: () => this.actionHandler?.("honey")
+      },
+      {
+        cls: "kibee-action--sting",
+        label: "Flag issue",
+        name: "Issue",
+        icon: `<svg width="17" height="17" viewBox="0 0 13 13" fill="none" aria-hidden="true">
+          <circle cx="6.5" cy="6.5" r="5.25" stroke="currentColor" stroke-width="1.4"/>
+          <path d="M6.5 4v3M6.5 9h.01" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+        </svg>`,
+        action: () => this.actionHandler?.("sting")
+      },
+      {
+        cls: "kibee-action--chat",
+        label: "Open assistant",
+        name: "Chat",
+        icon: `<svg width="17" height="17" viewBox="0 0 17 17" fill="none" aria-hidden="true">
+          <path d="M3 2.5 H14 C14.6 2.5 15 2.9 15 3.5 V10.5 C15 11.1 14.6 11.5 14 11.5
+                   H6.5 L3 14.5 V11.5 H3 C2.4 11.5 2 11.1 2 10.5 V3.5 C2 2.9 2.4 2.5 3 2.5 Z"
+                stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/>
+        </svg>`,
+        action: () => {
+          if (this.state !== "idle") return;
+          window.dispatchEvent(
+            new CustomEvent("kibee-assist-toggle", {
+              detail: { x: this.currentX, y: this.currentY }
+            })
+          );
+        }
+      },
+      {
+        cls: "kibee-action--dock",
+        label: "Set dock point here",
+        name: "Dock here",
+        icon: `<svg width="17" height="17" viewBox="0 0 17 17" fill="none" aria-hidden="true">
+          <circle cx="8.5" cy="8.5" r="3" stroke="currentColor" stroke-width="1.4"/>
+          <path d="M8.5 2v3M8.5 12v3M2 8.5h3M12 8.5h3" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/>
+        </svg>`,
+        action: () => {
+          this.setCustomDockPosition(this.currentX, this.currentY, { persist: true });
+          void this.dock();
+        }
+      }
+    ];
+    this.radialButtons = radialDefs.map((def, i) => {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = `kibee-action ${def.cls}`;
+      btn.setAttribute("aria-label", def.label);
+      btn.dataset.label = def.name;
+      btn.innerHTML = def.icon;
+      btn.style.setProperty("--i", String(i));
+      btn.style.display = "none";
+      btn.addEventListener("pointerdown", (e) => e.stopPropagation());
+      btn.addEventListener("mousedown", (e) => e.stopPropagation());
+      btn.addEventListener("click", (e) => {
+        e.stopPropagation();
+        e.preventDefault();
+        def.action();
+      });
+      btn.addEventListener("mouseenter", () => this.clearHideButtonsTimer());
+      btn.addEventListener("mouseleave", () => this.scheduleHideButtons());
+      return btn;
+    });
+    this.hoverZone = document.createElement("div");
+    this.hoverZone.className = "kibee-hover-zone";
+    this.hoverZone.addEventListener("mouseenter", this.handleBeeHoverEnter);
+    this.hoverZone.addEventListener("mouseleave", this.handleBeeHoverLeave);
+    this.hoverZone.addEventListener("pointerdown", this.handlePointerDown);
+    this.tooltip.addEventListener("mouseenter", this.handleBeeHoverEnter);
+    this.tooltip.addEventListener("mouseleave", this.handleBeeHoverLeave);
+    this.dockButton = document.createElement("button");
+    this.dockButton.type = "button";
+    this.dockButton.className = "kibee-dock";
+    this.dockButton.setAttribute("aria-label", "Wake KiBee");
+    this.dockButton.innerHTML = '<span class="kibee-dock__core" aria-hidden="true"></span><span class="kibee-dock__spark" aria-hidden="true"></span>';
+    this.dockButton.addEventListener("click", this.handleDockClick);
+    this.updateDockAria();
+    this.root.appendChild(this.canvasWrap);
+    this.root.appendChild(this.hoverZone);
+    this.root.appendChild(this.tooltip);
+    for (const btn of this.radialButtons) {
+      this.root.appendChild(btn);
+    }
+    this.root.appendChild(this.dockButton);
+    container.appendChild(this.root);
+    this.root.dataset.rendererReady = "false";
+    this.syncDockState();
+  }
+  createScene() {
+    this.scene = new THREE2.Scene();
+    this.scene.fog = new THREE2.FogExp2(16117212, 16e-4);
+  }
+  createCamera() {
+    this.camera = new THREE2.OrthographicCamera(
+      0,
+      window.innerWidth,
+      0,
+      window.innerHeight,
+      -1e3,
+      1e3
+    );
+    this.camera.position.z = 10;
+  }
+  createRenderer() {
+    try {
+      this.renderer = new THREE2.WebGLRenderer({
+        alpha: true,
+        antialias: true,
+        powerPreference: "high-performance"
+      });
+    } catch {
+      this.renderingAvailable = false;
+      return;
+    }
+    const performanceCap = this.resolvePixelRatioCap();
+    this.renderer.setPixelRatio(
+      Math.min(window.devicePixelRatio, performanceCap)
+    );
+    this.renderer.outputColorSpace = THREE2.SRGBColorSpace;
+    this.renderer.toneMapping = THREE2.ACESFilmicToneMapping;
+    this.renderer.toneMappingExposure = 2.1;
+    this.renderer.shadowMap.enabled = this.options.enableShadows ?? false;
+    this.renderer.shadowMap.type = THREE2.PCFSoftShadowMap;
+    this.renderer.domElement.className = "kibee-canvas";
+    this.canvasWrap.appendChild(this.renderer.domElement);
+    this.renderingAvailable = true;
+    this.root.dataset.rendererReady = "true";
+  }
+  createLights() {
+    const ambient = new THREE2.AmbientLight(4210752, 1.7);
+    const hemisphere = new THREE2.HemisphereLight(16249575, 11187132, 1.35);
+    const key = new THREE2.DirectionalLight(16777215, 1.8);
+    const fill = new THREE2.DirectionalLight(16777215, 1);
+    const rim = new THREE2.DirectionalLight(16773327, 0.85);
+    key.position.set(140, -180, 260);
+    fill.position.set(-140, -18, 140);
+    rim.position.set(-80, -120, 220);
+    if (this.renderer.shadowMap.enabled) {
+      [key, fill, rim].forEach((light) => {
+        light.castShadow = true;
+        light.shadow.mapSize.set(1024, 1024);
+      });
+    }
+    this.scene.add(ambient, hemisphere, key, fill, rim);
+  }
+  async loadBeeModel() {
+    try {
+      const loader = new GLTFLoader();
+      registerPbrSpecularGlossinessGLTFPlugin(loader);
+      const gltf = await loader.loadAsync(
+        this.options.assetUrl ?? "/models/bee-runtime.glb"
+      );
+      if (this.disposed) {
+        return false;
+      }
+      await applyLegacyBeeMaterialCompat(gltf);
+      const model = gltf.scene;
+      const anchor = new THREE2.Group();
+      const box = new THREE2.Box3().setFromObject(model);
+      const center = box.getCenter(new THREE2.Vector3());
+      const size = box.getSize(new THREE2.Vector3());
+      const targetHeight = this.options.assetVariant === "hero" ? 220 : 68;
+      const scale = targetHeight / Math.max(size.y, 1e-3);
+      model.position.copy(center.multiplyScalar(-1));
+      model.traverse((node) => {
+        if (!(node instanceof THREE2.Mesh)) {
+          return;
+        }
+        node.castShadow = Boolean(this.options.enableShadows);
+        node.receiveShadow = Boolean(this.options.enableShadows);
+        const materials = Array.isArray(node.material) ? node.material : [node.material];
+        for (const material of materials) {
+          if ("roughness" in material && typeof material.roughness === "number") {
+            material.roughness = Math.min(
+              1,
+              Math.max(0.2, material.roughness * 1.02)
+            );
+          }
+          if ("metalness" in material && typeof material.metalness === "number") {
+            material.metalness = Math.min(material.metalness, 0.08);
+          }
+          if ("envMapIntensity" in material) {
+            material.envMapIntensity = 1;
+          }
+          if ("map" in material && material.map instanceof THREE2.Texture) {
+            material.map.colorSpace = THREE2.SRGBColorSpace;
+          }
+          material.needsUpdate = true;
+        }
+      });
+      anchor.scale.setScalar(scale);
+      anchor.rotation.x = Math.PI;
+      anchor.add(model);
+      this.visualRig.add(anchor);
+      this.visualRig.position.set(0, -10, 0);
+      this.applyFacing("right", true);
+      if (gltf.animations.length > 0) {
+        this.mixer = new THREE2.AnimationMixer(model);
+        for (const clip of gltf.animations) {
+          this.actions.set(clip.name, this.mixer.clipAction(clip));
+        }
+      }
+      this.playClipForState("idle");
+      this.updateBeeScreenPosition();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  createFallbackBee() {
+    this.runtimeWings = null;
+    const bodyMaterial = new THREE2.MeshStandardMaterial({ color: 13867825 });
+    const stripeMaterial = new THREE2.MeshStandardMaterial({ color: 2760726 });
+    const wingMaterial = new THREE2.MeshStandardMaterial({
+      color: 13483943,
+      transparent: true,
+      opacity: 0.52
+    });
+    const body = new THREE2.Mesh(
+      new THREE2.SphereGeometry(14, 24, 24),
+      bodyMaterial
+    );
+    body.scale.set(1.2, 0.8, 0.8);
+    const stripe1 = new THREE2.Mesh(
+      new THREE2.BoxGeometry(6, 24, 16),
+      stripeMaterial
+    );
+    stripe1.position.x = -6;
+    const stripe2 = new THREE2.Mesh(
+      new THREE2.BoxGeometry(6, 24, 16),
+      stripeMaterial
+    );
+    stripe2.position.x = 6;
+    const wingL = new THREE2.Mesh(
+      new THREE2.SphereGeometry(8, 16, 16),
+      wingMaterial
+    );
+    wingL.scale.set(1.2, 0.5, 0.2);
+    wingL.position.set(-4, -12, 2);
+    wingL.rotation.z = -0.4;
+    const wingR = wingL.clone();
+    wingR.position.set(-4, 12, 2);
+    wingR.rotation.z = 0.4;
+    const head = new THREE2.Mesh(
+      new THREE2.SphereGeometry(8, 20, 20),
+      stripeMaterial
+    );
+    head.position.set(-18, 0, 0);
+    this.visualRig.add(body, stripe1, stripe2, wingL, wingR, head);
+    this.runtimeWings = {
+      left: wingL,
+      right: wingR
+    };
+    this.applyHomeFacing(true);
+    this.updateBeeScreenPosition();
+  }
+  initializeDockedHome() {
+    if (!this.isDockEnabled()) {
+      return;
+    }
+    const dock = this.getDockCenter();
+    this.currentX = dock.x;
+    this.currentY = dock.y;
+    this.docked = true;
+    this.dockVisible = true;
+    this.hoveringHome = false;
+    this.applyHomeFacing(true);
+    this.beeGroup.scale.setScalar(this.getDockedScale());
+    this.updateBeeScreenPosition();
+    this.syncDockState();
+  }
+  startRenderLoop() {
+    if (!this.renderingAvailable) {
+      return;
+    }
+    const render = () => {
+      this.animationFrameId = requestAnimationFrame(render);
+      const delta = this.clock.getDelta();
+      const t = this.clock.getElapsedTime();
+      if (this.mixer) {
+        this.mixer.update(this.reducedMotion ? delta * 0.6 : delta);
+      }
+      if (this.runtimeWings?.left && this.runtimeWings.right) {
+        const wingSpeed = this.reducedMotion ? 12 : 24;
+        const wingArc = this.reducedMotion ? 0.12 : 0.25;
+        this.runtimeWings.left.rotation.y = Math.sin(t * wingSpeed) * wingArc;
+        this.runtimeWings.right.rotation.y = -Math.sin(t * wingSpeed) * wingArc;
+      }
+      this.renderer.render(this.scene, this.camera);
+    };
+    render();
+  }
+  updateBeeScreenPosition() {
+    this.beeGroup.position.set(this.currentX, this.currentY, 0);
+    this.positionHoverZone();
+    this.publishBeePosition();
+  }
+  /**
+   * Notify any listeners (the assist panel, debugging overlays) where the
+   * bee currently sits in viewport coords. Throttled to ~60fps via the
+   * existing render loop — every callsite that moves the bee already calls
+   * updateBeeScreenPosition, so this rides along with no extra timer.
+   */
+  publishBeePosition() {
+    if (typeof window === "undefined") return;
+    window.dispatchEvent(
+      new CustomEvent("kibee-bee-move", {
+        detail: { x: this.currentX, y: this.currentY, docked: this.docked }
+      })
+    );
+  }
+  /** Public position read for callers that prefer pull over event subscription. */
+  getBeePosition() {
+    return { x: this.currentX, y: this.currentY, docked: this.docked };
+  }
+  startIdleMotion() {
+    this.playClipForState("idle");
+    const amplitude = this.docked ? 1 : this.hoveringHome ? 1.5 : 2;
+    const tilt = this.docked ? 0.01 : 0.02;
+    if (this.reducedMotion) {
+      gsap.set(this.beeGroup.position, { y: this.currentY });
+      gsap.to(this.beeGroup.rotation, {
+        z: tilt,
+        duration: 0.2,
+        ease: "sine.out",
+        overwrite: "auto"
+      });
+      return;
+    }
+    this.idleTween = gsap.to(this.beeGroup.position, {
+      y: this.currentY + amplitude,
+      duration: this.docked ? 2 : 1.8,
+      yoyo: true,
+      repeat: -1,
+      ease: "sine.inOut"
+    });
+    gsap.to(this.beeGroup.rotation, {
+      z: tilt,
+      duration: 0.6,
+      ease: "sine.inOut",
+      overwrite: "auto"
+    });
+  }
+  startThinkingMotion() {
+    this.playClipForState("thinking");
+    if (this.reducedMotion) {
+      gsap.to(this.beeGroup.rotation, {
+        z: 0.1,
+        duration: 0.2,
+        ease: "sine.out",
+        overwrite: "auto"
+      });
+      return;
+    }
+    this.idleTween = gsap.to(this.beeGroup.rotation, {
+      z: 0.18,
+      duration: 0.5,
+      yoyo: true,
+      repeat: -1,
+      ease: "sine.inOut"
+    });
+    gsap.to(this.beeGroup.position, {
+      x: this.currentX + 8,
+      duration: 0.5,
+      yoyo: true,
+      repeat: -1,
+      ease: "sine.inOut"
+    });
+  }
+  startCelebrateMotion() {
+    this.playClipForState("celebrating");
+    if (this.reducedMotion) {
+      gsap.to(this.beeGroup.rotation, {
+        z: 0.12,
+        duration: 0.18,
+        yoyo: true,
+        repeat: 1,
+        ease: "power1.out",
+        overwrite: "auto"
+      });
+      return;
+    }
+    this.celebrateTween = gsap.timeline();
+    this.celebrateTween.to(this.beeGroup.position, {
+      y: this.currentY - 18,
+      duration: 0.22,
+      ease: "power2.out"
+    }).to(this.beeGroup.rotation, {
+      z: 0.42,
+      duration: 0.18,
+      ease: "power1.out"
+    }).to(this.beeGroup.position, {
+      y: this.currentY,
+      duration: 0.28,
+      ease: "bounce.out"
+    }).to(
+      this.beeGroup.rotation,
+      {
+        z: 0,
+        duration: 0.25,
+        ease: "power1.out"
+      },
+      "<"
+    );
+  }
+  stopStateTweens() {
+    if (this.idleTween) {
+      this.idleTween.kill();
+      this.idleTween = null;
+    }
+    if (this.celebrateTween) {
+      this.celebrateTween.kill();
+      this.celebrateTween = null;
+    }
+    gsap.killTweensOf(this.beeGroup.position);
+    gsap.killTweensOf(this.beeGroup.rotation);
+    gsap.killTweensOf(this.beeGroup.scale);
+  }
+  positionTooltipNearBee() {
+    if (!this.tooltip || this.tooltip.style.display === "none") return;
+    const tw = this.tooltip.offsetWidth || 220;
+    const th = this.tooltip.offsetHeight || 70;
+    const layout = this.computeRadialLayout(tw, th);
+    this.tooltip.style.left = `${layout.tooltip.x}px`;
+    this.tooltip.style.top = `${layout.tooltip.y}px`;
+    this.tooltip.dataset.arrowEdge = layout.tooltip.arrowEdge;
+  }
+  /**
+   * Compute viewport-aware radial positions for radial action buttons and the
+   * tooltip. All returned coordinates are CSS `left`/`top` pixel values.
+   * The tooltip's `top` value is the *rendered center Y* (because CSS applies
+   * `transform: translate(0, -50%)` to the tooltip element).
+   */
+  computeRadialLayout(tooltipW, tooltipH) {
+    const bx = this.currentX;
+    const by = this.currentY;
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const RADIUS = 54;
+    const BTN = 30;
+    const MARGIN = 8;
+    const TOOLTIP_GAP = 70;
+    const ARC = 2 * Math.PI / 3;
+    const midAngle = Math.atan2(vh / 2 - by, vw / 2 - bx);
+    const n = Math.max(1, this.radialButtons.length);
+    const step = n <= 1 ? 0 : ARC / (n - 1);
+    const startAngle = midAngle - ARC / 2;
+    const angles = Array.from({ length: n }, (_, i) => startAngle + i * step);
+    const buttons = angles.map((a) => ({
+      x: Math.max(
+        MARGIN,
+        Math.min(vw - BTN - MARGIN, bx + RADIUS * Math.cos(a) - BTN / 2)
+      ),
+      y: Math.max(
+        MARGIN,
+        Math.min(vh - BTN - MARGIN, by + RADIUS * Math.sin(a) - BTN / 2)
+      )
+    }));
+    const oppAngle = midAngle + Math.PI;
+    const cos = Math.cos(oppAngle);
+    const sin = Math.sin(oppAngle);
+    let tooltipLeft;
+    let tooltipCssTop;
+    if (Math.abs(cos) >= Math.abs(sin)) {
+      tooltipLeft = cos > 0 ? bx + TOOLTIP_GAP : bx - TOOLTIP_GAP - tooltipW;
+      tooltipCssTop = by;
+    } else {
+      tooltipLeft = bx - tooltipW / 2;
+      tooltipCssTop = sin > 0 ? by + TOOLTIP_GAP + tooltipH / 2 : by - TOOLTIP_GAP - tooltipH / 2;
+    }
+    tooltipLeft = Math.max(MARGIN, Math.min(vw - tooltipW - MARGIN, tooltipLeft));
+    tooltipCssTop = Math.max(
+      MARGIN + tooltipH / 2,
+      Math.min(vh - MARGIN - tooltipH / 2, tooltipCssTop)
+    );
+    const tipTop = tooltipCssTop - tooltipH / 2;
+    const tipBottom = tooltipCssTop + tooltipH / 2;
+    const tipRight = tooltipLeft + tooltipW;
+    for (const btn of buttons) {
+      const overlapX = tooltipLeft < btn.x + BTN && tipRight > btn.x;
+      const overlapY = tipTop < btn.y + BTN && tipBottom > btn.y;
+      if (overlapX && overlapY) {
+        const nudge = BTN + MARGIN;
+        tooltipLeft = Math.max(
+          MARGIN,
+          Math.min(vw - tooltipW - MARGIN, tooltipLeft + cos * nudge)
+        );
+        tooltipCssTop = Math.max(
+          MARGIN + tooltipH / 2,
+          Math.min(
+            vh - MARGIN - tooltipH / 2,
+            tooltipCssTop + sin * nudge
+          )
+        );
+      }
+    }
+    const BEE_HW = 62;
+    const BEE_HH = 34;
+    const tipFinalTop = tooltipCssTop - tooltipH / 2;
+    const tipFinalBottom = tooltipCssTop + tooltipH / 2;
+    const tipFinalRight = tooltipLeft + tooltipW;
+    const beeLeft = bx - BEE_HW;
+    const beeRight = bx + BEE_HW;
+    const beeTop = by - BEE_HH;
+    const beeBottom = by + BEE_HH;
+    const overlapBeeX = tooltipLeft < beeRight && tipFinalRight > beeLeft;
+    const overlapBeeY = tipFinalTop < beeBottom && tipFinalBottom > beeTop;
+    if (overlapBeeX && overlapBeeY) {
+      const spaceLeft = tooltipLeft - beeLeft;
+      const spaceRight = beeRight - tipFinalRight;
+      if (cos <= 0) {
+        tooltipLeft = Math.max(MARGIN, beeLeft - tooltipW - MARGIN);
+      } else {
+        tooltipLeft = Math.min(vw - tooltipW - MARGIN, beeRight + MARGIN);
+      }
+      void spaceLeft;
+      void spaceRight;
+    }
+    const relX = tooltipLeft + tooltipW / 2 - bx;
+    const relY = tooltipCssTop - by;
+    let arrowEdge;
+    if (Math.abs(relX) >= Math.abs(relY)) {
+      arrowEdge = relX > 0 ? "left" : "right";
+    } else {
+      arrowEdge = relY > 0 ? "top" : "bottom";
+    }
+    return {
+      buttons,
+      tooltip: { x: tooltipLeft, y: tooltipCssTop, arrowEdge }
+    };
+  }
+  showRadialButtons() {
+    if (!this.radialButtons.length || this.isDragging) return;
+    const tw = this.tooltip.offsetWidth || 220;
+    const th = this.tooltip.offsetHeight || 70;
+    const layout = this.computeRadialLayout(tw, th);
+    this.radialButtons.forEach((btn, i) => {
+      const pos = layout.buttons[i];
+      if (!pos) return;
+      btn.style.left = `${pos.x}px`;
+      btn.style.top = `${pos.y}px`;
+      btn.style.display = "grid";
+      void btn.offsetWidth;
+      btn.classList.remove("kibee-action--hidden");
+      btn.classList.add("kibee-action--visible");
+    });
+    if (this.tooltip.style.display !== "none") {
+      this.tooltip.style.left = `${layout.tooltip.x}px`;
+      this.tooltip.style.top = `${layout.tooltip.y}px`;
+      this.tooltip.dataset.arrowEdge = layout.tooltip.arrowEdge;
+    }
+  }
+  hideRadialButtons() {
+    for (const btn of this.radialButtons) {
+      btn.classList.remove("kibee-action--visible");
+      btn.classList.add("kibee-action--hidden");
+    }
+    setTimeout(() => {
+      for (const btn of this.radialButtons) {
+        if (!btn.classList.contains("kibee-action--visible")) {
+          btn.style.display = "none";
+        }
+      }
+    }, 260);
+  }
+  positionHoverZone() {
+    if (!this.hoverZone) return;
+    const size = this.actionHandler ? 100 : 72;
+    this.hoverZone.style.left = `${this.currentX - size / 2}px`;
+    this.hoverZone.style.top = `${this.currentY - size / 2}px`;
+    this.hoverZone.style.width = `${size}px`;
+    this.hoverZone.style.height = `${size}px`;
+  }
+  startTooltipPulse() {
+    if (this.tooltipHasNav) return;
+    this.clearTooltipPulse();
+    this.tooltipPulseTimer = window.setTimeout(() => {
+      if (!this.tooltipMessage) return;
+      this.tooltip.classList.remove("kibee-tooltip--visible");
+      this.tooltip.classList.add("kibee-tooltip--hidden");
+    }, 3400);
+  }
+  clearTooltipPulse() {
+    if (this.tooltipPulseTimer !== null) {
+      clearTimeout(this.tooltipPulseTimer);
+      this.tooltipPulseTimer = null;
+    }
+  }
+  handleBeeHoverEnter = () => {
+    if (this.isDragging) return;
+    this.clearHideButtonsTimer();
+    if (this.tooltipMessage && !this.docked) {
+      this.tooltip.style.display = "block";
+      this.tooltip.classList.remove("kibee-tooltip--hidden");
+      this.tooltip.classList.add("kibee-tooltip--visible");
+      this.clearTooltipPulse();
+    }
+    if (this.actionHandler && this.state === "idle") {
+      this.showRadialButtons();
+    }
+  };
+  handleBeeHoverLeave = () => {
+    if (this.tooltipMessage && !this.docked) {
+      this.startTooltipPulse();
+    }
+    if (this.actionHandler) {
+      this.scheduleHideButtons();
+    }
+  };
+  scheduleHideButtons() {
+    this.clearHideButtonsTimer();
+    this.hideButtonsTimer = window.setTimeout(() => {
+      this.hideButtonsTimer = null;
+      this.hideRadialButtons();
+    }, 320);
+  }
+  clearHideButtonsTimer() {
+    if (this.hideButtonsTimer !== null) {
+      clearTimeout(this.hideButtonsTimer);
+      this.hideButtonsTimer = null;
+    }
+  }
+  // ── Drag handlers ───────────────────────────────────────────────────────
+  /** Instant undock used when the user drags the bee off the dock / launcher */
+  fastUndockForDrag() {
+    if (!this.isDockEnabled() || !this.docked) return;
+    this.docked = false;
+    this.dockVisible = false;
+    this.hoveringHome = false;
+    this.stopStateTweens();
+    gsap.killTweensOf(this);
+    gsap.killTweensOf(this.beeGroup.position);
+    gsap.killTweensOf(this.beeGroup.rotation);
+    gsap.killTweensOf(this.beeGroup.scale);
+    this.beeGroup.scale.setScalar(this.getActiveScale());
+    this.syncDockState();
+  }
+  handlePointerDown = (event) => {
+    if (event.button !== 0) return;
+    event.preventDefault();
+    this.isDragging = true;
+    this.dragMoved = false;
+    this.dragArmedFromDock = this.docked;
+    this.dragStartX = this.currentX - event.clientX;
+    this.dragStartY = this.currentY - event.clientY;
+    if (this.idleTween) {
+      this.idleTween.kill();
+      this.idleTween = null;
+    }
+    if (!this.docked) {
+      gsap.killTweensOf(this);
+      gsap.killTweensOf(this.beeGroup.position);
+      gsap.killTweensOf(this.beeGroup.rotation);
+    }
+    this.hoverZone.setPointerCapture(event.pointerId);
+    this.root.classList.add("kibee-root--dragging");
+    this.hideRadialButtons();
+  };
+  handlePointerMove = (event) => {
+    if (!this.isDragging) return;
+    const newX = event.clientX + this.dragStartX;
+    const newY = event.clientY + this.dragStartY;
+    if (this.docked) {
+      if (!this.dragMoved && (Math.abs(newX - this.currentX) > 4 || Math.abs(newY - this.currentY) > 4)) {
+        this.dragMoved = true;
+        this.fastUndockForDrag();
+      }
+      if (this.docked) return;
+    }
+    if (!this.dragMoved && (Math.abs(newX - this.currentX) > 4 || Math.abs(newY - this.currentY) > 4)) {
+      this.dragMoved = true;
+    }
+    const pad = 36;
+    this.currentX = Math.max(pad, Math.min(window.innerWidth - pad, newX));
+    this.currentY = Math.max(pad, Math.min(window.innerHeight - pad, newY));
+    this.updateBeeScreenPosition();
+    if (this.tooltipMessage && this.tooltip.style.display !== "none") {
+      this.positionTooltipNearBee();
+    }
+  };
+  handlePointerUp = (event) => {
+    if (!this.isDragging) return;
+    const armedFromDock = this.dragArmedFromDock;
+    const moved = this.dragMoved;
+    if (armedFromDock && !moved && this.docked) {
+      this.handleDockClick();
+    }
+    if (!moved && !this.docked && this.dockClickBehavior === "assist-panel" && this.state === "idle") {
+      window.dispatchEvent(
+        new CustomEvent("kibee-assist-toggle", {
+          detail: { x: this.currentX, y: this.currentY }
+        })
+      );
+    }
+    this.isDragging = false;
+    this.dragArmedFromDock = false;
+    this.hoverZone.releasePointerCapture(event.pointerId);
+    this.root.classList.remove("kibee-root--dragging");
+    if (this.state === "idle") {
+      this.startIdleMotion();
+    }
+    if (!this.docked && this.actionHandler && this.state === "idle") {
+      if (moved || !armedFromDock) {
+        this.clearHideButtonsTimer();
+        this.showRadialButtons();
+      }
+    }
+    if (!this.docked && this.tooltipMessage && this.state === "idle" && (moved || !armedFromDock)) {
+      this.tooltip.style.display = "block";
+      this.tooltip.classList.remove("kibee-tooltip--hidden");
+      this.tooltip.classList.add("kibee-tooltip--visible");
+      this.positionTooltipNearBee();
+      this.clearTooltipPulse();
+    }
+  };
+  handleResize = () => {
+    this.resize();
+  };
+  handleVisibilityChange = () => {
+    if (document.hidden) {
+      if (this.animationFrameId !== null) {
+        cancelAnimationFrame(this.animationFrameId);
+        this.animationFrameId = null;
+      }
+    } else if (this.animationFrameId === null && this.renderingAvailable) {
+      this.clock.getDelta();
+      this.startRenderLoop();
+    }
+  };
+  handlePanelOpen = (_event) => {
+    this.panelOpen = true;
+    if (this.tooltip.style.display !== "none") {
+      this.tooltip.classList.remove("kibee-tooltip--visible");
+      this.tooltip.classList.add("kibee-tooltip--hidden");
+      this.tooltip.style.display = "none";
+      this.clearTooltipPulse();
+    }
+    if (!this.docked) return;
+    requestAnimationFrame(() => {
+      if (!this.panelOpen) return;
+      const panel = document.querySelector(".kbp-panel");
+      if (!panel) return;
+      const rect = panel.getBoundingClientRect();
+      if (!rect.width) return;
+      void this.moveTo(rect.left + rect.width / 2, rect.top, {
+        offsetX: 0,
+        offsetY: 0,
+        duration: 0.55
+      });
+    });
+  };
+  handlePanelClose = () => {
+    this.panelOpen = false;
+    if (this.dockClickBehavior !== "assist-panel") {
+      void this.dock();
+    }
+  };
+  handleDockClick = () => {
+    if (document.body.dataset.kibeeEmptyDock === "true") {
+      return;
+    }
+    if (this.dockClickBehavior === "assist-panel") {
+      if (this.state !== "idle") return;
+      window.dispatchEvent(
+        new CustomEvent("kibee-assist-toggle", {
+          detail: { x: this.currentX, y: this.currentY }
+        })
+      );
+      return;
+    }
+    if (!this.docked) {
+      return;
+    }
+    this.hideMessage();
+    void this.undock({ hideDock: false }).then(() => {
+      this.speak("How can I help? Hover to bookmark or flag an issue.");
+    });
+  };
+  updateDockAria() {
+    if (!this.dockButton) {
+      return;
+    }
+    if (this.dockClickBehavior === "assist-panel") {
+      this.dockButton.setAttribute(
+        "aria-label",
+        "Open or close KiBee assistant"
+      );
+    } else {
+      this.dockButton.setAttribute("aria-label", "Wake KiBee");
+    }
+  }
+  shouldReduceMotion() {
+    if (this.options.motionMode === "reduced") {
+      return true;
+    }
+    if (this.options.motionMode === "full") {
+      return false;
+    }
+    return window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches ?? false;
+  }
+  resolvePixelRatioCap() {
+    const memoryAwareNavigator = navigator;
+    if (this.options.qualityTier === "high") {
+      return 2;
+    }
+    if (this.options.qualityTier === "low") {
+      return 1.05;
+    }
+    if (this.options.qualityTier === "balanced") {
+      return 1.45;
+    }
+    const lowCpu = navigator.hardwareConcurrency !== void 0 && navigator.hardwareConcurrency <= 4;
+    const lowMemory = memoryAwareNavigator.deviceMemory !== void 0 && memoryAwareNavigator.deviceMemory <= 4;
+    return lowCpu || lowMemory ? 1.05 : 1.45;
+  }
+  playClipForState(state) {
+    if (!this.mixer || this.actions.size === 0) {
+      return;
+    }
+    const preferredName = CLIP_BY_STATE[state];
+    const nextAction = this.actions.get(preferredName) ?? this.actions.values().next().value;
+    if (!nextAction) {
+      return;
+    }
+    const previousAction = this.activeActionName ? this.actions.get(this.activeActionName) ?? null : null;
+    if (previousAction === nextAction) {
+      nextAction.timeScale = this.getClipTimeScale(state);
+      return;
+    }
+    if (previousAction) {
+      previousAction.fadeOut(0.24);
+    }
+    nextAction.reset();
+    nextAction.enabled = true;
+    nextAction.timeScale = this.getClipTimeScale(state);
+    nextAction.clampWhenFinished = preferredName === "take_off_and_land";
+    nextAction.setLoop(
+      preferredName === "take_off_and_land" ? THREE2.LoopOnce : THREE2.LoopRepeat,
+      preferredName === "take_off_and_land" ? 1 : Infinity
+    );
+    nextAction.fadeIn(0.28).play();
+    this.activeActionName = nextAction.getClip().name;
+  }
+  getClipTimeScale(state) {
+    if (state === "guiding") {
+      return this.reducedMotion ? 0.7 : 1.12;
+    }
+    if (state === "thinking") {
+      return this.reducedMotion ? 0.5 : 0.82;
+    }
+    return this.reducedMotion ? 0.65 : 1;
+  }
+  applyFacing(facing, immediate = false) {
+    this.currentFacing = facing;
+    const targetY = facing === "right" ? -Math.PI / 1.56 : Math.PI / 1.56;
+    const tiltZ = facing === "right" ? -0.02 : 0.02;
+    if (immediate) {
+      this.visualRig.rotation.set(0.12, targetY, tiltZ);
+      return;
+    }
+    gsap.to(this.visualRig.rotation, {
+      x: 0.12,
+      y: targetY,
+      z: tiltZ,
+      duration: 0.28,
+      ease: "power2.out",
+      overwrite: "auto"
+    });
+  }
+  applyHomeFacing(immediate = false) {
+    const facesLeft = this.isDockOnRight();
+    this.currentFacing = facesLeft ? "left" : "right";
+    const yRot = facesLeft ? Math.PI / 1.6 : -Math.PI / 1.6;
+    if (immediate) {
+      this.visualRig.rotation.set(0.16, yRot, 0.12);
+      return;
+    }
+    gsap.to(this.visualRig.rotation, {
+      x: 0.16,
+      y: yRot,
+      z: 0.12,
+      duration: 0.28,
+      ease: "power2.out",
+      overwrite: "auto"
+    });
+  }
+  syncDockState() {
+    if (!this.root) {
+      return;
+    }
+    this.root.dataset.docked = String(this.docked);
+    this.root.dataset.idle = String(this.state === "idle");
+    this.root.dataset.dockVisible = String(this.dockVisible);
+    this.root.style.setProperty("--kibee-dock-size", `${this.getDockSize()}px`);
+    const cssVars = this.resolveDockCSSVars();
+    this.root.style.setProperty("--kibee-dock-right", cssVars.right);
+    this.root.style.setProperty("--kibee-dock-bottom", cssVars.bottom);
+    this.root.style.setProperty("--kibee-dock-left", cssVars.left);
+    this.root.style.setProperty("--kibee-dock-top", cssVars.top);
+    if (this.hoverZone) {
+      this.hoverZone.style.pointerEvents = "";
+    }
+    if (this.dockButton) {
+      const passThrough = this.docked && this.dockClickBehavior === "assist-panel";
+      this.dockButton.style.pointerEvents = passThrough ? "none" : "";
+    }
+  }
+  isDockEnabled() {
+    return this.options.dockEnabled ?? true;
+  }
+  setCustomDockPosition(x, y, opts = {}) {
+    const persist = opts.persist !== false && this.restorePersistedDockPosition;
+    this.customDockPos = { x, y };
+    if (persist) {
+      try {
+        localStorage.setItem("kibee:dock_pos", JSON.stringify({ x, y }));
+      } catch {
+      }
+    }
+    this.syncDockState();
+  }
+  /**
+   * Snap the docked bee and dock chrome to the current `getDockCenter()` without a full resize.
+   * Use after `setCustomDockPosition` when the dock target moves (e.g. scroll-linked layout).
+   */
+  refreshDockedBeeAfterDockMove() {
+    if (!this.isDockEnabled() || !this.docked || this.isDragging) return;
+    const dock = this.getDockCenter();
+    this.currentX = dock.x;
+    this.currentY = dock.y;
+    this.updateBeeScreenPosition();
+    this.positionTooltipNearBee();
+    this.syncDockState();
+  }
+  getDockCenter() {
+    if (this.customDockPos) {
+      return { ...this.customDockPos };
+    }
+    const size = this.getDockSize();
+    const pos = this.options.dockPosition ?? "bottom-right";
+    if (typeof pos === "string") {
+      return this.presetToCenter(pos, size);
+    }
+    if ("preset" in pos) {
+      const base = this.presetToCenter(pos.preset, size);
+      return { x: base.x + (pos.offsetX ?? 0), y: base.y + (pos.offsetY ?? 0) };
+    }
+    if ("custom" in pos) {
+      return { x: pos.custom.x, y: pos.custom.y };
+    }
+    if ("inline" in pos) {
+      return this.resolveInlineCenter(pos.inline, size);
+    }
+    return this.presetToCenter("bottom-right", size);
+  }
+  presetToCenter(preset, size) {
+    const margin = 22;
+    const padding = 24;
+    switch (preset) {
+      case "bottom-right":
+        return {
+          x: window.innerWidth - margin - size / 2,
+          y: window.innerHeight - padding - size / 2
+        };
+      case "bottom-left":
+        return {
+          x: margin + size / 2,
+          y: window.innerHeight - padding - size / 2
+        };
+      case "top-right":
+        return {
+          x: window.innerWidth - margin - size / 2,
+          y: padding + size / 2
+        };
+      case "top-left":
+        return {
+          x: margin + size / 2,
+          y: padding + size / 2
+        };
+    }
+  }
+  resolveInlineCenter(anchor, size) {
+    const el = typeof anchor.container === "string" ? document.querySelector(anchor.container) : anchor.container;
+    if (!el) return this.presetToCenter("bottom-right", size);
+    const rect = el.getBoundingClientRect();
+    const align = anchor.align ?? "center";
+    const x = align === "left" ? rect.left + size / 2 : align === "right" ? rect.right - size / 2 : rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    return { x, y };
+  }
+  /** Returns true when the dock sits on the right half of the viewport */
+  isDockOnRight() {
+    const pos = this.options.dockPosition ?? "bottom-right";
+    if (typeof pos === "string") {
+      return pos === "bottom-right" || pos === "top-right";
+    }
+    if ("preset" in pos) {
+      return pos.preset === "bottom-right" || pos.preset === "top-right";
+    }
+    return this.getDockCenter().x > window.innerWidth / 2;
+  }
+  /** Returns true when the dock sits on the bottom half of the viewport */
+  isDockOnBottom() {
+    const pos = this.options.dockPosition ?? "bottom-right";
+    if (typeof pos === "string") {
+      return pos === "bottom-right" || pos === "bottom-left";
+    }
+    if ("preset" in pos) {
+      return pos.preset === "bottom-right" || pos.preset === "bottom-left";
+    }
+    return this.getDockCenter().y > window.innerHeight / 2;
+  }
+  resolveDockCSSVars() {
+    const defaults = { right: "auto", bottom: "auto", left: "auto", top: "auto" };
+    if (this.customDockPos) {
+      const size = this.getDockSize();
+      return {
+        ...defaults,
+        left: `${this.customDockPos.x - size / 2}px`,
+        top: `${this.customDockPos.y - size / 2}px`
+      };
+    }
+    const pos = this.options.dockPosition ?? "bottom-right";
+    if (typeof pos === "string" || "preset" in pos) {
+      const preset = typeof pos === "string" ? pos : pos.preset;
+      switch (preset) {
+        case "bottom-right":
+          return { ...defaults, right: "22px", bottom: "24px" };
+        case "bottom-left":
+          return { ...defaults, left: "22px", bottom: "24px" };
+        case "top-right":
+          return { ...defaults, right: "22px", top: "24px" };
+        case "top-left":
+          return { ...defaults, left: "22px", top: "24px" };
+      }
+    }
+    if ("custom" in pos) {
+      return { ...defaults, left: `${pos.custom.x}px`, top: `${pos.custom.y}px` };
+    }
+    return defaults;
+  }
+  getWakeHoverPosition() {
+    const dock = this.getDockCenter();
+    const xDir = this.isDockOnRight() ? -1 : 1;
+    const yDir = this.isDockOnBottom() ? -1 : 1;
+    return {
+      x: dock.x + xDir * 34,
+      y: dock.y + yDir * 66
+    };
+  }
+  getDockScreenPosition() {
+    return this.getDockCenter();
+  }
+  getDockSize() {
+    return this.options.dockSize ?? 60;
+  }
+  getActiveScale() {
+    return 0.86;
+  }
+  getDockedScale() {
+    return 0.48;
+  }
+  getHomeHoverScale() {
+    return 0.68;
+  }
+  disposeSceneObjects() {
+    this.scene?.traverse((node) => {
+      if (!(node instanceof THREE2.Mesh)) {
+        return;
+      }
+      node.geometry.dispose();
+      const materials = Array.isArray(node.material) ? node.material : [node.material];
+      for (const material of materials) {
+        const textureKeys = [
+          "map",
+          "normalMap",
+          "aoMap",
+          "roughnessMap",
+          "metalnessMap",
+          "specularMap",
+          "emissiveMap"
+        ];
+        for (const key of textureKeys) {
+          const texture = material[key];
+          if (texture instanceof THREE2.Texture) {
+            texture.dispose();
+          }
+        }
+        material.dispose();
+      }
+    });
+  }
+};
+export {
+  ThreeBeeRenderer,
+  applyLegacyBeeMaterialCompat
+};