Merge main (rev2 changes) into rev3-dynamic-splitscreen

Merges all rev2 improvements into the v3.0 dynamic splitscreen branch:

From rev2 (main):
- cleanup-minecraft-splitscreen.sh: Complete uninstaller script
- Smart Steam Deck controller handling (OLED detection, virtual controllers)
- Architecture-aware AppImage downloads (x86_64/ARM64)
- Improved timeout handling in prompts
- TMPDIR environment variable support
- Enhanced logging with log_debug function
- Flatpak --system flag for remote selection
- Various bug fixes across all modules

Merged into rev3:
- Dynamic splitscreen mode (players join/leave mid-session)
- Controller hotplug detection
- Automatic window repositioning
- Desktop notifications

Conflict resolutions:
- Version headers: Keep 3.0.0, merge changelogs
- launcher_script_generator.sh: Integrate rev2 fixes (TMPDIR, log_debug,
  promptControllerMode) into rev3 dynamic mode structure
- CLAUDE.md/README.md: Include both Issue #5 (DONE) and Issue #6 (TODO)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: aradanmn

.gitignore

@@ -6,6 +6,7 @@
 !README.md
 !CLAUDE.md
 !install-minecraft-splitscreen.sh
+!cleanup-minecraft-splitscreen.sh
 !minecraftSplitscreen.sh
 !add-to-steam.py
 !accounts.json

CLAUDE.md

@@ -23,6 +23,7 @@ After successful setup, PrismLauncher files are cleaned up, leaving only PollyMC
 ```
 /
 ├── install-minecraft-splitscreen.sh    # Main entry point (386 lines)
+├── cleanup-minecraft-splitscreen.sh    # Uninstaller script (removes all components)
 ├── add-to-steam.py                     # Python script for Steam integration
 ├── accounts.json                       # Pre-configured offline accounts (P1-P4)
 ├── token.enc                           # Encrypted CurseForge API token
@@ -134,6 +135,35 @@ All modules use this header format:
 # - function1()
 ```
 
