@celestia-island/hikari 0.55.42 → 0.55.43

package/package.json

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

package/src/components/HkStepFlow.scss

@@ -1,19 +1,23 @@
-// Crossfading step bodies for HkStepFlow.
+// Direction-aware sliding 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.
+// positioned over it. This stylesheet owns ALL of the motion: direction,
+// travel distance and easings are driven by the `data-direction`
+// attribute and the staged `hk-stepflow-enter-from` / `hk-stepflow-leave-to` classes; the
+// component only toggles those classes on a shared-animation-bus frame
+// so the leave and the enter transitions start on the same style
+// recalculation (2026-09-22 user directive: back to the classic slide,
+// CSS as the base, animation context scheduling, zero black flashes).
 //
-// Duration resolves from one local custom property so consumers can tune
-// every phase at once; the default is the 0.3s family standard the spec
-// asked for.
+// Duration and travel resolve from local custom properties so consumers
+// can tune every phase at once; the 0.3s default matches the phone
+// sheet's morph duration so the sweep and the slide land together.
 
 .hk-step-flow {
   --hk-stepflow-duration: 0.3s;
+  --hk-stepflow-travel: 24px;
 }
 
 // Breathing room between the step indicator and the step bodies. Without
@@ -29,7 +33,7 @@
 // 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's step-flow-specific: the body gap folded into
+// block keeps only what is step-flow-specific: the body gap folded into
 // the pinned header's own padding (so the tint stays continuous while
 // the body scrolls) and the legacy styling knobs mapped onto the pin's
 // custom properties. The doubled class selector must beat
@@ -49,18 +53,17 @@
 }
 
 // The swap stage: entering bodies own the flow's height; the leaving one
-// overlays it, out of flow and pointer-transparent for the fade.
+// overlays it, out of flow and pointer-transparent for the slide.
 .hk-stepflow-bodies {
   position: relative;
 }
 
 .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.
+  // Enter grammar (the base rule is what an ENTERING body computes once
+  // its staged `hk-stepflow-enter-from` class lifts): the classic expressive ease-out.
   transition:
