From 7a336f64f9e82c9cacd6409c74009340ab439504 Mon Sep 17 00:00:00 2001 From: indrajeetor Date: Mon, 15 Jun 2026 00:22:50 -0700 Subject: [PATCH] docs: reflect the engine store + fix the tagline in the README --- README.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 945fbd1..8dfdaa0 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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//` — 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. @@ -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 @@ -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 @@ -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