feat(02-09): inline EN reveal with per-line cache, loading and error states, at three layers

- transcript.js: an EN control and a hidden .en div on EVERY line (D-18), the
idle/loading/shown/collapsed/error state machine in setTranslation(), the
onTranslateRequest hook, and debug.translation {requests, cacheHits, lastMs,
lastState, lastLineId, lastError, states}
- host.js: the decision and the money - a per-line session Map (D-17) in front of the
single avatar.translate() call, collapse on a second tap, cache hit on a third, and
a {error} rendered under the line with the control left usable
- transcript.css: the control as an inline chip that outranks the theme's button rules,
and .en[hidden] so a framework display:block cannot make "never shown unrequested" false
- transcript-harness.html: a fake 60 ms translator, __translationDebug, __failTranslation
- seam: test_translation_cache_lives_in_the_host (one call site, the Map in the host, no
translate() and no third Map in the renderer); .analyze( and .translate( added to the
host's required call list
- standalone: test_en_control_state_machine, the sequence recorded by a MutationObserver
- both transports: test_translation_reveal_under_both_transports - a cached re-show with
the request counter recording []
- deployed: test_translation_reveal, plus the over-long {error} contract

avatar/host.js

@@ -29,6 +29,14 @@
 // the renderer's bindPointer once and publishes transcript.debug.popover on __debug. The
 // lookup itself is a pure client action: the glosses ride inside the tokens the line
 // already holds, so a tap issues no request under either transport.
+//
+// Plan 02-09: the EN reveal is the other way round. The renderer owns the control and its
+// states; THIS file owns the decision and the money - the per-line session cache (D-17) is
+// a Map right here, and the facade's translate() is called from exactly one place in the
+// whole codebase. A tap on a line that has already been translated therefore cannot reach the
+// network by any path, which is the claim the deployed request counter checks. The cache
+// is per page load and per line id: nothing is persisted (D-17 says session only), and a
+// line id is never reused, so a stale entry is not a state this can reach.
 
 /** Matches REARM_TAIL_MS in mic.js: the controls re-enable when the mic may re-arm. */
 const REENABLE_AFTER_SPEECH_MS = 200;
@@ -68,6 +76,17 @@ const POPOVER_DEBUG_SEED = {
   closeCount: 0,
 };
 
+/** The EN reveal's numbers (plan 02-09), seeded for the same reason. */
+const TRANSLATION_DEBUG_SEED = {
+  requests: 0,
+  cacheHits: 0,
+  lastMs: null,
+  lastState: 'idle',
+  lastLineId: null,
+  lastError: null,
+  states: {},
+};
+
 /** Enter finishes a Japanese IME composition before it submits; this skips that Enter. */
 function isComposing(event) {
   return event.isComposing || event.keyCode === 229;
@@ -139,9 +158,11 @@ export function bindHost(avatar, doc = document, transcriptModule = null) {
   // 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 };
   const popover = transcript ? transcript.debug.popover : { ...POPOVER_DEBUG_SEED };
+  const translation = transcript ? transcript.debug.translation : { ...TRANSLATION_DEBUG_SEED };
   if (avatar.__debug) {
     avatar.__debug.furigana = furigana;
     avatar.__debug.popover = popover;
+    avatar.__debug.translation = translation;
   }
 
   let spoken = false; // whether anything has been said yet, for replay/slower
@@ -294,6 +315,46 @@ export function bindHost(avatar, doc = document, transcriptModule = null) {
     // Plan 02-08: the tap wiring for the lookup card lives in the renderer, so the page and
     // the standalone harness install exactly the same handlers. Called once, at bind.
     transcript.bindPointer();
+
+    // ------------------------------------------------------------- the EN reveal (02-09)
+    //
+    // D-16: never shown unrequested, collapsed again on a second tap. D-17: cached per
+    // line, in the browser, for the session only. The three branches below are the whole
+    // policy, and the ONLY one of them that can reach the network is the third.
+    //
+    // A failed translation is reported under the line rather than in the status strip: it
+    // belongs to the line it failed for, and it leaves the control enabled so the learner
+    // can simply tap again. There is no unlockAudio() here - no audio path starts on this
+    // button, and calling it would make every EN tap look like a gesture that wanted sound.
+    const translations = new Map(); // lineId -> { text, ms }
+    transcript.onTranslateRequest = (lineId, text, state) => {
+      if (state === 'shown') {
+        transcript.setTranslation(lineId, 'collapsed');
+        return;
+      }
+      const cached = translations.get(lineId);
+      if (cached) {
+        translation.cacheHits += 1;
+        transcript.setTranslation(lineId, 'shown', cached.text);
+        return;
+      }
+      translation.requests += 1;
+      transcript.setTranslation(lineId, 'loading');
+      // The ONE network call the whole reveal can make, kept on one line so the seam test
+      // and the plan's acceptance grep are looking at the CALL and not at a comment above it.
+      avatar.translate(text, lineId)
+        .then((result) => {
+          translations.set(lineId, { text: result.text, ms: result.ms });
+          translation.lastMs = result.ms;
+          translation.lastError = null;
+          transcript.setTranslation(lineId, 'shown', result.text);
+        })
+        .catch((err) => {
+          const message = String(err?.message ?? err);
+          translation.lastError = message;
+          transcript.setTranslation(lineId, 'error', `translation failed: ${message}`);
+        });
+    };
   }
 
   // ------------------------------------------------------------------- avatar -> page

avatar/transcript-harness.html

@@ -70,8 +70,34 @@
       // The same objects the renderer writes to, not copies: a test reads live numbers.
       window.__transcriptDebug = t.debug.furigana;
       window.__popoverDebug = t.debug.popover;
+      window.__translationDebug = t.debug.translation;
       window.__transcriptReady = false;
 
+      // A FAKE translator (plan 02-09). The per-line cache lives in host.js, not here, so
+      // this harness deliberately models only the state machine: every request costs the
+      // same 60 ms and returns '[EN] ' + the line, which is why a third tap here shows the
+      // loading state again where the real page shows a cache hit. What it proves is the
+      // part that belongs to the renderer - loading -> shown -> collapsed -> shown - with
+      // no server, no host framework and no network at all.
+      window.__translateDelayMs = 60;
+      window.__translateCalls = [];
+      t.onTranslateRequest = (lineId, text, state) => {
+        window.__translateCalls.push({ lineId, text, state });
+        if (state === 'shown') {
+          t.setTranslation(lineId, 'collapsed');
+          return;
+        }
+        t.setTranslation(lineId, 'loading');
+        setTimeout(
+          () => t.setTranslation(lineId, 'shown', `[EN] ${text}`),
+          window.__translateDelayMs
+        );
+      };
+      // The error state has no path through the real page's control (the server refuses a
+      // line before it is ever rendered), so the harness is where it is exercised.
+      window.__failTranslation = (lineId, message) =>
+        t.setTranslation(lineId, 'error', `translation failed: ${message}`);
+
       document.getElementById('furigana-mode').addEventListener('change', (e) => {
         t.setMode(e.target.value);
       });

avatar/transcript.css

@@ -66,6 +66,52 @@
   border-bottom-color: #c62828;
 }
 
+/* ------------------------------------------------- the EN reveal (plan 02-09, D-15/D-16)
+ *
+ * Every selector is prefixed with #transcript-text on purpose. The control is a real
+ * <button> living inside a gr.HTML value, so Gradio's own stylesheet has an opinion about
+ * it (full width, its own font, its own padding); an id + class selector outranks the
+ * theme's class selectors, and the resets below are what keep the control an inline chip
+ * beside the sentence rather than a block that pushes the line apart. The [hidden] rule is
+ * there for the same reason: a framework `div { display: block }` beats the UA's
+ * [hidden] { display: none }, and a translation that is "hidden" but visible would make
+ * "never shown unrequested" (D-16) false while every attribute still read correctly.
+ */
+#transcript-text .en-toggle {
+  font-size: 0.75em;
+  margin-left: 0.4em;
+  padding: 0 0.4em;
+  vertical-align: middle;
+  display: inline;
+  width: auto;
+  min-width: 0;
+  min-height: 0;
+  border: 1px solid rgba(0, 0, 0, 0.3);
+  border-radius: 3px;
+  background: transparent;
+  color: inherit;
+  font-family: inherit;
+  line-height: 1.6;
+  cursor: pointer;
+}
+#transcript-text .en-toggle[aria-busy="true"] {
+  opacity: 0.6;
+}
+#transcript-text .en-toggle:disabled {
+  cursor: default;
+}
+#transcript-text .en {
+  margin: 0.1em 0 0.4em 1.5em;
+  color: #333;
+  font-size: 0.92em;
+}
+#transcript-text .en[hidden] {
+  display: none;
+}
+#transcript-text .en.en-error {
+  color: #b00020;
+}
+
 /* ---------------------------------------------- the lookup card (plan 02-08, research Q6)
  *
  * A positioned div, not the Popover API: iOS 16 Safari lacks it and its top-layer behaviour

avatar/transcript.js

@@ -15,7 +15,15 @@
 // data with no round trip (D-14), and a tap on a word (plan 02-08) reads its reading, its
 // dictionary form, its level and its JMdict glosses straight out of the record the line
 // already holds - the lookup issues no request of any kind (D-05 / D-07, research § Q3).
-// Plan 02-09 adds the translation reveal under each line.
+//
+// Plan 02-09 adds the translation reveal under each line (D-15 / D-16 / D-18): every line,
+// the learner's as much as the avatar's, carries an EN control and a hidden `.en` div, and
+// setTranslation() is the whole state machine - idle / loading / shown / collapsed / error,
+// each one a set of attributes a test can read. This module NEVER translates: the button's
+// click calls the onTranslateRequest hook and stops there, so the network call and the
+// per-line session cache (D-17) have exactly one owner, host.js. That division is what
+// makes "a re-show costs zero requests" a fact the request counter can check rather than a
+// claim about where a Map happens to live.
 //
 // The card is a positioned <div>, not the Popover API: iOS 16 Safari is still in the field
 // without it and its top-layer behaviour inside the Hub's cross-origin frame is unverified
@@ -48,6 +56,15 @@ const LEVEL_LABELS = { 'N1+': 'N1+ / beyond lists', name: 'name' };
 /** D-07: the card shows the first two or three senses, English glosses only. */
 const MAX_SENSES = 3;
 
