@celestia-island/hikari 0.55.151 → 0.55.153

package/package.json

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

package/src/components/HkBoard.fitCap.test.tsx

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import HkBoard, { type BoardNodeInput } from "./HkBoard";
+
+/** A board whose content is far smaller than the viewport: the default fit
+ *  parks at the library cap; a fitCap lets the host fill the stage. */
+const nodes: BoardNodeInput[] = [
+  { id: "a", x: 0, y: 0, w: 120, h: 80, label: "A" },
+];
+const VIEW_W = 800;
+const VIEW_H = 600;
+
+function mountBoard(props: Record<string, unknown>): { world: () => string; app: ReturnType<typeof createApp> } {
+  // happy-dom lays nothing out: give the board a real viewport box so the
+  // fit maths are meaningful (the chest board tests use the same stub).
+  Object.defineProperty(HTMLElement.prototype, "clientWidth", { configurable: true, get: () => VIEW_W });
+  Object.defineProperty(HTMLElement.prototype, "clientHeight", { configurable: true, get: () => VIEW_H });
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const app = createApp(defineComponent({
+    setup: () => () => h(HkBoard, { nodes, ...props }),
+  }));
+  app.mount(host);
+  return {
+    world: () => document.body.querySelector<HTMLElement>(".hk-board-world")!.style.transform,
+    app,
+  };
+}
+
+/** The world transform's scale factor, parsed out of `translate(..) scale(k)`. */
+function scaleOf(transform: string): number {
+  return Number(/scale\(([\d.]+)\)/.exec(transform)?.[1] ?? 0);
+}
+
+describe("HkBoard fitCap", () => {
+  afterEach(() => { document.body.innerHTML = ""; });
+
+  it("caps the default fit at the library ceiling when no fitCap is given", async () => {
+    const { world, app } = mountBoard({});
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 30));
+    expect(scaleOf(world())).toBeLessThanOrEqual(1.25 + 1e-6);
+    app.unmount();
+  });
+
+  it("lets a host raise the fit ceiling to fill the stage", async () => {
+    const { world, app } = mountBoard({ fitCap: 3 });
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 30));
+    const k = scaleOf(world());
+    // The fit honours the raised cap: with a 120px node in an 800px-ish
+    // stage the scale would be ~5 at fill; the cap is the ceiling, so the
+    // observed scale must exceed the library default and not exceed 3.
+    expect(k).toBeGreaterThan(1.25);
+    expect(k).toBeLessThanOrEqual(3 + 1e-6);
+    app.unmount();
+  });
+});

package/src/components/HkBoard.tsx

@@ -117,6 +117,11 @@ export default defineComponent({
     minimap: { type: Boolean, default: true },
     minK: { type: Number, default: 0.2 },
     maxK: { type: Number, default: 4 },
+    /** Ceiling for the fit zoom (reset button, fitOnMount). The library
+     *  default caps a fit at 1.25 so a small board never fills a huge
+     *  viewport; a host that wants fill-the-stage framing passes a higher
+     *  cap (the camera clamp still honours maxK). */
+    fitCap: { type: Number, default: undefined },
     animated: { type: Boolean, default: true },
     fitOnMount: { type: Boolean, default: true },
   },
@@ -141,6 +146,7 @@ export default defineComponent({
       minK: props.minK,
       maxK: props.maxK,
       animated: props.animated,
+      fitCap: props.fitCap,
     });
     const camera = cam.camera as Ref<BoardCamera>;
 

package/src/components/HkScrollContainer.test.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, reactive, ref } from "vue";
 
 import HkScrollContainer from "./HkScrollContainer";
+import type { OverlayScrollbarMarker } from "../composables/useOverlayScrollbar";
 
 interface Mounted {
   app: ReturnType<typeof createApp>;
@@ -401,3 +402,44 @@ describe("HkScrollContainer back-to-top signal", () => {
     app.unmount();
   });
 });
