Refine avatar diagnostics and prune legacy assets

.github/copilot-instructions.md

@@ -1,24 +1,71 @@
 Prime Directive:
-Deliver production-ready, systemic solutions to root causes. Prioritize core utility and absolute system integrity. There is zero tolerance for surface patches, brittle fixes, or non-functional code.
-Mandatory Protocol:
-Map the System: Before acting, map all relevant logic flows, data transformations, and dependencies. Identify all side effects.
-Isolate Root Cause: Diagnose the fundamental issue with code-based evidence. Ensure the fix is systemic and permanent.
-Align with Utility: Every change must advance the project's core objective. Reject low-impact optimizations.
-Implementation Mandates:
-Code Integrity: All code must be robust, generalizable, and directly executable. Prohibit all hardcoding, duplicated functionality, and placeholder logic.
-Quality & Security: Enforce static typing, descriptive naming, and strict linting. Validate all I/O, eliminate unsafe calls, and add regression guards.
-Testing: Test coverage must target both the symptom and its root cause. The full test suite must pass without warnings.
-Execution Workflow:
-Analyze system flow.
-Confirm root cause.
-Plan solution.
-Implement the robust fix.
-Validate with all tests.
-Document systemic insights.
-
-Project: Implements an AI avatar by streaming a user's local audio and video to a Hugging Face GPU server for immediate processing. In the cloud, the system performs simultaneous generative face swapping—animating a source image's identity with the user's live motion—and real-time voice conversion, which morphs the user's speech to a target profile while preserving the original prosody. The fully synchronized audio-visual output is then streamed back to the local machine, functioning as an integrated virtual camera and microphone for seamless use in communication platforms like Zoom and WhatsApp.
-
-Operational instructions:
-- All implementations must be architected for the huggingface space located at https://huggingface.co/spaces/Islamckennon/mirage
-- After every change, push to github and huggingface, then await user feedback for next steps.
-- All code must be archhitected towards project real-world functionality only.
+
+Ship production code. Core utility only. Zero tolerance for patches or broken code.
+
+
+
+MANDATORY Protocol (Non-negotiable):
+
+1. Map all existing system flows, dependencies, side effects BEFORE coding
+
+2. Diagnose root cause with code evidence - fix must be systemic
+
+3. Every change MUST advance project's core objective
+
+
+
+Implementation Rules:
+
+- Code: Robust, generalizable, executable. NO hardcoding/duplication/placeholders
+
+- Quality: Static typing, descriptive names, validate ALL I/O, eliminate unsafe calls
+
+- Testing: Cover symptom AND root cause. Full suite passes clean
+
+
+
+Issue Resolution Protocol:
+
+- Use error logs + user feedback to isolate exact failure point
+
+- Trace execution path from failure backwards to root cause
+
+- Fix ONLY the identified issue - no speculative changes
+
+- Verify fix resolves original problem without side effects
+
+
+
+Operational Simplicity:
+
+- DEFAULT to simple solutions - complexity requires justification
+
+- New features MUST prove real-world utility for THIS project
+
+- Reject abstractions that don't directly serve avatar streaming
+
+- If implementation > 50 lines, question if simpler path exists
+
+
+
+Workflow (ENFORCE):
+
+1. Analyze → 2. Diagnose → 3. Plan → 4. Implement → 5. Test → 6. Document
+
+
+
+Project: 
+
+AI avatar: Stream local A/V → HuggingFace Spacce withh a10 GPU → Realtime face-swap + voice conversion → Stream back as virtual camera/mic for Zoom/WhatsApp.
+
+
+
+Operations:
+
+- Target: https://huggingface.co/spaces/Islamckennon/mirage
+
+- Push GitHub/HuggingFace after EVERY change
+
+- Await user feedback before proceeding
+
+- Production functionality ONLY - no demos/experiments

static/README.static.md

@@ -0,0 +1,8 @@
+# Static Assets
+
+Only the enterprise WebRTC client is served in production.
+
+- `index.html` – main UI shell
+- `webrtc_enterprise.js` – sole runtime script
+
+Legacy bundles (`app.js`, `webrtc_prod.js`, `worklet.js`) were removed intentionally.

