@nextpa/chat-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crosslabs GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @nextpa/chat-core
+
+Framework-neutral voice & text chat engine for the NextPA platform:
+realtime voice providers (OpenAI / Google / VertexAI), text + voice conversation
+orchestration, backend API/auth client, SignalR, audio and WebRTC handling.
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `@nextpa/chat-core` | Headless engine — controllers, API client, SignalR, WebRTC, page interaction, provider registry. **No provider SDK references.** |
+| `@nextpa/chat-core/openai` | Side-effect entry: registers the OpenAI realtime provider (lazy loader — the SDK stays in its own async chunk). |
+| `@nextpa/chat-core/google` | Side-effect entry: registers both Google Live providers (`google` + `vertexai`). |
+
+Apps import the provider entries for the providers they use (the internal apps
+import both — "works with whatever the backend says"):
+
+```ts
+import '@nextpa/chat-core/openai';
+import '@nextpa/chat-core/google';
+```
+
+Provider SDKs (`@openai/agents-realtime`, `@google/genai`) are **optional peer
+dependencies** — install only what you import.
+
+## Auth
+
+`WidgetApiClient` acquires its bearer token through a pluggable `tokenProvider`:
+
+- **Default (turnkey):** pass `apiKey` — the public widget key (public by design,
+  see `.claude/docs/widget.md` § Threat Model) is exchanged for a short-lived JWT
+  via `/api/widget/authenticate`.
+- **Custom (server-minted):** pass `tokenProvider: (ctx) => Promise<WidgetTokenResult>`
+  — e.g. a partner backend that mints/exchanges the token server-side, so no
+  long-lived secret ever reaches the browser. Called with `{ baseUrl, clientId }`
+  and re-invoked automatically when the token expires.
+
+```ts
+new WidgetApiClient({ apiKey: 'npa_…' });                        // turnkey
+new WidgetApiClient({ baseUrl, tokenProvider: myBackendMint });   // partner backend
+```
+
+⚠ Never add `"sideEffects": false` to `package.json`: provider registration
+runs via side-effect modules and would be tree-shaken away
+(see the `widget-embedding` capability under `openspec/specs/`).
+
+## Targets
+
+- `nx test chat-core` — unit tests (Vitest)
+- `nx run chat-core:typecheck` — `tsc --noEmit`
+- `nx run chat-core:build` — emits ESM + `.d.ts` to `dist/` (the `exports` map
+  in `package.json` points there; not published yet — consumed via tsconfig
+  path aliases)

package/dist/constants/defaults.d.ts

@@ -0,0 +1,6 @@
+import type { WidgetConfig, WidgetDesignTokens } from '../types';
+export declare const DEFAULT_DESIGN_TOKENS: WidgetDesignTokens;
+export declare const DEFAULT_LOGO_DATA_URL: string;
+export declare let isDemoMode: boolean;
+export declare function setDemoMode(enabled: boolean): void;
+export declare function getDemoConfig(): WidgetConfig | null;

package/dist/constants/defaults.js

