@celestia-island/hikari 0.40.12 → 0.40.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.40.12",
+  "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/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/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;
+}

package/src/errorReporting/HkErrorReportingOverlay.tsx

@@ -0,0 +1,103 @@
+import { computed, defineComponent } from "vue";
+
+import { useI18n } from "../i18n/context";
+import HButton from "../components/HkButton";
+import { HkErrorLanding } from "../components/HkErrorLanding";
+import { HkJsonTree } from "../components/HkJsonTree";
+import {
+  getErrorReportingOptions,
+  useErrorReportingState,
+} from "./state";
+
+import "./HkErrorReportingOverlay.scss";
+
+/**
+ * HkErrorReportingOverlay — the full-viewport takeover for uncaught errors.
+ *
+ * Renders nothing until the error-reporting state is raised. The card is
+ * the family-wide HkErrorLanding (same design language as every unified
+ * error surface): tone icon, headline, the error name as the code chip,
+ * the message as the description, the raw error record in a collapsible
+ * JSON tree, and Home / Retry actions.
+ *
+ * Mounted by `createErrorReporting` on a dedicated root appended to
+ * `document.body` via its own tiny app instance, so it keeps working even
+ * when the host component tree is the thing that crashed.
+ */
+export const HkErrorReportingOverlay = defineComponent({
+  name: "HkErrorReportingOverlay",
+  setup() {
+    const { t } = useI18n();
+    const state = useErrorReportingState();
+
+    const detailsValue = computed<Record<string, unknown> | undefined>(() => {
+      const err = state.value;
+      if (!err) return undefined;
+      const record: Record<string, unknown> = {
+        name: err.name,
+        message: err.message,
+        source: err.source,
+      };
+      if (err.stack) record.stack = err.stack;
+      if (err.info) record.info = err.info;
+      return record;
+    });
+
+    function goHome() {
+      const options = getErrorReportingOptions();
+      if (options.onHome) {
+        options.onHome();
+        return;
+      }
+      const href = options.homeHref === undefined ? "/" : options.homeHref;
+      if (href !== false) window.location.assign(href);
+    }
+
+    function retry() {
+      const options = getErrorReportingOptions();
+      if (options.onRetry) {
+        options.onRetry();
+        return;
+      }
+      window.location.reload();
+    }
+
+    return () => {
+      const err = state.value;
+      if (!err) return null;
+      const options = getErrorReportingOptions();
+
+      const description = options.describe
+        ? options.describe(err)
+        : err.message || t("hikari::errors.unexpectedDesc", "An unhandled error occurred.");
+
+      const showHome = Boolean(options.onHome) || options.homeHref !== false;
+
+      return (
+        <div class="hk-error-reporting-overlay" role="alertdialog" aria-live="assertive" aria-modal="true">
+          <HkErrorLanding
+            title={options.title || t("hikari::errors.defaultTitle", "Something went wrong")}
+            description={description}
+            code={err.name}
+          >
+            {{
+              default: () => <HkJsonTree value={detailsValue.value} ariaLabel="stack trace" />,
+              actions: () => [
+                ...(showHome
+                  ? [(
+                    <HButton key="home" size="sm" onClick={goHome}>
+                      {t("hikari::errors.backHome", "Back to home")}
+                    </HButton>
+                  )]
+                  : []),
+                <HButton key="retry" size="sm" variant="secondary" onClick={retry}>
+                  {t("hikari::errorBoundary.retry", "Retry")}
+                </HButton>,
+              ],
+            }}
+          </HkErrorLanding>
+        </div>
+      );
+    };
+  },
+});

