@celestia-island/hikari 0.55.324 → 0.55.327

package/package.json

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

package/src/animation/registerAnimations.ts

@@ -145,3 +145,9 @@ registerCssAnimation("hk-range-ribbon-pulse", { infinite: true });
 // prop's dot breathes while its state is in-flight — a settled dot sits
 // static. Reduced motion drops the loop (house pattern, see HkSkeleton).
 registerCssAnimation("hk-badge-dot-pulse", { infinite: true });
+// components/HkEdgeGlow.scss — the shared edge-glow breathe (loops
+// forever): the one painter behind HkScrollContainer's overflow glow and
+// any host-mounted band (the static selection hint keeps animate off).
+// Reduced motion keeps the band and drops the loop (house pattern, see
+// HkSkeleton); the global CSS-animation switch pauses it as usual.
+registerCssAnimation("hk-edge-glow-breathe", { infinite: true });

package/src/components/HkAdminShell.test.tsx

@@ -81,7 +81,14 @@ const setWidth = (w: number) => {
 function paddingInner(container: HTMLElement): HTMLElement | null | undefined {
   const viewport = container.querySelector(".hk-scroll-container-viewport")
     ?? container.querySelector(".hk-scroll-container");
-  return viewport?.firstElementChild as HTMLElement | null | undefined;
+  // The shell's fallback scroll-progress dock (2026-11-09) wraps the
+  // content with a display:contents scope — descend through it, the
+  // padding wrapper is still the viewport's only layout box.
+  let inner = viewport?.firstElementChild as HTMLElement | null | undefined;
+  if (inner?.classList.contains("hk-scroll-progress-dock-scope")) {
+    inner = inner.firstElementChild as HTMLElement;
+  }
+  return inner;
 }
 
 function mobileInnerPadding(container: HTMLElement): string {
@@ -240,10 +247,9 @@ describe("HkAdminShell", () => {
       { header: () => null, sidebar: NAV, content: CONTENT },
     ));
     // The padded inner wrapper exists INSIDE the scroll viewport (not as
-    // padding on the container itself).
-    const viewport = c.querySelector(".hk-scroll-container-viewport")
-      ?? c.querySelector(".hk-scroll-container");
-    const inner = viewport?.firstElementChild as HTMLElement | null | undefined;
+    // padding on the container itself) — behind the fallback dock's
+    // display:contents scope (see paddingInner).
+    const inner = paddingInner(c);
     expect(inner).toBeTruthy();
     expect(inner?.style.padding).toBe("2rem");
   });

package/src/components/HkAdminTablePage.tsx

@@ -1,6 +1,7 @@
 import { defineComponent, type Component, type PropType } from "vue";
 import { HAlert, HCard, HEmptyState, HSpinner, HTable, useI18n } from "@celestia-island/hikari";
 import HkCrossfade from "./HkCrossfade";
+import HkScrollProgressDock from "./HkScrollProgressDock";
 import { HkPageHeader } from "./HkPageHeader";
 import type { HkRowManageGate } from "./HkTable";
 
@@ -80,6 +81,24 @@ export const HkAdminTablePage = defineComponent({
      *  zero so a fresh or empty list shows no "共 0 条" flash. Pages
      *  that render their own count elsewhere set this false. */
     countReadout: { type: Boolean, default: true },
+    /** The page's own scroll-progress DOCK (user direction 2026-11-09:
+     *  the list large-component uses the dock itself). DEFAULT ON — the
+     *  page mounts an HkScrollProgressDock around the body crossfade so
+     *  the table (or a body-slot roster) self-registers against it and
+     *  the pill floats over the scrolling viewport; the crossfade's
+     *  generation swaps happen INSIDE the dock, so the registration
+     *  survives every exchange. A page under a shell fallback dock has
+     *  its OWN dock stand down automatically (the nested-dock rule
+     *  serves the outermost enabled dock — the fallback keeps the
+     *  pill); set `false` to demote the page — lists then fall through
+     *  to the nearest enabled dock above, if any. Layering: the shell
+     *  master switch (HkFaceShell `scrollProgress`) > this prop > the
+     *  dock's own `disabled`. Like every dock gate, the layering is
+     *  RESOLVED
+     *  ONCE at the dock's setup — hosts pass these statically, and a
+     *  runtime flip needs a remount (the HkScrollContainer prop
+     *  precedent). */
+    progressDock: { type: Boolean, default: true },
   },
   emits: {
     reorder: (_fromIndex: number, _toIndex: number) => true,
@@ -151,48 +170,55 @@ export const HkAdminTablePage = defineComponent({
               every host dissolves between them instead of popping. The
               key collapses loading-vs-empty into one "placeholder"
               generation: spinner → empty is a data arrival, not a slot
-              identity change worth animating. */}
-          <HkCrossfade
-            swapKey={
-              props.error ? "error"
-                : props.loading && !props.rows.length ? "placeholder"
-                  : !props.rows.length ? "placeholder"
-                    : "content"
-            }
-          >
-            {props.error ? (
-              <HAlert message={props.error} />
-            ) : props.loading && !props.rows.length ? (
-              <HSpinner center />
-            ) : !props.rows.length ? (
-              <HEmptyState
-                boxed
-                title={emptyTitle}
-                description={props.emptyDescription}
-              >
-                {emptySlots}
-              </HEmptyState>
-            ) : slots.body ? (
-              <div class="hk-admin-table-page-body">{slots.body()}</div>
-            ) : (
-              <HCard padded={false}>
-                <HTable
-                  columns={props.columns}
-                  rows={props.rows}
-                  rowKey={props.rowKey}
-                  total={props.total}
-                  draggable={props.draggable}
-                  manageable={props.manageable}
-                  onReorder={(from: number, to: number) => emit("reorder", from, to)}
-                  onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
-                    emit("manage", row, opener)
-                  }
+              identity change worth animating.
+              The whole exchange rides INSIDE this page's scroll-progress
+              dock (default on; `progressDock:false` demotes to a bare
+              passthrough): the dock must wrap the CROSSFADE, not sit in
+              a generation — a generation-scoped dock would unmount with
+              every swap and drop the registration. */}
+          <HkScrollProgressDock disabled={!props.progressDock}>
+            <HkCrossfade
+              swapKey={
+                props.error ? "error"
+                  : props.loading && !props.rows.length ? "placeholder"
+                    : !props.rows.length ? "placeholder"
+                      : "content"
+              }
+            >
+              {props.error ? (
+                <HAlert message={props.error} />
+              ) : props.loading && !props.rows.length ? (
+                <HSpinner center />
+              ) : !props.rows.length ? (
+                <HEmptyState
+                  boxed
+                  title={emptyTitle}
+                  description={props.emptyDescription}
                 >
-                  {slots}
-                </HTable>
-              </HCard>
-            )}
-          </HkCrossfade>
+                  {emptySlots}
+                </HEmptyState>
+              ) : slots.body ? (
+                <div class="hk-admin-table-page-body">{slots.body()}</div>
+              ) : (
+                <HCard padded={false}>
+                  <HTable
+                    columns={props.columns}
+                    rows={props.rows}
+                    rowKey={props.rowKey}
+                    total={props.total}
+                    draggable={props.draggable}
+                    manageable={props.manageable}
+                    onReorder={(from: number, to: number) => emit("reorder", from, to)}
+                    onManage={(row: Record<string, unknown>, opener: HTMLElement) =>
+                      emit("manage", row, opener)
+                    }
+                  >
+                    {slots}
+                  </HTable>
+                </HCard>
+              )}
+            </HkCrossfade>
+          </HkScrollProgressDock>
           {slots["create-modal"]?.()}
           {slots["edit-modal"]?.()}
         </div>

package/src/components/HkCalendarHeatmap.scss

@@ -24,20 +24,57 @@
     color: var(--hi-color-muted);
   }
 
