@commentray/render 0.0.9 → 0.1.1

package/dist/code-browser.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { MARKER_ID_BODY, buildBlockScrollLinks, findMonorepoPackagesDir, monorepoLayoutStartDir, } from "@commentray/core";
+import path, { join } from "node:path";
+import { buildBlockScrollLinks, findMonorepoPackagesDir, monorepoLayoutStartDir, normalizeRepoRelativePath, } from "@commentray/core";
 import { tryBuildBlockStretchTableHtml } from "./block-stretch-layout.js";
 import { formatCommentrayBuiltAtLocal } from "./build-stamp.js";
 import { escapeHtml } from "./html-utils.js";
@@ -11,12 +11,28 @@ 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";
+import { normPosixPath } from "./code-browser-pair-nav.js";
+import { injectCommentrayDocAnchors, injectSourceMarkdownAnchors, } from "./inject-md-line-anchors.js";
 function renderGeneratorMetaHtml(label) {
     const t = label?.trim();
     if (!t)
         return "";
     return `<meta name="generator" content="${escapeHtml(t)}" />\n    `;
 }
+/** Accepts short or full SHA; returns lowercase hex or undefined if the string is not a Git object name. */
+function normalizePagesBuildCommitSha(raw) {
+    const t = raw?.trim();
+    if (!t)
+        return undefined;
+    const lower = t.toLowerCase();
+    if (!/^[0-9a-f]{7,40}$/.test(lower))
+        return undefined;
+    return lower;
+}
+function footerCommitSuffixHtml(commitSha) {
+    const esc = escapeHtml(commitSha);
+    return ` · <code class="app__footer-attribution__sha" translate="no">${esc}</code>`;
+}
 const META_DESCRIPTION_MAX_LEN = 320;
 function codeBrowserMetaDescription(opts, title) {
     const custom = opts.metaDescription?.trim();
@@ -29,105 +45,6 @@ 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) {
-    let end = s.length;
-    while (end > 0) {
-        const c = s[end - 1];
-        if (c !== " " && c !== "\t")
-            break;
-        end--;
-    }
-    return s.slice(0, end);
-}
-function isSetextUnderlineLine(line) {
-    const t = trimEndSpacesTabs(line);
-    return /^\s{0,3}=+\s*$/.test(t) || /^\s{0,3}-+\s*$/.test(t);
-}
-function isThematicBreakLine(line) {
-    const t = trimEndSpacesTabs(line);
-    return (/^\s{0,3}(?:\*[ \t]*){3,}\s*$/.test(t) ||
-        /^\s{0,3}(?:-[ \t]*){3,}\s*$/.test(t) ||
-        /^\s{0,3}(?:_[ \t]*){3,}\s*$/.test(t));
-}
-function parseFenceDelimiter(line) {
-    const t = trimEndSpacesTabs(line);
-    const m = /^(\s{0,3})(`{3,}|~{3,})(.*)$/.exec(t);
-    if (!m)
-        return null;
-    const run = m[2];
-    const head = run[0];
-    if (head !== "`" && head !== "~")
-        return null;
-    const ch = head === "`" ? "`" : "~";
-    return { ch, runLen: run.length, rest: m[3] ?? "" };
-}
-function isClosingFenceLine(info, open) {
-    if (info.ch !== open.ch || info.runLen < open.len)
-        return false;
-    return info.rest.trim() === "";
-}
-function lineAnchorHtml(mdLine0) {
-    const mdLine = String(mdLine0);
-    return `<span class="commentray-line-anchor" data-commentray-md-line="${mdLine}" id="commentray-md-line-${mdLine}" aria-hidden="true"></span>`;
-}
-function appendMdLineAnchorWhenAllowed(line, mdLine0) {
-    if (isSetextUnderlineLine(line) || isThematicBreakLine(line))
-        return line;
-    /** Blank lines must stay blank: a line that is only `<span …>` breaks CommonMark HTML / paragraph starts after block markers. */
-    if (line === "")
-        return "";
-    return `${line}${lineAnchorHtml(mdLine0)}`;
-}
-/**
- * Inserts per-line anchors for search / hash jumps and block separator anchors after each
- * `<!-- commentray:block … -->` line (optional index attrs).
- *
- * Anchors are appended to the line when safe. A **leading** `<span>` breaks CommonMark block
- * recognition (`#` headings, lists, thematic breaks, fences). Fenced code lines must not get a
- * trailing anchor either (would corrupt fence delimiters or appear inside code).
- */
-function injectCommentrayDocAnchors(markdown, links) {
-    const byId = links ? new Map(links.map((l) => [l.id, l])) : undefined;
-    const lines = markdown.split("\n");
-    let fence = null;
-    const out = [];
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const delim = parseFenceDelimiter(line);
-        if (fence) {
-            if (delim && isClosingFenceLine(delim, fence)) {
-                fence = null;
-                out.push(line);
-                continue;
-            }
-            out.push(line);
-            continue;
-        }
-        if (delim) {
-            fence = { ch: delim.ch, len: delim.runLen };
-            out.push(line);
-            continue;
-        }
-        const m = BLOCK_MARKER_HTML_LINE.exec(line);
-        if (m?.[1]) {
-            const id = m[1];
-            const link = byId?.get(id);
-            const attrs = link !== undefined
-                ? ` data-source-start="${String(link.sourceStart)}" data-commentray-line="${String(link.commentrayLine)}"`
-                : "";
-            /** One `push` with embedded `\n\n` merged poorly with `join("\\n")`; keep real blank lines around raw `<div>`. */
-            out.push(`${line}${lineAnchorHtml(i)}`);
-            out.push("");
-            out.push(`<div id="commentray-block-${escapeHtml(id)}" class="commentray-block-anchor" aria-hidden="true"${attrs}></div>`);
-            out.push("");
-            continue;
-        }
-        out.push(appendMdLineAnchorWhenAllowed(line, i));
-    }
-    return out.join("\n");
-}
 /** GitHub “mark” glyph (Octicons-style path), MIT-licensed silhouette. */
 const GITHUB_MARK_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="20" height="20" fill="currentColor" aria-hidden="true">' +
     '<path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/>' +
