# Windows Troubleshooting Guide

## Overview

This guide addresses common issues when running the Shopify Price Updater TUI on Windows systems and provides solutions for optimal performance.

## Terminal Compatibility

### Recommended Terminals

#### Windows Terminal (Best Experience)

- **Download**: Microsoft Store or GitHub releases
- **Features**: Full Unicode support, true color, modern key handling
- **Configuration**: No additional setup required

#### PowerShell 7+ (Good Experience)

- **Download**: GitHub releases or Windows Package Manager
- **Features**: Good Unicode support, color support
- **Setup**:
  ```powershell
  winget install Microsoft.PowerShell
  ```

#### Command Prompt (Basic Experience)

- **Features**: Limited color support, basic functionality
- **Limitations**: No Unicode characters, limited colors

### Terminal Setup

#### Enable UTF-8 Support

```cmd
chcp 65001
```

#### PowerShell Profile Setup

Add to your PowerShell profile (`$PROFILE`):

```powershell
# Enable UTF-8 encoding
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8

# Set console to support ANSI escape sequences
$Host.UI.RawUI.WindowTitle = "PowerShell"
```

## Common Issues and Solutions

### Issue: Unicode Characters Not Displaying

**Symptoms:**

- Boxes, question marks, or missing characters in the TUI
- Progress bars showing incorrect characters

**Solutions:**

1. **Set Console Code Page:**

   ```cmd
   chcp 65001
   npm run tui
   ```

2. **Windows Terminal Configuration:**

   ```json
   {
   	"profiles": {
   		"defaults": {
   			"fontFace": "Cascadia Code",
   			"fontSize": 12
   		}
   	}
   }
   ```

3. **PowerShell Configuration:**
   ```powershell
   $OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding
   ```

### Issue: Colors Not Working

**Symptoms:**

- No colors in the interface
- All text appears in default terminal color

**Solutions:**

1. **Enable ANSI Support (Windows 10+):**

   ```cmd
   reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1
   ```

2. **Use Windows Terminal:**

   - Download from Microsoft Store
   - Automatically supports modern color features

3. **PowerShell Color Support:**
   ```powershell
   # Check if colors are supported
   $Host.UI.SupportsVirtualTerminal
   ```

### Issue: Keyboard Input Problems

**Symptoms:**

- Arrow keys not working
- Special keys producing unexpected characters
- Navigation not responding

**Solutions:**

1. **Windows Terminal (Recommended):**

   - Use Windows Terminal for best keyboard support
   - Supports all modern key sequences

2. **PowerShell ISE Alternative:**

   - Don't use PowerShell ISE - use regular PowerShell or Windows Terminal

3. **Command Prompt Limitations:**
   - Limited key support - consider upgrading to Windows Terminal

### Issue: Performance Problems

**Symptoms:**

- Slow rendering
- Flickering interface
- High CPU usage

**Solutions:**

1. **Windows Terminal Optimization:**

   ```json
   {
   	"profiles": {
   		"defaults": {
   			"useAcrylic": false,
   			"acrylicOpacity": 1.0
   		}
   	}
   }
   ```

2. **Disable Windows Defender Real-time Scanning:**

   - Add Node.js to exclusions
   - Add project directory to exclusions

3. **Close Unnecessary Applications:**
   - Free up system resources
   - Close other terminal windows

### Issue: Font and Display Problems

**Symptoms:**

- Misaligned text
- Incorrect character spacing
- Overlapping text

**Solutions:**

1. **Use Monospace Fonts:**

   - Cascadia Code (recommended)
   - Consolas
   - Courier New

2. **Windows Terminal Font Configuration:**

   ```json
   {
   	"profiles": {
   		"defaults": {
   			"fontFace": "Cascadia Code",
   			"fontSize": 12,
   			"fontWeight": "normal"
   		}
   	}
   }
   ```

3. **Adjust Terminal Size:**
   - Ensure minimum 80x24 characters
   - Avoid very small terminal windows

## Windows-Specific Features

### Windows Terminal Integration

The TUI includes specific optimizations for Windows Terminal:

- **True Color Support**: Full 24-bit color palette
- **Unicode Rendering**: Enhanced character support
- **Mouse Support**: Click interactions where appropriate
- **Resize Handling**: Automatic layout adjustment

### PowerShell Integration