+
+describe("HkScrollContainer change-mark rail", () => {
+  it("renders the marks prop, and re-applies new marks without rebuilding the chrome", async () => {
+    const markers = ref<OverlayScrollbarMarker[]>([{ start: 0.1, end: 0.2, kind: "added" }]);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, { markers: markers.value }, { default: () => h("span", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+
+    const rail = () => container.querySelector<HTMLElement>(".hk-scrollbar-markers");
+    const firstRail = rail();
+    expect(firstRail, "the rail exists once marks arrive").not.toBeNull();
+    expect(firstRail!.querySelectorAll(".hk-scrollbar-marker").length).toBe(1);
+
+    markers.value = [
+      { start: 0.5, end: 0.6, kind: "deleted" },
+      { start: 0.7, end: 0.8, kind: "modified" },
+    ];
+    await nextTick();
+    const marks = rail()!.querySelectorAll<HTMLElement>(".hk-scrollbar-marker");
+    expect(marks.length).toBe(2);
+    expect(marks[0].getAttribute("data-kind")).toBe("deleted");
+    // Same element: a marks update must not detach/reattach the overlay
+    // (that would drop the scroll flash and re-run the position guard).
+    expect(rail()).toBe(firstRail);
+    app.unmount();
+  });
+
+  it("keeps the rail out of the DOM when no marks are passed", () => {
+    const m = mountScroller({});
+    expect(m.container.querySelector(".hk-scrollbar-markers")).toBeNull();
+  });
+});

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 } from "../composables/useOverlayScrollbar";
+import { attachOverlayScrollbars, type OverlayScrollbarHandle, type OverlayScrollbarMarker } from "../composables/useOverlayScrollbar";
 import { useApproachEnd, type ApproachEndHandle } from "../composables/useApproachEnd";
 import { provideScrollWindow } from "../composables/useScrollWindow";
 import { SCROLL_HOST_CLASS } from "./HkScrollPin";
@@ -46,6 +46,12 @@ export default defineComponent({
     axis: { type: String as PropType<ScrollAxis>, default: "vertical" },
     mode: { type: String as PropType<ScrollMode>, default: "traditional" },
     scrollbar: { type: Boolean, default: true },
+    /** Change marks for the overlay's right-hand rail (VS Code's overview
+     *  ruler): fractions of the FULL content extent, so a mark stays put
+     *  while the user scrolls. Vertical axis only, and additive — leaving
+     *  it out renders exactly the chrome this container had before the
+     *  rail existed. */
+    markers: { type: Array as PropType<OverlayScrollbarMarker[]>, default: () => [] },
     autoFollow: { type: Boolean, default: false },
     overscanScreens: { type: Number, default: 1 },
     /** Inline-axis alignment of the content when it fits the viewport.
@@ -265,9 +271,16 @@ export default defineComponent({
       const vp = viewportRef.value;
       if (!vp) return;
       overlay?.detach();
-      overlay = attachOverlayScrollbars(vp, { axis: props.axis });
+      overlay = attachOverlayScrollbars(vp, { axis: props.axis, markers: props.markers });
     }
 
+    /** 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. */
+    watch(() => props.markers, (next) => {
+      overlay?.setMarkers(next ?? []);
+    }, { deep: true, flush: "post" });
+
     /** Tear down and rebuild the overlay tracks when the `scrollbar`
      *  opt-in flips at runtime (HkTabs passes the prop through). */
     watch(() => props.scrollbar, (on) => {

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

@@ -70,4 +70,45 @@ describe("overlay scrollbar chrome contract", () => {
     expect(chrome).toMatch(/\.hk-scrollbar-track\s*\{[^}]*pointer-events:\s*none/);
     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:
+    //
+    //  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]);
+
+    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);
+
+    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
+    // 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(
+      /outline-offset:\s*-1px/,
+    );
+  });
 });

package/src/composables/useBoardCamera.ts

@@ -47,6 +47,11 @@ export interface UseBoardCameraOptions {
   maxK?: number;
   /** Master animation switch; reduced-motion forces snapping regardless. */
   animated?: boolean;
+  /** Optional ceiling for fit()'s scale: boards whose content is smaller
+   *  than the viewport may want to fill it instead of parking at the
+   *  library's default cap (BOARD_FIT_CAP). Unset keeps the default; the
+   *  camera clamp still honours maxK. */
+  fitCap?: number;
 }
 
 export interface UseBoardCameraReturn {
@@ -81,6 +86,10 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
     minK = BOARD_K_MIN,
     maxK = BOARD_K_MAX,
     animated = true,
+    /** Ceiling for fit()'s scale: boards whose content is smaller than the
+     *  viewport may want to fill it instead of parking at the library's
+     *  default cap (BOARD_FIT_CAP). Unset keeps the default. */
+    fitCap = undefined,
   } = options;
 
   const camera = ref<BoardCamera>({ x: 0, y: 0, k: 1 });
@@ -195,7 +204,7 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
   }
 
   function fit(): void {
-    const target = boardFit(contentRect(), viewport());
+    const target = boardFit(contentRect(), viewport(), fitCap !== undefined ? { cap: fitCap } : {});
     kFloor = Math.min(minK, target.k);
     animateTo(target);
   }

