@n1h/sweetview 0.0.0-stage → 0.1.1

package/src/ipc/frame.ts

@@ -0,0 +1,16 @@
+// Wire frames. Every transport (WebSocket, the sweetview ring, memory) carries
+// exactly these, as JSON. The service never sees a frame; hosts do the
+// seq <-> promise correlation.
+
+/** Page -> backend. `seq: null` means fire and forget: no reply frame comes back. */
+export type CallFrame = { kind: "call"; seq: string | null; method: string; params: unknown };
+
+/** Backend -> page, answering one call. `error` is a user-safe message. */
+export type ReplyFrame =
+  | { kind: "reply"; seq: string; ok: true; result: unknown }
+  | { kind: "reply"; seq: string; ok: false; error: string };
+
+/** Backend -> page, unsolicited. */
+export type EventFrame = { kind: "event"; name: string; payload: unknown };
+
+export type Frame = CallFrame | ReplyFrame | EventFrame;

package/src/ipc/index.ts

@@ -0,0 +1,16 @@
+export type { CallFrame, EventFrame, Frame, ReplyFrame } from "./frame";
+export {
+  defineService,
+  type AnyEvent,
+  type Ctx,
+  type Emit,
+  type EventMap,
+  type Handlers,
+  type MethodMap,
+  type Service,
+  type ServiceDefinition,
+  type Session,
+  type SessionKind,
+} from "./service";
+export { createBridge, type Bridge, type Transport, type TransportKind } from "./bridge";
+export { memoryTransport } from "./memory";

package/src/ipc/memory.ts

