@celestia-island/hikari 0.4.4 → 0.30.0

package/src/composables/messaging/browserTransport.ts

@@ -0,0 +1,96 @@
+import { defaultDurationFor, defaultRequireInteraction, type MessagePayload, type MessageTransport } from "./types";
+import { scheduleCronAfter } from "@celestia-island/hikari";
+
+/**
+ * Browser Notifications API transport.
+ *
+ * Fires a native OS notification via `window.Notification`. Used when the page
+ * is hidden (user is in another tab/app) and the user has granted permission.
+ *
+ * Lifecycle notes:
+ *  - `available()` only returns true when the API is present *and* the user
+ *    has granted permission. Callers should call `requestPermission()` from
+ *    a user-gesture-triggered flow (e.g. a settings toggle) before relying
+ *    on this transport — browsers reject permission prompts that aren't
+ *    initiated by a user gesture.
+ *  - For error/warning severities we mirror the toast policy: the
+ *    notification is auto-closed after the same 30s window so the two
+ *    surfaces feel consistent. Errors additionally request sticky
+ *    interaction (`requireInteraction: true`) so they survive OS auto-hide.
+ *  - `onclick` focuses the originating window so the user lands back on the
+ *    app — this is the bridge back into the SPA from the OS surface.
+ */
+export const browserTransport: MessageTransport = {
+  name: "browser",
+  available: () =>
+    typeof Notification !== "undefined" && Notification.permission === "granted",
+  send(payload: MessagePayload) {
+    if (typeof Notification === "undefined") return;
+    if (Notification.permission !== "granted") return;
+
+    const severity = payload.severity;
+    const requireInteraction =
+      payload.requireInteraction ?? defaultRequireInteraction(severity);
+
+    const headlineSource = payload.title || payload.message;
+    const title = headlineSource.split("\n")[0]?.slice(0, 200) || headlineSource;
+    const body =
+      payload.body ||
+      (payload.message.length > title.length ? payload.message : undefined);
+
+    let notification: Notification;
+    try {
+      notification = new Notification(title, {
+        body,
+        tag: payload.tag,
+        requireInteraction,
+        data: payload.data,
+      });
+    } catch {
+      // Some browsers throw if the document isn't focused or service worker
+      // is unavailable. Swallow — the toast transport still covers the user.
+      return;
+    }
+
+    notification.onclick = () => {
+      try {
+        window.focus();
+      } catch {
+        // Cross-origin or no-op — ignore.
+      }
+      notification.close();
+    };
+
+    // Mirror the toast auto-close window for transient severities. Errors
+    // default to sticky (requireInteraction) and are skipped here.
+    if (!requireInteraction) {
+      const ttl = payload.duration ?? defaultDurationFor(severity);
+      if (ttl > 0) {
+        scheduleCronAfter(() => {
+          try {
+            notification.close();
+          } catch {
+            // Already closed — ignore.
+          }
+        }, ttl);
+      }
+    }
+  },
+};
+
+/**
+ * Request browser notification permission. Must be invoked from a user
+ * gesture (click handler) — browsers otherwise silently deny.
+ *
+ * Returns the resulting permission state. The shared permission ref inside
+ * {@link useMessaging} is updated as a side effect.
+ */
+export async function requestBrowserPermission(): Promise<NotificationPermission> {
+  if (typeof Notification === "undefined") return "denied";
+  if (Notification.permission !== "default") return Notification.permission;
+  try {
+    return await Notification.requestPermission();
+  } catch {
+    return Notification.permission;
+  }
+}

package/src/composables/messaging/index.ts

