electrobun 1.14.4 → 1.15.0-beta.0

package/README.md

@@ -0,0 +1,120 @@
+<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>
+</p>
+
+<h1 align="center">Electrobun</h1>
+
+<div align="center">
+  Get started with a template <br />
+  <code><strong>npx electrobun init</strong></code>   
+</div>
+
+
+
+## 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 <a href="https://ziglang.org/">zig</a>.
+
+Visit <a href="https://blackboard.sh/electrobun/">https://blackboard.sh/electrobun/</a> to see api documentation, guides, and 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 ~12MB (when using system webview, most of this is the bun runtime)
+- Even smaller app updates as small as 14KB (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.
+
+## Apps Built with Electrobun
+- [Audio TTS](https://github.com/blackboardsh/audio-tts) - desktop text-to-speech app using Qwen3-TTS for voice design, cloning, and generation
+- [Co(lab)](https://blackboard.sh/colab/) - a hybrid web browser + code editor for deep work
+- [DOOM](https://github.com/blackboardsh/electrobun-doom) - DOOM implemented in 2 ways: bun -> (c doom -> bundled wgpu) and (full ts port bun -> bundled wgpu)
+
+### Video Demos
+
+[![Audio TTS Demo](https://img.youtube.com/vi/Z4dNK1d6l6E/maxresdefault.jpg)](https://www.youtube.com/watch?v=Z4dNK1d6l6E)
+
+[![Co(lab) Demo](https://img.youtube.com/vi/WWTCqGmE86w/maxresdefault.jpg)](https://www.youtube.com/watch?v=WWTCqGmE86w)
+
+[![DOOM Demo](https://github.com/user-attachments/assets/6cc5f04a-6d97-4010-b65f-3f282d32590c)](https://x.com/YoavCodes/status/2028499038148903239?s=20)
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=blackboardsh/electrobun&type=date&legend=top-left&cache=2)](https://www.star-history.com/#blackboardsh/electrobun&type=date&legend=top-left)
+
+## Contributing
+Ways to get involved:
+
+- Follow us on X for updates <a href="https://twitter.com/BlackboardTech">@BlackboardTech</a> or <a href="https://bsky.app/profile/yoav.codes">@yoav.codes</a>
+- Join the conversation on <a href="https://discord.gg/ueKE4tjaCE">Discord</a>
+- Create and participate in Github issues and discussions
+- Let me know what you're building with Electrobun
+
+## Development Setup
+Building apps with Electrobun is as easy as updating your package.json dependencies with `npm add electrobun` or try one of our templates via `npx electrobun init`.
+
+**This section is for building Electrobun from source locally in order to contribute fixes to it.**
+
+### Prerequisites
+
+**macOS:**
+- Xcode command line tools
+- cmake (install via homebrew: `brew install cmake`)
+
+**Windows:**
+- Visual Studio Build Tools or Visual Studio with C++ development tools
+- cmake
+
+**Linux:**
+- build-essential package
+- cmake
+- webkit2gtk and GTK development packages
+
+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`
+
+### First-time Setup
+
+```bash
+git clone --recurse-submodules https://github.com/blackboardsh/electrobun.git
+cd electrobun/package
+bun install
+bun dev:clean
+```
+
+### Development Workflow
+
+```bash
+# All commands are run from the /package directory
+cd electrobun/package
+
+# After making changes to source code
+bun dev
+
+# If you only changed kitchen sink code (not electrobun source)
+bun dev:rerun
+
+# If you need a completely fresh start
+bun dev:clean
+```
+
+### 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
+
+### Debugging
+
+**macOS:** Use `lldb <path-to-bundle>/Contents/MacOS/launcher` and then `run` to debug release builds
+
+## Platform Support
+
+| OS | Status |
+|---|---|
+| macOS 14+ | Official |
+| Windows 11+ | Official |
+| Ubuntu 22.04+ | Official |
+| Other Linux distros (gtk3, webkit2gtk-4.1) | Community |

package/bun.lock

@@ -5,10 +5,12 @@
     "": {
       "name": "electrobun",
       "dependencies": {
+        "@babylonjs/core": "^7.45.0",
         "@types/bun": "^1.3.8",
         "archiver": "^7.0.1",
         "png-to-ico": "^2.1.8",
         "rcedit": "^4.0.1",
+        "three": "^0.165.0",
       },
       "devDependencies": {
         "@types/archiver": "^6.0.3",
@@ -17,6 +19,8 @@
     },
   },
   "packages": {
+    "@babylonjs/core": ["@babylonjs/core@7.54.3", "", {}, "sha512-P5ncXVd8GEUJLhwloP9V0oVwQYIrvZztguVeLlvd5Rx+9aQnenKjpV8auJ6SRsUlAmNZU4pFTKzwF6o2EUfhAw=="],
+
     "@isaacs/cliui": ["@isaacs/cliui@8.0.2", "", { "dependencies": { "string-width": "^5.1.2", "string-width-cjs": "npm:string-width@^4.2.0", "strip-ansi": "^7.0.1", "strip-ansi-cjs": "npm:strip-ansi@^6.0.1", "wrap-ansi": "^8.1.0", "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0" } }, "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA=="],
 
     "@malept/cross-spawn-promise": ["@malept/cross-spawn-promise@1.1.1", "", { "dependencies": { "cross-spawn": "^7.0.1" } }, "sha512-RTBGWL5FWQcg9orDOCcp4LvItNzUPcyEU9bwaeJX0rJ1IQxzucC48Y0/sQLp/g6t99IQgAlGIaesJS+gTn7tVQ=="],
@@ -169,6 +173,8 @@
 
     "text-decoder": ["text-decoder@1.2.3", "", { "dependencies": { "b4a": "^1.6.4" } }, "sha512-3/o9z3X0X0fTupwsYvR03pJ/DjWuqqrfwBgTQzdWDiQSm9KitAyz/9WqsT2JQW7KV2m+bC2ol/zqpW37NHxLaA=="],
 
+    "three": ["three@0.165.0", "", {}, "sha512-cc96IlVYGydeceu0e5xq70H8/yoVT/tXBxV/W8A/U6uOq7DXc4/s1Mkmnu6SqoYGhSRWWYFOhVwvq6V0VtbplA=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@5.26.5", "", {}, "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA=="],

package/dist/api/browser/index.ts

@@ -11,6 +11,7 @@ import {
 	type WebviewTagElement,
 	type WebviewEventTypes,
 } from "./webviewtag";
+import { type WgpuTagElement, type WgpuEventTypes } from "./wgputag";
 import "./global.d.ts";
 
 const WEBVIEW_ID = window.__electrobunWebviewId;
@@ -175,6 +176,8 @@ export {
 	Electroview,
 	type WebviewTagElement,
 	type WebviewEventTypes,
+	type WgpuTagElement,
+	type WgpuEventTypes,
 };
 
 const Electrobun = {

package/dist/api/browser/wgputag.ts

@@ -0,0 +1,48 @@
+import "./global.d.ts";
+
+type WgpuEventTypes = "ready";
+
+/**
+ * Interface representing an <electrobun-wgpu> custom element.
+ * Use this to properly type wgpu elements obtained via querySelector.
+ *
+ * @example
+ * const wgpu = document.querySelector('electrobun-wgpu') as WgpuTagElement;
+ * wgpu.toggleTransparent(true);
+ */
+interface WgpuTagElement extends HTMLElement {
+	// Properties
+	wgpuViewId?: number;
+	transparent: boolean;
+	passthroughEnabled: boolean;
+	hidden: boolean;
+
+	// Visibility and interaction
+	toggleTransparent(transparent?: boolean): void;
+	togglePassthrough(enablePassthrough?: boolean): void;
+	toggleHidden(hidden?: boolean): void;
+
+	// Dimension sync
+	syncDimensions(force?: boolean): void;
+
+	// Debug helper
+	runTest(): void;
+
+	// Mask management
+	addMaskSelector(selector: string): void;
+	removeMaskSelector(selector: string): void;
+
+	// Events - listener receives a CustomEvent with detail property
+	on(event: WgpuEventTypes, listener: (event: CustomEvent) => void): void;
+	off(event: WgpuEventTypes, listener: (event: CustomEvent) => void): void;
+	emit(event: WgpuEventTypes, detail: unknown): void;
+}
+
+// Augment global types so querySelector('electrobun-wgpu') returns WgpuTagElement
+declare global {
+	interface HTMLElementTagNameMap {
+		"electrobun-wgpu": WgpuTagElement;
+	}
+}
+
+export { type WgpuTagElement, type WgpuEventTypes };

package/dist/api/bun/ElectrobunConfig.ts

@@ -139,6 +139,16 @@ export interface ElectrobunConfig {
 		 */
 		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;
+
 		/**
 		 * Override the Bun runtime version.
 		 * Format: semver string (e.g., "1.4.2")
@@ -149,6 +159,14 @@ export interface ElectrobunConfig {
 		 */
 		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[] | "*";
+
 		/**
 		 * macOS-specific build configuration
 		 */
@@ -171,6 +189,12 @@ export interface ElectrobunConfig {
 			 */
 			bundleCEF?: boolean;
 
+			/**
+			 * Bundle Dawn (WebGPU) for GPU-native rendering
+			 * @default false
+			 */
+			bundleWGPU?: boolean;
+
 			/**
 			 * Default renderer for webviews when not explicitly specified
 			 * @default 'native'
@@ -214,6 +238,12 @@ export interface ElectrobunConfig {
 			 */
 			bundleCEF?: boolean;
 
+			/**
+			 * Bundle Dawn (WebGPU) for GPU-native rendering
+			 * @default false
+			 */
+			bundleWGPU?: boolean;
+
 			/**
 			 * Default renderer for webviews when not explicitly specified
 			 * @default 'native'
@@ -255,6 +285,12 @@ export interface ElectrobunConfig {
 			 */
 			bundleCEF?: boolean;
 
+			/**
+			 * Bundle Dawn (WebGPU) for GPU-native rendering
+			 * @default false
+			 */
+			bundleWGPU?: boolean;
+
 			/**
 			 * Default renderer for webviews when not explicitly specified
 			 * @default 'native'

package/dist/api/bun/core/BrowserWindow.ts

@@ -5,11 +5,12 @@ import { type Pointer } from "bun:ffi";
 import { BuildConfig } from "./BuildConfig";
 import { quit } from "./Utils";
 import { type RPCWithTransport } from "../../shared/rpc.js";
+import { getNextWindowId } from "./windowIds";
+import { GpuWindowMap } from "./GpuWindow";
+import { WGPUView } from "./WGPUView";
 
 const buildConfig = await BuildConfig.get();
 
-let nextWindowId = 1;
-
 export type WindowOptionsType<T = undefined> = {
 	title: string;
 	frame: {
@@ -72,16 +73,38 @@ electrobunEventEmitter.on("close", (event: { data: { id: number } }) => {
 		}
 	}
 
+	// Clean up all WGPU views associated with this window
+	const wgpuViews = WGPUView.getAll().filter(v => v.windowId === windowId);
+	for (const view of wgpuViews) {
+		try {
+			// If ptr is null, the view was already cleaned up by the renderer or native cleanup
+			if (view.ptr === null) {
+				// Already cleaned up, skip
+			} else {
+				// Programmatic close path - remove the view
+				view.remove();
+			}
+		} catch (e) {
+			console.error(`Error cleaning up WGPU view ${view.id}:`, e);
+			// If remove() failed, at least mark it as cleaned up
+			view.ptr = null as any;
+		}
+	}
+
 	const exitOnLastWindowClosed =
 		buildConfig.runtime?.exitOnLastWindowClosed ?? true;
 
-	if (exitOnLastWindowClosed && Object.keys(BrowserWindowMap).length === 0) {
+	if (
+		exitOnLastWindowClosed &&
+		Object.keys(BrowserWindowMap).length === 0 &&
+		Object.keys(GpuWindowMap).length === 0
+	) {
 		quit();
 	}
 });
 
 export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
-	id: number = nextWindowId++;
+	id: number = getNextWindowId();
 	ptr!: Pointer;
 	title: string = "Electrobun";
 	state: "creating" | "created" = "creating";

package/dist/api/bun/core/GpuWindow.ts

@@ -0,0 +1,248 @@
+import { ffi } from "../proc/native";
+import electrobunEventEmitter from "../events/eventEmitter";
+import { type Pointer } from "bun:ffi";
+import { WGPUView } from "./WGPUView";
+import { getNextWindowId } from "./windowIds";
+
+
+export type GpuWindowOptionsType = {
+	title: string;
+	frame: {
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+	};
+	styleMask?: {};
+	titleBarStyle: "hidden" | "hiddenInset" | "default";
+	transparent: boolean;
+};
+
+const defaultOptions: GpuWindowOptionsType = {
+	title: "Electrobun",
+	frame: {
+		x: 0,
+		y: 0,
+		width: 800,
+		height: 600,
+	},
+	titleBarStyle: "default",
+	transparent: false,
+};
+
+export const GpuWindowMap: {
+	[id: number]: GpuWindow;
+} = {};
+
+// Clean up the window map when a window closes and optionally quit the app
+electrobunEventEmitter.on("close", (event: { data: { id: number } }) => {
+	const windowId = event.data.id;
+	delete GpuWindowMap[windowId];
+
+	// Clean up all WGPU views associated with this window
+	for (const view of WGPUView.getAll()) {
+		if (view.windowId === windowId) {
+			view.remove();
+		}
+	}
+
+});
+
+export class GpuWindow {
+	id: number = getNextWindowId();
+	ptr!: Pointer;
+	title: string = "Electrobun";
+	state: "creating" | "created" = "creating";
+	transparent: boolean = false;
+	frame: {
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+	} = {
+		x: 0,
+		y: 0,
+		width: 800,
+		height: 600,
+	};
+	wgpuViewId!: number;
+
+	constructor(options: Partial<GpuWindowOptionsType> = defaultOptions) {
+		this.title = options.title || "New Window";
+		this.frame = options.frame
+			? { ...defaultOptions.frame, ...options.frame }
+			: { ...defaultOptions.frame };
+		this.transparent = options.transparent ?? false;
+
+		this.init(options);
+	}
+
+	init({
+		styleMask,
+		titleBarStyle,
+		transparent,
+	}: Partial<GpuWindowOptionsType>) {
+		this.ptr = ffi.request.createWindow({
+			id: this.id,
+			title: this.title,
+			url: "",
+			frame: {
+				width: this.frame.width,
+				height: this.frame.height,
+				x: this.frame.x,
+				y: this.frame.y,
+			},
+			styleMask: {
+				Borderless: false,
+				Titled: true,
+				Closable: true,
+				Miniaturizable: true,
+				Resizable: true,
+				UnifiedTitleAndToolbar: false,
+				FullScreen: false,
+				FullSizeContentView: false,
+				UtilityWindow: false,
+				DocModalWindow: false,
+				NonactivatingPanel: false,
+				HUDWindow: false,
+				...(styleMask || {}),
+				// hiddenInset: transparent titlebar with inset native controls
+				...(titleBarStyle === "hiddenInset"
+					? {
+							Titled: true,
+							FullSizeContentView: true,
+						}
+					: {}),
+				// hidden: no titlebar, no native controls (for fully custom chrome)
+				...(titleBarStyle === "hidden"
+					? {
+							Titled: false,
+							FullSizeContentView: true,
+						}
+					: {}),
+			},
+			titleBarStyle: titleBarStyle || "default",
+			transparent: transparent ?? false,
+		}) as Pointer;
+
+		GpuWindowMap[this.id] = this;
+
+		const wgpuView = new WGPUView({
+			frame: {
+				x: 0,
+				y: 0,
+				width: this.frame.width,
+				height: this.frame.height,
+			},
+			windowId: this.id,
+			autoResize: true,
+			startTransparent: false,
+			startPassthrough: false,
+		});
+
+		this.wgpuViewId = wgpuView.id;
+	}
+
+	get wgpuView() {
+		return WGPUView.getById(this.wgpuViewId) as WGPUView;
+	}
+
+	static getById(id: number) {
+		return GpuWindowMap[id];
+	}
+
+	setTitle(title: string) {
+		this.title = title;
+		return ffi.request.setTitle({ winId: this.id, title });
+	}
+
+	close() {
+		return ffi.request.closeWindow({ winId: this.id });
+	}
+
+	focus() {
+		return ffi.request.focusWindow({ winId: this.id });
+	}
+
+	show() {
+		return ffi.request.focusWindow({ winId: this.id });
+	}
+
+	minimize() {
+		return ffi.request.minimizeWindow({ winId: this.id });
+	}
+
+	unminimize() {
+		return ffi.request.restoreWindow({ winId: this.id });
+	}
+
+	isMinimized(): boolean {
+		return ffi.request.isWindowMinimized({ winId: this.id });
+	}
+
+	maximize() {
+		return ffi.request.maximizeWindow({ winId: this.id });
+	}
+
+	unmaximize() {
+		return ffi.request.unmaximizeWindow({ winId: this.id });
+	}
+
+	isMaximized(): boolean {
+		return ffi.request.isWindowMaximized({ winId: this.id });
+	}
+
+	setFullScreen(fullScreen: boolean) {
+		return ffi.request.setWindowFullScreen({ winId: this.id, fullScreen });
+	}
+
+	isFullScreen(): boolean {
+		return ffi.request.isWindowFullScreen({ winId: this.id });
+	}
+
+	setAlwaysOnTop(alwaysOnTop: boolean) {
+		return ffi.request.setWindowAlwaysOnTop({ winId: this.id, alwaysOnTop });
+	}
+
+	isAlwaysOnTop(): boolean {
+		return ffi.request.isWindowAlwaysOnTop({ winId: this.id });
+	}
+
+	setPosition(x: number, y: number) {
+		this.frame.x = x;
+		this.frame.y = y;
+		return ffi.request.setWindowPosition({ winId: this.id, x, y });
+	}
+
+	setSize(width: number, height: number) {
+		this.frame.width = width;
+		this.frame.height = height;
+		return ffi.request.setWindowSize({ winId: this.id, width, height });
+	}
+
+	setFrame(x: number, y: number, width: number, height: number) {
+		this.frame = { x, y, width, height };
+		return ffi.request.setWindowFrame({ winId: this.id, x, y, width, height });
+	}
+
+	getFrame(): { x: number; y: number; width: number; height: number } {
+		const frame = ffi.request.getWindowFrame({ winId: this.id });
+		this.frame = frame;
+		return frame;
+	}
+
+	getPosition(): { x: number; y: number } {
+		const frame = this.getFrame();
+		return { x: frame.x, y: frame.y };
+	}
+
+	getSize(): { width: number; height: number } {
+		const frame = this.getFrame();
+		return { width: frame.width, height: frame.height };
+	}
+
+	on(name: string, handler: (event: unknown) => void) {
+		const specificName = `${name}-${this.id}`;
+		electrobunEventEmitter.on(specificName, handler);
+	}
+}