@celestia-island/hikari 0.55.160 → 0.55.161

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.160",
+  "version": "0.55.161",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkDiffViewer.test.tsx

@@ -238,3 +238,115 @@ describe("HkDiffViewer", () => {
     expect(root.querySelector(".hk-diff-viewer__hunk")).toBeNull();
   });
 });
+
+// ── The fold-aware scroll map (2026-10-12 user direction) ──────────────
+// The scrollbar must represent the WHOLE document while the viewer folds
+// unchanged regions away: the map total is fold-invariant, deleted rows
+// carry no document extent (they are not in the current file), and the
+// hunk heading is chrome. Mounting and folding drives the emission.
+describe("HkDiffViewer scroll map", () => {
+  const MAPPED_DIFF = [
+    // Counts MUST match the listed lines (3 old-side, 4 new-side; then
+    // 3 and 3) or the map total drifts off totalLines.
+    "@@ -1,3 +1,4 @@",
+    " ctx1",
+    " ctx2",
+    " ctx3",
+    "+add",
+    "@@ -50,3 +51,3 @@",
+    " ctxA",
+    "-old",
+    "+new",
+    " ctxB",
+  ].join("\n");
+
+  function mountViewer(extra: Record<string, unknown> = {}) {
+    const emitted: Array<Array<{ dom: number; map: number }>> = [];
+    const root = mount({
+      diff: MAPPED_DIFF,
+      totalLines: 100,
+      onScrollMap: (segs: Array<{ dom: number; map: number }>) => emitted.push(segs),
+      ...extra,
+    });
+    return { root, emitted };
+  }
+
+  it("emits a map whose total is the document, fold-invariant", async () => {
+    const { root, emitted } = mountViewer();
+    await nextTick();
+    expect(emitted.length).toBeGreaterThanOrEqual(1);
+    const total = (segs: Array<{ map: number }>) => segs.reduce((a, s) => a + s.map, 0);
+    expect(total(emitted[emitted.length - 1])).toBe(100);
+    // Collapse a hunk: the document total must not change (the scrollbar
+    // is a map of the WHOLE file whatever is folded).
+    const head = root.querySelector<HTMLButtonElement>(".hk-diff-viewer__hunk-head")!;
+    head.click();
+    await nextTick();
+    expect(total(emitted[emitted.length - 1])).toBe(100);
+    head.click(); // back
+    await nextTick();
+    expect(total(emitted[emitted.length - 1])).toBe(100);
+  });
+
+  it("keeps an empty-batched gap's rung at zero dom while the document keeps its lines", async () => {
+    // A host answering [] marks the gap done with NO rows fetched: the
+    // rung must not claim dom extent for lines that never rendered (R2's
+    // N2 caught +1957px of phantom dom) while the document side keeps
+    // the gap's full extent.
+    const { root, emitted } = mountViewer({
+      loadContext: async () => [],
+    });
+    await nextTick();
+    // MAPPED_DIFF has no leading gap (hunk 1 starts at line 1); the first
+    // divider is the 46-line middle gap (lines 5..50, anchor=start).
+    const divider = root.querySelector<HTMLButtonElement>(".hk-diff-viewer__gap")!;
+    divider.click();
+    await tick();
+    await nextTick();
+    const segs = emitted[emitted.length - 1];
+    // The gap is DONE via the empty batch: its document extent survives
+    // as a zero-dom rung — no phantom rows for lines that never rendered.
+    expect(segs).toContainEqual({ dom: 0, map: 46 });
+    expect(segs).not.toContainEqual({ dom: 46, map: 46 });
+    // …and the document total is still the whole file.
+    expect(segs.reduce((a, x) => a + x.map, 0)).toBe(100);
+  });
+
+  it("orders an expanded anchor=start gap's revealed rung BEFORE its divider rung", async () => {
+    // R2's N3: swapping the rung order moved the remaining-divider's
+    // document start by ~727px. The render puts revealed rows above the
+    // remaining divider for anchor=start, and the map must mirror it.
+    const lines: string[] = [];
+    for (let i = 0; i < 40; i += 1) lines.push(` fetched-${i}`);
+    const { root, emitted } = mountViewer({
+      loadContext: async () => lines,
+    });
+    await nextTick();
+    // The trailing gap (anchor=start, after the last hunk).
+    const dividers = [...root.querySelectorAll<HTMLButtonElement>(".hk-diff-viewer__gap")];
+    const trailing = dividers[dividers.length - 1];
+    trailing.click();
+    await tick();
+    await nextTick();
+    const segs = emitted[emitted.length - 1];
+    // Find the trailing gap's rungs: revealed (dom>0, map=40) directly
+    // before the remaining divider (map = 100 - docBefore - 40).
+    const idx = segs.findIndex((x, i) => x.map === 40 && segs[i + 1] && segs[i + 1].map > 0 && segs[i + 1].dom >= 0 && x.dom > 0 && i > segs.length - 6);
+    expect(idx).toBeGreaterThan(-1);
+    expect(segs[idx].dom).toBeGreaterThan(0);
+    expect(segs[idx + 1].map).toBeGreaterThan(0);
+  });
+
+  it("counts deleted rows as rendered-but-not-in-the-document", async () => {
+    const { emitted } = mountViewer();
+    await nextTick();
+    const segs = emitted[emitted.length - 1];
+    const total = segs.reduce((a, s) => a + s.map, 0);
+    const dom = segs.reduce((a, s) => a + s.dom, 0);
+    // 4 context/add rows in hunk 1 + 6 in hunk 2 (one of them a DELETED
+    // row: rendered, map 0) → dom exceeds the hunks' map contribution.
+    expect(dom).toBeGreaterThan(total - 100 + 0); // sanity: dom side exists
+    const hunkRows = segs.filter((s) => s.dom === 1 && s.map <= 1);
+    expect(hunkRows.length).toBeGreaterThan(4);
+  });
+});

