OSIT-AE-App-Svelte/GEMINI.md

Aether (AE) SvelteKit Application

This project is a Svelte and SvelteKit based application, part of the Aether (AE) system. It uses Tailwind CSS and Skeleton for styling and some elements. This is the frontend UI/UX. The backend API uses Python FastAPI.

Core Aether modules

• accounts - client account, not user account
• hosted_files
• people
• users
• sites and site_domains

Additional Aether modules

• events
  • presentation management - import the program data (events, session, presentations, presenters, event files, locations/rooms, devices)
  • launcher - Technically this is used with presentation management. It is part of the native app that uses Electron. One of the libraries is for functions that only work when the site is opened in an Electron app. For example the regular browser can not move files around on the local computer or run local commands.
  • badge printing
  • lead retrieval - attendee tracking; QR codes
• journals - journal, documentation, notes, diary, blog, etc
• idaa - One of my clients

Documentation

• TODO.md
• Svelte - Introducing runes - https://svelte.dev/blog/runes
• Svelte - Breaking changes in runes mode - https://svelte.dev/docs/svelte/v5-migration-guide#Breaking-changes-in-runes-mode
• Dexie.js - Getting Started - https://dexie.org/docs/Tutorial/Getting-started
• Dexie.js - API Quick Reference - https://dexie.org/docs/API-Reference#quick-reference

Ignored Directories

The following directories are ignored for various operations (e.g., search, file listing) to focus on relevant source code:

• build
• node_modules
• tests

---

Refactoring Notes

process_ae_obj__*_props() Refactoring (2025-11-13)

The process_ae_obj__*_props() family of functions, which are responsible for transforming API data for frontend use, have been refactored to standardize their structure and improve maintainability.

The refactoring strategy involved creating a local, non-exported _process_generic_props helper function within each module (ae_journals, ae_events, ae_archives, ae_posts, ae_core). This approach was chosen to avoid altering the module import graph, which had previously caused a critical InternalError: module record has unexpected status: New in the SvelteKit development server when a shared utility file was introduced.

Key aspects of the refactoring:

• In-file Generic Helper (_process_generic_props): This function handles common data transformations:

  • *_random ID Aliasing: It automatically iterates over object keys and creates a non-suffixed alias for any key ending in _random (e.g., person_id_random becomes person_id). This is crucial for client-side logic that expects standard ID fields.
  • tmp_sort Field Generation: It creates a set of basic tmp_sort fields for client-side sorting.

• specific_processor Callback: Module-specific logic is handled by a specific_processor callback function passed to the _process_generic_props helper. This allows for:

  • Unique tmp_sort Logic: Modules can override the default tmp_sort fields with their own specific sorting requirements.
  • Content Processing: Asynchronous operations like Markdown parsing (using marked.parse) are handled within the specific_processor for the relevant modules (e.g., ae_journals__journal_entry.ts).
  • Other Special Cases: Any other module-specific data transformations are handled in this callback.

• core__crud_generic.ts Cleanup: The generic CRUD functions in src/lib/ae_core/core__crud_generic.ts were simplified:

  • The process_ae_obj__props function in this file was deprecated.
  • All calls to process_ae_obj__props and db_save_ae_obj_li__ae_obj were removed from the generic CRUD functions (load_ae_obj_id, load_ae_obj_li, etc.).
  • These functions are now responsible only for API interaction, delegating all data processing and caching to the module-specific functions that call them. This enforces a cleaner separation of concerns.

Tiptap to CodeMirror Migration (2025-11-17)

The rich text editor component, previously based on Tiptap (shad-editor), has been replaced with a CodeMirror-based solution. This change was driven by the complexity of Tiptap and its compatibility issues with Tailwind CSS, aiming for a simpler, markdown-focused editing experience.

Key aspects of the migration:

• Removal of Tiptap: All @tiptap/* and svelte-tiptap dependencies were removed from package.json, and the src/lib/components/shad-editor/ directory was deleted.
• CodeMirror Integration: A new CodeMirror component (src/lib/elements/element_codemirror_editor.svelte) was created, providing basic markdown formatting capabilities.
• Wrapper Component Update: The existing editor wrapper (src/lib/elements/element_tiptap_editor.svelte) was renamed to src/lib/elements/element_codemirror_wrapper.svelte and refactored to utilize the new CodeMirror component. Tiptap-specific logic and props were removed.
• Component Usage Updates: All Svelte components that previously imported and used the Tiptap wrapper were updated to import element_codemirror_wrapper.svelte. Unsupported props such as default_minimal, show_button_kv, bind:new_html, and bind:changed were removed from their usage.
• Dependency Cleanup: npm install was run to remove unneeded packages, and npm run format was executed to ensure consistent code style.

CodeMirror Bug Fixes (2025-11-18)

Following the initial migration to CodeMirror, several issues were identified and resolved:

• Initialization Errors: An "Unrecognized extension value" error was fixed by refactoring codemirror_modules.ts to explicitly import individual CodeMirror extensions instead of relying on the basicSetup bundle. This ensures proper singleton usage and prevents module duplication.
• Text Wrapping: The EditorView.lineWrapping extension was added to element_codemirror_editor.svelte and e_app_codemirror_v5.svelte to enable text wrapping.
• Content Saving: Content binding issues were resolved in various IDAA components by correctly binding the html_text prop of the CodeMirror wrapper to the corresponding state variables.
• Save Button Enablement: The logic for enabling the "Save" button was fixed in ae_idaa_comp__post_obj_id_edit.svelte to correctly detect changes in the CodeMirror editor.
• Editor Buttons: A TypeError in the editor's formatting buttons was fixed by using EditorSelection.range() to correctly create selection ranges.
• Component Renaming: The Tiptap_editor component alias was renamed to CodeMirror_wrapper across the project for clarity, and the wrapper file was renamed to element_codemirror_editor_wrapper.svelte.