@celestia-island/hikari 0.55.315 → 0.55.318

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.315",
+  "version": "0.55.318",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/animation/registerAnimations.test.ts

@@ -26,7 +26,7 @@ function collectSourceFiles(dir: string): string[] {
     if (entry.isDirectory()) {
       if (p === path.resolve(srcDir, "animation")) continue;
       out.push(...collectSourceFiles(p));
-    } else if (/\.(scss|ts|tsx)$/.test(entry.name) && !/\btest\.[tj]sx?$/.test(entry.name)) {
+    } else if (/\.(scss|ts|tsx)$/.test(entry.name) && !/\.(test|spec)\.[tj]sx?$/.test(entry.name)) {
       out.push(p);
     }
   }

package/src/components/HkListTransition.scss

@@ -179,7 +179,13 @@
    the strip itself is pointer-transparent), and inheritance does not
    beat an explicit auto. The ghost must not take clicks while it sinks:
    a tap opened a popover anchored to the fading element (2026-11-07
-   review). Specificity (0,1,1) outranks the (0,1,0) button faces. */
+   review). Specificity (0,1,1) outranks the (0,1,0) button faces.
+   Belt relationship: pinLeaving also sets `inert` on the ghost (blocks
+   clicks AND focus for every descendant where the pin ran); this rule is
+   the CSS belt that still dead-ends buttons when the pin skipped (no
+   layout — tests — or a host without captured rects). Future surface
+   consumers whose rows carry links/inputs, not just buttons: extend this
+   selector or rely on the inert. */
 .hk-list-surface-leave-active button {
   pointer-events: none;
 }

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

