@bezda/rhp-mcp 0.1.0 → 0.1.1

package/src/check/README.md

@@ -15,6 +15,10 @@ The CLI (`rhp-mcp check`) and the MCP tool (`rhp_check`) print the same report.
 5. **Probe** (inpage.js runs in the page; colors.js reads screenshots): layout, text, controls, rhp's CSS, colors.
    The report's screenshot is taken first, before any probe hides or restyles anything; then the screenshots the colors are read from.
    A slat's own transition on a block is read last, with motion asked for again (with reduced motion rhp turns every block's transition off).
+   Before that, the **sweep** (`sweep()` in index.js): every slat of the main Plot (up to 32, spread evenly) is picked in turn, by a tap at a phone's width and the mouse elsewhere, and what moved outside the plot is noted (as below).
+   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.
 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.
@@ -22,13 +26,21 @@ The CLI (`rhp-mcp check`) and the MCP tool (`rhp_check`) print the same report.
    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).
    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 and the screenshots.
+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.
    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).
 
 ### Screenshots, and the page they move
 
 A full-page screenshot of a page taller than the window makes Chromium lay the page out at another size for a moment (1 by 1 px, after most captures), so the page's resize, ResizeObserver and matchMedia handlers run: a chart whose orientation follows the width turns and turns back.
+The checker waits up to ten seconds for fonts, finite entry animations and two unchanged DOM frames, and checks the result of that wait.
+`settleTimeout` overrides this budget in `check()` and the MCP tool.
+The CLI exposes the same setting as `--settle-timeout <ms>`.
+The CLI and MCP accept 100 to 30,000ms; the MCP's overall 50-second deadline still applies.
+An unfinished wait produces `page-unsettled` instead of layout or color conclusions from a moving page.
+That holds for the page that is measured, with reduced motion asked for, where a live feed or a race changes in steps and comes to rest between them.
+The interaction pass runs with motion on, as a reader gets the page, and there a page that moves on its own never comes to rest: it waits up to three seconds for fonts and entry animations, half a second after each screenshot, and is tried as it moves (`clean-moving.html`).
+Geometry and text colors are read after the initial screenshots have settled, so responsive capture handlers cannot leave stale coordinates in the color probes.
 So every screenshot goes through `capture()` (index.js), which lets the page come to rest again when the capture made it change (`calm()` in inpage.js), and `hide()` and `show()` put back only the style properties they set, never a whole `style` attribute saved before (that undid what the page did meanwhile and left such a chart drawn wrong).
 
 ## Levels
@@ -100,6 +112,7 @@ The tests read this table: every code in it must have a chart in `test/broken/`
 |---|---|---|---|
 | `no-chart` | error | No `.rhp-chart` in the page (not reported when the code can't load, since that reason is reported instead). | Render into an element the page has, or fix the errors above. |
 | `empty-plot` | error | A Plot with no slats shown (an empty overlap Plot is fine: a readout drawn only while pointing). | Give the Plot its data. |
+| `page-unsettled` | error | Fonts, finite animations or DOM changes did not settle within the measurement budget. | Finish entry animations, honor reduced motion for continuous updates, or increase `settleTimeout` for a slow machine. |
 | `small-plot` | error | A plot under 40px along its value axis, or slats under 2px thick (3px slats are fine: a histogram's many bins, a line chart's slats for pointing). | A height or an aspect, a thickness, or fewer rows. |
 | `collapsed-chart` | error | A chart whose plot is under 2px wide: it sits in a flex row, an inline-block or a float that shrinks it to its room. | `flex: 1; min-width: 0`, or a box with a width. |
 | `plot-outside-chart` | error | A `.rhp-plot` with no `.rhp-chart` around it: no scale and none of rhp's CSS. | Put the Plot in a Chart. |
@@ -128,7 +141,7 @@ 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 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 by more than 2px (a lit name that gets bolder makes room "auto" wider, and every bar slides). 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), 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. |
 | `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). |
 | `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). |
 

package/src/check/findings.js

@@ -4,7 +4,7 @@
 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" };
+const DOING = { hover: "pointing at", tap: "tapping", click: "clicking", input: "setting", select: "setting", key: "pressing", pick: "picking" };
 
 // 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 ");

package/src/check/index.js

@@ -16,16 +16,19 @@
 //   outDir    where the screenshots go (a folder in the OS temp dir by default)
 //   guard     check how rhp is used, in the page (true by default; false is for proving the guard draws nothing)
 //   freeze    take the screenshots with CSS animations stopped (an endless one at its start), for comparing them