+### Versioning Convention (IMPORTANT)
+
+**When modifying any module file, you MUST update its version number and changelog.**
+
+Version format: `Major.Minor.Patch` (e.g., `2.1.0`)
+
+| Component | When to Increment | Example |
+|-----------|-------------------|---------|
+| **Major** | Breaking changes, complete rewrites, new major release | 1.x.x → 2.0.0 |
+| **Minor** | New features, significant improvements | 2.0.x → 2.1.0 |
+| **Patch** | Bug fixes, small changes | 2.1.0 → 2.1.1 |
+
+**Version history:**
+- `1.x.x` = Original flyingEwok era
+- `2.x.x` = aradanmn fork (current)
+- `3.x.x` = Reserved for future major release (e.g., dynamic splitscreen)
+
+**Update checklist when modifying a file:**
+1. Increment `@version` tag appropriately
+2. Update `@date` to current date
+3. Add changelog entry with version, date, and description:
+   ```bash
+   # @changelog
+   #   2.1.1 (2026-01-31) - Fix: Description of the bug fix
+   #   2.1.0 (2026-01-30) - Added new feature X
+   ```
+
+**Global version:** `SCRIPT_VERSION` in `version_info.sh` should match the highest module version for releases.
+
 ### Print Functions (from utilities.sh)
 
 ```bash
@@ -285,6 +315,7 @@ The installer generates `minecraftSplitscreen.sh` at runtime with:
 | File | Lines | Purpose |
 |------|-------|---------|
 | `install-minecraft-splitscreen.sh` | ~386 | Entry point, module loader |
+| `cleanup-minecraft-splitscreen.sh` | ~490 | Uninstaller (removes all components) |
 | `modules/path_configuration.sh` | ~600+ | Path management (CRITICAL) |
 | `modules/mod_management.sh` | ~1900 | Mod compatibility (largest) |
 | `modules/main_workflow.sh` | ~1300 | Main orchestration |
@@ -304,6 +335,59 @@ The installer generates `minecraftSplitscreen.sh` at runtime with:
 9. **System Integration** - Steam, desktop shortcuts
 10. **Completion Report** - Summary with paths and usage
 
+## Cleanup Script
+
+The `cleanup-minecraft-splitscreen.sh` script removes all components installed by the installer:
+
+```bash
+# Preview what would be removed (dry-run mode)
+./cleanup-minecraft-splitscreen.sh --dry-run
+
+# Clean everything except Java (default)
+./cleanup-minecraft-splitscreen.sh
+
+# Clean everything including Java, no prompts
+./cleanup-minecraft-splitscreen.sh --remove-java --force
+
+# Remote cleanup via SSH
+ssh deck@steamdeck './cleanup-minecraft-splitscreen.sh --force'
+```
+
+**What it removes:**
+- PollyMC data and AppImage (`~/.local/share/PollyMC`)
+- PollyMC Flatpak data (`~/.var/app/org.fn2006.PollyMC`)
+- PrismLauncher data and AppImage (`~/.local/share/PrismLauncher`)
+- PrismLauncher Flatpak data (`~/.var/app/org.prismlauncher.PrismLauncher`)
+- Flatpak applications (PollyMC, PrismLauncher)
+- Desktop shortcuts and app menu entries
+- Installer logs (`~/.local/share/MinecraftSplitscreen`)
+
+**What it preserves by default:**
+- Java installations (`~/.local/jdk/`) - use `--remove-java` to delete
+
+**Note:** Steam shortcuts (non-Steam games) must be removed manually in Steam.
+
+## Known Issues
+
+### SSH + curl | bash Causes Script Crash
+
+**Problem:** When running the installer via `curl | bash` over SSH, the script crashes at interactive prompts (exit code 139/SIGSEGV).
+
+**Root Cause:** The `prompt_user` function tries to read from `/dev/tty` for `curl | bash` compatibility, but this fails in certain SSH configurations.
+
+**Workaround:** Download the script first, then run it directly:
+
+```bash
+# Instead of: curl -fsSL URL | bash
+
+# Do this:
+curl -fsSL https://raw.githubusercontent.com/aradanmn/MinecraftSplitscreenSteamdeck/main/install-minecraft-splitscreen.sh -o /tmp/install.sh
+chmod +x /tmp/install.sh
+INSTALLER_SOURCE_URL=https://raw.githubusercontent.com/aradanmn/MinecraftSplitscreenSteamdeck/main/install-minecraft-splitscreen.sh /tmp/install.sh
+```
+
+**Status:** Affects remote SSH testing. Local execution works fine.
+
 ## TODO Items (from README)
 
 1. Steam Deck controller handling without system-wide disable
@@ -329,15 +413,37 @@ The installer generates `minecraftSplitscreen.sh` at runtime with:
 
 ---
 
-### Issue #2: Steam Deck Virtual Controller Detection (MEDIUM PRIORITY)
-**Problem:** When launching on Steam Deck without external controllers, the script detects the Steam virtual controller, filters it out, and then stops because no "real" controllers remain.
+### Issue #2: Steam Deck Controller Issues (MEDIUM PRIORITY)
+
+**Problem A: No Controllers Detected**
+When launching on Steam Deck without external controllers, the script detects the Steam virtual controller, filters it out, and then stops because no "real" controllers remain.
+
+**Problem B: Double Button Presses in Desktop Mode**
+When Steam is running in Desktop Mode, the Steam Deck's physical controls AND Steam's virtual controller BOTH send input to the game, causing every button press to register twice.
+
+**Root Cause:** Steam Input creates virtual controller devices that mirror physical inputs. In Desktop Mode with Steam running:
+- Physical controller → `/dev/input/js0` → game
+- Steam virtual controller → `/dev/input/js1` → game (duplicate!)
 
-**Current State:** The launcher script correctly filters Steam virtual controllers but doesn't handle the case where that's the ONLY controller available.
+**Current State:** The launcher script tries to filter Steam virtual controllers but:
+1. Doesn't handle when virtual controller is the ONLY option
+2. Doesn't prevent double-input when both physical AND virtual are active
 
-**Solution:** Modify controller detection logic to:
-- If on Steam Deck AND only Steam virtual controller detected AND no external controllers → allow using Steam Deck as Player 1
-- Provide a fallback "keyboard only" mode or prompt user
-- Consider: Steam Deck's built-in controls should count as 1 player
+**Solution Approaches:**
+
+*For Problem A (no controllers):*
+- If on Steam Deck AND only Steam virtual controller detected → allow using it as Player 1
+- Provide "keyboard only" fallback mode
+
+*For Problem B (double presses):*
+1. **User-side fix:** Disable Steam Input per-game in Steam properties
+2. **Script-side detection:** Warn user when both physical and virtual detected
+3. **Script-side fix:** Before launching, advise user to either:
+   - Launch from Game Mode (Steam handles this correctly there)
+   - Disable Steam Input for Minecraft in Steam settings
+   - Close Steam before launching (if not using Steam integration)
+
+**Controllable Mod Note:** The Controllable mod has device selection settings. Users may be able to manually select only the physical controller there. Worth documenting.
 
 **Files to modify:** `modules/launcher_script_generator.sh` (the generated script template)
 
@@ -412,12 +518,78 @@ The installer generates `minecraftSplitscreen.sh` at runtime with:
 
 ---
 
+### Issue #6: Detect Previous Installation (MEDIUM PRIORITY)
+**Problem:** When users run the installer multiple times, it starts fresh each time without recognizing existing installations. Users may want to update mods, change Minecraft version, or modify their setup without full reinstallation.
+
+**Desired Behavior:**
+- Detect if splitscreen instances already exist (check for `latestUpdate-1` through `latestUpdate-4`)
+- Detect existing launcher script (`minecraftSplitscreen.sh`)
+- If previous installation found, prompt user with options:
+  1. **Update** - Keep same Minecraft version, update mods to latest compatible
+  2. **Change Version** - Select new Minecraft version, reinstall mods
+  3. **Reconfigure** - Change mod selection (add/remove mods)
+  4. **Fresh Install** - Delete existing and start over
+  5. **Cancel** - Exit without changes
+
+**Detection Method: Config File**
+Save installation config to: `~/.local/share/MinecraftSplitscreen/install-config.json`
+
+```json
+{
+  "version": "3.0.0",
+  "installed_at": "2026-01-31T19:18:01Z",
+  "updated_at": "2026-01-31T19:18:01Z",
+  "minecraft_version": "1.21.4",
+  "fabric_version": "0.16.10",
+  "launcher": {
+    "type": "pollymc",
+    "install_type": "flatpak",
+    "data_dir": "/home/deck/.var/app/org.fn2006.PollyMC/data/PollyMC"
+  },
+  "mods": {
+    "selected": ["fabric-api", "controllable", "worldhost", "cloth-config"],
+    "versions": {
+      "fabric-api": "0.92.1",
+      "controllable": "1.2.3"
+    }
+  },
+  "instances": ["latestUpdate-1", "latestUpdate-2", "latestUpdate-3", "latestUpdate-4"],
+  "options": {
+    "steam_integration": true,
+    "desktop_shortcut": true,
+    "dynamic_mode_available": true
+  }
+}
+```
+
+**Benefits:**
+- Single file to check for previous installation
+- Contains all selections without parsing instance files
+- Easy to read/write with `jq`
+- Version field allows migration if format changes
+- `updated_at` tracks when last modified
+
+**Files to modify:**
+- `modules/main_workflow.sh` - Add detection at start of `run_installation()`
+- `modules/utilities.sh` - Add `detect_existing_installation()` and `save_install_config()` functions
+- Potentially new module: `modules/update_management.sh` for update logic
+
+**Considerations:**
+- Preserve user's Microsoft account if they added one
+- Preserve any custom JVM arguments
+- Handle partial installations gracefully (config exists but instances missing)
+- Log what was detected and what action was taken
+- Use `jq` for JSON parsing (already a dependency)
+
+---
+
 ### Implementation Order
 1. ✅ **Issue #3 (Logging)** - DONE. All print_* functions auto-log.
 2. ✅ **Issue #1 (User Input)** - DONE. All modules refactored to use `prompt_user()` and `prompt_yes_no()`.
 3. ✅ **Issue #5 (Dynamic Splitscreen)** - DONE. Players can join/leave mid-session.
-4. ⏳ **Issue #2 (Controller Detection)** - Improves Steam Deck UX
-5. ⏳ **Issue #4 (Versioning)** - Can wait until Minecraft actually releases new format
+4. ⏳ **Issue #6 (Previous Installation Detection)** - Improves repeat user experience
+5. ⏳ **Issue #2 (Controller Detection)** - Improves Steam Deck UX
+6. ⏳ **Issue #4 (Versioning)** - Can wait until Minecraft actually releases new format
 
 ## Useful Debugging