@celestia-island/hikari 0.55.58 → 0.55.60

package/package.json

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

package/src/components/HkCard.scrollable.test.tsx

@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkCard from "./HkCard";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountCard(props: Record<string, unknown> = {}, slotText = "content") {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(HkCard, props, { default: () => h("span", { class: "slot-marker" }, slotText) }),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const m of mounts) m.app.unmount();
+  mounts.length = 0;
+});
+
+describe("HkCard — scrollable body", () => {
+  it("default card renders no scroll machinery", () => {
+    const c = mountCard();
+    expect(c.querySelector(".hk-card-scrollable")).toBeNull();
+    expect(c.querySelector(".hk-scroll-container")).toBeNull();
+    // The slot lands directly in the body, no pad wrapper in between.
+    expect(c.querySelector(".hk-card-body .slot-marker")).not.toBeNull();
+    expect(c.querySelector(".hk-card-body-pad")).toBeNull();
+  });
+
+  it("scrollable embeds the standard scroll container and flex classes", () => {
+    const c = mountCard({ scrollable: true });
+    expect(c.querySelector(".hk-card-scrollable")).not.toBeNull();
+    const scroll = c.querySelector(".hk-card-body .hk-scroll-container");
+    expect(scroll).not.toBeNull();
+    // The embedded scroller IS the library scroll container (overlay
+    // scrollbar machinery), not a bare overflow div.
+    expect(scroll?.querySelector(".hk-scroll-container-viewport")).not.toBeNull();
+    // Padded card: content padding lives inside the scroll region.
+    expect(c.querySelector(".hk-scroll-container .hk-card-body-pad .slot-marker")).not.toBeNull();
+  });
+
+  it("padded false drops the inner pad wrapper too", () => {
+    const c = mountCard({ scrollable: true, padded: false });
+    expect(c.querySelector(".hk-card-body-pad")).toBeNull();
+    expect(c.querySelector(".hk-scroll-container .slot-marker")).not.toBeNull();
+  });
+
+  it("header and footer stay outside the scroll region", () => {
+    const c = mountCard(
+      { scrollable: true, title: "T" },
+      undefined,
+    );
+    // Re-mount with a footer slot via raw slots is not available through
+    // the props-only helper; assert the header ordering here and cover
+    // the footer through the props-less variant below.
+    const header = c.querySelector(".hk-card-header");
+    const scroll = c.querySelector(".hk-card-body-scroll");
+    expect(header).not.toBeNull();
+    expect(scroll).not.toBeNull();
+    expect(header!.contains(scroll as Node)).toBe(false);
+  });
+
+  it("footer renders after the scroll body, not inside it", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(HkCard, { scrollable: true }, {
+          default: () => h("span", { class: "slot-marker" }, "content"),
+          footer: () => h("div", { class: "footer-marker" }, "foot"),
+        }),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+
+    const footer = container.querySelector(".hk-card-footer");
+    const scroll = container.querySelector(".hk-card-body-scroll");
+    expect(footer).not.toBeNull();
+    expect(footer!.contains(scroll as Node)).toBe(false);
+    expect(scroll!.contains(footer as Node)).toBe(false);
+  });
+
+  it("scroll content survives remounts of the pad wrapper class", () => {
+    // Padding flag flips at runtime (a consumer toggling density): the
+    // scroll container must persist (keyed on nothing but its slot).
+    const c = mountCard({ scrollable: true });
+    expect(c.querySelector(".hk-card-body-pad")).not.toBeNull();
+  });
+});

package/src/components/HkCard.scss

@@ -53,3 +53,38 @@
   padding: var(--space-12) var(--space-16);
   border-top: 1px solid var(--border-faint);
 }
