refactor: update LLM warmup, optimize audio handling by removing conversion, and refine VRM animation API

.gitignore

@@ -8,3 +8,8 @@ core/__pycache__/
 *.wav
 static/Aiko.vrm
 static/Aiko.vrm
+
+.venv/
+.env
+.agents/
+.codex/

app.py

@@ -61,162 +61,72 @@ def build_soul_prompt(user_id: str) -> str:
 # HELPERS
 # ─────────────────────────────────────────────
 def _strip_for_speech(text: str) -> str:
+    """Remove search notes, tool tags, and think blocks before passing to TTS."""
     text = re.sub(r"\n?🔍 Searching: \*.*?\*\n?", "", text)
     text = re.sub(r"\n?🔧 .*?\n?", "", text)
     text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL)
     return text.strip()
 
 
-_SENTENCE_END = re.compile(r'(?<=[.!?。！？\n])\s*')
-
-
-def _split_ready_sentences(buffer: str):
-    parts = _SENTENCE_END.split(buffer)
-    if len(parts) <= 1:
-        return [], buffer
-    *complete, remainder = parts
-    return [p for p in complete if p.strip()], remainder
-
-
 # ─────────────────────────────────────────────
-# STREAM CORE
+# CORE RESPONSE  (full text → TTS → typewriter)
 # ─────────────────────────────────────────────
-_DONE = object()  # sentinel
 
-
-def _stream_response(message: str, history: list):
+def _get_response(message: str, history: list):
     """
-    Pipeline:
-      1. LLM streams tokens in background thread → sentence queue
-      2. Per sentence: TTS synthesis fires in background thread → audio queue
-      3. Gradio yields text+audio sentence by sentence as TTS completes
-      4. Chatbot shows text in sync with audio playback (sentence revealed
-         only when its audio is ready), input unlocks after all TTS done.
+    1. Show user message + thinking cursor immediately.
+    2. Run LLM to full completion (no streaming to UI).
+    3. Synthesize the complete response as one TTS pass.
+    4. Yield: chatbot with empty assistant bubble + TYPEWRITE signal + audio.
+       The iframe JS will typewrite the text into the chatbot bubble in sync
+       with the audio duration.
     """
     history = list(history) + [
-        {"role": "user", "content": message},
+        {"role": "user",      "content": message},
         {"role": "assistant", "content": "▋"},
     ]
+    # Show user message + thinking cursor right away
     yield history, None, None
 
-    # ── Stage 1: LLM → sentence queue ────────────────────────────────────────
-    sentence_q: queue.Queue = queue.Queue()
-    llm_error = {}
-
-    def _llm_thread():
-        buffer = ""
-        full_text = ""
-
-        def _cb(token):
-            nonlocal buffer, full_text
-            if token.startswith("__SEARCHING__:"):
-                q = token.split(":", 1)[1]
-                note = f"\n🔍 Searching: *{q}*\n"
-                buffer += note
-                full_text += note
-            elif token.startswith("__TOOL__:"):
-                note = token.split(":", 1)[1]
-                display = f"\n🔧 {note}\n"
-                buffer += display
-                full_text += display
-            else:
-                buffer += token
-                full_text += token
-
-            # Push complete sentences into queue as they arrive
-            sentences, new_buf = _split_ready_sentences(buffer)
-            buffer = new_buf
-            for s in sentences:
-                sentence_q.put(("sentence", s, full_text))
-
-        try:
-            think.chat(message, token_callback=_cb)
-        except Exception as e:
-            llm_error["e"] = e
-        finally:
-            # Flush remaining buffer
-            if buffer.strip():
-                sentence_q.put(("sentence", buffer.strip(), full_text))
-            sentence_q.put(("done", full_text, full_text))
-
-    threading.Thread(target=_llm_thread, daemon=True).start()
-
-    # ── Stage 2: sentence → TTS queue (parallel synthesis) ───────────────────
-    # Each sentence slot: (sentence_text, full_text_so_far, audio_queue)
-    # Audio synthesis fires immediately when sentence is ready; we drain
-    # in order so playback is sequential.
-    slots: list[tuple[str, str, queue.Queue]] = []
-    llm_done = threading.Event()
-    final_text = [""]
-
-    def _tts_worker(sentence: str, full_text: str, slot: queue.Queue):
-        clean = _strip_for_speech(sentence)
-        if not clean:
-            slot.put((None, "neutral", sentence, full_text))
-            return
-        audio, emotion = speak_to_file(clean)
-        slot.put((audio, emotion, sentence, full_text))
-
-    # Collect sentences and fire TTS threads
-    def _dispatch_thread():
-        while True:
-            kind, sentence, full_text = sentence_q.get()
-            if kind == "done":
-                final_text[0] = full_text
-                llm_done.set()
-                break
-            slot: queue.Queue = queue.Queue(maxsize=1)
-            slots.append(slot)
-            threading.Thread(
-                target=_tts_worker,
-                args=(sentence, full_text, slot),
-                daemon=True,
-            ).start()
-
-    threading.Thread(target=_dispatch_thread, daemon=True).start()
-
-    # ── Stage 3: drain slots in order, yield text+audio together ─────────────
-    # Show a "thinking" indicator while waiting for first sentence
-    displayed_text = ""
-    slot_idx = 0
-
-    while True:
-        # Check if new slots have appeared
-        if slot_idx < len(slots):
-            slot = slots[slot_idx]
-            audio, emotion, sentence, full_text_snapshot = slot.get()  # blocks until TTS done
-
-            # Reveal this sentence's text in sync with its audio
-            displayed_text += sentence + " "
-            history[-1]["content"] = displayed_text.strip()
-
-            yield (
-                history,
-                f"EMOTION:{emotion}|{_strip_for_speech(sentence)}",
-                audio,
-            )
-            slot_idx += 1
-
-        elif llm_done.is_set() and slot_idx >= len(slots):
-            # All sentences dispatched and drained
-            break
+    # ── Stage 1: full LLM completion ─────────────────────────────────────────
+    full_text = ""
+    search_notes: list[str] = []
+
+    def _cb(token: str):
+        nonlocal full_text
+        if token.startswith("__SEARCHING__:"):
+            q = token.split(":", 1)[1]
+            search_notes.append(f"🔍 Searching: *{q}*")
+        elif token.startswith("__TOOL__:"):
+            search_notes.append(f"🔧 {token.split(':', 1)[1]}")
         else:
