elizaos--eliza/packages/app-core/platforms/electrobun

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

Run from the canonical shell directory (the apps/app/electrobun/ folder is a compat wrapper regenerated by scripts/ensure-legacy-electrobun-compat.mjs and should not be used as a build root):

cd eliza/packages/app-core/platforms/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

First-party Remotes

Prototype ElizaLaunch Remotes are folded into this shell under remotes/ and seeded on desktop startup by src/first-party-remotes.ts. They use the existing @elizaos/plugin-remote-manifest install/start/log runtime instead of a parallel module system.

• eliza.runtime is required and runs as a Runtime Remote adapter over the existing Electrobun AgentManager; production mode must not start a second elizaOS runtime process.
• eliza.fs, eliza.local-model, eliza.pty, and eliza.git are first-party capability Remotes.
• eliza.surface is a dev/admin surface and is only included when ELIZA_ENABLE_DEV_REMOTES=1.

The current worker-to-worker bridge supports the upstream invoke-remote-plugin host request, and renderer/dev views can call workers through the typed remote-plugin:invokeWorker RPC. Broad automatic event broadcast is still a host-level follow-up, so dev surfaces should use explicit invokes plus polling where needed.

eliza.surface is not the product dashboard. Keep it as an inspector harness while product work moves toward dynamic agent-created canvas/A2UI views, Eliza-1 routing, voice loop latency tracing, and OmniVoice/Kokoro validation.

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.