Performance budget

A budget for an agentic surface that gets grafted into somebody else’s product. Copy it per integration and fill in the negotiated rows — a budget with blanks in it is a document, not a budget. Every threshold here is dated to the page it came from, because performance thresholds move and an undated number in a shared doc outlives its own truth by years.

One framing to keep at the front: you are spending from a budget you did not set. The host page already has an LCP, a CLS and an INP, and they are attributed to the host’s origin. Your line item is the delta you add, not the absolute number you measure in isolation.

Rows with published thresholds

These numbers are set outside your organisation and transfer unchanged between host products. Google defines, measures and ranks on the first three; that does not make them wrong, but it does mean they are a vendor’s definitions and have been revised before.

INP (Interaction to Next Paint)

Threshold: 200ms or less at the 75th percentile. Above 200 and up to 500 needs improvement; above 500 is poor. Per web.dev, last updated 2 September 2025.
How it is measured: Field: onINP from the web-vitals/attribution build, reported to your own endpoint. Lab: the Interactions track in the Chrome Performance panel, under a calibrated CPU throttling preset. Never from the Lighthouse performance score, which does not contain INP.
What breaks it: One React state update per streamed chunk. The damage lands in input delay (the click queues behind renders) and presentation delay (the frame cannot paint until pending commits clear), not in your handler.

Long tasks during a stream

Threshold: No main-thread task over 50ms while streaming. Fifty milliseconds is the specification’s definition of a long task, per web.dev (19 December 2024). This is a self-imposed row, not a Core Web Vital — it exists because it is the leading indicator INP lags.
How it is measured: Long tasks are highlighted in red above the flame chart in the Performance panel’s Main track. Mark your chunk-received and post-commit points with performance.mark() so the Timings track shows the boundary directly.
What breaks it: Re-parsing the full markdown body and re-highlighting code blocks on every chunk, which turns a linear stream into quadratic work. Also a single synchronous layout read inside a subscriber.

LCP (Largest Contentful Paint)

Threshold: 2.5 seconds or less at the 75th percentile, per the Core Web Vitals overview. This is the host page’s number, and you are spending from it.
How it is measured: Lighthouse navigation mode is fine here — this is the one part of the budget it measures well. Measure the host page with your surface present and absent; the delta is your line item.
What breaks it: Loading the agentic surface eagerly on a page where it is not the primary content. LCP stops reporting new entries as soon as the user interacts (web.dev, 4 September 2025), so everything your widget does before the first tap counts and everything after is invisible to it.

CLS (Cumulative Layout Shift)

Threshold: 0.1 or less at the 75th percentile. Scored over the largest burst of unexpected shifts in a 5-second session window, per the CLS article.
How it is measured: The Layout shifts track in a Performance recording, or the live-metrics view. Test the mount, not the stream — shifts within 500ms of user input carry hadRecentInput and are excluded, which covers most of what a streaming answer does.
What breaks it: A panel that mounts asynchronously into unreserved space and pushes host content down. This is the one Core Web Vital an embedded surface most often breaks for someone else, and it is entirely preventable with a reserved container.

Rows you have to negotiate

No standards body has a number for these. Leaving them empty is the most common way an integration ships without a budget while appearing to have one.

Marginal payload added to the host bundle

Threshold: No published standard exists. Do not invent one and do not quote a number you read on a blog. The threshold is whatever the host team will agree to in writing, expressed as compressed transfer size for the initial chunk, with everything else behind a dynamic import. Write their number here.
How it is measured: A bundle analyzer run against the host build with and without your surface. The number that counts is the delta to the host’s initial chunk, not the size of your package.
What breaks it: Duplicated transitive dependencies — a second markdown parser, a syntax highlighter with every language registered, a date library the host already ships. Shipping eagerly what should sit behind the first open of the panel.

Field-data coverage

Threshold: A p75 you can actually compute. Not a metric so much as the precondition for every row above it: without field data, every other threshold on this page is being checked against your own laptop.
How it is measured: CrUX where the page qualifies — origins and pages must be “publicly discoverable” with enough visitors — otherwise your own RUM beacon. Session volume has to be high enough that a 75th percentile means something.
What breaks it: Shipping behind a login, which removes CrUX entirely. Also CrUX’s user eligibility rules — Chrome only, usage statistics reporting on, history syncing, no sync passphrase — which mean even a public page’s field data describes a filtered slice of your users.

Lab regression guard in CI

Threshold: Whatever today’s value is, plus an agreed tolerance. A guard against getting worse, not a target. Scope it explicitly to load-time metrics.
How it is measured: Lighthouse navigation mode. Its score is Total Blocking Time 30%, LCP 25%, CLS 25%, First Contentful Paint 10%, Speed Index 10% for Lighthouse 10, per Chrome’s scoring documentation — whose own date stamp reads 2019-09-19, so re-check the composition against the version your CI pins.
What breaks it: Reading a green score as evidence of responsiveness. INP is not in that list. Timespan mode does report INP, but nothing runs timespan mode by default because it requires a human to interact.

Before you call the budget met

Every number has a date and an instrument written next to it. “INP 190ms” is not a measurement; “INP 190ms, field, p75, 14 days, web-vitals v5” is.
Every lab number has the CPU throttling setting next to it. Before and after must be at the same setting or the comparison is meaningless.
The INP row was measured with an interaction that happened mid-stream, and preferably late in a long one. An INP taken on an idle page is a measurement of an idle page.
The payload row is a delta against the host build, not the size of your own package in isolation.
Someone on the host team has seen and agreed the negotiated rows. A budget you set for yourself is a preference.

