@celestia-island/hikari 0.40.16 → 0.40.19

package/package.json

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

package/src/components/HkColorSchemeEditor.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { createApp, h, nextTick, ref, type Ref } from "vue";
+import { createApp, h, nextTick, onMounted, ref, type Ref } from "vue";
 
 import { registerTokenGroup, useTheme, type TokenGroupDefinition } from "../theme";
 import { HkColorSchemeEditor, type HCustomTheme } from "./HkColorSchemeEditor";
@@ -267,4 +267,27 @@ describe("HkColorSchemeEditor", () => {
     expect(ref.value!.getDraft().dark.onSolidText).toEqual({ r: 255, g: 200, b: 0 });
     expect(ref.value!.getDraft().dark.onSolidIcon).toEqual({ r: 0, g: 200, b: 255 });
   });
+
+  it("hides the built-in name input under showName=false and takes setThemeName", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    let exposed: { getDraft(): { name: string }; setThemeName(n: string): void } | null = null;
+    const app = createApp({
+      setup() {
+        const ed = ref<{ getDraft(): { name: string }; setThemeName(n: string): void } | null>(null);
+        onMounted(() => { exposed = ed.value; });
+        return () => h(HkColorSchemeEditor, { ref: ed, showName: false, initialName: "" });
+      },
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    await settle();
+
+    const label = [...container.querySelectorAll("label")].find((l) =>
+      l.textContent?.includes("Theme name") || l.textContent?.includes("主题名称"),
+    );
+    expect(label).toBeUndefined();
+    exposed!.setThemeName("Host owned name");
+    expect(exposed!.getDraft().name).toBe("Host owned name");
+  });
 });

package/src/components/HkColorSchemeEditor.tsx

