Files
kandev/docs/plans/desktop-native-integration/plan.md
T
2026-08-24 11:09:03 +00:00

129 lines
5.5 KiB
Markdown

---
spec: docs/specs/desktop/requirements/desktop-tauri-app.md
created: 2026-07-15
status: done
---
# Implementation Plan: Desktop Native Integration
## Goal
Add native menus and contextual shortcuts, signed prompt-before-install updates, native
notifications, persistent window state, focus/reopen behavior, and safe external links to the
existing Tauri shell without creating a second product UI or broadening WebView authority.
## Architecture
- Product contract: `docs/specs/desktop/requirements/desktop-tauri-app.md`
- Shell decision: `docs/decisions/0026-tauri-desktop-shell.md`
- Integration boundary: `docs/decisions/0039-native-desktop-integration-boundary.md`
- Rust owns OS and lifecycle behavior; the SPA owns navigation and contextual UI semantics.
- The loopback page gets a narrow typed desktop bridge, not generic Tauri plugin access.
- Desktop update presentation extends the existing `/settings/system/updates` surface. Browser,
service, and mobile behavior remains unchanged.
### Frozen bridge contract
Wave 1 uses a shared versioned adapter contract so the Rust and SPA tasks can proceed independently:
- native events: `close-context`, `open-settings`, `new-task`, and `check-for-updates`;
- SPA commands: `get-update-state`, `check-for-updates`, `install-update`, `show-notification`,
and `open-external`;
- every bridge message is namespaced as desktop protocol `v1` and carries only its task-specific
structured payload;
- unavailable or unsupported bridge operations return typed errors and never fall back to generic
plugin, shell, filesystem, URL, or window authority.
The implementation may choose Tauri-safe literal identifiers, but both sides must expose these
stable adapter names and payload types. A protocol change requires updating this plan before the
parallel Wave 1 tasks diverge.
## Execution Rules
- Tasks in a wave may run in parallel only where shown.
- Tasks touching `apps/desktop/src-tauri/Cargo.toml`, `tauri.conf.json`, capabilities, or
`src/main.rs` are intentionally serialized.
- Every behavioral change starts with a failing focused test where the local test harness supports
it. Config-only release assertions may be added directly to existing release tests.
- Do not begin a later wave until all dependencies are verified and task status is updated.
## Waves
### Wave 1: Command foundations
- [x] [Task 01: Native shell commands and window lifecycle](task-01-native-shell-commands.md)
- [x] [Task 02: SPA contextual command resolver](task-02-spa-contextual-commands.md)
These tasks may run in parallel. Task 01 owns desktop Rust/config files; Task 02 owns web files.
### Wave 2: Update release supply chain
- [x] [Task 03: Signed updater release artifacts](task-03-updater-release-artifacts.md)
Depends on Task 01 so the finalized Tauri target/config baseline is available.
### Wave 3: Updater runtime and existing settings UI
- [x] [Task 04: Desktop updater runtime and settings adapter](task-04-updater-runtime-settings.md)
Depends on Tasks 01-03. This task is the next owner of shared Tauri manifests/configuration.
### Wave 4: Native notification routing
- [x] [Task 05: Native notifications and duplicate suppression](task-05-native-notifications.md)
Depends on Task 04 and owns the next shared Tauri/plugin edit.
### Wave 5: External links
- [x] [Task 06: Scoped native external-link handling](task-06-external-links.md)
Depends on Task 05 and owns the final shared Tauri capability/plugin edit.
### Wave 6: Integrated QA and documentation
- [x] [Task 07: Desktop integration QA and public docs](task-07-integration-qa-docs.md)
Depends on Tasks 01-06.
## Cross-Cutting Acceptance
- `Cmd/Ctrl+W` never quits or closes the main window and closes only one eligible context.
- macOS red close and Quit cleanly stop the backend and exit.
- Zoom, Settings, New Task, Help, Check for Updates, focus/reopen, and window restore work through
native menus/lifecycle.
- Updates require valid Tauri signatures and explicit install/restart confirmation; Linux
auto-update is AppImage-only.
- Apple notarization and Windows code signing add publisher identity when configured but do not
block a complete Tauri-signed updater feed when absent; release warnings remain mandatory.
- Waiting-input and session-failure events yield one native desktop notification; generic focus
and activation events never infer a task route because Tauri exposes no desktop click payload.
- Browser/service/mobile settings and notification paths retain their current behavior.
- The loopback WebView has no shell/filesystem capability and unsupported external schemes fail
closed.
## Final Verification
Run formatting first, then focused and broad verification:
```bash
cd apps && rtk pnpm --filter @kandev/desktop build
cd apps/desktop/src-tauri && rtk cargo test --features desktop-runtime
cd apps/web && rtk pnpm run typecheck
cd apps && rtk pnpm --filter @kandev/web test
rtk make -C apps/backend fmt
rtk make -C apps/backend test
rtk make -C apps/backend lint
cd apps && rtk pnpm --filter @kandev/web lint
cd apps && rtk pnpm --filter @kandev/desktop e2e
```
Release workflow validation must additionally run the updater manifest/signature tests and
`scripts/release/verify-desktop-assets.sh` against representative artifacts for every target.
## Approval Checkpoint
The product decisions and implementation plan were approved on 2026-07-15. Any later change to
close priority, quit semantics, update consent, Linux update format, notification event scope, or
bridge permissions requires updating the spec/ADR first.