static/app.js

@@ -1,490 +0,0 @@
-/* DEPRECATED (dev WebSocket client). Removed for production. Use webrtc_prod.js */
-// This file intentionally contains no executable code in production deployments.
-// It remains only to avoid broken references from older pages; index.html does not load it.
-export {};
-
-// Globals
-let audioWs = null;
-let videoWs = null;
-let audioContext = null;
-let processorNode = null;
-let playerNode = null;
-let lastVideoSentTs = 0;
-let remoteImageURL = null;
-let isRunning = false;
-let pipelineInitialized = false;
-let referenceSet = false;
-let virtualCameraStream = null;
-let metricsInterval = null;
-
-// Configuration
-const videoMaxFps = 20; // Increased for real-time avatar
-const videoFrameIntervalMs = 1000 / videoMaxFps;
-
-// DOM elements
-const LOG_EL = document.getElementById('log');
-const INIT_BTN = document.getElementById('initBtn');
-const START_BTN = document.getElementById('startBtn');
-const STOP_BTN = document.getElementById('stopBtn');
-const LOCAL_VID = document.getElementById('localVid');
-const REMOTE_VID_IMG = document.getElementById('remoteVid');
-const REMOTE_AUDIO = document.getElementById('remoteAudio');
-const STATUS_DIV = document.getElementById('statusDiv');
-const REFERENCE_INPUT = document.getElementById('referenceInput');
-const VIRTUAL_CAM_BTN = document.getElementById('virtualCamBtn');
-const VIRTUAL_CANVAS = document.getElementById('virtualCanvas');
-
-function log(msg) {
-  const ts = new Date().toISOString().split('T')[1].replace('Z','');
-  LOG_EL.textContent += `[${ts}] ${msg}\n`;
-  LOG_EL.scrollTop = LOG_EL.scrollHeight;
-}
-
-function showStatus(message, type = 'info') {
-  STATUS_DIV.innerHTML = `<div class="status ${type}">${message}</div>`;
-  setTimeout(() => STATUS_DIV.innerHTML = '', 5000);
-}
-
-function wsURL(path) {
-  const proto = (location.protocol === 'https:') ? 'wss:' : 'ws:';
-  return `${proto}//${location.host}${path}`;
-}
-
-// Initialize AI Pipeline
-async function initializePipeline() {
-  INIT_BTN.disabled = true;
-  INIT_BTN.textContent = 'Initializing...';
-  
-  try {
-    log('Initializing AI pipeline...');
-    const response = await fetch('/initialize', { method: 'POST' });
-    const result = await response.json();
-    
-    if (result.status === 'success' || result.status === 'already_initialized') {
-      pipelineInitialized = true;
-      showStatus('AI pipeline initialized successfully!', 'success');
-      log('AI pipeline ready');
-      
-      // Enable controls
-      START_BTN.disabled = false;
-      REFERENCE_INPUT.disabled = false;
-      
-      // Start metrics updates
-      startMetricsUpdates();
-    } else {
-      showStatus(`Initialization failed: ${result.message}`, 'error');
-      log(`Pipeline init failed: ${result.message}`);
-    }
-  } catch (error) {
-    showStatus(`Initialization error: ${error.message}`, 'error');
-    log(`Init error: ${error}`);
-  } finally {
-    INIT_BTN.disabled = false;
-    INIT_BTN.textContent = 'Initialize AI Pipeline';
-  }
-}
-
-// Handle reference image upload
-async function handleReferenceUpload(event) {
-  const file = event.target.files[0];
-  if (!file) return;
-  
-  log('Uploading reference image...');
-  
-  try {
-    const formData = new FormData();
-    formData.append('file', file);
-    
-    const response = await fetch('/set_reference', {
-      method: 'POST',
-      body: formData
-    });
-    
-    const result = await response.json();
-    
-    if (result.status === 'success') {
-      referenceSet = true;
-      showStatus('Reference image set successfully!', 'success');
-      log('Reference image configured');
-      VIRTUAL_CAM_BTN.disabled = false;
-    } else {
-      showStatus(`Reference setup failed: ${result.message}`, 'error');
-      log(`Reference error: ${result.message}`);
-    }
-  } catch (error) {
-    showStatus(`Upload error: ${error.message}`, 'error');
-    log(`Reference upload error: ${error}`);
-  }
-}
-
-async function setupAudio(stream) {
-  audioContext = new (window.AudioContext || window.webkitAudioContext)({ sampleRate: 16000 });
-  if (audioContext.state === 'suspended') {
-    try { await audioContext.resume(); } catch (e) { log('AudioContext resume failed'); }
-  }
-
-  // Worklet loading
-  try {
-    await audioContext.audioWorklet.addModule('/static/worklet.js');
-  } catch (e) {
-    log('Failed to load worklet.js - audio processing disabled.');
-    console.error(e);
-    return;
-  }
-
-  // Enhanced chunk configuration for real-time processing
-  const chunkMs = 160; // Keep at 160ms for balance between latency and quality
-  const samplesPerChunk = Math.round(audioContext.sampleRate * (chunkMs / 1000));
-  
-  log(`Audio chunk config: sampleRate=${audioContext.sampleRate}Hz chunkMs=${chunkMs}ms samplesPerChunk=${samplesPerChunk}`);
-  
-  processorNode = new AudioWorkletNode(audioContext, 'pcm-chunker', {
-    processorOptions: { samplesPerChunk }
-  });
-  playerNode = new AudioWorkletNode(audioContext, 'pcm-player');
-
-  // Capture mic
-  const source = audioContext.createMediaStreamSource(stream);
-  source.connect(processorNode);
-  
-  // Keep worklet active
-  const gain = audioContext.createGain();
-  gain.gain.value = 0;
-  processorNode.connect(gain).connect(audioContext.destination);
-
-  processorNode.port.onmessage = (event) => {
-    if (!audioWs || audioWs.readyState !== WebSocket.OPEN) return;
-    const ab = event.data;
-    if (ab instanceof ArrayBuffer) audioWs.send(ab);
-  };
-
-  // Connect playback node
-  playerNode.connect(audioContext.destination);
-  log('Audio nodes ready (enhanced for AI processing)');
-}
-
-let _rxChunks = 0;
-function setupAudioWebSocket() {
-  audioWs = new WebSocket(wsURL('/audio'));
-  audioWs.binaryType = 'arraybuffer';
-  audioWs.onopen = () => log('Audio WebSocket connected');
-  audioWs.onclose = () => log('Audio WebSocket disconnected');
-  audioWs.onerror = (e) => log('Audio WebSocket error');
-  audioWs.onmessage = (evt) => {
-    if (!(evt.data instanceof ArrayBuffer)) return;
-    
-    const src = evt.data;
-    const copyBuf = src.slice(0);
-    
-    // Amplitude analysis for voice activity detection
-    const view = new Int16Array(src);
-    let min = 32767, max = -32768;
-    for (let i = 0; i < view.length; i++) { 
-      const v = view[i]; 
-      if (v < min) min = v; 
-      if (v > max) max = v; 
-    }
-    
-    // Forward to player
-    if (playerNode) playerNode.port.postMessage(copyBuf, [copyBuf]);
-    
-    _rxChunks++;
-    if ((_rxChunks % 30) === 0) { // Reduced logging frequency
-      log(`Audio processed: ${_rxChunks} chunks, amp:[${min},${max}]`);
-    }
-  };
-}
-
-async function setupVideo(stream) {
-  const track = stream.getVideoTracks()[0];
-  if (!track) {
-    log('No video track found');
-    return;
-  }
-  
-  const processor = new MediaStreamTrackProcessor({ track });
-  const reader = processor.readable.getReader();
-
-  const canvas = document.createElement('canvas');
-  canvas.width = 512;  // Increased resolution for AI processing
-  canvas.height = 512;
-  const ctx = canvas.getContext('2d');
-
-  async function readLoop() {
-    try {
-      const { value: frame, done } = await reader.read();
-      if (done) return;
-
-      const now = performance.now();
-      const elapsed = now - lastVideoSentTs;
-      const needSend = elapsed >= videoFrameIntervalMs;
-
-      if (needSend && frame) {
-        try {
-          // Draw frame with improved quality
-          if ('displayWidth' in frame && 'displayHeight' in frame) {
-            ctx.drawImage(frame, 0, 0, canvas.width, canvas.height);
-          } else {
-            const bmp = await createImageBitmap(frame);
-            ctx.drawImage(bmp, 0, 0, canvas.width, canvas.height);
-            bmp.close && bmp.close();
-          }
-
-          // Send to AI pipeline with higher quality
-          await new Promise((res, rej) => {
-            canvas.toBlob((blob) => {
-              if (!blob) return res();
-              blob.arrayBuffer().then((ab) => {
-                if (videoWs && videoWs.readyState === WebSocket.OPEN) {
-                  videoWs.send(ab);
-                }
-                res();
-              }).catch(rej);
-            }, 'image/jpeg', 0.8); // Higher quality for AI processing
-          });
-          
-          lastVideoSentTs = now;
-        } catch (err) {
-          log('Video frame processing error');
-          console.error(err);
-        }
-      }
-
-      frame.close && frame.close();
-      readLoop();
-    } catch (err) {
-      log('Video read loop error');
-      console.error(err);
-    }
-  }
-  readLoop();
-}
-
-function setupVideoWebSocket() {
-  videoWs = new WebSocket(wsURL('/video'));
-  videoWs.binaryType = 'arraybuffer';
-  videoWs.onopen = () => log('Video WebSocket connected');
-  videoWs.onclose = () => log('Video WebSocket disconnected');
-  videoWs.onerror = () => log('Video WebSocket error');
-  videoWs.onmessage = (evt) => {
-    if (!(evt.data instanceof ArrayBuffer)) return;
-    
-    // Display AI-processed video
-    const blob = new Blob([evt.data], { type: 'image/jpeg' });
-    if (remoteImageURL) URL.revokeObjectURL(remoteImageURL);
-    remoteImageURL = URL.createObjectURL(blob);
-    REMOTE_VID_IMG.src = remoteImageURL;
-    
-    // Update virtual camera if enabled
-    updateVirtualCamera(evt.data);
-  };
-}
-
-// Virtual Camera Support
-function updateVirtualCamera(imageData) {
-  if (!virtualCameraStream) return;
-  
-  try {
-    // Create image from received data
-    const blob = new Blob([imageData], { type: 'image/jpeg' });
-    const img = new Image();
-    
-    img.onload = () => {
-      // Draw to virtual canvas
-      const ctx = VIRTUAL_CANVAS.getContext('2d');
-      VIRTUAL_CANVAS.width = 512;
-      VIRTUAL_CANVAS.height = 512;
-      ctx.drawImage(img, 0, 0, 512, 512);
-    };
-    
-    img.src = URL.createObjectURL(blob);
-  } catch (error) {
-    console.error('Virtual camera update error:', error);
-  }
-}
-
-async function enableVirtualCamera() {
-  try {
-    if (!VIRTUAL_CANVAS.captureStream) {
-      showStatus('Virtual camera not supported in this browser', 'error');
-      return;
-    }
-    
-    // Create virtual camera stream from canvas
-    virtualCameraStream = VIRTUAL_CANVAS.captureStream(30);
-    
-    // Try to create a virtual camera device (browser-dependent)
-    if (navigator.mediaDevices.getDisplayMedia) {
-      log('Virtual camera enabled - canvas stream ready');
-      showStatus('Virtual camera enabled! Use canvas stream in video apps.', 'success');
-      VIRTUAL_CAM_BTN.textContent = 'Virtual Camera Active';
-      VIRTUAL_CAM_BTN.disabled = true;
-    } else {
-      showStatus('Virtual camera API not available', 'error');
-    }
-  } catch (error) {
-    showStatus(`Virtual camera error: ${error.message}`, 'error');
-    log(`Virtual camera error: ${error}`);
-  }
-}
-
-// Metrics and Performance Monitoring
-function startMetricsUpdates() {
-  if (metricsInterval) clearInterval(metricsInterval);
-  
-  metricsInterval = setInterval(async () => {
-    try {
-      const response = await fetch('/pipeline_status');
-      const data = await response.json();
-      
-      if (data.initialized && data.stats) {
-        const stats = data.stats;
-        
-        document.getElementById('fpsValue').textContent = stats.video_fps?.toFixed(1) || '0';
-        document.getElementById('latencyValue').textContent = 
-          Math.round(stats.avg_video_latency_ms || 0) + 'ms';
-        document.getElementById('gpuValue').textContent = 
-          stats.gpu_memory_used?.toFixed(1) + 'GB' || 'N/A';
-        document.getElementById('statusValue').textContent = 
-          stats.models_loaded ? 'Active' : 'Loading';
-      }
-    } catch (error) {
-      console.error('Metrics update error:', error);
-    }
-  }, 2000); // Update every 2 seconds
-}
-
-async function start() {
-  if (!pipelineInitialized) {
-    showStatus('Please initialize the AI pipeline first', 'error');
-    return;
-  }
-  
-  START_BTN.disabled = true;
-  START_BTN.textContent = 'Starting...';
-  
-  log('Requesting media access...');
-  
-  try {
-    const stream = await navigator.mediaDevices.getUserMedia({ 
-      audio: true, 
-      video: { 
-        width: 640, 
-        height: 480, 
-        frameRate: 30 
-      } 
-    });
-    
-    LOCAL_VID.srcObject = stream;
-    log('Media access granted');
-    
-    // Setup WebSocket connections
-    setupAudioWebSocket();
-    setupVideoWebSocket();
-    
-    // Setup audio and video processing
-    await setupAudio(stream);
-    await setupVideo(stream);
-    
-    isRunning = true;
-    START_BTN.style.display = 'none';
-    STOP_BTN.disabled = false;
-    STOP_BTN.style.display = 'inline-block';
-    
-    log(`Real-time AI avatar started: ${videoMaxFps} fps, 160ms audio chunks`);
-    showStatus('AI Avatar system is now running!', 'success');
-    
-  } catch (error) {
-    showStatus(`Media access failed: ${error.message}`, 'error');
-    log(`getUserMedia failed: ${error}`);
-    START_BTN.disabled = false;
-    START_BTN.textContent = 'Start Capture';
-  }
-}
-
-function stop() {
-  log('Stopping AI avatar system...');
-  
-  // Close WebSocket connections
-  if (audioWs) {
-    audioWs.close();
-    audioWs = null;
-  }
-  if (videoWs) {
-    videoWs.close();
-    videoWs = null;
-  }
-  
-  // Stop media tracks
-  if (LOCAL_VID.srcObject) {
-    LOCAL_VID.srcObject.getTracks().forEach(track => track.stop());
-    LOCAL_VID.srcObject = null;
-  }
-  
-  // Reset audio context
-  if (audioContext) {
-    audioContext.close();
-    audioContext = null;
-  }
-  
-  // Reset UI
-  isRunning = false;
-  START_BTN.disabled = false;
-  START_BTN.textContent = 'Start Capture';
-  START_BTN.style.display = 'inline-block';
-  STOP_BTN.disabled = true;
-  STOP_BTN.style.display = 'none';
-  
-  log('System stopped');
-  showStatus('AI Avatar system stopped', 'info');
-}
-
-// Event Listeners
-INIT_BTN.addEventListener('click', initializePipeline);
-START_BTN.addEventListener('click', start);
-STOP_BTN.addEventListener('click', stop);
-REFERENCE_INPUT.addEventListener('change', handleReferenceUpload);
-VIRTUAL_CAM_BTN.addEventListener('click', enableVirtualCamera);
-
-// Debug functions
-function testTone(seconds = 1, freq = 440) {
-  if (!audioContext || !playerNode) { 
-    log('testTone: audio not ready'); 
-    return; 
-  }
-  
-  const sampleRate = audioContext.sampleRate;
-  const total = Math.floor(sampleRate * seconds);
-  const int16 = new Int16Array(total);
-  
-  for (let i = 0; i < total; i++) {
-    const s = Math.sin(2 * Math.PI * freq * (i / sampleRate));
-    int16[i] = s * 32767;
-  }
-  
-  const chunk = Math.floor(sampleRate * 0.25);
-  for (let off = 0; off < int16.length; off += chunk) {
-    const view = int16.subarray(off, Math.min(off + chunk, int16.length));
-    const copy = new Int16Array(view.length);
-    copy.set(view);
-    playerNode.port.postMessage(copy.buffer, [copy.buffer]);
-  }
-  
-  log(`Test tone ${freq}Hz for ${seconds}s injected`);
-}
-
-// Global API for debugging
-window.__mirage = { 
-  start, 
-  stop, 
-  initializePipeline,
-  audioWs: () => audioWs, 
-  videoWs: () => videoWs, 
-  testTone,
-  pipelineInitialized: () => pipelineInitialized,
-  referenceSet: () => referenceSet
-};
-
-// Auto-initialize on load for development
-log('Mirage Real-time AI Avatar System loaded');
-log('Click "Initialize AI Pipeline" to begin setup');

