iOS PWA Optimization Plan for DeepStack
Overview
Transform DeepStack into a native-like iOS experience with PWA capabilities, offline support, and gesture navigation.
Current State: Solid iOS foundations (safe areas, touch targets, momentum scrolling) Goal: Full PWA with home screen install, offline support, and native-feel interactions
Phase 0: Critical UX Fixes (FIRST PRIORITY)
These scroll and layout issues must be fixed before PWA work.
0.1 Fix Chat Scroll Container
File: web/src/components/chat/ConversationView.tsx
Problem: Page scrolls instead of chat messages - can't scroll dialogue because outer container scrolls.
Fix:
- Ensure chat message area is in a proper scroll container with
overflow-hiddenon parent - Chat input must be
position: stickyorfixedat bottom - Messages container gets
flex-1 overflow-y-autowith propermin-h-0 - Add
overscroll-behavior: containto prevent scroll chaining to parent
0.2 Add Collapse Button to Watchlist/Chart Widget
File: web/src/components/widgets/WidgetPanel.tsx (or individual widget components)
Problem: Chart/watchlist widget pops up but has no way to collapse/dismiss.
Fix:
- Add collapse/expand toggle to widget header
- Store collapsed state in
ui-store.tsper widget - When collapsed, show only header bar (like chart panel's 40px collapsed state)
0.3 Smart Chart Panel Persistence Logic
File: web/src/components/chat/ConversationView.tsx + web/src/lib/stores/ui-store.ts
Problem: Chart shows/hides inconsistently. Need clear rules.
Fix - Chart Visibility Rules:
| State | Chart Behavior |
|---|---|
Home (no messages, activeContent: 'none') |
Show chart panel |
Chatting (messages exist, activeContent: 'none') |
Keep showing chart |
Tool active (activeContent !== 'none') |
Hide chart (tool takes space) |
Return to home/chat (activeContent → 'none') |
Restore chart |
Implementation:
- Track
previousChartStatebefore tool opens - Auto-restore when tool closes
- User can still manually collapse via toggle button
0.4 Global Scroll Audit
Files: Multiple layout components
Problem: "Couldn't see anything" - scroll areas not working properly.
Fix:
- Audit all
ScrollAreaandoverflow-*classes - Ensure each scrollable region has:
- Parent with
overflow-hiddenand fixed/constrained height - Child with
overflow-y-autoandmin-h-0(for flex) -webkit-overflow-scrolling: touchfor iOS momentumoverscroll-behavior: containto prevent bleed
- Parent with
- Test: Portfolio, News, Calendar, Options panels
Phase 1: PWA Foundation (Critical)
1.1 Create Web App Manifest
File: web/public/manifest.json
{
"name": "DeepStack - AI Trading Assistant",
"short_name": "DeepStack",
"description": "AI-powered trading assistant with emotional discipline",
"start_url": "/",
"display": "standalone",
"background_color": "#1a1613",
"theme_color": "#b8860b",
"orientation": "portrait-primary",
"icons": [
{ "src": "/icons/icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any maskable" },
{ "src": "/icons/icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
]
}
1.2 Generate App Icons
Directory: web/public/icons/
icon-192x192.png- PWA iconicon-512x512.png- Large PWA icon (install prompt)apple-touch-icon.png- 180x180 iOS home screen
1.3 Generate iOS Splash Screens
Directory: web/public/splash/
Cover major iPhone sizes:
- 640x1136 (iPhone SE)
- 750x1334 (iPhone 8)
- 1125x2436 (iPhone X/XS/11 Pro)
- 1170x2532 (iPhone 12/13/14)
- 1179x2556 (iPhone 14 Pro)
- 1290x2796 (iPhone 14/15 Pro Max)
1.4 Update Layout Metadata
File: web/src/app/layout.tsx
Add to metadata:
manifest: '/manifest.json'- Icon references for all sizes
- iOS splash screen media queries in
appleWebApp.startupImage
Phase 2: Service Worker & Offline (High Priority)
2.1 Install Serwist
npm install @serwist/next serwist
2.2 Configure Next.js
File: web/next.config.ts
import withSerwistInit from "@serwist/next";
const withSerwist = withSerwistInit({
swSrc: "src/app/sw.ts",
swDest: "public/sw.js",
});
export default withSerwist(nextConfig);
2.3 Create Service Worker
File: web/src/app/sw.ts
Caching strategy (critical for trading app):
- Network First: All API routes (fresh data essential)
- Network Only: Supabase, auth, trade execution
- Cache First: Static assets, fonts
- Stale While Revalidate: Images
2.4 Offline Fallback Page
File: web/src/app/offline/page.tsx
Simple page explaining:
- Real-time data requires connection
- Local data (watchlists, journal) saved and will sync
2.5 Background Sync Queue
File: web/src/lib/stores/sync-queue-store.ts
Queue failed mutations when offline, replay on reconnection using existing useNetworkStatus hook.
Phase 3: Native-Like Experience (Medium Priority)
3.1 Swipe Gesture Hook
File: web/src/hooks/useSwipeGesture.ts
interface SwipeConfig {
threshold?: number; // Default: 50px
velocity?: number; // Default: 0.3
onSwipeLeft?: () => void;
onSwipeRight?: () => void;
}
Integration:
- Swipe right from left edge → Open sidebar
- Swipe left on sidebar → Close sidebar
3.2 Haptic Feedback Hook
File: web/src/hooks/useHaptics.ts
{ light, medium, heavy, success, error }
Usage:
- Button taps (light)
- Trade confirmations (success)
- Errors (error pattern)
Note: iOS Safari has limited Vibration API support - use visual feedback as fallback.
3.3 Pull-to-Refresh Component
File: web/src/components/ui/PullToRefresh.tsx
Using Framer Motion (already installed). Apply to:
- Portfolio view
- Watchlist widget
- News feed
3.4 Install Prompt Hook
File: web/src/hooks/useInstallPrompt.ts
Handle beforeinstallprompt for Android/desktop.
For iOS: Show manual "Add to Home Screen" instructions.
Phase 4: Polish (Lower Priority)
4.1 Standalone Mode Detection
File: web/src/hooks/useStandaloneMode.ts
Detect PWA vs browser mode for:
- Hiding install prompts when already installed
- Analytics segmentation
- UI adjustments
4.2 Launch Animation
File: web/src/components/launch/LaunchScreen.tsx
Show DeepStack logo animation on PWA launch (once per session).
4.3 iOS Install Banner
File: web/src/components/pwa/IOSInstallBanner.tsx
For iOS Safari users: dismissible banner with instructions to "Add to Home Screen".
Files to Create
| File | Purpose |
|---|---|
web/public/manifest.json |
PWA manifest |
web/public/icons/*.png |
App icons (3 files) |
web/public/splash/*.png |
iOS splash screens (6 files) |
web/src/app/sw.ts |
Service worker |
web/src/app/offline/page.tsx |
Offline fallback |
web/src/hooks/useSwipeGesture.ts |
Swipe detection |
web/src/hooks/useHaptics.ts |
Haptic feedback |
web/src/hooks/useInstallPrompt.ts |
Install handling |
web/src/hooks/useStandaloneMode.ts |
PWA mode detection |
web/src/components/ui/PullToRefresh.tsx |
Pull refresh |
web/src/components/pwa/IOSInstallBanner.tsx |
iOS install prompt |
web/src/components/launch/LaunchScreen.tsx |
Launch animation |
web/src/lib/stores/sync-queue-store.ts |
Offline sync queue |
Files to Modify
| File | Changes |
|---|---|
web/src/components/chat/ConversationView.tsx |
Fix scroll container, smart chart logic |
web/src/components/widgets/WidgetPanel.tsx |
Add collapse toggles to widgets |
web/src/lib/stores/ui-store.ts |
Add widget collapse state, chart restore logic |
web/src/app/globals.css |
Add scroll containment classes |
web/src/app/layout.tsx |
Add manifest link, icons, splash screens |
web/next.config.ts |
Add Serwist PWA plugin |
web/src/components/layout/DeepStackLayout.tsx |
Add swipe gestures, launch screen |
web/package.json |
Add @serwist/next, serwist |
Dependencies
npm install @serwist/next serwist
Trading App Safety Rules
- Never cache stale market data - Network First/Only for all API calls
- Never cache auth - Network Only for Supabase auth
- Trade execution = Network Only - Clear error if offline
- Sync conflicts - Last-write-wins with timestamp for watchlists/journal
Testing Checklist
Phase 0 - UX Fixes:
- Chat messages scroll independently (page doesn't scroll)
- Chat input stays fixed at bottom of chat area
- Watchlist/chart widget has collapse button
- Collapsed widgets show only header bar
- Chart shows on home state
- Chart hides when tool is active
- Chart restores when returning to home/chat
- All tool panels (Portfolio, News, etc.) scroll properly
PWA Features:
- Home screen install works on iOS Safari
- Splash screens display on various iPhones
- Icons appear correctly on home screen
- Offline page shows when disconnected
- Data syncs when back online
- Swipe gestures work without iOS conflicts
- Virtual keyboard doesn't cover inputs
- Safe areas respected on notched devices
Execution Order
- Phase 0 - Critical UX fixes (scroll, widget collapse, chart logic) - DO FIRST
- Phase 1 - PWA manifest, icons, splash screens, metadata
- Phase 2 - Service worker with Serwist, offline page
- Phase 3 - Gestures, haptics, pull-to-refresh
- Phase 4 - Polish (standalone detection, launch animation, install banner)
Agent & Tool Assignments
Phase 0: Critical UX Fixes
| Task | Agent/Tool | Verification |
|---|---|---|
| 0.1 Fix Chat Scroll | frontend-developer agent | Playwright MCP: test scroll behavior |
| 0.2 Widget Collapse | frontend-developer agent | Playwright MCP: verify collapse toggle |
| 0.3 Chart Logic | frontend-developer agent | Playwright MCP: test state transitions |
| 0.4 Scroll Audit | frontend-developer agent | Playwright MCP: test all panels |
Skills: ui-builder, state-management
MCP: playwright-server for visual verification
Phase 1: PWA Foundation
| Task | Agent/Tool | Verification |
|---|---|---|
| 1.1 Create manifest.json | Main Claude | Lighthouse PWA audit |
| 1.2 Generate Icons | Main Claude (placeholder PNGs) | Visual inspection |
| 1.3 Splash Screens | Main Claude | iOS Safari test |
| 1.4 Update Metadata | Main Claude | Browser DevTools check |
MCP: playwright-server to test home screen install flow
Phase 2: Service Worker & Offline
| Task | Agent/Tool | Verification |
|---|---|---|
| 2.1 Install Serwist | Bash (npm install) | npm ls @serwist/next |
| 2.2 Configure next.config | Main Claude | Build succeeds |
| 2.3 Create sw.ts | fullstack-developer agent | SW registers in DevTools |
| 2.4 Offline Page | frontend-developer agent | Network offline test |
| 2.5 Sync Queue | fullstack-developer agent | Offline mutation test |
Skills: nextjs-project-manager
MCP: playwright-server for offline simulation
Phase 3: Native-Like Experience
| Task | Agent/Tool | Verification |
|---|---|---|
| 3.1 Swipe Gesture Hook | frontend-developer agent | Touch event test |
| 3.2 Haptics Hook | Main Claude | Manual test on device |
| 3.3 Pull-to-Refresh | frontend-developer agent | Playwright touch sim |
| 3.4 Install Prompt | Main Claude | beforeinstallprompt test |
Skills: ui-builder, state-management
Phase 4: Polish
| Task | Agent/Tool | Verification |
|---|---|---|
| 4.1 Standalone Detection | Main Claude | PWA launch test |
| 4.2 Launch Animation | frontend-developer agent | Visual test |
| 4.3 iOS Install Banner | frontend-developer agent | iOS Safari test |
Oversight Workflow
For each task:
1. ASSIGN → Launch appropriate agent with clear task description
2. REVIEW → Read agent output, check code changes
3. VERIFY → Use Playwright MCP to test the change:
- Navigate to relevant page
- Take screenshot/snapshot
- Test interaction
- Check console for errors
4. FIX → If issues found, iterate with agent or fix directly
5. CONFIRM → Mark task complete only after verification passes
Verification Commands:
npm run build- No build errorsnpm run lint- No lint errorsnpm run type-check- No type errors- Playwright:
browser_navigate→browser_snapshot→browser_click→ verify
Error Recovery:
- If agent output has errors → fix inline or re-run agent
- If build fails → check error, fix, re-verify
- If visual test fails → iterate on component