@celestia-island/hikari 0.55.37 → 0.55.39

package/package.json

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

package/src/components/HkModalBreadcrumb.blur.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Source contract for the breadcrumb strip's blur stand-down (2026-09-21
+ * chest field report, round 5 — the "content blinks once" residual).
+ *
+ * The strip floats over every popup band, so its backdrop-filter
+ * re-samples the whole blurred band each time the sheet behind it
+ * resizes or swaps content; on the phone GPU that re-filter read as a
+ * one-shot flash per wizard step. The family pattern (HkModal /
+ * HkDrawer / HkPopover) is a host-tunable blur knob that defaults to
+ * NONE on ≤767px — the strip was the last surface without it.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkModalBreadcrumb.scss"), "utf-8");
+
+/** Brace-aware `@media <query>` block extractor. */
+function mediaBlocks(source: string, query: string): string[] {
+  const blocks: string[] = [];
+  let from = 0;
+  for (;;) {
+    const at = source.indexOf(`@media ${query}`, from);
+    if (at < 0) break;
+    const open = source.indexOf("{", at);
+    let depth = 0;
+    let i = open;
+    for (; i < source.length; i++) {
+      if (source[i] === "{") depth++;
+      else if (source[i] === "}") {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    blocks.push(source.slice(at, i + 1));
+    from = i + 1;
+  }
+  return blocks;
+}
+
+describe("HkModalBreadcrumb blur contract", () => {
+  it("keeps the base blur host-tunable through the family knob", () => {
+    const rule = src.match(/\.hk-modal-breadcrumb\s*\{[^}]*\}/)![0]!;
+    expect(rule).toContain(
+      "backdrop-filter: var(--hk-modal-breadcrumb-blur, blur(var(--blur-md)));",
+    );
+    // No naked blur declaration left on the strip itself.
+    expect(rule).not.toMatch(/backdrop-filter:\s*blur\(/);
+  });
+
+  it("stands the blur down on ≤767px by default", () => {
+    const blocks = mediaBlocks(src, "(max-width: 767px)");
+    expect(blocks.length).toBe(1);
+    expect(blocks[0]).toContain(".hk-modal-breadcrumb");
+    expect(blocks[0]).toContain(
+      "backdrop-filter: var(--hk-modal-breadcrumb-blur-mobile, none);",
+    );
+  });
+});

package/src/components/HkModalBreadcrumb.scss

@@ -17,7 +17,13 @@
   border: 1px solid var(--hk-breadcrumb-border, rgba(0, 0, 0, 0.06));
   border-radius: var(--radius-md, 0.5rem);
   box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
-  backdrop-filter: blur(var(--blur-md));
+  /* Family blur pattern (HkModal/HkDrawer/HkPopover): host-tunable, and
+     stood down on phones — the strip floats over every popup, so its
+     backdrop-filter re-samples the whole blurred band each time the sheet
+     behind it resizes or swaps content. On the phone GPU that re-filter
+     read as a one-shot flash on every wizard step change (2026-09-21
+     chest report, round 5). */
+  backdrop-filter: var(--hk-modal-breadcrumb-blur, blur(var(--blur-md)));
   pointer-events: none;
   user-select: none;
   animation: hk-modal-breadcrumb-in var(--duration-fast, 0.15s) cubic-bezier(0.16, 1, 0.3, 1);
@@ -228,3 +234,13 @@
     animation: none;
   }
 }
+
+/* Phone stand-down for the strip's blur (see the base rule): the default
+ * is NONE on ≤767px; a host that explicitly wants the finish back can set
+ * --hk-modal-breadcrumb-blur-mobile (the same knob family the modal,
+ * drawer and popover sheets already expose). */
+@media (max-width: 767px) {
+  .hk-modal-breadcrumb {
+    backdrop-filter: var(--hk-modal-breadcrumb-blur-mobile, none);
+  }
+}

package/src/components/HkStepFlow.phonesnap.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Source contract for the phone step-swap snap (2026-09-21 chest field
+ * report, AddProviderWizard Prev/Next "content blinks once").
+ *
+ * On ≤767px the step body's slide+fade must be inert: inside the mobile
+ * bottom sheet the frame's own size morph already carries the spatial
+ * feedback, and the slide's transient layer promotion/demotion costs a
+ * one-frame raster gap at both ends on phone GPUs. Desktop keeps the
+ * directional slide; reduced motion already snaps globally.
+ *
+ * Pinned here so a refactor cannot silently restore the phone slide —
+ * the class names are the same, so only the media-scoped rule proves it.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkStepFlow.scss"), "utf-8");
+
+/** Brace-aware `@media <query>` block extractor: a naive slice at the
+ *  first `}` would cut at the first nested rule's closing brace. */
+function mediaBlocks(source: string, query: string): string[] {
+  const blocks: string[] = [];
+  let from = 0;
+  for (;;) {
+    const at = source.indexOf(`@media ${query}`, from);
+    if (at < 0) break;
+    const open = source.indexOf("{", at);
+    let depth = 0;
+    let i = open;
+    for (; i < source.length; i++) {
+      if (source[i] === "{") depth++;
+      else if (source[i] === "}") {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    blocks.push(source.slice(at, i + 1));
+    from = i + 1;
+  }
+  return blocks;
+}
+
+const PHONE_QUERY = "(max-width: 767px)";
+/** The four transition-class selectors Vue's <Transition> toggles. */
+const ACTIVE_SELECTORS = [
+  ".hk-stepflow-fwd-enter-active",
+  ".hk-stepflow-back-enter-active",
+  ".hk-stepflow-fwd-leave-active",
+  ".hk-stepflow-back-leave-active",
+];
+
+/** The single ≤767px block, asserted present IN the test that needs it
+ *  (a beforeAll assertion would downgrade a missing block to "skipped"
+ *  instead of a hard failure). */
+function phoneBlock(): string {
+  const blocks = mediaBlocks(src, PHONE_QUERY);
+  expect(blocks.length).toBe(1);
+  return blocks[0]!;
+}
+
+describe("HkStepFlow phone snap contract", () => {
+  it("disables the slide/fade transition on ≤767px", () => {
+    const block = phoneBlock();
+    for (const selector of ACTIVE_SELECTORS) {
+      expect(block).toContain(selector);
+    }
+    // transition:none on every active class — the whole point: no
+    // property animates, so no promotion window exists to blink.
+    expect(block).toMatch(/transition:\s*none\s*;/);
+    // …and it must be the ONLY transition declaration in the block
+    // (a stray `transition: opacity …` would re-open the blink).
+    const declarations = block.match(/transition:\s*[^;]+;/g) ?? [];
+    expect(declarations).toHaveLength(1);
+  });
+
+  it("keeps the desktop slide outside the phone block", () => {
+    // Mutation guard: the phone rule must be ADDITIVE. The base
+    // (desktop) enter/leave rules still carry the opacity+transform
+    // transition, so deleting them fails here instead of passing
+    // vacuously.
+    const baseEnter = src.match(
+      /\.hk-stepflow-fwd-enter-active\s*,\s*\n\.hk-stepflow-back-enter-active\s*\{[^}]*\}/,
+    );
+    expect(baseEnter).not.toBeNull();
+    expect(baseEnter![0]).toContain("transition:");
+    expect(baseEnter![0]).toContain("opacity");
+    expect(baseEnter![0]).toContain("transform");
+
+    const baseLeave = src.match(
+      /\.hk-stepflow-fwd-leave-active\s*,\s*\n\.hk-stepflow-back-leave-active\s*\{[^}]*\}/,
+    );
+    expect(baseLeave).not.toBeNull();
+    expect(baseLeave![0]).toContain("opacity");
+    expect(baseLeave![0]).toContain("transform");
+  });
+
+  it("keeps the reduce-motion snap block (house pattern) intact", () => {
+    const blocks = mediaBlocks(src, "(prefers-reduced-motion: reduce)");
+    expect(blocks.length).toBe(1);
+    expect(blocks[0]).toMatch(/transition:\s*none\s*;/);
+  });
+});

