@goodandready/dsh-voice 0.9.31 → 0.9.33

package/lib/client.js

@@ -248,6 +248,27 @@ window.__ModuleLoader__.load({
       'voiceActionsLabel': 'Voice action commands ("send", "cancel", "clear", "new line")',
       'liveInterimPreview': 'Live speech preview (ghost text preview)',
       'structuredPromptVoice': 'Spoken answers for interactive choice prompts',
+      'modeVerbatim': 'Verbatim',
+      'modeClean': 'Clean Text',
+      'modeTask': 'Agent Task',
+      'modeNote': 'Note',
+      'dictationModeTitle': 'Dictation Post-Processing Mode',
+      'dictationModeDesc': 'Select how dictated speech is processed before insertion: Verbatim (0 LLM calls), Clean text (formatting & filler removal), Agent task (structured prompt), or Note (key points & actions).',
+      'dictationPromptsTitle': 'Dictation Prompt Templates',
+      'dictationPromptsDesc': 'Custom prompt templates for dictation post-processing. Use {text} as placeholder for recognized speech.',
+      'promptClean': 'Clean text prompt',
+      'promptTask': 'Agent task prompt',
+      'promptNote': 'Note prompt',
+      'resetPrompts': 'Reset to defaults',
+      'voiceMacrosTitle': 'Voice Action Macros',
+      'voiceMacrosDesc': 'Spoken trigger phrases automatically expanded into structured prompt templates.',
+      'addMacro': 'Add macro',
+      'macroTrigger': 'Spoken trigger phrase',
+      'macroTemplate': 'Expanded prompt template',
+      'macroDelete': 'Delete',
+      'rawTab': 'Raw STT',
+      'resultTab': 'Result',
+      'llmUnavailableFallback': 'LLM unavailable, showing raw transcript',
       'jargonTitle': 'Developer Lexicon & IT Jargon',
       'techJargonCorrection': 'Auto-correct technical jargon (GitHub, Docker, pnpm, Kubernetes, etc.)',
       'jargonAdd': 'Add replacement',
@@ -258,6 +279,49 @@ window.__ModuleLoader__.load({
       'assistantSpeakingGated': 'Assistant speaking (gated mode)',
       'jargonFormatHint': ' (spoken -> replacement)',
       'errorPrefix': 'Error',
+      'wizardTitle': 'First-Run Setup & Diagnostics Wizard',
+      'wizardDesc': 'Step-by-step diagnostic test: check secure context, microphone permissions, audio level, and STT round-trip.',
+      'wizardBtnLaunch': 'Launch Mic & STT Wizard',
+      'wizardClose': 'Close Wizard',
+      'wizardStep1': '1. Audio & Environment',
+      'wizardStep2': '2. Live Signal Test',
+      'wizardStep3': '3. STT Transcription Test',
+      'wizardSecureContextOk': 'Secure context / HTTPS verified',
+      'wizardSecureContextBad': 'Insecure context (HTTPS or localhost required)',
+      'wizardMediaDevicesOk': 'Browser mediaDevices API supported',
+      'wizardMediaDevicesBad': 'Browser mediaDevices API missing',
+      'wizardMediaRecorderOk': 'MediaRecorder API supported',
+      'wizardMediaRecorderBad': 'MediaRecorder API unsupported in this browser',
+      'wizardMicPermissionOk': 'Microphone permission granted',
+      'wizardMicPermissionPrompt': 'Microphone permission not yet granted',
+      'wizardMicPermissionBad': 'Microphone permission denied',
+      'wizardRequestMic': 'Request Microphone Access',
+      'wizardMicLabel': 'Microphone input device:',
+      'wizardStartSignalCheck': 'Start Audio Level Test',
+      'wizardStopSignalCheck': 'Stop Audio Test',
+      'wizardSignalOk': 'Audio signal detected (RMS: {level}%)',
+      'wizardSignalZero': 'Zero audio level detected - speak into microphone or select correct device',
+      'wizardSignalTesting': 'Listening for audio signal… speak into your microphone',
+      'wizardProviderLabel': 'Active STT engine & model:',
+      'wizardProcessingArea': 'Processing area:',
+      'wizardAreaBrowser': 'In-browser (WebGPU / WebSpeech)',
+      'wizardAreaServer': 'Local MiniPC server (SenseVoice / Whisper)',
+      'wizardAreaCloud': 'Remote cloud provider',
+      'wizardStartTestRecord': 'Record 3-Second Test Phrase',
+      'wizardRecordingTest': 'Recording test phrase… speak now ({left}s)',
+      'wizardTranscribingTest': 'Transcribing test phrase…',
+      'wizardTestResult': 'STT Test Result:',
+      'wizardTestSuccess': 'STT round-trip verified successfully! Latency: {latency}ms',
+      'wizardTestEmpty': 'No speech detected in test recording. Please speak clearly and try again.',
+      'wizardTestFailed': 'STT test failed: {error}',
+      'wizardNextStepHint': 'Next step: {hint}',
+      'wizardHintPermission': 'Click "Request Microphone Access" and allow browser permission prompt.',
+      'wizardHintDevice': 'Check microphone connection or select a different input device.',
+      'wizardHintHttps': 'Open DeepSeek Harness via HTTPS or localhost address.',
+      'wizardHintProvider': 'Configure STT engine credentials or install SenseVoice model below.',
+      'wizardFinishSuccess': 'Setup & Verification Complete',
+      'wizardSkip': 'Skip Wizard',
+      'wizardStatusCompleted': 'Microphone and STT verified',
     }
 
     const zh = {
@@ -474,6 +538,27 @@ window.__ModuleLoader__.load({
       'voiceActionsLabel': '语音动作指令 ("发送", "取消", "清空", "换行")',
       'liveInterimPreview': '实时语音文本预览 (幽灵文本)',
       'structuredPromptVoice': '语音应答交互式选择提示',
+      'modeVerbatim': '逐字直录',
+      'modeClean': '清爽文本',
+      'modeTask': '智能体任务',
+      'modeNote': '便签备忘',
+      'dictationModeTitle': '听写后处理模式',
+      'dictationModeDesc': '选择听写文本后处理方式：逐字直录（零LLM调用）、清爽文本（整理标点去除语气词）、智能体任务（结构化提示词）或便签（要点与行动项）。',
+      'dictationPromptsTitle': '听写提示词模板',
+      'dictationPromptsDesc': '自定义听写后处理提示词模板。使用 {text} 作为识别语音的占位符。',
+      'promptClean': '清爽文本提示词',
+      'promptTask': '智能体任务提示词',
+      'promptNote': '便签提示词',
+      'resetPrompts': '恢复默认模板',
+      'voiceMacrosTitle': '语音动作宏',
+      'voiceMacrosDesc': '语音触发词自动展开为结构化提示词模板。',
+      'addMacro': '添加动作宏',
+      'macroTrigger': '语音触发短语',
+      'macroTemplate': '展开提示词模板',
+      'macroDelete': '删除',
+      'rawTab': '原始识别',
+      'resultTab': '处理结果',
+      'llmUnavailableFallback': 'LLM不可用，已保留原始识别文本',
       'jargonTitle': '开发者词汇与 IT 术语',
       'techJargonCorrection': '自动校正开发术语 (GitHub, Docker, pnpm, Kubernetes 等)',
       'jargonAdd': '添加替换项',
@@ -484,6 +569,49 @@ window.__ModuleLoader__.load({
       'assistantSpeakingGated': '助手正在发言（门控模式）',
       'jargonFormatHint': ' (口语 -> 替换文本)',
       'errorPrefix': '错误',
+      'wizardTitle': '首次启动与麦克风诊断向导',
+      'wizardDesc': '分步诊断检查：安全上下文、麦克风权限、音频信号电平及实时 STT 回环测试。',
+      'wizardBtnLaunch': '启动麦克风与 STT 诊断向导',
+      'wizardClose': '关闭向导',
+      'wizardStep1': '1. 音频与运行环境',
+      'wizardStep2': '2. 实时信号测试',
+      'wizardStep3': '3. STT 识别回环测试',
+      'wizardSecureContextOk': '安全上下文 / HTTPS 已验证',
+      'wizardSecureContextBad': '非安全上下文（需 HTTPS 或 localhost）',
+      'wizardMediaDevicesOk': '浏览器 mediaDevices API 支持正常',
+      'wizardMediaDevicesBad': '浏览器缺少 mediaDevices API 支持',
+      'wizardMediaRecorderOk': 'MediaRecorder API 支持正常',
+      'wizardMediaRecorderBad': '当前浏览器不支持 MediaRecorder API',
+      'wizardMicPermissionOk': '麦克风权限已授予',
+      'wizardMicPermissionPrompt': '尚未获得麦克风授权',
+      'wizardMicPermissionBad': '麦克风权限被拒绝',
+      'wizardRequestMic': '请求麦克风权限',
+      'wizardMicLabel': '麦克风输入设备：',
+      'wizardStartSignalCheck': '开始音频电平测试',
+      'wizardStopSignalCheck': '停止音频测试',
+      'wizardSignalOk': '检测到音频信号 (RMS: {level}%)',
+      'wizardSignalZero': '未检测到声音信号 — 请对着麦克风说话或选择正确设备',
+      'wizardSignalTesting': '正在监听声音信号… 请对着麦克风发声',
+      'wizardProviderLabel': '当前语音引擎与模型：',
+      'wizardProcessingArea': '处理区域：',
+      'wizardAreaBrowser': '浏览器端处理 (WebGPU / WebSpeech)',
+      'wizardAreaServer': '本地服务器处理 (SenseVoice / Whisper)',
+      'wizardAreaCloud': '远程云端服务',
+      'wizardStartTestRecord': '录制 3 秒测试语句',
+      'wizardRecordingTest': '正在录制测试音频… 请说话 ({left}秒)',
+      'wizardTranscribingTest': '正在请求语音识别…',
+      'wizardTestResult': 'STT 测试结果：',
+      'wizardTestSuccess': 'STT 链路验证成功！耗时：{latency}毫秒',
+      'wizardTestEmpty': '录音中未检测到有效语音，请清晰发音后重试。',
+      'wizardTestFailed': 'STT 测试失败：{error}',
+      'wizardNextStepHint': '建议下一步：{hint}',
+      'wizardHintPermission': '点击“请求麦克风权限”并在浏览器弹窗中允许访问。',
+      'wizardHintDevice': '检查麦克风硬件连接或切换选择其他输入设备。',
+      'wizardHintHttps': '请通过 HTTPS 或 localhost 访问 DeepSeek Harness。',
+      'wizardHintProvider': '请在下方配置 STT 密钥凭据或一键安装 SenseVoice 本地模型。',
+      'wizardFinishSuccess': '设置与验证已完成',
+      'wizardSkip': '跳过向导',
+      'wizardStatusCompleted': '麦克风与 STT 诊断已就绪',
     }
 
     // Strings are also needed outside components — in recording handlers and
@@ -547,7 +675,7 @@ window.__ModuleLoader__.load({
       '.dvo-preview-input:focus{border-color:var(--dsw-alias-state-info-primary)}' +
       '.dvo-btn-send{display:flex;align-items:center;justify-content:center;width:34px;height:34px;border-radius:50%;cursor:pointer;padding:0;flex:none;box-sizing:border-box;border:none;background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-1);transition:opacity 150ms ease}' +
       '.dvo-btn-send:hover{opacity:0.9}' +
-      '.dvo-warn-banner{font-size:12px;color:var(--dsw-alias-state-error-primary);background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent);border:1px solid var(--dsw-alias-state-error-primary);padding:4px 8px;border-radius:6px;margin-top:4px}'
+      '.dvo-warn-banner{font-size:12px;color:var(--dsw-alias-state-error-primary);background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent);border:1px solid var(--dsw-alias-state-error-primary);padding:4px 8px;border-radius:6px;margin-top:4px}' + '.dvo-mode-pill-btn{display:inline-flex;align-items:center;justify-content:center;height:28px;padding:0 8px;font-size:11px;font-weight:600;border-radius:14px;cursor:pointer;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-secondary);user-select:none;touch-action:manipulation;transition:all 150ms ease}' + '.dvo-mode-pill-btn:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-primary)}' + '.dvo-mode-badge{font-size:11px;font-weight:600;padding:2px 6px;border-radius:6px;background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);border:1px solid var(--dsw-alias-border-l2);margin-right:4px}' + '.dvo-macro-item{display:flex;flex-direction:column;gap:6px;padding:8px 10px;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l1);border-radius:8px;margin-top:6px}' + '.dvo-macro-actions{display:flex;justify-content:flex-end;gap:6px}' + '.dvo-fallback-badge{font-size:11px;padding:2px 6px;border-radius:4px;color:var(--dsw-alias-state-warning-primary);background:color-mix(in srgb, var(--dsw-alias-state-warning-primary) 12%, transparent);border:1px solid var(--dsw-alias-state-warning-primary)}'
     const cssId = 'dsh-voice/client.module.css'
     if (typeof document !== 'undefined' && !document.querySelector('style[data-dsh-plugin="dsh-voice"][data-plugin-css="' + cssId + '"]')) {
       const tag = document.createElement('style')
@@ -743,7 +871,26 @@ window.__ModuleLoader__.load({
 
     function extractContextKeywords() {
       if (!voice.settings || voice.settings.contextGlossary === false) return []
-      const text = (voice.input && typeof voice.input.draft === 'string') ? voice.input.draft : ''
+      const chunks = []
+      const draft = (voice.input && typeof voice.input.draft === 'string') ? voice.input.draft : ''
+      if (draft && draft.length >= 3) chunks.push(draft)
+      if (voice.session && Array.isArray(voice.session.messages)) {
+        const msgs = voice.session.messages.slice(-5)
+        for (const m of msgs) {
+          const t = (m && typeof m.content === 'string') ? m.content : ((m && typeof m.text === 'string') ? m.text : '')
+          if (t && t.length >= 3) chunks.push(t)
+        }
+      }
+      if (typeof document !== 'undefined') {
+        try {
+          const nodes = document.querySelectorAll('.message-content code, .dsh-message-body code, pre code')
+          for (let i = 0; i < Math.min(nodes.length, 10); i++) {
+            const ct = nodes[i].textContent
+            if (ct && ct.length < 100) chunks.push(ct)
+          }
+        } catch (_) {}
+      }
+      const text = chunks.join(' ')
       if (!text || text.length < 3) return []
       const matches = text.match(/[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{2,29}/g) || []
       // Linguistic filter: functional stop-word dictionary for vocabulary keyword extraction.
@@ -775,7 +922,11 @@ window.__ModuleLoader__.load({
 
       const tryHost = async (chainOverride) => {
         const dataBase64 = await blobToBase64(blob)
-        const payload = { dataBase64, mimeType: mime, mode }
+        const subMode = (voice._activeTarget && voice._activeTarget.dictationMode)
+          || voice.selectedDictationMode
+          || (voice.settings && voice.settings.dictationMode)
+          || 'clean'
+        const payload = { dataBase64, mimeType: mime, mode, subMode }
         if (Array.isArray(chainOverride)) {
           payload.chain = chainOverride.map((p) => (typeof p === 'string' ? { provider: p, model: modelMap[p] } : p))
         }
@@ -1491,7 +1642,10 @@ voice._chainsPromise = null
       const targetSession = voice.session || (targetInput && targetInput.session)
       const sessionId = (targetSession && (targetSession.sessionId || targetSession.id))
         || voice.currentSessionId || ''
-      const target = { actions: targetActions, input: targetInput, session: targetSession, span, initialDraft, sessionId }
+      const snapshotSubMode = voice.selectedDictationMode
+        || (voice.settings && voice.settings.dictationMode)
+        || 'clean'
+      const target = { actions: targetActions, input: targetInput, session: targetSession, span, initialDraft, sessionId, dictationMode: snapshotSubMode }
       voice._activeTarget = target
 
       if (voice.isTtsSpeaking) {
@@ -1738,7 +1892,15 @@ voice._chainsPromise = null
       if (v.phase !== 'idle' && v.phase !== 'error' && !hold.armed) return null
       const err = v.phase === 'error'
       const hk = voice.hotkey ? ` (${voice.hotkey})` : ''
+      const curMode = voice.selectedDictationMode || (voice.settings && voice.settings.dictationMode) || 'clean'
       return React.createElement(React.Fragment, null,
+        React.createElement('button', {
+          type: 'button',
+          className: 'dvo-mode-pill-btn',
+          title: t('dictationModeTitle') + ': ' + getDictationModeLabel(curMode, t),
+          'aria-label': t('dictationModeTitle') + ': ' + getDictationModeLabel(curMode, t),
+          onClick: cycleDictationMode,
+        }, getDictationModeLabel(curMode, t)),
         React.createElement('button', {
           type: 'button', className: 'dvo-btn', 'data-err': err ? '1' : '0',
           title: err ? v.error : t('dictationBtn'),
@@ -2208,6 +2370,25 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
       ? React.createElement('div', { className: 'dvo-warn-banner' }, t('sessionMismatch'))
       : null,
   )
+}
+// ------------------------------------------------------------------ 45-dictation
+// Dictation modes UI helper, mode cycler and labels (#264)
+
+const DICTATION_MODES = ['clean', 'task', 'note', 'verbatim']
+
+function getDictationModeLabel(m, t) {
+  const trans = t || moduleT
+  if (m === 'verbatim') return trans('modeVerbatim')
+  if (m === 'task') return trans('modeTask')
+  if (m === 'note') return trans('modeNote')
+  return trans('modeClean')
+}
+
+function cycleDictationMode() {
+  const cur = voice.selectedDictationMode || (voice.settings && voice.settings.dictationMode) || 'clean'
+  const nextIdx = (DICTATION_MODES.indexOf(cur) + 1) % DICTATION_MODES.length
+  voice.selectedDictationMode = DICTATION_MODES[nextIdx]
+  voice.notify()
 }
     // ----------------------------------------------------------- visualizers
     let _accentColorCache = { color: '', expires: 0 }
@@ -2530,7 +2711,12 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         // Live caption of what is heard right now. Until the browser emits a
         // final chunk the text is interim and changes on screen.
         const caption = voice.caption || (inBrowser ? '' : null)
+        const activeSubMode = (voice._activeTarget && voice._activeTarget.dictationMode)
+          || voice.selectedDictationMode
+          || (voice.settings && voice.settings.dictationMode)
+          || 'clean'
         return React.createElement('div', { className: 'dvo-pill', role: 'region', 'aria-label': t('title') },
+          React.createElement('span', { className: 'dvo-mode-badge' }, getDictationModeLabel(activeSubMode, t)),
           React.createElement('button', {
             type: 'button', className: 'dvo-pbtn', title: t('cancel'),
             'aria-label': t('cancel'),
@@ -2559,8 +2745,16 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
       }
 
       if (v.phase === 'processing') {
+        const activeSubMode = (voice._activeTarget && voice._activeTarget.dictationMode)
+          || voice.selectedDictationMode
+          || (voice.settings && voice.settings.dictationMode)
+          || 'clean'
         return React.createElement('div', { className: 'dvo-pill', role: 'region', 'aria-label': t('title') },
-          React.createElement('span', { className: 'dvo-status', 'aria-live': 'polite', 'aria-atomic': 'true' }, spinIcon(), t('transcribing')))
+          React.createElement('span', { className: 'dvo-status', 'aria-live': 'polite', 'aria-atomic': 'true' },
+            spinIcon(),
+            React.createElement('span', { className: 'dvo-mode-badge' }, getDictationModeLabel(activeSubMode, t)),
+            t('transcribing'),
+          ))
       }
 
       if (v.phase === 'pending') {
@@ -2677,6 +2871,9 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
                 voiceCommands: !!(data && data.voiceCommands),
                 vadSilenceMs: Number(data && data.modes && data.modes.dictation && data.modes.dictation.vadSilenceMs) || 700,
                 autoSendMs: Number(data && data.modes && data.modes.message && data.modes.message.autoSendMs) || 4000,
+                dictationMode: String((data && data.dictationMode) || 'clean'),
+                dictationPrompts: (data && data.dictationPrompts) || {},
+                voiceMacros: Array.isArray(data && data.voiceMacros) ? data.voiceMacros : [],
                 sendDelayMs: Number(data && data.modes && data.modes.dictation && data.modes.dictation.sendDelayMs) || 0,
                 stream: !!(data && data.modes && data.modes.dictation && data.modes.dictation.stream),
                 streamChunkMs: Number(data && data.modes && data.modes.dictation && data.modes.dictation.streamChunkMs) || 1200,
@@ -3016,6 +3213,93 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         ),
       )
     }
+// ------------------------------------------------------------------ 72-dictation-modes
+// Dictation modes configuration card and prompt template editors (#264)
+
+function DictationModesSection(props) {
+  const { t, draft, setTop, writable } = props
+  const prompts = (draft && draft.dictationPrompts) || {}
+  const currentMode = (draft && draft.dictationMode) || 'clean'
+
+  const setPrompt = (key, val) => {
+    const updated = { ...prompts, [key]: val }
+    setTop('dictationPrompts', updated)
+  }
+
+  const resetPrompts = () => {
+    setTop('dictationPrompts', { clean: '', task: '', note: '' })
+  }
+
+  return React.createElement('div', { className: 'cb-section-card' },
+    React.createElement('div', { className: 'cb-section-title' },
+      React.createElement('span', null, '🎙️ ' + t('dictationModeTitle')),
+    ),
+    React.createElement('div', { className: 'cb-field-desc' }, t('dictationModeDesc')),
+    React.createElement('div', { className: 'cb-grid-2', style: { marginTop: '8px' } },
+      ['clean', 'task', 'note', 'verbatim'].map((m) =>
+        React.createElement('label', { key: m, className: 'cb-check-label' },
+          React.createElement('input', {
+            type: 'radio',
+            name: 'dictationMode',
+            value: m,
+            checked: currentMode === m,
+            disabled: !writable,
+            onChange: () => setTop('dictationMode', m),
+          }),
+          getDictationModeLabel(m, t),
+        ),
+      ),
+    ),
+    React.createElement('div', { style: { marginTop: '12px', borderTop: '1px solid var(--dsw-alias-border-l1)', paddingTop: '10px' } },
+      React.createElement('div', { className: 'cb-section-title', style: { fontSize: '13px' } },
+        React.createElement('span', null, t('dictationPromptsTitle')),
+        React.createElement('button', {
+          type: 'button',
+          className: 'cb-btn cb-btn-secondary',
+          style: { fontSize: '11px', padding: '2px 8px' },
+          disabled: !writable,
+          onClick: resetPrompts,
+        }, t('resetPrompts')),
+      ),
+      React.createElement('div', { className: 'cb-field-desc' }, t('dictationPromptsDesc')),
+      React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: '8px', marginTop: '8px' } },
+        React.createElement('div', null,
+          React.createElement('label', { className: 'cb-label' }, t('promptClean')),
+          React.createElement('textarea', {
+            className: 'cb-input',
+            style: { minHeight: '48px', resize: 'vertical' },
+            value: prompts.clean || '',
+            placeholder: 'Default: punctuation & filler-word cleanup',
+            disabled: !writable,
+            onChange: (e) => setPrompt('clean', e.target.value),
+          }),
+        ),
+        React.createElement('div', null,
+          React.createElement('label', { className: 'cb-label' }, t('promptTask')),
+          React.createElement('textarea', {
+            className: 'cb-input',
+            style: { minHeight: '48px', resize: 'vertical' },
+            value: prompts.task || '',
+            placeholder: 'Default: structured problem/outcome/constraints/criteria',
+            disabled: !writable,
+            onChange: (e) => setPrompt('task', e.target.value),
+          }),
+        ),
+        React.createElement('div', null,
+          React.createElement('label', { className: 'cb-label' }, t('promptNote')),
+          React.createElement('textarea', {
+            className: 'cb-input',
+            style: { minHeight: '48px', resize: 'vertical' },
+            value: prompts.note || '',
+            placeholder: 'Default: key points & action items summary',
+            disabled: !writable,
+            onChange: (e) => setPrompt('note', e.target.value),
+          }),
+        ),
+      ),
+    ),
+  )
+}
     // 5. Hardware & Audio Engines Card
     function HardwareOptionsCard(props) {
       const t = props.t || moduleT
@@ -3499,6 +3783,78 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         ),
       )
     }
+// ------------------------------------------------------------------ 72-macros
+// Voice action macros configuration card (#167)
+
+function MacrosSection(props) {
+  const { t, draft, setTop, writable } = props
+  const macros = Array.isArray(draft && draft.voiceMacros) ? draft.voiceMacros : []
+
+  const addMacro = () => {
+    const next = [...macros, { trigger: '', template: '' }]
+    setTop('voiceMacros', next)
+  }
+
+  const updateMacro = (idx, field, val) => {
+    const next = macros.map((item, i) => (i === idx ? { ...item, [field]: val } : item))
+    setTop('voiceMacros', next)
+  }
+
+  const removeMacro = (idx) => {
+    const next = macros.filter((_, i) => i !== idx)
+    setTop('voiceMacros', next)
+  }
+
+  return React.createElement('div', { className: 'cb-section-card' },
+    React.createElement('div', { className: 'cb-section-title' },
+      React.createElement('span', null, '⚡ ' + t('voiceMacrosTitle')),
+      React.createElement('button', {
+        type: 'button',
+        className: 'cb-btn cb-btn-secondary',
+        style: { fontSize: '11px', padding: '2px 8px' },
+        disabled: !writable,
+        onClick: addMacro,
+      }, '+ ' + t('addMacro')),
+    ),
+    React.createElement('div', { className: 'cb-field-desc' }, t('voiceMacrosDesc')),
+    macros.length === 0
+      ? React.createElement('div', { style: { fontStyle: 'italic', color: 'var(--dsw-alias-label-tertiary)', fontSize: '12px', marginTop: '6px' } },
+          'No macros configured.',
+        )
+      : React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: '8px', marginTop: '6px' } },
+          macros.map((m, idx) =>
+            React.createElement('div', { key: idx, className: 'dvo-macro-item' },
+              React.createElement('div', { style: { display: 'flex', gap: '8px', alignItems: 'center' } },
+                React.createElement('input', {
+                  type: 'text',
+                  className: 'cb-input',
+                  style: { flex: '1', height: '28px', fontSize: '12px' },
+                  placeholder: t('macroTrigger'),
+                  value: m.trigger || '',
+                  disabled: !writable,
+                  onChange: (e) => updateMacro(idx, 'trigger', e.target.value),
+                }),
+                React.createElement('button', {
+                  type: 'button',
+                  className: 'cb-btn cb-btn-secondary',
+                  style: { padding: '2px 6px', fontSize: '11px', color: 'var(--dsw-alias-state-error-primary)' },
+                  disabled: !writable,
+                  onClick: () => removeMacro(idx),
+                }, t('macroDelete')),
+              ),
+              React.createElement('textarea', {
+                className: 'cb-input',
+                style: { minHeight: '38px', resize: 'vertical', fontSize: '12px' },
+                placeholder: t('macroTemplate') + ' (use {text} for argument)',
+                value: m.template || '',
+                disabled: !writable,
+                onChange: (e) => updateMacro(idx, 'template', e.target.value),
+              }),
+            ),
+          ),
+        ),
+  )
+}
     // SenseVoice Local ASR (1-Click Setup)
     function SensevoiceSection(props) {
       const t = props.t || moduleT
@@ -3553,14 +3909,21 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
       const whisperRunning = props.whisperRunning
       const providerCount = props.providerCount
       const onRefresh = props.onRefresh
+      const onOpenWizard = props.onOpenWizard
 
       return React.createElement('div', { className: 'cb-section-card' },
         React.createElement('div', { className: 'cb-section-title' },
           React.createElement('span', null, t('statusTitle')),
-          React.createElement('button', {
-            type: 'button', className: 'cb-btn', style: { fontSize: '12px', padding: '4px 8px' },
-            onClick: onRefresh,
-          }, '🔄 ' + t('refreshStats')),
+          React.createElement('div', { style: { display: 'flex', gap: '8px', alignItems: 'center' } },
+            onOpenWizard ? React.createElement('button', {
+              type: 'button', className: 'cb-btn cb-btn-primary', style: { fontSize: '12px', padding: '4px 10px' },
+              onClick: onOpenWizard,
+            }, '✨ ' + t('wizardBtnLaunch')) : null,
+            React.createElement('button', {
+              type: 'button', className: 'cb-btn', style: { fontSize: '12px', padding: '4px 8px' },
+              onClick: onRefresh,
+            }, '🔄 ' + t('refreshStats')),
+          ),
         ),
         React.createElement('div', { className: 'cb-row', style: { alignItems: 'center', gap: '12px', flexWrap: 'wrap' } },
           React.createElement('span', { className: 'cb-badge ' + (hostOnline ? 'cb-badge-ok' : 'cb-badge-err') },
@@ -3652,7 +4015,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
       const [serverConfig, setServerConfig] = React.useState(null)
       const [configLoading, setConfigLoading] = React.useState(true)
       const [revision, setRevision] = React.useState(null)
-
       React.useEffect(() => {
         let alive = true
         fetch('/dsh-voice/config', { cache: 'no-store' })
@@ -3662,6 +4024,7 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
               setServerConfig(data.config)
               if (typeof data.revision === 'number') setRevision(data.revision)
               setDraft((curr) => curr || deepClone(data.config))
+              if (data.config.wizardCompleted !== true) setShowWizard(true)
             }
           })
           .catch(() => {})
@@ -3670,10 +4033,10 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           })
         return () => { alive = false }
       }, [])
-
       // Hotkey picker: not a name field — press the key you want.
       const [catching, setCatching] = React.useState(false)
       const [jargonInput, setJargonInput] = React.useState(null)
+      const [showWizard, setShowWizard] = React.useState(false)
       React.useEffect(() => {
         if (!catching) return undefined
         const onKey = (event) => {
@@ -3693,7 +4056,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         document.addEventListener('keydown', onKey, true)
         return () => document.removeEventListener('keydown', onKey, true)
       }, [catching, ctx])
-
       React.useEffect(() => {
         let alive = true
         const render = () => { if (alive && scope && typeof scope.getSnapshot === 'function') setSnap(scope.getSnapshot()) }
@@ -3701,7 +4063,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         const off = (scope && typeof scope.subscribe === 'function') ? scope.subscribe(render) : () => {}
         return () => { alive = false; off() }
       }, [scope])
-
       const [devices, setDevices] = React.useState([])
       React.useEffect(() => {
         if (!navigator.mediaDevices || !navigator.mediaDevices.enumerateDevices) return
@@ -3709,11 +4070,9 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           .then((list) => setDevices(list.filter((d) => d.kind === 'audioinput')))
           .catch(() => {})
       }, [])
-
       const ready = !!serverConfig || (!!snap && snap.status === 'ready')
       const value = (snap && snap.status === 'ready' && snap.value) ? snap.value : (serverConfig || {})
       const writable = ready
-
       React.useEffect(() => {
         if (ready) return undefined
         let tries = 0
@@ -3730,14 +4089,12 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         }, 1000)
         return () => clearInterval(timer)
       }, [ready])
-
       const deepClone = (obj) => {
         if (typeof structuredClone === 'function') {
           try { return structuredClone(obj) } catch (e) { /* fallback */ }
         }
         try { return JSON.parse(JSON.stringify(obj)) } catch (e) { return Object.assign({}, obj) }
       }
-
       const setTop = (key, val) => {
         setDraft((d) => Object.assign({}, d || {}, { [key]: val }))
       }
@@ -3758,9 +4115,7 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         }),
         hint ? React.createElement('span', { className: 'dvs-sub' }, hint) : null,
       )
-
       React.useEffect(() => { if (ready && draft === null) setDraft(deepClone(value)) }, [ready, draft, value])
-
       React.useEffect(() => {
         if (!ready) return
         const val = value || {}
@@ -3792,10 +4147,12 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           techJargonCorrection: val.techJargonCorrection !== false,
           liveInterimPreview: val.liveInterimPreview !== false,
           structuredPromptVoice: val.structuredPromptVoice !== false,
+          dictationMode: val.dictationMode || 'clean',
+          dictationPrompts: val.dictationPrompts || {},
+          voiceMacros: Array.isArray(val.voiceMacros) ? val.voiceMacros : [],
           webgpuModel: String(val.webgpuModel || (voice.settings && voice.settings.webgpuModel) || 'onnx-community/whisper-tiny'),
         })
       }, [ready, value])
-
       const [statusData, setStatusData] = React.useState(null)
       const [statusLatency, setStatusLatency] = React.useState(null)
       const fetchStatus = React.useCallback(() => {
@@ -3819,17 +4176,12 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             setStatusLatency(null)
           })
       }, [])
-
       React.useEffect(() => {
         fetchStatus()
       }, [fetchStatus])
-
       const { sensevoiceState, installingSensevoice, triggerInstallSensevoice } = useSensevoiceInstaller(fetchStatus)
-
       const { testingMic, testLevel, toggleTestMic, gateDbVal, gateThresholdPercent } = useMicTester(draft, value, setErr)
-
       const { updaterStatus, updating, updaterMsg, updaterMsgKind, updaterLoading, checkUpdater, onUpdateNow } = usePluginUpdater()
-
       const save = async () => {
         setErr(''); setSaved(false)
         if (!draft) return
@@ -3848,7 +4200,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             .filter(Boolean)
           draft.jargonDictionary = parsed
         }
-
         let httpOk = false
         let httpError = null
         try {
@@ -3870,7 +4221,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         } catch (e) {
           httpError = e?.message || String(e)
         }
-
         if (httpOk && scope && typeof scope.set === 'function') {
           for (const k of Object.keys(draft)) {
             try {
@@ -3880,12 +4230,10 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             }
           }
         }
-
         if (!httpOk) {
           setErr(t('saveFailed') + ': ' + httpError)
           return
         }
-
         const d = draft || {}
         voice.hotkey = d.hotkey || ''
         if (voice.hotkey) {
@@ -3917,23 +4265,19 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           structuredPromptVoice: d.structuredPromptVoice !== false,
         })
         try { window.dispatchEvent(new CustomEvent('dsh-voice:settings-saved')) } catch (noEvents) { /* nobody */ }
