@kibee/renderer-three 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -3,6 +3,7 @@ import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 
 type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
 type BeeAssetVariant = "hero" | "runtime";
+type BeeAvatarPreset = "bee" | "orb" | "ring";
 type BeeQualityTier = "auto" | "high" | "balanced" | "low";
 type BeeMotionMode = "auto" | "full" | "reduced";
 
@@ -35,6 +36,9 @@ interface DockMotionOptions {
 }
 interface ThreeBeeRendererOptions {
     assetUrl?: string;
+    /** When set, loads GLB from memory (e.g. authenticated API proxy). Takes precedence over assetUrl. */
+    assetLoadFn?: () => Promise<ArrayBuffer>;
+    avatarPreset?: BeeAvatarPreset;
     assetVariant?: BeeAssetVariant;
     qualityTier?: BeeQualityTier;
     enableShadows?: boolean;
@@ -190,6 +194,8 @@ declare class ThreeBeeRenderer implements BeeRenderer {
     private createRenderer;
     private createLights;
     private loadBeeModel;
+    private createPresetAvatar;
+    private clearVisualRig;
     private createFallbackBee;
     private initializeDockedHome;
     private startRenderLoop;
@@ -275,4 +281,88 @@ declare class ThreeBeeRenderer implements BeeRenderer {
 
 declare function applyLegacyBeeMaterialCompat(gltf: GLTF): Promise<void>;
 
-export { type BeeActionChoice, type BeeActionHandler, type BeeAssetVariant, type BeeDockClickBehavior, type BeeDockPosition, type BeeDockVariant, type BeeMotionMode, type BeeQualityTier, type BeeRenderer, type BeeVisualState, type DockMotionOptions, type MoveToOptions, type PromptOptions, type SetCustomDockPositionOptions, type SpeakOptions, ThreeBeeRenderer, type ThreeBeeRendererOptions, type TooltipArrowEdge, applyLegacyBeeMaterialCompat };
+type Motion = "breathe" | "pulse" | "spin" | "none";
+interface DomAvatarRendererOptions {
+    mode: "vector" | "lottie";
+    svg?: string;
+    assetLoadFn?: () => Promise<ArrayBuffer>;
+    motion: Motion;
+    color?: string;
+    dockSize?: number;
+    dockPosition?: {
+        right?: string;
+        bottom?: string;
+        left?: string;
+        top?: string;
+    };
+    dockClickBehavior?: BeeDockClickBehavior;
+}
+declare class DomAvatarRenderer implements BeeRenderer {
+    private opts;
+    private root;
+    private avatar;
+    private tooltip;
+    private docked;
+    private clickBehavior;
+    private lottieAnim;
+    constructor(opts: DomAvatarRendererOptions);
+    mount(container?: HTMLElement): Promise<void>;
+    private loadLottie;
+    setState(state: BeeVisualState): void;
+    moveTo(x: number, y: number, options?: MoveToOptions): Promise<void>;
+    dock(_options?: DockMotionOptions): Promise<void>;
+    undock(_options?: DockMotionOptions): Promise<void>;
+    isDocked(): boolean;
+    speak(message: string, _options?: SpeakOptions): void;
+    prompt(_message: string, _options?: PromptOptions): Promise<string | null>;
+    hideMessage(): void;
+    showActions(_handler: BeeActionHandler): void;
+    hideActions(): void;
+    resize(): void;
+    setDockClickBehavior(mode: BeeDockClickBehavior): void;
+    getDockScreenPosition(): {
+        x: number;
+        y: number;
+    };
+    getBeePosition(): {
+        x: number;
+        y: number;
+        docked: boolean;
+    };
+    destroy(): void;
+}
+
+type AvatarMotion = "breathe" | "pulse" | "spin" | "none";
+/** Mirror of the contracts WidgetAvatarConfig union (kept local to avoid a hard dep). */
+type RendererAvatarConfig = {
+    mode: "default";
+} | {
+    mode: "preset";
+    preset: "orb" | "ring";
+} | {
+    mode: "custom";
+    assetUrl: string;
+} | {
+    mode: "vector";
+    svg: string;
+    motion: AvatarMotion;
+    color?: string;
+} | {
+    mode: "lottie";
+    assetUrl: string;
+    motion: AvatarMotion;
+};
+interface CreateRendererOptions {
+    three?: Partial<ThreeBeeRendererOptions>;
+    assetLoadFn?: () => Promise<ArrayBuffer>;
+    dockSize?: number;
+    dockPosition?: {
+        right?: string;
+        bottom?: string;
+        left?: string;
+        top?: string;
+    };
+}
+declare function createRenderer(avatar: RendererAvatarConfig, opts: CreateRendererOptions): BeeRenderer;
+
+export { type BeeActionChoice, type BeeActionHandler, type BeeAssetVariant, type BeeAvatarPreset, type BeeDockClickBehavior, type BeeDockPosition, type BeeDockVariant, type BeeMotionMode, type BeeQualityTier, type BeeRenderer, type BeeVisualState, type CreateRendererOptions, type DockMotionOptions, DomAvatarRenderer, type DomAvatarRendererOptions, type MoveToOptions, type PromptOptions, type RendererAvatarConfig, type SetCustomDockPositionOptions, type SpeakOptions, ThreeBeeRenderer, type ThreeBeeRendererOptions, type TooltipArrowEdge, applyLegacyBeeMaterialCompat, createRenderer };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 
 type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
 type BeeAssetVariant = "hero" | "runtime";
+type BeeAvatarPreset = "bee" | "orb" | "ring";
 type BeeQualityTier = "auto" | "high" | "balanced" | "low";
 type BeeMotionMode = "auto" | "full" | "reduced";
 
@@ -35,6 +36,9 @@ interface DockMotionOptions {
 }
 interface ThreeBeeRendererOptions {
     assetUrl?: string;
+    /** When set, loads GLB from memory (e.g. authenticated API proxy). Takes precedence over assetUrl. */
+    assetLoadFn?: () => Promise<ArrayBuffer>;
+    avatarPreset?: BeeAvatarPreset;
     assetVariant?: BeeAssetVariant;
     qualityTier?: BeeQualityTier;
     enableShadows?: boolean;
@@ -190,6 +194,8 @@ declare class ThreeBeeRenderer implements BeeRenderer {
     private createRenderer;
     private createLights;
     private loadBeeModel;
+    private createPresetAvatar;
+    private clearVisualRig;
     private createFallbackBee;
     private initializeDockedHome;
     private startRenderLoop;
@@ -275,4 +281,88 @@ declare class ThreeBeeRenderer implements BeeRenderer {
 
 declare function applyLegacyBeeMaterialCompat(gltf: GLTF): Promise<void>;
 
-export { type BeeActionChoice, type BeeActionHandler, type BeeAssetVariant, type BeeDockClickBehavior, type BeeDockPosition, type BeeDockVariant, type BeeMotionMode, type BeeQualityTier, type BeeRenderer, type BeeVisualState, type DockMotionOptions, type MoveToOptions, type PromptOptions, type SetCustomDockPositionOptions, type SpeakOptions, ThreeBeeRenderer, type ThreeBeeRendererOptions, type TooltipArrowEdge, applyLegacyBeeMaterialCompat };
+type Motion = "breathe" | "pulse" | "spin" | "none";
+interface DomAvatarRendererOptions {
+    mode: "vector" | "lottie";
+    svg?: string;
+    assetLoadFn?: () => Promise<ArrayBuffer>;
+    motion: Motion;
+    color?: string;
+    dockSize?: number;
+    dockPosition?: {
+        right?: string;
+        bottom?: string;
+        left?: string;
+        top?: string;
+    };
+    dockClickBehavior?: BeeDockClickBehavior;
+}
+declare class DomAvatarRenderer implements BeeRenderer {
+    private opts;
+    private root;
+    private avatar;
+    private tooltip;
+    private docked;
+    private clickBehavior;
+    private lottieAnim;
+    constructor(opts: DomAvatarRendererOptions);
+    mount(container?: HTMLElement): Promise<void>;
+    private loadLottie;
+    setState(state: BeeVisualState): void;
+    moveTo(x: number, y: number, options?: MoveToOptions): Promise<void>;
+    dock(_options?: DockMotionOptions): Promise<void>;
+    undock(_options?: DockMotionOptions): Promise<void>;
+    isDocked(): boolean;
+    speak(message: string, _options?: SpeakOptions): void;
+    prompt(_message: string, _options?: PromptOptions): Promise<string | null>;
+    hideMessage(): void;
+    showActions(_handler: BeeActionHandler): void;
+    hideActions(): void;
+    resize(): void;
+    setDockClickBehavior(mode: BeeDockClickBehavior): void;
+    getDockScreenPosition(): {
+        x: number;
+        y: number;
+    };
+    getBeePosition(): {
+        x: number;
+        y: number;
+        docked: boolean;
+    };
+    destroy(): void;
+}
+
+type AvatarMotion = "breathe" | "pulse" | "spin" | "none";
+/** Mirror of the contracts WidgetAvatarConfig union (kept local to avoid a hard dep). */
+type RendererAvatarConfig = {
+    mode: "default";
+} | {
+    mode: "preset";
+    preset: "orb" | "ring";
+} | {
+    mode: "custom";
+    assetUrl: string;
+} | {
+    mode: "vector";
+    svg: string;
+    motion: AvatarMotion;
+    color?: string;
+} | {
+    mode: "lottie";
+    assetUrl: string;
+    motion: AvatarMotion;
+};
+interface CreateRendererOptions {
+    three?: Partial<ThreeBeeRendererOptions>;
+    assetLoadFn?: () => Promise<ArrayBuffer>;
+    dockSize?: number;
+    dockPosition?: {
+        right?: string;
+        bottom?: string;
+        left?: string;
+        top?: string;
+    };
+}
+declare function createRenderer(avatar: RendererAvatarConfig, opts: CreateRendererOptions): BeeRenderer;
+
+export { type BeeActionChoice, type BeeActionHandler, type BeeAssetVariant, type BeeAvatarPreset, type BeeDockClickBehavior, type BeeDockPosition, type BeeDockVariant, type BeeMotionMode, type BeeQualityTier, type BeeRenderer, type BeeVisualState, type CreateRendererOptions, type DockMotionOptions, DomAvatarRenderer, type DomAvatarRendererOptions, type MoveToOptions, type PromptOptions, type RendererAvatarConfig, type SetCustomDockPositionOptions, type SpeakOptions, ThreeBeeRenderer, type ThreeBeeRendererOptions, type TooltipArrowEdge, applyLegacyBeeMaterialCompat, createRenderer };

package/dist/index.js

@@ -30,8 +30,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DomAvatarRenderer: () => DomAvatarRenderer,
   ThreeBeeRenderer: () => ThreeBeeRenderer,
-  applyLegacyBeeMaterialCompat: () => applyLegacyBeeMaterialCompat
+  applyLegacyBeeMaterialCompat: () => applyLegacyBeeMaterialCompat,
+  createRenderer: () => createRenderer
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -959,10 +961,15 @@ var ThreeBeeRenderer = class {
     this.scene.add(ambient, hemisphere, key, fill, rim);
   }
   async loadBeeModel() {
+    const preset = this.options.avatarPreset ?? "bee";
+    if (preset === "orb" || preset === "ring") {
+      this.createPresetAvatar(preset);
+      return true;
+    }
     try {
       const loader = new import_GLTFLoader.GLTFLoader();
       registerPbrSpecularGlossinessGLTFPlugin(loader);
-      const gltf = await loader.loadAsync(
+      const gltf = this.options.assetLoadFn ? await loader.parseAsync(await this.options.assetLoadFn(), "") : await loader.loadAsync(
         this.options.assetUrl ?? "/models/bee-runtime.glb"
       );
       if (this.disposed) {
@@ -1019,9 +1026,69 @@ var ThreeBeeRenderer = class {
       this.updateBeeScreenPosition();
       return true;
     } catch {
+      if (this.options.assetLoadFn || this.options.assetUrl) {
+        this.createPresetAvatar("orb");
+        return true;
+      }
       return false;
     }
   }
+  createPresetAvatar(preset) {
+    this.runtimeWings = null;
+    this.clearVisualRig();
+    if (preset === "orb") {
+      const orbMaterial = new THREE2.MeshPhysicalMaterial({
+        color: 13228274,
+        roughness: 0.28,
+        metalness: 0.04,
+        clearcoat: 0.45,
+        emissive: 9087192,
+        emissiveIntensity: 0.18
+      });
+      const orb = new THREE2.Mesh(new THREE2.SphereGeometry(14, 32, 32), orbMaterial);
+      this.visualRig.add(orb);
+    } else {
+      const ringMaterial = new THREE2.MeshPhysicalMaterial({
+        color: 13943976,
+        transparent: true,
+        opacity: 0.72,
+        roughness: 0.12,
+        metalness: 0.02,
+        side: THREE2.DoubleSide
+      });
+      const ring = new THREE2.Mesh(new THREE2.TorusGeometry(16, 2.4, 16, 64), ringMaterial);
+      ring.rotation.x = Math.PI / 2.3;
+      const core = new THREE2.Mesh(
+        new THREE2.SphereGeometry(6, 24, 24),
+        new THREE2.MeshPhysicalMaterial({
+          color: 15787730,
+          roughness: 0.34,
+          metalness: 0.05
+        })
+      );
+      this.visualRig.add(ring, core);
+    }
+    this.applyHomeFacing(true);
+    this.updateBeeScreenPosition();
+  }
+  clearVisualRig() {
+    while (this.visualRig.children.length > 0) {
+      const child = this.visualRig.children[0];
+      this.visualRig.remove(child);
+      child.traverse((node) => {
+        if (node instanceof THREE2.Mesh) {
+          node.geometry?.dispose();
+          const materials = Array.isArray(node.material) ? node.material : [node.material];
+          for (const material of materials) {
+            material.dispose();
+          }
+        }
+      });
+    }
+    this.mixer = null;
+    this.actions.clear();
+    this.activeActionName = null;
+  }
   createFallbackBee() {
     this.runtimeWings = null;
     const bodyMaterial = new THREE2.MeshStandardMaterial({ color: 13867825 });
@@ -1906,8 +1973,188 @@ var ThreeBeeRenderer = class {
     });
   }
 };
+
+// src/dom/DomAvatarRenderer.ts
+var STATE_CLASSES = ["kibee-2d-state--guiding", "kibee-2d-state--thinking", "kibee-2d-state--celebrating"];
+var MOTION_CLASSES = ["kibee-2d-motion--breathe", "kibee-2d-motion--pulse", "kibee-2d-motion--spin"];
+var DomAvatarRenderer = class {
+  opts;
+  root = null;
+  avatar = null;
+  tooltip = null;
+  docked = true;
+  clickBehavior;
+  lottieAnim = null;
+  constructor(opts) {
+    this.opts = opts;
+    this.clickBehavior = opts.dockClickBehavior ?? "undock";
+  }
+  async mount(container) {
+    document.querySelectorAll(".kibee-root").forEach((el) => el.remove());
+    const root = document.createElement("div");
+    root.className = "kibee-root kibee-root--dom";
+    const size = this.opts.dockSize ?? 60;
+    root.style.setProperty("--kibee-dock-size", `${size}px`);
+    const pos = this.opts.dockPosition ?? { right: "24px", bottom: "24px" };
+    root.style.setProperty("--kibee-dock-right", pos.right ?? "auto");
+    root.style.setProperty("--kibee-dock-bottom", pos.bottom ?? "auto");
+    root.style.setProperty("--kibee-dock-left", pos.left ?? "auto");
+    root.style.setProperty("--kibee-dock-top", pos.top ?? "auto");
+    if (this.opts.color) root.style.setProperty("--kibee-2d-color", this.opts.color);
+    const avatar = document.createElement("div");
+    avatar.className = "kibee-2d-avatar";
+    if (this.opts.mode === "vector") avatar.innerHTML = this.opts.svg ?? "";
+    const tooltip = document.createElement("div");
+    tooltip.className = "kibee-tooltip kibee-tooltip--hidden";
+    avatar.addEventListener("click", () => {
+      if (this.clickBehavior === "assist-panel") {
+        window.dispatchEvent(new CustomEvent("kibee-assist-toggle"));
+      } else {
+        void this.undock();
+      }
+    });
+    root.appendChild(avatar);
+    root.appendChild(tooltip);
+    (container ?? document.body).appendChild(root);
+    this.root = root;
+    this.avatar = avatar;
+    this.tooltip = tooltip;
+    if (this.opts.mode === "lottie" && this.opts.assetLoadFn) await this.loadLottie(avatar);
+    this.setState("idle");
+  }
+  async loadLottie(host) {
+    try {
+      const [{ default: lottie }, buffer] = await Promise.all([
+        import("lottie-web"),
+        this.opts.assetLoadFn()
+      ]);
+      const json = JSON.parse(new TextDecoder().decode(buffer));
+      this.lottieAnim = lottie.loadAnimation({
+        container: host,
+        renderer: "svg",
+        loop: true,
+        autoplay: true,
+        animationData: json
+      });
+    } catch {
+      host.innerHTML = "<div class='kibee-2d-fallback'></div>";
+    }
+  }
+  setState(state) {
+    if (!this.avatar) return;
+    this.avatar.classList.remove(...STATE_CLASSES);
+    if (this.opts.mode === "vector") {
+      this.avatar.classList.remove(...MOTION_CLASSES);
+      if (state === "idle") {
+        if (this.opts.motion !== "none") this.avatar.classList.add(`kibee-2d-motion--${this.opts.motion}`);
+      } else {
+        this.avatar.classList.add(`kibee-2d-state--${state}`);
+      }
+    }
+  }
+  moveTo(x, y, options) {
+    if (!this.root) return Promise.resolve();
+    const dur = options?.duration ?? 550;
+    this.docked = false;
+    this.root.style.transition = `transform ${dur}ms cubic-bezier(.22,.61,.36,1)`;
+    this.root.style.transform = `translate(${x + (options?.offsetX ?? 0)}px, ${y + (options?.offsetY ?? 0)}px)`;
+    if (dur === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      const done = () => {
+        this.root?.removeEventListener("transitionend", done);
+        resolve();
+      };
+      this.root.addEventListener("transitionend", done);
+      setTimeout(done, dur + 80);
+    });
+  }
+  dock(_options) {
+    if (this.root) this.root.style.transform = "";
+    this.docked = true;
+    return Promise.resolve();
+  }
+  undock(_options) {
+    this.docked = false;
+    return Promise.resolve();
+  }
+  isDocked() {
+    return this.docked;
+  }
+  speak(message, _options) {
+    if (!this.tooltip) return;
+    this.tooltip.textContent = message;
+    this.tooltip.classList.remove("kibee-tooltip--hidden");
+    this.tooltip.classList.add("kibee-tooltip--visible");
+  }
+  prompt(_message, _options) {
+    return Promise.resolve(null);
+  }
+  hideMessage() {
+    if (!this.tooltip) return;
+    this.tooltip.classList.remove("kibee-tooltip--visible");
+    this.tooltip.classList.add("kibee-tooltip--hidden");
+  }
+  showActions(_handler) {
+  }
+  hideActions() {
+  }
+  resize() {
+  }
+  setDockClickBehavior(mode) {
+    this.clickBehavior = mode;
+  }
+  getDockScreenPosition() {
+    if (!this.root) return { x: 0, y: 0 };
+    const r = this.root.getBoundingClientRect();
+    return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+  }
+  getBeePosition() {
+    const p = this.getDockScreenPosition();
+    return { x: p.x, y: p.y, docked: this.docked };
+  }
+  destroy() {
+    this.lottieAnim?.destroy();
+    this.lottieAnim = null;
+    this.root?.remove();
+    this.root = null;
+    this.avatar = null;
+    this.tooltip = null;
+  }
+};
+
+// src/createRenderer.ts
+function createRenderer(avatar, opts) {
+  if (avatar.mode === "vector") {
+    return new DomAvatarRenderer({
+      mode: "vector",
+      svg: avatar.svg,
+      motion: avatar.motion,
+      color: avatar.color,
+      dockSize: opts.dockSize,
+      dockPosition: opts.dockPosition
+    });
+  }
+  if (avatar.mode === "lottie") {
+    return new DomAvatarRenderer({
+      mode: "lottie",
+      assetLoadFn: opts.assetLoadFn,
+      motion: avatar.motion,
+      dockSize: opts.dockSize,
+      dockPosition: opts.dockPosition
+    });
+  }
+  const three = { ...opts.three ?? {} };
+  if (avatar.mode === "preset") three.avatarPreset = avatar.preset;
+  else if (avatar.mode === "custom") {
+    if (opts.assetLoadFn) three.assetLoadFn = opts.assetLoadFn;
+    else three.assetUrl = avatar.assetUrl;
+  }
+  return new ThreeBeeRenderer(three);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DomAvatarRenderer,
   ThreeBeeRenderer,
-  applyLegacyBeeMaterialCompat
+  applyLegacyBeeMaterialCompat,
+  createRenderer
 });

package/dist/index.mjs

@@ -922,10 +922,15 @@ var ThreeBeeRenderer = class {
     this.scene.add(ambient, hemisphere, key, fill, rim);
   }
   async loadBeeModel() {
+    const preset = this.options.avatarPreset ?? "bee";
+    if (preset === "orb" || preset === "ring") {
+      this.createPresetAvatar(preset);
+      return true;
+    }
     try {
       const loader = new GLTFLoader();
       registerPbrSpecularGlossinessGLTFPlugin(loader);
-      const gltf = await loader.loadAsync(
+      const gltf = this.options.assetLoadFn ? await loader.parseAsync(await this.options.assetLoadFn(), "") : await loader.loadAsync(
         this.options.assetUrl ?? "/models/bee-runtime.glb"
       );
       if (this.disposed) {
@@ -982,9 +987,69 @@ var ThreeBeeRenderer = class {
       this.updateBeeScreenPosition();
       return true;
     } catch {
+      if (this.options.assetLoadFn || this.options.assetUrl) {
+        this.createPresetAvatar("orb");
+        return true;
+      }
       return false;
     }
   }
+  createPresetAvatar(preset) {
+    this.runtimeWings = null;
+    this.clearVisualRig();
+    if (preset === "orb") {
+      const orbMaterial = new THREE2.MeshPhysicalMaterial({
+        color: 13228274,
+        roughness: 0.28,
+        metalness: 0.04,
+        clearcoat: 0.45,
+        emissive: 9087192,
+        emissiveIntensity: 0.18
+      });
+      const orb = new THREE2.Mesh(new THREE2.SphereGeometry(14, 32, 32), orbMaterial);
+      this.visualRig.add(orb);
+    } else {
+      const ringMaterial = new THREE2.MeshPhysicalMaterial({
+        color: 13943976,
+        transparent: true,
+        opacity: 0.72,
+        roughness: 0.12,
+        metalness: 0.02,
+        side: THREE2.DoubleSide
+      });
+      const ring = new THREE2.Mesh(new THREE2.TorusGeometry(16, 2.4, 16, 64), ringMaterial);
+      ring.rotation.x = Math.PI / 2.3;
+      const core = new THREE2.Mesh(
+        new THREE2.SphereGeometry(6, 24, 24),
+        new THREE2.MeshPhysicalMaterial({
+          color: 15787730,
+          roughness: 0.34,
+          metalness: 0.05
+        })
+      );
+      this.visualRig.add(ring, core);
+    }
+    this.applyHomeFacing(true);
+    this.updateBeeScreenPosition();
+  }
+  clearVisualRig() {
+    while (this.visualRig.children.length > 0) {
+      const child = this.visualRig.children[0];
+      this.visualRig.remove(child);
+      child.traverse((node) => {
+        if (node instanceof THREE2.Mesh) {
+          node.geometry?.dispose();
+          const materials = Array.isArray(node.material) ? node.material : [node.material];
+          for (const material of materials) {
+            material.dispose();
+          }
+        }
+      });
+    }
+    this.mixer = null;
+    this.actions.clear();
+    this.activeActionName = null;
+  }
   createFallbackBee() {
     this.runtimeWings = null;
     const bodyMaterial = new THREE2.MeshStandardMaterial({ color: 13867825 });
@@ -1869,7 +1934,187 @@ var ThreeBeeRenderer = class {
     });
   }
 };
+
+// src/dom/DomAvatarRenderer.ts
+var STATE_CLASSES = ["kibee-2d-state--guiding", "kibee-2d-state--thinking", "kibee-2d-state--celebrating"];
+var MOTION_CLASSES = ["kibee-2d-motion--breathe", "kibee-2d-motion--pulse", "kibee-2d-motion--spin"];
+var DomAvatarRenderer = class {
+  opts;
+  root = null;
+  avatar = null;
+  tooltip = null;
+  docked = true;
+  clickBehavior;
+  lottieAnim = null;
+  constructor(opts) {
+    this.opts = opts;
+    this.clickBehavior = opts.dockClickBehavior ?? "undock";
+  }
+  async mount(container) {
+    document.querySelectorAll(".kibee-root").forEach((el) => el.remove());
+    const root = document.createElement("div");
+    root.className = "kibee-root kibee-root--dom";
+    const size = this.opts.dockSize ?? 60;
+    root.style.setProperty("--kibee-dock-size", `${size}px`);
+    const pos = this.opts.dockPosition ?? { right: "24px", bottom: "24px" };
+    root.style.setProperty("--kibee-dock-right", pos.right ?? "auto");
+    root.style.setProperty("--kibee-dock-bottom", pos.bottom ?? "auto");
+    root.style.setProperty("--kibee-dock-left", pos.left ?? "auto");
+    root.style.setProperty("--kibee-dock-top", pos.top ?? "auto");
+    if (this.opts.color) root.style.setProperty("--kibee-2d-color", this.opts.color);
+    const avatar = document.createElement("div");
+    avatar.className = "kibee-2d-avatar";
+    if (this.opts.mode === "vector") avatar.innerHTML = this.opts.svg ?? "";
+    const tooltip = document.createElement("div");
+    tooltip.className = "kibee-tooltip kibee-tooltip--hidden";
+    avatar.addEventListener("click", () => {
+      if (this.clickBehavior === "assist-panel") {
+        window.dispatchEvent(new CustomEvent("kibee-assist-toggle"));
+      } else {
+        void this.undock();
+      }
+    });
+    root.appendChild(avatar);
+    root.appendChild(tooltip);
+    (container ?? document.body).appendChild(root);
+    this.root = root;
+    this.avatar = avatar;
+    this.tooltip = tooltip;
+    if (this.opts.mode === "lottie" && this.opts.assetLoadFn) await this.loadLottie(avatar);
+    this.setState("idle");
+  }
+  async loadLottie(host) {
+    try {
+      const [{ default: lottie }, buffer] = await Promise.all([
+        import("lottie-web"),
+        this.opts.assetLoadFn()
+      ]);
+      const json = JSON.parse(new TextDecoder().decode(buffer));
+      this.lottieAnim = lottie.loadAnimation({
+        container: host,
+        renderer: "svg",
+        loop: true,
+        autoplay: true,
+        animationData: json
+      });
+    } catch {
+      host.innerHTML = "<div class='kibee-2d-fallback'></div>";
+    }
+  }
+  setState(state) {
+    if (!this.avatar) return;
+    this.avatar.classList.remove(...STATE_CLASSES);
+    if (this.opts.mode === "vector") {
+      this.avatar.classList.remove(...MOTION_CLASSES);
+      if (state === "idle") {
+        if (this.opts.motion !== "none") this.avatar.classList.add(`kibee-2d-motion--${this.opts.motion}`);
+      } else {
+        this.avatar.classList.add(`kibee-2d-state--${state}`);
+      }
+    }
+  }
+  moveTo(x, y, options) {
+    if (!this.root) return Promise.resolve();
+    const dur = options?.duration ?? 550;
+    this.docked = false;
+    this.root.style.transition = `transform ${dur}ms cubic-bezier(.22,.61,.36,1)`;
+    this.root.style.transform = `translate(${x + (options?.offsetX ?? 0)}px, ${y + (options?.offsetY ?? 0)}px)`;
+    if (dur === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      const done = () => {
+        this.root?.removeEventListener("transitionend", done);
+        resolve();
+      };
+      this.root.addEventListener("transitionend", done);
+      setTimeout(done, dur + 80);
+    });
+  }
+  dock(_options) {
+    if (this.root) this.root.style.transform = "";
+    this.docked = true;
+    return Promise.resolve();
+  }
+  undock(_options) {
+    this.docked = false;
+    return Promise.resolve();
+  }
+  isDocked() {
+    return this.docked;
+  }
+  speak(message, _options) {
+    if (!this.tooltip) return;
+    this.tooltip.textContent = message;
+    this.tooltip.classList.remove("kibee-tooltip--hidden");
+    this.tooltip.classList.add("kibee-tooltip--visible");
+  }
+  prompt(_message, _options) {
+    return Promise.resolve(null);
+  }
+  hideMessage() {
+    if (!this.tooltip) return;
+    this.tooltip.classList.remove("kibee-tooltip--visible");
+    this.tooltip.classList.add("kibee-tooltip--hidden");
+  }
+  showActions(_handler) {
+  }
+  hideActions() {
+  }
+  resize() {
+  }
+  setDockClickBehavior(mode) {
+    this.clickBehavior = mode;
+  }
+  getDockScreenPosition() {
+    if (!this.root) return { x: 0, y: 0 };
+    const r = this.root.getBoundingClientRect();
+    return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+  }
+  getBeePosition() {
+    const p = this.getDockScreenPosition();
+    return { x: p.x, y: p.y, docked: this.docked };
+  }
+  destroy() {
+    this.lottieAnim?.destroy();
+    this.lottieAnim = null;
+    this.root?.remove();
+    this.root = null;
+    this.avatar = null;
+    this.tooltip = null;
+  }
+};
+
+// src/createRenderer.ts
+function createRenderer(avatar, opts) {
+  if (avatar.mode === "vector") {
+    return new DomAvatarRenderer({
+      mode: "vector",
+      svg: avatar.svg,
+      motion: avatar.motion,
+      color: avatar.color,
+      dockSize: opts.dockSize,
+      dockPosition: opts.dockPosition
+    });
+  }
+  if (avatar.mode === "lottie") {
+    return new DomAvatarRenderer({
+      mode: "lottie",
+      assetLoadFn: opts.assetLoadFn,
+      motion: avatar.motion,
+      dockSize: opts.dockSize,
+      dockPosition: opts.dockPosition
+    });
+  }
+  const three = { ...opts.three ?? {} };
+  if (avatar.mode === "preset") three.avatarPreset = avatar.preset;
+  else if (avatar.mode === "custom") {
+    if (opts.assetLoadFn) three.assetLoadFn = opts.assetLoadFn;
+    else three.assetUrl = avatar.assetUrl;
+  }
+  return new ThreeBeeRenderer(three);
+}
 export {
+  DomAvatarRenderer,
   ThreeBeeRenderer,
-  applyLegacyBeeMaterialCompat
+  applyLegacyBeeMaterialCompat,
+  createRenderer
 };

package/dist/styles.css

@@ -737,3 +737,27 @@ body[data-kibee-empty-dock="true"] .kibee-root[data-docked="true"] .kibee-canvas
       0 0 24px rgba(255, 208, 0, 0.18);
   }
 }
+.kibee-root--dom .kibee-2d-avatar {
+  width: var(--kibee-dock-size, 60px);
+  height: var(--kibee-dock-size, 60px);
+  display: flex; align-items: center; justify-content: center;
+  color: var(--kibee-2d-color, currentColor); cursor: pointer;
+}
+.kibee-root--dom .kibee-2d-avatar svg { width: 100%; height: 100%; display: block; }
+
+@media (prefers-reduced-motion: reduce) {
+  .kibee-2d-avatar, .kibee-2d-avatar * { animation: none !important; }
+}
+
+.kibee-2d-motion--breathe { animation: kibee2dBreathe 3.2s ease-in-out infinite; }
+.kibee-2d-motion--pulse { animation: kibee2dPulse 1.8s ease-in-out infinite; }
+.kibee-2d-motion--spin { animation: kibee2dSpin 6s linear infinite; }
+.kibee-2d-state--guiding { animation: kibee2dGuide 0.6s ease-in-out; }
+.kibee-2d-state--thinking { animation: kibee2dPulse 0.9s ease-in-out infinite; }
+.kibee-2d-state--celebrating { animation: kibee2dBounce 0.7s ease-out; }
+
+@keyframes kibee2dBreathe { 0%,100%{transform:scale(1)} 50%{transform:scale(1.06)} }
+@keyframes kibee2dPulse { 0%,100%{opacity:1;transform:scale(1)} 50%{opacity:.78;transform:scale(1.04)} }
+@keyframes kibee2dSpin { to { transform: rotate(360deg) } }
+@keyframes kibee2dGuide { 0%{transform:rotate(0)} 30%{transform:rotate(-8deg)} 60%{transform:rotate(6deg)} 100%{transform:rotate(0)} }
+@keyframes kibee2dBounce { 0%{transform:scale(1)} 30%{transform:scale(1.18) translateY(-6px)} 60%{transform:scale(.95)} 100%{transform:scale(1)} }

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@kibee/renderer-three",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "sideEffects": ["*.css"],
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -13,13 +15,16 @@
     },
     "./styles.css": "./dist/styles.css"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.build.json && cp src/styles.css dist/styles.css",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.build.json && cat src/styles.css src/dom/domAvatarStyles.css > dist/styles.css",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
   },
   "dependencies": {
     "gsap": "^3.12.5",
+    "lottie-web": "^5.12.2",
     "three": "^0.168.0"
   },
   "peerDependencies": {
@@ -27,5 +32,8 @@
   },
   "devDependencies": {
     "tsup": "^8.5.1"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }