@celestia-island/hikari 0.55.290 → 0.55.292

package/package.json

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

package/src/components/HkAdminTablePage.tsx

@@ -1,7 +1,16 @@
-import { defineComponent, type Component, type PropType } from "vue";
+import {
+  defineComponent,
+  inject,
+  onMounted,
+  onUnmounted,
+  ref,
+  type Component,
+  type PropType,
+} from "vue";
 import { HAlert, HCard, HEmptyState, HSpinner, HTable, useI18n } from "@celestia-island/hikari";
 import HkCrossfade from "./HkCrossfade";
 import { HkPageHeader } from "./HkPageHeader";
+import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressHandle } from "./HkScrollProgress";
 import type { HkRowManageGate } from "./HkTable";
 
 
@@ -65,12 +74,39 @@ export const HkAdminTablePage = defineComponent({
       type: [Boolean, Function] as PropType<HkRowManageGate>,
       default: false,
     },
+    /** Authoritative row total the scroll-progress pill uses as its
+     *  denominator (the server count behind a paged list — chest's
+     *  usePagedTableFetch total). Omitted: the pill falls back to
+     *  counting the delivered DOM rows. Registration into the
+     *  enclosing shell viewport is automatic (see setup). */
+    total: { type: Number, default: undefined },
   },
   emits: {
     reorder: (_fromIndex: number, _toIndex: number) => true,
     manage: (_row: Record<string, unknown>, _opener: HTMLElement) => true,
   },
   setup(props, { emit, slots }) {
+    // Scroll-progress registration: the nearest enclosing HkScrollContainer
+    // with `scrollProgress` on provides the registrar (provide/inject
+    // scoping resolves the shell viewport for admin pages and keeps an
+    // inner container's lists out of the shell). The handle exposes the
+    // table card as the row root plus the `total` prop live — the pill's
+    // denominator follows it as pages load.
+    const registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+    const tableCardRef = ref<HTMLElement | null>(null);
+    let handle: HkScrollProgressHandle | null = null;
+    onMounted(() => {
+      if (!registrar) return;
+      handle = {
+        getRoot: () => tableCardRef.value,
+        getTotal: () => props.total,
+      };
+      registrar.register(handle);
+    });
+    onUnmounted(() => {
+      if (registrar && handle) registrar.unregister(handle);
+      handle = null;
+    });
 
     return () => {
       const { t } = useI18n();
@@ -129,21 +165,23 @@ export const HkAdminTablePage = defineComponent({
             ) : 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}
-                  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>
+              <div ref={tableCardRef} class="hk-admin-table-page-tablecard">
+                <HCard padded={false}>
+                  <HTable
+                    columns={props.columns}
+                    rows={props.rows}
+                    rowKey={props.rowKey}
+                    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>
+              </div>
             )}
           </HkCrossfade>
           {slots["create-modal"]?.()}

package/src/components/HkFaceShell.tsx

