@celestia-island/hikari 0.55.299 → 0.55.301

package/package.json

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

package/src/components/HkIconButton.test.tsx

@@ -122,6 +122,36 @@ describe("HkIconButton", () => {
   });
 });
 
+
+describe("HkIconButton button semantics", () => {
+  it("renders type=button so a form never treats the chrome as a submitter", () => {
+    const c = mountComp(() => h(HkIconButton, { "aria-label": "probe" }));
+    const btn = c.querySelector<HTMLButtonElement>("button")!;
+    expect(btn.getAttribute("type")).toBe("button");
+  });
+
+  it("never overwrites an explicit type", () => {
+    for (const explicit of ["submit", "reset"] as const) {
+      const c = mountComp(() => h(HkIconButton, { "aria-label": "probe", type: explicit } as never));
+      expect(c.querySelector<HTMLButtonElement>("button")!.getAttribute("type")).toBe(explicit);
+    }
+  });
+
+  it("keeps the default when the attribute is explicitly undefined or empty", () => {
+    // The discriminating cases: a pre-fix ordering (default first, attrs
+    // after) elides the attribute for `undefined` and passes an empty
+    // string through — the first is an implicit submitter, the second an
+    // invalid value that ALSO defaults to submit.
+    for (const value of [undefined, null, ""] as const) {
+      const c = mountComp(() => h(HkIconButton, { "aria-label": "probe", type: value } as never));
+      expect(
+        c.querySelector<HTMLButtonElement>("button")!.getAttribute("type"),
+        `type=${JSON.stringify(value)} must fall back to button`,
+      ).toBe("button");
+    }
+  });
+});
+
 /**
  * Static pin for the header-chrome glyph step (user report 2026-09-29:
  * the search / refresh / filter glyphs in the top-right clusters read

package/src/components/HkIconButton.tsx

@@ -61,6 +61,14 @@ export default defineComponent({
         disabled={props.disabled}
         onClick={(e: MouseEvent) => emit("click", e)}
         {...attrs}
+        // A rendered <button> defaults to type=submit, which silently turns
+        // every icon-only control inside a <form> into a submitter. The
+        // family is chrome, never a submitter: default it here, once, so
+        // call sites do not each spread an attribute the component does not
+        // declare. Placed AFTER the attrs spread and guarded with `||` so an
+        // explicit `type` still wins while an explicitly `undefined` one
+        // cannot silently defeat the default (HkButton's idiom).
+        type={((attrs.type as string) || "button") as "button" | "reset" | "submit"}
       >
         <span class="hk-icon-button-icon">
           {slots.icon

package/src/components/HkPillToggleGroup.scss

@@ -95,6 +95,40 @@
     background: rgb(var(--color-primary) / 12%);
   }
 
+  /* Tone channels (2026-11-06): a pill can carry the hue identity of the
+   * thing it filters (the trace chips tint with their lane's token so a
+   * chip, its ribbon segments and its rows share one identity). A tone
+   * re-tints the ACTIVE state only — inactive pills stay muted regardless
+   * of tone. The four hue tones share one alpha (16%); the "muted" tone
+   * rides 18% because it has to read as a neutral wash rather than a hue.
+   * The attribute pair wins on SPECIFICITY ((0,3,0) vs (0,2,0)) — order
+   * independent; they are also written after the plain rule so the source
+   * order agrees with what specificity already decides. */
+  &[data-tone="success"][data-active] {
+    color: rgb(var(--color-success, 14 184 64));
+    background: rgb(var(--color-success, 14 184 64) / 16%);
+  }
+
+  &[data-tone="secondary"][data-active] {
+    color: rgb(var(--color-secondary, 81 154 115));
+    background: rgb(var(--color-secondary, 81 154 115) / 16%);
+  }
+
+  &[data-tone="warning"][data-active] {
+    color: rgb(var(--color-warning, 238 214 119));
+    background: rgb(var(--color-warning, 238 214 119) / 16%);
+  }
+
+  &[data-tone="error"][data-active] {
+    color: rgb(var(--color-error, 247 118 142));
+    background: rgb(var(--color-error, 247 118 142) / 16%);
+  }
+
+  &[data-tone="muted"][data-active] {
+    color: rgb(var(--color-text, 30 30 30));
+    background: rgb(var(--color-muted, 108 108 108) / 18%);
+  }
+
   &:focus-visible {
     outline: 2px solid rgb(var(--color-primary));
     outline-offset: -2px;

package/src/components/HkPillToggleGroup.test.tsx

@@ -1,5 +1,9 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { createApp, h } from "vue";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "sass";
 
 import HkPillToggleGroup from "./HkPillToggleGroup";
 
@@ -175,3 +179,96 @@ describe("HkPillToggleGroup", () => {
     expect(toggled).toEqual([OPTIONS[1].value]);
   });
 });