@@ -0,0 +1,33 @@
+// A Transport straight onto a Service in the same process. For tests, and for
+// a frontend rendered in plain Bun without any host.
+
+import type { Transport } from "./bridge";
+import type { EventMap, MethodMap, Service, Session } from "./service";
+
+let nextId = 1;
+
+export function memoryTransport<M extends MethodMap, E extends EventMap>(
+  service: Service<M, E>,
+  session: Session = { id: `memory-${nextId++}`, kind: "web" },
+): Transport & { close(): void } {
+  const ctx = { session };
+  const listeners = new Set<(name: string, payload: unknown) => void>();
+  const off = service.onEvent((name, payload, to) => {
+    if (to !== undefined && to !== session.id) return;
+    for (const fn of listeners) fn(name, payload);
+  });
+  const call = (method: string, params: unknown) => service.call(method as keyof M & string, params as never, ctx);
+  return {
+    kind: session.kind,
+    call,
+    notify: (method, params) => void call(method, params).catch(() => {}),
+    onEvent(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    close() {
+      off();
+      service.endSession(session.id);
+    },
+  };
+}

package/src/ipc/service.ts

@@ -0,0 +1,75 @@
+// The backend side of the contract. A Service is transport-free: no sockets,
+// no window handles, no seq numbers. Hosts (sweetipc-ws, sweetview) wrap one.
+
+/** method name -> [params, result]. `void` params mean "no argument". */
+export type MethodMap = Record<string, [params: unknown, result: unknown]>;
+/** event name -> payload */
+export type EventMap = Record<string, unknown>;
+
+export type SessionKind = "webview" | "web";
+export type Session = { id: string; kind: SessionKind };
+export type Ctx = { session: Session };
+
+/** One event as a discriminated union, so a listener can switch on `name` and get a typed `payload`. */
+export type AnyEvent<E extends EventMap> = { [N in keyof E & string]: { name: N; payload: E[N] } }[keyof E & string];
+
+/** Send an event to every session, or to one when `to` is given. */
+export type Emit<E extends EventMap> = <N extends keyof E & string>(name: N, payload: E[N], to?: string) => void;
+
+export interface Service<M extends MethodMap, E extends EventMap> {
+  call<K extends keyof M & string>(method: K, params: M[K][0], ctx: Ctx): Promise<M[K][1]>;
+  /** Subscribe to events; returns an unsubscribe function. */
+  onEvent(fn: (name: keyof E & string, payload: E[keyof E], to?: string) => void): () => void;
+  /** A client went away: drop anything held for that session. */
+  endSession(sessionId: string): void;
+  /** The process is shutting down. */
+  dispose(): Promise<void>;
+}
+
+export type Handlers<M extends MethodMap> = {
+  [K in keyof M & string]: (params: M[K][0], ctx: Ctx) => M[K][1] | Promise<M[K][1]>;
+};
+
+export type ServiceDefinition<M extends MethodMap> = {
+  methods: Handlers<M>;
+  endSession?: (sessionId: string) => void;
+  dispose?: () => void | Promise<void>;
+};
+
+/**
+ * Build a Service from a handler table. `setup` receives `emit` so handlers
+ * and background work can push events.
+ *
+ *   export const createService = () => defineService<Methods, Events>((emit) => ({ methods: { ... } }));
+ */
+export function defineService<M extends MethodMap, E extends EventMap>(setup: (emit: Emit<E>) => ServiceDefinition<M>): Service<M, E> {
+  type Listener = (name: keyof E & string, payload: E[keyof E], to?: string) => void;
+  const listeners = new Set<Listener>();
+  const emit: Emit<E> = (name, payload, to) => {
+    for (const fn of listeners) fn(name, payload, to);
+  };
+  const def = setup(emit);
+
+  return {
+    async call(method, params, ctx) {
+      // hasOwn: a name like "constructor" or "toString" must not resolve through Object.prototype.
+      const handler = Object.hasOwn(def.methods, method) ? (def.methods[method] as (p: unknown, c: Ctx) => unknown) : undefined;
+      if (!handler) throw new Error(`unknown method ${method}`);
+      return (await handler(params, ctx)) as never;
+    },
+    onEvent(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    endSession(sessionId) {
+      def.endSession?.(sessionId);
+    },
+    async dispose() {
+      try {
+        await def.dispose?.();
+      } finally {
+        listeners.clear();
+      }
+    },
+  };
+}

package/src/ipc-ws/client.ts

@@ -0,0 +1,111 @@
+// The page side: a sweetipc Transport over one WebSocket. Calls made before
+// the socket opens are queued; when the socket closes, every pending call
+// rejects and the transport stays closed (reload the page to reconnect).
+
+import type { Frame, Transport } from "../ipc";
+
+export type WsTransport = Transport & {
+  /** Resolves once the socket is open. */
+  readonly ready: Promise<void>;
+  /** Fires once, when the socket closes for any reason. */
+  onClose(fn: () => void): () => void;
+  close(): void;
+};
+
+/** `ws://` or `wss://` to match the page's own origin, with the given path. */
+export function wsUrl(path = "/ws"): string {
+  const proto = location.protocol === "https:" ? "wss:" : "ws:";
+  return `${proto}//${location.host}${path}`;
+}
+
+export function wsTransport(url: string = wsUrl()): WsTransport {
+  const ws = new WebSocket(url);
+  const pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  const eventListeners = new Set<(name: string, payload: unknown) => void>();
+  const closeListeners = new Set<() => void>();
+  let queue: string[] = [];
+  let seq = 0;
+
+  const ready = new Promise<void>((resolve, reject) => {
+    ws.addEventListener("open", () => {
+      for (const text of queue) ws.send(text);
+      queue = [];
+      resolve();
+    });
+    ws.addEventListener("close", () => {
+      reject(new Error("websocket closed"));
+      queue = [];
+      for (const p of pending.values()) p.reject(new Error("websocket closed"));
+      pending.clear();
+      for (const fn of closeListeners) fn();
+      closeListeners.clear();
+    });
+  });
+  ready.catch(() => {}); // the rejection is reported through pending calls and onClose
+
+  ws.addEventListener("message", (e: MessageEvent) => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(String(e.data));
+    } catch {
+      return;
+    }
+    if (typeof parsed !== "object" || parsed === null) return;
+    const frame = parsed as Frame;
+    if (frame.kind === "reply") {
+      const p = pending.get(frame.seq);
+      if (!p) return;
+      pending.delete(frame.seq);
+      if (frame.ok) p.resolve(frame.result);
+      else p.reject(new Error(frame.error));
+    } else if (frame.kind === "event") {
+      for (const fn of eventListeners) fn(frame.name, frame.payload);
+    }
+  });
+
+  const send = (frame: Frame) => {
+    const text = JSON.stringify(frame);
+    if (ws.readyState === WebSocket.OPEN) ws.send(text);
+    else if (ws.readyState === WebSocket.CONNECTING) queue.push(text);
+    else throw new Error("websocket closed");
+  };
+
+  return {
+    kind: "web",
+    ready,
+    call(method, params) {
+      return new Promise((resolve, reject) => {
+        const id = String(++seq);
+        pending.set(id, { resolve, reject });
+        try {
+          send({ kind: "call", seq: id, method, params });
+        } catch (err) {
+          pending.delete(id);
+          reject(err as Error);
+        }
+      });
+    },
+    notify(method, params) {
+      try {
+        send({ kind: "call", seq: null, method, params });
+      } catch (err) {
+        console.error(`${method} not sent:`, (err as Error).message);
+      }
+    },
+    onEvent(fn) {
+      eventListeners.add(fn);
+      return () => eventListeners.delete(fn);
+    },
+    onClose(fn) {
+      if (ws.readyState === WebSocket.CLOSED) {
+        fn();
+        return () => {};
+      }
+      closeListeners.add(fn);
+      return () => closeListeners.delete(fn);
+    },
+    close() {
+      ws.close();
+    },
+  };
+}