-
         setSaved(true); setJargonInput(null)
         setTimeout(() => setSaved(false), 2000)
         fetchStatus()
       }
-
       const modeVal = (mode, key, fallback) => {
         const m = draft && draft[mode]
         return m && m[key] !== undefined ? m[key] : fallback
       }
-
       const chainOptions = BUILTIN.concat(
         (draft && Array.isArray(draft.customProviders) ? draft.customProviders : [])
           .map((c) => String(c && c.key || '').trim())
           .filter((k) => k && BUILTIN.indexOf(k) < 0),
       )
-
       const langField = (mode) => {
         const val = modeVal(mode, 'language', '')
         const opts = SUPPORTED_LANGS.slice()
@@ -3950,7 +4294,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           ))),
         )
       }
-
       const numField = (mode, key, label, hint) => React.createElement('div', { className: 'cb-field' },
         React.createElement('label', null, label),
         React.createElement('input', {
@@ -3959,15 +4302,11 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         }),
         React.createElement('span', { className: 'dvs-sub' }, hint),
       )
-
-
       const statsData = (statusData && statusData.providerStats) || {}
       const hostOnline = statusLatency !== null
       const whisperRunning = !!(statusData && statusData.whisperRunning)
       const providerCount = (statusData && Array.isArray(statusData.providers)) ? statusData.providers.length : chainOptions.length
