feat(pwa): add offline support with vite-plugin-pwa

[francisfuzz]

Summary

Adds PWA offline support using vite-plugin-pwa. After the first visit, all pages and documentation are cached locally for offline access.

Motivation

When I travel, I like reading things while I'm in line. Sometimes, where I am does not have the best connection, but I'd still like to read the contents. This PR solves that issue 😉

Approach

• TDD workflow: Wrote E2E tests first (9 PWA-specific tests), verified they pass
• vite-plugin-pwa: Automatic service worker generation with Workbox
• Precaching strategy: All static assets (.js, .css, .html, .ico, .png, .svg, .woff2, .md, .txt)
• MPA configuration: No SPA fallback—each route (/, /skills/, /agents/, /mcp/) has its own HTML
• Updated manifest: Proper branding, theme colors (#1a1a2e dark, #f5f3ef light), and app metadata

What's Included

Service Worker

• Generated automatically during bun run build
• Located at dist/sw.js with Workbox runtime
• Precaches 24+ assets (~450KB total)
• Auto-updates service worker on new deployments

Web Manifest

• Updated with proper name, description, and app metadata
• Theme colors match site's light/dark mode support
• Icons for home screen installation (96x96, 192x192, 512x512)
• Standalone display mode for full-screen app experience

Tests

• 9 PWA-specific E2E tests verify:
  • Web manifest validity and metadata
  • Service worker file generation
  • Workbox runtime generation
  • All routes accessible and properly cached
  • Static resources available offline
• All 80 E2E tests passing

Documentation

• AGENTS.md: Detailed PWA setup, offline strategy, and maintenance guide
• README.md: Highlights offline capability for users

Trade-offs

Decision	Rationale
Precache all assets	Ensures full offline functionality; increases initial cache size (~450KB)
Auto-update strategy	Better UX than manual update prompts; users get new content automatically
No runtime caching	Site is fully static with no API calls; caching strategy focuses on precache only
MPA approach	Each route has its own HTML entry point; no SPA fallback needed

How to Test

Automated Tests

cd site
bun run build      # Verify dist/sw.js is generated
bun run test       # All 80 E2E tests (including 9 PWA tests) should pass

Manual Testing

cd site
bun run build
bun run preview    # Preview at http://localhost:4173

In browser DevTools:

1. Application > Service Workers — Verify SW is registered and active
2. Check "Offline" mode in DevTools
3. Navigate to all routes — Should work offline from cache
4. Reload pages — All content should load from cache

Verification Checklist

• ✅ All E2E tests pass (80/80, including 9 PWA tests)
• ✅ TypeScript type checking passes
• ✅ ESLint linting passes (0 warnings)
• ✅ Production build succeeds with service worker generation
• ✅ Service worker file (dist/sw.js) generated with Workbox precache manifest
• ✅ Web manifest (dist/site.webmanifest) valid and in dist
• ✅ AGENTS.md updated with PWA documentation
• ✅ README.md highlights offline capability
• ✅ Manual smoke test: SW registers, pages load offline

Commits

1. test(pwa): Add E2E tests for service worker and offline support
2. chore(deps): Add vite-plugin-pwa dependency
3. feat(pwa): Configure vite-plugin-pwa for MPA with precaching
4. feat(pwa): Update web manifest with proper metadata and theme colors
5. test(pwa): Verify all E2E tests pass with service worker
6. docs: Add PWA documentation to AGENTS.md and README.md
7. chore(pwa): Add manifest to public directory for distribution
8. chore(lock): Update dependencies after installation

🤖 Generated with Claude Code