Cross-platform checklist

Also available: Markdown · Plain text

Cross-platform checklist

Use this whenever you add a feature, change UI, or tweak behavior. Gnomad ships one React app (src/) on macOS, Windows, and Linux—but shell chrome, OS integrations, and some menus differ by design.

Goal: Shared UI works everywhere; platform-specific behavior is explicit, documented, and tested—not accidental Mac-only behavior.

Quick decision: does my change need per-OS work?

flowchart TD
  Start[Change landed] --> Q1{Only React/CSS in src/?}
  Q1 -->|Yes| Q2{Uses platformInfo or OS-specific CSS?}
  Q1 -->|No| Q3{Rust in src-tauri?}
  Q2 -->|No| Low[Usually OK on all OSes — run smoke checklist]
  Q2 -->|Yes| Med[Verify each branch + Win/Linux windowed]
  Q3 -->|Yes| High[Add cfg blocks + test on target OS or CI]
  Q3 -->|shell/context/window| High
If you changed… Typical scope Action
Chat, settings, knowledge, agent cards, composer Shared Smoke all OSes (panel + windowed on Win/Linux)
index.css layout / spacing Shared Check narrow width + windowed (toolbar may be hidden)
Title bar, traffic lights, toolbar, fullscreen Per-OS Update TitleBarLeading, AppToolbar, platform-*.css
Tray, panel position, global shortcut Per-OS window_manager.rs, platform.rs, lib.rs setup
Shell, elevation, credentials, context Per-OS backend privilege.rs, context.rs, keychain — UI can stay shared
New Tauri command Shared invoke Register in lib.rs; gate risky OS APIs with #[cfg]

Code map

Concern Primary files
Platform flags & labels src-tauri/src/platform.rs → src/lib/platform.ts
Frontend branching src/App.tsx, hooks (useOsContext, …), platformInfo, data-platform on <html>
Title bar / toolbar src/components/TitleBarLeading.tsx, src/components/AppToolbar.tsx
Win/Linux panel CSS src/index.css (.platform-windows, .platform-linux)
Window modes & tray src-tauri/src/window_manager.rs, src-tauri/src/menu_shell.rs
OS context & clipboard src-tauri/src/context.rs
Safety / elevation src-tauri/src/privilege.rs

Before you merge (all platforms)

UI & settings (shared React)

Test on each OS you have access to; at minimum run CI and spot-check one non-Mac OS before release.

All window modes

Check macOS Windows Linux
Panel (tray drop-down) opens, closes, global shortcut ☐ ☐ ☐
Pop out / floating window usable ☐ ☐ ☐
Windowed — content not clipped; settings reachable ☐ ☐ ☐
Fullscreen enter/exit (if touched) ☐ ☐ ☐
Close hides to tray (not quit) ☐ ☐ ☐
Quit from tray menu exits app ☐ ☐ ☐

Chat & composer

Check macOS Windows Linux
Send message (cloud + local if applicable) ☐ ☐ ☐
Attachments pick + show chips ☐ ☐ ☐
Shell command cards show output ☐ ☐ ☐
Sudo Gate appears for risky command; approve/deny works ☐ ☐ ☐
Failed shell/elevation shows Agent error banner (code, hint, expandable detail) ☐ ☐ ☐
Stop cancels in-flight work ☐ ☐ ☐

Settings panels (new work: tick your feature)

Check macOS Windows Linux
API keys — save/status (no secret in UI) ☐ ☐ ☐
Agent access — workspace, trust mode, planner ☐ ☐ ☐
Model / provider / Ollama URL ☐ ☐ ☐
Accessibility block only on macOS (hidden elsewhere) ☐ N/A N/A
Knowledge import (file dialog) ☐ ☐ ☐

Windowed mode on Windows/Linux: in-app toolbar is often hidden; use View menu (OS menu bar) for mode switches—confirm your feature isn’t toolbar-only.

Platform-specific expectations

macOS

Windows

Linux

Agent & shell features

Check macOS Windows Linux
shell_run / PTY executes simple command (command -v brew or echo hi) ☐ ☐ ☐
cd updates cwd in follow-up command ☐ ☐ ☐
Path Gate for file outside workspace (Standard mode) ☐ ☐ ☐
Path Gate mints signed token on approve (not boolean bypass) ☐ ☐ ☐
YOLO mode reduces path prompts (if enabled) ☐ ☐ ☐
Command planner (Ollama) converts prose → CLI when enabled ☐ ☐ ☐
Audit log written under app data (agent-audit.jsonl) ☐ ☐ ☐
Injection-like elevation ($(, ;, pipes) rejected with safety_blocked payload ☐ ☐ ☐

When you add a new feature (template)

Copy into your PR description or task notes:

### Cross-platform: [feature name]

**Layer:** ☐ Shared React  ☐ CSS  ☐ Rust (all OS)  ☐ Rust `#[cfg(...)]` per OS

**UI entry points:** ☐ Panel  ☐ Pop-out  ☐ Windowed  ☐ Settings  ☐ Tray menu  ☐ OS app menu

**Backend:** ☐ Tauri command  ☐ Shell  ☐ FS  ☐ Keychain/credentials  ☐ OS context

**Tested:**
- [ ] macOS — panel + windowed
- [ ] Windows — panel + windowed (or CI artifact)
- [ ] Linux — panel + windowed (or CI artifact)

**Platform notes:** _e.g. “Elevation on Windows still manual”; “Linux needs wl-paste”_

Implementing platform-aware UI (do / don’t)

Do

Don’t

CI & release

On push to main / master:

  1. GitHub Actions builds macOS, Windows, Linux (build.yml).
  2. Download artifacts and smoke-test installers when changing shell/window/tray code.
  3. Before tagging a release: run the Before you merge section on at least one build per OS (or delegate to CI + manual spot-check).