@alxxsck/ai-assistant 1.8.0 → 2.2.0

package/README.md

@@ -1,365 +1,172 @@
-# Bridge AI Chat Widget
+# Lola AI Assistant
 
-Embeddable React + TypeScript chat widget for Bridge AI agents, with:
+Embeddable browser library for the Lola assistant. The package owns its DOM host,
+Shadow DOM, chat UI, avatar, realtime transports, voice flow, and backend command
+runtime. A product frontend supplies only an authenticated interaction session and
+the few integrations that must cross into the host application.
 
-- text chat
-- optional realtime voice mode backed by the Lola Socket.IO proxy and xAI
-- optional animated 3D avatar (three.js)
-- WebSocket live message updates (AnyCable)
-- Shadow DOM isolation for host-page style safety
+## Install and build
 
-## What This Project Is
+The package requires React 19 or newer as a peer dependency.
 
-`bridgeapp-ai-chat-widget` is an ESM library bundle 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)
-- Socket.IO + AudioWorklet (realtime voice mode through Lola Backend)
-
-## 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` - Lola voice session, PCM media, and xAI realtime events
-- `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.
-Versioned `messageDelta` updates are applied by `messageId` and increasing
-`sequence`; each frame contains the current accumulated text, so duplicate or
-stale frames cannot append content twice. The UI renders every accepted frame
-immediately and animates only the newly arrived suffix. See
-[`docs/chat-streaming.ru.md`](docs/chat-streaming.ru.md) for the wire contract,
-lifecycle, rendering, and scroll behavior.
-
-### 4) Voice Domain
-
-`useVoiceStore` manages the Lola voice turn lifecycle:
-
-- creates a canonical `POST /voice/sessions` session
-- captures mono microphone input and converts it to PCM16 24 kHz in an AudioWorklet
-- connects to the authenticated `/assistant` Socket.IO namespace, activates the
-  provider session with `voice.connect`, and sends sequenced Lola protocol v4
-  `voice.audio.append` events with acknowledgements
-- plays `response.output_audio.delta` through a continuous AudioWorklet queue
-- unwraps canonical `voice.event` envelopes, renders Grok realtime transcripts,
-  and keeps avatar talking state in sync
-- creates a fresh VoiceSession after an unexpected voice socket disconnect
-- closes the session through `voice.disconnect` with the REST endpoint as a fallback
-
-### 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";
+```bash
+npm install
+npm run build-lib
 ```
 
-### `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`
+Library transport and asset origins are embedded at build time:
 
-Actual widget config
-
-- `agentId: string`
-- `customerId?: string`
-- `wsUrl: string`
-- `apiUrl: string`
-- `AIAvatar?: boolean` - is 3D avatar be used
-- `voiceEnabled?: boolean` - is voice mode enebled
-- `voiceConfig?: { voice: "ara" | "eve" | "leo" | "rex" | "sal" }` - optional xAI voice
-- `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`
+```dotenv
+VITE_LOLA_API_URL=https://api.example.test/api/v1
+VITE_LOLA_WS_URL=wss://ws.example.test/cable
+VITE_AI_ASSISTANT_ASSETS_URL=https://assets.example.test
+```
 
-### Events
+All three values are required absolute URLs. The library build fails when a value
+is missing, malformed, or uses an incompatible protocol. `VITE_*` values are
+public client configuration: never place service-account keys, access tokens, or
+other credentials in them. CI values override the placeholders in `.env`.
 
-- `avatar_ready` - emitted once avatar assets are fully loaded
-- `renew_session` - emitted when session is expired or near expiry
+## Minimal integration
 
-## Host Usage Example
+The product backend creates a Lola customer interaction session. The product
+frontend passes the short-lived result to the library:
 
 ```ts
-import { ChatWidgetInstance } from "bridgeapp-ai-chat-widget";
+import { ChatWidgetInstance } from "@alxxsck/ai-assistant";
 
 const widget = new ChatWidgetInstance({
-  mountElementId: "chat-widget-root",
-  customerInteractionSession: CustomerInteractionSession,
-  AIAvatar: true,
-  background: false,
-  voiceEnabled: true,
-  footer: false,
-  manualOpen: true,
-});
-
-widget.addEventListener("avatar_ready", () => {
-  widget.setOpen(true);
-});
-
-widget.addEventListener("renew_session", async () => {
-  const newSession = await fetchNewSessionSomehow();
-  widget.setCustomerInteractionSession(newSession);
+  customerInteractionSession: {
+    accessToken: session.accessToken,
+    interactionSessionId: session.interactionSessionId,
+    expiresAt: session.expiresAt,
+  },
 });
 ```
 
-Teardown:
+`CustomerInteractionSession` contains exactly:
 
 ```ts