package/src/errorReporting/index.test.tsx

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import {
+  clearGlobalError,
+  createErrorReporting,
+  reportGlobalError,
+  resetErrorReportingForTests,
+  type HkErrorReportingOptions,
+} from "./index";
+
+const Boom = defineComponent({
+  name: "Boom",
+  setup() {
+    throw new TypeError("Cannot read properties of undefined (reading 'length')");
+  },
+  render: () => h("div", "never"),
+});
+
+function installPlugin(options?: HkErrorReportingOptions) {
+  // A throwaway app: the plugin's window hooks and module state outlive it,
+  // exactly like the real host app installing it at bootstrap.
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => null });
+  app.use(createErrorReporting(options));
+  app.mount(container);
+  app.unmount();
+  container.remove();
+}
+
+function mountThrowingApp() {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(Boom);
+  app.use(createErrorReporting());
+  app.mount(container);
+  return { app, container };
+}
+
+function overlayHost(): HTMLElement | null {
+  return document.querySelector<HTMLElement>("[data-hikari-error-reporting]");
+}
+
+afterEach(() => {
+  resetErrorReportingForTests();
+  document.querySelectorAll("[data-hikari-error-reporting]").forEach((el) => el.remove());
+});
+
+describe("createErrorReporting", () => {
+  it("shows the unified error landing for uncaught render errors", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const { app, container } = mountThrowingApp();
+    await nextTick();
+
+    const host = overlayHost();
+    expect(host).not.toBeNull();
+    expect(host!.querySelector(".hk-error-landing")).not.toBeNull();
+    expect(host!.querySelector(".hk-error-landing__code")!.textContent).toBe("TypeError");
+    expect(host!.querySelector(".hk-error-landing__desc")!.textContent)
+      .toBe("Cannot read properties of undefined (reading 'length')");
+    // Raw details ride in the JSON tree.
+    expect(host!.querySelector(".s-tool-json-tree")).not.toBeNull();
+
+    app.unmount();
+    container.remove();
+  });
+
+  it("renders Home and Retry actions and hides Home when disabled", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    installPlugin();
+    reportGlobalError(new Error("boom"));
+    await nextTick();
+
+    const host = overlayHost()!;
+    const labels = Array.from(host.querySelectorAll("button")).map((b) => b.textContent);
+    expect(labels).toContain("Back to home");
+    expect(labels).toContain("Retry");
+
+    clearGlobalError();
+
+    installPlugin({ homeHref: false });
+    reportGlobalError(new Error("boom"));
+    await nextTick();
+    const labels2 = Array.from(overlayHost()!.querySelectorAll("button")).map((b) => b.textContent);
+    expect(labels2).not.toContain("Back to home");
+    expect(labels2).toContain("Retry");
+  });
+
+  it("takes over for unhandled window errors and rejections", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    installPlugin();
+
+    window.dispatchEvent(new ErrorEvent("error", { error: new RangeError("out of range") }));
+    await nextTick();
+    expect(overlayHost()!.querySelector(".hk-error-landing__code")!.textContent).toBe("RangeError");
+
+    clearGlobalError();
+
+    // happy-dom has no PromiseRejectionEvent constructor; a plain event with
+    // a `reason` property exercises the same listener path.
+    const rejection = new Event("unhandledrejection");
+    Object.defineProperty(rejection, "reason", { value: new Error("async boom") });
+    window.dispatchEvent(rejection);
+    await nextTick();
+    expect(overlayHost()!.querySelector(".hk-error-landing__desc")!.textContent).toBe("async boom");
+  });
+
+  it("keeps the first error and still fires onError for later ones", () => {
+    const onError = vi.fn();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    installPlugin({ onError });
+
+    reportGlobalError(new Error("first"));
+    reportGlobalError(new Error("second"));
+    expect(overlayHost()!.querySelector(".hk-error-landing__desc")!.textContent).toBe("first");
+    expect(onError).toHaveBeenCalledTimes(2);
+  });
+
+  it("drops errors rejected by shouldReport", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    installPlugin({ shouldReport: (_err, source) => source === "manual" });
+
+    window.dispatchEvent(new ErrorEvent("error", { error: new Error("filtered away") }));
+    expect(overlayHost()).toBeNull();
+  });
+
+  it("chains a pre-existing app errorHandler", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const previous = vi.fn();
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({ render: () => null });
+    app.config.errorHandler = previous;
+    app.use(createErrorReporting());
+    app.mount(container);
+    app.config.errorHandler!(new Error("routed"), null, "setup function");
+    expect(previous).toHaveBeenCalledTimes(1);
+    expect(overlayHost()).not.toBeNull();
+    app.unmount();
+    container.remove();
+  });
+
+  it("uses custom onRetry instead of reloading", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const onRetry = vi.fn();
+    installPlugin({ onRetry });
+    reportGlobalError(new Error("boom"));
+    await nextTick();
+
+    const retry = Array.from(overlayHost()!.querySelectorAll<HTMLButtonElement>("button"))
+      .find((b) => b.textContent === "Retry")!;
+    retry.click();
+    expect(onRetry).toHaveBeenCalledTimes(1);
+  });
+
+  it("clearGlobalError tears the overlay down", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    reportGlobalError(new Error("boom"));
+    await nextTick();
+    expect(overlayHost()).not.toBeNull();
+    clearGlobalError();
+    expect(overlayHost()).toBeNull();
+  });
+});

