@celestia-island/hikari 0.55.338 → 0.55.339

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.338",
+  "version": "0.55.339",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkRangeRibbon.scss

@@ -1,9 +1,16 @@
 @use "../styles/polyfill" as *;
 
-/* HkRangeRibbon — a multi-lane sequence ribbon with a brushed window.
-   Anatomy: a thin OVERVIEW strip (the full domain, always), the window
-   highlight + outside scrims + two edge handles riding over it, then the
-   lane list whose segment bars show either the full domain or the window.
+/* HkRangeRibbon — the two-layer sequence waterfall with a brushed window.
+   Anatomy: LAYER 1 (data-layer="minimap") is the thin OVERVIEW strip over
+   the full domain, always — the window highlight + outside scrims + two edge
+   handles ride over it and the reset seat sits on its field. LAYER 2
+   (data-layer="detail") is the lane list: the same segments shown either
+   across the full domain or mapped onto the window (0..100% of the track).
+   The minimap axis is `1 + headroom` wide, so a host can reserve a blank
+   trailing tail for a >100% budget; the after scrim dims that tail once a
+   window exists. The headroom never reaches the detail layer, and minimal
+   mode — which suppresses the lane rows and the detail layer while the bare
+   bar still lives in the minimap container — ignores it too.
 
    Geometry is part of the contract and pinned by HkRangeRibbon.test.tsx:
    the strip is 32px tall, a handle is an 8px half-overlapping grip
@@ -20,15 +27,17 @@
    pending-segment breathe, registered in animation/registerAnimations.ts. */
 
 .hk-range-ribbon {
-  // ONE label column for both surfaces: the overview paints through an
-  // empty gutter of this width, so an x% bar sits at the same inline
-  // position in the strip and in its lane (the strip locates segments).
+  // ONE label column for both layers: the overview paints through an empty
+  // gutter of this width, so both layers always start at the same inline x.
+  // Their x% agree only in the full-domain view — a window re-normalizes the
+  // detail against the selected sub-domain, and a headroom compresses the
+  // strip by `1/span`.
   // Wave (2026-11-06 raw-records five): the label column is JS-MEASURED —
   // the component publishes the widest rendered label as a px value on the
   // root (two-phase free/measure/pin). THIS fixed column is the no-JS /
-  // pre-measure fallback: a shared width keeps strip-lane x% alignment
-  // before the measurement lands (a bare max-content here would resolve
-  // 0px in the empty gutter and misalign everything).
+  // pre-measure fallback: a shared width keeps the two layers' inline START
+  // aligned before the measurement lands (a bare max-content here would
+  // resolve 0px in the empty gutter and misalign everything).
   --hk-range-ribbon-label-col: minmax(48px, 84px);
 
   display: flex;
@@ -38,7 +47,7 @@
   min-width: 0;
 }
 
-// ── Overview strip (the full-domain minimap + brush surface) ─────────────
+// ── LAYER 1: overview strip (the full-domain minimap + brush surface) ───
 .hk-range-ribbon-overview {
   position: relative;
   display: grid;
@@ -253,6 +262,17 @@
   white-space: nowrap;
 }
 
+// ── Detail layer (the window-focused lane list) ─────────────────────────
+// A plain column container, nothing else: it exists so the two layers are
+// explicit in the DOM (and to the stylesheet contract) without disturbing
+// the lane list's own gap/column layout. Its x-axis is the selected window
+// mapped to 0..100% — the headroom tail lives only on the minimap layer.
+.hk-range-ribbon-detail {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
 // ── Lane list ───────────────────────────────────────────────────────────
 .hk-range-ribbon-lanes {
   display: flex;

package/src/components/HkRangeRibbon.test.tsx

@@ -28,7 +28,11 @@ import jaBundle from "../i18n/locales/ja/components.json";
  *   · every reset path (button / dblclick / Escape / Home) lands null and
  *     restores the full view;
  *   · sub-minimum brushes, edge drags and keyboard nudges clamp instead of
- *     crossing.
+ *     crossing;
+ *   · the two layers stay explicit (minimap / detail) over one absolute
+ *     fraction contract, and `headroom` widens ONLY the minimap axis — the
+ *     detail stays window-relative and the blank tail clamps to content
+ *     100%.
  * A stylesheet contract at the bottom compiles the sheet and pins the
  * classes, geometry and the one animation (repo convention: vitest stubs
  * CSS, so the runtime cases can never catch a dead rule).
@@ -1357,6 +1361,214 @@ describe("HkRangeRibbon controlled contract", () => {
   });
 });
 