+//   settleTimeout  readiness budget per settling wait in ms (10000 by default); an unsettled page fails explicitly
 //   offline   fetch nothing from the web (fonts fall back): for tests that must not depend on the network
 //   browser   a Playwright Browser to use instead of launching one (it is left open)
 //   debug     also save the screenshots the color probes read (as drawn, with the text hidden, with the marks hidden)
 //
-// Result: { ok, file, format, rhpVersion, browser, findings, charts, interactions, interactedAt, screenshots, timings,
+// Result: { ok, file, format, rhpVersion, browser, findings, charts, interactions, interactedAt, swept, screenshots, timings,
 // text }
 //   ok            no finding is an error
 //   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
 //   screenshots   [{ width, dark, hover, path }]
 //   text          the report as plain text (what the CLI prints)
 import fs from "fs";
@@ -51,6 +54,12 @@ const LEVELS = { error: 0, warning: 1, info: 2 };
 const PHONE = 600;
 // The height of what a phone shows of a page (Safari on a 390 by 844 iPhone, its bars shown): where the taps are tried
 const PHONE_WINDOW = 664;
+// With motion on, the longest wait for a page to come to rest after it opens, and after a screenshot, in ms: a page
+// that moves on its own never does
+const MOVING_WAIT = 3000;
+const MOVING_CALM = 500;
+// The most breakpoint widths a width sweeps besides itself
+const MAX_BREAKPOINTS = 6;
 
 const shortHash = (text) => crypto.createHash("sha1").update(text).digest("hex").slice(0, 8);
 
@@ -80,6 +89,39 @@ function source({ file, code, format }) {
   return { file: abs, text: code };
 }
 