@@ -122,7 +122,7 @@ describe("HkModal leave-window height pin", () => {
   it("keeps the morph pin through the whole leave and releases at finalize", async () => {
     vi.useFakeTimers();
     freezeRaf();
-      stubPhoneViewport();
+    stubPhoneViewport();
     stubDurations();
     stubLayout(500);
     try {
@@ -160,7 +160,7 @@ describe("HkModal leave-window height pin", () => {
   it("leaves the frame unpinned through the enter; the open edge pins the settled height", async () => {
     vi.useFakeTimers();
     freezeRaf();
-      stubPhoneViewport();
+    stubPhoneViewport();
     stubDurations();
     stubLayout(400);
     try {
@@ -197,7 +197,7 @@ describe("HkModal leave-window height pin", () => {
   it("drops the held pin at a reopen-interrupt edge; the open edge re-pins", async () => {
     vi.useFakeTimers();
     freezeRaf();
-      stubPhoneViewport();
+    stubPhoneViewport();
     stubDurations();
     stubLayout(500);
     try {

package/src/components/HkModal.open-close-scale.test.ts

@@ -378,6 +378,24 @@ describe("HkModal desktop open/close contract (compiled cascade, user direction
     }
   });
 
+  it("keeps the desktop rest transition to the height leg only", () => {
+    // The size morph's height leg is the ONLY property the desktop rest
+    // state ever animates. The clip-path reveal morph belongs to the
+    // ≤767px sheet block (which replaces the list wholesale), and
+    // nothing changes the frame's max-height after mount (the 70vh cap
+    // is the body's, a different element) — retired legs smuggled back
+    // into the shorthand must fail this pin (2026-11-07 residue sweep).
+    const rest = frameWith();
+    expect(winner(rest, "transition", DESKTOP)).toBe(
+      "height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1))",
+    );
+    // The phone sheet keeps its own clip-path-only morph list.
+    const mobileRest = frameWith();
+    expect(winner(mobileRest, "transition", MOBILE)).toBe(
+      "clip-path var(--hk-modal-morph-duration, 0.3s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1))",
+    );
+  });
+
   it("fades the frame and rides its height on one shared token pair per direction", () => {
     // Pinned WHOLE (winner() normalizes whitespace), not by prefix: a
     // fourth time value (transition-delay) or an extra smuggled segment

package/src/components/HkModal.plate.contract.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Compiled-CSS contract for the modal BLUR PLATE — the open-stutter fix.
+ *
+ * Measured root cause (2026-11-07 open-jank spike, headless rAF matrix):
+ * a backdrop-filter re-filters its full-viewport backdrop on EVERY
+ * composited frame while any animation is live anywhere — the enter
+ * storm (frame + dim + strip + crumbs mounting together) ran at
+ * 26-55% dropped frames with live plates, while the steady state
+ * (nothing animating) is cached and runs 60fps. The architecture:
+ *
+ *   1. the blur lives on a STATIC plate that never animates and never
+ *      carries a transition;
+ *   2. the eye-tracked transition is the solid-color dim curtain
+ *      (opacity-only composite);
+ *   3. the plate is REMOVED on stack-covered windows (a present
+ *      backdrop-filter element still forces the per-frame backdrop
+ *      surface even computed to none — measured ~44pp worse than
+ *      hidden);
+ *   4. the overlay carries the default blur only for plate-less markup
+ *      (the Rust-rendered modals share this compiled sheet without a
+ *      plate element) and opts down to dim-only document-globally when
+ *      a Vue plate exists.
+ *
+ * Regression risk this file pins: a future edit re-adding a
+ * backdrop-filter to `.hk-modal-overlay` would double-filter the Vue
+ * path and reintroduce the jank; re-adding an enter/leave-scoped
+ * suppression leg would reintroduce the settle hitch; relaxing the
+ * covered drop would reintroduce the stacked-blur storm.
+ */
+import { describe, expect, it } from "vitest";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "sass";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const css = compile(join(here, "HkModal.scss"), {
+  loadPaths: [here, join(here, "..", "styles")],
+  style: "expanded",
+}).css;
+
+/** Brace-matched body of the first top-level block whose head starts
+ *  with the given prefix (`@media …` or a selector). */
+function topBlock(cssText: string, headPrefix: string): string {
+  const start = cssText.indexOf(headPrefix);
+  if (start === -1) return "";
+  const open = cssText.indexOf("{", start);
+  let depth = 0;
+  for (let i = open; i < cssText.length; i++) {
+    if (cssText[i] === "{") depth += 1;
+    else if (cssText[i] === "}") {
+      depth -= 1;
+      if (depth === 0) return cssText.slice(open + 1, i);
+    }
+  }
+  return "";
+}
+
+/** All `selector { body }` frames inside a block (one nesting level deep
+ *  is enough). Selector parts carry preceding block-glue in expanded
+ *  output (media heads, comment remains) — trimmed to the bare
+ *  selector. */
+function frames(block: string): { selectors: string[]; body: string }[] {
+  const out: { selectors: string[]; body: string }[] = [];
+  const re = /([^{}]+)\{([^{}]*)\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(block))) {
+    out.push({
+      selectors: m[1]
+        .split(",")
+        .map((part) => {
+          let t = part;
+          const comment = t.lastIndexOf("*/");
+          if (comment !== -1) t = t.slice(comment + 2);
+          const brace = t.lastIndexOf("{");
+          if (brace !== -1) t = t.slice(brace + 1);
+          const semi = t.lastIndexOf(";");
+          if (semi !== -1) t = t.slice(semi + 1);
+          return t.trim();
+        })
+        .filter((s) => s.startsWith(".") || s.startsWith("[") || s.startsWith(":")),
+      body: m[2].trim(),
+    });
+  }
+  return out;
+}
+
+/** Bodies of every rule whose selector LIST includes exactly `selector`. */
+function ruleBodies(sheet: string, selector: string): string[] {
+  return frames(sheet)
+    .filter((f) => f.selectors.includes(selector))
+    .map((f) => f.body);
+}
+const oneRule = (sheet: string, selector: string): string => {
+  const bodies = ruleBodies(sheet, selector);
+  expect(bodies.length, `rule ${selector} must exist`).toBeGreaterThan(0);
+  return bodies[0];
+};
+
+const mobileBlock = topBlock(css, "@media (max-width: 767px)");
+
+describe("modal blur plate (static filter, stack-covered removal)", () => {
+  it("carries the blur; the fading overlay must NOT (vue path)", () => {
+    // The core invariant: the overlay is the ANIMATED layer — a
+    // backdrop-filter on it re-filters the whole viewport per frame
+    // (the reported stutter). The blur lives on the never-animated
+    // plate only.
+    const plate = oneRule(css, ".hk-modal-blur-plate");
+    expect(plate).toMatch(/backdrop-filter:\s*var\(--hk-modal-overlay-blur/);
+    expect(plate).toContain("pointer-events: none");
+    expect(plate).toContain("z-index: -1");
+  });
+
+  it("gives plate-less markup (rust-rendered modals) the overlay blur", () => {
+    // The Rust-rendered modals share this compiled sheet but their
+    // markup has no plate element: the overlay keeps the default blur
+    // there.
+    const overlayDefault = ruleBodies(css, ".hk-modal-overlay").find((b) =>
+      b.includes("backdrop-filter: var(--hk-modal-overlay-blur"),
+    );
+    expect(overlayDefault, "default overlay blur must exist").toBeTruthy();
+  });
+
+  it("opts the overlay down to dim-only wherever a plate exists", () => {
+    // :root:has(plate) is document-global: one Vue modal anywhere means
+    // every overlay in the document is plate-backed and dim-only.
+    expect(css).toMatch(
+      /:root:has\(\.hk-modal-blur-plate\)\s*\.hk-modal-overlay\s*\{[^}]*backdrop-filter:\s*none/,
+    );
+  });
+
+  it("removes the plate on stack-covered windows", () => {
+    // A present backdrop-filter element still forces the per-frame
+    // backdrop surface even computed to none (~44pp worse than hidden).
+    const covered = ruleBodies(css, ".hk-modal-root[data-stack-covered] .hk-modal-blur-plate");
+    expect(covered.length).toBeGreaterThanOrEqual(1);
+    for (const body of covered) expect(body).toContain("display: none");
+  });
+
+  it("keeps no enter/leave-scoped suppression legs (the top plate animates with the filter)", () => {
+    // The top plate's own enter measured 2% dropped WITH the filter
+    // live (single live blur) — suppression legs were removed with the
+    // settle hitch they created. Re-adding any leg must be a deliberate
+    // re-trade.
+    expect(css).not.toMatch(
+      /hk-modal-content-(?:enter|leave)-(?:from|to|active) ~ \.hk-modal-blur-plate/,
+    );
+  });
+
+  it("keeps the mobile stand-down on both faces", () => {
+    expect(mobileBlock).toContain(".hk-modal-blur-plate");
+    expect(frames(mobileBlock).some((f) => f.selectors.includes(".hk-modal-blur-plate"))).toBe(true);
+    // The Vue-path opt-out must hold on phones too.
+    expect(mobileBlock).toMatch(
+      /:root:has\(\.hk-modal-blur-plate\)\s*\.hk-modal-overlay\s*\{[^}]*backdrop-filter:\s*none/,
+    );
+  });
+});

package/src/components/HkModal.scss

@@ -23,6 +23,44 @@
 // Overlay (backdrop)
 // ------
 
+// The BLUR is a separate static plate, NOT on the fading overlay: a
+// backdrop-filter re-filters the whole viewport on every composited frame
+// while ANY animation is live (the steady state is cached and clean —
+// measured separately), and the enter storm (frame + dim + strip + crumbs
+// mounting together) measured 36% dropped frames with the filter live vs
+// 0% with it suppressed (2026-11-07 open-jank spike, headless rAF matrix;
+// one modal, blur 3px). The plate holds the filter and never animates;
+// the overlay below is a solid-color dim curtain whose opacity ramp is
+// the cheapest possible layer to animate — and the ramp is what the eye
+// tracks, so the blur cutting in with the first frame (instead of
+// ramping over 0.42s) reads as focus pull, not as a missing layer.
+.hk-modal-blur-plate {
+  position: fixed;
+  inset: 0;
+  // Below the overlay (0) and the content frame (1) inside the root's own
+  // stacking context — the plate is DOM-last but paints first.
+  z-index: -1;
+  @include backdrop-filter(var(--hk-modal-overlay-blur, blur(3px)));
+  // The root is pointer-events: none; the plate must never take clicks.
+  pointer-events: none;
+}
+
+// STACK-COVERED: a covered (non-topmost) window's plate is REMOVED
+// outright (display:none, not merely filter:none — a present
+// backdrop-filter element still forces the per-frame backdrop surface
+// during any animation even with the filter computed to none, measured
+// at ~44pp dropped frames vs 2% hidden; 2026-11-07 open-jank spike).
+// Blur reads as a property of the TOP surface anyway: lower windows sit
+// under the top window's own dim + blur, so their own filter is
+// visually redundant (blur-of-blur). The dim curtains are untouched:
+// depth still darkens, only the redundant blur legs drop. (The
+// breadcrumb strip — z band 250 — paints ABOVE these roots: the strip
+// band is not part of any plate's backdrop, which is why removing the
+// covered plates, not the strip, was the fix that measured.)
+.hk-modal-root[data-stack-covered] .hk-modal-blur-plate {
+  display: none;
+}
+
 .hk-modal-overlay {
   position: fixed;
   inset: 0;
@@ -32,10 +70,20 @@
   // handle hasn't resolved yet — zIndex briefly starts at 0).
   z-index: 0;
   background: var(--hk-modal-overlay-bg, rgba(0, 0, 0, 0.45));
+  // The overlay itself carries the blur ONLY where no plate exists (the
+  // Rust-rendered modals share this compiled sheet but their markup has
+  // no plate element — dropping the property from the overlay would
+  // silently strip their desktop blur). The Vue path always renders a
+  // plate, so :root:has(...) opts the overlay down to dim-only there and
+  // the plate owns the blur (including its stack-covered removal).
   @include backdrop-filter(var(--hk-modal-overlay-blur, blur(3px)));
   pointer-events: auto;
 }
 
+:root:has(.hk-modal-blur-plate) .hk-modal-overlay {
+  @include backdrop-filter(none);
+}
+
 // Overlay enter/leave — fade-only classes emitted from the shared
 // window-layer contract (./_scrim-fade.scss): the curtain dims the whole
 // viewport in place, never sliding or scaling with the content frame.
@@ -74,14 +122,13 @@
   // (capped) height and pins it as px on every content change — the
   // transition below animates old→new px. Both pinned values are
   // explicit px, so this needs no interpolate-size keyword support.
-  // clip-path rides the same token pair for the mobile sheet's reveal
-  // morph (--hk-sheet-morph: clip below): the pin lands instantly and
-  // the top edge sweeps up paint-only — no per-frame layout, no
-  // per-frame backdrop re-raster over the resizing fixed layer.
-  transition:
-    height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
-    max-height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
-    clip-path var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
+  // Height is the only leg the desktop rest state ever animates: the
+  // clip-path reveal morph belongs to the ≤767px sheet block (which
+  // replaces this list wholesale), and on desktop nothing — hikari or
+  // host — changes the frame's max-height after mount (the 70vh cap is
+  // the body's, a different element; the phone caps move by design and
+  // deliberately carry no leg — see the IME cap-chase note below).
+  transition: height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
   background: var(--hk-modal-bg, var(--hi-color-surface, rgba(255,255,255,0.95)));
   @include backdrop-filter(var(--hk-modal-blur, none));
   border: 1px solid var(--hk-modal-border-color, var(--hi-color-border, rgba(100,100,100,0.08)));
@@ -154,6 +201,11 @@
   .hk-modal-content-enter-from,
   .hk-modal-content-leave-to {
     opacity: 0;
+    // Pre-promote at insert: enter-from lands in the same frame the
+    // content mounts — carrying will-change HERE (shared with the leave's
+    // end pose) means the layer is composited before the transition's
+    // first measured frame, not one hitch later.
+    will-change: opacity, transform;
     transform: translate(
           calc(-50% + var(--hk-modal-shift-x, 0px)),
           calc(-50% + var(--hk-modal-shift-y, 0px))
@@ -444,10 +496,18 @@
   // the page, so an opaque-ish sheet reads identically. Hosts restore
   // the finish per surface with --hk-modal-blur-mobile /
   // --hk-modal-bg-mobile.
+  .hk-modal-blur-plate {
+    @include backdrop-filter(var(--hk-modal-overlay-blur-mobile, none));
+  }
+
   .hk-modal-overlay {
     @include backdrop-filter(var(--hk-modal-overlay-blur-mobile, none));
   }
 
+  :root:has(.hk-modal-blur-plate) .hk-modal-overlay {
+    @include backdrop-filter(none);
+  }
+
   // Height-morph window (round 20): while the sheet's height animates
   // every frame, a backdrop-filter anywhere in the resizing subtree has
   // to re-render its backdrop surface every frame — the same per-frame
@@ -483,7 +543,7 @@
     //   direction change. Growth keeps its animated reveal via the
     //   clip-path sweep (the only transition left on phones).
     //
-    // Desktop keeps the full base list (height + max-height + clip-path).
+    // Desktop keeps the base list (height only — the size morph's leg).
     // 0.3s = the stepflow crossfade's family standard (2026-09-21 user
     // spec, round 7): the clip sweep, the riding body and the fade must
     // land together. Keyboard-driven height changes never animate
@@ -566,6 +626,7 @@
   .hk-modal-content-leave-to {
     opacity: 0;
     height: auto;
+    will-change: opacity, transform;
     transform: translateY(100%);
   }
 

package/src/components/HkModal.sheetgap.test.ts

@@ -114,16 +114,21 @@ describe("HkModal mobile sheet spacing contract", () => {
       expect(tr).not.toMatch(/\bmax-height\b/);
     });
 
-    it("keeps the desktop frame transition list intact (base rule)", () => {
-      // The guard is phone-only by design: the base rule outside the
-      // media block keeps height+max-height+clip-path animated.
+    it("keeps the desktop frame transition to the height leg only (base rule)", () => {
+      // The guard is phone-only by design: outside the media block the
+      // base rule animates height only — the size morph's leg. The
+      // clip-path reveal lives in the ≤767px block (which replaces the
+      // list wholesale), and nothing changes the frame's max-height
+      // after mount (the 70vh cap is the body's, a different element):
+      // the 2026-11-07 residue sweep retired the never-animated
+      // max-height/clip-path legs, and this pin keeps them retired.
       const base = src.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
       expect(base.length, "base .hk-modal-content rule extracted").toBeGreaterThan(0);
       const tr = base.match(/transition:\s*([^;]+);/)?.[1] ?? "";
       expect(tr.length, "base transition declaration present").toBeGreaterThan(0);
       expect(tr).toMatch(/\bheight\b/);
-      expect(tr).toMatch(/\bmax-height\b/);
-      expect(tr).toMatch(/\bclip-path\b/);
+      expect(tr).not.toMatch(/\bmax-height\b/);
+      expect(tr).not.toMatch(/\bclip-path\b/);
     });
 
     it("lifts the 70vh body cap on phones so the footer sits on the bottom edge", () => {

package/src/components/HkModal.sheetmorph.test.ts

@@ -11,9 +11,11 @@
  *   - growth morphs REVEAL through clip-path (--hk-sheet-morph: clip on
  *     the docking surfaces, useSizeMorph does the pin-instantly +
  *     sweep-up dance) — paint/compositor-level, zero per-frame layout;
- *     the frame stylesheet carries the clip-path transition on the SAME
- *     duration/ease tokens as the height transition, so the stretch look
- *     and its reduced-motion / data-css-animations governance are intact
+ *     the ≤767px sheet block replaces the frame's transition list
+ *     wholesale and carries the clip-path transition retimed to the
+ *     stepflow family standard, so the stretch look and its
+ *     reduced-motion / data-css-animations governance are intact (the
+ *     desktop base list animates the size morph's height leg only)
  *   - docked phone surfaces NEVER backdrop-filter (mobile-guard tokens
  *     defaulting to none: --hk-modal-blur-mobile, --hk-modal-overlay-
  *     blur-mobile, --hk-drawer-blur-mobile, --hk-drawer-overlay-blur-
@@ -54,12 +56,17 @@ describe("sheet family morph-performance contract", () => {
     expect(mobileModal).toMatch(/^[ \t]*--hk-sheet-morph:[ \t]*clip;$/m);
   });
 
-  it("carries a clip-path transition on the morph timing tokens", () => {
-    // Same duration/ease pair as the height morph — the reveal must keep
-    // the stretch look, not invent new timing.
+  it("keeps the clip sweep on the sheet block, out of the desktop base list", () => {
+    // 2026-11-07 residue sweep: the desktop rest state never sweeps a
+    // clip-path (no clip-mode surface exists ≥768px), so the base list
+    // carries the size morph's height leg only. The reveal grammar lives
+    // in the ≤767px block, which replaces the frame's transition list
+    // wholesale and retimes the sweep to the stepflow family standard
+    // (pinned by the next test).
     const frame = modal.match(/\.hk-modal-content\s*{[^}]*}/)?.[0] ?? "";
+    expect(frame).not.toMatch(/^[ \t]*clip-path var\(--duration-fast/m);
     expect(frame).toMatch(
-      /^[ \t]*clip-path var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
+      /^[ \t]*transition: height var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
     );
   });
 
@@ -92,9 +99,14 @@ describe("sheet family morph-performance contract", () => {
     const panel = select.match(/\.hk-select-sheet-panel\s*{[\s\S]*?^}/m)?.[0] ?? "";
     expect(panel).toMatch(/^[ \t]*--hk-sheet-morph:[ \t]*clip;$/m);
     expect(panel).toMatch(/^[ \t]*contain:[ \t]*layout style;$/m);
+    // 2026-11-07 residue sweep: the panel rides the modal's ≤767px
+    // grammar — clip-path is the ONLY leg (clip mode pins instantly and
+    // folds transition-off, and a max-height leg on a dvh-capped sheet
+    // is the IME cap-chase the modal block fixed on 2026-09-21).
     expect(panel).toMatch(
-      /^[ \t]*clip-path var\(--duration-fast, 0\.15s\) var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
+      /^[ \t]*transition: clip-path var\(--duration-fast, 0\.15s\)[\s]*var\(--ease-standard, cubic-bezier\(0\.4, 0, 0\.2, 1\)\);$/m,
     );
+    expect(panel).not.toMatch(/\bmax-height var\(--duration-fast/m);
     // Opaque already — the panel must not regress to a translucent
     // finish that re-composites against the streaming page.
     expect(panel).toMatch(/^[ \t]*background:[ \t]*rgb\(var\(--color-surface\)\);$/m);

package/src/components/HkModal.test.tsx

@@ -815,3 +815,81 @@ describe("HkModal Escape precedence", () => {
     expect(document.activeElement, "focus wraps back to the first focusable").toBe(first);
   });
 });
+
+describe("HkModal blur plate", () => {
+  it("renders the plate as the aria-hidden last child of the root", async () => {
+    // The plate is DOM-last so the sheet's stack-covered drop can be keyed
+    // by attribute scoping without depending on paint order (z-indexes
+    // carry that). Structural pin: last child + hidden from a11y.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const open = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, { modelValue: open.value }, { default: () => h("div", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await nextTick();
+    await nextTick();
+    const root = document.querySelector(".hk-modal-root")!;
+    const last = root.lastElementChild as HTMLElement | null;
+    expect(last?.classList.contains("hk-modal-blur-plate")).toBe(true);
+    expect(last?.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("marks covered roots while a higher window is open", async () => {
+    // TOP-ONLY BLUR wiring: the covered (lower) root carries
+    // data-stack-covered; the top root does not. Flips live with the
+    // registry: closing the top window un-covers the lower one.
+    const mounts2: ReturnType<typeof createApp>[] = [];
+    const containers2: HTMLElement[] = [];
+    try {
+      const openA = ref(true);
+      const openB = ref(true);
+      const mk = (mv: { value: boolean }, title: string) => {
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        containers2.push(container);
+        const Wrapper = defineComponent({
+          setup() {
+            return () =>
+              h(HkModal, { modelValue: mv.value, title }, { default: () => h("div", "content") });
+          },
+        });
+        const app = createApp(Wrapper);
+        mounts2.push(app);
+        app.mount(container);
+      };
+      mk(openA, "下层窗");
+      mk(openB, "上层窗");
+      await nextTick();
+      await nextTick();
+      const roots = () => [...document.querySelectorAll(".hk-modal-root")];
+      expect(roots()).toHaveLength(2);
+      // The later-registered window is the top: the FIRST root is covered.
+      const attrs = roots().map((r) => r.hasAttribute("data-stack-covered"));
+      expect(attrs).toEqual([true, false]);
+      openB.value = false;
+      await nextTick();
+      // The leave settles on the surface machine's own clock.
+      const deadline = Date.now() + 1500;
+      while (roots().some((r) => r.classList.contains("hk-modal-content-leave-active")) && Date.now() < deadline) {
+        await nextTick();
+      }
+      const deadline2 = Date.now() + 1500;
+      while (roots().some((r) => r.hasAttribute("data-stack-covered")) && Date.now() < deadline2) {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        await nextTick();
+      }
+      expect(roots().every((r) => !r.hasAttribute("data-stack-covered"))).toBe(true);
+    } finally {
+      for (const a of mounts2.splice(0)) a.unmount();
+      for (const c of containers2.splice(0)) c.remove();
+    }
+  });
+});

package/src/components/HkModal.tsx

@@ -566,6 +566,20 @@ export default defineComponent({
     // optimization for the class flip. See runtime/surfaceMachine.ts
     // for the axioms, the total transition table, and the invariants.
     const overlayEl = ref<HTMLElement>();
+    // TOP-ONLY BLUR: this window's blur plate carries the filter only
+    // while it is the topmost WINDOW-kind layer of the stack. The covered
+    // window's plate drops to dim-only (see the sheet) — with N stacked
+    // full-viewport backdrop-filters every composited frame re-runs all
+    // of them, and the open storm measured 36-55% dropped frames vs 2%
+    // with a single live filter. Reacts live: covered flips with every
+    // register/unregister above this window.
+    const stackCovered = computed(() => {
+      // Reuses the shared topWindowZ authority (the same windowing filter
+      // the dial consumes below) instead of a private registry scan.
+      const top = topWindowZ.value;
+      if (!handle.value || top === null) return false;
+      return handle.value.zIndex < top;
+    });
     const machine = useSurfaceMachine({
       layers: [
         // Budgets are the starvation-era upper bound; the driver probes
@@ -1071,6 +1085,7 @@ export default defineComponent({
         <Teleport to={ensureOverlayRoot()}>
           <div
             class="hk-modal-root"
+            data-stack-covered={stackCovered.value || undefined}
             style={{ zIndex: overlayZ.value, ...hkPadStyle(props.padding) }}
             onKeydown={onKeydown}
           >
@@ -1195,6 +1210,11 @@ export default defineComponent({
                   renderFooter(),
                   ])}
                 </div>
+          {/* Static blur plate — the LAST child of hk-modal-root so the
+              sheet's stack-covered drop ([data-stack-covered] on this
+              root) reaches it; paint order rides the explicit z-indexes
+              (plate -1 < overlay 0 < content 1), not DOM order. */}
+          <div class="hk-modal-blur-plate" aria-hidden="true" />
           </div>
         </Teleport>
       );

package/src/components/HkSelect.scss

@@ -311,24 +311,29 @@
   display: flex;
   flex-direction: column;
   /* The panel height hugs its content (up to the cap below); the sheet
-   * morphs smoothly when content grows/shrinks — a language list gaining
-   * or losing rows, a select whose options filter. `height: auto` growth
+   * morphs when content grows/shrinks — a language list gaining or
+   * losing rows, a select whose options filter. `height: auto` growth
    * cannot fire a CSS transition, so HkSelectPanel's useSizeMorph pins
-   * the measured natural height as px (see useSizeMorph) and the
-   * transition below animates old→new px; `interpolate-size: allow-keywords`
-   * stays harmless for the enter/leave slide. Growth reveals through
-   * clip-path instead (--hk-sheet-morph: clip, see useSizeMorph): the
-   * pin lands instantly and the top edge sweeps up paint-only — the
-   * sheet is a fixed full-width layer, and an animated height relaid
-   * out + repainted it every frame (mobile patchy-flicker source,
-   * 2026-09-15). Same duration/ease tokens, same stretch look. */
+   * the measured natural height as px (see useSizeMorph) and growth
+   * reveals through clip-path (--hk-sheet-morph: clip, see
+   * useSizeMorph): the pin lands instantly and the top edge sweeps up
+   * paint-only — the sheet is a fixed full-width layer, and an animated
+   * height relaid out + repainted it every frame (mobile
+   * patchy-flicker source, 2026-09-15). Shrink folds the same way and
+   * the atomic re-pin lands transition-off, so — exactly like the
+   * modal's ≤767px block — the clip-path leg is the ONLY animated
+   * property here. The max-height leg in particular must stay OUT: the
+   * cap below carries a live dvh/inset term, and with max-height in the
+   * list an adjustResize keyboard RETARGETS a 150ms transition every
+   * frame — cap-bound sheets chase their own viewport permanently (the
+   * IME cap-chase the modal block fixed on 2026-09-21; aligning this
+   * panel to that grammar on 2026-11-07 — inference-level evidence,
+   * same engine class, no same-day field report). */
   interpolate-size: allow-keywords;
   --hk-sheet-morph: clip;
   contain: layout style;
-  transition:
-    height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
-    max-height var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1)),
-    clip-path var(--duration-fast, 0.15s) var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
+  transition: clip-path var(--duration-fast, 0.15s)
+    var(--ease-standard, cubic-bezier(0.4, 0, 0.2, 1));
   max-height: min(
     72vh,
     calc(

package/src/components/sheetfamily-morph-invariant.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Source contract tying the sheet family's morph flag to its transition
+ * grammar (2026-11-07 residue sweep, the mechanical context the flag never
+ * had): `--hk-sheet-morph: clip` is read by useSizeMorph through
+ * getComputedStyle, while the transition LIST that actually animates the
+ * sweep is owned by these stylesheets — no other mechanism ties the two
+ * together, which is how dead legs survived five choreography generations.
+ * Pinned here:
+ *   - a rule that sets the flag MUST carry a clip-path transition leg
+ *     (otherwise the sweep composites unanimated / watchdog-landed);
+ *   - a clip-mode rule must NOT carry height/max-height legs (in clip
+ *     mode the morph pins instantly and folds transition-off, so those
+ *     legs are dead — and a live max-height leg on a dvh-capped sheet is
+ *     the IME cap-chase the modal block fixed on 2026-09-21);
+ *   - the flagged-rule set is pinned exactly, so a new flagged surface
+ *     opts in here consciously and inherits the grammar.
+ * Provenance: HkModal's base list trimmed in #1158; HkSelect's panel
+ * aligned in the same wave (inference-level evidence for the IME fix —
+ * same engine class as the modal's 2026-09-21 Xiaomi reports, no field
+ * report yet).
+ */
+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 read = (name: string): string => readFileSync(join(here, name), "utf-8");
+
+const FAMILY_SHEETS = ["HkModal.scss", "HkSelect.scss"] as const;
+
+/** The exact set of rules allowed to flag clip mode: selector text as it
+ *  appears in the sheet, keyed per file. A new flagged surface must add
+ *  itself here (and inherit the clip-only grammar consciously). */
+const EXPECTED_FLAGGED_RULES: Record<string, readonly string[]> = {
+  "HkModal.scss": [".hk-modal-content"],
+  "HkSelect.scss": [".hk-select-sheet-panel"],
+};
+
+/** Walk the source and return every rule block that sets
+ *  `--hk-sheet-morph: clip`, as {selector, body} — brace-matched so the
+ *  modal's media-nested block extracts whole. */
+function flaggedRules(source: string): Array<{ selector: string; body: string }> {
+  const out: Array<{ selector: string; body: string }> = [];
+  const flag = /--hk-sheet-morph:[ \t]*clip[ \t]*;/g;
+  for (const match of source.matchAll(flag)) {
+    const open = source.lastIndexOf("{", match.index);
+    if (open < 0) continue;
+    // Selector text: everything after the previous structural close
+    // (}; or }) up to the opening brace.
+    const prevClose = Math.max(
+      source.lastIndexOf("}", open),
+      source.lastIndexOf(";", open),
+    );
+    const selector = source
+      .slice(prevClose + 1, open)
+      .replace(/\/\*[\s\S]*?\*\//g, " ")
+      .replace(/\s+/g, " ")
+      .trim();
+    // Forward-match braces to the block's own close.
+    let depth = 0;
+    let end = -1;
+    for (let i = open; i < source.length; i += 1) {
+      if (source[i] === "{") depth += 1;
+      else if (source[i] === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    expect(end, `unbalanced braces after flag at offset ${match.index}`).toBeGreaterThan(0);
+    out.push({ selector, body: source.slice(open + 1, end) });
+  }
+  return out;
+}
+
+/** The block's own transition declaration (multi-line shorthands joined). */
+function transitionOf(block: string): string {
+  const match = block.match(/transition:[^;]+;/);
+  return match?.[0]?.replace(/\s+/g, " ").trim() ?? "";
+}
+
+describe("sheet family morph-flag ↔ transition-grammar contract", () => {
+  it("flags exactly the expected rules across the family", () => {
+    for (const sheet of FAMILY_SHEETS) {
+      const found = flaggedRules(read(sheet)).map((r) => r.selector).sort();
+      const expected = [...EXPECTED_FLAGGED_RULES[sheet]].sort();
+      expect(found, `${sheet} flagged rules`).toEqual(expected);
+    }
+  });
+
+  it("every flagged rule carries a clip-path leg and no dead height/max-height legs", () => {
+    for (const sheet of FAMILY_SHEETS) {
+      for (const rule of flaggedRules(read(sheet))) {
+        const tr = transitionOf(rule.body);
+        expect(tr, `${sheet} ${rule.selector} has a transition`).toContain("clip-path");
+        expect(tr, `${sheet} ${rule.selector} height leg is dead in clip mode`).not.toMatch(
+          /\bheight\b/,
+        );
+        expect(
+          tr,
+          `${sheet} ${rule.selector} max-height leg is dead in clip mode (IME cap-chase)`,
+        ).not.toMatch(/\bmax-height\b/);
+      }
+    }
+  });
+
+  it("no un-flagged family rule animates a clip-path sweep", () => {
+    // The dead-leg shape this sweep retired: a clip-path transition leg on
+    // a surface the flag never arms. Scoped to the family sheets; other
+    // components may animate clip-path for their own reasons.
+    for (const sheet of FAMILY_SHEETS) {
+      const source = read(sheet);
+      const flagged = flaggedRules(source);
+      for (const match of source.matchAll(/transition:[^;]*\bclip-path\b[^;]*;/g)) {
+        const open = source.lastIndexOf("{", match.index);
+        const prevClose = Math.max(
+          source.lastIndexOf("}", open),
+          source.lastIndexOf(";", open),
+        );
+        const selector = source
+          .slice(prevClose + 1, open)
+          .replace(/\/\*[\s\S]*?\*\//g, " ")
+          .replace(/\s+/g, " ")
+          .trim();
+        const isFlaggedRule = flagged.some((r) => r.selector === selector);
+        expect(
+          isFlaggedRule,
+          `${sheet} ${selector} animates clip-path without --hk-sheet-morph: clip`,
+        ).toBe(true);
+      }
+    }
+  });
+});

package/src/composables/useSizeMorph.test.ts

@@ -743,10 +743,12 @@ describe("useSizeMorph clip reveal", () => {
 // ── 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.
+// folding frame); a reopen that goes hold → start without releasing
+// animates from that pin (no current HkModal path does this — its reopen
+// edge releases first). deferRemeasure is the generic freeze gate: while
+// it returns true, resize-driven re-pins are deferred and an explicit
+// remeasure() flushes them — HkModal's only remaining freezer is the
+// stepflow slide window.
 
 describe("useSizeMorph hold + deferRemeasure", () => {
   it("hold keeps the pin and stops observing (leave-window stability)", () => {
@@ -790,14 +792,15 @@ describe("useSizeMorph hold + deferRemeasure", () => {
     // 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.
+    // Content changes while the gate is closed: the RO fires but the pin
+    // must not move — the caller froze the frame on purpose (the
+    // stepflow slide window at the consumer).
     h.setNatural(160);
     FakeResizeObserver.instances[0]!.callback();
     await settle();
     expect(h.frame.style.height).toBe("120px");
 
-    // The open edge flushes the deferred growth.
+    // An explicit remeasure bypasses the gate and flushes the growth.
     h.remeasure();
     expect(h.frame.style.height).toBe("160px");
 

package/src/composables/useSizeMorph.ts

@@ -35,12 +35,16 @@ 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 — the enter must own the frame's geometry (HkModal and
-   *  HkSelectPanel both arm at the machine's `open` edge; the enter
-   *  classes are off the frame by then, so calibration reads the rest
-   *  state). There is no early-arm protocol anymore: the modal's enter
-   *  is opacity+transform and never reads the frame's height, so an
-   *  enter-time pin would only freeze a stale height under
-   *  `overflow: hidden`. */
+   *  HkSelectPanel both arm at the machine's `open` edge). The call may
+   *  land one render flush before the enter classes actually leave the
+   *  frame (the machine flips the phase synchronously, Vue re-renders on
+   *  the next flush); that is safe because no enter class carries layout
+   *  rules that differ from rest — the choreographies are
+   *  opacity+transform, and the ≤767px from-pair's `height: auto`
+   *  coincides with the unpinned rest height — so calibration still
+   *  reads the rest geometry. There is no early-arm protocol anymore:
+   *  the modal's enter never reads the frame's height, so an enter-time
+   *  pin would only freeze a stale height under `overflow: hidden`. */
   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
@@ -56,7 +60,13 @@ export interface SizeMorph {
    *  does this, its reopen edge releases the pin first; 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). */
+   *  — acceptable, the enter's own choreography owns that moment).
+   *  Recorded design note: a close during an ENTER that never reached
+   *  `open` finds the morph disarmed (hold() early-returns) and the
+   *  leave folds on the live `height: auto` — the same unpinned grammar
+   *  the enter plays, and preferable to folding on a stale mount-time
+   *  pin. contentHold freezes the rendered leaf state at closingFrom, so
+   *  only a self-updating child could resize such a fold. */
   hold(): void;
   /** Drop the height pin and hand the frame back to `height: auto`
    *  without disarming anything (a hold()ed morph stays disarmed; an
@@ -177,7 +187,9 @@ export interface SizeMorphOptions {
  * 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
+ * cycle (applied at start(), cleared by hold() at the close request; a
+ * mid-cycle release() — the contamination guard's re-pin —
+ * deliberately keeps it, see 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.
@@ -233,7 +245,9 @@ export function useSizeMorph(
    *  normal close. */
   let revealWatchdog: ReturnType<typeof setTimeout> | null = null;
   /** Resident layer promotion on clip-mode surfaces: applied at arm time
-   *  and cleared on hold/release. Promoting at the STEP-change moment
+   *  and cleared by hold() at the close request (a mid-cycle release() —
+   *  the contamination guard's re-pin — deliberately leaves it for the
+   *  cycle to unwind, see clearResidentWill's callers). 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