OSIT-AE-App-Svelte/documentation/PROJECT_NATIVE_ELECTRON_INTEGRATION.md

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: Detailed audit of legacy features (process management, file caching, automation) to be preserved in the rewrite.
• 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: JSON schema definitions for the V3 bootstrap payload and the push-telemetry heartbeat logic.
• NATIVE_BRIDGE_INTERFACE_SPEC.md: Definition of the window.native_app IPC contract and the "Podium Reliability Protocol."
• NATIVE_APP_DEPLOYMENT_PLAN.md: Strategy for binary distribution and self-updates using the existing Syncthing admin_share infrastructure.
• 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