The Edge Streamer
First paint from the edge, interactivity in pieces, and Vitals as a build gate.
The incident
The single-page app shipped 4MB of JavaScript before painting a single pixel. On good hardware it felt fine to the team. In the field — mid-range phones, real networks — users stared at a blank screen for six seconds. Core Web Vitals graded it, search rankings priced that grade in, and the funnel lost people who never saw the product exist.
Why the obvious approach fails
The pure client-side SPA makes a bet: ship all the JavaScript, then build the page on the user's device. That bet is priced in the user's hardware and network — assets your team's machines systematically overestimate. The blank-screen window scales with bundle size, and bundle size only ever grows. Server-side rendering fixes first paint but naively recreates the problem at hydration: the page appears, then freezes while the whole bundle attaches. The mature pattern is streaming: HTML arrives immediately from the edge, suspense boundaries stream sections as they're ready, and hydration happens progressively — so the page is visible in hundreds of milliseconds and interactive in pieces, with the main-thread payload kept ruthlessly small because every kilobyte is a tax on the median phone, not the developer's laptop.
The standard
- First render is server-side or edge-side; the blank-screen SPA boot is banned for user-facing routes.
- Streaming with suspense boundaries: the shell paints immediately, sections arrive as ready, nothing waits for everything.
- The main-thread JavaScript payload carries a hard budget per route, enforced in CI — a bundle-size regression fails the build.
- Core Web Vitals (LCP, INP, CLS) are release gates measured on mid-range device profiles, not developer hardware.
- Images and fonts follow the discipline: sized, lazy where appropriate, and never the cause of layout shift.
How Cortex validates it
At plan time
user-facing routes declare their rendering strategy and per-route payload budgets in the blueprint.
At validation
assert: route.first_paint_source == server|edgeassert: main_thread_js <= route_budgetassert: vitals(mid_range_profile) ∈ passing at releaseAssertion syntax is illustrative.
At review
the approver sees the field-profile run: filmstrip of the page loading on a throttled mid-range device, Vitals scores, and the bundle diff versus the previous release.