5f27abddd4
* feat(web): in-app PWA update prompt when new service worker is available (closes #938) User-controlled reload with a persistent banner, visibility-triggered SW checks, and an expandable rationale. Switches registerType to prompt. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): align vite.config with soup layers for clean driver merge Keeps registerType prompt while matching garden IWER stubs and PWA share_target shape expected by feat/pwa-share-target in the manifest. Co-authored-by: Cursor <cursoragent@cursor.com> * Revert "fix(web): align vite.config with soup layers for clean driver merge" This reverts commit 6f0915b0884d029a2413d8819a4dfe81d7c4e595. * fix(web): make PWA reload apply waiting service worker updates Handle SKIP_WAITING in injectManifest sw.ts and reload via controllerchange with a timed fallback when vite-plugin-pwa prompt mode does not navigate. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): satisfy setTimeout mock typing in PWA reload tests Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): register PWA service worker before auth gates Mount PwaUpdateProvider at app root and show the update banner on login and error screens so registerSW runs for logged-out users too. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): offset PWA update banner below top status banners Reserve top-12 when syncing or reconnecting so the reload prompt stays visible above SyncingBanner and ReconnectingBanner. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(web): offset PWA update banner below voice error banner Use PwaUpdateBannerWithStatusOffset inside VoiceProvider so voice errors share the same top-12 reservation as sync and reconnect banners. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
5.2 KiB
Progressive Web App (PWA)
HAPI's web interface is a fully-featured PWA that can be installed on your phone for a native app-like experience.
What is PWA?
A Progressive Web App (PWA) is a web application that can be installed on your device and works like a native app:
- Home screen icon - Launch HAPI like any other app
- Full screen mode - No browser chrome, immersive experience
- Offline support - Basic functionality works without internet
- Auto-updates - Always get the latest version
Installing HAPI PWA
Android (Chrome/Edge)
- Open HAPI in Chrome or Edge browser
- Look for the "Install HAPI" banner at the bottom
- Tap "Install"
- HAPI appears on your home screen
::: tip If you don't see the install banner, tap the three-dot menu and select "Add to Home screen" or "Install app". :::
iOS (Safari)
- Open HAPI in Safari browser
- Tap the Share button (square with arrow)
- Scroll down and tap "Add to Home Screen"
- Tap "Add" in the top right corner
::: warning iOS requires Safari for PWA installation. Chrome/Firefox on iOS don't support the "Add to Home Screen" feature. :::
Desktop (Chrome/Edge)
- Open HAPI in your browser
- Click the install icon in the address bar (⊕)
- Or use the menu: "Install HAPI..."
- HAPI opens as a standalone window
PWA Features
Offline Mode
When offline, HAPI can:
- Display cached session lists
- Show previously loaded messages
- Queue actions for when you're back online
An offline indicator appears when you lose connection.
Auto-Update
HAPI checks for updates in the background and lets you choose when to reload:
- Updates are checked hourly and when you return to the tab
- When a new version is available, a persistent in-app banner appears at the top
- Tap Reload when you're ready to apply the update — the banner stays until you do
- Expand "Why can't I dismiss this?" on the banner for the rationale
HAPI uses a user-controlled reload instead of forcing an automatic refresh, so you choose when to reload. The banner cannot be dismissed without upgrading, so you won't forget you're on an old build.
Background Sync
Actions taken offline are synced when reconnected:
- Pending messages are sent
- Permission decisions are relayed
- Session state is refreshed
Caching Strategy
HAPI uses intelligent caching:
| Content | Strategy | Duration |
|---|---|---|
| App shell | Cache first | Until update |
| Sessions API | Network first | 5 minutes |
| Machines API | Network first | 10 minutes |
| Static assets | Cache first | Forever |
Notifications
HAPI supports push notifications to alert you when agents need attention.
Enable Notifications
- Open HAPI - a permission popup appears automatically
- Tap Allow to enable notifications
- If you missed the popup, go to system settings to grant permission
Notification Types
| Type | When Sent |
|---|---|
| Permission Request | Agent needs your approval |
| Ready | Agent finished and awaits input |
::: tip If push notifications don't work in your region (e.g., FCM unavailable), use Telegram integration instead. :::
Managing Your PWA
Check Install Status
HAPI shows different UI based on install status:
- Not installed - Shows install prompt
- Installing - Shows progress indicator
- Installed - No prompt shown
Uninstalling
Android:
- Long-press the HAPI icon
- Drag to "Uninstall" or tap the X
iOS:
- Long-press the HAPI icon
- Tap "Remove App" → "Delete App"
Desktop:
- Open HAPI
- Click the three-dot menu
- Select "Uninstall HAPI"
Clearing Cache
If you experience issues:
- Open HAPI in browser (not installed version)
- Open Developer Tools (F12)
- Go to Application → Storage
- Click "Clear site data"
Best Practices
Battery Optimization
On Android, disable battery optimization for HAPI to ensure:
- Background sync works reliably
- Notifications arrive promptly
Settings → Apps → HAPI → Battery → Unrestricted
Data Usage
HAPI uses minimal data:
- Initial load: ~500KB
- Cached after first load
- Only syncs changed data
Multiple Devices
You can install HAPI on multiple devices:
- All devices use the same server
- Sessions sync across devices
- Same access token works everywhere
Troubleshooting
Install Button Not Showing
- Ensure you're using HTTPS (required for PWA)
- Try refreshing the page
- Check if already installed
App Not Updating
- Close the app completely
- Reopen and wait for update prompt
- If stuck, clear cache and reinstall
Offline Mode Not Working
- Ensure you've loaded the app at least once online
- Check if ServiceWorker is registered (DevTools → Application)
- Clear cache and reload
iOS-Specific Issues
- Must use Safari for installation
- No background sync on iOS
- Limited offline capabilities
Telegram Mini App Alternative
If PWA doesn't suit your needs, consider the Telegram Mini App:
- Works inside Telegram
- No separate installation
- Same features as PWA
- Integrated notifications
See Installation Guide for Telegram setup.