OSIT-AE-App-Svelte/GEMINI.md

Aether (AE) SvelteKit Application

This project is the frontend UI/UX for the Aether (AE) system, built with Svelte 5 (SvelteKit), Tailwind CSS, and Skeleton. It interfaces with a Python FastAPI backend.

🎯 Core Mandates (Safety & Efficiency)

• Fast is slow. Slow is fast. Deliberate, careful progress is better than rushed, error-prone actions.
• Fail fast. If a change breaks the system, revert immediately to the last known working version before attempting a new fix.
• Commit early and often. Working changes MUST be committed before starting major new modifications. Always test before committing.
• Verify. Perform syntax checks and basic compile verification before finalizing any code change.
• Trust but verify. Always verify tool outputs, assumptions, and system state before proceeding.

🏗️ Architecture & Standards

Reactivity & Stores

• Svelte 5 Runes: Use $state, $derived, and $effect for component-level reactivity.
• Dexie LiveQuery: Results from liveQuery are observables. You MUST use the $ prefix (e.g., $lq__obj) in templates and logic to subscribe to the live data. Failure to do so will result in accessing the observable object instead of its data.
• Persistence: Use svelte-persisted-store for data that must survive page refreshes (e.g., ae_loc, journals_loc).
• Initialization: Always initialize reactive state ($state) outside of $props() destructuring. Use untrack inside $effect when synchronizing props to local state to prevent infinite loops.

ID Convention (Triple-ID Pattern)

• Standard: Use id, [obj_type]_id, and [obj_type]_id_random consistently.
• Primary Key: Always use _id_random (string) for routing, data fetching, and local storage.
• Local Storage: Alias id_random to both id (PK) and [obj_type]_id when saving to Dexie.

API V3 Implementation

• Robustness: Use the standardized primary helpers (get, post, patch, delete) in src/lib/ae_api/.
• SSR Parity: Helpers support custom fetch injection for SvelteKit server-side execution.
• Bootstrap Paradox: Use the unauthenticated bypass (x-no-account-id: "Nothing to See Here") for site/domain lookups.
• Envelopes: Helpers automatically handle the {data: ...} envelope returned by the backend.

Data Pattern

1. Fetch: API Function calls the V3 endpoint.
2. Process: Dedicated process_ae_obj__*_props function handles data shaping, parent ID injection, and computed fields.
3. Cache: Save cleaned data to IndexedDB via db_save_ae_obj_li__ae_obj.

---

🛠️ Tooling & Orchestration

Aether Ops (MCP Extension)

• verify_api_integrity: Headless verification of the FastAPI stack.
• schema_sync: Syncs Pydantic models to TypeScript interfaces in src/lib/types/ae_types.ts.
• ae_obj_info: Metadata lookup for Aether objects.
• UE-AE-01 Vision: Moving towards a unified agent with total system awareness across MariaDB, FastAPI, SvelteKit, and Nginx.

---

📂 Modules Overview

Core Modules

• Identity: accounts, people, users.
• Infrastructure: sites, site_domains.
• Storage: hosted_files.

Feature Modules

• Events: Presentation management, Badge printing, QR tracking.
• Journals: Documentation, notes, and AI-assisted summarization.
• IDAA: Client-specific logistics and video conferencing (Jitsi).

---

📝 Development History (Consolidated)

Launcher Phase 5 & Performance Sprint (2026-01-26)

• Hydration Optimization: Implemented Stale-While-Revalidate (SWR) pattern and non-blocking layouts across Sites, Events, and Journals to eliminate "white page" delays.
• Service Worker: Re-enabled automatic registration and implemented robust asset caching using SvelteKit metadata.
• Native Bridge: Implemented Phase 5 AppleScript handlers for PowerPoint and Keynote on macOS.
• Telemetry: Built a modern dashboard in Launcher Config with visual CPU/RAM gauges and animated sync status.
• API Hardening: Silenced noisy AbortError and NetworkError logs in background fetches.

Launcher Phase 4 & Hardening (2026-01-26)

• Heartbeat Engine: Implemented V3-compliant heartbeat and room refresh cycles.
• UI Integration: Migrated heartbeat/sync status from "Secret Monitor" to formal Launcher Config Drawer. ...

---

🧠 Session Context (2026-01-26)

• Status: Performance Sprint & Journals Standardization Complete.
• Recent Actions:
  • Eliminated page load delays via SWR and non-blocking background refreshes.
  • Standardized Journals module: renamed all components to ae_comp__*, normalized props to snake_case, and unified icons under lucide-svelte.
  • Fixed line-wrapping issues in both plain and CodeMirror editors.
  • Optimized Event Session list rendering with a "Details" toggle to defer expensive sub-components.
  • Hardened Service Worker and suppressed aborted fetch logs.
  • Finalized Native Launcher Phase 5 automation and Telemetry UI.
• Pending Tasks:
  • Refactor get_device_config to be non-blocking in root layout.
  • Audit IDAA pages for reported issues.
  • Restore Exhibit Search functionality.
  • Build standalone Payload Validation tool.

🔗 Resources

• Reference Stubs: agents_sync/technical/references/ (Svelte 5, Dexie, FastAPI).
• Official Docs: Svelte Runes | Dexie Quick Ref