@commentray/core 0.2.0 → 0.3.1

package/dist/approval-flow-grid.d.ts

@@ -0,0 +1,25 @@
+import { type ApprovalFlowSection, type ApprovalGridFormat } from "./buffering-flow-synchronizer-approval-printer.js";
+export declare function splitApprovalLineToCells(line: string, columnCount: number, columnGap?: string): string[];
+export declare function parseApprovalRows(asciiColumns: string, format?: ApprovalGridFormat): Array<string[] | null>;
+/**
+ * Joins section pairs when a blank line only separated flows that still belong to one sync story
+ * (e.g. `XXXX  R1XX` / blank / `R1XX  XXXX` must synchronize as one section).
+ */
+export declare function mergeAdjacentApprovalSectionsForContinuedSync(sections: ApprovalFlowSection[]): ApprovalFlowSection[];
+/** A trailing section with items on only one column is folded into the previous section (see `two-columns.second-column-missing-first-region.input.txt`). */
+export declare function mergeOrphanSingleColumnTailSection(sections: ApprovalFlowSection[]): ApprovalFlowSection[];
+/**
+ * Parse fixed-width two-column approval **input** grids into flow sections (blank row = section break).
+ * A synced region block is one `R{N}XX` row plus continuation rows in that column: `XXXX` body lines
+ * and/or empty cells opposite partner content (stagger), up to three rows total height. An anonymous
+ * block is consecutive `XXXX` lines in that column (height 1–3); a new `XXXX` row extends the open
+ * block unless height is already max, in which case a new `__ANON__*` block opens. Stagger before the
+ * next non-region block still adds `pendingStaggerSlackRows` → `bufferAbove` on that column’s next
+ * block when the region is closed at max height or by a new `R…XX` / section break.
+ */
+export declare function parseApprovalFlowSectionsWithFormat(asciiColumns: string): {
+    sections: ApprovalFlowSection[];
+    format: ApprovalGridFormat;
+};
+export declare function parseApprovalFlowSections(asciiColumns: string): ApprovalFlowSection[];
+//# sourceMappingURL=approval-flow-grid.d.ts.map

package/dist/approval-flow-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-flow-grid.d.ts","sourceRoot":"","sources":["../src/approval-flow-grid.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAExB,MAAM,mDAAmD,CAAC;AAO3D,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAA4B,GACtC,MAAM,EAAE,CAuBV;AAED,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,KAAK,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAgBxB;AAwLD;;;GAGG;AACH,wBAAgB,6CAA6C,CAC3D,QAAQ,EAAE,mBAAmB,EAAE,GAC9B,mBAAmB,EAAE,CAavB;AAED,6JAA6J;AAC7J,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,mBAAmB,EAAE,GAC9B,mBAAmB,EAAE,CAevB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,CAAC,YAAY,EAAE,MAAM,GAAG;IACzE,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,MAAM,EAAE,kBAAkB,CAAC;CAC5B,CAgDA;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAErF"}

package/dist/approval-flow-grid.js