+/**
+ * The EN control's states (plan 02-09). `collapsed` differs from `idle` only in that the
+ * `.en` div still holds its text: a third tap re-shows it without asking anyone.
+ */
+export const TRANSLATION_STATES = ['idle', 'loading', 'shown', 'collapsed', 'error'];
+/** The button's label. The ellipsis is the loading state a learner sees (D-15). */
+const EN_LABEL = 'EN';
+const EN_LOADING_LABEL = 'EN…';
+
 /** The gap between the tapped word and the card, and the inset from the column's edges. */
 const ANCHOR_GAP_PX = 6;
 const EDGE_INSET_PX = 8;
@@ -123,9 +140,23 @@ export function createTranscript(container, { doc = document } = {}) {
       openCount: 0,
       closeCount: 0,
     },
+    // The EN reveal's numbers (plan 02-09). `requests` and `cacheHits` are written by the
+    // host - they are facts about the network, which this module never touches - while
+    // `lastState` / `states` are written here, by the state machine itself. A test that
+    // wants "shown from the cache" reads cacheHits AND states[lineId], and the two can
+    // only agree if the host asked for the state the cache says it served.
+    translation: {
+      requests: 0,
+      cacheHits: 0,
+      lastMs: null,
+      lastState: 'idle',
+      lastLineId: null,
+      lastError: null,
+      states: {},
+    },
   };
 
