Symptom

The app always followed the OS dark/light setting with no way for the user to override it. Requesting a third toggle button in the top-right corner stack to force dark, light, or revert to system.

Root cause

No feature gap — this was a missing enhancement. Theme was controlled solely by isSystemInDarkTheme() in App.kt, with a headless-only escape via KRILL_THEME env var / -Dkrill.theme system property.

Fix

• Added ThemeStore interface (shared/commonMain/ui/ThemeStore.kt) with darkThemeOverride(): Boolean? and setDarkThemeOverride(Boolean?).
• Added four platform implementations mirroring OnboardingStore: JvmThemeStore (file), AndroidThemeStore (SharedPreferences), WasmThemeStore (localStorage), IosThemeStore (NSUserDefaults).
• Registered each in the matching AppModule.*.kt platform DI module.
• Hoisted theme state into App.kt: reads initial value from ThemeStore, exposes current override + toggle callback via LocalThemeOverride composition local. Headless env-var override still takes priority.
• Added ThemeModeToggle composable in ClientScreen.kt as the third button in the top-right vertical stack. Cycles system (🖥) → dark (🌙) → light (☀) → system. Active (non-null override) fills with primary color, matching ViewModeToggle and EditModeToggle styling conventions.

Prevention

• Persist user preferences that should survive relaunches via the ThemeStore / OnboardingStore platform-per-impl pattern — never ride transient process state.
• Keep all app-level theme state hoisted in App.kt; expose it to deep children via CompositionLocal, not prop-drilling or a global singleton.
• New toggle buttons in the top-right stack follow the Surface(CircleShape) + EmojiText pattern — one composable per toggle, added to the existing Column.