mirinjs 0.0.1-alpha.1 → 0.0.1-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirinjs",
-  "version": "0.0.1-alpha.1",
+  "version": "0.0.1-alpha.11",
   "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
   "type": "module",
   "license": "MIT",

package/src/app.ts

@@ -6,6 +6,8 @@
 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";
 
 /** Which native backend a window's `material` resolved to. */
 export type WindowMaterialInfo = {
@@ -32,6 +34,14 @@ export type AppEvents = {
   "window-all-closed": void;
 };
 
+/** 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>> {
@@ -127,6 +137,31 @@ export class WindowHandle extends Emitter<WindowEvents> {
     runtime().core.windowSetMaterial(this.id, JSON.stringify(normalizeMaterial(material)));
   }
 
+  /** Move the window's bottom-left origin to screen point (x, y), in points. */
+  setPosition(x: number, y: number): void {
+    runtime().core.windowSetPosition(this.id, x, y);
+  }
+
+  /** The latest known window frame (screen points, bottom-left origin). Tracked
+   *  from `moved`/`resized` events, so it's current without a round-trip. */
+  getFrame(): WindowFrame {
+    return this.#frame ?? { x: 0, y: 0, width: 0, height: 0 };
+  }
+
+  /** Whether the window is currently zoomed (maximized). */
+  isMaximized(): boolean {
+    return this.#maximized;
+  }
+
+  #frame: WindowFrame | null = null;
+  #maximized = false;
+
+  /** @internal — fed from native window frame events. */
+  _setFrame(frame: WindowFrame, maximized: boolean): void {
+    this.#frame = frame;
+    this.#maximized = maximized;
+  }
+
   #control(verb: string): void {
     runtime().core.windowControl(this.id, verb);
   }
@@ -246,6 +281,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),
@@ -322,7 +360,15 @@ export function wireAppEvents(): void {
   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);
+      if (id == null) return;
+      const handle = app.windows._byId(id);
+      if (!handle) return;
+      // moved/resized carry the current frame + maximized state; track them so
+      // getFrame()/isMaximized() are answerable without a round-trip.
+      if (event.frame) {
+        handle._setFrame(event.frame as WindowFrame, Boolean(event.maximized));
+      }
+      handle._emit(kind, undefined);
     });
   }
 }

package/src/config.ts

