electrobun 1.18.4-beta.17 → 1.18.4-beta.19

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,42 @@
 
 ## 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
+```
+
+Or bootstrap the same interactive initializer from npm or Bun. This installs
+Hutch when it is not already available:
+
+```bash
+npx electrobun init
+# or
+bunx 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

package/bin/electrobun.cjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+"use strict";
+
+const { existsSync, mkdtempSync, rmSync, writeFileSync } = require("node:fs");
+const { get } = require("node:https");
+const { homedir, tmpdir } = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const packageVersion = require("../package.json").version;
+const installerBaseUrl = "https://hutch.blackboard.sh/hutch";
+const maxInstallerBytes = 1024 * 1024;
+
+function normalizeChannel(value) {
+	if (value === "stable") return "production";
+	if (value === "production" || value === "canary") return value;
+	return null;
+}
+
+function channelForVersion(version, environment) {
+	for (const key of ["ELECTROBUN_HUTCH_CHANNEL", "HUTCH_ACTIVE_CHANNEL"]) {
+		const selected = normalizeChannel(environment[key]);
+		if (selected) return selected;
+	}
+	return version.includes("-") ? "canary" : "production";
+}
+
+function hutchBinaryPath(channel, environment, platform, userHome) {
+	if (environment.ELECTROBUN_HUTCH_BINARY) {
+		return environment.ELECTROBUN_HUTCH_BINARY;
+	}
+	const dashHome = environment.DASH_HOME || path.join(userHome, ".dash");
+	const command = channel === "canary" ? "hutch-canary" : "hutch";
+	const pathApi = platform === "win32" ? path.win32 : path.posix;
+	return pathApi.join(dashHome, "bin", `${command}${platform === "win32" ? ".exe" : ""}`);
+}
+
+function download(url, redirects = 0) {
+	if (redirects > 5) return Promise.reject(new Error("too many installer redirects"));
+	return new Promise((resolve, reject) => {
+		const request = get(url, (response) => {
+			if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+				response.resume();
+				resolve(download(new URL(response.headers.location, url).href, redirects + 1));
+				return;
+			}
+			if (response.statusCode !== 200) {
+				response.resume();
+				reject(new Error(`installer download returned HTTP ${response.statusCode}`));
+				return;
+			}
+
+			const chunks = [];
+			let size = 0;
+			response.on("data", (chunk) => {
+				size += chunk.length;
+				if (size > maxInstallerBytes) {
+					request.destroy(new Error("installer download exceeded 1 MiB"));
+					return;
+				}
+				chunks.push(chunk);
+			});
+			response.on("end", () => resolve(Buffer.concat(chunks)));
+		});
+		request.on("error", reject);
+	});
+}
+
+function checkedSpawn(command, args, options) {
+	const result = spawnSync(command, args, options);
+	if (result.error) throw result.error;
+	if (result.status !== 0) {
+		throw new Error(`${command} exited with status ${result.status ?? "unknown"}`);
+	}
+}
+
+async function installHutch({ channel, environment, platform }) {
+	const temporary = mkdtempSync(path.join(tmpdir(), "electrobun-hutch-"));
+	try {
+		if (platform === "win32") {
+			const installer = path.join(temporary, "install.ps1");
+			writeFileSync(installer, await download(`${installerBaseUrl}/install.ps1`));
+			checkedSpawn(
+				"powershell.exe",
+				[
+					"-NoProfile",
+					"-NonInteractive",
+					"-ExecutionPolicy",
+					"Bypass",
+					"-File",
+					installer,
+					"-Channel",
+					channel,
+				],
+				{ env: environment, stdio: "inherit" },
+			);
+		} else {
+			const installer = path.join(temporary, "install.sh");
+			writeFileSync(installer, await download(`${installerBaseUrl}/install.sh`), {
+				mode: 0o700,
+			});
+			checkedSpawn("sh", [installer, "--channel", channel], {
+				env: environment,
+				stdio: "inherit",
+			});
+		}
+	} finally {
+		rmSync(temporary, { force: true, recursive: true });
+	}
+}
+
+function runHutch({ binary, args, environment }) {
+	const result = spawnSync(binary, ["electrobun", ...args], {
+		env: environment,
+		stdio: "inherit",
+	});
+	if (result.error) throw result.error;
+	if (result.status !== null) return result.status;
+	return result.signal === "SIGINT" ? 130 : result.signal === "SIGTERM" ? 143 : 1;
+}
+
+async function main(options = {}) {
+	const args = options.args || process.argv.slice(2);
+	if (args[0] !== "init") {
+		throw new Error(
+			"the npm entry point supports only `electrobun init`; use `hutch electrobun` for project commands",
+		);
+	}
+	const environment = options.environment || process.env;
+	const platform = options.platform || process.platform;
+	const version = options.version || packageVersion;
+	const userHome = options.userHome || homedir();
+	const fileExists = options.existsSync || existsSync;
+	const install = options.installHutch || installHutch;
+	const run = options.runHutch || runHutch;
+	const channel = channelForVersion(version, environment);
+	const binary = hutchBinaryPath(channel, environment, platform, userHome);
+
+	if (!fileExists(binary)) {
+		if (environment.ELECTROBUN_HUTCH_BINARY) {
+			throw new Error(`ELECTROBUN_HUTCH_BINARY does not exist: ${binary}`);
+		}
+		console.error(`Electrobun requires Hutch; installing the latest ${channel} release...`);
+		await install({ channel, environment, platform });
+	}
+	if (!fileExists(binary)) throw new Error(`Hutch was not installed at ${binary}`);
+	return run({ binary, args, environment });
+}
+
+if (require.main === module) {
+	main()
+		.then((status) => {
+			process.exitCode = status;
+		})
+		.catch((error) => {
+			console.error(`electrobun: ${error.message}`);
+			process.exitCode = 1;
+		});
+}
+
+module.exports = {
+	channelForVersion,
+	hutchBinaryPath,
+	main,
+};

package/dash.config.ts

@@ -1,7 +1,7 @@
-// @dash cli=0.5.0-canary.5 cottontail=0.2.3
+// @dash cli=0.5.0-canary.9 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",
@@ -34,7 +34,7 @@ export default {
 		"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/bun 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: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",
@@ -46,7 +46,7 @@ export default {
 		"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:npm-bootstrap": "node scripts/run-cottontail-test.js bin/npm-bootstrap.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",

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/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,14 +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;
@@ -49,9 +56,9 @@ interface WebviewTagElement extends HTMLElement {
 	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

@@ -8,12 +8,14 @@ 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 = {
@@ -228,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]: {
@@ -237,7 +239,7 @@ export interface ElectrobunConfig {
 				 * Entry point for this view's TypeScript code
 				 */
 				entrypoint: string;
-			} & BundlerOptions;
+			} & ViewBundlerOptions;
 		};
 
 		/**
@@ -259,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.
@@ -468,7 +429,8 @@ export interface ElectrobunConfig {
 			autoGrantPermissions?: WindowsWebView2Permission[];
 
 			/**
-			 * Path to application icon (.ico format)
+			 * 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"