-
       return React.createElement('div', { className: 'cb-page dvo-settings-root' },
-        // 1. Connection & Engine Status Card
         React.createElement(ConnectionStatusCard, {
           t: t,
           hostOnline: hostOnline,
@@ -3975,9 +4314,15 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           whisperRunning: whisperRunning,
           providerCount: providerCount,
           onRefresh: fetchStatus,
+          onOpenWizard: () => setShowWizard((v) => !v),
         }),
-
-        // 2. Dictation Mode Card
+        showWizard ? React.createElement(FirstRunWizard, {
+          t: t,
+          draft: draft,
+          setTop: setTop,
+          writable: writable,
+          onClose: () => setShowWizard(false),
+        }) : null,
         React.createElement('div', { className: 'cb-section-card' },
           React.createElement('div', { className: 'cb-section-title' },
             React.createElement('span', null, '🎙️ ' + t('dictationBtn')),
@@ -4021,8 +4366,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           ),
           textField('wakeWord', t('wakeWord'), t('wakeWordHint')),
         ),
-
-        // 3. Voice Message Card
         React.createElement('div', { className: 'cb-section-card' },
           React.createElement('div', { className: 'cb-section-title' },
             React.createElement('span', null, '💬 ' + t('messageTitle')),
@@ -4061,8 +4404,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             ),
           ),
         ),