- **Profile Integration**: Works with PowerShell profiles
- **Module Loading**: Compatible with PowerShell modules
- **Error Handling**: Windows-specific error messages

### Command Prompt Compatibility

- **Graceful Degradation**: Reduced features for compatibility
- **Basic Colors**: Limited color palette
- **Essential Functions**: Core functionality maintained

## Environment Variables

### Windows-Specific Settings

```env
# Windows Terminal optimization
FORCE_COLOR=1
NO_COLOR=0

# Console encoding
PYTHONIOENCODING=utf-8
```

### PowerShell Environment

```powershell
# Set in PowerShell profile
$env:FORCE_COLOR = "1"
$env:NO_COLOR = "0"
```

## Installation Issues

### Node.js Version Problems

**Issue:** TUI fails to start with Node.js version errors

**Solution:**

```cmd
# Check Node.js version
node --version

# Should be 16.0.0 or higher
# Update if necessary from nodejs.org
```

### NPM Permission Issues

**Issue:** Permission denied errors during npm install

**Solutions:**

1. **Run as Administrator:**

   ```cmd
   # Right-click Command Prompt/PowerShell
   # Select "Run as administrator"
   npm install
   ```

2. **Configure NPM Prefix:**
   ```cmd
   npm config set prefix %APPDATA%\npm
   ```

### Dependency Installation Problems

**Issue:** Native module compilation failures

**Solutions:**

1. **Install Build Tools:**

   ```cmd
   npm install -g windows-build-tools
   ```

2. **Visual Studio Build Tools:**
   ```cmd
   # Download from Microsoft
   # Install C++ build tools
   ```

## Performance Optimization

### Windows Terminal Settings

```json
{
	"profiles": {
		"defaults": {
			"useAcrylic": false,
			"scrollbarState": "hidden",
			"snapOnInput": true,
			"historySize": 9001
		}
	},
	"rendering": {
		"forceFullRepaint": false,
		"software": false
	}
}
```

### System Optimization

1. **Disable Visual Effects:**

   - Control Panel → System → Advanced → Performance → Adjust for best performance

2. **Power Settings:**

   - Set to "High Performance" mode

3. **Background Apps:**
   - Disable unnecessary background applications

## Debugging

### Enable Debug Mode

```cmd
set DEBUG=shopify-price-updater:*
npm run tui
```

### Log Collection

```cmd
# Redirect output to file
npm run tui > debug.log 2>&1
```

### System Information

```cmd
# Collect system info
systeminfo > system-info.txt
node --version >> system-info.txt
npm --version >> system-info.txt
```

## Advanced Configuration

### Registry Settings

```cmd
# Enable ANSI escape sequences (Windows 10+)
reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1

# Disable QuickEdit mode (prevents accidental pausing)
reg add HKCU\Console /v QuickEdit /t REG_DWORD /d 0
```

### Windows Terminal Custom Actions

```json
{
	"actions": [
		{
			"command": {
				"action": "sendInput",
				"input": "npm run tui\r"
			},
			"keys": "ctrl+shift+t"
		}
	]
}
```

## Getting Help

### Information to Collect

When reporting Windows-specific issues, include:

1. **Windows Version:**

   ```cmd
   winver
   ```

2. **Terminal Information:**

   ```cmd
   echo $env:TERM
   ```

3. **Node.js Version:**

   ```cmd
   node --version
   npm --version
   ```

4. **Error Messages:**
   - Full error output
   - Stack traces if available

### Support Resources

- **Windows Terminal Issues**: GitHub repository
- **PowerShell Issues**: PowerShell GitHub repository
- **Node.js Issues**: Node.js support channels
- **Application Issues**: Project repository

## Best Practices

### Development Environment

1. **Use Windows Terminal** for the best experience
2. **Keep Node.js Updated** to the latest LTS version
3. **Use PowerShell 7+** instead of Windows PowerShell 5.1
4. **Configure UTF-8 Encoding** in your terminal profile

### Production Usage

1. **Test in Target Environment** before deployment
2. **Document Terminal Requirements** for end users
3. **Provide Fallback Instructions** for older terminals
4. **Monitor Performance** on target systems

### Maintenance

1. **Regular Updates** of terminal applications
2. **Monitor Windows Updates** that might affect terminal behavior
3. **Keep Dependencies Updated** for security and compatibility
4. **Test After System Updates** to ensure continued functionality