# TimeSafari Web-Push Cleanup Guide

**Status:** 🚀 Native-First Implementation  
**Date:** 2025-01-27T14:30Z (UTC)  
**Author:** Matthew Raymer  
**Scope:** Web-push code cleanup and deprecation  
**Goal:** Remove or quarantine all web-push code paths and mark as deprecated.

---

## Executive Summary

This document provides a comprehensive cleanup guide for removing web-push code
paths from TimeSafari. Web-push has been retired for unreliability, and the
system now focuses on native mobile reliability with Electron best-effort support.

---

## Cleanup Strategy

### Phase 1: Identify Web-Push Code Paths

#### Service Worker Files

- [ ] `sw_scripts/notification-click.js` - Mark as deprecated
- [ ] `sw_scripts/` directory - Review for web-push dependencies
- [ ] Service worker registration code - Remove or quarantine

#### Web-Specific Code

- [ ] Web push notification handlers
- [ ] Service worker event listeners
- [ ] Web notification API usage
- [ ] Push subscription management

#### Configuration Files

- [ ] VitePWA plugin configuration
- [ ] Service worker build configuration
- [ ] Web push manifest files

### Phase 2: Mark as Deprecated

#### Code Comments

```javascript
// DEPRECATED: Web-push notification handling
// This code is kept for reference but not used in production
// Replaced by Native-First notification system
```

#### Documentation Updates

- [ ] Mark web-push sections as deprecated
- [ ] Add deprecation notices
- [ ] Update README files
- [ ] Update API documentation

### Phase 3: Remove or Quarantine

#### Complete Removal

- [ ] Web push subscription code
- [ ] Service worker notification handlers
- [ ] Web-specific notification APIs
- [ ] Push message handling

#### Quarantine (Keep for Reference)

- [ ] Service worker registration code
- [ ] Web push configuration
- [ ] Historical web-push tests

---

## Detailed Cleanup Tasks

### 1. Service Worker Cleanup

#### Files to Deprecate

**`sw_scripts/notification-click.js`**

```javascript
// DEPRECATED: Service worker notification handling
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

// Original web-push notification click handler
self.addEventListener('notificationclick', (event) => {
  // DEPRECATED: Web-push only
  event.notification.close();

  const slotId = event.notification.data?.slotId;
  const route = slotId ? '/#/daily' : '/#/notifications';

  event.waitUntil(
    clients.openWindow(route).catch(() => {
      return clients.openWindow('/');
    })
  );
});
```

**Service Worker Registration**

```javascript
// DEPRECATED: Service worker registration
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

if ('serviceWorker' in navigator && process.env.VITE_PLATFORM === 'web') {
  // DEPRECATED: Web-push only
  navigator.serviceWorker.register('/sw.js')
    .then(registration => {
      console.log('Service Worker registered:', registration);
    })
    .catch(error => {
      console.error('Service Worker registration failed:', error);
    });
}
```

### 2. Web Push API Cleanup

#### Push Subscription Management

```javascript
// DEPRECATED: Web push subscription management
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

class WebPushManager {
  // DEPRECATED: Web-push only
  async subscribeToPush() {
    // Implementation kept for reference
  }

  // DEPRECATED: Web-push only
  async unsubscribeFromPush() {
    // Implementation kept for reference
  }
}
```

#### Push Message Handling

```javascript
// DEPRECATED: Push message handling
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

self.addEventListener('push', (event) => {
  // DEPRECATED: Web-push only
  const data = event.data ? event.data.json() : {};

  const options = {
    body: data.body,
    icon: '/icon-192x192.png',
    badge: '/badge-72x72.png',
    data: data
  };

  event.waitUntil(
    self.registration.showNotification(data.title, options)
  );
});
```

### 3. Configuration Cleanup

#### VitePWA Plugin Configuration