package/src/components/HkStepFlow.scss

@@ -89,6 +89,22 @@
   transform: translateX(24px);
 }
 
+/* Phone (≤767px): the body snaps between steps instead of sliding. On
+ * the mobile sheet the frame's own size morph already carries the
+ * spatial feedback, and the slide's transient layer promotion/demotion
+ * costs a one-frame raster gap at both ends on phone GPUs — the
+ * "content blinks once on every step" report (2026-09-21 chest field
+ * report, AddProviderWizard Prev/Next). Same shape as the
+ * reduced-motion block below; desktop keeps the directional slide. */
+@media (max-width: 767px) {
+  .hk-stepflow-fwd-enter-active,
+  .hk-stepflow-back-enter-active,
+  .hk-stepflow-fwd-leave-active,
+  .hk-stepflow-back-leave-active {
+    transition: none;
+  }
+}
+
 /* Reduced motion: the body snaps between steps instead of sliding
  * (house pattern: HkExpansionPanel.scss / HkAffixPicker.scss). */
 @media (prefers-reduced-motion: reduce) {

package/src/components/HkTitleBar.scss

@@ -115,6 +115,15 @@
   border-radius: 8px 0 0 0;
 }
 
+/* A maximized frame has no rounded window corner to follow: Windows 11
+   squares decorated windows itself and borderless hosts square the DWM
+   corners manually, so keeping the radius would round the hover fill
+   away from the (square) frame corner. The (0,3,0) compound out-ranks
+   both the base rule and the RTL mirror above. */
+.hk-titlebar[data-maximized] .hk-titlebar-btn-close {
+  border-radius: 0;
+}
+
 .hk-titlebar-btn-close:hover {
   background: var(--hk-tb-close-hover);
   color: var(--hi-color-text-on-danger, #ffffff);

package/src/components/HkTitleBar.test.tsx

@@ -0,0 +1,127 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+
+import HkTitleBar from "./HkTitleBar";
+
+/**
+ * HkTitleBar maximized-state contract tests.
+ *
+ * The `maximized` prop drives three things; all are contract-tested here
+ * because the failure mode is silent (a wrong glyph, a hover fill that
+ * rounds away from a square frame corner):
+ *
+ *   1. the root carries `data-maximized` only while maximized — the
+ *      stylesheet keys the close-button radius override off it,
+ *   2. the maximize button swaps its glyph/title with the same prop, and
+ *   3. the compiled sheet squares the close corner under `[data-maximized]`.
+ *
+ * The compiled-stylesheet guard exists because vitest stubs CSS, so a
+ * runtime test can never notice the rule going missing (the HkAboutModal
+ * styles test hit exactly that class of regression).
+ *
+ * (Repo test convention: raw createApp + container queries, no
+ * @vue/test-utils dependency.)
+ */
+
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkTitleBar", () => {
+  it("marks the root data-maximized only while maximized", () => {
+    const windowed = mount(h(HkTitleBar, { title: "App", maximized: false }));
+    expect(windowed.querySelector(".hk-titlebar")?.hasAttribute("data-maximized")).toBe(false);
+
+    const maximized = mount(h(HkTitleBar, { title: "App", maximized: true }));
+    expect(maximized.querySelector(".hk-titlebar")?.hasAttribute("data-maximized")).toBe(true);
+  });
+
+  it("follows the prop reactively, adding and removing the marker", async () => {
+    // Hosts toggle `maximized` live (resize listener → ref); the marker
+    // must come and go with it, not just latch on mount.
+    const maximized = ref(false);
+    const host = mount(
+      h(() => h(HkTitleBar, { title: "App", maximized: maximized.value })),
+    );
+    const bar = () => host.querySelector<HTMLElement>(".hk-titlebar")!;
+    expect(bar().hasAttribute("data-maximized")).toBe(false);
+
+    maximized.value = true;
+    await nextTick();
+    expect(bar().hasAttribute("data-maximized")).toBe(true);
+
+    maximized.value = false;
+    await nextTick();
+    expect(bar().hasAttribute("data-maximized")).toBe(false);
+  });
+
+  it("swaps the maximize glyph with the same prop", () => {
+    const windowed = mount(h(HkTitleBar, { title: "App", maximized: false }));
+    expect(windowed.querySelector('[title="Maximize"]')).toBeTruthy();
+
+    const maximized = mount(h(HkTitleBar, { title: "App", maximized: true }));
+    expect(maximized.querySelector('[title="Restore"]')).toBeTruthy();
+  });
+});
+
+describe("HkTitleBar stylesheet contract", () => {
+  const css = compile(resolve(componentDir, "HkTitleBar.scss"), {
+    style: "expanded",
+  }).css;
+
+  /**
+   * Body of one compiled rule, by exact selector (Sass drops the quotes
+   * around an attribute value: `[data-maximized]`).
+   *
+   * The selector is anchored to its own line: expanded Sass puts every
+   * selector of a rule (comma lists included) on its own line, so this
+   * skips compound rules that merely END with the selector (e.g. the
+   * `[data-maximized]` override) while still requiring exactly one match —
+   * a second copy, say inside a media query, would stay invisible to a
+   * looser scan while still winning the cascade.
+   */
+  function ruleBody(sheet: string, selector: string): string {
+    const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const matches = [
+      ...sheet.matchAll(new RegExp(`(?:^|\\n)\\s*${escaped}\\s*\\{([^}]*)\\}`, "g")),
+    ];
+    expect(matches, `${selector} compiles exactly once`).toHaveLength(1);
+    return matches[0]?.[1] ?? "";
+  }
+
+  it("squares the close button corner while maximized, both directions", () => {
+    // The (0,3,0) compound must survive compilation and out-rank the base
+    // radius rule and its RTL mirror; reading the compiled declarations
+    // (not the SCSS source) means a rule that failed to compile fails here.
+    const body = ruleBody(css, ".hk-titlebar[data-maximized] .hk-titlebar-btn-close");
+    expect(body).toContain("border-radius: 0");
+  });
+
+  it("keeps the windowed radius var wired to the close button", () => {
+    const scss = readFileSync(resolve(componentDir, "HkTitleBar.scss"), "utf8");
+    expect(scss).toContain("--hk-tb-radius-close:");
+    const body = ruleBody(css, ".hk-titlebar-btn-close");
+    expect(body).toContain("border-radius: var(--hk-tb-radius-close)");
+  });
+});