@@ -159,6 +76,25 @@ const TOOLBAR_ICON_FLIP_PANES_SVG = '<svg xmlns="http://www.w3.org/2000/svg" vie
     '<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>";
+/** Source markdown mode flip: rendered page <-> plain markdown rows. */
+const TOOLBAR_ICON_FLIP_SOURCE_MARKDOWN_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">' +
+    '<rect x="3" y="4" width="8" height="16" rx="1.5"/>' +
+    '<path d="M6 8h2M6 11h2M6 14h2"/>' +
+    '<rect x="13" y="4" width="8" height="16" rx="1.5"/>' +
+    '<path d="m15.5 12 2-2 2 2"/>' +
+    '<path d="m19.5 12-2 2-2-2"/>' +
+    "</svg>";
+/** Link/share glyph for copying a permalink to the current documentation pair. */
+const TOOLBAR_ICON_SHARE_LINK_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="M10 14a5 5 0 0 0 7.07 0l2.83-2.83a5 5 0 0 0-7.07-7.07L10 6"/>' +
+    '<path d="M14 10a5 5 0 0 0-7.07 0L4.1 12.83a5 5 0 0 0 7.07 7.07L14 17"/>' +
+    "</svg>";
+/** Help glyph for re-running the onboarding walkthrough. */
+const TOOLBAR_ICON_HELP_TOUR_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="M9.1 9a3 3 0 1 1 4.92 2.3c-.8.6-1.52 1.08-1.52 2.2"/>' +
+    '<circle cx="12" cy="17" r="0.8" fill="currentColor" stroke="none"/>' +
+    "</svg>";
 function safeExternalHttpUrl(url) {
     const t = url?.trim();
     if (!t)
@@ -194,9 +130,10 @@ function buildToolbarEndHtml(githubRepoUrl, siteHubUrl) {
     return "";
 }
 function renderPageFooterHtml(input) {
-    const { builtAt, toolHomeUrl, commentrayRenderSemver } = input;
+    const { builtAt, toolHomeUrl, commentrayRenderSemver, pagesBuildCommitSha } = input;
     const iso = builtAt.toISOString();
     const human = formatCommentrayBuiltAtLocal(builtAt);
+    const commitSuffix = pagesBuildCommitSha ? footerCommitSuffixHtml(pagesBuildCommitSha) : "";
     const tool = safeExternalHttpUrl(toolHomeUrl);
     if (tool) {
         const te = escapeHtml(tool);
@@ -206,11 +143,14 @@ function renderPageFooterHtml(input) {
             `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>` +
+            commitSuffix +
             `</p>` +
             `</footer>`);
     }
     return (`<footer class="app__footer" role="contentinfo">` +
-        `<p class="app__footer-line">HTML generated <time datetime="${escapeHtml(iso)}">${escapeHtml(human)}</time></p>` +
+        `<p class="app__footer-line">HTML generated <time datetime="${escapeHtml(iso)}">${escapeHtml(human)}</time>` +
+        commitSuffix +
+        `</p>` +
         `</footer>`);
 }
 function renderRelatedGithubNavHtml(links) {
@@ -242,9 +182,13 @@ function renderToolbarDocHubHtml(opts) {
         : "";
     return { toolbarDocHubHtml, navRailDocumentedHtml };
 }
-function dualPanePanesInnerHtml(codeHtml, commentrayHtml) {
+function dualPanePanesInnerHtml(codeHtml, commentrayHtml, sourceMarkdownRenderedHtml) {
+    const sourceRenderedPaneHtml = typeof sourceMarkdownRenderedHtml === "string" && sourceMarkdownRenderedHtml.trim().length > 0
+        ? `          <div class="source-pane source-pane--rendered-md" id="code-pane-markdown-body">${sourceMarkdownRenderedHtml}</div>\n`
+        : "";
     return (`        <section class="pane--code" id="code-pane" aria-label="Source code">` +
-        `          ${codeHtml}\n` +
+        `          <div class="source-pane source-pane--code" id="code-pane-code-body">${codeHtml}</div>\n` +
+        sourceRenderedPaneHtml +
         `        </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` +
@@ -253,7 +197,42 @@ function dualPanePanesInnerHtml(codeHtml, commentrayHtml) {
         `          </div>\n` +
         `        </section>\n`);
 }
-/** Plain-text Src/Doc labels above the panes; column widths track the resizable split via `--split-pct`. */
+function sourceMarkdownToggleControlsHtml(enabled) {
+    if (!enabled) {
+        return { sourceMarkdownToggleHtml: "", sourceMarkdownFlipScrollAffordanceHtml: "" };
+    }
+    const label = "Switch source pane between rendered markdown and markdown source";
+    const title = "Switch source pane between rendered markdown and markdown source";
+    const btn = `<button type="button" id="source-markdown-pane-flip" class="toolbar-source-render-toggle" aria-controls="code-pane" aria-pressed="false" aria-label="${label}" title="${title}"><span class="toolbar-source-render-toggle__box" aria-hidden="true"></span><span class="toolbar-source-render-toggle__face" aria-hidden="true">${TOOLBAR_ICON_FLIP_SOURCE_MARKDOWN_SVG}</span><span class="toolbar-source-render-toggle__caption">Render</span></button>`;
+    const floating = `<button type="button" id="source-markdown-pane-flip-scroll" class="toolbar-icon-btn toolbar-icon-btn--source-markdown-scroll-narrow" hidden aria-controls="code-pane" aria-pressed="false" aria-label="${label}" title="${title}">${TOOLBAR_ICON_FLIP_SOURCE_MARKDOWN_SVG}</button>`;
+    return {
+        sourceMarkdownToggleHtml: btn,
+        sourceMarkdownFlipScrollAffordanceHtml: floating,
+    };
+}
+function isMarkdownLikeSource(opts) {
+    const lang = opts.language.trim().toLowerCase();
+    if (lang === "md" || lang === "markdown" || lang === "mdx")
+        return true;
+    const filePath = (opts.filePath ?? "").trim().toLowerCase();
+    return filePath.endsWith(".md") || filePath.endsWith(".mdx") || filePath.endsWith(".markdown");
+}
+/** For source-pane Markdown, resolve local links from the source file directory (repo tree), not companion storage. */
+function sourcePaneOutputUrls(opts) {
+    const out = opts.commentrayOutputUrls;
+    if (!out)
+        return undefined;
+    const srcRel = (opts.filePath ?? "").trim();
+    if (srcRel.length === 0)
+        return out;
+    const repoRoot = path.resolve(out.repoRootAbs);
+    const candidate = path.resolve(repoRoot, srcRel);
+    const rel = path.relative(repoRoot, candidate);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return out;
+    return { ...out, markdownUrlBaseDirAbs: path.dirname(candidate) };
+}
+/** Pair paths above the panes; column widths track the resizable split via `--split-pct`. */
 function renderShellPairContextHtml(filePath, commentrayPath) {
     const fpRaw = (filePath ?? "").trim();
     const crRaw = (commentrayPath ?? "").trim();
@@ -265,12 +244,10 @@ function renderShellPairContextHtml(filePath, commentrayPath) {
     const crDisp = crRaw.length > 0 ? cr : "—";
     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>`;
@@ -292,6 +269,19 @@ function loadCodeBrowserClientBundle() {
     }
     throw new Error("Missing code-browser-client.bundle.js. Run `npm run build -w @commentray/render` to bundle the browser client.");
 }
+/** Intro-tour specific stylesheet; kept in a dedicated CSS file for easier tweaking. */
+function loadCodeBrowserIntroStyles() {
+    const packagesDir = findMonorepoPackagesDir(monorepoLayoutStartDir(import.meta.url));
+    const renderDistDir = join(packagesDir, "render", "dist");
+    const inDist = join(renderDistDir, "code-browser-intro.css");
+    const fromSrc = join(packagesDir, "render", "src", "code-browser-intro.css");
+    for (const p of [inDist, fromSrc]) {
+        if (existsSync(p)) {
+            return readFileSync(p, "utf8");
+        }
+    }
+    throw new Error("Missing code-browser-intro.css. Ensure the render package includes intro tour styles.");
+}
 /**
  * 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.
@@ -309,6 +299,11 @@ const TOOLBAR_COLOR_THEME_HTML = `          <div class="toolbar-theme">
             </div>
           </div>
 `;
+const TOOLBAR_SHARE_LINK_HTML = `          <button type="button" id="commentray-share-link" class="toolbar-theme__trigger toolbar-share-link-btn" aria-label="Copy shareable permalink" title="Copy shareable permalink">${TOOLBAR_ICON_SHARE_LINK_SVG}</button>
+`;
+const TOOLBAR_HELP_TOUR_HTML = `          <button type="button" id="commentray-help-tour" class="toolbar-theme__trigger toolbar-help-tour-btn" aria-label="Restart onboarding walkthrough" title="Restart onboarding walkthrough">${TOOLBAR_ICON_HELP_TOUR_SVG}</button>
+`;
+const CODE_BROWSER_INTRO_STYLES = loadCodeBrowserIntroStyles();
 const CODE_BROWSER_STYLES = `
       :root {
         --cr-control-h: 32px;
@@ -653,7 +648,15 @@ const CODE_BROWSER_STYLES = `
         text-underline-offset: 2px;
       }
       .app__footer-attribution__version { font-weight: 600; }
+      .app__footer-attribution__sha {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+        font-size: 0.95em;
+        font-weight: 500;
+        padding: 0 2px;
+        word-break: break-all;
+      }
       .toolbar label { display: inline-flex; align-items: center; gap: 6px; cursor: pointer; user-select: none; }
+      .toolbar label[hidden] { display: none !important; }
       .toolbar-wrap-lines {
         position: relative;
         margin: 0;
@@ -772,6 +775,80 @@ const CODE_BROWSER_STYLES = `
         outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
         outline-offset: 2px;
       }
+      .toolbar-source-render-toggle {
+        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-source-render-toggle:hover {
+        background: color-mix(in oklab, CanvasText 6%, Canvas);
+      }
+      .toolbar-source-render-toggle__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-source-render-toggle[aria-pressed="true"] .toolbar-source-render-toggle__box {
+        border-color: color-mix(in oklab, CanvasText 52%, Canvas);
+        background: color-mix(in oklab, CanvasText 6%, Canvas);
+      }
+      .toolbar-source-render-toggle__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-source-render-toggle[aria-pressed="true"] .toolbar-source-render-toggle__box::after {
+        display: block;
+      }
+      .toolbar-source-render-toggle__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-source-render-toggle__caption {
+        white-space: nowrap;
+      }
+      .toolbar-source-render-toggle[aria-pressed="true"] {
+        color: CanvasText;
+        background: color-mix(in oklab, CanvasText 10%, Canvas);
+      }
+      .toolbar-source-render-toggle:focus-visible {
+        outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
+        outline-offset: 2px;
+      }
+      .toolbar-icon-btn--source-markdown {
+        display: inline-flex;
+      }
+${CODE_BROWSER_INTRO_STYLES}
       .toolbar label input:focus-visible {
         outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
         outline-offset: 2px;
@@ -810,6 +887,16 @@ const CODE_BROWSER_STYLES = `
         outline: 2px solid color-mix(in oklab, CanvasText 45%, Canvas);
         outline-offset: 2px;
       }
+      .toolbar-theme__trigger svg {
+        width: var(--cr-icon-inner);
+        height: var(--cr-icon-inner);
+        display: block;
+        flex: 0 0 auto;
+      }
+      .toolbar-share-link-btn[data-copied="true"] {
+        background: color-mix(in oklab, #2ea043 24%, Canvas);
+        border-color: color-mix(in oklab, #2ea043 48%, CanvasText);
+      }
       .toolbar-theme__trigger .toolbar-theme__icon {
         display: none;
         flex: 0 0 auto;
@@ -917,6 +1004,14 @@ const CODE_BROWSER_STYLES = `
       .documented-files-tree .tree-file-link:hover {
         opacity: 0.92;
       }
+      .documented-files-tree .tree-file-link.tree-file-link--current {
+        font-weight: 600;
+        text-decoration-thickness: 2px;
+        border-radius: 3px;
+        padding: 1px 3px;
+        margin: -1px -3px;
+        background: color-mix(in oklab, CanvasText 10%, Canvas);
+      }
       .toolbar button {
         font: inherit;
         font-size: var(--cr-ui-fs);
@@ -1018,14 +1113,6 @@ const CODE_BROWSER_STYLES = `
         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;
@@ -1044,6 +1131,31 @@ const CODE_BROWSER_STYLES = `
         --code-line-font-size: 13px;
         --code-line-height: 1.5;
       }
+      .source-pane {
+        min-width: 0;
+      }
+      .source-pane--rendered-md {
+        font-size: 15px;
+        line-height: 1.45;
+      }
+      .source-pane--rendered-md img {
+        max-width: 100%;
+        height: auto;
+      }
+      .source-pane--rendered-md .commentray-mermaid {
+        overflow-x: auto;
+        max-width: 100%;
+      }
+      .source-pane--rendered-md .commentray-line-anchor--source {
+        display: inline;
+        vertical-align: baseline;
+      }
+      #shell[data-source-pane-mode="rendered-markdown"] .source-pane--code {
+        display: none;
+      }
+      #shell[data-source-pane-mode="source"] .source-pane--rendered-md {
+        display: none;
+      }
       .pane--code .code-line-stack { --code-ln-min-ch: 3; }
       .pane--code .code-line {
         display: grid;
@@ -1105,7 +1217,12 @@ const CODE_BROWSER_STYLES = `
       .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 svg {
+        width: 100%;
+        height: 100%;
+        display: block;
+        overflow: hidden;
+      }
       .gutter__rays-path {
         fill: none; stroke-linecap: round; vector-effect: non-scaling-stroke;
         stroke: color-mix(in oklab, var(--commentray-ray-accent) 72%, CanvasText);
@@ -1144,11 +1261,95 @@ const CODE_BROWSER_STYLES = `
       .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) {
+      /* Inline backtick code chips (GitHub-like): prose context only, never fenced pre/code blocks. */
+      .pane--doc .doc-pane-body :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code,
+      .shell--stretch-rows .stretch-preamble :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code,
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+        font-size: 0.92em;
+        padding: 0.12em 0.36em;
+        border-radius: 6px;
+        border: 1px solid color-mix(in oklab, CanvasText 12%, Canvas);
+        background: color-mix(in oklab, CanvasText 8%, Canvas);
+        color: inherit;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root:is(:not([data-commentray-theme]), [data-commentray-theme="system"]) .pane--doc .doc-pane-body :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code,
+        :root:is(:not([data-commentray-theme]), [data-commentray-theme="system"]) .shell--stretch-rows .stretch-preamble :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code,
+        :root:is(:not([data-commentray-theme]), [data-commentray-theme="system"]) .block-stretch td.stretch-doc .stretch-doc-inner :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code {
+          border-color: color-mix(in oklab, CanvasText 26%, Canvas);
+          background: color-mix(in oklab, CanvasText 16%, Canvas);
+        }
+      }
+      :root[data-commentray-theme="dark"] .pane--doc .doc-pane-body :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code,
+      :root[data-commentray-theme="dark"] .shell--stretch-rows .stretch-preamble :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code,
+      :root[data-commentray-theme="dark"] .block-stretch td.stretch-doc .stretch-doc-inner :where(p, li, blockquote, td, th, h1, h2, h3, h4, h5, h6) > code {
+        border-color: color-mix(in oklab, CanvasText 26%, Canvas);
+        background: color-mix(in oklab, CanvasText 16%, Canvas);
+      }
+      /**
+       * GFM tables in rendered Markdown (doc pane, stretch preamble, per-block doc cells).
+       * Intrinsic width so the pane scrolls sideways instead of squeezing columns; borders
+       * and padding match familiar GitHub-style readability.
+       */
+      .pane--doc .doc-pane-body :where(table),
+      .shell--stretch-rows .stretch-preamble :where(table),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(table) {
         width: max-content;
         max-width: none;
         border-collapse: collapse;
+        margin: 0.85em 0;
+        font-size: inherit;
+        line-height: inherit;
+      }
+      .pane--doc .doc-pane-body :where(th, td),
+      .shell--stretch-rows .stretch-preamble :where(th, td),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(th, td) {
+        border: 1px solid color-mix(in oklab, CanvasText 22%, Canvas);
+        padding: 8px 12px;
+        vertical-align: top;
+      }
+      .pane--doc .doc-pane-body :where(thead th),
+      .shell--stretch-rows .stretch-preamble :where(thead th),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(thead th) {
+        font-weight: 600;
+        background: color-mix(in oklab, CanvasText 7%, Canvas);
+      }
+      .pane--doc .doc-pane-body tbody tr:nth-child(even) :where(td),
+      .shell--stretch-rows .stretch-preamble tbody tr:nth-child(even) :where(td),
+      .block-stretch td.stretch-doc .stretch-doc-inner tbody tr:nth-child(even) :where(td) {
+        background: color-mix(in oklab, CanvasText 3.5%, Canvas);
+      }
+      .pane--doc .doc-pane-body :where(ul.contains-task-list),
+      .shell--stretch-rows .stretch-preamble :where(ul.contains-task-list),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(ul.contains-task-list) {
+        list-style: none;
+        padding-inline-start: 1.2em;
+      }
+      .pane--doc .doc-pane-body :where(li.task-list-item),
+      .shell--stretch-rows .stretch-preamble :where(li.task-list-item),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(li.task-list-item) {
+        position: relative;
+      }
+      .pane--doc .doc-pane-body :where(li.task-list-item input[type="checkbox"]),
+      .shell--stretch-rows .stretch-preamble :where(li.task-list-item input[type="checkbox"]),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(li.task-list-item input[type="checkbox"]) {
+        position: absolute;
+        margin-inline-start: -1.35em;
+        margin-top: 0.2em;
+      }
+      .pane--doc .doc-pane-body :where(del),
+      .shell--stretch-rows .stretch-preamble :where(del),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(del) {
+        opacity: 0.82;
+      }
+      .pane--doc .doc-pane-body :where(section.footnotes),
+      .shell--stretch-rows .stretch-preamble :where(section.footnotes),
+      .block-stretch td.stretch-doc .stretch-doc-inner :where(section.footnotes) {
+        margin-top: 1.5em;
+        padding-top: 0.75em;
+        border-top: 1px solid color-mix(in oklab, CanvasText 18%, Canvas);
+        font-size: 0.92em;
       }
       .pane--doc .doc-pane-body .commentray-mermaid {
         overflow-x: auto;
@@ -1166,6 +1367,23 @@ const CODE_BROWSER_STYLES = `
         overflow-wrap: normal;
         word-break: normal;
       }
+      #doc-pane-body .commentray-page-break {
+        position: relative;
+        min-height: var(--commentray-page-break-min-height, clamp(260px, 56vh, 620px));
+        margin: 24px 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        pointer-events: none;
+      }
+      #doc-pane-body .commentray-page-break__rule {
+        width: 100%;
+        border-top: 1px dashed var(--border);
+        opacity: 0.38;
+      }
+      #shell[data-page-breaks-enabled="false"] .commentray-page-break {
+        display: none;
+      }
       .toolbar-angle-picker {
         display: inline-flex;
         align-items: center;
@@ -1385,6 +1603,19 @@ const CODE_BROWSER_STYLES = `
             0 1px 2px color-mix(in oklab, CanvasText 12%, transparent),
             0 4px 14px color-mix(in oklab, CanvasText 18%, transparent);
         }
+        .toolbar-icon-btn--source-markdown-scroll-narrow {
+          display: none;
+        }
+        #source-markdown-pane-flip-scroll.toolbar-icon-btn--source-markdown-scroll-narrow.is-visible {
+          display: inline-flex;
+          position: fixed;
+          top: calc(10px + env(safe-area-inset-top, 0px));
+          left: calc(12px + env(safe-area-inset-left, 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;
@@ -1450,6 +1681,47 @@ const CODE_BROWSER_STYLES = `
           color: CanvasText;
           text-shadow: 0 0 2px Canvas, 0 0 3px Canvas;
         }
+        .toolbar-source-render-toggle {
+          min-width: var(--cr-control-h);
+          width: var(--cr-control-h);
+          height: var(--cr-control-h);
+          padding: 0;
+          justify-content: center;
+          gap: 0;
+        }
+        .toolbar-source-render-toggle__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-source-render-toggle__box {
+          display: none;
+        }
+        .toolbar-source-render-toggle__face {
+          display: inline-flex;
+          position: relative;
+          width: 100%;
+          height: 100%;
+          min-height: var(--cr-control-h);
+          min-width: var(--cr-control-h);
+        }
+        .toolbar-source-render-toggle[aria-pressed="true"] .toolbar-source-render-toggle__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;
@@ -1512,11 +1784,6 @@ const CODE_BROWSER_STYLES = `
         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;
@@ -1541,11 +1808,6 @@ const CODE_BROWSER_STYLES = `
         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%;
@@ -1660,16 +1922,20 @@ ${CODE_BROWSER_STYLES}
             <span class="toolbar-wrap-lines__caption">Wrap lines</span>
           </label>
           ${dualFlipControlHtml}
+          ${p.sourceMarkdownToggleHtml}
           ${p.toolbarDocHubHtml}
           ${p.relatedNavHtml}
           </div>
           <div class="toolbar__primary-trail">
         ${p.toolbarEndHtml}
+${TOOLBAR_SHARE_LINK_HTML}
+${TOOLBAR_HELP_TOUR_HTML}
 ${TOOLBAR_COLOR_THEME_HTML}
           </div>
         </div>
       </header>
       ${dualFlipScrollAffordanceHtml}
+      ${p.sourceMarkdownFlipScrollAffordanceHtml}
       <header class="app__chrome" role="region" aria-label="Search">
         <div class="chrome__search-row">
           <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>
@@ -1679,7 +1945,7 @@ ${TOOLBAR_COLOR_THEME_HTML}
         <div class="search-results" id="search-results" hidden aria-live="polite"></div>
       </header>
       <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}>
+        <div class="${shellClass}" id="shell" data-layout="${p.layout}"${p.layout === "dual" ? ' data-dual-mobile-pane="doc"' : ""}${p.sourcePaneModeAttr} 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.shellPairIdentityDataAttrs}${p.shellPairDocDataAttr}>
 ${p.shellInner}
         </div>
       </main>
@@ -1693,10 +1959,53 @@ ${loadCodeBrowserClientBundle()}
   </body>
 </html>`;
 }
+function firstNonEmpty(values) {
+    return values.find((v) => v.trim().length > 0);
+}
+function resolveMultiAngleDefaultSelection(args) {
+    const { multi, defaultId, opts, builtAngles } = args;
+    let defaultMarkdown = opts.commentrayMarkdown;
+    let defaultScrollB64 = "";
+    let defaultPathSearch = (opts.commentrayPathForSearch ?? "").trim();
+    let defaultGh = opts.commentrayOnGithubUrl;
+    let defaultStaticBrowse = (opts.commentrayStaticBrowseUrl ?? "").trim();
+    let defaultPaneHtml = "";
+    for (const b of builtAngles) {
+        if (b.spec.id !== defaultId)
+            continue;
+        defaultMarkdown = b.spec.markdown;
+        defaultScrollB64 = b.scrollB64;
+        defaultPathSearch = b.spec.commentrayPathRel.trim();
+        defaultGh = b.spec.commentrayOnGithubUrl;
+        defaultStaticBrowse = (b.spec.staticBrowseUrl ?? "").trim();
+        defaultPaneHtml = b.commentrayHtml;
+        break;
+    }
+    if (defaultStaticBrowse.length === 0) {
+        defaultStaticBrowse =
+            firstNonEmpty(multi.angles.map((a) => (a.staticBrowseUrl ?? "").trim())) ?? "";
+    }
+    if ((defaultGh ?? "").trim().length === 0) {
+        defaultGh = firstNonEmpty(multi.angles.map((a) => (a.commentrayOnGithubUrl ?? "").trim()));
+    }
+    return {
+        defaultMarkdown,
+        defaultScrollB64,
+        defaultPathSearch,
+        defaultGh,
+        defaultStaticBrowse,
+        defaultPaneHtml,
+    };
+}
 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 angleCrNorm = normalizeRepoRelativePath(spec.commentrayPathRel.replaceAll("\\", "/"));
+    const primaryNorm = normalizeRepoRelativePath((opts.filePath ?? "").replaceAll("\\", "/"));
+    const rowsPathOk = rows !== undefined &&
+        normalizeRepoRelativePath(rows.commentrayPathRel.replaceAll("\\", "/")) === angleCrNorm &&
+        normalizeRepoRelativePath(rows.sourceRelative.replaceAll("\\", "/")) === primaryNorm;
+    const links = rows !== undefined && rowsPathOk
+        ? buildBlockScrollLinks(rows.index, rows.sourceRelative, angleCrNorm, 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") : "";
@@ -1723,29 +2032,24 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
         ? multi.defaultAngleId
         : (multi.angles[0]?.id ?? "main");
     const jsonAngles = [];
-    let defaultMarkdown = opts.commentrayMarkdown;
-    let defaultScrollB64 = "";
-    let defaultPathSearch = (opts.commentrayPathForSearch ?? "").trim();
-    let defaultGh = opts.commentrayOnGithubUrl;
-    let defaultStaticBrowse = (opts.commentrayStaticBrowseUrl ?? "").trim();
-    let defaultPaneHtml = "";
-    const codeHtml = await renderHighlightedCodeLineRows(opts.code, opts.language);
+    const builtAngles = [];
+    const sourceMarkdownEnabled = isMarkdownLikeSource(opts);
+    const sourceMdForPane = sourceMarkdownEnabled ? injectSourceMarkdownAnchors(opts.code) : "";
+    const sourcePaneUrls = sourcePaneOutputUrls(opts);
+    const [codeHtml, sourceMarkdownPaneHtml] = await Promise.all([
+        renderHighlightedCodeLineRows(opts.code, opts.language),
+        sourceMarkdownEnabled
+            ? renderMarkdownToHtml(sourceMdForPane, {
+                commentrayOutputUrls: sourcePaneUrls,
+            })
+            : Promise.resolve(""),
+    ]);
     for (const spec of multi.angles) {
         const { jsonRow, commentrayHtml, scrollB64 } = await multiAngleJsonRowAndDocHtml(opts, spec);
-        if (spec.id === defaultId) {
-            defaultMarkdown = spec.markdown;
-            defaultScrollB64 = scrollB64;
-            defaultPathSearch = spec.commentrayPathRel.trim();
-            defaultGh = spec.commentrayOnGithubUrl;
-            {
-                const sb = (spec.staticBrowseUrl ?? "").trim();
-                if (sb.length > 0)
-                    defaultStaticBrowse = sb;
-            }
-            defaultPaneHtml = commentrayHtml;
-        }
+        builtAngles.push({ spec, commentrayHtml, scrollB64 });
         jsonAngles.push(jsonRow);
     }
+    const { defaultMarkdown, defaultScrollB64, defaultPathSearch, defaultGh, defaultStaticBrowse, defaultPaneHtml, } = resolveMultiAngleDefaultSelection({ multi, defaultId, opts, builtAngles });
     const selOpts = multi.angles
         .map((a) => {
         const lab = escapeHtml(a.title?.trim() || a.id);
@@ -1754,7 +2058,7 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
         .join("");
     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 shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, defaultPaneHtml, sourceMarkdownPaneHtml));
     const payloadObj = { defaultAngleId: defaultId, angles: jsonAngles };
     const multiAnglePayloadB64 = Buffer.from(JSON.stringify(payloadObj), "utf8").toString("base64");
     return {
@@ -1768,6 +2072,8 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
         },
         angleSelectHtml,
         multiAnglePayloadB64,
+        sourceMarkdownToggleEnabled: sourceMarkdownEnabled,
+        sourcePaneDefaultMode: sourceMarkdownEnabled ? "rendered-markdown" : "source",
     };
 }
 async function buildCodeBrowserShell(opts, layoutPref) {
@@ -1785,6 +2091,8 @@ async function buildCodeBrowserShell(opts, layoutPref) {
             scrollBlockLinksB64: ms.scrollBlockLinksB64,
             angleSelectHtml: built.angleSelectHtml,
             multiAnglePayloadB64: built.multiAnglePayloadB64,
+            sourceMarkdownToggleEnabled: built.sourceMarkdownToggleEnabled,
+            sourcePaneDefaultMode: built.sourcePaneDefaultMode,
             multiShell: ms,
         };
     }
@@ -1811,14 +2119,31 @@ async function buildCodeBrowserShell(opts, layoutPref) {
         if (links.length > 0) {
             scrollBlockLinksB64 = Buffer.from(JSON.stringify(links), "utf8").toString("base64");
         }
-        const [codeHtml, commentrayHtml] = await Promise.all([
+        const sourceMarkdownEnabled = isMarkdownLikeSource(opts);
+        const sourceMdForPane = sourceMarkdownEnabled ? injectSourceMarkdownAnchors(opts.code) : "";
+        const sourcePaneUrls = sourcePaneOutputUrls(opts);
+        const [codeHtml, commentrayHtml, sourceMarkdownPaneHtml] = await Promise.all([
             renderHighlightedCodeLineRows(opts.code, opts.language),
             renderMarkdownToHtml(mdForDoc, {
                 commentrayOutputUrls: opts.commentrayOutputUrls,
             }),
+            sourceMarkdownEnabled
+                ? renderMarkdownToHtml(sourceMdForPane, {
+                    commentrayOutputUrls: sourcePaneUrls,
+                })
+                : Promise.resolve(""),
         ]);
         const pairHtml = renderShellPairContextHtml(opts.filePath, (opts.commentrayPathForSearch ?? "").trim());
-        shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, commentrayHtml));
+        shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, commentrayHtml, sourceMarkdownPaneHtml));
+        return {
+            layout,
+            shellInner,
+            scrollBlockLinksB64,
+            angleSelectHtml: "",
+            multiAnglePayloadB64: "",
+            sourceMarkdownToggleEnabled: sourceMarkdownEnabled,
+            sourcePaneDefaultMode: sourceMarkdownEnabled ? "rendered-markdown" : "source",
+        };
     }
     return {
         layout,
@@ -1826,6 +2151,8 @@ async function buildCodeBrowserShell(opts, layoutPref) {
         scrollBlockLinksB64,
         angleSelectHtml: "",
         multiAnglePayloadB64: "",
+        sourceMarkdownToggleEnabled: false,
+        sourcePaneDefaultMode: "source",
     };
 }
 function searchChromeFromOptions(opts, commentrayPathOverride) {
@@ -1856,6 +2183,23 @@ function toolbarCommentrayGithubFromShell(shell, opts) {
 function rawMdB64FromShell(shell, opts) {
     return (shell.multiShell?.rawMdB64 ?? Buffer.from(opts.commentrayMarkdown, "utf8").toString("base64"));
 }
+function currentPairCommentrayPathRel(shell, opts) {
+    return (shell.multiShell?.commentrayPathForSearch ??
+        opts.commentrayPathForSearch ??
+        opts.blockStretchRows?.commentrayPathRel ??
+        "").trim();
+}
+/**
+ * Repo-relative source + companion Markdown paths for matching the current page to nav pairs
+ * (see `code-browser-client.ts` documented-files tree).
+ */
+function shellPairIdentityDataAttrs(shell, opts) {
+    const src = normPosixPath(opts.filePath ?? "");
+    const cr = normPosixPath(currentPairCommentrayPathRel(shell, opts));
+    if (src.length === 0 || cr.length === 0)
+        return "";
+    return ` data-commentray-pair-source-path="${escapeHtml(src)}" data-commentray-pair-commentray-path="${escapeHtml(cr)}"`;
+}
 /** Canonical doc target for static validation: same-site `./browse/…` when present, else GitHub blob. */
 function shellPairDocDataAttr(shell, opts) {
     if (shell.layout !== "dual")
@@ -1898,6 +2242,7 @@ export async function renderCodeBrowserHtml(opts) {
         builtAt,
         toolHomeUrl: opts.toolHomeUrl,
         commentrayRenderSemver: renderSemver,
+        pagesBuildCommitSha: normalizePagesBuildCommitSha(opts.pagesBuildCommitSha),
     });
     const { hljsLight, hljsDark } = hljsStylesheetThemes(opts.hljsTheme);
     const mermaidScript = mermaidRuntimeScriptHtml(opts.includeMermaidRuntime);
@@ -1915,11 +2260,15 @@ export async function renderCodeBrowserHtml(opts) {
     const shellDocumentedPairsAttr = shellDocumentedPairsAttrFromOptions(opts);
     const shellSearchAttrs = shellSearchAttrsWithNavJson(shellSearchAttrsBase, opts.documentedNavJsonUrl);
     const pairDocDataAttr = shellPairDocDataAttr(shell, opts);
+    const pairIdentityDataAttrs = shellPairIdentityDataAttrs(shell, opts);
+    const sourceMarkdownToggles = sourceMarkdownToggleControlsHtml(shell.sourceMarkdownToggleEnabled);
+    const sourcePaneModeAttr = ` data-source-pane-mode="${shell.sourcePaneDefaultMode}"`;
     return buildCodeBrowserPageHtml({
         title,
         metaDescriptionHtml,
         generatorMetaHtml,
         toolbarSiteHubHtml,
+        shellPairIdentityDataAttrs: pairIdentityDataAttrs,
         shellPairDocDataAttr: pairDocDataAttr,
         angleSelectHtml: shell.angleSelectHtml,
         toolbarDocHubHtml,
@@ -1939,6 +2288,9 @@ export async function renderCodeBrowserHtml(opts) {
         searchPlaceholder,
         shellSearchAttrs,
         multiAngleScriptBlock: shell.multiAnglePayloadB64,
+        sourceMarkdownToggleHtml: sourceMarkdownToggles.sourceMarkdownToggleHtml,
+        sourceMarkdownFlipScrollAffordanceHtml: sourceMarkdownToggles.sourceMarkdownFlipScrollAffordanceHtml,
+        sourcePaneModeAttr,
     });
 }
 //# sourceMappingURL=code-browser.js.map