feat(01-08): add the server turn - synthesis, timeline, per-request timings, directive

- telemetry/timings.py: TurnTimings with mark() and a stage() context manager, one flat
record per request, server_total_ms measured from construction; never module-level
- voice/models.py re-exports TurnTimings from telemetry and gives AvatarDirective to_dict()
- ui/blocks.py: turn() builds the viseme timeline from the query that was actually
synthesised at the requested speed, base64-encodes the WAV as a data URL and returns the
directive; validation and synthesis failures return {error} because the gr.HTML bridge
turns a raised exception into undefined in the browser; greeting() for one-click speech;
the full Phase 1 layout with stable elem_ids, the credit footer, the flow-down notice and
the About panel; warm_synthesizer bound to Blocks.load
- app.py slimmed to assembly plus the ZeroGPU probe (39 lines)

The bridge packs a call's arguments into one JSON value (dict from JS, list for several
args, [] for none) and calls the Python function with that single positional, so turn()
accepts a {text, speed} payload and greeting() tolerates a stray positional.

app.py

@@ -1,161 +1,39 @@
-"""Space entry point: assembly only.
+"""Space entry point: assembly only. The layout and the turn live in japanese_avatar.ui.blocks."""
 
-No logic and no module-level mutable state lives here. Gradio shares module globals
-across every visitor session, so the discipline starts now, while there is still
-nothing to share.
-
-The right-hand column is deliberately inert. Plans 01-08 and 01-09 give the controls
-their real behaviour; what they need from this plan is that the ``elem_id`` values
-(``status-line``, ``transcript``, ``credits``) already exist so their selectors are
-stable, and that interacting with the controls today already round-trips through
-Python - which is what ``test_no_remount`` measures the avatar against.
-"""
-
-import html
 import os
 import sys
 from pathlib import Path
 
-import gradio as gr
 import spaces
 
-# The Space runs `python app.py` with only requirements.txt installed - it never
-# pip-installs this repository - so the src/ layout package is not on sys.path there and
-# the import below raised ModuleNotFoundError on the first deploy (RUNTIME_ERROR on
-# 6eeb816). Locally the dev venv has the project installed and this is a no-op. Doing it
-# here rather than through a PYTHONPATH Space variable keeps the app runnable from a
-# clean checkout with no platform configuration to lose.
+# The Space runs `python app.py` against requirements.txt alone and never pip-installs this
+# repository, so the src/ layout is not on sys.path there (RUNTIME_ERROR on the first deploy).
 _SRC = Path(__file__).resolve().parent / "src"
 if str(_SRC) not in sys.path:
     sys.path.insert(0, str(_SRC))
 
-from japanese_avatar.ui.avatar_component import StatusLine, VrmStage  # noqa: E402
-
-# Serves avatar/ straight off disk, bypassing the Gradio cache, which is how the
-# browser reaches avatar.js, stage.html and tutor.vrm. Deliberately one dedicated
-# directory: this call's own docstring warns that ALL files under a listed path
-# become network-reachable.
-gr.set_static_paths(["avatar"])
-
-# Visitor-facing copy. This is a public portfolio Space, so it states plainly what the
-# build does and does not do: an avatar that renders but cannot answer is a bug report
-# waiting to happen if the page implies otherwise. Internal plan numbers never appear here.
-INTRO_HTML = (
-    '<div id="intro" class="intro">'
-    "<strong>Preview build.</strong> The 3D avatar, its idle animation and the mora-timed "
-    "lip-sync engine are live and running in your browser. Speech and conversation are "
-    "built and tested but not yet connected, so the avatar will not answer you yet - "
-    "the box below only echoes your text back."
-    "</div>"
-)
-
-CREDITS_HTML = (
-    '<div id="credits-text" class="credits">'
-    "Avatar: <em>VRM1_Constraint_Twist_Sample</em> by pixiv Inc. (VRM 1.0). "
-    "Voice credits appear here once synthesised audio ships."
-    "</div>"
-)
+from japanese_avatar.ui.blocks import build_blocks  # noqa: E402
 
 
 def gpu_disabled() -> bool:
