@n1h/sweetview 0.0.0-stage → 0.1.1

package/src/native/win32/tray.ts

@@ -0,0 +1,228 @@
+// Notification-area icon: Shell_NotifyIcon on a hidden message window.
+// Right click pops the menu; left double click fires onDoubleClick; a left
+// click that is not followed by a second one within GetDoubleClickTime fires
+// onClick. The single/double distinction uses a Win32 timer on the message
+// window rather than setTimeout, because Bun's event loop does not tick while
+// the webview's run loop owns the thread.
+
+import { resolveMenu } from "../menu";
+import type { MenuSource } from "../menu";
+import type { NotificationOptions } from "../notifications";
+import type { Tray, TrayOptions } from "../tray";
+import {
+  SM_CXICON,
+  WM_APP,
+  WM_LBUTTONDBLCLK,
+  WM_LBUTTONUP,
+  WM_RBUTTONUP,
+  WM_TIMER,
+  lastError,
+  shell32,
+  user32,
+  wstr,
+} from "./api";
+import { loadIcon, releaseIcon } from "./icon";
+import { popupMenuAtCursor } from "./menu";
+import { createMessageWindow } from "./message-window";
+
+const WM_TRAYICON = WM_APP + 1;
+const CLICK_TIMER_ID = 1n;
+
+const NIM_ADD = 0;
+const NIM_MODIFY = 1;
+const NIM_DELETE = 2;
+const NIF_MESSAGE = 0x1;
+const NIF_ICON = 0x2;
+const NIF_TIP = 0x4;
+const NIF_INFO = 0x10;
+
+// dwInfoFlags
+const NIIF_INFO = 0x1;
+const NIIF_USER = 0x4;
+const NIIF_NOSOUND = 0x10;
+const NIIF_LARGE_ICON = 0x20;
+const NIIF_RESPECT_QUIET_TIME = 0x80;
+
+// Balloon callbacks in the low word of lParam.
+const NIN_BALLOONUSERCLICK = 0x0405;
+
+// NOTIFYICONDATAW, x64, current version (sizeof = 976).
+export const NID_SIZE = 976;
+export const NID_HWND = 8;
+export const NID_UID = 16;
+export const NID_FLAGS = 20;
+export const NID_CALLBACK = 24;
+export const NID_HICON = 32;
+export const NID_TIP = 40; // WCHAR[128]
+export const NID_INFO = 304; // WCHAR[256]
+export const NID_INFO_TITLE = 820; // WCHAR[64]
+export const NID_INFO_FLAGS = 948;
+export const NID_BALLOON_ICON = 968;
+
+let nextUid = 1;
+let taskbarCreated: number | undefined;
+
+/**
+ * The Windows tray, as the rest of this folder sees it: the public Tray plus
+ * the balloon channel the notifier uses. Not exported from the package.
+ */
+export interface Win32Tray extends Tray {
+  readonly balloon: {
+    /** Shows a balloon (a toast on Windows 10/11). False once the tray is disposed or when the shell refuses. */
+    show(n: NotificationOptions): boolean;
+    onClick(fn: (() => void) | undefined): void;
+  };
+}
+
+let active: Win32Tray | undefined;
+/** The most recently created tray that has not been disposed. */
+export const currentTray = (): Win32Tray | undefined => active;
+
+/** Copies `value` into a fixed WCHAR[wchars] field, truncated so the NUL still fits. */
+const setWide = (nid: Uint8Array, offset: number, value: string, wchars: number) => {
+  const bytes = wstr(value);
+  nid.set(bytes.subarray(0, Math.min(bytes.length, (wchars - 1) * 2)), offset);
+};
+
+export type Balloon = { title: string; body: string; silent: boolean; hIcon: bigint };
+
+/** The NOTIFYICONDATAW for the icon itself, plus a balloon (Windows 10/11 shows it as a toast) when given. */
+export function notifyIconData(hwnd: bigint, uid: number, hIcon: bigint, tip: string, balloon?: Balloon): Uint8Array {
+  const nid = new Uint8Array(NID_SIZE);
+  const dv = new DataView(nid.buffer);
+  dv.setUint32(0, NID_SIZE, true);
+  dv.setBigUint64(NID_HWND, hwnd, true);
+  dv.setUint32(NID_UID, uid, true);
+  dv.setUint32(NID_FLAGS, NIF_MESSAGE | NIF_ICON | NIF_TIP | (balloon ? NIF_INFO : 0), true);
+  dv.setUint32(NID_CALLBACK, WM_TRAYICON, true);
+  dv.setBigUint64(NID_HICON, hIcon, true);
+  setWide(nid, NID_TIP, tip, 128);
+  if (balloon) {
+    setWide(nid, NID_INFO, balloon.body, 256);
+    setWide(nid, NID_INFO_TITLE, balloon.title, 64);
+    const ownIcon = balloon.hIcon !== 0n;
+    let flags = (ownIcon ? NIIF_USER | NIIF_LARGE_ICON : NIIF_INFO) | NIIF_RESPECT_QUIET_TIME;
+    if (balloon.silent) flags |= NIIF_NOSOUND;
+    dv.setUint32(NID_INFO_FLAGS, flags, true);
+    dv.setBigUint64(NID_BALLOON_ICON, balloon.hIcon, true);
+  }
+  return nid;
+}
+
+export function createTray(options: TrayOptions): Win32Tray {
+  const uid = nextUid++;
+  let icon = loadIcon(options.icon?.windows?.ico);
+  let balloonIcon = loadIcon(options.icon?.windows?.ico, SM_CXICON); // toasts want the 32px image
+  let tooltip = options.tooltip ?? "";
+  let balloonClick: (() => void) | undefined;
+  let menu: MenuSource | undefined = options.menu;
+  let disposed = false;
+  let menuOpen = false;
+  // A double click arrives as DOWN, UP, DBLCLK, UP: the trailing UP must not start the single-click timer.
+  let swallowNextUp = false;
+
+  taskbarCreated ??= user32.RegisterWindowMessageW(wstr("TaskbarCreated"));
+
+  const window = createMessageWindow((message, wParam, lParam) => {
+    if (message === WM_TRAYICON && Number(wParam) === uid) {
+      onTrayMessage(Number(lParam) & 0xffff);
+    } else if (message === WM_TIMER && wParam === CLICK_TIMER_ID) {
+      user32.KillTimer(window.hwnd, CLICK_TIMER_ID);
+      options.onClick?.();
+    } else if (message === taskbarCreated && !disposed) {
+      sync(NIM_ADD); // Explorer restarted and dropped every icon
+    }
+  });
+
+  const sync = (op: number, balloon?: Balloon) => {
+    const nid = notifyIconData(window.hwnd, uid, icon.handle, tooltip, balloon);
+    const ok = shell32.Shell_NotifyIconW(op, nid);
+    if (!ok && balloon) console.error(`sweetnative: Shell_NotifyIcon balloon failed (${lastError()})`);
+    // NIM_ADD fails with ERROR_TIMEOUT while Explorer is still starting (login autostart);
+    // the TaskbarCreated broadcast that follows re-adds the icon, so do not throw.
+    if (!ok && op === NIM_ADD) console.error(`sweetnative: Shell_NotifyIcon(NIM_ADD) failed (${lastError()}); waiting for TaskbarCreated`);
+  };
+
+  const onTrayMessage = (mouse: number) => {
+    switch (mouse) {
+      case NIN_BALLOONUSERCLICK:
+        balloonClick?.();
+        return;
+      case WM_RBUTTONUP: {
+        if (menuOpen || menu === undefined) return;
+        const template = resolveMenu(menu);
+        if (template.length === 0) return;
+        menuOpen = true;
+        try {
+          popupMenuAtCursor(window.hwnd, template);
+        } finally {
+          menuOpen = false;
+        }
+        return;
+      }
+      case WM_LBUTTONUP:
+        if (swallowNextUp) {
+          swallowNextUp = false;
+          return;
+        }
+        // Wait one double-click interval before calling it a single click.
+        if (options.onClick) user32.SetTimer(window.hwnd, CLICK_TIMER_ID, user32.GetDoubleClickTime(), null);
+        return;
+      case WM_LBUTTONDBLCLK:
+        user32.KillTimer(window.hwnd, CLICK_TIMER_ID);
+        swallowNextUp = true;
+        options.onDoubleClick?.();
+        return;
+    }
+  };
+
+  sync(NIM_ADD);
+
+  const tray: Win32Tray = {
+    balloon: {
+      show(n) {
+        if (disposed) return false;
+        // Only an icon we created is safe to hand over as hBalloonIcon; the stock one gets the info glyph.
+        const hIcon = balloonIcon.owned ? balloonIcon.handle : 0n;
+        const nid = notifyIconData(window.hwnd, uid, icon.handle, tooltip, { title: n.title, body: n.body ?? "", silent: n.silent === true, hIcon });
+        const ok = shell32.Shell_NotifyIconW(NIM_MODIFY, nid) !== 0;
+        if (!ok) console.error(`sweetnative: Shell_NotifyIcon balloon failed (${lastError()})`);
+        return ok;
+      },
+      onClick(fn) {
+        balloonClick = fn;
+      },
+    },
+    setTooltip(text) {
+      if (disposed) return;
+      tooltip = text;
+      sync(NIM_MODIFY);
+    },
+    setIcon(next) {
+      if (disposed) return;
+      const previous = icon;
+      const previousBalloon = balloonIcon;
+      icon = loadIcon(next.windows?.ico);
+      balloonIcon = loadIcon(next.windows?.ico, SM_CXICON);
+      sync(NIM_MODIFY);
+      releaseIcon(previous);
+      releaseIcon(previousBalloon);
+    },
+    setMenu(next) {
+      menu = next;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      user32.KillTimer(window.hwnd, CLICK_TIMER_ID);
+      sync(NIM_DELETE);
+      window.destroy();
+      releaseIcon(icon);
+      releaseIcon(balloonIcon);
+      if (active === tray) active = undefined;
+    },
+  };
+
+  active = tray;
+  return tray;
+}

