@commentray/render 0.0.9 → 0.1.1

package/dist/code-browser-client.js

@@ -1,11 +1,13 @@
 import { FuzzySearcher, PrefixSearcher, Query, SearcherFactory, SubstringSearcher, } from "@m31coding/fuzzy-search";
-import { activeBlockIdForViewport, clampViewportYToGutterLocal, codeLineDomIndex0, gutterRayBezierPaths, sortBlockLinksBySource, } from "./code-browser-block-rays.js";
+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 { 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, staticBrowseHrefForShellDataAttribute, } from "./code-browser-pair-nav.js";
+import { findDocumentedPair, isHubRelativeStaticBrowseHref, isSameDocumentedPair, normPosixPath, resolveStaticBrowseHref, siteRootPathnameFromPathname, staticBrowseHrefForShellDataAttribute, } from "./code-browser-pair-nav.js";
 import { COMMENTRAY_COLOR_THEME_STORAGE_KEY, applyCommentrayColorTheme, nextCommentrayColorThemeMode, parseCommentrayColorThemeMode, } from "./code-browser-color-theme.js";
+import { wireWideModeIntroTour } from "./code-browser-wide-intro-controller.js";
 import { readWebStorageItem, writeWebStorageItem } from "./code-browser-web-storage.js";
 /**
  * Hub pages emit `./browse/…` relative to the site root. From `/…/browse/current.html` the browser
@@ -104,9 +106,13 @@ function windowScrollRatio() {
     const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
     return maxY > 0 ? clamp(root.scrollTop / maxY, 0, 1) : 0;
 }
-function applyDocToCodeFlipPlanImpl(codePane, _docPane, plan) {
+function applyDocToCodeFlipPlanImpl(codePane, _docPane, plan, lineIdPrefix = "code-line-") {
+    const narrowSinglePane = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ).matches;
     if (plan.k === "block") {
-        const el = codePane.querySelector(`#code-line-${String(plan.src0)}`);
+        const exact = codePane.querySelector(`#${lineIdPrefix}${String(plan.src0)}`);
+        const el = exact instanceof HTMLElement
+            ? exact
+            : findAnchorAtOrAfter(sourceAnchorsFromPrefix(lineIdPrefix), plan.src0);
         if (el) {
             applyRevealChildInPane(codePane, el, 2);
         }
@@ -119,6 +125,8 @@ function applyDocToCodeFlipPlanImpl(codePane, _docPane, plan) {
         if (paneUsesInternalYScroll(codePane)) {
             const maxC = Math.max(0, codePane.scrollHeight - codePane.clientHeight);
             applyScrollTopClamped(codePane, plan.ratio * maxC);
+            if (narrowSinglePane)
+                applyWindowScrollRatio(plan.ratio);
         }
         else {
             applyWindowScrollRatio(plan.ratio);
@@ -128,6 +136,10 @@ function applyDocToCodeFlipPlanImpl(codePane, _docPane, plan) {
     const nextTop = mirroredScrollTop(plan.docTop, plan.docSH, plan.docCH, codePane.scrollHeight, codePane.clientHeight);
     if (paneUsesInternalYScroll(codePane)) {
         applyScrollTopClamped(codePane, nextTop);
+        if (narrowSinglePane) {
+            const denom = Math.max(1, codePane.scrollHeight - codePane.clientHeight);
+            applyWindowScrollRatio(clamp(nextTop / denom, 0, 1));
+        }
         return;
     }
     const denom = Math.max(1, codePane.scrollHeight - codePane.clientHeight);
@@ -163,7 +175,12 @@ function applyCodeToDocFlipPlanImpl(_codePane, docPane, plan) {
     applyWindowScrollRatio(clamp(nextTop / denom, 0, 1));
 }
 function buildDocToCodeFlipPlanBlockAware(docPane, getLinks) {
-    const winRatio = windowScrollRatio();
+    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 };
     const links = getLinks();
     const mdLine0 = probeCommentrayLine0FromDoc(docPane);
     const src0 = pickSourceLine0ForCommentrayScroll(links, mdLine0);
@@ -179,10 +196,10 @@ function buildDocToCodeFlipPlanBlockAware(docPane, getLinks) {
     }
     return { k: "mirrorW", ratio: winRatio };
 }
-function buildCodeToDocFlipPlanBlockAware(codePane, _docPane, getLinks) {
+function buildCodeToDocFlipPlanBlockAware(codePane, _docPane, getLinks, lineIdPrefix = "code-line-") {
     const winRatio = windowScrollRatio();
     const links = getLinks();
-    const line1 = probeCodeLine1FromViewport(codePane);
+    const line1 = probeCodeLine1FromViewport(codePane, lineIdPrefix);
     const mdLine0 = pickCommentrayLineForSourceScroll(links, line1);
     if (mdLine0 === null) {
         if (paneUsesInternalYScroll(codePane)) {
@@ -684,11 +701,22 @@ function parseScrollBlockLinksFromShell(b64) {
                 typeof o.commentrayLine === "number" &&
                 typeof o.sourceStart === "number" &&
                 typeof o.sourceEnd === "number") {
+                const mvRaw = o.markerViewportHalfOpen1Based;
+                const mv = typeof mvRaw === "object" &&
+                    mvRaw !== null &&
+                    typeof mvRaw.lo === "number" &&
+                    typeof mvRaw.hiExclusive === "number"
+                    ? {
+                        lo: mvRaw.lo,
+                        hiExclusive: mvRaw.hiExclusive,
+                    }
+                    : { lo: o.sourceStart, hiExclusive: o.sourceEnd + 1 };
                 out.push({
                     id: o.id,
                     commentrayLine: o.commentrayLine,
                     sourceStart: o.sourceStart,
                     sourceEnd: o.sourceEnd,
+                    markerViewportHalfOpen1Based: mv,
                 });
             }
         }
@@ -703,14 +731,41 @@ function rootScrollNearDocumentEnd(edgePx = 56) {
     const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
     return maxY > 0 && root.scrollTop >= maxY - edgePx;
 }
-function probeCodeLine1FromViewport(codePane) {
-    const rows = codePane.querySelectorAll('[id^="code-line-"]');
+/** When the pane itself is the scrollport (dual desktop), mirror root “near end” behavior. */
+function paneScrollNearEnd(pane, edgePx = 56) {
+    const maxY = Math.max(0, pane.scrollHeight - pane.clientHeight);
+    return maxY > 0 && pane.scrollTop >= maxY - edgePx;
+}
+function readCommentrayLine0FromAnchor(el) {
+    const lineAttr = el.getAttribute("data-commentray-line");
+    if (lineAttr === null || lineAttr === "")
+        return null;
+    return Number(lineAttr);
+}
+function bestCommentrayAnchorLine0AtOrAboveY(anchors, y) {
+    const readings = [];
+    for (const a of anchors) {
+        const line0 = readCommentrayLine0FromAnchor(a);
+        if (line0 === null)
+            continue;
+        readings.push({ line0, top: a.getBoundingClientRect().top });
+    }
+    return maxCommentrayAnchorLine0AtOrAboveViewportY(readings, y);
+}
+function lastCommentrayAnchorLine0(anchors) {
+    const last = anchors[anchors.length - 1];
+    if (!last)
+        return 0;
+    return readCommentrayLine0FromAnchor(last) ?? 0;
+}
+function probeCodeLine1FromViewport(codePane, lineIdPrefix = "code-line-") {
+    const rows = codePane.querySelectorAll(`[id^="${lineIdPrefix}"]`);
     if (rows.length === 0)
         return 1;
     if (!paneUsesInternalYScroll(codePane)) {
         if (rootScrollNearDocumentEnd()) {
             const last = rows[rows.length - 1];
-            const m = /^code-line-(\d+)$/.exec(last.id);
+            const m = /^(?:code-line-|code-md-line-)(\d+)$/.exec(last.id);
             if (m)
                 return Number(m[1]) + 1;
             return rows.length;
@@ -723,7 +778,7 @@ function probeCodeLine1FromViewport(codePane) {
         for (const el of rows) {
             const r = el.getBoundingClientRect();
             if (r.bottom > y - 1e-3) {
-                const m = /^code-line-(\d+)$/.exec(el.id);
+                const m = /^(?:code-line-|code-md-line-)(\d+)$/.exec(el.id);
                 if (m)
                     return Number(m[1]) + 1;
                 return 1;
@@ -731,12 +786,19 @@ function probeCodeLine1FromViewport(codePane) {
         }
         return rows.length;
     }
+    if (paneScrollNearEnd(codePane)) {
+        const last = rows[rows.length - 1];
+        const m = /^(?:code-line-|code-md-line-)(\d+)$/.exec(last.id);
+        if (m)
+            return Number(m[1]) + 1;
+        return rows.length;
+    }
     const sr = codePane.getBoundingClientRect();
     const y = sr.top + codePane.clientTop + 2;
     for (const el of rows) {
         const r = el.getBoundingClientRect();
         if (r.bottom > y - 1e-3) {
-            const m = /^code-line-(\d+)$/.exec(el.id);
+            const m = /^(?:code-line-|code-md-line-)(\d+)$/.exec(el.id);
             if (m)
                 return Number(m[1]) + 1;
             return 1;
@@ -749,41 +811,75 @@ function probeCommentrayLine0FromDoc(docPane) {
     if (anchors.length === 0)
         return 0;
     if (!paneUsesInternalYScroll(docPane)) {
-        if (rootScrollNearDocumentEnd()) {
-            const last = anchors[anchors.length - 1];
-            const lineAttr = last.getAttribute("data-commentray-line");
-            return lineAttr !== null && lineAttr !== "" ? Number(lineAttr) : 0;
-        }
+        if (rootScrollNearDocumentEnd())
+            return lastCommentrayAnchorLine0(anchors);
         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));
-        let best = 0;
-        for (const a of anchors) {
-            const lineAttr = a.getAttribute("data-commentray-line");
-            if (lineAttr === null || lineAttr === "")
-                continue;
-            if (a.getBoundingClientRect().top <= y + 1 + 1e-3)
-                best = Number(lineAttr);
-            else
-                break;
-        }
-        return best;
+        return bestCommentrayAnchorLine0AtOrAboveY(anchors, y);
     }
+    if (paneScrollNearEnd(docPane))
+        return lastCommentrayAnchorLine0(anchors);
     const dr = docPane.getBoundingClientRect();
-    const y = dr.top + docPane.clientTop + 2;
-    let best = 0;
-    for (const a of anchors) {
-        const lineAttr = a.getAttribute("data-commentray-line");
-        if (lineAttr === null || lineAttr === "")
+    /** 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));
+    return bestCommentrayAnchorLine0AtOrAboveY(anchors, y);
+}
+function pageBreakPullEnabled() {
+    const shell = document.getElementById("shell");
+    if (!(shell instanceof HTMLElement))
+        return false;
+    return shell.getAttribute("data-page-breaks-enabled") === "true";
+}
+function docProbeTopY(docPane) {
+    if (!paneUsesInternalYScroll(docPane)) {
+        const dr = docPane.getBoundingClientRect();
+        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));
+    }
+    const dr = docPane.getBoundingClientRect();
+    return dr.top + docPane.clientTop + 2;
+}
+/**
+ * In long synthetic page-break gaps, shift source toward the next block once
+ * the break itself occupies the top reading position.
+ */
+function pulledSourceLine0FromPageBreak(docPane) {
+    if (!pageBreakPullEnabled())
+        return null;
+    const topY = docProbeTopY(docPane);
+    const breaks = Array.from(docPane.querySelectorAll(".commentray-page-break[data-next-source-start]"));
+    for (const pageBreak of breaks) {
+        const nextSourceStartRaw = pageBreak.getAttribute("data-next-source-start");
+        if (!nextSourceStartRaw)
             continue;
-        if (a.getBoundingClientRect().top <= y + 1 + 1e-3)
-            best = Number(lineAttr);
-        else
-            break;
+        const nextSourceStart = Number.parseInt(nextSourceStartRaw, 10);
+        if (!Number.isFinite(nextSourceStart) || nextSourceStart <= 0)
+            continue;
+        const breakTop = pageBreak.getBoundingClientRect().top;
+        const nextLineRaw = pageBreak.getAttribute("data-next-commentray-line");
+        const nextLine0 = nextLineRaw ? Number.parseInt(nextLineRaw, 10) : Number.NaN;
+        const nextAnchor = Number.isFinite(nextLine0) && nextLine0 >= 0
+            ? docPane.querySelector(`[data-commentray-line="${String(nextLine0)}"]`)
+            : null;
+        const nextTop = nextAnchor
+            ? nextAnchor.getBoundingClientRect().top
+            : breakTop + pageBreak.clientHeight;
+        if (!(breakTop <= topY && topY < nextTop))
+            continue;
+        const denom = Math.max(1, nextTop - breakTop);
+        const progress = clamp((topY - breakTop) / denom, 0, 1);
+        const narrow = globalThis.matchMedia("(max-width: 767px)").matches;
+        const pullThreshold = narrow ? 0.2 : 0.35;
+        if (progress < pullThreshold)
+            return null;
+        return nextSourceStart - 1;
     }
-    return best;
+    return null;
 }
 /**
  * Programmatic `scrollTop` on the partner pane can emit a `scroll` event after the
@@ -832,16 +928,20 @@ function wireBidirectionalScroll(codePane, docPane, syncFromCode, syncFromDoc) {
     }, { passive: true });
 }
 /** Index-backed scroll sync when `data-scroll-block-links-b64` is present; else see proportional fallback. */
-function wireBlockAwareScrollSync(codePane, docPane, getLinks) {
+function wireBlockAwareScrollSync(codePane, docPane, getLinks, lineIdPrefix, shouldUseProportionalDocToCodeOnMobileFlip) {
     let pendingDocToCode = null;
     let pendingCodeToDoc = null;
     const syncFromCodeToDoc = () => {
-        applyCodeToDocFlipPlanImpl(codePane, docPane, buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks));
+        applyCodeToDocFlipPlanImpl(codePane, docPane, buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks, lineIdPrefix()));
     };
     const syncFromDocToCode = () => {
-        applyDocToCodeFlipPlanImpl(codePane, docPane, buildDocToCodeFlipPlanBlockAware(docPane, getLinks));
+        applyDocToCodeFlipPlanImpl(codePane, docPane, buildDocToCodeFlipPlanBlockAware(docPane, getLinks), lineIdPrefix());
     };
     const prepareMobileFlipToCode = () => {
+        if (shouldUseProportionalDocToCodeOnMobileFlip?.() === true) {
+            pendingDocToCode = { k: "mirrorW", ratio: windowScrollRatio() };
+            return;
+        }
         pendingDocToCode = buildDocToCodeFlipPlanBlockAware(docPane, getLinks);
     };
     const finishMobileFlipToCode = () => {
@@ -849,10 +949,10 @@ function wireBlockAwareScrollSync(codePane, docPane, getLinks) {
             return;
         const p = pendingDocToCode;
         pendingDocToCode = null;
-        applyDocToCodeFlipPlanImpl(codePane, docPane, p);
+        applyDocToCodeFlipPlanImpl(codePane, docPane, p, lineIdPrefix());
     };
     const prepareMobileFlipToDoc = () => {
-        pendingCodeToDoc = buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks);
+        pendingCodeToDoc = buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks, lineIdPrefix());
     };
     const finishMobileFlipToDoc = () => {
         if (!pendingCodeToDoc)
@@ -924,18 +1024,76 @@ function centerYInViewport(el) {
 function codeLineHighlightCenterYViewport(lineEl) {
     return centerYInViewport(lineEl);
 }
-function commentaryBandEndYViewport(docScrollEl, next, docTop) {
+function commentaryBandEndYViewport(docScrollEl, next, docTop, clipThroughPageBreakGaps) {
     if (next) {
         const nextEl = document.getElementById(`commentray-block-${next.id}`);
-        return nextEl ? nextEl.getBoundingClientRect().top - 3 : centerYInViewport(docTop);
+        if (!nextEl)
+            return centerYInViewport(docTop);
+        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));
     }
     const dr = docScrollEl.getBoundingClientRect();
     let bottom = dr.bottom - 4;
     const lastKid = docScrollEl.children[docScrollEl.children.length - 1];
     if (lastKid)
         bottom = Math.min(bottom, lastKid.getBoundingClientRect().bottom - 4);
+    if (clipThroughPageBreakGaps) {
+        const docBandTop = docTop.getBoundingClientRect().top + 4;
+        const contentBottom = maxRenderableCommentaryContentBottomViewport(docScrollEl, docTop, null);
+        bottom = Math.min(bottom, Math.max(docBandTop, contentBottom));
+    }
     return bottom;
 }
+function sourceAnchorIndexFromId(id, prefix) {
+    if (!id.startsWith(prefix))
+        return null;
+    const n = Number.parseInt(id.slice(prefix.length), 10);
+    return Number.isFinite(n) ? n : null;
+}
+function findAnchorAtOrAfter(anchors, line0) {
+    let lo = 0;
+    let hi = anchors.length - 1;
+    let ans = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const line = anchors[mid]?.line0 ?? -1;
+        if (line >= line0) {
+            ans = mid;
+            hi = mid - 1;
+        }
+        else {
+            lo = mid + 1;
+        }
+    }
+    return ans >= 0 ? (anchors[ans]?.el ?? null) : null;
+}
+function findAnchorAtOrBefore(anchors, line0) {
+    let lo = 0;
+    let hi = anchors.length - 1;
+    let ans = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const line = anchors[mid]?.line0 ?? -1;
+        if (line <= line0) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return ans >= 0 ? (anchors[ans]?.el ?? null) : null;
+}
+function sourceAnchorsFromPrefix(prefix) {
+    return Array.from(document.querySelectorAll(`[id^="${prefix}"]`))
+        .map((el) => ({ line0: sourceAnchorIndexFromId(el.id, prefix), el }))
+        .filter((x) => x.line0 !== null)
+        .sort((a, b) => a.line0 - b.line0);
+}
 function subscribeBlockRayRedraw(gutter, codePane, docScrollEl, scheduleDraw) {
     const onScrollOrResize = () => scheduleDraw();
     codePane.addEventListener("scroll", onScrollOrResize, { passive: true });
@@ -949,8 +1107,8 @@ function subscribeBlockRayRedraw(gutter, codePane, docScrollEl, scheduleDraw) {
     if (shell)
         ro.observe(shell);
 }
-function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based) {
-    const links = getLinks();
+function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based, lineIdPrefix) {
+    const links = dedupeBlockScrollLinksById(getLinks());
     const sorted = sortBlockLinksBySource(links);
     const gutterRect = gutter.getBoundingClientRect();
     const w = gutterRect.width;
@@ -959,23 +1117,33 @@ function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSource
         svg.replaceChildren();
         return;
     }
-    const activeId = activeBlockIdForViewport(links, probeTopSourceLine1Based());
+    /** 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 clipGutterRaysThroughPageBreakGaps = pageBreakPullEnabled();
     svg.setAttribute("viewBox", `0 0 ${String(w)} ${String(h)}`);
     svg.setAttribute("preserveAspectRatio", "none");
     const parts = [];
+    const sourceAnchors = Array.from(document.querySelectorAll(`[id^="${lineIdPrefix}"]`))
+        .map((el) => ({ line0: sourceAnchorIndexFromId(el.id, lineIdPrefix), el }))
+        .filter((x) => x.line0 !== null)
+        .sort((a, b) => a.line0 - b.line0);
     for (let i = 0; i < sorted.length; i++) {
         const link = sorted[i];
         if (!link)
             continue;
-        const next = sorted[i + 1];
+        const next = nextBlockLinkInCommentrayOrder(links, link);
         const i0 = codeLineDomIndex0(link.sourceStart);
         const i1 = codeLineDomIndex0(link.sourceEnd);
-        const codeTop = document.getElementById(`code-line-${String(i0)}`);
-        const codeBot = document.getElementById(`code-line-${String(i1)}`);
+        const codeTop = document.getElementById(`${lineIdPrefix}${String(i0)}`) ??
+            findAnchorAtOrAfter(sourceAnchors, i0);
+        const codeBot = document.getElementById(`${lineIdPrefix}${String(i1)}`) ??
+            findAnchorAtOrBefore(sourceAnchors, i1);
         const docTop = document.getElementById(`commentray-block-${link.id}`);
         if (!codeTop || !codeBot || !docTop)
             continue;
-        const docEndYViewport = commentaryBandEndYViewport(docScrollEl, next, docTop);
+        const docEndYViewport = commentaryBandEndYViewport(docScrollEl, next, docTop, clipGutterRaysThroughPageBreakGaps);
         const yCodeTop = codeLineHighlightCenterYViewport(codeTop);
         const yCodeBot = codeLineHighlightCenterYViewport(codeBot);
         const yDocTop = docTop.getBoundingClientRect().top + 2;
@@ -1009,13 +1177,14 @@ function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSource
 }
 /**
  * Splines in the gutter between each block’s source range and its commentary band (dual pane,
- * index-backed blocks). Emphasizes the block aligned with the current source viewport; clamps
- * off-screen endpoints so readers see which way to scroll.
+ * index-backed blocks). Emphasizes the block aligned with the **doc** viewport when block anchors
+ * exist; otherwise the source viewport. Clamps off-screen endpoints so readers see which way to scroll.
  *
  * @returns Request a redraw after DOM changes that do not resize the panes (e.g. multi-angle body swap).
  */
 function wireBlockRayConnectors(args) {
     const { gutter, codePane, docScrollEl, getLinks, probeTopSourceLine1Based } = args;
+    const sourceLineIdPrefix = args.sourceLineIdPrefix ?? (() => "code-line-");
     const svgNs = "http://www.w3.org/2000/svg";
     const host = document.createElement("div");
     host.className = "gutter__rays";
@@ -1029,7 +1198,7 @@ function wireBlockRayConnectors(args) {
             return;
         raf = globalThis.requestAnimationFrame(() => {
             raf = 0;
-            drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based);
+            drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based, sourceLineIdPrefix());
         });
     }
     subscribeBlockRayRedraw(gutter, codePane, docScrollEl, scheduleDraw);
@@ -1183,6 +1352,40 @@ function treeFileLinkTitle(pr) {
     }
     return pr.sourcePath;
 }
+function clearDocumentedTreePairHighlights(tree) {
+    for (const el of tree.querySelectorAll("a.tree-file-link")) {
+        if (!(el instanceof HTMLAnchorElement))
+            continue;
+        el.classList.remove("tree-file-link--current");
+        el.removeAttribute("aria-current");
+    }
+}
+function markFirstDocumentedTreeLinkMatchingPair(tree, curSrc, curCr) {
+    for (const el of tree.querySelectorAll("a.tree-file-link")) {
+        if (!(el instanceof HTMLAnchorElement))
+            continue;
+        const sp = el.getAttribute("data-pair-source-path")?.trim() ?? "";
+        const cp = el.getAttribute("data-pair-commentray-path")?.trim() ?? "";
+        if (!isSameDocumentedPair({ sourcePath: sp, commentrayPath: cp }, curSrc, curCr))
+            continue;
+        el.classList.add("tree-file-link--current");
+        el.setAttribute("aria-current", "page");
+        break;
+    }
+}
+/** Marks the tree link for the pair shown in `#shell` (pair paths from server or multi-angle swap). */
+function applyDocumentedTreeCurrentPairHighlight() {
+    const shell = document.getElementById("shell");
+    const tree = document.getElementById("documented-files-tree");
+    if (!(shell instanceof HTMLElement) || !(tree instanceof HTMLElement))
+        return;
+    clearDocumentedTreePairHighlights(tree);
+    const curSrc = shell.getAttribute("data-commentray-pair-source-path")?.trim() ?? "";
+    const curCr = shell.getAttribute("data-commentray-pair-commentray-path")?.trim() ?? "";
+    if (curSrc.length === 0 || curCr.length === 0)
+        return;
+    markFirstDocumentedTreeLinkMatchingPair(tree, curSrc, curCr);
+}
 function renderDocumentedTreeHtml(node) {
     const keys = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
     if (keys.length === 0)
@@ -1202,10 +1405,12 @@ function renderDocumentedTreeHtml(node) {
                 const label = escapeHtmlText(treeFileLinkLabel(pr, multi));
                 const title = escapeHtmlText(treeFileLinkTitle(pr));
                 const href = escapeHtmlText(treeFileLinkHref(pr));
+                const spAttr = escapeHtmlText(normPosixPath(pr.sourcePath));
+                const crAttr = escapeHtmlText(normPosixPath(pr.commentrayPath));
                 const useSiteBrowse = (pr.staticBrowseUrl?.trim() ?? "").length > 0;
                 const external = useSiteBrowse ? "" : ' target="_blank" rel="noopener noreferrer"';
                 lis.push(`<li><div class="tree-file">` +
-                    `<a class="tree-file-link" href="${href}"${external} title="${title}">${label}</a>` +
+                    `<a class="tree-file-link" href="${href}" data-pair-source-path="${spAttr}" data-pair-commentray-path="${crAttr}"${external} title="${title}">${label}</a>` +
                     `</div></li>`);
             }
         }
@@ -1223,6 +1428,7 @@ function renderDocumentedPairsIntoHost(treeHost, pairs, emptyBecauseFilter) {
     for (const p of pairs)
         insertSourcePathTrie(root, p);
     treeHost.innerHTML = renderDocumentedTreeHtml(root);
+    applyDocumentedTreeCurrentPairHighlight();
 }
 function loadDocumentedPairs(jsonUrl, embeddedB64) {
     let loaded = null;
@@ -1298,6 +1504,12 @@ function wireDocumentedFilesTreeMobileFlyout(hub) {
     globalThis.addEventListener("scroll", placeFlyout, true);
     return placeFlyout;
 }
+function focusDocumentedFilesFilterInput() {
+    const el = document.getElementById("documented-files-filter");
+    if (!(el instanceof HTMLInputElement))
+        return;
+    el.focus({ preventScroll: true });
+}
 function wireDocumentedFilesTree() {
     const hub = document.getElementById("documented-files-hub");
     const treeHost = document.getElementById("documented-files-tree");
@@ -1306,12 +1518,13 @@ function wireDocumentedFilesTree() {
     if (!(hub instanceof HTMLDetailsElement) || !(treeHost instanceof HTMLElement)) {
         return;
     }
+    const detailsHub = hub;
     const treeMount = treeHost;
-    const jsonUrl = hub.getAttribute("data-nav-json-url")?.trim() ?? "";
+    const jsonUrl = detailsHub.getAttribute("data-nav-json-url")?.trim() ?? "";
     const embeddedB64 = shell?.getAttribute("data-documented-pairs-b64")?.trim() ?? "";
     if (jsonUrl.length === 0 && embeddedB64.length === 0)
         return;
-    const placeDocHubFlyout = wireDocumentedFilesTreeMobileFlyout(hub);
+    const placeDocHubFlyout = wireDocumentedFilesTreeMobileFlyout(detailsHub);
     const ensureLoaded = loadDocumentedPairs(jsonUrl, embeddedB64);
     let cachedPairs = null;
     function applyFilterAndRender() {
@@ -1334,18 +1547,31 @@ function wireDocumentedFilesTree() {
                 '<p class="nav-rail__doc-hub-hint" role="alert">Could not load the file list.</p>';
         }
     }
-    hub.addEventListener("toggle", () => {
+    detailsHub.addEventListener("toggle", () => {
         placeDocHubFlyout();
-        if (hub.open) {
-            globalThis.requestAnimationFrame(placeDocHubFlyout);
+        if (detailsHub.open) {
+            globalThis.requestAnimationFrame(() => {
+                placeDocHubFlyout();
+                focusDocumentedFilesFilterInput();
+            });
         }
-        if (!hub.open)
+        if (!detailsHub.open)
             return;
         void hydrateTree();
     });
+    function onDocumentedFilesHubEscape(ev) {
+        if (!detailsHub.open || ev.key !== "Escape")
+            return;
+        ev.preventDefault();
+        detailsHub.open = false;
+        const sum = detailsHub.querySelector("summary");
+        if (sum instanceof HTMLElement)
+            sum.focus({ preventScroll: true });
+    }
+    document.addEventListener("keydown", onDocumentedFilesHubEscape, true);
     if (filterInput instanceof HTMLInputElement) {
         filterInput.addEventListener("input", () => {
-            if (!hub.open || cachedPairs === null)
+            if (!detailsHub.open || cachedPairs === null)
                 return;
             applyFilterAndRender();
         });
@@ -1384,11 +1610,61 @@ function wireSplitter(storageSplit, shell, codePane, gutter, initialPct) {
 const STORAGE_SPLIT_PCT = "commentray.codeCommentrayStatic.splitPct";
 const STORAGE_WRAP_LINES = "commentray.codeCommentrayStatic.wrap";
 const STORAGE_DUAL_MOBILE_PANE = "commentray.codeCommentrayStatic.dualMobilePane";
+const STORAGE_SOURCE_MARKDOWN_PANE_MODE = "commentray.codeCommentrayStatic.sourceMarkdownPaneMode";
+const STORAGE_PAGE_BREAKS_ENABLED = "commentray.codeCommentrayStatic.pageBreaksEnabled";
 /** Matches `code-browser.ts` `@media (max-width: 767px)` (dual column from 768px up). */
 const DUAL_MOBILE_SINGLE_PANE_MQ = "(max-width: 767px)";
 function normalizedDualMobilePane(v) {
     return v === "code" ? "code" : "doc";
 }
+function isNarrowViewport() {
+    return globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ).matches;
+}
+function wireWideModeIntroTrigger(shell) {
+    const btn = document.getElementById("commentray-help-tour");
+    if (!(btn instanceof HTMLButtonElement))
+        return;
+    btn.addEventListener("click", () => {
+        wireWideModeIntroTour(shell, isNarrowViewport, { force: true });
+    });
+}
+function sourcePaneModeForShell(shell) {
+    return shell.getAttribute("data-source-pane-mode") === "rendered-markdown"
+        ? "rendered-markdown"
+        : "source";
+}
+function pageBreaksEnabledFromStorage(raw) {
+    const t = (raw ?? "").trim().toLowerCase();
+    if (t === "0" || t === "false" || t === "off")
+        return false;
+    return true;
+}
+function applyPageBreakFeatureToggle(shell) {
+    const enabled = pageBreaksEnabledFromStorage(readWebStorageItem(localStorage, STORAGE_PAGE_BREAKS_ENABLED));
+    shell.setAttribute("data-page-breaks-enabled", enabled ? "true" : "false");
+}
+function wireResponsivePageBreakHeight(shell) {
+    const setHeight = () => {
+        const viewportHeight = Math.max(globalThis.innerHeight, document.documentElement?.clientHeight ?? 0);
+        if (!Number.isFinite(viewportHeight) || viewportHeight <= 0)
+            return;
+        const minHeightPx = Math.round(clamp(viewportHeight * 0.72, 260, 820));
+        shell.style.setProperty("--commentray-page-break-min-height", `${String(minHeightPx)}px`);
+    };
+    globalThis.addEventListener("resize", setHeight, { passive: true });
+    globalThis.addEventListener("orientationchange", setHeight, { passive: true });
+    globalThis.visualViewport?.addEventListener("resize", setHeight, { passive: true });
+    setHeight();
+}
+function syncWrapLinesVisibilityForSourcePaneMode(shell) {
+    const wrapToggle = document.querySelector("label.toolbar-wrap-lines");
+    if (!(wrapToggle instanceof HTMLLabelElement))
+        return;
+    wrapToggle.hidden = sourcePaneModeForShell(shell) === "rendered-markdown";
+}
+function sourceLineIdPrefixForShell(shell) {
+    return sourcePaneModeForShell(shell) === "rendered-markdown" ? "code-md-line-" : "code-line-";
+}
 /** When the commentary pane is visible, (re)run Mermaid so diagrams are not laid out under display:none. */
 function scheduleMermaidWhenDualDocPaneVisible(shell, mq) {
     const kick = () => {
@@ -1440,6 +1716,105 @@ function wireDualMobilePaneFlipScrollAffordance(primaryFlip, scrollFlip, mq) {
     mq.addEventListener("change", tick);
     globalThis.requestAnimationFrame(tick);
 }
+function wireSourceMarkdownPaneFlipAffordance(primaryFlip, scrollFlip) {
+    const hideScroll = () => {
+        scrollFlip.hidden = true;
+        scrollFlip.classList.remove("is-visible");
+    };
+    const showScroll = () => {
+        scrollFlip.hidden = false;
+        scrollFlip.classList.add("is-visible");
+    };
+    const tick = () => {
+        const r = primaryFlip.getBoundingClientRect();
+        const vh = globalThis.innerHeight;
+        const margin = 10;
+        const offScreen = r.bottom < margin || r.top > vh - margin;
+        if (offScreen)
+            showScroll();
+        else
+            hideScroll();
+    };
+    globalThis.addEventListener("scroll", tick, { passive: true });
+    globalThis.addEventListener("resize", tick, { passive: true });
+    globalThis.requestAnimationFrame(tick);
+}
+function closestSourceLine0ForPaneTop(codePane, idPrefix) {
+    const rows = codePane.querySelectorAll(`[id^="${idPrefix}"]`);
+    if (rows.length === 0)
+        return null;
+    const y = paneUsesInternalYScroll(codePane)
+        ? codePane.getBoundingClientRect().top + codePane.clientTop + 2
+        : Math.max(0, codePane.getBoundingClientRect().top) + 2;
+    for (const el of rows) {
+        const r = el.getBoundingClientRect();
+        if (r.bottom > y - 1e-3) {
+            const m = /^(?:code-line-|code-md-line-)(\d+)$/.exec(el.id);
+            if (!m?.[1])
+                return null;
+            return Number.parseInt(m[1], 10);
+        }
+    }
+    const last = rows[rows.length - 1];
+    if (!last)
+        return null;
+    const m = /^(?:code-line-|code-md-line-)(\d+)$/.exec(last.id);
+    if (!m?.[1])
+        return null;
+    return Number.parseInt(m[1], 10);
+}
+function wireSourceMarkdownPaneFlip(shell, codePane, flipBtn, flipScrollBtn, onAfterFlip) {
+    function syncSourceMarkdownFlipA11y() {
+        const mode = sourcePaneModeForShell(shell);
+        const renderedActive = mode === "rendered-markdown";
+        const nextModeLabel = renderedActive ? "markdown source" : "rendered markdown";
+        const ariaLabel = `Switch source pane to ${nextModeLabel}`;
+        const title = `Source pane: ${renderedActive ? "rendered markdown" : "markdown source"} (click to switch)`;
+        const apply = (btn) => {
+            if (!(btn instanceof HTMLButtonElement))
+                return;
+            btn.setAttribute("aria-pressed", renderedActive ? "true" : "false");
+            btn.setAttribute("aria-label", ariaLabel);
+            btn.title = title;
+        };
+        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);
+    const runFlip = () => {
+        const cur = sourcePaneModeForShell(shell);
+        const currentPrefix = cur === "rendered-markdown" ? "code-md-line-" : "code-line-";
+        const line0 = closestSourceLine0ForPaneTop(codePane, currentPrefix);
+        const next = cur === "rendered-markdown" ? "source" : "rendered-markdown";
+        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);
+        syncSourceMarkdownFlipA11y();
+        syncWrapLinesVisibilityForSourcePaneMode(shell);
+        if (line0 !== null) {
+            const row = codePane.querySelector(`#${nextPrefix}${String(line0)}`);
+            if (row instanceof HTMLElement) {
+                applyRevealChildInPane(codePane, row, 2);
+            }
+        }
+        if (next === "rendered-markdown") {
+            const sourceMdBody = document.getElementById("code-pane-markdown-body");
+            if (sourceMdBody instanceof HTMLElement) {
+                runMermaidOnFreshDocNodes(sourceMdBody);
+                rewriteHubRelativeBrowseAnchorsIn(sourceMdBody);
+            }
+        }
+        onAfterFlip?.();
+    };
+    flipBtn.addEventListener("click", runFlip);
+    if (flipScrollBtn) {
+        flipScrollBtn.addEventListener("click", runFlip);
+        wireSourceMarkdownPaneFlipAffordance(flipBtn, flipScrollBtn);
+    }
+}
 function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
     const mq = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ);
     function readStoredPane() {
@@ -1458,6 +1833,7 @@ function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
             return;
         const cur = normalizedDualMobilePane(shell.getAttribute("data-dual-mobile-pane"));
         const next = cur === "code" ? "doc" : "code";
+        const rootTopBeforeFlip = rootScrollingElement().scrollTop;
         if (next === "code") {
             scrollRunners.prepareMobileFlipToCode();
         }
@@ -1470,6 +1846,11 @@ function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
             globalThis.requestAnimationFrame(() => {
                 if (next === "code") {
                     scrollRunners.finishMobileFlipToCode();
+                    const root = rootScrollingElement();
+                    if (rootTopBeforeFlip > 5 && root.scrollTop <= 1) {
+                        const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+                        root.scrollTop = clamp(rootTopBeforeFlip, 0, maxY);
+                    }
                 }
                 else {
                     scrollRunners.finishMobileFlipToDoc();
@@ -1630,75 +2011,108 @@ 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);
+    rewriteHubRelativeBrowseAnchorsIn(docBody);
+    mutable.rawMd = decodeBase64Utf8(angle.rawMdB64);
+    mutable.mdLines = mutable.rawMd.split("\n");
+    mutable.commentrayPathLabel = angle.commentrayPathForSearch;
+    rebuildSearcher();
+    scrollLinksRef.current = parseScrollBlockLinksFromShell(angle.scrollBlockLinksB64);
+    shell.setAttribute("data-scroll-block-links-b64", angle.scrollBlockLinksB64);
+    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");
+    applyDocumentedTreeCurrentPairHighlight();
+    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");
+    }
+    searchInput.value = "";
+    searchResults.innerHTML = "";
+    searchResults.hidden = true;
+    requestBlockRayRedraw?.();
+    globalThis.requestAnimationFrame(() => {
+        requestBlockRayRedraw?.();
+        globalThis.requestAnimationFrame(() => {
+            requestBlockRayRedraw?.();
+        });
+    });
+}
 function wireDualPaneMultiAngleAndScroll(args) {
     const { codePane, docScrollEl, docBody, shell, scrollLinksRef, multiPayload, mutable, rebuildSearcher, searchInput, searchResults, requestBlockRayRedraw, } = args;
     if (multiPayload) {
-        const runners = wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
+        const runners = wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current, () => sourceLineIdPrefixForShell(shell), () => sourcePaneModeForShell(shell) === "rendered-markdown");
         const angleSel = document.getElementById("angle-select");
         if (angleSel && docBody) {
             angleSel.addEventListener("change", () => {
                 const a = multiPayload.angles.find((x) => x.id === angleSel.value);
                 if (!a)
                     return;
-                docBody.innerHTML = decodeBase64Utf8(a.docInnerHtmlB64);
-                runMermaidOnFreshDocNodes(docBody);
-                rewriteHubRelativeBrowseAnchorsIn(docBody);
-                mutable.rawMd = decodeBase64Utf8(a.rawMdB64);
-                mutable.mdLines = mutable.rawMd.split("\n");
-                mutable.commentrayPathLabel = a.commentrayPathForSearch;
-                rebuildSearcher();
-                scrollLinksRef.current = parseScrollBlockLinksFromShell(a.scrollBlockLinksB64);
-                shell.setAttribute("data-scroll-block-links-b64", a.scrollBlockLinksB64);
-                shell.setAttribute("data-search-commentray-path", a.commentrayPathForSearch);
-                const docPathEl = document.getElementById("nav-rail-doc-path");
-                if (docPathEl) {
-                    const path = a.commentrayPathForSearch.trim();
-                    docPathEl.textContent = path.length > 0 ? path : "—";
-                    if (path.length > 0)
-                        docPathEl.setAttribute("title", path);
-                    else
-                        docPathEl.removeAttribute("title");
-                }
-                const browse = a.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 = a.commentrayOnGithubUrl?.trim();
-                    if (ghu) {
-                        shell.setAttribute("data-commentray-pair-browse-href", ghu);
-                    }
-                    else {
-                        shell.removeAttribute("data-commentray-pair-browse-href");
-                    }
-                }
-                searchInput.value = "";
-                searchResults.innerHTML = "";
-                searchResults.hidden = true;
-                requestBlockRayRedraw?.();
-                globalThis.requestAnimationFrame(() => {
-                    requestBlockRayRedraw?.();
-                    globalThis.requestAnimationFrame(() => {
-                        requestBlockRayRedraw?.();
-                    });
+                applySelectedMultiAngle({
+                    angle: a,
+                    docBody,
+                    mutable,
+                    rebuildSearcher,
+                    scrollLinksRef,
+                    shell,
+                    searchInput,
+                    searchResults,
+                    requestBlockRayRedraw,
                 });
             });
         }
         return runners;
     }
     if (scrollLinksRef.current.length > 0) {
-        return wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
+        return wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current, () => sourceLineIdPrefixForShell(shell), () => sourcePaneModeForShell(shell) === "rendered-markdown");
     }
     return wireProportionalScrollSync(codePane, docScrollEl);
 }
 function wireDualPaneCommentrayLocationHash(docScrollEl, mdLineCount) {
+    function commentrayMdLineFromLocationHash(rawHash) {
+        const hash = rawHash.replace(/^#/, "").trim();
+        if (hash.length === 0)
+            return null;
+        const tokens = hash
+            .split(/--|&/)
+            .map((t) => t.trim())
+            .filter((t) => t.length > 0);
+        for (const token of tokens) {
+            const m = /^commentray-md-line-(\d+)$/.exec(token);
+            if (!m?.[1])
+                continue;
+            const line0 = Number.parseInt(m[1], 10);
+            if (Number.isFinite(line0))
+                return line0;
+        }
+        return null;
+    }
     function applyCommentrayLocationHash() {
-        const m = /^commentray-md-line-(\d+)$/.exec(globalThis.location.hash.slice(1));
-        if (!m?.[1])
-            return;
-        const line0 = Number.parseInt(m[1], 10);
-        if (!Number.isFinite(line0))
+        const line0 = commentrayMdLineFromLocationHash(globalThis.location.hash);
+        if (line0 === null)
             return;
         scrollDocToMarkdownLine0(docScrollEl, line0, mdLineCount());
     }
@@ -1707,6 +2121,23 @@ function wireDualPaneCommentrayLocationHash(docScrollEl, mdLineCount) {
         globalThis.requestAnimationFrame(applyCommentrayLocationHash);
     });
 }
+function initializeSourceMarkdownPane(shell) {
+    if (sourcePaneModeForShell(shell) !== "rendered-markdown")
+        return;
+    const sourceMdBody = document.getElementById("code-pane-markdown-body");
+    if (!(sourceMdBody instanceof HTMLElement))
+        return;
+    runMermaidOnFreshDocNodes(sourceMdBody);
+    rewriteHubRelativeBrowseAnchorsIn(sourceMdBody);
+}
+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);
+    initializeSourceMarkdownPane(shell);
+}
 function buildDualPaneSearcherBundle(shell, codePane) {
     const { rawCodeB64, rawMdB64 } = readEmbeddedRawB64Strings(shell, codePane);
     const rawCode = decodeBase64Utf8(rawCodeB64);
@@ -1778,12 +2209,11 @@ function wireDualPaneCodeBrowser(shell, codePane) {
     shell.style.setProperty("--split-pct", `${String(pct)}%`);
     const docPaneEl = document.getElementById("doc-pane");
     const docPaneForWrap = docPaneEl instanceof HTMLElement ? docPaneEl : null;
+    const sourceMdBodyForWrap = document.getElementById("code-pane-markdown-body");
     const blockRayRedraw = {};
     wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb, () => {
         blockRayRedraw.request?.();
-        codePane.dispatchEvent(new Event("scroll"));
-        docScrollEl.dispatchEvent(new Event("scroll"));
-    }, docPaneForWrap, docBody);
+    }, docPaneForWrap, docBody, sourceMdBodyForWrap instanceof HTMLElement ? sourceMdBodyForWrap : null);
     wireSplitter(STORAGE_SPLIT_PCT, shell, codePane, gutter, pct);
     const multiScript = document.getElementById("commentray-multi-angle-b64");
     const multiPayload = parseMultiAnglePayload(multiScript);
@@ -1794,7 +2224,8 @@ function wireDualPaneCodeBrowser(shell, codePane) {
             codePane,
             docScrollEl,
             getLinks: () => bundle.scrollLinksRef.current,
-            probeTopSourceLine1Based: () => probeCodeLine1FromViewport(codePane),
+            probeTopSourceLine1Based: () => probeCodeLine1FromViewport(codePane, sourceLineIdPrefixForShell(shell)),
+            sourceLineIdPrefix: () => sourceLineIdPrefixForShell(shell),
         })
         : undefined;
     blockRayRedraw.request = requestBlockRayRedraw;
@@ -1816,6 +2247,10 @@ function wireDualPaneCodeBrowser(shell, codePane) {
     if (flipBtn instanceof HTMLButtonElement) {
         wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn instanceof HTMLButtonElement ? flipScrollBtn : null);
     }
+    wireSourceMarkdownControls(shell, codePane, () => {
+        requestBlockRayRedraw?.();
+    });
+    wireWideModeIntroTour(shell, isNarrowViewport);
     wireDualPaneCommentrayLocationHash(docScrollEl, () => bundle.mutable.mdLines.length);
 }
 function commentrayThemeModeLabel(mode) {
@@ -1917,7 +2352,218 @@ function wireColorThemeToolbar() {
     document.addEventListener("keydown", onDocumentKeydown, true);
     syncUi();
 }
+function safePermalinkHref(raw) {
+    const t = raw.trim();
+    if (t.length === 0)
+        return null;
+    if (/^(javascript|data):/i.test(t))
+        return null;
+    try {
+        return new URL(t, globalThis.location.href).toString();
+    }
+    catch {
+        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) {
+        shell.setAttribute("data-nav-search-json-url", makeAbsoluteUrlAgainst(navSearchRaw, beforeHref));
+    }
+    const navTree = document.getElementById("documented-files-hub");
+    if (navTree instanceof HTMLElement) {
+        const navRaw = navTree.getAttribute("data-nav-json-url")?.trim() ?? "";
+        if (navRaw.length > 0) {
+            navTree.setAttribute("data-nav-json-url", makeAbsoluteUrlAgainst(navRaw, beforeHref));
+        }
+    }
+}
+function normalizePairBrowseHrefForCurrentPath(shell, pathname) {
+    const pairBrowseRaw = shell.getAttribute("data-commentray-pair-browse-href")?.trim() ?? "";
+    if (pairBrowseRaw.length > 0 && isHubRelativeStaticBrowseHref(pairBrowseRaw)) {
+        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))
+        return null;
+    const docBody = document.getElementById("doc-pane-body");
+    const docScrollEl = docBody instanceof HTMLElement ? docBody : docPane;
+    const anchors = docScrollEl.querySelectorAll(".commentray-block-anchor");
+    if (anchors.length === 0)
+        return null;
+    const mdLine0 = probeCommentrayLine0FromDoc(docScrollEl);
+    if (!Number.isFinite(mdLine0) || mdLine0 < 0)
+        return null;
+    return `commentray-md-line-${String(mdLine0)}`;
+}
+function maybeBackfillAddressBarWithHumanePairLink() {
+    const shell = document.getElementById("shell");
+    if (!(shell instanceof HTMLElement))
+        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}`);
+}
+function permalinkHashSuffixFromUi() {
+    const tokens = [];
+    const pushUnique = (token) => {
+        const t = token.trim();
+        if (t.length === 0)
+            return;
+        if (!tokens.includes(t))
+            tokens.push(t);
+    };
+    const angleSel = document.getElementById("angle-select");
+    if (angleSel instanceof HTMLSelectElement) {
+        const id = angleSel.value.trim();
+        if (id.length > 0) {
+            pushUnique(`angle-${encodeURIComponent(id)}`);
+        }
+    }
+    const activeAnchor = activeCommentrayHashTokenFromViewport();
+    if (activeAnchor)
+        pushUnique(activeAnchor);
+    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 hash = permalinkHashSuffixFromUi();
+    u.hash = hash.length > 0 ? hash.slice(1) : "";
+    return u.toString();
+}
+async function writeTextToClipboard(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+        return true;
+    }
+    catch {
+        const ta = document.createElement("textarea");
+        ta.value = text;
+        ta.setAttribute("readonly", "true");
+        ta.style.position = "fixed";
+        ta.style.top = "-1000px";
+        ta.style.left = "-1000px";
+        document.body.appendChild(ta);
+        ta.select();
+        try {
+            return document.execCommand("copy");
+        }
+        catch {
+            return false;
+        }
+        finally {
+            document.body.removeChild(ta);
+        }
+    }
+}
+function wireSharePermalinkButton() {
+    const shell = document.getElementById("shell");
+    const btn = document.getElementById("commentray-share-link");
+    if (!(shell instanceof HTMLElement) || !(btn instanceof HTMLButtonElement))
+        return;
+    const baseLabel = "Copy shareable permalink";
+    let copiedTimer;
+    btn.addEventListener("click", () => {
+        void (async () => {
+            const shareUrl = sharePermalinkFromShell(shell);
+            const copied = await writeTextToClipboard(shareUrl);
+            if (!copied)
+                return;
+            btn.dataset.copied = "true";
+            btn.setAttribute("aria-label", "Permalink copied");
+            btn.title = "Permalink copied";
+            if (copiedTimer !== undefined)
+                globalThis.clearTimeout(copiedTimer);
+            copiedTimer = globalThis.setTimeout(() => {
+                delete btn.dataset.copied;
+                btn.setAttribute("aria-label", baseLabel);
+                btn.title = baseLabel;
+            }, 1200);
+        })();
+    });
+}
 function main() {
+    wireSharePermalinkButton();
     wireColorThemeToolbar();
     wireDocumentedFilesTree();
     const shell = document.getElementById("shell");
@@ -1925,12 +2571,16 @@ function main() {
     if (!shell || !codePane) {
         return;
     }
+    applyPageBreakFeatureToggle(shell);
+    wireResponsivePageBreakHeight(shell);
+    wireWideModeIntroTrigger(shell);
     const layout = shell.getAttribute("data-layout") || "dual";
     if (layout === "stretch") {
         wireStretchLayoutChrome(codePane);
         return;
     }
     wireDualPaneCodeBrowser(shell, codePane);
+    maybeBackfillAddressBarWithHumanePairLink();
 }
 if (document.readyState === "loading") {
     document.addEventListener("DOMContentLoaded", main);