What each piece costs and how the library keeps a page fast, especially on phones.
The budgets
Every item declares a JavaScript budget and a WebGL tier, and CI checks them. Server pieces ship no JavaScript; islands are small and load when they near the viewport.
One GPU context
Shader backgrounds draw through a single shared WebGL2 context at a capped resolution, so a page of them does not exhaust the GPU. Three.js showcases each own a stage that is built when it nears the viewport and released after it has been off screen for a while.
Phones
- A scene runs only while it is on screen. There is no pre-roll margin on touch.
- A 3D stage hands its GPU context back two seconds after it leaves the screen.
- Gallery cards play at most two at a time.
- The loop videos on cards play only while visible and never with reduced motion.
What you can do
- Use one animated background per page, and not behind long text.
- Give animated pieces a fixed height or aspect ratio so they cause no layout shift.
- Set
interactive={false}where the pointer should not move a scene. - Measure on a mid-range phone: Largest Contentful Paint under 2.5 s is the goal.
Reduced motion
Loops stop, 3D settles into a composed still and nothing hides behind motion. Test it: turn on "reduce motion" in your system settings and reload.