@@ -0,0 +1,274 @@
+import { APPROVAL_CELL_WIDTH, APPROVAL_COLUMN_GAP, APPROVAL_FILLED_ROW, APPROVAL_REGION_TOKEN_RE, inferApprovalGridFormatFromAscii, } from "./buffering-flow-synchronizer-approval-printer.js";
+const ANONYMOUS_ID_PREFIX = "__ANON__";
+/** One `R{N}XX` header plus up to two continuation rows per column (see `HeightAdjustable.height`). */
+const MAX_APPROVAL_REGION_HEIGHT = 3;
+export function splitApprovalLineToCells(line, columnCount, columnGap = APPROVAL_COLUMN_GAP) {
+    const expectedLength = columnCount * APPROVAL_CELL_WIDTH + (columnCount - 1) * columnGap.length;
+    if (line.length !== expectedLength) {
+        throw new Error(`Row length ${line.length} does not match expected ${expectedLength}.`);
+    }
+    const cells = [];
+    for (let i = 0; i < columnCount; i++) {
+        const start = i * (APPROVAL_CELL_WIDTH + columnGap.length);
+        const cell = line.slice(start, start + APPROVAL_CELL_WIDTH);
+        cells.push(cell);
+        if (i < columnCount - 1) {
+            const gap = line.slice(start + APPROVAL_CELL_WIDTH, start + APPROVAL_CELL_WIDTH + columnGap.length);
+            if (gap !== columnGap) {
+                throw new Error(`Columns must be separated by exactly ${String(columnGap.length)} gap character(s).`);
+            }
+        }
+    }
+    return cells;
+}
+export function parseApprovalRows(asciiColumns, format) {
+    const lines = asciiColumns.split("\n").map((line) => line.replace(/\r$/, ""));
+    const nonBlankLines = lines.filter((line) => line.trim().length > 0);
+    if (nonBlankLines.length === 0)
+        return [];
+    const fmt = format ?? inferApprovalGridFormatFromAscii(asciiColumns);
+    const firstLine = nonBlankLines[0];
+    if (firstLine === undefined)
+        return [];
+    const first = firstLine.trimEnd();
+    const hasGap = first.length > APPROVAL_CELL_WIDTH;
+    const columnCount = hasGap ? 2 : 1;
+    const rowDataLen = fmt.rowDataLen;
+    return lines.map((line) => {
+        if (line.trim().length === 0)
+            return null;
+        const padded = line.length < rowDataLen ? line.padEnd(rowDataLen, " ") : line;
+        return splitApprovalLineToCells(padded, columnCount, fmt.columnGap);
+    });
+}
+function emptyColumnState() {
+    return {
+        currentRegion: null,
+        currentHeight: 0,
+        anonymousBlockCount: 0,
+        bufferAboveForCurrentOpenBlock: 0,
+        pendingStaggerSlackRows: 0,
+        syncRegionContinuationRows: [],
+    };
+}
+function pushCurrentRegionIfAny(items, st) {
+    if (st.currentRegion === null)
+        return;
+    const id = st.currentRegion;
+    const height = st.currentHeight;
+    if (isSyncRegionId(id) && height > 1) {
+        if (st.syncRegionContinuationRows.length !== height - 1) {
+            throw new Error(`Internal parse error: R region ${id} height ${String(height)} but ${String(st.syncRegionContinuationRows.length)} continuation kind(s).`);
+        }
+    }
+    const row = {
+        id,
+        height,
+        bufferAbove: st.bufferAboveForCurrentOpenBlock,
+        bufferBelow: 0,
+    };
+    if (isSyncRegionId(id) && height > 1) {
+        row.syncRegionContinuationRows = [...st.syncRegionContinuationRows];
+    }
+    items.push(row);
+    st.currentRegion = null;
+    st.currentHeight = 0;
+    st.bufferAboveForCurrentOpenBlock = 0;
+    st.syncRegionContinuationRows = [];
+}
+function openNewBlock(st, id) {
+    st.currentRegion = id;
+    st.currentHeight = 1;
+    st.bufferAboveForCurrentOpenBlock = st.pendingStaggerSlackRows;
+    st.pendingStaggerSlackRows = 0;
+    st.syncRegionContinuationRows = [];
+}
+function isSyncRegionId(id) {
+    return id !== null && APPROVAL_REGION_TOKEN_RE.test(id);
+}
+function consumeEmptyCellOppositeHasInk(items, st) {
+    if (st.currentRegion?.startsWith(ANONYMOUS_ID_PREFIX)) {
+        pushCurrentRegionIfAny(items, st);
+    }
+    if (isSyncRegionId(st.currentRegion)) {
+        if (st.currentHeight < MAX_APPROVAL_REGION_HEIGHT) {
+            st.currentHeight += 1;
+            st.syncRegionContinuationRows.push("stagger");
+            return;
+        }
+        pushCurrentRegionIfAny(items, st);
+        st.pendingStaggerSlackRows += 1;
+        return;
+    }
+    st.pendingStaggerSlackRows += 1;
+}
+function consumeFilledRowToken(items, st) {
+    if (st.currentRegion?.startsWith(ANONYMOUS_ID_PREFIX) &&
+        st.currentHeight >= MAX_APPROVAL_REGION_HEIGHT) {
+        pushCurrentRegionIfAny(items, st);
+    }
+    if (st.currentRegion === null) {
+        st.anonymousBlockCount += 1;
+        openNewBlock(st, `${ANONYMOUS_ID_PREFIX}${st.anonymousBlockCount}`);
+        return;
+    }
+    if (isSyncRegionId(st.currentRegion)) {
+        if (st.currentHeight < MAX_APPROVAL_REGION_HEIGHT) {
+            st.currentHeight += 1;
+            st.syncRegionContinuationRows.push("body");
+            return;
+        }
+        pushCurrentRegionIfAny(items, st);
+        st.anonymousBlockCount += 1;
+        openNewBlock(st, `${ANONYMOUS_ID_PREFIX}${st.anonymousBlockCount}`);
+        return;
+    }
+    st.currentHeight += 1;
+}
+function consumeOneColumn(row, columnIndex, items, st, partnerTrimmed) {
+    const token = row[columnIndex]?.trim() ?? "";
+    if (token === "") {
+        if (partnerTrimmed.length > 0) {
+            consumeEmptyCellOppositeHasInk(items, st);
+            return;
+        }
+        pushCurrentRegionIfAny(items, st);
+        return;
+    }
+    if (token === APPROVAL_FILLED_ROW) {
+        consumeFilledRowToken(items, st);
+        return;
+    }
+    if (!APPROVAL_REGION_TOKEN_RE.test(token)) {
+        throw new Error(`Unsupported token "${token}". Use RnXX markers or ${APPROVAL_FILLED_ROW}.`);
+    }
+    if (token === st.currentRegion) {
+        st.currentHeight += 1;
+        if (isSyncRegionId(st.currentRegion)) {
+            st.syncRegionContinuationRows.push("body");
+        }
+        return;
+    }
+    pushCurrentRegionIfAny(items, st);
+    openNewBlock(st, token);
+}
+function finalizeColumn(items, st) {
+    pushCurrentRegionIfAny(items, st);
+}
+function isSyncRegionMarkerId(id) {
+    return APPROVAL_REGION_TOKEN_RE.test(id);
+}
+function shouldMergeApprovalSectionsAcrossBlank(a, b) {
+    const aLastLeft = a.left.at(-1);
+    const aLastRight = a.right.at(-1);
+    const bFirstLeft = b.left[0];
+    const bFirstRight = b.right[0];
+    if (aLastRight !== undefined &&
+        bFirstLeft !== undefined &&
+        isSyncRegionMarkerId(aLastRight.id) &&
+        aLastRight.id === bFirstLeft.id) {
+        return true;
+    }
+    if (aLastLeft !== undefined &&
+        bFirstRight !== undefined &&
+        isSyncRegionMarkerId(aLastLeft.id) &&
+        aLastLeft.id === bFirstRight.id) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Joins section pairs when a blank line only separated flows that still belong to one sync story
+ * (e.g. `XXXX  R1XX` / blank / `R1XX  XXXX` must synchronize as one section).
+ */
+export function mergeAdjacentApprovalSectionsForContinuedSync(sections) {
+    const out = [...sections];
+    let i = 0;
+    while (i < out.length - 1) {
+        const a = out[i];
+        const b = out[i + 1];
+        if (a !== undefined && b !== undefined && shouldMergeApprovalSectionsAcrossBlank(a, b)) {
+            out.splice(i, 2, { left: [...a.left, ...b.left], right: [...a.right, ...b.right] });
+            continue;
+        }
+        i++;
+    }
+    return out;
+}
+/** A trailing section with items on only one column is folded into the previous section (see `two-columns.second-column-missing-first-region.input.txt`). */
+export function mergeOrphanSingleColumnTailSection(sections) {
+    if (sections.length < 2)
+        return sections;
+    const last = sections[sections.length - 1];
+    const prev = sections[sections.length - 2];
+    if (last === undefined || prev === undefined)
+        return sections;
+    const lastOrphanLeft = last.right.length === 0 && last.left.length > 0;
+    const lastOrphanRight = last.left.length === 0 && last.right.length > 0;
+    if (!lastOrphanLeft && !lastOrphanRight)
+        return sections;
+    return [
+        ...sections.slice(0, -2),
+        {
+            left: lastOrphanLeft ? [...prev.left, ...last.left] : [...prev.left],
+            right: lastOrphanRight ? [...prev.right, ...last.right] : [...prev.right],
+        },
+    ];
+}
+/**
+ * Parse fixed-width two-column approval **input** grids into flow sections (blank row = section break).
+ * A synced region block is one `R{N}XX` row plus continuation rows in that column: `XXXX` body lines
+ * and/or empty cells opposite partner content (stagger), up to three rows total height. An anonymous
+ * block is consecutive `XXXX` lines in that column (height 1–3); a new `XXXX` row extends the open
+ * block unless height is already max, in which case a new `__ANON__*` block opens. Stagger before the
+ * next non-region block still adds `pendingStaggerSlackRows` → `bufferAbove` on that column’s next
+ * block when the region is closed at max height or by a new `R…XX` / section break.
+ */
+export function parseApprovalFlowSectionsWithFormat(asciiColumns) {
+    const format = inferApprovalGridFormatFromAscii(asciiColumns);
+    const rows = parseApprovalRows(asciiColumns, format);
+    if (rows.length === 0)
+        return { sections: [], format };
+    const firstDataRow = rows.find((row) => row !== null);
+    const columnCount = firstDataRow?.length ?? 0;
+    if (columnCount !== 2) {
+        throw new Error("Approval fixtures must contain exactly 2 columns.");
+    }
+    const sections = [];
+    let leftItems = [];
+    let rightItems = [];
+    let leftSt = emptyColumnState();
+    let rightSt = emptyColumnState();
+    const flushSection = () => {
+        if (leftItems.length === 0 && rightItems.length === 0)
+            return;
+        sections.push({ left: leftItems, right: rightItems });
+        leftItems = [];
+        rightItems = [];
+        leftSt = emptyColumnState();
+        rightSt = emptyColumnState();
+    };
+    for (const row of rows) {
+        if (row === null) {
+            finalizeColumn(leftItems, leftSt);
+            finalizeColumn(rightItems, rightSt);
+            flushSection();
+            continue;
+        }
+        const leftTrim = row[0]?.trim() ?? "";
+        const rightTrim = row[1]?.trim() ?? "";
+        consumeOneColumn(row, 0, leftItems, leftSt, rightTrim);
+        consumeOneColumn(row, 1, rightItems, rightSt, leftTrim);
+    }
+    finalizeColumn(leftItems, leftSt);
+    finalizeColumn(rightItems, rightSt);
+    flushSection();
+    return {
+        sections: mergeOrphanSingleColumnTailSection(mergeAdjacentApprovalSectionsForContinuedSync(sections)),
+        format,
+    };
+}
+export function parseApprovalFlowSections(asciiColumns) {
+    return parseApprovalFlowSectionsWithFormat(asciiColumns).sections;
+}
+//# sourceMappingURL=approval-flow-grid.js.map

package/dist/approval-flow-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-flow-grid.js","sourceRoot":"","sources":["../src/approval-flow-grid.ts"],"names":[],"mappings":"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"}

package/dist/block-scroll-pickers.d.ts

@@ -16,6 +16,39 @@ export type BlockScrollLink = {
         hiExclusive: number;
     };
 };
