@bytexbyte/nxtlinq-ai-agent-ui-react-development 0.1.1

package/dist/voice/useWsRealtimeAudio.js

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { BrowserWsPcmPlayer } from './ws/BrowserWsPcmPlayer';
+import { BrowserWsPcmRecorder } from './ws/BrowserWsPcmRecorder';
+import { useVoiceSilenceCommit } from './useVoiceSilenceCommit';
+export function useWsRealtimeAudio(isCaptureActive, isVoiceActive, options) {
+    const playerRef = useRef(null);
+    const recorderRef = useRef(null);
+    const sessionRef = useRef(null);
+    const isCaptureActiveRef = useRef(isCaptureActive);
+    isCaptureActiveRef.current = isCaptureActive;
+    const prevCaptureActiveRef = useRef(isCaptureActive);
+    const getSession = useCallback(() => sessionRef.current, []);
+    const muteAfterSilenceCommitRef = useRef(options.muteAfterSilenceCommit);
+    muteAfterSilenceCommitRef.current = options.muteAfterSilenceCommit;
+    const silence = useVoiceSilenceCommit(getSession, () => muteAfterSilenceCommitRef.current(), options.voiceStatus);
+    const silenceRef = useRef(silence);
+    silenceRef.current = silence;
+    const ensurePlayer = useCallback(async () => {
+        if (!playerRef.current) {
+            playerRef.current = new BrowserWsPcmPlayer();
+            playerRef.current.prewarm();
+        }
+        await playerRef.current.ensureRunning();
+    }, []);
+    const stopCapture = useCallback((commit) => {
+        const s = silenceRef.current;
+        s.clearPoll();
+        recorderRef.current?.stop();
+        if (!commit)
+            return;
+        if (s.consumeSkipCommitOnMute())
+            return;
+        s.tryCommit('manual');
+    }, []);
+    const startCapture = useCallback(async () => {
+        const session = sessionRef.current;
+        if (!session)
+            return;
+        const s = silenceRef.current;
+        if (!recorderRef.current)
+            recorderRef.current = new BrowserWsPcmRecorder();
+        playerRef.current?.clearQueue();
+        recorderRef.current.bindSession(session);
+        recorderRef.current.setOnRms(s.onSpeechRms);
+        s.resetTurn();
+        try {
+            await recorderRef.current.start();
+            s.startPoll();
+        }
+        catch (err) {
+            s.clearPoll();
+            console.error('[nxtlinq] mic capture start failed', err);
+        }
+    }, []);
+    const cleanup = useCallback(() => {
+        silenceRef.current.clearPoll();
+        recorderRef.current?.cleanup();
+        recorderRef.current = null;
+        playerRef.current?.cleanup();
+        playerRef.current = null;
+        sessionRef.current = null;
+    }, []);
+    const bindSession = useCallback((session, captureWhenUnmuted = false) => {
+        sessionRef.current = session;
+        recorderRef.current?.bindSession(session);
+        if (session && captureWhenUnmuted && isCaptureActiveRef.current) {
+            void startCapture();
+        }
+    }, [startCapture]);
+    const buildCallbacks = useCallback((overrides) => ({
+        onOpen: () => {
+            void ensurePlayer();
+            overrides?.onOpen?.();
+        },
+        onAudioDelta: (pcm16) => {
+            void ensurePlayer().then(() => playerRef.current?.addAudio(pcm16));
+            overrides?.onAudioDelta?.(pcm16);
+        },
+        onClose: (reason) => {
+            cleanup();
+            overrides?.onClose?.(reason);
+        },
+        onError: (err) => {
+            cleanup();
+            overrides?.onError?.(err);
+        },
+    }), [cleanup, ensurePlayer]);
+    useEffect(() => {
+        if (!isVoiceActive) {
+            prevCaptureActiveRef.current = false;
+            cleanup();
+            return;
+        }
+        const prev = prevCaptureActiveRef.current;
+        prevCaptureActiveRef.current = isCaptureActive;
+        if (isCaptureActive && !prev)
+            void startCapture();
+        else if (!isCaptureActive && prev)
+            stopCapture(true);
+    }, [isCaptureActive, isVoiceActive, startCapture, stopCapture, cleanup]);
+    return { bindSession, buildCallbacks, getOutputAudioLevel: () => playerRef.current?.getAudioLevel() ?? 0 };
+}