+// ── Dual-layer waterfall + headroom axis ────────────────────────────────
+describe("HkRangeRibbon dual-layer waterfall", () => {
+  /** The minimap's x for a content fraction, in percent: every minimap box
+   *  is `fraction / span`, where span = 1 + headroom. */
+  function axisPercent(fraction: number, headroom: number): number {
+    return (fraction / (1 + headroom)) * 100;
+  }
+
+  it("marks both layers explicitly and keeps the lane markup intact", () => {
+    const root = mountRibbon({ window: [0.35, 0.67] });
+    const minimap = root.querySelector<HTMLElement>(".hk-range-ribbon-overview");
+    expect(minimap, "the minimap layer renders").toBeTruthy();
+    expect(minimap!.getAttribute("data-layer")).toBe("minimap");
+    // The strip (brush surface + window chrome host) is the minimap's own.
+    expect(minimap!.querySelector(".hk-range-ribbon-strip")).toBeTruthy();
+    expect(minimap!.querySelector(".hk-range-ribbon-overview-gutter")).toBeTruthy();
+    expect(minimap!.querySelectorAll(".hk-range-ribbon-overview-row")).toHaveLength(2);
+
+    const detail = root.querySelector<HTMLElement>(".hk-range-ribbon-detail");
+    expect(detail, "the detail layer renders").toBeTruthy();
+    expect(detail!.getAttribute("data-layer")).toBe("detail");
+    // The lane list keeps its markup verbatim and lives INSIDE the wrapper.
+    const lanes = detail!.querySelector<HTMLElement>(".hk-range-ribbon-lanes");
+    expect(lanes, "the lane list is nested in the detail layer").toBeTruthy();
+    expect(lanes!.parentElement).toBe(detail);
+    expect(detail!.querySelectorAll(".hk-range-ribbon-lane")).toHaveLength(2);
+    expect(detail!.querySelectorAll(".hk-range-ribbon-lane-track")).toHaveLength(2);
+    // Exactly two layers, in reading order (minimap above detail).
+    expect(Array.from(root.children).map((child) => child.getAttribute("data-layer"))).toEqual([
+      "minimap",
+      "detail",
+    ]);
+    // Minimal mode stays a bare bar: no detail layer at all.
+    expect(mountRibbon({ minimal: true }).querySelector(".hk-range-ribbon-detail")).toBeNull();
+  });
+
+  it("maps the same absolute fraction onto both layers (minimap f/span, detail window-relative)", () => {
+    // parse covers 30%..45% of the whole progress; the window is 35%..67%.
+    const root = mountRibbon({ window: [0.35, 0.67], headroom: 0.1 });
+    const parseOverview = root.querySelector<HTMLElement>(
+      '.hk-range-ribbon-overview-segment[data-segment-id="parse"]',
+    )!;
+    expect(boxOf(parseOverview).left, "minimap left = 0.3 / span").toBeCloseTo(
+      axisPercent(0.3, 0.1),
+      4,
+    );
+    expect(boxOf(parseOverview).width, "minimap width = 0.15 / span").toBeCloseTo(
+      axisPercent(0.15, 0.1),
+      4,
+    );
+
+    // Detail: the SAME segment, clipped to the window and re-normalized. The
+    // headroom never enters this axis — a [0.35, 0.67] window spans 0..100%.
+    const parseDetail = segmentById(root, "parse")!;
+    expect(boxOf(parseDetail).left, "detail starts at the window start").toBeCloseTo(0, 4);
+    expect(boxOf(parseDetail).width, "detail width is window-relative").toBeCloseTo(
+      ((0.45 - 0.35) / (0.67 - 0.35)) * 100,
+      4,
+    );
+    const writeDetail = segmentById(root, "write")!;
+    expect(
+      boxOf(writeDetail).left + boxOf(writeDetail).width,
+      "detail ends at the window end",
+    ).toBeCloseTo(100, 4);
+
+    // A detail box under a headroom is byte-identical to its box with no
+    // headroom at all — the tail is a minimap-only projection.
+    const noTail = mountRibbon({ window: [0.35, 0.67] });
+    expect(boxOf(segmentById(root, "write")!)).toEqual(boxOf(segmentById(noTail, "write")!));
+    // …while the window frame is axis-projected on the minimap.
+    const frame = root.querySelector<HTMLElement>(".hk-range-ribbon-window")!;
+    expect(boxOf(frame).left).toBeCloseTo(axisPercent(0.35, 0.1), 4);
+    expect(boxOf(frame).width).toBeCloseTo(axisPercent(0.32, 0.1), 4);
+  });
+
+  it("reserves the blank tail: scrims, frame and handles all stop at the axis end", () => {
+    // window [0.2, 1]: the whole content is selected, so the entire tail is
+    // "after the window" and must stay dimmed — reusing 1 - win[1] would
+    // leave it bare.
+    const root = mountRibbon({ window: [0.2, 1], headroom: 0.1 });
+    const before = root.querySelector<HTMLElement>('.hk-range-ribbon-scrim[data-side="before"]')!;
+    const after = root.querySelector<HTMLElement>('.hk-range-ribbon-scrim[data-side="after"]')!;
+    expect(boxOf(before).width, "before scrim = window start / span").toBeCloseTo(
+      axisPercent(0.2, 0.1),
+      4,
+    );
+    expect(boxOf(after).left, "after scrim starts where content 100% sits").toBeCloseTo(
+      axisPercent(1, 0.1),
+      4,
+    );
+    expect(boxOf(after).width, "after scrim width = (span - window end) / span").toBeCloseTo(
+      ((1.1 - 1) / 1.1) * 100,
+      4,
+    );
+    expect(
+      boxOf(after).left + boxOf(after).width,
+      "the after scrim reaches the axis end",
+    ).toBeCloseTo(100, 4);
+
+    const frame = root.querySelector<HTMLElement>(".hk-range-ribbon-window")!;
+    expect(boxOf(frame).left).toBeCloseTo(axisPercent(0.2, 0.1), 4);
+    expect(boxOf(frame).width).toBeCloseTo(axisPercent(0.8, 0.1), 4);
+
+    const start = root.querySelector<HTMLElement>('.hk-range-ribbon-handle[data-edge="start"]')!;
+    const end = root.querySelector<HTMLElement>('.hk-range-ribbon-handle[data-edge="end"]')!;
+    expect(parseFloat(start.style.left), "start grip at content 20% on the axis").toBeCloseTo(
+      axisPercent(0.2, 0.1),
+      4,
+    );
+    expect(parseFloat(end.style.left), "end grip at content 100% on the axis").toBeCloseTo(
+      axisPercent(1, 0.1),
+      4,
+    );
+    // The a11y readings stay CONTENT percentages: the axis projection is
+    // presentation, never the value the host or assistive tech sees.
+    expect(end.getAttribute("aria-valuenow")).toBe("100");
+    expect(end.getAttribute("aria-valuetext")).toBe("100%");
+    expect(
+      root.querySelector<HTMLElement>(".hk-range-ribbon-strip")!.getAttribute("aria-valuetext"),
+    ).toBe("20% – 100%");
+  });
+
+  it("sanitizes the headroom so a bad value never distorts the axis", () => {
+    const cases: Array<[number, number]> = [
+      [0, 1],
+      [-0.5, 1],
+      [Number.NaN, 1],
+      [Number.NEGATIVE_INFINITY, 1],
+      [Number.POSITIVE_INFINITY, 1],
+      [2, 2],
+    ];
+    for (const [headroom, span] of cases) {
+      const root = mountRibbon({ window: null, headroom });
+      const parse = root.querySelector<HTMLElement>(
+        '.hk-range-ribbon-overview-segment[data-segment-id="parse"]',
+      )!;
+      expect(parse, `headroom ${headroom} still paints`).toBeTruthy();
+      expect(boxOf(parse).left, `headroom ${headroom} maps through span ${span}`).toBeCloseTo(
+        (0.3 / span) * 100,
+        4,
+      );
+    }
+  });
+
+  it("keeps the headroom out of the detail when no window is selected", () => {
+    const root = mountRibbon({ window: null, headroom: 0.1 });
+    // Detail bars keep the full-domain content axis (30%, not 27.27%).
+    expect(boxOf(segmentById(root, "parse")!).left).toBeCloseTo(30, 4);
+    const overview = root.querySelector<HTMLElement>(
+      '.hk-range-ribbon-overview-segment[data-segment-id="parse"]',
+    )!;
+    expect(boxOf(overview).left, "the minimap still reserves the tail").toBeCloseTo(
+      axisPercent(0.3, 0.1),
+      4,
+    );
+  });
+
+  it("clamps a pointer in the blank tail to content 100% (padding is not progress)", async () => {
+    const host = mountHost(null, { headroom: 0.1 });
+    const { strip, x } = stubStrip(host.root);
+
+    // A press at axis 95% is inside the tail (content 104.5%) and must anchor
+    // at content 1.0; the drag back to axis 30% is content 33%.
+    await drag(strip, 0.95, 0.3, x);
+    expectWindow(lastWindow(host.windowChange), 0.33, 1);
+
+    // The end handle dragged INTO the blank tail (axis 95% reads content
+    // 104.5%) still commits content 100%: a read that skipped the span would
+    // answer 95% and leave the window at [0.2, 0.95]. Dragging to the exact
+    // far right would pass either way (1 × span = 1), so this target is the
+    // revert discriminator for the handle path.
+    await host.setWindow([0.2, 0.5]);
+    const end = host.root.querySelector<HTMLElement>('.hk-range-ribbon-handle[data-edge="end"]')!;
+    expect(end, "the end grip renders for the sub-window").toBeTruthy();
+    await drag(end, 0.45, 0.95, x);
+    expectWindow(lastWindow(host.windowChange), 0.2, 1);
+  });
+
+  it("ignores the headroom in minimal mode (it is a minimap-only axis)", async () => {
+    // Minimal mode has no minimap layer, so the bare bar must stay on the
+    // CONTENT axis. A headroom-applied span would park the rest end grip at
+    // ~90.9% and leave an unlabeled dim tail on a bar that has no tail
+    // semantics.
+    const rest = mountRibbon({ minimal: true, headroom: 0.1, window: [0, 1] });
+    const restStart = rest.querySelector<HTMLElement>('.hk-range-ribbon-handle[data-edge="start"]')!;
+    const restEnd = rest.querySelector<HTMLElement>('.hk-range-ribbon-handle[data-edge="end"]')!;
+    expect(parseFloat(restStart.style.left), "rest start grip at content 0%").toBeCloseTo(0, 4);
+    expect(parseFloat(restEnd.style.left), "rest end grip at content 100%").toBeCloseTo(100, 4);
+
+    // A sub-window keeps content geometry for its grips and after scrim: with
+    // a span the scrim would start at 54.5% and run 45.5%, i.e. a reserved
+    // tail that minimal mode cannot explain.
+    const sub = mountRibbon({ minimal: true, headroom: 0.1, window: [0.2, 0.6] });
+    const subEnd = sub.querySelector<HTMLElement>('.hk-range-ribbon-handle[data-edge="end"]')!;
+    expect(parseFloat(subEnd.style.left), "grips keep content fractions").toBeCloseTo(60, 4);
+    const after = sub.querySelector<HTMLElement>('.hk-range-ribbon-scrim[data-side="after"]')!;
+    expect(boxOf(after).left, "the after scrim starts at the window end").toBeCloseTo(60, 4);
+    expect(boxOf(after).width, "no reserved tail to dim").toBeCloseTo(40, 4);
+
+    // …and the pointer axis is the content axis: axis 50% reads content 50%
+    // (a headroom-applied read would answer 55%), and the far right is 100%.
+    const host = mountHost([0.2, 0.6], { minimal: true, headroom: 0.1 });
+    const { strip, x } = stubStrip(host.root);
+    await drag(strip, 0.5, 1, x);
+    expectWindow(lastWindow(host.windowChange), 0.5, 1);
+  });
+});
+
 // ── Stylesheet contract ─────────────────────────────────────────────────
 const componentDir = dirname(fileURLToPath(import.meta.url));
 
