v0.5.0-beta: Tauri Migration

PERFORMANCE_AUDIT.md

@@ -24,10 +24,10 @@ This document details the performance improvements made in V0.5.0-beta by migrat
 ## 3. The Tauri Migration (V0.5.0-beta)
 *Goal: Remove the massive Electron overhead for a background utility.*
 
-- **Removed Node.js & Chromium:** Replaced with Rust backend and native OS webview (WebKit on macOS).
-  - *Impact:* The `.dmg` size plummeted from ~80MB down to 7.3MB.
-- **Rust Backend:** All IPC calls now run through a highly optimized Rust backend using `std::fs` asynchronously.
-  - *Impact:* IPC latency is effectively instantaneous, with lower memory overhead for background processes.
+- **Zero-Copy IPC via `serde`:** Electron relies on JSON stringification over a Node.js bridge. Tauri uses Rust's `serde` library, which serializes and deserializes IPC payloads with near-zero overhead, making data transfer between the UI and backend virtually instantaneous.
+- **Native Async Runtime:** The Rust backend utilizes the `tokio` multi-threaded async runtime. Heavy operations like recursive directory walking (`get_notes`) and HTTP requests (`reqwest` for OpenAI) are executed off the main thread, ensuring the UI never stutters during disk I/O.
+- **Native Security:** Replaced Electron's `safeStorage` with a custom Rust implementation using the `keyring` crate (for OS-level credential storage) and `aes-gcm` (for AES-256-GCM encryption). This provides hardware-backed security with a fraction of the memory footprint.
+- **Strict Capability Scoping:** Migrated to Tauri v2's capability system, ensuring the frontend can only invoke explicitly whitelisted Rust commands and access strictly scoped file paths, eliminating entire classes of XSS-to-filesystem vulnerabilities present in Electron.
 
 ---
 
@@ -65,6 +65,6 @@ This document details the performance improvements made in V0.5.0-beta by migrat
 *Intellectual honesty: Where the app is still not perfectly optimized, and why.*
 
 1. **Graph View Rendering:** The D3.js graph view currently recalculates the entire force-directed layout on every node addition. With 1,000+ notes, this causes a 2-second UI freeze. 
-   - *Mitigation:* We accept this for V0.4.0 as graph view is a secondary feature. V0.5.0 will implement WebGL (via `react-force-graph`) or web workers for layout calculation.
-2. **Regex Parsing on Large Files:** The custom DSL regex runs on the entire document string on every keystroke. For files >50KB, this causes minor input latency.
-   - *Mitigation:* CodeMirror's incremental parsing helps, but we may need to move the DSL parser to a Web Worker in the future.
+   - *Mitigation:* We accept this for V0.4.0 as graph view is a secondary feature. V0.5.0 will implement WebGL (via `react-force-graph`) to offload layout calculations to the GPU.
+2. **Regex Parsing on Large Files:** The custom DSL regex runs on the entire document string on every keystroke. For files >50KB, this causes minor input latency in the JS main thread.
+   - *Mitigation:* In V0.5.0, this parsing can be ported to a `#[tauri::command]` in Rust. Rust's regex engine is highly performant and completely bypasses the JS main thread, eliminating input latency without needing Web Workers.

TAURI_MIGRATION.md

