Spaces:

WolfDavid
/

japanese-learning-avatar

Running on Zero

WolfDavid commited on 17 days ago

Commit

7d7a567

1 Parent(s): a4c4b26

feat(02-07): DOM-built ruby transcript renderer, stylesheet and standalone harness

- avatar/transcript.js: createTranscript (addLine/setTokens/setMode/setLevel), showRt on the kanji axis, LEVEL_RANK/FURIGANA_MODES/LEVELS, debug.furigana numbers (rt count, rt height, line height)
- avatar/transcript.css: line-height 2.1, ruby-position over, rt 0.55em, .tok touch-action
- avatar/transcript-harness.html: fixture tokens -> DOM with no server, 1-based sentence numbers
- tests/e2e/test_transcript_standalone.py: 4 tests incl. the height proof and the oracle-gated modes
- tests/e2e/test_avatar_loop.py: expected_rt, the Python oracle shared by all three layers
- tests/test_transport_seam.py: transcript.js DOM-only, css rules, ruby-not-rp guards

Files changed (6) hide show

avatar/transcript-harness.html +90 -0
avatar/transcript.css +45 -0
avatar/transcript.js +231 -0
tests/e2e/test_avatar_loop.py +42 -0
tests/e2e/test_transcript_standalone.py +193 -0
tests/test_transport_seam.py +48 -0

avatar/transcript-harness.html ADDED Viewed

	@@ -0,0 +1,90 @@

+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Transcript harness</title>
+    <link rel="stylesheet" href="./transcript.css" />
+    <style>
+      body {
+        margin: 16px;
+        font: 16px/1.4 system-ui, sans-serif;
+      }
+      #transcript-text {
+        border: 1px solid #ccc;
+        padding: 8px;
+        min-height: 2em;
+      }
+    </style>
+  </head>
+  <body>
+    <!--
+      THE STANDALONE LAYER FOR THE TRANSCRIPT (plan 02-07). Open it off a static server
+      with no Python app and no host framework: the golden fixture's token records go
+      through avatar/transcript.js into real <ruby><rt> DOM, exactly as stage.html does
+      for the avatar. If this page renders ruby and the
+      deployed page does not, the fault is the host, not the renderer.
+      window.__renderFixture(number, who) takes the 1-BASED sentence number of the 02-05
+      table (#9 = 日本語を勉強しています。, #13 = 田中さんは東京に住んでいます。). That is the ONE
+      convention every prose reference and every test in 02-07 / 02-08 / 02-09 uses -
+      never pass a 0-based index. window.__fixtureUnits(number) returns the same
+      sentence's token records for an oracle to compute against.
+      Query parameters: ?narrow=1 sets #transcript-text to 300 px (plan 02-08's phone column).
+    -->
+    <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>
+    <div id="transcript-text" class="transcript" aria-live="polite"></div>
+    <script type="module">
+      import { createTranscript } from './transcript.js';
+      const params = new URLSearchParams(location.search);
+      const container = document.getElementById('transcript-text');
+      if (params.get('narrow') === '1') container.style.width = '300px';
+      const t = createTranscript(container);
+      window.__transcript = t;
+      // The same object the renderer writes to, not a copy: a test reads live numbers.
+      window.__transcriptDebug = t.debug.furigana;
+      window.__transcriptReady = false;
+      document.getElementById('furigana-mode').addEventListener('change', (e) => {
+        t.setMode(e.target.value);
+      });
+      document.getElementById('level-select').addEventListener('change', (e) => {
+        t.setLevel(e.target.value);
+      });
+      // The static server serves the repo root; the golden fixture is one level up from avatar/.
+      const response = await fetch('../tests/fixtures/sentences.json');
+      if (!response.ok) throw new Error(`golden fixture: HTTP ${response.status}`);
+      const fixture = await response.json();
+      const sentences = fixture.sentences;
+      window.__fixtures = sentences;
+      window.__fixtureUnits = (number) => sentences[number - 1].units;
+      window.__renderFixture = (number, who = 'avatar') => {
+        const { text, units } = sentences[number - 1];
+        const { lineId } = t.addLine({ who, text });
+        t.setTokens(lineId, units);
+        return lineId;
+      };
+      window.__transcriptReady = true;
+    </script>
+  </body>
+</html>

avatar/transcript.css ADDED Viewed

	@@ -0,0 +1,45 @@

+/* avatar/transcript.css - the transcript's ruby rules (plan 02-07, research § Q5).
+ *
+ * The numbers here are what make the rendering verifiable: line-height 2.1 leaves room for
+ * an rt at 0.55em so consecutive lines never collide, ruby-position is pinned to `over` so
+ * a future theme cannot flip it, and the annotation is not selectable so copying a line
+ * copies the base text. tests/test_transport_seam.py greps these rules; the browser suites
+ * measure their effect (debug.furigana.lastLineRtHeightPx / lastLineHeightPx). Loaded by
+ * the app through a <link> inside the transcript's gr.HTML value and by
+ * avatar/transcript-harness.html relative to itself.
+ */
+#transcript-text {
+  position: relative;
+  overflow-x: clip;
+}
+#transcript-text .said {
+  line-height: 2.1;
+}
+#transcript-text ruby {
+  ruby-position: over;
+  ruby-align: center;
+}
+#transcript-text rt {
+  font-size: 0.55em;
+  user-select: none;
+}
+#transcript-text .tok {
+  cursor: pointer;
+  touch-action: manipulation;
+  border-radius: 3px;
+}
+#transcript-text .tok:hover,
+#transcript-text .tok:focus-visible {
+  background: rgba(0, 0, 0, 0.06);
+  outline: none;
+}
+#reading-controls {
+  display: flex;
+  gap: 0.5em;
+  align-items: center;
+  font-size: 0.9em;
+  margin: 0.25em 0;
+}
+#reading-controls select {
+  font: inherit;
+}