package/dist/voice/voiceMicConstants.d.ts

@@ -0,0 +1,4 @@
+import type { VoiceStatus } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+export declare const ASSISTANT_MIC_HOLD_STATUSES: ReadonlySet<VoiceStatus>;
+export declare const SPEAKER_ACTIVE_STATUSES: ReadonlySet<VoiceStatus>;
+//# sourceMappingURL=voiceMicConstants.d.ts.map

package/dist/voice/voiceMicConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voiceMicConstants.d.ts","sourceRoot":"","sources":["../../src/voice/voiceMicConstants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8CAA8C,CAAC;AAEhF,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,WAAW,CAK/D,CAAC;AAEH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,WAAW,CAG3D,CAAC"}

package/dist/voice/voiceMicConstants.js

@@ -0,0 +1,10 @@
+export const ASSISTANT_MIC_HOLD_STATUSES = new Set([
+    'transcribing',
+    'thinking',
+    'generating',
+    'speaking',
+]);
+export const SPEAKER_ACTIVE_STATUSES = new Set([
+    'generating',
+    'speaking',
+]);

package/dist/voice/ws/BrowserWsPcmPlayer.d.ts

@@ -0,0 +1,23 @@
+export declare class BrowserWsPcmPlayer {
+    private readonly sampleRate;
+    private readonly fadeSamples;
+    private audioContext;
+    private gainNode;
+    private analyserNode;
+    private analyserBuffer;
+    private readonly activeSources;
+    private queue;
+    private isPlaying;
+    private playHead;
+    private lastChunkRms;
+    private lastChunkAt;
+    ensureRunning(): Promise<void>;
+    prewarm(): void;
+    addAudio(pcm16: Int16Array | ArrayBuffer): void;
+    getAudioLevel(): number;
+    clearQueue(): void;
+    cleanup(): void;
+    private ensureContext;
+    private pipelineQueue;
+}
+//# sourceMappingURL=BrowserWsPcmPlayer.d.ts.map

package/dist/voice/ws/BrowserWsPcmPlayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserWsPcmPlayer.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/BrowserWsPcmPlayer.ts"],"names":[],"mappings":"AAeA,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmD;IAC/E,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAK;IAElB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAMpC,OAAO,IAAI,IAAI;IAIf,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAqB/C,aAAa,IAAI,MAAM;IAevB,UAAU,IAAI,IAAI;IAWlB,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,aAAa;CA2BtB"}

package/dist/voice/ws/BrowserWsPcmPlayer.js

