@celestia-island/hikari 0.55.298 → 0.55.299

package/package.json

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

package/src/components/HkModal.test.tsx

@@ -660,4 +660,158 @@ describe("HkModal Escape precedence", () => {
       document.removeEventListener("keydown", pageListener);
     }
   });
+
+  it("does not close a non-closable window on a consumed Escape, and does not swallow it", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const open = ref(true);
+    const emitted: boolean[] = [];
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, {
+            modelValue: open.value,
+            closable: false,
+            title: "Locked",
+            "onUpdate:modelValue": (v: boolean) => { emitted.push(v); open.value = v; },
+          }, {
+            default: () => h("div", {
+              class: "escape-owner",
+              onKeydown: (e: KeyboardEvent) => {
+                if (e.key === "Escape") e.preventDefault();
+              },
+            }, "nested control"),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await vi.waitFor(() => {
+      expect(document.body.querySelector(".escape-owner")).not.toBeNull();
+    });
+    const owner = document.body.querySelector<HTMLElement>(".escape-owner")!;
+
+    const pageHits: string[] = [];
+    const pageListener = (e: KeyboardEvent) => {
+      if (e.key === "Escape") pageHits.push("escape");
+    };
+    document.addEventListener("keydown", pageListener);
+    try {
+      const consumed = new KeyboardEvent("keydown", {
+        key: "Escape",
+        bubbles: true,
+        cancelable: true,
+      });
+      owner.dispatchEvent(consumed);
+      await nextTick();
+      expect(consumed.defaultPrevented, "the nested control consumed the key").toBe(true);
+      expect(emitted, "a non-closable window never emits on Escape").toEqual([]);
+      expect(open.value).toBe(true);
+      // Current semantics: the precedence guard returns before the close path
+      // and does NOT stopPropagation for a non-closable window, so page-level
+      // listeners still see the key.
+      expect(pageHits, "a non-closable window must not swallow the key").toEqual(["escape"]);
+    } finally {
+      document.removeEventListener("keydown", pageListener);
+    }
+  });
+
+  it("leaves a bare Escape to the host when the window is not closable", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const open = ref(true);
+    const emitted: boolean[] = [];
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, {
+            modelValue: open.value,
+            closable: false,
+            title: "Locked",
+            "onUpdate:modelValue": (v: boolean) => { emitted.push(v); open.value = v; },
+          }, {
+            default: () => h("div", "content"),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await vi.waitFor(() => {
+      expect(document.body.querySelector(".hk-modal-content")).not.toBeNull();
+    });
+    const content = document.body.querySelector<HTMLElement>(".hk-modal-content")!;
+
+    const pageHits: string[] = [];
+    const pageListener = (e: KeyboardEvent) => {
+      if (e.key === "Escape") pageHits.push("escape");
+    };
+    document.addEventListener("keydown", pageListener);
+    try {
+      const bare = new KeyboardEvent("keydown", {
+        key: "Escape",
+        bubbles: true,
+        cancelable: true,
+      });
+      content.dispatchEvent(bare);
+      await nextTick();
+      expect(emitted, "a non-closable window must stay open").toEqual([]);
+      expect(open.value).toBe(true);
+      expect(pageHits, "the host still gets the key").toEqual(["escape"]);
+      expect(bare.defaultPrevented, "and the window did not consume it").toBe(false);
+    } finally {
+      document.removeEventListener("keydown", pageListener);
+    }
+  });
+
+  it("keeps the Tab focus trap working when a nested control consumes Tab", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, {
+            modelValue: true,
+            closable: false,
+            title: "Trap",
+          }, {
+            default: () => h("div", {
+              class: "tab-owner",
+              onKeydown: (e: KeyboardEvent) => {
+                if (e.key === "Tab") e.preventDefault();
+              },
+            }, [
+              h("button", { class: "tab-first" }, "first"),
+              h("button", { class: "tab-last" }, "last"),
+            ]),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await vi.waitFor(() => {
+      expect(document.body.querySelector(".tab-last")).not.toBeNull();
+    });
+    const first = document.body.querySelector<HTMLButtonElement>(".tab-first")!;
+    const last = document.body.querySelector<HTMLButtonElement>(".tab-last")!;
+    const owner = document.body.querySelector<HTMLElement>(".tab-owner")!;
+
+    last.focus();
+    expect(document.activeElement, "the last focusable holds focus").toBe(last);
+
+    // A nested control consumes Tab; the focus trap must still run. This pins
+    // the defaultPrevented guard INSIDE the Escape branch: hoisting it to the
+    // top of the handler would silently disable wrapping for exactly this
+    // case.
+    owner.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Tab", bubbles: true, cancelable: true }),
+    );
+    await nextTick();
+    expect(document.activeElement, "focus wraps back to the first focusable").toBe(first);
+  });
 });

