perf(core): standardize non-blocking load pattern and add performance guidelines

- Documented the 'Non-Blocking Load Pattern' (SWR) in 'documentation/PERFORMANCE_GUIDELINES.md' to prevent future performance regressions.
- Refactored 'src/routes/core/people/[person_id]/+page.ts' to be non-blocking, improving perceived speed for person details.
- Updated 'GEMINI.md' standards and 'TODO.md' tasks to reflect system-wide performance hardening.
This commit is contained in:
Scott Idem
2026-01-27 12:32:26 -05:00
parent 9655604d86
commit b837e6d0f8
4 changed files with 103 additions and 9 deletions

View File

@@ -39,6 +39,10 @@
- **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.
- **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.
- **Performance (Non-Blocking Loads):**
- **Stale-While-Revalidate:** Never block SvelteKit `load` functions with API calls for data already tracked by `liveQuery`.
- **Fire & Forget:** Initiate API refreshes in `load` without `await`. Let the UI render instantly from IndexedDB cache and update reactively.
- **Documentation:** See `documentation/PERFORMANCE_GUIDELINES.md` for detailed patterns.
- **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.