feat(web-shell): honor voice hold mode

docs/design/web-shell-voice-mode.md

@@ -0,0 +1,22 @@
+# Web Shell voice mode
+
+## Goal
+
+Make the Web Shell voice control honor the workspace voice mode already returned by the daemon.
+
+## Behavior
+
+| Mode   | Start                | Finish                | Cancel                 |
+| ------ | -------------------- | --------------------- | ---------------------- |
+| `hold` | Primary pointer down | Matching pointer up   | Pointer cancel         |
+| `tap`  | Click while idle     | Click while recording | Click while connecting |
+
+The control captures the active pointer so releasing outside the button still finishes a hold. Keyboard-generated clicks retain the existing toggle behavior in either mode.
+
+Once microphone access is ready, audio produced while the socket connects is buffered locally. The socket receives `start`, the buffered audio, and then a deferred `stop`, so releasing during connection does not discard captured speech.
+
+The mode is loaded with the existing workspace voice status and refreshed through the existing settings-version signal. A status request remains fail-closed: the control stays hidden until the current workspace reports that voice is enabled.
+
+## Scope
+
+This change only affects Web Shell input interaction. It does not change the daemon settings contract, transcription transport, model selection, or TUI voice behavior.

packages/web-shell/client/voice/VoiceButton.test.tsx

