@bezda/rhp-mcp 0.1.5 → 0.1.7

package/src/check/findings.js

@@ -4,11 +4,65 @@
 const q = (text) => `"${text}"`;
 
 // What an interaction is, said as something a reader does ("clicking button "Q2"")
-const DOING = { hover: "pointing at", tap: "tapping", click: "clicking", input: "setting", select: "setting", key: "pressing", pick: "picking" };
+const DOING = { hover: "pointing at", tap: "tapping", click: "clicking", input: "setting", select: "setting", key: "pressing", pick: "picking", scrub: "moving the pointer along" };
 
 // How far something moved: "88px down", "12px right"
 const shift = ({ dx, dy }) => [dy && `${Math.abs(dy)}px ${dy > 0 ? "down" : "up"}`, dx && `${Math.abs(dx)}px ${dx > 0 ? "right" : "left"}`].filter(Boolean).join(" and ");
 
+// How a box changed size: "grows 18px taller", "shrinks 6px narrower"
+const grows = ({ dw, dh }) => [dh && `${dh > 0 ? "grows" : "shrinks"} ${Math.abs(dh)}px ${dh > 0 ? "taller" : "shorter"}`, dw && `${dw > 0 ? "grows" : "shrinks"} ${Math.abs(dw)}px ${dw > 0 ? "wider" : "narrower"}`].filter(Boolean).join(" and ");
+
+// The section of the skill's references that explains a finding's fix, for an agent whose fix did not hold: the
+// report names it ("See: ..."), so the agent reads that section, not the whole file
+const PITFALLS = (title) => `pitfalls.md, "${title}"`;
+export const SEE = {
+  "two-solids": PITFALLS("Mistakes that come from other libraries"),
+  "cdn-version": PITFALLS("Mistakes that come from other libraries"),
+  "no-chart": PITFALLS("Nothing draws, or the chart is empty"),
+  "empty-plot": PITFALLS("Nothing draws, or the chart is empty"),
+  "missing-import-map": PITFALLS("Nothing draws, or the chart is empty"),
+  "plain-script-tag": PITFALLS("Nothing draws, or the chart is empty"),
+  "missing-export": PITFALLS("Nothing draws, or the chart is empty"),
+  "bad-scale": PITFALLS("Bars, dots or labels in the wrong place"),
+  "value-past-scale": PITFALLS("Bars, dots or labels in the wrong place"),
+  "points-past-scale": PITFALLS("Bars, dots or labels in the wrong place"),
+  "nan-value": PITFALLS("Bars, dots or labels in the wrong place"),
+  "dot-size": PITFALLS("Bars, dots or labels in the wrong place"),
+  "sticks-out": PITFALLS("Text sticks out, is cut off or overlaps"),
+  "text-cut-off": PITFALLS("Text sticks out, is cut off or overlaps"),
+  "text-overlap": PITFALLS("Text sticks out, is cut off or overlaps"),
+  "text-outside-poster": PITFALLS("Text sticks out, is cut off or overlaps"),
+  "page-scrolls-sideways": PITFALLS("Text sticks out, is cut off or overlaps"),
+  "tiny-text": PITFALLS("Text sticks out, is cut off or overlaps"),
+  "small-plot": PITFALLS("The chart is tiny, squashed or the wrong size"),
+  "collapsed-chart": PITFALLS("The chart is tiny, squashed or the wrong size"),
+  "cramped": PITFALLS("The chart is tiny, squashed or the wrong size"),
+  "plot-outside-chart": PITFALLS("The chart is tiny, squashed or the wrong size"),
+  "stale-read": PITFALLS("Values never update, or the chart jumps"),
+  "static-chart": PITFALLS("Values never update, or the chart jumps"),
+  "style-string": PITFALLS("Values never update, or the chart jumps"),
+  "block-transition": PITFALLS("Values never update, or the chart jumps"),
+  "bare-boolean": PITFALLS("A click, hover, tap or key does nothing, or the wrong thing"),
+  "handler-at-render": PITFALLS("A click, hover, tap or key does nothing, or the wrong thing"),
+  "flicker": 'interaction.md, "2. Readout on hover, focus and tap"',
+  "selection-reset": 'interaction.md, "2. Readout on hover, focus and tap"',
+  "selection-hover-stays": 'interaction.md, "2. Readout on hover, focus and tap"',
+  "selection-control-reset": 'interaction.md, "2. Readout on hover, focus and tap"',
+  "layout-jump": PITFALLS("The layout jumps when the reader interacts"),
+  "text-shift": PITFALLS("The layout jumps when the reader interacts"),
+  "jitter": PITFALLS("The layout jumps when the reader interacts"),
+  "out-of-view": 'interaction.md, "2. Readout on hover, focus and tap"',
+  "scrolls-away": 'interaction.md, "2. Readout on hover, focus and tap"',
+  "focus-invisible": 'interaction.md, "9. Keyboard"',
+  "page-css-ignored": PITFALLS("Styles or colors do not apply"),
+  "series-past-theme": PITFALLS("Styles or colors do not apply"),
+  "class-name": PITFALLS("Styles or colors do not apply"),
+  "low-contrast": 'design.md, "4. Color"',
+  "faint-marks": 'design.md, "4. Color"',
+  "colorblind": 'design.md, "4. Color"',
+  "rhp-warning": PITFALLS("Console warnings rhp prints"),
+};
+
 // A finding from what measure() saw in the page
 export function fromProbe(f, context) {
 
@@ -173,7 +227,7 @@ export function fromProbe(f, context) {
         fix: "Give it visible text, an aria-label (aria-label=\"Play\" on an icon button), or a <label> around an input or a select.",
       };
     case "layout-jump": {
-      const list = f.moved.slice(0, 3).map((m) => `${m.what} moves ${shift(m)}`).join(", ");
+      const list = f.moved.slice(0, 3).map((m) => (m.box ? `${m.what} ${grows(m)}` : `${m.what} moves ${shift(m)}`)).join(", ");
       const plot = f.moved.some((m) => m.plot);
       return {
         level: "warning",
@@ -181,7 +235,42 @@ export function fromProbe(f, context) {
         message: `The layout jumps when ${DOING[f.kind] ?? f.kind} ${f.target}: ${list}${f.moved.length > 3 ? ` and ${f.moved.length - 3} more` : ""}${f.more ? ` (${f.more} more interaction${f.more > 1 ? "s do" : " does"} the same)` : ""}, so what the reader goes to next is no longer where it was.`,
         fix: plot
           ? "Keep the plot still while a slat is lit: a lit name that gets wider (bolder, larger) makes room: \"auto\" measure the names again, so keep the names' weight and size and change only their color, or give the room in px (room: { start: 140 })."
-          : "Keep what the interaction changes in a box that keeps its size: a readout or a headline on one line (white-space: nowrap; overflow: hidden; text-overflow: ellipsis) or with a min-height for its longest text, and buttons that keep their width when their label or weight changes.",
+          : "Keep what the interaction changes in a box that keeps its size: a readout or a headline on one line (white-space: nowrap; overflow: hidden; text-overflow: ellipsis) or with a min-height for its longest text, a readout's card or a legend's panel with a fixed width or a min-width and min-height for its longest content, and buttons that keep their width when their label or weight changes.",
+      };
+    }
+    case "text-shift": {
+      const list = f.moved.slice(0, 3).map((m) => `${m.what} moves ${shift(m)}`).join(", ");
+      return {
+        level: "warning",
+        code: f.code,
+        message: `Text that says the same thing moves when ${DOING[f.kind] ?? f.kind} ${f.target}: ${list}${f.moved.length > 3 ? ` and ${f.moved.length - 3} more` : ""}${f.more ? ` (${f.more} more interaction${f.more > 1 ? "s" : ""} or pick${f.more > 1 ? "s" : ""} move text too)` : ""}. Labels and values that slide as the numbers change make the reader lose their place.`,
+        fix: "Give what changes a place that keeps its size, so the text around it stays put: numbers in tabular figures (font-variant-numeric: tabular-nums) in a column of their own or with a min-width in ch, right-aligned; a label in its own column (a grid), not after a value on the same line; a readout's lines in a fixed order; and a min-height for the readout's longest text.",
+      };
+    }
+    case "jitter": {
+      const how = (m) => [m.dx && `slides up to ${Math.abs(m.dx)}px ${m.dx > 0 ? "right" : "left"}`, m.dy && `moves up to ${Math.abs(m.dy)}px ${m.dy > 0 ? "down" : "up"}`].filter(Boolean).join(" and ");
+      const list = f.moved.slice(0, 3).map((m) => `${m.what}${m.line ? ` (in "${m.line}")` : ""} ${how(m)}`).join(", ");
+      return {
+        level: "warning",
+        code: f.code,
+        message: `The readout jitters as the pointer moves along ${f.target}: ${list}${f.moved.length > 3 ? ` and ${f.moved.length - 3} more` : ""}. A text that keeps none of its edges in place while the values change, or moves while it says the same thing, shakes under the reader's eyes at every step along the chart.`,
+        fix: "Start each part of the readout where nothing before it changes width: a grid with a column per part, or each part on a line of its own, never a label after a value on the same line. Give each value a box that keeps its size: tabular figures (font-variant-numeric: tabular-nums) with a min-width in ch for the longest value it can show (and the longest date), right-aligned when it ends a column. Keep the readout on its lines whatever it says: white-space: nowrap, or a min-height for its longest text at the narrowest width.",
+      };
+    }
+    case "flicker":
+      return {
+        level: "warning",
+        code: f.code,
+        message: `Moving the mouse from ${f.from} to ${f.to}, ${f.readout ? "the readout goes back to what it shows at rest" : "the lit slat goes back to how it looks at rest"} for a moment between them${f.more ? ` (and between ${f.more} more pair${f.more > 1 ? "s" : ""} of neighbors)` : ""}: it flickers as the reader moves along the chart.`,
+        fix: "Keep the pick while the pointer is between slats: change it only when the pointer reaches another slat (on a pointer move over no slat, keep the pick), and clear it only when the pointer leaves the chart or the poster, as the readout example in SKILL.md does.",
+      };
+    case "scrolls-away": {
+      const parts = [f.controls.length && `its controls (${f.controls.join(", ")})`, f.readout && `its readout ("${f.readout}")`].filter(Boolean);
+      return {
+        level: "info",
+        code: f.code,
+        message: `With the middle of the chart in the middle of the ${f.phone ? "phone's screen" : "window"}, ${parts.join(" and ")} ${parts.length > 1 || f.controls.length ? "are" : "is"} scrolled out of view: a reader going through the chart has to scroll back to ${f.controls.length ? "use them" : "read it"}.`,
+        fix: "Consider keeping them in view as the reader scrolls (often better, not always): position: sticky; top: env(safe-area-inset-top, 0px) on the row that holds them, with a background and a z-index over the plot's 1, compact on a phone (one line, the readout under the controls), and scroll-margin-top on the slats so a picked slat is never under it. Leave them where they are when the design needs it.",
       };
     }
     case "out-of-view":
@@ -198,6 +287,13 @@ export function fromProbe(f, context) {
         message: `Tab reaches ${f.what}${f.more ? ` and ${f.more} more` : ""}, but nothing on screen shows the focus there: a keyboard reader cannot see where it is.`,
         fix: "Show focus: take off outline: none, or put a :focus-visible style that shows in its place (outline: 2px solid in the ink color, outline-offset: 2px; on a slat, in the slat type's css).",
       };
+    case "selection-control-reset":
+      return {
+        level: "warning",
+        code: f.code,
+        message: `The control "${f.control}" selects the same data as chart hover, but ${f.when} changes its committed value or loses its selected view.`,
+        fix: "Keep the choice made with this selection control separate from the temporary hover preview. The control may follow the hovered point visually, but when hover ends or focus moves, its value and selected view must return to the committed choice. Chart clicks, taps, keyboard selection and the input should update the same committed selection. Do not save and restore a shared value around individual events, reset the input on blur, or apply the initial-state reset rule to this control's chosen value. Preserve explicit user instructions for a different interaction policy.",
+      };
     case "selection-hover-stays":
       return {
         level: "warning",

package/src/check/index.js

@@ -27,8 +27,10 @@
 //   findings      [{ level: "error" | "warning" | "info", code, message, fix, width, widths }], errors first
 //   charts        [{ width, slats, blocks: { bar: 3, label: 6 }, box: { width, height } }]
 //   interactions  [{ width, kind, target, changed, how, error, moved, unseen }]
-//   swept         [{ width, breakpoint, slats, jumps }]: the widths at which every slat was picked in turn (each width
-//                 checked, and the page's own breakpoints between them), how many slats, and how many moved the layout
+//   swept         [{ width, breakpoint, slats, reached, jumps, scrubbed }]: the widths at which every slat was picked in
+//                 turn (each width checked, and the page's own breakpoints between them), how many slats, how many the
+//                 pointer could reach, how many moved the layout, and when the pointer was moved along the chart
+//                 instead, scrubbed: { points, moved: how many of its steps moved something }
 //   screenshots   [{ width, dark, hover, path }]
 //   text          the report as plain text (what the CLI prints)
 import fs from "fs";
@@ -39,7 +41,7 @@ import { pathToFileURL, fileURLToPath } from "url";
 import { detectFormat, bundle, guardedStandalone, htmlProblems, packages, contentType } from "./build.js";
 import { launch, NO_BROWSER_FIX } from "./browser.js";
 import { install } from "./inpage.js";
-import { fromProbe, fixForError, placeOf } from "./findings.js";
+import { fromProbe, fixForError, placeOf, SEE } from "./findings.js";
 import { textContrast, faintMarks, colorBlind } from "./colors.js";
 import { decode } from "./png.js";
 import { interact as interactionPass } from "./interact.js";
@@ -94,17 +96,28 @@ function source({ file, code, format }) {
 // Picks every slat of the page's main Plot in turn, as a reader going from one to the next (a tap on a touch screen,
 // the mouse elsewhere), on a page at rest with reduced motion asked for, where a pick shows at once; and lists what moved
 // outside the plot (moved() in inpage.js): a readout that takes another line for one slat, at one width. What a pick
-// throws is tagged with it in events, as the interaction pass does.
+// throws is tagged with it in events, as the interaction pass does. When the main chart draws a line or an area, a
+// layer over the plot takes the pointer (the slats cannot be pointed at) or the Plot has one or two slats (a line per
+// series), the reader moves along the chart, and the sweep scrubs it first (scrub()). { slats, reached: the slats it
+// could point at, jumps, scrub }
 async function sweep(page, touch, events) {
 
   const slats = await page.evaluate(() => window.__rhpProbe.sweepTargets());
   const jumps = [];
-  if (!touch) await page.mouse.move(0, 0);
-  await page.evaluate(() => window.__rhpProbe.place());
+  await page.mouse.move(0, 0);
+  await page.evaluate(() => {
+    window.__rhpProbe.place();
+    window.__rhpProbe.placeLines();
+    window.__rhpProbe.watch(true);
+  });
+  const first = slats.length ? await page.evaluate((n) => window.__rhpProbe.pointAt(n), slats[0].target).catch(() => null) : null;
+  const scrubbed = slats.length ? await scrub(page, events, slats.length <= 2 || !!first?.covered) : null;
+  let reached = 0;
   for (const s of slats) {
     // (a slat that something covers has no point: pointing there would pick what covers it)
     const point = await page.evaluate((n) => window.__rhpProbe.pointAt(n), s.target).catch(() => null);
     if (!Number.isFinite(point?.x) || !Number.isFinite(point?.y)) continue;
+    reached++;
     const name = `slat ${s.index} of ${s.of}${s.name ? ` (${s.name})` : ""}`;
     const before = events.length;
     try {
@@ -120,8 +133,92 @@ async function sweep(page, touch, events) {
     const moved = await page.evaluate((n) => window.__rhpProbe.moved(n, true), s.target).catch(() => []);
     if (moved.length) jumps.push({ target: name, moved });
   }
+  await page.evaluate(() => window.__rhpProbe.watch(false)).catch(() => {});
   if (!touch) await page.mouse.move(0, 0);
-  return { slats: slats.length, jumps };
+  return { slats: slats.length, reached, jumps, scrub: scrubbed };
+}
+
+// Moves the mouse along the main chart in small steps (scrubPath() in inpage.js, which says when), as a reader reading
+// a chart that follows the pointer across its plot (a line read day by day), at every width: a finger dragging along a phone's plot
+// shows the same readout. Each step is measured against the page at rest (place() and placeLines() before it): the
+// layout, as for a pick (moved()), and the lines of text around the charts (slides()), which jitter when a label
+// slides as the value before it changes width, or a readout takes another line on some days.
+// { points, steps: [what moved at each step that moved anything] }
+async function scrub(page, events, force) {
+
+  const path = await page.evaluate((f) => window.__rhpProbe.scrubPath(f), force).catch(() => null);
+  if (!path?.points.length) return null;
+  const start = events.length;
+  const steps = [];
+  let said = null;
+  let changes = 0;
+  try {
+    for (const p of path.points) {
+      await page.mouse.move(p.x, p.y);
+      await page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+      const [moved, text] = await page.evaluate((n) => [[...window.__rhpProbe.moved(n, true).filter((m) => !m.text), ...window.__rhpProbe.slides()], window.__rhpProbe.state().text], path.target).catch(() => [[], said]);
+      if (said !== null && text !== said) changes++;
+      said = text;
+      if (moved.length) steps.push(moved);
+    }
+  } finally {
+    await page.mouse.move(0, 0).catch(() => {});
+    for (const e of events.slice(start)) {
+      if (e.kind === "pageerror" || e.kind === "console-error") e.during ??= "moving the pointer along the chart";
+    }
+  }
+  // (a readout that changes at three steps in four or more follows the pointer along the chart: a sentence that slides
+  // there jitters; one that changes less often changes once per mark, and only what a pick counts counts)
+  const continuous = changes >= 0.75 * (path.points.length - 1);
+  const kept = steps.map((moved) => (continuous ? moved : moved.filter((m) => !m.strict))).filter((moved) => moved.length);
+  return { points: path.points.length, continuous, steps: kept };
+}
+
+// Moves the mouse from a slat to its neighbor in small steps (three pairs of the main Plot: the first, the middle and
+// the last), on a page at rest with reduced motion asked for, and notes each pair where the page, between two slats
+// that each show something, goes back for a moment to what it shows with the pointer away: the readout, or the lit
+// slat, flickers in the gap.
+async function glide(page, events) {
+
+  const start = events.length;
+  const pairs = await page.evaluate(() => window.__rhpProbe.neighbors()).catch(() => []);
+  if (!pairs.length) return [];
+  const frame = () => page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+  const state = () => page.evaluate(() => window.__rhpProbe.state());
+  const name = (s) => `slat ${s.index} of ${s.of}${s.name ? ` (${s.name})` : ""}`;
+  const out = [];
+  try {
+    await page.mouse.move(0, 0);
+    await frame();
+    const rest = await state();
+    for (const [a, b] of pairs) {
+      // (from the middle of one slat's largest mark to the middle of the next one's: what each slat shows of its own)
+      const p = await page.evaluate((n) => window.__rhpProbe.markCenter(n), a.target).catch(() => null);
+      const q = await page.evaluate((n) => window.__rhpProbe.markCenter(n, false), b.target).catch(() => null);
+      if (![p?.x, p?.y, q?.x, q?.y].every(Number.isFinite)) continue;
+      await page.mouse.move(p.x, p.y);
+      await frame();
+      const from = await state();
+      const seen = [];
+      for (let k = 1; k <= 12; k++) {
+        await page.mouse.move(p.x + ((q.x - p.x) * k) / 12, p.y + ((q.y - p.y) * k) / 12);
+        await frame();
+        seen.push(await state());
+      }
+      const to = seen.at(-1);
+      // The text, or the look of the slats, blinks when both slats show something other than the rest in it, and a
+      // step between them shows the rest (a slat the page lights at rest shows the rest of its own, and does not blink)
+      const blinks = (key) => from[key] !== rest[key] && to[key] !== rest[key] && seen.slice(0, -1).some((s) => s[key] === rest[key]);
+      const readout = blinks("text");
+      if (readout || blinks("look")) out.push({ from: name(a), to: name(b), readout });
+    }
+  } finally {
+    await page.mouse.move(0, 0).catch(() => {});
+    for (const e of events.slice(start)) {
+      if (e.kind === "pageerror" || e.kind === "console-error") e.during ??= "moving the mouse from a slat to its neighbor";
+    }
+  }
+  return out;
 }
 
 export async function check(options = {}) {
@@ -374,8 +471,17 @@ export async function check(options = {}) {
       // Every slat picked in turn, here and at the page's own breakpoints between this width and the next narrower
       // one checked (a page of its own at each), where a layout that only fits at the widths checked jumps
       const swept = [];
+      let flicker = [];
+      let away = null;
       if (wantInteract) {
         swept.push({ width, ...(await sweep(page, phone, events)) });
+        // what a reader scrolling through a tall chart loses sight of, and (with a mouse) a readout that flickers between slats
+        const scrolled = events.length;
+        away = await page.evaluate((h) => window.__rhpProbe.scrollsAway(h), phone ? PHONE_WINDOW : 900).catch(() => null);
+        for (const e of events.slice(scrolled)) {
+          if (e.kind === "pageerror" || e.kind === "console-error") e.during ??= "scrolling through the chart";
+        }
+        if (!phone && i === 0) flicker = await glide(page, events);
         const next = [...widths].sort((a, b) => b - a).find((w) => w < width);
         const between = next == null ? [] : (await page.evaluate(() => window.__rhpProbe.breakpoints())).filter((b) => b < width && b > next && !widths.includes(b));
         for (const b of between.slice(0, MAX_BREAKPOINTS)) {
@@ -427,7 +533,7 @@ export async function check(options = {}) {
         guarded.push(...(await fresh.evaluate(() => globalThis.__rhpCheck?.findings ?? []).catch(() => [])));
       }
 
-      results.push({ width, index: i, seen, events, guarded, colorFindings, interactions: interactions.map((x) => ({ width, ...x })), unfocused, selection, swept, ms: Math.round(performance.now() - w0) });
+      results.push({ width, index: i, seen, events, guarded, colorFindings, interactions: interactions.map((x) => ({ width, ...x })), unfocused, selection, swept, flicker, away, ms: Math.round(performance.now() - w0) });
       } catch (error) {
         if (error.code !== "page-unsettled") throw error;
         findings.push({ level: "error", code: error.code, message: error.message, fix: "Let finite entry animations finish, honor prefers-reduced-motion for live updates, or increase the check's settleTimeout for a slow machine.", width });
@@ -493,23 +599,58 @@ export async function check(options = {}) {
       findings.push({ ...f, width: r.width });
     }
 
-    // the layout jumping when an interaction runs: the same things moving for several interactions is one finding
+    // the layout jumping when an interaction runs: the same things moving for several interactions is one finding.
+    // Texts that moved with what jumped (by the same amount) are that jump; the others are one text-shift finding for
+    // the width, with each text at the most it moved, or, as the pointer moves along the chart, one jitter finding.
     const jumps = new Map();
+    const texted = { "text-shift": { found: null, by: new Map() }, jitter: { found: null, by: new Map() } };
+    const add = (kind, target, moved, code = "text-shift") => {
+      const other = moved.filter((m) => !m.text);
+      const texts = moved.filter((m) => m.text && !other.some((o) => Math.abs(o.dx - m.dx) <= 1 && Math.abs(o.dy - m.dy) <= 1));
+      if (other.length) {
+        const key = other.map((m) => m.what).join("\n");
+        if (jumps.has(key)) jumps.get(key).more++;
+        else jumps.set(key, { code: "layout-jump", kind, target, moved: other, more: 0 });
+      }
+      if (!texts.length) return;
+      const t = texted[code];
+      if (t.found) t.found.more++;
+      else t.found = { code, kind, target, more: 0 };
+      for (const m of texts) {
+        const was = t.by.get(m.what);
+        if (!was || Math.abs(m.dx) + Math.abs(m.dy) > Math.abs(was.dx) + Math.abs(was.dy)) t.by.set(m.what, m);
+      }
+    };
     for (const x of r.interactions.filter((x) => x.moved?.length)) {
-      const key = x.moved.map((m) => m.what).join("\n");
-      if (jumps.has(key)) jumps.get(key).more++;
-      else jumps.set(key, { code: "layout-jump", kind: x.kind, target: x.target, moved: x.moved, more: 0 });
+      add(x.kind, x.target, x.moved);
     }
     for (const sw of r.swept) {
+      const beside = sw.breakpoint ? ` at ${sw.width}px, beside one of the page's own breakpoints` : "";
+      for (const moved of sw.scrub?.steps ?? []) {
+        add("scrub", `the chart${beside}`, moved, "jitter");
+      }
       for (const j of sw.jumps) {
-        const key = j.moved.map((m) => m.what).join("\n");
-        if (jumps.has(key)) jumps.get(key).more++;
-        else jumps.set(key, { code: "layout-jump", kind: "pick", target: sw.breakpoint ? `${j.target} at ${sw.width}px, beside one of the page's own breakpoints` : j.target, moved: j.moved, more: 0 });
+        add("pick", `${j.target}${beside}`, j.moved);
       }
     }
     for (const j of jumps.values()) {
       findings.push({ ...fromProbe(j, {}), width: r.width });
     }
+    // (a text the scrub found jittering is that finding: a pick that moved it is one of the steps along the chart)
+    for (const what of texted.jitter.by.keys()) {
+      texted["text-shift"].by.delete(what);
+    }
+    for (const { found, by } of Object.values(texted)) {
+      if (!found || !by.size) continue;
+      const moved = [...by.values()].sort((a, b) => Math.abs(b.dx) + Math.abs(b.dy) - Math.abs(a.dx) - Math.abs(a.dy));
+      findings.push({ ...fromProbe({ ...found, moved }, {}), width: r.width });
+    }
+
+    // a readout or a lit slat that goes back to how it is at rest between two slats, as the mouse goes from one to the next
+    if (r.flicker.length) findings.push({ ...fromProbe({ code: "flicker", ...r.flicker[0], more: r.flicker.length - 1 }, {}), width: r.width });
+
+    // the controls or the readout out of view while the reader is in the middle of a tall chart
+    if (r.away) findings.push({ ...fromProbe({ code: "scrolls-away", ...r.away, phone: r.width <= PHONE }, {}), width: r.width });
 
     // taps whose every change of text lies outside the window: one finding, on the last of them (the furthest slat)
     const unseen = r.interactions.filter((x) => x.unseen);
@@ -526,7 +667,7 @@ export async function check(options = {}) {
   const charts = results.flatMap((r) => r.seen.charts.map((c) => ({ width: r.width, ...c })));
   const selectionAudits = results.flatMap((r) => r.selection.tested ? [{ width: r.width, ...r.selection.tested }] : []);
   const interactions = results.flatMap((r) => r.interactions);
-  const swept = results.flatMap((r) => r.swept.map(({ width, breakpoint, slats, jumps }) => ({ width, breakpoint: !!breakpoint, slats, jumps: jumps.length }))).sort((a, b) => b.width - a.width);
+  const swept = results.flatMap((r) => r.swept.map(({ width, breakpoint, slats, reached, jumps, scrub }) => ({ width, breakpoint: !!breakpoint, slats, reached, jumps: jumps.length, scrubbed: scrub ? { points: scrub.points, moved: scrub.steps.length } : null }))).sort((a, b) => b.width - a.width);
   timings.widths = Object.fromEntries(results.map((r) => [r.width, r.ms]));
 
   return finish({ ...base, browser: launched.name, findings, charts, interactions, interactedAt: wantInteract ? widths[0] : null, selectionAudits, swept, screenshots, timings, started });
@@ -544,7 +685,7 @@ function finish({ findings, started, timings, ...rest }) {
       if (f.width != null && !had.widths.includes(f.width)) had.widths.push(f.width);
       continue;
     }
-    merged.set(key, { level: f.level, code: f.code, message: f.message, fix: f.fix, width: f.width ?? null, widths: f.width != null ? [f.width] : [] });
+    merged.set(key, { level: f.level, code: f.code, message: f.message, fix: f.fix, see: SEE[f.code] ?? null, width: f.width ?? null, widths: f.width != null ? [f.width] : [] });
   }
 
   const list = [...merged.values()].sort((a, b) => LEVELS[a.level] - LEVELS[b.level]);