package/src/ipc-ws/index.ts

@@ -0,0 +1,5 @@
+// Import "@n1h/sweetview/ipc-ws/server" from Bun code and "@n1h/sweetview/ipc-ws/client" from the
+// page; this root re-exports both for convenience in code that is bundled
+// for one side only.
+export { wsHost, type WsData, type WsHost, type WsHostOptions } from "./server";
+export { wsTransport, wsUrl, type WsTransport } from "./client";

package/src/ipc-ws/server.ts

@@ -0,0 +1,133 @@
+// Hosts a Service behind Bun.serve's websocket handler. One session per
+// socket; events are broadcast, or sent to one session when `to` is set.
+//
+//   const host = wsHost(createService());
+//   Bun.serve({
+//     fetch(req, server) {
+//       if (new URL(req.url).pathname === "/ws") return host.upgrade(req, server) ? undefined : new Response("upgrade failed", { status: 400 });
+//       ...
+//     },
+//     websocket: host.websocket,
+//   });
+
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import type { CallFrame, EventMap, Frame, MethodMap, ReplyFrame, Service, Session } from "../ipc";
+
+export type WsData = { session: Session };
+
+export type WsHostOptions = {
+  /**
+   * Which `Origin` values may connect. Browsers do not apply same-origin to
+   * WebSockets, so without this any page the user has open could talk to the
+   * service. Default: only the page's own origin (Origin host matches the
+   * request's Host). Pass a list of origins, or a predicate.
+   */
+  allowOrigin?: string[] | ((origin: string, req: Request) => boolean);
+};
+
+export type WsHost = {
+  /** Upgrade a request to a session; returns false when it was not a websocket request or its Origin is not allowed. */
+  upgrade(req: Request, server: Server<WsData>): boolean;
+  websocket: WebSocketHandler<WsData>;
+  /** Number of live sessions. */
+  readonly sessions: number;
+  /** Close every socket and stop forwarding events. Does not dispose the service. */
+  close(): void;
+};
+
+export function wsHost<M extends MethodMap, E extends EventMap>(service: Service<M, E>, options: WsHostOptions = {}): WsHost {
+  const sockets = new Map<string, ServerWebSocket<WsData>>();
+  let nextId = 1;
+
+  const originAllowed = (req: Request): boolean => {
+    const origin = req.headers.get("origin");
+    if (origin === null) return true; // not a browser
+    const { allowOrigin } = options;
+    if (typeof allowOrigin === "function") return allowOrigin(origin, req);
+    if (allowOrigin) return allowOrigin.includes(origin);
+    try {
+      return new URL(origin).host === req.headers.get("host");
+    } catch {
+      return false;
+    }
+  };
+
+  const send = (ws: ServerWebSocket<WsData>, frame: Frame) => {
+    let text: string;
+    try {
+      text = JSON.stringify(frame);
+    } catch (err) {
+      // a result or payload JSON cannot carry (a BigInt, a cycle): the page gets an error reply instead of silence
+      if (frame.kind === "reply") text = JSON.stringify({ kind: "reply", seq: frame.seq, ok: false, error: `${frame.seq}: the result is not serialisable: ${(err as Error).message}` } satisfies ReplyFrame);
+      else {
+        console.error(`${frame.kind === "event" ? `event ${frame.name}` : "frame"} is not serialisable:`, (err as Error).message);
+        return;
+      }
+    }
+    ws.send(text);
+  };
+
+  const off = service.onEvent((name, payload, to) => {
+    const frame: Frame = { kind: "event", name, payload };
+    if (to !== undefined) {
+      const ws = sockets.get(to);
+      if (ws) send(ws, frame);
+      return;
+    }
+    for (const ws of sockets.values()) send(ws, frame);
+  });
+
+  const websocket: WebSocketHandler<WsData> = {
+    open(ws) {
+      sockets.set(ws.data.session.id, ws);
+    },
+    async message(ws, raw) {
+      let frame: unknown;
+      try {
+        frame = JSON.parse(typeof raw === "string" ? raw : new TextDecoder().decode(raw));
+      } catch {
+        return; // not ours
+      }
+      // anything that is not a call frame is ignored, including `null` and other non-objects
+      if (typeof frame !== "object" || frame === null || (frame as Frame).kind !== "call") return;
+      const reply = await handle(frame as CallFrame, ws.data.session);
+      if (reply && sockets.get(ws.data.session.id) === ws) send(ws, reply);
+    },
+    close(ws) {
+      const id = ws.data.session.id;
+      if (sockets.get(id) === ws) sockets.delete(id);
+      service.endSession(id);
+    },
+  };
+
+  async function handle(frame: CallFrame, session: Session): Promise<ReplyFrame | null> {
+    try {
+      const result = await service.call(frame.method as keyof M & string, frame.params as never, { session });
+      return frame.seq === null ? null : { kind: "reply", seq: frame.seq, ok: true, result };
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      if (frame.seq === null) {
+        console.error(`${frame.method} failed:`, error);
+        return null;
+      }
+      return { kind: "reply", seq: frame.seq, ok: false, error };
+    }
+  }
+
+  return {
+    upgrade(req, server) {
+      if (!originAllowed(req)) return false;
+      const session: Session = { id: `ws-${nextId++}`, kind: "web" };
+      return server.upgrade(req, { data: { session } });
+    },
+    websocket,
+    get sessions() {
+      return sockets.size;
+    },
+    close() {
+      off();
+      for (const ws of sockets.values()) ws.close();
+      sockets.clear();
+    },
+  };
+}

