# 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`