@commentray/render 0.1.0 → 0.1.2

package/dist/code-browser-client.js

@@ -1,6 +1,7 @@
 import { FuzzySearcher, PrefixSearcher, Query, SearcherFactory, SubstringSearcher, } from "@m31coding/fuzzy-search";
-import { activeBlockIdForViewport, clampViewportYToGutterLocal, codeLineDomIndex0, gutterRayBezierPaths, sortBlockLinksBySource, } from "./code-browser-block-rays.js";
+import { activeBlockIdForCommentrayLine0, activeBlockIdForViewport, clampViewportYToGutterLocal, codeLineDomIndex0, dedupeBlockScrollLinksById, gutterRayBezierPaths, maxRenderableCommentaryContentBottomViewport, nextBlockLinkInCommentrayOrder, sortBlockLinksBySource, } from "./code-browser-block-rays.js";
 import { mirroredScrollTop, pickCommentrayLineForSourceScroll, pickSourceLine0ForCommentrayScroll, } from "./code-browser-scroll-sync.js";
+import { maxCommentrayAnchorLine0AtOrAboveViewportY } from "./commentray-anchor-viewport-probe.js";
 import { decodeBase64Utf8 } from "./code-browser-encoding.js";
 import { readEmbeddedRawB64Strings } from "./code-browser-embedded-payload.js";
 import { escapeHtmlHighlightingSearchTokens, filterPairsByDocumentedTreeQuery, findOrderedTokenSpans, lineAtIndex, offsetToLineIndex, pathRowsFromDocumentedPairs, tokenizeQuery, uniqueSourceFilePreviewRows, } from "./code-browser-search.js";
@@ -700,11 +701,22 @@ function parseScrollBlockLinksFromShell(b64) {
                 typeof o.commentrayLine === "number" &&
                 typeof o.sourceStart === "number" &&
                 typeof o.sourceEnd === "number") {
+                const mvRaw = o.markerViewportHalfOpen1Based;
+                const mv = typeof mvRaw === "object" &&
+                    mvRaw !== null &&
+                    typeof mvRaw.lo === "number" &&
+                    typeof mvRaw.hiExclusive === "number"
+                    ? {
+                        lo: mvRaw.lo,
+                        hiExclusive: mvRaw.hiExclusive,
+                    }
+                    : { lo: o.sourceStart, hiExclusive: o.sourceEnd + 1 };
                 out.push({
                     id: o.id,
                     commentrayLine: o.commentrayLine,
                     sourceStart: o.sourceStart,
                     sourceEnd: o.sourceEnd,
+                    markerViewportHalfOpen1Based: mv,
                 });
             }
         }
@@ -730,19 +742,15 @@ function readCommentrayLine0FromAnchor(el) {
         return null;
     return Number(lineAttr);
 }