@@ -64,12 +64,16 @@ vi.mock('./useVoiceCapture', () => ({
 
 const mounted: Array<{ root: Root; container: HTMLElement }> = [];
 
-function voiceStatus(enabled: boolean, workspaceCwd = '/tmp/workspace') {
+function voiceStatus(
+  enabled: boolean,
+  workspaceCwd = '/tmp/workspace',
+  mode: 'hold' | 'tap' = 'hold',
+) {
   return {
     v: 1 as const,
     workspaceCwd,
     enabled,
-    mode: 'hold' as const,
+    mode,
     language: 'en',
     voiceModel: null,
     availableVoiceModels: [],
@@ -121,9 +125,25 @@ async function render(disabled: boolean): Promise<HTMLButtonElement> {
   return button;
 }
 
-const click = (button: HTMLButtonElement) => {
+const click = (button: HTMLButtonElement, detail = 1) => {
+  act(() => {
+    button.dispatchEvent(new MouseEvent('click', { bubbles: true, detail }));
+  });
+};
+
+const pointer = (
+  button: HTMLButtonElement,
+  type: 'pointerdown' | 'pointerup' | 'pointercancel',
+  pointerId = 1,
+  mouseButton = 0,
+) => {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    button: mouseButton,
+  });
+  Object.defineProperty(event, 'pointerId', { value: pointerId });
   act(() => {
-    button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    button.dispatchEvent(event);
   });
 };
 
@@ -584,6 +604,9 @@ describe('VoiceButton', () => {
   });
 
   it('lets a disabled composer stop active dictation', async () => {
+    mocks.workspaceVoice.mockResolvedValue(
+      voiceStatus(true, '/tmp/workspace', 'tap'),
+    );
     mocks.capture.status = 'recording';
     const button = await render(true);
 
@@ -594,6 +617,9 @@ describe('VoiceButton', () => {
   });
 
   it('lets a disabled composer abort a connecting dictation', async () => {
+    mocks.workspaceVoice.mockResolvedValue(
+      voiceStatus(true, '/tmp/workspace', 'tap'),
+    );
     mocks.capture.status = 'connecting';
     const button = await render(true);
     mocks.capture.abort.mockClear();
@@ -604,6 +630,131 @@ describe('VoiceButton', () => {
     expect(mocks.capture.abort).toHaveBeenCalledOnce();
   });
 
+  it('holds to start and releases to stop dictation', async () => {
+    const { root, container } = mount(false);
+    await flush();
+    let button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+    const heldButton = button;
+
+    pointer(button, 'pointerdown');
+    expect(mocks.capture.start).toHaveBeenCalledOnce();
+
+    mocks.capture.status = 'recording';
+    act(() => {
+      root.render(
+        <VoiceButton
+          disabled={false}
+          onInsert={() => {}}
+          target={legacyTarget}
+        />,
+      );
+    });
+    button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+    // The recording pill reuses the icon button's DOM node, so the pointer
+    // capture set on pointerdown survives the status change and the release
+    // still lands on this element.
+    expect(button).toBe(heldButton);
+    pointer(button, 'pointerup');
+    click(button);
+
+    expect(mocks.capture.stop).toHaveBeenCalledOnce();
+  });
+
+  it('stops a hold that is released while connecting', async () => {
+    const { root, container } = mount(false);
+    await flush();
+    let button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+    pointer(button, 'pointerdown');
+
+    mocks.capture.status = 'connecting';
+    act(() => {
+      root.render(
+        <VoiceButton
+          disabled={false}
+          onInsert={() => {}}
+          target={legacyTarget}
+        />,
+      );
+    });
+    button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+    pointer(button, 'pointerup');
+
+    expect(mocks.capture.stop).toHaveBeenCalledOnce();
+  });
+
+  it('aborts a hold when the pointer is cancelled', async () => {
+    const { root, container } = mount(false);
+    await flush();
+    let button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+    pointer(button, 'pointerdown');
+
+    mocks.capture.status = 'connecting';
+    act(() => {
+      root.render(
+        <VoiceButton
+          disabled={false}
+          onInsert={() => {}}
+          target={legacyTarget}
+        />,
+      );
+    });
+    button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+    pointer(button, 'pointercancel');
+
+    expect(mocks.capture.abort).toHaveBeenCalledOnce();
+  });
+
+  it('keeps click-to-toggle behavior in tap mode', async () => {
+    mocks.workspaceVoice.mockResolvedValue(
+      voiceStatus(true, '/tmp/workspace', 'tap'),
+    );
+    const { root, container } = mount(false);
+    await flush();
+    let button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+
+    click(button);
+    expect(mocks.capture.start).toHaveBeenCalledOnce();
+
+    mocks.capture.status = 'recording';
+    act(() => {
+      root.render(
+        <VoiceButton
+          disabled={false}
+          onInsert={() => {}}
+          target={legacyTarget}
+        />,
+      );
+    });
+    button = container.querySelector('button');
+    if (!button) throw new Error('VoiceButton did not render');
+    click(button);
+
+    expect(mocks.capture.stop).toHaveBeenCalledOnce();
+  });
+
+  it('ignores mouse click in hold mode', async () => {
+    const button = await render(false);
+
+    click(button); // detail defaults to 1 (real pointer click)
+
+    expect(mocks.capture.start).not.toHaveBeenCalled();
+  });
+
+  it('allows keyboard activation in hold mode', async () => {
+    const button = await render(false);
+
+    click(button, 0);
+
+    expect(mocks.capture.start).toHaveBeenCalledOnce();
+  });
+
   it('reports whether voice capture is active', async () => {
     const onActiveChange = vi.fn();
     const { root } = mount(false, legacyTarget, onActiveChange);

packages/web-shell/client/voice/VoiceButton.tsx

@@ -6,6 +6,7 @@
 
 import type React from 'react';
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { DaemonVoiceMode } from '@qwen-code/sdk';
 import {
   useConnection,
   useWorkspace,
@@ -110,10 +111,13 @@ export function VoiceButton({
   const [voiceGate, setVoiceGate] = useState<{
     queryKey: string | undefined;
     enabled: boolean;
+    mode: DaemonVoiceMode;
   }>(() => ({
     queryKey,
     enabled: false,
+    mode: 'hold',
   }));
+  const holdPointerIdRef = useRef<number | null>(null);
   const targetRef = useRef(target);
   targetRef.current = target;
   const requestGenerationRef = useRef(0);
@@ -135,6 +139,7 @@ export function VoiceButton({
     setVoiceGate({
       queryKey,
       enabled: false,
+      mode: 'hold',
     });
     if (
       !requestTarget ||
@@ -151,6 +156,7 @@ export function VoiceButton({
           setVoiceGate({
             queryKey,
             enabled: voice.enabled === true,
+            mode: voice.mode,
           });
         }
       })
@@ -303,6 +309,63 @@ export function VoiceButton({
   // composer is disabled (e.g. mid-turn) — only starting a new one is blocked.
   const canCancel = isRecording || isConnecting;
 
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (voiceGate.mode === 'hold' && event.detail !== 0) return;
+    if (isRecording) {
+      stop();
+    } else if (isConnecting) {
+      abort();
+    } else if (!disabled) {
+      setNoticeMessage(undefined);
+      start();
+    }
+  };
+
+  const handlePointerDown = (event: React.PointerEvent<HTMLButtonElement>) => {
+    if (
+      voiceGate.mode !== 'hold' ||
+      event.button !== 0 ||
+      disabled ||
+      isConnecting ||
+      isRecording
+    ) {
+      return;
+    }
+    event.preventDefault();
+    holdPointerIdRef.current = event.pointerId;
+    try {
+      event.currentTarget.setPointerCapture(event.pointerId);
+    } catch {
+      // Pointer capture is best-effort; release on the button still works.
+    }
+    setNoticeMessage(undefined);
+    start();
+  };
+
+  const handlePointerUp = (event: React.PointerEvent<HTMLButtonElement>) => {
+    if (
+      voiceGate.mode !== 'hold' ||
+      holdPointerIdRef.current !== event.pointerId
+    ) {
+      return;
+    }
+    holdPointerIdRef.current = null;
+    if (isConnecting || isRecording) stop();
+  };
+
+  const handlePointerCancel = (
+    event: React.PointerEvent<HTMLButtonElement>,
+  ) => {
+    if (
+      voiceGate.mode !== 'hold' ||
+      holdPointerIdRef.current !== event.pointerId
+    ) {
+      return;
+    }
+    holdPointerIdRef.current = null;
+    if (isConnecting || isRecording) abort();
+  };
+
   const label = isRecording
     ? t('voice.stopDictation')
     : isTranscribing
@@ -321,7 +384,10 @@ export function VoiceButton({
       <button
         type="button"
         className={styles.pill}
-        onClick={() => stop()}
+        onClick={handleClick}
+        onPointerDown={handlePointerDown}
+        onPointerUp={handlePointerUp}
+        onPointerCancel={handlePointerCancel}
         aria-label={label}
         title={label}
       >
@@ -365,17 +431,10 @@ export function VoiceButton({
       <button
         type="button"
         className={iconClass}
-        onClick={() => {
-          if (isConnecting) {
-            abort();
-          } else if (disabled) {
-            return;
-          } else {
-            // idle / error / notice → (re)start
-            setNoticeMessage(undefined);
-            start();
-          }
-        }}
+        onClick={handleClick}
+        onPointerDown={handlePointerDown}
+        onPointerUp={handlePointerUp}
+        onPointerCancel={handlePointerCancel}
         disabled={Boolean(disabled) && !canCancel}
         aria-label={label}
         title={errorMessage ?? noticeMessage ?? label}