# 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)

### Hardening & Error Reduction Sprint (2026-01-22)
- **Error Reduction:** Systematically cleared ~133 `svelte-check` errors (from 372 to 239) across the entire application.
- **Type Hardening:**
    - `analytics.svelte`: Moved global `Window` interface declarations to a dedicated module script block to resolve ambient module errors.
    - `element_ae_crud.svelte`: Hardened types for `patch_result` and corrected `core_func.update_ae_obj_id_crud` calls to include required `key` property.
    - `element_codemirror_editor.svelte`: Added null checks and type casting for `editor_container` element assignment.
    - `element_data_store.svelte`: Resolved "used before declaration" errors by correctly sequencing props destructuring and variable initialization.
    - `AE_AITools.svelte`: Added robust fallbacks for optional `model` and `systemPrompt` properties.
    - `ae_sponsorships_functions.ts`: Fixed imports and aligned V3 API calls with consistent `fields` pattern.
- **Cleanup & Standards:**
    - Removed redundant `true` argument from `window.location.reload()` calls across several components (`e_app_cfg`, `e_app_help_tech`).
    - Resolved `onsubmit` type mismatches in `ae_comp__hosted_files_upload.svelte` by transitioning to generic `Event` with internal casting.
    - Hardened QR Scanner and File Table elements with proper parameter typing and element casting.
    - Deleted multiple legacy/unused files (prefixed with `not_used`).

### Hardening & Search Restoration (2026-01-21)
- **Critical Learning: V3 Search Body Strictness:** The `search_query` POST body is extremely strict. Adding non-mapped fields (e.g., `event_location_name`) triggers HTTP 400 "Unauthorized search field" errors.
- **Critical Learning: Preservation of Business Logic:** Specialized search parameters (`ft_qry`, `lk_qry`, `and_qry`) are handled by custom backend logic and MUST be passed as URL query parameters (serialized JSON), not in the search body. These are the "sacred" rules of the Aether system and must not be "cleaned up" during modernization.
- **Critical Learning: Barrel Cleanup Order:** Barrel files (`api.ts`, `ae_core_functions.ts`) must be updated to remove legacy exports *before* deleting code from source files to prevent build-time `SyntaxError` crashes.
- **V3 API Hardening:** Updated `search_ae_obj_v3` to correctly serialize all object-type `params` into the URL, enabling complex filtering like `ft_qry`.
- **Event Session Search:** Restored full business logic mapping for session search, including `ft_qry`, `lk_qry`, and `and_qry`.
- **Service Worker:** Fixed 404 on `/manifest.json` path in `app.html` and restored `service-worker.js` to standard SvelteKit state to resolve evaluation errors.
- **Service Worker Mitigation:** Disabled automatic service worker registration in `svelte.config.js` to resolve persistent `TypeError` during script evaluation. Moved debugging tool to `src/routes/testing/fix-sw/`.

### Hardening & V3 Stabilization (2026-01-20)
- **IDAA Search Hardening:** Isolated IDAA Recovery Meetings to a specialized `qry_ae_obj_li__event_v2` function. Restored full 154-result capacity and implemented "Inclusive OR" location logic (Virtual/In-person).
- **System Lookups Restoration:** Fixed a `TypeError` by correctly exporting `get_ae_obj_li_for_lu` in `api.ts`. Reverted lookup endpoints to stable V2 paths to resolve V3 "Configuration error" 500s. Added Country Subdivisions card to the lookups page.
- **V3 Search Refinement:** Updated general `qry_ae_obj_li__event` to use the standardized `q` property for full-text search and robust "Body + Header" context injection.
- **Git State Resolution:** Resolved a complex 12-commit rebase conflict involving `manifest.webmanifest` and `ae_events__event.ts`. Pushed a clean, branded, and stable state to the remote repository.
- **Crash Prevention:** Hardened meeting detail views with null-checks for `contact_li_json` to handle legacy/incomplete data.

