[foxnne]

Part of fizzyedit/work#41 (EMBEDDED_EDITOR_PLAN step 5, fizzyedit/work#32)

What changes

sdk/remote/Client.zig is what a host adapter (Blender, Unreal, ...) calls first. It does five things:

• Finds the installed fizzy. FIZZY_EXE wins. Otherwise it checks the usual places per OS: /Applications and ~/Applications plus Launch Services on macOS; Velopack under %LOCALAPPDATA% plus App Paths on Windows; ~/.local, an AppImage and PATH on Linux.
• Asks for the socket. It runs fizzy --control-path, with --profile or FIZZY_PROFILE, unless the host names the socket.
• Starts fizzy quietly if nothing listens. It runs --quiet (macOS: open -g -j, never taking focus) and dials with backoff until timeout_ms.
• Upgrades and says hello. It sends GET /remote and exchanges hellos.
• Reconnects after a drop with the same steps.

Errors are distinct: NotInstalled, NotRunning, FizzyTooOld, ClientTooOld, TimedOut, StartFailed and Sandboxed. A sandboxed host that reaches neither the install nor the socket gets Sandboxed. A private second fizzy is never started.

capi.zig and fizzy_remote.h are the C ABI: open, reconnect, send/recv whole frames, close.

The file is Client.zig, not client.zig as the kickoff named it, because the lint file-alias rule requires a struct file to be TitleCase. build/app.zig now builds the fake fizzy and hands its path to the remote tests through an options module; this replaces the old generic list entry.

Over the soft 800-line limit: about 900 lines outside tests and docs. That counts the fake fizzy (about 120 lines) and a mostly-comment header (about 100 lines).

SDK impact

• None (nothing under sdk/src/**, no fingerprint move)

Verified

Tests run against fake_fizzy.zig, an executable listening on a test socket. They cover found without a second start, quiet start, not installed / not running / sandboxed, slow start, timeout then found later, crash during start (StartFailed), version skew both ways, and drop then reconnect. The C ABI is tested on top of the same fake.

• macOS: not tried by hand. The module cross-compiles for aarch64-macos, and candidates is tested as strings. mdfind and open -g -j are untested.

• Windows: not tried by hand. The module cross-compiles for x86_64-windows. reg query output parsing is tested; the registry lookup itself is not.

• Linux: all of these pass:

  • scripts/check-fmt.sh
  • zb build test (35/35 remote tests)
  • test-integration
  • check-web
  • test-sdk-version
  • lint
  • check-tests-reached

  The remote tests also pass natively with -lc.

• Web: not applicable. check-web passes.

Follow-ups

• Build the C ABI as a shared library target. For now it is compiled and tested through the test root.
• Fizzy's side of GET /remote (plan steps 3 and 4) is not here. The tests use the fake.

---

Generated by Claude Code