@celestia-island/hikari 0.55.200 → 0.55.202

package/package.json

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

package/src/components/HkAdminHeader.test.tsx

@@ -129,6 +129,28 @@ describe("HkAdminHeader", () => {
     expect(withoutTitle.querySelector("header > div")?.textContent).not.toContain("Dashboard");
   });
 
+  it("renders no avatar trigger when no identity is injected", () => {
+    // 2026-10-24 regression: the trigger rendered unconditionally, so a
+    // host with no identity props got a stray "?" button opening an
+    // empty "Signing in…" menu with a lone sign-out row. The identity
+    // cluster is injection-driven now — no identity, no trigger.
+    const anonymous = mount(headerNode({ username: "", title: "Anywhere" }));
+    expect(avatarButton(anonymous)).toBeNull();
+    // The page title still rides the left wing without the avatar.
+    expect(anonymous.querySelector("header > div")?.textContent).toContain("Anywhere");
+
+    // The pending identity flow is EXPLICIT injection: signingInLabel /
+    // onForceSignOut keep the "?" trigger alive so the force-sign-out
+    // escape stays reachable during a wedged session restore.
+    const pending = mount(headerNode({
+      username: "",
+      signingInLabel: "Signing in…",
+      onForceSignOut: () => {},
+    }));
+    const btn = avatarButton(pending) as HTMLButtonElement;
+    expect(btn.querySelector(".s-user-avatar")?.textContent).toBe("?");
+  });
+
   it("toggles the user dropdown with the profile identity header in menu mode", async () => {
     const c = mount(headerNode({
       userEmail: "alice@example.com",

package/src/components/HkAdminHeader.tsx

@@ -87,6 +87,23 @@ export const HkAdminHeader = defineComponent({
     const avatarModalOpen = ref(false);
     const avatarFailed = ref(false);
 
+    // The identity cluster is INJECTED, not assumed (2026-10-24): the
+    // trigger renders only when the host actually supplied an identity
+    // (username / email / avatar) or explicitly opted into the pending
+    // identity flow (signingInLabel / onForceSignOut — the fetchUser
+    // race machinery whose "?" trigger opens the force-sign-out escape).
+    // A host that passes none of those has no account surface, and the
+    // old unconditional render left it a stray "?" button opening an
+    // empty "Signing in…" menu.
+    const identityMounted = computed(
+      () =>
+        !!props.username ||
+        !!props.userEmail ||
+        !!props.avatarUrl ||
+        props.signingInLabel !== undefined ||
+        props.onForceSignOut !== undefined,
+    );
+
     function onAvatarClick(e: MouseEvent) {
       e.stopPropagation();
       if (props.avatarAction === "drawer") {
@@ -192,35 +209,37 @@ export const HkAdminHeader = defineComponent({
               <Menu size={20} class="s-admin-header-hamburger-icon" />
             </HButton>
           )}
-          <button
-            class="s-admin-header-avatar"
-            aria-label={props.avatarTriggerLabel ?? t("hikari::adminHeader.avatarTrigger", "Account menu")}
-            aria-haspopup={props.avatarAction === "drawer" ? "dialog" : "menu"}
-            aria-expanded={props.avatarAction === "menu" ? userMenuOpen.value : undefined}
-            onClick={onAvatarClick}
-          >
-            {/* Deliberately NO hover veil here: the trigger opens the user
-             *  MENU (the avatar edit lives one row down as the Camera
-             *  item), so a camera overlay would promise click-to-change
-             *  and lie (user report 2026-09-16). */}
-            {props.avatarUrl && !avatarFailed.value ? (
-              <img
-                src={props.avatarUrl}
-                alt={props.username}
-                class="s-admin-header-avatar-img"
-                onError={() => { avatarFailed.value = true; }}
-              />
-            ) : (
-              // Letter fallback on the shared avatar primitive — the
-              // same filled-circle grammar as the chat frontend's
-              // trigger. The old border-2 ring made the console's
-              // avatar read as a different control (user report
-              // 2026-09-12: 前后台头像不一致).
-              <span class="s-user-avatar">
-                {props.username?.charAt(0).toUpperCase() || "?"}
-              </span>
-            )}
-          </button>
+          {identityMounted.value && (
+            <button
+              class="s-admin-header-avatar"
+              aria-label={props.avatarTriggerLabel ?? t("hikari::adminHeader.avatarTrigger", "Account menu")}
+              aria-haspopup={props.avatarAction === "drawer" ? "dialog" : "menu"}
+              aria-expanded={props.avatarAction === "menu" ? userMenuOpen.value : undefined}
+              onClick={onAvatarClick}
+            >
+              {/* Deliberately NO hover veil here: the trigger opens the user
+               *  MENU (the avatar edit lives one row down as the Camera
+               *  item), so a camera overlay would promise click-to-change
+               *  and lie (user report 2026-09-16). */}
+              {props.avatarUrl && !avatarFailed.value ? (
+                <img
+                  src={props.avatarUrl}
+                  alt={props.username}
+                  class="s-admin-header-avatar-img"
+                  onError={() => { avatarFailed.value = true; }}
+                />
+              ) : (
+                // Letter fallback on the shared avatar primitive — the
+                // same filled-circle grammar as the chat frontend's
+                // trigger. The old border-2 ring made the console's
+                // avatar read as a different control (user report
+                // 2026-09-12: 前后台头像不一致).
+                <span class="s-user-avatar">
+                  {props.username?.charAt(0).toUpperCase() || "?"}
+                </span>
+              )}
+            </button>
+          )}
           {/* WHERE am I — the open view's title, not the nickname. The
               1.5 line-height (in the class) keeps descenders (g, y, p)
               inside the truncate clip box: the default text-sm box is

package/src/components/HkAdminShell.test.tsx

@@ -538,4 +538,74 @@ describe("HkAdminShell", () => {
     expect(tripleInner?.style.paddingLeft).toBe("2rem");
     expect(tripleInner?.style.paddingRight).toBe("2rem");
   });
+
+  it("reserves the footer band only when a status bar is actually injected", () => {
+    // 2026-10-24 regression: the body carried
+    // paddingBottom: var(--s-footer-height) unconditionally — a dead 3rem
+    // blank under every console that never mounts a status bar. The
+    // reservation is injection-driven now: the shell's own footer slot
+    // brings it, an explicit prop overrides it, nothing else reserves.
+    setWidth(1024);
+
+    // No footer slot, no prop: NO band.
+    const plain = mount(shellNode(
+      { navTitle: "Navigation" },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    const plainBody = plain.querySelector(".s-admin-shell-body") as HTMLElement;
+    expect(plainBody.style.paddingBottom).toBe("0px");
+    expect(plain.querySelector("footer.s-status-bar")).toBeNull();
+
+    // A filled footer slot renders the fixed .s-status-bar and reserves
+    // its band by default.
+    const withBar = mount(shellNode(
+      { navTitle: "Navigation" },
+      {
+        header: () => null,
+        sidebar: NAV,
+        content: CONTENT,
+        footer: () => h("div", { class: "bar-mock" }, "STATUS"),
+      },
+    ));
+    const barBody = withBar.querySelector(".s-admin-shell-body") as HTMLElement;
+    // A fallback-less var() survives as the direct longhand here — the
+    // shorthand round-trip failures happy-dom shows elsewhere in this
+    // file do not apply to a single-track longhand read.
+    expect(barBody.style.paddingBottom).toBe("var(--s-footer-height)");
+    expect(withBar.querySelector("footer.s-status-bar .bar-mock")).toBeTruthy();
+
+    // An explicit prop overrides BOTH branches: the opt-in for hosts that
+    // pin their own fixed bar outside the shell…
+    const external = mount(shellNode(
+      { navTitle: "Navigation", footerHeight: "3.5rem" },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    expect((external.querySelector(".s-admin-shell-body") as HTMLElement).style.paddingBottom)
+      .toBe("3.5rem");
+    // …and a custom band for hosts that fill the slot anyway. "0px"
+    // explicitly re-kills it.
+    const explicitZero = mount(shellNode(
+      { navTitle: "Navigation", footerHeight: "0px" },
+      {
+        header: () => null,
+        sidebar: NAV,
+        content: CONTENT,
+        footer: () => h("div", { class: "bar-mock" }, "STATUS"),
+      },
+    ));
+    expect((explicitZero.querySelector(".s-admin-shell-body") as HTMLElement).style.paddingBottom)
+      .toBe("0px");
+
+    // The empty string is an EXPLICIT value, not an absent one: `!==`
+    // undefined (not truthiness) is the gate, so "" passes through
+    // verbatim exactly as the old code passed it — same contract the
+    // contentPadding longhand pins below. A truthiness mutant would
+    // reroute "" into the slot branch; this mount catches it.
+    const explicitEmpty = mount(shellNode(
+      { navTitle: "Navigation", footerHeight: "" },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    expect((explicitEmpty.querySelector(".s-admin-shell-body") as HTMLElement).style.paddingBottom)
+      .toBe("");
+  });
 });

package/src/components/HkAdminShell.tsx

@@ -140,7 +140,17 @@ export const HkAdminShell = defineComponent({
      *  1024px "lg" breakpoint; lower it (e.g. 768) for tablet-friendly
      *  admins that keep the sidebar at md widths. */
     mobileBreakpoint: { type: Number, default: 1024 },
-    footerHeight: { type: String, default: "var(--s-footer-height)" },
+    /** Height reserved under the scroll body for a fixed status-bar
+     *  band. INJECTION-DRIVEN (2026-10-24): the reservation tracks
+     *  whether the shell actually renders a status bar — a filled
+     *  `footer` slot (the shell's own fixed `.s-status-bar`) reserves
+     *  `var(--s-footer-height)` by default, and with NO footer slot
+     *  nothing is reserved (`0px`). The old unconditional default
+     *  reserved the band on every host, leaving a dead 3rem blank under
+     *  consoles that never mount a status bar. Hosts that pin their OWN
+     *  fixed bar outside the shell opt back in by passing an explicit
+     *  value (e.g. `"var(--s-footer-height)"`). */
+    footerHeight: { type: String, default: undefined },
     navTitle: { type: String, default: undefined },
     /** Extra class for the mobile nav drawer's panel — lets consumers zero
      *  nested paddings so drawer nav rows and a `userPanel` footer share
@@ -186,6 +196,19 @@ export const HkAdminShell = defineComponent({
 
     const actionBar = provideActionBar();
 
+    // The status-bar band exists only when the shell renders one (the
+    // footer slot) or the host pins its own bar and says so via the prop
+    // — an unreserved shell carries no dead clearance (2026-10-24: the
+    // unconditional default used to blank 3rem under every console that
+    // never mounted a status bar). Computed INSIDE the render (not a
+    // `computed()`): slot PRESENCE is what it reads, and a cached
+    // computed is not reliably invalidated by a slot appearing or
+    // disappearing, while every re-render re-evaluates this line.
+    function footerPad(): string {
+      if (props.footerHeight !== undefined) return props.footerHeight;
+      return slots.footer ? "var(--s-footer-height)" : "0px";
+    }
+
     const toggleHamburger = () => {
       sidebarOpen.value = !sidebarOpen.value;
     };
@@ -215,7 +238,7 @@ export const HkAdminShell = defineComponent({
           </div>
         )}
 
-        <div class="s-admin-shell-body" style={{ paddingBottom: props.footerHeight }}>
+        <div class="s-admin-shell-body" style={{ paddingBottom: footerPad() }}>
           {isDesktop.value && !props.sidebarCollapsed && slots.sidebar && (
             <aside
               style={{

package/src/components/HkSettingsDialog.tsx

@@ -8,6 +8,7 @@ import {
   type PropType,
 } from "vue";
 
+import HkTransitionContainer from "./HkTransitionContainer";
 import HModal from "./HkModal";
 import "./HkSettingsDialog.scss";
 
@@ -124,7 +125,14 @@ export const HkSettingsBody = defineComponent({
           })}
         </nav>
         <div class="hk-settings__pane" ref={paneRef}>
-          {slots[active()]?.()}
+          {/* The section swap runs through the family's standard morph
+              container (audit 2026-10-23): the pane's frame follows the
+              incoming section's height and the contents dissolve, the
+              same mechanism HkTabs panels use. A settings pane is a page
+              slot — it must not hard-cut. */}
+          <HkTransitionContainer swapKey={active()} axis="height">
+            {slots[active()]?.()}
+          </HkTransitionContainer>
         </div>
       </div>
     );

package/src/components/HkTransitionContainer.tsx

@@ -102,8 +102,12 @@ export default defineComponent({
           pendingKey = null;
           if (key !== null) {
             emit("swap", { key, previous: previousKey, durationMs: props.duration });
+            // The handoff consumer reads `previous` to scroll the pane back;
+            // it must be the key we just left, not the one we mounted with
+            // (audit 2026-10-23: it was never reassigned).
+            previousKey = key;
           }
-        }, props.duration + 40);
+        }, motionDuration() + 40);
       });
       observer.observe(stageRef.value);
     }
@@ -119,6 +123,26 @@ export default defineComponent({
       void nextTick(() => observe());
     });
 
+    /**
+     * Reduced motion: the morph runs on an INLINE `transitionDuration`,
+     * which no stylesheet `@media (prefers-reduced-motion)` can override
+     * (inline beats non-important rules) and which the host's
+     * `html[data-css-animations="0"]` pin only covers if the host wired
+     * useReducedMotion() at boot. So the gate lives HERE (audit
+     * 2026-10-23): zero the morph when the OS asks for reduced motion or
+     * the host turned the animation switch off. The dissolve side is
+     * already handled by HkCrossfade's own media query.
+     */
+    function motionDuration(): number {
+      if (typeof window === "undefined") return props.duration;
+      const reduced =
+        typeof window.matchMedia === "function" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+      const switchedOff =
+        document.documentElement.dataset.cssAnimations === "0";
+      return reduced || switchedOff ? 0 : props.duration;
+    }
+
     onBeforeUnmount(() => {
       observer?.disconnect();
       observer = null;
@@ -127,7 +151,7 @@ export default defineComponent({
 
     return () => {
       const Tag = props.tag as "div" | "section" | "main" | "aside";
-      const d = `${props.duration}ms`;
+      const d = `${motionDuration()}ms`;
       return (
         <Tag
           ref={hostRef}

package/src/components/paneSwap.contract.test.ts

@@ -0,0 +1,148 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const componentsDir = here;
+
+/**
+ * Pane-swap contract — the enforcement half of the family's transition
+ * primitives (user audit 2026-10-23).
+ *
+ * THE RULE. A "pane slot" is a container whose visible content is selected
+ * by a state key while the container stays put: tabs, settings sections,
+ * step bodies, view areas. Every such slot must swap through the standard
+ * mechanism — `HkTransitionContainer` (frame morph + dissolve) or
+ * `HkCrossfade` (same-box dissolve) — or a component that composes them
+ * (`HkTabs` panels). The library shipped both primitives and then used
+ * them in exactly ONE place, so the rule was advisory: each surface
+ * re-decided, and two page-scale slots hard-cut while a third
+ * re-implemented the primitives by hand.
+ *
+ * HOW IT IS ENFORCED. Two source scans, because the violation is only
+ * visible in source (the primitives are leaf components; the call site
+ * cannot tell you a div is a page slot):
+ *
+ *  1. every `slots[<state>]?.()` pane render must be either routed through
+ *     HkTransitionContainer/HkCrossfade, or listed below with a reason —
+ *     an explicit-exception list, not a ban;
+ *  2. every pane-vocabulary `@keyframes` (names carrying pane/swap/
+ *     crossfade/morph/sheet vocabulary) must be allow-listed with a
+ *     reason, so new bespoke swap animations cannot slip in.
+ *
+ * ALLOW-LIST DISCIPLINE. Each entry states WHY the standard cannot carry
+ * it. Nothing is grandfathered silently; a new entry needs a reason that
+ * would survive review.
+ */
+
+/** Components whose slot render is a pane swap and MUST stay on the
+ *  standard mechanism — pinned positively so a refactor cannot quietly
+ *  drop back to a hard cut. */
+const STANDARD_PANE_HOSTS: Array<{ file: string; marker: string; why: string }> = [
+  {
+    file: "HkTabs.tsx",
+    marker: "<HkTransitionContainer",
+    why: "tab panels are the canonical pane slot",
+  },
+  {
+    file: "HkSettingsDialog.tsx",
+    marker: "<HkTransitionContainer",
+    why: "settings sections are a page-scale pane slot (migrated 2026-10-23)",
+  },
+];
+
+/** Justified bespoke mechanisms: "<scss file>: <animation identifier>" → reason. */
+const SANCTIONED_SWAP_KEYFRAMES: Record<string, string> = {
+  "HkPickerPane.scss: hk-picker-pane-fwd-in": "fixed-stage picker with a direction axis; the stage size is known, so the measured morph container does not apply",
+  "HkPickerPane.scss: hk-picker-pane-fwd-out": "fixed-stage picker with a direction axis (see above)",
+  "HkPickerPane.scss: hk-picker-pane-back-in": "fixed-stage picker with a direction axis (see above)",
+  "HkPickerPane.scss: hk-picker-pane-back-out": "fixed-stage picker with a direction axis (see above)",
+  "HkModalBreadcrumb.scss: hk-modal-breadcrumb-in": "breadcrumb level change — a text strip, not a pane",
+};
+
+/** Swap-vocabulary keyframe names: anything that reads as a pane-swap
+ *  animation must be argued, decorative pulses and spinners do not. */
+const SWAP_VOCABULARY = /(pane|swap|crossfade|morph|sheet)/;
+
+function readComponent(file: string): string {
+  return readFileSync(join(componentsDir, file), "utf-8");
+}
+
+function scssFiles(): string[] {
+  return readdirSync(componentsDir).filter((f) => f.endsWith(".scss"));
+}
+
+describe("pane-swap contract", () => {
+  it("keeps the known pane slots on the standard mechanism", () => {
+    for (const host of STANDARD_PANE_HOSTS) {
+      const src = readComponent(host.file);
+      expect(
+        src,
+        `${host.file} must swap through the standard pane mechanism (${host.why})`,
+      ).toContain(host.marker);
+    }
+  });
+
+  it("every keyed slot render is either standard or explicitly excepted", () => {
+    // `slots[active()]?.()`-style renders: the pattern a pane slot uses.
+    const slotRenders: Array<{ file: string; line: string }> = [];
+    for (const file of readdirSync(componentsDir).filter((f) => f.endsWith(".tsx"))) {
+      const text = readComponent(file);
+      for (const line of text.split("\n")) {
+        if (/slots\[[^\]]+\]\?\.\(\)/.test(line)) slotRenders.push({ file, line: line.trim() });
+      }
+    }
+    const EXCEPTIONS = new Set([
+      // These are hosts that MUST render their slot keyed by state — they
+      // are exactly the pane slots the rule is about, and each is either
+      // wrapped by the standard above or justified here.
+      "HkTabs.tsx", // wrapped by HkTransitionContainer (pinned above)
+      "HkSettingsDialog.tsx", // wrapped by HkTransitionContainer (pinned above)
+      "HkStepFlow.tsx", // justified: frozen-sheet two-window protocol + direction axis
+      "HkAdminShell.tsx", // content slot is host-owned; hosts key it (chest wraps HkCrossfade)
+      "HkThemePanelContent.tsx", // forwards to HTabs (HkTabs), inherits the mechanism
+      "HkMenuPanel.tsx", // menu items, not a pane swap
+      // Named slots that are not pane swaps at all: a header action strip
+      // (always-on actions, not a keyed slot) and a table page's modal /
+      // empty-action hooks (modals own their own enter/leave motion).
+      "HkAdminHeader.tsx",
+      "HkAdminTablePage.tsx",
+    ]);
+    const unexplained = slotRenders.filter((r) => !EXCEPTIONS.has(r.file));
+    expect(
+      unexplained.map((r) => `${r.file}: ${r.line}`),
+      "A keyed slot render appeared outside the standard mechanism. Route it through HkTransitionContainer/HkCrossfade, or add a reasoned exception.",
+    ).toEqual([]);
+  });
+
+  it("has no unsanctioned swap-vocabulary keyframes", () => {
+    const offenders: string[] = [];
+    for (const file of scssFiles()) {
+      const text = readFileSync(join(componentsDir, file), "utf-8");
+      for (const match of text.matchAll(/@keyframes\s+([\w-]+)/g)) {
+        const name = match[1];
+        if (!SWAP_VOCABULARY.test(name)) continue;
+        const key = `${file}: ${name}`;
+        if (!SANCTIONED_SWAP_KEYFRAMES[key]) offenders.push(`@keyframes ${key}`);
+      }
+    }
+    expect(
+      offenders,
+      "A bespoke pane-swap animation appeared. Use the standard primitives, or add a reasoned allow-list entry.",
+    ).toEqual([]);
+  });
+
+  it("allow-list entries reference real keyframes (no stale exceptions)", () => {
+    const present = new Set<string>();
+    for (const file of scssFiles()) {
+      const text = readFileSync(join(componentsDir, file), "utf-8");
+      for (const match of text.matchAll(/@keyframes\s+([\w-]+)/g)) {
+        present.add(`${file}: ${match[1]}`);
+      }
+    }
+    const stale = Object.keys(SANCTIONED_SWAP_KEYFRAMES).filter((k) => !present.has(k));
+    expect(stale, "Remove allow-list entries whose keyframe is gone.").toEqual([]);
+  });
+});

package/src/styles/admin-tokens.scss

@@ -1228,8 +1228,13 @@
   font-variant-numeric: tabular-nums;
 }
 
+// Full-viewport by default: the page does NOT assume a fixed status bar
+// is mounted under it (2026-10-24 — the old calc() subtracted
+// --s-footer-height unconditionally, stopping the background 3rem short
+// of the bottom on pages with no status bar). Hosts that DO pair the
+// auth page with a status bar subtract it themselves.
 .a-auth-page {
-  min-height: calc(100vh - var(--s-footer-height, 3rem));
+  min-height: 100vh;
 }
 
 // ── adjacent-button spacing (the button-row grammar) ──────────────────────