+
+// ── Tone channel ─────────────────────────────────────────────────────────
+describe("HkPillToggleGroup tone channel", () => {
+  const TONED_OPTIONS = [
+    { value: "input", label: "Input", tone: "success" },
+    { value: "text", label: "Text", tone: "secondary" },
+    { value: "tool", label: "Tool", tone: "warning" },
+    { value: "plain", label: "Plain" },
+    { value: "primary", label: "Primary", tone: "primary" },
+  ] as const;
+
+  it("carries data-tone for non-primary tones and omits it for default/primary", () => {
+    const c = mount(
+      h(HkPillToggleGroup, { label: "Kinds", options: [...TONED_OPTIONS], selected: new Set<string>() }),
+    );
+    const pills = [...c.querySelectorAll<HTMLButtonElement>(".hk-pill-group-pill")];
+    expect(pills[0].getAttribute("data-tone")).toBe("success");
+    expect(pills[1].getAttribute("data-tone")).toBe("secondary");
+    expect(pills[2].getAttribute("data-tone")).toBe("warning");
+    expect(pills[3].hasAttribute("data-tone"), "no tone → no attribute").toBe(false);
+    expect(pills[4].hasAttribute("data-tone"), "primary is the default → no attribute").toBe(false);
+  });
+
+  it("renders the option label alongside the tone attribute", () => {
+    const c = mount(
+      h(HkPillToggleGroup, {
+        label: "Kinds",
+        options: [{ value: "tool", label: "Tool", tone: "warning" }],
+        selected: new Set<string>(["tool"]),
+      }),
+    );
+    const pill = c.querySelector<HTMLButtonElement>(".hk-pill-group-pill")!;
+    expect(pill.textContent?.trim()).toBe("Tool");
+    expect(pill.hasAttribute("data-active")).toBe(true);
+    // Without this the whole channel could be reverted and the test stays green.
+    expect(pill.getAttribute("data-tone")).toBe("warning");
+  });
+
+  it("stylesheet contract: every tone re-tints the ACTIVE state only, after the plain rule", () => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const css = compile(join(here, "HkPillToggleGroup.scss"), { style: "expanded" }).css;
+    const tones = ["success", "secondary", "warning", "error", "muted"] as const;
+    // Same triplets styles/theme/channels.scss defines (light base).
+    const FALLBACKS: Record<(typeof tones)[number], string> = {
+      success: "14 184 64",
+      secondary: "81 154 115",
+      warning: "238 214 119",
+      error: "247 118 142",
+      muted: "108 108 108",
+    };
+    const plainActive = css.indexOf(".hk-pill-group-pill[data-active]");
+    expect(plainActive, "the plain active rule exists").toBeGreaterThan(-1);
+    for (const tone of tones) {
+      // Sass drops quotes around attribute values when expanding
+      // (`[data-status=pending]` — the HkRangeRibbon sheet contract hits
+      // the same formatting), so match the compiled shape.
+      const selector = `.hk-pill-group-pill[data-tone=${tone}][data-active]`;
+      const at = css.indexOf(selector);
+      expect(at, `${selector} compiles`).toBeGreaterThan(-1);
+      // Every tone rule must come AFTER the plain rule: the attribute pair
+      // outranks it, and the source order keeps that dominance explicit.
+      expect(at, `${tone} rule rides after the plain active rule`).toBeGreaterThan(plainActive);
+      // Tone must never repaint an INACTIVE pill: every tone selector has to
+      // carry the attribute pair. A bare `[data-tone=…]` rule would pass the
+      // assertions above while quietly tinting muted pills.
+      expect(css, "no tone rule without [data-active]").not.toMatch(
+        new RegExp(`\\[data-tone=${tone}\\]\\s*\\{`),
+      );
+      const body = css.slice(at, css.indexOf("}", at));
+      expect(body, `${tone} re-tints the ink`).toContain("color:");
+      expect(body, `${tone} re-tints the fill`).toContain("background:");
+      expect(body, `${tone} tint uses its theme token`).toContain(`var(--color-${tone}`);
+      // Presence alone is not enough: the token appears twice (ink + fill),
+      // so swapping one for another hue kept this green (R3 M9/M9b). Pin the
+      // ink and the fill to their own channels — muted is the documented
+      // exception (text ink, muted wash).
+      expect(body, `${tone} INK uses its own channel`).toContain(
+        `color: rgb(var(--color-${tone === "muted" ? "text" : tone}`,
+      );
+      expect(body, `${tone} FILL uses its own channel`).toContain(
+        `background: rgb(var(--color-${tone}`,
+      );
+      // The canonical fallback is what keeps the Rust-side mirror rendering
+      // the same hue without the theme layer — pin the exact triplet.
+      expect(body, `${tone} carries its canonical fallback`).toContain(FALLBACKS[tone]);
+      // Sass's expanded output drops the space before the alpha slash:
+      // `rgb(var(--color-x, t t t)/16%)`.
+      expect(body, `${tone} keeps the house alpha`).toMatch(
+        tone === "muted" ? /\/\s*18%/ : /\/\s*16%/,
+      );
+    }
+  });
+});

package/src/components/HkPillToggleGroup.tsx

@@ -3,6 +3,13 @@ import { defineComponent, h, type PropType, type VNode } from "vue";
 import { useOptionStrip } from "../composables/useOptionStrip";
 import "./HkPillToggleGroup.scss";
 