@@ -0,0 +1,69 @@
+export const DEFAULT_DESIGN_TOKENS = {
+    primaryColor: '#3B82F6',
+    primaryColorHover: '#2563EB',
+    textOnPrimary: '#FFFFFF',
+    secondaryColor: '#6B7280',
+    secondaryColorHover: '#4B5563',
+    textOnSecondary: '#FFFFFF',
+};
+const DEFAULT_LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 1024"><desc>Created with Fabric.js 5.3.0</desc> <defs> </defs> <g transform="matrix(4.517995572352866 0 0 4.517995572352866 639.1695563366901 511.71527645829366)" id="logo-logo" > <g style="" paint-order="stroke" > <g transform="matrix(0.28513151961095523 0 0 0.28513151961095523 35.70408416229856 -70.09827288048706)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <polygon style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(210,48,94); fill-rule: nonzero; opacity: 1;" paint-order="stroke" points="-100,-100 -100,100 100,100 " /> </g> </g> </g> <g transform="matrix(0.3655894025532038 0 0 0.3655894025532038 52.88960752035342 -52.91281898441855)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(210,48,94); fill-rule: nonzero; opacity: 1;" paint-order="stroke" transform=" translate(-125, -124.99981)" d="M 250 0 L 250 0 C 250 138.07089 138.07127 249.99962 0 249.99962 L 0 143.75606 C 76.0835 143.75606 137.76118 79.39407999999999 137.76118 0 L 137.76118 0 L 250 0 z" stroke-linecap="round" /> </g> </g> </g> <g transform="matrix(0 -0.28513151961095523 0.28513151961095523 0 -70.54771267927691 -35.72729562636363)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <polygon style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(137,33,167); fill-rule: nonzero; opacity: 1;" paint-order="stroke" points="-100,-100 -100,100 100,100 " /> </g> </g> </g> <g transform="matrix(0 -0.3655894025532038 0.3655894025532038 0 -53.36225878320852 -52.91281898441861)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(137,33,167); fill-rule: nonzero; opacity: 1;" paint-order="stroke" transform=" translate(-125, -124.99981)" d="M 250 0 L 250 0 C 250 138.07089 138.07127 249.99962 0 249.99962 L 0 143.75606 C 76.0835 143.75606 137.76118 79.39407999999999 137.76118 0 L 137.76118 0 L 250 0 z" stroke-linecap="round" /> </g> </g> </g> <g transform="matrix(-0.28513151961095523 0 0 -0.28513151961095523 -35.70408416229856 70.09827288048706)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <polygon style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(237,108,45); fill-rule: nonzero; opacity: 1;" paint-order="stroke" points="-100,-100 -100,100 100,100 " /> </g> </g> </g> <g transform="matrix(-0.3655894025532038 0 0 -0.3655894025532038 -52.88960752035342 52.91281898441855)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(237,108,45); fill-rule: nonzero; opacity: 1;" paint-order="stroke" transform=" translate(-125, -124.99981)" d="M 250 0 L 250 0 C 250 138.07089 138.07127 249.99962 0 249.99962 L 0 143.75606 C 76.0835 143.75606 137.76118 79.39407999999999 137.76118 0 L 137.76118 0 L 250 0 z" stroke-linecap="round" /> </g> </g> </g> <g transform="matrix(0 0.28513151961095523 -0.28513151961095523 0 70.54771267927697 35.727295626363684)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <polygon style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(243,177,62); fill-rule: nonzero; opacity: 1;" paint-order="stroke" points="-100,-100 -100,100 100,100 " /> </g> </g> </g> <g transform="matrix(0 0.3655894025532038 -0.3655894025532038 0 53.36225878320852 52.91281898441861)" > <g style="" paint-order="stroke" > <g transform="matrix(1 0 0 1 0 0)" > <path style="stroke: none; stroke-width: 1; stroke-dasharray: none; stroke-linecap: butt; stroke-dashoffset: 0; stroke-linejoin: miter; stroke-miterlimit: 4; fill: rgb(243,177,62); fill-rule: nonzero; opacity: 1;" paint-order="stroke" transform=" translate(-125, -124.99981)" d="M 250 0 L 250 0 C 250 138.07089 138.07127 249.99962 0 249.99962 L 0 143.75606 C 76.0835 143.75606 137.76118 79.39407999999999 137.76118 0 L 137.76118 0 L 250 0 z" stroke-linecap="round" /> </g> </g> </g> </g> </g></svg>`;
+export const DEFAULT_LOGO_DATA_URL = `data:image/svg+xml;base64,${btoa(DEFAULT_LOGO_SVG)}`;
+// Demo mode is off by default; the host app opts in at bootstrap (e.g. the
+// widget's dev page via VITE_DEMO_MODE). Exported as a live binding so engine
+// modules that imported it before setDemoMode() ran still see the update.
+export let isDemoMode = false;
+export function setDemoMode(enabled) {
+    isDemoMode = enabled;
+}
+function createDemoConfig() {
+    if (!isDemoMode) {
+        return null;
+    }
+    return {
+        assistantId: '00000000-0000-0000-0000-000000000000',
+        tenantId: '00000000-0000-0000-0000-000000000000',
+        name: 'Demo Assistant',
+        welcomeMessage: 'Hallo! Ich bin ein Demo-Assistent. Wie kann ich Ihnen helfen?',
+        logoUrl: DEFAULT_LOGO_DATA_URL,
+        theme: 'dark',
+        size: 'compact',
+        placement: 'bottom-right',
+        largeTeaserText: 'Sprechen Sie mich einfach an.',
+        largeCtaText: 'Chat starten',
+        inputPlaceholder: 'Nachricht eingeben...',
+        startButtonText: 'Chat starten',
+        connectingText: 'Verbinde...',
+        listeningText: 'Ich höre zu..',
+        preparingText: 'Einen Moment bitte...',
+        sendButtonText: 'Senden',
+        disconnectText: 'Gespräch beenden',
+        mutedText: 'Stummgeschaltet',
+        unmuteText: 'Stummschaltung aufheben',
+        minimizeText: 'Minimieren',
+        resetText: 'Gespräch zurücksetzen',
+        resetConfirmText: 'Gespräch zurücksetzen? Der Assistent wird sich nicht mehr an vorherige Unterhaltungen erinnern.',
+        resetConfirmButtonText: 'Zurücksetzen',
+        resetCancelButtonText: 'Abbrechen',
+        errorText: 'Es ist ein Fehler aufgetreten. Bitte versuchen Sie es später erneut.',
+        microphoneBlockedText: 'Mikrofonzugriff blockiert',
+        microphoneBlockedHintText: 'Bitte erlauben Sie den Mikrofonzugriff in Ihren Browser-Einstellungen (Klick auf das Schloss-Symbol in der Adressleiste) und versuchen Sie es erneut.',
+        voiceButtonText: 'Sprachassistent starten',
+        textButtonText: 'Text-Chat starten',
+        copyText: 'Kopieren',
+        copiedText: 'Kopiert!',
+        textChatFallbackText: 'Als Text-Chat fortfahren',
+        designTokens: DEFAULT_DESIGN_TOKENS,
+        popoverEnabled: true,
+        greetingEnabled: true,
+        popoverAutoCloseSeconds: 5,
+        popoverText: 'Haben Sie Fragen? Ich helfe Ihnen gerne!',
+        language: 'de',
+    };
+}
+// Computed lazily: setDemoMode() runs at host bootstrap, after this module
+// initialised — a module-init const would be pinned to the default (off).
+let demoConfig;
+export function getDemoConfig() {
+    demoConfig ??= createDemoConfig();
+    return demoConfig;
+}

