future-os / desktop

# Desktop Development Guide (`desktop/`)

FutureOS desktop app: Tauri + React + TypeScript, frontend `src/`, Tauri backend `src-tauri/` (Rust), connects to the repo-root agent via gRPC. For overall monorepo architecture/build, see **repo-root `CLAUDE.md`**; this file covers `desktop/` only.

## Document Map (read relevant sections on demand — don't pull whole files into context)

> Development docs live under `docs/internals/desktop/` (repo-root-relative paths below; formerly `desktop/DEV_MD/`).

| Document | Content | When to Read / Modify |
|---|---|---|
| `docs/internals/desktop/PRODUCT.md` (~35KB) | Product positioning, module boundaries, workspace object semantics, desktop experience | **Read** when changing product behavior / adding features / confirming domain semantics; **modify** only when product decisions change |
| `docs/internals/desktop/ER.md` (~42KB) | Data objects & relationships, table inventory, schema design decisions | **Read** when changing store / data flow; **modify** and keep in sync when schema changes |
| `docs/internals/desktop/COLOR.md` (~5KB) | Color semantic tokens + quick usage reference | **Read** when picking colors / changing styles; **modify** only when adding/changing tokens |
| `docs/internals/desktop/SANDBOX/COMMON.md` | Shared rules, tiers, approval UI/protocol, decisions and Codex references | **Read** for approval semantics; distinguish implemented behavior, accepted limitations and future plans |
| `docs/internals/desktop/SANDBOX/MACOS.md` / `LINUX.md` / `WINDOWS.md` | Platform implementation, differences, diagnostics, progress, validation procedures and evidence | **Read** the relevant platform; historical PASS is not validation of a new candidate; preserve the accepted Windows unelevated and Linux snapshot boundaries |
| `docs/internals/desktop/CONTEXT_COMPACTION.md` / `docs/internals/desktop/CONNECTION.md` | Compaction plans / remote product rationale, architecture, connection contract and implementation plan | **Read** for the corresponding feature; verify plan-vs-current against code |
| `docs/internals/desktop/embedded-terminal.md` | Embedded terminal: architecture, wire protocol, security model, lifecycle, platform status | **Read** before touching `src-tauri/src/terminal/` or `src/features/terminal/`; **modify** when the protocol or its boundaries change |

> `docs/internals/desktop/PRODUCT.md` / `docs/internals/desktop/ER.md` are large: use `Read` with `offset/limit` to read **specific sections** from the chapter index below — don't load the whole file.

### Chapter Quick Reference
- **PRODUCT.md**: §1 Positioning · §2 Module Boundaries · §3 Product Principles · §4 Work Objects (4.1 Workspace / 4.2 Chat / 4.3 Message / 4.4 Run / 4.5 Tool / 4.6 Approval / 4.7 Review / 4.8 Artifact / 4.9 Research / 4.10 Data / 4.11 Skill / 4.12 Attachment) · §5 Desktop Experience (5.1 Three-panel / 5.2 Left Nav / 5.3 Chat Area / 5.4 Right Context / 5.5 Colors / **5.6 Settings: Provider/Model/Login**) · §6 Agent Workflow · §9 Roadmap
- **ER.md**: §2 Relationship Overview · §3 Naming Conventions · §4 Objects (4.1 Workspace … 4.8 Approval Request / 4.9 Review Changeset / 4.10 Review File Change (incl. **Shadow Review extension**: `review_snapshots` table + changeset/file_change extension columns) … 4.20 Object Reference) · §5 V1 Table Inventory · §6 Key Design Decisions (**6.8 Shadow Repo "Previous Change Set"** / **6.9 Provider/Model/Login Config**)

> **Shadow Review** (run-level "previous change set"): product semantics in docs/internals/desktop/PRODUCT.md §4.7, data model in docs/internals/desktop/ER.md §4.10, design tradeoffs in docs/internals/desktop/ER.md §6.8. Read all three before modifying shadow repo / snapshot / changeset code (`src-tauri/src/shadow_review/`, `store/review_snapshots.rs`).

> **Provider / Model / FutureGene Login**: product behavior in docs/internals/desktop/PRODUCT.md §5.6, storage & login implementation in docs/internals/desktop/ER.md §6.9, custom-provider field validation in `agent_providers/validate.rs` (frontend mirror: `CustomProviderDialog.tsx` + settings.json strings `idPattern`/`idLength`/`baseUrlInvalid`). Read these before modifying `agent_providers/` (Providers view + custom-provider upsert/delete) / `future_platform.rs` (platform / model-API URL resolution, shared by login/skills/debug) / `auth_store.rs` / `future_login.rs` / `commands/login.rs`.

## Code Structure (`src/`)

