@commentray/render 0.3.3 → 0.3.5

package/dist/code-browser-client.js

@@ -13,7 +13,8 @@ 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
  * would otherwise resolve `./browse/…` against that folder and nest a second `browse/` segment.
@@ -30,30 +31,82 @@ function rewriteHubRelativeBrowseAnchorsIn(root) {
         el.href = resolveStaticBrowseHref(raw, path, origin);
     }
 }
+/**
+ * The Mermaid bundle is loaded via a trailing `type="module"` script (async `import()`). The main
+ * client runs as a classic inline script **before** that module executes, so `cy.visit` + an
+ * immediate pane flip can call {@link runMermaidOnFreshDocNodes} while `commentrayMermaid` is still
+ * undefined. We enqueue roots and flush on {@link COMMENTRAY_MERMAID_MODULE_READY_EVENT}.
+ */
+const pendingMermaidDocRoots = new Set();
+const queuedMermaidDocRoots = new Set();
+let mermaidQueueInFlight = null;
+function collectFreshMermaidPreNodes(roots) {
+    const uniq = new Set();
+    for (const root of roots) {
+        for (const pre of Array.from(root.querySelectorAll("pre.mermaid"))) {
+            const wrap = pre.closest(".commentray-mermaid");
+            if (wrap !== null && wrap.querySelector("svg") !== null)
+                continue;
+            uniq.add(pre);
+        }
+    }
+    return Array.from(uniq);
+}
+function pumpQueuedMermaidRuns() {
+    if (mermaidQueueInFlight)
+        return mermaidQueueInFlight;
+    mermaidQueueInFlight = (async () => {
+        while (queuedMermaidDocRoots.size > 0) {
+            const m = globalThis
+                .commentrayMermaid;
+            if (!m) {
+                for (const root of queuedMermaidDocRoots)
+                    pendingMermaidDocRoots.add(root);
+                queuedMermaidDocRoots.clear();
+                return;
+            }
+            const roots = Array.from(queuedMermaidDocRoots);
+            queuedMermaidDocRoots.clear();
+            const nodes = collectFreshMermaidPreNodes(roots);
+            if (nodes.length === 0)
+                continue;
+            try {
+                await m.run({ nodes });
+                dispatchCommentrayMermaidDone();
+            }
+            catch (err) {
+                console.error("Commentray: mermaid.run failed", err);
+            }
+        }
+    })().finally(() => {
+        mermaidQueueInFlight = null;
+        if (queuedMermaidDocRoots.size > 0)
+            void pumpQueuedMermaidRuns();
+    });
+    return mermaidQueueInFlight;
+}
+function queueMermaidRunForDocRoot(docRoot) {
+    queuedMermaidDocRoots.add(docRoot);
+    return pumpQueuedMermaidRuns();
+}
+function flushPendingMermaidDocRoots() {
+    const roots = Array.from(pendingMermaidDocRoots);
+    pendingMermaidDocRoots.clear();
+    for (const root of roots) {
+        void queueMermaidRunForDocRoot(root);
+    }
+}
+globalThis.addEventListener(COMMENTRAY_MERMAID_MODULE_READY_EVENT, () => {
+    flushPendingMermaidDocRoots();
+});
 function runMermaidOnFreshDocNodes(docBody) {
     if (typeof globalThis.location !== "undefined" && globalThis.location.protocol === "file:")
         return Promise.resolve();
-    /** Only fenced diagram sources; Mermaid leaves other `.mermaid` nodes in the tree after render. */
-    const allPres = Array.from(docBody.querySelectorAll("pre.mermaid"));
-    /** Do not re-run on wrappers that already have SVG (avoids corrupting output after dual-mobile pane flip). */
-    const nodes = allPres.filter((pre) => {
-        const wrap = pre.closest(".commentray-mermaid");
-        return wrap === null || wrap.querySelector("svg") === null;
-    });
-    if (nodes.length === 0)
-        return Promise.resolve();
-    const m = globalThis
-        .commentrayMermaid;
-    if (!m)
+    if (!globalThis.commentrayMermaid) {
+        pendingMermaidDocRoots.add(docBody);
         return Promise.resolve();
-    return m
-        .run({ nodes })
-        .then(() => {
-        dispatchCommentrayMermaidDone();
-    })
-        .catch((err) => {
-        console.error("Commentray: mermaid.run failed", err);
-    });
+    }
+    return queueMermaidRunForDocRoot(docBody);
 }
 function clamp(n, lo, hi) {
     return Math.max(lo, Math.min(hi, n));
@@ -1038,6 +1091,14 @@ function emptyBrowsePreviewInnerHtml(scope, filePathLabel, mutable) {
     const hint = emptyBrowsePreviewHint("commentray-and-paths", fb.length, fb.length, true);
     return emptySearchBrowsePreviewInnerHtml(hint, fb, hitCtx);
 }
+/**
+ * List rows use `focus({ preventScroll: true })` so the page does not jump; follow with
+ * `scrollIntoView` so overflow panels (`#search-results`, `#documented-files-tree`) still scroll.
+ */
+function focusListRowAndReveal(el) {
+    el.focus({ preventScroll: true });
+    el.scrollIntoView({ block: "nearest", inline: "nearest" });
+}
 function wireSearchResultsHitListKeyboard(searchResults, searchInput) {
     searchResults.addEventListener("keydown", (e) => {
         if (e.isComposing || searchResults.hidden)
@@ -1052,17 +1113,17 @@ function wireSearchResultsHitListKeyboard(searchResults, searchInput) {
         if (idx < 0)
             return;
         if (e.key === "ArrowDown" && idx < hits.length - 1) {
-            hits[idx + 1].focus({ preventScroll: true });
+            focusListRowAndReveal(hits[idx + 1]);
             e.preventDefault();
             return;
         }
         if (e.key === "ArrowUp") {
             if (idx > 0) {
-                hits[idx - 1].focus({ preventScroll: true });
+                focusListRowAndReveal(hits[idx - 1]);
                 e.preventDefault();
                 return;
             }
-            searchInput.focus({ preventScroll: true });
+            focusListRowAndReveal(searchInput);
             e.preventDefault();
         }
     });
@@ -1076,7 +1137,7 @@ function wireSearchInputKeyboard(searchInput, searchResults, actions) {
             if (!searchResults.hidden) {
                 const hits = listSearchHitButtons(searchResults);
                 if (hits.length > 0 && document.activeElement === searchInput) {
-                    hits[0].focus({ preventScroll: true });
+                    focusListRowAndReveal(hits[0]);
                     e.preventDefault();
                     return;
                 }
@@ -2262,7 +2323,34 @@ function focusDocumentedFilesFilterInput() {
     const el = document.getElementById("documented-files-filter");
     if (!(el instanceof HTMLInputElement))
         return;
-    el.focus({ preventScroll: true });
+    focusListRowAndReveal(el);
+}
+function focusDocumentedFilesHubSummaryIfPresent(hub) {
+    const sum = hub.querySelector("summary");
+    if (sum instanceof HTMLElement)
+        sum.focus({ preventScroll: true });
+}
+/** Escape to close; pointer outside `#documented-files-hub` to close (capture). */
+function wireDocumentedFilesHubDismissalHandlers(hub) {
+    function onEscape(ev) {
+        if (!hub.open || ev.key !== "Escape")
+            return;
+        ev.preventDefault();
+        hub.open = false;
+        focusDocumentedFilesHubSummaryIfPresent(hub);
+    }
+    document.addEventListener("keydown", onEscape, true);
+    document.addEventListener("pointerdown", (ev) => {
+        if (!hub.open)
+            return;
+        const t = ev.target;
+        if (!(t instanceof Node))
+            return;
+        if (hub.contains(t))
+            return;
+        hub.open = false;
+        focusDocumentedFilesHubSummaryIfPresent(hub);
+    }, true);
 }
 function wireDocumentedFilesTree() {
     const hub = document.getElementById("documented-files-hub");
@@ -2313,16 +2401,7 @@ function wireDocumentedFilesTree() {
             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);
+    wireDocumentedFilesHubDismissalHandlers(detailsHub);
     treeMount.addEventListener("keydown", (e) => {
         if (!detailsHub.open || e.isComposing)
             return;
@@ -2337,19 +2416,19 @@ function wireDocumentedFilesTree() {
             return;
         if (e.key === "ArrowDown") {
             if (idx < links.length - 1) {
-                links[idx + 1].focus({ preventScroll: true });
+                focusListRowAndReveal(links[idx + 1]);
                 e.preventDefault();
             }
             return;
         }
         if (e.key === "ArrowUp") {
             if (idx > 0) {
-                links[idx - 1].focus({ preventScroll: true });
+                focusListRowAndReveal(links[idx - 1]);
                 e.preventDefault();
                 return;
             }
             if (filterInput instanceof HTMLInputElement) {
-                filterInput.focus({ preventScroll: true });
+                focusListRowAndReveal(filterInput);
                 e.preventDefault();
             }
         }
@@ -2366,7 +2445,7 @@ function wireDocumentedFilesTree() {
             const links = listDocumentedTreeFileLinks(treeMount);
             if (links.length === 0)
                 return;
-            links[0].focus({ preventScroll: true });
+            focusListRowAndReveal(links[0]);
             e.preventDefault();
         });
     }
@@ -2411,6 +2490,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;
 }
@@ -2634,6 +2745,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();
@@ -2662,6 +2774,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() {
@@ -2688,6 +2803,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") {
@@ -2714,49 +2830,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;
@@ -3687,6 +3818,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);