fix(macronizer): details toggle dragged popup+summary up (M-023h.4)

Growing a popup that floats ABOVE its word extends it upward — expanding
Analysis details slid the just-clicked summary ~250px out from under the
cursor (visible on low words like "qui"). The rAF fix removed the flash but
the final position still moved.

Fix: on expand, do NOT reposition — keep the popup's top pinned and clamp the
expanded content into the room below (maxHeight = viewport - offsetTop,
overflowY:auto), so the summary stays under the cursor. Collapse restores
normal placement. Verified across 7 words: top stable within 1px on both
expand and collapse, never hidden, never out of viewport.

7 popup + 19 macronizer e2e + 22 unit + 81 IPA + 2067 golden + 348 census green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: hellpanderrr

wiktionary_pron/docs/ISSUES.md

@@ -1159,3 +1159,24 @@ stable position (no flash/jump) and no viewport overflow.
 
 **Status: FIXED.** 7 popup + 19 macronizer e2e + 22 unit + 81 IPA + 2067 golden
 + 348 census, all green.
+
+## M-023h.4 — Details toggle dragged the popup (and summary) up (2026-08-12) ✅
+
+**Symptom.** On words near the bottom (e.g. "qui" in a full sentence), clicking
+"Analysis details" made the popup jump up: the just-clicked <summary> slid
+~250px out from under the cursor. The rAF fix (h.3) removed the two-frame
+flash but the FINAL position itself moved, because growing a popup that floats
+ABOVE the word extends it upward.
+
+**Root cause.** Repositioning on expand recomputed top for the new, taller
+height — the top moved up and the popup grew away from the cursor.
+
+**Fix.** On expand, do NOT reposition: keep the popup's top pinned where it is
+and clamp the expanded content into the room below (`maxHeight = viewport -
+offsetTop`, `overflowY:auto`). The <summary> stays under the cursor; extra
+detail scrolls internally. On collapse, restore normal placement (so a stale
+tall maxHeight doesn't persist). Verified across 7 words: top stays within
+1px on both expand and collapse, never hidden, never out of viewport.
+
+**Status: FIXED.** 7 popup + 19 macronizer e2e + 22 unit + 81 IPA + 2067 golden
++ 348 census, all green.

wiktionary_pron/e2e/popup-check.spec.js

@@ -249,12 +249,12 @@ test("CSV split button exports per word (default) and per line from the dropdown
   expect(lineDownload2.suggestedFilename()).toMatch(/\.csv$/);
 });
 
-test("popup renders above the word, survives details toggle, stays in viewport", async () => {
-  // Regression for M-023h (+ .1, + .3): the popup is anchored ABOVE the word so
-  // expanding "Analysis details" grows it downward, away from the cursor. The
-  // toggle reposition must (a) not dismiss the popup, (b) stay in the viewport,
-  // and (c) settle on ONE position — a reflow race previously flashed it at the
-  // old spot then moved it. Deferring positionPopup to the next frame fixes (c).
+test("popup renders above the word, details toggle keeps it in place", async () => {
+  // Regression for M-023h (+ .1–.4): expanding "Analysis details" must NOT move
+  // the popup. Growing it upward (when floating above the word) drags the just-
+  // clicked <summary> out from under the cursor — the "popup jumps up" complaint.
+  // The fix keeps the popup's top pinned and clamps the expanded content into the
+  // space below with an internal scrollbar; collapsing restores normal placement.
   const page = sharedPage;
   test.setTimeout(300_000);
   await page.goto(PAGE);
@@ -272,7 +272,7 @@ test("popup renders above the word, survives details toggle, stays in viewport",
   expect(before.y + before.height).toBeLessThanOrEqual(wordRect.y + wordRect.height + 1);
   const summary = page.locator(".word-popup details.popup-analysis summary");
   const sb = await summary.boundingBox();
-  // sample the popup position around the click — must settle on ONE y, not flash
+  // sample the popup y around the click — the top must NOT move at all (no jump)
   const ys = [];
   const poll = (async () => {
     for (let t = 0; t < 8; t++) {
@@ -283,10 +283,15 @@ test("popup renders above the word, survives details toggle, stays in viewport",
   })();
   await page.mouse.click(sb.x + sb.width / 2, sb.y + sb.height / 2);
   await poll;
-  // still visible after the toggle reposition
+  // still visible after the toggle
   await expect(page.locator(".word-popup")).toBeVisible({ timeout: 5000 });
-  expect(new Set(ys).size).toBeLessThanOrEqual(1); // no jump
-  const box = await page.locator(".word-popup").boundingBox();
+  const unique = [...new Set(ys)];
+  expect(unique.length).toBeLessThanOrEqual(1);
+  if (unique.length) expect(Math.abs(unique[0] - Math.round(before.y))).toBeLessThanOrEqual(1);
+  // collapse restores normal placement (top comes back if it had been clamped)
+  await page.mouse.click(sb.x + sb.width / 2, sb.y + sb.height / 2);
+  await page.waitForTimeout(400);
+  const after = await page.locator(".word-popup").boundingBox();
   const vh = await page.evaluate(() => window.innerHeight);
-  expect(box.y + box.height).toBeLessThanOrEqual(vh + 1);
+  expect(after.y + after.height).toBeLessThanOrEqual(vh + 1);
 });

wiktionary_pron/macronizer.html

@@ -1345,19 +1345,22 @@ <h2 class="result-heading">Macronized</h2>
         if (!details) return;
         details.addEventListener('toggle', () => {
             if (popupEl.classList.contains('sheet')) return;
-            // Reposition for the new height — expanding may move the popup up, away
-            // from the cursor, which fires mouseleave and (on a small popup) hides it.
             // Pin while the analysis is open so reading it can't be dismissed by the
             // cursor slipping off; unpin on collapse so hover-out closes it again.
             popupPinned = details.open;
-            // Defer to the next frame: the <details> height change hasn't been laid
-            // out yet when 'toggle' fires, so offsetHeight would read the OLD (collapsed)
-            // size and we'd place the popup for the wrong height — visible as a jump
-            // (popup flashes at the old spot, then repositions) on some words.
+            // Do NOT reposition on expand: growing the popup upward (when it floats
+            // above the word) would drag the just-clicked <summary> out from under the
+            // cursor — the visible "jumps up" complaint. Instead keep the popup's top
+            // pinned where it is and clamp the expanded content into the space below
+            // with an internal scrollbar. Only the collapsed case re-runs the normal
+            // placement (so the popup doesn't keep a stale tall maxHeight).
             requestAnimationFrame(() => {
-                if (popupEl.style.display === 'block' && !popupEl.classList.contains('sheet')) {
-                    positionPopup(popupSpan);
-                }
+                if (popupEl.style.display !== 'block' || popupEl.classList.contains('sheet')) return;
+                if (!details.open) { positionPopup(popupSpan); return; }
+                const MARGIN = 8;
+                const roomBelow = window.innerHeight - popupEl.offsetTop - MARGIN;
+                popupEl.style.maxHeight = Math.max(120, roomBelow) + 'px';
+                popupEl.style.overflowY = 'auto';
             });
         });
     }