# Project Plan: Aether Native V3 Rewrite

**Target:** Electron 33+
**Primary Platform:** macOS (Production)
**Development Platform:** Arch Linux
**API Version:** Aether V3 (REST + JWT)

## 1. Minimalist Configuration Strategy
To simplify laptop deployment, we will move away from large local JSON files.

### 1.1 The "Seed" Config
Each laptop will contain a `seed.json` located in standard OS config paths (e.g., `~/.config/aether/seed.json` or `~/Library/Application Support/Aether/`).
```json
{
  "event_device_id": "AE-LPT-01",
  "api_base_url": "https://api.oneskyit.com"
}
```

### 1.2 The Bootstrap Flow
1.  **Launch:** Electron reads the `seed.json`.
2.  **Identity:** App calls `GET /v3/crud/event_device/{id}?view=full_config`.
3.  **Hydrate:** API returns the full operational config (Account context, Event settings, File cache paths).
4.  **Auth:** App uses its device-specific API key to exchange for a session JWT.
5.  **Inject:** Config and JWT are injected into the SvelteKit frontend via the Preload script.

## 2. macOS Hardening (Permissions)
macOS requires explicit user consent for several features. The new app will handle these during the "Splash Screen" phase.

- **AV Access:** Use `systemPreferences.askForMediaAccess('camera')` and `microphone`.
- **Accessibility:** For remote control/automation, check `systemPreferences.isTrustedAccessibilityClient(true)`.
- **Screen Recording:** Required for the presentation tracker. We will use a "Check and Prompt" loop.

## 3. Cross-Platform Handling
| Feature | macOS (Production) | Linux/Windows (Dev/Comp) |
| --- | --- | --- |
| **Process Kill** | `killall -INT "PowerPoint"` | `pkill -f "powerpnt.exe"` |
| **Automation** | AppleScript (`osascript`) | Mocked via logs or Shell commands. |
| **Paths** | `~/Library/Caches/Aether` | `~/.cache/aether` |
| **Window** | Frameless, Transparent support. | Standard decorated window. |

## 4. Proposed Directory Structure
```text
aether_app_native_v3/
├── src/
│   ├── main/
│   │   ├── index.ts          # Window lifecycle
│   │   ├── ipc_handlers.ts   # Whitelisted OS commands
│   │   ├── macos_perms.ts    # Mic/Cam/Accessibility logic
│   │   └── api_client.ts     # V3 Auth & Config sync
│   ├── preload/
│   │   └── index.ts          # Secure ContextBridge
│   └── shared/
│       └── types.ts          # TS Interfaces for the bridge
├── resources/                # Icons and splash screens
└── electron-builder.yml      # Multi-platform build config
```

## 5. Security Upgrades
1.  **JWT Storage:** Store the session token in Electron's `safeStorage` (OS-level encryption) rather than simple `localStorage`.
2.  **Navigation Lock:** Prevent the SvelteKit UI from navigating away from the Aether domain.
3.  **Command Whitelisting:** Instead of a generic `run_cmd`, implement specific handlers like `native:launch-presentation` which only accepts a file hash.

## 6. Deployment & Self-Update
To support onsite deployment via Syncthing:
1.  **Version Watcher:** Main process monitors `admin_share/binaries/native_app/version.json`.
2.  **Atomic Swap:** Use a dedicated `update_helper.sh` to swap the `.app` bundle while the app is closed.
3.  **Zero-Touch Provisioning:** Auto-copy `seed_[hostname].json` from the sync share if local config is missing.

## 7. Development Tools (Arch Linux)
- Use `fakeroot` and `binutils` to package for macOS on Linux.
- Use `Xvfb` for headless testing of Electron windows in CI/CD.