702a7a73de
- AE__Architecture.md: minor wording fix - TODO__Agents.md: add Svelte 4→5 store migration task (root cause of IDAA Novi re-auth bug; prerequisite for Phase 2c store refactor) - PROJECT__Stores_Svelte5_Migration.md: new migration planning doc Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# 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.
|