-    """SC-4's kill switch: the whole turn loop must complete with DISABLE_GPU=1.
-
-    Read per call rather than captured at import so a Space restart with the variable
-    flipped takes effect without a code change.
-    """
+    """SC-4's kill switch, read per call so a restart with the variable flipped takes effect."""
     return os.environ.get("DISABLE_GPU", "0").strip().lower() in {"1", "true", "yes"}
 
 
-# ZeroGPU REQUIRES at least one @spaces.GPU function to exist, or it refuses to run the
-# Space at all. Discovered empirically on the fourth deploy (8c9985e): the app built,
-# imported, bound port 7860 and printed its "Running on local URL" line, and the platform
-# then SIGTERMed it and reported
-#
-#     runtime.errorMessage: "No @spaces.GPU function detected during startup"
-#
-# That is a hard platform constraint and there is no way around it: docs/HOSTING.md
-# records that cpu-basic Gradio Spaces are 402-gated on this account, so ZeroGPU is the
-# only free hosting path this project has.
-#
-# So this function exists purely to satisfy the scheduler's startup scan. It is NOT on
-# the turn path, nothing in the app calls it, and it refuses to do anything when
-# DISABLE_GPU is set. If SC-4's demonstration ever needs strengthening, the right assertion
-# is "the turn loop completes without this function's counter moving", not "no GPU function
-# exists" - the platform has taken the latter off the table.
+# ZeroGPU refuses to run a Space with no @spaces.GPU function ("No @spaces.GPU function
+# detected during startup", docs/HOSTING.md). This probe exists only to satisfy that scan. It is
+# not on the turn path, nothing calls it, and tests/test_no_gpu_on_turn_path.py proves both.
 @spaces.GPU(duration=1)
 def zerogpu_probe() -> str:
     """The GPU entry point ZeroGPU requires to exist. Deliberately unreachable in Phase 1."""
     if gpu_disabled():
-        raise RuntimeError(
-            "zerogpu_probe called with DISABLE_GPU=1; Phase 1 has no GPU work and nothing "
-            "on the turn path may reach this function"
-        )
+        raise RuntimeError("zerogpu_probe called with DISABLE_GPU=1; Phase 1 has no GPU work")
     return "zerogpu reachable"
 
 
-def _echo(text: str, slower: bool, history: str) -> tuple[str, str]:
-    """Placeholder turn handler. Pure: state arrives as an argument and leaves as a value.
-
-    It exists so the controls perform a real Python round trip in Phase 1, because a
-    control that never reaches the server would not exercise the re-render path that
-    ``mountCount`` is supposed to survive. Plan 01-08 replaces the body with the real
-    turn dispatch; the signature is already the shape that plan needs.
-    """
-    said = (text or "").strip()
-    if not said:
-        return history, ""
-    speed = " (slower)" if slower else ""
-    # Escaped, not interpolated raw: this string is rendered as HTML and the text comes
-    # from the visitor. A placeholder is still a rendering path.
-    line = f'<div class="turn">{html.escape(said)}{html.escape(speed)}</div>'
-    return f"{history}{line}", ""
-
-
-def build_app() -> gr.Blocks:
-    """Build the Blocks app. Importable and callable from tests without launching."""
-    with gr.Blocks(title="Japanese Learning Avatar", fill_height=True) as blocks:
-        with gr.Row(equal_height=True):
-            with gr.Column(scale=3, min_width=320):
-                VrmStage()
-            with gr.Column(scale=2, min_width=280):
-                StatusLine()
-                gr.HTML(value=INTRO_HTML, elem_id="intro-html")
-                transcript = gr.HTML(
-                    value="",
-                    elem_id="transcript",
-                    label="Transcript",
-                )
-                text_in = gr.Textbox(
-                    value="",
-                    placeholder="Type anything - it echoes back for now",
-                    label="Text (echo preview - the avatar cannot reply yet)",
-                    elem_id="text-input",
-                    submit_btn=True,
-                )
-                slower = gr.Checkbox(
-                    value=False,
-                    label="Speak slower (inactive until speech is connected)",
-                    elem_id="slower",
-                )
-                send = gr.Button("Send", elem_id="send", variant="primary")
-                gr.HTML(value=CREDITS_HTML, elem_id="credits")
-
-        send.click(_echo, [text_in, slower, transcript], [transcript, text_in])
-        text_in.submit(_echo, [text_in, slower, transcript], [transcript, text_in])
-    return blocks
-
-
-# Module level, and named `demo`, because that is what the Space runner requires.
-# Hugging Face launches the app under gradio.utils.SpacesReloader, whose postrun() does
-# `getattr(watch_module, self.demo_name)` on every reload check. With the Blocks living
-# only inside build_app() there was no such attribute: the third deploy (e3ebc72) logged
-# `GRADIO_HOT_RELOAD: Launching demo not found in __main__. Using 'demo'`, printed its
-# "Running on local URL" line, and then stopped the Node server and exited - RUNTIME_ERROR
-# with no traceback. The factory is kept so tests can build an independent app.
-#
-# This is the one module-level object this file is allowed to own. It is the app itself,
-# not shared state: nothing mutates it per session.
-demo = build_app()
+# Module level and named `demo`: the Space runner looks it up by that name (docs/HOSTING.md).
+# It is the app itself, not shared state; nothing mutates it per session.
+demo = build_blocks()
 
 if __name__ == "__main__":
     demo.launch()