```javascript
// DEPRECATED: VitePWA plugin configuration
// This configuration is kept for reference but not used in production
// Replaced by Native-First notification system

import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    VitePWA({
      // DEPRECATED: Web-push only
      registerType: 'autoUpdate',
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg}']
      },
      includeAssets: ['favicon.ico', 'apple-touch-icon.png', 'masked-icon.svg'],
      manifest: {
        name: 'TimeSafari',
        short_name: 'TimeSafari',
        description: 'TimeSafari App',
        theme_color: '#ffffff',
        icons: [
          {
            src: 'pwa-192x192.png',
            sizes: '192x192',
            type: 'image/png'
          }
        ]
      }
    })
  ]
})
```

#### Service Worker Build Configuration

```javascript
// DEPRECATED: Service worker build configuration
// This configuration is kept for reference but not used in production
// Replaced by Native-First notification system

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        // DEPRECATED: Web-push only
        sw: 'sw_scripts/notification-click.js'
      }
    }
  }
})
```

### 4. Test Cleanup

#### Web Push Tests

```javascript
// DEPRECATED: Web push tests
// These tests are kept for reference but not used in production
// Replaced by Native-First notification system

describe('Web Push Notifications (DEPRECATED)', () => {
  // DEPRECATED: Web-push only
  it('should handle push notifications', async () => {
    // Test implementation kept for reference
  });

  // DEPRECATED: Web-push only
  it('should handle notification clicks', async () => {
    // Test implementation kept for reference
  });
});
```

#### Service Worker Tests

```javascript
// DEPRECATED: Service worker tests
// These tests are kept for reference but not used in production
// Replaced by Native-First notification system

describe('Service Worker (DEPRECATED)', () => {
  // DEPRECATED: Web-push only
  it('should register service worker', async () => {
    // Test implementation kept for reference
  });

  // DEPRECATED: Web-push only
  it('should handle push events', async () => {
    // Test implementation kept for reference
  });
});
```

### 5. Documentation Cleanup

#### README Updates

```markdown
# TimeSafari Native-First Notification System

## Web-Push Status: DEPRECATED

Web-push has been retired for unreliability. The system now focuses on native mobile reliability with Electron best-effort support.

### Deprecated Features
- ❌ Web push notifications
- ❌ Service worker notification handling
- ❌ Web notification API

### Active Features
- ✅ Native mobile notifications (Android/iOS)
- ✅ Electron notifications (best-effort)
- ✅ OS-scheduled background prefetch
- ✅ Rolling window safety
```

#### API Documentation Updates

```markdown
## Notification API (Native-First)

### Deprecated Methods
- `subscribeToPush()` - DEPRECATED: Web-push only
- `unsubscribeFromPush()` - DEPRECATED: Web-push only
- `handlePushMessage()` - DEPRECATED: Web-push only

### Active Methods
- `scheduleExact()` - Native exact scheduling
- `scheduleWindow()` - Native windowed scheduling
- `schedulePrefetch()` - Native background prefetch
```

---

## File-by-File Cleanup Checklist

### Service Worker Files

- [ ] `sw_scripts/notification-click.js` - Mark as deprecated
- [ ] `sw_scripts/` directory - Review for web-push dependencies
- [ ] Service worker build configuration - Remove or quarantine

### Web-Specific Code

- [ ] `src/main.web.ts` - Remove service worker registration
- [ ] `src/services/webPush.ts` - Mark as deprecated
- [ ] `src/utils/serviceWorker.ts` - Mark as deprecated
- [ ] Web notification API usage - Remove or quarantine

### Configuration Files

- [ ] `vite.config.web.mts` - Remove VitePWA plugin
- [ ] `package.json` - Remove web-push dependencies
- [ ] `public/manifest.json` - Mark as deprecated
- [ ] Service worker build scripts - Remove or quarantine

### Test Files

- [ ] `test-playwright/web-push.spec.ts` - Mark as deprecated
- [ ] `test/services/webPush.test.ts` - Mark as deprecated
- [ ] Service worker tests - Mark as deprecated

### Documentation Files

- [ ] `README.md` - Update to reflect native-first approach
- [ ] `doc/web-push.md` - Mark as deprecated
- [ ] API documentation - Remove web-push references

---

## Dependencies to Remove

### NPM Packages

```json
{
  "dependencies": {
    // DEPRECATED: Web-push only
    "web-push": "^7.4.0",
    "vite-plugin-pwa": "^0.17.0"
  },
  "devDependencies": {
    // DEPRECATED: Web-push only
    "workbox-webpack-plugin": "^6.5.0"
  }
}
```

