bridgeapp-ai-chat-widget 0.1.6 → 0.2.6

package/README.md

@@ -1,47 +1,265 @@
 # Bridge AI Chat Widget
 
-Embeddable AI chat widget for web applications.
+Embeddable React + TypeScript chat widget for Bridge AI agents, with:
 
-## Installation
+- text chat
+- optional real-time voice mode (WebRTC)
+- optional animated 3D avatar (three.js)
+- WebSocket live message updates (AnyCable)
+- Shadow DOM isolation for host-page style safety
 
-```bash
-npm install bridge-ai-chat-widget
+## What This Project Is
+
+`bridgeapp-ai-chat-widget` is a library bundle (ESM + UMD) that host applications instantiate via:
+
+- `new ChatWidgetInstance(config)`
+
+The instance mounts a React app into a host element's Shadow DOM, fetches static asset mappings from a remote manifest, initializes chat/voice/avatar modules, and exposes a small integration API (`setOpen`, `destroy`, `setCustomerInteractionSession`, events).
+
+## Tech Stack
+
+- React 19
+- TypeScript
+- Vite (dev app + library build)
+- Tailwind CSS 4
+- Zustand (state stores)
+- three.js + FBX assets (avatar rendering/animation)
+- AnyCable Web client (live chat transport)
+- WebRTC + data channels (voice mode)
+
+## Repository Layout
+
+High-level structure:
+
+- `src/index.ts` - public library entry (`ChatWidgetInstance`)
+- `src/index.types.ts` - public config/types surface
+- `src/App.tsx` - provider composition root
+- `src/react/mount.tsx` - React root mount helper
+- `src/ui/components` - UI components (chat widget, routes, controls)
+- `src/domain/message` - message store + websocket channel integration
+- `src/domain/voice` - voice lifecycle + WebRTC state
+- `src/avatar` - three.js avatar scene, animation manager, blend shapes
+- `src/api` - HTTP clients for messages/voice/session-related calls
+- `src/context/ChatWidgetContext.tsx` - widget-level UI state/context
+- `src/dev` - local/dev/demo stand bootstrap (non-library integration path)
+- `src/assets` - local assets used by the widget and avatar (not used directly, rather this whole folder is getting pushed to assets repo)
+- `scripts` - utility scripts (for example asset sync to remote static repo)
+
+## Runtime Architecture
+
+### 1) Host Integration Layer
+
+`ChatWidgetInstance` (`src/index.ts`) is the host-facing API:
+
+- validates `mountElementId`
+- creates `shadowRoot` on mount element
+- injects bundled CSS into shadow root
+- fetches `${ASSETS_URL}/manifest.json`
+- resolves hashed asset paths via `resolveAssetPath(path)`
+- optionally merges remote config (`remoteConfig`)
+- mounts React app and wires `AppApi` callbacks/events
+
+### 2) React App + Providers
+
+`App` composes:
+
+- `ChatWidgetContextProvider` (widget open state, sizing, config, loading progress)
+- `CableProvider` (AnyCable websocket service + network status)
+- `HashRouter` (voice/text/list routes)
+
+### 3) Messaging Domain
+
+`useMessageStore` handles:
+
+- initial thread bootstrap (`ListMessages`, `ListMessagesForThreads`)
+- optimistic and server-driven message updates
+- thread map and per-thread message derivation
+- message send (`CreateMessage`)
+- agentic steps merge/update and rendering support
+
+Live updates arrive via AnyCable channel events and are pushed into the store.
+
+### 4) Voice Domain
+
+`useVoiceStore` manages full voice call lifecycle:
+
+- starts voice session via API (`StartVoiceSession`)
+- builds RTCPeerConnection using TURN credentials from session payload
+- sends SDP offer / receives answer
+- buffers + sends ICE candidates
+- consumes voice data channels (`voice-events`, `voice-input`)
+- streams remote audio to an `Audio` element
+- handles mic enable/disable, device switching, and teardown (`EndSession` + `EndVoiceSession`)
+
+### 5) Avatar Domain
+
+`Avatar` + `AnimationManager`:
+
+- initializes three.js renderer/camera/lights/materials
+- loads model + texture + animation assets from resolved remote paths
+- emits `loading_progress`
+- starts animation mixer loops
+- maps viseme timeline to morph target animation during speech
+- exposes external animation actions (`excited`, `fix_hair`, `spin`, `kiss`)
+
+When all assets load, widget emits `avatar_ready` through `ChatWidgetInstance`.
+
+## Public API
+
+Import:
+
+```ts
+import { ChatWidgetInstance, type WidgetConfig } from "bridgeapp-ai-chat-widget";
 ```
 
-## Usage
+### `ExternalWidgetConfig`
+
+- `mountElementId: string`
+- - `configName: string` - remote config, lives at the same place as other static assets
+- `customerInteractionSession?: { accessToken; chatId; expiresAt }` - if there's no session (separate case for dev/demo mode) - we look for customerId in remote config and create session ourselves.
+
+### `RemoteWidgetConfig`
+
+Actual widget config
+
+- `agentId: string`
+- `customerId?: string`
+- `wsUrl: string`
+- `apiUrl: string`
+- `AIAvatar?: boolean` - is 3D avatar be used
+- `voiceEnabled?: boolean` - is voice mode enebled
+- `background?: boolean` - clear or visible background
+- `footer?: boolean` - is footer rendered
+- `debug?: boolean` (avatar debug GUI)
+- `manualOpen?: boolean` - is widget trigger rendered or should it be open only programatically
+
+### Instance Methods
+
+- `setOpen(open: boolean): void` - open/close widget
+- `setCustomerInteractionSession(session): void` - update session after initialization (on session expire)
+- `playAnimation(name): void`
+- `destroy(): void`
+
+### Events
+
+- `avatar_ready` - emitted once avatar assets are fully loaded
+- `renew_session` - emitted when session is expired or near expiry
+
+## Host Usage Example
 
-```javascript
-import { ChatWidgetInstance } from "bridge-ai-chat-widget";
+```ts
+import { ChatWidgetInstance } from "bridgeapp-ai-chat-widget";
 
 const widget = new ChatWidgetInstance({
   mountElementId: "chat-widget-root",
-  agentId: "222d810a-92dd-4bb4-9ce6-1fee92238e7f",
-  customerInteractionSession: {
-    accessToken: "ACCESS_TOKEN",
-    chatId: "CHAT_ID",
-    expiresAt: new Date(Date.now() + 86400000).toISOString(),
-  },
-  assetsUrl: "https://metamediastatic.com",
-  wsUrl: "wss://ws.brid93.com/ws",
-  apiUrl: "https://api.brid93.com",
+  customerInteractionSession: CustomerInteractionSession,
   AIAvatar: true,
   background: false,
   voiceEnabled: true,
   footer: false,
-  manualOpen: false
+  manualOpen: true,
 });
 
 widget.addEventListener("avatar_ready", () => {
-  widget.setOpen(true)
+  widget.setOpen(true);
 });
 
-//this event is thrown either when session is already expired or about to be expired
-widget.addEventListener("renew_session", () => {
-  const session = //... aquire session
-  widget.setCustomerInteractionSession(session)
+widget.addEventListener("renew_session", async () => {
+  const newSession = await fetchNewSessionSomehow();
+  widget.setCustomerInteractionSession(newSession);
 });
 ```
 
