mirinjs 0.1.0-alpha.14 → 0.1.0-alpha.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirinjs",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
   ],
   "exports": {
     ".": "./src/index.ts",
-    "./config": "./src/config.ts",
+    "./config": "./src/config/index.ts",
     "./rpc": "./src/rpc.ts",
     "./client": "./src/client.ts",
     "./codec": "./src/codec.ts",

package/src/{app.ts → app/facade.ts}

@@ -3,95 +3,35 @@
  * (docs/api-design.md). Talks to the native core through the runtime.
  */
 
-import { runtime, onNativeEvent, resolveUrl, type NativeEvent } from "./runtime.ts";
-import type { Router, EventProc } from "./rpc.ts";
-import type { WindowConfig, WindowMaterial, WindowMaterialOptions } from "./config.ts";
-import { updater } from "./updater.ts";
-import type { Updater } from "./updater.ts";
-import { sidecar as spawnSidecar } from "./sidecar.ts";
-import type { SidecarOptions, SidecarProcess } from "./sidecar.ts";
-
-/** Which native backend a window's `material` resolved to. */
-export type WindowMaterialInfo = {
-  /** The material that was requested. */
-  requested: string;
-  /** What actually rendered: real Liquid Glass, a vibrancy material, or none. */
-  backend: "liquidGlass" | "vibrancy" | "none";
-  /** Whether Apple's Liquid Glass (NSGlassEffectView, macOS 26+) is available. */
-  liquidGlassAvailable: boolean;
-};
-
-export type WindowEvents = {
-  focus: void;
-  blur: void;
-  moved: void;
-  resized: void;
-  closed: void;
-  /** Fired when a native background material is applied (see setMaterial). */
-  material: WindowMaterialInfo;
-};
-
-export type AppEvents = {
-  ready: void;
-  "window-all-closed": void;
-  /** A deep-link URL (a registered `urlSchemes` scheme) opened the app, or
-   *  arrived while it was running. Includes the launch URL. */
-  "open-url": string;
-};
-
-/** A window's frame in screen points (bottom-left origin, like AppKit). */
-export interface WindowFrame {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-type Listener<P> = (payload: P) => void;
-
-class Emitter<Events extends Record<string, unknown>> {
-  #listeners = new Map<keyof Events, Set<Listener<unknown>>>();
-
-  on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void {
-    let set = this.#listeners.get(type);
-    if (!set) this.#listeners.set(type, (set = new Set()));
-    set.add(listener as Listener<unknown>);
-    return () => set!.delete(listener as Listener<unknown>);
-  }
-
-  async *events<K extends keyof Events>(type: K): AsyncIterableIterator<Events[K]> {
-    const queue: Events[K][] = [];
-    let wake: (() => void) | undefined;
-    const off = this.on(type, (payload) => {
-      queue.push(payload);
-      wake?.();
-    });
-    try {
-      while (true) {
-        while (queue.length) yield queue.shift()!;
-        await new Promise<void>((resolve) => (wake = resolve));
-      }
-    } finally {
-      off();
-    }
-  }
-
-  protected emit<K extends keyof Events>(type: K, payload: Events[K]): void {
-    this.#listeners.get(type)?.forEach((fn) => fn(payload));
-  }
-}
-
-export interface WindowOpenOptions extends WindowConfig {
-  name?: string;
-}
+import type { WindowMaterial, WindowMaterialOptions } from "../config/index.ts";
+import type { Router } from "../rpc.ts";
+import { type NativeEvent, onNativeEvent, resolveUrl, runtime } from "../runtime.ts";
+import type { SidecarOptions, SidecarProcess } from "../sidecar.ts";
+import { sidecar as spawnSidecar } from "../sidecar.ts";
+import type { Updater } from "../updater/index.ts";
+import { updater } from "../updater/index.ts";
+import { Emitter } from "./lib/emitter.ts";
+import { normalizeMaterial } from "./lib/material.ts";
+import type {
+  AppEvents,
+  BroadcastEmitters,
+  Dock,
+  ServeHandle,
+  WindowEvents,
+  WindowFrame,
+  WindowMaterialInfo,
+  WindowOpenOptions,
+} from "./types.ts";
 
 /** A live, typed handle to an open window. */
 export class WindowHandle extends Emitter<WindowEvents> {
-  constructor(
-    readonly id: number,
-    readonly name: string | undefined,
-  ) {
+  readonly id: number;
+  readonly name: string | undefined;
+
+  constructor(id: number, name: string | undefined) {
     super();
+    this.id = id;
+    this.name = name;
   }
 
   async setTitle(title: string): Promise<void> {
@@ -182,7 +122,10 @@ export class WindowHandle extends Emitter<WindowEvents> {
   }
 }
 
-type RpcEmitters = Record<string, { emit(payload: unknown): void; broadcast(payload: unknown): void }>;
+type RpcEmitters = Record<
+  string,
+  { emit(payload: unknown): void; broadcast(payload: unknown): void }
+>;
 
 function rpcEmitters(send: (method: string, payload: unknown) => void): RpcEmitters {
   return new Proxy({} as RpcEmitters, {
@@ -195,20 +138,6 @@ function rpcEmitters(send: (method: string, payload: unknown) => void): RpcEmitt
   });
 }
 
-/** Typed push emitters derived from a router's `event` procedures. */
-export type BroadcastEmitters<R extends Router<any>> =
-  R extends Router<infer T>
-    ? {
-        [K in keyof T as T[K] extends EventProc<any> ? K : never]: T[K] extends EventProc<infer P>
-          ? { broadcast(payload: P): void }
-          : never;
-      }
-    : never;
-
-export interface ServeHandle<R extends Router<any>> {
-  readonly rpc: BroadcastEmitters<R>;
-}
-
 class Windows {
   #byName = new Map<string, WindowHandle>();
   #byId = new Map<number, WindowHandle>();
@@ -267,26 +196,10 @@ function manifestWindow(name: string): WindowOpenOptions {
   return found;
 }
 
-/** Normalize the `material` option (name or object, or null) to native form. */
-function normalizeMaterial(
-  material: WindowMaterial | WindowMaterialOptions | null | undefined,
-): WindowMaterialOptions | null {
-  if (!material) return null;
-  return typeof material === "string" ? { type: material } : material;
-}
-
-/** macOS Dock-icon controls (no-ops off macOS). */
-export interface Dock {
-  /** Hide the Dock icon and menu-bar presence (agent/accessory app). */
-  hide(): void;
-  /** Restore the Dock icon and menu bar. */
-  show(): void;
-}
-
 class MirinApp extends Emitter<AppEvents> {
   readonly windows = new Windows();
 
-  /** Auto-updater (macOS). Inert unless the app was built with `release` set. */
+  /** Cross-platform auto-updater. Inert unless the app was built with `release` set. */
   readonly updater: Updater = updater;
 
   /** This app's bundle id (mirin.config `id`). `undefined` when run detached. */
@@ -328,6 +241,7 @@ class MirinApp extends Emitter<AppEvents> {
     }
   }
 
+  /** Type-level `any` preserves the caller's concrete router shape. */
   serve<R extends Router<any>>(router: R): ServeHandle<R> {
     runtime().rpc.setRouter(router);
     return { rpc: this.rpc as BroadcastEmitters<R> };

package/src/app/index.ts

@@ -0,0 +1,2 @@
+export * from "./facade.ts";
+export * from "./types.ts";

package/src/app/lib/emitter.ts

@@ -0,0 +1,40 @@
+type Listener<P> = (payload: P) => void;
+
+export class Emitter<Events extends Record<string, unknown>> {
+  #listeners = new Map<keyof Events, Set<Listener<unknown>>>();
+
+  on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void {
+    let set = this.#listeners.get(type);
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(type, set);
+    }
+    set.add(listener as Listener<unknown>);
+    return () => {
+      set.delete(listener as Listener<unknown>);
+    };
+  }
+
+  async *events<K extends keyof Events>(type: K): AsyncIterableIterator<Events[K]> {
+    const queue: Events[K][] = [];
+    let wake: (() => void) | undefined;
+    const off = this.on(type, (payload) => {
+      queue.push(payload);
+      wake?.();
+    });
+    try {
+      while (true) {
+        while (queue.length) yield queue.shift()!;
+        await new Promise<void>((resolve) => {
+          wake = resolve;
+        });
+      }
+    } finally {
+      off();
+    }
+  }
+
+  protected emit<K extends keyof Events>(type: K, payload: Events[K]): void {
+    for (const fn of this.#listeners.get(type) ?? []) fn(payload);
+  }
+}

package/src/app/lib/material.ts

@@ -0,0 +1,9 @@
+import type { WindowMaterial, WindowMaterialOptions } from "../../config/index.ts";
+
+/** Normalize the `material` option (name or object, or null) to native form. */
+export function normalizeMaterial(
+  material: WindowMaterial | WindowMaterialOptions | null | undefined,
+): WindowMaterialOptions | null {
+  if (!material) return null;
+  return typeof material === "string" ? { type: material } : material;
+}

package/src/app/types.ts

@@ -0,0 +1,65 @@
+import type { WindowConfig } from "../config/index.ts";
+import type { EventProc, Router } from "../rpc.ts";
+
+/** Which native backend a window's `material` resolved to. */
+export type WindowMaterialInfo = {
+  /** The material that was requested. */
+  requested: string;
+  /** What actually rendered: real Liquid Glass, a vibrancy material, or none. */
+  backend: "liquidGlass" | "vibrancy" | "none";
+  /** Whether Apple's Liquid Glass (NSGlassEffectView, macOS 26+) is available. */
+  liquidGlassAvailable: boolean;
+};
+
+export type WindowEvents = {
+  focus: void;
+  blur: void;
+  moved: void;
+  resized: void;
+  closed: void;
+  /** Fired when a native background material is applied (see setMaterial). */
+  material: WindowMaterialInfo;
+};
+
+export type AppEvents = {
+  ready: void;
+  "window-all-closed": void;
+  /** A deep-link URL (a registered `urlSchemes` scheme) opened the app, or
+   *  arrived while it was running. Includes the launch URL. */
+  "open-url": string;
+};
+
+/** A window's frame in screen points (bottom-left origin, like AppKit). */
+export interface WindowFrame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface WindowOpenOptions extends WindowConfig {
+  name?: string;
+}
+
+/** Typed push emitters derived from a router's `event` procedures.
+ * Type-level `any` keeps the caller's router payload inference intact. */
+export type BroadcastEmitters<R extends Router<any>> = R extends Router<infer T>
+  ? {
+      [K in keyof T as T[K] extends EventProc<any> ? K : never]: T[K] extends EventProc<infer P>
+        ? { broadcast(payload: P): void }
+        : never;
+    }
+  : never;
+
+/** Type-level `any` preserves the caller's concrete router shape. */
+export interface ServeHandle<R extends Router<any>> {
+  readonly rpc: BroadcastEmitters<R>;
+}
+
+/** macOS Dock-icon controls (no-ops off macOS). */
+export interface Dock {
+  /** Hide the Dock icon and menu-bar presence (agent/accessory app). */
+  hide(): void;
+  /** Restore the Dock icon and menu bar. */
+  show(): void;
+}

package/src/client.ts

@@ -7,18 +7,18 @@
 
 import type { EventProc, MutationProc, QueryProc, Router } from "./rpc.ts";
 
-export type ClientFor<R extends Router<any>> =
-  R extends Router<infer T>
-    ? {
-        [K in keyof T]: T[K] extends QueryProc<infer I, infer O>
+// Type-level `any` preserves the app router's concrete procedure inference for UI callers.
+export type ClientFor<R extends Router<any>> = R extends Router<infer T>
+  ? {
+      [K in keyof T]: T[K] extends QueryProc<infer I, infer O>
+        ? (input: I) => Promise<Awaited<O>>
+        : T[K] extends MutationProc<infer I, infer O>
           ? (input: I) => Promise<Awaited<O>>
-          : T[K] extends MutationProc<infer I, infer O>
-            ? (input: I) => Promise<Awaited<O>>
-            : T[K] extends EventProc<infer P>
-              ? { on(listener: (payload: P) => void): () => void }
-              : never;
-      }
-    : never;
+          : T[K] extends EventProc<infer P>
+            ? { on(listener: (payload: P) => void): () => void }
+            : never;
+    }
+  : never;
 
 interface MirinTransport {
   call(method: string, input: unknown): Promise<unknown>;
@@ -49,6 +49,7 @@ function transport(): MirinTransport {
  * Create the typed client for the app's router. Pass the Router *type* only —
  * never import the router value (and its handlers) into UI code.
  */
+// Type-level `any` keeps `client<AppRouter>()` inference intact.
 export function client<R extends Router<any>>(): ClientFor<R> {
   const eventCache = new Map<string, { on(l: (p: unknown) => void): () => void }>();
 

package/src/config/index.ts

@@ -0,0 +1 @@
+export * from "./manifest.ts";

package/src/{config.ts → config/manifest.ts}

@@ -97,8 +97,10 @@ export interface MirinConfig {
    * `.ico` for the exe and window.
    */
   icon?: string;
+  /** CEF runtime packaging options. Omit to bundle every locale. */
+  cef?: CefConfig;
   /**
-   * Auto-update configuration (macOS). Omit to disable updates entirely.
+   * Cross-platform auto-update configuration. Omit to disable updates entirely.
    * `baseUrl` is a flat directory of release artifacts (a GitHub Releases
    * `…/releases/latest/download` URL, an S3/R2 bucket, or any static host).
    * `channel` (default "stable") is baked into artifact filenames + the app's
@@ -140,7 +142,8 @@ export interface MirinConfig {
   /**
    * External binaries bundled into the `.app` and spawned at runtime with
    * `app.sidecar(name)`. Maps a logical name to a path (relative to the project
-   * root) or a {@link SidecarSpec}. Each binary is copied into
+   * root) or a {@link SidecarSpec}. Names must be filename-safe (`A-Z`, `a-z`,
+   * `0-9`, `.`, `_`, `-`) and paths must stay under the project root. Each binary is copied into
    * `Contents/Resources/sidecars/<name>`, codesigned (hardened runtime), and —
    * when notary credentials are set — notarized with the rest of the app.
    *
@@ -151,7 +154,8 @@ export interface MirinConfig {
   sidecars?: Record<string, string | SidecarSpec>;
   /**
    * Extra Bun Worker entry files (relative to the project root) bundled next to
-   * the main worker. Resolve one at runtime with `resolveWorker(name)` and pass
+   * the main worker. Names follow the same filename-safe rule as sidecars, and
+   * paths must stay under the project root. Resolve one at runtime with `resolveWorker(name)` and pass
    * it to `new Worker(...)` from `node:worker_threads`. These run off the main
    * thread for CPU/IO offload and must NOT call window/native APIs — only the
    * app worker owns AppKit/CEF (see docs/architecture.md).
@@ -307,6 +311,16 @@ export interface ReleaseConfig {
   baseUrl: string;
   /** Update channel; baked into artifact names + support dir. Default "stable". */
   channel?: string;
+  /** Optional markdown release notes embedded in the update manifest. */
+  notes?: string;
+}
+
+export interface CefConfig {
+  /**
+   * Locale packs bundled with production apps, as BCP 47 tags such as
+   * `en-US`, `es-419`, or `pt-BR`. Omit to bundle every CEF locale.
+   */
+  locales?: string[];
 }
 
 /** Identity function for typing/intellisense. `const` generic preserves window names as literal keys. */

package/src/dialog.ts

@@ -3,7 +3,7 @@
  * back in a `dialog.result` event, which resolves the matching promise.
  */
 
-import { runtime, onNativeEvent } from "./runtime.ts";
+import { onNativeEvent, runtime } from "./runtime.ts";
 
 export interface OpenDialogOptions {
   message?: string;

package/src/host.ts

@@ -14,9 +14,9 @@
  *     their `app://` URLs served from Contents/Resources.
  */
 
-import { Worker } from "node:worker_threads";
-import { dirname, join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Worker } from "node:worker_threads";
 import { Core } from "./native.ts";
 
 // Bundle layout differs by platform: macOS `.app` puts the host in
@@ -45,15 +45,11 @@ if (!existsSync(corePath) || !existsSync(workerPath)) {
   process.exit(1);
 }
 
-const manifest = JSON.parse(
-  process.env.MIRIN_MANIFEST_JSON ?? readManifestFromBundle() ?? "{}",
-);
+const manifest = JSON.parse(process.env.MIRIN_MANIFEST_JSON ?? readManifestFromBundle() ?? "{}");
 
 const coreConfig = JSON.parse(
   process.env.MIRIN_CONFIG_JSON ??
-    JSON.stringify(
-      process.env.MIRIN_DEV_URL ? { dev: true } : { resources_path: resourcesDir },
-    ),
+    JSON.stringify(process.env.MIRIN_DEV_URL ? { dev: true } : { resources_path: resourcesDir }),
 );
 // Opt out of single-instance (the core default) when the app allows multiple.
 if (manifest.singleInstance === false) coreConfig.single_instance = false;

package/src/index.ts

@@ -7,7 +7,7 @@
  * `globalShortcut`, and `logger` features (docs/api-design.md).
  */
 
-import { app, wireAppEvents } from "./app.ts";
+import { app, wireAppEvents } from "./app/index.ts";
 import { boot } from "./runtime.ts";
 
 // Side-effect imports: each feature subscribes its native-event handlers.
@@ -16,48 +16,50 @@ import "./tray.ts";
 import "./dialog.ts";
 import "./shortcut.ts";
 
-export { app } from "./app.ts";
-export { menu } from "./menu.ts";
-export { Tray } from "./tray.ts";
-export { dialog } from "./dialog.ts";
-export { clipboard } from "./clipboard.ts";
-export { globalShortcut } from "./shortcut.ts";
-export { logger, setLogLevel, getLogLevel, Logger } from "./logger.ts";
-export { updater, Updater } from "./updater.ts";
-export { sidecar } from "./sidecar.ts";
-export { NotAttachedError, resolveWorker } from "./runtime.ts";
-
 export type {
+  AppEvents,
+  BroadcastEmitters,
+  Dock,
+  ServeHandle,
   WindowEvents,
-  WindowMaterialInfo,
   WindowFrame,
-  AppEvents,
   WindowHandle,
+  WindowMaterialInfo,
   WindowOpenOptions,
-  ServeHandle,
-  BroadcastEmitters,
-  Dock,
-} from "./app.ts";
-export type { MenuItemTemplate, MenuRole } from "./menu.ts";
-export type { LogLevel } from "./logger.ts";
-export type { UpdaterStatus, UpdateInfo, UpdateProgress, UpdaterEvents } from "./updater.ts";
-export type { SidecarOptions, SidecarProcess } from "./sidecar.ts";
-export type { TrayOptions } from "./tray.ts";
-export type { OpenDialogOptions, SaveDialogOptions, MessageDialogOptions } from "./dialog.ts";
+} from "./app/index.ts";
+export { app } from "./app/index.ts";
+export { clipboard } from "./clipboard.ts";
 export type {
-  MirinConfig,
-  WindowConfig,
-  WindowMaterial,
-  WindowMaterialOptions,
-  ReleaseConfig,
+  CefConfig,
   DmgConfig,
-  NsisConfig,
   InnoConfig,
   LinuxConfig,
   LinuxPackageFormat,
-  SidecarSpec,
+  MirinConfig,
+  NsisConfig,
+  ReleaseConfig,
   SidecarEntitlement,
-} from "./config.ts";
+  SidecarSpec,
+  WindowConfig,
+  WindowMaterial,
+  WindowMaterialOptions,
+} from "./config/index.ts";
+export type { MessageDialogOptions, OpenDialogOptions, SaveDialogOptions } from "./dialog.ts";
+export { dialog } from "./dialog.ts";
+export type { LogLevel } from "./logger.ts";
+export { getLogLevel, Logger, logger, setLogLevel } from "./logger.ts";
+export type { MenuItemTemplate, MenuRole } from "./menu.ts";
+export { menu } from "./menu.ts";
+export type { NotificationOptions } from "./notification.ts";
+export { notification } from "./notification.ts";
+export { NotAttachedError, resolveWorker } from "./runtime.ts";
+export { globalShortcut } from "./shortcut.ts";
+export type { SidecarOptions, SidecarProcess } from "./sidecar.ts";
+export { resolveSidecar, sidecar } from "./sidecar.ts";
+export type { TrayOptions } from "./tray.ts";
+export { Tray } from "./tray.ts";
+export type { UpdateInfo, UpdateProgress, UpdaterEvents, UpdaterStatus } from "./updater/index.ts";
+export { Updater, updater } from "./updater/index.ts";
 
 wireAppEvents();
 boot();

package/src/logger.ts

@@ -53,12 +53,16 @@ export function getLogLevel(): LogLevel {
 }
 
 export class Logger {
+  readonly #scope?: string;
+
   /** @param scope optional dotted scope shown as `[mirin:scope]`. */
-  constructor(private readonly scope?: string) {}
+  constructor(scope?: string) {
+    this.#scope = scope;
+  }
 
   /** Derive a scoped child logger (e.g. `logger.child("db")`). */
   child(scope: string): Logger {
-    return new Logger(this.scope ? `${this.scope}:${scope}` : scope);
+    return new Logger(this.#scope ? `${this.#scope}:${scope}` : scope);
   }
 
   /** Set the global level (same as the exported `setLogLevel`). */
@@ -85,7 +89,7 @@ export class Logger {
 
   #emit(level: Exclude<LogLevel, "silent">, args: unknown[]): void {
     if (ORDER[level] < ORDER[currentLevel]) return;
-    const name = this.scope ? `[mirin:${this.scope}]` : "[mirin]";
+    const name = this.#scope ? `[mirin:${this.#scope}]` : "[mirin]";
     const prefix = useColor ? `${COLOR.dim}${name}${COLOR.reset}` : name;
     const tag = useColor ? `${COLOR[level]}${level}${COLOR.reset}` : level;
     const sink = level === "warn" || level === "error" ? console.error : console.log;

package/src/menu.ts

@@ -4,12 +4,25 @@
  * carrying that id. `role` items map to AppKit's standard actions.
  */
 
-import { runtime, onNativeEvent } from "./runtime.ts";
+import { onNativeEvent, runtime } from "./runtime.ts";
 
 export type MenuRole =
-  | "quit" | "close" | "minimize" | "zoom" | "front" | "togglefullscreen"
-  | "hide" | "hideothers" | "unhide"
-  | "undo" | "redo" | "cut" | "copy" | "paste" | "selectall" | "delete";
+  | "quit"
+  | "close"
+  | "minimize"
+  | "zoom"
+  | "front"
+  | "togglefullscreen"
+  | "hide"
+  | "hideothers"
+  | "unhide"
+  | "undo"
+  | "redo"
+  | "cut"
+  | "copy"
+  | "paste"
+  | "selectall"
+  | "delete";
 
 export interface MenuItemTemplate {
   label?: string;

package/src/native.ts

@@ -6,7 +6,7 @@
  * process, so the Rust statics behind these symbols are shared.
  */
 
-import { dlopen, FFIType, ptr, CString, type Pointer } from "bun:ffi";
+import { CString, dlopen, FFIType, type Pointer, ptr } from "bun:ffi";
 
 function nullTerminated(s: string): Uint8Array {
   return new TextEncoder().encode(s + "\0");
@@ -23,8 +23,14 @@ const symbols = {
   mirin_window_set_title: { args: [FFIType.u32, FFIType.ptr], returns: FFIType.void },
   mirin_window_control: { args: [FFIType.u32, FFIType.ptr], returns: FFIType.void },
   mirin_window_set_material: { args: [FFIType.u32, FFIType.ptr], returns: FFIType.void },
-  mirin_window_set_position: { args: [FFIType.u32, FFIType.f64, FFIType.f64], returns: FFIType.void },
-  mirin_window_maybe_start_drag: { args: [FFIType.u32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.void },
+  mirin_window_set_position: {
+    args: [FFIType.u32, FFIType.f64, FFIType.f64],
+    returns: FFIType.void,
+  },
+  mirin_window_maybe_start_drag: {
+    args: [FFIType.u32, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32],
+    returns: FFIType.void,
+  },
   mirin_app_quit: { args: [], returns: FFIType.void },
   mirin_app_set_dock_visible: { args: [FFIType.i32], returns: FFIType.void },
   mirin_set_app_menu: { args: [FFIType.ptr], returns: FFIType.void },
@@ -36,6 +42,7 @@ const symbols = {
   mirin_clipboard_read_text: { args: [], returns: FFIType.ptr },
   mirin_clipboard_write_text: { args: [FFIType.ptr], returns: FFIType.void },
   mirin_dialog_show: { args: [FFIType.ptr], returns: FFIType.void },
+  mirin_notification_show: { args: [FFIType.ptr], returns: FFIType.i32 },
 } as const;
 
 export type EventListener = (event: string) => void;
@@ -168,4 +175,9 @@ export class Core {
     const buf = nullTerminated(specJson);
     this.#lib.symbols.mirin_dialog_show(ptr(buf));
   }
+
+  notificationShow(specJson: string): boolean {
+    const buf = nullTerminated(specJson);
+    return this.#lib.symbols.mirin_notification_show(ptr(buf)) === 1;
+  }
 }

package/src/notification.ts

@@ -0,0 +1,19 @@
+import { runtime } from "./runtime.ts";
+
+export interface NotificationOptions {
+  title: string;
+  body?: string;
+}
+
+export const notification = {
+  /** Ask the operating system to display a desktop notification. */
+  show(options: NotificationOptions): boolean {
+    const title = options.title.trim();
+    if (!title || title.length > 128) return false;
+    if (options.body && options.body.length > 512) return false;
+
+    return runtime().core.notificationShow(
+      JSON.stringify({ ...options, title, appName: runtime().id }),
+    );
+  },
+};