From d21109ec276c933bc979b820e0ceed8ccab02b8d Mon Sep 17 00:00:00 2001
From: jars <jakeadriansames@gmail.com>
Date: Sat, 9 May 2026 16:04:56 +0100
Subject: [PATCH] docs: defer dual theme cleanup to KNOWN-ISSUES KI-05

settings.theme and preferences.theme overlap: the legacy localStorage
field still drives two SegmentedButton bindings in SettingsPage.svelte
while preferences.theme is the canonical Tauri-persisted store. A
migration \$effect in the four route +layout files syncs the legacy
value into preferences whenever it changes.

Resolution requires touching SettingsPage.svelte (2 484 LOC),
src/lib/stores/page.svelte.ts, four route layouts, and the localStorage
migration system. That is moderate-risk frontend work, not pre-launch
polish, so it lands in KNOWN-ISSUES with a concrete plan and is
deferred from v0.1.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 KNOWN-ISSUES.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/KNOWN-ISSUES.md b/KNOWN-ISSUES.md
index 6bf0365..959490e 100644
--- a/KNOWN-ISSUES.md
+++ b/KNOWN-ISSUES.md
@@ -46,6 +46,24 @@ Tracked limitations and partial implementations in the current codebase. Each en
 
 **Workaround:** N/A.
 
+## Frontend
+
+### KI-05 — Dual theme system: `settings.theme` and `preferences.theme` coexist
+
+**Status:** Theme is stored twice. The legacy `settings.theme` ("Dark" / "Light" / "System", localStorage-only) is bound to two `SegmentedButton` controls in `SettingsPage.svelte`. The canonical `preferences.theme` ("dark" / "light" / "system", Tauri-persisted via `save_preferences`) is what the DOM and runtime actually consume. A migration `$effect` in `src/routes/+layout.svelte` (and the secondary `+layout@.svelte` files for `/preview`, `/viewer`, `/float`) syncs `settings.theme` → `preferences.theme` whenever the legacy value changes.
+
+**Source:**
+- [`src/lib/stores/page.svelte.ts:61`](src/lib/stores/page.svelte.ts#L61) (legacy default: `theme: "Dark"`)
+- [`src/lib/stores/preferences.svelte.ts:30`](src/lib/stores/preferences.svelte.ts#L30) (canonical default: `theme: "dark"`)
+- [`src/routes/+layout.svelte:61-68`](src/routes/+layout.svelte#L61) (migration `$effect`)
+- [`src/lib/pages/SettingsPage.svelte:1118`](src/lib/pages/SettingsPage.svelte#L1118), [`:2360`](src/lib/pages/SettingsPage.svelte#L2360) (UI bindings still on the legacy field)
+
+**Impact:** No user-facing bug; theme switching works. The cost is code complexity and a small race window where preference fan-out can lag behind a `settings.theme` change. The `$effect` is lightweight (string compare plus a debounced persist when the mapped value differs), not a hot-loop performance problem despite earlier framing.
+
+**Resolution (deferred):** Switch the two `SettingsPage` bindings to `preferences.theme` with mapped options, retire the migration `$effect` in all four route layouts, drop `theme` from `SettingsState`, and add a one-shot localStorage migration that copies any historical `settings.theme` into `preferences` on first run after the cleanup. Touches ~5 files including the 2 484-LOC `SettingsPage.svelte`; deferred from the v0.1 polish pass to avoid a moderate-risk frontend change immediately before launch.
+
+**Workaround:** N/A.
+
 ## How to add an entry
 
 When shipping a partial implementation or known limitation, add a `KI-NN` entry here with the four standard fields: **Status**, **Source** (file:line), **Impact**, **Workaround**. Link from the affected module's doc comment back to this file by ID.