@bezda/rhp-mcp 0.0.0-stage → 0.1.1

package/skill/references/looks.md

@@ -0,0 +1,267 @@
+# Looks: eight written out in full
+
+Eight looks for an editorial poster, each written out in full: tokens, fonts, paper texture, type and one ornament.
+Each goes on top of the base CSS and reads the tokens of design.md section 1, and each was tested on two recipes with the checker at 1280px and 390px.
+
+They are worked examples, not a menu.
+A look picked because it matches the topic (newsprint for anything in the news, a dark screen for anything technical) gives the chart the look every chart on that topic gets, and a reader sees the template.
+A look is also only the palette and the type (decisions 4 and 5 of design.md section 2): the idea, the marks and the composition are not in it.
+So write the look for your subject, and take from these what is hard to get right: paper and ink values that pass the contrast floors, a texture, the CSS of a key or a button group.
+design.md section 3 says how a look goes onto a page.
+
+| Look | The object it is taken from | Tested on |
+|---|---|---|
+| Broadsheet | a newspaper's front page | bar, diverging-bars |
+| Swiss grid | a 1960s typographic poster | stacked-100 (light and dark), stacked-bars |
+| Field guide | a naturalist's plate | column, waffle |
+| Luxury magazine | a fashion monthly's feature page | donut, waterfall |
+| Sports page | a matchday programme | race, grouped-bars |
+| Scientific figure | a journal's figure | pyramid, sparklines |
+| Night instrument | a cockpit display after dark | heatmap, area |
+| Photocopied zine | a stapled fanzine | lollipop, radial-bars |
+
+## Broadsheet
+
+Newsprint with a fine halftone, black ink and one spot blue, a condensed serif headline under the masthead's double rule.
+Marks: flat, square-ended bars (`--rhp-radius: 0px`), the story in the spot blue, a second series in orange, the rest grey.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Libre+Franklin:wght@400..800&family=Noto+Serif+Display:wdth,wght@62.5..100,500..800&display=swap">
+```
+
+```css
+/* Look: Broadsheet */
+:root {
+  --page: #d5d3cc; --paper: #f3f2ed; --ink: #151515; --soft: #64625c; --rule: #d3d1ca;
+  --accent: #1d58a8; --s2: #ca4a07; --s3: #262626; --quiet: #868580;
+  --display: "Noto Serif Display", Georgia, "Times New Roman", serif;
+  --text: "Libre Franklin", "Franklin Gothic Medium", Arial, sans-serif;
+}
+.poster { border-top: 6px solid var(--ink); box-shadow: inset 0 3px var(--paper), inset 0 4px var(--ink);
+  background-image: radial-gradient(rgb(0 0 0 / .05) .6px, transparent .9px); background-size: 3px 3px; }
+.poster .kicker { letter-spacing: .1em; }
+.poster .headline { font: 700 condensed clamp(42px, 6.5vw, 62px)/.96 var(--display); max-width: 16em; }
+.poster .dek { font-size: 18px; color: var(--ink); }
+.poster .note { border-top-color: var(--ink); }
+.poster .keys { font-size: 13px; font-weight: 600; }
+.poster .choice button { border-color: var(--ink); font: 700 12px/1 var(--text); letter-spacing: .08em; text-transform: uppercase; }
+```
+
+## Swiss grid
+
+The International Typographic Style: white stock with its twelve columns showing faintly, one strict left edge, a large grotesk, red and black.
+Marks: thick square bars, red for the story, black (`series-2`) for a second series, grey for the rest.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Host+Grotesk:wght@400..800&display=swap">
+```
+
+```css
+/* Look: Swiss grid */
+:root {
+  --page: #d9d9d5; --paper: #f7f7f4; --ink: #111111; --soft: #676765; --rule: #d6d6d3;
+  --accent: #ca2218; --s2: #1c1c1c; --s3: #2a5bd7; --quiet: #888887;
+  --display: "Host Grotesk", "Helvetica Neue", Helvetica, Arial, sans-serif; --text: var(--display);
+}
+.poster { background-image: repeating-linear-gradient(90deg, rgb(0 0 0 / .035) 0 1px, transparent 1px calc(100% / 12)); background-origin: content-box; }
+.poster .rhp-chart { background-color: var(--paper); }
+.poster .kicker { display: flex; align-items: center; gap: 10px; font-size: 13px; letter-spacing: .02em; text-transform: none; color: var(--ink); }
+.poster .kicker::before { content: ""; flex: none; width: 14px; height: 14px; background: var(--accent); }
+.poster .headline { font: 800 clamp(44px, 7.3vw, 70px)/.94 var(--display); letter-spacing: -.035em; max-width: 12em; }
+.poster .dek { max-width: 46ch; font-size: 18px; line-height: 1.45; color: var(--ink); }
+.poster .note { border-top: 2px solid var(--ink); }
+.poster .keys i { width: 14px; height: 14px; }
+.poster .choice button { margin-left: -2px; border: 2px solid var(--ink); font-weight: 700; }
+.poster .choice button[aria-pressed="true"] { background: var(--accent); border-color: var(--accent); color: var(--paper); }
+```
+
+## Field guide
+
+A naturalist's plate: ivory stock with faint foxing, a ruled plate frame, a bookish serif with italics for names, earth inks.
+Marks: flat earth inks, hairline outlines for containers (a gauge's tube), names of species in italics (`<em>`).
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Alegreya:ital,wght@0,400..800;1,400..800&family=Alegreya+Sans:wght@400;500;700&display=swap">
+```
+
+```css
+/* Look: Field guide */
+:root {
+  --page: #cfcbbf; --paper: #f2f0e8; --ink: #22201b; --soft: #66615a; --rule: #d6d1c4;
+  --accent: #a73703; --s2: #3a6b8f; --s3: #56644f; --quiet: #87847c;
+  --display: Alegreya, "Iowan Old Style", Georgia, serif; --text: "Alegreya Sans", "Gill Sans", "Trebuchet MS", sans-serif;
+}
+.poster { box-shadow: inset 0 0 0 14px var(--paper), inset 0 0 0 15px var(--soft), inset 0 0 0 18px var(--paper), inset 0 0 0 19px var(--rule);
+  background-image: radial-gradient(circle at 14% 22%, rgb(120 100 70 / .07), transparent 16%), radial-gradient(circle at 86% 78%, rgb(120 100 70 / .06), transparent 20%), radial-gradient(circle at 64% 8%, rgb(120 100 70 / .05), transparent 9%); }
+.poster .kicker { font-size: 13px; letter-spacing: .18em; }
+.poster .headline { font: 800 clamp(38px, 5.6vw, 54px)/1.02 var(--display); letter-spacing: -.01em; }
+.poster .dek { font: 400 19px/1.45 var(--display); }
+.poster .note { border-top: 0; font: italic 13px/1.5 var(--display); }
+.poster .keys i { border-radius: 50%; }
+.poster .choice button { border-color: var(--ink); font: 700 12px/1 var(--text); letter-spacing: .1em; text-transform: uppercase; }
+@media (max-width: 640px) {
+  .poster { box-shadow: inset 0 0 0 7px var(--paper), inset 0 0 0 8px var(--soft); }
+}
+```
+
+## Luxury magazine
+
+A fashion or travel monthly: bone stock with a linen weave, a high-contrast serif at large sizes, wide margins, letterspaced capitals, one deep color.
+Marks: square-ended bars (`--rhp-radius: 0px`), the story in the deep red, the rest in petrol and grey, large italic numbers for the key value.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Playfair:ital,opsz,wght@0,5..1200,300..800;1,5..1200,300..800&family=Urbanist:wght@400..700&display=swap">
+```
+
+```css
+/* Look: Luxury magazine */
+:root {
+  --page: #24211e; --paper: #f6f4ef; --ink: #15120f; --soft: #68625a; --rule: #ddd8ce;
+  --accent: #8a1c2f; --s2: #a57d3d; --s3: #2f4b5f; --quiet: #898682;
+  --display: Playfair, "Bodoni 72", Didot, "Times New Roman", serif; --text: Urbanist, "Avenir Next", "Century Gothic", sans-serif;
+}
+.poster { padding: 72px 80px 40px;
+  background-image: repeating-linear-gradient(0deg, rgb(40 30 20 / .035) 0 1px, transparent 1px 3px), repeating-linear-gradient(90deg, rgb(40 30 20 / .035) 0 1px, transparent 1px 3px); }
+.poster figcaption { gap: 18px; margin-bottom: 44px; }
+.poster .kicker { font: 600 11px/1.6 var(--text); letter-spacing: .32em; color: var(--ink); }
+.poster .kicker::before { content: ""; display: block; width: 56px; height: 1px; margin-bottom: 16px; background: currentColor; }
+.poster .headline { font: 400 clamp(46px, 8.1vw, 78px)/.96 var(--display); letter-spacing: -.02em; max-width: 11em; }
+.poster .headline em { color: var(--accent); }
+.poster .dek { max-width: 42ch; font: italic 400 21px/1.45 var(--display); }
+.poster .note { margin-top: 40px; border-top: 0; font: 500 11px/1.6 var(--text); letter-spacing: .04em; }
+.poster .keys { font: 600 11px/1.3 var(--text); letter-spacing: .2em; text-transform: uppercase; }
+.poster .keys i { width: 22px; height: 2px; vertical-align: 3px; }
+.poster .choice button { min-width: 24px; margin: 0 20px 0 0; padding: 8px 0; border: 0; border-bottom: 1px solid transparent; font: 600 12px/1 var(--text); letter-spacing: .24em; text-transform: uppercase; color: var(--soft); }
+.poster .choice button[aria-pressed="true"] { background: none; border-bottom-color: var(--ink); color: var(--ink); }
+@media (max-width: 640px) {
+  .poster { padding: 36px 20px 22px; }
+  .poster figcaption { margin-bottom: 28px; }
+  .poster .dek { font-size: 17px; }
+}
+```
+
+## Sports page
+
+A matchday programme: slanted extra-condensed capitals, speed stripes along the top, a jersey-mesh weave, racing orange and navy.
+Marks: bars with a slanted end (`shape=${SLANT}` with `const SLANT = shape(["M", 0, 0], ["L", 1, 0], ["L", "-8px", 1], ["L", 0, 1], ["Z"])`), big tabular numbers, the leader in the accent.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Sofia+Sans+Extra+Condensed:ital,wght@0,700..900;1,700..900&family=Sofia+Sans:ital,wght@0,400..800;1,800&display=swap">
+```
+
+```css
+/* Look: Sports page */
+:root {
+  --page: #c8cacb; --paper: #f3f3f0; --ink: #121418; --soft: #616468; --rule: #d5d6d4;
+  --accent: #b83900; --s2: #1d3b8f; --s3: #257656; --quiet: #858686;
+  --display: "Sofia Sans Extra Condensed", "Arial Narrow", Impact, sans-serif; --text: "Sofia Sans", "Segoe UI", Arial, sans-serif;
+}
+.poster { position: relative; padding-top: 58px;
+  background-image: radial-gradient(rgb(0 0 0 / .05) 1px, transparent 1.4px), radial-gradient(rgb(0 0 0 / .05) 1px, transparent 1.4px);
+  background-size: 6px 6px; background-position: 0 0, 3px 3px; }
+.poster::before { content: ""; position: absolute; inset: 0 0 auto; height: 12px; background: repeating-linear-gradient(-60deg, var(--accent) 0 14px, transparent 14px 24px); }
+.poster .kicker { font: italic 800 14px/1.2 var(--text); letter-spacing: .06em; }
+.poster .headline { font: italic 900 clamp(54px, 8.75vw, 84px)/.86 var(--display); text-transform: uppercase; max-width: 13em; }
+.poster .note { border-top: 3px solid var(--ink); font-weight: 500; }
+.poster .keys { font: 800 13px/1.2 var(--text); letter-spacing: .04em; text-transform: uppercase; }
+.poster .keys i { width: 18px; height: 10px; transform: skewX(-20deg); }
+.poster .choice { gap: 4px; }
+.poster .choice button { margin: 0; padding: 9px 14px; border: 0; background: var(--rule); font: italic 800 14px/1 var(--text); text-transform: uppercase; }
+@media (max-width: 640px) {
+  .poster { padding-top: 34px; }
+  .poster::before { height: 8px; }
+}
+```
+
+## Scientific figure
+
+A journal's figure: white coated stock, a figure label, a plain sans for the figure and a serif for its caption, colors that hold for color-blind readers.
+Marks: thin lines, small dots and square bars, the accent on what the finding is about, `n` and the method in the note.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400..700&family=STIX+Two+Text:ital,wght@0,400..700;1,400&display=swap">
+```
+
+```css
+/* Look: Scientific figure */
+:root {
+  --page: #e6e7e9; --paper: #ffffff; --ink: #1a1c1f; --soft: #63676d; --rule: #e1e3e6;
+  --accent: #b45000; --s2: #3563d0; --s3: #18805f; --quiet: #8d8e8f;
+  --display: "IBM Plex Sans", "Helvetica Neue", Arial, sans-serif; --text: var(--display); --caption: "STIX Two Text", "Times New Roman", serif;
+}
+.poster { max-width: 880px; border: 1px solid #d3d6da; background-image: linear-gradient(170deg, #ffffff 50%, #f6f7f8); }
+.poster .kicker { width: fit-content; padding: 3px 8px; background: var(--ink); color: var(--paper); font-size: 12px; letter-spacing: .06em; }
+.poster .headline { font: 700 clamp(26px, 3.6vw, 34px)/1.14 var(--display); letter-spacing: -.01em; max-width: 24em; }
+.poster .dek { max-width: 66ch; font: 400 17px/1.5 var(--caption); color: var(--ink); }
+.poster .note { font: 400 13px/1.5 var(--caption); }
+.poster .keys { font-size: 13px; }
+.poster .keys i { border-radius: 50%; }
+.poster .choice button { border-color: #aab0b8; font-weight: 500; font-size: 13px; }
+.poster .choice button:first-child { border-radius: 4px 0 0 4px; }
+.poster .choice button:last-child { border-radius: 0 4px 4px 0; }
+```
+
+## Night instrument
+
+A cockpit display after dark: graphite glass with a fine screen mesh, corner brackets, a typeface made for instruments, amber for what matters.
+Marks: thin lines and small dots, cells from dark to bright (section 4), no glow: a flat bright color on a dark ground is already the brightest thing on the page.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=B612:wght@400;700&family=B612+Mono&display=swap">
+```
+
+```css
+/* Look: Night instrument */
+:root {
+  color-scheme: dark;
+  --page: #070708; --paper: #121314; --ink: #e8eaec; --soft: #8f9499; --rule: #2e3134;
+  --accent: #ffb020; --s2: #69ddfc; --s3: #d26eca; --quiet: #666769;
+  --display: B612, "Segoe UI", system-ui, sans-serif; --text: var(--display); --mono: "B612 Mono", ui-monospace, Menlo, monospace;
+}
+.poster { position: relative; border-radius: 4px;
+  background-image: radial-gradient(rgb(255 255 255 / .035) .6px, transparent .9px), radial-gradient(ellipse at 50% 0%, rgb(255 255 255 / .05), transparent 70%);
+  background-size: 4px 4px, 100% 100%; }
+.poster::before { content: ""; position: absolute; inset: 12px; border: 1px solid var(--soft); pointer-events: none;
+  mask: conic-gradient(at 18px 18px, transparent 75%, #000 0) 0 0 / calc(100% - 18px) calc(100% - 18px); }
+.poster .kicker { font: 400 12px/1.3 var(--mono); letter-spacing: .16em; }
+.poster .headline { font: 700 clamp(30px, 4.6vw, 44px)/1.08 var(--display); letter-spacing: -.01em; }
+.poster .note { border-top-style: dashed; font-size: 12px; }
+.poster .keys { font: 400 12px/1.3 var(--mono); letter-spacing: .06em; text-transform: uppercase; }
+.poster .keys i { width: 14px; height: 3px; vertical-align: 3px; }
+.poster .choice button { border-color: var(--rule); font: 400 12px/1 var(--mono); letter-spacing: .08em; text-transform: uppercase; color: var(--soft); }
+.poster .choice button[aria-pressed="true"] { background: none; border-color: var(--accent); color: var(--accent); }
+.poster :focus-visible { outline-color: var(--accent); }
+@media (max-width: 640px) {
+  .poster::before { inset: 6px; }
+}
+```
+
+## Photocopied zine
+
+A stapled fanzine: speckled copier paper with a dark copier edge, the headline cut out on a black strip, typewriter text, one hot pink.
+Marks: black for most marks, pink for the one value that matters, dotted stems like a photocopied leader line.
+
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Anton&family=Courier+Prime:wght@400;700&display=swap">
+```
+
+```css
+/* Look: Photocopied zine */
+:root {
+  --page: #3a3936; --paper: #f1f0ec; --ink: #121212; --soft: #62615d; --rule: #cfcdc8;
+  --accent: #c30f59; --s2: #1f3fd1; --s3: #121212; --quiet: #848482;
+  --display: Anton, Impact, "Arial Black", sans-serif; --text: "Courier Prime", "Courier New", monospace;
+}
+.poster { position: relative; box-shadow: inset 16px 0 22px -16px rgb(0 0 0 / .22);
+  background-image: radial-gradient(rgb(0 0 0 / .3) .5px, transparent .9px), radial-gradient(rgb(0 0 0 / .22) .6px, transparent 1px), radial-gradient(rgb(0 0 0 / .26) .4px, transparent .8px), radial-gradient(rgb(0 0 0 / .18) .7px, transparent 1.1px);
+  background-size: 23px 31px, 47px 37px, 61px 89px, 113px 71px; background-position: 0 0, 17px 9px, 31px 52px, 7px 40px; }
+.poster::before { content: ""; position: absolute; top: 14px; left: 30px; width: 36px; height: 4px; border-radius: 1px; background: #8d8d8d; rotate: -6deg; }
+.poster .rhp-chart { background-color: var(--paper); }
+.poster .kicker { width: fit-content; padding: 3px 8px; background: var(--accent); color: var(--paper); letter-spacing: .08em; }
+.poster .headline { width: fit-content; max-width: 100%; padding: .04em .18em .08em; background: var(--ink); color: var(--paper); font: 400 clamp(40px, 6.5vw, 62px)/1.06 var(--display); text-transform: uppercase; text-wrap: wrap; rotate: -1deg; }
+.poster .dek { color: var(--ink); }
+.poster .note { border-top: 2px dashed var(--ink); }
+.poster .keys { font-size: 13px; font-weight: 700; }
+.poster .keys i { border: 1.5px solid var(--ink); }
+.poster .choice button { margin-left: -2px; border: 2px solid var(--ink); font-weight: 700; text-transform: uppercase; }
+```

package/skill/references/pitfalls.md

@@ -0,0 +1,202 @@
+# rhp pitfalls: symptoms, causes and fixes
+
+Use this file when a chart does not look or behave as it should, or when the checker reports a finding you do not understand.
+Find the symptom, then try its causes in order.
+Every cause here was reproduced with rhp 2.0.1; the numbers in brackets point to the "Gotchas" list at the end of [api.md](api.md).
+
+## Contents
+
+- Mistakes that come from other libraries
+- Nothing draws, or the chart is empty
+- Bars, dots or labels in the wrong place
+- Text sticks out, is cut off or overlaps
+- The chart is tiny, squashed or the wrong size
+- Values never update, or the chart jumps
+- A click, hover, tap or key does nothing, or the wrong thing
+- The layout jumps when the reader interacts
+- Text and layers laid over the chart
+- Styles or colors do not apply
+- Console warnings rhp prints
+- Mistakes in the work itself
+
+## Mistakes that come from other libraries
+
+rhp is not configured with an options object, and none of these exist: `<BarChart data=...>`, `<Chart type="bar">`, `series: [{ data }]`, `new Chart(ctx, config)`, `xAxis`, `yAxis`, `tooltip: { ... }`, `legend: { ... }`.
+A chart is a `Chart` holding `Plot`s, each Plot draws one slat per row of data, and the slat is a function you write from blocks.
+Start from a recipe, never from what another library does.
+
+- **rhp 1 code** (`react-html-plots`, Legend-State observables, `@bezda/rhp-core`, `BarPlot`, `useObservable`): a different, retired library. Use rhp 2 only, from `@bezda/rhp@2`.
+- **React JSX around rhp components** (`<Bar to={d.sold} />` inside a React component): React does not render Solid components. In React, write the chart with the `html` template from `@bezda/rhp/standalone` and mount it into an element (environments.md, React).
+- **`solid-js` imported in a React, Vue or plain page** next to `@bezda/rhp/standalone`: two copies of Solid, and reactivity silently stops between them. Import everything from the standalone module.
+- **`useState` or `useEffect` inside an rhp chart component**: use `createSignal`, `createMemo`, `createEffect` and `onCleanup` from the same module as rhp.
+- **A tooltip library or an SVG overlay**: rhp charts are HTML. Show a readout with a signal and `Show` inside the slat, or in the poster's dek (interaction.md).
+
+## Nothing draws, or the chart is empty
+
+1. **The module failed to load.** An error like "does not provide an export named createSelector": the standalone module has no `Dynamic`, `Portal`, `createResource` or `ErrorBoundary`, and rhp 2.0.1 also lacks `createSelector`, `createComputed`, `on`, `mergeProps`, `splitProps`, `Switch` and `Match`, which 2.0.2 adds [28]. Return the template from a function for `Dynamic`, `render()` into the other element for `Portal`, fetch in `onMount` for `createResource`, and compare in a function (`on=${(d) => on() === d.index}`) on any version.
+2. **The import map is missing or below the module script.** It must come before any `<script type="module">` and map `@bezda/rhp/standalone` to `https://cdn.jsdelivr.net/npm/@bezda/rhp@2/dist/standalone.js`.
+3. **`render` got the result instead of a function.** Write ``render(() => html`<${MyChart} />`, element)``.
+4. **The slat returns two elements, text, or nothing** [30]. Return one root element (`<div>`) holding the blocks.
+5. **The Plot is outside a Chart** [29], or the Plot got the bare function instead of what `slat()` returned (the slat then has no CSS or layout).
+6. **Data groups are empty** or the Plot has none of the names the slat reads: every slat reads `undefined` and draws at the start of the scale [16]. Check the names: `d.sold` needs a Plot prop `sold`; a list of objects goes in `rows`, not `data` [7].
+
+## Bars, dots or labels in the wrong place
+
+1. **The scale does not hold the data** [13]: bars are cut at the end, dots and ticks land outside the plot.
+   Build it from the data: `const s = nice(Math.min(0, ...values), Math.max(0, ...values))`, then `scale=${[s.min, s.max]} ticks=${s.ticks}`.
+2. **Negative values on a scale that starts at 0**: a value below the scale's min draws nothing; the scale above takes its min below 0.
+   A Bar whose `to` is below its `from` runs backward.
+3. **Area or Line points past the scale squeeze the whole outline** [14]: keep every x inside the scale; give `density()` a `domain` inside it.
+4. **A reversed or equal scale** (`[100, 0]`, `[5, 5]`) draws nothing [15]. For bars that run the other way, use negative values and print them with `format=${(v) => Math.abs(v)}`.
+5. **NaN, undefined or null** draw at the scale's start and print "NaN" [16]: clean or filter the data first.
+6. **Every slat got one item of a list meant for all of them**: an array given to a Plot is a column, item i for row i. To give every slat the same list (the series still shown, a set of picked names), pass a function of the row: `shown=${(d) => shown()}`.
+7. **Lists of different lengths** wrap around without an error [8]: the third slat of a 3-item list shown beside a 5-item list repeats the first values. Give every data group the same length.
+8. **A Dot is an oval**: its `size` was a number [17].
+   Give a length, `size="12px"`.
+   `ManyDots` has a different size contract: its numbers mean pixels, so `size=${12}` is a 12px point.
+9. **A vertical Plot over a horizontal chart draws 0px-tall columns**: in rhp 2.0.1, a second top-level Plot with `orientation="vertical"` in a horizontal Chart whose slat type has `room: "auto"` gets columns as wide as the chart and no height. Give the slats room in px, or put the Plot in a chart with `cross` (as the line recipe does).
+10. **A scatter or line chart puts everything on one line**: with Dot slats, the Chart needs `cross=${[min, max]}`, the Plot needs `overlap=${true}`, and each Dot needs `cross=${() => d.y}`.
+    The experimental [ManyDots collection](api.md#manydots-experimental-point-collection) goes directly inside a Chart with `cross` and takes its own `rows`, `at`, and `cross` accessors.
+
+## Text sticks out, is cut off or overlaps
+
+1. **Value labels past the bars stick out at the end**: `room.end` is too small, or a `room` you gave dropped the defaults [10]. Give every side you use, in px: `room: { start: 120, end: 56 }`.
+2. **Names are cut off or stick out at the start**: give `room.start` in px, or `"auto"` with the edge Labels as direct children of the slat's root [11]; cap long names with `max-width` and an ellipsis in the slat CSS, or let them wrap.
+3. **Names under a vertical chart end in "..."** [25]: they are as wide as their columns. Shorten them, let them wrap (`.name:vertical { white-space: normal; }`), or make the chart horizontal on phones.
+4. **Axis numbers stick out** [12]: the axis has fixed room, so keep `format` short ("1.2M", not "1,200,000 people").
+5. **Labels of neighboring slats overlap**: the slats are too thin for their text. Raise `thickness`, shorten the labels, show fewer of them (only the highlighted slat, or every other one), or turn the chart.
+6. **A label overlaps its own bar's end**: give the slat CSS `--rhp-label-gap` (the space between a Label and its value).
+7. **The value label of the longest bar runs into the next column or out of the chart**: leave headroom on the scale (build it from about 1.1 times the largest value with `nice()`), or give `room.end` its width.
+8. **Wide numbers on a cross axis stick out on the left**: the cross axis gets 42px for its numbers; numbers such as 30,000 need the slat type's `room.start` at about 48px.
+9. **A value Label over the last column of a vertical chart sticks out**: give `room.after` half the label's width.
+10. **Text overlaps on a phone only**: test at 390px. Use a media query or a container query on the page for the poster, and `:vertical` / `:horizontal` rules for the slat.
+11. **Two words run together in a readout** ("All regions12") [35]: Solid's html template drops a space that stands alone between two tags. Write it as `${" "}`.
+12. **The first or last name under a column sticks out of the chart**: a label centered under its column with `translate: -50%` runs past the plot's ends.
+    Align the first one's start and the last one's end with the plot, or give `room.before` and `room.after` half its width.
+13. **Axis numbers run together at 320px**: the names' and the values' room leave a narrow plot.
+    Give the Chart fewer ticks when the window is narrow (`ticks=${() => (narrow() ? every(10) : every(5))}`, with `narrow` a signal from `matchMedia("(max-width: 400px)")`), shorter numbers, or less room.
+14. **Small parts lose their names**: hiding a label that does not fit is never the only fallback.
+    Put it outside its mark with a short leader, or in a key beside the chart in the marks' order; on a phone use short codes before dropping names (design.md section 7).
+
+## The chart is tiny, squashed or the wrong size
+
+1. **It is 148px wide with an empty plot** [24]: it sits in a flex row, an `inline-block`, a float or a `fit-content` box. Give its wrapper `flex: 1; min-width: 0`, or a width.
+2. **A vertical chart is a flat strip**: it is 240px tall by default; set `height`.
+3. **A horizontal chart's slats are 32px thick and the chart is too tall or too short**: set `thickness` on the slat type, or `height` on the Chart to make slats share it.
+4. **The chart keeps a shape on every screen**: `aspect` on the Chart keeps width over height, and ignores `height` (rhp warns).
+
+## Values never update, or the chart jumps
+
+1. **`${d.sold}` was read once** [3]: wrap it, `${() => d.sold}`; never destructure `d`.
+2. **The Plot got a signal's value once**: pass the accessor (`sold=${sold}`) or a function (`sold=${() => data().sold}`), not `sold=${sold()}` at the top of a component that runs once.
+3. **The Chart is `static`** [33]: a static chart ignores signals other than its data. Remove `static` from interactive charts.
+4. **Slats swap data when rows are removed**: give the Plot a `key` (`key="city"`).
+5. **Blocks jump to new values instead of moving** [22]: a `transition` on a block replaces rhp's own. Put your transition on an element inside the block.
+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.
+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.
+
+## A click, hover, tap or key does nothing, or the wrong thing
+
+1. **A handler on a component has no parameter** [2]: `onClick=${() => pick()}` runs while drawing and is never attached. Write `onClick=${(e) => pick()}`. This holds for blocks and the Poster; plain elements are fine, and the Chart takes no handler at all (next item).
+2. **The handler is on the Chart** [6]: the Chart drops handlers, `data-*` and `title`. Put them on the Poster or a wrapper element.
+3. **A bare boolean** [1]: `<${Plot} keyboard>` passes an empty string, which is false. Write `keyboard=${true}` (also `overlap`, `static`, `animate`, `mirror`, `fill`, `smooth`).
+4. **An overlay Plot covers the slats under it**: give it `style=${{ "pointer-events": "none" }}` (an object: a string is dropped on Chart and Plot [4]).
+5. **The row is lost**: put `data-row=${() => d.index}` on the slat's root and find it with `e.target.closest("[data-row]")` from one handler on the poster.
+6. **A scroll on a phone changes the pick, or the readout flickers between slats**: the pick runs on `pointerdown` or on a finger's `pointermove` (every scroll starts with both), or it clears when the pointer is on no slat.
+   Pick on `pointermove` only for a mouse or a pen (`e.pointerType !== "touch"`), on `click` for a tap or a click, and on `focusin` for the keyboard; leave the pick as it is on no slat, and clear it on `pointerleave` and `focusout` (interaction.md, section 2).
+7. **The keyboard cannot reach it**: add `keyboard=${true}` to the Plot whose slats are interactive, and handle `focusin` like `pointermove`.
+8. **A focus handler throws on some elements**: `e.target.closest("[data-row]")` can return null; check it before reading `dataset`.
+9. **The chart vanished for screen readers**: `role="slider"` makes everything inside it presentational, so it must never wrap the chart; put it on its own element.
+10. **A slider has no name for screen readers**: an `<output>` inside the `<label>` takes the label from the input, because an output is labelable too. Show the value in a `<span>` or `<b>` with `aria-hidden="true"` and give the input `aria-valuetext`.
+
+## 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.
+
+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.
+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.
+
+## Text and layers laid over the chart
+
+A bold composition sets a headline, a picture or a key over the plot's empty part.
+These are the traps it brings.
+
+1. **A focus ring strikes through the text laid over the plot**: an outline on the slat's root runs the whole length of the plot.
+   Draw the ring on the mark instead: `.slat:focus-visible { outline: none; }` and `.slat:focus-visible .bar { outline: 2px solid var(--rhp-ink); outline-offset: 2px; }`, with `class="bar"` on the Bar.
+   A mark that wears a `shape()` or a mask shows no outline, because both cut it away: ring the slat's name instead (`.slat:focus-visible .name { outline: 2px solid var(--rhp-ink); outline-offset: 3px; }`), as `silhouettes` does.
+   Never take the slat's ring away without drawing another.
+2. **Gridlines run through the value labels**: a label just past a bar's end sits on the next gridline when the value is near a tick.
+   Give the number the paper as its background, on a span inside the Label so the Label keeps the gap rhp gives it (its own padding): `<${Label} at=${() => d.v} class="value"><span class="num">${() => d.v}</span><//>`, with `.num { margin: 0 -3px; padding: 0 3px; background: var(--rhp-surface); }` in the slat's css.
+   The grid is drawn under the slats, so the line stops at the text.
+   The theme's `surface` must be the paper (`surface: "var(--paper)"`; it is white by default), and the box suits a flat paper only: over a grain or a texture it shows as a patch.
+   Not next to a reference line, which stays whole (design.md section 7).
+3. **Taps on the marks pick nothing**: a layer laid over the chart (a picture, a glow, a caption box) takes every pointer event when it is drawn above rhp's plot (`z-index: 1`): at `z-index: 2` or more, or at 1 after the Plot in the page.
+   Give it `pointer-events: none`.
+   What the reader presses must be the slat or an element inside it: a mark that takes no pointer events sends the press to the chart under it, which cannot take focus, so the focused slat loses focus and the pick clears.
+   Give the mark `pointer-events: auto` (`donut`), or, when the chart picks by the pointer's place, put `onMouseDown=${(e) => e.preventDefault()}` on the element under the marks (`dial`).
+4. **The text laid over the plot runs into the marks with other data**: its place was set by hand (a fixed `top`, a share of the width) for these values.
+   Set it for your data, then check a copy whose values all sit near the largest, so the plot has no empty part, at every width, and look at the screenshots: the checker reports words over value labels, not words over bare marks.
+   Where the words meet a mark, set them above the chart at that width.
+
+## Styles or colors do not apply
+
+1. **Page CSS aimed at bars, labels or the axis** [21]: it cannot change their color, background, font, border, radius, shadow, padding or transition, even with `!important`. Move those rules into the slat type's `css`.
+2. **`className`** [5]: on a block it replaces rhp's class and the block vanishes. Use `class`.
+3. **The chart ignores the page's font or colors** [20]: give them in the Chart's `theme` (`font`, `ink`, `muted`, `grid`, `series`, ...).
+4. **`var(--brand)` as a color warns** [20]: put the brand colors in the theme instead.
+5. **Rows 5 and 6 take the first series color** [18]: `series()` counts six colors; with a shorter theme list call `series(n)`.
+6. **A value label does not take its bar's color** [19]: set `--rhp-color` on the slat's root in a style object (and leave `color` off the Bar), or color the label itself.
+7. **The poster looks unstyled** [31]: the Poster brings no CSS. Style `.poster`, `figcaption`, `.kicker`, `.headline`, `.dek` and `.note` in the page.
+8. **Focus rings on slats do not show your style** [22]: rhp's core CSS resets `outline` on slat roots, so a page `:focus-visible` rule never reaches them. Put `.slat:focus-visible { ... }` in the slat type's `css`.
+9. **The poster's styles do not apply inside a framework component**: scoped component styles (Vue `scoped`, Svelte, Astro, Angular's emulated encapsulation) never reach elements rhp makes. Use a plain CSS file; environments.md section 14 has every framework's verified caveats.
+10. **Padding on the chart's element does nothing**: rhp's room owns it. Pad a wrapper instead.
+11. **A white label is unreadable on some segments**: a label needs 4.5:1 on each segment's color. Darkening a segment can break the color-blind check against its neighbor, so switch that label to the ink color instead.
+12. **A transition on the slat's root does nothing** [22]: rhp keeps the root's own transition (its slide). Transition an element inside a block instead.
+13. **A rule in the slat's CSS matches nothing**: the class is on a different element than you think. Classes you put on blocks go on the block's own element (`.rhp-bar.bar`); `:horizontal` and `:vertical` go on the slat or a block, not on an element inside a block.
+14. **A pinned readout or a menu over the chart is drawn under the bars** [36]: give it `z-index: 2` or more.
+15. **The marks are invisible when the component is shown on its own**: its theme reads the app's variables with no fallback (`series: ["var(--chart-1)", …]`), so on a page without the app's CSS (the checker's page, a test, Storybook) every mark is transparent.
+    Give each a fallback with the app's own value: `"var(--chart-1, oklch(0.646 0.222 41.116))"` (design.md section 8).
+
+## Console warnings rhp prints
+
+Each is worth fixing [34]:
+
+| Warning starts with | Fix |
+|---|---|
+| "a Bar is a slat's root here" (or Dot, Label...) | wrap the block in an element: ``(d) => html`<div><${Bar} .../></div>` `` |
+| "an edge Label is inside another element" | make the edge Label a direct child of the slat's root, or give room in px |
+| "aspect takes a number above 0" | `aspect=${16 / 9}` |
+| "a Chart with an aspect takes its height from its width" | remove `height` |
+| "a flat Chart with an aspect has rows with a thickness" | remove `thickness` from the slat type |
+| "... reads a page variable; use a theme key" | put the color in the Chart's `theme` and use its key |
+| "--rhp-radius takes one length" | one length, or `--rhp-start-radius` and `--rhp-end-radius` |
+| "unknown ease" | a CSS name, four cubic-bezier numbers, or a function |
+| "linkedCss() was called, but this page doesn't link" | link `@bezda/rhp/rhp.css`, or remove `linkedCss()` |
+
+## Mistakes in the work itself
+
+These are not rhp errors, but they decide whether the user gets what they asked for.
+
+- **Dropping or changing a request**: every explicit request in the brief is in the result, exactly (their colors, their title, their sort order, "no poster"). A warning is fixed without removing a requested feature.
+- **Invented numbers presented as fact**: data you supplied names its source and year, or the note says "Illustrative data".
+- **A series the user did not ask for**: what is left when their parts do not reach 100% is a quiet, unlabeled remainder explained in the note, not a new series with its own color and key entry; the brief lists it under Asked as a deviation.
+- **A headline that is not true for the data**: recompute every number in the headline, the dek and the note from the final data ("four in ten" was false for 52%).
+- **Text computed from data that turns false on other data**: "rose ∞%" from a zero first week, "as many as" for a change from none, "held steady" because the first and last values match after a peak, "led for eight years" counted only inside the chart's window.
+  SKILL.md step 6 has the rules; step 8's hardest data finds them.
+- **Mixed releases**: real yearly figures taken partly from first estimates and partly from later revisions can reverse a move between two years.
+  Take each year from the latest release that covers it.
+- **A real name on invented numbers**: never put a real country, city, company or person on illustrative data; use real figures with their source, or plain invented names ("Riverton", "a monsoon city", "Team A") and say "invented" in the note.
+- **A magazine poster dropped into an app**: inside an existing app, use the app's fonts and colors (design.md).
+- **Hover-only information**: everything a hover shows also shows on focus and on tap.
+- **Not looking at the phone screenshot**: most layout problems appear only at 390px.
+- **Random data in a deliverable**: use fixed numbers unless the user asked for live or generated data.