@celestia-island/hikari 0.55.316 → 0.55.319

package/package.json

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

package/src/components/HkModal.plate.contract.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Compiled-CSS contract for the modal BLUR PLATE — the open-stutter fix.
+ *
+ * Measured root cause (2026-11-07 open-jank spike, headless rAF matrix):
+ * a backdrop-filter re-filters its full-viewport backdrop on EVERY
+ * composited frame while any animation is live anywhere — the enter
+ * storm (frame + dim + strip + crumbs mounting together) ran at
+ * 26-55% dropped frames with live plates, while the steady state
+ * (nothing animating) is cached and runs 60fps. The architecture:
+ *
+ *   1. the blur lives on a STATIC plate that never animates and never
+ *      carries a transition;
+ *   2. the eye-tracked transition is the solid-color dim curtain
+ *      (opacity-only composite);
+ *   3. the plate is REMOVED on stack-covered windows (a present
+ *      backdrop-filter element still forces the per-frame backdrop
+ *      surface even computed to none — measured ~44pp worse than
+ *      hidden);
+ *   4. the overlay carries the default blur only for plate-less markup
+ *      (the Rust-rendered modals share this compiled sheet without a
+ *      plate element) and opts down to dim-only document-globally when
+ *      a Vue plate exists.
+ *
+ * Regression risk this file pins: a future edit re-adding a
+ * backdrop-filter to `.hk-modal-overlay` would double-filter the Vue
+ * path and reintroduce the jank; re-adding an enter/leave-scoped
+ * suppression leg would reintroduce the settle hitch; relaxing the
+ * covered drop would reintroduce the stacked-blur storm.
+ */
+import { describe, expect, it } from "vitest";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "sass";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const css = compile(join(here, "HkModal.scss"), {
+  loadPaths: [here, join(here, "..", "styles")],
+  style: "expanded",
+}).css;
+
+/** Brace-matched body of the first top-level block whose head starts
+ *  with the given prefix (`@media …` or a selector). */
+function topBlock(cssText: string, headPrefix: string): string {
+  const start = cssText.indexOf(headPrefix);
+  if (start === -1) return "";
+  const open = cssText.indexOf("{", start);
+  let depth = 0;
+  for (let i = open; i < cssText.length; i++) {
+    if (cssText[i] === "{") depth += 1;
+    else if (cssText[i] === "}") {
+      depth -= 1;
+      if (depth === 0) return cssText.slice(open + 1, i);
+    }
+  }
+  return "";
+}
+
+/** All `selector { body }` frames inside a block (one nesting level deep
+ *  is enough). Selector parts carry preceding block-glue in expanded
+ *  output (media heads, comment remains) — trimmed to the bare
+ *  selector. */
+function frames(block: string): { selectors: string[]; body: string }[] {
+  const out: { selectors: string[]; body: string }[] = [];
+  const re = /([^{}]+)\{([^{}]*)\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(block))) {
+    out.push({
+      selectors: m[1]
+        .split(",")
+        .map((part) => {
+          let t = part;
+          const comment = t.lastIndexOf("*/");
+          if (comment !== -1) t = t.slice(comment + 2);
+          const brace = t.lastIndexOf("{");
+          if (brace !== -1) t = t.slice(brace + 1);
+          const semi = t.lastIndexOf(";");
+          if (semi !== -1) t = t.slice(semi + 1);
+          return t.trim();
+        })
+        .filter((s) => s.startsWith(".") || s.startsWith("[") || s.startsWith(":")),
+      body: m[2].trim(),
+    });
+  }
+  return out;
+}
+
+/** Bodies of every rule whose selector LIST includes exactly `selector`. */
+function ruleBodies(sheet: string, selector: string): string[] {
+  return frames(sheet)
+    .filter((f) => f.selectors.includes(selector))
+    .map((f) => f.body);
+}
+const oneRule = (sheet: string, selector: string): string => {
+  const bodies = ruleBodies(sheet, selector);
+  expect(bodies.length, `rule ${selector} must exist`).toBeGreaterThan(0);
+  return bodies[0];
+};
+
+const mobileBlock = topBlock(css, "@media (max-width: 767px)");
+
+describe("modal blur plate (static filter, stack-covered removal)", () => {
+  it("carries the blur; the fading overlay must NOT (vue path)", () => {
+    // The core invariant: the overlay is the ANIMATED layer — a
+    // backdrop-filter on it re-filters the whole viewport per frame
+    // (the reported stutter). The blur lives on the never-animated
+    // plate only.
+    const plate = oneRule(css, ".hk-modal-blur-plate");
+    expect(plate).toMatch(/backdrop-filter:\s*var\(--hk-modal-overlay-blur/);
+    expect(plate).toContain("pointer-events: none");
+    expect(plate).toContain("z-index: -1");
+  });
+
+  it("gives plate-less markup (rust-rendered modals) the overlay blur", () => {
+    // The Rust-rendered modals share this compiled sheet but their
+    // markup has no plate element: the overlay keeps the default blur
+    // there.
+    const overlayDefault = ruleBodies(css, ".hk-modal-overlay").find((b) =>
+      b.includes("backdrop-filter: var(--hk-modal-overlay-blur"),
+    );
+    expect(overlayDefault, "default overlay blur must exist").toBeTruthy();
+  });
+
+  it("opts the overlay down to dim-only wherever a plate exists", () => {
+    // :root:has(plate) is document-global: one Vue modal anywhere means
+    // every overlay in the document is plate-backed and dim-only.
+    expect(css).toMatch(
+      /:root:has\(\.hk-modal-blur-plate\)\s*\.hk-modal-overlay\s*\{[^}]*backdrop-filter:\s*none/,
+    );
+  });
+
+  it("removes the plate on stack-covered windows", () => {
+    // A present backdrop-filter element still forces the per-frame
+    // backdrop surface even computed to none (~44pp worse than hidden).
+    const covered = ruleBodies(css, ".hk-modal-root[data-stack-covered] .hk-modal-blur-plate");
+    expect(covered.length).toBeGreaterThanOrEqual(1);
+    for (const body of covered) expect(body).toContain("display: none");
+  });
+
+  it("keeps no enter/leave-scoped suppression legs (the top plate animates with the filter)", () => {
+    // The top plate's own enter measured 2% dropped WITH the filter
+    // live (single live blur) — suppression legs were removed with the
+    // settle hitch they created. Re-adding any leg must be a deliberate
+    // re-trade.
+    expect(css).not.toMatch(
+      /hk-modal-content-(?:enter|leave)-(?:from|to|active) ~ \.hk-modal-blur-plate/,
+    );
+  });
+
+  it("keeps the mobile stand-down on both faces", () => {
+    expect(mobileBlock).toContain(".hk-modal-blur-plate");
+    expect(frames(mobileBlock).some((f) => f.selectors.includes(".hk-modal-blur-plate"))).toBe(true);
+    // The Vue-path opt-out must hold on phones too.
+    expect(mobileBlock).toMatch(
+      /:root:has\(\.hk-modal-blur-plate\)\s*\.hk-modal-overlay\s*\{[^}]*backdrop-filter:\s*none/,
+    );
+  });
+});

package/src/components/HkModal.scss

@@ -23,6 +23,44 @@
 // Overlay (backdrop)
 // ------
 
+// The BLUR is a separate static plate, NOT on the fading overlay: a
+// backdrop-filter re-filters the whole viewport on every composited frame
+// while ANY animation is live (the steady state is cached and clean —
+// measured separately), and the enter storm (frame + dim + strip + crumbs
+// mounting together) measured 36% dropped frames with the filter live vs
+// 0% with it suppressed (2026-11-07 open-jank spike, headless rAF matrix;
+// one modal, blur 3px). The plate holds the filter and never animates;
+// the overlay below is a solid-color dim curtain whose opacity ramp is
+// the cheapest possible layer to animate — and the ramp is what the eye
+// tracks, so the blur cutting in with the first frame (instead of
+// ramping over 0.42s) reads as focus pull, not as a missing layer.
+.hk-modal-blur-plate {
+  position: fixed;
+  inset: 0;
+  // Below the overlay (0) and the content frame (1) inside the root's own
+  // stacking context — the plate is DOM-last but paints first.
+  z-index: -1;
+  @include backdrop-filter(var(--hk-modal-overlay-blur, blur(3px)));
+  // The root is pointer-events: none; the plate must never take clicks.
+  pointer-events: none;
+}
+
+// STACK-COVERED: a covered (non-topmost) window's plate is REMOVED
+// outright (display:none, not merely filter:none — a present
+// backdrop-filter element still forces the per-frame backdrop surface
+// during any animation even with the filter computed to none, measured
+// at ~44pp dropped frames vs 2% hidden; 2026-11-07 open-jank spike).
+// Blur reads as a property of the TOP surface anyway: lower windows sit
+// under the top window's own dim + blur, so their own filter is
+// visually redundant (blur-of-blur). The dim curtains are untouched:
+// depth still darkens, only the redundant blur legs drop. (The
+// breadcrumb strip — z band 250 — paints ABOVE these roots: the strip
+// band is not part of any plate's backdrop, which is why removing the
+// covered plates, not the strip, was the fix that measured.)
+.hk-modal-root[data-stack-covered] .hk-modal-blur-plate {
+  display: none;
+}
+
 .hk-modal-overlay {
   position: fixed;
   inset: 0;
@@ -32,10 +70,20 @@
   // handle hasn't resolved yet — zIndex briefly starts at 0).
   z-index: 0;
   background: var(--hk-modal-overlay-bg, rgba(0, 0, 0, 0.45));
+  // The overlay itself carries the blur ONLY where no plate exists (the
+  // Rust-rendered modals share this compiled sheet but their markup has
+  // no plate element — dropping the property from the overlay would
+  // silently strip their desktop blur). The Vue path always renders a
+  // plate, so :root:has(...) opts the overlay down to dim-only there and
+  // the plate owns the blur (including its stack-covered removal).
   @include backdrop-filter(var(--hk-modal-overlay-blur, blur(3px)));
   pointer-events: auto;
 }
 
+:root:has(.hk-modal-blur-plate) .hk-modal-overlay {
+  @include backdrop-filter(none);
+}
+
 // Overlay enter/leave — fade-only classes emitted from the shared
 // window-layer contract (./_scrim-fade.scss): the curtain dims the whole
 // viewport in place, never sliding or scaling with the content frame.
@@ -153,6 +201,11 @@
   .hk-modal-content-enter-from,
   .hk-modal-content-leave-to {
     opacity: 0;
+    // Pre-promote at insert: enter-from lands in the same frame the
+    // content mounts — carrying will-change HERE (shared with the leave's
+    // end pose) means the layer is composited before the transition's
+    // first measured frame, not one hitch later.
+    will-change: opacity, transform;
     transform: translate(
           calc(-50% + var(--hk-modal-shift-x, 0px)),
           calc(-50% + var(--hk-modal-shift-y, 0px))
@@ -443,10 +496,18 @@
   // the page, so an opaque-ish sheet reads identically. Hosts restore
   // the finish per surface with --hk-modal-blur-mobile /
   // --hk-modal-bg-mobile.
+  .hk-modal-blur-plate {
+    @include backdrop-filter(var(--hk-modal-overlay-blur-mobile, none));
+  }
+
   .hk-modal-overlay {
     @include backdrop-filter(var(--hk-modal-overlay-blur-mobile, none));
   }
 
+  :root:has(.hk-modal-blur-plate) .hk-modal-overlay {
+    @include backdrop-filter(none);
+  }
+
   // Height-morph window (round 20): while the sheet's height animates
   // every frame, a backdrop-filter anywhere in the resizing subtree has
   // to re-render its backdrop surface every frame — the same per-frame
@@ -565,6 +626,7 @@
   .hk-modal-content-leave-to {
     opacity: 0;
     height: auto;
+    will-change: opacity, transform;
     transform: translateY(100%);
   }
 

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

@@ -99,9 +99,14 @@ describe("sheet family morph-performance contract", () => {
     const panel = select.match(/\.hk-select-sheet-panel\s*{[\s\S]*?^}/m)?.[0] ?? "";
     expect(panel).toMatch(/^[ \t]*--hk-sheet-morph:[ \t]*clip;$/m);
     expect(panel).toMatch(/^[ \t]*contain:[ \t]*layout style;$/m);
+    // 2026-11-07 residue sweep: the panel rides the modal's ≤767px
+    // grammar — clip-path is the ONLY leg (clip mode pins instantly and
+    // folds transition-off, and a max-height leg on a dvh-capped sheet
+    // is the IME cap-chase the modal block fixed on 2026-09-21).
     expect(panel).toMatch(
-      /^[ \t]*clip-path var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
+      /^[ \t]*transition: clip-path var\(--duration-fast, 0\.15s\)[\s]*var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
     );
+    expect(panel).not.toMatch(/\bmax-height var\(--duration-fast/m);
     // Opaque already — the panel must not regress to a translucent
     // finish that re-composites against the streaming page.
     expect(panel).toMatch(/^[ \t]*background:[ \t]*rgb\(var\(--color-surface\)\);$/m);

package/src/components/HkModal.test.tsx

@@ -815,3 +815,81 @@ describe("HkModal Escape precedence", () => {
     expect(document.activeElement, "focus wraps back to the first focusable").toBe(first);
   });
 });
+
+describe("HkModal blur plate", () => {
+  it("renders the plate as the aria-hidden last child of the root", async () => {
+    // The plate is DOM-last so the sheet's stack-covered drop can be keyed
+    // by attribute scoping without depending on paint order (z-indexes
+    // carry that). Structural pin: last child + hidden from a11y.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const open = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, { modelValue: open.value }, { default: () => h("div", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await nextTick();
+    await nextTick();
+    const root = document.querySelector(".hk-modal-root")!;
+    const last = root.lastElementChild as HTMLElement | null;
+    expect(last?.classList.contains("hk-modal-blur-plate")).toBe(true);
+    expect(last?.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("marks covered roots while a higher window is open", async () => {
+    // TOP-ONLY BLUR wiring: the covered (lower) root carries
+    // data-stack-covered; the top root does not. Flips live with the
+    // registry: closing the top window un-covers the lower one.
+    const mounts2: ReturnType<typeof createApp>[] = [];
+    const containers2: HTMLElement[] = [];
+    try {
+      const openA = ref(true);
+      const openB = ref(true);
+      const mk = (mv: { value: boolean }, title: string) => {
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        containers2.push(container);
+        const Wrapper = defineComponent({
+          setup() {
+            return () =>
+              h(HkModal, { modelValue: mv.value, title }, { default: () => h("div", "content") });
+          },
+        });
+        const app = createApp(Wrapper);
+        mounts2.push(app);
+        app.mount(container);
+      };
+      mk(openA, "下层窗");
+      mk(openB, "上层窗");
+      await nextTick();
+      await nextTick();
+      const roots = () => [...document.querySelectorAll(".hk-modal-root")];
+      expect(roots()).toHaveLength(2);
+      // The later-registered window is the top: the FIRST root is covered.
+      const attrs = roots().map((r) => r.hasAttribute("data-stack-covered"));
+      expect(attrs).toEqual([true, false]);
+      openB.value = false;
+      await nextTick();
+      // The leave settles on the surface machine's own clock.
+      const deadline = Date.now() + 1500;
+      while (roots().some((r) => r.classList.contains("hk-modal-content-leave-active")) && Date.now() < deadline) {
+        await nextTick();
+      }
+      const deadline2 = Date.now() + 1500;
+      while (roots().some((r) => r.hasAttribute("data-stack-covered")) && Date.now() < deadline2) {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        await nextTick();
+      }
+      expect(roots().every((r) => !r.hasAttribute("data-stack-covered"))).toBe(true);
+    } finally {
+      for (const a of mounts2.splice(0)) a.unmount();
+      for (const c of containers2.splice(0)) c.remove();
+    }
+  });
+});

package/src/components/HkModal.tsx

@@ -566,6 +566,20 @@ export default defineComponent({
     // optimization for the class flip. See runtime/surfaceMachine.ts
     // for the axioms, the total transition table, and the invariants.
     const overlayEl = ref<HTMLElement>();
+    // TOP-ONLY BLUR: this window's blur plate carries the filter only
+    // while it is the topmost WINDOW-kind layer of the stack. The covered
+    // window's plate drops to dim-only (see the sheet) — with N stacked
+    // full-viewport backdrop-filters every composited frame re-runs all
+    // of them, and the open storm measured 36-55% dropped frames vs 2%
+    // with a single live filter. Reacts live: covered flips with every
+    // register/unregister above this window.
+    const stackCovered = computed(() => {
+      // Reuses the shared topWindowZ authority (the same windowing filter
+      // the dial consumes below) instead of a private registry scan.
+      const top = topWindowZ.value;
+      if (!handle.value || top === null) return false;
+      return handle.value.zIndex < top;
+    });
     const machine = useSurfaceMachine({
       layers: [
         // Budgets are the starvation-era upper bound; the driver probes
@@ -1071,6 +1085,7 @@ export default defineComponent({
         <Teleport to={ensureOverlayRoot()}>
           <div
             class="hk-modal-root"
+            data-stack-covered={stackCovered.value || undefined}
             style={{ zIndex: overlayZ.value, ...hkPadStyle(props.padding) }}
             onKeydown={onKeydown}
           >
@@ -1195,6 +1210,11 @@ export default defineComponent({
                   renderFooter(),
                   ])}
                 </div>
+          {/* Static blur plate — the LAST child of hk-modal-root so the
+              sheet's stack-covered drop ([data-stack-covered] on this
+              root) reaches it; paint order rides the explicit z-indexes
+              (plate -1 < overlay 0 < content 1), not DOM order. */}
+          <div class="hk-modal-blur-plate" aria-hidden="true" />
           </div>
         </Teleport>
       );

package/src/components/HkScrollContainer.tsx

@@ -453,7 +453,13 @@ export default defineComponent({
       }
       const band = vp.getBoundingClientRect();
       const active = pickActiveProgressRoot(band);
-      const rows = active ? active.root.querySelectorAll(props.scrollProgressSelector) : [];
+      // A list may own the row grammar (HkTable's section bands are body
+      // `<tr>`s that are not data rows); its `getRows` wins over the
+      // container selector. No `getRows` (or an undefined return) keeps the
+      // existing selector path byte-for-byte.
+      const rows = active
+        ? active.handle.getRows?.() ?? active.root.querySelectorAll(props.scrollProgressSelector)
+        : [];
       if (!active || rows.length === 0 || vp.scrollHeight <= vp.clientHeight + 1) {
         setProgressHidden();
         return;

package/src/components/HkScrollProgress.test.tsx

@@ -11,6 +11,7 @@ import { createApp, defineComponent, h, inject, nextTick, onMounted, onUnmounted
 
 import HkScrollContainer from "./HkScrollContainer";
 import { HkAdminTablePage } from "./HkAdminTablePage";
+import HTable from "./HkTable";
 import { HK_SCROLL_PROGRESS_REGISTRAR, type HkScrollProgressRegistrar } from "./HkScrollProgress";
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
@@ -219,6 +220,24 @@ describe("HkScrollProgress", () => {
     expect(pill.textContent).toBe("11 / 340");
   });
 
+  it("counts only a sectioned HkTable's data rows, not its bands", async () => {
+    // The band is a `<tr>` in the section body but not a row. The table's
+    // handle `getRows` wins over the container's `tbody tr` selector, so
+    // the pill reports 2 sections x 2 rows = 4, not 6.
+    const sections = [
+      { key: "panel-a", label: "Panel A", rows: [{ name: "a0" }, { name: "a1" }] },
+      { key: "panel-b", label: "Panel B", rows: [{ name: "b0" }, { name: "b1" }] },
+    ];
+    const scroller = mountScroller(() =>
+      h(HTable, { columns: [{ key: "name", title: "Name" }], sections }),
+    );
+    stubRootRect(scroller.container, ".hk-table-host", -100, 1900);
+    stubRows(scroller.container, 6, 0);
+    scroller.refresh();
+    await nextTick();
+    expect(scroller.pill()!.textContent).toBe("1 / 4");
+  });
+
   it("falls back to the DOM row count when the total is absent", async () => {
     const List = makeList({ rows: ROWS });
     const scroller = mountScroller(() => h(List));

package/src/components/HkScrollProgress.tsx

@@ -24,6 +24,12 @@ import "./HkScrollProgress.scss";
 export interface HkScrollProgressHandle {
   getRoot(): HTMLElement | null;
   getTotal(): number | undefined;
+  /** The list's own row elements in display order — wins over the
+   *  container's `scrollProgressSelector` when present. This is for a
+   *  list whose DOM rows are not all data rows (HkTable's section bands
+   *  are `<tr>`s in the body, but they are not rows). Return `undefined`
+   *  to fall back to the container's selector. */
+  getRows?(): readonly Element[] | undefined;
 }
 
 /** Provided by every HkScrollContainer instance whose `scrollProgress`

package/src/components/HkSelect.scss

@@ -311,24 +311,29 @@
   display: flex;
   flex-direction: column;
   /* The panel height hugs its content (up to the cap below); the sheet
-   * morphs smoothly when content grows/shrinks — a language list gaining
-   * or losing rows, a select whose options filter. `height: auto` growth
+   * morphs when content grows/shrinks — a language list gaining or
+   * losing rows, a select whose options filter. `height: auto` growth
    * cannot fire a CSS transition, so HkSelectPanel's useSizeMorph pins
-   * the measured natural height as px (see useSizeMorph) and the
-   * transition below animates old→new px; `interpolate-size: allow-keywords`
-   * stays harmless for the enter/leave slide. Growth reveals through
-   * clip-path instead (--hk-sheet-morph: clip, see useSizeMorph): the
-   * pin lands instantly and the top edge sweeps up paint-only — the
-   * sheet is a fixed full-width layer, and an animated height relaid
-   * out + repainted it every frame (mobile patchy-flicker source,
-   * 2026-09-15). Same duration/ease tokens, same stretch look. */
+   * the measured natural height as px (see useSizeMorph) and growth
+   * reveals through clip-path (--hk-sheet-morph: clip, see
+   * useSizeMorph): the pin lands instantly and the top edge sweeps up
+   * paint-only — the sheet is a fixed full-width layer, and an animated
+   * height relaid out + repainted it every frame (mobile
+   * patchy-flicker source, 2026-09-15). Shrink folds the same way and
+   * the atomic re-pin lands transition-off, so — exactly like the
+   * modal's ≤767px block — the clip-path leg is the ONLY animated
+   * property here. The max-height leg in particular must stay OUT: the
+   * cap below carries a live dvh/inset term, and with max-height in the
+   * list an adjustResize keyboard RETARGETS a 150ms transition every
+   * frame — cap-bound sheets chase their own viewport permanently (the
+   * IME cap-chase the modal block fixed on 2026-09-21; aligning this
+   * panel to that grammar on 2026-11-07 — inference-level evidence,
+   * same engine class, no same-day field report). */
   interpolate-size: allow-keywords;
   --hk-sheet-morph: clip;
   contain: layout style;
-  transition:
-    height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
-    max-height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
-    clip-path var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
+  transition: clip-path var(--duration-fast, 0.15s)
+    var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
   max-height: min(
     72vh,
     calc(

package/src/components/HkTable.scss

@@ -95,6 +95,26 @@
   background: var(--hi-color-bg-subtle, rgba(255, 255, 255, 0.03));
 }
 
+/* A section's band is the first child of its body, so the base zebra rule
+   would shade each section's FIRST data row (child 2). Restart the phase
+   after the band: even data children are unshaded, odd ones carry the
+   stripe — the same first-row-unshaded phase an unsectioned body has. */
+.hk-table-striped .hk-table-section-body .hk-table-row:nth-child(even) {
+  background: none;
+}
+
+.hk-table-striped .hk-table-section-body .hk-table-row:nth-child(odd) {
+  background: var(--hi-color-bg-subtle, rgba(255, 255, 255, 0.03));
+}
+
+/* The sectioned zebra pair above is (0,4,0) — it would out-specify the
+   shared `.hk-table-hover .hk-table-row:hover` rule (0,3,0) and kill hover
+   feedback on EVERY row of a striped sectioned table. Keep the pointer
+   feedback by re-stating it at a spec that beats the pair. */
+.hk-table-striped.hk-table-hover .hk-table-section-body .hk-table-row:hover {
+  background: var(--hi-color-bg-subtle, rgba(255, 255, 255, 0.04));
+}
+
 .hk-table-bordered {
   border: 1px solid var(--hi-color-border, rgba(100,100,100,0.1));
   border-radius: var(--radius-md, 8px);
@@ -153,6 +173,51 @@
   color: var(--hi-color-text-secondary, #666666);
 }
 
+/* ── Section bands (grouped tables) ───────────────────────────────────
+   One `<tbody>` per section, each led by a band row. The band is a
+   rowgroup header, not a data row: it never carries `.hk-table-row`, so
+   the copy layer (which marks and cursor-styles cells via
+   `[data-copy-cell]`), the hover paint, the striped rule, the drag strip
+   and the selection/⋯ tracks all ignore it by construction. The band cell
+   carries no `data-copy-cell`, so it needs no copy-cursor override either.
+
+   The cell itself is TYPE-NEUTRAL for consumer markup: the `section` slot
+   carries arbitrary content (badges, panel names, status chips), so only
+   the track is styled here (padding / hairline / background / start
+   alignment). `font-weight: inherit` neutralizes the UA `th { font-weight:
+   bold }`; nothing here sets `white-space` (long panel names may wrap) or
+   `cursor` (selectable band text keeps its I-beam). Sizing is delivered by
+   the consumer's own classes; the plain `label` fallback gets its own span
+   below. The hk-table-sm/lg ladder steps ONLY the band's padding —
+   typography deliberately does not scale with the table size, because the
+   consumer's slot content owns its type. */
+.hk-table-section-cell {
+  padding: var(--space-8, 8px) var(--space-12, 12px);
+  border-bottom: 1px solid var(--hi-color-border, rgba(100,100,100,0.08));
+  text-align: start;
+  background: var(--hi-color-bg-subtle, rgba(255, 255, 255, 0.03));
+  font-weight: inherit;
+}
+
+/* The default `label` branch only (the `section` slot bypasses this span
+   entirely): the previous text-sm / font-medium band look. */
+.hk-table-section-label {
+  font-size: var(--text-sm, 0.875rem);
+  font-weight: 500;
+}
+
+.hk-table-sm .hk-table-section-cell {
+  padding: var(--space-4, 4px) var(--space-8, 8px);
+}
+
+.hk-table-lg .hk-table-section-cell {
+  padding: var(--space-16, 16px) var(--space-24, 24px);
+}
+
+.hk-table-bordered .hk-table-section-cell {
+  border: 1px solid var(--hi-color-border, rgba(100,100,100,0.06));
+}
+
 /* ── Drag-to-reorder (draggable) ─────────────────────────────────────── */
 
 .hk-table-drag-handle {