+// 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.
+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());
+  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;
+    const name = `slat ${s.index} of ${s.of}${s.name ? ` (${s.name})` : ""}`;
+    const before = events.length;
+    try {
+      if (touch) await page.touchscreen.tap(point.x, point.y);
+      else await page.mouse.move(point.x, point.y);
+      await page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+    } catch {
+      continue;
+    }
+    for (const e of events.slice(before)) {
+      if (e.kind === "pageerror" || e.kind === "console-error") e.during ??= `${touch ? "tap" : "hover"} ${name}`;
+    }
+    const moved = await page.evaluate((n) => window.__rhpProbe.moved(n, true), s.target).catch(() => []);
+    if (moved.length) jumps.push({ target: name, moved });
+  }
+  if (!touch) await page.mouse.move(0, 0);
+  return { slats: slats.length, jumps };
+}
+
 export async function check(options = {}) {
 
   const started = performance.now();
@@ -89,6 +131,10 @@ export async function check(options = {}) {
   const dark = !!options.dark;
   const guard = options.guard !== false;
   const wantInteract = options.interact !== false;
+  const settleTimeout = options.settleTimeout ?? 10000;
+  const requireRest = (result) => {
+    if (!result.rest) throw Object.assign(new Error(`The page did not settle within ${settleTimeout}ms; layout and color measurements would be unreliable.`), { code: "page-unsettled" });
+  };
 
   const src = source(options);
   if (src.error) return finish({ file: options.file ?? null, format: options.format ?? null, findings: [{ level: "error", code: "no-file", message: src.error, fix: "Pass the path of the chart's file (an .html page, a .jsx component or a .js module)." }], timings, started });
@@ -190,7 +236,9 @@ export async function check(options = {}) {
   const isLocal = (u) => u.startsWith("file:") || u.startsWith(ORIGIN);
 
   // A page with the chart, the probe installed and at rest (in a window of another size when asked); what the page
-  // throws or prints goes to events
+  // throws or prints goes to events. The page that is measured, with reduced motion, must come to rest. With motion on
+  // (the interaction pass), a page that moves on its own (a live feed, a race that plays) never does: it gets a few
+  // seconds for its fonts and entry animations, and is then tried as it moves, as a reader gets it.
   const open = async (context, events, reducedMotion, viewport = null) => {
     const page = await context.newPage();
     if (viewport) await page.setViewportSize(viewport);
@@ -212,21 +260,25 @@ export async function check(options = {}) {
     await page.route("**/*", route);
     await page.goto(format === "html" ? pathToFileURL(file).href : ORIGIN + "/", { waitUntil: "load", timeout: 20000 }).catch((e) => events.push({ kind: "pageerror", text: "The page did not finish loading: " + String(e.message).split("\n")[0] }));
     await page.evaluate(install);
-    await page.evaluate(() => window.__rhpProbe.settle(2000));
+    const measured = reducedMotion === "reduce";
+    const rest = await page.evaluate((max) => window.__rhpProbe.settle(max), measured ? settleTimeout : Math.min(settleTimeout, MOVING_WAIT));
+    if (measured) requireRest(rest);
     return page;
   };
 
   // A screenshot, after which the page comes to rest again: taking one can lay the page out at another size for a
-  // moment (see calm() in inpage.js)
-  const capture = async (page, opts) => {
+  // moment (see calm() in inpage.js). In the interaction pass (moving: true) the page may move on its own, so it waits
+  // briefly and goes on.
+  const capture = async (page, opts, moving = false) => {
     const since = await page.evaluate(() => window.__rhpProbe.resized());
     const png = await page.screenshot(opts);
-    await page.evaluate((n) => window.__rhpProbe.calm(n), since).catch(() => {});
+    const rest = await page.evaluate(([n, max]) => window.__rhpProbe.calm(n, max), [since, moving ? Math.min(settleTimeout, MOVING_CALM) : settleTimeout]);
+    if (!moving) requireRest(rest);
     return png;
   };
 
   // The screenshot the report gives, cropped to what the page draws
-  const save = async (page, width, suffix) => {
+  const save = async (page, width, suffix, moving = false) => {
     const box = await page.evaluate(() => window.__rhpProbe.contentBox());
     const size = await page.evaluate(() => ({ w: document.documentElement.scrollWidth, h: document.documentElement.scrollHeight }));
     const pad = 16;
@@ -237,7 +289,7 @@ export async function check(options = {}) {
       height: Math.min(size.h, Math.ceil(box.bottom + pad)) - Math.max(0, Math.floor(box.top - pad)),
     };
     const png = path.join(outDir, `${name}-${width}${dark ? "-dark" : ""}${suffix ? "-" + suffix : ""}.png`);
-    await capture(page, { type: "png", path: png, fullPage: true, animations: options.freeze ? "disabled" : "allow", ...(clip && clip.width > 0 && clip.height > 0 ? { clip } : {}) });
+    await capture(page, { type: "png", path: png, fullPage: true, animations: options.freeze ? "disabled" : "allow", ...(clip && clip.width > 0 && clip.height > 0 ? { clip } : {}) }, moving);
     screenshots.push({ width, dark, hover: suffix === "hover", path: png });
   };
 
@@ -249,12 +301,11 @@ export async function check(options = {}) {
       const context = await browser.newContext({ viewport: { width, height: 900 }, deviceScaleFactor: phone ? 2 : 1, hasTouch: phone, colorScheme: dark ? "dark" : "light" });
       const events = [];
       const w0 = performance.now();
+      try {
 
       // The page is measured and pictured with reduced motion asked for: rhp's moves end at once, and a page that moves
       // on its own (an autoplay, a live feed) waits or changes in steps, so the screenshots show what was measured
       const page = await open(context, events, "reduce");
-      const seen = await page.evaluate(() => window.__rhpProbe.measure());
-      const items = await page.evaluate(() => window.__rhpProbe.colorItems());
 
       // first, before any probe hides or restyles anything
       await save(page, width, "");
@@ -266,6 +317,10 @@ export async function check(options = {}) {
         return decode(png);
       };
       const drawn = keep(await shot(), "drawn");
+      // Full-page captures can trigger responsive layout handlers. Read geometry
+      // and text colors only after those handlers have come to rest again.
+      const seen = await page.evaluate(() => window.__rhpProbe.measure());
+      const items = await page.evaluate(() => window.__rhpProbe.colorItems());
       await page.evaluate(() => window.__rhpProbe.hide("text"));
       const noText = keep(await shot(), "no-text");
       let noMarks = null;
@@ -276,6 +331,26 @@ export async function check(options = {}) {
       await page.evaluate(() => window.__rhpProbe.show());
       const colorFindings = [...textContrast(items, noText, 1), ...(noMarks ? faintMarks(items, drawn, noMarks, 1) : []), ...colorBlind(items, noMarks, 1)];
 
+      // 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 = [];
+      if (wantInteract) {
+        swept.push({ width, ...(await sweep(page, phone, 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)) {
+          let at = null;
+          try {
+            at = await open(context, events, "reduce", { width: b, height: 900 });
+            swept.push({ width: b, breakpoint: true, ...(await sweep(at, phone, events)) });
+          } catch (error) {
+            if (error.code !== "page-unsettled") throw error;
+          } finally {
+            await at?.close();
+          }
+        }
+      }
+
       // with reduced motion rhp turns every block's transition off, so a slat's own is read with motion on
       await page.emulateMedia({ reducedMotion: "no-preference" });
       seen.found.push(...(await page.evaluate(() => window.__rhpProbe.transitions())));
@@ -289,7 +364,7 @@ export async function check(options = {}) {
       const loaded = !events.some((e) => e.kind === "pageerror" && /^The page did not finish loading/.test(e.text));
       if (wantInteract && loaded && (i === 0 || phone)) {
         const fresh = await open(context, events, "no-preference", phone ? { width, height: PHONE_WINDOW } : null);
-        const pass = { events, capture: (opts) => capture(fresh, opts), shoot: (suffix) => save(fresh, width, suffix) };
+        const pass = { events, capture: (opts) => capture(fresh, opts, true), shoot: (suffix) => save(fresh, width, suffix, true) };
         const passes = [];
         if (i === 0) passes.push(await interactionPass(fresh, pass));
         if (phone) passes.push(await interactionPass(fresh, { ...pass, taps: true }));
@@ -302,8 +377,13 @@ 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, ms: Math.round(performance.now() - w0) });
-      await context.close();
+      results.push({ width, index: i, seen, events, guarded, colorFindings, interactions: interactions.map((x) => ({ width, ...x })), unfocused, swept, 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 });
+      } finally {
+        await context.close();
+      }
     }));
   } finally {
     if (!options.browser) await browser.close();
@@ -364,6 +444,13 @@ export async function check(options = {}) {
       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 });
     }
+    for (const sw of r.swept) {
+      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 });
+      }
+    }
     for (const j of jumps.values()) {
       findings.push({ ...fromProbe(j, {}), width: r.width });
     }
@@ -378,9 +465,10 @@ export async function check(options = {}) {
 
   const charts = results.flatMap((r) => r.seen.charts.map((c) => ({ width: r.width, ...c })));
   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);
   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, screenshots, timings, started });
