A visitor who opens bytestream.tv on a fresh browser waits about ten seconds for the first channel cards on a good phone connection, because the app downloads and reads the whole channel catalog before it draws a shelf. This contract sets out how the first load should run instead: draw Watch from a small index first, load the rest behind it, and report every step. The numbers below come from cold loads measured on 2026-11-19, and the budgets are what the build is measured against.
Nothing here is built yet. Every row says whether it is built or pending; the validator enforces the built rows and lists the pending ones, so a row flips to built when its code merges and the validator then holds the code to it.

Terms used below

  • Cold load: the first visit on a browser with nothing cached for bytestream.tv.
  • Shell: the HTML page the static export writes at build time, app/+html.tsx around Watch rendered once, so the browser can paint before any script runs.
  • Entry bundle: the one script every page loads first, /_expo/static/js/web/entry-<hash>.js.
  • Slice: the whole web catalog in one file, catalog/web.json in the public Supabase Storage bucket catalog: every channel, stream and schedule, 3.85 MB as served and about 20 MB of JSON. The catalog pipeline contract owns it.
  • Index and parts: the same catalog cut into a small catalog/web-index.json, which names the parts and carries a first view (the default shelves cut to one screen, with just those channels, streams and what is on now), and content-hashed parts. The catalog work on branch perf/catalog-parts builds them; the catalog contract will own their shape.
  • Skeleton: the grey rows Watch shows while the catalog loads (src/ui/ShelvesSkeleton.tsx).
  • Fast 4G: Chrome DevTools’ network preset, 9 Mbps down and 1.5 Mbps up with 60 ms latency, which DevTools applies as 1,012,500 bytes/s and 165 ms per request.
  • p75: the 75th percentile of real visits. Web Vitals are Google’s page-experience measures: TTFB (first byte), FCP (first text or image), LCP (largest text or image), CLS (how much the layout moves) and INP (how quickly the page answers a tap). web.dev calls a page good when its p75 is within LCP 2.5 s, INP 200 ms, CLS 0.1, FCP 1.8 s and TTFB 0.8 s.
  • As served: bytes over the wire, brotli at quality 3, which is what the production CDN serves.

Today and the target

Today a cold load paints the shell, runs a 1.38 MB entry script, then downloads the whole slice while also fetching Clerk’s sign-in scripts, every font and the programme guide. Watch shows the skeleton until the slice is parsed. On a desktop the shell is hidden for its first 1.5 s, so the screen stays black. In the target the shell paints at the window’s width at once and preloads the index. The app paints the first view’s shelves from the index, then loads the core parts (every channel, every stream, what is on now), then the full schedule. The whole slice, then the sources, are fallbacks. Clerk loads only for signed-in visitors, and everything else waits until the shelves are up.

Budgets

Field numbers are p75 of real visits; lab numbers are medians of cold loads by the measurement script. A pending budget is the target; today’s value shows how far it is.

Measured baselines

Medians of cold loads on 2026-11-19 in installed Chrome, headless, a new browser context per run, CPU not throttled: main at 6179a90 built locally (3 runs per row) and production, which serves the Sep 30 build 65fa7c1 (2 runs per row). The last row is the production load measured by hand that started this work. Times are from navigation start. Something visible is the first frame with text on it. On a desktop it waits for the shell’s 1.5 s hide rule or for the app, whichever comes first; on a phone the shell shows at once. In every run the largest paint was a card picture. The skeleton never left a blank frame before the shelves.

API: what the first load asks for

Required Cache-Control for each file and route, what production answered on 2026-11-19, and when the request may start. The catalog paths are defined in the catalog pipeline contract.

Data

Constants the code is built to, each with the code check that proves it. Shapes are in docs/contracts/first-load/data.schema.json: the boot summary, the per-card picture record and the budget rows.

Events

Each event is a performance mark plus a record the boot module keeps. Spans and measurements go to Sentry on 10% of loads; failures go to Sentry on every load; Speed Insights already collects the Web Vitals from every page view.

State

Motion uses the house tokens: the curve cubic-bezier(0.32, 0.08, 0.24, 1), 200 ms for a state change and 250 ms for a fade-out. Under reduced motion the state still changes, at once. The shelves never leave a blank frame: they are drawn under the skeleton before it fades.

boot

One page load, from navigation to Watch with everything loaded. The fast path is html_shell, app_mounted, first_view_painted, core_ready, full. The fallbacks keep the viewer on Watch: a failed index loads the whole slice, a failed slice loads the sources in the browser, and only when those fail and nothing is cached does the error or offline screen appear.

shelves view

Watch’s shelves area during boot.

card image

One rail card’s still or logo.

font face

One brand or icon font. Text paints in the system face at once (font-display swap) and swaps when the file arrives. An icon glyph is empty until its font arrives.

script chunk

One script file: the entry, or an async chunk (a route with async routes, livekit-client, hls.js once deferred).

third party

One third-party script: Clerk, the YouTube IFrame API, Speed Insights, Web Analytics, the Cloudflare beacon.

Failures

Ordered from the catalog’s fast path outwards: the index, the whole slice, the sources, then everything else a first load touches.

Observability

