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

Specification: Aether Native V3 Bridge Interface

Namespace: window.native_app Security: Context Isolated, Sandboxed IPC

1. Device & Identity (ae_device)

Functions for bootstrapping the app from the seed.json.

Method	Type	Description
getSeed()	() => Promise<SeedConfig>	Returns the local event_device_id and api_base_url.
getDeviceInfo()	() => Promise<DeviceInfo>	Returns OS, Arch, and unique hardware UUID.
getPermissions()	() => Promise<PermStatus>	Returns status of Mic, Camera, and Accessibility.
requestAccess()	(type: string) => Promise<boolean>	Triggers macOS TCC permission prompts.

2. Sync Engine (ae_sync)

The Sync Engine manages the "Cold Cache" (~/Library/Caches/Aether/). It handles atomic downloads and hash verification.

Method	Type	Description
getCacheStatus()	(file_hash: string) => Promise<CacheInfo>	Checks if a file exists and is valid.
startSync()	(task: SyncRequest) => Promise<void>	Begins background download of a presentation.
cancelSync()	(file_hash: string) => Promise<void>	Aborts an active download.
clearCache()	() => Promise<void>	Wipes the cold cache (Maintenance).

Events (Main -> Renderer)

• sync:progress: { hash, percent, speed, bytesLoaded }
• sync:complete: { hash, success, error }

3. Launcher (ae_launcher)

The "Big Red Button" logic. Handles the hand-off to the OS.

Method	Type	Description
launch()	(req: LaunchRequest) => Promise<void>	1. Moves file to Temp. 2. Opens with default app. 3. Starts slideshow.
killApp()	(appName: string) => Promise<void>	Closes PowerPoint/Keynote/Acrobat gracefully.
preventSleep()	(enable: boolean) => Promise<void>	Prevents the laptop from sleeping during a session.

4. System Control (ae_sys)

Low-level macOS/Windows/Linux wrappers.

Method	Type	Description
setVolume()	(level: number) => Promise<void>	Sets system master volume (0-100).
checkForUpdates()	() => Promise<UpdateStatus>	Checks the Syncthing share for a newer version.
applyUpdate()	() => Promise<void>	Triggers the update_helper.sh and exits.
execIntent()	(intent: string, args: any) => Promise<any>	Executes a whitelisted command (e.g. open-logs-folder).

---

5. TypeScript Interface (Draft)

export interface AE_Native_Bridge {
  device: {
    getSeed: () => Promise<{ device_id: string; api_url: string }>;
    requestPermissions: () => Promise<void>;
  };
  sync: {
    getStatus: (hash: string) => Promise<{ exists: boolean; verified: boolean }>;
    queueDownload: (payload: { url: string; hash: string; jwt: string }) => void;
  };
  launcher: {
    launch: (file: { hash: string; name: string; type: 'pptx'|'key'|'pdf' }) => Promise<boolean>;
    killAll: () => Promise<void>;
  };
}

6. Podium Reliability Protocol

To ensure the podium never fails:

1. Pre-Flight Check: The SvelteKit UI will call sync.getStatus for every file in the session as soon as the page loads.
2. Auto-Warmup: If a file is missing, the UI automatically calls sync.queueDownload in the background.
3. Verification: The launcher.launch command will perform a final sha256 check on the temp file before executing shell.openPath.