package/src/make-app.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+// The macOS .app bundle around a compiled sweetview binary, from the command
+// line. The same thing as a function is `makeMacApp` in "@n1h/sweetview/build".
+// Runs on any OS: it only writes files.
+//
+//   bun src/make-app.ts --name "My App" --bundle-id dev.example.my-app \
+//     --binary dist/my-app-macos-arm64 --out dist [--icns build/AppIcon.icns] \
+//     [--version 1.0.0] [--min-macos 11.0] [--plist LSUIElement=true]
+
+import { parseArgs } from "node:util";
+import { makeMacApp, type MacAppOptions } from "./build";
+
+const USAGE = `usage: bun src/make-app.ts --name <name> --bundle-id <id> --binary <path> --out <dir>
+                          [--icns <path>] [--version <x.y.z>] [--min-macos <x.y>] [--plist <Key=value>]...
+
+  --name       what Finder and the Dock show; the bundle is <name>.app
+  --bundle-id  reverse-DNS id (dev.example.my-app); macOS notifications need one
+  --binary     the compiled macOS executable (bun build --compile --target=bun-darwin-arm64)
+  --out        folder the bundle is written into; an existing <name>.app there is replaced
+  --icns       the .icns for Finder and the Dock (sweetview/build writeIconFiles); stock icon without it
+  --version    CFBundleVersion and CFBundleShortVersionString (default 0.1.0)
+  --min-macos  LSMinimumSystemVersion (default 11.0)
+  --plist      an extra Info.plist entry; true/false and numbers are typed, anything else is a string. Repeatable
+`;
+
+const SPEC = {
+  name: { type: "string" },
+  "bundle-id": { type: "string" },
+  binary: { type: "string" },
+  out: { type: "string" },
+  icns: { type: "string" },
+  version: { type: "string" },
+  "min-macos": { type: "string" },
+  plist: { type: "string", multiple: true },
+  help: { type: "boolean", short: "h" },
+} as const;
+
+function parse(argv: string[]) {
+  try {
+    return parseArgs({ args: argv, options: SPEC, strict: true }).values;
+  } catch (err) {
+    console.error((err as Error).message);
+    console.error(USAGE);
+    return undefined;
+  }
+}
+
+function main(argv: string[]): number {
+  const args = parse(argv);
+  if (args === undefined) return 2;
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  const missing = (["name", "bundle-id", "binary", "out"] as const).filter((k) => args[k] === undefined || args[k] === "");
+  if (missing.length > 0) {
+    console.error(`missing: ${missing.map((k) => `--${k}`).join(", ")}`);
+    console.error(USAGE);
+    return 2;
+  }
+
+  const plist: Record<string, string | number | boolean> = {};
+  for (const entry of args.plist ?? []) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0) {
+      console.error(`--plist wants Key=value, got ${JSON.stringify(entry)}`);
+      return 2;
+    }
+    const key = entry.slice(0, eq);
+    const raw = entry.slice(eq + 1);
+    plist[key] = raw === "true" ? true : raw === "false" ? false : raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : raw;
+  }
+
+  const options: MacAppOptions = {
+    name: args.name!,
+    bundleId: args["bundle-id"]!,
+    binary: args.binary!,
+    outDir: args.out!,
+    ...(args.icns !== undefined ? { icns: args.icns } : {}),
+    ...(args.version !== undefined ? { version: args.version } : {}),
+    ...(args["min-macos"] !== undefined ? { minimumSystemVersion: args["min-macos"] } : {}),
+    ...(Object.keys(plist).length > 0 ? { plist } : {}),
+  };
+  try {
+    console.log(`wrote ${makeMacApp(options)}`);
+    return 0;
+  } catch (err) {
+    console.error((err as Error).message);
+    return 1;
+  }
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)));

