LCP Regressions
Diagnose and resolve Largest Contentful Paint regressions after adding Coframe
Copy this guide and your current settings as a prompt for your AI agent.
Preview agent promptSee the guide, code and settings included when you copy.
If you observe a Largest Contentful Paint regression after installing Coframe, the most likely causes are the anti-flicker mechanism delaying body visibility or the anti-flicker snippet being installed in a way that prevents it from running before the first paint. This page walks through how to confirm Coframe is involved and what to fix.
For ongoing LCP measurement and how the anti-flicker mechanism interacts with Core Web Vitals in general, see LCP Monitoring.
On this page
01Confirm It’s Coframe
Before investigating configuration or installation issues, establish whether Coframe is actually contributing to the regression.
Append ?cf_disabled to any page URL to disable Coframe for that load:
https://yoursite.com/?cf_disabledWith ?cf_disabled present, the install script exits before the SDK loads or the anti-flicker body hide runs. An LCP measurement taken with this parameter is a clean baseline — the page behaves as if Coframe is not installed. Take the same measurement without the parameter to see LCP with Coframe active. The difference between the two numbers is Coframe’s contribution.
If LCP is similar in both measurements, the regression has a different cause and the rest of this page is unlikely to help. If LCP is meaningfully higher without ?cf_disabled, continue to the causes below.
For the full measurement procedure using the browser Performance panel or Lighthouse, see Testing and Validation.
02Common Causes
Anti-flicker timeout window
Coframe’s anti-flicker mechanism hides <body> immediately when the page loads and keeps it hidden until one of two things happens: the SDK applies its variant changes and explicitly reveals the body, or timeoutMs elapses and the failsafe show() call fires. The default timeoutMs for installed sites is 1000 ms.
Because LCP is measured against visible content, any LCP candidate inside <body> cannot register a paint while the body is hidden. The time the body stays hidden therefore adds to LCP — it sets a floor on when the LCP element can paint. In the best case the SDK loads and applies changes quickly, and the body is revealed well within the timeout window. If the SDK load is slow — due to network conditions, slow variant content that takes time to apply, or other delays — the body stays hidden for longer, and LCP grows with it. If the SDK never responds, the timeout fires at timeoutMs and the page reveals itself regardless; this is a fail-open design that prevents the page from being permanently hidden, but that full timeout duration still adds to LCP in the worst case.
What to check: Run the ?cf_disabled comparison described above. If LCP without ?cf_disabled is consistently worse and the gap is close to 1000 ms, the timeout is the ceiling you’re hitting. Also check how quickly the SDK actually applies its changes in normal conditions — if the apply time is well under 1000 ms, the timeout itself is not the bottleneck, and you may be looking at a slow variant application.
What to change: timeoutMs can be tuned in the SDK configuration. Lowering it reduces the worst-case delay ceiling but also shortens the window in which the SDK can successfully apply variants before the failsafe fires. Raising it extends the window — giving the SDK more time to apply changes cleanly — but also extends the worst-case LCP delay. Set it to the smallest value that still gives the SDK enough time to complete on your target network conditions. See Config Reference for how to set timeoutMs.
Anti-flicker snippet installed asynchronously
The anti-flicker snippet must run synchronously in <head>, before the browser first paints. Its entire purpose is to hide <body> before any content becomes visible — if it runs too late, the browser has already painted original content and there is nothing left to hide before that first paint.
If the snippet is delivered through a tag manager that loads scripts asynchronously, or if the script tag carrying the snippet includes an async or defer attribute, the snippet runs after the initial paint. In that scenario the body goes hidden only after paint, and the subsequent SDK reveal fires at a point that does not correspond to what the browser already recorded as LCP. The anti-flicker is not functioning as designed: the hide-and-reveal cycle no longer suppresses the flash of original content, because it runs too late in the load sequence.
What to check: Inspect the page source and confirm the anti-flicker snippet appears as a synchronous inline script in <head>, without async or defer, and before any other scripts. If you are using a tag manager, verify that the tag manager itself is not deferring injection of the snippet.
What to change: The anti-flicker snippet must be placed as a synchronous inline script directly in the <head> of the document. It is intentionally small so that the brief parse block it causes is minimal. The main SDK script (cf.js) can and should be loaded asynchronously — only the anti-flicker snippet itself requires synchronous placement. See Anti-Flicker for the correct installation pattern and a full explanation of why synchronous placement is required.
# LCP Regressions Diagnose and resolve Largest Contentful Paint regressions after adding Coframe If you observe a Largest Contentful Paint regression after installing Coframe, the most likely causes are the anti-flicker mechanism delaying body visibility or the anti-flicker snippet being installed in a way that prevents it from running before the first paint. This page walks through how to confirm Coframe is involved and what to fix. For ongoing LCP measurement and how the anti-flicker mechanism interacts with Core Web Vitals in general, see [LCP Monitoring](../docs/lcp-monitoring.html). ## Confirm It’s Coframe Before investigating configuration or installation issues, establish whether Coframe is actually contributing to the regression. Append `?cf_disabled` to any page URL to disable Coframe for that load: TEXT ``` https://yoursite.com/?cf_disabled ``` With `?cf_disabled` present, the install script exits before the SDK loads or the anti-flicker body hide runs. An LCP measurement taken with this parameter is a clean baseline — the page behaves as if Coframe is not installed. Take the same measurement without the parameter to see LCP with Coframe active. The difference between the two numbers is Coframe’s contribution. If LCP is similar in both measurements, the regression has a different cause and the rest of this page is unlikely to help. If LCP is meaningfully higher without `?cf_disabled`, continue to the causes below. For the full measurement procedure using the browser Performance panel or Lighthouse, see [Testing and Validation](../docs/testing-and-validation.html). ## Common Causes Anti-flicker timeout window Coframe’s anti-flicker mechanism hides `<body>` immediately when the page loads and keeps it hidden until one of two things happens: the SDK applies its variant changes and explicitly reveals the body, or `timeoutMs` elapses and the failsafe `show()` call fires. The default `timeoutMs` for installed sites is 1000 ms. Because LCP is measured against visible content, any LCP candidate inside `<body>` cannot register a paint while the body is hidden. The time the body stays hidden therefore adds to LCP — it sets a floor on when the LCP element can paint. In the best case the SDK loads and applies changes quickly, and the body is revealed well within the timeout window. If the SDK load is slow — due to network conditions, slow variant content that takes time to apply, or other delays — the body stays hidden for longer, and LCP grows with it. If the SDK never responds, the timeout fires at `timeoutMs` and the page reveals itself regardless; this is a fail-open design that prevents the page from being permanently hidden, but that full timeout duration still adds to LCP in the worst case. What to check: Run the `?cf_disabled` comparison described above. If LCP without `?cf_disabled` is consistently worse and the gap is close to 1000 ms, the timeout is the ceiling you’re hitting. Also check how quickly the SDK actually applies its changes in normal conditions — if the apply time is well under 1000 ms, the timeout itself is not the bottleneck, and you may be looking at a slow variant application. What to change: `timeoutMs` can be tuned in the SDK configuration. Lowering it reduces the worst-case delay ceiling but also shortens the window in which the SDK can successfully apply variants before the failsafe fires. Raising it extends the window — giving the SDK more time to apply changes cleanly — but also extends the worst-case LCP delay. Set it to the smallest value that still gives the SDK enough time to complete on your target network conditions. See [Config Reference](../docs/config-reference.html) for how to set `timeoutMs`. Anti-flicker snippet installed asynchronously The anti-flicker snippet must run synchronously in `<head>`, before the browser first paints. Its entire purpose is to hide `<body>` before any content becomes visible — if it runs too late, the browser has already painted original content and there is nothing left to hide before that first paint. If the snippet is delivered through a tag manager that loads scripts asynchronously, or if the script tag carrying the snippet includes an `async` or `defer` attribute, the snippet runs after the initial paint. In that scenario the body goes hidden only after paint, and the subsequent SDK reveal fires at a point that does not correspond to what the browser already recorded as LCP. The anti-flicker is not functioning as designed: the hide-and-reveal cycle no longer suppresses the flash of original content, because it runs too late in the load sequence. What to check: Inspect the page source and confirm the anti-flicker snippet appears as a synchronous inline script in `<head>`, without `async` or `defer`, and before any other scripts. If you are using a tag manager, verify that the tag manager itself is not deferring injection of the snippet. What to change: The anti-flicker snippet must be placed as a synchronous inline script directly in the `<head>` of the document. It is intentionally small so that the brief parse block it causes is minimal. The main SDK script (`cf.js`) can and should be loaded asynchronously — only the anti-flicker snippet itself requires synchronous placement. See [Anti-Flicker](../docs/anti-flicker.html) for the correct installation pattern and a full explanation of why synchronous placement is required. ## Related - [Anti-Flicker](../docs/anti-flicker.html) — how the body-hide mechanism works and why synchronous installation is required - [LCP Monitoring](../docs/lcp-monitoring.html) — how to interpret LCP measurements on pages running Coframe, and how anti-flicker affects them - [Testing and Validation](../docs/testing-and-validation.html) — the `?cf_disabled` comparison procedure and full SDK verification checklist - [Debug Checklist](../docs/debug-checklist.html) — structured first-pass checklist for any Coframe integration issue - [Config Reference](../docs/config-reference.html) — `timeoutMs` and other configuration options