+/**
+ * Which index block “owns” the source viewport top line (1-based), without hysteresis.
+ * Same geometry as {@link pickCommentrayLineForSourceScroll}.
+ */
+/**
+ * The index block whose source viewport span **strictly contains** `topSourceLine1Based`
+ * (`[lo, hiExclusive)`). When spans overlap, the earliest block by `lo` wins. Returns `null` in
+ * true inter-block **gaps** (including above the first `lo` only when that line is still below
+ * `lo` — callers combine with {@link sourceTopLineStrictlyBeforeFirstIndexLine} for “prelude”).
+ */
+export declare function blockStrictlyContainingSourceViewportLine(blocks: BlockScrollLink[], topSourceLine1Based: number): BlockScrollLink | null;
+/** True when the viewport top sits **strictly above** every block’s `[lo, hiExclusive)` span. */
+export declare function sourceTopLineStrictlyBeforeFirstIndexLine(blocks: BlockScrollLink[], topSourceLine1Based: number): boolean;
+/**
+ * True when the doc viewport probe sits strictly **between** two block marker lines in companion
+ * order (interstitial prose / blanks), not on a marker line and not before the first marker.
+ */
+export declare function commentrayProbeInStrictInterMarkerGap(blocks: BlockScrollLink[], topCommentrayLine0Based: number): boolean;
+export declare function pickBlockScrollLinkForSourceViewportTop(blocks: BlockScrollLink[], topSourceLine1Based: number): BlockScrollLink | null;
+/** Mutable lock for {@link pickBlockScrollLinkForSourceViewportWithHysteresis} / commentray twin. */
+export type BlockScrollStickyState = {
+    lockedId: string | null;
+};
+/** Default: require this many **source** lines into the naive winner before leaving the locked block. */
+export declare const DEFAULT_SOURCE_VIEWPORT_HYSTERESIS_LINES = 2;
+/** Default: require this many **commentray markdown** lines into the naive winner before leaving the lock. */
+export declare const DEFAULT_COMMENTRAY_VIEWPORT_HYSTERESIS_LINES = 4;
+/**
+ * Schmitt-style block pick for **source→commentray** sync: keeps the active block until the
+ * viewport top has moved clearly into another block’s territory, so probe noise at span edges
+ * does not flip the partner between unrelated regions.
+ */
+export declare function pickBlockScrollLinkForSourceViewportWithHysteresis(blocks: BlockScrollLink[], topSourceLine1Based: number, state: BlockScrollStickyState, hysteresisSourceLines?: number): BlockScrollLink | null;
 /**
  * Choose which commentray line (0-based) to reveal so the commentary matches
  * the top of the source viewport. Uses each link’s `markerViewportHalfOpen1Based`:
@@ -24,6 +57,15 @@ export type BlockScrollLink = {
  * block by `lo`.
  */
 export declare function pickCommentrayLineForSourceScroll(blocks: BlockScrollLink[], topSourceLine1Based: number): number | null;
