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

Functional Specification: Aether Native App (Electron)

Date: 2026-01-30 Status: V5 / Phase 5 Specification Target OS: macOS (Primary), Linux/Windows (Secondary)

1. Core Objectives

The Native App acts as a "Privileged Shell" for the Aether SvelteKit UI, providing capabilities that standard web browsers block for security reasons. It turns a standard laptop into a managed "Podium Kiosk."

2. macOS Permission Matrix (TCC)

To function as a podium controller, the Electron app requires specific entitlements.

Permission	Reason	Criticality
Accessibility	Required to send AppleScript commands (Next/Prev) to Keynote and PowerPoint.	CRITICAL
Screen Recording	Required by the aperture utility to record the presentation session.	CRITICAL
Microphone	Required to capture room audio/presenter voice during recording.	CRITICAL
Camera	Optional, only if "Presenter View" (PiP) recording is enabled.	Low
Automation	Allows the app to control "System Events", "Finder", "Keynote", and "Microsoft PowerPoint".	CRITICAL
Full Disk Access	Recommended to ensure access to ~/OSIT and ~/Downloads without nagging prompts.	High

3. Handler Registry (V5)

The following IPC handlers are exposed via window.aetherNative.

3.1 File & Cache System

Handler	Description
native:check-cache	Verifies file existence in the sharded local cache (~/OSIT/native_app/cache/xx/hash.file).
native:download-to-cache	Streams a file from the API to the local cache with SHA-256 verification.
native:launch-from-cache	Atomic Launch: Copies file from cache -> temp with original filename -> launches app.

3.2 Automation & Control (Phase 5)

Handler	Description
native:launch-presentation	Opens a file using the specific app (Keynote/PPT) with "Slide Show" mode enabled immediately.
native:control-presentation	Sends navigation commands: next, prev, start, stop.
native:kill-processes	Force quits applications by name (e.g., "Microsoft PowerPoint") to resolve freezes.

3.3 System Management (New Requirements)

These handlers are required for full "Kiosk" management.

Handler	Description	Implementation Note
native:set-wallpaper	Resets desktop background to a specific image.	AppleScript: tell application "System Events" to set picture of every desktop...
native:update-app	Checks ~/OSIT/admin_share/... for newer versions and self-updates.	Requires specific logic to swap the .app bundle and restart.
native:window-control	Controls the Electron window: maximize, minimize, kiosk, devtools.	Direct Electron BrowserWindow API calls.
native:manage-recording	Controls aperture process: start, stop, status.	Must track the PID of the spawned recording process.
native:set-display-layout	Toggles between Mirror and Extended modes.	Use bundled displayplacer binary (AppleScript is unreliable for this).
native:power-control	Initiates shutdown or restart.	Command: shutdown -h now (may require admin/sudo setup or user-level fallback).
native:open-external	Opens a URL in a specific browser (Chrome/Firefox).	spawn('open', ['-a', 'Google Chrome', url]).

4. Feature Specifications

4.1 Self-Update Strategy

1. Path: ~/OSIT/Speaker Ready System/Admin Share/Custom Applications/osit_binaries/
2. Logic:
   • Compare package.json version in running app vs. remote path.
   • If remote > local:
   • Display "Updating..." splash.
   • Copy new .app to /Applications (or current location).
   • Relaunch.

4.2 Web Page Handling

The Launcher avoids Safari.

• Strategy A (Simple): native:open-external -> Opens in Google Chrome Kiosk Mode (--kiosk).
• Strategy B (Integrated): Use an Electron BrowserView (not iframe) to render the website inside the Aether window, ensuring we keep the "Back" button overlay visible.

4.3 Display Layouts

To reliably switch between Mirroring (for setup) and Extended (for presentation):

• Tool: Bundle displayplacer (Homebrew utility) inside resources/bin.
• Command: displayplacer "id:<main> res:1920x1080" "id:<proj> res:1920x1080 origin:(1920,0)" (Example).

5. Security Guardrails

• IPC Whitelisting: All run-cmd calls are deprecated in favor of specific named handlers (e.g., set-wallpaper) to prevent arbitrary command execution.
• Path Validation: All file operations must be restricted to ~/OSIT or ~/tmp directories.