-```javascript
-widget.destroy()
-```
+Teardown:
+
+```ts
+widget.destroy();
+```
+
+## Local Development
+
+Install:
+
+```bash
+npm install
+```
+
+Start dev server:
+
+```bash
+npm run dev
+```
+
+Notes:
+
+- Vite dev server runs on `5179` by default.
+- `src/dev/main.tsx` is the local bootstrap path (creates session and mounts widget directly).
+- `vite.config.ts` is for app/dev runtime.
+- `vite.config.lib.ts` is for distributable library build.
+
+## Build, Publish, and Deployment
+
+### Build local dev app
+
+```bash
+npm run build-dev
+```
+
+### Build library artifacts
+
+```bash
+npm run build-lib
+```
+
+Outputs include:
+
+- `dist/bridge-ai-chat-widget.es.js`
+- `dist/bridge-ai-chat-widget.umd.js`
+- `dist/index.types.d.ts`
+
+### Publish flow
+
+- `prepublishOnly` runs `build-lib`
+- package exports are defined in `package.json` under `"exports"`
+
+### Other project scripts
+
+- `npm run lint`
+- `npm run lint-fix`
+- `npm run format`
+- `npm run format:check`
+- deployment scripts for S3 buckets (project-specific, to be reworked)
+- `npm run push-assets-metamediastatic` (sync `src/assets` into remote static assets repo)
+
+## Session Handling
+
+Widget relies on `customerInteractionSession`:
+
+- used as Bearer token for HTTP APIs
+- used in websocket query for AnyCable auth
+- periodically checked by `useSessionExpiryChecks`
+
+When session is near expiry or invalid, `renew_session` event is emitted; host app must provide a fresh session via `setCustomerInteractionSession`.
+
+## Asset Pipeline
+
+Runtime asset resolution:
+
+1. fetch remote manifest from `https://metamediastatic.com/manifest.json`
+2. map logical path (for example `animations/idle_1.fbx`) to hashed URL
+3. load via `resolveAssetPath`
+
+This allows cache-friendly hashed asset delivery without changing code references.
+
+## Troubleshooting
+
+- Widget does not mount:
+  - verify mount element exists and `mountElementId` is correct
+- No messages or send failures:
+  - verify `apiUrl`, `accessToken`, and `chatId`
+- No live updates:
+  - verify `wsUrl`, websocket reachability, and token validity
+- Voice fails to start:
+  - verify mic permission, TURN reachability, and voice API endpoints
+- Avatar never becomes ready:
+  - verify manifest URL + asset availability under static host

