@celestia-island/hikari 0.55.45 → 0.55.47

package/package.json

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

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

@@ -0,0 +1,329 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkModal from "./HkModal";
+import {
+  SHEET_SWEEP_SETTLE_EVENT,
+  SHEET_SWEEP_STAGE_EVENT,
+  STEPFLOW_SWAP_EVENT,
+} from "./HkStepFlow";
+
+/**
+ * Behavioural contract for the stepflow → sheet morph handoff
+ * (2026-09-22 user directive, round 10): a HkStepFlow swap announces the
+ * phase that owns the height change (`{ delta, durationMs, phase }`) and
+ * the hosting modal must morph its clip over ONE phase, not the 0.3s
+ * family default.
+ *
+ * Round-1 verification (2026-09-22) found this wiring DEAD in the real
+ * consumer: the listener was attached in `onMounted` while the modal
+ * renders nothing until `machine.mounted` flips, so `bodyRef.value` was
+ * undefined at attach time and every mount-closed-then-open consumer
+ * (chest's wizards) silently got no handoff at all — the sheet fell back
+ * to the morph's 150ms settle debounce plus a 0.3s sweep. These tests
+ * therefore drive the REAL pattern (mount closed, open later) and assert
+ * the observable token, so the defect cannot return unnoticed.
+ *
+ * happy-dom has no transition engine: durations are stubbed and rAF is
+ * frozen (same harness as HkModal.contenthold.test.tsx), with fake timers
+ * driving the machine's phase edges.
+ */
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+function freezeRaf(): void {
+  vi.stubGlobal("requestAnimationFrame", (_cb: FrameRequestCallback) => 0 as unknown as number);
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+}
+
+function stubDurations(): void {
+  const realGCS = window.getComputedStyle.bind(window);
+  vi.stubGlobal("getComputedStyle", (el: Element, ...rest: unknown[]) => {
+    const style = realGCS(el as Element, ...(rest as []));
+    return { ...style, transitionDuration: "0.3s" } as CSSStyleDeclaration;
+  });
+}
+
+interface Rig {
+  open: { value: boolean };
+  bodyEl: () => HTMLElement | null;
+  frameEl: () => HTMLElement | null;
+  /** Fire the swap passthrough the way HkStepFlow does (bubbling from a
+   *  descendant of the modal body). */
+  announceSwap: (detail: { delta: number; durationMs: number; phase: string }) => void;
+  morphToken: () => string;
+}
+
+async function mountRig(): Promise<Rig> {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const open = ref(false);
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkModal, {
+          modelValue: open.value,
+          closable: true,
+          title: "swap-test",
+          "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+        }, {
+          default: () => h("div", { class: "swap-body" }, "step content"),
+        });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  await nextTick();
+
+  return {
+    open,
+    bodyEl: () => document.querySelector<HTMLElement>(".hk-modal-body"),
+    frameEl: () => document.querySelector<HTMLElement>(".hk-modal-content"),
+    announceSwap: (detail) => {
+      const host = document.querySelector<HTMLElement>(".hk-modal-body .swap-body")
+        ?? document.querySelector<HTMLElement>(".hk-modal-body");
+      if (!host) throw new Error("announceSwap: modal body missing");
+      host.dispatchEvent(
+        new CustomEvent(STEPFLOW_SWAP_EVENT, { bubbles: true, detail }),
+      );
+    },
+    morphToken: () =>
+      document
+        .querySelector<HTMLElement>(".hk-modal-content")
+        ?.style.getPropertyValue("--hk-modal-morph-duration") ?? "",
+  };
+}
+
+describe("HkModal stepflow swap handoff", () => {
+  it("morphs over the announced phase for a modal mounted CLOSED (the real consumer path)", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    const rig = await mountRig();
+
+    // The premise of the round-1 defect: while closed there is no body to
+    // attach to, so an onMounted-time attach could never have worked.
+    expect(rig.bodyEl()).toBeNull();
+
+    rig.open.value = true;
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.bodyEl()).not.toBeNull();
+    expect(rig.morphToken()).toBe("");
+
+    // A swap that owns the height in its FIRST phase.
+    rig.announceSwap({ delta: 120, durationMs: 150, phase: "exit" });
+    await nextTick();
+    expect(rig.morphToken()).toBe("150ms");
+
+    // …and the override is scoped to that one sweep window.
+    await vi.advanceTimersByTimeAsync(500);
+    expect(rig.morphToken()).toBe("");
+  });
+
+  it("leaves the stylesheet default in place for an instant settlement", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    const rig = await mountRig();
+    rig.open.value = true;
+    await vi.advanceTimersByTimeAsync(600);
+
+    // Reduced motion / stylesheet-less runtimes announce durationMs 0:
+    // there is no phase to match, so no override may be written.
+    rig.announceSwap({ delta: 0, durationMs: 0, phase: "instant" });
+    await nextTick();
+    expect(rig.morphToken()).toBe("");
+    await vi.advanceTimersByTimeAsync(500);
+    expect(rig.morphToken()).toBe("");
+  });
+
+  it("ignores announcements while the surface is still unfolding", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    const rig = await mountRig();
+    rig.open.value = true;
+    // The machine's phase is opening* here: the morph is not armed yet, so
+    // an override would be stranded on the frame.
+    await vi.advanceTimersByTimeAsync(10);
+    if (rig.bodyEl()) {
+      rig.announceSwap({ delta: 60, durationMs: 150, phase: "exit" });
+      await nextTick();
+    }
+    expect(rig.morphToken()).toBe("");
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.morphToken()).toBe("");
+  });
+
+  it("drops the override when the modal unmounts mid-sweep", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    const rig = await mountRig();
+    rig.open.value = true;
+    await vi.advanceTimersByTimeAsync(600);
+
+    rig.announceSwap({ delta: 80, durationMs: 150, phase: "exit" });
+    await nextTick();
+    const frame = rig.frameEl();
+    expect(frame?.style.getPropertyValue("--hk-modal-morph-duration")).toBe("150ms");
+
+    // Unmount with the sweep still in flight: the timer must not outlive
+    // the component, and the token must not survive on the detached node.
+    for (const app of mounts.splice(0)) app.unmount();
+    await nextTick();
+    expect(frame?.style.getPropertyValue("--hk-modal-morph-duration")).toBe("");
+  });
+});
+
+describe("HkModal publishes its own fold for the step flow", () => {
+  /** Box model: the frame hugs its content up to `cap`; the content probe
+   *  reports `content` plus the chrome the calibration measures. */
+  let content = 0;
+  let cap = Number.POSITIVE_INFINITY;
+  const realOffsetHeight = Object.getOwnPropertyDescriptor(
+    HTMLElement.prototype,
+    "offsetHeight",
+  );
+
+  function stubBox(initialContent: number, capPx: number): void {
+    content = initialContent;
+    cap = capPx;
+    Object.defineProperty(HTMLElement.prototype, "offsetHeight", {
+      configurable: true,
+      get(this: HTMLElement) {
+        if (this.classList.contains("hk-modal-content")) {
+          return Math.min(content + 96, cap);
+        }
+        if (this.classList.contains("hk-modal-body-inner")) return content;
+        return 0;
+      },
+    });
+  }
+
+  function restoreBox(): void {
+    if (realOffsetHeight) {
+      Object.defineProperty(
+        HTMLElement.prototype,
+        "offsetHeight",
+        realOffsetHeight,
+      );
+    }
+  }
+
+  function stubClip(): void {
+    const real = window.getComputedStyle.bind(window);
+    vi.stubGlobal("getComputedStyle", (el: Element, ...rest: unknown[]) => {
+      const style = real(el as Element, ...(rest as []));
+      if (!(el instanceof HTMLElement)) return style;
+      if (el.classList.contains("hk-modal-content")) {
+        return {
+          ...style,
+          transitionDuration: "0.3s",
+          getPropertyValue: (name: string) =>
+            name === "--hk-sheet-morph" ? "clip" : style.getPropertyValue(name),
+        } as CSSStyleDeclaration;
+      }
+      return style;
+    });
+  }
+
+  afterEach(() => {
+    restoreBox();
+  });
+
+  it("republishes the morph's real fold span and its landing", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubClip();
+    // Content starts at 500 (frame 596) and the sheet is uncapped, so the
+    // morph can fold: shrinking the content must publish a conceal.
+    stubBox(500, Number.POSITIVE_INFINITY);
+    const rig = await mountRig();
+    rig.open.value = true;
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.bodyEl()).not.toBeNull();
+
+    const stages: unknown[] = [];
+    let settled = 0;
+    rig.bodyEl()!.addEventListener(SHEET_SWEEP_STAGE_EVENT, (e) => {
+      stages.push((e as CustomEvent).detail);
+    });
+    rig.bodyEl()!.addEventListener(SHEET_SWEEP_SETTLE_EVENT, () => {
+      settled += 1;
+    });
+
+    // The sweep needs real frames: pump rAF from here on (a frozen frame
+    // loop would strand the morph's warmup, as its own docs warn).
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+      frames.push(cb);
+      return frames.length;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+
+    // The flow owns the new height and announces; the modal measures,
+    // stages its conceal, and publishes the span it will sweep.
+    content = 300;
+    rig.announceSwap({ delta: -200, durationMs: 150, phase: "enter" });
+    await nextTick();
+    expect(stages).toEqual([
+      { direction: "conceal", from: 596, to: 396, sweep: expect.any(Number) },
+    ]);
+
+    // …and the landing is published when the sweep finishes, carrying the
+    // sweep's own identity (without it a consumer cannot tell its landing
+    // from another dance's teardown).
+    const landed: Array<{ sweep?: number }> = [];
+    rig.bodyEl()!.addEventListener(SHEET_SWEEP_SETTLE_EVENT, (e) => {
+      landed.push((e as CustomEvent<{ sweep?: number }>).detail ?? {});
+    });
+    for (let i = 0; i < 4; i += 1) {
+      for (const cb of frames.splice(0)) cb(i * 16);
+      await vi.advanceTimersByTimeAsync(60);
+    }
+    await vi.advanceTimersByTimeAsync(1200);
+    expect(settled).toBeGreaterThan(0);
+    expect(landed.length).toBeGreaterThan(0);
+    expect(typeof landed[0]?.sweep).toBe("number");
+  });
+
+  it("publishes NOTHING when the sheet is capped and cannot fold", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubClip();
+    // Content that already overflows the cap: the natural height cannot
+    // change, so the morph stages no sweep at all — the flow must park
+    // nothing (its span defaults to 0).
+    stubBox(900, 596);
+    const rig = await mountRig();
+    rig.open.value = true;
+    await vi.advanceTimersByTimeAsync(600);
+
+    const stages: unknown[] = [];
+    let settled = 0;
+    rig.bodyEl()!.addEventListener(SHEET_SWEEP_STAGE_EVENT, (e) => {
+      stages.push((e as CustomEvent).detail);
+    });
+    rig.bodyEl()!.addEventListener(SHEET_SWEEP_SETTLE_EVENT, () => {
+      settled += 1;
+    });
+
+    content = 850;
+    rig.announceSwap({ delta: -50, durationMs: 150, phase: "enter" });
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(1200);
+    expect(stages).toEqual([]);
+    expect(settled).toBe(0);
+  });
+});