package/src/components/HkTitleBar.tsx

@@ -23,7 +23,9 @@ import "./HkTitleBar.scss";
  * to the LEFT of minimize, each emitting `action` with its id.
  *
  * The maximized state is data-driven: the host passes `maximized` and the
- * component swaps the maximize/restore glyph — no shell probing inside.
+ * component swaps the maximize/restore glyph and squares the close button's
+ * window corner radius (a maximized frame has no rounded corner to follow)
+ * — no shell probing inside.
  */
 export default defineComponent({
   name: "HkTitleBar",
@@ -51,7 +53,11 @@ export default defineComponent({
   },
   setup(props, { emit, slots }) {
     return () => (
-      <div class="hk-titlebar" data-drag-region>
+      <div
+        class="hk-titlebar"
+        data-drag-region
+        data-maximized={props.maximized || undefined}
+      >
         {slots.left?.() ?? (
           <span class="hk-titlebar-title">
             {props.icon && <img class="hk-titlebar-icon" src={props.icon} alt="" />}

package/src/composables/useSizeMorph.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick, ref } from "vue";
 
+import { readHkRuntime } from "../runtime/registry";
+
 import { useSizeMorph, type SizeMorphOptions } from "./useSizeMorph";
 
 /** Injectable ResizeObserver: captures the callback so tests can fire
@@ -123,6 +125,15 @@ async function settle(): Promise<void> {
   await nextTick();
 }
 
+/** Await exactly N animation frames. The bus's one-shot pump is itself
+ *  rAF-driven and FIFO-ordered with these, so an awaited frame resolves
+ *  in the same tick the pump that ran before it did. */
+async function busFrames(n: number): Promise<void> {
+  for (let i = 0; i < n; i++) {
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  }
+}
+
 describe("useSizeMorph", () => {
   it("pins the frame to its natural height on start", () => {
     const h = mountHarness(120);
@@ -279,23 +290,82 @@ describe("useSizeMorph clip reveal", () => {
     h.frame.style.setProperty("--hk-sheet-morph", "clip");
     h.start();
     expect(h.frame.style.height).toBe("300px");
+    // Resident promotion: clip-mode frames carry will-change from the
+    // arm moment, not per sweep (2026-09-21 round-5 report: a per-sweep
+    // promotion read as a one-frame see-through).
+    expect(h.frame.style.willChange).toBe("clip-path");
 
     h.setNatural(360);
     FakeResizeObserver.instances[0]!.callback();
     await settle();
     // The pin landed at the new height with no height animation staged.
     expect(h.frame.style.height).toBe("360px");
-    // The sweep runs: end-state clip + layer promotion in flight.
+    // The sweep runs: end-state clip (promotion stays resident).
     expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
     expect(h.frame.style.willChange).toBe("clip-path");
     expect(h.frame.style.transition).toBe("");
 
     fireTransitionEnd(h.frame, "clip-path");
     expect(h.frame.style.clipPath).toBe("");
+    // Still resident until stop/hold.
+    expect(h.frame.style.willChange).toBe("clip-path");
+    h.stop();
     expect(h.frame.style.willChange).toBe("");
   });
 
-  it("starts the sweep from the old visual edge (delta inset)", () => {
+  it("holds the staged clip through a two-frame warmup before the sweep starts", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(360);
+    h.remeasure();
+    // Staged synchronously — new pin, start inset — but NO sweep yet:
+    // the reveal must let the resident layer raster the resized box
+    // first (2026-09-21 chest report — a same-task sweep outran the
+    // raster thread and the revealed band composited as black tiles).
+    expect(h.frame.style.height).toBe("360px");
+    expect(h.frame.style.clipPath).toBe("inset(60px 0 0 0 round 0px 0px 0px 0px)");
+
+    // The hold is TWO frames, not one: after the first frame the staged
+    // start inset must still be in place (a one-frame warmup would have
+    // already opened the clip).
+    await busFrames(1);
+    expect(h.frame.style.clipPath).toBe("inset(60px 0 0 0 round 0px 0px 0px 0px)");
+
+    await settle();
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("clip-path");
+  });
+
+  it("reports the sweep to the animation bus only once it starts", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    // Let any earlier test's report timer expire so the baseline is quiet.
+    await new Promise((resolve) => setTimeout(resolve, 220));
+    const transitions = (): number =>
+      Number(readHkRuntime("animationBus")?.transitions ?? 0);
+    const base = transitions();
+
+    h.start();
+    h.setNatural(360);
+    h.remeasure();
+    // Warmup pending: no CSS transition is running yet, nothing reported.
+    expect(transitions()).toBe(base);
+
+    // Two warmup frames start the sweep; its 150ms report is live now
+    // (well inside the report's window — do NOT use the 220ms settle,
+    // it outlives the report).
+    await busFrames(3);
+    expect(transitions()).toBe(base + 1);
+
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(transitions()).toBe(base);
+  });
+
+  it("starts the sweep from the old visual edge (delta inset)", async () => {
     const h = mountHarness(300);
     h.frame.style.setProperty("--hk-sheet-morph", "clip");
     h.start();
@@ -324,32 +394,75 @@ describe("useSizeMorph clip reveal", () => {
       "inset(120px 0 0 0 round 0px 0px 0px 0px)",
     ]);
     expect(h.frame.style.height).toBe("420px");
+    // The staged start inset HOLDS through the warmup — the sweep is a
+    // bus one-shot now, never part of the staging task.
+    expect(h.frame.style.clipPath).toBe("inset(120px 0 0 0 round 0px 0px 0px 0px)");
+    await settle();
     expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
   });
 
-  it("keeps the height morph for shrink and sub-threshold growth", async () => {
+  it("conceals shrink through clip-path and re-pins atomically at the end", async () => {
     const h = mountHarness(400);
     h.frame.style.setProperty("--hk-sheet-morph", "clip");
     h.start();
 
-    // Shrink: no clip state, the pin flips under the height transition.
+    // Shrink CONCEALS (round-5 report: the snap read as "no animation"):
+    // the box keeps the OLD pin while the top edge folds down through
+    // the closing inset — the pin swap lands only at the sweep's end.
     h.setNatural(320);
     FakeResizeObserver.instances[0]!.callback();
     await settle();
+    // Warmup + sweep in flight: clip folding toward inset(80px), height
+    // still the old pin.
+    expect(h.frame.style.clipPath).toBe("inset(80px 0 0 0 round 0px 0px 0px 0px)");
+    expect(h.frame.style.height).toBe("400px");
+    // The sweep ends: atomic re-pin — height jumps to the target with
+    // the clip cleared in one transition-off task (visually a no-op).
+    fireTransitionEnd(h.frame, "clip-path");
     expect(h.frame.style.height).toBe("320px");
     expect(h.frame.style.clipPath).toBe("");
-    expect(h.frame.style.willChange).toBe("");
 
     // Sub-threshold growth (2px < REVEAL_MIN_PX): snaps, no reveal.
     h.setNatural(322);
     h.remeasure();
     expect(h.frame.style.height).toBe("322px");
     expect(h.frame.style.clipPath).toBe("");
+
+    // Sub-threshold shrink (−2px): snaps too, no conceal.
+    h.setNatural(320);
+    h.remeasure();
+    expect(h.frame.style.height).toBe("320px");
+    expect(h.frame.style.clipPath).toBe("");
+  });
+
+  it("lands an interrupted conceal atomically on the next dance", async () => {
+    const h = mountHarness(400);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(320);
+    h.remeasure();
+    await settle();
+    expect(h.frame.style.clipPath).toBe("inset(80px 0 0 0 round 0px 0px 0px 0px)");
+    expect(h.frame.style.height).toBe("400px");
+
+    // A growth lands mid-conceal: the teardown must land the target pin
+    // ATOMICALLY (clearing the clip alone would pop the box back to
+    // full height for a frame), then the new reveal stages from the
+    // CONCEALED height (360 − 320 = 40px).
+    h.setNatural(360);
+    h.remeasure();
+    expect(h.frame.style.height).toBe("360px");
+    expect(h.frame.style.clipPath).toBe("inset(40px 0 0 0 round 0px 0px 0px 0px)");
+    await settle();
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
   });
 
   it("never clips without the mode flag (desktop height morph intact)", async () => {
     const h = mountHarness(300);
     h.start();
+    // No resident promotion either — the desktop surface never promotes.
+    expect(h.frame.style.willChange).toBe("");
 
     h.setNatural(400);
     FakeResizeObserver.instances[0]!.callback();
@@ -357,6 +470,13 @@ describe("useSizeMorph clip reveal", () => {
     expect(h.frame.style.height).toBe("400px");
     expect(h.frame.style.clipPath).toBe("");
     expect(h.frame.style.willChange).toBe("");
+
+    // Desktop shrink keeps the plain height morph (no conceal).
+    h.setNatural(240);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("240px");
+    expect(h.frame.style.clipPath).toBe("");
   });
 
   it("clears an in-flight reveal when a new dance starts", async () => {
@@ -366,18 +486,49 @@ describe("useSizeMorph clip reveal", () => {
 
     h.setNatural(380);
     h.remeasure();
+    // Staged: the sweep is still pending on the warmup.
+    expect(h.frame.style.clipPath).toBe("inset(80px 0 0 0 round 0px 0px 0px 0px)");
+    await settle();
     expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
 
-    // A second growth lands before transitionend fired: the stale clip
-    // must come off inside the new dance, then the new reveal stages.
+    // A second growth lands mid-sweep: the stale clip/listener/report
+    // must come off inside the new dance, then the new reveal stages
+    // from the NEW delta (450 − 380 = 70px).
     h.setNatural(450);
     h.remeasure();
     expect(h.frame.style.height).toBe("450px");
-    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    expect(h.frame.style.clipPath).toBe("inset(70px 0 0 0 round 0px 0px 0px 0px)");
     expect(h.frame.style.willChange).toBe("clip-path");
   });
 
-  it("clears an interrupted reveal inside the next dance (no transitionend)", () => {
+  it("cancels a pending warmup when a second growth re-stages mid-warmup", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(380);
+    h.remeasure();
+    expect(h.frame.style.clipPath).toBe("inset(80px 0 0 0 round 0px 0px 0px 0px)");
+
+    // Burn exactly one of the first warmup's two frames, then re-stage.
+    // A LEAKED first warmup would run its sweep on the next frame; the
+    // cancelled one (disconnect in stopReveal) never does.
+    await busFrames(1);
+    h.setNatural(450);
+    h.remeasure();
+    expect(h.frame.style.clipPath).toBe("inset(70px 0 0 0 round 0px 0px 0px 0px)");
+
+    // One frame later the leak would have flipped the clip open; the
+    // freshly staged start inset must still hold.
+    await busFrames(1);
+    expect(h.frame.style.clipPath).toBe("inset(70px 0 0 0 round 0px 0px 0px 0px)");
+
+    // The NEW warmup's second frame starts its own sweep.
+    await busFrames(1);
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+  });
+
+  it("clears an interrupted reveal inside the next dance (no transitionend)", async () => {
     const h = mountHarness(300);
     h.frame.style.setProperty("--hk-sheet-morph", "clip");
     h.start();
@@ -386,17 +537,22 @@ describe("useSizeMorph clip reveal", () => {
     h.remeasure();
     expect(h.frame.style.clipPath).not.toBe("");
 
-    // A SHRINK lands before the reveal's transitionend fired: unlike a
-    // follow-up growth (which restages its own clip), the height-morph
-    // branch writes no clip at all — the dance-start teardown is the
-    // only thing that returns the frame to CSS ownership (R1 mutation
-    // M1 evidence: without it the stale inset(0px) + will-change ride
-    // the shrink and linger at rest).
+    // A SHRINK lands before the reveal's warmup fired: the teardown
+    // drops the staged reveal (clip off — the reveal branch's teardown
+    // never pops the box, it already sits at its pin) and the new dance
+    // CONCEALS toward 310: the box keeps the 380 pin while the edge
+    // folds, so no height change is visible until the atomic re-pin.
+    // (R1 mutation M1 lineage: without the dance-start teardown a stale
+    // clip rode the next morph and lingered at rest.)
     h.setNatural(310);
     h.remeasure();
+    expect(h.frame.style.height).toBe("380px");
+    expect(h.frame.style.clipPath).toBe("");
+    await settle();
+    expect(h.frame.style.clipPath).toBe("inset(70px 0 0 0 round 0px 0px 0px 0px)");
+    fireTransitionEnd(h.frame, "clip-path");
     expect(h.frame.style.height).toBe("310px");
     expect(h.frame.style.clipPath).toBe("");
-    expect(h.frame.style.willChange).toBe("");
   });
 
   it("releases the clip state on stop so the leave animation owns the frame", async () => {
@@ -412,6 +568,12 @@ describe("useSizeMorph clip reveal", () => {
     expect(h.frame.style.height).toBe("");
     expect(h.frame.style.clipPath).toBe("");
     expect(h.frame.style.willChange).toBe("");
+
+    // A leaked warmup would fire the sweep AFTER the stop and re-add
+    // the clip/promotion — disconnect() in stopReveal is the fix.
+    await settle();
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
   });
 
   it("ignores transitionend events for other properties", async () => {
@@ -421,6 +583,8 @@ describe("useSizeMorph clip reveal", () => {
 
     h.setNatural(360);
     h.remeasure();
+    // The listener only exists once the warmup started the sweep.
+    await settle();
     fireTransitionEnd(h.frame, "height");
     expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
     fireTransitionEnd(h.frame, "opacity");

package/src/composables/useSizeMorph.ts

@@ -1,5 +1,11 @@
 import { onBeforeUnmount, type Ref } from "vue";
 
+import {
+  reportTransition,
+  scheduleFrame,
+  type AnimationHandle,
+} from "../runtime/animationBus";
+
 /** Chrome-allowance calibration constants (px): the floor covers a
  *  standard header+footer+borders stack (and bodies that overflow at
  *  arm time, where the resting delta goes negative and says nothing
@@ -13,6 +19,18 @@ const CHROME_ALLOWANCE_SLACK = 32;
  * layer for. */
 const REVEAL_MIN_PX = 3;
 
+/** Reveal warmup (bus frames): how long the staged clip holds before
+ *  the sweep starts. The pin + clip start + `will-change` land in one
+ *  task, so the promoted layer starts re-rastering the whole resized
+ *  box immediately; holding the sweep for two frames lets that raster
+ *  land before the moving edge reveals it. Starting the sweep in the
+ *  staging task outran the raster thread on phone GPUs and the
+ *  just-revealed band composited as black tiles (2026-09-21 chest
+ *  field report, AddProviderWizard step growth). The staged clip keeps
+ *  the new band hidden through the hold, so the visible geometry is
+ *  the pre-growth sheet while warming — the wait itself is invisible. */
+const REVEAL_WARMUP_FRAMES = 2;
+
 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
@@ -78,20 +96,37 @@ export interface SizeMorphOptions {
  * pin chases the target with the CSS transition — bounded, one-shot
  * choreography, not an infinite per-frame animation.
  *
- * Growth morphs on clip-mode surfaces (the mobile sheet docking, flagged
- * `--hk-sheet-morph: clip` in CSS) reveal instead of animating height:
- * the new pin lands instantly and the box's top edge sweeps up through
- * `clip-path: inset()` — same duration/ease tokens as the height
- * transition, same "content rides rigidly" grammar as the modal unveil,
- * but paint/compositor-level: no per-frame layout and no per-frame
+ * Size morphs on clip-mode surfaces (the mobile sheet docking, flagged
+ * `--hk-sheet-morph: clip` in CSS) ride paint-only clip-path in BOTH
+ * directions — same duration/ease tokens as the height transition, same
+ * "content rides rigidly" grammar as the modal unveil, but
+ * compositor-level: no per-frame layout and no per-frame
  * backdrop-filter re-raster over the resizing fixed layer (the mobile
- * patchy-flicker source, 2026-09-15 chest report). Height-mode
- * surfaces and the select sheet keep the height transition for shrinks
- * (their stylesheets list it); the phone MODAL sheet narrowed its list
- * to clip-path-only (2026-09-21 step-change shrink report — 150ms of
- * per-frame layout on the fixed layer re-rastered the moving edge), so
- * its shrinks snap: the L291-style pin flip lands instantly when the
- * stylesheet no longer transitions height.
+ * patchy-flicker source, 2026-09-15 chest report). Growth REVEALS: the
+ * new pin lands instantly and the top edge sweeps up through the staged
+ * inset — never in the staging task, a two-frame warmup
+ * (REVEAL_WARMUP_FRAMES) lets the layer's raster land first
+ * (2026-09-21 chest report — same-task starts revealed black tiles).
+ * Shrink CONCEALS: the box keeps its old pin while the top edge folds
+ * down through the closing inset, and an atomic re-pin (transition-off
+ * height swap) lands the target when the sweep ends — restoring the
+ * shrink animation the clip-path-only transition list had lost
+ * (2026-09-21 chest report, round 5) without reintroducing a frame of
+ * per-frame layout. The layer promotion is RESIDENT for the whole arm
+ * cycle (applied at start(), cleared on hold/release): promoting at the
+ * step-change moment cost a one-frame see-through as the old layer died
+ * before the new one rastered (same report).
+ * Height-mode surfaces (desktop) keep the height morph unchanged.
+ *
+ * Scheduling rides the shared animation context
+ * (`runtime/animationBus`): the measurement hop and the reveal warmup
+ * are bus one-shots (`scheduleFrame`), and the CSS sweep is reported
+ * (`reportTransition`) so the bus keeps beating through it and the
+ * runtime registry sees the load. The settle debounce stays a
+ * real-time timer on purpose — it gates MEASUREMENT, not motion, and a
+ * parked (reduced-motion) bus must never freeze layout by stalling it;
+ * bus one-shots fire even parked, so every frame path still completes
+ * and the motion collapse itself stays CSS-owned.
  *
  * Reduced motion / the global animation switch stay honored: the frame's
  * transition-duration collapses to one frame under
@@ -103,7 +138,7 @@ export function useSizeMorph(
   options: SizeMorphOptions = {},
 ): SizeMorph {
   let ro: ResizeObserver | null = null;
-  let raf = 0;
+  let raf: AnimationHandle | null = null;
   let settleTimer: ReturnType<typeof setTimeout> | null = null;
   let armed = false;
   /** Last pinned height (px) — the transition's "from" value. */
@@ -114,25 +149,140 @@ export function useSizeMorph(
    *  bodies that overflow at rest, plus subpixel slack. See the guard in
    *  remeasure(). */
   let chromeAllowance = CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
-  /** In-flight clip reveal (clip-mode growth morph): the frame whose
-   *  inline clip-path/will-change must come off again once the sweep
-   *  lands, plus the listener that does it. */
+  /** In-flight clip morph (clip-mode size change): the frame whose inline
+   *  clip-path must come off again once the sweep lands, the listener
+   *  that does it, the warmup one-shot that starts the sweep, the sweep's
+   *  bus transition report — and, for a CONCEAL (shrink), the target
+   *  height the atomic re-pin lands when the sweep ends. */
   let revealEl: HTMLElement | null = null;
   let revealEnd: ((ev: Event) => void) | null = null;
+  let revealWarmup: AnimationHandle | null = null;
+  let revealReport: AnimationHandle | null = null;
+  let revealDir: "reveal" | "conceal" | null = null;
+  let concealTo: number | null = null;
+  /** Resident layer promotion on clip-mode surfaces: applied at arm time
+   *  and cleared on hold/release. Promoting at the STEP-change moment
+   *  (0.55.38's per-sweep will-change) destroyed the old layer one frame
+   *  before the new one had rastered — on the phone GPU the sheet read
+   *  as a one-frame see-through flash exactly when the raster race had
+   *  just been fixed (2026-09-21 chest report, round 5). Promoting once
+   *  at open and KEEPING it means step morphs never cross a layer
+   *  boundary at all. */
+  let residentWill = false;
+
+  /** Land a conceal atomically: pin the target height and clear the clip
+   *  in one transition-disabled task. Called from the sweep's end, from
+   *  stopReveal() when a conceal is interrupted, and from hold/release.
+   *  Visually a no-op: the box top is exactly where the clip edge sits,
+   *  so the pin swap paints nothing. */
+  function finishConceal(f: HTMLElement): void {
+    const inlineTransition = f.style.transition;
+    f.style.transition = "none";
+    if (concealTo != null) {
+      f.style.height = `${concealTo}px`;
+      pinned = concealTo;
+    }
+    f.style.clipPath = "";
+    void f.offsetHeight;
+    f.style.transition = inlineTransition;
+    concealTo = null;
+  }
 
-  /** Tear down an in-flight clip reveal: drop the listener and return
-   *  the inline clip/will-change to CSS ownership. Safe to call when no
-   *  reveal is running (every dance start, stop, and unmount). */
+  /** Tear down an in-flight clip morph: cancel the pending warmup and
+   *  the bus report, drop the listener, and land the frame in its rest
+   *  state — an interrupted conceal re-pins its target atomically
+   *  (clearing the clip alone would pop the box back to full height for
+   *  one frame); a reveal just clears the clip. The resident
+   *  will-change is NOT touched here (it belongs to the arm cycle, see
+   *  residentWill). Safe to call when nothing is running (every dance
+   *  start, stop, and unmount). */
   function stopReveal(): void {
+    if (revealWarmup) {
+      revealWarmup.disconnect();
+      revealWarmup = null;
+    }
+    if (revealReport) {
+      revealReport.disconnect();
+      revealReport = null;
+    }
     if (revealEl && revealEnd) {
       revealEl.removeEventListener("transitionend", revealEnd);
     }
     if (revealEl) {
-      revealEl.style.clipPath = "";
-      revealEl.style.willChange = "";
+      if (revealDir === "conceal" && concealTo != null) {
+        finishConceal(revealEl);
+      } else {
+        revealEl.style.clipPath = "";
+      }
     }
     revealEl = null;
     revealEnd = null;
+    revealDir = null;
+    concealTo = null;
+  }
+
+  /** Drop the resident layer promotion (hold / release paths). */
+  function clearResidentWill(): void {
+    if (!residentWill) return;
+    residentWill = false;
+    const f = frame.value;
+    if (f) f.style.willChange = "";
+  }
+
+  /** The frame's computed clip-transition duration, for the bus report
+   *  at sweep start: the sweep is CSS-owned, so without a report the
+   *  bus goes quiet for its duration and starves concurrent entries
+   *  (and the runtime registry under-reports load). Max across the
+   *  duration list; falls back to the --duration-fast default when the
+   *  read fails (SSR) or carries no time token. */
+  function transitionDurationMs(f: HTMLElement): number {
+    let raw = "";
+    try {
+      raw = getComputedStyle(f).transitionDuration;
+    } catch {
+      raw = "";
+    }
+    let max = 0;
+    for (const m of raw.matchAll(/(\d+(?:\.\d+)?)(m?)s/g)) {
+      max = Math.max(max, parseFloat(m[1]!) * (m[2] ? 1 : 1000));
+    }
+    return max > 0 ? max : 150;
+  }
+
+  /** Begin the actual sweep: attach the end listener, report the CSS
+   *  transition to the bus so it keeps beating for the duration, and
+   *  flip the clip to the sweep's END state under the live transition.
+   *  A reveal opens the clip (inset(delta)→inset(0), the top edge
+   *  sweeping up); a conceal closes it (inset(0)→inset(delta), the top
+   *  edge folding down while the box itself stays pinned at the OLD
+   *  height — the atomic re-pin lands in finishConceal when the sweep
+   *  ends). Only ever called from the warmup's last frame — never
+   *  synchronously from the dance (see REVEAL_WARMUP_FRAMES). */
+  function startRevealSweep(
+    f: HTMLElement,
+    radii: string,
+    dir: "reveal" | "conceal",
+    insetPx: number,
+  ): void {
+    const onEnd = (ev: Event): void => {
+      // transitionend bubbles: a descendant animating its own
+      // clip-path must not end the frame's morph early.
+      if (
+        ev.target === f &&
+        (ev as TransitionEvent).propertyName === "clip-path"
+      ) {
+        stopReveal();
+      }
+    };
+    f.addEventListener("transitionend", onEnd);
+    revealEl = f;
+    revealEnd = onEnd;
+    revealDir = dir;
+    revealReport = reportTransition(transitionDurationMs(f));
+    f.style.clipPath =
+      dir === "reveal"
+        ? `inset(0px 0 0 0 round ${radii})`
+        : `inset(${insetPx}px 0 0 0 round ${radii})`;
   }
 
   /** Clip-mode opt-in, owned by CSS: the modal's mobile media block
@@ -178,6 +328,7 @@ export function useSizeMorph(
     const f = frame.value;
     if (f) f.style.height = "";
     stopReveal();
+    clearResidentWill();
     pinned = 0;
   }
 
@@ -212,8 +363,8 @@ export function useSizeMorph(
     //    natural (CSS-capped) height in one layout flush.
     // 2. Clip-mode growth: pin the NEW height outright and stage the
     //    clip start (still transition-disabled), so the reveal that
-    //    follows sweeps a fully-laid-out box — layout happens once,
-    //    here, never per frame.
+    //    follows (after the warmup, started by the bus) sweeps a
+    //    fully-laid-out box — layout happens once, here, never per frame.
     //    Otherwise re-establish the OLD pin (still transition-disabled)
     //    and flush it, so the style history is exactly "old height" when
     //    the live CSS transition returns.
@@ -251,22 +402,31 @@ export function useSizeMorph(
       return;
     }
     const next = Math.round(natural);
-    const growth = next - pinned;
-    // Clip reveal (see the composable doc): the pin lands instantly and
-    // the top edge sweeps up through paint-only clip-path, with the
-    // box's own corner radii riding the moving edge. The frame's
-    // stylesheet owns the clip-path transition (duration/ease tokens
-    // shared with the height transition), so reduced-motion and the
-    // global animation switch collapse it exactly like the height morph
-    // they already govern. Everything else — shrink, first pin,
-    // sub-threshold growth, height-mode surfaces — keeps the height
-    // morph below (desktop stays exactly as it was).
-    const reveal = pinned > 0 && growth >= REVEAL_MIN_PX && clipMode(f);
+    const delta = next - pinned;
+    // Clip morphs (see the composable doc): on clip-mode surfaces BOTH
+    // directions ride paint-only clip-path — growth REVEALS (pin the new
+    // height outright, then sweep the top edge up through the staged
+    // inset) and shrink CONCEALS (keep the old pin, then fold the top
+    // edge down; the atomic re-pin lands when the sweep ends). No
+    // per-frame layout in either direction; the frame's stylesheet owns
+    // the clip-path transition (duration/ease tokens shared with the
+    // height transition), so reduced-motion and the global animation
+    // switch collapse both exactly like the height morph they govern.
+    // First pin, sub-threshold deltas and height-mode surfaces keep the
+    // height morph below (desktop stays exactly as it was).
+    const reveal = pinned > 0 && delta >= REVEAL_MIN_PX && clipMode(f);
+    const conceal = pinned > 0 && delta <= -REVEAL_MIN_PX && clipMode(f);
     let radii = "";
     if (reveal) {
       radii = cornerRadii(f);
       f.style.height = `${next}px`;
-      f.style.clipPath = `inset(${growth}px 0 0 0 round ${radii})`;
+      f.style.clipPath = `inset(${delta}px 0 0 0 round ${radii})`;
+    } else if (conceal) {
+      radii = cornerRadii(f);
+      // The box stays pinned at the OLD height (the visible start state
+      // needs no staging — the dance-start teardown already cleared any
+      // clip, so the box paints its full current height).
+      f.style.height = `${pinned}px`;
     } else if (pinned > 0) {
       f.style.height = `${pinned}px`;
     }
@@ -275,26 +435,47 @@ export function useSizeMorph(
     // old visual edge / the height transition starts from the old pin.
     void f.offsetHeight;
     f.style.transition = inlineTransition;
-    if (reveal) {
-      const onEnd = (ev: Event): void => {
-        // transitionend bubbles: a descendant animating its own
-        // clip-path must not end the frame's reveal early.
-        if (
-          ev.target === f &&
-          (ev as TransitionEvent).propertyName === "clip-path"
-        ) {
-          stopReveal();
-        }
-      };
-      f.addEventListener("transitionend", onEnd);
+    if (reveal || conceal) {
+      // Warmup (see REVEAL_WARMUP_FRAMES): hold the staged state for two
+      // bus frames so the layer's raster lands before the edge moves;
+      // the sweep itself starts from the bus. The layer is ALREADY
+      // promoted (resident will-change since start()), so the warmup
+      // costs no layer churn. Bus one-shots fire even while the bus is
+      // parked for reduced motion — they are scheduling primitives, not
+      // motion; the motion collapse stays CSS-owned
+      // (transition-duration → one frame), so a parked bus still lands
+      // the sweep instantly and transitionend cleans up exactly as
+      // before.
       revealEl = f;
-      revealEnd = onEnd;
-      f.style.willChange = "clip-path";
-      f.style.clipPath = `inset(0px 0 0 0 round ${radii})`;
+      revealDir = reveal ? "reveal" : "conceal";
+      concealTo = conceal ? next : null;
+      const dir = revealDir;
+      const insetPx = Math.abs(delta);
+      let framesLeft = REVEAL_WARMUP_FRAMES;
+      const armWarmup = (): void => {
+        revealWarmup = scheduleFrame(() => {
+          revealWarmup = null;
+          // Torn down mid-warmup (new dance / hold / stop / unmount).
+          if (revealEl !== f || revealDir !== dir) return;
+          if (--framesLeft > 0) {
+            armWarmup();
+            return;
+          }
+          startRevealSweep(f, radii, dir, insetPx);
+        });
+      };
+      armWarmup();
     } else {
       f.style.height = `${next}px`;
     }
-    pinned = next;
+    if (!conceal) {
+      // The pin bookkeeping is immediate for reveals (the box already
+      // sits at the new height) and snaps (nothing animates). A conceal
+      // keeps the OLD pin until finishConceal() lands the target — a
+      // mid-flight remeasure must see the still-visual height as its
+      // "from".
+      pinned = next;
+    }
     // Self-heal the allowance on every VALIDATED pin: chrome that grew
     // after calibration (an async footer, a header slot mounting
     // mid-open) updates the baseline instead of tripping the guard on
@@ -321,8 +502,13 @@ export function useSizeMorph(
     settleTimer = setTimeout(() => {
       settleTimer = null;
       if (raf) return;
-      raf = requestAnimationFrame(() => {
-        raf = 0;
+      // Frame work rides the shared bus; the settle debounce above
+      // deliberately stays a real-time timer — it gates MEASUREMENT,
+      // not motion, and a parked (reduced-motion) bus must never freeze
+      // the layout by stalling a bus-ridden interval. One-shots fire
+      // even parked, so this hop is safe in every motion state.
+      raf = scheduleFrame(() => {
+        raf = null;
         remeasure();
       });
     }, 150);
@@ -335,6 +521,15 @@ export function useSizeMorph(
     // its enter (callers arm in after-enter) and sits at rest, so the
     // frame-vs-content delta is pure chrome.
     calibrate();
+    // Resident promotion on clip-mode surfaces (see residentWill): the
+    // layer crosses no boundary during later step morphs. Applied here,
+    // at the open edge — one promotion per open cycle instead of one
+    // per resize.
+    const f0 = frame.value;
+    if (f0 && clipMode(f0)) {
+      f0.style.willChange = "clip-path";
+      residentWill = true;
+    }
     if (typeof ResizeObserver === "undefined" || !content.value) {
       remeasure();
       return;
@@ -354,13 +549,16 @@ export function useSizeMorph(
       settleTimer = null;
     }
     if (raf) {
-      cancelAnimationFrame(raf);
-      raf = 0;
+      raf.disconnect();
+      raf = null;
     }
     // The next start() re-calibrates against whatever chrome that open
     // cycle carries.
     chromeAllowance = CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
     stopReveal();
+    // The leave fold no longer clips; drop the resident promotion with
+    // it (start() re-applies on the next open).
+    clearResidentWill();
     // 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.
   }
@@ -377,8 +575,9 @@ export function useSizeMorph(
   onBeforeUnmount(() => {
     ro?.disconnect();
     if (settleTimer) clearTimeout(settleTimer);
-    if (raf) cancelAnimationFrame(raf);
+    if (raf) raf.disconnect();
     stopReveal();
+    clearResidentWill();
   });
 
   return { start, stop, hold, remeasure };