mirinjs 0.0.1-alpha.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "mirinjs",
+  "version": "0.0.1-alpha.0",
+  "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/Netko-Labs/mirin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Netko-Labs/mirin.git",
+    "directory": "packages/mirin"
+  },
+  "bugs": "https://github.com/Netko-Labs/mirin/issues",
+  "keywords": [
+    "bun",
+    "desktop",
+    "cef",
+    "chromium",
+    "electron-alternative",
+    "macos",
+    "rpc",
+    "webview"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts",
+    "./rpc": "./src/rpc.ts",
+    "./client": "./src/client.ts",
+    "./host": "./src/host.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/app.ts

@@ -0,0 +1,300 @@
+/**
+ * The `app` singleton, window handles, and typed event emitters
+ * (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";
+
+/** 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;
+};
+
+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;
+}
+
+/** A live, typed handle to an open window. */
+export class WindowHandle extends Emitter<WindowEvents> {
+  constructor(
+    readonly id: number,
+    readonly name: string | undefined,
+  ) {
+    super();
+  }
+
+  async setTitle(title: string): Promise<void> {
+    runtime().core.windowSetTitle(this.id, title);
+  }
+
+  async loadUrl(url: string): Promise<void> {
+    runtime().core.windowLoadUrl(this.id, url);
+  }
+
+  async close(): Promise<void> {
+    runtime().core.windowClose(this.id);
+  }
+
+  async minimize(): Promise<void> {
+    this.#control("minimize");
+  }
+  async maximize(): Promise<void> {
+    this.#control("maximize");
+  }
+  async restore(): Promise<void> {
+    this.#control("restore");
+  }
+  async toggleFullscreen(): Promise<void> {
+    this.#control("fullscreen");
+  }
+  async focus(): Promise<void> {
+    this.#control("focus");
+  }
+  async show(): Promise<void> {
+    this.#control("show");
+  }
+  async hide(): Promise<void> {
+    this.#control("hide");
+  }
+  async center(): Promise<void> {
+    this.#control("center");
+  }
+  async setAlwaysOnTop(on: boolean): Promise<void> {
+    this.#control(on ? "alwaysOnTop:on" : "alwaysOnTop:off");
+  }
+
+  /**
+   * Change the window's native background material live (macOS, transparent
+   * windows only). Pass `null` to remove it. See {@link WindowMaterial}.
+   */
+  async setMaterial(material: WindowMaterial | WindowMaterialOptions | null): Promise<void> {
+    runtime().core.windowSetMaterial(this.id, JSON.stringify(normalizeMaterial(material)));
+  }
+
+  #control(verb: string): void {
+    runtime().core.windowControl(this.id, verb);
+  }
+
+  /** Typed push to this window's webview (used by router event procedures). */
+  get rpc(): RpcEmitters {
+    return rpcEmitters((method, payload) => runtime().rpc.emitTo(this.id, method, payload));
+  }
+
+  /** @internal */
+  _emit<K extends keyof WindowEvents>(type: K, payload: WindowEvents[K]): void {
+    this.emit(type, payload);
+  }
+}
+
+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, {
+    get(_t, method: string) {
+      return {
+        emit: (payload: unknown) => send(method, payload),
+        broadcast: (payload: unknown) => send(method, payload),
+      };
+    },
+  });
+}
+
+/** 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>();
+
+  get(name: string): WindowHandle {
+    const win = this.#byName.get(name);
+    if (!win) throw new Error(`no window named "${name}" is open`);
+    return win;
+  }
+
+  all(): WindowHandle[] {
+    return [...this.#byId.values()];
+  }
+
+  /** Look up a window by its numeric id (e.g. an RPC ctx.webview). */
+  byId(id: number): WindowHandle | undefined {
+    return this.#byId.get(id);
+  }
+
+  async open(options: WindowOpenOptions | string): Promise<WindowHandle> {
+    const opts = typeof options === "string" ? manifestWindow(options) : options;
+    const id = runtime().core.windowCreate(
+      JSON.stringify({
+        ...opts,
+        url: resolveUrl(opts.url),
+        material: normalizeMaterial(opts.material),
+      }),
+    );
+    const handle = new WindowHandle(id, opts.name);
+    this.#register(handle);
+    return handle;
+  }
+
+  #register(handle: WindowHandle): void {
+    this.#byId.set(handle.id, handle);
+    if (handle.name) this.#byName.set(handle.name, handle);
+  }
+
+  /** @internal */
+  _byId(id: number): WindowHandle | undefined {
+    return this.#byId.get(id);
+  }
+  /** @internal */
+  _remove(id: number): void {
+    const handle = this.#byId.get(id);
+    if (handle) {
+      this.#byId.delete(id);
+      if (handle.name) this.#byName.delete(handle.name);
+    }
+  }
+}
+
+function manifestWindow(name: string): WindowOpenOptions {
+  const found = runtime().manifestWindows.find((w) => w.name === name);
+  if (!found) throw new Error(`no window "${name}" declared in the manifest`);
+  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;
+}
+
+class MirinApp extends Emitter<AppEvents> {
+  readonly windows = new Windows();
+
+  serve<R extends Router<any>>(router: R): ServeHandle<R> {
+    runtime().rpc.setRouter(router);
+    return { rpc: this.rpc as BroadcastEmitters<R> };
+  }
+
+  get rpc(): RpcEmitters {
+    return rpcEmitters((method, payload) => runtime().rpc.broadcast(method, payload));
+  }
+
+  quit(): void {
+    runtime().core.quit();
+  }
+
+  /** @internal */
+  _emit<K extends keyof AppEvents>(type: K, payload: AppEvents[K]): void {
+    this.emit(type, payload);
+  }
+}
+
+export const app = new MirinApp();
+
+// ---- wire native events to the app/window emitters ----
+
+const WINDOW_EVENTS = ["focus", "blur", "moved", "resized"] as const;
+
+export function wireAppEvents(): void {
+  onNativeEvent("core.ready", () => {
+    for (const cfg of runtime().manifestWindows) {
+      if (cfg.open === "manual") continue;
+      void app.windows.open(cfg as WindowOpenOptions);
+    }
+    app._emit("ready", undefined);
+  });
+
+  onNativeEvent("window.closed", (event: NativeEvent) => {
+    const id = event.id as number | undefined;
+    if (id == null) return;
+    app.windows._byId(id)?._emit("closed", undefined);
+    app.windows._remove(id);
+  });
+
+  onNativeEvent("window.all-closed", () => app._emit("window-all-closed", undefined));
+
+  onNativeEvent("window.material", (event: NativeEvent) => {
+    const id = event.id as number | undefined;
+    if (id == null) return;
+    app.windows._byId(id)?._emit("material", {
+      requested: String(event.requested ?? ""),
+      backend: (event.backend as WindowMaterialInfo["backend"]) ?? "none",
+      liquidGlassAvailable: Boolean(event.liquidGlassAvailable),
+    });
+  });
+
+  for (const kind of WINDOW_EVENTS) {
+    onNativeEvent(`window.${kind}`, (event: NativeEvent) => {
+      const id = event.id as number | undefined;
+      if (id != null) app.windows._byId(id)?._emit(kind, undefined);
+    });
+  }
+}