+/**
+ * Schmitt twin for **commentray→source**: same idea in markdown line (0-based) space.
+ */
+export declare function pickBlockScrollLinkForCommentrayViewportWithHysteresis(blocks: BlockScrollLink[], topCommentrayLine0Based: number, state: BlockScrollStickyState, hysteresisMdLines?: number): BlockScrollLink | null;
+/**
+ * The block whose companion marker is at or above `topCommentrayLine0Based`
+ * (same rule as {@link pickSourceLine0ForCommentrayScroll}).
+ */
+export declare function pickBlockScrollLinkForCommentrayScroll(blocks: BlockScrollLink[], topCommentrayLine0Based: number): BlockScrollLink | null;
 /**
  * Choose a 0-based source line to reveal from the top of the commentray
  * viewport: the block whose marker is at or above that line wins; reveal the

package/dist/block-scroll-pickers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block-scroll-pickers.d.ts","sourceRoot":"","sources":["../src/block-scroll-pickers.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,4BAA4B,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,GAAG,IAAI,CAyBf;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,eAAe,EAAE,EACzB,uBAAuB,EAAE,MAAM,GAC9B,MAAM,GAAG,IAAI,CAUf"}
+{"version":3,"file":"block-scroll-pickers.d.ts","sourceRoot":"","sources":["../src/block-scroll-pickers.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,4BAA4B,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE,CAAC;AAEF;;;GAGG;AACH;;;;;GAKG;AACH,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,GAC1B,eAAe,GAAG,IAAI,CAUxB;AAED,iGAAiG;AACjG,wBAAgB,yCAAyC,CACvD,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAOT;AAED;;;GAGG;AACH,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,eAAe,EAAE,EACzB,uBAAuB,EAAE,MAAM,GAC9B,OAAO,CAqBT;AAED,wBAAgB,uCAAuC,CACrD,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,GAC1B,eAAe,GAAG,IAAI,CAyBxB;AAED,qGAAqG;AACrG,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,wCAAwC,IAAI,CAAC;AAE1D,8GAA8G;AAC9G,eAAO,MAAM,4CAA4C,IAAI,CAAC;AAoC9D;;;;GAIG;AACH,wBAAgB,kDAAkD,CAChE,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,EAC3B,KAAK,EAAE,sBAAsB,EAC7B,qBAAqB,GAAE,MAAiD,GACvE,eAAe,GAAG,IAAI,CA6BxB;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,eAAe,EAAE,EACzB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,GAAG,IAAI,CAGf;AAED;;GAEG;AACH,wBAAgB,sDAAsD,CACpE,MAAM,EAAE,eAAe,EAAE,EACzB,uBAAuB,EAAE,MAAM,EAC/B,KAAK,EAAE,sBAAsB,EAC7B,iBAAiB,GAAE,MAAqD,GACvE,eAAe,GAAG,IAAI,CA2BxB;AAED;;;GAGG;AACH,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,eAAe,EAAE,EACzB,uBAAuB,EAAE,MAAM,GAC9B,eAAe,GAAG,IAAI,CAUxB;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,eAAe,EAAE,EACzB,uBAAuB,EAAE,MAAM,GAC9B,MAAM,GAAG,IAAI,CAGf"}

package/dist/block-scroll-pickers.js

@@ -1,11 +1,63 @@
 /**
- * Choose which commentray line (0-based) to reveal so the commentary matches
- * the top of the source viewport. Uses each link’s `markerViewportHalfOpen1Based`:
- * if the top line falls in `[lo, hiExclusive)`, that block wins; in gaps, the block with the
- * greatest `lo` still at or above the top line; if the viewport is above every `lo`, the first
- * block by `lo`.
+ * Which index block “owns” the source viewport top line (1-based), without hysteresis.
+ * Same geometry as {@link pickCommentrayLineForSourceScroll}.
  */
