@memef1f1y/dsh-plugin-tts 0.6.1 → 0.6.3

package/lib/client.js

@@ -1,8 +1,8 @@
-// @dsh-external/dsh-plugin-tts — Client half (browser bundle).
+// @memef1f1y/dsh-plugin-tts — Client half (browser bundle).
 // Hand-written in the harness module-loader format; `require` answers the
 // platform externals (react), everything else is inlined.
 window.__ModuleLoader__.load({
-  id: "@dsh-external/dsh-plugin-tts",
+  id: "@memef1f1y/dsh-plugin-tts",
   factory: require => {
     var module = { exports: {} };
     var exports = module.exports;
@@ -18,7 +18,7 @@ window.__ModuleLoader__.load({
 
     // Bundle build tag: bump on every client fix so a console line proves
     // WHICH code is actually running (rules out stale-bundle confusion).
-    const CLIENT_BUILD = "2026-09-26.01-prewarm-skip-toast";
+    const CLIENT_BUILD = "2026-09-26.04-follow-v2";
     const apply = ctx => {
       const slots = ctx.slots ?? (typeof ctx.get === "function" ? ctx.get("slots") : undefined);
       if (!slots) throw new Error("[dsh-plugin-tts] slots service unavailable");
@@ -361,7 +361,8 @@ window.__ModuleLoader__.load({
             "overlay.showToggle": "显示全局朗读中按钮（实验性，默认关闭）",
             "overlay.showToggle.desc": "屏幕右侧显示朗读进度浮窗，可点击暂停/继续",
             "scrollFollow.label": "朗读高度跟随（实验性，默认关闭）",
-            "scrollFollow.desc": "朗读时自动滚动对话区域，使当前朗读段落保持在屏幕垂直居中位置",
+            "scrollFollow.desc": "朗读时自动滚动对话区域，使正在朗读的段落保持可见；你一动手滚动就停下，可点浮条回到跟随",
+            "follow.resume": "回到跟随",
             "footnote": "由 Microsoft Edge TTS / 本地 RVC / 本地 Index-TTS2 / 本地 CosyVoice / Google Cloud TTS 驱动。",
             "report.hint.lead": "遇到问题？点上方诊断区的「导出诊断日志」，把 JSON 附到 ",
             "report.hint.tail": " 提 issue；不方便用 GitHub 时再通过其他方式发给开发者，本地服务报错另附服务终端里的红色报错。",
@@ -740,7 +741,8 @@ window.__ModuleLoader__.load({
             "overlay.showToggle": "Show global reading indicator (experimental, off by default)",
             "overlay.showToggle.desc": "Show a floating reading progress indicator on the right side; click to pause/resume",
             "scrollFollow.label": "Auto scroll while reading (experimental, off by default)",
-            "scrollFollow.desc": "Automatically scroll the conversation so the currently reading paragraph stays vertically centred",
+            "scrollFollow.desc": "Auto-scroll the conversation to keep the spoken paragraph visible; stops the moment you scroll, resume from the floating bar",
+            "follow.resume": "Resume follow",
             "footnote": "Powered by Microsoft Edge TTS / local RVC / local Index-TTS2 / local CosyVoice / Google Cloud TTS.",
             "report.hint.lead": "Hit a bug? Export the diagnostic log in Diagnostics above and attach the JSON to ",
             "report.hint.tail": " ; if GitHub is inconvenient, send it to the developer another way. For local-service errors also paste the red traceback from the service terminal.",
@@ -980,7 +982,7 @@ window.__ModuleLoader__.load({
           seed: 0,
         },
         speaking: false,
-        diagLog: [], // one-click diagnostic log: recent speak attempts + toasts (no message text, textLen only; cap 20)
+        diagLog: [], // one-click diagnostic log: recent speak attempts + toasts (no message text, textLen only; cap 30)
         currentText: null,
         speakSource: null,
         speakToken: 0,
@@ -991,7 +993,8 @@ window.__ModuleLoader__.load({
         readingSentences: null, // array of sentence texts split from currentText (for scroll-center)
         readingSentenceIdx: 0,  // 0-based index of the sentence currently centered
         readingMsgEl: null,   // WeakRef to the message DOM node being read (anchored from the read button)
-        readingCenterOnce: false, // first follow tick centres the message (click feedback)
+        readingCenterOnce: false, // first follow tick centres the message (click-initiated reads only)
+        followHlEl: null,   // element currently carrying .dsh-tts-sentence-active (v2 block highlight)
         showReadingOverlay: false, // show the global reading progress overlay on the right (default off: follow still experimental)
         showScrollFollow: false,   // auto-scroll conversation to keep reading paragraph centred (default off: follow still experimental)
         currentJobId: null,  // active RVC chunked job, cancelled eagerly on stop
@@ -1459,7 +1462,7 @@ window.__ModuleLoader__.load({
       function logDiag(entry) {
         try {
           shared.diagLog.push(Object.assign({ at: Date.now() }, entry));
-          while (shared.diagLog.length > 20) shared.diagLog.shift();
+          while (shared.diagLog.length > 30) shared.diagLog.shift();
         } catch (e) { /* logging must never break playback */ }
       }
       function showToast(text, kind, action) {
@@ -2395,6 +2398,18 @@ window.__ModuleLoader__.load({
                 if (typeof onError === "function") onError(t("err.chunkFail") + r.error);
               } else {
                 completed = true;
+                // Silent early end (GC'd/unknown job, cancelled Host job):
+                // without this the player spins on "synthesizing…" forever
+                // with no trace. Only fires when indices never arrived — a
+                // clean drain has every queue slot filled.
+                let served = 0;
+                for (let i = 0; i < total; i++) if (queue[i] !== undefined) served++;
+                if (served < total) {
+                  try {
+                    logDiag({ kind: "chunk-early-done", text: "job " + jobId + " ended with " + served + "/" + total + " chunks served" });
+                  } catch (e) {}
+                  if (typeof onError === "function") onError(t("err.chunkFail") + " (" + served + "/" + total + ")");
+                }
               }
             })
             .catch(() => {
@@ -2601,6 +2616,18 @@ window.__ModuleLoader__.load({
                 if (typeof onError === "function") onError(t("err.chunkFail") + r.error);
               } else {
                 completed = true;
+                // Silent early end (GC'd/unknown job, cancelled Host job):
+                // without this the player spins on "synthesizing…" forever
+                // with no trace. Only fires when indices never arrived — a
+                // clean drain has every queue slot filled.
+                let served = 0;
+                for (let i = 0; i < total; i++) if (queue[i] !== undefined) served++;
+                if (served < total) {
+                  try {
+                    logDiag({ kind: "chunk-early-done", text: "job " + jobId + " ended with " + served + "/" + total + " chunks served" });
+                  } catch (e) {}
+                  if (typeof onError === "function") onError(t("err.chunkFail") + " (" + served + "/" + total + ")");
+                }
               }
             })
             .catch(() => {
@@ -2710,10 +2737,14 @@ window.__ModuleLoader__.load({
         // the chunked branch overwrites this with the real total.
         shared.chunkProgress = { index: 1, total: 1 };
         shared.readingIndex = 1;
+        shared.chunkSpans = null; // exact block spans arrive with chunked jobs (P1-3)
         // Playback-start timestamp for smooth scroll interpolation.
         shared.chunkStartedAt = Date.now();
-        // Centre the message on the first follow tick (instant feedback).
-        shared.readingCenterOnce = true;
+        // Follow engaged fresh; centre-once only for click-initiated reads —
+        // auto-read must never yank the view away from what the user reads.
+        ttsFollow.latched = true;
+        try { _ttsClearHighlight(); } catch (e) {}
+        shared.readingCenterOnce = (source === "manual");
         // New utterance: drop the previous message anchor (button clicks
         // re-anchor below; auto-read resolves on first successful lookup).
         shared.readingMsgEl = null;
@@ -2773,6 +2804,7 @@ window.__ModuleLoader__.load({
           if (Array.isArray(result.chunks) && result.chunks.length) {
             const total = result.total || result.chunks.length;
             shared.currentJobId = result.jobId || null;
+            shared.chunkSpans = Array.isArray(result.spans) ? result.spans : null;
             shared.chunkProgress = { index: 1, total };
             notify();
             // Prewarm skips happened during /speak (not at /rvc-next time),
@@ -3126,7 +3158,12 @@ window.__ModuleLoader__.load({
         ".dsh-tts-reading-overlay{position:fixed;right:16px;top:50%;transform:translateY(-50%);z-index:100;display:flex;flex-direction:column;align-items:flex-end;gap:4px;opacity:0;transition:opacity .45s cubic-bezier(.4,0,.2,1);pointer-events:none}" +
         ".dsh-tts-reading-overlay[data-visible]{opacity:1}" +
         ".dsh-tts-reading-bar{display:inline-flex;align-items:center;gap:7px;padding:6px 14px;border-radius:10px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l2);box-shadow:0 3px 16px rgba(0,0,0,.22),0 0 30px rgba(0,0,0,.08);font-size:12px;line-height:1;color:var(--dsw-alias-label-primary);white-space:nowrap;transition:transform .35s cubic-bezier(.4,0,.2,1),opacity .35s ease;transform:translateX(12px);backdrop-filter:blur(10px);-webkit-backdrop-filter:blur(10px);pointer-events:none;cursor:pointer}" +
-        ".dsh-tts-reading-overlay[data-visible] .dsh-tts-reading-bar{transform:translateX(0);pointer-events:auto}" +
+            ".dsh-tts-reading-overlay[data-visible] .dsh-tts-reading-bar{transform:translateX(0);pointer-events:auto}" +
+            // v2 block highlight (visual anchor for follow): soft background,
+            // no box-shadow (never reintroduce the shadow style).
+            ".dsh-tts-sentence-active{background:var(--dsw-alias-bg-layer-2);border-radius:6px;transition:background-color .3s ease}" +
+            // Resume-follow pill: appears only after the user latches follow off.
+            ".dsh-tts-follow-pill{margin-top:4px;padding:4px 12px;border-radius:10px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l2);box-shadow:0 3px 16px rgba(0,0,0,.22);font-size:12px;line-height:1;color:var(--dsw-alias-label-primary);white-space:nowrap;cursor:pointer}" +
         ".dsh-tts-reading-dot{width:7px;height:7px;border-radius:50%;background:var(--dsw-alias-brand-primary);flex:none;animation:dsh-tts-rpulse 1.6s ease-in-out infinite;box-shadow:0 0 6px var(--dsw-alias-brand-primary)}" +
         "@keyframes dsh-tts-rpulse{0%,100%{opacity:.35;transform:scale(.75)}50%{opacity:1;transform:scale(1.15)}}" +
         ".dsh-tts-reading-label{font-weight:600;font-variant-numeric:tabular-nums}" +
@@ -3441,6 +3478,12 @@ window.__ModuleLoader__.load({
       // classes left by older bundles.)
       let _ttsHighlightedEl = null;
       function _ttsClearHighlight() {
+        try {
+          if (shared.followHlEl) {
+            try { shared.followHlEl.classList.remove("dsh-tts-sentence-active"); } catch (e) {}
+            shared.followHlEl = null;
+          }
+        } catch (e) {}
         if (_ttsHighlightedEl) {
           try {
             _ttsHighlightedEl.classList.remove("dsh-tts-sentence-active");
@@ -3494,53 +3537,44 @@ window.__ModuleLoader__.load({
         const tip = shared.paused ? t("mini.resume")
           : (t("mini.pause") + (cp && cp.total > 1 ? " · " + (readingIdx || 0) + "/" + cp.total : ""));
 
-        // --- Scroll-follow: track live playback position ---
-        // Progress signal: single-file reads use audioEl.currentTime/duration
-        // (real position); chunked reads interpolate inside the current chunk
-        // by elapsed time (chunk length estimated from text length at ~3.6
-        // CJK chars/s, same heuristic as the server). Result is a continuous
-        // 0..1 ratio over the whole text, so the view glides instead of
-        // jumping per chunk. User scrolls yield: any manual scroll pauses
-        // follow for 5s so we never drag the view out of the user's hands.
-        const ttsUserScrollAt = { t: 0 };
-        // While true, scroll events come from our own scrollTo(), not the user.
-        const ttsSelfScroll = { on: false };
-        const ttsEstimateSec = (text) => {
-          let cjk = 0, latin = 0, other = 0;
-          const s = String(text || "");
-          for (const ch of s) {
-            const cp = ch.codePointAt(0);
-            if (cp >= 0x4e00 && cp <= 0x9fff) cjk++;
-            else if (/[A-Za-z0-9]/.test(ch)) latin++;
-            else other++;
-          }
-          return Math.max(1, cjk / 3.6 + latin / 12 + other / 4);
+        // --- Scroll-follow v2: visibility-driven minimal scrolling ---
+        // Design: docs/scroll-follow-v2.md. Block-index stepwise signal (no
+        // intra-chunk interpolation — the old equal-slice timing estimate
+        // drifted against variable-length chunks and snapped at boundaries);
+        // whole-message anchor only; scroll only when the current block
+        // leaves the viewport (block:"nearest"); user takeover latches off
+        // with manual resume; reduced-motion respected. No polling loop:
+        // evaluation runs per chunk-index change + on scroll/touch/viewport
+        // events (the old 250ms full-DOM scan forced reflow at 4Hz).
+        const ttsFollow = { latched: true, touchActive: false, selfUntil: 0 };
+        const ttsReducedMotion = () => {
+          try { return !!(window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches); } catch (e) { return false; }
         };
-        const ttsLiveRatio = () => {
+        // Which chunk is sounding (1-based). Stepwise: no fake glide inside
+        // a chunk, so pause/playback-rate can never desync the position.
+        const ttsBlockIdx = () => {
           const progress = shared.chunkProgress;
           if (!shared.speaking || !progress || !progress.total) return null;
-          const total = progress.total;
-          const idx = Math.min(Math.max(shared.readingIndex || 1, 1), total);
-          // Single audio element with known duration: exact position.
-          try {
-            const el = shared.audioEl;
-            if (el && el.duration && isFinite(el.duration) && el.duration > 0 &&
-                total <= 1 && typeof el.currentTime === "number") {
-              const r = el.currentTime / el.duration;
-              if (isFinite(r) && r >= 0) return Math.min(1, r);
-            }
-          } catch (e) {}
-          // Chunked: completed chunks + elapsed fraction of current chunk.
-          const fullText = shared.currentText || "";
-          const perChunk = ttsEstimateSec(fullText.slice(
-            Math.floor(fullText.length * (idx - 1) / total),
-            Math.floor(fullText.length * idx / total))) ||
-            ttsEstimateSec(fullText) / total;
-          const elapsed = Math.max(0, (Date.now() - (shared.chunkStartedAt || Date.now())) / 1000);
-          const frac = Math.min(1, elapsed / Math.max(1, perChunk));
-          return Math.min(1, ((idx - 1) + frac) / total);
+          return Math.min(Math.max(shared.readingIndex || 1, 1), progress.total);
+        };
+        // Approximate text sounding at block idx (equal division). Used ONLY
+        // to locate the paragraph for scroll/highlight — never for timing.
+        // Server spans (P1-3) make this exact; until then, advisory mapping.
+        const ttsBlockHead = (idx, total) => {
+          const full = shared.currentText || "";
+          if (!full || !total || total <= 0) return "";
+          // Exact server spans when present (P1-3), equal-division fallback.
+          const sp = shared.chunkSpans;
+          let slice = "";
+          if (Array.isArray(sp) && sp[idx - 1] && sp[idx - 1].length === 2 &&
+              Number.isFinite(sp[idx - 1][0]) && Number.isFinite(sp[idx - 1][1])) {
+            slice = full.slice(Math.max(0, sp[idx - 1][0]), Math.max(0, sp[idx - 1][1]));
+          } else {
+            slice = full.slice(Math.floor(full.length * (idx - 1) / total), Math.floor(full.length * idx / total));
+          }
+          return slice.replace(/\s+/g, " ").trim().slice(0, 30);
         };
-        const keepVisible = () => {
+        const ttsFollowTick = () => {
           const diag = window.__dshTtsFollowDiag || (window.__dshTtsFollowDiag = { calls: 0, last: "init", byReason: {} });
           const mark = (r) => {
             diag.calls++;
@@ -3548,12 +3582,16 @@ window.__ModuleLoader__.load({
             diag.byReason[r] = (diag.byReason[r] || 0) + 1;
           };
           if (!shared.showScrollFollow || !shared.speaking) { mark("off-or-idle"); return false; }
-          // Yield to the user for 5s after any manual scroll.
-          if (Date.now() - ttsUserScrollAt.t < 5000) { mark("user-yield"); return false; }
+          // Latched off: the user took over — stay parked until they tap
+          // "resume follow". No auto-recovery (the old 5s yield yanked the
+          // view back mid-read, the #1 follow complaint).
+          if (!ttsFollow.latched) { mark("latched-off"); return false; }
+          if (ttsReducedMotion()) { mark("reduced-motion"); return false; }
           if (shared.paused) { mark("paused"); return false; } // paused: hold still, don't drift
-          const ratio = ttsLiveRatio();
-          if (ratio == null) { mark("no-ratio"); return false; }
-          diag.ratio = ratio;
+          const idx = ttsBlockIdx();
+          const total = (shared.chunkProgress && shared.chunkProgress.total) || 0;
+          if (idx == null || !total) { mark("no-ratio"); return false; }
+          diag.idx = idx;
           try {
             const scrollEl = _ttsFindScrollContainer();
             if (!scrollEl) { mark("no-container"); return false; }
@@ -3631,108 +3669,155 @@ window.__ModuleLoader__.load({
               }
             }
             if (!msgEl) { mark("no-msgEl"); return false; }
+              mark("fragile"); // paragraph fallback: usable for this tick only,
+              // never cached as the anchor (caching it froze follow in §C).
             } else { mark("anchored"); }
-            // Cache text-resolved anchors: once a lookup finds a sane-size
-            // element, reuse it (covers auto-read which has no click anchor).
-            // Sanity: must be big enough to be a message, not a line.
-            try {
-              const h = msgEl.getBoundingClientRect ? msgEl.getBoundingClientRect().height : 0;
-              if (h > 60 && typeof WeakRef !== "undefined") shared.readingMsgEl = new WeakRef(msgEl);
-            } catch (e) {}
+            // Block locate + highlight happen below; the anchor itself is
+            // never replaced by a paragraph hit (see "fragile" above).
 
-            // Live proportional target: glides through the message as audio plays
+            // Current block: the paragraph sounding now. Searched inside the
+            // anchor by the block's head text; falls back to the anchor
+            // itself (highlighting the whole message is still truthful).
             const containerRect = scrollEl.getBoundingClientRect();
-            const msgRect = msgEl.getBoundingClientRect();
-            const msgTop = msgRect.top - containerRect.top + scrollEl.scrollTop;
-            const msgHeight = msgRect.height;
-            // Wrong-element guard (screen space!): skip only when the element
-            // is clearly a fragment — shorter than two lines, or nowhere near
-            // the viewport at all. NOTE msgTop is document coords; compare via
-            // rect delta instead (comparing msgTop against scrollTop wrongly
-            // rejected every tall message and froze follow completely).
-            const relTop = msgRect.top - containerRect.top;
-            const relBottom = msgRect.bottom - containerRect.top;
-            if (msgHeight < 40 || relBottom < -containerRect.height * 3 ||
-                relTop > containerRect.height * 3) {
+            const head = ttsBlockHead(idx, total);
+            let blockEl = msgEl;
+            if (head && head.length >= 10 && msgEl.querySelectorAll) {
+              try {
+                const cands = msgEl.querySelectorAll("p,li,div,section,blockquote,pre,td");
+                for (const c of cands) {
+                  if (c === msgEl) continue;
+                  try {
+                    if (c.querySelector && c.querySelector("p,li,div,section,blockquote,pre,td")) continue; // leaf-ish only
+                  } catch (e) {}
+                  let t = "";
+                  try { t = (c.textContent || "").trim().replace(/\s+/g, " "); } catch (e) {}
+                  if (t && t.length > 10 && t.includes(head.slice(0, 20))) { blockEl = c; break; }
+                }
+              } catch (e) {}
+            }
+            // Absurd-target guard: no box at all, or nowhere near the viewport.
+            let bRect = null;
+            try { bRect = blockEl.getBoundingClientRect(); } catch (e) {}
+            if (!bRect || !(bRect.height > 0) ||
+                bRect.bottom < containerRect.top - containerRect.height * 3 ||
+                bRect.top > containerRect.bottom + containerRect.height * 3) {
               mark("bad-target");
               diag.guard = {
-                h: Math.round(msgHeight),
-                scrollH: msgEl.scrollHeight || 0,
-                relTop: Math.round(relTop),
-                relBottom: Math.round(relBottom),
+                h: bRect ? Math.round(bRect.height) : -1,
                 contH: Math.round(containerRect.height),
-                tag: (msgEl.tagName || "?") + "." + String(msgEl.className || "").slice(0, 60),
+                tag: (blockEl.tagName || "?") + "." + String(blockEl.className || "").slice(0, 60),
               };
               return false;
             }
-            const targetY = msgTop + msgHeight * ratio;
-            diag.targetY = Math.round(targetY);
-            diag.msgH = Math.round(msgHeight);
-            const viewTop = scrollEl.scrollTop;
-            const viewBottom = viewTop + containerRect.height;
-            diag.viewTop = Math.round(viewTop);
-            // First tick after (re)anchor: centre the message unconditionally
-            // so clicking read gives instant visible feedback. Afterwards the
-            // deadband takes over for smooth tracking.
+            // Block highlight (the visual anchor follow was missing): move it
+            // as chunks advance. Whole-message fallback still truthful.
+            try {
+              const prev = shared.followHlEl;
+              if (prev && prev !== blockEl) {
+                try { prev.classList.remove("dsh-tts-sentence-active"); } catch (e) {}
+              }
+              if (blockEl.classList) {
+                try { blockEl.classList.add("dsh-tts-sentence-active"); } catch (e) {}
+                shared.followHlEl = blockEl;
+              }
+            } catch (e) {}
+            // First tick of a click-initiated read: centre once for instant
+            // feedback. (readingCenterOnce is only ever set for manual reads;
+            // auto-read never yanks the view.)
             if (shared.readingCenterOnce) {
               shared.readingCenterOnce = false;
-              const scrollTo = msgTop + msgHeight * Math.min(0.5, Math.max(0, ratio)) - containerRect.height / 2;
-              ttsSelfScroll.on = true;
+              let msgTop0 = 0;
+              let msgH0 = 0;
               try {
-                scrollEl.scrollTo({ top: Math.max(0, scrollTo), behavior: "auto" });
-              } finally {
-                setTimeout(() => { ttsSelfScroll.on = false; }, 120);
-              }
+                const msgRect0 = msgEl.getBoundingClientRect();
+                msgTop0 = msgRect0.top - containerRect.top + scrollEl.scrollTop;
+                msgH0 = msgRect0.height;
+              } catch (e) {}
+              ttsFollow.selfUntil = Date.now() + 300;
+              try {
+                scrollEl.scrollTo({ top: Math.max(0, msgTop0 + msgH0 / 2 - containerRect.height / 2), behavior: "auto" });
+              } catch (e) {}
               mark("centred");
               return true;
             }
-            // Deadband: nudge only when the live point leaves the central
-            // 50% band; small steps (no smooth-animation pile-up) so the
-            // view tracks instead of rubber-banding to a stale spot.
-            const margin = containerRect.height * 0.25;
-            if (targetY > viewTop + margin && targetY < viewBottom - margin) {
-              mark("in-view"); // comfortably visible, leave it alone
+            // Minimal scroll: fully visible (24px grace) → touch nothing.
+            // Otherwise scrollIntoView nearest = smallest move that reveals it.
+            // (Reduced-motion users never reach here: gated above.)
+            const pad = 24;
+            if (bRect.top >= containerRect.top + pad && bRect.bottom <= containerRect.bottom - pad) {
+              mark("in-view");
               return true;
             }
-            const scrollTo = targetY - containerRect.height / 2;
-            // Skip tiny corrections (<24px) to avoid jitter from estimate wobble
-            if (Math.abs(scrollTo - viewTop) < 24) { mark("tiny-skip"); return true; }
-
-            // Mark self-induced scroll so onUserScroll doesn't treat our own
-            // scrollTo() as a manual scroll (that froze follow forever: every
-            // heartbeat refreshed the 5s yield window with its own scroll).
-            ttsSelfScroll.on = true;
+            ttsFollow.selfUntil = Date.now() + 600;
             try {
-              scrollEl.scrollTo({ top: Math.max(0, scrollTo), behavior: "auto" });
-            } finally {
-              setTimeout(() => { ttsSelfScroll.on = false; }, 120);
-            }
-            mark("scrolled");
+              blockEl.scrollIntoView({ block: "nearest", behavior: "smooth" });
+            } catch (e) {}
+            mark("nearest-scrolled");
             return true;
           } catch (e) { mark("threw:" + String((e && e.message) || e).slice(0, 60)); return false; }
         };
+        // Stepwise evaluation: only chunk-index changes can move the target
+        // (no intra-chunk glide), so no polling loop is needed.
         react.useEffect(() => {
-          keepVisible();
+          ttsFollowTick();
         }, [speaking, readingIdx, cp && cp.index, shared.showScrollFollow]);
-        // Live heartbeat: 4x/sec while speaking so the view tracks the
-        // playback position continuously, not just on chunk changes.
-        // Also records manual scrolls (user takes over for 5s).
+        // Takeover detection (event-driven, no polling):
+        // - wheel with delta / touchmove gesture / pointer drag with buttons
+        //   = confirmed user intent → latch off (stays off until the resume
+        //   pill). Host autoscroll during streaming emits none of these, so
+        //   live-growing replies no longer freeze follow.
+        // - our own smooth scrollIntoView is fenced by selfUntil (cleared
+        //   early by scrollend, 600ms fallback) so it never latches us off;
+        //   momentum tails after a user flick land post-latch (no-op).
+        // - visualViewport resize (mobile URL bar) re-evaluates geometry.
         react.useEffect(() => {
           if (!speaking || !shared.showScrollFollow) return undefined;
-          const scrollEl = _ttsFindScrollContainer();
-          const onUserScroll = () => {
-            if (ttsSelfScroll.on) return; // our own scrollTo(), not the user
-            ttsUserScrollAt.t = Date.now();
+          const scrollEl = _ttsFindScrollContainer() ||
+            (typeof document !== "undefined" && document.scrollingElement) || null;
+          const isSelf = () => Date.now() < ttsFollow.selfUntil;
+          const latchOff = () => {
+            if (ttsFollow.latched) {
+              ttsFollow.latched = false;
+              try { notify(); } catch (e) {}
+            }
+          };
+          const onWheel = (e) => {
+            if (isSelf()) return;
+            try {
+              if ((e.deltaY || e.deltaX) !== 0) latchOff();
+            } catch (err) {}
           };
+          const onTouchStart = () => { ttsFollow.touchActive = true; };
+          const onTouchMove = () => { if (!isSelf()) latchOff(); };
+          const onTouchEnd = () => { ttsFollow.touchActive = false; };
+          const onPointerMove = (e) => {
+            if (isSelf()) return;
+            try { if (e.buttons && e.buttons !== 0) latchOff(); } catch (err) {}
+          };
+          const onScrollEnd = () => { ttsFollow.selfUntil = 0; };
+          const onViewResize = () => { ttsFollowTick(); };
+          const regs = [];
+          const listen = (target, type, fn) => {
+            try {
+              if (target) { target.addEventListener(type, fn, { passive: true }); regs.push([target, type, fn]); }
+            } catch (e) {}
+          };
+          listen(scrollEl, "wheel", onWheel);
+          listen(scrollEl, "touchstart", onTouchStart);
+          listen(scrollEl, "touchmove", onTouchMove);
+          listen(scrollEl, "touchend", onTouchEnd);
+          listen(scrollEl, "pointermove", onPointerMove);
+          listen(scrollEl, "scrollend", onScrollEnd);
           try {
-            if (scrollEl) scrollEl.addEventListener("scroll", onUserScroll, { passive: true });
+            if (window.visualViewport) {
+              window.visualViewport.addEventListener("resize", onViewResize);
+              regs.push([window.visualViewport, "resize", onViewResize]);
+            }
           } catch (e) {}
-          const timer = setInterval(keepVisible, 250);
           return () => {
-            clearInterval(timer);
-            try {
-              if (scrollEl) scrollEl.removeEventListener("scroll", onUserScroll);
-            } catch (e) {}
+            for (const r of regs) {
+              try { r[0].removeEventListener(r[1], r[2]); } catch (e) {}
+            }
           };
         }, [speaking, shared.showScrollFollow]);
 
@@ -3777,6 +3862,23 @@ window.__ModuleLoader__.load({
               shared.paused ? t("overlay.paused") : t("overlay.reading"),
             ),
           ),
+          // Resume-follow pill (v2 latch-off): only after the user takes over.
+          (shared.showScrollFollow && speaking && !ttsFollow.latched && !ttsReducedMotion()
+            ? react.createElement(
+              "button",
+              {
+                className: "dsh-tts-follow-pill",
+                title: t("follow.resume"),
+                onClick: (e) => {
+                  if (e) { try { if (typeof e.stopPropagation === "function") e.stopPropagation(); } catch (err) {} }
+                  ttsFollow.latched = true;
+                  try { ttsFollowTick(); } catch (err) {}
+                  try { notify(); } catch (err) {}
+                },
+              },
+              t("follow.resume"),
+            )
+            : null),
         );
       }
       slots.inject("shell.overlay", () =>
@@ -4912,6 +5014,10 @@ window.__ModuleLoader__.load({
             textLen: e.textLen,
             stage: e.stage || "",
             ms: e.ms,
+            // job-summary entries (stage "job") carry counts, not errors.
+            total: e.total,
+            served: e.served,
+            skipped: e.skipped,
             error: e.error || "",
           }));
           const clientRecent = shared.diagLog.map(e => {
@@ -4951,6 +5057,12 @@ window.__ModuleLoader__.load({
             exportedAt: new Date().toISOString(),
             ua: (() => { try { return navigator.userAgent; } catch (e) { return ""; } })(),
             plugin: (payload && payload.plugin) || null,
+            // Build tags pin down WHICH code produced the log: package
+            // versions only move on releases, so two different builds are
+            // otherwise indistinguishable (exactly what stalled the 1/3/2
+            // swap triage — the failing runs predated the fix).
+            clientBuild: CLIENT_BUILD,
+            hostBuild: (payload && payload.hostBuild) || null,
             // True when the Host predates the extended diagnose response
             // (plugin updated but dsh web not restarted): checks are valid,
             // but worker/recent/plugin are missing — re-run after a restart.