Files

Scott Idem 55773a332d refactor: harden type safety and modernize core forms for Svelte 5

- Standardize 'ae_BaseObj' and event types in 'ae_types.ts' to handle nullable fields from V3 API/Dexie.
- Modernize Person, Address, and Contact forms with Svelte 5 Runes and reactive synchronization.
- Refactor Event Settings and its sub-components to use the 'onsave' callback pattern, removing deprecated dispatchers.
- Hardened 'element_data_store_v2' with safe initialization and localStorage caching logic.
- Clean up unused 'element_data_store.svelte' (V1) and suppress Electron environment type errors in 'tmp_shell_handlers.ts'.
- Update documentation and workspace settings to reflect Phase 5 reactive patterns.

2026-01-28 14:40:20 -05:00

3.9 KiB

Raw Blame History

Aether Native Electron App - V3 Architecture (2026)

1. Overview

The Aether Native App serves as the OS-level bridge for the SvelteKit frontend. It enables functionality that is normally restricted by browser sandboxing, such as local filesystem management, hardware telemetry, and direct control of third-party presentation software (PowerPoint, Keynote, LibreOffice).

Core Tasks (Completed Jan 2026):

[Infrastructure]: Restore AE Events Presentation Launcher (Electron) (ID: 221513945)
[Frontend]: V3 File Caching: Implement Launcher CRUD Migration (ID: 173518010)
[Frontend]: Native App Bridge: Standardize Electron IPC (ID: 173448078)

2. The Three-Layer Architecture

2.1 The Engine (`src/main/*.ts`)

Process: Main Process (Node.js/TypeScript)
Role: Performs the actual OS-level operations.
Key Responsibilities:
- Shell Handlers (shell_handlers.ts): Executing shell commands, AppleScripts, and process management.
- File Handlers (file_handlers.ts): Managing the permanent Hashed Cache (file_cache/) and atomic Safe Handover.
- Resolving global path placeholders like [home] and [tmp] via file_utils.ts.

2.2 The Bridge (`src/preload/index.ts`)

Process: Preload Script
Role: The security gatekeeper.
Key Responsibilities:
- Uses Electron's contextBridge to securely expose Main Process functions to the UI.
- Exposes the window.aetherNative object.
- Ensures that only whitelisted IPC channels can be triggered by the renderer.

2.3 The Messenger (`src/lib/electron/electron_relay.ts`)

Process: Renderer Process (SvelteKit)
Role: The TypeScript API used by Svelte components.
Key Responsibilities:
- Standardizing IPC calls to snake_case.
- Implementing "Smart Fallbacks" (e.g., UI-side placeholder resolution if the bridge is inactive).

3. Core Lifecycle

Seed Phase: The Electron shell reads resources/seed_config.json to identify the device.
Hydration Phase: The shell authenticates with the Aether V3 API to pull device-specific settings.
Injection Phase: The shell injects the JWT and Native Config into the SvelteKit environment.
Observation Phase: Background sync loops manage file warming and heartbeat telemetry.

4. Native Tool Library (`window.aetherNative`)

File & Cache Management

check_cache({hash}): Verify if a file exists in the hidden hashed storage.
download_to_cache({url, hash}): Secure background download using the native API key.
launch_from_cache({hash, filename}): Safe Handover — copies from cache to temp with the original name and triggers the specialized launcher.

OS Execution (The "Actuators")

launch_presentation({path, app}): Phase 5 specialized launcher with auto-focus (activate) and slideshow start.
- Linux: Triggers libreoffice --impress.
- macOS: Triggers AppleScript for Keynote or PowerPoint.
control_presentation({app, action}): Remote navigation for active decks.
- Actions: next, prev, start, stop.
run_cmd({cmd}): Executes raw shell commands with automatic path resolution.
kill_processes([names]): Force-closes apps to clean the podium.

Metadata & Discovery

get_device_info(): Provides CPU/RAM stats and absolute system paths.
list_tools(): Returns a JSON manifest of all available native functions for self-documentation.

5. Path Placeholder System

To maintain cross-platform compatibility, the system uses a placeholder syntax for all paths:

[home]: Resolves to the user's home directory (e.g., /home/scott or /Users/scott).
[tmp]: Resolves to the system temporary directory.

Resolution Logic: All native handlers utilize a global regex (/\[home\]/g) to ensure these are converted to absolute paths before any disk or shell operation occurs.

3.9 KiB Raw Blame History