@commentray/render 0.0.6 → 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";
@@ -134,6 +136,29 @@ const GITHUB_MARK_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16
 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)
@@ -158,27 +183,32 @@ function buildToolbarSiteHubHtml(siteHubUrl) {
     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) {
+/** 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 (!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>`);
@@ -200,7 +230,7 @@ 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">Comment-rayed 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>
@@ -212,44 +242,49 @@ function renderToolbarDocHubHtml(opts) {
         : "";
     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);
-    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 === "") {
+    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 : "—";
-    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>
+    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");
@@ -257,18 +292,51 @@ 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;
         --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;
@@ -354,16 +422,23 @@ const CODE_BROWSER_STYLES = `
       }
       .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;
         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;
+        white-space: nowrap;
+      }
+      .chrome__search-row #search-clear:hover {
+        background: color-mix(in oklab, CanvasText 11%, Canvas);
       }
       .chrome__search-row input[type="search"]:focus-visible,
       .chrome__search-row #search-clear:focus-visible {
@@ -372,92 +447,17 @@ const CODE_BROWSER_STYLES = `
       }
       .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;
+        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: 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);
+      /* Wide viewports: same legible caps word as historic Pages shell (icon hidden). */
+      .chrome__search-label__glyph {
+        display: none;
       }
       .nav-rail__search-label {
         font-size: var(--cr-label-caps-fs);
@@ -466,16 +466,6 @@ const CODE_BROWSER_STYLES = `
         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;
@@ -489,16 +479,33 @@ const CODE_BROWSER_STYLES = `
       .nav-rail__doc-hub-summary {
         cursor: pointer;
         font-size: var(--cr-ui-fs);
-        font-weight: 600;
+        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.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 {
         position: absolute;
@@ -572,20 +579,52 @@ const CODE_BROWSER_STYLES = `
       .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;
+        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__main {
-        display: flex; flex-wrap: wrap; align-items: center; gap: 10px 14px;
+      .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__end {
-        display: flex; flex-wrap: wrap; align-items: center; gap: 10px 14px;
+      .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;
@@ -603,31 +642,227 @@ const CODE_BROWSER_STYLES = `
       }
       .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: var(--cr-ui-fs);
-        line-height: 1.35;
-        opacity: 0.85;
-        max-width: min(360px, 42vw);
-        text-align: right;
+      .app__footer-attribution {
+        margin: 0;
         color: color-mix(in oklab, CanvasText 88%, Canvas);
       }
-      .toolbar-attribution a { color: inherit; font-weight: 600; text-decoration: underline; text-underline-offset: 2px; }
+      .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__main > label:has(#wrap-lines) {
+      .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: color-mix(in oklab, CanvasText 4%, 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;
-        gap: 8px;
+        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-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-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-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-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 .file-path {
         font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
         font-size: var(--cr-ui-fs);
@@ -640,9 +875,10 @@ 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);
@@ -650,7 +886,7 @@ const CODE_BROWSER_STYLES = `
         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;
@@ -727,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;
@@ -743,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;
@@ -790,7 +1095,12 @@ const CODE_BROWSER_STYLES = `
         --commentray-ray-accent: #3b7dd8;
       }
       @media (prefers-color-scheme: dark) {
-        .gutter { --commentray-ray-accent: #6eb0ff; }
+        :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;
@@ -816,40 +1126,360 @@ 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: 8px;
+        gap: 6px;
         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;
+      /* 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: 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: CanvasText;
+        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; }
       .pane--doc .commentray-line-anchor {
@@ -878,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;
@@ -900,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;
@@ -948,19 +1607,38 @@ 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.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;
+      }
 `;
 /** 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" />
+    ${COMMENTRAY_FAVICON_LINK_HTML}
     ${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)" />
+    <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>
@@ -970,38 +1648,48 @@ ${CODE_BROWSER_STYLES}
     <div class="app">
       <header class="toolbar" role="banner" aria-label="View options">
         <h1 class="sr-only">${escapeHtml(p.title)}</h1>
-        <div class="toolbar__main">
+        <div class="toolbar__primary">
+          <div class="toolbar__primary-main">
           ${p.toolbarSiteHubHtml}
-          ${p.navRailContextHtml}
           ${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}
-          <label><input type="checkbox" id="wrap-lines" /> Wrap code lines</label>
-        </div>
+          </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>
       <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}>
+        <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>
       </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>`;
 }
@@ -1064,16 +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">` +
-        `          ${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 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 {
@@ -1136,16 +1817,8 @@ async function buildCodeBrowserShell(opts, layoutPref) {
                 commentrayOutputUrls: opts.commentrayOutputUrls,
             }),
         ]);
-        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` +
-                `          ${commentrayHtml}\n` +
-                `          </div>\n` +
-                `        </section>\n`;
+        const pairHtml = renderShellPairContextHtml(opts.filePath, (opts.commentrayPathForSearch ?? "").trim());
+        shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, commentrayHtml));
     }
     return {
         layout,
@@ -1177,28 +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 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 ??
+/** 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() ?? "";
@@ -1218,9 +1893,13 @@ export async function renderCodeBrowserHtml(opts) {
     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 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);
@@ -1235,17 +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),
-        commentrayStaticBrowseUrl: toolbarCommentrayStaticBrowseFromShell(shell, opts),
-    });
+    const pairDocDataAttr = shellPairDocDataAttr(shell, opts);
     return buildCodeBrowserPageHtml({
         title,
         metaDescriptionHtml,
         generatorMetaHtml,
         toolbarSiteHubHtml,
-        navRailContextHtml,
+        shellPairDocDataAttr: pairDocDataAttr,
         angleSelectHtml: shell.angleSelectHtml,
         toolbarDocHubHtml,
         navRailDocumentedHtml,
@@ -1258,7 +1933,7 @@ export async function renderCodeBrowserHtml(opts) {
         rawMdB64,
         scrollBlockLinksB64,
         shellDocumentedPairsAttr,
-        hljs,
+        hljs: hljsLight,
         hljsDark,
         mermaidScript,
         searchPlaceholder,