@celestia-island/hikari 0.55.313 → 0.55.315

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.313",
+  "version": "0.55.315",
   "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) && !/\btest\.[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).
@@ -143,3 +141,7 @@ registerCssAnimation("hk-screen-identify-in");
 // brushed window still reads as live. Reduced motion keeps the dashed
 // pending look and drops the loop (house pattern, see HkSkeleton).
 registerCssAnimation("hk-range-ribbon-pulse", { infinite: true });
+// HkBadge's presence pulse (opacity-only, loops forever): the `pulse`
+// prop's dot breathes while its state is in-flight — a settled dot sits
+// static. Reduced motion drops the loop (house pattern, see HkSkeleton).
+registerCssAnimation("hk-badge-dot-pulse", { infinite: true });

package/src/components/HkBadge.scss

@@ -64,6 +64,29 @@
   flex-shrink: 0;
 }
 
+/* Presence pulse (data-pulse, dot required): an in-flight / live state
+   breathes instead of sitting static. Opacity-only so the pill's layout
+   box never moves; consumers wanting a glow layer their own shadow. */
+@keyframes hk-badge-dot-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.4;
+  }
+}
+
+.hk-badge[data-pulse] [data-el="dot"] {
+  animation: hk-badge-dot-pulse 1.6s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hk-badge[data-pulse] [data-el="dot"] {
+    animation: none;
+  }
+}
+
 /* dot-only: strip the pill padding/border/background so it's just the
    indicator dot, not a dot wrapped in a bordered pill. */
 .hk-badge[data-dot-only] {

package/src/components/HkBadge.test.tsx

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+import { readFileSync } from "node:fs";
+import { compile } from "sass";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import HkBadge from "./HkBadge";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(renderNode: () => ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: renderNode });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+// Vitest stubs CSS, so the runtime suite can never catch a lost rule —
+// the pulse animation contract is additionally pinned by the compiled
+// stylesheet guard at the bottom of this file (HkCornerBadge pattern).
+describe("HkBadge pulse", () => {
+  it("renders the dot and data-pulse only when both dot and pulse are set", () => {
+    const container = mount(() => h(HkBadge, { dot: true, pulse: true }, () => "Creating"));
+    expect(container.querySelector(".hk-badge [data-el='dot']")).toBeTruthy();
+    expect(container.querySelector(".hk-badge[data-pulse]")).toBeTruthy();
+  });
+
+  it("never sets data-pulse without a dot — a pulsing pill with no dot is meaningless", () => {
+    const container = mount(() => h(HkBadge, { pulse: true }, () => "Creating"));
+    expect(container.querySelector(".hk-badge")).toBeTruthy();
+    expect(container.querySelector("[data-pulse]")).toBeNull();
+    expect(container.querySelector("[data-el='dot']")).toBeNull();
+  });
+
+  it("keeps the static dot the default — pulse is opt-in per call site", () => {
+    const container = mount(() => h(HkBadge, { dot: true }, () => "Idle"));
+    expect(container.querySelector(".hk-badge [data-el='dot']")).toBeTruthy();
+    expect(container.querySelector("[data-pulse]")).toBeNull();
+  });
+});
+
+describe("HkBadge pulse stylesheet contract", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const css = compile(resolve(here, "HkBadge.scss"), { style: "expanded" }).css;
+
+  it("drives the pulse through the data-pulse selector on the dot only", () => {
+    // Sass compiles quoted attribute selectors unquoted ([data-el=dot]).
+    expect(css).toContain(".hk-badge[data-pulse] [data-el=dot]");
+    // The animation must never ride the pill itself — layout stays frozen.
+    expect(css.match(/\.hk-badge\s*\{[^}]*animation/)).toBeNull();
+  });
+
+  it("names the keyframes and runs them infinitely", () => {
+    expect(css).toContain("@keyframes hk-badge-dot-pulse");
+    expect(/\.hk-badge\[data-pulse\] \[data-el=dot\]\s*\{[^}]*animation:\s*hk-badge-dot-pulse[^;]*infinite/.test(css)).toBe(true);
+  });
+
+  it("switches the pulse off under prefers-reduced-motion", () => {
+    expect(css).toMatch(/@media \(prefers-reduced-motion: reduce\)\s*\{[^@]*\.hk-badge\[data-pulse\] \[data-el=dot\]\s*\{[^}]*animation:\s*none/);
+  });
+});

package/src/components/HkBadge.tsx

@@ -15,6 +15,9 @@ export default defineComponent({
   props: {
     variant: { type: String as PropType<BadgeVariant>, default: "default" },
     dot: { type: Boolean, default: false },
+    /** Animate the dot with a presence pulse (in-flight / live state).
+     * Meaningful only with `dot`; honors prefers-reduced-motion. */
+    pulse: { type: Boolean, default: false },
     size: { type: String as PropType<"sm" | "md">, default: "md" },
     mono: { type: Boolean, default: false },
     uppercase: { type: Boolean, default: false },
@@ -38,6 +41,7 @@ export default defineComponent({
         data-size={props.size}
         data-pill={props.pill ? undefined : "false"}
         data-mono={props.mono ? "" : undefined}
+        data-pulse={props.pulse && props.dot ? "" : undefined}
         data-uppercase={props.uppercase ? "" : undefined}
         data-dot-only={(props.dot && !slots.default) || undefined}
         style={Object.keys(style.value).length ? style.value : undefined}

package/src/components/HkErrorLanding.scss

@@ -6,6 +6,7 @@
 // host themes (dark mode etc.) when the vars exist.
 
 @use "../styles/polyfill" as *;
+@use "./hikari-vars" as vars;
 
 .hk-error-landing {
   --hel-background: var(--color-background, 246 247 249);
@@ -34,7 +35,7 @@
   padding: var(--space-20, 1.25rem);
   background: rgb(var(--hel-background));
   color: rgb(var(--hel-text));
-  font-family: var(--font-sans, system-ui, -apple-system, "Segoe UI", sans-serif);
+  font-family: var(--font-sans, vars.$hikari-font-family-sans);
 }
 
 .hk-error-landing__card {

package/src/components/HkListTransition.scss

@@ -151,6 +151,58 @@
   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. */
+.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 +223,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 () => {