mirinjs 0.0.1-alpha.9 → 0.1.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirinjs",
-  "version": "0.0.1-alpha.9",
+  "version": "0.1.0-alpha.0",
   "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "./config": "./src/config.ts",
     "./rpc": "./src/rpc.ts",
     "./client": "./src/client.ts",
+    "./codec": "./src/codec.ts",
     "./host": "./src/host.ts"
   },
   "files": [

package/src/app.ts

@@ -6,6 +6,10 @@
 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 = {
@@ -30,6 +34,9 @@ export type WindowEvents = {
 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). */
@@ -279,6 +286,9 @@ export interface Dock {
 class MirinApp extends Emitter<AppEvents> {
   readonly windows = new Windows();
 
+  /** Auto-updater (macOS). Inert unless the app was built with `release` set. */
+  readonly updater: Updater = updater;
+
   /** macOS Dock-icon controls. Hiding suits resident, hotkey-summoned apps. */
   readonly dock: Dock = {
     hide: () => this.#setDock(false),
@@ -308,6 +318,14 @@ class MirinApp extends Emitter<AppEvents> {
     return rpcEmitters((method, payload) => runtime().rpc.broadcast(method, payload));
   }
 
+  /**
+   * Spawn a bundled sidecar binary (declared in `mirin.config.ts` `sidecars`).
+   * Resolves the in-bundle path and tracks the child so it's killed on quit.
+   */
+  sidecar(name: string, opts?: SidecarOptions): SidecarProcess {
+    return spawnSidecar(name, opts);
+  }
+
   quit(): void {
     runtime().core.quit();
   }
@@ -342,6 +360,11 @@ export function wireAppEvents(): void {
 
   onNativeEvent("window.all-closed", () => app._emit("window-all-closed", undefined));
 
+  onNativeEvent("app.open-url", (event: NativeEvent) => {
+    const url = event.url;
+    if (typeof url === "string") app._emit("open-url", url);
+  });
+
   onNativeEvent("window.material", (event: NativeEvent) => {
     const id = event.id as number | undefined;
     if (id == null) return;

package/src/client.ts

@@ -23,6 +23,8 @@ export type ClientFor<R extends Router<any>> =
 interface MirinTransport {
   call(method: string, input: unknown): Promise<unknown>;
   onEvent(method: string, listener: (payload: unknown) => void): () => void;
+  /** Fire-and-forget internal control action (window dragging/controls). */
+  control?(action: string, extra?: Record<string, unknown>): void;
 }
 
 declare global {
@@ -65,3 +67,21 @@ export function client<R extends Router<any>>(): ClientFor<R> {
     },
   });
 }
+
+/**
+ * Window controls for the current webview's window, callable from page code —
+ * for custom title bars (`titleBarStyle: hidden | hiddenInset`) where the app
+ * draws its own min/max/close buttons. On Windows these are the only controls
+ * (no native caption); on macOS the native traffic lights usually serve instead.
+ */
+export const windowControls = {
+  minimize(): void {
+    transport().control?.("window.control", { verb: "minimize" });
+  },
+  maximize(): void {
+    transport().control?.("window.control", { verb: "maximize" });
+  },
+  close(): void {
+    transport().control?.("window.close");
+  },
+};

package/src/codec.ts

@@ -0,0 +1,62 @@
+/**
+ * mirin/codec — thin bun:ffi bindings to libmirin_core's updater codec (zstd +
+ * bsdiff, file-path API). Used both at `mirin release` time (produce patches)
+ * and at runtime (apply them), loading the same dylib so compress/diff are
+ * byte-identical on both sides.
+ */
+
+import { dlopen, FFIType, ptr } from "bun:ffi";
+
+const SYMBOLS = {
+  mirin_zstd_compress_file: { args: [FFIType.ptr, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  mirin_zstd_decompress_file: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+  mirin_bsdiff_file: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+  mirin_bspatch_file: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+} as const;
+
+function cstr(s: string): Uint8Array {
+  return new TextEncoder().encode(s + "\0");
+}
+
+export interface Codec {
+  /** zstd-compress `src` → `dst` at `level` (default 19). */
+  compress(src: string, dst: string, level?: number): void;
+  /** zstd-decompress `src` → `dst`. */
+  decompress(src: string, dst: string): void;
+  /** bsdiff: write a patch turning `oldPath` into `newPath`. */
+  diff(oldPath: string, newPath: string, patchPath: string): void;
+  /** bspatch: apply `patchPath` to `oldPath`, producing `newPath`. */
+  patch(oldPath: string, patchPath: string, newPath: string): void;
+}
+
+/** Load the codec from a libmirin_core dylib path. */
+export function loadCodec(dylibPath: string): Codec {
+  const { symbols } = dlopen(dylibPath, SYMBOLS);
+  const check = (rc: number, op: string) => {
+    if (rc !== 0) throw new Error(`codec ${op} failed (rc=${rc})`);
+  };
+  return {
+    compress(src, dst, level = 19) {
+      const s = cstr(src);
+      const d = cstr(dst);
+      check(symbols.mirin_zstd_compress_file(ptr(s), ptr(d), level), "compress");
+    },
+    decompress(src, dst) {
+      const s = cstr(src);
+      const d = cstr(dst);
+      check(symbols.mirin_zstd_decompress_file(ptr(s), ptr(d)), "decompress");
+    },
+    diff(oldPath, newPath, patchPath) {
+      const o = cstr(oldPath);
+      const n = cstr(newPath);
+      const p = cstr(patchPath);
+      check(symbols.mirin_bsdiff_file(ptr(o), ptr(n), ptr(p)), "diff");
+    },
+    patch(oldPath, patchPath, newPath) {
+      const o = cstr(oldPath);
+      const p = cstr(patchPath);
+      const n = cstr(newPath);
+      check(symbols.mirin_bspatch_file(ptr(o), ptr(p), ptr(n)), "patch");
+    },
+  };
+}

package/src/config.ts

@@ -51,6 +51,13 @@ export interface WindowConfig {
   open?: "auto" | "manual";
   /** Custom title bar: hide it (content fills) or inset the traffic lights. */
   titleBarStyle?: "hidden" | "hiddenInset";
+  /**
+   * Reposition the macOS traffic-light buttons for a custom title bar.
+   * `x` insets the leftmost button from the left edge; `y` sets the effective
+   * title-bar height the buttons are vertically centered in (so `y` ≈ your CSS
+   * title-bar height minus the button height). Re-applied automatically on resize.
+   */
+  trafficLightPosition?: { x: number; y: number };
   /** Non-opaque window (for transparent/blurred UIs). */
   transparent?: boolean;
   /**
@@ -79,9 +86,103 @@ export interface MirinConfig {
    * into an `.icns`. Embedded in the bundle for the Dock and Finder.
    */
   icon?: string;
+  /**
+   * Auto-update configuration (macOS). 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
+   * support folder, so multiple channels can coexist at the same `baseUrl`.
+   */
+  release?: ReleaseConfig;
+  /**
+   * macOS `.dmg` installer produced by `mirin release` (alongside the updater
+   * artifacts). `true`/omitted builds a default drag-to-Applications DMG; an
+   * object customizes it; `false` disables it. The DMG is codesigned and (when
+   * notary credentials are set) notarized + stapled like the `.app`.
+   */
+  dmg?: boolean | DmgConfig;
+  /**
+   * 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
+   * `Contents/Resources/sidecars/<name>`, codesigned (hardened runtime), and —
+   * when notary credentials are set — notarized with the rest of the app.
+   *
+   * Prefer a binary already on the user's PATH (`Bun.spawn("git", …)`) or a
+   * download-on-first-run when size/licensing matter; bundle only when you need
+   * a pinned version offline.
+   */
+  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
+   * 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).
+   */
+  workers?: Record<string, string>;
+  /**
+   * Custom URL schemes this app registers as a handler for (macOS
+   * `CFBundleURLTypes`), e.g. `["anko"]` so `anko://…` links launch the app (or
+   * focus it if already running). Incoming URLs are delivered to
+   * `app.on("open-url", (url) => …)` — including the URL the app was launched
+   * with. Scheme names should be lowercase letters/digits (no `://`).
+   */
+  urlSchemes?: string[];
   windows: Record<string, WindowConfig>;
 }
 
+/** A bundled sidecar binary with optional hardened-runtime entitlements. */
+export interface SidecarSpec {
+  /** Path to the binary, relative to the project root. */
+  bin: string;
+  /**
+   * Extra codesign entitlements for this binary under the hardened runtime.
+   * Most plain CLIs need none. Use `disable-library-validation` for a binary
+   * that loads dylibs not signed by your Team ID, or the JIT entitlements for a
+   * binary that runs its own JIT (another Bun/V8/Node).
+   */
+  entitlements?: SidecarEntitlement[];
+}
+
+export type SidecarEntitlement =
+  | "allow-jit"
+  | "allow-unsigned-executable-memory"
+  | "disable-library-validation";
+
+export interface DmgConfig {
+  /** Volume name shown when the DMG is mounted. Default: the app name. */
+  volumeName?: string;
+  /**
+   * Disk-image format. `ULFO` (lzfse, default) compresses large CEF frameworks
+   * best on modern macOS; `UDZO` (zlib) is the most broadly compatible; `UDBZ`
+   * (bzip2) is smallest but slowest.
+   */
+  format?: "ULFO" | "UDZO" | "UDBZ";
+  /**
+   * Background image for the mounted Finder window (path relative to the project
+   * root). Setting this — or any position/size below — switches to the laid-out
+   * DMG (Finder window styled via AppleScript); best-effort, falling back to a
+   * plain DMG if Finder automation is unavailable.
+   */
+  background?: string;
+  /** Mounted Finder window size, in points. Default 640×400. */
+  windowSize?: { width: number; height: number };
+  /** Icon size in the mounted window, in points. Default 128. */
+  iconSize?: number;
+  /** App icon position in the window. Default centered-left. */
+  appPosition?: { x: number; y: number };
+  /** `/Applications` symlink position. Default centered-right. */
+  applicationsPosition?: { x: number; y: number };
+}
+
+export interface ReleaseConfig {
+  /** Flat directory URL hosting `{channel}-{platform}-{arch}-*` update files. */
+  baseUrl: string;
+  /** Update channel; baked into artifact names + support dir. Default "stable". */
+  channel?: string;
+}
+
 /** 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/host.ts

@@ -19,11 +19,21 @@ 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");
+// Bundle layout differs by platform: macOS `.app` puts the host in
+// `Contents/MacOS` with resources in `../Resources`; Windows is a flat app folder
+// where the host exe sits beside `mirin_core.dll` with resources in `resources/`.
+const isWindows = process.platform === "win32";
+const exeDir = dirname(process.execPath);
+const resourcesDir = isWindows ? join(exeDir, "resources") : join(exeDir, "..", "Resources");
 
-const corePath = process.env.MIRIN_CORE ?? join(exeDir, "libmirin_core.dylib");
+const corePath =
+  process.env.MIRIN_CORE ??
+  join(exeDir, isWindows ? "mirin_core.dll" : "libmirin_core.dylib");
 const workerPath = process.env.MIRIN_WORKER ?? join(resourcesDir, "worker.js");
+// Bundled-asset dirs for sidecars (Bun.spawn binaries) and extra workers. Dev
+// overrides via env (dev.ts stages them under .mirin); prod resolves in-bundle.
+const sidecarDir = process.env.MIRIN_SIDECAR_DIR ?? join(resourcesDir, "sidecars");
+const workersDir = process.env.MIRIN_WORKERS_DIR ?? join(resourcesDir, "workers");
 
 if (!existsSync(corePath) || !existsSync(workerPath)) {
   console.error(`[mirin host] missing core (${corePath}) or worker (${workerPath})`);
@@ -48,7 +58,14 @@ const coreConfig = JSON.parse(
 const core = new Core(corePath);
 
 const worker = new Worker(workerPath, {
-  workerData: { corePath, manifest, devUrl: process.env.MIRIN_DEV_URL },
+  workerData: {
+    corePath,
+    manifest,
+    devUrl: process.env.MIRIN_DEV_URL,
+    resourcesDir,
+    sidecarDir,
+    workersDir,
+  },
 });
 worker.on("error", (err) => console.error("[mirin worker]", err));
 

package/src/index.ts

@@ -3,8 +3,8 @@
  *
  * 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).
+ * the `app` singleton plus the `menu`, `Tray`, `dialog`, `clipboard`,
+ * `globalShortcut`, and `logger` features (docs/api-design.md).
  */
 
 import { app, wireAppEvents } from "./app.ts";
@@ -22,7 +22,10 @@ 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 { 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 {
   WindowEvents,
@@ -36,6 +39,9 @@ export type {
   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";
 export type {
@@ -43,6 +49,10 @@ export type {
   WindowConfig,
   WindowMaterial,
   WindowMaterialOptions,
+  ReleaseConfig,
+  DmgConfig,
+  SidecarSpec,
+  SidecarEntitlement,
 } from "./config.ts";
 
 wireAppEvents();

package/src/logger.ts

@@ -0,0 +1,97 @@
+/**
+ * mirin/logger — a small leveled logger for the Bun main process.
+ *
+ * Exported from `mirinjs` so app code and mirin itself log consistently. The
+ * level defaults from the `MIRIN_LOG` env var (`debug` | `info` | `warn` |
+ * `error` | `silent`), falling back to `info`; change it at runtime with
+ * `logger.setLevel(...)`. `warn`/`error` go to stderr, `debug`/`info` to stdout.
+ *
+ *   import { logger } from "mirinjs";
+ *   logger.info("server listening", port);
+ *   const db = logger.child("db");
+ *   db.debug("query", sql);            // → [mirin:db] debug query …
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+const ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: 100,
+};
+
+const COLOR = {
+  debug: "\x1b[2m", // dim
+  info: "\x1b[36m", // cyan
+  warn: "\x1b[33m", // yellow
+  error: "\x1b[31m", // red
+  dim: "\x1b[2m",
+  reset: "\x1b[0m",
+} as const;
+
+const LEVELS: LogLevel[] = ["debug", "info", "warn", "error", "silent"];
+
+function envLevel(): LogLevel {
+  const v = (process.env.MIRIN_LOG ?? "").toLowerCase() as LogLevel;
+  return LEVELS.includes(v) ? v : "info";
+}
+
+// Shared across every logger instance so `setLevel` is global.
+let currentLevel: LogLevel = envLevel();
+const useColor = Boolean(process.stderr.isTTY) && process.env.NO_COLOR == null;
+
+/** Set the global minimum level. Messages below it are dropped. */
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level;
+}
+
+/** The current global log level. */
+export function getLogLevel(): LogLevel {
+  return currentLevel;
+}
+
+export class Logger {
+  /** @param scope optional dotted scope shown as `[mirin:scope]`. */
+  constructor(private readonly scope?: string) {}
+
+  /** Derive a scoped child logger (e.g. `logger.child("db")`). */
+  child(scope: string): Logger {
+    return new Logger(this.scope ? `${this.scope}:${scope}` : scope);
+  }
+
+  /** Set the global level (same as the exported `setLogLevel`). */
+  setLevel(level: LogLevel): void {
+    setLogLevel(level);
+  }
+
+  get level(): LogLevel {
+    return currentLevel;
+  }
+
+  debug(...args: unknown[]): void {
+    this.#emit("debug", args);
+  }
+  info(...args: unknown[]): void {
+    this.#emit("info", args);
+  }
+  warn(...args: unknown[]): void {
+    this.#emit("warn", args);
+  }
+  error(...args: unknown[]): void {
+    this.#emit("error", args);
+  }
+
+  #emit(level: Exclude<LogLevel, "silent">, args: unknown[]): void {
+    if (ORDER[level] < ORDER[currentLevel]) return;
+    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;
+    sink(`${prefix} ${tag}`, ...args);
+  }
+}
+
+/** The default mirin logger. Import and use directly, or derive children. */
+export const logger = new Logger();

package/src/native.ts

@@ -24,6 +24,7 @@ const symbols = {
   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], 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 },
@@ -113,6 +114,10 @@ export class Core {
     this.#lib.symbols.mirin_window_set_position(id, x, y);
   }
 
+  windowMaybeStartDrag(id: number, x: number, y: number, detail: number): void {
+    this.#lib.symbols.mirin_window_maybe_start_drag(id, x, y, detail);
+  }
+
   quit(): void {
     this.#lib.symbols.mirin_app_quit();
   }

package/src/rpc-server.ts

@@ -18,10 +18,29 @@ interface RequestFrame {
   input: unknown;
 }
 
+/** Internal control frame from the preload bootstrap (window dragging, etc.) —
+ *  a side channel distinct from the app's typed RPC. `x`/`y` are viewport pixels
+ *  (CSS px, top-left) for pointer-driven actions like drag detection. */
+interface ControlFrame {
+  kind: "control";
+  action: string;
+  x?: number;
+  y?: number;
+  verb?: string;
+  /** Click count for pointer actions (2 = double-click → maximize). */
+  detail?: number;
+}
+
+type IncomingFrame = RequestFrame | ControlFrame;
+
+/** Handles an internal control action for the webview that sent it. */
+export type ControlHandler = (frame: ControlFrame, webview: number) => void;
+
 export class RpcServer {
   readonly token = crypto.randomUUID();
   #server?: ReturnType<typeof Bun.serve>;
   #router?: Router<any>;
+  #control?: ControlHandler;
   #sockets = new Set<ServerWebSocket<SocketData>>();
 
   /** Start listening on an ephemeral loopback port; returns the bound port. */
@@ -65,6 +84,11 @@ export class RpcServer {
     this.#router = router;
   }
 
+  /** Register the handler for internal `mirin:*` control actions (e.g. window drag). */
+  setControlHandler(handler: ControlHandler): void {
+    this.#control = handler;
+  }
+
   /** Push an event to every connected webview. */
   broadcast(method: string, payload: unknown): void {
     const frame = JSON.stringify({ kind: "event", method, payload });
@@ -80,12 +104,17 @@ export class RpcServer {
   }
 
   async #onMessage(ws: ServerWebSocket<SocketData>, raw: string | Buffer): Promise<void> {
-    let frame: RequestFrame;
+    let frame: IncomingFrame;
     try {
       frame = JSON.parse(typeof raw === "string" ? raw : raw.toString());
     } catch {
       return;
     }
+    // Internal control side channel (window drag, …) from the preload bootstrap.
+    if (frame.kind === "control") {
+      this.#control?.(frame, ws.data.webview);
+      return;
+    }
     if (frame.kind !== "request") return;
 
     const reply = (ok: boolean, body: { result?: unknown; error?: string }) =>

package/src/runtime.ts

@@ -5,6 +5,7 @@
  */
 
 import { workerData } from "node:worker_threads";
+import { join } from "node:path";
 import { Core } from "./native.ts";
 import { RpcServer } from "./rpc-server.ts";
 import type { WindowConfig } from "./config.ts";
@@ -18,6 +19,14 @@ export interface Runtime {
   rpc: RpcServer;
   manifestWindows: ManifestWindowConfig[];
   devUrl?: string;
+  /** Contents/Resources of the running .app (for the updater). Absent in dev. */
+  resourcesDir?: string;
+  /** Path to libmirin_core (for the updater codec). */
+  corePath?: string;
+  /** Dir holding bundled sidecar binaries (for `app.sidecar`). */
+  sidecarDir?: string;
+  /** Dir holding bundled extra-worker JS (for `resolveWorker`). */
+  workersDir?: string;
 }
 
 export class NotAttachedError extends Error {
@@ -79,6 +88,9 @@ export function boot(): void {
     corePath?: string;
     manifest?: { windows?: Record<string, WindowConfig> };
     devUrl?: string;
+    resourcesDir?: string;
+    sidecarDir?: string;
+    workersDir?: string;
   };
   const corePath = data.corePath ?? process.env.MIRIN_CORE;
   if (!corePath) return; // not under the host; the API stays detached
@@ -88,10 +100,49 @@ export function boot(): void {
   const port = rpc.start();
   core.setRpcEndpoint(port, rpc.token);
 
+  // Internal control actions from the preload bootstrap. `window.maybeStartDrag`
+  // forwards a left-mousedown's viewport coords; native checks them against the
+  // window's drag regions and begins an OS window-move if it's a title-bar drag
+  // area (the webview consumes the event, so dragging is driven from the renderer).
+  rpc.setControlHandler((frame, webview) => {
+    switch (frame.action) {
+      case "window.maybeStartDrag":
+        core.windowMaybeStartDrag(webview, frame.x ?? 0, frame.y ?? 0, frame.detail ?? 1);
+        break;
+      case "window.control":
+        if (frame.verb) core.windowControl(webview, frame.verb);
+        break;
+      case "window.close":
+        core.windowClose(webview);
+        break;
+    }
+  });
+
   const manifestWindows: ManifestWindowConfig[] = Object.entries(
     data.manifest?.windows ?? {},
   ).map(([name, cfg]) => ({ name, ...cfg }));
 
-  current = { core, rpc, manifestWindows, devUrl: data.devUrl };
+  current = {
+    core,
+    rpc,
+    manifestWindows,
+    devUrl: data.devUrl,
+    resourcesDir: data.resourcesDir,
+    corePath,
+    sidecarDir: data.sidecarDir,
+    workersDir: data.workersDir,
+  };
   core.onEvent(dispatch);
 }
+
+/**
+ * Resolve a bundled extra-worker (declared in `mirin.config.ts` `workers`) to an
+ * absolute path, for `new Worker(resolveWorker(name))` from `node:worker_threads`.
+ * Works in `mirin dev` and the built `.app`. Extra workers run off the main
+ * thread and must not call window/native APIs.
+ */
+export function resolveWorker(name: string): string {
+  const dir = current?.workersDir;
+  if (!dir) throw new NotAttachedError("resolveWorker");
+  return join(dir, `${name}.js`);
+}

package/src/sidecar.ts

@@ -0,0 +1,107 @@
+/**
+ * Sidecars — spawn a binary bundled into the `.app` (declared in
+ * `mirin.config.ts` `sidecars`). A thin wrapper over `Bun.spawn` that resolves
+ * the bundled path (dev or prod, via `runtime().sidecarDir`) and tracks the
+ * child so it's killed when the app quits — the two things hand-rolled
+ * `Bun.spawn` gets wrong (path resolution + orphaned processes).
+ *
+ * Sidecars run as separate OS processes, so they may do anything a CLI can; they
+ * just can't touch the app's AppKit/CEF UI (nothing off the main thread can).
+ */
+
+import { join } from "node:path";
+import { runtime, onNativeEvent } from "./runtime.ts";
+
+export interface SidecarOptions {
+  /** Arguments passed after the binary path. */
+  args?: string[];
+  cwd?: string;
+  /** Extra env on top of the inherited environment. */
+  env?: Record<string, string>;
+  /** Defaults: stdin "pipe", stdout "pipe", stderr "inherit". */
+  stdin?: Bun.SpawnOptions.Writable;
+  stdout?: Bun.SpawnOptions.Readable;
+  stderr?: Bun.SpawnOptions.Readable;
+}
+
+/** A running sidecar. Mirrors the subset of `Bun.Subprocess` apps need. */
+export interface SidecarProcess {
+  readonly pid: number;
+  readonly stdin: Bun.Subprocess["stdin"];
+  readonly stdout: Bun.Subprocess["stdout"];
+  readonly stderr: Bun.Subprocess["stderr"];
+  /** Resolves with the exit code when the process ends. */
+  readonly exited: Promise<number>;
+  /** Send a signal (default SIGTERM) and stop tracking it. */
+  kill(signal?: number | NodeJS.Signals): void;
+}
+
+const children = new Set<Bun.Subprocess>();
+let hooked = false;
+
+function killAll(): void {
+  for (const child of children) {
+    try {
+      child.kill();
+    } catch {
+      // already gone
+    }
+  }
+  children.clear();
+}
+
+/** Register shutdown hooks once, so sidecars don't outlive the app. */
+function ensureHooks(): void {
+  if (hooked) return;
+  hooked = true;
+  // App fully quit (last window closed / Cmd-Q path surfaces here).
+  onNativeEvent("window.all-closed", killAll);
+  // Worker-process shutdown backstops (normal exit / signals). `terminate()` is
+  // abrupt and won't fire these, hence the native-event hook above as well.
+  for (const sig of ["exit", "SIGINT", "SIGTERM"] as const) {
+    process.on(sig, killAll);
+  }
+}
+
+/**
+ * Spawn a bundled sidecar binary by its config name. Throws if the runtime
+ * isn't attached or no `sidecarDir` is known (e.g. run outside the host).
+ */
+export function sidecar(name: string, opts: SidecarOptions = {}): SidecarProcess {
+  const dir = runtime().sidecarDir;
+  if (!dir) {
+    throw new Error(`app.sidecar("${name}"): no sidecar dir (is this running under the mirin host?)`);
+  }
+  ensureHooks();
+
+  const bin = join(dir, name);
+  const child = Bun.spawn([bin, ...(opts.args ?? [])], {
+    cwd: opts.cwd,
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+    stdin: opts.stdin ?? "pipe",
+    stdout: opts.stdout ?? "pipe",
+    stderr: opts.stderr ?? "inherit",
+  });
+  children.add(child);
+  void child.exited.then(() => children.delete(child));
+
+  return {
+    get pid() {
+      return child.pid;
+    },
+    get stdin() {
+      return child.stdin;
+    },
+    get stdout() {
+      return child.stdout;
+    },
+    get stderr() {
+      return child.stderr;
+    },
+    exited: child.exited,
+    kill(signal) {
+      children.delete(child);
+      child.kill(signal as number | undefined);
+    },
+  };
+}

package/src/updater.ts

@@ -0,0 +1,381 @@
+/**
+ * mirin/updater — the `app.updater` API (runs in the Bun Worker).
+ *
+ * Reads the app's `Resources/version.json` (embedded by `mirin build` when
+ * `release` is set), polls `{baseUrl}/{prefix}-update.json`, and when a different
+ * version is published downloads it, verifies its SHA-256, then swaps the whole
+ * `.app` and relaunches. Updates prefer a small **delta patch** (bsdiff) from the
+ * currently-installed version and fall back to the full bundle whenever a patch
+ * isn't usable.
+ *
+ * A signed/notarized `.app` cannot be modified in place without breaking its
+ * signature, so the whole bundle is always replaced. Updates run only in a
+ * packaged app with `release` set; in `mirin dev` the updater is idle.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { $ } from "bun";
+import { runtime } from "./runtime.ts";
+import { loadCodec } from "./codec.ts";
+
+const IS_WINDOWS = process.platform === "win32";
+
+export type UpdaterStatus =
+  | "idle"
+  | "checking"
+  | "update-available"
+  | "downloading"
+  | "applying"
+  | "complete"
+  | "error";
+
+/** The running app's embedded identity (Resources/version.json). */
+interface VersionInfo {
+  version: string;
+  channel: string;
+  baseUrl: string;
+  name: string;
+  identifier: string;
+}
+
+/** The published-release manifest ({prefix}-update.json). */
+interface Manifest {
+  version: string;
+  channel: string;
+  platform: string;
+  arch: string;
+  /** SHA-256 of the uncompressed bundle tar (update identity + integrity). */
+  tarHash: string;
+  bundle: { url: string; sha256: string; size?: number };
+  patches?: Array<{ fromVersion: string; url: string; sha256: string; size?: number }>;
+}
+
+/** A published release the running app can update to. */
+export interface UpdateInfo {
+  version: string;
+  currentVersion: string;
+  channel: string;
+}
+
+export interface UpdateProgress {
+  received: number;
+  total: number;
+  /** 0..1 (0 when total is unknown). */
+  fraction: number;
+}
+
+export type UpdaterEvents = {
+  status: { status: UpdaterStatus };
+  progress: UpdateProgress;
+  "update-available": UpdateInfo;
+  error: { message: string };
+};
+
+type Listener<P> = (payload: P) => void;
+
+export class Updater {
+  #listeners = new Map<keyof UpdaterEvents, Set<Listener<unknown>>>();
+  #status: UpdaterStatus = "idle";
+  #info: VersionInfo | null | undefined;
+  #manifest: Manifest | null = null;
+  #staged: string | null = null;
+  #autoCheck: ReturnType<typeof setInterval> | undefined;
+
+  on<K extends keyof UpdaterEvents>(type: K, listener: Listener<UpdaterEvents[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>);
+  }
+
+  get status(): UpdaterStatus {
+    return this.#status;
+  }
+  get currentVersion(): string {
+    return this.#version()?.version ?? "0.0.0";
+  }
+  get channel(): string {
+    return this.#version()?.channel ?? "stable";
+  }
+  /** Whether updates are configured (packaged build with `release` set). */
+  get enabled(): boolean {
+    return this.#version() != null;
+  }
+
+  /** Fetch the channel manifest; report an available update or `null`. Never throws. */
+  async checkForUpdate(): Promise<UpdateInfo | null> {
+    const v = this.#version();
+    if (!v) return null;
+    this.#setStatus("checking");
+    try {
+      const url = `${v.baseUrl.replace(/\/$/, "")}/${this.#prefix()}-update.json?t=${Date.now()}`;
+      const res = await fetch(url, { redirect: "follow" });
+      if (!res.ok) throw new Error(`manifest ${res.status}`);
+      const m = (await res.json()) as Manifest;
+      if (!m.version || m.version === v.version) {
+        this.#manifest = null;
+        this.#setStatus("idle");
+        return null;
+      }
+      this.#manifest = m;
+      const info: UpdateInfo = { version: m.version, currentVersion: v.version, channel: v.channel };
+      this.#setStatus("update-available");
+      this.#emit("update-available", info);
+      return info;
+    } catch (err) {
+      this.#fail(err);
+      return null;
+    }
+  }
+
+  /**
+   * Download + verify the pending update — a delta patch from the installed
+   * version when available, else the full bundle. Emits `progress`.
+   */
+  async download(onProgress?: (p: UpdateProgress) => void): Promise<void> {
+    const v = this.#version();
+    const m = this.#manifest;
+    if (!v || !m) throw new Error("no update to download — call checkForUpdate() first");
+    this.#setStatus("downloading");
+    try {
+      const codec = loadCodec(this.#corePath());
+      const support = this.#supportDir(v);
+      const tarsDir = join(support, "tars");
+      const work = join(support, "updates");
+      mkdirSync(tarsDir, { recursive: true });
+      rmSync(work, { recursive: true, force: true });
+      mkdirSync(work, { recursive: true });
+
+      const base = v.baseUrl.replace(/\/$/, "");
+      const newTar = join(work, "new.tar");
+      const cachedTar = join(tarsDir, `${v.version}.tar`);
+      const patch = m.patches?.find((p) => p.fromVersion === v.version);
+
+      let ok = false;
+      if (patch && existsSync(cachedTar)) {
+        try {
+          const patchZst = join(work, "patch.zst");
+          await this.#fetchToFile(`${base}/${patch.url}`, patchZst, patch.sha256, onProgress);
+          const patchRaw = join(work, "patch.bin");
+          codec.decompress(patchZst, patchRaw);
+          codec.patch(cachedTar, patchRaw, newTar); // bspatch
+          await this.#verify(newTar, m.tarHash);
+          ok = true;
+        } catch {
+          ok = false; // delta failed → full bundle
+        }
+      }
+      if (!ok) {
+        const bundleZst = join(work, "bundle.tar.zst");
+        await this.#fetchToFile(`${base}/${m.bundle.url}`, bundleZst, m.bundle.sha256, onProgress);
+        codec.decompress(bundleZst, newTar);
+        await this.#verify(newTar, m.tarHash);
+      }
+
+      // Cache the new tar (for the next delta) and extract for swapping.
+      const keepTar = join(tarsDir, `${m.version}.tar`);
+      rmSync(keepTar, { force: true });
+      renameSync(newTar, keepTar);
+      await $`tar -xf ${keepTar} -C ${work}`.quiet();
+      // The packaged unit: a flat app folder on Windows, an `.app` on macOS.
+      const staged = join(work, IS_WINDOWS ? v.name : `${v.name}.app`);
+      if (!existsSync(staged)) throw new Error(`extracted bundle not found at ${staged}`);
+
+      if (!IS_WINDOWS) {
+        const verify = await $`codesign --verify --deep --strict ${staged}`.quiet().nothrow();
+        if (verify.exitCode !== 0)
+          throw new Error("codesign verification failed on the downloaded update");
+      }
+
+      // Keep only the newest cached tar.
+      for (const f of readdirSync(tarsDir)) {
+        if (f !== `${m.version}.tar`) rmSync(join(tarsDir, f), { force: true });
+      }
+
+      this.#staged = staged;
+      this.#setStatus("update-available");
+    } catch (err) {
+      this.#fail(err);
+      throw err;
+    }
+  }
+
+  /** Swap the running `.app` with the downloaded bundle and relaunch. */
+  async applyAndRelaunch(): Promise<void> {
+    const v = this.#version();
+    if (!v || !this.#staged) throw new Error("no staged update — call download() first");
+    this.#setStatus("applying");
+    try {
+      // The running app folder: macOS `.app` is Contents/Resources/../.. ; Windows
+      // is the exe dir, i.e. resources/.. . A detached helper waits for this process
+      // to exit (the exe/bundle is locked while running), swaps the folder, relaunches.
+      if (IS_WINDOWS) {
+        const runningApp = join(this.#resourcesDir()!, "..");
+        const exe = join(runningApp, `${this.#version()!.name}.exe`);
+        const ps = [
+          `$ErrorActionPreference='SilentlyContinue'`,
+          `while (Get-Process -Id ${process.pid} -ErrorAction SilentlyContinue) { Start-Sleep -Milliseconds 200 }`,
+          `Start-Sleep -Milliseconds 400`,
+          `Remove-Item -Recurse -Force ${psq(runningApp)}`,
+          `Move-Item -Force ${psq(this.#staged)} ${psq(runningApp)}`,
+          `Start-Process ${psq(exe)}`,
+        ].join("; ");
+        Bun.spawn(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps], {
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "ignore",
+        }).unref();
+      } else {
+        const runningApp = join(this.#resourcesDir()!, "..", "..");
+        const script = [
+          `APP=${sh(runningApp)}`,
+          `NEW=${sh(this.#staged)}`,
+          `PID=${process.pid}`,
+          `while kill -0 "$PID" 2>/dev/null; do sleep 0.2; done`,
+          `sleep 0.3`,
+          `rm -rf "$APP"`,
+          `mv "$NEW" "$APP"`,
+          `xattr -r -d com.apple.quarantine "$APP" 2>/dev/null || true`,
+          `open "$APP"`,
+        ].join("\n");
+        Bun.spawn(["/bin/sh", "-c", script], {
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "ignore",
+        }).unref();
+      }
+
+      this.#setStatus("complete");
+      runtime().core.quit();
+    } catch (err) {
+      this.#fail(err);
+      throw err;
+    }
+  }
+
+  /** Poll for updates every `intervalMs`. Returns a stop function. */
+  startAutoCheck(intervalMs = 6 * 60 * 60 * 1000): () => void {
+    this.stopAutoCheck();
+    void this.checkForUpdate();
+    this.#autoCheck = setInterval(() => void this.checkForUpdate(), intervalMs);
+    return () => this.stopAutoCheck();
+  }
+
+  stopAutoCheck(): void {
+    if (this.#autoCheck) clearInterval(this.#autoCheck);
+    this.#autoCheck = undefined;
+  }
+
+  // ---- internals ----
+
+  async #fetchToFile(
+    url: string,
+    dest: string,
+    expectedSha: string,
+    onProgress?: (p: UpdateProgress) => void,
+  ): Promise<void> {
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok || !res.body) throw new Error(`download ${res.status}`);
+    const total = Number(res.headers.get("content-length") ?? 0);
+    const reader = res.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let received = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      received += value.byteLength;
+      const p: UpdateProgress = { received, total, fraction: total ? received / total : 0 };
+      this.#emit("progress", p);
+      onProgress?.(p);
+    }
+    const buf = Buffer.concat(chunks);
+    const got = new Bun.CryptoHasher("sha256").update(buf).digest("hex");
+    if (got !== expectedSha) throw new Error("download hash mismatch");
+    await Bun.write(dest, buf);
+  }
+
+  async #verify(file: string, expectedSha: string): Promise<void> {
+    const buf = await Bun.file(file).bytes();
+    const got = new Bun.CryptoHasher("sha256").update(buf).digest("hex");
+    if (got !== expectedSha) throw new Error("reconstructed bundle hash mismatch");
+  }
+
+  #version(): VersionInfo | null {
+    if (this.#info !== undefined) return this.#info;
+    const dir = this.#resourcesDir();
+    const path = dir ? join(dir, "version.json") : undefined;
+    if (path && existsSync(path)) {
+      try {
+        this.#info = JSON.parse(readFileSync(path, "utf8")) as VersionInfo;
+      } catch {
+        this.#info = null;
+      }
+    } else {
+      this.#info = null;
+    }
+    return this.#info;
+  }
+
+  #resourcesDir(): string | undefined {
+    try {
+      return runtime().resourcesDir;
+    } catch {
+      return undefined;
+    }
+  }
+
+  #corePath(): string {
+    const p = runtime().corePath;
+    if (!p) throw new Error("libmirin_core path unavailable");
+    return p;
+  }
+
+  #prefix(): string {
+    const platform = IS_WINDOWS ? "win32" : "darwin";
+    return `${this.#version()!.channel}-${platform}-${process.arch}`;
+  }
+
+  #supportDir(v: VersionInfo): string {
+    if (IS_WINDOWS) {
+      const base = process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+      return join(base, v.identifier, v.channel);
+    }
+    return join(homedir(), "Library", "Application Support", v.identifier, v.channel);
+  }
+
+  #setStatus(status: UpdaterStatus): void {
+    this.#status = status;
+    this.#emit("status", { status });
+  }
+
+  #fail(err: unknown): void {
+    const message = err instanceof Error ? err.message : String(err);
+    this.#status = "error";
+    this.#emit("status", { status: "error" });
+    this.#emit("error", { message });
+  }
+
+  #emit<K extends keyof UpdaterEvents>(type: K, payload: UpdaterEvents[K]): void {
+    this.#listeners.get(type)?.forEach((fn) => fn(payload));
+    try {
+      runtime().rpc.broadcast(`mirin:updater:${type}`, payload);
+    } catch {
+      // detached / rpc not up — ignore
+    }
+  }
+}
+
+/** Single-quote a path for safe interpolation into a /bin/sh script. */
+function sh(p: string): string {
+  return `'${p.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Single-quote a path for safe interpolation into a PowerShell command. */
+function psq(p: string): string {
+  return `'${p.replace(/'/g, "''")}'`;
+}
+
+export const updater = new Updater();