@commentray/render 0.2.0 → 0.3.1

package/dist/code-browser.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path, { join } from "node:path";
-import { buildBlockScrollLinks, findMonorepoPackagesDir, monorepoLayoutStartDir, normalizeRepoRelativePath, } from "@commentray/core";
-import { tryBuildBlockStretchTableHtml } from "./block-stretch-layout.js";
+import { buildBlockScrollLinks, CURRENT_SCHEMA_VERSION, DEFAULT_STRETCH_BUFFER_SYNC, 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";
 import { commentrayColorThemeHeadBoot } from "./code-browser-color-theme.js";
@@ -13,6 +13,7 @@ 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";
+import { DEFAULT_DUAL_PANE_SCROLL_SYNC_STRATEGY, } from "./code-browser-scroll-sync-strategy.js";
 function renderGeneratorMetaHtml(label) {
     const t = label?.trim();
     if (!t)
@@ -184,7 +185,7 @@ function renderToolbarDocHubHtml(opts) {
 }
 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`
+        ? `          <div class="source-pane source-pane--rendered-md" id="code-pane-markdown-body" data-source-markdown-body="true">${sourceMarkdownRenderedHtml}</div>\n`
         : "";
     return (`        <section class="pane--code" id="code-pane" aria-label="Source code">` +
         `          <div class="source-pane source-pane--code" id="code-pane-code-body">${codeHtml}</div>\n` +
@@ -214,6 +215,8 @@ function isMarkdownLikeSource(opts) {
     const lang = opts.language.trim().toLowerCase();
     if (lang === "md" || lang === "markdown" || lang === "mdx")
         return true;
+    if (lang.length > 0)
+        return false;
     const filePath = (opts.filePath ?? "").trim().toLowerCase();
     return filePath.endsWith(".md") || filePath.endsWith(".mdx") || filePath.endsWith(".markdown");
 }
@@ -252,9 +255,24 @@ function renderShellPairContextHtml(filePath, commentrayPath) {
     </div>
   </div>`;
 }
-function wrapDualShellInner(pairContextHtml, panesHtml) {
+function shellPairSourcePath(filePath, sourceRelative) {
+    const filePathTrimmed = (filePath ?? "").trim();
+    if (filePathTrimmed.length > 0)
+        return filePathTrimmed;
+    return (sourceRelative ?? "").trim();
+}
+function shellPairCommentrayPath(commentrayPath, fallbackCommentrayPath) {
+    const commentrayPathTrimmed = (commentrayPath ?? "").trim();
+    if (commentrayPathTrimmed.length > 0)
+        return commentrayPathTrimmed;
+    return (fallbackCommentrayPath ?? "").trim();
+}
+function wrapShellInnerWithPairContext(pairContextHtml, mainHtml) {
     const row = pairContextHtml.trim().length > 0 ? `        ${pairContextHtml.trim()}\n` : "";
-    return `${row}        <div class="shell__panes">\n${panesHtml}        </div>\n`;
+    return `${row}${mainHtml}`;
+}
+function wrapDualShellInner(pairContextHtml, panesHtml) {
+    return wrapShellInnerWithPairContext(pairContextHtml, `        <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() {
@@ -609,7 +627,7 @@ const CODE_BROWSER_STYLES = `
         flex-wrap: wrap;
         align-items: center;
         justify-content: flex-end;
-        gap: 10px 14px;
+        gap: 6px;
         margin-left: auto;
         min-width: 0;
       }
@@ -1132,7 +1150,66 @@ ${CODE_BROWSER_INTRO_STYLES}
         text-overflow: ellipsis;
         white-space: nowrap;
       }
-      .shell__pair-path--secondary { opacity: 0.88; }
+      .shell__pair-path--secondary {
+        opacity: 0.88;
+        text-align: right;
+      }
+      .shell--stretch-rows .shell__pair-context {
+        --shell-pair-gutter-w: 14px;
+        --shell-pair-gutter-half: calc(var(--shell-pair-gutter-w) / 2);
+        display: grid;
+        grid-template-columns:
+          minmax(0, calc(var(--stretch-code-pct, 50%) - var(--shell-pair-gutter-half)))
+          var(--shell-pair-gutter-w)
+          minmax(0, calc(100% - var(--stretch-code-pct, 50%) - var(--shell-pair-gutter-half)));
+        width: 100%;
+        box-sizing: border-box;
+      }
+      .shell--stretch-rows .shell__pair-cell--src,
+      .shell--stretch-rows .shell__pair-cell--doc,
+      .shell--stretch-rows .shell__pair-gutter-spacer {
+        min-width: 0;
+      }
+      .shell--stretch-rows .shell__pair-cell--src {
+        grid-column: 1;
+        padding-left: var(--cr-pane-inline-pad);
+        padding-right: 0;
+      }
+      .shell--stretch-rows .shell__pair-gutter-spacer {
+        grid-column: 2;
+        width: var(--shell-pair-gutter-w);
+        min-width: var(--shell-pair-gutter-w);
+      }
+      .shell--stretch-rows .shell__pair-cell--doc {
+        grid-column: 3;
+        padding-left: var(--cr-pane-inline-pad);
+        padding-right: var(--cr-pane-inline-pad);
+      }
+      .shell[data-mobile-single-pane="true"] .shell__pair-context {
+        display: flex;
+        flex-direction: column;
+        align-items: stretch;
+        gap: 4px;
+        padding: 4px 0 6px;
+      }
+      .shell[data-mobile-single-pane="true"] .shell__pair-cell--src,
+      .shell[data-mobile-single-pane="true"] .shell__pair-cell--doc {
+        width: 100%;
+        padding-right: var(--cr-pane-inline-pad);
+        box-sizing: border-box;
+      }
+      .shell[data-mobile-single-pane="true"][data-dual-mobile-pane="code"] .shell__pair-cell--doc,
+      .shell[data-mobile-single-pane="true"][data-dual-mobile-pane="code"] .shell__pair-gutter-spacer {
+        display: none;
+      }
+      .shell[data-mobile-single-pane="true"][data-dual-mobile-pane="doc"] .shell__pair-cell--src,
+      .shell[data-mobile-single-pane="true"][data-dual-mobile-pane="doc"] .shell__pair-gutter-spacer {
+        display: none;
+      }
+      .shell[data-mobile-single-pane="true"]:not([data-dual-mobile-pane]) .shell__pair-cell--src,
+      .shell[data-mobile-single-pane="true"]:not([data-dual-mobile-pane]) .shell__pair-gutter-spacer {
+        display: none;
+      }
       .pane--code {
         flex: 0 0 var(--split-pct, 46%);
         min-width: 120px; overflow: auto; padding: 12px var(--cr-pane-inline-pad);
@@ -1270,6 +1347,8 @@ ${CODE_BROWSER_INTRO_STYLES}
       .doc-pane-body {
         flex: 1 1 auto; min-height: 0; overflow: auto;
       }
+      /* scroll-behavior: smooth was removed: it interpolates many scroll events per gesture and
+       * exhausts the partner-echo guard in wireBidirectionalScroll, so doc↔code ping-pong returns. */
       /* 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,
@@ -1760,6 +1839,22 @@ ${CODE_BROWSER_INTRO_STYLES}
           flex: 1 1 auto;
           padding-left: var(--cr-pane-inline-pad);
         }
+        .shell.shell--stretch-rows[data-dual-mobile-pane="code"] .stretch-col-doc,
+        .shell.shell--stretch-rows[data-dual-mobile-pane="doc"] .stretch-col-code,
+        .shell.shell--stretch-rows[data-dual-mobile-pane="code"] td.stretch-doc,
+        .shell.shell--stretch-rows[data-dual-mobile-pane="doc"] td.stretch-code {
+          display: none;
+        }
+        .shell.shell--stretch-rows[data-dual-mobile-pane="code"] td.stretch-code,
+        .shell.shell--stretch-rows[data-dual-mobile-pane="doc"] td.stretch-doc {
+          display: table-cell;
+          width: 100%;
+          padding-left: 0;
+          padding-right: 0;
+        }
+        .shell.shell--stretch-rows[data-dual-mobile-pane] #stretch-gutter {
+          display: none;
+        }
       }
       .pane--doc { font-size: 15px; line-height: 1.45; }
       .pane--doc img { max-width: 100%; height: auto; }
@@ -1771,9 +1866,8 @@ ${CODE_BROWSER_INTRO_STYLES}
       .pane--doc .commentray-block-anchor {
         display: block;
         height: 0;
-        margin: 14px 0 0;
+        margin: 0;
         border: 0;
-        border-top: 1px solid color-mix(in oklab, CanvasText 22%, Canvas);
         pointer-events: none;
       }
       .shell--stretch-rows {
@@ -1781,15 +1875,17 @@ ${CODE_BROWSER_INTRO_STYLES}
         min-height: 0;
         overflow: auto;
         display: block;
-        padding: 0 12px 20px;
+        padding: 0 0 20px;
       }
       .shell--stretch-rows .stretch-preamble {
         padding: 8px 4px 16px;
         margin-bottom: 8px;
-        border-bottom: 1px solid color-mix(in oklab, CanvasText 12%, Canvas);
         font-size: 15px;
         line-height: 1.45;
         overflow-x: auto;
+        /* overflow-x other than visible makes overflow-y:visible compute to auto, which traps
+         * vertical wheel on this node instead of the shell scrollport when height is ever capped. */
+        overflow-y: hidden;
         max-width: 100%;
       }
       .shell--stretch-rows .stretch-preamble img { max-width: 100%; height: auto; }
@@ -1798,27 +1894,49 @@ ${CODE_BROWSER_INTRO_STYLES}
         border-collapse: collapse;
         table-layout: fixed;
       }
-      .stretch-col-code { width: 50%; }
-      .stretch-col-doc { width: 50%; }
+      .stretch-grid {
+        position: relative;
+      }
+      .stretch-col-code { width: var(--stretch-code-pct, 50%); }
+      .stretch-col-doc { width: calc(100% - var(--stretch-code-pct, 50%)); }
       .block-stretch td.stretch-code {
         vertical-align: top;
         padding: 0 12px 0 0;
-        border-bottom: 1px solid color-mix(in oklab, CanvasText 8%, Canvas);
+        box-shadow: inset -1px 0 0 color-mix(in oklab, CanvasText 10%, Canvas);
+      }
+      #shell[data-stretch-buffer-sync="flow-synchronizer"] .block-stretch td.stretch-code > .stretch-cell-measure,
+      #shell[data-stretch-buffer-sync="flow-synchronizer"] .block-stretch td.stretch-doc > .stretch-cell-measure {
+        display: block;
+        width: 100%;
+        box-sizing: border-box;
+        height: max-content;
+        max-height: max-content;
+      }
+      #shell[data-stretch-buffer-sync="flow-synchronizer"] .block-stretch td.stretch-doc .stretch-doc-inner {
+        height: max-content;
+        max-height: max-content;
+      }
+      #shell[data-stretch-buffer-sync="flow-synchronizer"] .block-stretch .stretch-code-stack {
+        height: max-content;
+        max-height: max-content;
       }
       .block-stretch td.stretch-doc {
         vertical-align: top;
         padding: 0 0 0 12px;
-        border-bottom: 1px solid color-mix(in oklab, CanvasText 8%, Canvas);
+        box-shadow: inset 1px 0 0 color-mix(in oklab, CanvasText 8%, Canvas);
       }
       .block-stretch td.stretch-doc .stretch-doc-inner {
         font-size: 15px;
         line-height: 1.45;
         min-width: 0;
         overflow-x: auto;
+        /* Keep vertical scrolling on the shell; see stretch-preamble rule above. */
+        overflow-y: hidden;
       }
       .block-stretch td.stretch-doc .stretch-doc-inner img { max-width: 100%; height: auto; }
       .block-stretch td.stretch-doc .stretch-doc-inner .commentray-mermaid {
         overflow-x: auto;
+        overflow-y: hidden;
         max-width: 100%;
       }
       .block-stretch.wrap td.stretch-doc .stretch-doc-inner {
@@ -1837,7 +1955,6 @@ ${CODE_BROWSER_INTRO_STYLES}
         font-size: 13px;
         vertical-align: top;
       }
