@celestia-island/hikari 0.55.0 → 0.55.2

package/src/components/HkModalBreadcrumb.test.tsx

@@ -218,16 +218,20 @@ describe("HkModalBreadcrumb label budget", () => {
     expect(labels()).toEqual(["abcdefghijklmnopqrst", "abcdefghijklmnopqr…"]);
   });
 
-  it("keeps the whole layer name for assistive tech when it cuts", async () => {
+  it("keeps the whole layer name on a cut label", async () => {
     manager.register("modal", true, LONG);
     manager.register("modal", true, "细节");
     await mountStrip();
     const nav = strip()!;
-    const first = nav.querySelector<HTMLElement>(
-      ":scope > .hk-modal-breadcrumb-crumb .hk-modal-breadcrumb-item",
+    const first = nav.querySelector<HTMLButtonElement>(
+      ":scope > .hk-modal-breadcrumb-crumb button.hk-modal-breadcrumb-item",
     )!;
-    expect(first.querySelector('[aria-hidden="true"]')!.textContent).toBe(LONG_TAIL);
-    expect(first.querySelector(".hk-modal-breadcrumb-sr-only")!.textContent).toBe(LONG);
+    // Rendered cut, announced whole: a truncated string is not a name.
+    expect(first.textContent).toBe(LONG_TAIL);
+    expect(first.getAttribute("aria-label")).toBe(LONG);
+    expect(first.getAttribute("aria-expanded")).toBe("false");
+    // An uncut label stays plain text — no new interaction surface.
+    expect(nav.querySelectorAll("button.hk-modal-breadcrumb-item")).toHaveLength(1);
     // The measurement clone must never join the a11y tree.
     expect(
       nav.querySelector(".hk-modal-breadcrumb-measure")!.getAttribute("aria-hidden"),
@@ -252,6 +256,251 @@ describe("HkModalBreadcrumb label budget", () => {
     }
   });
 
+  it("reveals a cut label on the same crumb's popover", async () => {
+    setViewport(1200);
+    manager.register("modal", true, LONG);
+    manager.register("modal", true, "细节");
+    await mountStrip();
+    const cut = () =>
+      strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!;
+    expect(document.body.querySelector(".hk-popover-panel")).toBeNull();
+
+    cut().click();
+    await nextTick();
+    await nextTick();
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel).toBeTruthy();
+    // Desktop: an anchored popover carrying the WHOLE name, wrapping.
+    expect(panel.classList.contains("hk-is-sheet")).toBe(false);
+    expect(panel.querySelector(".hk-modal-breadcrumb-reveal")!.textContent).toBe(LONG);
+    expect(cut().getAttribute("aria-expanded")).toBe("true");
+
+    // Tapping the same crumb again puts it away.
+    cut().click();
+    await nextTick();
+    await nextTick();
+    expect(cut().getAttribute("aria-expanded")).toBe("false");
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
+  });
+
+  it("docks the revealed name as a bottom sheet on mobile", async () => {
+    setViewport(360);
+    manager.register("modal", true, LONG);
+    manager.register("modal", true, "细节");
+    await mountStrip();
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    // Settle before asserting: the sheet's own registration re-folds the
+    // strip, and the surface must outlive that (see the phone test above).
+    await until(() => document.body.querySelector(".hk-modal-breadcrumb-reveal") !== null);
+    await until(() => false, 150);
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel.classList.contains("hk-is-sheet")).toBe(true);
+    expect(panel.querySelector(".hk-modal-breadcrumb-reveal")!.textContent).toBe(LONG);
+    // It registers as a window layer like any other blocking sheet, and the
+    // name it reveals is the name it carries.
+    const blocking = [...manager.registry.value.values()].filter((entry) => entry.blocking);
+    expect(blocking.map((entry) => entry.title)).toContain(LONG);
+  });
+
+  it("keeps the revealed name open on a phone, where its own sheet moves the fold", async () => {
+    // Opening the reveal docks a blocking sheet, the sheet joins the stack
+    // the strip lists, and the tail is re-decided underneath: the tapped
+    // crumb can end up behind the trigger in the same frame. The surface
+    // belongs to the LAYER, not to the fold — closing it there made the
+    // reveal cancel itself on every phone (2026-09-16 review).
+    setViewport(360);
+    manager.register("modal", true, LONG); // cut, and visible before the tap
+    manager.register("modal", true, "第二层");
+    manager.register("modal", true, "第三层");
+    await mountStrip();
+    const crumb = strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!;
+    expect(crumb.getAttribute("aria-label")).toBe(LONG);
+
+    crumb.click();
+    await until(() => document.body.querySelector(".hk-modal-breadcrumb-reveal") !== null);
+    // Let every deferred consequence land (the sheet's registration, the
+    // re-measure, the fold) and assert the surface is STILL there.
+    await until(() => false, 200);
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")!.textContent).toBe(LONG);
+    expect(document.body.querySelector<HTMLElement>(".hk-popover-panel")!.classList.contains("hk-is-sheet")).toBe(true);
+  });
+
+  it("closes the reveal when its layer stops being cut (retitle)", async () => {
+    setViewport(1200);
+    const layer = manager.register("modal", true, LONG);
+    manager.register("modal", true, "细节");
+    await mountStrip();
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeTruthy();
+
+    // The owner renames the window to something that fits: the crumb is
+    // plain text again, so an open panel would be anchored to nothing while
+    // showing a name that no longer exists.
+    manager.setTitle(layer.id, "短标题");
+    await nextTick();
+    await nextTick();
+    expect(strip()!.querySelectorAll("button.hk-modal-breadcrumb-item")).toHaveLength(0);
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
+  });
+
+  it("follows a retitle that is still cut", async () => {
+    setViewport(1200);
+    const layer = manager.register("modal", true, LONG);
+    manager.register("modal", true, "细节");
+    await mountStrip();
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await nextTick();
+    await nextTick();
+    const longer = "另一个非常长的层级标题占位一二三四五";
+    manager.setTitle(layer.id, longer);
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")!.textContent).toBe(longer);
+  });
+
+  it("does not reopen the reveal after the strip comes back", async () => {
+    // The strip unmounts when the stack drops to one layer: the reveal goes
+    // with it (its surface is rendered inside), and a stale `revealed` would
+    // otherwise spring back — anchored to the element that no longer exists
+    // — the moment another window opens (review round two).
+    setViewport(1200);
+    manager.register("modal", true, LONG);
+    const other = manager.register("modal", true, "细节");
+    await mountStrip();
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeTruthy();
+
+    manager.unregister(other.id); // one layer left: the strip goes away
+    await nextTick();
+    expect(strip()).toBeNull();
+    manager.register("modal", true, "新来的层级");
+    await nextTick();
+    await nextTick();
+    expect(strip()).not.toBeNull();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
+  });
+
+  it("closes the anchored reveal when its crumb folds behind the trigger", async () => {
+    // A fold that unmounts the anchor would leave the anchored panel
+    // measuring a detached 0×0 rect on its next reposition, which parks it
+    // in the viewport corner (review round two). The sheet form needs no
+    // anchor and keeps the name (see the phone test above).
+    setViewport(1200);
+    manager.register("modal", true, LONG);
+    manager.register("modal", true, "第二个很长的层级标题占位一二三");
+    manager.register("modal", true, "第三个很长的层级标题占位一二三");
+    manager.register("modal", true, "细节");
+    await mountStrip();
+    expect(more()).toBeNull();
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeTruthy();
+
+    // More windows push the tapped crumb behind the trigger (the fold is
+    // re-decided a tick after the labels land, then rendered).
+    STACK_TITLES.forEach((title) => manager.register("modal", true, title));
+    await until(() => more() !== null, 300);
+    expect(more()).not.toBeNull();
+    expect(strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")).not.toBeNull();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
+  });
+
+  it("closes an open reveal when the folded-layers menu opens", async () => {
+    // On a phone the strip paints above the sheet's scrim, so its trigger
+    // stays tappable while a reveal is docked (review round two). The menu
+    // must take over from the reveal, not stack on top of it: one Escape,
+    // one surface.
+    setViewport(360);
+    [LONG, LONG, LONG, LONG].forEach((title, i) =>
+      manager.register("modal", true, `${i}：${title}`),
+    );
+    await mountStrip();
+    expect(more()).not.toBeNull();
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await until(() => document.body.querySelector(".hk-modal-breadcrumb-reveal") !== null);
+    expect(more()!.getAttribute("aria-expanded")).toBe("false");
+
+    more()!.click();
+    await nextTick();
+    await nextTick();
+    expect(more()!.getAttribute("aria-expanded")).toBe("true");
+    // The reveal's own sheet plays its leave out before the DOM drops it —
+    // and with nothing closing it, it never does (this assertion is what
+    // pins the symmetric close).
+    await until(() => document.body.querySelector(".hk-modal-breadcrumb-reveal") === null, 900);
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
+  });
+
+  it("closes whichever surface is open on Escape", async () => {
+    setViewport(1200);
+    STACK_TITLES.forEach((title) => manager.register("modal", true, title));
+    manager.register("modal", true, "细节");
+    await mountStrip();
+
+    // The folded-layers menu (anchored: its panel takes no focus, so the
+    // strip owns the key).
+    more()!.click();
+    await nextTick();
+    await nextTick();
+    expect(more()!.getAttribute("aria-expanded")).toBe("true");
+    document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await nextTick();
+    expect(more()!.getAttribute("aria-expanded")).toBe("false");
+
+    // The revealed name.
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeTruthy();
+    document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
+  });
+
+  it("closes the reveal when its layer leaves the stack", async () => {
+    setViewport(1200);
+    const layer = manager.register("modal", true, LONG);
+    manager.register("modal", true, "细节");
+    await mountStrip();
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeTruthy();
+
+    // The window closes under the open panel: there is no name left to
+    // reveal.
+    manager.unregister(layer.id);
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
+  });
+
+  it("opens the reveal instead of the hidden-layers menu", async () => {
+    // The two surfaces are never open together: tapping a crumb closes the
+    // menu it was opened from (its leave plays out, so the logical state is
+    // what the assertion reads).
+    setViewport(800);
+    STACK_TITLES.forEach((title) => manager.register("modal", true, title));
+    manager.register("modal", true, "细节");
+    await mountStrip();
+    more()!.click();
+    await nextTick();
+    await nextTick();
+    expect(menuRows().length).toBeGreaterThan(0);
+    expect(more()!.getAttribute("aria-expanded")).toBe("true");
+
+    strip()!.querySelector<HTMLButtonElement>("button.hk-modal-breadcrumb-item")!.click();
+    await nextTick();
+    await nextTick();
+    expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeTruthy();
+    expect(more()!.getAttribute("aria-expanded")).toBe("false");
+  });
+
   it("honours a narrower budget from the host", async () => {
     manager.register("modal", true, "自动化测试流水线冒烟");
     manager.register("modal", true, "细节");

package/src/components/HkModalBreadcrumb.tsx

@@ -14,6 +14,7 @@ import { useReportedTransition } from "../composables/useReportedTransition";
 import { scheduleEvery } from "../runtime/animationBus";
 import { ancestorZoom } from "../runtime/cssZoom";
 import { viewportGutterPx } from "../runtime/viewportGutter";
+import { useBreakpoint } from "../runtime/useBreakpoint";
 import { clampToDisplayWidth, displayWidthUnits, ELLIPSIS } from "../runtime/displayWidth";
 import HkPopover from "./HkPopover";
 import HkMenuPanel from "./HkMenuPanel";
@@ -69,6 +70,7 @@ export default defineComponent({
   setup(props) {
     const manager = usePopupManager();
     const { t } = useI18n();
+    const { isMobile } = useBreakpoint();
 
     /** Which entries the strip navigates. Windows (modal/drawer) always;
      *  dropdown-kind surfaces only while they BLOCK like a window — the
@@ -274,6 +276,12 @@ export default defineComponent({
 
     function openMenu(): void {
       if (!hidden.value.length) return;
+      // The two surfaces are never open together — and the symmetric close
+      // matters on a phone: the strip paints above the sheet's scrim, so
+      // its trigger stays tappable while a reveal is docked (review round
+      // two), and a menu opening underneath it would leave the pair
+      // fighting over one Escape.
+      revealed.value = null;
       menuItems.value = hidden.value.map(({ id, label }) => ({ id, label }));
       menuOpen.value = true;
     }
@@ -294,6 +302,79 @@ export default defineComponent({
       if (!stillFolded) menuOpen.value = false;
     });
 
+    // ── Truncated-name reveal ─────────────────────────────────────────
+    // A cut label travels whole to assistive tech, and the folded layers
+    // get the menu above — but a layer that is VISIBLE and still cut had no
+    // way to read it. Tapping such a crumb opens the same popover family
+    // (anchored under the crumb on desktop, bottom-up sheet on mobile) with
+    // the whole name, because the strip's own bar is not a place long text
+    // can be read from.
+    const revealed = ref<{ id: string; label: string } | null>(null);
+    const revealAnchor = ref<HTMLElement | null>(null);
+    const crumbEls = new Map<string, HTMLElement>();
+
+    function setCrumbEl(id: string, el: Element | null): void {
+      if (el) crumbEls.set(id, el as HTMLElement);
+      else crumbEls.delete(id);
+    }
+
+    function toggleReveal(crumb: Crumb): void {
+      if (revealed.value?.id === crumb.id) {
+        revealed.value = null;
+        return;
+      }
+      if (!crumbEls.has(crumb.id)) return;
+      menuOpen.value = false;
+      revealAnchor.value = crumbEls.get(crumb.id) ?? null;
+      revealed.value = { id: crumb.id, label: crumb.label };
+    }
+
+    // What keeps the reveal alive is the LAYER, never the fold: opening it
+    // on a phone docks a blocking sheet, which joins the stack the strip
+    // lists and re-decides the tail underneath — a fold that carried the
+    // tapped crumb behind the trigger used to close the surface in the same
+    // frame it opened (2026-09-16 review). It goes away when the layer
+    // itself does, and when the layer stops being cut in the first place
+    // (a retitle makes its crumb plain text again — an open panel would
+    // then be anchored to nothing while showing a name that no longer
+    // exists); a retitle that keeps cutting follows the live name.
+    watch([crumbs, tail], ([list, visibleTail]) => {
+      const open = revealed.value;
+      if (!open) return;
+      const crumb = list.find((entry) => entry.id === open.id);
+      if (!crumb || !crumb.truncated) {
+        revealed.value = null;
+        return;
+      }
+      // An ANCHORED panel whose crumb folded behind the trigger would keep
+      // a detached element as its anchor, and the next reposition (a
+      // resize, a panel resize) would measure a 0×0 rect and fly the panel
+      // into the viewport corner (review round two). The mobile sheet
+      // needs no anchor and keeps showing the name.
+      if (!isMobile.value && !visibleTail.some((entry) => entry.id === open.id)) {
+        revealed.value = null;
+        return;
+      }
+      if (crumb.label !== open.label) {
+        revealed.value = { id: crumb.id, label: crumb.label };
+      }
+    });
+
+    // Escape closes whichever strip surface is open. HkPopover owns Escape
+    // for its SHEET form (the panel takes focus there); the anchored form
+    // has no focusable panel, so a document listener covers both.
+    function onSurfaceKeydown(e: KeyboardEvent) {
+      if (e.key !== "Escape") return;
+      if (revealed.value) revealed.value = null;
+      else if (menuOpen.value) menuOpen.value = false;
+    }
+    const surfaceOpen = computed(() => revealed.value !== null || menuOpen.value);
+    watch(surfaceOpen, (open) => {
+      if (open) document.addEventListener("keydown", onSurfaceKeydown);
+      else document.removeEventListener("keydown", onSurfaceKeydown);
+    });
+    onBeforeUnmount(() => document.removeEventListener("keydown", onSurfaceKeydown));
+
     const topPx = ref(24);
     function resyncTop() {
       const app = document.getElementById(props.appRootId);
@@ -394,6 +475,7 @@ export default defineComponent({
           window.removeEventListener("resize", onViewportChange);
           releaseClone();
           menuOpen.value = false;
+          revealed.value = null;
           hiddenCount.value = 0;
         }
       },
@@ -502,16 +584,23 @@ export default defineComponent({
                 {/* A chevron separates two items — the FIRST rendered item
                     carries none, whether or not the trigger precedes it. */}
                 {(triggerShown.value || i > 0) && separator()}
-                <span class={itemClass(crumb)}>
-                  {crumb.truncated ? (
-                    <>
-                      <span aria-hidden="true">{crumb.text}</span>
-                      <span class="hk-modal-breadcrumb-sr-only">{crumb.label}</span>
-                    </>
-                  ) : (
-                    crumb.text
-                  )}
-                </span>
+                {crumb.truncated ? (
+                  // Cut label: tappable, and the full name is the button's
+                  // accessible name (a cut string is not a name).
+                  <button
+                    type="button"
+                    ref={(el) => setCrumbEl(crumb.id, el as Element | null)}
+                    class={`${itemClass(crumb)} hk-modal-breadcrumb-item-reveal`}
+                    aria-haspopup="dialog"
+                    aria-expanded={revealed.value?.id === crumb.id}
+                    aria-label={crumb.label}
+                    onClick={() => toggleReveal(crumb)}
+                  >
+                    {crumb.text}
+                  </button>
+                ) : (
+                  <span class={itemClass(crumb)}>{crumb.text}</span>
+                )}
               </span>
             ))}
           </nav>
@@ -542,6 +631,26 @@ export default defineComponent({
               ))}
             </HkMenuPanel>
           </HkPopover>
+          <HkPopover
+            modelValue={revealed.value !== null}
+            onUpdate:modelValue={(v: boolean) => {
+              if (!v) revealed.value = null;
+            }}
+            anchorRef={revealAnchor.value}
+            placement="bottom-start"
+            // Same clearance as the menu: the crumb sits inside the strip's
+            // own padding box, which paints above the anchored band.
+            offset={16}
+            sheetOnMobile
+            // The name is the surface's reason to exist, so it names it.
+            // The sheet heading ellipsises (it is chrome) — the panel body
+            // below carries the whole name and wraps.
+            title={revealed.value?.label ?? ""}
+          >
+            {revealed.value && (
+              <p class="hk-modal-breadcrumb-reveal">{revealed.value.label}</p>
+            )}
+          </HkPopover>
         </Teleport>
       ) : null;
   },

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 };
 }