Edison Jwa
bba6273af7
- Move ASPICE docs to chanoraapp/docs submodule at docs/ - Move development docs to dev-docs/ (superpowers, offline-knowledge, impl-mapping) - Add AGENTS.md with project conventions for AI agents - Add impl-mapping.md (SAD component → source file mapping) - Archive completed plans to dev-docs/superpowers/plans/_archived/ - Remove AGENTS.md from .gitignore (now tracked)
71 lines
3.1 KiB
Markdown
71 lines
3.1 KiB
Markdown
# State Sync and UI Settings Validation Design
|
|
|
|
**Date:** 2026-05-29
|
|
**Status:** Approved for implementation
|
|
**Scope:** P0/P1 validation-based completion for state-sync evidence and UI settings persistence
|
|
|
|
## 1. Goal
|
|
|
|
Close the current DV/P0-P1 gaps for reducer/state-sync evidence and UI settings persistence with tests first, minimal behavior changes, and updated documentation evidence.
|
|
|
|
## 2. State-Sync Design
|
|
|
|
`chanora_state` remains the reducer owner. The validation pass adds focused tests for known reducer contracts rather than broad refactoring. Missing behavior is implemented only when a test proves a gap.
|
|
|
|
Required evidence covers:
|
|
|
|
| Contract | Evidence |
|
|
|---|---|
|
|
| Snapshot creates ready state and deterministic normalized order | Existing and expanded reducer tests |
|
|
| Reconnect discards stale state and reconnect snapshot replaces state | Existing reducer tests |
|
|
| Disconnected/lost states suppress live deltas | Existing reducer tests |
|
|
| Duplicate IDs are normalized deterministically | Existing reducer tests |
|
|
| Unknown client voice activity is ignored | Existing reducer tests |
|
|
| Channel deletion removes clients in deleted channel | New reducer regression test and implementation |
|
|
| Same event sequence produces same state and deltas | Existing reducer determinism test |
|
|
|
|
## 3. UI Settings Design
|
|
|
|
`UiPreferencesService` remains a Flutter service backed by `shared_preferences`. This is the minimal P0/P1-complete implementation because the current app already uses SharedPreferences and no current behavior requires SQLite-backed UI settings.
|
|
|
|
`UiSettings` gains a typed `themeMode` field with values:
|
|
|
|
| Value | Meaning |
|
|
|---|---|
|
|
| `system` | Follow platform theme |
|
|
| `light` | Force light theme |
|
|
| `dark` | Force dark theme |
|
|
|
|
The service persists the selected theme mode, falls back to `system` for invalid stored values, and preserves independent saves for host and nickname.
|
|
|
|
## 4. App Wiring
|
|
|
|
`ChanoraApp` becomes stateful enough to load and apply persisted theme mode. `_BetaHome` continues to load/save host and nickname through `UiPreferencesService`. UI controls for selecting theme mode are out of this slice unless already present; this slice provides persistence and app-level application.
|
|
|
|
## 5. Documentation Updates
|
|
|
|
After tests pass:
|
|
|
|
| Document | Update |
|
|
|---|---|
|
|
| `docs/implementation-status-2026-05-28.md` | Mark reducer scaffold statement stale/resolved and UI settings persistence implemented for SharedPreferences scope |
|
|
| `docs/release/dv-waiver-register.md` | Close or soften reducer waiver; keep event replay as P1 gap |
|
|
| `docs/verification/swe4-unit-verification-plan.md` | Record reducer test evidence and UI settings tests |
|
|
| `docs/verification/swe6-software-verification-plan.md` | Update state sync and UI settings DV status |
|
|
| `docs/architecture/sdd.md` | Record UI settings persistence design |
|
|
|
|
## 6. Validation
|
|
|
|
Run focused tests:
|
|
|
|
```text
|
|
cargo test -p chanora_state --locked
|
|
flutter test test/services/ui_preferences_service_test.dart
|
|
```
|
|
|
|
Run wider checks if touched app-shell behavior requires it:
|
|
|
|
```text
|
|
flutter test --exclude-tags e2e
|
|
```
|