════════════════════════════════════════════════════════════════════════ CROSS-PLATFORM CHECKLIST Gnomad Desktop Assistant · docs/CROSS_PLATFORM_CHECKLIST.md ════════════════════════════════════════════════════════════════════════ 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? ------------------------------------------------ [mermaid] 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 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) -------------------------------- • [ ] npm run build passes (TypeScript + Vite) • [ ] cd src-tauri && cargo test passes • [ ] No Mac-only paths in shared React (avoid hardcoding /Users/…, osascript, pbcopy in src/) • [ ] New settings/UI visible in Settings without requiring macOS-only permissions • [ ] Strings use platformInfo for tray/menu labels when user-facing (e.g. “menu bar” vs “system tray”) • [ ] CI green on macOS, Windows, Linux (see .github/workflows/build.yml) ──────────────────────────────────────── 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 • [ ] Menu bar tray icon visible (not template-only broken) • [ ] Traffic-light spacer in panel/pop-out (titlebar-leading-macos) • [ ] Accessibility settings flow if context features changed • [ ] npm run tauri:build:mac produces .app / .dmg Windows • [ ] System tray icon and tooltip • [ ] Ctrl+Shift+Space toggles window • [ ] Panel opens near tray; no duplicate titlebar in windowed • [ ] Active window / clipboard pills populate (PowerShell available) • [ ] Elevated commands show structured elevation_unsupported (use admin terminal / agent_fs for writes) • [ ] npm run tauri:build:win on windows-latest or local VM Linux • [ ] System tray (AppIndicator); Wayland: left-click tray opens menu (shipped) • [ ] Ctrl+Shift+Space toggles window • [ ] Optional: xdotool / wl-paste / xclip for context pills (LINUX_PACKAGES.md) • [ ] pkexec argv-only elevation (injection patterns rejected with structured error) • [ ] npm run tauri:build:linux (deb or AppImage) ──────────────────────────────────────── 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: [markdown] ### 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 • Use getPlatformInfo() / platformInfo in React for labels and conditional sections. • Add Win/Linux rules next to macOS in index.css when layout differs (.platform-windows.mode-windowed, etc.). • Put OS-specific logic in Rust with #[cfg(target_os = "macos")] and keep the invoke API stable for the frontend. • Document gaps in this file or BUILD_PLATFORMS.md. Don’t • Assume the in-app toolbar is visible on Windows/Linux windowed mode. • Use macOS-only shortcuts in user-visible copy (prefer “global shortcut” or list both). • Test only menu-bar panel mode on Mac and ship. • Fork React into App.macos.tsx unless absolutely necessary—prefer flags and small components. ──────────────────────────────────────── 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). ──────────────────────────────────────── RELATED DOCS ------------ • BUILD_PLATFORMS.md — build commands and parity table • QA_CHECKLIST.md — formal release QA with P0/P1 IDs (use before shipping a version) • LINUX_PACKAGES.md — optional Linux dependencies • MACOS_PERMISSIONS.md — Accessibility / automation on macOS • AGENT_CAPABILITIES_PROPOSAL.md — agent architecture ════════════════════════════════════════════════════════════════════════ Built with ❤️ by Gnomad Studio 🦙 https://gnomadstudio.org ════════════════════════════════════════════════════════════════════════