package/src/components/HkModal.tsx

@@ -13,7 +13,11 @@ import { useSurfaceMachine } from "../composables/useSurfaceMachine";
 import { useSurfaceContentHold } from "../composables/useSurfaceContentHold";
 import { useSizeMorph } from "../composables/useSizeMorph";
 
-import { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
+import {
+  SHEET_SWEEP_SETTLE_EVENT,
+  SHEET_SWEEP_STAGE_EVENT,
+  STEPFLOW_SWAP_EVENT,
+} from "./HkStepFlow";
 import HButton from "./HkButton";
 import HFab from "./HkFab";
 import HSpinner from "./HkSpinner";
@@ -205,24 +209,70 @@ export default defineComponent({
       deferRemeasure: () =>
         machine.phase.value === "openingFrom" ||
         machine.phase.value === "openingTo",
+      // Republish the morph's real sweep span and its landing on the body
+      // element (bubbling), so content choreography can park against the
+      // landing geometry and release exactly when it happens instead of
+      // guessing the cap and the warmup (2026-09-22 verification finding).
+      onSweepStage: (info) => {
+        bodyRef.value?.dispatchEvent(
+          new CustomEvent(SHEET_SWEEP_STAGE_EVENT, { bubbles: true, detail: info }),
+        );
+      },
+      onSweepSettle: (info) => {
+        bodyRef.value?.dispatchEvent(
+          new CustomEvent(SHEET_SWEEP_SETTLE_EVENT, {
+            bubbles: true,
+            detail: info,
+          }),
+        );
+      },
     });
     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();
+    // flow root at the edge where the sheet must morph: the exit edge for
+    // a GROW (the new height is already in the flow, so the sheet finishes
+    // growing while the old body leaves) and the enter edge for a SHRINK
+    // (the flow held its old height until the old body finished playing).
+    // The morph's settle debounce is tuned for streaming bursts; a step
+    // swap is one clean change whose sweep must land INSIDE its 0.15s
+    // phase (2026-09-22 user directive, round 10) — so the event
+    // short-circuits straight into remeasure() and overrides the sheet's
+    // own sweep duration for this one morph (the stylesheet default stays
+    // the 0.3s family standard for every other morph). The override is
+    // cleared on the same duration+grace watchdog the sweep itself uses.
+    let morphDurationTimer: ReturnType<typeof setTimeout> | null = null;
+    const clearMorphDuration = (): void => {
+      if (morphDurationTimer !== null) {
+        clearTimeout(morphDurationTimer);
+        morphDurationTimer = null;
+      }
+      contentRef.value?.style.removeProperty("--hk-modal-morph-duration");
+    };
+    const onStepflowSwap = (event: Event): void => {
+      if (machine.phase.value !== "open") {
+        // A swap announced while the surface is closing/opening: drop any
+        // override a previous morph left behind instead of letting it ride
+        // into the next open (it is otherwise only cleared by its own
+        // ms+350 timer).
+        clearMorphDuration();
+        return;
+      }
+      const frame = contentRef.value;
+      const ms = (event as CustomEvent<{ durationMs?: number }>).detail?.durationMs;
+      if (frame && typeof ms === "number" && ms > 0) {
+        frame.style.setProperty("--hk-modal-morph-duration", `${ms}ms`);
+        morph.remeasure();
+        if (morphDurationTimer !== null) clearTimeout(morphDurationTimer);
+        morphDurationTimer = setTimeout(clearMorphDuration, ms + 350);
+      } else {
+        morph.remeasure();
+      }
     };
-    onMounted(() => {
-      bodyRef.value?.addEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
-    });
     onBeforeUnmount(() => {
       bodyRef.value?.removeEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
+      clearMorphDuration();
     });
 
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
@@ -430,6 +480,26 @@ export default defineComponent({
       },
     });
 