-    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));
+    opacity var(--hk-stepflow-duration, 0.3s) cubic-bezier(0.16, 1, 0.3, 1),
+    transform var(--hk-stepflow-duration, 0.3s) cubic-bezier(0.16, 1, 0.3, 1);
 }
 
 .hk-stepflow-body.leaving {
@@ -69,10 +72,46 @@
   left: 0;
   right: 0;
   pointer-events: none;
+  // Leave grammar: the sharp ease-in counterpart. Read when the staged
+  // `hk-stepflow-leave-to` class lands, so the exit keeps its own easing.
+  transition:
+    opacity var(--hk-stepflow-duration, 0.3s) cubic-bezier(0.5, 0, 0.75, 0),
+    transform var(--hk-stepflow-duration, 0.3s) cubic-bezier(0.5, 0, 0.75, 0);
+}
+
+// Direction-aware travel (the classic slide vocabulary): forward advances
+// exit LEFT and enter from the RIGHT; back mirrors. `hk-stepflow-enter-from` is the
+// entering body's staged start state, `hk-stepflow-leave-to` the leaving body's end
+// state — both removed/applied together one bus frame after staging.
+.hk-stepflow-bodies[data-direction="forward"] .hk-stepflow-body.hk-stepflow-enter-from,
+.hk-stepflow-bodies[data-direction="back"] .hk-stepflow-body.hk-stepflow-leave-to {
+  opacity: 0;
+  transform: translateX(var(--hk-stepflow-travel, 24px));
+}
+
+.hk-stepflow-bodies[data-direction="forward"] .hk-stepflow-body.hk-stepflow-leave-to,
+.hk-stepflow-bodies[data-direction="back"] .hk-stepflow-body.hk-stepflow-enter-from {
+  opacity: 0;
+  transform: translateX(calc(-1 * var(--hk-stepflow-travel, 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-bodies[data-direction="forward"] .hk-stepflow-body.hk-stepflow-enter-from,
+[dir="rtl"] .hk-stepflow-bodies[data-direction="back"] .hk-stepflow-body.hk-stepflow-leave-to {
+  transform: translateX(calc(-1 * var(--hk-stepflow-travel, 24px)));
+}
+
+[dir="rtl"] .hk-stepflow-bodies[data-direction="forward"] .hk-stepflow-body.hk-stepflow-leave-to,
+[dir="rtl"] .hk-stepflow-bodies[data-direction="back"] .hk-stepflow-body.hk-stepflow-enter-from {
+  transform: translateX(var(--hk-stepflow-travel, 24px));
 }
 
-/* Reduced motion: bodies swap instantly — no ride, no fade (the sheet
- * morph collapses the same way through its own duration tokens). */
+/* Reduced motion: bodies swap instantly. The component's duration probe
+ * reads the zeroed duration and settles without staging, so this block
+ * is the single switch for the whole choreography (the sheet morph
+ * collapses the same way through its own duration tokens). */
 @media (prefers-reduced-motion: reduce) {
   .hk-stepflow-body {
     transition: none;

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

@@ -0,0 +1,195 @@
+/**
+ * Source contract for the stepflow direction-aware slide (2026-09-22 user
+ * directive: back to the classic slide scheme, re-based on pure CSS with
+ * the shared animation context driving state, zero black flashes).
+ *
+ * A swap renders BOTH bodies for the whole duration — the entering one in
+ * the flow, the leaving one absolutely positioned — and the stylesheet
+ * owns ALL motion: direction, travel and easings are attribute/class
+ * driven, so a refactor cannot silently reintroduce inline-style
+ * choreography, a vertical ride, or the retired out-in grammar. The
+ * component side is pinned to the animation bus (scheduleFrame /
+ * reportTransition, no bare rAF) and to deterministic settling where no
+ * transition runs (reduced motion / stylesheet-less runtimes).
+ */
+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");
+const tsx = readFileSync(join(here, "HkStepFlow.tsx"), "utf-8");
+
+/** Top-level stylesheet rules as (selector-list, body) pairs. Nested
+ *  blocks (e.g. the reduced-motion media query) come out as one rule
+ *  whose body carries the inner braces — the direction rules this
+ *  contract binds are all top-level. */
+function extractRules(source: string): { selector: string; body: string }[] {
+  const rules: { selector: string; body: string }[] = [];
+  let i = 0;
+  while (i < source.length) {
+    const open = source.indexOf("{", i);
+    if (open === -1) break;
+    const selector = source
+      .slice(i, open)
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/[^\n]*/g, "")
+      .trim();
+    let depth = 1;
+    let j = open + 1;
+    while (j < source.length && depth > 0) {
+      if (source[j] === "{") depth += 1;
+      else if (source[j] === "}") depth -= 1;
+      j += 1;
+    }
+    rules.push({ selector, body: source.slice(open + 1, j - 1) });
+    i = j;
+  }
+  return rules;
+}
+
+const scssRules = extractRules(src);
+
+/** The declaration body of the ONE rule whose selector list carries the
+ *  exact selector — zero hits means the selector vanished, two means the
+ *  contract's premise broke; both are red. */
+function blockFor(selector: string): string {
+  const hits = scssRules.filter((r) =>
+    r.selector.split(",").map((s) => s.trim()).includes(selector),
+  );
+  expect(hits, `exactly one rule carries ${selector}`).toHaveLength(1);
+  return hits[0]!.body;
+}
+
+const TRAVEL_POSITIVE = "translateX(var(--hk-stepflow-travel, 24px))";
+const TRAVEL_NEGATIVE = "translateX(calc(-1 * var(--hk-stepflow-travel, 24px))";
+
+describe("HkStepFlow slide contract", () => {
+  it("pins the shared duration and travel tokens", () => {
+    const root = src.match(/\.hk-step-flow\s*\{[^}]*\}/)![0]!;
+    expect(root).toContain("--hk-stepflow-duration: 0.3s;");
+    expect(root).toContain("--hk-stepflow-travel: 24px;");
+  });
+
+  it("declares the enter grammar on the base body rule", () => {
+    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)");
+    // The classic expressive ease-out on enter.
+    expect(decl).toContain("cubic-bezier(0.16, 1, 0.3, 1)");
+  });
+
+  it("keeps the leaving body out of the flow with the leave grammar", () => {
+    const rule = src.match(/\.hk-stepflow-body\.leaving\s*\{[^}]*\}/)![0]!;
+    expect(rule).toContain("position: absolute");
+    expect(rule).toContain("pointer-events: none");
+    // The classic sharp ease-in on leave.
+    expect(rule).toContain("cubic-bezier(0.5, 0, 0.75, 0)");
+    expect(rule).toContain("var(--hk-stepflow-duration, 0.3s)");
+  });
+
+  it("binds each direction's travel sign to its exact selector", () => {
+    // The classic vocabulary, sign-bound (2026-09-22 R1 teeth gap: pinning
+    // selector strings plus the EXISTENCE of both translateX forms stayed
+    // green under a sign inversion — each selector must bind its sign):
+    // forward = enter from the RIGHT (+travel), exit LEFT (−travel);
+    // back mirrors; RTL flips the whole mapping.
+    const body = ".hk-stepflow-body";
+    const stage = ".hk-stepflow-bodies";
+    const ltr: Array<[string, string]> = [
+      [`${stage}[data-direction="forward"] ${body}.hk-stepflow-enter-from`, TRAVEL_POSITIVE],
+      [`${stage}[data-direction="forward"] ${body}.hk-stepflow-leave-to`, TRAVEL_NEGATIVE],
+      [`${stage}[data-direction="back"] ${body}.hk-stepflow-enter-from`, TRAVEL_NEGATIVE],
+      [`${stage}[data-direction="back"] ${body}.hk-stepflow-leave-to`, TRAVEL_POSITIVE],
+    ];
+    const rtl: Array<[string, string]> = [
+      [`[dir="rtl"] ${stage}[data-direction="forward"] ${body}.hk-stepflow-enter-from`, TRAVEL_NEGATIVE],
+      [`[dir="rtl"] ${stage}[data-direction="forward"] ${body}.hk-stepflow-leave-to`, TRAVEL_POSITIVE],
+      [`[dir="rtl"] ${stage}[data-direction="back"] ${body}.hk-stepflow-enter-from`, TRAVEL_POSITIVE],
+      [`[dir="rtl"] ${stage}[data-direction="back"] ${body}.hk-stepflow-leave-to`, TRAVEL_NEGATIVE],
+    ];
+    for (const [selector, sign] of ltr) {
+      const block = blockFor(selector);
+      expect(block, `${selector} must carry ${sign}`).toContain(sign);
+      const other = sign === TRAVEL_POSITIVE ? TRAVEL_NEGATIVE : TRAVEL_POSITIVE;
+      expect(block, `${selector} must not carry ${other}`).not.toContain(other);
+      expect(block).toContain("opacity: 0");
+    }
+    // RTL blocks are transform-only overrides over the LTR grammar.
+    for (const [selector, sign] of rtl) {
+      const block = blockFor(selector);
+      expect(block, `${selector} must carry ${sign}`).toContain(sign);
+      const other = sign === TRAVEL_POSITIVE ? TRAVEL_NEGATIVE : TRAVEL_POSITIVE;
+      expect(block, `${selector} must not carry ${other}`).not.toContain(other);
+    }
+    // The stage keeps its relative positioning for the overlay grammar.
+    expect(src).toMatch(/\.hk-stepflow-bodies\s*\{[^}]*position:\s*relative/);
+    // The component renders the direction attribute the CSS keys off.
+    expect(tsx).toContain("data-direction={dir}");
+  });
+
+  it("keeps all motion in the stylesheet — no inline style choreography", () => {
+    // The 2026-09-22 directive: CSS is the base. The component toggles
+    // classes only; it must never write motion styles or compute rides.
+    expect(tsx).not.toContain("style.transition");
+    expect(tsx).not.toContain("style.transform");
+    expect(tsx).not.toContain("style.opacity");
+    expect(tsx).not.toContain("translateY");
+  });
+
+  it("schedules state on the shared animation bus, never on bare rAF", () => {
+    expect(tsx).toContain('from "../runtime/animationBus"');
+    expect(tsx).toContain("scheduleFrame(");
+    expect(tsx).toContain("reportTransition(");
+    expect(tsx).not.toContain("requestAnimationFrame(");
+  });
+
+  it("settles deterministically where no transition runs", () => {
+    // The duration probe: zero (reduced motion / stylesheet-less runtime)
+    // selects the atomic instant-settle path — the debt pin for chest's
+    // transitionend-less wizard tests.
+    expect(tsx).toContain("bodyTransitionMs");
+    expect(tsx).toContain("transitionDuration");
+    // The motion path keeps a watchdog so a lost transitionend cannot
+    // freeze the swap (same grammar as the sheet morph).
+    expect(tsx).toContain("SWAP_WATCHDOG_GRACE_MS");
+    expect(tsx).toContain("addEventListener(\"transitionend\"");
+    // transitionend bubbles — only the leaving body's own transitions may
+    // settle the swap (R3 spot mutation: removing this guard survived the
+    // suite, so it is pinned here).
+    expect(tsx).toContain("event.target === goneEl");
+  });
+
+  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.
+    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 crossfade ride and the retired out-in classes", () => {
+    // Neither the round-7 vertical ride nor the pre-0.55.38 Vue
+    // transition class grammar may sneak back in, and no media block may
+    // fork step-body behaviour per viewport.
+    expect(tsx).not.toContain("hk-stepflow-fwd");
+    expect(tsx).not.toContain("hk-stepflow-back");
+    expect(src).not.toContain("hk-stepflow-fwd");
+    expect(src).not.toContain("hk-stepflow-back");
+    expect(src).not.toMatch(/@media[^{]*max-width/);
+  });
+
+  it("zeroes the transition under reduced motion so the probe settles", () => {
+    expect(src).toMatch(
+      /prefers-reduced-motion:\s*reduce\)\s*\{[\s\S]{0,160}?\.hk-stepflow-body\s*\{\s*transition:\s*none/,
+    );
+  });
+});

package/src/components/HkStepFlow.test.tsx

@@ -1,17 +1,22 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 
-import HkStepFlow from "./HkStepFlow";
+import HkStepFlow, { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
 import type { StepFlowSlotProps } from "./HkStepFlow";
 
 /**
  * HkStepFlow contract tests. House style: no @vue/test-utils dependency —
  * raw createApp mounts on shared containers torn down after each case.
  *
- * Note on transition-class assertions: happy-dom does not run stylesheet
- * transitions, so Vue's `out-in` leave phase leaves the leave-from/leave-
- * active classes in place until its rAF/settling timers fire — checking
- * class names right after `nextTick` is deterministic here.
+ * Two environment shapes are exercised:
+ *
+ * - DEFAULT (happy-dom, no stylesheet): the component's duration probe
+ *   reads a zero transition duration, so every swap settles INSTANTLY —
+ *   one body in the DOM, no timers to outlive, no transitionend to wait
+ *   for. This is the deterministic shape chest's wizard tests rely on.
+ * - MOTION STUBBED (`getComputedStyle` reports 0.3s): the full staged
+ *   slide choreography runs — staged start classes, one bus frame, then
+ *   the synchronized leave/enter transitions and the watchdog cleanup.
  */
 
 const mounts: ReturnType<typeof createApp>[] = [];
@@ -68,17 +73,38 @@ function mountStepFlow(options: {
   return { container, setCurrent: (key) => { current.value = key; } };
 }
 
-/** Let the swap's choreography timers (480ms sweep cleanup) settle. */
-async function settle(): Promise<void> {
+/** Let the swap watch's async flush (post render + internal nextTick) land. */
+async function flushSwap(): Promise<void> {
+  await nextTick();
+  await nextTick();
+  await nextTick();
+}
+
+/** Wait for the animation bus's staging frame(s) to fire. */
+async function awaitBusFrame(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 80));
 }
 
-/** Outlive the 480ms leaving-body cleanup timer. */
+/** Outlive the watchdog (0.3s stubbed duration + 350ms grace). */
 async function outliveSwap(): Promise<void> {
-  await new Promise((resolve) => setTimeout(resolve, 540));
+  await new Promise((resolve) => setTimeout(resolve, 720));
+}
+
+/** Force the motion path: the duration probe sees a 0.3s transition. */
+function stubMotion(duration = "0.3s"): void {
+  const real = window.getComputedStyle.bind(window);
+  vi.spyOn(window, "getComputedStyle").mockImplementation(
+    (el: Element, pseudoElt?: string | null): CSSStyleDeclaration => {
+      if (el instanceof HTMLElement && el.classList.contains("hk-stepflow-body")) {
+        return { transitionDuration: duration } as CSSStyleDeclaration;
+      }
+      return real(el, pseudoElt ?? undefined);
+    },
+  );
 }
 
 afterEach(() => {
+  vi.restoreAllMocks();
   for (const app of mounts.splice(0)) app.unmount();
   for (const el of containers.splice(0)) el.remove();
 });
@@ -107,46 +133,42 @@ describe("HkStepFlow", () => {
     const t = mountStepFlow({ initial: "a" });
     expect(t.container.querySelector(".hk-stepflow-body")?.textContent).toBe("a-body");
     t.setCurrent("d");
-    await nextTick();
-    await nextTick();
-    await new Promise((resolve) => setTimeout(resolve, 60));
-    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.
+    await flushSwap();
+    // Stylesheet-less runtime → instant settle: exactly one body, the new
+    // step's, with no leaving residue and no timers to outlive.
     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("crossfades both bodies for the whole swap window (2026-09-21 spec)", async () => {
+  it("settles deterministically to a single body where no transition runs", async () => {
+    // The 2026-09-22 debt pin: chest's LoginView MFA suite broke because
+    // the crossfade kept a leaving body alive for hundreds of ms in
+    // transitionend-less environments. With a zero probed duration the
+    // swap is atomic — the DOM NEVER carries two steps.
     const t = mountStepFlow({ initial: "a" });
+    const events: CustomEvent[] = [];
+    t.container.addEventListener(STEPFLOW_SWAP_EVENT, (e) => {
+      events.push(e as CustomEvent);
+    });
     t.setCurrent("b");
-    await nextTick();
-    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.
+    await flushSwap();
+    expect(t.container.querySelectorAll(".hk-stepflow-body").length).toBe(1);
+    expect(t.container.querySelector(".hk-stepflow-body.active")?.textContent).toBe("b-body");
+    expect(t.container.querySelector(".hk-stepflow-body.leaving")).toBeNull();
+    // Rapid successive swaps stay single-bodied the whole way through.
     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();
+    await flushSwap();
+    t.setCurrent("d");
+    await flushSwap();
     expect(t.container.querySelectorAll(".hk-stepflow-body").length).toBe(1);
+    expect(t.container.querySelector(".hk-stepflow-body.active")?.textContent).toBe("d-body");
+    // The sheet passthrough fired for every swap, carrying a numeric delta.
+    expect(events.length).toBe(3);
+    for (const e of events) {
+      expect(typeof (e.detail as { delta: number }).delta).toBe("number");
+    }
   });
 
   it("passes key/index/direction to scoped slots across navigation", async () => {
@@ -155,18 +177,17 @@ describe("HkStepFlow", () => {
     expect(seen.map((s) => `${s.key}:${s.index}:${s.direction}`)).toEqual(["a:0:forward"]);
 
     t.setCurrent("c");
-    await settle();
+    await flushSwap();
     expect(seen.at(-1)).toEqual({ key: "c", index: 2, direction: "forward" });
 
     t.setCurrent("b");
-    await settle();
+    await flushSwap();
     expect(seen.at(-1)).toEqual({ key: "b", index: 1, direction: "back" });
 
     // Returning forward again flips the direction back.
     t.setCurrent("d");
-    await settle();
+    await flushSwap();
     expect(seen.at(-1)?.direction).toBe("forward");
-    await settle();
   });
 
   it("emits update:modelValue when a clickable completed step is selected", async () => {
@@ -198,10 +219,9 @@ describe("HkStepFlow", () => {
     expect(first?.getAttribute("data-status")).toBe("completed");
     first.dispatchEvent(new MouseEvent("click"));
     await nextTick();
-    await settle();
+    await flushSwap();
     expect(selected).toEqual(["a"]);
     expect(container.querySelector(".hk-stepflow-body.active")?.textContent).toBe("");
-    await settle();
   });
 
   it("renders an empty body without warnings for an unknown key", async () => {
@@ -210,7 +230,7 @@ describe("HkStepFlow", () => {
       const t = mountStepFlow({ initial: "a" });
       t.setCurrent("does-not-exist");
       await nextTick();
-      await settle();
+      await flushSwap();
       const body = t.container.querySelector(".hk-stepflow-body.active");
       expect(body).not.toBeNull();
       expect(body?.textContent).toBe("");
@@ -262,9 +282,99 @@ describe("HkStepFlow", () => {
     // remembered index follows the array to 3, so 1 < 3 correctly reads BACK.
     current.value = "c";
     await nextTick();
-    await settle();
+    await flushSwap();
     expect(seen.at(-1)).toEqual({ key: "c", index: 1, direction: "back" });
-    await settle();
+  });
+});
+
+// ── Motion-stubbed slide choreography ─────────────────────────────────
+// `getComputedStyle` reports a 0.3s duration for step bodies, so the full
+// staged slide runs: staged start classes → one bus frame → synchronized
+// leave/enter transitions → transitionend/watchdog cleanup.
+describe("HkStepFlow slide swap (motion enabled)", () => {
+  it("stages both bodies, then starts the synchronized slide on the bus frame", async () => {
+    stubMotion();
+    const t = mountStepFlow({ initial: "a" });
+    const events: CustomEvent[] = [];
+    t.container.addEventListener(STEPFLOW_SWAP_EVENT, (e) => {
+      events.push(e as CustomEvent);
+    });
+    t.setCurrent("b");
+    await flushSwap();
+
+    // Staged: both bodies coexist; the leaving one overlays the flow
+    // WITHOUT its end state yet, the entering one holds its start state.
+    const leaving = t.container.querySelector<HTMLElement>(".hk-stepflow-body.leaving");
+    const active = t.container.querySelector<HTMLElement>(".hk-stepflow-body.active");
+    expect(leaving).not.toBeNull();
+    expect(active).not.toBeNull();
+    expect(leaving?.textContent).toBe("a-body");
+    expect(active?.textContent).toBe("b-body");
+    expect(leaving?.classList.contains("hk-stepflow-leave-to")).toBe(false);
+    expect(active?.classList.contains("hk-stepflow-enter-from")).toBe(true);
+    expect(
+      t.container.querySelector(".hk-stepflow-bodies")?.getAttribute("data-direction"),
+    ).toBe("forward");
+    // The sheet passthrough fired as the entering body took the flow.
+    expect(events.length).toBe(1);
+
+    // The bus frame flips both bodies together: leave end state on, enter
+    // start state off — both transitions start on one recalculation.
+    await awaitBusFrame();
+    expect(leaving?.classList.contains("hk-stepflow-leave-to")).toBe(true);
+    expect(active?.classList.contains("hk-stepflow-enter-from")).toBe(false);
+    // The slide is still in flight: both bodies remain mounted.
+    expect(t.container.querySelectorAll(".hk-stepflow-body").length).toBe(2);
+
+    // happy-dom never fires transitionend — the watchdog settles the swap.
+    await outliveSwap();
+    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("b-body");
+  });
+
+  it("mirrors the direction attribute for back navigation", async () => {
+    stubMotion();
+    const t = mountStepFlow({ initial: "c" });
+    t.setCurrent("a");
+    await flushSwap();
+    expect(
+      t.container.querySelector(".hk-stepflow-bodies")?.getAttribute("data-direction"),
+    ).toBe("back");
+    // Same staged grammar, mirrored travel lives in the stylesheet.
+    const leaving = t.container.querySelector<HTMLElement>(".hk-stepflow-body.leaving");
+    const active = t.container.querySelector<HTMLElement>(".hk-stepflow-body.active");
+    expect(leaving?.textContent).toBe("c-body");
+    expect(active?.classList.contains("hk-stepflow-enter-from")).toBe(true);
+    await awaitBusFrame();
+    expect(leaving?.classList.contains("hk-stepflow-leave-to")).toBe(true);
+    await outliveSwap();
+    expect(t.container.querySelectorAll(".hk-stepflow-body").length).toBe(1);
+  });
+
+  it("drops the stale leaving body outright on a rapid re-swap", async () => {
+    stubMotion();
+    const t = mountStepFlow({ initial: "a" });
+    t.setCurrent("b");
+    await flushSwap();
+    await awaitBusFrame();
+    // The first swap is running; re-swap before it settles.
+    t.setCurrent("c");
+    await flushSwap();
+    const leaving = t.container.querySelector<HTMLElement>(".hk-stepflow-body.leaving");
+    const active = t.container.querySelector<HTMLElement>(".hk-stepflow-body.active");
+    expect(t.container.querySelectorAll(".hk-stepflow-body").length).toBe(2);
+    expect(leaving?.textContent).toBe("b-body");
+    expect(active?.textContent).toBe("c-body");
+    // The new swap restages: no leftover end state on the new leaving body.
+    expect(leaving?.classList.contains("hk-stepflow-leave-to")).toBe(false);
+    expect(active?.classList.contains("hk-stepflow-enter-from")).toBe(true);
+    await awaitBusFrame();
+    await outliveSwap();
+    const bodies = t.container.querySelectorAll(".hk-stepflow-body");
+    expect(bodies.length).toBe(1);
+    expect(bodies[0]!.textContent).toBe("c-body");
   });
 });
 

package/src/components/HkStepFlow.tsx

@@ -11,6 +11,11 @@ import {
 import HkTimeline from "./HkTimeline";
 import type { TimelineCollapse, TimelineStep } from "./HkTimeline";
 import { SCROLL_HOST_CLASS } from "./HkScrollPin";
+import {
+  reportTransition,
+  scheduleFrame,
+  type AnimationHandle,
+} from "../runtime/animationBus";
 
 // Sticky header mode rides the shared scroll-pin contract (class + data
 // attributes on the timeline root); the pin stylesheet ships those
@@ -35,44 +40,82 @@ interface BodyEntry {
   /** 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. */
+   *  (absolutely positioned) for the slide's duration. */
   phase: "active" | "leaving";
 }
 
-/** A swap whose leaving body was handed its end state (transition armed). */
+/** A swap in flight: the leaving body slides out while the entering one
+ *  slides in. All MOTION is stylesheet-owned (the `data-direction`
+ *  attribute plus the `hk-stepflow-enter-from`/`hk-stepflow-leave-to` classes); script only
+ *  schedules the staging frame on the shared animation bus and books
+ *  the cleanup. */
 interface RunningSwap {
-  entryId: number;
-  timer: ReturnType<typeof setTimeout>;
+  leavingId: number;
+  enteringId: number;
+  /** The staging frame handle (disconnected when a re-swap pre-empts). */
+  frame: AnimationHandle | null;
+  /** Bus bookkeeping for the CSS sweep, held for its duration. */
+  report: AnimationHandle | null;
+  /** Watchdog: settle even if transitionend never arrives. */
+  timer: ReturnType<typeof setTimeout> | null;
+  listenEl: HTMLElement | null;
+  onEnded: ((event: TransitionEvent) => void) | null;
 }
 
 export const STEPFLOW_SWAP_EVENT = "hk-stepflow-swap";
 
+/** Extra grace on top of the resolved duration before the watchdog
+ *  settles the swap without a transitionend — the same grammar as the
+ *  sheet morph's sweep watchdog. */
+const SWAP_WATCHDOG_GRACE_MS = 350;
+
+/**
+ * Resolve the body's configured transition duration in milliseconds.
+ * A zero result means the swap settles INSTANTLY: reduced-motion users
+ * (the stylesheet zeroes the transition) and stylesheet-less runtimes
+ * (test environments) both get a deterministic single-body DOM with no
+ * timers to outlive and no transitionend to wait for.
+ */
+function bodyTransitionMs(el: HTMLElement | null): number {
+  if (!el) return 0;
+  const view = el.ownerDocument?.defaultView;
+  if (!view) return 0;
+  const raw = view.getComputedStyle(el).transitionDuration ?? "";
+  // Multiple entries ("0.3s, 0.3s") share one duration here — the first
+  // is representative; "0.3s" and "300ms" forms both parse.
+  const first = raw.split(",")[0]?.trim() ?? "";
+  const match = /^([0-9]*\.?[0-9]+)(ms|s)$/.exec(first);
+  if (!match) return 0;
+  const value = Number(match[1]);
+  return match[2] === "ms" ? value : value * 1000;
+}
+
 /**
  * Generic step-flow container: an optional HkTimeline header bound to
- * `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.
+ * `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 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.
+ * The swap choreography (2026-09-22 user directive: back to the classic
+ * direction-aware slide, re-based on pure CSS with the animation context
+ * driving state) — old and new bodies slide SIMULTANEOUSLY for the whole
+ * `--hk-stepflow-duration` (default 0.3s): forward advances exit left /
+ * enter from the right, back mirrors it. The entering body owns the
+ * flow's height from frame one (so the hosting sheet's morph targets the
+ * NEW geometry immediately) while the leaving body overlays it out of
+ * flow; travel distance, direction and easings all live in the
+ * stylesheet. State flips are scheduled on the shared animation bus:
+ * one staging frame after the DOM patch commits the start states, both
+ * bodies' classes flip in the same patch so leave and enter start on
+ * the same style recalculation — the simultaneous grammar is what keeps
+ * the retired `out-in` slide's empty mid-frame (and its raster flash)
+ * from coming back.
  *
  * 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.
+ * sheet's clip sweep starts on the same frame as the slide.
  */
 export default defineComponent({
   name: "HkStepFlow",
@@ -136,19 +179,31 @@ export default defineComponent({
       },
     );
 
-    // ── Crossfade body bookkeeping ────────────────────────────────────
+    // ── Swap body bookkeeping ─────────────────────────────────────────
     let mountSeq = 0;
     const bodies = ref<BodyEntry[]>([
       { id: mountSeq++, key: props.modelValue, phase: "active" },
     ]);
+    // `swap` is a plain let; `swapStage` carries the reactivity. Every
+    // mutation of `swap` is paired with either a `swapStage` or a
+    // `bodies` write, so renders always re-read the pair (see the watch
+    // and endSwap below).
     let swap: RunningSwap | null = null;
+    const swapStage = ref<"idle" | "staged" | "running">("idle");
     const flowRef = ref<HTMLDivElement | null>(null);
 
     function endSwap(): void {
       if (!swap) return;
-      clearTimeout(swap.timer);
-      const id = swap.entryId;
+      const handle = swap;
       swap = null;
+      swapStage.value = "idle";
+      handle.frame?.disconnect();
+      if (handle.timer !== null) clearTimeout(handle.timer);
+      handle.report?.disconnect();
+      if (handle.listenEl && handle.onEnded) {
+        handle.listenEl.removeEventListener("transitionend", handle.onEnded);
+      }
+      const id = handle.leavingId;
       bodies.value = bodies.value.filter((b) => b.id !== id);
     }
 
@@ -168,27 +223,69 @@ export default defineComponent({
       () => 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.
+        // A swap while the previous one is still sliding: drop the old
+        // leaving body outright and let the new swap own the stage. (If
+        // the previous entering body had not visibly settled yet it now
+        // becomes the leaving one and exits from its mid-flight state —
+        // one frame of re-staging, matching the classic grammar.)
         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",
-        );
+        // its height is the "old" reference for the sheet's delta. The
+        // same element also answers the motion probe.
+        const leavingEl =
+          flowRef.value?.querySelector<HTMLElement>(
+            ".hk-stepflow-body.active",
+          ) ?? null;
         const oldH = leavingEl?.offsetHeight ?? 0;
+        const durationMs = bodyTransitionMs(leavingEl);
+
+        if (durationMs <= 0) {
+          // Instant settle: no transition is configured (reduced motion,
+          // or a stylesheet-less runtime such as a test environment) —
+          // swap the bodies atomically so the DOM never carries two
+          // steps, then still poke the hosting sheet to remeasure.
+          bodies.value = [{ id: mountSeq++, key: next, phase: "active" }];
+          await nextTick();
+          const newEl = flowRef.value?.querySelector<HTMLElement>(
+            ".hk-stepflow-body.active",
+          );
+          const delta = (newEl?.offsetHeight ?? oldH) - oldH;
+          flowRef.value?.dispatchEvent(
+            new CustomEvent(STEPFLOW_SWAP_EVENT, {
+              bubbles: true,
+              detail: { delta },
+            }),
+          );
+          return;
+        }
+
         leaving.phase = "leaving";
-        bodies.value = [
-          ...bodies.value,
-          { id: mountSeq++, key: next, phase: "active" },
-        ];
+        const entering: BodyEntry = {
+          id: mountSeq++,
+          key: next,
+          phase: "active",
+        };
+        // Register the swap BEFORE the reactive mutations so the staged
+        // render already sees which entry is entering (hk-stepflow-enter-from) —
+        // `swap` itself is not reactive.
+        const handle: RunningSwap = {
+          leavingId: leaving.id,
+          enteringId: entering.id,
+          frame: null,
+          report: null,
+          timer: null,
+          listenEl: null,
+          onEnded: null,
+        };
+        swap = handle;
+        bodies.value = [...bodies.value, entering];
+        swapStage.value = "staged";
         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.
+        // Preempted while the DOM patched? The newer swap owns the stage —
+        // this continuation must not measure, dispatch or arm anything.
+        if (swap !== handle) return;
         const newEl = flowRef.value?.querySelector<HTMLElement>(
           ".hk-stepflow-body.active",
         );
@@ -196,48 +293,45 @@ export default defineComponent({
           ".hk-stepflow-body.leaving",
         );
         if (!newEl || !goneEl) {
+          // The flow went away mid-swap (unmount) — restore one body.
+          swap = null;
           leaving.phase = "active";
-          bodies.value = bodies.value.filter((b) => b.phase === "active");
+          bodies.value = [leaving];
+          swapStage.value = "idle";
           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";
+        const delta = newEl.offsetHeight - oldH;
         // Tell the hosting sheet to morph NOW (skip the settle debounce)
-        // so its clip sweep runs on the same frames as this crossfade.
+        // so its clip sweep runs on the same frames as this slide.
         flowRef.value?.dispatchEvent(
           new CustomEvent(STEPFLOW_SWAP_EVENT, {
             bubbles: true,
             detail: { delta },
           }),
         );
-        const entryId = leaving.id;
-        const timer = setTimeout(endSwap, 480);
-        swap = { entryId, timer };
+        handle.report = reportTransition(durationMs);
+        handle.listenEl = goneEl;
+        // Staging frame on the shared bus: commit the staged start states
+        // (the forced layout read), then flip BOTH bodies' classes in one
+        // patch — the leave and enter transitions start on the very same
+        // style recalculation.
+        handle.frame = scheduleFrame(() => {
+          if (swap !== handle) return;
+          handle.frame = null;
+          void flowRef.value?.offsetHeight;
+          const onEnded = (event: TransitionEvent) => {
+            // transitionend bubbles — only the leaving body's own
+            // property transitions may settle the swap.
+            if (event.target === goneEl) endSwap();
+          };
+          goneEl.addEventListener("transitionend", onEnded);
+          handle.onEnded = onEnded;
+          handle.timer = setTimeout(
+            endSwap,
+            durationMs + SWAP_WATCHDOG_GRACE_MS,
+          );
+          swapStage.value = "running";
+        });
       },
       { flush: "post" },
     );
@@ -248,7 +342,7 @@ export default defineComponent({
     });
 
     onBeforeUnmount(() => {
-      if (swap) clearTimeout(swap.timer);
+      endSwap();
     });
 
     return () => {
@@ -268,11 +362,20 @@ export default defineComponent({
               data-strategy={props.stickyHeader ? pinStrategy.value : undefined}
             />
           )}
-          <div class="hk-stepflow-bodies">
+          <div class="hk-stepflow-bodies" data-direction={dir}>
             {bodies.value.map((entry) => (
               <div
                 key={entry.id}
-                class={["hk-stepflow-body", entry.phase]}
+                class={[
+                  "hk-stepflow-body",
+                  entry.phase,
+                  entry.id === swap?.enteringId && swapStage.value === "staged"
+                    ? "hk-stepflow-enter-from"
+                    : null,
+                  entry.id === swap?.leavingId && swapStage.value === "running"
+                    ? "hk-stepflow-leave-to"
+                    : null,
+                ]}
               >
                 {slots[entry.key]?.({
                   key: entry.key,

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

@@ -1,61 +0,0 @@
-/**
- * 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/);
-  });
-});