test(02-08): popover at three layers, incl. the Pixel 7 column

- test_facade_parity.py::test_lookup_popover_under_both_transports: a typed turn, then
taps on 田中さん and 住んでいます inside a request counter. Zero requests under BOTH
transports, which is the whole claim: the glosses ride inside the token the line holds,
so the iframe transport needed no new bridge call
- test_avatar_loop.py::test_lookup_popover: the card's senses ("study" among them), its
dictionary form 勉強する, its reading べんきょうしています and a badge compared against the
page's own lastTokens[2].jlpt; the learner's line is tappable too (D-03/D-18); the
plain spans carry no button role (D-11)
- test_avatar_loop.py::test_lookup_popover_mobile: the Pixel 7 descriptor with real
touchscreen taps, asserting insideTranscript on a 324 px column

Found by the rows above and fixed here:
- the card was clamped into view even when that put it on top of the word it was anchored
to, so a second tap hit the card instead of the next word. It now goes on whichever side
of the word has more room and never grows past that room (it scrolls internally)
- a 196 px column is not tall enough to hold both the conversation and the card: the card
covered the line above its anchor and made those words untappable. #transcript-text is
now a 40vh scrolling log (335 px on a Pixel 7) instead of a min/max-height block

avatar/transcript.css

@@ -13,13 +13,16 @@
  * auto-height element - so a long conversation grew the page instead of scrolling the
  * transcript. The height is also what makes plan 02-08's `insideTranscript` a fact rather
  * than a coincidence: a card can only be proven to have stayed inside a box that has edges,
- * and on a phone that box is all the room there is. */
+ * and on a phone that box is all the room there is. It is a viewport fraction rather than a
+ * max-height because the lookup card needs room BESIDE the words as well as under them: on
+ * a 196 px column a card is wide enough to cover the line above the one it is anchored to,
+ * and a word under the card cannot be tapped. 40vh is 335 px on a Pixel 7. */
 #transcript-text {
   position: relative;
   overflow-x: clip;
   overflow-y: auto;
-  min-height: 9em;
-  max-height: 40vh;
+  height: 40vh;
+  min-height: 14em;
 }
 #transcript-text .said {
   line-height: 2.1;

avatar/transcript.js

@@ -51,8 +51,10 @@ const MAX_SENSES = 3;
 /** 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;
-/** The card never grows past this, nor past the column it must stay inside (see position). */
+/** The card never grows past this, nor past the room beside the word (see position). */
 const CARD_MAX_HEIGHT_PX = 240;
