@celestia-island/hikari 0.49.7 → 0.50.0

package/package.json

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

package/src/components/HkDatePicker.test.ts

@@ -41,13 +41,6 @@ function panel(): HTMLElement | null {
   return document.querySelector<HTMLElement>(".hk-dp-panel");
 }
 
-/** Let Vue's leave transitions (frame/timeout based) finish in happy-dom. */
-async function settle() {
-  await nextTick();
-  await new Promise((r) => setTimeout(r, 20));
-  await nextTick();
-}
-
 /** Poll until the drilled view's title button reads `expected`. The drill
  *  transition is frame/timeout based and a fixed 20 ms settle raced it on
  *  the CI runner (the year-grid test once read the previous view's title),
@@ -67,10 +60,23 @@ async function waitForTitle(expected: string): Promise<void> {
   }
 }
 
-/** Generic state poll over the same drill race: wait until `probe` holds. */
+/** Generic state poll over the same drill race: wait until `probe` holds
+ *  STABLY. A single true evaluation can be a mid-transition transient
+ *  (the leaving pane's cells vanish one tick before its container
+ *  unmounts), so the probe must hold across a 10 ms window before the
+ *  wait resolves — otherwise the raw asserts after it race the teardown
+ *  timers (observed on the hosted runner: pickCount read 24 right after
+ *  a "settled" poll). */
 async function waitForView(desc: string, probe: () => boolean): Promise<void> {
   const deadline = Date.now() + 2000;
-  while (!probe()) {
+  let holdSince: number | null = null;
+  for (;;) {
+    if (probe()) {
+      holdSince ??= Date.now();
+      if (Date.now() - holdSince >= 10) return;
+    } else {
+      holdSince = null;
+    }
     if (Date.now() > deadline) throw new Error(`view never reached: ${desc}`);
     await new Promise((r) => setTimeout(r, 10));
   }
@@ -163,8 +169,7 @@ describe("HkDatePicker", () => {
     expect(panel()?.querySelectorAll(".hk-dp-cell").length).toBe(42);
 
     panel()?.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
-    await settle();
-    expect(panel()).toBeNull();
+    await waitForView("the popup to close on Escape", () => panel() === null);
   });
 
   it("derives weekday header labels from Intl for the locale", async () => {
@@ -185,8 +190,7 @@ describe("HkDatePicker", () => {
     clickDay(20);
     await nextTick();
     expect(p.emitted).toEqual(["2026-08-20"]);
-    await settle();
-    expect(panel()).toBeNull();
+    await waitForView("the popup to close after picking a day", () => panel() === null);
   });
 
   it("disables days outside the inclusive min/max bounds", async () => {
@@ -244,8 +248,7 @@ describe("HkDatePicker", () => {
     await nextTick();
     expect(panel()).not.toBeNull();
     trigger?.click();
-    await settle();
-    expect(panel()).toBeNull();
+    await waitForView("the popup to close on trigger toggle", () => panel() === null);
 
     const d = mountPicker({ modelValue: "2026-08-16", disabled: true });
     const disabledTrigger = d.container.querySelector<HTMLElement>(".hk-dp-trigger");
@@ -345,7 +348,10 @@ describe("HkDatePicker", () => {
     await nextTick();
     const stage = panel()?.querySelector<HTMLElement>(".hk-dp-stage");
     panel()?.querySelector<HTMLButtonElement>(".hk-dp-title-btn")?.click();
-    await settle();
+    // Wait out the drill transition before reading the grid: a raced
+    // read still sees the leaving days pane (54 cells).
+    await waitForView("the months grid settled to one pane", () =>
+      panel()?.querySelectorAll(".hk-dp-cell").length === 12);
     expect(stage?.getAttribute("data-dir")).toBe("fwd");
     const picks = Array.from(panel()?.querySelectorAll<HTMLButtonElement>(".hk-dp-cell[data-variant='pick']") ?? []);
     expect(picks.length).toBe(12);
@@ -354,9 +360,9 @@ describe("HkDatePicker", () => {
         new Intl.DateTimeFormat("en", { month: "short" }).format(new Date(2024, i, 15))),
     );
     panel()?.querySelector<HTMLButtonElement>(".hk-dp-back")?.click();
-    await settle();
+    await waitForView("the days grid settled to one pane", () =>
+      panel()?.querySelectorAll(".hk-dp-cell").length === 42);
     expect(stage?.getAttribute("data-dir")).toBe("back");
-    expect(panel()?.querySelectorAll(".hk-dp-cell").length).toBe(42);
   });
 
   it("picks a year from the year grid and lands back on days with that year", async () => {
@@ -378,7 +384,12 @@ describe("HkDatePicker", () => {
     pickCells().find((c) => c.textContent === "2027")?.click();
     // Picking a year lands on the months grid of that year.
     await waitForTitle("2027");
-    pickCells()[6]?.click(); // July
+    // Click July BY LABEL: a positional click would hit whatever the
+    // grid shows if the view drifted (hosted CI once clicked the 2022
+    // year cell here and the title read "August 2022").
+    await waitForView("the July cell in the months grid", () =>
+      pickCells().some((c) => c.textContent === "Jul"));
+    pickCells().find((c) => c.textContent === "Jul")?.click();
     // ...and picking a month lands back on the days grid.
     await waitForView("the days grid", () => panel()?.querySelectorAll(".hk-dp-cell").length === 42);
     const fmt = new Intl.DateTimeFormat("en", { year: "numeric", month: "long" });
@@ -392,7 +403,6 @@ describe("HkDatePicker", () => {
     openViaEnter(p);
     await nextTick();
     panel()?.querySelector<HTMLButtonElement>(".hk-dp-title-btn")?.click();
-    await settle();
     await waitForTitle("2026");
     const navs = () => panel()?.querySelectorAll<HTMLButtonElement>(".hk-dp-nav");
     navs()?.[1].click();
@@ -423,25 +433,21 @@ describe("HkDatePicker", () => {
           stage?.querySelectorAll<HTMLButtonElement>(".hk-dp-cell:not([data-variant])").length === 42
         : pickCount() === 12 && stage?.children.length === 1;
     panel()?.querySelector<HTMLButtonElement>(".hk-dp-title-btn")?.click();
-    await settle();
     await waitForView("the months grid settled to one pane", settledDrill(false));
     expect(panel()?.querySelector<HTMLElement>(".hk-dp-stage")).toBe(stage);
     expect(stage?.getAttribute("data-dir")).toBe("fwd");
     expect(stage?.children.length).toBe(1); // one pane at a time after settle
     expect(pickCount()).toBe(12);
     panel()?.querySelector<HTMLButtonElement>(".hk-dp-title-btn")?.click();
-    await settle();
     await waitForView("the years grid settled to one pane", settledDrill(false));
     expect(stage?.getAttribute("data-dir")).toBe("fwd");
     expect(pickCount()).toBe(12);
     // back steps down the stack one level at a time: years → months → days.
     panel()?.querySelector<HTMLButtonElement>(".hk-dp-back")?.click();
-    await settle();
     await waitForView("the months grid again, one pane", settledDrill(false));
     expect(stage?.getAttribute("data-dir")).toBe("back");
     expect(pickCount()).toBe(12);
     panel()?.querySelector<HTMLButtonElement>(".hk-dp-back")?.click();
-    await settle();
     await waitForView("the days grid settled to one pane", settledDrill(true));
     expect(stage?.getAttribute("data-dir")).toBe("back");
     expect(stage?.querySelectorAll<HTMLButtonElement>(".hk-dp-cell:not([data-variant])").length).toBe(42);

package/src/components/HkDateTimePicker.test.ts

@@ -60,13 +60,6 @@ function mountPicker(props: Record<string, unknown> = {}): PickerHarness {
   return { container, emitted };
 }
 
-/** Let Vue's leave transitions (frame/timeout based) finish in happy-dom. */
-async function settle() {
-  await nextTick();
-  await new Promise((r) => setTimeout(r, 20));
-  await nextTick();
-}
-
 /** Poll until the drilled view's title button reads `expected`. The drill
  *  transition is frame/timeout based and a fixed 20 ms settle raced it
  *  under full-suite load (the assertion once read the days-view title),
@@ -88,10 +81,23 @@ function pickCells(): HTMLButtonElement[] {
   return Array.from(picker()?.querySelectorAll<HTMLButtonElement>(".hk-dtp-cell[data-variant='pick']") ?? []);
 }
 
-/** Generic state poll over the same drill race: wait until `probe` holds. */
+/** Generic state poll over the same drill race: wait until `probe` holds
+ *  STABLY. A single true evaluation can be a mid-transition transient
+ *  (the leaving pane's cells vanish one tick before its container
+ *  unmounts), so the probe must hold across a 10 ms window before the
+ *  wait resolves — otherwise the raw asserts after it race the teardown
+ *  timers (observed on the hosted runner: pickCount read 24 right after
+ *  a "settled" poll). */
 async function waitForView(desc: string, probe: () => boolean): Promise<void> {
   const deadline = Date.now() + 2000;
-  while (!probe()) {
+  let holdSince: number | null = null;
+  for (;;) {
+    if (probe()) {
+      holdSince ??= Date.now();
+      if (Date.now() - holdSince >= 10) return;
+    } else {
+      holdSince = null;
+    }
     if (Date.now() > deadline) throw new Error(`view never reached: ${desc}`);
     await new Promise((r) => setTimeout(r, 10));
   }
@@ -191,7 +197,6 @@ describe("HkDateTimePicker", () => {
     mountPicker();
     const monthBtn = picker()?.querySelectorAll<HTMLButtonElement>(".hk-dtp-title-btn")[0];
     monthBtn?.click();
-    await settle();
     // Destination state = the months pane mounted AND the leaving days
     // pane gone — mid-transition both conditions half-hold.
     await waitForView("the months grid settled to one pane", () =>
@@ -213,7 +218,6 @@ describe("HkDateTimePicker", () => {
     expect(stage?.children.length).toBe(1); // the single days pane
     const monthBtn = picker()?.querySelectorAll<HTMLButtonElement>(".hk-dtp-title-btn")[0];
     monthBtn?.click();
-    await settle();
     // Destination state = months pane mounted AND the leaving days pane
     // gone — mid-transition the cell counts already read final while the
     // stage still carries both panes.
@@ -223,13 +227,11 @@ describe("HkDateTimePicker", () => {
       stage?.children.length === 1);
     expect(stage?.getAttribute("data-dir")).toBe("fwd");
     expect(picker()?.querySelector<HTMLElement>(".hk-dtp-stage")).toBe(stage);
-    expect(stage?.children.length).toBe(1); // one pane at a time after settle
     // The time row lives outside the transitioned pane and stays in every
     // view, so the picker's footprint never changes.
     expect(picker()?.querySelectorAll(".hk-dtp-time").length).toBe(1);
     expect(picker()?.querySelectorAll(".hk-dtp-step").length).toBe(2);
     picker()?.querySelector<HTMLButtonElement>(".hk-dtp-back")?.click();
-    await settle();
     await waitForView("the days grid settled to one pane", () =>
       dayCells().length === 42 && stage?.children.length === 1);
     expect(stage?.getAttribute("data-dir")).toBe("back");
@@ -239,7 +241,6 @@ describe("HkDateTimePicker", () => {
     mountPicker();
     const monthBtn = picker()?.querySelectorAll<HTMLButtonElement>(".hk-dtp-title-btn")[0];
     monthBtn?.click();
-    await settle();
     await waitForTitle(String(BASE.getFullYear()));
     const navs = picker()?.querySelectorAll<HTMLButtonElement>(".hk-dtp-nav");
     navs?.[1].click();
@@ -254,7 +255,6 @@ describe("HkDateTimePicker", () => {
     mountPicker();
     const monthBtn = picker()?.querySelectorAll<HTMLButtonElement>(".hk-dtp-title-btn")[0];
     monthBtn?.click();
-    await settle();
     // Destination state = months pane mounted AND the leaving days pane
     // gone — mid-transition the cell counts already read final while the
     // stage still carries both panes.

package/src/components/HkFileBrowserDialog.scss

@@ -385,10 +385,14 @@
   text-align: start;
 }
 
-.hk-file-browser-list-head {
-  position: sticky;
-  top: 0;
-  z-index: 1;
+// The head is a scroll pin (class + data-side/data-strategy on the
+// element): positioning/z ride the shared .hk-scroll-pin rules, and the
+// doubled class keeps this explicit surface above the pin's default tint
+// regardless of stylesheet import order. Pinned under a gutter-cover
+// host (HkModal) it stops below the body's top whitespace instead of
+// jamming against the window chrome; the cover masks rows while they
+// pass under the gutter.
+.hk-file-browser-list-head.hk-scroll-pin {
   font-size: var(--text-xs);
   font-weight: 600;
   color: rgb(var(--color-muted));

package/src/components/HkFileBrowserDialog.tsx

@@ -30,6 +30,9 @@ import {
 } from "./filePicker";
 import HButton from "./HkButton";
 import HModal from "./HkModal";
+// The list head rides the scroll-pin contract; its stylesheet ships the
+// pin rules.
+import "./HkScrollPin.scss";
 import HSelect, { type HkSelectOption } from "./HkSelect";
 import HSpinner from "./HkSpinner";
 import "./HkFileBrowserDialog.scss";
@@ -657,7 +660,16 @@ export default defineComponent({
     function renderList(rows: RemoteFileEntry[]) {
       return (
         <div class="hk-file-browser-list">
-          <div class="hk-file-browser-list-head" aria-hidden="true">
+          {/* Scroll pin (static "offset"): rides the scroll host's gutter
+              contract so the pinned head keeps the body's top whitespace.
+              Under a host without the contract it degrades to a plain
+              flush sticky (the vars resolve to 0). */}
+          <div
+            class="hk-file-browser-list-head hk-scroll-pin"
+            data-side="top"
+            data-strategy="offset"
+            aria-hidden="true"
+          >
             <span class="hk-file-browser-col-name">
               {t("hikari::filePicker.name", "Name")}
             </span>

package/src/components/HkImageLightbox.scss

@@ -29,6 +29,14 @@
     max-height: none;
     display: flex;
     flex-direction: column;
+
+    // Immersive override: the body is un-padded here, so the pin contract's
+    // gutters (and the covers with them) collapse to zero too. Declared on
+    // the body so its own covers read them (inheritance runs downward).
+    --hk-scroll-pad-top: 0px;
+    --hk-scroll-pad-right: 0px;
+    --hk-scroll-pad-bottom: 0px;
+    --hk-scroll-pad-left: 0px;
   }
 
   .hk-modal-body-scroll {

package/src/components/HkModal.bodyrhythm.test.ts

@@ -35,6 +35,13 @@ describe("HkModal body rhythm contract", () => {
   });
 
   it("keeps the body padding hook unchanged", () => {
-    expect(inner).toContain("padding: var(--hk-modal-padding-body");
+    // 2026-09-14 scroll-pin contract: the padding consumes the declared
+    // --hk-scroll-pad-* vars (single source with the gutter covers and
+    // the pins); the vars themselves derive from --hk-modal-padding-body,
+    // so the host-tunable hook keeps working.
+    expect(inner).toContain("padding: var(--hk-scroll-pad-top");
+    // The old direct source must stay retired — a stale literal here
+    // would desync the pins from the padding.
+    expect(inner).not.toContain("padding: var(--hk-modal-padding-body");
   });
 });

package/src/components/HkModal.scss

@@ -240,6 +240,51 @@
   color: var(--hk-modal-body-color, var(--hi-color-text-primary, #1e1e1e));
   flex: 1;
   min-height: 0;
+
+  // Scroll-pin host contract: the body padding physically lives on
+  // .hk-modal-body-inner (a child of the scroller), where sticky can
+  // never hold it in place — pins read these instead, and the gutter
+  // covers below consume the same vars. Declared HERE (the scroller's
+  // parent): custom properties inherit downward, so the covers, the
+  // scroller and the inner all resolve them. The mobile sheet block
+  // retunes the vars only.
+  --hk-scroll-pad-top: var(--hk-modal-padding-body, 1.5rem);
+  --hk-scroll-pad-right: var(--hk-modal-padding-body, 1.5rem);
+  --hk-scroll-pad-bottom: var(--hk-modal-padding-body, 1.5rem);
+  --hk-scroll-pad-left: var(--hk-modal-padding-body, 1.5rem);
+
+  // Gutter covers (scroll-pin contract, 2026-09-14): the body's top and
+  // bottom whitespace stays paintable OUTSIDE the scroll flow, so a
+  // pinned child (HkScrollPin strategy="offset") stops below the gutter
+  // with the whitespace intact, and scrolled content vanishes under the
+  // cover instead of sliding through a see-through gap. At rest the
+  // covers sit over empty padding — same surface color, invisible.
+  &::before,
+  &::after {
+    content: "";
+    position: absolute;
+    left: 0;
+    right: 0;
+    z-index: 3;
+    pointer-events: none;
+    // Same paint source as the content frame by default; a host that
+    // re-themes the body itself overrides --hk-scroll-pin-cover-bg so the
+    // covers never surface as foreign bands over the padding.
+    background: var(
+      --hk-scroll-pin-cover-bg,
+      var(--hk-modal-bg, var(--hi-color-surface, rgba(240, 244, 248, 0.95)))
+    );
+  }
+
+  &::before {
+    top: 0;
+    height: var(--hk-scroll-pad-top, 0px);
+  }
+
+  &::after {
+    bottom: 0;
+    height: var(--hk-scroll-pad-bottom, 0px);
+  }
 }
 
 .hk-modal-body-scroll {
@@ -258,7 +303,8 @@
 }
 
 .hk-modal-body-inner {
-  padding: var(--hk-modal-padding-body, 1.5rem);
+  padding: var(--hk-scroll-pad-top, 1.5rem) var(--hk-scroll-pad-right, 1.5rem)
+    var(--hk-scroll-pad-bottom, 1.5rem) var(--hk-scroll-pad-left, 1.5rem);
 
   // Default vertical rhythm between bare stacked children (user direction
   // 2026-09-08: window bodies keep a little distance between their elements
@@ -428,8 +474,13 @@
     padding: 0.625rem 1rem 0.625rem;
   }
 
-  .hk-modal-body-inner {
-    padding: 1rem;
+  // The gutter contract retunes here too — the covers and the inner's
+  // padding both consume the vars, so one override moves both.
+  .hk-modal-body {
+    --hk-scroll-pad-top: 1rem;
+    --hk-scroll-pad-right: 1rem;
+    --hk-scroll-pad-bottom: 1rem;
+    --hk-scroll-pad-left: 1rem;
   }
 
   // Lift the desktop 70vh body cap on phones: with a docked sheet the cap

package/src/components/HkModal.sheetgap.test.ts

@@ -52,7 +52,10 @@ describe("HkModal mobile sheet spacing contract", () => {
     beforeAll(() => {
       block = src.slice(src.indexOf("@media (max-width: 767px)"));
       content = block.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
-      body = block.match(/\.hk-modal-body\s*{[^}]*}/)?.[0] ?? "";
+      // 2026-09-14: the sheet block carries more than one .hk-modal-body
+      // rule (the scroll-pin gutter-var override + the body-cap lift) —
+      // assertions below must see both, so concatenate them all.
+      body = (block.match(/\.hk-modal-body\s*{[^}]*}/g) ?? []).join("\n");
       footer = block.match(/\.hk-modal-footer\s*{[\s\S]*?^  }/m)?.[0] ?? "";
     });
 

package/src/components/HkModal.tsx

@@ -804,7 +804,13 @@ export default defineComponent({
                   <div ref={bodyRef} class="hk-modal-body">
                     <div
                       ref={scrollContainerRef}
-                      class="hk-modal-body-scroll"
+                      class="hk-modal-body-scroll hk-scroll-pin-host"
+                      data-scroll-axis="vertical"
+                      // The body gutters (top/bottom whitespace) are painted
+                      // by .hk-modal-body's covers, so pins stop at the
+                      // gutter line instead of absorbing the padding (see
+                      // HkScrollPin's strategy contract).
+                      data-pad-cover=""
                       onScroll={onBodyScroll}
                     >
                       <div ref={innerRef} class="hk-modal-body-inner">

package/src/components/HkScrollContainer.tsx

@@ -15,6 +15,7 @@ import "./HkScrollContainer.scss";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useApproachEnd, type ApproachEndHandle } from "../composables/useApproachEnd";
 import { provideScrollWindow } from "../composables/useScrollWindow";
+import { SCROLL_HOST_CLASS } from "./HkScrollPin";
 import { scheduleFrame, notifyScrollStart, onceFrame, type AnimationHandle } from "../runtime/animationBus";
 import HFab from "./HkFab";
 
@@ -437,7 +438,15 @@ export default defineComponent({
           data-align={alignCenter() ? "center" : undefined}
           data-fade={props.fade ? "true" : undefined}
         >
-          <div ref={viewportRef} class="hk-scroll-container-viewport">
+          {/* Scroll-pin host marker: the viewport participates in the pin
+              contract with its live axis; generic containers declare no
+              standard padding, so pins inside resolve their strategy from
+              whatever --hk-scroll-pad-* the consumer put on this viewport. */}
+          <div
+            ref={viewportRef}
+            class={["hk-scroll-container-viewport", SCROLL_HOST_CLASS]}
+            data-scroll-axis={props.axis}
+          >
             {content}
           </div>
           {showAutoTag.value && (

package/src/components/HkScrollPin.scrollcontract.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Source contract: THE SCROLL-PIN WHITESPACE CONTRACT (2026-09-14 user
+ * report — the wizard's step header pinned flush against the modal
+ * header because the body padding lives on .hk-modal-body-inner, a
+ * wrapper child of the scroller; CSS sticky resolves its offsets against
+ * the scrollport and never sees wrapper padding, so the pinned header
+ * lost its whitespace the moment it engaged).
+ *
+ * The contract has two halves that must stay in sync:
+ *  1. HOSTS declare `--hk-scroll-pad-*` on the scrolling viewport (class
+ *     .hk-scroll-pin-host) and, when they paint their gutters themselves,
+ *     carry `data-pad-cover` — pins then stop at the gutter line.
+ *  2. PINS (HkScrollPin / .hk-scroll-pin) absorb or respect the declared
+ *     padding per strategy; the bleed strategy's negative margin + padding
+ *     pair is the load-bearing geometry and must never lose a side.
+ *
+ * Verified live in headless Chromium before pinning here: padding on the
+ * scroller itself pins sticky children BELOW the padding (probe 2);
+ * padding on a wrapper does not (probe 1) — hence the declared-vars
+ * contract instead of "just move the padding".
+ */
+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 read = (name: string) => readFileSync(join(here, name), "utf-8");
+
+const pinScss = read("HkScrollPin.scss");
+const modalScss = read("HkModal.scss");
+const modalTsx = read("HkModal.tsx");
+const stepflowScss = read("HkStepFlow.scss");
+const stepflowTsx = read("HkStepFlow.tsx");
+const fileBrowserScss = read("HkFileBrowserDialog.scss");
+const fileBrowserTsx = read("HkFileBrowserDialog.tsx");
+const scrollContainerTsx = read("HkScrollContainer.tsx");
+
+/** Extract ONE balanced `{...}` declaration block following the given
+ *  selector — a naive `[^}]*` would stop at the first nested `}` and let
+ *  properties appended after a future nested block evade the pin. */
+function cssBlock(src: string, selector: string): string {
+  const at = src.indexOf(selector);
+  expect(at, `${selector} block exists`).toBeGreaterThanOrEqual(0);
+  const open = src.indexOf("{", at);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === "{") depth++;
+    else if (src[i] === "}") {
+      depth--;
+      if (depth === 0) return src.slice(open, i + 1);
+    }
+  }
+  return "";
+}
+
+describe("scroll-pin whitespace contract", () => {
+  it("the pin base is sticky with a floating-chrome surface", () => {
+    const base = cssBlock(pinScss, ".hk-scroll-pin {");
+    expect(base).toMatch(/position: sticky/);
+    expect(base).toMatch(/z-index: var\(--hk-scroll-pin-z/);
+    expect(base).toMatch(/background: var\(\s*--hk-scroll-pin-bg/);
+  });
+
+  it("every side x strategy pairing exists (12 total)", () => {
+    for (const strategy of ["offset", "bleed", "none"]) {
+      for (const side of ["top", "bottom", "left", "right"]) {
+        const selector = `.hk-scroll-pin[data-strategy="${strategy}"][data-side="${side}"]`;
+        expect(pinScss, selector).toContain(selector);
+      }
+    }
+  });
+
+  it("the bleed strategy pairs padding with the negative margin per side", () => {
+    // The load-bearing geometry: absorb the host's declared padding so the
+    // whitespace travels with the pin. Losing any half of a pair would
+    // shift the pin's content at rest (padding without margin) or overlap
+    // siblings (margin without padding).
+    for (const side of ["top", "bottom", "left", "right"]) {
+      const block = cssBlock(
+        pinScss,
+        `.hk-scroll-pin[data-strategy="bleed"][data-side="${side}"]`,
+      );
+      expect(block, `bleed ${side} padding`).toMatch(
+        new RegExp(`padding-${side}: var\\(--hk-scroll-pad-${side}`),
+      );
+      expect(block, `bleed ${side} negative margin`).toMatch(
+        new RegExp(
+          `margin-${side}: calc\\(-1 \\* var\\(--hk-scroll-pad-${side}`,
+        ),
+      );
+    }
+  });
+
+  it("the offset strategy stops at the declared gutter line per side", () => {
+    for (const side of ["top", "bottom", "left", "right"]) {
+      const block = cssBlock(
+        pinScss,
+        `.hk-scroll-pin[data-strategy="offset"][data-side="${side}"]`,
+      );
+      expect(block).toMatch(new RegExp(`${side}: var\\(--hk-scroll-pad-${side}`));
+    }
+  });
+
+  it("HkModal declares the four pad vars on .hk-modal-body (host contract)", () => {
+    // Declared on the BODY — the covers are the body's own pseudo rules
+    // and custom properties inherit downward only, so the scroller (a
+    // child) could never feed them. The FULL literal is pinned (var name
+    // AND the 1.5rem fallback): a silently changed default would desync
+    // the covers from the padding while every selector still matches.
+    const body = cssBlock(modalScss, ".hk-modal-body {");
+    for (const side of ["top", "right", "bottom", "left"]) {
+      expect(body, `--hk-scroll-pad-${side}`).toContain(
+        `--hk-scroll-pad-${side}: var(--hk-modal-padding-body, 1.5rem);`,
+      );
+    }
+  });
+
+  it("HkModal's body-inner consumes the same vars (one source of truth)", () => {
+    const inner = cssBlock(modalScss, ".hk-modal-body-inner {");
+    expect(inner).toMatch(/padding: var\(--hk-scroll-pad-top/);
+    expect(inner).toMatch(/var\(--hk-scroll-pad-left/);
+    // The old direct fallback must be gone — a stale `1.5rem` literal in
+    // the shorthand would desync the gutter covers from the padding.
+    expect(inner).not.toMatch(/padding: 1\.5rem/);
+    expect(inner).not.toMatch(/padding: var\(--hk-modal-padding-body/);
+  });
+
+  it("HkModal paints gutter covers from the same vars", () => {
+    expect(modalScss).toMatch(/&::before,\s*\n\s*&::after/);
+    // Anchor on the standalone pseudo blocks INSIDE .hk-modal-body — the
+    // combined selector ("&::before,\n &::after {") contains "&::after {"
+    // as a literal, so a bare indexOf would match the shared rule instead.
+    const bodyBlock = cssBlock(modalScss, ".hk-modal-body {");
+    expect(bodyBlock).toMatch(
+      /&::before \{\s*top: 0;\s*height: var\(--hk-scroll-pad-top/,
+    );
+    expect(bodyBlock).toMatch(
+      /&::after \{\s*bottom: 0;\s*height: var\(--hk-scroll-pad-bottom/,
+    );
+  });
+
+  it("the mobile sheet retunes the vars instead of the inner padding", () => {
+    // Grab the media-query block's body override.
+    const at = modalScss.indexOf(".hk-modal-body {", modalScss.indexOf("@media (max-width: 767px)"));
+    expect(at).toBeGreaterThan(-1);
+    const block = cssBlock(modalScss.slice(at), ".hk-modal-body {");
+    expect(block).toMatch(/--hk-scroll-pad-top: 1rem;/);
+    expect(block).toMatch(/--hk-scroll-pad-left: 1rem;/);
+  });
+
+  it("HkModal marks the scroller as a cover host in the tsx", () => {
+    expect(modalTsx).toMatch(/class="hk-modal-body-scroll hk-scroll-pin-host"/);
+    expect(modalTsx).toMatch(/data-scroll-axis="vertical"/);
+    expect(modalTsx).toMatch(/data-pad-cover=""/);
+  });
+
+  it("HkImageLightbox zeroes the contract for its un-padded body", () => {
+    const lightbox = readFileSync(join(here, "HkImageLightbox.scss"), "utf-8");
+    expect(lightbox).toMatch(/--hk-scroll-pad-top: 0px;/);
+    expect(lightbox).toMatch(/--hk-scroll-pad-bottom: 0px;/);
+  });
+
+  it("HkStepFlow delegates sticky positioning to the pin class", () => {
+    const sticky = cssBlock(
+      stepflowScss,
+      ".hk-step-flow[data-sticky-header] > .hk-timeline.hk-scroll-pin {",
+    );
+    expect(sticky).toBeTruthy();
+    // The delegation: no own position/sticky — that lives on .hk-scroll-pin.
+    expect(sticky).not.toMatch(/position:\s*sticky/);
+    expect(sticky).not.toMatch(/backdrop-filter/);
+    // The step-flow specifics stay: the folded body gap + legacy knobs.
+    expect(sticky).toMatch(/padding-bottom: var\(--hk-stepflow-header-gap/);
+    expect(sticky).toMatch(/--hk-scroll-pin-z: var\(--hk-stepflow-sticky-z/);
+    expect(sticky).toMatch(/--hk-scroll-pin-bg: var\(\s*--hk-stepflow-sticky-bg/);
+    // And the raw selector is gone (it would double-apply without the pin).
+    expect(stepflowScss).not.toMatch(/\.hk-step-flow\[data-sticky-header\] > \.hk-timeline \{/);
+  });
+
+  it("HkStepFlow stamps the pin class and side on the timeline root", () => {
+    expect(stepflowTsx).toMatch(/class=\{props\.stickyHeader \? "hk-scroll-pin" : undefined\}/);
+    expect(stepflowTsx).toMatch(/data-side=\{props\.stickyHeader \? "top" : undefined\}/);
+    // Strategy resolves on mount (cover host → "offset", else "bleed").
+    expect(stepflowTsx).toMatch(/data-strategy=\{props\.stickyHeader \? pinStrategy\.value : undefined\}/);
+    expect(stepflowTsx).toMatch(/pinStrategy\.value = "offset"/);
+    expect(stepflowTsx).toMatch(/hasAttribute\("data-pad-cover"\)/);
+    expect(stepflowTsx).toMatch(/import "\.\/HkScrollPin\.scss";/);
+  });
+
+  it("the file-browser list head is a pin and owns no sticky of its own", () => {
+    const head = cssBlock(fileBrowserScss, ".hk-file-browser-list-head.hk-scroll-pin {");
+    expect(head).toBeTruthy();
+    expect(head).not.toMatch(/position:\s*sticky/);
+    expect(head).not.toMatch(/top:\s*0/);
+    expect(head).toMatch(/background: rgb\(var\(--color-surface\)\)/);
+    expect(fileBrowserTsx).toMatch(/data-strategy="offset"/);
+  });
+
+  it("HkScrollContainer marks its viewport as a pin host", () => {
+    expect(scrollContainerTsx).toMatch(/SCROLL_HOST_CLASS/);
+    expect(scrollContainerTsx).toMatch(/data-scroll-axis=\{props\.axis\}/);
+  });
+});

package/src/components/HkScrollPin.scss

@@ -0,0 +1,109 @@
+// HkScrollPin.scss
+// The pinned-content contract between a scroll host and its pins.
+//
+// HOST declares (on the scrolling viewport, class .hk-scroll-pin-host):
+//   --hk-scroll-pad-top/right/bottom/left  the padding that pinned
+//     children must keep between themselves and the host's edge;
+//   data-scroll-axis="vertical|horizontal|both"  which sides may pin;
+//   data-pad-cover  present when the host paints its gutters itself
+//     (HkModal) — pins may simply stop at the gutter line ("offset").
+// PIN declares: data-side, data-strategy (resolved by the component).
+//
+// The 2026-09-14 bug this standardizes away: a sticky child pinned
+// inside a host whose padding lives on an in-flow wrapper loses the
+// padding the moment it pins (CSS sticky offsets resolve against the
+// scrollport, never against a wrapper's padding), so the pinned element
+// sat flush against the window chrome.
+
+.hk-scroll-pin {
+  position: sticky;
+  z-index: var(--hk-scroll-pin-z, 10);
+  // Floating-chrome surface: near-opaque surface tint + blur so scrolled
+  // content never bleeds through the pinned row (same look the step-flow
+  // sticky header introduced; hosts retune through --hk-scroll-pin-bg).
+  background: var(
+    --hk-scroll-pin-bg,
+    color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 95%, transparent)
+  );
+  backdrop-filter: var(--hk-scroll-pin-blur, blur(6px));
+}
+
+// ------
+// "offset" — the host paints its gutters; the pin stops at the gutter
+// line. Works for pins anywhere in the flow (no margin games), and the
+// host's cover hides scrolled content while it passes under the gutter.
+// ------
+
+.hk-scroll-pin[data-strategy="offset"][data-side="top"] {
+  top: var(--hk-scroll-pad-top, 0px);
+}
+
+.hk-scroll-pin[data-strategy="offset"][data-side="bottom"] {
+  bottom: var(--hk-scroll-pad-bottom, 0px);
+}
+
+.hk-scroll-pin[data-strategy="offset"][data-side="left"] {
+  left: var(--hk-scroll-pad-left, 0px);
+}
+
+.hk-scroll-pin[data-strategy="offset"][data-side="right"] {
+  right: var(--hk-scroll-pad-right, 0px);
+}
+
+// ------
+// "bleed" — the host's padding lives in the scroll flow (a wrapper
+// child); the pin absorbs it with padding + negative margin so its own
+// background paints over the padding zone and the whitespace pins
+// together with the content. Verified geometry (headless Chromium):
+// at rest the pin's CONTENT stays at its natural position (the negative
+// margin cancels the added padding exactly); pinned, the border box
+// rests flush at the scrollport edge with the padding painted.
+// Boundary contract: a top bleed pin must be the first element of the
+// scroll content, a bottom bleed pin the last — otherwise the negative
+// margin overlaps a sibling.
+// ------
+
+.hk-scroll-pin[data-strategy="bleed"][data-side="top"] {
+  top: 0;
+  padding-top: var(--hk-scroll-pad-top, 0px);
+  margin-top: calc(-1 * var(--hk-scroll-pad-top, 0px));
+}
+
+.hk-scroll-pin[data-strategy="bleed"][data-side="bottom"] {
+  bottom: 0;
+  padding-bottom: var(--hk-scroll-pad-bottom, 0px);
+  margin-bottom: calc(-1 * var(--hk-scroll-pad-bottom, 0px));
+}
+
+.hk-scroll-pin[data-strategy="bleed"][data-side="left"] {
+  left: 0;
+  padding-left: var(--hk-scroll-pad-left, 0px);
+  margin-left: calc(-1 * var(--hk-scroll-pad-left, 0px));
+}
+
+.hk-scroll-pin[data-strategy="bleed"][data-side="right"] {
+  right: 0;
+  padding-right: var(--hk-scroll-pad-right, 0px);
+  margin-right: calc(-1 * var(--hk-scroll-pad-right, 0px));
+}
+
+// ------
+// "none" — plain sticky flush at the edge: hosts without a declared
+// padding contract, and consumers opting out.
+// ------
+
+.hk-scroll-pin[data-strategy="none"][data-side="top"] {
+  top: 0;
+}
+
+.hk-scroll-pin[data-strategy="none"][data-side="bottom"] {
+  bottom: 0;
+}
+
+.hk-scroll-pin[data-strategy="none"][data-side="left"] {
+  left: 0;
+}
+
+.hk-scroll-pin[data-strategy="none"][data-side="right"] {
+  right: 0;
+}

package/src/components/HkScrollPin.test.tsx

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkScrollPin, { SCROLL_HOST_CLASS, type ScrollPinSide, type ScrollPinStrategy } from "./HkScrollPin";
+
+/**
+ * HkScrollPin contract tests. House style: raw createApp mounts on shared
+ * containers torn down after each case (no @vue/test-utils).
+ *
+ * Geometry is NOT asserted here — happy-dom performs no real sticky
+ * layout. The whitespace contract (bleed absorption, offset gutter line)
+ * is pinned by the source-contract test and was verified in headless
+ * Chromium (scroll-padding-on-wrapper vs on-scroller probes).
+ */
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts) app.unmount();
+  mounts.length = 0;
+  for (const c of containers) c.remove();
+  containers.length = 0;
+  vi.restoreAllMocks();
+});
+
+async function mountPin(options: {
+  side?: ScrollPinSide;
+  strategy?: ScrollPinStrategy;
+  hostAttrs?: Record<string, string>;
+  noHost?: boolean;
+  content?: string;
+} = {}): Promise<{ container: HTMLElement; el: HTMLElement | null }> {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const host = document.createElement("div");
+  host.className = SCROLL_HOST_CLASS;
+  for (const [k, v] of Object.entries(options.hostAttrs ?? {})) {
+    host.setAttribute(k, v);
+  }
+  const slot = ref(options.content ?? "pinned");
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkScrollPin, {
+          side: options.side ?? "top",
+          strategy: options.strategy ?? "auto",
+        }, { default: () => h("span", slot.value) });
+    },
+  });
+  if (!options.noHost) host.appendChild(container);
+  const app = createApp(Wrapper);
+  app.mount(container);
+  mounts.push(app);
+  // Strategy resolution runs onMounted and flips data-strategy via a
+  // reactive re-render — the mutation lands one flush AFTER the mount
+  // job, so it takes two ticks to reach the DOM.
+  await nextTick();
+  await nextTick();
+  return { container, el: container.querySelector(".hk-scroll-pin") };
+}
+
+describe("HkScrollPin", () => {
+  it("renders the pin wrapper with its side and slot content", async () => {
+    const { el } = await mountPin({ side: "bottom", content: "x" });
+    expect(el).toBeTruthy();
+    expect(el!.dataset.side).toBe("bottom");
+    expect(el!.textContent).toContain("x");
+  });
+
+  it("auto resolves to offset under a cover host with a declared pad", async () => {
+    const { el } = await mountPin({
+      side: "top",
+      hostAttrs: { "data-scroll-axis": "vertical", "data-pad-cover": "" },
+    });
+    // happy-dom resolves no custom properties; the component treats a
+    // cover host WITHOUT a resolvable pad as not covered — bleed is the
+    // safe default (a zero-var bleed is a plain sticky).
+    expect(["offset", "bleed"]).toContain(el!.dataset.strategy);
+  });
+
+  it("auto resolves to bleed for a plain host", async () => {
+    const { el } = await mountPin({ hostAttrs: { "data-scroll-axis": "vertical" } });
+    expect(el!.dataset.strategy).toBe("bleed");
+  });
+
+  it("explicit strategy passes through untouched", async () => {
+    const { el } = await mountPin({ strategy: "none", hostAttrs: { "data-pad-cover": "" } });
+    expect(el!.dataset.strategy).toBe("none");
+  });
+
+  it("warns in dev when the side contradicts the host axis", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await mountPin({ side: "left", hostAttrs: { "data-scroll-axis": "vertical" } });
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(String(warn.mock.calls[0][0])).toMatch(/side="left".*vertical/);
+  });
+
+  it("does not warn when the side agrees with the host axis", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await mountPin({ side: "top", hostAttrs: { "data-scroll-axis": "vertical" } });
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("warns when there is no marked host under auto resolution", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await mountPin({ side: "top", noHost: true });
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(String(warn.mock.calls[0][0])).toMatch(/no .hk-scroll-pin-host ancestor/);
+  });
+});

package/src/components/HkScrollPin.tsx

@@ -0,0 +1,150 @@
+import { defineComponent, onMounted, ref, type PropType } from "vue";
+
+import "./HkScrollPin.scss";
+
+/** Which edge of the nearest scroll host the pinned content rides. A
+ *  vertical scroller pins top/bottom; a horizontal scroller pins
+ *  left/right (the component warns in dev when a side contradicts the
+ *  host's declared `data-scroll-axis`). */
+export type ScrollPinSide = "top" | "bottom" | "left" | "right";
+
+/**
+ * How the pin keeps the host's whitespace:
+ *
+ * - `"auto"` (default) — read the host: a host that paints its gutters
+ *   itself (`data-pad-cover`, HkModal) gets `"offset"`; every other host
+ *   gets `"bleed"`.
+ * - `"offset"` — stop at the host's declared gutter line
+ *   (`--hk-scroll-pad-*`); the host paints the zone above/below the pin,
+ *   so scrolled content vanishes under the whitespace instead of showing
+ *   through a gap. Works for pins anywhere in the flow (toolbars may
+ *   precede them).
+ * - `"bleed"` — absorb the host's in-flow padding into the pin itself
+ *   (`padding: var(--hk-scroll-pad-…) + negative margin`): the pin's own
+ *   background paints over the padding zone so the whitespace travels
+ *   with the pinned content. Only safe for boundary pins — a top bleed
+ *   pin must be the first element of the scroll content (a bottom bleed
+ *   pin the last) — a negative margin would otherwise overlap preceding
+ *   siblings.
+ * - `"none"` — plain `position: sticky` flush at the edge; the host has
+ *   no declared padding or the consumer opts out of the contract.
+ */
+export type ScrollPinStrategy = "auto" | "offset" | "bleed" | "none";
+
+/** Scroll hosts that participate in the pin contract mark their
+ *  viewport with this class (HkModal body scroller, HkScrollContainer
+ *  viewport) and may declare `--hk-scroll-pad-top/right/bottom/left`
+ *  plus `data-scroll-axis="vertical|horizontal|both"`. */
+export const SCROLL_HOST_CLASS = "hk-scroll-pin-host";
+
+const AXIS_OK: Record<string, ScrollPinSide[]> = {
+  vertical: ["top", "bottom"],
+  horizontal: ["left", "right"],
+  both: ["top", "bottom", "left", "right"],
+};
+
+/**
+ * Pinned scroll content with a guaranteed whitespace contract: content
+ * placed in an `HkScrollPin` rides one edge of the nearest scroll host
+ * and never scrolls away — and the host's padding travels WITH it, so
+ * the pinned element keeps its breathing room (the 2026-09-14 wizard
+ * report: the step header pinned flush against the modal header because
+ * the body padding scrolled away beneath it).
+ *
+ * The pin is a plain `position: sticky` wrapper — it must sit inside the
+ * host's scroll flow (not inside a `position: absolute`/`fixed`
+ * ancestor, and not inside an `overflow: hidden` ancestor between it and
+ * the host, which would break stickiness).
+ */
+export default defineComponent({
+  name: "HkScrollPin",
+  props: {
+    /** Edge of the scroll host to pin against. */
+    side: {
+      type: String as PropType<ScrollPinSide>,
+      default: "top",
+      validator: (v: string) => ["top", "bottom", "left", "right"].includes(v),
+    },
+    /** Whitespace strategy — see the type doc. `"auto"` resolves from
+     *  the host at mount and is what every consumer should default to. */
+    strategy: {
+      type: String as PropType<ScrollPinStrategy>,
+      default: "auto",
+      validator: (v: string) => ["auto", "offset", "bleed", "none"].includes(v),
+    },
+    /** Override the default stacking height (pins float above scroll
+     *  content; hosts retune through `--hk-scroll-pin-z`). */
+    z: { type: Number, default: undefined },
+  },
+  setup(props, { slots }) {
+    const rootRef = ref<HTMLElement | null>(null);
+    /** Strategy after `"auto"` resolution — rendered as data-strategy so
+     *  the SCSS has one total switch to key on. */
+    const resolved = ref<"offset" | "bleed" | "none">("bleed");
+    let warned = false;
+
+    function warnOnce(message: string): void {
+      if (warned || !import.meta.env?.DEV) return;
+      warned = true;
+      console.warn(`[HkScrollPin] ${message}`);
+    }
+
+    function resolveStrategy(): void {
+      const el = rootRef.value;
+      if (!el) return;
+      const host = el.closest(`.${SCROLL_HOST_CLASS}`);
+      if (host) {
+        const axis = host.getAttribute("data-scroll-axis");
+        const allowed = AXIS_OK[axis ?? ""] ?? AXIS_OK.both;
+        if (!allowed.includes(props.side)) {
+          warnOnce(
+            `side="${props.side}" contradicts the nearest scroll host axis "${axis ?? "unmarked"}" — ` +
+              `vertical scrollers pin top/bottom, horizontal scrollers pin left/right.`,
+          );
+        }
+      }
+      if (props.strategy !== "auto") {
+        resolved.value = props.strategy;
+        return;
+      }
+      const covered =
+        host !== null &&
+        host.hasAttribute("data-pad-cover") &&
+        padDeclared(host, props.side);
+      resolved.value = covered ? "offset" : "bleed";
+      if (host === null) {
+        // No marked host: the pin still sticks (nearest scroll ancestor),
+        // but the whitespace contract cannot resolve — tell the author.
+        warnOnce(
+          "no .hk-scroll-pin-host ancestor found — the pin sticks to its nearest scrollable ancestor " +
+            "without a whitespace contract; mark the scroll viewport (SCROLL_HOST_CLASS) to opt in.",
+        );
+      }
+    }
+
+    function padDeclared(host: Element, side: ScrollPinSide): boolean {
+      const value = getComputedStyle(host).getPropertyValue(`--hk-scroll-pad-${side}`).trim();
+      return value !== "" && value !== "0px";
+    }
+
+    onMounted(resolveStrategy);
+
+    // Runtime host swaps (teleports, conditional wrappers) re-resolve on
+    // the next mount only — a pin that changes host must be re-keyed by
+    // the consumer. No listeners are held, so unmount needs no teardown.
+
+    return () => {
+      return (
+        <div
+          ref={rootRef}
+          class="hk-scroll-pin"
+          data-side={props.side}
+          data-strategy={resolved.value}
+          style={props.z !== undefined ? { zIndex: String(props.z) } : undefined}
+        >
+          {slots.default?.()}
+        </div>
+      );
+    };
+  },
+});

package/src/components/HkStepFlow.scss

@@ -20,18 +20,24 @@
   margin-bottom: var(--hk-stepflow-header-gap, var(--space-16, 1rem));
 }
 
-// Sticky header mode: keeps the step indicator visible while the body
-// scrolls inside long modal hosts. Surface tint + blur approximate the
-// floating-chrome look; hosts retune through the custom properties.
-.hk-step-flow[data-sticky-header] > .hk-timeline {
-  position: sticky;
-  top: var(--hk-stepflow-sticky-top, 0px);
-  z-index: var(--hk-stepflow-sticky-z, 10);
-  background: var(
+// Sticky header mode: positioning, surface and the whitespace contract
+// live on the shared .hk-scroll-pin rules (HkScrollPin.scss) — the
+// timeline root carries the class plus data-side/data-strategy. This
+// block keeps only what is step-flow-specific: the body gap folded into
+// the pinned header's own padding (so the tint stays continuous while
+// the body scrolls underneath) and the legacy styling knobs mapped onto
+// the pin's custom properties. The doubled class selector must beat
+// .hk-scroll-pin's own declarations regardless of import order.
+.hk-step-flow[data-sticky-header] > .hk-timeline.hk-scroll-pin {
+  --hk-scroll-pin-z: var(--hk-stepflow-sticky-z, 10);
+  --hk-scroll-pin-bg: var(
     --hk-stepflow-sticky-bg,
     color-mix(in srgb, var(--hi-color-surface, #f0f4f8) 95%, transparent)
   );
-  backdrop-filter: blur(6px);
+  // --hk-stepflow-sticky-top lifts the pin below a host chrome edge; this
+  // doubled selector outranks .hk-scroll-pin's own `top:` in every
+  // strategy, so the knob always wins when set.
+  top: var(--hk-stepflow-sticky-top, 0px);
   margin-bottom: 0;
   padding-bottom: var(--hk-stepflow-header-gap, var(--space-16, 1rem));
 }

package/src/components/HkStepFlow.test.tsx

@@ -244,3 +244,52 @@ describe("HkStepFlow", () => {
     await settle();
   });
 });
+
+// ── Sticky-header pin strategy resolution (2026-09-14 scroll-pin wave) ──
+// The timeline root rides HkScrollPin's contract; the strategy must flip
+// to "offset" when the nearest host paints its gutters (data-pad-cover,
+// HkModal) and stay "bleed" under a plain host. Behavioral, not
+// tautological: happy-dom resolves the attribute scan fine (no custom
+// properties involved).
+describe("HkStepFlow sticky-header pin strategy", () => {
+  async function mountWithHost(hostAttrs: Record<string, string> | null) {
+    const container = document.createElement("div");
+    const host = document.createElement("div");
+    host.className = "hk-scroll-pin-host";
+    for (const [k, v] of Object.entries(hostAttrs ?? {})) host.setAttribute(k, v);
+    host.appendChild(container);
+    document.body.appendChild(host);
+    containers.push(host);
+    const current = ref("a");
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkStepFlow, {
+            steps: STEPS,
+            modelValue: current.value,
+            stickyHeader: true,
+            "onUpdate:modelValue": (key: string) => { current.value = key; },
+          }, { a: () => h("p", "a"), b: () => h("p", "b"), c: () => h("p", "c"), d: () => h("p", "d") });
+      },
+    });
+    const app = createApp(Wrapper);
+    app.mount(container);
+    mounts.push(app);
+    // Resolution runs onMounted; the flip lands one flush later.
+    await nextTick();
+    await nextTick();
+    return container.querySelector<HTMLElement>(".hk-timeline");
+  }
+
+  it("resolves offset under a cover host (HkModal-style)", async () => {
+    const tl = await mountWithHost({ "data-pad-cover": "", "data-scroll-axis": "vertical" });
+    expect(tl!.dataset.strategy).toBe("offset");
+    expect(tl!.dataset.side).toBe("top");
+    expect(tl!.classList.contains("hk-scroll-pin")).toBe(true);
+  });
+
+  it("keeps bleed under a plain host", async () => {
+    const tl = await mountWithHost({ "data-scroll-axis": "vertical" });
+    expect(tl!.dataset.strategy).toBe("bleed");
+  });
+});

package/src/components/HkStepFlow.tsx

@@ -1,8 +1,13 @@
-import { defineComponent, Transition, watch, ref, type PropType } from "vue";
+import { defineComponent, Transition, onMounted, ref, watch, type PropType } from "vue";
 
 import HkTimeline from "./HkTimeline";
 import type { TimelineCollapse, TimelineStep } from "./HkTimeline";
+import { SCROLL_HOST_CLASS } from "./HkScrollPin";
 
+// Sticky header mode rides the shared scroll-pin contract (class + data
+// attributes on the timeline root); the pin stylesheet ships those
+// styles, so it is imported here directly.
+import "./HkScrollPin.scss";
 import "./HkStepFlow.scss";
 
 /** Scoped argument every step-keyed slot receives. */
@@ -34,7 +39,13 @@ export default defineComponent({
     /**
      * Pin the header to the top of the nearest scroll container (modal
      * body hosts) so the step indicator stays visible over long bodies.
-     * Styling knobs: --hk-stepflow-sticky-top/-z/-bg.
+     * The header rides the shared scroll-pin contract (HkScrollPin's
+     * class + data attributes on the timeline root): inside a host that
+     * declares the padding contract the header keeps the body's top
+     * whitespace when pinned instead of sitting flush against the
+     * window chrome (2026-09-14 wizard report). Legacy styling knobs
+     * --hk-stepflow-sticky-top/-z/-bg keep working through the pin's
+     * custom properties.
      */
     stickyHeader: { type: Boolean, default: false },
     collapse: {
@@ -78,6 +89,24 @@ export default defineComponent({
       },
     );
 
+    // Sticky-header whitespace strategy (2026-09-14): the timeline is the
+    // flow's boundary element, but content may sit ABOVE the whole flow
+    // inside the same scroll body — a bleed pin's negative margin would
+    // overlap it. Inside a host that paints its gutters (`data-pad-cover`,
+    // HkModal) the pin therefore stops at the gutter line ("offset",
+    // overlap-free anywhere in the flow); every other host keeps "bleed",
+    // where the flow is the de-facto boundary element. Resolution happens
+    // on mount (attribute scan only — no geometry), so CSR surfaces see
+    // the attribute flip once right after hydration; hikari renders
+    // client-side only.
+    const flowRef = ref<HTMLDivElement | null>(null);
+    const pinStrategy = ref<"offset" | "bleed">("bleed");
+
+    onMounted(() => {
+      const host = flowRef.value?.closest(`.${SCROLL_HOST_CLASS}`);
+      if (host?.hasAttribute("data-pad-cover")) pinStrategy.value = "offset";
+    });
+
     return () => {
       const index = indexOf(props.modelValue);
       // An unknown key finds no slot: the body simply renders empty, no
@@ -87,6 +116,7 @@ export default defineComponent({
 
       return (
         <div
+          ref={flowRef}
           class="hk-step-flow"
           data-sticky-header={props.stickyHeader || undefined}
         >
@@ -97,6 +127,9 @@ export default defineComponent({
               clickable={props.timelineClickable}
               collapse={props.collapse}
               onSelect={(key: string) => emit("update:modelValue", key)}
+              class={props.stickyHeader ? "hk-scroll-pin" : undefined}
+              data-side={props.stickyHeader ? "top" : undefined}
+              data-strategy={props.stickyHeader ? pinStrategy.value : undefined}
             />
           )}
           <Transition

package/src/index.ts

@@ -99,6 +99,8 @@ export { default as HTimeline } from "./components/HkTimeline";
 export { default as HTitleBar } from "./components/HkTitleBar";
 export { default as HStepFlow } from "./components/HkStepFlow";
 export type { StepFlowSlotProps } from "./components/HkStepFlow";
+export { default as HScrollPin, SCROLL_HOST_CLASS } from "./components/HkScrollPin";
+export type { ScrollPinSide, ScrollPinStrategy } from "./components/HkScrollPin";
 
 // Media player kit
 export { default as HMediaPlayer, MEDIA_RATES } from "./components/HkMediaPlayer";