@celestia-island/hikari 0.55.314 → 0.55.315

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.314",
+  "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).

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 () => {

package/src/components/HkModalBreadcrumb.motion.contract.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Compiled-CSS contract for the strip's MOTION — run against the COMPILED
+ * stylesheets, not the source text (the behavioural suite runs in
+ * happy-dom, which resolves no theme custom properties, so a wrong
+ * literal there paints green and breaks only in a real theme).
+ *
+ * User direction 2026-11-07: window crumbs must animate the way the
+ * windows themselves do (the B3 whole-window choreography — rise 10px,
+ * settle from 97% scale, fade; leave is the true reverse). Three layers
+ * carry that signature and this file pins all three:
+ *
+ *   1. the strip's own surface entrance/exit  (hk-modal-breadcrumb-enter/leave-*)
+ *   2. each crumb's enter/leave via the list container (hk-list-surface-*)
+ *   3. the shared pose constants with HkModal itself
+ *
+ * Compositor-only is the law here (the modal height-ride lesson): every
+ * animated rule below touches ONLY opacity/transform. A layout property
+ * (top/left/width/height) in any of them re-rasters the backdrop-filtered
+ * strip per frame — the exact jank class that retired the height ride.
+ */
+import { describe, expect, it } from "vitest";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "sass";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const compiled = (sheet: string): string =>
+  compile(join(here, sheet), {
+    loadPaths: [here, join(here, "..", "styles")],
+    style: "expanded",
+  }).css;
+
+const breadcrumb = compiled("HkModalBreadcrumb.scss");
+const list = compiled("HkListTransition.scss");
+const modal = compiled("HkModal.scss");
+
+/** Brace-matched body of the first top-level block whose head starts with
+ *  the given prefix (`@media …` or a selector). */
+function topBlock(cssText: string, headPrefix: string): string {
+  const start = cssText.indexOf(headPrefix);
+  if (start === -1) return "";
+  const open = cssText.indexOf("{", start);
+  let depth = 0;
+  for (let i = open; i < cssText.length; i++) {
+    if (cssText[i] === "{") depth += 1;
+    else if (cssText[i] === "}") {
+      depth -= 1;
+      if (depth === 0) return cssText.slice(open + 1, i);
+    }
+  }
+  return "";
+}
+
+/** All `selector { body }` frames anywhere inside a block (one nesting
+ *  level deep is enough for these sheets). A selector part that still
+ *  carries the preceding comment's tail (ellipsis + comment close before
+ *  the selector) is trimmed to the bare selector — sass expanded output
+ *  keeps comments, and their commas would otherwise glue the comment
+ *  onto the selector string. */
+function frames(block: string): { selectors: string[]; body: string }[] {
+  const out: { selectors: string[]; body: string }[] = [];
+  const re = /([^{}]+)\{([^{}]*)\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(block))) {
+    out.push({
+      selectors: m[1]
+        .split(",")
+        .map((s) => {
+          let t = s;
+          const comment = t.lastIndexOf("*/");
+          if (comment !== -1) t = t.slice(comment + 2);
+          const semi = t.lastIndexOf(";");
+          if (semi !== -1) t = t.slice(semi + 1);
+          return t.trim();
+        })
+        .filter((s) => s.startsWith(".") || s.startsWith("[") || s.includes("@")),
+      body: m[2].trim(),
+    });
+  }
+  return out;
+}
+
+/** The rule whose selector LIST contains exactly the given selector. */
+function rule(sheet: string, selector: string): string {
+  const all = frames(sheet);
+  const hit = all.find((f) => f.selectors.includes(selector));
+  expect(hit, `rule ${selector} must exist`).toBeTruthy();
+  return hit!.body;
+}
+
+/** Rule scoped to the body of a media block. */
+function ruleIn(block: string, selector: string): string {
+  const hit = frames(block).find((f) => f.selectors.includes(selector));
+  expect(hit, `rule ${selector} must exist in the block`).toBeTruthy();
+  return hit!.body;
+}
+
+const reducedBreadcrumb = topBlock(breadcrumb, "@media (prefers-reduced-motion: reduce)");
+const reducedList = topBlock(list, "@media (prefers-reduced-motion: reduce)");
+
+const MODAL_POSE = "translateY(10px) scale(0.97)";
+const EASE_OUT = "cubic-bezier(0.33, 1, 0.68, 1)";
+const EASE_IN = "cubic-bezier(0.45, 0, 0.55, 1)";
+
+describe("strip surface enter/leave (window choreography)", () => {
+  it("rides opacity + transform only — never a layout property", () => {
+    for (const sel of [
+      ".hk-modal-breadcrumb-enter-active",
+      ".hk-modal-breadcrumb-leave-active",
+      ".hk-modal-breadcrumb-enter-from",
+      ".hk-modal-breadcrumb-leave-to",
+    ]) {
+      const block = rule(breadcrumb, sel);
+      expect(block).not.toMatch(/\b(top|left|width|height|margin|padding)\s*:/);
+    }
+  });
+
+  it("arrives with the window's rise + settle + fade", () => {
+    const enter = rule(breadcrumb, ".hk-modal-breadcrumb-enter-active");
+    expect(enter).toContain(`opacity var(--duration-normal, 0.3s) ${EASE_OUT}`);
+    expect(enter).toContain(`transform var(--duration-normal, 0.3s) ${EASE_OUT}`);
+    const from = rule(breadcrumb, ".hk-modal-breadcrumb-enter-from");
+    expect(from).toContain("opacity: 0");
+    expect(from).toContain("translate(-50%, calc(-50% - 10px)) scale(0.97)");
+    const to = rule(breadcrumb, ".hk-modal-breadcrumb-enter-to");
+    expect(to).toContain("opacity: 1");
+    expect(to).toContain("translate(-50%, -50%) scale(1)");
+  });
+
+  it("leaves as the true reverse, quicker than the windows it names", () => {
+    const leave = rule(breadcrumb, ".hk-modal-breadcrumb-leave-active");
+    expect(leave).toContain(`opacity var(--duration-short, 0.15s) ${EASE_IN}`);
+    expect(leave).toContain(`transform var(--duration-short, 0.15s) ${EASE_IN}`);
+    const to = rule(breadcrumb, ".hk-modal-breadcrumb-leave-to");
+    expect(to).toContain("opacity: 0");
+    expect(to).toContain("translate(-50%, calc(-50% - 10px)) scale(0.97)");
+  });
+
+  it("keeps the centering prefix in every animated state", () => {
+    // The resting rule's transform is byte-identical to the enter-to /
+    // leave-from state — a re-seated mid-flight frame would drift the
+    // strip off its measured `top` line (the modal frame keeps the same
+    // contract for its dragged-shift vars).
+    const resting = rule(breadcrumb, ".hk-modal-breadcrumb")
+      .match(/transform:\s*([^;]+);/)?.[1]
+      ?.trim();
+    expect(resting).toBe("translate(-50%, -50%)");
+    expect(rule(breadcrumb, ".hk-modal-breadcrumb-enter-to")).toContain(
+      `transform: ${resting} scale(1)`,
+    );
+  });
+
+  it("has no keyframe animation on the base class (no double entrance)", () => {
+    // The Transition enter classes replaced the old mount keyframe; a
+    // reintroduced base `animation:` would stack on top of them. A regex
+    // literal on purpose: a plain string would read as a `@keyframes`
+    // DECLARATION to naive scanners of the source tree (see
+    // registerAnimations.test.ts's parity) — the `\s` escape keeps this
+    // assertion from being mistaken for one.
+    expect(rule(breadcrumb, ".hk-modal-breadcrumb")).not.toMatch(/animation\s*:/);
+    expect(breadcrumb).not.toMatch(/@keyframes\s+hk-modal-breadcrumb-in/);
+  });
+
+  it("drops the motion under prefers-reduced-motion", () => {
+    expect(reducedBreadcrumb).toContain(".hk-modal-breadcrumb-enter-active");
+    expect(reducedBreadcrumb).toContain(".hk-modal-breadcrumb-leave-active");
+    expect(ruleIn(reducedBreadcrumb, ".hk-modal-breadcrumb-enter-active")).toContain(
+      "transition: none",
+    );
+    expect(ruleIn(reducedBreadcrumb, ".hk-modal-breadcrumb-leave-active")).toContain(
+      "transition: none",
+    );
+  });
+});
+
+describe("crumb list surface variant (HkListTransition)", () => {
+  it("animates each crumb with the same window pose", () => {
+    const from = rule(list, ".hk-list-surface-enter-from");
+    expect(from).toContain("opacity: 0");
+    expect(from).toContain(`transform: ${MODAL_POSE}`);
+    const leaveTo = rule(list, ".hk-list-surface-leave-to");
+    expect(leaveTo).toContain("opacity: 0");
+    expect(leaveTo).toContain(`transform: ${MODAL_POSE}`);
+  });
+
+  it("uses the window family's curves at crumb pace", () => {
+    const enter = rule(list, ".hk-list-surface-enter-active");
+    expect(enter).toContain(`opacity var(--duration-normal, 0.3s) ${EASE_OUT}`);
+    expect(enter).toContain(`transform var(--duration-normal, 0.3s) ${EASE_OUT}`);
+    const leave = rule(list, ".hk-list-surface-leave-active");
+    expect(leave).toContain(`opacity var(--duration-short, 0.15s) ${EASE_IN}`);
+    expect(leave).toContain(`transform var(--duration-short, 0.15s) ${EASE_IN}`);
+    // The leaving crumb is lifted out of flow so the space collapses and
+    // the siblings glide (FLIP move) into it.
+    expect(leave).toContain("position: absolute");
+    // A sinking ghost takes no clicks — neither the row nor the buttons
+    // inside it, whose own pointer-events:auto would otherwise beat
+    // inheritance (the strip re-enables only its buttons).
+    expect(leave).toContain("pointer-events: none");
+    expect(rule(list, ".hk-list-surface-leave-active button")).toContain(
+      "pointer-events: none",
+    );
+    const move = rule(list, ".hk-list-surface-move");
+    expect(move).toContain("transform");
+    expect(move).toContain(EASE_OUT);
+    // Insurance: if a mis-classified ghost is ever stamped with the move
+    // class, its shorthand must not REPLACE the leave's opacity
+    // transition (a transform-only move would cancel the fade).
+    expect(move).toContain("opacity");
+    expect(move).toContain(EASE_IN);
+  });
+
+  it("shares the pose constants with HkModal itself", () => {
+    // Single source of truth by equality: retune the window's pose in the
+    // modal sheet and this fails until the crumbs follow (or the reviewer
+    // rules the divergence in — deliberately loud either way).
+    expect(rule(modal, ".hk-modal-content-enter-from")).toContain(MODAL_POSE);
+    expect(list).toContain(MODAL_POSE);
+    expect(list).toContain(EASE_OUT);
+  });
+
+  it("drops the motion under prefers-reduced-motion", () => {
+    expect(reducedList).toContain(".hk-list-surface-enter-active");
+    expect(reducedList).toContain(".hk-list-surface-leave-active");
+    expect(reducedList).toContain(".hk-list-surface-move");
+    // The shared guard rule's BODY matters, not just the selector list —
+    // pin it (mirrors the strip-side ruleIn assertions above).
+    expect(ruleIn(reducedList, ".hk-list-surface-enter-active")).toContain(
+      "transition: none !important",
+    );
+    expect(ruleIn(reducedList, ".hk-list-surface-leave-active")).toContain(
+      "transition: none !important",
+    );
+    expect(ruleIn(reducedList, ".hk-list-surface-move")).toContain("transition: none !important");
+  });
+});
+
+describe("crumb list host (HkModalBreadcrumb → HkListTransition)", () => {
+  it("renders the group as display:contents — the nav stays the sole layout owner", () => {
+    expect(rule(breadcrumb, ".hk-modal-breadcrumb-levels")).toContain("display: contents");
+  });
+});

