@celestia-island/hikari 0.52.0 → 0.53.0

package/package.json

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

package/src/components/HkDrawer.scss

@@ -22,9 +22,19 @@
   display: flex;
   flex-direction: column;
   background: var(--hk-drawer-bg, var(--hi-color-surface, rgba(240,244,248,0.95)));
-  backdrop-filter: blur(12px);
+  // Token-gated (was a hard blur(12px)): the drawer resizes through
+  // animated width/height, and a backdrop-filter on a resizing fixed
+  // layer re-rasters the blurred region every frame — on phones that
+  // lag shows as patchy flicker along the moving edge. The mobile
+  // guard below turns it off ≤767px; hosts restore a finish per
+  // surface with --hk-drawer-blur / --hk-drawer-blur-mobile.
+  backdrop-filter: var(--hk-drawer-blur, blur(12px));
   box-shadow: 0 8px 32px rgba(0, 0, 0, 0.16);
   outline: none;
+  // Scope layout/style invalidation to the drawer subtree — the page
+  // behind a phone drawer is usually streaming, and containment keeps
+  // those invalidations from cascading into each other.
+  contain: layout style;
   transition:
     width var(--duration-normal, 0.3s) ease,
     height var(--duration-normal, 0.3s) ease;
@@ -178,6 +188,20 @@
 // family's 44px touch lift. Same geometry, same tokens, one family.
 // ------
 @media (max-width: 767px) {
+  // Phones: docked drawers never backdrop-filter — the panel resizes
+  // through animated width/height, and a backdrop-filter on a resizing
+  // fixed layer re-rasters the blurred region every frame; on a phone
+  // GPU that lag shows as patchy flicker along the moving edge (same
+  // family guard as the modal/select sheets, 2026-09-15 chest report).
+  // The scrim's dim alone reads correctly there.
+  .hk-drawer-overlay {
+    backdrop-filter: var(--hk-drawer-overlay-blur-mobile, none);
+  }
+
+  .hk-drawer-panel {
+    backdrop-filter: var(--hk-drawer-blur-mobile, none);
+  }
+
   .hk-drawer-bottom {
     bottom: var(--hk-sheet-bottom-gap, 0px);
     border-radius: var(--hk-modal-radius, var(--radius-lg, 12px))

package/src/components/HkModal.scss

@@ -68,9 +68,14 @@
   // (capped) height and pins it as px on every content change — the
   // transition below animates old→new px. Both pinned values are
   // explicit px, so this needs no interpolate-size keyword support.
+  // clip-path rides the same token pair for the mobile sheet's reveal
+  // morph (--hk-sheet-morph: clip below): the pin lands instantly and
+  // the top edge sweeps up paint-only — no per-frame layout, no
+  // per-frame backdrop re-raster over the resizing fixed layer.
   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));
+    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));
   background: var(--hk-modal-bg, var(--hi-color-surface, rgba(240,244,248,0.95)));
   backdrop-filter: var(--hk-modal-blur, none);
   border: 1px solid var(--hk-modal-border-color, var(--hi-color-border, rgba(100,100,100,0.08)));