avatar/transcript.js ADDED Viewed

	@@ -0,0 +1,231 @@

+// avatar/transcript.js
+//
+// DOM ONLY. Knows nothing about the facade, the transports or the host framework; builds
+// children with createElement/textContent so glosses and learner text are never parsed as
+// HTML. tests/test_transport_seam.py enforces it.
+//
+// The renderer behind #transcript-text (plan 02-07). host.js hands it the container and
+// feeds it lines and the analyzer's token records; it turns each token's ruby spans into
+// real <ruby><rt> elements, gates the readings by mode and level on the KANJI axis
+// (D-02 / D-13), and publishes the numbers that prove the ruby rendered - the rt count,
+// the rendered rt height and the line height - on debug.furigana, so a stylesheet that
+// hides the annotation cannot pass a count (research Pitfall 4, the T-pose lesson).
+//
+// Every line's tokens are retained, so a mode or level change re-renders every line from
+// data with no round trip (D-14). bindPointer() is the seam plan 02-08 fills with tap
+// handling; plan 02-09 adds the translation reveal under each line.
+//
+// The token record (plan 02-05, nlp/analyzer.TOKEN_KEYS): `surface`, `tappable`, `jlpt`,
+// `kanji_levels` ({kanji: "N5".."N1" | null}) and `ruby` ([[text, rt | null], ...] - one
+// span per kanji run with its reading, kana spans with null). Non-tappable units carry
+// [[surface, null]] and never get an annotation.
+/** Difficulty order for the gate; mirrors nlp/levels.LEVEL_RANK. */
+export const LEVEL_RANK = { N5: 1, N4: 2, N3: 3, N2: 4, N1: 5 };
+/** The three-way control (D-02). 'above' = "above my level". */
+export const FURIGANA_MODES = ['always', 'above', 'never'];
+/** The level picker's range (D-14). N1 is not offered: at N1 "above my level" is 'never'. */
+export const LEVELS = ['N5', 'N4', 'N3', 'N2'];
+const LABELS = { you: 'You: ', avatar: 'Avatar: ', slower: 'Avatar (slower): ' };
+/**
+ * D-02 / D-13: a run gets its rt when the mode says so; 'above' keys on the KANJI axis -
+ * any kanji in the run above the learner's level, or unlisted (null, D-10), keeps the whole
+ * run annotated. A run whose every kanji is at or below the level renders bare.
+ *
+ * @param {string} runText      the base text of one ruby span
+ * @param {object} kanjiLevels  the token's {kanji: level | null}
+ * @param {string} mode         one of FURIGANA_MODES
+ * @param {string} level        one of LEVELS
+ */
+export function showRt(runText, kanjiLevels, mode, level) {
+  if (mode === 'always') return true;
+  if (mode === 'never') return false;
+  const mine = LEVEL_RANK[level] ?? 1;
+  const levels = kanjiLevels || {};
+  for (const ch of runText) {
+    if (!(ch in levels)) continue; // kana inside a run never happens; defensive
+    const lv = levels[ch];
+    if (lv == null || (LEVEL_RANK[lv] ?? 99) > mine) return true;
+  }
+  return false;
+}
+/**
+ * @param {Element} container  the project-owned #transcript-text element
+ * @param {object}  [opts]
+ * @param {Document} [opts.doc]
+ */
+export function createTranscript(container, { doc = document } = {}) {
+  if (!container) throw new Error('createTranscript: a container element is required');
+  // Every key seeded here so the key set on getDebug() never depends on timing.
+  const debug = {
+    furigana: {
+      mode: 'always',
+      level: 'N5',
+      storage: 'unknown', // host.js sets 'ok' | 'unavailable' after its localStorage probe
+      lines: 0,
+      rtTotal: 0,
+      lastLineId: null,
+      lastLineRt: 0,
+      lastLineKanjiRuns: 0,
+      lastLineRtHeightPx: 0,
+      lastLineHeightPx: 0,
+    },
+  };
+  /** lineId -> { el, said, who, text } in insertion order. */
+  const lines = new Map();
+  /** lineId -> the retained token records, so a re-render is pure. */
+  const tokensByLine = new Map();
+  let count = 0;
+  let mode = 'always';
+  let level = 'N5';
+  /** The number of [text, rt] spans WITH a reading across a line's tokens: the potential. */
+  function kanjiRuns(tokens) {
+    let runs = 0;
+    for (const token of tokens) {
+      for (const span of token.ruby || []) if (span[1]) runs += 1;
+    }
+    return runs;
+  }
+  function renderTokens(said, tokens) {
+    said.replaceChildren();
+    tokens.forEach((token, index) => {
+      const el = doc.createElement('span');
+      if (token.tappable) {
+        el.className = 'tok';
+        el.dataset.token = String(index);
+        el.setAttribute('role', 'button');
+        el.tabIndex = 0;
+        if (token.jlpt) el.dataset.level = token.jlpt;
+      } else {
+        el.className = 'plain';
+      }
+      const spans =
+        Array.isArray(token.ruby) && token.ruby.length > 0
+          ? token.ruby
+          : [[String(token.surface ?? ''), null]];
+      for (const [text, rt] of spans) {
+        if (rt && showRt(text, token.kanji_levels, mode, level)) {
+          const ruby = doc.createElement('ruby');
+          ruby.append(doc.createTextNode(text));
+          const rtEl = doc.createElement('rt');
+          rtEl.textContent = rt;
+          ruby.append(rtEl);
+          el.append(ruby);
+        } else {
+          el.append(doc.createTextNode(text));
+        }
+      }
+      said.append(el);
+    });
+  }
+  /**
+   * The published numbers, read from the rendered DOM after every (re)render. The line
+   * height is the `.turn` block's: an inline `.said` box reports only its own font's
+   * content area, which does not grow when an annotation sits above it, while the block
+   * that contains the line boxes does - so the block is where "a ruby line is taller than
+   * a bare one" is measurable.
+   */
+  function measure(lineId) {
+    const line = lines.get(lineId);
+    const f = debug.furigana;
+    f.lines = lines.size;
+    f.rtTotal = container.querySelectorAll('rt').length;
+    if (!line) return;
+    f.lastLineId = lineId;
+    f.lastLineRt = line.said.querySelectorAll('rt').length;
+    f.lastLineKanjiRuns = kanjiRuns(tokensByLine.get(lineId) || []);
+    const rt = line.said.querySelector('rt');
+    f.lastLineRtHeightPx = rt ? rt.getBoundingClientRect().height : 0;
+    f.lastLineHeightPx = line.el.getBoundingClientRect().height;
+  }
+  function render(lineId) {
+    const line = lines.get(lineId);
+    if (!line) return;
+    const tokens = tokensByLine.get(lineId);
+    if (tokens && tokens.length > 0) renderTokens(line.said, tokens);
+    else line.said.textContent = line.text; // no tokens (yet, or the analysis failed)
+    measure(lineId);
+  }
+  function renderAll() {
+    for (const lineId of lines.keys()) render(lineId);
+  }
+  /**
+   * 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).
+   *
+   * @param {{who: 'you'|'avatar'|'slower', text: string}} line
+   * @returns {{lineId: string, el: Element}}
+   */
+  function addLine({ who, text }) {
+    count += 1;
+    const lineId = `L${count}`;
+    const el = doc.createElement('div');
+    el.className = `turn turn-${who}`;
+    el.dataset.line = lineId;
+    el.dataset.who = who;
+    const label = doc.createElement('span');
+    label.className = 'who';
+    label.textContent = LABELS[who] ?? LABELS.avatar;
+    const said = doc.createElement('span');
+    said.className = 'said';
+    said.textContent = String(text ?? '');
+    el.append(label, said);
+    container.append(el);
+    container.scrollTop = container.scrollHeight;
+    lines.set(lineId, { el, said, who, text: String(text ?? '') });
+    measure(lineId);
+    return { lineId, el };
+  }
+  /**
+   * Attach (or replace) a line's tokens and rebuild its `.said` children from them.
+   * @returns {boolean} whether the line exists
+   */
+  function setTokens(lineId, tokens) {
+    if (!lines.has(lineId)) return false;
+    tokensByLine.set(lineId, Array.isArray(tokens) ? tokens : []);
+    render(lineId);
+    return true;
+  }
+  function setMode(value) {
+    if (!FURIGANA_MODES.includes(value)) return mode;
+    mode = value;
+    debug.furigana.mode = mode;
+    renderAll();
+    return mode;
+  }
+  function setLevel(value) {
+    if (!LEVELS.includes(value)) return level;
+    level = value;
+    debug.furigana.level = level;
+    renderAll();
+    return level;
+  }
+  return {
+    addLine,
+    setTokens,
+    setMode,
+    setLevel,
+    getMode: () => mode,
+    getLevel: () => level,
+    getTokens: (lineId) => tokensByLine.get(lineId) || null,
+    bindPointer() {
+      // plan 02-08: tap handling for .tok (the lookup popover) is installed here.
+    },
+    debug,
+  };
+}

