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/NATIVE_BRIDGE_INTERFACE_SPEC.md

@@ -0,0 +1,74 @@
+# Specification: Aether Native V3 Bridge Interface
+
+**Namespace:** `window.native_app`
+**Security:** Context Isolated, Sandboxed IPC
+
+## 1. Device & Identity (`ae_device`)
+Functions for bootstrapping the app from the `seed.json`.
+
+| Method | Type | Description |
+| --- | --- | --- |
+| `getSeed()` | `() => Promise<SeedConfig>` | Returns the local `event_device_id` and `api_base_url`. |
+| `getDeviceInfo()` | `() => Promise<DeviceInfo>` | Returns OS, Arch, and unique hardware UUID. |
+| `getPermissions()`| `() => Promise<PermStatus>` | Returns status of Mic, Camera, and Accessibility. |
+| `requestAccess()` | `(type: string) => Promise<boolean>` | Triggers macOS TCC permission prompts. |
+
+## 2. Sync Engine (`ae_sync`)
+The Sync Engine manages the "Cold Cache" (`~/Library/Caches/Aether/`). It handles atomic downloads and hash verification.
+
+| Method | Type | Description |
+| --- | --- | --- |
+| `getCacheStatus()` | `(file_hash: string) => Promise<CacheInfo>` | Checks if a file exists and is valid. |
+| `startSync()` | `(task: SyncRequest) => Promise<void>` | Begins background download of a presentation. |
+| `cancelSync()` | `(file_hash: string) => Promise<void>` | Aborts an active download. |
+| `clearCache()` | `() => Promise<void>` | Wipes the cold cache (Maintenance). |
+
+### Events (Main -> Renderer)
+- `sync:progress`: `{ hash, percent, speed, bytesLoaded }`
+- `sync:complete`: `{ hash, success, error }`
+
+## 3. Launcher (`ae_launcher`)
+The "Big Red Button" logic. Handles the hand-off to the OS.
+
+| Method | Type | Description |
+| --- | --- | --- |
+| `launch()` | `(req: LaunchRequest) => Promise<void>` | 1. Moves file to Temp. 2. Opens with default app. 3. Starts slideshow. |
+| `killApp()` | `(appName: string) => Promise<void>` | Closes PowerPoint/Keynote/Acrobat gracefully. |
+| `preventSleep()` | `(enable: boolean) => Promise<void>` | Prevents the laptop from sleeping during a session. |
+
+## 4. System Control (`ae_sys`)
+Low-level macOS/Windows/Linux wrappers.
+
+| Method | Type | Description |
+| --- | --- | --- |
+| `setVolume()` | `(level: number) => Promise<void>` | Sets system master volume (0-100). |
+| `checkForUpdates()`| `() => Promise<UpdateStatus>` | Checks the Syncthing share for a newer version. |
+| `applyUpdate()` | `() => Promise<void>` | Triggers the `update_helper.sh` and exits. |
+| `execIntent()` | `(intent: string, args: any) => Promise<any>` | Executes a whitelisted command (e.g. `open-logs-folder`). |
+
+---
+
+## 5. TypeScript Interface (Draft)
+
+```typescript
+export interface AE_Native_Bridge {
+  device: {
+    getSeed: () => Promise<{ device_id: string; api_url: string }>;
+    requestPermissions: () => Promise<void>;
+  };
+  sync: {
+    getStatus: (hash: string) => Promise<{ exists: boolean; verified: boolean }>;
+    queueDownload: (payload: { url: string; hash: string; jwt: string }) => void;
+  };
+  launcher: {
+    launch: (file: { hash: string; name: string; type: 'pptx'|'key'|'pdf' }) => Promise<boolean>;
+    killAll: () => Promise<void>;
+  };
+}
+```
+
+## 6. Podium Reliability Protocol
+To ensure the podium never fails:
+1.  **Pre-Flight Check:** The SvelteKit UI will call `sync.getStatus` for every file in the session as soon as the page loads.
+2.  **Auto-Warmup:** If a file is missing, the UI automatically calls `sync.queueDownload` in the background.
+3.  **Verification:** The `launcher.launch` command will perform a final `sha256` check on the temp file *before* executing `shell.openPath`.