@@ -402,6 +407,19 @@
 //   - rounded top corners only, full width
 // ------
 @media (max-width: 767px) {
+  // Docked sheets never re-filter their backdrop per frame: the sheet
+  // is a fixed, full-width layer whose geometry changes with every
+  // content morph, and a backdrop-filter on a resizing layer re-rasters
+  // the blurred region each frame — on a phone GPU that lag shows as
+  // patchy flicker along the moving edge (2026-09-15 chest report:
+  // model dialog etc. while content streamed). The scrim already dims
+  // 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-overlay {
+    backdrop-filter: var(--hk-modal-overlay-blur-mobile, none);
+  }
+
   .hk-modal-content {
     // !important beats the inline maxWidth (width prop); base width: 100%
     // already applies at every viewport, so only the cap is re-asserted.
@@ -419,6 +437,22 @@
     left: 0;
     right: 0;
     transform: none;
+    // Content morphs reveal by clip instead of animating height (see
+    // useSizeMorph): the pin lands instantly and the top edge sweeps up
+    // as a paint-only clip with the box's own corner radii — the same
+    // "content rides rigidly" grammar as the desktop unveil, and the
+    // CSS flag keeps the media query the single owner of the behavior.
+    --hk-sheet-morph: clip;
+    // Scope layout/style invalidation to the sheet subtree: the page
+    // behind a phone sheet is usually streaming (chat updates), and
+    // containment keeps those invalidations — and the sheet's own —
+    // from cascading into each other.
+    contain: layout style;
+    backdrop-filter: var(--hk-modal-blur-mobile, none);
+    background: var(
+      --hk-modal-bg-mobile,
+      var(--hk-modal-bg, var(--hi-color-surface, rgba(240, 244, 248, 0.95)))
+    );
     border-radius: var(--hk-modal-radius, var(--radius-lg, 12px))
                    var(--hk-modal-radius, var(--radius-lg, 12px))
                    0 0;

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

@@ -0,0 +1,127 @@
+/**
+ * Source contract for the sheet family's morph-performance grammar
+ * (2026-09-15 chest mobile report: bottom sheets — model dialog, select
+ * sheets, drawers — flickered in patches while their height changed;
+ * a phone's raster of a backdrop-filtered fixed layer lags the layer's
+ * animated geometry, and an animated `height` relaid out the sheet
+ * subtree every frame on the same main thread that was streaming the
+ * page behind).
+ *
+ * The family answer, pinned here so a refactor cannot silently regress:
+ *   - growth morphs REVEAL through clip-path (--hk-sheet-morph: clip on
+ *     the docking surfaces, useSizeMorph does the pin-instantly +
+ *     sweep-up dance) — paint/compositor-level, zero per-frame layout;
+ *     the frame stylesheet carries the clip-path transition on the SAME
+ *     duration/ease tokens as the height transition, so the stretch look
+ *     and its reduced-motion / data-css-animations governance are intact
+ *   - docked phone surfaces NEVER backdrop-filter (mobile-guard tokens
+ *     defaulting to none: --hk-modal-blur-mobile, --hk-modal-overlay-
+ *     blur-mobile, --hk-drawer-blur-mobile, --hk-drawer-overlay-blur-
+ *     mobile, --hk-popover-blur-mobile) — the scrim's dim reads alone
+ *   - docking surfaces carry `contain: layout style` so the streaming
+ *     page behind and the sheet subtree stop invalidating into each
+ *     other
+ *
+ * The JS half of the contract (pin instantly, sweep from the old edge,
+ * clear on transitionend / new dance / stop) lives in
+ * composables/useSizeMorph.test.ts.
+ */
+import { beforeAll, describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (name: string): string => readFileSync(join(here, name), "utf-8");
+const modal = read("HkModal.scss");
+const select = read("HkSelect.scss");
+const drawer = read("HkDrawer.scss");
+const popover = read("HkPopover.scss");
+
+describe("sheet family morph-performance contract", () => {
+  let mobileModal = "";
+  beforeAll(() => {
+    mobileModal = modal.slice(modal.indexOf("@media (max-width: 767px)"));
+  });
+
+  // Declaration assertions are LINE-ANCHORED (property → value →
+  // semicolon, own line): a plain toContain() on the token happily
+  // matches the explanatory COMMENT beside the rule — R2 mutation N2
+  // proved the select-sheet flag could be deleted with the suite still
+  // green because its comment mentions the same token.
+
+  it("flags the docked modal sheet for clip-mode growth morphs", () => {
+    expect(mobileModal).toMatch(/^[ \t]*--hk-sheet-morph:[ \t]*clip;$/m);
+  });
+
+  it("carries a clip-path transition on the morph timing tokens", () => {
+    // Same duration/ease pair as the height morph — the reveal must keep
+    // the stretch look, not invent new timing.
+    const frame = modal.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
+    expect(frame).toMatch(
+      /^[ \t]*clip-path var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
+    );
+  });
+
+  it("never backdrop-filters the docked modal sheet or its scrim", () => {
+    expect(mobileModal).toMatch(
+      /^[ \t]*backdrop-filter:[ \t]*var\(--hk-modal-blur-mobile, none\);$/m,
+    );
+    expect(mobileModal).toMatch(
+      /^[ \t]*backdrop-filter:[ \t]*var\(--hk-modal-overlay-blur-mobile, none\);$/m,
+    );
+  });
+
+  it("scopes the docked modal sheet with layout containment", () => {
+    expect(mobileModal).toMatch(/^[ \t]*contain:[ \t]*layout style;$/m);
+  });
+
+  it("applies the same grammar to the select sheet panel", () => {
+    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);
+    expect(panel).toMatch(
+      /^[ \t]*clip-path var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/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);
+  });
+
+  it("token-gates the drawer panel blur and guards it on phones", () => {
+    // Desktop keeps its finish through the token; the hard-coded blur
+    // must not return (it escaped the mobile guard entirely).
+    const panel = drawer.match(/\.hk-drawer-panel\s*{[^}]*}/)?.[0] ?? "";
+    expect(panel).toMatch(
+      /^[ \t]*backdrop-filter:[ \t]*var\(--hk-drawer-blur, blur\(12px\)\);$/m,
+    );
+    expect(panel).toMatch(/^[ \t]*contain:[ \t]*layout style;$/m);
+
+    const mobile = drawer.slice(drawer.indexOf("@media (max-width: 767px)"));
+    expect(mobile).toMatch(
+      /^[ \t]*backdrop-filter:[ \t]*var\(--hk-drawer-blur-mobile, none\);$/m,
+    );
+    expect(mobile).toMatch(
+      /^[ \t]*backdrop-filter:[ \t]*var\(--hk-drawer-overlay-blur-mobile, none\);$/m,
+    );
+  });
+
+  it("keeps the drawer's mobile rules in ONE media block", () => {
+    // HkDrawer.sheetfamily.test.ts slices the source from the FIRST
+    // max-width: 767px block and regex-matches rules after it — where
+    // that first block sits decides which rules its slice can even see
+    // (a guard block placed before the .hk-drawer-bottom base rule once
+    // redirected the family match to the base rule and reddened the
+    // contract). One block, one concern: the mobile guards live inside
+    // the family block, and no second block may wander in.
+    expect(drawer.match(/@media \(max-width: 767px\)/g)).toHaveLength(1);
+  });
+
+  it("guards the popover sheet variant the same way", () => {
+    const sheet = popover.match(/\.hk-popover-panel\.hk-is-sheet\s*{[\s\S]*?^}/m)?.[0] ?? "";
+    expect(sheet).toMatch(
+      /^[ \t]*backdrop-filter:[ \t]*var\(--hk-popover-blur-mobile, none\);$/m,
+    );
+    expect(sheet).toMatch(/^[ \t]*contain:[ \t]*layout style;$/m);
+  });
+});