package/dist/App.d.ts

@@ -1,10 +1,12 @@
-import type { WidgetConfig } from "./index.types";
-import { type OnAvatarReadyCB } from "./react/mount";
+import type { OnAvatarReady } from "./types";
+import type { WidgetConfig } from ".";
+import type { ExternallyAvailableActions } from "./avatar/Avatar";
 export type AppApi = {
-    onAvatarReady: OnAvatarReadyCB;
+    onAvatarReady: OnAvatarReady;
     onSessionExpired: () => void;
     registerSetOpen: (fn: ((open: boolean) => void) | null) => void;
     resolveAssetPath: (path: string) => string;
+    registerSendServiceMessage: ((fn: ((message: string, animationName: ExternallyAvailableActions) => void) | null) => void);
 };
 type AppProps = {
     config: WidgetConfig;

package/dist/api/messages.api.d.ts

@@ -1,6 +1,6 @@
-import type { MessageData } from "./api.types";
-import type { WidgetConfig } from "@/index.types";
+import type { MessageData } from "./messages.api.types";
 import type { AppApi } from "@/App";
+import type { WidgetConfig } from "..";
 export declare const MAX_FETCH_MESSAGES = 100;
 export type PaginationParams = {
     beforeMessageId?: string;

package/dist/api/{api.types.d.ts → messages.api.types.d.ts}

@@ -30,7 +30,7 @@ export type MessageData = {
     status: MessageStatus;
     agenticSteps: AgenticStep[];
     content: MessageContent;
-    data: {};
+    data: object;
     threadId?: string;
     threadMessagesCount: number;
     inReplyToMessageId: string | null;

package/dist/api/voice.api.d.ts

@@ -1,33 +1,7 @@
-import type { ChatParticipant } from "./api.types";
-import type { WidgetConfig } from "@/index.types";
+import type { ChatParticipant } from "./messages.api.types";
 import type { AppApi } from "@/App";
-type StartVoiceSessionResponse = {
-    status: number;
-    json: VoiceSessionData | ApiErrorResponse;
-};
-export type ApiErrorResponse = {
-    code: string;
-    message: string;
-};
-export type VoiceSessionData = {
-    session: {
-        id: string;
-        companyId: string;
-        agentId: string;
-        chatId: string;
-        participant: ChatParticipant;
-    };
-    sessionToken: string;
-    voiceProtocolVersion: number;
-    voiceBaseUrl: string;
-    voiceTurn: {
-        urls: string[];
-        username: string;
-        useSessionTokenCredential: boolean;
-        realm: string;
-        credentialExpiresAt: string;
-    };
-};
+import type { GetTurnBootstrapPayload, StartVoiceSessionResponse, VoiceSessionData, VoiceTurn } from "./voice.api.types";
+import type { WidgetConfig } from "..";
 export declare const startVoiceSession: (config: WidgetConfig, api: AppApi) => Promise<StartVoiceSessionResponse>;
 export declare function getVoiceSession(config: WidgetConfig, api: AppApi, id: string): Promise<VoiceSessionData>;
 type VoiceSessionStatus = "VOICE_SESSION_STATUS_ENDED" | "VOICE_SESSION_STATUS_ACTIVE";
@@ -87,4 +61,5 @@ type EndWebRtcSessionPayload = {
     reason?: string;
 };
 export declare function endWebRtcSession({ voiceBaseUrl, voiceSessionId, sessionToken, clientInstanceId, connectionId, connectionGeneration, reason, }: EndWebRtcSessionPayload): Promise<void>;
+export declare function getTurnBootstrap({ voiceBaseUrl, voiceSessionId, sessionToken, clientInstanceId, protocolVersion, }: GetTurnBootstrapPayload): Promise<VoiceTurn>;
 export {};

package/dist/api/voice.api.types.d.ts

@@ -0,0 +1,37 @@
+import type { ChatParticipant } from "./messages.api.types";
+export type StartVoiceSessionResponse = {
+    status: number;
+    json: VoiceSessionData | ApiErrorResponse;
+};
+export type ApiErrorResponse = {
+    code: string;
+    message: string;
+};
+export type VoiceSessionData = {
+    session: {
+        id: string;
+        companyId: string;
+        agentId: string;
+        chatId: string;
+        participant: ChatParticipant;
+    };
+    sessionToken: string;
+    voiceProtocolVersion: number;
+    voiceBaseUrl: string;
+    voiceTurn?: VoiceTurn;
+};
+export type GetTurnBootstrapPayload = {
+    voiceBaseUrl: string;
+    voiceSessionId: string;
+    sessionToken: string;
+    clientInstanceId: string;
+    protocolVersion: number;
+};
+export type VoiceTurn = {
+    urls: string[];
+    username: string;
+    credential: string;
+    credentialExpiresAt: string;
+    realm: string;
+    useSessionTokenCredential: boolean;
+};

package/dist/avatar/AnimationManager.d.ts

@@ -6,12 +6,12 @@ export type BlendShapeKey = (typeof BLEND_SHAPE_KEYS)[number];
 export default class AnimationManager {
     private model;
     private avatar;
+    activeActionName: string;
     private animations;
     private zeroMorphingInfluences;
     private visemeDataIndex;
     private visemeData;
     private mixer;
-    private activeActionName;
     private actions;
     private loadingManager;
     private fbxLoader;
@@ -24,7 +24,7 @@ export default class AnimationManager {
     private onLoadAnimation;
     private fadeDuration;
     fadeToAction(name: string): void;
-    reset(): void;
+    resetVisemeData(): void;
     setVisemeData(): void;
     convertVisemeDataToAnimationScenario(): void;
     update(delta: number, timePassed?: number): void;

package/dist/avatar/Avatar.d.ts

@@ -1,7 +1,7 @@
 import { Mesh, Vector3 } from "three";
 import { FBXLoader } from "three/examples/jsm/loaders/FBXLoader.js";
-import type { WidgetConfig } from "@/index.types";
 import type { AppApi } from "@/App";
+import type { WidgetConfig } from "..";
 export interface VisemeData {
     viseme: Viseme;
     time: number;
@@ -12,7 +12,7 @@ type CameraParams = {
     lookAt: Vector3;
     fov: number;
 };
-export type ExternallyAvailableActions = 'excited' | 'fix_hair' | 'spin' | 'kiss';
+export type ExternallyAvailableActions = "excited" | "fix_hair" | "spin" | "kiss";
 export declare class Avatar extends EventTarget {
     private canvas;
     private videoContainer;
@@ -44,6 +44,10 @@ export declare class Avatar extends EventTarget {
     private height;
     onResize: (width?: number, height?: number) => void;
     animate: () => void;
+    private SPEAKING_ANIMATION_NAME_1;
+    private SPEAKING_ANIMATION_NAME_2;
+    private IDLE_ANIMATION_NAME_1;
+    private IDLE_ANIMATION_NAME_2;
     private speakingAnimationName;
     private idleAnimationName;
     setTalking(talking: boolean): void;