55773a332d
- Standardize 'ae_BaseObj' and event types in 'ae_types.ts' to handle nullable fields from V3 API/Dexie. - Modernize Person, Address, and Contact forms with Svelte 5 Runes and reactive synchronization. - Refactor Event Settings and its sub-components to use the 'onsave' callback pattern, removing deprecated dispatchers. - Hardened 'element_data_store_v2' with safe initialization and localStorage caching logic. - Clean up unused 'element_data_store.svelte' (V1) and suppress Electron environment type errors in 'tmp_shell_handlers.ts'. - Update documentation and workspace settings to reflect Phase 5 reactive patterns.
77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
# Aether Native Electron App - V3 Architecture (2026)
|
|
|
|
## 1. Overview
|
|
The Aether Native App serves as the OS-level bridge for the SvelteKit frontend. It enables functionality that is normally restricted by browser sandboxing, such as local filesystem management, hardware telemetry, and direct control of third-party presentation software (PowerPoint, Keynote, LibreOffice).
|
|
|
|
**Core Tasks (Completed Jan 2026):**
|
|
* **[Infrastructure]**: Restore AE Events Presentation Launcher (Electron) (ID: 221513945)
|
|
* **[Frontend]**: V3 File Caching: Implement Launcher CRUD Migration (ID: 173518010)
|
|
* **[Frontend]**: Native App Bridge: Standardize Electron IPC (ID: 173448078)
|
|
|
|
---
|
|
|
|
## 2. The Three-Layer Architecture
|
|
|
|
### 2.1 The Engine (`src/main/*.ts`)
|
|
* **Process:** Main Process (Node.js/TypeScript)
|
|
* **Role:** Performs the actual OS-level operations.
|
|
* **Key Responsibilities:**
|
|
* **Shell Handlers (`shell_handlers.ts`)**: Executing shell commands, AppleScripts, and process management.
|
|
* **File Handlers (`file_handlers.ts`)**: Managing the permanent Hashed Cache (`file_cache/`) and atomic Safe Handover.
|
|
* Resolving global path placeholders like `[home]` and `[tmp]` via `file_utils.ts`.
|
|
|
|
### 2.2 The Bridge (`src/preload/index.ts`)
|
|
* **Process:** Preload Script
|
|
* **Role:** The security gatekeeper.
|
|
* **Key Responsibilities:**
|
|
* Uses Electron's `contextBridge` to securely expose Main Process functions to the UI.
|
|
* Exposes the `window.aetherNative` object.
|
|
* Ensures that only whitelisted IPC channels can be triggered by the renderer.
|
|
|
|
### 2.3 The Messenger (`src/lib/electron/electron_relay.ts`)
|
|
* **Process:** Renderer Process (SvelteKit)
|
|
* **Role:** The TypeScript API used by Svelte components.
|
|
* **Key Responsibilities:**
|
|
* Standardizing IPC calls to snake_case.
|
|
* Implementing "Smart Fallbacks" (e.g., UI-side placeholder resolution if the bridge is inactive).
|
|
|
|
---
|
|
|
|
## 3. Core Lifecycle
|
|
|
|
1. **Seed Phase:** The Electron shell reads `resources/seed_config.json` to identify the device.
|
|
2. **Hydration Phase:** The shell authenticates with the Aether V3 API to pull device-specific settings.
|
|
3. **Injection Phase:** The shell injects the **JWT** and **Native Config** into the SvelteKit environment.
|
|
4. **Observation Phase:** Background sync loops manage file warming and heartbeat telemetry.
|
|
|
|
---
|
|
|
|
## 4. Native Tool Library (`window.aetherNative`)
|
|
|
|
### File & Cache Management
|
|
- `check_cache({hash})`: Verify if a file exists in the hidden hashed storage.
|
|
- `download_to_cache({url, hash})`: Secure background download using the native API key.
|
|
- `launch_from_cache({hash, filename})`: **Safe Handover** — copies from cache to temp with the original name and triggers the specialized launcher.
|
|
|
|
### OS Execution (The "Actuators")
|
|
- `launch_presentation({path, app})`: Phase 5 specialized launcher with auto-focus (`activate`) and slideshow start.
|
|
- **Linux:** Triggers `libreoffice --impress`.
|
|
- **macOS:** Triggers AppleScript for Keynote or PowerPoint.
|
|
- `control_presentation({app, action})`: Remote navigation for active decks.
|
|
- **Actions:** `next`, `prev`, `start`, `stop`.
|
|
- `run_cmd({cmd})`: Executes raw shell commands with automatic path resolution.
|
|
- `kill_processes([names])`: Force-closes apps to clean the podium.
|
|
|
|
### Metadata & Discovery
|
|
- `get_device_info()`: Provides CPU/RAM stats and absolute system paths.
|
|
- `list_tools()`: Returns a JSON manifest of all available native functions for self-documentation.
|
|
|
|
---
|
|
|
|
## 5. Path Placeholder System
|
|
To maintain cross-platform compatibility, the system uses a placeholder syntax for all paths:
|
|
- `[home]`: Resolves to the user's home directory (e.g., `/home/scott` or `/Users/scott`).
|
|
- `[tmp]`: Resolves to the system temporary directory.
|
|
|
|
**Resolution Logic:** All native handlers utilize a global regex (`/\[home\]/g`) to ensure these are converted to absolute paths before any disk or shell operation occurs.
|