### Build Scripts

```json
{
  "scripts": {
    // DEPRECATED: Web-push only
    "build:sw": "workbox generateSW",
    "test:sw": "jest --testPathPattern=serviceWorker"
  }
}
```

---

## Migration Guide

### From Web-Push to Native-First

#### Step 1: Remove Web-Push Dependencies

```bash
# Remove web-push packages
npm uninstall web-push vite-plugin-pwa workbox-webpack-plugin

# Remove service worker files
rm -rf sw_scripts/
rm -f public/sw.js
rm -f public/workbox-*.js
```

#### Step 2: Update Configuration

```javascript
// Remove VitePWA plugin from vite.config.web.mts
export default defineConfig({
  plugins: [
    // Remove VitePWA plugin
    // VitePWA({ ... })
  ]
})
```

#### Step 3: Update Service Registration

```javascript
// Remove service worker registration from main.web.ts
// if ('serviceWorker' in navigator) {
//   navigator.serviceWorker.register('/sw.js')
// }
```

#### Step 4: Update Tests

```javascript
// Remove web-push tests
// describe('Web Push Notifications', () => { ... })
```

---

## Verification Checklist

### Code Removal Verification

- [ ] No web-push imports remain
- [ ] No service worker registration code
- [ ] No push subscription management
- [ ] No web notification API usage
- [ ] No VitePWA plugin configuration

### Documentation Verification

- [ ] All web-push references marked as deprecated
- [ ] README updated to reflect native-first approach
- [ ] API documentation updated
- [ ] Test documentation updated

### Build Verification

- [ ] Web build succeeds without service worker
- [ ] No service worker files generated
- [ ] No web-push dependencies in bundle
- [ ] Native builds work correctly

### Test Verification

- [ ] Web-push tests are marked as deprecated
- [ ] Native notification tests pass
- [ ] No web-push test failures
- [ ] Test suite runs successfully

---

## Rollback Plan

### Emergency Rollback

If native-first implementation fails, web-push code can be restored:

#### 1. **Restore Dependencies**

```bash
npm install web-push vite-plugin-pwa workbox-webpack-plugin
```

#### 2. **Restore Service Worker Files**

```bash
git checkout HEAD~1 -- sw_scripts/
git checkout HEAD~1 -- public/sw.js
```

#### 3. **Restore Configuration**

```bash
git checkout HEAD~1 -- vite.config.web.mts
git checkout HEAD~1 -- package.json
```

#### 4. **Restore Tests**

```bash
git checkout HEAD~1 -- test-playwright/web-push.spec.ts
git checkout HEAD~1 -- test/services/webPush.test.ts
```

### Rollback Verification

- [ ] Web-push functionality restored
- [ ] Service worker registration works
- [ ] Push notifications work
- [ ] Tests pass

---

## Post-Cleanup Tasks

### Code Review

- [ ] Review all changes for completeness
- [ ] Verify no web-push code remains
- [ ] Check for orphaned references
- [ ] Validate native-first implementation

### Testing

- [ ] Run full test suite
- [ ] Verify native notifications work
- [ ] Check Electron functionality
- [ ] Validate mobile builds

### Documentation

- [ ] Update all documentation
- [ ] Remove web-push references
- [ ] Update API documentation
- [ ] Update user guides

---

## Success Criteria

### Complete Web-Push Removal

- [ ] All web-push code marked as deprecated
- [ ] Service worker files quarantined
- [ ] Dependencies removed
- [ ] Configuration updated

### Native-First Implementation

- [ ] Native notifications work on Android
- [ ] Native notifications work on iOS
- [ ] Electron notifications work
- [ ] Background prefetch works

### Documentation Updated

- [ ] All docs reflect native-first approach
- [ ] Web-push marked as deprecated
- [ ] Migration guide provided
- [ ] Rollback plan documented

---

_This cleanup guide provides comprehensive instructions for removing web-push
code paths from TimeSafari. Web-push has been retired for unreliability, and the
system now focuses on native mobile reliability with Electron best-effort support._