Electrobun

Electrobun is a compact, cross-platform desktop framework for macOS, Windows, and Linux. It allows developers to build UIs using web technologies (HTML, CSS, TypeScript) while providing a native layer for windows, menus, trays, auto-updates, and WebGPU surfaces.

Unlike frameworks that bundle a full Chromium and Node.js instance, Electrobun uses the operating system's existing system webviews (WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux) and a small, high-performance runtime called Cottontail for the main process. This results in significantly smaller application sizes.

The ui-wgpu template demonstrates several key capabilities of the Electrobun UI runtime:

• Fine-grained reactivity without a compiler: Props can be thunks (functions) that update specific tree properties without a full re-render. For example: bg: () => hover() ? "#232336" : "#1b1b28".
• Solid-style state management: Uses createStore and produce() for immutable-feeling batch updates with path-level invalidation.
• Markup-like Builder API: Components are plain functions using a builder pattern, such as ui.column({...}, () => { ... }).
• Native Layer Integration: You can embed native layers directly as UI elements, such as <electrobun-wgpu> (a Dawn view via wgpuSurface) and <electrobun-webview> (an out-of-process webview), positioned using the UI layout engine.

The current platform support status for Electrobun is as follows:

The project is divided into a main process (Bun) and a renderer process (Mainview):

• src/bun/index.ts: The Main Process. It is responsible for window creation and performing native file system operations.
• src/mainview/index.html: The UI structure for the photo booth.
• src/mainview/index.css: The styling for the interface.
• src/mainview/index.ts: The Renderer Process. It contains the camera logic, video stream management, and photo management.

When building for release, Hutch automates the creation of all necessary distribution artifacts in a single pass, including:

• The runnable application.
• A small self-extracting wrapper.
• Update metadata.
• A compressed full-update archive.
• Platform-specific installer artifacts.
• Code signing and notarization.

Updates are delivered as binary diffs to minimize download sizes, with a full-download fallback mechanism. You can host these artifacts on any static storage (e.g., S3, R2, GitHub Releases), and the built-in updater will manage the distribution.

Electrobun uses a retained tree of nodes (boxes, text, native-layer anchors).

Key Rendering Concepts

• Fine-grained Reactivity: Reactive props are handled via thunks; each prop becomes an effect that updates a single tree property.
• Efficient Frame Ticks: A frame tick polls input and only runs layout and GPU drawing if the tree is marked as dirty. Idle UI performs no layout, paint, or GPU work.
• Instanced Drawing: The tree is flattened into an instance buffer and issued as one instanced draw call to the window's Dawn surface.
• GPU Stack: UIWindows are built on top of GpuWindows, utilizing the same native window and WGPUView surface.

Electrobun updates use a binary-diff approach to minimize download sizes.

1. The installed app compares its local hash with hosted update metadata.
2. It attempts to apply a binary patch from the installed hash to the current release.
3. If the patch is verified, the bundle is replaced.
4. If no valid patch path exists, it falls back to downloading the full compressed archive.

Implementation Note: There is no dedicated update server required; static object storage is sufficient for hosting updates. The application manages the check, download, install, and relaunch lifecycle via the Updater API.

Electrobun uses a decoupled process model to enhance security and stability:

1. Main Process: Owns the application state and all privileged native objects (windows, menus, etc.).
2. Browser Views: Run isolated from the main process. They render the UI and communicate with the main process via Electrobun's typed RPC and event bridges.

This separation ensures that even if a web view is compromised or buggy, it cannot access privileged native APIs unless they are explicitly exposed through the RPC bridge.

To place a native WGPU surface inside a webview layout (so it follows an element), use the <electrobun-wgpu> tag. This tag reports a native view ID to the host page, which is then sent to the main process via application RPC.

For native main processes (Zig, Rust, Go, Odin), you must use the SDK-level surface bridge to manage the lifecycle and marshal surface calls to the main thread.

On Linux, Electrobun uses a dual-binary approach to avoid dlopen failures caused by hard-linking CEF libraries. The selection of the binary is determined by the bundleCEF setting in electrobun.config.

Available Binaries

• libNativeWrapper.so (GTK-only)
  • Use case: When bundleCEF: false is set.
  • Dependencies: WebKitGTK, GTK+3, AppIndicator.
  • Benefit: Small bundle size (~1.46MB).
• libNativeWrapper_cef.so (CEF-enabled)
  • Use case: When bundleCEF: true is set.
  • Dependencies: WebKitGTK, GTK+3, AppIndicator + CEF libraries.
  • Benefit: Full CEF functionality, larger size (~3.47MB).

Selection Logic

During application packaging, Hutch selects the appropriate wrapper based on the build.linux.bundleCEF configuration. This selection is handled during the packaging phase, not within the thin electrobun npm bootstrap.