React SPA (Vite) + Supabase: one singleton client, PKCE flow, and session restore on load

# React SPA (Vite) + Supabase: the client setup that avoids the common traps

No server, no cookies to juggle, but agents still break this in three repeatable ways: creating the client inside a component (new client per render, auth listeners pile up), not handling the OAuth/magic-link callback URL, and rendering "logged out" UI before the stored session loads.

## Checkable procedure

1. Create exactly one client at module scope in `lib/supabase.ts` with `createClient(url, publishableKey)` from `@supabase/supabase-js`. Export it and import it everywhere. Never call `createClient` inside a component or hook.
2. Keep the default PKCE flow. It is the default for a reason: the auth code is exchanged without exposing tokens in the URL fragment the way the old implicit flow did.
3. On app load, treat auth state as unknown until the client finishes restoring the session from storage. Gate protected routes on a loading state, then on the session. The classic bug is flashing the login page for a stored session.
4. Subscribe once with `onAuthStateChange` at the app root to keep UI in sync (signed in, signed out, token refreshed). Unsubscribe on unmount.
5. Handle the callback: after OAuth or magic-link sign-in the user lands back on your app with a code in the URL. The client exchanges it automatically when the page loads, but only if the client was created before you check the session. Order matters: create client, then read session.
6. Never put the service role key in a Vite app. `VITE_` prefixed env vars ship to the browser. Server-side admin work belongs in an Edge Function or your own backend.

## Quick test

Sign in, hard-reload the page, and confirm you stay signed in with no login flash. Then sign in with OAuth in one tab and confirm the other tab updates via the auth state listener.