Improve deployment safety and chat reliability

frontend/js/admin.js

@@ -6,6 +6,16 @@ document.addEventListener('DOMContentLoaded', () => {
     const user = getUser();
     document.getElementById('admin-name').textContent = user?.username || 'Admin';
 
+    /** Escape text destined for innerHTML or an HTML attribute. */
+    function escapeHtml(value) {
+        return String(value ?? '').replace(/[&<>"']/g, c => ({
+            '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+        }[c]));
+    }
+
+    // id → username, so instructions can show who they belong to
+    let usersById = new Map();
+
     // Tab switching
     const tabs = document.querySelectorAll('.tab');
     const panels = document.querySelectorAll('.tab-panel');
@@ -16,6 +26,11 @@ document.addEventListener('DOMContentLoaded', () => {
             panels.forEach(p => p.classList.add('hidden'));
             tab.classList.add('active');
             document.getElementById(tab.dataset.panel).classList.remove('hidden');
+
+            // Clicking the tab itself clears any per-client filter set via 📝
+            if (tab.dataset.panel === 'instructions-panel' && currentFilterUserId !== null) {
+                clearInstructionFilter();
+            }
         });
     });
 
@@ -28,6 +43,7 @@ document.addEventListener('DOMContentLoaded', () => {
     async function loadUsers() {
         try {
             const users = await apiJSON('/users/');
+            usersById = new Map(users.map(u => [u.id, u.username]));
             usersBody.innerHTML = '';
 
             if (users.length === 0) {
@@ -38,13 +54,14 @@ document.addEventListener('DOMContentLoaded', () => {
             users.forEach(u => {
                 const row = document.createElement('tr');
                 row.innerHTML = `
-          <td>${u.username}</td>
-          <td class="hide-mobile">${u.email}</td>
+          <td>${escapeHtml(u.username)}</td>
+          <td class="hide-mobile">${escapeHtml(u.email)}</td>
           <td><span class="badge ${u.is_active ? 'badge-personal' : 'badge-homework'}">${u.is_active ? 'Active' : 'Inactive'}</span></td>
           <td class="hide-mobile">${new Date(u.created_at).toLocaleDateString()}</td>
           <td>
             <button class="btn btn-sm btn-secondary" onclick="editUser(${u.id})">Edit</button>
-            <button class="btn btn-sm btn-secondary" onclick="manageInstructions(${u.id}, '${u.username}')">📝</button>
+            <button class="btn btn-sm btn-secondary" data-username="${escapeHtml(u.username)}"
+              onclick="manageInstructions(${u.id}, this.dataset.username)">📝</button>
             <button class="btn btn-sm btn-danger" onclick="deleteUser(${u.id})">✕</button>
           </td>
         `;
@@ -120,7 +137,7 @@ document.addEventListener('DOMContentLoaded', () => {
     window.deleteUser = async (id) => {
         if (!confirm('Delete this client? This will also remove all their instructions.')) return;
         try {
-            await api(`/users/${id}`, { method: 'DELETE' });
+            await apiVoid(`/users/${id}`, { method: 'DELETE' });
             showToast('Client deleted');
             loadUsers();
         } catch (e) {
@@ -150,10 +167,10 @@ document.addEventListener('DOMContentLoaded', () => {
             instructions.forEach(inst => {
                 const row = document.createElement('tr');
                 row.innerHTML = `
-          <td>${inst.title}</td>
+          <td>${escapeHtml(inst.title)}</td>
           <td><span class="badge badge-${inst.type}">${inst.type}</span></td>
-          <td class="hide-mobile">${inst.user_id || 'Global'}</td>
-          <td class="hide-mobile">${inst.content.substring(0, 60)}${inst.content.length > 60 ? '...' : ''}</td>
+          <td class="hide-mobile">${inst.user_id ? escapeHtml(usersById.get(inst.user_id) || `#${inst.user_id}`) : 'Global'}</td>
+          <td class="hide-mobile">${escapeHtml(inst.content.substring(0, 60))}${inst.content.length > 60 ? '...' : ''}</td>
           <td>
             <button class="btn btn-sm btn-secondary" onclick="editInstruction(${inst.id})">Edit</button>
             <button class="btn btn-sm btn-danger" onclick="deleteInstruction(${inst.id})">✕</button>
@@ -171,21 +188,39 @@ document.addEventListener('DOMContentLoaded', () => {
             const users = await apiJSON('/users/');
             instrUserSelect.innerHTML = '<option value="">Global (all clients)</option>';
             users.forEach(u => {
-                instrUserSelect.innerHTML += `<option value="${u.id}">${u.username}</option>`;
+                instrUserSelect.innerHTML += `<option value="${u.id}">${escapeHtml(u.username)}</option>`;
             });
         } catch (e) {
             // silently fail
         }
     }
 
-    window.manageInstructions = (userId, username) => {
+    function applyInstructionFilter(userId, username) {
         currentFilterUserId = userId;
+
+        const heading = document.getElementById('instructions-heading');
+        const clearBtn = document.getElementById('instr-filter-clear');
+
+        if (userId === null) {
+            heading.textContent = 'Instructions';
+            clearBtn.classList.add('hidden');
+        } else {
+            heading.textContent = `Instructions — ${username}`;
+            clearBtn.classList.remove('hidden');
+        }
+
+        loadInstructions(userId);
+    }
+
+    window.clearInstructionFilter = () => applyInstructionFilter(null, null);
+
+    window.manageInstructions = (userId, username) => {
         // Switch to instructions tab
         tabs.forEach(t => t.classList.remove('active'));
         panels.forEach(p => p.classList.add('hidden'));
         document.querySelector('[data-panel="instructions-panel"]').classList.add('active');
         document.getElementById('instructions-panel').classList.remove('hidden');
-        loadInstructions(userId);
+        applyInstructionFilter(userId, username);
     };
 
     window.showInstructionModal = () => {
@@ -253,7 +288,7 @@ document.addEventListener('DOMContentLoaded', () => {
     window.deleteInstruction = async (id) => {
         if (!confirm('Delete this instruction?')) return;
         try {
-            await api(`/instructions/${id}`, { method: 'DELETE' });
+            await apiVoid(`/instructions/${id}`, { method: 'DELETE' });
             showToast('Instruction deleted');
             loadInstructions(currentFilterUserId);
         } catch (e) {
@@ -271,9 +306,11 @@ document.addEventListener('DOMContentLoaded', () => {
             if (!file) return;
 
             const text = await file.text();
+            // Open the modal first: showInstructionModal() calls form.reset(),
+            // which would wipe anything prefilled before it.
+            showInstructionModal();
             document.getElementById('instr-title').value = file.name.replace(/\.[^.]+$/, '');
             document.getElementById('instr-content').value = text;
-            showInstructionModal();
         };
         input.click();
     };
@@ -328,14 +365,14 @@ document.addEventListener('DOMContentLoaded', () => {
         const content = voiceGenText.value.trim();
         if (!content) return;
 
-        loadUserOptions();
+        // Open the modal first: showInstructionModal() calls form.reset() and
+        // loadUserOptions() itself, and would wipe anything prefilled before it.
+        showInstructionModal();
         document.getElementById('instr-content').value = content;
         document.getElementById('instr-title').value = 'Voice Generated Instruction';
-        showInstructionModal();
     };
 
     // ── Init ───────────────────────────────────────────────────────
-    loadUsers();
-    loadInstructions();
+    loadUsers().then(() => loadInstructions());
     document.getElementById('logout-btn').addEventListener('click', logout);
 });

frontend/js/api.js

@@ -52,15 +52,27 @@ async function api(path, options = {}) {
     return response;
 }
 
-async function apiJSON(path, options = {}) {
-    const response = await api(path, options);
-    if (!response || !response.ok) {
-        const error = await response?.json().catch(() => ({ detail: 'Request failed' }));
-        throw new Error(error.detail || 'Request failed');
+async function ensureOk(response) {
+    // api() returns undefined after a 401 — the redirect is already under way
+    if (!response) throw new Error('Session expired');
+
+    if (!response.ok) {
+        const error = await response.json().catch(() => null);
+        throw new Error(error?.detail || 'Request failed');
     }
+    return response;
+}
+
+async function apiJSON(path, options = {}) {
+    const response = await ensureOk(await api(path, options));
     return response.json();
 }
 
+/* Same, for endpoints that answer 204 No Content (the deletes). */
+async function apiVoid(path, options = {}) {
+    await ensureOk(await api(path, options));
+}
+
 function requireAuth() {
     if (!getToken()) {
         window.location.href = '/';
@@ -81,6 +93,8 @@ function requireAdmin() {
 function logout() {
     clearToken();
     clearUser();
+    // Drop the saved conversation as well — shared devices are the norm here
+    try { sessionStorage.clear(); } catch (e) { /* storage may be blocked */ }
     window.location.href = '/';
 }
 

frontend/js/chat.js

@@ -58,6 +58,15 @@ document.addEventListener('DOMContentLoaded', async () => {
 
     let history = [];
     let voiceModeOn = false;
+    let sending = false;
+    let abortController = null;
+    // Bumped by "New chat" — a send started before the bump must not write
+    // its late results into the conversation that replaced it.
+    let chatGeneration = 0;
+
+    // Conversations survive a reload but not a closed tab, and are scoped to
+    // the logged-in user so a shared device never shows someone else's lesson.
+    const CHAT_KEY = `fg_chat_${user?.id ?? 'anon'}`;
 
     // ── Personalised welcome ──────────────────────────────────────────
     const greetingEl = document.getElementById('welcome-greeting');
@@ -156,14 +165,123 @@ document.addEventListener('DOMContentLoaded', async () => {
         return div;
     }
 
+    /**
+     * Read an SSE stream to completion, calling onToken for every token.
+     *
+     * Buffers across reads: a chunk boundary can fall anywhere, splitting a
+     * multi-byte character (ä, ö, ü, ß) or a whole event across two reads.
+     */
+    function saveHistory() {
+        try {
+            sessionStorage.setItem(CHAT_KEY, JSON.stringify(history.slice(-40)));
+        } catch (e) {
+            console.warn('[Chat] Could not save conversation:', e);
+        }
+    }
+
+    function restoreHistory() {
+        let saved = [];
+        try {
+            saved = JSON.parse(sessionStorage.getItem(CHAT_KEY) || '[]');
+        } catch (e) {
+            return;
+        }
+        if (!Array.isArray(saved) || saved.length === 0) return;
+
+        history = saved;
+        for (const msg of saved) {
+            if (msg?.role && typeof msg.content === 'string') {
+                appendMessage(msg.role, msg.content);
+            }
+        }
+    }
+
+    function startNewChat() {
+        chatGeneration++;
+        abortController?.abort();
+        voice.stopPlayback();
+        abortController = null;
+        setSending(false);
+        history = [];
+        try {
+            sessionStorage.removeItem(CHAT_KEY);
+        } catch (e) {
+            /* storage may be blocked */
+        }
+        messagesEl.querySelectorAll('.message').forEach(el => el.remove());
+        inputEl.focus();
+    }
+
+    /** Toggle the composer between "Send" and "Stop". */
+    function setSending(on) {
+        sending = on;
+        sendBtn.textContent = on ? 'Stop' : 'Send';
+        sendBtn.classList.toggle('btn-danger', on);
+        sendBtn.classList.toggle('btn-primary', !on);
+    }
+
+    async function readSSE(response, onToken) {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let finished = false;
+
+        const handleEvent = (event) => {
+            for (const line of event.split('\n')) {
+                if (!line.startsWith('data: ')) continue;
+                const data = line.slice(6).trim();
+                if (data === '[DONE]') {
+                    finished = true;
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(data);
+                    if (parsed.token) onToken(parsed.token);
+                    if (parsed.error) showToast(parsed.error, 'error');
+                } catch (err) {
+                    console.warn('[Chat] Unparseable SSE data:', data);
+                }
+            }
+        };
+
+        while (!finished) {
+            const { done, value } = await reader.read();
+
+            if (done) {
+                buffer += decoder.decode();  // flush any pending bytes
+                if (buffer.trim()) handleEvent(buffer);
+                break;
+            }
+
+            buffer += decoder.decode(value, { stream: true });
+
+            // Events are separated by a blank line — keep the trailing fragment.
+            const events = buffer.split('\n\n');
+            buffer = events.pop();
+
+            for (const event of events) {
+                handleEvent(event);
+                if (finished) break;
+            }
+        }
+
+        try { await reader.cancel(); } catch (err) { /* already closed */ }
+    }
+
     async function sendMessage() {
+        if (sending) return;
+
         const text = inputEl.value.trim();
         if (!text) return;
 
+        setSending(true);
+        const controller = new AbortController();
+        abortController = controller;
+        const generation = chatGeneration;
+        const isCurrent = () => generation === chatGeneration;
         voice.lastInputWasVoice = false;
 
         inputEl.value = '';
-        sendBtn.disabled = true;
 
         appendMessage('user', text);
         history.push({ role: 'user', content: text });
@@ -175,6 +293,7 @@ document.addEventListener('DOMContentLoaded', async () => {
             const response = await api('/chat/', {
                 method: 'POST',
                 body: JSON.stringify({ message: text, history: history.slice(-20) }),
+                signal: controller.signal,
             });
 
             if (!response?.ok) {
@@ -182,94 +301,96 @@ document.addEventListener('DOMContentLoaded', async () => {
                 throw new Error(errData.detail || `Chat failed (${response?.status})`);
             }
 
-            const reader = response.body.getReader();
-            const decoder = new TextDecoder();
-
-            // Special handling for Voice Mode: Buffer text, wait for TTS, then show & play
             if (voiceModeOn) {
-                // "Thinking..." is already shown from appendMessage above
+                // Buffer the whole reply, fetch its audio, then reveal text and
+                // player together — "Thinking..." stays up until audio is ready.
+                await readSSE(response, (token) => {
+                    fullResponse += token;
+                });
 
-                while (true) {
-                    const { done, value } = await reader.read();
-                    if (done) break;
-                    const chunk = decoder.decode(value);
-                    const lines = chunk.split('\n');
-                    for (const line of lines) {
-                        if (line.startsWith('data: ')) {
-                            const data = line.slice(6).trim();
-                            if (data === '[DONE]') break;
-                            try {
-                                const parsed = JSON.parse(data);
-                                if (parsed.token) fullResponse += parsed.token;
-                                if (parsed.error) showToast(parsed.error, 'error');
-                            } catch (e) { }
-                        }
-                    }
-                }
+                if (!isCurrent()) return;
+                assistantEl.classList.remove('message-thinking');
 
-                // Text complete. Now fetch audio.
                 if (fullResponse) {
                     history.push({ role: 'assistant', content: fullResponse });
+                    saveHistory();
 
-                    // Keep "Thinking..." until audio is ready or failed
-                    const audioUrl = await voice.fetchAudio(fullResponse);
+                    // Same signal as the chat request, so Stop cancels TTS too
+                    const audioUrl = await voice.fetchAudio(fullResponse, controller.signal);
+                    if (!isCurrent()) return;
 
-                    // Visual update: Remove thinking, show text
-                    assistantEl.classList.remove('message-thinking');
+                    // The reply itself is complete — show it even when Stop
+                    // cancelled the audio
                     assistantEl.innerHTML = renderMarkdown(fullResponse);
                     messagesEl.scrollTop = messagesEl.scrollHeight;
 
-                    if (audioUrl) {
+                    if (audioUrl && !controller.signal.aborted) {
+                        // Re-enable sending before playback: playAudio() only
+                        // settles on ended/error, so a paused player would
+                        // otherwise keep chat locked until a reload.
+                        setSending(false);
                         await voice.playAudio(audioUrl, assistantEl);
                     }
+                } else {
+                    assistantEl.textContent = 'No response received. Please try again.';
                 }
-
             } else {
-                // Normal Text Mode: Stream directly to UI
-                while (true) {
-                    const { done, value } = await reader.read();
-                    if (done) break;
+                // Text mode: stream straight into the bubble
+                await readSSE(response, (token) => {
+                    fullResponse += token;
+                    assistantEl.innerHTML = renderMarkdown(fullResponse);
+                    messagesEl.scrollTop = messagesEl.scrollHeight;
+                });
 
-                    const chunk = decoder.decode(value);
-                    const lines = chunk.split('\n');
-
-                    for (const line of lines) {
-                        if (line.startsWith('data: ')) {
-                            const data = line.slice(6).trim();
-                            if (data === '[DONE]') break;
-
-                            try {
-                                const parsed = JSON.parse(data);
-                                if (parsed.token) {
-                                    fullResponse += parsed.token;
-                                    assistantEl.innerHTML = renderMarkdown(fullResponse);
-                                    messagesEl.scrollTop = messagesEl.scrollHeight;
-                                }
-                                if (parsed.error) {
-                                    showToast(parsed.error, 'error');
-                                }
-                            } catch (e) {
-                                // skip unparseable chunks
-                            }
-                        }
-                    }
-                }
+                if (!isCurrent()) return;
 
                 if (fullResponse) {
                     history.push({ role: 'assistant', content: fullResponse });
+                    saveHistory();
+                } else {
+                    assistantEl.textContent = 'No response received. Please try again.';
                 }
             }
         } catch (e) {
-            assistantEl.textContent = 'Sorry, something went wrong. Please try again.';
-            showToast(e.message, 'error');
-            console.error('[Chat] Error:', e);
+            if (e.name === 'AbortError') {
+                // Aborted by "New chat": that conversation is gone, discard this
+                if (!isCurrent()) {
+                    assistantEl.remove();
+                    return;
+                }
+                // User pressed Stop — keep the partial reply, drop an empty one
+                assistantEl.classList.remove('message-thinking');
+                if (fullResponse) {
+                    assistantEl.innerHTML = renderMarkdown(fullResponse);
+                    history.push({ role: 'assistant', content: fullResponse });
+                    saveHistory();
+                } else {
+                    assistantEl.remove();
+                }
+            } else {
+                assistantEl.textContent = 'Sorry, something went wrong. Please try again.';
+                showToast(e.message, 'error');
+                console.error('[Chat] Error:', e);
+            }
+        } finally {
+            // In voice mode this runs after playback, by which time a newer
+            // send may already own the composer — don't clobber its state.
+            if (abortController === controller) {
+                abortController = null;
+                setSending(false);
+            }
+            if (isCurrent()) saveHistory();
+            inputEl.focus();
         }
-
-        sendBtn.disabled = false;
-        inputEl.focus();
     }
 
-    sendBtn.addEventListener('click', sendMessage);
+    sendBtn.addEventListener('click', () => {
+        if (sending) {
+            abortController?.abort();
+            return;
+        }
+        sendMessage();
+    });
     inputEl.addEventListener('keydown', (e) => {
         if (e.key === 'Enter' && !e.shiftKey) {
             e.preventDefault();
@@ -277,6 +398,11 @@ document.addEventListener('DOMContentLoaded', async () => {
         }
     });
 
+    document.getElementById('new-chat-btn')?.addEventListener('click', startNewChat);
+
     // Logout
     document.getElementById('logout-btn').addEventListener('click', logout);
+
+    // Bring back this session's conversation, if there is one
+    restoreHistory();
 });

frontend/js/voice.js

@@ -14,6 +14,9 @@ class VoiceManager {
         this.browserSTTSupported = false;
         this.apiAvailable = false;
         this.onProcessing = null; // New callback for "Transcribing..." state
+        this.currentAudio = null;      // clip currently playing, if any
+        this._resolvePlayback = null;  // settles whoever awaits playAudio()
+        this._resetPlayerUI = null;    // puts that clip's player back to rest
     }
 
     async init() {
@@ -98,10 +101,18 @@ class VoiceManager {
         // if hardware access fails or takes time.
 
         if (this.mode === 'api') {
+            if (typeof MediaRecorder === 'undefined') {
+                showToast('This browser cannot record audio.', 'error');
+                return;
+            }
+
             try {
                 const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
                 this.audioChunks = [];
-                this.mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });
+
+                // Safari/iOS has no webm — let it fall through to mp4
+                const mimeType = VoiceManager.pickMimeType();
+                this.mediaRecorder = new MediaRecorder(stream, mimeType ? { mimeType } : undefined);
 
                 this.mediaRecorder.ondataavailable = (e) => {
                     if (e.data.size > 0) this.audioChunks.push(e.data);
@@ -109,7 +120,11 @@ class VoiceManager {
 
                 this.mediaRecorder.onstop = async () => {
                     stream.getTracks().forEach(t => t.stop());
-                    const blob = new Blob(this.audioChunks, { type: 'audio/webm' });
+                    // Use what the recorder produced, not what we asked for.
+                    // A few old WebViews report an empty mimeType even though
+                    // they recorded something else — webm is the best guess left.
+                    const type = this.mediaRecorder.mimeType || mimeType || 'audio/webm';
+                    const blob = new Blob(this.audioChunks, { type });
                     await this._transcribeAPI(blob);
                 };
 
@@ -124,7 +139,12 @@ class VoiceManager {
 
             } catch (e) {
                 console.error('[Voice] Mic access error:', e);
-                showToast('Microphone access denied or error', 'error');
+                showToast(
+                    e.name === 'NotAllowedError'
+                        ? 'Microphone access denied. Allow it in browser settings.'
+                        : `Could not start recording: ${e.message || e.name}`,
+                    'error'
+                );
                 this.isRecording = false;
                 if (this.onStateChange) this.onStateChange(false);
             }
@@ -175,7 +195,9 @@ class VoiceManager {
 
         try {
             const formData = new FormData();
-            formData.append('audio', blob, 'recording.webm');
+            // The OpenAI SDK infers the audio format from this filename, so it
+            // has to match what the recorder actually produced.
+            formData.append('audio', blob, `recording.${VoiceManager.extensionFor(blob.type)}`);
 
             const response = await api('/voice/transcribe', {
                 method: 'POST',
@@ -204,13 +226,15 @@ class VoiceManager {
      * Fetch TTS audio blob for text (API only).
      * Returns audio URL or null.
      */
-    async fetchAudio(text) {
+    async fetchAudio(text, signal) {
         if (!this.apiAvailable) return null;
 
         const clean = VoiceManager.stripMarkdown(text);
         try {
-            const response = await api(`/voice/synthesize?text=${encodeURIComponent(clean)}`, {
+            const response = await api('/voice/synthesize', {
                 method: 'POST',
+                body: JSON.stringify({ text: clean }),
+                signal,
             });
 
             if (response?.ok) {
@@ -235,7 +259,13 @@ class VoiceManager {
     async playAudio(audioUrl, containerEl) {
         if (!audioUrl) return;
 
+        this.stopPlayback();   // only one clip at a time
+
         const audio = new Audio(audioUrl);
+        this.currentAudio = audio;
+
+        // Settles on end, on error, or when stopPlayback() is called
+        const finished = new Promise(resolve => { this._resolvePlayback = resolve; });
 
         // Visual feedback — avatar pulse
         const avatarContainer = document.querySelector('.avatar-container');
@@ -268,6 +298,15 @@ class VoiceManager {
             containerEl.appendChild(player);
         }
 
+        // Lets stopPlayback() return this player to a resting state
+        const resetPlayerUI = () => {
+            playBtn.classList.remove('playing');
+            playBtn.innerHTML = VoiceManager._playIcon();
+            playBtn.title = 'Replay';
+            fill.style.width = '0%';
+        };
+        this._resetPlayerUI = resetPlayerUI;
+
         // ── Helpers ───────────────────────────────────────────────────
         function fmt(s) {
             if (!isFinite(s)) return '0:00';
@@ -301,6 +340,10 @@ class VoiceManager {
         // Play/pause toggle
         playBtn.addEventListener('click', () => {
             if (audio.paused) {
+                // Register the replay, otherwise stopPlayback() can't reach it
+                this.stopPlayback();
+                this.currentAudio = audio;
+                this._resetPlayerUI = resetPlayerUI;
                 audio.play();
                 playBtn.classList.add('playing');
                 playBtn.innerHTML = VoiceManager._pauseIcon();
@@ -308,6 +351,10 @@ class VoiceManager {
                 if (avatarContainer) avatarContainer.classList.add('speaking');
             } else {
                 audio.pause();
+                if (this.currentAudio === audio) {
+                    this.currentAudio = null;
+                    this._resetPlayerUI = null;
+                }
                 playBtn.classList.remove('playing');
                 playBtn.innerHTML = VoiceManager._playIcon();
                 playBtn.title = 'Play';
@@ -317,38 +364,78 @@ class VoiceManager {
 
         // ── Playback ──────────────────────────────────────────────────
         try {
-            // Wait for audio to be fully buffered before playing
-            await new Promise((resolve, reject) => {
-                audio.addEventListener('canplaythrough', resolve, { once: true });
-                audio.addEventListener('error', reject, { once: true });
-                audio.load(); // Explicitly trigger loading
-            });
+            // Wait for audio to be fully buffered before playing — but give up
+            // if stopPlayback() cuts in while it is still loading
+            await Promise.race([
+                new Promise((resolve, reject) => {
+                    audio.addEventListener('canplaythrough', resolve, { once: true });
+                    audio.addEventListener('error', reject, { once: true });
+                    audio.load(); // Explicitly trigger loading
+                }),
+                finished,
+            ]);
+
+            if (this.currentAudio !== audio) return;   // stopped while loading
+
             audio.currentTime = 0; // Ensure we start from the very beginning
             await audio.play();
-            return new Promise(resolve => {
-                audio.onended = () => {
-                    if (avatarContainer) avatarContainer.classList.remove('speaking');
-                    playBtn.classList.remove('playing');
-                    playBtn.innerHTML = VoiceManager._playIcon();
-                    playBtn.title = 'Replay';
-                    fill.style.width = '100%';
-                    // Reset to beginning for replay
-                    audio.currentTime = 0;
-                    resolve();
-                };
-                audio.onerror = () => {
-                    if (avatarContainer) avatarContainer.classList.remove('speaking');
-                    resolve();
-                };
-            });
+
+            audio.onended = () => {
+                if (avatarContainer) avatarContainer.classList.remove('speaking');
+                playBtn.classList.remove('playing');
+                playBtn.innerHTML = VoiceManager._playIcon();
+                playBtn.title = 'Replay';
+                fill.style.width = '100%';
+                // Reset to beginning for replay
+                audio.currentTime = 0;
+                this._settlePlayback();
+            };
+            audio.onerror = () => {
+                if (avatarContainer) avatarContainer.classList.remove('speaking');
+                this._settlePlayback();
+            };
+            return finished;
         } catch (e) {
             console.error('Playback failed', e);
             if (avatarContainer) avatarContainer.classList.remove('speaking');
             playBtn.classList.remove('playing');
             playBtn.innerHTML = VoiceManager._playIcon();
+            this._settlePlayback();
         }
     }
 
+    /**
+     * Stop whatever is playing right now. Without this the Audio object is
+     * unreachable once playAudio() returns, so removing the player from the
+     * DOM leaves a detached clip still talking.
+     */
+    stopPlayback() {
+        const audio = this.currentAudio;
+        if (audio) {
+            audio.pause();
+            try { audio.currentTime = 0; } catch (e) { /* not seekable yet */ }
+        }
+
+        // Leave onended attached so a later replay still resets its own player
+        const resetUI = this._resetPlayerUI;
+        this._resetPlayerUI = null;
+        if (resetUI) resetUI();
+
+        const avatarContainer = document.querySelector('.avatar-container');
+        if (avatarContainer) avatarContainer.classList.remove('speaking');
+
+        this._settlePlayback();
+    }
+
+    /** Release anyone awaiting playAudio() and forget the current clip. */
+    _settlePlayback() {
+        this.currentAudio = null;
+        this._resetPlayerUI = null;
+        const resolve = this._resolvePlayback;
+        this._resolvePlayback = null;
+        if (resolve) resolve();
+    }
+
     // ── SVG icons (inline, no external deps) ──────────────────────────
     static _playIcon() {
         return `<svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><polygon points="6,3 20,12 6,21"/></svg>`;
@@ -367,6 +454,31 @@ class VoiceManager {
         if (url) await this.playAudio(url);
     }
 
+    /**
+     * Pick a recording format this browser supports.
+     * Chrome/Edge/Firefox give webm; Safari and iOS only do mp4.
+     * Returns '' to let the browser choose its own default.
+     */
+    static pickMimeType() {
+        const candidates = [
+            'audio/webm;codecs=opus',
+            'audio/webm',
+            'audio/mp4',
+            'audio/ogg;codecs=opus',
+        ];
+
+        if (typeof MediaRecorder === 'undefined' || !MediaRecorder.isTypeSupported) return '';
+        return candidates.find(type => MediaRecorder.isTypeSupported(type)) || '';
+    }
+
+    /** File extension matching a recorded blob's MIME type. */
+    static extensionFor(mimeType = '') {
+        if (mimeType.includes('mp4')) return 'mp4';
+        if (mimeType.includes('mpeg')) return 'mp3';
+        if (mimeType.includes('ogg')) return 'ogg';
+        return 'webm';
+    }
+
     /**
      * Strip markdown formatting from text so TTS reads naturally.
      */