package/src/messages.ts

@@ -0,0 +1,16 @@
+// What crosses worker.postMessage, UI thread -> worker. The other direction
+// (worker -> UI thread) is sweetipc frames in the ring.
+
+import type { CallFrame } from "./ipc";
+
+export type InitMessage = {
+  kind: "init";
+  ring: SharedArrayBuffer;
+  webviewHandle: number;
+  drainCallbackPtr: number;
+  libPath: string;
+};
+
+export type WorkerMessage = InitMessage | CallFrame;
+
+export const WEBVIEW_SESSION = { id: "webview", kind: "webview" } as const;

package/src/native/app-icon.ts

@@ -0,0 +1,23 @@
+// The application's own icon, as the OS shows the running app.
+//
+// macOS: the Dock tile and the Cmd+Tab switcher (NSApplication's
+// applicationIconImage). Replaces what the bundle's CFBundleIconFile set, or
+// the generic icon for a bare executable.
+//
+// Windows: nothing to set at run time. Explorer, the taskbar and Alt+Tab take
+// the icon from the executable's resources (`bun build --compile
+// --windows-icon=app.ico`) and from each window (`NativeWindow.setIcon`,
+// `OverlayWindowOptions.icon`).
+
+import type { Icon } from "./icon";
+import { backend } from "./platform";
+
+type Backend = { setAppIcon(icon: Icon): void };
+const impl = backend<Backend>(
+  () => require("./win32/app-icon"),
+  () => require("./darwin/app-icon"),
+);
+
+export function setAppIcon(icon: Icon): void {
+  impl().setAppIcon(icon);
+}