package/src/native/win32/window.ts

@@ -0,0 +1,77 @@
+// Show/hide and close interception for a window someone else created (the
+// webview's). The close hook subclasses the window procedure with comctl32's
+// SetWindowSubclass, so the webview's own procedure stays in the chain for
+// everything but WM_CLOSE.
+
+import { FFIType, JSCallback } from "bun:ffi";
+import type { NativeWindow, WindowHandle } from "../window";
+import { SW_HIDE, SW_RESTORE, SW_SHOW, WM_CLOSE, WM_NCDESTROY, comctl32, user32 } from "./api";
+import { setWindowIcon } from "./icon";
+
+export const asHwnd = (handle: WindowHandle): bigint => {
+  if (handle === null || handle === 0 || handle === 0n) throw new Error("sweetnative: window handle is NULL");
+  return BigInt(handle);
+};
+
+const SUBCLASS_ID = 0x4e53n; // "NS"
+const closeHandlers = new Map<bigint, () => void>();
+
+// One SUBCLASSPROC for every window we hook, retained for the process.
+let subclassProc: JSCallback | undefined;
+const proc = () =>
+  (subclassProc ??= new JSCallback(
+    (hwnd: bigint, message: number, wParam: bigint, lParam: bigint, _id: bigint, _ref: bigint): bigint => {
+      const handler = closeHandlers.get(hwnd);
+      if (message === WM_CLOSE && handler !== undefined) {
+        try {
+          handler();
+        } catch (err) {
+          console.error("sweetnative: close handler threw:", err);
+        }
+        return 0n; // handled: the window stays
+      }
+      if (message === WM_NCDESTROY) {
+        // The window is going away for real (quit); leave the chain cleanly.
+        closeHandlers.delete(hwnd);
+        comctl32.RemoveWindowSubclass(hwnd, proc().ptr, SUBCLASS_ID);
+      }
+      return comctl32.DefSubclassProc(hwnd, message, wParam, lParam);
+    },
+    { args: [FFIType.u64, FFIType.u32, FFIType.u64, FFIType.i64, FFIType.u64, FFIType.u64], returns: FFIType.i64 },
+  ));
+
+export function nativeWindow(handle: WindowHandle): NativeWindow {
+  const hwnd = asHwnd(handle);
+  const self: NativeWindow = {
+    isVisible: () => user32.IsWindowVisible(hwnd) !== 0,
+    show() {
+      user32.ShowWindow(hwnd, user32.IsIconic(hwnd) ? SW_RESTORE : SW_SHOW);
+      user32.SetForegroundWindow(hwnd);
+    },
+    hide() {
+      user32.ShowWindow(hwnd, SW_HIDE);
+    },
+    toggle() {
+      if (self.isVisible()) self.hide();
+      else self.show();
+    },
+    setIcon(icon) {
+      setWindowIcon(hwnd, icon?.windows?.ico);
+    },
+    onCloseRequest(handler) {
+      if (!closeHandlers.has(hwnd)) {
+        // SetWindowSubclass on an already-subclassed (hwnd, proc, id) just updates refData.
+        if (!comctl32.SetWindowSubclass(hwnd, proc().ptr, SUBCLASS_ID, 0n)) {
+          throw new Error("sweetnative: SetWindowSubclass failed");
+        }
+      }
+      closeHandlers.set(hwnd, handler);
+      return () => {
+        if (closeHandlers.get(hwnd) !== handler) return;
+        closeHandlers.delete(hwnd);
+        comctl32.RemoveWindowSubclass(hwnd, proc().ptr, SUBCLASS_ID);
+      };
+    },
+  };
+  return self;
+}

