@mooncompany/uplink-chat 0.5.0

package/public/js/voice.js

@@ -0,0 +1,883 @@
+// ============================================
+// VOICE MODULE
+// Voice recording, 3D moon, audio playback
+// ============================================
+
+// Check for real-time voice support (loaded by realtime-voice.js)
+// window.UplinkRealtime = { start(), stop(), isActive() }
+
+// DOM elements
+let voiceBtn, voiceStatus, voiceTimer, moonCanvas;
+
+// Three.js objects
+let moonScene, moonCamera, moonRenderer, moonModel, haloMesh;
+
+// State
+let stream = null;
+let recorder = null;
+let chunks = [];
+let recordingStart = null;
+let timerInterval = null;
+let maxDurationTimeout = null; // M-17: timeout for max recording duration
+let isRecording = false;
+let isTransitioning = false;
+let haloOpacity = 0;
+let moonAnimationRunning = false;
+
+// Auto-hold mode
+let autoHoldMode = false;
+let lastTapTime = 0;
+let silenceStart = null;
+let audioContext = null;
+let analyser = null;
+let monitorInterval = null;
+
+// Animation frame timing
+let lastFrameTime = 0;
+let frameInterval = 1000 / 60; // Default 60fps
+let moonObserver = null;
+
+// Module init retry state
+let initRetryCount = 0;
+const MAX_INIT_RETRIES = 10;
+
+// Constants - Timing
+const INIT_RETRY_DELAY_MS = 100;
+const DOUBLE_TAP_DELAY_MS = 300;
+const AUTO_HOLD_SILENCE_DURATION_MS = 2000;
+const AUDIO_MONITOR_INTERVAL_MS = 100;
+const HOLD_DETECTION_DELAY_MS = 160;
+const TAP_VS_HOLD_THRESHOLD_MS = 150;
+const MIN_RECORDING_DURATION_MS = 500;
+const MAX_RECORDING_DURATION_MS = 300000; // 5 minutes max recording (M-17)
+const TIMER_UPDATE_INTERVAL_MS = 1000;
+const MEDIA_RECORDER_TIMESLICE_MS = 100;
+
+// Constants - Audio
+const SILENCE_THRESHOLD = 12;
+
+// Constants - 3D Moon
+const MOON_CANVAS_SIZE = 80;
+const MOON_CAMERA_FOV = 50;
+const MOON_CAMERA_NEAR = 0.1;
+const MOON_CAMERA_FAR = 1000;
+const MOON_CAMERA_Z = 3.5;
+const MOON_SPHERE_SEGMENTS = 64;
+const MOON_INITIAL_TILT = 0.2;
+const BASE_ROTATION_SPEED = 0.003;
+const RECORDING_ROTATION_SPEED = 0.015;
+const REALTIME_ROTATION_SPEED = 0.04;
+
+// Constants - Halo animation
+const HALO_INNER_RADIUS = 1.05;
+const HALO_OUTER_RADIUS = 1.5;
+const HALO_RECORDING_OPACITY = 0.7;
+const HALO_REALTIME_OPACITY = 0.9;
+const HALO_OPACITY_LERP = 0.25;
+const HALO_ROTATION_SPEED = 0.02;
+const HALO_PULSE_SPEED = 0.006;
+const HALO_PULSE_AMPLITUDE = 0.25;
+const HALO_PULSE_BASE = 0.6;
+const HALO_SCALE_SPEED = 0.004;
+const HALO_SCALE_AMPLITUDE = 0.05;
+
+function init() {
+  voiceBtn = document.getElementById('voiceBtn');
+  voiceStatus = document.getElementById('voiceStatus');
+  voiceTimer = document.getElementById('voiceTimer');
+  moonCanvas = document.getElementById('moonCanvas');
+
+  if (!voiceBtn) {
+    if (initRetryCount >= MAX_INIT_RETRIES) {
+      logger.error('Voice: Elements not found after max retries, giving up');
+      return;
+    }
+    initRetryCount++;
+    const delay = Math.min(INIT_RETRY_DELAY_MS * Math.pow(2, initRetryCount), 5000);
+    logger.warn(`Voice: Elements not found, retrying (${initRetryCount}/${MAX_INIT_RETRIES})...`);
+    setTimeout(init, delay);
+    return;
+  }
+
+  // Set initial ARIA label for accessibility
+  voiceBtn.setAttribute('aria-label', 'Start recording');
+
+  // Defer 3D moon initialization until voice mode is first shown.
+  // WebGL renderers can produce zero-sized contexts when the canvas
+  // parent has display:none (voice row is hidden by default).
+  // setupVisibilityObserver will trigger initMoon on first activation.
+  setupVisibilityObserver();
+
+  // Set up voice button events
+  setupVoiceEvents();
+
+  // Keyboard shortcuts
+  setupKeyboardShortcuts();
+
+  logger.debug('Voice: Initialized');
+}
+
+// ========== 3D Moon ==========
+
+function initMoon() {
+  if (!moonCanvas) {
+    logger.warn('Voice: moonCanvas not found');
+    return;
+  }
+  
+  if (typeof THREE === 'undefined') {
+    logger.warn('Voice: Three.js not loaded, using fallback');
+    showMoonFallback();
+    return;
+  }
+
+  // Set frame interval based on device (mobile = 30fps, desktop = 60fps)
+  frameInterval = window.innerWidth < 768 ? 1000 / 30 : 1000 / 60;
+
+  try {
+    const size = MOON_CANVAS_SIZE;
+    moonCanvas.width = size * 2;
+    moonCanvas.height = size * 2;
+
+    moonScene = new THREE.Scene();
+  moonCamera = new THREE.PerspectiveCamera(MOON_CAMERA_FOV, 1, MOON_CAMERA_NEAR, MOON_CAMERA_FAR);
+  moonCamera.position.z = MOON_CAMERA_Z;
+
+  moonRenderer = new THREE.WebGLRenderer({
+    canvas: moonCanvas,
+    alpha: true,
+    antialias: true
+  });
+  moonRenderer.setSize(size * 2, size * 2);
+  moonRenderer.setPixelRatio(window.devicePixelRatio);
+
+  // Lighting
+  const ambientLight = new THREE.AmbientLight(0x333333);
+  moonScene.add(ambientLight);
+
+  const keyLight = new THREE.DirectionalLight(0xffffff, 1.5);
+  keyLight.position.set(3, 1, 2);
+  moonScene.add(keyLight);
+
+  const rimLight = new THREE.DirectionalLight(0x4444ff, 0.3);
+  rimLight.position.set(-2, 0, -1);
+  moonScene.add(rimLight);
+
+  // Halo
+  const haloGeometry = new THREE.RingGeometry(HALO_INNER_RADIUS, HALO_OUTER_RADIUS, MOON_SPHERE_SEGMENTS);
+  const haloMaterial = new THREE.MeshBasicMaterial({
+    color: 0xffd700,
+    transparent: true,
+    opacity: 0,
+    side: THREE.DoubleSide
+  });
+  haloMesh = new THREE.Mesh(haloGeometry, haloMaterial);
+  haloMesh.position.z = 0.05;
+  moonScene.add(haloMesh);
+
+  // Moon sphere with texture
+  const geometry = new THREE.SphereGeometry(1, MOON_SPHERE_SEGMENTS, MOON_SPHERE_SEGMENTS);
+  const textureLoader = new THREE.TextureLoader();
+  const moonTexture = textureLoader.load('/moon_texture.jpg');
+  const material = new THREE.MeshStandardMaterial({
+    map: moonTexture,
+    roughness: 0.8,
+    metalness: 0.0
+  });
+
+  moonModel = new THREE.Mesh(geometry, material);
+  moonModel.rotation.x = MOON_INITIAL_TILT;
+  moonScene.add(moonModel);
+
+  animateMoon();
+  logger.debug('Voice: 3D moon initialized successfully');
+  } catch (err) {
+    logger.error('Voice: Failed to initialize 3D moon:', err);
+    showMoonFallback();
+  }
+}
+
+function showMoonFallback() {
+  // Show a static moon image as fallback when Three.js fails
+  if (!moonCanvas) return;
+  const ctx = moonCanvas.getContext('2d');
+  if (!ctx) return;
+  
+  const img = new Image();
+  img.onload = () => {
+    const size = MOON_CANVAS_SIZE * 2;
+    moonCanvas.width = size;
+    moonCanvas.height = size;
+    ctx.beginPath();
+    ctx.arc(size/2, size/2, size/2, 0, Math.PI * 2);
+    ctx.closePath();
+    ctx.clip();
+    ctx.drawImage(img, 0, 0, size, size);
+  };
+  img.onerror = () => {
+    // If image fails, draw a simple circle
+    const size = MOON_CANVAS_SIZE * 2;
+    moonCanvas.width = size;
+    moonCanvas.height = size;
+    ctx.beginPath();
+    ctx.arc(size/2, size/2, size/2 - 2, 0, Math.PI * 2);
+    ctx.fillStyle = '#888';
+    ctx.fill();
+  };
+  img.src = '/moon_texture.jpg';
+}
+
+let moonInitialized = false;
+
+function setupVisibilityObserver() {
+  const voiceRow = document.getElementById('voiceInputRow');
+  if (!voiceRow) return;
+
+  // Watch for class changes on the voice row to detect when it becomes visible
+  moonObserver = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
+        const isActive = voiceRow.classList.contains('active');
+        if (isActive) {
+          // Initialize moon on first activation (deferred from init to avoid
+          // creating a WebGL context on a hidden/zero-sized canvas)
+          if (!moonInitialized) {
+            moonInitialized = true;
+            initMoon();
+          }
+          if (!moonAnimationRunning && moonRenderer) {
+            startMoonAnimation();
+          }
+        }
+      }
+    });
+  });
+
+  moonObserver.observe(voiceRow, {
+    attributes: true,
+    attributeFilter: ['class']
+  });
+
+  // Also listen for document visibility changes
+  document.addEventListener('visibilitychange', () => {
+    if (!document.hidden && voiceRow.classList.contains('active') && !moonAnimationRunning) {
+      if (!moonInitialized) {
+        moonInitialized = true;
+        initMoon();
+      }
+      if (moonRenderer) {
+        startMoonAnimation();
+      }
+    }
+  });
+}
+
+function animateMoon(timestamp) {
+  // Stop animation if document is hidden (tab not active)
+  if (document.hidden) {
+    moonAnimationRunning = false;
+    return;
+  }
+
+  // Check if voice mode is visible before animating
+  const voiceRow = document.getElementById('voiceInputRow');
+  const isVisible = voiceRow && (voiceRow.classList.contains('active') || voiceRow.offsetParent !== null);
+  
+  if (!isVisible) {
+    moonAnimationRunning = false;
+    return;
+  }
+  
+  // FPS throttling for mobile - skip frame if not enough time elapsed
+  if (timestamp) {
+    const elapsed = timestamp - lastFrameTime;
+    if (elapsed < frameInterval) {
+      // Skip this frame, but still schedule next check
+      if (moonAnimationRunning) {
+        requestAnimationFrame(animateMoon);
+      }
+      return;
+    }
+    lastFrameTime = timestamp;
+  }
+  
+  // Update moon rotation
+  const realtimeActive = window.UplinkRealtime?.isActive?.() || false;
+  const realtimeMuted = window.UplinkRealtime?.isMuted?.() || false;
+  
+  if (moonModel) {
+    // Fast spin when listening, slow when mic is muted (agent responding)
+    const speed = realtimeActive 
+      ? (realtimeMuted ? BASE_ROTATION_SPEED : REALTIME_ROTATION_SPEED) 
+      : (isRecording ? RECORDING_ROTATION_SPEED : BASE_ROTATION_SPEED);
+    moonModel.rotation.y += speed;
+  }
+
+  // Update halo
+  if (haloMesh) {
+    const active = isRecording || realtimeActive;
+    const targetOpacity = realtimeActive ? HALO_REALTIME_OPACITY : (isRecording ? HALO_RECORDING_OPACITY : 0);
+    haloOpacity += (targetOpacity - haloOpacity) * HALO_OPACITY_LERP;
+    haloMesh.material.opacity = haloOpacity;
+
+    if (active) {
+      haloMesh.rotation.z += HALO_ROTATION_SPEED;
+      const pulse = HALO_PULSE_BASE + Math.sin(Date.now() * HALO_PULSE_SPEED) * HALO_PULSE_AMPLITUDE;
+      haloMesh.material.opacity = haloOpacity * pulse;
+      const scalePulse = 1 + Math.sin(Date.now() * HALO_SCALE_SPEED) * HALO_SCALE_AMPLITUDE;
+      haloMesh.scale.set(scalePulse, scalePulse, 1);
+    }
+  }
+
+  // Render the scene
+  if (moonRenderer && moonScene && moonCamera) {
+    moonRenderer.render(moonScene, moonCamera);
+  }
+
+  // Continue animation loop
+  if (moonAnimationRunning) {
+    requestAnimationFrame(animateMoon);
+  }
+}
+
+// ========== Voice Recording ==========
+
+async function initVoiceStream() {
+  if (stream) return true;
+
+  try {
+    stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+    // Audio level monitoring
+    audioContext = new (window.AudioContext || window.webkitAudioContext)();
+    analyser = audioContext.createAnalyser();
+    analyser.fftSize = 256;
+    const source = audioContext.createMediaStreamSource(stream);
+    source.connect(analyser);
+    monitorInterval = setInterval(monitorAudioLevel, AUDIO_MONITOR_INTERVAL_MS);
+
+    if (voiceStatus) voiceStatus.textContent = getVoiceStatusLabel();
+    return true;
+  } catch (e) {
+    if (voiceStatus) voiceStatus.textContent = 'Mic access denied';
+    return false;
+  }
+}
+
+function getAudioLevel() {
+  if (!analyser) return 0;
+  const data = new Uint8Array(analyser.frequencyBinCount);
+  analyser.getByteFrequencyData(data);
+  return data.reduce((a, b) => a + b) / data.length;
+}
+
+function monitorAudioLevel() {
+  if (!autoHoldMode || !isRecording) return;
+  
+  const level = getAudioLevel();
+  if (level > SILENCE_THRESHOLD) {
+    silenceStart = null;
+  } else {
+    if (!silenceStart) silenceStart = Date.now();
+    else if (Date.now() - silenceStart > AUTO_HOLD_SILENCE_DURATION_MS) {
+      if (recordingStart && Date.now() - recordingStart > MIN_RECORDING_DURATION_MS) {
+        autoHoldMode = false;
+        voiceBtn?.classList.remove('auto-hold');
+        stopRecording();
+      }
+    }
+  }
+}
+
+// Cached config for STT hint check
+let cachedClientConfig = null;
+let configCacheTime = 0;
+const CONFIG_CACHE_TTL_MS = 30000; // 30s cache
+
+async function getClientConfig() {
+  const now = Date.now();
+  if (cachedClientConfig && (now - configCacheTime) < CONFIG_CACHE_TTL_MS) {
+    return cachedClientConfig;
+  }
+  try {
+    const resp = await fetch('/api/config');
+    if (resp.ok) {
+      cachedClientConfig = await resp.json();
+      configCacheTime = now;
+    }
+  } catch (e) {
+    // Ignore fetch errors — don't block recording
+  }
+  return cachedClientConfig;
+}
+
+async function startRecording() {
+  // Premium check
+  if (window.UplinkPremium && !window.UplinkPremium.isActive()) {
+    window.UplinkPremium.showUpgradeModal('Voice chat');
+    return;
+  }
+  if (isTransitioning) return;
+  if (isRecording) return;  // Mutex: prevent multiple simultaneous recordings
+  isTransitioning = true;
+  const core = window.UplinkCore;
+  try {
+    if (core && core.chatState !== 'idle') return;
+
+    // Check voice mode and route accordingly
+    const cfg = await getClientConfig();
+    const voiceMode = cfg?.voiceMode || 'push-to-talk';
+    
+    if (voiceMode === 'live-voice') {
+      // Use OpenAI Realtime standalone mode
+      if (window.UplinkRealtime && typeof window.UplinkRealtime.start === 'function') {
+        isTransitioning = false;
+        if (voiceStatus) voiceStatus.textContent = 'Listening...';
+        window.UplinkRealtime.start('standalone');
+        return;
+      } else {
+        const chat = window.UplinkChat;
+        chat?.addMessage('Real-time voice module not loaded', 'system');
+        isTransitioning = false;
+        return;
+      }
+    } else if (voiceMode === 'agent-voice') {
+      // Use agent voice bridge mode
+      if (window.UplinkRealtime && typeof window.UplinkRealtime.start === 'function') {
+        isTransitioning = false;
+        const name = cfg?.assistantName || 'Agent';
+        if (voiceStatus) voiceStatus.textContent = `Listening — ${name}`;
+        window.UplinkRealtime.start('agent');
+        return;
+      } else {
+        const chat = window.UplinkChat;
+        chat?.addMessage('Real-time voice module not loaded', 'system');
+        isTransitioning = false;
+        return;
+      }
+    }
+    
+    // voiceMode === 'push-to-talk' — continue with existing recording flow
+
+    // Show hint if STT is not configured (don't block recording)
+    if (cfg && cfg.sttProvider === 'none' && !cfg.hasOpenaiKey) {
+      const chat = window.UplinkChat;
+      chat?.addMessage('Set up speech-to-text in Settings → Voice & STT to use voice input', 'system');
+    }
+    
+    // Set state early to prevent race conditions from double-taps
+    if (core) core.chatState = 'recording';
+    
+    if (!stream && !(await initVoiceStream())) {
+      if (core) core.chatState = 'idle';  // Reset on failure
+      return;
+    }
+    isRecording = true;
+    if (voiceBtn) voiceBtn.setAttribute('aria-label', 'Stop recording');
+    recordingStart = Date.now();
+    chunks = [];
+
+    try {
+      recorder = new MediaRecorder(stream);
+      recorder.ondataavailable = e => { if (e.data.size) chunks.push(e.data); };
+      recorder.onstop = sendVoice;
+      recorder.onerror = (e) => {
+        logger.error('Voice: MediaRecorder error', e.error);
+        if (window.UplinkDeveloper) {
+          window.UplinkDeveloper.logError(e.error || new Error('Recording failed'), 'MediaRecorder');
+        }
+        stopRecording();
+        resetVoice();
+      };
+      recorder.start(MEDIA_RECORDER_TIMESLICE_MS);
+    } catch (err) {
+      logger.error('Voice: Failed to create MediaRecorder', err);
+      if (window.UplinkDeveloper) {
+        window.UplinkDeveloper.logError(err, 'MediaRecorder init');
+      }
+      resetVoice();
+      return;
+    }
+
+    voiceBtn?.classList.add('recording');
+    if (voiceStatus) {
+      voiceStatus.textContent = 'Listening...';
+      voiceStatus.classList.add('recording');
+    }
+    if (voiceTimer) voiceTimer.classList.add('visible');
+
+    timerInterval = setInterval(() => {
+      const elapsed = Math.floor((Date.now() - recordingStart) / TIMER_UPDATE_INTERVAL_MS);
+      if (voiceTimer) {
+        voiceTimer.textContent = `${Math.floor(elapsed / 60)}:${(elapsed % 60).toString().padStart(2, '0')}`;
+      }
+    }, TIMER_UPDATE_INTERVAL_MS);
+
+    // M-17: Auto-stop recording after MAX_RECORDING_DURATION_MS
+    maxDurationTimeout = setTimeout(() => {
+      logger.warn(`Voice: Max recording duration (${MAX_RECORDING_DURATION_MS}ms) reached, stopping`);
+      if (voiceStatus) {
+        voiceStatus.textContent = 'Max duration reached';
+      }
+      stopRecording();
+    }, MAX_RECORDING_DURATION_MS);
+  } finally {
+    isTransitioning = false;
+  }
+}
+
+function stopRecording() {
+  if (isTransitioning) return;
+  isTransitioning = true;
+  try {
+    // Check if real-time voice is active
+    if (window.UplinkRealtime && typeof window.UplinkRealtime.isActive === 'function' && window.UplinkRealtime.isActive()) {
+      if (typeof window.UplinkRealtime.stop === 'function') {
+        window.UplinkRealtime.stop();
+      }
+      if (voiceStatus) voiceStatus.textContent = getVoiceStatusLabel();
+      isTransitioning = false;
+      return;
+    }
+
+    if (!isRecording) return;
+
+    clearInterval(timerInterval);
+    if (maxDurationTimeout) clearTimeout(maxDurationTimeout); // M-17: clear max duration timeout
+    if (voiceTimer) voiceTimer.classList.remove('visible');
+
+    if (recorder?.state === 'recording') recorder.stop();
+
+    voiceBtn?.classList.remove('recording');
+    if (voiceStatus) voiceStatus.classList.remove('recording');
+    isRecording = false;
+    if (voiceBtn) voiceBtn.setAttribute('aria-label', 'Start recording');
+  } finally {
+    isTransitioning = false;
+  }
+}
+
+async function sendVoice() {
+  if (!chunks.length) {
+    resetVoice();
+    return;
+  }
+
+  const core = window.UplinkCore;
+  if (core) core.chatState = 'processing';
+
+  voiceBtn?.classList.add('processing');
+  if (voiceStatus) voiceStatus.textContent = 'Sending audio...';
+
+  const chat = window.UplinkChat;
+  chat?.showTyping();
+
+  const blob = new Blob(chunks, { type: 'audio/webm' });
+  const form = new FormData();
+  form.append('audio', blob, 'rec.webm');
+
+  try {
+    const res = await fetch('/api/voice', { method: 'POST', body: form });
+    
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    }
+    
+    const data = await res.json();
+    chat?.hideTyping();
+
+    if (data.transcription) {
+      chat?.addMessage(data.transcription, 'user');
+      chat?.addMessage(data.response, 'assistant');
+      
+      if (core?.audioResponses) {
+        // Queue all audio chunks (chunked TTS) or fall back to single URL
+        const urls = data.audioUrls?.length ? data.audioUrls : (data.audioUrl ? [data.audioUrl] : []);
+        if (urls.length && window.UplinkChat?.playAudio) {
+          urls.forEach(url => window.UplinkChat.playAudio(url));
+        } else if (urls.length) {
+          // Fallback to direct play (first chunk only)
+          const audio = document.getElementById('audio');
+          if (audio) {
+            audio.src = urls[0];
+            audio.play().catch(playErr => {
+              logger.warn('Voice: Audio playback failed', playErr);
+            });
+          }
+        }
+      }
+    } else if (data.error) {
+      const friendlyMsg = window.UplinkErrors?.getFriendlyMessage(data.error) || data.error;
+      chat?.addMessage(friendlyMsg, 'system');
+      if (window.UplinkDeveloper) {
+        window.UplinkDeveloper.logError(new Error(data.error), '/api/voice');
+      }
+    }
+  } catch (err) {
+    chat?.hideTyping();
+    const friendlyMsg = window.UplinkErrors?.getFriendlyMessage(err) || 'Voice processing failed';
+    chat?.addMessage(friendlyMsg, 'system');
+    if (window.UplinkDeveloper) {
+      window.UplinkDeveloper.logError(err, '/api/voice');
+    }
+  }
+
+  resetVoice();
+}
+
+function resetVoice() {
+  const core = window.UplinkCore;
+  if (core) core.chatState = 'idle';
+  
+  autoHoldMode = false;
+  isRecording = false;
+  voiceBtn?.classList.remove('recording', 'processing', 'auto-hold');
+  if (voiceStatus) voiceStatus.textContent = getVoiceStatusLabel();
+}
+
+/**
+ * Get the appropriate voice status label based on voice mode config
+ * @returns {string}
+ */
+function getVoiceStatusLabel() {
+  const cfg = cachedClientConfig;
+  const voiceMode = cfg?.voiceMode || 'push-to-talk';
+  
+  if (voiceMode === 'agent-voice') {
+    const name = cfg?.assistantName || 'Agent';
+    return `Talk to ${name}`;
+  } else if (voiceMode === 'live-voice') {
+    return 'Tap to start live voice';
+  }
+  return 'Hold to talk';
+}
+
+function release() {
+  // Clear intervals
+  if (timerInterval) {
+    clearInterval(timerInterval);
+    timerInterval = null;
+  }
+  if (monitorInterval) {
+    clearInterval(monitorInterval);
+    monitorInterval = null;
+  }
+
+  // Stop recording if active
+  if (isRecording) {
+    stopRecording();
+  }
+
+  // Close audio context
+  if (audioContext) {
+    audioContext.close().catch(err => console.error('Voice: AudioContext close failed:', err));
+    audioContext = null;
+    analyser = null;
+  }
+
+  // Stop and release media stream
+  if (stream) {
+    stream.getTracks().forEach(track => track.stop());
+    stream = null;
+  }
+
+  // Clean up observer
+  if (moonObserver) {
+    moonObserver.disconnect();
+    moonObserver = null;
+  }
+
+  // Clean up Three.js resources
+  if (moonRenderer) {
+    moonRenderer.dispose();
+    moonRenderer = null;
+  }
+  if (moonModel?.geometry) {
+    moonModel.geometry.dispose();
+  }
+  if (moonModel?.material) {
+    moonModel.material.dispose();
+    if (moonModel.material.map) moonModel.material.map.dispose();
+  }
+  if (haloMesh?.geometry) {
+    haloMesh.geometry.dispose();
+  }
+  if (haloMesh?.material) {
+    haloMesh.material.dispose();
+  }
+  moonScene = null;
+  moonCamera = null;
+  moonModel = null;
+  haloMesh = null;
+  moonInitialized = false;
+
+  resetVoice();
+  logger.debug('Voice: Released');
+}
+
+// ========== Event Handlers ==========
+
+function setupVoiceEvents() {
+  if (!voiceBtn) return;
+
+  // Double-tap detection
+  function handleTap() {
+    const now = Date.now();
+    const core = window.UplinkCore;
+
+    // If realtime voice is active, any tap stops it
+    if (window.UplinkRealtime && typeof window.UplinkRealtime.isActive === 'function' && window.UplinkRealtime.isActive()) {
+      window.UplinkRealtime.stop();
+      if (voiceStatus) voiceStatus.textContent = getVoiceStatusLabel();
+      lastTapTime = now;
+      return;
+    }
+    
+    if (now - lastTapTime < DOUBLE_TAP_DELAY_MS && !autoHoldMode && core?.chatState === 'idle') {
+      autoHoldMode = true;
+      voiceBtn.classList.add('auto-hold');
+      silenceStart = null;
+      startRecording();
+    } else if (autoHoldMode && isRecording) {
+      autoHoldMode = false;
+      voiceBtn.classList.remove('auto-hold');
+      stopRecording();
+    }
+    lastTapTime = now;
+  }
+
+  // Track recent touch to prevent mouse event double-firing on touch devices
+  let lastTouchEnd = 0;
+  const TOUCH_MOUSE_DEBOUNCE_MS = 500;
+
+  // Touch events
+  let touchStart = 0, isTouchHold = false;
+  
+  voiceBtn.addEventListener('touchstart', (e) => {
+    e.preventDefault();
+    touchStart = Date.now();
+    isTouchHold = false;
+    
+    // Don't start new recording if realtime is active (tap will stop it)
+    if (window.UplinkRealtime?.isActive?.()) return;
+    if (autoHoldMode && isRecording) return;
+    
+    const core = window.UplinkCore;
+    if (!autoHoldMode && core?.chatState === 'idle') {
+      setTimeout(() => {
+        if (!autoHoldMode && core?.chatState === 'idle' && Date.now() - touchStart > TAP_VS_HOLD_THRESHOLD_MS) {
+          isTouchHold = true;
+          startRecording();
+        }
+      }, HOLD_DETECTION_DELAY_MS);
+    }
+  }, { passive: false });
+
+  voiceBtn.addEventListener('touchend', (e) => {
+    e.preventDefault();
+    lastTouchEnd = Date.now();
+    if (Date.now() - touchStart < TAP_VS_HOLD_THRESHOLD_MS) handleTap();
+    else if (isTouchHold && !autoHoldMode && isRecording) stopRecording();
+    isTouchHold = false;
+  }, { passive: false });
+
+  // Mouse events - skip if recently handled by touch (prevents double-firing)
+  let mouseStart = 0, isMouseHold = false;
+  
+  voiceBtn.addEventListener('mousedown', (e) => {
+    // Skip if this is a touch-originated mouse event
+    if (Date.now() - lastTouchEnd < TOUCH_MOUSE_DEBOUNCE_MS) return;
+    
+    mouseStart = Date.now();
+    isMouseHold = false;
+    
+    if (autoHoldMode && isRecording) return;
+    
+    const core = window.UplinkCore;
+    if (!autoHoldMode && core?.chatState === 'idle') {
+      setTimeout(() => {
+        if (!autoHoldMode && core?.chatState === 'idle' && Date.now() - mouseStart > TAP_VS_HOLD_THRESHOLD_MS) {
+          isMouseHold = true;
+          startRecording();
+        }
+      }, HOLD_DETECTION_DELAY_MS);
+    }
+  }, { passive: true });
+
+  voiceBtn.addEventListener('mouseup', (e) => {
+    // Skip if this is a touch-originated mouse event
+    if (Date.now() - lastTouchEnd < TOUCH_MOUSE_DEBOUNCE_MS) return;
+    
+    if (Date.now() - mouseStart < TAP_VS_HOLD_THRESHOLD_MS) handleTap();
+    else if (isMouseHold && !autoHoldMode && isRecording) stopRecording();
+    isMouseHold = false;
+  }, { passive: true });
+
+  voiceBtn.addEventListener('mouseleave', () => {
+    if (!autoHoldMode && isRecording && isMouseHold) {
+      stopRecording();
+      isMouseHold = false;
+    }
+  }, { passive: true });
+}
+
+function setupKeyboardShortcuts() {
+  document.addEventListener('keydown', (e) => {
+    const core = window.UplinkCore;
+    if (e.code === 'Space' && 
+        core?.mode === 'voice' && 
+        !e.target.matches('input, textarea') && 
+        core?.chatState === 'idle') {
+      e.preventDefault();
+      startRecording();
+    }
+  });
+
+  document.addEventListener('keyup', (e) => {
+    if (e.code === 'Space' && window.UplinkCore?.mode === 'voice' && isRecording) {
+      e.preventDefault();
+      stopRecording();
+    }
+  });
+}
+
+// Start moon animation (call when voice mode becomes visible)
+function startMoonAnimation() {
+  // Deferred init: create the WebGL context now that the canvas is visible
+  if (!moonInitialized) {
+    moonInitialized = true;
+    initMoon();
+  }
+  if (!moonAnimationRunning && moonRenderer) {
+    moonAnimationRunning = true;
+    animateMoon();
+  }
+}
+
+// Expose API
+export const UplinkVoice = {
+  startRecording,
+  stopRecording,
+  isRecording: () => isRecording,
+  release,
+  startMoonAnimation
+};
+
+import { UplinkCore } from './core.js';
+
+// Backward compat: assign to window
+window.UplinkVoice = UplinkVoice;
+
+// Helper for init retry with exponential backoff
+function scheduleInitRetry() {
+  if (initRetryCount >= MAX_INIT_RETRIES) {
+    logger.warn('Voice: Max init retries reached, giving up');
+    return;
+  }
+  initRetryCount++;
+  const delay = Math.min(INIT_RETRY_DELAY_MS * Math.pow(2, initRetryCount), 5000);
+  setTimeout(init, delay);
+}
+
+// Register and init
+UplinkCore.registerModule('voice', init);