cdf318e744
- Implemented 'untrack' safeguards in all modal effect blocks to prevent reactivity loops. - Standardized Module, Journal, and Entry configuration with unified tabbed UI and Aether Orange theme. - Fixed critical 'journal is undefined' and ReferenceErrors in configuration modals. - Restored missing button toggles and visibility options in journal-level settings. - Documented Dexie liveQuery '$' prefix mandate in GEMINI.md and project documentation. - Eliminated legacy JournalEntry_SettingsMenu in favor of ModalJournalEntryConfig.
137 lines
7.6 KiB
Markdown
137 lines
7.6 KiB
Markdown
# Aether Journals UI Update (2026)
|
|
|
|
> **Status:** 🚧 Stuck on Phase 4 (Security/Encryption Blockers)
|
|
> **Last Updated:** 2026-01-14
|
|
> **Primary Agent:** Frontend SvelteKit Agent
|
|
|
|
## 1. Project Overview
|
|
This document outlines the modernization of the Journals module UI in the SvelteKit frontend (`aether_app_sveltekit`). The primary goals are to fully leverage the generic V3 API architecture and introduce high-velocity productivity features for journal management.
|
|
|
|
**Context:** The backend transition to the generic `api_crud_v3` router is complete. Custom legacy routers have been removed. The frontend must now fully align with this pattern and provide a frictionless user experience.
|
|
|
|
---
|
|
|
|
## 2. Core Objectives
|
|
|
|
### 🎯 Primary Goals
|
|
1. **V3 API Verification:** Ensure all CRUD operations utilize the generic `api_crud_v3` endpoints (Verified).
|
|
2. **Quick Add UI:** Implement a specialized interface for rapid, friction-free entry creation.
|
|
3. **Append/Prepend UI:** Allow users to quickly add text to the beginning or end of existing entries without full edit mode.
|
|
4. **Interop & Portability:** Robust import/export logic for Markdown/HTML (Nextcloud Notes compatibility).
|
|
5. **Security Hardening:** Review and harden client-side encryption logic (BLOCKED).
|
|
|
|
---
|
|
|
|
## 3. Technical Architecture
|
|
|
|
### Backend (Completed)
|
|
* **Router:** `api_crud_v3` (Generic)
|
|
* **Definitions:** `app/ae_obj_types_def.py` -> `app/object_definitions/journals.py`
|
|
* **Endpoints:** `/v3/crud/journal/...` and `/v3/crud/journal_entry/...`
|
|
|
|
### Frontend (In Progress)
|
|
* **State Management:** `src/lib/ae_journals/ae_journals_stores.ts`
|
|
* **Local Storage:** Dexie.js (`db_journals`)
|
|
* **API Client:** `src/lib/api/api.ts` -> `get_ae_obj_v3`
|
|
* **Export Engine:** Centralized templates in `src/lib/ae_journals/ae_journals_export_templates.ts`.
|
|
|
|
---
|
|
|
|
## 4. Feature Specifications
|
|
|
|
### ⚡ Quick Add (Complete)
|
|
* **Component:** `src/routes/journals/ae_comp__journal_entry_quick_add.svelte`
|
|
* **Behavior:** Creates a new `journal_entry` attached to the active journal without leaving the list view.
|
|
|
|
### 📝 Append / Prepend (Complete)
|
|
* **Interaction:** Fast text injection via `AeCompModalJournalEntryAppend`.
|
|
* **Logic:** Updates entry content without full editor state overhead.
|
|
|
|
### 🔄 Interop (Markdown/HTML) (Complete)
|
|
* **Goal:** Bulk export/import for data portability.
|
|
* **Templates:** Standard, Personal Log, Amazon Vine.
|
|
|
|
---
|
|
|
|
## 5. Implementation Plan
|
|
|
|
### Phase 1: Foundation (Done)
|
|
- [x] Backend cleanup (remove legacy routers).
|
|
- [x] Verify frontend uses V3 API (`ae_journals__journal.ts`).
|
|
|
|
### Phase 2: Rapid Entry (Complete)
|
|
- [x] Create `ae_comp__journal_entry_quick_add.svelte`.
|
|
- [x] Integrate Quick Add into `+page.svelte`.
|
|
|
|
### Phase 3: Content Manipulation & Portability (Complete)
|
|
- [x] Implement Append/Prepend logic.
|
|
- [x] Implement Bulk Export/Import system.
|
|
- [x] Establish centralized Export Template engine.
|
|
|
|
### Phase 4: Polish & Security (ACTIVE)
|
|
- [x] Implement Auto-Save toggle and visual status indicators.
|
|
- [x] Extract decryption workflow to non-reactive helper.
|
|
- [x] **Standardize Configuration Modals:** Refactored Module, Journal, and Entry configuration into a unified tabbed UI.
|
|
- [x] **RESOLVED:** Decryption workflow stability (Fixed via dependency isolation).
|
|
- [ ] Solidify E2EE passcode system for Journals and Entries.
|
|
- [ ] Audit encryption flow for Quick Added and Imported entries.
|
|
- [ ] Integrate Outbound Email sharing.
|
|
|
|
---
|
|
|
|
## 🧠 Lessons Learned: Solving the Svelte 5 Reactivity Hang
|
|
|
|
During the implementation of the Privacy/Decryption toggle and the new Configuration Modals, we encountered critical browser hangs caused by infinite reactivity loops. Here is how we resolved them:
|
|
|
|
### 1. Rigorous Dependency Isolation (`untrack`)
|
|
Svelte 5 runes (`$effect`, `$derived`) automatically track **every** reactive variable read inside them.
|
|
* **The Problem:** An effect would read `save_status` or `tmp_entry_obj.content` to decide if it should sync, but the act of syncing would update those same variables, re-triggering the effect.
|
|
* **The Fix:** Wrap any "check-only" state or store reads in `untrack(() => ... )`. This allows the effect to use the value without becoming a dependency of it. This is **CRITICAL** when initializing local state from props inside an effect.
|
|
|
|
### 2. Standardized Modal UI ("Aether Orange")
|
|
We have established a unified design language for configuration interfaces:
|
|
* **Header/Footer:** Use `bg-orange-100 dark:bg-orange-900` with consistent borders.
|
|
* **Tabs:** Center-aligned tabbed navigation using Skeleton UI `btn` and `variant-filled-primary` / `variant-soft-surface`.
|
|
* **Icons:** Every tab and primary action should have a Lucide icon for better scannability.
|
|
* **Explicit Persistence:** All configuration modals must follow an "Edit working copy -> Save Changes" pattern to prevent accidental store/API churn.
|
|
|
|
### 3. Dexie LiveQuery Subscriptions
|
|
* **The Problem:** Accessing `liveQuery` observables directly in templates results in `[object Object]` or `undefined` property errors.
|
|
* **The Mandate:** ALWAYS use the `$` prefix (e.g. `$lq__obj`) when passing or using data from a Dexie `liveQuery`.
|
|
|
|
### 4. Manual Deep Copying vs. Proxies
|
|
Svelte 5 state is backed by Proxies.
|
|
* **The Problem:** Using `JSON.parse(JSON.stringify(proxy))` can sometimes trigger unexpected behavior or loops when used inside a reactive context.
|
|
* **The Fix:** Implement a manual `deep_copy` helper or selective property assignment when syncing "Original" vs "Temporary" state. This ensures `orig_entry_obj` is a plain JS object, making the `has_unsaved_changes` check stable.
|
|
|
|
### 3. Concurrency Locking (`is_processing`)
|
|
* **The Problem:** Decryption (Async) and Auto-Save (Debounced Async) can fire nearly simultaneously.
|
|
* **The Fix:** Use a simple `is_processing` boolean flag. If any async workflow is active, block others from starting and prevent the `has_unsaved_changes` derived rune from reporting `true`.
|
|
|
|
### 4. Comparison Normalization
|
|
* **The Problem:** Trivial differences (e.g., `null` vs `""` or trailing whitespace) would trigger "unsaved changes" and fire the save loop.
|
|
* **The Fix:** Use a `normalize()` function in the `has_unsaved_changes` derived rune to trim strings and treat `null/undefined` as empty strings during comparison.
|
|
|
|
---
|
|
|
|
## ⚠️ Technical Blocker: The "Decryption-Sync" Loop (Resolved)
|
|
|
|
### The Issue
|
|
The component is suffering from a **Reactive Feedback Loop** between decryption, auto-save, and background IDB refreshes.
|
|
1. **Decrypting content** triggers a change in `tmp_entry_obj.content`.
|
|
2. The **Auto-Save effect** sees this as a manual user edit and saves to the database.
|
|
3. **Dexie LiveQuery** detects the DB update and refreshes the object.
|
|
4. The **Sync effect** resets the entry to its encrypted state (from DB).
|
|
5. The **Auto-Decryption effect** fires again, starting the loop over.
|
|
|
|
### What we tried:
|
|
* **`is_processing` flags:** Attempted to block reactivity during decryption.
|
|
* **`untrack()`:** Attempted to isolate store updates.
|
|
* **Reference Sync:** Attempted to update `orig_entry_obj` simultaneously with decryption to fool the change detector.
|
|
* **Direct Store Updates:** Switching from property assignment to `journals_sess.update()` to fix Svelte 5 notification failures.
|
|
|
|
### Future Fix Ideas:
|
|
1. **Native Svelte 5 State:** Refactor `journals_sess` from a Svelte 4 `Writable` to a class using `$state`.
|
|
2. **Logic Extraction:** Move decryption logic into a non-reactive class/helper to isolate side effects from the UI render cycle.
|
|
3. **Hash Comparison:** Use content hashes for change detection instead of string comparisons to avoid whitespace/normalization loops.
|