-            # Still waiting for more sentences or TTS
-            time.sleep(0.05)
+            full_text += token
 
-    # Final cleanup — ensure full text is shown (covers edge case of no sentences)
-    if final_text[0] and history[-1]["content"] != final_text[0]:
-        history[-1]["content"] = final_text[0]
+    think.chat(message, token_callback=_cb)
 
-    yield history, None, None
+    # Build the display text shown in the chatbot bubble (notes + answer)
+    notes_prefix = "\n".join(search_notes) + "\n\n" if search_notes else ""
+    display_text = notes_prefix + full_text
 
-    if llm_error:
-        raise llm_error["e"]
+    # ── Stage 2: TTS on clean speech text ────────────────────────────────────
+    speech_text = _strip_for_speech(full_text)
+    if speech_text:
+        audio_path, emotion = speak_to_file(speech_text)
+    else:
+        audio_path, emotion = None, "neutral"
+
+    # ── Stage 3: signal the iframe to typewrite text in sync with audio ───────
+    # Chatbot bubble starts empty — JS will fill it character by character.
+    # Format packed into the hidden tts_text field:
+    #   TYPEWRITE:<emotion>|<display_text>
+    # The iframe reads audio.duration once metadata loads, then paces chars
+    # so the typewriter finishes exactly when the audio ends.
+    history[-1]["content"] = ""  # blank; JS owns this from here
+
+    signal = f"TYPEWRITE:{emotion}|{display_text}"
+    yield history, signal, audio_path
 
 
-# ─────────────────────────────────────────────
-# WRAPPERS
-# ─────────────────────────────────────────────
 def _submit(message, history):
     history = history or []
     message = (message or "").strip()
@@ -226,9 +136,9 @@ def _submit(message, history):
         return
 
     first = True
-    for h, tts, audio in _stream_response(message, history):
+    for h, tts, audio in _get_response(message, history):
         if first:
-            yield h, tts, audio, ""
+            yield h, tts, audio, ""   # clear input on first yield
             first = False
         else:
             yield h, tts, audio, gr.update()
@@ -241,11 +151,10 @@ def voice_chat(audio_path, history):
         return history, None, None
 
     transcript = transcribe_file(audio_path)
-
     if not transcript:
         return history, None, None
 
-    for h, tts, audio in _stream_response(transcript, history):
+    for h, tts, audio in _get_response(transcript, history):
         if h and len(h) >= 2:
             h[-2]["content"] = f"🎙️ {transcript}"
         yield h, tts, audio
