PWA_INSTALL_GUIDE.md

# BattleWords PWA Installation Guide

BattleWords can now be installed as a Progressive Web App (PWA) on your mobile device or desktop, giving you a native app experience directly from your browser!

## What is a PWA?

A Progressive Web App allows you to:
- ✅ Install BattleWords on your home screen (Android/iOS)
- ✅ Run in full-screen mode without browser UI
- ✅ Access the app quickly from your app drawer
- ✅ Get automatic updates (always the latest version)
- ✅ Basic offline functionality (cached assets)

## Installation Instructions

### Android (Chrome, Edge, Samsung Internet)

1. **Visit the app**: Open https://surn-battlewords.hf.space in Chrome
2. **Look for the install prompt**: A banner will appear at the bottom saying "Add BattleWords to Home screen"
3. **Tap "Add"** or **"Install"**
4. **Alternative method** (if no prompt):
   - Tap the **three-dot menu** (⋮) in the top-right
   - Select **"Install app"** or **"Add to Home screen"**
   - Tap **"Install"**
5. **Launch**: Find the BattleWords icon on your home screen and tap to open!

**Result**: The app opens full-screen without the browser address bar, just like a native app.

---

### iOS (Safari)

**Note**: iOS requires using Safari browser (Chrome/Firefox won't work for PWA installation)

1. **Visit the app**: Open https://surn-battlewords.hf.space in Safari
2. **Tap the Share button**: The square with an arrow pointing up (at the bottom of the screen)
3. **Scroll down** and tap **"Add to Home Screen"**
4. **Edit the name** (optional): You can rename it from "BattleWords" if desired
5. **Tap "Add"** in the top-right corner
6. **Launch**: Find the BattleWords icon on your home screen and tap to open!

**Result**: The app opens in standalone mode, similar to a native iOS app.

---

### Desktop (Chrome, Edge, Brave)

1. **Visit the app**: Open https://surn-battlewords.hf.space
2. **Look for the install icon**:
   - Chrome/Edge: Click the **install icon** (⊕) in the address bar
   - Or click the **three-dot menu** → **"Install BattleWords"**
3. **Click "Install"** in the confirmation dialog
4. **Launch**:
   - Windows: Find BattleWords in Start Menu or Desktop
   - Mac: Find BattleWords in Applications folder
   - Linux: Find in application launcher

**Result**: BattleWords opens in its own window, separate from your browser.

---

## Features of the PWA

### Works Immediately ✅
- Full game functionality (reveal cells, guess words, scoring)
- Challenge Mode (create and play shared challenges)
- Sound effects and background music
- Ocean-themed animated background
- All current features preserved

### Offline Support 🌐
- App shell cached for faster loading
- Icons and static assets available offline
- **Note**: Challenge Mode requires internet connection (needs to fetch/save from HuggingFace)

### Updates 🔄
- Automatic updates when you open the app
- Always get the latest features and bug fixes
- No manual update process needed

### Privacy & Security 🔒
- No new data collection (same as web version)
- Environment variables stay on server (never exposed to PWA)
- Service worker only caches public assets
- All game data in Challenge Mode handled server-side

---

## Uninstalling the PWA

### Android
1. Long-press the BattleWords icon
2. Tap "Uninstall" or drag to "Remove"

### iOS
1. Long-press the BattleWords icon
2. Tap "Remove App"
3. Confirm "Delete App"

### Desktop
- **Chrome/Edge**: Go to `chrome://apps` or `edge://apps`, right-click BattleWords, select "Uninstall"
- **Windows**: Settings → Apps → BattleWords → Uninstall
- **Mac**: Delete from Applications folder

---

## Troubleshooting

### "Install" option doesn't appear
- **Android**: Make sure you're using Chrome, Edge, or Samsung Internet (not Firefox)
- **iOS**: Must use Safari browser
- **Desktop**: Check if you're using a supported browser (Chrome, Edge, Brave)
- Try refreshing the page (the install prompt may take a moment to appear)

### App won't open after installation
- Try uninstalling and reinstalling
- Clear browser cache and try again
- Make sure you have internet connection for first launch

### Service worker errors in console
- This is normal during development
- The app will still function without the service worker
- Full offline support requires the service worker to register successfully

### Icons don't show up correctly
- Wait a moment after installation (icons may take time to download)
- Try force-refreshing the PWA (close and reopen)

---

## Technical Details

### Files Added for PWA Support

```
battlewords/
├── static/
│   ├── manifest.json          # PWA configuration
│   ├── service-worker.js      # Offline caching logic
│   ├── icon-192.png          # App icon (small)
│   └── icon-512.png          # App icon (large)
└── ui.py                     # Added PWA meta tags
```

### What's Cached Offline

- App shell (HTML structure)
- Icons (192x192, 512x512)
- Manifest file
- Previous game states (if you were playing before going offline)

### What Requires Internet

- Creating new challenges
- Submitting results to leaderboards
- Loading shared challenges
- Downloading word lists (first time)
- Fetching game updates

---

## Comparison: PWA vs Native App

| Feature | PWA | Native App |
|---------|-----|------------|
| Installation | Quick (1 tap) | Slow (app store) |
| Size | ~5-10 MB | ~15-30 MB |
| Updates | Automatic | Manual |
| Platform support | Android, iOS, Desktop | Separate builds |
| Offline mode | Partial | Full |
| Performance | 90% of native | 100% |
| App store presence | No | Yes |
| Development time | 2-4 hours ✅ | 40-60 hours per platform |

---

## Feedback

If you encounter issues installing or using the PWA, please:
1. Check the browser console for errors (F12 → Console tab)
2. Report issues at: https://github.com/Oncorporation/BattleWords/issues
3. Include: Device type, OS version, browser version, and error messages

---

## For Developers

To regenerate the PWA icons:
```bash
python3 generate_pwa_icons.py
```

To modify PWA behavior:
- Edit `battlewords/static/manifest.json` (app metadata)
- Edit `battlewords/static/service-worker.js` (caching logic)
- Edit `battlewords/ui.py` (PWA meta tags, lines 34-86)

To test PWA locally:
```bash
streamlit run app.py
# Open http://localhost:8501 in Chrome
# Chrome DevTools → Application → Manifest (verify manifest.json loads)
# Chrome DevTools → Application → Service Workers (verify registration)
```

---

**Enjoy BattleWords as a native-like app experience! 🎮🌊**