0
Fork 0
mirror of https://github.com/zeronsh/comet.git synced 2026-11-16 18:57:19 +00:00
comet/docs/reference/windows-development.md
fate e5466c5336
Windows browser, image previews in tool calls, selectable tool output (#813)
* Embed the browser on Windows and preview images in tool calls

- Browser tabs render pages inside Zeron on Windows (WebView2), matching macOS and Linux.
- Expanded tool calls preview the images they touch and free them on collapse.
  Right-click any transcript image to copy its path or the image itself.
- Paths, commands and output in expanded tool calls can be selected and copied.
- Fix: answering an agent question with multiple lines now grows the card instead
  of spilling text below it.

* Address review: repin zui upstream, harden the Windows browser and previews

- Depend on zeronsh/zui dce5c1f (zui#15 merged) and gpui-component
  47ccd07 instead of patching every gpui crate to a personal fork.
- Tool image previews: refuse UNC/device/drive-relative paths in the UI
  and, before any filesystem call, lexically jail requested paths in the
  engine (canonicalizing \\host\share opened an SMB session and leaked
  the user's NTLM hash); read chunks on the blocking pool; bound decodes
  with the shared raster limits; release keys a chip stops showing;
  decode base64 off the UI thread; copy sanitized SVG; cap output lines.
- Windows browser: fail closed on unreadable navigation targets; police
  subframes and cancel external-scheme launches; open tabs only for
  user-initiated popups (handled first); deny permission requests;
  disable web messages and host objects; cancel downloads silently
  unless the page itself is the file; recover from a browser-process
  exit on Reload; give each BrowserData its own InPrivate profile (no
  persistent fallback); sweep only folders of exited processes; never
  remount from an older composition generation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Wing <contact@winglee.io>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 23:06:18 -07:00

7.1 KiB

Windows development

Windows supports native x64 and ARM64 source builds, a per-user installer, and portable release ZIPs. The installer (dist/windows/zeron.iss, Inno Setup 6) installs into %LOCALAPPDATA%\Programs\Zeron without elevation, registers the Start menu entry, the zeron:// link handler, and the Settings → Apps uninstall entry. Both release packages carry zeron-update.json beside zeron.exe, which lets the app replace its executable in place from GitHub releases; keep it there for portable copies. Artifact names use Rust's architecture token (x86_64 or aarch64) so the updater can find the matching executable; published releases currently include x64 only. Background services are not supported yet.

scripts/package-windows.ps1 builds the portable ZIP, the updater payload .exe, and zeron-<version>-windows-<arch>-setup.exe (Inno Setup 6 required: winget install JRSoftware.InnoSetup). scripts/test-windows-installer.ps1 installs, inspects, and uninstalls the setup silently; it touches the current user's registration, so it only runs in CI or with -Force.

Build and run

Install stable MSVC Rust, Visual Studio C++ build tools, Windows SDK, CMake, and Git for Windows. On ARM64 also install LLVM so clang is on PATH — ring compiles its crypto with Clang on aarch64-pc-windows-msvc, and MSVC alone is not enough. Then run:

cargo run --locked -p zeron

Close the app before rebuilding. For release builds, use cargo build --release --locked -p zeron. If shader compiler discovery fails, set GPUI_FXC_PATH to the Windows SDK's fxc.exe.

Configuration and agent support

Setting Behavior
Application data %LOCALAPPDATA%\Zeron, falling back to %USERPROFILE%\AppData\Local\Zeron. Override with ZERON_DATA_DIR.
Managed adapters ZERON_ADAPTERS_DIR, then ZERON_DATA_DIR/adapters, then the default application's adapters directory.
Provider credentials Keep their provider-owned locations; changing Zeron's data root does not migrate them.
CODEX_EXECUTABLE Executable override. .exe (and .com) launch directly; .cmd/.bat shims launch through a wrapped cmd.exe with literal, individually escaped arguments. The override must exist on disk.

ACP, Claude, Codex, and opencode search PATH and known native installation directories. Discovery is PATHEXT-aware: npm's .cmd shims (and any .bat) resolve like cmd.exe would — per directory, extensions in PATHEXT order — and spawn through cmd.exe /e:ON /v:OFF /d /c inside the same Job Object, so npm- installed agents (codex, opencode, pi, a bare npm i -g grok) work without following node_modules payloads. Batch arguments containing CR/LF and batch executable paths containing percent expansion syntax are rejected. GUI launches additionally backfill %APPDATA%\npm, %LOCALAPPDATA%\{pnpm,Programs\nodejs,Volta\bin}, scoop shims, and %USERPROFILE%\{.local\bin,.bun\bin} from PATH. Managed JavaScript adapters run through Node; installation requires node.exe beside node_modules/npm/bin/npm-cli.js. Volta's selected tool-image npm location is unsupported.

An OS file lock prevents engines from sharing a profile; engine.lock.pid is only diagnostic. Terminals use ConPTY. Windows agents, login commands, adapter installs, and terminals own their child process trees through Job Objects. Terminal close waits up to five seconds for cleanup and reports failure; shutdown/drop log failures. Processes started through external services or brokers are outside this ownership. Closing a terminal or exiting its shell also terminates processes detached inside that job (including start children).

Embedded browser

Browser tabs embed Microsoft Edge WebView2 (the Evergreen runtime ships with Windows 10/11) in visual-hosting mode. Each page is a DirectComposition visual mounted in the zui overlay plane's native layer: GPUI's base content, then the page, then deferred GPUI content (menus, tooltips, prompts) in a second swap chain. DWM composites the page directly, without copies or child windows. A frame without deferred content detaches the overlay and draws nothing extra.

GPUI receives all pointer input, so anything drawn above the page occludes it naturally; presses, moves and wheel events that reach the page element are forwarded with SendMouseInput. The page owns the keyboard while focused; browser and app shortcuts are intercepted with AcceleratorKeyPressed and dispatched to GPUI. A press on GPUI content, or an interactive overlay opening, returns keyboard focus to the window.

All tabs of a window share one InPrivate environment (one browser process). Hidden tabs are unmounted and set invisible, so Chromium throttles them. The user-data folder (%TEMP%\zeron-webview2) holds only runtime caches; when another process still holds it (a second Zeron, or one shutting down after a quick restart), the window falls back to its own folder, and stale ones are swept in the background. Per-frame updates touch WebView2 only when geometry or visibility changed.

Frosted window chrome uses native Acrylic and requires Windows Settings > Personalization > Colors > Transparency effects. Content cards and popovers remain opaque because in-app backdrop blur is not supported. The pinned Zui DirectX fix supplies the renderer layout and edge-fade corrections.

When Windows disables Animation effects, Zeron's Reduce motion: System setting skips transitions and gives activity grids a gentle 2.4-second brightness pulse. Reduce motion: On keeps those indicators still; Off restores the usual travelling wave. Pause animations in background also pauses activity grids when the main window loses focus.

Verification

Windows CI builds the release application and tests application startup, agent discovery/protocols, process cleanup, ConPTY, locking, UI behavior, and shader layouts. Shared Rust regressions run on Linux and macOS. To run the engine and harness checks locally:

cargo test --locked -p zeron-engine -p zeron-harness --lib
cargo test --locked -p zeron-harness --features native-fixture --test codex_availability --test windows_native
cargo test --locked -p zeron-engine --test codex_catalog --test codex_login_resolution --test auth

Fixtures use synthetic agents, so these tests do not establish authenticated provider compatibility. GUI probes are optional CI dispatch checks and can also run on an interactive Windows desktop after building the release app:

cargo build --release --locked -p zeron-ui --example windows-render-fixture --features windows-render-fixture
./scripts/test-windows-lifecycle.ps1 -Runs 5
./scripts/test-windows-rendering.ps1

The lifecycle probe uses isolated data and provider homes. The renderer probe captures only its synthetic window. Results go to ignored target/windows-lifecycle-* and target/windows-render-* directories.

Remaining acceptance work includes authenticated provider runs and shutdown, broader GPU/DPI coverage, accessibility, cross-device parity, concurrent-launch log rotation, and invalid-window teardown diagnostics.