+/** Semantic tone channel for a pill's ACTIVE tint — the same vocabulary
+ *  the HkRangeRibbon segment family speaks (a filter bar can keep its
+ *  lane-hue identity while riding the shared pill chrome). Omit (or
+ *  "primary") = the default primary tint. A tone recolors the ACTIVE
+ *  state only; inactive pills stay muted regardless of tone. */
+export type HkPillTone = "primary" | "success" | "secondary" | "warning" | "error" | "muted";
+
 /** One toggleable pill of the group. */
 export interface HkPillToggleGroupOption {
   /** Stable identity — the value emitted back through `toggle`. */
@@ -14,6 +21,8 @@ export interface HkPillToggleGroupOption {
    * (never stringified: a raw function child renders as source text,
    * which is exactly the landmine this normalization defuses). */
   icon?: unknown;
+  /** Active-tint hue channel (see {@link HkPillTone}). */
+  tone?: HkPillTone;
 }
 
 /** Normalize an option icon to a renderable vnode. A component (function
@@ -94,6 +103,7 @@ export default defineComponent({
               type="button"
               key={o.value}
               class="hk-pill-group-pill"
+              data-tone={o.tone && o.tone !== "primary" ? o.tone : undefined}
               data-active={props.selected.has(o.value) || undefined}
               aria-pressed={props.selected.has(o.value) ? "true" : "false"}
               onClick={() => emit("toggle", o.value)}

package/src/components/HkRangeRibbon.scss

@@ -9,8 +9,10 @@
    the strip is 32px tall, a handle is an 8px half-overlapping grip
    (translateX(-50%) so `left: 20%` centers it on the window edge), a
    clipped segment keeps a 2px minimum so edge slivers stay visible, and
-   the reset chip clears the edge handle (right: 4px = the handle's
-   half-width, so a handle at 0% / 100% is never covered).
+   the reset button (a standard HkIconButton) clears the edge handle
+   (right: 4px = the handle's half-width, so a handle at 0% / 100% is never
+   covered). The 24px touch-floor seat costs the strip's top-right brush
+   band — the free band below the seat is what remains.
 
    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
@@ -152,7 +154,12 @@
   position: absolute;
   top: 3px;
   bottom: 3px;
-  z-index: 2;
+  // ABOVE the reset seat (z-index 3): a 24px seat reaches ~10-13% into the
+  // strip's right edge, so at z-index 2 a window whose end lands in that
+  // band had both grips covered by the reset's box and unreachable by
+  // pointer (the seat is opaque and paints later). The grip wins the band;
+  // the reset keeps every other pixel of its area.
+  z-index: 4;
   width: 8px;
   transform: translateX(-50%);
   border: 1px solid rgb(var(--color-surface));
@@ -174,32 +181,31 @@
   outline-offset: 2px;
 }
 
-.hk-range-ribbon-reset {
+// The reset affordance is a STANDARD HkIconButton (size 24, ghost) — the
+// icon-button sheet owns box, glyph size, hover, press and focus chrome.
+// 24 is the touch floor the family uses for dense chrome (the same floor the
+// consumers' icon-size guards enforce); the 32px strip still seats it with a
+// 4px inset top and bottom.
+// This rule only pins the seat on the overview field: right = the edge
+// handle's half-width, so a handle at 0% / 100% is never covered.
+// The seat rides the descendant key on purpose: `.hk-icon-button` declares
+// `position: relative` at the SAME (0,1,0) specificity, so a bare
+// `.hk-range-ribbon-reset` rule would only win while HkIconButton.scss
+// happens to come first in the bundle (the exact failure the lightbox close
+// hit in 2026-09-11 — its seat rule is `.hk-image-lightbox-close.hk-icon-button`
+// for this reason). (0,2,0) makes the seat order-independent.
+// The surface backing rides it for the same reason: the `--hi-icon-button-*`
+// properties also live on `.hk-icon-button` (HkIconButtonVars). The ghost
+// variant is transparent by default — a control floating on the strip's own
+// paint keeps a surface tint to stay legible over segments and scrims.
+.hk-range-ribbon .hk-range-ribbon-reset {
   position: absolute;
   top: 4px;
   right: 4px;
   z-index: 3;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 18px;
-  height: 18px;
-  padding: 0;
-  border: 1px solid rgb(var(--color-border));
-  border-radius: var(--radius-sm);
-  background: rgb(var(--color-surface) / 85%);
-  color: rgb(var(--color-text));
-  cursor: pointer;
-  transition: background-color var(--duration-fast, 0.15s) ease;
-}
-
-.hk-range-ribbon-reset:hover {
-  background: rgb(var(--color-surface));
-}
-
-.hk-range-ribbon-reset:focus-visible {
-  outline: 2px solid rgb(var(--color-primary));
-  outline-offset: 1px;
+  --hi-icon-button-bg: rgb(var(--color-surface) / 85%);
+  --hi-icon-button-bg-hover: rgb(var(--color-surface));
+  --hi-icon-button-bg-active: rgb(var(--color-surface));
 }
 
 // Visually hidden, still read by AT: labels the keyboard contract the

package/src/components/HkRangeRibbon.test.tsx

@@ -771,6 +771,18 @@ describe("HkRangeRibbon reset", () => {
     const host = mountHost([0.2, 0.6]);
     const button = host.root.querySelector<HTMLElement>(".hk-range-ribbon-reset");
     expect(button, "reset button is shown while a window exists").toBeTruthy();
+    // The reset affordance rides the STANDARD icon button (user direction
+    // 2026-11-06: no hand-rolled chip chrome), carrying its lucide glyph
+    // through the house-normal slot — pin the lucide class the slot must
+    // produce so a glyph swap cannot silently vanish.
+    expect(button!.className, "reset is an HkIconButton, not a bespoke chip").toContain(
+      "hk-icon-button",
+    );
+    expect(
+      button!.querySelector("svg.lucide-rotate-ccw"),
+      "reset glyph renders through the icon slot",
+    ).not.toBeNull();
+    expect(button!.getAttribute("type"), "reset never becomes a submit button").toBe("button");
     button!.click();
     await nextTick();
     expect(host.windowChange).toHaveBeenLastCalledWith(null);
@@ -1405,8 +1417,36 @@ describe("HkRangeRibbon stylesheet contract", () => {
     // A clipped 2px sliver must still be visible.
     expect(declaration(ruleBody(css, ".hk-range-ribbon-segment"), "min-width")).toBe("2px");
     expect(declaration(ruleBody(css, ".hk-range-ribbon-lane-track"), "height")).toBe("20px");
-    // The reset chip clears the edge handle (half its 8px width).
-    expect(declaration(ruleBody(css, ".hk-range-ribbon-reset"), "right")).toBe("4px");
+    // The reset seat clears the edge handle (half its 8px width). The rule
+    // must sit on the descendant key (0,2,0): `.hk-icon-button` declares
+    // `position: relative` at (0,1,0), so a bare-class seat would depend on
+    // bundle order.
+    const resetSeat = ruleBody(css, ".hk-range-ribbon .hk-range-ribbon-reset");
+    expect(declaration(resetSeat, "right")).toBe("4px");
+    expect(declaration(resetSeat, "position"), "the seat must out-rank .hk-icon-button").toBe(
+      "absolute",
+    );
+    expect(declaration(resetSeat, "top"), "the seat clears the strip edge").toBe("4px");
+    // The grip must paint ABOVE the seat: a right-side window puts its end
+    // handle inside the seat's box, and an opaque seat below it would make
+    // the grip unreachable by pointer.
+    const gripZ = Number(declaration(ruleBody(css, ".hk-range-ribbon-handle"), "z-index"));
+    const seatZ = Number(declaration(resetSeat, "z-index"));
+    expect(gripZ, "the edge grip outranks the reset seat").toBeGreaterThan(seatZ);
+    // The surface backing is what keeps the control legible over the strip's
+    // segments and scrims: ghost carries NO background (HkIconButtonVars),
+    // so without these three the reset degrades to a bare glyph floating on
+    // the paint. Removing them alone left the whole suite green (R3 M5b) —
+    // pin the paint, not just the geometry.
+    expect(declaration(resetSeat, "--hi-icon-button-bg"), "resting surface tint").toContain(
+      "var(--color-surface)",
+    );
+    expect(declaration(resetSeat, "--hi-icon-button-bg-hover"), "hover surface tint").toContain(
+      "var(--color-surface)",
+    );
+    expect(declaration(resetSeat, "--hi-icon-button-bg-active"), "press surface tint").toContain(
+      "var(--color-surface)",
+    );
     expect(ruleBody(css, ".hk-range-ribbon-window")).toContain("var(--color-primary)");
     expect(ruleBody(css, ".hk-range-ribbon-scrim")).toContain("var(--color-background)");
   });

package/src/components/HkRangeRibbon.tsx

@@ -11,6 +11,7 @@ import {
 } from "vue";
 
 import { useI18n } from "../i18n/context";
+import HIconButton from "./HkIconButton";
 import "./HkRangeRibbon.scss";
 
 /**
@@ -744,15 +745,23 @@ export default defineComponent({
                     onPointerdown={(event: PointerEvent) => onHandlePointerDown("end", event)}
                     onKeydown={(event: KeyboardEvent) => onHandleKeyDown("end", event)}
                   />
-                  <button
-                    type="button"
+                  {/* The reset affordance is the STANDARD icon button (user
+                      direction 2026-11-06: no hand-rolled chip chrome) —
+                      HkIconButton owns box, glyph size, hover, press and
+                      focus; this sheet only pins the seat (position) and a
+                      surface backing via its override vars. The glyph slots
+                      as a lucide component (the house-normal integration:
+                      every in-tree HkIconButton slots its glyph). */}
+                  <HIconButton
                     class="hk-range-ribbon-reset"
+                    size={24}
+                    variant="ghost"
                     aria-label={t("hikari::ribbon.reset", "Reset range")}
-                    title={t("hikari::ribbon.reset", "Reset range")}
+                    {...{ title: t("hikari::ribbon.reset", "Reset range") }}
                     onClick={resetWindow}
                   >
-                    <RotateCcw size={12} aria-hidden="true" />
-                  </button>
+                    {{ icon: () => <RotateCcw aria-hidden="true" /> }}
+                  </HIconButton>
                 </>
               )}
             </div>

package/src/components/HkScrollContainer.fade.contract.test.ts

