No UI Flash

Never flash the wrong UI

Client-rendered apps have a window between first paint and the moment client-side data resolves. The classic bug is filling that window with a placeholder that bets on one outcome — and losing the bet:

• An app-shell skeleton (sidebar, nav, content cards) shown to a signed-out visitor who is about to be bounced to login. They're shown an app they'll never reach, then a jarring swap.
• A results-grid skeleton on a search/list page that resolves to "no results found" — the skeleton promised content that doesn't exist.
• A light-theme first paint that snaps to dark once a preference loads.
• A skeleton for a route that turns out to be a 404.

The rule: render the placeholder for the state you have verified, not the state you hope for. When you can't verify, render a placeholder that's correct in every outcome (neutral, layout-stable) — not the happy path's. Getting there is three layers; each makes the next one's job smaller.

Layer 1 — resolve the state at the edge, before the document is served

The server/edge that serves the SPA's HTML usually already holds what the client will spend a round trip discovering. Use it there:

• Auth: most session schemes verify with no upstream round trip — sealed/signed cookies verify with local crypto, JWTs against a cached JWKS. Gate document requests: signed out → 302 /login?returnTo=<path> before any app HTML exists. The wrong shell can't flash if it's never served. Anyone who receives the SPA at a gated path is now known to be signed in — which makes the client's skeleton honest again.
• Data-shaped states: if the edge can cheaply answer "empty vs. populated" (a count, a KV flag, a cookie recording last-known state), it can serve the right variant — empty-state HTML, the populated shell, a redirect to onboarding — instead of a one-skeleton-fits-all document.
• Preferences (theme, locale, density): read the preference cookie at the edge and serve the correct variant in the initial HTML. A class on <html> beats a client-side flip.

Edge cases that bite (described for auth, but they generalize to any cookie-carried state):

• Gate document navigations only (GET/HEAD with sec-fetch-dest: document, falling back to Accept: text/html). API routes, module requests, and health probes answer for themselves.
• Clear invalid state carriers, don't just route around them. A cookie that fails validation is worse than none — anything keyed on its presence keeps misbehaving until it's gone. Expire it on the response.
• Persist anything the check rotated. If verification refreshed a token, the new value MUST reach the browser on this response — refresh tokens are typically single-use, and dropping the rotation silently breaks the session later. Applies on the serve path, not just redirects.
• Failures inside the edge check collapse to the safe state (signed out, default theme), never to a 500.

Layer 2 — a hint cookie for instant correct paints

Whatever the client normally learns from its first probe (/me, first search, preferences fetch), snapshot it into a non-HttpOnly cookie so the next load paints correctly without waiting:

• The client writes it whenever the server confirms the state, and reads it on the next load to seed an optimistic version while the probe is in flight. (Auth: identity display data. Search/list: "this account has data" or last result count. Theme: the resolved preference.)
• It is a hint, never an authority. Real authorization and real data still come from the server; a stale or forged hint can only change which placeholder briefly renders. Keep the payload to display data the user already knows; schema-validate on read and treat anything malformed as absent.
• The resolved probe always wins — reconcile the moment it lands.
• Clear it everywhere the underlying state dies (logout, account wipe, preference reset) — server-side on those responses, and client-side when a probe contradicts it. A hint that outlives its truth paints the wrong UI confidently.
• In an SSR/hydrating app, read the cookie after mount (effect/state), not during the first render — the first client render must match the server HTML. The flip costs one frame, not a round trip.

With layers 1+2, the client's "loading" placeholder is only reachable in states where it's genuinely correct (e.g. a verified user's first visit on a new browser) — so the optimistic skeleton is finally honest.