docs: add TAURI_MIGRATION.md

Author: VariableThe

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.