Optimize Performance

Optimise page performance

This starter is built for animation-heavy marketing sites: springs on scroll, text engines, Lenis smooth scroll, full-bleed imagery, often a WebGL scene. That combination has characteristic failures, and they are not the ones people go looking for. This skill was rewritten from scroll passes on ~50 production sites built from this starter; each lever says whether it is a rule (held on ≥ 3 sites) or observed (1–2). Read obsidian/knowledge/fix-catalog.md and obsidian/knowledge/pitfalls.md before fixing.

The loop is the skill. Build → measure → attribute → fix one thing → re-measure. Never skip to the fix; never report a win you did not measure.

If the project renders a three.js / WebGL scene (three in package.json, or a canvas with a render loop) — hard rule 14 sends you to optimize-3d-scene first. Come back here for the page around the scene.

The bar

ideal on PC and mobile, cold and warm: no frame over 50 ms, ≤ 1 % dropped frames, p99 ≤ 33 ms (budgets against 60 Hz even on a 120 Hz panel). smooth is no frame > 100 ms and ≤ 3 % dropped; anything else is janky. A 50 ms frame is three dropped frames at 60 Hz — where a hitch stops being subliminal.

0. Rules of measurement

1. Measure the build, never next dev. yarn build && yarn start. Kill the old server by port first; start the new one only if the build succeeded.
2. Baseline before you touch anything.
3. 3 runs, medians; a 1/3 freeze may be noise — re-run before fixing. A result near the 1 % line is a draw: A/B the two builds back to back (interleaved, ≥ 2 rounds) and compare per-frame work, not one record.
4. Throttle the CPU (4×) on the phone pass, and emulate 4G — localhost hides lazy-load freezes; any fetched during a pass is a freeze waiting for a slower link.
5. Change one thing at a time, same config before and after.
6. Tracing perturbs what it measures. Use a trace or profile to explain a freeze, never to measure one.
7. A busy machine fakes regressions. Above a load average of ~15 a scroll verdict is unreliable (GPU contention reads as janky) — re-run, don't act. Probes use a plain Chrome UA (the default puppeteer UA gets the robot form).

1. The scroll test — run this before anything else

node tools/qa/scroll-test.mjs --url http://localhost:3000/     # PC wheel + mobile touch (4× CPU), cold then warm
node tools/qa/scroll-test.mjs --url … --devices mobile --runs 1 # chase one freeze
node tools/qa/scroll-test.mjs --url … --first-scroll            # + a scroll from the loader's unlock frame

It opens a visible Chrome (headless GPU behaviour differs), waits until the page can actually scroll (Lenis running, no overflow: hidden), scrolls top → bottom like a person — wheel bursts on PC, touch flings on mobile — jumps back, and scrolls again warm. Every frame over 50 ms is reported with its section, cause and reproducibility:

Plus the worst sections by dropped frames — a page-wide 4 % was one section at 29 %. Read it as a diagnosis:

• Cold bad, warm clean → first-visit work inside animating frames — the most common shape in this starter. §2.
• Both bad → a steady per-frame cost. §3.
• Desktop drops steadily with the main thread idle on a WebGL page → the 120 Hz panel: cap the scene's draw at 60 fps (optimize-3d-scene §5).
• Both clean → the complaint is about load (optimize-load) or about the real phone (mobile-device-qa).

Lighthouse never scrolls; you won't find this by hand either, because by the time you scroll your own site you've warmed it. references/measuring.md has a bench for tracing a freeze the tool already located; tools/qa/profile.mjs --url … --scroll-to "<selector>" names the code.

The test's first scroll starts ~1 s after the page unlocks — a person's starts the instant the loader lets go. Work landing in that second (a scene build, section hydration) passed the test and was a reviewer's first impression on one site. Probe that moment: scroll-test.mjs --first-scroll wheels from the unlock frame — §2.

What it can't tell you: a phone's GPU (throttling slows the CPU, nothing slows the Mac's GPU — use the counted checks in optimize-3d-scene), a real network, iOS Safari. That's mobile-device-qa.

2. First-visit work — the usual culprit

Lazy media decoding mid-reveal

next/image marks anything below the fold loading="lazy"; on a first visit the fetch, decode and first paint land in the frame a reveal starts. The tell: frames drop, the longest main-thread task is ~20 ms — the stall is in raster/decode, not JS. The fix: decode the page's media up front — behind the opening loader if there is one — warming the next/image candidate, not the source file (references/fixes.md has the implementation and its four traps). Warm in idle time well after first interaction or under the loader, never "600 ms after the entrance" — that put a model decode on the first scroll (~700 ms stalls, observed).

Image sequences scrubbed by scroll (phones)

Each drawImage decodes synchronously on the main thread (3.3 s of decode in a 3,000 px scroll, observed). Ship a centre-cropped portrait set for portrait phones (~⅓ the bytes), size the canvas to the frame, decode ahead with createImageBitmap / img.decode() off the scroll path, request nearest-first a few per task (all 150 at once made a ~150 ms frame). Observed (2): janky → ideal hosted.

Hydration, lazy chunks and scene builds inside the scroll

• A dynamic() chunk that loads on scroll lands its fetch, parse and mount in the revealing frame. Preload it after load, mount below-fold scenes on idle after load rather than on proximity, or stop making it dynamic.
• Below-fold hydration (HydrateNear, RobotText lazy) trades TBT for a hydration frame mid-scroll. One site's on-approach hydration made mobile scroll janky every run (75–100 ms frames); one block per idle moment after load kept it smooth — rule (optimize-load §4). Check the scroll test either way.
• The first scroll after a loader. Build the scene and hydrate the sections under the loader, not at its lift; split the curtain-lift's entrances into their own tasks (rule: a 54–73 ms lift frame gone). Stop Lenis while the loader is up — a preloader's overflow: hidden doesn't stop it: a wheel flick under one loader landed the page 1,643 px down. Details: mobile-device-qa §first scroll.
• One bad frame at the loader's lift is not a scroll problem — it's the entrance; fix it there, don't chase it here.

Other first-visit costs

1. Fonts — next/font only, Latin WOFF2 subsets. A late webfont reflows every text engine at once.
2. First paint of a large composited layer — a full-bleed image, a backdrop-filter, a big filter: blur(). Pre-promote reveal layers: before blaming a blur or glass, render the reveals at rest — if the drops vanish, it's each block's first-frame layer promotion → will-change: opacity, transform from load until the reveal ends. Rule (3 sites — the glass was innocent each time).
3. A panel fading in from opacity 0 isn't painted while transparent, so it all rasterises in its first visible frame (40–90 ms, main idle): will-change: opacity on the content keeps it painted (observed).
4. Canvases gated by a scroll flag compile on their first draw — prewarm one hidden frame at mount (observed).