@@ -0,0 +1,26 @@
+# The Shift: From Electron to Tauri
+
+## Why We Migrated
+PaperCache was originally built on Electron. While Electron provides a fantastic, unified cross-platform development environment, it ships an entire Chromium browser and Node.js runtime with every application. For a minimalist, lightweight, global scratchpad that is designed to stay out of the user's way and be invoked instantly via a global hotkey, the overhead was simply too high.
+
+- **Resource Heaviness**: Electron apps consume hundreds of megabytes of RAM even when idling in the background. For a background-first application, this was a major flaw.
+- **Binary Size**: Installers were large, routinely exceeding 80MB, just to run a relatively lightweight notepad application.
+- **Security Posture**: Embedding Node.js alongside a Chromium rendering engine requires significant hardening (IPC sandboxing, context isolation) to prevent XSS attacks from becoming arbitrary remote code executions.
+
+## The Tauri & Rust Advantage
+Tauri takes a fundamentally different approach. Instead of bundling Chromium and Node.js, Tauri leverages the system's native webview (e.g., WebKit on macOS, WebView2 on Windows) and uses Rust for the backend architecture.
+
+### Benefits
+1. **Dramatically Smaller Binaries**: Since we aren't bundling a browser engine, the PaperCache macOS installer shrank from ~80MB down to ~7.3MB (an ~90% reduction).
+2. **Fractional Memory Usage**: PaperCache now uses the OS's shared webview processes, resulting in a >66% reduction in idle RAM usage.
+3. **Lightning Fast Startup**: The compiled native Rust backend and the lack of a bundled Node.js runtime mean the app spawns and responds to global hotkeys almost instantaneously.
+4. **Enhanced Security Posture**: Tauri uses a highly restrictive capabilities system. The frontend only has access to the exact commands we explicitly expose via Rust (e.g., specific file system access or global shortcuts). Rust's strict memory safety rules further eliminate entire classes of backend vulnerabilities.
+5. **Native OS Integrations**: Rust allows us to hook directly into low-level operating system APIs (like `cocoa` on macOS) to handle complex edge cases—such as hiding the dock icon, intercepting sleep/wake events, and injecting custom shadow states—without relying on heavy Node.js bridging.
+
+### Potential Cons and Trade-offs
+1. **Webview Inconsistencies**: Because Tauri relies on the OS's native webview (WebKit/Safari on macOS, Edge/WebView2 on Windows, WebKitGTK on Linux), CSS and JavaScript might behave slightly differently depending on the operating system. We lose the "write once, render exactly the same everywhere" guarantee of Electron's bundled Chromium.
+2. **Rust Learning Curve**: Building backend features, managing the system tray state, and handling global shortcuts now require writing Rust code, which has a steeper learning curve and stricter compilation rules than Node.js.
+3. **Ecosystem Maturity**: While growing rapidly, Tauri's plugin ecosystem is not quite as extensive as Electron's decade-old NPM module library. Advanced or niche OS integrations may require writing custom Rust wrappers.
+
+## Conclusion
+The migration to Tauri in `v0.5.0-beta` aligns perfectly with PaperCache's core philosophy: to be a lightning-fast, secure, and native-feeling utility. The incredible performance and resource gains vastly outweigh the minor webview fragmentation, solidifying Tauri as the optimal choice for the future of the application.

features.md

@@ -11,7 +11,7 @@ This document outlines every feature available in the PaperCache codebase, organ
 - **Date & Time Formats**: Highlights standard date (`DD-MM-YYYY` or `YYYY-MM-DD`) and time (`HH:MM` or `HH:MM:SS`) formats into clean, distinct pills.
 - **Interactive Checkboxes**: Type `/check` to create an interactive checkbox widget. Clicking it changes it to `/checked` and visually strikes through the text on that line!
 - **Tasks & Reminders**: Type `/task` to create a task widget. Add a space followed by `@` and a time (like `1d2h`, `tmrw`, or a specific date `YYYY-MM-DD HH:MM`) to set a due date. Press `Cmd+T` (or `Ctrl+T`) to open the Tasks Page, which tracks all tasks, calculates due times, and highlights overdue tasks in red.
-- **Customizable Theming & Fonts**: Customize fonts, text colors, background colors, background images, and individual highlight colors for variables, AI, and math. Supports full dark mode (`grid-dark`, `blueprint`) and custom zoom scaling.
+- **Customizable Theming & Fonts**: Customize fonts, text colors, background colors, background images, and individual highlight colors for variables, AI, and math. Supports full dark mode (`grid-dark`, `blueprint`).
 
 ## Math, Variables, and Calculations
 

src-tauri/Cargo.toml

@@ -10,7 +10,7 @@ rust-version = "1.77"
 tauri-build = { version = "2.0.0", features = [] }
 
 [dependencies]
-tauri = { version = "2.0.0", features = ["tray-icon", "image-png", "image-ico"] }
+tauri = { version = "2.0.0", features = ["tray-icon", "image-png", "image-ico", "macos-private-api"] }
 tauri-plugin-opener = "2"
 tauri-plugin-autostart = "2.0.0"
 tauri-plugin-window-state = "2.0.0"

src-tauri/build.rs

@@ -1,3 +1,3 @@
 fn main() {
-  tauri_build::build()
+    tauri_build::build()
 }

src-tauri/src/commands/ai.rs

