Heimgeist/docs/tauri-migration.md

Tauri Migration Notes

Tauri is now the primary experimental development shell for Heimgeist. Electron remains intact as a fallback until the remaining desktop and packaging gaps are closed.

References checked during the spike:

• Tauri Vite setup: https://v2.tauri.app/start/frontend/vite/
• Tauri JavaScript API: https://v2.tauri.app/reference/javascript/api/
• Tauri CLI: https://v2.tauri.app/reference/cli/
• Tauri dialog plugin: https://v2.tauri.app/plugin/dialog/
• Tauri opener plugin: https://v2.tauri.app/plugin/opener/

Current Desktop Responsibility Map

Area	Electron implementation	Tauri status
Main app window	BrowserWindow in electron/main.cjs, loading Vite in dev and dist/index.html in production	Implemented through src-tauri/tauri.conf.json; dev loads the same React/Vite renderer on the Tauri-specific port 5174
Settings window	Separate modal BrowserWindow routed to #/settings	Later phase: either a second Tauri webview window or the existing in-app settings route
Settings persistence	JSON under Electron app.getPath('userData'), or HEIMGEIST_SETTINGS_FILE when set	Implemented with persistent JSON under Tauri app config, with a first-run Electron settings import when safe
Renderer bridge	electron/preload.cjs exposes window.electronAPI; renderer uses src/desktop/desktopApi.js	Implemented: desktopApi still prefers Electron and falls back to Tauri commands/listeners
File picker	dialog.showOpenDialog via pick-paths IPC	Implemented through the official Tauri dialog plugin; supports the existing title, filters, and multiple option shape where practical
Open file/path	shell.openPath via open-path IPC	Implemented through the official Tauri opener plugin
External links	shell.openExternal and setWindowOpenHandler	Implemented through the official Tauri opener plugin for http, https, mailto, and tel URLs
Window focus events	Electron focus event forwarded to renderer	Implemented by emitting window-focused from Tauri and listening in desktopApi
App menu	Electron Menu.buildFromTemplate	Basic Tauri default menu implemented; detailed Electron menu parity remains later work
UI scale	Electron webContents.setZoomFactor	Implemented for Tauri/browser-like runtimes through desktopApi.applyUiScale, which applies renderer CSS zoom while leaving Electron native zoom unchanged
DevTools preference	Electron opens/closes DevTools in dev	Later phase: no clean stable Tauri equivalent is wired yet
Updates/changelog	Git-based update check, pull, restart, and local changelog	Later phase: replace with Tauri updater or another signed update flow
Backend lifecycle	External Node scripts start FastAPI in dev	Development parity implemented by scripts/run-tauri-dev.cjs, which starts or reuses the existing FastAPI dev backend; Python sidecar packaging remains later
Packaging	Electron starts from main and existing npm scripts	Later phase: Tauri bundle config, icons, signing/notarization, and Python backend sidecar

Development Workflow

• Electron development remains unchanged: npm run dev.
• Tauri development is now npm run dev:tauri or npm run dev:tauri:full.
• The Tauri wrapper starts or reuses FastAPI on 127.0.0.1:8000, waits for /health, then launches Tauri.
• Tauri uses its own strict Vite dev port: 127.0.0.1:5174. This avoids conflicts with the existing Electron renderer port 5173.
• The raw Tauri shell remains available as npm run dev:tauri:shell; use it only when the backend lifecycle is managed separately.

The Tauri dev backend is still the normal FastAPI backend started from the repository root through scripts/run-backend.cjs. That keeps chat history and local RAG data in the existing backend locations.

User Data Continuity

• Chats continue to use backend/app.db through the existing FastAPI backend. No database move, rewrite, or migration is part of this step.
• Local RAG libraries continue to use backend/libraries through the existing FastAPI backend. No library state is moved or rewritten.
• HEIMGEIST_SETTINGS_FILE remains an explicit shared settings override for both Electron and Tauri. When it is set, Tauri reads and writes that file directly and does not perform first-run import.
• Without HEIMGEIST_SETTINGS_FILE, Tauri stores settings in its app config settings.json.
• On first Tauri run only, when the Tauri settings file does not exist, Tauri attempts to read Electron settings from the platform config directory, including the existing Heimgeist/settings.json path used by Electron.
• If Electron settings are found, Tauri migrates and normalizes them into the Tauri settings path.
• Existing Tauri settings are not replaced by Electron settings.

Current Tauri Scaffold

• src-tauri/src/main.rs registers Tauri commands for settings, dialogs, path opening, external links, focus events, and update placeholders.
• src-tauri/capabilities/default.json grants the main window core, dialog, and opener permissions used by the scaffold.
• src-tauri/tauri.conf.json points Tauri at the existing Vite renderer on http://127.0.0.1:5174 in dev and ../dist for build output.
• scripts/run-tauri-dev.cjs is the full Tauri dev wrapper.
• src/desktop/desktopApi.js remains the only renderer bridge layer for Electron/Tauri desktop functions.

Intentional Non-Goals

• No Electron files, scripts, dependencies, or IPC behavior were removed.
• No backend API contracts changed.
• No Python backend sidecar, production backend packaging, or data relocation was added.
• No Tauri updater, changelog parity, or restart flow was implemented.

Remaining Gaps Before Electron Removal

• Update flow: startup/manual update checks, changelog, restart, and signed release strategy.
• Production backend lifecycle: package the FastAPI backend, set ffmpeg/ffprobe paths, health gate startup, and shut down cleanly.
• DevTools preference: Electron honors openDevToolsOnStartup; Tauri currently documents this as an Electron-only setting.
• Settings window parity: Electron still has a separate settings modal; Tauri currently uses the existing renderer route.
• App menu parity: Tauri has a basic default menu, not the full Electron template.
• Packaging: bundle metadata, final icons, signing/notarization, updater channel, and installer behavior.