The measurement module is what fills the first two sections in. The React and payload modules are what move the numbers once they are filled. If a row here has no corresponding line in learning/frontend-performance/MEASUREMENTS.md, that row is currently aspirational — which is worth knowing before someone else finds out.

Performance numbers go stale faster than most facts on this site — thresholds get retired, DevTools features move, browser support changes. Every claim here links to the page it came from and says when that page was last updated. If a source has moved on, check the resource list and tell your teaching agent — the course is meant to be corrected.

Performance budget

Rows with published thresholds

INP (Interaction to Next Paint)

Threshold: 200ms or less at the 75th percentile. Above 200 and up to 500 needs improvement; above 500 is poor. Per web.dev, last updated 2 September 2025.
How it is measured: Field: onINP from the web-vitals/attribution build, reported to your own endpoint. Lab: the Interactions track in the Chrome Performance panel, under a calibrated CPU throttling preset. Never from the Lighthouse performance score, which does not contain INP.
What breaks it: One React state update per streamed chunk. The damage lands in input delay (the click queues behind renders) and presentation delay (the frame cannot paint until pending commits clear), not in your handler.

Long tasks during a stream

Threshold: No main-thread task over 50ms while streaming. Fifty milliseconds is the specification’s definition of a long task, per web.dev (19 December 2024). This is a self-imposed row, not a Core Web Vital — it exists because it is the leading indicator INP lags.
How it is measured: Long tasks are highlighted in red above the flame chart in the Performance panel’s Main track. Mark your chunk-received and post-commit points with performance.mark() so the Timings track shows the boundary directly.
What breaks it: Re-parsing the full markdown body and re-highlighting code blocks on every chunk, which turns a linear stream into quadratic work. Also a single synchronous layout read inside a subscriber.

LCP (Largest Contentful Paint)

Threshold: 2.5 seconds or less at the 75th percentile, per the Core Web Vitals overview. This is the host page’s number, and you are spending from it.
How it is measured: Lighthouse navigation mode is fine here — this is the one part of the budget it measures well. Measure the host page with your surface present and absent; the delta is your line item.
What breaks it: Loading the agentic surface eagerly on a page where it is not the primary content. LCP stops reporting new entries as soon as the user interacts (web.dev, 4 September 2025), so everything your widget does before the first tap counts and everything after is invisible to it.

CLS (Cumulative Layout Shift)

Threshold: 0.1 or less at the 75th percentile. Scored over the largest burst of unexpected shifts in a 5-second session window, per the CLS article.
How it is measured: The Layout shifts track in a Performance recording, or the live-metrics view. Test the mount, not the stream — shifts within 500ms of user input carry hadRecentInput and are excluded, which covers most of what a streaming answer does.
What breaks it: A panel that mounts asynchronously into unreserved space and pushes host content down. This is the one Core Web Vital an embedded surface most often breaks for someone else, and it is entirely preventable with a reserved container.

Rows you have to negotiate

No standards body has a number for these. Leaving them empty is the most common way an integration ships without a budget while appearing to have one.

Marginal payload added to the host bundle

Threshold: No published standard exists. Do not invent one and do not quote a number you read on a blog. The threshold is whatever the host team will agree to in writing, expressed as compressed transfer size for the initial chunk, with everything else behind a dynamic import. Write their number here.
How it is measured: A bundle analyzer run against the host build with and without your surface. The number that counts is the delta to the host’s initial chunk, not the size of your package.
What breaks it: Duplicated transitive dependencies — a second markdown parser, a syntax highlighter with every language registered, a date library the host already ships. Shipping eagerly what should sit behind the first open of the panel.

Field-data coverage

Threshold: A p75 you can actually compute. Not a metric so much as the precondition for every row above it: without field data, every other threshold on this page is being checked against your own laptop.
How it is measured: CrUX where the page qualifies — origins and pages must be “publicly discoverable” with enough visitors — otherwise your own RUM beacon. Session volume has to be high enough that a 75th percentile means something.
What breaks it: Shipping behind a login, which removes CrUX entirely. Also CrUX’s user eligibility rules — Chrome only, usage statistics reporting on, history syncing, no sync passphrase — which mean even a public page’s field data describes a filtered slice of your users.

Lab regression guard in CI

Threshold: Whatever today’s value is, plus an agreed tolerance. A guard against getting worse, not a target. Scope it explicitly to load-time metrics.
How it is measured: Lighthouse navigation mode. Its score is Total Blocking Time 30%, LCP 25%, CLS 25%, First Contentful Paint 10%, Speed Index 10% for Lighthouse 10, per Chrome’s scoring documentation — whose own date stamp reads 2019-09-19, so re-check the composition against the version your CI pins.
What breaks it: Reading a green score as evidence of responsiveness. INP is not in that list. Timespan mode does report INP, but nothing runs timespan mode by default because it requires a human to interact.

Before you call the budget met

Every number has a date and an instrument written next to it. “INP 190ms” is not a measurement; “INP 190ms, field, p75, 14 days, web-vitals v5” is.

Every lab number has the CPU throttling setting next to it. Before and after must be at the same setting or the comparison is meaningless.

The INP row was measured with an interaction that happened mid-stream, and preferably late in a long one. An INP taken on an idle page is a measurement of an idle page.

The payload row is a delta against the host build, not the size of your own package in isolation.

Someone on the host team has seen and agreed the negotiated rows. A budget you set for yourself is a preference.