+/** Below this a card is not worth showing at all, so it is allowed to overflow instead. */
+const MIN_CARD_HEIGHT_PX = 48;
 
 function clamp(value, low, high) {
   return Math.min(Math.max(value, low), high);
@@ -293,23 +295,31 @@ export function createTranscript(container, { doc = document } = {}) {
    * Offsets are in the container's PADDING-BOX coordinates - what `position: absolute`
    * inside `#transcript-text` resolves against - so `clientLeft` / `clientTop` (the border
    * widths) come off the viewport rects, and `scrollTop` converts the visible position into
-   * the scrolled content's. The card is clamped horizontally into the column, flipped above
-   * the word when it would fall out of the bottom, and, when the column is tall enough to
-   * hold it at all, clamped into view vertically as a last resort - which is what keeps
-   * insideTranscript true on a 300 px phone column.
+   * the scrolled content's. The card is clamped horizontally into the column and placed on
+   * whichever side of the word has more room, never growing past that room - it scrolls
+   * internally instead. Those two rules together are what make the published numbers true
+   * by construction rather than by luck: the card cannot leave the column
+   * (insideTranscript) and cannot cover the word that was tapped, which is what would
+   * otherwise make "tap the next word to re-anchor" impossible on a short phone column.
    */
   function position(el, tokEl) {
     el.style.left = '0px';
     el.style.top = '0px';
-    // A three-sense entry can be taller than a phone's transcript column. Capping the card
-    // to the column (it scrolls internally past that) is what turns "it fitted this time"
-    // into "it always fits": every branch below can then place it inside.
-    el.style.maxHeight = `${Math.min(
-      CARD_MAX_HEIGHT_PX,
-      Math.max(60, container.clientHeight - 2 * EDGE_INSET_PX)
-    )}px`;
+    el.style.maxHeight = `${CARD_MAX_HEIGHT_PX}px`;
     const contRect = container.getBoundingClientRect();
     const tokRect = tokEl.getBoundingClientRect();
+
+    const viewTop = container.scrollTop;
+    const viewBottom = viewTop + container.clientHeight;
+    const tokTop = tokRect.top - contRect.top - container.clientTop + viewTop;
+    const tokBottom = tokTop + tokRect.height;
+
+    const roomBelow = viewBottom - (tokBottom + ANCHOR_GAP_PX) - 2;
+    const roomAbove = tokTop - ANCHOR_GAP_PX - viewTop - 2;
+    const below = roomBelow >= roomAbove;
+    const room = Math.max(MIN_CARD_HEIGHT_PX, below ? roomBelow : roomAbove);
+    el.style.maxHeight = `${Math.round(Math.min(CARD_MAX_HEIGHT_PX, room))}px`;
+
     const width = el.offsetWidth;
     const height = el.offsetHeight;
 
@@ -319,18 +329,11 @@ export function createTranscript(container, { doc = document } = {}) {
       EDGE_INSET_PX,
       maxLeft
     );
-
-    const viewTop = container.scrollTop;
-    const viewBottom = viewTop + container.clientHeight;
-    const base = tokRect.top - contRect.top - container.clientTop + viewTop;
-    let top = base + tokRect.height + ANCHOR_GAP_PX;
-    if (top + height > viewBottom) {
-      const above = base - height - ANCHOR_GAP_PX;
-      if (above >= viewTop) top = above;
-    }
-    if (height <= container.clientHeight) {
-      top = clamp(top, viewTop + 2, viewBottom - height - 2);
-    }
+    const top = clamp(
+      below ? tokBottom + ANCHOR_GAP_PX : tokTop - ANCHOR_GAP_PX - height,
+      viewTop,
+      Math.max(viewTop, viewBottom - height)
+    );
 
     el.style.left = `${Math.round(left)}px`;
     el.style.top = `${Math.round(top)}px`;

tests/e2e/test_avatar_loop.py

@@ -1476,3 +1476,202 @@ def test_furigana_modes(page, space_url, warm_space, speech_events, wait_for_ava
     _set_reading(page, "furigana-mode", "always")
     _set_reading(page, "level-select", "N5")
     assert _furigana(page)["mode"] == "always"
+
+
+# ================================================================ word lookup (plan 02-08)
+#
+# JPN-03 on the Space: tap any word, see its reading, its meaning and its level - instantly,
+# because the glosses ride inside the token the line already holds (research § Q3). Two rows
+# for one feature, because the interesting failures differ: on the desktop page the question
+# is whether the CARD is right (the senses, the dictionary form, the badge, and zero
+# requests); on a phone it is whether the card is REACHABLE - anchored inside a 412 px
+# column, under real touch input rather than Playwright's mouse (research Pitfall 5).
+
+# 勉強しています in 日本語を勉強しています。 - lemma 勉強する, N5, senses including "study".
+LOOKUP_STUDY_TOKEN = 2
+LOOKUP_LEARNER_TOKEN = 0  # 日本語 - the learner's own line is tappable too (D-03 / D-18)
+STUDY_VERB_READING = "べんきょうしています"
+STUDY_VERB_LEMMA = "勉強する"
+
+# The long fixture, so the avatar's line wraps on a phone column and its last word sits low
+# enough that an unflipped card would hang out of the bottom.
+LONG_TEXT = "今日はいい天気ですから、公園を散歩してから、買い物に行きました。"
+
+POPOVER_BOUND = "() => !!(window.Avatar && window.Avatar.__debug && window.Avatar.__debug.popover)"
+POPOVER = """
+async () => {
+  const d = await window.Avatar.getDebug();
+  return d.popover ? JSON.parse(JSON.stringify(d.popover)) : null;
+}
+"""
+AVATAR_TOKENS = "() => document.querySelectorAll('#transcript-text .turn-avatar .tok').length >= 3"
+CONTAINER_RECT = """
+() => { const c = document.querySelector('#transcript-text');
+  const r = c.getBoundingClientRect();
+  return { left: r.left, top: r.top, width: r.width, height: r.height,
+           clientWidth: c.clientWidth, clientHeight: c.clientHeight,
+           scrollHeight: c.scrollHeight, scrollTop: c.scrollTop }; }
+"""
+CARD_RECT = """
+() => { const el = document.querySelector('#lookup-popover');
+  if (!el) return null;
+  const r = el.getBoundingClientRect();
+  return { left: r.left, top: r.top, right: r.right, bottom: r.bottom,
+           width: r.width, height: r.height }; }
+"""
+
+
+def _popover(page) -> dict:
+    return page.evaluate(POPOVER)
+
+
+def _box(locator) -> dict:
+    """The element's box, scrolled into view first: on a phone the transcript is below the
+    fold, and raw input at a coordinate outside the viewport lands on nothing."""
+    locator.scroll_into_view_if_needed()
+    box = locator.bounding_box()
+    assert box and box["width"] > 0 and box["height"] > 0, f"nothing to tap: {box}"
+    return box
+
+
+def _tap_mouse(page, locator) -> None:
+    """Raw pointer input at the element's centre. NOT ``page.click``: the card opens on
+    ``pointerup`` and dismisses on a capture-phase ``pointerdown``, so the real order of the
+    two pointer events is part of what is under test."""
+    box = _box(locator)
+    page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
+
+
+def _tap_touch(page, locator) -> dict:
+    """A real touch sequence on a touch-enabled context - what a learner's thumb does."""
+    box = _box(locator)
+    page.touchscreen.tap(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
+    return box
+
+
+@pytest.mark.deployed
+def test_lookup_popover(
+    page, space_url, warm_space, speech_events, request_counter, wait_for_avatar_ready
+):
+    """JPN-03 / D-05 / D-06 / D-07 / D-08: tapping a word opens a card carrying that word's
+    reading, its JMdict senses, its dictionary form and its JLPT badge - with zero network
+    requests, because the lookup is a pure client action on data the line already holds.
+
+    The badge is compared against the level in the page's OWN token record, never a literal
+    here, for the same reason the furigana oracle exists: a wrong record and a wrong badge
+    must not be able to agree.
+    """
+    speech_events.install(page)
+    wait_for_avatar_ready(page, space_url)
+    page.wait_for_function(POPOVER_BOUND, timeout=READY_TIMEOUT_MS)
+    seeded = _popover(page)
+    assert seeded["open"] is False and seeded["openCount"] == 0
+
+    turn = _study_turn(page, speech_events)
+    tokens = page.evaluate(LAST_TOKENS)
+    avatar_line = page.locator("#transcript-text .turn-avatar").last
+    learner_line = page.locator("#transcript-text .turn-you").last
+    card = page.locator("#lookup-popover")
+
+    with request_counter(page) as seen:
+        _tap_mouse(page, avatar_line.locator(f".tok[data-token='{LOOKUP_STUDY_TOKEN}']"))
+        opened = _popover(page)
+        during = list(seen)
+
+    senses = card.locator(".lk-gloss li").all_text_contents()
+    print(
+        f"\n[deployed] {STUDY_TEXT} in {turn['turn_ms']} ms; tap 勉強しています -> {opened}\n"
+        f"[deployed] card: reading {card.locator('.lk-reading').text_content()!r}, "
+        f"badge {card.locator('.lk-level').text_content()!r}, "
+        f"lemma {card.locator('.lk-lemma').text_content()!r}, senses {senses}\n"
+        f"[deployed] requests during the tap: {during}; card rect {page.evaluate(CARD_RECT)}"
+    )
+    assert opened["open"] is True and opened["tokenIndex"] == LOOKUP_STUDY_TOKEN
+    assert opened["lineId"] == avatar_line.get_attribute("data-line")
+    assert during == [], (
+        "the lookup issued network requests; the glosses are supposed to ride inside the "
+        f"token the line already carries: {during}"
+    )
+    assert card.is_visible()
+    assert len(senses) >= 1 and opened["glossCount"] == len(senses)
+    assert "study" in " ".join(senses).lower(), senses
+    assert card.locator(".lk-level").text_content() == tokens[LOOKUP_STUDY_TOKEN]["jlpt"]
+    assert STUDY_VERB_LEMMA in card.locator(".lk-lemma").text_content()
+    assert card.locator(".lk-reading").text_content() == STUDY_VERB_READING
+
+    # D-11: the particle and the full stop are plain text - not tappable, no button role.
+    plains = page.locator("#transcript-text .turn-avatar .plain")
+    assert plains.count() >= 2
+    roles = [plains.nth(i).get_attribute("role") for i in range(plains.count())]
+    assert roles == [None] * len(roles), f"a plain span claims to be a control: {roles}"
+
+    # D-03 / D-18 parity: the learner's own line is tappable too.
+    _tap_mouse(page, learner_line.locator(f".tok[data-token='{LOOKUP_LEARNER_TOKEN}']"))
+    mine = _popover(page)
+    print(f"[deployed] tap the learner's own 日本語 -> {mine}")
+    assert mine["open"] is True
+    assert mine["lineId"] == learner_line.get_attribute("data-line")
+    assert mine["tokenIndex"] == LOOKUP_LEARNER_TOKEN
+    assert mine["openCount"] == 2, "a tap on another word re-anchors rather than re-opening"
+
+    page.keyboard.press("Escape")
+    closed = _popover(page)
+    assert closed["open"] is False and closed["closeCount"] >= 1
+    assert card.is_visible() is False
+
+
+@pytest.mark.deployed
+def test_lookup_popover_mobile(
+    browser, playwright, space_url, warm_space, speech_events, wait_for_avatar_ready
+):
+    """JPN-03 / D-06 on a phone: the same card, on a 412 px column, opened with real touch.
+
+    ``page.touchscreen.tap`` on the Pixel 7 descriptor, not ``page.click``: research
+    Pitfall 5 is that Playwright's mouse helpers make a card look reachable where a real
+    touch sequence would not dismiss or re-anchor it. ``insideTranscript`` is the phone
+    assertion - a card that renders outside the column is invisible on a phone and passes
+    every count-based check there is.
+    """
+    context = browser.new_context(**playwright.devices["Pixel 7"])
+    page = context.new_page()
+    try:
+        speech_events.install(page)
+        timings = wait_for_avatar_ready(page, space_url)
+        page.wait_for_function(POPOVER_BOUND, timeout=READY_TIMEOUT_MS)
+
+        submitted = time.monotonic()
+        _submit_text(page, LONG_TEXT)
+        wait_for_ruby(
+            page, AVATAR_TOKENS, LEARNER_RUBY_TIMEOUT_MS, "the avatar's line has no tappable words"
+        )
+        line_ms = round((time.monotonic() - submitted) * 1000)
+        cont = page.evaluate(CONTAINER_RECT)
+        print(
+            f"\n[deployed/Pixel 7] ready {timings['ready_seconds']:.1f}s; the avatar's line "
+            f"{line_ms} ms after Enter; transcript column {cont}"
+        )
+
+        avatar_line = page.locator("#transcript-text .turn-avatar").last
+        last_box = _tap_touch(page, avatar_line.locator(".tok").last)
+        low = _popover(page)
+        low_rect = page.evaluate(CARD_RECT)
+        print(f"[deployed/Pixel 7] tap the LAST word -> {low}; card {low_rect}")
+        assert low["open"] is True, f"a touch on {last_box} opened nothing"
+        assert low["insideTranscript"] is True, (low, low_rect, page.evaluate(CONTAINER_RECT))
+        assert low["width"] <= cont["clientWidth"], (low, cont)
+
+        _tap_touch(page, avatar_line.locator(".tok").first)
+        high = _popover(page)
+        high_rect = page.evaluate(CARD_RECT)
+        print(f"[deployed/Pixel 7] tap the FIRST word -> {high}; card {high_rect}")
+        assert high["open"] is True and high["openCount"] == 2
+        assert high["insideTranscript"] is True, (high, high_rect, page.evaluate(CONTAINER_RECT))
+        assert high["width"] <= cont["clientWidth"]
+
+        _tap_touch(page, page.locator("#intro"))
+        closed = _popover(page)
+        print(f"[deployed/Pixel 7] tap outside -> {closed}")
+        assert closed["open"] is False
+        assert page.locator("#lookup-popover").is_visible() is False
+    finally:
+        context.close()

tests/e2e/test_facade_parity.py

@@ -789,3 +789,84 @@ def test_ruby_under_both_transports(transport, page, gradio_apps, speech_events)
         f"Gradio page (always {back['lastLineHeightPx']} px vs never "
         f"{never['lastLineHeightPx']} px)"
     )
+
+
+# ------------------------------------------------------- the lookup popover (plan 02-08)
+#
+# The standalone layer proved the card in a browser with no server. This row proves the
+# HOST under both transports, and proves the claim the whole feature rests on: the lookup
+# is a PURE CLIENT ACTION. The glosses ride inside the token the line already holds
+# (research § Q3), so a request counter around the taps must record nothing at all - under
+# the iframe transport too, where a naive design would have needed a new bridge call.
+
+TANAKA_TEXT = "田中さんは東京に住んでいます。"
+NAME_TOKEN = 0  # 田中さん - a name (D-12), and a word JMdict has no entry for
+VERB_TOKEN = 4  # 住んでいます - one tap unit for the whole conjugation (D-05), lemma 住む
+
+POPOVER_BOUND = "() => !!(window.Avatar && window.Avatar.__debug && window.Avatar.__debug.popover)"
+POPOVER = """
+async () => {
+  const d = await window.Avatar.getDebug();
+  return d.popover ? JSON.parse(JSON.stringify(d.popover)) : null;
+}
+"""
+AVATAR_TOKENS = "() => document.querySelectorAll('#transcript-text .turn-avatar .tok').length >= 3"
+
+
+def _tap(page, locator) -> None:
+    """Raw pointer input at the element's centre. Not ``page.click``: the card opens on
+    ``pointerup`` and dismisses on a capture-phase ``pointerdown``, so the real order of
+    the two pointer events is part of what is being proven (research Pitfall 5)."""
+    box = locator.bounding_box()
+    assert box and box["width"] > 0 and box["height"] > 0, f"nothing to tap: {box}"
+    page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
+
+
+@pytest.mark.parametrize("transport", TRANSPORTS)
+def test_lookup_popover_under_both_transports(transport, page, gradio_apps, request_counter):
+    """JPN-03 / D-05 / D-06 / D-07 / D-12: tap a word, get its card - identically inline and
+    in an iframe, and without a single network request either way."""
+    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(POPOVER_BOUND, timeout=BOOT_TIMEOUT_MS)
+    seeded = page.evaluate(POPOVER)
+    assert seeded["open"] is False and seeded["openCount"] == 0
+
+    page.fill("#text-input input", TANAKA_TEXT)
+    page.press("#text-input input", "Enter")
+    wait_for_ruby(page, AVATAR_TOKENS, TURN_TIMEOUT_MS, "the avatar's line has no tappable words")
+    _wait_settled(page)
+
+    line = page.locator("#transcript-text .turn-avatar").last
+    with request_counter(page) as seen:
+        _tap(page, line.locator(f".tok[data-token='{NAME_TOKEN}']"))
+        name = page.evaluate(POPOVER)
+        _tap(page, line.locator(f".tok[data-token='{VERB_TOKEN}']"))
+        verb = page.evaluate(POPOVER)
+        during = list(seen)
+
+    card = page.locator("#lookup-popover")
+    print(
+        f"[{transport}] tap 田中さん -> {name}\n[{transport}] tap 住んでいます -> {verb}\n"
+        f"[{transport}] requests during both taps: {during}"
+    )
+    assert name["open"] is True and name["tokenIndex"] == NAME_TOKEN
+    assert name["surface"] == "田中さん" and name["level"] == "name"
+    assert name["glossCount"] == 0
+    assert verb["open"] is True and verb["tokenIndex"] == VERB_TOKEN
+    assert verb["level"] == "N5"
+    assert verb["glossCount"] >= 1
+    assert verb["openCount"] == 2, "a tap on another word re-anchors rather than re-opening"
+    assert verb["closeCount"] == 0, "re-anchoring must not pass through a closed state"
+    assert "住む" in card.locator(".lk-lemma").text_content()
+    assert during == [], (
+        f"{transport}: the lookup issued {len(during)} request(s) - the glosses are supposed "
+        f"to ride inside the token the line already holds: {during}"
+    )
+
+    _tap(page, page.locator("#intro"))
+    closed = page.evaluate(POPOVER)
+    assert closed["open"] is False and closed["closeCount"] == 1
+    assert card.is_visible() is False