package/src/components/HkModalBreadcrumb.scss

@@ -28,7 +28,6 @@
   @include backdrop-filter(var(--hk-modal-breadcrumb-blur, blur(var(--blur-md))));
   pointer-events: none;
   @include user-select(none);
-  animation: hk-modal-breadcrumb-in var(--duration-fast, 0.15s) cubic-bezier(0.16, 1, 0.3, 1);
   /* Never wider than the viewport (minus the shared gutter): the strip is
      centred on the app header, so a stack whose labels outgrow the screen
      used to spill past BOTH edges at once and read as a clipped bar with
@@ -40,6 +39,62 @@
   overflow: hidden;
 }
 
+/* ── Whole-surface enter/leave (window choreography) ─────────────────
+   The strip IS a window artefact — it materializes when a second window
+   opens and dissolves when the last-but-one closes — so its own entrance
+   and exit ride the same motion signature as the windows themselves
+   (B3, user direction 2026-11-07): rise 10px while settling from 97%
+   scale and fading in; leave is the true reverse. A compositor-only pair
+   (opacity + transform only; nothing layout ever animates — the
+   backdrop-filtered layer never re-rasters mid-motion).
+
+   The centering translate is the PERMANENT transform prefix in every
+   state (byte-identical between resting and animated), exactly the
+   contract the modal frame keeps for its dragged-shift vars.
+
+   Vue drives these classes (<Transition name="hk-modal-breadcrumb"
+   appear> in the tsx); there is no keyframe animation on the base class —
+   a mount replay would stack on top of the enter transition. */
+.hk-modal-breadcrumb-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);
+}
+
+/* Chrome departs quicker than the windows it names (the modal's own
+   leave runs 0.32s): the strip has nothing left to say once its last
+   level is gone. */
+.hk-modal-breadcrumb-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);
+}
+
+.hk-modal-breadcrumb-enter-from,
+.hk-modal-breadcrumb-leave-to {
+  opacity: 0;
+  transform: translate(-50%, calc(-50% - 10px)) scale(0.97);
+}
+
+.hk-modal-breadcrumb-enter-to,
+.hk-modal-breadcrumb-leave-from {
+  opacity: 1;
+  transform: translate(-50%, -50%) scale(1);
+}
+
+/* ── The keyed crumb list ────────────────────────────────────────────
+   The trigger and the visible tail ride HkListTransition (surface
+   variant — the window choreography per crumb). The group renders a real
+   wrapper span, and it is `display: contents`: the strip's own flex row
+   stays the SOLE layout owner (gap, alignment, the fence's clipping) and
+   the wrapper generates no box of its own, while still giving the
+   TransitionGroup a DOM host whose children can be measured pre-patch
+   (the multi-removal geometry pins need it) and absolutely positioned
+   against the strip when a crumb leaves. */
+.hk-modal-breadcrumb-levels {
+  display: contents;
+}
+
 .hk-modal-breadcrumb-crumb {
   display: inline-flex;
   align-items: center;
@@ -239,22 +294,15 @@
   transform: scaleX(-1);
 }
 
-@keyframes hk-modal-breadcrumb-in {
-  from {
-    opacity: 0;
-    transform: translate(-50%, calc(-50% - 8px));
-  }
-  to {
-    opacity: 1;
-    transform: translate(-50%, -50%);
-  }
-}
-
 // House reduced-motion guard (HkExpansionPanel / HkTooltip pattern): the
-// entrance is a transform slide — drop it, keep the strip visible instantly.
+// entrance and exit are transform rides — drop both, keep the strip's
+// state changes instant (Vue's transition classes with no transition
+// resolve to an immediate swap; the crumb group's guard lives in
+// HkListTransition.scss).
 @media (prefers-reduced-motion: reduce) {
-  .hk-modal-breadcrumb {
-    animation: none;
+  .hk-modal-breadcrumb-enter-active,
+  .hk-modal-breadcrumb-leave-active {
+    transition: none;
   }
 }