package/src/components/HkRangeRibbon.barrel.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import {
   HkRangeRibbon,
+  normalizeHkRangeWindow,
   type RibbonLane,
   type RibbonSegment,
   type RibbonStatus,
@@ -22,6 +23,14 @@ describe("the public barrel", () => {
     expect(HkRangeRibbon.name).toBe("HkRangeRibbon");
   });
 
+  it("re-exports the range-window normalizer hosts share", () => {
+    expect(typeof normalizeHkRangeWindow, "normalizeHkRangeWindow must be re-exported").toBe(
+      "function",
+    );
+    expect(normalizeHkRangeWindow([0.7, 0.3])).toEqual([0.3, 0.7]);
+    expect(normalizeHkRangeWindow(null)).toBeNull();
+  });
+
   it("re-exports the ribbon's public types", () => {
     // Type-only exports vanish at runtime, so each one is CONSUMED here: a
     // dropped `type Ribbon*` line fails vue-tsc on this file instead of

package/src/components/HkRangeRibbon.scss

@@ -12,7 +12,9 @@
    the reset chip clears the edge handle (right: 4px = the handle's
    half-width, so a handle at 0% / 100% is never covered).
 
-   Every colour/size comes from hikari theme tokens; the only motion is the
+   Colours and spacing come from hikari theme tokens; a few geometry values
+   (the 32px strip, the 8px grip, the 2px min-width floor) are deliberate
+   literals pinned by the contract, not token drift. The only motion is the
    pending-segment breathe, registered in animation/registerAnimations.ts. */
 
 .hk-range-ribbon {

package/src/components/HkRangeRibbon.test.tsx

@@ -6,7 +6,11 @@ import { compile } from "sass";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref, type Ref } from "vue";
 
-import HkRangeRibbon, { type RibbonLane, type RibbonSegment } from "./HkRangeRibbon";
+import HkRangeRibbon, {
+  normalizeHkRangeWindow,
+  type RibbonLane,
+  type RibbonSegment,
+} from "./HkRangeRibbon";
 import { setLocale } from "../i18n/context";
 import jaBundle from "../i18n/locales/ja/components.json";
 
@@ -310,6 +314,50 @@ describe("HkRangeRibbon full domain", () => {
   });
 });
 
+// ── Exported normalizer / component parity ──────────────────────────────
+describe("HkRangeRibbon window normalizer parity", () => {
+  it("keeps the component on the exported helper (source contract)", () => {
+    // The rendered-parity cases below are DIVERGENCE detectors: a
+    // byte-identical inlined copy of the algorithm renders the same window
+    // and passes them. This source pin is the CALL-SITE guard — the
+    // component must keep CALLING the exported normalizer rather than
+    // growing a private copy again.
+    const tsx = readFileSync(resolve(componentDir, "HkRangeRibbon.tsx"), "utf8");
+    expect(tsx).toMatch(/return normalizeHkRangeWindow\(source, minWidth\.value\)/);
+  });
+
+  it("renders exactly the window the exported helper returns", () => {
+    const rawWindows: Array<[number, number]> = [
+      [0.7, 0.3],
+      [0.5, 0.5],
+      [1.2, 1.5],
+      [-0.5, -0.2],
+      [1, 1],
+      [0.49, 0.51],
+    ];
+    for (const raw of rawWindows) {
+      const normalized = normalizeHkRangeWindow(raw);
+      expect(normalized, `${raw} normalizes`).not.toBeNull();
+
+      const root = mountRibbon({ window: raw });
+      expect(root.hasAttribute("data-windowed"), `${raw} is windowed`).toBe(true);
+      const highlight = root.querySelector<HTMLElement>(".hk-range-ribbon-window")!;
+      expect(boxOf(highlight).left, `${raw} left`).toBeCloseTo(normalized![0] * 100, 4);
+      expect(boxOf(highlight).width, `${raw} width`).toBeCloseTo(
+        (normalized![1] - normalized![0]) * 100,
+        4,
+      );
+
+      // Feeding the helper's output back in is idempotent — the rendered
+      // box is byte-identical, which is what lets a host pass either the raw
+      // or the normalized value into the same prop.
+      const again = mountRibbon({ window: [...normalized!] as [number, number] });
+      const againHighlight = again.querySelector<HTMLElement>(".hk-range-ribbon-window")!;
+      expect(boxOf(againHighlight), `${raw} idempotent`).toEqual(boxOf(highlight));
+    }
+  });
+});
+
 // ── Windowed view: clipping ─────────────────────────────────────────────
 describe("HkRangeRibbon windowed view", () => {
   it("clips and re-normalizes only intersecting segments — the only clipping site", () => {
@@ -802,6 +850,27 @@ describe("HkRangeRibbon reset", () => {
     expect(second.defaultPrevented).toBe(true);
   });
 
+  it("cancels an in-flight brush with Escape and consumes the key", async () => {
+    const host = mountHost(null);
+    const { strip, x } = stubStrip(host.root);
+    // Pointer down and stay inside the brush slop: no window exists yet.
+    pointer("pointerdown", x(0.5), strip);
+    pointer("pointermove", x(0.5) + 2, strip); // 2px < the 3px mouse slop
+    await nextTick();
+    expect(host.windowChange, "still inside the slop").not.toHaveBeenCalled();
+
+    const escape = keydown(strip, "Escape");
+    await nextTick();
+    expect(escape.defaultPrevented, "cancelling a live gesture consumes the key").toBe(true);
+    expect(host.windowChange, "cancelling is not a window change").not.toHaveBeenCalled();
+
+    // PROBE: the gesture is gone — a later move must not revive the brush.
+    pointer("pointermove", x(0.8), strip);
+    await nextTick();
+    expect(host.windowChange, "no brush may be revived after the cancel").not.toHaveBeenCalled();
+    expect(host.root.hasAttribute("data-windowed")).toBe(false);
+  });
+
   it("drops an in-flight brush when a reset interrupts it", async () => {
     const host = mountHost(null);
     const { strip, x } = stubStrip(host.root);
@@ -1107,6 +1176,38 @@ describe("HkRangeRibbon a11y and i18n", () => {
     expect(hint!.textContent).toContain("Resize window");
   });
 
+  it("announces a narrow window with a decimal so it differs from the full domain", () => {
+    const full = mountRibbon({ window: null });
+    expect(
+      full.querySelector<HTMLElement>(".hk-range-ribbon-strip")!.getAttribute("aria-valuetext"),
+      "the full domain keeps the classic integer text",
+    ).toBe("0% – 100%");
+
+    const narrow = mountRibbon({ window: [0.004, 0.996] });
+    const strip = narrow.querySelector<HTMLElement>(".hk-range-ribbon-strip")!;
+    const text = strip.getAttribute("aria-valuetext")!;
+    expect(text, "a fractional window keeps one decimal").toContain("0.4%");
+    expect(text).toContain("99.6%");
+    expect(text, "rounding to integers would be indistinguishable").not.toBe("0% – 100%");
+    expect(strip.getAttribute("aria-valuenow"), "valuenow uses the same precision").toBe("0.4");
+
+    const start = narrow.querySelector<HTMLElement>('[data-edge="start"]')!;
+    const end = narrow.querySelector<HTMLElement>('[data-edge="end"]')!;
+    expect(start.getAttribute("aria-valuenow")).toBe("0.4");
+    expect(start.getAttribute("aria-valuetext")).toBe("0.4%");
+    expect(end.getAttribute("aria-valuetext")).toBe("99.6%");
+    // The handle bounds share the precision: at a razor-narrow window an
+    // integer-rounded max (97) would contradict a decimal valuenow (97.5).
+    expect(start.getAttribute("aria-valuemax"), "start max keeps the decimal").toBe("97.6");
+    expect(end.getAttribute("aria-valuemin"), "end min keeps the decimal").toBe("2.4");
+
+    // An integer window keeps the integer text the earlier pins assert.
+    const integer = mountRibbon({ window: [0.2, 0.6] });
+    expect(
+      integer.querySelector<HTMLElement>(".hk-range-ribbon-strip")!.getAttribute("aria-valuetext"),
+    ).toBe("20% – 60%");
+  });
+
   it("localizes the labels and hint from the active locale bundle", async () => {
     await setLocale("ja");
     const root = mountRibbon({ window: [0.2, 0.6] });
@@ -1293,8 +1394,12 @@ describe("HkRangeRibbon stylesheet contract", () => {
     );
     expect(declaration(handle, "cursor")).toBe("ew-resize");
     expect(handle).toContain("touch-action: none");
+    // Require the UNPREFIXED declaration at a declaration boundary: the old
+    // /user-select:\s*none/ also matched "-webkit-user-select: none", so a
+    // hypothetical polyfill that emitted only the prefixed property would
+    // satisfy the pin while the standard property was gone.
     expect(handle, "a handle drag cannot start a text selection").toMatch(
-      /user-select:\s*none/,
+      /(?:^|[;{])\s*user-select\s*:\s*none/,
     );
 
     // A clipped 2px sliver must still be visible.

package/src/components/HkRangeRibbon.tsx

@@ -87,21 +87,60 @@ function clamp01(value: number): number {
   return value < 0 ? 0 : value > 1 ? 1 : value;
 }
 
+/** Percent with adaptive precision. An integer percentage stays an integer —
+ *  the full domain must keep announcing the classic "0% – 100%" — while a
+ *  fractional one keeps a decimal, so a narrow window ("0.4% – 99.6%") is
+ *  distinguishable from the full domain instead of rounding to the same
+ *  text. */
+function percentNumber(fraction: number): number {
+  const percentage = fraction * 100;
+  const rounded = Math.round(percentage);
+  return Math.abs(percentage - rounded) < 1e-9 ? rounded : Number(percentage.toFixed(1));
+}
+
+function percentText(fraction: number): string {
+  return `${percentNumber(fraction)}%`;
+}
+
 /** Inline left/width pair — percentages are deterministic in tests and do
  *  not depend on layout measurement for rendering. */
 function percent(fraction: number): string {
   return `${Number((fraction * 100).toFixed(4))}%`;
 }
 
-/** Normalize a host window: swap inverted ranges, clamp to the domain,
- *  ignore non-finite or malformed input (that means "no window"), and never
- *  return a window narrower than `minWidth`. */
-function normalizeWindow(input: unknown, minWidth: number): WindowRange | null {
+/**
+ * Normalize a host-supplied window into the ribbon's contract.
+ *
+ * This is the ONE implementation the component and its hosts share — the
+ * component's former private helper, identical except the min-guard, which
+ * absorbs the component's existing sanitizer (that helper had no other
+ * observers, so this is not a behaviour change). A consumer that keeps its
+ * own rendering/filter driven by the same window (chest's trace model builds
+ * its row filter from these fractions) must import this instead of mirroring
+ * the algorithm: a copy forks silently the moment the algorithm or the 0.02
+ * default changes upstream.
+ *
+ * @param input Any host window value. `null` / `undefined`, a non-array, an
+ *   array with fewer than two entries, or either member non-finite all mean
+ *   "no window" and return `null` (the host reads that as the full domain).
+ * @param minWidth Narrowest window the ribbon will produce, defaulting to
+ *   0.02. Clamped to [0, 1]; a non-finite or non-positive value falls back
+ *   to the default.
+ * @returns An ordered, domain-clamped `[start, end]` pair of full-domain
+ *   fractions, never narrower than `minWidth`, or `null` for "no window".
+ */
+export function normalizeHkRangeWindow(
+  input: unknown,
+  minWidth: number = MIN_WINDOW_FALLBACK,
+): [number, number] | null {
   if (input == null || !Array.isArray(input) || input.length < 2) return null;
   const first = Number(input[0]);
   const second = Number(input[1]);
   if (!Number.isFinite(first) || !Number.isFinite(second)) return null;
-  const min = Math.min(Math.max(minWidth, 0), 1);
+  const min =
+    Number.isFinite(minWidth) && minWidth > 0
+      ? Math.min(minWidth, 1)
+      : MIN_WINDOW_FALLBACK;
   let lo = clamp01(Math.min(first, second));
   let hi = clamp01(Math.max(first, second));
   if (hi - lo < min) {
@@ -142,8 +181,10 @@ function intersectsWindow(placed: PlacedSegment, win: WindowRange): boolean {
 }
 
 /** Clamp every segment into the domain; drop NaN/unusable entries (a broken
- *  row must not take the whole ribbon down). A zero-length segment is kept —
- *  it renders as a tick thanks to the sheet's min-width. */
+ *  row must not take the whole ribbon down). A zero-length segment is kept:
+ *  the LANE sheet gives it a 2px min-width floor under `box-sizing:
+ *  border-box`, so a lane tick is exactly that 2px (the 1px borders sit
+ *  inside it); the overview twin draws 1px. */
 function placeSegments(segments: RibbonSegment[] | undefined): PlacedSegment[] {
   if (!Array.isArray(segments)) return [];
   const placed: PlacedSegment[] = [];
@@ -254,7 +295,7 @@ export default defineComponent({
     const activeWindow = computed<WindowRange | null>(() => {
       if (!props.windowEnabled) return null;
       const source = controlled.value ? props.window : internalWindow.value;
-      return normalizeWindow(source, minWidth.value);
+      return normalizeHkRangeWindow(source, minWidth.value);
     });
 
     const lanes = computed<RibbonLane[]>(() =>
@@ -402,7 +443,12 @@ export default defineComponent({
       if (!props.windowEnabled || gesture) return;
       if (event.pointerType === "mouse" && event.button !== 0) return;
       if (!activeWindow.value) return;
-      // The handle sits over the strip: never start a brush underneath it.
+      // The handles are SIBLINGS of the strip, not children of it, so this
+      // press never reaches the strip's brush handler in the first place.
+      // The stopPropagation below keeps the press out of BUBBLE-phase
+      // listeners in the consuming host — none exist in-package today (every
+      // in-package document-level pointerdown listener is capture-phase and
+      // still sees the press).
       event.stopPropagation();
       gesture = { kind: "edge", pointerId: event.pointerId, edge };
       (event.currentTarget as HTMLElement).setPointerCapture?.(event.pointerId);
@@ -470,10 +516,17 @@ export default defineComponent({
     function onRootKeyDown(event: KeyboardEvent): void {
       if (!props.windowEnabled) return;
       // Escape resets from anywhere inside the ribbon — but only a REAL reset
-      // consumes the key: with no window, Escape must still reach the host
-      // (a dialog closes on it while focus sits in here).
+      // consumes the key: with no window AND no live gesture, Escape still
+      // reaches the host (a dialog closes on it while focus sits in here).
       if (event.key === "Escape") {
-        if (resetWindow()) event.preventDefault();
+        // An in-flight drag is a real, unsaved gesture: cancel it even before
+        // the first commit (a brush still inside the slop has produced no
+        // window yet, so the reset path alone would find nothing to do).
+        // Cancelling consumes the key on its own; with NO gesture and no
+        // window the key is still handed back to the host.
+        const hadGesture = gesture !== null;
+        gesture = null;
+        if (resetWindow() || hadGesture) event.preventDefault();
         return;
       }
       if (event.key !== "Home") return;
@@ -582,10 +635,8 @@ export default defineComponent({
           aria-disabled={props.windowEnabled ? undefined : "true"}
           aria-valuemin={0}
           aria-valuemax={100}
-          aria-valuenow={Math.round((win ? win[0] : 0) * 100)}
-          aria-valuetext={`${Math.round((win ? win[0] : 0) * 100)}% – ${Math.round(
-            (win ? win[1] : 1) * 100,
-          )}%`}
+          aria-valuenow={percentNumber(win ? win[0] : 0)}
+          aria-valuetext={`${percentText(win ? win[0] : 0)} – ${percentText(win ? win[1] : 1)}`}
           title={
             props.windowEnabled
               ? t(
@@ -671,9 +722,9 @@ export default defineComponent({
                     tabindex={0}
                     aria-label={t("hikari::ribbon.windowStart", "Window start")}
                     aria-valuemin={0}
-                    aria-valuemax={Math.round((win[1] - minWidth.value) * 100)}
-                    aria-valuenow={Math.round(win[0] * 100)}
-                    aria-valuetext={`${Math.round(win[0] * 100)}%`}
+                    aria-valuemax={percentNumber(win[1] - minWidth.value)}
+                    aria-valuenow={percentNumber(win[0])}
+                    aria-valuetext={percentText(win[0])}
                     style={{ left: percent(win[0]) }}
                     onPointerdown={(event: PointerEvent) => onHandlePointerDown("start", event)}
                     onKeydown={(event: KeyboardEvent) => onHandleKeyDown("start", event)}
@@ -685,10 +736,10 @@ export default defineComponent({
                     aria-orientation="horizontal"
                     tabindex={0}
                     aria-label={t("hikari::ribbon.windowEnd", "Window end")}
-                    aria-valuemin={Math.round((win[0] + minWidth.value) * 100)}
+                    aria-valuemin={percentNumber(win[0] + minWidth.value)}
                     aria-valuemax={100}
-                    aria-valuenow={Math.round(win[1] * 100)}
-                    aria-valuetext={`${Math.round(win[1] * 100)}%`}
+                    aria-valuenow={percentNumber(win[1])}
+                    aria-valuetext={percentText(win[1])}
                     style={{ left: percent(win[1]) }}
                     onPointerdown={(event: PointerEvent) => onHandlePointerDown("end", event)}
                     onKeydown={(event: KeyboardEvent) => onHandleKeyDown("end", event)}

package/src/components/normalizeHkRangeWindow.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+
+import { normalizeHkRangeWindow } from "./HkRangeRibbon";
+
+/**
+ * Public contract of `normalizeHkRangeWindow` — the ONE normalizer the
+ * ribbon and its hosts share.
+ *
+ * Motivation: chest's trace model mirrored this algorithm line-by-line
+ * (including the 0.02 minimum) to filter its rows with the same window. A
+ * mirror like that only has prose pins, so an upstream algorithm/default
+ * change forks the host silently. These pins are the function's contract —
+ * exact tuples, not "close enough" — because hosts bake these numbers into
+ * their own filters.
+ */
+/** Window endpoints at double precision + the contract invariants exactly
+ *  (ordered, in-domain, at least `minWidth` wide). The endpoints of an
+ *  expanded window are arithmetic results (e.g. 0.5 - 0.7/2), so pinning the
+ *  17th significant digit would test IEEE-754, not the contract. */
+function expectWindow(
+  actual: [number, number] | null,
+  expected: [number, number],
+  minWidth = 0.02,
+): void {
+  expect(actual, "a window is returned").not.toBeNull();
+  expect(actual![0], "start").toBeCloseTo(expected[0], 12);
+  expect(actual![1], "end").toBeCloseTo(expected[1], 12);
+  expect(actual![0], "ordered").toBeLessThan(actual![1]);
+  expect(actual![0], "clamped to the domain").toBeGreaterThanOrEqual(0);
+  expect(actual![1], "clamped to the domain").toBeLessThanOrEqual(1);
+  expect(actual![1] - actual![0], "never narrower than minWidth").toBeGreaterThanOrEqual(
+    minWidth - 1e-12,
+  );
+}
+
+describe("normalizeHkRangeWindow", () => {
+  it("returns null for anything that is not a usable window", () => {
+    expect(normalizeHkRangeWindow(null)).toBeNull();
+    expect(normalizeHkRangeWindow(undefined)).toBeNull();
+    // Not an array / not a pair / not finite: all mean "no window".
+    expect(normalizeHkRangeWindow(0.5)).toBeNull();
+    expect(normalizeHkRangeWindow("0.2,0.4")).toBeNull();
+    expect(normalizeHkRangeWindow([])).toBeNull();
+    expect(normalizeHkRangeWindow([0.2])).toBeNull();
+    expect(normalizeHkRangeWindow([Number.NaN, 0.5])).toBeNull();
+    expect(normalizeHkRangeWindow([0.2, Number.POSITIVE_INFINITY])).toBeNull();
+  });
+
+  it("orders inverted windows and clamps them to the domain", () => {
+    expectWindow(normalizeHkRangeWindow([0.7, 0.3]), [0.3, 0.7]);
+    // Both members beyond the end: collapsed to the trailing minimum.
+    expectWindow(normalizeHkRangeWindow([1.2, 1.5]), [0.98, 1]);
+    // Both members before the start: collapsed to the leading minimum.
+    expectWindow(normalizeHkRangeWindow([-0.5, -0.2]), [0, 0.02]);
+  });
+
+  it("expands a degenerate window to the default minimum (0.02)", () => {
+    expectWindow(normalizeHkRangeWindow([0.5, 0.5]), [0.49, 0.51]);
+    // Exactly the minimum width is left alone — no gratuitous expansion.
+    expectWindow(normalizeHkRangeWindow([0.49, 0.51]), [0.49, 0.51]);
+  });
+
+  it("honours a custom minWidth", () => {
+    expectWindow(normalizeHkRangeWindow([0.5, 0.5], 0.2), [0.4, 0.6], 0.2);
+    expectWindow(normalizeHkRangeWindow([0.5, 0.5], 0.7), [0.15, 0.85], 0.7);
+  });
+
+  it("falls back to the default for an unusable minWidth", () => {
+    for (const minWidth of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expectWindow(normalizeHkRangeWindow([0.5, 0.5], minWidth), [0.49, 0.51]);
+    }
+  });
+});

package/src/index.ts

@@ -826,6 +826,7 @@ export { default as HkTagDotRow } from "./components/HkTagDotRow";
 export { default as HkModelCard, type ModelCardTier } from "./components/HkModelCard";
 export {
   default as HkRangeRibbon,
+  normalizeHkRangeWindow,
   type RibbonLane,
   type RibbonSegment,
   type RibbonStatus,