@@ -0,0 +1,137 @@
+import { WS_REALTIME_SAMPLE_RATE } from './wsRealtimeConstants';
+const LEVEL_SCALE = 3.2;
+const LOOKAHEAD_SECONDS = 0.02;
+const CROSSFADE_SECONDS = 0.04;
+function applyFade(buffer, fadeSamples) {
+    const fade = Math.min(fadeSamples, Math.floor(buffer.length / 2));
+    if (fade <= 0)
+        return;
+    for (let i = 0; i < fade; i += 1) {
+        buffer[i] *= i / fade;
+        buffer[buffer.length - 1 - i] *= (fade - i) / fade;
+    }
+}
+export class BrowserWsPcmPlayer {
+    constructor() {
+        this.sampleRate = WS_REALTIME_SAMPLE_RATE;
+        this.fadeSamples = Math.max(1, Math.floor(this.sampleRate * 0.01));
+        this.audioContext = null;
+        this.gainNode = null;
+        this.analyserNode = null;
+        this.analyserBuffer = null;
+        this.activeSources = new Set();
+        this.queue = [];
+        this.isPlaying = true;
+        this.playHead = 0;
+        this.lastChunkRms = 0;
+        this.lastChunkAt = 0;
+    }
+    async ensureRunning() {
+        const ctx = this.ensureContext();
+        if (ctx.state === 'suspended')
+            await ctx.resume();
+        this.isPlaying = true;
+    }
+    prewarm() {
+        this.ensureContext();
+    }
+    addAudio(pcm16) {
+        const ctx = this.ensureContext();
+        const int16 = pcm16 instanceof ArrayBuffer ? new Int16Array(pcm16) : pcm16;
+        if (int16.length === 0)
+            return;
+        const floats = new Float32Array(int16.length);
+        let sumSq = 0;
+        for (let i = 0; i < int16.length; i += 1) {
+            const sample = int16[i] / 32768;
+            floats[i] = Math.max(-1, Math.min(1, sample));
+            sumSq += sample * sample;
+        }
+        applyFade(floats, this.fadeSamples);
+        this.lastChunkRms = Math.min(1, Math.sqrt(sumSq / int16.length) * LEVEL_SCALE);
+        this.lastChunkAt = Date.now();
+        const buffer = ctx.createBuffer(1, floats.length, this.sampleRate);
+        buffer.getChannelData(0).set(floats);
+        this.queue.push(buffer);
+        this.isPlaying = true;
+        this.pipelineQueue();
+    }
+    getAudioLevel() {
+        const analyser = this.analyserNode;
+        const buf = this.analyserBuffer;
+        if (analyser && buf && this.activeSources.size > 0) {
+            analyser.getFloatTimeDomainData(buf);
+            let sumSq = 0;
+            for (let i = 0; i < buf.length; i += 1) {
+                const v = buf[i];
+                sumSq += v * v;
+            }
+            return Math.min(1, Math.sqrt(sumSq / buf.length) * LEVEL_SCALE);
+        }
+        return Date.now() - this.lastChunkAt < 500 ? this.lastChunkRms : 0;
+    }
+    clearQueue() {
+        for (const source of this.activeSources) {
+            try {
+                source.stop();
+            }
+            catch { /* noop */ }
+        }
+        this.activeSources.clear();
+        this.queue = [];
+        this.playHead = this.audioContext?.currentTime ?? 0;
+        this.lastChunkRms = 0;
+        this.lastChunkAt = 0;
+    }
+    cleanup() {
+        this.clearQueue();
+        this.isPlaying = false;
+        void this.audioContext?.close();
+        this.analyserNode = null;
+        this.analyserBuffer = null;
+        this.gainNode = null;
+        this.audioContext = null;
+    }
+    ensureContext() {
+        if (!this.audioContext) {
+            this.audioContext = new AudioContext({ sampleRate: this.sampleRate });
+            this.gainNode = this.audioContext.createGain();
+            this.analyserNode = this.audioContext.createAnalyser();
+            this.analyserNode.fftSize = 512;
+            this.analyserBuffer = new Float32Array(this.analyserNode.fftSize);
+            this.gainNode.connect(this.analyserNode);
+            this.analyserNode.connect(this.audioContext.destination);
+            this.playHead = this.audioContext.currentTime;
+        }
+        return this.audioContext;
+    }
+    pipelineQueue() {
+        const ctx = this.audioContext;
+        const gain = this.gainNode;
+        if (!ctx || !gain || !this.isPlaying)
+            return;
+        while (this.queue.length > 0) {
+            const audioBuffer = this.queue.shift();
+            if (!audioBuffer)
+                return;
+            const source = ctx.createBufferSource();
+            source.buffer = audioBuffer;
+            const perSourceGain = ctx.createGain();
+            source.connect(perSourceGain);
+            perSourceGain.connect(gain);
+            const now = ctx.currentTime;
+            const startAt = Math.max((this.playHead || now) - CROSSFADE_SECONDS * 0.75, now + LOOKAHEAD_SECONDS);
+            const duration = audioBuffer.duration;
+            const endAt = startAt + duration;
+            const fade = Math.min(CROSSFADE_SECONDS, duration / 2);
+            perSourceGain.gain.setValueAtTime(0, startAt);
+            perSourceGain.gain.linearRampToValueAtTime(1, startAt + fade);
+            perSourceGain.gain.setValueAtTime(1, endAt - fade);
+            perSourceGain.gain.linearRampToValueAtTime(0, endAt);
+            this.playHead = endAt;
+            this.activeSources.add(source);
+            source.start(startAt);
+            source.onended = () => this.activeSources.delete(source);
+        }
+    }
+}

package/dist/voice/ws/BrowserWsPcmRecorder.d.ts

@@ -0,0 +1,17 @@
+import type { VoiceSession } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+/** getUserMedia only on start() — Berify hold-to-talk aligned. */
+export declare class BrowserWsPcmRecorder {
+    private session;
+    private onRms?;
+    private stream;
+    private audioContext;
+    private processor;
+    private source;
+    private silentGain;
+    bindSession(session: VoiceSession | null): void;
+    setOnRms(handler: (rms: number) => void): void;
+    start(): Promise<void>;
+    stop(): void;
+    cleanup(): void;
+}
+//# sourceMappingURL=BrowserWsPcmRecorder.d.ts.map