package/src/errorReporting/index.ts

@@ -0,0 +1,158 @@
+import { createApp, type App, type Plugin } from "vue";
+
+import { HkErrorReportingOverlay } from "./HkErrorReportingOverlay";
+import {
+  clearErrorReportingState,
+  reportError,
+  setErrorReportingOptions,
+  type HkErrorReportingOptions,
+  type HkErrorSource,
+} from "./state";
+
+export type {
+  HkErrorReportingOptions,
+  HkErrorSource,
+  HkReportedError,
+} from "./state";
+export { HkErrorReportingOverlay } from "./HkErrorReportingOverlay";
+
+/**
+ * createErrorReporting — the install-and-forget global error reporting hook.
+ *
+ * `app.use(createErrorReporting())` is all a host needs to get the
+ * family-wide unified error landing for every error nothing else caught:
+ *
+ * - `app.config.errorHandler` (render trees without an HErrorBoundary,
+ *   watchers, lifecycle hooks, async component failures, …);
+ * - uncaught `window` error events;
+ * - `unhandledrejection` events.
+ *
+ * On the first accepted error the plugin mounts a dedicated overlay app on
+ * `document.body` (z-index above every popup band) rendering HkErrorLanding
+ * with Home / Retry actions. Because the overlay lives on its own tiny app
+ * instance, it still shows when the host tree itself is what crashed.
+ *
+ * Any pre-existing `app.config.errorHandler` is chained, not discarded.
+ * All capture channels are optional; `shouldReport` filters, `onError` is
+ * the telemetry hook.
+ */
+export function createErrorReporting(options: HkErrorReportingOptions = {}): Plugin {
+  return {
+    install(app: App) {
+      setErrorReportingOptions(options);
+
+      const previous = app.config.errorHandler;
+      app.config.errorHandler = (err, instance, info) => {
+        if (previous) {
+          try {
+            previous(err, instance, info);
+          } catch {
+            // A broken custom handler must not swallow the report.
+          }
+        }
+        if (reportError(err, "vue", info)) ensureOverlayMounted();
+      };
+
+      installWindowHooks(options);
+    },
+  };
+}
+
+/**
+ * Raise the global error landing programmatically — the runtime-error
+ * counterpart of the old `window.__appFatal` handoff: fatal-fallback
+ * surfaces can route post-mount reports here once the SPA is up.
+ */
+export function reportGlobalError(err: unknown, source: HkErrorSource = "manual"): void {
+  if (reportError(err, source)) ensureOverlayMounted();
+}
+
+/** Dismiss the landing and tear the overlay app down (programmatic reset). */
+export function clearGlobalError(): void {
+  clearErrorReportingState();
+  unmountOverlay();
+}
+
+// ── window hooks ────────────────────────────────────────────────────────
+
+let windowCleanup: (() => void) | null = null;
+
+function installWindowHooks(options: HkErrorReportingOptions): void {
+  if (typeof window === "undefined") return;
+  if (windowCleanup) return; // One set of listeners per document, ever.
+
+  const disposers: Array<() => void> = [];
+
+  if (options.captureWindow !== false) {
+    const onError = (event: ErrorEvent) => {
+      // Resource-load failures never reach here (no capture phase); script
+      // errors always carry `error` or at least a `message`.
+      const err = event.error ?? new Error(event.message || "Unknown script error");
+      if (reportError(err, "window")) ensureOverlayMounted();
+    };
+    window.addEventListener("error", onError);
+    disposers.push(() => window.removeEventListener("error", onError));
+  }
+
+  if (options.captureRejection !== false) {
+    const onRejection = (event: PromiseRejectionEvent) => {
+      if (reportError(event.reason, "rejection")) ensureOverlayMounted();
+    };
+    window.addEventListener("unhandledrejection", onRejection);
+    disposers.push(() => window.removeEventListener("unhandledrejection", onRejection));
+  }
+
+  if (disposers.length === 0) return;
+  windowCleanup = () => {
+    for (const dispose of disposers) dispose();
+    windowCleanup = null;
+  };
+}
+
+// ── dedicated overlay app ───────────────────────────────────────────────
+
+let overlayApp: App | null = null;
+let overlayHost: HTMLElement | null = null;
+let overlayMounting = false;
+
+function ensureOverlayMounted(): void {
+  if (overlayApp || overlayMounting) return;
+  if (typeof document === "undefined") return;
+  overlayMounting = true;
+  try {
+    overlayHost = document.createElement("div");
+    overlayHost.dataset.hikariErrorReporting = "";
+    document.body.appendChild(overlayHost);
+    overlayApp = createApp(HkErrorReportingOverlay);
+    overlayApp.mount(overlayHost);
+  } catch (err) {
+    // Never let overlay mounting recurse into another report.
+    console.error("[hikari:error-reporting] failed to mount the overlay", err);
+    overlayHost?.remove();
+    overlayHost = null;
+    overlayApp = null;
+  } finally {
+    overlayMounting = false;
+  }
+}
+
+function unmountOverlay(): void {
+  if (overlayApp) {
+    try {
+      overlayApp.unmount();
+    } catch {
+      // Already gone.
+    }
+    overlayApp = null;
+  }
+  overlayHost?.remove();
+  overlayHost = null;
+}
+
+/** Test-only: reset singleton state, listeners and the overlay app. */
+export function resetErrorReportingForTests(): void {
+  clearErrorReportingState();
+  windowCleanup?.();
+  windowCleanup = null;
+  unmountOverlay();
+}