-export function pickCommentrayLineForSourceScroll(blocks, topSourceLine1Based) {
+/**
+ * The index block whose source viewport span **strictly contains** `topSourceLine1Based`
+ * (`[lo, hiExclusive)`). When spans overlap, the earliest block by `lo` wins. Returns `null` in
+ * true inter-block **gaps** (including above the first `lo` only when that line is still below
+ * `lo` — callers combine with {@link sourceTopLineStrictlyBeforeFirstIndexLine} for “prelude”).
+ */
+export function blockStrictlyContainingSourceViewportLine(blocks, topSourceLine1Based) {
+    if (blocks.length === 0)
+        return null;
+    const sorted = [...blocks].sort((a, b) => a.markerViewportHalfOpen1Based.lo - b.markerViewportHalfOpen1Based.lo);
+    for (const b of sorted) {
+        const { lo, hiExclusive } = b.markerViewportHalfOpen1Based;
+        if (lo <= topSourceLine1Based && topSourceLine1Based < hiExclusive)
+            return b;
+    }
+    return null;
+}
+/** True when the viewport top sits **strictly above** every block’s `[lo, hiExclusive)` span. */
+export function sourceTopLineStrictlyBeforeFirstIndexLine(blocks, topSourceLine1Based) {
+    if (blocks.length === 0)
+        return false;
+    let minLo = Infinity;
+    for (const b of blocks) {
+        minLo = Math.min(minLo, b.markerViewportHalfOpen1Based.lo);
+    }
+    return topSourceLine1Based < minLo;
+}
+/**
+ * True when the doc viewport probe sits strictly **between** two block marker lines in companion
+ * order (interstitial prose / blanks), not on a marker line and not before the first marker.
+ */
+export function commentrayProbeInStrictInterMarkerGap(blocks, topCommentrayLine0Based) {
+    if (blocks.length === 0)
+        return false;
+    const s = [...blocks].sort((a, b) => a.commentrayLine - b.commentrayLine);
+    const head = s[0];
+    if (head === undefined)
+        return false;
+    if (topCommentrayLine0Based < head.commentrayLine)
+        return false;
+    for (let i = 0; i < s.length; i++) {
+        const cur = s[i];
+        if (!cur)
+            continue;
+        const next = s[i + 1];
+        if (next === undefined) {
+            return topCommentrayLine0Based > cur.commentrayLine;
+        }
+        if (cur.commentrayLine < topCommentrayLine0Based &&
+            topCommentrayLine0Based < next.commentrayLine) {
+            return true;
+        }
+    }
+    return false;
+}
+export function pickBlockScrollLinkForSourceViewportTop(blocks, topSourceLine1Based) {
     if (blocks.length === 0)
         return null;
     const sorted = [...blocks].sort((a, b) => a.markerViewportHalfOpen1Based.lo - b.markerViewportHalfOpen1Based.lo);
@@ -16,9 +68,9 @@ export function pickCommentrayLineForSourceScroll(blocks, topSourceLine1Based) {
     const inside = sorted.find((b) => b.markerViewportHalfOpen1Based.lo <= topSourceLine1Based &&
         topSourceLine1Based < b.markerViewportHalfOpen1Based.hiExclusive);
     if (inside)
-        return inside.commentrayLine;
+        return inside;
     if (topSourceLine1Based < firstLo)
-        return first.commentrayLine;
+        return first;
     let best = first;
     let bestLo = -Infinity;
     for (const b of sorted) {
@@ -28,14 +80,122 @@ export function pickCommentrayLineForSourceScroll(blocks, topSourceLine1Based) {
             bestLo = lo;
         }
     }
-    return best.commentrayLine;
+    return best;
 }
+/** Default: require this many **source** lines into the naive winner before leaving the locked block. */
+export const DEFAULT_SOURCE_VIEWPORT_HYSTERESIS_LINES = 2;
+/** Default: require this many **commentray markdown** lines into the naive winner before leaving the lock. */
+export const DEFAULT_COMMENTRAY_VIEWPORT_HYSTERESIS_LINES = 4;
 /**
- * Choose a 0-based source line to reveal from the top of the commentray
- * viewport: the block whose marker is at or above that line wins; reveal the
- * first line of its viewport span (`lo` − 1).
+ * Shared prelude for Schmitt-style hysteresis after the caller’s naive pick: clear lock when there
+ * is no naive block; bootstrap or refresh `lockedId` on first hit / same block / stale lock;
+ * otherwise hand off naive + locked for span- or line-based separation math.
  */
-export function pickSourceLine0ForCommentrayScroll(blocks, topCommentrayLine0Based) {
+function resolveStickyHysteresisLock(naive, blocks, state) {
+    if (!naive) {
+        state.lockedId = null;
+        return { outcome: "clear" };
+    }
+    if (state.lockedId === null) {
+        state.lockedId = naive.id;
+        return { outcome: "return", link: naive };
+    }
+    if (state.lockedId === naive.id) {
+        return { outcome: "return", link: naive };
+    }
+    const locked = blocks.find((b) => b.id === state.lockedId);
+    if (!locked) {
+        state.lockedId = naive.id;
+        return { outcome: "return", link: naive };
+    }
+    return { outcome: "hysteresis", naive, locked };
+}
+/**
+ * Schmitt-style block pick for **source→commentray** sync: keeps the active block until the
+ * viewport top has moved clearly into another block’s territory, so probe noise at span edges
+ * does not flip the partner between unrelated regions.
+ */
+export function pickBlockScrollLinkForSourceViewportWithHysteresis(blocks, topSourceLine1Based, state, hysteresisSourceLines = DEFAULT_SOURCE_VIEWPORT_HYSTERESIS_LINES) {
+    const HYST = Math.max(1, Math.floor(hysteresisSourceLines));
+    const naive = pickBlockScrollLinkForSourceViewportTop(blocks, topSourceLine1Based);
+    const res = resolveStickyHysteresisLock(naive, blocks, state);
+    if (res.outcome === "clear")
+        return null;
+    if (res.outcome === "return")
+        return res.link;
+    const { naive: n, locked } = res;
+    const loL = locked.markerViewportHalfOpen1Based.lo;
+    const hiL = locked.markerViewportHalfOpen1Based.hiExclusive;
+    const loC = n.markerViewportHalfOpen1Based.lo;
+    const hiC = n.markerViewportHalfOpen1Based.hiExclusive;
+    const separatedBelow = loC >= hiL;
+    const separatedAbove = hiC <= loL;
+    if (!separatedBelow && !separatedAbove) {
+        state.lockedId = n.id;
+        return n;
+    }
+    if (separatedBelow) {
+        if (topSourceLine1Based >= loC + HYST) {
+            state.lockedId = n.id;
+            return n;
+        }
+        return locked;
+    }
+    if (topSourceLine1Based <= loL - HYST) {
+        state.lockedId = n.id;
+        return n;
+    }
+    return locked;
+}
+/**
+ * Choose which commentray line (0-based) to reveal so the commentary matches
+ * the top of the source viewport. Uses each link’s `markerViewportHalfOpen1Based`:
+ * if the top line falls in `[lo, hiExclusive)`, that block wins; in gaps, the block with the
+ * greatest `lo` still at or above the top line; if the viewport is above every `lo`, the first
+ * block by `lo`.
+ */
+export function pickCommentrayLineForSourceScroll(blocks, topSourceLine1Based) {
+    const b = pickBlockScrollLinkForSourceViewportTop(blocks, topSourceLine1Based);
+    return b ? b.commentrayLine : null;
+}
+/**
+ * Schmitt twin for **commentray→source**: same idea in markdown line (0-based) space.
+ */
+export function pickBlockScrollLinkForCommentrayViewportWithHysteresis(blocks, topCommentrayLine0Based, state, hysteresisMdLines = DEFAULT_COMMENTRAY_VIEWPORT_HYSTERESIS_LINES) {
+    const HYST = Math.max(1, Math.floor(hysteresisMdLines));
+    const naive = pickBlockScrollLinkForCommentrayScroll(blocks, topCommentrayLine0Based);
+    const res = resolveStickyHysteresisLock(naive, blocks, state);
+    if (res.outcome === "clear")
+        return null;
+    if (res.outcome === "return")
+        return res.link;
+    const { naive: n, locked } = res;
+    const lL = locked.commentrayLine;
+    const lC = n.commentrayLine;
+    const separatedBelow = lC > lL;
+    const separatedAbove = lC < lL;
+    if (!separatedBelow && !separatedAbove) {
+        state.lockedId = n.id;
+        return n;
+    }
+    if (separatedBelow) {
+        if (topCommentrayLine0Based >= lC + HYST) {
+            state.lockedId = n.id;
+            return n;
+        }
+        return locked;
+    }
+    if (topCommentrayLine0Based <= lL - HYST) {
+        state.lockedId = n.id;
+        return n;
+    }
+    return locked;
+}
+/**
+ * The block whose companion marker is at or above `topCommentrayLine0Based`
+ * (same rule as {@link pickSourceLine0ForCommentrayScroll}).
+ */
+export function pickBlockScrollLinkForCommentrayScroll(blocks, topCommentrayLine0Based) {
     if (blocks.length === 0)
         return null;
     const sorted = [...blocks].sort((a, b) => a.commentrayLine - b.commentrayLine);
@@ -47,6 +207,15 @@ export function pickSourceLine0ForCommentrayScroll(blocks, topCommentrayLine0Bas
         if (b.commentrayLine <= topCommentrayLine0Based)
             best = b;
     }
-    return best.markerViewportHalfOpen1Based.lo - 1;
+    return best;
+}
+/**
+ * Choose a 0-based source line to reveal from the top of the commentray
+ * viewport: the block whose marker is at or above that line wins; reveal the
+ * first line of its viewport span (`lo` − 1).
+ */
+export function pickSourceLine0ForCommentrayScroll(blocks, topCommentrayLine0Based) {
+    const link = pickBlockScrollLinkForCommentrayScroll(blocks, topCommentrayLine0Based);
+    return link ? link.markerViewportHalfOpen1Based.lo - 1 : null;
 }
 //# sourceMappingURL=block-scroll-pickers.js.map

package/dist/block-scroll-pickers.js.map

@@ -1 +1 @@
-{"version":3,"file":"block-scroll-pickers.js","sourceRoot":"","sources":["../src/block-scroll-pickers.ts"],"names":[],"mappings":"AAgBA;;;;;;GAMG;AACH,MAAM,UAAU,iCAAiC,CAC/C,MAAyB,EACzB,mBAA2B;IAE3B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAC7B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,4BAA4B,CAAC,EAAE,GAAG,CAAC,CAAC,4BAA4B,CAAC,EAAE,CAChF,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,4BAA4B,CAAC,EAAE,CAAC;IACtD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CACxB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,4BAA4B,CAAC,EAAE,IAAI,mBAAmB;QACxD,mBAAmB,GAAG,CAAC,CAAC,4BAA4B,CAAC,WAAW,CACnE,CAAC;IACF,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,cAAc,CAAC;IACzC,IAAI,mBAAmB,GAAG,OAAO;QAAE,OAAO,KAAK,CAAC,cAAc,CAAC;IAC/D,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,MAAM,GAAG,CAAC,QAAQ,CAAC;IACvB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,CAAC,CAAC,4BAA4B,CAAC,EAAE,CAAC;QAC7C,IAAI,EAAE,IAAI,mBAAmB,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;YAC7C,IAAI,GAAG,CAAC,CAAC;YACT,MAAM,GAAG,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,cAAc,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kCAAkC,CAChD,MAAyB,EACzB,uBAA+B;IAE/B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC;IAC/E,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,cAAc,IAAI,uBAAuB;YAAE,IAAI,GAAG,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,CAAC,4BAA4B,CAAC,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"block-scroll-pickers.js","sourceRoot":"","sources":["../src/block-scroll-pickers.ts"],"names":[],"mappings":"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"}

package/dist/browse-contract.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stable contract between index / nav JSON / static HTML and browse URL + on-disk layout.
+ * Default resolution mirrors `{storageDir}/source/…` under `_site/browse/…/index.html`
+ * ({@link staticBrowseIndexRelPathFromPair}); implement {@link CommentrayStaticBrowsePathResolver}
+ * only if a repo needs a different mapping.
+ */
+/** Same shape as index entries and nav `documentedPairs` browse inputs. */
+export type CommentrayStaticBrowsePairPaths = {
+    readonly sourcePath: string;
+    readonly commentrayPath: string;
+};
+/** Injectable browse path strategy (tests or alternate storage layouts). */
+export interface CommentrayStaticBrowsePathResolver {
+    browseIndexRelPathFromPair(pair: CommentrayStaticBrowsePairPaths, storageDir: string): string;
+}
+//# sourceMappingURL=browse-contract.d.ts.map

package/dist/browse-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-contract.d.ts","sourceRoot":"","sources":["../src/browse-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,+BAA+B,GAAG;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,WAAW,kCAAkC;IACjD,0BAA0B,CAAC,IAAI,EAAE,+BAA+B,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/F"}