Update CLS definition

[paulirish]

There were some new variants of CLS and after collecting data (go/nls-lighthouse-analysis and go/nls-ukm-analysis-doc), we got a winner. We're going to use the max-session-gap1s-limit5s one going forward: https://web.dev/evolving-cls/

Also we will use the same existing CLS name as the metric actually doesn't change much, (and even less in a lab scenario). Lastly, we'll upgrade things to the allframes definition, so any shifts from subframes are included.

We'll keep the older definition (aka "uncapped CLS") around for comparison, though with a distinct name. Also, while we're renaming it, we'll get a chance to satisfy the request in CLS: Initial Layout Shift · #12314 and clarify it's only during initial-load, whereas field (legacy) CLS is cumulative for the entire page lifetime.

So we kinda end up with 3: (New) CLS, old CLS (field/page lifetime), Initial-load oldCLS. (See also the last checkbox item)

todo

• add -allframes for gap1s-limit5s - core: add new CLS (all frames) to hidden metrics audit #12476
• rename CLS to initial-CLS. keep number exposed, but not in the report (and field tools are renaming CLS to legacy CLS or Total CLS)
  • tactically: keep new all-farmes cls. keep old cls. keep new single-frame cls. delete rest from metrics.
  • move CLS-gap1s-limit5s-all-frames code to CLS and rename to CLS
• potentially adjust scoring curve and/or score weighting
• does new CLS still need a specific name for lab's initial-load window to distinguish from field? Personally, I recognize they are distinct but expect that in practice, the gap isn't that wide enough to necessitate a unique name.
• update AF CLS smoke test for more events?

note that chrome 90 and 91 will get punished slightly if they don't have a viewport. fixed in 92. see #12353

---

ref core: add hidden layout-shift variant metrics by brendankenny · #12046

[adamraine]

#12353 We may not have stable CLS-AF until M92.

[brendankenny]

re: #12353 (review), we should also write a smoke test/tweak the existing one with specific iframe/element/shift sizing to make sure the subframe weighting is coming out as we expect

[tkadlec]

Jumping in here. :) We updated WebPageTest to use the new metric. From a naming perspective, here's what we're using for now:

• Cumulative Layout Shift: The new windowed metric
• Total Layout Shift: The legacy metric

We are also referencing the "shift window" in the JSON and UI so that it's easier for folks to group individual shifts together.

@rviscomi noted on Twitter that it'd be great to align on names across tools, which I'm all for doing (I think CLS in particular is a bit misleading now myself, since it's no longer really cumulative) as this gets fine-tuned.

[paulirish]

Jumping in here. :) We updated WebPageTest to use the new metric. From a naming perspective, here's what we're using for now:

• Cumulative Layout Shift: The new windowed metric
• Total Layout Shift: The legacy metric

Love it. TotalLayoutShift in WPT wfm.

We're calling the old one totalCumulativeLayoutShift in Lighthouse. (we have a 'cumulative' where you don't, but NDB). This is shipping in Lighthouse v8, along with the windowing changes being applied to CLS.

Also, to be comprehensive.. CrUX will be calling the old CLS "uncapped_cumulative_layout_shift`. (As the window isn't capped.) Obviously "uncapped" != "total", but that's okay as uncapped CLS is field-only summarizing entire page lifetime, and "total" CLS is lab-only summarizing the loadtime LS.

We are also referencing the "shift window" in the JSON and UI so that it's easier for folks to group individual shifts together.

hot.

@rviscomi noted on Twitter that it'd be great to align on names across tools, which I'm all for doing

very happy you reached out to make this happen. :)