**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).