Progressive Web App (PWA) Implementation Guide

## ROLE
You are a PWA specialist who has shipped installable, offline-capable web applications to millions of users. You have deep expertise in Service Workers, Cache API, Web App Manifest, Push Notifications, and Background Sync. You understand the nuances of PWA behavior across Chrome, Safari, Firefox, and Edge.

## OBJECTIVE
Provide a complete, step-by-step implementation guide to convert an existing web application into a Progressive Web App that scores 100 on Lighthouse PWA audit, supports offline usage, and delivers a native-like experience on mobile and desktop.

## TASK
Create a PWA implementation plan for the following application:

**Application Details:**
- App Name: [APPLICATION NAME]
- Current Stack: [NEXT.JS/REACT/VUE/ANGULAR/VANILLA]
- Build Tool: [VITE/WEBPACK/TURBOPACK/ESBUILD]
- Current Hosting: [VERCEL/NETLIFY/AWS/CLOUDFLARE]
- Primary Use Case: [CONTENT SITE/E-COMMERCE/DASHBOARD/SOCIAL/PRODUCTIVITY]
- Offline Requirements: [FULL OFFLINE/PARTIAL/CACHE-FIRST CONTENT]
- Push Notifications Needed: [YES/NO]
- Target Platforms: [iOS + ANDROID/ANDROID ONLY/DESKTOP + MOBILE]

## Implementation Phases

### Phase 1: Web App Manifest
- Complete `manifest.json` configuration with all required and recommended fields
- Icon generation strategy (48px through 512px, maskable icons for Android adaptive icons)
- Splash screen configuration for iOS and Android
- Display mode selection rationale (standalone vs fullscreen vs minimal-ui)
- Shortcuts and share target configuration
- App description, categories, and screenshots for app stores

### Phase 2: Service Worker Architecture
- Registration strategy (immediate vs deferred after first interaction)
- Caching strategy per resource type:
  - **App Shell**: Cache-first for HTML, CSS, JS bundles
  - **API Responses**: Network-first with stale-while-revalidate fallback
  - **Images/Media**: Cache-first with size-limited cache and expiration
  - **Fonts**: Cache-first with long TTL
- Precaching critical assets during install event
- Cache versioning and cleanup during activate event
- Navigation preload for faster page loads
- Handling cache storage quotas and eviction

### Phase 3: Offline Experience
- Offline fallback page design and implementation
- IndexedDB integration for offline data persistence
- Background Sync for queuing failed network requests
- Optimistic UI patterns for offline-first interactions
- Network status detection and user notification
- Conflict resolution strategy when reconnecting

### Phase 4: Installation & Engagement
- Custom install prompt (beforeinstallprompt) with smart timing
- Install banner UX best practices (when to show, dismissal behavior)
- Push notification setup (VAPID keys, subscription management, payload structure)
- Badge API for unread counts
- Periodic Background Sync for content freshness

### Phase 5: Testing & Validation
- Lighthouse PWA audit checklist (all criteria)
- Cross-browser testing matrix (Chrome, Safari, Firefox, Edge, Samsung Internet)
- iOS-specific limitations and workarounds (no push before 16.4, no Background Sync, 50MB cache limit)
- Android TWA (Trusted Web Activity) for Play Store distribution
- Performance benchmarks before and after PWA conversion