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

Aether Events Launcher: Native Electron Integration

Status: Operational / Phase 5 Implementation
Last Updated: February 10, 2026
Primary Platform: macOS (Darwin)
Fallback Platform: Linux / Windows

1. Overview

The Aether Events Launcher utilizes an Electron-based "Native Shell" to provide OS-level capabilities that are normally restricted by browser sandboxing. This enables persistent file caching, direct control of presentation software (Keynote, PowerPoint), and hardware telemetry.

Operational Modes

Mode	Purpose	File Handling
Default	Standard web browser access.	Direct downloads; no local caching.
Onsite	Web access on event networks.	Faster polling; browser-based file management.
Native	Dedicated Podium Kiosk (Electron).	Full background pre-caching; atomic safe-handover.

---

2. Architecture: The Three-Layer Bridge

The integration is built on a decoupled three-layer communication model to ensure security and cross-platform flexibility.

2.1 Layer 1: The Engine (Main Process)

• File: aether_app_native/src/main/*.ts
• Role: Performs the heavy lifting (Filesystem, Shell, AppleScript).
• Responsibilities:
  • Managing the Hashed Cache directory.
  • Executing osascript intents for presentation control.
  • Spawn/Kill process management.

2.2 Layer 2: The Gatekeeper (Preload Script)

• Namespace: window.aetherNative
• Role: Securely exposes whitelisted IPC channels to the Renderer.
• Standards: Uses contextBridge.exposeInMainWorld to prevent arbitrary code execution.

2.3 Layer 3: The Messenger (SvelteKit Relay)

• File: src/lib/electron/electron_relay.ts
• Role: Provides a clean, typed API for Svelte components.
• Responsibilities:
  • Mapping camelCase UI triggers to snake_case IPC calls.
  • Implementing "Smart Fallbacks" (e.g., resolving [home] placeholders if the bridge is partially hydrated).

---

3. The "Zero-Config" Lifecycle

To support rapid onsite deployment, the native app requires zero manual setup.

1. Seed: On launch, the Main process reads a local seed.json (Device ID + API Key).
2. Identity: Calls GET /v3/data_store/code/{device_code} or GET /v3/crud/event_device/{id} to pull operational context.
3. Hydrate: Authenticates with the Aether V3 API and injects the JWT and Device Config into the UI environment.
4. Launch: Navigates the SvelteKit frontend directly to the assigned Event Launcher route.

---

4. Podium Reliability Protocol

The system is designed to ensure that a presentation never fails due to network instability.

4.1 Hashed Cache Pattern

Files are stored persistently using their SHA-256 hash to prevent filename collisions and handle versioning.

• Root: ~/Library/Caches/OSIT/file_cache/
• Subdirectory: First 2 characters of hash (e.g., ab/)
• Filename: {hash}.file

4.2 Background Sync (File Warming)

When a user navigates to a session in the Launcher UI, the LauncherBackgroundSync component:

1. Extracts all event_file_id values for that session.
2. Checks the native cache via aetherNative.check_cache.
3. Triggers background downloads for missing files via aetherNative.download_to_cache.

4.3 Safe Handover (Launch Sequence)

When a user clicks "Open", the system follows a non-destructive sequence:

1. Verify: Confirm hash exists in the permanent cache.
2. Copy: Create an atomic copy in the system [tmp] directory.
3. Restore: Rename the copy to its original filename (e.g., Abstract_101.pptx).
4. Execute: Launch the file via the OS.

---

5. Automation & Actuators (Phase 5)

The native shell provides specialized handlers for controlling the "Podium Experience."

5.1 Presentation Acts

Action	Handler	Actuator (macOS)
Launch	launch_presentation	open or osascript (slideshow start)
Control	control_presentation	osascript (next/prev slide)
Clean Up	kill_processes	killall -INT (graceful exit)

5.2 System Management

• Telemetry: Pushes cpu_usage, memory_free_gb, and foreground_app via heartbeats using the get_device_info relay.
• Self-Update (Roadmap): Plan to monitor Syncthing admin_share for newer .app versions and perform atomic swaps.

5.3 Planned Actuators (Future Phases)

• Recording: Control for aperture session capture (start, stop).
• Display Layouts: Toggling between Mirror and Extended modes via displayplacer.

---

6. Launcher Configuration & Management

The Launcher features a standardized, responsive configuration interface designed for onsite technical management.

6.1 UI Architecture

• Tabbed Navigation: Categorized into System, Sync, and General settings.
• Section Wrapper (Launcher_Cfg_Section): A shared component providing a consistent header, icon, and responsive grid container.

6.2 3-Way State Logic

To manage screen real estate on varying laptop resolutions, all configuration sections utilize a 3-way visibility state:

• collapsed: Content is hidden.
• auto: Expanded by default, but automatically closes if another "auto" section is opened.
• pinned: Expanded and remains open regardless of other section interactions.

6.3 Technical Mode (edit_mode)

The UI dynamically filters fields based on the user's focus. Enabling Technical Mode ($ae_loc.edit_mode) reveals advanced diagnostic and writeable fields.

Category	Standard View (Read-Only)	Technical Mode (Read/Write)
Health	Heartbeat, RAM Usage, Sync Stats	Hostname, IP List, Raw Device JSON
OS Bridge	Folder Buttons, Recording Toggle	Manual Terminal Commands, Reset Wallpaper
Sync	Sync Completion Status	Millisecond Timers, Cache Prefix Logic
Update	Current Version Status	Manual Update Paths, URL Overrides

---

7. Implementation Reference (IPC Whitelist)

Core Functions (electron_relay.ts)

• get_device_config(): Returns hydrated device settings from the native shell.
• get_device_info(): Returns OS metadata, IP list, and path placeholders ([home], [tmp]).
• check_hash_file_cache({cache_root, hash}): Local filesystem hash check.
• download_to_cache({url, cache_root, hash, ...}): Authorized background download to the hashed cache.
• launch_from_cache({cache_root, hash, temp_root, filename}): Atomic "Safe Handover" trigger.
• launch_presentation({path, app}): Phase 5 specialized launcher with slideshow activation.
• control_presentation({app, action}): Remote navigation (next/prev) for active decks.
• kill_processes({process_name_li}): Graceful application termination.
• manage_recording({action}): Presentation session capture control (Aperture).
• list_tools(): Manifest of all available native bridge functions.

Path Placeholders

To ensure cross-platform compatibility, all paths should use:

• [home]: User home directory.
• [tmp]: System temporary directory.