@celestia-island/hikari 0.55.40 → 0.55.41

package/package.json

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

package/src/components/HkModal.scss

@@ -475,8 +475,13 @@
     //   clip-path sweep (the only transition left on phones).
     //
     // Desktop keeps the full base list (height + max-height + clip-path).
+    // 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
+    // through this list (height/max-height are not transitioned), so
+    // only content morphs ride this duration.
     transition:
-      clip-path var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
+      clip-path var(--hk-modal-morph-duration, 0.3s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
     // !important beats the inline maxWidth (width prop); base width: 100%
     // already applies at every viewport, so only the cap is re-asserted.
     max-width: 100% !important;

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

@@ -121,3 +121,15 @@ describe("HkModal mobile sheet spacing contract", () => {
     });
   });
 });
+
+// 2026-09-21 user spec, round 7: the phone sheet's clip sweep shares the
+// stepflow crossfade's 0.3s family duration (the pair must land together).
+describe("HkModal phone morph duration contract", () => {
+  it("rides the clip sweep on --hk-modal-morph-duration (0.3s default)", () => {
+    const block = src.slice(src.indexOf("@media (max-width: 767px)"));
+    const content = block.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
+    expect(content).toMatch(
+      /clip-path var\(--hk-modal-morph-duration, 0\.3s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\)/,
+    );
+  });
+});

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

@@ -63,6 +63,16 @@ describe("sheet family morph-performance contract", () => {
     );
   });
 