package/dist/core/chat-manager.d.ts

@@ -0,0 +1,17 @@
+import type { ChatMessage, FeedbackRating } from '../types';
+import { EventEmitter } from './event-emitter';
+interface ChatEvents {
+    messageAdded: (message: ChatMessage) => void;
+    messagesCleared: () => void;
+    feedbackChanged: (messageId: string, rating: FeedbackRating | undefined) => void;
+}
+export declare class ChatManager extends EventEmitter<ChatEvents> {
+    private messages;
+    addMessage(role: 'user' | 'assistant', content: string, id?: string): ChatMessage;
+    addUserMessage(content: string, id?: string): ChatMessage;
+    addAssistantMessage(content: string, id?: string): ChatMessage;
+    setFeedback(messageId: string, rating: FeedbackRating | undefined): void;
+    getMessages(): ChatMessage[];
+    clearMessages(): void;
+}
+export {};

package/dist/core/chat-manager.js

@@ -0,0 +1,39 @@
+import { EventEmitter } from './event-emitter';
+export class ChatManager extends EventEmitter {
+    messages = [];
+    addMessage(role, content, id) {
+        if (!content.trim()) {
+            throw new Error('Message content cannot be empty');
+        }
+        const message = {
+            id: id ?? crypto.randomUUID(),
+            role,
+            content: content.trim(),
+            timestamp: new Date(),
+        };
+        this.messages = [...this.messages, message];
+        this.emit('messageAdded', message);
+        return message;
+    }
+    addUserMessage(content, id) {
+        return this.addMessage('user', content, id);
+    }
+    addAssistantMessage(content, id) {
+        return this.addMessage('assistant', content, id);
+    }
+    setFeedback(messageId, rating) {
+        const message = this.messages.find(m => m.id === messageId);
+        if (!message)
+            return;
+        message.feedback = rating;
+        this.messages = [...this.messages];
+        this.emit('feedbackChanged', messageId, rating);
+    }
+    getMessages() {
+        return this.messages;
+    }
+    clearMessages() {
+        this.messages = [];
+        this.emit('messagesCleared');
+    }
+}

