V2 Tauri integration (#3854)

# Description of Changes Please provide a summary of the changes, including: ## Add PDF File Association Support for Tauri App ### 🎯 **Features Added** - PDF file association configuration in Tauri - Command line argument detection for opened files - Automatic file loading when app is launched via "Open with" - Cross-platform support (Windows/macOS) ### 🔧 **Technical Changes** - Added `fileAssociations` in `tauri.conf.json` for PDF files - New `get_opened_file` Tauri command to detect file arguments - `fileOpenService` with Tauri fs plugin integration - `useOpenedFile` hook for React integration - Improved backend health logging during startup (reduced noise) ### 🧪 **Testing** See * https://v2.tauri.app/start/prerequisites/ * [DesktopApplicationDevelopmentGuide.md](DesktopApplicationDevelopmentGuide.md) ```bash # Test file association during development: cd frontend npm install cargo tauri dev --no-watch -- -- "path/to/file.pdf" ``` For production testing: 1. Build: npm run tauri build 2. Install the built app 3. Right-click PDF → "Open with" → Stirling-PDF 🚀 User Experience - Users can now double-click PDF files to open them directly in Stirling-PDF - Files automatically load in the viewer when opened via file association - Seamless integration with OS file handling --- ## Checklist ### General - [ ] I have read the [Contribution Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md) - [ ] I have read the [Stirling-PDF Developer Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md) (if applicable) - [ ] I have read the [How to add new languages to Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md) (if applicable) - [ ] I have performed a self-review of my own code - [ ] My changes generate no new warnings ### Documentation - [ ] I have updated relevant docs on [Stirling-PDF's doc repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/) (if functionality has heavily changed) - [ ] I have read the section [Add New Translation Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/HowToAddNewLanguage.md#add-new-translation-tags) (for new translation tags only) ### UI Changes (if applicable) - [ ] Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR) ### Testing (if applicable) - [ ] I have tested my changes locally. Refer to the [Testing Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#6-testing) for more details. --------- Co-authored-by: Connor Yoh <[email protected]> Co-authored-by: James Brunton <[email protected]> Co-authored-by: James Brunton <[email protected]>
2026-07-16 11:23:10 +02:00 · 2025-11-05 11:44:59 +00:00
parent f3eed4428d
commit 4c0c9b28ef
120 changed files with 11005 additions and 1294 deletions
@@ -72,3 +72,59 @@ This section has moved here: [https://facebook.github.io/create-react-app/docs/d
 ### `npm run build` fails to minify

 This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)
+
+
+## Tauri
+In order to run Tauri, you first have to build the Java backend for Tauri to use.
+
+**macOS/Linux:**
+
+From the root of the repo, run:
+
+```bash
+./gradlew clean build
+./scripts/build-tauri-jlink.sh
+```
+
+**Windows**
+
+From the root of the repo, run:
+
+```batch
+gradlew clean build
+scripts\build-tauri-jlink.bat
+```
+
+### Testing the Bundled Runtime
+
+Before building the full Tauri app, you can test the bundled runtime:
+
+**macOS/Linux:**
+```bash
+./frontend/src-tauri/runtime/launch-stirling.sh
+```
+
+**Windows:**
+```cmd
+frontend\src-tauri\runtime\launch-stirling.bat
+```
+
+This will start Stirling-PDF using the bundled JRE, accessible at http://localhost:8080
+
+### Dev
+To run Tauri in development. Use the command in the `frontend` folder:
+
+```bash
+npm run tauri-dev
+```
+
+This will run the gradle runboot command and the tauri dev command concurrently, starting the app once both are stable.
+
+### Build
+To build a deployment of the Tauri app. Use this command in the `frontend` folder:
+
+```bash
+npm run tauri-build
+```
+
+This will bundle the backend and frontend into one executable for each target. Targets can be set within the `tauri.conf.json` file.
@@ -21,6 +21,7 @@ export default defineConfig(
      'dist',
      'node_modules',
      'public',
+      'src-tauri',
    ],
  },
  eslint.configs.recommended,
@@ -25,6 +25,8 @@
    "@embedpdf/plugin-viewport": "^1.3.14",
    "@embedpdf/plugin-zoom": "^1.3.14",
    "@emotion/react": "^11.14.0",
+    "@tauri-apps/api": "^2.5.0",
+    "@tauri-apps/plugin-fs": "^2.4.0",
    "@emotion/styled": "^11.14.1",
    "@iconify/react": "^6.0.2",
    "@mantine/core": "^8.3.1",
@@ -62,10 +64,13 @@
    "lint": "eslint --max-warnings=0",
    "build": "vite build",
    "preview": "vite preview",
-    "typecheck": "tsc --noEmit",
+    "tauri-dev": "tauri dev --no-watch",
+    "tauri-build": "tauri build",
+    "typecheck": "npm run typecheck:proprietary",
    "typecheck:core": "tsc --noEmit --project tsconfig.core.json",
    "typecheck:proprietary": "tsc --noEmit --project tsconfig.proprietary.json",
-    "typecheck:all": "npm run typecheck:core && npm run typecheck:proprietary",
+    "typecheck:desktop": "tsc --noEmit --project tsconfig.desktop.json",
+    "typecheck:all": "npm run typecheck:core && npm run typecheck:proprietary && npm run typecheck:desktop",
    "check": "npm run typecheck && npm run lint && npm run test:run",
    "generate-licenses": "node scripts/generate-licenses.js",
    "generate-icons": "node scripts/generate-icons.js",
@@ -103,6 +108,7 @@
    ]
  },
  "devDependencies": {
+    "@tauri-apps/cli": "^2.5.0",
    "@eslint/js": "^9.36.0",
    "@iconify-json/material-symbols": "^1.2.37",
    "@iconify/utils": "^3.0.2",
@@ -4592,5 +4592,10 @@
    "passwordMustBeDifferent": "New password must be different from current password",
    "passwordChangedSuccess": "Password changed successfully! Please log in again.",
    "passwordChangeFailed": "Failed to change password. Please check your current password."
+  },
+  "backendHealth": {
+    "checking": "Checking backend status...",
+    "online": "Backend Online",
+    "offline": "Backend Offline"
  }
 }
