@commentray/render 0.1.2 → 0.3.0

package/dist/code-browser-client.js

@@ -1,14 +1,19 @@
 import { FuzzySearcher, PrefixSearcher, Query, SearcherFactory, SubstringSearcher, } from "@m31coding/fuzzy-search";
-import { activeBlockIdForCommentrayLine0, activeBlockIdForViewport, clampViewportYToGutterLocal, codeLineDomIndex0, dedupeBlockScrollLinksById, gutterRayBezierPaths, maxRenderableCommentaryContentBottomViewport, nextBlockLinkInCommentrayOrder, sortBlockLinksBySource, } from "./code-browser-block-rays.js";
-import { mirroredScrollTop, pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./code-browser-scroll-sync.js";
+import { activeBlockIdForCommentrayLine0, activeBlockIdForViewport, clampViewportYToGutterLocal, codeLineDomIndex0, dedupeBlockScrollLinksById, gutterRayBezierPaths, commentaryGutterDocBandBottomViewport, maxRenderableCommentaryContentBottomViewport, nextBlockLinkInCommentrayOrder, sortBlockLinksBySource, } from "./code-browser-block-rays.js";
+import { blockStrictlyContainingSourceViewportLine, mirroredScrollTop, pickBlockScrollLinkForCommentrayScroll, sourceTopLineStrictlyBeforeFirstIndexLine, } from "./code-browser-scroll-sync.js";
 import { maxCommentrayAnchorLine0AtOrAboveViewportY } from "./commentray-anchor-viewport-probe.js";
 import { decodeBase64Utf8 } from "./code-browser-encoding.js";
 import { readEmbeddedRawB64Strings } from "./code-browser-embedded-payload.js";
 import { escapeHtmlHighlightingSearchTokens, filterPairsByDocumentedTreeQuery, findOrderedTokenSpans, lineAtIndex, offsetToLineIndex, pathRowsFromDocumentedPairs, tokenizeQuery, uniqueSourceFilePreviewRows, } from "./code-browser-search.js";
-import { findDocumentedPair, isHubRelativeStaticBrowseHref, isSameDocumentedPair, normPosixPath, resolveStaticBrowseHref, siteRootPathnameFromPathname, staticBrowseHrefForShellDataAttribute, } from "./code-browser-pair-nav.js";
+import { findDocumentedPair, isHubRelativeStaticBrowseHref, isSameDocumentedPair, normPosixPath, resolveStaticBrowseHref, staticBrowseHrefForShellDataAttribute, } from "./code-browser-pair-nav.js";
 import { COMMENTRAY_COLOR_THEME_STORAGE_KEY, applyCommentrayColorTheme, nextCommentrayColorThemeMode, parseCommentrayColorThemeMode, } from "./code-browser-color-theme.js";
+import { shouldRevertPartnerScrollForMonotonicity } from "./code-browser-scroll-sync-monotonic.js";
+import { SMOOTH_REVEAL_INFLIGHT_DEDUP_MS } from "./code-browser-smooth-reveal-dedup.js";
+import { parseDualPaneScrollSyncStrategy } from "./code-browser-scroll-sync-strategy.js";
+import { DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX, READING_LEAD_ALIGN_TOLERANCE_CSS_PX, READING_VIEWPORT_BOTTOM_EDGE_CSS_PX, readingViewportTopInsetCssPx, } from "./reading-viewport-comfort.js";
 import { wireWideModeIntroTour } from "./code-browser-wide-intro-controller.js";
 import { readWebStorageItem, writeWebStorageItem } from "./code-browser-web-storage.js";
+import { dispatchCommentrayMermaidDone, wireBlockStretchBufferSync, } from "./block-stretch-buffer-sync.js";
 /**
  * Hub pages emit `./browse/…` relative to the site root. From `/…/browse/current.html` the browser
  * would otherwise resolve that to `…/browse/browse/…`.
@@ -27,7 +32,7 @@ function rewriteHubRelativeBrowseAnchorsIn(root) {
 }
 function runMermaidOnFreshDocNodes(docBody) {
     if (typeof globalThis.location !== "undefined" && globalThis.location.protocol === "file:")
-        return;
+        return Promise.resolve();
     /** Only fenced diagram sources; Mermaid leaves other `.mermaid` nodes in the tree after render. */
     const allPres = Array.from(docBody.querySelectorAll("pre.mermaid"));
     /** Do not re-run on wrappers that already have SVG (avoids corrupting output after dual-mobile pane flip). */
@@ -36,12 +41,17 @@ function runMermaidOnFreshDocNodes(docBody) {
         return wrap === null || wrap.querySelector("svg") === null;
     });
     if (nodes.length === 0)
-        return;
+        return Promise.resolve();
     const m = globalThis
         .commentrayMermaid;
     if (!m)