@@ -145,6 +145,14 @@ export const HkColorSchemeEditor = defineComponent({
     initialLight: { type: Object as PropType<ThemeSchemeTokens>, default: undefined },
     /** Prefill extension token groups (per mode); defaults to registry defaults. */
     initialGroups: { type: Object as PropType<ThemeTokenGroupModes>, default: undefined },
+    /** Prefill the scheme name input (edit/fork flows); empty by default. */
+    initialName: { type: String, default: "" },
+    /**
+     * Render the built-in name input. Hosts that own the name field
+     * elsewhere (e.g. a "basic" tab above the editor) hide it and feed the
+     * value through `setThemeName()` — getDraft() still carries it.
+     */
+    showName: { type: Boolean, default: true },
   },
   setup(props, { expose }) {
     const { t } = useI18n();
@@ -153,7 +161,7 @@ export const HkColorSchemeEditor = defineComponent({
     // through a computed so config-file labels follow the live locale.
     const activeLocale = computed(() => useI18n().locale);
     const modeTab = ref<string>("dark");
-    const themeName = ref("");
+    const themeName = ref(props.initialName ?? "");
 
     const dark = reactive<ThemeSchemeTokens>({ ...defaultDark });
     const light = reactive<ThemeSchemeTokens>({ ...defaultLight });
@@ -196,7 +204,7 @@ export const HkColorSchemeEditor = defineComponent({
 
     function reset(): void {
       modeTab.value = useTheme().effectiveMode.value;
-      themeName.value = t("hikari::theme.customThemeName");
+      themeName.value = props.initialName ?? t("hikari::theme.customThemeName");
       Object.assign(dark, props.initialDark ?? defaultDark);
       Object.assign(light, props.initialLight ?? defaultLight);
       // Optional slots: a legacy prefill omitting them must reset to white
@@ -212,7 +220,11 @@ export const HkColorSchemeEditor = defineComponent({
 
     onMounted(() => reset());
 
-    expose({ reset, getDraft });
+    function setThemeName(name: string): void {
+      themeName.value = name;
+    }
+
+    expose({ reset, getDraft, setThemeName });
 
     watch(
       () => [
@@ -355,12 +367,14 @@ export const HkColorSchemeEditor = defineComponent({
 
     return () => (
       <div class="s-scheme-dialog">
-        <HInput
-          modelValue={themeName.value}
-          onUpdate:modelValue={(v: string) => { themeName.value = v; }}
-          label={t("hikari::theme.themeName")}
-          placeholder={t("hikari::theme.customThemeName")}
-        />
+        {props.showName && (
+          <HInput
+            modelValue={themeName.value}
+            onUpdate:modelValue={(v: string) => { themeName.value = v; }}
+            label={t("hikari::theme.themeName")}
+            placeholder={t("hikari::theme.customThemeName")}
+          />
+        )}
         <HTabs
           variant="segmented"
           class="s-scheme-mode-switch"

package/src/components/HkDrawer.tsx

@@ -6,7 +6,6 @@ import {
   onMounted,
   ref,
   Teleport,
-  Transition,
   watch,
   type PropType,
 } from "vue";
@@ -19,6 +18,7 @@ import { usePopupManager } from "../runtime/usePopupManager";
 import { createBackGuard } from "../runtime/backStack";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
+import { useSurfaceMachine } from "../composables/useSurfaceMachine";
 import HIconButton from "./HkIconButton";
 import HIcon from "./HkIcon";
 import "./window-close.scss";
@@ -57,10 +57,9 @@ export default defineComponent({
     const { t } = useI18n();
     const manager = usePopupManager();
     // Open/close motion reported into the unified animation context
-    // (animationBus) — scrim and sliding panel on separate tracks.
-    const surf = useSurfaceTransition(320);
-    const scrimHooks = surf.hooks("scrim");
-    const panelHooks = surf.hooks("panel");
+    // (animationBus) — one track for the whole surface, armed on the
+    // machine's animation-phase edges.
+    const surfTrack = useSurfaceTransition(320).track("surface");
     const overlayHook = useOverlay({
       name: "hk-drawer",
       // A global closeAll() must be able to actually close this drawer
@@ -89,25 +88,6 @@ export default defineComponent({
       bodyScrollbar = null;
     }
 
-    watch(() => props.modelValue, (open) => {
-      if (unmounted) return;
-      if (open) {
-        void nextTick(() => {
-          if (!props.modelValue || !bodyRef.value) return;
-          detachBodyScrollbar();
-          // The wrapper (not the panel) is the track host: the panel also
-          // contains the header/footer bands, and rails spanning those
-          // would light up in the wrong place.
-          bodyScrollbar = attachOverlayScrollbars(bodyRef.value, {
-            axis: "vertical",
-            host: bodyWrapRef.value,
-          });
-        });
-      } else {
-        detachBodyScrollbar();
-      }
-    });
-
     /**
      * Window-first back priority: while this drawer is the topmost open
      * window, the back gesture closes it instead of navigating the
@@ -121,6 +101,80 @@ export default defineComponent({
       },
     });
 
+    // ── Surface lifecycle machine ─────────────────────────────────────
+    // One machine drives the overlay scrim and the sliding panel — the
+    // layers are outputs of the shared phase, so the divergent-layer
+    // states of the two-<Transition> era are unrepresentable (see
+    // runtime/surfaceMachine.ts). The panel prefix follows the side
+    // prop; all four sides share the same 0.3s CSS timing.
+    const overlayEl = ref<HTMLElement>();
+    const machine = useSurfaceMachine({
+      layers: [
+        // Budgets are the starvation-era bounds over the SCSS truths
+        // (overlay 0.3s/0.3s, panel slides 0.3s/0.3s); the driver probes
+        // the live CSS durations and tightens them.
+        { prefix: "hk-drawer-overlay", el: () => overlayEl.value, enterMs: () => 320, leaveMs: () => 320 },
+        { prefix: "hk-drawer-left", el: () => panelRef.value, enterMs: () => 320, leaveMs: () => 320 },
+        { prefix: "hk-drawer-right", el: () => panelRef.value, enterMs: () => 320, leaveMs: () => 320 },
+        { prefix: "hk-drawer-top", el: () => panelRef.value, enterMs: () => 320, leaveMs: () => 320 },
+        { prefix: "hk-drawer-bottom", el: () => panelRef.value, enterMs: () => 320, leaveMs: () => 320 },
+      ],
+      onPhase: (from, to, event) => {
+        if (to === "openingFrom") {
+          surfTrack.run();
+          cleanup();
+          // Register with the drawer title so the modal-stack breadcrumb
+          // labels this layer by name — a drawer is a window on every
+          // form factor and must never fall back to a generic label.
+          handle.value = manager.register("drawer", true, props.title);
+          overlayHook.open();
+          previouslyFocused = document.activeElement as HTMLElement | null;
+          if (backGuardEnabled() && backGuard.entries === 0) {
+            backGuard.push();
+          }
+          // Scrollbar chrome mounts with the panel (was the modelValue
+          // watcher's open arm, nextTick after the DOM lands).
+          void nextTick(() => {
+            // props.modelValue (not machine.mounted): a same-tick
+            // open→close flap is already in closingFrom — still mounted —
+            // and must not attach a scrollbar onto the dying surface.
+            if (!props.modelValue || !bodyRef.value) return;
+            detachBodyScrollbar();
+            // The wrapper (not the panel) is the track host: the panel
+            // also contains the header/footer bands, and rails spanning
+            // those would light up in the wrong place.
+            bodyScrollbar = attachOverlayScrollbars(bodyRef.value, {
+              axis: "vertical",
+              host: bodyWrapRef.value,
+            });
+          });
+        } else if (to === "open") {
+          surfTrack.cancel();
+          const el = panelRef.value;
+          if (el) focusFirst(el);
+        } else if (to === "closingFrom") {
+          surfTrack.run();
+          // Register/unregister WITH the open state so a closed-but-
+          // mounted drawer does not linger in the overlay registry
+          // (isOverlayOpen must reflect reality). The popup manager
+          // handle is torn down by the finalize edge below or by
+          // cleanup() on unmount.
+          overlayHook.close();
+          backGuard.release();
+          detachBodyScrollbar();
+        } else if (
+          to === "closed" &&
+          (from === "closingFrom" || from === "closingTo") &&
+          // UNMOUNT mid-close is a teardown, not a finalized leave —
+          // afterLeave/focus-restore belong to the close lifecycle only.
+          event !== "UNMOUNT"
+        ) {
+          surfTrack.cancel();
+          onDrawerAfterLeave();
+        }
+      },
+    });
+
     const isVertical = computed(
       () => props.side === "left" || props.side === "right",
     );
@@ -149,11 +203,6 @@ export default defineComponent({
       if (props.closable) close();
     }
 
-    function onDrawerAfterEnter() {
-      const el = panelRef.value;
-      if (el) focusFirst(el);
-    }
-
     function onDrawerAfterLeave() {
       cleanup();
       if (previouslyFocused) {
@@ -174,25 +223,9 @@ export default defineComponent({
       () => props.modelValue,
       (val) => {
         if (unmounted) return;
-        if (val) {
-          cleanup();
-          // Register with the drawer title so the modal-stack breadcrumb
-          // labels this layer by name — a drawer is a window on every
-          // form factor and must never fall back to a generic label.
-          handle.value = manager.register("drawer", true, props.title);
-          overlayHook.open();
-          previouslyFocused = document.activeElement as HTMLElement | null;
-          if (backGuardEnabled() && backGuard.entries === 0) {
-            backGuard.push();
-          }
-        } else {
-          // Register/unregister WITH the open state so a closed-but-mounted
-          // drawer does not linger in the overlay registry (isOverlayOpen
-          // must reflect reality). The popup manager handle is torn down by
-          // the leave transition or by cleanup() on unmount.
-          overlayHook.close();
-          backGuard.release();
-        }
+        // The machine owns every visual/registry consequence on its
+        // phase edges; this watcher is purely the event feed.
+        machine.send(val ? "OPEN" : "CLOSE");
       },
       { immediate: true },
     );
@@ -231,42 +264,22 @@ export default defineComponent({
       cleanup();
     });
 
-    return () => (
+    return () => {
+      if (!machine.mounted.value) return null;
+      const panelPrefix = `hk-drawer-${props.side}`;
+      return (
       <Teleport to="body">
-        <Transition
-          name="hk-drawer-overlay"
-          appear
-          onBeforeEnter={scrimHooks.onBeforeEnter}
-          onAfterEnter={scrimHooks.onAfterEnter}
-          onBeforeLeave={scrimHooks.onBeforeLeave}
-          onAfterLeave={scrimHooks.onAfterLeave}
-        >
-          {props.modelValue && props.overlay ? (
-            <div
-              class="hk-drawer-overlay"
-              style={{ zIndex: overlayZ.value }}
-              onClick={onOverlayClick}
-            />
-          ) : null}
-        </Transition>
-        <Transition
-          name={`hk-drawer-${props.side}`}
-          appear
-          onBeforeEnter={panelHooks.onBeforeEnter}
-          onAfterEnter={() => {
-            panelHooks.onAfterEnter();
-            onDrawerAfterEnter();
-          }}
-          onBeforeLeave={panelHooks.onBeforeLeave}
-          onAfterLeave={() => {
-            panelHooks.onAfterLeave();
-            onDrawerAfterLeave();
-          }}
-        >
-          {props.modelValue ? (
-            <div
+        {props.overlay ? (
+          <div
+            ref={overlayEl}
+            class={["hk-drawer-overlay", ...machine.classesFor("hk-drawer-overlay")]}
+            style={{ zIndex: overlayZ.value }}
+            onClick={onOverlayClick}
+          />
+        ) : null}
+        <div
               ref={panelRef}
-              class={["hk-drawer-panel", `hk-drawer-${props.side}`, props.panelClass]}
+              class={["hk-drawer-panel", `hk-drawer-${props.side}`, props.panelClass, ...machine.classesFor(panelPrefix)]}
               style={panelStyle.value}
               role="dialog"
               aria-label={props.title}
@@ -304,9 +317,8 @@ export default defineComponent({
                 <div class="hk-drawer-footer">{slots.footer()}</div>
               ) : null}
             </div>
-          ) : null}
-        </Transition>
       </Teleport>
-    );
+      );
+    };
   },
 });

package/src/components/HkModal.enter-watchdog.test.tsx

@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkModal from "./HkModal";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(async () => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+/** Freeze rAF entirely — Vue's <Transition> engine double-raf's the
+ *  enter-from → enter-to class flip, so a frozen rAF reproduces the
+ *  occluded-webview pathology exactly: the enter can NEVER complete on
+ *  its own, the from-pair (opacity: 0 / translateY(100%)) freezes on the
+ *  layer, and only the enter watchdog can repair it. Mirror of the
+ *  leave-completion test's freezeRaf. */
+function freezeRaf(): void {
+  vi.stubGlobal("requestAnimationFrame", (_cb: FrameRequestCallback) => 0 as unknown as number);
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+}
+
+/** Mount an open modal wired to an `open` ref we can flip from the test. */
+async function mountOpenModal() {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const open = ref(true);
+  const afterLeaveEvents: number[] = [];
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkModal, {
+          modelValue: open.value,
+          closable: true,
+          "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+          onAfterLeave: () => { afterLeaveEvents.push(1); },
+        }, { default: () => h("div", "content") });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  await nextTick();
+  return {
+    open,
+    afterLeaveEvents,
+    unmount: () => { app.unmount(); },
+  };
+}
+
+describe("HkModal enter-class watchdog", () => {
+  // Regression for the 2026-09 mobile report: a starved enter froze the
+  // scrim's enter-from pair (opacity: 0) while the panel stayed open —
+  // the dim curtain vanished, and the eventual close flashed it back at
+  // full opacity (the "black rectangle"). The watchdog must strip the
+  // stuck classes on BOTH layers within its budget while the modal stays
+  // open and functional.
+  it("strips frozen enter classes on overlay and content within the budget", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    await mountOpenModal();
+
+    const overlay = document.querySelector<HTMLElement>(".hk-modal-overlay");
+    const content = document.querySelector<HTMLElement>(".hk-modal-content");
+    expect(overlay).not.toBeNull();
+    expect(content).not.toBeNull();
+    // The frozen enter left its from-pair on both layers.
+    expect(overlay!.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
+    expect(content!.classList.contains("hk-modal-content-enter-from")).toBe(true);
+
+    // Past every budget both layers rest at their open state — no
+    // frozen classes survive. (Environments without computed CSS
+    // durations complete even sooner via the probe; the property under
+    // test is the BOUND, not the exact frame.)
+    await vi.advanceTimersByTimeAsync(700);
+    // Both layers snapped to their resting (class-less) state.
+    expect(overlay!.className).toBe("hk-modal-overlay");
+    expect(content!.className).toBe("hk-modal-content");
+    // …and the surface is still open and intact.
+    expect(document.querySelector(".hk-modal-content")).not.toBeNull();
+  });
+
+  it("leaves a healthy enter untouched (watchdog disarmed on completion)", async () => {
+    // Real rAF: the enter completes on its own, the after-enter disarms
+    // the watchdog, and no strip ever fires past the budget.
+    vi.useFakeTimers();
+    await mountOpenModal();
+    await vi.advanceTimersByTimeAsync(700);
+
+    const overlay = document.querySelector<HTMLElement>(".hk-modal-overlay");
+    expect(overlay).not.toBeNull();
+    expect(Array.from(overlay!.classList).some((c) => c.startsWith("hk-modal-overlay-"))).toBe(
+      false,
+    );
+  });
+
+  it("a repaired modal still closes normally afterwards", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { open } = await mountOpenModal();
+    await vi.advanceTimersByTimeAsync(700);
+    expect(document.querySelector(".hk-modal-content")).not.toBeNull();
+
+    open.value = false;
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(700);
+    await nextTick();
+    expect(document.querySelector(".hk-modal-content")).toBeNull();
+    expect(document.querySelector(".hk-modal-overlay")).toBeNull();
+  });
+});
+
+describe("HkModal teardown during the leave window", () => {
+  // The machine's UNMOUNT edge walks closing* → closed; that must be a
+  // TEARDOWN, never a finalized leave — afterLeave/focus-restore belong
+  // to the close lifecycle (the machine's unmount hook runs before this
+  // component's onBeforeUnmount flips the `unmounted` guard).
+  it("does not emit afterLeave when unmounted mid-close", async () => {
+    vi.useFakeTimers();
+    const rig = await mountOpenModal();
+    await vi.advanceTimersByTimeAsync(700); // at open rest
+    expect(rig.afterLeaveEvents).toHaveLength(0);
+
+    rig.open.value = false;
+    await nextTick();
+    // Mid-leave teardown (route change, parent v-if) inside the ~540ms
+    // closing window.
+    rig.unmount();
+    expect(rig.afterLeaveEvents).toHaveLength(0);
+  });
+});
+
+describe("HkModal enter-class watchdog across an interrupted leave", () => {
+  // The exact field-report sequence (2026-09-07 recording, f108-f112):
+  // the modal started closing (scrim fading out), a reopen patched over
+  // the still-live leave on the SAME element, and rAF starvation froze
+  // the re-enter's from-pair — the scrim stayed invisible for seconds
+  // and the eventual close flashed it back at full opacity. The
+  // watchdog must repair both layers of the reopened surface.
+  it("repairs a reopen that froze mid-re-enter on the same element", async () => {
+    vi.useFakeTimers();
+    // Phase 1: open with WORKING rAF so the initial enter completes.
+    const { open } = await mountOpenModal();
+    await vi.advanceTimersByTimeAsync(700);
+    await nextTick();
+
+    // Phase 2: starve rAF, start a close, and reopen on the microtask
+    // boundary — the leave deadline cannot have fired yet, so the
+    // reopen patches over the still-live leave (the recording's
+    // f108-f112 churn).
+    freezeRaf();
+    open.value = false;
+    await nextTick();
+    open.value = true;
+    await nextTick();
+
+    const overlay = document.querySelector<HTMLElement>(".hk-modal-overlay")!;
+    const content = document.querySelector<HTMLElement>(".hk-modal-content")!;
+    expect(overlay).not.toBeNull();
+    expect(content).not.toBeNull();
+
+    // Past every budget the surface rests fully open with no frozen
+    // classes — repaired, and closing afterwards runs a NORMAL leave
+    // (fade from visible) instead of the full-opacity pop.
+    await vi.advanceTimersByTimeAsync(700);
+    expect(overlay.className).toBe("hk-modal-overlay");
+    expect(content.className).toBe("hk-modal-content");
+    // The surface is still open, and closing it afterwards runs a NORMAL
+    // leave (fade from visible) instead of the full-opacity pop.
+    open.value = false;
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(700);
+    await nextTick();
+    expect(document.querySelector(".hk-modal-content")).toBeNull();
+    expect(document.querySelector(".hk-modal-overlay")).toBeNull();
+  });
+});

package/src/components/HkModal.transition-completion.test.tsx

@@ -61,7 +61,7 @@ describe("HkModal leave-completion watchdog", () => {
   // full reload escaped it. The watchdog must finalize within its
   // budget, unmount both surface layers, and emit afterLeave exactly
   // the way a real transition would.
-  it("force-finalizes a stalled leave within the watchdog budget", async () => {
+  it("force-finalizes a stalled leave within the deadline budget", async () => {
     vi.useFakeTimers();
     freezeRaf();
     const { open, afterLeaveEvents } = await mountOpenModal();
@@ -69,12 +69,12 @@ describe("HkModal leave-completion watchdog", () => {
 
     open.value = false;
     await nextTick();
-    // Just inside the budget nothing else can have completed the leave.
-    await vi.advanceTimersByTimeAsync(590);
-    await nextTick();
-    expect(document.querySelector(".hk-modal-content")).not.toBeNull();
-
-    await vi.advanceTimersByTimeAsync(100);
+    // Past the machine's deadline budget the surface must be gone even
+    // though not a single frame or transitionend ever arrived — the
+    // timer column alone finalizes the leave (environments with live
+    // CSS durations exercise the full window; without them the probe
+    // completes even sooner — the property is the BOUND).
+    await vi.advanceTimersByTimeAsync(700);
     await nextTick();
     expect(document.querySelector(".hk-modal-content")).toBeNull();
     expect(document.querySelector(".hk-modal-overlay")).toBeNull();
@@ -97,10 +97,11 @@ describe("HkModal leave-completion watchdog", () => {
 
     open.value = false;
     await nextTick();
-    await vi.advanceTimersByTimeAsync(50); // leave live, nothing finalized
-    open.value = true; // reopen patches over the live leave
+    // Reopen while the leave is still live (before any deadline timer
+    // fires) — the reopen patches over the in-flight close.
+    open.value = true;
     await nextTick();
-    await vi.advanceTimersByTimeAsync(700); // past the watchdog budget
+    await vi.advanceTimersByTimeAsync(700); // past every budget
     await nextTick();
     // The reopened modal must survive both the stale onAfterLeave and
     // the (disarmed) watchdog from the aborted close.
@@ -164,16 +165,17 @@ describe("HkModal leave-completion watchdog", () => {
     expect(afterLeaveEvents).toHaveLength(2);
   });
 
-  // Contract pin: the watchdog must stay armed on the close path and
-  // its budget must stay bigger than any themed CSS leave
-  // (--hk-modal-duration defaults to 0.25s; a theme may raise it). A
-  // refactor that drops the arming — or shrinks the budget under the
-  // CSS timing — silently re-opens the frozen-modal failure mode.
-  it("pins the watchdog wiring and budget in the source", () => {
+  // Contract pin: the lifecycle machine owns finalization now. Its
+  // layer budgets must stay ≥ the themed CSS durations
+  // (--hk-modal-duration defaults to 0.3s; a theme may raise it) — a
+  // refactor that shrinks a budget under the CSS timing would cut the
+  // leave short, and one that drops the machine wiring re-opens the
+  // frozen-modal failure mode.
+  it("pins the machine wiring and deadline budgets in the source", () => {
     const src = readFileSync(join(here, "HkModal.tsx"), "utf-8");
-    expect(src).toContain("const LEAVE_WATCHDOG_MS = 600;");
-    expect(src).toContain("if (shouldRender.value) armLeaveWatchdog();");
-    expect(src).toContain("disarmLeaveWatchdog();");
+    expect(src).toContain("useSurfaceMachine({");
+    expect(src).toContain('{ prefix: "hk-modal-overlay", el: () => overlayEl.value, enterMs: () => 320, leaveMs: () => 340 }');
+    expect(src).toContain('{ prefix: "hk-modal-content", el: () => contentRef.value, enterMs: () => 320, leaveMs: () => 300 }');
     expect(src).toContain("onAfterLeaveFinalize();");
   });
 });