diff --git a/src/main/api/screen.ts b/src/main/api/screen.ts
index 437c146..6940e36 100644
--- a/src/main/api/screen.ts
+++ b/src/main/api/screen.ts
@@ -9,9 +9,8 @@ export type Size = {
};
/**
- * `workArea` excludes the taskbar on Windows only; macOS and Linux report `bounds`. macOS also
- * reports every display's origin as (0, 0), since CoreGraphics has no scalar origin getter.
- * `scaleFactor` is the device-pixel ratio, `rotation` degrees clockwise.
+ * `workArea` excludes the menu bar and Dock on macOS and the taskbar on Windows; Linux reports
+ * `bounds`. `scaleFactor` is the device-pixel ratio, `rotation` degrees clockwise.
*/
export type Display = {
readonly id: number;
diff --git a/website/src/content/docs/api/ipc-main.md b/website/src/content/docs/api/ipc-main.md
index 59df2b0..3c94407 100644
--- a/website/src/content/docs/api/ipc-main.md
+++ b/website/src/content/docs/api/ipc-main.md
@@ -164,7 +164,7 @@ The router covers the everyday `on`/`once`/`handle` flow, but several Electron m
* **`ipcMain.off`, `ipcMain.addListener`** - these Electron aliases for `removeListener`/`on` do not exist. Use `removeListener` and `on` directly.
* **Synchronous IPC (`event.returnValue`)** - there is no synchronous `ipcRenderer.sendSync` path, so listeners cannot set `event.returnValue` to reply inline. Use `handle`/`invoke` for request/response instead.
* **`event.frameId` / `event.processId` / `event.senderFrame`** - frame and process routing metadata is not exposed; `event.sender` is all you get, and iframe-level addressing is not modeled.
-* **`event.ports` and `MessagePort` transfer** - `MessagePortMain` / `postMessage` channels are not implemented; payloads cross as JSON, not structured clone. Functions, symbols and `bigint` are rejected on both sides, and the renderer side also rejects `Map`, `Set`, `ArrayBuffer` and typed arrays rather than letting JSON mangle them.
+* **`event.ports` and `MessagePort` transfer** - `MessagePortMain` / `postMessage` channels are not implemented; payloads cross as JSON, not structured clone. A `Map`, `Set`, `ArrayBuffer`, typed array, function, symbol or `bigint` is refused on both sides rather than arriving mangled: the preload throws a `TypeError`, and main throws an `InvalidArgumentError` (a handler that returns one makes the page's `invoke` reject). A Node `Buffer` sent from main arrives as `{ type: 'Buffer', data: [...] }`.
* **`EventEmitter` surface** - because `ipcMain` is not an `EventEmitter`, methods like `eventNames()`, `listenerCount()`, `setMaxListeners()`, and `prependListener()` are unavailable.
* **Full-fidelity error propagation** - `handle` errors are flattened to the `message` string only; stack traces and custom error properties are lost across the boundary (the same limitation Electron documents, noted here for parity).
diff --git a/website/src/content/docs/api/web-contents.md b/website/src/content/docs/api/web-contents.md
index 0f5a2e5..c11ce13 100644
--- a/website/src/content/docs/api/web-contents.md
+++ b/website/src/content/docs/api/web-contents.md
@@ -253,7 +253,7 @@ win.webContents.sendInputEvent({ type: 'keyDown', keyCode: 'Enter' });
win.webContents.sendInputEvent({ type: 'keyUp', keyCode: 'Enter' });
```
-Honest follow-up limits: there are no keyboard modifiers yet, synthesized drags don't carry button state, and `KeyboardEvent.code` / scan codes and the F1-F24 keys are not wired.
+Limits on Windows today: there are no modifier keys, so a `modifiers` array is ignored and Shift, Ctrl and Alt come from the physical keyboard. `keyDown` and `keyUp` know letters, digits, Enter, Tab, Escape, Backspace, Space, Delete, the arrows, Home, End, PageUp and PageDown; any other key, F1-F24 included, does nothing (`char` types any single character). Coordinates are only guaranteed at 100% display scaling. See the [parity page](/docs/migrating/parity#webcontentssendinputevent) for the full list.
### `contents.setWindowOpenHandler(handler)`
@@ -309,7 +309,7 @@ if (!win.webContents.isDestroyed()) {
* `channel` string
* `...args` any[]
-Sends an event on `channel` to the renderer, where `ipcRenderer.on(channel, ...)` in the preload receives it. Arguments are **JSON**-serialized, not structured-cloned as in Electron: a function, symbol or `bigint` throws `InvalidArgumentError`, a `Date` arrives as a string, `Map` / `Set` / typed arrays arrive as plain objects, and `undefined` properties vanish. Send plain data. A `send` before the page's first load is queued on all platforms and flushed once the bridge is up - at `dom-ready` on Linux and Windows, at `did-finish-load` on macOS - so a message fired right after `loadFile` is not lost.
+Sends an event on `channel` to the renderer, where `ipcRenderer.on(channel, ...)` in the preload receives it. Arguments are **JSON**-serialized, not structured-cloned as in Electron: a `Map`, `Set`, `ArrayBuffer`, typed array, function, symbol or `bigint` throws `InvalidArgumentError`, a `Date` arrives as a string, a Node `Buffer` arrives as `{ type: 'Buffer', data: [...] }`, and `undefined` properties vanish. Send plain data. A `send` before the page's first load is queued on all platforms and flushed once the bridge is up - at `dom-ready` on Linux and Windows, at `did-finish-load` on macOS - so a message fired right after `loadFile` is not lost.
```ts
win.webContents.send('update-available', { version: '1.2.0' });
diff --git a/website/src/content/docs/migrating/parity.md b/website/src/content/docs/migrating/parity.md
index faea252..bd0f74d 100644
--- a/website/src/content/docs/migrating/parity.md
+++ b/website/src/content/docs/migrating/parity.md
@@ -1,77 +1,485 @@
---
title: API Parity & Gaps
-description: "The single source of truth for which Electron modules and methods bunmaska implements, per platform (macOS, Linux, Windows). Honest, cell by cell."
+description: "Which Electron APIs work in Bunmaska on macOS, Linux and Windows, what behaves differently, and what to do when something is missing."
seoTitle: "Electron API parity matrix - per module, per platform"
order: 2
---
-We're allergic to lying in tables, so here's the honest map. Bunmaska implements **~21 of Electron's main-process modules** - about **70-80% of what a typical webview app actually uses** - and now ships on **three platforms**: macOS (AppKit + WKWebView), Linux (GTK 4 + WebKitGTK 6), and Windows (WinCairo WebKit + Win32). No bundled Chromium on any of them.
+We're allergic to lying in tables, so here's the honest map. Bunmaska implements **~21 of Electron's main-process modules**, which covers most of what a typical webview app uses. It runs on **three platforms**, and none of them bundles Chromium:
-Support is not uniform across platforms, and we won't pretend it is. The table below is the source of truth.
+- **macOS** uses AppKit and the system's own WebKit (`WKWebView`).
+- **Linux** uses GTK 4 and the system's WebKitGTK 6.
+- **Windows** uses Win32 and **WinCairo**, a Windows build of WebKit. Windows has no system WebKit, so Bunmaska builds WinCairo from source, and your Windows app has to carry it. Embed it with `engine.embed: true` or `bunmaska build --embed-engine
`. Without an engine, the app refuses to start. See [Building for Windows](/docs/building#windows).
-**Legend:** full · partial (see notes) · engine-blocked (the WebKit build lacks the API) · not implemented.
+Support is not the same on every platform, and we won't pretend it is. Start with the table for the one-line summary, then read the module's section below it for the details. Electron methods Bunmaska has not built at all are listed at the bottom of each API page, under "Not in Bunmaska (yet)" (for example, [app](/docs/api/app#not-in-bunmaska-yet)).
+
+## How to read the table
+
+- **Full.** Everything Bunmaska offers in this module works on this OS. A few differences from Electron apply on every OS, such as async clipboard reads, JSON IPC or media keys in `globalShortcut`. The note and the module's section list them.
+- **Partial.** It works on this OS, with gaps you should plan around. The note and the module's section say exactly which.
+- **Engine-blocked.** It can't be built on this OS today, because the WebKit build Bunmaska uses there lacks the piece it needs. `printToPDF` and `capturePage` reject with `UnsupportedPlatformError`. `protocol.handle` is the exception: it registers without an error but never serves anything (see [`protocol`](#protocol)). This changes only if WebKit adds the missing piece. See [why](#why-some-things-cant-work-on-an-os).
+- **Not implemented.** Not built on this OS yet, though nothing in the platform stops it. Calling it throws `UnsupportedPlatformError`, or rejects with it when the method returns a Promise. To fall back, catch it: import `UnsupportedPlatformError` from `bunmaska/main`, or check `err.code === 'ERR_UNSUPPORTED_PLATFORM'`. [Still to do](#still-to-do) says what is planned.
+
+### Linux opt-in switches
+
+Four Linux features stay off until your app turns them on, because they talk to the desktop's message bus (D-Bus) or keyring. Keeping them off by default also keeps our CI machines away from those services.
+
+- The tray: `BUNMASKA_ENABLE_LINUX_TRAY`
+- `powerMonitor`: `BUNMASKA_ENABLE_LINUX_POWER`
+- `powerSaveBlocker`: `BUNMASKA_ENABLE_LINUX_POWER_BLOCKER`
+- `safeStorage`: `BUNMASKA_ENABLE_LINUX_KEYRING`
+
+Your users don't set anything. Your main process does, at the top of `main.ts`, before `app.whenReady()` and before the first call, for example `process.env.BUNMASKA_ENABLE_LINUX_TRAY = '1'`. Set it early: `safeStorage`, `powerMonitor` and `powerSaveBlocker` check once and remember the answer.
## The matrix
| Module | macOS | Linux | Windows | Notes |
| --- | :---: | :---: | :---: | --- |
-| `app` | | | | Lifecycle with Electron's quit sequence (`before-quit`, window `close` vetoes, `will-quit`, `quit`), which the `quit` menu role runs everywhere and Cmd+Q, the Dock's Quit and logout run on macOS. Paths, single-instance, locale. Dock/badge are macOS-only and no-op elsewhere (as in Electron); the about panel works on macOS and Linux (GTK about dialog), no-op on Windows. `activate`/`open-url`/`open-file` fire on macOS only. The single-instance lock is unverified on Windows. |
-| `BrowserWindow` | | | | `getBounds`/`setBounds`/`setPosition` are real frame geometry in global top-left coordinates on macOS (read from AppKit) and Windows, and the `move` event fires on both. Linux leaves placement to the compositor (GTK4/Wayland): `setPosition` is a no-op, `setBounds` applies size only, `getBounds` reports `x`/`y` as `0`, no `move`, and `minimize`/`restore` never fire (the minimized state is not observed yet). `fromWebContents`/`getFocusedWindow` and `Object has been destroyed` after close match Electron everywhere. |
-| `webContents` (core) | | | | load/navigation/`executeJavaScript`/zoom/`insertCSS`/IPC `send` everywhere. `setWindowOpenHandler({action:'allow'})` is unimplemented on all three (`window.open` is blocked by default); on Windows the handler callback is not invoked yet. |
-| `webContents.printToPDF` | | | | macOS via `createPDFWithConfiguration`. Linux: not yet wired. Windows: engine-blocked (no PDF sink in the WinCairo C API). |
-| `webContents.capturePage` | | | | macOS via WKWebView snapshot, Linux via `webkit_web_view_get_snapshot` (visible viewport, PNG). Windows: engine-blocked (no UI-process snapshot). |
-| `webContents.sendInputEvent` | | | | Trusted input synthesis - the page sees `isTrusted === true`, which a script-dispatched event can't. Windows only (WinCairo, via posted/sent Win32 messages); macOS + Linux throw `UnsupportedPlatformError`. Windows follow-ups: no keyboard modifiers, synthesized drags don't carry button state, `KeyboardEvent.code`/scan-codes and F1-F24 aren't wired, and coordinates are correct at 100% display scale only (per-monitor DPI pending). |
-| `ipcMain` / `ipcRenderer` | | | | `handle`/`on`/`invoke`/`send`, `event.reply`. Payloads are JSON, not structured clone (see deviations below), and `ipcRenderer` lives in the preload. On Windows any page script can reach the bridge, so validate `event.sender` there. |
-| `contextBridge` | | | | Real isolated content world on macOS/Linux. Windows runs in the page world (WinCairo exposes no named world) - the bridge works, but the isolation guarantee is weaker. |
-| `Menu` / `MenuItem` | | | | Context menus + application menu bar on all three, with Electron's `click(menuItem, window, event)` (the focused window included) and checkbox/radio toggling. macOS routes roles to the responder chain; Linux wires the editing, window and `quit` roles; Windows wires the window and `quit` roles and shows its editing role items as inert labels. Accelerators work on macOS only: Linux and Windows neither bind nor show them. Electron's default application menu is installed on macOS only. |
-| `dialog` | | | | The leading `window` argument is accepted but not used (no sheets). Linux: message-box severity is a no-op. Windows: custom button labels approximated (native `MessageBoxW` button sets), and the folder picker ignores `defaultPath`. |
-| `clipboard` | | | | text / HTML / image on all three. Reads are async everywhere (GDK requires it). |
-| `Tray` | | | | Linux: SNI tray, gated behind `BUNMASKA_ENABLE_LINUX_TRAY`, no context menu yet. Windows: icon + tooltip + left-click, context menu deferred. |
-| `Notification` | | | | macOS delivers only from a real `.app` bundle (`isSupported()` is honest about it); click/close events not wired. Linux: `close` event only. Windows: balloon toast (rich toasts are a follow-up) that fires `close` on dismissal. `silent` works on all three. |
-| `nativeImage` | | | | path/buffer/dataURL/PNG/JPEG/resize/crop. JPEG quality is honored on macOS and Linux, ignored on Windows. |
-| `nativeTheme` | | | | macOS: read + `themeSource` override + live `updated`. Linux: read + live `updated`, but `themeSource` is TS-only (no native re-theme). Windows: read + `themeSource` (TS-level); live observation is a follow-up. |
-| `globalShortcut` | | | | Linux: X11 only (`isSupported()` is `false` under Wayland). |
-| `shell` | | | | `openExternal`/`openPath`/`showItemInFolder`/`beep`. Linux `showItemInFolder` opens the parent folder without selecting. |
-| `protocol` | | | | Custom scheme handlers serve on macOS/Linux; built-in schemes (`http`, `https`, `file`, ...) are refused. Windows: engine-blocked - the WinCairo C API exposes no scheme-handler entry point, and a window created with schemes registered logs a warning. |
-| `screen` | | | | Display enumeration, multi-monitor origins and scale factor work everywhere. macOS and Windows have a real `getCursorScreenPoint` and work area; Linux stubs both (cursor `{0,0}`, `workArea` = `bounds`). Rotation and `internal` are macOS-only; no display events anywhere. |
-| `powerMonitor` | | | | suspend/resume + lock/unlock on all three. `getSystemIdleTime`/`isOnBatteryPower` not implemented on any. Linux is gated behind `BUNMASKA_ENABLE_LINUX_POWER`, and its `suspend` is best-effort (no delay inhibitor, so it can arrive after wake). |
-| `powerSaveBlocker` | | | | Linux: gated, and both blocker types map to screensaver inhibition. |
-| `safeStorage` | | | | macOS Keychain, Windows DPAPI. Linux: libsecret, gated behind `BUNMASKA_ENABLE_LINUX_KEYRING` (no plaintext fallback - encrypt/decrypt throw when unavailable). On macOS and Linux one key is shared by every Bunmaska app (Electron keeps one per app). |
-| `session` | | | | `getUserAgent`/`setUserAgent` everywhere. `cookies` (`get`/`set`/`remove`) on macOS + Linux, with host-only and domain cookies matched as RFC 6265 says; `sameSite` cannot be set (macOS stores `lax`). Windows is engine-blocked (the WinCairo C API exposes no cookie read/write). `clearStorageData`: macOS clears all website data; Windows clears cookies + fetch caches; Linux not yet wired. |
-| `autoUpdater` | | | | Signed updates end to end: check/download, Ed25519 signatures on both `update.json` and the artifact plus hash verification (unsigned feeds refused), stage, and a real detached swap-and-relaunch installer that relaunches the old app if anything fails, on all three OSes. Honest residue: the live swap is the one step CI doesn't exercise end to end, `quitAndInstall` throws for non-installed layouts (dev runs), and checks refuse to run while the app version is unknown (`0.0.0`, no `version` in your `package.json`). |
-| `accelerator` · `app-paths` | | | | Pure or fully-wired on all three. |
-| `requestSingleInstanceLock` | | | | The argv hand-off rides a unix-domain socket, which is unverified on Windows. |
-
-## Engine-blocked - why these can't ship on a given OS
-
-These aren't laziness; the OS's WebKit simply doesn't expose the API:
-
-- **Windows `protocol` / `printToPDF` / `capturePage`** - the WinCairo WebKit2 C API has no custom-scheme-handler, no PDF sink (`WKPageDrawPagesToPDF` is Cocoa-only), and no UI-process snapshot (only the web-process `WKBundlePage*` variants). We confirmed each by parsing `WebKit2.dll`'s export table. They become available only if upstream WinCairo adds them.
-
-## Pending (inside shipped modules)
-
-Real gaps we're actively filling: `session.clearStorageData` on Linux; richer `webContents` events; the Windows `setWindowOpenHandler` callback; live `nativeTheme` observation on Windows; tray context menus on Linux/Windows; menu accelerators on Linux/Windows; the `move` event and minimized state on Linux; the cursor and work area on Linux; the isolated content world on Windows.
-
-## Deviations from Electron
-
-Places where the code does something different from Electron today, on every platform unless noted. Each is documented on its API page:
-
-- **IPC is JSON, not structured clone.** From the preload, a `Map`, `Set`, `ArrayBuffer`, typed array, function, symbol or `bigint` throws; from main, functions, symbols and `bigint` throw and the rest turn into plain objects. A `Date` arrives as a string. See [ipcRenderer](/docs/api/ipc-renderer#ipcrenderersendchannel-args).
-- **`contextBridge` functions are always async** on the page side (a DOM-event transport, not V8's), and `ipcRenderer` exists only in the preload on macOS and Linux.
-- **`protocol.handle` serves custom schemes only**; Electron can intercept `http`, `https` and `file`.
-- **No default application menu**, so a macOS app has no Cmd+Q until it sets a menu with a `quit` role.
-- **`app.quit()` runs no `beforeunload` handlers**; only main-process listeners and window `close` listeners can veto. `ready` passes no arguments.
-- **`app.setPath` does not require the directory to exist**, and `getPreferredSystemLanguages()` is `[getLocale()]` outside Linux.
-- **`BrowserWindow.fromId` misses with `undefined`**, not `null`.
-- **`dialog` ignores the parent window** (no sheets), and on Windows a save dialog's `defaultPath` cannot be a bare folder.
-- **`clipboard`, `shell` and `nativeImage` are main-process only**, and clipboard reads return Promises.
-- **`cookies.set` defaults `path` to `/`**, not the url's directory.
-- **`safeStorage` shares one key across Bunmaska apps** on macOS and Linux.
+| `app` | | | | [Lifecycle, quit, paths and locale work everywhere. Windows has no about panel.](#app) |
+| `BrowserWindow` | | | | [On Linux your app can't position its windows or tell when the user minimizes one. Windows reports moves and resizes only when a drag ends.](#browserwindow) |
+| `webContents` (core) | | | | [Loading, navigation, scripts and IPC work everywhere. Windows has no DevTools or pop-up handler yet.](#webcontents-core) |
+| `webContents.printToPDF` | | | | [macOS only.](#webcontentsprinttopdf) |
+| `webContents.capturePage` | | | | [macOS and Linux. Not possible on Windows today.](#webcontentscapturepage) |
+| `webContents.sendInputEvent` | | | | [Windows only, without modifier keys.](#webcontentssendinputevent) |
+| `ipcMain` / `ipcRenderer` | | | | [Works everywhere. Messages are sent as JSON, so send plain data only.](#ipcmain-and-ipcrenderer) |
+| `contextBridge` | | | | [On Windows the preload is not isolated from the page.](#contextbridge) |
+| `Menu` / `MenuItem` | | | | [Menu keyboard shortcuts work on macOS only.](#menu-and-menuitem) |
+| `dialog` | | | | [Dialogs never attach to a window. Windows can't show custom button labels.](#dialog) |
+| `clipboard` | | | | [Text, HTML and images everywhere. Reads return Promises.](#clipboard) |
+| `Tray` | | | | [No tray menu on Linux or Windows yet. Linux needs an opt-in switch.](#tray) |
+| `Notification` | | | | [macOS needs a packaged `.app`. No `click` event anywhere.](#notification) |
+| `nativeImage` | | | | [Works everywhere. Windows ignores JPEG quality.](#nativeimage) |
+| `nativeTheme` | | | | [Forcing light or dark with `themeSource` restyles the page on macOS only.](#nativetheme) |
+| `globalShortcut` | | | | [Linux works under X11 only. Media keys don't register anywhere.](#globalshortcut) |
+| `shell` | | | | [Works everywhere. Linux can't highlight the file in its folder.](#shell) |
+| `protocol` | | | | [Custom schemes like `app://` serve on macOS and Linux. Not possible on Windows today.](#protocol) |
+| `screen` | | | | [No display-change events anywhere. Linux can't read the cursor or work area.](#screen) |
+| `powerMonitor` | | | | [Sleep, wake, lock and unlock only. Linux needs an opt-in switch.](#powermonitor) |
+| `powerSaveBlocker` | | | | [Blocks idle sleep. Linux needs an opt-in switch, and both types do the same thing there.](#powersaveblocker) |
+| `safeStorage` | | | | [One key shared by every Bunmaska app. Linux needs an opt-in switch.](#safestorage) |
+| `session` | | | | [One default session. Cookies on macOS and Linux only.](#session) |
+| `autoUpdater` | | | | [Signed updates download, install and relaunch on all three. Unlike Electron, you start the download yourself, and `.deb` installs can't update themselves.](#autoupdater) |
+| Accelerator strings, `app.getPath` | | | | [Parse and resolve the same on all three.](#accelerator-strings-and-appgetpath) |
+| `requestSingleInstanceLock` | | | | [Not yet tested on Windows.](#requestsingleinstancelock) |
+
+## Module by module
+
+### `app`
+
+Works like Electron on all three: `whenReady`, the quit sequence, `getPath`, name and version, and locale. The single-instance lock works too, though it is not yet tested on Windows (see [`requestSingleInstanceLock`](#requestsingleinstancelock)).
+
+Quitting follows Electron's order. `app.quit()` fires `before-quit`, then closes every window, then fires `will-quit` and `quit`. Any window's `close` listener can cancel the quit, and so can `before-quit` and `will-quit`. Page `beforeunload` handlers don't run and can't cancel it. The `quit` menu role runs the same sequence on every OS. On macOS, Cmd+Q, the Dock's Quit and logging out run it too.
+
+- **macOS:** everything above, plus `app.dock`, the badge count, `hide`/`show`, the about panel, and the `activate`, `open-url` and `open-file` events.
+- **Linux:** `showAboutPanel()` opens a plain GTK about dialog. Your app's name and version are not filled in on it yet.
+- **Windows:** Windows has no standard about panel, so `showAboutPanel()` does nothing.
+- **Linux and Windows:**
+ - `app.dock` is `undefined`, as in Electron.
+ - `setBadgeCount` shows nothing and returns `false`, though `getBadgeCount` still returns what you set.
+ - `hide`, `show` and `setActivationPolicy` do nothing, and `isHidden()` / `isActive()` return `false`.
+ - `activate`, `open-url` and `open-file` never fire, because they come from macOS itself.
+
+### `BrowserWindow`
+
+Works like Electron on macOS. `getBounds`, `setBounds` and `setPosition` use the window's real on-screen frame, measured from the top-left corner of the primary display, as Electron does. The `move` event fires when the user drags the window.
+
+On every OS, `BrowserWindow.fromWebContents` and `getFocusedWindow` work, and a closed window (or its `webContents`) throws `TypeError: Object has been destroyed` when you use it, as in Electron. Check `isDestroyed()` first if you are unsure.
+
+- **Linux:** GTK 4 gives apps no way to place their own windows, and Wayland forbids it outright. The desktop decides where windows go. So on Linux:
+ - `setPosition` and `center` do nothing.
+ - `setBounds` applies the size and ignores `x` and `y`.
+ - `getBounds` and `getPosition` always report `x` and `y` as `0`.
+ - The `move` event never fires.
+ - `setAlwaysOnTop` does nothing, because GTK 4 dropped that feature.
+ - `setSize` sets the size of the content area, not the outer frame.
+ - The `minimize` and `restore` events never fire. `isMinimized()` is `true` only after you call `minimize()` yourself. It can't see the user minimizing the window.
+- **Windows:** geometry, the `move` event and `setMinimumSize` work. Two gaps:
+ - While the user drags or resizes a window, `move` and `resize` arrive when they let go of the mouse, not continuously.
+ - To your code, a closed window behaves as on the other OSes: `closed` fires, and using it throws `Object has been destroyed`. Behind the scenes, Bunmaska only hides the native window and loads a blank page into it, because tearing down a live WebKit view crashes on Windows today. That memory is freed only when the app exits, so an app that opens and closes many windows uses more memory over time.
+
+Parent, child and modal windows are not implemented on any OS. The [BrowserWindow page](/docs/api/browser-window#not-in-bunmaska-yet) lists the rest.
+
+### `webContents` (core)
+
+Loading pages, navigation events, `executeJavaScript`, zoom, `insertCSS` and `send` work on all three.
+
+Bunmaska can't create child windows yet, so `window.open` and `target="_blank"` links are always blocked, on every OS. On macOS and Linux your `setWindowOpenHandler` handler is still called with the URL. Returning `{ action: 'allow' }` logs a warning and the window stays blocked. The practical pattern: open the URL with `shell.openExternal(url)` and return `{ action: 'deny' }`.
+
+- **macOS:** `openDevTools()` opens the Web Inspector through a private WebKit API. If that API is missing, it logs a warning instead of throwing. `alert()`, `confirm()` and file inputs open native sheets. `prompt()` returns `null`, as in Electron.
+- **Linux:** `openDevTools()` opens the WebKitGTK inspector.
+- **Windows:** two gaps.
+ - `setWindowOpenHandler` is never called. Setting one logs a warning. So on Windows, `window.open` and `target="_blank"` links silently do nothing, and main never learns the URL. If your page has external links, catch the click in your preload and send the URL to main, which opens it with `shell.openExternal`.
+ - `openDevTools()` does nothing but log a warning. The WinCairo inspector is not wired up yet.
+- **Linux and Windows:** Bunmaska adds no handling of its own for `alert()`, `confirm()`, `prompt()` and file inputs. What happens is whatever that WebKit build does by default, and we haven't documented it per OS yet. Test them there, or have main show a [`dialog`](#dialog) over IPC when you need a predictable result.
+
+### `webContents.printToPDF`
+
+- **macOS:** works. Resolves to the PDF bytes. Options such as page size and margins are ignored (TypeScript flags them).
+- **Linux:** rejects with `UnsupportedPlatformError`. WebKitGTK has no call that hands back PDF bytes, but it can print to a file. Printing to a temporary PDF and reading it back would work. It just isn't wired up yet.
+- **Windows:** engine-blocked. Rejects with `UnsupportedPlatformError`. WinCairo has no PDF export at all.
+
+### `webContents.capturePage`
+
+- **macOS and Linux:** resolves to a [`NativeImage`](/docs/api/native-image) of the visible part of the page. A `rect` argument is ignored (TypeScript flags it). To capture part of the page, crop the result with `crop()`.
+- **Windows:** engine-blocked. Rejects with `UnsupportedPlatformError`. WinCairo can only take a snapshot from inside the page's own process, which Bunmaska can't reach from the app.
+
+### `webContents.sendInputEvent`
+
+Sends a real mouse or keyboard event into the page. The page sees `isTrusted === true`, which a script-dispatched event can never fake. That matters for widgets that ignore synthetic clicks.
+
+- **macOS and Linux:** throws `UnsupportedPlatformError`.
+- **Windows:** works for `mouseDown`, `mouseUp`, `mouseMove`, `keyDown`, `keyUp` and `char`. It works on a hidden window and never steals the user's focus. Any other type, such as `mouseWheel` or `mouseEnter`, throws a `TypeError`. A malformed event, such as a mouse event whose `x` isn't a finite number, also throws a `TypeError` instead of firing.
+
+Limits on Windows:
+
+- There are no modifier keys. A `modifiers` array is ignored (TypeScript flags it). Shift, Ctrl and Alt come from the physical keyboard, so you can't send Ctrl+A.
+- `keyDown` and `keyUp` know letters, digits and these named keys: Enter, Tab, Escape, Backspace, Space, Delete, the arrows, Home, End, PageUp and PageDown. Any other key, F1-F24 included, silently does nothing. `char` types any single character.
+- For the keys it knows, the event carries the key's US-layout scan code, the same layout Electron uses for `KeyboardEvent.code`.
+- A synthesized hover ends at once while the real mouse pointer is outside the window, so hover menus close immediately.
+- Coordinates are only guaranteed at 100% display scaling. Support for scaled displays is still to come.
+
+### `ipcMain` and `ipcRenderer`
+
+Works on all three: `ipcMain.handle` and `on`, `event.reply`, `ipcRenderer.invoke`, `send` and `on`, and `webContents.send`. As in Electron, `invoke` has no timeout, and an error thrown in a handler reaches the page as its message only.
+
+Differences on every OS:
+
+- **Messages travel as JSON, not Electron's structured clone.** Send plain data: strings, numbers, booleans, arrays and plain objects.
+ - A `Map`, `Set`, `ArrayBuffer`, typed array, function, symbol or `bigint` is refused in both directions, instead of arriving mangled.
+ - Sent from the preload (`ipcRenderer.send` or `invoke`), it throws a `TypeError`.
+ - Sent from main (`webContents.send`, `event.reply`), it throws an `InvalidArgumentError`. If an `ipcMain.handle` handler returns one, the page's `invoke` rejects.
+ - A `Date` arrives as an ISO string, and properties set to `undefined` disappear.
+ - A Node `Buffer` sent from main is the one exception. It is not refused, and arrives as `{ type: 'Buffer', data: [...] }`. To send binary data either way, convert it to base64 first.
+- **`ipcRenderer.sendSync` doesn't exist.** Switch those calls to `invoke`.
+- **The `event` an `ipcRenderer.on` listener receives is an empty object**, so `event.sender` and `event.ports` aren't there.
+- **`ipcRenderer` belongs in your preload.** Expose what the page needs with [`contextBridge`](#contextbridge), as with Electron's `contextIsolation: true`.
+
+Who can reach your handlers:
+
+- **macOS and Linux:** a page script can't reach `ipcRenderer` at all. It gets a `BunmaskaError` pointing at `contextBridge`.
+- **Windows:** the preload is not isolated (see [`contextBridge`](#contextbridge)), so any script on the page, third-party ones included, can call your handlers. If a window may load content you don't control, check `event.sender.getURL()` in the handlers that matter.
+
+`MessagePort` and `postMessage` are not implemented.
+
+### `contextBridge`
+
+- **macOS and Linux:** your preload runs in its own isolated JavaScript world, like Electron with `contextIsolation: true`. The page can't see the preload's globals.
+- **Windows:** the preload runs in the same JavaScript context as the page, like Electron with `contextIsolation: false`. WinCairo can't create a separate context without a native plugin inside the engine, which Bunmaska doesn't ship yet. `exposeInMainWorld` still works, but any script on the page, third-party ones included, can read and change what the preload sets up. Don't rely on the preload as a security boundary on Windows.
+
+On every OS:
+
+- Every function you expose is async on the page side and returns a `Promise`, even if your implementation is synchronous. Each call is passed between the two worlds as a message rather than made directly. Design the API as async from the start.
+- Arguments and return values are copied (structured clone), so only data crosses. That breaks Electron's common `window.api.onSomething(callback)` pattern, because the page can't hand a callback to the preload. Keep the `ipcRenderer.on` listener in the preload, and have the page ask for the latest value through an exposed async function. See [Forwarding events from the preload](/docs/api/context-bridge#forwarding-events-from-the-preload).
+- Calls have no timeout, as in Electron.
+- The preload and the bridge run in the top frame only, not in iframes.
+
+### `Menu` and `MenuItem`
+
+The application menu bar and context menus work on all three. `click(menuItem, window, event)` receives the focused window, as in Electron. The `event` argument is empty: no modifier keys, no `triggeredByAccelerator`.
+
+Checkbox and radio items toggle themselves. After a `MenuItem` is built, only `checked` can change. `label` and `enabled` are read-only, so to change one, build the menu again and set it again.
+
+On macOS, an app that sets no menu gets Electron's default one once it is ready: an app menu (About, Hide, Quit), File > Close Window, and the standard Edit and Window menus. So Cmd+Q and copy/paste work out of the box. Call `Menu.setApplicationMenu` (even with `null`) before `ready` to skip it. Linux and Windows get no default menu bar, where Electron gives you one.
+
+Roles (`copy`, `quit`, `minimize` and so on):
+
+- **macOS:** every role works, exactly like the native menu item.
+- **Linux:** the editing roles (undo, redo, cut, copy, paste, delete, select all), the window roles (minimize, close, zoom, toggle fullscreen) and `quit` work. `about`, `hide`, `hideOthers` and `unhide` appear but do nothing when clicked.
+- **Windows:** the window roles and `quit` work. The editing roles and `about`, `hide`, `hideOthers` and `unhide` appear but do nothing, because WinCairo has no call for editing commands like copy and paste.
+
+Keyboard shortcuts (`accelerator`) work on macOS only. On Linux and Windows the shortcut is neither bound nor shown next to the label, so pressing it does nothing. If you need one there today, listen for the key in your page and tell main over IPC.
+
+`popup()`:
+
+- On macOS and Windows, `popup()` doesn't return until the menu closes. On Linux it returns right away.
+- There is no `callback` option and no `menu-will-close` event.
+- `x` and `y` are relative to the window's content area and default to its top-left corner, not the mouse position. To open a context menu at the mouse, pass the position from the page's `contextmenu` event (`clientX`, `clientY`).
+
+### `dialog`
+
+Open, save, message and error dialogs work on all three. Every method returns a `Promise`. There are no `*Sync` variants.
+
+- **Every OS:** you can pass a window as the first argument, as in Electron, so ported code runs. The window is ignored, though. Dialogs open as separate windows, never as sheets attached to yours.
+- **Every OS:** `showErrorBox` doesn't wait for the user to close it, where Electron's does.
+- **Linux:** a message box's `type` (`info`, `warning`, `error` and so on) has no effect, because GTK's alert dialog has no severity icon.
+- **Windows:** message boxes can only show Windows' standard buttons, so your labels are replaced.
+ - One button shows OK.
+ - Two show OK/Cancel if one of yours is labeled "Cancel" or "No", otherwise Yes/No.
+ - Three or more show Yes/No/Cancel. A fourth button onward can't be reached.
+ - The result is still your button's index. Cancel and Esc return your "Cancel" or "No" button (or `0` if you have none). Yes/OK and No return your other buttons, in order. For example, `['Save', "Don't Save", 'Cancel']` shows Yes/No/Cancel and returns `0`, `1` and `2`.
+- **Windows:** the folder picker ignores `defaultPath`. A save dialog's `defaultPath` can be a file name or a full file path, but not a bare folder.
+- **Linux and Windows:** one dialog can't pick both files and folders, so `openDirectory` wins over `openFile`, as in Electron.
+
+### `clipboard`
+
+Text, HTML and images work on all three.
+
+Reads (`readText`, `readHTML`, `readImage`) return a `Promise` on every OS, where Electron's are synchronous. GTK 4 on Linux can only read the clipboard asynchronously, and Bunmaska keeps one API everywhere, so `await` your reads. Writes stay synchronous.
+
+The Linux selection clipboard, RTF, bookmarks and the combined `write()` are not implemented.
+
+### `Tray`
+
+- **macOS:** icon, tooltip, title, context menu and the `click` event all work. When a context menu is set, clicking opens the menu, so `click` fires only when no menu is set.
+- **Linux:** off by default. Turn it on with the `BUNMASKA_ENABLE_LINUX_TRAY` [opt-in switch](#linux-opt-in-switches).
+ - When it is off, or the desktop's message bus can't be reached, `new Tray()` still works but shows nothing, so the same code runs on every OS.
+ - When on, the icon uses StatusNotifierItem, the tray standard that KDE, Waybar, swaybar and GNOME (with the AppIndicator extension) draw.
+ - `click` fires when the desktop activates the icon. `setContextMenu` is accepted, but no menu shows yet.
+- **Windows:** icon, tooltip and left-click `click` work. `setContextMenu` is accepted, but no menu shows yet. `setTitle` does nothing, because Windows tray icons have no text. Right-click and double-click are not reported.
+
+On every OS, `click` carries no event, bounds or position.
+
+### `Notification`
+
+`new Notification({ title, body, subtitle, silent }).show()` works on all three. Those four are the only options; others such as `icon`, `actions` and `urgency` are ignored (TypeScript flags them). `silent` is honored everywhere. Changing a property after `show()` doesn't update the notification on screen. `click`, `reply` and `action` events are not delivered on any OS yet.
+
+- **macOS:** notifications only appear from a packaged `.app`. Under `bunmaska dev` or `bun main.ts`, nothing shows and `Notification.isSupported()` returns `false`, so check it first. The `close` event never fires.
+- **Linux:** shown through libnotify. `close` fires when the user or the system dismisses the notification. `subtitle` is ignored.
+- **Windows:** a basic balloon notification from the notification area. `close` fires when it is dismissed. `subtitle` becomes the first line of the body. Rich notifications with buttons, images or replies are still to come.
+
+### `nativeImage`
+
+Loading an image (from a path, a buffer or a data URL), encoding it as PNG or JPEG, `resize` and `crop` all work on all three. `toJPEG` defaults `quality` to `92`, where Electron requires you to pass it.
+
+- **Windows:** `toJPEG(quality)` ignores `quality` and uses the encoder's default. `.ico` files get no special handling, so which of the icon's sizes you get is up to Windows. Pass PNG or JPEG instead.
+- **Every OS:** `resize` accepts Electron's `quality` hint, but it doesn't pick a different scaling algorithm.
+- **macOS only:** template images (`setTemplateImage`) recolor for light and dark menu bars. Elsewhere the flag is kept but has no visible effect.
+
+### `nativeTheme`
+
+`shouldUseDarkColors` reads the real OS setting on all three. `themeSource` can force `'light'` or `'dark'` on all three: `shouldUseDarkColors` follows it, and setting it always emits `updated`.
+
+- **macOS:** forcing `themeSource` also restyles your windows, and the page's `prefers-color-scheme` follows. When the user switches dark mode, `updated` fires.
+- **Linux:** when the user switches dark mode, `updated` fires. Forcing `themeSource` only changes what `shouldUseDarkColors` reports. Native widgets and the page's `prefers-color-scheme` don't follow, so drive your page's theme from `shouldUseDarkColors`.
+- **Windows:** forcing `themeSource` works as on Linux. Windows doesn't tell Bunmaska when the user switches dark mode, so `updated` doesn't fire for it. `shouldUseDarkColors` reads the setting fresh each time, so checking it again (for example when a window gains focus) picks up the change.
+- **Linux and Windows:** `prefersReducedTransparency` is always `false`.
+
+### `globalShortcut`
+
+System-wide shortcuts that fire even when your app is not focused.
+
+- **macOS:** works, even when the app is not packaged.
+- **Windows:** works.
+- **Linux:** works under X11 only. Linux desktops run on one of two display systems, X11 or Wayland, and Ubuntu and Fedora default to Wayland. Under Wayland, `register` returns `false` and nothing is grabbed, even through XWayland. Supporting Wayland means asking the desktop for permission through its global-shortcuts service, which Bunmaska doesn't do yet. Check the return value of `register` and offer an in-app shortcut as a fallback. Under X11, shortcuts fire regardless of NumLock and CapsLock.
+- **Every OS:** media and volume keys (`MediaPlayPause`, `VolumeUp` and friends) parse, but `register` returns `false` for them. The numpad keys and `Insert` work. An accelerator that can't be parsed makes `register` return `false` instead of throwing.
+
+### `shell`
+
+`openExternal`, `openPath`, `showItemInFolder` and `beep` work on all three.
+
+- **Linux:** `showItemInFolder` opens the folder that contains the item, but can't highlight the item itself.
+- **macOS and Windows:** `showItemInFolder` quietly does nothing for a path it can't use: an empty path on macOS, and on Windows a relative path or one containing a double quote. Pass an absolute path, for example from `path.resolve`.
+- **Every OS:** `openExternal` resolves to `true` or `false` instead of rejecting, and takes no options. It needs a full URL with a scheme, such as `https://...` or `mailto:...`. A bare file path or program name resolves to `false`. Open files with `shell.openPath`.
+
+`trashItem` is not implemented on any OS.
+
+### `protocol`
+
+Serve your own URL scheme, such as `app://`, from the main process, so bundled files load without a local HTTP server.
+
+- **macOS and Linux:** works.
+- **Windows:** engine-blocked. WinCairo has no way to plug in a custom URL scheme. `protocol.handle` still registers without an error, but requests to the scheme are never served, and creating a window while a scheme is registered logs a warning. On Windows, load your files with `loadFile` instead.
+
+On every OS:
+
+- Custom schemes only. `handle` throws `InvalidArgumentError` for `http`, `https`, `file` and the other schemes WebKit serves itself. Electron can intercept those. WebKit can't.
+- Register the scheme before you create the window that uses it. A web view reads the list of schemes once, when it is created.
+- The handler receives only `{ url }`, with no method, headers or body. It must return synchronously: `{ data, mimeType }`, where `data` is a string or bytes and `mimeType` defaults to `text/html`. You can't set a status code or headers.
+- Return `undefined` and the request fails with a network error. There is no 404.
+- An Electron handler like `async (req) => new Response(...)` has to be rewritten, for example with `readFileSync`.
+
+`registerSchemesAsPrivileged` and per-session protocols are not implemented.
+
+### `screen`
+
+Listing displays with their bounds, scale factor and multi-monitor positions works on all three. Coordinates start at the top-left corner of the primary display.
+
+On every OS, `screen` emits no events: no `display-added`, `display-removed` or `display-metrics-changed`. It is a plain object, not an `EventEmitter`. Call `getAllDisplays()` again when you need fresh data.
+
+- **macOS:** `getCursorScreenPoint()` and `workArea` (the screen minus the menu bar and Dock) are real, and so are `rotation` and `internal`.
+- **Windows:** `getCursorScreenPoint()` and `workArea` (the screen minus the taskbar) are real. `rotation` is always `0` and `internal` is always `false`.
+- **Linux:**
+ - `getCursorScreenPoint()` always returns `{ x: 0, y: 0 }`.
+ - `workArea` equals `bounds`, so desktop panels are not subtracted.
+ - `rotation` is always `0` and `internal` is always `false`.
+ - GTK 4 has no primary monitor, so `getPrimaryDisplay()` returns the first one.
+ - Display ids are just positions in the list (`0`, `1`, `2` and so on). After a monitor is plugged in or removed, the same id can point to a different display, so don't store them.
+ - Fractional scale factors such as `1.5` need GTK 4.14 or later. Older GTK reports a whole number.
+
+### `powerMonitor`
+
+The `suspend`, `resume`, `lock-screen` and `unlock-screen` events work on all three. The rest of Electron's `powerMonitor` is missing on every OS: no `getSystemIdleTime` or `getSystemIdleState`, no `isOnBatteryPower` or `on-ac` / `on-battery`, no `shutdown` event and no thermal state.
+
+- **Linux:** off by default. Turn it on with the `BUNMASKA_ENABLE_LINUX_POWER` [opt-in switch](#linux-opt-in-switches). It also needs systemd-logind, Linux's login manager, on the system message bus. With it off, no events fire.
+ - `suspend` is best-effort. Bunmaska doesn't ask the system to wait for it, so the event can arrive after the machine wakes. Don't count on it to finish work before the lid closes.
+ - `lock-screen` and `unlock-screen` fire only when the lock goes through logind, for example `loginctl lock-session`. Lock screens that lock without telling logind don't trigger them, so test on the desktops you target before relying on these events.
+- **Windows:** Windows sometimes refuses the lock listener, usually when the app starts right at login. Bunmaska then logs a warning, and `lock-screen` and `unlock-screen` stay silent until the app restarts.
+
+### `powerSaveBlocker`
+
+`start`, `stop` and `isStarted` work on all three. `start()` always returns an id, even when nothing native happens, so your code never has to handle `-1`.
+
+- **macOS and Windows:** both `prevent-app-suspension` and `prevent-display-sleep` work. They block idle sleep only, as in Electron: closing the lid or choosing Sleep still puts the machine to sleep.
+- **Linux:** off by default. Turn it on with the `BUNMASKA_ENABLE_LINUX_POWER_BLOCKER` [opt-in switch](#linux-opt-in-switches), which is separate from `BUNMASKA_ENABLE_LINUX_POWER`. With it off, `start()` returns an id and does nothing. With it on, both types do the same thing: they ask the desktop to hold off the screen saver and idle sleep.
+
+### `safeStorage`
+
+`isEncryptionAvailable`, `encryptString` and `decryptString` work. Strings are encrypted with AES-256-GCM, so a tampered blob makes `decryptString` throw instead of returning garbage.
+
+- **macOS:** the key lives in the Keychain.
+- **Windows:** the key is sealed with DPAPI, Windows' built-in per-user encryption. It is stored as `safestorage.key` in the folder `BUNMASKA_HOME` names, or in `.bunmaska` in the user's home folder when that isn't set.
+- **Linux:** off by default. Turn it on with the `BUNMASKA_ENABLE_LINUX_KEYRING` [opt-in switch](#linux-opt-in-switches) to keep the key in the desktop keyring through libsecret.
+ - With it off, or with no keyring, `isEncryptionAvailable()` returns `false` and `encryptString` / `decryptString` throw.
+ - If the keyring is locked, the first `encryptString` or `decryptString` waits for the user to unlock it, and your main process is frozen until they do.
+
+Two differences from Electron on every OS:
+
+- **One key is shared by every Bunmaska app of the same user.** Electron keeps one per app. Any other Bunmaska app the same user runs can decrypt your app's data (macOS may ask the user first). Treat `safeStorage` as protection against other users and a stolen disk, not against other apps. A separate key per app is on the [to-do list](#still-to-do).
+- **There is no plaintext fallback.** Without a keyring, Electron falls back to a weak built-in key. Bunmaska refuses and throws instead. Blobs are Bunmaska's own format and can't be read by Electron.
+
+### `session`
+
+There is one session, `session.defaultSession`. Partitions (`fromPartition`, `fromPath`) are not implemented.
+
+- **Every OS:** `setUserAgent` sets the User-Agent for windows created after the call. Use `webContents.setUserAgent` for a window that already exists. `getUserAgent()` returns `''` until you set one, where Electron returns the default.
+- **macOS and Linux:** `cookies.get`, `set` and `remove` work, matching cookies the way browsers do (RFC 6265).
+ - `httpOnly` and `secure` are kept.
+ - `sameSite` isn't supported: `set` ignores it (TypeScript flags it) and `get` doesn't report it. On macOS, every cookie you set is stored as `lax`.
+ - `cookies.set` defaults `path` to `/`, not the URL's directory.
+- **Windows:** every `cookies` method rejects with `UnsupportedPlatformError`. WinCairo has no way to read or write a single cookie; it can only delete them all.
+- **`clearStorageData()`:**
+ - macOS clears all website data: cookies, caches, local storage, IndexedDB and the rest. Pages that are still open keep their in-memory cache until they reload.
+ - Windows clears cookies and Cache API storage (`caches`) only, not the HTTP cache, local storage or IndexedDB.
+ - Linux rejects with `UnsupportedPlatformError`. It is not wired up yet.
+ - On every OS, passing the `origin` or `storages` options rejects rather than quietly clearing everything.
+- **macOS, in development:** every Bunmaska app you run unpackaged (`bunmaska dev`, `bun main.ts`) shares one cookie jar and one set of web storage, across all your projects, because they all run as the same `bun` process. Logins and `localStorage` from one project show up in another. A packaged `.app` gets its own.
+
+### `autoUpdater`
+
+Your app can update itself on all three OSes. It doesn't use Squirrel, the update framework Electron relies on. Updating takes three steps.
+
+1. **Check.** `checkForUpdates()` fetches `update.json` from your update feed and compares versions. Unlike Electron, it doesn't download anything. Call `downloadUpdate()` when `update-available` fires.
+2. **Download and verify.** `downloadUpdate()` accepts only an update it can prove came from you.
+ - **Setup:** `bunmaska keygen` makes a key pair, and `bunmaska build --update --update-key ` signs each release.
+ - **Check:** before trusting an update, the app checks a signature on `update.json` and one on the downloaded file, against the public key you pass to `setFeedURL({ url, publicKey })`. The file's size and hash must also equal the ones listed in the signed `update.json`.
+ - **Why:** a hacked or spoofed update server can't push its own code to your users. A feed without valid signatures is refused.
+3. **Install.** `quitAndInstall()` quits your app, then a small helper program swaps in the new version and starts it. If any step of the swap fails, the helper starts the old version again, so users are never left without a working app.
+
+What to know before you ship:
+
+- The install step is tested piece by piece, but our CI doesn't run a complete live update on a real install yet. Test your own update path end to end.
+- `quitAndInstall()` can only replace the app layouts `bunmaska build` produces: the macOS `.app`, the Linux `.tar.gz` folder and the Windows portable folder. Anywhere else it throws without quitting. That includes `bunmaska dev`, `bun main.ts`, and a `.deb` install, whose files belong to the system's package manager. Ship `.deb` updates through your apt repository instead.
+- The swap renames the folder your app lives in, so the user needs write access to it. If they don't have it (for example, the app sits under `C:\Program Files`), the swap fails and the old version starts again.
+- `checkForUpdates()` rejects, and emits `error`, while the app's version is `0.0.0`. That is what `app.getVersion()` returns when your `package.json` has no `version`. An app that can't tell its own version would reinstall the same update forever, so set `version`.
+- Each feed folder serves one OS and CPU architecture. If its `update.json` is for another OS or architecture, `checkForUpdates()` rejects and emits `error`. Host one folder per OS and architecture, and point `setFeedURL` at the matching one.
+- The feed URL must be `https`. Plain `http` is allowed for `localhost` only, for testing.
+- A `before-quit`, window `close` or `will-quit` listener that cancels the quit keeps the app running. The helper waits and installs once the app does exit.
+- `before-quit-for-update` is not emitted. `update-downloaded` passes a single `{ version, releaseName }` object, without Electron's release notes, date or URL.
+
+The full publishing flow is on the [autoUpdater page](/docs/api/auto-updater) and in [Building & Distribution](/docs/building#auto-updates).
+
+### Accelerator strings and `app.getPath`
+
+Accelerator strings such as `CmdOrCtrl+Shift+K` parse the same way on all three. `CmdOrCtrl` means Command on macOS and Control elsewhere. Whether a shortcut actually fires depends on where you use it: see [`Menu`](#menu-and-menuitem) and [`globalShortcut`](#globalshortcut).
+
+`app.getPath` resolves every name it supports on all three. On Linux the user folders (`desktop`, `documents`, `downloads` and so on) come from the XDG settings, so localized folder names work. `recent` and `assets` are not supported.
+
+### `requestSingleInstanceLock`
+
+- **macOS and Linux:** works like Electron. A second launch passes its arguments, working directory and `additionalData` to the first instance as a `second-instance` event, never before `ready`.
+- **Windows:** the lock itself is a plain file. The hand-off that fires `second-instance` in the first copy goes over a Unix domain socket (a local socket file), which hasn't been tested on Windows. If you rely on `second-instance`, for example to focus your window or open a file the user double-clicked, test it on Windows before you ship.
+
+## Why some things can't work on an OS
+
+These gaps aren't laziness. The platform underneath doesn't offer the piece Bunmaska would need.
+
+### Windows: WinCairo is missing three entry points
+
+WinCairo's programming interface lacks three things other WebKit builds have:
+
+- **A custom URL scheme handler,** so `protocol` can't serve `app://` and friends.
+- **PDF export.** The call macOS uses exists only in Apple's WebKit, so `printToPDF` has nothing to call.
+- **A page snapshot from the app's side.** WinCairo's only snapshot calls run inside the web page's own process, which the app can't reach, so `capturePage` has nothing to call.
+
+We confirmed each one by reading the list of functions `WebKit2.dll` exports. They become possible only if WinCairo adds them upstream.
+
+The same interface explains two smaller Windows gaps. It can delete all cookies but not read or write one, which is why `session.cookies` rejects. It has no call for editing commands, which is why the copy and paste menu roles do nothing.
+
+### Linux: the desktop owns window placement
+
+GTK 4 removed the calls that let an app move its own window, and Wayland forbids it outright. The desktop decides where windows go and doesn't tell the app. That is why `setPosition`, `center`, the `x` and `y` of `getBounds`, the `move` event and `setAlwaysOnTop` don't work on Linux.
+
+## Still to do
+
+Gaps inside modules that already ship. We're filling them. Gaps mentioned above but not listed here, such as `sendInputEvent` on macOS and Linux, parent and child windows, `trashItem`, `MessagePort`, session partitions and `printToPDF` options, have no date yet.
+
+**Every OS**
+
+- `getSystemIdleTime` and `isOnBatteryPower` in `powerMonitor`.
+- `click`, `reply` and `action` events for notifications.
+- Display-change events in `screen`.
+- Media and volume keys for `globalShortcut`.
+- Child windows, so `setWindowOpenHandler` can `allow`.
+- A separate `safeStorage` key per app.
+- Richer `webContents` events.
+
+**macOS**
+
+- The `close` event for notifications.
+
+**Linux**
+
+- `session.clearStorageData`.
+- `printToPDF`.
+- The tray context menu.
+- Menu keyboard shortcuts.
+- The minimized state, and the `minimize` and `restore` events.
+- The cursor position and the work area in `screen`.
+- Global shortcuts under Wayland.
+- Your app's name and version in the about dialog.
+
+**Windows**
+
+- The `setWindowOpenHandler` callback.
+- DevTools.
+- Live dark-mode changes in `nativeTheme`.
+- The tray context menu.
+- Menu keyboard shortcuts.
+- An isolated world for the preload.
+- JPEG quality in `nativeImage`.
+- Rich notifications.
+- Modifier keys, more keys and scaled displays in `sendInputEvent`.
+- A test of the single-instance lock.
+- Continuous `move` and `resize` events while the user drags.
+
+## Where Bunmaska behaves differently from Electron
+
+Differences in behavior today, on every OS unless noted. Some are by design, like JSON IPC and async `contextBridge`. Others, like the shared `safeStorage` key, are on the list to fix. Each is also documented on its API page.
+
+- **IPC is JSON, not structured clone.** `Map`, `Set`, `ArrayBuffer`, typed arrays, functions, symbols and `bigint` throw in both directions. A `Date` arrives as a string, and a `Buffer` sent from main arrives as `{ type, data }`. `ipcRenderer.sendSync` doesn't exist. See [ipcRenderer](/docs/api/ipc-renderer#ipcrenderersendchannel-args).
+- **`contextBridge` functions are always async** on the page side, and `ipcRenderer` exists only in the preload on macOS and Linux.
+- **`protocol.handle` serves custom schemes only**, and its handler returns `{ data, mimeType }` synchronously instead of a `Response`. Electron can intercept `http`, `https` and `file`.
+- **The default application menu exists on macOS only.** Linux and Windows get no menu bar until you set one.
+- **`app.quit()` runs no `beforeunload` handlers.** Only main-process listeners and window `close` listeners can cancel it.
+- **The `ready` event passes no arguments.**
+- **`app.setPath` does not require the folder to exist.**
+- **On macOS and Windows, `getPreferredSystemLanguages()` returns a single entry**, the same value as `getLocale()`.
+- **`BrowserWindow.fromId` returns `undefined`** for an unknown id, not `null`.
+- **`dialog`'s open, save and message methods return Promises** (no `*Sync` variants) and ignore the parent window. `showErrorBox` doesn't block. On Windows a save dialog's `defaultPath` can't be a bare folder.
+- **`clipboard`, `shell` and `nativeImage` work in the main process only.** Call them there and expose what the page needs through IPC. Clipboard reads return Promises.
+- **`shell.openExternal` resolves `true` or `false`** instead of rejecting on failure.
+- **`cookies.set` defaults `path` to `/`**, not the URL's directory, and `session.getUserAgent()` returns `''` until you set one.
+- **`safeStorage` shares one key across all Bunmaska apps** of a user, on all three OSes, and has no plaintext fallback.
+- **`autoUpdater` doesn't download on its own.** You call `downloadUpdate()`, and `before-quit-for-update` is not emitted.
+- **`MenuItem` properties are read-only** after construction, except `checked`.
+- **`screen` is not an `EventEmitter`.**
## Out of scope by design
-Chromium-internal surfaces - not coming, and that's deliberate:
+Bunmaska doesn't bundle Chromium, and these features are not planned. Most belong to Chromium itself. That's deliberate:
+
+`BrowserView` / `WebContentsView` (several web views inside one window) · `desktopCapturer` · `net` / `netLog` · `webRequest` / proxy · `crashReporter` · `contentTracing` · `utilityProcess` · `TouchBar` · `inAppPurchase` · Chrome extensions · `pushNotifications` · Web Serial / WebHID / WebUSB.
-`BrowserView` / `WebContentsView` (single-process) · `desktopCapturer` · `net` / `netLog` · `webRequest` / proxy · `crashReporter` · `contentTracing` · `utilityProcess` · `TouchBar` · `inAppPurchase` · extensions · `pushNotifications` · Web Serial / WebHID / WebUSB.
+For two of them, Bun already has the replacement. Instead of `net`, use `fetch` in the main process. Instead of `utilityProcess`, use `Bun.spawn` or a `Worker`.
-> If a cell you need is , , or in "pending," now you know - before you've ported half your app. That's the whole reason this page exists.
+> If a cell you need is , , or listed under "Still to do", now you know, before you've ported half your app. That's the whole reason this page exists.