### Hardening & V3 Stabilization (2026-01-19)
- **Structured Error Handling:** Updated `api_get`, `api_post`, and `api_patch` helpers to extract rich metadata (`meta.details`) from V3 API 400/500 responses. Standard FastAPI `detail` fields are automatically wrapped for consistency.
- **JWT Race Condition Fix:** Implemented "Early Injection" in `+layout.ts`. The JWT is now read directly from `localStorage` during bootstrap, ensuring the first requests of a page load are correctly authenticated.
- **Archives Stability:** Resolved a critical async race condition in `load_ae_obj_li__archive` and hardened `_process_generic_props` to handle non-array API responses.
- **Fail-Fast Hardening:** Added HTTP `400` and `422` to the Fail-Fast protocol to prevent unnecessary retries on invalid requests.
- **V3 Hardening Tests:** Enhanced the `/testing` dashboard with "Live V3 Header Inspection" and automated audits for Permissive Mode and Structured Errors.
- **Status:** Main AE Events module verified working with V3 Search; IDAA isolated to V2 for stability.

### Hardening & Svelte 5 Modernization (2026-01-16)
- **Hardening:** Improved resilience for Journals and IDAA modules against API downtime and "ghost" account fallback.
- **Commit:** Atomic refactor of 15 files focusing for type safety, Svelte 5 runes, and API robustness.
- **Fixes:** Resolved download progress crashes in `api_get_object_v1` and corrected event handling in several Svelte 5 components.
- **Status:** Investigating Badge Rendering issues where `badge_template_obj` fails to load despite `badge_obj` being available.

### Config & Stability Sprint (2026-01-14)
- **Standardization:** Refactored Module, Journal, and Entry modals into a unified "Config" pattern with consistent iconography (Wrench/Gear/Zap).
- **Auto-Save:** Implemented background persistence for Status & Security fields using non-blocking API calls.
- **Payload Hardening:** Established a strict whitelisting pattern for update payloads to eliminate HTTP 400 "Unknown column" errors.
- **UX Refinement:** Replaced complex Journal menus with a streamlined "Config" button and dedicated "Quick Actions" tabs.

### Journals Module Refactor (2026-01-08)
- **Modularization:** Extracted `JournalEntry_AITools` and `JournalEntry_Metadata` from the 3000+ line main view.
- **UI/UX:** Standardized on Lucide icons. Implemented 3-state header toggle (View/Eye/Save).
- **CodeMirror:** Migrated to CM6 with `updateListener` pattern for Svelte 5 compatibility.

### Jitsi God Mode (2025-12-15)
- **Architecture:** Hybrid XMPP bot for server-side stats collection, pushing real-time meeting metadata to MariaDB.

### Build & Library Health (2025-12-08)
- **Upgrades:** Successfully updated to SkeletonLabs v4.7.4 and Flowbite-Svelte v4.0.1.
- **Staging:** `npm run build:staging` verified and clean of import/export errors.

---

## 🧠 Session Context (2026-01-23)
- **Status:** Phase 4 Implementation Complete (Telemetry/Heartbeat).
- **Recent Actions:**
    - Standardized Electron bridge to `snake_case` across all methods.
    - Implemented organized caching with mandatory 2-char subdirectories.
    - Verified Phase 3 OS commands (`run_cmd`, `run_osascript`, `kill_processes`).
    - Implemented exhaustive recursive room data fetching in `ae_events__event_location.ts`.
    - Hardened bootstrap to preserve local overrides for sync timers.
- **Pending Tasks:**
    - Verify heartbeat visibility in Launcher UI.
    - Implement Phase 5 AppleScript handlers for PowerPoint/Keynote.
    - Build Telemetry Dashboard in Launcher Config.

## 🔗 Resources
- **Reference Stubs:** `agents_sync/technical/references/` (Svelte 5, Dexie, FastAPI).
- **Official Docs:** [Svelte Runes](https://svelte.dev/blog/runes) | [Dexie Quick Ref](https://dexie.org/docs/API-Reference#quick-reference)