Aether Native Launcher (Electron)

The Aether Native Launcher is a specialized Electron-based shell for the Aether Platform. It provides a secure bridge between the SvelteKit web UI and the local operating system, enabling features restricted by browser sandboxing.

🚀 Overview

This application serves as the "Native Mode" runtime for Aether podiums and devices. It handles:

• Local File Orchestration: Managed cache for presentation files (PPTx, Keynote, PDF).
• Automation: Specialized AppleScript handlers for PowerPoint and Keynote.
• Hardware Telemetry: Direct access to CPU, RAM, and Network interface data.
• Remote Control: Slide navigation and application control via WebSocket intents.

🖥️ Onsite Deployment

Current hardware: MacBook Air 2018 — Intel x64. All current deployments use aether_launcher-darwin-x64. Future hardware: Apple Silicon Macs use aether_launcher-darwin-arm64. Windows and Linux builds are planned.

SSH user on all laptops: speaker ready IP pattern: 192.168.32.1XX (XX = zero-padded laptop number, e.g. 03 → .103). Find/replace this prefix for other onsite environments.

Deploy files live in deploy/:

File	Purpose
deploy/deploy.sh	Deploy script — handles arch detection, scp, and seed.json
deploy/devices.conf	Laptop list: number, IP, event_device_id
deploy/event.env	Gitignored — per-event API key and URLs (create from example)
deploy/event.env.example	Template for event.env

Step 1 — Build the app (workstation)

cd ~/OSIT_dev/aether_app_native_electron
npm run package:mac
# Produces builds/aether_launcher-darwin-x64/aether_launcher.app  ← the one to deploy

Only rebuild if source code has changed. The .app bundle is identical for all Intel laptops — only ~/seed.json differs per device.

Step 2 — Create event.env

cp deploy/event.env.example deploy/event.env
# Edit deploy/event.env — fill in AETHER_API_KEY

Create the API key in the Aether admin panel before the show (Core → Accounts or Events → Devices API key section). All laptops share one key per event. Delete it after the show.

Step 3 — Run the deploy script

# Deploy specific laptops:
./deploy/deploy.sh 01 02 03

# Deploy all laptops in devices.conf:
./deploy/deploy.sh all

# Update seed.json only (no .app copy — e.g. when rotating the API key):
./deploy/deploy.sh --seed-only all

The script auto-detects each Mac's CPU architecture, copies the correct .app build, writes seed.json, and verifies. One SSH connection failure won't abort the batch — it logs and continues, then reports which laptops need a retry.

Step 4 — Verify and launch

After the script completes, launch the app on each laptop and confirm it connects and shows the correct device name in the Launcher UI.

Adding SSH key to a new laptop (first time only)

ssh-copy-id "speaker ready"@192.168.32.1XX

Run once per laptop before deploying.

---

Manual deploy reference

The script covers the normal case. For one-off fixes or if the script isn't available:

# Detect arch
ssh "speaker ready"@192.168.32.103 "uname -m"
# x86_64 → darwin-x64  |  arm64 → darwin-arm64

# Copy .app (Intel example):
scp -r builds/aether_launcher-darwin-x64/aether_launcher.app \
    "speaker ready"@192.168.32.103:/Applications/aether_launcher.app

# Write seed.json:
ssh "speaker ready"@192.168.32.103 "cat > ~/seed.json" << 'EOF'
{
  "event_device_id": "DEVICE_ID_FOR_THIS_LAPTOP",
  "aether_api_key": "YOUR_API_KEY",
  "primary_api_base_url": "https://api.oneskyit.com",
  "backup_api_base_url": "https://bak-api.oneskyit.com",
  "onsite_api_base_url": null
}
EOF

# Verify:
ssh "speaker ready"@192.168.32.103 "cat ~/seed.json"

event_device_id values by laptop — see the Device Reference table below.

---

📋 Device Reference

Laptop	IP Address	event_device_id	Notes
01	192.168.32.101	tFLL1fLQfnk
02	192.168.32.102	rpbfunVPEzw
03	192.168.32.103	1EPfPX8kfw8
04	192.168.32.104	zvgyLM5yieU
05	192.168.32.105	QOc046GoeSc
06	192.168.32.106	2o8j6eb0L6s
07	192.168.32.107	Oa1tlxPEVSQ
08	192.168.32.108	fY4yznpUZ48
09	192.168.32.109	YlgGCyjo9bY
10	192.168.32.110	GcTnFsp1mHI
11	192.168.32.111	6z88m9oEZio
12	192.168.32.112	EggJqL2kWkA
13	192.168.32.113	O11eckHFdVE
14	192.168.32.114	reI0SecUEhI
15	192.168.32.115	crozxT8mA44
16	192.168.32.116	0nP4VZsvr2Q
17	192.168.32.117	Gm2gNqPGzLA
19	192.168.32.119	6tpukvRVugU	(no laptop 18)
x20	192.168.32.120	rwLYnKUNd1M	old 04, spare/retired

aether_api_key: all laptops share a single key per event deployment. The key is created in the Aether admin panel before the show and deleted after. Check builds/seed.json for the current key, or create a new one in Aether (Core → Accounts or Events → Devices API key section) before each deployment.

---

⚙️ Configuration

The application requires a seed.json file to identify the device and connect to the Aether API.

1. Seed Configuration

Location: ~/seed.json (user's home directory — external to the app bundle by design)

This file is intentionally kept outside the application bundle so it can be edited per-device without re-signing or repackaging the app. On macOS this is /Users/speaker ready/seed.json.

Seed file format:

{
  "event_device_id": "tFLL1fLQfnk",
  "aether_api_key": "YOUR_API_KEY",
  "primary_api_base_url": "https://api.oneskyit.com",
  "backup_api_base_url": "https://bak-api.oneskyit.com",
  "onsite_api_base_url": null
}

event_device_id is the id_random from the Aether event_device record for that physical laptop — see the Device Reference table above. aether_api_key is a shared key created per event deployment and deleted after the show.

2. Development Setup

npm install
npm start        # Compiles TypeScript (tsc) then launches Electron

3. File Cache Layout

Presentation files are cached locally under hash_prefix_length-char subdirectories (default: 2):

[local_file_cache_path]/
  4a/
    4a228ef8ac1a...sha256hash...file
  1d/
    1d720916a831...sha256hash...file

Important: hash_prefix_length must be consistent. If it changes, files in old directories become orphaned and will be re-downloaded. The default is 2 and should not be changed unless explicitly coordinated across all devices.

🌉 The Native Bridge (aetherNative)

The bridge is exposed to the renderer via contextBridge. It can be accessed in the web UI via window.aetherNative.

Core Methods

Method	Description
list_tools()	Returns a JSON manifest of all available native functions.
launch_presentation({path, app})	Launches a presentation with auto-focus and slideshow start.
control_presentation({app, action})	Sends next, prev, start, or stop to active decks.
open_folder(path)	Opens a local directory in the OS file explorer.
get_device_info()	Returns hardware metadata (RAM, IPs, Hostname).

Example Usage (UI Relay)

import * as native from '$lib/electron/electron_relay';

// Launch a file from local cache
await native.launch_presentation({ 
    path: '[tmp]/my_deck.pptx', 
    app: 'powerpoint' 
});

// Navigate slides
await native.control_presentation({ 
    app: 'powerpoint', 
    action: 'next' 
});

🛠️ Development

• Preload: Logic defined in src/preload/index.ts.
• Handlers: OS-level logic in src/main/shell_handlers.ts and src/main/file_handlers.ts.
• Types: Shared TypeScript interfaces in src/shared/types.ts.