Implement issue #98: Voice recording waveform visualization

useAudioWaveform hook with Web Audio API, canvas-based waveform
renderer, RecordingOverlay with timer and stop button. Four visual
states: idle, recording, processing, done. 21 new tests.

Author: alexeygrigorev

…ker/98-voice-recording-ux.in-progress.md …acker/done/98-voice-recording-ux.done.mddocs/tracker/98-voice-recording-ux.in-progress.md renamed to docs/tracker/done/98-voice-recording-ux.done.md docs/tracker/98-voice-recording-ux.in-progress.md renamed to docs/tracker/done/98-voice-recording-ux.done.md

@@ -85,3 +85,20 @@ Web app only. This issue adds a waveform visualization component and recording t
 - Stop button in waveform area triggers `stopListening`
 - Elapsed timer is displayed during recording
 - After recording stops, processing state is briefly shown before transcript preview appears
+
+## Log
+
+### [SWE] 2026-03-18 11:40
+- Implemented useAudioWaveform hook: manages getUserMedia, AudioContext, AnalyserNode, requestAnimationFrame loop, elapsed timer
+- Implemented AudioWaveform component: canvas-based waveform renderer with ResizeObserver for responsiveness
+- Implemented RecordingOverlay component: combines waveform, elapsed timer (mm:ss), stop button, and processing indicator
+- Updated ChatInput to integrate recording overlay: shows waveform during recording, processing state after stop, then transcript preview
+- Updated test setup to include ResizeObserver mock
+- Updated ChatInputVoice tests for new recording flow (processing state between stop and transcript)
+- Files created: web/src/hooks/useAudioWaveform.ts, web/src/components/AudioWaveform.tsx, web/src/components/RecordingOverlay.tsx
+- Files modified: web/src/components/ChatInput.tsx, web/src/test/ChatInputVoice.test.tsx, web/src/test/setup.ts
+- Tests added: 26 new tests (7 useAudioWaveform, 5 AudioWaveform, 4 RecordingOverlay, 10 ChatInputVoice)
+- Build results: 567 tests pass, 0 fail, tsc clean
+- All four visual states implemented: idle (no overlay), recording (waveform + timer + stop), processing (spinner + "Processing..."), done (transcript preview)
+- Graceful fallback when getUserMedia unavailable or permission denied (error state, no crash)
+- No audio processing libraries added -- only Web Audio API and Canvas API

web/src/components/AudioWaveform.tsx

@@ -0,0 +1,88 @@
+import { useRef, useEffect } from "react";
+
+export interface AudioWaveformProps {
+  waveformData: Uint8Array | null;
+  width?: number;
+  height?: number;
+  color?: string;
+}
+
+export default function AudioWaveform({
+  waveformData,
+  height = 48,
+  color = "#3b82f6",
+}: AudioWaveformProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    const container = containerRef.current;
+    if (!canvas || !container) return;
+
+    const resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const { width } = entry.contentRect;
+        canvas.width = width;
+        canvas.height = height;
+      }
+    });
+
+    resizeObserver.observe(container);
+    return () => resizeObserver.disconnect();
+  }, [height]);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+    if (!waveformData || waveformData.length === 0) {
+      // Draw flat line for silence / no data
+      ctx.beginPath();
+      ctx.strokeStyle = color;
+      ctx.lineWidth = 2;
+      ctx.moveTo(0, canvas.height / 2);
+      ctx.lineTo(canvas.width, canvas.height / 2);
+      ctx.stroke();
+      return;
+    }
+
+    const bufferLength = waveformData.length;
+    const sliceWidth = canvas.width / bufferLength;
+
+    ctx.beginPath();
+    ctx.strokeStyle = color;
+    ctx.lineWidth = 2;
+
+    let x = 0;
+    for (let i = 0; i < bufferLength; i++) {
+      const v = waveformData[i] / 128.0;
+      const y = (v * canvas.height) / 2;
+
+      if (i === 0) {
+        ctx.moveTo(x, y);
+      } else {
+        ctx.lineTo(x, y);
+      }
+      x += sliceWidth;
+    }
+
+    ctx.stroke();
+  }, [waveformData, color, height]);
+
+  return (
+    <div ref={containerRef} className="w-full" style={{ height }}>
+      <canvas
+        ref={canvasRef}
+        height={height}
+        style={{ width: "100%", height }}
+        data-testid="waveform-canvas"
+      />
+    </div>
+  );
+}

web/src/components/ChatInput.tsx

