@commentray/render 0.0.6 → 0.0.8

package/dist/code-browser-client.js

@@ -4,24 +4,221 @@ import { mirroredScrollTop, pickCommentrayLineForSourceScroll, pickSourceLine0Fo
 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, isSameDocumentedPair, normPosixPath, resolveStaticBrowseHref, } 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 { readWebStorageItem, writeWebStorageItem } from "./code-browser-web-storage.js";
+/**
+ * Hub pages emit `./browse/…` relative to the site root. From `/…/browse/current.html` the browser
+ * would otherwise resolve that to `…/browse/browse/…`.
+ */
+function rewriteHubRelativeBrowseAnchorsIn(root) {
+    const path = globalThis.location.pathname;
+    const origin = globalThis.location.origin;
+    for (const el of Array.from(root.querySelectorAll("a[href]"))) {
+        if (!(el instanceof HTMLAnchorElement))
+            continue;
+        const raw = el.getAttribute("href")?.trim() ?? "";
+        if (!isHubRelativeStaticBrowseHref(raw))
+            continue;
+        el.href = resolveStaticBrowseHref(raw, path, origin);
+    }
+}
 function runMermaidOnFreshDocNodes(docBody) {
     if (typeof globalThis.location !== "undefined" && globalThis.location.protocol === "file:")
         return;
-    const nodes = docBody.querySelectorAll(".mermaid");
+    /** 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). */
+    const nodes = allPres.filter((pre) => {
+        const wrap = pre.closest(".commentray-mermaid");
+        return wrap === null || wrap.querySelector("svg") === null;
+    });
     if (nodes.length === 0)
         return;
     const m = globalThis
         .commentrayMermaid;
     if (!m)
         return;
-    const list = Array.from(nodes);
-    void m.run({ nodes: list }).catch(() => { });
+    void m.run({ nodes }).catch((err) => {
+        console.error("Commentray: mermaid.run failed", err);
+    });
 }
 function clamp(n, lo, hi) {
     return Math.max(lo, Math.min(hi, n));
 }
