feat(02-07): furigana controls, level picker, persistence; every transcript line rendered from tokens

- blocks.py: READING_CONTROLS_HTML (#furigana-mode + #level-select) above the
transcript, transcript.css linked from TRANSCRIPT_HTML, honest Phase 2 intro
- avatar_component.py: the boot template imports transcript.js and hands it to
bindHost(avatar, document, transcript), so both transports render identical ruby
- host.js: learnerLine/avatarLine through the renderer, every turn rendered from
the turn event's tokens, jla.furigana / jla.level persisted through the two
guarded storageRead/storageWrite helpers, furigana.* seeded on __debug
- test_transport_seam.py: the three-argument bind, one transcript.js import,
every-line rendering, the storage guard and the seeded debug keys

avatar/host.js

@@ -14,26 +14,78 @@
 // #latency-text, #asr-tier-text) rather than to the host's wrapper elements, so a
 // re-render of a wrapper cannot delete a line, and user-supplied text is always written
 // through textContent, never innerHTML.
+//
+// Plan 02-07: the transcript is rendered by the DOM-only transcript module the boot
+// template imports and hands over as the third argument. EVERY line goes through it:
+// the avatar's lines from the tokens the 'turn' event carries, the learner's lines echoed
+// at once as plain text and upgraded to ruby when analyze() answers (D-01, D-03). The two
+// reading controls (#furigana-mode, #level-select) drive its mode and level, and both
+// preferences persist in the browser under jla.furigana / jla.level (D-14), read and
+// written only through storageRead / storageWrite, which never throw - Safari inside a
+// cross-origin iframe throws on the access itself (research Pitfall 9), and the page
+// then runs in memory with furigana.storage reporting 'unavailable'.
 
 /** Matches REARM_TAIL_MS in mic.js: the controls re-enable when the mic may re-arm. */
 const REENABLE_AFTER_SPEECH_MS = 200;
 
+/** The persisted reading preferences (D-14). Phase 4 adopts the same keys into the account. */
+const STORAGE_MODE_KEY = 'jla.furigana';
+const STORAGE_LEVEL_KEY = 'jla.level';
+
+/** Seeded on __debug even without a transcript module, so the key set is timing-independent. */
+const FURIGANA_DEBUG_SEED = {
+  mode: 'always',
+  level: 'N5',
+  storage: 'unknown',
+  lines: 0,
+  rtTotal: 0,
+  lastLineId: null,
+  lastLineRt: 0,
+  lastLineKanjiRuns: 0,
+  lastLineRtHeightPx: 0,
+  lastLineHeightPx: 0,
+};
+
 /** Enter finishes a Japanese IME composition before it submits; this skips that Enter. */
 function isComposing(event) {
   return event.isComposing || event.keyCode === 229;
 }
 
+/**
+ * Read one persisted preference. Returns { ok, value }: ok is false when the storage
+ * itself is unreachable (the access throws), value is null when the key is unset.
+ */
+function storageRead(win, key) {
+  try {
+    return { ok: true, value: win.localStorage.getItem(key) };
+  } catch {
+    return { ok: false, value: null };
+  }
+}
+
+/** Write one persisted preference. Returns whether the storage accepted it. */
+function storageWrite(win, key, value) {
+  try {
+    win.localStorage.setItem(key, String(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {object}   avatar the facade window.Avatar
  * @param {Document} [doc]
+ * @param {object}   [transcriptModule] the transcript renderer's exports; null renders plain lines
  * @returns {boolean} whether the bindings were installed by this call
  */
-export function bindHost(avatar, doc = document) {
+export function bindHost(avatar, doc = document, transcriptModule = null) {
   if (!avatar || typeof avatar.on !== 'function') return false;
   // boot() is re-entrant and returns the live object; the bindings must not double up.
   if (doc.__avatarHostBound) return false;
   doc.__avatarHostBound = true;
 
+  const win = doc.defaultView || window;
   const byId = (id) => doc.getElementById(id);
   const text = (id, value) => {
     const el = byId(id);
@@ -49,6 +101,22 @@ export function bindHost(avatar, doc = document) {
     replay: byId('replay-button'),
     slower: byId('slower-button'),
   };
+  const reading = {
+    mode: byId('furigana-mode'),
+    level: byId('level-select'),
+  };
+
+  // The transcript renderer, when the boot template handed it over and the page has the
+  // element. Without it (a harness that loads host.js alone) lines fall back to plain text.
+  const transcriptEl = byId('transcript-text');
+  const transcript =
+    transcriptModule && typeof transcriptModule.createTranscript === 'function' && transcriptEl
+      ? transcriptModule.createTranscript(transcriptEl, { doc })
+      : null;
+  // The SAME object the renderer writes to, so getDebug() reads live numbers; the facade
+  // merges the turn loop's and the stage's keys over the top and leaves this one intact.
+  const furigana = transcript ? transcript.debug.furigana : { ...FURIGANA_DEBUG_SEED };
+  if (avatar.__debug) avatar.__debug.furigana = furigana;
 
   let spoken = false; // whether anything has been said yet, for replay/slower
   let busy = false;
@@ -71,8 +139,9 @@ export function bindHost(avatar, doc = document) {
     applyEnabled();
   }
 
+  /** The plain-text fallback used only when no transcript module was handed over. */
   function transcriptLine(who, value) {
-    const el = byId('transcript-text');
+    const el = transcriptEl;
     if (!el) return;
     const line = doc.createElement('div');
     line.className = `turn turn-${who}`;
@@ -87,6 +156,36 @@ export function bindHost(avatar, doc = document) {
     el.scrollTop = el.scrollHeight;
   }
 
+  /**
+   * The learner's line (D-03): echoed synchronously as plain text - the visitor sees their
+   * words the instant they send, before any round trip - then upgraded to ruby when the
+   * analyze() answer arrives. Fire and forget: it never delays the turn's dispatch, and a
+   * failed analysis leaves the plain line in place.
+   */
+  function learnerLine(value) {
+    if (!transcript) {
+      transcriptLine('you', value);
+      return;
+    }
+    const { lineId } = transcript.addLine({ who: 'you', text: value });
+    avatar
+      .analyze(value)
+      .then((result) => transcript.setTokens(lineId, result.tokens))
+      .catch(() => {
+        /* the plain echo stands; the turn loop has already reported the error */
+      });
+  }
+
+  /** The avatar's line, rendered from the tokens the directive carried (no second round trip). */
+  function avatarLine(who, value, tokens) {
+    if (!transcript) {
+      transcriptLine(who, value);
+      return;
+    }
+    const { lineId } = transcript.addLine({ who, text: value });
+    transcript.setTokens(lineId, Array.isArray(tokens) ? tokens : []);
+  }
+
   function renderLatency({ lastTurnMs, timings }) {
     const t = timings || {};
     const ms = (key) => (typeof t[key] === 'number' ? Math.round(t[key]) : '—');
@@ -121,7 +220,7 @@ export function bindHost(avatar, doc = document) {
       return;
     }
     // Echo before the round trip, so the visitor sees their words the instant they send.
-    transcriptLine('you', value);
+    learnerLine(value);
     if (el) {
       el.value = '';
       // The host's textbox mirrors its value from input events; a bare .value write
@@ -131,19 +230,60 @@ export function bindHost(avatar, doc = document) {
     dispatch(value);
   }
 
+  // ------------------------------------------------------------ reading preferences (D-14)
+  //
+  // Read at bind, validated against the renderer's own lists (junk is ignored), applied to
+  // the selects and the renderer, then written back so a first visit persists its
+  // defaults and the write path is exercised - which is what makes storage 'ok' mean
+  // "read AND write work". A change on either select re-renders every line client-side.
+  if (transcript) {
+    const modes = transcriptModule.FURIGANA_MODES || [];
+    const levels = transcriptModule.LEVELS || [];
+    const savedMode = storageRead(win, STORAGE_MODE_KEY);
+    const savedLevel = storageRead(win, STORAGE_LEVEL_KEY);
+    const mode = modes.includes(savedMode.value) ? savedMode.value : transcript.getMode();
+    const level = levels.includes(savedLevel.value) ? savedLevel.value : transcript.getLevel();
+    transcript.setMode(mode);
+    transcript.setLevel(level);
+    if (reading.mode) reading.mode.value = mode;
+    if (reading.level) reading.level.value = level;
+    const wrote =
+      storageWrite(win, STORAGE_MODE_KEY, mode) && storageWrite(win, STORAGE_LEVEL_KEY, level);
+    furigana.storage = savedMode.ok && savedLevel.ok && wrote ? 'ok' : 'unavailable';
+
+    if (reading.mode) {
+      reading.mode.addEventListener('change', () => {
+        const value = transcript.setMode(reading.mode.value);
+        reading.mode.value = value;
+        if (!storageWrite(win, STORAGE_MODE_KEY, value)) furigana.storage = 'unavailable';
+      });
+    }
+    if (reading.level) {
+      reading.level.addEventListener('change', () => {
+        const value = transcript.setLevel(reading.level.value);
+        reading.level.value = value;
+        if (!storageWrite(win, STORAGE_LEVEL_KEY, value)) furigana.storage = 'unavailable';
+      });
+    }
+    transcript.bindPointer(); // plan 02-08 fills this with the lookup popover's tap handling
+  }
+
   // ------------------------------------------------------------------- avatar -> page
   avatar.on('listening', ({ active } = {}) => status(active ? 'listening…' : 'transcribing…'));
   avatar.on('transcript', ({ text: heard } = {}) => {
     if (!heard) return;
-    transcriptLine('you', heard);
+    learnerLine(heard);
     dispatch(heard);
   });
   avatar.on('turn-start', () => {
     setBusy(true);
     status('thinking…');
   });
-  avatar.on('turn', ({ subtitle, speed, greeting } = {}) => {
-    if (subtitle && (greeting || speed < 1)) transcriptLine(speed < 1 ? 'slower' : 'avatar', subtitle);
+  // EVERY avatar line is rendered from the turn event's tokens (plan 02-07). Phase 1 skipped
+  // the echo of a typed line because it repeated the learner; with furigana the avatar's
+  // reading of the same words is the point.
+  avatar.on('turn', ({ subtitle, speed, tokens } = {}) => {
+    if (subtitle) avatarLine(speed < 1 ? 'slower' : 'avatar', subtitle, tokens);
     spoken = true;
   });
   avatar.on('speech-start', () => {
@@ -168,7 +308,8 @@ export function bindHost(avatar, doc = document) {
   // gesture's own call stack - the only place a gesture-gated browser (iOS Safari;
   // Chromium in a cross-origin embed) lets an AudioContext resume. The turn loop makes
   // the same call at its entry points; this copy covers the gestures that never reach
-  // the loop (Send with an empty box, Enter mid-composition) and the ones that do.
+  // the loop (Send with an empty box, Enter mid-composition) and the ones that do. The
+  // two reading selects above are deliberately NOT in this set: no audio path starts there.
   if (controls.send) {
     controls.send.addEventListener('click', () => {
       avatar.unlockAudio();

src/japanese_avatar/ui/avatar_component.py

@@ -62,7 +62,10 @@ _BOOT_JS = """
         // The host glue: binds the page's controls to the facade and renders what it
         // reports. Loaded here, after boot, from the SAME template for both transports.
         const host = await import('/gradio_api/file=avatar/host.js');
-        host.bindHost(avatar, document);
+        // transcript.js is DOM rendering handed to the host glue; loaded from this one
+        // template so both transports render identical ruby (plan 02-07).
+        const transcript = await import('/gradio_api/file=avatar/transcript.js');
+        host.bindHost(avatar, document, transcript);
         watch('value', () => m.onDirective(props.value));
     }})().catch((err) => {{
         console.error('avatar boot failed:', err);

src/japanese_avatar/ui/blocks.py

@@ -343,15 +343,40 @@ def warm_language_on_load() -> None:
 # 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> "
+    "<strong>Phase 2: the avatar repeats what you say, now with furigana, word lookup and "
+    "translation. 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>"
 )
 
+# Plan 02-07. The reading controls (D-02 / D-14): a three-way furigana mode and an N5-N2 level
+# picker. Project-owned <select> elements inside a gr.HTML value rather than gr.Radio /
+# gr.Dropdown, for the Phase 1 reason: avatar/host.js binds by element id and never depends on
+# Gradio's own DOM or event routing, and a mode change is a client-side re-render with no server
+# call. Server-rendered so the first paint already carries them, like StatusLine. The defaults
+# are D-01's first visit: every kanji annotated, level N5.
+READING_CONTROLS_HTML = (
+    '<div id="reading-controls" class="reading-controls">'
+    '<label for="furigana-mode">Furigana</label>'
+    '<select id="furigana-mode" aria-label="Furigana mode">'
+    '<option value="always" selected>always</option><option value="above">above my level</option>'
+    '<option value="never">never</option></select>'
+    '<label for="level-select">My level</label>'
+    '<select id="level-select" aria-label="JLPT level">'
+    '<option value="N5" selected>N5</option><option value="N4">N4</option>'
+    '<option value="N3">N3</option><option value="N2">N2</option></select>'
+    "</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>'
+# writes to, and the wrappers are Gradio's own elements that tests select by elem_id. The
+# stylesheet link rides inside the same value: avatar/ is a static path, so the browser fetches
+# transcript.css from the app itself (the ruby rules the browser suites measure - plan 02-07).
+TRANSCRIPT_HTML = (
+    '<link rel="stylesheet" href="/gradio_api/file=avatar/transcript.css">'
+    '<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>'
@@ -425,6 +450,7 @@ def build_blocks() -> gr.Blocks:
             with gr.Column(scale=2, min_width=280):
                 StatusLine()
                 gr.HTML(value=INTRO_HTML, elem_id="intro-html")
+                gr.HTML(value=READING_CONTROLS_HTML, elem_id="reading-controls-html")
                 gr.HTML(value=TRANSCRIPT_HTML, elem_id="transcript")
                 with gr.Row():
                     gr.Button("Hold to talk", elem_id="ptt-button", variant="secondary")

tests/test_transport_seam.py

@@ -366,7 +366,12 @@ def test_host_glue_is_neither_a_transport_nor_the_turn_loop():
     assert component.count(f"import('/gradio_api/file=avatar/{HOST}')") == 1, (
         "the shared boot template must load host.js exactly once, for both transports"
     )
-    assert "bindHost(avatar, document)" in component
+    # Plan 02-07: the transcript renderer is the third argument, loaded from the same
+    # template exactly once so both transports render identical ruby.
+    assert component.count(f"import('/gradio_api/file=avatar/{TRANSCRIPT}')") == 1, (
+        "the shared boot template must load transcript.js exactly once, for both transports"
+    )
+    assert "bindHost(avatar, document, transcript)" in component
 
 
 # ------------------------------------------------------------------ plan 01-11: audio unlock
@@ -580,3 +585,46 @@ def test_transcript_uses_ruby_not_parentheses():
     assert "createElement('ruby')" in s or 'createElement("ruby")' in s
     assert "createElement('rt')" in s or 'createElement("rt")' in s
     assert "'rp'" not in s and '"rp"' not in s, "no <rp>: it would leak into textContent"
+
+
+# host.js's side of the transcript (plan 02-07): every avatar line rendered from the turn
+# event's tokens, the reading preferences persisted through exactly two guarded helpers, and
+# the furigana numbers seeded on __debug so getDebug() carries them from the first read.
+
+
+def test_host_renders_every_avatar_line():
+    """Phase 1 rendered only greeting / slower lines (the echo repeated the learner). With
+    furigana the avatar's reading of the same words is the point: every turn renders."""
+    host = src(HOST)
+    assert host.count("setTokens(") >= 2, "learner AND avatar lines must go through setTokens"
+    assert "greeting || speed < 1" not in host, "the Phase 1 skip-the-echo condition survives"
+    assert "createTranscript(" in host
+    assert ".analyze(" in host, "learner lines are tokenised through Avatar.analyze()"
+
+
+def test_host_persists_reading_prefs():
+    """Both keys are written and read, and the storage is touched ONLY inside the two
+    helpers - each wrapped in try - because Safari in a cross-origin iframe throws on the
+    access itself (research Pitfall 9) and an unguarded read would take the whole host down."""
+    host = src(HOST)
+    assert host.count("jla.furigana") >= 1 and host.count("jla.level") >= 1
+    assert "STORAGE_MODE_KEY" in host and "STORAGE_LEVEL_KEY" in host
+    remainder = host
+    for signature in ("function storageRead(", "function storageWrite("):
+        body = "\n".join(_function_body(host, signature))
+        assert "try" in body, f"{signature} has no try around the storage access"
+        assert "localStorage" in body, f"{signature} does not touch localStorage"
+        remainder = remainder.replace(body, "")
+    assert "localStorage" not in remainder, (
+        "localStorage is accessed outside storageRead / storageWrite in host.js"
+    )
+    assert "'unavailable'" in host and "'ok'" in host, "furigana.storage must publish both states"
+
+
+def test_host_seeds_language_debug():
+    """furigana.* is on __debug from bind, with or without a transcript module, so the
+    parity suite's key-set comparison never depends on timing."""
+    host = src(HOST)
+    assert "__debug.furigana" in host
+    for key in ("lastLineRt", "lastLineRtHeightPx", "lastLineHeightPx", "storage", "rtTotal"):
+        assert f"{key}:" in host, f"host.js does not seed furigana.{key}"