@commentray/render 0.0.4 → 0.0.6

package/dist/code-browser.js

@@ -3,83 +3,137 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { MARKER_ID_BODY, buildBlockScrollLinks, } from "@commentray/core";
 import { tryBuildBlockStretchTableHtml } from "./block-stretch-layout.js";
+import { formatCommentrayBuiltAtLocal } from "./build-stamp.js";
 import { escapeHtml } from "./html-utils.js";
+import { renderHighlightedCodeLineRows } from "./highlighted-code-lines.js";
 import { mermaidRuntimeScriptHtml } from "./mermaid-runtime-html.js";
-import { renderFencedCode, renderMarkdownToHtml, } from "./markdown-pipeline.js";
+import { renderMarkdownToHtml } from "./markdown-pipeline.js";
+import { commentrayRenderVersion } from "./package-version.js";
 function renderGeneratorMetaHtml(label) {
     const t = label?.trim();
     if (!t)
         return "";
     return `<meta name="generator" content="${escapeHtml(t)}" />\n    `;
 }
-function extractPreCodeInner(html) {
-    const m = /<pre(?:\s[^>]*)?>\s*<code(?:\s[^>]*)?>([\s\S]*?)<\/code>\s*<\/pre>/i.exec(html.trim());
-    return m ? m[1] : escapeHtml(html);
+const META_DESCRIPTION_MAX_LEN = 320;
+function codeBrowserMetaDescription(opts, title) {
+    const custom = opts.metaDescription?.trim();
+    if (custom)
+        return custom.slice(0, META_DESCRIPTION_MAX_LEN);
+    const fallback = `${title} — Side-by-side source and commentray documentation.`;
+    return fallback.slice(0, META_DESCRIPTION_MAX_LEN);
+}
+function renderMetaDescriptionHtml(opts, title) {
+    const content = codeBrowserMetaDescription(opts, title);
+    return `<meta name="description" content="${escapeHtml(content)}" />\n    `;
 }
 /** Single capture: marker id (avoid a wrapping group around the whole comment — that shifted indices). */
 const BLOCK_MARKER_HTML_LINE = new RegExp(`^<!--\\s*commentray:block\\s+id=(${MARKER_ID_BODY})\\s*-->$`, "i");
-/** Inserts thin separator anchors after each `<!-- commentray:block … -->` line (optional index attrs for scroll sync). */
-function injectCommentrayBlockAnchors(markdown, links) {
-    const byId = links ? new Map(links.map((l) => [l.id, l])) : undefined;
-    return markdown
-        .split("\n")
-        .map((line) => {
-        const m = BLOCK_MARKER_HTML_LINE.exec(line);
-        if (!m?.[1])
-            return line;
-        const id = m[1];
-        const link = byId?.get(id);
-        const attrs = link !== undefined
-            ? ` data-source-start="${String(link.sourceStart)}" data-commentray-line="${String(link.commentrayLine)}"`
-            : "";
-        return `${line}\n\n<div id="commentray-block-${escapeHtml(id)}" class="commentray-block-anchor" aria-hidden="true"${attrs}></div>`;
-    })
-        .join("\n");
+function trimEndSpacesTabs(s) {
+    let end = s.length;
+    while (end > 0) {
+        const c = s[end - 1];
+        if (c !== " " && c !== "\t")
+            break;
+        end--;
+    }
+    return s.slice(0, end);
+}
+function isSetextUnderlineLine(line) {
+    const t = trimEndSpacesTabs(line);
+    return /^\s{0,3}=+\s*$/.test(t) || /^\s{0,3}-+\s*$/.test(t);
+}
+function isThematicBreakLine(line) {
+    const t = trimEndSpacesTabs(line);
+    return (/^\s{0,3}(?:\*[ \t]*){3,}\s*$/.test(t) ||
+        /^\s{0,3}(?:-[ \t]*){3,}\s*$/.test(t) ||
+        /^\s{0,3}(?:_[ \t]*){3,}\s*$/.test(t));
+}
+function parseFenceDelimiter(line) {
+    const t = trimEndSpacesTabs(line);
+    const m = /^(\s{0,3})(`{3,}|~{3,})(.*)$/.exec(t);
+    if (!m)
+        return null;
+    const run = m[2];
+    const head = run[0];
+    if (head !== "`" && head !== "~")
+        return null;
+    const ch = head === "`" ? "`" : "~";
+    return { ch, runLen: run.length, rest: m[3] ?? "" };
+}
+function isClosingFenceLine(info, open) {
+    if (info.ch !== open.ch || info.runLen < open.len)
+        return false;
+    return info.rest.trim() === "";
+}
+function lineAnchorHtml(mdLine0) {
+    const mdLine = String(mdLine0);
+    return `<span class="commentray-line-anchor" data-commentray-md-line="${mdLine}" id="commentray-md-line-${mdLine}" aria-hidden="true"></span>`;
+}
+function appendMdLineAnchorWhenAllowed(line, mdLine0) {
+    if (isSetextUnderlineLine(line) || isThematicBreakLine(line))
+        return line;
+    /** Blank lines must stay blank: a line that is only `<span …>` breaks CommonMark HTML / paragraph starts after block markers. */
+    if (line === "")
+        return "";
+    return `${line}${lineAnchorHtml(mdLine0)}`;
 }
-/** One highlighted row per source line so in-page search can scroll to a line. */
-async function renderCodeLineBlocks(code, language) {
-    const lines = code.split("\n");
-    const langAttr = escapeHtml(language);
-    const parts = [];
+/**
+ * Inserts per-line anchors for search / hash jumps and block separator anchors after each
+ * `<!-- commentray:block … -->` line (optional index attrs).
+ *
+ * Anchors are appended to the line when safe. A **leading** `<span>` breaks CommonMark block
+ * recognition (`#` headings, lists, thematic breaks, fences). Fenced code lines must not get a
+ * trailing anchor either (would corrupt fence delimiters or appear inside code).
+ */
+function injectCommentrayDocAnchors(markdown, links) {
+    const byId = links ? new Map(links.map((l) => [l.id, l])) : undefined;
+    const lines = markdown.split("\n");
+    let fence = null;
+    const out = [];
     for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] === "" ? " " : lines[i];
-        const fence = "```" + language + "\n" + line + "\n```\n";
-        const block = await renderFencedCode(fence);
-        const inner = extractPreCodeInner(block);
-        const num = i + 1;
-        parts.push(`<div class="code-line" id="code-line-${i}" data-line="${i}">` +
-            `<span class="ln" aria-hidden="true">${num}</span>` +
-            `<pre><code class="hljs language-${langAttr}">${inner}</code></pre>` +
-            `</div>`);
-    }
-    return parts.join("\n");
-}
-/** Split a repo-relative path into its directory prefix (with trailing slash) and basename. */
-function splitFilePath(p) {
-    const normalized = p.replaceAll("\\", "/").replace(/^\/+/, "");
-    const idx = normalized.lastIndexOf("/");
-    if (idx < 0)
-        return { dir: "", base: normalized };
-    return { dir: normalized.slice(0, idx + 1), base: normalized.slice(idx + 1) };
-}
-function renderFilePathLabel(filePath, fallbackTitle) {
-    const shown = (filePath ?? "").trim();
-    if (!shown) {
-        return `<strong class="file-path file-path--title">${escapeHtml(fallbackTitle)}</strong>`;
+        const line = lines[i];
+        const delim = parseFenceDelimiter(line);
+        if (fence) {
+            if (delim && isClosingFenceLine(delim, fence)) {
+                fence = null;
+                out.push(line);
+                continue;
+            }
+            out.push(line);
+            continue;
+        }
+        if (delim) {
+            fence = { ch: delim.ch, len: delim.runLen };
+            out.push(line);
+            continue;
+        }
+        const m = BLOCK_MARKER_HTML_LINE.exec(line);
+        if (m?.[1]) {
+            const id = m[1];
+            const link = byId?.get(id);
+            const attrs = link !== undefined
+                ? ` data-source-start="${String(link.sourceStart)}" data-commentray-line="${String(link.commentrayLine)}"`
+                : "";
+            /** One `push` with embedded `\n\n` merged poorly with `join("\\n")`; keep real blank lines around raw `<div>`. */
+            out.push(`${line}${lineAnchorHtml(i)}`);
+            out.push("");
+            out.push(`<div id="commentray-block-${escapeHtml(id)}" class="commentray-block-anchor" aria-hidden="true"${attrs}></div>`);
+            out.push("");
+            continue;
+        }
+        out.push(appendMdLineAnchorWhenAllowed(line, i));
     }
-    const { dir, base } = splitFilePath(shown);
-    const dirHtml = dir
-        ? `<span class="file-path__dir">${escapeHtml(dir)}</span>`
-        : `<span class="file-path__dir file-path__dir--root" title="Repository root">/ </span>`;
-    return (`<strong class="file-path" title="${escapeHtml(shown)}">` +
-        dirHtml +
-        `<span class="file-path__base">${escapeHtml(base)}</span>` +
-        `</strong>`);
+    return out.join("\n");
 }
 /** GitHub “mark” glyph (Octicons-style path), MIT-licensed silhouette. */
 const GITHUB_MARK_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="20" height="20" fill="currentColor" aria-hidden="true">' +
     '<path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/>' +
     "</svg>";
+/** Simple home glyph for same-site hub link (matches Octocat control size). */
+const SITE_HOME_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true">' +
+    '<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>' +
+    "</svg>";
 function safeExternalHttpUrl(url) {
     const t = url?.trim();
     if (!t)
@@ -88,22 +142,47 @@ function safeExternalHttpUrl(url) {
         return null;
     return t;
 }
-function buildToolbarEndHtml(githubRepoUrl, toolHomeUrl) {
+/** Allows relative static browse links (`./browse/…`) and `http(s):` URLs; rejects `javascript:` / `data:`. */
+function safeToolbarNavigationHref(url) {
+    const t = url?.trim();
+    if (!t)
+        return null;
+    if (/^(javascript|data):/i.test(t))
+        return null;
+    return t;
+}
+function buildToolbarSiteHubHtml(siteHubUrl) {
+    const site = safeToolbarNavigationHref(siteHubUrl);
+    if (!site)
+        return "";
+    const se = escapeHtml(site);
+    return `<a class="toolbar-github" href="${se}" aria-label="Documentation home" title="Back to this site (hub)">${SITE_HOME_SVG}</a>`;
+}
+function buildToolbarEndHtml(githubRepoUrl, toolHomeUrl, commentrayRenderSemver, siteHubUrl) {
+    const site = safeToolbarNavigationHref(siteHubUrl);
     const gh = safeExternalHttpUrl(githubRepoUrl);
     const tool = safeExternalHttpUrl(toolHomeUrl);
     const bits = [];
-    if (gh) {
+    if (!site && gh) {
         const he = escapeHtml(gh);
         bits.push(`<a class="toolbar-github" href="${he}" target="_blank" rel="noopener noreferrer" aria-label="View repository on GitHub" title="View repository on GitHub">${GITHUB_MARK_SVG}</a>`);
     }
     if (tool) {
         const te = escapeHtml(tool);
-        bits.push(`<span class="toolbar-attribution" role="note">Rendered with <a href="${te}" target="_blank" rel="noopener noreferrer">Commentray</a></span>`);
+        const ver = escapeHtml(commentrayRenderSemver);
+        bits.push(`<span class="toolbar-attribution" role="note">Rendered with <a href="${te}" target="_blank" rel="noopener noreferrer">Commentray</a> <span class="toolbar-attribution__version" translate="no">v${ver}</span></span>`);
     }
     if (bits.length === 0)
         return "";
     return `<div class="toolbar__end">${bits.join("")}</div>`;
 }
+function renderPageFooterHtml(builtAt) {
+    const iso = builtAt.toISOString();
+    const human = formatCommentrayBuiltAtLocal(builtAt);
+    return (`<footer class="app__footer" role="contentinfo">` +
+        `<p class="app__footer-line">HTML generated <time datetime="${escapeHtml(iso)}">${escapeHtml(human)}</time></p>` +
+        `</footer>`);
+}
 function renderRelatedGithubNavHtml(links) {
     if (links.length === 0)
         return "";
@@ -114,34 +193,57 @@ function renderRelatedGithubNavHtml(links) {
         `</nav>`);
 }
 function renderToolbarDocHubHtml(opts) {
-    const parts = [];
-    const src = safeExternalHttpUrl(opts.sourceOnGithubUrl);
-    const cr = safeExternalHttpUrl(opts.commentrayOnGithubUrl);
     const nav = opts.documentedNavJsonUrl?.trim();
     const hasEmbed = (opts.documentedPairsEmbeddedB64?.trim() ?? "").length > 0;
     const showDocumentedTree = Boolean(nav) || hasEmbed;
-    if (src) {
-        parts.push(`<a class="toolbar-blob-link" href="${escapeHtml(src)}" target="_blank" rel="noopener noreferrer">Source on GitHub</a>`);
-    }
-    if (cr) {
-        parts.push(`<a class="toolbar-blob-link" href="${escapeHtml(cr)}" target="_blank" rel="noopener noreferrer">Commentray on GitHub</a>`);
-    }
-    if (showDocumentedTree) {
-        const navAttr = nav ? escapeHtml(nav) : "";
-        parts.push(`<button type="button" class="toolbar-tree-toggle" id="documented-files-toggle" aria-expanded="false" aria-controls="documented-files-panel" data-nav-json-url="${navAttr}">Documented files</button>`);
-    }
-    const toolbarDocHubHtml = parts.length > 0
-        ? `<div class="toolbar-doc-hub">${parts.join('<span class="toolbar-doc-hub__sep" aria-hidden="true"> · </span>')}</div>`
-        : "";
-    const documentedPanelHtml = showDocumentedTree
-        ? `<div id="documented-files-panel" class="documented-files-panel" hidden>
-        <div class="documented-files-panel__inner">
-          <p class="documented-files-panel__hint">Indexed source ↔ commentray pairs (embedded for offline when available). Links open on GitHub.</p>
+    const toolbarDocHubHtml = "";
+    const navAttr = escapeHtml(nav ?? "");
+    const navRailDocumentedHtml = showDocumentedTree
+        ? `<details class="nav-rail__doc-hub" id="documented-files-hub" data-nav-json-url="${navAttr}">
+        <summary class="nav-rail__doc-hub-summary">Comment-rayed files</summary>
+        <div class="nav-rail__doc-hub-inner">
+          <div class="nav-rail__doc-hub-filter-row">
+            <label class="nav-rail__doc-hub-filter-label" for="documented-files-filter">Filter</label>
+            <input type="search" id="documented-files-filter" class="nav-rail__doc-hub-filter" placeholder="Filter by path…" autocomplete="off" spellcheck="false" />
+          </div>
           <div id="documented-files-tree" class="documented-files-tree" role="tree"></div>
         </div>
-      </div>`
+      </details>`
         : "";
-    return { toolbarDocHubHtml, documentedPanelHtml };
+    return { toolbarDocHubHtml, navRailDocumentedHtml };
+}
+function renderNavRailContextHtml(filePath, commentrayPath, opts) {
+    const fpRaw = (filePath ?? "").trim();
+    const crRaw = (commentrayPath ?? "").trim();
+    const srcUrl = safeExternalHttpUrl(opts?.sourceOnGithubUrl);
+    const crUrl = safeExternalHttpUrl(opts?.commentrayOnGithubUrl);
+    const browseForCr = safeToolbarNavigationHref(opts?.commentrayStaticBrowseUrl);
+    const srcGh = srcUrl !== null
+        ? `<a class="nav-rail__pair-gh" id="toolbar-source-github" href="${escapeHtml(srcUrl)}" target="_blank" rel="noopener noreferrer" aria-label="Source file on GitHub" title="Open source on GitHub">${GITHUB_MARK_SVG}</a>`
+        : "";
+    const crGh = browseForCr !== null
+        ? `<a class="nav-rail__pair-gh" id="toolbar-commentray-github" href="${escapeHtml(browseForCr)}" rel="noopener" aria-label="Open companion pair in the site viewer" title="Open on site">${GITHUB_MARK_SVG}</a>`
+        : crUrl !== null
+            ? `<a class="nav-rail__pair-gh" id="toolbar-commentray-github" href="${escapeHtml(crUrl)}" target="_blank" rel="noopener noreferrer" aria-label="Companion commentray on GitHub" title="Open companion Markdown on GitHub">${GITHUB_MARK_SVG}</a>`
+            : "";
+    if (fpRaw.length === 0 && crRaw.length === 0 && srcGh === "" && crGh === "") {
+        return "";
+    }
+    const fp = escapeHtml(fpRaw);
+    const cr = escapeHtml(crRaw);
+    const fpDisp = fpRaw.length > 0 ? fp : "—";
+    const crDisp = crRaw.length > 0 ? cr : "—";
+    return `<div class="nav-rail__context nav-rail__context--compact" aria-label="Current documentation pair">
+    <span class="nav-rail__pair">
+      <span class="nav-rail__pair-lab">Src</span>
+      <span class="nav-rail__pair-path" title="${fp}">${fpDisp}</span>${srcGh}
+    </span>
+    <span class="nav-rail__pair-sep" aria-hidden="true">·</span>
+    <span class="nav-rail__pair">
+      <span class="nav-rail__pair-lab">Doc</span>
+      <span class="nav-rail__pair-path nav-rail__pair-path--secondary" id="nav-rail-doc-path" title="${cr}">${crDisp}</span>${crGh}
+    </span>
+  </div>`;
 }
 /** IIFE produced by `npm run build -w @commentray/render` (esbuild of `code-browser-client.ts`). */
 function loadCodeBrowserClientBundle() {
@@ -156,17 +258,328 @@ function loadCodeBrowserClientBundle() {
     throw new Error("Missing code-browser-client.bundle.js. Run `npm run build -w @commentray/render` to bundle the browser client.");
 }
 const CODE_BROWSER_STYLES = `
-      :root { color-scheme: light dark; }
+      :root {
+        color-scheme: light dark;
+        --cr-control-h: 32px;
+        --cr-control-radius: 8px;
+        --cr-icon-inner: 18px;
+        --cr-label-caps-fs: 10px;
+        --cr-label-caps-track: 0.06em;
+        --cr-ui-fs: 12px;
+      }
       * { box-sizing: border-box; }
       body { margin: 0; font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif; }
+      .skip-link {
+        position: absolute;
+        left: -9999px;
+        top: 0;
+        z-index: 10000;
+        padding: 8px 16px;
+        margin: 0;
+        font: inherit;
+        font-size: 14px;
+        text-decoration: none;
+        border-radius: 8px;
+        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas);
+        background: Canvas;
+        color: CanvasText;
+      }
+      .skip-link:focus {
+        left: 12px;
+        top: 8px;
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .skip-link:focus:not(:focus-visible) {
+        left: -9999px;
+        top: 0;
+        outline: none;
+      }
+      .skip-link:focus-visible {
+        left: 12px;
+        top: 8px;
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .sr-only {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+      }
+      .app {
+        display: flex;
+        flex-direction: column;
+        align-items: stretch;
+        height: 100vh;
+        width: 100%;
+        overflow: hidden;
+      }
+      .app__chrome {
+        flex: 0 0 auto;
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+        padding: 8px 12px 10px;
+        border-bottom: 1px solid color-mix(in oklab, CanvasText 15%, Canvas);
+        background: color-mix(in oklab, CanvasText 4%, Canvas);
+        max-height: min(40vh, 420px);
+        min-height: 0;
+        overflow: auto;
+      }
+      .chrome__search-row {
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        gap: 10px;
+        flex-wrap: nowrap;
+      }
+      .chrome__search-row input[type="search"] {
+        flex: 1 1 auto;
+        min-width: 140px;
+        min-height: var(--cr-control-h);
+        padding: 0 12px;
+        font: inherit;
+        font-size: var(--cr-ui-fs);
+        line-height: 1.25;
+        border-radius: var(--cr-control-radius);
+        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas);
+        background: Canvas;
+        color: CanvasText;
+      }
+      .chrome__search-row #search-clear {
+        flex: 0 0 auto;
+        font: inherit;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        min-height: var(--cr-control-h);
+        padding: 0 16px;
+        border-radius: var(--cr-control-radius);
+        cursor: pointer;
+        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas);
+        background: color-mix(in oklab, CanvasText 6%, Canvas);
+        color: CanvasText;
+      }
+      .chrome__search-row input[type="search"]:focus-visible,
+      .chrome__search-row #search-clear:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .chrome__search-label {
+        flex: 0 0 auto;
+        white-space: nowrap;
+      }
+      .nav-rail__context--compact {
+        display: flex;
+        flex-direction: row;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 6px 10px;
+        padding: 5px 10px;
+        border-radius: var(--cr-control-radius);
+        border: 1px solid color-mix(in oklab, CanvasText 14%, Canvas);
+        background: Canvas;
+        font-size: var(--cr-ui-fs);
+        line-height: 1.3;
+      }
+      .nav-rail__pair {
+        display: inline-flex;
+        flex-direction: row;
+        align-items: center;
+        gap: 6px;
+        min-width: 0;
+        flex: 1 1 140px;
+        max-width: min(48%, 100%);
+      }
+      .nav-rail__pair-lab {
+        flex: 0 0 auto;
+        font-size: var(--cr-label-caps-fs);
+        font-weight: 700;
+        letter-spacing: var(--cr-label-caps-track);
+        text-transform: uppercase;
+        opacity: 0.72;
+      }
+      .nav-rail__pair-path {
+        flex: 1 1 auto;
+        min-width: 0;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
+        font-size: var(--cr-ui-fs);
+        color: CanvasText;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+      .nav-rail__pair-path--secondary { opacity: 0.88; }
+      .nav-rail__pair-sep {
+        flex: 0 0 auto;
+        opacity: 0.45;
+        user-select: none;
+        padding: 0 2px;
+      }
+      .nav-rail__pair-gh {
+        flex: 0 0 auto;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: var(--cr-control-h);
+        height: var(--cr-control-h);
+        border-radius: var(--cr-control-radius);
+        border: 1px solid color-mix(in oklab, CanvasText 20%, Canvas);
+        background: color-mix(in oklab, CanvasText 5%, Canvas);
+        color: CanvasText;
+      }
+      .nav-rail__pair-gh:hover {
+        background: color-mix(in oklab, CanvasText 10%, Canvas);
+      }
+      .nav-rail__pair-gh:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .nav-rail__pair-gh svg {
+        width: var(--cr-icon-inner);
+        height: var(--cr-icon-inner);
+        display: block;
+      }
+      .toolbar .nav-rail__context--compact {
+        border: 0;
+        background: transparent;
+        padding: 0;
+        flex: 1 1 200px;
+        min-width: 0;
+        max-width: none;
+        gap: 6px 10px;
+      }
+      .toolbar .nav-rail__pair {
+        flex: 1 1 auto;
+        min-width: 0;
+        max-width: min(44vw, 420px);
+      }
+      .nav-rail__search-label {
+        font-size: var(--cr-label-caps-fs);
+        font-weight: 700;
+        letter-spacing: var(--cr-label-caps-track);
+        text-transform: uppercase;
+        opacity: 0.78;
+      }
+      .nav-rail__search-hint {
+        margin: 0;
+        font-size: 11px;
+        line-height: 1.35;
+        opacity: 0.78;
+      }
+      .nav-rail__code {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
+        font-size: 10px;
+      }
+      .nav-rail__doc-hub {
+        position: relative;
+        flex: 0 0 auto;
+        align-self: center;
+        display: block;
+        border: 1px solid color-mix(in oklab, CanvasText 16%, Canvas);
+        border-radius: var(--cr-control-radius);
+        background: Canvas;
+        overflow: visible;
+      }
+      .nav-rail__doc-hub-summary {
+        cursor: pointer;
+        font-size: var(--cr-ui-fs);
+        font-weight: 600;
+        padding: 0 12px;
+        min-height: var(--cr-control-h);
+        display: inline-flex;
+        align-items: center;
+        box-sizing: border-box;
+        list-style: none;
+        user-select: none;
+        line-height: 1.25;
+      }
+      .nav-rail__doc-hub-summary::-webkit-details-marker { display: none; }
+      .nav-rail__doc-hub-inner {
+        position: absolute;
+        left: 0;
+        top: calc(100% + 4px);
+        z-index: 60;
+        min-width: min(280px, 78vw);
+        max-width: min(440px, 94vw);
+        max-height: min(52vh, 400px);
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+        overflow: hidden;
+        padding: 8px 10px;
+        font-size: 12px;
+        border: 1px solid color-mix(in oklab, CanvasText 16%, Canvas);
+        border-radius: 8px;
+        background: Canvas;
+        box-shadow: 0 8px 28px color-mix(in oklab, CanvasText 12%, transparent);
+      }
+      .nav-rail__doc-hub-filter-row {
+        flex: 0 0 auto;
+      }
+      .nav-rail__doc-hub-filter-label {
+        display: block;
+        font-size: var(--cr-label-caps-fs);
+        font-weight: 700;
+        letter-spacing: var(--cr-label-caps-track);
+        text-transform: uppercase;
+        opacity: 0.78;
+        margin-bottom: 4px;
+      }
+      .nav-rail__doc-hub-filter {
+        width: 100%;
+        box-sizing: border-box;
+        font: inherit;
+        font-size: 12px;
+        padding: 4px 8px;
+        border-radius: 6px;
+        border: 1px solid color-mix(in oklab, CanvasText 22%, Canvas);
+        background: color-mix(in oklab, CanvasText 4%, Canvas);
+        color: CanvasText;
+      }
+      .nav-rail__doc-hub-filter:focus {
+        outline: 2px solid color-mix(in oklab, CanvasText 40%, Canvas);
+        outline-offset: 1px;
+      }
+      .nav-rail__doc-hub-hint {
+        margin: 0 0 8px;
+        opacity: 0.78;
+        line-height: 1.4;
+        font-size: 12px;
+      }
+      .app__main {
+        flex: 1 1 auto;
+        min-width: 0;
+        min-height: 0;
+        display: flex;
+        flex-direction: column;
+      }
+      .app__footer {
+        flex: 0 0 auto;
+        padding: 6px 12px 10px;
+        border-top: 1px solid color-mix(in oklab, CanvasText 12%, Canvas);
+        background: color-mix(in oklab, CanvasText 3%, Canvas);
+        font-size: 11px;
+        line-height: 1.4;
+        color: color-mix(in oklab, CanvasText 72%, Canvas);
+      }
+      .app__footer-line { margin: 0; }
+      .app__footer time { font-variant-numeric: tabular-nums; }
       .toolbar {
+        position: relative;
         display: flex; flex-wrap: wrap; align-items: center; gap: 10px 14px; padding: 8px 12px;
         border-bottom: 1px solid color-mix(in oklab, CanvasText 18%, Canvas);
-        font-size: 13px; flex: 0 0 auto;
+        font-size: var(--cr-ui-fs);
+        flex: 0 0 auto;
       }
       .toolbar__main {
         display: flex; flex-wrap: wrap; align-items: center; gap: 10px 14px;
-        flex: 1 1 280px;
+        flex: 0 1 auto;
         min-width: 0;
       }
       .toolbar__end {
@@ -176,22 +589,49 @@ const CODE_BROWSER_STYLES = `
       }
       .toolbar-github {
         display: inline-flex; align-items: center; justify-content: center;
-        width: 34px; height: 34px; border-radius: 8px;
+        width: var(--cr-control-h);
+        height: var(--cr-control-h);
+        border-radius: var(--cr-control-radius);
         border: 1px solid color-mix(in oklab, CanvasText 22%, Canvas);
         background: color-mix(in oklab, CanvasText 6%, Canvas);
         color: CanvasText;
       }
+      .toolbar-github svg {
+        width: var(--cr-icon-inner);
+        height: var(--cr-icon-inner);
+        display: block;
+      }
       .toolbar-github:hover { background: color-mix(in oklab, CanvasText 11%, Canvas); }
       .toolbar-github:focus-visible { outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas); outline-offset: 2px; }
       .toolbar-attribution {
-        font-size: 11px; line-height: 1.35; opacity: 0.82; max-width: min(360px, 42vw);
-        text-align: right; color: color-mix(in oklab, CanvasText 88%, Canvas);
+        font-size: var(--cr-ui-fs);
+        line-height: 1.35;
+        opacity: 0.85;
+        max-width: min(360px, 42vw);
+        text-align: right;
+        color: color-mix(in oklab, CanvasText 88%, Canvas);
       }
       .toolbar-attribution a { color: inherit; font-weight: 600; text-decoration: underline; text-underline-offset: 2px; }
       .toolbar label { display: inline-flex; align-items: center; gap: 6px; cursor: pointer; user-select: none; }
+      .toolbar__main > label:has(#wrap-lines) {
+        margin: 0;
+        min-height: var(--cr-control-h);
+        padding: 0 12px 0 10px;
+        border-radius: var(--cr-control-radius);
+        border: 1px solid color-mix(in oklab, CanvasText 16%, Canvas);
+        background: color-mix(in oklab, CanvasText 4%, Canvas);
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        gap: 8px;
+      }
+      .toolbar label input:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
       .toolbar .file-path {
         font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
-        font-size: 13px; font-weight: 500;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
         display: inline-flex; align-items: baseline; gap: 0; margin-right: 4px;
         max-width: 60vw; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
       }
@@ -205,7 +645,9 @@ const CODE_BROWSER_STYLES = `
       .toolbar .file-path--title { font-weight: 600; }
       .toolbar-related {
         display: inline-flex; flex-wrap: wrap; align-items: baseline; gap: 6px 10px;
-        max-width: min(520px, 90vw); font-size: 12px; line-height: 1.35;
+        max-width: min(520px, 90vw);
+        font-size: var(--cr-ui-fs);
+        line-height: 1.35;
         color: color-mix(in oklab, CanvasText 88%, Canvas);
       }
       .toolbar-related__prefix { font-weight: 600; opacity: 0.85; white-space: nowrap; }
@@ -215,69 +657,82 @@ const CODE_BROWSER_STYLES = `
         word-break: break-word;
       }
       .toolbar-related__sep { opacity: 0.55; user-select: none; }
-      .toolbar-doc-hub {
-        display: inline-flex; flex-wrap: wrap; align-items: center; gap: 4px 8px;
-        font-size: 12px; line-height: 1.35;
-        color: color-mix(in oklab, CanvasText 88%, Canvas);
-      }
-      .toolbar-doc-hub__sep { opacity: 0.45; user-select: none; }
-      .toolbar-blob-link {
-        color: inherit; font-weight: 500; text-decoration: underline; text-underline-offset: 2px;
-        white-space: nowrap;
+      #documented-files-tree {
+        flex: 1 1 auto;
+        min-height: 0;
+        overflow: auto;
       }
-      .toolbar-tree-toggle {
-        font: inherit; font-size: 12px; font-weight: 600; padding: 3px 10px; border-radius: 6px; cursor: pointer;
-        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas);
-        background: color-mix(in oklab, CanvasText 6%, Canvas); color: CanvasText;
+      .documented-files-tree ul { list-style: none; margin: 0; padding-left: 12px; }
+      .documented-files-tree > ul { padding-left: 0; }
+      .documented-files-tree li { margin: 2px 0; line-height: 1.35; }
+      .documented-files-tree .tree-dir { font-weight: 600; margin-top: 4px; font-size: 12px; }
+      .documented-files-tree .tree-file {
+        margin: 3px 0;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
+        font-size: 11px;
       }
-      .toolbar-tree-toggle:hover { background: color-mix(in oklab, CanvasText 11%, Canvas); }
-      .documented-files-panel {
-        flex: 0 0 auto; max-height: min(42vh, 360px); overflow: auto;
-        border-bottom: 1px solid color-mix(in oklab, CanvasText 12%, Canvas);
-        background: color-mix(in oklab, CanvasText 4%, Canvas);
+      .documented-files-tree .tree-file-link {
+        color: inherit;
+        font-weight: 500;
+        text-decoration: underline;
+        text-underline-offset: 2px;
+        word-break: break-word;
       }
-      .documented-files-panel__inner { padding: 10px 14px 14px; font-size: 13px; }
-      .documented-files-panel__hint { margin: 0 0 10px; opacity: 0.82; line-height: 1.4; }
-      .documented-files-panel__code { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace; font-size: 12px; }
-      .documented-files-tree ul { list-style: none; margin: 0; padding-left: 14px; }
-      .documented-files-tree > ul { padding-left: 0; }
-      .documented-files-tree li { margin: 2px 0; line-height: 1.4; }
-      .documented-files-tree .tree-dir { font-weight: 600; margin-top: 6px; }
-      .documented-files-tree .tree-file { display: flex; flex-wrap: wrap; align-items: baseline; gap: 6px 10px; margin: 4px 0; }
-      .documented-files-tree .tree-file-name { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace; font-size: 12px; }
-      .documented-files-tree .tree-file-links { display: inline-flex; flex-wrap: wrap; gap: 6px 10px; font-size: 11px; }
-      .documented-files-tree .tree-file-links a { color: inherit; text-decoration: underline; text-underline-offset: 2px; }
-      .toolbar .search-field {
-        display: inline-flex; align-items: center; gap: 6px; flex: 1 1 220px; min-width: 160px;
-      }
-      .toolbar .search-field input[type="search"] {
-        flex: 1; min-width: 0; padding: 4px 8px; font: inherit; border-radius: 6px;
-        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas); background: Canvas;
-        color: CanvasText;
+      .documented-files-tree .tree-file-link:hover {
+        opacity: 0.92;
       }
       .toolbar button {
-        font: inherit; padding: 4px 10px; border-radius: 6px; cursor: pointer;
-        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas); background: color-mix(in oklab, CanvasText 6%, Canvas);
+        font: inherit;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        min-height: var(--cr-control-h);
+        padding: 0 12px;
+        border-radius: var(--cr-control-radius);
+        cursor: pointer;
+        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas);
+        background: color-mix(in oklab, CanvasText 6%, Canvas);
         color: CanvasText;
       }
       .search-results {
-        flex: 0 0 auto; max-height: 160px; overflow: auto; padding: 6px 12px 8px;
-        border-bottom: 1px solid color-mix(in oklab, CanvasText 12%, Canvas);
-        font-size: 12px;
+        flex: 0 1 auto;
+        min-height: 0;
+        max-height: min(320px, 38vh);
+        overflow: auto;
+        padding: 8px 8px 10px;
+        border-radius: 8px;
+        border: 1px solid color-mix(in oklab, CanvasText 12%, Canvas);
+        background: Canvas;
+        font-size: 13px;
       }
       .search-results[hidden] { display: none !important; }
-      .search-results .hint { opacity: 0.75; margin-bottom: 6px; }
+      .search-results .hint { opacity: 0.75; margin-bottom: 8px; line-height: 1.45; }
       .search-results button.hit {
-        display: block; width: 100%; text-align: left; margin: 2px 0; padding: 6px 8px;
+        display: block; width: 100%; text-align: left; margin: 4px 0; padding: 8px 10px;
         border-radius: 6px; border: 1px solid color-mix(in oklab, CanvasText 14%, Canvas);
         background: color-mix(in oklab, CanvasText 5%, Canvas); color: CanvasText; cursor: pointer;
         font: inherit;
       }
       .search-results button.hit:hover { background: color-mix(in oklab, CanvasText 10%, Canvas); }
-      .search-results button.hit .meta { opacity: 0.8; font-size: 11px; }
-      .search-results button.hit .src-tag { opacity: 0.75; font-weight: 500; font-size: 10px; }
-      .search-results button.hit .snippet { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace; font-size: 11px; white-space: pre-wrap; word-break: break-word; margin-top: 2px; }
+      .search-results button.hit .meta { opacity: 0.8; font-size: 12px; }
+      .search-results button.hit .src-tag { opacity: 0.75; font-weight: 500; font-size: 11px; }
+      .search-results button.hit .snippet {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace; font-size: 13px;
+        line-height: 1.45; white-space: pre-wrap; word-break: break-word; margin-top: 4px;
+      }
+      .search-results mark.search-hit {
+        padding: 0 2px; border-radius: 3px; font: inherit;
+        background: color-mix(in oklab, #f5a623 70%, Canvas);
+        color: CanvasText;
+        box-decoration-break: clone;
+        -webkit-box-decoration-break: clone;
+      }
+      @media (prefers-color-scheme: dark) {
+        .search-results mark.search-hit {
+          background: color-mix(in oklab, #c9a227 55%, Canvas);
+        }
+      }
       .shell { display: flex; flex-direction: row; flex: 1; min-height: 0; }
+      .app__main .shell { flex: 1 1 auto; }
       .pane--code {
         flex: 0 0 50%;
         min-width: 120px; overflow: auto; padding: 12px 16px;
@@ -285,12 +740,12 @@ const CODE_BROWSER_STYLES = `
         --code-line-font-size: 13px;
         --code-line-height: 1.5;
       }
+      .pane--code .code-line-stack { --code-ln-min-ch: 3; }
       .pane--code .code-line {
         display: grid;
-        /* max-content: column wide enough for the longest line number (avoids 100+ bleeding into code). */
         grid-template-columns: max-content 1fr;
-        column-gap: 12px;
-        align-items: baseline;
+        column-gap: 10px;
+        align-items: start;
       }
       .pane--code .code-line pre {
         margin: 0;
@@ -316,6 +771,8 @@ const CODE_BROWSER_STYLES = `
         white-space: nowrap;
         font-size: var(--code-line-font-size);
         line-height: var(--code-line-height);
+        min-width: calc(var(--code-ln-min-ch, 3) * 1ch + 0.6ch);
+        box-sizing: content-box;
       }
       .pane--code .code-line:target .ln,
       .pane--code .code-line:hover .ln {
@@ -328,18 +785,78 @@ const CODE_BROWSER_STYLES = `
         white-space: pre;
       }
       .gutter {
-        flex: 0 0 8px; cursor: col-resize; background: color-mix(in oklab, CanvasText 12%, Canvas);
+        flex: 0 0 14px; cursor: col-resize; background: color-mix(in oklab, CanvasText 12%, Canvas);
         position: relative;
+        --commentray-ray-accent: #3b7dd8;
+      }
+      @media (prefers-color-scheme: dark) {
+        .gutter { --commentray-ray-accent: #6eb0ff; }
+      }
+      .gutter__rays {
+        position: absolute; inset: 0; pointer-events: none; z-index: 1;
+      }
+      .gutter__rays svg { width: 100%; height: 100%; display: block; overflow: visible; }
+      .gutter__rays-path {
+        fill: none; stroke-linecap: round; vector-effect: non-scaling-stroke;
+        stroke: color-mix(in oklab, var(--commentray-ray-accent) 72%, CanvasText);
+        stroke-width: 1.35px; opacity: 0.26;
+      }
+      .gutter__rays-path--active {
+        stroke-width: 2.4px; opacity: 0.88;
+      }
+      .gutter__rays-path--trail {
+        stroke-dasharray: 3 4; opacity: 0.42;
+      }
+      .gutter__rays-path--active.gutter__rays-path--trail {
+        opacity: 0.72;
       }
       .gutter:hover { background: color-mix(in oklab, CanvasText 22%, Canvas); }
       .gutter::after {
         content: ""; position: absolute; top: 0; bottom: 0; left: -4px; right: -4px;
       }
       .pane--doc {
-        flex: 1 1 auto; min-width: 120px; overflow: auto; padding: 12px 16px;
+        flex: 1 1 auto; min-width: 0; min-height: 0;
+        display: flex; flex-direction: column; overflow: hidden; padding: 12px 16px;
+      }
+      .doc-pane-body {
+        flex: 1 1 auto; min-height: 0; overflow: auto;
+      }
+      .toolbar-angle-picker {
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        flex: 0 0 auto;
+        color: color-mix(in oklab, CanvasText 88%, Canvas);
+      }
+      .toolbar-angle-picker > label {
+        font-size: var(--cr-label-caps-fs);
+        font-weight: 700;
+        letter-spacing: var(--cr-label-caps-track);
+        text-transform: uppercase;
+        opacity: 0.72;
+      }
+      .toolbar-angle-picker select {
+        font: inherit;
+        font-size: var(--cr-ui-fs);
+        min-height: var(--cr-control-h);
+        height: var(--cr-control-h);
+        padding: 0 10px;
+        border-radius: var(--cr-control-radius);
+        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas);
+        background: Canvas;
+        color: CanvasText;
+      }
+      .toolbar-angle-picker select:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
       }
       .pane--doc { font-size: 15px; line-height: 1.45; }
       .pane--doc img { max-width: 100%; height: auto; }
+      .pane--doc .commentray-line-anchor {
+        display: inline;
+        vertical-align: baseline;
+        scroll-margin-top: 10px;
+      }
       .pane--doc .commentray-block-anchor {
         display: block;
         height: 0;
@@ -348,8 +865,6 @@ const CODE_BROWSER_STYLES = `
         border-top: 1px solid color-mix(in oklab, CanvasText 22%, Canvas);
         pointer-events: none;
       }
-      .pane h2.pane-title { margin: 0 0 10px; font-size: 12px; letter-spacing: 0.06em; text-transform: uppercase; opacity: 0.75; }
-      .app { display: flex; flex-direction: column; height: 100vh; }
       .shell--stretch-rows {
         flex: 1;
         min-height: 0;
@@ -413,6 +928,7 @@ const CODE_BROWSER_STYLES = `
         font-size: var(--code-line-font-size, 13px);
         line-height: var(--code-line-height, 1.5);
       }
+      .block-stretch .code-line-stack { --code-ln-min-ch: 3; }
       .block-stretch .code-line .ln {
         font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
         font-variant-numeric: tabular-nums;
@@ -425,20 +941,16 @@ const CODE_BROWSER_STYLES = `
         white-space: nowrap;
         font-size: var(--code-line-font-size, 13px);
         line-height: var(--code-line-height, 1.5);
+        min-width: calc(var(--code-ln-min-ch, 3) * 1ch + 0.6ch);
+        box-sizing: content-box;
       }
       .block-stretch.wrap .code-line pre,
       .block-stretch.wrap .code-line pre code { white-space: pre-wrap; word-break: break-word; }
       .block-stretch:not(.wrap) .code-line pre,
       .block-stretch:not(.wrap) .code-line pre code { white-space: pre; }
-      .block-stretch-headings {
-        display: grid;
-        grid-template-columns: 1fr 1fr;
-        gap: 0 16px;
-        padding: 4px 12px 8px;
-        border-bottom: 1px solid color-mix(in oklab, CanvasText 10%, Canvas);
-      }
-      .block-stretch-headings .pane-title { margin: 0; }
 `;
+/** Native tooltip on #search-q (short hint is visible under the search row). */
+const CODE_BROWSER_SEARCH_INPUT_TITLE = "Filename, path, or words. Matches this pair (source + commentray lines) first; merges commentray-nav-search.json when the export includes it (indexed paths + commentray lines).";
 function buildCodeBrowserPageHtml(p) {
     const shellClass = p.layout === "stretch" ? "shell shell--stretch-rows" : "shell";
     return `<!doctype html>
@@ -446,7 +958,7 @@ function buildCodeBrowserPageHtml(p) {
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    ${p.generatorMetaHtml}<title>${escapeHtml(p.title)}</title>
+    ${p.metaDescriptionHtml}${p.generatorMetaHtml}<title>${escapeHtml(p.title)}</title>
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/styles/${escapeHtml(p.hljs)}.min.css" media="(prefers-color-scheme: light)" />
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/styles/${escapeHtml(p.hljsDark)}.min.css" media="(prefers-color-scheme: dark)" />
     <style>
@@ -454,27 +966,38 @@ ${CODE_BROWSER_STYLES}
     </style>
   </head>
   <body>
+    <a class="skip-link" href="#main-content">Skip to main content</a>
     <div class="app">
-      <header class="toolbar" aria-label="View options">
+      <header class="toolbar" role="banner" aria-label="View options">
+        <h1 class="sr-only">${escapeHtml(p.title)}</h1>
         <div class="toolbar__main">
-          ${p.filePathHtml}
+          ${p.toolbarSiteHubHtml}
+          ${p.navRailContextHtml}
+          ${p.navRailDocumentedHtml}
+          ${p.angleSelectHtml}
           ${p.toolbarDocHubHtml}
-          <span class="search-field">
-            <label for="search-q">Search</label>
-            <input type="search" id="search-q" placeholder="${escapeHtml(p.searchPlaceholder)}" autocomplete="off" spellcheck="false" />
-            <button type="button" id="search-clear" title="Clear search">Clear</button>
-          </span>
           ${p.relatedNavHtml}
           <label><input type="checkbox" id="wrap-lines" /> Wrap code lines</label>
         </div>
         ${p.toolbarEndHtml}
       </header>
-      ${p.documentedPanelHtml}
-      <div class="search-results" id="search-results" hidden aria-live="polite"></div>
-      <div class="${shellClass}" id="shell" data-layout="${p.layout}" data-raw-code-b64="${escapeHtml(p.rawCodeB64)}" data-raw-md-b64="${escapeHtml(p.rawMdB64)}" data-scroll-block-links-b64="${escapeHtml(p.scrollBlockLinksB64)}"${p.shellDocumentedPairsAttr}${p.shellSearchAttrs}>
+      <header class="app__chrome" role="region" aria-label="Search">
+        <div class="chrome__search-row">
+          <label class="chrome__search-label nav-rail__search-label" for="search-q">Search</label>
+          <input type="search" id="search-q" placeholder="${escapeHtml(p.searchPlaceholder)}" title="${escapeHtml(CODE_BROWSER_SEARCH_INPUT_TITLE)}" autocomplete="off" spellcheck="false" />
+          <button type="button" id="search-clear" title="Clear search">Clear</button>
+        </div>
+        <div class="search-results" id="search-results" hidden aria-live="polite"></div>
+        <p class="nav-rail__search-hint chrome__search-hint">This pair + merged <code class="nav-rail__code">commentray-nav-search.json</code> when the export ships it.</p>
+      </header>
+      <main id="main-content" class="app__main" tabindex="-1">
+        <div class="${shellClass}" id="shell" data-layout="${p.layout}" data-raw-code-b64="${escapeHtml(p.rawCodeB64)}" data-raw-md-b64="${escapeHtml(p.rawMdB64)}" data-scroll-block-links-b64="${escapeHtml(p.scrollBlockLinksB64)}"${p.shellDocumentedPairsAttr}${p.shellSearchAttrs}>
 ${p.shellInner}
-      </div>
+        </div>
+      </main>
+      ${p.pageFooterHtml}
     </div>
+    <script type="text/plain" id="commentray-multi-angle-b64">${p.multiAngleScriptBlock}</script>
     <script>
 ${loadCodeBrowserClientBundle()}
     </script>
@@ -482,10 +1005,108 @@ ${loadCodeBrowserClientBundle()}
   </body>
 </html>`;
 }
+async function multiAngleJsonRowAndDocHtml(opts, spec) {
+    const rows = spec.blockStretchRows;
+    const links = rows !== undefined
+        ? buildBlockScrollLinks(rows.index, rows.sourceRelative, rows.commentrayPathRel, spec.markdown, opts.code)
+        : [];
+    const mdForDoc = injectCommentrayDocAnchors(spec.markdown, links.length > 0 ? links : undefined);
+    const scrollB64 = links.length > 0 ? Buffer.from(JSON.stringify(links), "utf8").toString("base64") : "";
+    const commentrayHtml = await renderMarkdownToHtml(mdForDoc, {
+        commentrayOutputUrls: opts.commentrayOutputUrls,
+    });
+    return {
+        jsonRow: {
+            id: spec.id,
+            title: spec.title?.trim() || spec.id,
+            docInnerHtmlB64: Buffer.from(commentrayHtml, "utf8").toString("base64"),
+            rawMdB64: Buffer.from(spec.markdown, "utf8").toString("base64"),
+            scrollBlockLinksB64: scrollB64,
+            commentrayPathForSearch: spec.commentrayPathRel.trim(),
+            commentrayOnGithubUrl: spec.commentrayOnGithubUrl,
+            staticBrowseUrl: spec.staticBrowseUrl,
+        },
+        commentrayHtml,
+        scrollB64,
+    };
+}
+async function buildMultiAngleDualPaneShell(opts, multi) {
+    const defaultId = multi.angles.some((a) => a.id === multi.defaultAngleId)
+        ? multi.defaultAngleId
+        : (multi.angles[0]?.id ?? "main");
+    const jsonAngles = [];
+    let defaultMarkdown = opts.commentrayMarkdown;
+    let defaultScrollB64 = "";
+    let defaultPathSearch = (opts.commentrayPathForSearch ?? "").trim();
+    let defaultGh = opts.commentrayOnGithubUrl;
+    let defaultStaticBrowse = (opts.commentrayStaticBrowseUrl ?? "").trim();
+    let defaultPaneHtml = "";
+    const codeHtml = await renderHighlightedCodeLineRows(opts.code, opts.language);
+    for (const spec of multi.angles) {
+        const { jsonRow, commentrayHtml, scrollB64 } = await multiAngleJsonRowAndDocHtml(opts, spec);
+        if (spec.id === defaultId) {
+            defaultMarkdown = spec.markdown;
+            defaultScrollB64 = scrollB64;
+            defaultPathSearch = spec.commentrayPathRel.trim();
+            defaultGh = spec.commentrayOnGithubUrl;
+            {
+                const sb = (spec.staticBrowseUrl ?? "").trim();
+                if (sb.length > 0)
+                    defaultStaticBrowse = sb;
+            }
+            defaultPaneHtml = commentrayHtml;
+        }
+        jsonAngles.push(jsonRow);
+    }
+    const selOpts = multi.angles
+        .map((a) => {
+        const lab = escapeHtml(a.title?.trim() || a.id);
+        return `<option value="${escapeHtml(a.id)}"${a.id === defaultId ? " selected" : ""}>${lab}</option>`;
+    })
+        .join("");
+    const angleSelectHtml = `<span class="toolbar-angle-picker"><label for="angle-select">Angle</label><select id="angle-select" aria-label="Commentray angle">${selOpts}</select></span>`;
+    const shellInner = `        <section class="pane--code" id="code-pane" aria-label="Source code">` +
+        `          ${codeHtml}\n` +
+        `        </section>\n` +
+        `        <div class="gutter" id="gutter" role="separator" aria-orientation="vertical" aria-label="Resize panes"></div>\n` +
+        `        <section class="pane--doc commentray" id="doc-pane" aria-label="Commentray">\n` +
+        `          <div id="doc-pane-body" class="doc-pane-body">\n` +
+        `          ${defaultPaneHtml}\n` +
+        `          </div>\n` +
+        `        </section>\n`;
+    const payloadObj = { defaultAngleId: defaultId, angles: jsonAngles };
+    const multiAnglePayloadB64 = Buffer.from(JSON.stringify(payloadObj), "utf8").toString("base64");
+    return {
+        shellInner,
+        multiShell: {
+            rawMdB64: Buffer.from(defaultMarkdown, "utf8").toString("base64"),
+            scrollBlockLinksB64: defaultScrollB64,
+            commentrayPathForSearch: defaultPathSearch,
+            commentrayOnGithubUrl: defaultGh,
+            ...(defaultStaticBrowse.length > 0 ? { commentrayStaticBrowseUrl: defaultStaticBrowse } : {}),
+        },
+        angleSelectHtml,
+        multiAnglePayloadB64,
+    };
+}
 async function buildCodeBrowserShell(opts, layoutPref) {
     let layout = "dual";
     let shellInner = "";
     let scrollBlockLinksB64 = "";
+    const multi = opts.multiAngleBrowsing;
+    const multiActive = Boolean(multi && multi.angles.length >= 2);
+    if (multiActive && multi) {
+        const built = await buildMultiAngleDualPaneShell(opts, multi);
+        const ms = built.multiShell;
+        return {
+            layout: "dual",
+            shellInner: built.shellInner,
+            scrollBlockLinksB64: ms.scrollBlockLinksB64,
+            angleSelectHtml: built.angleSelectHtml,
+            multiAnglePayloadB64: built.multiAnglePayloadB64,
+            multiShell: ms,
+        };
+    }
     if (opts.blockStretchRows && layoutPref !== "dual") {
         const stretched = await tryBuildBlockStretchTableHtml({
             code: opts.code,
@@ -498,51 +1119,52 @@ async function buildCodeBrowserShell(opts, layoutPref) {
         });
         if (stretched) {
             layout = "stretch";
-            shellInner =
-                `        <div class="block-stretch-headings">` +
-                    `<h2 class="pane-title">Code</h2>` +
-                    `<h2 class="pane-title">Commentray</h2>` +
-                    `</div>\n` +
-                    `        ${stretched.preambleHtml}\n` +
-                    `        ${stretched.tableInnerHtml}\n`;
+            shellInner = `        ${stretched.preambleHtml}\n` + `        ${stretched.tableInnerHtml}\n`;
         }
     }
     if (layout === "dual") {
         const links = opts.blockStretchRows !== undefined
             ? buildBlockScrollLinks(opts.blockStretchRows.index, opts.blockStretchRows.sourceRelative, opts.blockStretchRows.commentrayPathRel, opts.commentrayMarkdown, opts.code)
             : [];
-        const mdForDoc = injectCommentrayBlockAnchors(opts.commentrayMarkdown, links.length > 0 ? links : undefined);
+        const mdForDoc = injectCommentrayDocAnchors(opts.commentrayMarkdown, links.length > 0 ? links : undefined);
         if (links.length > 0) {
             scrollBlockLinksB64 = Buffer.from(JSON.stringify(links), "utf8").toString("base64");
         }
         const [codeHtml, commentrayHtml] = await Promise.all([
-            renderCodeLineBlocks(opts.code, opts.language),
+            renderHighlightedCodeLineRows(opts.code, opts.language),
             renderMarkdownToHtml(mdForDoc, {
                 commentrayOutputUrls: opts.commentrayOutputUrls,
             }),
         ]);
         shellInner =
             `        <section class="pane--code" id="code-pane" aria-label="Source code">` +
-                `<h2 class="pane-title">Code</h2>\n` +
                 `          ${codeHtml}\n` +
                 `        </section>\n` +
                 `        <div class="gutter" id="gutter" role="separator" aria-orientation="vertical" aria-label="Resize panes"></div>\n` +
                 `        <section class="pane--doc commentray" id="doc-pane" aria-label="Commentray">\n` +
-                `          <h2 class="pane-title">Commentray</h2>\n` +
+                `          <div id="doc-pane-body" class="doc-pane-body">\n` +
                 `          ${commentrayHtml}\n` +
+                `          </div>\n` +
                 `        </section>\n`;
     }
-    return { layout, shellInner, scrollBlockLinksB64 };
+    return {
+        layout,
+        shellInner,
+        scrollBlockLinksB64,
+        angleSelectHtml: "",
+        multiAnglePayloadB64: "",
+    };
 }
-function searchChromeFromOptions(opts) {
+function searchChromeFromOptions(opts, commentrayPathOverride) {
+    const crPath = (commentrayPathOverride ?? opts.commentrayPathForSearch ?? "").trim();
     if (opts.staticSearchScope === "commentray-and-paths") {
         return {
-            searchPlaceholder: "Commentray + file paths (ordered tokens + fuzzy lines)…",
-            shellSearchAttrs: ` data-search-scope="commentray-and-paths" data-search-file-path="${escapeHtml(opts.filePath ?? "")}" data-search-commentray-path="${escapeHtml((opts.commentrayPathForSearch ?? "").trim())}"`,
+            searchPlaceholder: "Filename, path, or keywords…",
+            shellSearchAttrs: ` data-search-scope="commentray-and-paths" data-search-file-path="${escapeHtml(opts.filePath ?? "")}" data-search-commentray-path="${escapeHtml(crPath)}"`,
         };
     }
     return {
-        searchPlaceholder: "Whole source (ordered tokens + fuzzy lines)…",
+        searchPlaceholder: "Filename, path, or keywords…",
         shellSearchAttrs: "",
     };
 }
@@ -552,6 +1174,38 @@ function shellDocumentedPairsAttrFromOptions(opts) {
         return "";
     return ` data-documented-pairs-b64="${escapeHtml(emb)}"`;
 }
+function codeBrowserPageTitle(opts) {
+    return opts.title ?? opts.filePath ?? "Commentray";
+}
+function codeBrowserHljsThemes(opts) {
+    const hljs = opts.hljsTheme ?? "github";
+    const hljsDark = opts.hljsTheme?.includes("dark") ? opts.hljsTheme : "github-dark";
+    return { hljs, hljsDark };
+}
+function toolbarCommentrayGithubFromShell(shell, opts) {
+    return shell.multiShell?.commentrayOnGithubUrl ?? opts.commentrayOnGithubUrl;
+}
+function toolbarCommentrayStaticBrowseFromShell(shell, opts) {
+    const t = (shell.multiShell?.commentrayStaticBrowseUrl ??
+        opts.commentrayStaticBrowseUrl ??
+        "").trim();
+    return t.length > 0 ? t : undefined;
+}
+function rawMdB64FromShell(shell, opts) {
+    return (shell.multiShell?.rawMdB64 ?? Buffer.from(opts.commentrayMarkdown, "utf8").toString("base64"));
+}
+function navRailCommentrayPathFromShell(shell, opts) {
+    const trimmed = (shell.multiShell?.commentrayPathForSearch ??
+        opts.commentrayPathForSearch ??
+        "").trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function shellSearchAttrsWithNavJson(shellSearchAttrsBase, documentedNavJsonUrl) {
+    const navJson = documentedNavJsonUrl?.trim() ?? "";
+    if (navJson.length === 0)
+        return shellSearchAttrsBase;
+    return `${shellSearchAttrsBase} data-nav-search-json-url="${escapeHtml(navJson)}"`;
+}
 /**
  * Static HTML shell for a minimal “code browser”: code + rendered commentray,
  * draggable vertical splitter, togglable line wrap for the code pane, and
@@ -559,35 +1213,47 @@ function shellDocumentedPairsAttrFromOptions(opts) {
  */
 export async function renderCodeBrowserHtml(opts) {
     const rawCodeB64 = Buffer.from(opts.code, "utf8").toString("base64");
-    const rawMdB64 = Buffer.from(opts.commentrayMarkdown, "utf8").toString("base64");
-    const title = opts.title ?? opts.filePath ?? "Commentray";
-    const filePathHtml = renderFilePathLabel(opts.filePath, title);
-    const toolbarEndHtml = buildToolbarEndHtml(opts.githubRepoUrl, opts.toolHomeUrl);
-    const hljs = opts.hljsTheme ?? "github";
-    const hljsDark = opts.hljsTheme?.includes("dark") ? opts.hljsTheme : "github-dark";
+    const title = codeBrowserPageTitle(opts);
+    const metaDescriptionHtml = renderMetaDescriptionHtml(opts, title);
+    const builtAt = opts.builtAt ?? new Date();
+    const renderSemver = commentrayRenderVersion();
+    const toolbarSiteHubHtml = buildToolbarSiteHubHtml(opts.siteHubUrl);
+    const toolbarEndHtml = buildToolbarEndHtml(opts.githubRepoUrl, opts.toolHomeUrl, renderSemver, opts.siteHubUrl);
+    const pageFooterHtml = renderPageFooterHtml(builtAt);
+    const { hljs, hljsDark } = codeBrowserHljsThemes(opts);
     const mermaidScript = mermaidRuntimeScriptHtml(opts.includeMermaidRuntime);
     const relatedNavHtml = renderRelatedGithubNavHtml(opts.relatedGithubNav ?? []);
     const generatorMetaHtml = renderGeneratorMetaHtml(opts.generatorLabel);
-    const { toolbarDocHubHtml, documentedPanelHtml } = renderToolbarDocHubHtml({
-        sourceOnGithubUrl: opts.sourceOnGithubUrl,
-        commentrayOnGithubUrl: opts.commentrayOnGithubUrl,
+    const layoutPref = opts.codeBrowserLayout ?? "auto";
+    const shell = await buildCodeBrowserShell(opts, layoutPref);
+    const { toolbarDocHubHtml, navRailDocumentedHtml } = renderToolbarDocHubHtml({
         documentedNavJsonUrl: opts.documentedNavJsonUrl,
         documentedPairsEmbeddedB64: opts.documentedPairsEmbeddedB64,
     });
-    const layoutPref = opts.codeBrowserLayout ?? "auto";
-    const { layout, shellInner, scrollBlockLinksB64 } = await buildCodeBrowserShell(opts, layoutPref);
-    const { searchPlaceholder, shellSearchAttrs } = searchChromeFromOptions(opts);
+    const rawMdB64 = rawMdB64FromShell(shell, opts);
+    const scrollBlockLinksB64 = shell.scrollBlockLinksB64;
+    const { searchPlaceholder, shellSearchAttrs: shellSearchAttrsBase } = searchChromeFromOptions(opts, shell.multiShell?.commentrayPathForSearch);
     const shellDocumentedPairsAttr = shellDocumentedPairsAttrFromOptions(opts);
+    const shellSearchAttrs = shellSearchAttrsWithNavJson(shellSearchAttrsBase, opts.documentedNavJsonUrl);
+    const navRailContextHtml = renderNavRailContextHtml(opts.filePath, navRailCommentrayPathFromShell(shell, opts), {
+        sourceOnGithubUrl: opts.sourceOnGithubUrl,
+        commentrayOnGithubUrl: toolbarCommentrayGithubFromShell(shell, opts),
+        commentrayStaticBrowseUrl: toolbarCommentrayStaticBrowseFromShell(shell, opts),
+    });
     return buildCodeBrowserPageHtml({
         title,
+        metaDescriptionHtml,
         generatorMetaHtml,
-        filePathHtml,
+        toolbarSiteHubHtml,
+        navRailContextHtml,
+        angleSelectHtml: shell.angleSelectHtml,
         toolbarDocHubHtml,
-        documentedPanelHtml,
+        navRailDocumentedHtml,
         relatedNavHtml,
         toolbarEndHtml,
-        layout,
-        shellInner,
+        pageFooterHtml,
+        layout: shell.layout,
+        shellInner: shell.shellInner,
         rawCodeB64,
         rawMdB64,
         scrollBlockLinksB64,
@@ -597,6 +1263,7 @@ export async function renderCodeBrowserHtml(opts) {
         mermaidScript,
         searchPlaceholder,
         shellSearchAttrs,
+        multiAngleScriptBlock: shell.multiAnglePayloadB64,
     });
 }
 //# sourceMappingURL=code-browser.js.map