tests/e2e/test_avatar_loop.py CHANGED Viewed

@@ -27,6 +27,8 @@ from urllib.parse import urlparse
 import pytest
 import requests
 from tests.e2e.test_stage_standalone import (
     ARM_DOWN_MAX,
     FIRST_FRAME_TIMEOUT_MS,
@@ -1160,3 +1162,43 @@ def test_first_tap_is_audible(
         assert after["turnCount"] == 2
         assert after["lastSubtitle"] == TURN_TEXT
         assert second["duration"] > 0.5

 import pytest
 import requests
+from japanese_avatar.nlp.levels import LEVEL_RANK, kanji_levels
+from japanese_avatar.nlp.ruby import is_kanji
 from tests.e2e.test_stage_standalone import (
     ARM_DOWN_MAX,
     FIRST_FRAME_TIMEOUT_MS,
         assert after["turnCount"] == 2
         assert after["lastSubtitle"] == TURN_TEXT
         assert second["duration"] > 0.5
+# ================================================================ furigana (plan 02-07)
+#
+# The three-layer rule again: the rendered ruby is a NUMBER - rt count, rendered rt height,
+# line height - read from getDebug().furigana and from the DOM, at the standalone layer
+# (tests/e2e/test_transcript_standalone.py), under both transports
+# (test_facade_parity.py::test_ruby_under_both_transports) and here. The gate's expected
+# count is computed by an independent Python oracle over the page's own tokens and the
+# pinned kanji list, never hard-coded: 勉 / 強's levels are the data's to say.
+def expected_rt(tokens: list[dict], mode: str, level: str) -> int:
+    """The Python oracle of ``transcript.js::showRt`` over a line's token records.
+    ``always`` shows every kanji run that has a reading; ``never`` none; ``above`` shows a
+    run when ANY kanji in it is above the learner's level or on no list (D-02 / D-10 /
+    D-13, the kanji axis). Written against ``data/jlpt/kanji_levels.json`` through
+    :func:`japanese_avatar.nlp.levels.kanji_levels` and :func:`is_kanji` - not against the
+    token's own ``kanji_levels`` field - so the browser and the oracle agree only if both
+    the record and the gate are right.
+    """
+    if mode == "never":
+        return 0
+    runs = [text for token in tokens for text, rt in token["ruby"] if rt]
+    if mode == "always":
+        return len(runs)
+    assert mode == "above", mode
+    table = kanji_levels()
+    mine = LEVEL_RANK[level]
+    shown = 0
+    for text in runs:
+        for ch in text:
+            if not is_kanji(ch):
+                continue
+            listed = table.get(ch)
+            if listed is None or LEVEL_RANK[listed] > mine:
+                shown += 1
+                break
+    return shown

tests/e2e/test_transcript_standalone.py ADDED Viewed

	@@ -0,0 +1,193 @@

+"""The transcript renderer, proven in a real browser with no Python app and no host framework.
+avatar/transcript-harness.html is opened off the static server; fixture token records from
+tests/fixtures/sentences.json go through avatar/transcript.js into real <ruby><rt> DOM. If
+these pass and the deployed furigana rows fail, the fault is provably the host page (the
+stylesheet did not load, the module was not handed over), not the renderer - the same
+division of blame tests/e2e/test_stage_standalone.py gives the avatar.
+Every claim is a number (research Pitfall 4, "green count, invisible ruby"): the rt COUNT,
+the rendered rt HEIGHT and the line HEIGHT with ruby versus bare, all read from
+transcript.js's published debug object and asserted here before either browser layer that
+needs a server. Marked slow but NOT deployed.
+"""
+from __future__ import annotations
+import json
+from pathlib import Path
+import pytest
+from tests.e2e.test_avatar_loop import expected_rt
+pytestmark = pytest.mark.slow
+FIXTURE = Path(__file__).resolve().parent.parent / "fixtures" / "sentences.json"
+READY_TIMEOUT_MS = 15_000
+# 1-BASED sentence numbers of the 02-05 table - the harness's one convention. #9 has two
+# kanji runs (日本語, 勉強) around a bare particle and a bare inflection; #13 and #1 make up
+# the three-line re-render check.
+STUDY = 9
+STUDY_TEXT = "日本語を勉強しています。"
+STUDY_READING_FIRST = "にほんご"
+TANAKA = 13
+HELLO = 1
+DEBUG = "() => JSON.parse(JSON.stringify(window.__transcriptDebug))"
+def _units(number: int) -> list[dict]:
+    """The fixture's token records for a 1-based sentence number, for the Python oracle."""
+    sentences = json.loads(FIXTURE.read_text(encoding="utf-8"))["sentences"]
+    return sentences[number - 1]["units"]
+def _open_harness(page, static_server, query: str = ""):
+    page.goto(f"{static_server}/avatar/transcript-harness.html{query}")
+    page.wait_for_function("() => window.__transcriptReady === true", timeout=READY_TIMEOUT_MS)
+    assert page.evaluate("() => window.__fixtures[8].text") == STUDY_TEXT, (
+        "fixture #9 is not 日本語を勉強しています。; convention or golden file moved"
+    )
+def _render(page, number: int, who: str = "avatar") -> str:
+    return page.evaluate("([n, who]) => window.__renderFixture(n, who)", [number, who])
+def _debug(page) -> dict:
+    return page.evaluate(DEBUG)
+def _set(page, select_id: str, value: str) -> dict:
+    page.select_option(f"#{select_id}", value)
+    return _debug(page)
+def test_ruby_renders_with_numbers(page, static_server):
+    """D-01: the first line renders with every kanji annotated and nothing touched.
+    Two kanji runs -> two <rt>, each with a rendered height, on a line that is one
+    `.turn-avatar`; the readings are real DOM text (in textContent - which is why <rp> is
+    never emitted), the tappable units carry the accessibility floor and the particles are
+    plain spans.
+    """
+    _open_harness(page, static_server)
+    line_id = _render(page, STUDY, "avatar")
+    debug = _debug(page)
+    print(f"[standalone] {STUDY_TEXT} as avatar -> {line_id}: {debug}")
+    assert line_id == "L1"
+    assert page.locator("#transcript-text .turn-avatar").count() == 1
+    assert page.locator("#transcript-text .turn").count() == 1
+    assert debug["lastLineId"] == "L1"
+    assert debug["lastLineKanjiRuns"] == 2
+    assert debug["lastLineRt"] == 2, debug
+    assert debug["rtTotal"] == 2
+    assert debug["lastLineRtHeightPx"] > 0, "rt exists but rendered with no height - hidden ruby"
+    assert debug["lastLineHeightPx"] > 0
+    said = page.locator("#transcript-text .turn .said")
+    assert STUDY_READING_FIRST in said.text_content()
+    assert page.locator("#transcript-text .turn .who").text_content() == "Avatar: "
+    ruby = page.locator("#transcript-text ruby").first
+    assert "日本語" in ruby.inner_text()
+    assert page.locator("#transcript-text rt").first.text_content() == STUDY_READING_FIRST
+    toks = page.locator("#transcript-text .tok")
+    assert toks.count() == 2, "日本語 and 勉強しています are the two tappable units"
+    for i in range(toks.count()):
+        assert toks.nth(i).get_attribute("role") == "button"
+        assert toks.nth(i).get_attribute("tabindex") == "0"
+        assert toks.nth(i).get_attribute("data-token") is not None
+    assert page.locator("#transcript-text .plain").count() >= 2, "を and 。 are plain (D-11)"
+def test_furigana_modes_gate_on_kanji_axis(page, static_server):
+    """D-02 / D-13 / D-14: never -> 0; above@N5 and above@N2 equal the independent oracle
+    (computed from the pinned kanji list, never hard-coded); always -> 2 again; and the
+    always line is measurably taller than the never line - the rendered-height proof."""
+    _open_harness(page, static_server)
+    _render(page, STUDY, "avatar")
+    units = _units(STUDY)
+    always = _debug(page)
+    assert always["mode"] == "always" and always["level"] == "N5"
+    assert always["lastLineRt"] == expected_rt(units, "always", "N5") == 2
+    never = _set(page, "furigana-mode", "never")
+    assert never["mode"] == "never"
+    assert never["lastLineRt"] == 0 and never["rtTotal"] == 0
+    assert page.locator("#transcript-text rt").count() == 0
+    assert never["lastLineRtHeightPx"] == 0
+    above_n5 = _set(page, "furigana-mode", "above")
+    want_n5 = expected_rt(units, "above", "N5")
+    assert above_n5["mode"] == "above" and above_n5["level"] == "N5"
+    assert above_n5["lastLineRt"] == want_n5, (above_n5, want_n5)
+    above_n2 = _set(page, "level-select", "N2")
+    want_n2 = expected_rt(units, "above", "N2")
+    assert above_n2["level"] == "N2"
+    assert above_n2["lastLineRt"] == want_n2, (above_n2, want_n2)
+    assert want_n2 <= want_n5
+    back = _set(page, "furigana-mode", "always")
+    assert back["lastLineRt"] == 2 and back["rtTotal"] == 2
+    print(
+        f"[standalone] modes: always rt={always['lastLineRt']} h={always['lastLineHeightPx']} "
+        f"rtH={always['lastLineRtHeightPx']}; never rt=0 h={never['lastLineHeightPx']}; "
+        f"above@N5 rt={above_n5['lastLineRt']} (oracle {want_n5}); "
+        f"above@N2 rt={above_n2['lastLineRt']} (oracle {want_n2})"
+    )
+    assert always["lastLineHeightPx"] > never["lastLineHeightPx"], (
+        "the ruby line is not taller than the bare line; the annotation is not being laid out "
+        f"above the text (always {always['lastLineHeightPx']} px vs never "
+        f"{never['lastLineHeightPx']} px)"
+    )
+    assert back["lastLineHeightPx"] == always["lastLineHeightPx"]
+def test_learner_line_gets_ruby_too(page, static_server):
+    """D-03: the learner's own line carries the same ruby as the avatar's."""
+    _open_harness(page, static_server)
+    line_id = _render(page, STUDY, "you")
+    debug = _debug(page)
+    line = page.locator(f"#transcript-text [data-line='{line_id}']")
+    assert line.count() == 1
+    assert "turn-you" in line.get_attribute("class")
+    assert line.get_attribute("data-who") == "you"
+    assert line.locator(".who").text_content() == "You: "
+    assert debug["lastLineRt"] == 2
+    assert line.locator("rt").count() == 2
+    assert debug["lastLineRtHeightPx"] > 0
+def test_rerender_keeps_line_count(page, static_server):
+    """A mode flip re-renders every line from retained tokens: no duplicates, no losses."""
+    _open_harness(page, static_server)
+    ids = [_render(page, HELLO, "avatar"), _render(page, STUDY, "you"), _render(page, TANAKA)]
+    assert ids == ["L1", "L2", "L3"]
+    before = _debug(page)
+    assert before["lines"] == 3
+    total_always = before["rtTotal"]
+    assert total_always == sum(
+        expected_rt(_units(n), "always", "N5") for n in (HELLO, STUDY, TANAKA)
+    )
+    _set(page, "furigana-mode", "never")
+    _set(page, "level-select", "N3")
+    after = _set(page, "furigana-mode", "above")
+    assert after["lines"] == 3
+    assert page.locator("#transcript-text .turn").count() == 3
+    assert [
+        el.get_attribute("data-line") for el in page.locator("#transcript-text .turn").all()
+    ] == ids
+    assert after["rtTotal"] == sum(
+        expected_rt(_units(n), "above", "N3") for n in (HELLO, STUDY, TANAKA)
+    )
+    assert after["lastLineId"] == "L3"
+    restored = _set(page, "furigana-mode", "always")
+    assert restored["rtTotal"] == total_always
+    assert page.locator("#transcript-text .turn").count() == 3

tests/test_transport_seam.py CHANGED Viewed

@@ -39,6 +39,11 @@ AUDIO_IN = ["mic.js", "asr.js"]
 # it must import no avatar module, be imported by none, and implement no turn behaviour.
 HOST = "host.js"
 COMPONENT = AVATAR.parent / "src" / "japanese_avatar" / "ui" / "avatar_component.py"
 def src(name: str) -> str:
@@ -532,3 +537,46 @@ def test_bridge_calls_take_one_payload():
     assert "bridge.language_info(" in s
     assert "bridge.analyze(text" not in s, "analyze must pack its arguments into one object"
     assert "bridge.translate(text" not in s, "translate must pack its arguments into one object"

 # it must import no avatar module, be imported by none, and implement no turn behaviour.
 HOST = "host.js"
 COMPONENT = AVATAR.parent / "src" / "japanese_avatar" / "ui" / "avatar_component.py"
+# Plan 02-07. The transcript renderer: DOM only, handed to the host glue by the boot
+# template. It knows neither the facade nor the host framework, and builds ruby with
+# createElement so glosses and learner text are never parsed as markup.
+TRANSCRIPT = "transcript.js"
+TRANSCRIPT_CSS = "transcript.css"
 def src(name: str) -> str:
     assert "bridge.language_info(" in s
     assert "bridge.analyze(text" not in s, "analyze must pack its arguments into one object"
     assert "bridge.translate(text" not in s, "translate must pack its arguments into one object"
+# ------------------------------------------------------------- plan 02-07: the transcript
+#
+# Ruby is built by one DOM-only module. It must import nothing (it is handed the container),
+# reference neither window.Avatar nor the host framework, never write markup as a string,
+# and emit <ruby><rt> without <rp> - the fallback parentheses would leak into every
+# textContent-based assertion and are unnecessary on every target browser (research § Q5).
+def test_transcript_renderer_is_dom_only():
+    s = src(TRANSCRIPT)
+    assert not re.search(r"^\s*import\s", s, re.M), "transcript.js must import nothing"
+    assert "window.Avatar" not in s, "transcript.js must not know the facade"
+    assert "innerHTML" not in s, "transcript.js must build children, never parse markup"
+    lowered = s.lower()
+    for tok in GRADIO_TOKENS:
+        assert tok.lower() not in lowered, f"transcript.js references {tok!r}"
+    assert "export function createTranscript" in s
+    assert "export function showRt" in s
+    for name in [*TRANSPORTS, *SHARED, *CORE, *AUDIO_IN, HOST]:
+        assert TRANSCRIPT not in src(name), (
+            f"{name} references {TRANSCRIPT}; only the boot template may load it"
+        )
+def test_transcript_css_ships_the_measured_rules():
+    """The numbers research § Q5 arrived at, pinned so a theme cannot quietly undo them."""
+    css = src(TRANSCRIPT_CSS)
+    for rule in (
+        "line-height: 2.1",
+        "ruby-position: over",
+        "font-size: 0.55em",
+        "touch-action: manipulation",
+    ):
+        assert rule in css, f"transcript.css lost {rule!r}"
+def test_transcript_uses_ruby_not_parentheses():
+    s = src(TRANSCRIPT)
+    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"