@celestia-island/hikari 0.55.0 → 0.55.1

package/package.json

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

package/src/components/HkDrawer.tsx

@@ -19,6 +19,7 @@ import { createBackGuard } from "../runtime/backStack";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
+import { useSurfaceContentHold } from "../composables/useSurfaceContentHold";
 import HIconButton from "./HkIconButton";
 import HIcon from "./HkIcon";
 import "./window-close.scss";
@@ -269,6 +270,8 @@ export default defineComponent({
       cleanup();
     });
 
+    const contentHold = useSurfaceContentHold(machine.phase);
+
     return () => {
       if (!machine.mounted.value) return null;
       const panelPrefix = `hk-drawer-${props.side}`;
@@ -295,7 +298,11 @@ export default defineComponent({
                 else if (e.key === "Tab" && panelRef.value) trapFocus(panelRef.value, e);
               }}
             >
-              {props.title || slots.header ? (
+              {/* Same close-fold content hold as HkModal: the sheet's
+                  slide-away plays over the last live content even when
+                  the consumer tears its state down on close. */}
+              {contentHold.hold(() => [
+              props.title || slots.header ? (
                 <div class="hk-drawer-header">
                   {slots.header ? (
                     slots.header()
@@ -314,13 +321,14 @@ export default defineComponent({
                     </HIconButton>
                   ) : null}
                 </div>
-              ) : null}
+              ) : null,
               <div ref={bodyWrapRef} class="hk-drawer-body-wrap">
                 <div ref={bodyRef} class="hk-drawer-body">{slots.default?.()}</div>
-              </div>
-              {slots.footer ? (
+              </div>,
+              slots.footer ? (
                 <div class="hk-drawer-footer">{slots.footer()}</div>
-              ) : null}
+              ) : null,
+              ])}
             </div>
       </Teleport>
       );

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

@@ -0,0 +1,156 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkModal from "./HkModal";
+
+/**
+ * Source contract for the close-fold content hold (chest field report
+ * 2026-09-16): consumers routinely tear down the state that feeds the
+ * window's body in the same tick as the close (TodoLogModal's
+ * clear-on-close watcher emptied a 697px conversation window to a 200px
+ * stub BEFORE the fold started). While the machine is in a closing phase
+ * HkModal serves the last live-rendered children, so the fold always
+ * plays over the content the user was looking at.
+ *
+ * happy-dom has no transition engine, so the machine's duration probe
+ * reads a stubbed 0.3s (same harness trick as the surface-machine tests)
+ * and rAF is frozen — the flip timers drive the phase edges
+ * deterministically.
+ */
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(async () => {
+  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 };
+  setLines: (lines: string[]) => void;
+  closeWithTeardown: () => void;
+  bodyText: () => string;
+  frameEl: () => HTMLElement | null;
+}
+
+/** Mount HkModal behind a wrapper that models the chest clear-on-close
+ *  pattern: the body state clears in the SAME handler that flips the
+ *  v-model false. */
+async function mountRig(initialLines: string[]): Promise<Rig> {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const open = ref(false);
+  const lines = ref<string[]>(initialLines);
+
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkModal, {
+          modelValue: open.value,
+          closable: true,
+          title: "hold-test",
+          "onUpdate:modelValue": (v: boolean) => {
+            open.value = v;
+            // The reported chest pattern: destroy the content with the
+            // close request, before any leave animation runs.
+            if (!v) lines.value = [];
+          },
+        }, {
+          default: () => h("div", lines.value.map((l, i) => h("p", { key: i }, l))),
+        });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  await nextTick();
+
+  return {
+    open,
+    setLines: (next: string[]) => { lines.value = next; },
+    /** Faithful chest pattern: the store-watcher teardown runs in the SAME
+     *  tick as the v-model flip, regardless of who flipped it — clearing
+     *  only inside onUpdate:modelValue would miss programmatic closes and
+     *  the test would pass vacuously (R1 finding: the hold was never
+     *  exercised). */
+    closeWithTeardown: () => {
+      open.value = false;
+      lines.value = [];
+    },
+    bodyText: () => document.querySelector(".hk-modal-body-inner")?.textContent ?? "",
+    frameEl: () => document.querySelector<HTMLElement>(".hk-modal-content"),
+  };
+}
+
+describe("HkModal close-fold content hold", () => {
+  it("folds over the last live content even when the consumer clears state on close", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    const rig = await mountRig(["alpha", "beta"]);
+
+    // Open the surface to rest (flip timer 120ms + duration 300 + slack).
+    rig.open.value = true;
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.bodyText()).toBe("alphabeta");
+
+    // Close with the SAME-TICK teardown — this is the exact moment the
+    // hold must earn its keep (without it the body blanks immediately).
+    rig.closeWithTeardown();
+    await vi.advanceTimersByTimeAsync(150); // mid-leave (past the flip)
+    expect(rig.frameEl()).not.toBeNull();
+    // THE contract: the fold plays over the ORIGINAL content — the
+    // same-tick teardown must not blank the window mid-fold.
+    expect(rig.bodyText()).toBe("alphabeta");
+
+    // The leave settles and the DOM goes away with it.
+    await vi.advanceTimersByTimeAsync(600);
+    expect(rig.frameEl()).toBeNull();
+    expect(rig.bodyText()).toBe("");
+  });
+
+  it("a reopen interrupt drops the hold and serves live content again", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    const rig = await mountRig(["alpha", "beta"]);
+
+    rig.open.value = true;
+    await vi.advanceTimersByTimeAsync(600);
+    const frameBeforeClose = rig.frameEl();
+
+    // Close with the same-tick teardown, then interrupt mid-leave.
+    rig.closeWithTeardown();
+    await vi.advanceTimersByTimeAsync(150);
+    expect(rig.bodyText()).toBe("alphabeta");
+
+    // Reopen with FRESH content — the hold releases with the phase.
+    rig.open.value = true;
+    rig.setLines(["gamma"]);
+    await vi.advanceTimersByTimeAsync(30);
+    expect(rig.bodyText()).toBe("gamma");
+
+    // …and the same element survives the reversal (no remount flash).
+    expect(rig.frameEl()).toBe(frameBeforeClose);
+    await vi.advanceTimersByTimeAsync(800);
+    expect(rig.bodyText()).toBe("gamma");
+    expect(rig.frameEl()).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,169 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkModal from "./HkModal";
+
+/**
+ * Source contract for the leave-window height pin (chest field report
+ * 2026-09-16): the close fold owns the frame's geometry for the whole
+ * leave, so HkModal must KEEP the size morph's pin through closingFrom →
+ * closingTo (morph.hold()) and only release it on the finalize edge. The
+ * composable-level semantics are pinned by useSizeMorph.test.ts; this file
+ * pins the HkModal INTEGRATION — the wiring bug class (calling stop()
+ * instead of hold()) leaves the composable tests green while every real
+ * modal folds over a resizing frame.
+ *
+ * happy-dom has no layout engine, so the frame's offsetHeight is stubbed
+ * at the HTMLElement prototype level BEFORE mount — the morph's
+ * openingFrom-tick arm then measures 500px and pins it, and every
+ * mid-leave assertion reads the inline height string directly.
+ */
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(async () => {
+  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;
+  });
+}
+
+/** Prototype-level layout stub: every element measures `layoutH` tall.
+ *  Mutable so a test can simulate content growth mid-enter. */
+let layoutH = 500;
+function stubLayout(initial: number): void {
+  layoutH = initial;
+  Object.defineProperty(HTMLElement.prototype, "offsetHeight", {
+    configurable: true,
+    get: () => layoutH,
+  });
+}
+
+function restoreLayout(): void {
+  delete (HTMLElement.prototype as { offsetHeight?: number }).offsetHeight;
+}
+
+interface Rig {
+  open: { value: boolean };
+  pinHeight: () => string;
+  frameEl: () => HTMLElement | null;
+  clickClose: () => void;
+}
+
+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: "pin-test",
+          "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+        }, { default: () => h("div", "content") });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  await nextTick();
+
+  return {
+    open,
+    pinHeight: () => document.querySelector<HTMLElement>(".hk-modal-content")?.style.height ?? "",
+    frameEl: () => document.querySelector<HTMLElement>(".hk-modal-content"),
+    clickClose: () => {
+      const btn = document.querySelector<HTMLElement>(".hk-modal-close");
+      btn?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    },
+  };
+}
+
+describe("HkModal leave-window height pin", () => {
+  it("keeps the morph pin through the whole leave and releases at finalize", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    stubLayout(500);
+    try {
+      const rig = await mountRig();
+
+      // Open to rest: the enter-edge arm measured 500px and pinned it.
+      rig.open.value = true;
+      await vi.advanceTimersByTimeAsync(600);
+      expect(rig.frameEl()).not.toBeNull();
+      expect(rig.pinHeight()).toBe("500px");
+
+      // Close through the modal's own close button (the real path).
+      rig.clickClose();
+      await vi.advanceTimersByTimeAsync(150); // mid-leave, past the flip
+      expect(rig.frameEl()).not.toBeNull();
+      // THE contract: the pin survives the whole closing window — a
+      // stop()-instead-of-hold() wiring drops it here and the fold plays
+      // over a frame handed back to `height: auto`.
+      expect(rig.pinHeight()).toBe("500px");
+
+      // Still pinned late in the leave.
+      await vi.advanceTimersByTimeAsync(250);
+      if (rig.frameEl()) {
+        expect(rig.pinHeight()).toBe("500px");
+      }
+
+      // Finalize: the surface unmounts (the release write is invisible).
+      await vi.advanceTimersByTimeAsync(600);
+      expect(rig.frameEl()).toBeNull();
+    } finally {
+      restoreLayout();
+    }
+  });
+
+  it("flushes growth deferred through the enter with an open-edge remeasure", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    stubDurations();
+    stubLayout(400);
+    try {
+      const rig = await mountRig();
+
+      // Open: the enter-edge arm pins the enter-time height (400px).
+      rig.open.value = true;
+      await vi.advanceTimersByTimeAsync(150); // mid-enter, past the flip
+      expect(rig.pinHeight()).toBe("400px");
+
+      // Content grows mid-enter — with the enter's defer gate the pin
+      // must NOT chase it (the choreography's height-relative geometry
+      // stays put; in a real browser the RO fires and is deferred too).
+      layoutH = 700;
+      await vi.advanceTimersByTimeAsync(50);
+      expect(rig.pinHeight()).toBe("400px");
+
+      // The open edge flushes the deferred growth one tick after the
+      // transition classes clear — the pin lands at the grown height.
+      await vi.advanceTimersByTimeAsync(450);
+      expect(rig.pinHeight()).toBe("700px");
+
+      // Sanity: the surface really rested open before the flush assertion.
+      expect(rig.frameEl()).not.toBeNull();
+    } finally {
+      restoreLayout();
+    }
+  });
+});