@@ -236,6 +236,14 @@ export const HkFaceShell = defineComponent({
      *  `stage` renders the content bare — the face owns scrolling,
      *  canvases and floating layers. */
     contentMode: { type: String as PropType<"document" | "stage">, default: "document" },
+    /** Scroll-progress pill on the document viewport (2026-11): while a
+     *  registered list scrolls, the shell floats an "xx / xx" counter
+     *  near the viewport's bottom-center (HkScrollContainer
+     *  `scrollProgress`; lists register themselves — HkAdminTablePage
+     *  does it for every admin list — so hosts inherit the affordance
+     *  with zero per-page work). Default ON: the shell is the
+     *  system-wide default-on point. Pass `false` to run the face bare. */
+    scrollProgress: { type: Boolean, default: true },
     /** Content-area padding (inside the scroll viewport). Document mode
      *  only — a stage face owns its own geometry. Padding is applied to
      *  an inner wrapper rather than the scroll container so card
@@ -537,7 +545,7 @@ export const HkFaceShell = defineComponent({
             {props.contentMode === "stage" ? (
               renderContentStage()
             ) : (
-              <HScrollContainer class="s-admin-shell-scroll">
+              <HScrollContainer class="s-admin-shell-scroll" scrollProgress={props.scrollProgress}>
                 {/* Padding lives INSIDE the scroll viewport (an inner
                     wrapper) so card box-shadows are not clipped at the
                     viewport edges. */}

package/src/components/HkScrollContainer.tsx

@@ -3,6 +3,7 @@ import {
   defineComponent,
   onBeforeUnmount,
   onMounted,
+  provide,
   ref,
   shallowRef,
   watch,
@@ -16,6 +17,12 @@ import { attachOverlayScrollbars, type OverlayScrollbarHandle, type OverlayScrol
 import { useApproachEnd, type ApproachEndHandle } from "../composables/useApproachEnd";
 import { provideScrollWindow } from "../composables/useScrollWindow";
 import { SCROLL_HOST_CLASS } from "./HkScrollPin";
+import {
+  HK_SCROLL_PROGRESS_REGISTRAR,
+  default as HkScrollProgress,
+  type HkScrollProgressHandle,
+  type HkScrollProgressRegistrar,
+} from "./HkScrollProgress";
 import { scheduleFrame, notifyScrollStart, onceFrame, type AnimationHandle } from "../runtime/animationBus";
 import HFab from "./HkFab";
 
@@ -193,6 +200,40 @@ export default defineComponent({
       type: String,
       default: '[aria-current]:not([aria-current="false"]), [aria-selected="true"], .is-active',
     },
+    /** Scroll-progress pill opt-in (2026-11): while on, the container
+     *  floats a small "xx / xx" counter near its bottom-center while the
+     *  scroll offset is changing — first visible row index over total
+     *  rows of whichever registered list is under the viewport. Lists
+     *  opt in per-list by registering against the provided registrar
+     *  (see `HK_SCROLL_PROGRESS_REGISTRAR`); provide/inject scoping
+     *  keeps a list registered against an inner container from leaking
+     *  to this one. Sensing rides the same rAF-coalesced update pass as
+     *  the overflow mirror — no second scroll listener. Off by default
+     *  (per-house additive-chrome discipline; HkFaceShell turns it on
+     *  for the document-mode shell).
+     *
+     *  Known edges (both accepted, documented for the next reader):
+     *  the registrar is provided at SETUP time only — a container
+     *  mounted OFF that flips the prop on later renders the pill with
+     *  nothing registered (hosts pass the prop statically; FaceShell
+     *  never toggles it). And sensing keys on THIS container's viewport
+     *  scroll — a nested INNER scroller moving on its own triggers no
+     *  pass here, so rows clipped inside the inner scroller can be
+     *  counted by the outer pill while invisible. The admin grammar
+     *  (one shell viewport) never nests. */
+    scrollProgress: { type: Boolean, default: false },
+    /** Idle window (ms) after the last scroll-offset change before the
+     *  pill fades out. Read live; clamped to 300..3000. Only meaningful
+     *  with `scrollProgress`. */
+    scrollProgressIdle: { type: Number, default: 900 },
+    /** Which descendants count as "rows" for the numerator/denominator.
+     *  The default matches the table grammar every admin list ships —
+     *  BODY rows only: a `tr` default would count the header row as row
+     *  one and skew every index. A non-table list (a card roster)
+     *  overrides with its own row spelling. Only read while
+     *  `scrollProgress` is on; a runtime change re-senses on the next
+     *  pass. */
+    scrollProgressSelector: { type: String, default: "tbody tr" },
   },
   emits: { approachEnd: () => true, "update:backTopVisible": (_v: boolean) => true },
   setup(props, { slots, expose, emit }) {
@@ -275,6 +316,142 @@ export default defineComponent({
       provideScrollWindow(viewportRef, props.overscanScreens);
     }
 
+    // ── Scroll progress pill (scrollProgress opt-in) ──────────────────
+    // Registration store + pill state. The registrar is PROVIDED here —
+    // once, at setup, only when the prop is on (the windowed-mode
+    // precedent above) — so provide/inject scoping resolves a list's
+    // inject to the NEAREST enclosing container with the feature on: a
+    // list registered against an inner container never leaks to an
+    // outer one, and with the prop off there is no registrar at all.
+    const progressRegistrars = new Set<HkScrollProgressHandle>();
+    const progressShown = ref(false);
+    const progressActive = ref(false);
+    const progressNumerator = ref(0);
+    const progressDenominator = ref(0);
+    let progressIdleTimer: ReturnType<typeof setTimeout> | null = null;
+    // The offset the last sensing pass saw; null = not baselined yet, so
+    // the mount-time pass never counts as "scrolling" (the pill appears
+    // on the first real offset change, not on mount).
+    let progressLastTop: number | null = null;
+
+    function clampProgressIdle(): number {
+      return Math.min(3000, Math.max(300, props.scrollProgressIdle));
+    }
+
+    function disarmProgressIdle() {
+      if (progressIdleTimer !== null) {
+        clearTimeout(progressIdleTimer);
+        progressIdleTimer = null;
+      }
+    }
+
+    function armProgressIdle() {
+      disarmProgressIdle();
+      progressIdleTimer = setTimeout(() => {
+        progressIdleTimer = null;
+        progressActive.value = false;
+      }, clampProgressIdle());
+    }
+
+    function registerProgress(handle: HkScrollProgressHandle) {
+      progressRegistrars.add(handle);
+      scheduleUpdate();
+    }
+
+    function unregisterProgress(handle: HkScrollProgressHandle) {
+      progressRegistrars.delete(handle);
+      scheduleUpdate();
+    }
+
+    if (props.scrollProgress) {
+      provide(HK_SCROLL_PROGRESS_REGISTRAR, {
+        register: registerProgress,
+        unregister: unregisterProgress,
+      } satisfies HkScrollProgressRegistrar);
+    }
+
+    /** Drop every pill precondition at once. `progressLastTop` resets so
+     *  the next appearance re-baselines — a pass that only re-armed the
+     *  preconditions (content grew back) must not read as a scroll. */
+    function setProgressHidden() {
+      progressShown.value = false;
+      progressActive.value = false;
+      disarmProgressIdle();
+      progressLastTop = null;
+      progressNumerator.value = 0;
+      progressDenominator.value = 0;
+    }
+
+    /** The ACTIVE registration: the first registered list whose root
+     *  intersects the container viewport (registration order — the Set
+     *  preserves insertion); when none intersects, the one whose root
+     *  top is nearest ABOVE the viewport top (the list the user just
+     *  scrolled out of). Deterministic in both tiers. */
+    function pickActiveProgressRoot(band: DOMRect): { handle: HkScrollProgressHandle; root: HTMLElement } | null {
+      let firstIntersecting: { handle: HkScrollProgressHandle; root: HTMLElement } | null = null;
+      let nearestAbove: { handle: HkScrollProgressHandle; root: HTMLElement; top: number } | null = null;
+      for (const handle of progressRegistrars) {
+        const root = handle.getRoot();
+        if (!root || !root.isConnected) continue;
+        const rect = root.getBoundingClientRect();
+        if (rect.bottom > band.top && rect.top < band.bottom) {
+          if (!firstIntersecting) firstIntersecting = { handle, root };
+          continue;
+        }
+        if (rect.top <= band.top && (!nearestAbove || rect.top > nearestAbove.top)) {
+          nearestAbove = { handle, root, top: rect.top };
+        }
+      }
+      return firstIntersecting ?? (nearestAbove ? { handle: nearestAbove.handle, root: nearestAbove.root } : null);
+    }
+
+    /** Pill sensing, riding the same throttled pass as the overflow
+     *  mirror (scroll / resize / content resize / refresh — no second
+     *  listener). Preconditions: a registration, vertical overflow, and
+     *  an active list with at least one row; failing any hides the pill
+     *  outright. While they hold, the numerator is the first row whose
+     *  bottom edge is still below the viewport top (1-based), and the
+     *  denominator is the registered total — unless it is missing,
+     *  non-finite, sub-1, or STALE (smaller than the live row count, a
+     *  page that loaded more rows than it declared), in which case the
+     *  DOM count wins so numerator can never exceed denominator. */
+    function senseScrollProgress(vp: HTMLElement) {
+      if (!props.scrollProgress || progressRegistrars.size === 0) {
+        setProgressHidden();
+        return;
+      }
+      const band = vp.getBoundingClientRect();
+      const active = pickActiveProgressRoot(band);
+      const rows = active ? active.root.querySelectorAll(props.scrollProgressSelector) : [];
+      if (!active || rows.length === 0 || vp.scrollHeight <= vp.clientHeight + 1) {
+        setProgressHidden();
+        return;
+      }
+      let numerator = rows.length;
+      for (let i = 0; i < rows.length; i++) {
+        if ((rows[i] as HTMLElement).getBoundingClientRect().bottom > band.top) {
+          numerator = i + 1;
+          break;
+        }
+      }
+      const declared = active.handle.getTotal();
+      const denominator =
+        typeof declared === "number" && Number.isFinite(declared) && declared >= 1
+          ? Math.max(declared, rows.length)
+          : rows.length;
+      progressNumerator.value = Math.min(numerator, denominator);
+      progressDenominator.value = denominator;
+      progressShown.value = true;
+      // Scroll-active: only a changed offset counts (the pass also runs
+      // for resizes and content mutations). The idle fade re-arms on
+      // every moving pass, so continuous scrolling never snaps off.
+      if (progressLastTop !== null && vp.scrollTop !== progressLastTop) {
+        progressActive.value = true;
+        armProgressIdle();
+      }
+      progressLastTop = vp.scrollTop;
+    }
+
     const hasV = () => props.axis !== "horizontal";
     const hasH = () => props.axis !== "vertical";
     // Safe centering applies to horizontal-axis containers only; the
@@ -414,6 +591,7 @@ export default defineComponent({
       senseOverflow(vp);
       senseBackTop(vp);
       senseSelectionBeyond(vp);
+      senseScrollProgress(vp);
     }
 
     /** Back-to-top hysteresis, derived on the same throttled pass as the
@@ -622,6 +800,7 @@ export default defineComponent({
       overlay?.detach();
       overlay = null;
       stopApproach();
+      disarmProgressIdle();
       selectionMO?.disconnect();
       selectionMO = null;
       scheduled?.disconnect();
@@ -774,6 +953,14 @@ export default defineComponent({
           {showAutoTag.value && (
             <span class="hk-scroll-container-autotag" aria-hidden="true">{t("hikari::scrollContainer.auto", "Auto")}</span>
           )}
+          {props.scrollProgress && (
+            <HkScrollProgress
+              shown={progressShown.value}
+              active={progressActive.value}
+              numerator={progressNumerator.value}
+              denominator={progressDenominator.value}
+            />
+          )}
           {props.autoFollow && props.followAffordance && !pinned.value && (
             <HFab
               class="hk-scroll-container-jump"

package/src/components/HkScrollProgress.scss

@@ -0,0 +1,58 @@
+@use "../styles/polyfill" as *;
+
+/* ── Scroll-progress pill (HkScrollContainer scrollProgress) ──────
+   The "xx / xx" counter that floats near the bottom-center of a
+   scrolling list: first visible row index over total rows. It hangs
+   off the container HOST (position: relative), never the viewport —
+   viewport-absolute chrome scrolls away with the content, the same
+   reason the autotag band and the selection-hint gradients paint on
+   the root.
+
+   Visual vocabulary is the autotag band's (the container's other
+   bottom chrome): muted mono digits on the mixed surface pill, same
+   z-index tier (6). The bottom inset is safe-area aware the way
+   HkFab's corners are. Bare digits only — counters are locale-neutral
+   (the HkLoadMore counter precedent). */
+.hk-scroll-progress-pill {
+  position: absolute;
+  left: 50%;
+  bottom: max(var(--space-10), env(safe-area-inset-bottom, 0px));
+  transform: translateX(-50%);
+  z-index: 6;
+  pointer-events: none;
+  @include user-select(none);
+  padding: var(--space-2) var(--space-8);
+  font-family: var(--font-mono);
+  font-size: var(--text-2xs);
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.04em;
+  color: var(--hi-color-muted, #6c6c6c);
+  background: color-mix(in srgb, var(--hi-color-surface, rgba(255, 255, 255, 0.95)) 78%, transparent);
+  border: 1px solid color-mix(in srgb, var(--hi-color-border, rgba(100, 100, 100, 0.08)) 12%, transparent);
+  border-radius: var(--radius-full, 9999px);
+  @include backdrop-filter(blur(4px));
+
+  /* Resting = transparent; only an in-flight scroll lights it. The
+   * ~200ms ease is the show AND hide fade (data-state flips on the
+   * container's throttled sensing pass). */
+  opacity: 0;
+  transition: opacity 200ms ease;
+
+  &[data-state="active"] {
+    opacity: 0.85;
+  }
+
+  /* A failed precondition (no registered list, no vertical overflow,
+   * a list whose rows are empty) removes the box outright — the pill
+   * must never linger as dead chrome. */
+  &[data-state="hidden"] {
+    display: none;
+  }
+}
+
+/* Reduced motion: no fade at all — the state flips instantly. */
+@media (prefers-reduced-motion: reduce) {
+  .hk-scroll-progress-pill {
+    transition: none;
+  }
+}

package/src/components/HkScrollProgress.test.tsx

@@ -0,0 +1,502 @@
+// Scroll-progress pill: registration contract, sensing behavior, and the
+// HkAdminTablePage auto-registration. Geometry is stubbed the same way
+// the overlay-scrollbar tests do it (happy-dom performs no layout) —
+// Object.defineProperties for the viewport's scroll numbers, spyOn for
+// the getBoundingClientRect boxes the numerator reads.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, inject, nextTick, onMounted, onUnmounted, provide, ref } from "vue";
+
+import HkScrollContainer from "./HkScrollContainer";
+import { HkAdminTablePage } from "./HkAdminTablePage";
+import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressRegistrar } from "./HkScrollProgress";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+const rects: Array<ReturnType<typeof vi.spyOn>> = [];
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  for (const spy of rects.splice(0)) spy.mockRestore();
+});
+
+function mountTree(root: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => root });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+interface Scroller {
+  container: HTMLElement;
+  viewport: HTMLElement;
+  pill: () => HTMLElement | null;
+  refresh: () => void;
+  setScrollTop: (top: number) => void;
+}
+
+/** Mount a HkScrollContainer with `scrollProgress` on and the given slot
+ *  content. scrollTop rides a mutable cell so successive refresh() passes
+ *  can move it (the sensing pass reads the live getter). */
+function mountScroller(slot: () => ReturnType<typeof h>, props: Record<string, unknown> = {}): Scroller {
+  let scrollTop = 0;
+  const instance = ref<{ refresh: () => void } | null>(null);
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkScrollContainer, {
+          ref: instance as never,
+          scrollProgress: true,
+          ...props,
+        }, { default: slot });
+    },
+  });
+  const container = mountTree(h(Wrapper));
+  const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport");
+  if (!viewport) throw new Error("container did not render its viewport");
+  Object.defineProperties(viewport, {
+    scrollHeight: { configurable: true, get: () => 2000 },
+    clientHeight: { configurable: true, get: () => 400 },
+    scrollWidth: { configurable: true, get: () => 300 },
+    clientWidth: { configurable: true, get: () => 300 },
+    scrollLeft: { configurable: true, get: () => 0 },
+    scrollTop: { configurable: true, get: () => scrollTop },
+  });
+  rects.push(vi.spyOn(viewport, "getBoundingClientRect").mockReturnValue({
+    left: 0, top: 0, right: 300, bottom: 400, width: 300, height: 400, x: 0, y: 0,
+  } as DOMRect));
+  return {
+    container,
+    viewport,
+    pill: () => container.querySelector<HTMLElement>(".hk-scroll-progress-pill"),
+    refresh: () => instance.value?.refresh(),
+    setScrollTop: (top: number) => {
+      scrollTop = top;
+    },
+  };
+}
+
+/** A minimal registered list: `rows` tr elements inside a table (the
+ *  default `tr` row grammar), the registrar contacted on mounted. */
+function makeList(options: { rows: number; total?: number }) {
+  return defineComponent({
+    setup() {
+      const rootRef = ref<HTMLElement | null>(null);
+      const registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+      onMounted(() => {
+        registrar?.register({ getRoot: () => rootRef.value, getTotal: () => options.total });
+      });
+      return () =>
+        h("div", { ref: rootRef }, [
+          h("table", { class: "probe-table" }, [
+            h("tbody", {}, Array.from({ length: options.rows }, (_, i) =>
+              h("tr", { "data-row": String(i), key: i }, `row ${i}`),
+            )),
+          ]),
+        ]);
+    },
+  });
+}
+
+/** Stub every row's rect: 40px tall, stacked from the content top, so a
+ *  given scrollTop produces a deterministic first-visible row. */
+function stubRows(container: HTMLElement, rows: number, scrollTop = 0) {
+  container.querySelectorAll<HTMLElement>("tr").forEach((row, i) => {
+    const top = i * 40 - scrollTop;
+    rects.push(vi.spyOn(row, "getBoundingClientRect").mockReturnValue({
+      left: 0, top, right: 100, bottom: top + 40, width: 100, height: 40, x: 0, y: top,
+    } as DOMRect));
+  });
+}
+
+function stubRootRect(container: HTMLElement, selector: string, top: number, bottom: number, wrapper = false) {
+  // `wrapper`: stub the registered ROOT (the list's wrapper div) instead
+  // of the table inside it — pickActiveProgressRoot reads the root.
+  const anchor = container.querySelector<HTMLElement>(selector);
+  if (!anchor) throw new Error("list root missing");
+  const root = wrapper ? anchor.parentElement! : anchor;
+  rects.push(vi.spyOn(root, "getBoundingClientRect").mockReturnValue({
+    left: 0, top, right: 100, bottom, width: 100, height: bottom - top, x: 0, y: top,
+  } as DOMRect));
+}
+
+const ROWS = 40;
+
+describe("HkScrollProgress", () => {
+  it("renders no pill element when scrollProgress is off", async () => {
+    const scroller = mountScroller(() => h(makeList({ rows: ROWS, total: 500 })), { scrollProgress: false });
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()).toBeNull();
+  });
+
+  it("answers hidden while nothing is registered", async () => {
+    const scroller = mountScroller(() => h("div", { class: "bare-content" }, "content"));
+    scroller.refresh();
+    await nextTick();
+    const pill = scroller.pill();
+    expect(pill).not.toBeNull();
+    expect(pill!.dataset.state).toBe("hidden");
+  });
+
+  it("provides NO registrar when scrollProgress is off", () => {
+    // The provide is guarded by the prop — a list inside an OFF container
+    // must resolve null (so it falls through to an OUTER on-container, or
+    // registers nowhere). Pins the guard: deleting the `if (props.scrollProgress)`
+    // around the provide turns this red.
+    let saw: unknown = "unset";
+    const Probe = defineComponent({
+      setup() {
+        saw = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+        return () => h("div", "probe");
+      },
+    });
+    mountScroller(() => h(Probe), { scrollProgress: false });
+    expect(saw).toBeNull();
+  });
+
+  it("resolves inner-OFF inside outer-ON to the OUTER registrar identity", async () => {
+    const seen: unknown[] = [];
+    const Probe = defineComponent({
+      setup() {
+        const registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+        onMounted(() => {
+          registrar?.register({ getRoot: () => null, getTotal: () => 7 });
+          seen.push(registrar);
+        });
+        return () => h("div", "probe");
+      },
+    });
+    // Three probes: (a) directly under the outer ON container, (b) inside
+    // an inner OFF container, (c) inside an inner ON container. Registrar
+    // IDENTITY pins the scoping matrix: (a)==(b) — the OFF inner provides
+    // nothing, so (b) falls through to the OUTER registrar — while (c)
+    // receives the INNER container's own registrar (shadowing). Deleting
+    // the `if (props.scrollProgress)` provide guard turns (b) into a
+    // third distinct registrar and this test red.
+    const scroller = mountScroller(() =>
+      h("div", [
+        h(Probe),
+        h(HkScrollContainer, { scrollProgress: false }, { default: () => h(Probe) }),
+        h(HkScrollContainer, { scrollProgress: true }, { default: () => h(Probe) }),
+      ]),
+    );
+    scroller.refresh();
+    await nextTick();
+    expect(seen.length).toBe(3);
+    expect(seen[0]).not.toBeNull();
+    expect(seen[1]).toBe(seen[0]);
+    expect(seen[2]).not.toBe(seen[0]);
+    // Two pills exist (outer ON + inner ON; the OFF inner renders none).
+    expect(scroller.container.querySelectorAll(".hk-scroll-progress-pill").length).toBe(2);
+  });
+
+  it("shows the active count over the registered total on scroll", async () => {
+    const List = makeList({ rows: ROWS, total: 340 });
+    const scroller = mountScroller(() => h(List));
+    // Baseline pass: preconditions hold, no offset change yet.
+    stubRows(scroller.container, ROWS, 0);
+    stubRootRect(scroller.container, ".probe-table", -100, 1900);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.dataset.state).toBe("idle");
+
+    // A real offset change lights the pill: row 9's bottom edge lands at
+    // the viewport top, so the first VISIBLE row is #11; total 340.
+    scroller.setScrollTop(400);
+    stubRows(scroller.container, ROWS, 400);
+    scroller.refresh();
+    await nextTick();
+    const pill = scroller.pill()!;
+    expect(pill.dataset.state).toBe("active");
+    expect(pill.textContent).toBe("11 / 340");
+  });
+
+  it("falls back to the DOM row count when the total is absent", async () => {
+    const List = makeList({ rows: ROWS });
+    const scroller = mountScroller(() => h(List));
+    scroller.setScrollTop(400);
+    stubRows(scroller.container, ROWS, 400);
+    stubRootRect(scroller.container, ".probe-table", -100, 1900);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.textContent).toBe("11 / 40");
+  });
+
+  it("falls back to the DOM row count when the declared total went stale", async () => {
+    // A total smaller than the delivered rows (a page loaded more than it
+    // declared) must never let the numerator exceed the denominator.
+    const List = makeList({ rows: ROWS, total: 5 });
+    const scroller = mountScroller(() => h(List));
+    scroller.setScrollTop(400);
+    stubRows(scroller.container, ROWS, 400);
+    stubRootRect(scroller.container, ".probe-table", -100, 1900);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.textContent).toBe("11 / 40");
+  });
+
+  it("answers hidden when the content fits without overflow", async () => {
+    const List = makeList({ rows: ROWS, total: 340 });
+    const scroller = mountScroller(() => h(List));
+    Object.defineProperties(scroller.viewport, {
+      scrollHeight: { configurable: true, get: () => 400 },
+      clientHeight: { configurable: true, get: () => 400 },
+    });
+    stubRows(scroller.container, ROWS, 0);
+    stubRootRect(scroller.container, ".probe-table", 0, 400);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.dataset.state).toBe("hidden");
+  });
+
+  it("fades to idle after the idle window and re-arms on the next move", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    const List = makeList({ rows: ROWS, total: 340 });
+    const scroller = mountScroller(() => h(List));
+    stubRows(scroller.container, ROWS, 0);
+    stubRootRect(scroller.container, ".probe-table", -100, 1900);
+    scroller.refresh();
+    await nextTick();
+    scroller.setScrollTop(400);
+    stubRows(scroller.container, ROWS, 400);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.dataset.state).toBe("active");
+    // Idle window (default 900ms): opacity fades via data-state="idle".
+    vi.advanceTimersByTime(900);
+    await nextTick();
+    expect(scroller.pill()!.dataset.state).toBe("idle");
+    // The next offset change re-arms the active state.
+    scroller.setScrollTop(500);
+    stubRows(scroller.container, ROWS, 500);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.dataset.state).toBe("active");
+  });
+
+  it("tracks the intersecting list among several registrations", async () => {
+    // List A sits fully above the viewport; list B intersects. The pill
+    // describes B; once B unregisters, the nearest-above tier takes A.
+    const bHandle: { fn?: () => void } = {};
+    const listA = defineComponent({
+      setup() {
+        const registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+        const rootRef = ref<HTMLElement | null>(null);
+        onMounted(() => registrar?.register({ getRoot: () => rootRef.value, getTotal: () => 10 }));
+        return () =>
+          h("div", { ref: rootRef }, [
+            h("table", { class: "probe-table-a" }, [h("tbody", {}, Array.from({ length: 10 }, (_, i) => h("tr", { "data-list": "a", key: i }, `a${i}`)))]),
+          ]);
+      },
+    });
+    const listB = defineComponent({
+      setup() {
+        const registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+        const rootRef = ref<HTMLElement | null>(null);
+        onMounted(() => {
+          const handle = { getRoot: () => rootRef.value, getTotal: () => 20 };
+          registrar?.register(handle);
+          bHandle.fn = () => registrar?.unregister(handle);
+        });
+        return () =>
+          h("div", { ref: rootRef }, [
+            h("table", { class: "probe-table-b" }, [h("tbody", {}, Array.from({ length: 20 }, (_, i) => h("tr", { "data-list": "b", key: i }, `b${i}`)))]),
+          ]);
+      },
+    });
+    const scroller = mountScroller(() => h("div", [h(listA), h(listB)]));
+    // A's rows live above the band; B's rows intersect it.
+    scroller.container.querySelectorAll<HTMLTableRowElement>("tr").forEach((row) => {
+      const above = row.dataset.list === "a";
+      const top = above ? -2000 : 100;
+      rects.push(vi.spyOn(row, "getBoundingClientRect").mockReturnValue({
+        left: 0, top, right: 100, bottom: top + 40, width: 100, height: 40, x: 0, y: top,
+      } as DOMRect));
+    });
+    // Roots: A above (bottom above the band's top), B intersecting.
+    stubRootRect(scroller.container, ".probe-table-a", -2000, -1600, true);
+    stubRootRect(scroller.container, ".probe-table-b", 100, 900, true);
+    scroller.setScrollTop(100);
+    scroller.refresh();
+    await nextTick();
+    // B's rows all intersect the band, so the first visible row is #1.
+    expect(scroller.pill()!.textContent).toBe("1 / 20");
+
+    // B leaves the registry: the nearest-above tier describes A — every
+    // A row sits above the band, so the numerator reads as "past the
+    // end" (rows.length) over A's total.
+    bHandle.fn?.();
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.textContent).toBe("10 / 10");
+  });
+
+  it("hides once the registration goes away", async () => {
+    const handleBox: { fn?: () => void } = {};
+    const List = defineComponent({
+      setup() {
+        const registrar = inject(HK_SCROLL_PROGRESS_REGISTRAR, null);
+        const rootRef = ref<HTMLElement | null>(null);
+        onMounted(() => {
+          const handle = { getRoot: () => rootRef.value, getTotal: () => 10 };
+          registrar?.register(handle);
+          handleBox.fn = () => registrar?.unregister(handle);
+        });
+        return () =>
+          h("div", { ref: rootRef }, [
+            h("table", {}, [h("tbody", {}, Array.from({ length: 10 }, (_, i) => h("tr", { key: i }, `r${i}`)))]),
+          ]);
+      },
+    });
+    const scroller = mountScroller(() => h(List));
+    stubRows(scroller.container, 10, 0);
+    stubRootRect(scroller.container, "table", -100, 1900);
+    // First pass baselines the offset (no active yet); the second move
+    // lights the pill.
+    scroller.setScrollTop(100);
+    scroller.refresh();
+    await nextTick();
+    scroller.setScrollTop(200);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.dataset.state).toBe("active");
+    handleBox.fn?.();
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.dataset.state).toBe("hidden");
+  });
+});
+
+describe("HkAdminTablePage scroll-progress registration", () => {
+  it("registers its table root and total with the provided registrar", async () => {
+    const registered: Array<{ getRoot: () => HTMLElement | null; getTotal: () => number | undefined }> = [];
+    const unregistered: unknown[] = [];
+    const registrar: HkScrollProgressRegistrar = {
+      register: (handle) => registered.push(handle),
+      unregister: (handle) => unregistered.push(handle),
+    };
+    const Provider = defineComponent({
+      setup() {
+        provide(HK_SCROLL_PROGRESS_REGISTRAR, registrar);
+        return () =>
+          h(HkAdminTablePage, {
+            title: "T",
+            rows: [{ name: "a" }, { name: "b" }],
+            columns: [{ key: "name", title: "Name" }],
+            total: 99,
+          });
+      },
+    });
+    const container = mountTree(h(Provider));
+    expect(registered.length).toBe(1);
+    expect(registered[0].getTotal()).toBe(99);
+    // The table card is the row root — the element containing the rows.
+    expect(registered[0].getRoot()).not.toBeNull();
+    expect(registered[0].getRoot()!.contains(container.querySelector("table"))).toBe(true);
+
+    // Unmount unregisters the SAME handle.
+    mounts[0].app.unmount();
+    expect(unregistered.length).toBe(1);
+    expect(unregistered[0]).toBe(registered[0]);
+  });
+
+  it("renders its rows into the shell viewport's pill denominator end-to-end", async () => {
+    // The real provide/inject path: AdminTablePage inside a
+    // scrollProgress-on container registers itself, and the pill's
+    // denominator is the page's declared total (not the delivered rows).
+    const page = h(HkAdminTablePage, {
+      title: "T",
+      rows: Array.from({ length: 30 }, (_, i) => ({ name: `r${i}` })),
+      columns: [{ key: "name", title: "Name" }],
+      total: 500,
+    });
+    const instance = ref<{ refresh: () => void } | null>(null);
+    let scrollTop = 0;
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkScrollContainer, { ref: instance as never, scrollProgress: true }, { default: () => page });
+      },
+    });
+    const container = mountTree(h(Wrapper));
+    const viewport = container.querySelector<HTMLElement>(".hk-scroll-container-viewport")!;
+    Object.defineProperties(viewport, {
+      scrollHeight: { configurable: true, get: () => 4000 },
+      clientHeight: { configurable: true, get: () => 400 },
+      scrollWidth: { configurable: true, get: () => 300 },
+      clientWidth: { configurable: true, get: () => 300 },
+      scrollLeft: { configurable: true, get: () => 0 },
+      scrollTop: { configurable: true, get: () => scrollTop },
+    });
+    rects.push(vi.spyOn(viewport, "getBoundingClientRect").mockReturnValue({
+      left: 0, top: 0, right: 300, bottom: 400, width: 300, height: 400, x: 0, y: 0,
+    } as DOMRect));
+    // The list root is AdminTablePage's table-card wrapper (the anchor
+    // class the page ships for exactly this geometry contract).
+    const card = container.querySelector("table");
+    expect(card).not.toBeNull();
+    const cardHost = container.querySelector<HTMLElement>(".hk-admin-table-page-tablecard")!;
+    expect(cardHost.contains(card!)).toBe(true);
+    rects.push(vi.spyOn(cardHost, "getBoundingClientRect").mockReturnValue({
+      left: 0, top: -200, right: 300, bottom: 3800, width: 300, height: 4000, x: 0, y: -200,
+    } as DOMRect));
+    container.querySelectorAll<HTMLElement>("tbody tr").forEach((row, i) => {
+      const top = i * 40 - 200;
+      rects.push(vi.spyOn(row, "getBoundingClientRect").mockReturnValue({
+        left: 0, top, right: 300, bottom: top + 40, width: 300, height: 40, x: 0, y: top,
+      } as DOMRect));
+    });
+    scrollTop = 200;
+    instance.value!.refresh();
+    await nextTick();
+    const pill = container.querySelector<HTMLElement>(".hk-scroll-progress-pill");
+    expect(pill).not.toBeNull();
+    // First visible row #6 over the DECLARED total — the delivered rows
+    // (30) never override the page's server count.
+    expect(pill!.textContent).toBe("6 / 500");
+  });
+});
+
+
+// ── SCSS contract (textual pins — happy-dom does not lay out) ────────
+// The house style pins sheet claims with readFileSync probes
+// (HkButton.test.tsx icon-only precedent): these guard the paint
+// decisions the DOM tests cannot see.
+const scss = readFileSync(join(__dirname, "HkScrollProgress.scss"), "utf-8").replace(/\r\n/g, "\n");
+
+describe("HkScrollProgress SCSS contract", () => {
+  it("hides by display:none, never just transparency", () => {
+    const hidden = scss.match(/&\[data-state="hidden"\]\s*{[^}]*}/)?.[0] ?? "";
+    expect(hidden, "hidden-state rule must exist").toBeTruthy();
+    expect(hidden).toContain("display: none");
+  });
+
+  it("fades via a 200ms opacity transition on the pill itself", () => {
+    const rule = scss.match(/\.hk-scroll-progress-pill\s*{[^}]*}/)?.[0] ?? "";
+    expect(rule, "pill rule must exist").toBeTruthy();
+    expect(rule).toContain("transition: opacity 200ms ease");
+    expect(rule).toContain("pointer-events: none");
+  });
+
+  it("hangs bottom-center with the safe-area inset and the autotag z-tier", () => {
+    const rule = scss.match(/\.hk-scroll-progress-pill\s*{[^}]*}/)?.[0] ?? "";
+    expect(rule).toContain("position: absolute");
+    expect(rule).toContain("left: 50%");
+    expect(rule).toContain("max(var(--space-10), env(safe-area-inset-bottom, 0px))");
+    expect(rule).toContain("z-index: 6");
+  });
+
+  it("drops the fade entirely under prefers-reduced-motion", () => {
+    const reduced = scss.match(/@media \(prefers-reduced-motion: reduce\)\s*{[^}@]*{[^}]*}\s*}/)?.[0] ?? "";
+    expect(reduced, "reduced-motion block must exist").toBeTruthy();
+    expect(reduced).toContain("transition: none");
+  });
+});