-  /** lineId -> { el, said, who, text } in insertion order. */
+  /** lineId -> { el, said, toggle, en, who, text } in insertion order. */
   const lines = new Map();
   /** lineId -> the retained token records, so a re-render is pure. */
   const tokensByLine = new Map();
@@ -213,6 +244,10 @@ export function createTranscript(container, { doc = document } = {}) {
    * Append a line as plain text; tokens arrive through setTokens (immediately for the
    * avatar's lines, after the analyze round trip for the learner's).
    *
+   * The EN control and its empty `.en` div are built here, for EVERY line - the learner's
+   * as much as the avatar's (D-18) - so "does this line have a translation control" is a
+   * structural fact rather than a decision taken per speaker somewhere else.
+   *
    * @param {{who: 'you'|'avatar'|'slower', text: string}} line
    * @returns {{lineId: string, el: Element}}
    */
@@ -229,10 +264,31 @@ export function createTranscript(container, { doc = document } = {}) {
     const said = doc.createElement('span');
     said.className = 'said';
     said.textContent = String(text ?? '');
-    el.append(label, said);
+
+    // <button type="button" class="en-toggle" data-line="L1" aria-expanded="false"
+    //         aria-busy="false" aria-controls="en-L1">EN</button>
+    // <div class="en" id="en-L1" data-line="L1" hidden></div>
+    const toggle = doc.createElement('button');
+    toggle.type = 'button';
+    toggle.className = 'en-toggle';
+    toggle.dataset.line = lineId;
+    toggle.textContent = EN_LABEL;
+    toggle.setAttribute('aria-expanded', 'false');
+    toggle.setAttribute('aria-busy', 'false');
+    toggle.setAttribute('aria-controls', `en-${lineId}`);
+    toggle.title = 'Show the English translation of this line';
+    const en = doc.createElement('div');
+    en.className = 'en';
+    en.id = `en-${lineId}`;
+    en.dataset.line = lineId;
+    en.hidden = true;
+    toggle.addEventListener('click', () => requestTranslation(lineId));
+
+    el.append(label, said, toggle, en);
     container.append(el);
     container.scrollTop = container.scrollHeight;
-    lines.set(lineId, { el, said, who, text: String(text ?? '') });
+    lines.set(lineId, { el, said, toggle, en, who, text: String(text ?? '') });
+    debug.translation.states[lineId] = 'idle';
     measure(lineId);
     return { lineId, el };
   }
@@ -465,6 +521,66 @@ export function createTranscript(container, { doc = document } = {}) {
     return true;
   }
 
+  // -------------------------------------------------------- the EN reveal (02-09, D-15/16)
+
+  const translation = debug.translation;
+  /** The host's handler; see requestTranslation. Null until someone installs one. */
+  let onTranslateRequest = null;
+
+  /**
+   * The button's whole behaviour: report the tap and stop.
+   *
+   * Deliberately not "translate this line": the hook is handed the line's id, its text and
+   * its CURRENT state, and the decision - collapse, serve from the session cache, or spend
+   * a round trip - belongs to whoever installed it. That is why this file contains no
+   * cache and no network call, and why the deployed row can prove a re-show is free.
+   */
+  function requestTranslation(lineId) {
+    const line = lines.get(lineId);
+    if (!line || typeof onTranslateRequest !== 'function') return false;
+    onTranslateRequest(lineId, line.text, translation.states[lineId] ?? 'idle');
+    return true;
+  }
+
+  /**
+   * Move one line's EN control into a state and publish it.
+   *
+   * The `.en` text is written on `shown` and `error` only, so `collapsed` keeps what was
+   * already fetched and a re-show needs nothing from anyone. Every visible consequence is
+   * an attribute (`aria-busy`, `aria-expanded`, `disabled`) rather than a class, so the
+   * loading state a learner waits through is legible to a screen reader and to a test.
+   *
+   * @param {string} lineId
+   * @param {'idle'|'loading'|'shown'|'collapsed'|'error'} state
+   * @param {string} [text] the English (shown) or the message (error)
+   * @returns {boolean} whether the line and the state both exist
+   */
+  function setTranslation(lineId, state, text = '') {
+    const line = lines.get(lineId);
+    if (!line || !TRANSLATION_STATES.includes(state)) return false;
+    const loading = state === 'loading';
+    const shown = state === 'shown';
+    const error = state === 'error';
+
+    line.toggle.textContent = loading ? EN_LOADING_LABEL : EN_LABEL;
+    line.toggle.disabled = loading;
+    line.toggle.setAttribute('aria-busy', loading ? 'true' : 'false');
+    line.toggle.setAttribute('aria-expanded', shown ? 'true' : 'false');
+    if (shown || error) line.en.textContent = String(text ?? '');
+    line.en.classList.toggle('en-error', error);
+    line.en.hidden = !(shown || error);
+
+    translation.states[lineId] = state;
+    translation.lastState = state;
+    translation.lastLineId = lineId;
+    return true;
+  }
+
+  /** The line's current EN state, for a host that would rather ask than remember. */
+  function getTranslationState(lineId) {
+    return translation.states[lineId] ?? null;
+  }
+
   function setMode(value) {
     if (!FURIGANA_MODES.includes(value)) return mode;
     closePopover(); // Pitfall 10: a re-render replaces the .tok the card is anchored to
@@ -494,6 +610,16 @@ export function createTranscript(container, { doc = document } = {}) {
     openPopover,
     closePopover,
     bindPointer,
+    setTranslation,
+    getTranslationState,
+    // A property, not a method, so the host reads `transcript.onTranslateRequest = fn`
+    // exactly as it would an event handler; anything that is not a function clears it.
+    get onTranslateRequest() {
+      return onTranslateRequest;
+    },
+    set onTranslateRequest(fn) {
+      onTranslateRequest = typeof fn === 'function' ? fn : null;
+    },
     debug,
   };
 }

tests/e2e/test_avatar_loop.py

@@ -1675,3 +1675,176 @@ def test_lookup_popover_mobile(
         assert page.locator("#lookup-popover").is_visible() is False
     finally:
         context.close()
+
+
+# ------------------------------------------------------- the EN translation reveal (02-09)
+#
+# JPN-04 on the page. The parity layer already proved the state machine and the cache under
+# both transports against a local app; this row is the same sequence against the Space, and
+# it adds the number a learner actually feels - the wall time from the tap to the English
+# being on screen, which on the Space's CPU is a translation plus a Gradio round trip and is
+# the whole reason D-15 demands a loading state. It is PRINTED, never asserted against a
+# threshold: docs/LATENCY.md § Translation is where the deployed number is recorded, by
+# test_measure_translation, and a budget here would be measuring the fleet, not the feature.
+
+TRANSLATE_TEXT = "駅はどこですか。"
+TRANSLATE_EXPECT = "station"
+TRANSLATION_BOUND = (
+    "() => !!(window.Avatar && window.Avatar.__debug && window.Avatar.__debug.translation)"
+)
+TRANSLATION = """
+async () => {
+  const d = await window.Avatar.getDebug();
+  return d.translation ? JSON.parse(JSON.stringify(d.translation)) : null;
+}
+"""
+AVATAR_EN_TOGGLE = "() => !!document.querySelector('#transcript-text .turn-avatar .en-toggle')"
+# Installed before the click, so the loading state is RECORDED rather than sampled: a poll
+# that missed a fast round trip would be indistinguishable from a control that never showed
+# a loading state at all, which is the one thing D-15 asks for by name.
+OBSERVE_TOGGLE = """
+(lineId) => {
+  const btn = document.querySelector(`.en-toggle[data-line="${lineId}"]`);
+  if (!btn) return false;
+  window.__enSeq = [];
+  const record = () => window.__enSeq.push({
+    busy: btn.getAttribute('aria-busy'),
+    expanded: btn.getAttribute('aria-expanded'),
+    text: btn.textContent,
+    disabled: btn.disabled,
+  });
+  record();
+  new MutationObserver(record).observe(btn, {
+    attributes: true, childList: true, subtree: true, characterData: true,
+  });
+  return true;
+}
+"""
+EN_SEQUENCE = "() => window.__enSeq || []"
+EXPANDED = """
+(id) => {
+  const btn = document.querySelector(`.en-toggle[data-line="${id}"]`);
+  return !!btn && btn.getAttribute('aria-expanded') === 'true';
+}
+"""
+REJECT_TRANSLATE = """
+async ([text, lineId]) => {
+  try {
+    await window.Avatar.translate(text, lineId);
+    return null;
+  } catch (err) {
+    return String((err && err.message) || err);
+  }
+}
+"""
+OVERLONG_CHARS = 201
+TRANSLATE_TIMEOUT_MS = 120_000
+
+
+def _translation(page) -> dict:
+    return page.evaluate(TRANSLATION)
+
+
+def _en_toggle(page, line_id: str):
+    return page.locator(f"#transcript-text .en-toggle[data-line='{line_id}']")
+
+
+@pytest.mark.deployed
+def test_translation_reveal(
+    page, space_url, warm_space, speech_events, request_counter, wait_for_avatar_ready
+):
+    """JPN-04 / D-15 / D-16 / D-17 / D-18: on the deployed page, an EN control under every
+    line reveals the English inline after a loading state, collapses on a second tap, and
+    re-shows from the browser's session cache with zero network requests on a third.
+
+    The over-long line at the end is the ``{error}`` contract the UI's error state is built
+    on: the page's own control can never send one (the line is refused before it exists), so
+    the rejection is exercised through the facade here and the rendered error state is proven
+    in the standalone harness instead.
+    """
+    speech_events.install(page)
+    wait_for_avatar_ready(page, space_url)
+    page.wait_for_function(TRANSLATION_BOUND, timeout=READY_TIMEOUT_MS)
+    seeded = _translation(page)
+    assert seeded["requests"] == 0 and seeded["cacheHits"] == 0 and seeded["states"] == {}
+
+    submitted = time.monotonic()
+    _submit_text(page, TRANSLATE_TEXT)
+    wait_for_ruby(page, AVATAR_EN_TOGGLE, TRANSLATE_TIMEOUT_MS, "the avatar's line never arrived")
+    line_ms = round((time.monotonic() - submitted) * 1000)
+    _controls_rearmed(page, timeout_ms=TRANSLATE_TIMEOUT_MS)
+
+    avatar_line = page.locator("#transcript-text .turn-avatar").last
+    learner_line = page.locator("#transcript-text .turn-you").last
+    avatar_id = avatar_line.get_attribute("data-line")
+    learner_id = learner_line.get_attribute("data-line")
+    assert avatar_line.locator(".en-toggle").count() == 1
+    assert learner_line.locator(".en-toggle").count() == 1, "D-18: the learner's line too"
+    assert page.locator(f"#en-{avatar_id}").is_visible() is False, "D-16: never unrequested"
+
+    # 1. The tap a learner makes, timed from the click to the English being on screen.
+    assert page.evaluate(OBSERVE_TOGGLE, avatar_id) is True
+    tapped = time.monotonic()
+    _en_toggle(page, avatar_id).click()
+    page.wait_for_function(EXPANDED, arg=avatar_id, timeout=TRANSLATE_TIMEOUT_MS)
+    click_to_shown_ms = round((time.monotonic() - tapped) * 1000)
+    sequence = page.evaluate(EN_SEQUENCE)
+    shown = _translation(page)
+    english = page.locator(f"#en-{avatar_id}").text_content()
+    print(
+        f"\n[deployed] {TRANSLATE_TEXT} -> the avatar's line {line_ms} ms after Enter\n"
+        f"[deployed] tap EN -> {english!r} in {click_to_shown_ms} ms "
+        f"(the page's own lastMs {shown['lastMs']} ms)\n"
+        f"[deployed] the control's sequence: {sequence}\n[deployed] translation: {shown}"
+    )
+    assert any(f["busy"] == "true" for f in sequence), (
+        f"no loading state was ever visible - D-15 requires one: {sequence}"
+    )
+    assert any(f["text"] == "EN…" and f["disabled"] for f in sequence), sequence
+    assert shown["requests"] == 1 and shown["cacheHits"] == 0
+    assert shown["lastMs"] > 0 and shown["lastError"] is None
+    assert shown["states"][avatar_id] == "shown"
+    assert page.locator(f"#en-{avatar_id}").is_visible() is True
+    assert TRANSLATE_EXPECT in english.lower(), english
+
+    # 2. Collapse (D-16), without spending a translation.
+    _en_toggle(page, avatar_id).click()
+    collapsed = _translation(page)
+    assert collapsed["states"][avatar_id] == "collapsed" and collapsed["requests"] == 1
+    assert page.locator(f"#en-{avatar_id}").is_visible() is False
+
+    # 3. The cached re-show (D-17): instant, and provably free.
+    with request_counter(page) as seen:
+        re_tapped = time.monotonic()
+        _en_toggle(page, avatar_id).click()
+        page.wait_for_function(EXPANDED, arg=avatar_id, timeout=10_000)
+        cached_ms = round((time.monotonic() - re_tapped) * 1000)
+        during = list(seen)
+    cached = _translation(page)
+    print(f"[deployed] cached re-show in {cached_ms} ms; requests during it: {during}; {cached}")
+    assert during == [], (
+        f"a cached re-show issued {len(during)} request(s); host.js's per-line Map is "
+        f"supposed to answer it without the network: {during}"
+    )
+    assert cached["cacheHits"] == 1 and cached["requests"] == 1
+    assert page.locator(f"#en-{avatar_id}").text_content() == english
+
+    # 4. D-18: the learner's own line has its own control and its own translation.
+    learner_tapped = time.monotonic()
+    _en_toggle(page, learner_id).click()
+    page.wait_for_function(EXPANDED, arg=learner_id, timeout=TRANSLATE_TIMEOUT_MS)
+    learner_ms = round((time.monotonic() - learner_tapped) * 1000)
+    mine = _translation(page)
+    learner_english = page.locator(f"#en-{learner_id}").text_content()
+    print(f"[deployed] the learner's own line -> {learner_english!r} in {learner_ms} ms; {mine}")
+    assert mine["requests"] == 2 and mine["cacheHits"] == 1
+    assert mine["states"] == {avatar_id: "shown", learner_id: "shown"}
+    assert TRANSLATE_EXPECT in learner_english.lower(), learner_english
+
+    # 5. The {error} contract the error state renders. Not reachable through the control.
+    refused = page.evaluate(REJECT_TRANSLATE, ["あ" * OVERLONG_CHARS, "Lx"])
+    after = _translation(page)
+    print(f"[deployed] translate({OVERLONG_CHARS} chars) -> {refused!r}")
+    assert refused is not None and "characters" in refused, refused
+    assert after["requests"] == 2, "a refused translate is not a request the host made"
+    assert after["states"] == {avatar_id: "shown", learner_id: "shown"}

tests/e2e/test_facade_parity.py

@@ -870,3 +870,146 @@ def test_lookup_popover_under_both_transports(transport, page, gradio_apps, requ
     closed = page.evaluate(POPOVER)
     assert closed["open"] is False and closed["closeCount"] == 1
     assert card.is_visible() is False
+
+
+# ------------------------------------------------------- the EN translation reveal (02-09)
+#
+# The host's half of the reveal, which the standalone harness cannot see: the renderer's
+# hook wired to a REAL avatar.translate() round trip, and the per-line session cache that
+# sits in front of it. The claim that matters is the third tap - it must produce the English
+# again with the request counter recording nothing - and it is worth proving under the
+# iframe transport as well, because a cache accidentally living on the wrong side of the
+# transport boundary would still look right inline.
+
+STATION_EN = "station"
+TRANSLATION_BOUND = (
+    "() => !!(window.Avatar && window.Avatar.__debug && window.Avatar.__debug.translation)"
+)
+TRANSLATION = """
+async () => {
+  const d = await window.Avatar.getDebug();
+  return d.translation ? JSON.parse(JSON.stringify(d.translation)) : null;
+}
+"""
+AVATAR_EN_TOGGLE = "() => !!document.querySelector('#transcript-text .turn-avatar .en-toggle')"
+# Installed before the click, so the loading state is recorded rather than sampled: on a
+# fast local round trip it can be over in tens of milliseconds, and a poll that missed it
+# would be indistinguishable from a control that never showed one at all (D-15).
+OBSERVE_TOGGLE = """
+(lineId) => {
+  const btn = document.querySelector(`.en-toggle[data-line="${lineId}"]`);
+  if (!btn) return false;
+  window.__enSeq = [];
+  const record = () => window.__enSeq.push({
+    busy: btn.getAttribute('aria-busy'),
+    expanded: btn.getAttribute('aria-expanded'),
+    text: btn.textContent,
+    disabled: btn.disabled,
+  });
+  record();
+  new MutationObserver(record).observe(btn, {
+    attributes: true, childList: true, subtree: true, characterData: true,
+  });
+  return true;
+}
+"""
+EN_SEQUENCE = "() => window.__enSeq || []"
+EXPANDED = """
+(id) => {
+  const btn = document.querySelector(`.en-toggle[data-line="${id}"]`);
+  return !!btn && btn.getAttribute('aria-expanded') === 'true';
+}
+"""
+TRANSLATE_TIMEOUT_MS = 60_000
+
+
+def _translation(page) -> dict:
+    return page.evaluate(TRANSLATION)
+
+
+def _en_toggle(page, line_id: str):
+    return page.locator(f"#transcript-text .en-toggle[data-line='{line_id}']")
+
+
+@pytest.mark.parametrize("transport", TRANSPORTS)
+def test_translation_reveal_under_both_transports(transport, page, gradio_apps, request_counter):
+    """JPN-04 / D-15 / D-16 / D-17 / D-18: tap EN under a line and the English appears
+    inline after a loading state; tap again and it collapses; tap a third time and it comes
+    back from the browser's own cache with ZERO requests - identically inline and in an
+    iframe. The learner's own line has its own control and its own translation.
+    """
+    url = gradio_apps(transport)
+    page.goto(url)
+    page.wait_for_function(AVATAR_READY, timeout=BOOT_TIMEOUT_MS)
+    page.wait_for_function(FIRST_FRAME, timeout=FIRST_FRAME_TIMEOUT_MS)
+    page.wait_for_function(TRANSLATION_BOUND, timeout=BOOT_TIMEOUT_MS)
+    seeded = _translation(page)
+    assert seeded["requests"] == 0 and seeded["cacheHits"] == 0 and seeded["states"] == {}
+
+    page.fill("#text-input input", STATION)
+    page.press("#text-input input", "Enter")
+    wait_for_ruby(page, AVATAR_EN_TOGGLE, TURN_TIMEOUT_MS, "the avatar's line never arrived")
+    _wait_settled(page)
+
+    avatar_line = page.locator("#transcript-text .turn-avatar").last
+    learner_line = page.locator("#transcript-text .turn-you").last
+    avatar_id = avatar_line.get_attribute("data-line")
+    learner_id = learner_line.get_attribute("data-line")
+    assert avatar_line.locator(".en-toggle").count() == 1
+    assert learner_line.locator(".en-toggle").count() == 1, "D-18: the learner's line too"
+    assert page.locator(f"#en-{avatar_id}").is_visible() is False, "D-16: never unrequested"
+
+    # 1. The first tap: a loading state, then the English under the line.
+    assert page.evaluate(OBSERVE_TOGGLE, avatar_id) is True
+    _en_toggle(page, avatar_id).click()
+    page.wait_for_function(EXPANDED, arg=avatar_id, timeout=TRANSLATE_TIMEOUT_MS)
+    sequence = page.evaluate(EN_SEQUENCE)
+    shown = _translation(page)
+    english = page.locator(f"#en-{avatar_id}").text_content()
+    print(
+        f"\n[{transport}] tap EN on {avatar_id} -> {english!r}\n"
+        f"[{transport}] the control's sequence: {sequence}\n"
+        f"[{transport}] translation debug: {shown}"
+    )
+    assert any(f["busy"] == "true" for f in sequence), (
+        f"no loading state was ever visible - D-15 requires one: {sequence}"
+    )
+    assert any(f["text"] == "EN…" and f["disabled"] for f in sequence), sequence
+    assert shown["requests"] == 1 and shown["cacheHits"] == 0
+    assert shown["lastMs"] > 0 and shown["lastError"] is None
+    assert shown["states"][avatar_id] == "shown"
+    assert page.locator(f"#en-{avatar_id}").is_visible() is True
+    assert STATION_EN in english.lower(), english
+
+    # 2. The second tap collapses it, with no round trip (D-16).
+    _en_toggle(page, avatar_id).click()
+    collapsed = _translation(page)
+    assert collapsed["states"][avatar_id] == "collapsed"
+    assert collapsed["requests"] == 1, "collapsing must not spend a translation"
+    assert page.locator(f"#en-{avatar_id}").is_visible() is False
+
+    # 3. The third tap re-shows it from the cache - the number D-17 is about.
+    with request_counter(page) as seen:
+        _en_toggle(page, avatar_id).click()
+        page.wait_for_function(EXPANDED, arg=avatar_id, timeout=5_000)
+        during = list(seen)
+    cached = _translation(page)
+    print(f"[{transport}] re-show from cache: {cached}; requests during it: {during}")
+    assert during == [], (
+        f"{transport}: a cached re-show issued {len(during)} request(s); the session cache "
+        f"in host.js is supposed to answer it without the network: {during}"
+    )
+    assert cached["cacheHits"] == 1 and cached["requests"] == 1
+    assert cached["states"][avatar_id] == "shown"
+    assert page.locator(f"#en-{avatar_id}").text_content() == english
+
+    # 4. D-18: the learner's own line translates too, on its own request.
+    _en_toggle(page, learner_id).click()
+    page.wait_for_function(EXPANDED, arg=learner_id, timeout=TRANSLATE_TIMEOUT_MS)
+    mine = _translation(page)
+    learner_english = page.locator(f"#en-{learner_id}").text_content()
+    print(f"[{transport}] the learner's own line -> {learner_english!r}; {mine}")
+    assert mine["requests"] == 2 and mine["cacheHits"] == 1
+    assert mine["states"] == {avatar_id: "shown", learner_id: "shown"}
+    assert page.locator(f"#en-{learner_id}").is_visible() is True
+    assert STATION_EN in learner_english.lower(), learner_english

tests/e2e/test_transcript_standalone.py

@@ -40,6 +40,33 @@ LONG = 25
 
 DEBUG = "() => JSON.parse(JSON.stringify(window.__transcriptDebug))"
 POPOVER = "() => JSON.parse(JSON.stringify(window.__popoverDebug))"
+TRANSLATION = "() => JSON.parse(JSON.stringify(window.__translationDebug))"
+
+# The EN control's state machine (plan 02-09), recorded rather than polled. The loading
+# state lasts as long as the harness's fake translator takes (60 ms) - long enough to catch
+# with a 10 ms poll, but a poll would make the row's meaning depend on how busy the machine
+# is, and a missed sample is indistinguishable from a control that never went busy at all.
+# A MutationObserver installed BEFORE the click records every attribute the button passed
+# through, so the assertion is about the sequence rather than about a lucky sample.
+OBSERVE_TOGGLE = """
+(lineId) => {
+  const btn = document.querySelector(`.en-toggle[data-line="${lineId}"]`);
+  if (!btn) return false;
+  window.__enSeq = [];
+  const record = () => window.__enSeq.push({
+    busy: btn.getAttribute('aria-busy'),
+    expanded: btn.getAttribute('aria-expanded'),
+    text: btn.textContent,
+    disabled: btn.disabled,
+  });
+  record();
+  new MutationObserver(record).observe(btn, {
+    attributes: true, childList: true, subtree: true, characterData: true,
+  });
+  return true;
+}
+"""
+EN_SEQUENCE = "() => window.__enSeq || []"
 
 # The narrow column plan 02-08 has to survive: a Pixel-7-width viewport with the harness's
 # ?narrow=1 column (300 px wide, 360 px tall, scrolling).
@@ -166,7 +193,7 @@ def test_popover_anchors_and_dismisses(page, static_server):
 
     # D-06: a tap on empty column space closes it.
     cont = _container_rect(page)
-    line_box = page.locator(f"#transcript-text [data-line='{line_id}']").bounding_box()
+    line_box = page.locator(f"#transcript-text .turn[data-line='{line_id}']").bounding_box()
     page.mouse.click(cont["left"] + cont["width"] - 6, line_box["y"] + line_box["height"] / 2)
     closed = _popover(page)
     print(
@@ -270,6 +297,120 @@ def test_popover_stays_inside_narrow_column(browser, static_server):
         context.close()
 
 
+def _translation(page) -> dict:
+    """The EN reveal's live numbers, copied out of the object the renderer writes to."""
+    return page.evaluate(TRANSLATION)
+
+
+def test_en_control_state_machine(page, static_server):
+    """JPN-04 / D-15 / D-16: every line carries an EN control, and one tap walks it through
+    loading -> shown, a second collapses it, a third shows it again.
+
+    The renderer's half of the reveal, with no server and no host: the harness's fake
+    translator resolves after 60 ms, and there is no cache here on purpose, so what this row
+    proves is the STATE MACHINE - that the loading state is really entered (aria-busy, the
+    ellipsis label and a disabled button, all observed in sequence, not sampled), that the
+    English lands in the line's own `.en` div, and that collapsing keeps the text rather
+    than throwing it away. The error state is exercised too: it is the one state the real
+    page's control cannot reach, because the server refuses an over-long line before it can
+    ever be rendered as one.
+    """
+    _open_harness(page, static_server)
+    line_id = _render(page, STUDY, "avatar")
+    toggle = page.locator(f"#transcript-text .en-toggle[data-line='{line_id}']")
+    en = page.locator(f"#en-{line_id}")
+
+    seed = _translation(page)
+    print(f"[standalone] a fresh line: {seed}")
+    assert seed == {
+        "requests": 0,
+        "cacheHits": 0,
+        "lastMs": None,
+        "lastState": "idle",
+        "lastLineId": None,
+        "lastError": None,
+        "states": {line_id: "idle"},
+    }
+    assert toggle.count() == 1, "every line gets exactly one EN control (D-18)"
+    assert toggle.text_content() == "EN"
+    assert toggle.get_attribute("aria-expanded") == "false"
+    assert toggle.get_attribute("aria-busy") == "false"
+    assert toggle.get_attribute("aria-controls") == f"en-{line_id}"
+    assert en.count() == 1 and en.is_visible() is False, "D-16: never shown unrequested"
+
+    # 1. Tap: loading, then shown. The sequence is recorded from before the click.
+    assert page.evaluate(OBSERVE_TOGGLE, line_id) is True
+    toggle.click()
+    page.wait_for_function(
+        '(id) => document.querySelector(`.en-toggle[data-line="${id}"]`)'
+        ".getAttribute('aria-expanded') === 'true'",
+        arg=line_id,
+        timeout=5_000,
+    )
+    sequence = page.evaluate(EN_SEQUENCE)
+    shown = _translation(page)
+    print(f"[standalone] tap EN -> sequence {sequence}; {shown}")
+    busy_frames = [f for f in sequence if f["busy"] == "true"]
+    assert busy_frames, f"the control never went busy - no loading state was visible: {sequence}"
+    assert any(f["text"] == "EN…" for f in busy_frames), sequence
+    assert all(f["disabled"] for f in busy_frames), (
+        f"the control stayed clickable while loading - a second tap would double-spend: {sequence}"
+    )
+    assert sequence[-1] == {"busy": "false", "expanded": "true", "text": "EN", "disabled": False}
+    assert shown["states"][line_id] == "shown" and shown["lastState"] == "shown"
+    assert shown["lastLineId"] == line_id
+    assert en.is_visible() is True
+    assert en.text_content() == f"[EN] {STUDY_TEXT}"
+    assert "en-error" not in (en.get_attribute("class") or "")
+    assert len(page.evaluate("() => window.__translateCalls")) == 1
+
+    # 2. Second tap: collapsed. The text stays in the div, hidden.
+    toggle.click()
+    collapsed = _translation(page)
+    print(f"[standalone] tap again -> {collapsed}")
+    assert collapsed["states"][line_id] == "collapsed"
+    assert toggle.get_attribute("aria-expanded") == "false"
+    assert toggle.get_attribute("aria-busy") == "false"
+    assert en.is_visible() is False
+    assert en.text_content() == f"[EN] {STUDY_TEXT}", "collapsing must not discard the text"
+    assert page.evaluate("() => window.__translateCalls")[-1]["state"] == "shown"
+
+    # 3. Third tap: shown again. The harness has no cache, so it goes through loading -
+    # which is exactly the difference the deployed row measures against the real host.
+    toggle.click()
+    page.wait_for_function(
+        '(id) => document.querySelector(`.en-toggle[data-line="${id}"]`)'
+        ".getAttribute('aria-expanded') === 'true'",
+        arg=line_id,
+        timeout=5_000,
+    )
+    again = _translation(page)
+    print(f"[standalone] tap a third time -> {again}")
+    assert again["states"][line_id] == "shown"
+    assert en.is_visible() is True
+    calls = page.evaluate("() => window.__translateCalls")
+    assert [c["state"] for c in calls] == ["idle", "shown", "collapsed"], calls
+    assert all(c["text"] == STUDY_TEXT for c in calls), "the hook is handed the line's own text"
+
+    # 4. The error state: visible, red-classed, and the control left usable.
+    page.evaluate("(id) => window.__failTranslation(id, 'the translator is asleep')", line_id)
+    failed = _translation(page)
+    print(f"[standalone] forced failure -> {failed}; .en = {en.text_content()!r}")
+    assert failed["states"][line_id] == "error"
+    assert en.is_visible() is True
+    assert "en-error" in (en.get_attribute("class") or "")
+    assert "the translator is asleep" in en.text_content()
+    assert toggle.is_enabled() and toggle.text_content() == "EN"
+    assert toggle.get_attribute("aria-expanded") == "false"
+
+    # A second line gets its own control and its own state; nothing is shared but the map.
+    other = _render(page, TANAKA, "you")
+    two = _translation(page)
+    assert two["states"] == {line_id: "error", other: "idle"}
+    assert page.locator("#transcript-text .en-toggle").count() == 2
+    assert page.locator(f"#en-{other}").is_visible() is False
+
+
 def test_ruby_renders_with_numbers(page, static_server):
     """D-01: the first line renders with every kanji annotated and nothing touched.
 
@@ -358,7 +499,9 @@ def test_learner_line_gets_ruby_too(page, static_server):
     _open_harness(page, static_server)
     line_id = _render(page, STUDY, "you")
     debug = _debug(page)
-    line = page.locator(f"#transcript-text [data-line='{line_id}']")
+    # `.turn[data-line]`, not a bare `[data-line]`: since plan 02-09 the EN control and its
+    # `.en` div carry the same line id, so three elements answer to it.
+    line = page.locator(f"#transcript-text .turn[data-line='{line_id}']")
     assert line.count() == 1
     assert "turn-you" in line.get_attribute("class")
     assert line.get_attribute("data-who") == "you"

tests/test_transport_seam.py

@@ -358,7 +358,17 @@ def test_host_glue_is_neither_a_transport_nor_the_turn_loop():
         assert f"function {member}" not in host and f"async {member}(" not in host, (
             f"host.js implements {member}; turn behaviour belongs in avatar/turn-loop.js"
         )
-    for member in ["dispatchTurn", "requestSlower", "replay", "startListening", "stopListening"]:
+    # Plan 02-09 adds .analyze( and .translate(: the host is where the page's own calls into
+    # the facade are made, and both language round trips are the page's, not the loop's.
+    for member in [
+        "dispatchTurn",
+        "requestSlower",
+        "replay",
+        "startListening",
+        "stopListening",
+        "analyze",
+        "translate",
+    ]:
         assert f".{member}(" in host, f"host.js never calls Avatar.{member}()"
     for name in [*TRANSPORTS, *SHARED, *CORE, *AUDIO_IN]:
         assert HOST not in src(name), f"{name} references {HOST}; only the boot template may"
@@ -690,3 +700,43 @@ def test_host_binds_pointer_once():
     )
     assert host.count("__debug.popover") == 1
     assert "lookup-popover" not in host, "the card is the renderer's DOM, not the host's"
+
+
+def test_translation_cache_lives_in_the_host():
+    """Plan 02-09 / D-15 / D-17: the EN control is the renderer's, the network call and the
+    per-line session cache are the host's, and there is exactly one of each.
+
+    This is the seam that makes "a re-show costs zero requests" checkable at all. If the
+    renderer could translate, or if the host could be persuaded to call ``translate`` from
+    a second place, the deployed request counter would still record zero on a re-show and
+    prove nothing about where the answer came from.
+    """
+    host = src(HOST)
+    transcript = src(TRANSCRIPT)
+
+    calls = host.count("avatar.translate(")
+    assert "new Map(" in host, "host.js keeps no per-line cache; D-17 puts it in the browser"
+    assert host.count("cacheHits") >= 2, "the cache serves without counting itself"
+    assert calls == 1, (
+        "avatar.translate() must be called from exactly one place in host.js, or the cache "
+        f"is not the only gate in front of the network (found {calls})"
+    )
+    # D-17 is session-only: nothing about a translation is written to browser storage.
+    assert "jla.translation" not in host and "jla.en" not in host
+
+    # The renderer: the control, and nothing behind it.
+    assert "en-toggle" in transcript, "transcript.js builds no EN control"
+    assert "onTranslateRequest" in transcript, "the renderer must report the tap, not act on it"
+    assert "setTranslation" in transcript
+    assert ".translate(" not in transcript, (
+        "transcript.js calls translate(); the round trip belongs to the host (D-17 gives the "
+        "cache exactly one owner)"
+    )
+    # The renderer's two Maps are structural - the lines and their retained tokens. A third
+    # would be a cache growing back here, which is what this count exists to catch.
+    assert transcript.count("new Map(") == 2, (
+        "transcript.js has grown a third Map; it should hold only `lines` and `tokensByLine` "
+        f"(found {transcript.count('new Map(')})"
+    )
+    for forbidden in ("fetch(", "XMLHttpRequest"):
+        assert forbidden not in transcript, f"transcript.js references {forbidden!r}"