@celestia-island/hikari 0.55.212 → 0.55.213

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.212",
+  "version": "0.55.213",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",
@@ -37,6 +37,10 @@
     "./plugins": {
       "import": "./src/plugins/index.ts",
       "types": "./src/plugins/index.ts"
+    },
+    "./plugins/boot-chrome": {
+      "import": "./src/plugins/boot-chrome.mjs",
+      "types": "./src/plugins/boot-chrome.d.mts"
     }
   },
   "files": [

package/src/components/HkTitleBar.test.tsx

@@ -109,6 +109,74 @@ describe("HkTitleBar", () => {
   });
 });
 
+describe("HkTitleBar window-chrome claim", () => {
+  // The bar IS the app's title bar, so mounting it must stand hikari's boot bar
+  // (boot-chrome.js) down — otherwise two caption bars overlap for the rest of
+  // the session. Tests use a raw window listener: that is the whole contract.
+  function collect(): { claims: Array<{ by?: string }>; stop: () => void } {
+    const claims: Array<{ by?: string }> = [];
+    const listener = (event: Event) => {
+      claims.push((event as CustomEvent<{ by?: string }>).detail ?? {});
+    };
+    window.addEventListener("hk:chrome-claim", listener);
+    return {
+      claims,
+      stop: () => window.removeEventListener("hk:chrome-claim", listener),
+    };
+  }
+
+  function cleanup(): void {
+    document.documentElement.removeAttribute("data-hk-chrome");
+  }
+
+  it("claims the window on mount and marks the app as the chrome owner", () => {
+    const { claims, stop } = collect();
+    try {
+      mount(h(HkTitleBar, { title: "App" }));
+
+      expect(claims).toHaveLength(1);
+      expect(claims[0]?.by).toBe("HkTitleBar");
+      expect(document.documentElement.getAttribute("data-hk-chrome")).toBe("app");
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("never claims twice for one mount (a re-render is not a new takeover)", async () => {
+    const { claims, stop } = collect();
+    try {
+      const maximized = ref(false);
+      mount(h(() => h(HkTitleBar, { title: "App", maximized: maximized.value })));
+      expect(claims).toHaveLength(1);
+
+      maximized.value = true;
+      await nextTick();
+      maximized.value = false;
+      await nextTick();
+
+      expect(claims).toHaveLength(1);
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("leaves the existing props/emits contract untouched", () => {
+    const emitted: string[] = [];
+    const host = mount(
+      h(HkTitleBar, {
+        title: "App",
+        onMinimize: () => emitted.push("minimize"),
+        onClose: () => emitted.push("close"),
+      }),
+    );
+    host.querySelector<HTMLButtonElement>('[title="Minimize"]')!.click();
+    host.querySelector<HTMLButtonElement>('[title="Close"]')!.click();
+    expect(emitted).toEqual(["minimize", "close"]);
+  });
+});
+
 describe("HkTitleBar stylesheet contract", () => {
   const css = compile(resolve(componentDir, "HkTitleBar.scss"), {
     style: "expanded",

package/src/components/HkTitleBar.tsx

@@ -1,5 +1,6 @@
 import { defineComponent, onBeforeUnmount, onMounted, ref } from "vue";
 import { useI18n } from "../i18n/context";
+import { claimWindowChrome } from "../runtime/windowChrome";
 
 import "./HkTitleBar.scss";
 
@@ -60,6 +61,16 @@ export default defineComponent({
   },
   setup(props, { emit, slots }) {
     const { t } = useI18n();
+    // The bar IS the app's window chrome, so mounting it means the boot chrome
+    // (boot-chrome.js, drawn before the bundle exists) must hand the window
+    // over: dispatch `hk:chrome-claim` once per mount, never revoked. See
+    // runtime/windowChrome for the contract; hydration/SSR never reaches here.
+    let claimed = false;
+    onMounted(() => {
+      if (claimed) return;
+      claimed = true;
+      claimWindowChrome("HkTitleBar");
+    });
     return () => (
       <div
         class="hk-titlebar"

package/src/components/HkWindowControls.test.tsx

@@ -1,5 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { createApp, defineComponent, h, type App } from "vue";
+import { createApp, defineComponent, h, nextTick, type App } from "vue";
+
+import { WINDOW_IPC } from "../runtime/windowChrome";
 
 import HkWindowControls, { isApplePlatform } from "./HkWindowControls";
 
@@ -91,3 +93,234 @@ describe("HkWindowControls (two deliberate modes, explicit None)", () => {
     t.app.unmount();
   });
 });
+
+describe("HkWindowControls window-chrome claim", () => {
+  // Only a cluster that ACTUALLY renders may take the window over from
+  // hikari's boot bar: claiming while rendering nothing would remove the only
+  // usable controls in the window.
+  function collect(): { claims: Array<{ by?: string }>; stop: () => void } {
+    const claims: Array<{ by?: string }> = [];
+    const listener = (event: Event) => {
+      claims.push((event as CustomEvent<{ by?: string }>).detail ?? {});
+    };
+    window.addEventListener("hk:chrome-claim", listener);
+    return {
+      claims,
+      stop: () => window.removeEventListener("hk:chrome-claim", listener),
+    };
+  }
+
+  function cleanup(): void {
+    document.documentElement.removeAttribute("data-hk-chrome");
+  }
+
+  it("claims the window when the cluster really renders", () => {
+    stubTauriWindow();
+    const { claims, stop } = collect();
+    try {
+      const t = mountControls({ variant: "standard" });
+
+      expect(claims.map((c) => c.by)).toEqual(["HkWindowControls"]);
+      expect(document.documentElement.getAttribute("data-hk-chrome")).toBe("app");
+      t.app.unmount();
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("does not claim when no variant was given (it renders nothing)", () => {
+    stubTauriWindow();
+    const { claims, stop } = collect();
+    try {
+      const t = mountControls({});
+      expect(claims).toHaveLength(0);
+      expect(document.documentElement.hasAttribute("data-hk-chrome")).toBe(false);
+      t.app.unmount();
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("does not claim off-desktop (no Tauri window API)", () => {
+    const { claims, stop } = collect();
+    try {
+      const t = mountControls({ variant: "flush" });
+      expect(claims).toHaveLength(0);
+      expect(document.documentElement.hasAttribute("data-hk-chrome")).toBe(false);
+      t.app.unmount();
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("does not claim on Apple platforms (the OS owns the traffic lights)", () => {
+    stubTauriWindow();
+    vi.stubGlobal("navigator", {
+      userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+    });
+    const { claims, stop } = collect();
+    try {
+      const t = mountControls({ variant: "standard" });
+      expect(claims).toHaveLength(0);
+      expect(document.documentElement.hasAttribute("data-hk-chrome")).toBe(false);
+      t.app.unmount();
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("renders and claims when only __TAURI_INTERNALS__ exists (late __TAURI__)", async () => {
+    // The 2026-10-28 report: the documented API was late/absent at boot. The
+    // cluster must still paint three real controls and hand the window over,
+    // otherwise the boot bar never retires and two caption strips overlap.
+    const invoke = vi.fn(() => Promise.resolve(false));
+    vi.stubGlobal("__TAURI_INTERNALS__", {
+      invoke,
+      metadata: { currentWindow: { label: "main" } },
+    });
+    const { claims, stop } = collect();
+    try {
+      const t = mountControls({ variant: "standard" });
+      const buttons = t.container.querySelectorAll<HTMLButtonElement>(
+        ".hk-window-controls__btn",
+      );
+      expect(buttons).toHaveLength(3);
+      expect(claims.map((c) => c.by)).toEqual(["HkWindowControls"]);
+      expect(document.documentElement.getAttribute("data-hk-chrome")).toBe("app");
+
+      buttons[0]!.click();
+      buttons[1]!.click();
+      buttons[2]!.click();
+      await Promise.resolve();
+
+      expect(invoke).toHaveBeenCalledWith(WINDOW_IPC.minimize, {});
+      expect(invoke).toHaveBeenCalledWith(WINDOW_IPC.toggleMaximize, {});
+      expect(invoke).toHaveBeenCalledWith(WINDOW_IPC.close, {});
+      t.app.unmount();
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+
+  it("swallows a rejected is_maximized (no unhandled rejection during boot)", async () => {
+    // S2-6: the family's res/fatal-fallback.js raises the full-screen
+    // "Application failed to load" landing on `unhandledrejection` — during
+    // boot that is worse than a missing glyph, and the internals path polls,
+    // so an unhandled rejection would repeat every 500ms.
+    const invoke = vi.fn((command: string) =>
+      command === WINDOW_IPC.isMaximized
+        ? Promise.reject(new Error("window.is_maximized not allowed"))
+        : Promise.resolve(false),
+    );
+    vi.stubGlobal("__TAURI_INTERNALS__", { invoke });
+
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown) => void unhandled.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    const t = mountControls({ variant: "standard" });
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      // The cluster still renders and the rejection never escaped.
+      expect(
+        t.container.querySelectorAll(".hk-window-controls__btn"),
+      ).toHaveLength(3);
+      expect(unhandled).toHaveLength(0);
+    } finally {
+      t.app.unmount();
+      process.off("unhandledRejection", onUnhandled);
+    }
+  });
+
+  it("swallows rejected minimize/close (no unhandled rejection, no fake state)", async () => {
+    // S2-1 (R3): `void win.minimize()` without a rejection handler meant an
+    // ACL refusal became an unhandledrejection — which the family's
+    // res/fatal-fallback.js turns into the full-screen boot-failure landing —
+    // while the button kept looking perfectly usable.
+    const invoke = vi.fn((command: string) =>
+      command === WINDOW_IPC.isMaximized
+        ? Promise.resolve(false)
+        : Promise.reject(new Error(`${command} not allowed`)),
+    );
+    vi.stubGlobal("__TAURI_INTERNALS__", { invoke });
+
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown) => void unhandled.push(reason);
+    process.on("unhandledRejection", onUnhandled);
+    const t = mountControls({ variant: "standard" });
+    try {
+      const buttons = t.container.querySelectorAll<HTMLButtonElement>(
+        ".hk-window-controls__btn",
+      );
+      buttons[0]!.click(); // minimize
+      buttons[2]!.click(); // close
+      await new Promise((resolve) => setTimeout(resolve, 20));
+
+      expect(invoke).toHaveBeenCalledWith(WINDOW_IPC.minimize, {});
+      expect(invoke).toHaveBeenCalledWith(WINDOW_IPC.close, {});
+      expect(unhandled).toHaveLength(0);
+    } finally {
+      t.app.unmount();
+      process.off("unhandledRejection", onUnhandled);
+    }
+  });
+
+  it("stops the maximized poll when unmounted before onResized resolves (S2-7)", async () => {
+    vi.useFakeTimers();
+    try {
+      const invoke = vi.fn((_command: string) => Promise.resolve(false));
+      vi.stubGlobal("__TAURI_INTERNALS__", { invoke });
+
+      const t = mountControls({ variant: "standard" });
+      // Unmount while the awaited onResized() promise is still unresolved.
+      t.app.unmount();
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+
+      const isMaximizedCalls = () =>
+        invoke.mock.calls.filter((call) => call[0] === WINDOW_IPC.isMaximized)
+          .length;
+      const afterUnmount = isMaximizedCalls();
+      vi.advanceTimersByTime(5000);
+      // An orphaned 500ms interval would keep polling a dead component.
+      expect(isMaximizedCalls()).toBe(afterUnmount);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("claims once, not once per render", async () => {
+    // The maximized glyph re-renders the cluster; the takeover already happened.
+    vi.stubGlobal("__TAURI__", {
+      window: {
+        getCurrentWindow: () => ({
+          minimize: () => Promise.resolve(),
+          toggleMaximize: () => Promise.resolve(),
+          close: () => Promise.resolve(),
+          isMaximized: () => Promise.resolve(true),
+          onResized: () => Promise.resolve(() => {}),
+        }),
+      },
+    });
+    const { claims, stop } = collect();
+    try {
+      const t = mountControls({ variant: "standard" });
+      await nextTick();
+      await nextTick();
+      await nextTick();
+
+      // Proof the re-render happened: the maximize button now offers Restore.
+      expect(t.container.querySelector('[aria-label="Restore"]')).not.toBeNull();
+      expect(claims).toHaveLength(1);
+      t.app.unmount();
+    } finally {
+      stop();
+      cleanup();
+    }
+  });
+});

package/src/components/HkWindowControls.tsx

@@ -2,6 +2,8 @@ import { defineComponent, onMounted, onUnmounted, ref, type PropType } from "vue
 
 import { Minus, Square, X, Copy } from "lucide-vue-next";
 
+import { claimWindowChrome, resolveWindowApi } from "../runtime/windowChrome";
+
 import "./HkWindowControls.scss";
 
 /**
@@ -41,28 +43,15 @@ import "./HkWindowControls.scss";
  * renders nothing on Apple platforms and the header degrades to its
  * browser-face look automatically.
  *
- * The window API rides `__TAURI__.window.getCurrentWindow()` when
- * present; on a non-Tauri host (browser preview) the buttons render
- * but the calls no-op, keeping visual parity for storybook/tests.
+ * The window API comes from `resolveWindowApi()` (runtime/windowChrome):
+ * `__TAURI__.window.getCurrentWindow()` when the host exposes it, otherwise the
+ * `__TAURI_INTERNALS__` IPC surface. That fallback matters: the field report
+ * (2026-10-28) was a boot where `__TAURI__` was missing/late, this component
+ * rendered NOTHING, the boot bar never got claimed, and two caption strips
+ * fought over the top edge. The three gates below are unchanged; only the
+ * "is there a shell?" probe is shared now. No shell at all → nothing renders.
  */
 
-interface TauriWindowLike {
-  minimize(): Promise<void>;
-  toggleMaximize(): Promise<void>;
-  close(): Promise<void>;
-  isMaximized(): Promise<boolean>;
-  onResized(cb: () => void): Promise<() => void>;
-}
-
-function currentWindow(): TauriWindowLike | null {
-  const w = (
-    window as unknown as {
-      __TAURI__?: { window?: { getCurrentWindow?: () => TauriWindowLike } };
-    }
-  ).__TAURI__?.window;
-  return w?.getCurrentWindow?.() ?? null;
-}
-
 /** Apple platforms own their traffic lights — we never render there. */
 export function isApplePlatform(): boolean {
   return /Mac|iPhone|iPad|iPod/.test(
@@ -86,14 +75,48 @@ export const HkWindowControls = defineComponent({
   setup(props) {
     const maximized = ref(false);
     let unlisten: (() => void) | null = null;
+    // Set on unmount: the mount path awaits `onResized()`, and an unmount that
+    // lands before that promise resolves would otherwise arm a poll interval
+    // (and keep writing `maximized`) for a component that no longer exists.
+    let disposed = false;
+    // Only a mount that actually paints the cluster takes the window chrome
+    // over from the boot bar (boot-chrome.js): the SAME gates the render
+    // function applies, replayed once on mount. A component that renders
+    // nothing must not claim — the boot bar would vanish and leave the window
+    // with no controls at all. On Apple platforms nothing is painted (the OS
+    // owns the traffic lights), so a host that ships only this component on
+    // macOS must dispatch `claimWindowChrome()` itself.
+    let claimed = false;
 
     onMounted(async () => {
-      const win = currentWindow();
+      if (isApplePlatform()) return;
+      if (props.variant !== "standard" && props.variant !== "flush") return;
+      const win = resolveWindowApi();
       if (!win) return;
+      if (!claimed) {
+        claimed = true;
+        claimWindowChrome("HkWindowControls");
+      }
+      // Every shell read is failure-tolerant AND handled: an unhandled
+      // rejection during boot is treated as fatal by the family's
+      // `res/fatal-fallback.js` (it raises the full-screen "Application failed
+      // to load" landing on `unhandledrejection`), and the internals path would
+      // reproduce it every poll interval.
+      const refresh = () => {
+        void win.isMaximized().then(
+          (value) => {
+            if (!disposed) maximized.value = value;
+          },
+          () => {},
+        );
+      };
       try {
-        const refresh = () => void win.isMaximized().then((m) => (maximized.value = m));
         refresh();
         const off = await win.onResized(refresh);
+        if (disposed) {
+          off();
+          return;
+        }
         unlisten = off;
       } catch {
         /* the window API is optional furniture */
@@ -101,7 +124,9 @@ export const HkWindowControls = defineComponent({
     });
 
     onUnmounted(() => {
+      disposed = true;
       unlisten?.();
+      unlisten = null;
     });
 
     return () => {
@@ -111,9 +136,26 @@ export const HkWindowControls = defineComponent({
       // enforce the required prop).
       if (isApplePlatform()) return null;
       if (props.variant !== "standard" && props.variant !== "flush") return null;
-      const win = currentWindow();
+      const win = resolveWindowApi();
       if (!win) return null;
 
+      // Toggle, then re-read the shell state: the glyph must follow the real
+      // window, not a local guess (the internals path may have no resize event).
+      const toggleMaximize = () => {
+        void win
+          .toggleMaximize()
+          .then(() => win.isMaximized())
+          .then((value) => (maximized.value = value))
+          .catch(() => {});
+      };
+
+      // A refused shell call must never surface as an unhandled rejection (the
+      // family's res/fatal-fallback.js turns one into a full-screen boot
+      // failure) and must never look like a working button. The boot bar shows
+      // the degraded state when it is the one drawing the controls; here the
+      // host's own footer simply keeps the glyph it had.
+      const ignore = (pending: Promise<unknown>) => void pending.catch(() => {});
+
       const flush = props.variant === "flush";
       return (
         <div
@@ -124,7 +166,7 @@ export const HkWindowControls = defineComponent({
             type="button"
             class="hk-window-controls__btn"
             aria-label="Minimize"
-            onClick={() => void win.minimize()}
+            onClick={() => ignore(win.minimize())}
           >
             <Minus size={flush ? 14 : 16} />
           </button>
@@ -132,7 +174,7 @@ export const HkWindowControls = defineComponent({
             type="button"
             class="hk-window-controls__btn"
             aria-label={maximized.value ? "Restore" : "Maximize"}
-            onClick={() => void win.toggleMaximize()}
+            onClick={toggleMaximize}
           >
             {maximized.value
               ? <Copy size={flush ? 12 : 14} style={{ transform: "rotate(180deg)" }} />
@@ -142,7 +184,7 @@ export const HkWindowControls = defineComponent({
             type="button"
             class="hk-window-controls__btn hk-window-controls__btn--close"
             aria-label="Close"
-            onClick={() => void win.close()}
+            onClick={() => ignore(win.close())}
           >
             <X size={flush ? 14 : 16} />
           </button>

package/src/index.ts

@@ -826,3 +826,29 @@ export { type HAboutComponentVersion as HkAboutComponentVersion } from "./compon
 export { type HCustomTheme as HkCustomTheme } from "./components/HkColorSchemeDialog";
 export { OVERLAY_ROOT_SELECTOR, OVERLAY_Z, ensureOverlayRoot } from "./overlay/overlayRoot";
 export { HK_PAD_VAR, hkPadStyle, type HkPad } from "./runtime/containerPad";
+
+// Window-chrome handoff (2026-10-28): the boot bar hikari's Vite plugin draws
+// before the app bundle exists hands the window over on `hk:chrome-claim`.
+// `claimWindowChrome` is for hosts that paint their OWN title bar instead of
+// HkTitleBar/HkWindowControls (both claim automatically).
+export {
+  claimWindowChrome,
+  resolveWindowApi,
+  CHROME_CLAIM_EVENT,
+  CHROME_OWNER_ATTR,
+  WINDOW_IPC,
+  RESIZE_POLL_MS,
+  type WindowApiLike,
+} from "./runtime/windowChrome";
+// Pre-boot caption bar (`bootChromePlugin`) is NOT exported here. It ships from
+// its own published subpath — `@celestia-island/hikari/plugins/boot-chrome` —
+// resolved to a self-contained ESM module, and that is what a host imports in
+// vite.config.ts:
+//   1. this entry is what BROWSER bundles import; re-exporting the Node-side
+//      plugin from it makes every consumer's build pull the module, and Vite
+//      then emits `boot-chrome.js` as a duplicate 28.8 kB asset AND warns
+//      "node:fs has been externalized for browser compatibility" (measured with
+//      Vite 8; tree-shaking does not remove a statically-referenced asset), and
+//   2. the `/plugins` barrel is TypeScript, which Node cannot load from inside
+//      node_modules (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`) — the
+//      dedicated subpath exists precisely to avoid that.

package/src/plugins/boot-chrome.d.mts

@@ -0,0 +1,41 @@
+import type { Plugin } from "vite";
+
+/**
+ * Types for `boot-chrome.mjs` — the self-contained, published Vite plugin entry
+ * (`@celestia-island/hikari/plugins/boot-chrome`).
+ *
+ * The implementation is plain ESM with static Node imports on purpose: a
+ * consumer loads it from `node_modules` while resolving `vite.config.*`, where
+ * TypeScript cannot be stripped and Vite's `configLoader: "runner"` tears the
+ * module runner down before plugin hooks run. Keep the runtime file dependency
+ * free apart from `node:fs` / `node:path` / `node:url`.
+ */
+
+/** File name the bar is emitted and served under (output-dir root). */
+export declare const BOOT_CHROME_SCRIPT: "hk-boot-chrome.js";
+
+/** Root-absolute default URL the injected `<script src>` points at. */
+export declare const BOOT_CHROME_URL: string;
+
+export interface BootChromePluginOptions {
+  /** Application name on the left of the bar (default: `document.title`). */
+  title?: string;
+  /** Bar height in px; `boot-chrome.js` clamps it to 20..64 (default 32). */
+  height?: number;
+  /** Watchdog delay in ms before the reload affordance appears (default 20000). */
+  hangMs?: number;
+  /**
+   * Which HTML entries get the bar. Default: only entries whose basename is
+   * `index.html`. Multi-window shells MUST configure this — a transparent
+   * overlay window must never paint the caption bar.
+   *
+   * A `RegExp` is matched against the entry's file path; a `string[]` is
+   * matched against the basename or the path suffix (`"pages/index.html"`).
+   */
+  htmlFiles?: string[] | RegExp;
+}
+
+/** Vite plugin: inject `boot-chrome.js` into the app window's HTML entry. */
+export declare function bootChromePlugin(
+  options?: BootChromePluginOptions,
+): Plugin;