@@ -1,8 +1,10 @@
 /**
- * Source contract for the scroll-container edge fades (the 2026-11-02
- * revision of the 2026-10 composition): each edge owns a CSS var, the
- * viewport mask is built from the gradient LAYERS listed in
- * --hk-scroll-fade-layers, and the axis rules swap that list —
+ * Source contract for the scroll-container edge fades (the 2026-11-06
+ * progressive revision of the 2026-11-02 composition): each edge owns a
+ * CSS var, the viewport mask is built from the gradient LAYERS listed in
+ * --hk-scroll-fade-layers, the axis rules swap that list, and every lit
+ * band is the fade size scaled by a live strength the component
+ * publishes from the hidden-content depth (the progressive fade) —
  *
  *   - two-axis containers list the vertical AND horizontal gradients and
  *     intersect them, so the fade reaches zero on all four sides and the
@@ -28,6 +30,17 @@
  *   - all four edge vars are declared (top/right/bottom/left, 0px base);
  *   - start/end/both rules exist for BOTH axes;
  *   - RTL swaps the horizontal vars instead of rewriting the mask.
+ *
+ * And the regression this file now exists to keep dead (2026-11-06,
+ * user report "still hard-clipped while swiping", measured in a real
+ * engine): #902 (2026-10-29) declared the four zero defaults on the
+ * VIEWPORT base rule, and a directly declared custom property beats any
+ * inherited value, so the viewport's own 0px shadowed every root state
+ * rule's band — no edge ever faded again (resolved mask stops
+ * `rgb(0,0,0) 0px … rgb(0,0,0) 100%`), every faded strip hard-clipped,
+ * and the dock fades died with it. The defaults therefore live on the
+ * ROOT rule that also carries the strength fallbacks, and the viewport
+ * declares only the layers/mask pair.
  */
 import { describe, expect, it } from "vitest";
 import { readFileSync } from "node:fs";
@@ -90,26 +103,87 @@ describe("scroll fade composition contract", () => {
     }
   });
 
-  it("fades both axes from the sensed overflow", () => {
-    for (const axis of ["v", "h"]) {
-      for (const state of ["start", "end", "both"]) {
-        expect(sheet).toContain(
-          `[data-${axis}-overflow="${state}"]`,
-        );
+  it("declares the zero defaults on the ROOT, never on the viewport (the #902 shadowing)", () => {
+    // A directly declared custom property beats any inherited value: the
+    // moment the viewport base rule re-declares these defaults, every
+    // root state rule's band is shadowed back to 0px and the fades die
+    // silently (the 2026-10-29..11-06 hard-clip regression, measured in
+    // a real engine). The viewport rule declares only the layer list.
+    const viewportBase = sheet.match(
+      /\.hk-scroll-container:is\(\[data-fade="true"\], \[data-dock-fade\]\) > \.hk-scroll-container-viewport \{[\s\S]*?\n\}/,
+    );
+    expect(viewportBase, "the viewport base rule exists").toBeTruthy();
+    for (const edge of ["top", "right", "bottom", "left"]) {
+      expect(viewportBase![0]).not.toContain(`--hk-scroll-fade-${edge}: 0px;`);
+    }
+    // And the root rule that carries them exists with the strengths.
+    const rootDefaults = sheet.match(
+      /\.hk-scroll-container:is\(\[data-fade="true"\], \[data-dock-fade\]\) \{[\s\S]*?\n\}/,
+    );
+    expect(rootDefaults, "the root defaults rule exists").toBeTruthy();
+    for (const edge of ["top", "right", "bottom", "left"]) {
+      expect(rootDefaults![0]).toContain(`--hk-scroll-fade-${edge}: 0px;`);
+      expect(rootDefaults![0]).toContain(`--hk-scroll-fade-strength-${edge}: 1;`);
+    }
+    // Sheet-wide: the four zero defaults live EXACTLY in the root rule.
+    // A second rule re-declaring any of them (the R2 escape: a bare
+    // `.hk-scroll-container-viewport { --hk-scroll-fade-top: 0px }`)
+    // would re-shadow the bands without this going red. The RTL swap
+    // rules also write 0px — the DEAD-side slot, not a default — so
+    // they are excluded from the stray scan.
+    const rtlBlocks = sheet.match(
+      /\.hk-scroll-container\[data-dir="rtl"\]\[data-fade="true"\]\[data-h-overflow="(?:start|end|both)"\] \{[^}]*\}/g,
+    ) ?? [];
+    const sheetWithoutDefaults = sheet.replace(rootDefaults![0], "").replace(new RegExp(String.raw`${rtlBlocks.map((b) => b.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)).join("|")}`, "g"), "");
+    for (const edge of ["top", "right", "bottom", "left"]) {
+      expect(
+        sheetWithoutDefaults.includes(`--hk-scroll-fade-${edge}: 0px;`),
+        `a stray zero default for ${edge} lives outside the root rule`,
+      ).toBe(false);
+    }
+  });
+
+  it("scales every lit band by the published strength (the progressive fade)", () => {
+    // Band = fade size × strength, so the component's hidden-content
+    // depth (0..1 over fadeDistance) deepens each edge from a hard cut
+    // to the full band. A bare `var(--hk-scroll-fade-size)` band in a
+    // state rule is the pre-progressive binary shape — drift.
+    const bandRules = sheet.match(
+      /^\.hk-scroll-container\[data-fade="true"\]\[data-[hv]-overflow="(?:start|end|both)"\] \{[^}]*\}/gm,
+    ) ?? [];
+    expect(bandRules.length, "six lit-band state rules (3 per axis)").toBe(6);
+    for (const block of bandRules) {
+      const declarations = block.match(/--hk-scroll-fade-(?:top|right|bottom|left): [^;]+;/g) ?? [];
+      expect(declarations.length, "each state rule lights at least one band").toBeGreaterThan(0);
+      for (const declaration of declarations) {
+        expect(
+          declaration,
+          `strength-scaled band: ${declaration}`,
+        ).toMatch(/^--hk-scroll-fade-(?:top|right|bottom|left): calc\(var\(--hk-scroll-fade-size\) \* var\(--hk-scroll-fade-strength-(?:top|right|bottom|left), 1\)\);$/);
       }
     }
-    // The vertical half is what the old sheet was missing entirely.
-    expect(sheet).toContain('--hk-scroll-fade-top: var(--hk-scroll-fade-size)');
-    expect(sheet).toContain('--hk-scroll-fade-bottom: var(--hk-scroll-fade-size)');
+    expect(sheet).not.toMatch(/--hk-scroll-fade-(?:top|right|bottom|left): var\(--hk-scroll-fade-size\);/);
   });
 
-  it("swaps horizontal sides under RTL instead of rewriting the mask", () => {
+  it("swaps horizontal sides under the mirrored data-dir instead of rewriting the mask", () => {
+    // The slot swap keys on the component's mirrored data-dir (computed
+    // direction), NOT a literal [dir] selector: the physical-side
+    // strengths resolve direction in JS, and an ancestor attribute the
+    // selector misses (dir on the container, dir="auto", a deeper
+    // override) would light the wrong edge. See HkScrollContainer.tsx
+    // senseOverflow's data-dir mirror.
     expect(sheet).toContain(
-      '[dir="rtl"] .hk-scroll-container[data-fade="true"][data-h-overflow="start"]',
+      '.hk-scroll-container[data-dir="rtl"][data-fade="true"][data-h-overflow="start"]',
     );
     expect(sheet).toContain(
-      '[dir="rtl"] .hk-scroll-container[data-fade="true"][data-h-overflow="end"]',
+      '.hk-scroll-container[data-dir="rtl"][data-fade="true"][data-h-overflow="end"]',
     );
+    // A literal [dir="rtl"] band rule would disagree with the mirrored
+    // depths under exactly the configurations the mirror exists for.
+    expect(
+      sheet.match(/\[dir="rtl"\][^\n]*\{\s*--hk-scroll-fade-(?:left|right)/),
+      "no literal [dir]-keyed band rules remain",
+    ).toBeNull();
   });
 
   it("routes the dock fades through the same edge vars", () => {

package/src/components/HkScrollContainer.scss

@@ -66,12 +66,46 @@
    composite pair stays on the base rule: with one layer it is a no-op
    (there is no layer below to composite against), so the axis rules only
    swap the layer list. Dock fades ride the same vars — they feed the
-   vertical gradient, so they land on vertical and two-axis containers. */
-.hk-scroll-container:is([data-fade="true"], [data-dock-fade]) > .hk-scroll-container-viewport {
+   vertical gradient, so they land on vertical and two-axis containers.
+
+   PROGRESSIVE DEPTH (2026-11-06 revision) — two halves:
+
+   1. The state-driven vars moved back to the ROOT. #902 (2026-10-29)
+      added the four zero defaults to the VIEWPORT base rule below, and a
+      directly declared custom property beats any inherited value, so the
+      viewport's own 0px shadowed every state rule's band — measured in a
+      real engine (resolved mask stops `rgb(0,0,0) 0px … rgb(0,0,0)
+      100%`): no edge ever faded, every faded strip hard-clipped, and the
+      dock fades died with it. The defaults live on the root here (same
+      element the state rules write), where a consumer override on the
+      container still wins by the usual specificity order.
+
+   2. Each lit band is the fade size scaled by a live strength the
+      component publishes while `fade` is on: the hidden-content depth
+      past that edge (px) saturates over `fadeDistance` (default 96px)
+      into a 0..1 number mirrored as --hk-scroll-fade-strength-<side>.
+      Pull the strip and the trailing edge's fade grows from a hard cut
+      through a hint to the full band; scroll back and it recedes. Edges
+      with nothing hidden read strength 1 (the pre-JS / dock-fade
+      fallback), which with a 0px band contributes nothing. Physical-side
+      names AND a mirrored data-dir: the component resolves the computed
+      direction once and publishes both the depths and the direction
+      attribute from the same pass, so the LTR and RTL state rules
+      consume the same vars and the slot swap below never disagrees with
+      the depths (a literal [dir] selector can miss dir on the
+      container, dir="auto", or a deeper override). */
+.hk-scroll-container:is([data-fade="true"], [data-dock-fade]) {
   --hk-scroll-fade-top: 0px;
   --hk-scroll-fade-right: 0px;
   --hk-scroll-fade-bottom: 0px;
   --hk-scroll-fade-left: 0px;
+  --hk-scroll-fade-strength-top: 1;
+  --hk-scroll-fade-strength-right: 1;
+  --hk-scroll-fade-strength-bottom: 1;
+  --hk-scroll-fade-strength-left: 1;
+}
+
+.hk-scroll-container:is([data-fade="true"], [data-dock-fade]) > .hk-scroll-container-viewport {
   --hk-scroll-fade-layers:
     linear-gradient(
       to bottom,
@@ -122,49 +156,64 @@
   --hk-scroll-fade-size: var(--space-24);
 }
 
+/* ── Lit bands: fade size scaled by the published strength ─────────
+   `calc(length * number)` keeps the band arithmetic in CSS (consumer
+   --hk-scroll-fade-size overrides keep working; the JS side publishes
+   only the unitless strength). An edge with nothing hidden keeps the
+   default strength 1 AND a 0px band — no fade either way. */
+
 /* Vertical axis — the half the old implementation never had. */
 .hk-scroll-container[data-fade="true"][data-v-overflow="start"] {
-  --hk-scroll-fade-top: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-top: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-top, 1));
 }
 
 .hk-scroll-container[data-fade="true"][data-v-overflow="end"] {
-  --hk-scroll-fade-bottom: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-bottom: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-bottom, 1));
 }
 
 .hk-scroll-container[data-fade="true"][data-v-overflow="both"] {
-  --hk-scroll-fade-top: var(--hk-scroll-fade-size);
-  --hk-scroll-fade-bottom: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-top: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-top, 1));
+  --hk-scroll-fade-bottom: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-bottom, 1));
 }
 
 /* Horizontal axis (LTR: inline start = left). */
 .hk-scroll-container[data-fade="true"][data-h-overflow="start"] {
-  --hk-scroll-fade-left: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-left: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-left, 1));
 }
 
 .hk-scroll-container[data-fade="true"][data-h-overflow="end"] {
-  --hk-scroll-fade-right: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-right: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-right, 1));
 }
 
 .hk-scroll-container[data-fade="true"][data-h-overflow="both"] {
-  --hk-scroll-fade-left: var(--hk-scroll-fade-size);
-  --hk-scroll-fade-right: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-left: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-left, 1));
+  --hk-scroll-fade-right: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-right, 1));
 }
 