package/src/native/app-menu.ts

@@ -0,0 +1,18 @@
+// The application's menu bar. macOS: an app menu (About, Quit) and an Edit
+// menu, because webview creates NSApplication without one and Cmd+Q / Cmd+C /
+// Cmd+V do nothing otherwise. Windows: nothing; the tray menu is the menu.
+
+import { backend } from "./platform";
+
+export type AppMenuOptions = { appName: string; aboutText: string };
+
+type Backend = { installAppMenu(options: AppMenuOptions): void };
+const impl = backend<Backend>(
+  () => require("./win32/app-menu"),
+  () => require("./darwin/app-menu"),
+);
+
+/** Call on the UI thread before the run loop starts. */
+export function installAppMenu(options: AppMenuOptions): void {
+  impl().installAppMenu(options);
+}

package/src/native/darwin/app-icon.ts

@@ -0,0 +1,10 @@
+// Dock tile and Cmd+Tab icon: NSApplication.applicationIconImage. Full colour
+// (not a template) at the PNG's own size; 512px or 1024px looks right in the Dock.
+
+import type { Icon } from "../icon";
+import { applyImage, makeImage } from "./image";
+import { sharedApp } from "./objc";
+
+export function setAppIcon(icon: Icon): void {
+  applyImage(sharedApp(), "setApplicationIconImage:", makeImage(icon.macos, undefined, false));
+}

package/src/native/darwin/app-menu.ts

