@celestia-island/hikari 0.40.16 → 0.40.18

package/package.json

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

package/src/components/HkColorSchemeEditor.tsx

@@ -145,6 +145,8 @@ 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: "" },
   },
   setup(props, { expose }) {
     const { t } = useI18n();
@@ -153,7 +155,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 +198,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

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

@@ -0,0 +1,160 @@
+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 Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkModal, {
+          modelValue: open.value,
+          closable: true,
+          "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+        }, { default: () => h("div", "content") });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  await nextTick();
+  return { open };
+}
+
+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);
+
+    // Just inside the budget nothing has been repaired yet.
+    await vi.advanceTimersByTimeAsync(590);
+    expect(overlay!.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(100);
+    // 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(50);
+
+    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 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(50);
+    await nextTick();
+
+    // Phase 2: starve rAF, start a close, and reopen while the leave is
+    // still live — the re-enter freezes at its from-pair.
+    freezeRaf();
+    open.value = false;
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(120); // leave live, nothing finalized
+    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();
+    // The frozen re-enter left its from-pair on both layers (the scrim
+    // invisible at opacity 0 while the surface is logically open).
+    expect(overlay.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
+    expect(content.classList.contains("hk-modal-content-enter-from")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(590);
+    expect(overlay.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(100);
+    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.tsx

@@ -19,6 +19,7 @@ import { useOverlay } from "../runtime/useOverlay";
 import { usePopupManager } from "../runtime/usePopupManager";
 import { createBackGuard } from "../runtime/backStack";
 import { scheduleFrame, type AnimationHandle } from "../runtime/animationBus";
+import { armTransitionClassWatchdog, stripTransitionClasses } from "../runtime/transitionWatchdog";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSizeMorph } from "../composables/useSizeMorph";
@@ -180,6 +181,7 @@ export default defineComponent({
     });
 
     const handle = ref<{ id: string; zIndex: number } | null>(null);
+    const overlayRef = ref<HTMLElement>();
     const bodyRef = ref<HTMLElement>();
     const contentRef = ref<HTMLElement>();
     /** Natural-height probe inside the scroll container: the body's
@@ -229,6 +231,24 @@ export default defineComponent({
       }
     }
 
+    // ── Enter-class watchdog ──────────────────────────────────────────
+    // The leave side above bounds rAF starvation for the CLOSE; the enter
+    // side has no such guard. A starved enter freezes the from-pair on
+    // the layer (scrim at opacity: 0 while the panel floats above it),
+    // and the eventual close then flashes the resurrected curtain at full
+    // opacity — the mobile "black rectangle" report (2026-09). Each layer
+    // (overlay, content) arms on its before-enter and strips stuck
+    // enter classes once the same budget lapses; normal enters disarm.
+    let overlayEnterGuard: (() => void) | null = null;
+    let contentEnterGuard: (() => void) | null = null;
+
+    function disarmEnterGuards(): void {
+      overlayEnterGuard?.();
+      overlayEnterGuard = null;
+      contentEnterGuard?.();
+      contentEnterGuard = null;
+    }
+
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
     const contentZ = computed(() => (handle.value?.zIndex ?? 0) + 1);
     const resolvedWidth = computed(() => resolveModalWidth(props.width));
@@ -319,6 +339,7 @@ export default defineComponent({
       if (unmounted || props.modelValue || leaveFinalized) return;
       leaveFinalized = true;
       disarmLeaveWatchdog();
+      disarmEnterGuards();
       if (handle.value) {
         manager.unregister(handle.value.id);
         handle.value = null;
@@ -639,6 +660,9 @@ export default defineComponent({
           // (e.g. immediate), clean up now.
           overlay.close();
           backGuard.release();
+          // The enter cycles are dead the moment the surface starts
+          // closing — their guards must not fire into the leave.
+          disarmEnterGuards();
           // Bound the Transition leave: if rAF starvation froze the
           // class flip, the watchdog finalizes in the watchdog's place
           // (see LEAVE_WATCHDOG_MS above). Only an actually-mounted
@@ -678,6 +702,7 @@ export default defineComponent({
     onBeforeUnmount(() => {
       unmounted = true;
       disarmLeaveWatchdog();
+      disarmEnterGuards();
       detachBodyScrollbar();
       teardownWindowed();
       teardownAutoFollow();
@@ -731,13 +756,40 @@ export default defineComponent({
             <Transition
               name="hk-modal-overlay"
               appear
-              onBeforeEnter={overlayHooks.onBeforeEnter}
-              onAfterEnter={overlayHooks.onAfterEnter}
+              onBeforeEnter={(el: Element) => {
+                overlayHooks.onBeforeEnter();
+                // A prior interrupted cycle can stamp stale classes on a
+                // recycled node — never enter from a frozen transition.
+                stripTransitionClasses(el as HTMLElement, "hk-modal-overlay");
+                overlayEnterGuard?.();
+                overlayEnterGuard = armTransitionClassWatchdog(
+                  el as HTMLElement,
+                  "hk-modal-overlay",
+                  () => !unmounted && !!props.modelValue,
+                );
+              }}
+              onAfterEnter={(el: Element) => {
+                overlayHooks.onAfterEnter();
+                // Stale after-enters from an interrupted cycle (Vue fires
+                // them without a cancelled flag) must not disarm the live
+                // cycle's guard — only the current element's completion.
+                if (el === overlayRef.value) {
+                  overlayEnterGuard?.();
+                  overlayEnterGuard = null;
+                }
+              }}
+              onEnterCancelled={() => {
+                overlayHooks.onEnterCancelled();
+                overlayEnterGuard?.();
+                overlayEnterGuard = null;
+              }}
               onBeforeLeave={overlayHooks.onBeforeLeave}
               onAfterLeave={overlayHooks.onAfterLeave}
+              onLeaveCancelled={overlayHooks.onLeaveCancelled}
             >
               {props.modelValue && (
                 <div
+                  ref={overlayRef}
                   class="hk-modal-overlay"
                   onClick={onOverlayClick}
                 />
@@ -746,13 +798,34 @@ export default defineComponent({
             <Transition
               name="hk-modal-content"
               appear
-              onBeforeEnter={contentHooks.onBeforeEnter}
-              onAfterEnter={() => {
+              onBeforeEnter={(el: Element) => {
+                contentHooks.onBeforeEnter();
+                stripTransitionClasses(el as HTMLElement, "hk-modal-content");
+                contentEnterGuard?.();
+                contentEnterGuard = armTransitionClassWatchdog(
+                  el as HTMLElement,
+                  "hk-modal-content",
+                  () => !unmounted && !!props.modelValue,
+                );
+              }}
+              onAfterEnter={(el: Element) => {
                 contentHooks.onAfterEnter();
-                onAfterEnter();
-                // Size morphs arm once the open choreography finished —
-                // pinning during enter would override its height reveal.
-                morph.start();
+                // Identity gate: a stale after-enter from an interrupted
+                // cycle must neither disarm the live guard nor re-run the
+                // open side effects (focus, morph arming).
+                if (el === contentRef.value) {
+                  contentEnterGuard?.();
+                  contentEnterGuard = null;
+                  onAfterEnter();
+                  // Size morphs arm once the open choreography finished —
+                  // pinning during enter would override its height reveal.
+                  morph.start();
+                }
+              }}
+              onEnterCancelled={() => {
+                contentHooks.onEnterCancelled();
+                contentEnterGuard?.();
+                contentEnterGuard = null;
               }}
               onBeforeLeave={() => {
                 contentHooks.onBeforeLeave();
@@ -763,6 +836,7 @@ export default defineComponent({
                 contentHooks.onAfterLeave();
                 onAfterLeaveFinalize();
               }}
+              onLeaveCancelled={contentHooks.onLeaveCancelled}
             >
               {props.modelValue && (
                 <div

package/src/components/HkSelectPanel.test.tsx

@@ -664,3 +664,59 @@ describe("HkSelectPanel desktop popout motion", () => {
     expect(hosts.at(-1)!.textContent).toContain("a");
   });
 });
+
+describe("HkSelectPanel enter-class watchdog (frozen-rAF repair)", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  // Mirror of HkModal.enter-watchdog: a starved enter freezes the from
+  // pair on the sheet's scrim and panel (2026-09 mobile report — the
+  // scrim died invisible and flashed back at full opacity on close).
+  // The watchdog must strip the stuck classes on both layers while the
+  // panel stays open.
+  it("strips frozen enter classes on the sheet scrim and panel within the budget", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", (_cb: FrameRequestCallback) => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    setViewport(375);
+    const { open } = mountPanel();
+    await nextTick();
+    open.value = true;
+    await nextTick();
+
+    const scrim = document.body.querySelector<HTMLElement>(".hk-select-sheet-scrim")!;
+    const panel = document.body.querySelector<HTMLElement>(".hk-select-sheet-panel")!;
+    expect(scrim).toBeTruthy();
+    expect(panel).toBeTruthy();
+    // The frozen enter left its from-pair on both layers.
+    expect(scrim.classList.contains("hk-select-sheet-scrim-enter-from")).toBe(true);
+    expect(panel.classList.contains("hk-select-sheet-enter-from")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(590);
+    expect(scrim.classList.contains("hk-select-sheet-scrim-enter-from")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(100);
+    expect(scrim.classList.contains("hk-select-sheet-scrim-enter-from")).toBe(false);
+    expect(panel.classList.contains("hk-select-sheet-enter-from")).toBe(false);
+    // …and the surface is still open and intact.
+    expect(document.body.querySelector(".hk-select-sheet-panel")).not.toBeNull();
+  });
+
+  it("a repaired sheet still closes normally through its scrim click", async () => {
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", (_cb: FrameRequestCallback) => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    setViewport(375);
+    const { open } = mountPanel();
+    await nextTick();
+    open.value = true;
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(700);
+
+    (document.body.querySelector<HTMLElement>(".hk-select-sheet-scrim"))!.click();
+    await nextTick();
+    expect(open.value).toBe(false);
+  });
+});

package/src/components/HkSelectPanel.tsx

@@ -14,6 +14,7 @@ import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { useOverlay } from "../runtime/useOverlay";
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import { createBackGuard } from "../runtime/backStack";
+import { armTransitionClassWatchdog, stripTransitionClasses } from "../runtime/transitionWatchdog";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSizeMorph } from "../composables/useSizeMorph";
@@ -120,7 +121,11 @@ export default defineComponent({
     const popoutAnim = useSurfaceTransition(250);
     const sheetScrimAnim = useSurfaceTransition(320);
     const sheetPanelAnim = useSurfaceTransition(320);
+    // Stable hook sets (one object per track, hoisted out of handlers).
+    const popoutHooks = popoutAnim.hooks();
+    const sheetScrimHooks = sheetScrimAnim.hooks("scrim");
     const panelRef = ref<HTMLElement>();
+    const sheetScrimRef = ref<HTMLElement>();
     const sheetListRef = ref<HTMLElement>();
     /** Natural-height probe inside the sheet list: the content wrapper
      *  (slot children), whose height is the content's intrinsic height
@@ -131,19 +136,57 @@ export default defineComponent({
     // content growth (a language list gaining rows, filtered options)
     // with the height transition instead of snapping.
     const morph = useSizeMorph(panelRef, sheetContentRef);
+    // Enter-class watchdogs (runtime/transitionWatchdog): a starved enter
+    // freezes the from-pair on a layer — a stuck scrim at opacity: 0 with
+    // the panel floating above it, resurrected as a full-opacity flash on
+    // close (the 2026-09 mobile report). One guard per transition track;
+    // normal enters disarm them.
+    let scrimEnterGuard: (() => void) | null = null;
+    let sheetPanelEnterGuard: (() => void) | null = null;
+    let popoutEnterGuard: (() => void) | null = null;
+
+    function disarmEnterGuards(): void {
+      scrimEnterGuard?.();
+      scrimEnterGuard = null;
+      sheetPanelEnterGuard?.();
+      sheetPanelEnterGuard = null;
+      popoutEnterGuard?.();
+      popoutEnterGuard = null;
+    }
     // Sheet panel transition hooks: the surface transition's own set plus
     // the size-morph lifecycle (arm after enter — pinning during the
-    // slide-up would fight it — and release before the leave). The inner
-    // hooks("panel") call shares the same reported track, so merging is
-    // safe.
+    // slide-up would fight it — and release before the leave). The base
+    // hook set shares the same reported track, so merging is safe.
+    const sheetPanelBaseHooks = sheetPanelAnim.hooks("panel");
     const sheetPanelHooks = {
-      ...sheetPanelAnim.hooks("panel"),
-      onAfterEnter: () => {
-        sheetPanelAnim.hooks("panel").onAfterEnter();
-        morph.start();
+      ...sheetPanelBaseHooks,
+      onBeforeEnter: (el: Element) => {
+        sheetPanelBaseHooks.onBeforeEnter();
+        stripTransitionClasses(el as HTMLElement, "hk-select-sheet");
+        sheetPanelEnterGuard?.();
+        sheetPanelEnterGuard = armTransitionClassWatchdog(
+          el as HTMLElement,
+          "hk-select-sheet",
+          () => props.open,
+        );
+      },
+      onEnterCancelled: () => {
+        sheetPanelBaseHooks.onEnterCancelled();
+        sheetPanelEnterGuard?.();
+        sheetPanelEnterGuard = null;
+      },
+      onAfterEnter: (el: Element) => {
+        sheetPanelBaseHooks.onAfterEnter();
+        // Identity gate: a stale after-enter from an interrupted cycle
+        // must neither disarm the live guard nor re-arm the morph.
+        if (el === panelRef.value) {
+          sheetPanelEnterGuard?.();
+          sheetPanelEnterGuard = null;
+          morph.start();
+        }
       },
       onBeforeLeave: () => {
-        sheetPanelAnim.hooks("panel").onBeforeLeave();
+        sheetPanelBaseHooks.onBeforeLeave();
         morph.stop();
       },
     };
@@ -388,6 +431,9 @@ export default defineComponent({
           window.removeEventListener("resize", onResize);
           detachPanelScrollbar();
           stopDupTitleSync();
+          // Enter cycles died with the open state — their guards must
+          // not fire into the leave transitions.
+          disarmEnterGuards();
           backGuard.release();
           if (handle.value) {
             // Unregister immediately (stacking/breadcrumb must forget the
@@ -412,6 +458,7 @@ export default defineComponent({
       window.removeEventListener("resize", onResize);
       detachPanelScrollbar();
       stopDupTitleSync();
+      disarmEnterGuards();
       overlay.close();
       backGuard.destroy();
       if (handle.value) {
@@ -525,9 +572,38 @@ export default defineComponent({
                 panel's `hk-select-sheet` name, so the panel's
                 translateY(100%) enter pair slid the dim curtain up from
                 the bottom edge on phones (2026-09-06 report). */}
-            <Transition name="hk-select-sheet-scrim" appear {...sheetScrimAnim.hooks("scrim")}>
+            <Transition
+              name="hk-select-sheet-scrim"
+              appear
+              onBeforeEnter={(el: Element) => {
+                sheetScrimHooks.onBeforeEnter();
+                stripTransitionClasses(el as HTMLElement, "hk-select-sheet-scrim");
+                scrimEnterGuard?.();
+                scrimEnterGuard = armTransitionClassWatchdog(
+                  el as HTMLElement,
+                  "hk-select-sheet-scrim",
+                  () => props.open,
+                );
+              }}
+              onAfterEnter={(el: Element) => {
+                sheetScrimHooks.onAfterEnter();
+                if (el === sheetScrimRef.value) {
+                  scrimEnterGuard?.();
+                  scrimEnterGuard = null;
+                }
+              }}
+              onEnterCancelled={() => {
+                sheetScrimHooks.onEnterCancelled();
+                scrimEnterGuard?.();
+                scrimEnterGuard = null;
+              }}
+              onBeforeLeave={sheetScrimHooks.onBeforeLeave}
+              onAfterLeave={sheetScrimHooks.onAfterLeave}
+              onLeaveCancelled={sheetScrimHooks.onLeaveCancelled}
+            >
               {props.open ? (
                 <div
+                  ref={sheetScrimRef}
                   class="hk-select-sheet-scrim"
                   style={{ zIndex: popoutZ.value - 1 }}
                   onClick={close}
@@ -595,7 +671,37 @@ export default defineComponent({
       // after an auto-flip).
       return (
         <Teleport to="body">
-          <Transition name="hk-select-popout" appear {...popoutAnim.hooks()}>
+          <Transition
+            name="hk-select-popout"
+            appear
+            onBeforeEnter={(el: Element) => {
+              popoutHooks.onBeforeEnter();
+              stripTransitionClasses(el as HTMLElement, "hk-select-popout");
+              popoutEnterGuard?.();
+              popoutEnterGuard = armTransitionClassWatchdog(
+                el as HTMLElement,
+                "hk-select-popout",
+                () => props.open,
+              );
+            }}
+            onAfterEnter={(el: Element) => {
+              popoutHooks.onAfterEnter();
+              // Identity-gated disarm: a stale after-enter from an
+              // interrupted cycle must not disarm the live cycle's guard.
+              if (el === popoutHostRef.value) {
+                popoutEnterGuard?.();
+                popoutEnterGuard = null;
+              }
+            }}
+            onEnterCancelled={() => {
+              popoutHooks.onEnterCancelled();
+              popoutEnterGuard?.();
+              popoutEnterGuard = null;
+            }}
+            onBeforeLeave={popoutHooks.onBeforeLeave}
+            onAfterLeave={popoutHooks.onAfterLeave}
+            onLeaveCancelled={popoutHooks.onLeaveCancelled}
+          >
             {props.open ? (
               <div
                 ref={popoutHostRef}

package/src/components/HkThemeToggle.scss

@@ -13,13 +13,21 @@
   height: 1.75rem;
   min-width: 1.75rem;
   padding: 0 var(--space-6, 0.375rem);
-  border: 1px solid var(--border-faint, rgb(var(--color-border) / 12%));
+  /* Host/theme-tunable: borderless chrome sets --hk-theme-toggle-btn-border:
+   * transparent (e.g. the BA brand look). */
+  border: 1px solid var(--hk-theme-toggle-btn-border, var(--border-faint, rgb(var(--color-border) / 12%)));
   background: rgb(var(--color-surface));
   color: rgb(var(--color-text-secondary, var(--color-muted)));
   cursor: pointer;
   transition: background 0.15s ease, color 0.15s ease;
 }
 
+/* Host strip under the mode group (mode-extra slot). */
+.s-theme-mode-extra {
+  margin-top: var(--space-8, 0.5rem);
+  width: 100%;
+}
+
 .s-theme-toggle-btn:hover {
   background: rgb(var(--color-primary) / 12%);
   color: rgb(var(--color-text));

package/src/components/HkThemeToggle.test.ts

@@ -228,6 +228,41 @@ describe("HkThemeToggle color-mode group", () => {
     const activeBtn = document.body.querySelector<HTMLButtonElement>(".s-theme-item-btn[data-active]");
     expect(activeBtn?.querySelector(".s-theme-item-check")).toBeTruthy();
   });
+  it("renders the mode-extra strip under the mode group when provided", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(HkThemeToggle, { externalCustomize: true }, {
+          "mode-extra": () => h("div", { class: "dpi-mark", "data-x": "1" }, "dpi"),
+        }),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    await settle();
+    openMenu(container);
+    await settle();
+
+    const strip = document.body.querySelector(".s-theme-menu .s-theme-mode-extra");
+    expect(strip).toBeTruthy();
+    expect(strip!.querySelector(".dpi-mark")).toBeTruthy();
+    // It sits inside the menu, after the mode row and before the divider.
+    const menu = document.body.querySelector(".s-theme-menu")!;
+    const children = [...menu.children].map((c) => c.className);
+    const extraIdx = children.indexOf("s-theme-mode-extra");
+    expect(extraIdx).toBeGreaterThan(children.indexOf("s-theme-mode-row"));
+    expect(children[extraIdx + 1]).toContain("hk-divider");
+  });
+
+  it("omits the mode-extra strip when no slot is provided", async () => {
+    let container: HTMLElement;
+    const mounted = mountToggle(true);
+    container = mounted.container;
+    await settle();
+    openMenu(container);
+    await settle();
+    expect(document.body.querySelector(".s-theme-menu .s-theme-mode-extra")).toBeNull();
+  });
 });
 
 describe("HkThemeToggle item slots", () => {

package/src/components/HkThemeToggle.tsx

@@ -52,6 +52,10 @@ export interface ThemeItemScope {
  *    it entirely; the built-in custom-delete overlay is suppressed, so
  *    the host renders delete/edit itself where it wants them.
  *
+ * `mode-extra` — a host strip rendered directly under the color-mode
+ * group (before the divider). Mode-adjacent host chrome that is NOT a
+ * theme-editor concern lives here (e.g. display-scale control).
+ *
  * Color-mode group: the unified HTabs strip in segmented (radiogroup)
  * working mode (Auto | Light | Dark) — same pill chrome as every other
  * group. In AUTO mode the Light/Dark halves merge into the strip's
@@ -253,9 +257,16 @@ export const HkThemeToggle = defineComponent({
                     </button>
                   ),
                 }}
-              </HTabs>
+</HTabs>
             </div>
 
+            {/* Host extension point directly under the mode group (P98: the
+                 chest DPI control lives here — mode-adjacent chrome, not a theme
+                 editor tab). Rendered only when the host provides the slot. */}
+            {slots["mode-extra"] ? (
+              <div class="s-theme-mode-extra">{slots["mode-extra"]()}</div>
+            ) : null}
+
             <HDivider spacing="md" />
 
             <div class="s-theme-menu-label">{t("hikari::theme.themes")}</div>

package/src/components/scrim-fade.contract.test.ts

@@ -64,7 +64,9 @@ describe("window-layer scrim fade contract", () => {
 
   it("the select sheet scrim rides a transition name distinct from the panel's", () => {
     const src = read("HkSelectPanel.tsx");
-    const names = Array.from(src.matchAll(/<Transition name="([^"]+)"/g), (m) => m[1]);
+    // \s+ across the attribute list: the tag may be formatted with name
+    // on its own line.
+    const names = Array.from(src.matchAll(/<Transition\s+name="([^"]+)"/g), (m) => m[1]);
     expect(names).toContain("hk-select-sheet-scrim");
     expect(names).toContain("hk-select-sheet");
     expect(src).toContain('sheetScrimAnim.hooks("scrim")');

package/src/composables/useSizeMorph.test.ts

@@ -32,17 +32,19 @@ interface Harness {
   frame: HTMLElement;
   content: HTMLElement;
   setNatural(height: number): void;
+  setContentNatural(height: number): void;
   start(): void;
   stop(): void;
   remeasure(): void;
 }
 
-function mountHarness(initialHeight: number): Harness {
+function mountHarness(initialHeight: number, initialContentHeight = 0): Harness {
   const container = document.createElement("div");
   document.body.appendChild(container);
   let frameEl: HTMLElement | null = null;
   let contentEl: HTMLElement | null = null;
   let natural = initialHeight;
+  let contentNatural = initialContentHeight;
   let morph: ReturnType<typeof useSizeMorph> | null = null;
   const app = createApp({
     setup() {
@@ -68,6 +70,12 @@ function mountHarness(initialHeight: number): Harness {
               ref: (el: unknown) => {
                 content.value = (el as HTMLElement | null) ?? null;
                 contentEl = content.value;
+                if (contentEl) {
+                  Object.defineProperty(contentEl, "offsetHeight", {
+                    configurable: true,
+                    get: () => contentNatural,
+                  });
+                }
               },
               class: "content",
             }, "content"),
@@ -83,6 +91,9 @@ function mountHarness(initialHeight: number): Harness {
     setNatural: (h: number) => {
       natural = h;
     },
+    setContentNatural: (h: number) => {
+      contentNatural = h;
+    },
     start: () => morph!.start(),
     stop: () => morph!.stop(),
     remeasure: () => morph!.remeasure(),
@@ -153,4 +164,92 @@ describe("useSizeMorph", () => {
     h.remeasure();
     expect(h.frame.style.height).toBe("");
   });
+
+  // ── Contamination guard (2026-09 mobile report) ─────────────────────
+  // A remeasure taken under transition-class flex pollution (e.g. a
+  // frozen enter's `flex: 0 0 auto` uncapping the scroll body) reads a
+  // "natural" height far past the content — pinning it locked a 600px
+  // form at 1728px with ~1100px of blank shell. The guard must release
+  // to auto instead of pinning.
+
+  it("releases to auto when the measurement exceeds content plus chrome", async () => {
+    // Rest: 600px frame around 560px content → chrome allowance ≈128px.
+    const h = mountHarness(600, 560);
+    h.start();
+    expect(h.frame.style.height).toBe("600px");
+
+    // Contaminated probe: the frame "naturally" 1728px, content unmoved.
+    h.setNatural(1728);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("");
+    expect(h.frame.style.transition).toBe("");
+  });
+
+  it("recovers and pins again once a clean measurement returns", async () => {
+    const h = mountHarness(600, 560);
+    h.start();
+
+    h.setNatural(1728);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("");
+
+    h.setNatural(520);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("520px");
+  });
+
+  it("still pins when the content probe reads zero (no layout engine)", async () => {
+    // happy-dom-style degenerate probe: the guard cannot validate
+    // anything, so it must not block the pin (pre-guard behavior).
+    const h = mountHarness(160, 0);
+    h.start();
+    expect(h.frame.style.height).toBe("160px");
+
+    h.setNatural(300);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("300px");
+  });
+
+  it("pins legitimate overflow growth (frame capped under content height)", async () => {
+    // Overflow: content taller than the (capped) frame — the delta goes
+    // negative at rest, the allowance floors, and later capped pins
+    // must never trip the guard.
+    const h = mountHarness(700, 900);
+    h.start();
+    expect(h.frame.style.height).toBe("700px");
+
+    h.setNatural(720);
+    h.setContentNatural(1200);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("720px");
+  });
+
+  it("recalibrates the chrome allowance across stop/start cycles", async () => {
+    const h = mountHarness(600, 560);
+    h.start();
+    h.stop();
+
+    // A new open cycle with real chrome of ~200px (frame 700, content 500).
+    h.setNatural(700);
+    h.setContentNatural(500);
+    h.start();
+    expect(h.frame.style.height).toBe("700px");
+
+    // 730px is within content+chrome (500+232) → pins.
+    h.setNatural(730);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("730px");
+
+    // 900px is past it → releases.
+    h.setNatural(900);
+    FakeResizeObserver.instances[0]!.callback();
+    await settle();
+    expect(h.frame.style.height).toBe("");
+  });
 });

package/src/composables/useSizeMorph.ts

@@ -1,5 +1,13 @@
 import { onBeforeUnmount, type Ref } from "vue";
 
+/** Chrome-allowance calibration constants (px): the floor covers a
+ *  standard header+footer+borders stack (and bodies that overflow at
+ *  arm time, where the resting delta goes negative and says nothing
+ *  about chrome); the slack absorbs subpixel/border noise so the guard
+ *  never trips on a legitimate measurement. */
+const CHROME_ALLOWANCE_FLOOR = 96;
+const CHROME_ALLOWANCE_SLACK = 32;
+
 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
@@ -54,6 +62,12 @@ export function useSizeMorph(
   let armed = false;
   /** Last pinned height (px) — the transition's "from" value. */
   let pinned = 0;
+  /** Contamination allowance (px): how far the frame's natural height may
+   *  exceed the content probe at rest — its own chrome (header, footer,
+   *  borders, CSS min-height floors), captured at arm time, floored for
+   *  bodies that overflow at rest, plus subpixel slack. See the guard in
+   *  remeasure(). */
+  let chromeAllowance = CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
 
   function release(): void {
     const f = frame.value;
@@ -61,6 +75,22 @@ export function useSizeMorph(
     pinned = 0;
   }
 
+  /** Calibrate the chrome allowance from the resting (unpinned, enter
+   *  finished) frame — the only moment guaranteed free of transition-class
+   *  flex rules. Never calibrate from a remeasure sample: the first
+   *  remeasure can itself be the contaminated one (a frozen enter leaves
+   *  the flex rules behind when the surface is mid-repair). */
+  function calibrate(): void {
+    const f = frame.value;
+    const c = content.value;
+    if (!f || !c) return;
+    const frameH = f.offsetHeight;
+    const contentH = c.offsetHeight;
+    chromeAllowance = frameH > 0 && contentH > 0 && frameH >= contentH
+      ? Math.max(frameH - contentH, CHROME_ALLOWANCE_FLOOR) + CHROME_ALLOWANCE_SLACK
+      : CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
+  }
+
   function remeasure(): void {
     if (!armed) return;
     const f = frame.value;
@@ -74,7 +104,7 @@ export function useSizeMorph(
     // 3. Flip to the NEW pin under the live transition — the computed
     //    value changes old→new, so the height transition animates.
     // No paint happens between the steps: they run in one task and the
-    // layout flushes are invisible to the screen.
+    //    layout flushes are invisible to the screen.
     const inlineTransition = f.style.transition;
     f.style.transition = "none";
     f.style.height = "";
@@ -85,12 +115,36 @@ export function useSizeMorph(
       f.style.transition = inlineTransition;
       return;
     }
+    // Contamination guard: at rest the frame can only be taller than the
+    // content probe by its own chrome. A natural height past that bound
+    // describes a mid-transition state (e.g. enter/leave-class
+    // `flex: 0 0 auto` rules uncapping the scroll body) that never
+    // exists at rest — pinning it would lock a blank shell at the
+    // max-height cap (2026-09 mobile report: a 600px form pinned at
+    // 1728px with ~1100px of empty body). A zero-height probe (no layout
+    // engine, hidden content) validates nothing — fall through and pin.
+    // On a trip, release to auto; the observer re-fires on the next
+    // genuine content change.
+    if (c.offsetHeight > 0 && natural > c.offsetHeight + chromeAllowance) {
+      release();
+      f.style.transition = inlineTransition;
+      return;
+    }
     if (pinned > 0) f.style.height = `${pinned}px`;
     // Flush the old-pin state before re-enabling the transition.
     void f.offsetHeight;
     f.style.transition = inlineTransition;
     f.style.height = `${Math.round(natural)}px`;
     pinned = Math.round(natural);
+    // Self-heal the allowance on every VALIDATED pin: chrome that grew
+    // after calibration (an async footer, a header slot mounting
+    // mid-open) updates the baseline instead of tripping the guard on
+    // the next change and silently disabling the morph for the cycle.
+    const probeH = c.offsetHeight;
+    if (probeH > 0 && natural >= probeH) {
+      chromeAllowance =
+        Math.max(natural - probeH, CHROME_ALLOWANCE_FLOOR) + CHROME_ALLOWANCE_SLACK;
+    }
   }
 
   function onResize(): void {
@@ -114,6 +168,10 @@ export function useSizeMorph(
   function start(): void {
     if (armed) return;
     armed = true;
+    // Calibrate before the first pin: at this point the surface finished
+    // its enter (callers arm in after-enter) and sits at rest, so the
+    // frame-vs-content delta is pure chrome.
+    calibrate();
     if (typeof ResizeObserver === "undefined" || !content.value) {
       remeasure();
       return;
@@ -136,6 +194,9 @@ export function useSizeMorph(
       cancelAnimationFrame(raf);
       raf = 0;
     }
+    // The next start() re-calibrates against whatever chrome that open
+    // cycle carries.
+    chromeAllowance = CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
     release();
   }
 

package/src/runtime/transitionWatchdog.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { armTransitionClassWatchdog, stripTransitionClasses } from "./transitionWatchdog";
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+function makeEl(...classes: string[]): HTMLElement {
+  const el = document.createElement("div");
+  el.className = classes.join(" ");
+  return el;
+}
+
+describe("stripTransitionClasses", () => {
+  it("removes every name-prefixed transition class and keeps the rest", () => {
+    const el = makeEl(
+      "hk-modal-overlay",
+      "hk-modal-overlay-enter-from",
+      "hk-modal-overlay-enter-active",
+      "other-class",
+    );
+    stripTransitionClasses(el, "hk-modal-overlay");
+    expect(el.className).toBe("hk-modal-overlay other-class");
+  });
+
+  it("never strips a class merely containing the name mid-word", () => {
+    const el = makeEl("hk-modal-overlay-v2");
+    stripTransitionClasses(el, "hk-modal-overlay");
+    expect(el.className).toBe("hk-modal-overlay-v2");
+  });
+
+  it("is a no-op on a class-less element", () => {
+    const el = makeEl("hk-modal-overlay");
+    stripTransitionClasses(el, "hk-modal-overlay");
+    expect(el.className).toBe("hk-modal-overlay");
+  });
+});
+
+describe("armTransitionClassWatchdog", () => {
+  it("strips stuck transition classes once the budget lapses while open", () => {
+    vi.useFakeTimers();
+    const el = makeEl(
+      "hk-modal-overlay",
+      "hk-modal-overlay-enter-from",
+      "hk-modal-overlay-enter-active",
+    );
+    armTransitionClassWatchdog(el, "hk-modal-overlay", () => true);
+    vi.advanceTimersByTime(599);
+    expect(el.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
+    vi.advanceTimersByTime(2);
+    expect(el.className).toBe("hk-modal-overlay");
+  });
+
+  it("leaves the element alone once the surface closed (leave owns it)", () => {
+    vi.useFakeTimers();
+    const el = makeEl("hk-modal-overlay", "hk-modal-overlay-enter-from");
+    armTransitionClassWatchdog(el, "hk-modal-overlay", () => false);
+    vi.advanceTimersByTime(1000);
+    expect(el.classList.contains("hk-modal-overlay-enter-from")).toBe(true);
+  });
+
+  it("disarming cancels the strip (a normal enter finalized)", () => {
+    vi.useFakeTimers();
+    const el = makeEl("hk-modal-overlay", "hk-modal-overlay-enter-active");
+    const disarm = armTransitionClassWatchdog(el, "hk-modal-overlay", () => true);
+    disarm();
+    vi.advanceTimersByTime(1000);
+    expect(el.classList.contains("hk-modal-overlay-enter-active")).toBe(true);
+  });
+
+  it("does nothing when no transition class is stuck", () => {
+    vi.useFakeTimers();
+    const el = makeEl("hk-modal-overlay");
+    armTransitionClassWatchdog(el, "hk-modal-overlay", () => true);
+    vi.advanceTimersByTime(1000);
+    expect(el.className).toBe("hk-modal-overlay");
+  });
+});

package/src/runtime/transitionWatchdog.ts

@@ -0,0 +1,73 @@
+// Transition-class repair kit — the enter-side counterpart of HkModal's
+// leave watchdog.
+//
+// A Vue <Transition> flips enter-from → enter-to through rAF and waits on
+// transitionend. When rAF starves (occluded/backgrounded webview — the
+// same pathology the leave watchdog in HkModal bounds), the enter classes
+// FREEZE on the element: the layer keeps `*-enter-from` (opacity: 0,
+// translateY(100%), …) while the surface is logically open. The modal's
+// scrim then stays invisible with the panel floating above it, and the
+// eventual close flashes the resurrected curtain at full opacity — the
+// 2026-09 mobile "black rectangle" report (the leave pair
+// leave-from → leave-to snaps the scrim to opacity: 1 before fading).
+//
+// Two primitives:
+//   stripTransitionClasses — remove every `name-*` transition class so the
+//     element snaps to its resting state (no fade — this is a repair
+//     path, the animation already failed).
+//   armTransitionClassWatchdog — bounded safety net: if the element still
+//     carries `name-enter-*` classes once the budget lapses (larger than
+//     any themed duration), strip them. Normal enters disarm it; a
+//     completed enter is a no-op (the classes are already gone).
+
+/** The exact set of classes Vue's <Transition name=…> stamps on an
+ *  element — matched precisely so a hand-written class that merely
+ *  starts with the name (e.g. `name-v2`) is never touched. */
+const TRANSITION_CLASS_SUFFIXES = [
+  "-enter-from",
+  "-enter-active",
+  "-enter-to",
+  "-leave-from",
+  "-leave-active",
+  "-leave-to",
+] as const;
+
+function transitionClassesOf(el: HTMLElement, name: string): string[] {
+  const names = TRANSITION_CLASS_SUFFIXES.map((suffix) => `${name}${suffix}`);
+  return Array.from(el.classList).filter((cls) => names.includes(cls));
+}
+
+/** Strip all `name-*` transition classes off `el`, snapping it to its
+ *  resting (non-transition) state. Safe on class-less elements. */
+export function stripTransitionClasses(el: HTMLElement, name: string): void {
+  for (const cls of transitionClassesOf(el, name)) el.classList.remove(cls);
+}
+
+/**
+ * Bound a stuck transition: if the element still carries ANY `name-*`
+ * transition class after `budgetMs` while the surface is open (the enter
+ * never finalized — or an interrupted leave left its pair behind — rAF
+ * starvation), strip them so the layer renders in its open state instead
+ * of staying frozen at a from/to pair. The budget is larger than any
+ * themed CSS duration, so a legitimate animation never sees the strip.
+ *
+ * `isStillOpen` gates the repair: once the surface closed, the leave owns
+ * the element and a late strip must not fight it.
+ *
+ * @returns the disarm function (call on after-enter / enter-cancelled /
+ *   close / unmount).
+ */
+export function armTransitionClassWatchdog(
+  el: HTMLElement,
+  name: string,
+  isStillOpen: () => boolean,
+  budgetMs = 600,
+): () => void {
+  const timer = setTimeout(() => {
+    if (!isStillOpen()) return;
+    if (transitionClassesOf(el, name).length > 0) {
+      stripTransitionClasses(el, name);
+    }
+  }, budgetMs);
+  return () => clearTimeout(timer);
+}