@commentray/render 0.3.4 → 0.3.6

package/dist/code-browser-client.js

@@ -13,7 +13,7 @@ import { parseDualPaneScrollSyncStrategy } from "./code-browser-scroll-sync-stra
 import { DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX, READING_LEAD_ALIGN_TOLERANCE_CSS_PX, READING_VIEWPORT_BOTTOM_EDGE_CSS_PX, readingViewportTopInsetCssPx, } from "./reading-viewport-comfort.js";
 import { wireWideModeIntroTour } from "./code-browser-wide-intro-controller.js";
 import { readWebStorageItem, writeWebStorageItem } from "./code-browser-web-storage.js";
-import { dispatchCommentrayMermaidDone, wireBlockStretchBufferSync, } from "./block-stretch-buffer-sync.js";
+import { applyBlockStretchRowBuffers, dispatchCommentrayMermaidDone, wireBlockStretchBufferSync, } from "./block-stretch-buffer-sync.js";
 import { COMMENTRAY_MERMAID_MODULE_READY_EVENT } from "./commentray-mermaid-events.js";
 /**
  * Hub pages emit `./browse/…` relative to the site root. From `/…/browse/current.html` the browser
@@ -936,16 +936,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 = Math.round(scrollTopToAlignChildTop(docScrollEl, el, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX));
-        const maxY = Math.round(Math.max(0, docScrollEl.scrollHeight - docScrollEl.clientHeight));
-        docScrollEl.scrollTo({ top: clamp(top, 0, maxY), behavior: "smooth" });
+        applyRevealChildInPane(docScrollEl, el, DUAL_PANE_BLOCK_REVEAL_LEAD_CSS_PX);
         return;
     }
     if (mdLineCount <= 1)
         return;
-    const ratio = line0 / Math.max(1, mdLineCount - 1);
-    const maxScroll = Math.max(0, docScrollEl.scrollHeight - docScrollEl.clientHeight);
-    docScrollEl.scrollTo({ top: ratio * maxScroll, behavior: "smooth" });
+    const lineClamped = clamp(line0, 0, Math.max(0, mdLineCount - 1));
+    const scrollTarget = paneUsesInternalYScroll(docScrollEl) ? docScrollEl : rootScrollingElement();
+    const maxScroll = Math.max(0, scrollTarget.scrollHeight - scrollTarget.clientHeight);
+    const top = clamp((lineClamped / Math.max(1, mdLineCount - 1)) * maxScroll, 0, maxScroll);
+    scrollTarget.scrollTo({ top, behavior: "smooth" });
 }
 function navigateToDocumentedPair(pair, mdLine0) {
     if (pair.staticBrowseUrl?.trim()) {
@@ -1028,7 +1028,10 @@ function handlePathSearchHit(button, deps) {
     const hitSp = (button.getAttribute("data-sp-path") ?? "").trim();
     const pair = findDocumentedPair(deps.mutable.documentedPairs, hitCr, hitSp);
     if (pair && isSameDocumentedPair(pair, deps.filePathLabel, deps.mutable.commentrayPathLabel)) {
-        deps.docScrollEl.scrollTo({ top: 0, behavior: "smooth" });
+        const scrollTarget = paneUsesInternalYScroll(deps.docScrollEl)
+            ? deps.docScrollEl
+            : rootScrollingElement();
+        scrollTarget.scrollTo({ top: 0, behavior: "smooth" });
         return;
     }
     if (pair)
@@ -2490,6 +2493,38 @@ const DUAL_MOBILE_SINGLE_PANE_MQ = "(max-width: 767px)";
 function normalizedDualMobilePane(v) {
     return v === "code" ? "code" : "doc";
 }
+function splitLocationHashTokens(rawHash) {
+    const hash = rawHash.replace(/^#/, "").trim();
+    if (hash.length === 0)
+        return [];
+    return hash
+        .split(/--|&/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+function mobilePaneHashToken(pane) {
+    return `mobile-pane-${pane}`;
+}
+function mobilePaneFromLocationHash(rawHash) {
+    const tokens = splitLocationHashTokens(rawHash);
+    for (const token of tokens) {
+        if (token === "mobile-pane-code")
+            return "code";
+        if (token === "mobile-pane-doc")
+            return "doc";
+    }
+    return null;
+}
+function updateLocationHashToken(token, shouldReplace) {
+    const tokens = splitLocationHashTokens(globalThis.location.hash).filter((t) => !shouldReplace(t));
+    tokens.push(token);
+    const u = new URL(globalThis.location.href);
+    u.hash = tokens.length > 0 ? tokens.join("&") : "";
+    globalThis.history.replaceState(globalThis.history.state, "", u.toString());
+}
+function updateLocationHashForMobilePane(pane) {
+    updateLocationHashToken(mobilePaneHashToken(pane), (t) => /^mobile-pane-(?:code|doc)$/.test(t));
+}
 function isNarrowViewport() {
     return globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ).matches;
 }
@@ -2713,6 +2748,7 @@ function wireSourceMarkdownPaneFlip(shell, codePane, flipBtn, flipScrollBtn, sig
             if (curPane === "doc") {
                 shell.setAttribute("data-dual-mobile-pane", "code");
                 writeWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE, "code");
+                updateLocationHashForMobilePane("code");
             }
         }
         syncSourceMarkdownFlipA11y();
@@ -2741,6 +2777,9 @@ function wireSourceMarkdownPaneFlip(shell, codePane, flipBtn, flipScrollBtn, sig
 function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
     const mq = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ);
     function readStoredPane() {
+        const fromHash = mobilePaneFromLocationHash(globalThis.location.hash);
+        if (fromHash !== null)
+            return fromHash;
         return normalizedDualMobilePane(readWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE));
     }
     function applyForViewport() {
@@ -2767,6 +2806,7 @@ function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
         }
         shell.setAttribute("data-dual-mobile-pane", next);
         writeWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE, next);
+        updateLocationHashForMobilePane(next);
         globalThis.requestAnimationFrame(() => {
             globalThis.requestAnimationFrame(() => {
                 if (next === "code") {
@@ -2793,49 +2833,64 @@ function wireDualMobilePaneFlip(shell, flipBtn, scrollRunners, flipScrollBtn) {
         wireDualMobilePaneFlipScrollAffordance(flipBtn, flipScrollBtn, mq);
     }
     mq.addEventListener("change", applyForViewport);
+    globalThis.addEventListener("hashchange", applyForViewport);
     applyForViewport();
 }
 function wireStretchMobilePaneFlip(shell, codePane, flipBtn, flipScrollBtn, onAfterFlip) {
-    void codePane;
-    void onAfterFlip;
-    const mq = globalThis.matchMedia(DUAL_MOBILE_SINGLE_PANE_MQ);
-    function readStoredPane() {
-        return normalizedDualMobilePane(readWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE));
-    }
-    function applyForViewport() {
-        if (mq.matches) {
-            syncSinglePaneShellState(shell, true);
-            shell.setAttribute("data-dual-mobile-pane", readStoredPane());
+    const stretchTable = codePane instanceof HTMLTableElement ? codePane : null;
+    let anchorRow = null;
+    let anchorTopBefore = 0;
+    let rootTopBefore = 0;
+    const captureAnchor = () => {
+        const root = rootScrollingElement();
+        rootTopBefore = root.scrollTop;
+        if (stretchTable === null) {
+            anchorRow = null;
+            anchorTopBefore = 0;
+            return;
         }
-        else {
-            syncSinglePaneShellState(shell, false);
-            shell.removeAttribute("data-dual-mobile-pane");
+        const rows = stretchBlockRows(stretchTable);
+        anchorRow = rows.find((row) => row.getBoundingClientRect().bottom > 0) ?? null;
+        anchorTopBefore = anchorRow?.getBoundingClientRect().top ?? 0;
+    };
+    const restoreAnchor = () => {
+        const root = rootScrollingElement();
+        if (anchorRow !== null) {
+            const delta = anchorRow.getBoundingClientRect().top - anchorTopBefore;
+            if (Math.abs(delta) > 0.5) {
+                const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+                root.scrollTop = clamp(root.scrollTop + delta, 0, maxY);
+                return;
+            }
         }
-    }
-    const runFlip = () => {
-        if (!mq.matches)
-            return;
-        const cur = normalizedDualMobilePane(shell.getAttribute("data-dual-mobile-pane"));
-        const next = cur === "code" ? "doc" : "code";
-        shell.setAttribute("data-dual-mobile-pane", next);
-        writeWebStorageItem(localStorage, STORAGE_DUAL_MOBILE_PANE, next);
-        // When revealing the doc pane, (re)run Mermaid — diagrams inside display:none cells are
-        // skipped on initial load, so they need a triggered pass once the cells become visible.
-        if (next === "doc") {
-            queueMicrotask(() => {
+        const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
+        root.scrollTop = clamp(rootTopBefore, 0, maxY);
+    };
+    const applyBuffersAndRestore = () => {
+        if (stretchTable !== null)
+            applyBlockStretchRowBuffers(stretchTable);
+        restoreAnchor();
+    };
+    const runners = {
+        syncFromCodeToDoc: () => { },
+        syncFromDocToCode: () => { },
+        prepareMobileFlipToCode: captureAnchor,
+        prepareMobileFlipToDoc: captureAnchor,
+        finishMobileFlipToCode: () => {
+            applyBuffersAndRestore();
+            onAfterFlip?.();
+        },
+        finishMobileFlipToDoc: () => {
+            applyBuffersAndRestore();
+            onAfterFlip?.();
+            void runMermaidOnFreshDocNodes(shell).then(() => {
                 requestAnimationFrame(() => {
-                    void runMermaidOnFreshDocNodes(shell);
+                    applyBuffersAndRestore();
                 });
             });
-        }
+        },
     };
-    flipBtn.addEventListener("click", runFlip);
-    if (flipScrollBtn) {
-        flipScrollBtn.addEventListener("click", runFlip);
-        wireDualMobilePaneFlipScrollAffordance(flipBtn, flipScrollBtn, mq);
-    }
-    mq.addEventListener("change", applyForViewport);
-    applyForViewport();
+    wireDualMobilePaneFlip(shell, flipBtn, runners, flipScrollBtn);
 }
 /** Multi-angle stretch swaps `#shell` innerHTML; disconnect the previous table observer so listeners do not accumulate. */
 let stretchRowBufferSyncHandle = null;