What writing this contract found

  1. Every cold load waits for the whole catalog. The first shelf appears only after catalog/web.json (3.85 MB as served, about 20 MB of JSON) has downloaded and been parsed: 0.9 to 1.0 s after it arrives in the lab. On Fast 4G that puts first shelves at 9.5 s on main and 10.4 to 10.5 s in production.
  2. Files that never change are revalidated, and a missing one answers as a page. Hashed scripts and fonts go out with public, max-age=14400, must-revalidate. Every cold request in the production runs was REVALIDATED at Cloudflare and MISS at Vercel, and the entry took 969 ms to arrive against 40 ms locally. A request for a chunk the deployment does not have answers 200 with index.html.
  3. A wide window shows black for 1.5 s. The shell is pre-rendered at phone width and a rule hides it for 1.5 s on any window 768 px or wider. On Fast 4G a desktop shows its first text at 1.70 s; a phone shows the shell at 0.19 s.
  4. Nobody can see a slow boot. Sentry runs with tracesSampleRate 0 and the app marks no boot state. Speed Insights reports Web Vitals only, and no alert watches them.
  5. Boot shares its connection with things Watch does not need yet. Clerk (361 KB), the guide (735 KB), every font (1.52 MB) and the YouTube API start during boot, alongside the slice. The catalog store also waits for /api/creators before it reports ready.
  6. Card pictures have no placeholder and move the page. A card showed an empty tile until its picture loaded, and a failed picture dropped the caption and shortened the card. Failed pictures were recorded nowhere; that stays true for individual pictures, which are facts about the sources, but the boot summary counts them.
  7. Offline looks like a broken catalog. With no connection the loader falls through to the sources, they fail, and Watch says Couldn’t reach the catalog. Offline visitors cannot be alerted on; the boot summary counts them when they return.
  8. The skeleton is close to invisible. Its studio blocks reach a contrast of 1.04 to 1 against void at their dimmest and 1.08 to 1 at their brightest.
  9. The motion tokens are not on main. The motion doc describes src/ui/motion.ts with the house curve, 200 ms state and 250 ms move; the file exists only on unmerged branches, and main’s sidebar uses cubic-bezier(0.33, 1, 0.68, 1).
  10. The entry bundle carries code Watch does not draw. hls.js (186 KB as served), every icon family’s glyph map (137 KB), Sentry’s replay and feedback (65 KB), Clerk (75 KB), Supabase (46 KB) and the screens and features of other routes. bundle-plan.json lists each.

Bundle

The entry bundle on main is 2,890,591 bytes, 791,314 as served, from 1,591 source files in 66 npm packages. scripts/contracts/first-load/bundle.mjs attributes each byte to its package from the source map. The 25 largest packages, and whether Watch needs each for its first paint: Expo Router’s async routes split each route into its own chunk loaded when the route is visited. In SDK 57 they are opt-in on every platform: the docs say ‘In SDK 58 and later, async routes on web are stable and enabled by default in development and production’, and earlier SDKs need the expo-router config plugin option asyncRoutes. Static rendering stays supported: ‘Static rendering is supported in production web apps by rendering all Suspense boundaries synchronously in Node.js’. Sources: https://docs.expo.dev/router/web/async-routes/ (read 2026-11-19), and app.json, whose expo-router plugin sets only origin today. Dynamic import() already splits in this export: src/live/loadLiveKit.ts:21 and src/watchroom/faceTrack.web.ts:23 produce livekit-client-46cc91ab….js (154,544 bytes brotli) and vision_bundle-f843d42a….js (41,682 bytes brotli), outside the entry. React.lazy over a dynamic import() of a module therefore works in this build; a lazy component inside the static render needs a Suspense boundary, which the export renders synchronously.

Decisions

Open questions

  1. Can Cloudflare’s Browser Cache TTL for bytestream.tv be set to respect the origin’s headers? Production sends hashed files with public, max-age=14400, must-revalidate. Neither production’s vercel.json (65fa7c1) nor main’s sets a header for them, and Vercel sends its default public, max-age=0, must-revalidate for the HTML from the same deployment, so the 4-hour value comes from Cloudflare’s Browser Cache TTL. Until that setting changes, D2’s one-year header in vercel.json may not reach browsers. Default: Set Caching > Configuration > Browser Cache TTL to Respect Existing Headers. The validator’s live check reports whether production answers with the contracted header.
  2. When will main be promoted to production? Production runs the Sep 30 build 65fa7c1, about 530 commits behind main. Field numbers in Speed Insights and Sentry describe that build, so the field budgets cannot be judged for this work until a build containing it is promoted. Default: Changes are judged on the lab budgets against preview deploys. Field budgets start counting from the first promotion that contains D5.
  3. Does the Sentry plan allow performance spans on 10% of web loads? D5 turns tracing on for the web at a 10% sample. Each sampled load sends one transaction with about eight spans. Default: 10%. If the quota is tight, 2%, as long as A1 still sees at least 100 sampled loads a day.
  4. Is the brighter skeleton right? D7 makes the skeleton’s blocks paper at 16% over void, breathing between 0.7 and 1: a contrast of 1.28 to 1.48 against void, where today’s studio blocks reach 1.04 to 1.08. It is a visual call. Default: Paper at 16%, 0.7 to 1. The change shows it next to today’s skeleton before it merges.
  5. Does the production Clerk instance set its __client_uat cookie on bytestream.tv? D4 loads Clerk only when a session cookie says the visitor is signed in. That works when Clerk’s production instance runs on a bytestream.tv subdomain and sets the cookie on the app’s own domain; the local build uses a development instance on clerk.accounts.dev, which does not. Default: Check the cookie on production. If it is not there, load Clerk for everyone right after the first view instead of during boot.
  6. Keep the Cloudflare Web Analytics beacon alongside Vercel Analytics? Cloudflare injects static.cloudflareinsights.com/beacon.min.js (about 10 KB) into every page at the edge. Vercel Web Analytics already counts page views. Default: Keep it; it loads after the page and counts toward no budget except B12, where it must start after the first shelves.

Run the checks

From the atlas repo root. The validator reads the contract files and the code, and asks production for a few headers; it sends nothing else and writes nothing.
It exits 0 when the contracts pass and every live failure is explained by a pending decision, 1 when a contract check fails, and 2 when a live check fails for any other reason. The contract files are in docs/contracts/first-load/.