package/src/client.ts

@@ -0,0 +1,67 @@
+/**
+ * mirin/client — the browser-side RPC client (docs/api-design.md §3).
+ *
+ * Runs inside webviews. Talks to the `window.mirin` transport installed by the
+ * preload bootstrap (token-authenticated WebSocket to the Bun Worker — M3).
+ */
+
+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>
+          ? (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;
+
+interface MirinTransport {
+  call(method: string, input: unknown): Promise<unknown>;
+  onEvent(method: string, listener: (payload: unknown) => void): () => void;
+}
+
+declare global {
+  interface Window {
+    /** Installed by the mirin preload bootstrap before page scripts run. */
+    mirin?: MirinTransport;
+  }
+}
+
+function transport(): MirinTransport {
+  const t = window.mirin;
+  if (!t) {
+    throw new Error(
+      "window.mirin is not available — this page is not running inside a mirin webview " +
+        "(or the preload bootstrap failed to authenticate).",
+    );
+  }
+  return t;
+}
+
+/**
+ * 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.
+ */
+export function client<R extends Router<any>>(): ClientFor<R> {
+  const eventCache = new Map<string, { on(l: (p: unknown) => void): () => void }>();
+
+  return new Proxy({} as ClientFor<R>, {
+    get(_target, prop) {
+      if (typeof prop !== "string") return undefined;
+      // Procedure kind is unknowable from the type-erased proxy; expose a callable
+      // that is *also* event-shaped. The router type makes misuse a compile error.
+      const callable = (input: unknown) => transport().call(prop, input);
+      let ev = eventCache.get(prop);
+      if (!ev) {
+        ev = { on: (listener) => transport().onEvent(prop, listener) };
+        eventCache.set(prop, ev);
+      }
+      return Object.assign(callable, ev);
+    },
+  });
+}

package/src/clipboard.ts

@@ -0,0 +1,12 @@
+/** Clipboard text access (synchronous). */
+
+import { runtime } from "./runtime.ts";
+
+export const clipboard = {
+  readText(): string {
+    return runtime().core.clipboardReadText();
+  },
+  writeText(text: string): void {
+    runtime().core.clipboardWriteText(text);
+  },
+};

package/src/config.ts

@@ -0,0 +1,79 @@
+/**
+ * mirin/config — the pure-data manifest (docs/api-design.md §1).
+ *
+ * `mirin.config.ts` must stay serializable: no functions, no side effects.
+ * The CLI and the host bootstrap both read it without running app code.
+ */
+
+/**
+ * A native macOS background material rendered behind the web UI. macOS only.
+ *
+ * - `"liquidGlass"` — Apple's Liquid Glass (NSGlassEffectView, macOS 26+);
+ *   automatically falls back to a frosted vibrancy material on older systems.
+ * - the rest map to NSVisualEffectView vibrancy materials.
+ */
+export type WindowMaterial =
+  | "liquidGlass"
+  | "sidebar"
+  | "menu"
+  | "popover"
+  | "hud"
+  | "fullScreenUI"
+  | "underWindowBackground"
+  | "contentBackground"
+  | "windowBackground"
+  | "titlebar"
+  | "selection"
+  | "headerView"
+  | "sheet"
+  | "toolTip";
+
+export interface WindowMaterialOptions {
+  type: WindowMaterial;
+  /** Liquid Glass tint as a CSS hex color (e.g. "#3b82f6" or "#3b82f680"). */
+  tint?: string;
+  /** Corner radius in points (defaults to the panel radius, 14). */
+  cornerRadius?: number;
+}
+
+export interface WindowConfig {
+  /** Page to load: `app://` (bundled assets) or http(s). */
+  url: string;
+  title?: string;
+  width?: number;
+  height?: number;
+  /** "ready" (default) shows on first paint to avoid a white flash. */
+  show?: "ready" | "immediately";
+  /** "auto" (default) opens at launch; "manual" windows are templates for app.windows.open(name). */
+  open?: "auto" | "manual";
+  /** Custom title bar: hide it (content fills) or inset the traffic lights. */
+  titleBarStyle?: "hidden" | "hiddenInset";
+  /** Non-opaque window (for transparent/blurred UIs). */
+  transparent?: boolean;
+  /**
+   * Native background material behind the web UI (macOS). Implies `transparent`,
+   * so the page should use a translucent or clear background. Pass a material
+   * name or an object with `tint`/`cornerRadius`.
+   */
+  material?: WindowMaterial | WindowMaterialOptions;
+  /** Float above normal windows. */
+  alwaysOnTop?: boolean;
+  /** Drag the window from anywhere in its background. */
+  movableByBackground?: boolean;
+  /** Create the window hidden (e.g. a Spotlight panel shown on a hotkey). */
+  visible?: boolean;
+}
+
+export interface MirinConfig {
+  /** Reverse-DNS app id, e.g. "dev.peje.hello". */
+  id: string;
+  name: string;
+  /** Main-process entry, relative to the project root (runs in the Bun Worker). */
+  main: string;
+  windows: Record<string, WindowConfig>;
+}
+
+/** Identity function for typing/intellisense. `const` generic preserves window names as literal keys. */
+export function defineConfig<const T extends MirinConfig>(config: T): T {
+  return config;
+}

package/src/dialog.ts

@@ -0,0 +1,62 @@
+/**
+ * Native dialogs. Async: each call gets a `requestId` the native side echoes
+ * back in a `dialog.result` event, which resolves the matching promise.
+ */
+
+import { runtime, onNativeEvent } from "./runtime.ts";
+
+export interface OpenDialogOptions {
+  message?: string;
+  /** Allow selecting multiple items. */
+  multiple?: boolean;
+  /** Choose directories instead of files. */
+  directories?: boolean;
+}
+
+export interface SaveDialogOptions {
+  message?: string;
+  /** Pre-filled file name. */
+  defaultName?: string;
+}
+
+export interface MessageDialogOptions {
+  message: string;
+  detail?: string;
+  /** Button titles, left to right; the result is the clicked index. */
+  buttons?: string[];
+}
+
+const pending = new Map<number, (value: unknown) => void>();
+let nextRequestId = 1;
+
+onNativeEvent("dialog.result", (event) => {
+  const requestId = event.requestId as number;
+  const resolve = pending.get(requestId);
+  if (resolve) {
+    pending.delete(requestId);
+    resolve(event.value);
+  }
+});
+
+function show<T>(spec: Record<string, unknown>): Promise<T> {
+  const requestId = nextRequestId++;
+  return new Promise<T>((resolve) => {
+    pending.set(requestId, resolve as (value: unknown) => void);
+    runtime().core.dialogShow(JSON.stringify({ ...spec, requestId }));
+  });
+}
+
+export const dialog = {
+  /** Open file/directory picker; resolves to the chosen paths, or null if cancelled. */
+  openFile(options: OpenDialogOptions = {}): Promise<string[] | null> {
+    return show({ kind: "openFile", ...options });
+  },
+  /** Save panel; resolves to the chosen path, or null if cancelled. */
+  saveFile(options: SaveDialogOptions = {}): Promise<string | null> {
+    return show({ kind: "saveFile", ...options });
+  },
+  /** Alert with buttons; resolves to `{ button }` (0-based clicked index). */
+  message(options: MessageDialogOptions): Promise<{ button: number }> {
+    return show({ kind: "message", ...options });
+  },
+};

package/src/host.ts

@@ -0,0 +1,57 @@
+/**
+ * Host bootstrap — the process main-thread entry (docs/architecture.md §1).
+ *
+ * Compiled with `bun build --compile` into the bundle's `Contents/MacOS/<exe>`
+ * so CEF's library loader can resolve the framework relative to it. It spawns
+ * the user's app as a Bun Worker, then hands the main thread to CEF via
+ * `mirin_run` (which blocks until quit).
+ *
+ * Two modes:
+ *   - Dev (`mirin dev`): configured via env (MIRIN_CORE / MIRIN_WORKER /
+ *     MIRIN_MANIFEST_JSON / MIRIN_DEV_URL); windows load the Vite dev server.
+ *   - Production (built .app): no env — paths and the manifest are resolved
+ *     from inside the bundle, relative to this executable, and windows load
+ *     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 { Core } from "./native.ts";
+
+const exeDir = dirname(process.execPath); // Contents/MacOS
+const resourcesDir = join(exeDir, "..", "Resources");
+
+const corePath = process.env.MIRIN_CORE ?? join(exeDir, "libmirin_core.dylib");
+const workerPath = process.env.MIRIN_WORKER ?? join(resourcesDir, "worker.js");
+
+if (!existsSync(corePath) || !existsSync(workerPath)) {
+  console.error(`[mirin host] missing core (${corePath}) or worker (${workerPath})`);
+  process.exit(1);
+}
+
+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 ? {} : { resources_path: resourcesDir }),
+);
+
+const worker = new Worker(workerPath, {
+  workerData: { corePath, manifest, devUrl: process.env.MIRIN_DEV_URL },
+});
+worker.on("error", (err) => console.error("[mirin worker]", err));
+
+// Hand the main thread to CEF. Blocks in the message loop until the app quits.
+const core = new Core(corePath);
+const exitCode = core.run(JSON.stringify(coreConfig));
+
+void worker.terminate();
+process.exit(exitCode);
+
+function readManifestFromBundle(): string | undefined {
+  const path = join(resourcesDir, "mirin.manifest.json");
+  return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * mirin — the main-process API (runs in the Bun Worker).
+ *
+ * Importing this module boots the runtime (loads libmirin_core, starts the RPC
+ * server, begins draining native events) and exposes the developer-facing API:
+ * the `app` singleton plus the `menu`, `Tray`, `dialog`, `clipboard`, and
+ * `globalShortcut` features (docs/api-design.md).
+ */
+
+import { app, wireAppEvents } from "./app.ts";
+import { boot } from "./runtime.ts";
+
+// Side-effect imports: each feature subscribes its native-event handlers.
+import "./menu.ts";
+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 { NotAttachedError } from "./runtime.ts";
+
+export type {
+  WindowEvents,
+  WindowMaterialInfo,
+  AppEvents,
+  WindowHandle,
+  WindowOpenOptions,
+  ServeHandle,
+  BroadcastEmitters,
+} from "./app.ts";
+export type { MenuItemTemplate, MenuRole } from "./menu.ts";
+export type { TrayOptions } from "./tray.ts";
+export type { OpenDialogOptions, SaveDialogOptions, MessageDialogOptions } from "./dialog.ts";
+export type {
+  MirinConfig,
+  WindowConfig,
+  WindowMaterial,
+  WindowMaterialOptions,
+} from "./config.ts";
+
+wireAppEvents();
+boot();
+
+// Re-export so `import mirin from "mirin"` style also works if desired.
+export default app;

package/src/menu.ts

@@ -0,0 +1,74 @@
+/**
+ * Native menus. A template item's `click` handler is kept in a registry keyed
+ * by an auto-assigned id; the native side reports clicks as `menu.click` events
+ * carrying that id. `role` items map to AppKit's standard actions.
+ */
+
+import { runtime, onNativeEvent } from "./runtime.ts";
+
+export type MenuRole =
+  | "quit" | "close" | "minimize" | "zoom" | "front" | "togglefullscreen"
+  | "hide" | "hideothers" | "unhide"
+  | "undo" | "redo" | "cut" | "copy" | "paste" | "selectall" | "delete";
+
+export interface MenuItemTemplate {
+  label?: string;
+  role?: MenuRole;
+  type?: "normal" | "separator" | "submenu";
+  /** e.g. "Cmd+N", "Cmd+Shift+P". */
+  accelerator?: string;
+  enabled?: boolean;
+  checked?: boolean;
+  click?: () => void;
+  submenu?: MenuItemTemplate[];
+}
+
+interface NativeMenuItem {
+  id?: number;
+  label?: string;
+  role?: string;
+  type?: string;
+  accelerator?: string;
+  enabled?: boolean;
+  checked?: boolean;
+  submenu?: NativeMenuItem[];
+}
+
+let nextId = 1;
+const clickHandlers = new Map<number, () => void>();
+
+onNativeEvent("menu.click", (event) => {
+  clickHandlers.get(event.id as number)?.();
+});
+
+/** Convert a template to the native JSON shape, registering click handlers. */
+export function buildNativeMenu(items: MenuItemTemplate[]): NativeMenuItem[] {
+  return items.map((item) => {
+    const native: NativeMenuItem = {
+      label: item.label,
+      role: item.role,
+      type: item.type,
+      accelerator: item.accelerator,
+      enabled: item.enabled,
+      checked: item.checked,
+    };
+    if (item.click) {
+      const id = nextId++;
+      clickHandlers.set(id, item.click);
+      native.id = id;
+    }
+    if (item.submenu) native.submenu = buildNativeMenu(item.submenu);
+    return native;
+  });
+}
+
+export const menu = {
+  /** Replace the application menu bar. */
+  setApplicationMenu(template: MenuItemTemplate[]): void {
+    runtime().core.setAppMenu(JSON.stringify(buildNativeMenu(template)));
+  },
+  /** Show a context menu at the cursor. */
+  popup(template: MenuItemTemplate[]): void {
+    runtime().core.popupMenu(JSON.stringify(buildNativeMenu(template)));
+  },
+};

package/src/native.ts

@@ -0,0 +1,156 @@
+/**
+ * FFI bindings to libmirin_core (docs/architecture.md §3).
+ *
+ * Loaded in the Bun Worker (commands + event handler) and, separately, in the
+ * host's main thread (just `mirin_run`). Both dlopen the same dylib in the same
+ * process, so the Rust statics behind these symbols are shared.
+ */
+
+import { dlopen, FFIType, ptr, CString, type Pointer } from "bun:ffi";
+
+function nullTerminated(s: string): Uint8Array {
+  return new TextEncoder().encode(s + "\0");
+}
+
+const symbols = {
+  mirin_run: { args: [FFIType.ptr], returns: FFIType.i32 },
+  mirin_poll_event: { args: [], returns: FFIType.ptr },
+  mirin_set_rpc_endpoint: { args: [FFIType.u16, FFIType.ptr], returns: FFIType.void },
+  mirin_is_ready: { args: [], returns: FFIType.i32 },
+  mirin_window_create: { args: [FFIType.ptr], returns: FFIType.u32 },
+  mirin_window_close: { args: [FFIType.u32], returns: FFIType.void },
+  mirin_window_load_url: { args: [FFIType.u32, FFIType.ptr], returns: FFIType.void },
+  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_app_quit: { args: [], returns: FFIType.void },
+  mirin_set_app_menu: { args: [FFIType.ptr], returns: FFIType.void },
+  mirin_popup_menu: { args: [FFIType.ptr], returns: FFIType.void },
+  mirin_tray_create: { args: [FFIType.ptr], returns: FFIType.void },
+  mirin_tray_destroy: { args: [FFIType.u32], returns: FFIType.void },
+  mirin_shortcut_register: { args: [FFIType.u32, FFIType.ptr], returns: FFIType.i32 },
+  mirin_shortcut_unregister: { args: [FFIType.u32], returns: FFIType.void },
+  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 },
+} as const;
+
+export type EventListener = (event: string) => void;
+
+export class Core {
+  #lib: ReturnType<typeof dlopen<typeof symbols>>;
+  #polling = false;
+
+  constructor(libraryPath: string) {
+    this.#lib = dlopen(libraryPath, symbols);
+  }
+
+  /** Blocks: runs CEF's message loop until quit. Call on the process main thread. */
+  run(configJson: string): number {
+    const buf = nullTerminated(configJson);
+    return this.#lib.symbols.mirin_run(ptr(buf));
+  }
+
+  /**
+   * Drain native events on an interval and dispatch them. We poll because the
+   * host's main thread is blocked in `mirin_run`, so a bun:ffi callback invoked
+   * from it never reaches this Worker's loop (see engine::poll_event).
+   */
+  onEvent(listener: EventListener): void {
+    if (this.#polling) return;
+    this.#polling = true;
+    const drain = () => {
+      for (;;) {
+        const p = this.#lib.symbols.mirin_poll_event() as Pointer | null;
+        if (!p) break;
+        listener(new CString(p).toString());
+      }
+    };
+    setInterval(drain, 8);
+  }
+
+  setRpcEndpoint(port: number, token: string): void {
+    const buf = nullTerminated(token);
+    this.#lib.symbols.mirin_set_rpc_endpoint(port, ptr(buf));
+  }
+
+  isReady(): boolean {
+    return this.#lib.symbols.mirin_is_ready() === 1;
+  }
+
+  windowCreate(optsJson: string): number {
+    const buf = nullTerminated(optsJson);
+    return this.#lib.symbols.mirin_window_create(ptr(buf));
+  }
+
+  windowClose(id: number): void {
+    this.#lib.symbols.mirin_window_close(id);
+  }
+
+  windowLoadUrl(id: number, url: string): void {
+    const buf = nullTerminated(url);
+    this.#lib.symbols.mirin_window_load_url(id, ptr(buf));
+  }
+
+  windowSetTitle(id: number, title: string): void {
+    const buf = nullTerminated(title);
+    this.#lib.symbols.mirin_window_set_title(id, ptr(buf));
+  }
+
+  windowControl(id: number, verb: string): void {
+    const buf = nullTerminated(verb);
+    this.#lib.symbols.mirin_window_control(id, ptr(buf));
+  }
+
+  windowSetMaterial(id: number, specJson: string): void {
+    const buf = nullTerminated(specJson);
+    this.#lib.symbols.mirin_window_set_material(id, ptr(buf));
+  }
+
+  quit(): void {
+    this.#lib.symbols.mirin_app_quit();
+  }
+
+  setAppMenu(templateJson: string): void {
+    const buf = nullTerminated(templateJson);
+    this.#lib.symbols.mirin_set_app_menu(ptr(buf));
+  }
+
+  popupMenu(templateJson: string): void {
+    const buf = nullTerminated(templateJson);
+    this.#lib.symbols.mirin_popup_menu(ptr(buf));
+  }
+
+  trayCreate(specJson: string): void {
+    const buf = nullTerminated(specJson);
+    this.#lib.symbols.mirin_tray_create(ptr(buf));
+  }
+
+  trayDestroy(id: number): void {
+    this.#lib.symbols.mirin_tray_destroy(id);
+  }
+
+  shortcutRegister(id: number, accelerator: string): boolean {
+    const buf = nullTerminated(accelerator);
+    return this.#lib.symbols.mirin_shortcut_register(id, ptr(buf)) === 1;
+  }
+
+  shortcutUnregister(id: number): void {
+    this.#lib.symbols.mirin_shortcut_unregister(id);
+  }
+
+  clipboardReadText(): string {
+    const p = this.#lib.symbols.mirin_clipboard_read_text() as Pointer | null;
+    return p ? new CString(p).toString() : "";
+  }
+
+  clipboardWriteText(text: string): void {
+    const buf = nullTerminated(text);
+    this.#lib.symbols.mirin_clipboard_write_text(ptr(buf));
+  }
+
+  dialogShow(specJson: string): void {
+    const buf = nullTerminated(specJson);
+    this.#lib.symbols.mirin_dialog_show(ptr(buf));
+  }
+}

package/src/rpc-server.ts

@@ -0,0 +1,108 @@
+/**
+ * RPC data plane (docs/architecture.md §4): a token-authenticated localhost
+ * WebSocket the injected `window.mirin` connects to. Requests dispatch to the
+ * app's router here, in the Bun Worker; events push back to webviews.
+ */
+
+import type { Router, RpcContext } from "./rpc.ts";
+import type { ServerWebSocket } from "bun";
+
+interface SocketData {
+  webview: number;
+}
+
+interface RequestFrame {
+  kind: "request";
+  id: number;
+  method: string;
+  input: unknown;
+}
+
+export class RpcServer {
+  readonly token = crypto.randomUUID();
+  #server?: ReturnType<typeof Bun.serve>;
+  #router?: Router<any>;
+  #sockets = new Set<ServerWebSocket<SocketData>>();
+
+  /** Start listening on an ephemeral loopback port; returns the bound port. */
+  start(): number {
+    const token = this.token;
+    const onMessage = (ws: ServerWebSocket<SocketData>, raw: string | Buffer) =>
+      this.#onMessage(ws, raw);
+    const sockets = this.#sockets;
+
+    const server = Bun.serve<SocketData>({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch(req, server) {
+        const url = new URL(req.url);
+        if (url.searchParams.get("token") !== token) {
+          return new Response("unauthorized", { status: 401 });
+        }
+        const webview = Number(url.searchParams.get("webview") ?? "0");
+        if (server.upgrade(req, { data: { webview } })) return undefined;
+        return new Response("mirin rpc");
+      },
+      websocket: {
+        open(ws) {
+          sockets.add(ws);
+        },
+        message(ws, message) {
+          onMessage(ws, message);
+        },
+        close(ws) {
+          sockets.delete(ws);
+        },
+      },
+    });
+    this.#server = server;
+    const port = server.port;
+    if (port == null) throw new Error("mirin rpc server failed to bind a port");
+    return port;
+  }
+
+  setRouter(router: Router<any>): void {
+    this.#router = router;
+  }
+
+  /** Push an event to every connected webview. */
+  broadcast(method: string, payload: unknown): void {
+    const frame = JSON.stringify({ kind: "event", method, payload });
+    for (const ws of this.#sockets) ws.send(frame);
+  }
+
+  /** Push an event to a single webview. */
+  emitTo(webview: number, method: string, payload: unknown): void {
+    const frame = JSON.stringify({ kind: "event", method, payload });
+    for (const ws of this.#sockets) {
+      if (ws.data.webview === webview) ws.send(frame);
+    }
+  }
+
+  async #onMessage(ws: ServerWebSocket<SocketData>, raw: string | Buffer): Promise<void> {
+    let frame: RequestFrame;
+    try {
+      frame = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+    } catch {
+      return;
+    }
+    if (frame.kind !== "request") return;
+
+    const reply = (ok: boolean, body: { result?: unknown; error?: string }) =>
+      ws.send(JSON.stringify({ kind: "response", id: frame.id, ok, ...body }));
+
+    const proc = this.#router?.routes[frame.method];
+    if (!proc || (proc.type !== "query" && proc.type !== "mutation")) {
+      reply(false, { error: `no such procedure: ${frame.method}` });
+      return;
+    }
+
+    const ctx: RpcContext = { webview: ws.data.webview };
+    try {
+      const result = await proc.handler(frame.input, ctx);
+      reply(true, { result });
+    } catch (err) {
+      reply(false, { error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+}

package/src/rpc.ts

@@ -0,0 +1,63 @@
+/**
+ * mirin/rpc — schema-derived typed RPC (docs/api-design.md §3).
+ *
+ * Imported by BOTH the main process (handlers run here, in the Bun Worker)
+ * and UI code (type-only, via `client<Router>()` from mirin/client).
+ * The router is global; handlers learn their caller from `ctx`.
+ */
+
+export interface RpcContext {
+  /** Name of the calling window, if it was opened with one. */
+  window?: string;
+  /** Numeric id of the calling webview. */
+  webview: number;
+}
+
+export type Handler<I, O> = (input: I, ctx: RpcContext) => O | Promise<O>;
+
+export interface QueryProc<I, O> {
+  readonly type: "query";
+  readonly handler: Handler<I, O>;
+}
+
+export interface MutationProc<I, O> {
+  readonly type: "mutation";
+  readonly handler: Handler<I, O>;
+}
+
+export interface EventProc<P> {
+  readonly type: "event";
+  /** Phantom field carrying the payload type; never set at runtime. */
+  readonly __payload?: P;
+}
+
+export type Procedure =
+  | QueryProc<any, any>
+  | MutationProc<any, any>
+  | EventProc<any>;
+
+export interface Router<T extends Record<string, Procedure> = Record<string, Procedure>> {
+  readonly type: "router";
+  readonly routes: T;
+}
+
+export const rpc = {
+  router<T extends Record<string, Procedure>>(routes: T): Router<T> {
+    return { type: "router", routes };
+  },
+
+  /** Request/response, semantically a read. Runtime-identical to mutation in the MVP. */
+  query<I, O>(handler: Handler<I, O>): QueryProc<I, O> {
+    return { type: "query", handler };
+  },
+
+  /** Request/response, semantically a write. */
+  mutation<I, O>(handler: Handler<I, O>): MutationProc<I, O> {
+    return { type: "mutation", handler };
+  },
+
+  /** Main → UI push channel. Emit via window handles or app.rpc broadcast. */
+  event<P>(): EventProc<P> {
+    return { type: "event" };
+  },
+};

package/src/runtime.ts

@@ -0,0 +1,92 @@
+/**
+ * Worker-side runtime: loads libmirin_core, starts the RPC server, and pumps
+ * native events to feature modules. Infrastructure only — the developer-facing
+ * API lives in app.ts and the feature modules, which subscribe here.
+ */
+
+import { workerData } from "node:worker_threads";
+import { Core } from "./native.ts";
+import { RpcServer } from "./rpc-server.ts";
+import type { WindowConfig } from "./config.ts";
+
+export interface ManifestWindowConfig extends WindowConfig {
+  name: string;
+}
+
+export interface Runtime {
+  core: Core;
+  rpc: RpcServer;
+  manifestWindows: ManifestWindowConfig[];
+  devUrl?: string;
+}
+
+export class NotAttachedError extends Error {
+  constructor(what: string) {
+    super(`${what}: the mirin native host is not attached. Run via \`mirin dev\`.`);
+    this.name = "NotAttachedError";
+  }
+}
+
+let current: Runtime | undefined;
+
+/** The live runtime; throws if the native host isn't attached. */
+export function runtime(): Runtime {
+  if (!current) throw new NotAttachedError("mirin runtime");
+  return current;
+}
+
+/** Dev: every window loads the Vite server. Production: its manifest app:// URL. */
+export function resolveUrl(url: string): string {
+  return current?.devUrl ?? url;
+}
+
+// ---- native event dispatch ----
+
+export interface NativeEvent {
+  type: string;
+  [key: string]: unknown;
+}
+
+type NativeListener = (event: NativeEvent) => void;
+const listeners = new Map<string, Set<NativeListener>>();
+
+/** Subscribe to a native event type (e.g. "menu.click"). Safe before boot. */
+export function onNativeEvent(type: string, listener: NativeListener): () => void {
+  let set = listeners.get(type);
+  if (!set) listeners.set(type, (set = new Set()));
+  set.add(listener);
+  return () => set!.delete(listener);
+}
+
+function dispatch(raw: string): void {
+  let event: NativeEvent;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  listeners.get(event.type)?.forEach((fn) => fn(event));
+}
+
+/** Boot the runtime from the Worker's workerData. No-op when run detached. */
+export function boot(): void {
+  const data = (workerData ?? {}) as {
+    corePath?: string;
+    manifest?: { windows?: Record<string, WindowConfig> };
+    devUrl?: string;
+  };
+  const corePath = data.corePath ?? process.env.MIRIN_CORE;
+  if (!corePath) return; // not under the host; the API stays detached
+
+  const core = new Core(corePath);
+  const rpc = new RpcServer();
+  const port = rpc.start();
+  core.setRpcEndpoint(port, rpc.token);
+
+  const manifestWindows: ManifestWindowConfig[] = Object.entries(
+    data.manifest?.windows ?? {},
+  ).map(([name, cfg]) => ({ name, ...cfg }));
+
+  current = { core, rpc, manifestWindows, devUrl: data.devUrl };
+  core.onEvent(dispatch);
+}

package/src/shortcut.ts

@@ -0,0 +1,42 @@
+/**
+ * Global (system-wide) keyboard shortcuts. Each registration gets an id; the
+ * native side reports presses as `shortcut.trigger` events.
+ */
+
+import { runtime, onNativeEvent } from "./runtime.ts";
+
+let nextId = 1;
+const handlers = new Map<number, () => void>();
+const idByAccelerator = new Map<string, number>();
+
+onNativeEvent("shortcut.trigger", (event) => {
+  handlers.get(event.id as number)?.();
+});
+
+export const globalShortcut = {
+  /** Register a global hotkey, e.g. "Cmd+Shift+K". Returns false if invalid. */
+  register(accelerator: string, handler: () => void): boolean {
+    this.unregister(accelerator);
+    const id = nextId++;
+    handlers.set(id, handler);
+    const ok = runtime().core.shortcutRegister(id, accelerator);
+    if (ok) {
+      idByAccelerator.set(accelerator, id);
+    } else {
+      handlers.delete(id);
+    }
+    return ok;
+  },
+
+  unregister(accelerator: string): void {
+    const id = idByAccelerator.get(accelerator);
+    if (id == null) return;
+    runtime().core.shortcutUnregister(id);
+    handlers.delete(id);
+    idByAccelerator.delete(accelerator);
+  },
+
+  unregisterAll(): void {
+    for (const accelerator of [...idByAccelerator.keys()]) this.unregister(accelerator);
+  },
+};

package/src/tray.ts

@@ -0,0 +1,42 @@
+/**
+ * Menu-bar tray items. A tray with a `menu` shows it on click (items route
+ * through the shared menu registry); a tray without a menu fires `onClick`.
+ */
+
+import { runtime, onNativeEvent } from "./runtime.ts";
+import { buildNativeMenu, type MenuItemTemplate } from "./menu.ts";
+
+export interface TrayOptions {
+  title?: string;
+  tooltip?: string;
+  menu?: MenuItemTemplate[];
+  onClick?: () => void;
+}
+
+let nextId = 1;
+const clickHandlers = new Map<number, () => void>();
+
+onNativeEvent("tray.click", (event) => {
+  clickHandlers.get(event.id as number)?.();
+});
+
+export class Tray {
+  readonly id = nextId++;
+
+  constructor(options: TrayOptions) {
+    if (options.onClick) clickHandlers.set(this.id, options.onClick);
+    runtime().core.trayCreate(
+      JSON.stringify({
+        id: this.id,
+        title: options.title,
+        tooltip: options.tooltip,
+        menu: options.menu ? buildNativeMenu(options.menu) : undefined,
+      }),
+    );
+  }
+
+  destroy(): void {
+    runtime().core.trayDestroy(this.id);
+    clickHandlers.delete(this.id);
+  }
+}