package/src/native/window.ts

@@ -0,0 +1,40 @@
+// Control of a window someone else created (the webview's): show, hide, and
+// what the close button does.
+
+import type { Pointer } from "bun:ffi";
+import type { Icon } from "./icon";
+import { backend } from "./platform";
+
+/** A native window handle as the webview hands it out (HWND on Windows, NSWindow* on macOS). */
+export type WindowHandle = Pointer | bigint | number | null;
+
+export interface NativeWindow {
+  isVisible(): boolean;
+  /** Shows, un-minimises and brings to the front. */
+  show(): void;
+  hide(): void;
+  toggle(): void;
+  /**
+   * Windows: the title bar, taskbar and Alt+Tab icon for this window, from
+   * `icon.windows.ico`; undefined restores the stock one. macOS: no-op, a
+   * window has no icon of its own there; `setAppIcon` sets the Dock's.
+   */
+  setIcon(icon: Icon | undefined): void;
+  /**
+   * Replaces what the window's close button does (destroy the window, which
+   * ends the app) with `handler`, typically `hide`. Returns a function that
+   * restores the default. Only the close button is intercepted; quitting
+   * through a menu still works.
+   */
+  onCloseRequest(handler: () => void): () => void;
+}
+
+type Backend = { nativeWindow(handle: WindowHandle): NativeWindow };
+const impl = backend<Backend>(
+  () => require("./win32/window"),
+  () => require("./darwin/window"),
+);
+
+export function nativeWindow(handle: WindowHandle): NativeWindow {
+  return impl().nativeWindow(handle);
+}