-/* RTL: the inline start edge is the right side, so the horizontal vars
-   swap instead of the mask (the mask itself is direction-neutral). */
-[dir="rtl"] .hk-scroll-container[data-fade="true"][data-h-overflow="start"] {
+/* RTL: the inline start edge is the right side, so the horizontal band
+   slots swap instead of the mask (the mask itself is direction-neutral).
+   The swap keys on the component's MIRRORED data-dir, not on [dir]:
+   the strengths are published per PHYSICAL side from the computed
+   direction (normalized scroll signs), and a literal ancestor-[dir]
+   selector diverges from that resolution exactly when [dir] sits on the
+   container itself, on a dir="auto" ancestor, or under an explicit
+   deeper override — computed-direction-is-truth keeps slots and depths
+   in agreement. The attribute lands in the same sensing pass as the
+   overflow attrs (write-only-on-change, removed when fade turns off),
+   so slots and lit attrs are never from different frames. */
+.hk-scroll-container[data-dir="rtl"][data-fade="true"][data-h-overflow="start"] {
   --hk-scroll-fade-left: 0px;
-  --hk-scroll-fade-right: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-right: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-right, 1));
 }
 
-[dir="rtl"] .hk-scroll-container[data-fade="true"][data-h-overflow="end"] {
+.hk-scroll-container[data-dir="rtl"][data-fade="true"][data-h-overflow="end"] {
   --hk-scroll-fade-right: 0px;
-  --hk-scroll-fade-left: var(--hk-scroll-fade-size);
+  --hk-scroll-fade-left: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-left, 1));
 }
 
-[dir="rtl"] .hk-scroll-container[data-fade="true"][data-h-overflow="both"] {
-  --hk-scroll-fade-left: var(--hk-scroll-fade-size);
-  --hk-scroll-fade-right: var(--hk-scroll-fade-size);
+.hk-scroll-container[data-dir="rtl"][data-fade="true"][data-h-overflow="both"] {
+  --hk-scroll-fade-left: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-left, 1));
+  --hk-scroll-fade-right: calc(var(--hk-scroll-fade-size) * var(--hk-scroll-fade-strength-right, 1));
 }
 
 /* ── Anchored docks (dockTop / dockBottom slots) ─────────────────
@@ -187,7 +236,14 @@
    (opacity 100 -> 0 across --hk-scroll-dock-fade) reads as intentional
    instead of a hard clip against the dock's top edge. Content never
    sits under the dock, so this fades the viewport's last few pixels,
-   not the dock itself. */
+   not the dock itself. Ownership note (2026-11-06): when `fade` is ALSO
+   on, the state band rules below have higher specificity and own that
+   edge while it hides content — the dock band applies only when the
+   sense reports nothing hidden past it. With the progressive fade the
+   shared edge therefore deepens with the pull (≤ --space-24) and snaps
+   to the full dock fade only at the scroll end; no shipped consumer
+   combines the two, but a future one should treat that as the
+   documented shape, not a bug. */
 .hk-scroll-container[data-dock-fade="bottom"] {
   --hk-scroll-fade-bottom: var(--hk-scroll-dock-fade, 2rem);
 }

