@celestia-island/hikari 0.55.314 → 0.55.316

package/package.json

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

package/src/animation/registerAnimations.test.ts

@@ -15,7 +15,10 @@ const srcDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 /** Recursively collect SCSS/TS/TSX sources under src/, skipping the
  * animation registrar's own directory (it is the thing under test, not
- * an animation-owning component). */
+ * an animation-owning component). Test files are skipped too: a keyframe
+ * NAME quoted inside a test (a negative assertion, a fixture) is not a
+ * declaration — counting it made the parity below agree with itself
+ * instead of with the sheets (2026-11-07 review, M7). */
 function collectSourceFiles(dir: string): string[] {
   const out: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -23,7 +26,7 @@ function collectSourceFiles(dir: string): string[] {
     if (entry.isDirectory()) {
       if (p === path.resolve(srcDir, "animation")) continue;
       out.push(...collectSourceFiles(p));
-    } else if (/\.(scss|ts|tsx)$/.test(entry.name)) {
+    } else if (/\.(scss|ts|tsx)$/.test(entry.name) && !/\.(test|spec)\.[tj]sx?$/.test(entry.name)) {
       out.push(p);
     }
   }
@@ -65,7 +68,6 @@ describe("registerAnimations", () => {
     expect(byName.get("hk-range-ribbon-pulse")?.infinite).toBe(true);
     expect(byName.get("s-auth-card-in")?.infinite).toBe(false);
     expect(byName.get("hk-rolling-number-up")?.infinite).toBe(false);
-    expect(byName.get("hk-modal-breadcrumb-in")?.infinite).toBe(false);
     expect(byName.get("hk-pwd-flash")?.infinite).toBe(false);
   });
 

package/src/animation/registerAnimations.ts

@@ -84,8 +84,6 @@ registerCssAnimation("hk-status-pill-pulse", { infinite: true });
 registerCssAnimation("hk-rolling-number-up");
 // components/HkSpinner.scss — spinner rotation (loops forever).
 registerCssAnimation("hk-spinner-rotate", { infinite: true });
-// components/HkModalBreadcrumb.scss — breadcrumb entrance (plays once).
-registerCssAnimation("hk-modal-breadcrumb-in");
 // components/HkToast.scss — toast spinner rotation (loops forever).
 registerCssAnimation("hk-toast-spin", { infinite: true });
 // components/HkSkeleton.scss — skeleton shimmer (loops forever).

package/src/components/HkListTransition.scss

@@ -151,6 +151,64 @@
   transition: transform var(--duration-fast, 0.15s) ease;
 }
 