src/japanese_avatar/telemetry/timings.py

@@ -0,0 +1,64 @@
+"""Per-request stage timing.
+
+MUST be instantiated per request. Gradio shares module-level mutables across every concurrent
+user session, so a module-level ``TurnTimings`` would leak one visitor's latency into another's
+directive. ``tests/test_directive.py::test_timings_are_per_request`` scans the package for exactly
+that mistake.
+
+Two ways to record a stage, both accumulating into the same record so the synthesiser (which
+``mark``s two stages it times itself) and the turn handler (which wraps its own stages in
+``stage``) produce one flat dict::
+
+    timings = TurnTimings()
+    synthesize(text, timings=timings)          # marks audio_query and synthesis
+    with timings.stage("timeline"):
+        ...
+    timings.as_dict()  # {"audio_query_ms": ..., "synthesis_ms": ..., "timeline_ms": ...,
+                       #  "server_total_ms": ...}
+
+``server_total_ms`` is measured from construction, so construct the record at the top of the
+request handler, not lazily inside it.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+class TurnTimings:
+    """Per-stage millisecond timings for a single turn. Session-scoped; never a global."""
+
+    def __init__(self) -> None:
+        self._stages: dict[str, float] = {}
+        self._t0 = time.perf_counter()
+
+    def mark(self, name: str, ms: float) -> None:
+        """Record ``ms`` for stage ``name``, accumulating if the stage repeats in one turn."""
+        self._stages[name] = self._stages.get(name, 0.0) + float(ms)
+
+    @contextmanager
+    def stage(self, name: str) -> Iterator[None]:
+        """Time the enclosed block as stage ``name``. Records even if the block raises."""
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            self.mark(name, (time.perf_counter() - start) * 1000.0)
+
+    @property
+    def stages(self) -> dict[str, float]:
+        """A copy of the raw per-stage milliseconds, keyed by bare stage name."""
+        return dict(self._stages)
+
+    def as_dict(self) -> dict[str, float]:
+        """The wire form: ``<stage>_ms`` per stage plus ``server_total_ms`` since construction.
+
+        A fresh dict every call, so a caller cannot mutate the turn's record after the fact.
+        Values are rounded to microseconds - nothing downstream can use finer resolution and the
+        directive is smaller for it.
+        """
+        out = {f"{name}_ms": round(ms, 3) for name, ms in self._stages.items()}
+        out["server_total_ms"] = round((time.perf_counter() - self._t0) * 1000.0, 3)
+        return out

src/japanese_avatar/ui/blocks.py

@@ -0,0 +1,269 @@
+"""The Phase 1 Blocks layout and the server side of the turn loop.
+
+Two rules govern this module and both come from how Gradio runs a Space:
+
+1. **No module-level mutable state.** Gradio shares module globals across every concurrent
+   visitor session. Every ``TurnTimings`` is constructed inside the request that owns it, and the
+   only module-level names are constants and functions.
+2. **Python sends one directive per utterance; the browser owns the clock.** ``turn`` returns the
+   audio, the finished viseme timeline and the per-stage timings in one message, and never drives
+   animation frame by frame.
+
+How the browser reaches ``turn``: the stage component is built with both server functions
+registered, and Gradio exposes each as an async method on the ``server`` object inside
+``js_on_load``. Gradio 6.22.0's bridge (verified in the compiled frontend, ``core-*.js``) packs a
+call's arguments into ONE JSON
+value - a lone argument is sent as itself, several are sent as a list, none as ``[]`` - and the
+route then calls the Python function with that single value as its only positional argument.
+So ``turn`` accepts a ``{"text", "speed"}`` dict from the browser as well as the plain
+``turn(text, speed=...)`` signature Python callers and tests use, and ``greeting`` tolerates a
+stray positional. A raised exception becomes an HTTP 500 that the Gradio client swallows into
+``undefined`` on the JS side, so every failure path here returns a structured ``{"error": ...}``
+instead of raising.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import uuid
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+
+from japanese_avatar.telemetry.timings import TurnTimings
+from japanese_avatar.ui.avatar_component import StatusLine, VrmStage
+from japanese_avatar.voice import tts
+from japanese_avatar.voice.models import AvatarDirective
+from japanese_avatar.voice.tts import CREDIT_STRING, synthesize
+from japanese_avatar.voice.visemes import build_timeline, timeline_to_dicts
+
+log = logging.getLogger(__name__)
+
+#: The repo checkout. blocks.py lives at src/japanese_avatar/ui/, three levels below it.
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+#: The fixed utterance behind "Say hello", so success criterion 2 ("the avatar speaks a Japanese
+#: utterance aloud") is reachable with one click and no typing.
+GREETING_TEXT = "こんにちは。日本語を練習しましょう。"
+
+#: A turn is one sentence, not an essay. Longer text is refused with a structured error rather
+#: than synthesised into a 30-second data URL.
+MAX_TEXT_CHARS = 200
+
+#: VOICEVOX's speedScale is a divisor on every phoneme length; outside this band the audio is
+#: unintelligible and the timeline degenerate. 0.75 is the "Slower" control's value.
+SPEED_MIN = 0.5
+SPEED_MAX = 2.0
+SLOWER_SPEED = 0.75
+
+VOICEVOX_TERMS_URL = "https://voicevox.hiroshiba.jp/term/"
+ZUNDAMON_TERMS_URL = "https://zunko.jp/con_ongen_kiyaku.html"
+VRM_TERMS_URL = "https://vrm.dev/licenses/1.0/"
+VRM_CREDIT = "VRM1_Constraint_Twist_Sample (c) 2022 pixiv Inc. - VRM Public License 1.0"
+
+# ----------------------------------------------------------------------------- server functions
+
+
+def _unpack(text: Any, speed: Any) -> tuple[Any, Any]:
+    """Normalise the three shapes a call can arrive in: dict payload, list payload, or plain."""
+    if isinstance(text, dict):
+        return text.get("text"), text.get("speed", speed)
+    if isinstance(text, list | tuple):
+        if len(text) == 0:
+            return None, speed
+        return text[0], text[1] if len(text) > 1 else speed
+    return text, speed
+
+
+def _validate(text: Any, speed: Any) -> tuple[str, float] | dict:
+    """Return ``(text, speed)`` cleaned, or an ``{"error": ...}`` dict the browser can render."""
+    if not isinstance(text, str) or not text.strip():
+        return {"error": "Type or say something in Japanese first."}
+    cleaned = text.strip()
+    if len(cleaned) > MAX_TEXT_CHARS:
+        return {"error": f"Keep it to {MAX_TEXT_CHARS} characters ({len(cleaned)} given)."}
+    try:
+        rate = float(speed)
+    except (TypeError, ValueError):
+        return {"error": f"speed must be a number, got {speed!r}"}
+    if not (SPEED_MIN <= rate <= SPEED_MAX):
+        return {"error": f"speed must be between {SPEED_MIN} and {SPEED_MAX}, got {rate}"}
+    return cleaned, rate
+
+
+def turn(text: Any, speed: float = 1.0) -> dict:
+    """One utterance: text in, ``AvatarDirective`` dict out, with per-stage timings.
+
+    Every stage is timed into a ``TurnTimings`` constructed here, for this request only. The
+    timeline is built from the ``AudioQuery`` that was actually synthesised at this ``speed`` -
+    never from a cached one - because ``speedScale`` divides every phoneme, pre/post silences
+    included, and a timeline reused across speeds drifts by exactly the speed ratio (Pitfall 5).
+    """
+    timings = TurnTimings()
+    text, speed = _unpack(text, speed)
+    checked = _validate(text, speed)
+    if isinstance(checked, dict):
+        return checked
+    cleaned, rate = checked
+
+    try:
+        result = synthesize(cleaned, speed=rate, timings=timings)
+        with timings.stage("timeline"):
+            timeline = timeline_to_dicts(build_timeline(result.audio_query))
+        with timings.stage("encode"):
+            audio_url = "data:audio/wav;base64," + base64.b64encode(result.wav_bytes).decode(
+                "ascii"
+            )
+    except Exception as exc:  # noqa: BLE001 - the bridge would turn a raise into `undefined`
+        log.exception("turn failed for %r at speed %s", cleaned, rate)
+        return {"error": f"synthesis failed: {exc}"}
+
+    return AvatarDirective(
+        turn_id=f"t-{uuid.uuid4().hex[:8]}",
+        audio_url=audio_url,
+        timeline=timeline,
+        subtitle=cleaned,
+        expression="neutral",
+        speed=rate,
+        timings=timings.as_dict(),
+    ).to_dict()
+
+
+def greeting(_payload: Any = None) -> dict:
+    """The "Say hello" utterance. ``_payload`` absorbs the ``[]`` the bridge sends for no args."""
+    return turn(GREETING_TEXT)
+
+
+def warm_synthesizer() -> None:
+    """Pay the synthesiser load before the first turn. Idempotent; logs the cost the first time.
+
+    Bound to ``demo.load`` rather than run at import: the Space imports this module to find the
+    module-level ``demo`` and must stay importable where the VOICEVOX wheel or its assets are
+    absent, so the load cost is paid on the first page load - concurrently with the visitor's
+    10 MiB VRM download, which takes several times longer.
+    """
+    timings = TurnTimings()
+    try:
+        seconds = tts.warmup(timings)
+    except Exception as exc:  # noqa: BLE001 - startup must not take the page down
+        log.warning("synthesizer warm-up failed; the first turn will report it: %s", exc)
+        return
+    if seconds > 0.01:
+        log.info("synthesizer warm-up took %.2f s", seconds)
+
+
+# ------------------------------------------------------------------------------------- layout
+
+# Every visitor-facing string below is deliberately honest about what this build does. It is a
+# public portfolio Space; an avatar that echoes must say it echoes.
+INTRO_HTML = (
+    '<div id="intro" class="intro">'
+    "<strong>Phase 1: the avatar repeats what you say. Tutoring arrives in Phase 3.</strong> "
+    "Type Japanese and press Enter, or hold the microphone button and speak. Everything you hear "
+    "is synthesised on the CPU with mora-timed lip-sync; speech recognition runs in your browser."
+    "</div>"
+)
+
+# Server-rendered so the first paint already carries it; the inner ids are what the host script
+# writes to, and the wrappers are Gradio's own elements that tests select by elem_id.
+TRANSCRIPT_HTML = '<div id="transcript-text" class="transcript" aria-live="polite"></div>'
+LATENCY_HTML = '<div id="latency-text" class="latency">dispatch→speech: —</div>'
+ASR_BADGE_HTML = (
+    '<div id="asr-tier-text" class="asr-badge">ASR: loads in your browser on the first push</div>'
+)
+
+# DPLY-04. The exact string VOICEVOX:ずんだもん, ASCII colon, no spaces - the form the character
+# terms give as their example - always visible, with no interaction. The VRM credit is voluntary
+# (creditNotation: unnecessary) and carried anyway. See docs/VOICEVOX-SETUP.md and docs/ASSETS.md.
+CREDITS_HTML = (
+    '<div id="credits-text" class="credits">'
+    f"Voice: {CREDIT_STRING} &middot; Avatar: {VRM_CREDIT}"
+    "</div>"
+)
+
+# The flow-down notice, adjacent to the replay control (software clause 3 / voice-model clause
+# 4): wherever synthesised audio is obtainable, downstream users are bound to the same terms.
+TERMS_NOTICE_HTML = (
+    '<div id="terms-notice-text" class="terms-notice">'
+    f"Synthesised audio is provided under the "
+    f'<a href="{VOICEVOX_TERMS_URL}" target="_blank" rel="noopener">VOICEVOX</a> and '
+    f'<a href="{ZUNDAMON_TERMS_URL}" target="_blank" rel="noopener">{CREDIT_STRING}</a> '
+    "terms of use; by using it you agree to comply with them."
+    "</div>"
+)
+
+# The 「アプリの紹介画面」 the character terms ask for: an about screen, findable with a little
+# looking, carrying the full credit set. Open on first load so it is on the introduction screen
+# rather than behind a click.
+ABOUT_MD = f"""\
+**Voice** - {CREDIT_STRING}. Speech is synthesised with
+[VOICEVOX CORE]({VOICEVOX_TERMS_URL}) (software terms) using the ずんだもん voice by SSS LLC
+([character terms]({ZUNDAMON_TERMS_URL})). The synthesised audio is provided under both sets of
+terms; by using it you agree to comply with them.
+
+**Avatar** - {VRM_CREDIT}. Source: the official VRM specification samples
+(`vrm-c/vrm-specification`). Terms: [VRM Public License 1.0]({VRM_TERMS_URL}); the file's embedded
+`VRMC_vrm.meta` grants redistribution, avatar use by everyone, modification and commercial use,
+and requires no credit.
+
+**Japanese text analysis** - Open JTalk dictionary `open_jtalk_dic_utf_8-1.11`, BSD-3-Clause,
+(c) 2009 Nara Institute of Science and Technology; Open JTalk itself is by the Nagoya Institute
+of Technology and the HTS Working Group, also under a modified BSD licence.
+
+**Runtime libraries** - [three.js](https://threejs.org/) (MIT),
+[@pixiv/three-vrm](https://github.com/pixiv/three-vrm) (MIT) and
+[@huggingface/transformers](https://github.com/huggingface/transformers.js) (Apache-2.0), loaded
+in your browser. Speech recognition (Whisper) runs entirely on your device.
+
+This is a Phase 1 preview: the avatar repeats what you type or say. There is no tutor yet.
+"""
+
+
+def build_blocks() -> gr.Blocks:
+    """Build the Blocks app. Importable and callable from tests without launching.
+
+    No Python event handlers are attached to the controls: every control is wired in the browser,
+    by ``avatar/host.js``, to the ``window.Avatar`` facade, and the only server traffic a turn
+    generates is the ``server_functions`` call to :func:`turn`. That is what keeps the whole loop
+    identical under both avatar transports.
+    """
+    # Serves avatar/ straight off disk, bypassing the Gradio cache, which is how the browser
+    # reaches avatar.js, host.js, stage.html and tutor.vrm. Deliberately one directory: every
+    # file under a listed path becomes network-reachable.
+    gr.set_static_paths([REPO_ROOT / "avatar"])
+
+    with gr.Blocks(title="Japanese Learning Avatar", fill_height=True) as blocks:
+        with gr.Row(equal_height=True):
+            with gr.Column(scale=3, min_width=320):
+                VrmStage(server_functions=[turn, greeting])
+            with gr.Column(scale=2, min_width=280):
+                StatusLine()
+                gr.HTML(value=INTRO_HTML, elem_id="intro-html")
+                gr.HTML(value=TRANSCRIPT_HTML, elem_id="transcript")
+                with gr.Row():
+                    gr.Button("Hold to talk", elem_id="ptt-button", variant="secondary")
+                    gr.Button("Say hello", elem_id="hello-button", variant="secondary")
+                gr.Textbox(
+                    value="",
+                    placeholder="日本語を入力して Enter",
+                    label="Type Japanese (the avatar says it back)",
+                    elem_id="text-input",
+                    lines=1,
+                    max_lines=1,
+                    submit_btn=False,
+                )
+                with gr.Row():
+                    gr.Button("Send", elem_id="send-button", variant="primary")
+                    gr.Button("Replay", elem_id="replay-button")
+                    gr.Button("Slower", elem_id="slower-button")
+                gr.HTML(value=TERMS_NOTICE_HTML, elem_id="terms-notice")
+                gr.HTML(value=LATENCY_HTML, elem_id="latency-line")
+                gr.HTML(value=ASR_BADGE_HTML, elem_id="asr-tier-badge")
+                gr.HTML(value=CREDITS_HTML, elem_id="credits")
+                with gr.Accordion("About and credits", open=True, elem_id="about-panel"):
+                    gr.Markdown(ABOUT_MD, elem_id="about-text")
+
+        blocks.load(warm_synthesizer, api_visibility="private")
+    return blocks