package/src/errorReporting/state.ts

@@ -0,0 +1,104 @@
+import { ref, type Ref } from "vue";
+
+/** Where a reported error came from. */
+export type HkErrorSource = "vue" | "window" | "rejection" | "manual";
+
+/** A normalized error record carried by the global error landing. */
+export interface HkReportedError {
+  source: HkErrorSource;
+  error: unknown;
+  name: string;
+  message: string;
+  stack: string;
+  /** Vue's `info` string for errors surfaced through `app.config.errorHandler`. */
+  info?: string;
+}
+
+export interface HkErrorReportingOptions {
+  /** Headline override; defaults to `hikari::errors.defaultTitle`. */
+  title?: string;
+  /** Description builder; defaults to the error's message, falling back to
+   * `hikari::errors.unexpectedDesc` when the error carries none. */
+  describe?: (err: HkReportedError) => string;
+  /** Target of the "back to home" action. `false` hides the button.
+   * Ignored when `onHome` is set. Default `/`. */
+  homeHref?: string | false;
+  /** Overrides the default `window.location.assign(homeHref)` home action. */
+  onHome?: () => void;
+  /** Overrides the default `window.location.reload()` retry action. */
+  onRetry?: () => void;
+  /** Listen for uncaught `window` error events. Default `true`. */
+  captureWindow?: boolean;
+  /** Listen for `unhandledrejection` events. Default `true`. */
+  captureRejection?: boolean;
+  /** Drop an error entirely (no overlay, no `onError` callback). */
+  shouldReport?: (err: unknown, source: HkErrorSource) => boolean;
+  /** Telemetry hook: logging / reporting pipeline. Fires for every accepted
+   * error, including ones arriving while the landing is already up. */
+  onError?: (err: unknown, source: HkErrorSource) => void;
+}
+
+export function normalizeError(err: unknown): { name: string; message: string; stack: string } {
+  if (err instanceof Error) {
+    return {
+      name: err.name || "Error",
+      message: err.message || String(err),
+      stack: err.stack || "",
+    };
+  }
+  return { name: "Error", message: String(err), stack: "" };
+}
+
+/**
+ * Module-level singleton state for the global error reporting overlay.
+ * Module scope (not app provide/inject) is deliberate: window hooks and the
+ * dedicated overlay app must reach it without a host component tree — the
+ * host tree is exactly what is broken when this fires.
+ */
+const currentError: Ref<HkReportedError | null> = ref(null);
+
+/** Options of the most recent `createErrorReporting` install. */
+let activeOptions: HkErrorReportingOptions = {};
+
+export function getErrorReportingOptions(): HkErrorReportingOptions {
+  return activeOptions;
+}
+
+export function setErrorReportingOptions(options: HkErrorReportingOptions): void {
+  activeOptions = options;
+}
+
+export function useErrorReportingState(): Ref<HkReportedError | null> {
+  return currentError;
+}
+
+/**
+ * Raise the global error landing. The first error wins while the landing is
+ * up; later errors still log and fire `onError` but never swap the card.
+ * Returns the record when accepted, `null` when filtered or already showing.
+ */
+export function reportError(err: unknown, source: HkErrorSource, info?: string): HkReportedError | null {
+  const options = activeOptions;
+  if (options.shouldReport && !options.shouldReport(err, source)) return null;
+
+  console.error(`[hikari:error-reporting:${source}]`, err);
+  options.onError?.(err, source);
+
+  if (currentError.value !== null) return null;
+
+  const normalized = normalizeError(err);
+  const record: HkReportedError = {
+    source,
+    error: err,
+    name: normalized.name,
+    message: normalized.message,
+    stack: normalized.stack,
+    info,
+  };
+  currentError.value = record;
+  return record;
+}
+
+export function clearErrorReportingState(): void {
+  currentError.value = null;
+}

