Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Chat): add useXDSChatDictation hook and XDSChatDictationButton (#1314)

Cindy Zhang6a71791271de
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/dictation-lab/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/dictation-lab/page.tsx
new file mode 100644
index 0000000000..7b59527096
--- /dev/null
+++ b/apps/sandbox/src/app/(fullscreen)/pages/dictation-lab/page.tsx
@@ -0,0 +1,682 @@
+'use client';
+
+import {useState, useEffect, useCallback, useRef} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSVStack, XDSHStack} from '@xds/core/Stack';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSCard} from '@xds/core/Card';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSDivider} from '@xds/core/Divider';
+import {XDSBadge} from '@xds/core/Badge';
+import {
+ XDSChatComposer,
+ XDSChatDictationButton,
+ useXDSChatDictation,
+ XDSChatComposerInput,
+} from '@xds/core/Chat';
+import type {XDSChatComposerInputHandle} from '@xds/core/Chat';
+
+// =============================================================================
+// Shared AudioContext — Safari fix
+// Mobile Safari blocks AudioContext created outside user gestures.
+// We lazily create one shared context and reuse it across all tone functions.
+// =============================================================================
+
+let sharedAudioContext: AudioContext | null = null;
+
+function getAudioContext(): AudioContext {
+ if (!sharedAudioContext || sharedAudioContext.state === 'closed') {
+ sharedAudioContext = new AudioContext();
+ }
+ if (sharedAudioContext.state === 'suspended') {
+ sharedAudioContext.resume();
+ }
+ return sharedAudioContext;
+}
+
+// =============================================================================
+// Sound Mixer — Attack Styles × Note Patterns
+// =============================================================================
+
+type AttackStyleDef = {
+ id: string;
+ label: string;
+ waveType: OscillatorType;
+ noteDuration: number;
+ pitchBend: number;
+ attackTime: number;
+ pitchDrop: number;
+ harmonics: Array<{ratio: number; gain: number}>;
+ volumeMultiplier: number;
+ decayCurve: 'fast' | 'slow' | 'resonant';
+};
+
+type NotePatternDef = {
+ id: string;
+ label: string;
+ desc: string;
+ startNotes: Array<{freq: number; delay: number}>;
+ stopNotes: Array<{freq: number; delay: number}>;
+};
+
+function playMixedNotes(
+ notes: Array<{freq: number; delay: number}>,
+ style: AttackStyleDef,
+ volume: number,
+) {
+ const ctx = getAudioContext();
+ const now = ctx.currentTime;
+ notes.forEach(({freq, delay}) => {
+ // Scale duration for low frequencies — bass needs more time to speak.
+ // Below 200Hz, stretch proportionally (e.g. 65Hz gets ~3x the duration).
+ const freqScale = freq < 200 ? Math.max(1, 200 / freq) : 1;
+ const dur = style.noteDuration * Math.min(freqScale, 3);
+ const allHarmonics: Array<{ratio: number; gain: number}> = [
+ {ratio: 1, gain: 1},
+ ...style.harmonics,
+ ];
+ allHarmonics.forEach(({ratio, gain: hGain}) => {
+ const osc = ctx.createOscillator();
+ const gainNode = ctx.createGain();
+ const f = freq * ratio;
+ const v = volume * style.volumeMultiplier * hGain;
+
+ osc.type = style.waveType;
+ osc.frequency.setValueAtTime(f * style.pitchBend, now + delay);
+ osc.frequency.exponentialRampToValueAtTime(
+ f,
+ now + delay + style.attackTime,
+ );
+ if (style.pitchDrop !== 1) {
+ osc.frequency.exponentialRampToValueAtTime(
+ f * style.pitchDrop,
+ now + delay + dur,
+ );
+ }
+
+ gainNode.gain.setValueAtTime(0.001, now);
+ gainNode.gain.setValueAtTime(v, now + delay);
+
+ if (style.decayCurve === 'fast') {
+ gainNode.gain.exponentialRampToValueAtTime(
+ v * 0.2,
+ now + delay + dur * 0.12,
+ );
+ } else if (style.decayCurve === 'slow') {
+ gainNode.gain.exponentialRampToValueAtTime(
+ v * 0.4,
+ now + delay + dur * 0.3,
+ );
+ } else {
+ gainNode.gain.exponentialRampToValueAtTime(
+ v * 0.15,
+ now + delay + dur * 0.1,
+ );
+ }
+ gainNode.gain.exponentialRampToValueAtTime(0.001, now + delay + dur);
+
+ osc.connect(gainNode);
+ gainNode.connect(ctx.destination);
+ osc.start(now + delay);
+ osc.stop(now + delay + dur);
+ });
+ });
+}
+
+const attackStyles: AttackStyleDef[] = [
+ {
+ id: 'drip',
+ label: 'Drip',
+ waveType: 'sine',
+ noteDuration: 0.09,
+ pitchBend: 1.3,
+ attackTime: 0.01,
+ pitchDrop: 0.97,
+ harmonics: [],
+ volumeMultiplier: 1,
+ decayCurve: 'fast',
+ },
+ {
+ id: 'gentle',
+ label: 'Gentle',
+ waveType: 'triangle',
+ noteDuration: 0.2,
+ pitchBend: 1.3,
+ attackTime: 0.01,
+ pitchDrop: 0.97,
+ harmonics: [],
+ volumeMultiplier: 1,
+ decayCurve: 'slow',
+ },
+ {
+ id: 'resonant',
+ label: 'Resonant',
+ waveType: 'sine',
+ noteDuration: 0.25,
+ pitchBend: 1.15,
+ attackTime: 0.008,
+ pitchDrop: 1,
+ harmonics: [{ratio: 2.4, gain: 0.3}],
+ volumeMultiplier: 1,
+ decayCurve: 'resonant',
+ },
+ {
+ id: 'kalimba',
+ label: 'Kalimba',
+ waveType: 'sine',
+ noteDuration: 0.15,
+ pitchBend: 1.15,
+ attackTime: 0.008,
+ pitchDrop: 1,
+ harmonics: [{ratio: 2.4, gain: 0.3}],
+ volumeMultiplier: 1.2,
+ decayCurve: 'resonant',
+ },
+ {
+ id: 'plop',
+ label: 'Plop',
+ waveType: 'sine',
+ noteDuration: 0.06,
+ pitchBend: 1.3,
+ attackTime: 0.01,
+ pitchDrop: 0.93,
+ harmonics: [],
+ volumeMultiplier: 1,
+ decayCurve: 'fast',
+ },
+ {
+ id: 'singing-bowl',
+ label: 'Singing Bowl',
+ waveType: 'sine',
+ noteDuration: 0.4,
+ pitchBend: 1.08,
+ attackTime: 0.01,
+ pitchDrop: 1,
+ harmonics: [{ratio: 2.0, gain: 0.25}],
+ volumeMultiplier: 0.9,
+ decayCurve: 'slow',
+ },
+];
+
+const notePatterns: NotePatternDef[] = [
+ {
+ id: 'v-i',
+ label: 'V \u2192 I',
+ desc: 'G-B-D \u2192 C-E-G \u2014 the classic resolution',
+ startNotes: [
+ {freq: 392, delay: 0},
+ {freq: 494, delay: 0.05},
+ {freq: 587, delay: 0.1},
+ ],
+ stopNotes: [
+ {freq: 523, delay: 0},
+ {freq: 659, delay: 0.05},
+ {freq: 784, delay: 0.1},
+ ],
+ },
+ {
+ id: 'sus4-major',
+ label: 'sus4 \u2192 major',
+ desc: 'C-F-G \u2192 C-E-G \u2014 suspended tension releasing',
+ startNotes: [
+ {freq: 523, delay: 0},
+ {freq: 698, delay: 0.05},
+ {freq: 784, delay: 0.1},
+ ],
+ stopNotes: [
+ {freq: 523, delay: 0},
+ {freq: 659, delay: 0.05},
+ {freq: 784, delay: 0.1},
+ ],
+ },
+ {
+ id: 'dim-major',
+ label: 'dim \u2192 major',
+ desc: 'B-D-F \u2192 C-E-G \u2014 maximum tension to clean',
+ startNotes: [
+ {freq: 494, delay: 0},
+ {freq: 587, delay: 0.05},
+ {freq: 698, delay: 0.1},
+ ],
+ stopNotes: [
+ {freq: 523, delay: 0},
+ {freq: 659, delay: 0.05},
+ {freq: 784, delay: 0.1},
+ ],
+ },
+ {
+ id: 'min-major',
+ label: 'minor \u2192 major',
+ desc: 'C-Eb-G \u2192 C-E-G \u2014 dark to bright',
+ startNotes: [
+ {freq: 523, delay: 0},
+ {freq: 622, delay: 0.05},
+ {freq: 784, delay: 0.1},
+ ],
+ stopNotes: [
+ {freq: 523, delay: 0},
+ {freq: 659, delay: 0.05},
+ {freq: 784, delay: 0.1},
+ ],
+ },
+ {
+ id: 'maj7sharp11',
+ label: 'Cmaj7#11',
+ desc: 'C2-B3-G3-D4-F#4 \u2014 wide voicing, jazz/film tension',
+ startNotes: [
+ {freq: 65.4, delay: 0},
+ {freq: 246.9, delay: 0.04},
+ {freq: 196.0, delay: 0.07},
+ {freq: 293.7, delay: 0.1},
+ {freq: 370.0, delay: 0.13},
+ ],
+ stopNotes: [
+ {freq: 65.4, delay: 0},
+ {freq: 246.9, delay: 0.04},
+ {freq: 164.8, delay: 0.07},
+ {freq: 196.0, delay: 0.1},
+ ],
+ },
+ {
+ id: 'tritone-fifth',
+ label: 'tritone \u2192 fifth',
+ desc: 'F-B \u2192 C-G \u2014 dissonance to consonance',
+ startNotes: [
+ {freq: 349, delay: 0},
+ {freq: 494, delay: 0.06},
+ ],
+ stopNotes: [
+ {freq: 523, delay: 0},
+ {freq: 784, delay: 0.06},
+ ],
+ },
+ {
+ id: 'asc-fourth',
+ label: 'ascending 4th',
+ desc: 'G \u2192 C \u2014 simple doorbell, strong pull',
+ startNotes: [
+ {freq: 392, delay: 0},
+ {freq: 523, delay: 0.07},
+ ],
+ stopNotes: [
+ {freq: 523, delay: 0},
+ {freq: 392, delay: 0.07},
+ ],
+ },
+ {
+ id: 'whole-tone',
+ label: 'whole tone',
+ desc: 'C-D-E \u2192 E-D-C \u2014 rising energy then settling',
+ startNotes: [
+ {freq: 523, delay: 0},
+ {freq: 587, delay: 0.05},
+ {freq: 659, delay: 0.1},
+ ],
+ stopNotes: [
+ {freq: 659, delay: 0},
+ {freq: 587, delay: 0.05},
+ {freq: 523, delay: 0.1},
+ ],
+ },
+ {
+ id: 'triple-asc',
+ label: 'triple ascending',
+ desc: '400-600-850 \u2192 800-550-350',
+ startNotes: [
+ {freq: 400, delay: 0},
+ {freq: 600, delay: 0.05},
+ {freq: 850, delay: 0.1},
+ ],
+ stopNotes: [
+ {freq: 800, delay: 0},
+ {freq: 550, delay: 0.05},
+ {freq: 350, delay: 0.1},
+ ],
+ },
+];
+
+// =============================================================================
+// Sound bars button — volume-reactive bands + hue shift (for Live Demo)
+// =============================================================================
+
+function SoundBarsButton({
+ dictation,
+ size = 'md',
+}: {
+ dictation: ReturnType<typeof useXDSChatDictation>;
+ size?: 'sm' | 'md';
+}) {
+ const {isListening, bands, volume} = dictation;
+ const boosted = Math.min(Math.pow(volume / 0.1, 0.5), 1);
+ const isClipping = volume >= 0.1;
+
+ const hueShift = isClipping ? Math.min((volume - 0.1) / 0.1, 1) * 60 : 0;
+ const barColor = isClipping
+ ? `hsl(calc(var(--accent-hue, 210) + ${hueShift}), 80%, 50%)`
+ : 'var(--color-accent, hsl(210, 80%, 50%))';
+
+ const boostedBands = bands.map(b => Math.min(Math.pow(b / 0.1, 0.5), 1));
+
+ const barCount = 5;
+ const barWidth = size === 'sm' ? 2 : 2.5;
+ const barGap = size === 'sm' ? 1.5 : 2;
+ const barMaxHeight = size === 'sm' ? 14 : 18;
+ const barMinScale = 0.15;
+
+ return (
+ <span
+ style={{
+ position: 'relative',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ }}>
+ {isListening && (
+ <span
+ style={{
+ position: 'absolute',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: barGap,
+ height: barMaxHeight,
+ pointerEvents: 'none',
+ zIndex: 1,
+ }}>
+ {boostedBands.slice(0, barCount).map((level, i) => {
+ const scale = barMinScale + level * (1 - barMinScale);
+ return (
+ <span
+ key={i}
+ style={{
+ width: barWidth,
+ height: '100%',
+ borderRadius: barWidth / 2,
+ backgroundColor: barColor,
+ transformOrigin: 'center',
+ transform: `scaleY(${scale})`,
+ transition:
+ 'transform 0.06s ease-out, background-color 0.15s ease-out',
+ }}
+ />
+ );
+ })}
+ </span>
+ )}
+ <XDSButton
+ label={isListening ? 'Stop dictation' : 'Start dictation'}
+ aria-label={isListening ? 'Stop dictation' : 'Start dictation'}
+ variant="ghost"
+ size={size}
+ icon={
+ isListening ? undefined : <XDSIcon icon="microphone" size={size} />
+ }
+ isIconOnly
+ onClick={dictation.toggle}
+ />
+ </span>
+ );
+}
+
+// =============================================================================
+// Page-level styles
+// =============================================================================
+
+const pageStyles = stylex.create({
+ variantCell: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ gap: '8px',
+ padding: '16px',
+ cursor: 'pointer',
+ borderRadius: '8px',
+ },
+});
+
+// =============================================================================
+// Page
+// =============================================================================
+
+export default function DictationLabPage() {
+ const [volume, setVolume] = useState(0.25);
+ const [messages, setMessages] = useState<string[]>([]);
+ const [selectedAttack, setSelectedAttack] = useState('drip');
+ const [selectedPattern, setSelectedPattern] = useState('v-i');
+ const inputRef = useRef<XDSChatComposerInputHandle>(null);
+
+ const dictation = useXDSChatDictation({
+ inputRef,
+ hasSounds: true,
+ onResult: text => {
+ console.log('Final:', text);
+ },
+ });
+
+ const handleSubmit = useCallback((value: string) => {
+ setMessages(prev => [...prev, value]);
+ }, []);
+
+ // Simulated volume for each visual variant
+
+ return (
+ <div style={{maxWidth: 800, margin: '0 auto', padding: 32}}>
+ <XDSVStack gap={6}>
+ <XDSVStack gap={2}>
+ <XDSHeading level={2}>Dictation Lab</XDSHeading>
+ <XDSText type="body" color="secondary">
+ Test voice dictation, tune sound effects, and explore animation
+ variants.
+ </XDSText>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* ---- Live Demo ---- */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={3}>Live Demo</XDSHeading>
+ <XDSText type="supporting" color="secondary">
+ Click the mic button to start dictating. Speak naturally — the
+ volume ring reacts to your voice.
+ </XDSText>
+
+ {messages.length > 0 && (
+ <XDSCard>
+ <XDSVStack gap={2} style={{padding: 12}}>
+ {messages.map((msg, i) => (
+ <XDSText type="body" key={i}>
+ {msg}
+ </XDSText>
+ ))}
+ </XDSVStack>
+ </XDSCard>
+ )}
+
+ <XDSChatComposer
+ onSubmit={handleSubmit}
+ input={<XDSChatComposerInput ref={inputRef} />}
+ sendActions={<XDSChatDictationButton dictation={dictation} />}
+ />
+
+ {dictation.isListening && (
+ <XDSHStack gap={3} vAlign="center">
+ <XDSBadge label="Listening" variant="red" />
+ <div
+ style={{
+ flex: 1,
+ height: 6,
+ backgroundColor: 'var(--color-background-muted, #eee)',
+ borderRadius: 3,
+ overflow: 'hidden',
+ }}>
+ <div
+ style={{
+ height: '100%',
+ backgroundColor:
+ dictation.volume > 0.1
+ ? `hsl(calc(var(--accent-hue, 210) + ${Math.min((dictation.volume - 0.1) / 0.1, 1) * 60}), 80%, 50%)`
+ : 'var(--color-success, #22c55e)',
+ borderRadius: 3,
+ transition: 'width 0.08s ease-out',
+ width: `${Math.min(dictation.volume * 200, 100)}%`,
+ }}
+ />
+ </div>
+ <XDSText
+ type="supporting"
+ style={{fontFamily: 'monospace', minWidth: 40}}>
+ {dictation.volume.toFixed(2)}
+ </XDSText>
+ </XDSHStack>
+ )}
+
+ {/* Debug: Raw vs Calibrated bands */}
+ {dictation.isListening && (
+ <XDSVStack gap={1}>
+ <XDSText type="supporting" weight="semibold">Band Debug (raw vs calibrated)</XDSText>
+ <div style={{display: 'flex', gap: 8, fontFamily: 'monospace', fontSize: 11}}>
+ {['170-340', '340-860', '860-1.7k', '1.7-3k', '3k+'].map((label, i) => {
+ const raw = dictation.rawBands[i] ?? 0;
+ const clean = dictation.bands[i] ?? 0;
+ const barH = 40;
+ return (
+ <div key={label} style={{display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 2, flex: 1}}>
+ <div style={{display: 'flex', gap: 2, alignItems: 'flex-end', height: barH}}>
+ <div style={{
+ width: 8, backgroundColor: 'rgba(200,200,200,0.5)',
+ height: Math.min(raw * barH * 5, barH), borderRadius: 2,
+ }} />
+ <div style={{
+ width: 8, backgroundColor: 'var(--color-accent, hsl(210, 80%, 50%))',
+ height: Math.min(clean * barH * 5, barH), borderRadius: 2,
+ }} />
+ </div>
+ <span style={{opacity: 0.5, fontSize: 9}}>{label}</span>
+ <span style={{opacity: 0.4}}>r:{raw.toFixed(3)}</span>
+ <span style={{color: 'var(--color-accent, hsl(210, 80%, 50%))'}}>c:{clean.toFixed(3)}</span>
+ </div>
+ );
+ })}
+ </div>
+ <XDSText type="supporting" color="disabled">
+ Gray = raw mic input, Blue = after noise floor subtraction
+ </XDSText>
+ </XDSVStack>
+ )}
+
+ <XDSHStack gap={2} vAlign="center">
+ <XDSText type="supporting" color="secondary">
+ Sound bars variant:
+ </XDSText>
+ <SoundBarsButton dictation={dictation} />
+ </XDSHStack>
+
+ {!dictation.isSupported && (
+ <XDSBadge
+ label="SpeechRecognition not supported in this browser"
+ variant="yellow"
+ />
+ )}
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* ---- Sound Mixer ---- */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={3}>Sound Mixer</XDSHeading>
+ <XDSText type="supporting" color="secondary">
+ Combine any attack style with any note pattern. All synthesized — no
+ audio files.
+ </XDSText>
+
+ <XDSHStack gap={3} vAlign="center">
+ <XDSText type="supporting">Volume</XDSText>
+ <input
+ type="range"
+ min={0.05}
+ max={0.5}
+ step={0.01}
+ value={volume}
+ onChange={e => setVolume(parseFloat(e.target.value))}
+ style={{flex: 1, maxWidth: 200}}
+ />
+ <XDSText
+ type="supporting"
+ style={{fontFamily: 'monospace', minWidth: 40}}>
+ {volume.toFixed(2)}
+ </XDSText>
+ </XDSHStack>
+
+ <XDSVStack gap={1}>
+ <XDSText type="label">Attack Style</XDSText>
+ <XDSHStack gap={1} wrap="wrap">
+ {attackStyles.map(s => (
+ <XDSButton
+ key={s.id}
+ label={s.label}
+ variant={selectedAttack === s.id ? 'primary' : 'ghost'}
+ size="sm"
+ onClick={() => setSelectedAttack(s.id)}
+ />
+ ))}
+ </XDSHStack>
+ </XDSVStack>
+
+ <XDSVStack gap={1}>
+ <XDSText type="label">Note Pattern</XDSText>
+ <XDSHStack gap={1} wrap="wrap">
+ {notePatterns.map(p => (
+ <XDSButton
+ key={p.id}
+ label={p.label}
+ variant={selectedPattern === p.id ? 'primary' : 'ghost'}
+ size="sm"
+ onClick={() => setSelectedPattern(p.id)}
+ />
+ ))}
+ </XDSHStack>
+ </XDSVStack>
+
+ <XDSHStack gap={3} vAlign="center">
+ <XDSText type="body" weight="medium">
+ {attackStyles.find(s => s.id === selectedAttack)?.label}
+ {' \u00d7 '}
+ {notePatterns.find(p => p.id === selectedPattern)?.label}
+ </XDSText>
+ <XDSButton
+ label="Preview Start"
+ variant="secondary"
+ size="sm"
+ onClick={() => {
+ const style = attackStyles.find(s => s.id === selectedAttack);
+ const pattern = notePatterns.find(
+ p => p.id === selectedPattern,
+ );
+ if (style && pattern)
+ playMixedNotes(pattern.startNotes, style, volume);
+ }}
+ />
+ <XDSButton
+ label="Preview Stop"
+ variant="ghost"
+ size="sm"
+ onClick={() => {
+ const style = attackStyles.find(s => s.id === selectedAttack);
+ const pattern = notePatterns.find(
+ p => p.id === selectedPattern,
+ );
+ if (style && pattern)
+ playMixedNotes(pattern.stopNotes, style, volume);
+ }}
+ />
+ </XDSHStack>
+
+ <XDSText type="supporting" color="secondary">
+ {notePatterns.find(p => p.id === selectedPattern)?.desc}
+ </XDSText>
+ </XDSVStack>
+ </XDSVStack>
+ </div>
+ );
+}
diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.ts
index fb3d2b4aa9..eccff5a00c 100644
--- a/apps/sandbox/src/app/sandboxPages.ts
+++ b/apps/sandbox/src/app/sandboxPages.ts
@@ -150,6 +150,12 @@ export const categories: SandboxCategory[] = [
description:
'Compare luminance algorithms (BT.709 / WCAG 2 / APCA) for dark/light surface detection',
},
+ {
+ name: 'Dictation Lab',
+ href: '/pages/dictation-lab/',
+ description:
+ 'Test voice dictation, tune sound effects, and explore animation',
+ },
],
},
];
diff --git a/apps/storybook/stories/ChatDictation.stories.tsx b/apps/storybook/stories/ChatDictation.stories.tsx
new file mode 100644
index 0000000000..368482a6fd
--- /dev/null
+++ b/apps/storybook/stories/ChatDictation.stories.tsx
@@ -0,0 +1,256 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSChatDictationButton,
+ XDSChatComposer,
+ useXDSChatDictation,
+ XDSChatComposerInput,
+} from '@xds/core/Chat';
+import type {XDSChatComposerInputHandle} from '@xds/core/Chat';
+import type {UseSpeechRecognitionReturn} from '@xds/core/Chat';
+import {useState, useRef} from 'react';
+
+// =============================================================================
+// Mock dictation values for non-interactive stories
+// =============================================================================
+
+const idleDictation: UseSpeechRecognitionReturn = {
+ volume: 0,
+ rawBands: [0, 0, 0, 0, 0],
+ bands: [0, 0, 0, 0, 0],
+ isSupported: true,
+ isListening: false,
+ isSpeaking: false,
+ interimTranscript: '',
+ start: () => {},
+ stop: () => {},
+ abort: () => {},
+ toggle: () => {},
+};
+
+const listeningDictation: UseSpeechRecognitionReturn = {
+ volume: 0.05,
+ rawBands: [0.08, 0.06, 0.04, 0.02, 0.01],
+ bands: [0.08, 0.06, 0.04, 0.02, 0.01],
+ isSupported: true,
+ isListening: true,
+ isSpeaking: false,
+ interimTranscript: '',
+ start: () => {},
+ stop: () => {},
+ abort: () => {},
+ toggle: () => {},
+};
+
+const speakingDictation: UseSpeechRecognitionReturn = {
+ volume: 0.12,
+ rawBands: [0.15, 0.12, 0.08, 0.05, 0.02],
+ bands: [0.15, 0.12, 0.08, 0.05, 0.02],
+ isSupported: true,
+ isListening: true,
+ isSpeaking: true,
+ interimTranscript: 'hello world',
+ start: () => {},
+ stop: () => {},
+ abort: () => {},
+ toggle: () => {},
+};
+
+const unsupportedDictation: UseSpeechRecognitionReturn = {
+ volume: 0,
+ rawBands: [0, 0, 0, 0, 0],
+ bands: [0, 0, 0, 0, 0],
+ isSupported: false,
+ isListening: false,
+ isSpeaking: false,
+ interimTranscript: '',
+ start: () => {},
+ stop: () => {},
+ abort: () => {},
+ toggle: () => {},
+};
+
+// =============================================================================
+// Meta
+// =============================================================================
+
+const meta: Meta<typeof XDSChatDictationButton> = {
+ title: 'Chat/XDSChatDictationButton',
+ component: XDSChatDictationButton,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'centered',
+ },
+ decorators: [
+ Story => (
+ <div style={{width: 600, padding: 40}}>
+ <Story />
+ </div>
+ ),
+ ],
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSChatDictationButton>;
+
+// =============================================================================
+// Stories
+// =============================================================================
+
+/** Idle state — microphone icon, ready to start dictation */
+export const Idle: Story = {
+ render: () => <XDSChatDictationButton dictation={idleDictation} />,
+};
+
+/** Listening state — pulsing red record indicator */
+export const Listening: Story = {
+ render: () => <XDSChatDictationButton dictation={listeningDictation} />,
+};
+
+/** Speaking state — more intense pulse while speech is detected */
+export const Speaking: Story = {
+ render: () => <XDSChatDictationButton dictation={speakingDictation} />,
+};
+
+/** Unsupported browser — button hidden by default */
+export const Unsupported: Story = {
+ render: () => (
+ <div>
+ <p style={{marginBottom: 8}}>
+ Button is hidden when unsupported (nothing below):
+ </p>
+ <XDSChatDictationButton dictation={unsupportedDictation} />
+ </div>
+ ),
+};
+
+/** Unsupported browser — button visible when isHiddenWhenUnsupported is false */
+export const UnsupportedVisible: Story = {
+ render: () => (
+ <XDSChatDictationButton
+ dictation={unsupportedDictation}
+ isHiddenWhenUnsupported={false}
+ />
+ ),
+};
+
+/** Dictation button in sendActions slot of XDSChatComposer */
+export const InSendActions: Story = {
+ render: () => (
+ <XDSChatComposer
+ onSubmit={value => console.log('Submit:', value)}
+ sendActions={<XDSChatDictationButton dictation={idleDictation} />}
+ />
+ ),
+};
+
+/** Dictation button replacing the send button */
+export const AsSendButton: Story = {
+ render: () => (
+ <XDSChatComposer
+ onSubmit={value => console.log('Submit:', value)}
+ sendButton={<XDSChatDictationButton dictation={listeningDictation} />}
+ />
+ ),
+};
+
+/**
+ * Interactive demo with real SpeechRecognition.
+ *
+ * Note: SpeechRecognition may not work in Storybook's iframe.
+ * For full testing, open this story in a standalone browser tab.
+ */
+export const Interactive: Story = {
+ render: () => {
+ const inputRef = useRef<XDSChatComposerInputHandle>(null);
+
+ const dictation = useXDSChatDictation({
+ inputRef,
+ hasSounds: true,
+ onResult: text => {
+ console.log('Final:', text);
+ },
+ });
+
+ return (
+ <div>
+ <XDSChatComposer
+ onSubmit={v => {
+ console.log('Submit:', v);
+ }}
+ input={<XDSChatComposerInput ref={inputRef} />}
+ sendActions={<XDSChatDictationButton dictation={dictation} />}
+ />
+ {dictation.isListening && (
+ <div
+ style={{
+ marginTop: 8,
+ display: 'flex',
+ alignItems: 'center',
+ gap: 8,
+ }}>
+ <span style={{fontSize: 12, opacity: 0.5}}>Volume:</span>
+ <div
+ style={{
+ width: 120,
+ height: 8,
+ backgroundColor: '#eee',
+ borderRadius: 4,
+ overflow: 'hidden',
+ }}>
+ <div
+ style={{
+ height: '100%',
+ backgroundColor:
+ dictation.volume > 0.3 ? '#ef4444' : '#22c55e',
+ borderRadius: 4,
+ transition: 'width 0.08s ease-out',
+ width: `${Math.min(dictation.volume * 100 * 2, 100)}%`,
+ }}
+ />
+ </div>
+ <span style={{fontSize: 12, fontFamily: 'monospace', opacity: 0.5}}>
+ {dictation.volume.toFixed(2)}
+ </span>
+ </div>
+ )}
+
+ {dictation.isListening && (
+ <div style={{marginTop: 12}}>
+ <div style={{fontSize: 12, fontWeight: 600, marginBottom: 4}}>Band Debug (raw vs calibrated)</div>
+ <div style={{display: 'flex', gap: 8, fontFamily: 'monospace', fontSize: 11}}>
+ {['170-340', '340-860', '860-1.7k', '1.7-3k', '3k+'].map((label, i) => {
+ const raw = dictation.rawBands[i] ?? 0;
+ const clean = dictation.bands[i] ?? 0;
+ const barH = 40;
+ return (
+ <div key={label} style={{display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 2, flex: 1}}>
+ <div style={{display: 'flex', gap: 2, alignItems: 'flex-end', height: barH}}>
+ <div style={{
+ width: 8, backgroundColor: 'rgba(200,200,200,0.5)',
+ height: Math.min(raw * barH * 5, barH), borderRadius: 2,
+ }} />
+ <div style={{
+ width: 8, backgroundColor: '#3b82f6',
+ height: Math.min(clean * barH * 5, barH), borderRadius: 2,
+ }} />
+ </div>
+ <span style={{opacity: 0.5, fontSize: 9}}>{label}</span>
+ <span style={{opacity: 0.4}}>r:{raw.toFixed(3)}</span>
+ <span style={{color: '#3b82f6'}}>c:{clean.toFixed(3)}</span>
+ </div>
+ );
+ })}
+ </div>
+ <div style={{fontSize: 10, opacity: 0.4, marginTop: 4}}>Gray = raw mic, Blue = after noise floor</div>
+ </div>
+ )}
+
+ {!dictation.isSupported && (
+ <p style={{marginTop: 8, color: 'red'}}>
+ SpeechRecognition is not supported in this browser.
+ </p>
+ )}
+ </div>
+ );
+ },
+};
diff --git a/packages/core/src/Chat/XDSChatComposerInput.tsx b/packages/core/src/Chat/XDSChatComposerInput.tsx
index ed408ff1e6..0fd4c998f4 100644
--- a/packages/core/src/Chat/XDSChatComposerInput.tsx
+++ b/packages/core/src/Chat/XDSChatComposerInput.tsx
@@ -41,9 +41,15 @@ import {
} from '../theme/tokens.stylex';
import {xdsClassName, mergeProps} from '../utils';
import {useTriggerMenu} from './useTriggerMenu';
-import {useXDSChatComposerTokens, isCustomToken} from './useXDSChatComposerTokens';
+import {
+ useXDSChatComposerTokens,
+ isCustomToken,
+} from './useXDSChatComposerTokens';
import {XDSChatPastedTextToken} from './XDSChatPastedTextToken';
-import {useXDSChatPasteAsToken, type UseXDSChatPasteAsTokenReturn} from './useXDSChatPasteAsToken';
+import {
+ useXDSChatPasteAsToken,
+ type UseXDSChatPasteAsTokenReturn,
+} from './useXDSChatPasteAsToken';
import {XDSBadge, type XDSBadgeProps} from '../Badge';
import {useXDSChatComposerContext} from './XDSChatContext';
@@ -54,7 +60,9 @@ import {useXDSChatComposerContext} from './XDSChatContext';
/** Imperative handle exposed by XDSChatComposerInput via ref */
export interface XDSChatComposerInputHandle {
/** Insert a token (badge chip) at the current cursor position */
- insertToken: (token: XDSChatComposerToken) => void;
+ insertToken: (token: XDSChatComposerToken) => string | undefined;
+ /** Expand a token — replace the token span with its serialized text value */
+ expandToken: (id: string) => void;
/** Insert plain text at the current cursor position */
insertText: (text: string) => void;
/** Focus the input */
@@ -163,7 +171,10 @@ export interface XDSChatComposerInputProps extends Omit<
/** Disabled state. @default false */
isDisabled?: boolean;
/** Paste handler. Called with the plain text before insertion. Return true to handle the paste yourself (e.g. insert a token instead). */
- onPaste?: (event: ClipboardEvent<HTMLDivElement>, text: string) => boolean | void;
+ onPaste?: (
+ event: ClipboardEvent<HTMLDivElement>,
+ text: string,
+ ) => boolean | void;
/**
* Paste-as-token behavior. Defaults to converting pastes over 200 chars
* into token chips. Pass a custom useXDSChatPasteAsToken result to override,
@@ -306,14 +317,16 @@ export function XDSChatComposerInput(props: XDSChatComposerInputProps) {
const currentDraftRef = useRef('');
// Stable refs for imperative handle callbacks (avoid re-creating handle on every render)
- const insertTokenRef = useRef<(token: XDSChatComposerToken) => void>(
- () => {},
- );
+ const insertTokenRef = useRef<
+ (token: XDSChatComposerToken) => string | undefined
+ >(() => undefined);
const insertTextRef = useRef<(text: string) => void>(() => {});
useImperativeHandle(ref, () => {
const h: XDSChatComposerInputHandle = {
- insertToken: (token: XDSChatComposerToken) => insertTokenRef.current(token),
+ insertToken: (token: XDSChatComposerToken) =>
+ insertTokenRef.current(token),
+ expandToken: (id: string) => tokens.expandToken(id),
insertText: (text: string) => insertTextRef.current(text),
focus: () => editableRef.current?.focus(),
getValue: () =>
@@ -338,19 +351,28 @@ export function XDSChatComposerInput(props: XDSChatComposerInputProps) {
const text = serialize(editableRef.current);
// Browsers may leave a trailing <br> when all content is deleted,
// which serializes to "\n". Treat whitespace-only as empty.
- setIsEmpty(text.trim().length === 0);
- onChange?.(text);
+ const hasTokens =
+ editableRef.current.querySelector(
+ '[data-xds-token], [data-xds-dictation-interim]',
+ ) != null;
+ const trimmedEmpty = text.trim().length === 0 && !hasTokens;
+ setIsEmpty(trimmedEmpty);
+ onChange?.(trimmedEmpty ? '' : text);
tokens.cleanupPortals();
}, [onChange]);
// --- Token management (via hook) ---
- const tokens = useXDSChatComposerTokens({editableRef, onEmitChange: emitChange});
+ const tokens = useXDSChatComposerTokens({
+ editableRef,
+ onEmitChange: emitChange,
+ });
// --- Paste-as-token (internal default) ---
const defaultPasteAsToken = useXDSChatPasteAsToken({inputRef: selfRef});
- const pasteAsToken: UseXDSChatPasteAsTokenReturn | null = pasteAsTokenProp === false
- ? null
- : (pasteAsTokenProp ?? defaultPasteAsToken);
+ const pasteAsToken: UseXDSChatPasteAsTokenReturn | null =
+ pasteAsTokenProp === false
+ ? null
+ : (pasteAsTokenProp ?? defaultPasteAsToken);
const insertText = useCallback((text: string) => {
insertTextAtCursor(text);
@@ -548,27 +570,30 @@ export function XDSChatComposerInput(props: XDSChatComposerInputProps) {
style={{maxHeight: `${maxHeight}px`}}
/>
{triggerMenu.renderMenu()}
- {tokens.tokenPortals.map(({id, span, token}) =>
- createPortal(
- isCustomToken(token) ? (
- <span key={id}>{token.render()}</span>
- ) : token.value.length > (pasteAsToken === null ? Infinity : 200) ? (
- <XDSChatPastedTextToken
- key={id}
- text={token.value}
- onExpand={() => tokens.expandToken(id)}
- />
- ) : (
- <XDSBadge
- key={id}
- label={token.label}
- variant={token.variant}
- icon={token.icon}
- />
+ {tokens.tokenPortals
+ .filter(({span}) => span.isConnected)
+ .map(({id, span, token}) =>
+ createPortal(
+ isCustomToken(token) ? (
+ <span key={id}>{token.render()}</span>
+ ) : token.value.length >
+ (pasteAsToken === null ? Infinity : 200) ? (
+ <XDSChatPastedTextToken
+ key={id}
+ text={token.value}
+ onExpand={() => tokens.expandToken(id)}
+ />
+ ) : (
+ <XDSBadge
+ key={id}
+ label={token.label}
+ variant={token.variant}
+ icon={token.icon}
+ />
+ ),
+ span,
),
- span,
- ),
- )}
+ )}
</div>
);
}
diff --git a/packages/core/src/Chat/XDSChatDictationButton.tsx b/packages/core/src/Chat/XDSChatDictationButton.tsx
new file mode 100644
index 0000000000..14fbed32a0
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatDictationButton.tsx
@@ -0,0 +1,153 @@
+'use client';
+
+/**
+ * @file XDSChatDictationButton.tsx
+ * @input Uses React, StyleX, XDSButton, XDSIcon, useXDSChatDictation return
+ * @output Exports XDSChatDictationButton for voice input in chat composer
+ * @position UI component — renders in sendActions slot of XDSChatComposer
+ *
+ * A toggle button that connects to useXDSChatDictation. Shows a microphone
+ * icon when idle. When listening, replaces the icon with volume-reactive
+ * frequency bars (equalizer style) that respond to real mic input.
+ * Bars use the accent color and hue-shift when volume clips past 10%.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Chat/index.ts (exports)
+ */
+
+import type {UseSpeechRecognitionReturn} from './useSpeechRecognition';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {colorVars, radiusVars} from '../theme/tokens.stylex';
+import {XDSButton} from '../Button';
+import {XDSIcon} from '../Icon';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSChatDictationButtonProps {
+ /** The return value from useXDSChatDictation or useSpeechRecognition. */
+ dictation: UseSpeechRecognitionReturn;
+ /** Button size. @default "md" */
+ size?: 'sm' | 'md';
+ /** Hide the button when SpeechRecognition is not supported. @default true */
+ isHiddenWhenUnsupported?: boolean;
+ /** Accessible label override. */
+ label?: string;
+ /** Additional StyleX styles. */
+ xstyle?: StyleXStyles;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ wrapper: {
+ position: 'relative',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ },
+ barsContainer: {
+ position: 'absolute',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ pointerEvents: 'none',
+ zIndex: 1,
+ },
+ bar: {
+ borderRadius: radiusVars['--radius-full'],
+ transformOrigin: 'center',
+ transitionProperty: 'transform, background-color',
+ transitionDuration: '0.06s',
+ transitionTimingFunction: 'ease-out',
+ },
+});
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const BAR_COUNT = 5;
+const BAR_MIN_SCALE = 0.08;
+
+const SIZE_CONFIG = {
+ sm: {barWidth: 2, barGap: 1.5, barMaxHeight: 14},
+ md: {barWidth: 2.5, barGap: 2, barMaxHeight: 18},
+};
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function XDSChatDictationButton({
+ dictation,
+ size = 'md',
+ isHiddenWhenUnsupported = true,
+ label,
+ xstyle,
+}: XDSChatDictationButtonProps) {
+ if (isHiddenWhenUnsupported && !dictation.isSupported) {
+ return null;
+ }
+
+ const {isListening, bands, volume: rawVolume} = dictation;
+ const accessibleLabel =
+ label ?? (isListening ? 'Stop dictation' : 'Start dictation');
+
+ // Boost each band for visibility — quiet speech (0-10%) maps to full visual range
+ const boostedBands = bands.map(b => Math.min(Math.pow(b / 0.2, 0.5), 1));
+
+ // Hue shift from accent color when volume clips past 10%
+ const isClipping = rawVolume >= 0.2;
+ const hueShift = isClipping ? Math.min((rawVolume - 0.2) / 0.1, 1) * 60 : 0;
+
+ const barColor = isClipping
+ ? `hsl(calc(var(--accent-hue, 210) + ${hueShift}), 80%, 50%)`
+ : `var(--color-accent, ${colorVars['--color-accent']})`;
+
+ const {barWidth, barGap, barMaxHeight} = SIZE_CONFIG[size];
+
+ return (
+ <span {...stylex.props(styles.wrapper, xstyle)}>
+ {isListening && (
+ <span
+ aria-hidden
+ {...stylex.props(styles.barsContainer)}
+ style={{gap: barGap, height: barMaxHeight}}>
+ {boostedBands.slice(0, BAR_COUNT).map((level, i) => {
+ const scale = BAR_MIN_SCALE + level * (1 - BAR_MIN_SCALE);
+ return (
+ <span
+ key={i}
+ {...stylex.props(styles.bar)}
+ style={{
+ width: barWidth,
+ height: '100%',
+ backgroundColor: barColor,
+ transform: `scaleY(${scale})`,
+ }}
+ />
+ );
+ })}
+ </span>
+ )}
+ <XDSButton
+ label={accessibleLabel}
+ aria-label={accessibleLabel}
+ variant="ghost"
+ size={size}
+ icon={
+ isListening ? undefined : <XDSIcon icon="microphone" size={size} />
+ }
+ isIconOnly
+ onClick={dictation.toggle}
+ />
+ </span>
+ );
+}
+
+XDSChatDictationButton.displayName = 'XDSChatDictationButton';
diff --git a/packages/core/src/Chat/index.ts b/packages/core/src/Chat/index.ts
index 8073dab43c..427332427b 100644
--- a/packages/core/src/Chat/index.ts
+++ b/packages/core/src/Chat/index.ts
@@ -94,3 +94,18 @@ export {XDSChatLayout} from './XDSChatLayout';
export {XDSChatLayoutScrollButton} from './XDSChatLayoutScrollButton';
export type {XDSChatLayoutScrollButtonProps} from './XDSChatLayoutScrollButton';
export type {XDSChatLayoutProps} from './XDSChatLayout';
+
+export {useSpeechRecognition} from './useSpeechRecognition';
+export type {
+ UseSpeechRecognitionOptions,
+ UseSpeechRecognitionReturn,
+} from './useSpeechRecognition';
+
+export {useXDSChatDictation} from './useXDSChatDictation';
+export type {
+ UseXDSChatDictationOptions,
+ UseXDSChatDictationReturn,
+} from './useXDSChatDictation';
+
+export {XDSChatDictationButton} from './XDSChatDictationButton';
+export type {XDSChatDictationButtonProps} from './XDSChatDictationButton';
diff --git a/packages/core/src/Chat/useSpeechRecognition.ts b/packages/core/src/Chat/useSpeechRecognition.ts
new file mode 100644
index 0000000000..cd67338f65
--- /dev/null
+++ b/packages/core/src/Chat/useSpeechRecognition.ts
@@ -0,0 +1,383 @@
+'use client';
+
+/**
+ * @file useSpeechRecognition.ts
+ * @input Uses React hooks, browser SpeechRecognition API, AudioContext
+ * @output Exports useSpeechRecognition hook — pure utility for voice-to-text
+ * @position Utility hook — framework-agnostic SpeechRecognition wrapper
+ *
+ * Wraps the browser SpeechRecognition API in a headless React hook,
+ * providing start/stop/toggle controls, transcript state, and real-time
+ * volume level from the microphone via AudioContext analyser.
+ */
+
+import {useState, useCallback, useEffect, useRef} from 'react';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface UseSpeechRecognitionOptions {
+ /** BCP-47 language tag. @default navigator.language */
+ lang?: string;
+ /** Whether recognition continues until explicitly stopped. @default true */
+ continuous?: boolean;
+ /** Whether interim results are reported. @default true */
+ interimResults?: boolean;
+ /** Shared AudioContext — uses an internal lazy singleton by default. */
+ audioContext?: AudioContext;
+ /** Transform transcript text before reporting. */
+ transformTranscript?: (text: string) => string;
+ /** Called on each transcript result (interim or final). */
+ onTranscript?: (transcript: string, isFinal: boolean) => void;
+ /** Called when a final result is produced. */
+ onResult?: (transcript: string) => void;
+ /** Called when a recognition error occurs. */
+ onError?: (error: {error: string; message?: string}) => void;
+ /** Called when recognition starts. */
+ onStart?: () => void;
+ /** Called when recognition ends. */
+ onEnd?: () => void;
+}
+
+export interface UseSpeechRecognitionReturn {
+ /** Whether the browser supports SpeechRecognition. */
+ isSupported: boolean;
+ /** Whether recognition is currently active. */
+ isListening: boolean;
+ /** Whether speech is currently being detected. */
+ isSpeaking: boolean;
+ /** Real-time microphone volume level, 0 to 1. */
+ volume: number;
+ /** Frequency band levels (low to high), each 0-1. */
+ bands: number[];
+ /** Raw (uncalibrated) band levels for debugging. */
+ rawBands: number[];
+ /** The current interim transcript text. */
+ interimTranscript: string;
+ /** Start speech recognition. */
+ start: () => void;
+ /** Stop speech recognition gracefully. */
+ stop: () => void;
+ /** Abort speech recognition immediately. */
+ abort: () => void;
+ /** Toggle between start and stop. */
+ toggle: () => void;
+}
+
+// =============================================================================
+// SpeechRecognition type shim
+// =============================================================================
+
+type SpeechRecognitionInstance = {
+ lang: string;
+ continuous: boolean;
+ interimResults: boolean;
+ start: () => void;
+ stop: () => void;
+ abort: () => void;
+ onstart: (() => void) | null;
+ onend: (() => void) | null;
+ onresult: ((event: SpeechRecognitionEvent) => void) | null;
+ onspeechstart: (() => void) | null;
+ onspeechend: (() => void) | null;
+ onerror: ((event: {error: string; message?: string}) => void) | null;
+ onnomatch: (() => void) | null;
+};
+
+type SpeechRecognitionEvent = {
+ resultIndex: number;
+ results: {
+ length: number;
+ [index: number]: {
+ isFinal: boolean;
+ length: number;
+ [index: number]: {transcript: string};
+ };
+ };
+};
+
+type SpeechRecognitionConstructor = new () => SpeechRecognitionInstance;
+
+function getSpeechRecognition(): SpeechRecognitionConstructor | null {
+ if (typeof window === 'undefined') return null;
+ return (
+ (window as unknown as {SpeechRecognition?: SpeechRecognitionConstructor})
+ .SpeechRecognition ??
+ (
+ window as unknown as {
+ webkitSpeechRecognition?: SpeechRecognitionConstructor;
+ }
+ ).webkitSpeechRecognition ??
+ null
+ );
+}
+
+// =============================================================================
+// Volume analyser
+// =============================================================================
+
+interface VolumeAnalyser {
+ calibrate: () => void;
+ getVolume: () => number;
+ getBands: (count: number) => number[];
+ getRawBands: (count: number) => number[];
+ cleanup: () => void;
+}
+
+async function createVolumeAnalyser(
+ getCtx: () => AudioContext,
+): Promise<VolumeAnalyser | null> {
+ try {
+ const stream = await navigator.mediaDevices.getUserMedia({audio: true});
+ const audioContext = getCtx();
+ const source = audioContext.createMediaStreamSource(stream);
+ const analyser = audioContext.createAnalyser();
+ analyser.fftSize = 256;
+ analyser.smoothingTimeConstant = 0.5;
+ source.connect(analyser);
+
+ const dataArray = new Uint8Array(analyser.frequencyBinCount);
+ const noiseFloor = new Float32Array(analyser.frequencyBinCount);
+ let calibrationSamples = 0;
+ const CALIBRATION_FRAMES = 60;
+
+ function calibrate() {
+ analyser.getByteFrequencyData(dataArray);
+ calibrationSamples++;
+ for (let i = 0; i < dataArray.length; i++) {
+ const val = dataArray[i] / 255;
+ if (val > noiseFloor[i]) noiseFloor[i] = val;
+ }
+ }
+
+ function getCleanBin(i: number): number {
+ const raw = dataArray[i] / 255;
+ if (calibrationSamples < CALIBRATION_FRAMES) return 0;
+ return Math.max(0, raw - noiseFloor[i] * 1.1);
+ }
+
+ return {
+ calibrate,
+ getVolume: () => {
+ analyser.getByteFrequencyData(dataArray);
+ if (calibrationSamples < CALIBRATION_FRAMES) calibrate();
+ let sum = 0;
+ for (let i = 0; i < dataArray.length; i++) sum += getCleanBin(i);
+ return sum / dataArray.length;
+ },
+ getBands: (count: number) => {
+ analyser.getByteFrequencyData(dataArray);
+ if (calibrationSamples < CALIBRATION_FRAMES) calibrate();
+ const bands: number[] = [];
+ const binCount = dataArray.length;
+ const voiceSplits = [3, 6, 11, 18, binCount];
+ const splits = count <= voiceSplits.length ? voiceSplits.slice(0, count) : voiceSplits;
+ let start = 1;
+ for (let b = 0; b < splits.length; b++) {
+ const end = splits[b];
+ let bandSum = 0;
+ for (let i = start; i < end; i++) bandSum += getCleanBin(i);
+ bands.push(bandSum / (end - start));
+ start = end;
+ }
+ return bands;
+ },
+ getRawBands: (count: number) => {
+ analyser.getByteFrequencyData(dataArray);
+ const bands: number[] = [];
+ const binCount = dataArray.length;
+ const voiceSplits = [3, 6, 11, 18, binCount];
+ const splits = count <= voiceSplits.length ? voiceSplits.slice(0, count) : voiceSplits;
+ let start = 1;
+ for (let b = 0; b < splits.length; b++) {
+ const end = splits[b];
+ let bandSum = 0;
+ for (let i = start; i < end; i++) bandSum += dataArray[i] / 255;
+ bands.push(bandSum / (end - start));
+ start = end;
+ }
+ return bands;
+ },
+ cleanup: () => {
+ source.disconnect();
+ for (const track of stream.getTracks()) track.stop();
+ },
+ };
+ } catch {
+ return null;
+ }
+}
+
+// =============================================================================
+// AudioContext singleton
+// =============================================================================
+
+let _sharedAudioCtx: AudioContext | null = null;
+
+export function getDefaultAudioContext(): AudioContext {
+ if (!_sharedAudioCtx || _sharedAudioCtx.state === 'closed') {
+ _sharedAudioCtx = new AudioContext();
+ }
+ if (_sharedAudioCtx.state === 'suspended') {
+ _sharedAudioCtx.resume();
+ }
+ return _sharedAudioCtx;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useSpeechRecognition(
+ options: UseSpeechRecognitionOptions = {},
+): UseSpeechRecognitionReturn {
+ const {
+ lang,
+ continuous = true,
+ interimResults = true,
+ onTranscript,
+ onResult,
+ onError,
+ onStart,
+ onEnd,
+ audioContext: externalAudioContext,
+ transformTranscript,
+ } = options;
+
+ const getAudioContext = useCallback(
+ () => externalAudioContext ?? getDefaultAudioContext(),
+ [externalAudioContext],
+ );
+
+ const [isSupported, setIsSupported] = useState(false);
+ const [isListening, setIsListening] = useState(false);
+ const [isSpeaking, setIsSpeaking] = useState(false);
+ const [volume, setVolume] = useState(0);
+ const [bands, setBands] = useState<number[]>([0, 0, 0, 0, 0]);
+ const [rawBands, setRawBands] = useState<number[]>([0, 0, 0, 0, 0]);
+ const [interimTranscript, setInterimTranscript] = useState('');
+
+ const recognitionRef = useRef<SpeechRecognitionInstance | null>(null);
+ const getAudioContextRef = useRef(getAudioContext);
+ getAudioContextRef.current = getAudioContext;
+ const analyserRef = useRef<VolumeAnalyser | null>(null);
+ const rafRef = useRef<number>(0);
+
+ const callbacksRef = useRef({
+ onTranscript, onResult, onError, onStart, onEnd, transformTranscript,
+ });
+ callbacksRef.current = {onTranscript, onResult, onError, onStart, onEnd, transformTranscript};
+
+ useEffect(() => {
+ const SR = getSpeechRecognition();
+ setIsSupported(SR != null);
+ return () => {
+ recognitionRef.current?.abort();
+ recognitionRef.current = null;
+ analyserRef.current?.cleanup();
+ analyserRef.current = null;
+ cancelAnimationFrame(rafRef.current);
+ };
+ }, []);
+
+ const startVolumePolling = useCallback(() => {
+ const poll = () => {
+ const a = analyserRef.current;
+ if (a) {
+ setVolume(a.getVolume());
+ setBands(a.getBands(5));
+ setRawBands(a.getRawBands(5));
+ }
+ rafRef.current = requestAnimationFrame(poll);
+ };
+ rafRef.current = requestAnimationFrame(poll);
+ }, []);
+
+ const stopVolumePolling = useCallback(() => {
+ cancelAnimationFrame(rafRef.current);
+ setVolume(0);
+ setBands([0, 0, 0, 0, 0]);
+ setRawBands([0, 0, 0, 0, 0]);
+ analyserRef.current?.cleanup();
+ analyserRef.current = null;
+ }, []);
+
+ const start = useCallback(() => {
+ const SR = getSpeechRecognition();
+ if (!SR) return;
+ recognitionRef.current?.abort();
+ const recognition = new SR();
+ recognition.lang = lang ?? navigator.language;
+ recognition.continuous = continuous;
+ recognition.interimResults = interimResults;
+
+ recognition.onstart = () => {
+ setIsListening(true);
+ callbacksRef.current.onStart?.();
+ createVolumeAnalyser(getAudioContextRef.current).then(a => {
+ if (a) { analyserRef.current = a; startVolumePolling(); }
+ });
+ };
+
+ recognition.onend = () => {
+ setIsListening(false);
+ setIsSpeaking(false);
+ setInterimTranscript('');
+ stopVolumePolling();
+ callbacksRef.current.onEnd?.();
+ };
+
+ recognition.onspeechstart = () => { setIsSpeaking(true); };
+ recognition.onspeechend = () => { setIsSpeaking(false); };
+
+ recognition.onresult = (event: SpeechRecognitionEvent) => {
+ let interim = '';
+ for (let i = event.resultIndex; i < event.results.length; i++) {
+ const result = event.results[i];
+ let transcript = result[0].transcript;
+ if (callbacksRef.current.transformTranscript) {
+ transcript = callbacksRef.current.transformTranscript(transcript);
+ }
+ if (result.isFinal) {
+ callbacksRef.current.onResult?.(transcript);
+ callbacksRef.current.onTranscript?.(transcript, true);
+ setInterimTranscript('');
+ } else {
+ interim += transcript;
+ }
+ }
+ if (interim) {
+ setInterimTranscript(interim);
+ callbacksRef.current.onTranscript?.(interim, false);
+ }
+ };
+
+ recognition.onerror = event => {
+ callbacksRef.current.onError?.({ error: event.error, message: event.message });
+ };
+
+ recognition.onnomatch = () => {
+ callbacksRef.current.onError?.({ error: 'no-speech', message: 'No speech was detected.' });
+ };
+
+ recognitionRef.current = recognition;
+ recognition.start();
+ }, [lang, continuous, interimResults, startVolumePolling, stopVolumePolling]);
+
+ const stop = useCallback(() => { recognitionRef.current?.stop(); }, []);
+
+ const abort = useCallback(() => {
+ recognitionRef.current?.abort();
+ stopVolumePolling();
+ }, [stopVolumePolling]);
+
+ const toggle = useCallback(() => {
+ if (isListening) stop(); else start();
+ }, [isListening, start, stop]);
+
+ return {
+ isSupported, isListening, isSpeaking, volume, bands, rawBands,
+ interimTranscript, start, stop, abort, toggle,
+ };
+}
diff --git a/packages/core/src/Chat/useXDSChatComposerTokens.ts b/packages/core/src/Chat/useXDSChatComposerTokens.ts
index 53629c381a..f0c1c90209 100644
--- a/packages/core/src/Chat/useXDSChatComposerTokens.ts
+++ b/packages/core/src/Chat/useXDSChatComposerTokens.ts
@@ -19,7 +19,10 @@
*/
import {useCallback, useState} from 'react';
-import type {XDSChatComposerToken, XDSChatComposerTokenCustom} from './XDSChatComposerInput';
+import type {
+ XDSChatComposerToken,
+ XDSChatComposerTokenCustom,
+} from './XDSChatComposerInput';
// =============================================================================
// Types
@@ -44,7 +47,7 @@ export interface UseXDSChatComposerTokensReturn {
/** Expand a token — replace the token span with its text value. */
expandToken: (id: string) => void;
/** Insert a token at the current cursor position. */
- insertToken: (token: XDSChatComposerToken) => void;
+ insertToken: (token: XDSChatComposerToken) => string | undefined;
/** Handle keydown — intercepts Backspace near tokens. Returns true if handled. */
handleKeyDown: (e: React.KeyboardEvent) => boolean;
/** Handle paste — prevents pasting into token spans. Returns true if handled. */
@@ -105,7 +108,7 @@ export function useXDSChatComposerTokens({
// --- Insert token at cursor ---
const insertToken = useCallback(
- (token: XDSChatComposerToken) => {
+ (token: XDSChatComposerToken): string | undefined => {
const editable = editableRef.current;
if (!editable) return;
@@ -139,6 +142,7 @@ export function useXDSChatComposerTokens({
// Register for portal rendering
setTokenPortals(prev => [...prev, {id, span, token}]);
+ return id;
},
[editableRef],
);
diff --git a/packages/core/src/Chat/useXDSChatDictation.test.ts b/packages/core/src/Chat/useXDSChatDictation.test.ts
new file mode 100644
index 0000000000..4399a030a5
--- /dev/null
+++ b/packages/core/src/Chat/useXDSChatDictation.test.ts
@@ -0,0 +1,352 @@
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {renderHook, act} from '@testing-library/react';
+import {useSpeechRecognition} from './useSpeechRecognition';
+import {useXDSChatDictation} from './useXDSChatDictation';
+
+// =============================================================================
+// Mock SpeechRecognition
+// =============================================================================
+
+class MockSpeechRecognition {
+ lang = '';
+ continuous = false;
+ interimResults = false;
+ onstart: (() => void) | null = null;
+ onend: (() => void) | null = null;
+ onresult: ((event: unknown) => void) | null = null;
+ onspeechstart: (() => void) | null = null;
+ onspeechend: (() => void) | null = null;
+ onerror: ((event: unknown) => void) | null = null;
+ onnomatch: (() => void) | null = null;
+
+ start = vi.fn(() => {
+ this.onstart?.();
+ });
+
+ stop = vi.fn(() => {
+ this.onend?.();
+ });
+
+ abort = vi.fn(() => {
+ this.onend?.();
+ });
+}
+
+let lastInstance: MockSpeechRecognition | null = null;
+
+function MockSRConstructor() {
+ const instance = new MockSpeechRecognition();
+ lastInstance = instance;
+ return instance;
+}
+
+// =============================================================================
+// Setup / Teardown
+// =============================================================================
+
+let originalSR: unknown;
+
+beforeEach(() => {
+ lastInstance = null;
+ originalSR = (window as unknown as Record<string, unknown>)
+ .SpeechRecognition;
+ (window as unknown as Record<string, unknown>).SpeechRecognition =
+ MockSRConstructor;
+});
+
+afterEach(() => {
+ if (originalSR === undefined) {
+ delete (window as unknown as Record<string, unknown>).SpeechRecognition;
+ } else {
+ (window as unknown as Record<string, unknown>).SpeechRecognition =
+ originalSR;
+ }
+});
+
+// =============================================================================
+// useSpeechRecognition
+// =============================================================================
+
+describe('useSpeechRecognition', () => {
+ it('reports isSupported as false when SpeechRecognition is unavailable', () => {
+ delete (window as unknown as Record<string, unknown>).SpeechRecognition;
+ delete (window as unknown as Record<string, unknown>)
+ .webkitSpeechRecognition;
+
+ const {result} = renderHook(() => useSpeechRecognition());
+ expect(result.current.isSupported).toBe(false);
+ expect(result.current.isListening).toBe(false);
+ });
+
+ it('reports isSupported as true when SpeechRecognition is available', () => {
+ const {result} = renderHook(() => useSpeechRecognition());
+ expect(result.current.isSupported).toBe(true);
+ });
+
+ it('starts and sets isListening', () => {
+ const {result} = renderHook(() => useSpeechRecognition());
+
+ act(() => {
+ result.current.start();
+ });
+
+ expect(result.current.isListening).toBe(true);
+ expect(lastInstance?.start).toHaveBeenCalled();
+ });
+
+ it('stops and clears isListening', () => {
+ const {result} = renderHook(() => useSpeechRecognition());
+
+ act(() => {
+ result.current.start();
+ });
+ expect(result.current.isListening).toBe(true);
+
+ act(() => {
+ result.current.stop();
+ });
+ expect(result.current.isListening).toBe(false);
+ });
+
+ it('toggle starts when not listening and stops when listening', () => {
+ const {result} = renderHook(() => useSpeechRecognition());
+
+ // Toggle on
+ act(() => {
+ result.current.toggle();
+ });
+ expect(result.current.isListening).toBe(true);
+
+ // Toggle off
+ act(() => {
+ result.current.toggle();
+ });
+ expect(result.current.isListening).toBe(false);
+ });
+
+ it('abort immediately stops recognition', () => {
+ const {result} = renderHook(() => useSpeechRecognition());
+
+ act(() => {
+ result.current.start();
+ });
+ expect(result.current.isListening).toBe(true);
+
+ act(() => {
+ result.current.abort();
+ });
+ expect(result.current.isListening).toBe(false);
+ expect(lastInstance?.abort).toHaveBeenCalled();
+ });
+
+ it('calls onStart and onEnd callbacks', () => {
+ const onStart = vi.fn();
+ const onEnd = vi.fn();
+
+ const {result} = renderHook(() =>
+ useSpeechRecognition({onStart, onEnd}),
+ );
+
+ act(() => {
+ result.current.start();
+ });
+ expect(onStart).toHaveBeenCalledOnce();
+
+ act(() => {
+ result.current.stop();
+ });
+ expect(onEnd).toHaveBeenCalledOnce();
+ });
+
+ it('handles result events with final transcript', () => {
+ const onResult = vi.fn();
+ const onTranscript = vi.fn();
+
+ const {result} = renderHook(() =>
+ useSpeechRecognition({onResult, onTranscript}),
+ );
+
+ act(() => {
+ result.current.start();
+ });
+
+ // Simulate a final result
+ act(() => {
+ lastInstance?.onresult?.({
+ resultIndex: 0,
+ results: {
+ length: 1,
+ 0: {
+ isFinal: true,
+ length: 1,
+ 0: {transcript: 'hello world'},
+ },
+ },
+ });
+ });
+
+ expect(onResult).toHaveBeenCalledWith('hello world');
+ expect(onTranscript).toHaveBeenCalledWith('hello world', true);
+ });
+
+ it('handles interim results and updates interimTranscript', () => {
+ const onTranscript = vi.fn();
+
+ const {result} = renderHook(() =>
+ useSpeechRecognition({onTranscript}),
+ );
+
+ act(() => {
+ result.current.start();
+ });
+
+ // Simulate an interim result
+ act(() => {
+ lastInstance?.onresult?.({
+ resultIndex: 0,
+ results: {
+ length: 1,
+ 0: {
+ isFinal: false,
+ length: 1,
+ 0: {transcript: 'hel'},
+ },
+ },
+ });
+ });
+
+ expect(result.current.interimTranscript).toBe('hel');
+ expect(onTranscript).toHaveBeenCalledWith('hel', false);
+ });
+
+ it('cleans up recognition on unmount', () => {
+ const {result, unmount} = renderHook(() => useSpeechRecognition());
+
+ act(() => {
+ result.current.start();
+ });
+
+ const instance = lastInstance;
+ unmount();
+
+ expect(instance?.abort).toHaveBeenCalled();
+ });
+});
+
+// =============================================================================
+// useXDSChatDictation
+// =============================================================================
+
+describe('useXDSChatDictation', () => {
+ it('reports isSupported from speech recognition', () => {
+ const {result} = renderHook(() => useXDSChatDictation());
+ expect(result.current.isSupported).toBe(true);
+ });
+
+ it('includes volume, bands, rawBands in return', () => {
+ const {result} = renderHook(() => useXDSChatDictation());
+ expect(result.current.volume).toBe(0);
+ expect(result.current.bands).toEqual([0, 0, 0, 0, 0]);
+ expect(result.current.rawBands).toEqual([0, 0, 0, 0, 0]);
+ });
+
+ it('starts and sets isListening', () => {
+ const {result} = renderHook(() => useXDSChatDictation());
+
+ act(() => {
+ result.current.start();
+ });
+
+ expect(result.current.isListening).toBe(true);
+ });
+
+ it('stops and clears isListening', () => {
+ const {result} = renderHook(() => useXDSChatDictation());
+
+ act(() => {
+ result.current.start();
+ });
+ expect(result.current.isListening).toBe(true);
+
+ act(() => {
+ result.current.stop();
+ });
+ expect(result.current.isListening).toBe(false);
+ });
+
+ it('toggle starts and stops', () => {
+ const {result} = renderHook(() => useXDSChatDictation());
+
+ act(() => {
+ result.current.toggle();
+ });
+ expect(result.current.isListening).toBe(true);
+
+ act(() => {
+ result.current.toggle();
+ });
+ expect(result.current.isListening).toBe(false);
+ });
+
+ it('forwards onStart and onEnd callbacks', () => {
+ const onStart = vi.fn();
+ const onEnd = vi.fn();
+
+ const {result} = renderHook(() =>
+ useXDSChatDictation({onStart, onEnd}),
+ );
+
+ act(() => {
+ result.current.start();
+ });
+ expect(onStart).toHaveBeenCalledOnce();
+
+ act(() => {
+ result.current.stop();
+ });
+ expect(onEnd).toHaveBeenCalledOnce();
+ });
+
+ it('handles final transcript via onResult', () => {
+ const onResult = vi.fn();
+
+ const {result} = renderHook(() =>
+ useXDSChatDictation({onResult}),
+ );
+
+ act(() => {
+ result.current.start();
+ });
+
+ act(() => {
+ lastInstance?.onresult?.({
+ resultIndex: 0,
+ results: {
+ length: 1,
+ 0: {
+ isFinal: true,
+ length: 1,
+ 0: {transcript: 'hello world'},
+ },
+ },
+ });
+ });
+
+ expect(onResult).toHaveBeenCalledWith('hello world');
+ });
+
+ it('abort immediately stops recognition', () => {
+ const {result} = renderHook(() => useXDSChatDictation());
+
+ act(() => {
+ result.current.start();
+ });
+
+ act(() => {
+ result.current.abort();
+ });
+
+ expect(result.current.isListening).toBe(false);
+ expect(lastInstance?.abort).toHaveBeenCalled();
+ });
+});
diff --git a/packages/core/src/Chat/useXDSChatDictation.ts b/packages/core/src/Chat/useXDSChatDictation.ts
new file mode 100644
index 0000000000..4cc7cabdc3
--- /dev/null
+++ b/packages/core/src/Chat/useXDSChatDictation.ts
@@ -0,0 +1,439 @@
+'use client';
+
+/**
+ * @file useXDSChatDictation.ts
+ * @input Uses useSpeechRecognition, AudioContext, XDSChatComposerInputHandle
+ * @output Exports useXDSChatDictation — full dictation hook for XDSChatComposer
+ * @position Utility hook — the ONE hook consumers call for voice-to-text input
+ *
+ * Wraps useSpeechRecognition and adds AudioContext (volume, frequency bands,
+ * noise floor calibration), audio feedback sounds, CAPS LOCK (sustained volume
+ * → uppercase), and optional interim text DOM management for XDSChatComposerInput.
+ */
+
+import {useState, useCallback, useEffect, useRef} from 'react';
+import type {XDSChatComposerInputHandle} from './XDSChatComposerInput';
+import {useSpeechRecognition} from './useSpeechRecognition';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface UseXDSChatDictationOptions {
+ /** BCP-47 language tag. @default navigator.language */
+ lang?: string;
+ /** Whether recognition continues until explicitly stopped. @default true */
+ continuous?: boolean;
+ /** Whether interim results are reported. @default true */
+ interimResults?: boolean;
+ /** Transform transcript text before it's reported. Applied before CAPS LOCK. */
+ transformTranscript?: (transcript: string) => string;
+ /** Called on each transcript result (interim or final). */
+ onTranscript?: (transcript: string, isFinal: boolean) => void;
+ /** Called when a final result is produced. */
+ onResult?: (transcript: string) => void;
+ /** Called when a recognition error occurs. */
+ onError?: (error: {error: string; message?: string}) => void;
+ /** Called when recognition starts. */
+ onStart?: () => void;
+ /** Called when recognition ends. */
+ onEnd?: () => void;
+ /** Play subtle audio cues on start/stop. @default false */
+ hasSounds?: boolean;
+ /** Shared AudioContext — uses an internal lazy singleton by default. */
+ audioContext?: AudioContext;
+ /** Ref to XDSChatComposerInput. If provided, manages interim ghost text in the input. */
+ inputRef?: React.RefObject<XDSChatComposerInputHandle | null>;
+}
+
+export interface UseXDSChatDictationReturn {
+ /** Whether the browser supports SpeechRecognition. */
+ isSupported: boolean;
+ /** Whether recognition is currently active. */
+ isListening: boolean;
+ /** Whether speech is currently being detected. */
+ isSpeaking: boolean;
+ /** Real-time microphone volume level, 0 to 1. Updates ~60fps while listening. */
+ volume: number;
+ /** Frequency band levels (low to high), each 0-1. Updates ~60fps while listening. */
+ bands: number[];
+ /** Raw (uncalibrated) band levels for debugging. */
+ rawBands: number[];
+ /** The current interim transcript text. */
+ interimTranscript: string;
+ /** Start speech recognition. */
+ start: () => void;
+ /** Stop speech recognition gracefully (waits for final result). */
+ stop: () => void;
+ /** Abort speech recognition immediately. */
+ abort: () => void;
+ /** Toggle between start and stop. */
+ toggle: () => void;
+}
+
+// =============================================================================
+// Volume analyser
+// =============================================================================
+
+interface VolumeAnalyser {
+ calibrate: () => void;
+ getVolume: () => number;
+ getBands: (count: number) => number[];
+ getRawBands: (count: number) => number[];
+ cleanup: () => void;
+}
+
+async function createVolumeAnalyser(
+ getCtx: () => AudioContext,
+): Promise<VolumeAnalyser | null> {
+ try {
+ const stream = await navigator.mediaDevices.getUserMedia({audio: true});
+ const audioContext = getCtx();
+ const source = audioContext.createMediaStreamSource(stream);
+ const analyser = audioContext.createAnalyser();
+ analyser.fftSize = 256;
+ analyser.smoothingTimeConstant = 0.5;
+ source.connect(analyser);
+
+ const dataArray = new Uint8Array(analyser.frequencyBinCount);
+ const noiseFloor = new Float32Array(analyser.frequencyBinCount);
+ let calibrationSamples = 0;
+ const CALIBRATION_FRAMES = 60;
+
+ function calibrate() {
+ analyser.getByteFrequencyData(dataArray);
+ calibrationSamples++;
+ for (let i = 0; i < dataArray.length; i++) {
+ const val = dataArray[i] / 255;
+ if (val > noiseFloor[i]) noiseFloor[i] = val;
+ }
+ }
+
+ function getCleanBin(i: number): number {
+ const raw = dataArray[i] / 255;
+ if (calibrationSamples < CALIBRATION_FRAMES) return 0;
+ return Math.max(0, raw - noiseFloor[i] * 1.1);
+ }
+
+ return {
+ calibrate,
+ getVolume: () => {
+ analyser.getByteFrequencyData(dataArray);
+ if (calibrationSamples < CALIBRATION_FRAMES) calibrate();
+ let sum = 0;
+ for (let i = 0; i < dataArray.length; i++) sum += getCleanBin(i);
+ return sum / dataArray.length;
+ },
+ getBands: (count: number) => {
+ analyser.getByteFrequencyData(dataArray);
+ if (calibrationSamples < CALIBRATION_FRAMES) calibrate();
+ const bands: number[] = [];
+ const binCount = dataArray.length;
+ const voiceSplits = [3, 6, 11, 18, binCount];
+ const splits = count <= voiceSplits.length ? voiceSplits.slice(0, count) : voiceSplits;
+ let start = 1;
+ for (let b = 0; b < splits.length; b++) {
+ const end = splits[b];
+ let sum = 0;
+ for (let i = start; i < end; i++) sum += getCleanBin(i);
+ bands.push(sum / (end - start));
+ start = end;
+ }
+ return bands;
+ },
+ getRawBands: (count: number) => {
+ analyser.getByteFrequencyData(dataArray);
+ const bands: number[] = [];
+ const binCount = dataArray.length;
+ const voiceSplits = [3, 6, 11, 18, binCount];
+ const splits = count <= voiceSplits.length ? voiceSplits.slice(0, count) : voiceSplits;
+ let start = 1;
+ for (let b = 0; b < splits.length; b++) {
+ const end = splits[b];
+ let sum = 0;
+ for (let i = start; i < end; i++) sum += dataArray[i] / 255;
+ bands.push(sum / (end - start));
+ start = end;
+ }
+ return bands;
+ },
+ cleanup: () => {
+ source.disconnect();
+ for (const track of stream.getTracks()) track.stop();
+ },
+ };
+ } catch {
+ return null;
+ }
+}
+
+// =============================================================================
+// Audio feedback
+// =============================================================================
+
+let _sharedAudioCtx: AudioContext | null = null;
+
+function getDefaultAudioContext(): AudioContext {
+ if (!_sharedAudioCtx || _sharedAudioCtx.state === 'closed') {
+ _sharedAudioCtx = new AudioContext();
+ }
+ if (_sharedAudioCtx.state === 'suspended') {
+ _sharedAudioCtx.resume();
+ }
+ return _sharedAudioCtx;
+}
+
+const isIOS =
+ typeof navigator !== 'undefined' &&
+ /iPad|iPhone|iPod/.test(navigator.userAgent);
+
+function playPlop(
+ freq: number,
+ delay: number,
+ getCtx: () => AudioContext,
+ volume: number = 0.25,
+) {
+ try {
+ const ctx = getCtx();
+ const now = ctx.currentTime;
+ const dur = freq < 200 ? 0.18 : 0.06;
+ const osc = ctx.createOscillator();
+ const gain = ctx.createGain();
+ osc.type = 'sine';
+ osc.frequency.setValueAtTime(freq * 1.3, now + delay);
+ osc.frequency.exponentialRampToValueAtTime(freq, now + delay + 0.01);
+ osc.frequency.exponentialRampToValueAtTime(freq * 0.93, now + delay + dur);
+ gain.gain.setValueAtTime(0.001, now);
+ gain.gain.setValueAtTime(volume, now + delay);
+ gain.gain.exponentialRampToValueAtTime(volume * 0.2, now + delay + dur * 0.12);
+ gain.gain.exponentialRampToValueAtTime(0.001, now + delay + dur);
+ osc.connect(gain);
+ gain.connect(ctx.destination);
+ osc.start(now + delay);
+ osc.stop(now + delay + dur);
+ } catch {
+ // Audio playback is best-effort
+ }
+}
+
+function playStartSound(getCtx: () => AudioContext) {
+ if (isIOS) return;
+ playPlop(392, 0, getCtx);
+ playPlop(523, 0.07, getCtx);
+}
+
+function playStopSound(getCtx: () => AudioContext) {
+ if (isIOS) return;
+ playPlop(523, 0, getCtx);
+ playPlop(392, 0.07, getCtx);
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useXDSChatDictation(
+ options: UseXDSChatDictationOptions = {},
+): UseXDSChatDictationReturn {
+ const {
+ lang,
+ continuous,
+ interimResults,
+ transformTranscript: userTransform,
+ onTranscript: onTranscriptProp,
+ onResult: onResultProp,
+ onError,
+ onStart: onStartProp,
+ onEnd: onEndProp,
+ hasSounds = false,
+ audioContext: externalAudioContext,
+ inputRef,
+ } = options;
+
+ const getAudioContext = useCallback(
+ () => externalAudioContext ?? getDefaultAudioContext(),
+ [externalAudioContext],
+ );
+
+ const [volume, setVolume] = useState(0);
+ const [bands, setBands] = useState<number[]>([0, 0, 0, 0, 0]);
+ const [rawBands, setRawBands] = useState<number[]>([0, 0, 0, 0, 0]);
+
+ const volumeHistoryRef = useRef<number[]>([]);
+ const getAudioContextRef = useRef(getAudioContext);
+ getAudioContextRef.current = getAudioContext;
+ const analyserRef = useRef<VolumeAnalyser | null>(null);
+ const rafRef = useRef<number>(0);
+ const interimSpanRef = useRef<HTMLSpanElement | null>(null);
+
+ const callbacksRef = useRef({
+ onTranscriptProp,
+ onResultProp,
+ onStartProp,
+ onEndProp,
+ });
+ callbacksRef.current = {
+ onTranscriptProp,
+ onResultProp,
+ onStartProp,
+ onEndProp,
+ };
+
+ const startVolumePolling = useCallback(() => {
+ const poll = () => {
+ const analyser = analyserRef.current;
+ if (analyser) {
+ const vol = analyser.getVolume();
+ setVolume(vol);
+ const hist = volumeHistoryRef.current;
+ hist.push(vol);
+ if (hist.length > 30) hist.shift();
+ setBands(analyser.getBands(5));
+ setRawBands(analyser.getRawBands(5));
+ }
+ rafRef.current = requestAnimationFrame(poll);
+ };
+ rafRef.current = requestAnimationFrame(poll);
+ }, []);
+
+ const stopVolumePolling = useCallback(() => {
+ cancelAnimationFrame(rafRef.current);
+ setVolume(0);
+ setBands([0, 0, 0, 0, 0]);
+ setRawBands([0, 0, 0, 0, 0]);
+ volumeHistoryRef.current = [];
+ analyserRef.current?.cleanup();
+ analyserRef.current = null;
+ }, []);
+
+ const getEditable = useCallback((): HTMLDivElement | null => {
+ const active = document.activeElement;
+ if (active?.getAttribute('contenteditable') === 'true') {
+ return active as HTMLDivElement;
+ }
+ return document.querySelector<HTMLDivElement>(
+ '.xds-chat-composer-input [contenteditable="true"], [role="textbox"][contenteditable="true"]',
+ );
+ }, []);
+
+ const insertInterimSpan = useCallback(() => {
+ const editable = getEditable();
+ if (!editable) return;
+ const span = document.createElement('span');
+ span.setAttribute('data-xds-dictation-interim', '');
+ span.contentEditable = 'false';
+ span.style.color = 'var(--color-text-disabled, #999)';
+ span.style.fontStyle = 'italic';
+ span.style.opacity = '0.7';
+ span.style.pointerEvents = 'none';
+ editable.appendChild(span);
+ interimSpanRef.current = span;
+ editable.dispatchEvent(new Event('input', {bubbles: true}));
+ }, [getEditable]);
+
+ const removeInterimSpan = useCallback(() => {
+ const span = interimSpanRef.current;
+ if (span?.isConnected) {
+ try { span.remove(); } catch { /* Already removed */ }
+ }
+ interimSpanRef.current = null;
+ }, []);
+
+ const transformTranscript = useCallback(
+ (text: string) => {
+ let t = text;
+ if (userTransform) t = userTransform(t);
+ const hist = volumeHistoryRef.current;
+ const avgVolume =
+ hist.length > 0 ? hist.reduce((a, b) => a + b, 0) / hist.length : 0;
+ if (avgVolume >= 0.15 && hist.length >= 10) t = t.toUpperCase();
+ return t;
+ },
+ [userTransform],
+ );
+
+ useEffect(() => {
+ return () => {
+ analyserRef.current?.cleanup();
+ analyserRef.current = null;
+ cancelAnimationFrame(rafRef.current);
+ };
+ }, []);
+
+ const speech = useSpeechRecognition({
+ lang,
+ continuous,
+ interimResults,
+ transformTranscript,
+ onTranscript: (transcript, isFinal) => {
+ if (inputRef) {
+ if (isFinal) {
+ removeInterimSpan();
+ const handle = inputRef.current;
+ if (handle) {
+ handle.focus();
+ handle.insertText(transcript + ' ');
+ }
+ callbacksRef.current.onResultProp?.(transcript);
+ insertInterimSpan();
+ } else {
+ const span = interimSpanRef.current;
+ if (span) {
+ span.textContent = transcript;
+ } else {
+ insertInterimSpan();
+ if (interimSpanRef.current) {
+ interimSpanRef.current.textContent = transcript;
+ }
+ }
+ }
+ }
+ callbacksRef.current.onTranscriptProp?.(transcript, isFinal);
+ },
+ onResult: inputRef ? undefined : onResultProp,
+ onError,
+ onStart: () => {
+ if (hasSounds) playStartSound(getAudioContextRef.current);
+ createVolumeAnalyser(getAudioContextRef.current).then(analyser => {
+ if (analyser) {
+ analyserRef.current = analyser;
+ startVolumePolling();
+ }
+ });
+ if (inputRef) insertInterimSpan();
+ callbacksRef.current.onStartProp?.();
+ },
+ onEnd: () => {
+ stopVolumePolling();
+ if (hasSounds) playStopSound(getAudioContextRef.current);
+ if (inputRef) {
+ removeInterimSpan();
+ const editable = getEditable();
+ if (editable) {
+ editable.dispatchEvent(new Event('input', {bubbles: true}));
+ }
+ }
+ callbacksRef.current.onEndProp?.();
+ },
+ });
+
+ const speechAbort = speech.abort;
+ const wrappedAbort = useCallback(() => {
+ speechAbort();
+ stopVolumePolling();
+ }, [speechAbort, stopVolumePolling]);
+
+ return {
+ isSupported: speech.isSupported,
+ isListening: speech.isListening,
+ isSpeaking: speech.isSpeaking,
+ interimTranscript: speech.interimTranscript,
+ volume,
+ bands,
+ rawBands,
+ start: speech.start,
+ stop: speech.stop,
+ abort: wrappedAbort,
+ toggle: speech.toggle,
+ };
+}
diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsx
index 4df71173ed..0d7069ec5f 100644
--- a/packages/core/src/Icon/defaultIcons.tsx
+++ b/packages/core/src/Icon/defaultIcons.tsx
@@ -248,4 +248,15 @@ export const defaultIcons: XDSIconRegistry = {
<rect x="6" y="6" width="12" height="12" rx="2" />
</svg>
),
+
+ /** 🎤 — microphone (voice input / dictation) */
+ microphone: (
+ <svg {...svgProps}>
+ <path d="M12 2a3 3 0 00-3 3v6a3 3 0 006 0V5a3 3 0 00-3-3z" />
+ <path d="M19 10v1a7 7 0 01-14 0v-1" />
+ <path d="M12 18v4m-4 0h8" />
+ </svg>
+ ),
+
+ /** ⏺ — filled circle (recording indicator) */
};
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
index 2163abca81..8d93175396 100644
--- a/packages/core/src/Icon/globalIconRegistry.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -46,7 +46,8 @@ export type XDSIconName =
| 'copy'
| 'checkDouble'
| 'wrench'
- | 'stop';
+ | 'stop'
+ | 'microphone';
/**
* Icon registry mapping semantic names to React nodes.
diff --git a/packages/themes/daily/src/icons.tsx b/packages/themes/daily/src/icons.tsx
index a173d93701..45e83e2db8 100644
--- a/packages/themes/daily/src/icons.tsx
+++ b/packages/themes/daily/src/icons.tsx
@@ -27,6 +27,8 @@ import {
CheckCheck,
Wrench,
Square,
+ Mic,
+ CircleDot,
} from 'lucide-react';
const iconProps = {
@@ -60,4 +62,5 @@ export const dailyIconRegistry: XDSIconRegistry = {
checkDouble: <CheckCheck {...iconProps} />,
wrench: <Wrench {...iconProps} />,
stop: <Square {...iconProps} />,
+ microphone: <Mic {...iconProps} />,
};
diff --git a/packages/themes/default/src/icons.tsx b/packages/themes/default/src/icons.tsx
index 3617ac0671..1ed6d66fba 100644
--- a/packages/themes/default/src/icons.tsx
+++ b/packages/themes/default/src/icons.tsx
@@ -31,6 +31,7 @@ import {
ViewColumnsIcon,
ClipboardDocumentIcon,
WrenchIcon,
+ MicrophoneIcon,
} from '@heroicons/react/24/outline';
import {
@@ -39,6 +40,7 @@ import {
ExclamationTriangleIcon,
ArrowTopRightOnSquareIcon,
StopIcon,
+ StopCircleIcon,
} from '@heroicons/react/24/solid';
const iconProps = {
@@ -73,4 +75,5 @@ export const defaultIconRegistry: XDSIconRegistry = {
checkDouble: <CheckIcon {...iconProps} />,
wrench: <WrenchIcon {...iconProps} />,
stop: <StopIcon {...iconProps} />,
+ microphone: <MicrophoneIcon {...iconProps} />,
};
diff --git a/packages/themes/meta/src/icons.tsx b/packages/themes/meta/src/icons.tsx
index f56a8bf4b1..963ab917de 100644
--- a/packages/themes/meta/src/icons.tsx
+++ b/packages/themes/meta/src/icons.tsx
@@ -32,6 +32,7 @@ import {
ViewColumnsIcon,
ClipboardDocumentIcon,
WrenchScrewdriverIcon,
+ MicrophoneIcon,
} from '@heroicons/react/24/outline';
import {
@@ -40,6 +41,7 @@ import {
ExclamationTriangleIcon,
ArrowTopRightOnSquareIcon,
StopIcon,
+ StopCircleIcon,
} from '@heroicons/react/24/solid';
const iconProps = {
@@ -74,4 +76,5 @@ export const metaIconRegistry: XDSIconRegistry = {
checkDouble: <CheckIcon {...iconProps} />,
wrench: <WrenchScrewdriverIcon {...iconProps} />,
stop: <StopIcon {...iconProps} />,
+ microphone: <MicrophoneIcon {...iconProps} />,
};
diff --git a/packages/themes/neutral/src/icons.tsx b/packages/themes/neutral/src/icons.tsx
index 5294da0519..5a4be827e0 100644
--- a/packages/themes/neutral/src/icons.tsx
+++ b/packages/themes/neutral/src/icons.tsx
@@ -37,6 +37,8 @@ import {
CheckCheck,
Wrench,
Square,
+ Mic,
+ CircleDot,
} from 'lucide-react';
const iconProps = {
@@ -70,4 +72,5 @@ export const neutralIconRegistry: XDSIconRegistry = {
checkDouble: <CheckCheck {...iconProps} />,
wrench: <Wrench {...iconProps} />,
stop: <Square {...iconProps} />,
+ microphone: <Mic {...iconProps} />,
};
diff --git a/packages/themes/whatsapp/src/icons.tsx b/packages/themes/whatsapp/src/icons.tsx
index 25b3b98bec..f01d5b5ae7 100644
--- a/packages/themes/whatsapp/src/icons.tsx
+++ b/packages/themes/whatsapp/src/icons.tsx
@@ -29,6 +29,7 @@ import {
ViewColumnsIcon,
ClipboardDocumentIcon,
WrenchScrewdriverIcon,
+ MicrophoneIcon,
} from '@heroicons/react/24/outline';
import {
@@ -37,6 +38,7 @@ import {
ExclamationTriangleIcon,
ArrowTopRightOnSquareIcon,
StopIcon,
+ StopCircleIcon,
} from '@heroicons/react/24/solid';
const iconProps = {
@@ -71,4 +73,5 @@ export const whatsappIconRegistry: XDSIconRegistry = {
checkDouble: <CheckIcon {...iconProps} />,
wrench: <WrenchScrewdriverIcon {...iconProps} />,
stop: <StopIcon {...iconProps} />,
+ microphone: <MicrophoneIcon {...iconProps} />,
};