package/src/components/HkPopover.scss

@@ -106,6 +106,15 @@
    * rule's max-content width would over-constrain it (left+right+width
    * drops `right` in LTR) and dock it at content width instead. */
   width: auto;
+  /* Docked popover sheets never backdrop-filter: the sheet is a fixed
+   * full-width layer over a usually-streaming page, and a
+   * backdrop-filter re-rasters the blurred region on every repaint
+   * behind it — on phones that lag shows as patchy flicker (same
+   * family guard as the modal/select sheets, 2026-09-15). Hosts
+   * restore a finish with --hk-popover-blur-mobile. Containment
+   * scopes the sheet's layout/style invalidations away from the page. */
+  backdrop-filter: var(--hk-popover-blur-mobile, none);
+  contain: layout style;
   /* The base .hk-popover-panel max-width clamp (calc(100vw - 16px), the
    * anchored panel's ratchet guard) must NOT leak into the sheet: with
    * the inline left:0 + right:0 docking the clamp over-constrains the

package/src/components/HkSelect.scss

@@ -304,11 +304,19 @@
    * 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. */
+   * 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. */
   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));
+    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));
   max-height: min(
     72vh,
     calc(

package/src/composables/useSizeMorph.test.ts

@@ -253,3 +253,177 @@ describe("useSizeMorph", () => {
     expect(h.frame.style.height).toBe("");
   });
 });