@@ -3238,6 +3293,27 @@ function initialCommentrayScopePathState(shell, scope, filePathLabel, commentray
         : [filePathLabel, commentrayPathLabel].filter((s) => s.trim().length > 0).join("\n");
     return { documentedPairs, pathRowsForOrdering, pathBlobWide };
 }
+function effectiveCommentrayPathLabelFromDocumentedPairs(scope, filePathLabel, commentrayPathLabel, documentedPairs) {
+    if (scope !== "commentray-and-paths")
+        return commentrayPathLabel;
+    const sourcePath = filePathLabel.trim();
+    if (sourcePath.length === 0)
+        return commentrayPathLabel;
+    const pair = findDocumentedPair(documentedPairs, "", sourcePath);
+    if (!pair)
+        return commentrayPathLabel;
+    const fromShell = commentrayPathLabel.trim();
+    const fromPair = pair.commentrayPath.trim();
+    if (fromPair.length === 0)
+        return commentrayPathLabel;
+    if (fromShell.length === 0)
+        return fromPair;
+    // Older hub HTML can carry placeholder `commentray.md` while documentedPairs already has the real path.
+    if (normPosixPath(fromShell) === "commentray.md" && normPosixPath(fromPair) !== "commentray.md") {
+        return fromPair;
+    }
+    return commentrayPathLabel;
+}
 /**
  * Fetched `commentray-nav-search.json` sometimes omits `staticBrowseUrl` on pairs; the hub embed
  * carries browse URLs from the same build — merge so search hits open `_site/browse/…`, not GitHub.
@@ -3466,6 +3542,15 @@ function buildDualPaneSearcherBundle(shell, codePane) {
     const scrollLinksRef = { current: scrollLinks };
     const { scope, filePathLabel, commentrayPathLabel } = readSearchScopeFromShell(shell);
     const pathInit = initialCommentrayScopePathState(shell, scope, filePathLabel, commentrayPathLabel);
+    const effectiveCommentrayPathLabel = effectiveCommentrayPathLabelFromDocumentedPairs(scope, filePathLabel, commentrayPathLabel, pathInit.documentedPairs);
+    if (effectiveCommentrayPathLabel.trim().length > 0) {
+        shell.setAttribute("data-search-commentray-path", effectiveCommentrayPathLabel);
+        const docPathEl = document.getElementById("nav-rail-doc-path");
+        if (docPathEl) {
+            docPathEl.textContent = effectiveCommentrayPathLabel;
+            docPathEl.setAttribute("title", effectiveCommentrayPathLabel);
+        }
+    }
     const indexState = {
         hubNavRows: [],
         documentedPairs: pathInit.documentedPairs,
@@ -3474,7 +3559,7 @@ function buildDualPaneSearcherBundle(shell, codePane) {
     const mutable = {
         rawMd,
         mdLines: rawMd.split("\n"),
-        commentrayPathLabel,
+        commentrayPathLabel: effectiveCommentrayPathLabel,
         searcher: indexSearchLineRows([]),
         pathBlobWide: pathInit.pathBlobWide,
         pathRowsForOrdering: indexState.pathRowsForOrdering,
@@ -3498,7 +3583,7 @@ function buildDualPaneSearcherBundle(shell, codePane) {
         scrollLinksRef,
         scope,
         filePathLabel,
-        commentrayPathLabel,
+        commentrayPathLabel: effectiveCommentrayPathLabel,
         pathInit,
         indexState,
         mutable,
@@ -3766,6 +3851,11 @@ function permalinkHashSuffixFromUi() {
             pushUnique(`angle-${encodeURIComponent(id)}`);
         }
     }
+    const shell = document.getElementById("shell");
+    if (shell instanceof HTMLElement && shell.getAttribute("data-mobile-single-pane") === "true") {
+        const pane = normalizedDualMobilePane(shell.getAttribute("data-dual-mobile-pane"));
+        pushUnique(mobilePaneHashToken(pane));
+    }
     const activeAnchor = activeCommentrayHashTokenFromViewport();
     if (activeAnchor)
         pushUnique(activeAnchor);