@@ -0,0 +1,88 @@
+// macOS main menu. webview creates an NSApplication with no mainMenu, so there
+// is no app menu, no Quit, and Cmd+Q / Cmd+C / Cmd+V do nothing. Build the
+// standard minimum: app menu (About…, Quit) and an Edit menu so text editing
+// shortcuts reach the webview. Call on the main thread before webview.run().
+
+import type { AppMenuOptions } from "../app-menu";
+import {
+  NIL,
+  type Id,
+  alloc,
+  allocRaw,
+  asId,
+  cls,
+  makeTarget,
+  nsString,
+  release,
+  sel,
+  send,
+  sendInt,
+  sendIntRetBool,
+  sendPtr,
+  sendPtrSelPtr,
+  sharedApp,
+} from "./objc";
+
+const NSApplicationActivationPolicyRegular = 0n;
+
+type Item = [title: string, action: string, key: string, target?: Id] | "separator";
+
+function menuItem(title: string, action: string, key: string, target?: Id): Id {
+  const it = allocRaw("NSMenuItem");
+  const inited = sendPtrSelPtr(it, sel("initWithTitle:action:keyEquivalent:"), nsString(title), sel(action), nsString(key));
+  const id = inited === null ? NIL : BigInt(inited);
+  if (target !== undefined) sendPtr(id, sel("setTarget:"), target);
+  return id;
+}
+
+function submenu(parent: Id, title: string, items: Item[]) {
+  const holder = alloc("NSMenuItem");
+  sendPtr(parent, sel("addItem:"), holder);
+  const menu = asId(sendPtr(allocRaw("NSMenu"), sel("initWithTitle:"), nsString(title)));
+  for (const it of items) {
+    if (it === "separator") {
+      sendPtr(menu, sel("addItem:"), asId(send(cls("NSMenuItem"), sel("separatorItem"))));
+      continue;
+    }
+    const item = menuItem(...it);
+    sendPtr(menu, sel("addItem:"), item);
+    release(item); // the menu retains it
+  }
+  sendPtr(holder, sel("setSubmenu:"), menu);
+  release(menu); // the holder retains it
+  release(holder); // the parent retains it
+}
+
+function showAbout(appName: string, text: string) {
+  const alert = alloc("NSAlert");
+  sendPtr(alert, sel("setMessageText:"), nsString(`About ${appName}`));
+  sendPtr(alert, sel("setInformativeText:"), nsString(text));
+  sendPtr(alert, sel("addButtonWithTitle:"), nsString("OK"));
+  sendInt(alert, sel("runModal"));
+  release(alert);
+}
+
+export function installAppMenu(opts: AppMenuOptions) {
+  const app = sharedApp();
+  sendIntRetBool(app, sel("setActivationPolicy:"), NSApplicationActivationPolicyRegular);
+
+  const target = makeTarget("SweetviewAppMenuTarget", {
+    "showAbout:": () => showAbout(opts.appName, opts.aboutText),
+  });
+
+  const menubar = alloc("NSMenu");
+  submenu(menubar, opts.appName, [
+    [`About ${opts.appName}…`, "showAbout:", "", target],
+    "separator",
+    [`Quit ${opts.appName}`, "terminate:", "q"],
+  ]);
+  submenu(menubar, "Edit", [
+    ["Undo", "undo:", "z"],
+    ["Redo", "redo:", "Z"],
+    ["Cut", "cut:", "x"],
+    ["Copy", "copy:", "c"],
+    ["Paste", "paste:", "v"],
+    ["Select All", "selectAll:", "a"],
+  ]);
+  sendPtr(app, sel("setMainMenu:"), menubar);
+}

package/src/native/darwin/folder-picker.ts

@@ -0,0 +1,29 @@
+// Native macOS folder picker: NSOpenPanel through the Objective-C runtime via
+// bun:ffi. No child process. Must run on the main thread (AppKit rule), which
+// the webview UI thread is. See objc.ts for the id-as-bigint rule.
+
+import type { WindowHandle } from "../window";
+import { NIL, asId, cls, jsString, nsString, sel, send, sendBool, sendInt, sendPtr, sharedApp } from "./objc";
+
+const NSModalResponseOK = 1n;
+
+/** Opens NSOpenPanel in folder mode (app-modal; `owner` is not used). Returns the POSIX path, or null if cancelled. */
+export function pickFolder(_owner: WindowHandle, title: string): string | null {
+  sendBool(sharedApp(), sel("activateIgnoringOtherApps:"), true);
+
+  const panel = asId(send(cls("NSOpenPanel"), sel("openPanel")));
+  if (panel === NIL) throw new Error("NSOpenPanel.openPanel returned nil");
+  sendBool(panel, sel("setCanChooseDirectories:"), true);
+  sendBool(panel, sel("setCanChooseFiles:"), false);
+  sendBool(panel, sel("setAllowsMultipleSelection:"), false);
+  sendBool(panel, sel("setCanCreateDirectories:"), true);
+  sendPtr(panel, sel("setMessage:"), nsString(title));
+  sendPtr(panel, sel("setPrompt:"), nsString("Choose"));
+
+  if (BigInt(sendInt(panel, sel("runModal")) ?? 0) !== NSModalResponseOK) return null;
+
+  const url = asId(send(asId(send(panel, sel("URLs"))), sel("firstObject")));
+  if (url === NIL) return null;
+  const path = asId(send(url, sel("path")));
+  return path === NIL ? null : jsString(path);
+}