clawtap/docs/superpowers/specs/2026-03-26-pwa-optimization-design.md

PWA Optimization Design Spec

Date: 2026-03-26 Goal: Bring CodeTap's PWA to production-grade quality — proper viewport handling, splash screens, install prompts, SW updates, badge management, draft persistence, and navigation history.

---

Current State

CodeTap already has solid PWA foundations:

• Service Worker with Workbox precaching (vite-plugin-pwa, injectManifest)
• Web App Manifest (standalone, portrait, dark theme)
• Push notifications with badge support
• iOS meta tags (capable, black-translucent status bar)
• Offline detection + OfflineView
• overscroll-behavior: none, 16px inputs, h-dvh, safe-bottom

What's Missing

High Priority

1. Viewport & Safe Areas

Problem: Missing viewport-fit=cover. Only bottom safe area handled — notch/Dynamic Island area not accounted for.

Solution:

• Add viewport-fit=cover to viewport meta tag in index.html
• Add CSS for top safe area: headers get padding-top: env(safe-area-inset-top)
• The standalone PWA mode on iOS with black-translucent status bar needs the content to extend behind the status bar — viewport-fit=cover enables this

Files: index.html, src/index.css

2. Splash Screen / Launch Images

Problem: White flash on app startup — no branded loading experience.

Solution:

• Add apple-mobile-web-app-startup-image meta tags covering major iPhone sizes
• Use media attribute with device-width, device-height, and device-pixel-ratio queries
• Background: #09090b (matches theme), centered CodeTap mascot/logo
• Generate splash images as data URIs or static PNGs in /public/splash/
• Minimum coverage: iPhone SE, iPhone 14/15, iPhone 14/15 Pro Max, iPhone 16 Pro Max

Files: index.html, public/splash/ (new directory)

3. Android Install Prompt

Problem: No handling of beforeinstallprompt event — Android users never see install prompt.

Solution:

• Listen for beforeinstallprompt in App.tsx, store the event in state
• Show a dismissible install banner in SessionsView (below header)
• Banner text: "Install CodeTap for a better experience" with Install/Dismiss buttons
• On Install click: call event.prompt(), hide banner
• On Dismiss: hide banner, store dismissal in localStorage so it doesn't reappear
• After successful install (appinstalled event): hide banner permanently

Files: src/App.tsx, src/components/SessionsView.tsx

4. Service Worker Update Notification

Problem: SW updates silently — user doesn't know a new version is available.

Solution:

• Listen for controllerchange on navigator.serviceWorker in App.tsx
• When detected, show a toast at bottom: "New version available" with Refresh button
• On click: window.location.reload()
• Toast auto-dismisses after 10s but can be manually dismissed

Files: src/App.tsx

Medium Priority

5. Badge Clear on Focus

Problem: App badge persists even when user is actively looking at the app.

Solution:

• In App.tsx, listen for visibilitychange event
• When document.visibilityState === 'visible': call navigator.clearAppBadge() (with feature check)
• This ensures badge is cleared whenever user switches back to the app

Files: src/App.tsx

6. Manifest Shortcuts

Problem: No quick actions from home screen long-press.

Solution:

• Add shortcuts array to manifest in vite.config.ts:
  • "New Chat" — url: /?action=newchat, icon: chat-bubble-icon
• In App.tsx, check for ?action=newchat param and navigate accordingly

Files: vite.config.ts, src/App.tsx

7. Input Draft Auto-Save

Problem: Typed text lost if app is backgrounded or crashes.

Solution:

• In ShimmerInput: on every input change, debounce-save to localStorage with key codetap:draft:{sessionId}
• On mount: restore draft from localStorage if present
• On successful send or explicit clear: delete the draft
• Debounce: 500ms to avoid excessive writes

Files: src/components/ShimmerInput.tsx

8. Manifest Screenshots

Problem: Missing screenshots for app stores and install prompts.

Solution:

• Add screenshots array to manifest in vite.config.ts
• Provide at minimum:
  • 1 narrow screenshot (phone, 1080x1920) — chat view
  • 1 wide screenshot (tablet/desktop, 1920x1080) — sessions view
• Store in public/screenshots/

Files: vite.config.ts, public/screenshots/ (new directory)

Low Priority

9. Slow Network Detection

Problem: No feedback when on slow connection.

Solution:

• Check navigator.connection?.effectiveType (with feature detection)
• When 2g or slow-2g: show a subtle indicator in StatusBar ("Slow connection")
• Re-check on change event of navigator.connection

Files: src/components/StatusBar.tsx

10. History API Navigation

Problem: Browser back gesture doesn't work — app uses sessionStorage for view state, no history stack.

Solution:

• In App.tsx, use history.pushState() when navigating between views
• Listen for popstate event to handle back navigation
• Map each view to a history entry: sessions, chat/{sessionId}, settings, newchat/{cwd}
• This enables iOS swipe-back gesture and Android back button in standalone mode

Files: src/App.tsx

11. OpenGraph Meta Tags

Problem: No social sharing metadata.

Solution:

• Add to index.html:
  • og:title: "CodeTap"
  • og:description: "Use Claude Code from your phone"
  • og:image: link to a social card image
  • og:type: "website"
  • twitter:card: "summary"

Files: index.html

---

Design Principles

1. Progressive enhancement — All PWA features use feature detection. App works fine without them.
2. No new dependencies — Everything is native Web APIs or existing vite-plugin-pwa config.
3. Minimal UI additions — Install banner and SW update toast are the only new UI elements.
4. Respect user choice — Install prompt is dismissible and remembers dismissal.

Out of Scope

• Full offline-first with background sync (current offline detection is sufficient)
• Push notification permission prompt UI (current flow works)
• Image compression before upload
• Orientation lock via Screen Orientation API