# 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`.