static/index.html

@@ -524,6 +524,7 @@
         <span class="stage-step" data-stage="offer-sent">Offer</span>
         <span class="stage-step" data-stage="ice-gathering">ICE</span>
         <span class="stage-step" data-stage="answer-received">Answer</span>
+    <span class="stage-step" data-stage="finalizing">Finalize</span>
         <span class="stage-step" data-stage="remote-media">Video</span>
         <span class="stage-step" data-stage="connected">Ready</span>
       </div>

static/webrtc_client.js

@@ -1,4 +0,0 @@
-/* Legacy dev WebRTC bootstrap (no-op in production). */
-(function(){
-  // intentionally empty
-})();

static/webrtc_enterprise.js

@@ -152,7 +152,7 @@
   }
 
   /* ---------------- Stage / Timeline Management ---------------- */
-  const stageOrder = ['init','local-media','offer-sent','ice-gathering','answer-received','remote-media','connected'];
+  const stageOrder = ['init','local-media','offer-sent','ice-gathering','answer-received','finalizing','remote-media','connected'];
   function setStage(newStage){
     if(!els.stageTimeline) return;
     if(!stageOrder.includes(newStage)) return;
@@ -169,6 +169,36 @@
   }
   setStage('init');
 
+  const overlayState = { visible: true, message: 'Avatar feed will appear here', mode: 'idle' };
+  function setAvatarOverlay(visible, message, mode){
+    const overlay = els.avatarOverlay;
+    if(!overlay) return;
+    const nextMessage = (message !== undefined && message !== null) ? message : overlayState.message;
+    const nextMode = mode || overlayState.mode;
+    if(nextMessage !== overlayState.message){
+      overlay.innerHTML = `<span>${nextMessage}</span>`;
+      overlayState.message = nextMessage;
+    }
+    if(nextMode !== overlayState.mode){
+      overlay.dataset.state = nextMode;
+      overlayState.mode = nextMode;
+    }
+    if(overlayState.visible !== visible){
+      overlay.style.opacity = visible ? 1 : 0;
+      overlayState.visible = visible;
+    }
+  }
+  function showAvatarOverlay(message, mode){
+    setAvatarOverlay(true, message, mode);
+  }
+  function hideAvatarOverlay(force=false){
+    if(!force && !['waiting','warming','black','info'].includes(overlayState.mode)){
+      return;
+    }
+    setAvatarOverlay(false, null, 'active');
+  }
+  setAvatarOverlay(true, overlayState.message, overlayState.mode);
+
   /* --------------- Frame Counter & Black Frame Detection --------------- */
   let framePollTimer = null;
   let blackDetectTimer = null;
