Mobile PWA: installable Agent UI on iOS + Android

[kovtcharov]

Goal

Make the Agent UI an installable Progressive Web App (PWA) so consumers reaching GAIA via the ngrok tunnel can "Add to Home Screen" on iOS / Android and get an app-like experience instead of a bookmarked URL.

Why this matters for consumer adoption

The tunnel work in #872 already gives GAIA a mobile reach — but raw https://abc123.ngrok.app URLs aren't a consumer experience. With a PWA manifest + service worker:

• App icon appears on the user's home screen
• Launches into a full-screen view (no browser chrome)
• Works offline for cached UI shell
• Backgrounded experience matches native apps

This is the cheapest possible win for the mobile story: ~1 day of work, huge perceived-quality delta.

Scope (single PR, v0.18.2)

A. Web App Manifest

• src/gaia/apps/webui/public/manifest.json with:
  • name: "GAIA", short_name: "GAIA"
  • display: "standalone" (full-screen on launch)
  • theme_color, background_color matching the Agent UI palette
  • Icons at 192×192, 512×512 (square + maskable variants)
  • start_url: "/"
  • scope: "/"
• Reference manifest from index.html <link rel="manifest">
• Apple-specific meta tags (Safari PWA support is partial; needs apple-mobile-web-app-* tags + apple-touch-icon)

B. Service worker (minimal — no offline-first yet)

• Use Vite PWA plugin (vite-plugin-pwa, MIT) — handles registration, manifest injection, service worker generation
• Strategy: NetworkFirst for /api/* (always try fresh, fall back to cache only if offline), CacheFirst for static assets
• Cache versioning so app updates take effect on next launch (no stuck-on-old-version)

C. Icons

• Design: square + maskable + Apple touch icon at required sizes
• If brand kit doesn't exist, use a simple wordmark or the existing GAIA logo from src/gaia/img/

D. Add-to-Home-Screen prompt UX

• Detect PWA-installable state via beforeinstallprompt
• Show a subtle one-time hint after the user has used the app for ≥ 60 seconds: "Install GAIA as an app for the best mobile experience"
• Dismissable; remember dismissal in localStorage

E. Tests

• tests/e2e/pwa.spec.ts (under Agent UI: Playwright + Strix Halo E2E suite (validate every UI feature on real AMD hardware) #883 Playwright work) — verify manifest loads, service worker registers, install prompt appears

What this is NOT

• ❌ Not full offline mode (Lemonade is local but the agent loop still needs the laptop running)
• ❌ Not push notifications (separate issue M4)
• ❌ Not native iOS / Android apps

Acceptance criteria

• Visiting the tunnel URL on mobile Safari / Chrome shows an "Add to Home Screen" prompt
• Adding to home screen creates an app icon launching into full-screen GAIA
• Service worker registers; static assets served from cache after first load
• Lighthouse PWA audit score ≥ 90

Attribution / prior art

• vite-plugin-pwa (vite-pwa-org.netlify.app) — upstream library, MIT
• Web App Manifest spec (W3C)

Dependencies

• Adjacent: feat(ui): friendly ngrok tunnel diagnostics + cookie auth for mobile #872 (tunnel diagnostics + cookie auth), Agent UI: Playwright + Strix Halo E2E suite (validate every UI feature on real AMD hardware) #883 (Playwright E2E for mobile coverage)
• Unlocks: M4 (Web Push needs a service worker)