feat: improve arrow key handling to fix stray AB chars; add left/right navigation; update analyze docs

README.md

@@ -8,6 +8,7 @@
 
 - 🦡 **Deep System Cleanup** - Remove hidden caches, logs, and temp files in one sweep
 - 📦 **Smart Uninstall** - Complete app removal with all related files and folders
+- 📊 **Disk Space Analyzer** - Visualize disk usage with lightning-fast mdfind + du hybrid scanning
 - ⚡️ **Fast Interactive UI** - Arrow-key navigation with pagination for large lists
 - 🧹 **Massive Space Recovery** - Reclaim 100GB+ of wasted disk space
 
@@ -23,6 +24,7 @@ curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
 mole               # Interactive main menu
 mole clean         # Deep system cleanup
 mole uninstall     # Interactive app uninstaller
+mole analyze [path]# Analyze disk space (default: home directory)
 mole --help        # Show help
 ```
 
@@ -83,6 +85,84 @@ Select Apps to Remove
 ====================================================================
 ```
 
+### Disk Space Analyzer
+
+```bash
+# Quick start - explore your home directory
+$ mole analyze
+
+# View all disk volumes and major locations
+$ mole analyze --all
+
+💾 Disk Volumes & Locations
+
+  TYPE  SIZE        LOCATION
+  ────────────────────────────────────────────────────────────────────────────────
+▶ 💿  245.3GB     Macintosh HD (Root)
+  🏠  89.2GB      ~
+  📚  45.1GB      ~/Library
+  📁  33.7GB      ~/Downloads
+  📁  18.4GB      ~/Documents
+  🔌  128.0GB     External Drive
+
+# Explore specific directory with progress bar
+$ mole analyze ~/Downloads
+
+  📊 [████████████] 100% (25/25)  ← Real-time scanning progress
+
+📊 Disk Space Explorer
+
+  Current: ~/Downloads
+  ↑/↓: Navigate | → / Enter: Open folder | ← / Backspace: Back | q: Quit
+
+  Items (sorted by size):
+
+  TYPE  SIZE        NAME
+  ────────────────────────────────────────────────────────────────────────────────
+  ▶ 📁   33.72GB      materials       ← Use arrow keys to select
+    📁   5.67GB       learning
+    📁   4.50GB       projects
+    🎬   1.68GB       recording.mov   ← Files can't be opened
+    🎬   1.58GB       presentation.mov
+    📦   1.20GB       OldInstaller.dmg
+    📁   2.22GB       shared
+    📁   1.78GB       recent
+    ... and 12 more items
+
+# Press Enter on "materials" folder to drill down:
+
+📊 Disk Space Explorer
+
+  Current: ~/Downloads/materials
+  ↑/↓: Navigate | → / Enter: Open folder | ← / Backspace: Back | q: Quit
+
+  Items (sorted by size):
+
+  ▶ 📁   15.2GB       videos          ← Keep drilling down
+    📁   10.1GB       documents
+    📁   6.8GB        images
+    🎬   2.5GB        demo.mov
+```
+
+**Interactive Navigation:**
+
+- **Instant startup** - no waiting for initial scan
+- **Real-time progress** - visual progress bar when scanning (10+ directories)
+- **All volumes view** - `--all` flag shows all disks and major locations
+- **Files and folders mixed together**, sorted by size (largest first)
+- Shows **top 16 items** per directory (largest items only)
+- Use **↑/↓** arrow keys to navigate (green arrow ▶ shows selection)
+- Press **Enter** on a 📁 folder to drill down into it
+- Press **Backspace** or **←** to go back to parent directory
+- Press **q** to quit at any time
+- **Color coding**: Red folders >10GB, Yellow >1GB, Blue <1GB
+- Files (📦🎬📄🖼️📊) are shown but can't be opened (only folders)
+
+**Performance:**
+- **Fast scanning** - real-time progress bar for large directories (10+ folders)
+- **Smart caching** - sizes are calculated once and cached during navigation
+- **Top 16 only** - shows largest items first, keeps interface clean and fast
+
 ## What Mole Cleans
 
 | Category | Targets | Typical Recovery |

lib/common.sh

@@ -11,6 +11,7 @@ readonly BLUE="${ESC}[0;34m"
 readonly YELLOW="${ESC}[1;33m"
 readonly PURPLE="${ESC}[0;35m"
 readonly RED="${ESC}[0;31m"
+readonly GRAY="${ESC}[0;90m"
 readonly NC="${ESC}[0m"
 
 # Logging configuration
@@ -88,14 +89,12 @@ show_cursor() {
 
 # Keyboard input handling (simple and robust)
 read_key() {
-    local key rest
+    local key
-    # Use macOS bash 3.2 compatible read syntax
     IFS= read -r -s -n 1 key || return 1
 
-    # Some terminals can yield empty on Enter with -n1; treat as ENTER
+    # Empty = ENTER (some terminals)
     if [[ -z "$key" ]]; then
-        echo "ENTER"
+        echo "ENTER"; return 0
-        return 0
     fi
 
     case "$key" in
@@ -105,18 +104,29 @@ read_key() {
         'a'|'A') echo "ALL" ;;
         'n'|'N') echo "NONE" ;;
         '?') echo "HELP" ;;
+        $'\x7f'|$'\b') echo "BACKSPACE" ;;  # Support Backspace
         $'\x1b')
-            # Read the next two bytes within 1s; works well on macOS bash 3.2
+            # Non-blocking, byte-by-byte escape sequence parsing to avoid leaking 'A'/'B'
-            if IFS= read -r -s -n 2 -t 1 rest 2>/dev/null; then
+            local next third
-                case "$rest" in
+            if IFS= read -r -s -n 1 -t 0.02 next 2>/dev/null; then
-                    "[A") echo "UP" ;;
+                if [[ "$next" == "[" ]]; then
-                    "[B") echo "DOWN" ;;
+                    if IFS= read -r -s -n 1 -t 0.02 third 2>/dev/null; then
-                    "[C") echo "RIGHT" ;;
+                        case "$third" in
-                    "[D") echo "LEFT" ;;
+                            'A') echo "UP" ;;
-                    *) echo "OTHER" ;;
+                            'B') echo "DOWN" ;;
-                esac
+                            'C') echo "RIGHT" ;;
+                            'D') echo "LEFT" ;;
+                            *) echo "OTHER" ;;
+                        esac
+                    else
+                        echo "OTHER"
+                    fi
+                else
+                    # ESC followed by something else (e.g. ALT key combos)
+                    echo "OTHER"
+                fi
             else
-                # ESC pressed alone - treat as quit
+                # Bare ESC = quit
                 echo "QUIT"
             fi
             ;;