@@ -185,12 +215,31 @@
         if (j && j.frames_emitted != null && els.frameCounterDisplay) {
           els.frameCounterDisplay.textContent = 'Frames:' + j.frames_emitted;
         }
+        if(!j || j.active === false){
+          setAvatarOverlay(true, 'Avatar feed will appear here', 'idle');
+          return;
+        }
+        if(overlayState.mode === 'error'){
+          return;
+        }
+        if(j.source_bound === false){
+          showAvatarOverlay('Awaiting camera stream…', 'waiting');
+        } else if(j.placeholder_active){
+          showAvatarOverlay('Avatar pipeline warming up…', 'warming');
+        } else if((j.real_frames || 0) > 0 && overlayState.mode !== 'black'){
+          hideAvatarOverlay();
+        }
+        if(typeof j.luma_last === 'number' && j.luma_last <= 5 && (j.real_frames || 0) > 0){
+          showAvatarOverlay('Frames detected but extremely dark', 'info');
+        } else if (overlayState.mode === 'info' && (j.real_frames || 0) > 0) {
+          hideAvatarOverlay(true);
+        }
       } catch(_){ }
     }, 2000);
   }
   function startBlackDetection(){
     if(blackDetectTimer) clearInterval(blackDetectTimer);
-    const vid = els.remoteVideo; const overlay = els.avatarOverlay;
+  const vid = els.remoteVideo;
     if(!vid) return;
     const canvas = document.createElement('canvas');
     const ctx = canvas.getContext('2d');
@@ -204,13 +253,10 @@
         for (let i=0;i<data.length;i+=4){ sum += (data[i]*0.2126 + data[i+1]*0.7152 + data[i+2]*0.0722); count++; }
         const avg = sum / count;
         if (avg < BLACK_THRESHOLD) blackSampleConsecutive++; else blackSampleConsecutive = 0;
-        if (overlay){
-          if (blackSampleConsecutive >= BLACK_CONSECUTIVE_LIMIT){
-            overlay.style.opacity = 1;
-            overlay.innerHTML = '<span>Receiving black/placeholder frames... (pipeline warming or no source)</span>';
-          } else if (blackSampleConsecutive === 0 && overlay.innerText.includes('black/placeholder')) {
-            overlay.style.opacity = 0;
-          }
+        if (blackSampleConsecutive >= BLACK_CONSECUTIVE_LIMIT){
+          showAvatarOverlay('Receiving black frames… (pipeline warming or no source)', 'black');
+        } else if (blackSampleConsecutive === 0 && overlayState.mode === 'black') {
+          hideAvatarOverlay();
         }
       } catch(_){ }
     }, 1000);
