PWA: verify Clerk auth + relay reconnect under iOS standalone mode #5

Activity

1. deanjstone

   added

   wayfinder:researchWayfinder: research/investigation taskWayfinder: research/investigation task

   on Jul 23, 2026
2. deanjstone

   added a parent issue on Jul 23, 2026

   • Add basic installable PWA to apps/web (iOS) #1
3. deanjstone

   marked this as blocking on Jul 23, 2026

   • PWA: verify install + standalone launch on a real iPhone #6
4. deanjstone commented on Jul 23, 2026

   

   deanjstone

   on Jul 23, 2026

   OwnerAuthor

   More actions

   Code-level research (no real iPhone available on this machine — real-device behavior is still #6's job; this is what the code review can tell us in advance).

   Clerk auth

   • Sign-in is triggered via clerk.openSignIn({ forceRedirectUrl: window.location.href }) (ConnectCliAuthSurface.tsx) or clerk.openWaitlist() (useT3ConnectAuthPrompt.tsx) — both are Clerk's modal components, not full-page signInUrl redirects. That matters for standalone mode: the top-level browsing context never navigates away from the installed app's origin, so there's no risk of "sign in" popping the user back out into regular Safari and stranding them there. Good default for this use case.
   • The one place this could still break: if a user picks a social/OAuth provider inside that modal, Clerk does a top-level redirect to the provider and back (no popup/iframe for OAuth). In standalone mode that redirect happens within the same window (no new Safari tab), so it should return correctly into standalone display mode — but this is the one path that most plausibly behaves differently on-device and needs explicit coverage in PWA: verify install + standalone launch on a real iPhone #6.
   • Session/token storage: ManagedRelayAuthProvider (apps/web/src/cloud/managedAuth.tsx) pulls tokens from Clerk's in-memory getToken(), not from anything we write to localStorage ourselves. Clerk's own session persistence relies on first-party cookies. iOS Safari's ITP 7-day script-writable-storage cap does not apply to home-screen web apps (they're treated as their own first-party context), so this shouldn't be a real risk — flagging only because it's a "known Safari gotcha" worth having in mind if PWA: verify install + standalone launch on a real iPhone #6 turns up unexpected logouts after a few days idle.
   • Our own connection state (apps/web/src/connection/storage.ts) persists via IndexedDB, not cookies/localStorage — unaffected by any cookie-partitioning behavior either way.

   Relay reconnect

   • apps/web/src/connection/platform.ts already wires a Wakeups layer off document.visibilitychange → emits "application-active" whenever document.visibilityState === "visible", plus a separate Connectivity layer off window online/offline.
   • packages/client-runtime/src/connection/supervisor.ts consumes both: an application-active wakeup on an already-connected lease triggers a live health probe over the existing session (not a blind reconnect), and on a disconnected/backoff lease it triggers a retry. This is exactly the mechanism that needs to fire correctly when an iOS PWA comes back to the foreground after being backgrounded, so the plumbing for it already exists and doesn't need new code for the common case.
   • Gap I'd flag for real-device testing, not fixing inline: there's no pageshow/persisted (bfcache) handling anywhere in connection/platform.ts, only visibilitychange. iOS Safari is more aggressive than desktop about fully suspending or evicting backgrounded tabs/standalone contexts; if iOS restores the page via bfcache after backgrounding (page freeze + resume rather than reload), visibilitychange should still fire on resume so this is likely fine — but it's exactly the kind of thing that behaves differently in practice on iOS than the spec suggests, and desktop-browser testing can't tell us which case actually happens on-device.

   Recommendation

   Nothing here demonstrates a concrete bug — the modal-based sign-in and the visibility-driven wakeup/probe mechanism both look like they should already handle standalone mode correctly. The two things that specifically need real-device verification in #6 (not fixable/testable further from code alone) are: (1) does the OAuth-provider top-level redirect return cleanly into standalone display mode, and (2) does backgrounding for a real extended period (minutes+, not just tab-switch) correctly trigger the visibility-based reconnect probe, or does iOS's more aggressive suspension require a full reload. No new tickets opened — no code-level fix identified, just verification targets for #6.
5. deanjstone

   closed this as completedon Jul 23, 2026