@@ -1511,6 +1723,17 @@ describe("HkRangeRibbon stylesheet contract", () => {
     expect(css).toContain(".hk-range-ribbon-overview-gutter");
   });
 
+  it("makes the detail layer a plain column container for the lane list", () => {
+    const detail = ruleBody(css, ".hk-range-ribbon-detail");
+    expect(declaration(detail, "display")).toBe("flex");
+    expect(declaration(detail, "flex-direction"), "the lane list keeps its own column").toBe(
+      "column",
+    );
+    // The wrapper adds no rhythm of its own: the lanes keep their gap.
+    expect(detail, "the wrapper owns no gap").not.toContain("gap:");
+    expect(declaration(ruleBody(css, ".hk-range-ribbon-lanes"), "gap")).toBe("var(--space-2)");
+  });
+
   it("anchors the tip inward at the track edges", () => {
     const tip = ruleBody(css, ".hk-range-ribbon-tip");
     expect(declaration(tip, "text-align")).toBe("start");

package/src/components/HkRangeRibbon.tsx

@@ -6,17 +6,41 @@ import HIconButton from "./HkIconButton";
 import "./HkRangeRibbon.scss";
 
 /**
- * HkRangeRibbon — the generic multi-lane "sequence ribbon" with a brushed
- * observation window.
+ * HkRangeRibbon — the generic sequence-ribbon waterfall: two explicit layers
+ * projected from ONE host-supplied sequence.
  *
- * One thin OVERVIEW strip paints the whole sequence (fractions of the full
- * domain), a highlight marks the active window and the outside is dimmed;
- * below it, every lane renders its segments. With no window the lanes are
- * the full domain; with a window the lanes zoom to it — only segments that
- * intersect the window survive, clipped at the edges and re-normalized to
- * the window. The overview NEVER clips: it is the only place the full
- * domain stays visible. The overview shares the lanes' label column, so a
- * bar at x% sits at the same inline position on both surfaces.
+ * The ribbon owns no content vocabulary. `lanes` is the consumer's row
+ * structure and `segments` are its parts, each fed in ABSOLUTE fractions of
+ * the whole progress (0..1). Both layers derive their x from that same
+ * number, which is what keeps them mutually legible:
+ *
+ *   · data-layer="minimap" — the top, compact strip. It paints every lane's
+ *     segments across the FULL domain and never clips, so the window stays
+ *     locatable; the window frame, the two outside scrims, both edge handles
+ *     and the reset button ride on it, and it owns the brush surface.
+ *   · data-layer="detail" — the lower, taller lane list focused on the
+ *     selected window: a window of [0.35, 0.67] starts the detail at 35% and
+ *     ends it at 67% of the whole progress, because only segments that
+ *     intersect the window survive, clipped at its edges and re-normalized to
+ *     the track. With no window the detail is the full domain.
+ *
+ * The minimap shares the lanes' label column (an empty gutter), so both
+ * layers always start at the same inline x. Their x% agree only in the
+ * FULL-DOMAIN view: a window re-normalizes the detail against the selected
+ * sub-domain, and a headroom compresses the minimap by `1 + headroom`.
+ *
+ * HEADROOM: a host whose sequence is read against more than 100% (a 110%
+ * budget, a "10% still unknown" tail) reserves that space with `headroom`, a
+ * fraction clamped to 0..1. The minimap axis is then `1 + headroom` wide and
+ * every minimap x is `fraction / span`: content 100% sits at 100/110 ≈ 90.9%
+ * and the tail stays blank. The detail layer NEVER sees the headroom — its
+ * axis is always the content window mapped to 0..100%, so a zoomed detail is
+ * never polluted by reserved space. Windows and every emitted value stay
+ * CONTENT fractions in 0..1; a pointer in the blank tail clamps to content
+ * 100%, because the tail is padding, not selectable progress. `minimal` mode
+ * suppresses the minimap lane rows and the whole detail layer (its bare bar
+ * still lives in the overview container), so it ignores the headroom
+ * entirely and stays on the content axis.
  *
  * Editing: drag on the strip to brush a new window, drag either edge handle
  * to resize it, and reset back to the full domain — the reset button, a
@@ -224,6 +248,31 @@ function windowedBox(placed: PlacedSegment, win: WindowRange): SegmentBox | null
   };
 }
 
+/** The minimap projection for one CONTENT scalar — a coordinate or a length:
+ *  its AXIS value is `value / span` (span = 1 + headroom). This pair
+ *  (`projectToAxis` + `axisBox`) is the ONLY place the minimap axis is
+ *  computed, and every axis value is one of them: the overview segments, the
+ *  window frame and the before scrim go through `axisBox`; both handles and
+ *  the after scrim's left edge go through `projectToAxis`. The after scrim's
+ *  width is `1 - its left`, which is what makes it reach the axis end.
+ *  `fractionFrom` is the inverse (axis → content) for pointer input. The
+ *  detail layer is never projected — its axis is the window itself, so none
+ *  of this may leak into `windowedBox` / `fullDomainBox`. */
+function projectToAxis(value: number, span: number): number {
+  return value / span;
+}
+
+/** Project a CONTENT box onto the minimap's `1 + headroom` axis: the content
+ *  is compressed into the left 1/span of the strip and the reserved tail
+ *  stays empty. Delegates to `projectToAxis` so the axis arithmetic has one
+ *  home. The detail layer is never projected. */
+function axisBox(box: SegmentBox, span: number): SegmentBox {
+  return {
+    left: projectToAxis(box.left, span),
+    width: projectToAxis(box.width, span),
+  };
+}
+
 /** Pointer travel (px) that turns a press into a brush; below it a click
  *  with sub-pixel jitter must not zoom to a hairline window. Touch taps
  *  drift much further than a mouse press (4–6px is normal), so touch gets
@@ -260,10 +309,22 @@ export default defineComponent({
     windowEnabled: { type: Boolean, default: true },
     /** Narrowest window the ribbon will produce, in domain fractions. */
     minWindow: { type: Number, default: MIN_WINDOW_FALLBACK },
+    /** Trailing blank axis the MINIMAP reserves after content 100%, in
+     *  content fractions (0..1). The axis span is `1 + headroom`, so 0.1
+     *  reads the sequence against a 110% budget: content 100% lands at
+     *  ~90.9% of the strip and the last ~9.1% stays blank. Sanitized —
+     *  non-finite / negative means no headroom, above 1 caps at 1. This is a
+     *  MINIMAP-only axis: the detail layer ignores it (its axis is always
+     *  the window), `minimal` mode suppresses the minimap lane rows so there
+     *  is nothing to reserve (its bare bar stays on the content axis), and
+     *  windows plus every emitted value stay content fractions. */
+    headroom: { type: Number, default: 0 },
     /** Wave (2026-11-06 raw-records five): MINIMAL MODE — a bare dual-handle
-     *  range bar. No lane rows, no overview minimap, no label gutter; the
-     *  strip spans the full width and its track uses muted-based tokens
-     *  (the surface-based track read whitish inside dark phone modals).
+     *  range bar: no lane rows and no detail layer (the strip still lives in
+     *  the overview container, which keeps data-layer="minimap"), no label
+     *  gutter. The strip spans the full width and its track uses muted-based
+     *  tokens (the surface-based track read whitish inside dark phone
+     *  modals).
      *  The grips paint only for a NON-null window, so an uncontrolled
      *  minimal bar starts as a bare track; a host that wants the "default =
      *  everything selected" reading feeds the controlled window `[0, 1]`
@@ -292,6 +353,21 @@ export default defineComponent({
       return Number.isFinite(raw) && raw > 0 ? Math.min(raw, 1) : MIN_WINDOW_FALLBACK;
     });
 
+    /** Sanitized trailing headroom: a non-finite or negative value is no
+     *  headroom at all, and more than a full domain of padding is capped
+     *  (the axis never exceeds 2× the content). */
+    const headroom = computed(() => {
+      const raw = Number(props.headroom);
+      return Number.isFinite(raw) && raw > 0 ? Math.min(raw, 1) : 0;
+    });
+
+    /** Width of the minimap's axis in content fractions. Every minimap x is
+     *  divided by it; the detail layer never is. `minimal` mode suppresses
+     *  the lane rows and the detail layer (its bare bar still lives in the
+     *  overview container), so it ignores the headroom and keeps the content
+     *  axis — 100% stays at the right edge. */
+    const axisSpan = computed(() => (props.minimal ? 1 : 1 + headroom.value));
+
     /** A supplied `window` prop (even null) is the controlled contract; no
      *  prop at all means "keep your own state". */
     const controlled = computed(() => props.window !== undefined);
@@ -376,12 +452,18 @@ export default defineComponent({
       return true;
     }
 
+    /** Pointer x → absolute CONTENT fraction (0..1 of the real progress).
+     *  The pointer reads as a fraction of the strip's WHOLE width — the
+     *  axis, headroom included — so the reading is scaled by the span and
+     *  clamped: a press in the blank tail lands on content 100% instead of
+     *  inventing progress the host never declared. This is the only
+     *  axis→content conversion in the component. */
     function fractionFrom(clientX: number): number | null {
       const strip = stripRef.value;
       if (!strip) return null;
       const rect = strip.getBoundingClientRect();
       if (!(rect.width > 0)) return null;
-      return clamp01((clientX - rect.left) / rect.width);
+      return clamp01(((clientX - rect.left) / rect.width) * axisSpan.value);
     }
 
     function brushTo(fraction: number): void {
@@ -569,7 +651,8 @@ export default defineComponent({
     // to its own label; the overview gutter has no text to size from — a
     // hidden-probe attempt measured misaligned in real Chrome). Measuring
     // the widest rendered label and publishing it as the shared var gives
-    // BOTH surfaces the same resolved column: adaptive and aligned.
+    // BOTH surfaces the same resolved column, so they start at the same
+    // inline x: adaptive and aligned.
     const rootRef = ref<HTMLElement | null>(null);
     const pinnedCol = ref<string | null>(null);
     /** TWO-PHASE measure: FREE the column first. A pinned px width clips
@@ -698,6 +781,19 @@ export default defineComponent({
         byLane.get(placed.segment.lane)?.push(placed);
       }
 
+      // Minimap geometry, content → axis (projected through the two helpers
+      // only). The after scrim runs to the AXIS end, tail included: left is
+      // the projection of the window end and width is `1 - left`, whereas
+      // `1 - win[1]` would leave the reserved tail undimmed and read as
+      // progress the host still owes.
+      const span = axisSpan.value;
+      const minimapFrame = win ? axisBox({ left: win[0], width: win[1] - win[0] }, span) : null;
+      const minimapBefore = win ? axisBox({ left: 0, width: win[0] }, span) : null;
+      const minimapAfterLeft = win ? projectToAxis(win[1], span) : 0;
+      const minimapAfter = win
+        ? { left: minimapAfterLeft, width: 1 - minimapAfterLeft }
+        : null;
+
       const strip = (
         <div
           ref={stripRef}
@@ -730,12 +826,14 @@ export default defineComponent({
           onKeydown={onStripKeyDown}
         >
           {/* The overview paints the FULL domain only — it never follows
-              the zoom, so the window's position stays locatable. */}
+              the zoom, so the window's position stays locatable. Its x-axis
+              is the content plus the reserved headroom, so every bar here is
+              projected by `axisBox`. */}
           <div class="hk-range-ribbon-overview-lanes" aria-hidden="true">
             {!props.minimal && lanes.value.map((lane) => (
               <div class="hk-range-ribbon-overview-row" key={lane.key} data-lane={lane.key}>
                 {(byLane.get(lane.key) ?? []).map((placed) => {
-                  const box = fullDomainBox(placed);
+                  const box = axisBox(fullDomainBox(placed), span);
                   return (
                     <div
                       key={placed.segment.id}
@@ -755,18 +853,18 @@ export default defineComponent({
               <div
                 class="hk-range-ribbon-scrim"
                 data-side="before"
-                style={{ left: "0%", width: percent(win[0]) }}
+                style={{ left: percent(minimapBefore!.left), width: percent(minimapBefore!.width) }}
               />
               <div
                 class="hk-range-ribbon-scrim"
                 data-side="after"
-                style={{ left: percent(win[1]), width: percent(1 - win[1]) }}
+                style={{ left: percent(minimapAfter!.left), width: percent(minimapAfter!.width) }}
               />
               <div
                 class="hk-range-ribbon-window"
                 style={{
-                  left: percent(win[0]),
-                  width: percent(win[1] - win[0]),
+                  left: percent(minimapFrame!.left),
+                  width: percent(minimapFrame!.width),
                 }}
               />
             </>
@@ -783,15 +881,19 @@ export default defineComponent({
           data-window-enabled={props.windowEnabled ? "true" : "false"}
           onKeydown={onRootKeyDown}
         >
-          {/* The overview is laid out on the SAME label column as the lanes
-              (empty gutter first), so x% means the same inline position on
-              both surfaces — the strip can be used to locate a bar. */}
-          <div class="hk-range-ribbon-overview">
+          {/* LAYER 1 — the minimap: the full domain, the brush surface, the
+              window chrome. It shares the lanes' label column (an empty
+              gutter first), so both layers always start at the same inline
+              x; their x% agree only in the full-domain view (a window
+              re-normalizes the detail, a headroom compresses the minimap by
+              `1/span`). */}
+          <div class="hk-range-ribbon-overview" data-layer="minimap">
             {/* The gutter's width IS the shared label column: the
                 component JS-measures the widest rendered label and
                 publishes it on the root (two-phase free/measure/pin), so
-                this empty cell keeps the strip's x% aligned with the
-                lanes' x% at any label width. */}
+                this empty cell keeps both layers' inline START aligned at
+                any label width (their x% only agree in the full-domain
+                view, with no headroom). */}
             <span class="hk-range-ribbon-overview-gutter" aria-hidden="true" />
             <div class="hk-range-ribbon-overview-field">
               {strip}
@@ -808,7 +910,7 @@ export default defineComponent({
                     aria-valuemax={percentNumber(win[1] - minWidth.value)}
                     aria-valuenow={percentNumber(win[0])}
                     aria-valuetext={percentText(win[0])}
-                    style={{ left: percent(win[0]) }}
+                    style={{ left: percent(projectToAxis(win[0], span)) }}
                     onPointerdown={(event: PointerEvent) => onHandlePointerDown("start", event)}
                     onKeydown={(event: KeyboardEvent) => onHandleKeyDown("start", event)}
                   />
@@ -823,7 +925,7 @@ export default defineComponent({
                     aria-valuemax={100}
                     aria-valuenow={percentNumber(win[1])}
                     aria-valuetext={percentText(win[1])}
-                    style={{ left: percent(win[1]) }}
+                    style={{ left: percent(projectToAxis(win[1], span)) }}
                     onPointerdown={(event: PointerEvent) => onHandlePointerDown("end", event)}
                     onKeydown={(event: KeyboardEvent) => onHandleKeyDown("end", event)}
                   />
@@ -866,21 +968,28 @@ export default defineComponent({
               </span>
             )}
           </div>
+          {/* LAYER 2 — the detail: the same segments, focused. With a window
+              each bar is clipped to it and re-normalized to the track (so a
+              [0.35, 0.67] window spans 0..100% here); with no window it is
+              the full domain. The headroom is deliberately absent: this axis
+              is the selected content, never the reserved padding. */}
           {!props.minimal && (
-          <div class="hk-range-ribbon-lanes">
-            {lanes.value.map((lane) => (
-              <div class="hk-range-ribbon-lane" key={lane.key} data-lane={lane.key}>
-                <span class="hk-range-ribbon-lane-label" title={lane.label}>
-                  {lane.label}
-                </span>
-                <div class="hk-range-ribbon-lane-track" role="group" aria-label={lane.label}>
-                  {(byLane.get(lane.key) ?? []).map((placed) => {
-                    const box = win ? windowedBox(placed, win) : fullDomainBox(placed);
-                    return box ? renderSegment(placed, box) : null;
-                  })}
+          <div class="hk-range-ribbon-detail" data-layer="detail">
+            <div class="hk-range-ribbon-lanes">
+              {lanes.value.map((lane) => (
+                <div class="hk-range-ribbon-lane" key={lane.key} data-lane={lane.key}>
+                  <span class="hk-range-ribbon-lane-label" title={lane.label}>
+                    {lane.label}
+                  </span>
+                  <div class="hk-range-ribbon-lane-track" role="group" aria-label={lane.label}>
+                    {(byLane.get(lane.key) ?? []).map((placed) => {
+                      const box = win ? windowedBox(placed, win) : fullDomainBox(placed);
+                      return box ? renderSegment(placed, box) : null;
+                    })}
+                  </div>
                 </div>
-              </div>
-            ))}
+              ))}
+            </div>
           </div>
           )}
         </div>