@commentray/render 0.0.5 → 0.0.8

package/dist/code-browser.js

@@ -1,11 +1,13 @@
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { MARKER_ID_BODY, buildBlockScrollLinks, } from "@commentray/core";
+import { join } from "node:path";
+import { MARKER_ID_BODY, buildBlockScrollLinks, findMonorepoPackagesDir, monorepoLayoutStartDir, } from "@commentray/core";
 import { tryBuildBlockStretchTableHtml } from "./block-stretch-layout.js";
 import { formatCommentrayBuiltAtLocal } from "./build-stamp.js";
 import { escapeHtml } from "./html-utils.js";
+import { commentrayColorThemeHeadBoot } from "./code-browser-color-theme.js";
+import { hljsStylesheetThemes } from "./hljs-stylesheet-themes.js";
 import { renderHighlightedCodeLineRows } from "./highlighted-code-lines.js";
+import { COMMENTRAY_FAVICON_LINK_HTML } from "./inline-favicon.js";
 import { mermaidRuntimeScriptHtml } from "./mermaid-runtime-html.js";
 import { renderMarkdownToHtml } from "./markdown-pipeline.js";
 import { commentrayRenderVersion } from "./package-version.js";
@@ -15,10 +17,29 @@ function renderGeneratorMetaHtml(label) {
         return "";
     return `<meta name="generator" content="${escapeHtml(t)}" />\n    `;
 }