+    // The swap listener must follow the ELEMENT, not the component
+    // lifecycle: the render returns null until `machine.mounted` flips, so
+    // an onMounted-time attach silently missed for every
+    // mount-closed-then-open consumer — i.e. every chest wizard
+    // (2026-09-22 R1 verification finding: this wiring was dead at
+    // runtime, which is why the sheet kept morphing on the observer's
+    // 150ms debounce and the 0.3s stylesheet default). Post-flush on the
+    // mount flag instead: the listener lands on the real node and comes
+    // off with it.
+    watch(
+      machine.mounted,
+      (isMounted) => {
+        const el = bodyRef.value;
+        if (!el) return;
+        if (isMounted) el.addEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
+        else el.removeEventListener(STEPFLOW_SWAP_EVENT, onStepflowSwap);
+      },
+      { flush: "post", immediate: true },
+    );
+
     // --- Windowed mode ---
 
     function setupWindowed(container: HTMLElement) {

package/src/components/HkStepFlow.scss

@@ -1,19 +1,29 @@
-// Direction-aware sliding step bodies for HkStepFlow.
+// Two-phase 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. 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).
+// A swap runs TWO phases, each half of `--hk-stepflow-duration` (0.15s of
+// the 0.3s family standard):
+//
+//   EXIT  — the OLD body alone is visible: `hk-stepflow-leave-to` slides
+//           it out (forward exits left, back exits right) and fades it,
+//           with the sharp ease-in;
+//   ENTER — the old body is gone and the NEW one fades in PLACE (no
+//           travel) with the expressive ease-out.
+//
+// The new body is mounted from frame one with `hk-stepflow-enter-pending`
+// (invisible, but laid out so the flow owns the new height immediately),
+// which is what makes the two bodies structurally unable to overlap —
+// the doubled-ghost flash of the simultaneous cross-slide (2026-09-22
+// user directive, round 10).
+//
+// This stylesheet owns ALL of the motion: direction, travel distance and
+// easings are driven by the `data-direction` attribute and those two
+// classes; the component only flips them and schedules the phases. The
+// sheet's own morph is phase-matched by the hosting modal, which reads
+// the swap event's `durationMs`.
 //
 // 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.
+// sheet's morph window so the sweep and the slide land together.
 
 .hk-step-flow {
   --hk-stepflow-duration: 0.3s;
@@ -52,62 +62,89 @@
   padding-bottom: var(--hk-stepflow-header-gap, var(--space-16, 1rem));
 }
 
-// The swap stage: entering bodies own the flow's height; the leaving one
-// overlays it, out of flow and pointer-transparent for the slide.
+// The swap stage: the entering body owns the flow's height; the leaving
+// one overlays it, out of flow and pointer-transparent for the exit.
 .hk-stepflow-bodies {
   position: relative;
 }
 
 .hk-stepflow-body {
-  // 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.
+  // ENTER grammar (what a body computes once its `hk-stepflow-enter-pending`
+  // class lifts at the phase-2 edge): a plain fade in place — the new
+  // content never travels (2026-09-22 user directive). A STANDARD ease, not
+  // the expressive ease-out: the front-loaded curve put the first painted
+  // frame at ~50% opacity (half the distance in ~11% of the phase), which
+  // read on the device as the new content flashing in — the standard curve
+  // starts at ~20% instead (2026-09-22 device report, round 11).
   transition:
-    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);
+    opacity calc(var(--hk-stepflow-duration, 0.3s) / 2) cubic-bezier(0.4, 0, 0.2, 1);
 }
 
 .hk-stepflow-body.leaving {
   position: absolute;
+  // Default anchor: the stage's TOP. The component measures how far the
+  // stage travelled during the swap patch and writes that as an inline
+  // `top`, which is the only correct answer across host shapes — a
+  // bottom-docked sheet whose box grew, a capped box that could not grow,
+  // and an in-flow stage all differ, and a CSS anchor can only encode one
+  // of them (a guessed bottom anchor cut 276px off a capped sheet's
+  // outgoing step).
   top: 0;
   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.
+  // LEAVE grammar: the slide keeps its accelerating ease-in; the FADE gets
+  // its own gentler curve so the old content eases out over several frames
+  // instead of dropping 0.40 -> 0.03 in one (same device report).
   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);