-        return;
-    void m.run({ nodes }).catch((err) => {
+        return Promise.resolve();
+    return m
+        .run({ nodes })
+        .then(() => {
+        dispatchCommentrayMermaidDone();
+    })
+        .catch((err) => {
         console.error("Commentray: mermaid.run failed", err);
     });
 }
@@ -54,7 +64,14 @@ function scrollTopToAlignChildTop(scrollEl, child, leadCssPx) {
     const sr = scrollEl.getBoundingClientRect();
     return scrollEl.scrollTop + (cr.top - sr.top) - scrollEl.clientTop - leadCssPx;
 }
-/** Avoid feedback loops when sub-pixel math matches the current position (common with browser zoom). */
+/**
+ * Partner write for **proportional** mirror plans (`mirrorI` / `mirrorW`), which produce a fresh
+ * target on every driver scroll event. Must be **instant** — wrapping these in `behavior: "smooth"`
+ * makes the partner re-ease toward a moving target each frame, which the eye reads as up/down
+ * jitter while the user keeps scrolling. Block snaps also use instant writes (see
+ * {@link applyRevealChildInPane} and `docs/spec/dual-pane-scroll-sync.md`). Sub-pixel skip avoids
+ * feedback loops when zoom math matches the current position.
+ */
 function applyScrollTopClamped(scrollEl, nextTop) {
     const maxY = Math.max(0, scrollEl.scrollHeight - scrollEl.clientHeight);
     const clamped = clamp(nextTop, 0, maxY);
@@ -75,6 +92,41 @@ function rootScrollingElement() {
         return s;
     return document.documentElement;
 }
+function readPaneVerticalScroll(pane) {
+    return paneUsesInternalYScroll(pane) ? pane.scrollTop : rootScrollingElement().scrollTop;
+}
+/** Monotonic revert must not use {@link applyScrollTopClamped}’s sub-pixel skip, or the partner never moves back. */
+function writePaneVerticalScrollForced(partnerPane, target) {
+    if (paneUsesInternalYScroll(partnerPane)) {
+        const maxY = Math.max(0, partnerPane.scrollHeight - partnerPane.clientHeight);
+        partnerPane.scrollTop = clamp(target, 0, maxY);
+        return;
+    }
+    const root = rootScrollingElement();
+    const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+    root.scrollTop = clamp(target, 0, maxY);
+}
+/**
+ * Enforces dual-pane scroll sync monotonicity (`docs/spec/dual-pane-scroll-sync.md`):
+ * partner never moves opposite the driver on a decisive scroll step.
+ */
+function enforceScrollSyncMonotonic(args) {
+    const { driverDelta, partnerBefore, partnerPane, axis } = args;
+    const partnerAfter = readPaneVerticalScroll(partnerPane);
+    if (shouldRevertPartnerScrollForMonotonicity({ driverDelta, partnerBefore, partnerAfter })) {
+        if (scrollSyncTraceFeatureFlag()) {
+            globalThis.console.warn("[commentray:scroll-sync] monotonic.revert", {
+                t: Math.round(performance.now()),
+                axis: axis ?? "?",
+                driverDelta,
+                partnerBefore,
+                partnerAfter,
+            });
+        }
+        writePaneVerticalScrollForced(partnerPane, partnerBefore);
+    }
+}
+/** Window-root counterpart of {@link applyScrollTopClamped} for the narrow single-flow layout — same instant-vs-jitter rationale. */
 function applyWindowScrollRatio(ratio) {
     const root = rootScrollingElement();
     const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
@@ -86,10 +138,16 @@ function applyWindowScrollRatio(ratio) {
 /**
  * Reveal `child` near the top of the reading surface: the pane’s own scrollport when it scrolls
  * internally (desktop dual-pane), otherwise the document root (narrow flow layout).
+ *
+ * **Always instant** (`scrollTop` / `scrollTo` auto): smooth interpolation on a partner pane during
+ * bidirectional sync multiplies `scroll` events, shrinks the useful echo-suppression window, and
+ * fights {@link enforceScrollSyncMonotonic} — reads as rubber-band / desync. See
+ * `docs/spec/dual-pane-scroll-sync.md` (“Scroll-behavior on dual-pane scrollports”).
  */
 function applyRevealChildInPane(scrollport, child, leadCssPx) {
     if (paneUsesInternalYScroll(scrollport)) {
-        applyScrollTopClamped(scrollport, Math.round(scrollTopToAlignChildTop(scrollport, child, leadCssPx)));
+        const target = Math.round(scrollTopToAlignChildTop(scrollport, child, leadCssPx));
+        applyScrollTopClamped(scrollport, target);
         return;
     }
     const root = rootScrollingElement();
@@ -101,23 +159,228 @@ function applyRevealChildInPane(scrollport, child, leadCssPx) {
         return;
     root.scrollTop = clamped;
 }
+/**
+ * True when `child` is already placed like {@link applyRevealChildInPane} would (same few-pixel
+ * tolerance as code→doc’s {@link commentrayBlockAnchorAlignedWithLead}).
+ */
+function revealTargetAlreadyAtLead(scrollport, child, leadCssPx) {
+    if (paneUsesInternalYScroll(scrollport)) {
+        const cr = child.getBoundingClientRect();
+        const sr = scrollport.getBoundingClientRect();
+        const dist = cr.top - sr.top - scrollport.clientTop;
+        return Math.abs(dist - leadCssPx) <= READING_LEAD_ALIGN_TOLERANCE_CSS_PX;
+    }
+    const cr = child.getBoundingClientRect();
+    return Math.abs(cr.top - leadCssPx) <= READING_LEAD_ALIGN_TOLERANCE_CSS_PX;
+}
+/** True when the block anchor for `mdLine0` is already aligned like {@link applyRevealChildInPane} would. */
+function commentrayBlockAnchorAlignedWithLead(docPane, mdLine0, leadCssPx) {
+    const anchor = docPane.querySelector(`[data-commentray-line="${String(mdLine0)}"]`);
+    if (!(anchor instanceof HTMLElement))
+        return false;
+    return revealTargetAlreadyAtLead(docPane, anchor, leadCssPx);
+}
+/** Resolve the code line element used for doc→code block snaps (same lookup as {@link applyDocToCodeFlipPlanImpl}). */
+function findCodeLineElementForBlockSnap(codePane, lineIdPrefix, src0) {
+    const exact = codePane.querySelector(`#${lineIdPrefix}${String(src0)}`);
+    if (exact instanceof HTMLElement)
+        return exact;
+    return findAnchorAtOrAfter(sourceAnchorsFromPrefix(lineIdPrefix), src0);
+}
+/** True when the source line for `src0` is already aligned like {@link applyRevealChildInPane} would. */
+function sourceCodeLineAnchorAlignedWithLead(codePane, lineIdPrefix, src0, leadCssPx) {
+    const el = findCodeLineElementForBlockSnap(codePane, lineIdPrefix, src0);
+    if (!el)
+        return false;
+    return revealTargetAlreadyAtLead(codePane, el, leadCssPx);
+}
+/** If the code line head is already at the block-snap lead, doc→code should not re-issue a reveal (symmetric with code→doc). */
+function docToCodePlanIfCodeAnchorAlreadyAligned(codePane, lineIdPrefix, src0, traceReason, extraFields) {
+    if (!sourceCodeLineAnchorAlignedWithLead(codePane, lineIdPrefix, src0, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX)) {
+        return null;
+    }
+    scrollSyncTrace("doc→code.plan", {
+        reason: traceReason,
+        ...extraFields,
+        src0,
+        lineIdPrefix,
+    });
+    return { k: "noop", skipProportionalFallbackOnFlip: true };
+}
+/**
+ * After the strict `[lo, hiExclusive)` span ends, keep treating the same block as active for a few
+ * more source lines so `line1` probe noise at the boundary does not flip code→doc between block
+ * snap and gap mirror every frame.
+ */
+const SOURCE_BLOCK_TRAILING_SLACK_LINES = 6;
+function blockForCodeToDocSync(links, line1, sticky) {
+    const strict = blockStrictlyContainingSourceViewportLine(links, line1);
+    if (strict)
+        return strict;
+    const id = sticky.sourceSticky.lockedId;
+    if (id === null)
+        return null;
+    const b = links.find((x) => x.id === id);
+    if (!b)
+        return null;
+    const { lo, hiExclusive } = b.markerViewportHalfOpen1Based;
+    const slack = SOURCE_BLOCK_TRAILING_SLACK_LINES;
+    if (line1 >= lo && line1 < hiExclusive + slack)
+        return b;
+    return null;
+}
 function windowScrollRatio() {
     const root = rootScrollingElement();
     const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
     return maxY > 0 ? clamp(root.scrollTop / maxY, 0, 1) : 0;
 }
+const SCROLL_SYNC_DEBUG_FLAG = "commentrayDebugScroll";
+function scrollSyncDebugQueryOn() {
+    const v = new URLSearchParams(globalThis.location.search).get(SCROLL_SYNC_DEBUG_FLAG);
+    return v === "1" || v === "true" || v === "";
+}
+function scrollSyncDebugStorageOn(s) {
+    try {
+        const v = s.getItem(SCROLL_SYNC_DEBUG_FLAG);
+        return v === "1" || v === "true";
+    }
+    catch {
+        return false;
+    }
+}
+function scrollSyncDebugHashOn() {
+    const h = globalThis.location.hash;
+    return h === `#${SCROLL_SYNC_DEBUG_FLAG}` || h === `#${SCROLL_SYNC_DEBUG_FLAG}=1`;
+}
+/**
+ * True on common dev hostnames (`commentray serve`, local preview). Used only for the one-line
+ * boot banner — **not** for high-volume per-scroll tracing (that stays opt-in below).
+ */
+function scrollSyncDebugDevHostOn() {
+    const host = globalThis.location.hostname;
+    return host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "::1";
+}
+/**
+ * High-volume scroll-sync tracing (`scrollSyncTrace`, `wire.*.driver`, plan/apply lines): opt-in
+ * only via URL, hash, or Web Storage — **not** implied by localhost alone (keeps DevTools quiet
+ * during normal reading).
+ *
+ * Turn on any one of:
+ * - Query: `?commentrayDebugScroll=1` (or `=true`, or present with an empty value)
+ * - Hash: `#commentrayDebugScroll` or `#commentrayDebugScroll=1` (fragment is not sent to the server)
+ * - DevTools, then reload: `sessionStorage.setItem("commentrayDebugScroll", "1")` or the same for `localStorage`
+ *
+ * Log lines (filter DevTools console on `[commentray:scroll-sync]`):
+ * - `code→doc.plan` / `doc→code.plan` — which branch built the flip plan (`reason` field)
+ * - `code→doc.apply` / `doc→code.apply` — partner `scrollTop` before vs after apply, `driverDelta`, `plan`
+ * - `wire.code.driver` / `wire.doc.driver` — RAF-coalesced driver flush (delta, pane `scrollTop`)
+ * - `wire.code.flush-skipped` / `wire.doc.flush-skipped` — flush skipped (`partner-echo` throttled ~5/s; `sync-in-progress` immediate)
+ * - `monotonic.revert` — `console.warn` when the partner move was opposite the driver and was rolled back
+ *
+ * Tracing consults a **cached feature flag** (rechecked at most every 500ms and on `hashchange` /
+ * cross-tab `storage`) so hot scroll paths avoid reading storage every tick.
+ */
+function scrollSyncVerboseTraceEnabled() {
+    try {
+        if (scrollSyncDebugQueryOn())
+            return true;
+        if (scrollSyncDebugHashOn())
+            return true;
+        if (scrollSyncDebugStorageOn(globalThis.sessionStorage))
+            return true;
+        if (scrollSyncDebugStorageOn(globalThis.localStorage))
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Throttle for re-reading URL/storage into {@link scrollSyncTraceFeatureOn}. */
+const SCROLL_SYNC_TRACE_FLAG_RECHECK_MS = 500;
+/**
+ * Feature flag for scroll-sync tracing: mirrors {@link scrollSyncVerboseTraceEnabled} but cached so
+ * high-frequency scroll paths do not hit Web Storage on every event.
+ */
+let scrollSyncTraceFeatureOn = false;
+let scrollSyncTraceFeatureLastCheckMs = -Infinity;
+function invalidateScrollSyncTraceFeatureFlag() {
+    scrollSyncTraceFeatureLastCheckMs = -Infinity;
+}
+function scrollSyncTraceFeatureFlag() {
+    const now = performance.now();
+    if (now - scrollSyncTraceFeatureLastCheckMs < SCROLL_SYNC_TRACE_FLAG_RECHECK_MS) {
+        return scrollSyncTraceFeatureOn;
+    }
+    scrollSyncTraceFeatureLastCheckMs = now;
+    scrollSyncTraceFeatureOn = scrollSyncVerboseTraceEnabled();
+    return scrollSyncTraceFeatureOn;
+}
+if (typeof globalThis.addEventListener === "function") {
+    globalThis.addEventListener("hashchange", invalidateScrollSyncTraceFeatureFlag);
+    globalThis.addEventListener("storage", invalidateScrollSyncTraceFeatureFlag);
+}
+/**
+ * Boot announcement: **always** fires on dev hosts so a stale bundle is impossible to miss.
+ * On production hosts it still fires only when the opt-in flag is on. Uses `console.log`
+ * (visible at the default DevTools "Default" level filter) so a Verbose toggle is not required.
+ */
+function announceScrollSyncTraceOnBoot() {
+    const devHost = scrollSyncDebugDevHostOn();
+    const traceVerbose = scrollSyncVerboseTraceEnabled();
+    if (!devHost && !traceVerbose)
+        return;
+    globalThis.console.log("[commentray:scroll-sync] boot", {
+        t: Math.round(performance.now()),
+        href: globalThis.location.href,
+        devHost,
+        traceVerbose,
+    });
+}
+/**
+ * Structured scroll-sync log line when {@link scrollSyncTraceFeatureFlag} is on. Tags you can filter on:
+ * - `code→doc.plan` — branch taken inside {@link buildCodeToDocFlipPlanBlockAware} (`reason` explains why)
+ * - `doc→code.plan` — branch inside {@link buildDocToCodeFlipPlanBlockAware}
+ * - `code→doc.apply` / `doc→code.apply` — partner `scrollTop` before/after apply for that driver step
+ * - `wire.code.flush-skipped` / `wire.doc.flush-skipped` — RAF driver flush skipped (echo gate or `syncing`)
+ * - `wire.code.driver` / `wire.doc.driver` — driver pane ran sync this frame (`delta`, `scrollTop`)
+ * - `monotonic.revert` — emitted with `console.warn` (see {@link enforceScrollSyncMonotonic})
+ */
+function scrollSyncTrace(tag, fields) {
+    if (!scrollSyncTraceFeatureFlag())
+        return;
+    globalThis.console.log(`[commentray:scroll-sync] ${tag}`, {
+        t: Math.round(performance.now()),
+        ...fields,
+    });
+}
+function formatDocToCodePlanForLog(p) {
+    if (p.k === "noop") {
+        return p.skipProportionalFallbackOnFlip === true ? "noop(skipFlipFallback)" : "noop";
+    }
+    if (p.k === "block")
+        return `block(src0=${String(p.src0)})`;
+    if (p.k === "mirrorW")
+        return `mirrorW(ratio=${p.ratio.toFixed(4)})`;
+    return `mirrorI(docTop=${String(p.docTop)})`;
+}
+function formatCodeToDocPlanForLog(p) {
+    if (p.k === "noop")
+        return "noop";
+    if (p.k === "block")
+        return `block(mdLine0=${String(p.mdLine0)})`;
+    if (p.k === "mirrorW")
+        return `mirrorW(ratio=${p.ratio.toFixed(4)})`;
+    return `mirrorI(codeTop=${String(p.codeTop)})`;
+}
 function applyDocToCodeFlipPlanImpl(codePane, _docPane, plan, lineIdPrefix = "code-line-") {
+    if (plan.k === "noop")
+        return;
     const narrowSinglePane = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ).matches;
     if (plan.k === "block") {
-        const exact = codePane.querySelector(`#${lineIdPrefix}${String(plan.src0)}`);
-        const el = exact instanceof HTMLElement
-            ? exact
-            : findAnchorAtOrAfter(sourceAnchorsFromPrefix(lineIdPrefix), plan.src0);
+        const el = findCodeLineElementForBlockSnap(codePane, lineIdPrefix, plan.src0);
         if (el) {
-            applyRevealChildInPane(codePane, el, 2);
-        }
-        else {
-            applyWindowScrollRatio(plan.winRatio);
+            applyRevealChildInPane(codePane, el, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX);
         }
         return;
     }
@@ -146,13 +409,12 @@ function applyDocToCodeFlipPlanImpl(codePane, _docPane, plan, lineIdPrefix = "co
     applyWindowScrollRatio(clamp(nextTop / denom, 0, 1));
 }
 function applyCodeToDocFlipPlanImpl(_codePane, docPane, plan) {
+    if (plan.k === "noop")
+        return;
     if (plan.k === "block") {
         const anchor = docPane.querySelector(`[data-commentray-line="${String(plan.mdLine0)}"]`);
         if (anchor instanceof HTMLElement) {
-            applyRevealChildInPane(docPane, anchor, 2);
-        }
-        else {
-            applyWindowScrollRatio(plan.winRatio);
+            applyRevealChildInPane(docPane, anchor, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX);
         }
         return;
     }
@@ -174,45 +436,254 @@ function applyCodeToDocFlipPlanImpl(_codePane, docPane, plan) {
     const denom = Math.max(1, docPane.scrollHeight - docPane.clientHeight);
     applyWindowScrollRatio(clamp(nextTop / denom, 0, 1));
 }
-function buildDocToCodeFlipPlanBlockAware(docPane, getLinks) {
+function resetBlockScrollStickyIfLinksChanged(sticky, links) {
+    const key = links.map((l) => l.id).join("\0");
+    if (key !== sticky.linksKey.current) {
+        sticky.sourceSticky.lockedId = null;
+        sticky.commentraySticky.lockedId = null;
+        sticky.linksKey.current = key;
+    }
+}
+function tryDocToCodeFlipPlanFromMdProbe(codePane, links, sticky, lineIdPrefix, winRatio, mdLine0) {
+    if (mdLine0 === null)
+        return null;
+    const block = pickBlockScrollLinkForCommentrayScroll(links, mdLine0);
+    const src0 = block !== null ? block.markerViewportHalfOpen1Based.lo - 1 : null;
+    if (block !== null) {
+        sticky.commentraySticky.lockedId = block.id;
+    }
+    if (src0 === null)
+        return null;
+    const alignedNoop = docToCodePlanIfCodeAnchorAlreadyAligned(codePane, lineIdPrefix, src0, "block-code-anchor-already-aligned-noop", { mdLine0, blockId: block?.id ?? null });
+    if (alignedNoop)
+        return alignedNoop;
+    const plan = { k: "block", src0, winRatio };
+    scrollSyncTrace("doc→code.plan", {
+        reason: "block-from-md-probe",
+        plan: formatDocToCodePlanForLog(plan),
+        mdLine0,
+        blockId: block?.id ?? null,
+        markerSpan: block?.markerViewportHalfOpen1Based ?? null,
+    });
+    return plan;
+}
+function tryDocToCodeFlipPlanFromPageBreakPull(docPane, codePane, lineIdPrefix, winRatio, mdLine0) {
+    const pulledSrc0 = pulledSourceLine0FromPageBreak(docPane);
+    if (pulledSrc0 === null)
+        return null;
+    const pbAlignedNoop = docToCodePlanIfCodeAnchorAlreadyAligned(codePane, lineIdPrefix, pulledSrc0, "page-break-pull-code-anchor-already-aligned-noop", { mdLine0, pulledSrc0 });
+    if (pbAlignedNoop)
+        return pbAlignedNoop;
+    const plan = { k: "block", src0: pulledSrc0, winRatio };
+    scrollSyncTrace("doc→code.plan", {
+        reason: "page-break-pull",
+        plan: formatDocToCodePlanForLog(plan),
+        pulledSrc0,
+        mdLine0,
+    });
+    return plan;
+}
+function buildDocToCodeFlipPlanBlockAware(docPane, codePane, getLinks, sticky, lineIdPrefix, allowProportionalMirror) {
     const winRatio = paneUsesInternalYScroll(docPane)
         ? clamp(docPane.scrollTop / Math.max(1, docPane.scrollHeight - docPane.clientHeight), 0, 1)
         : windowScrollRatio();
-    const pulledSrc0 = pulledSourceLine0FromPageBreak(docPane);
-    if (pulledSrc0 !== null)
-        return { k: "block", src0: pulledSrc0, winRatio };
+    /**
+     * Block info is authoritative — `pulledSourceLine0FromPageBreak` is "active" for the entire span
+     * from a page-break element to its `nextAnchor`, which can cover whole blocks. If we let the
+     * page-break heuristic run first, it snaps code far forward (e.g. to the next segment's source
+     * line) while the doc viewport is still genuinely inside an earlier block; the later real-block
+     * resolution is then opposite the prior snap and `enforceScrollSyncMonotonic` reverts it, so
+     * code gets stuck hundreds of pixels ahead of the doc. Only fall back to `page-break-pull`
+     * when no indexed block matches the doc viewport (true inter-block / inter-segment gap).
+     */
     const links = getLinks();
+    resetBlockScrollStickyIfLinksChanged(sticky, links);
     const mdLine0 = probeCommentrayLine0FromDoc(docPane);
-    const src0 = pickSourceLine0ForCommentrayScroll(links, mdLine0);
-    if (src0 !== null)
-        return { k: "block", src0, winRatio };
+    const fromMd = tryDocToCodeFlipPlanFromMdProbe(codePane, links, sticky, lineIdPrefix, winRatio, mdLine0);
+    if (fromMd !== null)
+        return fromMd;
+    const fromPb = tryDocToCodeFlipPlanFromPageBreakPull(docPane, codePane, lineIdPrefix, winRatio, mdLine0);
+    if (fromPb !== null)
+        return fromPb;
+    /**
+     * Index-backed pair but no confident block anchor for this viewport (e.g. missing
+     * `.commentray-block-anchor` nodes, or probe could not map the doc band to a link).
+     * With {@link allowProportionalMirror}, mirror like the no-index path so static dual
+     * browse still scrolls both panes together; block-snap-only keeps the historical noop.
+     */
+    if (links.length > 0) {
+        scrollSyncTrace("doc→code.plan", {
+            reason: allowProportionalMirror
+                ? "indexed-fallback-mirror-no-confident-block"
+                : "indexed-noop-no-src0",
+            mdLine0,
+            linkCount: links.length,
+            allowProportionalMirror,
+        });
+        if (!allowProportionalMirror) {
+            return { k: "noop" };
+        }
+    }
+    else if (!allowProportionalMirror) {
+        scrollSyncTrace("doc→code.plan", { reason: "snap-only-no-index-noop", linkCount: 0 });
+        return { k: "noop" };
+    }
     if (paneUsesInternalYScroll(docPane)) {
-        return {
+        const plan = {
             k: "mirrorI",
             docTop: docPane.scrollTop,
             docSH: docPane.scrollHeight,
             docCH: docPane.clientHeight,
         };
+        scrollSyncTrace("doc→code.plan", {
+            reason: "no-index-mirror-internal",
+            plan: formatDocToCodePlanForLog(plan),
+        });
+        return plan;
+    }
+    const plan = { k: "mirrorW", ratio: winRatio };
+    scrollSyncTrace("doc→code.plan", {
+        reason: "no-index-mirror-window",
+        plan: formatDocToCodePlanForLog(plan),
+    });
+    return plan;
+}
+/** Mirror plan for the current source pane geometry — internal scroller (`mirrorI`) or window flow (`mirrorW`). */
+function codeMirrorPlan(codePane, winRatio) {
+    if (paneUsesInternalYScroll(codePane)) {
+        return {
+            k: "mirrorI",
+            codeTop: codePane.scrollTop,
+            codeSH: codePane.scrollHeight,
+            codeCH: codePane.clientHeight,
+        };
     }
     return { k: "mirrorW", ratio: winRatio };
 }
-function buildCodeToDocFlipPlanBlockAware(codePane, _docPane, getLinks, lineIdPrefix = "code-line-") {
+/** Source viewport sits **above** every indexed span — pin partner to the very first block head. */
+function preludeBlockAwareCodeToDocPlan(links, docPane, sticky, line1, lineIdPrefix, winRatio) {
+    const sorted = [...links].sort((a, b) => a.markerViewportHalfOpen1Based.lo - b.markerViewportHalfOpen1Based.lo);
+    const first = sorted[0];
+    if (!first) {
+        scrollSyncTrace("code→doc.plan", { reason: "prelude-missing-first-link", line1, lineIdPrefix });
+        return { k: "noop" };
+    }
+    sticky.sourceSticky.lockedId = first.id;
+    const mdLine0 = first.commentrayLine;
+    if (commentrayBlockAnchorAlignedWithLead(docPane, mdLine0, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX)) {
+        scrollSyncTrace("code→doc.plan", {
+            reason: "prelude-anchor-already-aligned-noop",
+            line1,
+            blockId: first.id,
+            mdLine0,
+        });
+        return { k: "noop" };
+    }
+    const plan = { k: "block", mdLine0, winRatio };
+    scrollSyncTrace("code→doc.plan", {
+        reason: "prelude-first-block",
+        line1,
+        blockId: first.id,
+        mdLine0,
+        plan: formatCodeToDocPlanForLog(plan),
+    });
+    return plan;
+}
+/** Source viewport falls inside (or in trailing-slack of) an indexed block — reveal that block's anchor. */
+function activeBlockCodeToDocPlan(active, strictContaining, docPane, sticky, line1, winRatio) {
+    sticky.sourceSticky.lockedId = active.id;
+    const mdLine0 = active.commentrayLine;
+    const pickMode = strictContaining !== null && strictContaining.id === active.id ? "strict" : "trailing-slack";
+    if (commentrayBlockAnchorAlignedWithLead(docPane, mdLine0, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX)) {
+        scrollSyncTrace("code→doc.plan", {
+            reason: "active-block-anchor-aligned-noop",
+            line1,
+            pickMode,
+            blockId: active.id,
+            mdLine0,
+        });
+        return { k: "noop" };
+    }
+    const plan = { k: "block", mdLine0, winRatio };
+    scrollSyncTrace("code→doc.plan", {
+        reason: "active-block-reveal",
+        line1,
+        pickMode,
+        blockId: active.id,
+        mdLine0,
+        markerSpan: active.markerViewportHalfOpen1Based,
+        plan: formatCodeToDocPlanForLog(plan),
+    });
+    return plan;
+}
+/**
+ * Releases the sticky source lock once the viewport is past the previous block plus its trailing
+ * slack — a true inter-block gap. Without this clear, the gap-mirror branch never reactivates after
+ * the slack expires.
+ */
+function clearStickySourceLockPastTrailingSlack(sticky, links, line1) {
+    const sid = sticky.sourceSticky.lockedId;
+    if (!sid)
+        return;
+    const prev = links.find((x) => x.id === sid);
+    if (!prev) {
+        sticky.sourceSticky.lockedId = null;
+        return;
+    }
+    const hi = prev.markerViewportHalfOpen1Based.hiExclusive;
+    if (line1 >= hi + SOURCE_BLOCK_TRAILING_SLACK_LINES) {
+        sticky.sourceSticky.lockedId = null;
+    }
+}
+function buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks, lineIdPrefix, sticky, allowProportionalMirror) {
     const winRatio = windowScrollRatio();
     const links = getLinks();
-    const line1 = probeCodeLine1FromViewport(codePane, lineIdPrefix);
-    const mdLine0 = pickCommentrayLineForSourceScroll(links, line1);
-    if (mdLine0 === null) {
-        if (paneUsesInternalYScroll(codePane)) {
-            return {
-                k: "mirrorI",
-                codeTop: codePane.scrollTop,
-                codeSH: codePane.scrollHeight,
-                codeCH: codePane.clientHeight,
-            };
+    resetBlockScrollStickyIfLinksChanged(sticky, links);
+    if (links.length === 0) {
+        if (!allowProportionalMirror) {
+            scrollSyncTrace("code→doc.plan", {
+                reason: "snap-only-no-block-links-noop",
+                lineIdPrefix,
+            });
+            return { k: "noop" };
         }
-        return { k: "mirrorW", ratio: winRatio };
+        const plan = codeMirrorPlan(codePane, winRatio);
+        scrollSyncTrace("code→doc.plan", {
+            reason: plan.k === "mirrorI" ? "no-block-links-mirror-internal" : "no-block-links-mirror-window",
+            lineIdPrefix,
+            plan: formatCodeToDocPlanForLog(plan),
+        });
+        return plan;
     }
-    return { k: "block", mdLine0, winRatio };
+    const line1 = probeCodeLine1FromViewport(codePane, lineIdPrefix);
+    if (sourceTopLineStrictlyBeforeFirstIndexLine(links, line1)) {
+        return preludeBlockAwareCodeToDocPlan(links, docPane, sticky, line1, lineIdPrefix, winRatio);
+    }
+    const strictContaining = blockStrictlyContainingSourceViewportLine(links, line1);
+    const active = blockForCodeToDocSync(links, line1, sticky);
+    if (active) {
+        return activeBlockCodeToDocPlan(active, strictContaining, docPane, sticky, line1, winRatio);
+    }
+    /** Source viewport sits in a true gap between indexed spans — mirror so the doc never snaps to an unrelated block head. */
+    clearStickySourceLockPastTrailingSlack(sticky, links, line1);
+    if (!allowProportionalMirror) {
+        scrollSyncTrace("code→doc.plan", {
+            reason: "snap-only-source-gap-noop",
+            line1,
+            lineIdPrefix,
+            stickyLockAfter: sticky.sourceSticky.lockedId,
+        });
+        return { k: "noop" };
+    }
+    const plan = codeMirrorPlan(codePane, winRatio);
+    scrollSyncTrace("code→doc.plan", {
+        reason: plan.k === "mirrorI" ? "source-gap-mirror-internal" : "source-gap-mirror-window",
+        line1,
+        lineIdPrefix,
+        stickyLockAfter: sticky.sourceSticky.lockedId,
+        plan: formatCodeToDocPlanForLog(plan),
+    });
+    return plan;
 }
 function buildDocToCodeFlipPlanProportional(docPane) {
     if (paneUsesInternalYScroll(docPane)) {
@@ -412,7 +883,7 @@ function emptySearchBrowsePreviewInnerHtml(hint, rows, ctx) {
 function scrollDocToMarkdownLine0(docScrollEl, line0, mdLineCount) {
     const el = docScrollEl.querySelector(`#commentray-md-line-${String(line0)}`);
     if (el instanceof HTMLElement) {
-        const top = Math.round(scrollTopToAlignChildTop(docScrollEl, el, 8));
+        const top = Math.round(scrollTopToAlignChildTop(docScrollEl, el, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX));
         const maxY = Math.round(Math.max(0, docScrollEl.scrollHeight - docScrollEl.clientHeight));
         docScrollEl.scrollTo({ top: clamp(top, 0, maxY), behavior: "smooth" });
         return;
@@ -488,6 +959,12 @@ function findSearchHitButton(leaf, searchResults) {
     }
     return null;
 }
+function listSearchHitButtons(searchResults) {
+    return [...searchResults.querySelectorAll("button.hit")].filter((el) => el instanceof HTMLButtonElement);
+}
+function listDocumentedTreeFileLinks(treeHost) {
+    return [...treeHost.querySelectorAll("a.tree-file-link")].filter((el) => el instanceof HTMLAnchorElement);
+}
 function scrollCodeHitToView(line) {
     const el = document.getElementById(`code-line-${String(line)}`);
     if (el)
@@ -561,12 +1038,77 @@ function emptyBrowsePreviewInnerHtml(scope, filePathLabel, mutable) {
     const hint = emptyBrowsePreviewHint("commentray-and-paths", fb.length, fb.length, true);
     return emptySearchBrowsePreviewInnerHtml(hint, fb, hitCtx);
 }
+function wireSearchResultsHitListKeyboard(searchResults, searchInput) {
+    searchResults.addEventListener("keydown", (e) => {
+        if (e.isComposing || searchResults.hidden)
+            return;
+        const hits = listSearchHitButtons(searchResults);
+        if (hits.length === 0)
+            return;
+        const active = document.activeElement;
+        if (!(active instanceof HTMLButtonElement) || !active.classList.contains("hit"))
+            return;
+        const idx = hits.indexOf(active);
+        if (idx < 0)
+            return;
+        if (e.key === "ArrowDown" && idx < hits.length - 1) {
+            hits[idx + 1].focus({ preventScroll: true });
+            e.preventDefault();
+            return;
+        }
+        if (e.key === "ArrowUp") {
+            if (idx > 0) {
+                hits[idx - 1].focus({ preventScroll: true });
+                e.preventDefault();
+                return;
+            }
+            searchInput.focus({ preventScroll: true });
+            e.preventDefault();
+        }
+    });
+}
+function wireSearchInputKeyboard(searchInput, searchResults, actions) {
+    const { renderEmptyBrowsePreview, runSearch, cancelDebounceTimer, hitClickDeps } = actions;
+    searchInput.addEventListener("keydown", (e) => {
+        if (e.isComposing)
+            return;
+        if (e.key === "ArrowDown") {
+            if (!searchResults.hidden) {
+                const hits = listSearchHitButtons(searchResults);
+                if (hits.length > 0 && document.activeElement === searchInput) {
+                    hits[0].focus({ preventScroll: true });
+                    e.preventDefault();
+                    return;
+                }
+            }
+            if (tokenizeQuery(searchInput.value).length > 0)
+                return;
+            renderEmptyBrowsePreview();
+            e.preventDefault();
+            return;
+        }
+        if (e.key !== "Enter")
+            return;
+        cancelDebounceTimer();
+        if (tokenizeQuery(searchInput.value).length > 0) {
+            runSearch();
+        }
+        const hits = listSearchHitButtons(searchResults);
+        if (!searchResults.hidden && hits.length > 0 && document.activeElement === searchInput) {
+            e.preventDefault();
+            handleSearchHitButtonClick(hits[0], hitClickDeps);
+        }
+    });
+}
 function wireSearchUi(ctx) {
     const { scope, filePathLabel, mutable, rawCode, searchInput, searchClear, searchResults, docScrollEl, } = ctx;
     let debounceTimer;
-    function clearSearch() {
+    function cancelDebounceTimer() {
         clearTimeout(debounceTimer);
         debounceTimer = undefined;
+    }
+    function clearSearch() {
+        cancelDebounceTimer();
         searchInput.value = "";
         searchResults.innerHTML = "";
         searchResults.hidden = true;
@@ -610,17 +1152,16 @@ function wireSearchUi(ctx) {
             return;
         handleSearchHitButtonClick(hit, hitClickDeps);
     });
+    wireSearchResultsHitListKeyboard(searchResults, searchInput);
     searchInput.addEventListener("input", () => {
         clearTimeout(debounceTimer);
         debounceTimer = setTimeout(runSearch, 200);
     });
-    searchInput.addEventListener("keydown", (e) => {
-        if (e.key !== "ArrowDown")
-            return;
-        if (tokenizeQuery(searchInput.value).length > 0)
-            return;
-        renderEmptyBrowsePreview();
-        e.preventDefault();
+    wireSearchInputKeyboard(searchInput, searchResults, {
+        renderEmptyBrowsePreview,
+        runSearch,
+        cancelDebounceTimer,
+        hitClickDeps,
     });
     searchClear.addEventListener("click", clearSearch);
     document.addEventListener("keydown", (e) => {
@@ -726,13 +1267,13 @@ function parseScrollBlockLinksFromShell(b64) {
         return [];
     }
 }
-function rootScrollNearDocumentEnd(edgePx = 56) {
+function rootScrollNearDocumentEnd(edgePx = READING_VIEWPORT_BOTTOM_EDGE_CSS_PX) {
     const root = rootScrollingElement();
     const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
     return maxY > 0 && root.scrollTop >= maxY - edgePx;
 }
 /** When the pane itself is the scrollport (dual desktop), mirror root “near end” behavior. */
-function paneScrollNearEnd(pane, edgePx = 56) {
+function paneScrollNearEnd(pane, edgePx = READING_VIEWPORT_BOTTOM_EDGE_CSS_PX) {
     const maxY = Math.max(0, pane.scrollHeight - pane.clientHeight);
     return maxY > 0 && pane.scrollTop >= maxY - edgePx;
 }
@@ -753,10 +1294,15 @@ function bestCommentrayAnchorLine0AtOrAboveY(anchors, y) {
     return maxCommentrayAnchorLine0AtOrAboveViewportY(readings, y);
 }
 function lastCommentrayAnchorLine0(anchors) {
-    const last = anchors[anchors.length - 1];
-    if (!last)
-        return 0;
-    return readCommentrayLine0FromAnchor(last) ?? 0;
+    for (let i = anchors.length - 1; i >= 0; i--) {
+        const el = anchors.item(i);
+        if (!el)
+            continue;
+        const v = readCommentrayLine0FromAnchor(el);
+        if (v !== null)
+            return v;
+    }
+    return null;
 }
 function probeCodeLine1FromViewport(codePane, lineIdPrefix = "code-line-") {
     const rows = codePane.querySelectorAll(`[id^="${lineIdPrefix}"]`);
@@ -774,7 +1320,7 @@ function probeCodeLine1FromViewport(codePane, lineIdPrefix = "code-line-") {
         const vh = globalThis.innerHeight;
         const clipT = Math.max(0, sr.top);
         const clipB = Math.min(vh, sr.bottom);
-        const y = clipT + Math.max(2, Math.min(40, (clipB - clipT) * 0.15));
+        const y = clipT + readingViewportTopInsetCssPx(clipB - clipT);
         for (const el of rows) {
             const r = el.getBoundingClientRect();
             if (r.bottom > y - 1e-3) {
@@ -794,7 +1340,7 @@ function probeCodeLine1FromViewport(codePane, lineIdPrefix = "code-line-") {
         return rows.length;
     }
     const sr = codePane.getBoundingClientRect();
-    const y = sr.top + codePane.clientTop + 2;
+    const y = sr.top + codePane.clientTop + readingViewportTopInsetCssPx(codePane.clientHeight);
     for (const el of rows) {
         const r = el.getBoundingClientRect();
         if (r.bottom > y - 1e-3) {
@@ -809,22 +1355,28 @@ function probeCodeLine1FromViewport(codePane, lineIdPrefix = "code-line-") {
 function probeCommentrayLine0FromDoc(docPane) {
     const anchors = docPane.querySelectorAll(".commentray-block-anchor");
     if (anchors.length === 0)
-        return 0;
+        return null;
     if (!paneUsesInternalYScroll(docPane)) {
-        if (rootScrollNearDocumentEnd())
-            return lastCommentrayAnchorLine0(anchors);
+        if (rootScrollNearDocumentEnd()) {
+            const tail = lastCommentrayAnchorLine0(anchors);
+            if (tail !== null)
+                return tail;
+        }
         const dr = docPane.getBoundingClientRect();
         const vh = globalThis.innerHeight;
         const clipT = Math.max(0, dr.top);
         const clipB = Math.min(vh, dr.bottom);
-        const y = clipT + Math.max(2, Math.min(40, (clipB - clipT) * 0.15));
+        const y = clipT + readingViewportTopInsetCssPx(clipB - clipT);
         return bestCommentrayAnchorLine0AtOrAboveY(anchors, y);
     }
-    if (paneScrollNearEnd(docPane))
-        return lastCommentrayAnchorLine0(anchors);
+    if (paneScrollNearEnd(docPane)) {
+        const tail = lastCommentrayAnchorLine0(anchors);
+        if (tail !== null)
+            return tail;
+    }
     const dr = docPane.getBoundingClientRect();
-    /** Same band as the root-scroll branch: a few px below the pane top so block anchors sit inside `top <= y` while their prose is what the reader sees first. */
-    const y = dr.top + docPane.clientTop + Math.max(2, Math.min(40, docPane.clientHeight * 0.15));
+    /** Same band as the root-scroll branch: inset below the pane top so anchors qualify while body text sits in the comfort zone. */
+    const y = dr.top + docPane.clientTop + readingViewportTopInsetCssPx(docPane.clientHeight);
     return bestCommentrayAnchorLine0AtOrAboveY(anchors, y);
 }
 function pageBreakPullEnabled() {
@@ -839,10 +1391,10 @@ function docProbeTopY(docPane) {
         const vh = globalThis.innerHeight;
         const clipT = Math.max(0, dr.top);
         const clipB = Math.min(vh, dr.bottom);
-        return clipT + Math.max(2, Math.min(40, (clipB - clipT) * 0.15));
+        return clipT + readingViewportTopInsetCssPx(clipB - clipT);
     }
     const dr = docPane.getBoundingClientRect();
-    return dr.top + docPane.clientTop + 2;
+    return dr.top + docPane.clientTop + readingViewportTopInsetCssPx(docPane.clientHeight);
 }
 /**
  * In long synthetic page-break gaps, shift source toward the next block once
@@ -852,13 +1404,13 @@ function pulledSourceLine0FromPageBreak(docPane) {
     if (!pageBreakPullEnabled())
         return null;
     const topY = docProbeTopY(docPane);
-    const breaks = Array.from(docPane.querySelectorAll(".commentray-page-break[data-next-source-start]"));
+    const breaks = Array.from(docPane.querySelectorAll(".commentray-page-break[data-next-source-viewport-line]"));
     for (const pageBreak of breaks) {
-        const nextSourceStartRaw = pageBreak.getAttribute("data-next-source-start");
-        if (!nextSourceStartRaw)
+        const nextViewportLineRaw = pageBreak.getAttribute("data-next-source-viewport-line");
+        if (!nextViewportLineRaw)
             continue;
-        const nextSourceStart = Number.parseInt(nextSourceStartRaw, 10);
-        if (!Number.isFinite(nextSourceStart) || nextSourceStart <= 0)
+        const nextViewportLine1Based = Number.parseInt(nextViewportLineRaw, 10);
+        if (!Number.isFinite(nextViewportLine1Based) || nextViewportLine1Based <= 0)
             continue;
         const breakTop = pageBreak.getBoundingClientRect().top;
         const nextLineRaw = pageBreak.getAttribute("data-next-commentray-line");
@@ -877,91 +1429,251 @@ function pulledSourceLine0FromPageBreak(docPane) {
         const pullThreshold = narrow ? 0.2 : 0.35;
         if (progress < pullThreshold)
             return null;
-        return nextSourceStart - 1;
+        return nextViewportLine1Based - 1;
     }
     return null;
 }
 /**
- * Programmatic `scrollTop` on the partner pane can emit a `scroll` event after the
- * synchronous `syncing` guard is cleared; that late event would mirror back and
- * jerk the pane the user is scrolling. We arm a short-lived skip on the partner
- * before each sync-driven update, and release one skip after two rAFs if no event
- * consumed it (e.g. `applyScrollTopClamped` no-oped).
+ * After we move the **partner** pane from a driver sync, its `scroll` handler must not run the
+ * opposite mapper until things settle — one user wheel can produce dozens of programmatic scroll
+ * events (layout, smooth interpolation, nested scrollports). A **fixed event budget** was
+ * exhausted mid-gesture and caused doc↔code ping-pong. We extend a **deadline** instead; each driver
+ * sync pushes `until` forward so continuous scrolling stays stable.
  */
-function armIgnoreNextPaneScrollReaction(armed) {
-    armed.n++;
-    queueMicrotask(() => {
-        requestAnimationFrame(() => {
-            requestAnimationFrame(() => {
-                armed.n = Math.max(0, armed.n - 1);
-            });
-        });
+/**
+ * Ignore partner `scroll` echoes after a driver sync. Must cover the tail of
+ * tail of a partner programmatic scroll; otherwise the partner’s frames can be treated as a driver
+ * and the panes ping-pong. Uses {@link SMOOTH_REVEAL_INFLIGHT_DEDUP_MS} as a conservative ceiling
+ * for any remaining smooth paths (e.g. hash navigation helpers).
+ */
+const PARTNER_SCROLL_ECHO_SUPPRESS_MS = Math.max(320, SMOOTH_REVEAL_INFLIGHT_DEDUP_MS + 250);
+function armPartnerScrollEchoGate(gate) {
+    const next = performance.now() + PARTNER_SCROLL_ECHO_SUPPRESS_MS;
+    gate.until = Math.max(gate.until, next);
+}
+function partnerScrollEchoActive(gate) {
+    return performance.now() < gate.until;
+}
+/** Throttle for the `wire.*.flush-skipped` `partner-echo` log line — without it we get one per animation frame. */
+const WIRE_ECHO_SKIP_TRACE_MIN_MS = 200;
+function emitFlushSkippedPartnerEcho(axis, state, ownEchoGate, driverPane) {
+    const t = performance.now();
+    if (!scrollSyncTraceFeatureFlag() ||
+        t - state.lastEchoSkipTraceAt < WIRE_ECHO_SKIP_TRACE_MIN_MS) {
+        return;
+    }
+    state.lastEchoSkipTraceAt = t;
+    scrollSyncTrace(`wire.${axis}.flush-skipped`, {
+        reason: "partner-echo",
+        echoUntilMs: Math.round(ownEchoGate.until),
+        [`${axis}ScrollTop`]: driverPane.scrollTop,
     });
 }
-function wireBidirectionalScroll(codePane, docPane, syncFromCode, syncFromDoc) {
-    let syncing = "none";
-    const ignoreCodeScrollFromPartnerSync = { n: 0 };
-    const ignoreDocScrollFromPartnerSync = { n: 0 };
-    codePane.addEventListener("scroll", () => {
-        if (ignoreCodeScrollFromPartnerSync.n > 0) {
-            ignoreCodeScrollFromPartnerSync.n--;
+/** Builds the RAF flush closure that consumes one driver pane's coalesced scroll bursts. */
+function makeDriverFlush(args) {
+    const { axis, driverPane, state, syncingRef, ownEchoGate, partnerEchoGate, syncFromDriver } = args;
+    return () => {
+        state.pendingRaf = 0;
+        if (partnerScrollEchoActive(ownEchoGate)) {
+            emitFlushSkippedPartnerEcho(axis, state, ownEchoGate, driverPane);
+            state.lastSeenTop = driverPane.scrollTop;
             return;
         }
-        if (syncing === "doc")
+        if (syncingRef.current !== "none") {
+            scrollSyncTrace(`wire.${axis}.flush-skipped`, {
+                reason: "sync-in-progress",
+                syncing: syncingRef.current,
+            });
             return;
-        syncing = "code";
-        armIgnoreNextPaneScrollReaction(ignoreDocScrollFromPartnerSync);
-        syncFromCode();
-        syncing = "none";
-    }, { passive: true });
-    docPane.addEventListener("scroll", () => {
-        if (ignoreDocScrollFromPartnerSync.n > 0) {
-            ignoreDocScrollFromPartnerSync.n--;
+        }
+        const now = driverPane.scrollTop;
+        const delta = now - state.lastSeenTop;
+        state.lastSeenTop = now;
+        syncingRef.current = axis;
+        armPartnerScrollEchoGate(partnerEchoGate);
+        scrollSyncTrace(`wire.${axis}.driver`, { delta, [`${axis}ScrollTop`]: now });
+        syncFromDriver(delta);
+        syncingRef.current = "none";
+    };
+}
+/** Installs the `scroll` listener on one driver pane that schedules at most one flush per frame. */
+function attachDriverScrollListener(args) {
+    const { driverPane, state, syncingRef, ownEchoGate, flush } = args;
+    driverPane.addEventListener("scroll", () => {
+        if (partnerScrollEchoActive(ownEchoGate)) {
+            state.lastSeenTop = driverPane.scrollTop;
+            if (state.pendingRaf !== 0) {
+                cancelAnimationFrame(state.pendingRaf);
+                state.pendingRaf = 0;
+            }
             return;
         }
-        if (syncing === "code")
+        if (syncingRef.current !== "none") {
+            state.lastSeenTop = driverPane.scrollTop;
             return;
-        syncing = "doc";
-        armIgnoreNextPaneScrollReaction(ignoreCodeScrollFromPartnerSync);
-        syncFromDoc();
-        syncing = "none";
+        }
+        if (state.pendingRaf !== 0) {
+            cancelAnimationFrame(state.pendingRaf);
+        }
+        state.pendingRaf = requestAnimationFrame(flush);
     }, { passive: true });
 }
+/**
+ * Coalesces high-frequency `scroll` bursts into **one** partner sync per pane per animation
+ * frame so block-aware snaps do not chain immediate reverse syncs (“slot machine” feel).
+ */
+function wireBidirectionalScroll(codePane, docPane, syncFromCode, syncFromDoc) {
+    const syncingRef = { current: "none" };
+    /** Code pane: ignore scroll echoes while we are applying a doc→code partner update. */
+    const suppressCodeScrollEcho = { until: 0 };
+    /** Doc pane: ignore scroll echoes while we are applying a code→doc partner update. */
+    const suppressDocScrollEcho = { until: 0 };
+    const codeState = {
+        lastSeenTop: codePane.scrollTop,
+        pendingRaf: 0,
+        lastEchoSkipTraceAt: -Infinity,
+    };
+    const docState = {
+        lastSeenTop: docPane.scrollTop,
+        pendingRaf: 0,
+        lastEchoSkipTraceAt: -Infinity,
+    };
+    const flushCode = makeDriverFlush({
+        axis: "code",
+        driverPane: codePane,
+        state: codeState,
+        syncingRef,
+        ownEchoGate: suppressCodeScrollEcho,
+        partnerEchoGate: suppressDocScrollEcho,
+        syncFromDriver: syncFromCode,
+    });
+    const flushDoc = makeDriverFlush({
+        axis: "doc",
+        driverPane: docPane,
+        state: docState,
+        syncingRef,
+        ownEchoGate: suppressDocScrollEcho,
+        partnerEchoGate: suppressCodeScrollEcho,
+        syncFromDriver: syncFromDoc,
+    });
+    attachDriverScrollListener({
+        driverPane: codePane,
+        state: codeState,
+        syncingRef,
+        ownEchoGate: suppressCodeScrollEcho,
+        flush: flushCode,
+    });
+    attachDriverScrollListener({
+        driverPane: docPane,
+        state: docState,
+        syncingRef,
+        ownEchoGate: suppressDocScrollEcho,
+        flush: flushDoc,
+    });
+}
+function blockAwareSyncFromCodeToDoc(bundle, driverDelta) {
+    const { codePane, docPane, getLinks, lineIdPrefix, sticky } = bundle;
+    const docBefore = readPaneVerticalScroll(docPane);
+    const prefix = lineIdPrefix();
+    const p = buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks, prefix, sticky, bundle.allowProportionalMirror);
+    applyCodeToDocFlipPlanImpl(codePane, docPane, p);
+    const docAfter = readPaneVerticalScroll(docPane);
+    scrollSyncTrace("code→doc.apply", {
+        driverDelta,
+        lineIdPrefix: prefix,
+        plan: formatCodeToDocPlanForLog(p),
+        docScrollTopBefore: docBefore,
+        docScrollTopAfter: docAfter,
+        docDelta: docAfter - docBefore,
+        codeScrollTop: codePane.scrollTop,
+    });
+    enforceScrollSyncMonotonic({
+        driverDelta,
+        partnerBefore: docBefore,
+        partnerPane: docPane,
+        axis: "code→doc",
+    });
+}
+function blockAwareSyncFromDocToCode(bundle, driverDelta) {
+    const { codePane, docPane, getLinks, lineIdPrefix, sticky } = bundle;
+    const codeBefore = readPaneVerticalScroll(codePane);
+    const prefix = lineIdPrefix();
+    const p = buildDocToCodeFlipPlanBlockAware(docPane, codePane, getLinks, sticky, prefix, bundle.allowProportionalMirror);
+    applyDocToCodeFlipPlanImpl(codePane, docPane, p, prefix);
+    const codeAfter = readPaneVerticalScroll(codePane);
+    scrollSyncTrace("doc→code.apply", {
+        driverDelta,
+        lineIdPrefix: prefix,
+        plan: formatDocToCodePlanForLog(p),
+        codeScrollTopBefore: codeBefore,
+        codeScrollTopAfter: codeAfter,
+        codeDelta: codeAfter - codeBefore,
+        docScrollTop: docPane.scrollTop,
+    });
+    enforceScrollSyncMonotonic({
+        driverDelta,
+        partnerBefore: codeBefore,
+        partnerPane: codePane,
+        axis: "doc→code",
+    });
+}
 /** Index-backed scroll sync when `data-scroll-block-links-b64` is present; else see proportional fallback. */
-function wireBlockAwareScrollSync(codePane, docPane, getLinks, lineIdPrefix, shouldUseProportionalDocToCodeOnMobileFlip) {
+function wireBlockAwareScrollSync(codePane, docPane, getLinks, lineIdPrefix, shouldUseProportionalDocToCodeOnMobileFlip, options) {
+    const allowProportionalMirror = options?.allowProportionalMirror !== false;
     let pendingDocToCode = null;
     let pendingCodeToDoc = null;
+    const sticky = {
+        sourceSticky: { lockedId: null },
+        commentraySticky: { lockedId: null },
+        linksKey: { current: "" },
+    };
+    const bundle = {
+        codePane,
+        docPane,
+        getLinks,
+        lineIdPrefix,
+        sticky,
+        allowProportionalMirror,
+    };
+    const syncFromCodeToDocInner = (d) => blockAwareSyncFromCodeToDoc(bundle, d);
+    const syncFromDocToCodeInner = (d) => blockAwareSyncFromDocToCode(bundle, d);
     const syncFromCodeToDoc = () => {
-        applyCodeToDocFlipPlanImpl(codePane, docPane, buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks, lineIdPrefix()));
+        blockAwareSyncFromCodeToDoc(bundle, 0);
     };
     const syncFromDocToCode = () => {
-        applyDocToCodeFlipPlanImpl(codePane, docPane, buildDocToCodeFlipPlanBlockAware(docPane, getLinks), lineIdPrefix());
+        blockAwareSyncFromDocToCode(bundle, 0);
     };
     const prepareMobileFlipToCode = () => {
-        if (shouldUseProportionalDocToCodeOnMobileFlip?.() === true) {
+        if (allowProportionalMirror && shouldUseProportionalDocToCodeOnMobileFlip?.() === true) {
             pendingDocToCode = { k: "mirrorW", ratio: windowScrollRatio() };
             return;
         }
-        pendingDocToCode = buildDocToCodeFlipPlanBlockAware(docPane, getLinks);
+        pendingDocToCode = buildDocToCodeFlipPlanBlockAware(docPane, codePane, getLinks, sticky, lineIdPrefix(), allowProportionalMirror);
     };
     const finishMobileFlipToCode = () => {
         if (!pendingDocToCode)
             return;
-        const p = pendingDocToCode;
+        let p = pendingDocToCode;
         pendingDocToCode = null;
+        if (p.k === "noop" && p.skipProportionalFallbackOnFlip !== true && allowProportionalMirror) {
+            p = buildDocToCodeFlipPlanProportional(docPane);
+        }
         applyDocToCodeFlipPlanImpl(codePane, docPane, p, lineIdPrefix());
     };
     const prepareMobileFlipToDoc = () => {
-        pendingCodeToDoc = buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks, lineIdPrefix());
+        pendingCodeToDoc = buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks, lineIdPrefix(), sticky, allowProportionalMirror);
     };
     const finishMobileFlipToDoc = () => {
         if (!pendingCodeToDoc)
             return;
-        const p = pendingCodeToDoc;
+        let p = pendingCodeToDoc;
         pendingCodeToDoc = null;
+        if (p.k === "noop" && allowProportionalMirror) {
+            p = buildCodeToDocFlipPlanProportional(codePane);
+        }
         applyCodeToDocFlipPlanImpl(codePane, docPane, p);
     };
-    wireBidirectionalScroll(codePane, docPane, syncFromCodeToDoc, syncFromDocToCode);
+    wireBidirectionalScroll(codePane, docPane, syncFromCodeToDocInner, syncFromDocToCodeInner);
     return {
         syncFromCodeToDoc,
         syncFromDocToCode,
@@ -975,11 +1687,49 @@ function wireBlockAwareScrollSync(codePane, docPane, getLinks, lineIdPrefix, sho
 function wireProportionalScrollSync(codePane, docPane) {
     let pendingDocToCode = null;
     let pendingCodeToDoc = null;
+    const syncFromCodeToDocInner = (driverDelta) => {
+        const docBefore = readPaneVerticalScroll(docPane);
+        const p = buildCodeToDocFlipPlanProportional(codePane);
+        applyCodeToDocFlipPlanImpl(codePane, docPane, p);
+        scrollSyncTrace("code→doc.apply", {
+            mode: "proportional-shell",
+            driverDelta,
+            plan: formatCodeToDocPlanForLog(p),
+            docScrollTopBefore: docBefore,
+            docScrollTopAfter: readPaneVerticalScroll(docPane),
+            codeScrollTop: codePane.scrollTop,
+        });
+        enforceScrollSyncMonotonic({
+            driverDelta,
+            partnerBefore: docBefore,
+            partnerPane: docPane,
+            axis: "code→doc",
+        });
+    };
+    const syncFromDocToCodeInner = (driverDelta) => {
+        const codeBefore = readPaneVerticalScroll(codePane);
+        const p = buildDocToCodeFlipPlanProportional(docPane);
+        applyDocToCodeFlipPlanImpl(codePane, docPane, p);
+        scrollSyncTrace("doc→code.apply", {
+            mode: "proportional-shell",
+            driverDelta,
+            plan: formatDocToCodePlanForLog(p),
+            codeScrollTopBefore: codeBefore,
+            codeScrollTopAfter: readPaneVerticalScroll(codePane),
+            docScrollTop: docPane.scrollTop,
+        });
+        enforceScrollSyncMonotonic({
+            driverDelta,
+            partnerBefore: codeBefore,
+            partnerPane: codePane,
+            axis: "doc→code",
+        });
+    };
     const syncFromCodeToDoc = () => {
-        applyCodeToDocFlipPlanImpl(codePane, docPane, buildCodeToDocFlipPlanProportional(codePane));
+        syncFromCodeToDocInner(0);
     };
     const syncFromDocToCode = () => {
-        applyDocToCodeFlipPlanImpl(codePane, docPane, buildDocToCodeFlipPlanProportional(docPane));
+        syncFromDocToCodeInner(0);
     };
     const prepareMobileFlipToCode = () => {
         pendingDocToCode = buildDocToCodeFlipPlanProportional(docPane);
@@ -1001,7 +1751,7 @@ function wireProportionalScrollSync(codePane, docPane) {
         pendingCodeToDoc = null;
         applyCodeToDocFlipPlanImpl(codePane, docPane, p);
     };
-    wireBidirectionalScroll(codePane, docPane, syncFromCodeToDoc, syncFromDocToCode);
+    wireBidirectionalScroll(codePane, docPane, syncFromCodeToDocInner, syncFromDocToCodeInner);
     return {
         syncFromCodeToDoc,
         syncFromDocToCode,
@@ -1032,9 +1782,7 @@ function commentaryBandEndYViewport(docScrollEl, next, docTop, clipThroughPageBr
         const nextTop = nextEl.getBoundingClientRect().top - 3;
         if (!clipThroughPageBreakGaps)
             return nextTop;
-        const docBandTop = docTop.getBoundingClientRect().top + 4;
-        const contentBottom = maxRenderableCommentaryContentBottomViewport(docScrollEl, docTop, nextEl);
-        return Math.min(nextTop, Math.max(docBandTop, contentBottom));
+        return commentaryGutterDocBandBottomViewport(docScrollEl, docTop, nextEl);
     }
     const dr = docScrollEl.getBoundingClientRect();
     let bottom = dr.bottom - 4;
@@ -1107,6 +1855,15 @@ function subscribeBlockRayRedraw(gutter, codePane, docScrollEl, scheduleDraw) {
     if (shell)
         ro.observe(shell);
 }
+/** Doc-aligned active block matches visible commentary; code-only probe can lag in page gaps. */
+function activeBlockIdForGutterRays(links, docScrollEl, probeTopSourceLine1Based) {
+    const mdLine0ForRay = probeCommentrayLine0FromDoc(docScrollEl);
+    const haveAnchors = docScrollEl.querySelector(".commentray-block-anchor") !== null;
+    if (haveAnchors && mdLine0ForRay !== null) {
+        return activeBlockIdForCommentrayLine0(links, mdLine0ForRay);
+    }
+    return activeBlockIdForViewport(links, probeTopSourceLine1Based());
+}
 function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based, lineIdPrefix) {
     const links = dedupeBlockScrollLinksById(getLinks());
     const sorted = sortBlockLinksBySource(links);
@@ -1117,10 +1874,7 @@ function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSource
         svg.replaceChildren();
         return;
     }
-    /** Doc-aligned active block matches visible commentary; code-only probe can lag in page gaps. */
-    const activeId = docScrollEl.querySelector(".commentray-block-anchor") !== null
-        ? activeBlockIdForCommentrayLine0(links, probeCommentrayLine0FromDoc(docScrollEl))
-        : activeBlockIdForViewport(links, probeTopSourceLine1Based());
+    const activeId = activeBlockIdForGutterRays(links, docScrollEl, probeTopSourceLine1Based);
     const clipGutterRaysThroughPageBreakGaps = pageBreakPullEnabled();
     svg.setAttribute("viewBox", `0 0 ${String(w)} ${String(h)}`);
     svg.setAttribute("preserveAspectRatio", "none");
@@ -1569,12 +2323,52 @@ function wireDocumentedFilesTree() {
             sum.focus({ preventScroll: true });
     }
     document.addEventListener("keydown", onDocumentedFilesHubEscape, true);
+    treeMount.addEventListener("keydown", (e) => {
+        if (!detailsHub.open || e.isComposing)
+            return;
+        const t = e.target;
+        if (!(t instanceof HTMLAnchorElement) || !t.classList.contains("tree-file-link"))
+            return;
+        const links = listDocumentedTreeFileLinks(treeMount);
+        if (links.length === 0)
+            return;
+        const idx = links.indexOf(t);
+        if (idx < 0)
+            return;
+        if (e.key === "ArrowDown") {
+            if (idx < links.length - 1) {
+                links[idx + 1].focus({ preventScroll: true });
+                e.preventDefault();
+            }
+            return;
+        }
+        if (e.key === "ArrowUp") {
+            if (idx > 0) {
+                links[idx - 1].focus({ preventScroll: true });
+                e.preventDefault();
+                return;
+            }
+            if (filterInput instanceof HTMLInputElement) {
+                filterInput.focus({ preventScroll: true });
+                e.preventDefault();
+            }
+        }
+    });
     if (filterInput instanceof HTMLInputElement) {
         filterInput.addEventListener("input", () => {
             if (!detailsHub.open || cachedPairs === null)
                 return;
             applyFilterAndRender();
         });
+        filterInput.addEventListener("keydown", (e) => {
+            if (!detailsHub.open || e.isComposing || e.key !== "ArrowDown")
+                return;
+            const links = listDocumentedTreeFileLinks(treeMount);
+            if (links.length === 0)
+                return;
+            links[0].focus({ preventScroll: true });
+            e.preventDefault();
+        });
     }
 }
 function wireSplitter(storageSplit, shell, codePane, gutter, initialPct) {
@@ -1620,6 +2414,13 @@ function normalizedDualMobilePane(v) {
 function isNarrowViewport() {
     return globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ).matches;
 }
+function syncSinglePaneShellState(shell, narrowSinglePane) {
+    if (narrowSinglePane) {
+        shell.setAttribute("data-mobile-single-pane", "true");
+        return;
+    }
+    shell.removeAttribute("data-mobile-single-pane");
+}
 function wireWideModeIntroTrigger(shell) {
     const btn = document.getElementById("commentray-help-tour");
     if (!(btn instanceof HTMLButtonElement))
@@ -1677,7 +2478,7 @@ function scheduleMermaidWhenDualDocPaneVisible(shell, mq) {
         const docBody = document.getElementById("doc-pane-body");
         if (!(docBody instanceof HTMLElement))
             return;
-        runMermaidOnFreshDocNodes(docBody);
+        void runMermaidOnFreshDocNodes(docBody);
     };
     queueMicrotask(() => {
         kick();
@@ -1716,7 +2517,7 @@ function wireDualMobilePaneFlipScrollAffordance(primaryFlip, scrollFlip, mq) {
     mq.addEventListener("change", tick);
     globalThis.requestAnimationFrame(tick);
 }
-function wireSourceMarkdownPaneFlipAffordance(primaryFlip, scrollFlip) {
+function wireSourceMarkdownPaneFlipAffordance(primaryFlip, scrollFlip, signal) {
     const hideScroll = () => {
         scrollFlip.hidden = true;
         scrollFlip.classList.remove("is-visible");
@@ -1726,6 +2527,10 @@ function wireSourceMarkdownPaneFlipAffordance(primaryFlip, scrollFlip) {
         scrollFlip.classList.add("is-visible");
     };
     const tick = () => {
+        if (primaryFlip.hidden || primaryFlip.getClientRects().length === 0) {
+            hideScroll();
+            return;
+        }
         const r = primaryFlip.getBoundingClientRect();
         const vh = globalThis.innerHeight;
         const margin = 10;
@@ -1735,10 +2540,27 @@ function wireSourceMarkdownPaneFlipAffordance(primaryFlip, scrollFlip) {
         else
             hideScroll();
     };
-    globalThis.addEventListener("scroll", tick, { passive: true });
-    globalThis.addEventListener("resize", tick, { passive: true });
+    globalThis.addEventListener("scroll", tick, { passive: true, signal });
+    globalThis.addEventListener("resize", tick, { passive: true, signal });
     globalThis.requestAnimationFrame(tick);
 }
+function syncSourceMarkdownToggleVisibility(shell, primaryFlip, scrollFlip) {
+    const hidden = isNarrowViewport() &&
+        normalizedDualMobilePane(shell.getAttribute("data-dual-mobile-pane")) !== "code";
+    primaryFlip.hidden = hidden;
+    if (hidden) {
+        primaryFlip.setAttribute("aria-hidden", "true");
+        primaryFlip.style.setProperty("display", "none", "important");
+    }
+    else {
+        primaryFlip.removeAttribute("aria-hidden");
+        primaryFlip.style.removeProperty("display");
+    }
+    if (!(scrollFlip instanceof HTMLButtonElement))
+        return;
+    scrollFlip.hidden = true;
+    scrollFlip.classList.remove("is-visible");
+}
 function closestSourceLine0ForPaneTop(codePane, idPrefix) {
     const rows = codePane.querySelectorAll(`[id^="${idPrefix}"]`);
     if (rows.length === 0)
@@ -1763,13 +2585,17 @@ function closestSourceLine0ForPaneTop(codePane, idPrefix) {
         return null;
     return Number.parseInt(m[1], 10);
 }
-function wireSourceMarkdownPaneFlip(shell, codePane, flipBtn, flipScrollBtn, onAfterFlip) {
+function wireSourceMarkdownPaneFlip(shell, codePane, flipBtn, flipScrollBtn, signal, onAfterFlip) {
+    function sourceMarkdownBodies() {
+        return Array.from(codePane.querySelectorAll('[data-source-markdown-body="true"]'));
+    }
     function syncSourceMarkdownFlipA11y() {
         const mode = sourcePaneModeForShell(shell);
         const renderedActive = mode === "rendered-markdown";
         const nextModeLabel = renderedActive ? "markdown source" : "rendered markdown";
+        const currentModeLabel = renderedActive ? "rendered markdown" : "markdown source";
         const ariaLabel = `Switch source pane to ${nextModeLabel}`;
-        const title = `Source pane: ${renderedActive ? "rendered markdown" : "markdown source"} (click to switch)`;
+        const title = `Switch source pane to ${nextModeLabel} (currently ${currentModeLabel})`;
         const apply = (btn) => {
             if (!(btn instanceof HTMLButtonElement))
                 return;
@@ -1780,10 +2606,21 @@ function wireSourceMarkdownPaneFlip(shell, codePane, flipBtn, flipScrollBtn, onA
         apply(flipBtn);
         apply(flipScrollBtn);
     }
-    // Keep initial behavior deterministic: source pane starts in rendered markdown mode.
-    shell.setAttribute("data-source-pane-mode", "rendered-markdown");
     syncSourceMarkdownFlipA11y();
     syncWrapLinesVisibilityForSourcePaneMode(shell);
+    syncSourceMarkdownToggleVisibility(shell, flipBtn, flipScrollBtn);
+    const onViewportChange = () => {
+        syncSourceMarkdownToggleVisibility(shell, flipBtn, flipScrollBtn);
+    };
+    globalThis.addEventListener("resize", onViewportChange, { passive: true, signal });
+    const mobileMq = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ);
+    mobileMq.addEventListener("change", onViewportChange, { signal });
+    const observer = new MutationObserver(onViewportChange);
+    observer.observe(shell, {
+        attributes: true,
+        attributeFilter: ["data-dual-mobile-pane", "data-source-pane-mode"],
+    });
+    signal.addEventListener("abort", () => observer.disconnect(), { once: true });
     const runFlip = () => {
         const cur = sourcePaneModeForShell(shell);
         const currentPrefix = cur === "rendered-markdown" ? "code-md-line-" : "code-line-";
@@ -1792,27 +2629,34 @@ function wireSourceMarkdownPaneFlip(shell, codePane, flipBtn, flipScrollBtn, onA
         const nextPrefix = next === "rendered-markdown" ? "code-md-line-" : "code-line-";
         shell.setAttribute("data-source-pane-mode", next);
         writeWebStorageItem(localStorage, STORAGE_SOURCE_MARKDOWN_PANE_MODE, next);
+        if (isNarrowViewport()) {
+            const curPane = normalizedDualMobilePane(shell.getAttribute("data-dual-mobile-pane"));
+            if (curPane === "doc") {
+                shell.setAttribute("data-dual-mobile-pane", "code");
+                writeWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE, "code");
+            }
+        }
         syncSourceMarkdownFlipA11y();
         syncWrapLinesVisibilityForSourcePaneMode(shell);
-        if (line0 !== null) {
+        const shouldWriteRevealScroll = !isNarrowViewport() || paneUsesInternalYScroll(codePane);
+        if (line0 !== null && shouldWriteRevealScroll) {
             const row = codePane.querySelector(`#${nextPrefix}${String(line0)}`);
             if (row instanceof HTMLElement) {
-                applyRevealChildInPane(codePane, row, 2);
+                applyRevealChildInPane(codePane, row, 0);
             }
         }
         if (next === "rendered-markdown") {
-            const sourceMdBody = document.getElementById("code-pane-markdown-body");
-            if (sourceMdBody instanceof HTMLElement) {
-                runMermaidOnFreshDocNodes(sourceMdBody);
+            for (const sourceMdBody of sourceMarkdownBodies()) {
+                void runMermaidOnFreshDocNodes(sourceMdBody);
                 rewriteHubRelativeBrowseAnchorsIn(sourceMdBody);
             }
         }
         onAfterFlip?.();
     };
-    flipBtn.addEventListener("click", runFlip);
+    flipBtn.addEventListener("click", runFlip, { signal });
     if (flipScrollBtn) {
-        flipScrollBtn.addEventListener("click", runFlip);
-        wireSourceMarkdownPaneFlipAffordance(flipBtn, flipScrollBtn);
+        flipScrollBtn.addEventListener("click", runFlip, { signal });
+        wireSourceMarkdownPaneFlipAffordance(flipBtn, flipScrollBtn, signal);
     }
 }
 function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
@@ -1822,9 +2666,11 @@ function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
     }
     function applyForViewport() {
         if (mq.matches) {
+            syncSinglePaneShellState(shell, true);
             shell.setAttribute("data-dual-mobile-pane", readStoredPane());
         }
         else {
+            syncSinglePaneShellState(shell, false);
             shell.removeAttribute("data-dual-mobile-pane");
         }
     }
@@ -1870,13 +2716,282 @@ function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
     mq.addEventListener("change", applyForViewport);
     applyForViewport();
 }
-function wireStretchLayoutChrome(codePane) {
+function wireStretchMobilePaneFlip(shell, codePane, flipBtn, flipScrollBtn, onAfterFlip) {
+    void codePane;
+    void onAfterFlip;
+    const mq = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ);
+    function readStoredPane() {
+        return normalizedDualMobilePane(readWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE));
+    }
+    function applyForViewport() {
+        if (mq.matches) {
+            syncSinglePaneShellState(shell, true);
+            shell.setAttribute("data-dual-mobile-pane", readStoredPane());
+        }
+        else {
+            syncSinglePaneShellState(shell, false);
+            shell.removeAttribute("data-dual-mobile-pane");
+        }
+    }
+    const runFlip = () => {
+        if (!mq.matches)
+            return;
+        const cur = normalizedDualMobilePane(shell.getAttribute("data-dual-mobile-pane"));
+        const next = cur === "code" ? "doc" : "code";
+        shell.setAttribute("data-dual-mobile-pane", next);
+        writeWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE, next);
+        // When revealing the doc pane, (re)run Mermaid — diagrams inside display:none cells are
+        // skipped on initial load, so they need a triggered pass once the cells become visible.
+        if (next === "doc") {
+            queueMicrotask(() => {
+                requestAnimationFrame(() => {
+                    void runMermaidOnFreshDocNodes(shell);
+                });
+            });
+        }
+    };
+    flipBtn.addEventListener("click", runFlip);
+    if (flipScrollBtn) {
+        flipScrollBtn.addEventListener("click", runFlip);
+        wireDualMobilePaneFlipScrollAffordance(flipBtn, flipScrollBtn, mq);
+    }
+    mq.addEventListener("change", applyForViewport);
+    applyForViewport();
+}
+/** Multi-angle stretch swaps `#shell` innerHTML; disconnect the previous table observer so listeners do not accumulate. */
+let stretchRowBufferSyncHandle = null;
+let stretchGutterConnectorHandle = null;
+function stretchFlowSynchronizerEnabled(shell) {
+    return shell.getAttribute("data-stretch-buffer-sync") === "flow-synchronizer";
+}
+function stretchBlockRows(table) {
+    return Array.from(table.querySelectorAll("tbody tr.stretch-row--block[data-commentray-stretch-sync-id]")).filter((row) => (row.dataset.commentrayStretchSyncId?.trim() ?? "").length > 0);
+}
+function stretchRowPairRects(row) {
+    const id = row.dataset.commentrayStretchSyncId?.trim() ?? "";
+    if (id.length === 0)
+        return null;
+    const codeTd = row.querySelector(":scope > td.stretch-code");
+    const docTd = row.querySelector(":scope > td.stretch-doc");
+    if (!(codeTd instanceof HTMLTableCellElement) || !(docTd instanceof HTMLTableCellElement))
+        return null;
+    return { id, codeRect: codeTd.getBoundingClientRect(), docRect: docTd.getBoundingClientRect() };
+}
+function visibleElementRect(el) {
+    if (!(el instanceof HTMLElement))
+        return null;
+    const rect = el.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0)
+        return null;
+    const style = globalThis.getComputedStyle(el);
+    if (style.display === "none" || style.visibility === "hidden")
+        return null;
+    return rect;
+}
+function stretchVisibleSourcePane(codeTd, shell) {
+    const preferredSel = sourcePaneModeForShell(shell) === "rendered-markdown"
+        ? ".source-pane--rendered-md"
+        : ".source-pane--code";
+    const preferred = codeTd.querySelector(preferredSel);
+    if (visibleElementRect(preferred) !== null)
+        return preferred;
+    const fallbacks = codeTd.querySelectorAll(".source-pane--code, .source-pane--rendered-md");
+    for (const el of fallbacks) {
+        if (visibleElementRect(el) !== null)
+            return el;
+    }
+    return null;
+}
+function stretchCodeContentBottomViewport(codeTd, shell) {
+    const visiblePane = stretchVisibleSourcePane(codeTd, shell);
+    const paneRect = visibleElementRect(visiblePane);
+    if (paneRect !== null)
+        return paneRect.bottom;
+    return codeTd.getBoundingClientRect().bottom;
+}
+function stretchDocContentBottomViewport(docTd) {
+    const inner = docTd.querySelector(":scope .stretch-doc-inner");
+    const innerRect = visibleElementRect(inner);
+    if (innerRect !== null)
+        return innerRect.bottom;
+    return docTd.getBoundingClientRect().bottom;
+}
+function activeStretchSyncId(shell, rows) {
+    const shellRect = shell.getBoundingClientRect();
+    const probeY = shellRect.top + Math.min(Math.max(shellRect.height * 0.18, 24), 120);
+    for (const row of rows) {
+        const rect = row.getBoundingClientRect();
+        if (rect.top <= probeY && rect.bottom >= probeY) {
+            return row.dataset.commentrayStretchSyncId?.trim() ?? null;
+        }
+    }
+    return rows[0]?.dataset.commentrayStretchSyncId?.trim() ?? null;
+}
+function drawStretchGutterConnectorsIntoSvg(svg, shell, table, gutter) {
+    const rows = stretchBlockRows(table);
+    const gutterRect = gutter.getBoundingClientRect();
+    const w = gutterRect.width;
+    const h = gutterRect.height;
+    if (w <= 0 || h <= 0 || rows.length === 0) {
+        svg.replaceChildren();
+        return;
+    }
+    svg.setAttribute("viewBox", `0 0 ${String(w)} ${String(h)}`);
+    svg.setAttribute("preserveAspectRatio", "none");
+    const activeId = activeStretchSyncId(shell, rows);
+    const parts = [];
+    for (const row of rows) {
+        const pair = stretchRowPairRects(row);
+        if (pair === null)
+            continue;
+        const codeTd = row.querySelector(":scope > td.stretch-code");
+        const docTd = row.querySelector(":scope > td.stretch-doc");
+        if (!(codeTd instanceof HTMLTableCellElement) || !(docTd instanceof HTMLTableCellElement))
+            continue;
+        const codeContentBottom = stretchCodeContentBottomViewport(codeTd, shell);
+        const docContentBottom = stretchDocContentBottomViewport(docTd);
+        const codeTop = clampViewportYToGutterLocal(pair.codeRect.top + 1, gutterRect.top, h);
+        const docTop = clampViewportYToGutterLocal(pair.docRect.top + 1, gutterRect.top, h);
+        const codeBottom = clampViewportYToGutterLocal(codeContentBottom - 1, gutterRect.top, h);
+        const docBottom = clampViewportYToGutterLocal(docContentBottom - 1, gutterRect.top, h);
+        const strokeClass = pair.id === activeId ? "gutter__rays-path gutter__rays-path--active" : "gutter__rays-path";
+        const trailClass = `${strokeClass} gutter__rays-path--trail`;
+        const topPaths = gutterRayBezierPaths(0, codeTop.y, w, docTop.y, {
+            tension: 0.38,
+            clipStart: codeTop.clipped,
+            clipEnd: docTop.clipped,
+        });
+        const bottomPaths = gutterRayBezierPaths(0, codeBottom.y, w, docBottom.y, {
+            tension: 0.38,
+            clipStart: codeBottom.clipped,
+            clipEnd: docBottom.clipped,
+        });
+        const topExtra = topPaths.dotted ? `<path class="${trailClass}" d="${topPaths.dotted}" />` : "";
+        const bottomExtra = bottomPaths.dotted
+            ? `<path class="${trailClass}" d="${bottomPaths.dotted}" />`
+            : "";
+        parts.push(`<g class="gutter__rays-block" data-commentray-block="${escapeHtmlText(pair.id)}">` +
+            `<path class="${strokeClass}" d="${topPaths.solid}" />` +
+            topExtra +
+            `<path class="${strokeClass}" d="${bottomPaths.solid}" />` +
+            bottomExtra +
+            `</g>`);
+    }
+    svg.innerHTML = parts.join("");
+}
+function wireStretchGutterConnectors(shell, table, gutter) {
+    gutter.querySelector(":scope > .gutter__rays")?.remove();
+    const svgNs = "http://www.w3.org/2000/svg";
+    const host = document.createElement("div");
+    host.className = "gutter__rays";
+    host.setAttribute("aria-hidden", "true");
+    const svg = document.createElementNS(svgNs, "svg");
+    host.appendChild(svg);
+    gutter.appendChild(host);
+    let raf = 0;
+    const scheduleDraw = () => {
+        if (raf !== 0)
+            return;
+        raf = globalThis.requestAnimationFrame(() => {
+            raf = 0;
+            drawStretchGutterConnectorsIntoSvg(svg, shell, table, gutter);
+        });
+    };
+    const onScrollOrResize = () => scheduleDraw();
+    shell.addEventListener("scroll", onScrollOrResize, { passive: true });
+    globalThis.addEventListener("resize", onScrollOrResize);
+    const ro = new ResizeObserver(onScrollOrResize);
+    ro.observe(shell);
+    ro.observe(table);
+    ro.observe(gutter);
+    scheduleDraw();
+    globalThis.requestAnimationFrame(() => {
+        scheduleDraw();
+        globalThis.requestAnimationFrame(scheduleDraw);
+    });
+    return {
+        disconnect: () => {
+            if (raf !== 0)
+                globalThis.cancelAnimationFrame(raf);
+            shell.removeEventListener("scroll", onScrollOrResize);
+            globalThis.removeEventListener("resize", onScrollOrResize);
+            ro.disconnect();
+            host.remove();
+        },
+        request: scheduleDraw,
+    };
+}
+function wireStretchSplitter(shell, codePane) {
+    const gutter = document.getElementById("stretch-gutter");
+    if (!(gutter instanceof HTMLElement))
+        return;
+    const stored = Number.parseFloat(readWebStorageItem(localStorage, STORAGE_SPLIT_PCT) ?? "");
+    const initial = clamp(Number.isFinite(stored) ? stored : 50, 15, 85);
+    shell.style.setProperty("--stretch-code-pct", `${String(initial)}%`);
+    let dragging = false;
+    const onMove = (ev) => {
+        if (!dragging)
+            return;
+        const rect = codePane.getBoundingClientRect();
+        if (rect.width <= 0)
+            return;
+        const x = ev.clientX - rect.left;
+        const pct = clamp((x / rect.width) * 100, 15, 85);
+        shell.style.setProperty("--stretch-code-pct", `${String(pct)}%`);
+        writeWebStorageItem(localStorage, STORAGE_SPLIT_PCT, String(pct));
+        stretchGutterConnectorHandle?.request();
+    };
+    const onUp = () => {
+        if (!dragging)
+            return;
+        dragging = false;
+        document.body.style.cursor = "";
+        document.body.style.userSelect = "";
+        globalThis.removeEventListener("mousemove", onMove);
+        globalThis.removeEventListener("mouseup", onUp);
+    };
+    gutter.addEventListener("mousedown", (ev) => {
+        ev.preventDefault();
+        dragging = true;
+        document.body.style.cursor = "col-resize";
+        document.body.style.userSelect = "none";
+        globalThis.addEventListener("mousemove", onMove);
+        globalThis.addEventListener("mouseup", onUp);
+    });
+}
+/** Wrap toggle always; `BufferingFlowSynchronizer` padding pass only when `#shell` has `data-stretch-buffer-sync="flow-synchronizer"`. */
+function wireStretchLayoutChrome(shell, codePane) {
+    if (codePane instanceof HTMLTableElement && stretchFlowSynchronizerEnabled(shell)) {
+        stretchRowBufferSyncHandle?.disconnect();
+        stretchRowBufferSyncHandle = wireBlockStretchBufferSync(codePane);
+    }
+    else {
+        stretchRowBufferSyncHandle?.disconnect();
+        stretchRowBufferSyncHandle = null;
+    }
     const wrapCb = document.getElementById("wrap-lines");
     if (wrapCb) {
         wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb, () => {
             globalThis.dispatchEvent(new Event("resize"));
         });
     }
+    const gutter = document.getElementById("stretch-gutter");
+    stretchGutterConnectorHandle?.disconnect();
+    stretchGutterConnectorHandle =
+        codePane instanceof HTMLElement && gutter instanceof HTMLElement
+            ? wireStretchGutterConnectors(shell, codePane, gutter)
+            : null;
+    wireStretchSplitter(shell, codePane);
+}
+function multiAngleAngleRowLooksValid(row, layoutMode) {
+    if (row === null || typeof row !== "object")
+        return false;
+    const a = row;
+    if (typeof a.id !== "string" || typeof a.docInnerHtmlB64 !== "string")
+        return false;
+    if (layoutMode !== "stretch")
+        return true;
+    return typeof a.stretchSwapInnerB64 === "string" && a.stretchSwapInnerB64.trim().length > 0;
 }
 function parseMultiAnglePayload(script) {
     const t = script?.textContent?.trim() ?? "";
@@ -1886,29 +3001,133 @@ function parseMultiAnglePayload(script) {
         const raw = JSON.parse(decodeBase64Utf8(t));
         if (!raw || !Array.isArray(raw.angles) || raw.angles.length < 2)
             return null;
-        for (const a of raw.angles) {
-            if (typeof a.id !== "string" || typeof a.docInnerHtmlB64 !== "string")
-                return null;
-        }
-        return raw;
+        const layoutMode = raw.layoutMode === "stretch" ? "stretch" : "dual";
+        if (!raw.angles.every((row) => multiAngleAngleRowLooksValid(row, layoutMode)))
+            return null;
+        return { ...raw, layoutMode };
     }
     catch {
         return null;
     }
 }
-function readDualPaneDomBundle() {
+function applyMultiAngleStretchAngleToShell(shell, angle) {
+    const innerB64 = angle.stretchSwapInnerB64;
+    if (innerB64 === undefined || innerB64.trim().length === 0)
+        return;
+    shell.innerHTML = decodeBase64Utf8(innerB64);
+    const nextCodePane = document.getElementById("code-pane");
+    if (nextCodePane instanceof HTMLElement) {
+        wireStretchLayoutChrome(shell, nextCodePane);
+        wireSourceMarkdownControls(shell, nextCodePane, () => {
+            globalThis.dispatchEvent(new Event("resize"));
+        });
+        const flipBtn = document.getElementById("mobile-pane-flip");
+        const flipScrollBtn = document.getElementById("mobile-pane-flip-scroll");
+        if (flipBtn instanceof HTMLButtonElement) {
+            wireStretchMobilePaneFlip(shell, nextCodePane, flipBtn, flipScrollBtn instanceof HTMLButtonElement ? flipScrollBtn : null, () => {
+                globalThis.dispatchEvent(new Event("resize"));
+            });
+        }
+    }
+    shell.setAttribute("data-scroll-block-links-b64", angle.scrollBlockLinksB64);
+    shell.setAttribute("data-raw-md-b64", angle.rawMdB64);
+    shell.setAttribute("data-search-commentray-path", angle.commentrayPathForSearch);
+    const crIdentity = normPosixPath(angle.commentrayPathForSearch);
+    if (crIdentity.length > 0)
+        shell.setAttribute("data-commentray-pair-commentray-path", crIdentity);
+    else
+        shell.removeAttribute("data-commentray-pair-commentray-path");
+    const docPathEl = document.getElementById("nav-rail-doc-path");
+    if (docPathEl) {
+        const path = angle.commentrayPathForSearch.trim();
+        docPathEl.textContent = path.length > 0 ? path : "—";
+        if (path.length > 0)
+            docPathEl.setAttribute("title", path);
+        else
+            docPathEl.removeAttribute("title");
+    }
+    const browse = angle.staticBrowseUrl?.trim() ?? "";
+    if (browse.length > 0) {
+        const resolved = staticBrowseHrefForShellDataAttribute(browse, globalThis.location.pathname, globalThis.location.origin);
+        shell.setAttribute("data-commentray-pair-browse-href", resolved);
+    }
+    else {
+        const ghu = angle.commentrayOnGithubUrl?.trim();
+        if (ghu)
+            shell.setAttribute("data-commentray-pair-browse-href", ghu);
+        else
+            shell.removeAttribute("data-commentray-pair-browse-href");
+    }
+    applyDocumentedTreeCurrentPairHighlight();
+    assignLocationToCanonicalBrowsePermalinkIfNeeded(shell);
+    void runMermaidOnFreshDocNodes(shell);
+    rewriteHubRelativeBrowseAnchorsIn(shell);
+    rootScrollingElement().scrollTop = 0;
+}
+function wireMultiAngleStretchAngleSelect(shell, payload, onAngleApplied) {
+    if (payload.layoutMode !== "stretch")
+        return;
+    const angleSel = document.getElementById("angle-select");
+    if (!angleSel)
+        return;
+    angleSel.addEventListener("change", () => {
+        const a = payload.angles.find((x) => x.id === angleSel.value);
+        if (!a)
+            return;
+        applyMultiAngleStretchAngleToShell(shell, a);
+        onAngleApplied?.(a);
+    });
+}
+function wireStretchSearchUi(shell, codePane) {
+    const searchDom = readDualPaneSearchDom();
+    if (!searchDom)
+        return;
+    const bundle = buildDualPaneSearcherBundle(shell, codePane);
+    const { searchInput, searchClear, searchResults } = searchDom;
+    wireSearchUi({
+        scope: bundle.scope,
+        filePathLabel: bundle.filePathLabel,
+        mutable: bundle.mutable,
+        rawCode: bundle.rawCode,
+        searchInput,
+        searchClear,
+        searchResults,
+        docScrollEl: shell,
+    });
+    wireDualPaneNavSearchFetch(shell, bundle.pathInit.documentedPairs, bundle.indexState, bundle.mutable, bundle.rebuildSearcher, searchInput);
+    const multiScript = document.getElementById("commentray-multi-angle-b64");
+    const multiPayload = parseMultiAnglePayload(multiScript);
+    if (multiPayload?.layoutMode !== "stretch")
+        return;
+    wireMultiAngleStretchAngleSelect(shell, multiPayload, (angle) => {
+        bundle.mutable.rawMd = decodeBase64Utf8(angle.rawMdB64);
+        bundle.mutable.mdLines = bundle.mutable.rawMd.split("\n");
+        bundle.mutable.commentrayPathLabel = angle.commentrayPathForSearch;
+        bundle.rebuildSearcher();
+        searchInput.value = "";
+        searchResults.innerHTML = "";
+        searchResults.hidden = true;
+    });
+}
+function readDualPaneCoreDom() {
     const docPane = document.getElementById("doc-pane");
     const gutter = document.getElementById("gutter");
     const wrapCb = document.getElementById("wrap-lines");
+    if (!docPane || !gutter || !wrapCb) {
+        return null;
+    }
+    const docBody = document.getElementById("doc-pane-body");
+    const docScrollEl = docBody instanceof HTMLElement ? docBody : docPane;
+    return { docBody, docScrollEl, gutter, wrapCb };
+}
+function readDualPaneSearchDom() {
     const searchInput = document.getElementById("search-q");
     const searchClear = document.getElementById("search-clear");
     const searchResults = document.getElementById("search-results");
-    if (!docPane || !gutter || !wrapCb || !searchInput || !searchClear || !searchResults) {
+    if (!searchInput || !searchClear || !searchResults) {
         return null;
     }
-    const docBody = document.getElementById("doc-pane-body");
-    const docScrollEl = docBody instanceof HTMLElement ? docBody : docPane;
-    return { docBody, docScrollEl, gutter, wrapCb, searchInput, searchClear, searchResults };
+    return { searchInput, searchClear, searchResults };
 }
 function hubSearcherRowsForDualPane(args) {
     const { scope, rawCode, filePathLabel, hubNavRows, pathRowsForOrdering, rawMd, commentrayPathLabel, } = args;
@@ -2014,7 +3233,7 @@ function wireDualPaneNavSearchFetch(shell, embeddedPairs, indexState, mutable, r
 function applySelectedMultiAngle(args) {
     const { angle, docBody, mutable, rebuildSearcher, scrollLinksRef, shell, searchInput, searchResults, requestBlockRayRedraw, } = args;
     docBody.innerHTML = decodeBase64Utf8(angle.docInnerHtmlB64);
-    runMermaidOnFreshDocNodes(docBody);
+    void runMermaidOnFreshDocNodes(docBody);
     rewriteHubRelativeBrowseAnchorsIn(docBody);
     mutable.rawMd = decodeBase64Utf8(angle.rawMdB64);
     mutable.mdLines = mutable.rawMd.split("\n");
@@ -2050,9 +3269,12 @@ function applySelectedMultiAngle(args) {
         else
             shell.removeAttribute("data-commentray-pair-browse-href");
     }
-    searchInput.value = "";
-    searchResults.innerHTML = "";
-    searchResults.hidden = true;
+    if (searchInput && searchResults) {
+        searchInput.value = "";
+        searchResults.innerHTML = "";
+        searchResults.hidden = true;
+    }
+    assignLocationToCanonicalBrowsePermalinkIfNeeded(shell);
     requestBlockRayRedraw?.();
     globalThis.requestAnimationFrame(() => {
         requestBlockRayRedraw?.();
@@ -2061,10 +3283,14 @@ function applySelectedMultiAngle(args) {
         });
     });
 }
-function wireDualPaneMultiAngleAndScroll(args) {
+/**
+ * Indexed / multi-angle wiring plus proportional fallback when there is no block map.
+ * `allowProportionalMirror: false` implements **block-snap-only** (partner holds in gaps / no index).
+ */
+function wireDualPaneScrollIndexedOrProportional(args, blockAwareOpts) {
     const { codePane, docScrollEl, docBody, shell, scrollLinksRef, multiPayload, mutable, rebuildSearcher, searchInput, searchResults, requestBlockRayRedraw, } = args;
     if (multiPayload) {
-        const runners = wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current, () => sourceLineIdPrefixForShell(shell), () => sourcePaneModeForShell(shell) === "rendered-markdown");
+        const runners = wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current, () => sourceLineIdPrefixForShell(shell), () => sourcePaneModeForShell(shell) === "rendered-markdown", blockAwareOpts);
         const angleSel = document.getElementById("angle-select");
         if (angleSel && docBody) {
             angleSel.addEventListener("change", () => {
@@ -2087,9 +3313,19 @@ function wireDualPaneMultiAngleAndScroll(args) {
         return runners;
     }
     if (scrollLinksRef.current.length > 0) {
-        return wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current, () => sourceLineIdPrefixForShell(shell), () => sourcePaneModeForShell(shell) === "rendered-markdown");
+        return wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current, () => sourceLineIdPrefixForShell(shell), () => sourcePaneModeForShell(shell) === "rendered-markdown", blockAwareOpts);
     }
-    return wireProportionalScrollSync(codePane, docScrollEl);
+    if (blockAwareOpts.allowProportionalMirror) {
+        return wireProportionalScrollSync(codePane, docScrollEl);
+    }
+    return wireBlockAwareScrollSync(codePane, docScrollEl, () => [], () => sourceLineIdPrefixForShell(shell), () => sourcePaneModeForShell(shell) === "rendered-markdown", blockAwareOpts);
+}
+function wireDualPaneMultiAngleAndScroll(args) {
+    const strategy = parseDualPaneScrollSyncStrategy(args.shell.getAttribute("data-scroll-sync-strategy"));
+    const blockAwareOpts = strategy === "block-snap-only"
+        ? { allowProportionalMirror: false }
+        : { allowProportionalMirror: true };
+    return wireDualPaneScrollIndexedOrProportional(args, blockAwareOpts);
 }
 function wireDualPaneCommentrayLocationHash(docScrollEl, mdLineCount) {
     function commentrayMdLineFromLocationHash(rawHash) {
@@ -2124,18 +3360,23 @@ function wireDualPaneCommentrayLocationHash(docScrollEl, mdLineCount) {
 function initializeSourceMarkdownPane(shell) {
     if (sourcePaneModeForShell(shell) !== "rendered-markdown")
         return;
-    const sourceMdBody = document.getElementById("code-pane-markdown-body");
-    if (!(sourceMdBody instanceof HTMLElement))
+    const codePane = document.getElementById("code-pane");
+    if (!(codePane instanceof HTMLElement))
         return;
-    runMermaidOnFreshDocNodes(sourceMdBody);
-    rewriteHubRelativeBrowseAnchorsIn(sourceMdBody);
+    for (const sourceMdBody of codePane.querySelectorAll('[data-source-markdown-body="true"]')) {
+        void runMermaidOnFreshDocNodes(sourceMdBody);
+        rewriteHubRelativeBrowseAnchorsIn(sourceMdBody);
+    }
 }
+let sourceMarkdownControlsAbort = null;
 function wireSourceMarkdownControls(shell, codePane, onAfterFlip) {
     const sourceMdFlip = document.getElementById("source-markdown-pane-flip");
     const sourceMdFlipScroll = document.getElementById("source-markdown-pane-flip-scroll");
     if (!(sourceMdFlip instanceof HTMLButtonElement))
         return;
-    wireSourceMarkdownPaneFlip(shell, codePane, sourceMdFlip, sourceMdFlipScroll instanceof HTMLButtonElement ? sourceMdFlipScroll : null, onAfterFlip);
+    sourceMarkdownControlsAbort?.abort();
+    sourceMarkdownControlsAbort = new AbortController();
+    wireSourceMarkdownPaneFlip(shell, codePane, sourceMdFlip, sourceMdFlipScroll instanceof HTMLButtonElement ? sourceMdFlipScroll : null, sourceMarkdownControlsAbort.signal, onAfterFlip);
     initializeSourceMarkdownPane(shell);
 }
 function buildDualPaneSearcherBundle(shell, codePane) {
@@ -2186,23 +3427,28 @@ function buildDualPaneSearcherBundle(shell, codePane) {
     };
 }
 function wireDualPaneCodeBrowser(shell, codePane) {
-    const dom = readDualPaneDomBundle();
-    if (!dom)
+    const coreDom = readDualPaneCoreDom();
+    if (!coreDom) {
         return;
-    const { docBody, docScrollEl, gutter, wrapCb, searchInput, searchClear, searchResults } = dom;
+    }
+    const { docBody, docScrollEl, gutter, wrapCb } = coreDom;
+    const searchDom = readDualPaneSearchDom();
     const bundle = buildDualPaneSearcherBundle(shell, codePane);
     rewriteHubRelativeBrowseAnchorsIn(document);
-    wireSearchUi({
-        scope: bundle.scope,
-        filePathLabel: bundle.filePathLabel,
-        mutable: bundle.mutable,
-        rawCode: bundle.rawCode,
-        searchInput,
-        searchClear,
-        searchResults,
-        docScrollEl,
-    });
-    wireDualPaneNavSearchFetch(shell, bundle.pathInit.documentedPairs, bundle.indexState, bundle.mutable, bundle.rebuildSearcher, searchInput);
+    if (searchDom) {
+        const { searchInput, searchClear, searchResults } = searchDom;
+        wireSearchUi({
+            scope: bundle.scope,
+            filePathLabel: bundle.filePathLabel,
+            mutable: bundle.mutable,
+            rawCode: bundle.rawCode,
+            searchInput,
+            searchClear,
+            searchResults,
+            docScrollEl,
+        });
+        wireDualPaneNavSearchFetch(shell, bundle.pathInit.documentedPairs, bundle.indexState, bundle.mutable, bundle.rebuildSearcher, searchInput);
+    }
     const pct0 = parseFloat(readWebStorageItem(localStorage, STORAGE_SPLIT_PCT) || "46");
     const pct = clamp(Number.isFinite(pct0) ? pct0 : 46, 15, 85);
     codePane.style.flex = `0 0 ${pct}%`;
@@ -2238,8 +3484,8 @@ function wireDualPaneCodeBrowser(shell, codePane) {
         multiPayload,
         mutable: bundle.mutable,
         rebuildSearcher: bundle.rebuildSearcher,
-        searchInput,
-        searchResults,
+        searchInput: searchDom?.searchInput,
+        searchResults: searchDom?.searchResults,
         requestBlockRayRedraw,
     });
     const flipBtn = document.getElementById("mobile-pane-flip");
@@ -2365,46 +3611,9 @@ function safePermalinkHref(raw) {
         return null;
     }
 }
-function humaneBrowseAliasPathForSource(sourcePath) {
-    return sourcePath
-        .split("/")
-        .filter((seg) => seg.length > 0)
-        .map((seg) => seg.startsWith(".") ? `%2E${encodeURIComponent(seg.slice(1))}` : encodeURIComponent(seg))
-        .join("/");
-}
-function companionStemFromCommentrayPath(commentrayPath) {
-    const norm = normPosixPath(commentrayPath);
-    const last = norm.split("/").filter(Boolean).at(-1) ?? "";
-    return last.replace(/\.md$/i, "").trim();
-}
 function makeAbsoluteUrlAgainst(raw, baseHref) {
     return new URL(raw, baseHref).toString();
 }
-function shellEligibleForHumaneBackfill(shell, pathname) {
-    if ((shell.getAttribute("data-layout") ?? "dual") !== "dual")
-        return false;
-    if (pathname.includes("/browse/"))
-        return false;
-    return pathname.endsWith("/") || pathname.endsWith("/index.html");
-}
-function nextHumaneBrowsePathForShell(shell, pathname) {
-    const sourcePath = normPosixPath(shell.getAttribute("data-commentray-pair-source-path") ?? "");
-    if (sourcePath.length === 0)
-        return null;
-    const alias = humaneBrowseAliasPathForSource(sourcePath);
-    if (alias.length === 0)
-        return null;
-    const angleSel = document.getElementById("angle-select");
-    const selectedAngle = angleSel instanceof HTMLSelectElement ? angleSel.value.trim() : "";
-    const commentrayPath = shell.getAttribute("data-commentray-pair-commentray-path") ?? "";
-    const stem = companionStemFromCommentrayPath(commentrayPath);
-    const angleName = selectedAngle.length > 0 ? selectedAngle : stem;
-    if (angleName.length === 0)
-        return null;
-    const angleAlias = `${alias}@${encodeURIComponent(angleName)}.html`;
-    const siteRoot = siteRootPathnameFromPathname(pathname);
-    return siteRoot === "/" ? `/browse/${angleAlias}` : `${siteRoot}/browse/${angleAlias}`;
-}
 function absolutizeNavJsonUrls(shell, beforeHref) {
     const navSearchRaw = shell.getAttribute("data-nav-search-json-url")?.trim() ?? "";
     if (navSearchRaw.length > 0) {
@@ -2424,14 +3633,6 @@ function normalizePairBrowseHrefForCurrentPath(shell, pathname) {
         shell.setAttribute("data-commentray-pair-browse-href", resolveStaticBrowseHref(pairBrowseRaw, pathname, globalThis.location.origin));
     }
 }
-function normalizeDocumentationHomeHrefForCurrentPath() {
-    const home = document.querySelector('a[aria-label="Documentation home"]');
-    if (!(home instanceof HTMLAnchorElement))
-        return;
-    const siteRoot = siteRootPathnameFromPathname(globalThis.location.pathname);
-    const normalized = siteRoot === "/" ? "/" : `${siteRoot}/`;
-    home.setAttribute("href", normalized);
-}
 function activeCommentrayHashTokenFromViewport() {
     const docPane = document.getElementById("doc-pane");
     if (!(docPane instanceof HTMLElement))
@@ -2442,42 +3643,33 @@ function activeCommentrayHashTokenFromViewport() {
     if (anchors.length === 0)
         return null;
     const mdLine0 = probeCommentrayLine0FromDoc(docScrollEl);
-    if (!Number.isFinite(mdLine0) || mdLine0 < 0)
+    if (mdLine0 === null || !Number.isFinite(mdLine0) || mdLine0 < 0)
         return null;
     return `commentray-md-line-${String(mdLine0)}`;
 }
-function maybeBackfillAddressBarWithHumanePairLink() {
-    const shell = document.getElementById("shell");
-    if (!(shell instanceof HTMLElement))
+/**
+ * Resolves hub-relative `data-nav-*` and pair-browse attributes against the current document URL so
+ * `fetch()` and toolbar targets work from deep `/browse/…/index.html` pages (static HTML stays portable).
+ */
+function resolveEmbeddedStaticNavUrlsForCurrentPage(shell) {
+    if ((shell.getAttribute("data-layout") ?? "dual") !== "dual")
         return;
     const pathname = globalThis.location.pathname;
-    normalizeDocumentationHomeHrefForCurrentPath();
-    if (!shellEligibleForHumaneBackfill(shell, pathname))
-        return;
     const beforeHref = globalThis.location.href;
     absolutizeNavJsonUrls(shell, beforeHref);
     normalizePairBrowseHrefForCurrentPath(shell, pathname);
-    /** Prefer the same `staticBrowseUrl` the static build put on `#shell` (slug or `…/index.html` shims). */
-    const canonicalBrowsePathname = (() => {
-        const raw = shell.getAttribute("data-commentray-pair-browse-href")?.trim() ?? "";
-        if (raw.length === 0)
-            return null;
-        try {
-            const u = new URL(raw, globalThis.location.href);
-            if (u.origin !== globalThis.location.origin)
-                return null;
-            if (!u.pathname.includes("/browse/"))
-                return null;
-            return u.pathname;
-        }
-        catch {
-            return null;
-        }
-    })();
-    const nextPath = canonicalBrowsePathname ?? nextHumaneBrowsePathForShell(shell, pathname);
-    if (nextPath === null)
-        return;
-    globalThis.history.replaceState(null, "", `${nextPath}${globalThis.location.search}${globalThis.location.hash}`);
+}
+/**
+ * Absolute base URL for the pair browse / permalink target from `#shell` `data-commentray-pair-browse-href`
+ * (hub-relative `./browse/…` resolved via {@link resolveStaticBrowseHref}; same contract as static build).
+ */
+function pairBrowsePermalinkBaseHrefFromShell(shell) {
+    const raw = shell.getAttribute("data-commentray-pair-browse-href") ?? "";
+    const t = raw.trim();
+    const canonical = isHubRelativeStaticBrowseHref(t) && t.length > 0
+        ? resolveStaticBrowseHref(t, globalThis.location.pathname, globalThis.location.origin)
+        : safePermalinkHref(t);
+    return canonical ?? globalThis.location.href;
 }
 function permalinkHashSuffixFromUi() {
     const tokens = [];
@@ -2501,16 +3693,31 @@ function permalinkHashSuffixFromUi() {
     return tokens.length > 0 ? `#${tokens.join("&")}` : "";
 }
 function sharePermalinkFromShell(shell) {
-    const raw = shell.getAttribute("data-commentray-pair-browse-href") ?? "";
-    const canonical = isHubRelativeStaticBrowseHref(raw.trim()) && raw.trim().length > 0
-        ? resolveStaticBrowseHref(raw.trim(), globalThis.location.pathname, globalThis.location.origin)
-        : safePermalinkHref(raw);
-    const base = canonical ?? globalThis.location.href;
-    const u = new URL(base, globalThis.location.href);
+    const u = new URL(pairBrowsePermalinkBaseHrefFromShell(shell), globalThis.location.href);
     const hash = permalinkHashSuffixFromUi();
     u.hash = hash.length > 0 ? hash.slice(1) : "";
     return u.toString();
 }
+/**
+ * Static multi-angle: each angle has its own `/browse/…/<angle>/index.html`. After `#angle-select`
+ * changes, load that canonical page without a `#angle-…` fragment (path is the permalink).
+ */
+function assignLocationToCanonicalBrowsePermalinkIfNeeded(shell) {
+    let target;
+    try {
+        target = new URL(pairBrowsePermalinkBaseHrefFromShell(shell), globalThis.location.href);
+    }
+    catch {
+        return;
+    }
+    if (target.origin !== globalThis.location.origin)
+        return;
+    target.hash = "";
+    const here = new URL(globalThis.location.href);
+    if (here.pathname === target.pathname && here.search === target.search)
+        return;
+    globalThis.location.assign(target.toString());
+}
 async function writeTextToClipboard(text) {
     try {
         await navigator.clipboard.writeText(text);
@@ -2563,6 +3770,7 @@ function wireSharePermalinkButton() {
     });
 }
 function main() {
+    announceScrollSyncTraceOnBoot();
     wireSharePermalinkButton();
     wireColorThemeToolbar();
     wireDocumentedFilesTree();
@@ -2576,11 +3784,22 @@ function main() {
     wireWideModeIntroTrigger(shell);
     const layout = shell.getAttribute("data-layout") || "dual";
     if (layout === "stretch") {
-        wireStretchLayoutChrome(codePane);
+        wireStretchLayoutChrome(shell, codePane);
+        wireStretchSearchUi(shell, codePane);
+        wireSourceMarkdownControls(shell, codePane, () => {
+            globalThis.dispatchEvent(new Event("resize"));
+        });
+        const flipBtn = document.getElementById("mobile-pane-flip");
+        const flipScrollBtn = document.getElementById("mobile-pane-flip-scroll");
+        if (flipBtn instanceof HTMLButtonElement) {
+            wireStretchMobilePaneFlip(shell, codePane, flipBtn, flipScrollBtn instanceof HTMLButtonElement ? flipScrollBtn : null, () => {
+                globalThis.dispatchEvent(new Event("resize"));
+            });
+        }
         return;
     }
     wireDualPaneCodeBrowser(shell, codePane);
-    maybeBackfillAddressBarWithHumanePairLink();
+    resolveEmbeddedStaticNavUrlsForCurrentPage(shell);
 }
 if (document.readyState === "loading") {
     document.addEventListener("DOMContentLoaded", main);