package/dist/voice/ws/BrowserWsPcmRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserWsPcmRecorder.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/BrowserWsPcmRecorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAC;AAajF,kEAAkE;AAClE,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,KAAK,CAAC,CAAwB;IACtC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,CAAC,UAAU,CAAyB;IAE3C,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAI/C,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B,IAAI,IAAI,IAAI;IAgBZ,OAAO,IAAI,IAAI;CAIhB"}

package/dist/voice/ws/BrowserWsPcmRecorder.js

@@ -0,0 +1,71 @@
+import { float32ToPcm16 } from './float32ToPcm16';
+import { WS_REALTIME_SAMPLE_RATE } from './wsRealtimeConstants';
+function computeRms(channel) {
+    let sum = 0;
+    for (let i = 0; i < channel.length; i += 1) {
+        const v = channel[i];
+        sum += v * v;
+    }
+    return channel.length > 0 ? Math.sqrt(sum / channel.length) : 0;
+}
+/** getUserMedia only on start() — Berify hold-to-talk aligned. */
+export class BrowserWsPcmRecorder {
+    constructor() {
+        this.session = null;
+        this.stream = null;
+        this.audioContext = null;
+        this.processor = null;
+        this.source = null;
+        this.silentGain = null;
+    }
+    bindSession(session) {
+        this.session = session;
+    }
+    setOnRms(handler) {
+        this.onRms = handler;
+    }
+    async start() {
+        if (this.processor)
+            return;
+        this.stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        const ctx = new AudioContext({ sampleRate: WS_REALTIME_SAMPLE_RATE });
+        this.audioContext = ctx;
+        this.source = ctx.createMediaStreamSource(this.stream);
+        this.processor = ctx.createScriptProcessor(4096, 1, 1);
+        this.silentGain = ctx.createGain();
+        this.silentGain.gain.value = 0;
+        this.source.connect(this.processor);
+        this.processor.connect(this.silentGain);
+        this.silentGain.connect(ctx.destination);
+        this.processor.onaudioprocess = (event) => {
+            if (!this.session?.appendInputAudio)
+                return;
+            const channel = event.inputBuffer.getChannelData(0);
+            const rms = computeRms(channel);
+            this.onRms?.(rms);
+            this.session.appendInputAudio(float32ToPcm16(channel));
+        };
+        if (ctx.state === 'suspended') {
+            await ctx.resume();
+        }
+    }
+    stop() {
+        this.processor?.disconnect();
+        this.source?.disconnect();
+        this.silentGain?.disconnect();
+        this.processor = null;
+        this.source = null;
+        this.silentGain = null;
+        for (const track of this.stream?.getTracks() ?? []) {
+            track.stop();
+        }
+        this.stream = null;
+        void this.audioContext?.close();
+        this.audioContext = null;
+        this.session?.clearInputAudio?.();
+    }
+    cleanup() {
+        this.stop();
+        this.session = null;
+    }
+}

package/dist/voice/ws/float32ToPcm16.d.ts

@@ -0,0 +1,2 @@
+export declare function float32ToPcm16(input: Float32Array): Int16Array;
+//# sourceMappingURL=float32ToPcm16.d.ts.map

package/dist/voice/ws/float32ToPcm16.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"float32ToPcm16.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/float32ToPcm16.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CAO9D"}

package/dist/voice/ws/float32ToPcm16.js

@@ -0,0 +1,8 @@
+export function float32ToPcm16(input) {
+    const out = new Int16Array(input.length);
+    for (let i = 0; i < input.length; i += 1) {
+        const sample = Math.max(-1, Math.min(1, input[i]));
+        out[i] = sample < 0 ? sample * 0x8000 : sample * 0x7fff;
+    }
+    return out;
+}

package/dist/voice/ws/voiceSilenceConstants.d.ts

@@ -0,0 +1,5 @@
+export declare const MIC_SPEECH_RMS_THRESHOLD = 0.008;
+export declare const MIC_BARGE_IN_RMS_THRESHOLD = 0.045;
+export declare const MIC_SILENCE_COMMIT_MS = 400;
+export declare const MIC_SILENCE_POLL_MS = 100;
+//# sourceMappingURL=voiceSilenceConstants.d.ts.map

