43 lines
3.2 KiB
Markdown
43 lines
3.2 KiB
Markdown
# Aether Frontend Agent Context: Gemini CLI Standard
|
|
> **Role:** Aether App Orchestrator (SvelteKit Frontend)
|
|
> **Location:** GEMINI.md (Project Root)
|
|
|
|
## 🚨 MANDATORY PROTOCOL
|
|
You must follow the safety, testing, and coordination standards defined in:
|
|
`documentation/GUIDE__DEVELOPMENT.md`
|
|
|
|
---
|
|
|
|
## 🏗️ Technical Domain: Aether Frontend
|
|
### Stack & UI Standards
|
|
- **Framework:** SvelteKit v2 + Svelte 5 (Runes)
|
|
- **Styling:** Tailwind 4 + Skeleton UI + Skeleton V3 (SkeletonNext)
|
|
- **Local Cache:** Dexie.js (IndexedDB)
|
|
- **Icons:** Standardizing on **Lucide-Svelte**. Avoid legacy Font-Awesome where possible.
|
|
|
|
### Reactivity Patterns (The "Aether Way")
|
|
- **Svelte 5 Runes:** Use `$state`, `$derived`, and `$effect`.
|
|
- **Navigation Shield:** Use SvelteKit's `page.url` searchParams as the single source of truth for navigation-driven selection. Sync to global stores only via `untrack()` within effects.
|
|
- **Side-Effect Purge:** Keep `liveQuery` observables pure. Do NOT update global stores ($events_slct) inside derived observables to prevent infinite reactivity loops.
|
|
- **Dexie LiveQuery:** Use the `$` prefix (e.g., `$lq__obj`) consistently. Results from `liveQuery` are observables.
|
|
- **Initialization:** Always initialize reactive state (`$state`) outside of `$props()` destructuring.
|
|
|
|
### Performance & Data
|
|
- **SWR (Stale-While-Revalidate):** Never block SvelteKit `load` functions with API calls for cached data. Let the UI render instantly from IndexedDB and update reactively.
|
|
- **Triple-ID Pattern:** Map `id`, `[obj_type]_id`, and `[obj_type]_id_random` consistently.
|
|
- **ID Vision:** The backend uses String IDs. Primary keys should use `_id` or `id` (String) mapping to backend `id_random`.
|
|
|
|
## 🧠 Recent Strategy & Patterns
|
|
- **Safe Handover (Native):** Rename `.tmp` to `.file` ONLY after SHA-256 verification in Electron.
|
|
- **Envelopes:** API helpers automatically handle the `{data: ...}` envelope returned by the backend.
|
|
- **Bootstrap Paradox:** Use unauthenticated bypass (`x-no-account-id: "Nothing to See Here"`) for initial site/domain lookups.
|
|
- **Sev-1 Incident Recovery (2026-02-13):** Purged redundant/misplaced headers (`x-aether-api-token`, `Access-Control-Allow-Origin`). Unified all CRUD helpers to standard `/v3/crud/...` paths.
|
|
- **Account ID Scavenging:** Core fetch helpers now proactively read `account_id` from `localStorage` (`ae_loc`) if missing from config. This is the mandatory fix for Svelte 5 hydration race conditions where `onMount` triggers API calls before global stores are synced.
|
|
- **V3 Event File Mapping (2026-02-19):** Mapped prefixed backend fields (`hosted_file_hash_sha256`, `hosted_file_size`) to flat properties (`hash_sha256`, `file_size`) in the data layer. Required `inc_hosted_file=true` query param for full metadata retrieval.
|
|
- **Launcher Location Discovery:** Resolved missing locations in room select by ensuring `load_ae_obj_li__event_location` requests `hidden: 'all'` during background sync and initial load.
|
|
|
|
## 🤝 Coordination & Continuity
|
|
- **Handshake:** Use the `message` tool to notify the Backend Agent of UI/Data requirements.
|
|
- **Active Tasks:** Track your progress in `documentation/AGENT_TODO.md`.
|
|
- **Reference:** See `README.md` for build/deploy steps and `TODO.md` for project milestones.
|