Skip to content
Shell
12.6 KB
Raw Blame

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-hidden on parent
  • Chat input must be position: sticky or fixed at bottom
  • Messages container gets flex-1 overflow-y-auto with proper min-h-0
  • Add overscroll-behavior: contain to 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.ts per 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 previousChartState before 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 ScrollArea and overflow-* classes
  • Ensure each scrollable region has:
    • Parent with overflow-hidden and fixed/constrained height
    • Child with overflow-y-auto and min-h-0 (for flex)
    • -webkit-overflow-scrolling: touch for iOS momentum
    • overscroll-behavior: contain to prevent bleed
  • 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 icon
  • icon-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

  1. Never cache stale market data - Network First/Only for all API calls
  2. Never cache auth - Network Only for Supabase auth
  3. Trade execution = Network Only - Clear error if offline
  4. 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

  1. Phase 0 - Critical UX fixes (scroll, widget collapse, chart logic) - DO FIRST
  2. Phase 1 - PWA manifest, icons, splash screens, metadata
  3. Phase 2 - Service worker with Serwist, offline page
  4. Phase 3 - Gestures, haptics, pull-to-refresh
  5. 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 errors
  • npm run lint - No lint errors
  • npm 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