feat(02-08): word-lookup popover (reading, glosses, level, dictionary form) with published numbers

- transcript.js: openPopover / closePopover / bindPointer and a seeded debug.popover
(open, lineId, tokenIndex, surface, reading, level, glossCount, left, top, width,
insideTranscript, openCount, closeCount). The card is filled from the token record the
line already holds, so a tap issues no request of any kind
- pointerup opens, a capture-phase pointerdown on the document dismisses (so a tap on
another word re-anchors without passing through a closed state), Escape closes,
Enter/Space open the focused word, the column's scroll closes; setMode / setLevel /
setTokens close first, because a re-render replaces the anchor
- transcript.css: the card, five level-rank hues on the badge and a 1 px rank underline on
tappable words; #transcript-text becomes a real column (min-height 9em, max-height 40vh,
overflow-y auto) so "the card stayed inside the transcript" is a measurable fact
- host.js calls the renderer's bindPointer once and publishes debug.popover on __debug
- standalone rows: anchor / dismiss / re-anchor / Escape / Tab+Enter, and insideTranscript
on a 300 px scrolling column driven with real touch input

avatar/host.js

@@ -24,6 +24,11 @@
 // written only through storageRead / storageWrite, which never throw - Safari inside a
 // cross-origin iframe throws on the access itself (research Pitfall 9), and the page
 // then runs in memory with furigana.storage reporting 'unavailable'.
+//
+// Plan 02-08: the word-lookup card is the renderer's too - this file only calls
+// 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.
 
 /** Matches REARM_TAIL_MS in mic.js: the controls re-enable when the mic may re-arm. */
 const REENABLE_AFTER_SPEECH_MS = 200;
@@ -46,6 +51,23 @@ const FURIGANA_DEBUG_SEED = {
   lastLineHeightPx: 0,
 };
 
+/** The lookup card's numbers (plan 02-08), seeded for the same reason. */
+const POPOVER_DEBUG_SEED = {
+  open: false,
+  lineId: null,
+  tokenIndex: null,
+  surface: null,
+  reading: null,
+  level: null,
+  glossCount: 0,
+  left: 0,
+  top: 0,
+  width: 0,
+  insideTranscript: null,
+  openCount: 0,
+  closeCount: 0,
+};
+
 /** Enter finishes a Japanese IME composition before it submits; this skips that Enter. */
 function isComposing(event) {
   return event.isComposing || event.keyCode === 229;
@@ -116,7 +138,11 @@ export function bindHost(avatar, doc = document, transcriptModule = null) {
   // The SAME object the renderer writes to, so getDebug() reads live numbers; the facade
   // merges the turn loop's and the stage's keys over the top and leaves this one intact.
   const furigana = transcript ? transcript.debug.furigana : { ...FURIGANA_DEBUG_SEED };
-  if (avatar.__debug) avatar.__debug.furigana = furigana;
+  const popover = transcript ? transcript.debug.popover : { ...POPOVER_DEBUG_SEED };
+  if (avatar.__debug) {
+    avatar.__debug.furigana = furigana;
+    avatar.__debug.popover = popover;
+  }
 
   let spoken = false; // whether anything has been said yet, for replay/slower
   let busy = false;
@@ -265,7 +291,9 @@ export function bindHost(avatar, doc = document, transcriptModule = null) {
         if (!storageWrite(win, STORAGE_LEVEL_KEY, value)) furigana.storage = 'unavailable';
       });
     }
-    transcript.bindPointer(); // plan 02-08 fills this with the lookup popover's tap handling
+    // 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();
   }
 
   // ------------------------------------------------------------------- avatar -> page

avatar/transcript-harness.html

@@ -10,10 +10,11 @@
         margin: 16px;
         font: 16px/1.4 system-ui, sans-serif;
       }
+      /* Border and padding only: the column's height and overflow are transcript.css's, so
+         the harness measures the shape the app ships rather than one of its own. */
       #transcript-text {
         border: 1px solid #ccc;
         padding: 8px;
-        min-height: 2em;
       }
     </style>
   </head>
@@ -31,7 +32,9 @@
       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).