@@ -6,7 +6,11 @@ const SERVICE_NAME: &str = "com.variablethe.papercache";
 const DEFAULT_BASE_URL: &str = "https://api.openai.com/v1";
 
 #[tauri::command]
-pub async fn openai_chat(model: String, messages: Vec<serde_json::Value>, base_url: String) -> Result<serde_json::Value, String> {
+pub async fn openai_chat(
+    model: String,
+    messages: Vec<serde_json::Value>,
+    base_url: String,
+) -> Result<serde_json::Value, String> {
     if model.trim().is_empty() {
         return Err("Invalid model provided".into());
     }
@@ -16,7 +20,8 @@ pub async fn openai_chat(model: String, messages: Vec<serde_json::Value>, base_u
 
     let entry = Entry::new(SERVICE_NAME, "openai_api_key")
         .map_err(|e| format!("Failed to access keyring: {}", e))?;
-    let api_key = entry.get_password()
+    let api_key = entry
+        .get_password()
         .map_err(|_| "API key not found. Please set it in settings.".to_string())?;
 
     let client = Client::new();
@@ -35,7 +40,8 @@ pub async fn openai_chat(model: String, messages: Vec<serde_json::Value>, base_u
         "messages": messages
     });
 
-    let response = client.post(&base)
+    let response = client
+        .post(&base)
         .header("Authorization", format!("Bearer {}", api_key))
         .header("Content-Type", "application/json")
         .header("HTTP-Referer", "https://github.com/papercache/papercache")
@@ -47,9 +53,18 @@ pub async fn openai_chat(model: String, messages: Vec<serde_json::Value>, base_u
 
     if !response.status().is_success() {
         let status = response.status();
-        let error_text = response.text().await.unwrap_or_else(|_| "Unknown error".to_string());
-        return Err(format!("API request failed with status {}: {}", status, error_text));
+        let error_text = response
+            .text()
+            .await
+            .unwrap_or_else(|_| "Unknown error".to_string());
+        return Err(format!(
+            "API request failed with status {}: {}",
+            status, error_text
+        ));
     }
 
-    response.json().await.map_err(|e| format!("Failed to parse API response: {}", e))
+    response
+        .json()
+        .await
+        .map_err(|e| format!("Failed to parse API response: {}", e))
 }

src-tauri/src/commands/fs.rs

@@ -1,6 +1,6 @@
+use serde::{Deserialize, Serialize};
 use std::fs;
 use std::path::{Path, PathBuf};
-use serde::{Deserialize, Serialize};
 use tauri::AppHandle;
 use tauri_plugin_dialog::DialogExt;
 
@@ -23,17 +23,17 @@ pub fn get_papercache_dir() -> Result<PathBuf, String> {
 pub fn get_safe_path(id: &str) -> Result<PathBuf, String> {
     let base = get_papercache_dir()?;
     let target = base.join(id);
-    
+
     let parent = target.parent().ok_or("Invalid path parent")?;
     if !parent.exists() {
         fs::create_dir_all(parent).map_err(|e| e.to_string())?;
     }
     let canonical_parent = parent.canonicalize().map_err(|e| e.to_string())?;
-    
+
     if !canonical_parent.starts_with(&base) {
         return Err("Path traversal detected".to_string());
     }
-    
+
     if target.exists() {
         let canonical_target = target.canonicalize().map_err(|e| e.to_string())?;
         if !canonical_target.starts_with(&base) {
@@ -57,19 +57,17 @@ fn walk_dir(dir: &Path, notes: &mut Vec<Note>, base_path: &Path) {
                 if ext == "md" || ext == "json" {
                     if let Ok(content) = fs::read_to_string(&path) {
                         let metadata = fs::metadata(&path).ok();
-                        let mtime = metadata.and_then(|m| m.modified().ok())
+                        let mtime = metadata
+                            .and_then(|m| m.modified().ok())
                             .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
                             .map(|d| d.as_millis() as u64)
                             .unwrap_or(0);
-                        let id = path.strip_prefix(base_path)
+                        let id = path
+                            .strip_prefix(base_path)
                             .unwrap_or(&path)
                             .to_string_lossy()
                             .to_string();
-                        notes.push(Note {
-                            id,
-                            content,
-                            mtime,
-                        });
+                        notes.push(Note { id, content, mtime });
                     }
                 }
             }
@@ -83,7 +81,10 @@ fn clean_empty_parents(file_path: &Path, base: &Path) {
         if parent == base || !parent.starts_with(base) {
             break;
         }
-        if fs::read_dir(parent).map(|mut i| i.next().is_none()).unwrap_or(false) {
+        if fs::read_dir(parent)
+            .map(|mut i| i.next().is_none())
+            .unwrap_or(false)
+        {
             if fs::remove_dir(parent).is_err() {
                 break;
             }
@@ -122,11 +123,11 @@ pub fn delete_note(id: String) -> Result<bool, String> {
     }
     let path = get_safe_path(&id)?;
     fs::remove_file(&path).map_err(|e| e.to_string())?;
-    
+
     if let Ok(base) = get_papercache_dir() {
         clean_empty_parents(&path, &base);
     }
-    
+
     Ok(true)
 }
 
@@ -135,11 +136,11 @@ pub fn rename_note(old_id: String, new_id: String) -> Result<bool, String> {
     let old_path = get_safe_path(&old_id)?;
     let new_path = get_safe_path(&new_id)?;
     fs::rename(&old_path, &new_path).map_err(|e| e.to_string())?;
-    
+
     if let Ok(base) = get_papercache_dir() {
         clean_empty_parents(&old_path, &base);
     }
-    
+
     Ok(true)
 }
 
@@ -152,35 +153,39 @@ pub async fn export_note(
 ) -> Result<bool, String> {
     use std::sync::atomic::Ordering;
     state.is_open.store(true, Ordering::SeqCst);
-    
+
     let state_clone = state.is_open.clone();
     let (tx, rx) = tokio::sync::oneshot::channel();
-
-    app.dialog().file().set_file_name(&filename).save_file(move |file_path| {
-        state_clone.store(false, Ordering::SeqCst);
-        let res = if let Some(path) = file_path {
-            let sys_path = path.into_path().map_err(|_| "Invalid path from dialog".to_string());
-            match sys_path {
-                Ok(p) => fs::write(p, content).map(|_| true).map_err(|e| e.to_string()),
-                Err(e) => Err(e),
-            }
-        } else {
-            Ok(false)
-        };
-        let _ = tx.send(res);
-    });
-
+
+    app.dialog()
+        .file()
+        .set_file_name(&filename)
+        .save_file(move |file_path| {
+            state_clone.store(false, Ordering::SeqCst);
+            let res = if let Some(path) = file_path {
+                let sys_path = path
+                    .into_path()
+                    .map_err(|_| "Invalid path from dialog".to_string());
+                match sys_path {
+                    Ok(p) => fs::write(p, content)
+                        .map(|_| true)
+                        .map_err(|e| e.to_string()),
+                    Err(e) => Err(e),
+                }
+            } else {
+                Ok(false)
+            };
+            let _ = tx.send(res);
+        });
+
     rx.await.unwrap_or_else(|_| {
         state.is_open.store(false, Ordering::SeqCst);
         Err("Dialog was closed unexpectedly".to_string())
     })
 }
 
 #[tauri::command]
-pub fn set_dialog_open(
-    state: tauri::State<'_, crate::DialogState>,
-    open: bool,
-) {
+pub fn set_dialog_open(state: tauri::State<'_, crate::DialogState>, open: bool) {
     use std::sync::atomic::Ordering;
     state.is_open.store(open, Ordering::SeqCst);
 }
@@ -197,11 +202,17 @@ pub fn run_onboarding() {
             let _ = fs::create_dir_all(&commands_dir);
             let summarize_path = commands_dir.join("summarize.md");
             if !summarize_path.exists() {
-                let _ = fs::write(&summarize_path, "# Summarize\n\nPlease summarize the selected text into 3 bullet points.");
+                let _ = fs::write(
+                    &summarize_path,
+                    "# Summarize\n\nPlease summarize the selected text into 3 bullet points.",
+                );
             }
             let translate_path = commands_dir.join("translate.md");
             if !translate_path.exists() {
-                let _ = fs::write(&translate_path, "# Translate\n\nPlease translate the following text into English.");
+                let _ = fs::write(
+                    &translate_path,
+                    "# Translate\n\nPlease translate the following text into English.",
+                );
             }
         }
     }