@mooncompany/uplink-chat 0.5.0

package/public/js/chat.js

@@ -0,0 +1,1211 @@
+// ============================================
+// CHAT MODULE
+// Message sending, receiving, display
+// ============================================
+// Chat module v7 - streaming working
+
+import { UplinkLogger } from './logger.js';
+import { UplinkCore } from './core.js';
+import { UplinkStorage } from './storage.js';
+import { UplinkErrors } from './errors.js';
+import { UplinkStreamingHandler } from './streaming-handler.js';
+import { UplinkMessageRenderer } from './message-renderer.js';
+import { UplinkAudioQueue } from './audio-queue.js';
+import { UplinkOfflineQueue } from './offline-queue.js';
+import { UplinkFileHandler } from './file-handler.js';
+import { emit as emitEvent } from './event-bus.js';
+
+// DOM elements (cached on init)
+let messagesEl, emptyStateEl, textInput, sendBtn, typingEl, stopBtn;
+
+// Auto-scroll behavior
+const SCROLL_THRESHOLD_PX = 100;
+let isNearBottom = true;
+let scrollToBottomBtn = null;
+let hasUnreadMessages = false;
+
+// Typing indicator timeout (30 seconds for text, 5 minutes for images)
+const TYPING_TIMEOUT_MS = 120000; // 2 minutes (thinking status will reset it sooner)
+const IMAGE_TYPING_TIMEOUT_MS = 300000; // 5 minutes for image analysis
+let typingTimeoutId = null;
+
+// Message queue for when processing
+const messageQueue = [];
+
+// Offline message queue — delegated to UplinkOfflineQueue module
+
+// Message hooks - allows other modules to observe messages without patching
+// This replaces the window.addMessage patching pattern used by satellites/notifications
+const messageHooks = [];
+
+// Abort controller for stopping generation
+let currentAbortController = null;
+
+// Submission lock to prevent double-submit race conditions
+let isSubmitting = false;
+
+// AbortController for event listeners cleanup
+let eventsAbortController = null;
+
+// Module init retry state
+let initRetryCount = 0;
+const MAX_INIT_RETRIES = 10;
+
+// Offline queue functions now live in offline-queue.js (UplinkOfflineQueue)
+
+// Initialize
+function init() {
+  messagesEl = document.getElementById('messages');
+  emptyStateEl = document.getElementById('emptyState');
+  textInput = document.getElementById('textInput');
+  sendBtn = document.getElementById('sendBtn');
+
+  if (!messagesEl || !textInput) {
+    if (initRetryCount >= MAX_INIT_RETRIES) {
+      logger.error('Chat: Required elements not found after max retries, giving up');
+      return;
+    }
+    initRetryCount++;
+    const delay = Math.min(100 * Math.pow(2, initRetryCount), 5000);
+    logger.warn(`Chat: Required elements not found, retrying (${initRetryCount}/${MAX_INIT_RETRIES})...`);
+    setTimeout(init, delay);
+    return;
+  }
+
+  // Abort previous event listeners to prevent stacking if init called multiple times
+  if (eventsAbortController) {
+    eventsAbortController.abort();
+  }
+  eventsAbortController = new AbortController();
+  const signal = eventsAbortController.signal;
+
+  updateScrollState();
+  messagesEl.addEventListener('scroll', updateScrollState, { passive: true, signal });
+
+  // Add aria-live region for screen reader announcements
+  messagesEl.setAttribute('aria-live', 'polite');
+  messagesEl.setAttribute('aria-atomic', 'false');
+  messagesEl.setAttribute('aria-relevant', 'additions');
+
+  // Event listeners
+  sendBtn?.addEventListener('click', () => {
+    // If in stop mode (send-stop class, no text in input), abort generation
+    if (isSendingState && sendBtn.classList.contains('send-stop')) {
+      stopGeneration();
+      return;
+    }
+    handleSubmit();
+  }, { signal });
+  
+  // Detect mobile/touch device
+  const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) 
+                   || ('ontouchstart' in window);
+  
+  textInput.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') {
+      // On mobile: Enter = new line, use Send button to submit
+      // On desktop: Enter = submit, Shift+Enter = new line
+      if (isMobile) {
+        // Let Enter add new line naturally on mobile
+        return;
+      }
+      
+      if (!e.shiftKey) {
+        // Don't handle if it's a slash command
+        if (textInput.value.trim().startsWith('/')) return;
+        e.preventDefault();
+        handleSubmit();
+      }
+    }
+  }, { signal });
+
+  // Auto-resize textarea — and keep messages scrolled to bottom as input grows
+  // Also toggle send/stop icon when user types during streaming
+  textInput.addEventListener('input', () => {
+    const prevHeight = textInput.offsetHeight;
+    textInput.style.height = 'auto';
+    textInput.style.height = Math.min(textInput.scrollHeight, 150) + 'px';
+    const delta = textInput.offsetHeight - prevHeight;
+    // If the input grew and user was near the bottom, scroll to compensate
+    if (delta > 0 && messagesEl && isNearBottom) {
+      messagesEl.scrollTop += delta;
+    }
+
+    // Change 2: Toggle send/stop button based on input content during streaming
+    if (isSendingState && sendBtn) {
+      if (textInput.value.trim().length > 0) {
+        showSendIcon();
+      } else {
+        showStopIcon();
+      }
+    }
+  }, { signal });
+
+  // Load offline queue from localStorage
+  if (window.UplinkOfflineQueue) {
+    window.UplinkOfflineQueue.load();
+  }
+
+  // Listen for online event to process queued messages
+  window.addEventListener('online', () => {
+    logger.debug('Chat: Network online, processing offline queue');
+    setTimeout(() => {
+      if (window.UplinkOfflineQueue) {
+        window.UplinkOfflineQueue.processQueue().catch(err =>
+          logger.error('Chat: Offline queue processing failed', err)
+        );
+      }
+    }, 1000); // Small delay to let connection stabilize
+  }, { signal });
+
+  // Listen for connection events to process queue
+  if (window.UplinkConnection) {
+    window.UplinkConnection.onConnection((event) => {
+      if (event === 'connected') {
+        setTimeout(() => {
+          if (window.UplinkOfflineQueue) {
+            window.UplinkOfflineQueue.processQueue().catch(err =>
+              logger.error('Chat: Offline queue processing failed', err)
+            );
+          }
+        }, 500);
+      }
+    });
+  }
+
+  // Load history (async but we don't block init on it — fire and forget with error handling)
+  loadHistory().catch(err => logger.error('Chat: Failed to load history', err));
+
+  // Initialize audio queue
+  if (window.UplinkAudioQueue) {
+    window.UplinkAudioQueue.init();
+  }
+
+  logger.debug('Chat: Initialized');
+}
+
+function updateScrollState() {
+  if (!messagesEl) return;
+  const distanceFromBottom = messagesEl.scrollHeight - messagesEl.scrollTop - messagesEl.clientHeight;
+  isNearBottom = distanceFromBottom <= SCROLL_THRESHOLD_PX;
+  
+  // If user scrolled to bottom, hide the button and clear unread flag
+  if (isNearBottom) {
+    hasUnreadMessages = false;
+    hideScrollToBottomBtn();
+  }
+}
+
+/**
+ * Create and show scroll-to-bottom button
+ */
+function showScrollToBottomBtn() {
+  if (scrollToBottomBtn || !messagesEl) return;
+  
+  scrollToBottomBtn = document.createElement('button');
+  scrollToBottomBtn.className = 'scroll-to-bottom-btn';
+  scrollToBottomBtn.innerHTML = '↓ New messages';
+  scrollToBottomBtn.title = 'Scroll to bottom';
+  scrollToBottomBtn.setAttribute('aria-label', 'Scroll to new messages');
+  scrollToBottomBtn.style.cssText = `
+    position: absolute;
+    bottom: 80px;
+    left: 50%;
+    transform: translateX(-50%);
+    background: var(--accent, #007bff);
+    color: white;
+    border: none;
+    border-radius: 20px;
+    padding: 8px 16px;
+    font-size: 13px;
+    cursor: pointer;
+    z-index: 100;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.3);
+    animation: fadeInUp 0.2s ease;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+  `;
+  
+  scrollToBottomBtn.onclick = () => {
+    if (messagesEl) {
+      messagesEl.scrollTo({ top: messagesEl.scrollHeight, behavior: 'smooth' });
+    }
+    hideScrollToBottomBtn();
+    hasUnreadMessages = false;
+  };
+  
+  // Insert after messages container
+  const chatContainer = messagesEl.parentElement;
+  if (chatContainer) {
+    chatContainer.style.position = 'relative';
+    chatContainer.appendChild(scrollToBottomBtn);
+  }
+}
+
+/**
+ * Hide scroll-to-bottom button
+ */
+function hideScrollToBottomBtn() {
+  if (scrollToBottomBtn) {
+    scrollToBottomBtn.remove();
+    scrollToBottomBtn = null;
+  }
+}
+
+// Load chat history from storage
+async function loadHistory() {
+  if (!window.UplinkStorage) return;
+
+  const history = await window.UplinkStorage.loadHistory();
+  if (history.length > 0) {
+    if (emptyStateEl) emptyStateEl.style.display = 'none';
+    history.forEach(msg => {
+      addMessage(msg.text, msg.type, msg.imageUrl, false, msg.timestamp || null);
+    });
+  }
+}
+
+// Handle message submission
+async function handleSubmit() {
+  // Prevent double submission race condition
+  if (isSubmitting) return;
+
+  let text = textInput.value.trim();
+  if (!text) return;
+
+  isSubmitting = true;
+  
+  // Show send-in-progress state
+  setSendingState(true);
+
+  // Format with reply context if replying to a message
+  if (window.UplinkMessageActions?.getReplyContext()) {
+    text = window.UplinkMessageActions.formatMessageWithReply(text);
+  }
+
+  // Check for pending image from files module
+  const pendingImage = window.UplinkFiles?.getPendingImage();
+  const hasImage = !!pendingImage;
+
+  // Check for pending text file from files module
+  const pendingFile = window.UplinkFiles?.getPendingFile();
+  const hasTextFile = !hasImage && pendingFile?.isText;
+
+  // If there's a text file, prepend its content to the message
+  if (hasTextFile) {
+    const fileHeader = `[File: ${pendingFile.name}]\n\`\`\`\n${pendingFile.content}\n\`\`\`\n\n`;
+    text = fileHeader + text;
+  }
+
+  textInput.value = '';
+  textInput.style.height = 'auto';
+
+  // Clear image preview if exists
+  if (hasImage) {
+    window.UplinkFiles?.clearPending();
+    const preview = document.getElementById('imagePreview');
+    if (preview) preview.classList.remove('visible');
+  }
+
+  // Clear text file preview if exists
+  if (hasTextFile) {
+    window.UplinkFiles?.clearPending();
+    const preview = document.getElementById('imagePreview');
+    if (preview) preview.classList.remove('visible');
+  }
+
+  // Check if we're offline - queue the message for later
+  if (!navigator.onLine && window.UplinkOfflineQueue) {
+    const queuedMsg = window.UplinkOfflineQueue.queueMessage(text, hasImage ? pendingImage : null);
+    if (emptyStateEl) emptyStateEl.style.display = 'none';
+    window.UplinkOfflineQueue.addMessageWithQueuedIndicator(
+      messagesEl, text, 'user', hasImage ? pendingImage : null, queuedMsg.id, formatMessage, isNearBottom
+    );
+    isSubmitting = false;
+    setSendingState(false);
+    return;
+  }
+
+  // If already processing, queue the message silently
+  const core = window.UplinkCore;
+  if (core && core.chatState !== 'idle') {
+    messageQueue.push({ text, imageUrl: hasImage ? pendingImage : null });
+    // Show the user's message immediately with a subtle "queued" indicator
+    const msgDiv = addMessage(text, 'user', hasImage ? pendingImage : null);
+    if (msgDiv) {
+      msgDiv.classList.add('queued');
+      msgDiv.title = 'Queued - will send after current response';
+    }
+    isSubmitting = false;
+    // Don't call setSendingState(false) — we're still streaming.
+    // Switch back to stop icon since input is now empty.
+    showStopIcon();
+    return;
+  }
+
+  try {
+    if (hasImage) {
+      await sendImageMessage(pendingImage, text);
+    } else if (pendingFile && !pendingFile.isText && pendingFile.blob) {
+      // Non-text file (PDF, DOCX, XLSX, etc.) — upload via /api/file
+      const fileToSend = pendingFile;
+      window.UplinkFiles?.clearPending();
+      const preview = document.getElementById('imagePreview');
+      if (preview) preview.classList.remove('visible');
+      await sendFileMessage(fileToSend, text);
+    } else {
+      await sendTextMessage(text);
+    }
+  } finally {
+    isSubmitting = false;
+    setSendingState(false);
+  }
+}
+
+// SVG icons for send button states
+const STOP_ICON_SVG = '<svg viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><rect x="2" y="2" width="12" height="12" rx="2"/></svg>';
+
+// Track whether we're currently in streaming/sending mode
+let isSendingState = false;
+
+/**
+ * Set visual state for send-in-progress
+ * When streaming: show stop icon. If user types, switch to send icon for queueing.
+ */
+function setSendingState(sending) {
+  isSendingState = sending;
+  if (!sendBtn) return;
+
+  sendBtn.classList.toggle('sending', sending);
+
+  if (sending) {
+    sendBtn.dataset.originalHtml = sendBtn.innerHTML;
+    showStopIcon();
+  } else {
+    sendBtn.classList.remove('send-stop');
+    if (sendBtn.dataset.originalHtml) {
+      sendBtn.innerHTML = sendBtn.dataset.originalHtml;
+    }
+    sendBtn.setAttribute('aria-label', 'Send message');
+  }
+  // Keep textInput enabled - allow typing while waiting for response
+}
+
+/**
+ * Show the stop icon on the send button
+ */
+function showStopIcon() {
+  if (!sendBtn) return;
+  sendBtn.classList.add('send-stop');
+  sendBtn.innerHTML = STOP_ICON_SVG;
+  sendBtn.setAttribute('aria-label', 'Stop generation');
+}
+
+/**
+ * Restore the send icon on the send button (for queueing during streaming)
+ */
+function showSendIcon() {
+  if (!sendBtn) return;
+  sendBtn.classList.remove('send-stop');
+  if (sendBtn.dataset.originalHtml) {
+    sendBtn.innerHTML = sendBtn.dataset.originalHtml;
+  }
+  sendBtn.setAttribute('aria-label', 'Send message');
+}
+
+// addMessageWithQueuedIndicator now lives in offline-queue.js (UplinkOfflineQueue)
+
+// ============================================
+// STREAMING HANDLER INSTANCE
+// Delegates streaming primitives to shared UplinkStreamingHandler
+// ============================================
+
+let chatStreamHandler = null;
+
+/**
+ * Get or create the streaming handler instance for the main chat.
+ * Lazily initialized because messagesEl may not be available at module load time.
+ * @returns {Object} StreamingHandler instance
+ */
+function getStreamHandler() {
+  if (!chatStreamHandler) {
+    // Ensure messagesEl is available (fallback query if init timing issue)
+    if (!messagesEl) {
+      messagesEl = document.getElementById('messages');
+    }
+    chatStreamHandler = window.UplinkStreamingHandler.create({
+      container: messagesEl,
+      formatMessage,
+      getIsNearBottom: () => isNearBottom,
+      showAvatar: true
+    });
+  }
+  return chatStreamHandler;
+}
+
+// ============================================
+// sendTextMessage - Extracted Helper Functions
+// ============================================
+
+/**
+ * Create streaming message container for assistant response
+ * Delegates to shared StreamingHandler.
+ * @returns {HTMLDivElement} The message container element
+ */
+function createStreamingMessageDiv() {
+  return getStreamHandler().createStreamingMessage();
+}
+
+/**
+ * Update streaming message content and handle auto-scroll.
+ * Delegates to shared StreamingHandler for throttled markdown rendering.
+ * @param {HTMLDivElement} _responseDiv - DEPRECATED: ignored, handler tracks its own div.
+ *   Kept for backward compatibility with connection.js callers.
+ * @param {string} content - Complete accumulated response text
+ */
+function updateStreamingContent(_responseDiv, content) {
+  getStreamHandler().updateStreamingContent(content);
+}
+
+/**
+ * Handle stream completion — finalize DOM if needed (WS-adopted divs),
+ * then apply chat-specific logic: usage stats, storage, seen-marking, hooks.
+ *
+ * When called from processStreamChunk's onDone callback, the shared handler
+ * has already finalized the div. When called from the WS-handled path in
+ * processSSEStream, the div is a WS sync stream adoption that needs DOM cleanup.
+ *
+ * @param {HTMLDivElement} responseDiv - The message container
+ * @param {string} fullResponse - Complete response text
+ * @param {Object} parsed - Parsed SSE data with usage info and media
+ */
+function handleStreamCompletion(responseDiv, fullResponse, parsed) {
+  // Finalize DOM if the div is still in streaming state (WS-adopted path)
+  if (responseDiv && responseDiv.classList.contains('streaming')) {
+    responseDiv.classList.remove('streaming');
+    responseDiv.dataset.originalText = fullResponse;
+    const textSpan = responseDiv.querySelector('.message-text');
+    if (textSpan && fullResponse) {
+      textSpan.innerHTML = formatMessage(fullResponse);
+    }
+  }
+  
+  // Add media images if present
+  if (responseDiv && parsed.media && parsed.media.length > 0) {
+    // Insert images before the text span
+    const textSpan = responseDiv.querySelector('.message-text');
+    parsed.media.forEach(mediaUrl => {
+      const img = document.createElement('img');
+      img.src = mediaUrl;
+      img.alt = 'Agent-generated media';
+      img.loading = 'lazy';
+      img.onerror = () => {
+        // Silently hide broken images
+        img.remove();
+      };
+      if (textSpan) {
+        responseDiv.insertBefore(img, textSpan);
+      } else {
+        responseDiv.appendChild(img);
+      }
+    });
+  }
+  
+  if (parsed.usage) {
+    if (window.UplinkDeveloper) {
+      window.UplinkDeveloper.updateTokens(parsed.usage);
+    }
+  }
+  // Refresh context tracker after message completes
+  if (parsed.done && window.UplinkContextTracker) {
+    window.UplinkContextTracker.refresh();
+  }
+  
+  if (fullResponse && window.UplinkStorage) {
+    window.UplinkStorage.saveMessage({ text: fullResponse, type: 'assistant' });
+  }
+  
+  // Mark message as seen to prevent sync broadcast duplicate
+  if (fullResponse && window.UplinkConnection?.markMessageSeen) {
+    window.UplinkConnection.markMessageSeen(null, 'assistant', fullResponse, Date.now());
+  }
+  
+  // Invoke message hooks for streamed assistant responses (for satellites, etc.)
+  if (fullResponse) {
+    for (const hook of messageHooks) {
+      try {
+        hook({ text: fullResponse, type: 'assistant', imageUrl: null, save: true });
+      } catch (e) {
+        logger.error('Chat: Message hook error (stream)', e);
+      }
+    }
+  }
+}
+
+/**
+ * Handle error received within SSE stream
+ * @param {string} errorMessage - Error message from stream
+ */
+function handleInStreamError(errorMessage) {
+  hideTyping();
+  const friendlyMsg = window.UplinkErrors?.getFriendlyMessage(errorMessage) || errorMessage;
+  addMessage(friendlyMsg, 'system', null, false);
+  if (window.UplinkDeveloper) {
+    window.UplinkDeveloper.logError(new Error(errorMessage), '/api/chat');
+  }
+}
+
+/**
+ * Handle fetch/network level errors
+ * @param {Error} err - The caught error
+ */
+function handleFetchError(err) {
+  hideTyping();
+  hideStopButton();
+  
+  if (err.name === 'AbortError') {
+    addMessage('Generation stopped', 'system', null, false);
+  } else {
+    const friendlyMsg = window.UplinkErrors?.getFriendlyMessage(err) || err.message;
+    addMessage(friendlyMsg, 'system', null, false);
+    if (window.UplinkDeveloper) {
+      window.UplinkDeveloper.logError(err, '/api/chat');
+    }
+  }
+}
+
+/**
+ * Process a single parsed SSE chunk.
+ * Delegates to the shared StreamingHandler.processChunk() for thinking/tool/content/done/error
+ * handling, with chat-specific callbacks for typing indicator, developer logging,
+ * and stream completion finalization.
+ *
+ * @param {Object} parsed - Parsed JSON from SSE data line
+ * @param {Object} state - Mutable state { responseDiv, fullResponse }
+ * @returns {Object} Updated state
+ */
+function processStreamChunk(parsed, state) {
+  const handler = getStreamHandler();
+
+  // Clear typing indicator on any real content event
+  if (parsed.status === 'thinking' || parsed.tool || parsed.content) {
+    clearTypingTimeout();
+    hideTyping();
+  }
+
+  handler.processChunk(parsed, {
+    onThinking: () => {
+      state.responseDiv = handler.getStreamingDiv();
+    },
+    onTool: (tool) => {
+      state.responseDiv = handler.getStreamingDiv();
+      if (window.UplinkDeveloper) {
+        window.UplinkDeveloper.logTool(tool);
+      }
+    },
+    onDone: ({ div, fullResponse, parsed: doneParsed }) => {
+      state.responseDiv = div;
+      state.fullResponse = fullResponse;
+      // Handle completion-specific logic (usage stats, storage save, hooks)
+      handleStreamCompletion(div, fullResponse, doneParsed);
+    },
+    onError: (errorMessage) => {
+      handleInStreamError(errorMessage);
+    }
+  });
+
+  // Keep state.responseDiv in sync with the handler's streaming div
+  if (!state.responseDiv && handler.getStreamingDiv()) {
+    state.responseDiv = handler.getStreamingDiv();
+  }
+  // Keep state.fullResponse in sync with accumulated content
+  if (handler.getStreamContent()) {
+    state.fullResponse = handler.getStreamContent();
+  }
+
+  return state;
+}
+
+/**
+ * Process SSE stream from response body
+ * 
+ * Handles the case where a WebSocket sync stream is already displaying
+ * content in real-time (e.g., when behind Cloudflare tunnel which buffers SSE).
+ * If a sync stream div exists, the SSE handler defers to it for display
+ * and only handles finalization (usage stats, save to storage).
+ * 
+ * @param {ReadableStreamDefaultReader} reader - Response body reader
+ * @returns {Promise<{responseDiv: HTMLDivElement|null, fullResponse: string, wsHandled: boolean}>}
+ */
+async function processSSEStream(reader) {
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let state = { responseDiv: null, fullResponse: '', wsHandled: false };
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (!line.startsWith('data: ')) continue;
+      
+      const data = line.slice(6);
+      if (data === '[DONE]' || data.startsWith(':')) continue;
+
+      try {
+        const parsed = JSON.parse(data);
+        
+        // Check if WebSocket sync stream has taken over display
+        // This happens when behind a buffering proxy (e.g. Cloudflare tunnel)
+        // where SSE chunks arrive late but WS deltas arrive in real-time
+        // Also check wasSyncStreamUsed() — the stream may have already been
+        // finalized by the sync message handler before SSE chunks arrive
+        if (!state.wsHandled && !state.responseDiv) {
+          const activeSyncStream = window.UplinkConnection?.findActiveSyncStream?.();
+          const alreadyFinalized = window.UplinkConnection?.wasSyncStreamUsed?.();
+          if (activeSyncStream || alreadyFinalized) {
+            state.wsHandled = true;
+            logger.debug('Chat: WebSocket sync stream active/finalized, SSE deferring to WS for display');
+          }
+        }
+
+        if (state.wsHandled) {
+          // Still accumulate full response and handle completion,
+          // but don't create/update a display div — WS stream handles that
+          if (parsed.tool && window.UplinkDeveloper) {
+            window.UplinkDeveloper.logTool(parsed.tool);
+          }
+          if (parsed.content) {
+            state.fullResponse += parsed.content;
+          }
+          if (parsed.done) {
+            // Adopt the sync stream div for finalization
+            const active = window.UplinkConnection?.findActiveSyncStream?.();
+            if (active) {
+              const adopted = window.UplinkConnection?.adoptSyncStream?.(active.requestId);
+              if (adopted) {
+                state.responseDiv = adopted.div;
+                if (!state.fullResponse && adopted.fullResponse) {
+                  state.fullResponse = adopted.fullResponse;
+                }
+              }
+            }
+            handleStreamCompletion(state.responseDiv, state.fullResponse, parsed);
+          }
+        } else {
+          state = processStreamChunk(parsed, state);
+        }
+        
+        // Force a paint by yielding to the browser
+        await new Promise(r => setTimeout(r, 0));
+      } catch (jsonParseError) {
+        // Skip unparseable chunks
+      }
+    }
+  }
+
+  return state;
+}
+
+// ============================================
+// sendTextMessage - Main Function (Refactored)
+// ============================================
+
+/**
+ * Send text message with streaming response
+ * @param {string} text - Message text to send
+ * @param {boolean} skipAddMessage - Skip adding user message (already shown when queued)
+ */
+async function sendTextMessage(text, skipAddMessage = false) {
+  const core = window.UplinkCore;
+  if (core) core.chatState = 'processing';
+
+  // Reset sync stream tracking for this new request
+  window.UplinkConnection?.resetSyncStreamUsed?.();
+
+  if (!skipAddMessage) addMessage(text, 'user');
+  
+  // Emit message:sent event for cross-module communication
+  emitEvent('message:sent', { text, type: 'user' });
+  
+  showTyping();
+  showStopButton();
+  currentAbortController = new AbortController();
+
+  try {
+    const satelliteId = window.UplinkSatellites?.getCurrentSatellite() || 'main';
+    const satellites = window.UplinkSatellites?.getSatellites() || {};
+    const satelliteName = satellites[satelliteId]?.name || satelliteId;
+    const agentId = window.UplinkSatellites?.getCurrentAgentId?.() || 'main';
+    
+    const chatResponse = await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message: text, stream: true, satelliteId, satelliteName, agentId }),
+      signal: currentAbortController.signal
+    });
+
+    if (!chatResponse.ok) {
+      throw new Error(`HTTP ${chatResponse.status}`);
+    }
+
+    const { responseDiv, fullResponse, wsHandled } = await processSSEStream(chatResponse.body.getReader());
+
+    hideTyping();
+    hideStopButton();
+    
+    // If WebSocket handled the streaming display, check if we need to finalize
+    if (wsHandled && !responseDiv) {
+      // WS stream may still be active — adopt it now for cleanup
+      const active = window.UplinkConnection?.findActiveSyncStream?.();
+      const adopted = active ? window.UplinkConnection?.adoptSyncStream?.(active.requestId) : null;
+      if (adopted) {
+        const finalContent = adopted.fullResponse || fullResponse;
+        if (window.UplinkChat?.finalizeSyncStream) {
+          window.UplinkChat.finalizeSyncStream(adopted.div, finalContent);
+        }
+        if (finalContent && window.UplinkStorage) {
+          window.UplinkStorage.saveMessage({ text: finalContent, type: 'assistant' });
+        }
+      }
+    } else if (!fullResponse && !responseDiv) {
+      // Check if WS sync stream has the content (fallback)
+      const active = window.UplinkConnection?.findActiveSyncStream?.();
+      if (active) {
+        const adopted = window.UplinkConnection?.adoptSyncStream?.(active.requestId);
+        if (adopted?.fullResponse) {
+          if (window.UplinkChat?.finalizeSyncStream) {
+            window.UplinkChat.finalizeSyncStream(adopted.div, adopted.fullResponse);
+          }
+          if (window.UplinkStorage) {
+            window.UplinkStorage.saveMessage({ text: adopted.fullResponse, type: 'assistant' });
+          }
+        } else {
+          addMessage('No response received', 'system', null, false);
+        }
+      } else {
+        addMessage('No response received', 'system', null, false);
+      }
+    }
+
+  } catch (err) {
+    handleFetchError(err);
+  }
+
+  currentAbortController = null;
+  if (core) core.chatState = 'idle';
+  processQueue();
+}
+
+// ============================================
+// FILE UPLOAD DELEGATES
+// Delegate to shared UplinkFileHandler module
+// ============================================
+
+/** Chat interface object passed to UplinkFileHandler */
+function getChatInterface() {
+  return {
+    addMessage,
+    showTyping,
+    hideTyping,
+    playAudio,
+    updateLastUserImageUrl: (serverUrl) => {
+      window.UplinkFileHandler?.updateLastUserImageUrl(messagesEl, serverUrl);
+    }
+  };
+}
+
+// Send image message — delegates to UplinkFileHandler
+async function sendImageMessage(imageUrl, caption = '', skipAddMessage = false) {
+  const core = window.UplinkCore;
+  if (core) core.chatState = 'processing';
+
+  try {
+    await window.UplinkFileHandler.sendImageMessage(
+      imageUrl, caption, getChatInterface(), skipAddMessage, IMAGE_TYPING_TIMEOUT_MS
+    );
+  } catch (err) {
+    hideTyping();
+    const friendlyMsg = window.UplinkErrors?.getFriendlyMessage(err) || 'Upload failed';
+    addMessage(friendlyMsg, 'system', null, false);
+  }
+
+  if (core) core.chatState = 'idle';
+  processQueue();
+}
+
+// Send file message — delegates to UplinkFileHandler
+async function sendFileMessage(fileInfo, caption = '') {
+  const core = window.UplinkCore;
+  if (core) core.chatState = 'processing';
+
+  try {
+    await window.UplinkFileHandler.sendFileMessage(
+      fileInfo, caption, getChatInterface(), IMAGE_TYPING_TIMEOUT_MS
+    );
+  } catch (err) {
+    hideTyping();
+    const friendlyMsg = window.UplinkErrors?.getFriendlyMessage(err) || 'File upload failed';
+    addMessage(friendlyMsg, 'system', null, false);
+  }
+
+  if (core) core.chatState = 'idle';
+  processQueue();
+}
+
+// Process queued messages (with mutex to prevent race conditions)
+let processingQueue = false;
+async function processQueue() {
+  if (processingQueue) return;  // Prevent concurrent processing
+  if (messageQueue.length === 0) return;
+  
+  const core = window.UplinkCore;
+  if (core && core.chatState !== 'idle') return;
+
+  processingQueue = true;
+  try {
+    const next = messageQueue.shift();
+    // Pass skipAddMessage=true since message was already shown when queued
+    if (next.imageUrl) {
+      await sendImageMessage(next.imageUrl, next.text, true);
+    } else {
+      await sendTextMessage(next.text, true);
+    }
+  } finally {
+    processingQueue = false;
+    // Process remaining items
+    if (messageQueue.length > 0) {
+      setTimeout(processQueue, 100);
+    }
+  }
+}
+
+// Add message to display
+// Delegates DOM creation to shared UplinkMessageRenderer, then applies
+// chat-specific behaviors (empty state, scroll-to-bottom button, storage, hooks).
+function addMessage(text, type, imageUrl = null, save = true, timestamp = null) {
+  if (!messagesEl) return;
+  
+  if (emptyStateEl) emptyStateEl.style.display = 'none';
+
+  // Delegate to shared renderer for div creation, avatar, image, text, scroll, auto-dismiss
+  const div = window.UplinkMessageRenderer?.addMessageToContainer({
+    container: messagesEl,
+    text,
+    type,
+    imageUrl,
+    showAvatar: type === 'assistant',
+    timestamp,
+    scroll: {
+      isNearBottom,
+      onNewMessage: () => {
+        // User has scrolled up and a real message arrived — show button
+        if (!scrollToBottomBtn) {
+          hasUnreadMessages = true;
+          showScrollToBottomBtn();
+        }
+      }
+    }
+  });
+
+  if (!div) return;
+
+  // Save to storage
+  if (save && type !== 'system' && window.UplinkStorage) {
+    window.UplinkStorage.saveMessage({ text, type, imageUrl });
+  }
+
+  // Mark message as seen for sync deduplication (prevents WebSocket echo duplicates)
+  if (text && window.UplinkConnection?.markMessageSeen) {
+    const role = type === 'user' ? 'user' : 'assistant';
+    window.UplinkConnection.markMessageSeen(null, role, text, Date.now());
+  }
+
+  // Invoke message hooks (for satellites, notifications, etc.)
+  // This replaces the need for other modules to patch addMessage
+  for (const hook of messageHooks) {
+    try {
+      hook({ text, type, imageUrl, save });
+    } catch (e) {
+      logger.error('Chat: Message hook error', e);
+    }
+  }
+  
+  // Emit event bus event for cross-module communication
+  emitEvent('message:added', { text, type, imageUrl, save, timestamp });
+  
+  return div;
+}
+
+// updateLastUserImageUrl now lives in file-handler.js (UplinkFileHandler)
+
+/**
+ * Register a hook to be called when messages are added
+ * Replaces the old pattern of patching window.addMessage
+ * @param {Function} hook - Function receiving { text, type, imageUrl, save }
+ * @returns {Function} Unsubscribe function
+ */
+function onMessage(hook) {
+  if (typeof hook !== 'function') return () => {};
+  messageHooks.push(hook);
+  return () => {
+    const idx = messageHooks.indexOf(hook);
+    if (idx >= 0) messageHooks.splice(idx, 1);
+  };
+}
+
+// Create screen reader announcement region
+function createSRAnnouncementRegion() {
+  if (document.getElementById('sr-announcements')) return;
+  
+  const region = document.createElement('div');
+  region.id = 'sr-announcements';
+  region.setAttribute('role', 'status');
+  region.setAttribute('aria-live', 'polite');
+  region.setAttribute('aria-atomic', 'true');
+  // Visually hidden but accessible to screen readers
+  region.style.cssText = 'position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;';
+  document.body.appendChild(region);
+}
+
+// Announce message to screen readers
+function announceToSR(message) {
+  const region = document.getElementById('sr-announcements');
+  if (region) {
+    // Clear and set to trigger announcement
+    region.textContent = '';
+    // Use setTimeout to ensure the change is detected
+    setTimeout(() => {
+      region.textContent = message;
+    }, 50);
+  }
+}
+
+// ============================================
+// SHARED MODULE DELEGATES
+// Delegate to UplinkMessageRenderer for avatars, formatting, etc.
+// ============================================
+
+function buildAgentAvatar(agentId) {
+  return window.UplinkMessageRenderer?.buildAgentAvatar(agentId) || null;
+}
+
+function formatMessage(text) {
+  return window.UplinkMessageRenderer?.formatMessage(text) || text || '';
+}
+
+// Show typing indicator with timeout protection
+function showTyping(timeoutMs = TYPING_TIMEOUT_MS) {
+  if (typingEl) return;
+  
+  typingEl = document.createElement('div');
+  typingEl.className = 'typing';
+  typingEl.id = 'typing';
+  typingEl.setAttribute('role', 'status');
+  typingEl.setAttribute('aria-label', 'Assistant is typing');
+  typingEl.innerHTML = '<span></span><span></span><span></span>';
+  messagesEl?.appendChild(typingEl);
+  if (messagesEl && isNearBottom) messagesEl.scrollTop = messagesEl.scrollHeight;
+
+  // Announce to screen readers
+  const announcer = document.getElementById('sr-announcer');
+  if (announcer) announcer.textContent = 'Assistant is typing';
+  
+  // Set timeout to auto-hide typing indicator if server hangs
+  clearTypingTimeout();
+  typingTimeoutId = setTimeout(() => {
+    const timeoutSec = Math.round(timeoutMs / 1000);
+    logger.warn(`Chat: Typing indicator timed out after ${timeoutSec}s`);
+    hideTyping();
+    addMessage('Response timed out. The server may be busy.', 'system', null, false);
+  }, timeoutMs);
+}
+
+// Clear typing timeout
+function clearTypingTimeout() {
+  if (typingTimeoutId) {
+    clearTimeout(typingTimeoutId);
+    typingTimeoutId = null;
+  }
+}
+
+// Hide typing indicator
+function hideTyping() {
+  clearTypingTimeout();
+  
+  // Always try to remove by ID first (catches orphaned elements)
+  const typingById = document.getElementById('typing');
+  if (typingById) typingById.remove();
+  
+  // Then clear reference (might be different element)
+  if (typingEl) {
+    if (typingEl.parentNode) typingEl.remove();
+    typingEl = null;
+  }
+  
+  // Nuclear option: remove ALL .typing elements
+  document.querySelectorAll('.typing').forEach(el => el.remove());
+
+  // Clear screen reader announcement
+  const announcer = document.getElementById('sr-announcer');
+  if (announcer) announcer.textContent = '';
+}
+
+// Show stop generation button
+function showStopButton() {
+  if (stopBtn) return;
+  
+  stopBtn = document.createElement('button');
+  stopBtn.className = 'stop-generation-btn';
+  stopBtn.innerHTML = '⬛ Stop';
+  stopBtn.title = 'Stop generation';
+  stopBtn.setAttribute('aria-label', 'Stop generation');
+  stopBtn.onclick = stopGeneration;
+  
+  // Insert before the input area
+  const inputArea = document.querySelector('.chat-input');
+  if (inputArea) {
+    inputArea.insertAdjacentElement('beforebegin', stopBtn);
+  }
+}
+
+// Hide stop generation button
+function hideStopButton() {
+  if (stopBtn) {
+    stopBtn.remove();
+    stopBtn = null;
+  }
+}
+
+// Stop the current generation
+function stopGeneration() {
+  if (currentAbortController) {
+    currentAbortController.abort();
+  }
+  clearAudioQueue();
+  hideStopButton();
+  // Reset send button to normal state
+  setSendingState(false);
+}
+
+// ============================================
+// AUDIO DELEGATES
+// Delegate to shared UplinkAudioQueue module
+// ============================================
+
+function playAudio(url) {
+  if (window.UplinkAudioQueue) {
+    window.UplinkAudioQueue.playAudio(url);
+  }
+}
+
+function clearAudioQueue() {
+  if (window.UplinkAudioQueue) {
+    window.UplinkAudioQueue.clearQueue();
+  }
+}
+
+// Audio queue functions now live in audio-queue.js (UplinkAudioQueue)
+// playAudio() and clearAudioQueue() above are thin delegates
+
+// Cleanup function
+function destroy() {
+  if (eventsAbortController) {
+    eventsAbortController.abort();
+    eventsAbortController = null;
+  }
+  if (currentAbortController) {
+    currentAbortController.abort();
+    currentAbortController = null;
+  }
+  clearAudioQueue();
+  messageQueue.length = 0;
+  // Note: We don't clear offlineQueue on destroy - it persists for reconnection
+}
+
+/**
+ * Finalize a sync-streamed message bubble with the full content
+ * Does NOT save to storage or fire hooks (sync messages use save=false)
+ * @param {HTMLDivElement} div - The streaming message container
+ * @param {string} fullContent - Complete response text
+ */
+function finalizeSyncStream(div, fullContent) {
+  if (!div) return;
+
+  // Guard against double-finalization: if already finalized, skip re-render
+  if (!div.classList.contains('streaming')) return;
+
+  // Clean up streaming render timer via shared handler
+  getStreamHandler().clearStreamRenderTimer();
+
+  div.classList.remove('streaming');
+  div.dataset.originalText = fullContent;
+  const textSpan = div.querySelector('.message-text');
+  if (textSpan && fullContent) {
+    textSpan.innerHTML = formatMessage(fullContent);
+  }
+  if (fullContent && window.UplinkConnection?.markMessageSeen) {
+    window.UplinkConnection.markMessageSeen(null, 'assistant', fullContent, Date.now());
+  }
+  if (messagesEl && isNearBottom) {
+    messagesEl.scrollTop = messagesEl.scrollHeight;
+  }
+}
+
+// Export API
+export const UplinkChat = {
+addMessage,
+formatMessage,
+showTyping,
+hideTyping,
+sendTextMessage,
+sendImageMessage,
+sendFileMessage,
+stopGeneration,
+playAudio,
+clearAudioQueue,
+createStreamingMessage: createStreamingMessageDiv,
+updateStreamingMessage: updateStreamingContent,
+finalizeSyncStream,
+clearMessages: () => {
+  if (messagesEl) messagesEl.innerHTML = '';
+  if (emptyStateEl) {
+    emptyStateEl.style.display = 'flex';
+    messagesEl?.appendChild(emptyStateEl);
+  }
+},
+destroy,
+// Offline queue management (delegates to UplinkOfflineQueue)
+getOfflineQueueLength: () => UplinkOfflineQueue.getLength?.() || 0,
+processOfflineQueue: () => UplinkOfflineQueue.processQueue?.(),
+clearOfflineQueue: () => UplinkOfflineQueue.clear?.(),
+// Message hook system - replaces patching window.addMessage
+onMessage,
+loadHistory
+};
+
+// Backward compat: assign to window
+window.UplinkChat = UplinkChat;
+
+// DEPRECATED: Legacy globals for backward compatibility
+window.addMessage = addMessage;
+window.formatMessage = formatMessage;
+
+// Helper for init retry with exponential backoff
+function scheduleInitRetry() {
+if (initRetryCount >= MAX_INIT_RETRIES) {
+  UplinkLogger.warn('Chat: Max init retries reached, giving up');
+  return;
+}
+initRetryCount++;
+const delay = Math.min(50 * Math.pow(2, initRetryCount), 5000);
+setTimeout(init, delay);
+}
+
+// Register and init
+UplinkCore.registerModule('chat', init);