package/dist/core/config-manager.d.ts

@@ -0,0 +1,14 @@
+import type { WidgetConfig } from '../types';
+import type { WidgetApiClient } from '../services/api';
+export declare class ConfigManager {
+    private config;
+    private readonly apiClient;
+    constructor(apiClient: WidgetApiClient);
+    loadConfig(): Promise<WidgetConfig>;
+    getConfig(): WidgetConfig | null;
+    isDemoMode(): boolean;
+    private normalizeConfig;
+    private normalizeTheme;
+    private normalizeSize;
+    private normalizePlacement;
+}

package/dist/core/config-manager.js

@@ -0,0 +1,75 @@
+import { getDemoConfig, isDemoMode } from '../constants/defaults';
+import { logger } from '../utils/logger';
+export class ConfigManager {
+    config = null;
+    apiClient;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    async loadConfig() {
+        const demoConfig = isDemoMode ? getDemoConfig() : null;
+        if (demoConfig) {
+            logger.debug('[ConfigManager] Running in demo mode');
+            this.config = demoConfig;
+            return this.config;
+        }
+        const rawConfig = await this.apiClient.getWidgetConfig();
+        this.config = this.normalizeConfig(rawConfig);
+        logger.debug('[ConfigManager] Config loaded:', this.config.name);
+        return this.config;
+    }
+    getConfig() {
+        return this.config;
+    }
+    isDemoMode() {
+        return isDemoMode;
+    }
+    normalizeConfig(config) {
+        return {
+            ...config,
+            unmuteText: config.unmuteText || 'Unmute',
+            minimizeText: config.minimizeText || 'Minimize',
+            voiceButtonText: config.voiceButtonText || config.startButtonText,
+            textButtonText: config.textButtonText || config.startButtonText,
+            copyText: config.copyText || 'Copy',
+            copiedText: config.copiedText || 'Copied!',
+            theme: this.normalizeTheme(config.theme),
+            size: this.normalizeSize(config.size),
+            placement: this.normalizePlacement(config.placement),
+        };
+    }
+    normalizeTheme(theme) {
+        const normalized = String(theme).toLowerCase();
+        if (normalized === 'light')
+            return 'light';
+        if (normalized === 'auto')
+            return 'auto';
+        return 'dark';
+    }
+    normalizeSize(size) {
+        const normalized = String(size).toLowerCase();
+        if (normalized === 'small')
+            return 'small';
+        if (normalized === 'large')
+            return 'large';
+        return 'compact';
+    }
+    normalizePlacement(placement) {
+        const normalized = String(placement).toLowerCase();
+        const mapping = {
+            'topleft': 'top-left',
+            'top-left': 'top-left',
+            'topcenter': 'top-center',
+            'top-center': 'top-center',
+            'topright': 'top-right',
+            'top-right': 'top-right',
+            'bottomleft': 'bottom-left',
+            'bottom-left': 'bottom-left',
+            'bottomcenter': 'bottom-center',
+            'bottom-center': 'bottom-center',
+            'bottomright': 'bottom-right',
+            'bottom-right': 'bottom-right',
+        };
+        return mapping[normalized] ?? 'bottom-right';
+    }
+}

