feat: Add PWA assets and metadata for iOS Safari installation

- Generate app icons in multiple sizes (192x192, 512x512, 180x180, 32x32) - Create favicon and apple-touch-icon SVG files - Add comprehensive PWA meta tags in app layout - Configure theme color (#3B82F6) and background color - Update manifest.json with icon references (PNG and SVG) - Create icon generation scripts (SVG and PNG conversion) - Add browser-based PNG icon generator (HTML) - Create comprehensive PWA testing guide - Add icon setup documentation Requirements: 4.1, 4.2 Task: 13. Add PWA assets and metadata
2025-12-01 20:39:11 +00:00
parent 9726f3a9e1
commit 6cb9a593d4
13 changed files with 1014 additions and 39 deletions
--- a/PWA_TESTING_GUIDE.md
+++ b/PWA_TESTING_GUIDE.md
@@ -0,0 +1,279 @@
+# PWA Testing Guide - Ultimate Lists App
+
+## Overview
+This guide helps you test the Progressive Web App (PWA) functionality of the Ultimate Lists app, with a focus on iOS Safari installation.
+
+## Prerequisites
+
+### Generate PNG Icons First
+Before testing, you need to generate PNG versions of the icons:
+
+**Option 1: Browser-based Generator (Easiest)**
+1. Open `scripts/generate-png-icons.html` in your browser
+2. Click "Download All Icons"
+3. Save each PNG file to the `public/` directory
+
+**Option 2: Using Sharp**
+```bash
+npm install --save-dev sharp
+node scripts/convert-with-sharp.js
+```
+
+**Option 3: Using ImageMagick**
+```bash
+brew install imagemagick  # macOS
+convert public/icon-192.svg -resize 192x192 public/icon-192.png
+convert public/icon-512.svg -resize 512x512 public/icon-512.png
+convert public/apple-touch-icon.svg -resize 180x180 public/apple-touch-icon.png
+convert public/favicon.svg -resize 32x32 public/favicon-32.png
+```
+
+## Testing on iOS Safari
+
+### Step 1: Deploy or Use Local Network
+The PWA must be served over HTTPS or localhost. For iOS testing:
+
+**Option A: Deploy to Vercel/Netlify**
+```bash
+npm run build
+# Deploy to your hosting provider
+```
+
+**Option B: Local Network Testing**
+1. Find your local IP: `ifconfig | grep "inet " | grep -v 127.0.0.1`
+2. Run dev server: `npm run dev`
+3. Access from iPhone: `http://YOUR_IP:3000`
+4. Note: Service workers require HTTPS in production
+
+### Step 2: Test Installation on iPhone/iPad
+
+1. **Open Safari** on your iOS device
+   - Navigate to your app URL
+   - Ensure the app loads correctly
+
+2. **Add to Home Screen**
+   - Tap the Share button (square with arrow)
+   - Scroll down and tap "Add to Home Screen"
+   - Verify the icon preview looks correct
+   - Verify the name is "Ultimate Lists"
+   - Tap "Add"
+
+3. **Verify Home Screen Icon**
+   - Check that the icon appears on your home screen
+   - Verify the icon is clear and not blurry
+   - Verify the icon has the correct colors (blue background, white checkmark)
+
+4. **Launch the App**
+   - Tap the icon on your home screen
+   - The app should open in standalone mode (no Safari UI)
+   - Verify the status bar style (should be translucent)
+   - Verify the app fills the screen properly
+
+### Step 3: Test PWA Features
+
+**Standalone Mode**
+- ✓ No Safari address bar visible
+- ✓ No Safari toolbar at bottom
+- ✓ App uses full screen (respecting safe areas)
+- ✓ Status bar is styled correctly
+
+**Offline Functionality**
+- ✓ Enable Airplane Mode
+- ✓ Open the app (should still load)
+- ✓ Navigate between pages (should work)
+- ✓ Create/edit tasks (should queue for sync)
+- ✓ Disable Airplane Mode
+- ✓ Verify changes sync to server
+
+**App Behavior**
+- ✓ App remembers state between launches
+- ✓ Smooth navigation without page reloads
+- ✓ Touch interactions work properly
+- ✓ Forms and inputs work correctly
+
+## Testing on Android Chrome
+
+### Step 1: Access the App
+1. Open Chrome on Android device
+2. Navigate to your app URL
+3. Ensure the app loads correctly
+
+### Step 2: Install the App
+1. Look for the "Add to Home screen" prompt (may appear automatically)
+2. Or tap the menu (⋮) → "Add to Home screen" or "Install app"
+3. Verify the icon and name
+4. Tap "Add" or "Install"
+
+### Step 3: Test PWA Features
+- ✓ App opens in standalone mode
+- ✓ Icon appears in app drawer
+- ✓ Offline functionality works
+- ✓ Can uninstall like a native app
+
+## Testing on Desktop
+
+### Chrome/Edge
+1. Open the app in Chrome or Edge
+2. Look for the install icon (⊕) in the address bar
+3. Click to install
+4. App opens in a standalone window
+5. Test offline mode using DevTools (Network → Offline)
+
+### Safari (macOS)
+1. Open the app in Safari
+2. File → Add to Dock
+3. App appears in Dock
+4. Opens in standalone window
+
+## Verification Checklist
+
+### Icons
+- [ ] Favicon appears in browser tab
+- [ ] Home screen icon is clear and properly sized
+- [ ] Icon has correct colors and design
+- [ ] Icon is not blurry or pixelated
+- [ ] Icon works on both light and dark backgrounds
+
+### Manifest
+- [ ] App name displays correctly
+- [ ] Theme color matches design (#3B82F6)
+- [ ] Background color is white
+- [ ] Display mode is "standalone"
+- [ ] Orientation is set correctly
+
+### Meta Tags
+- [ ] Apple touch icon loads correctly
+- [ ] Status bar style is appropriate
+- [ ] Viewport settings work on mobile
+- [ ] Theme color appears in browser UI
+
+### Service Worker
+- [ ] Service worker registers successfully
+- [ ] Static assets are cached
+- [ ] App works offline
+- [ ] Updates are handled properly
+
+### User Experience
+- [ ] App loads quickly
+- [ ] Navigation is smooth
+- [ ] Touch targets are appropriately sized
+- [ ] Forms work correctly
+- [ ] Data persists between sessions
+
+## Troubleshooting
+
+### Icon Not Showing on iOS
+**Problem**: Default icon or no icon appears
+
+**Solutions**:
+1. Ensure PNG files exist (iOS doesn't support SVG for touch icons)
+2. Check file paths in `app/layout.tsx`
+3. Verify files are in `public/` directory
+4. Clear Safari cache: Settings → Safari → Clear History and Website Data
+5. Remove and re-add to home screen
+
+### App Not Installing
+**Problem**: No "Add to Home Screen" option
+
+**Solutions**:
+1. Ensure manifest.json is accessible at `/manifest.json`
+2. Check browser console for errors
+3. Verify HTTPS (required for service workers)
+4. Check manifest.json syntax is valid
+5. Ensure all required manifest fields are present
+
+### Service Worker Not Working
+**Problem**: App doesn't work offline
+
+**Solutions**:
+1. Check browser console for service worker errors
+2. Verify service worker file is at `/sw.js`
+3. Ensure HTTPS (service workers require secure context)
+4. Check service worker registration in DevTools
+5. Try unregistering and re-registering service worker
+
+### Icon Blurry or Wrong Size
+**Problem**: Icon appears pixelated or wrong dimensions
+
+**Solutions**:
+1. Regenerate PNG icons at correct sizes
+2. Ensure PNG files are not compressed too much
+3. Verify icon dimensions match manifest.json
+4. Use higher resolution source images
+5. Test on actual device (not just simulator)
+
+### App Not Opening in Standalone Mode
+**Problem**: Safari UI still visible when opening from home screen
+
+**Solutions**:
+1. Check `apple-mobile-web-app-capable` meta tag is set to "yes"
+2. Verify manifest.json has `"display": "standalone"`
+3. Remove and re-add to home screen
+4. Check for JavaScript errors preventing proper initialization
+
+## Testing Tools
+
+### Browser DevTools
+- **Chrome DevTools**: Application → Manifest / Service Workers
+- **Safari DevTools**: Develop → Show Web Inspector → Storage
+- **Lighthouse**: Run PWA audit for comprehensive check
+
+### Online Tools
+- [PWA Builder](https://www.pwabuilder.com/) - Test and validate PWA
+- [Manifest Validator](https://manifest-validator.appspot.com/) - Validate manifest.json
+- [Web.dev PWA Checklist](https://web.dev/pwa-checklist/) - Comprehensive checklist
+
+### Command Line
+```bash
+# Check if files exist
+ls -la public/*.png public/*.svg public/manifest.json
+
+# Validate manifest.json
+cat public/manifest.json | jq .
+
+# Check service worker
+curl http://localhost:3000/sw.js
+```
+
+## Best Practices
+
+### Icon Design
+- Use simple, recognizable shapes
+- Ensure good contrast
+- Test on both light and dark backgrounds
+- Keep important content in the center 80%
+- Use consistent branding colors
+
+### Testing Workflow
+1. Test on actual devices (not just simulators)
+2. Test on multiple iOS versions
+3. Test on different Android devices
+4. Test offline functionality thoroughly
+5. Test on slow network connections
+6. Test with different screen sizes
+
+### Deployment
+1. Always use HTTPS in production
+2. Set appropriate cache headers
+3. Version your service worker
+4. Monitor service worker updates
+5. Test after each deployment
+
+## Success Criteria
+
+Your PWA is ready when:
+- ✓ Installs successfully on iOS Safari
+- ✓ Installs successfully on Android Chrome
+- ✓ Icon appears correctly on all platforms
+- ✓ Opens in standalone mode (no browser UI)
+- ✓ Works offline for core functionality
+- ✓ Passes Lighthouse PWA audit
+- ✓ Provides native-like experience
+- ✓ Handles updates gracefully
+
+## Additional Resources
+
+- [Apple PWA Documentation](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html)
+- [Google PWA Documentation](https://web.dev/progressive-web-apps/)
+- [MDN Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest)
+- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)