package/src/i18n/locales/ar/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "حدث خطأ ما",
-    "hikari::errors.rawDetails": "تفاصيل الخطأ الأصلية"
+    "hikari::errors.rawDetails": "تفاصيل الخطأ الأصلية",
+    "hikari::errors.backHome": "العودة إلى الرئيسية",
+    "hikari::errors.unexpectedDesc": "واجه التطبيق خطأً غير معالج. يمكنك العودة إلى الصفحة الرئيسية أو إعادة المحاولة."
   }
 }

package/src/i18n/locales/de/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "Etwas ist schiefgelaufen",
-    "hikari::errors.rawDetails": "Fehlerdetails im Original"
+    "hikari::errors.rawDetails": "Fehlerdetails im Original",
+    "hikari::errors.backHome": "Zur Startseite",
+    "hikari::errors.unexpectedDesc": "In der Anwendung ist ein unbehandelter Fehler aufgetreten. Sie können zur Startseite zurückkehren oder es erneut versuchen."
   }
 }

package/src/i18n/locales/en/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "Something went wrong",
-    "hikari::errors.rawDetails": "Raw error details"
+    "hikari::errors.rawDetails": "Raw error details",
+    "hikari::errors.backHome": "Back to home",
+    "hikari::errors.unexpectedDesc": "The application hit an unhandled error. You can go back to the home page or retry."
   }
 }

package/src/i18n/locales/es/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "Algo salió mal",
-    "hikari::errors.rawDetails": "Detalles del error original"
+    "hikari::errors.rawDetails": "Detalles del error original",
+    "hikari::errors.backHome": "Volver al inicio",
+    "hikari::errors.unexpectedDesc": "La aplicación encontró un error no controlado. Puede volver al inicio o reintentar."
   }
 }

package/src/i18n/locales/fr/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "Une erreur est survenue",
-    "hikari::errors.rawDetails": "Détails bruts de l'erreur"
+    "hikari::errors.rawDetails": "Détails bruts de l'erreur",
+    "hikari::errors.backHome": "Retour à l'accueil",
+    "hikari::errors.unexpectedDesc": "L'application a rencontré une erreur non gérée. Vous pouvez revenir à l'accueil ou réessayer."
   }
 }

package/src/i18n/locales/ja/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "問題が発生しました",
-    "hikari::errors.rawDetails": "エラーの詳細（原文）"
+    "hikari::errors.rawDetails": "エラーの詳細（原文）",
+    "hikari::errors.backHome": "ホームに戻る",
+    "hikari::errors.unexpectedDesc": "アプリケーションで未処理のエラーが発生しました。ホームに戻るか、再試行できます。"
   }
 }

package/src/i18n/locales/ko/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "문제가 발생했습니다",
-    "hikari::errors.rawDetails": "원본 오류 세부 정보"
+    "hikari::errors.rawDetails": "원본 오류 세부 정보",
+    "hikari::errors.backHome": "홈으로 돌아가기",
+    "hikari::errors.unexpectedDesc": "애플리케이션에서 처리되지 않은 오류가 발생했습니다. 홈으로 돌아가거나 다시 시도할 수 있습니다."
   }
 }

package/src/i18n/locales/pt/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "Algo deu errado",
-    "hikari::errors.rawDetails": "Detalhes do erro original"
+    "hikari::errors.rawDetails": "Detalhes do erro original",
+    "hikari::errors.backHome": "Voltar ao início",
+    "hikari::errors.unexpectedDesc": "O aplicativo encontrou um erro não tratado. Você pode voltar ao início ou tentar novamente."
   }
 }

