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.tsxnew file mode 100644index 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.tsindex 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.tsxnew file mode 100644index 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.tsxindex 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.tsxnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 renderingsetTokenPortals(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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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} />,};