Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript

docs: define the desktop shell contract and add Tauri packages

Alan Buscaglia2f94f1197043
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
new file mode 100644
index 0000000..33d02ef
--- /dev/null
+++ b/apps/desktop/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "@gentle-dot/desktop",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "tauri": "tauri",
+ "dev": "tauri dev",
+ "build": "tauri build"
+ },
+ "devDependencies": {
+ "@tauri-apps/cli": "^2.12.1"
+ }
+}
diff --git a/docs/design.md b/docs/design.md
index 275f2df..9642744 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -171,7 +171,46 @@ Every daemon message carries `seq` (monotonic per connection) so the UI can dete
- WebSocket upgrades check `Origin` against an allowlist (`http://127.0.0.1:4317`, `tauri://localhost`).
- The VPS guide requires HTTPS, a reverse proxy with authentication, and a dedicated Docker container with no access to personal machines.
-## 9. Configuration
+## 9. Desktop shell contract (Tauri 2 <-> UI)
+
+The desktop app bundles the built UI (`packages/ui/dist/app`) as its frontend, so its origin is `tauri://localhost`, which the daemon allows. It has no dock icon (macOS accessory activation policy).
+
+### Windows
+
+| Label | Size | URL | Properties |
+|---|---|---|---|
+| `dot` | 56 × 56 | `index.html?surface=dot` | transparent, no decorations, always on top, not resizable, skip taskbar, visible on all workspaces, shadow off |
+| `panel` | 420 × 640 | `index.html?surface=panel` | transparent with macOS vibrancy (`HudWindow`), no decorations, always on top, hidden at start, skip taskbar |
+
+When the panel opens, it is placed next to the Dot on the side with more room, and it stays inside the monitor.
+
+### Rust commands the UI calls (`@tauri-apps/api/core` `invoke`)
+
+| Command | Arguments | Result |
+|---|---|---|
+| `connection_info` | — | `{ "url": "ws://127.0.0.1:<port>/ws", "token": "…", "webUrl": "http://127.0.0.1:<port>/#token=…" }`, read from `~/.gentle-dot/config.json` and `~/.gentle-dot/token` |
+| `toggle_panel` | — | shows and focuses the panel next to the Dot, or hides it |
+| `hide_panel` | — | hides the panel |
+| `set_dot_state` | `{ "state": AgentState }` | updates the tray icon tooltip and title marker |
+
+The Dot drags with `getCurrentWindow().startDragging()` (permission `core:window:allow-start-dragging`). After a drag ends (no move events for 300 ms), Rust snaps the Dot to the nearest monitor edge with a 12 px margin and saves the position in `~/.gentle-dot/desktop.json`; the next launch restores it, or defaults to the right edge, vertically centered.
+
+### Events Rust emits to the UI (`@tauri-apps/api/event` `listen`)
+
+| Event | Payload | Meaning |
+|---|---|---|
+| `dot://new-conversation` | — | the tray item "New conversation" was chosen; the panel starts a new conversation and opens |
+| `dot://panel-shown` | — | the panel became visible; the UI focuses the composer |
+
+### Menu bar and shortcut
+
+Tray menu: Open (`⌥ Space`), New conversation, Open in browser, Restart assistant, Launch at login (check item), Quit. The global shortcut `Alt+Space` (configurable as `shortcut` in `config.json`) toggles the panel. Launch at login uses `tauri-plugin-autostart`; Open in browser uses `tauri-plugin-opener` with `webUrl`.
+
+### Daemon lifecycle
+
+On launch, the app checks `GET /health`. If the daemon does not answer, the app spawns it: `<node> <repo>/packages/daemon/src/cli.ts`, with the `PATH` captured at build time (apps launched from Finder get a minimal `PATH`, and the daemon needs `gentle-shell`). `build.rs` records the absolute `node` path, the daemon script path, and `PATH`; `GENTLE_DOT_NODE` and `GENTLE_DOT_DAEMON_SCRIPT` override them at runtime. A daemon spawned by the app is stopped on Quit. Restart assistant restarts a spawned daemon, and reports through a dialog when the daemon was started outside the app. The UI connects only after `/health` answers.
+
+## 10. Configuration
`~/.gentle-dot/config.json`, all optional:
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 8c5b9a3..5a6edaa 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -9,6 +9,7 @@
},
"dependencies": {
"@gentle-dot/protocol": "workspace:*",
+ "@tauri-apps/api": "^2.12.1",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"react-markdown": "^10.1.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4b2ea62..2137d01 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -24,6 +24,12 @@ importers:
specifier: ^5.0.3
+ apps/desktop:
+ devDependencies:
+ '@tauri-apps/cli':
+ specifier: ^2.12.1
+ version: 2.12.1
+
packages/daemon:
dependencies:
'@gentle-dot/protocol':
@@ -44,6 +50,9 @@ importers:
'@gentle-dot/protocol':
specifier: workspace:*
version: link:../protocol
+ '@tauri-apps/api':
+ specifier: ^2.12.1
+ version: 2.12.1
react:
specifier: ^19.3.0
version: 19.3.0
@@ -330,6 +339,85 @@ packages:
'@rolldown/[email protected]':
resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-DeyFHa3wynpyoqTDikDEDGTJIq4LQ5USfolQGRmGIWT6JMADyxZBTDa5cAdT3tDg73rUXufPaCwN7aXBos4OnQ==}
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-8bMnbpJ2jKO/ufrOPL65EMHC3ptw7fzeraoQkwibyfGLqIl+UCWsC0152kmNbW6r9NvVQduXqAZF5mH1QgTWhw==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-G+2qte8GNqNlEZ9ftd21rbu/APVkl3r/nzNDI7LVxEoqJWVNe9GbEgQUMH1r4PHT20Z2UxR3KjCkltIb0e/Wjg==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [darwin]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-5b3n4DaTW+A1Zntnh4Yn44VyLrlPEpB8kMOBRfWkzNnzolBk+AYhKIfKjCLmoC8Mob3ETodxAEOMkE2YPKEWzQ==}
+ engines: {node: '>= 10'}
+ cpu: [arm]
+ os: [linux]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-APArHhDu+8pXSCkCQmvaz1nD3d8WTmlCoSS/oG475TJ6AATBvyQOAmf5qELgsQ4s2+8MOsop0Zd699RKELF1Cw==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [glibc]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-JaCxcLoV0oGtllVkLr4UAHWG/wTfkEunnUqnsEsGYOp0VRxnUwHg63wFBD0jU2ul5eFfSLIDS4RF2gfzsSo5Jg==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [musl]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-K5+VXM7+SGVDwZleA2+lMgvbTVuA5e1tkiVEawu1Yxj26ZyEfO8h8xTC1rBdRX2xgJDSwCk6vPUBCS6i+Z5slQ==}
+ engines: {node: '>= 10'}
+ cpu: [riscv64]
+ os: [linux]
+ libc: [glibc]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-Z1QGPr49HJZMktu+Spu6Q1b/f9ANadXvqZZZt2645ua1x1ev6prOgp85eiGv2jRzohFEMLo6aJyaLjLUX5KIvA==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [linux]
+ libc: [glibc]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-nHuEhRPOMSJ/8RRhtMRxB9B9lVr7xxpe4DapBz8x1GIau3vdzjHHJ1hAfmw+PyayPLZ6XoaVIHPgI17rX6ii8w==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [linux]
+ libc: [musl]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-I0oPk2uGh86R8dAs2X5OxSP+/GqSc8jh1Px3l8EqrocSNivsRHDTh2k3PVOqdv163dlV6PIVvmhZAbH/lPfZrA==}
+ engines: {node: '>= 10'}
+ cpu: [arm64]
+ os: [win32]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-baNZRBfepAJ5qNFRMwzgBk94xQmkcmTZrNDjZjnzrq2vAaTC3NAhallb/zo3hyoCGQlMS13sdovktrg46NZz6Q==}
+ engines: {node: '>= 10'}
+ cpu: [ia32]
+ os: [win32]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-dIFaKslrzcbesb+bBh+E1R9km241pHyj32w6D9FPtvQeYpRUFbiCLEa/2S+S0UnIytfxepp4P+X8IerGqnXeYg==}
+ engines: {node: '>= 10'}
+ cpu: [x64]
+ os: [win32]
+
+ '@tauri-apps/[email protected]':
+ resolution: {integrity: sha512-kEDEiGzG+yAc5FeLxtXpES/VN+F2C8H0r4gDVtfRLKxT9np9101d9REG/Kgo2lr0hKi0IpDsODiHnU3+naOmLg==}
+ engines: {node: '>= 10'}
+ hasBin: true
+
'@testing-library/[email protected]':
resolution: {integrity: sha512-yzr2S9HyAIdhz2/6qHgbs665Q7PKVcDF05vsOlHPxG1mo36gKVesdYVeDLnXgfjJ03CrKRk08knc6+E/9m8v2Q==}
engines: {node: '>=18'}
@@ -1452,6 +1540,55 @@ snapshots:
'@rolldown/[email protected]': {}
+ '@tauri-apps/[email protected]': {}
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optional: true
+
+ '@tauri-apps/[email protected]':
+ optionalDependencies:
+ '@tauri-apps/cli-darwin-arm64': 2.12.1
+ '@tauri-apps/cli-darwin-x64': 2.12.1
+ '@tauri-apps/cli-linux-arm-gnueabihf': 2.12.1
+ '@tauri-apps/cli-linux-arm64-gnu': 2.12.1
+ '@tauri-apps/cli-linux-arm64-musl': 2.12.1
+ '@tauri-apps/cli-linux-riscv64-gnu': 2.12.1
+ '@tauri-apps/cli-linux-x64-gnu': 2.12.1
+ '@tauri-apps/cli-linux-x64-musl': 2.12.1
+ '@tauri-apps/cli-win32-arm64-msvc': 2.12.1
+ '@tauri-apps/cli-win32-ia32-msvc': 2.12.1
+ '@tauri-apps/cli-win32-x64-msvc': 2.12.1
+
'@testing-library/[email protected]':
dependencies:
'@babel/code-frame': 7.29.7
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 924b55f..6f00273 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,2 +1,3 @@
packages:
- packages/*
+ - apps/*