@bezda/rhp-mcp 0.1.6 → 0.1.7

package/skill/references/forms.md

@@ -30,7 +30,7 @@ rhp draws all of these; the recipe named has the technique, not the design.
 | a route or a sequence in space (stops, stages, a course, a river) | one line with its stations in order | `stacked-100` (its key is a metro line), `gantt`, `slope` |
 | a document the reader knows (a receipt, a ledger, a timetable, a scoreboard, a league table, a menu) | the chart laid out as that document, its lines the slats | `lollipop`, `waterfall`, `sparklines`, `live` |
 | a place (states, districts, seats in a hall, a pitch, a shelf) | a grid of tiles that echoes the place | `heatmap`'s composition (a Plot of rows, each a Plot of Cells) |
-| an instrument that measures it (a thermometer, a gauge, a ruler, a clock, a scale) | the instrument's own scale and pointer | a `Scale` drawn your own way, a Tick as the pointer, `radial-bars` |
+| an instrument that measures it (a thermometer, a gauge, a ruler, a clock, a scale) | the instrument's own scale and pointer | a `Scale` drawn your own way, a Tick as the pointer, `radial-bars`, `tape` (a ruler's rules and numerals along a whole cut into lengths) |
 
 - The native form is the hero, and the numbers still have to be read: print each value on or beside its mark, since a ring, an outline or a tile is read less exactly than a bar on a shared baseline.
 - When an exact comparison is the whole point, keep bars from one baseline and let the subject show in how the marks are drawn (design.md section 2).
@@ -76,7 +76,7 @@ The headline will be its answer.
 | see a value over two categories | a grid of values (day by hour) | heatmap | `heatmap` |
 | see two groups across ordered bands | two values per band | pyramid | `pyramid` |
 | see things known by their shape at their size | one value per item, each item with an outline | silhouettes to scale | `silhouettes` |
-| see how a day or another cycle splits | parts that add up to the cycle | a dial | `dial` |
+| see how a day or another cycle splits | parts that add up to the cycle | a dial, or a tape cut into lengths | `dial`, `tape` |
 | follow one part of a total over periods, and count it | parts per period that add up | unit stacks with the part at the foot | `unit-stack` |
 | see a schedule and its progress | tasks with start, end, progress | gantt | `gantt` |
 | follow prices with their range | open, high, low, close per day | candlestick | `candlestick` |
@@ -150,6 +150,7 @@ The interaction listed is the recipe's; interaction.md has the others.
 | `pyramid` | two sides of a population by age | 2 | an age picked lights everyone that age or older |
 | `silhouettes` | ten towers to scale, each in its own outline, on one street | 1, vertical, `shape()` per row | readout of the tower picked, its level carried to the tallest |
 | `dial` | the parts of a day around a 24-hour dial | 10 + 9 | a hand that turns to the part picked, a readout in the hub |
