@celestia-island/hikari 0.55.248 → 0.55.249

package/package.json

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

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

@@ -0,0 +1,132 @@
+// AI-generated: developed with the DeepSeek Harness agent (model
+// DeepSeek-Flash) and the ZCode agent (model GLM-5.3), directed and reviewed
+// by langyo — SySL-1.0 §2.3 disclosure.
+
+import type { Plugin } from "vite";
+
+/**
+ * Types for `boot-recovery.mjs` — the self-contained, published Vite plugin
+ * entry (`@celestia-island/hikari/plugins/boot-recovery`).
+ *
+ * The implementation is plain ESM loaded from `node_modules` while a consumer's
+ * `vite.config.*` is resolved, where TypeScript cannot be stripped and Vite's
+ * `configLoader: "runner"` tears the module runner down before plugin hooks
+ * run. Keep the runtime file limited to static imports (`node:path` only).
+ */
+
+/** The canonical Tauri app origin on Windows/Android. */
+export declare const BOOT_RECOVERY_CANONICAL_ORIGIN: "http://tauri.localhost";
+
+/** Default watchdog delay in ms. */
+export declare const BOOT_RECOVERY_DEADLINE_MS: 15000;
+
+/** Default selector of the host's static loading element. */
+export declare const BOOT_RECOVERY_LOADING_SELECTOR: "#loading-screen";
+
+/** Default class that marks a loading element as already dismissed. */
+export declare const BOOT_RECOVERY_DISMISSED_CLASS: "hidden";
+
+/** Default failure-panel message (English; override through `copy.message`). */
+export declare const BOOT_RECOVERY_MESSAGE: string;
+
+/** Default failure-panel retry label (English; override through `copy.retry`). */
+export declare const BOOT_RECOVERY_RETRY: string;
+
+/** Marker attribute on the injected inline `<script>` tag. */
+export declare const BOOT_RECOVERY_ATTR: "data-hk-boot-recovery";
+
+/** The default options, frozen (see {@link BootRecoveryPluginOptions}). */
+export interface BootRecoveryDefaults {
+  readonly canonicalOrigin: string;
+  readonly deadlineMs: number;
+  readonly loadingScreen: Readonly<{
+    selector: string;
+    dismissedClass: string;
+  }>;
+  readonly copy: Readonly<{ message: string; retry: string }>;
+  readonly injectTo: "head" | "head-prepend";
+}
+
+/** Frozen snapshot of every default. */
+export declare const BOOT_RECOVERY_DEFAULTS: Readonly<BootRecoveryDefaults>;
+
+/** The loading-screen half of the recovery (the watchdog). */
+export interface BootRecoveryLoadingScreenOptions {
+  /** Element whose contents are replaced when nothing mounted (default `#loading-screen`). */
+  selector?: string;
+  /** Class marking the element as dismissed/fading (default `hidden`; empty disables the check). */
+  dismissedClass?: string;
+}
+
+/** Overridable failure-panel copy (English defaults). */
+export interface BootRecoveryCopyOptions {
+  /** Main message of the panel. */
+  message?: string;
+  /** Retry button label. */
+  retry?: string;
+}
+
+/** Options for {@link bootRecoveryPlugin} / {@link bootRecoveryScript}. */
+export interface BootRecoveryPluginOptions {
+  /**
+   * Which HTML entries get the inline script. Default: only entries whose
+   * basename is `index.html`. Multi-window shells MUST configure this — a
+   * transparent overlay window must never be reloaded or healed by boot
+   * recovery.
+   *
+   * 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;
+  /**
+   * The watchdog half: an object customises the loading element; `false`
+   * disables it entirely (heal-only mode, for hosts with their own fatal
+   * landing page). Default: `{ selector: "#loading-screen", dismissedClass: "hidden" }`.
+   */
+  loadingScreen?: BootRecoveryLoadingScreenOptions | false;
+  /** Watchdog delay in ms (default 15000). */
+  deadlineMs?: number;
+  /** Absolute http(s) app origin (default `http://tauri.localhost`). */
+  canonicalOrigin?: string;
+  /**
+   * Custom mangled-origin predicate. It runs in the PAGE, so it is embedded
+   * by source text: pass a self-contained ES2017-safe function expression or
+   * arrow function (no closures, no method shorthand, ASCII-only). Default:
+   * `isMangledOrigin` (http/https only, hostname starts with the canonical
+   * host and differs from it; `tauri://` untouched).
+   */
+  isMangledOrigin?: (protocol: string, hostname: string) => boolean;
+  /** Failure-panel copy overrides. */
+  copy?: BootRecoveryCopyOptions;
+  /**
+   * Where the tag is injected. Default `"head"` (end of `<head>`, after
+   * `<meta charset>` — charset-prescan safe). `"head-prepend"` runs even
+   * earlier but is charset-unsafe (the encoding prescan only reads the first
+   * 1024 bytes); use it only when the host sends an explicit charset header.
+   */
+  injectTo?: "head" | "head-prepend";
+}
+
+/**
+ * The default mangled-origin predicate: http(s) only, a hostname that starts
+ * with the canonical origin's hostname but is not equal to it (`tauri://`
+ * origins are never redirected).
+ */
+export declare function isMangledOrigin(
+  protocol: string,
+  hostname: string,
+  canonicalOrigin?: string,
+): boolean;
+
+/**
+ * The generated inline IIFE — deterministic, ASCII-only, classic (non-module)
+ * and safe to hash into a host CSP.
+ */
+export declare function bootRecoveryScript(
+  options?: BootRecoveryPluginOptions,
+): string;
+
+/** Vite plugin: inject the boot recovery script into the configured entries. */
+export declare function bootRecoveryPlugin(
+  options?: BootRecoveryPluginOptions,
+): Plugin;