- `components/layout/` — `AppShell` (layout orchestration) + `ContextPanel` + `ActivityRail` (left nav) + dialog shells (`AppShellDialogs` / `WorkspaceDialogs` / `LeftPanelTitlebarToggle`); `hooks/` contains AppShell domain hooks: `useThreadStore` / `useAgentConnection` / `useApprovals` / `useAppSettings` / `useModelSelection` / `useNewConversation` (new-conversation create flow: pending prompt + `startNewConversation`) / `useThreadDialogs` / `useUnreadThreads` / `useWorkspaceDialogs` / `useDropUpMenu`
- `components/ui/` — Generic presentational components (`Badge` / `DiffView` / `CopyablePre` / `TextInput` / `Select` / `Button` / `Overlay` / `ToastHost` …), no business logic
- `features/{agent,review,runs,artifacts,filetree,skills,remote,terminal,settings,markdown,filepreview}/` — Domain-specific business components (Skills and Remote have user-facing navigation; Research/Data remain hidden — verify ActivityRail.tsx and PRODUCT.md §5.2). Large features split their logic out of the view: `agent/` keeps the send flow in a non-React `sendPipeline.ts` driven by hooks `useSendMessage` / `useRunReattach` / `useThreadMessages` (`useAgentThreadState` is now just the orchestrator), approval-payload parsing/validation in `approvalPayload.ts`, and the new-conversation workspace form in `useWorkspaceForm.ts` + `NewConversationWorkspaceForm.tsx`; `review/` splits into `GitChangesReview` / `LastRunReview`; `markdown/` renders through `renderers/` (`CodeBlock` / `SafeLink` (URL sanitization) / `FutureEmbed` / …); `filepreview/` renders the fullscreen local-file preview overlay — image + markdown + JSON + code / config text (`previewKind.ts`), every other file (PDFs included) opens with the OS default handler
- `integrations/` — Boundary with the Tauri backend: `tauri/invoke.ts` (sole typed invoke entry point) + `tauri/useBuildInfo.ts`, `agent/`, `skills/` (`skillsClient.ts`), `storage/` (`threadStore.ts` is the barrel, domain modules in sibling files; `types.ts` + `typeGuards.ts` hold the stored-payload shapes and their runtime guards)
- `i18n/` — `en`/`zh` locale bundles + init (language switch, PRODUCT.md §5.6). `lib/` stays i18n-free: locale-dependent helpers (`date.formatTime`) take a `locale` arg passed by callers, never import `i18n`
- `lib/` — Dependency-free utilities: `usePolling` / `useAsyncResource` / `futureEvents` (typed event bus) / `cn` / `clipboard` / `date` (`formatTime` takes an optional `locale`) / `format` (`formatBytes`) / `errors` (`errorMessage`) / `platform` / `objects` / `useDismissableLayer` / `useFloatingScrollbar` / `useIsFullscreen` / `windowDrag`

## GUI Development Principles (Long-term Memory)