+
+/* Scrollable card: the body becomes the flex host of an embedded
+   HkScrollContainer, so the card carries the ONE library scrollbar
+   system instead of every consumer nesting its own scroll layer.
+   Header and footer stay natural-height; the body fills the remainder.
+   Content padding lives INSIDE the scroll region (the pad wrapper the
+   component renders when `padded` is set) so the overlay scrollbar
+   hugs the card edge while content keeps its inset while scrolling. */
+.hk-card-scrollable {
+  display: flex;
+  flex-direction: column;
+
+  > .hk-card-header,
+  > .hk-card-footer {
+    flex: none;
+  }
+
+  > .hk-card-body {
+    display: flex;
+    flex-direction: column;
+    flex: 1 1 auto;
+    min-height: 0;
+    padding: 0;
+    overflow: hidden;
+  }
+
+  > .hk-card-body > .hk-card-body-scroll {
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+
+  .hk-card-body-pad {
+    padding: var(--space-16);
+  }
+}

package/src/components/HkCard.tsx

@@ -1,5 +1,6 @@
 import { defineComponent } from "vue";
 
+import HkScrollContainer from "./HkScrollContainer";
 import "./HkCard.scss";
 
 export default defineComponent({
@@ -8,6 +9,17 @@ export default defineComponent({
     title: { type: String, default: undefined },
     hoverable: { type: Boolean, default: false },
     padded: { type: Boolean, default: true },
+    /** Turn the card body into the library's standard scroll region
+     *  (HkScrollContainer: overlay scrollbar, overflow sensing) instead
+     *  of a plain static block. The card becomes a column flex box —
+     *  header and footer keep their natural height while the body
+     *  fills the rest and scrolls. The card itself needs a height from
+     *  its context (grid stretch, an explicit h-* / max-h-* utility, or a flex
+     *  parent), exactly like any scroll container: without one there is
+     *  nothing to scroll and the body simply fits. Content padding
+     *  moves inside the scroll region so the scrollbar hugs the card
+     *  edge; `padded: false` drops the inner padding as usual. */
+    scrollable: { type: Boolean, default: false },
     class: { type: String, default: "" },
   },
   emits: {
@@ -18,6 +30,7 @@ export default defineComponent({
       <div
         class={[
           "hk-card",
+          props.scrollable ? "hk-card-scrollable" : "",
           props.hoverable ? "hk-card-hoverable" : "",
           props.class,
         ]}
@@ -29,7 +42,13 @@ export default defineComponent({
           </div>
         ) : null}
         <div class={["hk-card-body", !props.padded ? "hk-card-body-unpadded" : ""]}>
-          {slots.default?.()}
+          {props.scrollable ? (
+            <HkScrollContainer axis="vertical" class="hk-card-body-scroll">
+              <div class={props.padded ? "hk-card-body-pad" : undefined}>{slots.default?.()}</div>
+            </HkScrollContainer>
+          ) : (
+            slots.default?.()
+          )}
         </div>
         {slots.footer ? <div class="hk-card-footer">{slots.footer()}</div> : null}
       </div>

package/src/components/HkModal.scss

@@ -451,6 +451,18 @@
     backdrop-filter: var(--hk-modal-overlay-blur-mobile, 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
+  // surface churn that made promoted layers flash through on phone
+  // GPUs, and the 2026-09-15 report's patchy-flicker source. The morph
+  // flags the frame, and the sticky step indicator drops its blur for
+  // the window (its 95%-opaque background keeps it visually
+  // indistinguishable).
+  .hk-modal-content[data-hk-morphing] .hk-scroll-pin {
+    backdrop-filter: none;
+  }
+
   .hk-modal-content {
     // Phone-sheet transition = clip-path ONLY (2026-09-21, two Xiaomi
     // WebView chest reports same day):

package/src/composables/useSizeMorph.test.ts

@@ -1170,11 +1170,19 @@ describe("useSizeMorph deferRemeasure gate (freeze protocol witness)", () => {
 
 describe("useSizeMorph heightMorph (round 18)", () => {
   it("transitions the pin with an inline height transition and cleans up", async () => {
-    const h = mountHarness(300, 300);
+    // A resident rider (the host chrome) is promoted at arm time — the
+    // morph must demote it too: the body block is a flex child, so its
+    // box resizes every frame of a height transition.
+    const rider = document.createElement("div");
+    const h = mountHarness(300, 300, {
+      collectRide: () => [{ el: rider }],
+    });
     h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.content.appendChild(rider);
     h.start();
     expect(h.frame.style.height).toBe("300px");
     expect(h.frame.style.willChange).toBe("clip-path");
+    expect(rider.style.willChange).toBe("transform");
 
     h.setNatural(400);
     (h as unknown as { heightMorph: (ms: number) => void }).heightMorph(300);
@@ -1184,20 +1192,70 @@ describe("useSizeMorph heightMorph (round 18)", () => {
     expect(h.frame.style.transition).toContain("300ms");
     // No clip staging, no riders — this is a plain height animation.
     expect(h.frame.style.clipPath).toBe("");
-    // The resident layer promotion is LIFTED for the animation's
-    // duration (round 19: the per-frame texture re-allocation of a
-    // composited layer during height animation composites as
-    // transparent on phone GPUs — the background flash-through).
+    // EVERY resident promotion is lifted for the animation's duration
+    // (round 19: the frame; round 20: the riders too — the body block
+    // is a flex child, so its box resizes every frame and its
+    // composited texture re-allocates every frame, which is the
+    // content-area flash-through the phone kept reporting). The morph
+    // flag is up so the stylesheet can drop per-frame backdrop-filter
+    // work as well.
     expect(h.frame.style.willChange).toBe("");
+    expect(rider.style.willChange).toBe("");
+    expect(h.frame.hasAttribute("data-hk-morphing")).toBe(true);
 
-    // The transitionend cleans the inline override AND restores the
-    // resident promotion (the frame is at rest).
+    // The transitionend cleans the inline override, drops the morph
+    // flag and restores every promotion (the frame is at rest).
     const ev = new Event("transitionend");
     Object.defineProperty(ev, "propertyName", { value: "height" });
     h.frame.dispatchEvent(ev);
     expect(h.frame.style.transition).toBe("");
     expect(h.frame.style.willChange).toBe("clip-path");
+    expect(rider.style.willChange).toBe("transform");
+    expect(h.frame.hasAttribute("data-hk-morphing")).toBe(false);
+    h.stop();
+  });
+
+  it("keeps the demotion across overlapping morphs (generation guard)", async () => {
+    // A second navigation can land while the first height animation is
+    // still running. The superseded morph's watchdog must NOT restore
+    // the promotions in the middle of the successor's animation — the
+    // rig caught a re-promoted rider there. Only the newest generation
+    // restores, and it restores the ORIGINAL values (the first
+    // demotion's snapshot), not the empty ones it observed.
+    vi.useFakeTimers();
+    const rider = document.createElement("div");
+    const h = mountHarness(300, 300, {
+      collectRide: () => [{ el: rider }],
+    });
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.content.appendChild(rider);
+    h.start();
+    expect(rider.style.willChange).toBe("transform");
+
+    // Morph #1 starts at t=0 (watchdog at 120+350ms).
+    h.setNatural(400);
+    h.heightMorph(120);
+    expect(rider.style.willChange).toBe("");
+    // Morph #2 lands 100ms later (its own watchdog at 570ms).
+    vi.advanceTimersByTime(100);
+    h.setNatural(500);
+    h.heightMorph(120);
+    // #1's watchdog (470ms) fires inside #2's window — and must not
+    // touch the successor's demotion.
+    vi.advanceTimersByTime(380);
+    expect(
+      rider.style.willChange,
+      "the superseded morph must not re-promote mid-animation",
+    ).toBe("");
+    expect(h.frame.hasAttribute("data-hk-morphing")).toBe(true);
+
+    // #2's own window closes: everything comes back.
+    vi.advanceTimersByTime(120);
+    expect(rider.style.willChange).toBe("transform");
+    expect(h.frame.style.willChange).toBe("clip-path");
+    expect(h.frame.hasAttribute("data-hk-morphing")).toBe(false);
     h.stop();
+    vi.useRealTimers();
   });
 
   it("is a no-op for sub-threshold deltas", async () => {

package/src/composables/useSizeMorph.ts

@@ -245,6 +245,17 @@ export function useSizeMorph(
    *  small, and opacity-composited by its own fade anyway) keep the
    *  stage-time promotion. */
   let residentRideEls: HTMLElement[] = [];
+  /** Height-morph promotion snapshot (round 20). Overlapping morphs are
+   *  possible (a second navigation lands while the first height
+   *  animation still runs): the FIRST demotion captures the real
+   *  resident values, later morphs leave the snapshot alone, and only
+   *  the newest generation's restore puts them back — otherwise a
+   *  superseded morph's watchdog re-promotes the riders in the middle
+   *  of the successor's animation (the rig caught exactly that). */
+  let morphEpoch = 0;
+  let morphDemoted = false;
+  let morphSavedFrameWill = "";
+  let morphSavedRiderWills: Array<[HTMLElement, string]> = [];
   /** Identity of the sweep currently staged/folding, echoed to consumers. */
   let sweepSeq = 0;
   let activeSweep = 0;
@@ -440,8 +451,14 @@ export function useSizeMorph(
   /** Drop the resident layer promotion (hold / release paths) — the
    *  frame's own and the resident riders' together: the whole open
    *  cycle's layerization unwinds at once, inside the close
-   *  choreography's own leave window. */
+   *  choreography's own leave window. A height morph still in flight
+   *  loses its restore snapshot here too: the cycle is over, so the
+   *  pending restore must not put the promotions back on a sheet that
+   *  already unwound them. */
   function clearResidentWill(): void {
+    morphSavedRiderWills = [];
+    morphSavedFrameWill = "";
+    morphDemoted = false;
     for (const el of residentRideEls) {
       el.style.willChange = "";
     }
@@ -936,36 +953,64 @@ export function useSizeMorph(
     // 2. Re-establish the OLD pin under no transition, flush it.
     f.style.height = `${pinned}px`;
     void f.offsetHeight;
-    // 3. DEMOTE the frame from its resident composited layer for the
-    //    animation's duration. A `will-change: clip-path` layer whose
-    //    element changes layout size per-frame re-allocates its GPU
-    //    texture every frame — on a phone GPU the gap between the old
-    //    texture being discarded and the new one rastering composites
-    //    as TRANSPARENT, flashing the page behind the sheet through
-    //    (round-19 report: "background content keeps flashing"). With
-    //    the promotion lifted, the height animation's per-frame paint
-    //    happens on the main thread, which is slower but never leaves
-    //    a frame where the sheet's surface is missing.
-    const residentWill_ = f.style.willChange;
+    // 3. DEMOTE every promoted layer in the sheet for the animation's
+    //    duration — the frame AND the resident riders. A composited
+    //    layer whose element changes layout size per-frame re-allocates
+    //    its GPU texture every frame; on a phone GPU the gap between the
+    //    old texture being discarded and the new one rastering
+    //    composites as TRANSPARENT, so the region that layer covers
+    //    flashes through to the page behind (round-19 report on the
+    //    frame; round-20 report showed the flicker persisting over
+    //    exactly the CONTENT area — the body block keeps its resident
+    //    promotion from round 15 and is a flex child, so its box
+    //    resizes every frame of a height transition). A backdrop-filter
+    //    on a resizing subtree is the same class of per-frame surface
+    //    churn (the sticky step indicator's blur), so the morph also
+    //    flags the frame for the stylesheet to drop it. With everything
+    //    demoted the height animation's per-frame paint happens on the
+    //    main thread, which is slower but never leaves a frame where
+    //    the sheet's surface is missing.
+    const epoch = ++morphEpoch;
+    if (!morphDemoted) {
+      morphSavedFrameWill = f.style.willChange;
+      morphSavedRiderWills = residentRideEls.map((el) => [
+        el,
+        el.style.willChange,
+      ]);
+      morphDemoted = true;
+    }
     if (residentWill) {
       f.style.willChange = "";
       residentWill = false;
     }
+    for (const el of residentRideEls) {
+      el.style.willChange = "";
+    }
+    f.setAttribute("data-hk-morphing", "");
     f.style.transition =
       `height ${durationMs}ms cubic-bezier(0.4, 0, 0.2, 1)`;
     f.style.height = `${next}px`;
     pinned = next;
     // 4. Clean up on the animation's own clock: restore the transition
-    //    list and the resident layer promotion together — the frame is
-    //    at its final geometry and at rest, so the re-promotion's
+    //    list, the morph flag and every promotion together — the frame
+    //    is at its final geometry and at rest, so the re-promotion's
     //    raster has all the time it needs.
     const restore = (): void => {
       f.removeEventListener("transitionend", onEnd);
+      // A superseded morph must not touch the successor's demotion.
+      if (epoch !== morphEpoch) return;
       f.style.transition = "";
-      if (residentWill_ === "clip-path") {
+      f.removeAttribute("data-hk-morphing");
+      if (morphSavedFrameWill === "clip-path") {
         f.style.willChange = "clip-path";
         residentWill = true;
       }
+      for (const [el, will] of morphSavedRiderWills) {
+        el.style.willChange = will;
+      }
+      morphSavedRiderWills = [];
+      morphSavedFrameWill = "";
+      morphDemoted = false;
     };
     const onEnd = (ev: TransitionEvent): void => {
       if (ev.target === f && ev.propertyName === "height") {
@@ -973,10 +1018,7 @@ export function useSizeMorph(
       }
     };
     f.addEventListener("transitionend", onEnd);
-    const watchdog = setTimeout(restore, durationMs + 350);
-    // If the element goes away mid-flight, don't leak the timer.
-    const origClear = watchdog;
-    void origClear; // timer fires restore() which is idempotent
+    setTimeout(restore, durationMs + 350);
   }
 
   return { start, stop, hold, remeasure, heightMorph };