+      Query parameters: ?narrow=1 sets #transcript-text to a 300 px SCROLLING column - the
+      phone shape plan 02-08's popover has to stay inside, and the only way the container's
+      own scroll event (which closes the card) can fire at all.
     -->
     <div id="reading-controls" class="reading-controls">
       <label for="furigana-mode">Furigana</label>
@@ -55,12 +58,18 @@
 
       const params = new URLSearchParams(location.search);
       const container = document.getElementById('transcript-text');
-      if (params.get('narrow') === '1') container.style.width = '300px';
+      if (params.get('narrow') === '1') {
+        container.style.width = '300px';
+        container.style.maxHeight = '360px';
+        container.style.overflowY = 'auto';
+      }
 
       const t = createTranscript(container);
+      t.bindPointer();
       window.__transcript = t;
-      // The same object the renderer writes to, not a copy: a test reads live numbers.
+      // 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.__transcriptReady = false;
 
       document.getElementById('furigana-mode').addEventListener('change', (e) => {

avatar/transcript.css

@@ -8,9 +8,18 @@
  * the app through a <link> inside the transcript's gr.HTML value and by
  * avatar/transcript-harness.html relative to itself.
  */
+/* The transcript is a COLUMN with a top and a bottom, not an ever-growing block. host.js has
+ * always ended every line with `el.scrollTop = el.scrollHeight`, which is a no-op on an
+ * 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. */
 #transcript-text {
   position: relative;
   overflow-x: clip;
+  overflow-y: auto;
+  min-height: 9em;
+  max-height: 40vh;
 }
 #transcript-text .said {
   line-height: 2.1;
@@ -33,6 +42,104 @@
   background: rgba(0, 0, 0, 0.06);
   outline: none;
 }
+/* The word-level badge on the word itself (D-14): one pixel of the same rank colour under a
+ * tappable unit, so the transcript carries the level information the card spells out. */
+#transcript-text .tok[data-level] {
+  border-bottom: 1px solid rgba(0, 0, 0, 0.25);
+}
+#transcript-text .tok[data-level="N5"] {
+  border-bottom-color: #2e7d32;
+}
+#transcript-text .tok[data-level="N4"] {
+  border-bottom-color: #558b2f;
+}
+#transcript-text .tok[data-level="N3"] {
+  border-bottom-color: #f9a825;
+}
+#transcript-text .tok[data-level="N2"] {
+  border-bottom-color: #ef6c00;
+}
+#transcript-text .tok[data-level="N1"] {
+  border-bottom-color: #c62828;
+}
+
+/* ---------------------------------------------- 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
+ * inside the Hub's cross-origin frame is unverified. transcript.js sets left/top from
+ * getBoundingClientRect and clamps them into #transcript-text (which is position: relative
+ * above), so the card can never leave the column on a phone. max-height keeps a three-sense
+ * entry inside a short column; z-index 5 clears the transcript's own content only.
+ */
+#lookup-popover {
+  position: absolute;
+  max-width: min(320px, calc(100% - 16px));
+  max-height: 240px;
+  overflow-y: auto;
+  z-index: 5;
+  box-sizing: border-box;
+  padding: 8px 10px;
+  border-radius: 6px;
+  background: #fff;
+  color: #111;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.18);
+  font-size: 0.95em;
+  line-height: 1.45;
+}
+#lookup-popover .lk-head {
+  display: flex;
+  gap: 0.5em;
+  align-items: baseline;
+  flex-wrap: wrap;
+}
+#lookup-popover .lk-surface {
+  font-weight: 600;
+  font-size: 1.15em;
+}
+#lookup-popover .lk-reading {
+  color: #555;
+}
+#lookup-popover .lk-level {
+  font-size: 0.75em;
+  padding: 0 0.4em;
+  border-radius: 3px;
+  color: #fff;
+  background: #777;
+  white-space: nowrap;
+}
+#lookup-popover .lk-level[data-level="N5"] {
+  background: #2e7d32;
+}
+#lookup-popover .lk-level[data-level="N4"] {
+  background: #558b2f;
+}
+#lookup-popover .lk-level[data-level="N3"] {
+  background: #f9a825;
+}
+#lookup-popover .lk-level[data-level="N2"] {
+  background: #ef6c00;
+}
+#lookup-popover .lk-level[data-level="N1"] {
+  background: #c62828;
+}
+#lookup-popover .lk-level[data-level="N1+"],
+#lookup-popover .lk-level[data-level="name"] {
+  background: #777;
+}
+#lookup-popover .lk-lemma {
+  color: #555;
+  font-size: 0.9em;
+}
+#lookup-popover .lk-gloss {
+  margin: 0.3em 0 0;
+  padding-left: 1.2em;
+}
+#lookup-popover .lk-none {
+  color: #777;
+  font-size: 0.9em;
+  margin-top: 0.3em;
+}
+
 #reading-controls {
   display: flex;
   gap: 0.5em;

