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