@@ -0,0 +1,5 @@
+# Generated by Cargo
+# will have compiled files and executables
+/target/
+/gen/schemas
+/runtime/
@@ -0,0 +1,35 @@
+[package]
+name = "stirling-pdf"
+version = "0.1.0"
+description = "Stirling-PDF Desktop Application"
+authors = ["Stirling-PDF Contributors"]
+license = ""
+repository = ""
+edition = "2021"
+rust-version = "1.77.2"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+name = "app_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2.2.0", features = [] }
+
+[dependencies]
+serde_json = "1.0"
+serde = { version = "1.0", features = ["derive"] }
+log = "0.4"
+tauri = { version = "2.9.0", features = [ "devtools"] }
+tauri-plugin-log = "2.0.0-rc"
+tauri-plugin-shell = "2.1.0"
+tauri-plugin-fs = "2.4.4"
+tokio = { version = "1.0", features = ["time"] }
+reqwest = { version = "0.11", features = ["json"] }
+
+# macOS-specific dependencies for native file opening
+[target.'cfg(target_os = "macos")'.dependencies]
+objc = "0.2"
+cocoa = "0.24"
+once_cell = "1.19"
@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}
@@ -0,0 +1,15 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "enables the default permissions",
+  "windows": [
+    "main"
+  ],
+  "permissions": [
+    "core:default",
+    { 
+    "identifier": "fs:allow-read-file",
+    "allow": [{ "path": "**" }]
+   }
+  ]
+}
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-rainbow" viewBox="0 0 16 16"><path d="M8 4.5a7 7 0 0 0-7 7 .5.5 0 0 1-1 0 8 8 0 1 1 16 0 .5.5 0 0 1-1 0 7 7 0 0 0-7-7zm0 2a5 5 0 0 0-5 5 .5.5 0 0 1-1 0 6 6 0 1 1 12 0 .5.5 0 0 1-1 0 5 5 0 0 0-5-5zm0 2a3 3 0 0 0-3 3 .5.5 0 0 1-1 0 4 4 0 1 1 8 0 .5.5 0 0 1-1 0 3 3 0 0 0-3-3zm0 2a1 1 0 0 0-1 1 .5.5 0 0 1-1 0 2 2 0 1 1 4 0 .5.5 0 0 1-1 0 1 1 0 0 0-1-1z"/></svg>
@@ -0,0 +1,379 @@
+use tauri_plugin_shell::ShellExt;
+use tauri::Manager;
+use std::sync::Mutex;
+use std::path::PathBuf;
+use crate::utils::add_log;
+
+// Store backend process handle globally
+static BACKEND_PROCESS: Mutex<Option<tauri_plugin_shell::process::CommandChild>> = Mutex::new(None);
+static BACKEND_STARTING: Mutex<bool> = Mutex::new(false);
+
+// Helper function to reset starting flag
+fn reset_starting_flag() {
+    let mut starting_guard = BACKEND_STARTING.lock().unwrap();
+    *starting_guard = false;
+}
+
+// Check if backend is already running or starting
+fn check_backend_status() -> Result<(), String> {
+    // Check if backend is already running
+    {
+        let process_guard = BACKEND_PROCESS.lock().unwrap();
+        if process_guard.is_some() {
+            add_log("⚠️ Backend process already running, skipping start".to_string());
+            return Err("Backend already running".to_string());
+        }
+    }
+    
+    // Check and set starting flag to prevent multiple simultaneous starts
+    {
+        let mut starting_guard = BACKEND_STARTING.lock().unwrap();
+        if *starting_guard {
+            add_log("⚠️ Backend already starting, skipping duplicate start".to_string());
+            return Err("Backend startup already in progress".to_string());
+        }
+        *starting_guard = true;
+    }
+    
+    Ok(())
+}
+
+// Find the bundled JRE and return the java executable path
+fn find_bundled_jre(resource_dir: &PathBuf) -> Result<PathBuf, String> {
+    let jre_dir = resource_dir.join("runtime").join("jre");
+    let java_executable = if cfg!(windows) {
+        jre_dir.join("bin").join("java.exe")
+    } else {
+        jre_dir.join("bin").join("java")
+    };
+    
+    if !java_executable.exists() {
+        let error_msg = format!("❌ Bundled JRE not found at: {:?}", java_executable);
+        add_log(error_msg.clone());
+        return Err(error_msg);
+    }
+    
+    add_log(format!("✅ Found bundled JRE: {:?}", java_executable));
+    Ok(java_executable)
+}
+
+// Find the Stirling-PDF JAR file
+fn find_stirling_jar(resource_dir: &PathBuf) -> Result<PathBuf, String> {
+    let libs_dir = resource_dir.join("libs");
+    let mut jar_files: Vec<_> = std::fs::read_dir(&libs_dir)
+        .map_err(|e| {
+            let error_msg = format!("Failed to read libs directory: {}. Make sure the JAR is copied to libs/", e);
+            add_log(error_msg.clone());
+            error_msg
+        })?
+        .filter_map(|entry| entry.ok())
+        .filter(|entry| {
+            let path = entry.path();
+            // Match any .jar file containing "stirling-pdf" (case-insensitive)
+            path.extension().and_then(|s| s.to_str()).map(|ext| ext.eq_ignore_ascii_case("jar")).unwrap_or(false)
+                && path.file_name()
+                    .and_then(|f| f.to_str())
+                    .map(|name| name.to_ascii_lowercase().contains("stirling-pdf"))
+                    .unwrap_or(false)
+        })
+        .collect();
+    
+    if jar_files.is_empty() {
+        let error_msg = "No Stirling-PDF JAR found in libs directory.".to_string();
+        add_log(error_msg.clone());
+        return Err(error_msg);
+    }
+    
+    // Sort by filename to get the latest version (case-insensitive)
+    jar_files.sort_by(|a, b| {
+        let name_a = a.file_name().to_string_lossy().to_ascii_lowercase();
+        let name_b = b.file_name().to_string_lossy().to_ascii_lowercase();
+        name_b.cmp(&name_a) // Reverse order to get latest first
+    });
+    
+    let jar_path = jar_files[0].path();
+    add_log(format!("📋 Selected JAR: {:?}", jar_path.file_name().unwrap()));
+    Ok(jar_path)
+}
+
+// Normalize path to remove Windows UNC prefix
+fn normalize_path(path: &PathBuf) -> PathBuf {
+    if cfg!(windows) {
+        let path_str = path.to_string_lossy();
+        if path_str.starts_with(r"\\?\") {
+            PathBuf::from(&path_str[4..]) // Remove \\?\ prefix
+        } else {
+            path.clone()
+        }
+    } else {
+        path.clone()
+    }
+}
+
+// Create, configure and run the Java command to run Stirling-PDF JAR
+fn run_stirling_pdf_jar(app: &tauri::AppHandle, java_path: &PathBuf, jar_path: &PathBuf) -> Result<(), String> {
+    // Get platform-specific application data directory for Tauri mode
+    let app_data_dir = if cfg!(target_os = "macos") {
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
+        PathBuf::from(home).join("Library").join("Application Support").join("Stirling-PDF")
+    } else if cfg!(target_os = "windows") {
+        let appdata = std::env::var("APPDATA").unwrap_or_else(|_| std::env::temp_dir().to_string_lossy().to_string());
+        PathBuf::from(appdata).join("Stirling-PDF")
+    } else {
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
+        PathBuf::from(home).join(".config").join("Stirling-PDF")
+    };
+    
+    // Create subdirectories for different purposes
+    let config_dir = app_data_dir.join("configs");
+    let log_dir = app_data_dir.join("logs");
+    let work_dir = app_data_dir.join("workspace");
+    
+    // Create all necessary directories
+    std::fs::create_dir_all(&app_data_dir).ok();
+    std::fs::create_dir_all(&log_dir).ok();
+    std::fs::create_dir_all(&work_dir).ok();
+    std::fs::create_dir_all(&config_dir).ok();
+    
+    add_log(format!("📁 App data directory: {}", app_data_dir.display()));
+    add_log(format!("📁 Log directory: {}", log_dir.display()));
+    add_log(format!("📁 Working directory: {}", work_dir.display()));
+    add_log(format!("📁 Config directory: {}", config_dir.display()));
+    
+    // Define all Java options with Tauri-specific paths
+    let log_path_option = format!("-Dlogging.file.path={}", log_dir.display());
+
+    let java_options = vec![
+        "-Xmx2g",
+        "-DBROWSER_OPEN=false",
+        "-DSTIRLING_PDF_DESKTOP_UI=false",
+        "-DSTIRLING_PDF_TAURI_MODE=true",
+        &log_path_option,
+        "-Dlogging.file.name=stirling-pdf.log",
+        "-jar",
+        jar_path.to_str().unwrap()
+    ];
+    
+    // Log the equivalent command for external testing
+    let java_command = format!(
+        "TAURI_PARENT_PID={} \"{}\" {}",
+        std::process::id(),
+        java_path.display(),
+        java_options.join(" ")
+    );
+    add_log(format!("🔧 Equivalent command: {}", java_command));
+    add_log(format!("📁 Backend logs will be in: {}", log_dir.display()));
+    
+    // Additional macOS-specific checks
+    if cfg!(target_os = "macos") {
+        // Check if java executable has execute permissions
+        if let Ok(metadata) = std::fs::metadata(java_path) {
+            let permissions = metadata.permissions();
+            add_log(format!("🔍 Java executable permissions: {:?}", permissions));
+            
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                let mode = permissions.mode();
+                add_log(format!("🔍 Java executable mode: 0o{:o}", mode));
+                if mode & 0o111 == 0 {
+                    add_log("⚠️ Java executable may not have execute permissions".to_string());
+                }
+            }
+        }
+        
+        // Check if we can read the JAR file
+        if let Ok(metadata) = std::fs::metadata(jar_path) {
+            add_log(format!("📦 JAR file size: {} bytes", metadata.len()));
+        } else {
+            add_log("⚠️ Cannot read JAR file metadata".to_string());
+        }
+    }
+    
+    let sidecar_command = app
+        .shell()
+        .command(java_path.to_str().unwrap())
+        .args(java_options)
+        .current_dir(&work_dir)  // Set working directory to writable location
+        .env("TAURI_PARENT_PID", std::process::id().to_string())
+        .env("STIRLING_PDF_CONFIG_DIR", config_dir.to_str().unwrap())
+        .env("STIRLING_PDF_LOG_DIR", log_dir.to_str().unwrap())
+        .env("STIRLING_PDF_WORK_DIR", work_dir.to_str().unwrap());
+    
+    add_log("⚙️ Starting backend with bundled JRE...".to_string());
+    
+    let (rx, child) = sidecar_command
+        .spawn()
+        .map_err(|e| {
+            let error_msg = format!("❌ Failed to spawn sidecar: {}", e);
+            add_log(error_msg.clone());
+            error_msg
+        })?;
+    
+    // Store the process handle
+    {
+        let mut process_guard = BACKEND_PROCESS.lock().unwrap();
+        *process_guard = Some(child);
+    }
+    
+    add_log("✅ Backend started with bundled JRE, monitoring output...".to_string());
+    
+    // Start monitoring output
+    monitor_backend_output(rx);
+    
+    Ok(())
+}
+
+// Monitor backend output in a separate task
+fn monitor_backend_output(mut rx: tauri::async_runtime::Receiver<tauri_plugin_shell::process::CommandEvent>) {
+    tokio::spawn(async move {
+        let mut _startup_detected = false;
+        let mut error_count = 0;
+        
+        while let Some(event) = rx.recv().await {
+            match event {
+                tauri_plugin_shell::process::CommandEvent::Stdout(output) => {
+                    let output_str = String::from_utf8_lossy(&output);
+                    add_log(format!("📤 Backend: {}", output_str));
+                    
+                    // Look for startup indicators
+                    if output_str.contains("Started SPDFApplication") || 
+                       output_str.contains("Navigate to "){
+                        _startup_detected = true;
+                        add_log(format!("🎉 Backend startup detected: {}", output_str));
+                    }
+                    
+                    // Look for port binding
+                    if output_str.contains("8080") {
+                        add_log(format!("🔌 Port 8080 related output: {}", output_str));
+                    }
+                }
+                tauri_plugin_shell::process::CommandEvent::Stderr(output) => {
+                    let output_str = String::from_utf8_lossy(&output);
+                    add_log(format!("📥 Backend Error: {}", output_str));
+                    
+                    // Look for error indicators
+                    if output_str.contains("ERROR") || output_str.contains("Exception") || output_str.contains("FATAL") {
+                        error_count += 1;
+                        add_log(format!("⚠️ Backend error #{}: {}", error_count, output_str));
+                    }
+                    
+                    // Look for specific common issues
+                    if output_str.contains("Address already in use") {
+                        add_log("🚨 CRITICAL: Port 8080 is already in use by another process!".to_string());
+                    }
+                    if output_str.contains("java.lang.ClassNotFoundException") {
+                        add_log("🚨 CRITICAL: Missing Java dependencies!".to_string());
+                    }
+                    if output_str.contains("java.io.FileNotFoundException") {
+                        add_log("🚨 CRITICAL: Required file not found!".to_string());
+                    }
+                }
+                tauri_plugin_shell::process::CommandEvent::Error(error) => {
+                    add_log(format!("❌ Backend process error: {}", error));
+                }
+                tauri_plugin_shell::process::CommandEvent::Terminated(payload) => {
+                    add_log(format!("💀 Backend terminated with code: {:?}", payload.code));
+                    if let Some(code) = payload.code {
+                        match code {
+                            0 => println!("✅ Process terminated normally"),
+                            1 => println!("❌ Process terminated with generic error"),
+                            2 => println!("❌ Process terminated due to misuse"),
+                            126 => println!("❌ Command invoked cannot execute"),
+                            127 => println!("❌ Command not found"),
+                            128 => println!("❌ Invalid exit argument"),
+                            130 => println!("❌ Process terminated by Ctrl+C"),
+                            _ => println!("❌ Process terminated with code: {}", code),
+                        }
+                    }
+                    // Clear the stored process handle
+                    let mut process_guard = BACKEND_PROCESS.lock().unwrap();
+                    *process_guard = None;
+                }
+                _ => {
+                    println!("🔍 Unknown command event: {:?}", event);
+                }
+            }
+        }
+        
+        if error_count > 0 {
+            println!("⚠️ Backend process ended with {} errors detected", error_count);
+        }
+    });
+}
+
+// Command to start the backend with bundled JRE
+#[tauri::command]
+pub async fn start_backend(app: tauri::AppHandle) -> Result<String, String> {
+    add_log("🚀 start_backend() called - Attempting to start backend with bundled JRE...".to_string());
+    
+    // Check if backend is already running or starting
+    if let Err(msg) = check_backend_status() {
+        return Ok(msg);
+    }
+    
+    // Use Tauri's resource API to find the bundled JRE and JAR
+    let resource_dir = app.path().resource_dir().map_err(|e| {
+        let error_msg = format!("❌ Failed to get resource directory: {}", e);
+        add_log(error_msg.clone());
+        reset_starting_flag();
+        error_msg
+    })?;
+    
+    add_log(format!("🔍 Resource directory: {:?}", resource_dir));
+    
+    // Find the bundled JRE
+    let java_executable = find_bundled_jre(&resource_dir).map_err(|e| {
+        reset_starting_flag();
+        e
+    })?;
+    
+    // Find the Stirling-PDF JAR
+    let jar_path = find_stirling_jar(&resource_dir).map_err(|e| {
+        reset_starting_flag();
+        e
+    })?;
+    
+    // Normalize the paths to remove Windows UNC prefix
+    let normalized_java_path = normalize_path(&java_executable);
+    let normalized_jar_path = normalize_path(&jar_path);
+    
+    add_log(format!("📦 Found JAR file: {:?}", jar_path));
+    add_log(format!("📦 Normalized JAR path: {:?}", normalized_jar_path));
+    add_log(format!("📦 Normalized Java path: {:?}", normalized_java_path));
+    
+    // Create and start the Java command
+    run_stirling_pdf_jar(&app, &normalized_java_path, &normalized_jar_path).map_err(|e| {
+        reset_starting_flag();
+        e
+    })?;
+    
+    // Wait for the backend to start
+    println!("⏳ Waiting for backend startup...");
+    tokio::time::sleep(std::time::Duration::from_millis(10000)).await;
+    
+    // Reset the starting flag since startup is complete
+    reset_starting_flag();
+    add_log("✅ Backend startup sequence completed, starting flag cleared".to_string());
+    
+    Ok("Backend startup initiated successfully with bundled JRE".to_string())
+}
+
+// Cleanup function to stop backend on app exit
+pub fn cleanup_backend() {
+    let mut process_guard = BACKEND_PROCESS.lock().unwrap();
+    if let Some(child) = process_guard.take() {
+        let pid = child.pid();
+        add_log(format!("🧹 App shutting down, cleaning up backend process (PID: {})", pid));
+        
+        match child.kill() {
+            Ok(_) => {
+                add_log(format!("✅ Backend process (PID: {}) terminated during cleanup", pid));
+            }
+            Err(e) => {
+                add_log(format!("❌ Failed to terminate backend process during cleanup: {}", e));
+                println!("❌ Failed to terminate backend process during cleanup: {}", e);
+            }
+        }
+    }
+}
@@ -0,0 +1,48 @@
+use crate::utils::add_log;
+use std::sync::Mutex;
+
+// Store the opened file path globally
+static OPENED_FILE: Mutex<Option<String>> = Mutex::new(None);
+
+// Set the opened file path (called by macOS file open events)
+pub fn set_opened_file(file_path: String) {
+    let mut opened_file = OPENED_FILE.lock().unwrap();
+    *opened_file = Some(file_path.clone());
+    add_log(format!("📂 File opened via file open event: {}", file_path));
+}
+
+// Command to get opened file path (if app was launched with a file)
+#[tauri::command]
+pub async fn get_opened_file() -> Result<Option<String>, String> {
+    // First check if we have a file from macOS file open events
+    {
+        let opened_file = OPENED_FILE.lock().unwrap();
+        if let Some(ref file_path) = *opened_file {
+            add_log(format!("📂 Returning stored opened file: {}", file_path));
+            return Ok(Some(file_path.clone()));
+        }
+    }
+    
+    // Fallback to command line arguments (Windows/Linux)
+    let args: Vec<String> = std::env::args().collect();
+    
+    // Look for a PDF file argument (skip the first arg which is the executable)
+    for arg in args.iter().skip(1) {
+        if arg.ends_with(".pdf") && std::path::Path::new(arg).exists() {
+            add_log(format!("📂 PDF file opened via command line: {}", arg));
+            return Ok(Some(arg.clone()));
+        }
+    }
+    
+    Ok(None)
+}
+
+// Command to clear the opened file (after processing)
+#[tauri::command]
+pub async fn clear_opened_file() -> Result<(), String> {
+    let mut opened_file = OPENED_FILE.lock().unwrap();
+    *opened_file = None;
+    add_log("📂 Cleared opened file".to_string());
+    Ok(())
+}
+
@@ -0,0 +1,36 @@
+// Command to check if backend is healthy
+#[tauri::command]
+pub async fn check_backend_health() -> Result<bool, String> {
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(5))
+        .build()
+        .map_err(|e| format!("Failed to create HTTP client: {}", e))?;
+    
+    match client.get("http://localhost:8080/api/v1/info/status").send().await {
+        Ok(response) => {
+            let status = response.status();
+            if status.is_success() {
+                match response.text().await {
+                    Ok(_body) => {
+                        println!("✅ Backend health check successful");
+                        Ok(true)
+                    }
+                    Err(e) => {
+                        println!("⚠️ Failed to read health response: {}", e);
+                        Ok(false)
+                    }
+                }
+            } else {
+                println!("⚠️ Health check failed with status: {}", status);
+                Ok(false)
+            }
+        }
+        Err(e) => {
+            // Only log connection errors if they're not the common "connection refused" during startup
+            if !e.to_string().contains("connection refused") && !e.to_string().contains("No connection could be made") {
+                println!("❌ Health check error: {}", e);
+            }
+            Ok(false)
+        }
+    }
+}
@@ -0,0 +1,7 @@
+pub mod backend;
+pub mod health;
+pub mod files;
+
+pub use backend::{start_backend, cleanup_backend};
+pub use health::check_backend_health;
+pub use files::{get_opened_file, clear_opened_file, set_opened_file};
@@ -0,0 +1,189 @@
+/// Multi-platform file opening handler
+/// 
+/// This module provides unified file opening support across platforms:
+/// - macOS: Uses native NSApplication delegate (proper Apple Events)
+/// - Windows/Linux: Uses command line arguments (fallback approach)
+/// - All platforms: Runtime event handling via Tauri events
+
+use crate::utils::add_log;
+use crate::commands::set_opened_file;
+use tauri::AppHandle;
+
+
+/// Initialize file handling for the current platform
+pub fn initialize_file_handler(app: &AppHandle<tauri::Wry>) {
+    add_log("🔧 Initializing file handler...".to_string());
+    
+    // Platform-specific initialization
+    #[cfg(target_os = "macos")]
+    {
+        add_log("🍎 Using macOS native file handler".to_string());
+        macos_native::register_open_file_handler(app);
+    }
+    
+    #[cfg(not(target_os = "macos"))]
+    {
+        add_log("🖥️ Using command line argument file handler".to_string());
+        let _ = app; // Suppress unused variable warning
+    }
+    
+    // Universal: Check command line arguments (works on all platforms)
+    check_command_line_args();
+}
+
+/// Early initialization for macOS delegate registration
+pub fn early_init() {
+    #[cfg(target_os = "macos")]
+    {
+        add_log("🔄 Early macOS initialization...".to_string());
+        macos_native::register_delegate_early();
+    }
+}
+
+/// Check command line arguments for file paths (universal fallback)
+fn check_command_line_args() {
+    let args: Vec<String> = std::env::args().collect();
+    add_log(format!("🔍 DEBUG: All command line args: {:?}", args));
+    
+    // Check command line arguments for file opening
+    for (i, arg) in args.iter().enumerate() {
+        add_log(format!("🔍 DEBUG: Arg {}: {}", i, arg));
+        if i > 0 && arg.ends_with(".pdf") && std::path::Path::new(arg).exists() {
+            add_log(format!("📂 File argument detected: {}", arg));
+            set_opened_file(arg.clone());
+            break; // Only handle the first PDF file
+        }
+    }
+}
+
+/// Handle runtime file open events (for future single-instance support)
+#[allow(dead_code)]
+pub fn handle_runtime_file_open(file_path: String) {
+    if file_path.ends_with(".pdf") && std::path::Path::new(&file_path).exists() {
+        add_log(format!("📂 Runtime file open: {}", file_path));
+        set_opened_file(file_path);
+    }
+}
+
+#[cfg(target_os = "macos")]
+mod macos_native {
+    use objc::{class, msg_send, sel, sel_impl};
+    use objc::runtime::{Class, Object, Sel};
+    use cocoa::appkit::NSApplication;
+    use cocoa::base::{id, nil};
+    use once_cell::sync::Lazy;
+    use std::sync::Mutex;
+    use tauri::{AppHandle, Emitter};
+    
+    use crate::utils::add_log;
+    use crate::commands::set_opened_file;
+    
+    // Static app handle storage
+    static APP_HANDLE: Lazy<Mutex<Option<AppHandle<tauri::Wry>>>> = Lazy::new(|| Mutex::new(None));
+    
+    // Store files opened during launch
+    static LAUNCH_FILES: Lazy<Mutex<Vec<String>>> = Lazy::new(|| Mutex::new(Vec::new()));
+    
+    
+    extern "C" fn open_files(_self: &Object, _cmd: Sel, _sender: id, filenames: id) {
+        unsafe {
+            add_log(format!("📂 macOS native openFiles event called"));
+            
+            // filenames is an NSArray of NSString objects
+            let count: usize = msg_send![filenames, count];
+            add_log(format!("📂 Number of files to open: {}", count));
+            
+            for i in 0..count {
+                let filename: id = msg_send![filenames, objectAtIndex: i];
+                let cstr = {
+                    let bytes: *const std::os::raw::c_char = msg_send![filename, UTF8String];
+                    std::ffi::CStr::from_ptr(bytes)
+                };
+                
+                if let Ok(path) = cstr.to_str() {
+                    add_log(format!("📂 macOS file open: {}", path));
+                    if path.ends_with(".pdf") {
+                        // Always set the opened file for command-line interface
+                        set_opened_file(path.to_string());
+                        
+                        if let Some(app) = APP_HANDLE.lock().unwrap().as_ref() {
+                            // App is running, emit event immediately
+                            add_log(format!("✅ App running, emitting file event: {}", path));
+                            let _ = app.emit("macos://open-file", path.to_string());
+                        } else {
+                            // App not ready yet, store for later processing
+                            add_log(format!("🚀 App not ready, storing file for later: {}", path));
+                            LAUNCH_FILES.lock().unwrap().push(path.to_string());
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    // Register the delegate immediately when the module loads
+    pub fn register_delegate_early() {
+        add_log("🔧 Registering macOS delegate early...".to_string());
+        
+        unsafe {
+            let ns_app = NSApplication::sharedApplication(nil);
+            
+            // Check if there's already a delegate
+            let existing_delegate: id = msg_send![ns_app, delegate];
+            if existing_delegate != nil {
+                add_log("⚠️ Tauri already has an NSApplication delegate, trying to extend it...".to_string());
+                
+                // Try to add our method to the existing delegate's class
+                let delegate_class: id = msg_send![existing_delegate, class];
+                let class_name: *const std::os::raw::c_char = msg_send![delegate_class, name];
+                let class_name_str = std::ffi::CStr::from_ptr(class_name).to_string_lossy();
+                add_log(format!("🔍 Existing delegate class: {}", class_name_str));
+                
+                // This approach won't work with existing classes, so let's try a different method
+                // We'll use method swizzling or create a new delegate that forwards to the old one
+                add_log("🔄 Will try alternative approach...".to_string());
+            }
+            
+            let delegate_class = Class::get("StirlingAppDelegate").unwrap_or_else(|| {
+                let superclass = class!(NSObject);
+                let mut decl = objc::declare::ClassDecl::new("StirlingAppDelegate", superclass).unwrap();
+                
+                // Add file opening delegate method (modern plural version)
+                decl.add_method(
+                    sel!(application:openFiles:),
+                    open_files as extern "C" fn(&Object, Sel, id, id)
+                );
+                
+                decl.register()
+            });
+    
+            let delegate: id = msg_send![delegate_class, new];
+            let _: () = msg_send![ns_app, setDelegate:delegate];
+        }
+        
+        add_log("✅ macOS delegate registered early".to_string());
+    }
+    
+    pub fn register_open_file_handler(app: &AppHandle<tauri::Wry>) {
+        add_log("🔧 Connecting app handle to file handler...".to_string());
+        
+        // Store the app handle 
+        *APP_HANDLE.lock().unwrap() = Some(app.clone());
+        
+        // Process any files that were opened during launch
+        let launch_files = {
+            let mut files = LAUNCH_FILES.lock().unwrap();
+            let result = files.clone();
+            files.clear();
+            result
+        };
+        
+        for file_path in launch_files {
+            add_log(format!("📂 Processing stored launch file: {}", file_path));
+            set_opened_file(file_path.clone());
+            let _ = app.emit("macos://open-file", file_path);
+        }
+        
+        add_log("✅ macOS file handler connected successfully".to_string());
+    }
+}
@@ -0,0 +1,65 @@
+use tauri::{RunEvent, WindowEvent, Emitter};
+
+mod utils;
+mod commands;
+mod file_handler;
+
+use commands::{start_backend, check_backend_health, get_opened_file, clear_opened_file, cleanup_backend, set_opened_file};
+use utils::{add_log, get_tauri_logs};
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+  // Initialize file handler early for macOS
+  file_handler::early_init();
+  
+  tauri::Builder::default()
+    .plugin(tauri_plugin_shell::init())
+    .plugin(tauri_plugin_fs::init())
+    .setup(|app| {
+      add_log("🚀 Tauri app setup started".to_string());
+      
+      // Initialize platform-specific file handler
+      file_handler::initialize_file_handler(&app.handle());
+      
+      add_log("🔍 DEBUG: Setup completed".to_string());
+      Ok(())
+    })
+    .invoke_handler(tauri::generate_handler![start_backend, check_backend_health, get_opened_file, clear_opened_file, get_tauri_logs])
+    .build(tauri::generate_context!())
+    .expect("error while building tauri application")
+    .run(|app_handle, event| {
+      match event {
+        RunEvent::ExitRequested { .. } => {
+          add_log("🔄 App exit requested, cleaning up...".to_string());
+          cleanup_backend();
+          // Use Tauri's built-in cleanup
+          app_handle.cleanup_before_exit();
+        }
+        RunEvent::WindowEvent { event: WindowEvent::CloseRequested {.. }, .. } => {
+          add_log("🔄 Window close requested, cleaning up...".to_string());
+          cleanup_backend();
+          // Allow the window to close
+        }
+        #[cfg(target_os = "macos")]
+        RunEvent::Opened { urls } => {
+          add_log(format!("📂 Tauri file opened event: {:?}", urls));
+          for url in urls {
+            let url_str = url.as_str();
+            if url_str.starts_with("file://") {
+              let file_path = url_str.strip_prefix("file://").unwrap_or(url_str);
+              if file_path.ends_with(".pdf") {
+                add_log(format!("📂 Processing opened PDF: {}", file_path));
+                set_opened_file(file_path.to_string());
+                let _ = app_handle.emit("macos://open-file", file_path.to_string());
+              }
+            }
+          }
+        }
+        _ => {
+          // Only log unhandled events in debug mode to reduce noise
+          // #[cfg(debug_assertions)]
+          // add_log(format!("🔍 DEBUG: Unhandled event: {:?}", event));
+        }
+      }
+    });
+}
@@ -0,0 +1,6 @@
+// Prevents additional console window on Windows in release, DO NOT REMOVE!!
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+  app_lib::run();
+}
@@ -0,0 +1,90 @@
+use std::sync::Mutex;
+use std::collections::VecDeque;
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::path::PathBuf;
+
+// Store backend logs globally
+static BACKEND_LOGS: Mutex<VecDeque<String>> = Mutex::new(VecDeque::new());
+
+// Get platform-specific log directory
+fn get_log_directory() -> PathBuf {
+    if cfg!(target_os = "macos") {
+        // macOS: ~/Library/Logs/Stirling-PDF
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
+        PathBuf::from(home).join("Library").join("Logs").join("Stirling-PDF")
+    } else if cfg!(target_os = "windows") {
+        // Windows: %APPDATA%\Stirling-PDF\logs
+        let appdata = std::env::var("APPDATA").unwrap_or_else(|_| std::env::temp_dir().to_string_lossy().to_string());
+        PathBuf::from(appdata).join("Stirling-PDF").join("logs")
+    } else {
+        // Linux: ~/.config/Stirling-PDF/logs
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
+        PathBuf::from(home).join(".config").join("Stirling-PDF").join("logs")
+    }
+}
+
+// Helper function to add log entry
+pub fn add_log(message: String) {
+    let timestamp = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_secs();
+    
+    let log_entry = format!("{}: {}", timestamp, message);
+    
+    // Add to memory logs
+    {
+        let mut logs = BACKEND_LOGS.lock().unwrap();
+        logs.push_back(log_entry.clone());
+        // Keep only last 100 log entries
+        if logs.len() > 100 {
+            logs.pop_front();
+        }
+    }
+    
+    // Write to file
+    write_to_log_file(&log_entry);
+    
+    // Remove trailing newline if present
+    let clean_message = message.trim_end_matches('\n').to_string();
+    println!("{}", clean_message); // Also print to console
+}
+
+// Write log entry to file
+fn write_to_log_file(log_entry: &str) {
+    let log_dir = get_log_directory();
+    if let Err(e) = std::fs::create_dir_all(&log_dir) {
+        eprintln!("Failed to create log directory: {}", e);
+        return;
+    }
+    
+    let log_file = log_dir.join("tauri-backend.log");
+    
+    match OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&log_file)
+    {
+        Ok(mut file) => {
+            if let Err(e) = writeln!(file, "{}", log_entry) {
+                eprintln!("Failed to write to log file: {}", e);
+            }
+        }
+        Err(e) => {
+            eprintln!("Failed to open log file {:?}: {}", log_file, e);
+        }
+    }
+}
+
+// Get current logs for debugging
+pub fn get_logs() -> Vec<String> {
+    let logs = BACKEND_LOGS.lock().unwrap();
+    logs.iter().cloned().collect()
+}
+
+// Command to get logs from frontend
+#[tauri::command]
+pub async fn get_tauri_logs() -> Result<Vec<String>, String> {
+    Ok(get_logs())
+}
@@ -0,0 +1,3 @@
+pub mod logging;
+
+pub use logging::{add_log, get_tauri_logs};
@@ -0,0 +1,14 @@
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Stirling-PDF
+Comment=Locally hosted web application that allows you to perform various operations on PDF files
+Icon={{icon}}
+Terminal=false
+MimeType=application/pdf;
+Categories=Office;Graphics;Utility;
+Actions=open-file;
+
+[Desktop Action open-file]
+Name=Open PDF File
+Exec=/usr/bin/stirling-pdf %F
@@ -0,0 +1,63 @@
+{
+  "$schema": "../node_modules/@tauri-apps/cli/config.schema.json",
+  "productName": "Stirling-PDF",
+  "version": "2.0.0",
+  "identifier": "stirling.pdf.dev",
+  "build": {
+    "frontendDist": "../dist",
+    "devUrl": "http://localhost:5173",
+    "beforeDevCommand": "npm run dev -- --mode desktop",
+    "beforeBuildCommand": "npm run build -- --mode desktop"
+  },
+  "app": {
+    "windows": [
+      {
+        "title": "Stirling-PDF",
+        "width": 1280,
+        "height": 800,
+        "resizable": true,
+        "fullscreen": false
+      }
+    ]
+  },
+  "bundle": {
+    "active": true,
+    "targets": ["deb", "rpm", "dmg", "msi"],
+    "icon": [
+      "icons/icon.png",
+      "icons/icon.icns",
+      "icons/icon.ico",
+      "icons/16x16.png",
+      "icons/32x32.png",
+      "icons/64x64.png",
+      "icons/128x128.png",
+      "icons/192x192.png"
+    ],
+    "resources": [
+      "libs/*.jar",
+      "runtime/jre/**/*"
+    ],
+    "fileAssociations": [
+      {
+        "ext": ["pdf"],
+        "name": "PDF Document",
+        "description": "Open PDF files with Stirling-PDF",
+        "role": "Editor",
+        "mimeType": "application/pdf"
+      }
+    ],
+    "linux": {
+      "deb": {
+        "desktopTemplate": "stirling-pdf.desktop"
+      }
+    }
+  },
+  "plugins": {
+    "shell": {
+      "open": true
+    },
+    "fs": {
+      "requireLiteralLeadingDot": false
+    }
+  }
+}
@@ -0,0 +1,7 @@
+interface RightRailFooterExtensionsProps {
+  className?: string;
+}
+
+export function RightRailFooterExtensions(_props: RightRailFooterExtensionsProps) {
+  return null;
+}
@@ -13,6 +13,7 @@ import { Tooltip } from '@app/components/shared/Tooltip';
 import { ViewerContext } from '@app/contexts/ViewerContext';
 import { useSignature } from '@app/contexts/SignatureContext';
 import LocalIcon from '@app/components/shared/LocalIcon';
+import { RightRailFooterExtensions } from '@app/components/rightRail/RightRailFooterExtensions';

 import { useSidebarContext } from '@app/contexts/SidebarContext';
 import { RightRailButtonConfig, RightRailRenderContext, RightRailSection } from '@app/types/rightRail';
@@ -224,6 +225,8 @@ export default function RightRail() {
        </div>

        <div className="right-rail-spacer" />
+
+        <RightRailFooterExtensions className="right-rail-footer" />
      </div>
    </div>
  );
@@ -17,6 +17,9 @@
  align-items: center;
  gap: 0.75rem;
  padding: 1rem 0.5rem;
+  width: 100%;
+  height: 100%;
+  flex: 1;
 }

 .right-rail-section {
@@ -20,14 +20,21 @@ import { useFilesModalContext } from "@app/contexts/FilesModalContext";
 import AppConfigModal from "@app/components/shared/AppConfigModal";
 import ToolPanelModePrompt from "@app/components/tools/ToolPanelModePrompt";
 import AdminAnalyticsChoiceModal from "@app/components/shared/AdminAnalyticsChoiceModal";
+import { useHomePageExtensions } from "@app/pages/useHomePageExtensions";

 import "@app/pages/HomePage.css";

 type MobileView = "tools" | "workbench";

+interface HomePageProps {
+  openedFile?: File | null;
+}

-export default function HomePage() {
+export default function HomePage({ openedFile }: HomePageProps = {}) {
  const { t } = useTranslation();
+
+  // Extension hook for desktop-specific behavior (e.g., file opening)
+  useHomePageExtensions(openedFile);
  const {
    sidebarRefs,
  } = useSidebarContext();
@@ -0,0 +1,10 @@
+import { useEffect } from 'react';
+
+/**
+ * Extension point for HomePage behaviour.
+ * Core version does nothing.
+ */
+export function useHomePageExtensions(_openedFile?: File | null) {
+  useEffect(() => {
+  }, [_openedFile]);
+}
@@ -1,10 +1,11 @@
 import axios from 'axios';
 import { handleHttpError } from '@app/services/httpErrorHandler';
 import { setupApiInterceptors } from '@app/services/apiClientSetup';
+import { getApiBaseUrl } from '@app/services/apiClientConfig';

 // Create axios instance with default config
 const apiClient = axios.create({
-  baseURL: import.meta.env.VITE_API_BASE_URL || '/',
+  baseURL: getApiBaseUrl(),
  responseType: 'json',
 });

@@ -0,0 +1,7 @@
+/**
+ * Get the base URL for API requests.
+ * Core version uses simple environment variable.
+ */
+export function getApiBaseUrl(): string {
+  return import.meta.env.VITE_API_BASE_URL || '/';
+}
@@ -0,0 +1,234 @@
+import { createContext, useContext, useEffect, useState, ReactNode, useCallback } from 'react';
+import apiClient from '@app/services/apiClient';
+import { springAuth } from '@app/auth/springAuthClient';
+import type { Session, User, AuthError, AuthChangeEvent } from '@app/auth/springAuthClient';
+
+/**
+ * Auth Context Type
+ * Simplified version without SaaS-specific features (credits, subscriptions)
+ */
+interface AuthContextType {
+  session: Session | null;
+  user: User | null;
+  loading: boolean;
+  error: AuthError | null;
+  signOut: () => Promise<void>;
+  refreshSession: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextType>({
+  session: null,
+  user: null,
+  loading: true,
+  error: null,
+  signOut: async () => {},
+  refreshSession: async () => {},
+});
+
+/**
+ * Auth Provider Component
+ *
+ * Manages authentication state and provides it to the entire app.
+ * Integrates with Spring Security + JWT backend.
+ */
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const [session, setSession] = useState<Session | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<AuthError | null>(null);
+
+  /**
+   * Refresh current session
+   */
+  const refreshSession = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError(null);
+      console.debug('[Auth] Refreshing session...');
+
+      const { data, error } = await springAuth.refreshSession();
+
+      if (error) {
+        console.error('[Auth] Session refresh error:', error);
+        setError(error);
+        setSession(null);
+      } else {
+        console.debug('[Auth] Session refreshed successfully');
+        setSession(data.session);
+      }
+    } catch (err) {
+      console.error('[Auth] Unexpected error during session refresh:', err);
+      setError(err as AuthError);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  /**
+   * Sign out user
+   */
+  const signOut = useCallback(async () => {
+    try {
+      setError(null);
+      console.debug('[Auth] Signing out...');
+
+      const { error } = await springAuth.signOut();
+
+      if (error) {
+        console.error('[Auth] Sign out error:', error);
+        setError(error);
+      } else {
+        console.debug('[Auth] Signed out successfully');
+        setSession(null);
+      }
+    } catch (err) {
+      console.error('[Auth] Unexpected error during sign out:', err);
+      setError(err as AuthError);
+    }
+  }, []);
+
+  /**
+   * Initialize auth on mount
+   */
+  useEffect(() => {
+    let mounted = true;
+
+    const initializeAuth = async () => {
+      try {
+        console.debug('[Auth] Initializing auth...');
+
+        // First check if login is enabled
+        const configResponse = await apiClient.get('/api/v1/config/app-config');
+        if (configResponse.status === 200) {
+          const config = configResponse.data;
+
+          // If login is disabled, skip authentication entirely
+          if (config.enableLogin === false) {
+            console.debug('[Auth] Login disabled - skipping authentication');
+            if (mounted) {
+              setSession(null);
+              setLoading(false);
+            }
+            return;
+          }
+        }
+
+        // Login is enabled, proceed with normal auth check
+        const { data, error } = await springAuth.getSession();
+
+        if (!mounted) return;
+
+        if (error) {
+          console.error('[Auth] Initial session error:', error);
+          setError(error);
+        } else {
+          console.debug('[Auth] Initial session loaded:', {
+            hasSession: !!data.session,
+            userId: data.session?.user?.id,
+            email: data.session?.user?.email,
+          });
+          setSession(data.session);
+        }
+      } catch (err) {
+        console.error('[Auth] Unexpected error during auth initialization:', err);
+        if (mounted) {
+          setError(err as AuthError);
+        }
+      } finally {
+        if (mounted) {
+          setLoading(false);
+        }
+      }
+    };
+
+    initializeAuth();
+
+    // Subscribe to auth state changes
+    const { data: { subscription } } = springAuth.onAuthStateChange(
+      async (event: AuthChangeEvent, newSession: Session | null) => {
+        if (!mounted) return;
+
+        console.debug('[Auth] Auth state change:', {
+          event,
+          hasSession: !!newSession,
+          userId: newSession?.user?.id,
+          email: newSession?.user?.email,
+          timestamp: new Date().toISOString(),
+        });
+
+        // Schedule state update
+        setTimeout(() => {
+          if (mounted) {
+            setSession(newSession);
+            setError(null);
+
+            // Handle specific events
+            if (event === 'SIGNED_OUT') {
+              console.debug('[Auth] User signed out, clearing session');
+            } else if (event === 'SIGNED_IN') {
+              console.debug('[Auth] User signed in successfully');
+            } else if (event === 'TOKEN_REFRESHED') {
+              console.debug('[Auth] Token refreshed');
+            } else if (event === 'USER_UPDATED') {
+              console.debug('[Auth] User updated');
+            }
+          }
+        }, 0);
+      }
+    );
+
+    return () => {
+      mounted = false;
+      subscription.unsubscribe();
+    };
+  }, []);
+
+  const value: AuthContextType = {
+    session,
+    user: session?.user ?? null,
+    loading,
+    error,
+    signOut,
+    refreshSession,
+  };
+
+  return (
+    <AuthContext.Provider value={value}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+/**
+ * Hook to access auth context
+ * Must be used within AuthProvider
+ */
+export function useAuth() {
+  const context = useContext(AuthContext);
+
+  if (context === undefined) {
+    throw new Error('useAuth must be used within an AuthProvider');
+  }
+
+  return context;
+}
+
+/**
+ * Debug hook to expose auth state for debugging
+ * Can be used in development to monitor auth state
+ */
+export function useAuthDebug() {
+  const auth = useAuth();
+
+  useEffect(() => {
+    console.debug('[Auth Debug] Current auth state:', {
+      hasSession: !!auth.session,
+      hasUser: !!auth.user,
+      loading: auth.loading,
+      hasError: !!auth.error,
+      userId: auth.user?.id,
+      email: auth.user?.email,
+    });
+  }, [auth.session, auth.user, auth.loading, auth.error]);
+
+  return auth;
+}
@@ -0,0 +1,437 @@
+/**
+ * Spring Auth Client
+ *
+ * This client integrates with the Spring Security + JWT backend.
+ * - Uses localStorage for JWT storage (sent via Authorization header)
+ * - JWT validation handled server-side
+ * - No email confirmation flow (auto-confirmed on registration)
+ */
+
+import apiClient from '@app/services/apiClient';
+
+// Auth types
+export interface User {
+  id: string;
+  email: string;
+  username: string;
+  role: string;
+  enabled?: boolean;
+  is_anonymous?: boolean;
+  app_metadata?: Record<string, any>;
+}
+
+export interface Session {
+  user: User;
+  access_token: string;
+  expires_in: number;
+  expires_at?: number;
+}
+
+export interface AuthError {
+  message: string;
+  status?: number;
+}
+
+export interface AuthResponse {
+  user: User | null;
+  session: Session | null;
+  error: AuthError | null;
+}
+
+export type AuthChangeEvent =
+  | 'SIGNED_IN'
+  | 'SIGNED_OUT'
+  | 'TOKEN_REFRESHED'
+  | 'USER_UPDATED';
+
+type AuthChangeCallback = (event: AuthChangeEvent, session: Session | null) => void;
+
+class SpringAuthClient {
+  private listeners: AuthChangeCallback[] = [];
+  private sessionCheckInterval: NodeJS.Timeout | null = null;
+  private readonly SESSION_CHECK_INTERVAL = 60000; // 1 minute
+  private readonly TOKEN_REFRESH_THRESHOLD = 300000; // 5 minutes before expiry
+
+  constructor() {
+    // Start periodic session validation
+    this.startSessionMonitoring();
+  }
+
+  /**
+   * Helper to get CSRF token from cookie
+   */
+  private getCsrfToken(): string | null {
+    const cookies = document.cookie.split(';');
+    for (const cookie of cookies) {
+      const [name, value] = cookie.trim().split('=');
+      if (name === 'XSRF-TOKEN') {
+        return value;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get current session
+   * JWT is stored in localStorage and sent via Authorization header
+   */
+  async getSession(): Promise<{ data: { session: Session | null }; error: AuthError | null }> {
+    try {
+      // Get JWT from localStorage
+      const token = localStorage.getItem('stirling_jwt');
+
+      if (!token) {
+        console.debug('[SpringAuth] getSession: No JWT in localStorage');
+        return { data: { session: null }, error: null };
+      }
+
+      // Verify with backend
+      // Note: We pass the token explicitly here, overriding the interceptor's default
+      const response = await apiClient.get('/api/v1/auth/me', {
+        headers: {
+          'Authorization': `Bearer ${token}`,
+        },
+      });
+
+      const data = response.data;
+
+      // Create session object
+      const session: Session = {
+        user: data.user,
+        access_token: token,
+        expires_in: 3600,
+        expires_at: Date.now() + 3600 * 1000,
+      };
+
+      console.debug('[SpringAuth] getSession: Session retrieved successfully');
+      return { data: { session }, error: null };
+    } catch (error: any) {
+      console.error('[SpringAuth] getSession error:', error);
+
+      // If 401/403, token is invalid - clear it
+      if (error?.response?.status === 401 || error?.response?.status === 403) {
+        localStorage.removeItem('stirling_jwt');
+        console.debug('[SpringAuth] getSession: Not authenticated');
+        return { data: { session: null }, error: null };
+      }
+
+      // Clear potentially invalid token on other errors too
+      localStorage.removeItem('stirling_jwt');
+      return {
+        data: { session: null },
+        error: { message: error?.response?.data?.message || error?.message || 'Unknown error' },
+      };
+    }
+  }
+
+  /**
+   * Sign in with email and password
+   */
+  async signInWithPassword(credentials: {
+    email: string;
+    password: string;
+  }): Promise<AuthResponse> {
+    try {
+      const response = await apiClient.post('/api/v1/auth/login', {
+        username: credentials.email,
+        password: credentials.password
+      }, {
+        withCredentials: true, // Include cookies for CSRF
+      });
+
+      const data = response.data;
+      const token = data.session.access_token;
+
+      // Store JWT in localStorage
+      localStorage.setItem('stirling_jwt', token);
+      console.log('[SpringAuth] JWT stored in localStorage');
+
+      const session: Session = {
+        user: data.user,
+        access_token: token,
+        expires_in: data.session.expires_in,
+        expires_at: Date.now() + data.session.expires_in * 1000,
+      };
+
+      // Notify listeners
+      this.notifyListeners('SIGNED_IN', session);
+
+      return { user: data.user, session, error: null };
+    } catch (error: any) {
+      console.error('[SpringAuth] signInWithPassword error:', error);
+      const errorMessage = error?.response?.data?.error || error?.message || 'Login failed';
+      return {
+        user: null,
+        session: null,
+        error: { message: errorMessage },
+      };
+    }
+  }
+
+  /**
+   * Sign up new user
+   */
+  async signUp(credentials: {
+    email: string;
+    password: string;
+    options?: { data?: { full_name?: string }; emailRedirectTo?: string };
+  }): Promise<AuthResponse> {
+    try {
+      const response = await apiClient.post('/api/v1/user/register', {
+        username: credentials.email,
+        password: credentials.password,
+      }, {
+        withCredentials: true,
+      });
+
+      const data = response.data;
+
+      // Note: Spring backend auto-confirms users (no email verification)
+      // Return user but no session (user needs to login)
+      return { user: data.user, session: null, error: null };
+    } catch (error: any) {
+      console.error('[SpringAuth] signUp error:', error);
+      const errorMessage = error?.response?.data?.error || error?.message || 'Registration failed';
+      return {
+        user: null,
+        session: null,
+        error: { message: errorMessage },
+      };
+    }
+  }
+
+  /**
+   * Sign in with OAuth provider (GitHub, Google, etc.)
+   * Redirects to Spring OAuth2 authorization endpoint
+   */
+  async signInWithOAuth(params: {
+    provider: 'github' | 'google' | 'apple' | 'azure';
+    options?: { redirectTo?: string; queryParams?: Record<string, any> };
+  }): Promise<{ error: AuthError | null }> {
+    try {
+      const redirectUrl = `/oauth2/authorization/${params.provider}`;
+      console.log('[SpringAuth] Redirecting to OAuth:', redirectUrl);
+      window.location.assign(redirectUrl);
+      return { error: null };
+    } catch (error) {
+      return {
+        error: { message: error instanceof Error ? error.message : 'OAuth redirect failed' },
+      };
+    }
+  }
+
+  /**
+   * Send password reset email
+   * Not used in OSS version, but included for completeness
+   */
+  async resetPasswordForEmail(email: string): Promise<{ data: object; error: AuthError | null }> {
+    try {
+      await apiClient.post('/api/v1/auth/reset-password', {
+        email,
+      }, {
+        withCredentials: true,
+      });
+
+      return { data: {}, error: null };
+    } catch (error: any) {
+      console.error('[SpringAuth] resetPasswordForEmail error:', error);
+      return {
+        data: {},
+        error: {
+          message: error?.response?.data?.error || error?.message || 'Password reset failed',
+        },
+      };
+    }
+  }
+
+  /**
+   * Sign out user (invalidate session)
+   */
+  async signOut(): Promise<{ error: AuthError | null }> {
+    try {
+      const response = await apiClient.post('/api/v1/auth/logout', null, {
+        headers: {
+          'X-CSRF-TOKEN': this.getCsrfToken() || '',
+        },
+        withCredentials: true,
+      });
+
+      if (response.status === 200) {
+        console.debug('[SpringAuth] signOut: Success');
+      }
+
+      // Clean up local storage
+      localStorage.removeItem('stirling_jwt');
+
+      // Notify listeners
+      this.notifyListeners('SIGNED_OUT', null);
+
+      return { error: null };
+    } catch (error: any) {
+      console.error('[SpringAuth] signOut error:', error);
+      return {
+        error: {
+          message: error?.response?.data?.error || error?.message || 'Logout failed',
+        },
+      };
+    }
+  }
+
+  /**
+   * Refresh JWT token
+   */
+  async refreshSession(): Promise<{ data: { session: Session | null }; error: AuthError | null }> {
+    try {
+      const response = await apiClient.post('/api/v1/auth/refresh', null, {
+        headers: {
+          'X-CSRF-TOKEN': this.getCsrfToken() || '',
+        },
+        withCredentials: true,
+      });
+
+      const data = response.data;
+      const token = data.session.access_token;
+
+      // Update local storage with new token
+      localStorage.setItem('stirling_jwt', token);
+
+      const session: Session = {
+        user: data.user,
+        access_token: token,
+        expires_in: data.session.expires_in,
+        expires_at: Date.now() + data.session.expires_in * 1000,
+      };
+
+      // Notify listeners
+      this.notifyListeners('TOKEN_REFRESHED', session);
+
+      return { data: { session }, error: null };
+    } catch (error: any) {
+      console.error('[SpringAuth] refreshSession error:', error);
+      localStorage.removeItem('stirling_jwt');
+
+      // Handle different error statuses
+      if (error?.response?.status === 401 || error?.response?.status === 403) {
+        return { data: { session: null }, error: { message: 'Token refresh failed - please log in again' } };
+      }
+
+      return {
+        data: { session: null },
+        error: { message: error?.response?.data?.message || error?.message || 'Token refresh failed' },
+      };
+    }
+  }
+
+  /**
+   * Listen to auth state changes
+   */
+  onAuthStateChange(callback: AuthChangeCallback): { data: { subscription: { unsubscribe: () => void } } } {
+    this.listeners.push(callback);
+
+    return {
+      data: {
+        subscription: {
+          unsubscribe: () => {
+            this.listeners = this.listeners.filter((cb) => cb !== callback);
+          },
+        },
+      },
+    };
+  }
+
+  // Private helper methods
+
+  private notifyListeners(event: AuthChangeEvent, session: Session | null) {
+    // Use setTimeout to avoid calling callbacks synchronously
+    setTimeout(() => {
+      this.listeners.forEach((callback) => {
+        try {
+          callback(event, session);
+        } catch (error) {
+          console.error('[SpringAuth] Error in auth state change listener:', error);
+        }
+      });
+    }, 0);
+  }
+
+  private startSessionMonitoring() {
+    // Periodically check session validity
+    // Since we use HttpOnly cookies, we just need to check with the server
+    this.sessionCheckInterval = setInterval(async () => {
+      try {
+        // Try to get current session
+        const { data } = await this.getSession();
+
+        // If we have a session, proactively refresh if needed
+        // (The server will handle token expiry, but we can be proactive)
+        if (data.session) {
+          const timeUntilExpiry = (data.session.expires_at || 0) - Date.now();
+
+          // Refresh if token expires soon
+          if (timeUntilExpiry > 0 && timeUntilExpiry < this.TOKEN_REFRESH_THRESHOLD) {
+            console.log('[SpringAuth] Proactively refreshing token');
+            await this.refreshSession();
+          }
+        }
+      } catch (error) {
+        console.error('[SpringAuth] Session monitoring error:', error);
+      }
+    }, this.SESSION_CHECK_INTERVAL);
+  }
+
+  public destroy() {
+    if (this.sessionCheckInterval) {
+      clearInterval(this.sessionCheckInterval);
+    }
+  }
+}
+
+export const springAuth = new SpringAuthClient();
+
+/**
+ * Get current user
+ */
+export const getCurrentUser = async () => {
+  const { data } = await springAuth.getSession();
+  return data.session?.user || null;
+};
+
+/**
+ * Check if user is anonymous
+ */
+export const isUserAnonymous = (user: User | null) => {
+  return user?.is_anonymous === true;
+};
+
+/**
+ * Create an anonymous user object for use when login is disabled
+ * This provides a consistent User interface throughout the app
+ */
+export const createAnonymousUser = (): User => {
+  return {
+    id: 'anonymous',
+    email: 'anonymous@local',
+    username: 'Anonymous User',
+    role: 'USER',
+    enabled: true,
+    is_anonymous: true,
+    app_metadata: {
+      provider: 'anonymous',
+    },
+  };
+};
+
+/**
+ * Create an anonymous session for use when login is disabled
+ */
+export const createAnonymousSession = (): Session => {
+  return {
+    user: createAnonymousUser(),
+    access_token: '',
+    expires_in: Number.MAX_SAFE_INTEGER,
+    expires_at: Number.MAX_SAFE_INTEGER,
+  };
+};
+
+// Export auth client as default for convenience
+export default springAuth;
@@ -0,0 +1,80 @@
+import React, { useMemo, useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Box, Tooltip, useMantineTheme, useComputedColorScheme, rem } from '@mantine/core';
+import { useBackendHealth } from '@app/hooks/useBackendHealth';
+
+interface BackendHealthIndicatorProps {
+  className?: string;
+}
+
+export const BackendHealthIndicator: React.FC<BackendHealthIndicatorProps> = ({
+  className = ''
+}) => {
+  const { t } = useTranslation();
+  const theme = useMantineTheme();
+  const colorScheme = useComputedColorScheme('light');
+  const { isHealthy, isChecking, checkHealth } = useBackendHealth();
+
+  const label = useMemo(() => {
+    if (isChecking) {
+      return t('backendHealth.checking', 'Checking backend status...');
+    }
+
+    if (isHealthy) {
+      return t('backendHealth.online', 'Backend Online');
+    }
+
+    return t('backendHealth.offline', 'Backend Offline');
+  }, [isChecking, isHealthy, t]);
+
+  const dotColor = useMemo(() => {
+    if (isChecking) {
+      return theme.colors.yellow?.[5] ?? '#fcc419';
+    }
+    if (isHealthy) {
+      return theme.colors.green?.[5] ?? '#37b24d';
+    }
+    return theme.colors.red?.[6] ?? '#e03131';
+  }, [isChecking, isHealthy, theme.colors.green, theme.colors.red, theme.colors.yellow]);
+
+  const handleKeyDown = useCallback((event: React.KeyboardEvent<HTMLSpanElement>) => {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      checkHealth();
+    }
+  }, [checkHealth]);
+
+  return (
+    <Tooltip
+      label={label}
+      position="left"
+      offset={12}
+      withArrow
+      withinPortal
+      color={colorScheme === 'dark' ? undefined : 'dark'}
+    >
+      <Box
+        component="span"
+        className={className ? `${className}` : undefined}
+        role="status"
+        aria-live="polite"
+        aria-label={label}
+        tabIndex={0}
+        onClick={checkHealth}
+        onKeyDown={handleKeyDown}
+        style={{
+          width: rem(12),
+          height: rem(12),
+          borderRadius: '50%',
+          backgroundColor: dotColor,
+          boxShadow: colorScheme === 'dark'
+            ? '0 0 0 2px rgba(255, 255, 255, 0.18)'
+            : '0 0 0 2px rgba(0, 0, 0, 0.08)',
+          cursor: 'pointer',
+          display: 'inline-block',
+          outline: 'none',
+        }}
+      />
+    </Tooltip>
+  );
+};
@@ -0,0 +1,23 @@
+import { Box, rem } from '@mantine/core';
+import { BackendHealthIndicator } from '@app/components/BackendHealthIndicator';
+
+interface RightRailFooterExtensionsProps {
+  className?: string;
+}
+
+export function RightRailFooterExtensions({ className }: RightRailFooterExtensionsProps) {
+  return (
+    <Box
+      className={className}
+      style={{
+        width: '100%',
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'center',
+        paddingBottom: rem(12),
+      }}
+    >
+      <BackendHealthIndicator />
+    </Box>
+  );
+}
@@ -0,0 +1,135 @@
+import React, { createContext, useContext, useState, useEffect } from 'react';
+import apiClient from '@app/services/apiClient';
+
+// Retry configuration
+const MAX_RETRIES = 5;
+const INITIAL_DELAY = 1000; // 1 second
+
+/**
+ * Sleep utility for delays
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export interface AppConfig {
+  baseUrl?: string;
+  contextPath?: string;
+  serverPort?: number;
+  appNameNavbar?: string;
+  languages?: string[];
+  enableLogin?: boolean;
+  enableEmailInvites?: boolean;
+  isAdmin?: boolean;
+  enableAlphaFunctionality?: boolean;
+  enableAnalytics?: boolean | null;
+  enablePosthog?: boolean | null;
+  enableScarf?: boolean | null;
+  premiumEnabled?: boolean;
+  premiumKey?: string;
+  termsAndConditions?: string;
+  privacyPolicy?: string;
+  cookiePolicy?: string;
+  impressum?: string;
+  accessibilityStatement?: string;
+  runningProOrHigher?: boolean;
+  runningEE?: boolean;
+  license?: string;
+  SSOAutoLogin?: boolean;
+  serverCertificateEnabled?: boolean;
+  error?: string;
+}
+
+interface AppConfigContextValue {
+  config: AppConfig | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+}
+
+// Create context
+const AppConfigContext = createContext<AppConfigContextValue | undefined>(undefined);
+
+/**
+ * Provider component that fetches and provides app configuration
+ * Should be placed at the top level of the app, before any components that need config
+ */
+export const AppConfigProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [config, setConfig] = useState<AppConfig | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchConfig = async () => {
+    setLoading(true);
+    setError(null);
+
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        if (attempt > 0) {
+          const delay = INITIAL_DELAY * Math.pow(2, attempt - 1);
+          console.log(`[AppConfig] Retry attempt ${attempt}/${MAX_RETRIES} after ${delay}ms delay...`);
+          await sleep(delay);
+        } else {
+          console.log('[AppConfig] Fetching app config...');
+        }
+
+        const response = await apiClient.get<AppConfig>('/api/v1/config/app-config');
+
+        setConfig(response.data);
+        console.log('[AppConfig] Successfully fetched app config');
+        setLoading(false);
+        return; // Success - exit function
+      } catch (err: any) {
+        const status = err?.response?.status;
+
+        // Check if we should retry (network errors or 5xx errors)
+        const shouldRetry = (!status || status >= 500) && attempt < MAX_RETRIES;
+
+        if (shouldRetry) {
+          console.warn(`[AppConfig] Attempt ${attempt + 1} failed (status ${status || 'network error'}):`, err.message, '- will retry...');
+          continue;
+        }
+
+        // Final attempt failed or non-retryable error (4xx)
+        const errorMessage = err?.response?.data?.message || err?.message || 'Unknown error occurred';
+        setError(errorMessage);
+        console.error(`[AppConfig] Failed to fetch app config after ${attempt + 1} attempts:`, err);
+        break;
+      }
+    }
+
+    setLoading(false);
+  };
+
+  useEffect(() => {
+    fetchConfig();
+  }, []);
+
+  const value: AppConfigContextValue = {
+    config,
+    loading,
+    error,
+    refetch: fetchConfig,
+  };
+
+  return (
+    <AppConfigContext.Provider value={value}>
+      {children}
+    </AppConfigContext.Provider>
+  );
+};
+
+/**
+ * Hook to access application configuration
+ * Must be used within AppConfigProvider
+ */
+export function useAppConfig(): AppConfigContextValue {
+  const context = useContext(AppConfigContext);
+
+  if (context === undefined) {
+    throw new Error('useAppConfig must be used within AppConfigProvider');
+  }
+
+  return context;
+}
@@ -0,0 +1,91 @@
+import { useState, useEffect, useCallback } from 'react';
+import { tauriBackendService } from '@app/services/tauriBackendService';
+
+export type BackendStatus = 'starting' | 'healthy' | 'unhealthy' | 'stopped';
+
+interface BackendHealthState {
+  status: BackendStatus;
+  message?: string;
+  lastChecked?: number;
+  isChecking: boolean;
+  error: string | null;
+}
+
+/**
+ * Hook to monitor backend health status with retries
+ */
+export function useBackendHealth(pollingInterval = 5000) {
+  const [health, setHealth] = useState<BackendHealthState>({
+    status: tauriBackendService.isBackendRunning() ? 'healthy' : 'stopped',
+    isChecking: false,
+    error: null,
+  });
+
+  const checkHealth = useCallback(async () => {
+    setHealth((current) => ({
+      ...current,
+      status: current.status === 'healthy' ? 'healthy' : 'starting',
+      isChecking: true,
+      error: 'Backend starting up...',
+      lastChecked: Date.now(),
+    }));
+
+    try {
+      const isHealthy = await tauriBackendService.checkBackendHealth();
+
+      setHealth({
+        status: isHealthy ? 'healthy' : 'unhealthy',
+        lastChecked: Date.now(),
+        message: isHealthy ? 'Backend is healthy' : 'Backend is unavailable',
+        isChecking: false,
+        error: isHealthy ? null : 'Backend offline',
+      });
+
+      return isHealthy;
+    } catch (error) {
+      console.error('[BackendHealth] Health check failed:', error);
+      setHealth({
+        status: 'unhealthy',
+        lastChecked: Date.now(),
+        message: 'Backend is unavailable',
+        isChecking: false,
+        error: 'Backend offline',
+      });
+      return false;
+    }
+  }, []);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    const initialize = async () => {
+      setHealth((current) => ({
+        ...current,
+        status: tauriBackendService.isBackendRunning() ? 'starting' : 'stopped',
+        isChecking: true,
+        error: 'Backend starting up...',
+      }));
+
+      await checkHealth();
+      if (!isMounted) return;
+    };
+
+    initialize();
+
+    const interval = setInterval(() => {
+      if (!isMounted) return;
+      void checkHealth();
+    }, pollingInterval);
+
+    return () => {
+      isMounted = false;
+      clearInterval(interval);
+    };
+  }, [checkHealth, pollingInterval]);
+
+  return {
+    ...health,
+    isHealthy: health.status === 'healthy',
+    checkHealth,
+  };
+}
@@ -0,0 +1,40 @@
+import { useEffect } from 'react';
+import { useBackendHealth } from '@app/hooks/useBackendHealth';
+import { useEndpointConfig } from '@app/hooks/useEndpointConfig';
+import { tauriBackendService } from '@app/services/tauriBackendService';
+
+/**
+ * Hook to initialize backend and monitor health
+ */
+export function useBackendInitializer() {
+  const { status, checkHealth } = useBackendHealth();
+  const { backendUrl } = useEndpointConfig();
+
+  useEffect(() => {
+    // Skip if backend already running
+    if (tauriBackendService.isBackendRunning()) {
+      void checkHealth();
+      return;
+    }
+
+    const initializeBackend = async () => {
+      try {
+        console.log('[BackendInitializer] Starting backend...');
+        await tauriBackendService.startBackend(backendUrl);
+        console.log('[BackendInitializer] Backend started successfully');
+
+        // Begin health checks after a short delay
+        setTimeout(() => {
+          void checkHealth();
+        }, 500);
+      } catch (error) {
+        console.error('[BackendInitializer] Failed to start backend:', error);
+      }
+    };
+
+    // Only start backend if it's not already starting/healthy
+    if (status !== 'healthy' && status !== 'starting') {
+      void initializeBackend();
+    }
+  }, [status, backendUrl, checkHealth]);
+}
@@ -0,0 +1,126 @@
+import { useMemo, useState, useEffect } from 'react';
+import apiClient from '@app/services/apiClient';
+
+interface EndpointConfig {
+  backendUrl: string;
+}
+
+/**
+ * Desktop-specific endpoint checker that hits the backend directly via axios.
+ */
+export function useEndpointEnabled(endpoint: string): {
+  enabled: boolean | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+} {
+  const [enabled, setEnabled] = useState<boolean | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchEndpointStatus = async () => {
+    if (!endpoint) {
+      setEnabled(null);
+      setLoading(false);
+      return;
+    }
+
+    try {
+      setLoading(true);
+      setError(null);
+
+      const response = await apiClient.get<boolean>('/api/v1/config/endpoint-enabled', {
+        params: { endpoint },
+      });
+
+      setEnabled(response.data);
+    } catch (err: any) {
+      const message = err?.response?.data?.message || err?.message || 'Unknown error occurred';
+      setError(message);
+      setEnabled(null);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchEndpointStatus();
+  }, [endpoint]);
+
+  return {
+    enabled,
+    loading,
+    error,
+    refetch: fetchEndpointStatus,
+  };
+}
+
+export function useMultipleEndpointsEnabled(endpoints: string[]): {
+  endpointStatus: Record<string, boolean>;
+  loading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+} {
+  const [endpointStatus, setEndpointStatus] = useState<Record<string, boolean>>({});
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchAllEndpointStatuses = async () => {
+    if (!endpoints || endpoints.length === 0) {
+      setEndpointStatus({});
+      setLoading(false);
+      return;
+    }
+
+    try {
+      setLoading(true);
+      setError(null);
+
+      const endpointsParam = endpoints.join(',');
+
+      const response = await apiClient.get<Record<string, boolean>>('/api/v1/config/endpoints-enabled', {
+        params: { endpoints: endpointsParam },
+      });
+
+      setEndpointStatus(response.data);
+    } catch (err: any) {
+      const message = err?.response?.data?.message || err?.message || 'Unknown error occurred';
+      setError(message);
+
+      const fallbackStatus = endpoints.reduce((acc, endpointName) => {
+        acc[endpointName] = false;
+        return acc;
+      }, {} as Record<string, boolean>);
+      setEndpointStatus(fallbackStatus);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchAllEndpointStatuses();
+  }, [endpoints.join(',')]);
+
+  return {
+    endpointStatus,
+    loading,
+    error,
+    refetch: fetchAllEndpointStatuses,
+  };
+}
+
+/**
+ * Desktop override exposing the backend URL used by the embedded server.
+ */
+export function useEndpointConfig(): EndpointConfig {
+  const backendUrl = useMemo(() => {
+    const runtimeEnv = typeof process !== 'undefined' ? process.env : undefined;
+
+    return runtimeEnv?.STIRLING_BACKEND_URL
+      || import.meta.env.VITE_DESKTOP_BACKEND_URL
+      || import.meta.env.VITE_API_BASE_URL
+      || 'http://localhost:8080';
+  }, []);
+
+  return { backendUrl };
+}
@@ -0,0 +1,47 @@
+import { useState, useEffect } from 'react';
+import { fileOpenService } from '@app/services/fileOpenService';
+
+export function useOpenedFile() {
+  const [openedFilePath, setOpenedFilePath] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const checkForOpenedFile = async () => {
+      console.log('🔍 Checking for opened file...');
+      try {
+        const filePath = await fileOpenService.getOpenedFile();
+        console.log('🔍 fileOpenService.getOpenedFile() returned:', filePath);
+        
+        if (filePath) {
+          console.log('✅ App opened with file:', filePath);
+          setOpenedFilePath(filePath);
+          
+          // Clear the file from service state after consuming it
+          await fileOpenService.clearOpenedFile();
+        } else {
+          console.log('ℹ️ No file was opened with the app');
+        }
+
+      } catch (error) {
+        console.error('❌ Failed to check for opened file:', error);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    checkForOpenedFile();
+
+    // Listen for runtime file open events (abstracted through service)
+    const unlistenRuntimeEvents = fileOpenService.onFileOpened((filePath: string) => {
+      console.log('📂 Runtime file open event:', filePath);
+      setOpenedFilePath(filePath);
+    });
+
+    // Cleanup function
+    return () => {
+      unlistenRuntimeEvents();
+    };
+  }, []);
+
+  return { openedFilePath, loading };
+}
@@ -0,0 +1,26 @@
+import { useEffect } from 'react';
+
+/**
+ * Desktop override: Handle file opened with app (Tauri mode)
+ */
+export function useHomePageExtensions(openedFile?: File | null) {
+  useEffect(() => {
+    if (openedFile) {
+      const loadOpenedFile = async () => {
+        try {
+          // TAURI NOTE: Implement file opening logic here
+          // // Add to active files if not already present
+          // await addToActiveFiles(openedFile);
+
+          // // Switch to viewer mode to show the opened file
+          // setCurrentView('viewer');
+          // setReaderMode(true);
+        } catch (error) {
+          console.error('Failed to load opened file:', error);
+        }
+      };
+
+      loadOpenedFile();
+    }
+  }, [openedFile]);
+}
@@ -0,0 +1,95 @@
+import { Navigate, useLocation } from 'react-router-dom';
+import { useState, useEffect } from 'react';
+import { useOpenedFile } from '@app/hooks/useOpenedFile';
+import { useBackendInitializer } from '@app/hooks/useBackendInitializer';
+import { fileOpenService } from '@app/services/fileOpenService';
+import { useAuth } from '@app/auth/UseSession';
+import { useAppConfig } from '@app/contexts/AppConfigContext';
+import HomePage from '@app/pages/HomePage';
+import Login from '@app/routes/Login';
+
+/**
+ * Landing component - Smart router based on authentication status
+ *
+ * If login is disabled: Show HomePage directly (anonymous mode)
+ * If user is authenticated: Show HomePage
+ * If user is not authenticated: Show Login or redirect to /login
+ */
+export default function Landing() {
+  const { session, loading: authLoading } = useAuth();
+  const { config, loading: configLoading } = useAppConfig();
+  const location = useLocation();
+
+  const loading = authLoading || configLoading;
+
+  console.log('[Landing] State:', {
+    pathname: location.pathname,
+    loading,
+    hasSession: !!session,
+    loginEnabled: config?.enableLogin,
+  });
+
+  // Initialize backend on app startup
+  useBackendInitializer();
+
+  // Handle file opened with app (Tauri mode)
+  const { openedFilePath, loading: openedFileLoading } = useOpenedFile();
+  const [openedFile, setOpenedFile] = useState<File | null>(null);
+
+  // Load opened file once when path is available
+  useEffect(() => {
+    if (openedFilePath && !openedFileLoading) {
+      const loadOpenedFile = async () => {
+        try {
+          const fileData = await fileOpenService.readFileAsArrayBuffer(openedFilePath);
+          if (fileData) {
+            // Create a File object from the ArrayBuffer
+            const file = new File([fileData.arrayBuffer], fileData.fileName, {
+              type: 'application/pdf'
+            });
+            setOpenedFile(file);
+          }
+        } catch (error) {
+          console.error('Failed to load opened file:', error);
+        }
+      };
+
+      loadOpenedFile();
+    }
+  }, [openedFilePath, openedFileLoading]);
+
+  // Show loading while checking auth and config
+  if (loading) {
+    return (
+      <div style={{ minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+        <div className="text-center">
+          <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600 mx-auto mb-3"></div>
+          <div className="text-gray-600">
+            Loading...
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // If login is disabled, show app directly (anonymous mode)
+  if (config?.enableLogin === false) {
+    console.debug('[Landing] Login disabled - showing app in anonymous mode');
+    return <HomePage openedFile={openedFile} />;
+  }
+
+  // If we have a session, show the main app
+  if (session) {
+    return <HomePage openedFile={openedFile} />;
+  }
+
+  // If we're at home route ("/"), show login directly (marketing/landing page)
+  // Otherwise navigate to login (fixes URL mismatch for tool routes)
+  const isHome = location.pathname === '/' || location.pathname === '';
+  if (isHome) {
+    return <Login />;
+  }
+
+  // For non-home routes without auth, navigate to login (preserves from location)
+  return <Navigate to="/login" replace state={{ from: location }} />;
+}
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-rainbow" viewBox="0 0 16 16"><path d="M8 4.5a7 7 0 0 0-7 7 .5.5 0 0 1-1 0 8 8 0 1 1 16 0 .5.5 0 0 1-1 0 7 7 0 0 0-7-7zm0 2a5 5 0 0 0-5 5 .5.5 0 0 1-1 0 6 6 0 1 1 12 0 .5.5 0 0 1-1 0 5 5 0 0 0-5-5zm0 2a3 3 0 0 0-3 3 .5.5 0 0 1-1 0 4 4 0 1 1 8 0 .5.5 0 0 1-1 0 3 3 0 0 0-3-3zm0 2a1 1 0 0 0-1 1 .5.5 0 0 1-1 0 2 2 0 1 1 4 0 .5.5 0 0 1-1 0 1 1 0 0 0-1-1z"/></svg>`