7a8871c51f
- Synchronize Functional Spec with new system handlers (Wallpaper, Power, Recording, Displays). - Update Automation Scripts with finalized AppleScript handlers for PowerPoint and Keynote. - Mark IDAA and Phase 5 automation tasks as completed in TODO.md.
76 lines
4.6 KiB
Markdown
76 lines
4.6 KiB
Markdown
# 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.
|