-  // w-max + auto margins center the whole calendar (rail included) on
-  // wide cards while letting narrow screens scroll from the left edge —
-  // auto margins resolve to zero when the content overflows, so mobile
-  // keeps its natural scroll origin.
+  // The strip's scroll host is HkScrollContainer — the root element carries
+  // .hk-scroll-container PLUS this class. The native horizontal bar is gone
+  // (2026-11-08: the battle heatmap's platform bar was the last one in the
+  // chart family and read as an embedded widget); hikari's auto-hiding
+  // overlay scrollbar is the only bar, and the container's align="center"
+  // centers the calendar while it fits and lets it scroll when it does not
+  // (the old auto-margin recipe now lives there — do NOT re-add overflow
+  // here: a native bar would come back and the overlay chrome would stack
+  // under it).
+  //
+  // padding-bottom is the OVERLAY TRACK's strip, not breathing room: the
+  // shared chrome is positioned against this root (bottom: 2px, height:
+  // 6px), so 8px of padding keeps the bar BELOW the Sunday rail instead of
+  // painting over it while the strip scrolls.
   &-scroll {
     margin-top: 12px;
+    padding-bottom: 8px;
+  }
+
+  // ── Legacy plain-form fallback (Rust/WASM renderer) ──────────────────
+  // The Vue form mounted the strip on HkScrollContainer (above), but the
+  // Rust/WASM CalendarHeatmap (packages/components/src/data/calendar_heatmap.rs)
+  // still renders the pre-migration plain -.hk-calendar-heatmap-scroll div and
+  // reads THIS sheet through the generated vue-mirror. The mirror sheet no
+  // longer owns the plain form's overflow/centering, so restore the previous
+  // horizontal scrolling here for the plain form ONLY: a Vue strip carries
+  // .hk-scroll-container on the same element and never matches, so the
+  // overlay chrome can never be re-claimed by this rule. The platform bar is
+  // suppressed (the chart family's no-native-bar invariant) — until the Rust
+  // renderer migrates onto the shared scroll-container script this form
+  // scrolls by wheel/touch/keyboard without a visible bar, the same
+  // bar-less trade the suppression-only scrollers take.
+  &-scroll:not(.hk-scroll-container) {
     overflow-x: auto;
-    padding-bottom: 4px;
+    scrollbar-width: none;
+
+    &::-webkit-scrollbar {
+      display: none;
+    }
+
+    > .hk-calendar-heatmap-body {
+      margin-inline: auto;
+    }
   }
 
+  // width: max-content keeps the strip's natural extent (the container's
+  // aligner owns the centering, so no auto margins here — they would be
+  // resolved inside a box sized exactly to this element's content).
   &-body {
     display: flex;
     width: max-content;
-    margin-inline: auto;
     gap: 8px;
   }
 

package/src/components/HkCalendarHeatmap.test.tsx

@@ -1,9 +1,23 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, reactive } from "vue";
 
 import HkCalendarHeatmap from "./HkCalendarHeatmap";
 import { HEATMAP_LEVEL_OPACITY, shiftIso } from "./calendarHeatmap";
 
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Resolve after two animation frames: the scroll container coalesces its
+ *  sensing pass through the shared animationBus, whose rAF is scheduled one
+ *  frame ahead of the awaited callback. */
+const flushFrames = async () => {
+  await new Promise<void>((r) => requestAnimationFrame(() => r()));
+  await new Promise<void>((r) => requestAnimationFrame(() => r()));
+};
+
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
 
 function mount(node: ReturnType<typeof h>) {
@@ -381,3 +395,125 @@ describe("HkCalendarHeatmap", () => {
     }
   });
 });
