feat(theme): add palette module with 4 built-in themes

CHANGELOG.md

@@ -9,6 +9,75 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+_No unreleased changes yet._
+
+---
+
+## [0.2.0] — customization
+
+### Added
+- **Configuration file** at `~/.typerush/config.toml`. Entirely optional — a
+  missing or malformed file silently falls back to defaults. See
+  `config.example.toml` and `docs/USAGE.md` for the full schema.
+- **Built-in themes**: `dark` (the existing look, still the default), `light`,
+  `monokai`, `dracula`. Pick one with `theme = "monokai"` in the config.
+  Each theme paints its own canonical background — light is genuinely light
+  even on a dark terminal, monokai and dracula look like the real schemes
+  regardless of host terminal. Dark uses `Color::Reset` so the user's
+  terminal background still shines through.
+- **Per-slot color overrides** on top of any built-in theme. Ten themable
+  slots (`accent`, `secondary`, `correct`, `incorrect`, `pending`, `extra`,
+  `mode_tag`, `error`, `neutral`, `background`) cover every UI element.
+- **Color parser** for `#RRGGBB` hex strings and the 16 ANSI color names
+  (case-insensitive, `_` / `-` separators tolerated).
+- **`--theme <name>` CLI flag** for one-shot overrides. Wins over the config.
+- **`--list-themes` CLI flag** prints every built-in theme name and exits —
+  useful for shell-completion scripts.
+- **Default mode + per-mode defaults** in the config — pre-selects the
+  matching menu row at startup.
+- **`docs/DEVELOPMENT.md`** — practical local-dev workflow (running with
+  CLI args, sandboxed config testing via `HOME` redirect, `cargo-watch`
+  patterns for TUI apps, recommended two-terminal loop).
+- Test count grew from 4 to 48 — color parsing, config deserialization,
+  theme resolution, override application, CLI precedence, menu-row
+  matching, render-level background paint, custom-mode auto-finish,
+  Ctrl+H/W/Backspace dispatch.
+
+### Changed
+- Zen mode now desaturates to theme-aware `pending` / `neutral` colors instead
+  of hardcoded grays, keeping the screen readable on light backgrounds.
+- Help overlay lists the config file path alongside the stats file path.
+- Menu screen gained 2 rows of top padding so the TYPERUSH banner no longer
+  hugs the terminal's title bar / tab strip.
+- Light theme foreground palette darkened across every slot — the previous
+  values were carried over from the dark theme and washed out on white.
+  All slots now land at ≥4.5:1 contrast against the `#FAFAFA` background.
+
+### Fixed
+- **Custom-file mode (`--file <path>`) now auto-finishes** when the user
+  types the last word, matching the documented behavior in
+  `docs/USAGE.md`. Previously the session sat waiting for `Esc`.
+- **Progress-gauge timer label** is now explicitly styled (`secondary` +
+  bold) instead of falling through to whatever default ratatui picked.
+  Readable on both the filled and unfilled portions of the bar across
+  every built-in theme.
+- **Plain (unstyled) text on the light theme** — menu list items, the
+  stats table's date column, and plain help-overlay lines — now render
+  in `theme.neutral` rather than terminal-default foreground. Previously
+  they were near-white on white when running the light theme on a dark
+  terminal.
+- **Ctrl+Backspace now actually deletes the current word.** Most terminals
+  send `Ctrl+Backspace` as a literal `^H` byte — crossterm reports it as
+  `Char('h') + CTRL`, not as `Backspace + CTRL` — so the old keymap was
+  silently dropping it into the "ignore control chords" branch. The
+  keymap now also recognises `Ctrl+W` (Unix "kill word" muscle memory).
+
+### Compatibility
+- Existing CLI flags (`--time`, `--words`, `--quote`, `--code`, `--zen`,
+  `--file`) are unchanged.
+- `~/.typerush/stats.json` format is unchanged — old session history loads
+  exactly as before.
+
 ---
 
 ## [0.1.1] — initial release
@@ -41,5 +110,6 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   dedicated docs.
 - Demo GIF uses absolute GitHub raw URL for correct display on crates.io.
 
-[Unreleased]: https://github.com/withrvr/typerush/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/withrvr/typerush/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/withrvr/typerush/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/withrvr/typerush/releases/tag/v0.1.1

CONTRIBUTING.md

@@ -63,17 +63,16 @@ are incremental and finish in under a second.
 
 ### Running during development
 
-```bash
-cargo run                       # debug build, opens the menu
-cargo run -- --time 30          # pass any CLI flag through
-cargo watch -x run              # rerun on every save
-```
+For the full local-dev workflow — running with CLI args, debug vs release,
+testing the config file safely, `cargo-watch` patterns for TUI apps, the
+recommended two-terminal loop — see [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).
 
-For a release build:
+Quick reference:
 
 ```bash
-cargo build --release
-./target/release/typerush
+cargo run                       # debug build, opens the menu
+cargo run -- --time 30          # pass any CLI flag through
+cargo build --release && ./target/release/typerush
 ```
 
 ---
@@ -174,11 +173,9 @@ menu row, optionally add a CLI flag.
 
 ## Adding a new theme
 