+/** Y offset in `scrollEl`’s scroll coordinate space to place `child`’s top at the scrollport (CSS px). */
+function scrollTopToAlignChildTop(scrollEl, child, leadCssPx) {
+    const cr = child.getBoundingClientRect();
+    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). */
+function applyScrollTopClamped(scrollEl, nextTop) {
+    const maxY = Math.max(0, scrollEl.scrollHeight - scrollEl.clientHeight);
+    const clamped = clamp(nextTop, 0, maxY);
+    if (Math.abs(scrollEl.scrollTop - clamped) < 0.25)
+        return;
+    scrollEl.scrollTop = clamped;
+}
+function paneUsesInternalYScroll(el) {
+    const max = el.scrollHeight - el.clientHeight;
+    if (max <= 1)
+        return false;
+    const oy = getComputedStyle(el).overflowY;
+    return oy === "auto" || oy === "scroll" || oy === "overlay";
+}
+function rootScrollingElement() {
+    const s = document.scrollingElement;
+    if (s instanceof HTMLElement)
+        return s;
+    return document.documentElement;
+}
+function applyWindowScrollRatio(ratio) {
+    const root = rootScrollingElement();
+    const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+    const next = clamp(ratio * maxY, 0, maxY);
+    if (Math.abs(root.scrollTop - next) < 0.25)
+        return;
+    root.scrollTop = next;
+}
+/**
+ * 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).
+ */
+function applyRevealChildInPane(scrollport, child, leadCssPx) {
+    if (paneUsesInternalYScroll(scrollport)) {
+        applyScrollTopClamped(scrollport, Math.round(scrollTopToAlignChildTop(scrollport, child, leadCssPx)));
+        return;
+    }
+    const root = rootScrollingElement();
+    const cr = child.getBoundingClientRect();
+    const targetTop = globalThis.scrollY + cr.top - leadCssPx;
+    const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+    const clamped = clamp(targetTop, 0, maxY);
+    if (Math.abs(root.scrollTop - clamped) < 0.25)
+        return;
+    root.scrollTop = clamped;
+}
+function windowScrollRatio() {
+    const root = rootScrollingElement();
+    const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+    return maxY > 0 ? clamp(root.scrollTop / maxY, 0, 1) : 0;
+}
+function applyDocToCodeFlipPlanImpl(codePane, _docPane, plan) {
+    if (plan.k === "block") {
+        const el = codePane.querySelector(`#code-line-${String(plan.src0)}`);
+        if (el) {
+            applyRevealChildInPane(codePane, el, 2);
+        }
+        else {
+            applyWindowScrollRatio(plan.winRatio);
+        }
+        return;
+    }
+    if (plan.k === "mirrorW") {
+        if (paneUsesInternalYScroll(codePane)) {
+            const maxC = Math.max(0, codePane.scrollHeight - codePane.clientHeight);
+            applyScrollTopClamped(codePane, plan.ratio * maxC);
+        }
+        else {
+            applyWindowScrollRatio(plan.ratio);
+        }
+        return;
+    }
+    const nextTop = mirroredScrollTop(plan.docTop, plan.docSH, plan.docCH, codePane.scrollHeight, codePane.clientHeight);
+    if (paneUsesInternalYScroll(codePane)) {
+        applyScrollTopClamped(codePane, nextTop);
+        return;
+    }
+    const denom = Math.max(1, codePane.scrollHeight - codePane.clientHeight);
+    applyWindowScrollRatio(clamp(nextTop / denom, 0, 1));
+}
+function applyCodeToDocFlipPlanImpl(_codePane, docPane, plan) {
+    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);
+        }
+        return;
+    }
+    if (plan.k === "mirrorW") {
+        if (paneUsesInternalYScroll(docPane)) {
+            const maxD = Math.max(0, docPane.scrollHeight - docPane.clientHeight);
+            applyScrollTopClamped(docPane, plan.ratio * maxD);
+        }
+        else {
+            applyWindowScrollRatio(plan.ratio);
+        }
+        return;
+    }
+    const nextTop = mirroredScrollTop(plan.codeTop, plan.codeSH, plan.codeCH, docPane.scrollHeight, docPane.clientHeight);
+    if (paneUsesInternalYScroll(docPane)) {
+        applyScrollTopClamped(docPane, nextTop);
+        return;
+    }
+    const denom = Math.max(1, docPane.scrollHeight - docPane.clientHeight);
+    applyWindowScrollRatio(clamp(nextTop / denom, 0, 1));
+}
+function buildDocToCodeFlipPlanBlockAware(docPane, getLinks) {
+    const winRatio = windowScrollRatio();
+    const links = getLinks();
+    const mdLine0 = probeCommentrayLine0FromDoc(docPane);
+    const src0 = pickSourceLine0ForCommentrayScroll(links, mdLine0);
+    if (src0 !== null)
+        return { k: "block", src0, winRatio };
+    if (paneUsesInternalYScroll(docPane)) {
+        return {
+            k: "mirrorI",
+            docTop: docPane.scrollTop,
+            docSH: docPane.scrollHeight,
+            docCH: docPane.clientHeight,
+        };
+    }
+    return { k: "mirrorW", ratio: winRatio };
+}
+function buildCodeToDocFlipPlanBlockAware(codePane, _docPane, getLinks) {
+    const winRatio = windowScrollRatio();
+    const links = getLinks();
+    const line1 = probeCodeLine1FromViewport(codePane);
+    const mdLine0 = pickCommentrayLineForSourceScroll(links, line1);
+    if (mdLine0 === null) {
+        if (paneUsesInternalYScroll(codePane)) {
+            return {
+                k: "mirrorI",
+                codeTop: codePane.scrollTop,
+                codeSH: codePane.scrollHeight,
+                codeCH: codePane.clientHeight,
+            };
+        }
+        return { k: "mirrorW", ratio: winRatio };
+    }
+    return { k: "block", mdLine0, winRatio };
+}
+function buildDocToCodeFlipPlanProportional(docPane) {
+    if (paneUsesInternalYScroll(docPane)) {
+        return {
+            k: "mirrorI",
+            docTop: docPane.scrollTop,
+            docSH: docPane.scrollHeight,
+            docCH: docPane.clientHeight,
+        };
+    }
+    return { k: "mirrorW", ratio: windowScrollRatio() };
+}
+function buildCodeToDocFlipPlanProportional(codePane) {
+    if (paneUsesInternalYScroll(codePane)) {
+        return {
+            k: "mirrorI",
+            codeTop: codePane.scrollTop,
+            codeSH: codePane.scrollHeight,
+            codeCH: codePane.clientHeight,
+        };
+    }
+    return { k: "mirrorW", ratio: windowScrollRatio() };
+}
 function escapeHtmlText(s) {
     return s
         .replace(/&/g, "&amp;")
@@ -198,17 +395,16 @@ 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 = el.getBoundingClientRect().top -
-            docScrollEl.getBoundingClientRect().top +
-            docScrollEl.scrollTop;
-        docScrollEl.scrollTo({ top: Math.max(0, top - 8), behavior: "smooth" });
+        const top = Math.round(scrollTopToAlignChildTop(docScrollEl, el, 8));
+        const maxY = Math.round(Math.max(0, docScrollEl.scrollHeight - docScrollEl.clientHeight));
+        docScrollEl.scrollTo({ top: clamp(top, 0, maxY), behavior: "smooth" });
         return;
     }
     if (mdLineCount <= 1)
         return;
     const ratio = line0 / Math.max(1, mdLineCount - 1);
-    const maxScroll = docScrollEl.scrollHeight - docScrollEl.clientHeight;
-    docScrollEl.scrollTo({ top: ratio * Math.max(0, maxScroll), behavior: "smooth" });
+    const maxScroll = Math.max(0, docScrollEl.scrollHeight - docScrollEl.clientHeight);
+    docScrollEl.scrollTo({ top: ratio * maxScroll, behavior: "smooth" });
 }
 function navigateToDocumentedPair(pair, mdLine0) {
     if (pair.staticBrowseUrl?.trim()) {
@@ -424,20 +620,51 @@ function wireSearchUi(ctx) {
         e.preventDefault();
     });
 }
