pixelweaver 0.1.0

package/todo/.obsolete/tauri-desktop-bundle.md

@@ -0,0 +1,424 @@
+# Tauri Desktop Bundle: Production-Ready Self-Contained App
+
+## Current State
+
+The Tauri 2 wrapper exists at `src-tauri/` and consists of:
+
+- **`src/lib.rs`** (~179 lines): A sidecar manager that spawns the Python FastAPI server via `uv run pixelweaver serve`, polls `GET /health` over raw TCP every 500ms (10s timeout), and kills the child process on app exit. Falls back to "offline mode" if the server cannot be started, and reuses an existing server if one is already running on port 7779.
+- **`tauri.conf.json`**: Minimal config -- product name, window size (1280x800), icons, CSP disabled, no resource declarations, no updater.
+- **`Cargo.toml`**: Tauri 2.10.3 with `tauri-plugin-log` (debug only) and `tauri-plugin-shell`.
+- **`capabilities/default.json`**: Core defaults plus `shell:allow-spawn` and `shell:allow-execute`.
+- **Server (`server/pyproject.toml`)**: Python >=3.13, FastAPI + uvicorn + websockets + Pillow + MCP. Entry point: `pixelweaver.cli:main`. Build backend: `uv_build`. CORS already allows `tauri://localhost` and `https://tauri.localhost` origins.
+
+**What is missing:**
+
+| Gap | Impact |
+|-----|--------|
+| Requires `uv` on user's PATH | Non-developers cannot run the app |
+| Requires Python (via uv) to already be available or downloadable | First launch fails without network awareness |
+| `spawn_server()` locates `server/` via cwd heuristics | Breaks in production bundle (cwd is unpredictable) |
+| No bootstrap / first-launch flow | User sees a blank window or error |
+| No error handling UX | Failures are silent (logged to stderr) |
+| No crash recovery | Server crash = dead app until manual restart |
+| No restart IPC command | No way to restart the server without restarting the entire app |
+| No auto-updater | Users must manually download new versions |
+| No build pipeline for bundling resources | Cannot produce distributable artifacts |
+| Never been tested as a production build | Unknown issues lurk |
+
+## Goal
+
+A self-contained desktop application that artists and designers can download, double-click, and use with zero prerequisites. No terminal. No `uv`. No Python knowledge. First-time setup happens automatically with a visible progress screen.
+
+## Architecture: Bundled uv Approach
+
+### What Ships in the Bundle
+
+The Tauri resource system (`bundle.resources` in `tauri.conf.json`) copies specified files into the app bundle at build time. Tauri's `resource_dir()` API locates them at runtime.
+
+| Bundle path | Contents | Size |
+|-------------|----------|------|
+| `resources/uv` (or `resources/uv.exe` on Windows) | Platform-specific uv binary | ~15 MB |
+| `resources/server/pyproject.toml` | Dependency declarations + entry point | <1 KB |
+| `resources/server/uv.lock` | Locked dependency versions | ~50 KB |
+| `resources/server/src/pixelweaver/` | Python source code | ~100 KB |
+
+### Venv Lives Outside the Bundle
+
+The bundle is read-only (especially on macOS where `.app` contents are code-signed and immutable). The Python virtual environment must live in user-writable space.
+
+| Item | Location |
+|------|----------|
+| Virtual environment | `<app_data_dir>/python/.venv/` |
+| Copied project files | `<app_data_dir>/python/pyproject.toml`, `uv.lock`, `src/` |
+| Lock hash (for update detection) | `<app_data_dir>/python/uv.lock` (compared against bundled copy) |
+
+`app_data_dir()` resolves to platform-appropriate paths:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/com.pixelweaver.app/python/` |
+| Linux | `~/.local/share/com.pixelweaver.app/python/` |
+| Windows | `C:\Users\<user>\AppData\Roaming\com.pixelweaver.app\python\` |
+
+### uv Binary Per Platform
+
+A build script downloads the correct binary from uv's GitHub releases before `tauri build`.
+
+| Platform | Binary name | Archive |
+|----------|------------|---------|
+| macOS arm64 | `uv-aarch64-apple-darwin` | `.tar.gz` |
+| macOS x86_64 | `uv-x86_64-apple-darwin` | `.tar.gz` |
+| Linux x86_64 | `uv-x86_64-unknown-linux-gnu` | `.tar.gz` |
+| Windows x86_64 | `uv-x86_64-pc-windows-msvc.exe` | `.zip` |
+
+### Python Caching
+
+uv caches Python toolchains globally at `~/.local/share/uv/python/` (macOS/Linux) or `%LOCALAPPDATA%\uv\python\` (Windows). If the user has other uv-managed projects, the Python 3.13 interpreter may already be cached, making first-launch faster.
+
+---
+
+## Phase 1: Bootstrap Flow (First Launch)
+
+**Effort: Medium** -- Rust bootstrap module + frontend setup screen component.
+
+### Step-by-Step Flow
+
+1. User opens the app (double-click).
+2. Rust checks: does `<app_data_dir>/python/.venv/bin/python` (or `.venv/Scripts/python.exe` on Windows) exist?
+3. **No** -- emit `bootstrap:start` event to the webview via Tauri's event system.
+4. WebView renders a setup screen with progress text and a spinner.
+5. Rust copies `pyproject.toml` + `uv.lock` + `src/` from `resource_dir()` to `<app_data_dir>/python/`.
+6. Rust runs:
+   ```
+   <resource_dir>/uv sync --frozen --directory <app_data_dir>/python/
+   ```
+   - `--frozen` prevents lockfile modification -- it installs exactly what is locked.
+   - uv auto-downloads Python 3.13 (version from `requires-python` in pyproject.toml) to its global cache if not already present.
+   - uv creates `.venv/` and installs all dependencies.
+   - Duration: 10-15 seconds depending on network speed and whether Python is cached.
+7. Rust captures stdout/stderr from the `uv sync` process and emits `bootstrap:progress` events with human-readable messages.
+8. WebView displays progressive status: "Downloading Python...", "Installing dependencies...", "Almost ready..."
+9. `uv sync` exits with code 0.
+10. Rust spawns the server:
+    ```
+    <resource_dir>/uv run --directory <app_data_dir>/python/ pixelweaver serve --port 7779
+    ```
+11. Rust polls `GET /health` every 500ms, 10s timeout (existing logic, relocated).
+12. Emit `bootstrap:complete` -- webview transitions to the main application.
+
+**Total first-launch time:** 10-15 seconds. This happens exactly once (unless deps change in an update).
+
+### Implementation Details
+
+- Use `tauri::path::PathResolver` to get `resource_dir()` and `app_data_dir()`.
+- The copy step should use recursive directory copying with proper error handling for permission issues.
+- The `uv sync` command should be spawned with `Stdio::piped()` on both stdout and stderr so that progress can be streamed.
+- Parse uv's output to extract meaningful progress phases (downloading, resolving, installing).
+
+---
+
+## Phase 2: Warm Start (Subsequent Launches)
+
+**Effort: Low** -- Conditional check before the existing spawn logic.
+
+### Flow
+
+1. Rust checks: `.venv/bin/python` exists in `<app_data_dir>/python/`? **Yes.**
+2. Rust checks: SHA-256 hash of bundled `uv.lock` == SHA-256 hash of `<app_data_dir>/python/uv.lock`? **Yes** (same app version).
+3. Skip bootstrap entirely.
+4. Spawn server using the bundled uv binary:
+   ```
+   <resource_dir>/uv run --directory <app_data_dir>/python/ pixelweaver serve --port 7779
+   ```
+5. Poll `/health`, timeout 10s.
+6. App is live in **1-2 seconds**.
+
+### Notes
+
+- The hash comparison is cheap (read two small files, compute SHA-256).
+- If the hashes match, there is no network call, no `uv sync`, no delay.
+- The existing `check_health` / reuse-existing-server logic should be preserved as a fallback.
+
+---
+
+## Phase 3: Update Flow
+
+**Effort: Low** -- Lockfile hash comparison triggers incremental re-sync.
+
+When a new version of the app ships with updated Python code or dependencies:
+
+1. On launch, Rust detects that the bundled `uv.lock` hash differs from the installed copy in `<app_data_dir>/python/`.
+2. Rust copies the updated `pyproject.toml`, `uv.lock`, and `src/` from `resource_dir()` to `<app_data_dir>/python/`, overwriting the previous versions.
+3. Rust runs `uv sync --frozen --directory <app_data_dir>/python/` (incremental -- only installs changed/added deps, removes stale ones).
+4. Starts the server as usual.
+
+**If only Python source changed** (no dependency changes): `uv sync` is a near-instant no-op (~100ms), and the updated source files in `<app_data_dir>/python/src/` are picked up directly by the next server start.
+
+---
+
+## Phase 4: Server Restart IPC
+
+**Effort: Low** -- One Tauri IPC command + a frontend overlay.
+
+### Rust Side
+
+A single Tauri command exposed to the webview:
+
+```rust
+#[tauri::command]
+fn restart_server(state: State<SidecarProcess>) -> Result<(), String> {
+    kill_sidecar(&state);
+    spawn_server(&state)?;
+    wait_for_healthy()?;
+    Ok(())
+}
+```
+
+Registered via `.invoke_handler(tauri::generate_handler![restart_server])` in the builder.
+
+### Use Cases
+
+- Configuration changes that require a server restart.
+- Feature flag toggles.
+- Manual crash recovery (user clicks "Restart Server").
+
+### Frontend Side
+
+- A "Reconnecting..." overlay component that appears when the WebSocket connection drops.
+- The overlay disappears when the server is back and the WebSocket reconnects.
+- The existing `ws-client.ts` already implements exponential backoff reconnection logic (`calculateBackoff`, `scheduleReconnect`, `reconnectAttempts`), so the reconnection itself is handled. The overlay just needs to react to connection state.
+
+---
+
+## Phase 5: Auto-Crash Recovery
+
+**Effort: Low** -- Process watcher + automatic restart loop.
+
+### Flow
+
+1. Rust monitors the sidecar child process. When using `Child`, check `try_wait()` periodically or use a dedicated watcher thread.
+2. If the child process exits unexpectedly (non-zero exit or signal), emit a `server:crashed` event to the webview.
+3. WebView shows the "Reconnecting..." overlay (same component as Phase 4).
+4. Rust automatically calls `spawn_server()` + `wait_for_healthy()`.
+5. On success, emit `server:ready` -- webview reconnects via `ws-client.ts` auto-reconnect.
+
+### Retry Limits
+
+- Maximum 3 automatic restarts within a 60-second sliding window.
+- If the limit is exceeded, emit `server:fatal` and show an error screen with:
+  - Last N lines of stderr from the server process.
+  - A "Try Again" button (resets the retry counter).
+  - A "Report Bug" button (copies diagnostics to clipboard or opens an issue URL).
+
+### Implementation
+
+A background thread (or `tokio` task if async is adopted) that calls `child.try_wait()` in a loop with a short sleep (e.g., 1s). When the process is gone, it triggers the restart logic. The retry counter and timestamp window are tracked in shared state.
+
+---
+
+## Phase 6: Auto-Updater
+
+**Effort: Medium** -- Plugin setup + update server/endpoint configuration.
+
+### Setup
+
+1. Add `tauri-plugin-updater = "2"` to `src-tauri/Cargo.toml`.
+2. Initialize the plugin in `lib.rs`: `.plugin(tauri_plugin_updater::Builder::new().build())`.
+3. Configure the updater in `tauri.conf.json`:
+   ```json
+   "plugins": {
+     "updater": {
+       "endpoints": ["https://releases.pixelweaver.com/updates/{{target}}/{{current_version}}"],
+       "pubkey": "<public key for signature verification>"
+     }
+   }
+   ```
+4. The endpoint can be a static file host (S3, GitHub Releases) serving update manifests, or a dynamic server.
+
+### Update Flow
+
+1. On launch (after the server is running), the frontend checks for updates via the updater plugin API.
+2. If an update is available, show a non-intrusive notification: "Update available. Restart to apply?"
+3. User confirms -- download new bundle, apply, restart.
+4. After restart, the bootstrap system (Phase 3 update flow) handles any Python dependency changes automatically.
+
+### Signing
+
+- Updates must be signed. Tauri's updater verifies signatures against the configured public key.
+- The build pipeline generates signed update bundles using `tauri signer`.
+
+---
+
+## Error Handling
+
+| Failure | User-Facing Behavior |
+|---------|---------------------|
+| No network on first launch | Setup screen shows: "Internet connection required for first-time setup. Please connect and click Retry." with a Retry button. |
+| `uv sync` fails (bad deps, build error) | Setup screen shows the last 20 lines of stderr in a scrollable text area, plus a "Copy Error" button and a "Report Bug" button. |
+| Server won't start (health check timeout) | After 10s timeout, show last stderr lines from the server process, a Retry button, and a "Report Bug" button. |
+| Server crashes mid-session | Auto-restart up to 3 times in 60s (Phase 5). If limit exceeded, show error screen with diagnostics. |
+| Disk full | `uv sync` or file copy fails -- show the OS error message with clear context ("Not enough disk space to complete setup"). |
+| Port 7779 already in use | Detect `EADDRINUSE` in server stderr. Options: (a) try the next port (7780, 7781, ...) and pass it to the frontend via a Tauri event, or (b) show an error asking the user to close the other application. Option (a) is better UX. |
+| Corrupted venv | If the venv exists but `uv run` fails, delete `<app_data_dir>/python/` and re-run the full bootstrap. Show a "Repairing installation..." message. |
+
+---
+
+## Rust Module Structure
+
+The current monolithic `lib.rs` should be split into focused modules:
+
+| File | Responsibility | Approx. Lines |
+|------|---------------|---------------|
+| `src-tauri/src/main.rs` | Entry point (existing, minimal -- just calls `pixelweaver_lib::run()`) | ~5 |
+| `src-tauri/src/lib.rs` | Tauri builder setup, plugin registration, IPC handler registration, run loop with exit cleanup | ~60 |
+| `src-tauri/src/sidecar.rs` | `spawn_server()`, `kill_sidecar()`, `check_health()`, `wait_for_healthy()`, `SidecarProcess` state, process watcher thread | ~120 |
+| `src-tauri/src/bootstrap.rs` | `needs_bootstrap()`, `needs_update()`, `run_bootstrap()`, file copying, `uv sync` execution, progress event emission | ~150 |
+
+Total: ~335 lines of Rust. The current 179 lines grow to accommodate bootstrap, update detection, crash recovery, and restart IPC, but the logic is straightforward.
+
+---
+
+## Frontend Changes
+
+Two new lightweight Svelte 5 components:
+
+### BootstrapScreen.svelte
+
+- Displayed during first launch (Phase 1) and update re-sync (Phase 3).
+- Listens for `bootstrap:start`, `bootstrap:progress`, `bootstrap:complete`, and `bootstrap:error` Tauri events.
+- Shows a centered card with the PixelWeaver logo, a progress message, and a CSS spinner.
+- On error, switches to an error state with stderr output and action buttons.
+- Conditionally rendered at the app root, above/instead-of the main workspace.
+
+### ReconnectOverlay.svelte
+
+- Displayed when the WebSocket connection drops (crash recovery, restart IPC).
+- Listens for `server:crashed`, `server:ready`, and `server:fatal` Tauri events.
+- Semi-transparent overlay on top of the workspace (the canvas remains visible but non-interactive).
+- Shows "Reconnecting..." with a spinner during recovery, or an error screen if recovery fails.
+- Can also be triggered manually by the restart IPC flow.
+
+Both components are small (50-100 lines each) and use the existing design tokens (`--bg-*`, `--text-*`, `--accent`).
+
+---
+
+## Build Pipeline
+
+There is currently no build script for the Tauri production bundle. A `scripts/tauri-build` script (or Makefile target) is needed.
+
+### Build Steps
+
+1. **Download the platform-appropriate `uv` binary** from GitHub releases to `src-tauri/resources/uv` (or `uv.exe`). Pin to a specific uv version for reproducibility.
+2. **Make it executable**: `chmod +x src-tauri/resources/uv` (macOS/Linux).
+3. **Copy the server directory**: Copy `server/pyproject.toml`, `server/uv.lock`, and `server/src/` to `src-tauri/resources/server/`.
+4. **Run `tauri build`**: Produces the platform-specific bundle (.dmg, .AppImage, .msi).
+
+### CI Configuration
+
+For CI (GitHub Actions or similar), run the build per-platform:
+
+| Runner | Target | Artifact |
+|--------|--------|----------|
+| macos-14 (arm64) | aarch64-apple-darwin | `.dmg` |
+| macos-13 (x86_64) | x86_64-apple-darwin | `.dmg` |
+| ubuntu-latest | x86_64-unknown-linux-gnu | `.AppImage`, `.deb` |
+| windows-latest | x86_64-pc-windows-msvc | `.msi`, `.exe` |
+
+### tauri.conf.json Changes
+
+Add the `resources` key to declare bundled files:
+
+```json
+"bundle": {
+  "active": true,
+  "targets": "all",
+  "resources": {
+    "resources/uv": "uv",
+    "resources/server/": "server/"
+  },
+  ...
+}
+```
+
+This tells Tauri to include these files in the app bundle and makes them accessible via `resource_dir()` at runtime.
+
+---
+
+## Platform-Specific Notes
+
+### macOS
+
+- The bundled `uv` binary must have its executable bit set before bundling. Tauri preserves file permissions.
+- The `.app` bundle is **read-only when code-signed**, which is why the venv must live outside it in `app_data_dir()`.
+- Distribution outside the Mac App Store requires **notarization** via `xcrun notarytool`. The Tauri build pipeline supports this with `--sign` and notarization config.
+- The webview origin is `tauri://localhost` -- already in the server's CORS allow list.
+- Gatekeeper may quarantine the app on first launch; notarization resolves this.
+
+### Linux
+
+- **AppImage** is the best format for self-contained distribution -- it is a single file that runs on most distros.
+- `.deb` packages also work and install to `/usr/lib/`.
+- The bundled `uv` binary must be the glibc-linked variant (not musl) to match common desktop distros.
+- The webview origin is `https://tauri.localhost` -- already in the server's CORS allow list.
+- Some distros may require WebKitGTK to be installed; this is a Tauri system requirement, not specific to this bundling work.
+
+### Windows
+
+- `.msi` installer is the standard distribution format. `.exe` (NSIS) is also available.
+- The `uv` binary is `uv.exe`; the venv structure uses `.venv\Scripts\` instead of `.venv/bin/`.
+- All path logic in Rust must use `std::path::PathBuf` (never hardcoded slashes) to handle this transparently.
+- **Windows Defender SmartScreen** shows a warning for unsigned apps. Signing with an EV certificate eliminates this. Without signing, users see "Windows protected your PC" and must click "More info" then "Run anyway".
+- The webview origin is `https://tauri.localhost` -- already in the server's CORS allow list.
+
+---
+
+## CORS Configuration
+
+The FastAPI server's CORS middleware (`server/src/pixelweaver/main.py`) already uses a regex that matches all three Tauri webview origins:
+
+```python
+allow_origin_regex=r"^(tauri|https?)://(tauri\.)?localhost(:\d+)?$"
+```
+
+This covers:
+- `tauri://localhost` (macOS)
+- `https://tauri.localhost` (Windows, Linux)
+- `http://localhost:<port>` (dev mode)
+
+**No CORS changes are needed.** This is noted here so future developers do not accidentally narrow the regex.
+
+---
+
+## Files That Will Change
+
+| File | Action | Phase |
+|------|--------|-------|
+| `src-tauri/src/lib.rs` | Refactor: extract sidecar logic to `sidecar.rs`, add bootstrap orchestration, register IPC handlers | 1, 4 |
+| `src-tauri/src/sidecar.rs` | Create: `spawn_server`, `kill_sidecar`, `check_health`, `wait_for_healthy`, `SidecarProcess`, process watcher | 1, 5 |
+| `src-tauri/src/bootstrap.rs` | Create: `needs_bootstrap`, `needs_update`, `run_bootstrap`, file copy, `uv sync` runner, progress events | 1, 2, 3 |
+| `src-tauri/tauri.conf.json` | Edit: add `bundle.resources`, add `plugins.updater` config | 1, 6 |
+| `src-tauri/Cargo.toml` | Edit: add `tauri-plugin-updater`, possibly `sha2` for hash comparison | 1, 6 |
+| `src-tauri/capabilities/default.json` | Edit: add permissions for event emission, updater, and resource access if needed | 1, 6 |
+| `src/lib/components/BootstrapScreen.svelte` | Create: first-launch setup UI with progress and error states | 1 |
+| `src/lib/components/ReconnectOverlay.svelte` | Create: server restart/crash overlay | 4, 5 |
+| `src/App.svelte` (or equivalent root) | Edit: conditionally render BootstrapScreen and ReconnectOverlay | 1, 4 |
+| `scripts/tauri-build` | Create: build script that fetches uv, copies server, runs `tauri build` | Build |
+
+---
+
+## Effort Summary
+
+| Phase | Description | Effort | Dependencies |
+|-------|-------------|--------|-------------|
+| Phase 1 | Bootstrap flow (first launch) | Medium | None |
+| Phase 2 | Warm start (subsequent launches) | Low | Phase 1 |
+| Phase 3 | Update flow (new app versions) | Low | Phase 1 |
+| Phase 4 | Server restart IPC | Low | Phase 1 (sidecar refactor) |
+| Phase 5 | Auto-crash recovery | Low | Phase 4 (restart logic) |
+| Phase 6 | Auto-updater | Medium | Phase 3 (update detection) |
+| Build pipeline | Scripts + CI for per-platform builds | Medium | Phase 1 (resource layout) |
+| Testing | Manual testing on all target platforms | Medium | All phases |
+
+Phases 1-3 form the critical path. Phases 4-5 are quick wins once the sidecar module is extracted. Phase 6 and the build pipeline can proceed independently once Phase 1 is complete.
+
+**Total estimated effort:** 3-5 focused sessions, with Phase 1 + build pipeline being the largest chunk.