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: 2026-03-11 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)

• Repo: ~/OSIT_dev/aether_app_native_electron/ (separate git repo)
• File: aether_app_native_electron/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 Implemented Actuators (Phase 5 Complete)

• Recording: manage_recording({action}) — Aperture session capture (start, stop, status). macOS only.
• Display Layouts: set_display_layout({mode}) — Mirror / Extend via displayplacer. macOS only.
• Power Control: power_control({action}) — Shutdown, reboot, sleep. macOS + Linux.
• Window Control: window_control({action}) — Maximize, minimize, fullscreen, kiosk mode.
• Wallpaper: set_wallpaper({path}) — macOS (AppleScript) + Linux (gsettings).

Note: update_app is implemented as a stub — downloads but does not install. Not yet functional for end users.

---

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)

All functions below are exported from src/lib/electron/electron_relay.ts and safely no-op when window.aetherNative is not present (i.e., in browser/non-native mode).

Config & Info

• get_device_config() — Returns hydrated device settings injected by the native shell on startup.
• get_device_info() — Returns OS metadata, IP list, hostname, and path placeholders ([home], [tmp]).

File Cache

• check_hash_file_cache({cache_root, hash, hash_prefix_length?}) — Verifies a file exists in the local hashed cache.
• download_to_cache({url, cache_root, hash, api_key, account_id, hash_prefix_length?}) — Streams a file download to the hashed cache with SHA-256 integrity check.
• launch_from_cache({cache_root, hash, temp_root, filename, hash_prefix_length?}) — Atomic "Safe Handover": copy from cache → tmp → rename → execute.
• cleanup_tmp_files({cache_root, max_age_minutes?}) — Removes stale *.tmp download artifacts. Default: 1440 min (24h). Called at launcher startup.

hash_prefix_length defaults to 2 throughout. Do not change without coordinating all devices — mismatched values create orphaned cache subdirectories.

Shell & OS

• open_folder(path) — Opens a path in the OS file manager.
• run_cmd({cmd, timeout?, return_stdout?}) — Async shell command execution.
• run_cmd_sync({cmd, return_stdout?}) — Synchronous shell command execution.
• run_osascript(script) — Executes an AppleScript string. macOS only.
• kill_processes({process_name_li}) — Gracefully terminates processes by name.
• open_local_file_v2(path) — Opens a file with its default OS application.

Presentations (Phase 5)

• launch_presentation({path, app?, os?}) — Platform-aware launcher. macOS: PowerPoint/Keynote via AppleScript. Linux: LibreOffice Impress. Resolves [home]/[tmp] placeholders.
• control_presentation({app, action}) — Slide navigation (next/prev/start/stop) for PowerPoint or Keynote via AppleScript.

System Management (Phase 5)

• set_wallpaper({path}) — Sets desktop wallpaper. macOS (AppleScript) + Linux (gsettings).
• window_control({action, value?}) — Electron window management: maximize, minimize, fullscreen, kiosk.
• set_display_layout({mode, configStr?}) — Mirror or extend displays via displayplacer. macOS only.
• power_control({action}) — Shutdown, reboot, or sleep the host machine. macOS + Linux.
• manage_recording({action, options?}) — Aperture capture control (start/stop/status). macOS only.
• open_external({url, app?}) — Opens a URL in Chrome, Firefox, or the default browser.
• update_app(args) — Stub only. Downloads but does not install. Not yet functional.
• list_tools() — Returns a self-documenting manifest of all available native bridge functions.

Path Placeholders

All paths passed to native handlers should use tokens rather than hardcoded OS paths:

• [home] — Resolved to the user's home directory by the native bridge.
• [tmp] — Resolved to the system temporary directory.

Not Exposed via Relay (intentional)

• get_seed_config / get_jwt — Exposed in the preload but not relayed to the UI. The JWT and seed are injected into the environment at startup; components should not call these directly.