@@ -488,6 +534,7 @@
             setSystemStatus('connected', 'Avatar stream received');
             setAvatarStatus('connected', 'Active');
             setStage('remote-media');
+            showAvatarOverlay('Waiting for avatar frames…', 'waiting');
             
             let stream;
             if (ev.streams && ev.streams[0]) {
@@ -534,11 +581,13 @@
               setAvatarStatus('idle', 'Disconnected');
               if (els.avatarWrapper) els.avatarWrapper.classList.remove('active');
             };
+                  hideAvatarOverlay();
             
             tr.onmute = () => {
               log('video track muted');
               setAvatarStatus('warning', 'Muted');
             };
+                  showAvatarOverlay('Avatar stream error', 'error');
             
             tr.onunmute = () => {
               log('video track unmuted');
@@ -546,16 +595,19 @@
             };
             
           } else if (tr && tr.kind === 'audio') {
+                  setAvatarOverlay(true, 'Avatar feed will appear here', 'idle');
             setSystemStatus('connected', 'Audio stream received');
           }
         } catch(e) { 
           log('ontrack error', e);
           setAvatarStatus('error', 'Connection Error');
+                  showAvatarOverlay('Avatar stream muted', 'info');
         }
       };
 
       // Data channel setup
       state.control = state.pc.createDataChannel('control');