@@ -0,0 +1,204 @@
+import { computed, readonly, ref } from "vue";
+
+import { browserTransport, requestBrowserPermission } from "./browserTransport";
+import { toastTransport } from "./toastTransport";
+import { defaultCopyable, defaultDurationFor, type MessagePayload, type MessageSeverity, type MessageTransport, type NotifyOptions, type TransportName } from "./types";
+
+// Re-export the messaging types from the public entry point so consumers
+// can `import type { MessageSeverity } from "./messaging"`.
+export type {
+  MessagePayload,
+  MessageSeverity,
+  MessageTransport,
+  NotifyOptions,
+  TransportName,
+} from "./types";
+
+/**
+ * Registry of all known transports, in priority order.
+ *
+ * Built-ins (`toast`, `browser`) are pre-registered. Native client bridges
+ * (Tauri desktop, mobile native, iOS APNs long-poll) push themselves here
+ * via {@link registerTransport} during boot — typically by reading
+ * `window.__nativeBridge` and wrapping it in a {@link MessageTransport}.
+ */
+const transports: MessageTransport[] = [toastTransport, browserTransport];
+
+/** Page visibility — drives the toast-vs-browser routing decision. */
+const _pageHidden = ref(typeof document !== "undefined" && document.hidden);
+if (typeof document !== "undefined") {
+  const onVis = () => { _pageHidden.value = document.hidden; };
+  document.addEventListener("visibilitychange", onVis);
+}
+const pageHidden = computed(() => _pageHidden.value);
+
+/** Live browser notification permission. */
+const browserPermission = ref<NotificationPermission>(
+  typeof Notification !== "undefined" ? Notification.permission : "denied",
+);
+
+function refreshPermission() {
+  if (typeof Notification !== "undefined") {
+    browserPermission.value = Notification.permission;
+  }
+}
+
+let nextId = 0;
+
+/**
+ * Register a new transport (e.g. a native bridge). Idempotent — re-registering
+ * the same name replaces the prior instance and disposes it if supported.
+ *
+ * Returns an unregister handle so ephemeral bridges (e.g. a reconnecting
+ * WebSocket-based push subscription) can tear themselves down cleanly.
+ */
+export function registerTransport(transport: MessageTransport): () => void {
+  const idx = transports.findIndex((t) => t.name === transport.name);
+  if (idx !== -1) {
+    const [prev] = transports.splice(idx, 1);
+    prev.dispose?.();
+  }
+  transports.push(transport);
+  return () => {
+    const i = transports.indexOf(transport);
+    if (i !== -1) {
+      const [removed] = transports.splice(i, 1);
+      removed.dispose?.();
+    }
+  };
+}
+
+/**
+ * Register a native bridge discovered on `window.__nativeBridge`. Safe to call
+ * unconditionally — no-ops if no bridge is present. Future native client
+ * integrations (Tauri `notification` plugin, HarmonyOS `NotificationService`,
+ * iOS long-poll subscriber) should hook in here.
+ */
+export function registerNativeBridge(): () => void {
+  const bridge =
+    typeof window !== "undefined"
+      ? (window as unknown as { __nativeBridge?: MessageTransport }).__nativeBridge
+      : undefined;
+  if (!bridge || typeof bridge.send !== "function") return () => {};
+  if (bridge.name !== "native") {
+    // Coerce the name so routing allow-lists resolve consistently.
+    (bridge as MessageTransport).name = "native";
+  }
+  return registerTransport(bridge);
+}
+
+/**
+ * Decide which transports a given payload should fire on. Returns the
+ * filtered list (in registry order).
+ *
+ * Routing policy:
+ *   - `toast`: ALWAYS (it's the in-app surface; cheap and visible when the
+ *     user returns).
+ *   - `browser`: ONLY when the page is hidden AND permission is granted AND
+ *     the severity is actionable off-page (error/warning/success). Pure info
+ *     pings don't earn an OS-level interruption.
+ *   - `native`: ALWAYS when available (the native shell decides how to render
+ *     based on its own focus state — we don't second-guess it from the web
+ *     layer).
+ */
+function routePayload(
+  payload: MessagePayload,
+  allowList: TransportName[] | "all",
+): MessageTransport[] {
+  const allow = allowList === "all" ? null : new Set(allowList);
+  const out: MessageTransport[] = [];
+  for (const t of transports) {
+    if (allow && !allow.has(t.name)) continue;
+    if (!t.available()) continue;
+    if (t.name === "browser") {
+      const actionable =
+        payload.severity === "error" ||
+        payload.severity === "warning" ||
+        payload.severity === "success";
+      if (!payload.pageHidden || !actionable) continue;
+    }
+    out.push(t);
+  }
+  return out;
+}
+
+/**
+ * Unified messaging context. Drop-in replacement for {@link useToast} at call
+ * sites that want cross-transport routing — the helper signatures
+ * (`error`/`warning`/`success`/`info`) mirror the toast API to make migration
+ * mechanical.
+ *
+ * @example
+ * const msg = useMessaging();
+ * msg.error(t("auth.login.failed"));          // top-right toast + (if hidden) browser push
+ * msg.warning("Disk almost full", { tag: "disk" });
+ * msg.notify("Saved", { severity: "success", transports: ["toast"] }); // in-app only
+ */
+export function useMessaging() {
+  function notify(message: string, options: NotifyOptions = {}): number {
+    const severity: MessageSeverity = options.severity || "info";
+    const payload: MessagePayload = {
+      id: ++nextId,
+      severity,
+      message,
+      title: options.title,
+      body: options.body,
+      tag: options.tag,
+      requireInteraction: options.requireInteraction,
+      copyable: options.copyable ?? defaultCopyable(severity),
+      duration: options.duration ?? defaultDurationFor(severity),
+      data: options.data,
+      timestamp: Date.now(),
+      pageHidden: pageHidden.value,
+    };
+
+    const routed = routePayload(payload, options.transports ?? "all");
+    for (const t of routed) {
+      try {
+        t.send(payload);
+      } catch {
+        // Transport failure must never propagate — the next transport still
+        // gets a chance.
+      }
+    }
+    return payload.id;
+  }
+
+  function error(message: string, options: Omit<NotifyOptions, "severity"> = {}) {
+    return notify(message, { ...options, severity: "error" });
+  }
+  function warning(message: string, options: Omit<NotifyOptions, "severity"> = {}) {
+    return notify(message, { ...options, severity: "warning" });
+  }
+  function success(message: string, options: Omit<NotifyOptions, "severity"> = {}) {
+    return notify(message, { ...options, severity: "success" });
+  }
+  function info(message: string, options: Omit<NotifyOptions, "severity"> = {}) {
+    return notify(message, { ...options, severity: "info" });
+  }
+
+  /**
+   * Request browser notification permission. Must be called from a user
+   * gesture handler (button click) — otherwise browsers silently deny.
+   */
+  async function ensureBrowserPermission(): Promise<NotificationPermission> {
+    const result = await requestBrowserPermission();
+    refreshPermission();
+    return result;
+  }
+
+  return {
+    notify,
+    error,
+    warning,
+    success,
+    info,
+    ensureBrowserPermission,
+    /** Whether the browser tab is currently hidden. Reactive. */
+    pageHidden: readonly(pageHidden),
+    /** Live browser notification permission. Reactive. */
+    browserPermission: readonly(browserPermission),
+    /** Register a transport at runtime (e.g. native bridge). */
+    registerTransport,
+  };
+}

