v1.0.16: TTS fix (AudioContext/iOS), typewriter animation, swipe handle, avatar glow, Quick Study chip, personalization

- Fix TTS on iOS Chrome: unlock shared AudioContext synchronously in user
  gesture (handleSpeak), then decode/play via decodeAudioData in Promise
  chain — avoids autoplay-policy rejection from HTMLAudioElement.play()
- Add typewriter animation: SSE tokens queued; 20ms interval reveals 5
  chars/tick with smooth scroll to keep new text visible
- Avatar pulse/glow on TTS instead of bounce: CSS @Keyframes aica-speaking-glow
  applied to toggle button via .aica-speaking class
- Restrict mobile swipe-to-close to dedicated .aica-swipe-handle bar above
  header — prevents accidental dismissal when scrolling content
- Add Quick Study starter chip: time picker (5/10/15/30 min) + topic selector
  (AI-guided default + course topics + custom); tracks sessions in localStorage
- Personalization: store last session topic; show 'Continue where you left off'
  suggestion on re-open; tracks quiz history for welcome-back context
- db/upgrade.php: add savepoint for 2026030700 (no schema changes)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: caswelltom

amd/build/chat.min.js

@@ -409,6 +409,14 @@ define([
 
     /** @type {HTMLElement|null} Current streaming message element */
     let streamingEl = null;
+    /** Typewriter: full text received from SSE (may be ahead of visual display) */
+    let typewriterFull = '';
+    /** Typewriter: number of characters currently displayed */
+    let typewriterPos = 0;
+    /** Typewriter: setInterval handle */
+    let typewriterTimer = null;
+    /** Characters revealed per 20ms tick (~200 chars/sec) */
+    const TYPEWRITER_SPEED = 5;
 
     /** @type {HTMLElement|null} Currently playing TTS message element */
     let speakingEl = null;
@@ -765,20 +773,23 @@ define([
      * Safe to call on desktop too — touch events simply never fire there.
      */
     const initMobileGestures = function() {
-        // ── Mobile: swipe-down on header to close ────────────────────────────────
+        // ── Mobile: swipe-down on swipe handle to close ──────────────────────────
+        // Restricted to the dedicated .aica-swipe-handle bar to avoid accidental
+        // dismissal when scrolling through messages or swiping on content.
         var swipeTouchStartY = 0;
         var swipeTouchStartX = 0;
-        if (drawer) {
-            drawer.addEventListener('touchstart', function(e) {
+        var swipeHandle = drawer ? drawer.querySelector('.aica-swipe-handle') : null;
+        if (swipeHandle) {
+            swipeHandle.addEventListener('touchstart', function(e) {
                 swipeTouchStartY = e.touches[0].clientY;
                 swipeTouchStartX = e.touches[0].clientX;
             }, {passive: true});
 
-            drawer.addEventListener('touchend', function(e) {
+            swipeHandle.addEventListener('touchend', function(e) {
                 var dy = e.changedTouches[0].clientY - swipeTouchStartY;
                 var dx = Math.abs(e.changedTouches[0].clientX - swipeTouchStartX);
-                // Swipe down ≥ 80px, more vertical than horizontal → close drawer.
-                if (dy > 80 && dx < dy * 0.8) {
+                // Swipe down ≥ 60px, more vertical than horizontal → close drawer.
+                if (dy > 60 && dx < dy * 0.8) {
                     closeDrawer();
                 }
             }, {passive: true});
@@ -1152,6 +1163,10 @@ define([
                 av.classList.toggle('aica-avatar-svg--speaking', !!on);
             });
         }
+        // Pulse-glow the toggle button itself (drives the CSS @keyframes aica-speaking-glow).
+        if (toggle) {
+            toggle.classList.toggle('aica-speaking', !!on);
+        }
     };
 
     /**
@@ -1166,21 +1181,74 @@ define([
     };
 
     /**
-     * Append a chunk to the current streaming message.
-     * Re-renders all accumulated text through markdown on each chunk.
+     * Scroll just enough to keep the bottom of the streaming content visible.
+     * Unlike scrollToBottom, this doesn't snap to the very end of the messages container.
+     */
+    const scrollToKeepStreamingVisible = function() {
+        if (!messagesContainer || !streamingEl) {
+            return;
+        }
+        const content = streamingEl.querySelector('.local-ai-course-assistant__message-content');
+        if (!content) {
+            return;
+        }
+        const cRect = messagesContainer.getBoundingClientRect();
+        const eRect = content.getBoundingClientRect();
+        if (eRect.bottom > cRect.bottom - 4) {
+            messagesContainer.scrollTop += (eRect.bottom - cRect.bottom) + 6;
+        }
+    };
+
+    /**
+     * Internal: advance the typewriter by TYPEWRITER_SPEED characters and re-render.
+     */
+    const tickTypewriter = function() {
+        if (!streamingEl) {
+            clearTypewriterTimer();
+            return;
+        }
+        const target = typewriterFull.length;
+        if (typewriterPos >= target) {
+            return; // Caught up — more tokens may still arrive
+        }
+        typewriterPos = Math.min(typewriterPos + TYPEWRITER_SPEED, target);
+        const partial = typewriterFull.substring(0, typewriterPos);
+        const content = streamingEl.querySelector('.local-ai-course-assistant__message-content');
+        if (content) {
+            content.innerHTML = Markdown.render(partial);
+            if (scrollFollowMode) {
+                messagesContainer.scrollTop = messagesContainer.scrollHeight;
+            } else {
+                scrollToKeepStreamingVisible();
+            }
+        }
+    };
+
+    /**
+     * Clear the typewriter timer and reset state.
+     */
+    const clearTypewriterTimer = function() {
+        if (typewriterTimer) {
+            clearInterval(typewriterTimer);
+            typewriterTimer = null;
+        }
+        typewriterFull = '';
+        typewriterPos = 0;
+    };
+
+    /**
+     * Append a chunk to the current streaming message using typewriter animation.
+     * Queues the new text; a timer reveals it character-by-character.
      *
      * @param {string} fullText The full accumulated text so far
      */
     const updateStreamContent = function(fullText) {
         if (!streamingEl) {
             return;
         }
-        const content = streamingEl.querySelector('.local-ai-course-assistant__message-content');
-        content.innerHTML = Markdown.render(fullText);
-        // In follow mode (user clicked the scroll-down arrow during streaming),
-        // keep the bottom of new content visible. Otherwise stay at message top.
-        if (scrollFollowMode) {
-            messagesContainer.scrollTop = messagesContainer.scrollHeight;
+        typewriterFull = fullText;
+        if (!typewriterTimer) {
+            typewriterTimer = setInterval(tickTypewriter, 20);
         }
     };
 
@@ -1191,6 +1259,8 @@ define([
      * @param {Function|null} onSpeak   Optional TTS callback; if provided, adds speak button
      */
     const finishStreaming = function(fullText, onSpeak) {
+        // Stop typewriter animation — final render below replaces it.
+        clearTypewriterTimer();
         if (streamingEl) {
             const completedEl = streamingEl;
             const content = streamingEl.querySelector('.local-ai-course-assistant__message-content');
@@ -2590,6 +2660,59 @@ define([
         }
     };
 
+    /**
+     * Start mouth sync from an already-created AnalyserNode (AudioContext TTS path).
+     * Used when the audio is played through a shared AudioContext (e.g. iOS TTS fix).
+     *
+     * @param {AnalyserNode} analyser  Pre-configured analyser connected to audio source
+     */
+    const startMouthSyncFromAnalyser = function(analyser) {
+        stopMouthSync();
+        if (!root || !analyser) {
+            return;
+        }
+        analyser.fftSize = 256;
+        analyser.smoothingTimeConstant = 0.55;
+        var data = new Uint8Array(analyser.frequencyBinCount);
+        var rafId = null;
+        var alive = true;
+
+        var resetMouth = function() {
+            if (!root) { return; }
+            root.querySelectorAll('.aica-mouth-open').forEach(function(el) {
+                el.style.transform = 'scaleY(0)';
+                el.style.opacity = '0';
+            });
+            root.querySelectorAll('.aica-mouth-smile').forEach(function(el) {
+                el.style.opacity = '';
+            });
+        };
+
+        mouthSyncCleanup = function() {
+            alive = false;
+            if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
+            mouthSyncCleanup = null;
+            resetMouth();
+        };
+
+        var update = function() {
+            if (!alive) { return; }
+            analyser.getByteFrequencyData(data);
+            var sum = 0;
+            for (var i = 2; i <= 20; i++) { sum += data[i]; }
+            var amp = Math.min(1, (sum / 19 / 90));
+            root.querySelectorAll('.aica-mouth-open').forEach(function(el) {
+                el.style.transform = 'scaleY(' + amp + ')';
+                el.style.opacity = amp > 0.08 ? '1' : '0';
+            });
+            root.querySelectorAll('.aica-mouth-smile').forEach(function(el) {
+                el.style.opacity = String(Math.max(0.05, 1 - amp * 1.3));
+            });
+            rafId = requestAnimationFrame(update);
+        };
+        update();
+    };
+
     /**
      * Stop Web Audio mouth sync and reset mouth to resting state.
      */
@@ -2665,6 +2788,7 @@ define([
         highlightWordAt: highlightWordAt,
         stopWordHighlight: stopWordHighlight,
         startMouthSync: startMouthSync,
+        startMouthSyncFromAnalyser: startMouthSyncFromAnalyser,
         stopMouthSync: stopMouthSync,
         isStartersVisible: isStartersVisible,
     };

amd/build/chat.min.js.map

@@ -189,5 +189,11 @@ function xmldb_local_ai_course_assistant_upgrade($oldversion) {
         upgrade_plugin_savepoint(true, 2025022600, 'local', 'ai_course_assistant');
     }
 
+    if ($oldversion < 2026030700) {
+        // v1.0.16: JS-only changes (typewriter animation, AudioContext TTS, Quick Study chip).
+        // No schema changes needed.
+        upgrade_plugin_savepoint(true, 2026030700, 'local', 'ai_course_assistant');
+    }
+
     return true;
 }

amd/build/ui.min.js

@@ -408,6 +408,7 @@
 $string['chat:starter_ell_practice']        = 'Practice Speaking';
 $string['chat:starter_ell_pronunciation']   = 'ELL Pronunciation';
 $string['chat:starter_ai_coach']            = 'AI Coach';
+$string['chat:starter_quick_study']         = 'Quick Study';
 $string['chat:starter_speak']               = 'Speak a starter';
 // Legacy keys kept for backwards compatibility.
 $string['chat:starter_help_lesson']         = 'Explain This';

amd/build/ui.min.js.map

@@ -570,8 +570,32 @@
     }
 }
 
+/* Swipe handle bar — appears above header on mobile, used to drag-to-dismiss */
+.aica-swipe-handle {
+    display: none; /* hidden on desktop */
+    flex-shrink: 0;
+    height: 20px;
+    align-items: center;
+    justify-content: center;
+    cursor: grab;
+    touch-action: pan-y;
+    -webkit-tap-highlight-color: transparent;
+}
+.aica-swipe-handle::after {
+    content: '';
+    display: block;
+    width: 36px;
+    height: 4px;
+    border-radius: 2px;
+    background: rgba(0, 0, 0, 0.18);
+}
+
 /* Mobile (< 600px) */
 @media (max-width: 600px) {
+    .aica-swipe-handle {
+        display: flex;
+    }
+
     .local-ai-course-assistant__drawer {
         position: fixed;
         left: 8px;
@@ -2477,18 +2501,15 @@
                aica-avatar-pulse 2.5s ease-out infinite;
 }
 
-/* Bounce — for preset (non-generated) avatars while speaking */
-@keyframes aica-avatar-bounce {
-    0%   { transform: translateY(0); }
-    35%  { transform: translateY(-8px) scale(1.04); }
-    55%  { transform: translateY(-3px) scale(1.01); }
-    70%  { transform: translateY(-6px) scale(1.03); }
-    100% { transform: translateY(0); }
+/* Glow pulse on the toggle button while TTS is active */
+@keyframes aica-speaking-glow {
+    0%   { box-shadow: 0 0 0 0px  rgba(74, 108, 247, 0.7); }
+    50%  { box-shadow: 0 0 0 12px rgba(74, 108, 247, 0.15); }
+    100% { box-shadow: 0 0 0 0px  rgba(74, 108, 247, 0.7); }
 }
 
-/* PNG/SVG-file avatars: bounce */
-.aica-avatar-svg--speaking:not(.aica-avatar-svg--has-svg) {
-    animation: aica-avatar-bounce 0.65s ease-in-out infinite;
+.local-ai-course-assistant__toggle.aica-speaking {
+    animation: aica-speaking-glow 0.7s ease-in-out infinite !important;
 }
 
 /* CSS fallback mouth for generated SVG avatars when Web Audio is unavailable */

amd/src/chat.js

@@ -74,6 +74,9 @@
          aria-label="{{#str}}chat:title, local_ai_course_assistant{{/str}}"
          aria-hidden="true">
 
+        {{! Swipe handle — mobile only; drag down to close }}
+        <div class="aica-swipe-handle" aria-hidden="true"></div>
+
         {{! Header }}
         <div class="local-ai-course-assistant__header">
             <div class="local-ai-course-assistant__header-title">
@@ -260,6 +263,13 @@
                 </span>
                 <span>{{#str}}chat:starter_ai_coach, local_ai_course_assistant{{/str}}</span>
             </button>
+            <button class="local-ai-course-assistant__starter" data-starter="quick-study">
+                <span class="aica-starter-icon" aria-hidden="true">
+                    {{! Timer icon — Quick Study }}
+                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16" fill="currentColor" aria-hidden="true"><path d="M15 1H9v2h6V1zm-4 13h2V8h-2v6zm8.03-6.61 1.42-1.42c-.43-.51-.9-.99-1.41-1.41l-1.42 1.42A7.73 7.73 0 0 0 12 4a8 8 0 1 0 8 8c0-2.21-.9-4.21-2.03-5.39zm-1.97 9.61A6 6 0 1 1 12 6a6 6 0 0 1 5.06 9.61z"/></svg>
+                </span>
+                <span>{{#str}}chat:starter_quick_study, local_ai_course_assistant{{/str}}</span>
+            </button>
         </div>
 
         {{! Typing indicator }}