Saving the new documentation for the Launcher project plans. Finally moving this to a new version of Electron and pretty much starting from scratch.

documentation/PROJECT_NATIVE_ELECTRON_INTEGRATION.md

@@ -0,0 +1,62 @@
+# Project: Aether Native Electron Integration
+
+**Status:** Planning / Documentation
+**Date:** 2026-01-20
+**Target Platform:** macOS (Production), Arch Linux (Development)
+
+## 1. Overview
+This project aims to integrate the modern SvelteKit-based Aether UI into the established Electron native shell (`aether_app_native`). This enables "Native Mode" functionality, such as local file system access, presentation management, and hardware integration, which are restricted in standard web browsers.
+
+## 2. Component Mapping
+
+### 2.1 The Shell (`aether_app_native`)
+- **Main Process:** Handles window creation, lifecycle, and IPC handlers.
+- **Config:** Uses `ae_native_app_sk_config.json` located in `~/OSIT/native_app/` or `~/.config/OSIT/`.
+- **Preload Script:** (To be standardized) The bridge that injects functionality into the UI.
+
+### 2.2 The UI (`aether_app_sveltekit`)
+- **Framework:** Svelte 5 / SvelteKit.
+- **Detection:** Uses `+layout.svelte` to check for `window.native_app`.
+- **Relay:** `src/lib/electron/electron_relay.js` acts as the frontend-side API for the native bridge.
+
+## 3. Development Strategy (Arch Linux)
+Since production targets macOS but development happens on Linux:
+1. **Mocking macOS APIs:** Any calls to `osascript` or macOS-specific shell commands must be wrapped in a platform check.
+2. **Path Handling:** Use `[home]` placeholders in config files to ensure paths resolve correctly on both `/home/scott/` (Linux) and `/Users/scott/` (Mac).
+3. **Packaging:** Use `electron-packager` with macOS target flags to verify build integrity on Linux.
+
+## 4. Implementation Plan
+
+### Phase 1: Bridge Standardization
+- Move existing logic from `aether_app_native/app/js/aether_app_native_v4.js` into a formal `preload.js`.
+- Use `contextBridge.exposeInMainWorld` to provide a secure `native_app` object.
+- Standardize return types (Promises) for all IPC calls.
+
+### Phase 2: SvelteKit Build Integration
+- Transition SvelteKit build to support relative asset paths (required for `file://` protocol).
+- Update the native app's `index.js` to load the built SvelteKit `index.html` instead of a remote URL.
+
+### Phase 3: Feature Parity (Events Module)
+- Port the "Event Launcher" logic to the new bridge.
+- Implement robust file caching using the `local_file_cache_path` from the native config.
+- Ensure `kill_processes` works for both `pkill` (Linux) and `killall` (Mac).
+
+## 5. Security Protocols
+- **Context Isolation:** Must remain enabled.
+- **Sandbox:** Enabled where possible.
+- **IPC Whitelisting:** Only specific, pre-defined commands can be executed via `run_cmd`.
+
+## 6. Project Documentation Index
+The following documents provide detailed specifications for the V3 Native App rebuild:
+
+- **[NATIVE_APP_FUNCTIONAL_SPEC.md](NATIVE_APP_FUNCTIONAL_SPEC.md)**: Detailed audit of legacy features (process management, file caching, automation) to be preserved in the rewrite.
+- **[NATIVE_APP_V3_REWRITE_PLAN.md](NATIVE_APP_V3_REWRITE_PLAN.md)**: Technical strategy for Electron 33+, including the Zero-Config hydration flow and macOS permission handling.
+- **[NATIVE_APP_V3_API_PAYLOAD.md](NATIVE_APP_V3_API_PAYLOAD.md)**: JSON schema definitions for the V3 bootstrap payload and the push-telemetry heartbeat logic.
+- **[NATIVE_BRIDGE_INTERFACE_SPEC.md](NATIVE_BRIDGE_INTERFACE_SPEC.md)**: Definition of the `window.native_app` IPC contract and the "Podium Reliability Protocol."
+- **[NATIVE_APP_DEPLOYMENT_PLAN.md](NATIVE_APP_DEPLOYMENT_PLAN.md)**: Strategy for binary distribution and self-updates using the existing Syncthing `admin_share` infrastructure.
+- **[NATIVE_APP_AUTOMATION_SCRIPTS.md](NATIVE_APP_AUTOMATION_SCRIPTS.md)**: Specifications for AppleScript intents, recording lifecycle (Aperture), and Arch Linux mocking logic.
+
+## 7. References
+- Existing Native Docs: `aether_app_native/Aether App Native setup documentation.txt`
+- Electron Integration: `src/lib/electron/README.md`
+- Svelte 5 Runes: `documentation/ARCHITECTURE.md`