2ad6bce8db
file_handlers.ts had AI-generated escaped backticks (\`) and template
literal dollar signs (\${) throughout, causing TypeScript compile errors
("Invalid character", "Unterminated template literal"). Fixed all 15
affected lines.
README updated: corrected seed config path from resources/seed_config.json
to ~/seed.json (external to app bundle by design), added explanation of
why it's kept external (no re-signing needed per device), and documented
the 2-char hash prefix cache layout with consistency warning.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
94 lines
3.3 KiB
Markdown
94 lines
3.3 KiB
Markdown
# Aether Native Launcher (Electron)
|
|
|
|
The Aether Native Launcher is a specialized Electron-based shell for the Aether Platform. It provides a secure bridge between the SvelteKit web UI and the local operating system, enabling features restricted by browser sandboxing.
|
|
|
|
## 🚀 Overview
|
|
|
|
This application serves as the "Native Mode" runtime for Aether podiums and devices. It handles:
|
|
- **Local File Orchestration:** Managed cache for presentation files (PPTx, Keynote, PDF).
|
|
- **Automation:** Specialized AppleScript handlers for PowerPoint and Keynote.
|
|
- **Hardware Telemetry:** Direct access to CPU, RAM, and Network interface data.
|
|
- **Remote Control:** Slide navigation and application control via WebSocket intents.
|
|
|
|
## ⚙️ Configuration
|
|
|
|
The application requires a `seed.json` file to identify the device and connect to the Aether API.
|
|
|
|
### 1. Seed Configuration
|
|
|
|
**Location: `~/seed.json`** (user's home directory — external to the app bundle by design)
|
|
|
|
This file is intentionally kept outside the application bundle so it can be edited per-device
|
|
without re-signing or repackaging the app. On macOS this is `/Users/<username>/seed.json`.
|
|
|
|
Create/edit `~/seed.json`:
|
|
```json
|
|
{
|
|
"event_device_id": "YOUR_DEVICE_ID",
|
|
"aether_api_key": "YOUR_API_KEY",
|
|
"primary_api_base_url": "https://api.yourdomain.com",
|
|
"backup_api_base_url": null
|
|
}
|
|
```
|
|
|
|
> **Note:** The `event_device_id` and `aether_api_key` values come from the Aether admin panel
|
|
> (Events → Devices). Each physical device gets its own record and key.
|
|
|
|
### 2. Development Setup
|
|
```bash
|
|
npm install
|
|
npm start # Compiles TypeScript (tsc) then launches Electron
|
|
```
|
|
|
|
### 3. File Cache Layout
|
|
|
|
Presentation files are cached locally under `hash_prefix_length`-char subdirectories (default: 2):
|
|
```text
|
|
[local_file_cache_path]/
|
|
4a/
|
|
4a228ef8ac1a...sha256hash...file
|
|
1d/
|
|
1d720916a831...sha256hash...file
|
|
```
|
|
|
|
**Important:** `hash_prefix_length` must be consistent. If it changes, files in old directories
|
|
become orphaned and will be re-downloaded. The default is `2` and should not be changed unless
|
|
explicitly coordinated across all devices.
|
|
|
|
## 🌉 The Native Bridge (`aetherNative`)
|
|
|
|
The bridge is exposed to the renderer via `contextBridge`. It can be accessed in the web UI via `window.aetherNative`.
|
|
|
|
### Core Methods
|
|
|
|
| Method | Description |
|
|
| --- | --- |
|
|
| `list_tools()` | Returns a JSON manifest of all available native functions. |
|
|
| `launch_presentation({path, app})` | Launches a presentation with auto-focus and slideshow start. |
|
|
| `control_presentation({app, action})` | Sends `next`, `prev`, `start`, or `stop` to active decks. |
|
|
| `open_folder(path)` | Opens a local directory in the OS file explorer. |
|
|
| `get_device_info()` | Returns hardware metadata (RAM, IPs, Hostname). |
|
|
|
|
### Example Usage (UI Relay)
|
|
```typescript
|
|
import * as native from '$lib/electron/electron_relay';
|
|
|
|
// Launch a file from local cache
|
|
await native.launch_presentation({
|
|
path: '[tmp]/my_deck.pptx',
|
|
app: 'powerpoint'
|
|
});
|
|
|
|
// Navigate slides
|
|
await native.control_presentation({
|
|
app: 'powerpoint',
|
|
action: 'next'
|
|
});
|
|
```
|
|
|
|
## 🛠️ Development
|
|
|
|
- **Preload:** Logic defined in `src/preload/index.ts`.
|
|
- **Handlers:** OS-level logic in `src/main/shell_handlers.ts` and `src/main/file_handlers.ts`.
|
|
- **Types:** Shared TypeScript interfaces in `src/shared/types.ts`.
|