-widget.destroy();
+type CustomerInteractionSession = {
+  readonly accessToken: string;
+  readonly interactionSessionId: string;
+  readonly expiresAt: string;
+};
 ```
 
-## Local Development
+Realtime settings, voice availability, provider voice selection, and project
+settings belong to Lola Backend. They are not widget constructor properties and
+must not be copied into the interaction session.
 
-Install:
+The instance creates a dedicated host below `document.body` and attaches an open
+Shadow DOM to it. Multiple instances remain isolated. Call `destroy()` to unmount
+the widget, disconnect its runtime, clear pending work, and remove the owned host.
 
-```bash
-npm install
-```
+## Lifecycle
 
-Start dev server:
+The supported instance methods are:
 
-```bash
-npm run dev
+```ts
+widget.setOpen(true);
+widget.setCustomerInteractionSession(nextSession);
+widget.destroy();
 ```
 
-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
-```
+`setOpen` may be called before asynchronous widget initialization completes; the
+latest requested state is applied when the UI is ready. Session replacement updates
+authenticated HTTP, realtime, message, voice, and command dependencies without
+recreating the public widget instance.
 
-### Build library artifacts
+The widget emits `renew_session` before expiry and after supported authentication
+failures. Refresh through the product backend and replace the session:
 
-```bash
-npm run build-lib
+```ts
+widget.addEventListener("renew_session", async () => {
+  const nextSession = await productApi.createLolaInteractionSession();
+  widget.setCustomerInteractionSession(nextSession);
+});
 ```
 
-Outputs include:
-
-- `dist/bridge-ai-chat-widget.es.js`
-- `dist/index.types.d.ts`
+The constructor and replacement method reject empty tokens, empty interaction
+session identifiers, and invalid expiry timestamps.
 
-### Publish flow
+## Launcher control
 
-- `prepublishOnly` runs `build-lib`
-- package exports are defined in `package.json` under `"exports"`
+The built-in launcher is visible by default. Products that render their own button
+can hide it while keeping the same programmatic open path:
 
-### Other project scripts
+```ts
+const widget = new ChatWidgetInstance({
+  customerInteractionSession: session,
+  hideOpenButton: true,
+});
 
-The demo app reads its service credential from
-`VITE_SERVICE_ACCOUNT_API_KEY`; credentials must not be committed to source or
-static config files.
+productButton.addEventListener("click", () => widget.setOpen(true));
+```
 