package/src/page.ts

@@ -0,0 +1,48 @@
+// Page side. Safe to import in browser code: no Bun, no FFI.
+//
+// The UI thread binds `__sweetview_rpc(method, params)` into the page with
+// webview_bind, and delivers events by evaluating `__sweetview_emit(name,
+// payload)`, which this module installs.
+
+import type { Transport } from "./ipc";
+
+declare global {
+  interface Window {
+    __sweetview_rpc?: (method: string, params: unknown) => Promise<unknown>;
+    __sweetview_emit?: (name: string, payload: unknown) => void;
+  }
+}
+
+/** True when the page is running inside a sweetview window. */
+export const isWebview = (): boolean => typeof window !== "undefined" && typeof window.__sweetview_rpc === "function";
+
+// One emit global per page, shared by every transport created on it.
+const listeners = new Set<(name: string, payload: unknown) => void>();
+
+export function webviewTransport(): Transport {
+  const rpc = typeof window !== "undefined" ? window.__sweetview_rpc : undefined;
+  if (!rpc) throw new Error("not running inside sweetview");
+  window.__sweetview_emit ??= (name, payload) => {
+    for (const fn of listeners) fn(name, payload);
+  };
+
+  const call = (method: string, params: unknown) =>
+    rpc(method, params).then(
+      (r) => r,
+      (e: unknown) => {
+        // webview rejects with the JSON passed to webview_return(status=1): { message }
+        const message = typeof e === "object" && e && "message" in e ? String((e as { message: unknown }).message) : String(e);
+        throw new Error(message);
+      },
+    );
+
+  return {
+    kind: "webview",
+    call,
+    notify: (method, params) => void call(method, params).catch((e: Error) => console.error(`${method} failed:`, e.message)),
+    onEvent(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+}

package/src/ring.ts

@@ -0,0 +1,110 @@
+// Single-producer / single-consumer byte ring over a SharedArrayBuffer.
+//
+// Producer: the worker (Bun event loop). Consumer: the UI thread, inside a
+// webview_dispatch callback. Frames are length-prefixed. The producer blocks
+// (Atomics.wait) only when the ring is full; the consumer never blocks.
+//
+// Header (Int32, shared): [0] write cursor, [1] read cursor, [2] wakeup pending.
+// Cursors grow monotonically and wrap in int32; all arithmetic is done with
+// `| 0` so the wrap is harmless.
+
+const HEADER_BYTES = 16;
+const WRITE = 0;
+const READ = 1;
+const PENDING = 2;
+
+export class Ring {
+  readonly #hdr: Int32Array;
+  readonly #data: Uint8Array;
+  readonly #cap: number;
+
+  /** `capacity` must be a power of two: the cursors wrap in int32 and `pos % capacity` only stays continuous across that wrap when capacity divides 2^32. */
+  static create(capacity: number): SharedArrayBuffer {
+    Ring.#checkCapacity(capacity);
+    return new SharedArrayBuffer(HEADER_BYTES + capacity);
+  }
+
+  constructor(sab: SharedArrayBuffer) {
+    this.#hdr = new Int32Array(sab, 0, HEADER_BYTES / 4);
+    this.#data = new Uint8Array(sab, HEADER_BYTES);
+    this.#cap = this.#data.length;
+    Ring.#checkCapacity(this.#cap);
+  }
+
+  static #checkCapacity(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity < 16 || (capacity & (capacity - 1)) !== 0 || capacity > 1 << 30) {
+      throw new RangeError(`ring capacity must be a power of two between 16 and 2^30, got ${capacity}`);
+    }
+  }
+
+  get capacity() {
+    return this.#cap;
+  }
+
+  /** Producer side. Blocks while the ring is full. */
+  write(bytes: Uint8Array): void {
+    const need = 4 + bytes.length;
+    if (need > this.#cap) throw new RangeError(`frame of ${bytes.length} bytes exceeds ring capacity ${this.#cap}`);
+    for (;;) {
+      const w = Atomics.load(this.#hdr, WRITE);
+      const r = Atomics.load(this.#hdr, READ);
+      if (((w - r) | 0) + need <= this.#cap) break;
+      Atomics.wait(this.#hdr, READ, r);
+    }
+    const w = Atomics.load(this.#hdr, WRITE);
+    const len = new Uint8Array(4);
+    new DataView(len.buffer).setUint32(0, bytes.length, true);
+    this.#put(w, len);
+    this.#put((w + 4) | 0, bytes);
+    Atomics.store(this.#hdr, WRITE, (w + need) | 0);
+  }
+
+  /**
+   * Producer side. Returns true when the caller should wake the consumer
+   * (no wakeup is already in flight), so a burst costs one dispatch.
+   */
+  claimWakeup(): boolean {
+    return Atomics.compareExchange(this.#hdr, PENDING, 0, 1) === 0;
+  }
+
+  /** Consumer side. Call first thing in the wakeup, before draining. */
+  acknowledgeWakeup(): void {
+    Atomics.store(this.#hdr, PENDING, 0);
+  }
+
+  /** Consumer side. Yields every complete frame currently in the ring. */
+  *drain(): Generator<Uint8Array> {
+    let r = Atomics.load(this.#hdr, READ);
+    const w = Atomics.load(this.#hdr, WRITE);
+    while (r !== w) {
+      const lenBytes = this.#get(r, 4);
+      const len = new DataView(lenBytes.buffer, lenBytes.byteOffset).getUint32(0, true);
+      const frame = this.#get((r + 4) | 0, len);
+      r = (r + 4 + len) | 0;
+      Atomics.store(this.#hdr, READ, r);
+      Atomics.notify(this.#hdr, READ);
+      yield frame;
+    }
+  }
+
+  #offset(pos: number) {
+    const m = pos % this.#cap;
+    return m < 0 ? m + this.#cap : m;
+  }
+
+  #put(pos: number, bytes: Uint8Array) {
+    const off = this.#offset(pos);
+    const first = Math.min(bytes.length, this.#cap - off);
+    this.#data.set(bytes.subarray(0, first), off);
+    if (first < bytes.length) this.#data.set(bytes.subarray(first), 0);
+  }
+
+  #get(pos: number, len: number): Uint8Array {
+    const out = new Uint8Array(len);
+    const off = this.#offset(pos);
+    const first = Math.min(len, this.#cap - off);
+    out.set(this.#data.subarray(off, off + first), 0);
+    if (first < len) out.set(this.#data.subarray(0, len - first), first);
+    return out;
+  }
+}

package/src/settings-store.ts

@@ -0,0 +1,101 @@
+// A small app's settings: one JSON document in the user's app-data folder,
+// read once at start and written whole on every change. Synchronous on
+// purpose: the UI thread is blocked in the OS loop after run() and cannot
+// await, and a settings change is a few hundred bytes.
+//
+//   const store = createSettingsStore<Settings>({ app: "my-app", defaults: DEFAULTS, sanitize });
+//   let settings = store.load();          // before run(); defaults when the file is missing or unreadable
+//   store.save(settings = { ...settings, ...patch });
+//
+// No Bun or FFI; usable from any build or test script.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * The per-user folder an app keeps its own files in: `%APPDATA%\<app>` on
+ * Windows, `~/Library/Application Support/<app>` on macOS,
+ * `$XDG_CONFIG_HOME/<app>` (default `~/.config/<app>`) elsewhere. Not created.
+ */
+export function appDataDir(app: string): string {
+  const base =
+    process.platform === "win32"
+      ? (process.env.APPDATA || join(homedir(), "AppData", "Roaming"))
+      : process.platform === "darwin"
+        ? join(homedir(), "Library", "Application Support")
+        : (process.env.XDG_CONFIG_HOME || join(homedir(), ".config"));
+  return join(base, app);
+}
+
+export type SettingsStoreOptions<T> = {
+  /** The app's folder name under the app-data folder (`appDataDir`). */
+  app: string;
+  /** The file inside it. Default `settings.json`. */
+  file?: string;
+  /** The folder itself, instead of `appDataDir(app)`; for tests, or an app that keeps settings elsewhere. */
+  dir?: string;
+  /** The baseline: what the default `sanitize` merges the file over, and what `load()` returns when `sanitize` throws. */
+  defaults: T;
+  /**
+   * Turns whatever the file held into a valid T: fill gaps, clamp ranges,
+   * drop junk. Gets the parsed JSON, or `undefined` when the file was
+   * missing, unreadable or not JSON. Default: the defaults with the file's
+   * own keys over them, when the file holds an object. A throw is logged and
+   * `defaults` is returned instead.
+   */
+  sanitize?: (input: unknown) => T;
+};
+
+export type SettingsStore<T> = {
+  /** Where the file is (or will be). */
+  readonly path: string;
+  /** The saved settings through `sanitize`; `sanitize(undefined)` when the file is missing, unreadable or not JSON (the cause goes to stderr). Never throws. */
+  load(): T;
+  /** Writes the whole document, creating the folder; a failure goes to stderr and is otherwise ignored, so a read-only disk never stops the app. */
+  save(settings: T): void;
+};
+
+export function createSettingsStore<T extends object>(options: SettingsStoreOptions<T>): SettingsStore<T> {
+  const path = join(options.dir ?? appDataDir(options.app), options.file ?? "settings.json");
+  const isPlainObject = (input: unknown): input is Partial<T> => typeof input === "object" && input !== null && !Array.isArray(input);
+  const sanitize = options.sanitize ?? ((input: unknown): T => ({ ...options.defaults, ...(isPlainObject(input) ? input : {}) }));
+  // sanitize runs on every path, so a custom one that derives or migrates fields always gets its turn;
+  // a throw from it is reported like an unreadable file and the defaults are used.
+  const settle = (input: unknown): T => {
+    try {
+      return sanitize(input);
+    } catch (err) {
+      console.error(`settings: sanitize failed for ${path}, using defaults:`, (err as Error).message);
+      return { ...options.defaults };
+    }
+  };
+  return {
+    path,
+    load() {
+      if (!existsSync(path)) return settle(undefined);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+      } catch (err) {
+        console.error(`settings: ${path} unreadable, using defaults:`, (err as Error).message);
+        return settle(undefined);
+      }
+      return settle(parsed);
+    },
+    save(settings) {
+      // written beside the file and renamed over it, so a crash mid-write leaves the previous document rather than a truncated one
+      const tmp = `${path}.${process.pid}.tmp`;
+      try {
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}\n`);
+        renameSync(tmp, path);
+      } catch (err) {
+        try {
+          rmSync(tmp, { force: true });
+        } catch {}
+        console.error(`settings: could not write ${path}:`, (err as Error).message);
+      }
+    },
+  };
+}

package/src/webview-lib.ts

@@ -0,0 +1,60 @@
+// sweetview runs on the webview library that @n1h/sweetview-webview-bun ships:
+// upstream webview/webview plus `webview_set_background_color` and
+// `webview_set_asset` (see ../docs/webview-library.md). webview-bun loads it from
+// its own build/ folder; `bun build --compile` embeds that file. The two extra
+// symbols are probed here at run time rather than assumed: without
+// webview_set_background_color the page stays opaque with a warning; without
+// webview_set_asset createWebviewApp throws, because the page cannot load.
+
+import { FFIType, dlopen, ptr, type Pointer } from "bun:ffi";
+
+/** The path webview-bun loads its native library from, resolved the same way it does, so the worker can dlopen the same file (it needs webview_dispatch). */
+export async function webviewLibPath(): Promise<string> {
+  if (process.env.WEBVIEW_PATH) return process.env.WEBVIEW_PATH;
+  switch (process.platform) {
+    case "win32":
+      //@ts-expect-error file import
+      return (await import("@n1h/sweetview-webview-bun/build/libwebview.dll")).default;
+    case "darwin":
+      //@ts-expect-error file import
+      return (await import("@n1h/sweetview-webview-bun/build/libwebview.dylib")).default;
+    default:
+      return (await import(`@n1h/sweetview-webview-bun/build/libwebview-${process.arch}.so`)).default;
+  }
+}
+
+export type SetBackgroundColor = (w: Pointer, r: number, g: number, b: number, a: number) => number;
+export type SetAsset = (w: Pointer, path: string, mime: string, data: Uint8Array) => number;
+
+/** The library's `webview_set_background_color`, or undefined when this build does not have it. */
+export function backgroundColorCall(libPath: string): SetBackgroundColor | undefined {
+  try {
+    return dlopen(libPath, {
+      webview_set_background_color: { args: [FFIType.ptr, FFIType.i32, FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+    }).symbols.webview_set_background_color as SetBackgroundColor;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The library's `webview_set_asset`, or undefined when this build does not have it. */
+export function setAssetCall(libPath: string): SetAsset | undefined {
+  try {
+    const { webview_set_asset } = dlopen(libPath, {
+      webview_set_asset: { args: [FFIType.ptr, FFIType.cstring, FFIType.cstring, FFIType.ptr, FFIType.u64], returns: FFIType.i32 },
+    }).symbols;
+    const cstr = (s: string) => Buffer.from(`${s}\0`, "utf8");
+    // The library copies the bytes, so nothing here needs to outlive the call.
+    return (w, path, mime, data) => webview_set_asset(w, cstr(path), cstr(mime), data.byteLength ? ptr(data) : null, BigInt(data.byteLength));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Where assets are served from, per platform. Windows intercepts
+ * http://webview.localhost with WebView2's WebResourceRequested; macOS
+ * registers a WKURLSchemeHandler for the "webview" scheme. Relative URLs in
+ * the page work the same on both.
+ */
+export const ASSET_ORIGIN = process.platform === "darwin" ? "webview://localhost" : "http://webview.localhost";