@djangocfg/layouts 2.1.35 → 2.1.37

package/src/snippets/PWA/@refactoring2/RECOMMENDATIONS.md

@@ -0,0 +1,1321 @@
+# Recommendations: How to Fix Remaining Issues
+
+**Date**: December 2025
+**Context**: Post-P0 Refactoring
+
+This document provides **actionable recommendations** with **ready-to-use code** for fixing all remaining issues identified in [REMAINING-ISSUES.md](./REMAINING-ISSUES.md).
+
+---
+
+## Table of Contents
+
+### P1 (High Priority) - ~30 minutes total
+1. [Fix Security Vulnerability](#1-fix-security-vulnerability-p1-1) (5 min)
+2. [Fix Inconsistent Logging](#2-fix-inconsistent-logging-p1-2) (10 min)
+3. [Centralize LocalStorage Keys](#3-centralize-localstorage-keys-p1-3) (15 min)
+
+### P2 (Medium Priority) - ~4 hours total
+4. [Handle Unused EngagementMetrics](#4-handle-unused-engagementmetrics-p2-1) (30 min)
+5. [Simplify Context Composition](#5-simplify-context-composition-p2-2) (30 min)
+6. [Add Server-Side Persistence](#6-add-server-side-persistence-p2-3) (1.5 hours)
+7. [Improve Error Recovery](#7-improve-error-recovery-p2-4) (1 hour)
+
+### P3 (Nice to Have) - Ongoing
+8. [Add Testing](#8-add-testing-p3-1) (4-8 hours)
+9. [Improve Accessibility](#9-improve-accessibility-p3-2) (2-3 hours)
+10. [Enable TypeScript Strict Mode](#10-enable-typescript-strict-mode-p3-3) (2-4 hours)
+
+---
+
+## P1: High Priority Fixes
+
+### 1. Fix Security Vulnerability (P1-1)
+
+**Issue**: `config.ts` exposes `VAPID_PRIVATE_KEY` in frontend package
+
+**File**: `src/snippets/PWA/config.ts`
+
+**Current Code** (lines 7-11):
+```typescript
+// ❌ SECURITY VULNERABILITY
+export const DEFAULT_VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '';
+export const VAPID_PRIVATE_KEY = process.env.VAPID_PRIVATE_KEY || '';
+export const VAPID_MAILTO = process.env.VAPID_MAILTO || '';
+```
+
+**✅ Fixed Code**:
+```typescript
+/**
+ * PWA Configuration
+ *
+ * Centralized constants for PWA functionality.
+ *
+ * SECURITY NOTE:
+ * - VAPID_PRIVATE_KEY should NEVER be in frontend code
+ * - Use only in backend/API routes
+ * - Frontend only needs the public key
+ */
+
+// Default VAPID public key (safe to expose)
+export const DEFAULT_VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '';
+
+// NOTE: VAPID private key and mailto should only exist in:
+// - Backend environment variables
+// - API route handlers
+// - Service worker generation scripts
+// NEVER import or use private keys in frontend code
+```
+
+**Additional**: Add to `.env.example`:
+```bash
+# Frontend (PUBLIC - safe to expose)
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key_here
+
+# Backend only (PRIVATE - never expose)
+VAPID_PRIVATE_KEY=your_private_key_here
+VAPID_MAILTO=mailto:your-email@example.com
+```
+
+**Verification**:
+```bash
+# Ensure private key never bundled
+npm run build
+grep -r "VAPID_PRIVATE_KEY" .next/static # Should return nothing
+```
+
+---
+
+### 2. Fix Inconsistent Logging (P1-2)
+
+**Issue**: 3 files use `console.error` instead of `pwaLogger.error`
+
+**Files**:
+- `components/PushPrompt.tsx:106`
+- `components/A2HSHint.tsx:150`
+- `context/PushContext.tsx:114`
+
+#### Fix 2.1: PushPrompt.tsx
+
+**Current Code** (line 106):
+```typescript
+} catch (error) {
+  console.error('[PushPrompt] Enable failed:', error);
+} finally {
+  setEnabling(false);
+}
+```
+
+**✅ Fixed Code**:
+```typescript
+import { pwaLogger } from '../utils/logger';
+
+// ... in handleEnable function
+} catch (error) {
+  pwaLogger.error('[PushPrompt] Enable failed:', error);
+} finally {
+  setEnabling(false);
+}
+```
+
+#### Fix 2.2: A2HSHint.tsx
+
+**Current Code** (line 150):
+```typescript
+} catch (error) {
+  console.error('[A2HSHint] Install error:', error);
+} finally {
+  setInstalling(false);
+}
+```
+
+**✅ Fixed Code**:
+```typescript
+import { pwaLogger } from '../utils/logger';
+
+// ... in handleClick function
+} catch (error) {
+  pwaLogger.error('[A2HSHint] Install error:', error);
+} finally {
+  setInstalling(false);
+}
+```
+
+#### Fix 2.3: PushContext.tsx
+
+**Current Code** (line 114):
+```typescript
+} catch (error) {
+  console.error('Failed to send push:', error);
+  throw error;
+}
+```
+
+**✅ Fixed Code**:
+```typescript
+import { pwaLogger } from '../utils/logger';
+
+// ... in sendPush function
+} catch (error) {
+  pwaLogger.error('[PushContext] Failed to send push:', error);
+  throw error;
+}
+```
+
+**Verification**: Search for remaining console calls:
+```bash
+grep -r "console\." src/snippets/PWA --include="*.ts" --include="*.tsx" | grep -v "\.md" | grep -v "example"
+```
+
+Should only return JSDoc examples, no actual code.
+
+---
+
+### 3. Centralize LocalStorage Keys (P1-3)
+
+**Issue**: `DISMISSED_KEY` duplicated in A2HSHint and PushPrompt
+
+**Files**:
+- `components/A2HSHint.tsx:27`
+- `components/PushPrompt.tsx:18`
+
+**Current Code**:
+```typescript
+// A2HSHint.tsx
+const DISMISSED_KEY = 'cmdop-a2hs-dismissed';
+
+// PushPrompt.tsx
+const DISMISSED_KEY = 'pwa-push-dismissed';
+```
+
+#### Fix 3.1: Update utils/localStorage.ts
+
+**Add to existing STORAGE_KEYS** (after line 14):
+```typescript
+export const STORAGE_KEYS = {
+  IOS_GUIDE_DISMISSED: 'pwa_ios_guide_dismissed_at',
+  APP_INSTALLED: 'pwa_app_installed',
+  ENGAGEMENT: 'pwa_engagement_metrics',
+  // ✅ NEW: Add these keys
+  A2HS_DISMISSED: 'pwa_a2hs_dismissed_at',
+  PUSH_DISMISSED: 'pwa_push_dismissed_at',
+} as const;
+```
+
+**Add helper functions** (at end of file):
+```typescript
+/**
+ * Check if A2HS hint was dismissed recently
+ * @param resetDays Number of days before re-showing (default: 3)
+ */
+export function isA2HSDismissedRecently(resetDays: number = 3): boolean {
+  return isDismissedRecently(resetDays, STORAGE_KEYS.A2HS_DISMISSED);
+}
+
+/**
+ * Mark A2HS hint as dismissed
+ */
+export function markA2HSDismissed(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(STORAGE_KEYS.A2HS_DISMISSED, Date.now().toString());
+  } catch {
+    // Fail silently
+  }
+}
+
+/**
+ * Check if push prompt was dismissed recently
+ * @param resetDays Number of days before re-showing (default: 7)
+ */
+export function isPushDismissedRecently(resetDays: number = 7): boolean {
+  return isDismissedRecently(resetDays, STORAGE_KEYS.PUSH_DISMISSED);
+}
+
+/**
+ * Mark push prompt as dismissed
+ */
+export function markPushDismissed(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(STORAGE_KEYS.PUSH_DISMISSED, Date.now().toString());
+  } catch {
+    // Fail silently
+  }
+}
+
+/**
+ * Helper: Check if a key was dismissed recently
+ */
+function isDismissedRecently(resetDays: number, key: string): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    const dismissed = localStorage.getItem(key);
+    if (!dismissed) return false;
+    const dismissedAt = parseInt(dismissed, 10);
+    const daysSince = (Date.now() - dismissedAt) / (1000 * 60 * 60 * 24);
+    return daysSince < resetDays;
+  } catch {
+    return false;
+  }
+}
+```
+
+#### Fix 3.2: Update A2HSHint.tsx
+
+**Remove local constant** (delete line 27):
+```typescript
+// ❌ DELETE THIS
+const DISMISSED_KEY = 'cmdop-a2hs-dismissed';
+```
+
+**Add import**:
+```typescript
+import { markA2HSDismissed, isA2HSDismissedRecently } from '../utils/localStorage';
+```
+
+**Replace dismissal logic** (lines 100-116):
+```typescript
+// ✅ REPLACE with
+if (!forceShow && typeof window !== 'undefined') {
+  // If resetAfterDays is null, never reset
+  if (resetAfterDays === null) {
+    if (isA2HSDismissedRecently(Number.MAX_SAFE_INTEGER)) return;
+  } else if (isA2HSDismissedRecently(resetAfterDays)) {
+    return; // Still within reset period
+  }
+}
+```
+
+**Replace handleDismiss** (lines 123-130):
+```typescript
+const handleDismiss = () => {
+  setShow(false);
+  if (!forceShow) {
+    markA2HSDismissed();
+  }
+};
+```
+
+#### Fix 3.3: Update PushPrompt.tsx
+
+**Remove local constant** (delete line 18):
+```typescript
+// ❌ DELETE THIS
+const DISMISSED_KEY = 'pwa-push-dismissed';
+```
+
+**Add import**:
+```typescript
+import { markPushDismissed, isPushDismissedRecently } from '../utils/localStorage';
+```
+
+**Replace dismissal logic** (lines 79-90):
+```typescript
+// ✅ REPLACE with
+if (typeof window !== 'undefined') {
+  if (isPushDismissedRecently(resetAfterDays)) {
+    return; // Still within reset period
+  }
+}
+```
+
+**Replace handleDismiss** (lines 112-118):
+```typescript
+const handleDismiss = () => {
+  setShow(false);
+  markPushDismissed();
+  onDismissed?.();
+};
+```
+
+#### Fix 3.4: Export new functions in index.ts
+
+**Add to exports** (in index.ts):
+```typescript
+export {
+  // ... existing exports
+  markA2HSDismissed,
+  markPushDismissed,
+  isA2HSDismissedRecently,
+  isPushDismissedRecently,
+} from './utils/localStorage';
+```
+
+**Verification**:
+```bash
+# Ensure no hardcoded localStorage keys
+grep -r "localStorage\\..*Item\\(" src/snippets/PWA/components
+# Should not return any results
+```
+
+---
+
+## P2: Medium Priority Fixes
+
+### 4. Handle Unused EngagementMetrics (P2-1)
+
+**Issue**: 74 lines of engagement tracking code that's never used
+
+**Decision Required**: Remove or Use?
+
+#### Option A: Remove It (Recommended)
+
+**If**: No plan to use within 2 sprints
+
+**Step 1**: Remove from `utils/localStorage.ts` (lines 132-205):
+```typescript
+// ❌ DELETE these functions:
+// - getEngagementMetrics
+// - saveEngagementMetrics
+// - trackAction
+// - trackTimeSpent
+// - updateVisit
+```
+
+**Step 2**: Remove from `types/components.ts`:
+```typescript
+// ❌ DELETE this interface
+export interface EngagementMetrics {
+  actions: number;
+  timeSpent: number;
+  lastVisit: number | null;
+  visitCount: number;
+}
+```
+
+**Step 3**: Update `STORAGE_KEYS`:
+```typescript
+export const STORAGE_KEYS = {
+  IOS_GUIDE_DISMISSED: 'pwa_ios_guide_dismissed_at',
+  APP_INSTALLED: 'pwa_app_installed',
+  // ❌ DELETE this line
+  // ENGAGEMENT: 'pwa_engagement_metrics',
+} as const;
+```
+
+**Step 4**: Update `clearAllPWAData()` (line 210):
+```typescript
+export function clearAllPWAData(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.removeItem(STORAGE_KEYS.IOS_GUIDE_DISMISSED);
+    localStorage.removeItem(STORAGE_KEYS.APP_INSTALLED);
+    // ❌ DELETE this line
+    // localStorage.removeItem(STORAGE_KEYS.ENGAGEMENT);
+  } catch {
+    // Fail silently
+  }
+}
+```
+
+#### Option B: Actually Use It
+
+**If**: You want engagement-based install prompts
+
+**Step 1**: Create hook `hooks/useEngagement.ts`:
+```typescript
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { getEngagementMetrics, saveEngagementMetrics, type EngagementMetrics } from '../utils/localStorage';
+
+export function useEngagement() {
+  const [metrics, setMetrics] = useState<EngagementMetrics>(getEngagementMetrics);
+
+  const trackAction = useCallback(() => {
+    setMetrics(prev => {
+      const updated = { ...prev, actions: prev.actions + 1 };
+      saveEngagementMetrics(updated);
+      return updated;
+    });
+  }, []);
+
+  const trackTimeSpent = useCallback((ms: number) => {
+    setMetrics(prev => {
+      const updated = { ...prev, timeSpent: prev.timeSpent + ms };
+      saveEngagementMetrics(updated);
+      return updated;
+    });
+  }, []);
+
+  return { ...metrics, trackAction, trackTimeSpent };
+}
+```
+
+**Step 2**: Use in `A2HSHint.tsx`:
+```typescript
+import { useEngagement } from '../hooks/useEngagement';
+
+export function A2HSHint({ ... }: A2HSHintProps) {
+  const { actions, timeSpent } = useEngagement();
+
+  // Only show if user is engaged
+  const isEngaged = actions >= 5 && timeSpent >= 30000; // 30 seconds
+  const shouldShow = isEngaged && (forceShow || (!isInstalled && ...));
+
+  // ... rest of component
+}
+```
+
+**Recommendation**: Option A (remove) unless there's concrete plan to use
+
+---
+
+### 5. Simplify Context Composition (P2-2)
+
+**Issue**: `PwaProvider` conditionally wraps children with `PushProvider`
+
+**File**: `context/InstallContext.tsx:81-84`
+
+**Current Code**:
+```typescript
+// Wrap with PushProvider if configured
+if (config.pushNotifications) {
+  content = <PushProvider {...config.pushNotifications}>{content}</PushProvider>;
+}
+
+return content;
+```
+
+**Problem**: Magic wrapping, hard to understand
+
+**✅ Fixed Code**:
+
+**Step 1**: Create `ConditionalPushProvider` helper:
+```typescript
+// At top of InstallContext.tsx
+function ConditionalPushProvider({
+  enabled,
+  children,
+  ...config
+}: PushNotificationOptions & { enabled: boolean; children: React.ReactNode }) {
+  if (!enabled) return <>{children}</>;
+  return <PushProvider {...config}>{children}</PushProvider>;
+}
+```
+
+**Step 2**: Refactor `PwaProvider`:
+```typescript
+export function PwaProvider({ children, ...config }: PwaConfig & { children: React.ReactNode }) {
+  // If not enabled, acts as a simple pass-through
+  if (config.enabled === false) {
+    return <>{children}</>;
+  }
+
+  const prompt = useInstallPrompt();
+
+  const value: PwaContextValue = {
+    isIOS: prompt.isIOS,
+    isAndroid: prompt.isAndroid,
+    isSafari: prompt.isSafari,
+    isChrome: prompt.isChrome,
+    isInstalled: prompt.isInstalled,
+    canPrompt: prompt.canPrompt,
+    install: prompt.promptInstall,
+  };
+
+  const showHint = config.showInstallHint !== false;
+
+  // ✅ Explicit composition tree
+  return (
+    <PwaContext.Provider value={value}>
+      <ConditionalPushProvider
+        enabled={!!config.pushNotifications}
+        vapidPublicKey={config.pushNotifications?.vapidPublicKey || ''}
+        subscribeEndpoint={config.pushNotifications?.subscribeEndpoint}
+      >
+        {children}
+        {showHint && (
+          <A2HSHint
+            resetAfterDays={config.resetAfterDays}
+            delayMs={config.delayMs}
+            logo={config.logo}
+            pushNotifications={config.pushNotifications}
+          />
+        )}
+      </ConditionalPushProvider>
+    </PwaContext.Provider>
+  );
+}
+```
+
+**Benefits**:
+- ✅ Explicit composition (no magic)
+- ✅ Easy to understand
+- ✅ Easy to test in isolation
+- ✅ Same functionality
+
+---
+
+### 6. Add Server-Side Persistence (P2-3)
+
+**Issue**: Push subscriptions not persisted on server
+
+**Files**: Backend API routes + `hooks/usePushNotifications.ts`
+
+#### Step 1: Create Backend API Routes
+
+**Create `app/api/push/subscribe/route.ts`**:
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db'; // Your database client
+
+export async function POST(request: NextRequest) {
+  try {
+    const subscription: PushSubscription = await request.json();
+
+    // Validate subscription
+    if (!subscription.endpoint || !subscription.keys) {
+      return NextResponse.json(
+        { success: false, error: 'Invalid subscription' },
+        { status: 400 }
+      );
+    }
+
+    // Get user ID (from auth session)
+    const userId = await getUserIdFromSession(request);
+    if (!userId) {
+      return NextResponse.json(
+        { success: false, error: 'Unauthorized' },
+        { status: 401 }
+      );
+    }
+
+    // Save to database
+    const subscriptionId = await db.pushSubscriptions.upsert({
+      where: {
+        endpoint: subscription.endpoint,
+      },
+      update: {
+        keys: subscription.keys,
+        updatedAt: new Date(),
+      },
+      create: {
+        userId,
+        endpoint: subscription.endpoint,
+        keys: subscription.keys,
+        expirationTime: subscription.expirationTime,
+      },
+    });
+
+    return NextResponse.json({
+      success: true,
+      subscriptionId,
+    });
+  } catch (error) {
+    console.error('[API] Push subscription failed:', error);
+    return NextResponse.json(
+      { success: false, error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+**Create `app/api/push/unsubscribe/route.ts`**:
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+
+export async function DELETE(request: NextRequest) {
+  try {
+    const { endpoint } = await request.json();
+
+    const userId = await getUserIdFromSession(request);
+    if (!userId) {
+      return NextResponse.json(
+        { success: false, error: 'Unauthorized' },
+        { status: 401 }
+      );
+    }
+
+    await db.pushSubscriptions.delete({
+      where: {
+        endpoint,
+        userId, // Ensure user can only delete their own
+      },
+    });
+
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error('[API] Push unsubscription failed:', error);
+    return NextResponse.json(
+      { success: false, error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+**Database schema** (Prisma example):
+```prisma
+model PushSubscription {
+  id             String   @id @default(cuid())
+  userId         String
+  endpoint       String   @unique
+  keys           Json
+  expirationTime BigInt?
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+}
+```
+
+#### Step 2: Update Frontend Hook
+
+**Update `hooks/usePushNotifications.ts`** (lines 117-123):
+
+**Replace**:
+```typescript
+// Send subscription to server
+if (options.subscribeEndpoint) {
+  await fetch(options.subscribeEndpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(subscription),
+  });
+}
+```
+
+**With**:
+```typescript
+// Send subscription to server
+if (options.subscribeEndpoint) {
+  const response = await fetch(options.subscribeEndpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(subscription),
+    credentials: 'include', // Include cookies for auth
+  });
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new Error(
+      `Server failed to save subscription: ${errorData.error || response.statusText}`
+    );
+  }
+
+  const { success, subscriptionId } = await response.json();
+  if (!success) {
+    throw new Error('Server reported failure to save subscription');
+  }
+
+  pwaLogger.info('[usePushNotifications] Server saved subscription:', subscriptionId);
+}
+```
+
+**Update unsubscribe** (lines 149-168):
+
+**Replace**:
+```typescript
+const unsubscribe = async (): Promise<boolean> => {
+  if (!state.subscription) {
+    pwaLogger.warn('[usePushNotifications] No active subscription to unsubscribe');
+    return false;
+  }
+
+  try {
+    await state.subscription.unsubscribe();
+    setState((prev) => ({
+      ...prev,
+      isSubscribed: false,
+      subscription: null,
+    }));
+    pwaLogger.info('[usePushNotifications] Successfully unsubscribed from push notifications');
+    return true;
+  } catch (error) {
+    pwaLogger.error('[usePushNotifications] Unsubscribe failed:', error);
+    return false;
+  }
+};
+```
+
+**With**:
+```typescript
+const unsubscribe = async (): Promise<boolean> => {
+  if (!state.subscription) {
+    pwaLogger.warn('[usePushNotifications] No active subscription to unsubscribe');
+    return false;
+  }
+
+  try {
+    // Unsubscribe client-side
+    await state.subscription.unsubscribe();
+
+    // Notify server
+    if (options?.subscribeEndpoint) {
+      const unsubscribeEndpoint = options.subscribeEndpoint.replace('/subscribe', '/unsubscribe');
+      await fetch(unsubscribeEndpoint, {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ endpoint: state.subscription.endpoint }),
+        credentials: 'include',
+      }).catch((err) => {
+        pwaLogger.warn('[usePushNotifications] Failed to notify server:', err);
+        // Don't fail if server notification fails
+      });
+    }
+
+    setState((prev) => ({
+      ...prev,
+      isSubscribed: false,
+      subscription: null,
+    }));
+    pwaLogger.info('[usePushNotifications] Successfully unsubscribed from push notifications');
+    return true;
+  } catch (error) {
+    pwaLogger.error('[usePushNotifications] Unsubscribe failed:', error);
+    return false;
+  }
+};
+```
+
+---
+
+### 7. Improve Error Recovery (P2-4)
+
+**Issue**: No retry logic for push subscription failures
+
+**File**: `hooks/usePushNotifications.ts`
+
+**Step 1**: Add retry helper:
+```typescript
+/**
+ * Retry a function with exponential backoff
+ */
+async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries: number = 3,
+  baseDelayMs: number = 1000
+): Promise<T> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      const isLastAttempt = attempt === maxRetries - 1;
+      if (isLastAttempt) {
+        throw error;
+      }
+
+      // Exponential backoff: 1s, 2s, 4s, ...
+      const delayMs = baseDelayMs * Math.pow(2, attempt);
+      pwaLogger.debug(`[usePushNotifications] Retry attempt ${attempt + 1}/${maxRetries} after ${delayMs}ms`);
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+  }
+  throw new Error('Retry failed'); // Shouldn't reach here
+}
+```
+
+**Step 2**: Update subscribe function signature:
+```typescript
+// Add to PushNotificationOptions type
+export interface PushNotificationOptions {
+  vapidPublicKey: string;
+  subscribeEndpoint?: string;
+  // ✅ NEW options
+  onError?: (error: string) => void;
+  maxRetries?: number;
+}
+```
+
+**Step 3**: Refactor subscribe with retry:
+```typescript
+const subscribe = async (): Promise<boolean> => {
+  if (!state.isSupported) {
+    pwaLogger.warn('[usePushNotifications] Push notifications not supported');
+    options?.onError?.('Push notifications not supported in this browser');
+    return false;
+  }
+
+  if (!options?.vapidPublicKey) {
+    const error = 'VAPID public key is required for push notifications';
+    pwaLogger.error('[usePushNotifications]', error);
+    options?.onError?.(error);
+    return false;
+  }
+
+  try {
+    // Request permission
+    const permission = await Notification.requestPermission();
+    setState((prev) => ({ ...prev, permission }));
+
+    if (permission !== 'granted') {
+      const error = 'Notification permission denied';
+      pwaLogger.warn('[usePushNotifications]', error);
+      options?.onError?.(error);
+      return false;
+    }
+
+    // Get service worker
+    const registration = await navigator.serviceWorker.ready;
+
+    // Convert VAPID key
+    let applicationServerKey: Uint8Array;
+    try {
+      applicationServerKey = urlBase64ToUint8Array(options.vapidPublicKey);
+      pwaLogger.info('[usePushNotifications] VAPID key validated successfully');
+    } catch (e) {
+      const errorMsg = e instanceof VapidKeyError
+        ? `Invalid VAPID key: ${e.message}`
+        : 'Failed to convert VAPID key';
+      pwaLogger.error('[usePushNotifications]', errorMsg);
+      options?.onError?.(errorMsg);
+      return false;
+    }
+
+    // Unsubscribe from existing subscription
+    const existingSub = await registration.pushManager.getSubscription();
+    if (existingSub) {
+      await existingSub.unsubscribe();
+    }
+
+    // ✅ Subscribe with retry
+    const subscription = await retryWithBackoff(
+      async () => {
+        return await registration.pushManager.subscribe({
+          userVisibleOnly: true,
+          applicationServerKey: applicationServerKey as unknown as BufferSource,
+        });
+      },
+      options.maxRetries ?? 3
+    );
+
+    // ✅ Send to server with retry
+    if (options.subscribeEndpoint) {
+      await retryWithBackoff(
+        async () => {
+          const response = await fetch(options.subscribeEndpoint!, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(subscription),
+            credentials: 'include',
+          });
+
+          if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(errorData.error || response.statusText);
+          }
+
+          return response.json();
+        },
+        options.maxRetries ?? 3
+      );
+    }
+
+    setState((prev) => ({
+      ...prev,
+      isSubscribed: true,
+      subscription,
+    }));
+
+    pwaLogger.success('[usePushNotifications] Successfully subscribed to push notifications');
+    return true;
+
+  } catch (error: any) {
+    const userError = getUserFriendlyError(error);
+    pwaLogger.error('[usePushNotifications] Subscribe failed:', error);
+    options?.onError?.(userError);
+
+    // Specific diagnostics for common errors
+    if (error.name === 'AbortError' || error.message?.includes('push service error')) {
+      pwaLogger.error('[usePushNotifications] Push service blocked. Possible causes:');
+      pwaLogger.error('  1. Network: Firewall/VPN blocking ports 5228-5230');
+      pwaLogger.error('  2. Browser: Privacy settings or Do Not Disturb mode');
+      pwaLogger.error('  3. Browser: Shield/blocking settings (Brave, Firefox)');
+      pwaLogger.error('  4. Browser: Corrupt profile (try Incognito)');
+    }
+
+    return false;
+  }
+};
+
+/**
+ * Convert technical error to user-friendly message
+ */
+function getUserFriendlyError(error: any): string {
+  if (error.name === 'AbortError') {
+    return 'Push notifications blocked. Check your browser settings or try disabling VPN.';
+  }
+  if (error.message?.includes('push service error')) {
+    return 'Cannot connect to push service. Check your network connection.';
+  }
+  if (error.message?.includes('Server failed')) {
+    return 'Failed to save subscription. Please try again.';
+  }
+  return 'Failed to enable push notifications. Please try again later.';
+}
+```
+
+**Step 4**: Use error callback in components:
+```typescript
+// PushPrompt.tsx
+<PushPrompt
+  vapidPublicKey={vapidKey}
+  subscribeEndpoint="/api/push/subscribe"
+  maxRetries={2}
+  onError={(error) => {
+    toast.error('Push Notification Error', {
+      description: error,
+    });
+  }}
+/>
+```
+
+---
+
+## P3: Nice to Have
+
+### 8. Add Testing (P3-1)
+
+**Goal**: Add unit tests for utils, integration tests for hooks
+
+**Setup**: Use Vitest + Testing Library
+
+#### Install dependencies:
+```bash
+npm install -D vitest @testing-library/react @testing-library/react-hooks @testing-library/jest-dom
+```
+
+#### Example: Test `utils/platform.ts`
+
+**Create `utils/__tests__/platform.test.ts`**:
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { isStandalone, isMobileDevice, hasValidManifest, isStandaloneReliable } from '../platform';
+
+describe('platform utilities', () => {
+  describe('isStandalone', () => {
+    it('returns false when window is undefined', () => {
+      // Simulates SSR
+      expect(isStandalone()).toBe(false);
+    });
+
+    it('checks matchMedia for standalone display mode', () => {
+      // Mock matchMedia
+      Object.defineProperty(window, 'matchMedia', {
+        writable: true,
+        value: (query: string) => ({
+          matches: query === '(display-mode: standalone)',
+          media: query,
+          addEventListener: () => {},
+          removeEventListener: () => {},
+        }),
+      });
+
+      expect(isStandalone()).toBe(true);
+    });
+
+    it('falls back to navigator.standalone on iOS', () => {
+      // Mock iOS environment
+      Object.defineProperty(window, 'matchMedia', {
+        writable: true,
+        value: undefined,
+      });
+      Object.defineProperty(navigator, 'standalone', {
+        writable: true,
+        value: true,
+      });
+
+      expect(isStandalone()).toBe(true);
+    });
+  });
+
+  describe('isMobileDevice', () => {
+    it('detects iOS devices', () => {
+      Object.defineProperty(navigator, 'userAgent', {
+        writable: true,
+        value: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)',
+      });
+
+      expect(isMobileDevice()).toBe(true);
+    });
+
+    it('detects Android devices', () => {
+      Object.defineProperty(navigator, 'userAgent', {
+        writable: true,
+        value: 'Mozilla/5.0 (Linux; Android 10)',
+      });
+
+      expect(isMobileDevice()).toBe(true);
+    });
+
+    it('returns false for desktop', () => {
+      Object.defineProperty(navigator, 'userAgent', {
+        writable: true,
+        value: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)',
+      });
+
+      expect(isMobileDevice()).toBe(false);
+    });
+  });
+
+  describe('hasValidManifest', () => {
+    beforeEach(() => {
+      document.head.innerHTML = '';
+    });
+
+    it('returns true when manifest link exists', () => {
+      const link = document.createElement('link');
+      link.rel = 'manifest';
+      link.href = '/manifest.json';
+      document.head.appendChild(link);
+
+      expect(hasValidManifest()).toBe(true);
+    });
+
+    it('returns false when no manifest link', () => {
+      expect(hasValidManifest()).toBe(false);
+    });
+  });
+
+  describe('isStandaloneReliable', () => {
+    it('returns true for mobile PWA', () => {
+      // Mock mobile + standalone
+      Object.defineProperty(navigator, 'userAgent', {
+        writable: true,
+        value: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)',
+      });
+      Object.defineProperty(window, 'matchMedia', {
+        writable: true,
+        value: (query: string) => ({
+          matches: query === '(display-mode: standalone)',
+        }),
+      });
+
+      expect(isStandaloneReliable()).toBe(true);
+    });
+
+    it('requires manifest for desktop PWA', () => {
+      // Mock desktop + standalone but no manifest
+      Object.defineProperty(navigator, 'userAgent', {
+        writable: true,
+        value: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)',
+      });
+      Object.defineProperty(window, 'matchMedia', {
+        writable: true,
+        value: (query: string) => ({
+          matches: query === '(display-mode: standalone)',
+        }),
+      });
+
+      expect(isStandaloneReliable()).toBe(false);
+
+      // Add manifest
+      const link = document.createElement('link');
+      link.rel = 'manifest';
+      document.head.appendChild(link);
+
+      expect(isStandaloneReliable()).toBe(true);
+    });
+  });
+});
+```
+
+**Run tests**:
+```bash
+npm run test
+```
+
+---
+
+### 9. Improve Accessibility (P3-2)
+
+**Goal**: Add focus traps, keyboard navigation, ARIA attributes
+
+#### Example: Add focus trap to IOSGuideModal
+
+**Install dependency**:
+```bash
+npm install focus-trap-react
+```
+
+**Update `components/IOSGuideModal.tsx`**:
+```typescript
+import FocusTrap from 'focus-trap-react';
+
+export function IOSGuideModal({ onDismiss, open = true }: IOSGuideModalProps) {
+  // Handle Escape key
+  useEffect(() => {
+    if (!open) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        onDismiss();
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [open, onDismiss]);
+
+  return (
+    <Dialog open={open} onOpenChange={(isOpen) => !isOpen && onDismiss()}>
+      <DialogContent
+        className="sm:max-w-md"
+        role="alertdialog"
+        aria-labelledby="ios-guide-title"
+        aria-describedby="ios-guide-description"
+      >
+        <FocusTrap active={open}>
+          <div>
+            <DialogHeader className="text-left">
+              <DialogTitle id="ios-guide-title" className="flex items-center gap-2">
+                <Share className="w-5 h-5 text-primary" aria-hidden="true" />
+                Add to Home Screen
+              </DialogTitle>
+              <DialogDescription id="ios-guide-description" className="text-left">
+                Install this app on your iPhone for quick access and a better experience
+              </DialogDescription>
+            </DialogHeader>
+
+            <div className="space-y-3 py-4" role="list">
+              {steps.map((step) => (
+                <StepCard key={step.number} step={step} />
+              ))}
+            </div>
+
+            <DialogFooter>
+              <Button
+                onClick={onDismiss}
+                variant="default"
+                className="w-full"
+                aria-label="Close installation guide"
+              >
+                <Check className="w-4 h-4 mr-2" aria-hidden="true" />
+                Got It
+              </Button>
+            </DialogFooter>
+          </div>
+        </FocusTrap>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+**Add to StepCard**:
+```typescript
+function StepCard({ step }: { step: InstallStep }) {
+  return (
+    <Card className="border border-border" role="listitem">
+      <CardContent className="p-4">
+        <div className="flex items-start gap-3">
+          <div
+            className="flex items-center justify-center rounded-full bg-primary text-primary-foreground flex-shrink-0"
+            style={{ width: '32px', height: '32px' }}
+            aria-label={`Step ${step.number}`}
+          >
+            <span className="text-sm font-semibold" aria-hidden="true">
+              {step.number}
+            </span>
+          </div>
+
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2 mb-1">
+              <step.icon className="w-5 h-5 text-primary" aria-hidden="true" />
+              <h3 className="font-semibold text-foreground">{step.title}</h3>
+            </div>
+            <p className="text-sm text-muted-foreground">{step.description}</p>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+### 10. Enable TypeScript Strict Mode (P3-3)
+
+**Goal**: Enable strict type checking to catch more errors
+
+#### Step 1: Enable in tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true
+  }
+}
+```
+
+#### Step 2: Fix type errors
+
+**Example fixes**:
+
+```typescript
+// ❌ Before
+const handleMessage = (event) => {
+  if (event.data && event.data.type === 'PUSH_RECEIVED') {
+    // ...
+  }
+};
+
+// ✅ After
+const handleMessage = (event: MessageEvent<{
+  type: string;
+  notification?: Partial<PushMessage>
+}>) => {
+  if (event.data?.type === 'PUSH_RECEIVED') {
+    // ...
+  }
+};
+```
+
+```typescript
+// ❌ Before
+const subscription: any = await registration.pushManager.subscribe(options);
+
+// ✅ After
+const subscription: PushSubscription = await registration.pushManager.subscribe(options);
+```
+
+#### Step 3: Add strict null checks
+
+```typescript
+// ❌ Before
+const cleanup = onDisplayModeChange((isStandalone) => {
+  setState(prev => ({ ...prev, isInstalled: isStandalone }));
+});
+
+// ✅ After (explicit null check)
+const cleanup = onDisplayModeChange((isStandalone) => {
+  setState((prev) => ({ ...prev, isInstalled: isStandalone }));
+});
+
+return cleanup; // TypeScript ensures cleanup is always returned
+```
+
+---
+
+## Summary
+
+**P1 Fixes** (30 min):
+- ✅ Remove VAPID_PRIVATE_KEY from config.ts
+- ✅ Replace 3 console.error with pwaLogger
+- ✅ Centralize localStorage keys
+
+**P2 Fixes** (4 hours):
+- ✅ Remove or use EngagementMetrics
+- ✅ Simplify context composition
+- ✅ Add server-side persistence
+- ✅ Improve error recovery with retry
+
+**P3 Enhancements** (Ongoing):
+- ✅ Add testing (utils → hooks → components)
+- ✅ Improve accessibility (focus traps, ARIA)
+- ✅ Enable TypeScript strict mode
+
+**Next Steps**: Start with P1, deploy, then tackle P2 incrementally.