electrobun 1.18.4-beta.12 → 1.18.4-beta.18

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://electrobun.dev"><img src="https://github.com/blackboardsh/electrobun/assets/75102186/8799b522-0507-45e9-86e3-c3cfded1aa7c" alt="Logo" height=170></a>
+  <a href="https://framework.blackboard.sh/electrobun/"><img src="https://github.com/blackboardsh/electrobun/assets/75102186/8799b522-0507-45e9-86e3-c3cfded1aa7c" alt="Logo" height=170></a>
 </p>
 
 <h1 align="center">Electrobun</h1>
@@ -13,28 +13,33 @@
 
 ## What is Electrobun?
 
-Electrobun aims to be a complete **solution-in-a-box** for building, updating, and shipping ultra fast, tiny, and cross-platform desktop applications written in Typescript.
-Under the hood it uses Cottontail, Electrobun's JSC-based JavaScript runtime, to execute the main process and bundle webview TypeScript. Native bindings are written in ObjC and C++, with several core components written in <a href="https://ziglang.org/">Zig</a>.
+Electrobun aims to be a complete **solution-in-a-box** for building, updating, and shipping fast, compact, cross-platform desktop applications written in TypeScript.
+Hutch is the native build and package-management CLI. Cottontail is Electrobun's JSC-based default JavaScript runtime. Electrobun's platform layer combines Zig, Objective-C, and C++.
 
 Visit <a href="https://framework.blackboard.sh/electrobun/">https://framework.blackboard.sh/electrobun/</a> to see api documentation, guides, and more.
 
-You use it via npm.
+Install Hutch globally, then use it to create a project, install the npm package that provides Electrobun's SDKs, and build the application:
+
+```bash
+curl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh
+hutch electrobun init
+```
 
 Don't miss our:
-- self-extracting bundles that use ZSTD compression for more compact distributables as small as 16MB
-- zig optimized BSDIFF implementation that lets you ship tiny app updates as small as 4KB
+- self-extracting bundles that use Zstandard compression for compact distributables
+- a Zig-optimized BSDIFF implementation that can produce kilobyte-scale updates
 - `bundleCEF` flag to bundle and pin Chromium for those that want that tradeoff of consistency over file size
 - `bundleWGPU` that lets you use Bun Typescript -> WGPU to control a native GPU surface without a webview
 - Our Three.js and Babylon.js adapters that work directly in the Cottontail main process
-- Our `<electrobun-webview>` and `<electrobun-wpgu>` html elements that let you composit proper OOPIFs and native GPU surfaces into your UIs
+- Our `<electrobun-webview>` and `<electrobun-wgpu>` HTML elements that let you composite isolated webviews and native GPU surfaces into your UIs
 - so much more.
 
 **Project Goals**
 
 - Write typescript for the main process and webviews without having to think about it.
 - Isolation between main and webview processes with fast, typed, easy to implement RPC between them.
-- Small self-extracting app bundles ~14MB (when using the system webview, most of this is the Cottontail/JSC runtime)
-- Even smaller app updates as small as 4KB (using bsdiff it only downloads tiny patches between versions)
+- Small self-extracting app bundles when using the system webview
+- Small updates that use binary patches before falling back to a compressed full download
 - Provide everything you need in one tightly integrated workflow to start writing code in 5 minutes and distribute in 10.
 
 ## Apps Built with Electrobun