-(Once theming lands in v0.2.) Each theme is a `Theme` struct in
-`src/config.rs` mapping the four character states (Correct / Incorrect /
-Pending / Extra) to ratatui colors. The plan is to read these from
-`~/.typerush/config.toml`. Until then, hard-coded constants live in
-`src/ui/typing.rs::style_for_char`.
+Drop a `ThemePalette` constant into `src/theme/builtin.rs` and append it to
+`ALL`. The recipe lives in `docs/ARCHITECTURE.md` — see "When you add a new
+theme".
 
 ---
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "typerush"
-version = "0.1.1"
+version = "0.2.0"
 edition = "2021"
 description = "In your terminal — a fast, cross-platform WPM typing trainer built with Rust"
 license = "MIT"
@@ -27,6 +27,7 @@ rand = "0.8"
 chrono = { version = "0.4", features = ["serde"] }
 anyhow = "1"
 dirs = "5"
+toml = "0.8"
 
 [profile.release]
 lto = true

README.md

@@ -29,7 +29,7 @@ with a quote — TypeRush meets you where you already work: the command line.
 ## ✨ Why TypeRush
 
 - 🚀 **Instant feedback** — see your WPM and accuracy climb keystroke by keystroke
-- 🎨 **Beautiful TUI** — clean colors, smooth layout, no distractions
+- 🎨 **Themes built-in** — `dark`, `light`, `monokai`, `dracula`, or roll your own colors
 - ⏱ **Six built-in modes** — Time, Words, Quote, Code, Zen, and Custom-file
 - 💾 **Tracks your progress** — every session saved locally, with charts and a personal best
 - 🌍 **Runs everywhere** — Linux · macOS · Windows · WSL · Git Bash
@@ -69,6 +69,8 @@ typerush --quote             # one programming quote
 typerush --code rust         # a real Rust snippet
 typerush --zen               # zen mode — no timer, no pressure
 typerush --file my_text.txt  # type anything you want
+typerush --theme monokai     # try a different theme
+typerush --list-themes       # see all built-in themes
 ```
 
 ---
@@ -109,10 +111,29 @@ shows your personal best, average accuracy, a trend sparkline, and your last
 
 ---
 
+## 🎨 Make it yours
+
+Drop a [`config.toml`](config.example.toml) into `~/.typerush/` to pick a
+theme, set your default mode, or override individual colors:
+
+```toml
+theme = "monokai"
+
+[defaults]
+mode = "time"
+time_seconds = 30
+```
+
+See [`docs/USAGE.md`](docs/USAGE.md#configuration--typerushconfigtoml) for
+the full reference.
+
+---
+
 ## 📚 More documentation
 
 - 📖 [USAGE](docs/USAGE.md) — all keybindings, modes, CLI flags, config
 - 🏛 [ARCHITECTURE](docs/ARCHITECTURE.md) — how the code is laid out
+- 🛠 [DEVELOPMENT](docs/DEVELOPMENT.md) — local dev workflow, cargo-watch, sandbox config
 - 🗺 [ROADMAP](docs/ROADMAP.md) — what's done, what's next
 - 🤝 [CONTRIBUTING](CONTRIBUTING.md) — dev setup, conventions, how to help
 - 📝 [CHANGELOG](CHANGELOG.md) — what changed in every release

config.example.toml

@@ -0,0 +1,49 @@
+# TypeRush — example configuration file
+#
+# Copy this file to `~/.typerush/config.toml` and edit to taste.
+# TypeRush works fine without a config file — every setting below is optional.
+#
+# Precedence: CLI flags > this file > built-in defaults.
+
+# -----------------------------------------------------------------------------
+# Theme — pick one of the built-in palettes by name.
+# Available names: dark, light, monokai, dracula
+# Run `typerush --list-themes` to see what's currently shipped.
+# -----------------------------------------------------------------------------
+theme = "monokai"
+
+# -----------------------------------------------------------------------------
+# Defaults — pre-selects a menu row and sets the initial mode when no CLI flag
+# is given. CLI flags (--time, --words, --quote, --code, --zen) always win.
+# -----------------------------------------------------------------------------
+[defaults]
+# Which menu row to pre-select: "time" | "words" | "quote" | "code" | "zen"
+mode = "time"
+# Used when mode = "time". Standard menu rows: 15 / 30 / 60 / 120.
+time_seconds = 15
+# Used when mode = "words". Standard menu rows: 10 / 25 / 50 / 100.
+word_count = 25
+# Used when mode = "code". One of: rust | python | js
+code_lang = "rust"
+
+# -----------------------------------------------------------------------------
+# Color overrides — applied ON TOP of the chosen theme.
+# Any slot omitted here keeps the theme's value.
+# Values may be:
+#   - a hex string like "#A6E22E"
+#   - one of the 16 ANSI names: black, red, green, yellow, blue, magenta,
+#     cyan, gray, dark_gray, light_red, light_green, light_yellow,
+#     light_blue, light_magenta, light_cyan, white
+# -----------------------------------------------------------------------------
+# [colors]
+# accent     = "#66D9EF"   # cursor, gauge, banner, time, titles
+# secondary  = "#E6DB74"   # WPM number, section titles
+# correct    = "#A6E22E"   # correctly-typed characters + accuracy %
+# incorrect  = "#F92672"   # wrongly-typed characters
+# pending    = "#75715E"   # untyped characters + muted labels/footers
+# extra      = "#FD971F"   # surplus characters past end of word
+# mode_tag   = "#AE81FF"   # [mode] badge in the header
+# error      = "#F92672"   # error modal border
+# neutral    = "#F8F8F2"   # emphasized neutral text (char totals)
+# background = "#272822"   # full-screen background fill
+#                          # set to "reset" to use the terminal's native bg