@celestia-island/hikari 0.55.157 → 0.55.159

package/package.json

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

package/src/components/HkInfiniteTail.tsx

@@ -25,11 +25,14 @@ import "./HkInfiniteTail.scss";
  * - `"idle"` — more exists, nothing in flight. With `auto` (default)
  *   the invisible sentinel watches the viewport and emits `loadMore`
  *   as it approaches; with `auto={false}` the explicit load-more
- *   button (HkLoadMore) renders instead. NOTE: with `auto`, a tail
- *   page failure retries in place every time the sentinel re-enters
- *   view (the machine's error guard paces it to one attempt per
- *   emission, no backoff) — hosts that want backoff map the error
- *   state away from `"idle"` themselves.
+ *   button (HkLoadMore) renders instead. NOTE: a failed page
+ *   terminalizes the machine's walk — the tail keeps emitting
+ *   `loadMore` as the sentinel re-enters view, but each emission is a
+ *   no-op until the host calls `reload()` (the retry verb; the
+ *   delivered rows stay on screen under the host's stale banner).
+ *   Auto-retrying from the tail is deliberately not supported: the
+ *   sentinel would re-fire on a fixed geometry with no backoff, one
+ *   RPC per round trip, which locks a shared rate budget.
  *
  * The sentinel observes the BROWSER viewport (IntersectionObserver,
  * `rootMargin` lookahead), so it works inside any nested scroll

package/src/components/HkScrollContainer.test.ts

@@ -404,7 +404,7 @@ describe("HkScrollContainer back-to-top signal", () => {
 });
 
 describe("HkScrollContainer change-mark rail", () => {
-  it("renders the marks prop, and re-applies new marks without rebuilding the chrome", async () => {
+  it("widens the track, renders the marks prop, and re-applies them without rebuilding", async () => {
     const markers = ref<OverlayScrollbarMarker[]>([{ start: 0.1, end: 0.2, kind: "added" }]);
     const container = document.createElement("div");
     document.body.appendChild(container);
@@ -419,9 +419,11 @@ describe("HkScrollContainer change-mark rail", () => {
     mounts.push(app);
     app.mount(container);
 
-    const rail = () => container.querySelector<HTMLElement>(".hk-scrollbar-markers");
+    // The marks live INSIDE the vertical track: the rail IS the track.
+    const rail = () => container.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])");
     const firstRail = rail();
-    expect(firstRail, "the rail exists once marks arrive").not.toBeNull();
+    expect(firstRail, "the track exists once marks arrive").not.toBeNull();
+    expect(firstRail!.classList.contains("has-markers"), "the track widens for marks").toBe(true);
     expect(firstRail!.querySelectorAll(".hk-scrollbar-marker").length).toBe(1);
 
     markers.value = [
@@ -438,8 +440,10 @@ describe("HkScrollContainer change-mark rail", () => {
     app.unmount();
   });
 
-  it("keeps the rail out of the DOM when no marks are passed", () => {
+  it("keeps the narrow track and no marks when none are passed", () => {
     const m = mountScroller({});
-    expect(m.container.querySelector(".hk-scrollbar-markers")).toBeNull();
+    const track = m.container.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])");
+    expect(track?.classList.contains("has-markers") ?? false, "no widening").toBe(false);
+    expect(track?.querySelectorAll(".hk-scrollbar-marker").length ?? 0).toBe(0);
   });
 });

package/src/components/HkScrollContainer.tsx

@@ -52,6 +52,9 @@ export default defineComponent({
      *  it out renders exactly the chrome this container had before the
      *  rail existed. */
     markers: { type: Array as PropType<OverlayScrollbarMarker[]>, default: () => [] },
+    /** 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 },
     autoFollow: { type: Boolean, default: false },
     overscanScreens: { type: Number, default: 1 },
     /** Inline-axis alignment of the content when it fits the viewport.
@@ -271,7 +274,7 @@ export default defineComponent({
       const vp = viewportRef.value;
       if (!vp) return;
       overlay?.detach();
-      overlay = attachOverlayScrollbars(vp, { axis: props.axis, markers: props.markers });
+      overlay = attachOverlayScrollbars(vp, { axis: props.axis, markers: props.markers, markersWidth: props.markersWidth });
     }
 
     /** Re-apply marks without rebuilding the chrome: a diff re-renders its

package/src/components/overlayScrollbarChrome.contract.test.ts

@@ -71,43 +71,58 @@ describe("overlay scrollbar chrome contract", () => {
     expect(chrome).toMatch(/&?\.is-scrolling,\s*&?\.is-hovering\s*\{[^}]*pointer-events:\s*auto/);
   });
 
-  it("keeps the change-mark rail clear of the track and out of the click path", () => {
-    // The rail is a SECOND overlay in the same corner. Two facts have to
-    // survive any future restyle:
+  it("widens the track into the ruler and keeps the click rules straight", () => {
+    // The marks live INSIDE the track, which widens only when it carries
+    // them (`.has-markers`) — VS Code's overview ruler is the scrollbar's
+    // own strip widened, not a second strip. Three facts must survive any
+    // future restyle:
     //
-    //  1. It must not overlap the track (right 2px + width 6px), or marks
-    //     would draw across the thumb;
-    //  2. it must not take pointer input — it spans the WHOLE host, docks
-    //     included, so a live hot zone there eats presses meant for
-    //     right-aligned dock controls. Only the marks accept input, and
-    //     that exemption is exactly why the rail itself must stay `none`.
-    // The vertical geometry lives in the track's own nested
-    // `&:not([data-axis="horizontal"])` block, not a top-level selector.
-    const track = /&:not\(\[data-axis="horizontal"\]\)\s*\{[^}]*\}/.exec(chrome)?.[0] ?? "";
-    expect(track, "positive control: the vertical track rule was found").not.toBe("");
-    const trackRight = Number(/right:\s*(\d+)px/.exec(track)?.[1]);
-    const trackWidth = Number(/width:\s*(\d+)px/.exec(track)?.[1]);
+    //  1. The widened ground is FAINT and theme-adaptive (a translucent
+    //     mid-grey: grey over a light page, slightly lighter over a dark
+    //     one), with the 2px rounding the band promised;
+    //  2. it stays pointer-transparent AT REST — the widened band spans
+    //     the whole host, docks included, and a live hot zone there would
+    //     eat presses meant for right-aligned dock controls;
+    //  3. the MARKS are the hit area and hug the band's edges: removed
+    //     content at the start, added at the end (VS Code's two lanes),
+    //     so one vertical position can carry both.
+    expect(chrome, "no second strip — the separate rail is gone").not.toContain(".hk-scrollbar-markers");
 
-    const rail = /\.hk-scrollbar-markers\s*\{[^}]*\}/.exec(chrome)?.[0] ?? "";
-    expect(rail, "positive control: the rail rule was found").not.toBe("");
-    const railRight = Number(/right:\s*(\d+)px/.exec(rail)?.[1]);
-    const railWidth = Number(/width:\s*(\d+)px/.exec(rail)?.[1]);
-
-    expect(
-      railRight,
-      "the rail starts outboard of the track's inner edge",
-    ).toBeGreaterThanOrEqual(trackRight + trackWidth);
-    expect(railRight + railWidth, "and stays inside the host").toBeLessThanOrEqual(24);
+    const widened = /&\.has-markers:not\(\[data-axis="horizontal"\]\)\s*\{[^}]*\}/.exec(chrome)?.[0] ?? "";
+    expect(widened, "positive control: the widened-band rule was found").not.toBe("");
+    expect(widened, "the ground is faint (translucent grey)").toMatch(
+      /color-mix\(in srgb,\s*var\(--hi-color-muted,\s*rgb\(118 122 128\)\)\s*\d+%,\s*transparent\)/,
+    );
+    expect(widened, "the band keeps its 2px rounding").toMatch(/border-radius:\s*2px/);
+    expect(widened, "and a parameterised width the engine overrides").toMatch(/width:\s*\d+px/);
+    // The base track's own pointer contract (pinned above) is untouched;
+    // the widened rule must not sneak a `pointer-events: auto` in.
+    expect(widened).not.toMatch(/pointer-events:\s*auto/);
 
-    expect(rail, "the rail itself takes no pointer input").toMatch(/pointer-events:\s*none/);
-    const marker = /\.hk-scrollbar-marker\s*\{[^}]*\}/.exec(chrome)?.[0] ?? "";
-    expect(marker, "positive control: the mark rule was found").not.toBe("");
-    expect(marker, "the marks are the hit area").toMatch(/pointer-events:\s*auto/);
-    // The hover ring must be drawn INSIDE the mark: the rail clips its
+    // The mark's whole rule (it is the file's last block, and its nested
+    // lanes/hover/kind blocks make a single-block regex fragile).
+    const markerBlock = chrome.slice(chrome.indexOf(".hk-scrollbar-marker {"));
+    expect(markerBlock, "positive control: the mark rule was found").not.toBe("");
+    expect(markerBlock, "the marks are the hit area").toMatch(/pointer-events:\s*auto/);
+    expect(markerBlock, "the band's 2px rounding reaches the marks").toMatch(/border-radius:\s*2px/);
+    // The two lanes, at the band's edges (the rules nest inside the mark
+    // selector, so they are written `&[data-side=…]`).
+    expect(markerBlock).toMatch(/&\[data-side="start"\]\s*\{[^}]*left:\s*0/);
+    expect(markerBlock).toMatch(/&\[data-side="end"\]\s*\{[^}]*right:\s*0/);
+    // …and their WIDTH: a restyle that silently stretched a lane across
+    // the whole band would collapse the two-lane reading into one strip
+    // (caught only by the vendored-sync byte comparison before this pin).
+    expect(markerBlock, "the start lane hugs a third of the band").toMatch(
+      /&\[data-side="start"\]\s*\{[^}]*width:\s*34%/,
+    );
+    expect(markerBlock, "and the end lane the other third").toMatch(
+      /&\[data-side="end"\]\s*\{[^}]*width:\s*34%/,
+    );
+    // The hover ring must be drawn INSIDE the mark: the track clips its
     // children, and a plain outline loses both side strokes to that clip,
     // leaving a two-line "ring" that reads as a stray rule rather than a
     // hover cue. Nothing else would notice that regression.
-    expect(marker, "the hover ring is drawn inside the mark").toMatch(
+    expect(markerBlock, "the hover ring is drawn inside the mark").toMatch(
       /outline-offset:\s*-1px/,
     );
   });

package/src/composables/useInfinitePages.test.ts

@@ -114,7 +114,7 @@ describe("useInfinitePages", () => {
     expect(handle.exhausted.value).toBe(true);
   });
 
-  it("a failed later page keeps the delivered rows and retries in place", async () => {
+  it("a failed later page keeps the delivered rows and terminalizes the walk", async () => {
     const fetcher = vi
       .fn(async (): Promise<HkPageResultLike<Row>> => page([], 0, false))
       .mockImplementationOnce(async () => page([{ id: "a" }], 3, true))
@@ -127,10 +127,36 @@ describe("useInfinitePages", () => {
     await handle.loadMore();
     expect(handle.error.value).toBe("boom");
     expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
-    // The tail failure is retriable without a full reload.
+    // A tail failure does NOT auto-retry: the sentinel's idle re-check
+    // would re-fire loadMore on a fixed geometry with no backoff — one
+    // RPC per round trip forever, locking any shared rate budget. The
+    // failure is terminal until `reload`.
     await handle.loadMore();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
+    // `reload` is the retry verb: it clears the failure and refetches
+    // from page one.
+    await handle.reload();
     expect(handle.error.value).toBeNull();
-    expect(handle.items.value.map((r) => r.id)).toEqual(["a", "b", "c"]);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["b", "c"]);
+  });
+
+  it("a tail failure cannot storm: repeated loadMore stays a no-op", async () => {
+    const fetcher = vi
+      .fn(async (): Promise<HkPageResultLike<Row>> => page([], 0, false))
+      .mockImplementationOnce(async () => page([{ id: "a" }], 5, true))
+      .mockImplementation(async () => {
+        throw new Error("tail down");
+      });
+    const { handle } = withHandle(() => useInfinitePages<Row>({ fetcher, pageSize: 1 }));
+    await vi.waitFor(() => expect(handle.loading.value).toBe(false));
+    await handle.loadMore();
+    expect(handle.error.value).toBe("tail down");
+    // Ten idle-entry re-checks (the tail sentinel's emission pattern)
+    // spend ZERO further RPCs.
+    for (let i = 0; i < 10; i++) await handle.loadMore();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(handle.items.value.map((r) => r.id)).toEqual(["a"]);
   });
 
   it("a param change triggers a debounced reload from page one", async () => {

package/src/composables/useInfinitePages.ts

@@ -83,9 +83,9 @@ export interface InfinitePagesHandle<T> {
   error: Ref<string | null>;
   /** One-based index of the next page to fetch. */
   nextPage: Ref<number>;
-  /** Fetch the next page (guarded: no-op while busy or exhausted).
-   * A TAIL-page failure stays retriable in place — the next `loadMore`
-   * refetches the same page; only a page-one failure needs `reload`. */
+  /** Fetch the next page (guarded: no-op while busy, exhausted, or
+   * after ANY failure — `reload` is the retry verb for both the
+   * first-page and the tail-page error dialects). */
   loadMore: () => Promise<void>;
   /** Reset to page one and fetch (also the error-clearing retry). */
   reload: () => Promise<void>;
@@ -101,7 +101,11 @@ export interface InfinitePagesHandle<T> {
  *
  * Error dialect: a failed page keeps everything already delivered (the
  * consumer renders it as a stale banner — one failed fetch must never
- * hide rows the user was reading); `reload` is the retry verb.
+ * hide rows the user was reading) and terminalizes the walk; `reload`
+ * is the retry verb for every failure. Auto-retrying a tail failure is
+ * deliberately NOT done: the tail's sentinel would re-fire on a fixed
+ * geometry with no backoff, turning one flaky page into an RPC storm
+ * that locks a shared rate budget.
  */
 export function useInfinitePages<T, P extends Record<string, unknown> = Record<string, unknown>>(
   options: InfinitePagesOptions<T, P>,
@@ -123,9 +127,6 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
   let seq = 0;
   let reloadTimer: ReturnType<typeof setTimeout> | null = null;
   let disposed = false;
-  /** Which phase the current `error` came from — a tail-page failure
-   * retried by `loadMore` in place, a first-page failure by `reload`. */
-  let errorPhase: "load" | "more" = "load";
 
   function normalize(result: HkPageResultLike<T>): HkPageResult<T> {
     const loose = result as {
@@ -196,14 +197,20 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
   }
 
   async function loadMore(): Promise<void> {
-    // A failure from a LATER page is retriable in place (the delivered
-    // rows stay, the cursor stays); a failure from page one needs a
-    // full reload (the retry verb for the hard-error state).
+    // ANY failure terminalizes the walk until `reload()` — including a
+    // tail-page failure. The in-place retry this used to allow read
+    // fine in isolation but stormed in the field: a failed tail leaves
+    // the state machine "idle", the tail's sentinel stays in view, and
+    // its idle-entry re-check fires loadMore again with no geometry
+    // change — one RPC per round trip, no backoff, forever. On a shared
+    // per-user rate budget that loop locks the bucket and denies every
+    // OTHER paged page, so the retry verb is `reload()` (the delivered
+    // rows stay on screen under the stale banner; the header refresh is
+    // the user's affordance).
     if (loading.value || loadingMore.value || exhausted.value) return;
-    if (error.value && errorPhase !== "more") return;
+    if (error.value) return;
     if (nextPage.value > 1 && items.value.length === 0) return;
     loadingMore.value = true;
-    errorPhase = "more";
     const mine = ++seq;
     try {
       await fetchPage(nextPage.value, mine);
@@ -225,7 +232,6 @@ export function useInfinitePages<T, P extends Record<string, unknown> = Record<s
       reloadTimer = null;
     }
     loading.value = true;
-    errorPhase = "load";
     error.value = null;
     if (!options.keepDuringReload) {
       // Invalidate the cursor BEFORE the fetch so a straggler from the

package/src/composables/useOverlayScrollbar.test.ts

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { attachOverlayScrollbars, type OverlayScrollbarHandle, type OverlayScrollbarOptions } from "./useOverlayScrollbar";
@@ -23,10 +26,11 @@ function mountViewport(
   return { container, wrapper, viewport, handle };
 }
 
-/** A scrollable vertical viewport with a deterministic 100px rail box:
- *  happy-dom performs no layout, so both the geometry and the rail's
- *  bounding box are stubbed. `height` of the rail is what maps a mark's
- *  fraction to a pixel position. */
+/** A scrollable vertical viewport with a deterministic band box: happy-dom
+ *  performs no layout, so both the geometry and the track's bounding box
+ *  are stubbed. `height` of the band is what maps a mark's fraction to a
+ *  pixel position. The marks live INSIDE the vertical track (the widened
+ *  scrollbar is the ruler), so "the rail" below IS the track. */
 function mountRailed(railHeight = 100) {
   const mounted = mountViewport("vertical");
   stubGeometry(mounted.viewport, {
@@ -37,12 +41,13 @@ function mountRailed(railHeight = 100) {
   return {
     ...mounted,
     rail: () => {
-      const el = mounted.wrapper.querySelector<HTMLElement>(".hk-scrollbar-markers");
+      const el = mounted.wrapper.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])");
       if (el) {
         vi.spyOn(el, "getBoundingClientRect").mockReturnValue({
-          top: 0, left: 0, width: 8, height: railHeight,
-          bottom: railHeight, right: 8, x: 0, y: 0, toJSON: () => ({}),
+          top: 0, left: 0, width: 14, height: railHeight,
+          bottom: railHeight, right: 14, x: 0, y: 0, toJSON: () => ({}),
         } as DOMRect);
+        Object.defineProperty(el, "clientHeight", { configurable: true, get: () => railHeight });
       }
       return el;
     },
@@ -354,9 +359,11 @@ describe("attachOverlayScrollbars", () => {
 });
 
 describe("change-mark rail", () => {
-  it("renders no rail at all when the consumer passes no markers", () => {
+  it("keeps the narrow track, unmarked, when the consumer passes no markers", () => {
     const { wrapper } = mountViewport("vertical");
-    expect(wrapper.querySelector(".hk-scrollbar-markers")).toBeNull();
+    const track = wrapper.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])");
+    expect(track?.classList.contains("has-markers") ?? false, "no widening").toBe(false);
+    expect(track?.querySelectorAll(".hk-scrollbar-marker").length ?? 0).toBe(0);
   });
 
   it("creates the rail and one mark per entry, tagged by kind", () => {
@@ -439,6 +446,79 @@ describe("change-mark rail", () => {
     expect(mark.style.height).toBe("60%");
   });
 
+  it("honours the consumer's markersWidth, clamped to a sane band", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.1, end: 0.2, kind: "added" }]);
+    const width = () => m.rail()!.style.width;
+    // The default band, then the consumer's own, then the clamps.
+    expect(width()).toBe("14px");
+    m.handle.detach();
+    handles.splice(handles.indexOf(m.handle), 1);
+
+    const custom = mountViewport("vertical", { markers: [{ start: 0.1, end: 0.2, kind: "added" }], markersWidth: 22 });
+    custom.handle.update();
+    expect(
+      custom.wrapper.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])")!.style.width,
+    ).toBe("22px");
+    custom.handle.detach();
+    handles.splice(handles.indexOf(custom.handle), 1);
+
+    const clamped = mountViewport("vertical", { markers: [{ start: 0.1, end: 0.2, kind: "added" }], markersWidth: 999 });
+    clamped.handle.update();
+    expect(
+      clamped.wrapper.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])")!.style.width,
+      "above the 40px ceiling it clamps").toBe("40px");
+  });
+
+  it("mirrors side onto data-side so the lanes can be styled", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([
+      { start: 0.1, end: 0.2, kind: "deleted", side: "start" },
+      { start: 0.1, end: 0.2, kind: "added", side: "end" },
+      { start: 0.5, end: 0.6, kind: "modified" },
+    ]);
+    const marks = m.rail()!.querySelectorAll<HTMLElement>(".hk-scrollbar-marker");
+    expect(marks[0].getAttribute("data-side")).toBe("start");
+    expect(marks[1].getAttribute("data-side")).toBe("end");
+    expect(marks[2].getAttribute("data-side"), "no side = full band").toBeNull();
+  });
+
+  it("does not scrub on a press on the band's empty ground", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.3, end: 0.35, kind: "added" }]);
+    stubGeometry(m.viewport, {
+      scrollHeight: 1000, clientHeight: 100, scrollTop: 0,
+      scrollWidth: 100, clientWidth: 100, scrollLeft: 0,
+    });
+    // A press on the TRACK (not on a mark) keeps the track's own
+    // click-to-page behaviour: no scrub, no drag state.
+    const track = m.rail()!;
+    track.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, clientY: 0 }));
+    expect(track.classList.contains("is-dragging"), "no drag state").toBe(false);
+    document.dispatchEvent(new MouseEvent("mousemove", { clientY: 100 }));
+    expect(m.viewport.scrollTop, "no scrub followed the pointer").toBe(0);
+    document.dispatchEvent(new MouseEvent("mouseup"));
+  });
+
+  it("keeps the band and its marks visible at rest (an overview ruler is a glance)", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.1, end: 0.2, kind: "added" }]);
+    // The track is pointer-transparent at rest, but the widened band and
+    // its marks must still SHOW: hiding them made the ruler a hover-only
+    // affordance, which is exactly what an overview ruler is not.
+    // happy-dom does not apply stylesheets to computed styles, so this
+    // pins the rule in the shipped chrome (the vendored copy) instead.
+    const chrome = readFileSync(
+      resolve(dirname(fileURLToPath(import.meta.url)), "../styles/theme/scrollbar.scss"),
+      "utf-8",
+    );
+    const widened = /&\.has-markers:not\(\[data-axis="horizontal"\]\)\s*\{[^}]*\}/.exec(chrome)?.[0] ?? "";
+    expect(widened, "positive control: the widened rule was found").not.toBe("");
+    expect(widened, "the band is visible at rest").toMatch(/opacity:\s*1/);
+    // …and the thumb rides above it.
+    expect(chrome).toMatch(/\.hk-scrollbar-thumb\s*\{[^}]*z-index:\s*2/);
+  });
+
   it("positions marks against the content, so scrolling does not move them", () => {
     const m = mountRailed();
     m.handle.setMarkers([{ start: 0.25, end: 0.3, kind: "added" }]);
@@ -458,7 +538,9 @@ describe("change-mark rail", () => {
     m.handle.setMarkers([{ start: 0.1, end: 0.2, kind: "added" }]);
     expect(m.rail()).not.toBeNull();
     m.handle.setMarkers([]);
-    expect(m.wrapper.querySelector(".hk-scrollbar-markers")).toBeNull();
+    const track = m.wrapper.querySelector<HTMLElement>(".hk-scrollbar-track:not([data-axis='horizontal'])");
+    expect(track?.classList.contains("has-markers") ?? false, "the widening is undone").toBe(false);
+    expect(track?.querySelectorAll(".hk-scrollbar-marker").length ?? 0).toBe(0);
   });
 
   it("hides the rail while the content fits, and shows it again when it scrolls", () => {
@@ -486,7 +568,9 @@ describe("change-mark rail", () => {
     });
     m.handle.update();
     m.handle.setMarkers([{ start: 0.1, end: 0.2, kind: "added" }]);
-    expect(m.wrapper.querySelector(".hk-scrollbar-markers")).toBeNull();
+    const hTrack = m.wrapper.querySelector<HTMLElement>('.hk-scrollbar-track[data-axis="horizontal"]');
+    expect(hTrack?.classList.contains("has-markers") ?? false, "no band on a horizontal track").toBe(false);
+    expect(hTrack?.querySelectorAll(".hk-scrollbar-marker").length ?? 0).toBe(0);
   });
 
   it("ignores non-finite mark bounds instead of parking them at NaN%", () => {
@@ -556,7 +640,7 @@ describe("change-mark rail", () => {
     mark.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, clientY: 0 }));
     m.handle.detach();
     handles.splice(handles.indexOf(m.handle), 1);
-    expect(m.wrapper.querySelector(".hk-scrollbar-markers")).toBeNull();
+    expect(m.wrapper.querySelectorAll(".hk-scrollbar-marker").length).toBe(0);
     m.viewport.scrollTop = 0;
     document.dispatchEvent(new MouseEvent("mousemove", { clientY: 100 }));
     expect(m.viewport.scrollTop, "detach dropped the drag listener").toBe(0);
@@ -568,6 +652,6 @@ describe("change-mark rail", () => {
     m.handle.detach();
     handles.splice(handles.indexOf(m.handle), 1);
     expect(() => m.handle.setMarkers([{ start: 0, end: 1, kind: "added" }])).not.toThrow();
-    expect(m.wrapper.querySelector(".hk-scrollbar-markers")).toBeNull();
+    expect(m.wrapper.querySelectorAll(".hk-scrollbar-marker").length).toBe(0);
   });
 });

package/src/composables/useOverlayScrollbar.ts

@@ -51,6 +51,13 @@ export interface OverlayScrollbarMarker {
   /** Semantic tag mirrored onto `data-kind`, so the consumer's theme owns
    *  the palette (this engine ships no colours of its own). */
   kind?: string;
+  /**
+   * Which third of the band the mark hugs — VS Code's diff overview ruler
+   * draws REMOVED content against the band's start edge and ADDED content
+   * against its end edge, so one vertical position can carry both. Omitted
+   * = the mark spans the full band width.
+   */
+  side?: "start" | "end";
 }
 
 /** Shortest a mark may render, as a fraction of the rail. A one-line edit
@@ -66,6 +73,11 @@ const MARKER_MIN_FRACTION = 0.005;
  *  from the SAME number, which CSS cannot express. */
 const MARKER_MIN_PX = 2;
 
+/** Width the vertical track widens to when marks arrive, unless the
+ *  consumer passes its own. VS Code's scrollbar strip is ~14px; the
+ *  default keeps the marks' two lanes readable at a glance. */
+const DEFAULT_MARKERS_WIDTH = 14;
+
 /** 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 {
@@ -98,6 +110,10 @@ export interface OverlayScrollbarOptions {
    *  "position in the document". Omitted or empty creates no rail at all,
    *  so consumers that never pass markers keep the exact chrome they had. */
   markers?: OverlayScrollbarMarker[];
+  /** Width the vertical track widens to while marks are showing, in CSS
+   *  pixels. Selective: consumers without marks keep the narrow track.
+   *  Clamped to a sane range (the thumb and marks share the band). */
+  markersWidth?: number;
 }
 
 export interface OverlayScrollbarHandle {
@@ -216,22 +232,27 @@ export function attachOverlayScrollbars(
   let detached = false;
 
   // ── Change-mark rail (vertical only) ─────────────────────────────────
-  // Created lazily on the first non-empty marker list: consumers that
-  // never pass markers keep byte-identical chrome, and the rail's own
-  // listeners exist only while the rail does.
-  let rail: HTMLElement | null = null;
+  // The marks live INSIDE the vertical track, which widens to
+  // `markersWidth` for as long as marks are showing (VS Code's overview
+  // ruler is a widening of the same strip, not a second one). Consumers
+  // that never pass markers keep byte-identical chrome.
+  let track: HTMLElement | null = null;
   let markers: OverlayScrollbarMarker[] = [];
   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. */
   let renderedRailHeight = 0;
 
+  /** The vertical track, found once and reused. */
+  const verticalTrack = (): HTMLElement | null =>
+    states.find((s) => !s.horizontal)?.track ?? null;
+
   /** Scroll so the rail position under `clientY` lands in the viewport —
    *  the same fraction → scrollTop mapping the track's own click uses, so
    *  a mark and the track at the same height agree. */
   function railScrollTo(clientY: number) {
-    if (!rail) return;
-    const rect = rail.getBoundingClientRect();
+    if (!track) return;
+    const rect = track.getBoundingClientRect();
     if (rect.height <= 0) return;
     const ratio = clamp01((clientY - rect.top) / rect.height);
     const { scrollSize, clientSize } = axisMetrics(viewport, false);
@@ -243,28 +264,34 @@ export function attachOverlayScrollbars(
   }
   function onRailUp() {
     railDragging = false;
-    rail?.classList.remove("is-dragging");
+    track?.classList.remove("is-dragging");
     document.removeEventListener("mousemove", onRailMove);
     document.removeEventListener("mouseup", onRailUp);
   }
   function onRailDown(e: MouseEvent) {
+    // Only a press ON a mark scrubs: the rest of the band keeps the
+    // track's own click-to-page behaviour.
+    const mark = (e.target as Element | null)?.closest?.(".hk-scrollbar-marker");
+    if (!mark) return;
     e.preventDefault();
-    // The rail sits inside a modal/panel that may itself dismiss on an
-    // outside press — scrubbing the rail must not double as that press.
+    // The band rides inside modals/panels that may dismiss on an outside
+    // press — scrubbing a mark must not double as that press.
     e.stopPropagation();
     railDragging = true;
-    rail?.classList.add("is-dragging");
+    track?.classList.add("is-dragging");
     railScrollTo(e.clientY);
     document.addEventListener("mousemove", onRailMove);
     document.addEventListener("mouseup", onRailUp);
   }
 
   function renderMarkers() {
-    if (!rail) return;
-    rail.replaceChildren();
+    if (!track) return;
+    // The thumb is a sibling that must stay on top of the marks (it slides
+    // over them, VS Code's semi-transparent thumb over the ruler).
+    track.querySelectorAll(":scope > .hk-scrollbar-marker").forEach((m) => m.remove());
     // Measured, not assumed: happy-dom and a `display:none` rail both
     // report 0, and the fraction floor is the honest answer there.
-    const railH = rail.clientHeight;
+    const railH = track.clientHeight;
     renderedRailHeight = railH;
     const floor = railH > 0
       ? Math.max(MARKER_MIN_FRACTION, MARKER_MIN_PX / railH)
@@ -283,12 +310,28 @@ export function attachOverlayScrollbars(
       const el = document.createElement("div");
       el.className = "hk-scrollbar-marker";
       if (m.kind) el.setAttribute("data-kind", m.kind);
+      if (m.side) el.setAttribute("data-side", m.side);
       el.style.top = pct(top);
       el.style.height = pct(size);
-      rail.appendChild(el);
+      track.appendChild(el);
     }
   }
 
+  /** Widen the track to the markers width (and back when they go away). */
+  function applyBandWidth() {
+    if (!track) return;
+    if (markers.length === 0) {
+      track.classList.remove("has-markers");
+      track.style.width = "";
+      return;
+    }
+    track.classList.add("has-markers");
+    const w = Math.round(
+      Math.min(Math.max(opts.markersWidth ?? DEFAULT_MARKERS_WIDTH, 8), 40),
+    );
+    track.style.width = `${w}px`;
+  }
+
   // An arrow const, not a function declaration: the guard above narrows
   // `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
@@ -296,40 +339,35 @@ export function attachOverlayScrollbars(
   const setMarkers = (next: OverlayScrollbarMarker[]) => {
     if (detached) return;
     markers = Array.isArray(next) ? next : [];
+    track = verticalTrack();
     if (markers.length === 0) {
-      // No marks = no rail, i.e. exactly the pre-marker chrome.
-      if (rail) {
-        rail.removeEventListener("mousedown", onRailDown);
-        rail.remove();
-        rail = null;
-      }
+      // No marks = exactly the pre-marker chrome.
+      track?.querySelectorAll(":scope > .hk-scrollbar-marker").forEach((m) => m.remove());
+      applyBandWidth();
       onRailUp();
       return;
     }
-    if (!wantV) return;
-    if (!rail) {
-      rail = document.createElement("div");
-      rail.className = "hk-scrollbar-markers";
-      rail.addEventListener("mousedown", onRailDown);
-      parent.appendChild(rail);
+    if (!wantV || !track) return;
+    if (!track.dataset.markersWired) {
+      track.dataset.markersWired = "true";
+      track.addEventListener("mousedown", onRailDown);
     }
+    applyBandWidth();
     renderMarkers();
-    // The rail's visibility follows the track's fit test.
+    // The marks' visibility follows the track's own fit test.
     update();
   };
 
   function updateAxis(s: AxisState, horizontal: boolean) {
     const { scrollSize, clientSize, scrollPos } = axisMetrics(viewport, horizontal);
     if (scrollSize <= clientSize) {
-      // Content fits — no bar at all. The rail follows the track: marks on
-      // a region that cannot scroll would claim changes the reader can
-      // never reach.
+      // Content fits — no bar at all. The marks live inside the track, so
+      // hiding it hides them too: marks on a region that cannot scroll
+      // would claim changes the reader can never reach.
       s.track.style.display = "none";
-      if (!horizontal && rail) rail.style.display = "none";
       return;
     }
     s.track.style.display = "";
-    if (!horizontal && rail) rail.style.display = "";
     const trackSize = horizontal ? s.track.clientWidth : s.track.clientHeight;
     const ratio = clientSize / scrollSize;
     const thumbSize = Math.max(ratio * trackSize, 20);
@@ -354,13 +392,14 @@ export function attachOverlayScrollbars(
   function update() {
     if (detached) return;
     for (const s of states) updateAxis(s, s.horizontal);
-    // The marks' pixel floor is a fraction OF the rail, so a height change
-    // invalidates the sizes they were rendered with. A hidden rail reports
+    // The marks' pixel floor is a fraction OF the band, so a height change
+    // invalidates the sizes they were rendered with. A hidden band reports
     // 0 and is skipped here; `renderMarkers` leaves that 0 behind as its
     // "never sized against a real height" sentinel, so the first visible
     // update re-renders even when the height matches the last one used.
-    const railH = rail?.clientHeight ?? 0;
-    if (rail && markers.length > 0 && railH > 0 && railH !== renderedRailHeight) {
+    const band = verticalTrack();
+    const railH = band?.clientHeight ?? 0;
+    if (band && markers.length > 0 && railH > 0 && railH !== renderedRailHeight) {
       renderMarkers();
     }
   }
@@ -480,17 +519,14 @@ export function attachOverlayScrollbars(
       ro = null;
       scheduled?.disconnect();
       scheduled = null;
-      if (rail) {
-        rail.removeEventListener("mousedown", onRailDown);
-        rail.remove();
-        rail = null;
-      }
       onRailUp();
       for (const { state, handlers } of axisBindings) {
         state.thumb.removeEventListener("mousedown", handlers.onDown);
         state.track.removeEventListener("click", handlers.onTrackClick);
         state.track.removeEventListener("mouseenter", handlers.onEnter);
         state.track.removeEventListener("mouseleave", handlers.onLeave);
+        state.track.removeEventListener("mousedown", onRailDown);
+        delete state.track.dataset.markersWired;
         document.removeEventListener("mousemove", handlers.onMove);
         document.removeEventListener("mouseup", handlers.onUp);
         state.hideTimer?.disconnect();

package/src/styles/theme/scrollbar.scss

@@ -51,6 +51,31 @@
     opacity: 1;
     pointer-events: auto;
   }
+
+  /* ── The widened band (marks showing) ───────────────────────────────
+     VS Code's overview ruler is the scrollbar's own strip WIDENED, not a
+     second strip beside it. Selective: only a track carrying marks gets
+     the width, the faint ground and the rounding.
+     The ground is a translucent mid-grey — over a light page it reads as
+     a faint grey, over a dark one as slightly lighter than the page, so
+     one declaration serves both modes (the muted token does not flip). */
+  &.has-markers:not([data-axis="horizontal"]) {
+    width: 14px; /* the engine overrides this inline with markersWidth */
+    border-radius: 2px;
+    background: color-mix(in srgb, var(--hi-color-muted, rgb(118 122 128)) 12%, transparent);
+    /* The band and its marks are ALWAYS visible — the whole point of an
+       overview ruler is a glance, not a hover. The track itself stays
+       `pointer-events: none` (below), so the ground still never steals a
+       press; only the marks accept input. */
+    opacity: 1;
+  }
+}
+
+/* The thumb rides OVER the marks (VS Code's translucent thumb over the
+   ruler): without a z-index of its own it would paint UNDER the opaque
+   marks, which are appended after it in the same stacking context. */
+.hk-scrollbar-thumb {
+  z-index: 2;
 }
 
 .hk-scrollbar-thumb {
@@ -84,65 +109,48 @@
   min-height: 20px;
 }
 
-/* ── Change-mark rail (VS Code's overview ruler) ──────────────────────
-   Rendered only when a consumer passes `markers` to
-   attachOverlayScrollbars (HkScrollContainer's `markers` prop), so every
-   existing consumer's chrome above is unchanged. It sits immediately
-   inboard of the vertical track — the two together read as one thick
-   marked scrollbar — and carries no chrome of its own beyond a faint
-   groove: the marks are the content. */
-.hk-scrollbar-markers {
-  position: absolute;
-  z-index: 11;
-  top: 4px;
-  bottom: 4px;
-  /* Vertical track: right 2px + width 6px → occupies 2–8px; a 2px gutter
-     puts the rail at 10px. The contract test pins this non-overlap. */
-  right: 10px;
-  width: 8px;
-  border-radius: 4px;
-  background: color-mix(in srgb, var(--hi-color-muted, rgb(118 122 128)) 18%, transparent);
-  overflow: hidden;
-  transition: background var(--hi-duration-fast, 0.15s) ease;
-
-  /* Pointer-transparent, exactly like the track above and for the same
-     reason: an overlay hugging the region's edge must never steal a press
-     meant for the content beneath it — and this rail spans the WHOLE host,
-     docks included, so it sits over right-aligned dock controls too. Only
-     the MARKS take input (see below): they are the targets that mean
-     something, and they are the rail's entire content. */
-  pointer-events: none;
-
-  &.is-dragging {
-    background: color-mix(in srgb, var(--hi-color-muted, rgb(118 122 128)) 32%, transparent);
-  }
-}
-
-/* One mark. `data-kind` is whatever tag the consumer passed; the three
-   diff kinds get the diff palette, anything else the neutral muted one.
-   The fallbacks mirror the thumb's: a themeless standalone render must
-   still show marks rather than an invalid-at-computed-value-time
-   transparent.
+/* ── Change marks (VS Code's overview ruler) ──────────────────────────
+   The marks live INSIDE the widened track (`.hk-scrollbar-track.has-markers`
+   above), so the scrollbar itself is the ruler — one band, not two. The
+   thumb slides OVER them (its z-index is higher and it is translucent, as
+   in VS Code). Only a track carrying marks changes: every other consumer's
+   chrome above is unchanged.
 
    Height comes ENTIRELY from the engine, which floors a hairline mark in
-   both fractions and pixels and sizes the end-of-rail inset against that
+   both fractions and pixels and sizes the end-of-band inset against that
    same number. A `min-height` here is therefore redundant — the engine
-   already guarantees 2px — and, because the rail clips, would win over
+   already guarantees 2px — and, because the track clips, would win over
    the inset on the occasions it did bite. */
 .hk-scrollbar-marker {
   position: absolute;
+  z-index: 1;
   left: 0;
   width: 100%;
-  border-radius: 1px;
+  border-radius: 2px;
   background: var(--hi-color-muted, rgb(118 122 128));
-  /* The rail is pointer-transparent; the marks are the hit area. */
+  /* The track is pointer-transparent at rest; the marks are the hit area. */
   pointer-events: auto;
   cursor: pointer;
 
+  /* VS Code's two lanes: REMOVED content hugs the band's start edge,
+     ADDED content its end edge, so one vertical position can carry both.
+     No `side` = the mark spans the full band. */
+  &[data-side="start"] {
+    left: 0;
+    right: auto;
+    width: 34%;
+  }
+
+  &[data-side="end"] {
+    left: auto;
+    right: 0;
+    width: 34%;
+  }
+
   &:hover {
-    /* Negative offset: the rail clips its children, and a plain outline
-       lost both side strokes to that clip (only the top/bottom lines
-       survived) — drawn inside, the ring stays whole. */
+    /* Negative offset: an outset ring would draw past the mark's own box
+       and read as a stray rule floating beside it — drawn inside, the cue
+       stays attached to the mark it belongs to. */
     outline: 1px solid color-mix(in srgb, var(--hi-color-muted, rgb(118 122 128)) 60%, transparent);
     outline-offset: -1px;
   }