<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for ChatGPT: scripts/model-profiles.json -->

#Scope contract

FILE_ISOLATION: Modify only files inside the scope the task names. Reading elsewhere is allowed; writing outside it is not, and a needed out-of-scope change is reported, not made. SIGNATURE_PINNING: Before implementing, write the exact signatures you will add or change (name, parameters, return type). Implement to those signatures; if one must change, say so before changing it. TYPE_CONTRACTS: Every public function carries explicit parameter and return types. No any, untyped dict, or interface{} at a module boundary.

---

#Purpose

Rules for making a web application fast. Performance work is worth doing only against measurements — and against the right ones: field data from real users, not a local build on a fast laptop.

Optimising what you have not measured is how teams ship a 40 KB saving on a page whose problem is a 3-second server response.

---

#Measure the right things

Field data (Chrome UX Report, web-vitals in production) beats lab data (Lighthouse). Lab data is reproducible; field data is true.

ts
import { onLCP, onINP, onCLS } from "web-vitals";
onLCP(send); onINP(send); onCLS(send);      // report p75 by route and device class

Track p75, segmented by device class and connection. A p50 on desktop hides the experience of the median mobile user entirely. Test on a mid-range Android device with CPU throttling, not on your development machine.

---

#JavaScript is the expensive part

A byte of JavaScript costs far more than a byte of image: it must be downloaded, parsed, compiled and executed, on the main thread.

• Measure the bundle in CI and fail the build on a regression (size-limit, bundlesize). Growth is otherwise invisible until it is large.
• Analyse before optimising (@next/bundle-analyzer, rollup-plugin-visualizer). It is usually one dependency, not a hundred small things.
• Route-level code splitting first, then component-level for genuinely heavy things — a chart library, a rich text editor, a date picker.
• Check for duplicate copies of the same library at different versions.
• Prefer platform APIs: Intl.DateTimeFormat instead of a date library, fetch instead of a client, structuredClone instead of a deep-clone helper.
• Load third-party scripts with defer or async, from a consent gate, and audit them regularly — analytics and tag managers are frequently the largest script on the page and nobody owns them.

tsx
const Chart = lazy(() => import("./Chart"));   // loaded when rendered, not at boot

Never ship a library for one function. A 70 KB dependency imported for debounce is the most common single avoidable regression.

---

#Images and fonts

Images are usually the LCP element, and fonts are usually the cause of layout shift.

html
<img src="hero.avif" width="1200" height="630" alt="…"
     fetchpriority="high" decoding="async" />
<img src="below.avif" width="400" height="300" alt="…" loading="lazy" />

• Always set width and height (or aspect-ratio). Without them the layout shifts when the image loads — the main cause of CLS.
• loading="lazy" on everything below the fold; never on the LCP image, which needs fetchpriority="high".
• Serve AVIF or WebP with srcset/sizes so a phone does not download a desktop-sized image.
• Fonts: font-display: swap, preload the one font used above the fold, subset it, and self-host. @import from a third party costs an extra connection and round trip before any text renders.
• Declare size-adjust/ascent-override on the fallback font so the swap does not shift the layout.

---

#Rendering cost

• Virtualise long lists (@tanstack/virtual). Rendering 10,000 rows is slow no matter how cheap each row is.
• Keep the main thread free: heavy computation belongs in a web worker.
• Debounce or throttle high-frequency handlers; use useDeferredValue to keep input responsive while an expensive list catches up.
• Avoid layout thrash — batch DOM reads and writes rather than interleaving them.
• Animate transform and opacity only; animating width, top or box-shadow triggers layout or paint on every frame.
• Prefer CSS to JavaScript for animation, and honour prefers-reduced-motion. → Frontend/react

---

#Network and delivery

• Cache static assets immutably with content hashes: Cache-Control: public, max-age=31536000, immutable.
• HTML is no-cache or short-lived; it is what points at the hashed assets.
• Serve from a CDN close to users; compress with Brotli.
• preconnect to critical third-party origins; preload genuinely critical resources only — over-preloading competes with the resources that matter.
• Prefetch the next likely route on intent (hover, viewport), not everything.
• Server-render or statically generate content-heavy pages; a client-rendered page cannot have a good LCP because nothing renders until the JavaScript arrives. → Frontend/server-components

---

#Anti-patterns

---

#Checklist

• LCP, INP and CLS are collected from real users and reviewed at p75
• Metrics are segmented by device class and route
• Testing includes a throttled mid-range mobile device
• A bundle-size budget is enforced in CI
• The bundle has been analysed and large dependencies justified
• Routes are code-split; heavy components load on demand
• No dependency is included for a single small utility
• Third-party scripts are inventoried, deferred and consent-gated
• Every image declares dimensions or an aspect ratio
• The LCP image is prioritised and never lazy-loaded
• Images are served in modern formats with responsive sizes
• Fonts are self-hosted, subset, preloaded, with font-display: swap
• Fallback font metrics are adjusted to avoid swap shift
• Long lists are virtualised
• Expensive computation runs off the main thread
• Animations use only transform and opacity, honouring reduced motion
• Static assets are content-hashed and cached immutably
• Content-heavy pages are server-rendered or statically generated