+  return finish({ ...base, browser: launched.name, findings, charts, interactions, interactedAt: wantInteract ? widths[0] : null, swept, screenshots, timings, started });
 }
 
 // Merges the same finding at several widths, sorts errors first, and writes the report
@@ -410,6 +498,7 @@ function finish({ findings, started, timings, ...rest }) {
     charts: rest.charts ?? [],
     interactions: rest.interactions ?? [],
     interactedAt: rest.interactedAt ?? null,
+    swept: rest.swept ?? [],
     screenshots: rest.screenshots ?? [],
     timings,
   };

package/src/check/inpage.js

@@ -22,12 +22,13 @@ export function install() {
   // Waits for fonts, two frames, the animations that end (CSS transitions, a slat's own animations) and a DOM that
   // stays still for two frames (the JS version moves numbers on its own clock), up to max ms. Says whether the page
   // came to rest.
-  async function settle(max = 2000) {
+  async function settle(max = 10000) {
 
     const start = performance.now();
     const left = () => max - (performance.now() - start);
 
-    await Promise.race([document.fonts?.ready, new Promise((r) => setTimeout(r, Math.max(0, left())))]);
+    let timer;
+    await Promise.race([document.fonts?.ready, new Promise((r) => { timer = setTimeout(r, Math.max(0, left())); })]).finally(() => clearTimeout(timer));
     await frame();
     await frame();
 
@@ -39,7 +40,7 @@ export function install() {
       still = !moving && mutations === before ? still + 1 : 0;
     }
 
-    return { ms: Math.round(performance.now() - start), rest: still >= 2 };
+    return { ms: Math.round(performance.now() - start), rest: still >= 2 && document.fonts?.status !== "loading" };
   }
 
   // A full-page screenshot lays the page out at another size for a moment (Chromium does, to draw what is past the
@@ -48,11 +49,12 @@ export function install() {
   // since.
   let resizes = 0;
   addEventListener("resize", () => resizes++);
-  async function calm([r, m]) {
+  async function calm([r, m], max = 10000) {
 
     await frame();
     const moving = document.getAnimations().some((a) => a.playState === "running" && Number.isFinite(a.effect?.getComputedTiming?.().endTime ?? Infinity));
-    if (resizes !== r && (mutations !== m || moving)) await settle(500);
+    if (resizes !== r || mutations !== m || moving || document.fonts?.status === "loading") return settle(max);
+    return { rest: true };
   }
 
   const visible = (el) => !!el && el.checkVisibility?.({ opacityProperty: true, visibilityProperty: true }) !== false;
@@ -958,6 +960,62 @@ export function install() {
     return { left: left + scrollX, top: top + scrollY, right: right + scrollX, bottom: bottom + scrollY };
   }
 
+  // The slats of the main Plot, in screen order: the largest chart's (a size key drawn as a chart of its own comes before
+  // the chart it explains) first Plot with slats that takes the pointer (an overlay of guides or a readout takes none)
+  function mainSlats() {
+
+    const area = (el) => el.getBoundingClientRect().width * el.getBoundingClientRect().height;
+    const chart = all().filter((c) => visible(c) && !c.parentElement?.closest(".rhp-chart")).sort((a, b) => area(b) - area(a))[0];
+    const plots = chart ? [...chart.querySelectorAll(":scope > .rhp-body > .rhp-plot")].filter((p) => !p.classList.contains("rhp-scale") && [...p.children].some((s) => !s.hidden)) : [];
+    const plot = plots.find((p) => getComputedStyle(p).pointerEvents !== "none") ?? plots[0];
+    if (!plot) return [];
+    const vertical = plot.dataset.rhpO === "v";
+    const slats = [...plot.children].filter((s) => !s.hidden && visible(s));
+    slats.sort((a, b) => (vertical ? a.getBoundingClientRect().left - b.getBoundingClientRect().left : a.getBoundingClientRect().top - b.getBoundingClientRect().top));
+    return slats;
+  }
+
+  // The slats the sweep picks in turn (see sweep() in index.js): every slat of the main Plot, or max of them spread
+  // evenly from the first to the last
+  function sweepTargets(max = 32) {
+
+    const slats = mainSlats();
+    const list = (window.__rhpTargets ??= []);
+    const picks = slats.length <= max ? slats.map((_, i) => i) : [...new Set(Array.from({ length: max }, (_, k) => Math.round((k * (slats.length - 1)) / (max - 1))))];
+    return picks.map((i) => ({ index: i + 1, of: slats.length, name: snippet([...slats[i].querySelectorAll(".rhp-label")].map(seenText).find((x) => x) ?? ""), target: list.push(slats[i]) - 1 }));
+  }
+
+  // The window widths at which the page's own media queries switch: the last width of one layout and the first of the
+  // next (for max-width: N, N and N + 1; for min-width: N, N - 1 and N; the range forms likewise). An em counts 16px.
+  function breakpoints() {
+
+    const out = new Set();
+    const px = (v, unit) => (unit === "px" ? +v : +v * 16);
+    // the first width of the wider layout, from a bound and whether the narrow layout includes it
+    const add = (n, narrowHasIt) => {
+      const first = narrowHasIt ? Math.floor(n) + 1 : Math.ceil(n);
+      out.add(first - 1);
+      out.add(first);
+    };
+    const walk = (rules) => {
+      for (const r of rules ?? []) {
+        const text = r.media?.mediaText ?? "";
+        for (const m of text.matchAll(/(min|max)-width\s*:\s*([\d.]+)(px|r?em)/g)) add(px(m[2], m[3]), m[1] === "max");
+        for (const m of text.matchAll(/width\s*(<=|<|>=|>)\s*([\d.]+)(px|r?em)/g)) add(px(m[2], m[3]), m[1] === "<=" || m[1] === ">");
+        for (const m of text.matchAll(/([\d.]+)(px|r?em)\s*(<=|<|>=|>)\s*width/g)) add(px(m[1], m[2]), m[3] === ">=" || m[3] === "<");
+        if (r.cssRules) walk(r.cssRules);
+      }
+    };
+    for (const sheet of [...document.styleSheets, ...(document.adoptedStyleSheets ?? [])]) {
+      try {
+        walk(sheet.cssRules);
+      } catch {
+        // a style sheet from another origin (a font's CSS) cannot be read, and holds no layout
+      }
+    }
+    return [...out].filter((w) => w >= 200).sort((a, b) => b - a);
+  }
+
   // What the interaction pass works on: slats to point at (the first, the middle and the last of the largest chart, and
   // the one whose edge Label is widest: lit, a name that gets bolder can make room: "auto" measure again), buttons and
   // toggles, ranges, selects, a slider for the arrow keys, Plots with keyboard. Controls go by their accessible name.
@@ -968,16 +1026,8 @@ export function install() {
     const out = { slats: [], widest: null, buttons: [], ranges: [], selects: [], slider: null, keyboard: null };
     const label = (el) => (nameOf(el) ? `"${snippet(nameOf(el))}"` : describe(el));
 
-    // the largest chart (a size key drawn as a chart of its own comes before the chart it explains)
-    const area = (el) => el.getBoundingClientRect().width * el.getBoundingClientRect().height;
-    const chart = all().filter((c) => visible(c) && !c.parentElement?.closest(".rhp-chart")).sort((a, b) => area(b) - area(a))[0];
-    // its first Plot with slats that takes the pointer (an overlay of guides or a readout takes none)
-    const plots = chart ? [...chart.querySelectorAll(":scope > .rhp-body > .rhp-plot")].filter((p) => !p.classList.contains("rhp-scale") && [...p.children].some((s) => !s.hidden)) : [];
-    const plot = plots.find((p) => getComputedStyle(p).pointerEvents !== "none") ?? plots[0];
-    if (plot) {
-      const vertical = plot.dataset.rhpO === "v";
-      const slats = [...plot.children].filter((s) => !s.hidden && visible(s));
-      slats.sort((a, b) => (vertical ? a.getBoundingClientRect().left - b.getBoundingClientRect().left : a.getBoundingClientRect().top - b.getBoundingClientRect().top));
+    const slats = mainSlats();
+    if (slats.length) {
       const range = document.createRange();
       const nameWidth = (s) => Math.max(0, ...[...s.querySelectorAll(".rhp-label[data-rhp-edge]")].map((l) => {
         range.selectNodeContents(l);
@@ -1090,6 +1140,7 @@ export function install() {
   // moves with it (rows sorted or removed), so only what it moves apart from its slat counts. What is fixed or sticky
   // moves with scrolling, so it is left out.
   let placed = [];
+  let sections = [];
   const at = (el) => {
     const r = el.getBoundingClientRect();
     return { el, x: r.left + scrollX, y: r.top + scrollY };
@@ -1118,6 +1169,13 @@ export function install() {
       const slat = chart ? null : el.closest(".rhp-plot > *");
       return { ...at(el), chart, slat: slat && at(slat), gutters: chart ? gutters(el) : null };
     });
+    // the end of each chart's section (its outermost box inside the body): a readout after the chart that takes
+    // another line makes it longer, even on a page shorter than the window
+    sections = [...new Set(charts.map((c) => {
+      let a = c;
+      while (a.parentElement && a.parentElement !== document.body && a.parentElement !== document.documentElement) a = a.parentElement;
+      return a;
+    }))].map((el) => ({ el, end: el.getBoundingClientRect().bottom + scrollY }));
   }
 
   function moved(n, lit = false) {
@@ -1150,6 +1208,12 @@ export function install() {
       if (now.o === "v" && far(start)) out.push({ what: "the plot's bottom edge", dx: 0, dy: -start, plot: true });
       if (now.o === "v" && far(end)) out.push({ what: "the plot's top edge", dx: 0, dy: end, plot: true });
     }
+    // lighting a slat makes no section longer or shorter: a readout after the chart that takes another line moves
+    // whatever follows it, which no control may show
+    for (const { el, end } of lit ? sections : []) {
+      const grew = Math.round(el.getBoundingClientRect().bottom + scrollY - end);
+      if (el.isConnected && far(grew)) out.push({ what: "the end of the chart's section", dx: 0, dy: grew });
+    }
 
     return out;
   }
@@ -1264,5 +1328,5 @@ export function install() {
     return { what: focusName(el), clip: box };
   }
 
-  window.__rhpProbe = { settle, calm, resized: () => [resizes, mutations], measure, transitions, colorItems, hide, show, contentBox, targets, pointAt, place, moved, record, stop, unseen, focused, focusStop };
+  window.__rhpProbe = { settle, calm, resized: () => [resizes, mutations], measure, transitions, colorItems, hide, show, contentBox, targets, sweepTargets, breakpoints, pointAt, place, moved, record, stop, unseen, focused, focusStop };
 }

package/src/check/report.js

@@ -52,7 +52,7 @@ export function report(r) {
   section("info", "Notes");
 
   const codes = new Set(r.findings.map((f) => f.code));
-  if (r.charts?.length || r.screenshots?.length) {
+  if (!codes.has("page-unsettled") && (r.charts?.length || r.screenshots?.length)) {
     const passed = [];
     for (const [fail, text] of PASSES) {
       if (fail.some((c) => codes.has(c))) continue;
@@ -88,6 +88,9 @@ export function report(r) {
       if (quiet.includes(x.kind)) continue;
       lines.push(`- ${x.kind} ${x.target}${x.width !== r.interactedAt ? ` at ${x.width}px` : ""}: ${x.how}${x.error ? `, and it threw: ${x.error}` : ""}`);
     }
+    // the sweep: one line, every width at which every slat was picked in turn
+    const swept = (r.swept ?? []).filter((x) => x.slats);
+    if (swept.length) lines.push(`- every slat picked in turn (${swept[0].slats}) at ${swept.map((x) => `${x.width}px`).join(", ")}: ${swept.some((x) => x.jumps) ? "the layout jumped (see the warnings)" : "nothing else moved"}`);
   } else if (r.charts?.length && r.interactedAt) {
     lines.push("", "Interactions: nothing to interact with (no slats to point at, no buttons, ranges or selects).");
   }

package/src/guard/rhp.js

@@ -168,6 +168,10 @@ function inspectChart(props) {
   }
 
   checkTheme("Chart's theme", read(props, "theme"));
+  for (const prop of ["grid", "crossGrid"]) {
+    const value = read(props, prop);
+    if (value != null && typeof value !== "boolean") note("error", "bad-prop", `Chart's ${prop} is ${show(value)}.`, "Use false to hide grid lines while retaining axis numbers, or true to show them.");
+  }
 }
 
 // The keys of the objects in rows, over all of them (a row may leave one out)

package/src/guard/rules.js

@@ -25,7 +25,7 @@ export const SETTING_VALUE = {
   children: (v) => typeof v === "function",
 };
 
-export const CHART_PROPS = ["scale", "orientation", "height", "aspect", "ticks", "format", "animate", "theme", "static", "cross", "crossTicks", "crossFormat", "label", "id", "class", "role", "style", "ref", "children"];
+export const CHART_PROPS = ["scale", "orientation", "height", "aspect", "ticks", "grid", "format", "animate", "theme", "static", "cross", "crossTicks", "crossGrid", "crossFormat", "label", "id", "class", "role", "style", "ref", "children"];
 
 export const THEME_KEYS = ["series", "positive", "negative", "ink", "muted", "grid", "surface", "low", "high", "font"];
 

package/src/server.js

@@ -21,7 +21,7 @@ const LIMIT = 50;
 const MAX_WIDTH = 1280;
 const MAX_HEIGHT = 2000;
 
-const INSTRUCTIONS = `rhp 2 (@bezda/rhp) makes charts out of HTML elements and CSS with SolidJS. It came out in September 2026, after your training data, so what you remember about rhp is wrong or belongs to the unrelated rhp 1. Before you write or change any rhp code, call rhp_guide and follow its workflow. Start each chart from the closest recipe (rhp_recipe), and look up every prop you are unsure of with rhp_reference instead of guessing. After every edit, call rhp_check with the chart file's absolute path, fix what it reports and look at its screenshots, until it reports no errors and no warnings.`;
+const INSTRUCTIONS = `rhp 2 (@bezda/rhp) makes charts out of HTML elements and CSS with SolidJS. It came out in September 2026, after your training data, so what you remember about rhp is wrong or belongs to the unrelated rhp 1. Before you write or change any rhp code, call rhp_guide and follow its workflow. Take each chart's technique from the closest recipe (rhp_recipe) and design the chart for its own subject, and look up every prop you are unsure of with rhp_reference instead of guessing. After every edit, call rhp_check with the chart file's absolute path, fix what it reports and look at its screenshots, until it reports no errors and no warnings.`;
 
 const text = (body) => ({ content: [{ type: "text", text: body }] });
 const failure = (body) => ({ content: [{ type: "text", text: body }], isError: true });
@@ -112,7 +112,7 @@ async function images(browser, shots) {
 }
 
 // Checks a chart: the report, then each screenshot as an image after a line saying what it shows
-async function checkTool({ file, code, format, widths, dark, interact }) {
+async function checkTool({ file, code, format, widths, dark, interact, settleTimeout }) {
 
   if (file && code) return failure("Give file or code, not both.");
   if (!file && !code) return failure("Give the chart to check: file (the absolute path of its file) or code (its code).");
@@ -131,7 +131,7 @@ async function checkTool({ file, code, format, widths, dark, interact }) {
   const { check } = await import("./check/index.js");
   const got = await sharedBrowser();
   const browser = got.browser;
-  const running = check({ file, code, format, widths, dark, interact, browser }).then((result) => ({ result }), (error) => ({ error }));
+  const running = check({ file, code, format, widths, dark, interact, settleTimeout, browser }).then((result) => ({ result }), (error) => ({ error }));
   let timer;
   const late = new Promise((resolve) => {
     timer = setTimeout(resolve, LIMIT * 1000, { late: true });
@@ -185,9 +185,9 @@ server.registerTool("rhp_guide", {
 
 server.registerTool("rhp_reference", {
   title: "rhp reference",
-  description: "Returns one of rhp's references by name: api (every component, prop, helper and CSS variable, exactly), design (the editorial poster, looks, color, type, layout), interaction (which interaction for which story, with code), environments (plain HTML, Solid, React, Next.js, Vue, Svelte, Angular, Astro), forms (which chart for which data and story), pitfalls (mistakes and their fixes). Look props up here instead of guessing. A long reference comes back as its list of sections: call again with section to get the one you need.",
+  description: "Returns one of rhp's references by name: api (every component, prop, helper and CSS variable, exactly), design (art direction from the subject, the editorial poster, color, type, layout), looks (eight looks written out in full, as examples), interaction (which interaction for which story, with code), environments (plain HTML, Solid, React, Next.js, Vue, Svelte, Angular, Astro), forms (the subject's own form, which chart for which data and story), pitfalls (mistakes and their fixes). Look props up here instead of guessing. A long reference comes back as its list of sections: call again with section to get the one you need.",
   inputSchema: {
-    name: z.string().describe("The reference: api, design, environments, forms, interaction or pitfalls"),
+    name: z.string().describe("The reference: api, design, environments, forms, interaction, looks or pitfalls"),
     section: z.string().optional().describe('One "##" section of the reference, by its number or title, for example "4" or "Plot"'),
   },
   annotations: { readOnlyHint: true, openWorldHint: false },
@@ -200,7 +200,7 @@ server.registerTool("rhp_reference", {
 
 server.registerTool("rhp_recipe", {
   title: "rhp recipe",
-  description: 'Lists rhp\'s recipes (call it with no type), or returns one recipe\'s complete HTML file (type, for example "bar"). A recipe is a tested, designed chart page, a worked example of one way to build a chart: start every chart from the closest recipe, keep its structure and techniques, and replace its data, text and look.',
+  description: 'Lists rhp\'s recipes (call it with no type), or returns one recipe\'s complete HTML file (type, for example "bar"). A recipe is a tested chart page that shows the technique for one kind of chart: take its technique (how its Plots, slats and blocks are composed, its interaction, its phone rules) and leave its design, which was made for its own subject.',
   inputSchema: {
     type: z.string().optional().describe('The recipe, for example "bar", "line" or "donut"; leave it out for the list'),
   },
@@ -220,9 +220,10 @@ server.registerTool("rhp_check", {
     file: z.string().optional().describe("The chart file's absolute path"),
     code: z.string().optional().describe("The chart's code, instead of a file, when you cannot write files"),
     format: z.enum(["html", "solid", "react", "module"]).optional().describe("What the code is; found from the file's extension and the code when left out"),
-    widths: z.array(z.number().int().min(200).max(2560)).min(1).max(4).optional().describe("Page widths in px, [1280, 390] by default; the interactions are tried at the first, and slats are tapped at phone widths (600px or less)"),
+    widths: z.array(z.number().int().min(200).max(2560)).min(1).max(6).optional().describe("Page widths in px, [1280, 390] by default; the interactions are tried at the first, and slats are tapped at phone widths (600px or less)"),
     dark: z.boolean().optional().describe("Render with a dark color scheme (prefers-color-scheme: dark)"),
     interact: z.boolean().optional().describe("Try the chart's interactions (true by default)"),
+    settleTimeout: z.number().int().min(100).max(30000).optional().describe("Maximum milliseconds per readiness wait, 10000 by default. Increase for a slow machine; the overall check still has a 50-second limit."),
   },
   annotations: { readOnlyHint: true, openWorldHint: true },
 }, checkTool);
@@ -238,7 +239,7 @@ server.registerPrompt("chart", {
     role: "user",
     content: {
       type: "text",
-      text: `Make this chart with rhp (@bezda/rhp): ${request}\n\nFirst call rhp_guide and follow its workflow: write the brief, start from the closest recipe (rhp_recipe), and look up props with rhp_reference instead of guessing. After every edit, call rhp_check with the chart file's absolute path, fix what it reports and look at its screenshots, until it reports no errors and no warnings.`,
+      text: `Make this chart with rhp (@bezda/rhp): ${request}\n\nFirst call rhp_guide and follow its workflow: write the brief, take the technique from the closest recipe (rhp_recipe), design the chart for its own subject, and look up props with rhp_reference instead of guessing. After every edit, call rhp_check with the chart file's absolute path, fix what it reports and look at its screenshots, until it reports no errors and no warnings.`,
     },
   }],
 }));