@celestia-island/hikari 0.40.11 → 0.40.13

package/package.json

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

package/src/components/HkDrawer.scss

@@ -1,3 +1,5 @@
+@use "./scrim-fade" as sf;
+
 .hk-drawer-overlay {
   position: fixed;
   inset: 0;
@@ -5,18 +7,15 @@
   backdrop-filter: var(--hk-drawer-overlay-blur, blur(6px));
 }
 
-.hk-drawer-overlay-enter-active {
-  transition: opacity var(--hi-duration-normal, 0.3s) var(--hi-ease-out, cubic-bezier(0.16, 1, 0.3, 1));
-}
-
-.hk-drawer-overlay-leave-active {
-  transition: opacity var(--hi-duration-normal, 0.3s) var(--hi-ease-in, cubic-bezier(0.4, 0, 1, 1));
-}
-
-.hk-drawer-overlay-enter-from,
-.hk-drawer-overlay-leave-to {
-  opacity: 0;
-}
+// Overlay enter/leave — fade-only classes from the shared window-layer
+// contract (./_scrim-fade.scss); the panel below owns all the motion.
+@include sf.scrim-fade(
+  "hk-drawer-overlay",
+  $enter-duration: var(--hi-duration-normal, 0.3s),
+  $enter-ease: var(--hi-ease-out, cubic-bezier(0.16, 1, 0.3, 1)),
+  $leave-duration: var(--hi-duration-normal, 0.3s),
+  $leave-ease: var(--hi-ease-in, cubic-bezier(0.4, 0, 1, 1))
+);
 
 .hk-drawer-panel {
   position: fixed;

package/src/components/HkErrorBoundary.test.tsx

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, type Component } from "vue";
+
+import HkErrorBoundary from "./HkErrorBoundary";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountWith(child: Component, props: Record<string, unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () => h(HkErrorBoundary, props, { default: () => h(child) }),
+  });
+  app.config.errorHandler = () => {}; // Silence Vue's own duplicate logging.
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+const Boom = defineComponent({
+  name: "Boom",
+  setup() {
+    throw new TypeError("Cannot read properties of undefined (reading 'length')");
+  },
+  render: () => h("div", "never"),
+});
+
+const Fine = defineComponent({
+  name: "Fine",
+  render: () => h("div", { class: "fine-child" }, "fine"),
+});
+
+afterEach(() => {
+  for (const { app, container } of mounts) {
+    app.unmount();
+    container.remove();
+  }
+  mounts.length = 0;
+  vi.restoreAllMocks();
+});
+
+describe("HkErrorBoundary", () => {
+  it("renders children while nothing throws", () => {
+    const el = mountWith(Fine);
+    expect(el.querySelector(".fine-child")).not.toBeNull();
+    expect(el.querySelector(".hk-error-landing")).toBeNull();
+  });
+
+  it("captures a crash and renders the inline error landing", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const el = mountWith(Boom);
+    await nextTick();
+
+    const landing = el.querySelector(".hk-error-landing");
+    expect(landing).not.toBeNull();
+    expect(landing!.classList.contains("is-inline")).toBe(true);
+    expect(el.querySelector(".hk-error-landing__code")!.textContent).toBe("TypeError");
+    expect(el.querySelector(".hk-error-landing__desc")!.textContent)
+      .toBe("Cannot read properties of undefined (reading 'length')");
+    // Raw details ride in the JSON tree.
+    expect(el.querySelector(".s-tool-json-tree")).not.toBeNull();
+    expect(errorSpy).toHaveBeenCalled();
+  });
+
+  it("falls back to the default headline when no title is given", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const el = mountWith(Boom);
+    await nextTick();
+    expect(el.querySelector(".hk-error-landing__title")!.textContent).toBe("Something went wrong");
+  });
+
+  it("honours a custom title override", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const el = mountWith(Boom, { errorTitle: "发生了错误" });
+    await nextTick();
+    expect(el.querySelector(".hk-error-landing__title")!.textContent).toBe("发生了错误");
+  });
+
+  it("recovers via the retry action", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const el = mountWith(Boom, { retryLabel: "重试" });
+    await nextTick();
+
+    const buttons = Array.from(el.querySelectorAll<HTMLButtonElement>("button"));
+    const retry = buttons.find((b) => b.textContent === "重试");
+    expect(retry).toBeDefined();
+    retry!.click();
+    await nextTick();
+    // The slot rerender throws again, so the landing stays — but the error
+    // ref was cleared and recaptured (boundary proven by a fresh record).
+    expect(el.querySelector(".hk-error-landing")).not.toBeNull();
+  });
+
+  it("keeps the custom fallback render prop contract", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const el = mountWith(Boom, {
+      fallback: (err: string, retry: () => void) => h("div", { class: "custom-fallback" }, [err.slice(0, 10), h("button", { onClick: retry }, "go")]),
+    });
+    await nextTick();
+    expect(el.querySelector(".custom-fallback")).not.toBeNull();
+    expect(el.querySelector(".hk-error-landing")).toBeNull();
+  });
+});

