@celestia-island/hikari 0.55.316 → 0.55.318

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.316",
+  "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/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.
@@ -153,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))
@@ -443,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
@@ -565,6 +626,7 @@
   .hk-modal-content-leave-to {
     opacity: 0;
     height: auto;
+    will-change: opacity, transform;
     transform: translateY(100%);
   }
 

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

@@ -99,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);
+      }
+    }
+  });
+});