9da3e5326b
- Apply consistent prefix naming: AE__, GUIDE__, PROJECT__, MODULE__, TODO__ - Move superseded/session docs to documentation/history/ - Migrate old/ directory contents to history/ with updated naming - README.md: replace stale Modules section with accurate current routes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
147 lines
7.0 KiB
Markdown
147 lines
7.0 KiB
Markdown
# Aether Events Launcher: Native Electron Integration
|
|
|
|
> **Status:** Operational / Phase 5 Implementation
|
|
> **Last Updated:** February 10, 2026
|
|
> **Primary Platform:** macOS (Darwin)
|
|
> **Fallback Platform:** Linux / Windows
|
|
|
|
## 1. Overview
|
|
The Aether Events Launcher utilizes an Electron-based "Native Shell" to provide OS-level capabilities that are normally restricted by browser sandboxing. This enables persistent file caching, direct control of presentation software (Keynote, PowerPoint), and hardware telemetry.
|
|
|
|
### Operational Modes
|
|
| Mode | Purpose | File Handling |
|
|
| :--- | :--- | :--- |
|
|
| **Default** | Standard web browser access. | Direct downloads; no local caching. |
|
|
| **Onsite** | Web access on event networks. | Faster polling; browser-based file management. |
|
|
| **Native** | Dedicated Podium Kiosk (Electron). | Full background pre-caching; atomic safe-handover. |
|
|
|
|
---
|
|
|
|
## 2. Architecture: The Three-Layer Bridge
|
|
|
|
The integration is built on a decoupled three-layer communication model to ensure security and cross-platform flexibility.
|
|
|
|
### 2.1 Layer 1: The Engine (Main Process)
|
|
- **File:** `aether_app_native/src/main/*.ts`
|
|
- **Role:** Performs the heavy lifting (Filesystem, Shell, AppleScript).
|
|
- **Responsibilities:**
|
|
- Managing the **Hashed Cache** directory.
|
|
- Executing `osascript` intents for presentation control.
|
|
- Spawn/Kill process management.
|
|
|
|
### 2.2 Layer 2: The Gatekeeper (Preload Script)
|
|
- **Namespace:** `window.aetherNative`
|
|
- **Role:** Securely exposes whitelisted IPC channels to the Renderer.
|
|
- **Standards:** Uses `contextBridge.exposeInMainWorld` to prevent arbitrary code execution.
|
|
|
|
### 2.3 Layer 3: The Messenger (SvelteKit Relay)
|
|
- **File:** `src/lib/electron/electron_relay.ts`
|
|
- **Role:** Provides a clean, typed API for Svelte components.
|
|
- **Responsibilities:**
|
|
- Mapping `camelCase` UI triggers to `snake_case` IPC calls.
|
|
- Implementing "Smart Fallbacks" (e.g., resolving `[home]` placeholders if the bridge is partially hydrated).
|
|
|
|
---
|
|
|
|
## 3. The "Zero-Config" Lifecycle
|
|
|
|
To support rapid onsite deployment, the native app requires zero manual setup.
|
|
|
|
1. **Seed:** On launch, the Main process reads a local `seed.json` (Device ID + API Key).
|
|
2. **Identity:** Calls `GET /v3/data_store/code/{device_code}` or `GET /v3/crud/event_device/{id}` to pull operational context.
|
|
3. **Hydrate:** Authenticates with the Aether V3 API and injects the **JWT** and **Device Config** into the UI environment.
|
|
4. **Launch:** Navigates the SvelteKit frontend directly to the assigned Event Launcher route.
|
|
|
|
---
|
|
|
|
## 4. Podium Reliability Protocol
|
|
|
|
The system is designed to ensure that a presentation never fails due to network instability.
|
|
|
|
### 4.1 Hashed Cache Pattern
|
|
Files are stored persistently using their SHA-256 hash to prevent filename collisions and handle versioning.
|
|
- **Root:** `~/Library/Caches/OSIT/file_cache/`
|
|
- **Subdirectory:** First 2 characters of hash (e.g., `ab/`)
|
|
- **Filename:** `{hash}.file`
|
|
|
|
### 4.2 Background Sync (File Warming)
|
|
When a user navigates to a session in the Launcher UI, the `LauncherBackgroundSync` component:
|
|
1. Extracts all `event_file_id` values for that session.
|
|
2. Checks the native cache via `aetherNative.check_cache`.
|
|
3. Triggers background downloads for missing files via `aetherNative.download_to_cache`.
|
|
|
|
### 4.3 Safe Handover (Launch Sequence)
|
|
When a user clicks "Open", the system follows a non-destructive sequence:
|
|
1. **Verify:** Confirm hash exists in the permanent cache.
|
|
2. **Copy:** Create an atomic copy in the system `[tmp]` directory.
|
|
3. **Restore:** Rename the copy to its original filename (e.g., `Abstract_101.pptx`).
|
|
4. **Execute:** Launch the file via the OS.
|
|
|
|
---
|
|
|
|
## 5. Automation & Actuators (Phase 5)
|
|
|
|
The native shell provides specialized handlers for controlling the "Podium Experience."
|
|
|
|
### 5.1 Presentation Acts
|
|
| Action | Handler | Actuator (macOS) |
|
|
| :--- | :--- | :--- |
|
|
| **Launch** | `launch_presentation` | `open` or `osascript` (slideshow start) |
|
|
| **Control** | `control_presentation` | `osascript` (next/prev slide) |
|
|
| **Clean Up**| `kill_processes` | `killall -INT` (graceful exit) |
|
|
|
|
### 5.2 System Management
|
|
- **Telemetry:** Pushes `cpu_usage`, `memory_free_gb`, and `foreground_app` via heartbeats using the `get_device_info` relay.
|
|
- **Self-Update (Roadmap):** Plan to monitor Syncthing `admin_share` for newer `.app` versions and perform atomic swaps.
|
|
|
|
### 5.3 Planned Actuators (Future Phases)
|
|
- **Recording:** Control for `aperture` session capture (`start`, `stop`).
|
|
- **Display Layouts:** Toggling between Mirror and Extended modes via `displayplacer`.
|
|
|
|
---
|
|
|
|
## 6. Launcher Configuration & Management
|
|
|
|
The Launcher features a standardized, responsive configuration interface designed for onsite technical management.
|
|
|
|
### 6.1 UI Architecture
|
|
- **Tabbed Navigation:** Categorized into System, Sync, and General settings.
|
|
- **Section Wrapper (`Launcher_Cfg_Section`):** A shared component providing a consistent header, icon, and responsive grid container.
|
|
|
|
### 6.2 3-Way State Logic
|
|
To manage screen real estate on varying laptop resolutions, all configuration sections utilize a 3-way visibility state:
|
|
- **`collapsed`**: Content is hidden.
|
|
- **`auto`**: Expanded by default, but automatically closes if another "auto" section is opened.
|
|
- **`pinned`**: Expanded and remains open regardless of other section interactions.
|
|
|
|
### 6.3 Technical Mode (`edit_mode`)
|
|
The UI dynamically filters fields based on the user's focus. Enabling Technical Mode (`$ae_loc.edit_mode`) reveals advanced diagnostic and writeable fields.
|
|
|
|
| Category | Standard View (Read-Only) | Technical Mode (Read/Write) |
|
|
| :--- | :--- | :--- |
|
|
| **Health** | Heartbeat, RAM Usage, Sync Stats | Hostname, IP List, Raw Device JSON |
|
|
| **OS Bridge** | Folder Buttons, Recording Toggle | Manual Terminal Commands, Reset Wallpaper |
|
|
| **Sync** | Sync Completion Status | Millisecond Timers, Cache Prefix Logic |
|
|
| **Update** | Current Version Status | Manual Update Paths, URL Overrides |
|
|
|
|
---
|
|
|
|
## 7. Implementation Reference (IPC Whitelist)
|
|
|
|
### Core Functions (`electron_relay.ts`)
|
|
- `get_device_config()`: Returns hydrated device settings from the native shell.
|
|
- `get_device_info()`: Returns OS metadata, IP list, and path placeholders (`[home]`, `[tmp]`).
|
|
- `check_hash_file_cache({cache_root, hash})`: Local filesystem hash check.
|
|
- `download_to_cache({url, cache_root, hash, ...})`: Authorized background download to the hashed cache.
|
|
- `launch_from_cache({cache_root, hash, temp_root, filename})`: Atomic "Safe Handover" trigger.
|
|
- `launch_presentation({path, app})`: Phase 5 specialized launcher with slideshow activation.
|
|
- `control_presentation({app, action})`: Remote navigation (next/prev) for active decks.
|
|
- `kill_processes({process_name_li})`: Graceful application termination.
|
|
- `manage_recording({action})`: Presentation session capture control (Aperture).
|
|
- `list_tools()`: Manifest of all available native bridge functions.
|
|
|
|
### Path Placeholders
|
|
To ensure cross-platform compatibility, all paths should use:
|
|
- `[home]`: User home directory.
|
|
- `[tmp]`: System temporary directory.
|