+                  hideAvatarOverlay();
       
       state.control.onopen = () => {
         setSystemStatus('connected', 'WebRTC connection established');
@@ -649,6 +701,9 @@
   const answer = await r.json();
   await state.pc.setRemoteDescription(new RTCSessionDescription(answer));
   setStage('answer-received');
+  setStage('finalizing');
+  setSystemStatus('connecting', 'Finalizing connection...');
+  showAvatarOverlay('Preparing avatar stream…', 'waiting');
       log('WebRTC negotiation complete');
 
     } catch(e) {
@@ -657,6 +712,7 @@
       showToast('Failed to establish connection', 'error');
       state.connecting = false;
       setButtonLoading(els.connect, false);
+      setAvatarOverlay(true, 'Avatar feed will appear here', 'idle');
       throw e;
     }
   }
@@ -676,6 +732,16 @@
       clearInterval(state.metricsTimer); 
       state.metricsTimer = null; 
     }
+    if (framePollTimer) {
+      clearInterval(framePollTimer);
+      framePollTimer = null;
+    }
+    if (blackDetectTimer) {
+      clearInterval(blackDetectTimer);
+      blackDetectTimer = null;
+    }
+    blackSampleConsecutive = 0;
+    setAvatarOverlay(true, 'Avatar feed will appear here', 'idle');
 
     // Close connections
     if (state.control) { 
@@ -738,6 +804,7 @@
     els.connect.disabled = false; 
     els.disconnect.disabled = true; 
     setSystemStatus('idle', 'Disconnected');
+    setStage('init');
     showToast('Connection terminated', 'warning');
   }
 