@@ -42,12 +42,22 @@ export interface WindowConfig {
   title?: string;
   width?: number;
   height?: number;
+  /** Screen position (bottom-left origin, points). Centered when absent. */
+  x?: number;
+  y?: 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";
+  /**
+   * 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;
   /**
@@ -70,9 +80,30 @@ export interface MirinConfig {
   name: string;
   /** Main-process entry, relative to the project root (runs in the Bun Worker). */
   main: string;
+  /**
+   * App icon, relative to the project root (macOS). Accepts a `.icns`, a
+   * `.iconset` directory, or a single square `.png` (≥512px) that mirin renders
+   * 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;
   windows: Record<string, WindowConfig>;
 }
 
+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

@@ -36,7 +36,9 @@ const manifest = JSON.parse(
 
 const coreConfig = JSON.parse(
   process.env.MIRIN_CONFIG_JSON ??
-    JSON.stringify(process.env.MIRIN_DEV_URL ? {} : { resources_path: resourcesDir }),
+    JSON.stringify(
+      process.env.MIRIN_DEV_URL ? { dev: true } : { resources_path: resourcesDir },
+    ),
 );
 
 // Load the native core on the main thread FIRST. The Worker also dlopens the
@@ -46,7 +48,7 @@ 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 },
 });
 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,11 +22,14 @@ 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 { NotAttachedError } from "./runtime.ts";
 
 export type {
   WindowEvents,
   WindowMaterialInfo,
+  WindowFrame,
   AppEvents,
   WindowHandle,
   WindowOpenOptions,
@@ -35,6 +38,8 @@ 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 { TrayOptions } from "./tray.ts";
 export type { OpenDialogOptions, SaveDialogOptions, MessageDialogOptions } from "./dialog.ts";
 export type {

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

@@ -23,6 +23,7 @@ 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_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 },
@@ -108,6 +109,10 @@ export class Core {
     this.#lib.symbols.mirin_window_set_material(id, ptr(buf));
   }
 
+  windowSetPosition(id: number, x: number, y: number): void {
+    this.#lib.symbols.mirin_window_set_position(id, x, y);
+  }
+
   quit(): void {
     this.#lib.symbols.mirin_app_quit();
   }

package/src/runtime.ts

@@ -18,6 +18,8 @@ export interface Runtime {
   rpc: RpcServer;
   manifestWindows: ManifestWindowConfig[];
   devUrl?: string;
+  /** Contents/Resources of the running .app (for the updater). Absent in dev. */
+  resourcesDir?: string;
 }
 
 export class NotAttachedError extends Error {
@@ -35,9 +37,14 @@ export function runtime(): Runtime {
   return current;
 }
 
-/** Dev: every window loads the Vite server. Production: its manifest app:// URL. */
+/** Dev: every window loads the Vite server. Production: its manifest app:// URL.
+ *  Any query/hash on the requested URL (e.g. "#devtools") is preserved so
+ *  hash-routed sub-windows reach the right view through the dev server too. */
 export function resolveUrl(url: string): string {
-  return current?.devUrl ?? url;
+  const devUrl = current?.devUrl;
+  if (!devUrl) return url;
+  const suffix = url.match(/[?#].*$/)?.[0] ?? "";
+  return devUrl + suffix;
 }
 
 // ---- native event dispatch ----
@@ -74,6 +81,7 @@ export function boot(): void {
     corePath?: string;
     manifest?: { windows?: Record<string, WindowConfig> };
     devUrl?: string;
+    resourcesDir?: string;
   };
   const corePath = data.corePath ?? process.env.MIRIN_CORE;
   if (!corePath) return; // not under the host; the API stays detached
@@ -87,6 +95,6 @@ export function boot(): void {
     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 };
   core.onEvent(dispatch);
 }

package/src/updater.ts

@@ -0,0 +1,314 @@
+/**
+ * mirin/updater — the `app.updater` API (runs in the Bun Worker).
+ *
+ * Reads the app's own `Resources/version.json` (embedded by `mirin build` when
+ * `release` is configured), polls the manifest at `{baseUrl}/{prefix}-update.json`,
+ * downloads the full `.app` bundle when a different version is published, verifies
+ * its SHA-256, then swaps the whole `.app` and relaunches.
+ *
+ * A signed/notarized `.app` cannot be modified in place without breaking its
+ * signature, so every update replaces the entire bundle. Updates run only in a
+ * packaged app with `release` set; in `mirin dev` (no version.json) the updater
+ * stays idle and `checkForUpdate()` resolves `null`.
+ *
+ *   import { app } from "mirinjs";
+ *   const info = await app.updater.checkForUpdate();
+ *   if (info) { await app.updater.download(p => …); await app.updater.applyAndRelaunch(); }
+ */
+
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { $ } from "bun";
+import { runtime } from "./runtime.ts";
+
+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;
+}
+
+/** A published release the running app can update to. */
+export interface UpdateInfo {
+  /** Version being offered. */
+  version: string;
+  /** The currently-running version. */
+  currentVersion: string;
+  channel: string;
+  /** Artifact filename, relative to baseUrl. */
+  url: string;
+  sha256: string;
+  size?: number;
+}
+
+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; // undefined = not yet read
+  #pending: UpdateInfo | null = null;
+  #staged: string | null = null; // path to the extracted, verified .app
+  #autoCheck: ReturnType<typeof setInterval> | undefined;
+
+  /** Subscribe to an updater event. Returns an unsubscribe function. */
+  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 this build has updates configured (packaged + `release` set). */
+  get enabled(): boolean {
+    return this.#version() != null;
+  }
+
+  /**
+   * Fetch the channel manifest and report an available update, or `null` if the
+   * app is up to date / updates aren't configured. 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 {
+        version: string;
+        url: string;
+        sha256: string;
+        size?: number;
+      };
+      if (!m.version || m.version === v.version) {
+        this.#setStatus("idle");
+        return null;
+      }
+      const info: UpdateInfo = {
+        version: m.version,
+        currentVersion: v.version,
+        channel: v.channel,
+        url: m.url,
+        sha256: m.sha256,
+        size: m.size,
+      };
+      this.#pending = info;
+      this.#setStatus("update-available");
+      this.#emit("update-available", info);
+      return info;
+    } catch (err) {
+      this.#fail(err);
+      return null;
+    }
+  }
+
+  /**
+   * Download (and verify) the pending update's bundle into the app's support
+   * dir. Emits `progress`. Call `checkForUpdate()` first.
+   */
+  async download(onProgress?: (p: UpdateProgress) => void): Promise<void> {
+    const v = this.#version();
+    if (!v || !this.#pending) throw new Error("no update to download — call checkForUpdate() first");
+    const info = this.#pending;
+    this.#setStatus("downloading");
+    try {
+      const dir = this.#updatesDir(v);
+      rmSync(dir, { recursive: true, force: true });
+      mkdirSync(dir, { recursive: true });
+
+      const url = `${v.baseUrl.replace(/\/$/, "")}/${info.url}`;
+      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") ?? info.size ?? 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);
+
+      // Integrity: the manifest's sha256 must match the downloaded artifact.
+      const got = new Bun.CryptoHasher("sha256").update(buf).digest("hex");
+      if (got !== info.sha256) {
+        throw new Error(`hash mismatch (expected ${info.sha256.slice(0, 12)}…, got ${got.slice(0, 12)}…)`);
+      }
+
+      const tarPath = join(dir, "update.tar.gz");
+      await Bun.write(tarPath, buf);
+      await $`tar -xzf ${tarPath} -C ${dir}`.quiet();
+      const staged = join(dir, `${v.name}.app`);
+      if (!existsSync(staged)) throw new Error(`extracted bundle not found at ${staged}`);
+
+      // Refuse a tampered/corrupt bundle (works for ad-hoc + Developer ID).
+      const verify = await $`codesign --verify --deep --strict ${staged}`.quiet().nothrow();
+      if (verify.exitCode !== 0) throw new Error("codesign verification failed on the downloaded update");
+
+      this.#staged = staged;
+      this.#setStatus("update-available");
+    } catch (err) {
+      this.#fail(err);
+      throw err;
+    }
+  }
+
+  /**
+   * Swap the running `.app` with the downloaded bundle and relaunch. Spawns a
+   * detached helper that waits for this process to exit, replaces the bundle,
+   * strips quarantine, and reopens the app — then quits.
+   */
+  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 {
+      const runningApp = join(this.#resourcesDir()!, "..", "..");
+      const script = [
+        `APP=${sh(runningApp)}`,
+        `NEW=${sh(this.#staged)}`,
+        `PID=${process.pid}`,
+        // Wait for the running app to fully exit before swapping.
+        `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");
+      // Quit; the detached helper does the swap + relaunch after we exit.
+      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 ----
+
+  #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; // detached (not under the host)
+    }
+  }
+
+  #prefix(): string {
+    const v = this.#version()!;
+    return `${v.channel}-darwin-${process.arch}`;
+  }
+
+  #updatesDir(v: VersionInfo): string {
+    return join(homedir(), "Library", "Application Support", v.identifier, v.channel, "updates");
+  }
+
+  #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));
+    // Bridge to webviews so frontends can react without polling.
+    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, `'\\''`)}'`;
+}
+
+export const updater = new Updater();