@deepseek-ai/dsh-experimental-client-ui-voice-input 0.2.2-rc.1 → 0.2.2-rc.2

package/src/client/PreparationCard.tsx

@@ -0,0 +1,165 @@
+/** Provider-owned preparation steps and persisted recognition preferences. */
+import { useEffect, useState } from 'react'
+import { Button, DisclosureRow, IconChevronDownOutlineRegular, StateDot, type StateDotState } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SpeechPreparationState, SpeechProviderId, SpeechProviderView, SpeechSelectionPatch } from '@deepseek-ai/dsh-experimental-speech-to-text/types'
+import type { VoiceInputInjected } from './VoiceInput.tsx'
+import { MicrophonePicker } from './MicrophonePicker.tsx'
+import { NS } from './locales.ts'
+import css from './VoiceInput.module.css'
+
+/** One recognizer's resource readiness and explicit preparation controls. */
+export type PreparationCardProps = Pick<InjectFace<VoiceInputInjected>, 'prepare' | 'cancelPreparation'>
+  & PropsLocale<typeof NS> & { readonly provider: SpeechProviderView; readonly connected: boolean }
+
+function preparationTone(state: SpeechPreparationState): StateDotState {
+  if (state.phase === 'ready' || state.phase === 'standby') return 'done'
+  if (state.phase === 'failed') return 'error'
+  if (state.phase === 'unprepared' || state.phase === 'cancelled') return 'idle'
+  return 'ongoing'
+}
+
+function byteText(state: Extract<SpeechPreparationState, { phase: 'downloading' }>, t: PropsLocale<typeof NS>['t']): string {
+  return state.totalBytes === undefined ? t('downloadUnknown', { completed: (state.completedBytes / 1_000_000).toFixed(1) })
+    : t('downloadBytes', { completed: (state.completedBytes / 1_000_000).toFixed(1),
+      total: (state.totalBytes / 1_000_000).toFixed(1), percent: String(Math.floor(state.completedBytes / state.totalBytes * 100)) })
+}
+
+function DownloadProgress({ state, t }: { state: SpeechPreparationState } & PropsLocale<typeof NS>) {
+  return state.phase === 'downloading' && state.totalBytes !== undefined
+    ? <progress className={css.progress} aria-label={t('downloadProgress')} value={state.completedBytes} max={state.totalBytes} /> : null
+}
+
+function PreparationFailure({ state, t }: { state: Extract<SpeechPreparationState, { phase: 'failed' }> } & PropsLocale<typeof NS>) {
+  const failure = state.download
+  if (!failure) return <p className={css.preparationError} role="alert">{t('preparationFailed', { message: state.message })}</p>
+  return <div className={css.downloadFailure} role="alert">
+    <p className={css.preparationError}>{t(`download.${failure.reason}`, { resource: failure.resource, status: String(failure.status) })}</p>
+    <p>{t(`downloadAdvice.${failure.reason}`)}</p>
+    <small className={css.metric}>{t('downloadSource', { source: failure.source })}</small>
+    {failure.code && <small className={css.metric}>{t('downloadCode', { code: failure.code })}</small>}
+  </div>
+}
+
+/** Render a collapsed current-step summary or all Host-owned preparation steps. */
+export function PreparationCard({ provider, connected, prepare, cancelPreparation, t }: PreparationCardProps) {
+  const state = provider.preparation
+  const [expanded, setExpanded] = useState(false), [now, setNow] = useState(Date.now), [error, setError] = useState('')
+  const [source, setSource] = useState(''), [submitting, setSubmitting] = useState(false)
+  const sources = provider.downloadSources ?? []
+  const [firstSource = ''] = sources
+  const selectedSource = sources.includes(source) ? source : sources.length === 1 ? firstSource : ''
+  const canPrepare = ['unprepared', 'cancelled', 'failed'].includes(state.phase)
+  const current = state.steps?.find(step => step.status === 'running' || step.status === 'failed' || step.status === 'cancelled')
+  const preparing = preparationTone(state) === 'ongoing'
+  const startedAt = current?.startedAt ?? ('startedAt' in state ? state.startedAt : undefined)
+  useEffect(() => {
+    if (!preparing || startedAt === undefined) return
+    const timer = setInterval(() => { setNow(Date.now()) }, 1000)
+    return () => { clearInterval(timer) }
+  }, [preparing, startedAt])
+  const run = async (action: () => Promise<unknown>): Promise<void> => {
+    setError(''); setSubmitting(true)
+    try { await action() } catch (failure) { setError(failure instanceof Error ? failure.message : String(failure)) }
+    finally { setSubmitting(false) }
+  }
+  const metric = state.phase === 'downloading' ? byteText(state, t)
+    : preparing && startedAt !== undefined ? t('elapsed', { seconds: String(Math.max(0, Math.floor((now - startedAt) / 1000))) }) : ''
+  const summary = !connected ? t('reconnecting') : preparing && current ? t(`step.${current.kind}`, { name: provider.name })
+    : state.phase === 'downloading' ? t('short.downloading')
+      : state.phase === 'failed' ? t('short.failed')
+        : state.phase === 'ready' && provider.location === 'cloud' ? t('cloudReady')
+          : t(`preparation.${state.phase}`, { name: provider.name })
+  return <section className={css.preparation} data-speech-provider={provider.id}>
+    <strong>{provider.name}</strong>
+    {state.phase === 'unprepared' && provider.location === 'host-local' && provider.setupEstimate && <div className={css.setupEstimate}>
+      <p>{t('setup.local')}</p>
+      <dl>
+        <div><dt>{t('setup.disk')}</dt><dd>{t('setup.diskValue', {
+          gb: String(provider.setupEstimate.recommendedDiskBytes / 1_000_000_000),
+        })}</dd></div>
+        <div><dt>{t('setup.memory')}</dt><dd>{t('setup.memoryValue', {
+          gb: String(provider.setupEstimate.expectedMemoryBytes / 1_000_000_000),
+        })}</dd></div>
+        <div><dt>{t('setup.time')}</dt><dd>{t('setup.timeValue', {
+          min: String(provider.setupEstimate.minimumMinutes), max: String(provider.setupEstimate.maximumMinutes),
+        })}</dd></div>
+      </dl>
+      <small>{t('setup.estimateNote')}</small>
+    </div>}
+    <DisclosureRow icon={<StateDot state={preparationTone(state)} size={16} appearance="step" />}
+      title={expanded ? t('preparationSteps') : summary} open={expanded} expandable={(state.steps?.length ?? 0) > 0} expandOnRowClick previewChevron={false}
+      onToggle={() => { setExpanded(value => !value) }} rowClassName={css.summaryRow} titleClassName={css.summaryTitle}
+      collapsedContent={<><span className={css.metric} role="status">{metric}</span>{state.steps && <IconChevronDownOutlineRegular />}</>}>
+      <ol className={css.steps}>
+        {state.steps?.map(step => <li key={step.kind} data-step={step.kind} data-step-state={step.status}
+          aria-label={`${t(`step.${step.kind}`, { name: provider.name })} · ${t(`stepStatus.${step.status}`)}`}>
+          <StateDot appearance="step" size={16} state={step.status === 'complete' ? 'done' : step.status === 'running' ? 'ongoing'
+            : step.status === 'failed' ? 'error' : 'idle'} />
+          <div className={css.stepBody}><span>{t(`step.${step.kind}`, { name: provider.name })}</span>
+            {step.status === 'running' && <div className={css.stepProgress}>
+              <span className={css.metric} role="status">{metric}</span><DownloadProgress state={state} t={t} />
+              {state.phase === 'downloading' && <small>{state.resource}</small>}
+            </div>}
+          </div>
+        </li>)}
+      </ol>
+    </DisclosureRow>
+    {!expanded && <DownloadProgress state={state} t={t} />}
+    {state.phase === 'failed' && <PreparationFailure state={state} t={t} />}
+    {canPrepare && sources.length > 0 && <div className={css.sourceChoice}>
+      <label>{t('sourceChoice')}<select aria-label={t('sourceChoice')} value={selectedSource} disabled={!connected || submitting || sources.length === 1}
+        onChange={(event) => { setSource(event.target.value) }}>
+        {sources.length > 1 && <option value="">{t('sourceAuto')}</option>}
+        {sources.map(origin => <option key={origin} value={origin}>
+          {origin === 'https://huggingface.co' ? t('sourceHuggingFace')
+            : origin === 'https://hf-mirror.com' ? t('sourceMirror') : origin}
+        </option>)}
+      </select></label>
+      <small className={css.metric}>{t(selectedSource === '' ? 'sourceAutoHelp' : 'sourceManualHelp')}</small>
+    </div>}
+    <div className={css.preparationActions}>
+      {canPrepare && <Button variant="outline" size="sm" disabled={!connected || submitting}
+        onClick={() => { void run(() => selectedSource === '' ? prepare(provider.id) : prepare(provider.id, { downloadSource: selectedSource })) }}>{t(state.phase === 'unprepared' ? 'prepare' : 'retryPrepare')}</Button>}
+      {preparing && state.phase !== 'waking' && <Button variant="ghost" size="sm" disabled={!connected || submitting || state.phase === 'cancelling'}
+        onClick={() => { void run(() => cancelPreparation(provider.id)) }}>{t('cancelPrepare')}</Button>}
+    </div>
+    {error && <p className={css.preparationError} role="alert">{t('failed', { message: error })}</p>}
+  </section>
+}
+
+/** Recognition preferences and preparation cards shared by plugin details and Settings. */
+export function VoicePreparation({ useSpeechReadiness, ...props }: Pick<InjectFace<VoiceInputInjected>,
+  'useSpeechReadiness' | 'configure' | 'prepare' | 'cancelPreparation' | 'createRecording' | 'useMicrophoneDevice' | 'selectMicrophone'> & PropsLocale<typeof NS>) {
+  const readiness = useSpeechReadiness(value => value), catalog = readiness.catalog
+  const [saving, setSaving] = useState(false), [error, setError] = useState('')
+  const configure = async (patch: SpeechSelectionPatch): Promise<void> => {
+    setSaving(true); setError('')
+    try { await props.configure(patch) } catch (failure) { setError(failure instanceof Error ? failure.message : String(failure)) }
+    finally { setSaving(false) }
+  }
+  const selected = catalog?.providers.find(provider => provider.id === catalog.selection.providerId)
+  const languageNames: Readonly<Record<string, string>> = {
+    auto: props.t('auto'), zh: props.t('zh'), en: props.t('en'), yue: props.t('yue'), ja: props.t('ja'), es: props.t('es'), fr: props.t('fr'), de: props.t('de'), ru: props.t('ru'), pt: props.t('pt'), ko: props.t('ko'),
+  }
+  return <div>
+    {catalog && <div className={css.preferences}>
+      <MicrophonePicker {...props} />
+      <label>{props.t('provider')}<select value={catalog.selection.providerId} disabled={!readiness.connected || saving}
+        onChange={(event) => { void configure({ providerId: event.target.value as SpeechProviderId }) }}>
+        {catalog.providers.map(provider => <option key={provider.id} value={provider.id}>{provider.name}</option>)}
+      </select></label>
+      <label>{props.t('language')}<select value={catalog.selection.language} disabled={!readiness.connected || saving}
+        onChange={(event) => { void configure({ language: event.target.value }) }}>
+        {selected?.languages.map(language =>
+          <option key={language} value={language}>{languageNames[language] ?? language}</option>)}
+      </select></label>
+      <p>{props.t(selected?.location === 'cloud' ? 'cloud' : 'local')}</p>
+      {error && <p role="alert">{props.t('failed', { message: error })}</p>}
+    </div>}
+    {catalog?.providers.map(provider =>
+      <PreparationCard key={provider.id} provider={provider} connected={readiness.connected} {...props} />)}
+    {!catalog && <p role="status">{props.t('loading')}</p>}
+    {readiness.error && <p role="alert">{props.t('failed', { message: readiness.error })}</p>}
+  </div>
+}