package/src/components/HkScrollContainer.test.ts

@@ -180,6 +180,206 @@ describe("HkScrollContainer overflow sensing", () => {
   });
 });
 
+// ── Progressive fade strengths (fadeDistance, 2026-11-06): while `fade`
+// is on the container mirrors the hidden-content depth past each edge as
+// a 0..1 band scale on the root's inline style — pull the strip and the
+// trailing fade deepens, saturate at the full band, recede on the way
+// back. CSS consumes the vars (fade.contract.test.ts pins the sheet). ──
+describe("HkScrollContainer progressive fade strengths", () => {
+  const varOf = (m: Mounted, side: string): string =>
+    m.root.style.getPropertyValue(`--hk-scroll-fade-strength-${side}`);
+
+  it("publishes the hidden depth per edge, saturating at 1", () => {
+    const m = mountScroller({ axis: "horizontal", fade: true });
+    // scrollWidth 300 in a 100px viewport: hiddenLeft = scrollLeft,
+    // hiddenRight = 200 - scrollLeft. Default fadeDistance 96.
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 48 });
+    m.instance?.refresh();
+    // 48/96 = exactly half depth on the start edge; 152 hidden past the
+    // end edge saturates the band.
+    expect(varOf(m, "left")).toBe("0.5");
+    expect(varOf(m, "right")).toBe("1");
+    // Vertical edges hide nothing: strength 1 with a 0px band (invisible).
+    expect(varOf(m, "top")).toBe("1");
+    expect(varOf(m, "bottom")).toBe("1");
+  });
+
+  it("grows the strength with the pull and recedes on the way back", () => {
+    const m = mountScroller({ axis: "horizontal", fade: true });
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 0 });
+    m.instance?.refresh();
+    expect(varOf(m, "left")).toBe("1"); // nothing hidden past the start
+    expect(varOf(m, "right")).toBe("1"); // 200 hidden: saturated
+
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 24 });
+    m.viewport.dispatchEvent(new Event("scroll"));
+    m.instance?.refresh();
+    expect(varOf(m, "left")).toBe("0.25"); // 24/96: the pull deepens it
+    expect(varOf(m, "right")).toBe("1"); // 176 hidden: still saturated
+
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 190 });
+    m.viewport.dispatchEvent(new Event("scroll"));
+    m.instance?.refresh();
+    expect(varOf(m, "left")).toBe("1"); // fully pulled: saturated
+    expect(varOf(m, "right")).toBe("0.104"); // 10 hidden past the end: receding
+  });
+
+  it("keeps the ≤1px deadband of the overflow sense on the strength side", () => {
+    const m = mountScroller({ axis: "horizontal", fade: true });
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 199.5 });
+    m.instance?.refresh();
+    // 0.5px hidden past the end: the sense still reports "start" (the
+    // same deadband) and the strength must not read as a visible fade.
+    expect(m.root.getAttribute("data-h-overflow")).toBe("start");
+    expect(varOf(m, "right")).toBe("1");
+  });
+
+  it("degrades to the binary shape with a zero fadeDistance", () => {
+    const m = mountScroller({ axis: "horizontal", fade: true, fadeDistance: 0 });
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 48 });
+    m.instance?.refresh();
+    expect(varOf(m, "left")).toBe("1");
+    expect(varOf(m, "right")).toBe("1");
+  });
+
+  it("re-derives strengths when only fadeDistance changes at runtime", async () => {
+    // The distance is read live per pass: changing it with NO scroll and
+    // NO refresh() call must re-derive every strength on the watcher's
+    // scheduled pass alone (a scroll-driven delta would pass even with a
+    // dead watcher — the scroll event schedules its own pass).
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const props = reactive({ fade: true, fadeDistance: 96 });
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, { axis: "horizontal", fade: props.fade, fadeDistance: props.fadeDistance }, {
+            default: () => h("span", "content"),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const root = container.querySelector<HTMLElement>(".hk-scroll-container")!;
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport")!;
+    stubGeometry(viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 48 });
+    // One baseline pass (the mount pass ran before the stub landed);
+    // after this, NO further scroll happens — the flip below must
+    // re-derive on the watcher's pass alone.
+    viewport.dispatchEvent(new Event("scroll"));
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    expect(root.style.getPropertyValue("--hk-scroll-fade-strength-left")).toBe("0.5");
+
+    props.fadeDistance = 192; // same geometry, doubled distance
+    await nextTick();
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    expect(viewport.scrollLeft, "no scroll between the passes").toBe(48);
+    expect(root.style.getPropertyValue("--hk-scroll-fade-strength-left")).toBe("0.25");
+    app.unmount();
+  });
+
+  it("publishes on a fade prop flip without any scroll (the re-sense watcher)", async () => {
+    // Mounting fade-off with content already hidden publishes nothing;
+    // flipping the prop on must light the strengths on the watcher's
+    // scheduled pass alone — no scroll event, no refresh() call.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const props = reactive({ fade: false });
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, { axis: "horizontal", fade: props.fade }, {
+            default: () => h("span", "content"),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const root = container.querySelector<HTMLElement>(".hk-scroll-container")!;
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport")!;
+    stubGeometry(viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 48 });
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    expect(root.style.getPropertyValue("--hk-scroll-fade-strength-left")).toBe("");
+
+    props.fade = true;
+    await nextTick();
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    expect(root.style.getPropertyValue("--hk-scroll-fade-strength-left")).toBe("0.5");
+    expect(root.style.getPropertyValue("--hk-scroll-fade-strength-right")).toBe("1");
+    app.unmount();
+  });
+
+  it("clears the published strengths and mirrored dir when fade flips off", async () => {
+    // Stale inline values must not outlive the feature (the
+    // stopSelectionSensing symmetry): off removes all four strength
+    // vars and data-dir from the root, so a downstream reader of the
+    // root's style never sees zombie strengths.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const props = reactive({ fade: true });
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, { axis: "horizontal", fade: props.fade }, {
+            default: () => h("span", "content"),
+          });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    const root = container.querySelector<HTMLElement>(".hk-scroll-container")!;
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport")!;
+    stubGeometry(viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 48 });
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    expect(root.getAttribute("data-dir")).toBe("ltr");
+    expect(root.style.getPropertyValue("--hk-scroll-fade-strength-left")).not.toBe("");
+
+    props.fade = false;
+    await nextTick();
+    await new Promise<void>((r) => requestAnimationFrame(() => r()));
+    for (const side of ["left", "right", "top", "bottom"]) {
+      expect(root.style.getPropertyValue(`--hk-scroll-fade-strength-${side}`)).toBe("");
+    }
+    expect(root.hasAttribute("data-dir")).toBe(false);
+    app.unmount();
+  });
+
+  it("publishes nothing while the fade prop is off", () => {
+    const m = mountScroller({ axis: "horizontal" });
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: 48 });
+    m.instance?.refresh();
+    expect(varOf(m, "left")).toBe("");
+    expect(varOf(m, "right")).toBe("");
+    expect(m.root.getAttribute("data-h-overflow")).toBe("both"); // sense still runs
+  });
+
+  it("normalizes RTL scroll signs for both the sense and the strengths", () => {
+    const m = mountScroller({ axis: "horizontal", fade: true });
+    m.viewport.style.direction = "rtl";
+    // Chromium RTL convention: scrollLeft runs 0 → -(max). Raw -48 sits
+    // mid-scroll; the pre-normalization sense would have read "end"
+    // (scrollPos ≤ 1) for every RTL position.
+    stubGeometry(m.viewport, { scrollWidth: 300, clientWidth: 100, scrollLeft: -48 });
+    m.instance?.refresh();
+    expect(m.root.getAttribute("data-h-overflow")).toBe("both");
+    // The mirror is the CSS slot swap's only direction truth — a mutant
+    // that hardcodes "ltr" (or inverts the ternary) would keep the
+    // depths correct and light the WRONG physical edge, so the artifact
+    // itself is pinned, not just its consequences.
+    expect(m.root.getAttribute("data-dir")).toBe("rtl");
+    // Physical start edge (visual RIGHT under RTL) hides 48px…
+    expect(varOf(m, "left")).toBe("1");
+    expect(varOf(m, "right")).toBe("0.5");
+    m.viewport.style.direction = "";
+  });
+});
+
 describe("HkScrollContainer scrollbar reactivity", () => {
   it("builds and tears down the overlay tracks when the scrollbar prop flips", async () => {
     const container = document.createElement("div");

package/src/components/HkScrollContainer.tsx

@@ -84,6 +84,23 @@ export default defineComponent({
     /** Fade the viewport's inline edges (CSS mask) on the sides where
      *  the sensed overflow (`data-h-overflow`) reports hidden content. */
     fade: { type: Boolean, default: false },
+    /** Hidden-content distance (px) over which a lit edge fade deepens
+     *  from a hard cut to the full band (the progressive fade): the
+     *  component senses how much content hides past each edge and
+     *  mirrors it as a 0..1 strength (--hk-scroll-fade-strength-<side>)
+     *  that scales the band in CSS, so pulling the strip grows the
+     *  trailing fade and scrolling back recedes it. Read live (runtime
+     *  changes need no remount, like approachDistance). 0 or negative
+     *  degrades to the pre-2026-11 binary shape: any lit edge jumps
+     *  straight to the full band. Only read while `fade` is on.
+     *
+     *  RTL normalization assumes the Chromium/WebKit convention
+     *  (scrollLeft runs 0 → -max): every engine hikari deploys on is
+     *  Chromium-family (the sheet's WebView notes). A legacy
+     *  positive-descending engine would clamp the normalized offset to
+     *  0 — bounded degradation: the sense parks at "end" and one fade
+     *  stays saturated, never inverted. */
+    fadeDistance: { type: Number, default: 96 },
     /** Additive opt-in: while autoFollow is enabled and the user has
      *  scrolled away from the bottom, float a small jump-back FAB that
      *  snaps to the latest content and re-arms follow. */
@@ -259,6 +276,20 @@ export default defineComponent({
     let lastHOverflow: OverflowSense | null = null;
     let lastVOverflow: OverflowSense | null = null;
 
+    // Progressive fade strengths last written to the root (see the
+    // fadeDistance prop doc). Same write-only-on-change discipline as
+    // the overflow mirror: scroll redraws the mask every frame anyway,
+    // but a pass that re-senses identical geometry must not churn
+    // inline style for nothing. The mirrored direction rides the same
+    // contract — it keys the CSS band-slot swap (see the SCSS RTL
+    // rules) and MUST agree with the physical-side depths below, which
+    // is why the computed direction is mirrored instead of CSS
+    // sniffing [dir] itself: a computed rtl under a missing/mismatched
+    // ancestor attribute (dir on the container, dir="auto") would
+    // light the wrong physical edge.
+    const lastFadeStrengths = new Map<string, string>();
+    let lastPublishedDir: string | null = null;
+
     // Sensed selection edge hint (see the selectionHint prop doc),
     // mirrored onto the root as data-selection-beyond — the same
     // write-only-on-change discipline as the overflow mirror.
@@ -618,13 +649,29 @@ export default defineComponent({
     }
 
     /** Mirror the live scroll geometry onto the root element as
-     *  data-h-overflow / data-v-overflow. Runs on every scheduled
-     *  update (scroll, resize, content resize via the aligner). */
+     *  data-h-overflow / data-v-overflow, and while `fade` is on publish
+     *  the per-edge fade strengths (hidden-content depth saturating over
+     *  fadeDistance). Runs on every scheduled update (scroll, resize,
+     *  content resize via the aligner).
+     *
+     *  Scroll offsets are normalized to LTR convention first: Chromium
+     *  reports negative scrollLeft under RTL (0 at the inline start down
+     *  to -(max) at the inline end), so both the overflow sense and the
+     *  strengths would read as "always at start" without it. Strengths
+     *  are PHYSICAL-side (left/right), so the direction-neutral
+     *  start/end state rules and their RTL width swap below consume the
+     *  same vars unchanged. */
     function senseOverflow(vp: HTMLElement) {
       const root = vp.parentElement;
       if (!root) return;
-      const h = hasH() ? computeOverflow(vp.scrollWidth, vp.clientWidth, vp.scrollLeft) : "none";
-      const v = hasV() ? computeOverflow(vp.scrollHeight, vp.clientHeight, vp.scrollTop) : "none";
+      const rtl = getComputedStyle(vp).direction === "rtl";
+      const hMax = Math.max(0, vp.scrollWidth - vp.clientWidth);
+      const vMax = Math.max(0, vp.scrollHeight - vp.clientHeight);
+      const clampPos = (pos: number, max: number) => Math.min(max, Math.max(0, pos));
+      const hPos = clampPos(hasH() ? (rtl ? -vp.scrollLeft : vp.scrollLeft) : 0, hMax);
+      const vPos = clampPos(hasV() ? vp.scrollTop : 0, vMax);
+      const h = hasH() ? computeOverflow(vp.scrollWidth, vp.clientWidth, hPos) : "none";
+      const v = hasV() ? computeOverflow(vp.scrollHeight, vp.clientHeight, vPos) : "none";
       if (h !== lastHOverflow) {
         lastHOverflow = h;
         root.setAttribute("data-h-overflow", h);
@@ -633,6 +680,78 @@ export default defineComponent({
         lastVOverflow = v;
         root.setAttribute("data-v-overflow", v);
       }
+      if (props.fade) {
+        // Physical-side depths: the normalized hPos counts the inline
+        // START, which is the visual RIGHT edge under RTL — swap there
+        // so --hk-scroll-fade-strength-left always means the left edge.
+        // Axis-gated edges never hide anything this container can fade,
+        // so they publish the unlit "1" rather than live geometry.
+        publishFadeStrengths(root, {
+          left: hasH() ? (rtl ? hMax - hPos : hPos) : 0,
+          right: hasH() ? (rtl ? hPos : hMax - hPos) : 0,
+          top: hasV() ? vPos : 0,
+          bottom: hasV() ? vMax - vPos : 0,
+        });
+        // Mirror the COMPUTED direction for the CSS band-slot swap (the
+        // SCSS RTL rules key on this attribute, not on [dir]): the
+        // depths above are physical, so the slot mapping must come from
+        // the same resolved direction the normalization used — an
+        // ancestor [dir] the selector happens to miss (dir on this
+        // element, dir="auto", an explicit deeper override) would
+        // otherwise light the wrong edge. Lands the same pass as the
+        // overflow attrs, so band slots and lit attrs are never from
+        // different frames. Known trade (2026-11-06 review): a pure
+        // direction change at rest (locale flip, scrollLeft 0, no
+        // layout delta) schedules no sensing pass, so the mirror and
+        // the depths sit stale until the next scroll / resize /
+        // refresh / prop touch — wrong physical edge in that window,
+        // self-healing; a dir MutationObserver was rejected as
+        // over-engineering for a narrow trigger.
+        const dir = rtl ? "rtl" : "ltr";
+        if (lastPublishedDir !== dir) {
+          lastPublishedDir = dir;
+          root.setAttribute("data-dir", dir);
+        }
+      } else {
+        clearPublishedFade(root);
+      }
+    }
+
+    /** Drop every fade state the mirror published (fade prop off):
+     *  the four strength vars, their cache and the mirrored direction —
+     *  a stale inline value must not outlive the feature that wrote it
+     *  (same contract shape as stopSelectionSensing). */
+    function clearPublishedFade(root: HTMLElement) {
+      if (lastFadeStrengths.size === 0 && lastPublishedDir === null) return;
+      for (const side of ["left", "right", "top", "bottom"]) {
+        root.style.removeProperty(`--hk-scroll-fade-strength-${side}`);
+      }
+      lastFadeStrengths.clear();
+      if (lastPublishedDir !== null) {
+        lastPublishedDir = null;
+        root.removeAttribute("data-dir");
+      }
+    }
+
+    /** Progressive fade strengths (see the fadeDistance prop doc): the
+     *  hidden px past an edge saturates linearly over fadeDistance into
+     *  the band's 0..1 depth, so the fade grows with the pull and caps
+     *  at the full band. An edge hiding nothing (the same ≤1px deadband
+     *  computeOverflow uses) publishes 1 — with its 0px band that is
+     *  invisible, and it keeps dock-fed edges (which share the vars,
+     *  no fade prop → never published) at their designed full band. */
+    function publishFadeStrengths(root: HTMLElement, hidden: { left: number; right: number; top: number; bottom: number }) {
+      const dist = Math.max(0, props.fadeDistance);
+      for (const [side, depth] of Object.entries(hidden) as Array<[keyof typeof hidden, number]>) {
+        const strength =
+          depth <= 1 || dist === 0
+            ? "1"
+            : String(Math.min(1, Math.round((depth / dist) * 1000) / 1000));
+        if (lastFadeStrengths.get(side) !== strength) {
+          lastFadeStrengths.set(side, strength);
+          root.style.setProperty(`--hk-scroll-fade-strength-${side}`, strength);
+        }
+      }
     }
 
     /** Selection edge hint (see the selectionHint prop doc): does any
@@ -705,6 +824,13 @@ export default defineComponent({
 
     watch(() => props.selectionSelector, () => scheduleUpdate());
 
+    // Runtime fade changes re-sense immediately: flipping `fade` on with
+    // content already hidden must not wait for a scroll, and a different
+    // fadeDistance re-derives every strength without any DOM motion.
+    watch(() => [props.fade, props.fadeDistance] as const, () => {
+      scheduleUpdate();
+    });
+
     function onScroll() {
       if (!viewportRef.value) return;
       scheduleUpdate();

package/src/components/range-ribbon-reset.contract.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Source contract for the range-ribbon reset affordance (user direction
+ * 2026-11-06: the waterfall minimap's reset control must be the STANDARD
+ * icon button, not a per-component hand-rolled `<button>` chip).
+ *
+ * HkRangeRibbon renders its reset through HkIconButton (the shared icon
+ * button: one box ladder, one glyph channel, one hover/press/focus chrome)
+ * carrying the a directly-imported `RotateCcw` glyph in the icon slot — the same "named-icon contract" the unified window-close wave
+ * pinned (window-close.contract.test.ts). The positioning class
+ * `hk-range-ribbon-reset` survives ONLY as the seat hook the component
+ * sheet pins (it must keep clearing the edge handle).
+ *
+ * Pinned here so a refactor cannot silently re-sprout a bespoke chip —
+ * the same "looks unified but drifted" failure class the window-close
+ * contract guards against.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const ribbon = readFileSync(join(here, "HkRangeRibbon.tsx"), "utf-8");
+
+describe("range-ribbon reset control contract", () => {
+  it("renders the reset affordance through the standard HkIconButton", () => {
+    expect(ribbon, "the reset must ride HkIconButton chrome").toContain("HIconButton");
+    expect(ribbon, "the seat class survives as the positioning hook").toContain(
+      'class="hk-range-ribbon-reset"',
+    );
+    expect(
+      ribbon,
+      "the glyph rides the house-normal lucide slot (every in-tree HkIconButton slots its glyph)",
+    ).toContain("<RotateCcw");
+    expect(ribbon, "no hand-rolled <button> may carry the reset class").not.toMatch(
+      /<button[^>]*hk-range-ribbon-reset/,
+    );
+    // The three things a partial revert silently drops while still passing
+    // the substring checks above.
+    expect(ribbon, "the reset keeps its touch-floor size").toMatch(
+      /<HIconButton[\s\S]{0,200}?size=\{24\}/,
+    );
+    // The non-submit guarantee moved upstream into HkIconButton (one
+    // implementation, not a per-call-site spread); it is pinned in
+    // HkIconButton.test.tsx and asserted on the rendered DOM in
+    // HkRangeRibbon.test.tsx.
+    expect(ribbon, "the reset passes the standard variant explicitly").toContain('variant="ghost"');
+    expect(ribbon, "the glyph rides the slot form, not the icon prop").toMatch(
+      /\{\{\s*icon:\s*\(\)\s*=>\s*<RotateCcw/,
+    );
+  });
+});

package/src/index.ts

@@ -978,7 +978,7 @@ export type {
 } from "./composables/useInfinitePages";
 export { default as HkFilterChip } from "./components/HkFilterChip";
 export { default as HkPillToggleGroup } from "./components/HkPillToggleGroup";
-export type { HkPillToggleGroupOption } from "./components/HkPillToggleGroup";
+export type { HkPillToggleGroupOption, HkPillTone } from "./components/HkPillToggleGroup";
 export { HkIconChip as HkIconChip } from "./components/HkIconChip";
 export { HkIconChip as HIconChip } from "./components/HkIconChip";
 export { HkCardList, HkListRow } from "./components/HkCardList";