AGENTS.md

1# AGENTS.md
2 
3## Cursor Cloud specific instructions
4 
5This is an **Elixir library** (not a standalone app). It provides native desktop windowing for Phoenix LiveView apps via wxWidgets.
6 
7### Toolchain
8 
9Erlang and Elixir versions are managed via `.tool-versions` (asdf format). The Cloud VM uses **mise** to resolve these. After the update script runs, `erl` and `elixir` are available on `PATH`.
10 
11### System dependencies
12 
13wxWidgets GUI support requires `libwxgtk-webview3.2-dev` and `xvfb` on headless Linux. These are pre-installed in the VM snapshot.
14 
15### Key commands
16 
17| Task | Command |
18|---|---|
19| Install deps | `mix deps.get` |
20| Compile | `mix compile` |
21| Lint (all) | `mix lint` (runs compile --warnings-as-errors, format --check-formatted, credo --ignore refactor, dialyzer) |
22| Tests (fast, no wx) | `mix test.fast` |
23| Tests (wx only) | `xvfb-run -a mix test.wx` (or `DISPLAY=:99 mix test.wx` if xvfb is already running) |
24| Tests (all) | `xvfb-run -a mix test` |
25| Regression guard | `mix test.guard` |
26| Run code | `xvfb-run mix run -e '<elixir code>'` |
27| IEx shell | `xvfb-run iex -S mix` |
28 
29### Known issues
30 
31- **Dialyzer warnings**: `mix dialyzer` emits pre-existing warnings in `lib/mix/tasks/desktop.install.ex` related to the optional `igniter` dependency. These also fail in CI on `main`.
32- **Install test**: `test/mix/tasks/desktop.install_test.exs` fails because `Igniter.Test.phx_test_project/1` requires a working `mix phx.new` integration that does not fully resolve in all environments. This is pre-existing and CI does not run `mix test`.
33- **GLib warning**: `xvfb-run` may emit a harmless `GLib-WARNING` about `g_spawn_sync()` / `ECHILD`; this is cosmetic and can be ignored.
34 
35### Running without a display
36 
37All commands that load the `:wx` application (compile, test, iex) need a display. Use `xvfb-run` prefix on headless servers. The `NO_WX` environment variable selects the `Desktop.Backend.Browser` platform backend (OS browser fallback, no native window).
38 
39### Platform backends
40 
41| Backend | When |
42|---|---|
43| `Desktop.Backend.Wx` | Desktop host targets with OTP `:wx` (default) |
44| `Desktop.Backend.Json` | `:mobile_target` compile config or `OS.mobile?/0` — JSON bridge via `BRIDGE_PORT` |
45| `Desktop.Backend.Browser` | `NO_WX=1` or `:wx` unavailable |
46 
47Override with `config :desktop, :backend, :wx | :json | :browser | :auto` or a custom module.
48Custom backends may set `config :desktop, :menu_adapter, Some.Menu.Adapter` (used by `desktop_webview`).
49 
50### Platform abstraction (do not regress)
51 
52Library code is layered:
53 
541. **Public API** — `Desktop`, `Desktop.Window`, `Desktop.OS` (legacy helpers).
552. **Platform facades** — `Desktop.Platform.*` (route to the active backend).
563. **Backends** — `Desktop.Backend.Wx`, `.Json`, `.Browser` (implement behaviour).
57 
58**Rules for agents and contributors:**
59 
60| Do | Don't |
61|---|---|
62| Call `Desktop.Platform.System.locale/0`, `.open_external_url/1`, `Desktop.Platform.Window.*`, etc. from library code | Call `Desktop.Backend.*` or `:wx*` modules directly from `Window`, `Menu`, `OS`, etc. |
63| Keep `Desktop.OS.launch_default_browser/1` as a thin spawn wrapper to `Platform.System.open_external_url/1` only in `os.ex` | Re-implement browser launch, locale, or wx setup in `OS` with `case OS.type()` / `wx_available?` branches |
64| Let `Desktop.Platform.Helpers.with_wx_env/1` (used by `Platform.System` and `Platform.Window`) call `Desktop.Env.wx_use_env/0` before backend work | Call `Desktop.Env.wx_use_env/0` from app/library modules; never guard it with `if Platform.System.wx_available?()` |
65| Rely on `wx_use_env/0` being a safe no-op when `Desktop.Env` is down or `wx_env` is nil | Assume wx is loaded on Json/mobile or skip Platform because “it's only wx” |
66| On **Json/mobile**, use `Protocol.new/call/connect` with **bridge atoms** (e.g. `[:getSystemLanguage]`) | Put evaluated BEAM calls in RPC args (e.g. `Protocol.new(:wxLocale, [:wxLocale.getSystemLanguage()])` or `:wxLocale.getSystemLanguage/0` in `json.ex`) |
67| Put wx-specific logic in the matching **backend** module | Put Android/iOS `:ok` stubs or `Null.wx_call` in `OS` or `Window` |
68 
69**Regression guards:** `mix test.guard` runs `guard_boolean_ops.exs` and `guard_platform_abstraction.exs` (forbidden patterns under `lib/`).
70 
71**Tests:** `mix test.fast` — no wx; `xvfb-run -a mix test.wx` — wx backend; `mix test.guard` — static rules.
72