+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");
 function trimEndSpacesTabs(s) {
-    return s.replace(/[ \t]+$/, "");
+    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);
@@ -111,6 +132,33 @@ function injectCommentrayDocAnchors(markdown, links) {
 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>";
+/** Folder-with-list glyph (file tree / documented pairs hub). */
+const TOOLBAR_ICON_TREE_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+    '<path d="M4 20h16a1 1 0 0 0 1-1V9a2 2 0 0 0-2-2h-5.5a2 2 0 0 1-1.6-.8L10.5 4.5a2 2 0 0 0-1.6-.8H5a2 2 0 0 0-2 2v14a1 1 0 0 0 1 1Z"/>' +
+    '<path d="M8 12h8M8 16h6M8 20h4"/>' +
+    "</svg>";
+/**
+ * Line wrap — Material "wrap_text" glyph (Apache-2.0), same visual family as
+ * https://www.svgrepo.com/svg/376703/text-wrap-line (filled 24dp path scaled to 18px).
+ */
+const TOOLBAR_ICON_WRAP_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18" fill="currentColor" aria-hidden="true">' +
+    '<path d="M4 19h6v-2H4v2zM20 5H4v2h16V5zm-3 6H4v2h13.25c1.1 0 2 .9 2 2s-.9 2-2 2H15v-2l-3 3 3 3v-2h2c2.21 0 4-1.79 4-4s-1.79-4-4-4z"/>' +
+    "</svg>";
+const CHROME_ICON_SEARCH_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+    '<circle cx="11" cy="11" r="7"/>' +
+    '<path d="m21 21-4.3-4.3"/>' +
+    "</svg>";
+/** Swap / flip: circle split by a diameter, one arrow per half (narrow viewports). */
+const TOOLBAR_ICON_FLIP_PANES_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+    '<circle cx="12" cy="12" r="9"/>' +
+    '<path d="M12 4v16"/>' +
+    '<path d="M10.5 12H6l2.5-2.5M6 12l2.5 2.5"/>' +
+    '<path d="M13.5 12H18l-2.5-2.5M18 12l-2.5 2.5"/>' +
+    "</svg>";
 function safeExternalHttpUrl(url) {
     const t = url?.trim();
     if (!t)
@@ -119,26 +167,48 @@ function safeExternalHttpUrl(url) {
         return null;
     return t;
 }
-function buildToolbarEndHtml(githubRepoUrl, toolHomeUrl, commentrayRenderSemver) {
+/** 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>`;
+}
+/** GitHub Octocat in the toolbar when a repo URL is set and the hub link does not replace it. */
+function buildToolbarEndHtml(githubRepoUrl, 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>`);
+        return `<div class="toolbar__end"><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></div>`;
     }
+    return "";
+}
+function renderPageFooterHtml(input) {
+    const { builtAt, toolHomeUrl, commentrayRenderSemver } = input;
+    const iso = builtAt.toISOString();
+    const human = formatCommentrayBuiltAtLocal(builtAt);
+    const tool = safeExternalHttpUrl(toolHomeUrl);
     if (tool) {
         const te = escapeHtml(tool);
         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>`);
+        return (`<footer class="app__footer" role="contentinfo">` +
+            `<p class="app__footer-line app__footer-attribution" role="note">` +
+            `Rendered with <a href="${te}" target="_blank" rel="noopener noreferrer">Commentray</a> ` +
+            `<span class="app__footer-attribution__version" translate="no">v${ver}</span>: ` +
+            `<time datetime="${escapeHtml(iso)}">${escapeHtml(human)}</time>` +
+            `</p>` +
+            `</footer>`);
     }
-    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>`);
@@ -160,49 +230,61 @@ function renderToolbarDocHubHtml(opts) {
     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">Documented files</summary>
+        <summary class="nav-rail__doc-hub-summary" title="Comment-rayed files" aria-label="Comment-rayed files"><span class="nav-rail__doc-hub-summary__caption">Comment-rayed files</span><span class="nav-rail__doc-hub-summary__glyph" aria-hidden="true">${TOOLBAR_ICON_TREE_SVG}</span></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>
       </details>`
         : "";
     return { toolbarDocHubHtml, navRailDocumentedHtml };
 }
-function renderNavRailContextHtml(filePath, commentrayPath, opts) {
+function dualPanePanesInnerHtml(codeHtml, commentrayHtml) {
+    return (`        <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` +
+        `          ${commentrayHtml}\n` +
+        `          </div>\n` +
+        `        </section>\n`);
+}
+/** Plain-text Src/Doc labels above the panes; column widths track the resizable split via `--split-pct`. */
+function renderShellPairContextHtml(filePath, commentrayPath) {
     const fpRaw = (filePath ?? "").trim();
     const crRaw = (commentrayPath ?? "").trim();
-    const srcUrl = safeExternalHttpUrl(opts?.sourceOnGithubUrl);
-    const crUrl = safeExternalHttpUrl(opts?.commentrayOnGithubUrl);
-    if (fpRaw.length === 0 && crRaw.length === 0 && srcUrl === null && crUrl === null) {
+    if (fpRaw.length === 0 && crRaw.length === 0)
         return "";
-    }
     const fp = escapeHtml(fpRaw);
     const cr = escapeHtml(crRaw);
     const fpDisp = fpRaw.length > 0 ? fp : "—";
     const crDisp = crRaw.length > 0 ? cr : "—";
-    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 = 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>`
-        : "";
-    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" title="${cr}">${crDisp}</span>${crGh}
-    </span>
+    return `<div class="shell__pair-context" aria-label="Current documentation pair">
+    <div class="shell__pair-cell shell__pair-cell--src">
+      <span class="shell__pair-lab">Src</span>
+      <span class="shell__pair-path" title="${fp}">${fpDisp}</span>
+    </div>
+    <div class="shell__pair-gutter-spacer" aria-hidden="true"></div>
+    <div class="shell__pair-cell shell__pair-cell--doc">
+      <span class="shell__pair-lab">Doc</span>
+      <span class="shell__pair-path shell__pair-path--secondary" id="nav-rail-doc-path" title="${cr}">${crDisp}</span>
+    </div>
   </div>`;
 }
+function wrapDualShellInner(pairContextHtml, panesHtml) {
+    const row = pairContextHtml.trim().length > 0 ? `        ${pairContextHtml.trim()}\n` : "";
+    return `${row}        <div class="shell__panes">\n${panesHtml}        </div>\n`;
+}
 /** IIFE produced by `npm run build -w @commentray/render` (esbuild of `code-browser-client.ts`). */
 function loadCodeBrowserClientBundle() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const inDist = join(here, "code-browser-client.bundle.js");
-    const fromSrc = join(here, "..", "dist", "code-browser-client.bundle.js");
+    const packagesDir = findMonorepoPackagesDir(monorepoLayoutStartDir(import.meta.url));
+    const renderDistDir = join(packagesDir, "render", "dist");
+    const inDist = join(renderDistDir, "code-browser-client.bundle.js");
+    const fromSrc = join(packagesDir, "render", "code-browser-client.bundle.js");
     for (const p of [inDist, fromSrc]) {
         if (existsSync(p)) {
             return readFileSync(p, "utf8");
@@ -210,10 +292,94 @@ function loadCodeBrowserClientBundle() {
     }
     throw new Error("Missing code-browser-client.bundle.js. Run `npm run build -w @commentray/render` to bundle the browser client.");
 }
+/**
+ * Compact theme control: primary click opens a menu (readme.io–style), secondary click cycles
+ * system → light → dark. Paired with {@link ./code-browser-color-theme.ts} and the client bundle.
+ */
+const TOOLBAR_COLOR_THEME_HTML = `          <div class="toolbar-theme">
+            <button type="button" id="commentray-theme-trigger" class="toolbar-theme__trigger" data-commentray-trigger-mode="system" aria-haspopup="menu" aria-expanded="false" aria-label="Color theme" title="Appearance: left-click opens the theme menu. Right-click cycles System, Light, and Dark.">
+              <span class="toolbar-theme__icon toolbar-theme__icon--system" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8m-4-4v4"/></svg></span>
+              <span class="toolbar-theme__icon toolbar-theme__icon--light" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2m0 16v2M4.93 4.93l1.41 1.41m11.32 11.32l1.41 1.41M2 12h2m16 0h2M6.34 6.34L4.93 4.93m12.02 12.02l1.41 1.41M17.66 6.34l1.41-1.41M6.34 17.66l-1.41 1.41"/></svg></span>
+              <span class="toolbar-theme__icon toolbar-theme__icon--dark" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="18" height="18" fill="currentColor"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg></span>
+            </button>
+            <div id="commentray-theme-menu" class="toolbar-theme__menu" role="menu" hidden aria-labelledby="commentray-theme-trigger">
+              <button type="button" role="menuitemradio" class="toolbar-theme__menuitem" data-commentray-theme-value="system" aria-checked="true">System</button>
+              <button type="button" role="menuitemradio" class="toolbar-theme__menuitem" data-commentray-theme-value="light" aria-checked="false">Light</button>
+              <button type="button" role="menuitemradio" class="toolbar-theme__menuitem" data-commentray-theme-value="dark" aria-checked="false">Dark</button>
+            </div>
+          </div>
+`;
 const CODE_BROWSER_STYLES = `
-      :root { color-scheme: light dark; }
+      :root {
+        --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;
+        /** Matches code/doc pane horizontal padding so pair-context rows line up with pane content (e.g. line nums). */
+        --cr-pane-inline-pad: 12px;
+      }
+      :root:is(:not([data-commentray-theme]), [data-commentray-theme="system"]) {
+        color-scheme: light dark;
+      }
+      :root[data-commentray-theme="light"] {
+        color-scheme: light;
+      }
+      :root[data-commentray-theme="dark"] {
+        color-scheme: dark;
+      }
       * { box-sizing: border-box; }
-      body { margin: 0; font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif; }
+      html { background: Canvas; color: CanvasText; }
+      body {
+        margin: 0;
+        font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+        background: Canvas;
+        color: CanvasText;
+      }
+      .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;
@@ -244,148 +410,101 @@ const CODE_BROWSER_STYLES = `
       .chrome__search-row input[type="search"] {
         flex: 1 1 auto;
         min-width: 140px;
-        padding: 8px 10px;
+        min-height: var(--cr-control-h);
+        padding: 0 12px;
         font: inherit;
-        font-size: 14px;
-        border-radius: 8px;
+        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;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-height: var(--cr-control-h);
+        padding: 0 12px;
         font: inherit;
-        padding: 6px 14px;
-        border-radius: 8px;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        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-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: 8px;
-        border: 1px solid color-mix(in oklab, CanvasText 14%, Canvas);
-        background: Canvas;
-        font-size: 12px;
-        line-height: 1.3;
+      .chrome__search-row #search-clear:hover {
+        background: color-mix(in oklab, CanvasText 11%, Canvas);
       }
-      .nav-rail__pair {
+      .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;
         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: 9px;
-        font-weight: 700;
-        letter-spacing: 0.06em;
-        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: 11px;
-        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;
+        cursor: default;
         user-select: none;
-        padding: 0 2px;
       }
-      .nav-rail__pair-gh {
-        flex: 0 0 auto;
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        width: 26px;
-        height: 26px;
-        border-radius: 6px;
-        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: 14px;
-        height: 14px;
-        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);
+      /* Wide viewports: same legible caps word as historic Pages shell (icon hidden). */
+      .chrome__search-label__glyph {
+        display: none;
       }
       .nav-rail__search-label {
-        font-size: 11px;
+        font-size: var(--cr-label-caps-fs);
         font-weight: 700;
-        letter-spacing: 0.05em;
+        letter-spacing: var(--cr-label-caps-track);
         text-transform: uppercase;
-        opacity: 0.8;
-      }
-      .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: 6px;
+        border-radius: var(--cr-control-radius);
         background: Canvas;
         overflow: visible;
       }
       .nav-rail__doc-hub-summary {
         cursor: pointer;
-        font-size: 12px;
-        font-weight: 600;
-        padding: 4px 10px;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        color: color-mix(in oklab, CanvasText 88%, Canvas);
+        padding: 0 12px;
+        min-height: var(--cr-control-h);
+        display: inline-flex;
+        flex-direction: row;
+        align-items: center;
+        justify-content: flex-start;
+        gap: 8px;
+        box-sizing: border-box;
         list-style: none;
         user-select: none;
-        line-height: 1.35;
+        line-height: 1.25;
+      }
+      .nav-rail__doc-hub-summary:hover {
+        background: color-mix(in oklab, CanvasText 6%, Canvas);
+      }
+      .nav-rail__doc-hub-summary__caption {
+        white-space: nowrap;
+      }
+      .nav-rail__doc-hub-summary__glyph {
+        display: none;
+      }
+      .nav-rail__doc-hub-summary svg {
+        display: block;
+        flex: 0 0 auto;
       }
       .nav-rail__doc-hub-summary::-webkit-details-marker { display: none; }
       .nav-rail__doc-hub-inner {
@@ -396,7 +515,10 @@ const CODE_BROWSER_STYLES = `
         min-width: min(280px, 78vw);
         max-width: min(440px, 94vw);
         max-height: min(52vh, 400px);
-        overflow: auto;
+        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);
@@ -404,6 +526,33 @@ const CODE_BROWSER_STYLES = `
         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;
@@ -426,41 +575,298 @@ const CODE_BROWSER_STYLES = `
         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 {
-        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;
+      .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);
+        background: color-mix(in oklab, CanvasText 4%, Canvas);
+        font-size: var(--cr-ui-fs);
+        flex: 0 0 auto;
+        min-width: 0;
+      }
+      .toolbar__primary {
+        display: flex;
+        flex-direction: row;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 10px 14px;
+        flex: 1 1 auto;
+        min-width: 0;
+      }
+      .toolbar__primary-main {
+        display: flex;
+        flex-direction: row;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 10px 14px;
+        flex: 0 1 auto;
+        min-width: 0;
+      }
+      .toolbar__primary-trail {
+        display: flex;
+        flex-direction: row;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: flex-end;
+        gap: 10px 14px;
+        margin-left: auto;
+        min-width: 0;
+      }
+      .toolbar__end {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: flex-end;
+        gap: 10px 14px;
+        min-width: 0;
+      }
+      .toolbar-github {
+        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 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; }
+      .app__footer-attribution {
+        margin: 0;
+        color: color-mix(in oklab, CanvasText 88%, Canvas);
+      }
+      .app__footer-attribution a {
+        color: inherit;
+        font-weight: 600;
+        text-decoration: underline;
+        text-underline-offset: 2px;
+      }
+      .app__footer-attribution__version { font-weight: 600; }
+      .toolbar label { display: inline-flex; align-items: center; gap: 6px; cursor: pointer; user-select: none; }
+      .toolbar-wrap-lines {
+        position: relative;
+        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: Canvas;
+        display: inline-flex;
+        flex-direction: row;
+        align-items: center;
+        justify-content: flex-start;
+        gap: 8px;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        color: color-mix(in oklab, CanvasText 88%, Canvas);
+        cursor: pointer;
+      }
+      .toolbar-wrap-lines:hover {
+        background: color-mix(in oklab, CanvasText 6%, Canvas);
+      }
+      .toolbar-wrap-lines__input {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+        opacity: 0;
+      }
+      /** Visible tick box: the real input is visually hidden for a11y; unchecked looked like an empty box with no mark when on. */
+      .toolbar-wrap-lines__box {
+        flex: 0 0 auto;
+        width: 16px;
+        height: 16px;
+        box-sizing: border-box;
+        border: 1.5px solid color-mix(in oklab, CanvasText 38%, Canvas);
+        border-radius: 3px;
+        background: Canvas;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        color: CanvasText;
+      }
+      .toolbar-wrap-lines:has(.toolbar-wrap-lines__input:checked) .toolbar-wrap-lines__box {
+        border-color: color-mix(in oklab, CanvasText 52%, Canvas);
+        background: color-mix(in oklab, CanvasText 6%, Canvas);
+      }
+      .toolbar-wrap-lines__box::after {
+        content: "";
+        display: none;
+        width: 4px;
+        height: 9px;
+        margin-top: -2px;
+        border: solid currentColor;
+        border-width: 0 2px 2px 0;
+        transform: rotate(45deg);
+      }
+      .toolbar-wrap-lines:has(.toolbar-wrap-lines__input:checked) .toolbar-wrap-lines__box::after {
+        display: block;
+      }
+      .toolbar-wrap-lines__face {
+        display: none;
+        align-items: center;
+        justify-content: center;
+        min-height: var(--cr-control-h);
+        min-width: var(--cr-control-h);
+        color: color-mix(in oklab, CanvasText 82%, Canvas);
+      }
+      .toolbar-wrap-lines__caption {
+        white-space: nowrap;
+      }
+      .toolbar-wrap-lines:has(.toolbar-wrap-lines__input:checked) {
+        color: CanvasText;
+        background: color-mix(in oklab, CanvasText 10%, Canvas);
+      }
+      .toolbar-wrap-lines:has(.toolbar-wrap-lines__input:checked) .toolbar-wrap-lines__caption {
+        color: CanvasText;
+      }
+      .toolbar-wrap-lines:has(.toolbar-wrap-lines__input:checked) .toolbar-wrap-lines__face {
+        color: CanvasText;
+        background: color-mix(in oklab, CanvasText 10%, Canvas);
+        border-radius: calc(var(--cr-control-radius) - 1px);
+      }
+      .toolbar-wrap-lines:has(.toolbar-wrap-lines__input:focus-visible) {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .toolbar-icon-btn {
+        display: none;
+        align-items: center;
+        justify-content: center;
+        width: var(--cr-control-h);
+        height: var(--cr-control-h);
+        padding: 0;
+        margin: 0;
+        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;
+        cursor: pointer;
+        flex: 0 0 auto;
+      }
+      .toolbar-icon-btn svg {
+        display: block;
+        flex: 0 0 auto;
+      }
+      .toolbar-icon-btn:hover {
+        background: color-mix(in oklab, CanvasText 14%, Canvas);
+        border-color: color-mix(in oklab, CanvasText 34%, Canvas);
+      }
+      .toolbar-icon-btn:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .toolbar label input:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .toolbar .toolbar-theme {
+        position: relative;
+        display: inline-flex;
+        align-items: center;
+        margin: 0;
+        padding: 0;
+        min-width: 0;
+        border: 0;
+      }
+      .toolbar-theme__trigger {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: var(--cr-control-h);
+        height: var(--cr-control-h);
+        padding: 0;
+        margin: 0;
+        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;
+        cursor: pointer;
+      }
+      .toolbar-theme__trigger:hover {
+        background: color-mix(in oklab, CanvasText 14%, Canvas);
+        border-color: color-mix(in oklab, CanvasText 34%, Canvas);
+      }
+      .toolbar-theme__trigger:active {
+        background: color-mix(in oklab, CanvasText 18%, Canvas);
+      }
+      .toolbar-theme__trigger:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .toolbar-theme__trigger .toolbar-theme__icon {
+        display: none;
+        flex: 0 0 auto;
       }
-      .toolbar__main {
-        display: flex; flex-wrap: wrap; align-items: center; gap: 10px 14px;
-        flex: 0 1 auto;
-        min-width: 0;
+      .toolbar-theme__trigger[data-commentray-trigger-mode="system"] .toolbar-theme__icon--system,
+      .toolbar-theme__trigger[data-commentray-trigger-mode="light"] .toolbar-theme__icon--light,
+      .toolbar-theme__trigger[data-commentray-trigger-mode="dark"] .toolbar-theme__icon--dark {
+        display: block;
       }
-      .toolbar__end {
-        display: flex; flex-wrap: wrap; align-items: center; gap: 10px 14px;
-        margin-left: auto;
-        justify-content: flex-end;
+      .toolbar-theme__menu {
+        position: absolute;
+        left: 0;
+        top: calc(100% + 4px);
+        z-index: 80;
+        min-width: 148px;
+        padding: 4px;
+        margin: 0;
+        list-style: none;
+        border-radius: 8px;
+        border: 1px solid color-mix(in oklab, CanvasText 16%, Canvas);
+        background: Canvas;
+        color: CanvasText;
+        box-shadow: 0 8px 28px color-mix(in oklab, CanvasText 12%, transparent);
       }
-      .toolbar-github {
-        display: inline-flex; align-items: center; justify-content: center;
-        width: 34px; height: 34px; border-radius: 8px;
-        border: 1px solid color-mix(in oklab, CanvasText 22%, Canvas);
-        background: color-mix(in oklab, CanvasText 6%, Canvas);
+      .toolbar-theme__menu[hidden] {
+        display: none !important;
+      }
+      .toolbar-theme__menuitem {
+        display: block;
+        width: 100%;
+        margin: 0;
+        padding: 8px 10px;
+        border: 0;
+        border-radius: 6px;
+        font: inherit;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        text-align: left;
+        cursor: pointer;
         color: CanvasText;
+        background: transparent;
       }
-      .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);
+      .toolbar-theme__menuitem:hover {
+        background: color-mix(in oklab, CanvasText 8%, Canvas);
+      }
+      .toolbar-theme__menuitem:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 0;
+      }
+      .toolbar-theme__menuitem[aria-checked="true"] {
+        background: color-mix(in oklab, CanvasText 10%, Canvas);
+        font-weight: 500;
       }
-      .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 .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;
       }
@@ -469,21 +875,29 @@ const CODE_BROWSER_STYLES = `
       }
       .toolbar .file-path__dir--root { letter-spacing: 0; }
       .toolbar .file-path__base {
-        color: CanvasText; font-weight: 600;
+        color: CanvasText;
+        font-weight: 500;
       }
-      .toolbar .file-path--title { font-weight: 600; }
+      .toolbar .file-path--title { font-weight: 500; }
       .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; }
+      .toolbar-related__prefix { font-weight: 500; opacity: 0.88; white-space: nowrap; }
       .toolbar-related__links { min-width: 0; }
       .toolbar-related a {
         color: inherit; text-decoration: underline; text-underline-offset: 2px; font-weight: 500;
         word-break: break-word;
       }
       .toolbar-related__sep { opacity: 0.55; user-select: none; }
+      #documented-files-tree {
+        flex: 1 1 auto;
+        min-height: 0;
+        overflow: auto;
+      }
       .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; }
@@ -504,8 +918,15 @@ const CODE_BROWSER_STYLES = `
         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 {
@@ -542,15 +963,83 @@ const CODE_BROWSER_STYLES = `
         -webkit-box-decoration-break: clone;
       }
       @media (prefers-color-scheme: dark) {
-        .search-results mark.search-hit {
+        :root:is(:not([data-commentray-theme]), [data-commentray-theme="system"]) .search-results mark.search-hit {
           background: color-mix(in oklab, #c9a227 55%, Canvas);
         }
       }
-      .shell { display: flex; flex-direction: row; flex: 1; min-height: 0; }
+      :root[data-commentray-theme="dark"] .search-results mark.search-hit {
+        background: color-mix(in oklab, #c9a227 55%, Canvas);
+      }
+      .shell:not(.shell--stretch-rows) {
+        display: flex;
+        flex-direction: column;
+        flex: 1;
+        min-height: 0;
+        min-width: 0;
+        --split-pct: 46%;
+      }
       .app__main .shell { flex: 1 1 auto; }
+      .shell__panes {
+        display: flex;
+        flex-direction: row;
+        flex: 1 1 auto;
+        min-height: 0;
+        min-width: 0;
+      }
+      .shell__pair-context {
+        flex: 0 0 auto;
+        display: flex;
+        flex-direction: row;
+        align-items: stretch;
+        padding: 6px 0 8px;
+        border-bottom: 1px solid color-mix(in oklab, CanvasText 15%, Canvas);
+        background: color-mix(in oklab, CanvasText 3%, Canvas);
+        font-size: var(--cr-ui-fs);
+        line-height: 1.3;
+      }
+      .shell__pair-cell {
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        gap: 8px;
+        min-width: 0;
+      }
+      .shell__pair-cell--src {
+        flex: 0 0 var(--split-pct);
+        padding-left: var(--cr-pane-inline-pad);
+      }
+      .shell__pair-gutter-spacer {
+        flex: 0 0 14px;
+        min-width: 14px;
+        align-self: stretch;
+      }
+      .shell__pair-cell--doc {
+        flex: 1 1 auto;
+        min-width: 0;
+        padding-left: var(--cr-pane-inline-pad);
+      }
+      .shell__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;
+      }
+      .shell__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;
+      }
+      .shell__pair-path--secondary { opacity: 0.88; }
       .pane--code {
-        flex: 0 0 50%;
-        min-width: 120px; overflow: auto; padding: 12px 16px;
+        flex: 0 0 var(--split-pct, 46%);
+        min-width: 120px; overflow: auto; padding: 12px var(--cr-pane-inline-pad);
         border-right: 1px solid color-mix(in oklab, CanvasText 15%, Canvas);
         --code-line-font-size: 13px;
         --code-line-height: 1.5;
@@ -558,9 +1047,10 @@ const CODE_BROWSER_STYLES = `
       .pane--code .code-line-stack { --code-ln-min-ch: 3; }
       .pane--code .code-line {
         display: grid;
-        grid-template-columns: max-content 1fr;
+        grid-template-columns: max-content minmax(0, 1fr);
         column-gap: 10px;
         align-items: start;
+        min-width: 0;
       }
       .pane--code .code-line pre {
         margin: 0;
@@ -600,8 +1090,35 @@ 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) {
+        :root:is(:not([data-commentray-theme]), [data-commentray-theme="system"]) .gutter {
+          --commentray-ray-accent: #6eb0ff;
+        }
+      }
+      :root[data-commentray-theme="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 {
@@ -609,18 +1126,359 @@ const CODE_BROWSER_STYLES = `
       }
       .pane--doc {
         flex: 1 1 auto; min-width: 0; min-height: 0;
-        display: flex; flex-direction: column; overflow: hidden; padding: 12px 16px;
+        display: flex; flex-direction: column; overflow: hidden; padding: 12px var(--cr-pane-inline-pad);
+        background: Canvas;
+        color: CanvasText;
+      }
+      /* #doc-pane-body.wrap beats pre code.hljs from the hljs theme so fenced blocks follow the toggle. */
+      #doc-pane-body.wrap pre,
+      #doc-pane-body.wrap pre code {
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+      #doc-pane-body:not(.wrap) pre,
+      #doc-pane-body:not(.wrap) pre code {
+        white-space: pre;
+        word-break: normal;
       }
       .doc-pane-body {
         flex: 1 1 auto; min-height: 0; overflow: auto;
       }
+      /** Wide GFM tables: intrinsic width so the doc pane scrolls sideways instead of squeezing columns. */
+      .pane--doc .doc-pane-body :where(table) {
+        width: max-content;
+        max-width: none;
+        border-collapse: collapse;
+      }
+      .pane--doc .doc-pane-body .commentray-mermaid {
+        overflow-x: auto;
+        max-width: 100%;
+      }
+      /** Wrap on: break long URLs/words in prose; tables opt out so they stay wide + scroll with the body. */
+      #doc-pane-body.wrap {
+        overflow-wrap: break-word;
+      }
+      #doc-pane-body.wrap :where(table) {
+        overflow-wrap: normal;
+        word-break: normal;
+      }
+      #doc-pane-body:not(.wrap) {
+        overflow-wrap: normal;
+        word-break: normal;
+      }
       .toolbar-angle-picker {
-        display: inline-flex; align-items: center; gap: 6px; flex: 0 0 auto;
-        font-size: 12px; color: color-mix(in oklab, CanvasText 88%, Canvas);
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        flex: 0 0 auto;
+      }
+      /* Angle caption uses the same class as the Search label (.nav-rail__search-label). */
+      .toolbar-angle-picker__lab {
+        display: inline-block;
+        margin: 0;
+        padding: 0;
+        cursor: default;
+        flex: 0 0 auto;
+        white-space: nowrap;
+        user-select: none;
       }
       .toolbar-angle-picker select {
-        font: inherit; font-size: 12px; padding: 3px 8px; border-radius: 6px;
-        border: 1px solid color-mix(in oklab, CanvasText 25%, Canvas); background: Canvas; color: CanvasText;
+        font: inherit;
+        font-size: var(--cr-ui-fs);
+        font-weight: 500;
+        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: color-mix(in oklab, CanvasText 88%, Canvas);
+      }
+      .toolbar-angle-picker select:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      /* Single-pane + compact chrome below typical tablet / Bootstrap md threshold (768px). */
+      @media (max-width: 767px) {
+        html,
+        body {
+          overflow-x: auto;
+          overflow-y: auto;
+        }
+        .app {
+          height: auto;
+          min-height: 100vh;
+          min-height: 100dvh;
+          min-width: 0;
+          overflow-x: auto;
+          overflow-y: visible;
+        }
+        .app__main {
+          flex: 0 0 auto;
+          width: 100%;
+          min-height: 0;
+        }
+        .app__main > #shell:not(.shell--stretch-rows) {
+          flex: none !important;
+          min-height: auto !important;
+          overflow: visible !important;
+        }
+        .app__main > #shell:not(.shell--stretch-rows) .shell__panes {
+          flex: none !important;
+          min-height: auto !important;
+          min-width: 0;
+          width: 100%;
+          max-width: 100%;
+          box-sizing: border-box;
+        }
+        .app__main > #shell:not(.shell--stretch-rows) .pane--code,
+        .app__main > #shell:not(.shell--stretch-rows) .pane--doc {
+          flex: none !important;
+          min-height: auto !important;
+          overflow: visible !important;
+          max-height: none !important;
+          /* flex:none + basis:auto otherwise sizes to max-content so line-wrap has no width cap */
+          width: 100%;
+          max-width: 100%;
+          min-width: 0 !important;
+          box-sizing: border-box;
+        }
+        .app__main > #shell:not(.shell--stretch-rows) .pane--doc {
+          display: block;
+        }
+        .app__main > #shell:not(.shell--stretch-rows) .doc-pane-body {
+          flex: none !important;
+          min-height: auto !important;
+          min-width: 0;
+          overflow: visible !important;
+        }
+        .app__footer {
+          margin-top: auto;
+          flex-shrink: 0;
+          padding: 5px 10px 8px;
+          font-size: 10px;
+          line-height: 1.35;
+        }
+        .app__main > #shell.shell--stretch-rows {
+          flex: 1 1 auto;
+          min-height: min(72vh, 720px);
+          min-height: min(72dvh, 720px);
+          overflow: auto;
+        }
+        .toolbar {
+          padding: 5px 8px 5px;
+          row-gap: 4px;
+        }
+        .toolbar__primary {
+          display: flex;
+          flex-direction: row;
+          flex-wrap: nowrap;
+          align-items: center;
+          gap: 6px;
+          min-width: 0;
+          width: 100%;
+          box-sizing: border-box;
+        }
+        .toolbar__primary-main {
+          flex: 1 1 auto;
+          min-width: 0;
+          flex-wrap: nowrap;
+          overflow-x: auto;
+          overflow-y: visible;
+          -webkit-overflow-scrolling: touch;
+          gap: 6px;
+          scrollbar-width: thin;
+        }
+        .toolbar__primary-trail {
+          flex: 0 0 auto;
+          flex-wrap: nowrap;
+          align-self: center;
+        }
+        .toolbar-angle-picker {
+          position: relative;
+          flex: 0 1 auto;
+          min-width: 0;
+          max-width: 100%;
+        }
+        .toolbar-angle-picker__lab {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          padding: 0;
+          margin: -1px;
+          overflow: hidden;
+          clip: rect(0, 0, 0, 0);
+          white-space: nowrap;
+          border: 0;
+          opacity: 0;
+          pointer-events: none;
+        }
+        .toolbar-angle-picker select {
+          max-width: min(200px, 52vw);
+          min-width: 0;
+          text-overflow: ellipsis;
+        }
+        .app__chrome {
+          padding: 5px 8px 6px;
+          gap: 5px;
+          max-height: min(36vh, 360px);
+        }
+        /* Compact chrome: avoid heavy rings on inline fields (clear stays a real button). */
+        .chrome__search-row input[type="search"]:focus-visible {
+          outline: none;
+          border-color: color-mix(in oklab, CanvasText 42%, Canvas);
+        }
+        .chrome__search-row #search-clear:focus-visible {
+          outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+          outline-offset: 2px;
+        }
+        .chrome__search-label__caption {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          padding: 0;
+          margin: -1px;
+          overflow: hidden;
+          clip: rect(0, 0, 0, 0);
+          white-space: nowrap;
+          border: 0;
+        }
+        .chrome__search-label__glyph {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          padding: 0 2px;
+          margin: 0;
+          color: color-mix(in oklab, CanvasText 72%, Canvas);
+        }
+        .chrome__search-label__glyph:hover {
+          color: color-mix(in oklab, CanvasText 88%, Canvas);
+        }
+        .chrome__search-label:focus-within {
+          outline: none;
+        }
+        .chrome__search-label__glyph svg {
+          display: block;
+          flex: 0 0 auto;
+        }
+        .toolbar-angle-picker select:focus-visible {
+          outline: none;
+          border-color: color-mix(in oklab, CanvasText 42%, Canvas);
+        }
+        .toolbar-icon-btn--flip-only-narrow {
+          display: inline-flex;
+        }
+        /**
+         * Secondary flip: only on narrow viewports, only while the toolbar flip is off-screen
+         * (see client IntersectionObserver). Same control as toolbar; fixed so it stays reachable.
+         */
+        .toolbar-icon-btn--flip-scroll-narrow {
+          display: none;
+        }
+        #mobile-pane-flip-scroll.toolbar-icon-btn--flip-scroll-narrow.is-visible {
+          display: inline-flex;
+          position: fixed;
+          top: calc(10px + env(safe-area-inset-top, 0px));
+          right: calc(12px + env(safe-area-inset-right, 0px));
+          z-index: 50;
+          box-shadow:
+            0 1px 2px color-mix(in oklab, CanvasText 12%, transparent),
+            0 4px 14px color-mix(in oklab, CanvasText 18%, transparent);
+        }
+        /** Region connector lines are not needed on the narrow single-pane layout (gutter is hidden). */
+        .shell:not(.shell--stretch-rows) .gutter .gutter__rays {
+          opacity: 0 !important;
+          pointer-events: none !important;
+        }
+        .nav-rail__doc-hub-summary {
+          min-width: var(--cr-control-h);
+          padding: 0 10px;
+          justify-content: center;
+          gap: 0;
+        }
+        .nav-rail__doc-hub-summary__caption {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          padding: 0;
+          margin: -1px;
+          overflow: hidden;
+          clip: rect(0, 0, 0, 0);
+          white-space: nowrap;
+          border: 0;
+        }
+        .nav-rail__doc-hub-summary__glyph {
+          display: inline-flex;
+        }
+        .toolbar-wrap-lines {
+          min-width: var(--cr-control-h);
+          padding: 0;
+          justify-content: center;
+          gap: 0;
+          font-weight: 500;
+        }
+        .toolbar-wrap-lines__caption {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          padding: 0;
+          margin: -1px;
+          overflow: hidden;
+          clip: rect(0, 0, 0, 0);
+          white-space: nowrap;
+          border: 0;
+        }
+        .toolbar-wrap-lines__box {
+          display: none;
+        }
+        .toolbar-wrap-lines__face {
+          display: inline-flex;
+          position: relative;
+          width: 100%;
+          height: 100%;
+          min-height: var(--cr-control-h);
+          min-width: var(--cr-control-h);
+        }
+        .toolbar-wrap-lines:has(.toolbar-wrap-lines__input:checked) .toolbar-wrap-lines__face::after {
+          content: "✓";
+          position: absolute;
+          right: 1px;
+          bottom: 0;
+          font-size: 11px;
+          line-height: 1;
+          font-weight: 800;
+          color: CanvasText;
+          text-shadow: 0 0 2px Canvas, 0 0 3px Canvas;
+        }
+        .shell:not(.shell--stretch-rows)[data-dual-mobile-pane="code"] .pane--doc,
+        .shell:not(.shell--stretch-rows)[data-dual-mobile-pane="code"] .gutter {
+          display: none !important;
+        }
+        .shell:not(.shell--stretch-rows)[data-dual-mobile-pane="doc"] .pane--code,
+        .shell:not(.shell--stretch-rows)[data-dual-mobile-pane="doc"] .gutter {
+          display: none !important;
+        }
+        .shell:not(.shell--stretch-rows)[data-dual-mobile-pane="code"] .pane--code,
+        .shell:not(.shell--stretch-rows)[data-dual-mobile-pane="doc"] .pane--doc {
+          border-right: 0 !important;
+        }
+        .shell:not(.shell--stretch-rows) .shell__pair-context {
+          flex-direction: column;
+          align-items: stretch;
+          gap: 4px;
+          padding: 4px 0 6px;
+        }
+        .shell:not(.shell--stretch-rows) .shell__pair-gutter-spacer {
+          display: none;
+        }
+        .shell:not(.shell--stretch-rows) .shell__pair-cell--src {
+          flex: 1 1 auto;
+          padding-left: var(--cr-pane-inline-pad);
+        }
+        .shell:not(.shell--stretch-rows) .shell__pair-cell--doc {
+          flex: 1 1 auto;
+          padding-left: var(--cr-pane-inline-pad);
+        }
       }
       .pane--doc { font-size: 15px; line-height: 1.45; }
       .pane--doc img { max-width: 100%; height: auto; }
@@ -637,7 +1495,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; }
       .shell--stretch-rows {
         flex: 1;
         min-height: 0;
@@ -651,8 +1508,15 @@ const CODE_BROWSER_STYLES = `
         border-bottom: 1px solid color-mix(in oklab, CanvasText 12%, Canvas);
         font-size: 15px;
         line-height: 1.45;
+        overflow-x: auto;
+        max-width: 100%;
       }
       .shell--stretch-rows .stretch-preamble img { max-width: 100%; height: auto; }
+      .shell--stretch-rows .stretch-preamble :where(table) {
+        width: max-content;
+        max-width: none;
+        border-collapse: collapse;
+      }
       .block-stretch {
         width: 100%;
         border-collapse: collapse;
@@ -673,8 +1537,30 @@ const CODE_BROWSER_STYLES = `
       .block-stretch td.stretch-doc .stretch-doc-inner {
         font-size: 15px;
         line-height: 1.45;
+        min-width: 0;
+        overflow-x: auto;
       }
       .block-stretch td.stretch-doc .stretch-doc-inner img { max-width: 100%; height: auto; }
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(table) {
+        width: max-content;
+        max-width: none;
+        border-collapse: collapse;
+      }
+      .block-stretch td.stretch-doc .stretch-doc-inner .commentray-mermaid {
+        overflow-x: auto;
+        max-width: 100%;
+      }
+      .block-stretch.wrap td.stretch-doc .stretch-doc-inner {
+        overflow-wrap: break-word;
+      }
+      .block-stretch.wrap td.stretch-doc .stretch-doc-inner :where(table) {
+        overflow-wrap: normal;
+        word-break: normal;
+      }
+      .block-stretch:not(.wrap) td.stretch-doc .stretch-doc-inner {
+        overflow-wrap: normal;
+        word-break: normal;
+      }
       .block-stretch td.stretch-doc--gap {
         color: color-mix(in oklab, CanvasText 38%, Canvas);
         font-size: 13px;
@@ -721,68 +1607,117 @@ const CODE_BROWSER_STYLES = `
       .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.wrap .stretch-doc-inner pre,
+      .block-stretch.wrap .stretch-doc-inner pre code {
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+      .block-stretch:not(.wrap) .stretch-doc-inner pre,
+      .block-stretch:not(.wrap) .stretch-doc-inner pre code {
+        white-space: pre;
       }
-      .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";
+    const dualFlipControlHtml = p.layout === "dual"
+        ? `<button type="button" id="mobile-pane-flip" class="toolbar-icon-btn toolbar-icon-btn--flip-only-narrow" aria-label="Switch between source code and commentary" title="Switch between source code and commentary">${TOOLBAR_ICON_FLIP_PANES_SVG}</button>`
+        : "";
+    const dualFlipScrollAffordanceHtml = p.layout === "dual"
+        ? `<button type="button" id="mobile-pane-flip-scroll" class="toolbar-icon-btn toolbar-icon-btn--flip-scroll-narrow" hidden aria-label="Switch between source code and commentary" title="Switch between source code and commentary">${TOOLBAR_ICON_FLIP_PANES_SVG}</button>`
+        : "";
     return `<!doctype html>
-<html lang="en">
+<html lang="en" data-commentray-theme="system">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    ${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)" />
+    ${COMMENTRAY_FAVICON_LINK_HTML}
+    ${p.metaDescriptionHtml}${p.generatorMetaHtml}<title>${escapeHtml(p.title)}</title>
+    <link rel="stylesheet" id="commentray-hljs-light" 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" id="commentray-hljs-dark" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/styles/${escapeHtml(p.hljsDark)}.min.css" media="(prefers-color-scheme: dark)" />
+    <script>
+${commentrayColorThemeHeadBoot()}
+    </script>
     <style>
 ${CODE_BROWSER_STYLES}
     </style>
   </head>
   <body>
+    <a class="skip-link" href="#main-content">Skip to main content</a>
     <div class="app">
-      <header class="app__chrome" role="region" aria-label="Search and navigation">
+      <header class="toolbar" role="banner" aria-label="View options">
+        <h1 class="sr-only">${escapeHtml(p.title)}</h1>
+        <div class="toolbar__primary">
+          <div class="toolbar__primary-main">
+          ${p.toolbarSiteHubHtml}
+          ${p.navRailDocumentedHtml}
+          ${p.angleSelectHtml}
+          <label class="toolbar-wrap-lines" title="Wrap long lines in the source pane; in commentary, wrap long words and fenced code when on (wide tables and diagrams scroll horizontally).">
+            <input type="checkbox" id="wrap-lines" class="toolbar-wrap-lines__input" />
+            <span class="toolbar-wrap-lines__box" aria-hidden="true"></span>
+            <span class="toolbar-wrap-lines__face" aria-hidden="true">${TOOLBAR_ICON_WRAP_SVG}</span>
+            <span class="toolbar-wrap-lines__caption">Wrap lines</span>
+          </label>
+          ${dualFlipControlHtml}
+          ${p.toolbarDocHubHtml}
+          ${p.relatedNavHtml}
+          </div>
+          <div class="toolbar__primary-trail">
+        ${p.toolbarEndHtml}
+${TOOLBAR_COLOR_THEME_HTML}
+          </div>
+        </div>
+      </header>
+      ${dualFlipScrollAffordanceHtml}
+      <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>
+          <label class="chrome__search-label" for="search-q" aria-label="Search" title="Search"><span class="chrome__search-label__caption nav-rail__search-label">Search</span><span class="chrome__search-label__glyph" aria-hidden="true">${CHROME_ICON_SEARCH_SVG}</span></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>
+          <button type="button" id="search-clear" aria-label="Clear search" 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>
-      <div class="app__main">
-        <header class="toolbar" aria-label="View options">
-          <div class="toolbar__main">
-            ${p.navRailContextHtml}
-            ${p.navRailDocumentedHtml}
-            ${p.angleSelectHtml}
-            ${p.toolbarDocHubHtml}
-            ${p.relatedNavHtml}
-            <label><input type="checkbox" id="wrap-lines" /> Wrap code lines</label>
-          </div>
-          ${p.toolbarEndHtml}
-        </header>
-        <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}>
+      <main id="main-content" class="app__main" tabindex="-1">
+        <div class="${shellClass}" id="shell" data-layout="${p.layout}"${p.layout === "dual" ? ' data-dual-mobile-pane="doc"' : ""} 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.shellPairDocDataAttr}>
 ${p.shellInner}
         </div>
-      </div>
+      </main>
       ${p.pageFooterHtml}
     </div>
     <script type="text/plain" id="commentray-multi-angle-b64">${p.multiAngleScriptBlock}</script>
+    ${p.mermaidScript}
     <script>
 ${loadCodeBrowserClientBundle()}
     </script>
-    ${p.mermaidScript}
   </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
@@ -792,34 +1727,24 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
     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 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,
-        });
+        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({
-            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,
-        });
+        jsonAngles.push(jsonRow);
     }
     const selOpts = multi.angles
         .map((a) => {
@@ -827,18 +1752,9 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
         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">` +
-        `<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` +
-        `          ${defaultPaneHtml}\n` +
-        `          </div>\n` +
-        `        </section>\n`;
+    const angleSelectHtml = `<span class="toolbar-angle-picker"><label class="toolbar-angle-picker__lab nav-rail__search-label" for="angle-select">Angle</label><select id="angle-select" aria-label="Commentray angle">${selOpts}</select></span>`;
+    const pairHtml = renderShellPairContextHtml(opts.filePath, defaultPathSearch);
+    const shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, defaultPaneHtml));
     const payloadObj = { defaultAngleId: defaultId, angles: jsonAngles };
     const multiAnglePayloadB64 = Buffer.from(JSON.stringify(payloadObj), "utf8").toString("base64");
     return {
@@ -848,6 +1764,7 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
             scrollBlockLinksB64: defaultScrollB64,
             commentrayPathForSearch: defaultPathSearch,
             commentrayOnGithubUrl: defaultGh,
+            ...(defaultStaticBrowse.length > 0 ? { commentrayStaticBrowseUrl: defaultStaticBrowse } : {}),
         },
         angleSelectHtml,
         multiAnglePayloadB64,
@@ -883,13 +1800,7 @@ 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") {
@@ -906,18 +1817,8 @@ async function buildCodeBrowserShell(opts, layoutPref) {
                 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`;
+        const pairHtml = renderShellPairContextHtml(opts.filePath, (opts.commentrayPathForSearch ?? "").trim());
+        shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, commentrayHtml));
     }
     return {
         layout,
@@ -949,22 +1850,30 @@ function shellDocumentedPairsAttrFromOptions(opts) {
 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 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 ??
+/** Canonical doc target for static validation: same-site `./browse/…` when present, else GitHub blob. */
+function shellPairDocDataAttr(shell, opts) {
+    if (shell.layout !== "dual")
+        return "";
+    const browseRaw = (shell.multiShell?.commentrayStaticBrowseUrl ??
+        opts.commentrayStaticBrowseUrl ??
         "").trim();
-    return trimmed.length > 0 ? trimmed : undefined;
+    if (browseRaw.length > 0) {
+        const href = safeToolbarNavigationHref(browseRaw);
+        if (href !== null) {
+            return ` data-commentray-pair-browse-href="${escapeHtml(href)}"`;
+        }
+    }
+    const gh = safeExternalHttpUrl(toolbarCommentrayGithubFromShell(shell, opts));
+    if (gh !== null) {
+        return ` data-commentray-pair-browse-href="${escapeHtml(gh)}"`;
+    }
+    return "";
 }
 function shellSearchAttrsWithNavJson(shellSearchAttrsBase, documentedNavJsonUrl) {
     const navJson = documentedNavJsonUrl?.trim() ?? "";
@@ -980,11 +1889,17 @@ function shellSearchAttrsWithNavJson(shellSearchAttrsBase, documentedNavJsonUrl)
 export async function renderCodeBrowserHtml(opts) {
     const rawCodeB64 = Buffer.from(opts.code, "utf8").toString("base64");
     const title = codeBrowserPageTitle(opts);
+    const metaDescriptionHtml = renderMetaDescriptionHtml(opts, title);
     const builtAt = opts.builtAt ?? new Date();
     const renderSemver = commentrayRenderVersion();
-    const toolbarEndHtml = buildToolbarEndHtml(opts.githubRepoUrl, opts.toolHomeUrl, renderSemver);
-    const pageFooterHtml = renderPageFooterHtml(builtAt);
-    const { hljs, hljsDark } = codeBrowserHljsThemes(opts);
+    const toolbarSiteHubHtml = buildToolbarSiteHubHtml(opts.siteHubUrl);
+    const toolbarEndHtml = buildToolbarEndHtml(opts.githubRepoUrl, opts.siteHubUrl);
+    const pageFooterHtml = renderPageFooterHtml({
+        builtAt,
+        toolHomeUrl: opts.toolHomeUrl,
+        commentrayRenderSemver: renderSemver,
+    });
+    const { hljsLight, hljsDark } = hljsStylesheetThemes(opts.hljsTheme);
     const mermaidScript = mermaidRuntimeScriptHtml(opts.includeMermaidRuntime);
     const relatedNavHtml = renderRelatedGithubNavHtml(opts.relatedGithubNav ?? []);
     const generatorMetaHtml = renderGeneratorMetaHtml(opts.generatorLabel);
@@ -999,14 +1914,13 @@ export async function renderCodeBrowserHtml(opts) {
     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),
-    });
+    const pairDocDataAttr = shellPairDocDataAttr(shell, opts);
     return buildCodeBrowserPageHtml({
         title,
+        metaDescriptionHtml,
         generatorMetaHtml,
-        navRailContextHtml,
+        toolbarSiteHubHtml,
+        shellPairDocDataAttr: pairDocDataAttr,
         angleSelectHtml: shell.angleSelectHtml,
         toolbarDocHubHtml,
         navRailDocumentedHtml,
@@ -1019,7 +1933,7 @@ export async function renderCodeBrowserHtml(opts) {
         rawMdB64,
         scrollBlockLinksB64,
         shellDocumentedPairsAttr,
-        hljs,
+        hljs: hljsLight,
         hljsDark,
         mermaidScript,
         searchPlaceholder,