@nextpa/chat-core 0.1.0

package/dist/services/webrtc.d.ts

@@ -0,0 +1,44 @@
+import type { ConnectionState, ConversationEvents, ToolDefinition } from '../types';
+import type { RealtimeProviderType } from './realtime/types';
+export type TranscriptionMode = 'oob' | 'native';
+export interface WebRtcConfig {
+    token: string;
+    model: string;
+    voice?: string;
+    instructions?: string;
+    tools?: ToolDefinition[];
+    speed?: number;
+    language?: string;
+    transcribeModel?: string;
+    transcriptionMode?: TranscriptionMode;
+    transcriptionPrompt?: string;
+    provider?: RealtimeProviderType;
+    proxyUrl?: string;
+    proxyBearerToken?: string;
+    skipGreeting?: boolean;
+}
+export declare class WebRtcService {
+    private client;
+    private events;
+    private _connectionState;
+    private watchdog;
+    private readonly microphoneManager;
+    private providerType;
+    private model;
+    get connectionState(): ConnectionState;
+    get isConnected(): boolean;
+    setEventHandlers(events: ConversationEvents): void;
+    requestMicrophonePermission(): Promise<'granted' | 'denied' | 'prompt'>;
+    connect(config: WebRtcConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    private readonly resumeAudioOnVisible;
+    private attachVisibilityResume;
+    private detachVisibilityResume;
+    sendText(text: string): Promise<void>;
+    setMuted(muted: boolean): void;
+    interrupt(): void;
+    waitForResponseComplete(timeoutMs?: number): Promise<void>;
+    sendFunctionResult(callId: string, name: string, result: string): Promise<void>;
+    private handleUsageUpdated;
+    private setConnectionState;
+}

package/dist/services/webrtc.js

@@ -0,0 +1,196 @@
+import { createRealtimeProvider } from './realtime/provider-factory';
+import { logger } from '../utils/logger';
+import { MicrophoneManager } from './webrtc-microphone';
+import { setupEventHandlers } from './webrtc-event-handler';
+import { startGreetingFlow } from './webrtc-greeting';
+import { VoiceHealthWatchdog } from './voice-health-watchdog';
+export class WebRtcService {
+    client = null;
+    events = {};
+    _connectionState = 'disconnected';
+    watchdog = null;
+    microphoneManager = new MicrophoneManager();
+    providerType = 'openai';
+    model = '';
+    get connectionState() {
+        return this._connectionState;
+    }
+    get isConnected() {
+        return this._connectionState === 'connected';
+    }
+    setEventHandlers(events) {
+        this.events = events;
+    }
+    async requestMicrophonePermission() {
+        return this.microphoneManager.requestPermission();
+    }
+    async connect(config) {
+        if (this.client) {
+            await this.disconnect();
+        }
+        this.setConnectionState('connecting');
+        try {
+            this.providerType = config.provider ?? 'openai';
+            this.model = config.model;
+            logger.debug('[WebRTC] Connecting with provider:', this.providerType, 'model:', this.model);
+            this.client = await createRealtimeProvider(this.providerType);
+            setupEventHandlers(this.client, this.events, this.microphoneManager, (state) => this.setConnectionState(state), (usage) => this.handleUsageUpdated(usage));
+            // Start the health watchdog before connecting so it never misses an
+            // early sessionReady. It detects a "connected but dead" session
+            // (no setup / greeting never responds) and asks the owner to recover.
+            this.watchdog = new VoiceHealthWatchdog(this.client, !(config.skipGreeting ?? false), (reason) => this.events.onVoiceUnhealthy?.(reason), () => this.events.onVoiceHealthy?.());
+            this.watchdog.start();
+            await this.client.connect({
+                apiKey: config.token,
+                model: config.model,
+                instructions: config.instructions || '',
+                voice: config.voice || 'ash',
+                tools: config.tools || [],
+                toolChoice: 'auto',
+                speed: config.speed,
+                transcription: config.language
+                    ? {
+                        mode: config.transcriptionMode ?? 'native',
+                        model: config.transcribeModel,
+                        language: config.language,
+                        prompt: config.transcriptionPrompt,
+                    }
+                    : undefined,
+                proxyUrl: config.proxyUrl,
+                proxyBearerToken: config.proxyBearerToken,
+            });
+            logger.debug('[WebRTC] Connected successfully');
+            this.attachVisibilityResume();
+            this.microphoneManager.startDeviceChangeDetection();
+            this.client.mute(true);
+            this.microphoneManager.initPendingUnmute();
+            logger.debug('[WebRTC] Microphone initially muted, pending unmute after greeting');
+            startGreetingFlow(this.client, this.microphoneManager, this.events.onMicrophoneReady, config.skipGreeting ?? false);
+        }
+        catch (error) {
+            this.watchdog?.stop();
+            this.watchdog = null;
+            logger.error('[WebRTC] Connection failed:', error);
+            // Drop the half-built client so the retry creates a fresh peer
+            // connection instead of trying to drive the closed one (which
+            // throws InvalidStateError 'signalingState is closed').
+            if (this.client) {
+                try {
+                    this.client.close();
+                }
+                catch {
+                    // best-effort — the SDK may already have torn it down
+                }
+                this.client = null;
+            }
+            this.setConnectionState('error');
+            this.events.onError?.(error instanceof Error ? error.message : 'Connection failed');
+            throw error;
+        }
+    }
+    async disconnect() {
+        this.detachVisibilityResume();
+        this.watchdog?.stop();
+        this.watchdog = null;
+        this.microphoneManager.reset();
+        if (this.client) {
+            this.client.close();
+            this.client = null;
+        }
+        this.setConnectionState('disconnected');
+        logger.debug('[WebRTC] Disconnected');
+    }
+    // iOS suspends audio when an installed PWA is backgrounded; nudge the active
+    // provider to re-arm playback + the mic-level analyser when we're visible again.
+    resumeAudioOnVisible = () => {
+        if (typeof document !== 'undefined' && document.visibilityState !== 'visible')
+            return;
+        this.client?.resumeAudio?.();
+    };
+    attachVisibilityResume() {
+        if (typeof document === 'undefined')
+            return;
+        document.addEventListener('visibilitychange', this.resumeAudioOnVisible);
+        if (globalThis.window !== undefined) {
+            globalThis.window.addEventListener('focus', this.resumeAudioOnVisible);
+        }
+    }
+    detachVisibilityResume() {
+        if (typeof document === 'undefined')
+            return;
+        document.removeEventListener('visibilitychange', this.resumeAudioOnVisible);
+        if (globalThis.window !== undefined) {
+            globalThis.window.removeEventListener('focus', this.resumeAudioOnVisible);
+        }
+    }
+    async sendText(text) {
+        if (this.client?.status !== 'connected') {
+            throw new Error('Not connected');
+        }
+        // The caller (WidgetController.sendMessage) already adds the user
+        // message and persists it as 'Typed'. Re-emitting it as a transcript
+        // would make the voice-state-manager add it a second time, so the
+        // history shows the typed line twice. Spoken transcripts still arrive
+        // through the provider client's native transcript events.
+        this.client.sendText(text);
+    }
+    setMuted(muted) {
+        if (!this.client)
+            return;
+        this.microphoneManager.setMuted(muted, this.client);
+    }
+    interrupt() {
+        if (this.client?.status === 'connected') {
+            this.client.interrupt();
+        }
+    }
+    waitForResponseComplete(timeoutMs = 30000) {
+        return new Promise((resolve) => {
+            if (this.client?.status !== 'connected') {
+                resolve();
+                return;
+            }
+            const client = this.client;
+            let resolved = false;
+            let timeoutHandle = null;
+            const finish = (reason) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                if (timeoutHandle !== null) {
+                    clearTimeout(timeoutHandle);
+                    timeoutHandle = null;
+                }
+                unsubscribeAudioDone();
+                logger.debug(`[WebRTC] ${reason}`);
+                resolve();
+            };
+            const unsubscribeAudioDone = client.on('audioDone', () => {
+                logger.debug('[WebRTC] audioDone received, monitoring audio playback...');
+                client.waitForAudioPlaybackEnd()
+                    .then((silenceReason) => finish(`Audio playback complete (${silenceReason})`))
+                    .catch(() => finish('Audio monitoring unavailable, disconnecting'));
+            });
+            timeoutHandle = setTimeout(() => {
+                finish('Response wait timeout');
+            }, timeoutMs);
+        });
+    }
+    async sendFunctionResult(callId, name, result) {
+        if (this.client?.status !== 'connected') {
+            throw new Error('Not connected');
+        }
+        this.client.sendToolResult(callId, name, result);
+    }
+    handleUsageUpdated(usage) {
+        this.events.onUsageUpdated?.({
+            provider: this.providerType,
+            model: this.model,
+            ...usage,
+        });
+    }
+    setConnectionState(state) {
+        this._connectionState = state;
+        this.events.onConnectionStateChanged?.(state);
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,151 @@
+export interface WidgetDesignTokens {
+    primaryColor: string;
+    primaryColorHover: string;
+    textOnPrimary: string;
+    secondaryColor: string;
+    secondaryColorHover: string;
+    textOnSecondary: string;
+}
+export type AssistantMode = 'voice' | 'text';
+export interface WidgetConfig {
+    assistantId: string;
+    tenantId: string;
+    name: string;
+    welcomeMessage: string;
+    logoUrl: string;
+    theme: WidgetTheme;
+    size: WidgetSize;
+    placement: WidgetPlacement;
+    voice?: string;
+    largeTeaserText: string;
+    largeCtaText: string;
+    inputPlaceholder: string;
+    startButtonText: string;
+    connectingText: string;
+    listeningText: string;
+    preparingText: string;
+    sendButtonText: string;
+    disconnectText: string;
+    mutedText: string;
+    unmuteText: string;
+    minimizeText: string;
+    resetText: string;
+    resetConfirmText: string;
+    resetConfirmButtonText: string;
+    resetCancelButtonText: string;
+    errorText: string;
+    microphoneBlockedText: string;
+    microphoneBlockedHintText: string;
+    designTokens: WidgetDesignTokens;
+    darkDesignTokens?: WidgetDesignTokens;
+    lightDesignTokens?: WidgetDesignTokens;
+    showTermsAndConditions?: boolean;
+    termsAndConditions?: string;
+    termsAcceptButtonText?: string;
+    termsDeclineButtonText?: string;
+    speechSpeed?: number;
+    popoverEnabled?: boolean;
+    greetingEnabled?: boolean;
+    popoverAutoCloseSeconds?: number;
+    popoverText?: string;
+    chatTitle?: string;
+    assistantMode?: AssistantMode;
+    language?: string;
+    textChatFallbackText?: string;
+    transcribeModel?: string;
+    transcriptionMode?: 'oob' | 'native';
+    transcriptionPrompt?: string;
+    voiceButtonText?: string;
+    textButtonText?: string;
+    voiceButtonHint?: string;
+    textButtonHint?: string;
+    copyText?: string;
+    copiedText?: string;
+    hideBranding?: boolean;
+}
+export interface ConnectOptions {
+    /**
+     * Hold the first user message (display and send) until the greeting has finished streaming.
+     * Default `true`. Set `false` to send the first message immediately, even mid-greeting.
+     */
+    waitForGreeting?: boolean;
+    /**
+     * Override the per-assistant greeting setting (`config.greetingEnabled`) for this connect.
+     * `undefined` uses the server config; `true` forces a greeting; `false` suppresses it.
+     * Applies to both text and voice. Never re-greets a resumed conversation.
+     */
+    greeting?: boolean;
+}
+export type WidgetTheme = 'light' | 'dark' | 'auto';
+export type WidgetSize = 'small' | 'compact' | 'large';
+export type WidgetPlacement = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: Date;
+    feedback?: FeedbackRating;
+}
+export type FeedbackRating = -1 | 1 | 2;
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+export interface ToolDefinition {
+    type: 'function';
+    name: string;
+    description: string;
+    strict?: boolean;
+    parameters: ToolParameters;
+}
+export interface ToolParameters {
+    type: 'object';
+    properties: Record<string, ToolProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+export interface ToolProperty {
+    type: string;
+    description?: string;
+    format?: string;
+    items?: ToolProperty;
+    properties?: Record<string, ToolProperty>;
+    required?: string[];
+    enum?: string[];
+}
+export interface FunctionCall {
+    callId: string;
+    name: string;
+    arguments: string;
+}
+export interface VoiceUsage {
+    readonly provider: string;
+    readonly model: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly cachedTokens?: number;
+    readonly textCachedInputTokens?: number;
+    readonly audioCachedInputTokens?: number;
+    readonly audioInputTokens?: number;
+    readonly audioOutputTokens?: number;
+    readonly textInputTokens?: number;
+    readonly textOutputTokens?: number;
+}
+export interface ConversationEvents {
+    onUserSpeechStart?: () => void;
+    onUserSpeechStop?: () => void;
+    onUserSpeechEnd?: () => void;
+    onTranscriptReceived?: (isUser: boolean, text: string) => void;
+    onTranscriptDelta?: (isUser: boolean, delta: string) => void;
+    onFunctionCall?: (call: FunctionCall) => void;
+    onUsageUpdated?: (usage: VoiceUsage) => void;
+    onError?: (error: string) => void;
+    onConnectionStateChanged?: (state: ConnectionState) => void;
+    onMicrophoneReady?: () => void;
+    onAudioLevel?: (level: number) => void;
+    onVoiceUnhealthy?: (reason: string) => void;
+    onVoiceHealthy?: () => void;
+}
+export interface ApiError {
+    message: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/audio-context.d.ts

@@ -0,0 +1,11 @@
+export declare function getSharedAudioContext(): AudioContext | null;
+export declare function withResumedContext(ctx: AudioContext, play: () => void, onError: (err: unknown) => void): void;
+/**
+ * Unlock audio inside a user gesture's activation window. iOS/Safari only let an
+ * AudioContext run once it has been resumed during a gesture; the voice playback
+ * context is created later (after getUserMedia + token await) and would stay
+ * suspended. Resuming the shared context on the start-voice click unlocks audio
+ * for the page session so the later playback context runs. Call synchronously
+ * before any await; idempotent and provider-agnostic.
+ */
+export declare function primeAudioOnGesture(): void;

package/dist/utils/audio-context.js

@@ -0,0 +1,33 @@
+let cachedContext = null;
+export function getSharedAudioContext() {
+    if (cachedContext)
+        return cachedContext;
+    const Ctor = globalThis.AudioContext;
+    if (!Ctor)
+        return null;
+    try {
+        cachedContext = new Ctor();
+        return cachedContext;
+    }
+    catch {
+        return null;
+    }
+}
+export function withResumedContext(ctx, play, onError) {
+    const resume = ctx.state === 'suspended' ? ctx.resume() : Promise.resolve();
+    void resume.then(play).catch(onError);
+}
+/**
+ * Unlock audio inside a user gesture's activation window. iOS/Safari only let an
+ * AudioContext run once it has been resumed during a gesture; the voice playback
+ * context is created later (after getUserMedia + token await) and would stay
+ * suspended. Resuming the shared context on the start-voice click unlocks audio
+ * for the page session so the later playback context runs. Call synchronously
+ * before any await; idempotent and provider-agnostic.
+ */
+export function primeAudioOnGesture() {
+    const ctx = getSharedAudioContext();
+    if (!ctx)
+        return;
+    withResumedContext(ctx, () => undefined, () => undefined);
+}

package/dist/utils/connect-chime.d.ts

@@ -0,0 +1,11 @@
+export type ConnectChimeVariantId = 'plagal' | 'arpeggio' | 'bell';
+export interface ConnectChimeVariant {
+    readonly id: ConnectChimeVariantId;
+    readonly label: string;
+    readonly description: string;
+}
+export declare const CONNECT_CHIME_VARIANTS: readonly ConnectChimeVariant[];
+export declare function getActiveConnectChimeVariant(): ConnectChimeVariantId;
+export declare function setActiveConnectChimeVariant(variant: ConnectChimeVariantId): void;
+export declare function playConnectChimeVariant(variant: ConnectChimeVariantId): void;
+export declare function playConnectChime(): void;

package/dist/utils/connect-chime.js

@@ -0,0 +1,230 @@
+import { getSharedAudioContext, withResumedContext } from './audio-context';
+import { logger } from './logger';
+const MASTER_FILTER_Q = 0.5;
+const REVERB_DECAY_POWER = 2.2;
+const cachedImpulses = new Map();
+function getImpulseResponse(ctx, durationSec, decayPower) {
+    const key = Math.round(durationSec * 100) + decayPower / 10;
+    const existing = cachedImpulses.get(key);
+    if (existing)
+        return existing;
+    const length = Math.floor(durationSec * ctx.sampleRate);
+    const buffer = ctx.createBuffer(2, length, ctx.sampleRate);
+    for (let channel = 0; channel < 2; channel++) {
+        const data = buffer.getChannelData(channel);
+        for (let i = 0; i < length; i++) {
+            const t = i / length;
+            data[i] = (Math.random() * 2 - 1) * Math.pow(1 - t, decayPower);
+        }
+    }
+    cachedImpulses.set(key, buffer);
+    return buffer;
+}
+function buildBus(ctx, filterFreq, reverbDurationSec, reverbWet) {
+    const filter = ctx.createBiquadFilter();
+    filter.type = 'lowpass';
+    filter.frequency.value = filterFreq;
+    filter.Q.value = MASTER_FILTER_Q;
+    const dryGain = ctx.createGain();
+    dryGain.gain.value = 1 - reverbWet;
+    dryGain.connect(ctx.destination);
+    const convolver = ctx.createConvolver();
+    convolver.buffer = getImpulseResponse(ctx, reverbDurationSec, REVERB_DECAY_POWER);
+    const wetGain = ctx.createGain();
+    wetGain.gain.value = reverbWet;
+    convolver.connect(wetGain).connect(ctx.destination);
+    filter.connect(dryGain);
+    filter.connect(convolver);
+    return filter;
+}
+function scheduleSineChord(params) {
+    const { ctx, voices, startAt, attackSec, holdSec, releaseSec, peakGain, destination } = params;
+    const envelope = ctx.createGain();
+    const peakAt = startAt + attackSec;
+    const holdEnd = peakAt + holdSec;
+    const releaseAt = holdEnd + releaseSec;
+    envelope.gain.setValueAtTime(0.0001, startAt);
+    envelope.gain.exponentialRampToValueAtTime(peakGain, peakAt);
+    envelope.gain.setValueAtTime(peakGain, holdEnd);
+    envelope.gain.exponentialRampToValueAtTime(0.0001, releaseAt);
+    envelope.connect(destination);
+    for (const voice of voices) {
+        const osc = ctx.createOscillator();
+        osc.type = 'sine';
+        osc.frequency.value = voice.frequency;
+        const voiceGain = ctx.createGain();
+        voiceGain.gain.value = voice.gain;
+        osc.connect(voiceGain).connect(envelope);
+        osc.start(startAt);
+        osc.stop(releaseAt + 0.05);
+    }
+}
+const PLAGAL_SUBDOMINANT = [
+    { frequency: 196, gain: 0.85 },
+    { frequency: 246.94, gain: 0.65 },
+    { frequency: 293.66, gain: 0.55 },
+    { frequency: 392, gain: 0.6 },
+    { frequency: 493.88, gain: 0.42 },
+    { frequency: 587.33, gain: 0.35 },
+];
+const PLAGAL_TONIC = [
+    { frequency: 146.83, gain: 0.7 },
+    { frequency: 220, gain: 0.55 },
+    { frequency: 293.66, gain: 0.9 },
+    { frequency: 369.99, gain: 0.7 },
+    { frequency: 440, gain: 0.6 },
+    { frequency: 587.33, gain: 0.55 },
+    { frequency: 739.99, gain: 0.4 },
+];
+function playPlagalChime(ctx) {
+    const bus = buildBus(ctx, 4800, 2, 0.3);
+    const startAt = ctx.currentTime + 0.03;
+    scheduleSineChord({
+        ctx, voices: PLAGAL_SUBDOMINANT, startAt,
+        attackSec: 0.04, holdSec: 0.18, releaseSec: 0.9, peakGain: 0.26, destination: bus,
+    });
+    scheduleSineChord({
+        ctx, voices: PLAGAL_TONIC, startAt: startAt + 0.42,
+        attackSec: 0.08, holdSec: 0.35, releaseSec: 1.8, peakGain: 0.32, destination: bus,
+    });
+}
+const ARPEGGIO_NOTES = [293.66, 369.99, 440];
+const ARPEGGIO_STEP_SEC = 0.14;
+const ARPEGGIO_HARMONICS = [
+    { ratio: 1, gain: 0.9 },
+    { ratio: 2, gain: 0.4 },
+    { ratio: 3, gain: 0.18 },
+    { ratio: 4, gain: 0.1 },
+];
+const ARPEGGIO_FINAL_CHORD = [
+    { frequency: 146.83, gain: 0.55 },
+    { frequency: 220, gain: 0.5 },
+    { frequency: 293.66, gain: 0.85 },
+    { frequency: 369.99, gain: 0.7 },
+    { frequency: 440, gain: 0.65 },
+    { frequency: 587.33, gain: 0.55 },
+    { frequency: 739.99, gain: 0.4 },
+];
+function scheduleBellPluck(ctx, fundamental, startAt, destination) {
+    const envelope = ctx.createGain();
+    const peakAt = startAt + 0.005;
+    const holdEnd = peakAt + 0.04;
+    const releaseAt = holdEnd + 0.6;
+    envelope.gain.setValueAtTime(0.0001, startAt);
+    envelope.gain.exponentialRampToValueAtTime(0.36, peakAt);
+    envelope.gain.setValueAtTime(0.36, holdEnd);
+    envelope.gain.exponentialRampToValueAtTime(0.0001, releaseAt);
+    envelope.connect(destination);
+    for (const harmonic of ARPEGGIO_HARMONICS) {
+        const osc = ctx.createOscillator();
+        osc.type = 'sine';
+        osc.frequency.value = fundamental * harmonic.ratio;
+        const layerGain = ctx.createGain();
+        layerGain.gain.value = harmonic.gain;
+        osc.connect(layerGain).connect(envelope);
+        osc.start(startAt);
+        osc.stop(releaseAt + 0.05);
+    }
+}
+function playArpeggioChime(ctx) {
+    const bus = buildBus(ctx, 5400, 2, 0.3);
+    const startAt = ctx.currentTime + 0.03;
+    ARPEGGIO_NOTES.forEach((freq, index) => {
+        scheduleBellPluck(ctx, freq, startAt + index * ARPEGGIO_STEP_SEC, bus);
+    });
+    scheduleSineChord({
+        ctx, voices: ARPEGGIO_FINAL_CHORD,
+        startAt: startAt + ARPEGGIO_STEP_SEC * 2,
+        attackSec: 0.06, holdSec: 0.35, releaseSec: 1.7, peakGain: 0.28, destination: bus,
+    });
+}
+const MODERN_BELL_VOICES = [
+    { frequency: 146.83, gain: 0.55, decaySec: 1.6 },
+    { frequency: 293.66, gain: 0.85, decaySec: 2.4 },
+    { frequency: 369.99, gain: 0.7, decaySec: 2.2 },
+    { frequency: 440, gain: 0.7, decaySec: 2.2 },
+    { frequency: 554.37, gain: 0.55, decaySec: 2 },
+    { frequency: 587.33, gain: 0.6, decaySec: 2 },
+    { frequency: 739.99, gain: 0.42, decaySec: 1.8 },
+    { frequency: 880, gain: 0.36, decaySec: 1.6 },
+    { frequency: 1174.66, gain: 0.22, decaySec: 1.3 },
+];
+function playModernBellChime(ctx) {
+    const bus = buildBus(ctx, 6800, 2.6, 0.34);
+    const startAt = ctx.currentTime + 0.03;
+    const master = ctx.createGain();
+    master.gain.setValueAtTime(0.34, startAt);
+    master.connect(bus);
+    for (const voice of MODERN_BELL_VOICES) {
+        const envelope = ctx.createGain();
+        const peakAt = startAt + 0.004;
+        const holdEnd = peakAt + 0.04;
+        const releaseAt = holdEnd + voice.decaySec;
+        envelope.gain.setValueAtTime(0.0001, startAt);
+        envelope.gain.exponentialRampToValueAtTime(voice.gain, peakAt);
+        envelope.gain.setValueAtTime(voice.gain, holdEnd);
+        envelope.gain.exponentialRampToValueAtTime(0.0001, releaseAt);
+        envelope.connect(master);
+        const osc = ctx.createOscillator();
+        osc.type = 'sine';
+        osc.frequency.value = voice.frequency;
+        osc.connect(envelope);
+        osc.start(startAt);
+        osc.stop(releaseAt + 0.05);
+    }
+}
+export const CONNECT_CHIME_VARIANTS = [
+    { id: 'plagal', label: 'Plagal-Cadence', description: 'warm, geborgen (G-Dur → D-Dur)' },
+    { id: 'arpeggio', label: 'Arpeggio-Up', description: 'perlend, hell (D–F♯–A aufsteigend)' },
+    { id: 'bell', label: 'Modern Bell', description: 'modern, Dmaj7 als Glockenanschlag' },
+];
+const DEFAULT_VARIANT = 'arpeggio';
+const STORAGE_KEY = 'nextpa.chat-app.connect-chime-variant';
+function isValidVariantId(value) {
+    return value === 'plagal' || value === 'arpeggio' || value === 'bell';
+}
+export function getActiveConnectChimeVariant() {
+    try {
+        const stored = globalThis.localStorage?.getItem(STORAGE_KEY);
+        if (isValidVariantId(stored))
+            return stored;
+    }
+    catch {
+        // localStorage may be unavailable (SSR, privacy mode); fall through.
+    }
+    return DEFAULT_VARIANT;
+}
+export function setActiveConnectChimeVariant(variant) {
+    try {
+        globalThis.localStorage?.setItem(STORAGE_KEY, variant);
+    }
+    catch {
+        // best-effort persistence
+    }
+}
+function playVariant(ctx, variant) {
+    switch (variant) {
+        case 'plagal':
+            playPlagalChime(ctx);
+            return;
+        case 'arpeggio':
+            playArpeggioChime(ctx);
+            return;
+        case 'bell':
+            playModernBellChime(ctx);
+            return;
+    }
+}
+export function playConnectChimeVariant(variant) {
+    const ctx = getSharedAudioContext();
+    if (!ctx)
+        return;
+    withResumedContext(ctx, () => playVariant(ctx, variant), (err) => logger.debug('[ConnectChime] failed to play', err));
+}
+export function playConnectChime() {
+    // The live voice-connect cue is fixed to 'arpeggio' (Norbert's pick).
+    // getActiveConnectChimeVariant + the localStorage key remain available
+    // for the hidden ChimeTestSelector, but a stale persisted choice from
+    // earlier testing must not override the live cue.
+    playConnectChimeVariant('arpeggio');
+}

package/dist/utils/consent.d.ts

@@ -0,0 +1,4 @@
+export declare function getConsentCookieName(assistantId: string): string;
+export declare function hasUserConsented(assistantId: string): boolean;
+export declare function setUserConsent(assistantId: string, consented: boolean): void;
+export declare function clearUserConsent(assistantId: string): void;