@commentray/render 0.0.2 → 0.0.5

package/dist/code-browser-client.js

@@ -1,24 +1,15 @@
 import { FuzzySearcher, PrefixSearcher, Query, SearcherFactory, SubstringSearcher, } from "@m31coding/fuzzy-search";
-import { findOrderedTokenSpans, lineAtIndex, offsetToLineIndex } from "./code-browser-search.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 { readWebStorageItem, writeWebStorageItem } from "./code-browser-web-storage.js";
 function tokenizeQuery(q) {
     return q.trim().split(/\s+/).filter(Boolean);
 }
 function clamp(n, lo, hi) {
     return Math.max(lo, Math.min(hi, n));
 }
-function decodeB64(b64) {
-    try {
-        return decodeURIComponent(escape(atob(b64)));
-    }
-    catch {
-        try {
-            return atob(b64);
-        }
-        catch {
-            return "";
-        }
-    }
-}
 function escapeHtmlText(s) {
     return s
         .replace(/&/g, "&")
@@ -36,7 +27,9 @@ function snippet(s, maxLen) {
 function mergeHits(rows, max) {
     const byKey = new Map();
     for (const r of rows) {
-        const key = `${r.kind}:${r.line}`;
+        const key = r.kind === "path"
+            ? `path:${r.spPath ?? ""}|${r.crPath ?? ""}|${r.text.slice(0, 120)}`
+            : `${r.kind}:${r.line}:${r.crPath ?? ""}`;
         const prev = byKey.get(key);
         if (!prev || r.score > prev.score) {
             byKey.set(key, r);
@@ -82,12 +75,214 @@ function buildFuzzyHits(searcher, query, topN) {
             text: row.text,
             score: 100 + m.quality,
             source: "fuzzy",
+            crPath: row.crPath,
+            spPath: row.spPath,
         });
     }
     return out;
 }
+/** Ordered token matches per path row (keeps `spPath` / `crPath` for navigation). */
+function buildOrderedPathHitsFromRows(pathRows, tokens) {
+    if (tokens.length === 0)
+        return [];
+    const out = [];
+    for (const row of pathRows) {
+        if (row.kind !== "path")
+            continue;
+        const spans = findOrderedTokenSpans(row.text, tokens);
+        if (spans.length === 0)
+            continue;
+        out.push({
+            kind: "path",
+            line: row.line,
+            text: row.text,
+            score: 1000,
+            source: "ordered",
+            spPath: row.spPath,
+            crPath: row.crPath,
+        });
+    }
+    return out;
+}
+function computeMergedSearchHits(input) {
+    const { scope, filePathLabel, commentrayPathLabel, rawCode, rawMd, searcher, queryRaw, tokens, pathBlobWide, pathRowsForOrdering, } = input;
+    const pathBlob = (pathBlobWide && pathBlobWide.trim().length > 0
+        ? pathBlobWide.trim()
+        : [filePathLabel, commentrayPathLabel].filter((s) => s.trim().length > 0).join("\n")) || "";
+    const orderedCode = scope === "commentray-and-paths" ? [] : buildOrderedHits(rawCode, "code", tokens);
+    const orderedPath = scope === "commentray-and-paths" && pathRowsForOrdering && pathRowsForOrdering.length > 0
+        ? buildOrderedPathHitsFromRows(pathRowsForOrdering, tokens)
+        : scope === "commentray-and-paths" && pathBlob
+            ? buildOrderedHits(pathBlob, "path", tokens)
+            : [];
+    const orderedMd = buildOrderedHits(rawMd, "md", tokens);
+    const fuzzyHits = buildFuzzyHits(searcher, queryRaw, 60);
+    return mergeHits([...orderedCode, ...orderedPath, ...orderedMd, ...fuzzyHits], 80);
+}
+function searchScopeResultsHintIntro(scope) {
+    return scope === "commentray-and-paths"
+        ? "Paths + indexed commentray (this page + browse pages when built). Ordered tokens + fuzzy lines."
+        : "Whole source: whitespace tokens in order (may span lines). Per-line fuzzy ranking for typos.";
+}
+function searchHitMetaLabel(h, ctx) {
+    if (h.kind === "code")
+        return `Code L${h.line + 1}`;
+    if (h.kind === "path")
+        return `Path`;
+    const foreign = h.crPath && h.crPath !== ctx.currentCommentrayPath ? ` · ${h.crPath}` : "";
+    return `Commentray L${h.line + 1}${foreign}`;
+}
+function searchHitButtonHtml(h, tokens, ctx) {
+    const label = searchHitMetaLabel(h, ctx);
+    const tag = h.source === "ordered" ? "ordered" : "fuzzy";
+    const snippetHtml = escapeHtmlHighlightingSearchTokens(snippet(h.text, 320), tokens);
+    const crAttr = escapeHtmlText(h.kind === "md" ? (h.crPath ?? ctx.currentCommentrayPath) : (h.crPath ?? ""));
+    const spAttr = escapeHtmlText(h.kind === "md" ? (h.spPath ?? ctx.currentSourcePath) : (h.spPath ?? ""));
+    return (`<button type="button" class="hit" data-kind="${h.kind}" data-line="${String(h.line)}" data-cr-path="${crAttr}" data-sp-path="${spAttr}">` +
+        `<span class="meta">${escapeHtmlText(label)} <span class="src-tag">(${tag})</span></span>` +
+        `<div class="snippet">${snippetHtml}</div></button>`);
+}
+function searchResultsInnerHtml(scope, combined, tokens, ctx) {
+    if (combined.length === 0) {
+        return '<div class="hint">No matches. Try fewer tokens or looser spelling (fuzzy matches per line).</div>';
+    }
+    const hintIntro = searchScopeResultsHintIntro(scope);
+    const buf = [];
+    buf.push(`<div class="hint">${hintIntro} ${combined.length} hit(s).</div>`);
+    for (const h of combined) {
+        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) {
+        const top = el.getBoundingClientRect().top -
+            docScrollEl.getBoundingClientRect().top +
+            docScrollEl.scrollTop;
+        docScrollEl.scrollTo({ top: Math.max(0, top - 8), 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" });
+}
+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);
+        if (mdLine0 !== null && mdLine0 >= 0)
+            u.hash = `commentray-md-line-${String(mdLine0)}`;
+        globalThis.open(u.toString(), "_blank", "noopener,noreferrer");
+        return;
+    }
+    if (p.commentrayOnGithub) {
+        const url = mdLine0 !== null && mdLine0 >= 0
+            ? `${p.commentrayOnGithub}#L${String(mdLine0 + 1)}`
+            : p.commentrayOnGithub;
+        globalThis.open(url, "_blank", "noopener,noreferrer");
+    }
+}
+function readSearchScopeFromShell(shell) {
+    const scopeAttr = shell.getAttribute("data-search-scope") || "";
+    return {
+        scope: scopeAttr === "commentray-and-paths" ? "commentray-and-paths" : "full",
+        filePathLabel: shell.getAttribute("data-search-file-path") || "",
+        commentrayPathLabel: shell.getAttribute("data-search-commentray-path") || "",
+    };
+}
+function buildIndexedSearchRows(scope, rawCode, rawMd, filePathLabel, commentrayPathLabel) {
+    const mdLines = rawMd.split("\n");
+    const codeLines = rawCode.split("\n");
+    const pathRows = [];
+    if (scope === "commentray-and-paths") {
+        if (filePathLabel.trim()) {
+            pathRows.push({ kind: "path", line: pathRows.length, text: filePathLabel });
+        }
+        if (commentrayPathLabel.trim()) {
+            pathRows.push({ kind: "path", line: pathRows.length, text: commentrayPathLabel });
+        }
+    }
+    return [
+        ...(scope === "full"
+            ? codeLines.map((text, line) => ({ kind: "code", line, text }))
+            : []),
+        ...pathRows,
+        ...mdLines.map((text, line) => ({ kind: "md", line, text })),
+    ];
+}
+function indexSearchLineRows(rows) {
+    const searcher = SearcherFactory.createDefaultSearcher();
+    searcher.indexEntities(rows, (e) => {
+        if (e.kind === "md" && e.crPath)
+            return `md:${e.crPath}:${e.line}`;
+        if (e.kind === "path")
+            return `path:${e.spPath ?? ""}|${e.crPath ?? ""}|${e.line}|${e.text.slice(0, 120)}`;
+        return `${e.kind}:${e.line}`;
+    }, (e) => [e.text]);
+    return searcher;
+}
+function findSearchHitButton(leaf, searchResults) {
+    let t = leaf;
+    while (t) {
+        if (t.classList?.contains("hit"))
+            return t;
+        if (t === searchResults)
+            return null;
+        t = t.parentElement;
+    }
+    return null;
+}
+function scrollCodeHitToView(line) {
+    const el = document.getElementById(`code-line-${String(line)}`);
+    if (el)
+        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) {
+        deps.docScrollEl.scrollTo({ top: 0, behavior: "smooth" });
+        return;
+    }
+    openForeignPairBrowseOrGithub(deps.mutable.documentedPairs, cr, null);
+}
+function handleMdSearchHit(line, crHit, deps) {
+    if (crHit.length > 0 && crHit !== deps.mutable.commentrayPathLabel) {
+        openForeignPairBrowseOrGithub(deps.mutable.documentedPairs, crHit, line);
+        return;
+    }
+    scrollDocToMarkdownLine0(deps.docScrollEl, line, deps.mutable.mdLines.length);
+}
+function handleSearchHitButtonClick(button, deps) {
+    const kind = button.getAttribute("data-kind");
+    const line = parseInt(button.getAttribute("data-line") || "0", 10);
+    const crHit = button.getAttribute("data-cr-path")?.trim() ?? "";
+    if (kind === "code") {
+        scrollCodeHitToView(line);
+        return;
+    }
+    if (kind === "path") {
+        handlePathSearchHit(button, deps);
+        return;
+    }
+    handleMdSearchHit(line, crHit, deps);
+}
 function wireSearchUi(ctx) {
-    const { rawCode, rawMd, mdLines, searcher, searchInput, searchClear, searchResults, docPane } = ctx;
+    const { scope, filePathLabel, mutable, rawCode, searchInput, searchClear, searchResults, docScrollEl, } = ctx;
+    let debounceTimer;
+    function clearSearch() {
+        clearTimeout(debounceTimer);
+        debounceTimer = undefined;
+        searchInput.value = "";
+        searchResults.innerHTML = "";
+        searchResults.hidden = true;
+    }
     function runSearch() {
         const tokens = tokenizeQuery(searchInput.value);
         if (tokens.length === 0) {
@@ -95,78 +290,422 @@ function wireSearchUi(ctx) {
             searchResults.innerHTML = "";
             return;
         }
-        const orderedCode = buildOrderedHits(rawCode, "code", tokens);
-        const orderedMd = buildOrderedHits(rawMd, "md", tokens);
-        const fuzzyHits = buildFuzzyHits(searcher, searchInput.value, 60);
-        const combined = mergeHits([...orderedCode, ...orderedMd, ...fuzzyHits], 80);
+        const combined = computeMergedSearchHits({
+            scope,
+            filePathLabel,
+            commentrayPathLabel: mutable.commentrayPathLabel,
+            rawCode,
+            rawMd: mutable.rawMd,
+            searcher: mutable.searcher,
+            queryRaw: searchInput.value,
+            tokens,
+            pathBlobWide: mutable.pathBlobWide,
+            pathRowsForOrdering: mutable.pathRowsForOrdering.length > 0 ? mutable.pathRowsForOrdering : undefined,
+        });
         searchResults.hidden = false;
-        if (combined.length === 0) {
-            searchResults.innerHTML =
-                '<div class="hint">No matches. Try fewer tokens or looser spelling (fuzzy matches per line).</div>';
-            return;
-        }
-        const buf = [];
-        buf.push(`<div class="hint">Whole source: whitespace tokens in order (may span lines). Per-line fuzzy ranking for typos. ${combined.length} hit(s).</div>`);
-        for (const h of combined) {
-            const label = h.kind === "code" ? `Code L${h.line + 1}` : `Commentray L${h.line + 1}`;
-            const tag = h.source === "ordered" ? "ordered" : "fuzzy";
-            buf.push(`<button type="button" class="hit" data-kind="${h.kind}" data-line="${String(h.line)}">` +
-                `<span class="meta">${label} <span class="src-tag">(${tag})</span></span>` +
-                `<div class="snippet">${escapeHtmlText(snippet(h.text, 200))}</div></button>`);
-        }
-        searchResults.innerHTML = buf.join("");
+        searchResults.innerHTML = searchResultsInnerHtml(scope, combined, tokens, {
+            currentCommentrayPath: mutable.commentrayPathLabel,
+            currentSourcePath: filePathLabel,
+        });
     }
+    const hitClickDeps = { mutable, docScrollEl };
     searchResults.addEventListener("click", (ev) => {
-        let t = ev.target;
-        while (t && t !== searchResults && (!t.classList || !t.classList.contains("hit"))) {
-            t = t.parentElement;
-        }
-        if (!t || !t.classList || !t.classList.contains("hit"))
+        const hit = findSearchHitButton(ev.target, searchResults);
+        if (!hit)
             return;
-        const kind = t.getAttribute("data-kind");
-        const line = parseInt(t.getAttribute("data-line") || "0", 10);
-        if (kind === "code") {
-            const el = document.getElementById(`code-line-${String(line)}`);
-            if (el)
-                el.scrollIntoView({ block: "nearest", behavior: "smooth" });
-        }
-        else {
-            const total = mdLines.length;
-            if (total <= 0)
-                return;
-            const ratio = line / Math.max(1, total - 1);
-            const maxScroll = docPane.scrollHeight - docPane.clientHeight;
-            docPane.scrollTo({ top: ratio * Math.max(0, maxScroll), behavior: "smooth" });
-        }
+        handleSearchHitButtonClick(hit, hitClickDeps);
     });
-    let debounceTimer;
     searchInput.addEventListener("input", () => {
         clearTimeout(debounceTimer);
         debounceTimer = setTimeout(runSearch, 200);
     });
-    searchClear.addEventListener("click", () => {
-        clearTimeout(debounceTimer);
-        searchInput.value = "";
-        searchResults.innerHTML = "";
-        searchResults.hidden = true;
+    searchClear.addEventListener("click", clearSearch);
+    document.addEventListener("keydown", (e) => {
+        if (e.key !== "Escape")
+            return;
+        const query = searchInput.value.trim().length > 0;
+        const searchFocused = document.activeElement === searchInput;
+        const resultsOpen = !searchResults.hidden;
+        if (!query && !searchFocused && !resultsOpen)
+            return;
+        clearSearch();
+        if (searchFocused)
+            searchInput.blur();
+        e.preventDefault();
     });
 }
 function wireWrapToggle(storageWrap, codePane, wrapCb) {
-    const wrap = localStorage.getItem(storageWrap) === "1";
+    const wrap = readWebStorageItem(localStorage, storageWrap) === "1";
     wrapCb.checked = wrap;
     if (wrap)
         codePane.classList.add("wrap");
     wrapCb.addEventListener("change", () => {
         if (wrapCb.checked) {
             codePane.classList.add("wrap");
-            localStorage.setItem(storageWrap, "1");
+            writeWebStorageItem(localStorage, storageWrap, "1");
         }
         else {
             codePane.classList.remove("wrap");
-            localStorage.setItem(storageWrap, "0");
+            writeWebStorageItem(localStorage, storageWrap, "0");
         }
     });
 }
+function parseScrollBlockLinksFromShell(b64) {
+    const t = b64.trim();
+    if (!t)
+        return [];
+    try {
+        const raw = JSON.parse(decodeBase64Utf8(t));
+        if (!Array.isArray(raw))
+            return [];
+        const out = [];
+        for (const x of raw) {
+            if (typeof x !== "object" || x === null)
+                continue;
+            const o = x;
+            if (typeof o.id === "string" &&
+                typeof o.commentrayLine === "number" &&
+                typeof o.sourceStart === "number" &&
+                typeof o.sourceEnd === "number") {
+                out.push({
+                    id: o.id,
+                    commentrayLine: o.commentrayLine,
+                    sourceStart: o.sourceStart,
+                    sourceEnd: o.sourceEnd,
+                });
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function probeCodeLine1FromViewport(codePane) {
+    const y = codePane.getBoundingClientRect().top + 2;
+    const rows = codePane.querySelectorAll('[id^="code-line-"]');
+    for (const el of rows) {
+        const r = el.getBoundingClientRect();
+        if (r.bottom > y) {
+            const m = /^code-line-(\d+)$/.exec(el.id);
+            if (m)
+                return Number(m[1]) + 1;
+            return 1;
+        }
+    }
+    return rows.length > 0 ? rows.length : 1;
+}
+function probeCommentrayLine0FromDoc(docPane) {
+    const y = docPane.getBoundingClientRect().top + 2;
+    const anchors = docPane.querySelectorAll(".commentray-block-anchor");
+    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)
+            best = Number(lineAttr);
+        else
+            break;
+    }
+    return best;
+}
+function wireBidirectionalScroll(codePane, docPane, syncFromCode, syncFromDoc) {
+    let syncing = "none";
+    codePane.addEventListener("scroll", () => {
+        if (syncing === "doc")
+            return;
+        syncing = "code";
+        syncFromCode();
+        syncing = "none";
+    }, { passive: true });
+    docPane.addEventListener("scroll", () => {
+        if (syncing === "code")
+            return;
+        syncing = "doc";
+        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);
+            }
+        }
+    });
+}
+/** 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);
+    });
+}
+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"));
+}
+function pairsFromJsonArray(raw) {
+    const pairs = [];
+    if (!Array.isArray(raw))
+        return pairs;
+    for (const x of raw) {
+        if (isDocumentedPairNav(x))
+            pairs.push(x);
+    }
+    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;
+    if (typeof r.line !== "number" || typeof r.text !== "string")
+        return null;
+    const sp = typeof r.sourcePath === "string" ? r.sourcePath : "";
+    const cr = typeof r.commentrayPath === "string" ? r.commentrayPath : "";
+    return { kind: "md", line: r.line, text: r.text, spPath: sp, crPath: cr };
+}
+function pathRowFromNavJson(r, pathLine) {
+    if (r.kind !== "sourcePath" && r.kind !== "commentrayPath")
+        return null;
+    const sp = typeof r.sourcePath === "string" ? r.sourcePath : "";
+    const cr = typeof r.commentrayPath === "string" ? r.commentrayPath : "";
+    const text = r.kind === "sourcePath" ? sp : cr;
+    if (!text)
+        return null;
+    return { kind: "path", line: pathLine, text, spPath: sp, crPath: cr };
+}
+function rowsFromNavSearchJson(doc) {
+    if (!doc || typeof doc !== "object")
+        return [];
+    const rowsRaw = doc.rows;
+    if (!Array.isArray(rowsRaw))
+        return [];
+    const out = [];
+    let pathLine = 0;
+    for (const raw of rowsRaw) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const r = raw;
+        const mdRow = commentrayLineRowFromNavJson(r);
+        if (mdRow) {
+            out.push(mdRow);
+            continue;
+        }
+        const pathRow = pathRowFromNavJson(r, pathLine);
+        if (pathRow) {
+            out.push(pathRow);
+            pathLine += 1;
+        }
+    }
+    return out;
+}
+/** Offline-first: UTF-8 base64 JSON array produced by the static Pages build. */
+function parseDocumentedPairsFromEmbeddedB64(b64) {
+    const t = b64.trim();
+    if (t === "")
+        return [];
+    try {
+        const raw = JSON.parse(decodeBase64Utf8(t));
+        return pairsFromJsonArray(raw);
+    }
+    catch {
+        return [];
+    }
+}
+function insertSourcePathTrie(root, pair) {
+    const segments = pair.sourcePath.split("/").filter(Boolean);
+    if (segments.length === 0)
+        return;
+    let n = root;
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (seg === undefined)
+            continue;
+        if (!n.children.has(seg))
+            n.children.set(seg, { children: new Map(), pairs: [] });
+        const next = n.children.get(seg);
+        if (next === undefined)
+            return;
+        if (i === segments.length - 1)
+            next.pairs.push(pair);
+        n = next;
+    }
+}
+function pathBasenamePosixStyle(p) {
+    const t = p.replace(/\\/g, "/").replace(/\/+$/, "");
+    const i = t.lastIndexOf("/");
+    return i >= 0 ? t.slice(i + 1) : t;
+}
+/** Companion Markdown filename stem (e.g. `main` from `.../README.md/main.md`). */
+function companionDocStem(commentrayPath) {
+    const norm = commentrayPath.replace(/\\/g, "/").replace(/\/+$/, "");
+    const lastSeg = norm.split("/").filter(Boolean).at(-1) ?? "";
+    return lastSeg.replace(/\.md$/i, "");
+}
+function treeFileLinkLabel(pr, disambiguate) {
+    const base = pathBasenamePosixStyle(pr.sourcePath);
+    if (!disambiguate)
+        return base;
+    const stem = companionDocStem(pr.commentrayPath);
+    return stem !== "" && stem !== base ? `${base} · ${stem}` : base;
+}
+function renderDocumentedTreeHtml(node) {
+    const keys = [...node.children.keys()].sort((a, b) => a.localeCompare(b));
+    if (keys.length === 0)
+        return "";
+    const lis = [];
+    for (const name of keys) {
+        const ch = node.children.get(name);
+        if (ch === undefined)
+            continue;
+        if (ch.children.size > 0) {
+            const inner = renderDocumentedTreeHtml(ch);
+            lis.push(`<li><div class="tree-dir">${escapeHtmlText(name)}</div>${inner}</li>`);
+        }
+        if (ch.pairs.length > 0) {
+            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`);
+                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>` +
+                    `</div></li>`);
+            }
+        }
+    }
+    return `<ul>${lis.join("")}</ul>`;
+}
+function renderDocumentedPairsIntoHost(treeHost, pairs) {
+    if (pairs.length === 0) {
+        treeHost.innerHTML =
+            '<p class="nav-rail__doc-hub-hint" role="status">No documented pairs in this export.</p>';
+        return;
+    }
+    const root = { children: new Map(), pairs: [] };
+    for (const p of pairs)
+        insertSourcePathTrie(root, p);
+    treeHost.innerHTML = renderDocumentedTreeHtml(root);
+}
+function loadDocumentedPairs(jsonUrl, embeddedB64) {
+    let loaded = null;
+    let loadPromise = null;
+    return async () => {
+        if (loaded !== null)
+            return loaded;
+        if (loadPromise === null) {
+            loadPromise = (async () => {
+                if (embeddedB64.length > 0) {
+                    loaded = parseDocumentedPairsFromEmbeddedB64(embeddedB64);
+                    if (loaded.length > 0)
+                        return;
+                }
+                if (jsonUrl.length === 0) {
+                    loaded = [];
+                    return;
+                }
+                const res = await fetch(jsonUrl, { credentials: "same-origin" });
+                if (!res.ok)
+                    throw new Error(`nav json ${String(res.status)}`);
+                const body = (await res.json());
+                loaded = pairsFromJsonArray(body.documentedPairs);
+            })();
+        }
+        await loadPromise;
+        return loaded ?? [];
+    };
+}
+function wireDocumentedFilesTree() {
+    const hub = document.getElementById("documented-files-hub");
+    const treeHost = document.getElementById("documented-files-tree");
+    const shell = document.getElementById("shell");
+    if (!(hub instanceof HTMLDetailsElement) || !(treeHost instanceof HTMLElement)) {
+        return;
+    }
+    const treeMount = treeHost;
+    const jsonUrl = hub.getAttribute("data-nav-json-url")?.trim() ?? "";
+    const embeddedB64 = shell?.getAttribute("data-documented-pairs-b64")?.trim() ?? "";
+    if (jsonUrl.length === 0 && embeddedB64.length === 0)
+        return;
+    const ensureLoaded = loadDocumentedPairs(jsonUrl, embeddedB64);
+    async function hydrateTree() {
+        try {
+            const pairs = await ensureLoaded();
+            renderDocumentedPairsIntoHost(treeMount, pairs);
+        }
+        catch {
+            treeMount.innerHTML =
+                '<p class="nav-rail__doc-hub-hint" role="alert">Could not load the file list.</p>';
+        }
+    }
+    hub.addEventListener("toggle", () => {
+        if (!hub.open)
+            return;
+        void hydrateTree();
+    });
+}
 function wireSplitter(storageSplit, shell, codePane, gutter, initialPct) {
     let dragging = false;
     let lastPct = initialPct;
@@ -185,7 +724,7 @@ function wireSplitter(storageSplit, shell, codePane, gutter, initialPct) {
         window.removeEventListener("mouseup", stop);
         document.body.style.cursor = "";
         document.body.style.userSelect = "";
-        localStorage.setItem(storageSplit, String(lastPct));
+        writeWebStorageItem(localStorage, storageSplit, String(lastPct));
     }
     gutter.addEventListener("mousedown", (e) => {
         e.preventDefault();
@@ -196,52 +735,241 @@ function wireSplitter(storageSplit, shell, codePane, gutter, initialPct) {
         window.addEventListener("mouseup", stop);
     });
 }
-function main() {
-    const storageSplit = "commentray.codeCommentrayStatic.splitPct";
-    const storageWrap = "commentray.codeCommentrayStatic.wrap";
-    const shell = document.getElementById("shell");
-    const codePane = document.getElementById("code-pane");
+const STORAGE_SPLIT_PCT = "commentray.codeCommentrayStatic.splitPct";
+const STORAGE_WRAP_LINES = "commentray.codeCommentrayStatic.wrap";
+function wireStretchLayoutChrome(codePane) {
+    const wrapCb = document.getElementById("wrap-lines");
+    if (wrapCb) {
+        wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb);
+    }
+}
+function parseMultiAnglePayload(script) {
+    const t = script?.textContent?.trim() ?? "";
+    if (!t)
+        return null;
+    try {
+        const raw = JSON.parse(decodeBase64Utf8(t));
+        if (!raw || !Array.isArray(raw.angles) || raw.angles.length < 2)
+            return null;
+        for (const a of raw.angles) {
+            if (typeof a.id !== "string" || typeof a.docInnerHtmlB64 !== "string")
+                return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+function readDualPaneDomBundle() {
     const docPane = document.getElementById("doc-pane");
     const gutter = document.getElementById("gutter");
     const wrapCb = document.getElementById("wrap-lines");
     const searchInput = document.getElementById("search-q");
     const searchClear = document.getElementById("search-clear");
     const searchResults = document.getElementById("search-results");
-    if (!shell ||
-        !codePane ||
-        !docPane ||
-        !gutter ||
-        !wrapCb ||
-        !searchInput ||
-        !searchClear ||
-        !searchResults) {
-        return;
-    }
-    const rawCode = decodeB64(codePane.getAttribute("data-raw-code-b64") || "");
-    const rawMd = decodeB64(codePane.getAttribute("data-raw-md-b64") || "");
-    const mdLines = rawMd.split("\n");
-    const codeLines = rawCode.split("\n");
-    const lineRows = [
-        ...codeLines.map((text, line) => ({ kind: "code", line, text })),
-        ...mdLines.map((text, line) => ({ kind: "md", line, text })),
-    ];
-    const searcher = SearcherFactory.createDefaultSearcher();
-    searcher.indexEntities(lineRows, (e) => `${e.kind}:${e.line}`, (e) => [e.text]);
+    if (!docPane || !gutter || !wrapCb || !searchInput || !searchClear || !searchResults) {
+        return null;
+    }
+    const docBody = document.getElementById("doc-pane-body");
+    const docScrollEl = docBody instanceof HTMLElement ? docBody : docPane;
+    return { docBody, docScrollEl, gutter, wrapCb, searchInput, searchClear, searchResults };
+}
+function hubSearcherRowsForDualPane(args) {
+    const { scope, rawCode, filePathLabel, hubNavRows, pathRowsForOrdering, rawMd, commentrayPathLabel, } = args;
+    if (scope !== "commentray-and-paths") {
+        return buildIndexedSearchRows(scope, rawCode, rawMd, filePathLabel, commentrayPathLabel);
+    }
+    if (hubNavRows.length > 0)
+        return hubNavRows;
+    const pathPart = pathRowsForOrdering.length > 0
+        ? pathRowsForOrdering
+        : buildIndexedSearchRows(scope, rawCode, rawMd, filePathLabel, commentrayPathLabel).filter((r) => r.kind === "path");
+    const mdRows = rawMd.split("\n").map((text, line) => ({
+        kind: "md",
+        line,
+        text,
+        spPath: filePathLabel,
+        crPath: commentrayPathLabel,
+    }));
+    return [...pathPart, ...mdRows];
+}
+function initialCommentrayScopePathState(shell, scope, filePathLabel, commentrayPathLabel) {
+    if (scope !== "commentray-and-paths") {
+        return { documentedPairs: [], pathRowsForOrdering: [], pathBlobWide: "" };
+    }
+    const documentedPairs = parseDocumentedPairsFromEmbeddedB64(shell.getAttribute("data-documented-pairs-b64")?.trim() ?? "");
+    const pathRowsForOrdering = pathRowsFromDocumentedPairs(documentedPairs);
+    const pathBlobWide = pathRowsForOrdering.length > 0
+        ? pathRowsForOrdering.map((r) => r.text).join("\n")
+        : [filePathLabel, commentrayPathLabel].filter((s) => s.trim().length > 0).join("\n");
+    return { documentedPairs, pathRowsForOrdering, pathBlobWide };
+}
+function wireDualPaneNavSearchFetch(navSearchUrl, indexState, mutable, rebuildSearcher, searchInput) {
+    if (navSearchUrl.length === 0)
+        return;
+    void (async () => {
+        try {
+            const res = await fetch(navSearchUrl, { credentials: "same-origin" });
+            if (!res.ok)
+                return;
+            const doc = (await res.json());
+            const fetched = pairsFromJsonArray(doc.documentedPairs);
+            if (fetched.length > 0) {
+                indexState.documentedPairs = fetched;
+                mutable.documentedPairs = fetched;
+            }
+            const nr = rowsFromNavSearchJson(doc);
+            if (nr.length === 0)
+                return;
+            indexState.hubNavRows = nr;
+            indexState.pathRowsForOrdering = nr.filter((r) => r.kind === "path");
+            mutable.pathRowsForOrdering = indexState.pathRowsForOrdering;
+            mutable.pathBlobWide = indexState.pathRowsForOrdering.map((r) => r.text).join("\n");
+            rebuildSearcher();
+            if (searchInput.value.trim().length > 0) {
+                searchInput.dispatchEvent(new Event("input", { bubbles: true }));
+            }
+        }
+        catch {
+            /* keep embedded index */
+        }
+    })();
+}
+function wireDualPaneMultiAngleAndScroll(args) {
+    const { codePane, docScrollEl, docBody, shell, scrollLinks, multiPayload, mutable, rebuildSearcher, searchInput, searchResults, } = args;
+    const activeLinks = { current: scrollLinks };
+    if (multiPayload) {
+        wireBlockAwareScrollSync(codePane, docScrollEl, () => activeLinks.current);
+        const angleSel = document.getElementById("angle-select");
+        if (angleSel && docBody) {
+            angleSel.addEventListener("change", () => {
+                const a = multiPayload.angles.find((x) => x.id === angleSel.value);
+                if (!a)
+                    return;
+                docBody.innerHTML = decodeBase64Utf8(a.docInnerHtmlB64);
+                mutable.rawMd = decodeBase64Utf8(a.rawMdB64);
+                mutable.mdLines = mutable.rawMd.split("\n");
+                mutable.commentrayPathLabel = a.commentrayPathForSearch;
+                rebuildSearcher();
+                activeLinks.current = parseScrollBlockLinksFromShell(a.scrollBlockLinksB64);
+                shell.setAttribute("data-scroll-block-links-b64", a.scrollBlockLinksB64);
+                shell.setAttribute("data-search-commentray-path", a.commentrayPathForSearch);
+                const gh = document.getElementById("toolbar-commentray-github");
+                if (gh instanceof HTMLAnchorElement && a.commentrayOnGithubUrl?.trim()) {
+                    gh.href = a.commentrayOnGithubUrl.trim();
+                }
+                searchInput.value = "";
+                searchResults.innerHTML = "";
+                searchResults.hidden = true;
+            });
+        }
+        return;
+    }
+    if (scrollLinks.length > 0) {
+        wireBlockAwareScrollSync(codePane, docScrollEl, () => scrollLinks);
+        return;
+    }
+    wireProportionalScrollSync(codePane, docScrollEl);
+}
+function wireDualPaneCommentrayLocationHash(docScrollEl, mdLineCount) {
+    function applyCommentrayLocationHash() {
+        const m = /^commentray-md-line-(\d+)$/.exec(globalThis.location.hash.slice(1));
+        if (!m?.[1])
+            return;
+        const line0 = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(line0))
+            return;
+        scrollDocToMarkdownLine0(docScrollEl, line0, mdLineCount());
+    }
+    globalThis.addEventListener("hashchange", applyCommentrayLocationHash);
+    globalThis.requestAnimationFrame(() => {
+        globalThis.requestAnimationFrame(applyCommentrayLocationHash);
+    });
+}
+function wireDualPaneCodeBrowser(shell, codePane) {
+    const dom = readDualPaneDomBundle();
+    if (!dom)
+        return;
+    const { docBody, docScrollEl, gutter, wrapCb, searchInput, searchClear, searchResults } = dom;
+    const { rawCodeB64, rawMdB64 } = readEmbeddedRawB64Strings(shell, codePane);
+    const rawCode = decodeBase64Utf8(rawCodeB64);
+    const rawMd = decodeBase64Utf8(rawMdB64);
+    const scrollLinks = parseScrollBlockLinksFromShell(shell.getAttribute("data-scroll-block-links-b64") || "");
+    const { scope, filePathLabel, commentrayPathLabel } = readSearchScopeFromShell(shell);
+    const pathInit = initialCommentrayScopePathState(shell, scope, filePathLabel, commentrayPathLabel);
+    const indexState = {
+        hubNavRows: [],
+        documentedPairs: pathInit.documentedPairs,
+        pathRowsForOrdering: pathInit.pathRowsForOrdering,
+    };
+    const mutable = {
+        rawMd,
+        mdLines: rawMd.split("\n"),
+        commentrayPathLabel,
+        searcher: indexSearchLineRows([]),
+        pathBlobWide: pathInit.pathBlobWide,
+        pathRowsForOrdering: indexState.pathRowsForOrdering,
+        documentedPairs: indexState.documentedPairs,
+    };
+    function rebuildSearcher() {
+        mutable.searcher = indexSearchLineRows(hubSearcherRowsForDualPane({
+            scope,
+            rawCode,
+            filePathLabel,
+            hubNavRows: indexState.hubNavRows,
+            pathRowsForOrdering: indexState.pathRowsForOrdering,
+            rawMd: mutable.rawMd,
+            commentrayPathLabel: mutable.commentrayPathLabel,
+        }));
+    }
+    rebuildSearcher();
     wireSearchUi({
+        scope,
+        filePathLabel,
+        mutable,
         rawCode,
-        rawMd,
-        mdLines,
-        searcher,
         searchInput,
         searchClear,
         searchResults,
-        docPane,
+        docScrollEl,
     });
-    const pct0 = parseFloat(localStorage.getItem(storageSplit) || "50");
+    const navSearchUrl = shell.getAttribute("data-nav-search-json-url")?.trim() ?? "";
+    wireDualPaneNavSearchFetch(navSearchUrl, 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}%`;
-    wireWrapToggle(storageWrap, codePane, wrapCb);
-    wireSplitter(storageSplit, shell, codePane, gutter, pct);
+    wireWrapToggle(STORAGE_WRAP_LINES, codePane, wrapCb);
+    wireSplitter(STORAGE_SPLIT_PCT, shell, codePane, gutter, pct);
+    const multiScript = document.getElementById("commentray-multi-angle-b64");
+    const multiPayload = parseMultiAnglePayload(multiScript);
+    wireDualPaneMultiAngleAndScroll({
+        codePane,
+        docScrollEl,
+        docBody,
+        shell,
+        scrollLinks,
+        multiPayload,
+        mutable,
+        rebuildSearcher,
+        searchInput,
+        searchResults,
+    });
+    wireDualPaneCommentrayLocationHash(docScrollEl, () => mutable.mdLines.length);
+}
+function main() {
+    wireDocumentedFilesTree();
+    const shell = document.getElementById("shell");
+    const codePane = document.getElementById("code-pane");
+    if (!shell || !codePane) {
+        return;
+    }
+    const layout = shell.getAttribute("data-layout") || "dual";
+    if (layout === "stretch") {
+        wireStretchLayoutChrome(codePane);
+        return;
+    }
+    wireDualPaneCodeBrowser(shell, codePane);
 }
 if (document.readyState === "loading") {
     document.addEventListener("DOMContentLoaded", main);