@@ -59,6 +64,8 @@ Don't miss our:
 - [dotlock](https://github.com/tsconfigdotjson/dotlock) - macOS desktop app for managing `.env` files across your projects
 - [electrobun-pdf](https://github.com/GijungKim/electrobun-pdf) - local-first PDF & DOCX editor for opening, annotating, and exporting documents without leaving your machine
 - [electrobun-rms](https://github.com/khanhthanhdev/electrobun-rms) - fast Electrobun desktop app template with React, Tailwind CSS, and Vite
+- [FLACK](https://github.com/BLCK-B/FLACK) - local audio player for Windows
+- [gloomberb](https://gloom.sh) - financial terminal for the rest of us
 - [golb](https://github.com/chrisdadev13/golb) - desktop AI coding workspace built with React, Vite, and Tailwind
 - [GOG Achievements GUI](https://github.com/timendum/gog-achievements-gui) - desktop app for managing GOG achievements
 - [groov](https://github.com/laurenzcodes/groov) - desktop audio deck monitor
@@ -142,6 +149,12 @@ On Windows PowerShell:
 
 On Ubuntu/Debian based distros: `sudo apt install build-essential cmake pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev`
 
+Linux applications also require the corresponding GTK 3, WebKitGTK 4.1,
+Ayatana AppIndicator, and librsvg runtime packages on end-user systems. See the
+[cross-platform development guide](./docs/src/content/docs/electrobun/guides/cross-platform-development.mdx#linux)
+for distro-specific install commands. The launcher reports the exact missing
+shared library when these dependencies are unavailable.
+
 ### First-time Setup
 
 ```bash
@@ -164,6 +177,11 @@ hutch dev
 hutch dev:clean
 ```
 
+The native build generates `package/src/native/compile_flags.txt` from the
+compiler flags resolved for the current machine. clangd-compatible editors
+discover it automatically; rerun the build after changing native dependencies
+or system toolchains.
+
 With sibling `jsc`, `cottontail`, `dash-cloud`, and `electrobun` checkouts, use
 one command to build only changed native layers and run Kitchen with the local
 stack:
@@ -194,6 +212,6 @@ All commands are run from the `/package` directory:
 |---|---|
 | macOS 14+ | Official |
 | Windows 11+ | Official |
-| Ubuntu 22.04+ | Official |
+| Ubuntu 24.04+ | Official |
 | Other Linux distros (gtk3, webkit2gtk-4.1) | Community |
 | Raspberry Pi | Unofficial fork: [kortexa-ai/electrobun (linux-wpe)](https://github.com/kortexa-ai/electrobun/tree/kortexa/linux-wpe) — follow the author [@francip](https://x.com/francip/status/2050149256053539059?s=20) |

package/bun.lock

@@ -7,6 +7,7 @@
       "dependencies": {
         "@babylonjs/core": "^7.45.0",
         "@types/bun": "^1.3.8",
+        "@types/three": "^0.165.0",
         "png-to-ico": "^2.1.8",
         "proxy-agent": "^6.5.0",
         "rcedit": "^4.0.1",
@@ -24,10 +25,18 @@
 
     "@tootallnate/quickjs-emscripten": ["@tootallnate/quickjs-emscripten@0.23.0", "", {}, "sha512-C5Mc6rdnsaJDjO3UpGW/CQTHtCKaYlScZTly4JIu97Jxo/odCiH0ITnDXSJPTOrEKk/ycSZ0AOgTmkDtkOsvIA=="],
 
+    "@tweenjs/tween.js": ["@tweenjs/tween.js@23.1.3", "", {}, "sha512-vJmvvwFxYuGnF2axRtPYocag6Clbb5YS7kLL+SO/TeVFzHqDIWrNKYtcsPMibjDx9O+bu+psAy9NKfWklassUA=="],
+
     "@types/bun": ["@types/bun@1.3.8", "", { "dependencies": { "bun-types": "1.3.8" } }, "sha512-3LvWJ2q5GerAXYxO2mffLTqOzEu5qnhEAlh48Vnu8WQfnmSwbgagjGZV6BoHKJztENYEDn6QmVd949W4uESRJA=="],
 
     "@types/node": ["@types/node@17.0.45", "", {}, "sha512-w+tIMs3rq2afQdsPJlODhoUEKzFP1ayaoyl1CcnwtIlsVe7K7bA1NGm4s3PraqTLlXnbIN84zuBlxBWo1u9BLw=="],
 
+    "@types/stats.js": ["@types/stats.js@0.17.4", "", {}, "sha512-jIBvWWShCvlBqBNIZt0KAshWpvSjhkwkEu4ZUcASoAvhmrgAUI2t1dXrjSL4xXVLB4FznPrIsX3nKXFl/Dt4vA=="],
+
+    "@types/three": ["@types/three@0.165.0", "", { "dependencies": { "@tweenjs/tween.js": "~23.1.1", "@types/stats.js": "*", "@types/webxr": "*", "fflate": "~0.8.2", "meshoptimizer": "~0.18.1" } }, "sha512-AJK8JZAFNBF0kBXiAIl5pggYlzAGGA8geVYQXAcPCEDRbyA+oEjkpUBcJJrtNz6IiALwzGexFJGZG2yV3WsYBw=="],
+
+    "@types/webxr": ["@types/webxr@0.5.24", "", {}, "sha512-h8fgEd/DpoS9CBrjEQXR+dIDraopAEfu4wYVNY2tEPwk60stPWhvZMf4Foo5FakuQ7HFZoa8WceaWFervK2Ovg=="],
+
     "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
     "ast-types": ["ast-types@0.13.4", "", { "dependencies": { "tslib": "^2.0.1" } }, "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w=="],
@@ -54,6 +63,8 @@
 
     "esutils": ["esutils@2.0.3", "", {}, "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g=="],
 
+    "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="],
+
     "get-uri": ["get-uri@6.0.5", "", { "dependencies": { "basic-ftp": "^5.0.2", "data-uri-to-buffer": "^6.0.2", "debug": "^4.3.4" } }, "sha512-b1O07XYq8eRuVzBNgJLstU6FYc1tS6wnMtF1I1D9lE8LxZSOGZ7LhxN54yPP6mGw5f2CkXY2BQUL9Fx41qvcIg=="],
 
     "http-proxy-agent": ["http-proxy-agent@7.0.2", "", { "dependencies": { "agent-base": "^7.1.0", "debug": "^4.3.4" } }, "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig=="],
@@ -70,6 +81,8 @@
 
     "lru-cache": ["lru-cache@7.18.3", "", {}, "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA=="],
 
+    "meshoptimizer": ["meshoptimizer@0.18.1", "", {}, "sha512-ZhoIoL7TNV4s5B6+rx5mC//fw8/POGyNxS/DZyCJeiZ12ScLfVwRE/GfsxwiTkMYYD5DmK2/JXnEVXqL4rF+Sw=="],
+
     "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
 
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],

package/dash.config.ts

@@ -1,13 +1,14 @@
-// @dash cli=0.3.1 cottontail=0.2.3
+// @dash cli=0.5.0-canary.8 cottontail=0.2.3
 export default {
 	scripts: {
-		start: "hutch src/sdks/bun/index.ts",
+		start: "hutch src/sdks/main/index.ts",
 		"check-zig-version": "vendors/zig/zig version",
 		"check-rust-version": "vendors/rust/bin/rustc --version",
 		"build:dev": "hutch build.ts",
 		"build:local": "scripts/build-local.js",
 		"build:release": "hutch build.ts --release",
 		dev: "scripts/dev.ts",
+		"dev:matrix": "scripts/dev-matrix.ts",
 		"dev:test": "scripts/dev.test.ts",
 		"dev:clean": "cd ../kitchen && rm -rf node_modules vendors/cef && cd ../package && hutch dev",
 		"dev:canary": "hutch install && hutch build:release && cd ../kitchen && hutch install && hutch electrobun build --env=canary",
@@ -15,14 +16,40 @@ export default {
 		"build:docs:release": "cd ../docs && hutch run build",
 		"npm:publish": "hutch build:release && npm publish",
 		"npm:publish:beta": "hutch build:release && npm publish --tag beta",
-		typecheck: "./node_modules/.bin/tsc --noEmit && cd ../kitchen && ./node_modules/.bin/tsc --noEmit",
-		"push:beta": "hutch typecheck && node scripts/push-version.js beta",
-		"push:patch": "hutch typecheck && node scripts/push-version.js patch",
-		"push:minor": "hutch typecheck && node scripts/push-version.js minor",
-		"push:major": "hutch typecheck && node scripts/push-version.js major",
-		"push:stable": "hutch typecheck && node scripts/push-version.js stable",
+		typecheck:
+			"node node_modules/typescript/bin/tsc --noEmit && cd ../kitchen && node node_modules/typescript/bin/tsc --noEmit",
+		"check:release": "hutch typecheck && hutch test:templates && hutch test:template-publisher && hutch test:signing && hutch test:deployment-target && hutch test:linux-abi && hutch test:linux-extractor && hutch test:npm-bootstrap && hutch test:release-notes",
+		"push:beta": "hutch check:release && node scripts/push-version.js beta",
+		"push:patch": "hutch check:release && node scripts/push-version.js patch",
+		"push:minor": "hutch check:release && node scripts/push-version.js minor",
+		"push:major": "hutch check:release && node scripts/push-version.js major",
+		"push:stable": "hutch check:release && node scripts/push-version.js stable",
 		"build:push:artifacts": "node scripts/build-and-upload-artifacts.js",
-		"test:unit": "hutch test src/shared src/sdks/bun src/config",
+		"test:dialog-paths-native": "hutch scripts/test-dialog-paths-native.js",
+		"test:linux-cef-idle": "node scripts/test-linux-cef-idle.js",
+		"test:linux-dpi-native": "hutch scripts/test-linux-dpi-native.js",
+		"test:linux-x11-geometry-native":
+			"hutch scripts/test-linux-x11-geometry-native.js",
+		"test:views-url-native": "hutch scripts/test-views-url-native.js",
+		"test:windows-ui-native": "hutch scripts/test-windows-ui-native.js",
+		"test:windows-ui-native-integration":
+			"hutch scripts/test-windows-ui-native.js --require-native-wrapper",
+		"test:unit": "node scripts/run-cottontail-test.js src/shared src/sdks/main src/config src/preload && hutch test:dialog-paths-native && hutch test:linux-dpi-native && hutch test:linux-x11-geometry-native && hutch test:views-url-native && hutch test:webview2-permissions && hutch test:windows-ui-native",
+		"test:linux-native-dialog":
+			"node scripts/run-cottontail-test.js src/shared/linux-native-file-dialog.test.ts && scripts/test-linux-native-file-dialog.sh",
+		"test:cef-debug": "scripts/test-cef-remote-debugging.ts",
+		"test:webview2-permissions": "scripts/test-webview2-permissions.ts",
+		"test:macos-inspector-layout": "scripts/test-macos-inspector-layout.sh",
+		"test:templates": "node scripts/run-cottontail-test.js ../templates/template-manifests.test.ts",
+		"test:template-publisher": "node --test ../scripts/publish-templates.test.mjs",
+		"test:signing": "node scripts/run-cottontail-test.js scripts/verify-macho-code-signing.test.ts",
+		"test:deployment-target": "node scripts/run-cottontail-test.js scripts/verify-macho-deployment-target.test.ts",
+		"test:linux-abi": "node scripts/run-cottontail-test.js scripts/verify-linux-elf-abi.test.ts",
+		"test:linux-extractor": "node scripts/test-linux-adjacent-extractor.mjs",
+		"test:npm-bootstrap": "node scripts/run-cottontail-test.js bin/npm-bootstrap-retirement.test.ts",
+		"test:release-notes": "node scripts/release-notes-contract.test.mjs",
+		"test:spell-check": "node --test src/shared/spell-check.test.js",
+		"test:macos-spell-check": "scripts/test-macos-spell-check.sh",
 		"bump-cef": "hutch scripts/update-cef-version.ts",
 	},
 };

package/dist/api/browser/global.d.ts

@@ -19,6 +19,7 @@ interface MessageHandler {
 
 declare global {
   interface Window {
+    __electrobunPlatform: "linux" | "macos" | "windows";
     __electrobunWebviewId: number;
     __electrobunWindowId: number;
     __electrobunRpcSocketPort: number;
@@ -31,6 +32,7 @@ declare global {
     __electrobunInternalBridge?: MessageHandler;
     __electrobunHostBridge?: MessageHandler;
     __electrobunBunBridge?: MessageHandler;
+    __electrobunSendToHost: (message: unknown) => void;
   }
 }
 

package/dist/api/browser/index.ts

@@ -1,6 +1,7 @@
 import {
 	type RPCSchema,
 	type RPCTransport,
+	type RPCRequestOptions,
 	type ElectrobunRPCSchema,
 	type ElectrobunRPCConfig,
 	type RPCWithTransport,
@@ -18,12 +19,17 @@ const WEBVIEW_ID = window.__electrobunWebviewId;
 const HOST_SOCKET_PORT =
 	window.__electrobunHostSocketPort ?? window.__electrobunRpcSocketPort;
 
+type QueuedHostMessage = {
+	message: string;
+	markSent: () => void;
+};
+
 class Electroview<T extends RPCWithTransport> {
 	hostSocket?: WebSocket;
 	hostSocketCanSend = false;
-	pendingHostSocketMessages: string[] = [];
+	pendingHostSocketMessages: QueuedHostMessage[] = [];
 	flushingHostSocketMessages = false;
-	hostSocketSendQueue: string[] = [];
+	hostSocketSendQueue: QueuedHostMessage[] = [];
 	flushingHostSocketSendQueue = false;
 	// user's custom rpc browser <-> bun
 	rpc?: T;
@@ -119,7 +125,8 @@ class Electroview<T extends RPCWithTransport> {
 
 		socket.addEventListener("close", (_event) => {
 			this.hostSocketCanSend = false;
-			this.pendingHostSocketMessages = [];
+			this.flushHostMessagesViaFallback(this.pendingHostSocketMessages);
+			this.flushHostMessagesViaFallback(this.hostSocketSendQueue);
 			// console.log("Socket closed:", event);
 		});
 	}
@@ -130,7 +137,7 @@ class Electroview<T extends RPCWithTransport> {
 			send(message: unknown) {
 				try {
 					const messageString = JSON.stringify(message);
-					that.sendMessageToHost(messageString);
+					return that.sendMessageToHost(messageString);
 				} catch (error) {
 					console.error("host: failed to serialize message to webview", error);
 				}
@@ -141,20 +148,24 @@ class Electroview<T extends RPCWithTransport> {
 		};
 	}
 
-	async sendMessageToHost(msg: string) {
-		if (this.canSendToHostSocket()) {
-			this.hostSocketSendQueue.push(msg);
-			void this.flushHostSocketSendQueue();
-			return;
-		}
+	sendMessageToHost(msg: string): Promise<void> {
+		return new Promise((markSent) => {
+			const queuedMessage = { message: msg, markSent };
 
-		if (this.hostSocket?.readyState === WebSocket.CONNECTING) {
-			this.pendingHostSocketMessages.push(msg);
-			return;
-		}
+			if (this.canSendToHostSocket()) {
+				this.hostSocketSendQueue.push(queuedMessage);
+				void this.flushHostSocketSendQueue();
+				return;
+			}
 
-		// if socket's are unavailable, fallback to postMessage
-		window.__electrobunHostBridge?.postMessage(msg);
+			if (this.hostSocket?.readyState === WebSocket.CONNECTING) {
+				this.pendingHostSocketMessages.push(queuedMessage);
+				return;
+			}
+
+			// If sockets are unavailable, hand the packet to the native bridge.
+			this.sendMessageToHostViaFallback(queuedMessage);
+		});
 	}
 
 	canSendToHostSocket() {
@@ -174,7 +185,6 @@ class Electroview<T extends RPCWithTransport> {
 				this.hostSocket!.send(msg);
 				return true;
 			}
-			await new Promise((resolve) => setTimeout(resolve, 0));
 			const { encryptedData, iv, tag } =
 				await window.__electrobun_encrypt(msg);
 
@@ -192,6 +202,22 @@ class Electroview<T extends RPCWithTransport> {
 		}
 	}
 
+	sendMessageToHostViaFallback(queuedMessage: QueuedHostMessage) {
+		try {
+			window.__electrobunHostBridge?.postMessage(queuedMessage.message);
+		} catch (error) {
+			console.error("Error sending message to host via native bridge:", error);
+		} finally {
+			queuedMessage.markSent();
+		}
+	}
+
+	flushHostMessagesViaFallback(queue: QueuedHostMessage[]) {
+		while (queue.length > 0) {
+			this.sendMessageToHostViaFallback(queue.shift()!);
+		}
+	}
+
 	async flushHostSocketSendQueue() {
 		if (this.flushingHostSocketSendQueue) {
 			return;
@@ -203,10 +229,12 @@ class Electroview<T extends RPCWithTransport> {
 				this.hostSocketSendQueue.length > 0 &&
 				this.canSendToHostSocket()
 			) {
-				const message = this.hostSocketSendQueue[0]!;
+				const queuedMessage = this.hostSocketSendQueue[0]!;
 				this.hostSocketSendQueue.shift();
-				if (!(await this.sendMessageToHostSocket(message))) {
-					window.__electrobunHostBridge?.postMessage(message);
+				if (!(await this.sendMessageToHostSocket(queuedMessage.message))) {
+					this.sendMessageToHostViaFallback(queuedMessage);
+				} else {
+					queuedMessage.markSent();
 				}
 			}
 		} finally {
@@ -222,8 +250,8 @@ class Electroview<T extends RPCWithTransport> {
 		this.flushingHostSocketMessages = true;
 		try {
 			while (this.pendingHostSocketMessages.length > 0) {
-				const message = this.pendingHostSocketMessages.shift()!;
-				this.hostSocketSendQueue.push(message);
+				const queuedMessage = this.pendingHostSocketMessages.shift()!;
+				this.hostSocketSendQueue.push(queuedMessage);
 			}
 			await this.flushHostSocketSendQueue();
 		} finally {
@@ -293,6 +321,7 @@ class Electroview<T extends RPCWithTransport> {
 
 export {
 	type RPCSchema,
+	type RPCRequestOptions,
 	type ElectrobunRPCSchema,
 	type ElectrobunRPCConfig,
 	createRPC,

package/dist/api/browser/webviewtag.ts

@@ -1,12 +1,20 @@
 import "./global.d.ts";
 
 type WebviewEventTypes =
+	| "will-navigate"
 	| "did-navigate"
 	| "did-navigate-in-page"
 	| "did-commit-navigation"
 	| "dom-ready"
 	| "host-message"
-	| "new-window-open";
+	| "new-window-open"
+	| "download-started"
+	| "download-progress"
+	| "download-completed"
+	| "download-failed"
+	| "load-started"
+	| "load-committed"
+	| "load-finished";
 
 /**
  * Interface representing an <electrobun-webview> custom element.
@@ -19,13 +27,13 @@ type WebviewEventTypes =
  */
 interface WebviewTagElement extends HTMLElement {
 	// Properties
-	webviewId?: number;
+	webviewId: number | null;
 	maskSelectors: Set<string>;
 	transparent: boolean;
 	passthroughEnabled: boolean;
+	spellCheckEnabled: boolean;
 	hidden: boolean;
-	hiddenMirrorMode: boolean;
-	partition: string | null;
+	readonly sandbox: boolean;
 
 	// Attribute-backed properties (getters/setters)
 	src: string | null;
@@ -45,11 +53,12 @@ interface WebviewTagElement extends HTMLElement {
 	reload(): void;
 	loadURL(url: string): void;
 	loadHTML(html: string): void;
+	setSpellCheck(enabled: boolean): Promise<boolean>;
 
 	// Visibility and interaction
-	toggleTransparent(transparent?: boolean, bypassState?: boolean): void;
-	togglePassthrough(enablePassthrough?: boolean, bypassState?: boolean): void;
-	toggleHidden(hidden?: boolean, bypassState?: boolean): void;
+	toggleTransparent(transparent?: boolean): void;
+	togglePassthrough(enablePassthrough?: boolean): void;
+	toggleHidden(hidden?: boolean): void;
 
 	// Events - listener receives a CustomEvent with detail property
 	on(event: WebviewEventTypes, listener: (event: CustomEvent) => void): void;

package/dist/api/browser/wgputag.ts

@@ -12,7 +12,7 @@ type WgpuEventTypes = "ready";
  */
 interface WgpuTagElement extends HTMLElement {
 	// Properties
-	wgpuViewId?: number;
+	wgpuViewId: number | null;
 	transparent: boolean;
 	passthroughEnabled: boolean;
 	hidden: boolean;

package/dist/api/config/ElectrobunConfig.ts

@@ -3,15 +3,19 @@
  * Used in electrobun.config.ts files
  */
 
+import type { WindowsWebView2Permission } from "./windowsPermissions";
+
 type BundlerOptions = {
 	external?: string[];
 	define?: Record<string, string>;
-	loader?: Record<string, string>;
+	alias?: Record<string, string>;
 	minify?: boolean;
 	sourcemap?: boolean | "inline" | "external" | "linked";
-	splitting?: boolean;
-	plugins?: unknown[];
-	[key: string]: unknown;
+	target?: string | string[];
+};
+
+type ViewBundlerOptions = BundlerOptions & {
+	format?: "esm" | "cjs" | "iife";
 };
 
 type CarrotFileActivatorConfig = {
@@ -137,6 +141,7 @@ export interface ElectrobunConfig {
 	build?: {
 		/**
 		 * Main process implementation to build and package.
+		 * - "bun": bundle and run the Bun main process entrypoint
 		 * - "cottontail": bundle and run the Cottontail main process entrypoint
 		 * - "zig": compile and run the Zig main process entrypoint
 		 * - "rust": compile and run the Rust main process entrypoint
@@ -144,7 +149,19 @@ export interface ElectrobunConfig {
 		 * - "odin": compile and run the Odin main process entrypoint
 		 * @default "cottontail"
 		 */
-		mainProcess?: "cottontail" | "zig" | "rust" | "go" | "odin";
+		mainProcess?: "bun" | "cottontail" | "zig" | "rust" | "go" | "odin";
+
+		/**
+		 * Bun main process build configuration.
+		 * Used when `build.mainProcess` is set to `"bun"`.
+		 */
+		bun?: {
+			/**
+			 * Entry point for the main Bun process
+			 * @default "src/bun/index.ts"
+			 */
+			entrypoint?: string;
+		} & BundlerOptions;
 
 		/**
 		 * Cottontail main process build configuration.
@@ -213,8 +230,8 @@ export interface ElectrobunConfig {
 
 		/**
 		 * Browser view build configurations.
-		 * Each view accepts bundler options (plugins, sourcemap, minify, define, etc.)
-		 * in addition to the entrypoint.
+		 * Each view accepts the supported bundler options in addition to the
+		 * entrypoint.
 		 */
 		views?: {
 			[viewName: string]: {
@@ -222,7 +239,7 @@ export interface ElectrobunConfig {
 				 * Entry point for this view's TypeScript code
 				 */
 				entrypoint: string;
-			} & BundlerOptions;
+			} & ViewBundlerOptions;
 		};
 
 		/**
@@ -244,47 +261,6 @@ export interface ElectrobunConfig {
 		 */
 		artifactFolder?: string;
 
-		/**
-		 * Build targets to compile for
-		 * Can be "current", "all", or comma-separated list like "macos-arm64,win-x64"
-		 */
-		targets?: string;
-
-		/**
-		 * Enable ASAR archive packaging for bundled assets
-		 * When enabled, all files in the Resources folder will be packed into an app.asar archive
-		 * @default false
-		 */
-		useAsar?: boolean;
-
-		/**
-		 * Glob patterns for files to exclude from ASAR packing (extract to app.asar.unpacked)
-		 * Useful for native modules or executables that need to be accessible as regular files
-		 * @default ["*.node", "*.dll", "*.dylib", "*.so"]
-		 */
-		asarUnpack?: string[];
-
-		/**
-		 * Override the CEF (Chromium Embedded Framework) version.
-		 * Format: "CEF_VERSION+chromium-CHROMIUM_VERSION"
-		 * Example: "144.0.11+ge135be2+chromium-144.0.7559.97"
-		 *
-		 * Check the electrobun-cef-compat compatibility matrix for tested combinations
-		 * before overriding. Using an untested version may cause runtime issues.
-		 * @default Uses the version bundled with this Electrobun release
-		 */
-		cefVersion?: string;
-
-		/**
-		 * Override the Dawn (WebGPU) version.
-		 * Format: semver string (e.g., "0.2.3") or tag (e.g., "v0.2.3-beta.0")
-		 *
-		 * This downloads the specified electrobun-dawn release and uses it
-		 * instead of the latest release.
-		 * @default Uses the latest electrobun-dawn release
-		 */
-		wgpuVersion?: string;
-
 		/**
 		 * Additional file or directory paths to watch for changes during `electrobun dev --watch`.
 		 * Paths are relative to the project root.
@@ -364,6 +340,10 @@ export interface ElectrobunConfig {
 			 * - `"value"` — add a flag with a value
 			 * - `false` — remove a default flag set by Electrobun
 			 *
+			 * CEF remote debugging is automatic for dev builds and disabled by
+			 * default for packaged builds. Set `"remote-debugging-port"` to a
+			 * string port to opt in, or `false` to disable it explicitly.
+			 *
 			 * @example
 			 * ```typescript
 			 * chromiumFlags: {
@@ -423,6 +403,10 @@ export interface ElectrobunConfig {
 			 * - `"value"` — add a flag with a value
 			 * - `false` — remove a default flag set by Electrobun
 			 *
+			 * CEF remote debugging is automatic for dev builds and disabled by
+			 * default for packaged builds. Set `"remote-debugging-port"` to a
+			 * string port to opt in, or `false` to disable it explicitly.
+			 *
 			 * @example
 			 * ```typescript
 			 * chromiumFlags: {
@@ -434,7 +418,19 @@ export interface ElectrobunConfig {
 			chromiumFlags?: Record<string, string | boolean>;
 
 			/**
-			 * Path to application icon (.ico format)
+			 * WebView2 permissions to grant automatically without showing a prompt.
+			 * This applies to every origin loaded in a native Windows webview, so only
+			 * enable permissions that the application intentionally delegates to its
+			 * web content. This option does not affect CEF webviews.
+			 *
+			 * @example ["camera", "microphone"]
+			 * @default []
+			 */
+			autoGrantPermissions?: WindowsWebView2Permission[];
+
+			/**
+			 * Path to an application icon in ICO or PNG format. PNG input is
+			 * converted to ICO by Hutch.
 			 * Used for the installer/extractor wrapper, desktop shortcuts, and taskbar
 			 * Should include multiple sizes (16x16, 32x32, 48x48, 256x256) for best results
 			 * @example "assets/icon.ico"
@@ -465,6 +461,31 @@ export interface ElectrobunConfig {
 			 */
 			defaultRenderer?: "native" | "cef";
 
+			/**
+			 * Emit an expanded Flatpak-builder recipe alongside the normal Linux
+			 * artifacts. This is an opt-in packaging MVP: Hutch writes a manifest
+			 * and `/app` payload but does not invoke `flatpak-builder`.
+			 */
+			flatpak?: {
+				/** Enable Flatpak recipe generation. @default false */
+				enabled: boolean;
+
+				/** Output directory relative to `build.artifactFolder`. @default "flatpak" */
+				outputPath?: string;
+
+				/** Flatpak runtime identifier. @default "org.freedesktop.Platform" */
+				runtime?: string;
+
+				/** Flatpak runtime branch. @default "25.08" */
+				runtimeVersion?: string;
+
+				/** Flatpak SDK identifier. @default "org.freedesktop.Sdk" */
+				sdk?: string;
+
+				/** Override the manifest's default sandbox finish arguments. */
+				finishArgs?: string[];
+			};
+
 			/**
 			 * Custom Chromium command-line flags to pass to CEF during initialization.
 			 * Keys are flag names without the "--" prefix.
@@ -472,6 +493,10 @@ export interface ElectrobunConfig {
 			 * - `"value"` — add a flag with a value
 			 * - `false` — remove a default flag set by Electrobun
 			 *
+			 * CEF remote debugging is automatic for dev builds and disabled by
+			 * default for packaged builds. Set `"remote-debugging-port"` to a
+			 * string port to opt in, or `false` to disable it explicitly.
+			 *
 			 * @example
 			 * ```typescript
 			 * chromiumFlags: {