+/* surface — the window choreography (HkModal's whole-window entrance,
+ * user direction 2026-11-07): a row arrives rising 10px while settling
+ * from 97% scale and fading in, and leaves by sinking back to that same
+ * pose. A compositor-only signature end to end — opacity + transform
+ * only, so the row never reflows per frame (the lesson the modal's own
+ * height-ride era taught the hard way). Siblings glide into the freed
+ * space with the same ease. Shares the window family's curves: the
+ * modal's ease-out (0.33, 1, 0.68, 1) arriving, its ease-in
+ * (0.45, 0, 0.55, 1) departing. */
+.hk-list-surface-enter-active {
+  transition:
+    opacity var(--duration-normal, 0.3s) cubic-bezier(0.33, 1, 0.68, 1),
+    transform var(--duration-normal, 0.3s) cubic-bezier(0.33, 1, 0.68, 1);
+}
+
+.hk-list-surface-leave-active {
+  transition:
+    opacity var(--duration-short, 0.15s) cubic-bezier(0.45, 0, 0.55, 1),
+    transform var(--duration-short, 0.15s) cubic-bezier(0.45, 0, 0.55, 1);
+  position: absolute;
+  pointer-events: none;
+}
+
+/* A dying ghost's interactive descendants re-enable hit-testing on
+   themselves (the modal breadcrumb's trigger/reveal buttons carry auto —
+   the strip itself is pointer-transparent), and inheritance does not
+   beat an explicit auto. The ghost must not take clicks while it sinks:
+   a tap opened a popover anchored to the fading element (2026-11-07
+   review). Specificity (0,1,1) outranks the (0,1,0) button faces.
+   Belt relationship: pinLeaving also sets `inert` on the ghost (blocks
+   clicks AND focus for every descendant where the pin ran); this rule is
+   the CSS belt that still dead-ends buttons when the pin skipped (no
+   layout — tests — or a host without captured rects). Future surface
+   consumers whose rows carry links/inputs, not just buttons: extend this
+   selector or rely on the inert. */
+.hk-list-surface-leave-active button {
+  pointer-events: none;
+}
+
+.hk-list-surface-enter-from,
+.hk-list-surface-leave-to {
+  opacity: 0;
+  transform: translateY(10px) scale(0.97);
+}
+
+.hk-list-surface-move {
+  /* opacity rides along on purpose: if a multi-row batch ever classifies
+     a leaving ghost as moved (its FLIP delta measured before the
+     correction pass lands), the stamped move transition would REPLACE
+     the leave's transition shorthand — a transform-only move cancels the
+     fade mid-flight and snaps the ghost invisible. Carrying the leave's
+     own opacity curve keeps the fade alive under that stamp; for true
+     moved rows the property goes 1→1 and is inert. */
+  transition:
+    opacity var(--duration-short, 0.15s) cubic-bezier(0.45, 0, 0.55, 1),
+    transform var(--duration-normal, 0.3s) cubic-bezier(0.33, 1, 0.68, 1);
+}
+
 .hk-list-none-enter-active,
 .hk-list-none-leave-active,
 .hk-list-none-move {
@@ -171,11 +229,14 @@
   .hk-list-grow-leave-active,
   .hk-list-reveal-enter-active,
   .hk-list-reveal-leave-active,
+  .hk-list-surface-enter-active,
+  .hk-list-surface-leave-active,
   .hk-list-pop-move,
   .hk-list-slide-move,
   .hk-list-fade-move,
   .hk-list-grow-move,
-  .hk-list-reveal-move {
+  .hk-list-reveal-move,
+  .hk-list-surface-move {
     transition: none !important;
   }
 }

package/src/components/HkListTransition.tsx

@@ -1,14 +1,15 @@
-import { defineComponent, onBeforeUpdate, ref, TransitionGroup, type PropType } from "vue";
+import { defineComponent, onBeforeUpdate, queuePostFlushCb, ref, TransitionGroup, type PropType } from "vue";
 
 import { clearLeaveGeometry, pinLeaveGeometry, type LeaveBoxSnapshot } from "../utils/dom";
 import { useReportedTransition } from "../composables/useReportedTransition";
+import { ancestorZoom } from "../runtime/cssZoom";
 
 import "./HkListTransition.scss";
 
-type ListAnimVariant = "pop" | "slide" | "fade" | "grow" | "reveal";
+type ListAnimVariant = "pop" | "slide" | "fade" | "grow" | "reveal" | "surface";
 
-/** Enter/leave report window: the slowest variant (pop/slide/fade) runs
- *  --hi-duration-normal, the fast ones (grow/reveal) run their own 150ms
+/** Enter/leave report window: the slowest variant (pop/slide/fade/surface)
+ *  runs --hi-duration-normal, the fast ones (grow/reveal) run their own 150ms
  *  plus a 150ms stagger delay — both finish inside this budget. */
 const REPORT_MS = 320;
 
@@ -27,6 +28,13 @@ const REPORT_MS = 320;
  *     their natural height (interpolate-size + calc-size), leaving rows
  *     shrink back — the container height itself animates, so wrapping
  *     groups and stacked cards both get a real space transition.
+ *   - `surface` — the window choreography (HkModal's whole-window
+ *     entrance, user direction 2026-11-07): a row rises 10px while
+ *     settling from 97% scale and fading in, and leaves by sinking back
+ *     to the same pose; siblings glide into the freed space (FLIP).
+ *     The motion signature of the surface family, so a list whose rows
+ *     ARE windows (HkModalBreadcrumb's stack) can animate them the way
+ *     the windows themselves arrive.
  *
  * Animation-context participation: every enter/leave batch is REPORTED to
  * the runtime animation bus (`reportTransition`), so JS choreography that
@@ -69,7 +77,7 @@ export default defineComponent({
     // the geometry pin; `reveal` animates the row's own height in place
     // and `none` never leaves the flow, so a pin would freeze the very
     // property they animate.
-    const ABSOLUTE_VARIANTS: ReadonlySet<string> = new Set(["pop", "slide", "fade", "grow"]);
+    const ABSOLUTE_VARIANTS: ReadonlySet<string> = new Set(["pop", "slide", "fade", "grow", "surface"]);
 
     // Pre-patch geometry of every row, refreshed on each update (the DOM
     // is still the pre-patch tree at onBeforeUpdate — same pattern as
@@ -82,6 +90,18 @@ export default defineComponent({
     // position:relative (the full-width leave flash).
     const hostRef = ref<{ $el?: Element } | null>(null);
     const prePatchBoxes = new WeakMap<Element, LeaveBoxSnapshot>();
+    /** Pre-patch VIEWPORT position of every row (gBCR). The offset boxes
+     *  above are relative to the offsetParent's padding box — for a host
+     *  whose padding box MOVES when its content shrinks (a centered
+     *  shrink-to-fit host) that origin shift is exactly the ghost-drift
+     *  the compensation below cancels, so the viewport truth is what the
+     *  compensation must restore. */
+    const prePatchRects = new WeakMap<Element, { x: number; y: number }>();
+    // Known limit: the rects include in-flight enter/move transforms — a
+    // row removed mid-entrance freezes its transient pose into the
+    // one-shot margin. Cosmetic (dying ghost, ≤300ms race window,
+    // ≤10px); excluded-transform capture would need offset math per
+    // host, not worth it for a generic primitive.
     onBeforeUpdate(() => {
       // Fragment hosts (tag="") have a comment anchor as $el — no
       // element children to measure there.
@@ -95,20 +115,118 @@ export default defineComponent({
           width: e.offsetWidth,
           height: e.offsetHeight,
         });
+        const r = e.getBoundingClientRect();
+        prePatchRects.set(e, { x: r.left, y: r.top });
       }
     });
 
     const usesAbsoluteLeave = () =>
       !props.disabled && ABSOLUTE_VARIANTS.has(props.variant);
 
+    /** Ghosts of the current batch (inline-absolute, awaiting removal).
+     *  Iterated by the post-flush correction below; pruned when a leave
+     *  aborts or an element leaves the DOM. */
+    const pinnedGhosts = new Set<HTMLElement>();
+    let ghostCorrectionQueued = false;
+
+    /** The centered-host compensation can only see the refits that have
+     *  ALREADY happened when a ghost is pinned — in a MULTI-ROW batch
+     *  (a fold evicting several crumbs in one patch) the later lifts
+     *  re-shrink a centered host further, dragging every earlier ghost
+     *  by Σ_w_later/2 before anything paints (2026-11-07 review, round
+     *  4). One post-flush pass fixes the whole batch exactly: it runs
+     *  after the patch (all lifts done, final refit reached) but — being
+     *  enqueued mid-patch, inside the leave hook, while TransitionGroup
+     *  only enqueues its own updated hook once its update COMPLETES —
+     *  BEFORE the FLIP pass measures positions. Exact ghosts mean
+     *  dx=dy=0, so no ghost is ever mis-classified as moved (a move
+     *  stamp would swap the leave's opacity transition for the move's
+     *  transform-only one and snap the fade). Idempotent: the write
+     *  derives the delta from the live rect including the current
+     *  margin. */
+    function scheduleGhostCorrection(): void {
+      if (ghostCorrectionQueued) return;
+      ghostCorrectionQueued = true;
+      queuePostFlushCb(() => {
+        ghostCorrectionQueued = false;
+        for (const ghost of pinnedGhosts) {
+          if (!ghost.isConnected) {
+            pinnedGhosts.delete(ghost);
+            continue;
+          }
+          const pre = prePatchRects.get(ghost);
+          if (pre == null) continue;
+          // Same visual→local conversion as the first-phase compensation:
+          // gBCR deltas are zoom-scaled at paint, margins are local.
+          const z = ancestorZoom(ghost);
+          const now = ghost.getBoundingClientRect();
+          const dx = (pre.x - now.left) / z;
+          const dy = (pre.y - now.top) / z;
+          if (dx === 0 && dy === 0) continue;
+          const currentMx = Number.parseFloat(ghost.style.marginLeft || "0") || 0;
+          const currentMy = Number.parseFloat(ghost.style.marginTop || "0") || 0;
+          ghost.style.marginLeft = `${currentMx + dx}px`;
+          ghost.style.marginTop = `${currentMy + dy}px`;
+        }
+      });
+    }
+
     function pinLeaving(el: Element) {
       if (!usesAbsoluteLeave()) return;
+      const node = el as HTMLElement;
       pinLeaveGeometry(el, { anchorX: "left", box: prePatchBoxes.get(el) });
+      // ── Centered-host compensation (first phase) ───────────────────
+      // An absolute ghost is positioned against the host's PADDING box —
+      // and a shrink-to-fit host REFITS the instant the ghost leaves the
+      // flow. A centered host (the modal breadcrumb's nav: fixed +
+      // left:50% + translate(-50%,-50%)) then moves its padding origin
+      // right by half the freed width, and the pinned `left` lands the
+      // ghost ΔW/2 away from where the user last saw it (2026-11-07
+      // review, real-Chrome repro: 74px jump on a single removal). Cancel
+      // the ALREADY-HAPPENED refits while nobody has painted: lift the
+      // ghost out of flow inline — in the SAME patch pass as the pin
+      // (Vue adds the leave-active class synchronously here too; its
+      // nextFrame only gates the leave-from → leave-to swap) — force the
+      // refit with one layout read, and write the visual delta back as a
+      // ONE-SHOT margin. Refits that happen AFTER this hook (later ghosts
+      // of the same batch) are corrected by scheduleGhostCorrection's
+      // post-flush pass above — the pair lands every ghost of any batch
+      // on its pre-patch spot before the first leave frame paints, with
+      // the ghost's motion itself opacity + transform only (compositor
+      // contract intact; margins are static one-time writes).
+      const pre = prePatchRects.get(el);
+      if (pre == null || node.offsetParent == null) return;
+      pinnedGhosts.add(node);
+      // Dying ghosts take no clicks AND no Tab focus (pointer-events does
+      // not stop focus; a Tab landing mid-leave would focus a doomed
+      // button and drop to <body> when it unmounts).
+      node.inert = true;
+      node.style.position = "absolute";
+      // gBCR deltas are VISUAL px (scaled by any ancestor zoom, e.g.
+      // chest's manual DPI scale); margins are LOCAL px painted ×z —
+      // convert through the zoom read at the ghost, or the correction
+      // over-shoots by (z−1)·delta on zoomed hosts.
+      const z = ancestorZoom(node);
+      const now = node.getBoundingClientRect();
+      const dx = (pre.x - now.left) / z;
+      const dy = (pre.y - now.top) / z;
+      if (dx !== 0) node.style.marginLeft = `${dx}px`;
+      if (dy !== 0) node.style.marginTop = `${dy}px`;
+      scheduleGhostCorrection();
     }
 
     function unpinLeaving(el: Element) {
       if (!usesAbsoluteLeave()) return;
       clearLeaveGeometry(el);
+      // The compensation writes of pinLeaving — an aborted leave returns
+      // the row to the flow, where a stale position/margin would freeze
+      // it off its slot.
+      const node = el as HTMLElement;
+      pinnedGhosts.delete(node);
+      node.inert = false;
+      node.style.position = "";
+      node.style.marginLeft = "";
+      node.style.marginTop = "";
     }
 
     return () => {

package/src/components/HkModal.leavepin.test.tsx

@@ -122,7 +122,7 @@ describe("HkModal leave-window height pin", () => {
   it("keeps the morph pin through the whole leave and releases at finalize", async () => {
     vi.useFakeTimers();
     freezeRaf();
-      stubPhoneViewport();
+    stubPhoneViewport();
     stubDurations();
     stubLayout(500);
     try {
@@ -160,7 +160,7 @@ describe("HkModal leave-window height pin", () => {
   it("leaves the frame unpinned through the enter; the open edge pins the settled height", async () => {
     vi.useFakeTimers();
     freezeRaf();
-      stubPhoneViewport();
+    stubPhoneViewport();
     stubDurations();
     stubLayout(400);
     try {
@@ -197,7 +197,7 @@ describe("HkModal leave-window height pin", () => {
   it("drops the held pin at a reopen-interrupt edge; the open edge re-pins", async () => {
     vi.useFakeTimers();
     freezeRaf();
-      stubPhoneViewport();
+    stubPhoneViewport();
     stubDurations();
     stubLayout(500);
     try {

package/src/components/HkModal.open-close-scale.test.ts

@@ -378,6 +378,24 @@ describe("HkModal desktop open/close contract (compiled cascade, user direction
     }
   });
 
+  it("keeps the desktop rest transition to the height leg only", () => {
+    // The size morph's height leg is the ONLY property the desktop rest
+    // state ever animates. The clip-path reveal morph belongs to the
+    // ≤767px sheet block (which replaces the list wholesale), and
+    // nothing changes the frame's max-height after mount (the 70vh cap
+    // is the body's, a different element) — retired legs smuggled back
+    // into the shorthand must fail this pin (2026-11-07 residue sweep).
+    const rest = frameWith();
+    expect(winner(rest, "transition", DESKTOP)).toBe(
+      "height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1))",
+    );
+    // The phone sheet keeps its own clip-path-only morph list.
+    const mobileRest = frameWith();
+    expect(winner(mobileRest, "transition", MOBILE)).toBe(
+      "clip-path var(--hk-modal-morph-duration, 0.3s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1))",
+    );
+  });
+
   it("fades the frame and rides its height on one shared token pair per direction", () => {
     // Pinned WHOLE (winner() normalizes whitespace), not by prefix: a
     // fourth time value (transition-delay) or an extra smuggled segment

package/src/components/HkModal.scss

@@ -74,14 +74,13 @@
   // (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)),
-    clip-path var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
+  // Height is the only leg the desktop rest state ever animates: the
+  // clip-path reveal morph belongs to the ≤767px sheet block (which
+  // replaces this list wholesale), and on desktop nothing — hikari or
+  // host — changes the frame's max-height after mount (the 70vh cap is
+  // the body's, a different element; the phone caps move by design and
+  // deliberately carry no leg — see the IME cap-chase note below).
+  transition: height 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(255,255,255,0.95)));
   @include 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)));
@@ -483,7 +482,7 @@
     //   direction change. Growth keeps its animated reveal via the
     //   clip-path sweep (the only transition left on phones).
     //
-    // Desktop keeps the full base list (height + max-height + clip-path).
+    // Desktop keeps the base list (height only — the size morph's leg).
     // 0.3s = the stepflow crossfade's family standard (2026-09-21 user
     // spec, round 7): the clip sweep, the riding body and the fade must
     // land together. Keyboard-driven height changes never animate

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

@@ -114,16 +114,21 @@ describe("HkModal mobile sheet spacing contract", () => {
       expect(tr).not.toMatch(/\bmax-height\b/);
     });
 
-    it("keeps the desktop frame transition list intact (base rule)", () => {
-      // The guard is phone-only by design: the base rule outside the
-      // media block keeps height+max-height+clip-path animated.
+    it("keeps the desktop frame transition to the height leg only (base rule)", () => {
+      // The guard is phone-only by design: outside the media block the
+      // base rule animates height only — the size morph's leg. The
+      // clip-path reveal lives in the ≤767px block (which replaces the
+      // list wholesale), and nothing changes the frame's max-height
+      // after mount (the 70vh cap is the body's, a different element):
+      // the 2026-11-07 residue sweep retired the never-animated
+      // max-height/clip-path legs, and this pin keeps them retired.
       const base = src.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
       expect(base.length, "base .hk-modal-content rule extracted").toBeGreaterThan(0);
       const tr = base.match(/transition:\s*([^;]+);/)?.[1] ?? "";
       expect(tr.length, "base transition declaration present").toBeGreaterThan(0);
       expect(tr).toMatch(/\bheight\b/);
-      expect(tr).toMatch(/\bmax-height\b/);
-      expect(tr).toMatch(/\bclip-path\b/);
+      expect(tr).not.toMatch(/\bmax-height\b/);
+      expect(tr).not.toMatch(/\bclip-path\b/);
     });
 
     it("lifts the 70vh body cap on phones so the footer sits on the bottom edge", () => {

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

@@ -11,9 +11,11 @@
  *   - 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
+ *     the ≤767px sheet block replaces the frame's transition list
+ *     wholesale and carries the clip-path transition retimed to the
+ *     stepflow family standard, so the stretch look and its
+ *     reduced-motion / data-css-animations governance are intact (the
+ *     desktop base list animates the size morph's height leg only)
  *   - 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-
@@ -54,12 +56,17 @@ describe("sheet family morph-performance contract", () => {
     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.
+  it("keeps the clip sweep on the sheet block, out of the desktop base list", () => {
+    // 2026-11-07 residue sweep: the desktop rest state never sweeps a
+    // clip-path (no clip-mode surface exists ≥768px), so the base list
+    // carries the size morph's height leg only. The reveal grammar lives
+    // in the ≤767px block, which replaces the frame's transition list
+    // wholesale and retimes the sweep to the stepflow family standard
+    // (pinned by the next test).
     const frame = modal.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
+    expect(frame).not.toMatch(/^[ \t]*clip-path var\(--duration-fast/m);
     expect(frame).toMatch(
-      /^[ \t]*clip-path var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
+      /^[ \t]*transition: height var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
     );
   });