avatar/transcript.js

@@ -12,8 +12,17 @@
 // 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.
+// 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.
+//
+// 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
+// (research § Q6). Anchoring is 40 lines of getBoundingClientRect + clamp that publish
+// their numbers on debug.popover, so "it stayed inside the phone column" is an assertion
+// rather than a screenshot. Press-and-hold is deliberately not a gesture here (D-04), and
+// the card is read-only: no save, no tap history (D-08).
 //
 // 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
@@ -29,6 +38,26 @@ export const LEVELS = ['N5', 'N4', 'N3', 'N2'];
 
 const LABELS = { you: 'You: ', avatar: 'Avatar: ', slower: 'Avatar (slower): ' };
 
+/**
+ * The badge text for a token's WORD-level axis. N5..N1 read as themselves; the two values
+ * the analyser uses for "not on a list" are spelled out on the card so the learner is never
+ * told a level the data does not claim (D-10 / D-12).
+ */
+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 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). */
+const CARD_MAX_HEIGHT_PX = 240;
+
+function clamp(value, low, high) {
+  return Math.min(Math.max(value, low), high);
+}
+
 /**
  * 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
@@ -65,7 +94,7 @@ export function createTranscript(container, { doc = document } = {}) {
     furigana: {
       mode: 'always',
       level: 'N5',
-      storage: 'unknown', // host.js sets 'ok' | 'unavailable' after its localStorage probe
+      storage: 'unknown', // host.js sets 'ok' | 'unavailable' after its browser-storage probe
       lines: 0,
       rtTotal: 0,
       lastLineId: null,
@@ -74,6 +103,24 @@ export function createTranscript(container, { doc = document } = {}) {
       lastLineRtHeightPx: 0,
       lastLineHeightPx: 0,
     },
+    // The lookup card's numbers (plan 02-08, research § Q6). insideTranscript is the phone
+    // assertion: the card's rect within the column's rect. null until the first open, so
+    // "never opened" and "opened outside" are different readings.
+    popover: {
+      open: false,
+      lineId: null,
+      tokenIndex: null,
+      surface: null,
+      reading: null,
+      level: null,
+      glossCount: 0,
+      left: 0,
+      top: 0,
+      width: 0,
+      insideTranscript: null,
+      openCount: 0,
+      closeCount: 0,
+    },
   };
 
   /** lineId -> { el, said, who, text } in insertion order. */
