@nextclaw/ui 0.25.1 → 0.25.2

package/src/features/chat/features/conversation/hooks/__tests__/use-chat-voice-input.test.tsx

@@ -26,21 +26,90 @@ const beginDraft = () => draft;
 beforeEach(() => {
   vi.useFakeTimers();
   recognition = new Recognition();
-  manager = new ChatVoiceInputManager(() => recognition);
+  manager = new ChatVoiceInputManager(() => recognition, async () => null);
   commit = vi.fn<(text?: string) => void>();
   draft = { commit, update: vi.fn(), cancel: vi.fn() };
   useChatVoiceShortcutStore.getState().setShortcut(null);
   vi.spyOn(document, 'hasFocus').mockReturnValue(true);
 });
 afterEach(() => {
-  manager.cancel();
+  act(() => { manager.cancel(); });
   vi.useRealTimers();
   vi.restoreAllMocks();
 });
 
 describe('dictation lifecycle', () => {
-  it('waits for the final transcript before opening settings without restarting recording', () => {
+  it('saves on exit only after the final tail arrives and closes without rolling back the draft', async () => {
+    manager.start('en', 'one', draft);
+    await Promise.resolve();
+    recognition.onstart?.();
+    recognition.result('hello');
+    manager.saveAndClose();
+    manager.saveAndClose();
+    expect(recognition.stop).toHaveBeenCalledOnce();
+    expect(commit).not.toHaveBeenCalled();
+    recognition.result('hello', 'tail');
+    recognition.onend?.();
+    expect(draft.update).toHaveBeenLastCalledWith('hello tail', '');
+    expect(commit).toHaveBeenCalledOnce();
+    expect(draft.cancel).not.toHaveBeenCalled();
+    expect(manager.getSnapshot().phase).toBe('idle');
+  });
+  it.each(['timeout', 'network'])('preserves visible dictation on explicit exit even if finalization reports %s', async (error) => {
+    manager.start('en', 'one', draft);
+    await Promise.resolve();
+    recognition.onstart?.();
+    recognition.onresult?.({ results: [{ isFinal: false, 0: { transcript: 'visible words' } }] });
+    manager.saveAndClose();
+    if (error === 'timeout') vi.advanceTimersByTime(8000);
+    else recognition.onerror?.({ error });
+    expect(commit).toHaveBeenCalledExactlyOnceWith();
+    expect(draft.cancel).not.toHaveBeenCalled();
+    expect(manager.getSnapshot().phase).toBe('idle');
+  });
+  it('does not count time spent in the explicit permission prompt as a speech-service timeout', async () => {
+    let resolveCheck!: (value: null) => void;
+    manager = new ChatVoiceInputManager(() => recognition,
+      () => new Promise<null>((resolve) => { resolveCheck = resolve; }));
+    manager.start('en', 'one', draft);
+    vi.advanceTimersByTime(30000);
+    expect(manager.getSnapshot().phase).toBe('starting');
+    resolveCheck(null);
+    await Promise.resolve();
+    expect(recognition.start).toHaveBeenCalledOnce();
+    vi.advanceTimersByTime(15000);
+    expect(manager.getSnapshot().error).toBe('timeout');
+  });
+  it('checks permission on retry and ignores a successful check after cancellation', async () => {
+    let resolveCheck!: (value: null) => void;
+    const check = vi.fn().mockResolvedValueOnce('permission')
+      .mockImplementationOnce(() => new Promise<null>((resolve) => { resolveCheck = resolve; }));
+    manager = new ChatVoiceInputManager(() => recognition, check);
+    manager.start('en', 'one', draft);
+    await Promise.resolve();
+    manager.start('en', 'one', draft);
+    expect(check).toHaveBeenCalledTimes(2);
+    manager.cancel();
+    resolveCheck(null);
+    await Promise.resolve();
+    expect(recognition.start).not.toHaveBeenCalled();
+    expect(manager.getSnapshot().phase).toBe('idle');
+  });
+  it('starts again after a successful permission check and identifies missing devices', async () => {
+    const check = vi.fn().mockResolvedValueOnce('no-device').mockResolvedValueOnce(null);
+    manager = new ChatVoiceInputManager(() => recognition, check);
+    manager.start('en', 'one', draft);
+    await Promise.resolve();
+    expect(manager.getSnapshot().error).toBe('no-device');
+    manager.start('en', 'one', draft);
+    await Promise.resolve();
+    expect(recognition.start).toHaveBeenCalledOnce();
+    recognition.onstart?.();
+    expect(manager.getSnapshot().phase).toBe('recording');
+  });
+  it('waits for the final transcript before opening settings without restarting recording', async () => {
     manager.start('zh', 'one', draft);
+    await Promise.resolve();
     recognition.onstart?.();
     recognition.result('first');
     manager.openSettings();
@@ -53,15 +122,17 @@ describe('dictation lifecycle', () => {
     manager.cancel();
     expect(recognition.start).toHaveBeenCalledOnce();
   });
-  it('still opens settings when finishing recognition fails', () => {
+  it('still opens settings when finishing recognition fails', async () => {
     manager.start('en', 'one', draft);
+    await Promise.resolve();
     recognition.onstart?.();
     manager.openSettings();
     recognition.onerror?.({ error: 'no-speech' });
     expect(manager.getSnapshot()).toMatchObject({ phase: 'ready', error: null, text: '', interim: '' });
   });
-  it('replaces cumulative results, waits for the final tail, and inserts once', () => {
+  it('replaces cumulative results, waits for the final tail, and inserts once', async () => {
     manager.start('zh', 'one', draft);
+    await Promise.resolve();
     expect(manager.getSnapshot().phase).toBe('starting');
     recognition.onstart?.();
     recognition.result('hello');
@@ -105,8 +176,9 @@ describe('dictation lifecycle', () => {
     expect(recognition.abort).toHaveBeenCalledOnce();
     expect(commit).not.toHaveBeenCalled();
   });
-  it('commits confirmed text on interruption without a second insertion', () => {
+  it('commits confirmed text on interruption without a second insertion', async () => {
     manager.start('en', 'one', draft);
+    await Promise.resolve();
     recognition.onstart?.();
     recognition.result('keep this');
     manager.interrupt();
@@ -114,11 +186,13 @@ describe('dictation lifecycle', () => {
     manager.cancel();
     expect(commit).toHaveBeenCalledOnce();
   });
-  it('times out startup and stopping and ends recording at 60 seconds', () => {
+  it('times out startup and stopping and ends recording at 60 seconds', async () => {
     manager.start('en', 'one', draft);
+    await Promise.resolve();
     vi.advanceTimersByTime(15000);
     expect(manager.getSnapshot().error).toBe('timeout');
     manager.start('en', 'one', draft);
+    await Promise.resolve();
     recognition.onstart?.();
     vi.advanceTimersByTime(60000);
     expect(manager.getSnapshot().phase).toBe('stopping');
@@ -126,18 +200,50 @@ describe('dictation lifecycle', () => {
     vi.advanceTimersByTime(8000);
     expect(manager.getSnapshot().error).toBe('timeout');
   });
-  it('handles unsupported APIs and thrown starts', () => {
+  it('handles unsupported APIs and thrown starts', async () => {
     const unsupported = new ChatVoiceInputManager(() => null);
     unsupported.start('en', 'one', draft);
     expect(unsupported.getSnapshot().error).toBe('unsupported');
     recognition.start.mockImplementation(() => { throw new Error('device'); });
     manager.start('en', 'one', draft);
+    await Promise.resolve();
     expect(manager.getSnapshot().error).toBe('failed');
   });
 
 });
 
 describe('keyboard and page integration', () => {
+  it('keeps a pending authorization alive across window blur and starts after permission is granted', async () => {
+    renderHook(() => useChatVoiceInput(manager, 'one', 'en', true, beginDraft));
+    act(() => { manager.start('en', 'one', draft); window.dispatchEvent(new Event('blur')); });
+    expect(manager.getSnapshot().phase).toBe('starting');
+    expect(recognition.abort).not.toHaveBeenCalled();
+    await act(async () => { await Promise.resolve(); recognition.onstart?.(); });
+    expect(manager.getSnapshot().phase).toBe('recording');
+  });
+  it.each(['visibilitychange', 'pagehide'])('cancels pending authorization on %s and ignores a late grant', (event) => {
+    renderHook(() => useChatVoiceInput(manager, 'one', 'en', true, beginDraft));
+    act(() => { manager.start('en', 'one', draft); });
+    const lateStart = recognition.onstart;
+    vi.spyOn(document, 'hidden', 'get').mockReturnValue(true);
+    act(() => { (event === 'pagehide' ? window : document).dispatchEvent(new Event(event)); lateStart?.(); });
+    expect(recognition.abort).toHaveBeenCalledOnce();
+    expect(manager.getSnapshot().phase).not.toBe('recording');
+  });
+  it('still interrupts active recording on window blur', async () => {
+    renderHook(() => useChatVoiceInput(manager, 'one', 'en', true, beginDraft));
+    await act(async () => { manager.start('en', 'one', draft); await Promise.resolve(); recognition.onstart?.(); window.dispatchEvent(new Event('blur')); });
+    expect(manager.getSnapshot().error).toBe('interrupted');
+    expect(recognition.abort).toHaveBeenCalledOnce();
+  });
+  it('still stops an active recording when the page becomes hidden', async () => {
+    renderHook(() => useChatVoiceInput(manager, 'one', 'en', true, beginDraft));
+    await act(async () => { manager.start('en', 'one', draft); await Promise.resolve(); recognition.onstart?.(); });
+    vi.spyOn(document, 'hidden', 'get').mockReturnValue(true);
+    act(() => { document.dispatchEvent(new Event('visibilitychange')); });
+    expect(manager.getSnapshot().error).toBe('interrupted');
+    expect(recognition.abort).toHaveBeenCalledOnce();
+  });
   const bind = (ctrl = false, alt = false) => useChatVoiceShortcutStore.getState().setShortcut({ code: 'KeyV', ctrl, meta: false, alt, shift: false });
   const key = (type: string, options: KeyboardEventInit = {}) => new KeyboardEvent(type, { code: 'KeyV', bubbles: true, cancelable: true, ...options });
   it('never steals paste, normal typing, or input-method composition', () => {
@@ -153,10 +259,10 @@ describe('keyboard and page integration', () => {
     expect(recognition.start).not.toHaveBeenCalled();
     input.remove();
   });
-  it('holds a configured combination and stops when a modifier is released', () => {
+  it('holds a configured combination and stops when a modifier is released', async () => {
     bind(true, true);
     renderHook(() => useChatVoiceInput(manager, 'one', 'en', true, beginDraft));
-    act(() => { window.dispatchEvent(key('keydown', { ctrlKey: true, altKey: true })); recognition.onstart?.(); });
+    await act(async () => { window.dispatchEvent(key('keydown', { ctrlKey: true, altKey: true })); await Promise.resolve(); recognition.onstart?.(); });
     expect(recognition.start).toHaveBeenCalledOnce();
     act(() => { window.dispatchEvent(key('keyup', { code: 'AltLeft', key: 'Alt' })); });
     expect(recognition.stop).toHaveBeenCalledOnce();

package/src/features/chat/features/conversation/hooks/use-chat-voice-input.ts

@@ -36,13 +36,26 @@ export function useChatVoiceInput(manager: ChatVoiceInputManager, context: strin
       if (held) manager.cancel();
     };
   }, [manager, context, language, keyboardEnabled, beginDraft, shortcut]);
+  useEffect(() => {
+    const onEscape = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || event.isComposing || ['idle', 'ready'].includes(manager.getSnapshot().phase)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      manager.saveAndClose();
+    };
+    window.addEventListener('keydown', onEscape, true);
+    return () => { window.removeEventListener('keydown', onEscape, true); };
+  }, [manager]);
   useEffect(() => {
     const onVisibility = () => { if (document.hidden) manager.interrupt(); };
-    window.addEventListener('blur', manager.interrupt);
+    // Native authorization prompts can blur the window before recognition starts.
+    // Actual page departure is handled independently, including pending requests.
+    const onBlur = () => { if (manager.getSnapshot().phase !== 'starting') manager.interrupt(); };
+    window.addEventListener('blur', onBlur);
     window.addEventListener('pagehide', manager.cancel);
     document.addEventListener('visibilitychange', onVisibility);
     return () => {
-      window.removeEventListener('blur', manager.interrupt);
+      window.removeEventListener('blur', onBlur);
       window.removeEventListener('pagehide', manager.cancel);
       document.removeEventListener('visibilitychange', onVisibility);
       manager.cancel();

package/src/features/chat/managers/chat-voice-input.manager.ts

@@ -1,7 +1,8 @@
 import type { ChatComposerDictationSession } from '@nextclaw/agent-chat-ui';
+import { checkMicrophoneAccess, classifyMicrophoneError } from '@/features/chat/utils/chat-voice-permissions.utils';
 
 export type VoicePhase = 'idle' | 'ready' | 'starting' | 'recording' | 'stopping' | 'error';
-export type VoiceError = 'unsupported' | 'permission' | 'network' | 'audio-capture' | 'no-speech' | 'interrupted' | 'timeout' | 'failed';
+export type VoiceError = 'unsupported' | 'permission' | 'service-denied' | 'no-device' | 'device-busy' | 'network' | 'audio-capture' | 'no-speech' | 'interrupted' | 'timeout' | 'failed';
 export type VoiceSnapshot = { phase: VoicePhase; text: string; interim: string; seconds: number; error: VoiceError | null };
 export type SpeechRecognitionLike = {
   lang: string;
@@ -33,9 +34,11 @@ export class ChatVoiceInputManager {
   private ticker: ReturnType<typeof setInterval> | undefined;
   private context = '';
   private settingsRequested = false;
+  private exitRequested = false;
   private draft: ChatComposerDictationSession | null = null;
 
-  constructor(private readonly createRecognition = createBrowserRecognition) {}
+  constructor(private readonly createRecognition = createBrowserRecognition,
+    private readonly checkMicrophone = checkMicrophoneAccess) {}
 
   getSnapshot = (): VoiceSnapshot => this.snapshot;
   subscribe = (listener: () => void): (() => void) => {
@@ -74,9 +77,19 @@ export class ChatVoiceInputManager {
       recognition.continuous = true;
       recognition.interimResults = true;
       this.connect(recognition);
+      void this.checkAndStart(recognition);
+    } catch (error) { this.fail(classifyMicrophoneError(error)); }
+  };
+  private checkAndStart = async (recognition: SpeechRecognitionLike): Promise<void> => {
+    try {
+      const error = await this.checkMicrophone();
+      if (this.recognition !== recognition || this.snapshot.phase !== 'starting') return;
+      if (error) { this.fail(error); return; }
       this.setDeadline(15000);
       recognition.start();
-    } catch { this.fail('failed'); }
+    } catch (error) {
+      if (this.recognition === recognition) this.fail(classifyMicrophoneError(error));
+    }
   };
   private connect = (recognition: SpeechRecognitionLike): void => {
     recognition.onstart = () => {
@@ -104,13 +117,14 @@ export class ChatVoiceInputManager {
     };
     recognition.onerror = ({ error }) => {
       if (this.recognition !== recognition) return;
-      const reason: VoiceError = error === 'not-allowed' || error === 'service-not-allowed'
+      const reason: VoiceError = error === 'service-not-allowed' ? 'service-denied' : error === 'not-allowed'
         ? 'permission'
         : error === 'network' || error === 'audio-capture' || error === 'no-speech' ? error : 'failed';
       this.fail(reason);
     };
     recognition.onend = () => {
       if (this.recognition !== recognition) return;
+      if (this.exitRequested) { this.release(false); this.acceptDraft(); return; }
       const text = this.snapshot.text.trim();
       this.release(false);
       if (!text) { this.fail('no-speech'); return; }
@@ -129,6 +143,12 @@ export class ChatVoiceInputManager {
     this.setDeadline(8000);
     try { this.recognition.stop(); } catch { this.fail('failed'); }
   };
+  saveAndClose = (): void => {
+    this.exitRequested = true;
+    if (this.snapshot.phase === 'recording') { this.finish(); return; }
+    if (this.snapshot.phase === 'stopping') return;
+    this.acceptDraft();
+  };
   interrupt = (): void => {
     if (isActive(this.snapshot.phase)) this.fail('interrupted');
   };
@@ -139,6 +159,7 @@ export class ChatVoiceInputManager {
   };
   cancel = (): void => {
     this.settingsRequested = false;
+    this.exitRequested = false;
     this.release();
     this.context = '';
     this.draft?.cancel();
@@ -146,6 +167,7 @@ export class ChatVoiceInputManager {
     this.update(initialSnapshot());
   };
   private fail = (error: VoiceError): void => {
+    if (this.exitRequested) { this.acceptDraft(); return; }
     this.release();
     if (this.snapshot.text) this.draft?.commit(this.snapshot.text);
     else this.draft?.cancel();

package/src/features/chat/utils/chat-voice-permissions.utils.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, expect, it, vi } from 'vitest';
+import { checkMicrophoneAccess, classifyMicrophoneError, voicePermissionInstructionKeys } from './chat-voice-permissions.utils';
+
+afterEach(() => vi.unstubAllGlobals());
+
+it.each([
+  ['NotAllowedError', 'permission'], ['NotFoundError', 'no-device'],
+  ['NotSupportedError', 'unsupported'],
+  ['NotReadableError', 'device-busy'], ['AbortError', 'device-busy'], ['Error', 'failed'],
+])('classifies %s from the actual media API', (name, expected) => {
+  expect(classifyMicrophoneError(new DOMException('microphone', name))).toBe(expected);
+});
+
+it('rechecks access and immediately releases every captured track', async () => {
+  const stop = vi.fn();
+  const getUserMedia = vi.fn().mockResolvedValue({ getTracks: () => [{ stop }, { stop }] });
+  vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
+  expect(await checkMicrophoneAccess()).toBeNull();
+  expect(getUserMedia).toHaveBeenCalledWith({ audio: true });
+  expect(stop).toHaveBeenCalledTimes(2);
+});
+
+it('reports unavailable media API and an actual denial without caching', async () => {
+  vi.stubGlobal('navigator', {});
+  expect(await checkMicrophoneAccess()).toBe('unsupported');
+  vi.stubGlobal('navigator', { mediaDevices: { getUserMedia: vi.fn().mockRejectedValue(new DOMException('', 'NotAllowedError')) } });
+  expect(await checkMicrophoneAccess()).toBe('permission');
+});
+
+it.each([
+  ['Macintosh Chrome', 'Mac'], ['Windows Chrome', 'Windows'], ['iPhone', 'Ios'],
+  ['Android Chrome', 'Android'], ['Linux', 'System'],
+])('offers instructions matching %s', (ua, platform) => {
+  expect(voicePermissionInstructionKeys(ua)).toEqual(['chatInputVoicePermissionBrowser', `chatInputVoicePermission${platform}`]);
+  expect(voicePermissionInstructionKeys(`${ua} Electron`)[0]).toBe('chatInputVoicePermissionDesktop');
+});

package/src/features/chat/utils/chat-voice-permissions.utils.ts

@@ -0,0 +1,31 @@
+export type MicrophoneError = 'permission' | 'no-device' | 'device-busy' | 'unsupported' | 'failed';
+
+export function classifyMicrophoneError(error: unknown): MicrophoneError {
+  const name = error instanceof DOMException || error instanceof Error ? error.name : '';
+  if (name === 'NotSupportedError') return 'unsupported';
+  if (name === 'NotAllowedError' || name === 'SecurityError') return 'permission';
+  if (name === 'NotFoundError' || name === 'DevicesNotFoundError') return 'no-device';
+  if (name === 'NotReadableError' || name === 'AbortError') return 'device-busy';
+  return 'failed';
+}
+
+/** Check on explicit start/retry; release every track even if the panel was closed. */
+export async function checkMicrophoneAccess(): Promise<MicrophoneError | null> {
+  if (!navigator.mediaDevices?.getUserMedia) return 'unsupported';
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    stream.getTracks().forEach((track) => track.stop());
+    return null;
+  } catch (error) {
+    return classifyMicrophoneError(error);
+  }
+}
+
+export function voicePermissionInstructionKeys(userAgent: string): string[] {
+  const system = /iPhone|iPad|iPod/i.test(userAgent) ? 'chatInputVoicePermissionIos'
+    : /Android/i.test(userAgent) ? 'chatInputVoicePermissionAndroid'
+    : /Macintosh|Mac OS X/i.test(userAgent) ? 'chatInputVoicePermissionMac'
+    : /Windows/i.test(userAgent) ? 'chatInputVoicePermissionWindows'
+    : 'chatInputVoicePermissionSystem';
+  return [/Electron/i.test(userAgent) ? 'chatInputVoicePermissionDesktop' : 'chatInputVoicePermissionBrowser', system];
+}

package/src/shared/lib/i18n/locales/en-US/chat.json

@@ -640,17 +640,32 @@
   "chatInputAttachmentTooLarge": "Files must be {maxMb} MB or smaller.",
   "chatInputAttachmentReadFailed": "Failed to read the file. Please try again.",
   "chatInputVoice": "Voice input",
-  "chatInputVoicePermissionDenied": "Microphone permission was denied. Allow it in the browser or system settings and retry.",
+  "chatInputVoicePermissionDenied": "Microphone access was denied. The browser may not distinguish site permission from system permission. Check the following settings.",
+  "chatInputVoicePermissionPurpose": "Voice input uses your microphone to turn speech into a draft. Choose Allow when prompted; review the text before sending it.",
+  "chatInputVoiceCheckAndRetry": "Check microphone and retry",
+  "chatInputVoicePermissionRetryHint": "After allowing access, select “Check microphone and retry”. If the system requires an app restart, save your draft before reopening your browser or NextClaw.",
+  "chatInputVoicePermissionBrowser": "Open the site information or permissions menu beside the address bar and allow Microphone for this site. Alternatively, search browser settings for Microphone and check whether this site is blocked.",
+  "chatInputVoicePermissionDesktop": "Check that the system allows NextClaw to use the microphone. If access is already allowed, reopen NextClaw and retry.",
+  "chatInputVoicePermissionMac": "macOS: open System Settings → Privacy & Security → Microphone, and allow your browser or NextClaw.",
+  "chatInputVoicePermissionWindows": "Windows: open Settings → Privacy & security (Privacy on Windows 10) → Microphone. Enable microphone access and access for desktop apps.",
+  "chatInputVoicePermissionIos": "iPhone / iPad: check Microphone in the browser’s website settings. Also check Settings → Privacy & Security → Microphone for browser access, if listed.",
+  "chatInputVoicePermissionAndroid": "Android: open Settings → Apps → your browser → Permissions → Microphone and allow access. Also check this website’s browser permissions.",
+  "chatInputVoicePermissionSystem": "In system sound settings, select an available input device and check whether microphone access is restricted for your browser or NextClaw.",
+  "chatInputVoiceNoDevice": "No microphone was detected. Connect or enable an input device, then check again.",
+  "chatInputVoiceDeviceBusy": "The microphone cannot be read. Another app or a system restriction may be preventing access. Close other recording apps, check your input device and retry.",
+  "chatInputVoiceServiceDenied": "The browser denied access to speech recognition. Check its speech service settings or organization policy, or use a browser that supports speech recognition.",
   "chatInputVoiceUnsupported": "Speech input is not supported in this browser.",
   "chatInputVoiceNoSpeech": "Could not hear you. Please try again.",
   "chatInputVoiceFailed": "Voice input failed. Please try again.",
   "chatInputVoicePrivacy": "Click to dictate at the cursor. Underlined words are still being recognized. Your browser may process audio online. Nothing is sent automatically.",
   "chatInputVoiceStart": "Start recording",
   "chatInputVoiceFinish": "Finish recording",
+  "chatInputVoiceSaveAndClose": "Save and close",
+  "chatInputVoiceEscapeHint": "Press Esc to save dictation and close",
   "chatInputVoiceCancel": "Cancel",
-  "chatInputVoiceStarting": "Connecting to microphone…",
+  "chatInputVoiceStarting": "Preparing",
   "chatInputVoiceRecording": "Listening",
-  "chatInputVoiceFinishing": "Finishing transcription…",
+  "chatInputVoiceFinishing": "Finishing",
   "chatInputVoiceReview": "Recording stopped",
   "chatInputVoiceSpeak": "Speak now. Your transcript will appear here.",
   "chatInputVoiceReviewHint": "Confirmed words remain in your draft; provisional words were removed. Continue editing or try again.",

package/src/shared/lib/i18n/locales/zh-CN/chat.json

@@ -640,17 +640,32 @@
   "chatInputAttachmentTooLarge": "文件不能超过 {maxMb} MB。",
   "chatInputAttachmentReadFailed": "读取文件失败，请重试。",
   "chatInputVoice": "语音输入",
-  "chatInputVoicePermissionDenied": "麦克风权限被拒绝，请在浏览器或系统中允许后重试。",
+  "chatInputVoicePermissionDenied": "无法获得麦克风权限。浏览器可能无法区分网站权限和系统权限，请按以下步骤检查。",
+  "chatInputVoicePermissionPurpose": "语音输入需要使用麦克风，把你说的话转为草稿。出现权限提示时请选择允许；文字由你检查后发送。",
+  "chatInputVoiceCheckAndRetry": "检测麦克风并重试",
+  "chatInputVoicePermissionRetryHint": "允许后点击“检测麦克风并重试”。若系统要求重启应用，请先保留草稿再重开浏览器或 NextClaw。",
+  "chatInputVoicePermissionBrowser": "打开地址栏左侧的网站信息或权限菜单，将当前网站的“麦克风”设为允许。找不到时，在浏览器设置中搜索“麦克风”，检查当前网站是否被屏蔽。",
+  "chatInputVoicePermissionDesktop": "检查系统是否允许 NextClaw 使用麦克风。如果权限已允许但仍失败，请重开 NextClaw 后重试。",
+  "chatInputVoicePermissionMac": "macOS：打开系统设置 → 隐私与安全性 → 麦克风，允许当前浏览器或 NextClaw。",
+  "chatInputVoicePermissionWindows": "Windows：打开设置 → 隐私和安全性（Windows 10 为“隐私”）→ 麦克风，开启麦克风访问及桌面应用访问。",
+  "chatInputVoicePermissionIos": "iPhone / iPad：在浏览器的网站设置中检查麦克风权限；同时在系统设置 → 隐私与安全性 → 麦克风中检查浏览器权限（如有该项）。",
+  "chatInputVoicePermissionAndroid": "Android：打开系统设置 → 应用 → 当前浏览器 → 权限 → 麦克风，允许使用；并检查浏览器中当前网站的权限。",
+  "chatInputVoicePermissionSystem": "在系统声音设置中确认已选中可用输入设备，并检查系统是否限制了浏览器或 NextClaw 的麦克风访问。",
+  "chatInputVoiceNoDevice": "没有检测到麦克风。请连接或启用输入设备，再检测重试。",
+  "chatInputVoiceDeviceBusy": "麦克风无法读取，可能被其他应用占用或被系统限制。请关闭其他录音应用，检查输入设备后重试。",
+  "chatInputVoiceServiceDenied": "浏览器拒绝了语音识别服务。请检查浏览器的语音服务设置或组织策略，或使用支持语音识别的浏览器。",
   "chatInputVoiceUnsupported": "当前浏览器不支持语音输入。",
   "chatInputVoiceNoSpeech": "没有听清，请再试一次。",
   "chatInputVoiceFailed": "语音输入失败，请重试。",
   "chatInputVoicePrivacy": "点击录音，文字实时显示在光标处，下划线表示尚未确定的内容。浏览器语音服务可能联网处理声音，不会自动发送。",
   "chatInputVoiceStart": "开始录音",
   "chatInputVoiceFinish": "结束录音",
+  "chatInputVoiceSaveAndClose": "保存并退出",
+  "chatInputVoiceEscapeHint": "按 Esc 保存语音文字并退出",
   "chatInputVoiceCancel": "取消",
-  "chatInputVoiceStarting": "正在连接麦克风…",
+  "chatInputVoiceStarting": "准备录音",
   "chatInputVoiceRecording": "正在聆听",
-  "chatInputVoiceFinishing": "正在完成转写…",
+  "chatInputVoiceFinishing": "完成转写",
   "chatInputVoiceReview": "录音已停止",
   "chatInputVoiceSpeak": "请说话，转写会显示在这里",
   "chatInputVoiceReviewHint": "已确认的文字保留在草稿中，未确定的片段已撤回。你可以继续编辑或重试。",