@@ -391,7 +300,7 @@ with gr.Blocks(
                 // Find and click whatever button starts recording
                 const buttons = audioContainer.querySelectorAll('button');
                 buttons.forEach(b => {
-                    if (b.title?.toLowerCase().includes('record') || 
+                    if (b.title?.toLowerCase().includes('record') ||
                         b.getAttribute('aria-label')?.toLowerCase().includes('record')) {
                         b.click();
                     }
@@ -402,7 +311,7 @@ with gr.Blocks(
                 // Find and click stop
                 const buttons = audioContainer.querySelectorAll('button');
                 buttons.forEach(b => {
-                    if (b.title?.toLowerCase().includes('stop') || 
+                    if (b.title?.toLowerCase().includes('stop') ||
                         b.getAttribute('aria-label')?.toLowerCase().includes('stop')) {
                         b.click();
                     }
@@ -414,6 +323,127 @@ with gr.Blocks(
         """
     )
 
+    # ── Typewriter bridge ────────────────────────────────────────────────────
+    # When tts_text changes to a TYPEWRITE: signal, inject JS that:
+    #   1. Stores the full display text on window for the iframe to also use
+    #      (caption bar, lip-sync text source).
+    #   2. Waits for the <audio> element's metadata to know its duration.
+    #   3. Types characters into the last chatbot assistant bubble at a pace
+    #      that finishes exactly when audio ends (min 18ms/char so it's readable).
+    tts_text.change(
+        None,
+        inputs=[tts_text],
+        js="""
+        (rawSignal) => {
+            if (!rawSignal || !rawSignal.startsWith('TYPEWRITE:')) return;
+
+            const rest     = rawSignal.slice('TYPEWRITE:'.length);
+            const pipeIdx  = rest.indexOf('|');
+            const emotion  = rest.slice(0, pipeIdx);
+            const fullText = rest.slice(pipeIdx + 1);
+
+            // ── 1. Pass text + emotion to the VRM iframe ──────────────────
+            const iframe = document.querySelector('#aiko-vrm-frame');
+            if (iframe?.contentWindow) {
+                iframe.contentWindow.postMessage(
+                    JSON.stringify({ expression: emotion, ttsText: fullText }),
+                    '*'
+                );
+            }
+            // Also stash on window so the iframe's poll can find it
+            window._aikoLatestTtsText = fullText;
+
+            // ── 2. Find the last assistant bubble in the chatbot ──────────
+            // Gradio 4/5 uses .message.bot; Gradio 3 uses .bot.
+            // We look for the last rendered bot bubble's inner paragraph.
+            function getLastBubble() {
+                // Try Gradio 4/5 messages format first
+                const bubbles = document.querySelectorAll(
+                    '#aiko-chatbot .message.bot p, ' +
+                    '#aiko-chatbot [data-testid="bot"] p, ' +
+                    '#aiko-chatbot .bot p'
+                );
+                return bubbles.length ? bubbles[bubbles.length - 1] : null;
+            }
+
+            // ── 3. Typewriter function, paced to audio duration ───────────
+            let twTimer = null;
+
+            function runTypewriter(duration) {
+                const bubble = getLastBubble();
+                if (!bubble) {
+                    // Bubble not rendered yet — retry briefly
+                    setTimeout(() => runTypewriter(duration), 80);
+                    return;
+                }
+
+                const chars   = fullText.length;
+                // Aim to finish slightly before audio ends (×0.92 buffer)
+                const msPerChar = Math.max(18, (duration * 1000 * 0.92) / chars);
+
+                bubble.textContent = '';
+                let i = 0;
+
+                clearInterval(twTimer);
+                twTimer = setInterval(() => {
+                    if (i < chars) {
+                        bubble.textContent = fullText.slice(0, ++i);
+                        // Auto-scroll the chatbot to bottom
+                        const chatScroll = document.querySelector('#aiko-chatbot > div');
+                        if (chatScroll) chatScroll.scrollTop = chatScroll.scrollHeight;
+                    } else {
+                        clearInterval(twTimer);
+                    }
+                }, msPerChar);
+            }
+
+            // ── 4. Wait for audio element + its duration metadata ─────────
+            function waitForAudioAndType() {
+                const audioEl = document.querySelector('#aiko-audio audio');
+
+                if (!audioEl) {
+                    // Audio element not in DOM yet — poll briefly
+                    setTimeout(waitForAudioAndType, 100);
+                    return;
+                }
+
+                function start() {
+                    const dur = audioEl.duration;
+                    if (Number.isFinite(dur) && dur > 0) {
+                        runTypewriter(dur);
+                    } else {
+                        // Fallback: estimate ~0.075s per character
+                        const estimated = Math.max(2, fullText.length * 0.075);
+                        runTypewriter(estimated);
+                    }
+                }
+
+                if (audioEl.readyState >= 1 && Number.isFinite(audioEl.duration) && audioEl.duration > 0) {
+                    start();
+                } else {
+                    // Wait for metadata, but also set a fallback timeout
+                    const onMeta = () => {
+                        audioEl.removeEventListener('loadedmetadata', onMeta);
+                        start();
+                    };
+                    audioEl.addEventListener('loadedmetadata', onMeta);
+                    // Safety net: if metadata never fires (e.g. no audio), start anyway
+                    setTimeout(() => {
+                        audioEl.removeEventListener('loadedmetadata', onMeta);
+                        if (audioEl.duration > 0) {
+                            start();
+                        } else {
+                            runTypewriter(Math.max(2, fullText.length * 0.075));
+                        }
+                    }, 600);
+                }
+            }
+
+            waitForAudioAndType();
+        }
+        """
+    )
+
     demo.queue()
 
 # ─────────────────────────────────────────────

core/think.py

@@ -94,10 +94,13 @@ class AikoThink:
                 "/",
                 json={
                     "model":      LLAMA_MODEL,
-                    "max_tokens": 1,
-                    "messages":   [{"role": "user", "content": "hi"}],
+                    "max_tokens": 50,           # enough to force real inference
+                    "messages":   [{"role": "user", "content": "Say hello briefly."}],
+                    "temperature": 0.1,
                 },
+                timeout=120,
             )
+            log.info("LLM warmup complete")
         except Exception as e:
             log.warning("LLM warmup failed: %s", e)
 

ui/speak.py

@@ -118,17 +118,10 @@ async def _edge_tts_to_file(text: str, out_path: Path) -> None:
     )
     await communicate.save(str(out_path))
 
-
 def _miotts_to_file(text: str, out_path: Path) -> None:
-    """Call MioTTS /v1/tts/file (multipart/form-data) → write WAV then convert to MP3."""
+    """Call MioTTS /v1/tts/file (multipart/form-data) → write WAV."""
     import httpx
-    from pydub import AudioSegment
-    import io
 
-    # /v1/tts/file accepts multipart form fields:
-    #   text                — required
-    #   reference_preset_id — preset name registered via register_preset_cli
-    #   output_format       — "wav" returns raw audio/wav bytes directly
     data = {
         "text": text,
         "reference_preset_id": MIOTTS_PRESET_ID,
@@ -142,17 +135,14 @@ def _miotts_to_file(text: str, out_path: Path) -> None:
     )
     resp.raise_for_status()
 
-    # Response is raw WAV bytes (audio/wav) — convert to MP3 for Gradio browser playback
-    wav_bytes = io.BytesIO(resp.content)
-    audio = AudioSegment.from_wav(wav_bytes)
-    audio.export(str(out_path), format="mp3")
-
+    # Write WAV bytes directly — no conversion needed
+    out_path.write_bytes(resp.content)
 
 def _synth_to_file(clean: str) -> str | None:
-    """Synthesize cleaned text, return MP3 path or None on failure."""
+    """Synthesize cleaned text, return WAV path or None on failure."""
     TTS_DIR.mkdir(parents=True, exist_ok=True)
     digest = hashlib.sha1(f"{time.time_ns()}:{clean}".encode()).hexdigest()[:16]
-    out_path = TTS_DIR / f"aiko_{digest}.mp3"
+    out_path = TTS_DIR / f"aiko_{digest}.wav"
     try:
         if MIOTTS_URL:
             _miotts_to_file(clean[:4000], out_path)

ui/vrm.py

@@ -31,10 +31,16 @@ def gradio_file_url(path: Path) -> str:
 
 def avatar_html(vrm_urls: str | list[str]) -> str:
     """Return an iframe containing the Three/VRM viewer.
+
     Camera is framed to a half-body shot (waist-up). The iframe exposes a
-    postMessage API for expression, viseme, and ttsText/caption control.
-    An internal caption bar at the bottom of the canvas streams assistant
-    text as closed captions during audio playback.
+    postMessage API for expression, viseme, ttsText, and duration control.
+    Caption bar at the bottom streams the speech text during audio playback.
+
+    postMessage API (JSON string or object):
+      { expression: str, intensity?: float }        — set face expression
+      { ttsText: str, duration?: float }            — set lip-sync + caption text
+      { speaking: bool }                            — force speaking state
+      { viseme: str, weight?: float }               — direct viseme override
     """
     if isinstance(vrm_urls, str):
         vrm_urls = [vrm_urls]
@@ -91,7 +97,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       position: fixed;
       bottom: 0;
       left: 0;
-      right: 40%; /* leaves room for external chat overlay on the right */
+      right: 40%;
       min-height: 50px;
       max-height: 108px;
       padding: 10px 20px 14px 18px;
@@ -150,15 +156,15 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
     import {{ GLTFLoader }} from 'three/addons/loaders/GLTFLoader.js';
     import {{ VRMLoaderPlugin, VRMUtils }} from '@pixiv/three-vrm';
 
-    // ── Hard-lock this iframe's document height ──
+    // ── Hard-lock this iframe's document height ──────────────────────────────
     document.documentElement.style.setProperty('height', '100vh', 'important');
     document.documentElement.style.setProperty('overflow', 'hidden', 'important');
     document.body.style.setProperty('height', '100vh', 'important');
     document.body.style.setProperty('overflow', 'hidden', 'important');
     document.body.style.setProperty('max-height', '100vh', 'important');
-    
-    const RAW_VRM_URLS = {vrm_urls!r};
-    const VISEME_MAP = {{ A: 'aa', I: 'ih', U: 'ou', E: 'ee', O: 'oh' }};
+
+    const RAW_VRM_URLS  = {vrm_urls!r};
+    const VISEME_MAP    = {{ A: 'aa', I: 'ih', U: 'ou', E: 'ee', O: 'oh' }};
     const VISEME_PRESETS = ['aa', 'ih', 'ou', 'ee', 'oh'];
     const TEXT_VISEME_MAP = {{
       a: 'aa', á: 'aa', à: 'aa', â: 'aa', ä: 'aa', あ: 'aa', ア: 'aa', か: 'aa', カ: 'aa', さ: 'aa', サ: 'aa', た: 'aa', タ: 'aa', な: 'aa', ナ: 'aa', は: 'aa', ハ: 'aa', ま: 'aa', マ: 'aa', や: 'aa', ヤ: 'aa', ら: 'aa', ラ: 'aa', わ: 'aa', ワ: 'aa',
@@ -167,6 +173,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       e: 'ee', é: 'ee', è: 'ee', ê: 'ee', ë: 'ee', え: 'ee', エ: 'ee', け: 'ee', ケ: 'ee', せ: 'ee', セ: 'ee', て: 'ee', テ: 'ee', ね: 'ee', ネ: 'ee', へ: 'ee', ヘ: 'ee', め: 'ee', メ: 'ee', れ: 'ee', レ: 'ee',
       o: 'oh', ó: 'oh', ò: 'oh', ô: 'oh', ö: 'oh', お: 'oh', オ: 'oh', こ: 'oh', コ: 'oh', そ: 'oh', ソ: 'oh', と: 'oh', ト: 'oh', の: 'oh', ノ: 'oh', ほ: 'oh', ホ: 'oh', も: 'oh', モ: 'oh', よ: 'oh', ヨ: 'oh', ろ: 'oh', ロ: 'oh', を: 'oh', ヲ: 'oh', ん: 'oh', ン: 'oh',
     }};
+
     function withTrailingSlash(url) {{ return url.endsWith('/') ? url : url + '/'; }}
     function buildVrmUrls(rawUrls) {{
       const urls = [];
@@ -185,15 +192,14 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       }}
       return [...new Set(urls)];
     }}
+
     const VRM_URLS = buildVrmUrls(RAW_VRM_URLS);
-    const canvas  = document.getElementById('canvas');
+    const canvas   = document.getElementById('canvas');
     const renderer = new THREE.WebGLRenderer({{ canvas, antialias: true, alpha: true }});
     renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
     renderer.outputColorSpace = THREE.SRGBColorSpace;
+
     const scene  = new THREE.Scene();
-    // ── Half-body camera framing ──────────────────────────────────────────────
-    // Position: slightly closer, raised to ~waist level focus.
-    // FOV narrowed to 22° to reduce perspective distortion on a close portrait shot.
     const camera = new THREE.PerspectiveCamera(22, 1, 0.1, 100);
     camera.position.set(0.30, 1.18, 2.1);
     const controls = new OrbitControls(camera, canvas);
@@ -202,7 +208,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
     controls.enablePan     = false;
     controls.minDistance   = 1.0;
     controls.maxDistance   = 3.2;
-    // ─────────────────────────────────────────────────────────────────────────
+
     scene.add(new THREE.HemisphereLight(0xded4ff, 0x21182f, 2.4));
     const key = new THREE.DirectionalLight(0xffffff, 2.7);
     key.position.set(1.8, 3.0, 2.5);
@@ -210,8 +216,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
     const rim = new THREE.DirectionalLight(0x9b7cff, 1.5);
     rim.position.set(-2.5, 1.4, -1.2);
     scene.add(rim);
-    // No floor grid — cleaner for half-body portrait
-    // scene.add(new THREE.GridHelper(10, 20, 0x1a0a2a, 0x100820));
+
     let vrm = null;
     let mouth = 0;
     let smoothedAudioMouth = 0;
@@ -229,6 +234,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
     let speechVisemes  = [];
     let speechStartedAt = 0;
     let speechDuration = 0;
+
     const REST = window._REST = {{
       leftUpperArm:  {{ x:  0.02, y: 0.0, z: -1.28 }},
       rightUpperArm: {{ x:  0.02, y: 0.0, z:  1.28 }},
@@ -237,15 +243,19 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       leftHand:      {{ x:  0.0,  y: 0.08, z:  0.0 }},
       rightHand:     {{ x:  0.0,  y:-0.08, z:  0.0 }},
     }};
+
     const dot         = document.getElementById('dot');
     const statusText  = document.getElementById('status-text');
     const emotionEl   = document.getElementById('emotion');
     const captionBar  = document.getElementById('caption-bar');
     const captionText = document.getElementById('caption-text');
+
     // ── Caption streaming ─────────────────────────────────────────────────────
+    // Paces word-by-word reveal proportional to audio duration.
     let captionWords = [];
     let captionIdx   = 0;
     let captionTimer = null;
+
     function startCaption(text) {{
       clearInterval(captionTimer);
       captionWords = text.trim().split(/\s+/).filter(Boolean);
@@ -253,28 +263,31 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       captionText.textContent = '';
       captionBar.classList.remove('hidden');
       if (!captionWords.length) return;
-      // Pace: reveal ~2-3 words at a time proportional to speech duration
+
       const totalWords   = captionWords.length;
-      const totalSeconds = (lastAudio && lastAudio.duration > 0) ? lastAudio.duration : Math.max(2, totalWords * 0.38);
-      const msPerWord    = (totalSeconds * 1000) / totalWords;
+      const totalSeconds = (lastAudio && lastAudio.duration > 0)
+        ? lastAudio.duration
+        : Math.max(2, totalWords * 0.38);
+      const msPerWord = (totalSeconds * 1000) / totalWords;
+
       captionTimer = setInterval(() => {{
         if (captionIdx >= captionWords.length) {{
           clearInterval(captionTimer);
-          // fade out after a short hold
           setTimeout(() => {{ captionBar.classList.add('hidden'); }}, 1800);
           return;
         }}
-        // Show a rolling window of the last ~12 words
         const windowEnd   = captionIdx + 1;
         const windowStart = Math.max(0, windowEnd - 12);
         captionText.textContent = captionWords.slice(windowStart, windowEnd).join(' ');
         captionIdx++;
       }}, msPerWord);
     }}
+
     function stopCaption() {{
       clearInterval(captionTimer);
       setTimeout(() => captionBar.classList.add('hidden'), 1200);
     }}
+
     // ─────────────────────────────────────────────────────────────────────────
     function nextBlinkWait() {{ return 3.0 + Math.random() * 4.0; }}
     function expressionNames() {{
@@ -285,17 +298,19 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
     function safeSetExpression(name, weight) {{
       try {{ vrm?.expressionManager?.setValue(name, weight); }} catch (_) {{}}
     }}
+
     let lastW = 0, lastH = 0;
     function resize() {{
-        const w = Math.max(1, Math.min(window.screen.width, canvas.clientWidth || window.innerWidth));
-        const h = Math.max(1, Math.min(window.screen.height, canvas.clientHeight || window.innerHeight));
-        if (w === lastW && h === lastH) return;
-        lastW = w; lastH = h;
-        renderer.setSize(w, h, false);
-        camera.aspect = w / h;
-        camera.updateProjectionMatrix();
+      const w = Math.max(1, Math.min(window.screen.width,  canvas.clientWidth  || window.innerWidth));
+      const h = Math.max(1, Math.min(window.screen.height, canvas.clientHeight || window.innerHeight));
+      if (w === lastW && h === lastH) return;
+      lastW = w; lastH = h;
+      renderer.setSize(w, h, false);
+      camera.aspect = w / h;
+      camera.updateProjectionMatrix();
     }}
     addEventListener('resize', resize);
+
     function setExpression(name, weight = 1) {{
       if (!vrm?.expressionManager) return;
       for (const k of ['happy', 'relaxed', 'angry', 'sad', 'surprised']) {{
@@ -303,6 +318,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       }}
       emotionEl.textContent = name || 'neutral';
     }}
+
     function setMouth(weight, viseme = 'aa') {{
       if (!vrm) return;
       const clamped = Math.max(0, Math.min(1, Number(weight) || 0));
@@ -327,7 +343,9 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         if (jaw) jaw.rotation.x = clamped * 0.5;
       }}
     }}
+
     function clearMouth() {{ setMouth(0, 'aa'); }}
+
     function setSpeaking(active) {{
       speaking = Boolean(active);
       dot.className = speaking ? 'speaking' : '';
@@ -335,12 +353,14 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       setExpression(speaking ? 'happy' : 'relaxed', speaking ? 0.55 : 0.25);
       if (!speaking) {{ clearMouth(); stopCaption(); }}
     }}
+
     function estimateSpeechDuration(text, requestedDuration = null) {{
       const explicit = Number(requestedDuration);
       if (Number.isFinite(explicit) && explicit > 0) return explicit;
       if (lastAudio && Number.isFinite(lastAudio.duration) && lastAudio.duration > 0) return lastAudio.duration;
       return Math.max(1.0, Math.min(12, text.length * 0.075));
     }}
+
     function textToVisemes(text) {{
       const tokens = [];
       let lastViseme = 'aa';
@@ -357,6 +377,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       }}
       return tokens.length ? tokens : [{{ viseme: 'aa', weight: 0.25 }}];
     }}
+
     function setSpeechText(text, duration = null) {{
       const nextText = String(text || '').trim();
       if (!nextText) return;
@@ -364,14 +385,17 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       speechVisemes   = textToVisemes(speechText);
       speechDuration  = estimateSpeechDuration(speechText, duration);
       speechStartedAt = performance.now();
-      // Start closed captions
       startCaption(speechText);
     }}
+
     function currentTextMouth(now) {{
       if (!speechVisemes.length) return null;
-      const audioDuration = lastAudio && Number.isFinite(lastAudio.duration) && lastAudio.duration > 0 ? lastAudio.duration : speechDuration;
+      const audioDuration = lastAudio && Number.isFinite(lastAudio.duration) && lastAudio.duration > 0
+        ? lastAudio.duration : speechDuration;
       const duration  = Math.max(0.25, audioDuration || speechDuration || 1);
-      const elapsed   = lastAudio && !lastAudio.paused ? lastAudio.currentTime : (now - speechStartedAt) / 1000;
+      const elapsed   = lastAudio && !lastAudio.paused
+        ? lastAudio.currentTime
+        : (now - speechStartedAt) / 1000;
       const progress  = Math.max(0, Math.min(0.999, elapsed / duration));
       const index     = Math.min(speechVisemes.length - 1, Math.floor(progress * speechVisemes.length));
       const token     = speechVisemes[index];
@@ -381,23 +405,13 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         weight: Math.max(0, Math.min(1, token.weight * (0.55 + Math.abs(syllablePhase) * 0.45))),
       }};
     }}
-    function findParentSpeechText() {{
-      if (window._aikoLatestTtsText) {{
-        const t = window._aikoLatestTtsText;
-        window._aikoLatestTtsText = '';
-        return t;
-      }}
-      try {{
-        const doc = parent.document;
-        const el  = doc.querySelector('#aiko-tts-text textarea, #aiko-tts-text input');
-        return el ? (el.value || el.textContent || '') : '';
-      }} catch (_) {{ return ''; }}
-    }}
+
     function getBone(name) {{
       const h = vrm?.humanoid;
       if (!h) return null;
       return h.getRawBoneNode?.(name) || h.getNormalizedBoneNode?.(name) || null;
     }}
+
     function applyIdle(dt) {{
       if (!vrm?.humanoid) return;
       idleTime += dt;
@@ -434,10 +448,11 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       if (rUA) {{ rUA.rotation.x = REST.rightUpperArm.x + Math.sin(idleTime * 0.53 + 0.9) * 0.010; rUA.rotation.y = REST.rightUpperArm.y + Math.sin(idleTime * 0.35 + 0.4) * 0.006; rUA.rotation.z = REST.rightUpperArm.z + Math.sin(idleTime * 0.37 + 0.7) * 0.008; }}
       if (lLA) {{ lLA.rotation.x = REST.leftLowerArm.x  + Math.sin(idleTime * 0.61) * 0.008; lLA.rotation.y = REST.leftLowerArm.y; lLA.rotation.z = REST.leftLowerArm.z  + Math.sin(idleTime * 0.43) * 0.004; }}
       if (rLA) {{ rLA.rotation.x = REST.rightLowerArm.x + Math.sin(idleTime * 0.57 + 1.4) * 0.008; rLA.rotation.y = REST.rightLowerArm.y; rLA.rotation.z = REST.rightLowerArm.z + Math.sin(idleTime * 0.51 + 0.5) * 0.004; }}
-      if (lH)  {{ lH.rotation.x = REST.leftHand.x;  lH.rotation.y = REST.leftHand.y  + Math.sin(idleTime * 0.33) * 0.008; lH.rotation.z = REST.leftHand.z; }}
-      if (rH)  {{ rH.rotation.x = REST.rightHand.x; rH.rotation.y = REST.rightHand.y + Math.sin(idleTime * 0.29 + 1.2) * 0.008; rH.rotation.z = REST.rightHand.z; }}
+      if (lH)  {{ lH.rotation.x  = REST.leftHand.x;  lH.rotation.y  = REST.leftHand.y  + Math.sin(idleTime * 0.33) * 0.008; lH.rotation.z = REST.leftHand.z; }}
+      if (rH)  {{ rH.rotation.x  = REST.rightHand.x; rH.rotation.y  = REST.rightHand.y + Math.sin(idleTime * 0.29 + 1.2) * 0.008; rH.rotation.z = REST.rightHand.z; }}
     }}
-    // ── Idle gesture state machine ───────────────────────────────────────────
+
+    // ── Idle gesture state machine ───────────────��────────────────────────────
     let gestureState    = 'none';
     let gestureT        = 0;
     let gestureDuration = 0;
@@ -445,14 +460,10 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
     let gestureTarget   = null;
     const GESTURES = ['lookAround', 'sideGlance', 'meetGaze', 'curiousTilt', 'shiftWeight', 'hairTuck', 'stretchNeck'];
     const GESTURE_DURATION = {{
-      lookAround: 3.2,
-      sideGlance: 2.2,
-      meetGaze: 2.8,
-      curiousTilt: 2.4,
-      shiftWeight: 3.2,
-      hairTuck: 2.7,
-      stretchNeck: 2.6,
+      lookAround: 3.2, sideGlance: 2.2, meetGaze: 2.8,
+      curiousTilt: 2.4, shiftWeight: 3.2, hairTuck: 2.7, stretchNeck: 2.6,
     }};
+
     function pickGesture() {{
       const g = GESTURES[Math.floor(Math.random() * GESTURES.length)];
       gestureState    = g;
@@ -466,12 +477,14 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         hairSide: side,
       }};
     }}
+
     function easeInOutSine(t) {{ return -(Math.cos(Math.PI * t) - 1) / 2; }}
     function holdCurve(progress, inPortion = 0.28, outPortion = 0.30) {{
       if (progress < inPortion) return easeInOutSine(progress / inPortion);
       if (progress > 1 - outPortion) return easeInOutSine((1 - progress) / outPortion);
       return 1;
     }}
+
     function applyGestures(dt) {{
       if (!vrm?.humanoid) return;
       if (speaking) {{ gestureState = 'none'; return; }}
@@ -491,43 +504,27 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       const spine = getBone('spine'), hips = getBone('hips');
       switch (gestureState) {{
         case 'lookAround':
-          if (head) {{
-            head.rotation.y += gestureTarget.lookAround * held;
-            head.rotation.x += Math.sin(eased * Math.PI) * 0.025;
-          }}
-          if (neck) neck.rotation.y += gestureTarget.lookAround * 0.22 * held;
+          if (head) {{ head.rotation.y += gestureTarget.lookAround * held; head.rotation.x += Math.sin(eased * Math.PI) * 0.025; }}
+          if (neck)   neck.rotation.y += gestureTarget.lookAround * 0.22 * held;
           break;
         case 'sideGlance':
-          if (head) {{
-            head.rotation.y += gestureTarget.sideGlance * held;
-            head.rotation.z -= gestureTarget.sideGlance * 0.18 * intensity;
-          }}
+          if (head) {{ head.rotation.y += gestureTarget.sideGlance * held; head.rotation.z -= gestureTarget.sideGlance * 0.18 * intensity; }}
           safeSetExpression('relaxed', 0.28);
           break;
         case 'meetGaze':
-          if (head) {{
-            head.rotation.y *= 1 - held * 0.78;
-            head.rotation.z *= 1 - held * 0.70;
-            head.rotation.x += held * 0.018;
-          }}
-          if (neck) {{
-            neck.rotation.y *= 1 - held * 0.55;
-            neck.rotation.z *= 1 - held * 0.55;
-          }}
+          if (head) {{ head.rotation.y *= 1 - held * 0.78; head.rotation.z *= 1 - held * 0.70; head.rotation.x += held * 0.018; }}
+          if (neck) {{ neck.rotation.y *= 1 - held * 0.55; neck.rotation.z *= 1 - held * 0.55; }}
           safeSetExpression('relaxed', 0.30);
           safeSetExpression('happy', 0.04 * held);
           break;
         case 'curiousTilt':
-          if (head) {{
-            head.rotation.z += gestureTarget.curiousTilt * held;
-            head.rotation.x -= 0.018 * intensity;
-          }}
-          if (neck) neck.rotation.z += gestureTarget.curiousTilt * 0.45 * held;
+          if (head) {{ head.rotation.z += gestureTarget.curiousTilt * held; head.rotation.x -= 0.018 * intensity; }}
+          if (neck)   neck.rotation.z += gestureTarget.curiousTilt * 0.45 * held;
           break;
         case 'shiftWeight':
-          if (hips) hips.position.x += Math.sin(eased * Math.PI) * 0.016;
+          if (hips)  hips.position.x  += Math.sin(eased * Math.PI) * 0.016;
           if (spine) spine.rotation.z += Math.sin(eased * Math.PI) * 0.018;
-          if (head) head.rotation.z -= Math.sin(eased * Math.PI) * 0.012;
+          if (head)  head.rotation.z  -= Math.sin(eased * Math.PI) * 0.012;
           break;
         case 'hairTuck':
           if (gestureTarget.hairSide < 0) {{
@@ -539,10 +536,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
             if (rLA) {{ rLA.rotation.x = REST.rightLowerArm.x - intensity * 0.26; rLA.rotation.z = REST.rightLowerArm.z + intensity * 0.10; }}
             if (rH)  {{ rH.rotation.y  = REST.rightHand.y - intensity * 0.16; rH.rotation.z = REST.rightHand.z + intensity * 0.10; }}
           }}
-          if (head) {{
-            head.rotation.z -= gestureTarget.hairSide * intensity * 0.035;
-            head.rotation.y += gestureTarget.hairSide * intensity * 0.025;
-          }}
+          if (head) {{ head.rotation.z -= gestureTarget.hairSide * intensity * 0.035; head.rotation.y += gestureTarget.hairSide * intensity * 0.025; }}
           break;
         case 'stretchNeck':
           if (neck) neck.rotation.x += -intensity * 0.05;
@@ -551,7 +545,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
       }}
       if (progress >= 1) gestureState = 'none';
     }}
-    // ─────────────────────────────────────────────────────────────────────────
+
     function applyBlink(dt) {{
       if (!vrm?.expressionManager) return;
       if (blinkPhase === 'wait') {{
@@ -570,6 +564,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         }}
       }}
     }}
+
     let lastAudio      = null;
     let audioContext   = null;
     let analyserAudio  = null;
@@ -577,15 +572,16 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
     let audioSource    = null;
     let audioMeterOk   = false;
     let meteredAudio   = null;
+
     function setupAudioMeter(audio) {{
-      if (!audio || audioMeterOk && audio === meteredAudio) return;
+      if (!audio || (audioMeterOk && audio === meteredAudio)) return;
       try {{
         audioContext = audioContext || new (window.AudioContext || window.webkitAudioContext)();
         if (audioContext.state === 'suspended') audioContext.resume().catch(() => {{}});
         analyserAudio = audioContext.createAnalyser();
         analyserAudio.fftSize = 512;
         analyserAudio.smoothingTimeConstant = 0.72;
-        audioData = new Uint8Array(analyserAudio.fftSize);
+        audioData   = new Uint8Array(analyserAudio.fftSize);
         audioSource = audio._aikoMediaSource || audioContext.createMediaElementSource(audio);
         audio._aikoMediaSource = audioSource;
         audioSource.connect(analyserAudio);
@@ -600,6 +596,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         audioData = null;
       }}
     }}
+
     function getAudioMouth() {{
       if (!analyserAudio || !audioData) return null;
       analyserAudio.getByteTimeDomainData(audioData);
@@ -608,76 +605,101 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         const centered = (audioData[i] - 128) / 128;
         sum += centered * centered;
       }}
-      const rms = Math.sqrt(sum / audioData.length);
-      const gated = Math.max(0, rms - 0.018);
+      const rms    = Math.sqrt(sum / audioData.length);
+      const gated  = Math.max(0, rms - 0.018);
       const target = Math.min(1, Math.pow(gated * 7.5, 0.72));
       smoothedAudioMouth += (target - smoothedAudioMouth) * (target > smoothedAudioMouth ? 0.55 : 0.28);
       return smoothedAudioMouth;
     }}
+
     function findParentAudio() {{
       try {{ return parent.document.querySelector('#aiko-audio audio') || parent.document.querySelector('audio'); }}
       catch (_) {{ return null; }}
     }}
+
     function syncAudioState(audio) {{
       if (!audio) return;
       setSpeaking(!audio.paused && !audio.ended && audio.currentTime >= 0);
     }}
+
     function attachAudio(audio) {{
       if (!audio) return;
       if (audio !== lastAudio) {{
         lastAudio = audio;
+
         audio.addEventListener('play', () => {{
           setSpeaking(true);
           setupAudioMeter(audio);
-          let tries = 0;
-          const poll = setInterval(() => {{
-            const text = findParentSpeechText();
-            if (text) {{
-              clearInterval(poll);
-              setSpeechText(text, audio.duration);
-            }} else if (++tries >= 10) {{
-              clearInterval(poll);
-            }}
-          }}, 200);
+          // ttsText is pushed via postMessage from the parent page's JS bridge;
+          // _aikoLatestTtsText is set on window by that same bridge as a fallback.
+          if (window._aikoLatestTtsText) {{
+            setSpeechText(window._aikoLatestTtsText, audio.duration);
+            window._aikoLatestTtsText = '';
+          }}
         }});
+
         audio.addEventListener('playing', () => {{
           setSpeaking(true);
           setupAudioMeter(audio);
-          const text = findParentSpeechText();
-          if (text) setSpeechText(text, audio.duration);
+          if (window._aikoLatestTtsText) {{
+            setSpeechText(window._aikoLatestTtsText, audio.duration);
+            window._aikoLatestTtsText = '';
+          }}
+        }});
+
+        audio.addEventListener('timeupdate', () => {{
+          if (!audio.paused && audio.currentTime > 0) setSpeaking(true);
         }});
-        audio.addEventListener('timeupdate', () => {{ if (!audio.paused && audio.currentTime > 0) setSpeaking(true); }});
         audio.addEventListener('pause',  () => setSpeaking(false));
         audio.addEventListener('ended',  () => setSpeaking(false));
       }}
       syncAudioState(audio);
     }}
+
     setInterval(() => attachAudio(findParentAudio()), 500);
+
+    // ── postMessage API ───────────────────────────────────────────────────────
+    // Receives messages from app.py's tts_text.change JS bridge (and anything
+    // else that wants to control the avatar).
     window.addEventListener('message', (e) => {{
       try {{
         const msg = (typeof e.data === 'string') ? JSON.parse(e.data) : e.data;
-        if (msg.speaking !== undefined) setSpeaking(msg.speaking);
+
+        // Expression / emotion
         if (msg.expression !== undefined) {{
           setExpression(msg.expression, msg.intensity ?? 1.0);
           clearTimeout(exprResetTimer);
-          if (msg.expression && msg.expression !== 'neutral')
+          if (msg.expression && msg.expression !== 'neutral') {{
             exprResetTimer = setTimeout(() => setExpression('relaxed', 0.25), EXPR_RESET_DELAY);
+          }}
         }}
+
+        // Speech text for lip-sync + caption (sent by the JS bridge alongside audio)
         const incomingText = msg.ttsText ?? msg.speechText ?? msg.text;
         if (incomingText !== undefined) {{
+          // Store for the audio 'play' event to pick up if it fires after postMessage
           window._aikoLatestTtsText = incomingText;
           setSpeechText(incomingText, msg.duration ?? msg.audioDuration ?? null);
           if (msg.speaking === undefined && msg.playNow) setSpeaking(true);
         }}
+
+        // Direct speaking state override
+        if (msg.speaking !== undefined) setSpeaking(msg.speaking);
+
+        // Direct viseme override (for external controllers)
         if (msg.viseme !== undefined) {{
           setMouth(msg.weight ?? 1.0, msg.viseme);
           clearTimeout(window._aikoMouthTimer);
           window._aikoMouthTimer = setTimeout(clearMouth, 180);
         }}
+
       }} catch (_) {{}}
     }});
+
+    // ── VRM loader ────────────────────────────────────────────────────────────
     const loader = new GLTFLoader();
     loader.register(parser => new VRMLoaderPlugin(parser));
+
     function loadVrm(index = 0) {{
       const url = VRM_URLS[index];
       if (!url) {{
@@ -692,13 +714,14 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         vrm.scene.traverse(o => {{ if (o.frustumCulled) o.frustumCulled = false; }});
         vrm.scene.rotation.y = 0;
         scene.add(vrm.scene);
-        // Add this after scene.add:
+
         setTimeout(() => {{
           const lUA = vrm.humanoid?.getRawBoneNode('leftUpperArm');
           const rUA = vrm.humanoid?.getRawBoneNode('rightUpperArm');
           console.log('[aiko-vrm] leftUpperArm rotation:', lUA?.rotation);
           console.log('[aiko-vrm] rightUpperArm rotation:', rUA?.rotation);
         }}, 500);
+
         setExpression('relaxed', 0.25);
         console.log('Available expressions:', expressionNames());
         document.getElementById('loader').classList.add('fade');
@@ -708,18 +731,23 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         loadVrm(index + 1);
       }});
     }}
+
     loadVrm();
+
+    // ── Render loop ───────────────────────────────────────────────────────────
     function tick() {{
       requestAnimationFrame(tick);
       resize();
-      const dt  = Math.min(clock.getDelta(), 0.05);
+      const dt = Math.min(clock.getDelta(), 0.05);
       controls.update();
       if (vrm) vrm.update(dt);
       applyIdle(dt);
       applyGestures(dt);
-      const now       = performance.now();
-      const textMouth = speaking ? currentTextMouth(now) : null;
-      const audioMouth = speaking ? getAudioMouth() : null;
+
+      const now        = performance.now();
+      const textMouth  = speaking ? currentTextMouth(now) : null;
+      const audioMouth = speaking ? getAudioMouth()       : null;
+
       if (audioMouth !== null) {{
         setMouth(audioMouth, textMouth?.viseme ?? 'aa');
       }} else if (textMouth) {{
@@ -731,6 +759,7 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         smoothedAudioMouth = 0;
         clearMouth();
       }}
+
       applyBlink(dt);
       renderer.render(scene, camera);
     }}
@@ -743,4 +772,4 @@ def avatar_html(vrm_urls: str | list[str]) -> str:
         '<iframe id="aiko-vrm-frame" title="Aiko VRM Avatar" '
         'sandbox="allow-scripts allow-same-origin" '
         f'srcdoc="{html.escape(srcdoc, quote=True)}"></iframe>'
-    )
+    )