1. **Colors**: Use only semantic tokens from `docs/internals/desktop/COLOR.md`; no bare Tailwind colors (`blue-300`…). Status badges use `<Badge tone>`; categorical colors (event categories / error subtypes) are intentional exceptions.
2. **Tauri Invoke**: All `invoke` calls go through `integrations/tauri/invoke.ts`'s `invokeCommand` — never call `invoke` directly. Command params: structured input via `{ input }`, single scalars via named keys. (Other `@tauri-apps/api` capabilities — event `listen`, dialog, `convertFileSrc`, window/webview — are not wrapped by `invoke.ts`; import them directly as needed.)
3. **Cross-component Events**: Use `lib/futureEvents.ts` typed `emitFutureEvent` / `onFutureEvent`; never use raw `window` CustomEvent.
4. **Async / Polling**: Cancellation-safe loading uses `lib/useAsyncResource`, polling uses `lib/usePolling` (don't hand-roll `cancelled` flag effects or `setInterval`). When polling connection/status changes, **don't flash `checking` on every tick** — retry silently, only update state when you have a result.
5. **AppShell State**: Split by domain into hooks under `components/layout/hooks/`; AppShell only does layout orchestration. Hooks expose state via named destructuring to AppShell to minimize the change surface.
6. **Data**: Schema changes must sync to `docs/internals/desktop/ER.md`; frontend store changes must account for corresponding backend `src-tauri/src/store/` (split by domain).
7. **Released database migrations**: The GUI SQLite database is now in production. `SCHEMA` defines a fresh install only; changing it alone is never sufficient for an existing user database. For every database-structure change (tables, columns, constraints, indexes, data shape, or destructive cleanup), add or update a versioned migration and test both upgrade and fresh-install paths. Use the latest reachable release tag as the boundary (`git describe --tags --abbrev=0`): migrations already present in that tag are immutable; only an unreleased migration may be amended. For one target release tag, consolidate related schema work into **one new migration** whenever practical; create more only when a documented ordering/operational constraint requires it. Each migration must be ordered, transactional where SQLite permits, idempotent or safely resumable, and covered by a fixture/database representing the previous release tag.
8. **Backend Errors**: Tauri commands return `Result<_, AppError>` (`thiserror`), **serialized as strings**; frontend handles them as strings. Backend loose colors have been tokenized / AppError'd — don't regress to `.map_err(|e| e.to_string())`.
9. **Approval (v2 file-based + three-tier)**: Approval targets **file path access**, except manual shell and macOS/Linux whole-command escalation. Rules live in `${WS}/.future/approval_rule.json` and `~/.future/approval_rule.json`; Agent reads them, GUI writes through trusted `approval_rules.rs` + `commands/approvals.rs`. Tiers are `manual` / `sandbox` / `off`, sent via `set_sandbox_policy`. OS backends are macOS Seatbelt, Linux system Bubblewrap, and Windows unelevated write protection; availability follows `useSandboxAvailability`, not equivalent guarantees across platforms. `approval_requests` retains `action_payload` / `sandbox_boundary` / `save_suggestion`. Semantics and evidence: `docs/internals/desktop/SANDBOX/COMMON.md`, the platform document, and `docs/internals/desktop/ER.md §4.8`. Legacy SQLite rule/config tables were deleted on 2026-07-05.
10. **Config-file IO**: The JSON config files the GUI owns under `~/.future/` (`models.json`, `auth.json`, `approval_rule.json`) go through `src-tauri/src/config_io.rs` — `read_json_object` (strict: corrupt/non-object is an **error**, never a silent reset that would clobber user-authored config), `write_json_atomic` (unique temp + `rename`, `owner_only` for `auth.json`), and `with_config_lock` (per-path lock serializing read-modify-write). Don't hand-roll `fs::read`/`fs::write` for these; a *cache* file may use `read_json_lenient`.
11. **Run status writes**: A run's status is only ever written by the compare-and-set `store::update_run_status_if_active` (and `fail_run_if_active`) — the unguarded writer was removed so a late completion/failure can't clobber a concurrent abort's terminal state. Startup convergence no longer cancels orphaned runs outright: non-terminal runs are reconciled against the Agent's actual state (`reconcile_interrupted_runs` + `reanimate_run` + the active-run watchdog), and pending approvals via `reconcile_pending_approvals` — the Agent may have survived a GUI crash. Don't add an unguarded status `UPDATE`.
12. **Store row mapping**: Each record's `*_COLUMNS` string and `*_from_row` are generated together from one field list by `sql_record!` (`store/record_macro.rs`) so they can't drift; declare fields once, in `SELECT` order, with names matching the SQL columns.
13. **No emoji**: Never use emoji anywhere in the product — UI labels, icons, status indicators, code, comments, commit messages, or logs. Use a `lucide-react` icon (SVG) for any glyph; text labels stay plain. (Emoji render inconsistently across platforms/fonts and don't theme.) This is a hard rule, not a style preference.
14. **Cross-platform (incl. Windows)**: Code must work on Windows as well as macOS/Linux. Don't assume POSIX: paths can use `\` separators and `.exe` suffixes and are case-insensitive; the agent's shell tool runs via PowerShell on Windows — pwsh 7 when on PATH, else Windows PowerShell 5.1 (`bash -c` elsewhere; see agent `sandbox::shell_invocation`); never hard-code `/`, `~`, or shell-specific syntax when a platform-neutral form exists. When parsing command strings or paths, handle both separators and casing.
15. **Tool vs run status**: In tool-facing UI (e.g. the Runs panel) show the *tool's* own status (`running`/`completed`/`failed`), never the enclosing run's status or error. A tool still `running` after its run has ended was interrupted — treat it as `failed` (a user abort is indistinguishable from a real failure). Run-level errors belong only in run-level UI (the inspector banner), not on individual tool rows.
16. **Embedded terminal**: The terminal is a PTY registry in `src-tauri/src/terminal/` served to the webview over a **loopback-only HTTP/WebSocket listener** (opencode's transport model), not over Tauri IPC. Output is a byte stream with an absolute cursor: a view resumes by asking for the bytes after the cursor it applied, so reopening the panel, reloading the webview or remounting a tab never re-renders history. Keep it that way — the socket is also what makes the feature verifiable without a GUI (`cargo test terminal::server` drives a real shell end to end). The webview's `authorization` header means every control request is CORS-preflighted; the listener answers the preflight and refuses foreign origins. Terminals are conversation-scoped: deleting a conversation or workspace closes its shells, and a shell must never outlive its context. Never route terminal bytes through the agent, RPC, remote control, logs or SQLite. Details: `docs/internals/desktop/embedded-terminal.md`.
17. **i18n (user-facing text + dates/times)**: Every string a user reads goes through `react-i18next` `t(...)` with a key in **both** `i18n/locales/en` and `i18n/locales/zh` — never hard-code a literal (Chinese or English) in JSX/components. Dates and times are formatted with the caller's locale via `lib/date.formatTime(..., locale)` — never build a date string with a hard-coded format or a locale-less `toLocaleString()`; `lib/` stays i18n-free, so pass the locale in rather than importing `i18n` there. Exempt: model-facing prompt strings (e.g. `buildInlineAttachmentContext`) are sent to the LLM, not shown in the UI, so they're not localized.

## Verification (Run After Every Change)

```bash
cd desktop && npx tsc --noEmit && npx eslint "src/**/*.{ts,tsx}" && npx vitest run
# If Tauri backend is affected, also run:
cd desktop/src-tauri && cargo fmt --check && cargo clippy && cargo test
```

GPG signing fails in non-interactive terminals; commit with `git commit --no-gpg-sign`. Visual changes (colors, etc.) must be confirmed in a live `make run-desktop`.