package/dist/core/connection-manager.d.ts

@@ -0,0 +1,68 @@
+import type { ConnectionState, FunctionCall, VoiceUsage, WidgetConfig } from '../types';
+import type { WidgetApiClient } from '../services/api';
+import type { DocumentProvider, WindowProvider, ExternalExecutor } from '../services/page-interaction/page-interaction-handler';
+import { EventEmitter } from './event-emitter';
+interface ConnectionEvents {
+    connectionStateChanged: (state: ConnectionState) => void;
+    unexpectedDisconnect: () => void;
+    voiceUnhealthy: (reason: string) => void;
+    voiceHealthy: () => void;
+    userSpeechStart: () => void;
+    userSpeechStop: () => void;
+    userSpeechEnd: () => void;
+    audioLevel: (level: number) => void;
+    transcriptReceived: (data: {
+        isUser: boolean;
+        text: string;
+    }) => void;
+    transcriptDelta: (data: {
+        isUser: boolean;
+        delta: string;
+    }) => void;
+    functionCall: (call: FunctionCall) => void;
+    usageUpdated: (usage: VoiceUsage) => void;
+    toolCall: (data: {
+        toolName: string;
+        status: string;
+    }) => void;
+    error: (error: string) => void;
+    microphoneBlocked: () => void;
+    stopConversation: () => void;
+    openUrl: (url: string) => void;
+    openFile: (url: string) => void;
+    microphoneReady: () => void;
+}
+export declare class ConnectionManager extends EventEmitter<ConnectionEvents> {
+    private webrtcService;
+    private signalRService;
+    private pageInteractionHandler;
+    private readonly apiClient;
+    private readonly voiceSessionTracker;
+    private connectionState;
+    private userInitiatedDisconnect;
+    private isMuted;
+    private servicesInitialized;
+    private pendingExternalExecutor;
+    private pendingDocumentProvider;
+    constructor(apiClient: WidgetApiClient);
+    private initializeServices;
+    private setupEventHandlers;
+    connect(config: WidgetConfig, pageUrl?: string, pageTitle?: string, skipGreeting?: boolean): Promise<void>;
+    private setupSignalRAndPageInteraction;
+    private simulateDemoConnection;
+    disconnect(): Promise<void>;
+    sendText(text: string): Promise<void>;
+    sendFunctionResult(callId: string, name: string, result: string): Promise<void>;
+    setMuted(muted: boolean): void;
+    interrupt(): void;
+    setDocumentProvider(getDoc: DocumentProvider, getWin: WindowProvider): void;
+    setExternalExecutor(executor: ExternalExecutor | null): void;
+    getConnectionState(): ConnectionState;
+    isConnected(): boolean;
+    isMutedState(): boolean;
+    waitForResponseComplete(timeoutMs?: number): Promise<void>;
+    private static readonly NOISE_WORDS;
+    private isNoiseTranscript;
+    dispose(): void;
+}
+export {};

package/dist/core/connection-manager.js

