Show CrUX field data alongside lab Web Vitals

  A lab run measures one device, one network, one location — often a fast,
  cached, well-connected one. That makes the lab Web Vitals look healthier than
  what real users actually experience, and a regression real users already feel
  can stay invisible in the lab numbers. sitespeed.io already collects CrUX field
  data when configured, but it lived on a separate tab, so nobody compared the two.

  This puts the CrUX field p75 directly under the lab median in the Google Web
  Vitals card for TTFB, FCP, LCP, CLS and INP, graded against the same
  Good/Needs-improvement/Poor thresholds. The field line is matched to the device
  you tested (mobile run → PHONE, desktop → DESKTOP, falling back to ALL when the
  matching form factor wasn't collected) and always labels which form factor it
  used, so the two numbers are never silently mismatched. When the lab grades a
  metric better than the field does, the card flags it as "lab is more optimistic
  than real users" — the cue that your test conditions are hiding a real-world
  regression.

  Co-authored-by: Claude noreply@anthropic.com

Author: soulgalore

AGENTS.md

@@ -171,6 +171,9 @@ The report has accumulated several non-obvious behaviours that an agent should k
 - **VisualProgress is event-based, not continuous.** Browsertime emits a `VisualProgress` sample only when the similarity-to-final-frame percent changes. Filmstrip frames are snapshots at specific moments. The visual-progress curve must STEP (hold previous percent, step up at next sample), not linearly interpolate — interpolation falsely suggests rendering during a blank period. The scrubber must show the most recent frame whose timestamp is `<=` cursor, not the nearest in either direction. And cursor-to-time math uses the curve's coordinate system (which lives inside a ~38px horizontal inset), not the container width — otherwise the playhead drifts out of sync with the curve. [#4734](https://github.com/sitespeedio/sitespeed.io/pull/4734).
 - **Folder path aliases accept Unicode.** Non-ASCII URL components used to collapse to `-` in result paths (issue #3880). The path-alias regex now permits Unicode letters and digits. Don't tighten it back. [#4759](https://github.com/sitespeedio/sitespeed.io/pull/4759).
 - **CSS rebuilds are required.** Editing SCSS under `lib/plugins/html/src/sass/` does nothing on its own — run `npm run build:css` and commit the compiled `*.min.css` under `lib/plugins/html/assets/css/`. The build step writes both light and dark themes.
+- **Per-URL data is keyed by message type, stored nested.** `dataCollector.addDataForUrl` uses `set()` from `lib/support/objectPath.js`, which splits the message-type path on `.`. So `browsertime.pageSummary` and `crux.pageSummary` land as `pageInfo.data.browsertime.pageSummary` / `pageInfo.data.crux.pageSummary` — nested objects, not literal dotted keys. Read them with `h.get(pageInfo.data, 'crux.pageSummary…')` (also dot-splitting) or direct nested access; a literal `pageInfo.data['crux.pageSummary']` lookup returns nothing.
+- **CrUx field data exposes two shapes.** `crux/repackage.js` produces flat per-metric keys (`loadingExperience.ALL.LARGEST_CONTENTFUL_PAINT_MS.p75`, etc.) **and** keeps the raw API response under `loadingExperience.ALL.data.record.metrics.<snake_case>.percentiles.p75`. Each flat key only exists if that metric was in the CrUx response, so guard before reading. The summary template reads the raw `.data` path; the Web Vitals lab-vs-field line uses the flat keys.
+- **The Google Web Vitals hero is one shared partial.** `lib/plugins/html/templates/url/metrics/index.pug` builds the `wvTiles` scoreboard and is `include`d by both `url/summary/index.pug` and `url/iteration/index.pug`. Edit it once; it renders on both the median-summary and per-run pages. The Web Vitals thresholds (`gwvLcpClass`, … and `wvStatusLabel`) are defined inline near the top of that file — reuse them rather than re-deriving cutoffs.
 
 ## Project metadata
 

docs/documentation/sitespeed.io/crux/index.md

@@ -35,6 +35,13 @@ sitespeed.io --crux.key $CRUX_API_KEY --plugins.remove browsertime --graphite.na
 
 You will get a new tab in your result HTML with the CrUx data.
 
+## Compare your lab data with the field
+When you collect CrUx data, the **Google Web Vitals** card on each URL's metrics tab also shows the CrUx field p75 underneath your own lab median for TTFB, FCP, LCP, CLS and INP. Both lines are graded against the same Good / Needs improvement / Poor thresholds, so you can see at a glance whether your test setup matches what real users experience. When the lab grade is better than the field grade, the card flags the metric as *"Lab is more optimistic than real users"* — a hint that your test conditions (network, device, location, cached state) are rosier than the field, and the lab number is hiding a regression real users already feel.
+
+The field line is matched to the device you tested with: a mobile run (```--mobile```, a real Android device, or iOS) is compared against the CrUx **PHONE** form factor, and a desktop run against **DESKTOP**. To get that match you need to collect the matching form factor (see [Form factor](#form-factor) below) — e.g. ```--crux.formFactor PHONE``` for a mobile run. If the matching form factor wasn't collected, the comparison falls back to **ALL**. The field line always shows which form factor it used (for example *"Field p75 · phone"* or *"Field p75 · all devices"*) so the two lines are never silently mismatched.
+
+The comparison only appears for metrics that exist in both your run and the CrUx response; if CrUx has no data for a Vital, only the lab line is shown.
+
 ## Form factor
 The CrUx data has four different buckets depending on device: DESKTOP, PHONE, TABLET and ALL. You can choose which data to get with ```--crux.formFactor```. Getting only phone data: ```--crux.formFactor PHONE```. If you want to collect data for multiple form factors, add ```--crux.formFactor``` multiple times.
 

lib/plugins/html/assets/css/index-dark.min.css

@@ -743,3 +743,74 @@ $lcp--render-delay: #a78bfa;
   .web-vital--warning & { color: #facc15; }
   .web-vital--error & { color: $color--error; }
 }
+
+// Lab / Field eyebrow label that prefixes the lab status word and the
+// CrUX field line, so the two measurements can't be confused.
+.web-vital-source {
+  font-size: 0.7rem;
+  font-weight: $font--weight--medium;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: $color--text-muted;
+  margin-right: 6px;
+}
+
+// CrUX field p75 line below the lab status. Its own dot is coloured by
+// the field's own Web Vitals class, independent of the tile background
+// (which tracks the lab value).
+.web-vital-field {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-top: 6px;
+  font-size: 0.82rem;
+  color: $color--text-secondary;
+}
+
+// Dot + value + status sit on one line; nowrap keeps the number and its
+// unit (e.g. "490 ms") together instead of breaking across lines.
+.web-vital-field-measure {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  white-space: nowrap;
+}
+
+.web-vital-field-dot {
+  flex: 0 0 auto;
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  background: $color--text-muted;
+
+  &.web-vital-field-dot--ok { background: $color--ok; }
+  &.web-vital-field-dot--warning { background: #facc15; }
+  &.web-vital-field-dot--error { background: $color--error; }
+}
+
+.web-vital-field-value {
+  font-variant-numeric: tabular-nums;
+  font-weight: $font--weight--medium;
+}
+
+.web-vital-field-status {
+  color: $color--text-muted;
+  text-transform: uppercase;
+  font-size: 0.72rem;
+  letter-spacing: 0.04em;
+}
+
+// Shown only when the lab classifies a Vital better than the field does
+// — i.e. the test conditions are rosier than what real users see.
+.web-vital-flag {
+  display: inline-block;
+  margin-top: 6px;
+  padding: 2px 8px;
+  border-radius: $radius--sm;
+  background: $color--warning-bg;
+  border: 1px solid $color--warning-border;
+  color: $color--warning;
+  font-size: 0.72rem;
+  font-weight: $font--weight--medium;
+  line-height: 1.4;
+}

lib/plugins/html/assets/css/index-light.min.css

@@ -819,3 +819,74 @@ $lcp--render-delay: #7c3aed;
   .web-vital--warning & { color: #a16207; }
   .web-vital--error & { color: $color--error; }
 }
+
+// Lab / Field eyebrow label that prefixes the lab status word and the
+// CrUX field line, so the two measurements can't be confused.
+.web-vital-source {
+  font-size: 0.7rem;
+  font-weight: $font--weight--medium;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: $color--text-muted;
+  margin-right: 6px;
+}
+
+// CrUX field p75 line below the lab status. Its own dot is coloured by
+// the field's own Web Vitals class, independent of the tile background
+// (which tracks the lab value).
+.web-vital-field {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-top: 6px;
+  font-size: 0.82rem;
+  color: $color--text-secondary;
+}
+
+// Dot + value + status sit on one line; nowrap keeps the number and its
+// unit (e.g. "490 ms") together instead of breaking across lines.
+.web-vital-field-measure {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  white-space: nowrap;
+}
+
+.web-vital-field-dot {
+  flex: 0 0 auto;
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  background: $color--text-muted;
+
+  &.web-vital-field-dot--ok { background: $color--ok; }
+  &.web-vital-field-dot--warning { background: #facc15; }
+  &.web-vital-field-dot--error { background: $color--error; }
+}
+
+.web-vital-field-value {
+  font-variant-numeric: tabular-nums;
+  font-weight: $font--weight--medium;
+}
+
+.web-vital-field-status {
+  color: $color--text-muted;
+  text-transform: uppercase;
+  font-size: 0.72rem;
+  letter-spacing: 0.04em;
+}
+
+// Shown only when the lab classifies a Vital better than the field does
+// — i.e. the test conditions are rosier than what real users see.
+.web-vital-flag {
+  display: inline-block;
+  margin-top: 6px;
+  padding: 2px 8px;
+  border-radius: $radius--sm;
+  background: $color--warning-bg;
+  border: 1px solid $color--warning-border;
+  color: $color--warning;
+  font-size: 0.72rem;
+  font-weight: $font--weight--medium;
+  line-height: 1.4;
+}

lib/plugins/html/src/sass/dark/components/metricsCards.scss

@@ -162,19 +162,34 @@ if browsertime
   if googleWebVitals
     a#google-web-vitals
     - const wvTiles = []
-    - if (timings.ttfb) wvTiles.push({short: 'TTFB', label: 'Time to first byte', formatted: h.time.ms(timings.ttfb.toFixed ? timings.ttfb.toFixed(0) : timings.ttfb), cls: gwvTtfbClass(timings.ttfb), href: baseHelpURL + 'ttfb'})
-    - if (timings.paintTiming && timings.paintTiming['first-contentful-paint']) { const v = timings.paintTiming['first-contentful-paint']; wvTiles.push({short: 'FCP', label: 'First Contentful Paint', formatted: h.time.ms(v), cls: gwvFcpClass(v), href: baseHelpURL + 'firstContentfulPaint'}) }
-    - if (timings.largestContentfulPaint) { const v = Math.max(timings.largestContentfulPaint.loadTime, timings.largestContentfulPaint.renderTime); wvTiles.push({short: 'LCP', label: 'Largest Contentful Paint', formatted: h.time.ms(v), cls: gwvLcpClass(v), href: '#largestContentfulPaint'}) }
-    - if (browsertime.pageinfo && browsertime.pageinfo.cumulativeLayoutShift !== undefined) { const v = browsertime.pageinfo.cumulativeLayoutShift; wvTiles.push({short: 'CLS', label: 'Cumulative Layout Shift', formatted: v.toFixed(2), cls: gwvClsClass(v), href: '#cumulativeLayoutShift'}) }
-    - if (timings.interactionToNextPaint) { const v = timings.interactionToNextPaint; wvTiles.push({short: 'INP', label: 'Interaction to next paint', formatted: h.time.ms(v), cls: gwvInpClass(v), href: '#interactionToNextPaint'}) }
+    //- CrUX field p75 for the same URL (only when the crux plugin ran).
+    //- The field line reuses the same lab thresholds so Good / Needs
+    //- improvement / Poor mean the same thing on the lab and field rows.
+    //- Match the CrUX form factor to the lab device so a mobile-emulated
+    //- run isn't compared against desktop-heavy field data; fall back to
+    //- ALL when the matched form factor wasn't collected (default is ALL).
+    - const cruxFF = h.get(pageInfo.data, 'crux.pageSummary.loadingExperience')
+    - const labIsMobile = !!(options.mobile || options.android || h.get(options, 'chrome.android.package') || h.get(options, 'firefox.android.package') || h.get(options, 'safari.ios') || h.get(options, 'safari.useSimulator'))
+    - const wantFF = labIsMobile ? 'PHONE' : 'DESKTOP'
+    - const cruxFFKey = cruxFF ? (cruxFF[wantFF] ? wantFF : (cruxFF.ALL ? 'ALL' : null)) : null
+    - const cruxField = cruxFFKey ? cruxFF[cruxFFKey] : null
+    - const cruxFFLabel = cruxFFKey === 'PHONE' ? 'phone' : (cruxFFKey === 'DESKTOP' ? 'desktop' : (cruxFFKey === 'TABLET' ? 'tablet' : 'all devices'))
+    - const fieldVital = (path, classifier, fmt) => { if (!cruxField) return null; const raw = h.get(cruxField, path); return raw == null ? null : {formatted: fmt(raw), cls: classifier(raw)} }
+    - if (timings.ttfb) wvTiles.push({short: 'TTFB', label: 'Time to first byte', formatted: h.time.ms(timings.ttfb.toFixed ? timings.ttfb.toFixed(0) : timings.ttfb), cls: gwvTtfbClass(timings.ttfb), href: baseHelpURL + 'ttfb', field: fieldVital('TIME_TO_FIRST_BYTE_MS.p75', gwvTtfbClass, (v) => h.time.ms(v))})
+    - if (timings.paintTiming && timings.paintTiming['first-contentful-paint']) { const v = timings.paintTiming['first-contentful-paint']; wvTiles.push({short: 'FCP', label: 'First Contentful Paint', formatted: h.time.ms(v), cls: gwvFcpClass(v), href: baseHelpURL + 'firstContentfulPaint', field: fieldVital('FIRST_CONTENTFUL_PAINT_MS.p75', gwvFcpClass, (v) => h.time.ms(v))}) }
+    - if (timings.largestContentfulPaint) { const v = Math.max(timings.largestContentfulPaint.loadTime, timings.largestContentfulPaint.renderTime); wvTiles.push({short: 'LCP', label: 'Largest Contentful Paint', formatted: h.time.ms(v), cls: gwvLcpClass(v), href: '#largestContentfulPaint', field: fieldVital('LARGEST_CONTENTFUL_PAINT_MS.p75', gwvLcpClass, (v) => h.time.ms(v))}) }
+    - if (browsertime.pageinfo && browsertime.pageinfo.cumulativeLayoutShift !== undefined) { const v = browsertime.pageinfo.cumulativeLayoutShift; wvTiles.push({short: 'CLS', label: 'Cumulative Layout Shift', formatted: v.toFixed(2), cls: gwvClsClass(v), href: '#cumulativeLayoutShift', field: fieldVital('CUMULATIVE_LAYOUT_SHIFT_SCORE.p75', (v) => gwvClsClass(Number(v)), (v) => Number(v).toFixed(2))}) }
+    - if (timings.interactionToNextPaint) { const v = timings.interactionToNextPaint; wvTiles.push({short: 'INP', label: 'Interaction to next paint', formatted: h.time.ms(v), cls: gwvInpClass(v), href: '#interactionToNextPaint', field: fieldVital('INTERACTION_TO_NEXT_PAINT_MS.p75', gwvInpClass, (v) => h.time.ms(v))}) }
     - else if (cpu && cpu.longTasks) { const v = cpu.longTasks.totalBlockingTime; wvTiles.push({short: 'TBT', label: 'Total Blocking Time', formatted: h.time.ms(v), cls: gwvTbtClass(v), href: baseHelpURL + 'totalBlockingTime'}) }
     .listing-card.web-vitals-hero
       .listing-card-header
         h3.listing-card-title Google Web Vitals
         if medianRun
           span.listing-card-meta from run #{medianRun.runIndex}
       .web-vitals-hero-grid
+        - const wvRank = (c) => c === 'error' ? 2 : (c === 'warning' ? 1 : (c === 'ok' ? 0 : -1))
         each tile in wvTiles
+          - const labRosier = tile.field && wvRank(tile.cls) >= 0 && wvRank(tile.field.cls) > wvRank(tile.cls)
           .web-vital(class=tile.cls ? 'web-vital--' + tile.cls : '')
             span.web-vital-dot
             .web-vital-body
@@ -184,7 +199,19 @@ if browsertime
               .web-vital-name
                 a(href=tile.href) #{tile.label}
               if tile.cls
-                .web-vital-status #{wvStatusLabel(tile.cls)}
+                .web-vital-status
+                  if tile.field
+                    span.web-vital-source Lab
+                  span #{wvStatusLabel(tile.cls)}
+              if tile.field
+                .web-vital-field
+                  span.web-vital-source Field p75 · #{cruxFFLabel}
+                  .web-vital-field-measure
+                    span.web-vital-field-dot(class='web-vital-field-dot--' + tile.field.cls)
+                    span.web-vital-field-value #{tile.field.formatted}
+                    span.web-vital-field-status #{wvStatusLabel(tile.field.cls)}
+              if labRosier
+                span.web-vital-flag ⚠ Lab is more optimistic than real users
 
   //- 3-5. The three "interactive" Web Vitals each get their own deep-dive
   //- card from a sub-template (LCP phase breakdown, CLS shift list, INP