63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# Project: Aether Native Electron Integration
|
|
|
|
**Status:** Planning / Documentation
|
|
**Date:** 2026-01-20
|
|
**Target Platform:** macOS (Production), Arch Linux (Development)
|
|
|
|
## 1. Overview
|
|
This project aims to integrate the modern SvelteKit-based Aether UI into the established Electron native shell (`aether_app_native`). This enables "Native Mode" functionality, such as local file system access, presentation management, and hardware integration, which are restricted in standard web browsers.
|
|
|
|
## 2. Component Mapping
|
|
|
|
### 2.1 The Shell (`aether_app_native`)
|
|
- **Main Process:** Handles window creation, lifecycle, and IPC handlers.
|
|
- **Config:** Uses `ae_native_app_sk_config.json` located in `~/OSIT/native_app/` or `~/.config/OSIT/`.
|
|
- **Preload Script:** (To be standardized) The bridge that injects functionality into the UI.
|
|
|
|
### 2.2 The UI (`aether_app_sveltekit`)
|
|
- **Framework:** Svelte 5 / SvelteKit.
|
|
- **Detection:** Uses `+layout.svelte` to check for `window.native_app`.
|
|
- **Relay:** `src/lib/electron/electron_relay.js` acts as the frontend-side API for the native bridge.
|
|
|
|
## 3. Development Strategy (Arch Linux)
|
|
Since production targets macOS but development happens on Linux:
|
|
1. **Mocking macOS APIs:** Any calls to `osascript` or macOS-specific shell commands must be wrapped in a platform check.
|
|
2. **Path Handling:** Use `[home]` placeholders in config files to ensure paths resolve correctly on both `/home/scott/` (Linux) and `/Users/scott/` (Mac).
|
|
3. **Packaging:** Use `electron-packager` with macOS target flags to verify build integrity on Linux.
|
|
|
|
## 4. Implementation Plan
|
|
|
|
### Phase 1: Bridge Standardization
|
|
- Move existing logic from `aether_app_native/app/js/aether_app_native_v4.js` into a formal `preload.js`.
|
|
- Use `contextBridge.exposeInMainWorld` to provide a secure `native_app` object.
|
|
- Standardize return types (Promises) for all IPC calls.
|
|
|
|
### Phase 2: SvelteKit Build Integration
|
|
- Transition SvelteKit build to support relative asset paths (required for `file://` protocol).
|
|
- Update the native app's `index.js` to load the built SvelteKit `index.html` instead of a remote URL.
|
|
|
|
### Phase 3: Feature Parity (Events Module)
|
|
- Port the "Event Launcher" logic to the new bridge.
|
|
- Implement robust file caching using the `local_file_cache_path` from the native config.
|
|
- Ensure `kill_processes` works for both `pkill` (Linux) and `killall` (Mac).
|
|
|
|
## 5. Security Protocols
|
|
- **Context Isolation:** Must remain enabled.
|
|
- **Sandbox:** Enabled where possible.
|
|
- **IPC Whitelisting:** Only specific, pre-defined commands can be executed via `run_cmd`.
|
|
|
|
## 6. Project Documentation Index
|
|
The following documents provide detailed specifications for the V3 Native App rebuild:
|
|
|
|
- **[NATIVE_APP_FUNCTIONAL_SPEC.md](NATIVE_APP_FUNCTIONAL_SPEC.md)**: Detailed audit of legacy features (process management, file caching, automation) to be preserved in the rewrite.
|
|
- **[NATIVE_APP_V3_REWRITE_PLAN.md](NATIVE_APP_V3_REWRITE_PLAN.md)**: Technical strategy for Electron 33+, including the Zero-Config hydration flow and macOS permission handling.
|
|
- **[NATIVE_APP_V3_API_PAYLOAD.md](NATIVE_APP_V3_API_PAYLOAD.md)**: JSON schema definitions for the V3 bootstrap payload and the push-telemetry heartbeat logic.
|
|
- **[NATIVE_BRIDGE_INTERFACE_SPEC.md](NATIVE_BRIDGE_INTERFACE_SPEC.md)**: Definition of the `window.native_app` IPC contract and the "Podium Reliability Protocol."
|
|
- **[NATIVE_APP_DEPLOYMENT_PLAN.md](NATIVE_APP_DEPLOYMENT_PLAN.md)**: Strategy for binary distribution and self-updates using the existing Syncthing `admin_share` infrastructure.
|
|
- **[NATIVE_APP_AUTOMATION_SCRIPTS.md](NATIVE_APP_AUTOMATION_SCRIPTS.md)**: Specifications for AppleScript intents, recording lifecycle (Aperture), and Arch Linux mocking logic.
|
|
|
|
## 7. References
|
|
- Existing Native Docs: `aether_app_native/Aether App Native setup documentation.txt`
|
|
- Electron Integration: `src/lib/electron/README.md`
|
|
- Svelte 5 Runes: `documentation/ARCHITECTURE.md`
|