@kibee/contracts 0.7.0 → 0.8.0

package/dist/index.d.mts

@@ -4,13 +4,31 @@ type WidgetDockPosition = WidgetDockPreset | {
     offsetX?: number;
     offsetY?: number;
 };
-type AvatarMode = "default" | "preset" | "custom";
+type AvatarMode = "default" | "preset" | "custom" | "vector" | "lottie";
 type AvatarPresetId = "orb" | "ring";
-interface WidgetAvatarConfig {
-    mode: AvatarMode;
-    preset?: AvatarPresetId;
-    assetUrl?: string;
-}
+type AvatarMotion = "breathe" | "pulse" | "spin" | "none";
+/** Relative path — embed apps fetch via API with publishable key (bucket URLs are often private). */
+declare const WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+/** Query appended to WIDGET_AVATAR_PROXY_PATH to fetch the tenant's Lottie JSON. */
+declare const WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+type WidgetAvatarConfig = {
+    mode: "default";
+} | {
+    mode: "preset";
+    preset: AvatarPresetId;
+} | {
+    mode: "custom";
+    assetUrl: string;
+} | {
+    mode: "vector";
+    svg: string;
+    motion: AvatarMotion;
+    color?: string;
+} | {
+    mode: "lottie";
+    assetUrl: string;
+    motion: AvatarMotion;
+};
 interface WidgetConfigResponse {
     dockPosition: WidgetDockPosition;
     dockSize: number;
@@ -32,10 +50,16 @@ interface WidgetSettingsRecord {
     avatarPreset?: AvatarPresetId;
     avatarAssetUrl?: string;
     avatarAssetKey?: string;
+    avatarSvg?: string;
+    avatarColor?: string;
+    avatarLottieKey?: string;
+    avatarMotion?: AvatarMotion;
     [key: string]: unknown;
 }
 declare function isAvatarMode(value: unknown): value is AvatarMode;
 declare function isAvatarPresetId(value: unknown): value is AvatarPresetId;
+declare function isAvatarMotion(value: unknown): value is AvatarMotion;
+declare function isWidgetAvatarProxyUrl(url: string): boolean;
 declare function parseWidgetAvatar(settings: WidgetSettingsRecord): WidgetAvatarConfig;
 declare function buildWidgetConfigResponse(settings: WidgetSettingsRecord): WidgetConfigResponse;
 /** Map widget avatar config to ThreeBeeRenderer constructor options. */
@@ -43,6 +67,17 @@ declare function resolveRendererAvatarOptions(avatar: WidgetAvatarConfig): {
     avatarPreset: "bee" | AvatarPresetId;
     assetUrl?: string;
 };
+type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
+type AnimationSpec = {
+    kind: "css";
+    className: string | null;
+} | {
+    kind: "lottie";
+    segment: string;
+    loop: boolean;
+};
+/** Per-state animation descriptor consumed by DomAvatarRenderer. */
+declare function getAvatarStateAnimations(mode: "vector" | "lottie", motion: AvatarMotion): Record<BeeVisualState, AnimationSpec>;
 
 /**
  * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
@@ -844,4 +879,4 @@ declare const SLO_THRESHOLDS: {
     };
 };
 
-export { type AdminSessionSummary, type AllowedDomain, type AllowlistCheckResponse, type AnalyticsEvent, type AuditAction, type AuditEvent, type AvatarMode, type AvatarPresetId, BUDDY_TRANSITIONS, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type CandidateGroup, type CaptureStatus, type CaptureSummary, type CaptureUploadEnvelope, type CaptureUploadPayload, type CaptureUploadResponse, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DiffPreview, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FeatureFlag, type FeatureFlagOverride, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type FlowStep, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MemoryRecallItem, type MemoryRecallResponse, type MemoryScope, type MessageTemplate, type PairingState, type PromoteCandidatePayload, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type ResolvedFlagSet, SLO_THRESHOLDS, type SessionState, type SloSnapshot, type SloWindow, type StartSessionRequest, type SurfaceId, type TargetRef, type TenantAttachPayload, type TenantFlowsResponse, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, type WidgetAvatarConfig, type WidgetConfig, type WidgetConfigResponse, type WidgetDockPosition, type WidgetDockPreset, type WidgetSettingsRecord, buildWidgetConfigResponse, canTransition, isAvatarMode, isAvatarPresetId, isBridgeEnvelope, parseWidgetAvatar, resolveRendererAvatarOptions };
+export { type AdminSessionSummary, type AllowedDomain, type AllowlistCheckResponse, type AnalyticsEvent, type AnimationSpec, type AuditAction, type AuditEvent, type AvatarMode, type AvatarMotion, type AvatarPresetId, BUDDY_TRANSITIONS, type BeeVisualState, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type CandidateGroup, type CaptureStatus, type CaptureSummary, type CaptureUploadEnvelope, type CaptureUploadPayload, type CaptureUploadResponse, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DiffPreview, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FeatureFlag, type FeatureFlagOverride, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type FlowStep, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MemoryRecallItem, type MemoryRecallResponse, type MemoryScope, type MessageTemplate, type PairingState, type PromoteCandidatePayload, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type ResolvedFlagSet, SLO_THRESHOLDS, type SessionState, type SloSnapshot, type SloWindow, type StartSessionRequest, type SurfaceId, type TargetRef, type TenantAttachPayload, type TenantFlowsResponse, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, WIDGET_AVATAR_LOTTIE_PROXY_PATH, WIDGET_AVATAR_PROXY_PATH, type WidgetAvatarConfig, type WidgetConfig, type WidgetConfigResponse, type WidgetDockPosition, type WidgetDockPreset, type WidgetSettingsRecord, buildWidgetConfigResponse, canTransition, getAvatarStateAnimations, isAvatarMode, isAvatarMotion, isAvatarPresetId, isBridgeEnvelope, isWidgetAvatarProxyUrl, parseWidgetAvatar, resolveRendererAvatarOptions };

package/dist/index.d.ts

@@ -4,13 +4,31 @@ type WidgetDockPosition = WidgetDockPreset | {
     offsetX?: number;
     offsetY?: number;
 };
-type AvatarMode = "default" | "preset" | "custom";
+type AvatarMode = "default" | "preset" | "custom" | "vector" | "lottie";
 type AvatarPresetId = "orb" | "ring";
-interface WidgetAvatarConfig {
-    mode: AvatarMode;
-    preset?: AvatarPresetId;
-    assetUrl?: string;
-}
+type AvatarMotion = "breathe" | "pulse" | "spin" | "none";
+/** Relative path — embed apps fetch via API with publishable key (bucket URLs are often private). */
+declare const WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+/** Query appended to WIDGET_AVATAR_PROXY_PATH to fetch the tenant's Lottie JSON. */
+declare const WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+type WidgetAvatarConfig = {
+    mode: "default";
+} | {
+    mode: "preset";
+    preset: AvatarPresetId;
+} | {
+    mode: "custom";
+    assetUrl: string;
+} | {
+    mode: "vector";
+    svg: string;
+    motion: AvatarMotion;
+    color?: string;
+} | {
+    mode: "lottie";
+    assetUrl: string;
+    motion: AvatarMotion;
+};
 interface WidgetConfigResponse {
     dockPosition: WidgetDockPosition;
     dockSize: number;
@@ -32,10 +50,16 @@ interface WidgetSettingsRecord {
     avatarPreset?: AvatarPresetId;
     avatarAssetUrl?: string;
     avatarAssetKey?: string;
+    avatarSvg?: string;
+    avatarColor?: string;
+    avatarLottieKey?: string;
+    avatarMotion?: AvatarMotion;
     [key: string]: unknown;
 }
 declare function isAvatarMode(value: unknown): value is AvatarMode;
 declare function isAvatarPresetId(value: unknown): value is AvatarPresetId;
+declare function isAvatarMotion(value: unknown): value is AvatarMotion;
+declare function isWidgetAvatarProxyUrl(url: string): boolean;
 declare function parseWidgetAvatar(settings: WidgetSettingsRecord): WidgetAvatarConfig;
 declare function buildWidgetConfigResponse(settings: WidgetSettingsRecord): WidgetConfigResponse;
 /** Map widget avatar config to ThreeBeeRenderer constructor options. */
@@ -43,6 +67,17 @@ declare function resolveRendererAvatarOptions(avatar: WidgetAvatarConfig): {
     avatarPreset: "bee" | AvatarPresetId;
     assetUrl?: string;
 };
+type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
+type AnimationSpec = {
+    kind: "css";
+    className: string | null;
+} | {
+    kind: "lottie";
+    segment: string;
+    loop: boolean;
+};
+/** Per-state animation descriptor consumed by DomAvatarRenderer. */
+declare function getAvatarStateAnimations(mode: "vector" | "lottie", motion: AvatarMotion): Record<BeeVisualState, AnimationSpec>;
 
 /**
  * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
@@ -844,4 +879,4 @@ declare const SLO_THRESHOLDS: {
     };
 };
 
-export { type AdminSessionSummary, type AllowedDomain, type AllowlistCheckResponse, type AnalyticsEvent, type AuditAction, type AuditEvent, type AvatarMode, type AvatarPresetId, BUDDY_TRANSITIONS, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type CandidateGroup, type CaptureStatus, type CaptureSummary, type CaptureUploadEnvelope, type CaptureUploadPayload, type CaptureUploadResponse, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DiffPreview, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FeatureFlag, type FeatureFlagOverride, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type FlowStep, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MemoryRecallItem, type MemoryRecallResponse, type MemoryScope, type MessageTemplate, type PairingState, type PromoteCandidatePayload, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type ResolvedFlagSet, SLO_THRESHOLDS, type SessionState, type SloSnapshot, type SloWindow, type StartSessionRequest, type SurfaceId, type TargetRef, type TenantAttachPayload, type TenantFlowsResponse, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, type WidgetAvatarConfig, type WidgetConfig, type WidgetConfigResponse, type WidgetDockPosition, type WidgetDockPreset, type WidgetSettingsRecord, buildWidgetConfigResponse, canTransition, isAvatarMode, isAvatarPresetId, isBridgeEnvelope, parseWidgetAvatar, resolveRendererAvatarOptions };
+export { type AdminSessionSummary, type AllowedDomain, type AllowlistCheckResponse, type AnalyticsEvent, type AnimationSpec, type AuditAction, type AuditEvent, type AvatarMode, type AvatarMotion, type AvatarPresetId, BUDDY_TRANSITIONS, type BeeVisualState, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type CandidateGroup, type CaptureStatus, type CaptureSummary, type CaptureUploadEnvelope, type CaptureUploadPayload, type CaptureUploadResponse, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DiffPreview, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FeatureFlag, type FeatureFlagOverride, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type FlowStep, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MemoryRecallItem, type MemoryRecallResponse, type MemoryScope, type MessageTemplate, type PairingState, type PromoteCandidatePayload, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type ResolvedFlagSet, SLO_THRESHOLDS, type SessionState, type SloSnapshot, type SloWindow, type StartSessionRequest, type SurfaceId, type TargetRef, type TenantAttachPayload, type TenantFlowsResponse, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, WIDGET_AVATAR_LOTTIE_PROXY_PATH, WIDGET_AVATAR_PROXY_PATH, type WidgetAvatarConfig, type WidgetConfig, type WidgetConfigResponse, type WidgetDockPosition, type WidgetDockPreset, type WidgetSettingsRecord, buildWidgetConfigResponse, canTransition, getAvatarStateAnimations, isAvatarMode, isAvatarMotion, isAvatarPresetId, isBridgeEnvelope, isWidgetAvatarProxyUrl, parseWidgetAvatar, resolveRendererAvatarOptions };

package/dist/index.js

@@ -22,33 +22,65 @@ var index_exports = {};
 __export(index_exports, {
   BUDDY_TRANSITIONS: () => BUDDY_TRANSITIONS,
   SLO_THRESHOLDS: () => SLO_THRESHOLDS,
+  WIDGET_AVATAR_LOTTIE_PROXY_PATH: () => WIDGET_AVATAR_LOTTIE_PROXY_PATH,
+  WIDGET_AVATAR_PROXY_PATH: () => WIDGET_AVATAR_PROXY_PATH,
   buildWidgetConfigResponse: () => buildWidgetConfigResponse,
   canTransition: () => canTransition,
+  getAvatarStateAnimations: () => getAvatarStateAnimations,
   isAvatarMode: () => isAvatarMode,
+  isAvatarMotion: () => isAvatarMotion,
   isAvatarPresetId: () => isAvatarPresetId,
   isBridgeEnvelope: () => isBridgeEnvelope,
+  isWidgetAvatarProxyUrl: () => isWidgetAvatarProxyUrl,
   parseWidgetAvatar: () => parseWidgetAvatar,
   resolveRendererAvatarOptions: () => resolveRendererAvatarOptions
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/widget.ts
-var AVATAR_MODES = ["default", "preset", "custom"];
+var WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+var WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+var AVATAR_MODES = ["default", "preset", "custom", "vector", "lottie"];
 var AVATAR_PRESETS = ["orb", "ring"];
+var AVATAR_MOTIONS = ["breathe", "pulse", "spin", "none"];
 function isAvatarMode(value) {
   return typeof value === "string" && AVATAR_MODES.includes(value);
 }
 function isAvatarPresetId(value) {
   return typeof value === "string" && AVATAR_PRESETS.includes(value);
 }
+function isAvatarMotion(value) {
+  return typeof value === "string" && AVATAR_MOTIONS.includes(value);
+}
+function isWidgetAvatarProxyUrl(url) {
+  const trimmed = url.trim();
+  return trimmed === WIDGET_AVATAR_PROXY_PATH || trimmed.endsWith(WIDGET_AVATAR_PROXY_PATH);
+}
 function parseWidgetAvatar(settings) {
   const mode = isAvatarMode(settings.avatarMode) ? settings.avatarMode : "default";
+  const motion = isAvatarMotion(settings.avatarMotion) ? settings.avatarMotion : "breathe";
   if (mode === "preset") {
     const preset = isAvatarPresetId(settings.avatarPreset) ? settings.avatarPreset : "orb";
     return { mode, preset };
   }
-  if (mode === "custom" && typeof settings.avatarAssetUrl === "string" && settings.avatarAssetUrl.trim()) {
-    return { mode, assetUrl: settings.avatarAssetUrl.trim() };
+  if (mode === "custom") {
+    const assetKey = typeof settings.avatarAssetKey === "string" ? settings.avatarAssetKey.trim() : "";
+    if (assetKey) return { mode, assetUrl: WIDGET_AVATAR_PROXY_PATH };
+    if (typeof settings.avatarAssetUrl === "string" && settings.avatarAssetUrl.trim()) {
+      return { mode, assetUrl: settings.avatarAssetUrl.trim() };
+    }
+    return { mode: "default" };
+  }
+  if (mode === "vector") {
+    const svg = typeof settings.avatarSvg === "string" ? settings.avatarSvg.trim() : "";
+    if (!svg) return { mode: "default" };
+    const color = typeof settings.avatarColor === "string" && settings.avatarColor.trim() ? settings.avatarColor.trim() : void 0;
+    return color ? { mode, svg, motion, color } : { mode, svg, motion };
+  }
+  if (mode === "lottie") {
+    const key = typeof settings.avatarLottieKey === "string" ? settings.avatarLottieKey.trim() : "";
+    if (!key) return { mode: "default" };
+    return { mode, assetUrl: WIDGET_AVATAR_LOTTIE_PROXY_PATH, motion };
   }
   return { mode: "default" };
 }
@@ -67,14 +99,27 @@ function buildWidgetConfigResponse(settings) {
   };
 }
 function resolveRendererAvatarOptions(avatar) {
-  if (avatar.mode === "preset" && avatar.preset) {
-    return { avatarPreset: avatar.preset };
-  }
-  if (avatar.mode === "custom" && avatar.assetUrl) {
-    return { avatarPreset: "bee", assetUrl: avatar.assetUrl };
-  }
+  if (avatar.mode === "preset") return { avatarPreset: avatar.preset };
+  if (avatar.mode === "custom") return { avatarPreset: "bee", assetUrl: avatar.assetUrl };
   return { avatarPreset: "bee" };
 }
+function getAvatarStateAnimations(mode, motion) {
+  if (mode === "lottie") {
+    return {
+      idle: { kind: "lottie", segment: "idle", loop: true },
+      guiding: { kind: "lottie", segment: "idle", loop: true },
+      thinking: { kind: "lottie", segment: "thinking", loop: true },
+      celebrating: { kind: "lottie", segment: "celebrate", loop: false }
+    };
+  }
+  const idleClass = motion === "none" ? null : `kibee-2d-motion--${motion}`;
+  return {
+    idle: { kind: "css", className: idleClass },
+    guiding: { kind: "css", className: "kibee-2d-state--guiding" },
+    thinking: { kind: "css", className: "kibee-2d-state--thinking" },
+    celebrating: { kind: "css", className: "kibee-2d-state--celebrating" }
+  };
+}
 
 // src/bridge.ts
 var SURFACE_IDS = /* @__PURE__ */ new Set(["web", "extension", "desktop"]);
@@ -130,11 +175,16 @@ var SLO_THRESHOLDS = {
 0 && (module.exports = {
   BUDDY_TRANSITIONS,
   SLO_THRESHOLDS,
+  WIDGET_AVATAR_LOTTIE_PROXY_PATH,
+  WIDGET_AVATAR_PROXY_PATH,
   buildWidgetConfigResponse,
   canTransition,
+  getAvatarStateAnimations,
   isAvatarMode,
+  isAvatarMotion,
   isAvatarPresetId,
   isBridgeEnvelope,
+  isWidgetAvatarProxyUrl,
   parseWidgetAvatar,
   resolveRendererAvatarOptions
 });

package/dist/index.mjs

@@ -1,20 +1,47 @@
 // src/widget.ts
-var AVATAR_MODES = ["default", "preset", "custom"];
+var WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+var WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+var AVATAR_MODES = ["default", "preset", "custom", "vector", "lottie"];
 var AVATAR_PRESETS = ["orb", "ring"];
+var AVATAR_MOTIONS = ["breathe", "pulse", "spin", "none"];
 function isAvatarMode(value) {
   return typeof value === "string" && AVATAR_MODES.includes(value);
 }
 function isAvatarPresetId(value) {
   return typeof value === "string" && AVATAR_PRESETS.includes(value);
 }
+function isAvatarMotion(value) {
+  return typeof value === "string" && AVATAR_MOTIONS.includes(value);
+}
+function isWidgetAvatarProxyUrl(url) {
+  const trimmed = url.trim();
+  return trimmed === WIDGET_AVATAR_PROXY_PATH || trimmed.endsWith(WIDGET_AVATAR_PROXY_PATH);
+}
 function parseWidgetAvatar(settings) {
   const mode = isAvatarMode(settings.avatarMode) ? settings.avatarMode : "default";
+  const motion = isAvatarMotion(settings.avatarMotion) ? settings.avatarMotion : "breathe";
   if (mode === "preset") {
     const preset = isAvatarPresetId(settings.avatarPreset) ? settings.avatarPreset : "orb";
     return { mode, preset };
   }
-  if (mode === "custom" && typeof settings.avatarAssetUrl === "string" && settings.avatarAssetUrl.trim()) {
-    return { mode, assetUrl: settings.avatarAssetUrl.trim() };
+  if (mode === "custom") {
+    const assetKey = typeof settings.avatarAssetKey === "string" ? settings.avatarAssetKey.trim() : "";
+    if (assetKey) return { mode, assetUrl: WIDGET_AVATAR_PROXY_PATH };
+    if (typeof settings.avatarAssetUrl === "string" && settings.avatarAssetUrl.trim()) {
+      return { mode, assetUrl: settings.avatarAssetUrl.trim() };
+    }
+    return { mode: "default" };
+  }
+  if (mode === "vector") {
+    const svg = typeof settings.avatarSvg === "string" ? settings.avatarSvg.trim() : "";
+    if (!svg) return { mode: "default" };
+    const color = typeof settings.avatarColor === "string" && settings.avatarColor.trim() ? settings.avatarColor.trim() : void 0;
+    return color ? { mode, svg, motion, color } : { mode, svg, motion };
+  }
+  if (mode === "lottie") {
+    const key = typeof settings.avatarLottieKey === "string" ? settings.avatarLottieKey.trim() : "";
+    if (!key) return { mode: "default" };
+    return { mode, assetUrl: WIDGET_AVATAR_LOTTIE_PROXY_PATH, motion };
   }
   return { mode: "default" };
 }
@@ -33,14 +60,27 @@ function buildWidgetConfigResponse(settings) {
   };
 }
 function resolveRendererAvatarOptions(avatar) {
-  if (avatar.mode === "preset" && avatar.preset) {
-    return { avatarPreset: avatar.preset };
-  }
-  if (avatar.mode === "custom" && avatar.assetUrl) {
-    return { avatarPreset: "bee", assetUrl: avatar.assetUrl };
-  }
+  if (avatar.mode === "preset") return { avatarPreset: avatar.preset };
+  if (avatar.mode === "custom") return { avatarPreset: "bee", assetUrl: avatar.assetUrl };
   return { avatarPreset: "bee" };
 }
+function getAvatarStateAnimations(mode, motion) {
+  if (mode === "lottie") {
+    return {
+      idle: { kind: "lottie", segment: "idle", loop: true },
+      guiding: { kind: "lottie", segment: "idle", loop: true },
+      thinking: { kind: "lottie", segment: "thinking", loop: true },
+      celebrating: { kind: "lottie", segment: "celebrate", loop: false }
+    };
+  }
+  const idleClass = motion === "none" ? null : `kibee-2d-motion--${motion}`;
+  return {
+    idle: { kind: "css", className: idleClass },
+    guiding: { kind: "css", className: "kibee-2d-state--guiding" },
+    thinking: { kind: "css", className: "kibee-2d-state--thinking" },
+    celebrating: { kind: "css", className: "kibee-2d-state--celebrating" }
+  };
+}
 
 // src/bridge.ts
 var SURFACE_IDS = /* @__PURE__ */ new Set(["web", "extension", "desktop"]);
@@ -95,11 +135,16 @@ var SLO_THRESHOLDS = {
 export {
   BUDDY_TRANSITIONS,
   SLO_THRESHOLDS,
+  WIDGET_AVATAR_LOTTIE_PROXY_PATH,
+  WIDGET_AVATAR_PROXY_PATH,
   buildWidgetConfigResponse,
   canTransition,
+  getAvatarStateAnimations,
   isAvatarMode,
+  isAvatarMotion,
   isAvatarPresetId,
   isBridgeEnvelope,
+  isWidgetAvatarProxyUrl,
   parseWidgetAvatar,
   resolveRendererAvatarOptions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kibee/contracts",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",