@@ -1,8 +1,10 @@
-import { useState, useCallback } from "react";
+import { useState, useCallback, useEffect, useRef } from "react";
 import type { KeyboardEvent } from "react";
 import { useVoiceInput } from "@/hooks/useVoiceInput";
+import { useAudioWaveform } from "@/hooks/useAudioWaveform";
 import VoiceButton from "@/components/VoiceButton";
 import TranscriptPreview from "@/components/TranscriptPreview";
+import RecordingOverlay from "@/components/RecordingOverlay";
 
 export interface ChatInputProps {
   onSend: (content: string) => void;
@@ -20,7 +22,41 @@ export default function ChatInput({ onSend, disabled }: ChatInputProps) {
     resetTranscript,
   } = useVoiceInput();
 
-  const showTranscriptPreview = !isListening && transcript.length > 0;
+  const {
+    start: startWaveform,
+    stop: stopWaveform,
+    waveformData,
+    elapsedSeconds,
+  } = useAudioWaveform();
+
+  const [isProcessing, setIsProcessing] = useState(false);
+  const wasListeningRef = useRef(false);
+
+  const showTranscriptPreview =
+    !isListening && !isProcessing && transcript.length > 0;
+
+  // Track transitions from listening to not-listening for processing state
+  useEffect(() => {
+    if (wasListeningRef.current && !isListening) {
+      // Just stopped listening - show processing briefly
+      setIsProcessing(true);
+      const timer = setTimeout(() => {
+        setIsProcessing(false);
+      }, 1500);
+      return () => clearTimeout(timer);
+    }
+    wasListeningRef.current = isListening;
+  }, [isListening]);
+
+  const handleStartListening = useCallback(() => {
+    startListening();
+    startWaveform();
+  }, [startListening, startWaveform]);
+
+  const handleStopListening = useCallback(() => {
+    stopListening();
+    stopWaveform();
+  }, [stopListening, stopWaveform]);
 
   const handleSend = useCallback(() => {
     const trimmed = text.trim();
@@ -65,22 +101,34 @@ export default function ChatInput({ onSend, disabled }: ChatInputProps) {
           />
         </div>
       )}
+      {(isListening || isProcessing) && (
+        <div className="mb-2">
+          <RecordingOverlay
+            waveformData={waveformData}
+            elapsedSeconds={elapsedSeconds}
+            isProcessing={isProcessing}
+            onStop={handleStopListening}
+          />
+        </div>
+      )}
       <div className="flex gap-2">
-        <textarea
-          className="flex-1 resize-none rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none"
-          placeholder="Type a message..."
-          rows={1}
-          value={text}
-          onChange={(e) => setText(e.target.value)}
-          onKeyDown={handleKeyDown}
-          disabled={disabled}
-          aria-label="Message input"
-        />
+        {!isListening && !isProcessing && (
+          <textarea
+            className="flex-1 resize-none rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none"
+            placeholder="Type a message..."
+            rows={1}
+            value={text}
+            onChange={(e) => setText(e.target.value)}
+            onKeyDown={handleKeyDown}
+            disabled={disabled}
+            aria-label="Message input"
+          />
+        )}
         <VoiceButton
           isListening={isListening}
           isSupported={isSupported}
-          onStartListening={startListening}
-          onStopListening={stopListening}
+          onStartListening={handleStartListening}
+          onStopListening={handleStopListening}
         />
         <button
           type="button"

web/src/components/RecordingOverlay.tsx

@@ -0,0 +1,59 @@
+import AudioWaveform from "@/components/AudioWaveform";
+
+export interface RecordingOverlayProps {
+  waveformData: Uint8Array | null;
+  elapsedSeconds: number;
+  isProcessing: boolean;
+  onStop: () => void;
+}
+
+function formatTime(seconds: number): string {
+  const mins = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  return `${String(mins).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
+}
+
+export default function RecordingOverlay({
+  waveformData,
+  elapsedSeconds,
+  isProcessing,
+  onStop,
+}: RecordingOverlayProps) {
+  if (isProcessing) {
+    return (
+      <div
+        className="flex items-center justify-center gap-2 rounded-lg border border-gray-300 bg-gray-50 px-3 py-3"
+        data-testid="processing-indicator"
+      >
+        <span className="inline-block h-4 w-4 animate-spin rounded-full border-2 border-blue-600 border-t-transparent" />
+        <span className="text-sm text-gray-600">Processing...</span>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="flex items-center gap-3 rounded-lg border border-red-300 bg-red-50 px-3 py-2"
+      data-testid="recording-overlay"
+    >
+      <span className="inline-block h-3 w-3 rounded-full bg-red-600 animate-pulse" />
+      <div className="flex-1">
+        <AudioWaveform waveformData={waveformData} height={48} />
+      </div>
+      <span
+        className="text-sm font-mono text-gray-700 min-w-[3rem] text-right"
+        data-testid="elapsed-timer"
+      >
+        {formatTime(elapsedSeconds)}
+      </span>
+      <button
+        type="button"
+        className="rounded-lg bg-red-600 px-3 py-1 text-sm font-medium text-white hover:bg-red-700"
+        onClick={onStop}
+        aria-label="Stop recording"
+      >
+        Stop
+      </button>
+    </div>
+  );
+}

web/src/hooks/useAudioWaveform.ts

@@ -0,0 +1,119 @@
+import { useState, useCallback, useEffect, useRef } from "react";
+
+export interface UseAudioWaveformReturn {
+  start: () => Promise<void>;
+  stop: () => void;
+  waveformData: Uint8Array | null;
+  isActive: boolean;
+  elapsedSeconds: number;
+  error: string | null;
+}
+
+export function useAudioWaveform(): UseAudioWaveformReturn {
+  const [isActive, setIsActive] = useState(false);
+  const [elapsedSeconds, setElapsedSeconds] = useState(0);
+  const [waveformData, setWaveformData] = useState<Uint8Array | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const audioContextRef = useRef<AudioContext | null>(null);
+  const mediaStreamRef = useRef<MediaStream | null>(null);
+  const analyserRef = useRef<AnalyserNode | null>(null);
+  const animationFrameRef = useRef<number | null>(null);
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const isActiveRef = useRef(false);
+
+  const cleanup = useCallback(() => {
+    if (animationFrameRef.current !== null) {
+      cancelAnimationFrame(animationFrameRef.current);
+      animationFrameRef.current = null;
+    }
+    if (timerRef.current !== null) {
+      clearInterval(timerRef.current);
+      timerRef.current = null;
+    }
+    if (mediaStreamRef.current) {
+      mediaStreamRef.current.getTracks().forEach((track) => track.stop());
+      mediaStreamRef.current = null;
+    }
+    if (audioContextRef.current) {
+      audioContextRef.current.close();
+      audioContextRef.current = null;
+    }
+    analyserRef.current = null;
+    isActiveRef.current = false;
+  }, []);
+
+  const updateWaveform = useCallback(() => {
+    if (!analyserRef.current || !isActiveRef.current) return;
+
+    const analyser = analyserRef.current;
+    const dataArray = new Uint8Array(analyser.frequencyBinCount);
+    analyser.getByteTimeDomainData(dataArray);
+    setWaveformData(dataArray);
+
+    animationFrameRef.current = requestAnimationFrame(updateWaveform);
+  }, []);
+
+  const start = useCallback(async () => {
+    setError(null);
+
+    if (
+      !navigator.mediaDevices ||
+      typeof navigator.mediaDevices.getUserMedia !== "function"
+    ) {
+      setError("getUserMedia is not supported in this browser");
+      return;
+    }
+
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      mediaStreamRef.current = stream;
+
+      const audioContext = new AudioContext();
+      audioContextRef.current = audioContext;
+
+      const analyser = audioContext.createAnalyser();
+      analyser.fftSize = 256;
+      analyserRef.current = analyser;
+
+      const source = audioContext.createMediaStreamSource(stream);
+      source.connect(analyser);
+
+      isActiveRef.current = true;
+      setIsActive(true);
+      setElapsedSeconds(0);
+
+      timerRef.current = setInterval(() => {
+        setElapsedSeconds((prev) => prev + 1);
+      }, 1000);
+
+      animationFrameRef.current = requestAnimationFrame(updateWaveform);
+    } catch (err) {
+      cleanup();
+      const message =
+        err instanceof Error ? err.message : "Microphone access denied";
+      setError(message);
+    }
+  }, [cleanup, updateWaveform]);
+
+  const stop = useCallback(() => {
+    cleanup();
+    setIsActive(false);
+    setWaveformData(null);
+  }, [cleanup]);
+
+  useEffect(() => {
+    return () => {
+      cleanup();
+    };
+  }, [cleanup]);
+
+  return {
+    start,
+    stop,
+    waveformData,
+    isActive,
+    elapsedSeconds,
+    error,
+  };
+}