package/src/components/HkDiffViewer.tsx

@@ -1,9 +1,10 @@
-import { computed, defineComponent, ref, watch } from "vue";
+import { computed, defineComponent, onMounted, ref, watch } from "vue";
 import { AlertTriangle, ChevronDown, ChevronRight, UnfoldVertical } from "lucide-vue-next";
 import HkSpinner from "./HkSpinner";
 import { useI18n } from "../i18n/context";
 import { highlight } from "../composables/useHighlight";
 import { computeGaps, parseUnifiedDiff, type DiffLine, type UnchangedGap } from "./diffParse";
+import type { OverlayScrollMapSegment } from "../composables/useOverlayScrollbar";
 import "./HkDiffViewer.scss";
 
 /**
@@ -57,15 +58,133 @@ export default defineComponent({
      */
     loadContext: { type: Function, default: null },
   },
-  setup(props) {
+  emits: {
+    /**
+     * The fold-aware scroll map (see `OverlayScrollMapSegment`): document
+     * units are NEW-SIDE file lines (deleted rows carry none — they do
+     * not exist in the current file), dom units are MEASURED PIXELS of
+     * the rows that render (row-count fallback where nothing lays out; a
+     * hunk heading is chrome and carries no document extent). The total
+     * is FOLD-INVARIANT — expanding a region moves its extent from the
+     * divider's rung onto real rows without changing the document — so
+     * the scrollbar stays a map of the WHOLE file whatever is folded.
+     * Bind it to a HkScrollContainer's `mapSegments`.
+     */
+    "scroll-map": null as OverlayScrollMapSegment[] | null,
+  },
+  setup(props, { emit }) {
+    const host = ref<HTMLElement | null>(null);
     const { t } = useI18n();
 
     const parsed = computed(() => parseUnifiedDiff(props.diff));
     const gaps = computed(() => computeGaps(parsed.value, props.totalLines ?? null));
     const collapsedHunks = ref<Set<number>>(new Set());
+
+    /**
+     * Measured pixel heights of the three row kinds, so the map's dom
+     * side can be honest in px instead of row counts — a hunk heading is
+     * ~1.7 lines tall and a divider ~1.35, and count-units drift the
+     * rung boundaries one to two rows off the real geometry (R1's pin
+     * plateau sat 17px past the divider). Zero = not measured yet
+     * (no-layout environments), and the map falls back to counts.
+     */
+    const rowKinds = ref({ line: 0, head: 0, gap: 0 });
+
+    function measureRowKinds() {
+      const root = host.value;
+      if (!root) return;
+      const line = root.querySelector<HTMLElement>(".hk-diff-viewer__line");
+      const head = root.querySelector<HTMLElement>(".hk-diff-viewer__hunk-head");
+      const gap = root.querySelector<HTMLElement>(".hk-diff-viewer__gap");
+      const next = {
+        line: line?.offsetHeight ?? 0,
+        head: head?.offsetHeight ?? 0,
+        gap: gap?.offsetHeight ?? 0,
+      };
+      // Write only on a real change: `rowKinds` feeds the scrollMap
+      // computed, and this runs from a watcher on that computed — an
+      // unconditional assign (a fresh object with equal values) would
+      // re-trigger it and recurse forever.
+      const prev = rowKinds.value;
+      if (
+        next.line !== prev.line || next.head !== prev.head || next.gap !== prev.gap
+      ) {
+        rowKinds.value = next;
+      }
+    }
+
+    /** The fold-aware scroll map, in RENDER order (mirrors the tree the
+     *  render function interleaves below, rung for rung). */
+    const scrollMap = computed<OverlayScrollMapSegment[]>(() => {
+      const segs: OverlayScrollMapSegment[] = [];
+      const mapOfGap = (gap: UnchangedGap) => {
+        const st = gapStates.value.get(gap.start);
+        const revealed = st?.revealed ?? 0;
+        const remaining = Math.max(gap.count - revealed, 0);
+        // Dom side counts the rows that actually RENDER (the same window
+        // walk the render does): a host answering an empty batch marks
+        // the gap done with zero rows shown, and the map must not claim
+        // dom extent for them — the DOCUMENT side keeps the lines.
+        const first =
+          gap.anchor === "end" ? gap.start + gap.count - revealed : gap.start;
+        let rendered = 0;
+        for (let no = first; no < first + revealed; no += 1) {
+          if (st?.lines.has(no)) rendered += 1;
+        }
+        const px = rowKinds.value.line > 0 ? rowKinds.value.line : 1;
+        const dividerPx =
+          rowKinds.value.gap > 0 ? rowKinds.value.gap : rowKinds.value.line > 0 ? rowKinds.value.line : 1;
+        const revealedRung = { dom: rendered * px, map: revealed };
+        const dividerRung = { dom: remaining > 0 ? dividerPx : 0, map: remaining };
+        // Mirror renderGap's order: anchor=end puts the divider ABOVE the
+        // revealed rows, anchor=start below them.
+        if (gap.anchor === "end") segs.push(dividerRung, revealedRung);
+        else segs.push(revealedRung, dividerRung);
+      };
+      const mapOfHunk = (idx: number) => {
+        const hunk = parsed.value.hunks[idx];
+        const linePx = rowKinds.value.line > 0 ? rowKinds.value.line : 1;
+        const headPx = rowKinds.value.head > 0 ? rowKinds.value.head : 1;
+        // The heading is chrome: it occupies a row and no document line.
+        segs.push({ dom: headPx, map: 0 });
+        const live = hunk.lines.filter((l) => l.kind !== "del").length;
+        if (collapsedHunks.value.has(idx)) {
+          // Body hidden: the whole new-side extent rides the heading rung.
+          segs.push({ dom: 0, map: live });
+        } else {
+          for (const line of hunk.lines) {
+            // Deleted rows render but exist only in the old file.
+            segs.push({ dom: linePx, map: line.kind === "del" ? 0 : 1 });
+          }
+        }
+      };
+      const gapsByHunk = new Map<number, UnchangedGap>();
+      for (const gap of gaps.value) gapsByHunk.set(gap.beforeHunk, gap);
+      for (let i = 0; i < parsed.value.hunks.length; i += 1) {
+        const gap = gapsByHunk.get(i);
+        if (gap) mapOfGap(gap);
+        mapOfHunk(i);
+      }
+      const trailing = gapsByHunk.get(parsed.value.hunks.length);
+      if (trailing) mapOfGap(trailing);
+      return segs;
+    });
+
     /** Gap states keyed by the gap's new-side start line (stable identity). */
     const gapStates = ref<Map<number, GapState>>(new Map());
 
+    // Emit on every fold change (and once up front) — the consumer feeds
+    // it straight into its HkScrollContainer's `mapSegments`. Declared
+    // AFTER gapStates: the immediate evaluation reads it, and a watch
+    // above the declaration would hit the temporal dead zone.
+    watch(scrollMap, (segs) => emit("scroll-map", segs), { immediate: true, flush: "post" });
+    // Re-measure after the DOM catches up (mount + every fold change:
+    // a first-ever divider/heading may have appeared).
+    onMounted(() => measureRowKinds());
+    watch([() => props.diff, () => props.totalLines, scrollMap], () => {
+      measureRowKinds();
+    }, { flush: "post" });
+
     // A fresh diff invalidates every cached context line and fold state.
     watch(
       () => [props.diff, props.totalLines],
@@ -267,7 +386,7 @@ export default defineComponent({
       const trailing = gapsByHunk.get(hunks.length);
       if (trailing) blocks.push(renderGap(trailing));
       return (
-        <div class="hk-diff-viewer">
+        <div class="hk-diff-viewer" ref={host}>
           <div class="hk-diff-viewer__body">{blocks}</div>
         </div>
       );

package/src/components/HkScrollContainer.tsx

@@ -12,7 +12,7 @@ import {
 import { useI18n } from "../i18n/context";
 import { laidOffsetWithin } from "../composables/layoutGeometry";
 import "./HkScrollContainer.scss";
-import { attachOverlayScrollbars, type OverlayScrollbarHandle, type OverlayScrollbarMarker } from "../composables/useOverlayScrollbar";
+import { attachOverlayScrollbars, type OverlayScrollbarHandle, type OverlayScrollMapSegment, type OverlayScrollbarMarker } from "../composables/useOverlayScrollbar";
 import { useApproachEnd, type ApproachEndHandle } from "../composables/useApproachEnd";
 import { provideScrollWindow } from "../composables/useScrollWindow";
 import { SCROLL_HOST_CLASS } from "./HkScrollPin";
@@ -55,6 +55,13 @@ export default defineComponent({
     /** Width the vertical track widens to while marks show, in px. Omitted
      *  = the library default (14). Only read when `markers` is non-empty. */
     markersWidth: { type: Number, default: undefined },
+    /**
+     * Asymmetric scroll map (vertical): the scrollbar represents the
+     * DOCUMENT while the viewport holds only rendered rows — collapsed
+     * regions sweep the thumb quickly and pin the content while dragging
+     * (see `OverlayScrollMapSegment`). Omitted = the dom-native bar.
+     */
+    mapSegments: { type: Array as PropType<OverlayScrollMapSegment[]>, default: undefined },
     autoFollow: { type: Boolean, default: false },
     overscanScreens: { type: Number, default: 1 },
     /** Inline-axis alignment of the content when it fits the viewport.
@@ -274,9 +281,16 @@ export default defineComponent({
       const vp = viewportRef.value;
       if (!vp) return;
       overlay?.detach();
-      overlay = attachOverlayScrollbars(vp, { axis: props.axis, markers: props.markers, markersWidth: props.markersWidth });
+      overlay = attachOverlayScrollbars(vp, { axis: props.axis, markers: props.markers, markersWidth: props.markersWidth, mapSegments: props.mapSegments });
     }
 
+    /** Swap the fold state's map without rebuilding the chrome: expanding
+     *  or collapsing a region only re-derives the thumb from the new
+     *  rungs. */
+    watch(() => props.mapSegments, (next) => {
+      overlay?.setMapSegments(next ?? []);
+    }, { deep: true, flush: "post" });
+
     /** Re-apply marks without rebuilding the chrome: a diff re-renders its
      *  marks on every tick, and detaching/reattaching would drop the
      *  scroll flash and re-run the positioning guard each time. */

package/src/composables/useOverlayScrollbar.scrollMap.test.ts

@@ -0,0 +1,187 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "./useOverlayScrollbar";
+
+/**
+ * The asymmetric scroll map (2026-10-12 user direction): a scrollbar that
+ * represents the DOCUMENT while the scroller holds only rendered rows —
+ * the diff viewer's collapsed unchanged regions. The three behaviours the
+ * user named, plus the guarantee that nobody who opts out notices:
+ *
+ *  1. scrolling the CONTENT sweeps the thumb quickly across a collapsed
+ *     region's map range;
+ *  2. DRAGGING the thumb through that range leaves the content pinned
+ *     until the range ends;
+ *  3. swapping the map (a region unfolded) re-derives the thumb from the
+ *     same document total — folding never moves the document;
+ *  4. without `mapSegments` the bar is dom-native, byte-for-byte the
+ *     math every consumer had before.
+ */
+
+/** Scroll geometry is stubbed (happy-dom lays nothing out): 900px of
+ *  rendered content in a 300px viewport. The map below models a document
+ *  of 2000 lines whose middle 1100 lines are collapsed to one divider:
+ *
+ *    rung 1: dom 300, map 600   (rendered rows, 1:1)
+ *    rung 2: dom   1, map 1100  (the collapsed divider)
+ *    rung 3: dom 599, map 300
+ */
+const GEOM = { scrollHeight: 900, clientHeight: 300, scrollTop: 0 };
+
+function stubGeometry(el: HTMLElement, geom: { scrollHeight?: number; clientHeight?: number } = {}) {
+  const desc: PropertyDescriptorMap = {
+    scrollHeight: { configurable: true, get: () => geom.scrollHeight ?? GEOM.scrollHeight },
+    clientHeight: { configurable: true, get: () => geom.clientHeight ?? GEOM.clientHeight },
+  };
+  let top = GEOM.scrollTop;
+  desc.scrollTop = { configurable: true, get: () => top, set: (v: number) => { top = v; } };
+  Object.defineProperties(el, desc);
+  return () => { GEOM.scrollTop = top; };
+}
+
+/** dom 300|map 600, dom 1|map 1100, dom 599|map 300: Σdom=900 (the real
+ *  scrollHeight), Σmap=2000 (the whole document). */
+const FOLDED: Array<{ dom: number; map: number }> = [
+  { dom: 300, map: 600 },
+  { dom: 1, map: 1100 },
+  { dom: 599, map: 300 },
+];
+
+const handles: OverlayScrollbarHandle[] = [];
+const cleanups: Array<() => void> = [];
+
+function mount(segments?: Array<{ dom: number; map: number }>) {
+  const host = document.createElement("div");
+  const viewport = document.createElement("div");
+  host.appendChild(viewport);
+  document.body.appendChild(host);
+  cleanups.push(() => host.remove());
+  const sync = stubGeometry(viewport);
+  const track = () => host.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])")!;
+  const thumb = () => host.querySelector<HTMLElement>(".hk-scrollbar-thumb")!;
+  const pct = (el: HTMLElement) => Number(/([\d.]+)px/.exec(el.style.transform ?? "")?.[1] ?? "0");
+  const height = (el: HTMLElement) => Number.parseFloat(el.style.height || "0");
+  const handle = attachOverlayScrollbars(viewport, {
+    axis: "vertical",
+    ...(segments ? { mapSegments: segments } : {}),
+  });
+  handles.push(handle);
+  handle.update();
+  return { viewport, handle, sync, track, thumb, pct, height, host };
+}
+
+afterEach(() => {
+  for (const h of handles.splice(0)) h.detach();
+  for (const c of cleanups.splice(0)) c();
+  document.body.innerHTML = "";
+});
+
+describe("overlay scrollbar scroll map", () => {
+  it("sizes and places the thumb in DOCUMENT space", () => {
+    const t = vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(200);
+    // track height 200; viewport covers map 300→600? — with the viewport
+    // at dom 0, map 0..~333 of 2000 (300px viewport over 900px content
+    // spans rung 1 entirely plus a sliver of the divider).
+    const m = mount(FOLDED);
+    // Σmap=2000, viewport map extent = fracToMap(300/900) = 600 + (0/1)*1100 = 600.
+    // thumb = 600/2000 * 200 = 60px; max progress 0 → offset 0.
+    expect(m.height(m.thumb())).toBeCloseTo(60, 1);
+    expect(m.pct(m.thumb())).toBeCloseTo(0, 1);
+    t.mockRestore();
+  });
+
+  it("sweeps the thumb FAST across a collapsed region while the content scrolls it (1)", () => {
+    const t = vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(200);
+    const m = mount(FOLDED);
+    // 1px of dom travel at the divider = 1100 map units; the whole
+    // divider is crossed by 1px. Content at dom 300 (divider top):
+    m.viewport.scrollTop = 299;
+    m.handle.update();
+    const before = m.pct(m.thumb());
+    m.viewport.scrollTop = 301; // past the divider entirely
+    m.handle.update();
+    const after = m.pct(m.thumb());
+    // The two pixels of content moved the thumb across the collapsed
+    // range: from rung 1's end (map 600/2000) to rung 3's start
+    // (map 1700/2000) — over half the track for 2px of scroll.
+    expect(before).toBeLessThan(60);
+    expect(after).toBeGreaterThan(120);
+    t.mockRestore();
+  });
+
+  it("PINS the content while the thumb drags through a collapsed range (2)", () => {
+    const t = vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(200);
+    const m = mount(FOLDED);
+    m.viewport.scrollTop = 300; // the divider
+    m.handle.update();
+    const thumbEl = m.thumb();
+    thumbEl.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, clientX: 0, clientY: 100 }));
+    // Drag well into the collapsed range (map 600..1700). The track is
+    // 200px, the thumb ~60px, so ~140px of travel ≈ the whole document.
+    const dragTo = (y: number) => {
+      document.dispatchEvent(new MouseEvent("mousemove", { clientX: 0, clientY: y }));
+    };
+    dragTo(120); // a little into the range — still inside the divider's dom extent
+    expect(m.viewport.scrollTop).toBeGreaterThanOrEqual(299);
+    expect(m.viewport.scrollTop).toBeLessThanOrEqual(301);
+    dragTo(160); // deep into the range — the DOM cannot present it
+    expect(m.viewport.scrollTop).toBeGreaterThanOrEqual(299);
+    expect(m.viewport.scrollTop).toBeLessThanOrEqual(301);
+    document.dispatchEvent(new MouseEvent("mouseup"));
+    t.mockRestore();
+  });
+
+  it("re-derives the thumb from the SAME document total when a region unfolds (3)", () => {
+    const t = vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(200);
+    const m = mount(FOLDED);
+    // Unfold: the divider's 1100 map lines become real dom rows (the
+    // consumer re-renders and reports taller content too).
+    const UNFOLDED = [
+      { dom: 300, map: 600 },
+      { dom: 1100, map: 1100 },
+      { dom: 599, map: 300 },
+    ];
+    vi.spyOn(m.viewport, "scrollHeight", "get").mockReturnValue(1999);
+    m.handle.setMapSegments(UNFOLDED);
+    m.handle.update();
+    // The thumb still describes the same document: its height is
+    // unchanged (viewport map extent / total), even though the dom grew.
+    expect(m.height(m.thumb())).toBeCloseTo(60, 1);
+    // And clearing the map returns the dom-native bar.
+    m.handle.setMapSegments([]);
+    m.handle.update();
+    expect(m.height(m.thumb())).toBeCloseTo((300 / 1999) * 200, 1);
+    t.mockRestore();
+  });
+
+  it("falls back to the dom-native bar when the map carries no document", () => {
+    const t = vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(200);
+    // A pure-deletion diff folds to zero document extent: Σmap = 0 must
+    // read as "no usable map", not as a zero-total map (whose thumb would
+    // be Infinity-tall and the dom-native fallback dead).
+    const m = mount([
+      { dom: 300, map: 0 },
+      { dom: 1, map: 0 },
+      { dom: 599, map: 0 },
+    ]);
+    expect(m.height(m.thumb())).toBeCloseTo((300 / 900) * 200, 1);
+    t.mockRestore();
+  });
+
+  it("without mapSegments the bar stays dom-native (4)", () => {
+    const t = vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(200);
+    const m = mount();
+    expect(m.height(m.thumb())).toBeCloseTo((300 / 900) * 200, 1);
+    // Drag math unchanged: full track travel = full scroll range.
+    m.viewport.scrollTop = 0;
+    m.handle.update();
+    m.thumb().dispatchEvent(new MouseEvent("mousedown", { bubbles: true, clientX: 0, clientY: 0 }));
+    document.dispatchEvent(new MouseEvent("mousemove", { clientX: 0, clientY: 70 }));
+    // Dom-native math, unchanged from before the map existed: thumb
+    // (300/900)*200 ≈ 66.7px, range 133.3px, so 70px of pointer =
+    // (70/133.3)·600 ≈ 315 — the exact value the pre-map engine produced.
+    expect(m.viewport.scrollTop).toBeCloseTo(315, 0);
+    document.dispatchEvent(new MouseEvent("mouseup"));
+    t.mockRestore();
+  });
+});

package/src/composables/useOverlayScrollbar.ts

@@ -78,6 +78,86 @@ const MARKER_MIN_PX = 2;
  *  default keeps the marks' two lanes readable at a glance. */
 const DEFAULT_MARKERS_WIDTH = 14;
 
+/**
+ * One rung of an ASYMMETRIC scroll map: `dom` units of rendered scroll
+ * space that carry `map` units of document space. The scrollbar then
+ * represents the DOCUMENT (the fully-expanded whole) while the scroller
+ * holds only what is rendered — collapsed regions ("40 unchanged
+ * lines…") occupy real map extent and (near-)zero dom extent, so:
+ *
+ *  - scrolling the CONTENT sweeps the thumb quickly across a collapsed
+ *    region's map range (a one-row divider stands for N document lines);
+ *  - DRAGGING the thumb through that range leaves the content pinned
+ *    (the divider is all the DOM there is to show) until the range ends;
+ *  - markers, which consumers express as fractions of the FULL document,
+ *    align with the thumb's map position — with a dom-native bar they
+ *    clump against a mostly-collapsed scroller instead.
+ *
+ * Both sides may use any consistent unit (rows, px, lines); the engine
+ * normalises Σdom onto the scroller's real extent, so approximations are
+ * fine as long as proportions are honest. `map: 0` rungs are chrome
+ * (a hunk heading) and `dom: 0` rungs are fully-collapsed content — both
+ * are honoured. Vertical axis only.
+ */
+export interface OverlayScrollMapSegment {
+  /** Rendered scroll-space extent of this rung (>0 unless collapsed). */
+  dom: number;
+  /** Document-space extent it stands for (0 = pure chrome). */
+  map: number;
+}
+
+/** Nothing has been mapped: run the dom-native math unchanged. */
+interface ScrollMap {
+  total: number;
+  fracToMap(frac: number): number;
+  mapToFrac(map: number): number;
+}
+
+/** Build the piecewise-linear tables; null unless the map is usable. */
+function buildScrollMap(
+  segments: OverlayScrollMapSegment[] | null | undefined,
+): ScrollMap | null {
+  if (!segments || segments.length === 0) return null;
+  let domTotal = 0;
+  let mapTotal = 0;
+  const domCum: number[] = [0];
+  const mapCum: number[] = [0];
+  for (const seg of segments) {
+    const dom = Number.isFinite(seg.dom) ? Math.max(seg.dom, 0) : 0;
+    const map = Number.isFinite(seg.map) ? Math.max(seg.map, 0) : 0;
+    domTotal += dom;
+    mapTotal += map;
+    domCum.push(domTotal);
+    mapCum.push(mapTotal);
+  }
+  if (domTotal <= 0 || mapTotal <= 0) return null;
+  return {
+    total: mapTotal,
+    fracToMap(frac: number): number {
+      const f = Math.min(Math.max(frac, 0), 1) * domTotal;
+      for (let i = 0; i < segments.length; i += 1) {
+        if (f <= domCum[i + 1] || i === segments.length - 1) {
+          const span = domCum[i + 1] - domCum[i];
+          const local = span > 0 ? (f - domCum[i]) / span : 1;
+          return mapCum[i] + local * (mapCum[i + 1] - mapCum[i]);
+        }
+      }
+      return mapTotal;
+    },
+    mapToFrac(map: number): number {
+      const m = Math.min(Math.max(map, 0), mapTotal);
+      for (let i = 0; i < segments.length; i += 1) {
+        if (m <= mapCum[i + 1] || i === segments.length - 1) {
+          const span = mapCum[i + 1] - mapCum[i];
+          const local = span > 0 ? (m - mapCum[i]) / span : 1;
+          return (domCum[i] + local * (domCum[i + 1] - domCum[i])) / domTotal;
+        }
+      }
+      return 1;
+    },
+  };
+}
+
 /** Clamp to [0, 1]; non-finite input is the caller's bug, but the rail
  *  must never render a mark at a meaningless position, so it becomes 0. */
 function clamp01(n: number): number {
@@ -114,11 +194,23 @@ export interface OverlayScrollbarOptions {
    *  pixels. Selective: consumers without marks keep the narrow track.
    *  Clamped to a sane range (the thumb and marks share the band). */
   markersWidth?: number;
+  /**
+   * Asymmetric scroll map for the vertical axis (see
+   * `OverlayScrollMapSegment`): the scrollbar represents the DOCUMENT
+   * while the scroller holds only the rendered rows. Omitted or empty =
+   * the dom-native bar every consumer had before. Update it any time the
+   * layout folds or unfolds — the thumb, drag, click and marker-scrub
+   * paths all re-derive from it.
+   */
+  mapSegments?: OverlayScrollMapSegment[];
 }
 
 export interface OverlayScrollbarHandle {
   /** Re-read the viewport's scroll geometry and reposition the thumbs. */
   update(): void;
+  /** Swap the asymmetric scroll map (empty clears it back to dom-native).
+   *  Call whenever the layout folds or unfolds. */
+  setMapSegments(segments: OverlayScrollMapSegment[]): void;
   /** Replace the rail's marks. Passing an empty list removes the rail
    *  again. No-op when the handle was attached against no host. */
   setMarkers(markers: OverlayScrollbarMarker[]): void;
@@ -192,7 +284,7 @@ export function attachOverlayScrollbars(
   const axis = opts.axis ?? "vertical";
   const parent = opts.host ?? viewport.parentElement;
   if (!parent) {
-    return { update() {}, setMarkers() {}, detach() {} };
+    return { update() {}, setMapSegments() {}, setMarkers() {}, detach() {} };
   }
 
   const wantV = axis !== "horizontal";
@@ -238,6 +330,8 @@ export function attachOverlayScrollbars(
   // that never pass markers keep byte-identical chrome.
   let track: HTMLElement | null = null;
   let markers: OverlayScrollbarMarker[] = [];
+  /** The asymmetric document map, when the consumer provides one. */
+  let scrollMap: ScrollMap | null = buildScrollMap(opts.mapSegments);
   let railDragging = false;
   /** Rail height the marks were last sized against — the pixel floor is a
    *  function of it, so a resize has to re-render them. */
@@ -256,6 +350,16 @@ export function attachOverlayScrollbars(
     if (rect.height <= 0) return;
     const ratio = clamp01((clientY - rect.top) / rect.height);
     const { scrollSize, clientSize } = axisMetrics(viewport, false);
+    if (scrollMap) {
+      // The band is the DOCUMENT: a scrub walks map space and collapses
+      // onto whatever dom position can present it.
+      const mapStart = scrollMap.fracToMap(viewport.scrollTop / scrollSize);
+      const mapEnd = scrollMap.fracToMap((viewport.scrollTop + clientSize) / scrollSize);
+      const viewportMap = Math.max(mapEnd - mapStart, 1e-6);
+      const mapPos = ratio * Math.max(scrollMap.total - viewportMap, 0);
+      viewport.scrollTop = scrollMap.mapToFrac(mapPos) * scrollSize;
+      return;
+    }
     viewport.scrollTop = ratio * Math.max(scrollSize - clientSize, 0);
   }
 
@@ -336,6 +440,13 @@ export function attachOverlayScrollbars(
   // `parent` to non-null, and only a closure created AFTER that narrowing
   // keeps it (a hoisted declaration may run at any time, so TS widens the
   // capture back to `HTMLElement | null`).
+  /** Swap in a new fold state; the thumb re-derives on the next update. */
+  const setMapSegments = (next: OverlayScrollMapSegment[]) => {
+    if (detached) return;
+    scrollMap = buildScrollMap(next);
+    update();
+  };
+
   const setMarkers = (next: OverlayScrollbarMarker[]) => {
     if (detached) return;
     markers = Array.isArray(next) ? next : [];
@@ -369,16 +480,30 @@ export function attachOverlayScrollbars(
     }
     s.track.style.display = "";
     const trackSize = horizontal ? s.track.clientWidth : s.track.clientHeight;
-    const ratio = clientSize / scrollSize;
+    // Asymmetric map (vertical): the thumb's SIZE and POSITION are
+    // document-space quantities — how much of the FILE the viewport shows
+    // and where in the FILE it sits — while every input stays the real
+    // DOM scroll the browser reports. A collapsed rung therefore shows as
+    // the thumb sweeping its map range with (almost) no dom travel.
+    let viewportMap = clientSize;
+    let maxScroll = scrollSize - clientSize;
+    let progressBase = scrollPos;
+    if (!horizontal && scrollMap) {
+      const mapStart = scrollMap.fracToMap(scrollPos / scrollSize);
+      const mapEnd = scrollMap.fracToMap((scrollPos + clientSize) / scrollSize);
+      viewportMap = Math.max(mapEnd - mapStart, 1e-6);
+      maxScroll = Math.max(scrollMap.total - viewportMap, 0);
+      progressBase = mapStart;
+    }
+    const ratio = viewportMap / (scrollMap && !horizontal ? scrollMap.total : scrollSize);
     const thumbSize = Math.max(ratio * trackSize, 20);
-    const maxScroll = scrollSize - clientSize;
     const maxTrack = trackSize - thumbSize;
     // A right-to-left scroller starts with `scrollLeft` at 0 (showing the
     // content's right end) and counts DOWN to -maxScroll, so its progress is
     // the magnitude — and the thumb rests at the track's right end and
     // travels left, mirrored against the left-to-right bar.
     const rtl = isRtlAxis(viewport, horizontal);
-    const progress = maxScroll > 0 ? Math.abs(scrollPos) / maxScroll : 0;
+    const progress = maxScroll > 0 ? Math.abs(progressBase) / maxScroll : 0;
     const offset = (rtl ? 1 - progress : progress) * maxTrack;
     if (horizontal) {
       s.thumb.style.width = `${thumbSize}px`;
@@ -443,12 +568,30 @@ export function attachOverlayScrollbars(
       // and falls back to the viewport box.
       const trackSize = horizontal ? s.track.clientWidth : s.track.clientHeight;
       const measured = trackSize > 0 ? trackSize : clientSize;
-      const thumbSize = Math.max((clientSize / scrollSize) * measured, 20);
+      const { scrollSize: sizeNow, clientSize: clientNow } = axisMetrics(viewport, horizontal);
+      if (horizontal || !scrollMap) {
+        // Dom-native drag (and every horizontal axis).
+        const thumbSize = Math.max((clientNow / sizeNow) * measured, 20);
+        const trackRange = measured - thumbSize;
+        if (trackRange <= 0) return;
+        const target = s.dragStartScroll + (delta / trackRange) * (sizeNow - clientNow);
+        if (horizontal) viewport.scrollLeft = target;
+        else viewport.scrollTop = target;
+        return;
+      }
+      // Mapped drag: the pointer walks the thumb through DOCUMENT space;
+      // `mapToFrac` collapses a rung the DOM cannot render into (almost)
+      // one scrollTop — dragging across a collapsed region leaves the
+      // content pinned at its divider until the range ends.
+      const f0 = s.dragStartScroll / sizeNow;
+      const mapStart = scrollMap.fracToMap(f0);
+      const mapEnd = scrollMap.fracToMap((s.dragStartScroll + clientNow) / sizeNow);
+      const viewportMap = Math.max(mapEnd - mapStart, 1e-6);
+      const thumbSize = Math.max((viewportMap / scrollMap.total) * measured, 20);
       const trackRange = measured - thumbSize;
       if (trackRange <= 0) return;
-      const target = s.dragStartScroll + (delta / trackRange) * (scrollSize - clientSize);
-      if (horizontal) viewport.scrollLeft = target;
-      else viewport.scrollTop = target;
+      const mapPos = mapStart + (delta / trackRange) * (scrollMap.total - viewportMap);
+      viewport.scrollTop = scrollMap.mapToFrac(mapPos) * sizeNow;
     };
     const onUp = () => {
       s.dragging = false;
@@ -480,6 +623,16 @@ export function attachOverlayScrollbars(
         : (e.clientY - rect.top) / rect.height;
       const { scrollSize, clientSize } = axisMetrics(viewport, horizontal);
       const max = scrollSize - clientSize;
+      if (!horizontal && scrollMap) {
+        // Clicking the band jumps the DOCUMENT to the clicked rung — the
+        // same space the thumb lives in.
+        const mapStart = scrollMap.fracToMap(viewport.scrollTop / scrollSize);
+        const mapEnd = scrollMap.fracToMap((viewport.scrollTop + clientSize) / scrollSize);
+        const viewportMap = Math.max(mapEnd - mapStart, 1e-6);
+        const mapPos = ratio * Math.max(scrollMap.total - viewportMap, 0);
+        viewport.scrollTop = scrollMap.mapToFrac(mapPos) * scrollSize;
+        return;
+      }
       if (horizontal) {
         // RTL: the track's left end is the content's END, and `scrollLeft`
         // runs 0 → −max (see the thumb mirroring in `update`), so a click at
@@ -510,6 +663,7 @@ export function attachOverlayScrollbars(
 
   return {
     update,
+    setMapSegments,
     setMarkers,
     detach() {
       if (detached) return;

package/src/index.ts

@@ -422,7 +422,7 @@ export { useApproachEnd } from "./composables/useApproachEnd";
 export type { ApproachEndOptions, ApproachEndHandle } from "./composables/useApproachEnd";
 // The change-mark rail's public vocabulary: HkScrollContainer's `markers`
 // prop is typed with it, so consumers can name what they pass.
-export type { OverlayScrollbarMarker } from "./composables/useOverlayScrollbar";
+export type { OverlayScrollMapSegment, OverlayScrollbarMarker } from "./composables/useOverlayScrollbar";
 export { useDeferredTransition } from "./composables/useDeferredTransition";
 export { useSurfaceTransition } from "./composables/useSurfaceTransition";
 export { useSizeMorph } from "./composables/useSizeMorph";