Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 19 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Bun Maska

> Dip your Electron in some fresh Bun Maska. Built on Bun and your operating system's own WebKit, because shipping 150 MB of Chromium with every desktop app is one of those ideas that made sense in 2013 and has been quietly ruining lives ever since.
> The bread and butter of desktop apps: Electron's familiar APIs on Bun and your operating system's own WebKit. No bundled Chromium — because shipping 150 MB of browser with every app is one of those ideas that made sense in 2013 and has been quietly ruining laptop fans ever since.

## What

Expand Down Expand Up @@ -28,9 +28,22 @@ Your laptop fan has strong opinions about RAM. Your users have data caps and lim

Honest measured numbers: a packaged Bun Maska app is roughly a **16–23 MB download** and lands at about **61 MB on disk** once Bun unpacks itself. The equivalent minimal Electron app starts north of 150 MB and only grows from there. Updates are tiny because there is no 150 MB engine to re-download. Your OS already patches WebKit. We do not make you participate in the Chromium CVE re-shipping treadmill.

## "But then I can't pin the WebKit version"

Fair. By default you render on whatever WebKit the machine already has — that's the whole reason the apps are small. When you'd rather ship the exact build you tested, Bun Maska has a content-addressed engine store: pin an engine in `bunmaska.config`, and at launch the app resolves *that* build from `~/.bunmaska/webkit/<id>/` — downloaded once, shared by every app, so they stay tiny. Different apps can pin different versions and run side by side; there is no global "switch the version for everything" footgun. If the pinned engine isn't there, the app quietly falls back to the system WebKit and tells you so.

```sh
bunmaska engine list # what's installed, side by side
bunmaska engine which # the engine this project resolves
bunmaska engine install … # a local build, or a signature- and hash-verified URL
bunmaska doctor # runtime, store, and the resolved pin
```

Where this honestly is: the resolve → store → load path is built and **proven on Linux** — an app loads its pinned WebKit from the store instead of the system one, verified in CI. The part still in progress is *publishing* the prebuilt engine binaries to install from. macOS pinning is designed and feasible (it just means shipping our own signed `WebKit.framework`); Windows is its own saga (below). So the plumbing is real; the hosted engines are the next milestone, not a finished promise.

## Status

**Alpha.** Held together with optimism, `strict: true`, and 1,380 tests that were green the last time CI ran.
**Alpha.** Held together with optimism, `strict: true`, and roughly 1,400 tests that were green the last time CI ran.

It works properly on both **macOS** and **Linux** today. You get real native windows, system WebKit rendering, full Electron-style IPC with context isolation, application and context menus, tray icons, dialogs, clipboard (text + HTML + images), `nativeImage`, `safeStorage`, `powerMonitor`, `printToPDF`, `capturePage`, and a growing list of other modules — all implemented with pure `bun:ffi` and zero compiled code in the framework.

Expand All @@ -43,7 +56,7 @@ If you are already running this in production, we admire your courage and declin
We are not going to sell you a fantasy.

- **Single process.** No Chromium sandbox. No per-window crash isolation. A nasty WebKit or JavaScriptCore crash takes the whole app with it. This is the architectural price of the lightness.
- **No Windows support yet.** We are waiting for a usable WebKit port on Windows that does not involve shipping Chromium. We are aware this is a hill. We are comfortable dying on it.
- **No Windows support yet.** Windows ships no system WebKit, so doing it our way means bringing our own — WinCairo WebKit, not WebView2 (that's Chromium with extra steps). It's deferred, not abandoned, and it lands behind macOS + Linux. We are aware this is a hill. We are comfortable dying on it.
- **~70–80% weighted API parity** for the things most real apps actually use. The long tail (`BrowserView`, sync IPC, Web Serial/WebHID/WebUSB from the renderer, deeply Chromium-internal surfaces) is either out of scope by design or will throw a clear error so you know immediately what is missing.

## Platforms
Expand All @@ -52,7 +65,7 @@ We are not going to sell you a fantasy.
|---------|------------------------------------------------------------------------|
| macOS | Actively developed — AppKit + WKWebView via `objc_msgSend` and hand-built ObjC blocks |
| Linux | Actively developed — GTK 4 + WebKitGTK 6 via `dlopen` |
| Windows | Deferred. We will not ship Chromium. |
| Windows | Deferred will bring WinCairo WebKit, never WebView2/Chromium |

## Install

Expand Down Expand Up @@ -92,6 +105,8 @@ bunmaska dev # run with file watching and auto-restart
bunmaska run main.ts # just run it
bunmaska build # produce distributables for the current OS
bunmaska build --update # also emit the auto-update feed (update.json + .tar.zst)
bunmaska engine list # manage the pinned-WebKit engine store (install/which/prune/…)
bunmaska doctor # report the runtime, the store, and the resolved engine
```

## Migrating from Electron
Expand Down
Loading