package/src/components/HkErrorBoundary.tsx

@@ -1,14 +1,38 @@
-import { Copy, RefreshCw, TriangleAlert as AlertTriangle } from "lucide-vue-next";
-import { defineComponent, onErrorCaptured, ref, type PropType, type VNode } from "vue";
-
-
+import { Copy, RefreshCw } from "lucide-vue-next";
+import { computed, defineComponent, onErrorCaptured, ref, type PropType, type VNode } from "vue";
 
 import { useClipboard } from "../runtime/useClipboard";
 import { useI18n } from "../i18n/context";
 import HButton from "./HkButton";
-import HScrollContainer from "./HkScrollContainer";
-import "./HkErrorBoundary.scss";
+import { HkErrorLanding } from "./HkErrorLanding";
+import { HkJsonTree } from "./HkJsonTree";
+
+interface CapturedError {
+  name: string;
+  message: string;
+  stack: string;
+}
 
+function captureError(err: unknown): CapturedError {
+  if (err instanceof Error) {
+    return { name: err.name || "Error", message: err.message, stack: err.stack || "" };
+  }
+  return { name: "Error", message: String(err), stack: "" };
+}
+
+function formatError(err: CapturedError): string {
+  return err.stack ? `${err.name}: ${err.message}\n\n${err.stack}` : `${err.name}: ${err.message}`;
+}
+
+/**
+ * HkErrorBoundary — inline crash guard rendering the shared error landing.
+ *
+ * Captures descendant errors via `onErrorCaptured` and stops propagation.
+ * The built-in fallback is the same HkErrorLanding card the family's
+ * full-page takeovers use (inline variant): tone icon, headline, the error
+ * name as the code chip, the message as the description, the raw
+ * name/message/stack in a collapsible JSON tree, plus retry / copy actions.
+ */
 export default defineComponent({
   name: "HkErrorBoundary",
   props: {
@@ -21,15 +45,12 @@ export default defineComponent({
   setup(props, { slots }) {
     const clipboard = useClipboard();
     const { t } = useI18n();
-    const error = ref<string | null>(null);
+    const error = ref<CapturedError | null>(null);
 
     onErrorCaptured((err) => {
-      const msg =
-        err instanceof Error
-          ? `${err.name}: ${err.message}\n\n${err.stack || ""}`
-          : String(err);
-      console.error(`[ErrorBoundary:${props.name}]`, msg);
-      error.value = msg;
+      const captured = captureError(err);
+      console.error(`[ErrorBoundary:${props.name}]`, err);
+      error.value = captured;
       return false;
     });
 
@@ -37,48 +58,49 @@ export default defineComponent({
       error.value = null;
     }
 
-    function copyError() {
-      clipboard.copy(error.value!);
-    }
+    const detailsValue = computed(() => {
+      if (!error.value) return undefined;
+      const record: Record<string, unknown> = {
+        name: error.value.name,
+        message: error.value.message,
+      };
+      if (error.value.stack) record.stack = error.value.stack;
+      if (props.name !== "unknown") record.boundary = props.name;
+      return record;
+    });
 
     return () => {
       if (error.value === null) {
         return slots.default?.();
       }
 
+      const err = error.value;
+
       if (props.fallback) {
-        return props.fallback(error.value, retry);
+        return props.fallback(formatError(err), retry);
       }
 
       return (
-        <div class="hk-error-boundary">
-          <div class="hk-error-boundary-card">
-            <div class="hk-error-boundary-header">
-              <AlertTriangle size={16} class="hk-error-boundary-icon" />
-              <span class="hk-error-boundary-label">{props.errorTitle || t("hikari::errorBoundary.title", "Component Error")}</span>
-              {props.name !== "unknown" && (
-                <span class="hk-error-boundary-tag">{props.name}</span>
-              )}
-            </div>
-            <div class="hk-error-boundary-msg">
-              <div style={{ maxHeight: "12rem" }}>
-                <HScrollContainer>
-                  {error.value}
-                </HScrollContainer>
-              </div>
-            </div>
-            <div class="hk-error-boundary-actions">
-              <HButton variant="ghost" size="sm" onClick={copyError}>
-                <Copy size={12} />
-                {props.copyErrorLabel || t("hikari::errorBoundary.copyError", "Copy Error")}
-              </HButton>
-              <HButton variant="outline" size="sm" onClick={retry}>
+        <HkErrorLanding
+          variant="inline"
+          title={props.errorTitle || t("hikari::errors.defaultTitle", "Something went wrong")}
+          description={err.message}
+          code={err.name}
+        >
+          {{
+            default: () => <HkJsonTree value={detailsValue.value} ariaLabel="stack trace" />,
+            actions: () => [
+              <HButton variant="primary" size="sm" onClick={retry}>
                 <RefreshCw size={12} />
                 {props.retryLabel || t("hikari::errorBoundary.retry", "Retry")}
-              </HButton>
-            </div>
-          </div>
-        </div>
+              </HButton>,
+              <HButton variant="ghost" size="sm" onClick={() => clipboard.copy(formatError(err))}>
+                <Copy size={12} />
+                {props.copyErrorLabel || t("hikari::errorBoundary.copyError", "Copy Error")}
+              </HButton>,
+            ],
+          }}
+        </HkErrorLanding>
       );
     };
   },

package/src/components/HkErrorLanding.scss

@@ -181,6 +181,15 @@
   margin-top: var(--space-16, 1rem);
 }
 
+// Inline variant: the same card without the viewport takeover — used when
+// HkErrorBoundary captures a crash inside a pane and swaps in the landing
+// in-place instead of covering the whole screen.
+.hk-error-landing.is-inline {
+  min-height: 0;
+  padding: var(--space-20, 1.25rem) var(--space-12, 0.75rem);
+  background: transparent;
+}
+
 @media (max-width: 480px) {
   .hk-error-landing__card {
     padding: 1.5rem 1.125rem;

package/src/components/HkErrorLanding.test.tsx

@@ -11,6 +11,7 @@ interface MountOptions {
   code?: string;
   status?: number;
   tone?: "error" | "warning" | "info";
+  variant?: "page" | "inline";
   detailsOpen?: boolean;
   details?: () => ReturnType<typeof h>;
   actions?: () => ReturnType<typeof h>;
@@ -28,6 +29,7 @@ function mountLanding(opts: MountOptions = {}) {
         code: opts.code ?? "",
         status: opts.status,
         tone: opts.tone ?? "error",
+        variant: opts.variant ?? "page",
         detailsOpen: opts.detailsOpen ?? true,
       }, {
         ...(opts.details ? { default: opts.details } : {}),
@@ -99,4 +101,10 @@ describe("HkErrorLanding", () => {
     expect(el.querySelector(".fake-action")).not.toBeNull();
     expect(el.querySelector(".fake-brand")).not.toBeNull();
   });
+
+  it("applies the inline variant class without the page backdrop", () => {
+    const el = mountLanding({ variant: "inline", title: "Boom" });
+    const root = el.querySelector(".hk-error-landing")!;
+    expect(root.classList.contains("is-inline")).toBe(true);
+  });
 });

package/src/components/HkErrorLanding.tsx

@@ -7,6 +7,15 @@ import "./HkErrorLanding.scss";
 /** Visual severity of the landing icon and accents. */
 export type HErrorTone = "error" | "warning" | "info";
 
+/**
+ * Layout variant of the landing.
+ * - `page` (default): owns a full-viewport backdrop — for overlays and
+ *   standalone error pages.
+ * - `inline`: drops the backdrop and viewport height so the same card can
+ *   live inside a pane captured by HkErrorBoundary.
+ */
+export type HErrorLandingVariant = "page" | "inline";
+
 /**
  * HkErrorLanding — the shared full-page error landing.
  *
@@ -33,6 +42,8 @@ export const HkErrorLanding = defineComponent({
     /** HTTP status chip, e.g. 400. */
     status: { type: Number, default: undefined },
     tone: { type: String as PropType<HErrorTone>, default: "error" },
+    /** Layout variant: `page` (viewport backdrop) or `inline` (in-flow card). */
+    variant: { type: String as PropType<HErrorLandingVariant>, default: "page" },
     /** Initial expansion of the raw-details section. */
     detailsOpen: { type: Boolean, default: true },
   },
@@ -48,7 +59,7 @@ export const HkErrorLanding = defineComponent({
     }
 
     return () => (
-      <div class={`hk-error-landing is-${props.tone}`}>
+      <div class={`hk-error-landing is-${props.tone}${props.variant === "inline" ? " is-inline" : ""}`}>
         <div class="hk-error-landing__card">
           {slots.brand?.()}
 

package/src/components/HkModal.scss

@@ -6,6 +6,8 @@
 // colors, spacing, and typography. Component-specific overrides
 // use the --hk-modal-* namespace.
 
+@use "./scrim-fade" as sf;
+
 // ------
 // Root wrapper — positioned via popup-manager z-index
 // ------
@@ -33,20 +35,16 @@
   pointer-events: auto;
 }
 
-.hk-modal-overlay-enter-active {
-  transition: opacity var(--hk-modal-duration, 0.3s)
-    var(--hk-modal-ease-out, cubic-bezier(0.16, 1, 0.3, 1));
-}
-
-.hk-modal-overlay-leave-active {
-  transition: opacity var(--hk-modal-duration, 0.3s)
-    var(--hk-modal-ease-in, cubic-bezier(0.4, 0, 1, 1));
-}
-
-.hk-modal-overlay-enter-from,
-.hk-modal-overlay-leave-to {
-  opacity: 0;
-}
+// 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.
+@include sf.scrim-fade(
+  "hk-modal-overlay",
+  $enter-duration: var(--hk-modal-duration, 0.3s),
+  $enter-ease: var(--hk-modal-ease-out, cubic-bezier(0.16, 1, 0.3, 1)),
+  $leave-duration: var(--hk-modal-duration, 0.3s),
+  $leave-ease: var(--hk-modal-ease-in, cubic-bezier(0.4, 0, 1, 1))
+);
 
 // ------
 // Content frame

package/src/components/HkPopover.scss

@@ -1,4 +1,5 @@
 @use "./menu-item" as mi;
+@use "./scrim-fade" as sf;
 
 .hk-popover-backdrop {
   position: fixed;
@@ -211,6 +212,12 @@
   transform: translateY(100%);
 }
 
+/* Sheet scrim fade — shared window-layer contract (./_scrim-fade.scss):
+ * opacity-only, own transition name, in place. The scrim used to mount
+ * and unmount bare, snapping the dim curtain on and off around the
+ * sliding panel. */
+@include sf.scrim-fade("hk-popover-scrim");
+
 @media (prefers-reduced-motion: reduce) {
   .hk-popover-sheet-enter-active,
   .hk-popover-sheet-leave-active {

package/src/components/HkPopover.tsx

@@ -101,8 +101,12 @@ export default defineComponent({
     // Open/close motion reported into the unified animation context
     // through the same standard hook wiring every surface shares
     // (useSurfaceTransition) — this component was the pattern's
-    // origin and now consumes it like the rest.
-    const anim = useSurfaceTransition(300).hooks();
+    // origin and now consumes it like the rest. Scrim and panel ride
+    // separate named tracks (window-layer contract, ./_scrim-fade.scss)
+    // so the backdrop's fade reports and settles on its own.
+    const surfaceAnim = useSurfaceTransition(300);
+    const anim = surfaceAnim.hooks();
+    const scrimAnim = surfaceAnim.hooks("scrim");
 
     // Suppress native browser tooltips while the popover is open — and
     // not just on the anchor itself: a `title` on ANY descendant fires
@@ -525,13 +529,20 @@ export default defineComponent({
 
     return () => (
       <Teleport to="body">
-        {sheetMode.value && props.modelValue && props.closeOnBackdrop && (
-          <div
-            class="hk-popover-scrim"
-            style={{ zIndex: backdropZ.value }}
-            onClick={() => close()}
-          />
-        )}
+        {/* Window-layer contract (./_scrim-fade.scss): the sheet scrim
+            fades in place under its own transition name — it used to
+            mount and unmount bare, snapping the dim curtain on and off
+            around the sliding panel. z rides the live registration,
+            which outlives the close until the leave fade finishes. */}
+        <Transition name="hk-popover-scrim" appear {...scrimAnim}>
+          {sheetMode.value && props.modelValue && props.closeOnBackdrop ? (
+            <div
+              class="hk-popover-scrim"
+              style={{ zIndex: backdropZ.value }}
+              onClick={() => close()}
+            />
+          ) : null}
+        </Transition>
         {props.backdrop && !sheetMode.value && props.modelValue && (
           <div
             class="hk-popover-backdrop"

package/src/components/HkSelect.scss

@@ -1,5 +1,6 @@
 @use "../tokens";
 @use "./menu-item" as mi;
+@use "./scrim-fade" as sf;
 
 /* HkSelect — popup select component */
 
@@ -401,6 +402,13 @@
   transform: translateY(100%);
 }
 
+/* Scrim fade — the shared window-layer contract (./_scrim-fade.scss):
+ * the dim curtain fades in place under its OWN transition name while the
+ * panel above slides. It once shared this `hk-select-sheet` name, so the
+ * panel's translateY(100%) enter pair dragged the backdrop up from the
+ * bottom edge on phones (2026-09-06 report). */
+@include sf.scrim-fade("hk-select-sheet-scrim");
+
 @media (prefers-reduced-motion: reduce) {
   .hk-select-sheet-enter-active,
   .hk-select-sheet-leave-active,

package/src/components/HkSelectPanel.tsx

@@ -520,7 +520,12 @@ export default defineComponent({
       if (sheetMode.value) {
         return (
           <Teleport to="body">
-            <Transition name="hk-select-sheet" appear {...sheetScrimAnim.hooks("scrim")}>
+            {/* Window-layer contract (./_scrim-fade.scss): the scrim fades
+                in place under its OWN transition name. It once shared the
+                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")}>
               {props.open ? (
                 <div
                   class="hk-select-sheet-scrim"

package/src/components/_scrim-fade.scss

@@ -0,0 +1,59 @@
+// _scrim-fade.scss
+//
+// Window-layer animation contract — the one place every modal-context
+// surface's dim curtain is defined (2026-09-06 user directive).
+//
+// Every windowed surface in hikari (HkModal, HkDrawer, the sheet-docked
+// HkSelectPanel, the sheet-docked HkPopover) is TWO independent layers:
+//
+//   overlay / scrim — position: fixed; inset: 0; painted one band below
+//     its panel. It renders inside its OWN <Transition> whose name ends
+//     in -overlay / -scrim and is NEVER the panel's transition name, and
+//     its classes animate OPACITY ONLY: the dim curtain appears over the
+//     whole viewport at once, in place — it never slides, scales, or
+//     clips, on any breakpoint.
+//   panel / content — its own <Transition> with the surface's pop/slide
+//     name (desktop: height-clip or anchored pop; phones: bottom-sheet
+//     translateY). Transforms live here and nowhere else.
+//
+// Why this file exists: the HkSelectPanel sheet scrim reused the panel's
+// `hk-select-sheet` transition name, so the panel's enter-from pair
+// (`transform: translateY(100%)`) applied to the backdrop too — on phones
+// every second-level dropdown sheet dragged its dim curtain up from the
+// bottom edge instead of fading it in globally. First-level modals were
+// fine (their overlay already had a distinct name), which is what made
+// the drift look deliberate.
+//
+// Surfaces generate their fade classes through `scrim-fade()` so the rule
+// is structural, not per-file discipline. Durations and easings accept
+// any CSS value including var() tokens; the defaults are the sheet family
+// feel (0.25s out / 0.2s in, matching the panel opacity timings).
+// Enforced by scrim-fade.contract.test.ts against the compiled css.
+
+@mixin scrim-fade(
+  $name,
+  $enter-duration: 0.25s,
+  $enter-ease: ease-out,
+  $leave-duration: 0.2s,
+  $leave-ease: ease-in
+) {
+  .#{$name}-enter-active {
+    transition: opacity $enter-duration $enter-ease;
+  }
+
+  .#{$name}-leave-active {
+    transition: opacity $leave-duration $leave-ease;
+  }
+
+  .#{$name}-enter-from,
+  .#{$name}-leave-to {
+    opacity: 0;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .#{$name}-enter-active,
+    .#{$name}-leave-active {
+      transition: none;
+    }
+  }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Source contract for the window-layer animation rules (2026-09-06 user
+ * directive). Every modal-context surface's dim curtain — the
+ * HkModal/HkDrawer overlay, the sheet scrim of HkSelectPanel and
+ * HkPopover — is an INDEPENDENT full-screen layer that fades in and out
+ * in place: opacity only, own transition name, never the panel's.
+ *
+ * The bug this pins shut: the HkSelectPanel sheet scrim reused the
+ * panel's `hk-select-sheet` transition name, so the panel's
+ * `translateY(100%)` enter pair applied to the backdrop too — on phones
+ * every second-level dropdown sheet dragged its dim curtain up from the
+ * bottom edge, while first-level modals (distinct overlay name) looked
+ * right.
+ *
+ * The classes are GENERATED by the shared mixin (_scrim-fade.scss), so
+ * this test compiles each surface stylesheet and pins the emitted css —
+ * it holds no matter how a surface authors its rules, and fails the
+ * moment a curtain regains a transform or a panel loses its slide.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as sass from "sass";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (f: string) => readFileSync(join(here, f), "utf-8");
+
+const CURTAINS: Array<{ file: string; curtain: string }> = [
+  { file: "HkModal.scss", curtain: "hk-modal-overlay" },
+  { file: "HkDrawer.scss", curtain: "hk-drawer-overlay" },
+  { file: "HkSelect.scss", curtain: "hk-select-sheet-scrim" },
+  { file: "HkPopover.scss", curtain: "hk-popover-scrim" },
+];
+
+/** One compiled rule block for `<curtain>-<phase>`, or "" when absent. */
+function rule(css: string, curtain: string, phase: string): string {
+  return css.match(new RegExp(`\\.${curtain}-${phase}[^{]*\\{[^}]*\\}`))?.[0] ?? "";
+}
+
+describe("window-layer scrim fade contract", () => {
+  for (const { file, curtain } of CURTAINS) {
+    it(`${curtain} (${file}) fades in place — opacity only, no transform`, () => {
+      const css = sass.compile(join(here, file)).css;
+      for (const phase of ["enter-active", "leave-active"]) {
+        const block = rule(css, curtain, phase);
+        expect(block, `${curtain}-${phase} rule missing`).toContain("transition: opacity");
+        expect(block, `${curtain}-${phase} must not move the curtain`).not.toContain("transform");
+      }
+      for (const phase of ["enter-from", "leave-to"]) {
+        const block = rule(css, curtain, phase);
+        expect(block, `${curtain}-${phase} rule missing`).toContain("opacity: 0");
+        expect(block, `${curtain}-${phase} must not move the curtain`).not.toContain("transform");
+      }
+    });
+  }
+
+  it("the sheet PANELS keep their slide — the contract never flattens the panel", () => {
+    const select = sass.compile(join(here, "HkSelect.scss")).css;
+    expect(rule(select, "hk-select-sheet", "enter-from")).toContain("translateY(100%)");
+    const popover = sass.compile(join(here, "HkPopover.scss")).css;
+    expect(rule(popover, "hk-popover-sheet", "enter-from")).toContain("translateY(100%)");
+  });
+
+  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]);
+    expect(names).toContain("hk-select-sheet-scrim");
+    expect(names).toContain("hk-select-sheet");
+    expect(src).toContain('sheetScrimAnim.hooks("scrim")');
+  });
+
+  it("the popover sheet scrim fades instead of mounting bare", () => {
+    const src = read("HkPopover.tsx");
+    expect(src).toContain('<Transition name="hk-popover-scrim"');
+    expect(src).toContain('surfaceAnim.hooks("scrim")');
+    // The panel's sheet name stays the slide family — distinct from the scrim.
+    expect(src).toContain('"hk-popover-sheet"');
+  });
+});

package/src/errorReporting/HkErrorReportingOverlay.scss

@@ -0,0 +1,9 @@
+// HkErrorReportingOverlay — fixed full-viewport host for the error landing.
+// Sits above every popup band (modal 1000 / dropdown 2000 / tooltip 3000 /
+// toast 4000): an uncaught-error takeover must never be covered.
+
+.hk-error-reporting-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 5000;
+}