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-05-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/crud/event_device/{id} to pull device config and extract app_base_url (the event FQDN) and account_id.
3. Site Context: POSTs to /v3/crud/site_domain/search?limit=1 with the FQDN to resolve the correct site. No JWT — auth is x-aether-api-key + x-account-id throughout.
4. Launch: Navigates the SvelteKit frontend directly to the assigned Event Launcher route (/events/{eventId}/launcher/{locationId}).

---

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_cache({cache_root, hash, hash_prefix_length?, verify_hash?}) — Verifies a file exists in the local hashed cache. verify_hash: true re-hashes to confirm integrity.
• 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. Stale .tmp files (older than 5 min) from crashed downloads are cleaned up automatically on each call.
• copy_from_cache_to_temp({cache_root, hash, temp_root, filename, hash_prefix_length?}) — Preferred primitive. Copies a cached file to temp and returns { success, path }. The Svelte caller decides what to do next (run a script, open it, etc.).
• launch_from_cache({cache_root, hash, temp_root, filename, hash_prefix_length?, script_template?}) — Combines copy + launch in one call. Uses script_template if provided, otherwise falls back to hardcoded extension logic. See Configurable Launch Scripts below.

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. Hardened (2026-05-11): writes script to a temp .scpt file; multi-line scripts and paths with special characters now work correctly. No shell escaping needed in the passed string.
• kill_processes({process_name_li}) — Terminates processes by name. macOS/Linux: pkill -f. Windows: taskkill /F.
• 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.

---

8. Configurable Launch Scripts (No-Rebuild File Handling)

To avoid requiring a full Electron rebuild for changes to how files are opened, launch_from_cache supports an optional script_template parameter. When provided, Electron runs the template instead of its built-in hardcoded logic. The hardcoded logic remains intact as the fallback when no template is configured.

Template Formats

Format	Example
AppleScript (macOS)	Multi-line AppleScript string with {{path}} placeholder
Shell command	String prefixed with shell: — e.g. shell:open "{{path}}"

The placeholder {{path}} is replaced with the full resolved path to the file in the temp directory (after the atomic copy from cache).

Where to Configure

Templates are resolved in priority order by get_launch_script_template() in launcher_file_cont.svelte:

1. event_device.data_json.launch_scripts — API-driven, per-device. Highest priority. Set via the event_device record (Pres Mgmt → Device Management or direct DB edit).
2. $events_loc.launcher.launch_scripts — Local persistent config. Editable via the Launcher config UI (planned) or direct localStorage manipulation.

If neither is set, script_template is null and Electron uses its built-in hardcoded defaults.

Key Format

Keys are lowercase file extensions without the dot. A "default" key catches all unrecognised extensions.

// event_device.data_json.launch_scripts example
{
  "launch_scripts": {
    "pptx": "tell application \"Microsoft PowerPoint\"\n  activate\n  open (POSIX file \"{{path}}\")\n  delay 3\nend tell\ntell application \"System Events\"\n  keystroke return using command down\nend tell",
    "key": "tell application \"Keynote\"\n  activate\n  open (POSIX file \"{{path}}\")\n  delay 1\n  start (front document)\nend tell",
    "pdf": "shell:open \"{{path}}\"",
    "default": "shell:open \"{{path}}\""
  }
}

AppleScript Execution — All Handlers Hardened (2026-05-11)

All AppleScript execution in the native shell now writes scripts to a temp .scpt file and runs osascript "<path>" rather than the old osascript -e "<inline>" approach.

• run_osascript — hardened (2026-05-11, earlier batch)
• launch_from_cache — hardened (same batch)
• launch_presentation — hardened (2026-05-11, follow-up fix; was the last handler still using -e)
• control_presentation — uses single-line scripts with no path interpolation; -e is safe here and retained for simplicity

The -e approach breaks on (1) multi-line scripts and (2) file paths containing spaces, quotes, or parentheses — common in conference presentation filenames.

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.