@commentray/render 0.0.9 → 0.1.0

package/dist/code-browser.js

@@ -11,6 +11,7 @@ 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";
 function renderGeneratorMetaHtml(label) {
     const t = label?.trim();
     if (!t)
@@ -31,6 +32,7 @@ function renderMetaDescriptionHtml(opts, title) {
 }
 /** 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");
+const PAGE_BREAK_MARKER_HTML_LINE = /^<!--\s*commentray:page-break\s*-->$/i;
 function trimEndSpacesTabs(s) {
     let end = s.length;
     while (end > 0) {
@@ -68,10 +70,72 @@ function isClosingFenceLine(info, open) {
         return false;
     return info.rest.trim() === "";
 }
+/**
+ * GFM delimiter row: cells between pipes contain only colons, hyphens, and spaces; each cell has
+ * at least three hyphens (same rule remark-gfm uses). Used so we do not append raw HTML to table
+ * lines — trailing `<span>` breaks GFM table recognition in the Markdown parser.
+ */
+function isGfmTableDelimiterRow(line) {
+    const t = trimEndSpacesTabs(line);
+    if (!t.includes("|"))
+        return false;
+    const cells = t
+        .split("|")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (cells.length === 0)
+        return false;
+    for (const cell of cells) {
+        if (!/^:?-{3,}:?$/.test(cell))
+            return false;
+    }
+    return true;
+}
+/**
+ * 0-based line indices that must not receive a trailing line-anchor span: they belong to a GFM
+ * table (header + delimiter + following rows until a blank line). Scans full `lines` so indices
+ * align with {@link injectCommentrayDocAnchors}; lines inside fenced code are harmless to mark
+ * because that pass never appends anchors there anyway.
+ */
+function gfmTableLineIndicesWithoutAnchors(lines) {
+    const skip = new Set();
+    const n = lines.length;
+    for (let i = 0; i < n - 1; i++) {
+        const header = lines[i] ?? "";
+        const delim = lines[i + 1] ?? "";
+        if (header === "")
+            continue;
+        if (!trimEndSpacesTabs(header).includes("|"))
+            continue;
+        if (isSetextUnderlineLine(header) || isThematicBreakLine(header))
+            continue;
+        if (!isGfmTableDelimiterRow(delim))
+            continue;
+        skip.add(i);
+        skip.add(i + 1);
+        let j = i + 2;
+        while (j < n) {
+            const row = lines[j] ?? "";
+            if (row === "")
+                break;
+            if (isSetextUnderlineLine(row) || isThematicBreakLine(row))
+                break;
+            if (isGfmTableDelimiterRow(row))
+                break;
+            skip.add(j);
+            j++;
+        }
+    }
+    return skip;
+}
 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 sourceLineAnchorHtml(line0) {
+    const s = String(line0);
+    return `<span class="commentray-line-anchor commentray-line-anchor--source" data-source-md-line="${s}" id="code-md-line-${s}" aria-hidden="true"></span>`;
+}
 function appendMdLineAnchorWhenAllowed(line, mdLine0) {
     if (isSetextUnderlineLine(line) || isThematicBreakLine(line))
         return line;
@@ -80,17 +144,59 @@ function appendMdLineAnchorWhenAllowed(line, mdLine0) {
         return "";
     return `${line}${lineAnchorHtml(mdLine0)}`;
 }
+function appendSourceMdLineAnchorWhenAllowed(line, line0) {
+    if (isSetextUnderlineLine(line) || isThematicBreakLine(line))
+        return line;
+    if (line === "")
+        return "";
+    return `${line}${sourceLineAnchorHtml(line0)}`;
+}
+function pageBreakNextBlockMetaByLine(lines, byId) {
+    const out = new Map();
+    let nextMeta = null;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i] ?? "";
+        const blockMatch = BLOCK_MARKER_HTML_LINE.exec(line);
+        if (blockMatch?.[1]) {
+            const id = blockMatch[1];
+            const sourceStart = byId?.get(id)?.sourceStart;
+            nextMeta =
+                sourceStart !== undefined ? { commentrayLine: i, sourceStart } : { commentrayLine: i };
+            continue;
+        }
+        if (!PAGE_BREAK_MARKER_HTML_LINE.test(line) || nextMeta === null)
+            continue;
+        out.set(i, nextMeta);
+    }
+    return out;
+}
+function blockAnchorAttrs(link) {
+    if (link === undefined)
+        return "";
+    return ` data-source-start="${String(link.sourceStart)}" data-commentray-line="${String(link.commentrayLine)}"`;
+}
+function pageBreakNextAttrs(next) {
+    if (next === undefined)
+        return "";
+    const nextCommentrayAttr = ` data-next-commentray-line="${String(next.commentrayLine)}"`;
+    const nextSourceAttr = next.sourceStart !== undefined ? ` data-next-source-start="${String(next.sourceStart)}"` : "";
+    return `${nextCommentrayAttr}${nextSourceAttr}`;
+}
 /**
  * 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).
+ * trailing anchor either (would corrupt fence delimiters or appear inside code). **GFM pipe
+ * tables** must not get a trailing anchor: extra HTML after the row breaks `remark-gfm` table
+ * detection, so tables would render as plain text.
  */
 function injectCommentrayDocAnchors(markdown, links) {
     const byId = links ? new Map(links.map((l) => [l.id, l])) : undefined;
     const lines = markdown.split("\n");
+    const pageBreakNextByLine = pageBreakNextBlockMetaByLine(lines, byId);
+    const skipLineAnchor = gfmTableLineIndicesWithoutAnchors(lines);
     let fence = null;
     const out = [];
     for (let i = 0; i < lines.length; i++) {
@@ -113,10 +219,7 @@ function injectCommentrayDocAnchors(markdown, links) {
         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)}"`
-                : "";
+            const attrs = blockAnchorAttrs(byId?.get(id));
             /** 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("");
@@ -124,10 +227,56 @@ function injectCommentrayDocAnchors(markdown, links) {
             out.push("");
             continue;
         }
+        if (PAGE_BREAK_MARKER_HTML_LINE.test(line)) {
+            const nextAttrs = pageBreakNextAttrs(pageBreakNextByLine.get(i));
+            out.push(`${line}${lineAnchorHtml(i)}`);
+            out.push("");
+            out.push(`<div class="commentray-page-break" data-commentray-page-break="true"${nextAttrs} aria-hidden="true"><div class="commentray-page-break__rule"></div></div>`);
+            out.push("");
+            continue;
+        }
+        if (skipLineAnchor.has(i)) {
+            out.push(line);
+            continue;
+        }
         out.push(appendMdLineAnchorWhenAllowed(line, i));
     }
     return out.join("\n");
 }
+/**
+ * Adds stable source-line anchors (`id="code-line-N"`) to Markdown so rendered-source mode can
+ * preserve block-aware scroll sync and block ray geometry.
+ */
+function injectSourceMarkdownAnchors(markdown) {
+    const lines = markdown.split("\n");
+    const skipLineAnchor = gfmTableLineIndicesWithoutAnchors(lines);
+    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;
+        }
+        if (skipLineAnchor.has(i)) {
+            out.push(line);
+            continue;
+        }
+        out.push(appendSourceMdLineAnchorWhenAllowed(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 +308,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)
@@ -242,9 +410,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,6 +425,26 @@ function dualPanePanesInnerHtml(codeHtml, commentrayHtml) {
         `          </div>\n` +
         `        </section>\n`);
 }
+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 path = (opts.filePath ?? "").trim().toLowerCase();
+    return path.endsWith(".md") || path.endsWith(".mdx") || path.endsWith(".markdown");
+}
 /** 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();
@@ -292,6 +484,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 +514,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;
@@ -654,6 +864,7 @@ const CODE_BROWSER_STYLES = `
       }
       .app__footer-attribution__version { font-weight: 600; }
       .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 +983,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 +1095,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 +1212,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);
@@ -1044,6 +1347,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;
@@ -1144,11 +1472,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 +1578,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 +1814,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 +1892,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 +1995,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 +2019,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 +2133,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 +2156,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,6 +2170,44 @@ ${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
@@ -1723,29 +2238,23 @@ 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 [codeHtml, sourceMarkdownPaneHtml] = await Promise.all([
+        renderHighlightedCodeLineRows(opts.code, opts.language),
+        sourceMarkdownEnabled
+            ? renderMarkdownToHtml(sourceMdForPane, {
+                commentrayOutputUrls: opts.commentrayOutputUrls,
+            })
+            : 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 +2263,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 +2277,8 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
         },
         angleSelectHtml,
         multiAnglePayloadB64,
+        sourceMarkdownToggleEnabled: sourceMarkdownEnabled,
+        sourcePaneDefaultMode: sourceMarkdownEnabled ? "rendered-markdown" : "source",
     };
 }
 async function buildCodeBrowserShell(opts, layoutPref) {
@@ -1785,6 +2296,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 +2324,30 @@ 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 [codeHtml, commentrayHtml, sourceMarkdownPaneHtml] = await Promise.all([
             renderHighlightedCodeLineRows(opts.code, opts.language),
             renderMarkdownToHtml(mdForDoc, {
                 commentrayOutputUrls: opts.commentrayOutputUrls,
             }),
+            sourceMarkdownEnabled
+                ? renderMarkdownToHtml(sourceMdForPane, {
+                    commentrayOutputUrls: opts.commentrayOutputUrls,
+                })
+                : 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 +2355,8 @@ async function buildCodeBrowserShell(opts, layoutPref) {
         scrollBlockLinksB64,
         angleSelectHtml: "",
         multiAnglePayloadB64: "",
+        sourceMarkdownToggleEnabled: false,
+        sourcePaneDefaultMode: "source",
     };
 }
 function searchChromeFromOptions(opts, commentrayPathOverride) {
@@ -1856,6 +2387,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")
@@ -1915,11 +2463,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 +2491,9 @@ export async function renderCodeBrowserHtml(opts) {
         searchPlaceholder,
         shellSearchAttrs,
         multiAngleScriptBlock: shell.multiAnglePayloadB64,
+        sourceMarkdownToggleHtml: sourceMarkdownToggles.sourceMarkdownToggleHtml,
+        sourceMarkdownFlipScrollAffordanceHtml: sourceMarkdownToggles.sourceMarkdownFlipScrollAffordanceHtml,
+        sourcePaneModeAttr,
     });
 }
 //# sourceMappingURL=code-browser.js.map