-/** Greatest marker line whose anchor sits at or above viewport Y `y`. */
 function bestCommentrayAnchorLine0AtOrAboveY(anchors, y) {
-    let best = 0;
+    const readings = [];
     for (const a of anchors) {
         const line0 = readCommentrayLine0FromAnchor(a);
         if (line0 === null)
             continue;
-        if (a.getBoundingClientRect().top <= y + 1 + 1e-3)
-            best = line0;
-        else
-            break;
+        readings.push({ line0, top: a.getBoundingClientRect().top });
     }
-    return best;
+    return maxCommentrayAnchorLine0AtOrAboveViewportY(readings, y);
 }
 function lastCommentrayAnchorLine0(anchors) {
     const last = anchors[anchors.length - 1];
@@ -815,7 +823,8 @@ function probeCommentrayLine0FromDoc(docPane) {
     if (paneScrollNearEnd(docPane))
         return lastCommentrayAnchorLine0(anchors);
     const dr = docPane.getBoundingClientRect();
-    const y = dr.top + docPane.clientTop + 2;
+    /** Same band as the root-scroll branch: a few px below the pane top so block anchors sit inside `top <= y` while their prose is what the reader sees first. */
+    const y = dr.top + docPane.clientTop + Math.max(2, Math.min(40, docPane.clientHeight * 0.15));
     return bestCommentrayAnchorLine0AtOrAboveY(anchors, y);
 }
 function pageBreakPullEnabled() {
@@ -1015,16 +1024,28 @@ function centerYInViewport(el) {
 function codeLineHighlightCenterYViewport(lineEl) {
     return centerYInViewport(lineEl);
 }
-function commentaryBandEndYViewport(docScrollEl, next, docTop) {
+function commentaryBandEndYViewport(docScrollEl, next, docTop, clipThroughPageBreakGaps) {
     if (next) {
         const nextEl = document.getElementById(`commentray-block-${next.id}`);
-        return nextEl ? nextEl.getBoundingClientRect().top - 3 : centerYInViewport(docTop);
+        if (!nextEl)
+            return centerYInViewport(docTop);
+        const nextTop = nextEl.getBoundingClientRect().top - 3;
+        if (!clipThroughPageBreakGaps)
+            return nextTop;
+        const docBandTop = docTop.getBoundingClientRect().top + 4;
+        const contentBottom = maxRenderableCommentaryContentBottomViewport(docScrollEl, docTop, nextEl);
+        return Math.min(nextTop, Math.max(docBandTop, contentBottom));
     }
     const dr = docScrollEl.getBoundingClientRect();
     let bottom = dr.bottom - 4;
     const lastKid = docScrollEl.children[docScrollEl.children.length - 1];
     if (lastKid)
         bottom = Math.min(bottom, lastKid.getBoundingClientRect().bottom - 4);
+    if (clipThroughPageBreakGaps) {
+        const docBandTop = docTop.getBoundingClientRect().top + 4;
+        const contentBottom = maxRenderableCommentaryContentBottomViewport(docScrollEl, docTop, null);
+        bottom = Math.min(bottom, Math.max(docBandTop, contentBottom));
+    }
     return bottom;
 }
 function sourceAnchorIndexFromId(id, prefix) {
@@ -1087,7 +1108,7 @@ function subscribeBlockRayRedraw(gutter, codePane, docScrollEl, scheduleDraw) {
         ro.observe(shell);
 }
 function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSourceLine1Based, lineIdPrefix) {
-    const links = getLinks();
+    const links = dedupeBlockScrollLinksById(getLinks());
     const sorted = sortBlockLinksBySource(links);
     const gutterRect = gutter.getBoundingClientRect();
     const w = gutterRect.width;
@@ -1096,7 +1117,11 @@ function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSource
         svg.replaceChildren();
         return;
     }
-    const activeId = activeBlockIdForViewport(links, probeTopSourceLine1Based());
+    /** Doc-aligned active block matches visible commentary; code-only probe can lag in page gaps. */
+    const activeId = docScrollEl.querySelector(".commentray-block-anchor") !== null
+        ? activeBlockIdForCommentrayLine0(links, probeCommentrayLine0FromDoc(docScrollEl))
+        : activeBlockIdForViewport(links, probeTopSourceLine1Based());
+    const clipGutterRaysThroughPageBreakGaps = pageBreakPullEnabled();
     svg.setAttribute("viewBox", `0 0 ${String(w)} ${String(h)}`);
     svg.setAttribute("preserveAspectRatio", "none");
     const parts = [];
@@ -1108,7 +1133,7 @@ function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSource
         const link = sorted[i];
         if (!link)
             continue;
-        const next = sorted[i + 1];
+        const next = nextBlockLinkInCommentrayOrder(links, link);
         const i0 = codeLineDomIndex0(link.sourceStart);
         const i1 = codeLineDomIndex0(link.sourceEnd);
         const codeTop = document.getElementById(`${lineIdPrefix}${String(i0)}`) ??
@@ -1118,7 +1143,7 @@ function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSource
         const docTop = document.getElementById(`commentray-block-${link.id}`);
         if (!codeTop || !codeBot || !docTop)
             continue;
-        const docEndYViewport = commentaryBandEndYViewport(docScrollEl, next, docTop);
+        const docEndYViewport = commentaryBandEndYViewport(docScrollEl, next, docTop, clipGutterRaysThroughPageBreakGaps);
         const yCodeTop = codeLineHighlightCenterYViewport(codeTop);
         const yCodeBot = codeLineHighlightCenterYViewport(codeBot);
         const yDocTop = docTop.getBoundingClientRect().top + 2;
@@ -1152,8 +1177,8 @@ function drawBlockRaysIntoSvg(svg, gutter, docScrollEl, getLinks, probeTopSource
 }
 /**
  * Splines in the gutter between each block’s source range and its commentary band (dual pane,
- * index-backed blocks). Emphasizes the block aligned with the current source viewport; clamps
- * off-screen endpoints so readers see which way to scroll.
+ * index-backed blocks). Emphasizes the block aligned with the **doc** viewport when block anchors
+ * exist; otherwise the source viewport. Clamps off-screen endpoints so readers see which way to scroll.
  *
  * @returns Request a redraw after DOM changes that do not resize the panes (e.g. multi-angle body swap).
  */
@@ -1493,12 +1518,13 @@ function wireDocumentedFilesTree() {
     if (!(hub instanceof HTMLDetailsElement) || !(treeHost instanceof HTMLElement)) {
         return;
     }
+    const detailsHub = hub;
     const treeMount = treeHost;
-    const jsonUrl = hub.getAttribute("data-nav-json-url")?.trim() ?? "";
+    const jsonUrl = detailsHub.getAttribute("data-nav-json-url")?.trim() ?? "";
     const embeddedB64 = shell?.getAttribute("data-documented-pairs-b64")?.trim() ?? "";
     if (jsonUrl.length === 0 && embeddedB64.length === 0)
         return;
-    const placeDocHubFlyout = wireDocumentedFilesTreeMobileFlyout(hub);
+    const placeDocHubFlyout = wireDocumentedFilesTreeMobileFlyout(detailsHub);
     const ensureLoaded = loadDocumentedPairs(jsonUrl, embeddedB64);
     let cachedPairs = null;
     function applyFilterAndRender() {
@@ -1521,21 +1547,31 @@ function wireDocumentedFilesTree() {
                 '<p class="nav-rail__doc-hub-hint" role="alert">Could not load the file list.</p>';
         }
     }
-    hub.addEventListener("toggle", () => {
+    detailsHub.addEventListener("toggle", () => {
         placeDocHubFlyout();
-        if (hub.open) {
+        if (detailsHub.open) {
             globalThis.requestAnimationFrame(() => {
                 placeDocHubFlyout();
                 focusDocumentedFilesFilterInput();
             });
         }
-        if (!hub.open)
+        if (!detailsHub.open)
             return;
         void hydrateTree();
     });
+    function onDocumentedFilesHubEscape(ev) {
+        if (!detailsHub.open || ev.key !== "Escape")
+            return;
+        ev.preventDefault();
+        detailsHub.open = false;
+        const sum = detailsHub.querySelector("summary");
+        if (sum instanceof HTMLElement)
+            sum.focus({ preventScroll: true });
+    }
+    document.addEventListener("keydown", onDocumentedFilesHubEscape, true);
     if (filterInput instanceof HTMLInputElement) {
         filterInput.addEventListener("input", () => {
-            if (!hub.open || cachedPairs === null)
+            if (!detailsHub.open || cachedPairs === null)
                 return;
             applyFilterAndRender();
         });
@@ -2333,7 +2369,7 @@ function humaneBrowseAliasPathForSource(sourcePath) {
     return sourcePath
         .split("/")
         .filter((seg) => seg.length > 0)
-        .map((seg) => encodeURIComponent(seg))
+        .map((seg) => seg.startsWith(".") ? `%2E${encodeURIComponent(seg.slice(1))}` : encodeURIComponent(seg))
         .join("/");
 }
 function companionStemFromCommentrayPath(commentrayPath) {
@@ -2418,12 +2454,29 @@ function maybeBackfillAddressBarWithHumanePairLink() {
     normalizeDocumentationHomeHrefForCurrentPath();
     if (!shellEligibleForHumaneBackfill(shell, pathname))
         return;
-    const nextPath = nextHumaneBrowsePathForShell(shell, pathname);
-    if (nextPath === null)
-        return;
     const beforeHref = globalThis.location.href;
     absolutizeNavJsonUrls(shell, beforeHref);
     normalizePairBrowseHrefForCurrentPath(shell, pathname);
+    /** Prefer the same `staticBrowseUrl` the static build put on `#shell` (slug or `…/index.html` shims). */
+    const canonicalBrowsePathname = (() => {
+        const raw = shell.getAttribute("data-commentray-pair-browse-href")?.trim() ?? "";
+        if (raw.length === 0)
+            return null;
+        try {
+            const u = new URL(raw, globalThis.location.href);
+            if (u.origin !== globalThis.location.origin)
+                return null;
+            if (!u.pathname.includes("/browse/"))
+                return null;
+            return u.pathname;
+        }
+        catch {
+            return null;
+        }
+    })();
+    const nextPath = canonicalBrowsePathname ?? nextHumaneBrowsePathForShell(shell, pathname);
+    if (nextPath === null)
+        return;
     globalThis.history.replaceState(null, "", `${nextPath}${globalThis.location.search}${globalThis.location.hash}`);
 }
 function permalinkHashSuffixFromUi() {