-function wireWrapToggle(storageWrap, codePane, wrapCb) {
+/**
+ * After toggling `pre-wrap`, line rows reflow without necessarily resizing the pane’s border box,
+ * so gutter block rays and scroll sync must be nudged explicitly.
+ *
+ * Pass optional `docWrapRoots` (e.g. `#doc-pane` and `#doc-pane-body` in dual layout): the toggle
+ * syncs `wrap` on those nodes so commentary fenced blocks and prose honor the control. `#doc-pane-body`
+ * is targeted in CSS with an id so rules win over `pre code.hljs` from the highlight.js theme.
+ */
+function wireWrapToggle(storageWrap, codePane, wrapCb, onAfterLayout, ...docWrapRoots) {
+    const docTargets = docWrapRoots.filter((el) => el instanceof HTMLElement);
     const wrap = readWebStorageItem(localStorage, storageWrap) === "1";
     wrapCb.checked = wrap;
-    if (wrap)
+    if (wrap) {
         codePane.classList.add("wrap");
+        for (const el of docTargets)
+            el.classList.add("wrap");
+    }
+    else {
+        codePane.classList.remove("wrap");
+        for (const el of docTargets)
+            el.classList.remove("wrap");
+    }
     wrapCb.addEventListener("change", () => {
         if (wrapCb.checked) {
             codePane.classList.add("wrap");
+            for (const el of docTargets)
+                el.classList.add("wrap");
             writeWebStorageItem(localStorage, storageWrap, "1");
         }
         else {
             codePane.classList.remove("wrap");
+            for (const el of docTargets)
+                el.classList.remove("wrap");
             writeWebStorageItem(localStorage, storageWrap, "0");
         }
+        if (!onAfterLayout)
+            return;
+        queueMicrotask(() => {
+            requestAnimationFrame(() => {
+                onAfterLayout();
+                requestAnimationFrame(() => {
+                    onAfterLayout();
+                });
+            });
+        });
     });
 }
 function parseScrollBlockLinksFromShell(b64) {
@@ -471,101 +698,218 @@ function parseScrollBlockLinksFromShell(b64) {
         return [];
     }
 }
+function rootScrollNearDocumentEnd(edgePx = 56) {
+    const root = rootScrollingElement();
+    const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+    return maxY > 0 && root.scrollTop >= maxY - edgePx;
+}
 function probeCodeLine1FromViewport(codePane) {
-    const y = codePane.getBoundingClientRect().top + 2;
     const rows = codePane.querySelectorAll('[id^="code-line-"]');
+    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);
+            if (m)
+                return Number(m[1]) + 1;
+            return rows.length;
+        }
+        const sr = codePane.getBoundingClientRect();
+        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));
+        for (const el of rows) {
+            const r = el.getBoundingClientRect();
+            if (r.bottom > y - 1e-3) {
+                const m = /^code-line-(\d+)$/.exec(el.id);
+                if (m)
+                    return Number(m[1]) + 1;
+                return 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) {
+        if (r.bottom > y - 1e-3) {
             const m = /^code-line-(\d+)$/.exec(el.id);
             if (m)
                 return Number(m[1]) + 1;
             return 1;
         }
     }
-    return rows.length > 0 ? rows.length : 1;
+    return rows.length;
 }
 function probeCommentrayLine0FromDoc(docPane) {
-    const y = docPane.getBoundingClientRect().top + 2;
     const anchors = docPane.querySelectorAll(".commentray-block-anchor");
+    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;
+        }
+        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;
+    }
+    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 === "")
             continue;
-        if (a.getBoundingClientRect().top <= y + 1)
+        if (a.getBoundingClientRect().top <= y + 1 + 1e-3)
             best = Number(lineAttr);
         else
             break;
     }
     return best;
 }
+/**
+ * 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).
+ */
+function armIgnoreNextPaneScrollReaction(armed) {
+    armed.n++;
+    queueMicrotask(() => {
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                armed.n = Math.max(0, armed.n - 1);
+            });
+        });
+    });
+}
 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--;
+            return;
+        }
         if (syncing === "doc")
             return;
         syncing = "code";