+    opacity calc(var(--hk-stepflow-duration, 0.3s) / 2) cubic-bezier(0.4, 0, 0.6, 1),
+    transform calc(var(--hk-stepflow-duration, 0.3s) / 2) 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 {
+// The parked new body of a shrink whose sheet will fold. Out of flow (the
+// stage keeps the OLD height through the fold) and offset by the span the
+// sheet published, so it already sits on the line the fold lands on; the
+// component releases both when the sheet reports that landing.
+.hk-stepflow-body.hk-stepflow-enter-tail {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+}
+
+// The staged new body: LAID OUT (so the flow owns the new height from
+// frame one — the sheet can grow through the exit phase) but invisible,
+// which is what guarantees the old and new bodies are never on screen
+// together. `visibility` (not display/removal) keeps it measurable and
+// keeps a re-swap from ever destroying its reveal.
+.hk-stepflow-body.hk-stepflow-enter-pending {
   opacity: 0;
-  transform: translateX(var(--hk-stepflow-travel, 24px));
+  visibility: hidden;
 }
 
-.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 {
+// Direction-aware travel, on the LEAVING body only: forward exits LEFT,
+// back exits RIGHT (the classic vocabulary). The entering body appears in
+// place, so it carries no direction rule at all.
+.hk-stepflow-bodies[data-direction="forward"] .hk-stepflow-body.hk-stepflow-leave-to {
   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)));
+.hk-stepflow-bodies[data-direction="back"] .hk-stepflow-body.hk-stepflow-leave-to {
+  opacity: 0;
+  transform: translateX(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 {
+/* RTL: reading direction flips, so the exit mirrors — forward exits right
+ * (house pattern: HkListTransition.scss [dir="rtl"] form). */
+[dir="rtl"] .hk-stepflow-bodies[data-direction="forward"] .hk-stepflow-body.hk-stepflow-leave-to {
   transform: translateX(var(--hk-stepflow-travel, 24px));
 }
 
+[dir="rtl"] .hk-stepflow-bodies[data-direction="back"] .hk-stepflow-body.hk-stepflow-leave-to {
+  transform: translateX(calc(-1 * var(--hk-stepflow-travel, 24px)));
+}
+
 /* 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