@@ -0,0 +1,273 @@
+import { VoiceSessionTracker } from '../services/realtime/voice-session-tracker';
+import { isDemoMode } from '../constants/defaults';
+import { logger } from '../utils/logger';
+import { EventEmitter } from './event-emitter';
+const MIN_TRANSCRIPT_LENGTH = 2;
+const DEMO_CONNECTION_DELAY_MS = 500;
+export class ConnectionManager extends EventEmitter {
+    webrtcService = null;
+    signalRService = null;
+    pageInteractionHandler = null;
+    apiClient;
+    voiceSessionTracker = new VoiceSessionTracker();
+    connectionState = 'disconnected';
+    userInitiatedDisconnect = false;
+    isMuted = false;
+    servicesInitialized = false;
+    pendingExternalExecutor = null;
+    pendingDocumentProvider = null;
+    constructor(apiClient) {
+        super();
+        this.apiClient = apiClient;
+    }
+    async initializeServices() {
+        if (this.servicesInitialized) {
+            return;
+        }
+        logger.debug('[ConnectionManager] Lazy loading WebRTC and SignalR services...');
+        const [{ WebRtcService }, { SignalRService }] = await Promise.all([
+            import('../services/webrtc'),
+            import('../services/signalr'),
+        ]);
+        this.webrtcService = new WebRtcService();
+        this.signalRService = new SignalRService();
+        this.setupEventHandlers();
+        this.servicesInitialized = true;
+        logger.debug('[ConnectionManager] Services initialized');
+    }
+    setupEventHandlers() {
+        if (!this.webrtcService || !this.signalRService) {
+            return;
+        }
+        this.webrtcService.setEventHandlers({
+            onUserSpeechStart: () => this.emit('userSpeechStart'),
+            onUserSpeechStop: () => this.emit('userSpeechStop'),
+            onUserSpeechEnd: () => this.emit('userSpeechEnd'),
+            onAudioLevel: (level) => this.emit('audioLevel', level),
+            onTranscriptReceived: (isUser, text) => {
+                const trimmed = text.trim();
+                if (!trimmed) {
+                    return;
+                }
+                if (isUser && this.isNoiseTranscript(trimmed)) {
+                    logger.debug('[ConnectionManager] Filtered noise transcript:', trimmed);
+                    return;
+                }
+                this.emit('transcriptReceived', { isUser, text: trimmed });
+            },
+            onTranscriptDelta: (isUser, delta) => {
+                if (isUser && delta.trim().length <= MIN_TRANSCRIPT_LENGTH) {
+                    return;
+                }
+                this.emit('transcriptDelta', { isUser, delta });
+            },
+            onFunctionCall: (call) => this.emit('functionCall', call),
+            onUsageUpdated: (usage) => this.emit('usageUpdated', usage),
+            onError: (err) => this.emit('error', err),
+            onConnectionStateChanged: (state) => {
+                const wasConnected = this.connectionState === 'connected';
+                this.connectionState = state;
+                this.emit('connectionStateChanged', state);
+                if (state === 'disconnected' && wasConnected && !this.userInitiatedDisconnect) {
+                    logger.debug('[ConnectionManager] Unexpected disconnect detected');
+                    this.emit('unexpectedDisconnect');
+                }
+            },
+            onMicrophoneReady: () => this.emit('microphoneReady'),
+            onVoiceUnhealthy: (reason) => {
+                if (!this.userInitiatedDisconnect)
+                    this.emit('voiceUnhealthy', reason);
+            },
+            onVoiceHealthy: () => this.emit('voiceHealthy'),
+        });
+        this.signalRService.setEventHandlers({
+            onStopConversation: () => this.emit('stopConversation'),
+            onOpenUrl: (url) => this.emit('openUrl', url),
+            onOpenFile: (url) => this.emit('openFile', url),
+            onError: (title, message) => this.emit('error', `${title}: ${message}`),
+        });
+    }
+    async connect(config, pageUrl, pageTitle, skipGreeting = false) {
+        if (isDemoMode) {
+            await this.simulateDemoConnection();
+            return;
+        }
+        this.userInitiatedDisconnect = false;
+        await this.initializeServices();
+        if (!this.webrtcService || !this.signalRService) {
+            throw new Error('Services not initialized');
+        }
+        try {
+            const micPermission = await this.webrtcService.requestMicrophonePermission();
+            if (micPermission === 'denied') {
+                this.emit('microphoneBlocked');
+                throw new Error('Microphone permission denied');
+            }
+            const [tokenResponse, instructions, tools] = await Promise.all([
+                this.apiClient.getEphemeralToken().catch((err) => {
+                    throw new Error(`Ephemeral token request failed: ${err instanceof Error ? err.message : String(err)}`);
+                }),
+                this.apiClient.generatePrompt(pageUrl, pageTitle).catch((err) => {
+                    throw new Error(`Prompt generation failed: ${err instanceof Error ? err.message : String(err)}`);
+                }),
+                this.apiClient.getTools().catch(() => []),
+            ]);
+            const bearerToken = this.apiClient.getBearerToken();
+            if (bearerToken) {
+                await this.setupSignalRAndPageInteraction(this.signalRService, bearerToken);
+            }
+            const providerType = (tokenResponse.provider ?? 'openai');
+            const effectiveToken = providerType === 'vertexai'
+                ? (this.apiClient.getBearerToken() ?? '')
+                : tokenResponse.token;
+            let proxyUrl = tokenResponse.proxyUrl;
+            let proxyBearerToken;
+            if (providerType === 'vertexai' && proxyUrl) {
+                const baseUrl = this.apiClient.getBaseUrl().replace(/\/$/, '');
+                const wsBase = baseUrl.replace(/^http/, 'ws');
+                proxyUrl = `${wsBase}${proxyUrl}`;
+                proxyBearerToken = this.apiClient.getBearerToken() ?? '';
+            }
+            await this.webrtcService.connect({
+                token: effectiveToken,
+                model: tokenResponse.model,
+                instructions,
+                voice: config.voice,
+                tools,
+                speed: config.speechSpeed,
+                language: config.language,
+                transcribeModel: config.transcribeModel,
+                transcriptionMode: config.transcriptionMode,
+                transcriptionPrompt: config.transcriptionPrompt,
+                provider: providerType,
+                proxyUrl,
+                proxyBearerToken,
+                skipGreeting,
+            });
+            const voiceSessionId = crypto.randomUUID();
+            await this.voiceSessionTracker.startTracking(this.apiClient, voiceSessionId);
+            logger.debug('[ConnectionManager] Connected successfully');
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Connection failed';
+            logger.error('[ConnectionManager] Connection failed:', message);
+            throw err;
+        }
+    }
+    async setupSignalRAndPageInteraction(signalR, bearerToken) {
+        const claims = this.apiClient.getTokenClaims();
+        signalR.setRegistrationInfo(this.apiClient.getClientId(), claims.tenantId ?? '00000000-0000-0000-0000-000000000000', claims.userId ?? '00000000-0000-0000-0000-000000000000');
+        const { PageInteractionHandler } = await import('../services/page-interaction/page-interaction-handler');
+        this.pageInteractionHandler = new PageInteractionHandler(() => signalR.getConnection() ?? null);
+        if (this.pendingExternalExecutor) {
+            this.pageInteractionHandler.setExternalExecutor(this.pendingExternalExecutor);
+        }
+        if (this.pendingDocumentProvider) {
+            this.pageInteractionHandler.setDocumentProvider(this.pendingDocumentProvider.getDoc, this.pendingDocumentProvider.getWin);
+        }
+        signalR.setTextChatHandlers({
+            onToolCall: (toolName, status) => {
+                this.emit('toolCall', { toolName, status });
+            },
+        });
+        signalR.setPageInteractionHandlers({
+            onPageInteractionRequest: (requestJson) => {
+                this.pageInteractionHandler?.handleRequest(requestJson);
+            },
+        });
+        await signalR.connect(this.apiClient.getBaseUrl(), bearerToken);
+    }
+    async simulateDemoConnection() {
+        await new Promise((resolve) => setTimeout(resolve, DEMO_CONNECTION_DELAY_MS));
+        this.connectionState = 'connected';
+        this.emit('connectionStateChanged', 'connected');
+    }
+    async disconnect() {
+        this.userInitiatedDisconnect = true;
+        await this.voiceSessionTracker.stopTracking();
+        if (isDemoMode) {
+            this.connectionState = 'disconnected';
+            this.emit('connectionStateChanged', 'disconnected');
+            return;
+        }
+        this.signalRService?.clearPageInteractionHandlers();
+        this.pageInteractionHandler = null;
+        const disconnectTasks = [];
+        if (this.webrtcService)
+            disconnectTasks.push(this.webrtcService.disconnect());
+        if (this.signalRService)
+            disconnectTasks.push(this.signalRService.disconnect());
+        await Promise.all(disconnectTasks);
+        logger.debug('[ConnectionManager] Disconnected');
+    }
+    async sendText(text) {
+        if (isDemoMode || !this.webrtcService) {
+            return;
+        }
+        await this.webrtcService.sendText(text);
+    }
+    async sendFunctionResult(callId, name, result) {
+        if (this.webrtcService?.isConnected) {
+            await this.webrtcService.sendFunctionResult(callId, name, result);
+        }
+    }
+    setMuted(muted) {
+        this.isMuted = muted;
+        if (!isDemoMode && this.webrtcService) {
+            this.webrtcService.setMuted(muted);
+        }
+    }
+    interrupt() {
+        if (!isDemoMode) {
+            this.webrtcService?.interrupt();
+        }
+    }
+    setDocumentProvider(getDoc, getWin) {
+        this.pendingDocumentProvider = { getDoc, getWin };
+        this.pageInteractionHandler?.setDocumentProvider(getDoc, getWin);
+    }
+    setExternalExecutor(executor) {
+        this.pendingExternalExecutor = executor;
+        this.pageInteractionHandler?.setExternalExecutor(executor);
+    }
+    getConnectionState() {
+        return this.connectionState;
+    }
+    isConnected() {
+        return this.connectionState === 'connected';
+    }
+    isMutedState() {
+        return this.isMuted;
+    }
+    async waitForResponseComplete(timeoutMs = 30000) {
+        if (isDemoMode || !this.webrtcService) {
+            return;
+        }
+        await this.webrtcService.waitForResponseComplete(timeoutMs);
+    }
+    static NOISE_WORDS = new Set([
+        'uh', 'uhh', 'uhhh', 'uhm', 'uhmm',
+        'hm', 'hmm', 'hmmm', 'mhm', 'mhmm',
+        'ah', 'ahh', 'ahhh', 'oh', 'ohh', 'ohhh',
+        'eh', 'ehh', 'ehhh', 'öh', 'öhh',
+        'äh', 'ähh', 'ähm', 'ähmm',
+        'tja', 'psst', 'huh',
+        'pff', 'pfff', 'tss', 'tsss',
+        'sh', 'shh', 'shhh',
+        'ha', 'haha', 'hahaha',
+        'he', 'hehe', 'hehehe',
+        'hi', 'hihi', 'hihihi',
+    ]);
+    isNoiseTranscript(text) {
+        return text.length <= MIN_TRANSCRIPT_LENGTH || ConnectionManager.NOISE_WORDS.has(text.toLowerCase());
+    }
+    dispose() {
+        this.userInitiatedDisconnect = true;
+        void this.voiceSessionTracker.stopTracking();
+        this.signalRService?.clearPageInteractionHandlers();
+        this.pageInteractionHandler = null;
+        this.webrtcService?.disconnect();
+        this.signalRService?.disconnect();
+        this.removeAllListeners();
+    }
+}

package/dist/core/connection-retry-handler.d.ts

@@ -0,0 +1,11 @@
+type RetryOptions = {
+    connectFn: () => Promise<void>;
+    cleanupFn: () => Promise<void>;
+    label: string;
+    logPrefix: string;
+    onMicrophoneDenied?: () => void;
+};
+export declare class ConnectionRetryHandler {
+    retryAsync({ connectFn, cleanupFn, label, logPrefix, onMicrophoneDenied }: RetryOptions): Promise<boolean>;
+}
+export {};