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

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).

---

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.