electrobun 1.18.1 → 1.18.4-beta.10

package/README.md

@@ -14,9 +14,9 @@
 ## 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 <a href="https://bun.sh">bun</a> to execute the main process and to bundle webview typescript, and has native bindings written in Objc, C++, and several core parts written in <a href="https://ziglang.org/">zig</a>.
+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>.
 
-Visit <a href="https://docs.electrobunny.ai/electrobun/">https://docs.electrobunny.ai/electrobun/</a> to see api documentation, guides, and more.
+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.
 
@@ -25,7 +25,7 @@ Don't miss our:
 - zig optimized BSDIFF implementation that lets you ship tiny app updates as small as 4KB
 - `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 right in Bun
+- 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
 - so much more.
 
@@ -33,7 +33,7 @@ Don't miss our:
 
 - 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 system webview, most of this is the bun runtime)
+- 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)
 - Provide everything you need in one tightly integrated workflow to start writing code in 5 minutes and distribute in 10.
 
@@ -63,9 +63,11 @@ Don't miss our:
 - [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
 - [Guerilla Glass](https://github.com/okikeSolutions/guerillaglass) - open-source cross-platform creator studio for fast Record -> Edit -> Deliver workflows
+- [Invoke](https://getinvoke.com) - macOS UI automation & shortcut platform
 - [Marginalia](https://github.com/lars-hoeijmans/Marginalia) - a simple note taking app
 - [MarkBun](https://github.com/xiaochong/markbun) - fast, beautiful, Typora-like markdown desktop editor
 - [md-browse](https://github.com/needle-tools/md-browse) - a markdown-first browser that converts web pages to clean markdown
+- [moop](https://github.com/zrubinrattet/moop/) - desktop app for batch image optimization for the web
 - [Patchline](https://github.com/adwaithks/Patchline) - lightweight desktop Git client for reading patches and line diffs, then staging and committing changes
 - [peekachu](https://github.com/needle-tools/peekachu) - password manager for AIs; store secrets in your OS keychain and scrub output so AI assistants never see actual values
 - [PiBun](https://github.com/khairold/pibun) - desktop GUI for the Pi coding agent with chat, terminal, git integration, and plugin system
@@ -113,6 +115,18 @@ Building apps with Electrobun is as easy as updating your package.json dependenc
 
 ### Prerequisites
 
+Install Dash globally before building Electrobun:
+
+```bash
+curl -fsSL https://electrobun-artifacts.blackboard.sh/dash-cli/install.sh | sh
+```
+
+On Windows PowerShell:
+
+```powershell
+& ([scriptblock]::Create((irm https://electrobun-artifacts.blackboard.sh/dash-cli/install.ps1)))
+```
+
 **macOS:**
 - Xcode command line tools
 - cmake (install via homebrew: `brew install cmake`)
@@ -133,8 +147,8 @@ On Ubuntu/Debian based distros: `sudo apt install build-essential cmake pkg-conf
 ```bash
 git clone --recurse-submodules https://github.com/blackboardsh/electrobun.git
 cd electrobun/package
-bun install
-bun dev:clean
+dash install
+dash dev:clean
 ```
 
 ### Development Workflow
@@ -144,22 +158,31 @@ bun dev:clean
 cd electrobun/package
 
 # After making changes to source code
-bun dev
-
-# If you only changed kitchen sink code (not electrobun source)
-bun dev:rerun
+dash dev
 
 # If you need a completely fresh start
-bun dev:clean
+dash dev:clean
+```
+
+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:
+
+```bash
+dash dev --local
 ```
 
+The first Dash is globally installed. Stack preparation explicitly selects the
+completed local Dash engine and Cottontail build for the remainder of the
+command.
+
 ### Additional Commands
 
 All commands are run from the `/package` directory:
 
-- `bun dev:canary` - Build and run kitchen sink in canary mode
-- `bun build:dev` - Build electrobun in development mode
-- `bun build:release` - Build electrobun in release mode
+- `dash dev:canary` - Build and run kitchen sink in canary mode
+- `dash build:dev` - Build Electrobun in development mode
+- `dash build:release` - Build Electrobun in release mode
 
 ### Debugging
 

package/dash.config.ts

@@ -0,0 +1,28 @@
+// @dash cli=0.2.0-canary.2 cottontail=0.1.1-canary.2
+export default {
+	scripts: {
+		start: "dash src/sdks/bun/index.ts",
+		"check-zig-version": "vendors/zig/zig version",
+		"check-rust-version": "vendors/rust/bin/rustc --version",
+		"build:dev": "dash build.ts",
+		"build:local": "scripts/build-local.js",
+		"build:release": "dash build.ts --release",
+		dev: "scripts/dev.ts",
+		"dev:test": "scripts/dev.test.ts",
+		"dev:clean": "cd ../kitchen && rm -rf node_modules vendors/cef && cd ../package && dash dev",
+		"dev:canary": "dash install && dash build:release && cd ../kitchen && dash install && dash electrobun build --env=canary",
+		"dev:production": "dash install && dash build:release && cd ../kitchen && dash install && dash electrobun build --env=production",
+		"build:docs:release": "cd ../docs && dash run build",
+		"npm:publish": "dash build:release && npm publish",
+		"npm:publish:beta": "dash build:release && npm publish --tag beta",
+		typecheck: "./node_modules/.bin/tsc --noEmit && cd ../kitchen && ./node_modules/.bin/tsc --noEmit",
+		"push:beta": "dash typecheck && node scripts/push-version.js beta",
+		"push:patch": "dash typecheck && node scripts/push-version.js patch",
+		"push:minor": "dash typecheck && node scripts/push-version.js minor",
+		"push:major": "dash typecheck && node scripts/push-version.js major",
+		"push:stable": "dash typecheck && node scripts/push-version.js stable",
+		"build:push:artifacts": "node scripts/build-and-upload-artifacts.js",
+		"test:unit": "dash test src/shared src/sdks/bun src/config",
+		"bump-cef": "dash scripts/update-cef-version.ts",
+	},
+};

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

@@ -7,6 +7,8 @@ interface ElectrobunEncryptResult {
 }
 
 interface ElectrobunBridge {
+  receiveMessageFromHost: (msg: unknown) => void;
+  receiveInternalMessageFromHost: (msg: unknown) => void;
   receiveMessageFromBun: (msg: unknown) => void;
   receiveInternalMessageFromBun: (msg: unknown) => void;
 }
@@ -20,10 +22,14 @@ declare global {
     __electrobunWebviewId: number;
     __electrobunWindowId: number;
     __electrobunRpcSocketPort: number;
+    __electrobunHostSocketPort?: number;
+    __electrobunPlaintextHostSocket?: boolean;
     __electrobun?: ElectrobunBridge;
+    __electrobunPendingHostMessages?: unknown[];
     __electrobun_encrypt: (msg: string) => Promise<ElectrobunEncryptResult>;
     __electrobun_decrypt: (encryptedData: string, iv: string, tag: string) => Promise<string>;
     __electrobunInternalBridge?: MessageHandler;
+    __electrobunHostBridge?: MessageHandler;
     __electrobunBunBridge?: MessageHandler;
   }
 }

package/dist/api/browser/index.ts

@@ -15,13 +15,27 @@ import { type WgpuTagElement, type WgpuEventTypes } from "./wgputag";
 import "./global.d.ts";
 
 const WEBVIEW_ID = window.__electrobunWebviewId;
-const RPC_SOCKET_PORT = window.__electrobunRpcSocketPort;
+const HOST_SOCKET_PORT =
+	window.__electrobunHostSocketPort ?? window.__electrobunRpcSocketPort;
 
 class Electroview<T extends RPCWithTransport> {
-	bunSocket?: WebSocket;
+	hostSocket?: WebSocket;
+	hostSocketCanSend = false;
+	pendingHostSocketMessages: string[] = [];
+	flushingHostSocketMessages = false;
+	hostSocketSendQueue: string[] = [];
+	flushingHostSocketSendQueue = false;
 	// user's custom rpc browser <-> bun
 	rpc?: T;
 	rpcHandler?: (msg: unknown) => void;
+	carrots = {
+		invoke: <R = unknown>(
+			carrotId: string,
+			method: string,
+			params?: unknown,
+			options?: { windowId?: string },
+		) => this.invokeCarrot<R>(carrotId, method, params, options),
+	};
 
 	constructor(config: { rpc: T }) {
 		this.rpc = config.rpc;
@@ -29,49 +43,65 @@ class Electroview<T extends RPCWithTransport> {
 	}
 
 	init() {
-		this.initSocketToBun();
+		this.initSocketToHost();
 
-		// Set up handler for user RPC messages from bun
-		// Note: receiveInternalMessageFromBun is set up by the preload script
-		window.__electrobun!.receiveMessageFromBun =
-			this.receiveMessageFromBun.bind(this);
+		// Set up handler for user RPC messages from the host runtime.
+		const hostMessageHandler = this.receiveMessageFromHost.bind(this);
+		window.__electrobun!.receiveMessageFromHost = hostMessageHandler;
+		window.__electrobun!.receiveMessageFromBun = hostMessageHandler;
 
 		if (this.rpc) {
 			this.rpc.setTransport(this.createTransport());
 		}
+
+		const pendingMessages = window.__electrobunPendingHostMessages;
+		if (pendingMessages?.length) {
+			window.__electrobunPendingHostMessages = [];
+			for (const message of pendingMessages) {
+				hostMessageHandler(message);
+			}
+		}
 	}
 
-	initSocketToBun() {
+	initSocketToHost() {
 		// Skip native socket when running in a remote browser (no port/webview ID)
-		if (!RPC_SOCKET_PORT || !WEBVIEW_ID) {
+		if (!HOST_SOCKET_PORT || !WEBVIEW_ID) {
 			return;
 		}
 
-		// Note: Using ws:// for localhost is intentional - all RPC messages are
+		// Note: Using ws:// for loopback is intentional - all RPC messages are
 		// encrypted with per-webview AES-GCM keys, making TLS redundant
 		const socket = new WebSocket(
-			`ws://localhost:${RPC_SOCKET_PORT}/socket?webviewId=${WEBVIEW_ID}`,
+			`ws://127.0.0.1:${HOST_SOCKET_PORT}/socket?webviewId=${WEBVIEW_ID}`,
 		);
 
-		this.bunSocket = socket;
+		this.hostSocket = socket;
 
 		socket.addEventListener("open", () => {
-			// this.bunSocket?.send("Hello from webview " + WEBVIEW_ID);
+			this.hostSocketCanSend = true;
+			void this.flushPendingHostSocketMessages();
 		});
 
 		socket.addEventListener("message", async (event) => {
 			const message = event.data;
 			if (typeof message === "string") {
 				try {
-					const encryptedPacket = JSON.parse(message);
-
-					const decrypted = await window.__electrobun_decrypt(
-						encryptedPacket.encryptedData,
-						encryptedPacket.iv,
-						encryptedPacket.tag,
-					);
-
-					this.rpcHandler?.(JSON.parse(decrypted));
+					const packet = JSON.parse(message);
+					this.hostSocketCanSend = true;
+					if (
+						typeof packet?.encryptedData === "string" &&
+						typeof packet?.iv === "string" &&
+						typeof packet?.tag === "string"
+					) {
+						const decrypted = await window.__electrobun_decrypt(
+							packet.encryptedData,
+							packet.iv,
+							packet.tag,
+						);
+						this.rpcHandler?.(JSON.parse(decrypted));
+					} else {
+						this.rpcHandler?.(packet);
+					}
 				} catch (err) {
 					console.error("Error parsing bun message:", err);
 				}
@@ -83,10 +113,13 @@ class Electroview<T extends RPCWithTransport> {
 		});
 
 		socket.addEventListener("error", (event) => {
+			this.hostSocketCanSend = false;
 			console.error("Socket error:", event);
 		});
 
 		socket.addEventListener("close", (_event) => {
+			this.hostSocketCanSend = false;
+			this.pendingHostSocketMessages = [];
 			// console.log("Socket closed:", event);
 		});
 	}
@@ -97,9 +130,9 @@ class Electroview<T extends RPCWithTransport> {
 			send(message: unknown) {
 				try {
 					const messageString = JSON.stringify(message);
-					that.bunBridge(messageString);
+					that.sendMessageToHost(messageString);
 				} catch (error) {
-					console.error("bun: failed to serialize message to webview", error);
+					console.error("host: failed to serialize message to webview", error);
 				}
 			},
 			registerHandler(handler: (msg: unknown) => void) {
@@ -108,36 +141,121 @@ class Electroview<T extends RPCWithTransport> {
 		};
 	}
 
-	async bunBridge(msg: string) {
-		if (this.bunSocket?.readyState === WebSocket.OPEN) {
-			try {
-				const { encryptedData, iv, tag } =
-					await window.__electrobun_encrypt(msg);
-
-				const encryptedPacket = {
-					encryptedData: encryptedData,
-					iv: iv,
-					tag: tag,
-				};
-				const encryptedPacketString = JSON.stringify(encryptedPacket);
-				this.bunSocket.send(encryptedPacketString);
-				return;
-			} catch (error) {
-				console.error("Error sending message to bun via socket:", error);
-			}
+	async sendMessageToHost(msg: string) {
+		if (this.canSendToHostSocket()) {
+			this.hostSocketSendQueue.push(msg);
+			void this.flushHostSocketSendQueue();
+			return;
+		}
+
+		if (this.hostSocket?.readyState === WebSocket.CONNECTING) {
+			this.pendingHostSocketMessages.push(msg);
+			return;
 		}
 
 		// if socket's are unavailable, fallback to postMessage
-		window.__electrobunBunBridge?.postMessage(msg);
+		window.__electrobunHostBridge?.postMessage(msg);
+	}
+
+	canSendToHostSocket() {
+		return (
+			this.hostSocketCanSend &&
+			this.hostSocket?.readyState === WebSocket.OPEN
+		);
+	}
+
+	async sendMessageToHostSocket(msg: string) {
+		if (!this.canSendToHostSocket()) {
+			return false;
+		}
+
+		try {
+			if (window.__electrobunPlaintextHostSocket) {
+				this.hostSocket!.send(msg);
+				return true;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 0));
+			const { encryptedData, iv, tag } =
+				await window.__electrobun_encrypt(msg);
+
+			const encryptedPacket = {
+				encryptedData: encryptedData,
+				iv: iv,
+				tag: tag,
+			};
+			const encryptedPacketString = JSON.stringify(encryptedPacket);
+			this.hostSocket!.send(encryptedPacketString);
+			return true;
+		} catch (error) {
+			console.error("Error sending message to host via socket:", error);
+			return false;
+		}
+	}
+
+	async flushHostSocketSendQueue() {
+		if (this.flushingHostSocketSendQueue) {
+			return;
+		}
+
+		this.flushingHostSocketSendQueue = true;
+		try {
+			while (
+				this.hostSocketSendQueue.length > 0 &&
+				this.canSendToHostSocket()
+			) {
+				const message = this.hostSocketSendQueue[0]!;
+				this.hostSocketSendQueue.shift();
+				if (!(await this.sendMessageToHostSocket(message))) {
+					window.__electrobunHostBridge?.postMessage(message);
+				}
+			}
+		} finally {
+			this.flushingHostSocketSendQueue = false;
+		}
 	}
 
-	receiveMessageFromBun(msg: unknown) {
-		// NOTE: in the webview messages are passed by executing ElectrobunView.receiveMessageFromBun(object)
+	async flushPendingHostSocketMessages() {
+		if (this.flushingHostSocketMessages) {
+			return;
+		}
+
+		this.flushingHostSocketMessages = true;
+		try {
+			while (this.pendingHostSocketMessages.length > 0) {
+				const message = this.pendingHostSocketMessages.shift()!;
+				this.hostSocketSendQueue.push(message);
+			}
+			await this.flushHostSocketSendQueue();
+		} finally {
+			this.flushingHostSocketMessages = false;
+		}
+	}
+
+	receiveMessageFromHost(msg: unknown) {
+		// NOTE: in the webview messages are passed by executing window.__electrobun.receiveMessageFromHost(object)
 		// so they're already parsed into an object here
 		if (this.rpcHandler) {
 			this.rpcHandler(msg);
 		}
 	}
+
+	async invokeCarrot<R = unknown>(
+		carrotId: string,
+		method: string,
+		params?: unknown,
+		options?: { windowId?: string },
+	): Promise<R> {
+		const requestProxy = (this.rpc as any)?.request;
+		if (!requestProxy || typeof requestProxy.invokeCarrot !== "function") {
+			throw new Error("Renderer carrot invocation is not available in this Electrobun host.");
+		}
+		return requestProxy.invokeCarrot({
+			carrotId,
+			method,
+			params,
+			windowId: options?.windowId,
+		}) as Promise<R>;
+	}
 	static defineRPC<Schema extends ElectrobunRPCSchema>(
 		config: ElectrobunRPCConfig<Schema, "webview">,
 	) {

package/dist/api/{bun → config}/ElectrobunConfig.ts

@@ -3,15 +3,38 @@
  * Used in electrobun.config.ts files
  */
 
-/**
- * Bun.build() options that can be passed through to the bundler.
- * Excludes options that are controlled by Electrobun (entrypoints, outdir, target).
- * See https://bun.sh/docs/bundler for full documentation.
- */
-type BunBuildOptions = Omit<
-	Parameters<typeof Bun.build>[0],
-	"entrypoints" | "outdir" | "target"
->;
+type BundlerOptions = {
+	external?: string[];
+	define?: Record<string, string>;
+	loader?: Record<string, string>;
+	minify?: boolean;
+	sourcemap?: boolean | "inline" | "external" | "linked";
+	splitting?: boolean;
+	plugins?: unknown[];
+	[key: string]: unknown;
+};
+
+type CarrotFileActivatorConfig = {
+	baseName?: string;
+	nodeType?: "file" | "dir" | "any";
+	slate: {
+		type: string;
+		name?: string;
+		icon?: string;
+		config?: Record<string, unknown>;
+	};
+};
+
+type CarrotContributionsConfig = {
+	fileActivators?: CarrotFileActivatorConfig[];
+};
+
+type CarrotUIDefinition = {
+	name?: string;
+	entrypoint?: string;
+	path?: string;
+	[key: string]: unknown;
+};
 
 export interface ElectrobunConfig {
 	/**
@@ -113,22 +136,85 @@ export interface ElectrobunConfig {
 	 */
 	build?: {
 		/**
-		 * Bun process build configuration.
-		 * Accepts all Bun.build() options (plugins, sourcemap, minify, define, etc.)
-		 * in addition to the entrypoint. See https://bun.sh/docs/bundler
+		 * Main process implementation to build and package.
+		 * - "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
+		 * - "go": compile and run the Go main process entrypoint
+		 * - "odin": compile and run the Odin main process entrypoint
+		 * @default "cottontail"
+		 */
+		mainProcess?: "cottontail" | "zig" | "rust" | "go" | "odin";
+
+		/**
+		 * Cottontail main process build configuration.
+		 * Used when `build.mainProcess` is set to `"cottontail"`.
 		 */
-		bun?: {
+		cottontail?: {
 			/**
-			 * Entry point for the main Bun process
+			 * Entry point for the main Cottontail process
 			 * @default "src/bun/index.ts"
 			 */
 			entrypoint?: string;
-		} & BunBuildOptions;
+		} & BundlerOptions;
+
+		/**
+		 * Zig main process build configuration.
+		 * Used when `build.mainProcess` is set to `"zig"`.
+		 */
+		zig?: {
+			/**
+			 * Entry point for the main Zig process
+			 * @default "src/zig/main.zig"
+			 */
+			entrypoint?: string;
+		};
+
+		/**
+		 * Rust main process build configuration.
+		 * Used when `build.mainProcess` is set to `"rust"`.
+		 */
+		rust?: {
+			/**
+			 * Entry point for the main Rust process
+			 * @default "src/rust/main.rs"
+			 */
+			entrypoint?: string;
+		};
+
+		/**
+		 * Go main process build configuration.
+		 * Used when `build.mainProcess` is set to `"go"`.
+		 */
+		go?: {
+			/**
+			 * Entry point for the main Go process
+			 * @default "src/go/main.go"
+			 */
+			entrypoint?: string;
+		};
+
+		/**
+		 * Odin main process build configuration.
+		 * Used when `build.mainProcess` is set to `"odin"`.
+		 *
+		 * Note: Odin support has platform caveats (x64-only on Windows, MSVC
+		 * Build Tools required on Windows). See docs for details.
+		 */
+		odin?: {
+			/**
+			 * Entry point for the main Odin process. May be a .odin file or a
+			 * package directory; a file entrypoint compiles its containing
+			 * directory as the root package.
+			 * @default "src/odin/main.odin"
+			 */
+			entrypoint?: string;
+		};
 
 		/**
 		 * Browser view build configurations.
-		 * Each view accepts all Bun.build() options (plugins, sourcemap, minify, define, etc.)
-		 * in addition to the entrypoint. See https://bun.sh/docs/bundler
+		 * Each view accepts bundler options (plugins, sourcemap, minify, define, etc.)
+		 * in addition to the entrypoint.
 		 */
 		views?: {
 			[viewName: string]: {
@@ -136,7 +222,7 @@ export interface ElectrobunConfig {
 				 * Entry point for this view's TypeScript code
 				 */
 				entrypoint: string;
-			} & BunBuildOptions;
+			} & BundlerOptions;
 		};
 
 		/**
@@ -199,24 +285,6 @@ export interface ElectrobunConfig {
 		 */
 		wgpuVersion?: string;
 
-		/**
-		 * Override the Bun runtime version.
-		 * Format: semver string (e.g., "1.4.2")
-		 *
-		 * This downloads the specified Bun version from GitHub releases and uses it
-		 * instead of the version bundled with this Electrobun release.
-		 * @default Uses the version bundled with this Electrobun release
-		 */
-		bunVersion?: string;
-
-		/**
-		 * Locales to include in the ICU data file (Linux/Windows only).
-		 * Set to '*' to include all locales, or specify a subset like ['en', 'de']
-		 * to reduce app size. Has no effect on macOS (uses system ICU).
-		 * @default '*'
-		 */
-		locales?: string[] | "*";
-
 		/**
 		 * Additional file or directory paths to watch for changes during `electrobun dev --watch`.
 		 * Paths are relative to the project root.
@@ -242,9 +310,10 @@ export interface ElectrobunConfig {
 			description?: string;
 			mode?: "window" | "background";
 			carrotOnly?: boolean;
-			permissions?: Record<string, unknown>;
 			dependencies?: Record<string, string>;
-			remoteUIs?: Record<string, { entrypoint: string; [key: string]: unknown }>;
+			remoteUIs?: Record<string, CarrotUIDefinition>;
+			slateUIs?: Record<string, CarrotUIDefinition>;
+			contributions?: CarrotContributionsConfig;
 		};
 
 		/**
@@ -425,7 +494,7 @@ export interface ElectrobunConfig {
 
 	/**
 	 * Runtime behaviour configuration.
-	 * These values are copied into build.json and available to the Bun process at runtime.
+	 * These values are copied into build.json and available to the main process at runtime.
 	 * You can add arbitrary keys here and access them via BuildConfig.
 	 */
 	runtime?: {
@@ -478,7 +547,7 @@ export interface ElectrobunConfig {
 		baseUrl?: string;
 		/**
 		 * Generate delta patch files by diffing against the previous release.
-		 * Disable to skip patch generation for local canary/stable testing.
+		 * Disable to skip patch generation for local canary/production testing.
 		 * @default true
 		 */
 		generatePatch?: boolean;

package/dist/api/config/validate.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "bun:test";
+import { assertNoLegacyBunMainProcessConfig } from "./validate";
+
+describe("assertNoLegacyBunMainProcessConfig", () => {
+	it("accepts Cottontail and native main-process configurations", () => {
+		expect(() =>
+			assertNoLegacyBunMainProcessConfig({
+				build: {
+					mainProcess: "cottontail",
+					cottontail: { entrypoint: "src/bun/index.ts" },
+				},
+			}),
+		).not.toThrow();
+		expect(() =>
+			assertNoLegacyBunMainProcessConfig({
+				build: { mainProcess: "zig" },
+			}),
+		).not.toThrow();
+	});
+
+	it.each([
+		{ mainProcess: "bun" },
+		{ bun: { entrypoint: "src/bun/index.ts" } },
+		{ bunVersion: "1.3.8" },
+		{ bunnyBun: "bunny-bun-test" },
+	])("rejects removed Bun configuration: %p", (build) => {
+		expect(() => assertNoLegacyBunMainProcessConfig({ build })).toThrow(
+			'Use build.mainProcess = "cottontail"',
+		);
+	});
+});