+  it("slows the phone sheet's clip sweep to the crossfade's 0.3s", () => {
+    // 2026-09-21 user spec, round 7: the clip sweep, the riding body and
+    // the fade must land together — the phone block overrides the fast
+    // desktop timing with the stepflow family standard. Desktop keeps
+    // the fast pair above.
+    expect(mobileModal).toMatch(
+      /^[ \t]*clip-path var\(--hk-modal-morph-duration, 0\.3s\) 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,

package/src/components/HkModal.tsx

@@ -1,15 +1,4 @@
-import {
-  computed,
-  defineComponent,
-  nextTick,
-  onBeforeUnmount,
-  onMounted,
-  ref,
-  shallowRef,
-  Teleport,
-  watch,
-  type PropType,
-} from "vue";
+import { computed, defineComponent, nextTick, onBeforeUnmount, onMounted, ref, shallowRef, Teleport, watch, type PropType,  } from "vue";
 
 import { useI18n } from "../i18n/context";
 import "./HkModal.scss";
@@ -23,6 +12,8 @@ import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
 import { useSurfaceContentHold } from "../composables/useSurfaceContentHold";
 import { useSizeMorph } from "../composables/useSizeMorph";
+
+import { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
 import HButton from "./HkButton";
 import HFab from "./HkFab";
 import HSpinner from "./HkSpinner";
@@ -218,6 +209,22 @@ export default defineComponent({
     let previouslyFocused: HTMLElement | null = null;
     let unmounted = false;
 
+    // HkStepFlow swaps dispatch STEPFLOW_SWAP_EVENT (bubbling) from the
+    // flow root the moment the entering body owns the flow height. The
+    // morph's settle debounce is tuned for streaming bursts, but a step
+    // swap is one clean change whose sheet sweep must start on the SAME
+    // frames as the crossfade (2026-09-21 user spec, round 7) — so the
+    // event short-circuits straight into remeasure().
+    const onStepflowSwap = (): void => {
+      if (machine.phase.value === "open") morph.remeasure();
+    };
+    onMounted(() => {
+      bodyRef.value?.addEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
+    });
+    onBeforeUnmount(() => {
+      bodyRef.value?.removeEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
+    });
+
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
     const contentZ = computed(() => (handle.value?.zIndex ?? 0) + 1);
     const resolvedWidth = computed(() =>

package/src/components/HkStepFlow.crossfade.contract.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Source contract for the stepflow crossfade (2026-09-21 user spec,
+ * round 7): a swap renders BOTH bodies for the whole duration — the
+ * entering one in the flow, the leaving one absolutely positioned — and
+ * the ride + fade share one duration/ease pair (0.3s family default) so
+ * the sheet's clip sweep, the ride and the crossfade land together.
+ *
+ * Pinned here so a refactor cannot silently regress to the retired
+ * out-in slide (hk-stepflow-fwd/back classes) or strand a phone-only
+ * stand-down: the crossfade is the ONE grammar, on every viewport.
+ */
+import { 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 src = readFileSync(join(here, "HkStepFlow.scss"), "utf-8");
+
+describe("HkStepFlow crossfade contract", () => {
+  it("rides and fades on one shared duration/ease pair", () => {
+    const rule = src.match(/\.hk-stepflow-body\s*\{[^}]*\}/)![0]!;
+    const transitions = rule.match(/transition:\s*[^;}]+/g) ?? [];
+    expect(transitions).toHaveLength(1);
+    const decl = transitions[0]!;
+    expect(decl).toContain("opacity");
+    expect(decl).toContain("transform");
+    expect(decl).toContain("var(--hk-stepflow-duration, 0.3s)");
+  });
+
+  it("defaults the family duration to 0.3s", () => {
+    const root = src.match(/\.hk-step-flow\s*\{[^}]*\}/)![0]!;
+    expect(root).toContain("--hk-stepflow-duration: 0.3s;");
+  });
+
+  it("keeps the leaving body out of the flow and pointer-transparent", () => {
+    const rule = src.match(/\.hk-stepflow-body\.leaving\s*\{[^}]*\}/)![0]!;
+    expect(rule).toContain("position: absolute");
+    expect(rule).toContain("pointer-events: none");
+  });
+
+  it("dispatches the swap passthrough so the host sheet morphs in lockstep", () => {
+    // The component side of the lockstep contract: the swap dispatches
+    // the bubbling event the moment the entering body owns the flow
+    // height, and the modal side short-circuits its settle debounce.
+    const tsx = readFileSync(join(here, "HkStepFlow.tsx"), "utf-8");
+    expect(tsx).toContain("STEPFLOW_SWAP_EVENT");
+    expect(tsx).toMatch(/new CustomEvent\(STEPFLOW_SWAP_EVENT/);
+    const modal = readFileSync(join(here, "HkModal.tsx"), "utf-8");
+    expect(modal).toContain('addEventListener(STEPFLOW_SWAP_EVENT');
+    expect(modal).toMatch(/removeEventListener\(STEPFLOW_SWAP_EVENT/);
+  });
+
+  it("retires the out-in slide classes and every viewport stand-down", () => {
+    // The retired grammar must not sneak back in, and the crossfade is
+    // unconditional — no media block may fork step-body behaviour.
+    expect(src).not.toContain("hk-stepflow-fwd");
+    expect(src).not.toContain("hk-stepflow-back");
+    expect(src).not.toMatch(/@media[^{]*max-width/);
+  });
+});

package/src/components/HkStepFlow.scss

@@ -1,17 +1,23 @@
-// Direction-aware step body transitions for HkStepFlow.
+// Crossfading step bodies for HkStepFlow.
+//
+// A swap renders BOTH bodies for the whole duration: the entering one in
+// the flow (so the container's height — and the hosting sheet's morph —
+// are the NEW geometry from frame one) and the leaving one absolutely
+// positioned over it. Exactly one body rides the sheet's moving top edge
+// while the other stays pinned (2026-09-21 user spec, round 7); the ride
+// and the opacity crossfade share one duration/ease pair so the sheet's
+// clip sweep, the ride and the fade all land together.
 //
-// Forward slides the body leftward (the flow advances to a later step),
-// back mirrors it toward the right. Timings follow the phase-transition
-// family — an expressive ease-out on enter, a sharp ease-in on leave.
 // Duration resolves from one local custom property so consumers can tune
-// every phase at once.
+// every phase at once; the default is the 0.3s family standard the spec
+// asked for.
 
 .hk-step-flow {
-  --hk-stepflow-duration: 0.2s;
+  --hk-stepflow-duration: 0.3s;
 }
 
-// Breathing room between the step indicator and the step body. Without it
-// the timeline row butts directly against the first body element (modal
+// Breathing room between the step indicator and the step bodies. Without
+// it the timeline row butts directly against the first body element (modal
 // wizards read as cramped). Tune or remove per host through
 // --hk-stepflow-header-gap; the sticky mode folds the gap into the pinned
 // header's own padding so the surface tint stays continuous while the
@@ -23,10 +29,10 @@
 // Sticky header mode: positioning, surface and the whitespace contract
 // live on the shared .hk-scroll-pin rules (HkScrollPin.scss) — the
 // timeline root carries the class plus data-side/data-strategy. This
-// block keeps only what is step-flow-specific: the body gap folded into
+// block keeps only what's step-flow-specific: the body gap folded into
 // the pinned header's own padding (so the tint stays continuous while
-// the body scrolls underneath) and the legacy styling knobs mapped onto
-// the pin's custom properties. The doubled class selector must beat
+// the body scrolls) and the legacy styling knobs mapped onto the pin's
+// custom properties. The doubled class selector must beat
 // .hk-scroll-pin's own declarations regardless of import order.
 .hk-step-flow[data-sticky-header] > .hk-timeline.hk-scroll-pin {
   --hk-scroll-pin-z: var(--hk-stepflow-sticky-z, 10);
@@ -42,76 +48,33 @@
   padding-bottom: var(--hk-stepflow-header-gap, var(--space-16, 1rem));
 }
 
-.hk-stepflow-fwd-enter-active,
-.hk-stepflow-back-enter-active {
-  transition:
-    opacity var(--hk-stepflow-duration, 0.2s) cubic-bezier(0.16, 1, 0.3, 1),
-    transform var(--hk-stepflow-duration, 0.2s) cubic-bezier(0.16, 1, 0.3, 1);
+// The swap stage: entering bodies own the flow's height; the leaving one
+// overlays it, out of flow and pointer-transparent for the fade.
+.hk-stepflow-bodies {
+  position: relative;
 }
 
-.hk-stepflow-fwd-leave-active,
-.hk-stepflow-back-leave-active {
+.hk-stepflow-body {
+  // The ride + fade (armed from script with a staged start state — see
+  // the component's swap dance): same tokens for both properties so the
+  // sheet's clip sweep, the ride and the crossfade stay in lockstep.
   transition:
-    opacity var(--hk-stepflow-duration, 0.2s) cubic-bezier(0.5, 0, 0.75, 0),
-    transform var(--hk-stepflow-duration, 0.2s) cubic-bezier(0.5, 0, 0.75, 0);
-}
-
-.hk-stepflow-fwd-enter-from {
-  opacity: 0;
-  transform: translateX(24px);
-}
-
-.hk-stepflow-fwd-leave-to {
-  opacity: 0;
-  transform: translateX(-24px);
-}
-
-.hk-stepflow-back-enter-from {
-  opacity: 0;
-  transform: translateX(-24px);
+    opacity var(--hk-stepflow-duration, 0.3s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
+    transform var(--hk-stepflow-duration, 0.3s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
 }
 
-.hk-stepflow-back-leave-to {
-  opacity: 0;
-  transform: translateX(24px);
-}
-
-/* RTL: reading direction flips, so the slide mirrors — forward enters
- * from the left and exits right (house pattern: HkListTransition.scss
- * [dir="rtl"] form). */
-[dir="rtl"] .hk-stepflow-fwd-enter-from,
-[dir="rtl"] .hk-stepflow-back-leave-to {
-  transform: translateX(-24px);
-}
-
-[dir="rtl"] .hk-stepflow-fwd-leave-to,
-[dir="rtl"] .hk-stepflow-back-enter-from {
-  transform: translateX(24px);
-}
-
-/* Phone (≤767px): the body snaps between steps instead of sliding. On
- * the mobile sheet the frame's own size morph already carries the
- * spatial feedback, and the slide's transient layer promotion/demotion
- * costs a one-frame raster gap at both ends on phone GPUs — the
- * "content blinks once on every step" report (2026-09-21 chest field
- * report, AddProviderWizard Prev/Next). Same shape as the
- * reduced-motion block below; desktop keeps the directional slide. */
-@media (max-width: 767px) {
-  .hk-stepflow-fwd-enter-active,
-  .hk-stepflow-back-enter-active,
-  .hk-stepflow-fwd-leave-active,
-  .hk-stepflow-back-leave-active {
-    transition: none;
-  }
+.hk-stepflow-body.leaving {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  pointer-events: none;
 }
 
-/* Reduced motion: the body snaps between steps instead of sliding
- * (house pattern: HkExpansionPanel.scss / HkAffixPicker.scss). */
+/* Reduced motion: bodies swap instantly — no ride, no fade (the sheet
+ * morph collapses the same way through its own duration tokens). */
 @media (prefers-reduced-motion: reduce) {
-  .hk-stepflow-fwd-enter-active,
-  .hk-stepflow-back-enter-active,
-  .hk-stepflow-fwd-leave-active,
-  .hk-stepflow-back-leave-active {
+  .hk-stepflow-body {
     transition: none;
   }
 }

package/src/components/HkStepFlow.test.tsx

@@ -68,11 +68,16 @@ function mountStepFlow(options: {
   return { container, setCurrent: (key) => { current.value = key; } };
 }
 
-/** Let Vue finish the out-in cycle's settling timers before teardown. */
+/** Let the swap's choreography timers (480ms sweep cleanup) settle. */
 async function settle(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 80));
 }
 
+/** Outlive the 480ms leaving-body cleanup timer. */
+async function outliveSwap(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 540));
+}
+
 afterEach(() => {
   for (const app of mounts.splice(0)) app.unmount();
   for (const el of containers.splice(0)) el.remove();
@@ -105,25 +110,43 @@ describe("HkStepFlow", () => {
     await nextTick();
     await nextTick();
     await new Promise((resolve) => setTimeout(resolve, 60));
-    expect(t.container.querySelector(".hk-stepflow-body")?.textContent).toBe("d-body");
-    await settle();
+    expect(t.container.querySelector(".hk-stepflow-body.active")?.textContent).toBe("d-body");
+    await outliveSwap();
+    // The leaving body is gone after the sweep window; exactly one body
+    // remains and it is the new step's.
+    const bodies = t.container.querySelectorAll(".hk-stepflow-body");
+    expect(bodies.length).toBe(1);
+    expect(bodies[0]!.className).toBe("hk-stepflow-body active");
+    expect(bodies[0]!.textContent).toBe("d-body");
   });
 
-  it("slides forward when moving to a later step and back when returning", async () => {
-    const t = mountStepFlow({ initial: "b" });
-    const bodyClass = (): string =>
-      t.container.querySelector(".hk-stepflow-body")?.className ?? "";
-
-    t.setCurrent("c");
-    await nextTick();
-    // out-in: the old body is mid-leave on this tick.
-    expect(bodyClass()).toContain("hk-stepflow-fwd-leave-active");
-
-    await settle();
+  it("crossfades both bodies for the whole swap window (2026-09-21 spec)", async () => {
+    const t = mountStepFlow({ initial: "a" });
     t.setCurrent("b");
     await nextTick();
-    expect(bodyClass()).toContain("hk-stepflow-back-leave-active");
-    await settle();
+    await nextTick();
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    const leaving = t.container.querySelector<HTMLElement>(".hk-stepflow-body.leaving");
+    const active = t.container.querySelector<HTMLElement>(".hk-stepflow-body.active");
+    // Both bodies coexist; the leaving one is out of the flow and the
+    // pair carries the crossfade's END opacities (armed inline —
+    // happy-dom does not run the stylesheet transition).
+    expect(leaving).not.toBeNull();
+    expect(active).not.toBeNull();
+    expect(leaving?.textContent).toBe("a-body");
+    expect(active?.textContent).toBe("b-body");
+    expect(leaving?.style.opacity).toBe("0");
+    expect(active?.style.opacity).toBe("1");
+    // A rapid re-swap mid-fade drops the stale leaving body outright.
+    t.setCurrent("c");
+    await nextTick();
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    const after = t.container.querySelectorAll(".hk-stepflow-body");
+    expect(after.length).toBe(2);
+    expect(t.container.querySelector(".hk-stepflow-body.leaving")?.textContent).toBe("b-body");
+    expect(t.container.querySelector(".hk-stepflow-body.active")?.textContent).toBe("c-body");
+    await outliveSwap();
+    expect(t.container.querySelectorAll(".hk-stepflow-body").length).toBe(1);
   });
 
   it("passes key/index/direction to scoped slots across navigation", async () => {
@@ -177,7 +200,7 @@ describe("HkStepFlow", () => {
     await nextTick();
     await settle();
     expect(selected).toEqual(["a"]);
-    expect(container.querySelector(".hk-stepflow-body")?.textContent).toBe("");
+    expect(container.querySelector(".hk-stepflow-body.active")?.textContent).toBe("");
     await settle();
   });
 
@@ -188,7 +211,7 @@ describe("HkStepFlow", () => {
       t.setCurrent("does-not-exist");
       await nextTick();
       await settle();
-      const body = t.container.querySelector(".hk-stepflow-body");
+      const body = t.container.querySelector(".hk-stepflow-body.active");
       expect(body).not.toBeNull();
       expect(body?.textContent).toBe("");
       expect(warnSpy.mock.calls.some((args) => String(args[0]).includes("Slot"))).toBe(false);

package/src/components/HkStepFlow.tsx

@@ -1,4 +1,12 @@
-import { defineComponent, Transition, onMounted, ref, watch, type PropType } from "vue";
+import {
+  defineComponent,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  watch,
+  type PropType,
+} from "vue";
 
 import HkTimeline from "./HkTimeline";
 import type { TimelineCollapse, TimelineStep } from "./HkTimeline";
@@ -20,12 +28,51 @@ export interface StepFlowSlotProps {
   direction: "forward" | "back";
 }
 
+/** One rendered body: the active step plus, during a swap, the leaving one. */
+interface BodyEntry {
+  /** Unique mount id — the v-for key, so a re-entering step remounts. */
+  id: number;
+  /** The step key this body renders. */
+  key: string;
+  /** `active` bodies sit in the flow; a `leaving` body is out of flow
+   *  (absolutely positioned) for the crossfade's duration. */
+  phase: "active" | "leaving";
+}
+
+/** A swap whose leaving body was handed its end state (transition armed). */
+interface RunningSwap {
+  entryId: number;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export const STEPFLOW_SWAP_EVENT = "hk-stepflow-swap";
+
 /**
  * Generic step-flow container: an optional HkTimeline header bound to
- * `modelValue` plus a direction-aware sliding body fed purely by named
- * slots keyed by step key. Navigation state lives in the consumer — the
- * component only translates `modelValue` changes into `out-in` body
- * transitions and echoes timeline selections upward.
+ * `modelValue` plus a crossfading body fed purely by named slots keyed
+ * by step key. Navigation state lives in the consumer — the component
+ * only translates `modelValue` changes into body swaps and echoes
+ * timeline selections upward.
+ *
+ * The swap choreography (2026-09-21 user spec, round 7): old and new
+ * bodies cross-fade SIMULTANEOUSLY for the whole `--hk-stepflow-duration`
+ * (default 0.3s), and exactly one of them rides the sheet's moving top
+ * edge while the other stays pinned at the post-swap geometry:
+ *
+ * - SHRINK (old body taller): the sheet's top edge folds DOWN, so the
+ *   OLD body rides it (translateY −Δ → 0, glued to the edge) while it
+ *   fades out; the NEW body is already at its final top and only fades
+ *   in. (The container's layout height is the new body's from frame
+ *   one, so the sheet morph and the crossfade start together.)
+ * - GROW: mirrored — the OLD body stays where it was (its top is below
+ *   the container's new top by Δ, i.e. exactly the band the sheet's
+ *   staged clip keeps visible) and fades out; the NEW body rides the
+ *   edge upward (translateY +Δ → 0) while fading in.
+ *
+ * Each swap also dispatches `hk-stepflow-swap` (bubbles, detail
+ * `{ delta }`) from the flow root — the hosting modal listens for it and
+ * re-measures immediately, skipping the morph's settle debounce so the
+ * sheet's clip sweep starts on the same frame as the crossfade.
  */
 export default defineComponent({
   name: "HkStepFlow",
@@ -89,6 +136,22 @@ export default defineComponent({
       },
     );
 
+    // ── Crossfade body bookkeeping ────────────────────────────────────
+    let mountSeq = 0;
+    const bodies = ref<BodyEntry[]>([
+      { id: mountSeq++, key: props.modelValue, phase: "active" },
+    ]);
+    let swap: RunningSwap | null = null;
+    const flowRef = ref<HTMLDivElement | null>(null);
+
+    function endSwap(): void {
+      if (!swap) return;
+      clearTimeout(swap.timer);
+      const id = swap.entryId;
+      swap = null;
+      bodies.value = bodies.value.filter((b) => b.id !== id);
+    }
+
     // Sticky-header whitespace strategy (2026-09-14): the timeline is the
     // flow's boundary element, but content may sit ABOVE the whole flow
     // inside the same scroll body — a bleed pin's negative margin would
@@ -99,27 +162,100 @@ export default defineComponent({
     // on mount (attribute scan only — no geometry), so CSR surfaces see
     // the attribute flip once right after hydration; hikari renders
     // client-side only.
-    const flowRef = ref<HTMLDivElement | null>(null);
     const pinStrategy = ref<"offset" | "bleed">("bleed");
 
+    watch(
+      () => props.modelValue,
+      async (next, prev) => {
+        if (next === prev) return;
+        // A swap while the previous one is still fading: drop the old
+        // leaving body outright (its content is gone from the flow) and
+        // let the new swap own the choreography.
+        endSwap();
+        const leaving = bodies.value.find((b) => b.phase === "active");
+        if (!leaving) return;
+        // Pre-swap geometry while the leaving body still owns the flow:
+        // its height is the "old" reference for the ride distance.
+        const leavingEl = flowRef.value?.querySelector<HTMLElement>(
+          ".hk-stepflow-body.active",
+        );
+        const oldH = leavingEl?.offsetHeight ?? 0;
+        leaving.phase = "leaving";
+        bodies.value = [
+          ...bodies.value,
+          { id: mountSeq++, key: next, phase: "active" },
+        ];
+        await nextTick();
+        // Post-swap geometry: the container's flow height is the new
+        // body's; the leaving body (already absolute) keeps reporting
+        // its own height for the delta.
+        const newEl = flowRef.value?.querySelector<HTMLElement>(
+          ".hk-stepflow-body.active",
+        );
+        const goneEl = flowRef.value?.querySelector<HTMLElement>(
+          ".hk-stepflow-body.leaving",
+        );
+        if (!newEl || !goneEl) {
+          leaving.phase = "active";
+          bodies.value = bodies.value.filter((b) => b.phase === "active");
+          return;
+        }
+        const newH = newEl.offsetHeight;
+        const delta = newH - oldH;
+        // Ride distance (px): one body rides the sheet's moving top edge
+        // by exactly |Δ|; the other stays put. Grow: new rides from +Δ
+        // (the old top) to 0. Shrink: old rides from −Δ (its original
+        // top, above the container's new top) to 0.
+        const mag = Math.abs(delta);
+        const rides = delta > 0 ? goneEl : newEl;
+        const from = `${delta > 0 ? mag : -mag}px`;
+        // Arm the riders: stage the start state with the transition off,
+        // flush, then flip to the end state under the live transition
+        // (same dance grammar as the sheet morph — no mid-frame paint of
+        // the intermediate state).
+        for (const el of [goneEl, newEl]) {
+          el.style.transition = "none";
+        }
+        goneEl.style.transform = delta > 0 ? "translateY(0px)" : from;
+        newEl.style.transform = delta > 0 ? from : "translateY(0px)";
+        goneEl.style.opacity = "1";
+        newEl.style.opacity = "0";
+        void flowRef.value?.offsetHeight;
+        for (const el of [goneEl, newEl]) {
+          el.style.transition = "";
+        }
+        rides.style.transform = "translateY(0px)";
+        goneEl.style.opacity = "0";
+        newEl.style.opacity = "1";
+        // Tell the hosting sheet to morph NOW (skip the settle debounce)
+        // so its clip sweep runs on the same frames as this crossfade.
+        flowRef.value?.dispatchEvent(
+          new CustomEvent(STEPFLOW_SWAP_EVENT, {
+            bubbles: true,
+            detail: { delta },
+          }),
+        );
+        const entryId = leaving.id;
+        const timer = setTimeout(endSwap, 480);
+        swap = { entryId, timer };
+      },
+      { flush: "post" },
+    );
+
     onMounted(() => {
       const host = flowRef.value?.closest(`.${SCROLL_HOST_CLASS}`);
       if (host?.hasAttribute("data-pad-cover")) pinStrategy.value = "offset";
     });
 
+    onBeforeUnmount(() => {
+      if (swap) clearTimeout(swap.timer);
+    });
+
     return () => {
-      const index = indexOf(props.modelValue);
-      // An unknown key finds no slot: the body simply renders empty, no
-      // warnings — consumers may briefly park between two known steps.
-      const slotFn = index >= 0 ? slots[props.modelValue] : undefined;
       const dir = direction.value;
 
       return (
-        <div
-          ref={flowRef}
-          class="hk-step-flow"
-          data-sticky-header={props.stickyHeader || undefined}
-        >
+        <div ref={flowRef} class="hk-step-flow" data-sticky-header={props.stickyHeader || undefined}>
           {!props.hideTimeline && (
             <HkTimeline
               steps={props.steps}
@@ -132,14 +268,20 @@ export default defineComponent({
               data-strategy={props.stickyHeader ? pinStrategy.value : undefined}
             />
           )}
-          <Transition
-            name={dir === "back" ? "hk-stepflow-back" : "hk-stepflow-fwd"}
-            mode="out-in"
-          >
-            <div key={props.modelValue} class="hk-stepflow-body">
-              {slotFn?.({ key: props.modelValue, index, direction: dir })}
-            </div>
-          </Transition>
+          <div class="hk-stepflow-bodies">
+            {bodies.value.map((entry) => (
+              <div
+                key={entry.id}
+                class={["hk-stepflow-body", entry.phase]}
+              >
+                {slots[entry.key]?.({
+                  key: entry.key,
+                  index: indexOf(entry.key),
+                  direction: dir,
+                })}
+              </div>
+            ))}
+          </div>
         </div>
       );
     };

package/src/components/HkStepFlow.phonesnap.test.ts

@@ -1,105 +0,0 @@
-/**
- * Source contract for the phone step-swap snap (2026-09-21 chest field
- * report, AddProviderWizard Prev/Next "content blinks once").
- *
- * On ≤767px the step body's slide+fade must be inert: inside the mobile
- * bottom sheet the frame's own size morph already carries the spatial
- * feedback, and the slide's transient layer promotion/demotion costs a
- * one-frame raster gap at both ends on phone GPUs. Desktop keeps the
- * directional slide; reduced motion already snaps globally.
- *
- * Pinned here so a refactor cannot silently restore the phone slide —
- * the class names are the same, so only the media-scoped rule proves it.
- */
-import { 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 src = readFileSync(join(here, "HkStepFlow.scss"), "utf-8");
-
-/** Brace-aware `@media <query>` block extractor: a naive slice at the
- *  first `}` would cut at the first nested rule's closing brace. */
-function mediaBlocks(source: string, query: string): string[] {
-  const blocks: string[] = [];
-  let from = 0;
-  for (;;) {
-    const at = source.indexOf(`@media ${query}`, from);
-    if (at < 0) break;
-    const open = source.indexOf("{", at);
-    let depth = 0;
-    let i = open;
-    for (; i < source.length; i++) {
-      if (source[i] === "{") depth++;
-      else if (source[i] === "}") {
-        depth--;
-        if (depth === 0) break;
-      }
-    }
-    blocks.push(source.slice(at, i + 1));
-    from = i + 1;
-  }
-  return blocks;
-}
-
-const PHONE_QUERY = "(max-width: 767px)";
-/** The four transition-class selectors Vue's <Transition> toggles. */
-const ACTIVE_SELECTORS = [
-  ".hk-stepflow-fwd-enter-active",
-  ".hk-stepflow-back-enter-active",
-  ".hk-stepflow-fwd-leave-active",
-  ".hk-stepflow-back-leave-active",
-];
-
-/** The single ≤767px block, asserted present IN the test that needs it
- *  (a beforeAll assertion would downgrade a missing block to "skipped"
- *  instead of a hard failure). */
-function phoneBlock(): string {
-  const blocks = mediaBlocks(src, PHONE_QUERY);
-  expect(blocks.length).toBe(1);
-  return blocks[0]!;
-}
-
-describe("HkStepFlow phone snap contract", () => {
-  it("disables the slide/fade transition on ≤767px", () => {
-    const block = phoneBlock();
-    for (const selector of ACTIVE_SELECTORS) {
-      expect(block).toContain(selector);
-    }
-    // transition:none on every active class — the whole point: no
-    // property animates, so no promotion window exists to blink.
-    expect(block).toMatch(/transition:\s*none\s*;/);
-    // …and it must be the ONLY transition declaration in the block
-    // (a stray `transition: opacity …` would re-open the blink).
-    const declarations = block.match(/transition:\s*[^;]+;/g) ?? [];
-    expect(declarations).toHaveLength(1);
-  });
-
-  it("keeps the desktop slide outside the phone block", () => {
-    // Mutation guard: the phone rule must be ADDITIVE. The base
-    // (desktop) enter/leave rules still carry the opacity+transform
-    // transition, so deleting them fails here instead of passing
-    // vacuously.
-    const baseEnter = src.match(
-      /\.hk-stepflow-fwd-enter-active\s*,\s*\n\.hk-stepflow-back-enter-active\s*\{[^}]*\}/,
-    );
-    expect(baseEnter).not.toBeNull();
-    expect(baseEnter![0]).toContain("transition:");
-    expect(baseEnter![0]).toContain("opacity");
-    expect(baseEnter![0]).toContain("transform");
-
-    const baseLeave = src.match(
-      /\.hk-stepflow-fwd-leave-active\s*,\s*\n\.hk-stepflow-back-leave-active\s*\{[^}]*\}/,
-    );
-    expect(baseLeave).not.toBeNull();
-    expect(baseLeave![0]).toContain("opacity");
-    expect(baseLeave![0]).toContain("transform");
-  });
-
-  it("keeps the reduce-motion snap block (house pattern) intact", () => {
-    const blocks = mediaBlocks(src, "(prefers-reduced-motion: reduce)");
-    expect(blocks.length).toBe(1);
-    expect(blocks[0]).toMatch(/transition:\s*none\s*;/);
-  });
-});