package/src/plugins/boot-recovery.install.test.ts

@@ -0,0 +1,280 @@
+// @vitest-environment node
+// AI-generated: developed with the DeepSeek Harness agent (model
+// DeepSeek-Flash) and the ZCode agent (model GLM-5.3), directed and reviewed
+// by langyo — SySL-1.0 §2.3 disclosure.
+
+import { execFileSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterAll, describe, expect, it } from "vitest";
+
+/**
+ * The npm install-face regression test for `boot-recovery.mjs`.
+ *
+ * `bootRecoveryPlugin` runs inside a consumer's `vite.config.*`, loaded from
+ * `node_modules`. Two failure modes have bitten hikari before (pinned by
+ * `boot-chrome.install.test.ts`, reproduced here for this entry):
+ *
+ *   1. shipping the plugin as TypeScript → Node refuses type stripping under
+ *      `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`);
+ *   2. a dynamic `import(...)` from a plugin hook → Vite's
+ *      `configLoader: "runner"` has already torn the module runner down
+ *      ("Vite module runner has been closed").
+ *
+ * Vitest transforms TS and keeps a module runner alive, so it can never catch
+ * either one. This test copies the published layout into a fake
+ * `node_modules` — `src/plugins` ONLY: boot recovery needs no `src/res`
+ * asset, which is part of its install face — and imports it from a CHILD
+ * `node` process, then builds a consumer through Vite with BOTH config loaders.
+ */
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const VUE_DIR = resolve(HERE, "../..");
+const PACKAGE_JSON = JSON.parse(
+  readFileSync(join(VUE_DIR, "package.json"), "utf8"),
+) as {
+  name: string;
+  version: string;
+  type: string;
+  exports: Record<string, { import: string; types?: string }>;
+};
+
+const INSTALL_SUBPATH = "./plugins/boot-recovery";
+
+const temps: string[] = [];
+
+afterAll(() => {
+  for (const dir of temps.splice(0)) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* a leftover temp dir must not fail the suite */
+    }
+  }
+});
+
+/** Lay out `node_modules/@celestia-island/hikari` exactly like `npm pack` does. */
+function fakeInstall(): string {
+  const root = mkdtempSync(join(tmpdir(), "hikari-boot-recovery-install-"));
+  temps.push(root);
+
+  const pkgDir = join(root, "node_modules", PACKAGE_JSON.name);
+  mkdirSync(join(pkgDir, "src"), { recursive: true });
+  // `files: ["src/"]` — the published tarball carries the sources it needs.
+  // NOTE: no `src/res` copy on purpose — this plugin has no runtime asset.
+  cpSync(join(VUE_DIR, "src/plugins"), join(pkgDir, "src/plugins"), {
+    recursive: true,
+  });
+  writeFileSync(
+    join(pkgDir, "package.json"),
+    JSON.stringify(
+      {
+        name: PACKAGE_JSON.name,
+        version: PACKAGE_JSON.version,
+        private: false,
+        type: PACKAGE_JSON.type,
+        exports: PACKAGE_JSON.exports,
+      },
+      null,
+      2,
+    ),
+  );
+  writeFileSync(
+    join(root, "package.json"),
+    JSON.stringify(
+      { name: "boot-recovery-install-probe", private: true, type: "module" },
+      null,
+      2,
+    ),
+  );
+  return root;
+}
+
+/** Run any command in a child process, capturing everything. */
+function runCommand(
+  command: string,
+  args: string[],
+  cwd: string,
+): { code: number; stdout: string; stderr: string } {
+  try {
+    const stdout = execFileSync(command, args, {
+      cwd,
+      encoding: "utf8",
+      stdio: "pipe",
+      timeout: 120_000,
+      env: { ...process.env, NO_COLOR: "1" },
+    });
+    return { code: 0, stdout, stderr: "" };
+  } catch (err) {
+    const failure = err as { status?: number; stdout?: string; stderr?: string };
+    return {
+      code: failure.status ?? 1,
+      stdout: failure.stdout ?? "",
+      stderr: failure.stderr ?? String(err),
+    };
+  }
+}
+
+/** Run one ESM probe in a child `node` (no bundler, no transforms). */
+function runProbe(
+  root: string,
+  source: string,
+): { code: number; stdout: string; stderr: string } {
+  try {
+    const stdout = execFileSync(
+      process.execPath,
+      ["--input-type=module", "-e", source],
+      { cwd: root, encoding: "utf8", stdio: "pipe", timeout: 30_000 },
+    );
+    return { code: 0, stdout, stderr: "" };
+  } catch (err) {
+    const failure = err as { status?: number; stdout?: string; stderr?: string };
+    return {
+      code: failure.status ?? 1,
+      stdout: failure.stdout ?? "",
+      stderr: failure.stderr ?? String(err),
+    };
+  }
+}
+
+describe("published install face (boot recovery)", () => {
+  it("declares a resolvable ESM subpath with types", () => {
+    const entry = PACKAGE_JSON.exports[INSTALL_SUBPATH];
+    expect(entry, INSTALL_SUBPATH + " must be exported").toBeTruthy();
+    expect(entry.import).toBe("./src/plugins/boot-recovery.mjs");
+    expect(entry.types).toBe("./src/plugins/boot-recovery.d.mts");
+    expect(existsSync(join(VUE_DIR, entry.import))).toBe(true);
+    expect(existsSync(join(VUE_DIR, entry.types!))).toBe(true);
+  });
+
+  it("imports and runs from node_modules in a plain child node process", { timeout: 60_000 }, () => {
+    const root = fakeInstall();
+    const probe = [
+      "// Plain Node: no type stripping of node_modules, no Vite module runner.",
+      'const mod = await import("' + PACKAGE_JSON.name + '/plugins/boot-recovery");',
+      "const script = mod.bootRecoveryScript();",
+      'if (!script.includes("http://tauri.localhost")) {',
+      '  console.error("NO_SCRIPT");',
+      "  process.exit(3);",
+      "}",
+      'if (!script.startsWith("(function () {")) {',
+      '  console.error("NOT_AN_IIFE");',
+      "  process.exit(4);",
+      "}",
+      "const plugin = mod.bootRecoveryPlugin();",
+      'if (!plugin || plugin.name !== "hikari-boot-recovery") {',
+      '  console.error("NO_FACTORY");',
+      "  process.exit(5);",
+      "}",
+      'const tags = plugin.transformIndexHtml("", { filename: "/app/index.html" });',
+      "if (",
+      "  !Array.isArray(tags) ||",
+      "  tags.length !== 1 ||",
+      '  tags[0].tag !== "script" ||',
+      '  tags[0].injectTo !== "head" ||',
+      '  tags[0].attrs["data-hk-boot-recovery"] !== "" ||',
+      "  tags[0].children !== script",
+      ") {",
+      '  console.error("NO_TAG");',
+      "  process.exit(6);",
+      "}",
+      "const healOnly = mod.bootRecoveryScript({ loadingScreen: false });",
+      'if (healOnly.includes("setTimeout(")) {',
+      '  console.error("HEAL_ONLY_BROKEN");',
+      "  process.exit(7);",
+      "}",
+      'console.log("INSTALL_OK " + script.length);',
+    ].join("\n");
+    const result = runProbe(root, probe);
+
+    expect(
+      result.stderr,
+      "child node stderr (type-strip / runner failures show up here):\n" +
+        result.stderr,
+    ).not.toMatch(
+      /ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING|module runner has been closed|Cannot find module/,
+    );
+    expect(result.code, "child exited " + result.code + ": " + result.stderr).toBe(0);
+    expect(result.stdout).toContain("INSTALL_OK");
+  });
+
+  it("builds a consumer through vite with BOTH config loaders", { timeout: 120_000 }, () => {
+    // The R2 scenario: a consumer whose vite.config imports the plugin from its
+    // own node_modules. The DEFAULT loader fails on a TypeScript entry; the
+    // `runner` loader additionally fails on a dynamic import from a hook. Both
+    // loader modes are exercised so a future Vite bump gets caught.
+    const root = fakeInstall();
+    writeFileSync(
+      join(root, "index.html"),
+      '<!doctype html><html><head><meta charset="UTF-8"><title>App</title></head>' +
+        '<body><div id="loading-screen"><span>Loading...</span></div>' +
+        '<div id="app"></div><script type="module" src="/main.js"></script></body></html>',
+    );
+    writeFileSync(join(root, "main.js"), 'document.getElementById("app");');
+    writeFileSync(
+      join(root, "vite.config.mjs"),
+      [
+        'import { bootRecoveryPlugin } from "' +
+          PACKAGE_JSON.name +
+          '/plugins/boot-recovery";',
+        "export default {",
+        "  plugins: [bootRecoveryPlugin()],",
+        '  build: { outDir: "dist", emptyOutDir: true },',
+        "};",
+      ].join("\n"),
+    );
+
+    // Resolve the repo's own vite binary: the fake install has no toolchain,
+    // and the point is what a consumer's build does with the published files.
+    const viteEntry = createRequire(import.meta.url).resolve("vite");
+    const viteBin = resolve(dirname(viteEntry), "../../bin/vite.js");
+    for (const loader of ["default", "runner"]) {
+      const args = [viteBin, "build"];
+      if (loader === "runner") args.push("--configLoader", "runner");
+      const result = runCommand(process.execPath, args, root);
+      expect(
+        result.code,
+        "vite build (" + loader + " config loader) failed:\n" +
+          (result.stderr || result.stdout),
+      ).toBe(0);
+      const html = readFileSync(join(root, "dist", "index.html"), "utf8");
+      expect(html).toContain("data-hk-boot-recovery");
+      expect(html).toContain("(function () {");
+      // Inline, not an external asset the install would have had to ship.
+      expect(html).not.toMatch(/<script[^>]*data-hk-boot-recovery[^>]*\ssrc=/);
+    }
+  });
+
+  it("keeps the runtime module free of dynamic imports and TypeScript", () => {
+    // Enforce the properties the failure modes above come from: a refactor back
+    // to a dynamic import or a .ts implementation is caught without a full
+    // build. Comments mention the banned forms (they explain why), so only
+    // real code is checked.
+    const source = readFileSync(
+      join(VUE_DIR, "src/plugins/boot-recovery.mjs"),
+      "utf8",
+    );
+    const code = source
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/^\s*\/\/.*$/gm, "");
+    expect(code).not.toMatch(/\bimport\s*\(/);
+    expect(code).not.toMatch(/\bfrom\s+["'][^"']*\.ts["']/);
+    // Static imports only — and only the one Node builtin it needs.
+    expect(code).toMatch(/from "node:path"/);
+    // No runtime asset: the plugin is pure string generation.
+    expect(code).not.toMatch(/res\//);
+    expect(code).not.toContain("readFileSync");
+  });
+});