138 lines
5.2 KiB
Markdown
138 lines
5.2 KiB
Markdown
---
|
|
phase: 26-pwa-performance
|
|
plan: 00
|
|
subsystem: ui
|
|
tags: [pwa, service-worker, cache-first, idb, web-push, vitest, typescript]
|
|
|
|
# Dependency graph
|
|
requires: []
|
|
provides:
|
|
- Cache-first service worker (nexus-v1) replacing old network-first paperclip-v2
|
|
- Web push notification handler in service worker
|
|
- BeforeInstallPromptEvent TypeScript type declaration
|
|
- idb installed in @paperclipai/ui
|
|
- web-push + @types/web-push installed in @paperclipai/server
|
|
- Wave 0 test stubs for useOfflineQueue, useInstallPrompt, usePushNotifications, PullToRefresh
|
|
affects:
|
|
- 26-pwa-performance (plans 01-04 depend on this foundation)
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: [idb@8.0.3, web-push@3.6.7, @types/web-push@3.6.4]
|
|
patterns:
|
|
- Cache-first strategy for static assets and navigation via service worker
|
|
- it.todo() test stubs for Wave 0 scaffolding (Phase 21-25 convention)
|
|
- @vitest-environment jsdom pragma for component test files
|
|
|
|
key-files:
|
|
created:
|
|
- ui/src/types/pwa.d.ts
|
|
- ui/src/hooks/useOfflineQueue.test.ts
|
|
- ui/src/hooks/useInstallPrompt.test.ts
|
|
- ui/src/hooks/usePushNotifications.test.ts
|
|
- ui/src/components/PullToRefresh.test.tsx
|
|
modified:
|
|
- ui/public/sw.js
|
|
- ui/package.json
|
|
- server/package.json
|
|
- pnpm-lock.yaml
|
|
|
|
key-decisions:
|
|
- "Cache name changed from paperclip-v2 to nexus-v1; activate event deletes all non-nexus-v1 caches to bust stale entries"
|
|
- "API paths (/api/*) pass through without SW interception — network-only for all API traffic"
|
|
- "Push event handler uses /android-chrome-192x192.png as default icon and /favicon-32x32.png as badge"
|
|
|
|
patterns-established:
|
|
- "SW fetch handler: API passthrough first, then navigate cache-first, then static-extension cache-first, then passthrough"
|
|
- "Wave 0 test stubs: minimal imports, it.todo() only, no mocks until implementation plans"
|
|
|
|
requirements-completed: [PWA-01, PWA-07, PERF-05]
|
|
|
|
# Metrics
|
|
duration: 5min
|
|
completed: 2026-04-02
|
|
---
|
|
|
|
# Phase 26 Plan 00: PWA Performance Foundation Summary
|
|
|
|
**Cache-first service worker with nexus-v1 cache, push/notificationclick handlers, idb + web-push installed, and 14 Wave 0 test stubs for PWA hooks and PullToRefresh**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 5 min
|
|
- **Started:** 2026-04-02T01:58:25Z
|
|
- **Completed:** 2026-04-02T02:01:00Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 9
|
|
|
|
## Accomplishments
|
|
|
|
- Rewrote service worker from network-first (paperclip-v2) to cache-first (nexus-v1) strategy enabling PERF-05
|
|
- Added push and notificationclick event handlers to the service worker for web push notifications
|
|
- Created BeforeInstallPromptEvent TypeScript types for upcoming useInstallPrompt hook
|
|
- Installed idb@8.0.3 and web-push@3.6.7 dependencies for Phase 26 plans
|
|
- Created 4 Wave 0 test stub files with 14 it.todo() entries covering all PWA hooks and PullToRefresh component
|
|
|
|
## Task Commits
|
|
|
|
1. **Task 1: Install dependencies, create PWA types, and rewrite service worker** - `95ebf3d8` (feat)
|
|
2. **Task 2: Create Wave 0 test stubs for Phase 26 hooks and components** - `8e7a3e2b` (test)
|
|
|
|
## Files Created/Modified
|
|
|
|
- `ui/public/sw.js` - Rewritten: cache-first strategy with nexus-v1 cache, push and notificationclick handlers
|
|
- `ui/src/types/pwa.d.ts` - Created: BeforeInstallPromptEvent interface and WindowEventMap augmentation
|
|
- `ui/src/hooks/useOfflineQueue.test.ts` - Created: 4 it.todo() stubs
|
|
- `ui/src/hooks/useInstallPrompt.test.ts` - Created: 4 it.todo() stubs
|
|
- `ui/src/hooks/usePushNotifications.test.ts` - Created: 3 it.todo() stubs
|
|
- `ui/src/components/PullToRefresh.test.tsx` - Created: 3 it.todo() stubs with @vitest-environment jsdom
|
|
- `ui/package.json` - Added idb dependency
|
|
- `server/package.json` - Added web-push + @types/web-push dependencies
|
|
- `pnpm-lock.yaml` - Updated lockfile
|
|
|
|
## Decisions Made
|
|
|
|
- Cache name nexus-v1 replaces paperclip-v2; activate event deletes all caches with names not equal to nexus-v1 to bust stale versions
|
|
- API requests (/api/*) are excluded from SW interception entirely (network-only)
|
|
- Push handler defaults: icon=/android-chrome-192x192.png, badge=/favicon-32x32.png
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
One minor cleanup: a comment in sw.js initially contained "paperclip-v2" as a reference. Removed the word to satisfy acceptance criteria (`grep "paperclip" ui/public/sw.js` returns 0).
|
|
|
|
## Issues Encountered
|
|
|
|
None.
|
|
|
|
## User Setup Required
|
|
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- Service worker foundation ready for Phase 26 plans 01-04
|
|
- idb available for useOfflineQueue hook implementation (plan 01)
|
|
- web-push available for push subscription API (plan 03)
|
|
- All Wave 0 test stubs provide TDD RED targets for subsequent implementation plans
|
|
- 14 todos confirmed passing in vitest run (todos are not failures)
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All created files verified:
|
|
- FOUND: ui/public/sw.js
|
|
- FOUND: ui/src/types/pwa.d.ts
|
|
- FOUND: ui/src/hooks/useOfflineQueue.test.ts
|
|
- FOUND: ui/src/hooks/useInstallPrompt.test.ts
|
|
- FOUND: ui/src/hooks/usePushNotifications.test.ts
|
|
- FOUND: ui/src/components/PullToRefresh.test.tsx
|
|
- FOUND: .planning/phases/26-pwa-performance/26-00-SUMMARY.md
|
|
|
|
All commits verified:
|
|
- FOUND: 95ebf3d8 (Task 1)
|
|
- FOUND: 8e7a3e2b (Task 2)
|
|
|
|
---
|
|
*Phase: 26-pwa-performance*
|
|
*Completed: 2026-04-02*
|