🎨 Palette: [UX improvement] Add comma formatting to scores and enhance achievement feedback

.Jules/palette.md

@@ -33,3 +33,11 @@
 ## 2024-04-24 - Avoiding Trailing Artifacts in CLI Applications
 **Learning:** When dynamically updating terminal lines using carriage return (`\r`), relying on hardcoded padding spaces to overwrite old text is brittle and leads to trailing text artifacts when new lines are shorter than previous ones.
 **Action:** Always use the ANSI escape sequence `\033[K` (Erase in Line) immediately after the carriage return (`\r`) to cleanly clear the line before writing new content, rather than manually managing padding spaces.
+
+## 2026-05-24 - Readability of Large Numbers in CLI
+**Learning:** In "clicker" style games or any application dealing with large numbers, raw integers quickly become difficult to parse visually. Implementing comma formatting (thousands separators) significantly improves readability and the user's ability to quickly gauge their progress.
+**Action:** Use a `formatWithCommas` helper for all numeric displays exceeding three digits in CLI applications to enhance cognitive ease.
+
+## 2026-05-24 - Contextual Achievement Feedback
+**Learning:** Announcing a "New Best" is rewarding, but providing the *previous* record alongside it (e.g., "was 1,000") provides immediate context for the magnitude of the achievement. This makes the progress feel more tangible and rewarding for the user.
+**Action:** Always include the previous baseline or high score when celebrating a new achievement to provide immediate contextual reward.

src/main.cpp

@@ -10,6 +10,18 @@
 #include <csignal>
 #include <cstdlib>
 
+std::string formatWithCommas(long long value) {
+    std::string s = std::to_string(value);
+    int n = static_cast<int>(s.length());
+    int limit = (value < 0) ? 1 : 0;
+    int insertPosition = n - 3;
+    while (insertPosition > limit) {
+        s.insert(insertPosition, ",");
+        insertPosition -= 3;
+    }
+    return s;
+}
+
 // Color and formatting macros for terminal output
 #define RESET     "\033[0m"
 #define RED       "\033[31m"
@@ -78,7 +90,7 @@ int main() {
     std::cout << CLR_CTRL << "==========================\n      SPEED CLICKER\n==========================\n" << CLR_RESET;
 
     if (highscore > 0) {
-        std::cout << " Personal Best: " << CLR_SCORE << highscore << CLR_RESET << "\n\n";
+        std::cout << " Personal Best: " << CLR_SCORE << formatWithCommas(highscore) << CLR_RESET << "\n\n";
     }
 
     std::cout << "Controls:\n " << CLR_CTRL << "[h]" << CLR_RESET << " Toggle Hard Mode (10x Speed!)\n "
@@ -142,9 +154,9 @@ int main() {
         }
 
         if (updateUI) {
-            std::cout << "\r" ERASE_LINE << CLR_SCORE << "Score: " << score << CLR_RESET << " | High: " << highscore << " "
+            std::cout << "\r" ERASE_LINE << CLR_SCORE << "Score: " << formatWithCommas(score) << CLR_RESET << " | High: " << formatWithCommas(highscore) << " "
                       << (hardMode ? CLR_HARD "[HARD MODE]" : CLR_NORM "[NORMAL MODE]")
-                      << (score > initialHighscore ? " NEW BEST! 🥳" : "")
+                      << (score > initialHighscore ? CLR_CTRL " ✨ NEW BEST! (was " + formatWithCommas(initialHighscore) + ") 🥳" CLR_RESET : "")
                       << std::flush;
             updateUI = false;
         }
@@ -155,7 +167,7 @@ int main() {
     }
 
     tcsetattr(STDIN_FILENO, TCSANOW, &oldt);
-    std::cout << "\n\n" << CLR_SCORE << "Final Score: " << score << CLR_RESET << "\n";
+    std::cout << "\n\n" << CLR_SCORE << "Final Score: " << formatWithCommas(score) << CLR_RESET << "\n";
     if (score > initialHighscore) {
         std::cout << "Congratulations! A new personal best!\n";
     }