Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix: Restore Native caching business logic and implement 3-mode launcher

Browse Source 
- Implemented Default, Onsite, and Native launcher modes in launcher_file_cont.svelte.
- Restored background pre-caching logic with configurable timers in new LauncherBackgroundSync component.
- Fixed standard browser download regression for regular website mode.
- Modernized electron_relay to TypeScript and standardized bridge detection in layout.
- Detailed startup and background sync technical flow in documentation.
This commit is contained in:
Scott Idem
2026-01-23 15:17:50 -05:00
parent 20b41ebaef
commit 683ea0394d
11 changed files with 558 additions and 961 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
documentation/NATIVE_APP_V3_REWRITE_PLAN.md
View File

@@ -11,6 +11,17 @@ The sole purpose of this Native App is to serve as the **AE Events Launcher**. I
- Execute OS-level shell commands and scripts (e.g., launching presentation software).
- Provide a "Zero-Config" experience for onsite event laptops.
### 0.1 Application Modes
The system must support three distinct operational modes:
| Mode | Refresh Logic | File Handling |
| --- | --- | --- |
| **Default** | Slower auto-refresh timers. | Standard browser downloads. No local caching. |
| **Onsite** | Faster auto-refresh timers. | Downloads files with modified extensions (e.g., .pptxwin). |
| **Native** | Fastest auto-refresh timers. | Full background pre-caching. Launching from local temp directory with original names. |
---
## 1. Minimalist Configuration Strategy
To simplify laptop deployment, we will move away from large local JSON files.
@@ -36,6 +47,76 @@ Each laptop will contain a `seed.json`. For development, this is located at `~/s
`http://[app_base_url]/events/[event_id]/launcher/[event_location_id]`
5. **Inject:** Config and JWT are injected into the SvelteKit frontend via the Preload script.
### 1.3 Technical Flow: Startup & Background Caching
The system utilizes a multi-layered hydration and synchronization strategy to ensure files are available instantly.
#### Step 1: Zero-Config Initialization (Main Process)
- **Seed Discovery:** Main process reads `seed.json`.
- **Identity Exchange:** Main process authenticates with the API using the `aether_api_key`.
- **Global Injections:** Once hydrated, the Main process provides the SvelteKit frontend with:
- `native_device`: Full record from `event_device` table (contains timers).
- `aether_api_key`: For authorized background downloads.
- `local_file_cache_path`: Root for the permanent hashed cache.
- `host_file_temp_path`: Root for the operational launch directory.
#### Step 2: Session-Driven Caching (Renderer Process)
- **View Trigger:** When a user navigates to a session or location, the SvelteKit frontend populates the `event_file_obj_li` store.
- **Sync Cycle:** The `LauncherBackgroundSync` component detects the new file list and:
1. Extracts all `event_file_id` values.
2. Fetches full metadata (hashes) from the local Dexie IndexedDB.
3. Asynchronously checks the Native Cache for each hash.
- **Background Download:** Missing files are downloaded directly to the hashed cache using the authorized Native API Key.
- **Timer Loop:** A background loop runs every `check_event_loop_period` (configurable via API) to ensure the cache stays in sync with server-side changes.
#### Step 3: Hashed Cache Pattern (Filesystem)
To prevent filename collisions and handle versioning, the permanent cache follows the server's structure:
- **Root:** `[local_file_cache_path]`
- **Subdirectory:** First 2 characters of SHA256 (e.g., `ab/`)
- **Filename:** Full SHA256 with `.file` extension (e.g., `abc123...file`)
#### Step 4: Safe Handover (Launch Sequence)
When a user clicks "Open", the system follows a non-destructive handover:
1. **Verify:** Confirm hash exists in `local_file_cache_path`.
2. **Prepare:** Copy the hashed file to `host_file_temp_path`.
3. **Restore:** Rename the copy back to its original filename (e.g., `Presentation.pptx`).
4. **Execute:** Trigger OS-level `shell.openPath()` on the temp file.
*This ensures the permanent cache remains clean while the third-party app (PowerPoint, etc.) can operate on a file with a familiar name.*
### 1.3 Technical Flow: Startup & Background Caching
The system utilizes a multi-layered hydration and synchronization strategy to ensure files are available instantly.
#### Step 1: Zero-Config Initialization (Main Process)
- **Seed Discovery:** Main process reads `seed.json`.
- **Identity Exchange:** Main process authenticates with the API using the `aether_api_key`.
- **Global Injections:** Once hydrated, the Main process provides the SvelteKit frontend with:
- `native_device`: Full record from `event_device` table (contains timers).
- `aether_api_key`: For authorized background downloads.
- `local_file_cache_path`: Root for the permanent hashed cache.
- `host_file_temp_path`: Root for the operational launch directory.
#### Step 2: Session-Driven Caching (Renderer Process)
- **View Trigger:** When a user navigates to a session or location, the SvelteKit frontend populates the `event_file_obj_li` store.
- **Sync Cycle:** The `LauncherBackgroundSync` component detects the new file list and:
1. Extracts all `event_file_id` values.
2. Fetches full metadata (hashes) from the local Dexie IndexedDB.
3. Asynchronously checks the Native Cache for each hash.
- **Background Download:** Missing files are downloaded directly to the hashed cache using the authorized Native API Key.
- **Timer Loop:** A background loop runs every `check_event_loop_period` (configurable via API) to ensure the cache stays in sync with server-side changes.
#### Step 3: Hashed Cache Pattern (Filesystem)
To prevent filename collisions and handle versioning, the permanent cache follows the server's structure:
- **Root:** `[local_file_cache_path]`
- **Subdirectory:** First 2 characters of SHA256 (e.g., `ab/`)
- **Filename:** Full SHA256 with `.file` extension (e.g., `abc123...file`)
#### Step 4: Safe Handover (Launch Sequence)
When a user clicks "Open", the system follows a non-destructive handover:
1. **Verify:** Confirm hash exists in `local_file_cache_path`.
2. **Prepare:** Copy the hashed file to `host_file_temp_path`.
3. **Restore:** Rename the copy back to its original filename (e.g., `Presentation.pptx`).
4. **Execute:** Trigger OS-level `shell.openPath()` on the temp file.
*This ensures the permanent cache remains clean while the third-party app (PowerPoint, etc.) can operate on a file with a familiar name.*
## 2. macOS Hardening (Permissions)
...
macOS requires explicit user consent for several features. The new app will handle these during the "Splash Screen" phase.