package/src/composables/messaging/messaging.test.ts

@@ -0,0 +1,256 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useToast } from "@celestia-island/hikari";
+import { registerNativeBridge, registerTransport, useMessaging } from "./index";
+import type { MessagePayload, MessageTransport } from "./types";
+
+function flushToasts() {
+  const { toasts, remove } = useToast();
+  while (toasts.length > 0) remove(toasts[0].id);
+}
+
+function makeStubTransport(name: MessageTransport["name"]): MessageTransport & {
+  calls: MessagePayload[];
+} {
+  const calls: MessagePayload[] = [];
+  return {
+    name,
+    available: () => true,
+    send: (p) => calls.push(p),
+    calls,
+  };
+}
+
+describe("useMessaging", () => {
+  beforeEach(() => {
+    flushToasts();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("severity helpers", () => {
+    it("error() routes through the toast transport by default", () => {
+      const { toasts } = useToast();
+      const { error } = useMessaging();
+      error("boom");
+      expect(toasts).toHaveLength(1);
+      expect(toasts[0].type).toBe("error");
+      expect(toasts[0].messages[0].text).toBe("boom");
+      expect(toasts[0].duration).toBe(30_000);
+      expect(toasts[0].copyable).toBe(true);
+    });
+
+    it("warning() shares the 30s long-lived duration", () => {
+      const { toasts } = useToast();
+      const { warning } = useMessaging();
+      warning("careful");
+      expect(toasts[0].type).toBe("warning");
+      expect(toasts[0].duration).toBe(30_000);
+    });
+
+    it("success/info keep the short duration", () => {
+      const { toasts } = useToast();
+      const { success, info } = useMessaging();
+      success("yep");
+      expect(toasts[0].duration).toBe(3_000);
+      info("hi");
+      expect(toasts[1].duration).toBe(3_000);
+    });
+
+    it("notify() accepts an explicit duration override", () => {
+      const { toasts } = useToast();
+      const { notify } = useMessaging();
+      notify("manual", { severity: "error", duration: 1_000 });
+      expect(toasts[0].duration).toBe(1_000);
+    });
+  });
+
+  describe("transport allow-list", () => {
+    it("respects transports: ['toast'] to suppress other channels", () => {
+      const stub = makeStubTransport("native");
+      const unregister = registerTransport(stub);
+      const { notify } = useMessaging();
+      notify("hi", { severity: "info", transports: ["toast"] });
+      expect(stub.calls).toHaveLength(0);
+      unregister();
+    });
+
+    it("still routes to whitelisted transports", () => {
+      const stub = makeStubTransport("native");
+      const unregister = registerTransport(stub);
+      const { notify } = useMessaging();
+      notify("hi", { severity: "info", transports: ["toast", "native"] });
+      expect(stub.calls).toHaveLength(1);
+      unregister();
+    });
+  });
+
+  describe("registerTransport", () => {
+    it("is idempotent on name and replaces the prior transport", () => {
+      const a = makeStubTransport("native");
+      const b = makeStubTransport("native");
+      const unA = registerTransport(a);
+      const unB = registerTransport(b);
+      const { notify } = useMessaging();
+      notify("x", { severity: "info", transports: ["native"] });
+      expect(a.calls).toHaveLength(0);
+      expect(b.calls).toHaveLength(1);
+      unB();
+      unA();
+    });
+
+    it("unregister handle removes the transport", () => {
+      const stub = makeStubTransport("native");
+      const unregister = registerTransport(stub);
+      const { notify } = useMessaging();
+      notify("x", { severity: "info", transports: ["native"] });
+      expect(stub.calls).toHaveLength(1);
+      stub.calls.length = 0;
+      unregister();
+      notify("y", { severity: "info", transports: ["native"] });
+      expect(stub.calls).toHaveLength(0);
+    });
+
+    it("skips transports that report unavailable", () => {
+      const unavailableStub: MessageTransport = {
+        name: "native",
+        available: () => false,
+        send: vi.fn(),
+      };
+      const unregister = registerTransport(unavailableStub);
+      const { notify } = useMessaging();
+      notify("x", { severity: "info", transports: ["native"] });
+      expect(unavailableStub.send).not.toHaveBeenCalled();
+      unregister();
+    });
+
+    it("isolates a transport failure — other transports still fire", () => {
+      const exploding: MessageTransport = {
+        name: "native",
+        available: () => true,
+        send: () => {
+          throw new Error("boom");
+        },
+      };
+      const un = registerTransport(exploding);
+      const { toasts } = useToast();
+      const { notify } = useMessaging();
+      expect(() => notify("x", { severity: "info" })).not.toThrow();
+      // Toast transport should still have fired despite the native throw.
+      expect(toasts.length).toBeGreaterThan(0);
+      un();
+    });
+  });
+
+  describe("registerNativeBridge", () => {
+    it("no-ops when window.__nativeBridge is absent", () => {
+      const w = window as unknown as { __nativeBridge?: unknown };
+      const original = w.__nativeBridge;
+      delete w.__nativeBridge;
+      try {
+        const unregister = registerNativeBridge();
+        expect(typeof unregister).toBe("function");
+        // With no native bridge registered, a message restricted to the
+        // "native" allow-list must not be delivered to ANY transport —
+        // including the always-present toast surface.
+        const { toasts } = useToast();
+        const { notify } = useMessaging();
+        notify("native hi", { severity: "info", transports: ["native"] });
+        expect(toasts).toHaveLength(0);
+        unregister();
+      } finally {
+        if (original !== undefined) w.__nativeBridge = original;
+      }
+    });
+
+    it("registers a discovered bridge under the 'native' name", () => {
+      const calls: MessagePayload[] = [];
+      const bridge = {
+        name: "custom" as const,
+        available: () => true,
+        send: (p: MessagePayload) => calls.push(p),
+      };
+      const w = window as unknown as { __nativeBridge?: unknown };
+      const original = w.__nativeBridge;
+      w.__nativeBridge = bridge;
+      try {
+        const unregister = registerNativeBridge();
+        const { notify } = useMessaging();
+        notify("native hi", { severity: "warning", transports: ["native"] });
+        expect(bridge.name).toBe("native");
+        expect(calls).toHaveLength(1);
+        expect(calls[0].severity).toBe("warning");
+        unregister();
+      } finally {
+        if (original !== undefined) w.__nativeBridge = original;
+        else delete w.__nativeBridge;
+      }
+    });
+  });
+
+  describe("browser transport gating", () => {
+    it("does not throw when Notification is unavailable (SSR-like)", () => {
+      const w = window as unknown as { Notification?: unknown };
+      const original = w.Notification;
+      delete w.Notification;
+      try {
+        const { toasts } = useToast();
+        const { error } = useMessaging();
+        expect(() => error("no Notification API")).not.toThrow();
+        // Toast still covers the user.
+        expect(toasts).toHaveLength(1);
+      } finally {
+        if (original !== undefined) w.Notification = original;
+      }
+    });
+
+    it("defaults requireInteraction to true only for errors", async () => {
+      const created: Array<{ title: string; requireInteraction: boolean }> = [];
+      const w = window as unknown as {
+        Notification?: typeof Notification;
+      };
+      const Original = w.Notification;
+      class FakeNotification {
+        static permission: NotificationPermission = "granted";
+        static requestPermission = vi.fn().mockResolvedValue("granted");
+        title: string;
+        options?: NotificationOptions;
+        onclick: (() => void) | null = null;
+        close() {}
+        constructor(title: string, options?: NotificationOptions) {
+          this.title = title;
+          this.options = options;
+          created.push({ title, requireInteraction: !!options?.requireInteraction });
+        }
+      }
+      w.Notification = FakeNotification as unknown as typeof Notification;
+      try {
+        // Exercise the browser transport's `send()` directly to assert the
+        // severity-driven requireInteraction default (the public routing
+        // layer is covered elsewhere).
+        const { browserTransport } = await import("./browserTransport");
+        browserTransport.send({
+          id: 1,
+          severity: "error",
+          message: "boom",
+          timestamp: Date.now(),
+          pageHidden: true,
+        });
+        browserTransport.send({
+          id: 2,
+          severity: "warning",
+          message: "careful",
+          timestamp: Date.now(),
+          pageHidden: true,
+        });
+        expect(created).toHaveLength(2);
+        expect(created[0].requireInteraction).toBe(true); // error → sticky
+        expect(created[1].requireInteraction).toBe(false); // warning → transient
+      } finally {
+        if (Original !== undefined) w.Notification = Original;
+      }
+    });
+  });
+});

package/src/composables/messaging/toastTransport.ts

@@ -0,0 +1,26 @@
+import { useToast } from "@celestia-island/hikari";
+import type { MessagePayload, MessageTransport } from "./types";
+
+/**
+ * In-app toast transport. Always available while the SPA is mounted — the
+ * toast container lives in {@link AppShell} and is teleport-bound to
+ * `document.body`, so it renders even when individual route views are
+ * unmounted.
+ *
+ * The toast is the canonical surface for user feedback: even when the page
+ * is hidden and a browser notification fires, the same payload is also pushed
+ * here so the user sees it the moment they return (within the 30s
+ * warning/error window).
+ */
+export const toastTransport: MessageTransport = {
+  name: "toast",
+  available: () => true,
+  send(payload: MessagePayload) {
+    const toast = useToast();
+    toast.show(payload.message, {
+      type: payload.severity,
+      duration: payload.duration,
+      copyable: payload.copyable,
+    });
+  },
+};

package/src/composables/messaging/types.ts

@@ -0,0 +1,115 @@
+/**
+ * Unified messaging context — types & contracts.
+ *
+ * The messaging context routes user-facing notifications through one or more
+ * {@link MessageTransport} adapters. The routing decision is driven by the
+ * page-visibility state and the per-transport availability (e.g. browser
+ * notification permission).
+ *
+ * Built-in transports:
+ *   - {@link "toast"} — always available; renders via {@link useToast} in the
+ *     top-right corner.
+ *   - {@link "browser"} — the Web Notifications API; used when the page is
+ *     hidden and the user has granted permission.
+ *
+ * Future transports (desktop/mobile/iOS long-poll) will be registered via
+ * {@link registerTransport} and follow the same {@link MessageTransport}
+ * contract. Native bridges are expected to expose themselves on
+ * `window.__nativeBridge` and call {@link registerTransport} at boot — the
+ * messaging layer is transport-agnostic.
+ */
+
+/** User-facing severity. Mirrors {@link ToastType} so toasts stay the source of truth. */
+export type MessageSeverity = "error" | "warning" | "success" | "info" | "loading";
+
+/** Transport identifiers used by the routing layer. */
+export type TransportName = "toast" | "browser" | "native";
+
+/**
+ * Options accepted by {@link useMessaging}'s helpers.
+ *
+ * Most fields are transport-agnostic; transports pick the ones they understand
+ * (e.g. the browser transport uses {@link title} as the notification headline
+ * while the toast transport only renders {@link message}).
+ */
+export interface NotifyOptions {
+  severity?: MessageSeverity;
+  /** Short headline. Used by browser/native transports; toast falls back to {@link message}. */
+  title?: string;
+  /** Long-form body. Used by browser/native transports when set. */
+  body?: string;
+  /** Toast auto-close ms. `0` keeps the toast sticky. Defaults to severity-based duration. */
+  duration?: number;
+  /** Toast: show the copy button. Defaults to `true` for error/warning. */
+  copyable?: boolean;
+  /** Browser: dedup tag — same-tag notifications replace each other. */
+  tag?: string;
+  /** Browser: stay open until user dismisses. Defaults to severity-driven. */
+  requireInteraction?: boolean;
+  /**
+   * Restrict routing to a subset of transports. `"all"` (default) lets the
+   * visibility/permission gate decide. Useful for low-priority pings that
+   * should never interrupt the user off-page (e.g. `transports: ["toast"]`).
+   */
+  transports?: TransportName[] | "all";
+  /**
+   * Opaque payload reserved for future native transports (desktop IPC, mobile
+   * push subscription, iOS APNs long-poll). Passed through untouched.
+   */
+  data?: Record<string, unknown>;
+}
+
+/** Fully-resolved message handed to each transport. */
+export interface MessagePayload {
+  id: number;
+  severity: MessageSeverity;
+  /** Primary text — always populated. */
+  message: string;
+  title?: string;
+  body?: string;
+  tag?: string;
+  requireInteraction?: boolean;
+  copyable?: boolean;
+  duration?: number;
+  data?: Record<string, unknown>;
+  /** Epoch ms — useful for native transports that queue/batch. */
+  timestamp: number;
+  /** Whether the page was hidden when this message was dispatched. */
+  pageHidden: boolean;
+}
+
+/**
+ * Contract every push channel must implement.
+ *
+ * Transports are stateless from the registry's perspective: they receive a
+ * resolved payload and decide for themselves how to render it. Availability
+ * (e.g. permission, native bridge presence) is checked before each send so
+ * transports can degrade gracefully without re-registration.
+ */
+export interface MessageTransport {
+  /** Stable identifier — used by {@link NotifyOptions.transports} allow-lists. */
+  name: TransportName;
+  /** Whether this transport can be used right now (permission, bridge present, …). */
+  available(): boolean;
+  /** Issue the message. Must not throw — wrap failures in a no-op. */
+  send(payload: MessagePayload): void;
+  /** Optional teardown for transports that own resources (event listeners, etc.). */
+  dispose?(): void;
+}
+
+/** Convenience: severity → default toast duration (mirrors {@link TOAST_DURATION}). */
+export function defaultDurationFor(severity: MessageSeverity): number {
+  if (severity === "error" || severity === "warning") return 30_000;
+  if (severity === "loading") return 0;
+  return 3_000;
+}
+
+/** Convenience: severity → whether a browser notification should stay sticky. */
+export function defaultRequireInteraction(severity: MessageSeverity): boolean {
+  return severity === "error";
+}
+
+/** Convenience: severity → default copyable flag for the toast surface. */
+export function defaultCopyable(severity: MessageSeverity): boolean {
+  return severity === "error" || severity === "warning";
+}