feat(native): harden launcher bridge and implement presentation-aware handover

- Upgraded LauncherBackgroundSync to force-hydrate OS metadata (home/tmp) on mount.
- Hardened electron_relay.ts with robust placeholder resolution and global regex.
- Restored safe handover by making native.launch_from_cache presentation-aware.
- Integrated heartbeat and sync status into the formal Launcher Config UI.
- Added comprehensive technical documentation for the 2026 native architecture.

documentation/AETHER_NATIVE_APP_ELECTRON_NEW_2026.md

@@ -0,0 +1,70 @@
+# Aether Native Electron App - V3 Architecture (2026)
+
+## 1. Overview
+The Aether Native App serves as the OS-level bridge for the SvelteKit frontend. It enables functionality that is normally restricted by browser sandboxing, such as local filesystem management, hardware telemetry, and direct control of third-party presentation software (PowerPoint, Keynote, LibreOffice).
+
+---
+
+## 2. The Three-Layer Architecture
+
+### 2.1 The Engine (`electron_native.js`)
+*   **Process:** Main Process (Node.js)
+*   **Role:** Performs the actual OS-level operations.
+*   **Key Responsibilities:**
+    *   Executing shell commands via `child_process`.
+    *   Managing the permanent Hashed Cache (`file_cache/`).
+    *   Performing atomic "Safe Handover" copies to the operational `temp/` directory.
+    *   Resolving global path placeholders like `[home]` and `[tmp]`.
+
+### 2.2 The Bridge (`preload.js`)
+*   **Process:** Preload Script
+*   **Role:** The security gatekeeper.
+*   **Key Responsibilities:**
+    *   Uses Electron's `contextBridge` to securely expose specific Main Process functions to the UI.
+    *   Exposes the `window.aetherNative` object.
+    *   Ensures that only whitelisted IPC channels can be triggered by the renderer.
+
+### 2.3 The Messenger (`electron_relay.ts`)
+*   **Process:** Renderer Process (SvelteKit)
+*   **Role:** The TypeScript API used by Svelte components.
+*   **Key Responsibilities:**
+    *   Detecting if the app is running in "Native Mode".
+    *   Providing a clean, typed interface for native calls.
+    *   Implementing "Smart Fallbacks" (e.g., resolving placeholders UI-side if the bridge is outdated).
+
+---
+
+## 3. Core Lifecycle
+
+1.  **Seed Phase:** The Electron shell reads `~/seed.json` to identify the device.
+2.  **Hydration Phase:** The shell authenticates with the Aether V3 API to pull device-specific settings (room assignment, sync timers).
+3.  **Injection Phase:** The shell injects the **JWT (Auth Token)** and **Native Config** into the SvelteKit environment.
+4.  **Observation Phase:** `LauncherBackgroundSync.svelte` force-hydrates absolute OS paths (Home/Tmp) into the global `ae_loc` store for immediate use.
+
+---
+
+## 4. Native Tool Library (`window.aetherNative`)
+
+### File & Cache Management
+- `check_cache({hash})`: Verify if a file exists in the hidden hashed storage.
+- `download_to_cache({url, hash})`: Secure background download using the native API key.
+- `launch_from_cache({hash, filename})`: **Safe Handover** — copies from cache to temp with the original name and triggers the launcher.
+
+### OS Execution (The "Actuators")
+- `launch_presentation({path, app})`: Intelligent application selection.
+    - **Linux:** Triggers `libreoffice --impress`.
+    - **macOS:** Triggers AppleScript for Keynote/PowerPoint.
+- `run_cmd({cmd})`: Executes raw shell commands with automatic `[home]` and `[tmp]` resolution.
+- `kill_processes([names])`: Force-closes presentation apps to clean the podium between sessions.
+
+### System Metadata
+- `get_device_info()`: Provides OS version, CPU/RAM stats, and absolute system paths.
+
+---
+
+## 5. Path Placeholder System
+To maintain cross-platform compatibility, the system uses a placeholder syntax for all paths:
+- `[home]`: Resolves to the user's home directory (e.g., `/home/scott` or `/Users/scott`).
+- `[tmp]`: Resolves to the system temporary directory.
+
+**Resolution Logic:** All native handlers utilize a global regex (`/\[home\]/g`) to ensure these are converted to absolute paths before any disk or shell operation occurs.