+// ── Overlay scroll strip (2026-11-08) ────────────────────────────────────
+// The calendar body rides HkScrollContainer now: hikari's auto-hiding
+// overlay bar is the only bar, the strip opens focused on the NEWEST day
+// (anchor="end"), a host can opt back to the start, and a series
+// replacement re-parks at the end. happy-dom performs no layout, so the
+// strip's extent is stubbed and a dispatched scroll event runs the
+// container's coalesced sensing pass.
+describe("HkCalendarHeatmap overlay scroll strip", () => {
+  const stripOf = (c: HTMLElement): HTMLElement =>
+    c.querySelector<HTMLElement>(".hk-calendar-heatmap-scroll")!;
+  const viewportOf = (c: HTMLElement): HTMLElement =>
+    c.querySelector<HTMLElement>(".hk-scroll-container-viewport")!;
+
+  /** Mount a live render function (reactive props re-render — the range
+   *  switch test replaces the series). */
+  function mountLive(render: () => ReturnType<typeof h>): HTMLElement {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({ render });
+    app.mount(container);
+    mounts.push({ app, container });
+    return container;
+  }
+
+  /** Give the viewport a scrollable extent. Only the SIZES are stubbed:
+   *  the position stays happy-dom's settable scrollLeft, so the park's
+   *  write is observable exactly as a reader's scroll would be. */
+  function stubStrip(el: HTMLElement, scrollWidth: number, clientWidth: number) {
+    Object.defineProperties(el, {
+      scrollWidth: { configurable: true, get: () => scrollWidth },
+      clientWidth: { configurable: true, get: () => clientWidth },
+    });
+  }
+
+  it("mounts the overlay chrome over the strip, with the body still inside", () => {
+    const c = mount(
+      h(HkCalendarHeatmap, { days: daysFrom(CLEAN_HEAD_MON, 7), first: null }),
+    );
+    const strip = stripOf(c);
+    // The class contract survives (consumers style .hk-calendar-heatmap-scroll)
+    // and the element IS the scroll container root.
+    expect(strip.classList.contains("hk-scroll-container")).toBe(true);
+    // hikari's auto-hiding overlay track is the only bar…
+    expect(
+      c.querySelector('.hk-scrollbar-track[data-axis="horizontal"]'),
+    ).not.toBeNull();
+    // …the overflow glow is opted in (the strip hides days at its edges)…
+    expect(strip.getAttribute("data-overflow-glow")).toBe("true");
+    // …and the body still rides inside the scrolling viewport.
+    expect(viewportOf(c).querySelector(".hk-calendar-heatmap-body")).not.toBeNull();
+  });
+
+  it("keeps native overflow out of the Vue form (source contract)", () => {
+    const sheet = readFileSync(join(here, "HkCalendarHeatmap.scss"), "utf8");
+    // The -rail/-cells contract is pinned by calendarHeatmapRail.contract;
+    // this pin owns the STRIP rule the migration rewrote.
+    const scrollRule = sheet.match(/&-scroll \{[\s\S]*?\n  \}/)?.[0] ?? "";
+    expect(scrollRule, "the &-scroll rule still owns the strip box").toContain("&-scroll {");
+    // The Vue strip IS the HkScrollContainer root. Any overflow declaration
+    // in this rule would bring a NATIVE bar back on top of the overlay chrome
+    // (the 2026-11-08 regression this migration fixed).
+    expect(scrollRule).not.toMatch(/overflow/);
+    // The Rust/WASM renderer still renders the plain div, so the sheet keeps
+    // a fallback scroller for it — but ONLY off the container form, and the
+    // platform bar stays suppressed (the chart family's native-bar invariant;
+    // the Rust form is bar-less until it migrates onto the shared script).
+    const fallback =
+      sheet.match(/&-scroll:not\(\.hk-scroll-container\) \{[\s\S]*?\n  \}/)?.[0] ?? "";
+    expect(fallback, "the plain-form fallback must exist for the Rust mirror").not.toBe("");
+    expect(fallback).toContain("overflow-x: auto");
+    expect(fallback).toContain("scrollbar-width: none");
+    expect(fallback).toMatch(/&::-webkit-scrollbar\s*\{[\s\S]*?display:\s*none/);
+    expect(fallback, "the plain form keeps its centering").toContain("margin-inline: auto");
+  });
+
+  it("opens focused on the newest end (anchor=end parks the strip)", async () => {
+    const c = mount(
+      h(HkCalendarHeatmap, { days: daysFrom(CLEAN_HEAD_MON, 7), first: null }),
+    );
+    const viewport = viewportOf(c);
+    stubStrip(viewport, 300, 100);
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(viewport.scrollLeft, "parked at max = 300 - 100").toBe(200);
+  });
+
+  it("forwards anchor=start so a host can opt back to the oldest end", async () => {
+    const c = mount(
+      h(HkCalendarHeatmap, {
+        days: daysFrom(CLEAN_HEAD_MON, 7),
+        first: null,
+        anchor: "start",
+      }),
+    );
+    const viewport = viewportOf(c);
+    stubStrip(viewport, 300, 100);
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(viewport.scrollLeft).toBe(0);
+  });
+
+  it("re-parks at the end when the series is replaced (range switch)", async () => {
+    const state = reactive({ days: daysFrom(CLEAN_HEAD_MON, 7) });
+    const c = mountLive(() => h(HkCalendarHeatmap, { days: state.days, first: null }));
+    const viewport = viewportOf(c);
+    stubStrip(viewport, 300, 100);
+    viewport.dispatchEvent(new Event("scroll"));
+    await flushFrames();
+    expect(viewport.scrollLeft, "initial end focus").toBe(200);
+
+    // A reader scrolls back to the oldest day…
+    viewport.scrollLeft = 0;
+    // …then switches range: the new series must land on ITS newest end
+    // (the container's sticky anchor deliberately would not, since the
+    // reader is no longer parked — the days watcher is the deterministic
+    // re-park).
+    state.days = daysFrom("2025-11-01", 30);
+    await nextTick();
+    await nextTick();
+    expect(viewport.scrollLeft).toBe(200);
+  });
+});

package/src/components/HkCalendarHeatmap.tsx

@@ -1,6 +1,7 @@
-import { computed, defineComponent, type PropType } from "vue";
+import { computed, defineComponent, ref, watch, type PropType } from "vue";
 
 import { useI18n } from "../i18n/context";
+import HkScrollContainer from "./HkScrollContainer";
 import {
   calendarGrid,
   heatmapCellFill,
@@ -53,6 +54,18 @@ function fill(template: string, vars: Record<string, string | number>): string {
  * null = never). All math lives in ./calendarHeatmap (pure, pinned by
  * its own tests). The `toolbar` slot rides right of the legend — the
  * consumer's range tabs / controls belong there.
+ *
+ * Scrolling (2026-11-08): the calendar body rides HkScrollContainer
+ * (axis="horizontal", align="center") so the strip uses hikari's own
+ * auto-hiding overlay scrollbar and NEVER a native bar — a chart that
+ * paints a platform scrollbar reads as an embedded widget, and the
+ * battle heatmap's bar was the last one in the family. The container's
+ * `anchor` prop defaults to "end" here: the newest day is the reading
+ * interest, so the strip opens focused on it (and the `anchor` prop lets
+ * a host opt back to "start"), while the container's overflow glow marks
+ * the side that still hides days. A series replacement (range switch,
+ * refetch across midnight) re-parks at the end explicitly — see the
+ * days watcher.
  */
 export default defineComponent({
   name: "HkCalendarHeatmap",
@@ -72,6 +85,15 @@ export default defineComponent({
     /** Square-cell scale (GitHub-scale: a 53-week grid stays compact). */
     cellSize: { type: Number, default: 14 },
     cellGap: { type: Number, default: 3 },
+    /** Which end of the horizontal strip is focused first: the default
+     *  "end" opens on the NEWEST day (the reading interest — a year-wide
+     *  series otherwise starts at the oldest, faded edge, which is exactly
+     *  the "why is the chart empty-looking?" report this default answers).
+     *  Forwarded to HkScrollContainer's `anchor`; the days/range watcher
+     *  still re-parks at the end on a data change, so this prop changes the
+     *  INITIAL focus (and the sticky behaviour) rather than the re-park
+     *  contract. Pass "start" to restore the old GitHub-style origin. */
+    anchor: { type: String as PropType<"start" | "end">, default: "end" },
   },
   setup(props, { slots }) {
     const { t } = useI18n();
@@ -160,6 +182,38 @@ export default defineComponent({
         : undefined;
     });
 
+    // The strip's scroll host. Only the two handle members the heatmap
+    // uses are named (structural typing, the consumers' house convention):
+    // the end park and the sensing refresh.
+    const scroller = ref<{
+      scrollToEnd: (behavior?: ScrollBehavior) => void;
+      refresh: () => void;
+    } | null>(null);
+
+    /** Re-park at the newest day whenever the caller replaces the series —
+     *  a range switch (the toolbar tabs), a refetch across UTC midnight, a
+     *  totalled window. The container's `anchor="end"` only keeps a
+     *  viewport that ALREADY sits at the end, deliberately (it must never
+     *  fight a reader who scrolled back); switching range from mid-strip is
+     *  a data replacement, so "land on the newest" is made unconditional
+     *  here instead.
+     *
+     *  flush: "post" is load-bearing — the grid must have re-rendered (new
+     *  scrollWidth, possibly a narrower strip) before the target is
+     *  measured, or the park would aim at the previous range's extent.
+     *  refresh() then re-derives the overlay chrome from the same new
+     *  extent: a range that shrinks the series from overflowing to fitting
+     *  fires no scroll event, so without it the auto-hiding track could
+     *  stay painted over content that no longer overflows. */
+    watch(
+      () => props.days,
+      () => {
+        scroller.value?.scrollToEnd("auto");
+        scroller.value?.refresh();
+      },
+      { flush: "post" },
+    );
+
     return () => (
       <div class="hk-calendar-heatmap">
         {/* The legend row: the scale in the caller's one unit on the
@@ -191,10 +245,23 @@ export default defineComponent({
           {slots.toolbar?.({})}
         </div>
 
-        {/* The scroll wrapper centers the whole calendar (rail included)
-         * on wide cards while letting narrow screens scroll from the
-         * left edge (see the SCSS). */}
-        <div class="hk-calendar-heatmap-scroll">
+        {/* The strip rides HkScrollContainer: hikari's own auto-hiding
+         * overlay scrollbar is the ONLY bar (a native one would read as an
+         * embedded platform widget — the battle heatmap's last regression),
+         * align="center" keeps the whole calendar (rail included) centered
+         * while it fits and lets it scroll once it does not, and
+         * anchor="end" opens it focused on the newest day. The class stays
+         * on the container root, so consumers styling
+         * .hk-calendar-heatmap-scroll keep working; overflowGlow lights the
+         * side that still hides days. */}
+        <HkScrollContainer
+          ref={scroller}
+          class="hk-calendar-heatmap-scroll"
+          axis="horizontal"
+          align="center"
+          anchor={props.anchor}
+          overflowGlow
+        >
           <div class="hk-calendar-heatmap-body">
             {/* Weekday rail: the first (Monday) and last (Sunday) rows
              * carry the labels, the wowsp convention. */}
@@ -271,7 +338,7 @@ export default defineComponent({
               </div>
             </div>
           </div>
-        </div>
+        </HkScrollContainer>
       </div>
     );
   },

package/src/components/HkCardList.tsx

@@ -9,7 +9,7 @@ import HkTooltip from "./HkTooltip";
 import { hasRenderedContent } from "../runtime/hasRenderedContent";
 import { useMediaQuery } from "../runtime/useMediaQuery";
 import type { StatTone } from "./HkStatCard";
-import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressHandle } from "./HkScrollProgress";
+import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressHandle } from "./HkScrollProgressDock";
 import "./HkCardList.scss";
 
 /**
@@ -47,22 +47,22 @@ export const HkCardList = defineComponent({
   props: {
     /** Authoritative row total the scroll-progress pill uses as its
      *  denominator (the server count behind a windowed/infinite list).
-     *  Forwarded to the nearest enclosing HkScrollContainer with
-     *  `scrollProgress` on, exactly like HkAdminTablePage's `total`.
-     *  Omitted: the pill falls back to counting the delivered DOM rows
-     *  (right for fully-delivered lists, drifting low for windowed
-     *  ones — pass the server count there). */
+     *  Forwarded to the nearest enclosing enabled HkScrollProgressDock,
+     *  exactly like HkAdminTablePage's `total`. Omitted: the pill falls
+     *  back to counting the delivered DOM rows (right for
+     *  fully-delivered lists, drifting low for windowed ones — pass the
+     *  server count there). */
     total: { type: Number, default: undefined },
   },
   setup(props, { slots }) {
     // Scroll-progress registration (the HkTable precedent): the NEAREST
-    // enclosing HkScrollContainer with `scrollProgress` on provides the
-    // registrar — provide/inject scoping resolves the admin shell's
-    // viewport for console pages and keeps a list registered against an
-    // inner container out of the shell. The handle hands the pill the
-    // list element as the row root, the `total` prop live, and the
-    // rendered HkListRow elements as the rows (a card list's rows ARE
-    // its data rows — no section-band caveat).
+    // enclosing ENABLED HkScrollProgressDock provides the registrar —
+    // provide/inject scoping resolves the shell viewport for console
+    // pages and keeps a list registered against an inner dock out of
+    // the shell. The handle hands the pill the list element as the row
+    // root, the `total` prop live, and the rendered HkListRow elements
+    // as the rows (a card list's rows ARE its data rows — no
+    // section-band caveat).
     const listRef = ref<HTMLElement | null>(null);
     const progressRegistrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
     const progressHandle: HkScrollProgressHandle = {

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

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import * as barrel from "../index";
+import { asIndexable } from "../utils/typing";
+
+/**
+ * The public barrel guard for the edge-glow painter (same shape as
+ * HkCalendarHeatmap.barrel.test.ts): deleting the export lines from
+ * index.ts kept the ENTIRE suite green while the component's own tests
+ * reach the module through "./HkEdgeGlow" — only an external consumer
+ * would have noticed. HkScrollContainer imports the module directly too,
+ * so this file is the only thing pinning the public names.
+ *
+ * This file deliberately does NOT mock "@celestia-island/hikari": the
+ * package's self-reference resolves to the very same src/index.ts module
+ * as "../index", so a vi.mock here would replace the barrel under test
+ * with the mock's own namespace.
+ */
+describe("the public barrel", () => {
+  it("exports the edge-glow painter under both family names", () => {
+    const hk = asIndexable(barrel.HkEdgeGlow);
+    expect(hk, "HkEdgeGlow must be re-exported").toBeTruthy();
+    expect(hk.name).toBe("HkEdgeGlow");
+    // The H- alias rides the HCard/HkCard family convention: consumers
+    // import either name, one component underneath.
+    expect(barrel.HEdgeGlow).toBe(barrel.HkEdgeGlow);
+  });
+});