+        armIgnoreNextPaneScrollReaction(ignoreDocScrollFromPartnerSync);
         syncFromCode();
         syncing = "none";
     }, { passive: true });
     docPane.addEventListener("scroll", () => {
+        if (ignoreDocScrollFromPartnerSync.n > 0) {
+            ignoreDocScrollFromPartnerSync.n--;
+            return;
+        }
         if (syncing === "code")
             return;
         syncing = "doc";
+        armIgnoreNextPaneScrollReaction(ignoreCodeScrollFromPartnerSync);
         syncFromDoc();
         syncing = "none";
     }, { passive: true });
 }
 /** Index-backed scroll sync when `data-scroll-block-links-b64` is present; else see proportional fallback. */
 function wireBlockAwareScrollSync(codePane, docPane, getLinks) {
-    wireBidirectionalScroll(codePane, docPane, () => {
-        const links = getLinks();
-        const line1 = probeCodeLine1FromViewport(codePane);
-        const mdLine0 = pickCommentrayLineForSourceScroll(links, line1);
-        if (mdLine0 === null) {
-            docPane.scrollTop = mirroredScrollTop(codePane.scrollTop, codePane.scrollHeight, codePane.clientHeight, docPane.scrollHeight, docPane.clientHeight);
-        }
-        else {
-            const anchor = docPane.querySelector(`[data-commentray-line="${String(mdLine0)}"]`);
-            if (anchor instanceof HTMLElement) {
-                const top = anchor.getBoundingClientRect().top -
-                    docPane.getBoundingClientRect().top +
-                    docPane.scrollTop;
-                docPane.scrollTop = Math.max(0, top - 2);
-            }
-            else {
-                docPane.scrollTop = mirroredScrollTop(codePane.scrollTop, codePane.scrollHeight, codePane.clientHeight, docPane.scrollHeight, docPane.clientHeight);
-            }
-        }
-    }, () => {
-        const links = getLinks();
-        const mdLine0 = probeCommentrayLine0FromDoc(docPane);
-        const src0 = pickSourceLine0ForCommentrayScroll(links, mdLine0);
-        if (src0 === null) {
-            codePane.scrollTop = mirroredScrollTop(docPane.scrollTop, docPane.scrollHeight, docPane.clientHeight, codePane.scrollHeight, codePane.clientHeight);
-        }
-        else {
-            const el = document.getElementById(`code-line-${String(src0)}`);
-            if (el) {
-                const top = el.getBoundingClientRect().top -
-                    codePane.getBoundingClientRect().top +
-                    codePane.scrollTop;
-                codePane.scrollTop = Math.max(0, top - 2);
-            }
-            else {
-                codePane.scrollTop = mirroredScrollTop(docPane.scrollTop, docPane.scrollHeight, docPane.clientHeight, codePane.scrollHeight, codePane.clientHeight);
-            }
-        }
-    });
+    let pendingDocToCode = null;
+    let pendingCodeToDoc = null;
+    const syncFromCodeToDoc = () => {
+        applyCodeToDocFlipPlanImpl(codePane, docPane, buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks));
+    };
+    const syncFromDocToCode = () => {
+        applyDocToCodeFlipPlanImpl(codePane, docPane, buildDocToCodeFlipPlanBlockAware(docPane, getLinks));
+    };
+    const prepareMobileFlipToCode = () => {
+        pendingDocToCode = buildDocToCodeFlipPlanBlockAware(docPane, getLinks);
+    };
+    const finishMobileFlipToCode = () => {
+        if (!pendingDocToCode)
+            return;
+        const p = pendingDocToCode;
+        pendingDocToCode = null;
+        applyDocToCodeFlipPlanImpl(codePane, docPane, p);
+    };
+    const prepareMobileFlipToDoc = () => {
+        pendingCodeToDoc = buildCodeToDocFlipPlanBlockAware(codePane, docPane, getLinks);
+    };
+    const finishMobileFlipToDoc = () => {
+        if (!pendingCodeToDoc)
+            return;
+        const p = pendingCodeToDoc;
+        pendingCodeToDoc = null;
+        applyCodeToDocFlipPlanImpl(codePane, docPane, p);
+    };
+    wireBidirectionalScroll(codePane, docPane, syncFromCodeToDoc, syncFromDocToCode);
+    return {
+        syncFromCodeToDoc,
+        syncFromDocToCode,
+        prepareMobileFlipToCode,
+        finishMobileFlipToCode,
+        prepareMobileFlipToDoc,
+        finishMobileFlipToDoc,
+    };
 }
 /** Proportional scroll sync when there is no index-backed block map (GitHub Pages default). */
 function wireProportionalScrollSync(codePane, docPane) {
-    wireBidirectionalScroll(codePane, docPane, () => {
-        docPane.scrollTop = mirroredScrollTop(codePane.scrollTop, codePane.scrollHeight, codePane.clientHeight, docPane.scrollHeight, docPane.clientHeight);
-    }, () => {
-        codePane.scrollTop = mirroredScrollTop(docPane.scrollTop, docPane.scrollHeight, docPane.clientHeight, codePane.scrollHeight, codePane.clientHeight);
-    });
+    let pendingDocToCode = null;
+    let pendingCodeToDoc = null;
+    const syncFromCodeToDoc = () => {
+        applyCodeToDocFlipPlanImpl(codePane, docPane, buildCodeToDocFlipPlanProportional(codePane));
+    };
+    const syncFromDocToCode = () => {
+        applyDocToCodeFlipPlanImpl(codePane, docPane, buildDocToCodeFlipPlanProportional(docPane));
+    };
+    const prepareMobileFlipToCode = () => {
+        pendingDocToCode = buildDocToCodeFlipPlanProportional(docPane);
+    };
+    const finishMobileFlipToCode = () => {
+        if (!pendingDocToCode)
+            return;
+        const p = pendingDocToCode;
+        pendingDocToCode = null;
+        applyDocToCodeFlipPlanImpl(codePane, docPane, p);
+    };
+    const prepareMobileFlipToDoc = () => {
+        pendingCodeToDoc = buildCodeToDocFlipPlanProportional(codePane);
+    };
+    const finishMobileFlipToDoc = () => {
+        if (!pendingCodeToDoc)
+            return;
+        const p = pendingCodeToDoc;
+        pendingCodeToDoc = null;
+        applyCodeToDocFlipPlanImpl(codePane, docPane, p);
+    };
+    wireBidirectionalScroll(codePane, docPane, syncFromCodeToDoc, syncFromDocToCode);
+    return {
+        syncFromCodeToDoc,
+        syncFromDocToCode,
+        prepareMobileFlipToCode,
+        finishMobileFlipToCode,
+        prepareMobileFlipToDoc,
+        finishMobileFlipToDoc,
+    };
 }
 function centerYInViewport(el) {
     const r = el.getBoundingClientRect();
@@ -667,6 +1011,8 @@ 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.
+ *
+ * @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;
@@ -693,6 +1039,7 @@ function wireBlockRayConnectors(args) {
         scheduleDraw();
         globalThis.requestAnimationFrame(scheduleDraw);
     });
