webperf-snippets 1.5.0 → 1.7.0

package/snippets/Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport.js

@@ -10,26 +10,40 @@
   }
   // @end-shared isOwnRequest
 
-  function getSelector(node) {
-    let sel = "";
-    try {
-      while (node && node.nodeType !== 9) {
-        const el = node;
-        const name = el.nodeName.toLowerCase();
-        const part = el.id
-          ? "#" + el.id
-          : name +
-            (el.classList && el.classList.value && el.classList.value.trim()
-              ? "." + el.classList.value.trim().split(/\s+/).slice(0, 2).join(".")
-              : "");
-        if (sel.length + part.length > 80) return sel || part;
-        sel = sel ? part + ">" + sel : part;
-        if (el.id) break;
-        node = el.parentNode;
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
       }
-    } catch {}
-    return sel;
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
   }
+  // @end-shared uniqueSelector
+
 
   function isInViewport(element) {
     const rect = element.getBoundingClientRect();
@@ -59,12 +73,12 @@
     while (parent && parent !== document.body) {
       const cs = window.getComputedStyle(parent);
       if (cs.display === "none" || cs.visibility === "hidden") {
-        return { hidden: true, reason: "CSS hidden", container: getSelector(parent) };
+        return { hidden: true, reason: "CSS hidden", container: uniqueSelector(parent) };
       }
       for (const selector of hiddenSelectors) {
         try {
           if (parent.matches(selector)) {
-            return { hidden: true, reason: selector, container: getSelector(parent) };
+            return { hidden: true, reason: selector, container: uniqueSelector(parent) };
           }
         } catch {}
       }
@@ -133,7 +147,7 @@
     // Skip images in viewport (they shouldn't be lazy loaded)
     if (isInViewport(img)) {
       if (img === lcpCandidate) {
-        results.excluded.lcpCandidate = getSelector(img);
+        results.excluded.lcpCandidate = uniqueSelector(img);
       } else {
         results.excluded.inViewport++;
       }
@@ -151,7 +165,7 @@
     const hiddenCheck = isInHiddenContainer(img);
 
     const imageData = {
-      selector: getSelector(img),
+      selector: uniqueSelector(img),
       src: src.length > 60 ? "..." + src.slice(-57) : src,
       fullSrc: src,
       dimensions: `${img.naturalWidth}×${img.naturalHeight}`,

package/snippets/Media/Image-Element-Audit.js

@@ -181,6 +181,40 @@
   // if the server does not expose CORS headers.
   const formats = await Promise.all(images.map((img) => fetchFormat(img.currentSrc || img.src)));
 
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
+      }
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
+  }
+  // @end-shared uniqueSelector
+
   const audited = images.map((img, i) => {
     const inViewport = isInViewport(img);
     const isLcp = img === lcpCandidate;
@@ -230,6 +264,7 @@
 
     return {
       img,
+      selector: uniqueSelector(img),
       inViewport,
       isLcp,
       src,
@@ -393,7 +428,7 @@
       totalInfos,
       lcpCandidate: lcpData
         ? {
-            selector: shortSrc(lcpData.src),
+            selector: lcpData.selector,
             format: lcpData.format,
             fetchpriority: lcpData.fetchpriority,
             loading: lcpData.loading,
@@ -402,6 +437,7 @@
         : null,
     },
     items: rankedImages.slice(0, MAX_ITEMS).map((r) => ({
+      selector: r.selector,
       url: r.src,
       format: r.format,
       inViewport: r.inViewport,

package/snippets/Media/Oversized-Images.js

@@ -42,11 +42,39 @@
   const shortUrl = (url) => (url.startsWith("data:") ? url.slice(0, 60) : url);
   const fileName = (url) => url.split("?")[0].split("/").pop() || url;
 
-  function selectorOf(el) {
-    if (el.id) return `img#${el.id}`;
-    const cls = Array.from(el.classList).slice(0, 2);
-    return cls.length ? `img.${cls.join(".")}` : "img";
+  // @shared uniqueSelector
+  // A CSS selector that matches only el in its document (or shadow root): its id when it is unique,
+  // otherwise a path of tag, classes and :nth-of-type() that goes up to the nearest ancestor with a
+  // unique id, or to the root, and stops as soon as it matches one element.
+  function uniqueSelector(el) {
+    const root = el.getRootNode();
+    const matchesOne = (selector) => {
+      try {
+        return root.querySelectorAll(selector).length === 1;
+      } catch {
+        return false;
+      }
+    };
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+      if (node.id && matchesOne(`#${window.CSS.escape(node.id)}`)) {
+        parts.unshift(`#${window.CSS.escape(node.id)}`);
+        break;
+      }
+      const tag = node.localName;
+      let part = tag + Array.from(node.classList).slice(0, 2).map((c) => `.${window.CSS.escape(c)}`).join("");
+      const siblings = node.parentNode ? Array.from(node.parentNode.children) : [node];
+      if (siblings.filter((s) => s.matches(part)).length > 1) {
+        part += `:nth-of-type(${siblings.filter((s) => s.localName === tag).indexOf(node) + 1})`;
+      }
+      parts.unshift(part);
+      if (matchesOne(parts.join(" > "))) break;
+      node = node.parentElement;
+    }
+    return parts.join(" > ");
   }
+  // @end-shared uniqueSelector
 
   function isVector(url) {
     return /^data:image\/svg/i.test(url) || /\.svg([?#]|$)/i.test(url);
@@ -154,7 +182,7 @@
     if (wastedBytes !== null) wastedBytesByUrl.set(url, Math.max(wastedBytesByUrl.get(url) ?? 0, wastedBytes));
 
     flagged.push({
-      selector: selectorOf(img),
+      selector: uniqueSelector(img),
       url: shortUrl(url),
       verdict,
       naturalWidth: file.width,

package/snippets/SCHEMA.md

@@ -59,6 +59,9 @@ Every script must return an object matching this shape:
     target?: string;   // The URL, selector or name the issue is about, when there is one issue per thing
   }>;
 
+  // Next steps in plain text, most important first, without emoji (Cache-Strategy-Analysis)
+  recommendations?: string[];
+
   // Tracking scripts (status: "tracking")
   message?: string;      // Human-readable status message
   getDataFn?: string;    // window function to call for data: evaluate_script(`${getDataFn}()`). May be a dotted path such as "loafHelpers.getData"
@@ -68,6 +71,8 @@ Every script must return an object matching this shape:
 }
 ```
 
+A field named `selector`, `element` or `finalElement`, at any level, is a CSS selector that matches only its element in the document, so `document.querySelector()` returns that element and no other: the id when it is unique, otherwise a path of tag, classes and `:nth-of-type()` up to the nearest ancestor with a unique id, such as `div.carousel-item:nth-of-type(8) > img`. A selector of an element inside a shadow root marks the boundary with `>>>` or ends in `(shadow root)`, and cannot be read from the document. `cli/tests/e2e/snippet-contract.test.js` checks it on its pages.
+
 ---
 
 ## Execution Patterns
@@ -170,7 +175,7 @@ return {
 **The window function must also return a structured object** matching the same schema, including when nothing has been recorded yet:
 
 - `status: "ok"` with `count: 0` when zero is a valid result (no long tasks, no long animation frames).
-- `status: "error"` with an `error` message when there is nothing to report yet and the agent needs to act first (no interactions recorded).
+- `status: "tracking"` with a `message` and its `getDataFn` when there is nothing to report yet and someone has to act first (no interactions recorded): nothing failed, the snippet is still recording. `status: "error"` is for a snippet that failed.
 
 **Scripts using this pattern:** INP, Interactions, Input-Latency-Breakdown, Layout-Shift-Loading-and-Interaction, Scroll-Performance, Long-Animation-Frames (ongoing tracking), LongTask (ongoing tracking), Long-Animation-Frames-Script-Attribution.
 
@@ -262,11 +267,11 @@ Returns buffered CLS immediately and keeps tracking. Always call `getCLS()` afte
 }
 ```
 
-If no interactions yet, `getINP()` returns `status: "error"` with `getDataFn: "getINP"` — retry after user interaction.
+If no interactions yet, `getINP()` returns `status: "tracking"` with a `message` and `getDataFn: "getINP"`: interact with the page and call it again.
 
 The phases describe the whole interaction, not one of its events. A tap fires `pointerdown`, `pointerup` and `click`, and a key press `keydown` and `keyup`, with one `interactionId`. INP, Interactions and Input-Latency-Breakdown group the entries by `interactionId`, also when they arrive in separate observer callbacks, and measure the interaction over its entries painted in the frame of the longest one: `inputDelay` runs from the first `startTime` to the first `processingStart`, `processingTime` to the last `processingEnd`, and `presentationDelay` from there to the paint (`startTime + duration`, never below zero). The interaction is reported under the event whose handler ran longest, or under the `click` or `keydown` when no handler took a millisecond more than theirs; `worstEvent`, the Interactions `type` and the Input-Latency-Breakdown event type follow that rule.
 
-`getINPDetails()` returns the 15 slowest interactions, slowest first, with the total in `count`. `target` is a CSS selector built like `details.element` of LCP, or `null` when the browser reports no target. Use it when `getINP()` shows poor INP and you need to identify patterns across multiple slow interactions. With no interactions yet it returns `status: "error"`, `count: 0` and no items.
+`getINPDetails()` returns the 15 slowest interactions, slowest first, with the total in `count`. `target` is a CSS selector built like `details.element` of LCP, or `null` when the browser reports no target. Use it when `getINP()` shows poor INP and you need to identify patterns across multiple slow interactions. With no interactions yet it returns `status: "tracking"`, a `message`, `count: 0` and no items.
 
 ```json
 {
@@ -1132,7 +1137,7 @@ Returns buffered long tasks immediately. Ongoing tracking continues. `items` lis
 
 #### Oversized-Images (async)
 
-Compares the pixels of each loaded image file with the pixels drawn (rendered size times `devicePixelRatio`, scaled by `object-fit`). `ratio` is file pixels per pixel drawn: `oversized` at 1.5 or more, `undersized` (blurry) under 0.9. `items` lists the flagged images, the most wasted pixels first (at most 50); `count` and `details` cover all of them. `wastedBytes` and `transferBytes` are `null` when the transfer size is hidden (cross-origin without `Timing-Allow-Origin`); `details.wastedBytes` counts each URL once. Images with a zero-size box, unloaded images and SVGs are counted in `details.skipped*`.
+Compares the pixels of each loaded image file with the pixels drawn (rendered size times `devicePixelRatio`, scaled by `object-fit`). `ratio` is file pixels per pixel drawn: `oversized` at 1.5 or more, `undersized` (blurry) under 0.9. `items` lists the flagged images, the most wasted pixels first (at most 50); `count` and `details` cover all of them. `wastedBytes` and `transferBytes` are `null` when the transfer size is hidden (cross-origin without `Timing-Allow-Origin`); `details.wastedBytes` counts each URL once. Images with a zero-size box, unloaded images and SVGs are counted in `details.skipped*`. `selector` matches only the image of its item, built like `details.element` of LCP, so an image with no id or class has a path such as `div.partners > img:nth-of-type(3)` instead of `img`.
 
 ```json
 {
@@ -1141,7 +1146,7 @@ Compares the pixels of each loaded image file with the pixels drawn (rendered si
   "count": 1,
   "details": { "devicePixelRatio": 2, "totalImages": 9, "imagesChecked": 7, "oversized": 1, "undersized": 0, "wastedPixels": 1800000, "wastedBytes": 1614610, "skippedHidden": 1, "skippedNotLoaded": 1, "skippedVector": 0 },
   "items": [
-    { "selector": "img#hero", "url": "https://example.com/hero.png", "verdict": "oversized", "naturalWidth": 1600, "naturalHeight": 1200, "renderedWidth": 200, "renderedHeight": 150, "neededWidth": 400, "neededHeight": 300, "ratio": 4, "wastedPixels": 1800000, "transferBytes": 1922153, "wastedBytes": 1614610, "hasSrcset": false, "hasSizes": false }
+    { "selector": "#hero", "url": "https://example.com/hero.png", "verdict": "oversized", "naturalWidth": 1600, "naturalHeight": 1200, "renderedWidth": 200, "renderedHeight": 150, "neededWidth": 400, "neededHeight": 300, "ratio": 4, "wastedPixels": 1800000, "transferBytes": 1922153, "wastedBytes": 1614610, "hasSrcset": false, "hasSizes": false }
   ],
   "issues": [{ "severity": "warning", "message": "hero.png: 1600x1200 file for a 400x300 slot at 2x (4x too large, about 1577 KB wasted)" }]
 }
@@ -1398,7 +1403,7 @@ Each issue names the preloaded script in `target`.
 
 ### Cache-Strategy-Analysis
 
-Each issue names its resource in `target`, except `header-coverage`. `id` repeats the code, as before the codes.
+Each issue names its resource in `target`, except `header-coverage`. `id` repeats the code, as before the codes. `recommendations` lists the next steps in plain text, the most important first; the console marks their priority with 🔴, 🟡 and ℹ️.
 
 | Code | Severity | When |
 |------|----------|------|

package/snippets/_view/fields.js

@@ -0,0 +1,36 @@
+// How each field of a result is shown, the same in every language: its format, its place among the
+// others (a lower order comes first; a field without one keeps its place after them) and whether it is
+// hidden. The entries of a snippet win over the general ones under "*". A field without an entry takes
+// its format from the suffix of its key (format.js). The words are in locales/.
+
+export default {
+  '*': {
+    // A CSS selector of an element of the page, which a consumer can make inspectable
+    selector: { format: 'selector' },
+    element: { format: 'selector' },
+    finalElement: { format: 'selector' },
+    // The name of a phase, read as its label
+    slowestPhase: { format: 'key' },
+    // The issues of a row: the issues section of the result lists them already
+    issues: { hidden: true },
+  },
+  'Find-Above-The-Fold-Lazy-Loaded-Images': {
+    // Its top and left in px: the distance from the edge of the viewport says what matters
+    position: { hidden: true },
+  },
+  'Input-Latency-Breakdown': {
+    // The same as its rows, one per event type
+    eventTypes: { hidden: true },
+  },
+  INP: {
+    phases: { format: 'phases' },
+  },
+  'Find-render-blocking-resources': {
+    shortName: { order: 1 },
+    type: { order: 2 },
+    responseEndMs: { order: 3 },
+    durationMs: { order: 4 },
+    sizeBytes: { order: 5 },
+    url: { order: 6 },
+  },
+}

package/snippets/_view/format.js

@@ -0,0 +1,39 @@
+// The formats of the values of a result, with the numbers written as the locale writes them. A field
+// without a format in fields.js takes it from the suffix of its key.
+
+const KB = 1024
+const MB = 1024 * 1024
+
+const number = (value, locale, digits = 0, minimum = 0) =>
+  new Intl.NumberFormat(locale, { maximumFractionDigits: digits, minimumFractionDigits: minimum }).format(value)
+
+const FORMATS = {
+  ms: (value, locale) => `${number(Math.round(value), locale)} ms`,
+  bytes: (value, locale) =>
+    value >= MB ? `${number(value / MB, locale, 1, 1)} MB` : value >= KB ? `${number(value / KB, locale, 1, 1)} KB` : `${number(value, locale)} B`,
+  percent: (value, locale) => new Intl.NumberFormat(locale, { style: 'unit', unit: 'percent', maximumFractionDigits: 1 }).format(value),
+  count: (value, locale) => number(value, locale),
+  score: (value, locale) => number(value, locale, 3, 3),
+  bpp: (value, locale) => `${number(value, locale, 3, 3)} bpp`,
+  fps: (value, locale) => `${number(Math.round(value), locale)} fps`,
+  px: (value, locale) => `${number(Math.round(value), locale)} px`,
+}
+
+// The suffixes that name a unit, and the format each one gives
+export const SUFFIXES = [
+  ['Ms', 'ms'],
+  ['Bytes', 'bytes'],
+  ['Percent', 'percent'],
+  ['Count', 'count'],
+  ['Px', 'px'],
+]
+
+export const formatOfKey = (key) => SUFFIXES.find(([suffix]) => key.endsWith(suffix) && key !== suffix)?.[1]
+
+// Text as it is, a number in its format, and an object or a list as compact JSON
+export function formatValue(value, format, locale = 'en') {
+  if (value === undefined || value === null) return ''
+  if (typeof value === 'number') return (FORMATS[format] ?? ((v, l) => number(v, l, 3)))(value, locale)
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}

package/snippets/_view/index.js

@@ -0,0 +1,304 @@
+// The view of a snippet result, shared by the panel of the extension, the reports of the CLI and the
+// visualizer of the site: the title of its table, its details and its columns with labels, formats and
+// order. Each one paints the view its own way, so this module writes no HTML. A field with no entry in
+// fields.js or locales/ still reads well: its format comes from the suffix of its key, and its label
+// from the key in words.
+
+import FIELDS from './fields.js'
+import en from './locales/en.js'
+import { formatOfKey, formatValue, SUFFIXES } from './format.js'
+
+export { formatValue }
+
+const LOCALES = { en }
+
+// Kept in capitals when a key is turned into words
+const ACRONYMS = new Set(
+  'api bfcache cdn cls cors cpu css csr dns dom ect fcp fid fps html http https id inp js json lcp loaf loafs rtt ssr svg sw tbt tcp tls ttfb ui url urls'.split(' ')
+)
+const CAPITALS = { bfcache: 'bfcache', loaf: 'LoAF', loafs: 'LoAFs', urls: 'URLs' }
+
+// A key in words, without the unit its suffix names, since the value shows it: totalBlockingUntilMs is
+// "Total blocking until", isLCP "Is LCP". A count is not a unit, so imageCount is "Image count"
+export function words(key) {
+  const suffix = SUFFIXES.find(([s, format]) => format !== 'count' && key.endsWith(s) && key !== s)?.[0]
+  const stem = suffix ? key.slice(0, -suffix.length) : key
+  const parts = stem
+    // Words in mixed case that the split by capitals would break
+    .replace(/LoAF(s?)/g, ' loaf$1 ')
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .trim()
+    .split(/\s+/)
+    .map((w) => {
+      const lower = w.toLowerCase()
+      if (ACRONYMS.has(lower)) return CAPITALS[lower] ?? lower.toUpperCase()
+      return w.length > 1 && w === w.toUpperCase() ? w : lower
+    })
+  const text = parts.join(' ')
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+// A field with nothing to show: no value, an empty string, or an empty list or object
+const isEmpty = (value) =>
+  value === undefined || value === null || value === '' || (typeof value === 'object' && Object.keys(value).length === 0)
+
+// The locale, its language, and English, which has every word
+const chainOf = (locale) => [...new Set([locale, locale.split('-')[0], 'en'])]
+
+function dictionaries(script, { locale = 'en', fields = {}, locales = {} }) {
+  const allFields = { ...FIELDS, ...fields }
+  const allLocales = { ...LOCALES, ...locales }
+  const chain = chainOf(locale).map((l) => allLocales[l]).filter(Boolean)
+  // The entries of the snippet come before the general ones in any language: a key can mean something
+  // else in a snippet, and its own label in English says it better than a general one translated
+  const scopes = [...chain.map((d) => d[script]), ...chain.map((d) => d['*'])].filter(Boolean)
+  // The words of the view itself (Yes, No, none, rows), in the first language that has them
+  const ui = (name) => chain.map((l) => l['*']?.words?.[name]).find((w) => w !== undefined)
+  return {
+    title: scopes.find((s) => s.title)?.title,
+    // Label and phrase come from the same entry, so a sentence never mixes two languages
+    words: (key) => scopes.find((s) => s.fields?.[key])?.fields[key] ?? {},
+    shape: (key) => ({ ...allFields['*']?.[key], ...allFields[script]?.[key] }),
+    ui,
+    locale,
+  }
+}
+
+function describeField(key, d) {
+  const shape = d.shape(key)
+  const { label, phrase } = d.words(key)
+  return { key, label: label ?? words(key), format: shape.format ?? formatOfKey(key), order: shape.order, hidden: shape.hidden, phrase }
+}
+
+// A lower order first; a field without one keeps its place after them
+const byOrder = (a, b) => (a.order ?? Infinity) - (b.order ?? Infinity)
+
+const splitPhrase = (template) => {
+  const [before, after = ''] = template.split('{value}')
+  return { before, after }
+}
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The format a value has by its shape, when neither its entry nor the suffix of its key gives one
+function shapeOf(value) {
+  if (typeof value === 'boolean') return 'boolean'
+  if (typeof value === 'string' && /^https?:\/\//.test(value)) return 'url'
+  if (Array.isArray(value)) return value.every(isObject) ? 'table' : 'list'
+  if (!isObject(value)) return undefined
+  const values = Object.values(value)
+  if (values.every((v) => typeof v === 'number')) return 'distribution'
+  if (values.every((v) => isObject(v) && typeof v.value === 'number')) return 'phases'
+  if (values.every(isObject)) return 'table'
+  return 'fields'
+}
+
+// The file of a URL, or its host when the path has none
+function shortUrl(url) {
+  try {
+    const { hostname, pathname } = new URL(url)
+    return pathname.split('/').filter(Boolean).pop() ?? hostname
+  } catch {
+    return url
+  }
+}
+
+// A part of a distribution reads inside a line, so in lower case, unless it starts with an acronym
+const inLine = (label) => (/^[A-Z][a-z]/.test(label) ? label.charAt(0).toLowerCase() + label.slice(1) : label)
+
+const plural = (forms, n, locale) => (forms?.[new Intl.PluralRules(locale).select(n)] ?? forms?.other ?? '{n}').replace('{n}', n)
+
+// The phases of a metric: a part each, with its share of the whole and the slowest marked, and the
+// thresholds of the metric as the scale to draw them on
+function phases(value, d, result) {
+  const entries = Object.entries(value).map(([key, v]) => [key, typeof v === 'number' ? { value: v } : v])
+  const sum = entries.reduce((total, [, v]) => total + v.value, 0)
+  // The snippet knows which one is the slowest, also on a tie; otherwise, the longest
+  const named = result?.details?.slowestPhase
+  const slowest = entries.some(([key]) => key === named)
+    ? named
+    : entries.reduce((max, [key, v]) => (v.value > (max?.value ?? 0) ? { key, value: v.value } : max), null)?.key
+  const parts = entries.map(([key, v]) => ({
+    key,
+    label: describeField(key, d).label,
+    value: v.value,
+    text: formatValue(v.value, 'ms', d.locale),
+    percent: v.percent ?? (sum > 0 ? Math.round((v.value / sum) * 100) : 0),
+    overTarget: v.overTarget === true,
+    slowest: key === slowest,
+  }))
+  const t = result?.thresholds
+  const scale = { total: typeof result?.value === 'number' ? result.value : sum, ...(t ? { good: t.good, poor: t.needsImprovement } : {}) }
+  const text = parts
+    .filter((p) => p.value > 0)
+    .map((p) => `${p.label} ${p.text} (${formatValue(p.percent, 'percent', d.locale)})`)
+    .join(' · ')
+  return { parts, scale, text }
+}
+
+// A width and a height of the same thing, as one value of its size: naturalWidth and naturalHeight are
+// naturalSize, 1,200×900
+function joinSizes(rows, locale) {
+  const keys = new Set(rows.flatMap((row) => Object.keys(row)))
+  const heightOf = (width) => width.replace(/^width/, 'height').replace(/Width(Px)?$/, 'Height$1')
+  const pairs = [...keys]
+    .filter((key) => /^(width|.+Width)(Px)?$/.test(key) && keys.has(heightOf(key)))
+    .map((width) => [width, heightOf(width), width.replace(/^width/, 'size').replace(/Width(Px)?$/, 'Size$1')])
+    .filter(([, , size]) => !keys.has(size))
+  if (pairs.length === 0) return rows
+  const number = (n) => formatValue(n, 'count', locale)
+  return rows.map((row) =>
+    Object.fromEntries(
+      Object.entries(row).flatMap(([key, value]) => {
+        const pair = pairs.find(([width, height]) => key === width || key === height)
+        if (!pair) return [[key, value]]
+        if (key === pair[1]) return []
+        const [width, height, size] = pair
+        const both = typeof row[width] === 'number' && typeof row[height] === 'number'
+        const unit = size.endsWith('Px') ? ' px' : ''
+        return [[size, both ? `${number(row[width])}×${number(row[height])}${unit}` : undefined]]
+      })
+    )
+  )
+}
+
+const sameValue = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+
+// A list of objects as a table: its columns, each with its label, and a row of cells per object. A
+// column with the same value in every row is a constant, a line above the table; a column with the
+// file of a URL column gives that one its place and label; and two or more columns of booleans are
+// one column of marks
+function table(items, d) {
+  const rows = joinSizes(
+    items.map((item) => (isObject(item) ? item : { value: item })),
+    d.locale
+  )
+  // A column empty in every row says nothing
+  let columns = [...new Set(rows.flatMap((row) => Object.keys(row)))]
+    .filter((key) => rows.some((row) => !isEmpty(row[key])))
+    .map((key) => describeField(key, d))
+    .filter((c) => !c.hidden)
+    .sort(byOrder)
+  const cells = rows.map((row) => Object.fromEntries(columns.map(({ key }) => [key, describeValue(key, row[key], d, { inTable: true })])))
+
+  const same = (key) => rows.length > 1 && rows.every((row) => sameValue(row[key], rows[0][key]))
+  // Rows that are all the same keep their columns: a table without any says nothing of how many there are
+  const allSame = columns.every(({ key }) => same(key))
+  const constant = (key) => !allSame && same(key)
+  const constants = columns
+    .filter(({ key }) => constant(key))
+    .map(({ key }) => {
+      const { label, text } = describeValue(key, rows[0][key], d)
+      return { key, label, text }
+    })
+  columns = columns.filter(({ key }) => !constant(key))
+
+  for (const url of columns.filter(({ key }) => cells.every((c) => c[key].format === 'url' || c[key].text === ''))) {
+    const short = columns.find(
+      (c) => c !== url && cells.every((row) => (row[url.key].text === '' ? row[c.key].text === '' : row[c.key].value === row[url.key].text))
+    )
+    if (!short) continue
+    columns = columns.filter((c) => c !== url).map((c) => (c === short ? { ...url, label: short.label } : c))
+  }
+
+  const booleans = columns.filter(({ key }) => rows.every((row) => row[key] === undefined || typeof row[key] === 'boolean'))
+  const flagged = booleans.length > 1
+  if (flagged) columns = [...columns.filter((c) => !booleans.includes(c)), { key: 'flags', label: d.ui('flags'), format: 'flags' }]
+  const flagLabel = (c) => inLine(c.label.replace(/^(Is|Has) /, ''))
+
+  return {
+    columns: columns.map(({ key, label, format }) => ({ key, label, format })),
+    constants,
+    rows: cells.map((row, i) => ({
+      cells: columns.map(({ key }) => {
+        if (key !== 'flags' || !flagged) return row[key]
+        const flags = booleans.filter((c) => rows[i][c.key] === true).map(flagLabel)
+        return { key, format: 'flags', value: booleans.filter((c) => rows[i][c.key] === true).map((c) => c.key), flags, text: flags.join(' · ') }
+      }),
+    })),
+  }
+}
+
+// A value with its label and its text, and the parts, fields or rows of a value made of others
+function describeValue(key, value, d, { inTable = false, result } = {}) {
+  const field = describeField(key, d)
+  const format = field.format ?? shapeOf(value)
+  const base = { key, label: field.label, format, value }
+  if (value === undefined || value === null) return { ...base, text: '' }
+  switch (format) {
+    case 'distribution': {
+      const parts = Object.entries(value)
+        .filter(([, n]) => n !== 0)
+        .map(([k, n]) => ({ key: k, label: inLine(describeField(k, d).label), value: n, text: formatValue(n, 'count', d.locale) }))
+      return { ...base, parts, text: parts.length ? parts.map((p) => `${p.label} ${p.text}`).join(' · ') : d.ui('none') }
+    }
+    case 'phases':
+      return { ...base, ...phases(value, d, result) }
+    case 'key':
+      return { ...base, text: describeField(String(value), d).label }
+    case 'table': {
+      // An object of objects is a table too, with the key of each one in its row
+      const items = Array.isArray(value) ? value : Object.entries(value).map(([name, v]) => ({ name, ...v }))
+      return { ...base, ...table(items, d), text: plural(d.ui('rows'), items.length, d.locale) }
+    }
+    case 'fields': {
+      const fields = Object.entries(value)
+        .filter(([k, v]) => !isEmpty(v) && !describeField(k, d).hidden)
+        .map(([k, v]) => describeValue(k, v, d))
+      return { ...base, fields, text: fields.map((f) => `${f.label} ${f.text}`).join(' · ') }
+    }
+    case 'list':
+      return { ...base, text: value.map((v) => formatValue(v, undefined, d.locale)).join(', ') }
+    case 'boolean':
+      return { ...base, text: inTable ? (value ? '✓' : '') : d.ui(value ? 'yes' : 'no') }
+    case 'url':
+      return { ...base, text: shortUrl(value), href: value }
+    default:
+      return { ...base, text: formatValue(value, format, d.locale) }
+  }
+}
+
+export function describeResult(result, options = {}) {
+  const d = dictionaries(result?.script, options)
+
+  const details = Object.entries(isObject(result?.details) ? result.details : {})
+    .filter(([, value]) => !isEmpty(value))
+    .map(([key, value]) => ({ field: describeField(key, d), value, key }))
+    .filter(({ field }) => !field.hidden)
+    .sort((a, b) => byOrder(a.field, b.field))
+    .map(({ field, key, value }) => ({
+      ...describeValue(key, value, d, { result }),
+      ...(field.phrase ? { phrase: splitPhrase(field.phrase) } : {}),
+    }))
+
+  const items = Array.isArray(result?.items) ? result.items : []
+  const { columns, constants, rows } = table(items, d)
+
+  // An issue with a target belongs to the row that has that URL, selector or name in one of its fields
+  const rowOf = (target) => {
+    const index = target === undefined ? -1 : items.findIndex((item) => isObject(item) && Object.values(item).includes(target))
+    return index < 0 ? undefined : index
+  }
+  const issues = (Array.isArray(result?.issues) ? result.issues : []).map(({ severity, code, message, target }) => ({
+    severity,
+    code,
+    message,
+    target,
+    row: rowOf(target),
+  }))
+
+  return {
+    title: d.title,
+    details,
+    columns,
+    constants,
+    rows: rows.map((row, i) => ({ ...row, issues: issues.filter((issue) => issue.row === i) })),
+    issues,
+    recommendations: Array.isArray(result?.recommendations) ? result.recommendations.filter((r) => typeof r === 'string') : [],
+    // The message of a snippet that records is written for the console (call getINP() again); the view
+    // says what to do in its own words
+    message: result?.status === 'tracking' && result.getDataFn ? d.ui('tracking') : result?.message,
+  }
+}