-
-        // 4. Custom Providers Card
         React.createElement('div', { className: 'cb-section-card' },
           React.createElement('div', { className: 'cb-section-title' },
             React.createElement('span', null, '⚙️ ' + t('customTitle')),
@@ -4074,8 +4415,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             onChange: (v) => setTop('customProviders', v),
           }),
         ),
-
-        // 5. Hardware & Audio Engines Card
         React.createElement(HardwareOptionsCard, {
           t: t,
           draft: draft,
@@ -4095,8 +4434,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             clearGlobalHotkey()
           },
         }),
-
-        // 6. SenseVoice Local ASR (1-Click Setup)
         React.createElement(SensevoiceSection, {
           t: t,
           sensevoiceState: sensevoiceState,
@@ -4104,8 +4441,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           writable: writable,
           onInstall: triggerInstallSensevoice,
         }),
-
-        // 7. Turn-Taking & Audio Coordination
         React.createElement('div', { className: 'cb-section-card' },
           React.createElement('div', { className: 'cb-section-title' },
             React.createElement('span', null, '🎙️ ' + t('turnTakingTitle')),
@@ -4132,8 +4467,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             ),
           ),
         ),
-
-        // 8. Hands-free & Smart Actions
         React.createElement('div', { className: 'cb-section-card' },
           React.createElement('div', { className: 'cb-section-title' },
             React.createElement('span', null, '✨ ' + t('smartActionsTitle')),
@@ -4177,8 +4510,20 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
             ),
           ),
         ),