package/dist/voice/ws/voiceSilenceConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voiceSilenceConstants.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/voiceSilenceConstants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAC9C,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAChD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/voice/ws/voiceSilenceConstants.js

@@ -0,0 +1,4 @@
+export const MIC_SPEECH_RMS_THRESHOLD = 0.008;
+export const MIC_BARGE_IN_RMS_THRESHOLD = 0.045;
+export const MIC_SILENCE_COMMIT_MS = 400;
+export const MIC_SILENCE_POLL_MS = 100;

package/dist/voice/ws/wsRealtimeConstants.d.ts

@@ -0,0 +1,2 @@
+export declare const WS_REALTIME_SAMPLE_RATE = 24000;
+//# sourceMappingURL=wsRealtimeConstants.d.ts.map

package/dist/voice/ws/wsRealtimeConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsRealtimeConstants.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/wsRealtimeConstants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,QAAQ,CAAC"}

package/dist/voice/ws/wsRealtimeConstants.js

@@ -0,0 +1 @@
+export const WS_REALTIME_SAMPLE_RATE = 24000;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@bytexbyte/nxtlinq-ai-agent-ui-react-development",
+  "version": "0.1.1",
+  "description": "Official React Web UI for nxtlinq AI Agent — drop-in chat widget",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "yarn build"
+  },
+  "keywords": [
+    "nxtlinq",
+    "ai-agent",
+    "react",
+    "web",
+    "ui",
+    "chatbot"
+  ],
+  "author": "ByteXByte",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/nxtlinqLLC/nxtlinq/_git/nxtlinq-AI-Agent-SDK",
+    "directory": "packages/ai-agent-ui-react"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@bytexbyte/nxtlinq-ai-agent-core-development": "0.3.8",
+    "@bytexbyte/nxtlinq-ai-agent-web-development": "0.1.1",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^7.2.0",
+    "@mui/material": "^7.2.0",
+    "ethers": "^6.16.0",
+    "fast-json-stable-stringify": "^2.1.0",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@bytexbyte/nxtlinq-ai-agent-core-development": "workspace:^",
+    "@bytexbyte/nxtlinq-ai-agent-web-development": "workspace:^",
+    "@types/react": "^18.2.64",
+    "@types/react-dom": "^18.2.25",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.4.2"
+  }
+}

package/src/NxtlinqAgentChat.tsx