-- `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)
+Closing a hidden-launcher widget leaves it non-interactive until the product calls
+`setOpen(true)` again. The runtime and active interaction session remain mounted.
 
-## Session Handling
+## Host handlers
 
-Widget relies on `customerInteractionSession`:
+`handlers` is optional and is the only command integration surface. Use it when a
+backend command must navigate the product, open a product modal, or customize an
+element highlight:
 
-- used as Bearer token for HTTP APIs
-- used in websocket query for AnyCable auth
-- periodically checked by `useSessionExpiryChecks`
+```ts
+const widget = new ChatWidgetInstance({
+  customerInteractionSession: session,
+  handlers: {
+    openPage: ({ route }) => productRouter.push(route),
+    openModal: ({ modalName }) => productModals.open(modalName),
+    highlight: ({ element, active }) => {
+      element?.classList.toggle("lola-highlight", active);
+    },
+  },
+});
+```
 
-When session is near expiry or invalid, `renew_session` event is emitted; host app must provide a fresh session via `setCustomerInteractionSession`.
+Page and modal targets arrive in canonical Lola command envelopes. The built-in
+element fallback resolves stable `[data-lola="..."]` attributes. CTA display,
+chat open/close, speech, voice conversations, and avatar animation stay internal.
 
-## Lola Backend conversations
+Command lifecycle events are available as `command_received`,
+`command_succeeded`, `command_failed`, `command_expired`, and
+`command_unsupported`.
 
-The widget uses Lola's canonical conversation API. Interaction `chatId` remains
-the authenticated session identifier; chat history is keyed independently by
-`conversationId` (`threadId` in realtime compatibility messages).
+## Diagnostics
 
-- `GET /chat/conversations` loads the open chat list.
-- `GET /chat/conversations/:conversationId/messages` loads one history.
-- `POST /chat/conversations` creates and selects a new chat.
-- `POST /chat/conversations/:conversationId/select` selects an existing chat
-  for the current interaction session.
-- `POST /chat/messages` sends `conversationId` and adopts the canonical
-  `conversationId` returned by the backend when a chat is resolved or created.
+Set `debug: true` to enable verbose lifecycle, realtime, speech, and voice logs
+prefixed with `[Lola-Widget]`. Initialization and runtime errors remain visible
+without this flag. The option does not restore the removed debug GUI or avatar
+debug controls.
 
-A `409` response means that the selected conversation was closed. It is shown
-as a chat error and the open conversation list is refreshed; only `401`
-requests trigger interaction-session renewal.
+## Breaking migration
 
-## Lola Backend command runtime
+This release intentionally removes the former dev/demo and host-configuration
+surface. Remove these constructor properties from integrations:
 
-The widget consumes Lola Backend `command.created` envelopes from the AnyCable
-`commandCreated`/`uiCommand` frame, acknowledges `received` and a final result, and
-deduplicates `commandId` during reconnect replay. Updating the interaction session
-now reconnects REST and AnyCable without remounting the widget.
+- `mountElementId`, `agentId`, `customerId`, `configName`
+- `apiUrl`, `wsUrl`
+- `AIAvatar`, `background`, `footer`, `voiceEnabled`, `voiceConfig`, `locale`
+- `manualOpen`, `avatarDebug`, `uiTargets`, `commandHandlers`
 
-The complete frontend integration and rollout guide is available in
-[`docs/ui-actions-sdk.ru.md`](docs/ui-actions-sdk.ru.md).
+Replace `manualOpen` with `hideOpenButton: true` only when the standard launcher
+must be hidden. Remove calls to `playAnimation`, `executeReaction`,
+`sendServiceMessage`, `setLocale`, `registerUiTarget`, and
+`registerCommandHandler`. Backend commands retain the supported assistant
+behaviour internally.
 
-The previous callback fields (`url`, `target`, `commandType`,
-`targetDefinition`, and `modalId`) remain as deprecated aliases for a
-zero-downtime host migration.
+The repository ships only the library build. It no longer contains an app-mode
+HTML entry, local session creation, remote JSON widget configs, a debug GUI,
+preview/deploy demo scripts, or a Vite dev-server configuration.
 
-Canonical page routes and modal names arrive in `data.target`; the host only
-provides typed callbacks:
+## Verification
 
-```ts
-const widget = new ChatWidgetInstance({
-  // Existing widget options...
-  customerInteractionSession: {
-    accessToken,
-    chatId: sessionId,
-    sessionId,
-    expiresAt,
-  },
-  handlers: {
-    openModal: ({ modalName }) => modalRegistry.open(modalName),
-    openPage: ({ route }) => router.push(route),
-  },
-  // Temporary fallback for legacy commands without data.target.
-  uiTargets: {
-    deposit_button: {
-      kind: "button",
-      selector: '[data-lola-action="deposit"]',
-    },
-    deposit_modal: {
-      kind: "modal",
-      modalName: "deposit",
-    },
-    account_page: {
-      kind: "page",
-      route: "/account",
-      query: { source: "lola" },
-    },
-  },
-});
+```bash
+npm run typecheck
+npm test
+npm run lint
+npm run format:check
+npm run build-lib
 ```
-
-Targets and handlers can also be registered after construction with
-`registerUiTarget(code, target)` and `registerCommandHandler(name, handler)`.
-Both return an unregister callback.
-
-Built-in handlers cover assistant/chat visibility, supported avatar animations,
-CTA rendering inside the text chat, and element highlighting. Highlight targets
-fall back to `[data-lola="code"]` or `[data-lola-action="code"]`. The default
-highlight is a fixed overlay attached to `document.body`, so it is not clipped
-by an element's `overflow` or container bounds and follows resize and scroll. A registered page
-URL fallback uses `history.pushState` and emits `popstate`, so an explicitly
-configured query such as `?lola_modal=deposit` can be handled without reloading the
-host SPA. A registered modal selector can also open a native `HTMLDialogElement`.
-`data.target` is authoritative. Legacy commands without it are resolved through
-`payload.modalId`/`pageId` and `uiTargets`. If no safe handler/fallback exists, the widget sends
-`unsupported` and emits `command_unsupported`; other lifecycle events are
-`command_received`, `command_succeeded`, `command_failed`, and `command_expired`.
-
-## 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, Lola `apiUrl`, Socket.IO reachability, and backend `Project.settings.voiceEnabled`
-- Avatar never becomes ready:
-  - verify manifest URL + asset availability under static host

package/dist/App.d.ts

@@ -13,14 +13,7 @@ export type AppApi = {
     playAvatarAnimation: (name: ExternallyAvailableActions, expiresAt?: string | null) => Promise<void>;
     onSessionExpired: () => void;
     registerSetOpen: (fn: ((open: boolean) => void) | null) => void;
-    registerExecuteReaction: (fn: ((params: {
-        animation: string;
-        voice: string;
-        text: string;
-    }) => void) | null) => void;
     resolveAssetPath: (path: string) => string;
-    registerSendServiceMessage: (fn: ((message: string, animationName: ExternallyAvailableActions) => void) | null) => void;
-    registerSetLocale: (fn: ((locale: string) => void) | null) => void;
     registerSetSession: (fn: ((session: CustomerInteractionSession) => void) | null) => void;
     commandRuntime: CommandRuntime;
 };