@@ -194,13 +241,230 @@ export function createTranscript(container, { doc = document } = {}) {
    */
   function setTokens(lineId, tokens) {
     if (!lines.has(lineId)) return false;
+    closePopover(); // the line's spans are rebuilt below; the card's anchor would be stale
     tokensByLine.set(lineId, Array.isArray(tokens) ? tokens : []);
     render(lineId);
     return true;
   }
 
+  // ------------------------------------------------------------- the lookup card (02-08)
+
+  const popover = debug.popover;
+  /** Built on the first open and reused; `card.el` is the one #lookup-popover element. */
+  let card = null;
+  let pointerBound = false;
+
+  function buildCard() {
+    const el = doc.createElement('div');
+    el.id = 'lookup-popover';
+    el.className = 'lookup-popover';
+    el.setAttribute('role', 'dialog');
+    el.setAttribute('aria-label', 'Word lookup');
+    el.hidden = true;
+
+    const head = doc.createElement('div');
+    head.className = 'lk-head';
+    const surface = doc.createElement('span');
+    surface.className = 'lk-surface';
+    const reading = doc.createElement('span');
+    reading.className = 'lk-reading';
+    const badge = doc.createElement('span');
+    badge.className = 'lk-level';
+    head.append(surface, reading, badge);
+
+    const lemma = doc.createElement('div');
+    lemma.className = 'lk-lemma';
+    const gloss = doc.createElement('ol');
+    gloss.className = 'lk-gloss';
+    const none = doc.createElement('div');
+    none.className = 'lk-none';
+    none.textContent = 'no dictionary entry';
+    none.hidden = true;
+
+    el.append(head, lemma, gloss, none);
+    container.append(el);
+    card = { el, surface, reading, badge, lemma, gloss, none };
+    return card;
+  }
+
+  /**
+   * Anchor the card under (or above) the tapped word and publish where it landed.
+   *
+   * 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.
+   */
+  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`;
+    const contRect = container.getBoundingClientRect();
+    const tokRect = tokEl.getBoundingClientRect();
+    const width = el.offsetWidth;
+    const height = el.offsetHeight;
+
+    const maxLeft = Math.max(EDGE_INSET_PX, container.clientWidth - width - EDGE_INSET_PX);
+    const left = clamp(
+      tokRect.left - contRect.left - container.clientLeft,
+      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);
+    }
+
+    el.style.left = `${Math.round(left)}px`;
+    el.style.top = `${Math.round(top)}px`;
+
+    const rect = el.getBoundingClientRect();
+    popover.left = Math.round(left);
+    popover.top = Math.round(top);
+    popover.width = rect.width;
+    popover.insideTranscript =
+      rect.left >= contRect.left - 0.5 &&
+      rect.right <= contRect.right + 0.5 &&
+      rect.top >= contRect.top - 0.5 &&
+      rect.bottom <= contRect.bottom + 0.5;
+  }
+
+  /**
+   * Show the card for one token of one line, filled from THAT token's own record.
+   *
+   * Every field is written with textContent: the glosses are dictionary data and the
+   * surfaces can be anything the learner typed. Returns a copy of the published numbers.
+   *
+   * @param {string} lineId
+   * @param {number} tokenIndex the index the `.tok` carries in data-token
+   */
+  function openPopover(lineId, tokenIndex) {
+    const line = lines.get(lineId);
+    const token = (tokensByLine.get(lineId) || [])[tokenIndex];
+    if (!line || !token) return { ...popover };
+    const tokEl = line.said.querySelector(`.tok[data-token="${tokenIndex}"]`);
+    if (!tokEl) return { ...popover };
+    const c = card || buildCard();
+
+    const surface = String(token.surface ?? '');
+    const badgeValue = token.jlpt == null ? '' : String(token.jlpt);
+    c.surface.textContent = surface;
+    c.reading.textContent = String(token.reading ?? '');
+    c.badge.textContent = LEVEL_LABELS[badgeValue] ?? badgeValue;
+    c.badge.hidden = badgeValue === '';
+    if (badgeValue) c.badge.dataset.level = badgeValue;
+    else delete c.badge.dataset.level;
+
+    const lemma = String(token.lemma ?? '');
+    const showLemma = lemma !== '' && lemma !== surface;
+    c.lemma.textContent = showLemma ? `dictionary form: ${lemma}` : '';
+    c.lemma.hidden = !showLemma;
+
+    const senses = Array.isArray(token.gloss) ? token.gloss.slice(0, MAX_SENSES) : [];
+    c.gloss.replaceChildren();
+    for (const sense of senses) {
+      const item = doc.createElement('li');
+      item.textContent = Array.isArray(sense) ? sense.join('; ') : String(sense);
+      c.gloss.append(item);
+    }
+    c.gloss.hidden = senses.length === 0;
+    c.none.hidden = senses.length > 0;
+
+    c.el.hidden = false;
+    position(c.el, tokEl);
+
+    popover.open = true;
+    popover.lineId = lineId;
+    popover.tokenIndex = tokenIndex;
+    popover.surface = surface;
+    popover.reading = c.reading.textContent;
+    popover.level = badgeValue || null;
+    popover.glossCount = senses.length;
+    popover.openCount += 1;
+    return { ...popover };
+  }
+
+  /** Hide the card. A no-op (and not counted) when it is already closed. */
+  function closePopover() {
+    if (!popover.open) return { ...popover };
+    if (card) card.el.hidden = true;
+    popover.open = false;
+    popover.closeCount += 1;
+    return { ...popover };
+  }
+
+  function openFromElement(tok) {
+    const line = tok.closest('[data-line]');
+    if (!line) return null;
+    return openPopover(line.dataset.line, Number(tok.dataset.token));
+  }
+
+  /**
+   * Install the tap wiring. Idempotent: the host calls it once at bind, the standalone
+   * harness calls it too, so there is exactly one implementation of the gesture.
+   *
+   * `pointerup` on the column covers mouse, touch and pen alike, with no 300 ms delay
+   * (the page has a viewport meta and `.tok` is touch-action: manipulation). The dismiss
+   * listener is a CAPTURE-phase pointerdown on the document, so a tap on another word
+   * falls through to the pointerup above and re-anchors WITHOUT passing through a closed
+   * state. Scrolling the column moves the anchor, so it closes (research § Q6). No
+   * press-and-hold gesture exists (D-04).
+   */
+  function bindPointer() {
+    if (pointerBound) return false;
+    pointerBound = true;
+
+    container.addEventListener('pointerup', (event) => {
+      const tok = event.target?.closest?.('.tok');
+      if (!tok) return;
+      openFromElement(tok);
+    });
+
+    doc.addEventListener(
+      'pointerdown',
+      (event) => {
+        if (event.target?.closest?.('#lookup-popover, .tok')) return;
+        closePopover();
+      },
+      true
+    );
+
+    doc.addEventListener('keydown', (event) => {
+      if (event.key === 'Escape') {
+        closePopover();
+        return;
+      }
+      if (event.key !== 'Enter' && event.key !== ' ') return;
+      const tok = event.target?.closest?.('.tok');
+      if (!tok) return;
+      event.preventDefault();
+      openFromElement(tok);
+    });
+
+    container.addEventListener('scroll', () => closePopover());
+    return true;
+  }
+
   function setMode(value) {
     if (!FURIGANA_MODES.includes(value)) return mode;
+    closePopover(); // Pitfall 10: a re-render replaces the .tok the card is anchored to
     mode = value;
     debug.furigana.mode = mode;
     renderAll();
@@ -209,6 +473,7 @@ export function createTranscript(container, { doc = document } = {}) {
 
   function setLevel(value) {
     if (!LEVELS.includes(value)) return level;
+    closePopover();
     level = value;
     debug.furigana.level = level;
     renderAll();
@@ -223,9 +488,9 @@ export function createTranscript(container, { doc = document } = {}) {
     getMode: () => mode,
     getLevel: () => level,
     getTokens: (lineId) => tokensByLine.get(lineId) || null,
-    bindPointer() {
-      // plan 02-08: tap handling for .tok (the lookup popover) is installed here.
-    },
+    openPopover,
+    closePopover,
+    bindPointer,
     debug,
   };
 }

tests/e2e/test_transcript_standalone.py

@@ -34,8 +34,17 @@ STUDY_TEXT = "日本語を勉強しています。"
 STUDY_READING_FIRST = "にほんご"
 TANAKA = 13
 HELLO = 1
+# The long fixture, used to make a 300 px column scroll: 今日はいい天気ですから、公園を散歩して
+# から、買い物に行きました。 - eight tappable units, several of them with three senses.
+LONG = 25
 
 DEBUG = "() => JSON.parse(JSON.stringify(window.__transcriptDebug))"
+POPOVER = "() => JSON.parse(JSON.stringify(window.__popoverDebug))"
+
+# 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).
+PHONE_VIEWPORT = {"width": 412, "height": 839}
+NARROW_COLUMN_PX = 300
 
 
 def _units(number: int) -> list[dict]:
@@ -65,6 +74,202 @@ def _set(page, select_id: str, value: str) -> dict:
     return _debug(page)
 
 
+def _popover(page) -> dict:
+    """The card's live numbers, copied out of the object the renderer writes to."""
+    return page.evaluate(POPOVER)
+
+
+def _units_in_page(page, number: int) -> list[dict]:
+    """The fixture's records as the PAGE sees them, so a level is never hard-coded here."""
+    return page.evaluate("(n) => window.__fixtureUnits(n)", number)
+
+
+def _centre(locator) -> tuple[float, float]:
+    box = locator.bounding_box()
+    assert box and box["width"] > 0 and box["height"] > 0, f"nothing to tap: {box}"
+    return box["x"] + box["width"] / 2, box["y"] + box["height"] / 2
+
+
+def _click_token(page, index: int) -> dict:
+    """Raw pointer input on the token's centre, not ``page.click``: the popover is opened
+    on ``pointerup``, and the dismiss listener is a capture-phase ``pointerdown``, so the
+    ORDER of the two real pointer events is the thing under test (research Pitfall 5)."""
+    x, y = _centre(page.locator(f"#transcript-text .tok[data-token='{index}']").first)
+    page.mouse.click(x, y)
+    return _popover(page)
+
+
+def _container_rect(page) -> dict:
+    return page.evaluate(
+        "() => { 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 }; }"
+    )
+
+
+def _card_rect(page) -> dict:
+    return page.evaluate(
+        "() => { 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 _scroll_container(page, top) -> None:
+    page.evaluate(
+        "(t) => { const c = document.querySelector('#transcript-text');"
+        " c.scrollTop = t === null ? c.scrollHeight : t; }",
+        top,
+    )
+    page.wait_for_timeout(60)  # the scroll event is dispatched on the next frame
+
+
+def test_popover_anchors_and_dismisses(page, static_server):
+    """JPN-03 / D-05 / D-06 / D-07 / D-11 / D-12: a tap on a word opens a card built from
+    that word's OWN record - reading, dictionary form, level badge and JMdict senses - and
+    the card dismisses, re-anchors and answers the keyboard.
+
+    Every claim is a number on ``debug.popover`` cross-checked against the DOM, and the
+    level comes from the fixture record the page itself rendered (``__fixtureUnits``), never
+    from a literal here: a wrong record and a wrong badge must not be able to agree.
+    """
+    _open_harness(page, static_server)
+    line_id = _render(page, TANAKA, "avatar")
+    units = _units_in_page(page, TANAKA)
+
+    seed = _popover(page)
+    assert seed["open"] is False and seed["openCount"] == 0 and seed["insideTranscript"] is None
+
+    # 田中さん: a name (D-12), and a word JMdict has no entry for - the card says both.
+    name = _click_token(page, 0)
+    card = page.locator("#lookup-popover")
+    print(f"[standalone] tap 田中さん -> {name}; card {_card_rect(page)}")
+    assert name["open"] is True
+    assert name["lineId"] == line_id and name["tokenIndex"] == 0
+    assert name["surface"] == units[0]["surface"] == "田中さん"
+    assert name["reading"] == units[0]["reading"] == "たなかさん"
+    assert name["level"] == units[0]["jlpt"] == "name"
+    assert name["glossCount"] == 0
+    assert name["openCount"] == 1 and name["closeCount"] == 0
+    assert name["insideTranscript"] is True, name
+    assert card.is_visible()
+    assert card.get_attribute("role") == "dialog"
+    assert card.locator(".lk-surface").text_content() == "田中さん"
+    assert card.locator(".lk-level").text_content() == "name"
+    assert card.locator(".lk-level").get_attribute("data-level") == "name"
+    assert card.locator(".lk-lemma").text_content() == "dictionary form: 田中"
+    assert card.locator(".lk-gloss li").count() == 0
+    assert card.locator(".lk-none").is_visible(), "an unlisted word must say so, not show blank"
+
+    # 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()
+    page.mouse.click(cont["left"] + cont["width"] - 6, line_box["y"] + line_box["height"] / 2)
+    closed = _popover(page)
+    print(
+        f"[standalone] tap the empty column -> open={closed['open']} closes={closed['closeCount']}"
+    )
+    assert closed["open"] is False and closed["closeCount"] == 1
+    assert card.is_visible() is False
+
+    # 住んでいます: the conjugated form is one tap target (D-05) and the card names 住む.
+    verb = _click_token(page, 4)
+    print(f"[standalone] tap 住んでいます -> {verb}")
+    assert verb["open"] is True and verb["tokenIndex"] == 4
+    assert verb["surface"] == units[4]["surface"]
+    assert verb["level"] == units[4]["jlpt"], "the badge must be the record's level, not a guess"
+    assert verb["glossCount"] >= 1
+    assert verb["openCount"] == 2 and verb["insideTranscript"] is True
+    assert "住む" in card.locator(".lk-lemma").text_content()
+    assert card.locator(".lk-gloss li").count() == verb["glossCount"]
+    assert card.locator(".lk-none").is_visible() is False
+    assert card.locator(".lk-level").text_content() == units[4]["jlpt"]
+
+    page.keyboard.press("Escape")
+    escaped = _popover(page)
+    assert escaped["open"] is False and escaped["closeCount"] == 2
+    assert card.is_visible() is False
+
+    # D-11: particles and punctuation are not words. は / に / 。 are plain spans.
+    assert page.locator("#transcript-text .tok").count() == 3
+    assert page.locator("#transcript-text .plain").count() >= 3
+    tok_text = page.locator("#transcript-text .tok").all_text_contents()
+    assert "は" not in tok_text and "。" not in tok_text, tok_text
+
+    # The accessibility floor (research § Q6): Tab reaches a word, Enter opens its card.
+    page.focus("#level-select")
+    page.keyboard.press("Tab")
+    focused = page.evaluate(
+        "() => { const a = document.activeElement;"
+        " return { cls: a.className, token: a.dataset ? a.dataset.token : null }; }"
+    )
+    assert "tok" in focused["cls"], focused
+    page.keyboard.press("Enter")
+    keyed = _popover(page)
+    print(f"[standalone] Tab to {focused} + Enter -> {keyed}")
+    assert keyed["open"] is True and keyed["tokenIndex"] == int(focused["token"])
+    assert keyed["openCount"] == 3
+
+
+def test_popover_stays_inside_narrow_column(browser, static_server):
+    """D-06 on a phone: on a 300 px scrolling column, with REAL touch input, the card stays
+    inside the transcript wherever the word is - including the last word of the last line,
+    where an unflipped card would hang off the bottom.
+
+    ``page.touchscreen.tap`` on a ``has_touch`` context, not ``page.click``: Playwright's
+    click helper grants activation and dispatches a mouse sequence, which is exactly the
+    thing research Pitfall 5 warns masks phone behaviour.
+    """
+    context = browser.new_context(viewport=PHONE_VIEWPORT, has_touch=True)
+    page = context.new_page()
+    try:
+        _open_harness(page, static_server, "?narrow=1")
+        for _ in range(6):
+            _render(page, LONG, "avatar")
+        _scroll_container(page, None)
+        cont = _container_rect(page)
+        print(f"[standalone] narrow column: {cont}")
+        assert cont["scrollHeight"] > cont["clientHeight"], (
+            f"the column does not scroll, so the scroll-dismiss claim would be vacuous: {cont}"
+        )
+        assert cont["clientWidth"] <= NARROW_COLUMN_PX + 16
+
+        last_tok = page.locator("#transcript-text .turn").last.locator(".tok").last
+        page.touchscreen.tap(*_centre(last_tok))
+        bottom = _popover(page)
+        rect = _card_rect(page)
+        print(f"[standalone] tap the LAST word of the LAST line -> {bottom}; card {rect}")
+        assert bottom["open"] is True
+        assert bottom["insideTranscript"] is True, (bottom, rect, _container_rect(page))
+        assert bottom["left"] >= 0
+        assert bottom["width"] <= NARROW_COLUMN_PX, bottom
+
+        # Scrolling moves the anchor, so the card closes (research § Q6).
+        _scroll_container(page, 0)
+        after_scroll = _popover(page)
+        assert after_scroll["open"] is False and after_scroll["closeCount"] == 1
+
+        first_tok = page.locator("#transcript-text .turn").first.locator(".tok").first
+        page.touchscreen.tap(*_centre(first_tok))
+        top = _popover(page)
+        print(
+            f"[standalone] tap the FIRST word of the FIRST line -> {top}; card {_card_rect(page)}"
+        )
+        assert top["open"] is True and top["openCount"] == 2
+        assert top["insideTranscript"] is True, (top, _card_rect(page), _container_rect(page))
+        assert top["width"] <= NARROW_COLUMN_PX
+
+        _scroll_container(page, 40)
+        scrolled = _popover(page)
+        assert scrolled["open"] is False and scrolled["closeCount"] == 2
+        assert page.locator("#lookup-popover").is_visible() is False
+    finally:
+        context.close()
+
+
 def test_ruby_renders_with_numbers(page, static_server):
     """D-01: the first line renders with every kanji annotated and nothing touched.
 

tests/test_transport_seam.py

@@ -628,3 +628,65 @@ def test_host_seeds_language_debug():
     assert "__debug.furigana" in host
     for key in ("lastLineRt", "lastLineRtHeightPx", "lastLineHeightPx", "storage", "rtTotal"):
         assert f"{key}:" in host, f"host.js does not seed furigana.{key}"
+
+
+# --------------------------------------------------------- plan 02-08: the lookup popover
+#
+# The card is DOM and nothing else. Its whole claim - "instant lookup" - rests on the
+# glosses already riding inside the token record the line holds (research § Q3), so a
+# network call anywhere in this module would mean the claim is false; and D-08 says the tap
+# is read-only in Phase 2, so a browser-storage write would be a feature nobody asked for.
+
+
+def test_popover_is_dom_only_and_read_only():
+    s = src(TRANSCRIPT)
+    assert "lookup-popover" in s, "transcript.js builds no #lookup-popover element"
+    assert "openPopover" in s and "closePopover" in s
+    assert "token.gloss" in s, "the card must read the glosses off the token, not fetch them"
+
+    for forbidden in ("fetch(", "XMLHttpRequest", "localStorage", "sessionStorage"):
+        assert forbidden not in s, (
+            f"transcript.js references {forbidden!r}: the lookup is a pure client action on "
+            "data the line already holds (research § Q3), and D-08 makes it read-only"
+        )
+    # D-04: no press-and-hold reveal, so no long-press plumbing and no suppressed menu.
+    assert "contextmenu" not in s
+    assert "longpress" not in s.replace("-", "").replace("_", "").lower()
+
+    # The gesture wiring: pointerup opens (mouse, touch and pen alike) and a CAPTURE-phase
+    # pointerdown on the document dismisses, which is what lets a tap on another word
+    # re-anchor without passing through a closed state.
+    assert "'pointerup'" in s, "the open gesture must be pointerup, not click"
+    capture = re.search(r"addEventListener\(\s*'pointerdown',[\s\S]{0,600}?,\s*true\s*\)", s)
+    assert capture, "the dismiss listener is not a capture-phase pointerdown on the document"
+    assert "'Escape'" in s, "Escape must close the card"
+    assert "'scroll'" in s, "scrolling the column moves the anchor; the card must close"
+
+    # Pitfall 10: every re-render replaces the .tok the card is anchored to.
+    for signature in ("function setMode(", "function setLevel(", "function setTokens("):
+        body = "\n".join(_function_body(s, signature))
+        assert "closePopover()" in body, f"{signature} re-renders without closing the card"
+
+
+def test_popover_publishes_its_position():
+    """insideTranscript is the phone assertion (research § Q6): a card that renders outside
+    the column is invisible on a 412 px screen and passes every count-based check."""
+    s = src(TRANSCRIPT)
+    for key in ("insideTranscript", "openCount", "closeCount", "glossCount", "tokenIndex"):
+        assert f"{key}:" in s, f"transcript.js does not seed popover.{key}"
+    assert s.count("insideTranscript") >= 2, "insideTranscript is seeded but never measured"
+    assert "getBoundingClientRect" in s
+    # D-10 / D-12: the card never invents a level for a word that is on no list.
+    assert "N1+ / beyond lists" in s
+    assert "name:" in s
+
+
+def test_host_binds_pointer_once():
+    """One call, at bind, and the numbers published beside furigana's - so a deployed row
+    reads the card's state through the same getDebug() it already uses."""
+    host = src(HOST)
+    assert host.count("transcript.bindPointer()") == 1, (
+        "host.js must install the tap wiring exactly once, and only through the renderer"
+    )
+    assert host.count("__debug.popover") == 1
+    assert "lookup-popover" not in host, "the card is the renderer's DOM, not the host's"