@@ -0,0 +1,79 @@
+import { NxtlinqAgentProvider } from '@bytexbyte/nxtlinq-ai-agent-web-development';
+import React from 'react';
+import { AgentAssistantShell } from './components/AgentAssistantShell';
+import type { NxtlinqAgentChatProps } from './types';
+
+/**
+ * Drop-in React Web assistant UI wired to `@bytexbyte/nxtlinq-ai-agent-web-development`.
+ *
+ * @example
+ * ```tsx
+ * import { NxtlinqAgentChat } from '@bytexbyte/nxtlinq-ai-agent-ui-react-development';
+ *
+ * export default function Page() {
+ *   return (
+ *     <NxtlinqAgentChat
+ *       style={{ height: '100vh' }}
+ *       serviceId="..."
+ *       apiKey="..."
+ *       apiSecret="..."
+ *       environment="staging"
+ *       pseudoId={userId}
+ *       loadHistoryOnMount
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function NxtlinqAgentChat({
+  title,
+  placeholder,
+  presetMessages,
+  loadHistoryOnMount = false,
+  historyLast,
+  enableVoice = true,
+  enableFileUpload = true,
+  startInVoiceMode = false,
+  startWithMicMuted = true,
+  holdMicDuringAssistant = true,
+  theme,
+  style,
+  headerStyle,
+  onMessage,
+  onError,
+  onToolUse,
+  children,
+  fetchImpl,
+  getTimezone,
+  resetOnIdentityChange,
+  ...agentConfig
+}: NxtlinqAgentChatProps): React.ReactElement {
+  return (
+    <NxtlinqAgentProvider
+      fetchImpl={fetchImpl}
+      getTimezone={getTimezone}
+      resetOnIdentityChange={resetOnIdentityChange}
+      onMessage={onMessage}
+      onError={onError}
+      onToolUse={onToolUse}
+      {...agentConfig}
+    >
+      <AgentAssistantShell
+        title={title}
+        placeholder={placeholder}
+        presetMessages={presetMessages}
+        loadHistoryOnMount={loadHistoryOnMount}
+        historyLast={historyLast}
+        enableVoice={enableVoice}
+        enableFileUpload={enableFileUpload}
+        startInVoiceMode={startInVoiceMode}
+        startWithMicMuted={startWithMicMuted}
+        holdMicDuringAssistant={holdMicDuringAssistant}
+        theme={theme}
+        style={style}
+        headerStyle={headerStyle}
+      />
+      {children}
+    </NxtlinqAgentProvider>
+  );
+}

package/src/components/AgentAssistantShell.tsx

@@ -0,0 +1,104 @@
+import React, { useEffect, useRef, useState } from 'react';
+import {
+  AgentAssistantProvider,
+  useAgentAssistant,
+} from '../context/AgentAssistantContext';
+import type { NxtlinqAgentChatProps } from '../types';
+import { AgentComposer } from './AgentComposer';
+import { AgentMessageList } from './AgentMessageList';
+import { AgentRemoteAudio } from './AgentRemoteAudio';
+import { AgentVoiceBar } from './AgentVoiceBar';
+import { PresetMessageChips } from './PresetMessageChips';
+
+export type AgentAssistantShellProps = Pick<
+  NxtlinqAgentChatProps,
+  | 'title'
+  | 'placeholder'
+  | 'presetMessages'
+  | 'enableVoice'
+  | 'enableFileUpload'
+  | 'theme'
+  | 'style'
+  | 'headerStyle'
+  | 'loadHistoryOnMount'
+  | 'historyLast'
+  | 'startInVoiceMode'
+  | 'startWithMicMuted'
+  | 'holdMicDuringAssistant'
+>;
+
+function AgentAssistantInner({
+  title,
+  headerStyle,
+  style,
+  loadHistoryOnMount,
+  historyLast,
+  startInVoiceMode,
+}: AgentAssistantShellProps): React.ReactElement {
+  const { theme, loadHistory, startVoice, isVoiceAvailable } = useAgentAssistant();
+  const [historyReady, setHistoryReady] = useState(!loadHistoryOnMount);
+  const voiceAutoStartRef = useRef(false);
+
+  useEffect(() => {
+    if (loadHistoryOnMount) {
+      void loadHistory({ last: historyLast ?? 50 }).finally(() => setHistoryReady(true));
+    }
+  }, [loadHistory, loadHistoryOnMount, historyLast]);
+
+  useEffect(() => {
+    if (!startInVoiceMode || !isVoiceAvailable || voiceAutoStartRef.current) return;
+    voiceAutoStartRef.current = true;
+    void startVoice();
+  }, [startInVoiceMode, isVoiceAvailable, startVoice]);
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        flex: 1,
+        minHeight: 0,
+        backgroundColor: theme.colors.background,
+        ...style,
+      }}
+    >
+      <header
+        style={{
+          padding: theme.spacing.md,
+          borderBottom: `1px solid ${theme.colors.border}`,
+          backgroundColor: theme.colors.surface,
+          fontSize: theme.typography.titleSize,
+          fontWeight: 600,
+          color: theme.colors.assistantText,
+          ...headerStyle,
+        }}
+      >
+        {title ?? 'AI Assistant'}
+      </header>
+      <PresetMessageChips />
+      {historyReady ? <AgentMessageList /> : <div style={{ flex: 1 }} />}
+      <AgentVoiceBar />
+      <AgentComposer />
+      <AgentRemoteAudio />
+    </div>
+  );
+}
+
+export function AgentAssistantShell(props: AgentAssistantShellProps): React.ReactElement {
+  return (
+    <AgentAssistantProvider
+      ui={{
+        title: props.title,
+        placeholder: props.placeholder,
+        presetMessages: props.presetMessages,
+        enableVoice: props.enableVoice,
+        enableFileUpload: props.enableFileUpload,
+        theme: props.theme,
+        startWithMicMuted: props.startWithMicMuted,
+        holdMicDuringAssistant: props.holdMicDuringAssistant,
+      }}
+    >
+      <AgentAssistantInner {...props} />
+    </AgentAssistantProvider>
+  );
+}