+
+// ── Clip reveal mode (--hk-sheet-morph: clip, mobile sheets) ─────────
+// Growth morphs reveal through paint-only clip-path instead of an
+// animated height: the pin lands instantly and the top edge sweeps up,
+// keeping the stretch look without per-frame layout on the fixed,
+// backdrop-carrying sheet layer (2026-09-15 mobile flicker report).
+
+/** happy-dom has no TransitionEvent constructor on some builds — the
+ * generic Event plus an assigned propertyName reads the same to the
+ * composable's listener. */
+function fireTransitionEnd(el: HTMLElement, propertyName: string): void {
+  // happy-dom's TransitionEvent (when present) ignores the init dict's
+  // propertyName — always build the generic event and assign the field.
+  const ev = new Event("transitionend");
+  Object.defineProperty(ev, "propertyName", { value: propertyName });
+  el.dispatchEvent(ev);
+}
+
+describe("useSizeMorph clip reveal", () => {
+  it("reveals growth through clip-path with an instant pin", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+    expect(h.frame.style.height).toBe("300px");
+
+    h.setNatural(360);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    // The pin landed at the new height with no height animation staged.
+    expect(h.frame.style.height).toBe("360px");
+    // The sweep runs: end-state clip + layer promotion in flight.
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    expect(h.frame.style.willChange).toBe("clip-path");
+    expect(h.frame.style.transition).toBe("");
+
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
+  it("starts the sweep from the old visual edge (delta inset)", () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    // The dance overwrites the inline clip synchronously (start → flush
+    // → end), so the START state is only observable at the forced-layout
+    // flush: wrap the frame's offsetHeight getter to record the clip
+    // each flush reads.
+    const reads: string[] = [];
+    const desc = Object.getOwnPropertyDescriptor(h.frame, "offsetHeight")!;
+    Object.defineProperty(h.frame, "offsetHeight", {
+      configurable: true,
+      get: () => {
+        reads.push(h.frame.style.clipPath);
+        return (desc.get as () => number)();
+      },
+    });
+
+    h.setNatural(420);
+    h.remeasure();
+    // Flush sequence: the released measure (clip ""), then the staged
+    // start state — the reveal hides exactly the 120px the sheet grew
+    // (420 − 300), putting the visible top edge back at the old line.
+    expect(reads).toEqual([
+      "",
+      "inset(120px 0 0 0 round 0px 0px 0px 0px)",
+    ]);
+    expect(h.frame.style.height).toBe("420px");
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+  });
+
+  it("keeps the height morph for shrink and sub-threshold growth", async () => {
+    const h = mountHarness(400);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    // Shrink: no clip state, the pin flips under the height transition.
+    h.setNatural(320);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("320px");
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+
+    // Sub-threshold growth (2px < REVEAL_MIN_PX): snaps, no reveal.
+    h.setNatural(322);
+    h.remeasure();
+    expect(h.frame.style.height).toBe("322px");
+    expect(h.frame.style.clipPath).toBe("");
+  });
+
+  it("never clips without the mode flag (desktop height morph intact)", async () => {
+    const h = mountHarness(300);
+    h.start();
+
+    h.setNatural(400);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("400px");
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
+  it("clears an in-flight reveal when a new dance starts", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(380);
+    h.remeasure();
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+
+    // A second growth lands before transitionend fired: the stale clip
+    // must come off inside the new dance, then the new reveal stages.
+    h.setNatural(450);
+    h.remeasure();
+    expect(h.frame.style.height).toBe("450px");
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    expect(h.frame.style.willChange).toBe("clip-path");
+  });
+
+  it("clears an interrupted reveal inside the next dance (no transitionend)", () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(380);
+    h.remeasure();
+    expect(h.frame.style.clipPath).not.toBe("");
+
+    // A SHRINK lands before the reveal's transitionend fired: unlike a
+    // follow-up growth (which restages its own clip), the height-morph
+    // branch writes no clip at all — the dance-start teardown is the
+    // only thing that returns the frame to CSS ownership (R1 mutation
+    // M1 evidence: without it the stale inset(0px) + will-change ride
+    // the shrink and linger at rest).
+    h.setNatural(310);
+    h.remeasure();
+    expect(h.frame.style.height).toBe("310px");
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
+  it("releases the clip state on stop so the leave animation owns the frame", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(380);
+    h.remeasure();
+    expect(h.frame.style.clipPath).not.toBe("");
+
+    h.stop();
+    expect(h.frame.style.height).toBe("");
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
+  it("ignores transitionend events for other properties", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(360);
+    h.remeasure();
+    fireTransitionEnd(h.frame, "height");
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    fireTransitionEnd(h.frame, "opacity");
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(h.frame.style.clipPath).toBe("");
+  });
+});

package/src/composables/useSizeMorph.ts

@@ -8,6 +8,11 @@ import { onBeforeUnmount, type Ref } from "vue";
 const CHROME_ALLOWANCE_FLOOR = 96;
 const CHROME_ALLOWANCE_SLACK = 32;
 
+/** Growth below this (px) snaps instead of revealing — under half a
+ * text row the sweep is imperceptible and not worth promoting a
+ * layer for. */
+const REVEAL_MIN_PX = 3;
+
 export interface SizeMorph {
   /** Arm the morph: observe the content and pin the frame's natural
    *  height on every change. Call once the surface finished its open
@@ -48,6 +53,17 @@ export interface SizeMorph {
  * pin chases the target with the CSS transition — bounded, one-shot
  * choreography, not an infinite per-frame animation.
  *
+ * Growth morphs on clip-mode surfaces (the mobile sheet docking, flagged
+ * `--hk-sheet-morph: clip` in CSS) reveal instead of animating height:
+ * the new pin lands instantly and the box's top edge sweeps up through
+ * `clip-path: inset()` — same duration/ease tokens as the height
+ * transition, same "content rides rigidly" grammar as the modal unveil,
+ * but paint/compositor-level: no per-frame layout and no per-frame
+ * backdrop-filter re-raster over the resizing fixed layer (the mobile
+ * patchy-flicker source, 2026-09-15 chest report). Shrinks and every
+ * height-mode surface keep the height transition — the rare direction
+ * is not worth the flex-compression look-ahead trade.
+ *
  * Reduced motion / the global animation switch stay honored: the frame's
  * transition-duration collapses to one frame under
  * `html[data-css-animations="0"]`, so the pin updates snap.
@@ -68,10 +84,70 @@ export function useSizeMorph(
    *  bodies that overflow at rest, plus subpixel slack. See the guard in
    *  remeasure(). */
   let chromeAllowance = CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
+  /** In-flight clip reveal (clip-mode growth morph): the frame whose
+   *  inline clip-path/will-change must come off again once the sweep
+   *  lands, plus the listener that does it. */
+  let revealEl: HTMLElement | null = null;
+  let revealEnd: ((ev: Event) => void) | null = null;
+
+  /** Tear down an in-flight clip reveal: drop the listener and return
+   *  the inline clip/will-change to CSS ownership. Safe to call when no
+   *  reveal is running (every dance start, stop, and unmount). */
+  function stopReveal(): void {
+    if (revealEl && revealEnd) {
+      revealEl.removeEventListener("transitionend", revealEnd);
+    }
+    if (revealEl) {
+      revealEl.style.clipPath = "";
+      revealEl.style.willChange = "";
+    }
+    revealEl = null;
+    revealEnd = null;
+  }
+
+  /** Clip-mode opt-in, owned by CSS: the modal's mobile media block
+   *  sets `--hk-sheet-morph: clip` inside its ≤767px query, and the
+   *  select sheet sets it on its class rule directly (that class only
+   *  renders in JS-gated sheet mode, so the breakpoint still owns the
+   *  behavior); a host can override per surface either way (an inline
+   *  custom property wins over the stylesheet's). */
+  function clipMode(f: HTMLElement): boolean {
+    const inline = f.style.getPropertyValue("--hk-sheet-morph").trim();
+    if (inline) return inline === "clip";
+    try {
+      return getComputedStyle(f).getPropertyValue("--hk-sheet-morph").trim() === "clip";
+    } catch {
+      return false;
+    }
+  }
+
+  /** The frame's corner radii for the reveal's `round` clause — the
+   *  moving clip edge keeps the sheet's own rounded corners instead of
+   *  shaving them straight for the sweep's duration. First token only
+   *  (horizontal radius); non-px values degrade to square. */
+  function cornerRadii(f: HTMLElement): string {
+    let cs: CSSStyleDeclaration | null = null;
+    try {
+      cs = getComputedStyle(f);
+    } catch {
+      cs = null;
+    }
+    const first = (v: string | undefined): string => {
+      const token = (v ?? "").trim().split(/\s+/)[0] ?? "";
+      return token.endsWith("px") ? token : "0px";
+    };
+    return [
+      first(cs?.borderTopLeftRadius),
+      first(cs?.borderTopRightRadius),
+      first(cs?.borderBottomRightRadius),
+      first(cs?.borderBottomLeftRadius),
+    ].join(" ");
+  }
 
   function release(): void {
     const f = frame.value;
     if (f) f.style.height = "";
+    stopReveal();
     pinned = 0;
   }
 
@@ -98,15 +174,23 @@ export function useSizeMorph(
     if (!f || !c) return;
     // 1. Disable transitions, release the pin and measure the frame's
     //    natural (CSS-capped) height in one layout flush.
-    // 2. Re-establish the OLD pin (still transition-disabled) and flush
-    //    it, so the style history is exactly "old height" when the live
-    //    CSS transition returns.
-    // 3. Flip to the NEW pin under the live transition — the computed
-    //    value changes old→new, so the height transition animates.
+    // 2. Clip-mode growth: pin the NEW height outright and stage the
+    //    clip start (still transition-disabled), so the reveal that
+    //    follows sweeps a fully-laid-out box — layout happens once,
+    //    here, never per frame.
+    //    Otherwise re-establish the OLD pin (still transition-disabled)
+    //    and flush it, so the style history is exactly "old height" when
+    //    the live CSS transition returns.
+    // 3. Flip to the new state under the live transition — a real
+    //    computed-value change, so the CSS transition animates.
     // No paint happens between the steps: they run in one task and the
     //    layout flushes are invisible to the screen.
     const inlineTransition = f.style.transition;
     f.style.transition = "none";
+    // A second content change mid-reveal restarts from the new delta
+    // (the settle debounce already collapses bursts; this makes it a
+    // hard guarantee that no stale clip survives into the new dance).
+    stopReveal();
     f.style.height = "";
     const natural = f.offsetHeight;
     if (natural <= 0) {
@@ -130,12 +214,51 @@ export function useSizeMorph(
       f.style.transition = inlineTransition;
       return;
     }
-    if (pinned > 0) f.style.height = `${pinned}px`;
-    // Flush the old-pin state before re-enabling the transition.
+    const next = Math.round(natural);
+    const growth = next - pinned;
+    // Clip reveal (see the composable doc): the pin lands instantly and
+    // the top edge sweeps up through paint-only clip-path, with the
+    // box's own corner radii riding the moving edge. The frame's
+    // stylesheet owns the clip-path transition (duration/ease tokens
+    // shared with the height transition), so reduced-motion and the
+    // global animation switch collapse it exactly like the height morph
+    // they already govern. Everything else — shrink, first pin,
+    // sub-threshold growth, height-mode surfaces — keeps the height
+    // morph below (desktop stays exactly as it was).
+    const reveal = pinned > 0 && growth >= REVEAL_MIN_PX && clipMode(f);
+    let radii = "";
+    if (reveal) {
+      radii = cornerRadii(f);
+      f.style.height = `${next}px`;
+      f.style.clipPath = `inset(${growth}px 0 0 0 round ${radii})`;
+    } else if (pinned > 0) {
+      f.style.height = `${pinned}px`;
+    }
+    // Flush the staged state (new pin + clip start, or the old pin)
+    // before re-enabling the transition, so the sweep starts from the
+    // old visual edge / the height transition starts from the old pin.
     void f.offsetHeight;
     f.style.transition = inlineTransition;
-    f.style.height = `${Math.round(natural)}px`;
-    pinned = Math.round(natural);
+    if (reveal) {
+      const onEnd = (ev: Event): void => {
+        // transitionend bubbles: a descendant animating its own
+        // clip-path must not end the frame's reveal early.
+        if (
+          ev.target === f &&
+          (ev as TransitionEvent).propertyName === "clip-path"
+        ) {
+          stopReveal();
+        }
+      };
+      f.addEventListener("transitionend", onEnd);
+      revealEl = f;
+      revealEnd = onEnd;
+      f.style.willChange = "clip-path";
+      f.style.clipPath = `inset(0px 0 0 0 round ${radii})`;
+    } else {
+      f.style.height = `${next}px`;
+    }
+    pinned = next;
     // Self-heal the allowance on every VALIDATED pin: chrome that grew
     // after calibration (an async footer, a header slot mounting
     // mid-open) updates the baseline instead of tripping the guard on
@@ -204,6 +327,7 @@ export function useSizeMorph(
     ro?.disconnect();
     if (settleTimer) clearTimeout(settleTimer);
     if (raf) cancelAnimationFrame(raf);
+    stopReveal();
   });
 
   return { start, stop, remeasure };

package/src/i18n/context.ts

@@ -54,6 +54,13 @@ localeCache.set("en", enFallback);
 // every language without knowing which locale is currently active.
 let mergedMessages: Record<string, Messages> = {};
 
+/** The app-selected hikari locale ("en" until setLocale runs). Date and
+ *  time formatters consume this so display follows the user's chosen
+ *  language instead of the browser's. */
+export function activeLocale(): string {
+  return state.locale;
+}
+
 export async function setLocale(locale: string): Promise<void> {
   if (!localeCache.has(locale)) {
     localeCache.set(locale, buildLocaleMessages(locale));

package/src/index.ts

@@ -268,6 +268,7 @@ export {
 export {
   useI18n,
   setLocale,
+  activeLocale,
   mergeMessages,
 } from "./i18n/context";
 
@@ -455,6 +456,8 @@ export {
   formatPriceUsd,
   formatRelativeTime,
   formatDateTime,
+  formatDate,
+  formatTime,
   formatMs,
   type RelativeTimeT,
 } from "./utils/format";

package/src/utils/format.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { formatRelativeTime, type RelativeTimeT } from "./format";
+import { formatDate, formatDateTime, formatRelativeTime, formatTime, type RelativeTimeT } from "./format";
 
 const MIN = 60_000;
 const HOUR = 3_600_000;
@@ -114,3 +114,47 @@ describe("formatRelativeTime", () => {
     expect(calls).toHaveLength(0);
   });
 });
+
+// ── Locale awareness (2026-09-15) ────────────────────────────────────
+// Every locale-sensitive formatter must follow the app-selected hikari
+// locale (setLocale), not the browser default: a zh-Hans app on an en
+// browser used to render dates as "9/13/2026" next to zh words.
+
+describe("locale-aware date formatting", () => {
+  it("formatDate composes the locale's full day label", async () => {
+    const { setLocale } = await import("../i18n/context");
+    const d = new Date(2026, 8, 13);
+    await setLocale("zh-Hans");
+    expect(formatDate(d, { month: "short", day: "numeric" })).toBe("9月13日");
+    await setLocale("en");
+    expect(formatDate(d, { month: "short", day: "numeric" })).toBe("Sep 13");
+    // Whole-date default: no opts = the locale's own date format.
+    expect(formatDate(d)).toContain("2026");
+  });
+
+  it("formatTime follows the locale's clock convention", async () => {
+    const { setLocale } = await import("../i18n/context");
+    const d = new Date(2026, 8, 13, 15, 24);
+    await setLocale("en");
+    expect(formatTime(d)).toMatch(/3:24/);
+    await setLocale("zh-Hans");
+    expect(formatTime(d)).toMatch(/15:24/);
+  });
+
+  it("formatDateTime renders through the app locale", async () => {
+    const { setLocale } = await import("../i18n/context");
+    await setLocale("ja");
+    const out = formatDateTime(new Date(2026, 8, 13, 15, 24));
+    expect(out).toMatch(/2026/);
+    // ja month rendering carries the 月 particle from the ja locale data.
+    expect(out).toMatch(/9月13日|9\/13/);
+    await setLocale("en");
+  });
+
+  it("formatDate/formatTime return empty for missing or invalid input", () => {
+    expect(formatDate("")).toBe("");
+    expect(formatDate("nope")).toBe("");
+    expect(formatTime(0)).toBe("");
+    expect(formatTime("junk")).toBe("");
+  });
+});

package/src/utils/format.ts

@@ -5,7 +5,14 @@
  * Consolidates the hand-rolled copies previously scattered across
  * arona (formatDate/formatUptime/formatNumber) and shittim-chest
  * (formatTokenCount/formatMediaTime).
- */
+ *
+ * Every locale-sensitive formatter resolves its locale through the
+ * hikari i18n state (activeLocale()), NOT the browser default: the app
+ * selects its language explicitly (setLocale on switch), and dates that
+ * follow the browser while every word around them follows the app read
+ * as mixed-language output (2026-09-15 user report: "9月 13" headings
+ * under a zh-Hans app on an en browser). */
+import { activeLocale } from "../i18n/context";
 
 /** "1234" -> "1.2k", "2500000" -> "2.5M". */
 export function formatTokenCount(n: number): string {
@@ -75,14 +82,15 @@ export function formatRelativeTime(
       t?.("common.time.weeksAgo", "{n} w ago", { n: weeks }) ?? `${weeks}w ago`
     );
   }
-  return d.toLocaleDateString();
+  return d.toLocaleDateString(activeLocale());
 }
 
 // Media timestamps ("m:ss") already live on the media-player kit — one
 // definition, re-exported so `../utils/format` is the single import site.
 export { formatMediaTime } from "../components/HkMediaControlBar";
 
-/** Absolute timestamp formatting with a shared locale-aware renderer. */
+/** Absolute timestamp formatting with a shared locale-aware renderer.
+ *  Follows the app-selected hikari locale (see activeLocale). */
 export function formatDateTime(
   input: string | number | Date,
   opts?: { dateStyle?: "short" | "medium" | "long"; timeStyle?: "short" | "medium" },
@@ -90,12 +98,39 @@ export function formatDateTime(
   if (!input) return "";
   const d = input instanceof Date ? input : new Date(input);
   if (isNaN(d.getTime())) return "";
-  return d.toLocaleString(undefined, {
+  return d.toLocaleString(activeLocale(), {
     dateStyle: opts?.dateStyle ?? "medium",
     timeStyle: opts?.timeStyle ?? "short",
   });
 }
 
+/** Date-only rendering (no time), following the app-selected hikari
+ *  locale. `opts` is the raw Intl.DateTimeFormatOptions passthrough —
+ *  omit it for the locale's whole-date default, or scope to a slice
+ *  (e.g. { month: "short", day: "numeric" } for day-group headings). */
+export function formatDate(
+  input: string | number | Date,
+  opts?: Intl.DateTimeFormatOptions,
+): string {
+  if (!input) return "";
+  const d = input instanceof Date ? input : new Date(input);
+  if (isNaN(d.getTime())) return "";
+  return d.toLocaleDateString(activeLocale(), opts);
+}
+
+/** Time-only rendering (no date), following the app-selected hikari
+ *  locale. `opts` is the raw Intl.DateTimeFormatOptions passthrough —
+ *  omit it for the locale's default (en "3:24 PM", zh "15:24"). */
+export function formatTime(
+  input: string | number | Date,
+  opts?: Intl.DateTimeFormatOptions,
+): string {
+  if (!input) return "";
+  const d = input instanceof Date ? input : new Date(input);
+  if (isNaN(d.getTime())) return "";
+  return d.toLocaleTimeString(activeLocale(), opts);
+}
+
 /** Milliseconds for latency/duration displays: sub-second keeps one
  *  decimal, >=1s switches to whole seconds (and beyond to minutes).
  *  Thousands-grouped for the rare large value. */