Files

Scott Idem b072857d68 feat(native): harden launcher bridge and implement presentation-aware handover

- Upgraded LauncherBackgroundSync to force-hydrate OS metadata (home/tmp) on mount.
- Hardened electron_relay.ts with robust placeholder resolution and global regex.
- Restored safe handover by making native.launch_from_cache presentation-aware.
- Integrated heartbeat and sync status into the formal Launcher Config UI.
- Added comprehensive technical documentation for the 2026 native architecture.

2026-01-26 15:12:03 -05:00

3.4 KiB

Raw Blame History

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 (`electron_native.js`)

Process: Main Process (Node.js)
Role: Performs the actual OS-level operations.
Key Responsibilities:
- Executing shell commands via child_process.
- Managing the permanent Hashed Cache (file_cache/).
- Performing atomic "Safe Handover" copies to the operational temp/ directory.
- Resolving global path placeholders like [home] and [tmp].

2.2 The Bridge (`preload.js`)

Process: Preload Script
Role: The security gatekeeper.
Key Responsibilities:
- Uses Electron's contextBridge to securely expose specific 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 (`electron_relay.ts`)

Process: Renderer Process (SvelteKit)
Role: The TypeScript API used by Svelte components.
Key Responsibilities:
- Detecting if the app is running in "Native Mode".
- Providing a clean, typed interface for native calls.
- Implementing "Smart Fallbacks" (e.g., resolving placeholders UI-side if the bridge is outdated).

3. Core Lifecycle

Seed Phase: The Electron shell reads ~/seed.json to identify the device.
Hydration Phase: The shell authenticates with the Aether V3 API to pull device-specific settings (room assignment, sync timers).
Injection Phase: The shell injects the JWT (Auth Token) and Native Config into the SvelteKit environment.
Observation Phase: LauncherBackgroundSync.svelte force-hydrates absolute OS paths (Home/Tmp) into the global ae_loc store for immediate use.

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

OS Execution (The "Actuators")

launch_presentation({path, app}): Intelligent application selection.
- Linux: Triggers libreoffice --impress.
- macOS: Triggers AppleScript for Keynote/PowerPoint.
run_cmd({cmd}): Executes raw shell commands with automatic [home] and [tmp] resolution.
kill_processes([names]): Force-closes presentation apps to clean the podium between sessions.

System Metadata

get_device_info(): Provides OS version, CPU/RAM stats, and absolute system paths.

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.

3.4 KiB Raw Blame History