static/worklet.js

@@ -1,87 +0,0 @@
-class PCMChunker extends AudioWorkletProcessor {
-  constructor(options) {
-    super();
-    // samplesPerChunk is injected from main thread (B8 sets 160ms @16kHz = 2560 samples)
-    this.samplesPerChunk = (options && options.processorOptions && options.processorOptions.samplesPerChunk) || 16000;
-    this.buffer = new Float32Array(this.samplesPerChunk);
-    this.offset = 0;
-  }
-
-  process(inputs) {
-    const input = inputs[0];
-    if (input && input[0]) {
-      const data = input[0];
-      let i = 0;
-      while (i < data.length) {
-        const space = this.samplesPerChunk - this.offset;
-        const toCopy = Math.min(space, data.length - i);
-        this.buffer.set(data.subarray(i, i + toCopy), this.offset);
-        this.offset += toCopy;
-        i += toCopy;
-        if (this.offset >= this.samplesPerChunk) {
-          const out = new Int16Array(this.samplesPerChunk);
-          for (let j = 0; j < this.samplesPerChunk; j++) {
-            let s = this.buffer[j];
-            if (s > 1) s = 1; else if (s < -1) s = -1;
-            out[j] = s < 0 ? s * 32768 : s * 32767;
-          }
-          const buf = out.buffer;
-          this.port.postMessage(buf, [buf]);
-          this.offset = 0;
-        }
-      }
-    }
-    return true;
-  }
-}
-
-registerProcessor('pcm-chunker', PCMChunker);
-
-// PCM player pulls Int16 buffers from a queue pushed via port messages and outputs Float32 samples.
-class PCMPlayer extends AudioWorkletProcessor {
-  constructor() {
-    super();
-    this.queue = [];
-    this.current = null;
-    this.offset = 0;
-    this.samplesPerBuffer = 0;
-    this.port.onmessage = (e) => {
-      const d = e.data;
-      if (d instanceof ArrayBuffer) {
-        this.queue.push(new Int16Array(d));
-      } else if (d instanceof Int16Array) {
-        this.queue.push(d);
-      }
-    };
-  }
-  process(_inputs, outputs) {
-    const output = outputs[0][0];
-    if (!output) return true;
-    let i = 0;
-    while (i < output.length) {
-      if (!this.current) {
-        this.current = this.queue.shift();
-        this.offset = 0;
-        if (!this.current) {
-          // Fill rest with silence
-          while (i < output.length) output[i++] = 0;
-          break;
-        }
-      }
-      const remain = this.current.length - this.offset;
-      const needed = output.length - i;
-      const toCopy = Math.min(remain, needed);
-      for (let j = 0; j < toCopy; j++) {
-        output[i + j] = this.current[this.offset + j] / 32768;
-      }
-      i += toCopy;
-      this.offset += toCopy;
-      if (this.offset >= this.current.length) {
-        this.current = null;
-      }
-    }
-    return true;
-  }
-}
-
-registerProcessor('pcm-player', PCMPlayer);