docs: add/update Firefly theme repair summary

documentation/PROJECT__AE_Firefly_Theme_Repair_SUMMARY.md

@@ -0,0 +1,68 @@
+**AE Firefly Theme Repair — Summary (merged & updated)**
+
+- Summary: Investigation and targeted repairs to restore light/dark theme colors for the AE Firefly family. Repairs were diagnostic and staged on WIP branches; this document records what was attempted, what was reverted, the current safe state, and the next minimal steps to finish validation and merge changes safely.
+
+Root Cause
+- Variables outside selectors: several Firefly theme files had custom-property declarations placed outside of their `html[data-theme='...']` selector blocks (invalid CSS placement), so theme variables did not apply as intended.
+- Variable precedence: the app's base `:root` variables (numeric triplets intended for `hsl(var(--...))`) were taking precedence. Some theme files used color functions (oklch/oklab/etc.) while the app expected numeric triplets inside `hsl(var(--...))`.
+
+Actions taken
+- Theme repairs (attempted): moved custom-property declarations into the proper selector blocks and added `--background: ... !important` in both light and `html.dark[...]` selectors to prevent `:root` from overriding the theme background.
+  - Edited: `src/ae-firefly.css`, `src/ae-firefly-steelblue.css`, `src/ae-firefly-indigo.css`, `src/ae-firefly-rainbow.css`.
+- App-level compatibility attempt: added a defensive change in `src/app.css` to accept either raw function values (e.g., `oklch(...)`) or numeric triplets used with `hsl(var(--...))` by falling back to `var(--...)` before `hsl(var(--...))`.
+- Testing: started the dev server (Vite) to smoke-test theme switching; server ran during testing.
+
+Additional low-risk fix applied while validating WIP imports:
+- `src/lib/stores/store_versions.ts` — added a defensive guard around `localStorage` calls to avoid a runtime crash when importing WIP components during SSR/module evaluation. This guard is non-destructive and prevents Module-eval failures in non-browser environments.
+
+Repository actions (safety-first workflow)
+- Created a backup branch with the repair work: `wip/theme-fix` (contains repair commit(s)).
+- When the visual result remained grayscale, the Firefly theme files were restored to their prior state on `wip/theme-fix` (a revert commit was created there) and a safe branch was created from the known-good upstream: `restore/good-state`.
+- Reset the workspace to the known-good state with:
+  - `git switch -C restore/good-state origin/ae_app_3x_llm`
+  - `git reset --hard origin/ae_app_3x_llm`
+
+Note about branches in the workspace now:
+- `ae_app_3x_llm` — canonical baseline (target for merging documentation and safe changes).
+- `wip/theme-fix` — contains the original repair attempts and the revert; keep for reference.
+- `wip-modal-fix-attempt` — contains many UI/layout edits (icon/preset work); imported files are being reviewed on an integration branch (`integrate/from-ae_app_3x_llm-*`).
+- `integrate/*` — temporary integration branches used for selective cherry-picks and review.
+
+Current merged state (this file merged into `ae_app_3x_llm`):
+- This summary file is now recorded on `ae_app_3x_llm` and updated with the latest findings and plan.
+- A defensive `store_versions.ts` guard is present on the integration branch used for selective imports and has been committed to the working integration branch for safety; if you prefer exact last-night parity on `ae_app_3x_llm` we can revert that single guard commit, but keeping it prevents SSR import crashes when bringing in WIP files.
+
+Files touched during the troubleshooting (for review)
+- `src/ae-firefly.css`
+- `src/ae-firefly-steelblue.css`
+- `src/ae-firefly-indigo.css`
+- `src/ae-firefly-rainbow.css`
+- `src/app.css` (compatibility tweak attempt)
+
+Other commits created or inspected during the repair/integration workflow:
+- `b543c8a9` — chore: migrate FA → Lucide (already present on `ae_app_3x_llm`).
+- `ae7689e2` / `b081b079` — theme-fix commits on `integrate/temp-merge-*` / `wip/theme-fix` (touch only the `src/ae-firefly*` files).
+
+Why the repair didn't produce expected results
+- Even after moving variables into selector blocks and forcing `--background`, there are multiple interacting factors: the order of CSS imports, how the app consumes variables (expecting numeric triplets for `hsl(var(--...))`), and the presence of other global rules (Skeleton/Tailwind presets) that can override color rendering. The attempted app-level compatibility tweak may not persist because we later reset to the known-good commit.
+
+Additional note: importing multiple WIP UI files at once can expose SSR/import-time issues (for example the `localStorage` error). The safe workflow is: cherry-pick small batches, run `npx svelte-check`, then run the dev server, and inspect computed CSS via browser devtools.
+
+Recommended next steps (selective, minimally invasive)
+1. Continue merging UI/layout changes in small batches onto an integration branch (`integrate/from-ae_app_3x_llm-*`).
+2. After each batch: run `npx svelte-check`, start `npm run dev`, and fix SSR/module-time errors (like the `localStorage` guard added earlier).
+3. Once layouts + core components are stable, merge theme-file changes from `wip/theme-fix` and re-test theme rendering.
+4. Open a PR with staged changes for final review.
+
+Small example: to import a single theme file from `wip/theme-fix` into an integration branch:
+```bash
+git checkout ae_app_3x_llm
+git checkout -b integrate/theme-test
+git checkout wip/theme-fix -- src/ae-firefly-steelblue.css
+git add src/ae-firefly-steelblue.css && git commit -m "cherry: bring ae-firefly-steelblue.css from wip/theme-fix for test"
+```
+
+Closing note
+- Nothing destructive was lost — all repair attempts are saved to `wip/theme-fix`. The working tree was reset to the known-good upstream commit and `restore/good-state` was created. We can re-run experiments using the repair commits as a starting point and proceed with a smaller, deterministic test matrix (inspect computed variables first, then apply one small change at a time and test).
+
+Prepared by: GitHub Copilot (working in the workspace).