package/src/components/HkModal.tsx

@@ -21,6 +21,7 @@ import { scheduleFrame, type AnimationHandle } from "../runtime/animationBus";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
+import { useSurfaceContentHold } from "../composables/useSurfaceContentHold";
 import { useSizeMorph } from "../composables/useSizeMorph";
 import HButton from "./HkButton";
 import HFab from "./HkFab";
@@ -201,8 +202,19 @@ export default defineComponent({
      *  useSizeMorph). */
     const innerRef = ref<HTMLElement>();
     // Content-driven size morphing: the frame follows content growth with
-    // the height transition instead of snapping (see useSizeMorph).
-    const morph = useSizeMorph(contentRef, innerRef);
+    // the height transition instead of snapping (see useSizeMorph). The
+    // gate freezes resize-driven re-measurement through the enter unfold:
+    // the choreography's geometry is height-relative (translateY 5% +
+    // bottom-10% clip of the frame height), so content streaming in
+    // mid-enter would otherwise recompute the pixel geometry under the
+    // running animation (2026-09-16 chest field report — the frame
+    // snapped 459→697px mid-unfold). The open phase edge flushes the
+    // deferred growth with an animated remeasure.
+    const morph = useSizeMorph(contentRef, innerRef, {
+      deferRemeasure: () =>
+        machine.phase.value === "openingFrom" ||
+        machine.phase.value === "openingTo",
+    });
     let previouslyFocused: HTMLElement | null = null;
     let unmounted = false;
 
@@ -347,13 +359,29 @@ export default defineComponent({
             backGuard.push();
           }
           surfTrack.run();
+          // Arm the size morph WITH the enter (one tick later, once the
+          // mounting patch landed): the pin locks the frame's height for
+          // the whole unfold so late-streaming content cannot move the
+          // choreography mid-flight (see the morph's gate above). The
+          // zero-duration fast paths reach `open` before the tick — the
+          // open branch's own start() covers them.
+          void nextTick(() => {
+            const p = machine.phase.value;
+            if (p === "openingFrom" || p === "openingTo") morph.start();
+          });
         } else if (to === "open") {
           surfTrack.cancel();
           onAfterEnter();
-          // Size morphs arm once the open choreography finished —
-          // pinning during enter would fight the reveal's transform
-          // transition.
+          // Idempotent re-arm for the fast paths (see openingFrom); the
+          // morph is usually armed already by the enter-edge tick.
           morph.start();
+          // Flush the growth deferred through the unfold. One tick later
+          // the transition classes are off the frame, so the base height
+          // transition animates the pin change instead of the enter's
+          // transform/clip-only transition list swallowing it as a snap.
+          void nextTick(() => {
+            if (machine.phase.value === "open") morph.remeasure();
+          });
         } else if (to === "closingFrom") {
           // Close-request bookkeeping (was the watcher's close arm): the
           // registries forget the surface at request time; the finalize
@@ -361,8 +389,18 @@ export default defineComponent({
           surfTrack.run();
           overlay.close();
           backGuard.release();
-          // Release the pinned height so the leave owns the frame.
-          morph.stop();
+          // Keep the height PIN through the leave: the fold owns the
+          // frame's geometry and a mid-leave content change must not
+          // resize it. The pin releases on the finalize edge below.
+          morph.hold();
+          // The leave must not chase a live tail — the window folds over
+          // the final frame of content, not over a moving stream. A
+          // self-updating child inside the held content could still
+          // mutate the DOM mid-fold (the observer would re-pin the
+          // scroll), so auto-follow tears down with the close request;
+          // a reopen interrupt re-arms it at the open edge
+          // (onAfterEnter → setupAutoFollow).
+          teardownAutoFollow();
         } else if (
           to === "closed" &&
           (from === "closingFrom" || from === "closingTo") &&
@@ -373,6 +411,10 @@ export default defineComponent({
           event !== "UNMOUNT"
         ) {
           surfTrack.cancel();
+          // Bookkeeping reset for the NEXT open cycle: zeroes the morph's
+          // pin so the next enter starts clean (release() writes on the
+          // invisible, about-to-unmount frame — no visual effect).
+          morph.stop();
           onAfterLeaveFinalize();
         }
         // to === "closed" via UNMOUNT: teardown is owned by
@@ -743,6 +785,8 @@ export default defineComponent({
       return null;
     }
 
+    const contentHold = useSurfaceContentHold(machine.phase);
+
     return () => {
       if (!machine.mounted.value) return null;
 
@@ -773,7 +817,12 @@ export default defineComponent({
                   onClick={onContentClick}
                   tabindex={-1}
                 >
-                  {headerShown && (
+                  {/* Content hold: while the machine is in a closing
+                      phase this serves the last live-rendered children,
+                      so a consumer tearing down its state on close
+                      cannot blank the window mid-fold. */}
+                  {contentHold.hold(() => [
+                  headerShown ? (
                     <>
                       <div
                         class={[
@@ -807,7 +856,7 @@ export default defineComponent({
                         <div class="hk-modal-subheader">{slots.header()}</div>
                       )}
                     </>
-                  )}
+                  ) : null,
                   <div ref={bodyRef} class="hk-modal-body">
                     <div
                       ref={scrollContainerRef}
@@ -851,8 +900,9 @@ export default defineComponent({
                         )}
                       </>
                     )}
-                  </div>
-                  {renderFooter()}
+                  </div>,
+                  renderFooter(),
+                  ])}
                 </div>
           </div>
         </Teleport>

package/src/composables/useSizeMorph.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick, ref } from "vue";
 
-import { useSizeMorph } from "./useSizeMorph";
+import { useSizeMorph, type SizeMorphOptions } from "./useSizeMorph";
 
 /** Injectable ResizeObserver: captures the callback so tests can fire
  *  content changes deterministically (happy-dom's own RO never fires —
@@ -35,10 +35,11 @@ interface Harness {
   setContentNatural(height: number): void;
   start(): void;
   stop(): void;
+  hold(): void;
   remeasure(): void;
 }
 
-function mountHarness(initialHeight: number, initialContentHeight = 0): Harness {
+function mountHarness(initialHeight: number, initialContentHeight = 0, options?: SizeMorphOptions): Harness {
   const container = document.createElement("div");
   document.body.appendChild(container);
   let frameEl: HTMLElement | null = null;
@@ -50,7 +51,7 @@ function mountHarness(initialHeight: number, initialContentHeight = 0): Harness
     setup() {
       const frame = ref<HTMLElement | null>(null);
       const content = ref<HTMLElement | null>(null);
-      morph = useSizeMorph(frame, content);
+      morph = useSizeMorph(frame, content, options);
       return () =>
         h("div", [
           h("div", {
@@ -96,6 +97,7 @@ function mountHarness(initialHeight: number, initialContentHeight = 0): Harness
     },
     start: () => morph!.start(),
     stop: () => morph!.stop(),
+    hold: () => morph!.hold(),
     remeasure: () => morph!.remeasure(),
   };
 }
@@ -427,3 +429,73 @@ describe("useSizeMorph clip reveal", () => {
     expect(h.frame.style.clipPath).toBe("");
   });
 });
+
+// ── Leave-window hold + enter-window defer (2026-09-16 modal report) ──
+// The modal's close fold owns the frame's geometry for the whole leave:
+// hold() keeps the pin (a mid-leave content change must not resize the
+// folding frame) and the reopen-interrupt path animates FROM that pin.
+// The enter unfold is height-relative geometry (translateY 5% + bottom
+// 10% clip of the frame height), so deferRemeasure freezes resize-driven
+// re-pins through the enter and the open edge flushes them.
+
+describe("useSizeMorph hold + deferRemeasure", () => {
+  it("hold keeps the pin and stops observing (leave-window stability)", () => {
+    const h = mountHarness(120, 100);
+    h.start();
+    expect(h.frame.style.height).toBe("120px");
+
+    h.hold();
+    // The pin STAYS (unlike stop's release to auto)…
+    expect(h.frame.style.height).toBe("120px");
+    // …and the observer is disarmed: no content change can re-pin.
+    expect(FakeResizeObserver.instances[0]!.disconnected).toBe(true);
+  });
+
+  it("stop after a hold still releases (full-close bookkeeping)", () => {
+    const h = mountHarness(120, 100);
+    h.start();
+    h.hold();
+    h.stop();
+    expect(h.frame.style.height).toBe("");
+  });
+
+  it("start after a hold re-arms and animates from the held pin", () => {
+    const h = mountHarness(120, 100);
+    h.start();
+    h.hold();
+    // Reopen interrupt: the natural height changed while held — the next
+    // arm re-pins to it (from the held 120px, per the dance's re-pin).
+    h.setNatural(200);
+    h.start();
+    expect(h.frame.style.height).toBe("200px");
+    // A FRESH observer owns the new cycle.
+    expect(FakeResizeObserver.instances.length).toBe(2);
+    expect(FakeResizeObserver.instances[1]!.disconnected).toBe(false);
+  });
+
+  it("deferRemeasure freezes RO-driven re-pins; explicit remeasure flushes", async () => {
+    let gated = true;
+    const h = mountHarness(120, 100, { deferRemeasure: () => gated });
+    h.start();
+    // The initial pin is NOT gated (arming must pin immediately).
+    expect(h.frame.style.height).toBe("120px");
+
+    // Content streams in mid-enter: the RO fires but the pin must not
+    // move — the unfold's height-relative geometry stays put.
+    h.setNatural(160);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("120px");
+
+    // The open edge flushes the deferred growth.
+    h.remeasure();
+    expect(h.frame.style.height).toBe("160px");
+
+    // Gate off: RO-driven updates flow again.
+    gated = false;
+    h.setNatural(200);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("200px");
+  });
+});

package/src/composables/useSizeMorph.ts

@@ -17,16 +17,41 @@ export interface SizeMorph {
   /** Arm the morph: observe the content and pin the frame's natural
    *  height on every change. Call once the surface finished its open
    *  enter transition — pinning during enter would override the
-   *  choreography's own height animation. */
+   *  choreography's own height animation. (Surfaces whose enter is
+   *  height-INDEPENDENT — HkModal's clip+transform unfold — may arm
+   *  earlier with a `deferRemeasure` gate, see below.) */
   start(): void;
   /** Disarm the morph and release the frame to `height: auto` — call
    *  before a surface's leave/close so the exit animation owns the
    *  height again. */
   stop(): void;
+  /** Leave-window hold: disarm the observer/timers and cancel any
+   *  mid-flight reveal like stop(), but KEEP the height pin — the close
+   *  choreography owns the frame's geometry through the whole leave and
+   *  the pin keeps it stable (a mid-leave content change must not resize
+   *  the folding frame). The next start() re-arms and, because the pin
+   *  was kept, a re-pin to the SAME natural height is a no-op (the
+   *  typical reopen-interrupt case — held content is unchanged, delta
+   *  zero; a re-pin to a CHANGED natural while an enter's transition
+   *  classes own the frame lands without a height animation, i.e. snaps
+   *  — acceptable, the enter's own choreography owns that moment). */
+  hold(): void;
   /** Re-measure and pin now (resize events, open flows). */
   remeasure(): void;
 }
 
+export interface SizeMorphOptions {
+  /** While this returns true, resize-driven re-measurements are deferred
+   *  (the current pin stays). HkModal freezes the frame's height during
+   *  the enter unfold: the choreography's translateY(5%) + bottom-10%
+   *  clip are fractions of the frame height, so late-streaming content
+   *  resizing the frame mid-enter would recompute the geometry under the
+   *  running animation (2026-09-16 chest field report — the frame snapped
+   *  459→697px mid-unfold). The caller flushes the deferred growth with
+   *  an explicit remeasure() at the open edge. */
+  deferRemeasure?: () => boolean;
+}
+
 /**
  * useSizeMorph — smooth size morphing for content-hugging surfaces.
  *
@@ -71,6 +96,7 @@ export interface SizeMorph {
 export function useSizeMorph(
   frame: Ref<HTMLElement | null | undefined>,
   content: Ref<HTMLElement | null | undefined>,
+  options: SizeMorphOptions = {},
 ): SizeMorph {
   let ro: ResizeObserver | null = null;
   let raf = 0;
@@ -155,7 +181,13 @@ export function useSizeMorph(
    *  finished) frame — the only moment guaranteed free of transition-class
    *  flex rules. Never calibrate from a remeasure sample: the first
    *  remeasure can itself be the contaminated one (a frozen enter leaves
-   *  the flex rules behind when the surface is mid-repair). */
+   *  the flex rules behind when the surface is mid-repair). HkModal's
+   *  reopen-interrupt arm violates the precondition on purpose (it
+   *  calibrates a pinned, enter-classed frame): benign today because no
+   *  current enter/leave class carries height/flex rules (the inline pin
+   *  beats the mobile sheet's static height:auto), and the contamination
+   *  guard below degrades any future SCSS regression to a dropped pin
+   *  rather than a corrupted one. */
   function calibrate(): void {
     const f = frame.value;
     const c = content.value;
@@ -271,6 +303,10 @@ export function useSizeMorph(
   }
 
   function onResize(): void {
+    // Frozen window (e.g. HkModal's enter unfold): keep the current pin;
+    // the caller flushes the accumulated change with an explicit
+    // remeasure() once the choreography hands the height back.
+    if (options.deferRemeasure?.()) return;
     // Debounce the choreography: content can change in a burst (a list
     // transition shrinking rows over several frames, a textarea growing
     // per keystroke). Dancing to every intermediate would restart the
@@ -304,7 +340,7 @@ export function useSizeMorph(
     remeasure();
   }
 
-  function stop(): void {
+  function hold(): void {
     if (!armed) return;
     armed = false;
     ro?.disconnect();
@@ -320,6 +356,17 @@ export function useSizeMorph(
     // The next start() re-calibrates against whatever chrome that open
     // cycle carries.
     chromeAllowance = CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
+    stopReveal();
+    // Deliberately no release(): the pin stays on the frame so the close
+    // fold plays on a stable box, and a reopen interrupt animates from it.
+  }
+
+  function stop(): void {
+    // Disarm only when armed — after hold() the morph is already
+    // disarmed and only the release is owed. release() is internally
+    // guarded (no pin / no frame → no-op), so a never-armed stop()
+    // stays the no-op it always was.
+    if (armed) hold();
     release();
   }
 
@@ -330,5 +377,5 @@ export function useSizeMorph(
     stopReveal();
   });
 
-  return { start, stop, remeasure };
+  return { start, stop, hold, remeasure };
 }

package/src/composables/useSurfaceContentHold.ts

@@ -0,0 +1,58 @@
+import { computed, watch, type ComputedRef } from "vue";
+
+import type { SurfacePhase } from "../runtime/surfaceMachine";
+
+/**
+ * useSurfaceContentHold — keep a surface's last live content on screen
+ * for the whole close fold.
+ *
+ * Consumers routinely tear down the very state that feeds a window's body
+ * the moment its v-model flips false (clear-on-close watchers, store
+ * resets, socket disconnects). Without a hold, the leave transition then
+ * plays on an emptied shell: the frame collapses to its chrome BEFORE the
+ * fold starts (chest TodoLogModal, 2026-09-16 field report — the 697px
+ * conversation window became a 200px stub in the same tick as the close).
+ *
+ * While the machine is in a closing phase this serves the most recent
+ * live-rendered children instead of re-invoking the slots, so the fold
+ * always plays over the content the user was actually looking at. Vue's
+ * patch skips identical vnode references, so the held DOM is never
+ * re-patched during the close; child components with their own store
+ * subscriptions may still self-update (harmless — the failure mode under
+ * repair is content VANISHING, not content ticking).
+ *
+ * The hold releases the moment the surface leaves a closing phase: a
+ * reopen interrupt (closing → openingFrom) serves live slots again, and
+ * `closed` drops the cache so a closed surface retains nothing.
+ */
+export function useSurfaceContentHold(phase: ComputedRef<SurfacePhase>) {
+  const closing = computed(
+    () => phase.value === "closingFrom" || phase.value === "closingTo",
+  );
+
+  let held: unknown = null;
+
+  // A closed surface renders nothing — the cache would only pin a dead
+  // vnode tree. Drop it on the closed edge.
+  watch(phase, (p) => {
+    if (p === "closed") held = null;
+  });
+
+  /**
+   * Wrap one render-region producer: live while opening/open, frozen
+   * while closing. The first closing render falls through to live
+   * production when no snapshot exists (the surface opened directly into
+   * a close is not a real path, but the guard keeps the contract total).
+   */
+  function hold<T>(produce: () => T): T {
+    if (closing.value) {
+      if (held !== null) return held as T;
+      return produce();
+    }
+    const next = produce();
+    held = next;
+    return next;
+  }
+
+  return { hold, closing };
+}

package/src/composables/useSurfaceMachine.test.ts

@@ -240,6 +240,56 @@ describe("useSurfaceMachine driver", () => {
     expect(rig.edges.length).toBe(edgesAtRest);
   });
 
+  it("transitionstart re-arms the deadline once so a late-latched transition completes", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", () => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    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;
+    });
+    const rig = mountRig(true);
+    rig.send("OPEN");
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(130); // flip timer forced the FLIP
+    expect(rig.phase()).toBe("openingTo");
+    // Flip-relative deadline: 300 + 80 → settles at t≈500 unless the
+    // browser reports the transition ACTUALLY started late (frame
+    // starvation latches the transition on the first post-flip frame).
+    const panel = document.querySelector<HTMLElement>(".panel")!;
+
+    // t=330: the transition latches 200ms after the flip.
+    await vi.advanceTimersByTimeAsync(200);
+    panel.dispatchEvent(new Event("transitionstart", { bubbles: true }));
+    // → deadline re-armed to 330 + 300 + 80 = 710.
+
+    // t=390: a bubbled report from a NON-layer descendant (target filter)
+    // and a duplicate report on the panel (one re-arm per phase) are
+    // both ignored — either would push the deadline to 770.
+    await vi.advanceTimersByTimeAsync(60);
+    const child = document.createElement("span");
+    panel.appendChild(child);
+    child.dispatchEvent(new Event("transitionstart", { bubbles: true }));
+    panel.dispatchEvent(new Event("transitionstart", { bubbles: true }));
+
+    // The flip-relative deadline (t=500) passes without settling — the
+    // re-arm is real…
+    await vi.advanceTimersByTimeAsync(300); // t=690
+    expect(rig.phase()).toBe("openingTo");
+    // …and the latch-relative deadline completes the open (t=710), ahead
+    // of where a second re-arm would have put it (t=770).
+    await vi.advanceTimersByTimeAsync(30); // t=720
+    expect(rig.phase()).toBe("open");
+    await nextTick();
+    expect(scrimClasses(rig)).toEqual([]);
+    // No late timers fire afterwards.
+    const edgesAtRest = rig.edges.length;
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(rig.phase()).toBe("open");
+    expect(rig.edges.length).toBe(edgesAtRest);
+  });
+
   it("UNMOUNT from any phase clears every clock and walks to closed", async () => {
     vi.useFakeTimers();
     const rig = mountRig();

package/src/composables/useSurfaceMachine.ts

@@ -58,7 +58,10 @@ export interface SurfaceMachine {
  * - The ONLY correctness clock is setTimeout: every animation phase arms
  *   exactly one deadline timer; the frame flip is double-rAF (smooth)
  *   with a flip timer as the starved fallback. Duplicate FLIPs are
- *   absorbed by the table (idempotent self-loops).
+ *   absorbed by the table (idempotent self-loops). transitionend (TEND)
+ *   settles a phase early; transitionstart re-arms the deadline once so
+ *   a frame-starved, late-latched transition still completes — both are
+ *   advisory optimizations, never the correctness clock.
  * - Phase changes clear every pending timer/rAF before arming the next
  *   phase's — at most one flip + one deadline exist at any moment, so
  *   timers cannot leak or fire stale (the machine has no "late
@@ -257,6 +260,7 @@ export function useSurfaceMachine(options: SurfaceMachineOptions): SurfaceMachin
         if (measured > 0) {
           rearmDeadline(measured + slack);
           armTend(measured);
+          armStart(measured);
         } else {
           completeNow();
         }
@@ -264,6 +268,36 @@ export function useSurfaceMachine(options: SurfaceMachineOptions): SurfaceMachin
     }
   }
 
+  /** transitionstart re-arm: under frame starvation the CSS transition
+   *  only LATCHES when the first frame after the flip is produced, while
+   *  this phase's deadline was armed at the flip — a transition starting
+   *  300ms late would be cut mid-flight by its own deadline, snapping the
+   *  surface to rest (2026-09-16 chest field report: the desktop modal
+   *  enter freezes at its low/transparent from-pair, then jumps). When
+   *  the browser reports the transition actually started, re-arm the
+   *  deadline from that moment so a late-started transition still runs
+   *  to completion. A never-started transition (frames never come) fires
+   *  nothing — the flip-relative deadline stays the bound (A2), so this
+   *  changes settle latency only when the animation genuinely runs.
+   *  One re-arm per layer per phase: every animated property fires its
+   *  own transitionstart on the same frame. */
+  function armStart(expectedMs: number): void {
+    const seen = new Set<HTMLElement>();
+    for (const layer of options.layers) {
+      const el = layer.el?.();
+      if (!el || !el.isConnected || seen.has(el)) continue;
+      seen.add(el);
+      let rearmed = false;
+      const onStart = (e: TransitionEvent) => {
+        if (e.target !== el || rearmed) return;
+        rearmed = true;
+        rearmDeadline(expectedMs + slack);
+      };
+      el.addEventListener("transitionstart", onStart);
+      tendCleanups.push(() => el.removeEventListener("transitionstart", onStart));
+    }
+  }
+
   function send(event: SurfaceEventType): void {
     const from = phase.value;
     const to = surfaceTransition(from, event);