# Functional Specification: Aether Native App (Electron)

**Date:** 2026-01-30
**Status:** V5 / Phase 5 Specification
**Target OS:** macOS (Primary), Linux/Windows (Secondary)

## 1. Core Objectives
The Native App acts as a "Privileged Shell" for the Aether SvelteKit UI, providing capabilities that standard web browsers block for security reasons. It turns a standard laptop into a managed "Podium Kiosk."

## 2. macOS Permission Matrix (TCC)
To function as a podium controller, the Electron app requires specific entitlements.

| Permission | Reason | Criticality |
| :--- | :--- | :--- |
| **Accessibility** | Required to send AppleScript commands (Next/Prev) to Keynote and PowerPoint. | **CRITICAL** |
| **Screen Recording** | Required by the `aperture` utility to record the presentation session. | **CRITICAL** |
| **Microphone** | Required to capture room audio/presenter voice during recording. | **CRITICAL** |
| **Camera** | Optional, only if "Presenter View" (PiP) recording is enabled. | Low |
| **Automation** | Allows the app to control "System Events", "Finder", "Keynote", and "Microsoft PowerPoint". | **CRITICAL** |
| **Full Disk Access** | Recommended to ensure access to `~/OSIT` and `~/Downloads` without nagging prompts. | High |

## 3. Handler Registry (V5)
The following IPC handlers are exposed via `window.aetherNative`.

### 3.1 File & Cache System
| Handler | Description |
| :--- | :--- |
| `native:check-cache` | Verifies file existence in the sharded local cache (`~/OSIT/native_app/cache/xx/hash.file`). |
| `native:download-to-cache` | Streams a file from the API to the local cache with SHA-256 verification. |
| `native:launch-from-cache` | **Atomic Launch:** Copies file from cache -> temp with original filename -> launches app. |

### 3.2 Automation & Control (Phase 5)
| Handler | Description |
| :--- | :--- |
| `native:launch-presentation` | Opens a file using the specific app (Keynote/PPT) with "Slide Show" mode enabled immediately. |
| `native:control-presentation` | Sends navigation commands: `next`, `prev`, `start`, `stop`. |
| `native:kill-processes` | Force quits applications by name (e.g., "Microsoft PowerPoint") to resolve freezes. |

### 3.3 System Management (New Requirements)
These handlers are required for full "Kiosk" management.

| Handler | Description | Implementation Note |
| :--- | :--- | :--- |
| `native:set-wallpaper` | Resets desktop background to a specific image. | AppleScript: `tell application "System Events" to set picture of every desktop...` |
| `native:update-app` | Checks `~/OSIT/admin_share/...` for newer versions and self-updates. | Requires specific logic to swap the `.app` bundle and restart. |
| `native:window-control` | Controls the Electron window: `maximize`, `minimize`, `kiosk`, `devtools`. | Direct Electron `BrowserWindow` API calls. |
| `native:manage-recording` | Controls `aperture` process: `start`, `stop`, `status`. | Must track the PID of the spawned recording process. |
| `native:set-display-layout` | Toggles between **Mirror** and **Extended** modes. | Use bundled `displayplacer` binary (AppleScript is unreliable for this). |
| `native:power-control` | Initiates `shutdown` or `restart`. | Command: `shutdown -h now` (may require admin/sudo setup or user-level fallback). |
| `native:open-external` | Opens a URL in a specific browser (Chrome/Firefox). | `spawn('open', ['-a', 'Google Chrome', url])`. |

## 4. Feature Specifications

### 4.1 Self-Update Strategy
1.  **Path:** `~/OSIT/Speaker Ready System/Admin Share/Custom Applications/osit_binaries/`
2.  **Logic:**
    *   Compare `package.json` version in running app vs. remote path.
    *   If remote > local:
    *   Display "Updating..." splash.
    *   Copy new `.app` to `/Applications` (or current location).
    *   Relaunch.

### 4.2 Web Page Handling
The Launcher avoids Safari.
*   **Strategy A (Simple):** `native:open-external` -> Opens in Google Chrome Kiosk Mode (`--kiosk`).
*   **Strategy B (Integrated):** Use an Electron `BrowserView` (not `iframe`) to render the website *inside* the Aether window, ensuring we keep the "Back" button overlay visible.

### 4.3 Display Layouts
To reliably switch between Mirroring (for setup) and Extended (for presentation):
*   **Tool:** Bundle **`displayplacer`** (Homebrew utility) inside `resources/bin`.
*   **Command:** `displayplacer "id:<main> res:1920x1080" "id:<proj> res:1920x1080 origin:(1920,0)"` (Example).

## 5. Security Guardrails
*   **IPC Whitelisting:** All `run-cmd` calls are deprecated in favor of specific named handlers (e.g., `set-wallpaper`) to prevent arbitrary command execution.
*   **Path Validation:** All file operations must be restricted to `~/OSIT` or `~/tmp` directories.