+    return scheduleDraw;
 }
 function isDocumentedPairNav(x) {
     if (typeof x !== "object" || x === null)
@@ -905,6 +1252,52 @@ function loadDocumentedPairs(jsonUrl, embeddedB64) {
         return loaded ?? [];
     };
 }
+/**
+ * On narrow viewports the toolbar strip uses horizontal overflow; absolutely positioned
+ * `.nav-rail__doc-hub-inner` is clipped. Pin the panel with `position: fixed` while open.
+ */
+function wireDocumentedFilesTreeMobileFlyout(hub) {
+    const innerCandidate = hub.querySelector(".nav-rail__doc-hub-inner");
+    if (!(innerCandidate instanceof HTMLElement)) {
+        return () => { };
+    }
+    const flyoutInner = innerCandidate;
+    const mq = globalThis.matchMedia("(max-width: 767px)");
+    function summaryEl() {
+        const s = hub.querySelector("summary");
+        return s instanceof HTMLElement ? s : null;
+    }
+    function placeFlyout() {
+        if (!hub.open || !mq.matches) {
+            flyoutInner.style.removeProperty("position");
+            flyoutInner.style.removeProperty("top");
+            flyoutInner.style.removeProperty("left");
+            flyoutInner.style.removeProperty("right");
+            flyoutInner.style.removeProperty("width");
+            flyoutInner.style.removeProperty("max-width");
+            flyoutInner.style.removeProperty("max-height");
+            flyoutInner.style.removeProperty("z-index");
+            return;
+        }
+        const sum = summaryEl();
+        if (!sum)
+            return;
+        const r = sum.getBoundingClientRect();
+        const pad = 8;
+        flyoutInner.style.position = "fixed";
+        flyoutInner.style.top = `${String(Math.round(r.bottom + 4))}px`;
+        flyoutInner.style.left = `${String(Math.round(pad))}px`;
+        flyoutInner.style.right = `${String(Math.round(pad))}px`;
+        flyoutInner.style.width = "auto";
+        flyoutInner.style.maxWidth = "none";
+        flyoutInner.style.maxHeight = "min(52vh, 400px)";
+        flyoutInner.style.zIndex = "200";
+    }
+    mq.addEventListener("change", placeFlyout);
+    globalThis.addEventListener("resize", placeFlyout);
+    globalThis.addEventListener("scroll", placeFlyout, true);
+    return placeFlyout;
+}
 function wireDocumentedFilesTree() {
     const hub = document.getElementById("documented-files-hub");
     const treeHost = document.getElementById("documented-files-tree");
@@ -918,6 +1311,7 @@ function wireDocumentedFilesTree() {
     const embeddedB64 = shell?.getAttribute("data-documented-pairs-b64")?.trim() ?? "";
     if (jsonUrl.length === 0 && embeddedB64.length === 0)
         return;
+    const placeDocHubFlyout = wireDocumentedFilesTreeMobileFlyout(hub);
     const ensureLoaded = loadDocumentedPairs(jsonUrl, embeddedB64);
     let cachedPairs = null;
     function applyFilterAndRender() {
@@ -941,6 +1335,10 @@ function wireDocumentedFilesTree() {
         }
     }
     hub.addEventListener("toggle", () => {
+        placeDocHubFlyout();
+        if (hub.open) {
+            globalThis.requestAnimationFrame(placeDocHubFlyout);
+        }
         if (!hub.open)
             return;
         void hydrateTree();
@@ -964,6 +1362,7 @@ function wireSplitter(storageSplit, shell, codePane, gutter, initialPct) {
         const p = clamp((x / rect.width) * 100, 15, 85);
         lastPct = p;
         codePane.style.flex = `0 0 ${p}%`;
+        shell.style.setProperty("--split-pct", `${String(p)}%`);
     }
     function stop() {
         dragging = false;
@@ -984,10 +1383,118 @@ 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";
+/** 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";
+}
+/** When the commentary pane is visible, (re)run Mermaid so diagrams are not laid out under display:none. */
+function scheduleMermaidWhenDualDocPaneVisible(shell, mq) {
+    const kick = () => {
+        if (shell.getAttribute("data-layout") !== "dual")
+            return;
+        if (!mq.matches)
+            return;
+        if (normalizedDualMobilePane(shell.getAttribute("data-dual-mobile-pane")) !== "doc")
+            return;
+        const docBody = document.getElementById("doc-pane-body");
+        if (!(docBody instanceof HTMLElement))
+            return;
+        runMermaidOnFreshDocNodes(docBody);
+    };
+    queueMicrotask(() => {
+        kick();
+        requestAnimationFrame(() => {
+            kick();
+            requestAnimationFrame(kick);
+        });
+    });
+}
+function wireDualMobilePaneFlipScrollAffordance(primaryFlip, scrollFlip, mq) {
+    const hideScroll = () => {
+        scrollFlip.hidden = true;
+        scrollFlip.classList.remove("is-visible");
+    };
+    const showScroll = () => {
+        scrollFlip.hidden = false;
+        scrollFlip.classList.add("is-visible");
+    };
+    /** Prefer geometry over IntersectionObserver: a sliver “intersecting” the viewport is still unusable. */
+    const tick = () => {
+        if (!mq.matches) {
+            hideScroll();
+            return;
+        }
+        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 });
+    mq.addEventListener("change", tick);
+    globalThis.requestAnimationFrame(tick);
+}
+function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
+    const mq = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ);
+    function readStoredPane() {
+        return normalizedDualMobilePane(readWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE));
+    }
+    function applyForViewport() {
+        if (mq.matches) {
+            shell.setAttribute("data-dual-mobile-pane", readStoredPane());
+        }
+        else {
+            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";
+        if (next === "code") {
+            scrollRunners.prepareMobileFlipToCode();
+        }
+        else {
+            scrollRunners.prepareMobileFlipToDoc();
+        }
+        shell.setAttribute("data-dual-mobile-pane", next);
+        writeWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE, next);
+        globalThis.requestAnimationFrame(() => {
+            globalThis.requestAnimationFrame(() => {
+                if (next === "code") {
+                    scrollRunners.finishMobileFlipToCode();
+                }
+                else {
+                    scrollRunners.finishMobileFlipToDoc();
+                }
+            });
+        });
+        // Only here (not on every viewport apply): avoids redundant Mermaid passes on load/resize for the default commentary-first shell.
+        if (next === "doc") {
+            scheduleMermaidWhenDualDocPaneVisible(shell, mq);
+        }
+    };
+    flipBtn.addEventListener("click", runFlip);
+    if (flipScrollBtn) {
+        flipScrollBtn.addEventListener("click", runFlip);
+        wireDualMobilePaneFlipScrollAffordance(flipBtn, flipScrollBtn, mq);
+    }
+    mq.addEventListener("change", applyForViewport);
+    applyForViewport();
+}
 function wireStretchLayoutChrome(codePane) {
     const wrapCb = document.getElementById("wrap-lines");
     if (wrapCb) {
-        wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb);
+        wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb, () => {
+            globalThis.dispatchEvent(new Event("resize"));
+        });
     }
 }
 function parseMultiAnglePayload(script) {
@@ -1124,9 +1631,9 @@ function wireDualPaneNavSearchFetch(shell, embeddedPairs, indexState, mutable, r
     })();
 }
 function wireDualPaneMultiAngleAndScroll(args) {
-    const { codePane, docScrollEl, docBody, shell, scrollLinksRef, multiPayload, mutable, rebuildSearcher, searchInput, searchResults, } = args;
+    const { codePane, docScrollEl, docBody, shell, scrollLinksRef, multiPayload, mutable, rebuildSearcher, searchInput, searchResults, requestBlockRayRedraw, } = args;
     if (multiPayload) {
-        wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
+        const runners = wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
         const angleSel = document.getElementById("angle-select");
         if (angleSel && docBody) {
             angleSel.addEventListener("change", () => {
@@ -1135,6 +1642,7 @@ function wireDualPaneMultiAngleAndScroll(args) {
                     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;
@@ -1151,35 +1659,38 @@ function wireDualPaneMultiAngleAndScroll(args) {
                     else
                         docPathEl.removeAttribute("title");
                 }
-                const gh = document.getElementById("toolbar-commentray-github");
-                if (gh instanceof HTMLAnchorElement) {
-                    const browse = a.staticBrowseUrl?.trim() ?? "";
-                    if (browse.length > 0) {
-                        gh.href = resolveStaticBrowseHref(browse, globalThis.location.pathname, globalThis.location.origin);
-                        gh.removeAttribute("target");
-                        gh.setAttribute("rel", "noopener");
+                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 {
-                        const ghu = a.commentrayOnGithubUrl?.trim();
-                        if (ghu) {
-                            gh.href = ghu;
-                            gh.target = "_blank";
-                            gh.setAttribute("rel", "noopener noreferrer");
-                        }
+                        shell.removeAttribute("data-commentray-pair-browse-href");
                     }
                 }
                 searchInput.value = "";
                 searchResults.innerHTML = "";
                 searchResults.hidden = true;
+                requestBlockRayRedraw?.();
+                globalThis.requestAnimationFrame(() => {
+                    requestBlockRayRedraw?.();
+                    globalThis.requestAnimationFrame(() => {
+                        requestBlockRayRedraw?.();
+                    });
+                });
             });
         }
-        return;
+        return runners;
     }
     if (scrollLinksRef.current.length > 0) {
-        wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
-        return;
+        return wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
     }
-    wireProportionalScrollSync(codePane, docScrollEl);
+    return wireProportionalScrollSync(codePane, docScrollEl);
 }
 function wireDualPaneCommentrayLocationHash(docScrollEl, mdLineCount) {
     function applyCommentrayLocationHash() {
@@ -1196,11 +1707,7 @@ function wireDualPaneCommentrayLocationHash(docScrollEl, mdLineCount) {
         globalThis.requestAnimationFrame(applyCommentrayLocationHash);
     });
 }
-function wireDualPaneCodeBrowser(shell, codePane) {
-    const dom = readDualPaneDomBundle();
-    if (!dom)
-        return;
-    const { docBody, docScrollEl, gutter, wrapCb, searchInput, searchClear, searchResults } = dom;
+function buildDualPaneSearcherBundle(shell, codePane) {
     const { rawCodeB64, rawMdB64 } = readEmbeddedRawB64Strings(shell, codePane);
     const rawCode = decodeBase64Utf8(rawCodeB64);
     const rawMd = decodeBase64Utf8(rawMdB64);
@@ -1234,48 +1741,184 @@ function wireDualPaneCodeBrowser(shell, codePane) {
         }));
     }
     rebuildSearcher();
-    wireSearchUi({
+    return {
+        rawCode,
+        rawMd,
+        scrollLinksRef,
         scope,
         filePathLabel,
+        commentrayPathLabel,
+        pathInit,
+        indexState,
         mutable,
-        rawCode,
+        rebuildSearcher,
+    };
+}
+function wireDualPaneCodeBrowser(shell, codePane) {
+    const dom = readDualPaneDomBundle();
+    if (!dom)
+        return;
+    const { docBody, docScrollEl, gutter, wrapCb, searchInput, searchClear, searchResults } = dom;
+    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, pathInit.documentedPairs, indexState, mutable, rebuildSearcher, searchInput);
-    const pct0 = parseFloat(readWebStorageItem(localStorage, STORAGE_SPLIT_PCT) || "50");
-    const pct = clamp(Number.isFinite(pct0) ? pct0 : 50, 15, 85);
+    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}%`;
-    wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb);
+    shell.style.setProperty("--split-pct", `${String(pct)}%`);
+    const docPaneEl = document.getElementById("doc-pane");
+    const docPaneForWrap = docPaneEl instanceof HTMLElement ? docPaneEl : null;
+    const blockRayRedraw = {};
+    wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb, () => {
+        blockRayRedraw.request?.();
+        codePane.dispatchEvent(new Event("scroll"));
+        docScrollEl.dispatchEvent(new Event("scroll"));
+    }, docPaneForWrap, docBody);
     wireSplitter(STORAGE_SPLIT_PCT, shell, codePane, gutter, pct);
     const multiScript = document.getElementById("commentray-multi-angle-b64");
     const multiPayload = parseMultiAnglePayload(multiScript);
-    wireDualPaneMultiAngleAndScroll({
+    const shouldWireBlockRays = multiPayload !== null || bundle.scrollLinksRef.current.length > 0;
+    const requestBlockRayRedraw = shouldWireBlockRays
+        ? wireBlockRayConnectors({
+            gutter,
+            codePane,
+            docScrollEl,
+            getLinks: () => bundle.scrollLinksRef.current,
+            probeTopSourceLine1Based: () => probeCodeLine1FromViewport(codePane),
+        })
+        : undefined;
+    blockRayRedraw.request = requestBlockRayRedraw;
+    const scrollRunners = wireDualPaneMultiAngleAndScroll({
         codePane,
         docScrollEl,
         docBody,
         shell,
-        scrollLinksRef,
+        scrollLinksRef: bundle.scrollLinksRef,
         multiPayload,
-        mutable,
-        rebuildSearcher,
+        mutable: bundle.mutable,
+        rebuildSearcher: bundle.rebuildSearcher,
         searchInput,
         searchResults,
+        requestBlockRayRedraw,
     });
-    if (scrollLinksRef.current.length > 0) {
-        wireBlockRayConnectors({
-            gutter,
-            codePane,
-            docScrollEl,
-            getLinks: () => scrollLinksRef.current,
-            probeTopSourceLine1Based: () => probeCodeLine1FromViewport(codePane),
+    const flipBtn = document.getElementById("mobile-pane-flip");
+    const flipScrollBtn = document.getElementById("mobile-pane-flip-scroll");
+    if (flipBtn instanceof HTMLButtonElement) {
+        wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn instanceof HTMLButtonElement ? flipScrollBtn : null);
+    }
+    wireDualPaneCommentrayLocationHash(docScrollEl, () => bundle.mutable.mdLines.length);
+}
+function commentrayThemeModeLabel(mode) {
+    if (mode === "light")
+        return "Light";
+    if (mode === "dark")
+        return "Dark";
+    return "System";
+}
+function setCommentrayThemeTriggerHints(trigger, mode) {
+    const label = commentrayThemeModeLabel(mode);
+    trigger.setAttribute("aria-label", `Color theme: ${label}. Left-click opens the menu. Right-click cycles System, Light, and Dark.`);
+    trigger.title = `Appearance: ${label} — left-click menu, right-click cycle`;
+}
+function wireColorThemeToolbar() {
+    const wrapEl = document.querySelector(".toolbar-theme");
+    const triggerEl = document.getElementById("commentray-theme-trigger");
+    const menuEl = document.getElementById("commentray-theme-menu");
+    if (!wrapEl || !(triggerEl instanceof HTMLButtonElement) || !(menuEl instanceof HTMLElement))
+        return;
+    const themeToolbarWrap = wrapEl;
+    const themeButton = triggerEl;
+    const themeMenu = menuEl;
+    let currentMode = parseCommentrayColorThemeMode(readWebStorageItem(localStorage, COMMENTRAY_COLOR_THEME_STORAGE_KEY));
+    applyCommentrayColorTheme(currentMode);
+    let menuOpen = false;
+    function syncUi() {
+        themeButton.dataset.commentrayTriggerMode = currentMode;
+        themeButton.setAttribute("aria-expanded", menuOpen ? "true" : "false");
+        setCommentrayThemeTriggerHints(themeButton, currentMode);
+        for (const el of themeMenu.querySelectorAll("[data-commentray-theme-value]")) {
+            const v = parseCommentrayColorThemeMode(el.dataset.commentrayThemeValue ?? "");
+            el.setAttribute("aria-checked", v === currentMode ? "true" : "false");
+        }
+    }
+    function openMenu() {
+        menuOpen = true;
+        themeMenu.removeAttribute("hidden");
+        syncUi();
+        const checked = themeMenu.querySelector('[role="menuitemradio"][aria-checked="true"]');
+        (checked ?? themeMenu.querySelector('[role="menuitemradio"]'))?.focus();
+    }
+    function closeMenu() {
+        menuOpen = false;
+        themeMenu.setAttribute("hidden", "");
+        syncUi();
+    }
+    function persistAndApply(mode) {
+        currentMode = mode;
+        writeWebStorageItem(localStorage, COMMENTRAY_COLOR_THEME_STORAGE_KEY, mode);
+        applyCommentrayColorTheme(mode);
+        syncUi();
+    }
+    themeButton.addEventListener("click", (ev) => {
+        ev.preventDefault();
+        ev.stopPropagation();
+        if (menuOpen) {
+            closeMenu();
+        }
+        else {
+            openMenu();
+        }
+    });
+    themeButton.addEventListener("contextmenu", (ev) => {
+        ev.preventDefault();
+        if (menuOpen)
+            closeMenu();
+        persistAndApply(nextCommentrayColorThemeMode(currentMode));
+    });
+    for (const item of themeMenu.querySelectorAll("[data-commentray-theme-value]")) {
+        item.addEventListener("click", (ev) => {
+            ev.stopPropagation();
+            const mode = parseCommentrayColorThemeMode(item.dataset.commentrayThemeValue ?? "");
+            persistAndApply(mode);
+            closeMenu();
+            themeButton.focus();
         });
     }
-    wireDualPaneCommentrayLocationHash(docScrollEl, () => mutable.mdLines.length);
+    function onDocumentPointerDown(ev) {
+        if (!menuOpen)
+            return;
+        const t = ev.target;
+        if (!(t instanceof Node))
+            return;
+        if (themeToolbarWrap.contains(t))
+            return;
+        closeMenu();
+    }
+    function onDocumentKeydown(ev) {
+        if (!menuOpen || ev.key !== "Escape")
+            return;
+        ev.preventDefault();
+        ev.stopPropagation();
+        closeMenu();
+        themeButton.focus();
+    }
+    document.addEventListener("mousedown", onDocumentPointerDown, true);
+    document.addEventListener("touchstart", onDocumentPointerDown, true);
+    document.addEventListener("keydown", onDocumentKeydown, true);
+    syncUi();
 }
 function main() {
+    wireColorThemeToolbar();
     wireDocumentedFilesTree();
     const shell = document.getElementById("shell");
     const codePane = document.getElementById("code-pane");