Eliza Electrobun shell (@elizaai/electrobun)

This package is the native desktop wrapper around the Eliza companion UI: it creates the BrowserWindow, loads the Vite renderer, wires RPC to native modules, and (on macOS) applies vibrancy, traffic-light layout, and frameless window chrome (drag + resize).

Why this exists

Electrobun is the shell, not the agent runtime. The same Eliza runtime (dist/ / packaged eliza-dist) is used from CLI, server, and desktop; this folder only hosts main-process TypeScript, preload, native .mm helpers, and Electrobun config.

macOS window chrome (read this before editing)

titleBarStyle: "hiddenInset" removes the standard title bar. WKWebView then covers the client area. Dragging and inner-edge resizing are handled with transparent native views above the web view so AppKit owns hit testing and cursor rects — not the HTML layer.

• Why: WebKit applies page cursors continuously; NSTrackingArea under the web view could not reliably show resize cursors or receive drags, and competing NSCursor updates caused flicker.
• Docs (WHYs, file map, build): Electrobun macOS window chrome (or docs/guides/electrobun-mac-window-chrome.md in-repo).
• Code: native/macos/window-effects.mm — ElectrobunNativeDragView (top strip), ElizaResizeStripView (right / bottom / BR), elizaChromeDepthPoints (per-screen thickness when host passes height ≤ 0).
• Main process: src/index.ts — applyMacOSWindowEffects, alignChrome on resize, move (display changes), and webview dom-ready so strips stay above WKWebView after layout.
• FFI: src/native/mac-window-effects.ts.

Rebuild native effects after changing .mm

cd apps/app/electrobun && bun run build:native-effects

Produces src/libMacWindowEffects.dylib (consumed via Bun FFI at runtime).

Common commands

| Command | Purpose | |--------|---------| | bun run dev | Preload build + electrobun dev | | bun run build | Preload + production Electrobun build | | bun run test | Vitest (src/__tests__, etc.) | | bun run build:native-effects | Compile macOS window-effects.mm → dylib |

WebGPU status log and macOS version (Darwin)

Startup logs [WebGPU Browser] … use os.release(), which reports the Darwin kernel major (e.g. 25.x on macOS 26 Tahoe)—not the macOS marketing major in About This Mac. Why it matters: a single Darwin − 9 rule matched macOS 11–15 but labeled Tahoe as “macOS 16” and wrong-feature-gated WKWebView WebGPU. getMacOSMajorVersion() in src/native/webgpu-browser-support.ts implements the two-part mapping; full WHYs and the reference table: Darwin vs macOS version (Electrobun WebGPU).

Related repo docs

• Desktop app — install, runtime modes, native modules.
• Electrobun startup — agent/bootstrap guards in src/native/agent.ts.
• Darwin vs macOS version (WebGPU) — uname -r vs macOS 26+, WebGPU gating rationale.