@celestia-island/hikari 0.55.44 → 0.55.46

package/package.json

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

package/src/animation/registerAnimations.ts

@@ -106,6 +106,8 @@ registerCssAnimation("hk-placeholder-marquee-scroll", { infinite: true });
 // styles/admin-tokens.scss — admin header emergency-stop chip while
 // engaged (loops forever).
 registerCssAnimation("s-admin-header-emergency-pulse", { infinite: true });
+registerCssAnimation("hk-loading-veil-in");
+registerCssAnimation("hk-loading-veil-spin", { infinite: true });
 // The styles/theme/mixins.scss ambient/glow/entrance keyframes were
 // retired with the legacy Gen-1 sheet vendoring (hikari #476) — their
 // registrar entries went with them.

package/src/components/HkLoadingVeil.scss

@@ -0,0 +1,64 @@
+// HkLoadingVeil — fullscreen semi-transparent blocking overlay.
+// The z-index sits above the toast band (--hk-z-toast) so the veil is
+// the topmost painted surface while active; pointer-events: all on the
+// root swallows every interaction beneath (the blocking contract).
+.hk-loading-veil {
+  position: fixed;
+  inset: 0;
+  z-index: calc(var(--hk-z-toast, 4000) + 100);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  // Semi-transparent backdrop with a slight blur: the page beneath
+  // stays readable (orientation) but clearly inactive.
+  background: rgb(var(--color-background, 214 236 240) / 0.55);
+  backdrop-filter: blur(6px);
+  -webkit-backdrop-filter: blur(6px);
+  pointer-events: all;
+  animation: hk-loading-veil-in 150ms ease-out;
+
+  // Both light and dark themes ride the --color-background token.
+}
+
+.hk-loading-veil-body {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+  padding: 24px 32px;
+  border-radius: 12px;
+  background: rgb(var(--color-surface, 240 244 248) / 0.85);
+  box-shadow: 0 8px 32px rgb(0 0 0 / 0.12);
+}
+
+.hk-loading-veil-spinner {
+  display: inline-block;
+  width: 28px;
+  height: 28px;
+  border: 3px solid rgb(var(--color-border, 100 100 100) / 0.4);
+  border-top-color: rgb(var(--color-primary, 122 162 247));
+  border-radius: 50%;
+  animation: hk-loading-veil-spin 0.8s linear infinite;
+}
+
+.hk-loading-veil-label {
+  margin: 0;
+  font-size: 0.875rem;
+  color: rgb(var(--color-text, 30 30 30));
+  text-align: center;
+}
+
+@keyframes hk-loading-veil-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes hk-loading-veil-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}

package/src/components/HkLoadingVeil.test.tsx

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkLoadingVeil from "./HkLoadingVeil";
+
+/**
+ * HkLoadingVeil contract tests:
+ * - nothing renders while inactive (zero DOM footprint)
+ * - active paints the veil root, the spinner, and the label
+ * - no label prop → no label node (spinner-only)
+ * - reactive: active toggles appearance/disappearance
+ * - the root carries role=status / aria-live=polite / the label as
+ *   aria-label (screen readers announce the blocking state)
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils dependency.)
+ */
+
+const mounts: Array<() => void> = [];
+
+function mountVeil(props: { active?: boolean; label?: string } = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const active = ref(props.active ?? false);
+  const app = createApp({
+    setup() {
+      return () =>
+        h(HkLoadingVeil, {
+          active: active.value,
+          label: props.label ?? "",
+        });
+    },
+  });
+  app.mount(container);
+  mounts.push(() => {
+    app.unmount();
+    container.remove();
+  });
+  return { active, container };
+}
+
+afterEach(() => {
+  while (mounts.length) mounts.pop()?.();
+});
+
+describe("HkLoadingVeil", () => {
+  it("renders nothing while inactive", async () => {
+    const { container } = mountVeil({ active: false });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).toBeNull();
+  });
+
+  it("renders the veil, spinner and label while active", async () => {
+    const { container } = mountVeil({ active: true, label: "Opening…" });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).not.toBeNull();
+    expect(container.querySelector(".hk-loading-veil-spinner")).not.toBeNull();
+    const label = container.querySelector(".hk-loading-veil-label");
+    expect(label?.textContent).toBe("Opening…");
+  });
+
+  it("omits the label node when no label is given", async () => {
+    const { container } = mountVeil({ active: true });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil-spinner")).not.toBeNull();
+    expect(container.querySelector(".hk-loading-veil-label")).toBeNull();
+  });
+
+  it("appears and disappears reactively with the active prop", async () => {
+    const { active, container } = mountVeil({ active: false });
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).toBeNull();
+    active.value = true;
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).not.toBeNull();
+    active.value = false;
+    await nextTick();
+    expect(container.querySelector(".hk-loading-veil")).toBeNull();
+  });
+
+  it("carries role=status and the label as aria-label", async () => {
+    const { container } = mountVeil({ active: true, label: "Loading backend" });
+    await nextTick();
+    const root = container.querySelector(".hk-loading-veil");
+    expect(root?.getAttribute("role")).toBe("status");
+    expect(root?.getAttribute("aria-label")).toBe("Loading backend");
+    expect(root?.getAttribute("aria-live")).toBe("polite");
+  });
+});

package/src/components/HkLoadingVeil.tsx

@@ -0,0 +1,41 @@
+/**
+ * HkLoadingVeil — a fullscreen semi-transparent blocking overlay for
+ * navigation-span loading (the "one tap, no dead window" pattern).
+ *
+ * While `active`, the veil paints above everything (z-index above the
+ * toast band): a dimmed backdrop with backdrop-blur, a centered spinner
+ * and a one-line label, and it swallows ALL pointer events — the user
+ * cannot double-tap, scroll, or interact with anything beneath. When
+ * `active` turns false the veil fades out (150 ms) and pointer events
+ * return.
+ *
+ * Use it when a click must IMMEDIATELY show progress across a lazy
+ * boundary (the frontend→backend console jump): the toast band is
+ * top-right and non-blocking — callers that need true blocking (one
+ * click, fullscreen feedback, zero interaction until ready) mount this
+ * instead. It is NOT a modal: no scroll lock, no focus trap, no
+ * Esc-close — the caller's flight owns the lifetime.
+ */
+import { defineComponent } from "vue";
+import "./HkLoadingVeil.scss";
+
+export default defineComponent({
+  name: "HkLoadingVeil",
+  props: {
+    /** Paint + block while true; fade out on false. */
+    active: { type: Boolean, default: false },
+    /** One-line label under the spinner (already-localized by caller). */
+    label: { type: String, default: "" },
+  },
+  setup(props) {
+    return () =>
+      props.active ? (
+        <div class="hk-loading-veil" role="status" aria-live="polite" aria-label={props.label || "loading"}>
+          <div class="hk-loading-veil-body">
+            <span class="hk-loading-veil-spinner" aria-hidden="true" />
+            {props.label ? <p class="hk-loading-veil-label">{props.label}</p> : null}
+          </div>
+        </div>
+      ) : null;
+  },
+});

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