package/src/client/VoiceInput.module.css

@@ -0,0 +1,55 @@
+.trigger { width: 28px; padding: 0; flex: none; }
+.triggerAnchor { display: inline-flex; flex: none; }
+.captureRow { display: flex; align-items: center; gap: 12px; width: 100%; min-width: 0; min-height: 34px; }
+.roundButton { width: 32px; height: 32px; padding: 0; border-radius: 50%; corner-shape: round; flex: none; background: var(--dsw-specific-selector); }
+@media (hover: hover) {
+  .roundButton:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover-solid); }
+}
+.waveform { display: block; flex: 1; width: 0; height: 24px; min-width: 24px; color: var(--dsw-alias-label-secondary); }
+.activityMessage { display: flex; align-items: center; gap: 8px; flex: 1; min-width: 0; font-size: 12px; color: var(--dsw-alias-label-secondary); overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+.inlineAction { flex: none; }
+
+.preparation { display: flex; flex-direction: column; gap: 10px; padding: 14px; margin: 12px 0; border: 0.5px solid var(--dsw-alias-border-l1); border-radius: 10px; font-size: 13px; }
+.preparation p { margin: 0; }
+.preparationActions { display: flex; gap: 8px; }
+.preparationActions:empty { display: none; }
+.preparationError { color: var(--dsw-alias-state-error-primary); overflow-wrap: anywhere; font-size: 12px; }
+.downloadFailure { display: grid; gap: 6px; overflow-wrap: anywhere; }
+.summaryRow { min-height: 28px; height: auto; flex-wrap: wrap; gap: 4px; }
+.summaryTitle { flex: 1; min-width: 0; }
+.metric { font-size: 12px; color: var(--dsw-alias-label-tertiary); }
+.progress { width: 100%; height: 6px; accent-color: var(--dsw-alias-state-business-primary); }
+.steps { list-style: none; display: flex; flex-direction: column; gap: 14px; padding: 16px 0 2px; margin: 0; }
+.steps li { display: flex; align-items: flex-start; gap: 10px; line-height: 18px; }
+.steps li > :first-child { margin-top: 1px; }
+.steps li[data-step-state='pending'] { color: var(--dsw-alias-label-tertiary); }
+.stepBody { flex: 1; min-width: 0; }
+.stepProgress { display: flex; flex-direction: column; gap: 6px; margin-top: 6px; }
+.stepProgress small { font-size: 11px; color: var(--dsw-alias-label-tertiary); overflow-wrap: anywhere; }
+.preferences { display: grid; gap: 12px; font-size: 13px; margin: 18px 0; }
+.deviceRow, .preferences label, .sourceChoice label { display: grid; grid-template-columns: 100px minmax(120px, 280px); align-items: center; gap: 12px; }
+.preferences select, .sourceChoice select { border: 0.5px solid var(--dsw-alias-border-l1); border-radius: 6px; padding: 6px 10px; background: transparent; color: inherit; font: inherit; }
+.sourceChoice { display: grid; gap: 6px; }
+.preferences p { margin: 0; }
+.settingsCard { list-style: none; padding: 16px; border: 0.5px solid var(--dsw-alias-border-l1); border-radius: 10px; }
+.settingsCard > p { font-size: 13px; color: var(--dsw-alias-label-secondary); margin: 8px 0 0; }
+.setupEstimate { display: grid; gap: 10px; padding: 12px; border-radius: 8px; background: var(--dsw-alias-interactive-bg-hover); color: var(--dsw-alias-label-secondary); line-height: 1.6; }
+.setupEstimate dl { display: grid; gap: 6px; margin: 0; }
+.setupEstimate dl > div { display: grid; grid-template-columns: 72px minmax(0, 1fr); gap: 10px; }
+.setupEstimate dt { color: var(--dsw-alias-label-tertiary); }
+.setupEstimate dd { margin: 0; }
+.setupEstimate small { color: var(--dsw-alias-label-tertiary); font-size: 12px; }
+
+.deviceField { position: relative; display: block; min-width: 0; }
+.deviceField select { width: 100%; }
+.deviceField select.deviceSelectMeter { padding-right: 72px; }
+.deviceMeter { position: absolute; top: 50%; right: 24px; display: inline-flex; transform: translateY(-50%); pointer-events: none; }
+.deviceError { grid-column: 2; min-width: 0; color: var(--dsw-alias-state-error-primary); overflow-wrap: anywhere; font-size: 12px; }
+.inputLevel { display: inline-flex; align-items: center; gap: 3px; flex: none; }
+.inputLevel > span { width: 3px; height: 12px; border-radius: 1px; background: var(--dsw-alias-border-l1); }
+.inputLevel > span[data-active='true'] { background: var(--dsw-alias-state-success-primary); }
+@media (max-width: 480px) {
+  .deviceRow, .preferences label, .sourceChoice label { grid-template-columns: minmax(0, 1fr); gap: 6px; }
+
+  .deviceError { grid-column: 1; }
+}

package/src/client/VoiceInput.tsx

@@ -0,0 +1,182 @@
+/** Click-to-record toolbar activity; transcripts remain in the original Session draft. */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { HostObservable, InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { TokenSpan } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { TranscriptionRequest } from '@deepseek-ai/dsh-experimental-api-speech-to-text/types'
+import type { SpeechPreparationOptions, SpeechProviderId, SpeechSelection, SpeechSelectionPatch, Transcript } from '@deepseek-ai/dsh-experimental-speech-to-text/types'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { audioBase64, type Recording } from './audio.ts'
+import { failureText } from './failure-text.ts'
+import type { MicrophoneDevice } from './microphone-device.ts'
+import type { SpeechReadiness } from './readiness.ts'
+import { Waveform } from './Waveform.tsx'
+import { VoiceSetupDialog } from './VoiceSetupDialog.tsx'
+import { NS } from './locales.ts'
+import { Button, IconCloseOutlineRegular, IconStopFillRegular, IconMicrophoneOutlineRegular, StateDot, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
+import css from './VoiceInput.module.css'
+
+/** Host calls injected without exposing a Cordis Context to React. */
+export interface VoiceInputActions {
+  /** Open the voice bundle details without starting preparation. */
+  openSettings: () => void
+  /** @returns one microphone operation owned by the plugin lifecycle. */
+  createRecording: () => Recording
+  /** Remember the browser microphone used by previews and subsequent recordings. */
+  selectMicrophone: (device: MicrophoneDevice) => void
+  transcribe: (request: TranscriptionRequest, signal: AbortSignal) => Promise<RemoteResult<Transcript>>
+  prepare: (providerId: SpeechProviderId, options?: SpeechPreparationOptions) => Promise<void>
+  cancelPreparation: (providerId: SpeechProviderId) => Promise<void>
+  configure: (patch: SpeechSelectionPatch) => Promise<void>
+}
+
+/** Entry-injected Host readiness and microphone operations. */
+export interface VoiceInputInjected extends VoiceInputActions {
+  hooks: {
+    speechReadiness: HostObservable<SpeechReadiness>
+    microphoneDevice: HostObservable<MicrophoneDevice>
+    /** Whether the Plugins page navigation service is present; the setup dialog offers the details only while it is. */
+    pluginNavigation: HostObservable<boolean>
+  }
+}
+
+/** Composer-owned expansion and draft actions; preferences stay in plugin settings. */
+export type VoiceInputProps = Pick<PropsRuntime<'conversation.input.activity'>, 'sessionId' | 'inputActions' | 'locked' | 'onActiveChange'>
+  & PropsLocale<typeof NS> & InjectFace<VoiceInputInjected>
+
+type Phase = 'idle' | 'requesting' | 'recording' | 'transcribing' | 'feedback'
+interface ActiveRecording {
+  readonly capture: Recording
+  readonly abort: AbortController
+  readonly span: TokenSpan
+  readonly selection: SpeechSelection
+  readonly maxDurationSeconds: number
+  readonly maxAudioBytes: number
+  phase: 'requesting' | 'recording' | 'transcribing'
+  timer?: ReturnType<typeof setTimeout> | undefined
+}
+
+async function disposeRecording(capture: Recording): Promise<void> {
+  try { await capture.dispose() } catch (_error) {
+    // Tracks stop before AudioContext.close(); a close failure must not hide the recording result.
+  }
+}
+
+/** Render a compact microphone or an expanded capture, transcription, or retry row. */
+export function VoiceInput({ sessionId, inputActions, locked, onActiveChange,
+  createRecording, transcribe, openSettings, useSpeechReadiness, usePluginNavigation, t }: VoiceInputProps) {
+  const readiness = useSpeechReadiness(value => value), catalog = readiness.catalog
+  const navigable = usePluginNavigation(present => present)
+  const provider = catalog?.providers.find(item => item.id === catalog.selection.providerId)
+  const usable = readiness.connected && (provider?.preparation.phase === 'ready' || provider?.preparation.phase === 'standby'
+    || provider?.preparation.phase === 'waking')
+  const [phase, setPhase] = useState<Phase>('idle'), [message, setMessage] = useState(''), [pending, setPending] = useState('')
+  const [setupOpen, setSetupOpen] = useState(false)
+  useEffect(() => { if (usable) setSetupOpen(false) }, [usable])
+  const current = useRef<ActiveRecording>(), generation = useRef(0)
+  const expanded = phase !== 'idle'
+  useLayoutEffect(() => { onActiveChange(expanded); return () => { onActiveChange(false) } }, [expanded, onActiveChange])
+
+  const cancel = (): void => {
+    generation.current++
+    const active = current.current
+    current.current = undefined
+    if (active) { clearTimeout(active.timer); active.abort.abort(); void disposeRecording(active.capture) }
+    setPending(''); setMessage(''); setPhase('idle'); setSetupOpen(false)
+  }
+  useEffect(() => {
+    setPending(''); setMessage(''); setPhase('idle'); setSetupOpen(false)
+    const blur = (): void => { if (current.current?.phase === 'recording') cancel() }
+    const visibility = (): void => {
+      if (document.hidden && current.current && current.current.phase !== 'transcribing') cancel()
+    }
+    const escape = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape' && current.current) { event.preventDefault(); cancel() }
+    }
+    window.addEventListener('blur', blur); document.addEventListener('visibilitychange', visibility)
+    document.addEventListener('keydown', escape)
+    return () => {
+      window.removeEventListener('blur', blur); document.removeEventListener('visibilitychange', visibility)
+      document.removeEventListener('keydown', escape)
+      generation.current++
+      const active = current.current
+      current.current = undefined
+      if (active) { clearTimeout(active.timer); active.abort.abort(); void disposeRecording(active.capture) }
+    }
+  }, [sessionId])
+
+  const feedback = (text: string): void => { setMessage(text); setPhase('feedback') }
+  const finish = async (): Promise<void> => {
+    const active = current.current
+    if (!active || active.phase !== 'recording') return
+    active.phase = 'transcribing'
+    const run = generation.current
+    clearTimeout(active.timer); setPhase('transcribing')
+    try {
+      const audio = await active.capture.stop(active.maxDurationSeconds)
+      if (run !== generation.current) return
+      if (audio.byteLength > active.maxAudioBytes) { feedback(t('tooLarge')); return }
+      const result = await transcribe({ audioBase64: audioBase64(audio), ...active.selection }, active.abort.signal)
+      if (run !== generation.current) return
+      if (!result.ok) { feedback(t('failed', { message: result.error.message })); return }
+      if (result.value.text === '') { feedback(t('empty')); return }
+      if (!inputActions.insertText(result.value.text, active.span)) { setPending(result.value.text); feedback(t('conflict')); return }
+      setPhase('idle')
+    } catch (failure) {
+      await disposeRecording(active.capture)
+      if (run === generation.current) feedback(failureText(failure, t))
+    } finally { if (run === generation.current) current.current = undefined }
+  }
+  const start = async (): Promise<void> => {
+    if (!catalog || !usable || locked || current.current) return
+    const run = ++generation.current
+    const active: ActiveRecording = { capture: createRecording(), abort: new AbortController(),
+      span: inputActions.captureInsertion(), selection: catalog.selection,
+      maxDurationSeconds: catalog.maxDurationSeconds, maxAudioBytes: catalog.maxAudioBytes, phase: 'requesting' }
+    current.current = active
+    setMessage(''); setPending(''); setPhase('requesting')
+    try {
+      await active.capture.start((failure) => {
+        if (run !== generation.current || current.current !== active || active.phase === 'transcribing') return
+        current.current = undefined
+        clearTimeout(active.timer); active.abort.abort()
+        feedback(failureText(failure, t))
+      })
+      if (run !== generation.current || current.current !== active) return
+      active.phase = 'recording'
+      setPhase('recording')
+      active.timer = setTimeout(() => { void finish() }, active.maxDurationSeconds * 1000)
+    } catch (failure) {
+      await disposeRecording(active.capture)
+      if (run === generation.current) { current.current = undefined; feedback(failureText(failure, t)) }
+    }
+  }
+  if (!expanded) return <>
+    <Tooltip label={t('dictate')} disabled={!usable} side="top" portal>
+      <span className={css.triggerAnchor}><Button className={css.trigger} size="sm" disabled={locked}
+        aria-label={t(usable ? 'start' : 'setupPrompt.trigger')} aria-haspopup={usable ? undefined : 'dialog'}
+        onMouseDown={(event) => { event.preventDefault() }}
+        onClick={() => { if (usable) void start(); else setSetupOpen(true) }}><IconMicrophoneOutlineRegular size={18} /></Button></span>
+    </Tooltip>
+    <VoiceSetupDialog open={setupOpen && !usable}
+      needsInstallation={readiness.connected && provider?.location === 'host-local' && provider.preparation.phase === 'unprepared'}
+      onDismiss={() => { setSetupOpen(false) }}
+      onOpenDetails={navigable ? () => { setSetupOpen(false); openSettings() } : undefined} t={t} />
+  </>
+  return <div className={css.captureRow} data-voice-activity={phase}>
+    <Button type="button" className={css.roundButton} size="sm" aria-label={t(pending ? 'discard' : 'cancel')}
+      onClick={cancel}><IconCloseOutlineRegular size={14} /></Button>
+    {phase === 'recording' ? <Waveform recording={current.current?.capture} label={t('recording')} />
+      : <span className={css.activityMessage} role="status" title={pending || message}>
+        {(phase === 'requesting' || phase === 'transcribing') && <StateDot state="ongoing" />}
+        {phase === 'feedback' ? message : t(phase === 'requesting' ? 'requesting'
+          : provider?.preparation.phase === 'waking' ? 'wakingShort' : 'transcribingShort')}</span>}
+    {phase === 'recording' && <Button type="button" className={css.roundButton} size="sm" aria-label={t('stop')}
+      onClick={() => { void finish() }}><IconStopFillRegular size={14} /></Button>}
+    {phase === 'feedback' && (pending
+      ? <Button className={css.inlineAction} size="sm" type="button" onClick={() => {
+        if (inputActions.insertText(pending, inputActions.captureInsertion())) { setPending(''); setPhase('idle') }
+      }}>{t('insert')}</Button>
+      : <Button className={css.roundButton} size="sm" type="button" aria-label={t('retryRecording')} disabled={!usable || locked}
+        onClick={() => { void start() }}><IconMicrophoneOutlineRegular size={18} /></Button>)}
+  </div>
+}

package/src/client/VoiceSetupDialog.tsx

@@ -0,0 +1,32 @@
+/** Shared modal for voice activation and unavailable recognition. */
+import { Button, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-plugin-manager/client'
+import type { NS } from './locales.ts'
+
+type VoiceSetupDialogProps = PropsLocale<typeof NS>
+  & Pick<PropsRuntime<'plugins.bundle.activation'>, 'onDismiss'>
+  & {
+    open: boolean
+    needsInstallation: boolean
+    /** Open the plugin details; the details button is absent while it is undefined. */
+    onOpenDetails: PropsRuntime<'plugins.bundle.activation'>['onOpenDetails'] | undefined
+  }
+
+/**
+ * Guide activation or microphone clicks to the existing plugin details.
+ * @param props - visibility, installation need and navigation callbacks.
+ * @returns a dismissible prompt that never starts preparation or recording.
+ */
+export function VoiceSetupDialog({ open, needsInstallation, onDismiss, onOpenDetails, t }: VoiceSetupDialogProps) {
+  return <Modal open={open} title={t(needsInstallation ? 'setupPrompt.title' : 'setupPrompt.unavailableTitle')}
+    closeLabel={t('cancel')} onClose={onDismiss}
+    footer={<>
+      <Button variant="ghost" onClick={onDismiss}>{t('setupPrompt.later')}</Button>
+      {onOpenDetails !== undefined && <Button variant="primary" data-modal-autofocus onClick={onOpenDetails}>
+        {t(needsInstallation ? 'setupPrompt.open' : 'setupPrompt.details')}
+      </Button>}
+    </>}>
+    <p>{t(needsInstallation ? 'setupPrompt.body' : 'setupPrompt.unavailableBody')}</p>
+  </Modal>
+}

package/src/client/VoiceSetupPrompt.tsx

@@ -0,0 +1,27 @@
+/** Activation guidance after the Host inspects local recognition resources. */
+import { useEffect } from 'react'
+import { VoiceSetupDialog } from './VoiceSetupDialog.tsx'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-plugin-manager/client'
+import type { VoiceInputInjected } from './VoiceInput.tsx'
+import type { NS } from './locales.ts'
+
+/** Registration shares for the bundle's activation guidance. */
+export type VoiceSetupPromptProps = PropsRuntime<'plugins.bundle.activation'> & PropsLocale<typeof NS>
+  & Pick<InjectFace<VoiceInputInjected>, 'useSpeechReadiness'>
+
+/**
+ * Offer navigation to installation without starting a download.
+ * @param props - activation navigation and the shared Host readiness observer.
+ * @returns the shared modal only when the selected local provider needs preparation.
+ */
+export function VoiceSetupPrompt({ useSpeechReadiness, onDismiss, onOpenDetails, t }: VoiceSetupPromptProps) {
+  const readiness = useSpeechReadiness(value => value)
+  const provider = readiness.catalog?.providers.find(item => item.id === readiness.catalog?.selection.providerId)
+  const phase = readiness.connected ? provider?.preparation.phase : undefined
+  const needsSetup = phase === 'unprepared' && provider?.location === 'host-local'
+  useEffect(() => {
+    if (phase !== undefined && phase !== 'checking' && !needsSetup) onDismiss()
+  }, [phase, needsSetup, onDismiss])
+  return <VoiceSetupDialog open={needsSetup} needsInstallation onDismiss={onDismiss} onOpenDetails={onOpenDetails} t={t} />
+}

package/src/client/Waveform.tsx

@@ -0,0 +1,33 @@
+/** Live microphone amplitude history; animation updates SVG geometry without React state churn. */
+import { useEffect, useRef } from 'react'
+import type { Recording } from './audio.ts'
+import css from './VoiceInput.module.css'
+
+/** Render recent measured microphone levels; silent audio remains a dotted baseline. */
+export function Waveform({ recording, label }: { readonly recording: Recording | undefined; readonly label: string }) {
+  const svg = useRef<SVGSVGElement>(null)
+  useEffect(() => {
+    const bars = Array.from((svg.current as SVGSVGElement).querySelectorAll('line')).reverse()
+      .map(element => ({ element, level: 0 }))
+    let frame: number, previous = -Infinity
+    const draw = (now: number): void => {
+      if (now - previous >= 50) {
+        previous = now
+        let next = recording?.amplitude() ?? 0
+        for (const bar of bars) {
+          const previousLevel = bar.level
+          bar.level = next; next = previousLevel
+          const height = 1 + Math.min(1, bar.level * 5) * 17
+          bar.element.setAttribute('y1', String(20 - height)); bar.element.setAttribute('y2', String(20 + height))
+        }
+      }
+      frame = requestAnimationFrame(draw)
+    }
+    frame = requestAnimationFrame(draw)
+    return () => { cancelAnimationFrame(frame) }
+  }, [recording])
+  return <svg ref={svg} className={css.waveform} viewBox="0 0 640 40" preserveAspectRatio="none" role="img" aria-label={label}>
+    {Array.from({ length: 80 }, (_, index) => <line key={index} x1={index * 8 + 4} x2={index * 8 + 4}
+      y1="19" y2="21" stroke="currentColor" strokeWidth="3" strokeLinecap="round" opacity={0.25 + index / 120} />)}
+  </svg>
+}