-      .block-stretch .stretch-gap-mark { display: inline-block; padding-top: 2px; }
       .block-stretch .stretch-code-stack {
         display: flex;
         flex-direction: column;
@@ -1887,15 +2004,39 @@ ${CODE_BROWSER_INTRO_STYLES}
       .block-stretch:not(.wrap) .stretch-doc-inner pre code {
         white-space: pre;
       }
+      .stretch-gutter {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        left: var(--stretch-code-pct, 50%);
+        transform: translateX(-50%);
+        width: 14px;
+        cursor: col-resize;
+        touch-action: none;
+        border-left: 1px solid color-mix(in oklab, CanvasText 14%, Canvas);
+        border-right: 1px solid color-mix(in oklab, CanvasText 10%, Canvas);
+        background: color-mix(in oklab, CanvasText 8%, Canvas);
+        border-radius: 999px;
+        --commentray-ray-accent: #3b7dd8;
+        z-index: 6;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root:is(:not([data-commentray-theme]), [data-commentray-theme="system"]) .stretch-gutter {
+          --commentray-ray-accent: #6eb0ff;
+        }
+      }
+      :root[data-commentray-theme="dark"] .stretch-gutter {
+        --commentray-ray-accent: #6eb0ff;
+      }
 `;
 /** 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"
+    const dualFlipControlHtml = p.layout === "dual" || p.layout === "stretch"
         ? `<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"
+    const dualFlipScrollAffordanceHtml = p.layout === "dual" || p.layout === "stretch"
         ? `<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>
@@ -1924,13 +2065,13 @@ ${CODE_BROWSER_STYLES}
           ${p.toolbarSiteHubHtml}
           ${p.navRailDocumentedHtml}
           ${p.angleSelectHtml}
+          ${dualFlipControlHtml}
           <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.sourceMarkdownToggleHtml}
           ${p.toolbarDocHubHtml}
           ${p.relatedNavHtml}
@@ -1954,7 +2095,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"' : ""}${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}>
+        <div class="${shellClass}" id="shell" data-layout="${p.layout}"${p.layout === "dual" || p.layout === "stretch" ? ' 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.scrollSyncStrategyShellAttr ?? ""}${p.stretchBufferSyncShellAttr ?? ""}>
 ${p.shellInner}
         </div>
       </main>
@@ -1971,6 +2112,27 @@ ${loadCodeBrowserClientBundle()}
 function firstNonEmpty(values) {
     return values.find((v) => v.trim().length > 0);
 }
+function stretchBufferSyncFromOpts(opts) {
+    return opts.stretchBufferSync ?? DEFAULT_STRETCH_BUFFER_SYNC;
+}
+function angleBlockStretchRowsPathOk(spec, opts) {
+    const rows = spec.blockStretchRows;
+    if (rows === undefined)
+        return false;
+    const angleCrNorm = normalizeRepoRelativePath(spec.commentrayPathRel.replaceAll("\\", "/"));
+    const primaryNorm = normalizeRepoRelativePath((opts.filePath ?? "").replaceAll("\\", "/"));
+    return (normalizeRepoRelativePath(rows.commentrayPathRel.replaceAll("\\", "/")) === angleCrNorm &&
+        normalizeRepoRelativePath(rows.sourceRelative.replaceAll("\\", "/")) === primaryNorm);
+}
+function multiAngleToolbarAngleSelectHtml(multi, defaultId) {
+    const selOpts = multi.angles
+        .map((a) => {
+        const lab = escapeHtml(a.title?.trim() || a.id);
+        return `<option value="${escapeHtml(a.id)}"${a.id === defaultId ? " selected" : ""}>${lab}</option>`;
+    })
+        .join("");
+    return `<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>`;
+}
 function resolveMultiAngleDefaultSelection(args) {
     const { multi, defaultId, opts, builtAngles } = args;
     let defaultMarkdown = opts.commentrayMarkdown;
@@ -2008,11 +2170,8 @@ function resolveMultiAngleDefaultSelection(args) {
 }
 async function multiAngleJsonRowAndDocHtml(opts, spec) {
     const rows = spec.blockStretchRows;
+    const rowsPathOk = angleBlockStretchRowsPathOk(spec, opts);
     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)
         : [];
@@ -2036,6 +2195,85 @@ async function multiAngleJsonRowAndDocHtml(opts, spec) {
         scrollB64,
     };
 }
+/**
+ * When every angle has a valid block index and `tryBuildBlockStretchTableHtml` succeeds for each,
+ * emit one outer scroll (table rows = aligned block “arithmetics”) instead of dual-pane sync.
+ */
+async function buildMultiAngleBlockStretchShell(opts, multi) {
+    const defaultId = multi.angles.some((a) => a.id === multi.defaultAngleId)
+        ? multi.defaultAngleId
+        : (multi.angles[0]?.id ?? "main");
+    const sourceMarkdownEnabled = isMarkdownLikeSource(opts);
+    const sourceMarkdownUrls = sourceMarkdownEnabled ? sourcePaneOutputUrls(opts) : undefined;
+    const perAngle = [];
+    for (const spec of multi.angles) {
+        if (!angleBlockStretchRowsPathOk(spec, opts))
+            return null;
+        const rows = spec.blockStretchRows;
+        if (rows === undefined)
+            return null;
+        const stretched = await tryBuildBlockStretchTableHtml({
+            code: opts.code,
+            language: opts.language,
+            commentrayMarkdown: spec.markdown,
+            index: rows.index,
+            sourceRelative: rows.sourceRelative,
+            commentrayPathRel: rows.commentrayPathRel,
+            commentrayOutputUrls: opts.commentrayOutputUrls,
+            sourceMarkdownOutputUrls: sourceMarkdownUrls,
+            stretchBufferSync: stretchBufferSyncFromOpts(opts),
+        });
+        if (stretched === null)
+            return null;
+        const { jsonRow, commentrayHtml, scrollB64 } = await multiAngleJsonRowAndDocHtml(opts, spec);
+        const stretchPairHtml = renderShellPairContextHtml(shellPairSourcePath(opts.filePath, rows.sourceRelative), jsonRow.commentrayPathForSearch);
+        const stretchSwapInner = wrapShellInnerWithPairContext(stretchPairHtml, `        ${stretched.preambleHtml}\n        ${stretched.tableInnerHtml}\n`);
+        perAngle.push({
+            spec,
+            stretched,
+            jsonRow: {
+                ...jsonRow,
+                stretchSwapInnerB64: Buffer.from(stretchSwapInner, "utf8").toString("base64"),
+            },
+            commentrayHtml,
+            scrollB64,
+        });
+    }
+    const builtAngles = perAngle.map((p) => ({
+        spec: p.spec,
+        commentrayHtml: p.commentrayHtml,
+        scrollB64: p.scrollB64,
+    }));
+    const { defaultMarkdown, defaultScrollB64, defaultPathSearch, defaultGh, defaultStaticBrowse } = resolveMultiAngleDefaultSelection({ multi, defaultId, opts, builtAngles });
+    const defaultStretch = perAngle.find((p) => p.spec.id === defaultId) ?? perAngle[0];
+    if (defaultStretch === undefined)
+        return null;
+    const shellInner = wrapShellInnerWithPairContext(renderShellPairContextHtml(shellPairSourcePath(opts.filePath, defaultStretch.spec.blockStretchRows?.sourceRelative), defaultPathSearch), `        ${defaultStretch.stretched.preambleHtml}\n` +
+        `        ${defaultStretch.stretched.tableInnerHtml}\n`);
+    const payloadObj = {
+        layoutMode: "stretch",
+        defaultAngleId: defaultId,
+        angles: perAngle.map((p) => p.jsonRow),
+    };
+    const multiAnglePayloadB64 = Buffer.from(JSON.stringify(payloadObj), "utf8").toString("base64");
+    return {
+        layout: "stretch",
+        shellInner,
+        scrollBlockLinksB64: defaultScrollB64,
+        angleSelectHtml: multiAngleToolbarAngleSelectHtml(multi, defaultId),
+        multiAnglePayloadB64,
+        sourceMarkdownToggleEnabled: sourceMarkdownEnabled,
+        sourcePaneDefaultMode: "source",
+        stretchBufferSync: stretchBufferSyncFromOpts(opts),
+        multiShell: {
+            rawMdB64: Buffer.from(defaultMarkdown, "utf8").toString("base64"),
+            scrollBlockLinksB64: defaultScrollB64,
+            commentrayPathForSearch: defaultPathSearch,
+            commentrayOnGithubUrl: defaultGh,
+            ...(defaultStaticBrowse.length > 0 ? { commentrayStaticBrowseUrl: defaultStaticBrowse } : {}),
+        },
+    };
+}
 async function buildMultiAngleDualPaneShell(opts, multi) {
     const defaultId = multi.angles.some((a) => a.id === multi.defaultAngleId)
         ? multi.defaultAngleId
@@ -2059,14 +2297,8 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
         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);
-        return `<option value="${escapeHtml(a.id)}"${a.id === defaultId ? " selected" : ""}>${lab}</option>`;
-    })
-        .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 angleSelectHtml = multiAngleToolbarAngleSelectHtml(multi, defaultId);
+    const pairHtml = renderShellPairContextHtml(shellPairSourcePath(opts.filePath, opts.blockStretchRows?.sourceRelative), defaultPathSearch);
     const shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, defaultPaneHtml, sourceMarkdownPaneHtml));
     const payloadObj = { defaultAngleId: defaultId, angles: jsonAngles };
     const multiAnglePayloadB64 = Buffer.from(JSON.stringify(payloadObj), "utf8").toString("base64");
@@ -2085,74 +2317,100 @@ async function buildMultiAngleDualPaneShell(opts, multi) {
         sourcePaneDefaultMode: sourceMarkdownEnabled ? "rendered-markdown" : "source",
     };
 }
-async function buildCodeBrowserShell(opts, layoutPref) {
-    let layout = "dual";
-    let shellInner = "";
+async function buildDualPaneSingleAngleShell(opts) {
+    const rows = opts.blockStretchRows;
+    const links = rows !== undefined
+        ? buildBlockScrollLinks(rows.index, rows.sourceRelative, rows.commentrayPathRel, opts.commentrayMarkdown, opts.code)
+        : [];
+    const mdForDoc = injectCommentrayDocAnchors(opts.commentrayMarkdown, links.length > 0 ? links : undefined);
     let scrollBlockLinksB64 = "";
-    const multi = opts.multiAngleBrowsing;
-    const multiActive = Boolean(multi && multi.angles.length >= 2);
-    if (multiActive && multi) {
-        const built = await buildMultiAngleDualPaneShell(opts, multi);
-        const ms = built.multiShell;
-        return {
-            layout: "dual",
-            shellInner: built.shellInner,
-            scrollBlockLinksB64: ms.scrollBlockLinksB64,
-            angleSelectHtml: built.angleSelectHtml,
-            multiAnglePayloadB64: built.multiAnglePayloadB64,
-            sourceMarkdownToggleEnabled: built.sourceMarkdownToggleEnabled,
-            sourcePaneDefaultMode: built.sourcePaneDefaultMode,
-            multiShell: ms,
-        };
+    if (links.length > 0) {
+        scrollBlockLinksB64 = Buffer.from(JSON.stringify(links), "utf8").toString("base64");
     }
-    if (opts.blockStretchRows && layoutPref !== "dual") {
+    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(shellPairSourcePath(opts.filePath, opts.blockStretchRows?.sourceRelative), shellPairCommentrayPath(opts.commentrayPathForSearch, opts.blockStretchRows?.commentrayPathRel));
+    const shellInner = wrapDualShellInner(pairHtml, dualPanePanesInnerHtml(codeHtml, commentrayHtml, sourceMarkdownPaneHtml));
+    return {
+        layout: "dual",
+        shellInner,
+        scrollBlockLinksB64,
+        angleSelectHtml: "",
+        multiAnglePayloadB64: "",
+        sourceMarkdownToggleEnabled: sourceMarkdownEnabled,
+        sourcePaneDefaultMode: "source",
+    };
+}
+async function buildSingleAngleCodeBrowserShell(opts, layoutPref) {
+    let layout = "dual";
+    let shellInner = "";
+    const sourceMarkdownEnabled = isMarkdownLikeSource(opts);
+    const sourceMarkdownUrls = sourceMarkdownEnabled ? sourcePaneOutputUrls(opts) : undefined;
+    if (layoutPref !== "dual") {
+        const fallbackSourceRelative = (opts.filePath ?? "").trim().length > 0 ? (opts.filePath ?? "").trim() : "source";
+        const fallbackCommentrayPathRel = (opts.commentrayPathForSearch ?? "").trim().length > 0
+            ? (opts.commentrayPathForSearch ?? "").trim()
+            : "commentray.md";
+        const fallbackSourceLineCount = Math.max(1, opts.code.split("\n").length);
+        const fallbackBlockId = "commentray-full";
+        const fallbackStretchMarkdown = opts.blockStretchRows === undefined
+            ? `<!-- commentray:block id=${fallbackBlockId} -->\n${opts.commentrayMarkdown}`
+            : opts.commentrayMarkdown;
+        const stretchRows = opts.blockStretchRows ??
+            {
+                index: {
+                    schemaVersion: CURRENT_SCHEMA_VERSION,
+                    byCommentrayPath: {
+                        [fallbackCommentrayPathRel]: {
+                            sourcePath: fallbackSourceRelative,
+                            commentrayPath: fallbackCommentrayPathRel,
+                            blocks: [
+                                { id: fallbackBlockId, anchor: `lines:1-${String(fallbackSourceLineCount)}` },
+                            ],
+                        },
+                    },
+                },
+                sourceRelative: fallbackSourceRelative,
+                commentrayPathRel: fallbackCommentrayPathRel,
+            };
         const stretched = await tryBuildBlockStretchTableHtml({
             code: opts.code,
             language: opts.language,
-            commentrayMarkdown: opts.commentrayMarkdown,
-            index: opts.blockStretchRows.index,
-            sourceRelative: opts.blockStretchRows.sourceRelative,
-            commentrayPathRel: opts.blockStretchRows.commentrayPathRel,
+            commentrayMarkdown: fallbackStretchMarkdown,
+            index: stretchRows.index,
+            sourceRelative: stretchRows.sourceRelative,
+            commentrayPathRel: stretchRows.commentrayPathRel,
             commentrayOutputUrls: opts.commentrayOutputUrls,
+            sourceMarkdownOutputUrls: sourceMarkdownUrls,
+            stretchBufferSync: stretchBufferSyncFromOpts(opts),
         });
         if (stretched) {
             layout = "stretch";
-            shellInner = `        ${stretched.preambleHtml}\n` + `        ${stretched.tableInnerHtml}\n`;
+            shellInner = wrapShellInnerWithPairContext(renderShellPairContextHtml(shellPairSourcePath(opts.filePath, stretchRows.sourceRelative), shellPairCommentrayPath(opts.commentrayPathForSearch, stretchRows.commentrayPathRel)), `        ${stretched.preambleHtml}\n` + `        ${stretched.tableInnerHtml}\n`);
         }
     }
     if (layout === "dual") {
-        const links = opts.blockStretchRows !== undefined
-            ? buildBlockScrollLinks(opts.blockStretchRows.index, opts.blockStretchRows.sourceRelative, opts.blockStretchRows.commentrayPathRel, opts.commentrayMarkdown, opts.code)
-            : [];
-        const mdForDoc = injectCommentrayDocAnchors(opts.commentrayMarkdown, links.length > 0 ? links : undefined);
-        if (links.length > 0) {
-            scrollBlockLinksB64 = Buffer.from(JSON.stringify(links), "utf8").toString("base64");
-        }
-        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, sourceMarkdownPaneHtml));
-        return {
-            layout,
-            shellInner,
-            scrollBlockLinksB64,
-            angleSelectHtml: "",
-            multiAnglePayloadB64: "",
-            sourceMarkdownToggleEnabled: sourceMarkdownEnabled,
-            sourcePaneDefaultMode: sourceMarkdownEnabled ? "rendered-markdown" : "source",
-        };
+        return buildDualPaneSingleAngleShell(opts);
+    }
+    const rows = opts.blockStretchRows;
+    const links = rows !== undefined
+        ? buildBlockScrollLinks(rows.index, rows.sourceRelative, rows.commentrayPathRel, opts.commentrayMarkdown, opts.code)
+        : [];
+    let scrollBlockLinksB64 = "";
+    if (links.length > 0) {
+        scrollBlockLinksB64 = Buffer.from(JSON.stringify(links), "utf8").toString("base64");
     }
     return {
         layout,
@@ -2160,10 +2418,35 @@ async function buildCodeBrowserShell(opts, layoutPref) {
         scrollBlockLinksB64,
         angleSelectHtml: "",
         multiAnglePayloadB64: "",
-        sourceMarkdownToggleEnabled: false,
+        sourceMarkdownToggleEnabled: sourceMarkdownEnabled,
         sourcePaneDefaultMode: "source",
+        stretchBufferSync: stretchBufferSyncFromOpts(opts),
     };
 }
+async function buildCodeBrowserShell(opts, layoutPref) {
+    const multi = opts.multiAngleBrowsing;
+    const multiActive = Boolean(multi && multi.angles.length >= 2);
+    if (multiActive && multi) {
+        if (layoutPref !== "dual") {
+            const stretchMulti = await buildMultiAngleBlockStretchShell(opts, multi);
+            if (stretchMulti !== null)
+                return stretchMulti;
+        }
+        const built = await buildMultiAngleDualPaneShell(opts, multi);
+        const ms = built.multiShell;
+        return {
+            layout: "dual",
+            shellInner: built.shellInner,
+            scrollBlockLinksB64: ms.scrollBlockLinksB64,
+            angleSelectHtml: built.angleSelectHtml,
+            multiAnglePayloadB64: built.multiAnglePayloadB64,
+            sourceMarkdownToggleEnabled: built.sourceMarkdownToggleEnabled,
+            sourcePaneDefaultMode: built.sourcePaneDefaultMode,
+            multiShell: ms,
+        };
+    }
+    return buildSingleAngleCodeBrowserShell(opts, layoutPref);
+}
 function searchChromeFromOptions(opts, commentrayPathOverride) {
     const crPath = (commentrayPathOverride ?? opts.commentrayPathForSearch ?? "").trim();
     if (opts.staticSearchScope === "commentray-and-paths") {
@@ -2198,8 +2481,7 @@ function currentPairCommentrayPathRel(shell, opts) {
         opts.blockStretchRows?.commentrayPathRel ??
         "").trim();
 }
-/**
- * Repo-relative source + companion Markdown paths for matching the current page to nav pairs
+/** 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) {
@@ -2211,8 +2493,6 @@ function shellPairIdentityDataAttrs(shell, opts) {
 }
 /** 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();
@@ -2272,6 +2552,13 @@ export async function renderCodeBrowserHtml(opts) {
     const pairIdentityDataAttrs = shellPairIdentityDataAttrs(shell, opts);
     const sourceMarkdownToggles = sourceMarkdownToggleControlsHtml(shell.sourceMarkdownToggleEnabled);
     const sourcePaneModeAttr = ` data-source-pane-mode="${shell.sourcePaneDefaultMode}"`;
+    const scrollSyncStrategyShellAttr = opts.dualPaneScrollSyncStrategy !== undefined &&
+        opts.dualPaneScrollSyncStrategy !== DEFAULT_DUAL_PANE_SCROLL_SYNC_STRATEGY
+        ? ` data-scroll-sync-strategy="${escapeHtml(opts.dualPaneScrollSyncStrategy)}"`
+        : "";
+    const stretchBufferSyncShellAttr = shell.layout === "stretch" && shell.stretchBufferSync === "flow-synchronizer"
+        ? ` data-stretch-buffer-sync="flow-synchronizer"`
+        : "";
     return buildCodeBrowserPageHtml({
         title,
         metaDescriptionHtml,
@@ -2300,6 +2587,8 @@ export async function renderCodeBrowserHtml(opts) {
         sourceMarkdownToggleHtml: sourceMarkdownToggles.sourceMarkdownToggleHtml,
         sourceMarkdownFlipScrollAffordanceHtml: sourceMarkdownToggles.sourceMarkdownFlipScrollAffordanceHtml,
         sourcePaneModeAttr,
+        scrollSyncStrategyShellAttr,
+        stretchBufferSyncShellAttr,
     });
 }
 //# sourceMappingURL=code-browser.js.map