package/src/composables/useOverlayScrollbar.test.ts

@@ -1,13 +1,16 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "./useOverlayScrollbar";
+import { attachOverlayScrollbars, type OverlayScrollbarHandle, type OverlayScrollbarOptions } from "./useOverlayScrollbar";
 
 const handles: OverlayScrollbarHandle[] = [];
 const containers: HTMLElement[] = [];
 
 /** Mount a viewport (the scrolling element) inside a wrapper inside a
  *  fresh container: wrapper ← viewport. The wrapper is the track host. */
-function mountViewport(axis: "vertical" | "horizontal" | "both" = "vertical") {
+function mountViewport(
+  axis: "vertical" | "horizontal" | "both" = "vertical",
+  extra: Omit<OverlayScrollbarOptions, "axis"> = {},
+) {
   const container = document.createElement("div");
   document.body.appendChild(container);
   containers.push(container);
@@ -15,11 +18,37 @@ function mountViewport(axis: "vertical" | "horizontal" | "both" = "vertical") {
   const viewport = document.createElement("div");
   wrapper.appendChild(viewport);
   container.appendChild(wrapper);
-  const handle = attachOverlayScrollbars(viewport, { axis });
+  const handle = attachOverlayScrollbars(viewport, { axis, ...extra });
   handles.push(handle);
   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. */
+function mountRailed(railHeight = 100) {
+  const mounted = mountViewport("vertical");
+  stubGeometry(mounted.viewport, {
+    scrollHeight: 1000, clientHeight: 100, scrollTop: 0,
+    scrollWidth: 100, clientWidth: 100, scrollLeft: 0,
+  });
+  mounted.handle.update();
+  return {
+    ...mounted,
+    rail: () => {
+      const el = mounted.wrapper.querySelector<HTMLElement>(".hk-scrollbar-markers");
+      if (el) {
+        vi.spyOn(el, "getBoundingClientRect").mockReturnValue({
+          top: 0, left: 0, width: 8, height: railHeight,
+          bottom: railHeight, right: 8, x: 0, y: 0, toJSON: () => ({}),
+        } as DOMRect);
+      }
+      return el;
+    },
+  };
+}
+
 /** happy-dom performs no layout, so scroll geometry is stubbed on the
  *  viewport instance (shadowing the prototype getters) — the same
  *  trick HkScrollContainer.test.ts uses, plus writable scroll offsets
@@ -44,6 +73,16 @@ function stubGeometry(
   Object.defineProperties(el, desc);
 }
 
+/** Give the rail a measured height before applying the marks under test.
+ *  The pixel floor is derived from `clientHeight` AT RENDER TIME, so the
+ *  stub has to exist before the marks are rendered. */
+function railOfHeight(m: ReturnType<typeof mountRailed>, height: number): HTMLElement {
+  m.handle.setMarkers([{ start: 0, end: 0 }]);
+  const rail = m.rail()!;
+  Object.defineProperty(rail, "clientHeight", { configurable: true, get: () => height });
+  return rail;
+}
+
 afterEach(() => {
   for (const h of handles.splice(0)) h.detach();
   for (const el of containers.splice(0)) el.remove();
@@ -308,7 +347,227 @@ describe("attachOverlayScrollbars", () => {
     handles.push(handle);
     expect(() => {
       handle.update();
+      handle.setMarkers([{ start: 0, end: 0.5 }]);
       handle.detach();
     }).not.toThrow();
   });
 });
+
+describe("change-mark rail", () => {
+  it("renders no rail at all when the consumer passes no markers", () => {
+    const { wrapper } = mountViewport("vertical");
+    expect(wrapper.querySelector(".hk-scrollbar-markers")).toBeNull();
+  });
+
+  it("creates the rail and one mark per entry, tagged by kind", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([
+      { start: 0.1, end: 0.2, kind: "added" },
+      { start: 0.5, end: 0.6, kind: "deleted" },
+    ]);
+    const rail = m.rail();
+    expect(rail).not.toBeNull();
+    const marks = rail!.querySelectorAll<HTMLElement>(".hk-scrollbar-marker");
+    expect(marks.length).toBe(2);
+    expect(marks[0].getAttribute("data-kind")).toBe("added");
+    expect(marks[1].getAttribute("data-kind")).toBe("deleted");
+    expect(marks[0].style.top).toBe("10%");
+    expect(marks[0].style.height).toBe("10%");
+    expect(marks[1].style.top).toBe("50%");
+  });
+
+  it("accepts markers through the attach options", () => {
+    const m = mountViewport("vertical", { markers: [{ start: 0, end: 0.25, kind: "added" }] });
+    stubGeometry(m.viewport, {
+      scrollHeight: 1000, clientHeight: 100, scrollTop: 0,
+      scrollWidth: 100, clientWidth: 100, scrollLeft: 0,
+    });
+    m.handle.update();
+    expect(m.wrapper.querySelectorAll(".hk-scrollbar-marker").length).toBe(1);
+  });
+
+  it("floors a hairline mark and keeps an end-of-file mark inside the rail", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([
+      // One line of a 1000-line file: 0.1% — under the floor.
+      { start: 0.4, end: 0.401, kind: "modified" },
+      // The very last line: top + height must not overflow the rail.
+      { start: 1, end: 1, kind: "added" },
+    ]);
+    const marks = m.rail()!.querySelectorAll<HTMLElement>(".hk-scrollbar-marker");
+    expect(parseFloat(marks[0].style.height), "floored to the minimum").toBeCloseTo(0.5, 5);
+    const top = parseFloat(marks[1].style.top);
+    const height = parseFloat(marks[1].style.height);
+    expect(top + height, "a mark at the end stays inside the rail").toBeLessThanOrEqual(100);
+  });
+
+  it("floors a hairline mark in PIXELS on a short rail, not just as a fraction", () => {
+    const m = mountRailed();
+    railOfHeight(m, 100);
+    m.handle.setMarkers([{ start: 0.4, end: 0.401, kind: "modified" }]);
+    // `update()` is the path that re-renders marks laid out before a height
+    // existed (a no-layout DOM reports 0, which leaves the "never sized"
+    // sentinel behind) — without it this test silently asserted the
+    // FRACTION floor and would have stayed green with no pixel floor at all.
+    m.handle.update();
+    // 2px of a 100px rail = 2%. The fraction floor alone (0.5%) is a
+    // half-pixel target — and since the rail is pointer-transparent the
+    // marks ARE the hit area, so a half-pixel mark is a half-pixel button.
+    expect(
+      parseFloat(m.rail()!.querySelector<HTMLElement>(".hk-scrollbar-marker")!.style.height),
+    ).toBeCloseTo(2, 5);
+  });
+
+  it("re-sizes the marks when the rail is resized", () => {
+    const m = mountRailed();
+    const rail = railOfHeight(m, 100);
+    m.handle.setMarkers([{ start: 0.4, end: 0.401, kind: "modified" }]);
+    const height = () =>
+      parseFloat(m.rail()!.querySelector<HTMLElement>(".hk-scrollbar-marker")!.style.height);
+    expect(height()).toBeCloseTo(2, 5);
+    // A taller rail makes the same 2px a smaller share of it.
+    Object.defineProperty(rail, "clientHeight", { configurable: true, get: () => 400 });
+    m.handle.update();
+    expect(height(), "2px of a 400px rail").toBeCloseTo(0.5, 5);
+  });
+
+  it("clamps a reversed or out-of-range span instead of rendering it outside", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.8, end: 0.2, kind: "added" }]);
+    const mark = m.rail()!.querySelector<HTMLElement>(".hk-scrollbar-marker")!;
+    expect(mark.style.top).toBe("20%");
+    expect(mark.style.height).toBe("60%");
+  });
+
+  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" }]);
+    const top = () => m.rail()!.querySelector<HTMLElement>(".hk-scrollbar-marker")!.style.top;
+    expect(top()).toBe("25%");
+    stubGeometry(m.viewport, {
+      scrollHeight: 1000, clientHeight: 100, scrollTop: 500,
+      scrollWidth: 100, clientWidth: 100, scrollLeft: 0,
+    });
+    m.viewport.dispatchEvent(new Event("scroll"));
+    m.handle.update();
+    expect(top(), "the rail maps the whole document, not the window").toBe("25%");
+  });
+
+  it("removes the rail again when the marks are cleared", () => {
+    const m = mountRailed();
+    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();
+  });
+
+  it("hides the rail while the content fits, and shows it again when it scrolls", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.1, end: 0.2, kind: "added" }]);
+    stubGeometry(m.viewport, {
+      scrollHeight: 100, clientHeight: 100, scrollTop: 0,
+      scrollWidth: 100, clientWidth: 100, scrollLeft: 0,
+    });
+    m.handle.update();
+    expect(m.rail()!.style.display).toBe("none");
+    stubGeometry(m.viewport, {
+      scrollHeight: 1000, clientHeight: 100, scrollTop: 0,
+      scrollWidth: 100, clientWidth: 100, scrollLeft: 0,
+    });
+    m.handle.update();
+    expect(m.rail()!.style.display).toBe("");
+  });
+
+  it("never renders a rail on a horizontal-only scroll region", () => {
+    const m = mountViewport("horizontal");
+    stubGeometry(m.viewport, {
+      scrollHeight: 100, clientHeight: 100, scrollTop: 0,
+      scrollWidth: 1000, clientWidth: 100, scrollLeft: 0,
+    });
+    m.handle.update();
+    m.handle.setMarkers([{ start: 0.1, end: 0.2, kind: "added" }]);
+    expect(m.wrapper.querySelector(".hk-scrollbar-markers")).toBeNull();
+  });
+
+  it("ignores non-finite mark bounds instead of parking them at NaN%", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([
+      { start: Number.NaN, end: Number.NaN, kind: "added" },
+      { start: Number.POSITIVE_INFINITY, end: 0.9, kind: "modified" },
+    ]);
+    const marks = m.rail()!.querySelectorAll<HTMLElement>(".hk-scrollbar-marker");
+    // "NaN%" is rejected by CSSOM: the element keeps no inline top/height,
+    // collapses to zero height and the mark silently does not exist.
+    expect(marks[0].style.top).toBe("0%");
+    expect(marks[0].style.height).toBe("0.5%");
+    // Infinity is not "the end of the file" — non-finite clamps to 0.
+    expect(marks[1].style.top).toBe("0%");
+  });
+
+  it("keeps a mark press from escaping to the page and shows the drag", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.3, end: 0.35, kind: "added" }]);
+    const rail = m.rail()!;
+    const mark = rail.querySelector<HTMLElement>(".hk-scrollbar-marker")!;
+    // The rail rides inside modals/drawers that dismiss on an outside
+    // press; scrubbing it must not double as that press.
+    let escaped = 0;
+    const spy = () => { escaped += 1; };
+    document.body.addEventListener("mousedown", spy);
+    const down = new MouseEvent("mousedown", { bubbles: true, cancelable: true, clientY: 0 });
+    mark.dispatchEvent(down);
+    expect(down.defaultPrevented, "the press is consumed").toBe(true);
+    expect(escaped, "the press never reaches the page").toBe(0);
+    expect(rail.classList.contains("is-dragging"), "the rail shows the drag").toBe(true);
+    document.dispatchEvent(new MouseEvent("mouseup"));
+    expect(rail.classList.contains("is-dragging"), "and clears it on release").toBe(false);
+    document.body.removeEventListener("mousedown", spy);
+  });
+
+  it("jumps to a mark when the mark is pressed", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.3, end: 0.35, kind: "added" }]);
+    const mark = m.rail()!.querySelector<HTMLElement>(".hk-scrollbar-marker")!;
+    mark.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, clientY: 50 }));
+    // Halfway down a 100px rail over a 900px scroll range.
+    expect(m.viewport.scrollTop).toBe(450);
+    document.dispatchEvent(new MouseEvent("mouseup"));
+  });
+
+  it("scrubs while the rail is dragged and stops on mouseup", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.3, end: 0.35, kind: "added" }]);
+    const mark = m.rail()!.querySelector<HTMLElement>(".hk-scrollbar-marker")!;
+    mark.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, clientY: 0 }));
+    expect(m.viewport.scrollTop).toBe(0);
+    document.dispatchEvent(new MouseEvent("mousemove", { clientY: 100 }));
+    expect(m.viewport.scrollTop, "dragged to the bottom").toBe(900);
+    document.dispatchEvent(new MouseEvent("mouseup"));
+    // The document listeners are gone: a later move must not scroll.
+    m.viewport.scrollTop = 0;
+    document.dispatchEvent(new MouseEvent("mousemove", { clientY: 50 }));
+    expect(m.viewport.scrollTop, "no scrub after mouseup").toBe(0);
+  });
+
+  it("detach removes the rail and its document listeners", () => {
+    const m = mountRailed();
+    m.handle.setMarkers([{ start: 0.3, end: 0.35, kind: "added" }]);
+    const mark = m.rail()!.querySelector<HTMLElement>(".hk-scrollbar-marker")!;
+    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();
+    m.viewport.scrollTop = 0;
+    document.dispatchEvent(new MouseEvent("mousemove", { clientY: 100 }));
+    expect(m.viewport.scrollTop, "detach dropped the drag listener").toBe(0);
+    document.dispatchEvent(new MouseEvent("mouseup"));
+  });
+
+  it("ignores setMarkers after detach", () => {
+    const m = mountRailed();
+    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();
+  });
+});

