@bezda/rhp-mcp 0.0.0-stage → 0.1.1

package/src/check/colors.js

@@ -0,0 +1,324 @@
+// The color probes, read from screenshots: text contrast (against what is behind each text, from a screenshot with the
+// glyphs hidden), marks that barely show against what is behind them, and series colors that look alike to readers
+// with color blindness. Then the color math they use: WCAG contrast, color blindness simulated (Machado, Oliveira and
+// Fernandes 2009, at severity 1), and CIEDE2000 color differences.
+import { pixelsIn } from "./png.js";
+
+// The pixel of a list whose luminance is the median, and how much the luminance spreads (10th to 90th percentile)
+function median(pixels) {
+
+  const ranked = pixels.map((p) => [luminance(p), p]).sort((a, b) => a[0] - b[0]);
+  const at = (q) => ranked[Math.min(ranked.length - 1, Math.floor(q * ranked.length))];
+
+  return { color: at(0.5)[1], spread: at(0.9)[0] - at(0.1)[0] };
+}
+
+const scaled = (box, k) => ({ left: box.left * k, top: box.top * k, right: box.right * k, bottom: box.bottom * k });
+
+const rgbOf = (h) => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16));
+
+// The color closest to fg, on the way from fg to white or to black, that reaches the contrast asked for against bg (as
+// a hex color, which still reaches it once rounded). Away from bg first (a dark text gets darker); when that end can't
+// reach it and flip is allowed, the other way (white text on a mid green becomes a dark text). Null when none can.
+function fixColor(fg, bg, target, flip = true) {
+
+  const away = luminance(fg) >= luminance(bg) ? [255, 255, 255] : [0, 0, 0];
+  const back = away[0] ? [0, 0, 0] : [255, 255, 255];
+
+  for (const toward of flip ? [away, back] : [away]) {
+    if (contrast(toward, bg) < target) continue;
+    const at = (t) => over(toward, t, fg);
+    let t = 0;
+    while (t < 1 && contrast(at(t), bg) < target) {
+      t = Math.min(1, t + 0.02);
+    }
+    let lo = Math.max(0, t - 0.02);
+    let hi = t;
+    for (let i = 0; i < 12; i++) {
+      const mid = (lo + hi) / 2;
+      if (contrast(at(mid), bg) >= target) hi = mid;
+      else lo = mid;
+    }
+    while (hi < 1 && contrast(rgbOf(hex(at(hi))), bg) < target) {
+      hi = Math.min(1, hi + 0.002);
+    }
+    return hex(at(hi));
+  }
+
+  return null;
+}
+
+// Text whose contrast with what is behind it is too low. WCAG AA asks for 4.5:1, or 3:1 for large text (24px, or
+// 18.66px bold). Under 3:1 (2:1 for large text) the text is hard to read for anyone: an error. From there up to AA it
+// reads, but not for every reader: a warning.
+export function textContrast(items, behind, k) {
+
+  const worst = new Map();
+
+  for (const t of items) {
+    if (t.kind !== "text") continue;
+    const pixels = t.boxes.flatMap((b) => pixelsIn(behind, scaled(b, k)));
+    if (pixels.length < 4) continue;
+    const bg = median(pixels);
+    const alpha = t.color[3] * t.opacity;
+    if (alpha < 0.05) continue;
+    const fg = over(t.color, alpha, bg.color);
+    const ratio = contrast(fg, bg.color);
+    const large = t.size >= 24 || (t.size >= 18.66 && t.bold);
+    const need = large ? 3 : 4.5;
+    if (ratio >= need) continue;
+    const level = ratio < (large ? 2 : 3) ? "error" : "warning";
+    const key = level + hex(fg) + hex(bg.color);
+    const had = worst.get(key);
+    if (!had || ratio < had.ratio) worst.set(key, { level, text: t.text, fg, bg: bg.color, ratio, need, large, count: (had?.count ?? 0) + 1 });
+    else had.count++;
+  }
+
+  return [...worst.values()].sort((a, b) => a.ratio - b.ratio).map((w) => {
+    const size = w.large ? "large text" : "text this size";
+    // the text may turn from light to dark, but what is behind it only moves away from the text (a white page is not
+    // made dark)
+    const text = fixColor(w.fg, w.bg, w.need);
+    const back = fixColor(w.bg, w.fg, w.need, false);
+    const fixes = [text && `make the text ${text}`, back && `the color behind it ${back}`].filter(Boolean);
+    return {
+      level: w.level,
+      code: "low-contrast",
+      key: `low-contrast ${w.level} ${hex(w.fg)} ${w.text}`,
+      message: w.level === "error"
+        ? `${JSON.stringify(w.text)} is ${hex(w.fg)} on ${hex(w.bg)}: contrast ${w.ratio.toFixed(2)}:1, too faint to read (under ${w.large ? 2 : 3}:1; WCAG AA asks for ${w.need}:1 for ${size})${w.count > 1 ? ` (${w.count} texts like it)` : ""}.`
+        : `${JSON.stringify(w.text)} is ${hex(w.fg)} on ${hex(w.bg)}: contrast ${w.ratio.toFixed(2)}:1, under the ${w.need}:1 WCAG AA asks for ${size}${w.count > 1 ? ` (${w.count} texts like it)` : ""}.`,
+      fix: fixes.length
+        ? `${fixes.join(", or ")} (${fixes.length > 1 ? "each the nearest color" : "the nearest color"} that reaches ${w.need}:1).`.replace(/^./, (c) => c.toUpperCase())
+        : "Change the text's color or what is behind it: no shade of this color reaches it on that background.",
+    };
+  });
+}
+
+// An edge (a border, an outline or a box-shadow) counts when its color, drawn with its alpha over what is behind the
+// mark, reaches the 3:1 that WCAG asks of the parts of a graphic.
+const EDGE = 3;
+const edged = (m, bg) => m.edges?.some((e) => contrast(over(e.color, e.color[3], bg), bg) >= EDGE);
+
+const holds = (outer, inner) => outer.left <= inner.left + 1 && outer.top <= inner.top + 1 && outer.right >= inner.right - 1 && outer.bottom >= inner.bottom - 1;
+
+// Marks close to invisible against what is behind them: each pixel a mark draws (read from a screenshot with the
+// marks) against the same pixel without them. A mark counts as seen when a tenth of its pixels reach 1.25:1 (an
+// outline, the colored half of a two-tone capsule), or when it or a mark it lies in (a cup around its layers) has a
+// border, an outline or a box-shadow that reaches 3:1. Quiet marks drawn on purpose (the work still to do in a Gantt
+// chart, leader lines, connectors) sit around 1.35:1 to 1.45:1 and read without effort, so the line is lower than that.
+const FAINT = 1.25;
+export function faintMarks(items, shown, hidden, k) {
+
+  const faint = new Map();
+  const marks = items.filter((m) => m.kind === "mark");
+
+  for (const m of marks) {
+    if (m.track) continue;
+    const box = scaled(m.boxes[0], k);
+    const a = pixelsIn(shown, box);
+    const b = pixelsIn(hidden, box);
+    const ratios = [];
+    for (let i = 0; i < a.length; i++) {
+      if (Math.abs(a[i][0] - b[i][0]) + Math.abs(a[i][1] - b[i][1]) + Math.abs(a[i][2] - b[i][2]) > 6) ratios.push([contrast(a[i], b[i]), a[i], b[i]]);
+    }
+    // a mark that changes few of its pixels is an outline or empty: not what this probe is about
+    if (ratios.length < 6 || ratios.length < a.length * 0.3) continue;
+    ratios.sort((x, y) => x[0] - y[0]);
+    const [ratio, fg, bg] = ratios[Math.floor(ratios.length * 0.9)];
+    if (ratio >= FAINT) continue;
+    const behind = median(b).color;
+    if (edged(m, behind) || marks.some((o) => o !== m && o.slat != null && o.slat === m.slat && holds(o.boxes[0], m.boxes[0]) && edged(o, behind))) continue;
+    const key = m.block + hex(m.color);
+    const had = faint.get(key);
+    faint.set(key, { block: m.block, fg: had?.fg ?? fg, bg: had?.bg ?? bg, ratio: Math.min(ratio, had?.ratio ?? Infinity), count: (had?.count ?? 0) + 1 });
+  }
+
+  return [...faint.values()].map((f) => ({
+    level: "warning",
+    code: "faint-marks",
+    key: `faint-marks ${f.block} ${hex(f.fg)}`,
+    message: `${f.count > 1 ? `${f.count} ${f.block}s` : `A ${f.block}`} in ${hex(f.fg)} ${f.count > 1 ? "are" : "is"} ${f.ratio.toFixed(2)}:1 against ${hex(f.bg)} behind ${f.count > 1 ? "them" : "it"}, hard to see.`,
+    fix: `Give the marks a color with more contrast against the background (${fixColor(f.fg, f.bg, 3) ?? "a darker or lighter one"} reaches 3:1), or an edge that does: a border, an outline or a box-shadow in the slat's css.`,
+  }));
+}
+
+// Series colors that look alike: 2 to 8 distinct mark colors in a chart, and two of them, with no labels in their slats
+// that tell them apart, either touching somewhere (stacked segments, mixed dots) and under a CIEDE2000 difference of 10,
+// or anywhere and under 5 (the same color, to that reader), for normal vision or simulated protanopia, deuteranopia or
+// tritanopia. Colors that never touch are told apart by their place too (the first and last segments of a stack). A
+// see-through color (rgba, color-mix with transparent, a mark's opacity) is the color it makes over what is behind
+// the mark, read from the screenshot with the marks hidden.
+export function colorBlind(items, hidden, k) {
+
+  const out = [];
+  const charts = new Map();
+
+  for (const m of items) {
+    const alpha = m.color[3] * m.opacity;
+    if (m.kind !== "mark" || m.track || alpha < 0.2) continue;
+    const behind = alpha < 1 && hidden ? pixelsIn(hidden, scaled(m.boxes[0], k)) : [];
+    const rgb = behind.length ? over(m.color, alpha, median(behind).color) : m.color.slice(0, 3);
+    if (!charts.has(m.chart)) charts.set(m.chart, []);
+    charts.get(m.chart).push({ ...m, rgb });
+  }
+
+  for (const marks of charts.values()) {
+    // one entry per color, colors that look the same merged
+    const colors = [];
+    for (const m of marks) {
+      const rgb = m.rgb;
+      let c = colors.find((x) => difference(x.rgb, rgb) < 2);
+      if (!c) colors.push((c = { rgb, names: new Set(), marks: [] }));
+      c.marks.push(m);
+      for (const n of m.names) {
+        c.names.add(n);
+      }
+    }
+    if (colors.length < 2 || colors.length > 8) continue;
+
+    let worst = null;
+    for (let i = 0; i < colors.length; i++) {
+      for (let j = i + 1; j < colors.length; j++) {
+        const [a, b] = [colors[i], colors[j]];
+        const labelled = a.names.size && b.names.size && !(a.names.size === b.names.size && [...a.names].every((n) => b.names.has(n)));
+        if (labelled) continue;
+        const near = touching(a.marks, b.marks);
+        for (const vision of VISIONS) {
+          const d = difference(a.rgb, b.rgb, vision);
+          if (d < (near ? 10 : 5) && (!worst || d < worst.d)) worst = { a, b, vision, d, near };
+        }
+      }
+    }
+
+    if (worst) {
+      const who = worst.vision === "normal" ? "anyone" : `readers with ${worst.vision}`;
+      out.push({
+        level: "warning",
+        code: "colorblind",
+        message: `Two of the ${colors.length} series colors, ${hex(worst.a.rgb)} and ${hex(worst.b.rgb)}, look alike to ${who} (CIEDE2000 difference ${worst.d.toFixed(1)}${worst.near ? ", where their marks touch" : ""}).`,
+        fix: "Make the colors differ in lightness as well as hue (one light, one dark), or name each series next to its marks instead of only in a legend.",
+      });
+    }
+  }
+
+  return out;
+}
+
+// Whether a mark of one list comes within 4px of a mark of the other
+function touching(a, b) {
+
+  const gap = (p, q) => Math.max(0, p.left - q.right, q.left - p.right, p.top - q.bottom, q.top - p.bottom);
+
+  for (const m of a.slice(0, 3000)) {
+    for (const n of b.slice(0, 3000)) {
+      if (gap(m.boxes[0], n.boxes[0]) <= 4) return true;
+    }
+  }
+
+  return false;
+}
+
+const linear = (c) => {
+  const v = c / 255;
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+};
+
+const gamma = (v) => {
+  const c = Math.min(1, Math.max(0, v));
+  return 255 * (c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055);
+};
+
+// WCAG 2 relative luminance of an sRGB color [r, g, b] (0 to 255)
+const luminance = ([r, g, b]) => 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+
+function contrast(a, b) {
+
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// A color drawn with alpha over a background, as the browser blends them (in sRGB)
+const over = ([r, g, b], alpha, [br, bg, bb]) => [r * alpha + br * (1 - alpha), g * alpha + bg * (1 - alpha), b * alpha + bb * (1 - alpha)];
+
+const hex = ([r, g, b]) => "#" + [r, g, b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
+
+// Machado et al. 2009, severity 1, applied to linear RGB
+const MACHADO = {
+  protanopia: [[0.152286, 1.052583, -0.204868], [0.114503, 0.786281, 0.099216], [-0.003882, -0.048116, 1.051998]],
+  deuteranopia: [[0.367322, 0.860646, -0.227968], [0.280085, 0.672501, 0.047413], [-0.01182, 0.04294, 0.968881]],
+  tritanopia: [[1.255528, -0.076749, -0.178779], [-0.078411, 0.930809, 0.147602], [0.004733, 0.691367, 0.3039]],
+};
+
+const VISIONS = ["normal", ...Object.keys(MACHADO)];
+
+function simulate(rgb, vision) {
+
+  const m = MACHADO[vision];
+  if (!m) return rgb;
+
+  const lin = rgb.map(linear);
+
+  return m.map((row) => gamma(row[0] * lin[0] + row[1] * lin[1] + row[2] * lin[2]));
+}
+
+// sRGB to CIE Lab (D65)
+function lab(rgb) {
+
+  const [r, g, b] = rgb.map(linear);
+  const x = (0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / 0.95047;
+  const y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
+  const z = (0.0193339 * r + 0.119192 * g + 0.9503041 * b) / 1.08883;
+  const f = (t) => (t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 * t + 16) / 116);
+
+  return [116 * f(y) - 16, 500 * (f(x) - f(y)), 200 * (f(y) - f(z))];
+}
+
+// CIEDE2000 (Sharma, Wu and Dalal 2005)
+function ciede2000([L1, a1, b1], [L2, a2, b2]) {
+
+  const rad = Math.PI / 180;
+  const C1 = Math.hypot(a1, b1);
+  const C2 = Math.hypot(a2, b2);
+  const Cbar = (C1 + C2) / 2;
+  const G = 0.5 * (1 - Math.sqrt(Cbar ** 7 / (Cbar ** 7 + 25 ** 7)));
+  const a1p = (1 + G) * a1;
+  const a2p = (1 + G) * a2;
+  const C1p = Math.hypot(a1p, b1);
+  const C2p = Math.hypot(a2p, b2);
+  const hue = (b, a) => (b === 0 && a === 0 ? 0 : (Math.atan2(b, a) / rad + 360) % 360);
+  const h1p = hue(b1, a1p);
+  const h2p = hue(b2, a2p);
+
+  const dLp = L2 - L1;
+  const dCp = C2p - C1p;
+  let dhp = 0;
+  if (C1p * C2p !== 0) {
+    dhp = h2p - h1p;
+    if (dhp > 180) dhp -= 360;
+    else if (dhp < -180) dhp += 360;
+  }
+  const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin((dhp / 2) * rad);
+
+  const Lbp = (L1 + L2) / 2;
+  const Cbp = (C1p + C2p) / 2;
+  let hbp = h1p + h2p;
+  if (C1p * C2p !== 0) {
+    if (Math.abs(h1p - h2p) <= 180) hbp = (h1p + h2p) / 2;
+    else hbp = h1p + h2p < 360 ? (h1p + h2p + 360) / 2 : (h1p + h2p - 360) / 2;
+  }
+
+  const T = 1 - 0.17 * Math.cos((hbp - 30) * rad) + 0.24 * Math.cos(2 * hbp * rad) + 0.32 * Math.cos((3 * hbp + 6) * rad) - 0.2 * Math.cos((4 * hbp - 63) * rad);
+  const dTheta = 30 * Math.exp(-(((hbp - 275) / 25) ** 2));
+  const RC = 2 * Math.sqrt(Cbp ** 7 / (Cbp ** 7 + 25 ** 7));
+  const SL = 1 + (0.015 * (Lbp - 50) ** 2) / Math.sqrt(20 + (Lbp - 50) ** 2);
+  const SC = 1 + 0.045 * Cbp;
+  const SH = 1 + 0.015 * Cbp * T;
+  const RT = -Math.sin(2 * dTheta * rad) * RC;
+
+  return Math.sqrt((dLp / SL) ** 2 + (dCp / SC) ** 2 + (dHp / SH) ** 2 + RT * (dCp / SC) * (dHp / SH));
+}
+
+// How far apart two colors look, for one kind of vision
+const difference = (a, b, vision = "normal") => ciede2000(lab(simulate(a, vision)), lab(simulate(b, vision)));

package/src/check/findings.js

@@ -0,0 +1,247 @@
+// Every finding the checker reports: what the probes in the page saw, what the page printed or threw, as
+// { level, code, message, fix }. The codes and their fixes are listed in README.md (next to this file).
+
+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" };
+
+// 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 ");
+
+// A finding from what measure() saw in the page
+export function fromProbe(f, context) {
+
+  switch (f.code) {
+    case "no-chart":
+      return {
+        level: "error",
+        code: f.code,
+        message: "No chart was drawn: the page has no rhp chart after it loaded.",
+        fix: context.errors ? "Fix the errors above first: the chart is drawn by the code that threw." : 'Render the chart into an element the page has: render(() => html`<${Chart} ...>`, document.getElementById("chart")) with <div id="chart"></div> in the body (in a Solid or React file, export the chart component as default).',
+      };
+    case "empty-plot":
+      return { level: "error", code: f.code, message: "A Plot draws no slats: its data groups are empty, or its order hides every row.", fix: "Give the Plot its data: a list per data group with one item per row (name={names} value={values}), or rows={objects}." };
+    case "small-plot":
+      if (f.thin) {
+        return {
+          level: "error",
+          code: f.code,
+          message: `Each slat of a plot is only ${f.band}px thick, too thin to see.`,
+          fix: f.vertical
+            ? "Show fewer columns (bin or group the data), or turn the chart horizontal: a horizontal chart grows with its rows."
+            : "Give the slat type a thickness (slat({ thickness: 28, ... }, fn)), or show fewer rows.",
+        };
+      }
+      return {
+        level: "error",
+        code: f.code,
+        message: `A plot is only ${f.length}px ${f.vertical ? "tall" : "wide"}, too small to read.`,
+        fix: f.vertical ? "Give the Chart a height (height={320}) or an aspect (aspect={16 / 9}), and its parent the room for it." : "Give the chart more width: its parent is too narrow, or the room for labels (room start and end) takes it all.",
+      };
+    case "nan-value":
+      if (f.printed) return { level: "error", code: f.code, message: `${f.what} in the chart shows ${q(f.text)}: a value it prints is missing or not a number.`, fix: "Check the data the label prints (a missing value, a misspelled name, a division by zero), and format numbers before printing them." };
+      return { level: "error", code: f.code, message: `${f.block}'s ${f.prop} is ${f.value}.`, fix: `Give ${f.block} a number for ${f.prop}: check the data it is computed from (a missing value, a name that is misspelled, a division by zero).` };
+    case "plot-outside-chart":
+      return {
+        level: "error",
+        code: f.code,
+        message: `${f.count > 1 ? `${f.count} Plots are` : "A Plot is"} drawn outside a Chart, so ${f.count > 1 ? "they get" : "it gets"} no scale and none of rhp's CSS: nothing in ${f.count > 1 ? "them" : "it"} is placed.`,
+        fix: "Put every Plot inside a Chart: <${Chart} scale=${[0, 100]}><${Plot} ...>${Slat}<//><//> (a Plot inside a slat is fine: the slat is in a Chart).",
+      };
+    case "collapsed-chart":
+      return {
+        level: "error",
+        code: f.code,
+        message: `The chart is only ${f.width}px wide and its plot 0px${f.why ? `: ${f.why}, which shrinks it to fit its content` : ""}, so its marks have no room.`,
+        fix: "A chart takes the width of its box. In a flex row give the chart's box flex: 1; min-width: 0, and don't put it in an inline-block, a float or a width: fit-content box (or give that box a width).",
+      };
+    case "cramped":
+      if (f.vertical) return { level: "warning", code: f.code, message: "The vertical chart is at the default height (240px), and the labels in its slats crowd each other.", fix: "Give the Chart the height its labels need (height={360}), or an aspect (aspect={4 / 3}), or show fewer labels per slat." };
+      return { level: "warning", code: f.code, message: `Each slat is only ${f.band}px thick, too thin for the labels it holds: text and marks crowd each other.`, fix: "Give the slat type a thickness of 24px or more (slat({ thickness: 28, ... }, fn)), or the Chart the height for it." };
+    case "points-past-scale": {
+      const scale = f.cross ? "cross" : "scale";
+      return {
+        level: "error",
+        code: f.code,
+        message: `${f.block === "Area" ? "An Area's" : "A Line's"} points reach ${f.value}, outside the Chart's ${f.cross ? "cross scale" : "scale"} [${f.min}, ${f.max}]: rhp squeezes the whole outline into the scale, so every point is drawn in the wrong place${f.count > 1 ? ` (${f.count} values)` : ""}.`,
+        fix: `Keep every point inside the scale: ${scale}=\${[${Math.min(f.min, f.value)}, ${Math.max(f.max, f.value)}]} or wider (nice() gives round ends), or cut the points to it (density() and bins() take a domain).`,
+      };
+    }
+    case "series-past-theme": {
+      const keys = f.keys.map((k) => "series-" + k).join(", ");
+      return {
+        level: "error",
+        code: f.code,
+        message: `${keys} ${f.keys.length > 1 ? "are" : "is"} past the theme's ${f.have} series colors, so ${f.count > 1 ? `${f.count} marks fall` : "a mark falls"} back to series-1.`,
+        fix: `Use series(${f.have}) for a theme of ${f.have} colors (series() counts 6 by default), or give the theme more series colors.`,
+      };
+    }
+    case "block-transition":
+      return {
+        level: "warning",
+        code: f.code,
+        message: `The slat's CSS gives ${f.path ? `the outline of ${f.what}` : f.what} a transition of its own (${f.set}), which replaces rhp's (${f.dropped.join(", ")}), so ${f.count > 1 ? `${f.count} ${f.block}s jump` : `the ${f.block} jumps`} to new values instead of moving.`,
+        fix: `Put the transition on an element inside the ${f.block} (a span in it) and leave the ${f.block}'s own to rhp, or name rhp's too: transition-property: ${[...f.dropped, f.set].join(", ")}.`,
+      };
+    case "page-css-ignored": {
+      const colors = f.props.some((p) => /color|background|fill|stroke/.test(p));
+      const font = f.props.some((p) => /^font/.test(p));
+      return {
+        level: "warning",
+        code: f.code,
+        message: `The page's CSS rule ${f.selector} sets ${f.props.join(", ")} on ${f.what}${f.count > 1 ? ` and ${f.count - 1} more` : ""} in a chart, where rhp's own CSS wins, so it changes nothing.`,
+        fix: `Style what is in a chart in the slat type's css (slat({ css: \`.bar { ... }\` }, fn))${colors ? ", and give colors with the block's color prop or the Chart's theme" : ""}${font ? ", and the font with the theme's font" : ""}. Page CSS can only set opacity, cursor, filter, transform, z-index and pointer-events there.`,
+      };
+    }
+    case "value-past-scale": {
+      const where = `${f.cross ? "the Chart's cross scale" : "the Chart's scale"} [${f.min}, ${f.max}]`;
+      const count = f.count > 1 ? ` (${f.count} values)` : "";
+      let message = `A ${f.block} sits at ${f.value}, outside ${where}, so it is drawn outside the plot${count}.`;
+      if (f.kept) message = `A ${f.block} sits at ${f.value}, outside ${where}: rhp keeps it at the ${f.value < f.min ? "start" : "end"} of the scale, away from its value${count}.`;
+      if (f.block === "Bar") message = `A Bar reaches ${f.value}, outside ${where}: rhp cuts a bar at the ends of the scale, so this one ${f.gone ? "draws nothing" : "shows the wrong value"}${count}.`;
+      return {
+        level: "error",
+        code: f.code,
+        message,
+        fix: `Make the scale cover the data: ${f.cross ? "cross" : "scale"}=\${[${Math.min(f.min, f.value)}, ${Math.max(f.max, f.value)}]} or wider (nice(lo, hi).min and .max give round ends)${f.block === "Label" ? ", or place the Label at the value its mark shows" : ""}.`,
+      };
+    }
+    case "sticks-out": {
+      // the side the value axis starts on (left, or bottom in a vertical chart) and the side it ends on
+      const along = f.vertical ? f.side === "top" || f.side === "bottom" : f.side === "left" || f.side === "right";
+      const start = f.side === (f.vertical ? "bottom" : "left");
+      let fix = "Keep marks inside the chart: the values inside the scale (build it with nice()), and room for what is drawn outside the plot (slat({ room: { ... } }, fn)).";
+      if (f.axis) fix = "Keep the axis numbers short (a format that drops units, or fewer ticks): the axis has fixed room past each end of the scale.";
+      else if (f.label && !along) fix = "Give the slats the thickness their labels need (slat({ thickness: 32 }, fn)), or make the labels smaller.";
+      else if (f.label && (f.edge || start)) fix = "Give the slat type room for its names on that side (room: { start: 120 }, or room: \"auto\" to fit the longest), or cap them: max-width with text-overflow: ellipsis on the label's class.";
+      else if (f.label) fix = "Give the slat type room at the end for its value labels (room: { end: 60 }), or build the scale past the largest value with nice().";
+      return {
+        level: "error",
+        code: f.code,
+        message: `${f.what}${f.text ? ` ${q(f.text)}` : ""} sticks out of its chart by ${f.by}px on the ${f.side}${f.count > 1 ? ` (${f.count} elements stick out)` : ""}.`,
+        fix,
+      };
+    }
+    case "text-outside-poster":
+      return { level: "error", code: f.code, message: `${q(f.text)} sticks out of the poster by ${f.by}px.`, fix: "Let the text wrap inside the poster (no white-space: nowrap, max-width: 100%), or make it smaller at narrow widths." };
+    case "text-cut-off": {
+      // an ellipsis is drawn on purpose, and the text is still there to read in part: a warning. Text clipped with no
+      // sign of it is an error.
+      let keep = "give it room (a wider or taller box), let it wrap, or shorten it.";
+      if (f.label && f.vertical) keep = "a vertical chart's names are as wide as their columns, so let them wrap (.name:vertical { white-space: normal }), shorten them, or draw the chart horizontal on narrow screens.";
+      else if (f.edge) keep = "give the names room (room: { start: 140 } in the slat type, or room: \"auto\" to fit the longest), let them wrap (white-space: normal on the label's class), or shorten them.";
+      return f.ellipsis
+        ? { level: "warning", code: f.code, message: `${q(f.text)} ends in an ellipsis: ${f.lost}px of it is hidden by ${f.by}, so the reader loses the rest of it.`, fix: `To keep it whole, ${keep}` }
+        : { level: "error", code: f.code, message: `${q(f.text)} is cut off: ${f.lost}px of it is hidden by ${f.by}, with no sign that it goes on.`, fix: `To show it whole, ${keep}` };
+    }
+    case "text-overlap":
+      return { level: "error", code: f.code, message: `${q(f.a)} overlaps ${q(f.b)} (${f.x} by ${f.y}px).`, fix: "Give each text its own space: more room or thickness, a smaller font, shorter text, or show one of them only where it fits." };
+    case "ambiguous-label": {
+      const mark = f.other ? `the mark of ${q(f.other)}` : "another slat's mark (one with no name)";
+      const more = f.count > 1 ? ` (${f.count} names are placed like it)` : "";
+      return {
+        level: "warning",
+        code: f.code,
+        message: f.over
+          ? `${q(f.text)} is drawn over ${mark}${more}, so a reader may take it for that mark's name.`
+          : `${q(f.text)} is ${f.near}px from ${mark}, in line with its text, and ${f.own}px from its own mark${more}, so a reader may take it for that mark's name.`,
+        fix: "Put each name beside its own mark, on the side away from its neighbors (a side or an offset per row, and another on narrow screens), or leave a crowded name to the readout.",
+      };
+    }
+    case "page-scrolls-sideways":
+      return {
+        level: "error",
+        code: f.code,
+        message: `The page scrolls sideways by ${f.by}px at ${f.viewport}px wide${f.what ? `: ${f.what} is ${f.width}px wide` : ""}.`,
+        fix: "Keep everything inside the page's width: max-width: 100% and box-sizing: border-box on the poster, no fixed width wider than the phone, and long words allowed to wrap.",
+      };
+    case "tiny-text":
+      return { level: "error", code: f.code, message: `${q(f.text)} is ${f.size}px${f.count > 1 ? ` (${f.count} texts are under 9px)` : ""}, too small to read.`, fix: "Make text at least 9px, and data labels 11px or more." };
+    case "font-not-loaded":
+      return {
+        level: "info",
+        code: f.code,
+        message: `The font ${q(f.family)} did not load${f.failed ? " (its file failed to download: offline, or a wrong URL)" : ""}, so its text uses a fallback font.`,
+        fix: "Load it with a Google Fonts <link> in the head, or drop it from the font stack.",
+      };
+    case "unnamed-control":
+      return {
+        level: "warning",
+        code: f.code,
+        message: `${f.what} has no accessible name${f.count > 1 ? ` (${f.count} controls have none)` : ""}: a screen reader says only what kind of control it is, not what it does.`,
+        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 plot = f.moved.some((m) => m.plot);
+      return {
+        level: "warning",
+        code: f.code,
+        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.",
+      };
+    }
+    case "out-of-view":
+      return {
+        level: "warning",
+        code: f.code,
+        message: `Tapping ${f.target} changes text only outside the screen (${f.what}, ${f.by}px ${f.side} it)${f.more ? `, and so does tapping ${f.more} more slat${f.more > 1 ? "s" : ""}` : ""}: on a phone the reader cannot see what the tap says.`,
+        fix: "Put the readout next to the slat (in the slat, or in a Label of it), or keep it in view on a phone (position: sticky; top: 0; z-index: 2, above the chart's plot).",
+      };
+    case "focus-invisible":
+      return {
+        level: "warning",
+        code: f.code,
+        message: `Tab reaches ${f.what}${f.more ? ` and ${f.more} more` : ""}, but nothing on screen shows the focus there: a keyboard reader cannot see where it is.`,
+        fix: "Show focus: take off outline: none, or put a :focus-visible style that shows in its place (outline: 2px solid in the ink color, outline-offset: 2px; on a slat, in the slat type's css).",
+      };
+    default:
+      return { level: "error", code: f.code, message: JSON.stringify(f), fix: "" };
+  }
+}
+
+const STANDALONE = ["render", "html", "createSignal", "createMemo", "createEffect", "createRoot", "onMount", "onCleanup", "batch", "untrack", "For", "Index", "Show", "createStore", "reconcile", "produce", "unwrap", "Plot", "Scale", "Chart", "Theme", "Axis", "at", "useOrientation", "THEME", "series", "slat", "restyle", "linkedCss", "shape", "Bar", "Dot", "Tick", "Label", "Cell", "Place", "Area", "Line", "Poster", "sortBy", "cycle", "every", "extent", "nice", "stackUp", "shares", "running", "summary", "bins", "density", "animated", "curve", "drawing"];
+
+// What to do about an error the page threw
+export function fixForError(message, format) {
+
+  let m = message.match(/(\w+) is not defined/);
+  if (m) return STANDALONE.includes(m[1]) ? `Import ${m[1]}: import { ${m[1]}, ... } from "${format === "solid" ? (["render", "createSignal", "createMemo", "createEffect", "Show", "For", "Index", "onMount", "onCleanup", "batch", "untrack", "createRoot"].includes(m[1]) ? "solid-js" : "@bezda/rhp") : "@bezda/rhp/standalone"}".` : `Define ${m[1]} or import it before it is used.`;
+
+  m = message.match(/Failed to resolve module specifier "([^"]+)"/);
+  if (m) return `Map "${m[1]}" in the page's import map: <script type="importmap">{ "imports": { "@bezda/rhp/standalone": "https://cdn.jsdelivr.net/npm/@bezda/rhp@2/dist/standalone.js" } }</script>, before the module script.`;
+
+  m = message.match(/Cannot read properties of (undefined|null) \(reading '([^']+)'\)/);
+  if (m) return `Something is ${m[1]} where the code reads .${m[2]}: check the data and the names (a slat reads d.name only when the Plot is given name={...}).`;
+
+  if (/rhp: a slat must return one element/.test(message)) return "Return one element from the slat, with the blocks inside it: (d) => html`<div><${Bar} to=${() => d.value} /></div>`.";
+  if (/rhp: a Plot's child must be a slat function/.test(message)) return "Give the Plot one slat function as its child: <${Plot} value=${values}>${Fruit}<//>, where Fruit is (d) => html`<div>...</div>` or made with slat().";
+  if (/rhp: a Scale goes inside a Chart/.test(message)) return "Put the Scale inside the Chart, beside its Plots.";
+  if (/Unexpected token 'export'|Cannot use import statement outside a module/.test(message)) return "Load modules with <script type=\"module\">, and rhp through the import map.";
+  if (/is not a function/.test(message)) return "Check the name and where it comes from: it is not a function there (an import that doesn't exist, or a value used as a function).";
+  if (/Maximum call stack/.test(message)) return "Something calls itself without end: a signal set inside an effect that reads it, or a component that renders itself.";
+
+  return "Fix the code that throws, at the place the message gives.";
+}
+
+// A short "file:line" for the first frame of a stack that is the user's (not rhp's or Solid's)
+export function placeOf(stack, base, map) {
+
+  for (const line of String(stack ?? "").split("\n").slice(1)) {
+    const m = line.match(/\(?((?:file|https?):\/\/[^\s)]+?):(\d+):(\d+)\)?\s*$/);
+    if (!m) continue;
+    const [, url, row, col] = m;
+    if (map && url.includes("/__rhp/bundle.js")) {
+      const at = map(+row, +col);
+      if (at && !/node_modules|rhp-check|\/dist\/source\/|\/src\/guard\//.test(at.source)) return `${at.source.replace(/^.*\//, "")}:${at.line}:${at.column}`;
+      continue;
+    }
+    if (/cdn\.jsdelivr|unpkg\.com|esm\.sh/.test(url)) continue;
+    return `${decodeURIComponent(url.replace(/^.*\//, ""))}:${row}:${col}`;
+  }
+
+  return "";
+}