@celestia-island/hikari 0.55.166 → 0.55.167

package/package.json

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

package/src/errorReporting/HkErrorReportingOverlay.tsx

@@ -80,6 +80,17 @@ export const HkErrorReportingOverlay = defineComponent({
       if (!err) return null;
       const options = getErrorReportingOptions();
 
+      // Host-owned card: everything inside the takeover is the host's —
+      // content, actions, dismissal. The host keeps the capture channels
+      // and the crash-surviving mount; only the card is swapped.
+      if (options.landing) {
+        return (
+          <div class="hk-error-reporting-overlay" role="alertdialog" aria-live="assertive" aria-modal="true">
+            {options.landing(err)}
+          </div>
+        );
+      }
+
       const description = options.describe
         ? options.describe(err)
         : err.message || t("hikari::errors.unexpectedDesc", "An unhandled error occurred");

package/src/errorReporting/index.test.tsx

@@ -207,4 +207,75 @@ describe("createErrorReporting", () => {
     clearGlobalError();
     expect(overlayHost()).toBeNull();
   });
+
+  it("renders the host landing card instead of the built-in one", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    installPlugin({
+      landing: (err) =>
+        h("div", { class: "host-card", "data-code": err.name }, [
+          h("p", { class: "host-card__msg" }, err.message),
+          h(
+            "button",
+            { class: "host-card__dismiss", onClick: () => clearGlobalError() },
+            "Dismiss",
+          ),
+        ]),
+    });
+    reportGlobalError(new TypeError("host boom"));
+    await nextTick();
+
+    const host = overlayHost();
+    expect(host).not.toBeNull();
+    // The built-in card is fully replaced by the host's.
+    expect(host!.querySelector(".hk-error-landing")).toBeNull();
+    expect(host!.querySelector(".host-card")).not.toBeNull();
+    expect(host!.querySelector(".host-card")!.getAttribute("data-code")).toBe("TypeError");
+    expect(host!.querySelector(".host-card__msg")!.textContent).toBe("host boom");
+    // The host owns the actions: the built-in Home/Retry pair is gone.
+    expect(host!.textContent).not.toContain("Back to home");
+    expect(host!.textContent).not.toContain("Retry");
+    // The takeover shell stays (fixed, alert-dialog semantics).
+    expect(host!.querySelector(".hk-error-reporting-overlay")!.getAttribute("role")).toBe(
+      "alertdialog",
+    );
+    // The host card rides INSIDE the takeover shell (same fixed z-band), not
+    // beside it: a sibling placement would float outside --hk-z-error. The
+    // quadrant of these assertions that pins "same shell" is the ancestor
+    // relationship — descendants of the shell, not just of the data node.
+    expect(host!.querySelector(".hk-error-reporting-overlay .host-card")).not.toBeNull();
+    // The host's own dismissal tears the takeover down.
+    (host!.querySelector(".host-card__dismiss") as HTMLButtonElement).click();
+    await nextTick();
+    expect(overlayHost()).toBeNull();
+  });
+
+  it("lets landing step over title/describe and the built-in actions", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    installPlugin({
+      title: "ignored headline",
+      describe: () => "ignored description",
+      homeHref: "/should-not-be-used",
+      onHome: vi.fn(),
+      onRetry: vi.fn(),
+      landing: (err) =>
+        h("div", { class: "host-card", "data-msg": err.message }, [
+          h("p", { class: "host-card__msg" }, err.message),
+        ]),
+    });
+    reportGlobalError(new TypeError("own content"));
+    await nextTick();
+
+    const host = overlayHost()!;
+    // The host's card won outright; the built-in card (and its translated
+    // headline / description) never mounted.
+    expect(host.querySelector(".hk-error-landing")).toBeNull();
+    expect(host.querySelector(".host-card__msg")!.textContent).toBe("own content");
+    expect(host.textContent).not.toContain("ignored headline");
+    expect(host.textContent).not.toContain("ignored description");
+    expect(host.textContent).not.toContain("Back to home");
+    expect(host.textContent).not.toContain("Retry");
+    // The host card still receives the raw accepted record, not a
+    // title/describe-shaped one — the overrides never leak in.
+    expect(host.querySelector(".host-card")!.getAttribute("data-msg")).toBe("own content");
+  });
 });

package/src/errorReporting/index.ts

@@ -32,6 +32,11 @@ export { HkErrorReportingOverlay } from "./HkErrorReportingOverlay";
  * 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.
  *
+ * Hosts whose error landing carries app-specific semantics pass
+ * `options.landing(err)`: the takeover then renders the host's card inside
+ * the same crash-surviving shell — capture channels and the takeover
+ * guarantee stay, the built-in card and its actions step aside.
+ *
  * Any pre-existing `app.config.errorHandler` is chained, not discarded.
  * All capture channels are optional; `shouldReport` filters, `onError` is
  * the telemetry hook.

package/src/errorReporting/state.ts

@@ -1,4 +1,4 @@
-import { ref, type Ref } from "vue";
+import { ref, type Ref, type VNodeChild } from "vue";
 
 import { reportHkRuntime, type HkRuntimeHandle } from "../runtime/registry";
 
@@ -17,11 +17,23 @@ export interface HkReportedError {
 }
 
 export interface HkErrorReportingOptions {
-  /** Headline override; defaults to `hikari::errors.defaultTitle`. */
+  /** Headline override; defaults to `hikari::errors.defaultTitle`.
+   * Ignored when `landing` is set (the host owns the whole card). */
   title?: string;
   /** Description builder; defaults to the error's message, falling back to
-   * `hikari::errors.unexpectedDesc` when the error carries none. */
+   * `hikari::errors.unexpectedDesc` when the error carries none.
+   * Ignored when `landing` is set. */
   describe?: (err: HkReportedError) => string;
+  /** Host-provided takeover card — the unification hatch for hosts whose
+   * error landing carries app-specific semantics (localized per-code
+   * headlines, raw wire payloads, a Dismiss action). When set, the overlay
+   * renders `landing(err)` INSTEAD of the built-in HkErrorLanding, inside
+   * the same crash-surviving host (dedicated body app, --hk-z-error): the
+   * host keeps every capture channel and the takeover guarantee and owns
+   * the card's content and actions outright — `title`, `describe`,
+   * `homeHref`, `onHome` and `onRetry` are all ignored. Resolve app-shaped
+   * payloads from `err.error` (e.g. an Error subclass carrying them). */
+  landing?: (err: HkReportedError) => VNodeChild;
   /** Target of the "back to home" action. `false` hides the button.
    * Ignored when `onHome` is set. Default `/`. */
   homeHref?: string | false;