# 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

```typescript
// 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)

```svelte
<!-- 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

```typescript
// 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)

- [x] Phase A: Plan written.
- [x] Phase B: Core infrastructure setup (runed, renames, wrappers).
- [x] 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.