feat: add Electron-compatible Notification module with libnotify on Linux and best-effort NSUserNotification on macOS

Author: ipfizz

src/main/api/notification.ts

@@ -0,0 +1,135 @@
+import { EventEmitter } from 'node:events';
+import { UnsupportedPlatformError } from '../../common/errors';
+import { currentPlatform } from '../../common/platform';
+import { linuxNotificationBackend } from '../platform/linux/gtk-notification';
+import { macosNotificationBackend } from '../platform/macos/cocoa-notification';
+
+/**
+ * Native desktop notifications — the drop-in equivalent of Electron's
+ * `Notification`.
+ *
+ * Extends Node's {@link EventEmitter} so the full listener API
+ * (`on`/`once`/`addListener`/…) matches Electron's contract. Events:
+ * - `show` — emitted synchronously from {@link Notification.show}.
+ * - `close` — emitted when the OS reports the notification was dismissed/closed,
+ *   IF the platform backend can wire it (Linux libnotify exposes a `closed`
+ *   signal; macOS un-bundled cannot, so it is best-effort there).
+ *
+ * `click` (and other user-action events) are DEFERRED in v1: they require an OS
+ * delegate/action wiring that is not yet implemented. They are intentionally not
+ * advertised so consumers do not rely on events Sambar does not deliver.
+ *
+ * The native backend is injectable (mirrors `menu`/`dialog`/`shell`) so the
+ * class's option-mapping, event wiring, and lifecycle are unit-testable with a
+ * fake — no FFI required.
+ */
+
+export type NotificationOptions = {
+  readonly title?: string;
+  readonly body?: string;
+  readonly subtitle?: string;
+  readonly silent?: boolean;
+};
+
+/** The fields a backend needs to present one notification. */
+export type NotificationSpec = {
+  readonly title: string;
+  readonly body: string;
+  readonly subtitle: string;
+  readonly silent: boolean;
+};
+
+/** A live, presented notification the API can close and observe. */
+export type NotificationHandle = {
+  /** Dismiss the notification. Safe to call more than once. */
+  close(): void;
+  /** Register a callback fired when the OS closes/dismisses the notification. */
+  onClosed(callback: () => void): void;
+};
+
+/** The native backend the public `Notification` API delegates to. */
+export type NotificationBackend = {
+  /** The HONEST per-platform answer to whether notifications can be delivered. */
+  isSupported(): boolean;
+  /** Present a notification and return a handle to close/observe it. */
+  present(spec: NotificationSpec): NotificationHandle;
+};
+
+const macosBackend: NotificationBackend = macosNotificationBackend;
+const linuxBackend: NotificationBackend = linuxNotificationBackend;
+
+let backend: NotificationBackend | undefined;
+
+const getBackend = (): NotificationBackend => {
+  if (backend !== undefined) {
+    return backend;
+  }
+  if (currentPlatform() === 'macos') {
+    return macosBackend;
+  }
+  if (currentPlatform() === 'linux') {
+    return linuxBackend;
+  }
+  throw new UnsupportedPlatformError(`Notification is not supported on ${currentPlatform()} yet`);
+};
+
+/** Override the native notification backend. Test-only. */
+export const setNotificationBackendForTesting = (fake: NotificationBackend | undefined): void => {
+  backend = fake;
+};
+
+export class Notification extends EventEmitter {
+  /** Notification title (the bold first line). */
+  title: string;
+  /** Notification body text. */
+  body: string;
+  /** Secondary line shown under the title (macOS; ignored where unsupported). */
+  subtitle: string;
+  /** Whether to suppress the notification sound. */
+  silent: boolean;
+
+  #handle: NotificationHandle | undefined;
+
+  constructor(options: NotificationOptions = {}) {
+    super();
+    this.title = options.title ?? '';
+    this.body = options.body ?? '';
+    this.subtitle = options.subtitle ?? '';
+    this.silent = options.silent ?? false;
+  }
+
+  /**
+   * Whether the host platform can actually deliver notifications. Honest:
+   * - Linux: libnotify loaded and `notify_init` succeeded.
+   * - macOS: `false` un-bundled (the default notification center is nil without
+   *   an app bundle); reliable delivery needs packaging (a follow-up).
+   */
+  static isSupported(): boolean {
+    return getBackend().isSupported();
+  }
+
+  /** Display the notification and emit `show`. */
+  show(): void {
+    const handle = getBackend().present({
+      title: this.title,
+      body: this.body,
+      subtitle: this.subtitle,
+      silent: this.silent,
+    });
+    this.#handle = handle;
+    handle.onClosed(() => {
+      this.emit('close');
+    });
+    this.emit('show');
+  }
+
+  /** Dismiss the notification if it is showing. Idempotent. */
+  close(): void {
+    const handle = this.#handle;
+    if (handle === undefined) {
+      return;
+    }
+    this.#handle = undefined;
+    handle.close();
+  }
+}