package/src/composables/useOverlayScrollbar.ts

@@ -30,6 +30,57 @@ import { scheduleFrame, type AnimationHandle } from "../runtime/animationBus";
 /** Which axes get an overlay track. Defaults to "vertical". */
 export type OverlayScrollbarAxis = "vertical" | "horizontal" | "both";
 
+/**
+ * One change mark on the vertical rail beside the track — the "where in
+ * the document is the interesting part" affordance a diff, a search
+ * result set or a lint run wants next to its scrollbar (VS Code's
+ * overview ruler).
+ *
+ * Positions are fractions of the FULL content extent, never of the
+ * visible window: line 500 of a 1000-line file sits at 0.5 while the
+ * user scrolls, and the rail keeps representing the whole document while
+ * the thumb represents the window. The engine stays domain-agnostic —
+ * the consumer divides its own line numbers, byte offsets or match
+ * indices by its own total.
+ */
+export interface OverlayScrollbarMarker {
+  /** Mark start in [0, 1] along the content. */
+  start: number;
+  /** Mark end in [0, 1]; clamped to at least `start`. */
+  end: number;
+  /** Semantic tag mirrored onto `data-kind`, so the consumer's theme owns
+   *  the palette (this engine ships no colours of its own). */
+  kind?: string;
+}
+
+/** Shortest a mark may render, as a fraction of the rail. A one-line edit
+ *  in a long file is ~0.1% of the content — without a floor it would be a
+ *  sub-pixel sliver, i.e. invisible exactly when the reader needs it. */
+const MARKER_MIN_FRACTION = 0.005;
+
+/** …and the same floor in CSS pixels, which is what actually decides
+ *  whether a mark can be SEEN and HIT on a short rail: at 1000px tall the
+ *  fraction floor is 5px, at 100px it is 0.5px. It lives in the engine —
+ *  not as a stylesheet `min-height` — for two reasons: the floor has to
+ *  scale with the rail, and the end-of-rail inset below has to be computed
+ *  from the SAME number, which CSS cannot express. */
+const MARKER_MIN_PX = 2;
+
+/** 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 {
+  if (!Number.isFinite(n)) return 0;
+  return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+
+/** A rail offset as a CSS percentage with the float noise trimmed: the
+ *  span `0.8 − 0.2` is 0.6000000000000001, and a position is not a
+ *  measurement — "60.00000000000001%" is noise in the DOM, in snapshots
+ *  and in any consumer assertion. */
+function pct(fraction: number): string {
+  return `${Number((fraction * 100).toFixed(4))}%`;
+}
+
 export interface OverlayScrollbarOptions {
   axis?: OverlayScrollbarAxis;
   /** Element the tracks are appended to — their positioning context.
@@ -42,11 +93,19 @@ export interface OverlayScrollbarOptions {
    *  (see HkDrawer/HkSidebar/HkTable for the pattern). Never rely on
    *  the guard to promote `body`. */
   host?: HTMLElement;
+  /** Change marks drawn on a rail immediately inboard of the vertical
+   *  track. Vertical axis only — a horizontal rail has no meaningful
+   *  "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[];
 }
 
 export interface OverlayScrollbarHandle {
   /** Re-read the viewport's scroll geometry and reposition the thumbs. */
   update(): 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;
   /** Remove the tracks and every listener/observer; restore any
    *  inline positioning the guard applied. Safe to call twice. */
   detach(): void;
@@ -117,7 +176,7 @@ export function attachOverlayScrollbars(
   const axis = opts.axis ?? "vertical";
   const parent = opts.host ?? viewport.parentElement;
   if (!parent) {
-    return { update() {}, detach() {} };
+    return { update() {}, setMarkers() {}, detach() {} };
   }
 
   const wantV = axis !== "horizontal";
@@ -156,14 +215,121 @@ export function attachOverlayScrollbars(
   let ro: ResizeObserver | null = null;
   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;
+  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;
+
+  /** 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 (rect.height <= 0) return;
+    const ratio = clamp01((clientY - rect.top) / rect.height);
+    const { scrollSize, clientSize } = axisMetrics(viewport, false);
+    viewport.scrollTop = ratio * Math.max(scrollSize - clientSize, 0);
+  }
+
+  function onRailMove(e: MouseEvent) {
+    if (railDragging) railScrollTo(e.clientY);
+  }
+  function onRailUp() {
+    railDragging = false;
+    rail?.classList.remove("is-dragging");
+    document.removeEventListener("mousemove", onRailMove);
+    document.removeEventListener("mouseup", onRailUp);
+  }
+  function onRailDown(e: MouseEvent) {
+    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.
+    e.stopPropagation();
+    railDragging = true;
+    rail?.classList.add("is-dragging");
+    railScrollTo(e.clientY);
+    document.addEventListener("mousemove", onRailMove);
+    document.addEventListener("mouseup", onRailUp);
+  }
+
+  function renderMarkers() {
+    if (!rail) return;
+    rail.replaceChildren();
+    // 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;
+    renderedRailHeight = railH;
+    const floor = railH > 0
+      ? Math.max(MARKER_MIN_FRACTION, MARKER_MIN_PX / railH)
+      : MARKER_MIN_FRACTION;
+    for (const m of markers) {
+      const size = Math.max(
+        Math.abs(clamp01(m.end) - clamp01(m.start)),
+        floor,
+      );
+      // Keep the whole mark inside the rail: a mark at the very end would
+      // otherwise overflow the bottom, get clipped, and read as absent.
+      const top = Math.max(
+        Math.min(clamp01(m.start), clamp01(m.end), 1 - size),
+        0,
+      );
+      const el = document.createElement("div");
+      el.className = "hk-scrollbar-marker";
+      if (m.kind) el.setAttribute("data-kind", m.kind);
+      el.style.top = pct(top);
+      el.style.height = pct(size);
+      rail.appendChild(el);
+    }
+  }
+
+  // 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
+  // capture back to `HTMLElement | null`).
+  const setMarkers = (next: OverlayScrollbarMarker[]) => {
+    if (detached) return;
+    markers = Array.isArray(next) ? next : [];
+    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;
+      }
+      onRailUp();
+      return;
+    }
+    if (!wantV) return;
+    if (!rail) {
+      rail = document.createElement("div");
+      rail.className = "hk-scrollbar-markers";
+      rail.addEventListener("mousedown", onRailDown);
+      parent.appendChild(rail);
+    }
+    renderMarkers();
+    // The rail's visibility follows the track's 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.
+      // 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.
       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);
@@ -188,6 +354,15 @@ 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
+    // 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) {
+      renderMarkers();
+    }
   }
 
   function scheduleUpdate() {
@@ -292,9 +467,11 @@ export function attachOverlayScrollbars(
   ro = new ResizeObserver(scheduleUpdate);
   ro.observe(viewport);
   update();
+  if (opts.markers?.length) setMarkers(opts.markers);
 
   return {
     update,
+    setMarkers,
     detach() {
       if (detached) return;
       detached = true;
@@ -303,6 +480,12 @@ 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);

package/src/index.ts

@@ -420,6 +420,9 @@ export type { PasswordValidationResult, PasswordLevel, PasswordStrengthEvaluator
 export { FOCUSABLE_SELECTOR, getFocusableElements, focusFirst, trapFocus, scrollToElement } from "./utils/dom";
 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 { useDeferredTransition } from "./composables/useDeferredTransition";
 export { useSurfaceTransition } from "./composables/useSurfaceTransition";
 export { useSizeMorph } from "./composables/useSizeMorph";

package/src/styles/theme/scrollbar.scss

@@ -83,3 +83,79 @@
   width: 100%;
   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.
+
+   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
+   same number. A `min-height` here is therefore redundant — the engine
+   already guarantees 2px — and, because the rail clips, would win over
+   the inset on the occasions it did bite. */
+.hk-scrollbar-marker {
+  position: absolute;
+  left: 0;
+  width: 100%;
+  border-radius: 1px;
+  background: var(--hi-color-muted, rgb(118 122 128));
+  /* The rail is pointer-transparent; the marks are the hit area. */
+  pointer-events: auto;
+  cursor: pointer;
+
+  &: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. */
+    outline: 1px solid color-mix(in srgb, var(--hi-color-muted, rgb(118 122 128)) 60%, transparent);
+    outline-offset: -1px;
+  }
+
+  &[data-kind="added"] {
+    background: var(--hi-color-success, #0eb840);
+  }
+
+  &[data-kind="deleted"] {
+    background: var(--hi-color-danger, #ff4c00);
+  }
+
+  &[data-kind="modified"] {
+    background: var(--hi-color-warning, #eed677);
+  }
+}