hytale-f2p-mirror/docs/UPDATE_SYSTEM_FIXES.md

# Update System Fixes Summary

## Overview
This document summarizes the fixes made to the launcher auto-update system to improve UX and fix macOS-specific issues.

## Issues Fixed

### 1. Duplicate Update Popups
**Problem:** Two different update UI files (`update.js` and `updater.js`) were both listening for update events, causing duplicate popups to appear.

**Solution:**
- Disabled `updater.js` in `index.html` (commented out the script tag)
- Now only `update.js` handles all update UI with improved features

### 2. Missing Skip Button
**Problem:** Users were soft-locked on the update screen with no way to dismiss it, especially problematic on macOS where auto-install often fails.

**Solution:**
- Added "Skip for now (not recommended)" button to update popup
- Skip button appears:
  - After 30 seconds (timeout fallback)
  - Immediately on any update error
  - After install attempt fails (5 second timeout)
  - Always visible once download completes

### 3. macOS Auto-Install Failure
**Problem:** `quitAndInstall()` silently fails on unsigned macOS apps, leaving users stuck.

**Solution:**
- Detect macOS in `main.js` and send `autoInstallSupported: false` flag
- On macOS, show "Download Manually (Recommended)" as primary action
- "Try Install & Restart" shown as secondary option
- Added force quit fallback in `install-update` handler for macOS
- Clear messaging: "Update downloaded but auto-install may not work on macOS"

### 4. Missing IPC Handlers
**Problem:** `open-download-page` IPC handler was not registered, causing errors when clicking manual download.

**Solution:**
- Added `open-download-page` handler in `main.js` that opens GitHub releases page
- Added `quitAndInstallUpdate` alias in `preload.js` for compatibility

### 5. Interface Blocking Not Removed
**Problem:** `unblockInterface()` method was called but never defined, leaving the UI blurred after closing popup.

**Solution:**
- Added complete `unblockInterface()` method that:
  - Removes `interface-blocked` class from main content
  - Removes `no-select` class from body
  - Properly removes event listeners using stored bound function references

### 6. Breathing Animation on Downloaded State
**Problem:** The pulse/breathing animation continued after download completed, which felt inappropriate for a "ready to install" state.

**Solution:**
- Remove `update-popup-pulse` class in `showUpdateDownloaded()` method

### 7. Player Name Not Synced on First Install
**Problem:** Player name entered during installation wasn't synced to settings page input.

**Solution:**
- In `install.js`, sync player name to both `playerName` and `settingsPlayerName` inputs after installation completes

## Files Modified

### `GUI/index.html`
- Commented out `updater.js` script tag (duplicate update UI)

### `GUI/js/update.js`
- Removed legacy `onUpdatePopup` listener
- Added `closeUpdatePopup()` method
- Added `unblockInterface()` method
- Added skip button to popup HTML
- Added skip button visibility logic (30s timeout, on error, after download)
- Added macOS detection and alternative UI (manual download as primary)
- Removed pulse animation when download completes
- Added console logging for debugging
- Added extra DOM check to prevent duplicate popups
- Fixed manual download button to show "Opened in browser" and close popup

### `main.js`
- Changed `autoUpdater.autoDownload` from `false` to `true`
- Added macOS error handling with `requiresManualDownload` flag
- Added `autoInstallSupported` flag to `update-downloaded` event
- Added `open-download-page` IPC handler
- Enhanced `install-update` handler with macOS force quit fallback

### `preload.js`
- Added `quitAndInstallUpdate` alias for `install-update` IPC

### `GUI/js/install.js`
- Sync player name to `settingsPlayerName` input after installation

### `backend/utils/clientPatcher.js`
- Removed server patching code (server uses pre-patched JAR from CDN)
- Simplified to client-only patching
- Removed unused imports: `crypto`, `AdmZip`, `execSync`, `spawn`, `getJavaExec`, `getBundledJavaPath`, `JRE_DIR`
- Removed unused methods: `stringToUtf8()`, `findAndReplaceDomainUtf8()`
- Cleaned up comments and documentation
- Localhost/local dev code moved to `clientPatcher.localhost.js.bak` for reference

## Testing

To test the update popup manually, you can temporarily add this debug code to `update.js` init():

```javascript
// DEBUG: Simulate update available popup after 2 seconds
setTimeout(() => {
    this.showUpdatePopup({
        currentVersion: '2.0.0',
        newVersion: '2.1.0',
        releaseNotes: 'Debug test update'
    });

    // Simulate download complete after 3 more seconds
    setTimeout(() => {
        this.showUpdateDownloaded({
            version: '2.1.0',
            platform: 'darwin',
            autoInstallSupported: false  // Simulate macOS
        });
    }, 3000);
}, 2000);
```

## Platform-Specific Behavior

### Windows/Linux
- Auto-download enabled
- "Install & Restart" as primary action
- Skip button available as fallback

### macOS
- Auto-download enabled (download works, install doesn't)
- "Download Manually (Recommended)" as primary action
- "Try Install & Restart" as secondary option
- Skip button always visible after download
- Force quit fallback if quitAndInstall fails