package/src/i18n/locales/ru/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "Что-то пошло не так",
-    "hikari::errors.rawDetails": "Исходные детали ошибки"
+    "hikari::errors.rawDetails": "Исходные детали ошибки",
+    "hikari::errors.backHome": "На главную",
+    "hikari::errors.unexpectedDesc": "В приложении произошла необработанная ошибка. Вы можете вернуться на главную страницу или повторить попытку."
   }
 }

package/src/i18n/locales/zh-Hans/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "出错了",
-    "hikari::errors.rawDetails": "原始错误详情"
+    "hikari::errors.rawDetails": "原始错误详情",
+    "hikari::errors.backHome": "返回首页",
+    "hikari::errors.unexpectedDesc": "应用遇到了未处理的错误，您可以返回首页或重试。"
   }
 }

package/src/i18n/locales/zh-Hant/errors.json

@@ -1,6 +1,8 @@
 {
   "errors": {
     "hikari::errors.defaultTitle": "出錯了",
-    "hikari::errors.rawDetails": "原始錯誤詳情"
+    "hikari::errors.rawDetails": "原始錯誤詳情",
+    "hikari::errors.backHome": "返回首頁",
+    "hikari::errors.unexpectedDesc": "應用程式遇到未處理的錯誤，您可以返回首頁或重試。"
   }
 }

package/src/index.ts

@@ -111,7 +111,17 @@ export { default as HErrorBoundary } from "./components/HkErrorBoundary";
 export {
   HkErrorLanding as HErrorLanding,
   type HErrorTone,
+  type HErrorLandingVariant,
 } from "./components/HkErrorLanding";
+export { HkErrorReportingOverlay as HErrorReportingOverlay } from "./errorReporting";
+export {
+  createErrorReporting,
+  reportGlobalError,
+  clearGlobalError,
+  type HkErrorReportingOptions,
+  type HkErrorSource,
+  type HkReportedError,
+} from "./errorReporting";
 export { default as HDraggableList } from "./components/HkDraggableList";
 export { default as HDraggableGrid } from "./components/HkDraggableGrid";
 export { default as HSelectionGrid } from "./components/HkSelectionGrid";

package/src/components/HkErrorBoundary.scss

@@ -1,67 +0,0 @@
-// Use theme variables with namespace to avoid conflicts
-@use "./hikari-vars" as vars;
-
-.hk-error-boundary {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 2rem;
-}
-
-.hk-error-boundary-card {
-  max-width: 28rem;
-  width: 100%;
-  background: rgb(from var(--hi-color-error, #f85149) r g b / 0.06);
-  border: 1px solid rgb(from var(--hi-color-error, #f85149) r g b / 0.18);
-  border-radius: 8px;
-  padding: 1.25rem;
-  display: flex;
-  flex-direction: column;
-  gap: 0.75rem;
-}
-
-.hk-error-boundary-header {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-}
-
-.hk-error-boundary-icon {
-  color: var(--hi-color-error, #f85149);
-  flex-shrink: 0;
-}
-
-.hk-error-boundary-label {
-  font-size: 0.75rem;
-  font-weight: 600;
-  color: var(--hi-color-error, #f85149);
-  letter-spacing: 0.02em;
-  text-transform: uppercase;
-}
-
-.hk-error-boundary-tag {
-  font-size: 0.75rem;
-  font-weight: 500;
-  padding: 0.0625rem 0.375rem;
-  border-radius: 4px;
-  background: rgb(from var(--hi-color-error, #f85149) r g b / 0.12);
-  color: var(--hi-color-error, #f85149);
-  font-family: var(--font-mono, vars.$hikari-font-family-mono);
-}
-
-.hk-error-boundary-msg {
-  font-size: 0.8125rem;
-  line-height: 1.5;
-  color: var(--hi-color-text-primary, #c9d1d9);
-  opacity: 0.85;
-  word-break: break-word;
-  white-space: pre-wrap;
-  font-family: var(--font-mono, vars.$hikari-font-family-mono);
-}
-
-.hk-error-boundary-actions {
-  display: flex;
-  align-items: center;
-  justify-content: flex-end;
-  gap: 0.5rem;
-}