package/src/components/HkScrollProgress.tsx

@@ -0,0 +1,71 @@
+// Scroll-progress pill: the shared registration vocabulary and the pill
+// renderer for HkScrollContainer's `scrollProgress` opt-in.
+//
+// This module owns three things:
+// 1. the provide/inject key (`HK_SCROLL_PROGRESS_REGISTRAR`) a list uses to
+//    find the registrar of the NEAREST enclosing HkScrollContainer that has
+//    the feature on — provide/inject scoping is what makes a list registered
+//    against an inner container never leak to an outer one;
+// 2. the registration types (`HkScrollProgressHandle`,
+//    `HkScrollProgressRegistrar`);
+// 3. the pill renderer itself — HkScrollContainer imports and mounts it
+//    inside its host, so the component stays internal to the feature.
+//
+// The pill shows bare digits "12 / 340" (first visible row / total rows) —
+// deliberately locale-neutral, the same contract as HkLoadMore's counter.
+import { defineComponent, type InjectionKey } from "vue";
+
+import "./HkScrollProgress.scss";
+
+/** What a list hands to the registrar so the pill can describe it:
+ *  the list's root element (the box that scrolls inside the container's
+ *  viewport) and the authoritative row total when the list knows one
+ *  (undefined = the pill falls back to counting DOM rows). */
+export interface HkScrollProgressHandle {
+  getRoot(): HTMLElement | null;
+  getTotal(): number | undefined;
+}
+
+/** Provided by every HkScrollContainer instance whose `scrollProgress`
+ *  prop is on, and never when the prop is off. Lists inject it (null
+ *  fallback) and register on mounted / unregister on unmounted. */
+export interface HkScrollProgressRegistrar {
+  register(handle: HkScrollProgressHandle): void;
+  unregister(handle: HkScrollProgressHandle): void;
+}
+
+export const HK_SCROLL_PROGRESS_REGISTRAR: InjectionKey<HkScrollProgressRegistrar> =
+  Symbol("hk-scroll-progress-registrar");
+
+/** The pill renderer. Three states, mirrored on `data-state` so the SCSS
+ *  owns the paint:
+ *  - "hidden"  — a precondition fails (no registration, no overflow, no
+ *    rows): `display: none`, never just transparent;
+ *  - "active"  — the scroll offset is changing: opaque;
+ *  - "idle"    — scrolling stopped: opacity 0 over the ~200ms fade.
+ *  A11y honesty: `aria-hidden` throughout — the pill is DECORATIVE chrome
+ *  and nothing announces the row position (HkInfiniteTail's role=status
+ *  announces load / end-of-list events only, never a scroll position);
+ *  this component adds no announce channel of its own. */
+const HkScrollProgress = defineComponent({
+  name: "HkScrollProgress",
+  props: {
+    shown: { type: Boolean, default: false },
+    active: { type: Boolean, default: false },
+    numerator: { type: Number, default: 0 },
+    denominator: { type: Number, default: 0 },
+  },
+  setup(props) {
+    return () => (
+      <span
+        class="hk-scroll-progress-pill"
+        aria-hidden="true"
+        data-state={!props.shown ? "hidden" : props.active ? "active" : "idle"}
+      >
+        {props.numerator} / {props.denominator}
+      </span>
+    );
+  },
+});
+
+export default HkScrollProgress;

package/src/index.ts

@@ -507,6 +507,12 @@ export type { PasswordValidationResult, PasswordLevel, PasswordStrengthEvaluator
 export { FOCUSABLE_SELECTOR, getFocusableElements, focusFirst, trapFocus, scrollToElement } from "./utils/dom";
 export { useApproachEnd } from "./composables/useApproachEnd";
 export type { ApproachEndOptions, ApproachEndHandle } from "./composables/useApproachEnd";
+// The scroll-progress pill's public vocabulary: HkScrollContainer's
+// `scrollProgress` registrar — lists (HkAdminTablePage does it built-in)
+// inject this key to register their row root + total with the nearest
+// enclosing container that has the feature on.
+export { HK_SCROLL_PROGRESS_REGISTRAR } from "./components/HkScrollProgress";
+export type { HkScrollProgressHandle, HkScrollProgressRegistrar } from "./components/HkScrollProgress";
 // The change-mark rail's public vocabulary: HkScrollContainer's `markers`
 // prop is typed with it, so consumers can name what they pass.
 export type { OverlayScrollMapSegment, OverlayScrollbarMarker } from "./composables/useOverlayScrollbar";