-
-        // 9. Developer Lexicon & IT Jargon
+        // Dictation Modes & Prompts (#264)
+        React.createElement(DictationModesSection, {
+          t: t,
+          draft: draft,
+          setTop: setTop,
+          writable: writable,
+        }),
+        // Voice Action Macros (#167)
+        React.createElement(MacrosSection, {
+          t: t,
+          draft: draft,
+          setTop: setTop,
+          writable: writable,
+        }),
         React.createElement(JargonEditor, {
           t: t,
           draft: draft,
@@ -4187,15 +4532,11 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           jargonInput: jargonInput,
           setJargonInput: setJargonInput,
         }),
-
-        // 10. Provider Telemetry & Latency Dashboard
         React.createElement(ProviderDashboard, {
           t: t,
           statsData: statsData,
           onRefresh: fetchStatus,
         }),
-
-        // 7. Plugin Version & Updates Card
         React.createElement(UpdaterCard, {
           t: t,
           updaterStatus: updaterStatus,
@@ -4206,8 +4547,6 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
           onCheck: checkUpdater,
           onUpdateNow: onUpdateNow,
         }),
-
-        // Action bar (Save)
         React.createElement('div', { className: 'cb-row' },
           React.createElement('button', { type: 'button', className: 'cb-btn cb-btn-primary', disabled: !writable, onClick: save }, t('save')),
           saved ? React.createElement('span', { className: 'dvs-ok' }, t('saved')) : null,
@@ -4215,6 +4554,395 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
         ),
       )
     }