src/main/index.ts

@@ -19,6 +19,7 @@ export {
   type MenuItemType,
 } from './api/menu';
 export { nativeTheme, type NativeTheme } from './api/native-theme';
+export { Notification, type NotificationOptions } from './api/notification';
 export { shell, type Shell } from './api/shell';
 export {
   FFIError,

src/main/module-list.ts

@@ -65,6 +65,7 @@ export const IMPLEMENTED_MODULES = [
   'Menu',
   'MenuItem',
   'nativeTheme',
+  'Notification',
   'shell',
 ] as const;
 

src/main/platform/linux/gtk-notification.ts

@@ -0,0 +1,111 @@
+import { JSCallback, type Pointer } from 'bun:ffi';
+import type {
+  NotificationBackend,
+  NotificationHandle,
+  NotificationSpec,
+} from '../../api/notification';
+import { cstr } from '../cstr';
+import { connectSignal } from './gtk-signals';
+import { loadLibnotifyFFI } from './libnotify-ffi';
+
+/**
+ * Linux notifications via libnotify — the Linux half of Sambar's `Notification`.
+ *
+ * libnotify forwards to the session's notification daemon over D-Bus.
+ * `notify_init('Sambar')` is called once per process before the first
+ * notification. `notify_notification_new(title, body, NULL)` builds the
+ * notification; `notify_notification_show(n, NULL)` displays it (returns FALSE if
+ * there is no daemon — e.g. headless CI — which is expected and not an error);
+ * `notify_notification_close(n, NULL)` dismisses it.
+ *
+ * The `NotifyNotification::closed` signal is wired via the existing
+ * {@link connectSignal} (`g_signal_connect_data`) so the `Notification`'s `close`
+ * event fires when the daemon/user dismisses it.
+ *
+ * JSCallback lifecycle (a past SIGSEGV class): the `closed` handler thunk MUST
+ * stay reachable for the life of the connection — Bun GCs an unreferenced
+ * {@link JSCallback}, and the daemon would then call into freed memory. Each live
+ * notification therefore RETAINS its callback in the returned handle's closure,
+ * and {@link JSCallback.close} is deferred to a later tick (never called
+ * synchronously inside the handler's own invocation).
+ */
+
+/** ABI shape for `NotifyNotification::closed`: `(notification, user_data) -> void`. */
+export const CLOSED_CB_DEF = { args: ['ptr', 'ptr'], returns: 'void' } as const;
+
+/**
+ * Every `closed`-signal {@link JSCallback} currently wired to a live
+ * notification. Retained at module scope so Bun cannot GC the native thunk while
+ * the daemon still holds its pointer (the SIGSEGV-avoidance retain). Each entry
+ * is removed (and the callback closed on a later tick) when its notification
+ * fires `closed` or is explicitly closed.
+ */
+const liveCallbacks = new Set<JSCallback>();
+
+let initialized = false;
+
+/** Ensure `notify_init('Sambar')` has run once. Returns whether init succeeded. */
+const ensureInit = (): boolean => {
+  const notify = loadLibnotifyFFI();
+  if (initialized || notify.symbols.notify_is_initted() !== 0) {
+    initialized = true;
+    return true;
+  }
+  const ok = notify.symbols.notify_init(cstr('Sambar')) !== 0;
+  initialized = ok;
+  return ok;
+};
+
+const present = (spec: NotificationSpec): NotificationHandle => {
+  const notify = loadLibnotifyFFI();
+  ensureInit();
+
+  const notification = notify.symbols.notify_notification_new(
+    cstr(spec.title),
+    cstr(spec.body),
+    // `cstring` cannot be null via the FFI binding, so an empty icon name (no
+    // icon) is passed instead of NULL — equivalent for our purposes.
+    cstr(''),
+  );
+  if (notification === null) {
+    throw new Error('notify_notification_new() returned null');
+  }
+
+  // No daemon (headless CI) makes show return FALSE — expected, not an error.
+  notify.symbols.notify_notification_show(notification, null);
+
+  return {
+    close: () => {
+      notify.symbols.notify_notification_close(notification, null);
+    },
+    // Wire the daemon's `closed` signal to `cb`. The thunk is retained in
+    // `liveCallbacks` until it fires; it is closed on a LATER tick (never
+    // synchronously inside its own invocation — that would free the trampoline
+    // the daemon is about to return into).
+    onClosed: (cb) => {
+      const callback = new JSCallback((_notification: Pointer, _userData: Pointer): void => {
+        cb();
+        setTimeout(() => {
+          liveCallbacks.delete(callback);
+          callback.close();
+        }, 0);
+      }, CLOSED_CB_DEF);
+      liveCallbacks.add(callback);
+      connectSignal(notification, 'closed', callback);
+    },
+  };
+};
+
+const isSupported = (): boolean => {
+  try {
+    return ensureInit();
+  } catch {
+    return false;
+  }
+};
+
+/** The Linux native notification backend (libnotify). */
+export const linuxNotificationBackend: NotificationBackend = {
+  isSupported,
+  present,
+};

src/main/platform/linux/libnotify-ffi.ts

@@ -0,0 +1,80 @@
+import { dlopen, FFIType } from 'bun:ffi';
+import { UnsupportedPlatformError } from '../../../common/errors';
+import { currentPlatform } from '../../../common/platform';
+
+/**
+ * Loads the libnotify symbols behind Sambar's `Notification` API on Linux.
+ *
+ * libnotify is the freedesktop desktop-notification client library; it forwards
+ * to the session's notification daemon over D-Bus. CI runs headless (xvfb) with
+ * NO notification daemon, so `notify_notification_show` may return FALSE / no-op
+ * there — that is EXPECTED. The integration test therefore asserts only that the
+ * symbols resolve, `notify_init` runs, and construct/show/close do not throw; it
+ * does NOT assert a banner appeared.
+ *
+ * Declared separately from {@link loadLibnotifyFFI} so unit tests can assert ABI
+ * shapes (arg arrays, return types) without `dlopen` on a non-Linux host.
+ *
+ * Convention (matches the existing Linux loaders): `gboolean` is modelled as
+ * {@link FFIType.i32} (compare `!== 0`); the `NotifyNotification*` handle and the
+ * `GError**` out-param are real pointers ({@link FFIType.pointer}); `cstring`
+ * args are NUL-terminated UTF-8 strings. The `GError**` arg is always passed as
+ * `null` (failures are reported via the gboolean return, not unwrapped).
+ *
+ * Only callable on Linux — throws {@link UnsupportedPlatformError} otherwise so
+ * the module stays safely importable on macOS for unit testing.
+ */
+
+const LIBNOTIFY_PATH = 'libnotify.so.4';
+
+/** The libnotify FFI symbol descriptor table (from `libnotify.so.4`). */
+export const LIBNOTIFY_FFI_SYMBOLS = {
+  // (app_name) -> gboolean; call once per process before creating notifications.
+  notify_init: {
+    args: [FFIType.cstring],
+    returns: FFIType.i32,
+  },
+  notify_is_initted: {
+    args: [],
+    returns: FFIType.i32,
+  },
+  // (summary, body, icon) -> NotifyNotification*; body/icon may be NULL.
+  notify_notification_new: {
+    args: [FFIType.cstring, FFIType.cstring, FFIType.cstring],
+    returns: FFIType.pointer,
+  },
+  // (notification, GError** /*null*/) -> gboolean (FALSE if no daemon).
+  notify_notification_show: {
+    args: [FFIType.pointer, FFIType.pointer],
+    returns: FFIType.i32,
+  },
+  // (notification, GError** /*null*/) -> gboolean.
+  notify_notification_close: {
+    args: [FFIType.pointer, FFIType.pointer],
+    returns: FFIType.i32,
+  },
+  // (notification, timeout_ms) -> void; -1 = default, 0 = never expire.
+  notify_notification_set_timeout: {
+    args: [FFIType.pointer, FFIType.i32],
+    returns: FFIType.void,
+  },
+} as const;
+
+const cache: { ffi: ReturnType<typeof dlopen<typeof LIBNOTIFY_FFI_SYMBOLS>> | undefined } = {
+  ffi: undefined,
+};
+
+export const loadLibnotifyFFI = () => {
+  const platform = currentPlatform();
+  if (platform !== 'linux') {
+    throw new UnsupportedPlatformError(
+      `loadLibnotifyFFI() is only supported on Linux; current platform is ${platform}`,
+    );
+  }
+  if (cache.ffi) {
+    return cache.ffi;
+  }
+  const ffi = dlopen(LIBNOTIFY_PATH, LIBNOTIFY_FFI_SYMBOLS);
+  cache.ffi = ffi;
+  return ffi;
+};