From faa4cdd16275a15d561861c244939d537d0f0ea0 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 7 Jul 2026 17:12:11 +0000
Subject: [PATCH] palette: enhance score readability and achievement feedback

- Implement formatWithCommas utility in src/utils.hpp
- Apply thousands separators to all score and highscore displays
- Improve "NEW BEST!" feedback with color, emojis, and previous record context
- Ensure terminal state is reset after volatile updates

Co-authored-by: aidasofialily-cmd <247843425+aidasofialily-cmd@users.noreply.github.com>
---
 .Jules/palette.md |  8 ++++++++
 src/main.cpp      | 13 +++++++------
 src/utils.hpp     | 21 +++++++++++++++++++++
 3 files changed, 36 insertions(+), 6 deletions(-)
 create mode 100644 src/utils.hpp

diff --git a/.Jules/palette.md b/.Jules/palette.md
index 05d4366..217ef45 100644
--- a/.Jules/palette.md
+++ b/.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-07-07 - Contextual Achievement Feedback
+**Learning:** Announcing a "New Best" is more impactful when the player can immediately see the magnitude of their improvement. Providing the previous record in the announcement (e.g., "was 1,000") provides instant context and enhances the sense of progression without requiring the player to remember their past performance.
+**Action:** Always include the previous milestone or record value when celebrating achievements in games or progress-based interfaces.
+
+## 2026-07-07 - Numeric Readability in CLI
+**Learning:** In terminal applications, large raw integers are difficult to parse at a glance, especially during fast-paced interactions. Implementing thousands-separator formatting (e.g., "1,000,000") significantly reduces cognitive load and allows for immediate comprehension of numeric values.
+**Action:** Use a standardized `formatWithCommas` utility for all user-facing numeric displays exceeding three digits in CLI tools.
diff --git a/src/main.cpp b/src/main.cpp
index 60ae556..e29562e 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -9,6 +9,7 @@
 #include <algorithm>
 #include <csignal>
 #include <cstdlib>
+#include "utils.hpp"
 
 // Color and formatting macros for terminal output
 #define RESET     "\033[0m"
@@ -78,7 +79,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,10 +143,10 @@ 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! 🥳" : "")
-                      << std::flush;
+                      << (score > initialHighscore ? CLR_CTRL " NEW BEST! ✨🥳 (was " + formatWithCommas(initialHighscore) + ")" : "")
+                      << CLR_RESET << std::flush;
             updateUI = false;
         }
     }
@@ -155,9 +156,9 @@ 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";
+        std::cout << "Congratulations! A new personal best of " << CLR_SCORE << formatWithCommas(score) << CLR_RESET << "!\n";
     }
     std::cout << "Thanks for playing!\n";
     std::cout << "\033[?25h" << std::flush;
diff --git a/src/utils.hpp b/src/utils.hpp
new file mode 100644
index 0000000..9daff10
--- /dev/null
+++ b/src/utils.hpp
@@ -0,0 +1,21 @@
+#ifndef UTILS_HPP
+#define UTILS_HPP
+
+#include <string>
+
+/**
+ * Formats a long long value with comma separators for thousands.
+ * Example: 1000 -> "1,000", -1234567 -> "-1,234,567"
+ */
+inline std::string formatWithCommas(long long value) {
+    std::string s = std::to_string(value);
+    int limit = (value < 0) ? 1 : 0;
+    int insertPosition = static_cast<int>(s.length()) - 3;
+    while (insertPosition > limit) {
+        s.insert(insertPosition, ",");
+        insertPosition -= 3;
+    }
+    return s;
+}
+
+#endif