src/japanese_avatar/voice/models.py

@@ -1,10 +1,11 @@
 """Shared voice data types.
 
-Three of the four types here are frozen. The one that is not - :class:`TurnTimings` - must be
-**instantiated per request and never held at module level**. Gradio shares module-level objects
-across every concurrent user session, so a module-level ``TurnTimings`` would silently interleave
-one visitor's stage timings with another's. Every mutable field below uses ``default_factory`` for
-the same reason: a shared default dict is the same bug wearing a different hat.
+Every type here is frozen. The one mutable record in the voice path - :class:`TurnTimings` - now
+lives in :mod:`japanese_avatar.telemetry.timings` and is re-exported here so the synthesiser's
+``timings=`` parameter keeps its type. It must be **instantiated per request and never held at
+module level**: Gradio shares module-level objects across every concurrent user session, so a
+module-level ``TurnTimings`` would silently interleave one visitor's stage timings with
+another's.
 
 :class:`SynthResult` carries the ``AudioQuery`` as a **plain dict**, never a live
 ``voicevox_core`` object. That boundary conversion is what lets ``visemes.py`` (plan 01-06) be a
@@ -15,7 +16,11 @@ installed.
 from __future__ import annotations
 
 import json
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass
+
+from japanese_avatar.telemetry.timings import TurnTimings
+
+__all__ = ["FRAMERATE", "AvatarDirective", "SynthResult", "TurnTimings", "VisemeEvent"]
 
 #: Frame rate VOICEVOX quantises every phoneme to: 24000 Hz / 256 samples.
 #: Exposed here because the timeline builder and the fixtures must agree on it exactly.
@@ -54,30 +59,15 @@ class SynthResult:
     speed_scale: float
 
 
-@dataclass
-class TurnTimings:
-    """Per-stage millisecond timings for a single turn.
-
-    Session-scoped. NEVER a module-level global - Gradio shares those across all users.
-    """
-
-    stages: dict[str, float] = field(default_factory=dict)
-
-    def mark(self, name: str, ms: float) -> None:
-        """Record ``ms`` for stage ``name``, accumulating if the stage repeats in one turn."""
-        self.stages[name] = self.stages.get(name, 0.0) + float(ms)
-
-    def as_dict(self) -> dict[str, float]:
-        """A copy, so a caller cannot mutate the turn's record after the fact."""
-        return dict(self.stages)
-
-
 @dataclass(frozen=True)
 class AvatarDirective:
     """The single message Python sends the browser per utterance.
 
     The browser owns the clock from here on: it schedules ``timeline`` against
     ``AudioContext.currentTime``. Python never drives animation frame by frame.
+
+    ``timings`` is this turn's :class:`TurnTimings` record in wire form, so the browser can render
+    the per-stage breakdown next to its own dispatch-to-speech number without a second request.
     """
 
     turn_id: str
@@ -88,5 +78,9 @@ class AvatarDirective:
     speed: float
     timings: dict[str, float]
 
+    def to_dict(self) -> dict:
+        """The JSON-ready dict the gr.HTML server bridge returns to ``server.turn()``."""
+        return asdict(self)
+
     def to_json(self) -> str:
-        return json.dumps(asdict(self), ensure_ascii=False)
+        return json.dumps(self.to_dict(), ensure_ascii=False)

tests/test_directive.py

@@ -22,7 +22,6 @@ pytest.importorskip("voicevox_core")
 
 from japanese_avatar.telemetry.timings import TurnTimings  # noqa: E402
 from japanese_avatar.ui.blocks import GREETING_TEXT, MAX_TEXT_CHARS, greeting, turn  # noqa: E402
-
 from japanese_avatar.voice.models import AvatarDirective  # noqa: E402
 from japanese_avatar.voice.tts import wav_duration_seconds  # noqa: E402
 from japanese_avatar.voice.visemes import FRAMERATE, to_frame  # noqa: E402