+    // ------------------------------------------------------- first-run wizard (#265)
+    function FirstRunWizard(props) {
+      const t = props.t || moduleT
+      const draft = props.draft
+      const setTop = props.setTop
+      const writable = props.writable
+      const onClose = props.onClose
+
+      const isSecure = typeof window !== 'undefined' ? (window.isSecureContext || window.location.protocol === 'https:' || window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1') : true
+      const hasMediaDevices = typeof navigator !== 'undefined' && !!navigator.mediaDevices && typeof navigator.mediaDevices.getUserMedia === 'function'
+      const hasMediaRecorder = typeof MediaRecorder !== 'undefined'
+
+      const [micPermission, setMicPermission] = React.useState('prompt')
+      const [devices, setDevices] = React.useState([])
+      const [selectedDev, setSelectedDev] = React.useState((draft && draft.micDeviceId) || '')
+      const [signalTesting, setSignalTesting] = React.useState(false)
+      const [currentRms, setCurrentRms] = React.useState(0)
+      const [peakRms, setPeakRms] = React.useState(0)
+      const [testingStt, setTestingStt] = React.useState(false)
+      const [testCountdown, setTestCountdown] = React.useState(0)
+      const [testResult, setTestResult] = React.useState(null)
+      const [testError, setTestError] = React.useState('')
+      const [testLatency, setTestLatency] = React.useState(null)
+
+      const signalStreamRef = React.useRef(null)
+      const audioCtxRef = React.useRef(null)
+      const animFrameRef = React.useRef(null)
+
+      React.useEffect(() => {
+        if (typeof navigator !== 'undefined' && navigator.permissions && navigator.permissions.query) {
+          navigator.permissions.query({ name: 'microphone' })
+            .then((p) => {
+              if (p) {
+                setMicPermission(p.state)
+                p.onchange = () => setMicPermission(p.state)
+              }
+            })
+            .catch(() => {})
+        }
+      }, [])
+
+      const refreshDevices = () => {
+        if (!navigator.mediaDevices || !navigator.mediaDevices.enumerateDevices) return
+        navigator.mediaDevices.enumerateDevices()
+          .then((list) => {
+            const audioInputs = list.filter((d) => d.kind === 'audioinput')
+            setDevices(audioInputs)
+          })
+          .catch(() => {})
+      }
+
+      React.useEffect(() => {
+        refreshDevices()
+      }, [])
+
+      const stopSignalTest = () => {
+        if (animFrameRef.current) {
+          cancelAnimationFrame(animFrameRef.current)
+          animFrameRef.current = null
+        }
+        if (signalStreamRef.current) {
+          try { signalStreamRef.current.getTracks().forEach((trk) => trk.stop()) } catch (_) {}
+          signalStreamRef.current = null
+        }
+        if (audioCtxRef.current) {
+          try { audioCtxRef.current.close() } catch (_) {}
+          audioCtxRef.current = null
+        }
+        setSignalTesting(false)
+        setCurrentRms(0)
+      }
+
+      React.useEffect(() => {
+        return () => {
+          stopSignalTest()
+        }
+      }, [])
+
+      const requestPermissionAndTestSignal = async () => {
+        stopSignalTest()
+        setTestError('')
+        try {
+          const constraints = {
+            audio: selectedDev ? { deviceId: { exact: selectedDev } } : true,
+          }
+          const stream = await navigator.mediaDevices.getUserMedia(constraints)
+          signalStreamRef.current = stream
+          setMicPermission('granted')
+          refreshDevices()
+
+          const AC = typeof AudioContext !== 'undefined' ? AudioContext
+            : (typeof webkitAudioContext !== 'undefined' ? webkitAudioContext : null)
+          if (!AC) return
+          const actx = new AC()
+          audioCtxRef.current = actx
+          if (actx.state === 'suspended') { actx.resume().catch(() => {}) }
+          const src = actx.createMediaStreamSource(stream)
+          const analyser = actx.createAnalyser()
+          analyser.fftSize = 128
+          src.connect(analyser)
+
+          setSignalTesting(true)
+          const buf = new Uint8Array(analyser.frequencyBinCount)
+
+          const checkLevel = () => {
+            if (!signalStreamRef.current) return
+            analyser.getByteFrequencyData(buf)
+            let sum = 0
+            for (let i = 0; i < buf.length; i++) sum += buf[i]
+            const rms = Math.min(100, Math.round((sum / buf.length / 255) * 100 * 2.2))
+            setCurrentRms(rms)
+            setPeakRms((prev) => Math.max(prev, rms))
+            animFrameRef.current = requestAnimationFrame(checkLevel)
+          }
+          animFrameRef.current = requestAnimationFrame(checkLevel)
+        } catch (err) {
+          setMicPermission('denied')
+          setTestError(String(err && err.message ? err.message : err))
+          stopSignalTest()
+        }
+      }
+
+      const runSttTest = async () => {
+        stopSignalTest()
+        setTestError('')
+        setTestResult(null)
+        setTestLatency(null)
+        setTestingStt(true)
+        setTestCountdown(3)
+
+        let testStream = null
+        let recorder = null
+        const chunks = []
+
+        try {
+          const constraints = {
+            audio: selectedDev ? { deviceId: { exact: selectedDev } } : true,
+          }
+          testStream = await navigator.mediaDevices.getUserMedia(constraints)
+          let mime = 'audio/webm;codecs=opus'
+          if (!MediaRecorder.isTypeSupported(mime)) mime = ''
+          recorder = mime ? new MediaRecorder(testStream, { mimeType: mime }) : new MediaRecorder(testStream)
+          recorder.ondataavailable = (e) => {
+            if (e.data && e.data.size > 0) chunks.push(e.data)
+          }
+          recorder.start()
+
+          let left = 3
+          const countdownTimer = setInterval(() => {
+            left -= 1
+            setTestCountdown(left)
+            if (left <= 0) {
+              clearInterval(countdownTimer)
+              if (recorder.state !== 'inactive') recorder.stop()
+            }
+          }, 1000)
+
+          await new Promise((resolve) => recorder.addEventListener('stop', resolve, { once: true }))
+
+          try { testStream.getTracks().forEach((trk) => trk.stop()) } catch (_) {}
+
+          const blob = new Blob(chunks, { type: mime || 'audio/webm' })
+          if (blob.size < 400) {
+            setTestError(t('wizardTestEmpty'))
+            setTestingStt(false)
+            return
+          }
+
+          setTestCountdown(0)
+          const startMs = Date.now()
+          const dataBase64 = await blobToBase64(blob)
+          const payload = {
+            dataBase64,
+            mimeType: mime || recorder.mimeType || 'audio/webm',
+            mode: 'dictation',
+            subMode: 'clean',
+          }
+
+          const res = await fetch('/dsh-voice/transcribe', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+          })
+          const data = await res.json()
+          const latency = Date.now() - startMs
+          setTestLatency(latency)
+
+          if (!res.ok || !data || !data.ok) {
+            const msg = (data && data.error && data.error.message) || `HTTP ${res.status}`
+            setTestError(msg)
+          } else {
+            const recognized = String(data.text || '').trim()
+            if (recognized) {
+              setTestResult(recognized)
+              if (typeof setTop === 'function') {
+                setTop('wizardCompleted', true)
+              }
+            } else {
+              setTestError(t('wizardTestEmpty'))
+            }
+          }
+        } catch (err) {
+          setTestError(String(err && err.message ? err.message : err))
+        } finally {
+          if (testStream) {
+            try { testStream.getTracks().forEach((trk) => trk.stop()) } catch (_) {}
+          }
+          setTestingStt(false)
+        }
+      }
+
+      // Determine active chain info
+      const dictationChain = (draft && draft.dictation && draft.dictation.chain) || []
+      const activeProvider = (dictationChain[0] && (dictationChain[0].provider || dictationChain[0])) || 'sensevoice'
+      let areaLabel = t('wizardAreaServer')
+      if (activeProvider === 'browser' || activeProvider === 'browser-webgpu') {
+        areaLabel = t('wizardAreaBrowser')
+      } else if (activeProvider !== 'sensevoice' && activeProvider !== 'local-whisper') {
+        areaLabel = t('wizardAreaCloud')
+      }
+
+      let nextStepHint = ''
+      if (!isSecure) {
+        nextStepHint = t('wizardHintHttps')
+      } else if (micPermission === 'denied') {
+        nextStepHint = t('wizardHintPermission')
+      } else if (peakRms === 0 && signalTesting) {
+        nextStepHint = t('wizardHintDevice')
+      } else if (testError) {
+        nextStepHint = t('wizardHintProvider')
+      }
+
+      return React.createElement('div', { className: 'cb-section-card', style: { borderColor: 'var(--dsw-alias-state-brand-primary)' } },
+        React.createElement('div', { className: 'cb-section-title' },
+          React.createElement('span', null, '✨ ' + t('wizardTitle')),
+          React.createElement('div', { style: { display: 'flex', gap: '8px' } },
+            testResult ? React.createElement('span', { className: 'cb-badge cb-badge-ok' }, '✓ ' + t('wizardStatusCompleted')) : null,
+            onClose ? React.createElement('button', {
+              type: 'button', className: 'cb-btn cb-btn-mini', onClick: onClose, title: t('wizardClose'),
+            }, '✕') : null,
+          ),
+        ),
+        React.createElement('div', { className: 'cb-section-desc' }, t('wizardDesc')),
+
+        // Step 1: Environment & Permissions
+        React.createElement('div', { className: 'dvs-card' },
+          React.createElement('div', { className: 'dvs-h' }, t('wizardStep1')),
+          React.createElement('div', { className: 'cb-row' },
+            React.createElement('span', { className: 'cb-badge ' + (isSecure ? 'cb-badge-ok' : 'cb-badge-err') },
+              isSecure ? ('✓ ' + t('wizardSecureContextOk')) : ('✗ ' + t('wizardSecureContextBad'))
+            ),
+            React.createElement('span', { className: 'cb-badge ' + (hasMediaDevices ? 'cb-badge-ok' : 'cb-badge-err') },
+              hasMediaDevices ? ('✓ ' + t('wizardMediaDevicesOk')) : ('✗ ' + t('wizardMediaDevicesBad'))
+            ),
+            React.createElement('span', { className: 'cb-badge ' + (hasMediaRecorder ? 'cb-badge-ok' : 'cb-badge-err') },
+              hasMediaRecorder ? ('✓ ' + t('wizardMediaRecorderOk')) : ('✗ ' + t('wizardMediaRecorderBad'))
+            ),
+            React.createElement('span', { className: 'cb-badge ' + (micPermission === 'granted' ? 'cb-badge-ok' : (micPermission === 'denied' ? 'cb-badge-err' : 'cb-badge-warn')) },
+              micPermission === 'granted' ? ('✓ ' + t('wizardMicPermissionOk')) : (micPermission === 'denied' ? ('✗ ' + t('wizardMicPermissionBad')) : ('· ' + t('wizardMicPermissionPrompt')))
+            ),
+          ),
+          React.createElement('div', { className: 'cb-field', style: { marginTop: '8px' } },
+            React.createElement('label', null, t('wizardMicLabel')),
+            React.createElement('div', { className: 'cb-row' },
+              React.createElement('select', {
+                value: selectedDev,
+                style: { flex: 1, minWidth: '240px' },
+                onChange: (e) => {
+                  setSelectedDev(e.target.value)
+                  if (typeof setTop === 'function') setTop('micDeviceId', e.target.value)
+                  stopSignalTest()
+                },
+              },
+                React.createElement('option', { value: '' }, 'Default System Microphone'),
+                devices.map((d) => React.createElement('option', { key: d.deviceId, value: d.deviceId }, d.label || `Microphone ${d.deviceId.slice(0, 8)}…`))
+              ),
+              React.createElement('button', {
+                type: 'button',
+                className: 'cb-btn',
+                onClick: requestPermissionAndTestSignal,
+              }, t('wizardRequestMic')),
+            ),
+          ),
+        ),
+
+        // Step 2: Live Audio Signal Test
+        React.createElement('div', { className: 'dvs-card' },
+          React.createElement('div', { className: 'dvs-h' }, t('wizardStep2')),
+          React.createElement('div', { className: 'cb-row', style: { alignItems: 'center' } },
+            React.createElement('button', {
+              type: 'button',
+              className: 'cb-btn ' + (signalTesting ? 'cb-btn-danger' : 'cb-btn-primary'),
+              onClick: signalTesting ? stopSignalTest : requestPermissionAndTestSignal,
+            }, signalTesting ? t('wizardStopSignalCheck') : t('wizardStartSignalCheck')),
+            signalTesting ? React.createElement('span', { className: 'dvs-sub' }, t('wizardSignalTesting')) : null,
+          ),
+          signalTesting ? React.createElement('div', { style: { marginTop: '8px', display: 'flex', flexDirection: 'column', gap: '6px' } },
+            React.createElement('div', {
+              style: {
+                height: '14px',
+                borderRadius: '7px',
+                background: 'var(--dsw-alias-bg-layer-1)',
+                border: '1px solid var(--dsw-alias-border-l1)',
+                overflow: 'hidden',
+                position: 'relative',
+              },
+            },
+              React.createElement('div', {
+                style: {
+                  width: `${currentRms}%`,
+                  height: '100%',
+                  background: currentRms > 5 ? 'var(--dsw-alias-state-success-primary)' : 'var(--dsw-alias-label-dimmed)',
+                  transition: 'width 0.05s linear',
+                },
+              }),
+            ),
+            React.createElement('span', { className: currentRms > 5 ? 'dvs-ok' : 'dvs-sub' },
+              currentRms > 5
+                ? t('wizardSignalOk').replace('{level}', currentRms)
+                : t('wizardSignalZero')
+            ),
+          ) : null,
+        ),
+
+        // Step 3: Transcription Round-Trip Test
+        React.createElement('div', { className: 'dvs-card' },
+          React.createElement('div', { className: 'dvs-h' }, t('wizardStep3')),
+          React.createElement('div', { className: 'cb-row' },
+            React.createElement('span', { className: 'dvs-sub' }, `${t('wizardProviderLabel')} ${activeProvider}`),
+            React.createElement('span', { className: 'cb-badge' }, `${t('wizardProcessingArea')} ${areaLabel}`),
+          ),
+          React.createElement('div', { className: 'cb-row', style: { marginTop: '8px' } },
+            React.createElement('button', {
+              type: 'button',
+              className: 'cb-btn cb-btn-primary',
+              disabled: testingStt || micPermission === 'denied',
+              onClick: runSttTest,
+            }, testingStt
+              ? (testCountdown > 0 ? t('wizardRecordingTest').replace('{left}', testCountdown) : t('wizardTranscribingTest'))
+              : t('wizardStartTestRecord')
+            ),
+          ),
+          testResult ? React.createElement('div', { style: { marginTop: '8px', display: 'flex', flexDirection: 'column', gap: '4px' } },
+            React.createElement('div', { className: 'dvs-ok' },
+              '✓ ' + t('wizardTestSuccess').replace('{latency}', testLatency || 0)
+            ),
+            React.createElement('blockquote', {
+              style: {
+                margin: '4px 0 0 0',
+                padding: '8px 12px',
+                borderRadius: '6px',
+                background: 'var(--dsw-alias-bg-layer-3)',
+                borderLeft: '4px solid var(--dsw-alias-state-success-primary)',
+                color: 'var(--dsw-alias-label-primary)',
+                fontStyle: 'italic',
+              },
+            }, `“${testResult}”`),
+          ) : null,
+          testError ? React.createElement('div', { className: 'cb-alert-err', style: { marginTop: '8px' } },
+            t('wizardTestFailed').replace('{error}', testError)
+          ) : null,
+        ),
+
+        // Next Step Hint / Feedback
+        nextStepHint ? React.createElement('div', { className: 'dvs-wait', style: { fontStyle: 'italic' } },
+          t('wizardNextStepHint').replace('{hint}', nextStepHint)
+        ) : null,
+
+        // Wizard Bottom Actions
+        React.createElement('div', { className: 'cb-row', style: { justifyContent: 'space-between', marginTop: '6px' } },
+          React.createElement('button', {
+            type: 'button',
+            className: 'cb-btn',
+            onClick: () => {
+              if (typeof setTop === 'function') setTop('wizardCompleted', true)
+              if (onClose) onClose()
+            },
+          }, t('wizardSkip')),
+          testResult ? React.createElement('button', {
+            type: 'button',
+            className: 'cb-btn cb-btn-primary',
+            onClick: () => {
+              if (typeof setTop === 'function') setTop('wizardCompleted', true)
+              if (onClose) onClose()
+            },
+          }, '✓ ' + t('wizardFinishSuccess')) : null,
+        ),
+      )
+    }
     // Card in Settings → Plugins → Plugin settings (#18)
     function PluginCard(props) {
       const page = !!(props && props.view === 'page')
@@ -4320,6 +5048,9 @@ function renderEditablePreviewPill(voice, v, isPlaying, setIsPlaying, audioRef)
       isAllowedInEditable,
       isHotkeyRelease,
       extractContextKeywords,
+      DICTATION_MODES,
+      getDictationModeLabel,
+      cycleDictationMode,
       resolveBrowserRecognitionLang,
       VoiceSection,
       cutPhrase,