OSIT-AE-App-Svelte/documentation/PROJECT__Stores_Svelte5_Migration.md

Project: Svelte 4 Store → Svelte 5 State Migration

Status: Execution / Phase B (In Progress) Priority: High (post-April 2026 conference) Created: 2026-03-30 Related: TODO__Agents.md — [Stores] Svelte 5 State Migration entry

---

Background

All core Aether stores (ae_loc, idaa_loc, ae_events_loc, etc.) are being migrated from Svelte 4 stores to Svelte 5 $state using the runed library's PersistedState. This provides fine-grained reactivity, ensuring that effects only re-run when specific fields they access are updated, rather than on every write to the store object.

Phase B Progress & Learnings (Updated 2026-03-30)

1. Dependency Installed: runed is now a project dependency.
2. Module Resolution Strategy:
   • Core store files renamed: ae_stores.ts → ae_stores.svelte.ts, etc.
   • Critical Discovery: SvelteKit and CLI tools (svelte-check) struggled to resolve extension-less imports (like $lib/stores/ae_stores) when only .svelte.ts existed.
   • Solution: Created .ts wrapper files (e.g., src/lib/stores/ae_stores.ts) that simply re-export everything via export * from './ae_stores.svelte'. This maintains backward compatibility for all existing import paths without manual updates.
3. API Confirmation: Confirmed that runed's PersistedState uses .current to access the state object, matching the intended migration syntax.
4. Mass Replacement:
   • $ae_loc → ae_loc_v5.current
   • $idaa_loc → idaa_loc_v5.current
   • $events_loc → events_loc_v5.current
   • These replacements have been applied across the entire src/ directory (~2000+ sites).
5. Import Updates: A robust Python script was used to surgically add ae_loc_v5, idaa_loc_v5, and events_loc_v5 to existing import blocks, avoiding import type lines and duplicates.

---

Syntax Changes: Before / After

Store declaration

// BEFORE (ae_stores.svelte.ts)
export const ae_loc: Writable<key_val> = persisted('ae_loc', defaults);

// AFTER (ae_stores.svelte.ts)
export const ae_loc_v5 = new PersistedState('ae_loc', defaults);

Reading/Writing (Consumers)

<!-- BEFORE -->
{$ae_loc.theme_mode}
{#if $ae_loc.trusted_access}

<!-- AFTER -->
{ae_loc_v5.current.theme_mode}
{#if ae_loc_v5.current.trusted_access}

Batch Update Pattern

// Use Object.assign for multi-field updates to maintain fine-grained reactivity
Object.assign(ae_loc_v5.current, { theme_mode: 'dark', edit_mode: true });

---

Implementation Notes

Prettier & Formatting

Because the mass migration touches ~250 files, formatting may be inconsistent (especially in import blocks). It is recommended to run npm run format (if available) or rely on standard linting after the imports are stabilized.

Batching vs. "Big Sweep"

While the original plan suggested smaller batches, the global nature of ae_loc and the hundreds of interdependent files made a "Big Sweep" more efficient to ensure the app remains in a consistent state. However, verification should still be done module-by-module.

---

Current Status (Pause Point)

• Phase A: Plan written.
• Phase B: Core infrastructure setup (runed, renames, wrappers).
• Phase B: Mass variable replacement ($ae_loc -> ae_loc_v5.current).
• [/] Phase B: Mass import update (In Progress/Verifying).
• Phase B: Final validation (svelte-check clean).

Do NOT stage or commit until npx svelte-check is fully verified. The app currently has a high error count due to the transition period where imports are being re-aligned. Final verification is the next step after the pause.