Desktop GUI Build
Class-level skill: build a native desktop GUI application (Tauri 2.x on Windows) over an existing CLI or Rust/JS core, with a full screen suite, settings, a command palette, keyboard-first UX, and verification artifacts (builds, tests, end-to-end smoke test). This is the pattern the NLP-CLI desktop app used: a verified Rust core, a thin JSON-protocol service, and a vanilla-TS frontend.
When to Use
Use this skill whenever the task involves windowed desktop GUI work on Windows where the deliverable is a real desktop app (not a browser dashboard), including:
- Scaffolding a Tauri 2.x app around an existing CLI or library core.
- Migrating or wrapping an existing command-line or library into a windowed shell.
- Adding screens, settings, a command palette, themes, or accessibility to a desktop app.
- Verifying a multi-component desktop build (Rust backend + TS/HTML/CSS frontend + native shell).
Mandatory default for this user's desktop work: Tauri 2 (pywebview is a fallback only). A desktop GUI is a windowed native app, never a browser dashboard.
Standing rules (apply to every instance)
- Proceed with all in order. Full implementation, never a stub or a "will add later" placeholder. Every screen, setting, command and wiring path is implemented and connected before the deliverable is called done.
- Verification-first with working artifacts. A working MVP means cargo check/build clean, npm run build clean, tests pass, and an end-to-end smoke test against the real binary/core all return sensible values. No invented output. If a real path is blocked, say so plainly.
- Accessibility is default, not a polish item. Every screen is keyboard navigable, has ARIA labels where needed, visible focus, and never relies on colour alone. Test contrast at theme boundaries.
- Generative UI as a core architectural feature where the app is user-facing: UI must be data-driven and agents must be able to add/modify/optimize components in real time, not static hand-authored HTML.
- Next steps = implementation, not release advice. The deliverable is a working artifact plus a short report of what was verified and what is left.
- No stubs. If a component is hard to implement, implement it partially with a clearly labelled fallback, never leave a feature unbuilt inside a done screen.
- Command contracts live in ONE place. Tauri command names must appear in a single typed client module (backend and frontend both import from it), never hand-written in two places.
Process
1. Inventory the current state (where the previous agent left off)
- Read the repo design docs first (README, ARCHITECTURE, GUI-DESIGN, GAPS, CLI, FROZEN) - they define the feature set and approved defaults.
- Read git log and git status. The commit graph is the source of truth for what code exists; untracked files are tentative.
- Walk the tree and list source, data, spec, models, docs, target dirs. Note sizes so you know what a trained model counts as and what is missing.
- Do not assume a partial feature exists because a file name suggests it. Verify each feature path by reading source or running the binary.
2. Decide the shell
| Option | Best for | Drawbacks |
|---|---|---|
| Tauri 2 (WebView2) | Every desktop GUI job (user default). Native window, small bundle, Rust backend. | WebView2 runtime required; dev-mode quirks on Windows. |
| pywebview + local backend | Quick wrappers, fallback when WebView2 blocked. | Heavier runtime, less native. |
| ratatui TUI (same binary) | Terminal-first products (GUI-DESIGN may propose). | Not a windowed GUI; user asked for GUI, not the default. |
Decision rule: user asked for a GUI - Tauri 2 first. If a Tauri native launch fails (no WebView2, file locks), fall back to pywebview with the same frontend bundle, then report the blocker.
3. Choose backend wiring
- Reuse the verified core in-process for everything derived from it (routing, teach/review, verify, training, eval). In-process usage is exactly what the CLI does internally, so the desktop shell can never drift from the CLI.
- Spawn the CLI binary as a child process only for natural subprocesses (cli(args) - e.g. diagnostics, running the command line). Keep the spawn without a console window (CREATE_NO_WINDOW on Windows).
- Prefer plain Rust Result<T, String> in the service layer, with Tauri commands as thin wrappers. Keeps the service testable without a Tauri app (cargo test + integration tests).
- Train progress: run train_observed on a background thread, observer sends JSON progress lines over an mpsc channel; the async Tauri command polls the channel and emits train-progress / train-complete events to the frontend. Cancel = a global AtomicBool (thread_local, reachable from cancel_train) the observer checks at each epoch boundary; the worker is joined and the state cleared.
- Audit log schema is the CLI's one (session, id, at_unix, input, tool, risk, args, args_sha256, answer). Never invent a new audit format.
4. Layout the app in the workspace
- New desktop app = a separate cargo package (packages/desktop/src-tauri/), a member of the existing workspace, never editing the existing Rust crates.
- Frontend sources in packages/desktop/src/; Vite builds to packages/desktop/dist/; tauri.conf.json build.frontendDist points at ../dist.
- build.rs builds/spawns cargo build --release -p nlp-cli in the workspace and copies target/release/nlp-cli.exe into src-tauri/bin/nlp-cli.exe, emitting nlp-cli = { env: "NLP_CLI_BIN" } so the backend knows the embedded binary path at compile time.
- Do not give the desktop app a name that collides with the CLI binary (nlp-cli.exe vs nlpcli-desktop.exe).
5. Build the backend service
- audit.rs - audit log schema + append/read helpers (CLI-compatible).
- config.rs - desktop settings: TOML next to the project, defaults(), load() (missing = defaults), atomic save() (temp + rename), settings_schema() (category tree, every field with default/origin, locked flags), export/import JSON.
- service.rs - the service struct holding project_dir plus run_route, run_teach, run_review, audit_items/append_audit, load_spec/load_model, run_train (progress + cancel), run_verify, run_model_status, run_evaluate (in-process core -> structured + Markdown), run_tools, run_config_show, run_save_config, run_diagnostics, run_cli. All Result<T, String>.
- commands.rs - #[tauri::command] hands that translate Tauri args into service calls plus event emission (train-progress, train-complete, train-error) plus the TRAIN_STATE global for cancel.
- Unit tests inside each module; one integration test (src-tauri/tests/) that copies the real NLP-CLI project (spec + model + data) into a temp dir and asserts real routing decisions, teach/review round-trip, audit schema, verify truth, safety failure count = 0, config schema + save/load, diagnostics fields, and train producing a new model + sidecar. This is the wiring proof.
- Keep cargo fmt + cargo clippy clean on the new crate (the repo standard is 0 warnings).
6. Build the frontend
- Scaffold: package.json (vanilla TS + vite + @tauri-apps/api), tsconfig.json (strict + noUnusedLocals + noUnusedParameters - the repo standard), vite.config.ts (base: './', build.outDir: 'dist', dev port 1420), tauri.conf.json (window, frontendDist: '../dist', beforeDevCommand + beforeBuildCommand, devUrl, bundle), src/main.ts + src/index.html + src/global.css.
- src/tauri-client.ts - the single typed interface over invoke + event listeners (listen('train-progress') etc.). Every screen imports here; command names match the backend exactly. Keep fetch() as a browser fallback so the same bundle works in dev/browser and native.
- State (state.ts): a singleton with subscribe(); screens re-render on navigation and train-progress events. Persistence: settings to TOML via save_config; history via backend history command.
- Screens (a screen base class Screen with id, title, primaryAction, render()): Ask, History, Review, Train, Model, Evaluate, Tools, Settings, Help, Diagnostics - the nine top-level screens from GUI-DESIGN.md section 4, each with one primary action.
- Ask screen: input + decision card + trace + confirm dialog + suggestions + status line. Keyboard: Enter submit, Alt+Enter new line, Up/Down history, Ctrl+R reverse search, Ctrl+P palette.
- Settings screen: category tree + search box; each field shows name/eff/default/origin/locked with a lock icon and reason; editable text/number/select/bool/path/list; protected paths add-only; export/import; theme picker (auto/dark/light/mono/high-contrast); colour + glyphs; history retention; keys preset/bindings; advanced log level/diagnostics.
- Train screen: config (epochs/hidden/seed), Start with progress log + Cancel, results summary + digest + comparison with the previous model, retraining note.
- Model screen: path, digest, verify-on-start, provenance, format/version, Verify now and Retrain.
- Evaluate screen: T1 classifier alone, full pipeline, safety suite tables + misses + export (Markdown + JSON).
- Tools screen: catalogue from the spec (name, risk, slots, templates, broad flags) + search + Try to fill the Ask input. Generated from the spec, never hand-maintained.
- Command palette (Ctrl+P): fuzzy search over every action in the app with keyboard nav (Up/Down/Enter/Esc).
- Dashboard chrome: status bar (primary action, model-verified state, theme), confirmation modal (tool + args + approve/decline), toasts, onboarding tour on first run, Diagnostics page.
- Accessibility pass: focus-visible outlines, role/aria, live regions for toasts/status, state labels not colour alone, contrast check across themes.
7. Verify
- Backend: cargo check + cargo fmt --check + cargo clippy on the new crate, cargo test (unit + integration test).
- Frontend: npm install (project-local), npm run build (tsc && vite build) - no type errors in the console output.
- Desktop: cargo tauri build ends with a built binary and the frontend assets embedded. If the build passes but the binary fails to run (WebView2 0x800700AA, stale binary), follow the recovery sequences: kill stale app.exe, remove src-tauri/target, rebuild.
- End-to-end smoke test with the real project: run the service against X:\Projects\NLP_CLI (real model, real data) and print route/verify/evaluate/history results. Compare the numbers with the CLI's own reports (the desktop app's numbers must match).
- Visual verification is not possible in this headless environment; do not claim it. Structural verification (build + tests + smoke) is the honest bar.
8. Deliver
- State the deliverable (path, what it contains), what was verified (commands + results), what is left (e.g. visual confirmation). No release advice - the user asked for working software.
Windows toolchain notes (this host)
- cargo/rustc live on X: (X:\Dev\cargo\bin); cargo-tauri (tauri-cli 2.11.4) is there. Use the full path or rely on the bash env; never cargo from an unqualified cmd (cmd does not see it).
- The terminal tool runs commands through bash (git-bash/MSYS) on this host, not PowerShell/cmd. MSYS paths like /c/Users/... work; native Windows tools need C:/Users/x-style forward-slash paths (not translated). npm is npm.CMD (a batch file) - subprocess.run cannot exec it directly; use cmd /c npm ...
- Node 26, npm 11, pnpm, Python 3.14, git all present. Network access to registry.npmjs.org works, so npm install is the dependency source of truth.
- cargo tauri dev on Windows can leave a stale app.exe holding target/debug/app.exe - kill it before rebuilding; if the lock persists, temporarily rename the binary in Cargo.toml, rebuild, restore the name.
- cargo tauri dev can fail with exit 124 from a non-tty shell; prefer the manual dev flow (build frontend, start cargo tauri dev or run the binary manually and open the Vite dev server URL) over blind retries. |- In a Tauri desktop app the frontend is served as file:// assets under base: './' - Vite must output ./assets/... references, not absolute /assets/..., or JS/CSS never load in the native window.
Cross-platform Rust workspace integration (new)
This section is written for the Browzeit + Custode integration work, the most recent session's lesson set. It applies to any Rust multi-crate workspace on Windows where MSYS (bash) and native Windows tools share the same workspace.
Path resolution is the #1 failure mode
cargo, rustc, and other native Windows tools do NOT have MSYS path conversion: a path like /x/Projects/Browzeit is seen by cargo as a literal path under a /-prefixed drive, not as Z:\x\Projects\Browzeit. Rules:
- For
cargo check/cargo build(run through theterminaltool), use theX:\Projects\...orC:\Users\...format with backslashes — this is what the native toolchain expects. - For
Cargo.tomldependencypathfields, use forward slashes:path = "X:/Projects/Browzeit/browzeit/crates/traits". This is valid in both MSYS and native Windows build systems. cdin bash (MSYS) maps/x→Z:\xbut native tools see the raw/xas an unsupported prefix. Never pass MSYS-style paths tocargo,rustc, or other native Windows binaries.
Tool write behaviors (critical pitfalls)
write_filerefuses to overwrite a file it has not seen in the current session, even if the file exists on disk under a different path. The fix:read_filethe file first (even a partial view), thenwrite_fileorpatchagain. This was the cause of six of the source files in this session being silently written to the wrong directory.patchcannot create a new file — it requires an existing match. To create a new file, usewrite_fileorterminal.terminalruns through bash (MSYS). Heredocs (<< 'END') break on single quotes and backslashes in content. For complex file content (Rust source with//!doc comments, triple-quoted strings), write the file via a Python script usingopen(path, 'w')instead of a bash heredoc.
Cargo offline and dependency resolution
--offlinemode will fail on any dependency that needs to be downloaded from the registry, even if the crate is written correctly and all workspace members resolve. This happened withrustls v0.22.4being unavailable in the offline cache. Use normal (non-offline)cargo checkwhen dependencies are missing from the cache.- Rust package names use hyphens in
Cargo.toml(name = "browzeit-core") but underscore-separated in Rust code (use browzeit_core::...). When referencing workspace members, match the package name exactly.
Multi-crate workspace on Windows (this host)
Rust multi-crate workspaces on this host split MSYS (bash) and native Windows path handling. Two failure modes that repeatedly cost sessions:
- Relative member paths are resolved from the member crate's directory, not the workspace root. From
packages/desktop/src-tauri/Cargo.toml, the repo root (NLP_CLI) is three..levels up:../../../crates/core. Writing../../crates/core(two levels) resolves topackages/crates/core— a directory that exists but holds noCargo.toml.cargothen fails with afailed to read <that path>error whose path is correct for the wrong directory; the manifest you meant to edit is untouched. Always trace the relative member path forward from the member crate, and verify withcargo metadata --no-depsbefore you invest incargo check. - Verify the parsed workspace before building. After editing the workspace root
Cargo.toml(membersarray), runcargo metadata --no-deps --manifest-path <root>/Cargo.tomland check that the new package appears inworkspace_members. If it does not, re-apply the patch — the working tree can silently revert to committed content (the desktop member was lost this session, leaving onlycrates/coreandcrates/cli, and everycargo checkfailed on the stale parse). Only runcargo checkafter the parsed workspace is right; a "member not found" error can be a stale parse from an earlier member list, not a code error.
Workspace member addition
- To add a new crate to an existing Rust workspace, append its package name to the
membersarray of the workspace rootCargo.toml. The new crate'sCargo.tomlmust already exist (or be created) at the listed path, and its dependencies on other workspace members use a relativepaththat is resolved from the member crate's directory, not the workspace root (packages/desktop/src-tauri'snlpcli-coredependency is../../../crates/core, three..levels). Then verify withcargo metadata --no-deps --manifest-path <root>/Cargo.tomlthat the new package appears inworkspace_membersbefore runningcargo check.
Overlaps and where to look instead
- tauri-gui-workflow covers a different project (Agentic Workbench / BitForge: FastAPI sidecar + React + Tauri on Windows, telemetry dashboards, sidecar management). Its patterns are not this class's pattern; do not copy its backend architecture wholesale.
- verification-first-development overlaps on the verification bar; combine its verify-all-components bar with this skill's desktop-specific steps.
- windows-python-shell-interop covers the MSYS/Windows boundary; this skill's notes above are the condensed version for desktop GUI work.
references/
- references/desktop-gui-decision-table.md - shell choice, backend wiring choices, and the full 9-screen feature brief template.
- references/windows-desktop-toolchain.md - this host's toolchain facts and the complete dev/native-launch recovery recipes.