+| `tape` | the parts of a day laid end to end along a tape measure cut into three 8-hour lengths | 2 (an `overlap` Plot of Bars from each part's start to its end), a Chart per length + 9 | readout of the part picked, its key lines picking too |
 | `log-line` | ten years of a price on a log scale with a line at each doubling, its falls shaded | 5 (the falls as one filled Line) + 8 + 9, log scale | a crosshair readout by pointer, tap, drag or keys |
 | `unit-stack` | monthly spending as piles of coins, one part at the foot of every pile | 2 (the picked part and the rest), units by a mask | a picker of parts |
 | `gantt` | tasks over weeks, progress, today | 2 + 8 + 9 | readout of a task and its dependencies |

package/skill/references/interaction.md

@@ -1,6 +1,6 @@
 # Interaction
 
-How to pick the one interaction that serves a chart's story when the user names none, and how to build any interaction a user asks for.
+How to choose interaction behavior and presentation for the reader's task, and how to build an interaction a user asks for.
 rhp keeps no interaction state: the app holds it in a signal, passes it to the Plot as data, and the slat shows it.
 
 Contents:
@@ -71,10 +71,14 @@ The page's CSS styles what sits around the chart (the poster, the readout, butto
 
 ## 1. Pick the interaction from the story
 
-When the user names an interaction, build exactly that, from the section that matches it.
-When they name none, find the chart's story here and add that one interaction.
+When the user names an interaction, preserve the behavior they requested and use the sections below for the techniques it needs.
+When they name none, decide what the reader should be able to inspect, compare or change, and what visible response helps them do it.
+The table offers working examples, not fixed pairings between stories, chart types and controls.
+Reuse reliable state and event handling, while choosing the controls, feedback, placement and transitions for this chart.
+The same selection state can drive an inline annotation, a comparison or a detail reveal; a separate readout band is only one way to present it.
+Keep a familiar pattern when it fits the task and design; difference alone is not a reason to change it.
 
-| The story | The interaction | Section | Recipes that have it |
+| The reader's task | Example interaction | Section | Recipes demonstrating the technique |
 |---|---|---|---|
 | compare items: which is bigger, by how much | readout of the slat under the pointer, finger or focus, with the fields the bars do not show | 2 | bar, column, pyramid, donut |
 | a ranking whose order depends on the measure | sort toggle | 3 | grouped-bars, bullet, dumbbell |

package/skill/references/pitfalls.md

@@ -95,7 +95,7 @@ Start from a recipe, never from what another library does.
 6. **Numbers show long decimals while they move** [26]: in the JS version (`animate`) values are fractional mid-way; round what you print.
 7. **Bars vanish, or a slat jumps to the first place, after the data changes** [4]: a `style` given as a string that changed (or turned to nothing) replaced the variables rhp keeps in the element's style.
    Give a slat root's changing style as an object: `style=${() => ({ "--n": d.n })}`.
-   Blocks need the same workaround on published rhp 2.0.2; current source fixes Block style replacements for the upcoming 2.0.3 release.
+   Blocks need the same workaround only on rhp 2.0.2; 2.0.3 fixed Block style replacements.
 8. **`animate` is on, but a value still jumps**: the JS version never moves a group given as a function of the row (`v=${(d) => ...}`). Give the changing numbers as a list (`v=${() => values()}`), a single value or a field of `rows`.
 9. **A race stops at each step, or a live feed's marks stop between readings**: to play back data you have, never step through it with a timer; move a playhead on every frame, give the Plot the values interpolated between the steps around it, and keep the JS version's default 150 ms, so the marks glide and Pause leaves them between steps (interaction.md section 10). For a live feed, whose next value is not known yet, ease linear into each new reading over a little more than one interval (`ease: "linear"`, 1.5 intervals); with ease-out or a shorter duration the marks rest between readings.
 10. **Marks trail behind data that changes rapidly or continuously** (a live feed, a slider or drag that drives the data, a play button, a bar chart race): in the default CSS version every new value restarts a CSS transition from wherever the mark is, so under steady change the marks always lag, and Safari can stall transitions that input events retarget. Give the Plot `animate` for the data groups that change (`animate=${["value"]}`, or `animate=${true}`), or the Chart when the scale moves with the data: rhp's JS clock carries each move into the next value. Measured with a slider changing the data every frame: the CSS version trailed the data by 10 points of 100, the JS version by 6.
@@ -116,12 +116,13 @@ Start from a recipe, never from what another library does.
 
 ## The layout jumps when the reader interacts
 
-The checker warns (`layout-jump`) when a control or the chart moves after one of its interactions; these are the usual causes. It tries only some controls, so try every one yourself and compare.
+The checker warns (`layout-jump`) when a control or the chart moves after one of its interactions, (`text-shift`) when a text that still says the same thing moves, and (`jitter`) when a text moves as the pointer goes along a chart that follows it (a line read day by day); these are the usual causes. It tries only some controls, so try every one yourself and compare.
 
 1. **Text that changes with a switch moves the controls below it** (a headline or a dek per question): stack every version in one grid cell (a wrapper with `display: grid`, each version at `grid-area: 1 / 1`, `visibility: hidden` except the current one), so the cell is always as tall as the longest version.
    Align the versions to the cell's end (`align-self: end`) when the chart is below them, so a short version leaves no empty line above the chart.
 2. **A readout that wraps on a phone pushes the chart down**: give it a `min-height` for its longest text at 320px (`min-height: 2lh`, or `3lh`), counting the longest numbers and dates that gain a year ("Jan 4, 2027").
 3. **Numbers that change width shift what follows them**: use `font-variant-numeric: tabular-nums`, and give a column of numbers a fixed room; in an "auto" end room, align them across slats with `justify-self: stretch` and `justify-content: flex-end` on the label.
+   In a readout, tabular figures alone are not enough when the number of digits changes ("$654" to "$84,176") or a date's month names differ in width: start each part where nothing before it changes width (a grid with a column per part, or each part on its own line), or give the value a box with a `min-width` in `ch` for the longest value it can show, right-aligned. A label or a unit after a value on the same line ("8,101 tons in 2026") slides at every step of a pointer moving along the chart.
 4. **Every bar slides when a slat is lit**: the lit name turns bold in a `room.start` of "auto", which measures the widest name again and moves the plot.
    Change only the lit name's color, or keep its bold width at rest: room in px, or the bold text drawn hidden under the name (`.name::after { content: attr(data-name); display: block; height: 0; overflow: hidden; visibility: hidden; font-weight: 700; }`, with `data-name=${() => d.name}` on the Label; measured: the bars held still at 1280px, where a plain bold name moved them 10.8px).
 5. **A button whose text changes (Play, Pause) moves its neighbors**: stack both texts in one grid cell, the hidden one `visibility: hidden`, so the button is always as wide as the longer one.

package/skill/scripts/add-download.mjs

@@ -0,0 +1,33 @@
+// Adds the poster's fit-to-screen and PNG download block to a standalone HTML page, before </body>.
+// The block is the same in every recipe; this copies it from one, so the agent never reads it.
+// Usage: node scripts/add-download.mjs <page.html>
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const page = process.argv[2];
+if (!page || !fs.existsSync(page)) {
+  console.error("Usage: node scripts/add-download.mjs <page.html> (the page must exist)");
+  process.exit(1);
+}
+
+const html = fs.readFileSync(page, "utf8");
+if (html.includes('id="poster-download-script"')) {
+  console.log(`${page} already has the download block.`);
+  process.exit(0);
+}
+if (!/<\/body>/i.test(html)) {
+  console.error(`${page} has no </body>: add the block by hand, from <style id="poster-download-styles"> to </body> of any recipe.`);
+  process.exit(1);
+}
+
+const recipe = fs.readFileSync(path.join(here, "../recipes/bar.html"), "utf8");
+const start = recipe.indexOf('<style id="poster-download-styles">');
+const end = recipe.lastIndexOf("</body>");
+const block = recipe.slice(start, end);
+
+// We insert before the last </body>, so a </body> inside a script or a comment is left alone.
+const at = html.toLowerCase().lastIndexOf("</body>");
+fs.writeFileSync(page, html.slice(0, at) + block + html.slice(at));
+console.log(`Added the fit-to-screen and download block to ${page} (${block.length} characters). The poster needs the class "poster" for the block to find it.`);

package/src/check/README.md

@@ -19,14 +19,26 @@ The CLI (`rhp-mcp check`) and the MCP tool (`rhp_check`) print the same report.
    It runs at each width checked, and on a page of its own at each of the page's own breakpoints between that width and the next narrower one (both sides of each `min-width` or `max-width` of its media queries, up to six per width), where a layout made only for the widths checked jumps: a readout that takes another line for one slat, just past the width where the poster's padding changes.
    With reduced motion a pick shows at once, so two frames after each are enough: the sweep takes a few seconds per width.
    Widths between those (a jump only from 322 to 338px) are not swept; a readout that keeps its height by design (one line, or the same number of lines whatever it says) has none.
+   While the sweep picks, the texts around the charts that a pick rewrites are noted: that is the readout.
+   When the main chart draws a Line or an Area, a layer over the plot takes the pointer (the main Plot's first slat cannot be pointed at) or the main Plot has one or two slats (a line per series), the reader moves along the chart, and the sweep first **scrubs** it (`scrub()` in index.js): the mouse goes through 41 points across the plot's middle, along the scale of the plot that draws the line or the area (or of a Plot of one or two slats) and across the main Plot's slats otherwise, at every width (a finger dragging along a phone's plot shows the same readout).
+   After each point the layout is measured as for a pick, and so is every line of text around the charts, each text node on its own (its first line box, in the box it floats in), against the page with the pointer away: a text that still says the same thing and moved jitters, and so does one whose words changed and that kept none of its edges (its start, its end or, on one line, its middle) where it was.
+   When the page's text changes at three steps in four or more, the readout follows the pointer along the chart (a line read day by day), and a whole sentence that slides counts, though a pick lets one slide. When it changes less often, it changes once per mark crossed (bubbles that a layer covers), and a slide along the line counts as for a pick: only for a text that still says the same thing, and not for a sentence. A text that moves up or down (a readout's name centered beside a description that takes another line) counts either way.
+   The report says when no slat could be picked, rather than that nothing moved.
+   Then, when the main chart is taller than three quarters of the window (664px at a phone's width), the page is scrolled so that the chart's middle is in the middle of the window, and the controls of the chart's section (not its fit and download icons) and the readout are noted when all of them are out of view.
+   At the first width, with a mouse, the **glide** (`glide()` in index.js) then moves the pointer from a slat to its neighbor in twelve steps, for the first two slats, two in the middle and the last two, and reads after each step the page's visible text and how the slats are drawn (two hashes).
+   When both slats show something of their own and a step between them shows the text, or the slats, as they are with the pointer away, the readout or the lit slat flickers in the gap.
 6. **Interact** (interact.js), on a fresh page with motion on, as a reader gets it.
    At the first width: point at a mark of the first, middle and last slat of the largest chart (in its first Plot that takes the pointer), and of the slat whose edge Label is widest when it is wider than theirs (lit, a name that gets bolder can make room "auto" wider); click each button and toggle, change each range and select, press an arrow key on a slider (`role=slider` first, else a range), and press Tab and the arrow keys when slats take focus.
    Then Tab through the page (up to 8 stops), and compare a screenshot of each stop's box (with 12px around it for an outline) focused and blurred: under 20 pixels that change (by more than 24 in all three channels) is focus that shows nothing.
    At a phone's width, in a window 664px tall (what Safari shows of a page on a 390 by 844 iPhone): tap a mark of the first and the last slat, and note when the tap changed text the reader can see (wrote it, or showed it) but all of that text lies outside the window while the tapped slat is in it; a style the tap changed in view (the tapped bar lit) does not tell the reader what the text says.
    A point on a mark is one that reaches its slat: on its marks, inside an SVG shape in it (`isPointInFill`, for a donut's wedge that fills a small part of its box), or at a Label's center. When none does and the slat takes the pointer, something covers it, and the step says "could not reach slat N" and what covers it instead of pointing at a corner of a box.
-   After each step the guard reads again what the slats read once (stale values, static charts), and the pass notes what moved on the page (the layout jumps).
+   After each step the guard reads again what the slats read once (stale values, static charts), and the pass notes what moved on the page (the layout jumps, and the texts that moved).
+   A step that is not a pick (a button, a range, a select, a key on a slider) is also read five times as it runs, every 200ms, so a text that jitters while Play runs the years counts even when it is back in place at the end.
+   A text is measured in the box it floats in when it floats (fixed, sticky or absolute: a readout pinned to the window, a tooltip that follows the pointer), else on the page, and only when its own text (its text nodes, not its children's) is the same as before: a value that changed may change its size, but the label beside it stays put.
+   A text that moves by as much as something that jumped is reported with that jump, not again.
    Controls go by their accessible name, slats by their Labels' text as the reader sees it (not hidden text, nor screen-reader text).
 7. **Report** (findings.js turns probe results into findings, report.js writes the text): errors first, then warnings, then notes, what passed, the interactions (with one line for the sweep: how many slats, and every width it picked them at) and the screenshots.
+   A finding whose fix the skill's references explain names that section on a line of its own (`See: pitfalls.md, "The layout jumps when the reader interacts"`, from `SEE` in findings.js), so an agent whose fix did not hold reads that section, not the whole file; the headings it names must stay as they are.
    When pointing at slats (and tapping them) changes nothing but buttons or a slider change the chart, the report says so in one line.
    When nothing changes and the page has no controls, it says "no interaction found (fine when none was asked for)" in one line, instead of a line per slat (slats that others cover, in an overlap Plot with no interaction, are left out of it, as long as one slat was reached).
 
@@ -141,8 +153,12 @@ The tests read this table: every code in it must have a chart in `test/broken/`
 | Code | Level | What triggers it | Fix it gives |
 |---|---|---|---|
 | `unnamed-control` | warning | A button, input, select or control with a role (slider, switch, tab...) that has no accessible name: no text, aria-label, aria-labelledby or label, so a screen reader says only what kind of control it is. | Visible text, an aria-label on an icon button, or a `<label>` around an input or a select. |
-| `layout-jump` | warning | An interaction of the pass, or a pick of the sweep, moves a control other than the one it used, or a chart's top, by more than 2px (a readout that takes a second line, a button whose label changes its width); or, while it lights a slat (pointing, a tap, the keyboard), it moves an edge of the plot (a lit name that gets bolder makes room "auto" wider, and every bar slides) or the end of the chart's section (its outermost box in the page: a readout after the chart that takes a second line), by more than 2px. A control in a slat that moves with its slat (rows sorted or removed) is left out, and so are fixed and sticky elements. | A box that keeps its size: a readout on one line with an ellipsis, or a min-height for its longest text; buttons that keep their width; names that keep their weight and size when lit, or room in px. |
+| `layout-jump` | warning | An interaction of the pass, or a pick of the sweep, moves a control other than the one it used, or a chart's top, by more than 2px (a readout that takes a second line, a button whose label changes its width); or, while it lights a slat (pointing, a tap, the keyboard), it moves an edge of the plot (a lit name that gets bolder makes room "auto" wider, and every bar slides) or the end of the chart's section (its outermost box in the page: a readout after the chart that takes a second line), or it changes the size of a box around the charts that has a background, a border or a shadow and holds no chart (a readout's card that shrinks to its text, a legend's panel), by more than 2px. A control in a slat that moves with its slat (rows sorted or removed) is left out, and so are fixed and sticky elements; a box that floats (fixed or absolute: a tooltip) is left out. | A box that keeps its size: a readout on one line with an ellipsis, or a min-height for its longest text; a card or a panel with a fixed width, or a min-width and min-height for its longest content; buttons that keep their width; names that keep their weight and size when lit, or room in px. |
+| `text-shift` | warning | An interaction of the pass, a pick of the sweep, or a moment while a control runs (Play), moves a text around the charts whose own text did not change, by more than 2px, inside the box it floats in or on the page: a label after a value that got wider, a unit after a number in proportional figures, a readout's lines that change order, a legend that reflows, a column that resizes to its widest value. One finding per width, each text at the most it moved; a text that moved with a layout jump is that jump. | Numbers in tabular figures in a column of their own or with a min-width in ch, right-aligned; labels in their own column (a grid), not after a value on one line; lines in a fixed order; a min-height for the readout's longest text. |
+| `jitter` | warning | While the scrub moves the pointer along the chart, a text around the charts moves by more than 2px against the page at rest, inside the box it floats in or on the page: a label or a unit after a value that changed width ("8,101 tons in 2026", where " in 2026" slides), a phrase after a date whose month names differ in width, a sentence whose values change, a line that wraps on some days and not others. One finding per width, each text at the most it moved, named with the line it is part of; a text that moved with a layout jump is that jump, and a text found here is left out of the width's text-shift. | 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. Values in tabular figures with a min-width in ch for the longest value they can show, right-aligned when they end a column; the readout on its lines whatever it says (nowrap, or a min-height). |
+| `flicker` | warning | With a mouse, between two neighboring slats that each show something of their own, a step of the glide shows the page's text, or the slats, as they are with the pointer away: the pick clears in the gap between two bars and comes back, so the readout or the lit slat blinks as the reader moves along the chart. | Keep the pick while the pointer is between slats: change it only on another slat, clear it only when the pointer leaves the chart or the poster. |
 | `out-of-view` | warning | At a phone's width, in a window 664px tall, a tap on a slat that is in the window changes text the reader can see, and all of it lies outside the window (above, below or beside it), even when the tap lights the slat in view: a readout above a tall chart, when the last slat is tapped. | A readout next to the slat (in the slat, or in a Label of it), or one kept in view (`position: sticky`, with a z-index over the plot's 1). |
+| `scrolls-away` | info | The main chart is taller than three quarters of the window (664px at a phone's width), and with its middle in the middle of the window, all of its section's controls (not its fit and download icons), or all of its readout (the texts a pick rewrites), are out of view: the reader has to scroll back to change the year or to read the values. A note: keeping them in view is usually better, not always. | Consider `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, and `scroll-margin-top` on the slats so a picked slat is never under it. |
 | `focus-invisible` | warning | Tab reaches a slat or a control, and a screenshot of its box (with 12px around it) focused and blurred differ in under 20 pixels: `outline: none` with nothing in its place. | Keep the focus ring, or a `:focus-visible` style that shows in its place (on a slat, in the slat type's css). |
 
 ### Conditional selection repair

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":

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]);