@commentray/render 0.0.5 → 0.0.6

package/dist/code-browser-client.js

@@ -1,11 +1,23 @@
 import { FuzzySearcher, PrefixSearcher, Query, SearcherFactory, SubstringSearcher, } from "@m31coding/fuzzy-search";
+import { activeBlockIdForViewport, clampViewportYToGutterLocal, codeLineDomIndex0, gutterRayBezierPaths, sortBlockLinksBySource, } from "./code-browser-block-rays.js";
 import { mirroredScrollTop, pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./code-browser-scroll-sync.js";
 import { decodeBase64Utf8 } from "./code-browser-encoding.js";
 import { readEmbeddedRawB64Strings } from "./code-browser-embedded-payload.js";
-import { escapeHtmlHighlightingSearchTokens, findOrderedTokenSpans, lineAtIndex, offsetToLineIndex, } from "./code-browser-search.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 { readWebStorageItem, writeWebStorageItem } from "./code-browser-web-storage.js";
-function tokenizeQuery(q) {
-    return q.trim().split(/\s+/).filter(Boolean);
+function runMermaidOnFreshDocNodes(docBody) {
+    if (typeof globalThis.location !== "undefined" && globalThis.location.protocol === "file:")
+        return;
+    const nodes = docBody.querySelectorAll(".mermaid");
+    if (nodes.length === 0)
+        return;
+    const m = globalThis
+        .commentrayMermaid;
+    if (!m)
+        return;
+    const list = Array.from(nodes);
+    void m.run({ nodes: list }).catch(() => { });
 }
 function clamp(n, lo, hi) {
     return Math.max(lo, Math.min(hi, n));
@@ -154,6 +166,35 @@ function searchResultsInnerHtml(scope, combined, tokens, ctx) {
     }
     return buf.join("");
 }
+function emptyBrowsePreviewHint(scope, rowCount, totalUnique, usedIndexFallback) {
+    if (scope === "full") {
+        return "Documented source for this page. Type to search.";
+    }
+    if (usedIndexFallback) {
+        return "Documented source on this page. Type to search the index when it is available.";
+    }
+    if (totalUnique > rowCount) {
+        return `Indexed source files (${String(rowCount)} of ${String(totalUnique)} shown). Type to search.`;
+    }
+    return `Indexed source files (${String(totalUnique)}). Type to search.`;
+}
+function emptySearchBrowsePreviewInnerHtml(hint, rows, ctx) {
+    const tokens = [];
+    const buf = [`<div class="hint">${escapeHtmlText(hint)}</div>`];
+    const hits = rows.map((r, i) => ({
+        kind: "path",
+        line: i,
+        text: r.sourcePath,
+        score: 1000,
+        source: "ordered",
+        spPath: r.sourcePath,
+        crPath: r.commentrayPath,
+    }));
+    for (const h of hits) {
+        buf.push(searchHitButtonHtml(h, tokens, ctx));
+    }
+    return buf.join("");
+}
 function scrollDocToMarkdownLine0(docScrollEl, line0, mdLineCount) {
     const el = docScrollEl.querySelector(`#commentray-md-line-${String(line0)}`);
     if (el instanceof HTMLElement) {
@@ -169,22 +210,19 @@ function scrollDocToMarkdownLine0(docScrollEl, line0, mdLineCount) {
     const maxScroll = docScrollEl.scrollHeight - docScrollEl.clientHeight;
     docScrollEl.scrollTo({ top: ratio * Math.max(0, maxScroll), behavior: "smooth" });
 }
-function openForeignPairBrowseOrGithub(pairs, commentrayPath, mdLine0) {
-    const p = pairs.find((x) => x.commentrayPath === commentrayPath);
-    if (!p)
-        return;
-    if (p.staticBrowseUrl?.trim()) {
-        const u = new URL(p.staticBrowseUrl.trim(), globalThis.location.href);
+function navigateToDocumentedPair(pair, mdLine0) {
+    if (pair.staticBrowseUrl?.trim()) {
+        const href = resolveStaticBrowseHref(pair.staticBrowseUrl.trim(), globalThis.location.pathname, globalThis.location.origin);
+        const u = new URL(href);
         if (mdLine0 !== null && mdLine0 >= 0)
             u.hash = `commentray-md-line-${String(mdLine0)}`;
-        globalThis.open(u.toString(), "_blank", "noopener,noreferrer");
+        globalThis.location.assign(u.toString());
         return;
     }
-    if (p.commentrayOnGithub) {
-        const url = mdLine0 !== null && mdLine0 >= 0
-            ? `${p.commentrayOnGithub}#L${String(mdLine0 + 1)}`
-            : p.commentrayOnGithub;
-        globalThis.open(url, "_blank", "noopener,noreferrer");
+    const gh = (pair.commentrayOnGithub ?? "").trim();
+    if (gh.length > 0) {
+        const url = mdLine0 !== null && mdLine0 >= 0 ? `${gh}#L${String(mdLine0 + 1)}` : gh;
+        globalThis.location.assign(url);
     }
 }
 function readSearchScopeFromShell(shell) {
@@ -243,18 +281,25 @@ function scrollCodeHitToView(line) {
         el.scrollIntoView({ block: "nearest", behavior: "smooth" });
 }
 function handlePathSearchHit(button, deps) {
-    const cr = (button.getAttribute("data-cr-path")?.trim() ?? "").trim();
-    const curCr = deps.mutable.commentrayPathLabel.trim();
-    const isCurrentPair = cr.length === 0 || cr === curCr;
-    if (isCurrentPair) {
+    const hitCr = (button.getAttribute("data-cr-path") ?? "").trim();
+    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" });
         return;
     }
-    openForeignPairBrowseOrGithub(deps.mutable.documentedPairs, cr, null);
+    if (pair)
+        navigateToDocumentedPair(pair, null);
 }
 function handleMdSearchHit(line, crHit, deps) {
-    if (crHit.length > 0 && crHit !== deps.mutable.commentrayPathLabel) {
-        openForeignPairBrowseOrGithub(deps.mutable.documentedPairs, crHit, line);
+    const curCr = deps.mutable.commentrayPathLabel.trim();
+    const cr = crHit.trim();
+    if (cr.length > 0 && normPosixPath(cr) !== normPosixPath(curCr)) {
+        const pair = findDocumentedPair(deps.mutable.documentedPairs, cr, "");
+        if (pair) {
+            navigateToDocumentedPair(pair, line);
+            return;
+        }
         return;
     }
     scrollDocToMarkdownLine0(deps.docScrollEl, line, deps.mutable.mdLines.length);
@@ -273,6 +318,36 @@ function handleSearchHitButtonClick(button, deps) {
     }
     handleMdSearchHit(line, crHit, deps);
 }
+/** Empty query + ArrowDown: browse preview HTML, or null when there is nothing to show. */
+function emptyBrowsePreviewInnerHtml(scope, filePathLabel, mutable) {
+    const hitCtx = {
+        currentCommentrayPath: mutable.commentrayPathLabel,
+        currentSourcePath: filePathLabel,
+    };
+    if (scope === "full") {
+        const sp = filePathLabel.trim();
+        if (sp.length === 0)
+            return null;
+        const rows = [
+            { sourcePath: sp, commentrayPath: mutable.commentrayPathLabel.trim() },
+        ];
+        const hint = emptyBrowsePreviewHint("full", rows.length, rows.length, false);
+        return emptySearchBrowsePreviewInnerHtml(hint, rows, hitCtx);
+    }
+    const { rows, totalUnique } = uniqueSourceFilePreviewRows(mutable.documentedPairs);
+    if (rows.length > 0) {
+        const hint = emptyBrowsePreviewHint("commentray-and-paths", rows.length, totalUnique, false);
+        return emptySearchBrowsePreviewInnerHtml(hint, rows, hitCtx);
+    }
+    const sp = filePathLabel.trim();
+    if (sp.length === 0)
+        return null;
+    const fb = [
+        { sourcePath: sp, commentrayPath: mutable.commentrayPathLabel.trim() },
+    ];
+    const hint = emptyBrowsePreviewHint("commentray-and-paths", fb.length, fb.length, true);
+    return emptySearchBrowsePreviewInnerHtml(hint, fb, hitCtx);
+}
 function wireSearchUi(ctx) {
     const { scope, filePathLabel, mutable, rawCode, searchInput, searchClear, searchResults, docScrollEl, } = ctx;
     let debounceTimer;
@@ -283,6 +358,13 @@ function wireSearchUi(ctx) {
         searchResults.innerHTML = "";
         searchResults.hidden = true;
     }
+    function renderEmptyBrowsePreview() {
+        const html = emptyBrowsePreviewInnerHtml(scope, filePathLabel, mutable);
+        if (html === null)
+            return;
+        searchResults.hidden = false;
+        searchResults.innerHTML = html;
+    }
     function runSearch() {
         const tokens = tokenizeQuery(searchInput.value);
         if (tokens.length === 0) {
@@ -308,7 +390,7 @@ function wireSearchUi(ctx) {
             currentSourcePath: filePathLabel,
         });
     }
-    const hitClickDeps = { mutable, docScrollEl };
+    const hitClickDeps = { mutable, docScrollEl, filePathLabel };
     searchResults.addEventListener("click", (ev) => {
         const hit = findSearchHitButton(ev.target, searchResults);
         if (!hit)
@@ -319,6 +401,14 @@ function wireSearchUi(ctx) {
         clearTimeout(debounceTimer);
         debounceTimer = setTimeout(runSearch, 200);
     });
+    searchInput.addEventListener("keydown", (e) => {
+        if (e.key !== "ArrowDown")
+            return;
+        if (tokenizeQuery(searchInput.value).length > 0)
+            return;
+        renderEmptyBrowsePreview();
+        e.preventDefault();
+    });
     searchClear.addEventListener("click", clearSearch);
     document.addEventListener("keydown", (e) => {
         if (e.key !== "Escape")
@@ -477,15 +567,151 @@ function wireProportionalScrollSync(codePane, docPane) {
         codePane.scrollTop = mirroredScrollTop(docPane.scrollTop, docPane.scrollHeight, docPane.clientHeight, codePane.scrollHeight, codePane.clientHeight);
     });
 }
+function centerYInViewport(el) {
+    const r = el.getBoundingClientRect();
+    return (r.top + r.bottom) / 2;
+}
+/**
+ * Vertical anchor for gutter rays on the source side. Must match the **numbered row** the reader
+ * sees: the full `.code-line` row (line number + highlighted code) shares one grid row with
+ * aligned line-heights. Measuring only `pre code` can shift Y (hljs spans, sub-pixel layout) so
+ * rays sit above the line labels; the row’s geometric center tracks `lines:a-b` anchors reliably.
+ */
+function codeLineHighlightCenterYViewport(lineEl) {
+    return centerYInViewport(lineEl);
+}
+function commentaryBandEndYViewport(docScrollEl, next, docTop) {
+    if (next) {
+        const nextEl = document.getElementById(`commentray-block-${next.id}`);
+        return nextEl ? nextEl.getBoundingClientRect().top - 3 : centerYInViewport(docTop);
+    }
+    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);
+    return bottom;
+}
+function subscribeBlockRayRedraw(gutter, codePane, docScrollEl, scheduleDraw) {
+    const onScrollOrResize = () => scheduleDraw();
+    codePane.addEventListener("scroll", onScrollOrResize, { passive: true });
+    docScrollEl.addEventListener("scroll", onScrollOrResize, { passive: true });
+    globalThis.addEventListener("resize", onScrollOrResize);
+    const ro = new ResizeObserver(onScrollOrResize);
+    ro.observe(gutter);
+    ro.observe(codePane);
+    ro.observe(docScrollEl);
+    const shell = gutter.parentElement;
+    if (shell)
+        ro.observe(shell);
+}
+function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based) {
+    const links = getLinks();
+    const sorted = sortBlockLinksBySource(links);
+    const gutterRect = gutter.getBoundingClientRect();
+    const w = gutterRect.width;
+    const h = gutterRect.height;
+    if (w <= 0 || h <= 0 || sorted.length === 0) {
+        svg.replaceChildren();
+        return;
+    }
+    const activeId = activeBlockIdForViewport(links, probeTopSourceLine1Based());
+    svg.setAttribute("viewBox", `0 0 ${String(w)} ${String(h)}`);
+    svg.setAttribute("preserveAspectRatio", "none");
+    const parts = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const link = sorted[i];
+        if (!link)
+            continue;
+        const next = sorted[i + 1];
+        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 docTop = document.getElementById(`commentray-block-${link.id}`);
+        if (!codeTop || !codeBot || !docTop)
+            continue;
+        const docEndYViewport = commentaryBandEndYViewport(docScrollEl, next, docTop);
+        const yCodeTop = codeLineHighlightCenterYViewport(codeTop);
+        const yCodeBot = codeLineHighlightCenterYViewport(codeBot);
+        const yDocTop = docTop.getBoundingClientRect().top + 2;
+        const yDocEnd = Math.max(docEndYViewport, yDocTop + 4);
+        const c0 = clampViewportYToGutterLocal(yCodeTop, gutterRect.top, h);
+        const c1 = clampViewportYToGutterLocal(yDocTop, gutterRect.top, h);
+        const c2 = clampViewportYToGutterLocal(yCodeBot, gutterRect.top, h);
+        const c3 = clampViewportYToGutterLocal(yDocEnd, gutterRect.top, h);
+        const strokeClass = link.id === activeId ? "gutter__rays-path gutter__rays-path--active" : "gutter__rays-path";
+        const trailClass = `${strokeClass} gutter__rays-path--trail`;
+        const topPaths = gutterRayBezierPaths(0, c0.y, w, c1.y, {
+            tension: 0.38,
+            clipStart: c0.clipped,
+            clipEnd: c1.clipped,
+        });
+        const botPaths = gutterRayBezierPaths(0, c2.y, w, c3.y, {
+            tension: 0.38,
+            clipStart: c2.clipped,
+            clipEnd: c3.clipped,
+        });
+        const topExtra = topPaths.dotted ? `<path class="${trailClass}" d="${topPaths.dotted}" />` : "";
+        const botExtra = botPaths.dotted ? `<path class="${trailClass}" d="${botPaths.dotted}" />` : "";
+        parts.push(`<g class="gutter__rays-block" data-commentray-block="${escapeHtmlText(link.id)}">` +
+            `<path class="${strokeClass}" d="${topPaths.solid}" />` +
+            topExtra +
+            `<path class="${strokeClass}" d="${botPaths.solid}" />` +
+            botExtra +
+            `</g>`);
+    }
+    svg.innerHTML = parts.join("");
+}
+/**
+ * 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.
+ */
+function wireBlockRayConnectors(args) {
+    const { gutter, codePane, docScrollEl, getLinks, probeTopSourceLine1Based } = args;
+    const svgNs = "http://www.w3.org/2000/svg";
+    const host = document.createElement("div");
+    host.className = "gutter__rays";
+    host.setAttribute("aria-hidden", "true");
+    const svg = document.createElementNS(svgNs, "svg");
+    host.appendChild(svg);
+    gutter.appendChild(host);
+    let raf = 0;
+    function scheduleDraw() {
+        if (raf !== 0)
+            return;
+        raf = globalThis.requestAnimationFrame(() => {
+            raf = 0;
+            drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based);
+        });
+    }
+    subscribeBlockRayRedraw(gutter, codePane, docScrollEl, scheduleDraw);
+    scheduleDraw();
+    /** First paint can report gutter height 0 before flex layout settles; redraw after layout. */
+    globalThis.requestAnimationFrame(() => {
+        scheduleDraw();
+        globalThis.requestAnimationFrame(scheduleDraw);
+    });
+}
 function isDocumentedPairNav(x) {
     if (typeof x !== "object" || x === null)
         return false;
     const o = x;
-    return (typeof o.sourcePath === "string" &&
-        typeof o.commentrayPath === "string" &&
-        typeof o.sourceOnGithub === "string" &&
-        typeof o.commentrayOnGithub === "string" &&
-        (o.staticBrowseUrl === undefined || typeof o.staticBrowseUrl === "string"));
+    if (typeof o.sourcePath !== "string" || typeof o.commentrayPath !== "string")
+        return false;
+    if (o.staticBrowseUrl !== undefined && typeof o.staticBrowseUrl !== "string")
+        return false;
+    const sg = o.sourceOnGithub;
+    const cg = o.commentrayOnGithub;
+    const hasSg = typeof sg === "string";
+    const hasCg = typeof cg === "string";
+    if (hasSg !== hasCg)
+        return false;
+    const browseOk = typeof o.staticBrowseUrl === "string" && o.staticBrowseUrl.trim().length > 0;
+    if (!browseOk && !hasSg)
+        return false;
+    return true;
 }
 function pairsFromJsonArray(raw) {
     const pairs = [];
@@ -497,27 +723,6 @@ function pairsFromJsonArray(raw) {
     }
     return pairs;
 }
-function pathRowsFromDocumentedPairs(pairs) {
-    const seen = new Set();
-    const out = [];
-    let line = 0;
-    for (const p of pairs) {
-        for (const seg of [p.sourcePath, p.commentrayPath]) {
-            const t = seg.trim();
-            if (!t || seen.has(t))
-                continue;
-            seen.add(t);
-            out.push({
-                kind: "path",
-                line: line++,
-                text: t,
-                spPath: p.sourcePath,
-                crPath: p.commentrayPath,
-            });
-        }
-    }
-    return out;
-}
 function commentrayLineRowFromNavJson(r) {
     if (r.kind !== "commentrayLine")
         return null;
@@ -612,6 +817,25 @@ function treeFileLinkLabel(pr, disambiguate) {
     const stem = companionDocStem(pr.commentrayPath);
     return stem !== "" && stem !== base ? `${base} · ${stem}` : base;
 }
+/** Prefer static hub browse page; optional SCM blob URL when the export has no `staticBrowseUrl`. */
+function treeFileLinkHref(pr) {
+    const browse = (pr.staticBrowseUrl ?? "").trim();
+    if (browse.length > 0) {
+        return resolveStaticBrowseHref(browse, globalThis.location.pathname, globalThis.location.origin);
+    }
+    const gh = (pr.commentrayOnGithub ?? "").trim();
+    return gh.length > 0 ? gh : "#";
+}
+function treeFileLinkTitle(pr) {
+    const browse = (pr.staticBrowseUrl ?? "").trim();
+    if (browse.length > 0) {
+        return `${pr.sourcePath} — open this pair in the site viewer`;
+    }
+    if ((pr.commentrayOnGithub ?? "").trim().length > 0) {
+        return `${pr.sourcePath} — open companion commentray on the repository host`;
+    }
+    return pr.sourcePath;
+}
 function renderDocumentedTreeHtml(node) {
     const keys = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
     if (keys.length === 0)
@@ -629,19 +853,23 @@ function renderDocumentedTreeHtml(node) {
             const multi = ch.pairs.length > 1;
             for (const pr of ch.pairs) {
                 const label = escapeHtmlText(treeFileLinkLabel(pr, multi));
-                const title = escapeHtmlText(`${pr.sourcePath} — open companion on GitHub`);
+                const title = escapeHtmlText(treeFileLinkTitle(pr));
+                const href = escapeHtmlText(treeFileLinkHref(pr));
+                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="${escapeHtmlText(pr.commentrayOnGithub)}" target="_blank" rel="noopener noreferrer" title="${title}">${label}</a>` +
+                    `<a class="tree-file-link" href="${href}"${external} title="${title}">${label}</a>` +
                     `</div></li>`);
             }
         }
     }
     return `<ul>${lis.join("")}</ul>`;
 }
-function renderDocumentedPairsIntoHost(treeHost, pairs) {
+function renderDocumentedPairsIntoHost(treeHost, pairs, emptyBecauseFilter) {
     if (pairs.length === 0) {
-        treeHost.innerHTML =
-            '<p class="nav-rail__doc-hub-hint" role="status">No documented pairs in this export.</p>';
+        treeHost.innerHTML = emptyBecauseFilter
+            ? '<p class="nav-rail__doc-hub-hint" role="status">No paths match this filter.</p>'
+            : '<p class="nav-rail__doc-hub-hint" role="status">No documented pairs in this export.</p>';
         return;
     }
     const root = { children: new Map(), pairs: [] };
@@ -680,6 +908,7 @@ function loadDocumentedPairs(jsonUrl, embeddedB64) {
 function wireDocumentedFilesTree() {
     const hub = document.getElementById("documented-files-hub");
     const treeHost = document.getElementById("documented-files-tree");
+    const filterInput = document.getElementById("documented-files-filter");
     const shell = document.getElementById("shell");
     if (!(hub instanceof HTMLDetailsElement) || !(treeHost instanceof HTMLElement)) {
         return;
@@ -690,12 +919,23 @@ function wireDocumentedFilesTree() {
     if (jsonUrl.length === 0 && embeddedB64.length === 0)
         return;
     const ensureLoaded = loadDocumentedPairs(jsonUrl, embeddedB64);
+    let cachedPairs = null;
+    function applyFilterAndRender() {
+        if (cachedPairs === null)
+            return;
+        const q = filterInput instanceof HTMLInputElement ? filterInput.value : "";
+        const pairs = filterPairsByDocumentedTreeQuery(cachedPairs, q);
+        const filterActive = q.trim().length > 0;
+        renderDocumentedPairsIntoHost(treeMount, pairs, filterActive && cachedPairs.length > 0 && pairs.length === 0);
+    }
     async function hydrateTree() {
         try {
             const pairs = await ensureLoaded();
-            renderDocumentedPairsIntoHost(treeMount, pairs);
+            cachedPairs = pairs;
+            applyFilterAndRender();
         }
         catch {
+            cachedPairs = null;
             treeMount.innerHTML =
                 '<p class="nav-rail__doc-hub-hint" role="alert">Could not load the file list.</p>';
         }
@@ -705,6 +945,13 @@ function wireDocumentedFilesTree() {
             return;
         void hydrateTree();
     });
+    if (filterInput instanceof HTMLInputElement) {
+        filterInput.addEventListener("input", () => {
+            if (!hub.open || cachedPairs === null)
+                return;
+            applyFilterAndRender();
+        });
+    }
 }
 function wireSplitter(storageSplit, shell, codePane, gutter, initialPct) {
     let dragging = false;
@@ -805,7 +1052,46 @@ function initialCommentrayScopePathState(shell, scope, filePathLabel, commentray
         : [filePathLabel, commentrayPathLabel].filter((s) => s.trim().length > 0).join("\n");
     return { documentedPairs, pathRowsForOrdering, pathBlobWide };
 }
-function wireDualPaneNavSearchFetch(navSearchUrl, indexState, mutable, rebuildSearcher, searchInput) {
+/**
+ * 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.
+ */
+function mergeFetchedDocumentedPairsWithEmbeddedBrowse(embedded, fetched) {
+    if (fetched.length === 0)
+        return embedded;
+    if (embedded.length === 0)
+        return fetched;
+    const browseByCr = new Map();
+    for (const p of embedded) {
+        const b = (p.staticBrowseUrl ?? "").trim();
+        if (b.length === 0)
+            continue;
+        browseByCr.set(normPosixPath(p.commentrayPath), b);
+    }
+    return fetched.map((p) => {
+        const have = (p.staticBrowseUrl ?? "").trim();
+        if (have.length > 0)
+            return p;
+        const fromEmb = browseByCr.get(normPosixPath(p.commentrayPath));
+        if (fromEmb !== undefined && fromEmb.length > 0) {
+            return { ...p, staticBrowseUrl: fromEmb };
+        }
+        return p;
+    });
+}
+function resolvedNavSearchJsonUrl(shell) {
+    const raw = shell.getAttribute("data-nav-search-json-url")?.trim() ?? "";
+    if (raw.length === 0)
+        return "";
+    try {
+        return new URL(raw, globalThis.location.href).href;
+    }
+    catch {
+        return raw;
+    }
+}
+function wireDualPaneNavSearchFetch(shell, embeddedPairs, indexState, mutable, rebuildSearcher, searchInput) {
+    const navSearchUrl = resolvedNavSearchJsonUrl(shell);
     if (navSearchUrl.length === 0)
         return;
     void (async () => {
@@ -815,9 +1101,10 @@ function wireDualPaneNavSearchFetch(navSearchUrl, indexState, mutable, rebuildSe
                 return;
             const doc = (await res.json());
             const fetched = pairsFromJsonArray(doc.documentedPairs);
-            if (fetched.length > 0) {
-                indexState.documentedPairs = fetched;
-                mutable.documentedPairs = fetched;
+            const mergedPairs = mergeFetchedDocumentedPairsWithEmbeddedBrowse(embeddedPairs, fetched);
+            if (mergedPairs.length > 0) {
+                indexState.documentedPairs = mergedPairs;
+                mutable.documentedPairs = mergedPairs;
             }
             const nr = rowsFromNavSearchJson(doc);
             if (nr.length === 0)
@@ -837,10 +1124,9 @@ function wireDualPaneNavSearchFetch(navSearchUrl, indexState, mutable, rebuildSe
     })();
 }
 function wireDualPaneMultiAngleAndScroll(args) {
-    const { codePane, docScrollEl, docBody, shell, scrollLinks, multiPayload, mutable, rebuildSearcher, searchInput, searchResults, } = args;
-    const activeLinks = { current: scrollLinks };
+    const { codePane, docScrollEl, docBody, shell, scrollLinksRef, multiPayload, mutable, rebuildSearcher, searchInput, searchResults, } = args;
     if (multiPayload) {
-        wireBlockAwareScrollSync(codePane, docScrollEl, () => activeLinks.current);
+        wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
         const angleSel = document.getElementById("angle-select");
         if (angleSel && docBody) {
             angleSel.addEventListener("change", () => {
@@ -848,16 +1134,39 @@ function wireDualPaneMultiAngleAndScroll(args) {
                 if (!a)
                     return;
                 docBody.innerHTML = decodeBase64Utf8(a.docInnerHtmlB64);
+                runMermaidOnFreshDocNodes(docBody);
                 mutable.rawMd = decodeBase64Utf8(a.rawMdB64);
                 mutable.mdLines = mutable.rawMd.split("\n");
                 mutable.commentrayPathLabel = a.commentrayPathForSearch;
                 rebuildSearcher();
-                activeLinks.current = parseScrollBlockLinksFromShell(a.scrollBlockLinksB64);
+                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 gh = document.getElementById("toolbar-commentray-github");
-                if (gh instanceof HTMLAnchorElement && a.commentrayOnGithubUrl?.trim()) {
-                    gh.href = a.commentrayOnGithubUrl.trim();
+                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");
+                    }
+                    else {
+                        const ghu = a.commentrayOnGithubUrl?.trim();
+                        if (ghu) {
+                            gh.href = ghu;
+                            gh.target = "_blank";
+                            gh.setAttribute("rel", "noopener noreferrer");
+                        }
+                    }
                 }
                 searchInput.value = "";
                 searchResults.innerHTML = "";
@@ -866,8 +1175,8 @@ function wireDualPaneMultiAngleAndScroll(args) {
         }
         return;
     }
-    if (scrollLinks.length > 0) {
-        wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinks);
+    if (scrollLinksRef.current.length > 0) {
+        wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinksRef.current);
         return;
     }
     wireProportionalScrollSync(codePane, docScrollEl);
@@ -896,6 +1205,7 @@ function wireDualPaneCodeBrowser(shell, codePane) {
     const rawCode = decodeBase64Utf8(rawCodeB64);
     const rawMd = decodeBase64Utf8(rawMdB64);
     const scrollLinks = parseScrollBlockLinksFromShell(shell.getAttribute("data-scroll-block-links-b64") || "");
+    const scrollLinksRef = { current: scrollLinks };
     const { scope, filePathLabel, commentrayPathLabel } = readSearchScopeFromShell(shell);
     const pathInit = initialCommentrayScopePathState(shell, scope, filePathLabel, commentrayPathLabel);
     const indexState = {
@@ -934,8 +1244,7 @@ function wireDualPaneCodeBrowser(shell, codePane) {
         searchResults,
         docScrollEl,
     });
-    const navSearchUrl = shell.getAttribute("data-nav-search-json-url")?.trim() ?? "";
-    wireDualPaneNavSearchFetch(navSearchUrl, indexState, mutable, rebuildSearcher, searchInput);
+    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);
     codePane.style.flex = `0 0 ${pct}%`;
@@ -948,13 +1257,22 @@ function wireDualPaneCodeBrowser(shell, codePane) {
         docScrollEl,
         docBody,
         shell,
-        scrollLinks,
+        scrollLinksRef,
         multiPayload,
         mutable,
         rebuildSearcher,
         searchInput,
         searchResults,
     });
+    if (scrollLinksRef.current.length > 0) {
+        wireBlockRayConnectors({
+            gutter,
+            codePane,
+            docScrollEl,
+            getLinks: () => scrollLinksRef.current,
+            probeTopSourceLine1Based: () => probeCodeLine1FromViewport(codePane),
+        });
+    }
     wireDualPaneCommentrayLocationHash(docScrollEl, () => mutable.mdLines.length);
 }
 function main() {