@bezda/rhp-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 Make charts with [rhp](https://rhp.vercel.app) from any AI agent.
 rhp 2 came out in September 2026, after the training data of today's models, so an agent knows nothing about it until it reads rhp's guide.
-This package carries that guide (the workflow, the references and 30 tested recipes) and a checker that renders the agent's chart in a browser and reports what is wrong, with a fix for each problem and screenshots to look at.
+This package carries that guide (the workflow, the references and the tested recipes) and a checker that renders the agent's chart in a browser and reports what is wrong, with a fix for each problem and screenshots to look at.
 
 ## Start here: the rhp skill
 
@@ -30,6 +30,7 @@ It checks an `.html` page, a Solid or React `.jsx` or `.tsx` component, or a `.j
 | `--widths 1280,390` | The page widths to check; the interactions are tried at the first, and slats are tapped at phone widths (600px or less). |
 | `--dark` | Renders with a dark color scheme. |
 | `--no-interact` | Skips the interactions. |
+| `--settle-timeout <ms>` | How long the page may take to come to rest before it is measured, 100 to 30000 ms (10000 by default); raise it on a slow machine. |
 | `--format <format>` | `html`, `solid`, `react` or `module`, when the file's extension and code leave it unclear. |
 | `--json` | Prints the whole result as JSON. |
 | `--out <dir>` | Where the screenshots go (a folder in the system's temp folder by default). |
@@ -147,9 +148,9 @@ Without `--scope user` it goes to the project's `.gemini/settings.json`.
 | Tool | What it returns |
 |---|---|
 | `rhp_guide` | The workflow from a request to a checked chart, the rules that prevent most bugs, and the names of the references and recipes. The agent calls it first. |
-| `rhp_reference` | One reference by `name`: `api`, `design`, `environments`, `forms`, `interaction` or `pitfalls`. A long one comes back as its list of sections, and `section` (a number or a title) returns one of them. |
+| `rhp_reference` | One reference by `name`: `api`, `design`, `environments`, `forms`, `interaction`, `looks` or `pitfalls`. A long one comes back as its list of sections, and `section` (a number or a title) returns one of them. |
 | `rhp_recipe` | With no `type`, the list of recipes with what each is for; with a `type` such as `bar`, that recipe's whole HTML file, a tested chart page to start from. |
-| `rhp_check` | Renders the chart at `file` (an absolute path) or the `code` given, and returns the report (errors and warnings, each with a fix, and the interactions it tried) and the screenshots as images. Options: `format`, `widths` (`[1280, 390]` by default), `dark`, `interact`. |
+| `rhp_check` | Renders the chart at `file` (an absolute path) or the `code` given, and returns the report (errors and warnings, each with a fix, and the interactions it tried) and the screenshots as images. Options: `format`, `widths` (`[1280, 390]` by default, up to six), `dark`, `interact`, `settleTimeout`. |
 
 `rhp_check` takes absolute paths only: some clients (Codex) start the server in its own folder, where a relative path would point at the wrong file.
 The server also has one prompt, `chart`, which clients show as a slash command: it asks for a chart and tells the agent to follow `rhp_guide` and to check with `rhp_check` until the report is clean.

package/bin/rhp-mcp.js

@@ -14,6 +14,7 @@ const USAGE = `rhp-mcp: make charts with rhp from an AI agent.
       --widths 1280,390       page widths to check (the interaction pass runs at the first)
       --dark                  emulate a dark color scheme
       --no-interact           skip the interaction pass
+      --settle-timeout <ms>   readiness wait budget, 100 to 30000 ms (default 10000)
       --format <format>       html, solid, react or module (found from the file when left out)
       --json                  print the whole result as JSON
       --out <dir>             where the screenshots go (left out: a folder in the system's temp dir, so nothing is
@@ -24,7 +25,7 @@ const USAGE = `rhp-mcp: make charts with rhp from an AI agent.
 `;
 
 const FLAGS = ["--dark", "--no-interact", "--json"];
-const VALUES = ["--widths", "--format", "--out"];
+const VALUES = ["--widths", "--format", "--out", "--settle-timeout"];
 const FORMATS = ["html", "solid", "react", "module"];
 
 function usageError(message) {
@@ -57,9 +58,11 @@ async function runCheck(argv) {
   }
 
   const widths = value["--widths"]?.split(",").map(Number);
+  const settleTimeout = value["--settle-timeout"] === undefined ? undefined : Number(value["--settle-timeout"]);
   if (files.length !== 1) return usageError(files.length ? `check takes one file, not ${files.length}` : "check needs the chart's file");
   if (widths && !widths.every((w) => Number.isInteger(w) && w >= 200 && w <= 2560)) return usageError("--widths takes page widths in px from 200 to 2560, for example 1280,390");
   if (value["--format"] && !FORMATS.includes(value["--format"])) return usageError(`--format is one of ${FORMATS.join(", ")}`);
+  if (settleTimeout !== undefined && (!Number.isInteger(settleTimeout) || settleTimeout < 100 || settleTimeout > 30000)) return usageError("--settle-timeout takes milliseconds from 100 to 30000");
 
   const { check } = await import("../src/check/index.js");
   const result = await check({
@@ -68,6 +71,7 @@ async function runCheck(argv) {
     widths,
     dark: argv.includes("--dark"),
     interact: !argv.includes("--no-interact"),
+    settleTimeout,
     outDir: value["--out"],
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bezda/rhp-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Make charts with rhp from any AI agent: an MCP server with rhp's guide, references and recipes, and a checker that renders a chart in a browser and reports what is wrong, with screenshots",
   "keywords": [
     "rhp",
@@ -47,11 +47,11 @@
   "scripts": {
     "build": "node scripts/build.js",
     "prepack": "npm run build",
-    "test": "node test/mcp.js && node test/run.js"
+    "test": "node test/settle-regression.js && node test/mcp.js && node test/run.js"
   },
   "dependencies": {
     "@babel/core": "^7.29.7",
-    "@bezda/rhp": "^2.0.1",
+    "@bezda/rhp": "^2.0.3",
     "@modelcontextprotocol/sdk": "^1.32.0",
     "babel-preset-solid": "^1.9.15",
     "esbuild": "^0.28.2",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rhp
-description: Makes charts, graphs, plots, infographics and data visualizations with rhp (@bezda/rhp, reactive html plots), charts built from HTML elements and CSS with SolidJS that run in a plain HTML page, React, Next.js, Vue, Svelte, Solid or Astro. Use it whenever the user asks to create, restyle, fix or extend a chart and rhp is the library to use, which is when they name rhp or @bezda/rhp, the project depends on @bezda/rhp, or the project has no chart library yet. Covers bar, column, grouped, stacked, 100% stacked, diverging, waterfall, line, area, scatter, bubble, slope, sparkline, histogram, box, violin, strip, dumbbell, gantt, candlestick, donut, radial, waffle, heatmap, lollipop, bullet and pyramid charts, bar chart races and live data, with magazine-style poster design, interaction, and a tool that renders the chart and reports problems.
+description: Makes charts, graphs, plots, infographics and data visualizations with rhp (@bezda/rhp, reactive html plots), charts built from HTML elements and CSS with SolidJS that run in a plain HTML page, React, Next.js, Vue, Svelte, Solid or Astro. Use it whenever the user asks to create, restyle, fix or extend a chart and rhp is the library to use, which is when they name rhp or @bezda/rhp, the project depends on @bezda/rhp, or the project has no chart library yet. Covers bar, column, grouped, stacked, 100% stacked, diverging, waterfall, line, area, scatter, bubble, slope, sparkline, histogram, box, violin, strip, dumbbell, gantt, candlestick, donut, radial, waffle, heatmap, lollipop, bullet and pyramid charts, dials, log-scale lines, silhouettes to scale, unit stacks, bar chart races and live data, with magazine-style poster design, interaction, and a tool that renders the chart and reports problems.
 license: MIT
 metadata:
   author: Bezda (rhp)
@@ -12,6 +12,8 @@ metadata:
 
 rhp draws charts out of HTML elements placed by CSS.
 You describe one **slat** (the element drawn for one row of data) from a few **blocks** (Bar, Dot, Tick, Label, Cell, Place, Area, Line), and rhp draws a slat for every row of the data and keeps each one in its place.
+For bulk scatter points, the experimental [`ManyDots` collection](references/api.md#manydots-experimental-point-collection) can draw plain HTML points directly inside a Chart with `cross`, without a Plot or a slat per point.
+Use a repository build that exports it; a version-2 package or CDN URL alone does not establish prototype availability.
 
 **You do not know rhp yet.**
 rhp 2 was written in September 2026, after your training data.
@@ -32,11 +34,19 @@ Asked (must all be in the result):
 - "<the user's words>" -> what that means for the chart
 - ...
 Chosen (the user left these open):
-- form, environment and file, data, look, interaction, motion (CSS by default; JS for data that changes rapidly), size
+- form, environment and file, data, interaction, motion (CSS by default; JS for data that changes rapidly), size
+Design (from the subject; none of it the starting recipe's):
+- Idea: the subject's own shape, object or way of drawing this data, and how it helps the reading
+- Marks: how each mark is drawn to carry the idea
+- Composition: where the headline, the chart and the other parts sit, on a desktop and on a phone
+- Palette: the paper, the ink, the accent, and where each comes from
+- Type: the faces, and why these
 ```
 
 - Put under **Asked** every explicit request, quoting the user's words: the data and its numbers, the chart type, titles and text, colors, fonts, size, orientation, sort order, labels, legend, interactions, animation, framework, file name, and anything they said not to do.
 - Everything else goes under **Chosen**, filled with the defaults below.
+- The five **Design** lines are written at step 4, after you have looked at the subject (step 3) and at the starting recipe.
+  A line the user or the app has fixed says so ("Palette: theirs, exactly", "Type: the app's"); a "plain", "minimal" or "no poster" request has no Design lines.
 - A request is never dropped, swapped for something "better" or quietly reduced. If rhp cannot do something exactly, say so in the brief and do the closest thing.
 - A part of the data the user did not name (what is left when their parts do not reach 100%) is a quiet remainder: unlabeled, in the quiet color, with no key entry, and explained in the note, never a new series with its own color.
   Write it under **Asked**, beside the request it changes, as a deviation.
@@ -66,7 +76,13 @@ Look at the project before you write anything: read package.json (dependencies a
 Name a new file after its subject (`languages.html`, `RainfallChart.jsx`), and put it where the project keeps similar files.
 Install with the project's package manager (`npm install @bezda/rhp`) unless the chart is a plain HTML page, which loads rhp from jsDelivr.
 
-### 3. Design the slat, then pick the recipes to start from
+### 3. Find the subject's own form, design the slat, pick recipes for technique
+
+Look at the subject before you think of a chart type.
+A reader already knows what it looks like: its shape (a week is seven columns, a river runs from source to mouth, a depth hangs below the surface), its objects (a ticket, a scoreboard, a gauge, a ledger), and the way people who work with it already draw this data (a tide table, a score sheet, a growth chart at the doctor's).
+When one of those can hold the data honestly, it is the chart's form: [forms.md](references/forms.md) lists the shapes rhp draws and the recipe that has the technique for each.
+When none can, the form comes from the data alone, and the subject shows in the marks and the composition (step 4).
+The form the user named always wins.
 
 An rhp chart has no chart type to configure.
 It is one slat, the element drawn for each row of data, composed from blocks, so you design that slat:
@@ -76,11 +92,24 @@ It is one slat, the element drawn for each row of data, composed from blocks, so
 3. **What sits on top of the slats?** A second Plot over the first (`overlap`) draws layers: a scatter, a line, a crosshair, a marker for today.
 4. **What does each slat hold of its own?** A Plot inside a slat draws small multiples: a heatmap's cells, a grouped bar's bars, a strip of dots.
 
-[forms.md](references/forms.md) maps data and stories to forms and to these compositions; use the form the user named, if they named one.
+[forms.md](references/forms.md) maps subjects, data and stories to forms and to these compositions; use the form the user named, if they named one.
 Then open the closest recipe in `recipes/` and read it whole.
-Every recipe is a complete, tested, designed chart page, a worked example of one composition: start from it, keep its structure and its techniques, and replace its data, text, look and details.
+
+**A recipe gives technique, not a design.**
+Every recipe is a complete, tested chart page, and its comment at the top says which part is which.
+Take its technique: how the Plots and blocks are composed, the scale, the helpers, the interaction handlers, the accessibility, the phone rules.
+Leave its design: its look, the order and place of its parts, its readout band and controls row, the way its marks are drawn, and its wording were made for another subject.
+A chart that keeps them is that recipe with new data, and a reader can tell.
 When the story needs a slat no recipe has (a name, a bar, a sparkline and a target in one slat), combine the techniques of several recipes.
 
+For a bulk scatter collection, consider `ManyDots` instead of creating one slat per point.
+Keep `Dot` when you need rich point content or Plot's automatic keyboard navigation, selection, or readout behavior.
+Both remain explicit choices at any count, with no automatic switch at 500 points.
+Read the [ManyDots API and accessible example](references/api.md#manydots-experimental-point-collection) before using it.
+It preserves per-point color, size, shape, classes, and appearance styles and supports native hover, click, touch, and pointer events through its host.
+Point metadata uses the original `data-rhp-index`; drag behavior and keyboard-accessible controls are supplied by the application.
+Its numeric sizes mean pixels, updates are immediate and scan the rows, and initial SSR hydration requires aligned row order when DOM identity matters.
+
 | Recipe | Use it for |
 |---|---|
 | `bar` | ranked categories, long names (horizontal bars) |
@@ -113,27 +142,46 @@ When the story needs a slat no recipe has (a name, a bar, a sparkline and a targ
 | `lollipop` | ranked values, lighter than bars |
 | `bullet` | actual against target, with bands |
 | `pyramid` | two sides of one population by age |
+| `silhouettes` | things known by their shape (buildings, ships, bottles), each in its own outline to scale |
+| `dial` | how a day, a week or another cycle splits into parts, around a dial |
+| `log-line` | a quantity that grows by multiples over years, on a log scale, its falls measured |
+| `unit-stack` | a total made of parts over periods, counted out in units, one part to follow |
 
 The rhp MCP server's `rhp_recipe` tool (`rhp:rhp_recipe`) returns the same recipes when the files are not on disk.
 
 ### 4. Design it
 
 Unless the user gave a style, the chart is an original **editorial poster**: a magazine, advertisement or feature-article infographic designed for this subject.
-Read [design.md](references/design.md) and follow its procedure; in short:
+Original means that a reader could not guess which recipe it started from, and that with its words covered it still says what it is about.
+Read [design.md](references/design.md) and make its five decisions, in the brief's Design lines, each from this subject and each different from the starting recipe's:
+
+- **Idea.** The subject's own shape, object or way of drawing this data (step 3), in one sentence, and how it helps the reading.
+  It is the one thing a reader remembers, and it shows in the form or the marks, not only in the frame.
+- **Marks.** Drawn to carry the idea: each item in its own outline, a bar counted out in units, a container and what fills it, the stroke of the subject's own instrument.
+  Flat and honest: the value is still read from a length, a position or a count.
+- **Composition.** Where the headline, the chart, the key number and the note sit, taken from the idea and not from the recipe.
+  The idea must still be there at 390px.
+- **Palette.** The subject's own ground as the paper (a colored paper built from the subject's own color when it has one; design.md section 4 says how), its ink, one accent the subject owns for the story, and context marks quiet without being a wall of gray.
+- **Type.** A display face with the subject's voice and a plain text face, neither of them the recipe's.
+
+What the user or the project has fixed stays fixed, and the rest is still designed:
+
+| The request | Fixed | Yours, from the subject |
+|---|---|---|
+| no style given | nothing | all five |
+| the user's colors, fonts, brand or "dark" | those, exactly | the idea, the marks, the composition, and what they left open |
+| a chart inside an app with a look of its own | the app's fonts, colors, card and spacing | the idea, the marks, and the composition inside the card |
+| "plain", "minimal", "no poster", "just the chart" | the plain chart of design.md section 9 | nothing: plain wins |
+
+Unless the request is plain (design.md section 9 says what a plain or a minimal chart keeps):
 
-- The poster carries a **kicker** (the topic, a few words), a **headline that states the finding** ("Bananas outsell everything else", not "Fruit sales"), a **dek** (context and how to read the chart), the chart, and a **note** (source and year, or "Illustrative data"; no source line when the user gave the data and no source).
-- Derive the look from the subject: a material or setting, a palette, a type pairing, how the marks are drawn, and one ornament.
-  Make it your own, not a copy of the recipe's look or of another chart you made: never reuse a recipe's headline formula, kicker wording or readout band as they are.
+- The chart carries a **headline that states the finding** ("Bananas outsell everything else", not "Fruit sales"), and a poster also a **kicker** (the topic, a few words), a **dek** (context and how to read the chart) and a **note** (source and year, or "Illustrative data"; no source line when the user gave the data and no source).
+  Write them for this subject: never a recipe's headline formula or kicker wording.
 - Color has a purpose: one accent for the story, quieter colors for the rest. Direct labels beat legends.
 - The series or item the headline names leads at rest: lit, labeled and in the accent before the reader does anything.
   When the user's color for it is weak on the background, keep the color and outline or label its marks.
 - It must read on a phone (390px wide) as well as on a desktop, with the chart in the phone's first screen.
-
-When the user gives a style, a brand, colors or fonts, use exactly those: the palette and the type are theirs.
-The layout, the frame, the marks and one idea from the subject are still yours to design, with design.md's legibility rules.
-
-Inside an existing app with a look of its own (its fonts, CSS variables, Tailwind theme or component library), the chart takes the app's fonts and colors instead of a poster's.
-Keep the editorial habits that help any chart: a title that states the finding, direct labels, a source line.
+- Legibility is never traded for the idea: design.md's contrast floors, text sizes and honesty rules hold for every design.
 
 ### 5. Give it an interaction
 
@@ -145,9 +193,10 @@ The hint for an interaction sits beside its control, in words that fit every dev
 When the user asks for a "static" chart, an image-like chart or no interaction, add none.
 A chart with fixed data and no interaction gets `static=${true}` on its Chart: rhp draws it once and keeps no signals.
 
-### 6. Build it from the recipe
+### 6. Build it, with the recipe's technique
 
 - Keep the recipe's code format and section order: data, then slat types, then the chart component, then mounting.
+  With `ManyDots`, omit slat types and put the collection directly inside the Chart.
 - Use the user's data exactly, every value, in their units.
   With no data given: when the subject is factual, use real figures and name the source and year in the note; with network access, take them from the primary source (the agency or publisher that makes them) rather than from memory, and from memory use only figures you know well.
   Otherwise use plausible figures and the note says "Illustrative data".
@@ -158,6 +207,13 @@ A chart with fixed data and no interaction gets `static=${true}` on its Chart: r
   The handoff says exactly how to put their own numbers in, or offers to read a file they point to.
 - Compute the scale from the data: `nice(Math.min(0, ...values), Math.max(0, ...values))` (rule 2 below).
 - Compute the ranks, the leader and every number in the headline and the dek from a sorted copy of the data, never from its input order: a Plot's `order` sorts only what it draws.
+- Text computed from the data (the headline, the dek, a readout, an `aria-label`) must stay true for any data it may get:
+  - A change from a zero or missing base prints "new" or "up from none", never ∞%, NaN% or "as many as"; a change in a rate is in percentage points ("down 0.8 points").
+  - A change computed from the first and last values names them ("22% above 12 weeks ago"), and "held steady" needs every value inside a narrow band, not two equal ends.
+  - A count over the chart's window ("led for eight years", "a record") names the window ("every year from 2015 to 2022") unless you checked it holds before the window too.
+  - Numbers in the text are rounded as the labels are, and labels use the fewest decimals that keep neighbors apart, with no trailing zeros.
+- Real data from yearly releases takes each year from the latest release that covers it, never a mix of first estimates and revisions.
+  When the user asks for brands and the source counts companies, the note names every merge shown ("Lenovo includes Motorola").
 - Look up anything you are unsure of in [api.md](references/api.md) rather than guessing a prop.
 - Keep the code short and plain: comments at section heads and where a reader needs one.
 
@@ -169,12 +225,22 @@ Run the checker on the file after the first full draft and again after every fix
 - otherwise run `npx -y @bezda/rhp-mcp check <file>` (add `--dark` when the page has a dark mode).
 
 A chart component that takes its data from the app cannot be drawn on its own: check a small entry file that draws it with fixed data, as environments.md section 13 shows.
+For the experimental `ManyDots` collection, use a build that exports it and also check its rendered point count, coordinates, per-point appearance, native interactions, and keyboard-accessible alternative directly in the browser.
+A clean standard-chart checker report alone does not establish coverage of its bulk points.
 
 It builds the chart, renders it in a browser at 1280px and 390px, tries its interaction, and reports runtime errors, props rhp does not have, data the slat reads but the Plot lacks, values past the scale, overlapping or cut-off text, marks sticking out, sideways scrolling, low contrast and tiny text, with a fix for each.
 Its screenshots show the page with reduced motion asked for, so a chart that animates on load is pictured at rest; its interactions run with motion on.
 They go to a folder in the system's temp directory, and the report gives their paths; `--out <dir>` puts them elsewhere.
 Keep screenshots, and any test files of your own, out of the user's project.
 Then open the screenshots and look at them as a demanding art director would: hierarchy, spacing, alignment, color, legibility on the phone, and whether the headline is true for the data.
+Unless the request was plain or minimal, put the design to two tests:
+
+- **The recipe test.** Run the checker on the recipe you started from as well, and look at its 1280px screenshot beside yours.
+  If a reader could tell that yours started from it (the same parts in the same places, the same band above the chart, the same marks in new colors), change the composition or the marks; new colors and fonts do not pass this test.
+- **The subject test.** Look at your screenshots at 1280px and at 390px as if the words were covered.
+  What is left must still say what the chart is about.
+  If it could hold any data, the idea lives only in the text and the frame: carry it into the form or the marks.
+
 Fix what you see, and check again.
 
 Never make a warning go away by removing something the user asked for.
@@ -185,8 +251,9 @@ If the checker cannot run here (no Node, no browser, a chatbot without tools), g
 - Go through every **Asked** item of the brief against the final code and screenshots, and fix anything missing.
 - Recompute every number in the headline, the dek and the note from the final data: a claim must be true for the numbers shown.
 - Try every control once more and compare before and after: nothing else on the page may move (pitfalls.md, "The layout jumps").
-- Check once more at four widths (`--widths 1280,1024,768,390`, or `widths` in `rhp_check`): layouts that change between 390px and 1280px (a breakpoint, a turned chart, a panel beside the chart) are where most layout bugs are.
-- When the chart will take other data (the user's own, live or generated), check a copy with the hardest data it may get: the longest names, values ten times larger, twice as many rows.
+- Check once more at six widths (`--widths 1280,1024,768,390,360,320`): layouts that change between 320px and 1280px (a breakpoint, a turned chart, a panel beside the chart) are where most layout bugs are; 360px and 320px catch narrower phone layouts.
+  If `rhp_check` accepts only four widths per call, use two calls to cover all six.
+- When the chart will take other data (the user's own, live, loaded or generated, or a component that takes its rows as a prop even if the app's data is fixed today), check a copy with the hardest data it may get: the longest real names of the domain, values ten times larger, twice as many rows, one row and none, a first value of 0 and all zeros, the smallest parts (1 to 5%), and dates across a year's end.
 - Then tell the user, briefly: what you made, where it is and how to open or run it (an HTML file opens with a double-click, and needs a connection for rhp), what you chose for them (form, look, interaction, data source or "illustrative"), and anything you could not do, with the reason.
   For a short request, those few lines are the whole handoff: no test logs, tool versions or local paths.
   To name the checker, give the command anyone can run, `npx -y @bezda/rhp-mcp check <file>`.
@@ -324,11 +391,21 @@ The html template (every format except Solid JSX):
 8. **A handler on a component takes its event:** `onClick=${(e) => pick(e)}`. A function with no parameter on a component (a block or a Poster) runs once while drawing and is never attached. Handlers on plain elements (`div`, `button`) work either way, and the Chart takes none at all (rule 16).
 9. **`class`, never `className`**: on a block, `className` replaces rhp's own class and the block disappears.
 10. **A space between two tags disappears**: `<b>${() => d.name}</b> <em>12</em>` renders "Name12". Write the space as `${" "}` or keep text next to it (`<b>Name</b>: <em>`).
-11. **`style` on a Chart or a Plot is an object** (`style=${{ "pointer-events": "none" }}`); a string is dropped. Blocks and plain elements take either.
+11. **Chart, Plot and slat roots use style objects.**
+    On a Chart or a Plot, use `style=${{ "pointer-events": "none" }}`: a string is dropped.
+    On a slat's root, keep a changing style an object (`style=${() => ({ "--n": d.n })}`), because a string that changes or a style that becomes `undefined` erases its stack position.
+    On published rhp 2.0.2, the same replacement can erase a Block's position and color, so use objects there too; the Block bug is fixed in current source for the upcoming 2.0.3 release.
+    Other plain elements accept objects or strings.
 
 Structure and layout:
 
-12. **One root element per slat**, holding its blocks (`<div>`); never return a block itself (only an `overlap` Plot may). Give the Plot the slat type `slat()` returns, not the function you passed to it.
+12. **One root element per slat.**
+    In an ordinary Plot, use a wrapper (`<div>`) holding its blocks.
+    In an `overlap` Plot or a Scale, a single block can be the root itself, including its own children, so avoid an extra wrapper.
+    Those children use the block's box, not the full slat's band.
+    Several blocks still need a common root.
+    Keep a wrapper for a full-band hover or pointer target, even with one block.
+    Give the Plot the slat type `slat()` returns, not the function you passed to it.
 13. **Import from one place.** In a Solid app, import rhp from `@bezda/rhp` and Solid from `solid-js`. Everywhere else, import everything from `@bezda/rhp/standalone` (rhp, `html`, `render`, `createSignal`, `createMemo`, `createEffect`, `Show`, `For`, `Index`, `onMount`, `onCleanup`, `batch`, `untrack`, `createStore`, `reconcile`), which carries its own Solid: never add a second `solid-js` beside it. From rhp 2.0.2 it also has `createSelector`, `createComputed`, `on`, `mergeProps`, `splitProps`, `Switch` and `Match` (2.0.1 lacks them); it has no `Dynamic`, `Portal`, `createResource` or `ErrorBoundary`. For the slat the reader is on, a per-row comparison (`on=${(d) => on() === d.index}`) works with every rhp 2.
 14. **Make room for text.** Names before the plot need `room.start` (px or "auto"), numbers past the bars need `room.end`. A `room` you give replaces the defaults on every side, so set each side you need. "auto" measures only edge Labels that are direct children of the slat's root. Long names need `max-width` with an ellipsis, or wrapping, in the slat CSS.
 15. **Size the chart.** A horizontal chart without `height` gives each slat 32px unless the slat type sets `thickness`; a vertical chart is 240px tall unless you set `height`. A chart inside a flex row, an inline-block or a `fit-content` box collapses: give it `flex: 1; min-width: 0` or a width.
@@ -336,8 +413,17 @@ Structure and layout:
 
 Style and color:
 
-17. **Style the inside of a chart with the slat's `css` and the Chart's `theme` only.** rhp's CSS is `!important` inside cascade layers, so page CSS cannot change a block's color, background, font, border, radius, shadow, padding or transition. Page CSS styles the poster around the chart and the chart's box. Focus styles for slats (`.slat:focus-visible`) go in the slat's `css` too: a page `:focus-visible` rule never reaches a slat.
-18. **Color with theme keys or CSS colors**: `color="series-2"`, `"positive"`, `"negative"`, `"muted"` or `"#c2410c"`. Set the palette in the Chart's `theme` (`series`, `ink`, `muted`, `grid`, `surface`, `positive`, `negative`, `low`, `high`, `font`). Theme values may read the page's own variables (`ink: "var(--ink)"`), so the poster and the chart share one set of tokens and dark mode is a few lines of CSS (design.md); a block's `color` may not (rhp warns), and page CSS never sets rhp's own `--rhp-*` variables. `series()` counts six colors: with a shorter `series` list, call `series(n)`. A Label does not take its Bar's color: color the slat root (`--rhp-color` in its style) or the Label's own text.
+17. **Style regular slat blocks with the slat's `css` and the Chart's `theme`.**
+    rhp's block CSS is `!important` inside cascade layers, so page CSS cannot change a block's color, background, font, border, radius, shadow, padding or transition.
+    Page CSS styles the poster around the chart and the chart's box.
+    Focus styles for slats (`.slat:focus-visible`) go in the slat's `css` too: a page `:focus-visible` rule never reaches a slat.
+    `ManyDots` instead uses `pointClass` and ordinary application CSS or `pointStyle` for appearance, while the collection guards point geometry.
+18.
+    **Color with theme keys or CSS colors**: `color="series-2"`, `"positive"`, `"negative"`, `"muted"` or `"#c2410c"`.
+    Set the palette in the Chart's `theme` (`series`, `ink`, `muted`, `grid`, `surface`, `positive`, `negative`, `low`, `high`, `font`).
+    Theme values may read the page's own variables (`ink: "var(--ink)"`), so the poster and the chart share one set of tokens and dark mode is a few lines of CSS (design.md); a block's `color` may not (rhp warns), and page CSS never sets rhp's own `--rhp-*` variables.
+    `series()` counts six colors: with a shorter `series` list, call `series(n)`.
+    A Label does not take its Bar's color: give the slat's root `--rhp-color` in a style object (`style=${() => ({ "--rhp-color": d.on ? ACCENT : QUIET })}`) or color the Label's own text.
 19. **A Dot's `size` is a length** (`size="12px"`); a bare number stretches it into an oval.
 20. **Overlay Plots** (a crosshair, a marker over other Plots) need `style=${{ "pointer-events": "none" }}` so the pointer reaches the Plot under them.
 
@@ -352,12 +438,13 @@ The full list, with the mistake and the fix for each, is [pitfalls.md](reference
 
 Read the ones the chart needs; each is self-contained.
 
-- [forms.md](references/forms.md): which chart for which data and story, and which recipe to start from.
-- [design.md](references/design.md): the poster, art direction from the subject, look kits, palettes, type, layout, annotation, dark mode.
+- [forms.md](references/forms.md): the subject's own form, which chart for which data and story, and which recipe has the technique.
+- [design.md](references/design.md): art direction from the subject (idea, marks, composition, palette, type), the poster, color, type, layout, annotation, charts inside an app, a style the user asks for.
+- [looks.md](references/looks.md): eight looks written out in full (tokens, fonts, texture, type), as examples of how a look is written, not a menu.
 - [interaction.md](references/interaction.md): which interaction for which story, with complete code for each.
 - [environments.md](references/environments.md): plain HTML, Solid, Astro, React, Next.js, Vue, Svelte and Angular, each verified, and the html template to JSX rules.
 - [api.md](references/api.md): every component, prop, helper and CSS variable, exactly.
 - [pitfalls.md](references/pitfalls.md): mistakes and their fixes.
-- `recipes/*.html`: the tested starting points listed in step 3.
+- `recipes/*.html`: the tested pages listed in step 3, for technique.
 
 Live gallery and docs: https://rhp.vercel.app

package/skill/recipes/area.html

@@ -5,6 +5,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>A summer day on the grid</title>
 <meta name="description" content="Area chart of one quantity over a day: a filled Line on a second axis, with its peak and low annotated, and a switch between two days that morphs the area while the other day stays as a thin reference line. Use it for one quantity over time, filled, or to compare two periods.">
+<!--
+  A recipe gives technique, not a design.
+  Take: a filled Line on a second axis, its peak and low annotated, an hour Scale, and a switch that morphs between two days while the other stays as a thin line.
+  Leave: the design. This poster was made for its own subject (a July day's power demand over Manhattan's street grid, on pale concrete).
+  Its look, the place of its parts and the way its marks are drawn say that subject: design yours from your own (design.md, section 2).
+-->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Big+Shoulders+Display:wght@700..900&family=Work+Sans:wght@400..700&display=swap">

package/skill/recipes/bar.html

@@ -5,6 +5,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>The most spoken languages</title>
 <meta name="description" content="Horizontal bar chart, ranked, the top bar highlighted, with a readout on hover, focus and tap. Use it to rank categories by one value, especially with long names.">
+<!--
+  A recipe gives technique, not a design.
+  Take: ranked Bars with names in an "auto" room, the leader lit, and a readout on hover, focus and tap that stays at the top of a phone's screen.
+  Leave: the design. This poster was made for its own subject (the world's languages as speech: each bar a speech bubble, each name in its own script, the share under a big quotation mark).
+  Its look, the place of its parts and the way its marks are drawn say that subject: design yours from your own (design.md, section 2).
+-->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400..700&family=Instrument+Serif:ital@0;1&display=swap">

package/skill/recipes/box-plot.html

@@ -5,6 +5,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Bikes beat cars, and keep to time</title>
 <meta name="description" content="Box plot of commute times by mode of transport made with summary(): whiskers, the middle half as a box, the median and outliers, with a readout of the picked group. Use it to compare the spread of several groups at a glance.">
+<!--
+  A recipe gives technique, not a design.
+  Take: summary() drawn as whiskers, a box and a median in one slat, outliers in an overlay Plot, and a readout of the picked group.
+  Leave: the design. This poster was made for its own subject (commute times on the enamel map board of a tiled station wall, the kicker as the station's sign).
+  Its look, the place of its parts and the way its marks are drawn say that subject: design yours from your own (design.md, section 2).
+-->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Overpass:wght@400..900&display=swap">

package/skill/recipes/bubble.html

@@ -5,6 +5,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Two ways to hold 20 million</title>
 <meta name="description" content="Bubble chart: two measures per item on a second axis (log scales) and a third as the bubble's area, with guide lines of equal size, labels for the story's items and a readout for the bubble under the pointer, a tap or the arrow keys. Use it for items with two measures and a size.">
+<!--
+  A recipe gives technique, not a design.
+  Take: Dots on two log axes sized by area, guide lines of equal size, labels placed per row, and a readout of the bubble under the pointer.
+  Leave: the design. This poster was made for its own subject (cities seen from orbit at night, with a map's scale bar under the kicker).
+  Its look, the place of its parts and the way its marks are drawn say that subject: design yours from your own (design.md, section 2).
+-->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Sora:wght@400..700&family=DM+Mono:wght@400;500&display=swap">

package/skill/recipes/bullet.html

@@ -5,6 +5,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Sales against target by region</title>
 <meta name="description" content="Bullet chart: actual against target for each item, over gray bands for poor, fair and good, with a switch that sorts by the actual value or by the share of target. Use it for performance against goals, budgets or quotas.">
+<!--
+  A recipe gives technique, not a design.
+  Take: band Bars, the actual Bar and a target Tick in one slat, and a switch that sorts by value or by share of target.
+  Leave: the design. This poster was made for its own subject (a page of an annual report, black on white with one orange, the year on a tab under the top rule).
+  Its look, the place of its parts and the way its marks are drawn say that subject: design yours from your own (design.md, section 2).
+-->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo:wdth,wght@62..125,400..900&display=swap">

package/skill/recipes/candlestick.html

@@ -5,6 +5,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>A 15% drop erased the month's gains</title>
 <meta name="description" content="Candlestick chart of one month of daily share prices: a wick from each day's low to its high and a body from its open to its close (hollow when it rose, filled when it fell), with a crosshair and a price readout for the picked day. Use it for open, high, low and close prices over days.">
+<!--
+  A recipe gives technique, not a design.
+  Take: a thin Bar for the wick and a wide one for the body (hollow when the day rose), a crosshair in an overlay Plot, and a price readout on one line.
+  Leave: the design. This poster was made for its own subject (a stock's month printed on an engraved share certificate, ivory paper inside a double rule).
+  Its look, the place of its parts and the way its marks are drawn say that subject: design yours from your own (design.md, section 2).
+-->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:ital,wght@0,500..700;1,500..600&family=IBM+Plex+Mono:wght@400;500;600&display=swap">

package/skill/recipes/column.html

@@ -5,6 +5,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>A monsoon year</title>
 <meta name="description" content="Column chart of a value over twelve months, a season marked under its columns, with a scrub that reads out the running total by hover, focus and tap. Use it for values over periods (months, years) or a few categories.">
+<!--
+  A recipe gives technique, not a design.
+  Take: vertical Bars over twelve periods, a bracket under a group of columns, and a scrub that reads out a running total.
+  Leave: the design. This poster was made for its own subject (a monsoon year as twelve rain gauges in the night rain, each month a glass tube with its water inside).
+  Its look, the place of its parts and the way its marks are drawn say that subject: design yours from your own (design.md, section 2).
+-->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo:wdth,wght@62..125,400..800&display=swap">
@@ -22,14 +28,16 @@
   .poster .dek { max-width: 54ch; font-size: 16px; line-height: 1.5; color: #b5bdc4; }
   .poster .note { display: block; margin-top: 24px; font-size: 12px; line-height: 1.5; color: #8d969e; }
   /* The readout: how much rain has fallen by the month in focus */
-  .readout { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 14px; min-height: 2lh; margin: 0 0 22px; padding-top: 16px; border-top: 1px solid #2c3135; font-size: 15px; line-height: 1.4; color: #b5bdc4; }
+  .readout { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 14px; margin: 0 0 22px; padding-top: 16px; border-top: 1px solid #2c3135; font-size: 15px; line-height: 1.4; color: #b5bdc4; }
   .readout b { font-size: 30px; font-weight: 700; font-stretch: 110%; color: #fff; font-variant-numeric: tabular-nums; }
+  /* Where the figure and its longest text no longer fit on one line, the text goes under the figure with two lines
+     kept, so the readout has one height whatever it says and the chart never moves */
+  @media (max-width: 720px) { .readout { flex-direction: column; align-items: start; } .readout span { min-height: 2lh; } }
   @media (max-width: 560px) {
     body { padding: 16px 16px 32px; }
     .poster { padding: 26px 16px 18px; }
     .poster .headline { font-size: 32px; }
     .poster .dek { font-size: 15px; }
-    .readout { min-height: 4lh; } /* the longest readout, so the chart never moves */
     .readout b { font-size: 24px; }
   }
 </style>
@@ -46,6 +54,8 @@ const SEASON = { name: "Monsoon", from: 5, to: 8 }; // June to September; null f
 
 const mm = new Intl.NumberFormat("en-US");
 const percent = new Intl.NumberFormat("en-US", { style: "percent" });
+// A share in whole percents that never rounds some rain to "0%" or a year not yet over to "100%"
+const share = (x) => (x > 0 && x < 0.005 ? "under 1%" : x >= 0.995 && x < 1 ? "over 99%" : percent.format(x));
 const year = RAIN.reduce((a, b) => a + b, 0);
 const scale = nice(0, Math.max(...RAIN), 4); // 0 to 1,000 mm, a line every 250
 
@@ -65,14 +75,17 @@ const Month = slat({
     .season { position: absolute; top: calc(100% + 30px); left: 24%; width: calc(var(--months) * 100% - 48%); height: 7px; border: 1.5px solid #6cc3ff; border-top: 0; }
     .season b { position: absolute; top: 13px; left: 50%; translate: -50% 0; font-size: 11px; font-weight: 700; letter-spacing: .16em; text-transform: uppercase; color: #6cc3ff; white-space: nowrap; }
     .month:focus-visible { outline: 2px solid #6cc3ff; outline-offset: -2px; border-radius: 4px; }
+    .name .short { display: none; }
     @container (max-width: 520px) { .name { font-size: 11px; font-stretch: 70%; letter-spacing: 0; } .mm { font-size: 11px; font-stretch: 80%; } }
+    /* Columns under about 21px: the month's first letter, the whole name staying in the readout and the slat's label */
+    @container (max-width: 293px) { .name .long { display: none; } .name .short { display: inline; } }
   `,
 }, (d) => html`
   <div class=${() => "month " + d.step} data-row=${() => d.index} aria-label=${() => `${d.month}: ${mm.format(d.mm)} mm`}>
     <${Bar} to=${scale.max} class="tube" />
     <${Bar} to=${() => d.mm} class="water" />
     <${Label} at=${() => d.mm} class="mm">${() => mm.format(d.mm)}<//>
-    <${Label} edge="start" class="name">${() => d.month.slice(0, 3)}<//>
+    <${Label} edge="start" class="name"><span class="long">${() => d.month.slice(0, 3)}</span><span class="short">${() => d.month[0]}</span><//>
     <${Show} when=${() => d.index === SEASON?.from}>
       <span class="season" style=${() => `--months: ${SEASON.to - SEASON.from + 1}`}><b>${() => SEASON.name}</b></span>
     <//>
@@ -103,12 +116,12 @@ function MonsoonYear() {
       kicker="A monsoon city · rain by month"
       title="Four months bring nearly all of the year's rain"
       dek="Each tube holds a month's rain in millimetres. From June to September the monsoon fills them; for the rest of the year they stay almost dry."
-      note="Illustrative data, shaped like a monsoon city's year. Point at a month, tap it, or Tab into the chart and use the arrow keys to add up the year."
+      note="Illustrative data, shaped like a monsoon city's year."
       onPointerMove=${(e) => e.pointerType !== "touch" && pick(e)} onClick=${pick} onFocusIn=${pick}
       onPointerLeave=${leave} onFocusOut=${(e) => !e.currentTarget.contains(e.relatedTarget) && setAt(null)}>
       <p class="readout" aria-live="polite">
         <b>${() => mm.format(sofar()) + " mm"}</b>
-        <span>${() => (at() == null ? "in the whole year" : `by the end of ${MONTHS[end()]}, ${percent.format(sofar() / year)} of the year's rain`)}</span>
+        <span>${() => (at() == null ? "in the whole year. Tap or point at a month to add it up." : `by the end of ${MONTHS[end()]}, ${share(sofar() / year)} of the year's rain`)}</span>
       </p>
       <${Chart} orientation="vertical" height=${300} scale=${[scale.min, scale.max]} ticks=${scale.ticks} format=${(v) => mm.format(v)}
         label="Rainfall by month, in millimetres"