plot-io 0.6.0__tar.gz → 0.8.0__tar.gz

{plot_io-0.6.0 → plot_io-0.8.0}/API.md

@@ -17,22 +17,26 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
 
 ## 1. Conventions
 
-* **Model.** A `Figure` holds plots (and colorbars) in a grid; a `Plot` holds series, two
-  axes, a title, a legend and colorbars; a series holds data and style. Nothing is
-  computed until the figure is drawn (`save`, `to_bytes`, `draw`), so settings can change
+* **Model.** A `Figure` holds plots (and colorbars) in a grid, and titles; a `Plot` holds
+  series, two axes, titles, a legend and colorbars; a series holds data and style. Nothing is
+  computed until the figure is drawn (`save`, `write`, `draw`), so settings can change
   in any order.
 * **Settings.** Every object takes its settings as keywords when created and in
   `set(**settings)`, which returns the object. `set(name=None)` goes back to the inherited
   or default value. `get(name)` returns the value as given (`"4.5pt"`, `"var(color)"`),
   `resolve(name)` the final one (px, degrees, colors), and `explain(name)` where it comes
   from ([values](#values)). Unknown names and invalid values raise `ValueError` naming
-  the setting (with the nearest valid name).
+  the setting (with the nearest valid name; `alpha=` names `opacity=`).
 * **Inheritance.** Settings marked *inherited* in the tables (font, line width, palette,
-  alpha, `rasterize`, `simplify`) are looked up series → plot → figure → style.
+  `opacity`, `rasterize`, `simplify`) are looked up series → plot → figure → style.
+* **Shorthands.** A setting has one full name and at most one shorthand; marker names have
+  shorthands too ([shorthands](#shorthands)). Giving a shorthand with its full name is an
+  error.
+
 * **Setting groups.** Settings that travel together are declared once as a group and
   embedded by each owner: `Font` (family, size, variable-font axes), `TextStyle` (size,
   weight, style, color of one text element), `Stroke` (color, width, dash style, caps,
-  joins), `Marker`, `FillStyle` (`fill`: on or off, an opacity or a color) and
+  joins), `Marker`, `FillStyle` (`fill`: on, off or a color; `fill_opacity`) and
   `NumberFormat`. The naming rule: an owner's primary element takes a group unprefixed, a
   secondary one prefixed, and every member's prefixed name follows its pattern. A
   scatter's markers are `size`, `edge_color`, …; a line's are `marker_size`,
@@ -40,9 +44,10 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `whisker_style`; an axis' tick labels are `tick_label_font_size`, `tick_label_weight`,
   `tick_label_color`. Each table ends with the groups the class embeds and their
   prefixes; [groups](#setting-groups) lists the members.
-* **Defaults.** Every default is in one dict, `pl.DEFAULTS` (`plot_io/defaults.py`; read
-  it, do not change it: styles set other values): bare names for inherited settings (font size,
-  sans-serif, black text, line width, `simplify="auto"`, the palette, …),
+* **Defaults.** Every default is in one read-only mapping, `pl.DEFAULTS`
+  (`plot_io/defaults.py`), the `"default"` style that ends every figure's
+  [style chain](#10-styles); styles set other values. Bare names for inherited settings
+  (font size, sans-serif, black text, line width, `simplify="auto"`, the palette, …),
   `"Class.name"` for the settings of each class and `"Group.member"` for every embedding
   of a group member (`"Marker.size"`: every marker size). A class without an entry uses
   its base class's, then the group's. Entries are plain data: a default that follows
@@ -52,27 +57,32 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `"calc(1.4 * inherit)"`, a fill's opacity `"calc(0.3 * inherit)"`). `"XAxis.name"` and
   `"YAxis.name"` give one axis its own default.
 * **`"auto"`.** A setting whose default is `"auto"` documents its rule. Rules that follow
-  from the model (a colorbar's orientation from its position, a legend's inner pad from
+  from the model (a colorbar's orientation from its side, a legend's inner pad from
   its frame, a genome track's gap) are resolved with the setting: `resolve()` returns the
   result and `get()` `"auto"`. Rules that need the data or the layout (axis limits,
   padding, tick count and rotation, number formats, legend placement) are resolved when
   the figure is drawn.
 * **Resolution.** One cascade finds every value, for `resolve`, `get` and `explain`:
   1. the value set on the object; for a plot's x or y axis, then the value set on the
-     figure's axis of that role (`fig.x_axis(…)`);
-  2. a rule of the class (a track's axis lines from its content);
-  3. the style's key for the object's class, then for its base classes (`"Series.alpha"`
-     reaches every series), stopping at a class that has a default of its own;
-  4. for inherited settings, the parent's value (unless the class default refers to it
-     with `inherit`);
-  5. the style's key for the setting's group (`"Marker.size"`);
-  6. the class default, then the group default;
-  7. for inherited settings, the style's bare name, then `DEFAULTS`'.
-
-  An owner's key always comes before its group's: `"Line.marker_size"` overrides
-  `"Marker.size"` for lines.
-* **Styles.** `Figure(style=…)` presets settings: a style name or a dict of settings,
-  merged over the inherited defaults (the bare names of `DEFAULTS`). See [Styles](#styles).
+     figure's axis of that role (`fig.x_axis(…)`); for a series' own color or size axis,
+     the series' `color_scale`, `color_limits`, … ;
+  2. each style of the figure's chain, nearest first: its key for the object's class,
+     then for its base classes (`"Series.opacity"` reaches every series), stopping at a
+     class that has a default of its own, then its key for the setting's group
+     (`"Marker.size"`). A rule of the class, a default it computes from the model (a
+     track's axis lines from its content, the width, spacing, columns and shared x of
+     tracks), comes after the keys of its class and of more specific ones
+     (`"Track.spines"`, `"Figure.width"`) and before those of its base classes
+     (`"Plot.spines"`);
+  3. for inherited settings, the parent's value;
+  4. the class default, then the group default (first, when it refers to the parent's
+     value with `inherit`);
+  5. for inherited settings, the bare name: the nearest style's, else `DEFAULTS`'.
+
+  Within one style, or within `DEFAULTS`, an owner's key comes before its group's:
+  `"Line.marker_size"` overrides `"Marker.size"` for lines.
+* **Styles.** `Figure(style=…)` presets settings: a style name or a dict of settings, in
+  front of `DEFAULTS`. See [Styles](#10-styles).
 * **Entry points.** `pl.Figure()`, `pl.Plot()` and the series classes (`pl.Scatter()`, …)
   each create the levels above them: `pl.Scatter(x, y)` makes a plot (`.plot`) in a new
   figure (`.plot.figure`). `fig.plot(…)` is `pl.Plot(figure=fig, …)` and `p.scatter(…)` is
@@ -86,8 +96,17 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `Swarm` `width`) are `"80%"` of the slot or `"0.8d"` in data units. Positions along an
   axis (a decoration's `min`/`max`) take bare numbers as data values. See
   [values](#values).
-  Images are `dpi` pixels per inch: `dpi=96` gives one image pixel per px, the default 192
-  two. A dpi up to 16 is a multiple of 96: `dpi=2` is 192. PDF pages are sized in pt (× 0.75).
+  PDF pages are sized in pt (× 0.75).
+* **Resolutions.** A dpi is dots per inch: a number (`150`, `16`), or a multiple of 96
+  written `"2x"` (192 dpi), wherever a resolution is taken (`dpi`, `default_dpi`,
+  `rasterize`, `simplify`, `flatten`'s `dpi`). Images are `dpi` pixels per inch (the
+  figure's `default_dpi`, `"4x"`, when an output gives none): `96` gives one image pixel per
+  px, `"4x"` four.
+* **Opacity and alpha.** `opacity` (and `fill_opacity`, `band_opacity`, `frame_opacity`,
+  `glyph_opacity`, `opacity_range`) multiplies what is drawn; alpha is the alpha channel of
+  a color (`"#rrggbbaa"`, `"rgb(… / 0.5)"`), kept and multiplied by the opacity. `fill` is
+  `True` (the owner's color), a color or `False`; its opacity is `fill_opacity`, for a
+  color too, as in SVG (`fill="red", fill_opacity=1` for an opaque red fill).
 * **Data.** Sequences (`None` = missing), `array.array`, or any buffer (numpy arrays are
   read without importing numpy). NaN or `None` values are missing: scatter skips them,
   line and fill break there, box ignores them, heatmap cells take `nan_color`.
@@ -95,7 +114,15 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   ([tables](#tables-data)); dates make time axes ([dates](#dates-and-times)).
 * **Text.** Titles, axis labels and legend entries are strings or rich content: a list of
   strings and `pl.Span` (vec_io's), e.g. `["Area (m", pl.Span("2",
-  baseline_shift="super", font_scale=0.7), ")"]`.
+  baseline_shift="super", font_scale=0.7), ")"]`. Strings take markup:
+  `"Growth of <i>E. coli</i> at <b>37 °C</b>"`, `"Area (m<sup>2</sup>)"`. Tags: `<i>`/`<em>`
+  italic, `<b>`/`<strong>` bold, `<u>` underline, `<s>`/`<del>` strikethrough, `<sup>` and
+  `<sub>` (0.7 of the size, raised 0.33 em or lowered 0.2 em), in either case, nested,
+  each closed by its own end tag; an unclosed or crossed tag is an error. Styles add to the text's own (`<b>`
+  in a bold title stays bold). Any other `<` is text (`x < 5`, `<0.05`); `&lt;`, `&gt;` and
+  `&amp;` write `<`, `>` and `&`. Strings inside rich content are read too; tick labels
+  take no markup. `markup=False` (inherited: on the figure, a plot or a text element) keeps
+  strings literal; `get()` returns the string as given.
 * **Named colors.** `"blue"`, `"blue 0.45"`, `"blue 45%"`: 28 scales (`red`, `orange`,
   `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`,
   `violet`, `purple`, `fuchsia`, `pink`, `rose`, `slate`, `gray`/`grey`, `zinc`, `neutral`,
@@ -120,20 +147,55 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `pl.Figure(font_family="Roboto Flex", font_stretch="85%", font_variations={"GRAD": 50})`.
 * **Text and fonts.** Text is shaped by `vec_io.text` (pairs kerned) and its fonts are
   embedded as subsets; plot text needs an installed outline font. Each character takes
-  the first family of `font_family` that is available (output options `font_dirs`, then
-  `VEC_IO_FONT_DIRS`, then installed fonts unless `system_fonts=False`; a family that is
+  the first family of `font_family` that is available (the `fonts` setting or output
+  option, a vec_io `Fonts`: its `dirs`, then `VEC_IO_FONT_DIRS`, then installed fonts unless
+  `system=False`; a family that is
   not installed tries its metric aliases first: Helvetica and Arial → Liberation Sans,
   Arimo, …), then a generic family's list (`sans-serif`: Arial, Helvetica, Liberation
   Sans, DejaVu Sans, Noto Sans, …), then any font with the character. The default
-  `"SF Pro, Inter, Helvetica, Arial, sans-serif"` is SF Pro where installed, else Inter,
-  else Helvetica or Arial (or an alias of theirs), else the system's sans-serif. With no
-  outline font at all, output raises `NoFontError` (a `ValueError`, from vec_io).
+  `"Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo"` is Helvetica where
+  installed, else the first of the others installed (all have Helvetica's widths); with
+  none installed, vec_io downloads Nimbus Sans (URW's base 35 fonts). With no outline
+  font at all, output raises
+  `NoFontError` (a `ValueError`, from vec_io). A line of text is `line_height` tall (a
+  multiple of the font size; default 1), the glyphs centered in it, so the gaps around
+  text do not change with the font; `"normal"` takes the font's ascent and descent.
 * **Names.** `pl.` holds the figure and plot classes, the plot types, the value types
-  (`ColorAxis`, `SizeAxis`, `ColorMap`, `SizeMap`, `Palette`, `Density`, `ErrorBars`,
-  `Span`), `facet`, the registries (`register_layer`, `register_marker`,
-  `register_color_map`, `register_palette`, `register_style`), `styles` (the styles
-  module), `set_style`, `use_style` and `DEFAULTS`; see [modules](#12-modules) for the
-  rest. Enum-like settings take strings.
+  (`ColorAxis`, `SizeAxis`, `ColorMap`, `SizeMap`, `Palette`, `Density`, `Errors`,
+  `Span`), `facet`, `registry` (below), `Series`, `set_style`, `use_style` and `DEFAULTS`;
+  see [modules](#12-modules) for the rest. Enum-like settings take strings.
+* **Registries.** `pl.registry` groups the named things: `registry.color_maps`,
+  `palettes`, `markers`, `styles` and `layers` (plot types), each with `add(name, value)`,
+  `names()` and `get(name)` (`ValueError` for an unknown name) and `name in registry.…`.
+* **Guides.** Titles, legends and colorbars follow one pattern. A figure has
+  `fig.add_title`, `fig.add_legend` and `fig.add_colorbar` (in the lanes beside a set of
+  plots, `side=`) and `fig.colorbar_area` (a colorbar in its own grid area); a plot has
+  `p.add_title`, `p.add_legend` (the plot's legend, `p.legend`) and `p.add_colorbar`
+  (attached, `side=`); `fig.plot(legend=…, colorbar=…)` calls them for the common case.
+
+### Shorthands
+
+`settings.ALIASES` (setting names, on every class with the full setting) and
+`settings.MARKER_ALIASES` (marker names):
+
+<!-- settings:shorthands -->
+| Shorthand | Stands for |
+|---|---|
+| `c=` | `color=` |
+| `s=` | `size=` |
+| `cmap=` | `color_map=` |
+| `smap=` | `size_map=` |
+| `marker="o"` | `"circle"` |
+| `marker="s"` | `"square"` |
+| `marker="d"` | `"diamond"` |
+| `marker="^"` | `"triangle_up"` |
+| `marker="v"` | `"triangle_down"` |
+| `marker="<"` | `"triangle_left"` |
+| `marker=">"` | `"triangle_right"` |
+| `marker="+"` | `"plus"` |
+| `marker="x"` | `"cross"` |
+| `marker="triangle"` | `"triangle_up"` |
+<!-- /settings -->
 
 ### Values
 
@@ -147,7 +209,7 @@ p.bar(days, counts, width="20h")                   # a duration on a time axis
 p.box(groups, positions=[1, 4, 9], width="0.8d")  # data units (default: 80% of the slot)
 p.errorbar(x, y, y_error=e, cap_length="0.2d")    # data units across the bar
 p.title(font_size="large", color="var(--accent)")
-p.legend(pad="calc(1em - 2px)")
+p.add_legend(pad="calc(1em - 2px)")
 fig.set(vars={"accent": "#c00"})                   # custom variables, read by var(--name)
 ```
 
@@ -166,7 +228,7 @@ fig.set(vars={"accent": "#c00"})                   # custom variables, read by v
 
 * **`var(name[, fallback])`** reads another setting of the object, resolved through the
   usual inheritance. **`inherit`** (or `var()` of the setting's own name) reads the
-  parent's value of the same setting (`alpha="calc(inherit / 2)"`). `var(--name)` reads a custom variable: from the
+  parent's value of the same setting (`opacity="calc(inherit / 2)"`). `var(--name)` reads a custom variable: from the
   nearest `vars` (figure or plot), else a `"--name"` key of the style. The fallback is used
   when the value is unset. Loops raise. Text settings (titles, labels, names, formats)
   never read `var()`.
@@ -201,7 +263,8 @@ What `%` of a length can be of, besides another setting (the tables name it per
 | `axes_length` | the axes length along the axis |
 | `data_range` | the axis range |
 | `bar_across` | the axes side across the colorbar |
-| `bar_along` | the axes side along the colorbar |
+| `bar_thickness` | the span along a key, the axes side across a bar |
+| `bar_along` | the span along the colorbar (the axes side of an attached one) |
 | `figure` | the figure width (across) or height (down) |
 | `slot` | the slot: one category, or the smallest gap between positions |
 | `slot_part` | each series' part of a shared slot |
@@ -212,8 +275,9 @@ What `%` of a length can be of, besides another setting (the tables name it per
 #### Setting groups
 
 Members, their names under a prefix `{p}`, and the group defaults (`"Group.member"` keys).
-`"FillStyle.fill"` sets every series fill (bars, boxes, violins, pies, densities,
-contours, genome signals and intervals); `"Marker.fill"` every marker fill.
+`"FillStyle.fill_opacity"` sets the opacity of every series fill (bars, boxes, violins,
+pies, densities, contours, genome signals and intervals); `"Marker.fill"` turns every
+marker fill on or off.
 
 <!-- settings:groups -->
 | Group | Member | Under a prefix `{p}` | Default |
@@ -223,12 +287,14 @@ contours, genome signals and intervals); `"Marker.fill"` every marker fill.
 | `Font` | `font_stretch` | `{p}font_stretch` | inherited |
 | `Font` | `font_variations` | `{p}font_variations` | inherited |
 | `Font` | `font_optical_sizing` | `{p}font_optical_sizing` | inherited |
+| `Font` | `line_height` | `{p}line_height` | inherited |
+| `Font` | `markup` | `{p}markup` | inherited |
 | `TextStyle` | `font_size` | `{p}font_size` | '1em' |
 | `TextStyle` | `font_weight` | `{p}weight` | 'normal' |
 | `TextStyle` | `font_style` | `{p}style` | 'normal' |
 | `TextStyle` | `color` | `{p}color` | 'var(text_color)' |
 | `Stroke` | `color` | `{p}color` | — |
-| `Stroke` | `line_width` | `{p}width` | 0.75 |
+| `Stroke` | `line_width` | `{p}width` | 0.5 |
 | `Stroke` | `line_style` | `{p}style` | 'solid' |
 | `Stroke` | `cap` | `{p}cap` | 'butt' |
 | `Stroke` | `join` | `{p}join` | 'round' |
@@ -236,10 +302,12 @@ contours, genome signals and intervals); `"Marker.fill"` every marker fill.
 | `Marker` | `size` | `{p}size` | 4.5 |
 | `Marker` | `color` | `{p}color` | — |
 | `Marker` | `edge_color` | `{p}edge_color` | 'auto' |
-| `Marker` | `edge_width` | `{p}edge_width` | 0.75 |
+| `Marker` | `edge_width` | `{p}edge_width` | 0.5 |
 | `Marker` | `fill` | `{p}fill` | True |
+| `Marker` | `fill_opacity` | `{p}fill_opacity` | 1.0 |
 | `Marker` | `size_basis` | `size_basis (never prefixed)` | 'area' |
 | `FillStyle` | `fill` | `{p}fill` | — |
+| `FillStyle` | `fill_opacity` | `{p}fill_opacity` | — |
 | `NumberFormat` | `decimal_separator` | `{p}decimal_separator` | inherited |
 | `NumberFormat` | `thousands_separator` | `{p}thousands_separator` | inherited |
 | `NumberFormat` | `minus` | `{p}minus` | inherited |
@@ -262,8 +330,11 @@ pl.Figure(**settings)
 fig.plot(id=None, **settings)            # the plot with id (created if needed), or the next one
 fig.scatter(x, y, **settings)            # any plot type: a new plot holding it
 fig.title(text, **settings)              # figure title
+fig.add_title(text, plots=None, side="top", **settings)   # another, over plots
+fig.add_legend(plots=None, side="right", **settings)      # a legend of plots' entries
 fig.x_axis(**settings)                   # settings of every plot's x axis (fig.y_axis: y)
-fig.colorbar(source, id=None, **settings)    # the guide of a color axis, in its own area
+fig.add_colorbar(source=None, plots=None, side="bottom", **settings)  # beside plots
+fig.colorbar_area(source, id=None, **settings)   # a color axis' guide in its own area
 fig.color_axis(**settings)               # a shared color axis (fig.size_axis: size)
 fig.size_legend(source, id=None, values=None, title=None)
 fig.track(**settings)                    # a new track (layout="tracks")
@@ -271,6 +342,7 @@ fig.vline(x, rows=None, **settings)      # through plots and the gaps between th
 fig.vspan(x0, x1=None, rows=None, **settings)
 fig.group(first, last=None, label=None, letter=None)
 fig.plots                                # plots in creation order
+fig.titles, fig.legends, fig.colorbars   # figure titles (main first), legends, colorbars
 ```
 
 A plot type called on the figure (`fig.scatter(…)`, `fig.hist(…)`, `fig.bigwig(…)`) makes
@@ -326,30 +398,36 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 | `"axes"` | each cell's axes are `width` | the widest plot box of a column (axes plus the column's largest margins) is `width`; the axes are what is left | the figure is `width`; the axes share what the gutters leave |
 | `"borders"` | a column's box is `width` plus the largest margins in it, so every axes rectangle is at least `width` | each cell's box is `width` | the figure is `width`; the boxes share what the gaps leave |
 
-* Columns (rows) holding only vertical (horizontal) colorbars are as wide as the bar,
-  unless `widths` (`heights`) is given.
+* Columns (rows) holding only vertical (horizontal) colorbars are as wide as the bar (a
+  key: as wide as it is), unless `widths` (`heights`) is given.
 * Margins come from the real text metrics of tick labels, axis labels, titles, outside
   legends and attached colorbars ([layout](#layout)).
 
 ### Layout
 
 * **Bands.** A plot is its axes rectangle with four stacks of bands around it, from the
-  axes outward: tick marks, tick labels, the ×10ᵏ offset (above the y axis), the axis
-  label, twin axes, an outside legend, attached colorbars, the plot title (top) and the
-  plot's `space_above`; outermost on the left, the row label and group bands, as wide as the
-  widest of the plot's grid column. Each band has a thickness and an overhang along its
-  side (tick labels past the ends of the axis, a wide title). A side's margin is its
-  bands' thicknesses, at least the overhangs of the bands across it. Bands stack: each
-  starts past the ones before it (mirrored ticks included), the title past everything on
-  top; only twin axes are drawn at the axes edge.
+  axes outward: tick marks, tick labels, the axis label, twin axes, the y axis' ×10ᵏ
+  offset (on top, past the x axis and twin x axes there), an outside legend, attached
+  colorbars, the plot's titles and (on top) the plot's `space_above`; outermost on the
+  left, the row label band and the band of [group](#rows) letters, as wide as the widest
+  of the plot's grid column. Each band has a thickness and an overhang along its side
+  (tick labels past the ends of the axis, a wide title or axis label). A side's margin is
+  its bands' thicknesses, at least the overhangs of the bands across it. Bands stack:
+  each starts past the ones before it (mirrored ticks included), the titles past
+  everything on their side; only twin axes are drawn at the axes edge. An axis label
+  (a string) longer than the plot's box along its axis (the axes and the other axis'
+  ticks and tick labels) wraps at spaces to that length.
 * **Grid.** Each line between cells takes the largest margin of the plots there
   (`align="axes"`), or each plot's axes are what its margins leave of its box
   (`"borders"`). Colorbars and size legends in their own areas are cells of the grid; the
-  figure title is a band at the top of the figure.
+  figure title is a band at the top of the figure, and the other figure titles, the
+  figure legends and colorbars and the groups' labels sit in lanes in the lines between
+  cells ([figure title](#figure-title)).
 * **Rounds.** Only what is circular is repeated: an axis' length sets its ticks, whose
   labels set the margins, which (with `reference="plot"` or `"figure"`) set the length;
   `data_ratio`; stats binned at the axes' resolution ([hexbin](#hexbin), genome
-  [bins](#9-genome-tracks)); the figure title's band in a figure of fixed height. A round
+  [bins](#9-genome-tracks)); the figure title's band in a figure of fixed height; the
+  lanes of figure titles that wrap to the width of the plots they cover. A round
   measures every plot for its axes size and solves the grid. Rounds stop when no axes size
   moves by more than 1/3 px; after 5, a layout still moving (between two tick sets) keeps
   the last. With `reference="axes"` one round suffices. `position="auto"` legends are
@@ -357,10 +435,13 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 * **Geometry.** The layout ends in a frozen geometry: every axes rectangle, tick mark,
   text run, legend entry and colorbar in px. Drawing reads it and measures nothing: a text
   run holds its shaped line (shaped once per content and font, memoized in the font
-  database), which is what is drawn; the figure title is laid out once as paragraphs.
+  database), which is what is drawn; figure titles on top and bottom are laid out once as
+  paragraphs.
 * **One plot.** `p.save()` lays out the whole figure and keeps the plot at its size in it:
   its axes (`align="axes"`), or its box (`"borders"`: the axes are what its own margins
-  leave), with its outer tick labels and its own row label band.
+  leave), with its outer tick labels, its own row label band, its own titles and its
+  whole legend and its attached colorbars (figure titles, legends and colorbars are left
+  out).
 
 ### Figure title
 
@@ -368,32 +449,84 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 fig.title(text, **settings)        # None removes it
 ```
 
-A band at the top of the figure: the title's height (all lines, wrapped within its
-width) plus `pad`. The figure grows by the band, except with `reference="figure"`, where
-the plots shrink by it. `over="axes"` aligns it within the leftmost to
-rightmost axes (a left-aligned title starts at the first y axis line), `"figure"` within
-the figure minus `margin`. Rich content styles a second line (`["Title\n",
-pl.Span("subtitle", font_size=7, font_weight="normal")]`). It is drawn last and is not
-part of `Plot.save`. `title=` given to `pl.Plot` sets the plot title. The figure's
-`title_rule_color` draws a rule `title_rule_width` thick above the title, across its
-width.
+```python
+fig.add_title("Treated", plots=[a, b], side="top", **settings)   # returns it
+fig.titles                         # the main title first
+```
+
+The main title is a band at the top of the figure: the title's height (all lines,
+wrapped within its width) plus `pad`. The figure grows by the band, except with
+`reference="figure"`, where the plots shrink by it. `over="axes"` aligns it within the
+leftmost to rightmost axes (a start-aligned title starts at the first y axis line),
+`"plot"` within their boxes, `"figure"` within the figure minus `margin`. Rich content
+styles a second line (`["Title\n", pl.Span("subtitle", font_size=7,
+font_weight="normal")]`). It is drawn last and is not part of `Plot.save`. `title=` given
+to `pl.Plot` sets the plot title. `rule` draws a line `rule_width` thick across its width:
+`"outside"` above the title (The Economist's red bar, in the `economist` style), `True`
+between the title and the plots.
+
+`fig.add_title` makes a title over a set of plots (plots or their series, as
+`fig.group` takes them; default every plot), which covers the grid rectangle of their
+cells: a plot inside that rectangle but not given is an error naming it. Figure titles
+share the settings of plot titles ([title](#title)).
+
+```python
+fig.add_title("Sites", plots=[a, b, c])
+fig.add_title("Treated", plots=[a, b])              # nested: under "Sites"
+fig.add_title("Control", plots=[d, e], rule=True)   # beside another span: same lane
+fig.add_title("Batch 1", plots=[a, d], side="left")
+```
+
+* **Lanes.** A figure title sits in the line between cells beside the plots it covers: a
+  top title above its topmost row, a bottom one below its bottommost, a left or right one
+  beside its first or last column. The titles of one side of a line stack outward from
+  the plots: a title whose plots are a subset of another's is nearer, titles over
+  disjoint spans share a lane, overlapping ones take lanes in creation order; `order`
+  overrides (lower nearer; unset counts as the lane the rules give): a title sits past
+  every lane of a lower order, and titles of one order share a lane where their spans
+  are disjoint. A lane is as thick
+  as its thickest title: `pad`, the text, and `rule_width + rule_gap` with a rule. Plot
+  titles are inside the plots' boxes, nearer than any figure title. Figure legends and
+  colorbars take lanes too ([figure legends](#figure-legends), [colorbars](#colorbars));
+  over the same plots, from the plots outward: legend, colorbar, title.
+* **Gaps.** The gap at a line between rows (columns) is `spacing` plus its lanes, along
+  the whole line, so the titles in it line up. On the figure's edge, the lanes come between
+  two `margin`s, one at the edge and one between them and the plots, as the main title's
+  band does. With `reference="figure"` the plots shrink by the lanes; otherwise the
+  figure grows.
+* **Text.** Titles on top and bottom wrap to their span (`over`); titles on the left and
+  right do not (`\n` starts a line) and read upward on the left, downward on the right.
+* A [group](#rows)'s `label` is a left figure title over its plots.
+* The main title is the outermost lane of the top, over every plot. On another side,
+  rotated, or with an `order`, it is laid out in the lanes as the others are.
+  Style keys `"MainTitle.name"` apply to it alone, `"FigureTitle.name"` to every figure
+  title.
+* `p.save()` (one plot alone) leaves out the figure titles, legends and colorbars.
 
 <!-- settings:FigureTitle -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `text` | — | Title text: a string or rich content; `\n` starts a line. |
+| `side` | 'top' | `top`, `bottom`, `left` or `right`. |
+| `align` | 'center' | Alignment along the side: `start`, `center`, `end`, or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right; there `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
+| `over` | 'axes' | Span it is aligned and wrapped within: from the first to the last axes of its plots, their boxes, or the whole figure. |
+| `rotation` | 'auto' | `auto`: 0 on top and bottom, 90 on the left (reads upward), −90 on the right (reads downward); or 0, 90, −90. |
+| `pad` | '0.5em' | Gap between the title and the plots. Length. |
+| `order` | — | Place in its side's lanes: lower is nearer the plots; unset: a title nested in another nearer, then creation order. |
+| `rule` | False | A line along the span: `True` or `"inside"` between the title and what it covers, `"outside"` beyond the title, `False` none. |
+| `rule_color` | 'var(color)' | Color of the rule. |
+| `rule_width` | 'var(line_width)' | Thickness of the rule. Length. |
+| `rule_gap` | '0.5em' | Gap between the rule and the title. Length; `%`: of the font size. |
 | `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
 | `font_weight` | 'bold' | `normal`, `bold` or a weight 1–1000. |
 | `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
-| `align` | 'center' | Alignment. |
-| `over` | 'axes' | Width it is aligned and wrapped within: from the leftmost to the rightmost axes, or the whole figure. |
-| `pad` | '0.5em' | Gap between the title and the plots; default half the font size. Length. |
 | `color` | 'var(text_color)' | Text color. |
-| `rule_gap` | '0.5em' | Gap between the title and the figure's `title_rule_color`. Length; `%`: of the font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `TextStyle`, `Font`.
 <!-- /settings -->
@@ -411,7 +544,8 @@ the same column span) or `"row"` (the same row span). `share` sets both; `"grid"
 per column and y per row. A plot's own `share_x`, `share_y` or `share` (another plot)
 overrides the figure's groups for it; groups chain. Colorbars and plots without axes are
 never in a group. `share_color` and `share_size` group plots the same way for their
-series' color and size axes ([color and size axes](#6-color-and-size-axes)).
+series' color and size axes ([color and size axes](#6-color-and-size-axes)), and
+`share_legend` for one legend of their entries ([figure legends](#figure-legends)).
 
 Within a group the scale (which must be equal), the limits (from all members' series,
 then padding, `include_zero` and `snap`; one explicit `limits` applies to the group, two
@@ -451,9 +585,15 @@ fig.vspan(-1, 1)                                 # under every plot
   label: beside its axis or in the band. Tracks put theirs in the band. A plot's
   `space_above` adds space above it.
 * **Groups.** `fig.group(first, last=None, **settings)`: plots `first` to `last` (plots
-  or their series, in creation order) with a rotated `label` and a bold panel `letter` in a
-  band left of the row labels. With a shared x axis and `label_outer`, the group's last
-  plot shows the tick labels too (the axis title stays under the bottom plot).
+  or their series, in creation order). Its `label` is a left [figure title](#figure-title)
+  over them, reading upward, centered on their axes, in the group's font settings
+  (`font_size`, `font_family`, `text_color`, `markup`; normal weight) and `pad` from the
+  plots; it is made at each layout, in the group's creation order, and is not in
+  `fig.titles`. The plots must fill the grid rectangle they span. A bold panel `letter`
+  sits in a band left of the row labels, level with the top of the first plot's axes.
+  With a shared x axis and `label_outer`, the group's last plot shows the tick labels too
+  (the axis title stays under the bottom plot). `p.save()` leaves out the label, as other
+  figure titles.
 * **Lines and bands.** `fig.vline(x, rows=None)` and `fig.vspan(x0, x1, rows=None)` run
   from the top of the first of the plots `rows` (a plot, a series, or a list; all by
   default) to the bottom of the last one, gaps included, in each grid column; `x` is in
@@ -467,9 +607,9 @@ FigureVLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'dashed' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 
 Groups: `Stroke`.
 <!-- /settings -->
@@ -480,7 +620,7 @@ FigureVSpan:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#e5e5e5' | Fill color. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 <!-- /settings -->
 
 FigureGroup:
@@ -488,16 +628,17 @@ FigureGroup:
 <!-- settings:FigureGroup -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `label` | — | Group label, rotated, left of the plots' row labels. |
-| `letter` | — | Panel letter at the group's top left. |
+| `label` | — | Group label: a left figure title over the group's plots, reading upward, centered on their axes. |
+| `letter` | — | Panel letter at the group's top left, left of the row labels. |
 | `font_size` | '1em' | Font size of the label. Length; `%`: of the parent's font size. |
 | `letter_font_size` | '1.4em' | Font size of the letter. Length; `%`: of the font size. |
 | `letter_weight` | 'bold' | Weight of the letter. |
-| `pad` | '0.5em' | Gap right of the group band. Length; `%`: of the font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `pad` | '0.5em' | Gap right of the letter, and the label's `pad` (its gap to the plots). Length; `%`: of the font size. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
-Groups: `TextStyle` (`letter_`).
+Groups: `TextStyle` (`letter_`), `Font`.
 <!-- /settings -->
 
 ### Facets
@@ -526,10 +667,12 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
   column, y per row, outer labels only), `share_color` (default `"all"`: the panels'
   color axes train as one; a `color_map`, `color_limits` or `color_scale` given to the
   call goes to each series alike) and `share_size` (default `"all"`: one size axis, so
-  one size key, in the top-right panel's legend).
-* **Colorbar.** `colorbar="right"`, `"left"`, `"top"` or `"bottom"` adds a column (or a
-  row, with a horizontal bar) to the grid, holding the colorbar of the first call that maps
-  colors (`panels.colorbar`): the guide of the panels' shared color axis.
+  one size key) and `share_legend` (default `"all"`: one legend for the panels' entries,
+  on the right, [figure legends](#figure-legends)).
+* **Colorbar.** `colorbar="right"`, `"left"`, `"top"` or `"bottom"` adds the colorbar of
+  the first call that maps colors (`panels.colorbar`, a
+  [figure colorbar](#colorbars) over every panel, `fig.add_colorbar`) on that side: the
+  guide of the panels' shared color axis.
 * `panels.panels` maps facet keys (a value, or `(row value, col value)`) to plots;
   `panels.plot(key)` returns one; iterating the set gives the plots; `panels.subsets()`
   gives `(key, plot, rows)`.
@@ -546,35 +689,37 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
 | `align` | 'axes' | `axes`: axis lines line up across plots; `borders`: plot boxes line up. |
 | `widths` | — | Column widths: ratios (numbers or `fr`) sharing the room left by fixed lengths (`"2in"`, `"30%"` of the figure width). |
 | `heights` | — | Row heights, as `widths`. |
-| `width` | '150px' | Width of the `reference` box: one cell's axes, one cell's plot, or the figure. Length. |
-| `height` | 'calc(var(width) / var(aspect_ratio))' | Height of the `reference` box. Length. |
+| `width` | '150px' | Width of the `reference` box: one cell's axes, one cell's plot, or the figure; a paper size names its width (`"a4"`, `"letter"`, `"a4-landscape"`). Length. |
+| `height` | 'calc(var(width) / var(aspect_ratio))' | Height of the `reference` box (a paper size: its height). Length. |
 | `aspect_ratio` | 1.25 | Width / height of the `reference` box (16:9 → `16 / 9`), when only one of `width` and `height` is given. |
 | `reference` | 'axes' | What `width` and `height` measure: `axes` (each grid cell's axes rectangle), `plot` (each cell's whole plot box) or `figure`. |
 | `spacing` | 13.0 | Minimum gap between neighbouring plots. Length; `%`: of the figure width (across) or height (down). |
 | `margin` | 5.0 | Space around the figure. Length; `%`: of the figure width (across) or height (down). |
-| `background` | 'white' | Figure background, default white; `None` or `"none"`: transparent (white in JPEG, which has no transparency). |
-| `dpi` | 192.0 | Resolution of PNG, JPEG, JPEG XL and AVIF output: `96` gives one image pixel per px, the default `192` two; up to 16, a multiple of 96 (`2` is 192). |
-| `quality` | 'auto' | Quality (1–100), as vec_io's: of PNG output (a lossy palette of at most 256 colors), JPEG, JPEG XL and AVIF output, and of rasterized content in PDFs (stored as JPEG); `"lossless"` (not JPEG); `"auto"`: 90 for PNG and JPEG, lossless for JPEG XL, AVIF and PDF content. |
-| `title_rule_color` | — | Color of a rule above the figure title, across its width (The Economist's red bar); default none. |
-| `title_rule_width` | 4.0 | Thickness of the title rule. Length. |
+| `background` | 'white' | Figure background, default the style's (white); `"none"` or `"transparent"`: transparent (white in JPEG, which has no transparency). `None` unsets it. |
+| `fonts` | — | Where fonts come from: a vec_io `Fonts` or a dict of its fields (`dirs`, `system`, `downloads`: `True`, `False` or `"cache"`, `db`); unset: `VEC_IO_FONT_DIRS`, installed fonts and `VEC_IO_FONT_DOWNLOADS` (downloads on by default). |
+| `default_dpi` | '4x' | Resolution of PNG, JPEG, JPEG XL and AVIF output when `save`/`write` give no `dpi`: dots per inch, or a multiple of 96 (`"2x"` is 192); `96` gives one image pixel per px, the default `"4x"` four. PDF, EPS and SVG output never use it. |
+| `quality` | 'auto' | Quality (1–100), as vec_io's: of PNG output (a lossy palette of at most 256 colors), JPEG, JPEG XL and AVIF output, and of rasterized content in PDF and SVG output (stored as JPEG); `"lossless"` (not JPEG); `"auto"`: 90 for PNG and JPEG, lossless for JPEG XL, AVIF and PDF content. |
 | `share_x` | — | Plots sharing their x axis: `False`, `True`/`"all"`, `"col"` (same column span) or `"row"` (same row span). |
 | `share_y` | — | Plots sharing their y axis, as `share_x`. |
 | `share` | — | Both axes at once: as `share_x`, or `"grid"` (x per column, y per row); `share_x`/`share_y` override it. |
 | `share_color` | False | Plots whose series' own color axes are one (limits over all their values), as `share_x`. |
 | `share_size` | False | Plots whose series' own size axes are one (limits over all their values, one size key), as `share_x`. |
+| `share_legend` | False | Legends shared by plots, made by the figure: `False`, `True`/`"all"` (one on the right of the figure), `"row"` (one on the right of each row), `"col"` (one at the bottom of each column). |
 | `label_outer` | — | Tick labels and axis titles of shared axes only on the outer plots (bottom of each column, left of each row); default `True` for groups from the figure's settings, `False` for plots paired with `share_x=plot`. |
 | `style` | — | A style name (`"ggplot2"`, …) or a dict of settings with an optional `"base"`; default: the session style (`set_style`, `use_style`), else `"default"`. |
 | `vars` | — | Custom variables, read by `var(--name)` in any setting here and below: `{"accent": "#c00"}`. |
 | `scaling` | 1.0 | Multiplies every font size, line width, marker size, tick length and pad of the style; default 1. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (0.75) | Default line width. Length. |
+| `line_width` | inherited (0.5) | Default line width. Length. |
 | `palette` | inherited ('tab10_custom') | Colors of series without one. |
-| `alpha` | inherited (1.0) | Default opacity of series. |
+| `opacity` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
 | `simplify` | inherited ('auto') | vec_io's `simplify` for every series; default `"auto"`. |
 | `data` | inherited (None) | A table whose columns the series' data arguments name. |
@@ -586,22 +731,27 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
 
-Groups: `Stroke` (`title_rule_`), `Font`, `NumberFormat`.
+Groups: `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ## 3. Plots
 
 ```python
-pl.Plot(figure=None, id=None, **settings)   # title="…", x_axis={…}, y_axis={…}
+pl.Plot(figure=None, id=None, **settings)   # title=, x_axis={…}, y_axis={…}, legend=, colorbar=
 p.scatter(x, y, **s)   p.line(x, y=None, **s)   p.fill(x, y1, y2=0, **s)
-p.box(values, **s)     p.heatmap(values, **s)   p.colorbar(source=None, **s)
-p.title(text, **s)     p.x_axis(label, **s)     p.y_axis(label, **s)    p.legend(position, **s)
-p.series   p.colorbars   p.figure   p.id
+p.box(values, **s)     p.heatmap(values, **s)   p.dots(color, size=None, **s)
+p.title(text, **s)     p.x_axis(label, **s)     p.y_axis(label, **s)
+p.add_title(text, side="top", **s)              # another title, returned
+p.add_legend(position=None, **s)                # the plot's legend (p.legend), returned
+p.add_colorbar(source=None, side=None, **s)     # an attached colorbar, returned
+p.series   p.titles   p.colorbars   p.figure   p.id
 ```
 
-`p.title`, `p.x_axis`, `p.y_axis` and `p.legend` are objects; calling one sets its
-settings and returns it. At creation (and in `p.set`), `title=` sets the title text and
-`x_axis={…}`, `y_axis={…}` set the axes' settings: `pl.Scatter(x, y, x_axis={"scale":
+`p.title`, `p.x_axis` and `p.y_axis` are objects; calling one sets its settings and
+returns it (`p.legend` is set by `p.add_legend`, or `p.legend.set`). At creation (and in
+`p.set`), `title=` sets the title text, `x_axis={…}`, `y_axis={…}` set the axes' settings,
+`legend=` (a position, a dict of legend settings or `False`) calls `add_legend` and
+`colorbar=` (`True`, a side or a dict of colorbar settings) `add_colorbar`: `pl.Scatter(x, y, x_axis={"scale":
 "log"})`, `fig.bigwig(reader, y_axis={"label": "ATAC"})`. Series are drawn in `z` order (default: call order) inside the
 axes clip.
 
@@ -612,7 +762,7 @@ axes clip.
 | `data_ratio` | — | Data aspect ratio: 1 makes one unit as long on both axes. |
 | `background` | — | Background color of the axes area. |
 | `border_color` | — | Color of a frame around the axes area (drawn under the axis lines); default none. |
-| `border_width` | 0.75 | Width of the frame. Length. |
+| `border_width` | 0.5 | Width of the frame. Length. |
 | `clip` | True | Clip series to the axes area. |
 | `axes` | True | Draw axes; `False` hides both axes, drops padding and fixes the aspect to 1 (set by pie charts). |
 | `share_x` | — | Another plot of the figure whose x axis this plot shares (groups chain); overrides the figure's `share_x`. |
@@ -621,14 +771,16 @@ axes clip.
 | `share` | — | Another plot whose x and y axes this plot shares. |
 | `space_above` | 0.0 | Space above the plot, beyond the figure's `spacing`. Length; `%`: of the font size. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (0.75) | Default line width. Length. |
+| `line_width` | inherited (0.5) | Default line width. Length. |
 | `palette` | inherited ('tab10_custom') | Colors of series without one. |
-| `alpha` | inherited (1.0) | Default opacity of series. |
+| `opacity` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
 | `simplify` | inherited ('auto') | vec_io's `simplify` for every series: `"auto"`, `True`, a dpi or `False`. |
 | `color_map` | inherited ('rainbow_llhh') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
@@ -645,42 +797,83 @@ Groups: `Stroke` (`border_`), `Font`, `NumberFormat`.
 
 ### Title
 
+```python
+p.title("Yield")                                 # the main title
+p.add_title("Subtitle", order=-1)                # between the main title and the axes
+p.add_title("n = 120", side="bottom", align="start")
+p.add_title("Batch 1", side="left", rule=True)
+```
+
+A plot has a main title (`p.title`) and any number of others (`p.add_title`, which
+returns the title; `p.titles` lists them, main first), each on a `side` of the plot.
+The titles of one side stack outward from the axes, outermost of the side's bands (past
+the axis, twin axes, an outside legend and attached colorbars): the main title nearest,
+then the others in creation order; `order` places a title elsewhere, lower nearer
+(`order=-1`: a subtitle between the main title and the axes). Each takes a band of its
+`pad`, its text across the side and, with a `rule`, `rule_width + rule_gap`; the rule runs
+along its span (`over`). `\n` starts a line, `line_height` apart; the last line is
+nearest the axes on top and on the left and right, the first at the bottom. Left titles
+read upward, right titles downward (`rotation="auto"`); `rotation=0` sets them
+horizontal, beside the axes.
+
+`align` takes the vocabulary of figure legends and colorbars: `start`, `center`, `end`, or
+an end by name. On top and bottom, `start` is the left end (`left`, `right` name the
+ends); on the left and right, `start` is where the text begins (the bottom for text
+reading upward, else the top) and `top`, `bottom` name the ends.
+
 <!-- settings:Title -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `text` | — | Title text: a string or rich content. |
+| `text` | — | Title text: a string or rich content; `\n` starts a line. |
+| `side` | 'top' | `top`, `bottom`, `left` or `right`. |
+| `align` | 'center' | Alignment along the side: `start`, `center`, `end`, or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right; there `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
+| `over` | 'axes' | Span the title is aligned within: the axes, or the axes and the axis labels beside them (the y axis' on top and bottom, the x axis' on the left and right). |
+| `rotation` | 'auto' | `auto`: 0 on top and bottom, 90 on the left (reads upward), −90 on the right (reads downward); or 0, 90, −90. |
+| `pad` | 5.0 | Gap between the title and what it covers. Length; `%`: of the axes height. |
+| `order` | — | Place in its side's stack: lower is nearer; unset: the main title nearest, then the others in creation order. |
+| `rule` | False | A line along the span: `True` or `"inside"` between the title and what it covers, `"outside"` beyond the title, `False` none. |
+| `rule_color` | 'var(color)' | Color of the rule. |
+| `rule_width` | 'var(line_width)' | Thickness of the rule. Length. |
+| `rule_gap` | '0.5em' | Gap between the rule and the title. Length; `%`: of the font size. |
 | `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
 | `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
 | `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
 | `color` | 'var(text_color)' | Text color. |
-| `align` | 'center' | Alignment over the axes. |
-| `pad` | 5.0 | Gap above the axes. Length; `%`: of the axes height. |
-| `over` | 'axes' | Width the title is aligned within: the axes, or the axes and the y axis labels. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `TextStyle`, `Font`.
 <!-- /settings -->
 
 ### Legend
 
+```python
+p.add_legend("top_left", frame=True)          # the plot's legend, p.legend; returns it
+fig.plot(legend="outside_right")              # the same, when the plot is made
+```
+
 One entry per series with a `name`, drawn as the series draws itself (marker, line,
 swatch or box), or with `glyph="box"`, `"circle"` or `"line"` in the series color. At
 `top`, `bottom`, `outside_top` and `outside_bottom` entries are side by side unless
-`orientation` or `columns` is set.
-
-**Size keys.** A series whose `size` goes through a [size axis](#6-color-and-size-axes)
-adds a size key, the axis' guide, to its plot's legend, below the series entries: the
-axis' `label` (default: the `size` column name) as a header, then sample markers at their
-real size with their values (the list given as the series' `size_legend`, else the axis'
-`ticks`, else 3–5 nice numbers inside its limits; in its `tick_format`;
-`size_legend=False` drops it). Series sharing one size axis (one `fig.size_axis()`, or own
-axes trained as one by `share_size` or `group=`) share one key, in grey, also across
-plots. The key goes in the legend of the rightmost of their plots, and the topmost of
-those, so it sits at the figure's top right. Users with different `size_map`s get a key
-per map. A single series' key takes its color (grey when its colors are mapped).
+`orientation` or `columns` is set. Outside the axes, without `columns`, entries wrap
+within the axes' length along their side: into rows as wide as the axes on top and
+bottom, into columns as tall as the axes on the right.
+
+**Size keys in the legend.** A series whose `size` goes through a
+[size axis](#6-color-and-size-axes) has a size key, the axis' guide: by default a key
+like a colorbar's ([size keys](#size-keys)); with `size_key="legend"`, rows in its
+plot's legend, below the series entries: the axis' `label` (default: the `size` column
+name) as a header, then sample markers at their real size with their values (the axis'
+`ticks`, else 3–5 nice numbers inside its limits; in its `tick_format`). Series sharing
+one size axis (one `fig.size_axis()`, or own axes trained as one by `share_size` or
+`group=`) share one key, in grey, also across plots. The key goes in the legend of the
+rightmost of their plots, and the topmost of those, so it sits at the figure's top
+right. Users with different `size_map`s get a key per map. A single series' key takes
+its color (grey when its colors are mapped).
 `fig.size_legend(source, id=…, values=None, title=None)` places the key of a size axis
 (or of a series' one) in its own grid area, as colorbars do. It shows every series of
 that axis, and no plot legend repeats it.
@@ -699,7 +892,7 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 <!-- settings:Legend -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `position` | 'auto' | `auto`, `top_right`, `top_left`, `bottom_right`, `bottom_left`, `top`, `bottom`, `outside_right`, `outside_top`, `outside_bottom` or `none`. |
+| `position` | 'auto' | `auto`, `top_right`, `top_left`, `bottom_right`, `bottom_left`, `top`, `bottom`, `center_right`, `center_left`, `outside_right`, `outside_top`, `outside_bottom` or `none`. |
 | `columns` | 1 | Number of columns. |
 | `frame` | False | Draw a frame and background. |
 | `title` | 'auto' | Legend title; `"auto"`: the `group` column name, if any. |
@@ -710,8 +903,8 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 | `frame_width` | 0.5 | Frame line width. Length. |
 | `pad` | 5.0 | Gap to the axes. Length; `%`: of the axes width (across) or height (down). |
 | `frame_radius` | 0.0 | Corner radius of the frame. Length. |
-| `frame_alpha` | 1.0 | Opacity of the frame and background. |
-| `glyph_alpha` | — | Fill opacity of `box` and `circle` symbols, outlined in the opaque color; default: the series' own fill. |
+| `frame_opacity` | 1.0 | Opacity of the frame and background. |
+| `glyph_opacity` | — | Fill opacity of `box` and `circle` symbols, outlined in the opaque color; default: the series' own fill. |
 | `glyph` | 'series' | Entry symbol: as the series draws itself, or a filled `box`, a `circle` or a `line` in the series color. |
 | `orientation` | 'auto' | `horizontal`: entries side by side; `auto`: horizontal at `top`, `bottom`, `outside_top` and `outside_bottom`. |
 | `glyph_length` | '1.4em' | Width of an entry's symbol. Length; `%`: of the font size. |
@@ -720,14 +913,68 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 | `column_gap` | '1em' | Gap between columns. Length; `%`: of the font size. |
 | `title_gap` | '0.3em' | Gap below the title. Length; `%`: of the font size. |
 | `inner_pad` | 'auto' | Space inside the box; `"auto"`: 0.5em with a frame, 0.15em without. Length; `%`: of the font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `TextStyle`, `Stroke` (`frame_`), `Font`.
 <!-- /settings -->
 
+#### Figure legends
+
+```python
+fig.add_legend(plots=[a, b], side="right", **settings)   # returns it
+fig.add_legend()                                        # every plot, on the right
+fig.legends
+fig = pl.Figure(cols=2, share_legend="row")              # one legend per row
+```
+
+A figure legend shows the entries of a set of plots (plots or their series; default every
+plot) in one legend, in the lanes beside them as [figure titles](#figure-title) are: its
+plots' cells must fill the grid rectangle they span (a plot inside it but not given is an
+error naming it).
+
+* **Entries.** Its plots' entries, in plot order (row by row), then in series order.
+  Entries with the same label and the same symbol (what the legend draws for them: kind,
+  colors, marker, line style and width) are one entry; the same label with another
+  symbol keeps both. A size key whose series' plots the legend all covers goes into it
+  (the first such legend), one key per shared size axis as in a plot legend.
+* **Plot legends.** Its plots' legends lose those entries, and a plot left without
+  entries shows no legend. A plot whose `legend.position` is set keeps its legend whole
+  (the figure legend shows its entries too).
+* **Place.** `side` (`top`, `bottom`, `left`, `right`) and `align` along the side
+  (`start`: the left or top end, `center`, `end`; or `left`, `right` on top and bottom,
+  `top`, `bottom` on the left and right) within the axes of its plots, kept within the figure; the
+  figure grows when the legend is longer than its content. On top and bottom, entries
+  are side by side in rows as wide as the span (unless `columns` is set); on the left and
+  right, in a column (`columns`).
+* **Lanes.** Legends and figure titles share the lanes and their rules (nesting, then
+  shared lanes for disjoint spans, then creation order; `order` overrides); over the same
+  plots, a legend is nearer the plots than a title. A legend without entries takes no
+  lane.
+* **`share_legend`** (`False`, `True`/`"all"`, `"row"`, `"col"`) makes figure legends for
+  the groups `share_color` would make (two plots or more): one on the right of the
+  figure (`"all"`), of each row (`"row"`), one at the bottom of each column (`"col"`).
+  A group with a plot an `add_legend` legend covers gets none. They take the
+  `FigureLegend` (and `Legend`) keys of the style, but their `side`.
+* `p.save()` (one plot alone) leaves out figure legends: the plot's legend shows all its
+  entries.
+
+Figure legends have the settings of plot legends but `position`, `orientation`, and:
+
+<!-- settings:FigureLegend -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `side` | 'right' | `top`, `bottom`, `left` or `right` of its plots. |
+| `align` | 'center' | Alignment along the side: `start` (left, or top), `center`, `end` (right, or bottom), or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right. |
+| `order` | — | Place in its side's lanes, as figure titles' `order`: lower is nearer the plots. |
+| `pad` | 5.0 | Gap between the legend and the plots. Length. |
+| `title` | 'auto' | Legend title; `"auto"`: the `group` column name of its plots' series, if any. |
+<!-- /settings -->
+
 ### Decorations
 
 Reference lines, bands, text and annotations. They take no palette color, are in the
@@ -755,12 +1002,12 @@ HLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
 | `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
 | `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 | `z` | 1.0 | Drawing order among the series (default 0). |
 | `extend_limits` | False | Include the decoration in the axis limits. |
 | `clip` | True | Clip to the axes area. |
@@ -774,10 +1021,10 @@ AxLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 | `z` | 1.0 | Drawing order among the series (default 0). |
 | `extend_limits` | False | Include the decoration in the axis limits. |
 | `clip` | True | Clip to the axes area. |
@@ -796,7 +1043,7 @@ HSpan:
 | `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
 | `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 | `z` | -1.0 | Drawing order among the series (default 0). |
 | `extend_limits` | False | Include the decoration in the axis limits. |
 | `clip` | True | Clip to the axes area. |
@@ -815,15 +1062,17 @@ Text:
 | `coords` | 'data' | `data`, `axes` (0–1) or `figure` (0–1). |
 | `color` | 'var(text_color)' | Text color; default `text_color`. |
 | `font_size` | inherited (11.0) | Font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
 | `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
 | `text_color` | inherited ('black') | Text color. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 | `z` | 1.0 | Drawing order among the series (default 0). |
 | `extend_limits` | False | Include the decoration in the axis limits. |
 | `clip` | False | Clip to the axes area. |
@@ -842,7 +1091,7 @@ Annotate:
 | `arrow` | True | Draw an arrow from the text to `xy`. |
 | `arrow_style` | '->' | `->` (open head), `-\|>` (filled head) or `-` (no head). |
 | `arrow_color` | 'var(color)' | Arrow color; default the text color. |
-| `arrow_width` | 0.75 | Arrow line width. Length. |
+| `arrow_width` | 0.5 | Arrow line width. Length. |
 | `head_length` | 7.0 | Arrowhead length. Length. |
 | `shrink` | 3.0 | Gap left at both ends of the arrow. Length. |
 
@@ -910,9 +1159,13 @@ grid only when its axis asks). `p.save` includes its twins.
 
 * `"auto"`: the union of the series' extents plus `padding` (0.05 of the range per side,
   in position space: a factor on log axes; heatmaps take none).
-* `"lo/hi"`: each side `min`, `max`, a number or `q:F` (quantile F of the axis's values):
-  `"0/max"`, `"q:0.01/q:0.99"`. Or `(lo, hi)`, `None` meaning automatic.
-* A single value is widened by ±0.5 in position space. `invert=True` reverses the axis.
+* `"lo/hi"`: each side `min`, `max` (any case), a number, an ISO date or time, or `q:F`
+  (quantile F of the axis's values): `"0/max"`, `"q:0.01/q:0.99"`,
+  `"2024-01-01T10:00Z/2024-02-01"`. Or `(lo, hi)`, `None` meaning automatic.
+* A single value is widened by ±0.5 in position space; a single time by one unit of its
+  data each side (a day at midnight, else an hour, a minute, a second).
+* `invert=True` reverses the axis; so do limits given high to low, `(2, 0)` (with
+  `invert=True` too, the axis is reversed once).
 * `include_zero=True` extends automatic limits to 0 (linear and sqrt axes) before padding
   and `snap`; `"auto"` does so where a series on the axis asks for it, following
   Vega-Lite's default: both axes of scatter plots, the value axis of lines, areas and
@@ -944,9 +1197,6 @@ grid only when its axis asks). `p.save` includes its twins.
 * `tick_format` takes any [number format](#number-formats); the default `"auto"` is the
   rule above.
 
-Category axes of heatmaps draw labels only (no axis line or ticks) unless `tick_length`
-or the plot's `spines` is set.
-
 * **Grid lines:** `grid` at the major ticks, `minor_grid` at the minor ticks (or halfway
   between major ticks on linear axes without minor ticks), and `zero_line` at 0 (when 0
   is within the limits), under the series.
@@ -977,7 +1227,7 @@ or the plot's `spines` is set.
 | `padding` | 'auto' | Space added to automatic limits, as a fraction of the range; `"auto"`: `auto_padding`, or 0 on axes of series drawn to exact limits (box value axes, heatmaps, …) and in plots without axes. Length; `%`: of the axis range. |
 | `auto_padding` | '5%' | The fraction `padding="auto"` adds on each side. Length; `%`: of the axis range. |
 | `sticky` | True | No padding past the baseline of bars and histograms when an automatic limit is on it (matplotlib's sticky edges). |
-| `invert` | False | Reverse the axis. |
+| `invert` | False | Reverse the axis (limits given high to low, `(2, 0)`, reverse it too). |
 | `ticks` | — | `False` (no ticks) or a list of tick values. |
 | `tick_labels` | — | Labels of `ticks`. |
 | `minor_ticks` | — | `True`, `False` or a list of values; default: on for log10. |
@@ -990,19 +1240,19 @@ or the plot's `spines` is set.
 | `category_label_spacing` | ('1.6em', '1.3em') | Distance between category labels: rotated (horizontal axes) and stacked (vertical axes); labels closer than it are thinned out. Length; `em` and `%`: of `tick_label_font_size`. |
 | `auto_max_ticks` | (10, 8) | Most automatic ticks on numeric and time axes. |
 | `sci_limits` | (-4, 5) | Exponents beyond which labels become mantissas × 10ᵏ. |
-| `tick_length` | 5.0 | Tick length. Length; `%`: of the axes side across the axis. |
+| `tick_length` | 6.0 | Tick length. Length; `%`: of the axes side across the axis. |
 | `minor_tick_length` | '60%' | Minor tick length; default 0.6 × `tick_length`. Length; `%`: of `tick_length`. |
 | `tick_direction` | 'out' | `out`, `in` or `both`. |
 | `tick_color` | 'var(color)' | Tick color. |
-| `tick_width` | 0.75 | Tick line width. Length. |
+| `tick_width` | 0.5 | Tick line width. Length. |
 | `tick_label_font_size` | '1em' | Font size of tick labels. Length; `%`: of the font size. |
 | `tick_label_weight` | 'normal' | Tick label weight: `normal`, `bold` or 1–1000. |
 | `tick_label_color` | 'var(color)' | Tick label color. |
-| `tick_pad` | 3.0 | Gap between ticks and labels. Length; `%`: of the axes side across the axis. |
-| `label_pad` | 4.0 | Gap between tick labels and the label. Length; `%`: of the axes side across the axis. |
+| `tick_pad` | 5.0 | Gap between ticks and labels. Length; `%`: of the axes side across the axis. |
+| `label_pad` | 5.0 | Gap between tick labels and the label. Length; `%`: of the axes side across the axis. |
 | `color` | 'var(text_color)' | Color of the axis line, ticks and labels (the default of `line_color`, `tick_color`, `tick_label_color`, `label_color`). |
 | `line_color` | 'var(color)' | Axis line color. |
-| `line_width` | 0.75 | Axis line width. Length. |
+| `line_width` | 0.5 | Axis line width. Length. |
 | `side` | x: 'bottom' / y: 'left' | Where the ticks, labels and axis line go: `bottom` or `top` (x axis), `left` or `right` (y axis). |
 | `mirror` | False | Ticks also on the opposite side of the axes. |
 | `spine_offset` | 0.0 | Distance the axis line (with its ticks and labels) is moved away from the axes. Length; `%`: of the axes side across the axis. |
@@ -1022,10 +1272,12 @@ or the plot's `spines` is set.
 | `minor_grid_style` | 'var(grid_style)' | Minor grid style; default `grid_style`. Length. |
 | `visible` | True | Draw the axis (ticks, labels). |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `text_color` | inherited ('black') | Text color. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
@@ -1039,7 +1291,7 @@ Groups: `TextStyle` (`label_`), `Stroke` (`tick_`), `TextStyle` (`tick_label_`),
 
 ## 5. Series
 
-All series take `name`, `alpha`, `z`, `rasterize` and `simplify` (see [Output](#8-output)).
+All series take `name`, `opacity`, `z`, `rasterize` and `simplify` (see [Output](#8-output)).
 Series without their own color take the plot's next palette color, in call order; series
 with several value sets (histograms, densities, areas, pies) take one per set.
 
@@ -1054,7 +1306,7 @@ with several value sets (histograms, densities, areas, pies) take one per set.
   stem, regression): its x data go along the y axis, its y data along the x axis, and it
   draws the same marks with x and y swapped (curves along y, steps included). Grids
   (heatmap, hist2d, hexbin, contour, 2-D kde) and pies have none: swap their arguments.
-* **New types.** `pl.register_layer(name, factory)` adds `plot.<name>(…)`, which calls
+* **New types.** `pl.registry.layers.add(name, factory)` adds `plot.<name>(…)`, which calls
   `factory(…, plot=plot)`. A factory that is a `pl.Series` subclass implements
   `layers()`, returning its `Call` (layers, legend entries, what the axes, maps and
   palette need; see `plot_io/layers/`); its class name is a style class. The genome types
@@ -1068,10 +1320,21 @@ with several value sets (histograms, densities, areas, pies) take one per set.
   count as one, and so do split violins.
 * **Stacking.** `stack=True` (bars, histograms, densities) puts a series on the previous
   stacked series of its kind in the plot, per category or bin; positive and negative
-  values stack apart; `stack="normalize"` divides each position by its total.
+  values stack apart; `stack="normalize"` divides each position by its total. Stacked
+  densities share one grid (the union of their spans).
+* **Fill and opacity.** `fill` turns a series' fills on (`True`: their own colors, or a
+  color) or off (`False`) on every plot type that fills, and `fill_opacity` is their
+  opacity; `opacity` is the opacity of the whole series (fills, lines and outlines),
+  multiplying `fill_opacity`.
 * **Derived data.** Histograms, densities, ECDFs, violins, 2-D bins, contours and
-  regressions compute their data once (in C, by plot_io's kernels) and keep it until
-  a setting changes; `series.stats` exposes it.
+  regressions compute their data once (in C, by plot_io's kernels) and keep it while
+  the settings they read resolve to the same values (a style change recomputes it);
+  `series.stats` exposes it. On an axis with a scale they are computed in the axis'
+  space: bins are even there, and densities (`hist` and `hist2d` `stat="density"`,
+  `kde`, `violin`, 2-D `kde`) are per axis unit (on a log axis, per log unit), so a
+  histogram and a density of the same data agree. Degenerate data draw nothing (an
+  empty set, all NaN) or, for a density without a bandwidth (one value, all equal), no
+  curve and a warning; a violin of one value is a line at it.
 * **Shifted and rescaled coordinates.** `x_origin`, `x_scale` and `x_extent` (and `y_…`)
   draw a series' values `v` at `(v − origin) × scale`, without changing the data:
   `p.line(profile, x_origin="center")` draws positions 0…1000 at −500…500, `x_scale=10`
@@ -1105,7 +1368,7 @@ p = pl.Plot(data=df); p.scatter("a", "b")       # data inherited by the plot's s
 `data` is any object returning a column for `data[name]`: a dict of sequences, a pandas
 or polars data frame, a numpy structured array. Columns are read through `__getitem__`
 (and `to_numpy()` when present); no table library is imported. With `data`, a string in
-a positional data argument or in `color`, `edge_color`, `size`, `alpha`, `group`,
+a positional data argument or in `color`, `edge_color`, `size`, `opacity`, `group`,
 `draw_order`, `x_error`, `y_error`, `weights`, `positions`, `x`, `y` or `names` names a
 column. Positional arguments, `group`, `weights` and `positions` must be columns; in
 `color`, a color name that is no column stays a color (a column wins, with a warning if
@@ -1115,14 +1378,26 @@ the colorbar label to the `color` column, the legend title to the `group` column
 columns keep their category order for groups and category axes.
 
 Box, violin, strip and swarm also take long data: `values` flat, with the category of each
-value in `x` (`y` when horizontal).
+value in `x` (`y` when horizontal). [Dots](#dots) take one row per cell.
+
+```python
+t = pl.group_summary(values, groups, names=None, threshold=0.0, mean="all")
+p.dots(data=t, x="name", y="group", color="mean", size="fraction", size_limits="0/1")
+```
+
+`group_summary` summarizes an observations × variables matrix (rows: observations; a 2-D
+buffer or a list of rows) per group: columns `group`, `name` (the variable; default its
+index), `mean` and `fraction` (the share of the group's observations above `threshold`).
+`mean="expressed"` averages only the observations above `threshold` (none: a missing
+mean). Groups in order of first appearance (a categorical: its order); missing labels are
+left out.
 
 ### Groups (`group=`)
 
 ```python
 g = p.scatter(x, y, group=labels, marker="auto")   # one series per group
 g = p.line(t, y, group=subject, line_style="auto")
-g["a"].set(color="black"); g.set(alpha=0.6)
+g["a"].set(color="black"); g.set(opacity=0.6)
 ```
 
 `group` takes a label per point. The call returns a `SeriesGroup`, a list of one series per
@@ -1150,7 +1425,7 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 * `size` is a diameter (a length; per-point numbers are px). With `size_basis="area"` (default) every shape has the
   area of the circle of that diameter: a square of size 4 is drawn 3.54 px wide.
 * Error bars: `x_error`/`y_error` take a value, a sequence, `(low, high)` sequences or
-  `ErrorBars(values, color=None, line_width=None, cap_length=None)` (cap: the series'
+  `Errors(values, color=None, line_width=None, cap_length=None)` (cap: the series'
   `cap_length`, else 4 px).
 
 <!-- settings:Scatter -->
@@ -1160,8 +1435,9 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `size` | 4.5 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `edge_width` | 0.75 | Outline width; 0: no outline. Length. |
-| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `edge_width` | 0.5 | Outline width; 0: no outline. Length. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
@@ -1171,11 +1447,11 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `size_limits` | — | Limits of the series' size axis, as an axis' `limits`; unset: `"auto"`. |
 | `size_scale` | — | Scale of the series' size axis; unset: `linear`. |
 | `size_axis` | — | A shared `SizeAxis` (`figure.size_axis(…)`) in place of the series' own: it holds the sizes, limits and scale. |
-| `size_legend` | True | With mapped sizes: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
+| `size_key` | 'key' | With mapped sizes: a key attached to the plot, as a colorbar's (`"key"`), sample rows in the legend (`"legend"`), none (`False`), or the values to show (a list: a key with a marker at each). |
 | `draw_order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `alpha_range`. |
-| `alpha_range` | (0.2, 1.0) | Opacities of the least and most dense points when `alpha` is a density. |
-| `x_error` | — | Horizontal error bars: a value, a sequence, `(low, high)` or `ErrorBars`. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `opacity_range`. |
+| `opacity_range` | (0.2, 1.0) | Opacities of the least and most dense points when `opacity` is a density. |
+| `x_error` | — | Horizontal error bars: a value, a sequence, `(low, high)` or `Errors`. |
 | `y_error` | — | Vertical error bars. |
 | `orientation` | 'vertical' | `vertical` (x along the x axis) or `horizontal` (x along the y axis). |
 | `name` | — | Legend entry; unset: not in the legend. |
@@ -1184,10 +1460,12 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker`, `Font`.
 <!-- /settings -->
@@ -1202,7 +1480,7 @@ Named line styles scale with the width. Markers (`marker`, `marker_size`,
 `marker_color`, …) are drawn at the points when `marker` or `show_markers` is set.
 Numbers per point (or `"density"`, of a single line) in `marker_color` and
 `marker_edge_color` go through the series' [color axis](#6-color-and-size-axes)
-(`color_map`, `color_limits`, `color_scale`, `color_axis`; `p.colorbar(line)`), as
+(`color_map`, `color_limits`, `color_scale`, `color_axis`; `p.add_colorbar(line)`), as
 `color` does on Scatter; the line keeps `color`, and the legend's marker takes the
 gradient's middle color.
 
@@ -1219,7 +1497,7 @@ gradient's middle color.
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Line color; default: the next palette color. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list; named styles scale with the width. Length. |
 | `cap` | 'butt' | Line cap. |
 | `join` | 'round' | Line join. |
@@ -1229,8 +1507,9 @@ gradient's middle color.
 | `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
-| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
@@ -1241,16 +1520,18 @@ gradient's middle color.
 | `show_markers` | False | Draw markers at the points (also turned on by setting `marker`). |
 | `orientation` | 'vertical' | `vertical` (x along the x axis) or `horizontal` (x along the y axis). |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1272,7 +1553,7 @@ each side in its color).
 |---|---|---|
 | `color` | — | Fill color; default: the next palette color. |
 | `color_below` | — | Fill color where `y1` is below `y2` (crossings found on straight segments); default `color` everywhere. |
-| `alpha` | 'calc(0.3 * inherit)' | Opacity; default 0.3 × the plot's. |
+| `opacity` | 'calc(0.3 * inherit)' | Opacity; default 0.3 × the plot's. |
 | `edge_color` | — | Outline color; default none. |
 | `edge_width` | 'var(line_width)' | Outline width; default the line width. Length. |
 | `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
@@ -1284,10 +1565,12 @@ each side in its color).
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
@@ -1315,7 +1598,7 @@ category.
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `edge_color` | 'series' | Box outline, whiskers, caps and median: a color, `"series"` (each box's own color) or `"auto"` (a grey 0.6 × as light as the series' lightest color, as seaborn). |
-| `edge_width` | 0.75 | Outline width. Length. |
+| `edge_width` | 'var(line_width)' | Outline width. Length. |
 | `whisker_color` | — | Whisker and cap color; default `edge_color`. |
 | `whisker_width` | 'var(edge_width)' | Whisker and cap width; default `edge_width`. Length. |
 | `whisker_style` | 'solid' | Whisker line style: `solid`, `dashed`, `dotted`, `dashdot` or a dash list (caps stay solid). Length. |
@@ -1327,7 +1610,8 @@ category.
 | `whiskers` | 1.5 | Whisker reach: a multiple of the IQR, `"range"`, or percentiles `(lo, hi)`. |
 | `outliers` | True | Draw points beyond the whiskers. |
 | `saturation` | 1.0 | Saturation of the box fills (1: the colors as given; seaborn uses 0.75). |
-| `fill` | 0.25 | Box fill: an opacity of the box color, times `alpha` (lines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `fill` | True | Fill: `True` (the box's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (lines keep `opacity`). |
 | `mean` | False | Draw the mean as a marker. |
 | `mean_marker` | 'diamond' | Marker of the mean. |
 | `mean_color` | 'white' | Fill of the mean marker (outline: `edge_color`). |
@@ -1340,19 +1624,22 @@ category.
 | `marker_color` | — | Outlier fill: a color, or colors per outlier. |
 | `marker_edge_color` | — | Outlier outline: as the fill, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
 | `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
-| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `Stroke` (`whisker_`), `Stroke` (`median_`), `FillStyle`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1387,16 +1674,18 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 | `value_label_font_size` | '0.9em' | Font size of cell labels. Length; `%`: of the font size. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1407,13 +1696,80 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 Groups: `TextStyle` (`value_label_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
+### Dots
+
+```python
+pl.Dots(color=None, size=None, x=None, y=None, plot=None, **settings)
+p.dots(mean, size=fraction, x=genes, y=clusters, cmap="magma", size_limits="0/1")
+p.dots(data=table, x="gene", y="cluster", color="mean", size="fraction")
+```
+
+One dot per cell of a grid (a dot plot): `color` and `size` are 2-D grids of values (row
+0 first) of one shape, or one value (a color, a diameter). `x`/`y` label the columns and
+rows, as a heatmap's: labels (category axes), `None` (indices), centres or edges. Values
+always map: colors through the series' [color axis](#6-color-and-size-axes) (a colorbar
+by default), sizes through its size axis (`size_map` `(0, 12)` px and `size_limits`
+`"0/max"`: area ∝ value; fractions: `"0/1"`) and its [size key](#size-keys), on the
+colorbar's line when both fit. A missing size leaves the cell empty; a missing color
+takes the map's `bad`.
+
+* **Long data.** `x`, `y` and `color`/`size` per cell (columns with `data=`, or
+  sequences), one row per cell; two rows for one cell are an error, cells without a row
+  get no dot. Categories in order of first appearance (pandas or polars categoricals:
+  theirs); `x_categories=`/`y_categories=` lists select and order them.
+* **`scale_color`.** `"rows"` / `"columns"` rescales color values to 0–1 in each row or
+  column before mapping (one variable's range per column).
+* **Cells.** The axes' width (`Figure(width=…)`) sets the space per column; rotated
+  labels closer than `category_label_spacing` are thinned out. `data_ratio=1` on the plot
+  makes cells square.
+
+<!-- settings:Dots -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
+| `size` | 4.5 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
+| `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
+| `edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `edge_width` | 0.5 | Outline width; 0: no outline. Length. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `size_map` | (0.0, 12.0) | The sizes numbers in `size` are drawn with: a `SizeMap` (alias `smap`); without it (or `size_axis`), numbers are sizes in px. |
+| `size_limits` | '0/max' | Limits of the series' size axis, as an axis' `limits`; unset: `"auto"`. |
+| `size_scale` | — | Scale of the series' size axis; unset: `linear`. |
+| `size_axis` | — | A shared `SizeAxis` (`figure.size_axis(…)`) in place of the series' own: it holds the sizes, limits and scale. |
+| `size_key` | 'key' | With mapped sizes: a key attached to the plot, as a colorbar's (`"key"`), sample rows in the legend (`"legend"`), none (`False`), or the values to show (a list: a key with a marker at each). |
+| `scale_color` | — | `rows` / `columns`: color values rescaled to 0–1 in each row or column before mapping; unset: as given. |
+| `origin` | 'top' | `top`: row 0 at the top (y axis inverted); `bottom`: at the bottom. |
+| `colorbar` | True | Attach a colorbar to the plot (with color values). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
+
+Groups: `Marker`, `Font`.
+<!-- /settings -->
+
 ### Bar
 
 ```python
 pl.Bar(x, height=None, plot=None, **settings)
 ```
 
-`x`: categories (a category axis) or numbers (bars centred on them, `width` in data units); a dict `{category: height}`; or heights alone (at 0, 1, …). `value_labels` writes the values outside, inside or at the centre of the bars, formatted by `value_label_format`; `fill` is the opacity of the bars' fill (or a color); `error` adds error bars at the bar ends. Value axes include 0 (`include_zero="auto"`).
+`x`: categories (a category axis) or numbers (bars centred on them, `width` in data units); a dict `{category: height}`; or heights alone (at 0, 1, …). `value_labels` writes the values outside, inside or at the centre of the bars, formatted by `value_label_format`; `fill_opacity` is the opacity of the bars' fill (`fill`: a color in place of theirs); `error` adds error bars at the bar ends. Value axes include 0 (`include_zero="auto"`).
 
 <!-- settings:Bar -->
 | Setting | Default | Meaning |
@@ -1423,9 +1779,10 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
-| `edge_color` | 'series' | Outline color: a color, `"series"` (each bar's own color, at `alpha`) or none. |
+| `edge_color` | 'series' | Outline color: a color, `"series"` (each bar's own color, at `opacity`) or none. |
 | `edge_width` | 'var(line_width)' | Outline width. Length. |
-| `fill` | 0.25 | Fill: an opacity of each bar's color, times `alpha` (outlines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `fill` | True | Fill: `True` (each bar's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (outlines keep `opacity`). |
 | `seam_color` | 'white' | Where outlined bars touch (dodged or adjacent), the shared edge in this color; `none`: both outlines as drawn. Between the parts of a stack, the line is the outline of the part nearer the baseline. |
 | `max_width` | — | Largest width of the series' part of a slot (as `width`); default none. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
 | `width` | '80%' | Bar width: `%` of the slot, a length (bare numbers: px), `d` data units, or a duration (or `timedelta`) on time axes. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
@@ -1435,22 +1792,24 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `dodge` | True | Bar series sharing a category share its slot side by side; `False` overlays them. |
 | `gap` | 0.0 | Fraction of each bar's part of a shared slot left empty. Length; `%`: of each series' part of a shared slot. |
 | `saturation` | 1.0 | Saturation of the fills (seaborn: 0.75). |
-| `error` | — | Error bars at the bar ends: a value, a sequence, `(low, high)` or `ErrorBars`. |
+| `error` | — | Error bars at the bar ends: a value, a sequence, `(low, high)` or `Errors`. |
 | `error_color` | '#333333' | Error bar color. |
-| `error_width` | 0.75 | Error bar line width. Length. |
+| `error_width` | 0.5 | Error bar line width. Length. |
 | `value_labels` | False | Value labels: `True`/`"outside"`, `"inside"`, `"center"`. Outside labels widen automatic limits so they fit in the axes; a label too large for its bar goes outside, or is left out on a stacked bar. |
 | `value_label_format` | 'auto' | Number format of the value labels. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1467,7 +1826,7 @@ Groups: `Stroke` (`edge_`), `FillStyle`, `Stroke` (`error_`), `Font`, `NumberFor
 pl.Hist(values, plot=None, **settings)
 ```
 
-`values`: one array, or several (a dict, a list of arrays) sharing the bins. `bins`: a count, edges, or numpy's rules (`auto` is numpy 2's). Bins are even on the axis scale (`bins_scale="axis"`): on a log axis, in log space. `stat` turns counts into densities (area 1), probabilities, percents or counts per unit; `cumulative` accumulates them. Several sets overlay (opacity 0.5), stack (`stack=True`) or dodge (`dodge=True`). `hist.stats`: `edges`, `counts` and `heights` per set.
+`values`: one array, or several (a dict, a list of arrays) sharing the bins; dates draw on a time axis. `bins`: a count (at most 10⁶), edges, or numpy's rules (`auto` is numpy 2's; a rule asking for more than 10⁶ bins is an error). Bins are even on the axis scale (`bins_scale="axis"`): on a log axis, in log space; edges or a `range` outside the axis' scale (0 on a log axis) are refused. `stat` turns counts into densities (area 1), probabilities, percents or counts per unit, per unit of the axis' space; `cumulative` accumulates them. Several sets overlay (`fill="auto"`: opacity 0.5), stack (`stack=True`) or dodge (`dodge=True`). Bars have no outline by default (`edge_width` 0). `hist.stats`: `edges`, `counts` and `heights` per set.
 
 <!-- settings:Hist -->
 | Setting | Default | Meaning |
@@ -1475,33 +1834,37 @@ pl.Hist(values, plot=None, **settings)
 | `bins` | 'auto' | A count, edges, or a rule: `auto`, `fd`, `sturges`, `scott`, `sqrt`, `rice`, `doane` (numpy's). |
 | `range` | — | Range of the bins; default the data range. |
 | `weights` | — | A weight per value (per set for several sets). |
-| `stat` | 'count' | `count`, `density` (area 1), `probability`, `percent` or `frequency` (count per unit). |
+| `stat` | 'count' | `count`, `density` (area 1), `probability`, `percent` or `frequency` (count per unit); densities and frequencies per unit of the axis' space (log axes: per log unit, as `kde`). |
 | `cumulative` | False | Accumulate the bins. |
 | `kind` | 'stepfilled' | `bar` (adjacent bars), `step` (outline) or `stepfilled`. |
 | `bins_scale` | 'axis' | `axis`: bins even on the axis scale (log axes: in log space); `linear`: even in data units. |
 | `orientation` | 'vertical' | `vertical` (bins along x) or `horizontal`. |
 | `stack` | False | Stack the sets (and other stacked histograms with the same bins). |
 | `dodge` | False | Put the sets side by side within each bin. |
-| `color` | — | Fill color, or one per set; default palette colors. |
+| `color` | — | Fill color, one per set (a list, or a dict by set name); default palette colors. |
 | `edge_color` | — | Bar outline color; default none. |
-| `edge_width` | 0.0 | Bar outline width. Length. |
+| `edge_width` | 0.0 | Bar outline width; default 0 (none). Length. |
 | `line_color` | — | Step and outline color; default each set's color. |
-| `line_width` | inherited (0.75) | Step line width. Length. |
+| `line_width` | inherited (0.5) | Step line width. Length. |
 | `outline` | True | `bar` and `stepfilled` kinds: the outer outline of each set, in `line_color` (dodged bars: each bar's outline). |
-| `alpha` | 'auto' | Opacity; `"auto"`: 0.5 for overlaid sets, else the plot's. |
+| `fill` | True | Fill: `True` (each set's color), a color, or `False` (none). |
+| `fill_opacity` | 'auto' | Opacity of the fills, times `opacity` (lines keep `opacity`); `"auto"`: 0.5 for overlaid sets, else 1. |
 | `saturation` | 1.0 | Saturation of the fills. |
 | `value_labels` | False | Value labels on bars. |
 | `value_label_format` | 'auto' | Number format of the value labels. |
 | `name` | — | Legend entry; unset: not in the legend. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1518,7 +1881,7 @@ Groups: `Stroke` (`edge_`), `Stroke` (`line_`), `Font`, `NumberFormat`.
 pl.Kde(values, plot=None, **settings)
 ```
 
-A Gaussian kernel density of each set on a common grid of `points` points, extending `cut` bandwidths past the data (within `range`). `fill` fills under each curve (`True`: at 0.25, an opacity, or a color). `bandwidth`: `scott` (default), `silverman` (as scipy's `gaussian_kde`) or a number, times `adjust`. On log axes the density is computed in log space, per log unit. `kde.stats`: `grid`, `densities`, `bandwidths`.
+A Gaussian kernel density of each set on a common grid of `points` points, extending `cut` bandwidths past the data (within `range`); dates draw on a time axis. `fill` fills under each curve (`True`, or a color; at `fill_opacity`, 0.25). `bandwidth`: `scott` (default), `silverman` (as scipy's `gaussian_kde`) or a number, times `adjust`. On log axes the density is computed in log space, per log unit. A set without a bandwidth (no values, one, all equal) or a `range` outside the data has no curve (NaN densities), with a warning. `kde.stats`: `grid`, `densities`, `bandwidths`.
 
 <!-- settings:Kde -->
 | Setting | Default | Meaning |
@@ -1529,24 +1892,27 @@ A Gaussian kernel density of each set on a common grid of `points` points, exten
 | `range` | — | Limits of the curve (within the data plus `cut`); default none. |
 | `points` | 512 | Number of points of the curve. |
 | `cumulative` | False | Plot the cumulative distribution. |
-| `fill` | False | Fill under the curve: an opacity of its color, `True` (0.25), a color, or `False` (stacked curves: 0.25). |
+| `fill` | False | Fill under the curve: `True` (its color), a color, or `False` (stacked curves are filled anyway). |
+| `fill_opacity` | 0.25 | Opacity of the fill (0–1). |
 | `weights` | — | A weight per value (per set for several sets). |
 | `orientation` | 'vertical' | `vertical` (values along x) or `horizontal`. |
 | `stack` | False | Stack the sets (seaborn's `multiple="stack"`). |
-| `color` | — | Color, or one per set; default palette colors. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `color` | — | Color, one per set (a list, or a dict by set name); default palette colors. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | Line style. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `FillStyle`, `Stroke`, `Font`.
 <!-- /settings -->
@@ -1561,8 +1927,9 @@ Density contours of points (seaborn's `kdeplot(x=, y=)`): the 2-D Gaussian densi
 (bandwidth as [`Density`](#point-density): scipy's covariance times Scott's factor, or
 Silverman's, a number or a matrix, times `adjust`) on a `points` × `points` grid over
 the data plus `cut` bandwidths, in axis positions (log axes in log space). With a number
-of `levels`, contour k of n encloses an equal share of the mass, from 1 − `thresh` (the
-outermost) up; a list gives density values. Unfilled lines take the next palette color,
+n of `levels`, level k (0 … n − 1) encloses 1 − p of the mass, p = `thresh` + (1 −
+`thresh`)·k/(n − 1): the outermost 1 − `thresh`, the last at the density's maximum; a
+list gives density values. Unfilled lines take the next palette color,
 or `palette` (one color or colors per level), unless `color_map` is set; `fill=True`
 colors the bands through
 `color_map`, with the top band up to the maximum. Drawn by the contour code (lines,
@@ -1571,7 +1938,7 @@ labels, colorbar).
 <!-- settings:Kde2d -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `levels` | 10 | A number of iso-proportion levels (contour k of n encloses k/n of the mass, above `thresh`), or density values. |
+| `levels` | 10 | A number n of iso-proportion levels: level k (0 … n − 1) encloses 1 − p of the mass, p = `thresh` + (1 − `thresh`)·k/(n − 1) (the outermost 1 − `thresh`, the last at the density's maximum); or density values. |
 | `thresh` | 0.05 | Lowest iso-proportion: the outermost contour encloses 1 − `thresh` of the mass. |
 | `bandwidth` | 'scott' | `"scott"`, `"silverman"`, a number or a 2 × 2 matrix, as `Density`. |
 | `adjust` | 1.0 | Factor of the bandwidth. |
@@ -1586,7 +1953,7 @@ labels, colorbar).
 pl.Ecdf(values, plot=None, **settings)
 ```
 
-A step line through the sorted values of each set: `stat` `proportion`, `count` or `percent`; `complementary` plots 1 − F.
+A step line through the sorted values of each set: `stat` `proportion`, `count` or `percent`; `complementary` plots 1 − F. `color`: one, a list (one per set) or a dict by set name.
 
 <!-- settings:Ecdf -->
 | Setting | Default | Meaning |
@@ -1595,20 +1962,22 @@ A step line through the sorted values of each set: `stat` `proportion`, `count`
 | `stat` | 'proportion' | `proportion` (0–1), `count` or `percent`. |
 | `complementary` | False | Plot 1 − F (survival). |
 | `orientation` | 'vertical' | `vertical`: values along x; `horizontal`: along y. |
-| `color` | — | Line color, or one per set; default palette colors. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `color` | — | Line color, one per set (a list, or a dict by set name); default palette colors. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'solid' | Line style. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke`, `Font`.
 <!-- /settings -->
@@ -1619,7 +1988,7 @@ Groups: `Stroke`, `Font`.
 pl.Violin(values, positions=None, plot=None, **settings)
 ```
 
-`values` as box plots take them. Each violin is the density of its category, mirrored; `width_scale` gives equal areas (default), areas proportional to the counts, or equal widths. `inner` draws a thin box with whiskers and a median dot, dashed quartiles, the points, or nothing (`False`). With `split=True`, two violin series share each slot as facing halves.
+`values` as box plots take them. Each violin is the density of its category, mirrored, in the value axis' space (log axes: in log space); `width_scale` gives equal areas (default), areas proportional to the counts, or equal widths. A category of one value (or all equal) is a line at it, with a warning. `inner` draws a thin box with whiskers and a median dot, dashed quartiles, the points, or nothing (`False`). With `split=True`, two violin series share each slot as facing halves.
 
 <!-- settings:Violin -->
 | Setting | Default | Meaning |
@@ -1629,11 +1998,11 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
-| `edge_color` | 'series' | Outline and inner color: a color or `"series"` (each violin's own color, at `alpha`). |
-| `edge_width` | 0.75 | Outline width. Length. |
+| `edge_color` | 'series' | Outline and inner color: a color or `"series"` (each violin's own color, at `opacity`). |
+| `edge_width` | 'var(line_width)' | Outline width. Length. |
 | `saturation` | 1.0 | Saturation of the fills. |
-| `alpha` | 1.0 | Opacity of the violins. |
-| `fill` | 0.25 | Fill: an opacity of each violin's color, times `alpha` (outlines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `fill` | True | Fill: `True` (each violin's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (outlines keep `opacity`). |
 | `max_width` | — | Largest width of the series' part of a slot (as `width`); default none. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
 | `width` | '80%' | Violin width: `%` of the slot, a length (bare numbers: px), `d` data units, or a duration on time axes. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
 | `bandwidth` | 'scott' | `scott`, `silverman` or a number. |
@@ -1648,15 +2017,18 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | `gap` | '10%' | Fraction of each part of a shared slot left empty. Length; `%`: of each series' part of a shared slot. |
 | `categories` | — | Category names of a list of arrays. |
 | `name` | — | Legend entry; unset: not in the legend. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `FillStyle`, `Font`.
 <!-- /settings -->
@@ -1677,8 +2049,9 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `size` | 4.5 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `edge_width` | 0.75 | Outline width; 0: no outline. Length. |
-| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `edge_width` | 0.5 | Outline width; 0: no outline. Length. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
@@ -1688,7 +2061,7 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `size_limits` | — | Limits of the series' size axis, as an axis' `limits`; unset: `"auto"`. |
 | `size_scale` | — | Scale of the series' size axis; unset: `linear`. |
 | `size_axis` | — | A shared `SizeAxis` (`figure.size_axis(…)`) in place of the series' own: it holds the sizes, limits and scale. |
-| `size_legend` | True | With mapped sizes: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
+| `size_key` | 'key' | With mapped sizes: a key attached to the plot, as a colorbar's (`"key"`), sample rows in the legend (`"legend"`), none (`False`), or the values to show (a list: a key with a marker at each). |
 | `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
 | `max_width` | — | Largest width of the series' part of a slot (as `width`); default none. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
 | `width` | '80%' | Width the points spread over: `%` of the slot, a length (bare numbers: px), `d` data units, or a duration on time axes. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
@@ -1698,18 +2071,20 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `jitter` | '10%' | Half-width of the jitter (`%` of the slot width). Length; `%`: of the slot: one category, or the smallest gap between positions. |
 | `seed` | 0 | Seed of the jitter. |
 | `draw_order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `alpha_range`. |
-| `alpha_range` | (0.2, 1.0) | Opacities of the least and most dense points when `alpha` is a density. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `opacity_range`. |
+| `opacity_range` | (0.2, 1.0) | Opacities of the least and most dense points when `opacity` is a density. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker`, `Font`.
 <!-- /settings -->
@@ -1720,32 +2095,36 @@ Groups: `Marker`, `Font`.
 pl.Area(x, ys, plot=None, **settings)
 ```
 
-Layers (rows of `ys`, or a dict `{name: values}`, one legend entry each) stacked on `baseline`: `zero`, `sym`, `wiggle` or `weighted_wiggle` (matplotlib's stackplot baselines). `interpolation` and `missing` as `Fill`.
+Layers (rows of `ys`, a dict `{name: values}`, one legend entry each, or one flat sequence) stacked on `baseline`: `zero`, `sym`, `wiggle` or `weighted_wiggle` (matplotlib's stackplot baselines). `fill_opacity` is the fills' opacity, `opacity` the whole series'. `interpolation` and `missing` as `Fill`.
 
 <!-- settings:Area -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `baseline` | 'zero' | `zero`, `sym` (symmetric around 0), `wiggle` or `weighted_wiggle` (streamgraphs, as matplotlib's stackplot). |
 | `stack` | True | Stack the layers; `False` overlays them from 0. |
-| `color` | — | A color, or one per layer; default palette colors. |
-| `alpha` | 0.25 | Opacity of the fills. |
+| `color` | — | A color, one per layer (a list, or a dict by layer name); default palette colors. |
+| `fill` | True | Fill: `True` (each layer's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (outlines keep `opacity`). |
 | `edge_color` | 'series' | Outline color of each layer's top: a color, `"series"` (each layer's own color) or none. |
 | `edge_width` | 'var(line_width)' | Outline width; default the line width. Length. |
 | `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
 | `missing` | 'break' | Missing values: `break` the line there, or `skip` them and connect their neighbours. |
 | `orientation` | 'vertical' | `vertical` (layers along x) or `horizontal` (along y). |
 | `name` | — | Legend entry; unset: not in the legend. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
-Groups: `Stroke` (`edge_`), `Font`.
+Groups: `FillStyle`, `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
 
 ### Errorbar
@@ -1763,32 +2142,35 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
-| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `color` | — | Bar color; default: the next palette color. |
-| `line_width` | inherited (0.75) | Bar width. Length. |
+| `line_width` | inherited (0.5) | Bar width. Length. |
 | `cap_length` | 4.0 | Cap width (`data`: in data units across the bar); 0: no caps. Length; `d`: data units. |
 | `x_error` | — | Horizontal errors. |
 | `y_error` | — | Vertical errors. |
 | `y_error_style` | 'bars' | `bars`, or `band`: a filled band between the y error ends (points sorted by x). |
-| `band_alpha` | 0.25 | Opacity of a band. |
+| `band_opacity` | 0.25 | Opacity of a band. |
 | `orientation` | 'vertical' | `vertical` (x along the x axis) or `horizontal` (x along the y axis). |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1809,29 +2191,32 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `marker_edge_color` | — | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
 | `marker_edge_width` | 0.0 | Outline width; 0: no outline. Length. |
-| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `color` | — | Stem and marker color; default: the next palette color. |
-| `line_width` | inherited (0.75) | Stem width. Length. |
+| `line_width` | inherited (0.5) | Stem width. Length. |
 | `baseline` | 0.0 | Value the stems start from. |
 | `baseline_color` | '#4d4d4d' | Baseline color; `none`: no baseline. |
-| `baseline_width` | 0.75 | Baseline width. Length. |
+| `baseline_width` | 0.5 | Baseline width. Length. |
 | `orientation` | 'vertical' | `vertical` stems (values on y) or `horizontal`. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Marker` (`marker_`), `Stroke` (`baseline_`), `Font`.
 <!-- /settings -->
@@ -1842,7 +2227,7 @@ Groups: `Marker` (`marker_`), `Stroke` (`baseline_`), `Font`.
 pl.Regression(x, y, plot=None, **settings)
 ```
 
-A least-squares polynomial of `order` with the confidence band of the mean (Student's t), or a LOWESS curve (`lowess=True`, no band); `logx` fits against log x; `range` sets the x range of the polynomial curve (default the data's), drawn in `points` points. The points are drawn too unless `scatter=False` (marker settings with the `marker_` prefix; numbers in `marker_color` map through the series' color axis, as on [Line](#line)). `regression.stats`: `coefficients` (lowest power first), `r2`, `se`, and the curve.
+A least-squares polynomial of `order` with the confidence band of the mean (Student's t), or a LOWESS curve (`lowess=True`, no band); `logx` fits against log x; `range` sets the x range of the polynomial curve (default the data's), drawn in `points` points. With fewer distinct x values than `order` + 1, the order is lowered (one distinct x: no fit), with a warning. The points are drawn too unless `scatter=False` (marker settings with the `marker_` prefix; numbers in `marker_color` map through the series' color axis, as on [Line](#line)). `regression.stats`: `coefficients` (lowest power first), `r2`, `se`, and the curve.
 
 <!-- settings:Regression -->
 | Setting | Default | Meaning |
@@ -1858,13 +2243,14 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `color` | — | Line, band and point color; default the next palette color. |
 | `line_width` | 'calc(1.4 * inherit)' | Line width; default 1.4 × the plot's. Length. |
 | `line_style` | 'solid' | Line style or dash list. Length. |
-| `band_alpha` | 0.2 | Opacity of the band. |
+| `band_opacity` | 0.2 | Opacity of the band. |
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
 | `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
 | `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
-| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
-| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
@@ -1872,16 +2258,18 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `orientation` | 'vertical' | `vertical` (y on x) or `horizontal` (the fit drawn with x along the y axis). |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
@@ -1892,7 +2280,7 @@ Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 pl.Hist2d(x, y, plot=None, **settings)
 ```
 
-Counts in rectangular bins (even on the axis scales), drawn as a heatmap with the heatmap's settings; bins below `min_count` are transparent; a colorbar source.
+Counts in rectangular bins (even on the axis scales), drawn as a heatmap with the heatmap's settings; bins below `min_count` are transparent; `stat="density"` per unit area of the axes' space; a colorbar source.
 
 <!-- settings:Hist2d -->
 | Setting | Default | Meaning |
@@ -1932,16 +2320,18 @@ the axes are not counted. Colored by `cmap`; a colorbar source.
 | `edge_width` | 0.0 | Outline width. Length. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
@@ -1958,7 +2348,8 @@ Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `level
 | Setting | Default | Meaning |
 |---|---|---|
 | `levels` | 10 | A number of levels (nice values over the data) or the level values. |
-| `fill` | False | Fill the bands between levels: `True`, an opacity (0–1, times `alpha`), or `False`. |
+| `fill` | False | Fill the bands between levels: `True` or `False`. |
+| `fill_opacity` | 1.0 | Opacity of the bands, times `opacity`. |
 | `lines` | True | Draw the iso-lines. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
 | `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
@@ -1968,7 +2359,7 @@ Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `level
 | `line_width` | 'calc(0.6 * inherit)' | Line width; default 0.6 × the plot's. Length. |
 | `line_style` | 'solid' | Line style. Length. |
 | `negative_style` | — | Line style of negative levels drawn with a single color (matplotlib: dashed). |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 | `value_labels` | False | Write the level values on the lines. |
 | `value_label_format` | 'auto' | Number format of the value labels. |
 | `value_label_font_size` | '0.8em' | Label font size. Length; `%`: of the font size. |
@@ -1979,10 +2370,12 @@ Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `level
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -2017,8 +2410,9 @@ Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a pl
 | `value_label_format` | 'auto' | Number format of the value labels (percentages: of 100). |
 | `edge_color` | 'series' | Wedge outline color: a color, `"series"` (each wedge's own color) or `none`. |
 | `edge_width` | 1.25 | Wedge outline width. Length. |
-| `alpha` | 1.0 | Opacity. |
-| `fill` | 0.25 | Wedge fill: an opacity of each wedge's color, times `alpha` (outlines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `opacity` | 1.0 | Opacity. |
+| `fill` | True | Wedge fill: `True` (each wedge's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fills, times `opacity` (outlines keep `opacity`). |
 | `seam_color` | 'white' | The edges neighbouring wedges share, in this color; `none`: both outlines as drawn. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
@@ -2026,10 +2420,12 @@ Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a pl
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -2054,7 +2450,7 @@ h.color_axis                                        # the series' own color axis
 ca = fig.color_axis(color_map="magma", limits="0/max")   # a shared one
 p.heatmap(v, color_axis=ca)
 q.scatter(x, y, c=z, color_axis=ca)
-fig.colorbar(ca, id=5, label="energy")
+fig.colorbar_area(ca, id=5, label="energy")
 fig = pl.Figure(cols=3, share_color="row")          # each row's plots: one color axis
 fig = pl.Figure(cols=3, share_size="all")           # one size axis, one size key
 ```
@@ -2080,12 +2476,16 @@ fig = pl.Figure(cols=3, share_size="all")           # one size axis, one size ke
   color this way (`"all"` by default).
 * **`share_size`** does the same for the own size axes: limits over all the group's
   values, one `size_limits` (or `size_scale`) for the group, and one size key for the
-  group ([legend](#legend)). Each series keeps its `size_map`. Facet figures share size
-  too (`"all"`).
+  group, beside its plots as a shared colorbar ([size keys](#size-keys); in the
+  [legend](#legend) with `size_key="legend"`, where a figure legend covering every plot
+  of a key takes it). Each series keeps its `size_map`. Facet figures share size too
+  (`"all"`).
 * **Training.** Before the layout, each axis is resolved from the values it maps, by the
   code of x and y axes: the scale's domain, `limits` and quantiles, `include_zero`, no
   padding (unless `padding` is set). Values past the limits take the gradient's
-  `under`/`over` colors and missing values its `bad` color (sizes: the `SizeMap`'s).
+  `under`/`over` colors and missing values its `bad` color (sizes: the `SizeMap`'s);
+  colors outside the scale's domain (0 on a log scale) take the `bad` color too, with a
+  warning naming their count.
 
 Color and size axes have the settings of [axes](#4-axes); these differ:
 
@@ -2106,37 +2506,140 @@ Color and size axes have the settings of [axes](#4-axes); these differ:
 ### Colorbars
 
 ```python
-p.colorbar(source=None, **settings)          # attached to a side of the plot
-fig.colorbar(source, id=None, **settings)    # in its own grid area
-cb.axis                                      # the color axis shown
+p.add_colorbar(source=None, side="bottom", **settings)       # attached to a side of the plot
+fig.plot(colorbar=True)                                  # the same, when the plot is made
+fig.add_colorbar(source=None, plots=None, side="bottom", **settings)   # beside plots
+fig.colorbar_area(source, id=None, **settings)           # in its own grid area
+fig.colorbars                                            # those of add_colorbar
+cb.axis                                                  # the color axis shown
 ```
 
-`source` is a mapped series (its color axis; default: the plot's last mapped series) or
-a color axis. The bar draws the axis' gradient between its trained limits, with the
-axis' ticks, number format and fonts, and a label: `label`, else the axis' `label`, else
-the name of the color column or density. Attached bars take margin on their side, so axes
-stay aligned. A bar in its own area runs along the neighbouring axes (`align="axes"`) or
-boxes (`"borders"`). Axis settings given to a bar go to its axis:
-`p.colorbar(h, label="z", tick_format="{:.0%}")` sets `h.color_axis`'s tick format.
+`source` is a mapped series (its color axis; default: the plot's last mapped series, or
+that of the first covered plot with one) or a color axis. A colorbar draws the axis'
+gradient between its trained limits, with a label: `label`, else the axis' `label`, else
+the name of the color column or density.
+
+* **Key** (`style="key"`, the default): one line of the low limit, a short bar with round
+  ends filled with the gradient (`thickness` 4 px, `length` 40 px), the high limit, then
+  the label; `value_gap` (0.6em) between a limit and the bar, `label_gap` (1.2em) before
+  the label. The texts are centered on the bar's middle line, in the axis' tick label font
+  (the label in its label font); `em` is the axis' tick label font size. When the limits
+  clip the data (`extend`), a dot as wide as the bar, in the gradient's under or over
+  color, sits half the thickness past that end (`extend_shape`: `dot`, `block`,
+  `triangle`). `frame` outlines the bar and the dots, following their shapes.
+* **Values.** `values="limits"`: the axis' limits in its `tick_format` (`"auto"`: rounded
+  to two digits of their range); `"ticks"`: the axis' ticks along the bar instead, under
+  it (right of a vertical one); `"signs"`: a bold − (always U+2212, whatever `minus`) and
+  a bold +; or a pair of texts with markup, `("Low", "High")`, `None` keeping that end's
+  number: `(None, "max")`.
+* **Vertical** (on the left and right): the high limit above the bar, the low limit below
+  it, the label above everything, horizontal, all centered on the bar.
+  `label_position`: `end` (after the high end; above a vertical key), `start` (before
+  the low end; below a vertical key), `top` (above the key), `side` (under a horizontal
+  key; beside a vertical one, reading upward).
+* **Bar** (`style="bar"`): a long bar (`length` `100%`, `thickness` 13 px) with the axis'
+  ticks, tick labels and label beside it, for many ticks (log scales, diverging maps).
+  `values`, the gaps and `label_position` are a key's.
+* **Attached.** A band of the plot's box on its `side` (default `bottom`;
+  `orientation="auto"`: horizontal on top and bottom, vertical on the left and right),
+  placed along the side by `align` (default `center`; `start` is the left or top end, as
+  for figure legends). On one side, from the axes outward: an outside legend, the
+  colorbars (by `order`, else in creation order), the titles. A key longer than its axes
+  side passes its ends, and the margins there grow.
+* **Lanes.** `fig.add_colorbar` puts a colorbar beside a set of plots (plots or their
+  series; default every plot) in the lanes of [figure titles](#figure-title) and
+  [legends](#figure-legends), with their rules (the plots' grid rectangle, nesting, shared
+  lanes for disjoint spans, creation order, `order`); over the same plots, a legend is
+  nearer the plots, then a colorbar, then a title. `align` (default `center`) places it
+  within the axes of its plots. A `%` `length` is of that span, and a key then fills
+  that part of it (`length="100%"`: the bar takes what the texts leave of the span). The
+  covered plots' attached colorbars of the same axis are left out.
+* **Shared color axes.** When plots sharing a color axis have attached colorbars of it,
+  one colorbar in the lanes replaces them: per group of `share_color`, on the right of a
+  row or of the figure, at the bottom of a column; then per axis that the attached
+  colorbars of two plots or more show (`fig.color_axis()`), at the bottom of a column,
+  else on the right. It takes the settings of the first one but its place. An attached
+  colorbar whose `side` is set stays, as do those of plots that are not a grid
+  rectangle.
+* **Own area.** `fig.colorbar_area(source, id=…)` is vertical in its grid area (`orientation`):
+  a key placed along it by `align`, a bar running along the neighbouring axes
+  (`align="axes"`) or boxes (`"borders"`).
+* `p.save()` (one plot alone) leaves out figure colorbars: the plot's attached colorbars
+  show again.
+
+Axis settings given to a colorbar go to its axis:
+`p.add_colorbar(h, label="z", tick_format="{:.0%}")` sets `h.color_axis`'s tick format.
 
 <!-- settings:Colorbar -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `position` | 'right' | Side of the plot an attached bar takes. |
-| `orientation` | 'auto' | Bar direction; `"auto"`: vertical, or horizontal for bars attached at the top or bottom. |
-| `thickness` | 13.0 | Bar thickness (`%` of the attached axes side across it). Length; `%`: of the axes side across the colorbar. |
-| `length` | '100%' | Bar length as a fraction of the axes side (attached bars). Length; `%`: of the axes side along the colorbar. |
-| `pad` | 11.0 | Gap between the axes and an attached bar. Length; `%`: of the axes side across the colorbar. |
-| `label` | — | Bar label: a string or rich content; default: the axis' `label`, else the name of the color column or density. |
+| `side` | 'bottom' | Side of the plot (or of the plots) it sits on. |
+| `align` | 'center' | Place along its side: `start` (left, or top), `center`, `end` (right, or bottom), or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right. |
+| `order` | — | Place among the colorbars of its side: lower is nearer the axes; unset: creation order. |
+| `style` | 'key' | `key`: one line of the limits around a short bar with round ends, then the label; `bar`: a long bar with the axis' ticks. |
+| `orientation` | 'auto' | Direction; `"auto"`: horizontal on top and bottom, vertical on the left and right and in an area of its own. |
+| `thickness` | 'auto' | Bar thickness; `"auto"`: 4 px on a key, 13 px on a bar. Length; `%`: of the span along a key, the axes side across a bar. |
+| `length` | 'auto' | Bar length; `"auto"`: 40 px on a key, `100%` on a bar. A key given in `%` fills that part of the span with its texts and bar. Length; `%`: of the span along the colorbar (the axes side of an attached one). |
+| `values` | 'limits' | A key's end texts: `limits` (the axis' limits in its `tick_format`), `ticks` (the axis' ticks along the bar, lengthened to show at least two), `signs` (a bold − and +) or a pair of texts (`None`: that end's number). |
+| `value_gap` | '0.6em' | Gap between a key's end texts and its bar (and above or below a label on top or under it). Length; `%`: of the font size. |
+| `label_gap` | '1.2em' | Gap between a key's texts and its label, along the key. Length; `%`: of the font size. |
+| `label_position` | 'end' | A key's label: after the high end (`end`; above a vertical key), before the low end (`start`; below a vertical key), beside the bar (`side`: under a horizontal key, rotated right of a vertical one) or above the key (`top`). |
+| `pad` | 'auto' | Gap between the axes and an attached colorbar; `"auto"`: 0.8em on a key, 11 px on a bar. Length; `%`: of the axes side across the colorbar. |
+| `label` | — | Label: a string or rich content; default: the axis' `label`, else the name of the color column or density. |
 | `extend` | 'auto' | Ends in the under/over colors: `auto` shows them when the limits clip the data. |
-| `extend_shape` | 'block' | `block`: a separate block at the end of the bar, within its length; `triangle`: a triangle past the bar's end. |
-| `frame` | False | Outline the bar. |
+| `extend_shape` | 'auto' | `dot`: a dot past the key's end; `block`: a separate block at the end (within a bar's length); `triangle`: a triangle past the end; `"auto"`: `dot` on a key, `block` on a bar. |
+| `frame` | False | Outline the bar (and its ends), following its shape. |
+| `count` | 3 | A size key's markers below its high limit (`values="limits"`). |
+| `marker_gap` | '0.4em' | Gap between a size key's markers (edge to edge). Length; `%`: of the font size. |
 | `frame_color` | '#666666' | Outline color. |
 | `frame_width` | 0.5 | Outline width. Length. |
 
 Groups: `Stroke` (`frame_`).
 <!-- /settings -->
 
+Figure colorbars (`fig.add_colorbar`) have the settings of colorbars, and:
+
+<!-- settings:FigureColorbar -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `order` | — | Place in its side's lanes, as figure titles' `order`: lower is nearer the plots. |
+| `pad` | 'auto' | Gap between the colorbar and the plots; `"auto"`: 0.8em on a key, 11 px on a bar. Length. |
+<!-- /settings -->
+
+### Size keys
+
+```python
+p.scatter(x, y, size=w, size_map=(0, 12))           # a size key under the plot
+p.add_colorbar(s.size_axis, side="right", count=3)      # a size key placed by hand
+s.set(size_key=[10, 50, 100])                       # a marker at each value, labelled
+```
+
+A colorbar of a size axis is a size key: a key whose bar is sample markers of increasing
+size, `0%  ·  •  ●  100%  Expressing`. Every series mapping sizes has one by default
+(`size_key="key"`), attached to its plot under the axes, after the plot's colorbars; a
+colorbar of the plot showing the same size axis, or a `fig.size_legend` area, replaces
+it.
+
+* **Markers.** `count` (3) markers at values evenly spaced below the high limit (in the
+  scale's terms), the high limit's own marker left out; when the low limit's size is
+  zero, the first marker is the next value (at 0–1: ¼, ½, ¾).
+  `marker_gap` (0.4em) between their edges; the line is as tall as the largest. The
+  series' marker shape, in grey, or the series' color when one series of one color uses
+  the axis. Vertical (on the left and right): largest at the top.
+* **Values.** The limits at the ends in the axis' `tick_format` (`"percent"` for
+  fractions); `values="ticks"`, or a series' `size_key` list: a marker at each value
+  (the axis' ticks, else 3–5 nice numbers), its value under it (right of a vertical
+  key).
+* **Label**: `label`, else the axis' `label`, else the `size` column name.
+* **One line.** On top or bottom, a horizontal key joins the line of the keys before it
+  on that side when the line still fits the axes width, `2 × label_gap` apart, middle
+  lines aligned: a dot plot's color and size keys side by side.
+* **Shared.** As colorbars: plots sharing a size axis (`share_size`, or one
+  `fig.size_axis()` in two plots or more) get one key beside them, in the lanes.
+* The other settings are a key's (`side`, `align`, `order`, `pad`, `value_gap`,
+  `label_gap`, `label_position`); `style`, `thickness`, `length` and `extend` do not
+  apply.
+
 ## 7. Colors, maps and markers
 
 ### Colors and palette
@@ -2152,8 +2655,8 @@ that take a palette color.
 
 ```python
 pl.Palette(colors="tab10_custom", name=None)    # a name, colors, a Palette or n -> colors
-pl.register_palette(name, palette)           # a Palette, colors or a function
-pl.palette_names()
+pl.registry.palettes.add(name, palette)     # a Palette, colors or a function
+pl.registry.palettes.names()   pl.registry.palettes.get(name)   # a Palette
 ```
 
 | `Palette` | |
@@ -2190,8 +2693,8 @@ parts: `palette=pl.ColorMap("viridis").to_palette(5)` for ordered categories.
 ```python
 pl.ColorMap(colors="rainbow_llhh", positions=None, under=None, over=None, bad=None,
             space=None, name=None, interpolation=None, widen_colors=1, widen_sides=1.0)
-pl.register_color_map(name, color_map)
-pl.color_map_names()
+pl.registry.color_maps.add(name, color_map)
+pl.registry.color_maps.names()   pl.registry.color_maps.get(name)   # a ColorMap ("_r": reversed)
 ```
 
 | Member | |
@@ -2294,8 +2797,8 @@ on the axis positions (log axes in log space); NaN points get NaN. `normalize`:
 under automatic limits. `method`: `"exact"` (the sum over all points, multithreaded in
 C, equal to scipy's), `"grid"` (binned, blurred and read back, about 1e-4 relative) or
 `"auto"` (exact up to 20,000 points). A `Density` (or `"density"`) is accepted by
-`color`, `edge_color`, `size` (through the size axis, default `SizeMap()`), `alpha` (mapped
-linearly to `alpha_range`, default (0.2, 1)) and `draw_order`, and by `marker_color` and
+`color`, `edge_color`, `size` (through the size axis, default `SizeMap()`), `opacity`
+(mapped linearly to `opacity_range`, default (0.2, 1)) and `draw_order`, and by `marker_color` and
 `marker_edge_color` of Line (one line), Errorbar, Stem and Regression; one object computes each
 series' own density, cached until a setting changes, and exposed as
 `series.stats["density"]`. The colorbar label defaults to `"density"`.
@@ -2352,35 +2855,59 @@ Inherited settings (figure → plot → axis; series → its color axis):
 | `plus` | 0.51 |
 | `cross` | 0.5754 |
 
-Aliases: `triangle`, `o`, `s`, `d`, `^`, `v`, `<`, `>`, `+`, `x`. A `vec_io.Path` or SVG
-path data in a unit box centred on the origin also works. `pl.register_marker(name, path)`
-adds a shape (its area measured from the outline); `plot_io.markers.marker_path(name)` returns a path
-for vec_io's `draw_markers`; `plot_io.markers.marker_area(name)` its area.
+Shorthands: `triangle`, `o`, `s`, `d`, `^`, `v`, `<`, `>`, `+`, `x`
+([shorthands](#shorthands)). A `vec_io.Path` or SVG path data in a unit box centred on the
+origin also works. `pl.registry.markers.add(name, path)` adds a shape (its area measured
+from the outline), `pl.registry.markers.get(name)` returns its path; `plot_io.markers.resolve(name)` returns
+its unit path for vec_io's `draw_markers` and its area; `plot_io.markers.marker_area(name)`
+the area.
 
 ## 8. Output
 
 ```python
-fig.save(path, **options)          # .pdf, .png, .jpg/.jpeg, .jxl, .avif
-fig.to_bytes(format="pdf", **options)
+fig.save(file, *, region=None, format=None, **options)   # .pdf, .eps, .svg, .png, .jpg/.jpeg, .jxl, .avif
+fig.write(kind, *, region=None, **options)                # bytes: "pdf", "eps", "svg", "png", …
 fig.draw(canvas, x=0, y=0)         # on any vec_io canvas (its document's fonts); returns (width, height) in px
 fig.size()                         # (width, height) in px
-p.save(path, …)   p.to_bytes(…)   p.draw(canvas, …)   # one plot alone, at its size in the figure
+p.save(file, …)   p.write(kind, …)   p.draw(canvas, …)   # one plot alone, at its size in the figure
 ```
 
-The figure is drawn once on a page of a vec_io document in px; each output is made from
-it with its own options:
+`save` writes to a path or a binary file object, in `format` (`"pdf"`, `"eps"`, `"svg"`,
+`"png"`, `"jpeg"`/`"jpg"`, `"jxl"`, `"avif"`) or by the path's extension; a path without
+one of these extensions and no `format` raises `ValueError`, as does a file object without
+`format`. `region` draws a genome region instead of the x axes' (figures and plots).
+
+The figure is drawn once on a page of a vec_io document in px; each output is that
+document written by `vec_io.Document.write` with its options (option objects of
+`vec_io.options`, or dicts of their fields). plot_io reads `quality`, `dpi`,
+`default_dpi`, `background`, `simplify` and `fonts` (below) and passes the others; an option
+of another format (`font_hinting` for PNG) or an unknown one raises vec_io's `OptionError`
+(a `ValueError`). vec_io's `view` and `pages` are refused: a figure's size is its own
+(`width`, `height`, `margin`).
 
 | Options | Of |
 |---|---|
 | `title`, `author`, `subject`, `keywords`, `creator`, `creation_date`, `pdf_a`, `color_mode`, `ink_limit`, `icc_profile`, `base_dir` | the document (vec_io `Document`) |
-| `font_dirs`, `system_fonts` | the fonts text is shaped and embedded with ([fonts](#1-conventions)) |
-| `quality` | the figure's `quality` when not given: 1–100, `"lossless"` (not JPEG) or `"auto"`, the default: PNG 90, a palette of at most 256 colors; JPEG 90; JPEG XL, AVIF and rasterized content in a PDF lossless |
-| `compression` | `"fast"`, `"balanced"` (default), `"best"`: the encoder's effort (PDF streams and images, PNG, JPEG, JPEG XL, AVIF) |
-| `simplify` | the output's `simplify` for content without its own (series have theirs, below) |
-| `compress`, `font_hinting` | PDF: compressed streams (default) or a readable file; TrueType hinting kept in embedded subsets (default: left out) |
-| `dpi`, `background` | images: resolution (default 192: two image pixels per px); a color under the figure (default the figure's, white; `None` is transparent, white in JPEG) |
-
-JPEG XL output (`.jxl`) needs libjxl, AVIF output (`.avif`) libavif 1.x. Images inside a
+| `fonts` | the fonts text is shaped and embedded with ([fonts](#1-conventions)): a vec_io `Fonts` or a dict of its fields (`dirs`, `system`, `downloads`, `db`); default the figure's `fonts` |
+| `text_as_paths` | text drawn as the outlines of its glyphs: no font embedded, text not selectable (default `False`) |
+| `quality` | the figure's `quality` when not given: 1–100, `"lossless"` (not JPEG) or `"auto"`, the default: PNG 90, a palette of at most 256 colors; JPEG 90; JPEG XL, AVIF and rasterized content in a PDF or SVG lossless. It goes into `images` (PDF, EPS, SVG) or the format's option (`png`, …) unless a dict there sets its own; an option object is used as given |
+| `compression` | PDF and EPS: `"fast"`, `"balanced"` (default), `"small"`: the encoder's effort for streams and image samples; `None`: uncompressed streams, a readable file. Images: `png={"compression": …}`, … |
+| `simplify` | the figure's `simplify` for this output: every series without its own follows it ([large data](#large-data)) |
+| `font_hinting` | PDF and EPS: TrueType hinting kept in embedded subsets (default: left out) |
+| `flatten` | PDF, EPS and SVG: a vec_io `Flatten` or a dict of its fields (`transparency`, `fallback`, `dpi`, `budget`, `cell`): translucent content drawn as opaque vectors (PDF and SVG: off by default; EPS: always), and what cannot be (an image by default, at `dpi`; a dict's `dpi` takes `"2x"`) |
+| `dpi` | the output's resolution (dots per inch, or `"2x"`: 192). Images: rendered at it. PDF, EPS and SVG: their images (rasterized series, heatmaps drawn as images) resampled to it, by vec_io's `ImagePolicy(dpi=…)`; not given, they are kept as they are |
+| `default_dpi` | images without `dpi`: the resolution, for this call (default the figure's `default_dpi`, `"4x"`: four image pixels per px); PDF, EPS and SVG never use it |
+| `background` | images: the color the figure is drawn on, in place of its `background` (`None`, `"none"`: transparent, white in JPEG); not given, the figure's |
+| `images` | PDF, EPS and SVG: a vec_io `ImagePolicy` or a dict of its fields: `quality`, `jxl`, and with `dpi` `dpi_mode` (`"down"`, default: images finer than `dpi` resampled down; `"match"`: every image to `dpi`), `dpi_threshold` (images within this factor kept, default 1.5), `dpi_average` (shrinking averages the stored values, `"srgb"`, default, or light, `"linear"`) |
+| `png`, `jpeg`, `jxl`, `avif` | that image output: a vec_io `PNG`, `JPEG`, `JXL` or `AVIF` or a dict of its fields (`quality`, `compression`, …) |
+
+EPS output (`.eps`) is vec_io's: one page of PostScript Level 3, its transparency (the
+opacity of bands, markers, …) flattened into opaque shapes, with an image where it cannot
+be (dense translucent scatters), and its fonts embedded (Type 42 or CFF). SVG output
+(`.svg`) is vec_io's SVG writer: paths, `<text>` naming the font families (fonts are not
+embedded: the reader needs them, or use `text_as_paths=True`), images as PNG or JPEG data;
+it keeps what the PDF keeps (`simplify`, rasterized series as their images, `quality`). JPEG XL output
+(`.jxl`) needs libjxl, AVIF output (`.avif`) libavif 1.x. Images inside a
 PDF (rasterized series, heatmaps) are stored losslessly or as JPEG (`quality`), never as
 JPEG XL, so every PDF reader shows them. Fonts are embedded subsets without hinting: a
 typical figure's text adds a few KB per face. A plot
@@ -2390,9 +2917,9 @@ outer tick labels ([layout](#layout)).
 
 PNG quality: by default (`quality="auto"`) PNGs are palette images at quality 90: the plot's
 own colors stay exact, only antialiasing and gradients are approximated, and an image 256
-colors cannot render well enough stays lossless. The 21 example PNGs total 0.74 MB this way,
-1.57 MB with `quality="lossless"` and 1.38 MB lossless with `compression="best"` (same pixels,
-slower). Notebook previews are lossless.
+colors cannot render well enough stays lossless. The 28 example PNGs total 2.0 MB this way.
+Notebook previews (`_repr_png_`) are lossless, at the figure's `default_dpi`, and shown at the
+figure's size in px.
 
 ### Large data
 
@@ -2409,6 +2936,9 @@ slower). Notebook previews are lossless.
   axes and text stay vectors. Image output draws the group as vectors at its own
   resolution.
 
+Statistics and rasterization run on vec_io's worker threads: `VEC_IO_THREADS` sets their
+number (default: the usable CPUs, at most 8; 1: none). Results never depend on it.
+
 Timings (`tools/bench.py`, 8 threads, PDF written):
 
 | Case | Time |
@@ -2482,8 +3012,9 @@ Details:
   `"chr1:500kb-2Mb"`, with `k`, `M`, `G` and an optional `b`, any case, and `,` or `_`
   between thousands), a `(chr, start, end)` tuple or list (0-based, half-open; the same
   position strings), or a mapping with `chr`, `start` and `end`; `plot_io.genome.parse_region` gives the
-  `Region` (`chr`, `start`, `end`). A series reads its own `region`, else its x axis'.
-  Data are read when the figure is drawn, for the region drawn: `save`, `to_bytes`, `draw`
+  `Region` (`chr`, `start`, `end`). A region has no strand: a fourth element or a `strand`
+  key is a `ValueError`. A series reads its own `region`, else its x axis'.
+  Data are read when the figure is drawn, for the region drawn: `save`, `write`, `draw`
   and `size` take `region=` to draw another one (it replaces `fig.x_axis`'s region for
   that call).
 * **x axis.** Ticks under every track (but a Hi-C triangle with `direction="down"`), tick
@@ -2534,8 +3065,8 @@ readers, recognised by their `type` attribute (`"bigwig"`, `"bigbed"`, `"bed"`,
 | Data | Methods called |
 |---|---|
 | signal (bigWig; the coverage of bigBed, BED and peaks readers) | `read_values([(chr, start, end)], bin_count=n, bin_mode=…, def_value=…, zoom="auto")`, or with `bin_size=b, snap_to_grid="expand"` and the row's bounds from `resolve_regions([(chr, start, end)], bin_size=b, snap_to_grid="expand")` (without it, `snap_to_grid=False, full_bin=True`): one row of values |
-| intervals (bigBed, BED, peaks) | `read_entries([(chr, start, end)], as_cols=True, col_count=…)`: a dict (or a list of one dict) of columns; `col_count` from `auto_sql` when the reader has it |
-| annotation (GTF, GFF3) | `read_transcripts([(chr, start, end)], as_cols=True, gene_type=…, transcript_type=…)`: a dict (or a list of one dict) of transcript columns: `start`, `end`, `strand`, `transcript_id`, `transcript_name`, `gene_id`, `gene_name`, `cds_start`, `cds_end` (−1 when non-coding), `exon_starts`, `exon_ends`, `exon_offsets` |
+| intervals (bigBed, BED, peaks) | `read_entries([(chr, start, end)], columns=…)`: a table, a dict of columns; `columns` from `auto_sql` when the reader has it |
+| annotation (GTF, GFF3) | `read_entries([(chr, start, end)], model="transcript", gene_type=…, transcript_type=…)`: a table of transcripts: `start`, `end`, `strand`, `transcript_id`, `transcript_name`, `gene_id`, `gene_name`, `cds_start`, `cds_end` (−1 when non-coding); their exons are the table `nested["exons"]` (`start`, `end`), transcript `i`'s at rows `groups[i]:groups[i + 1]`. A reader is told for one by its `tss` method |
 | contacts (Hi-C) | `bin_sizes`, `normalizations`, `read_values((chr, start, end), bin_size=b, snap_to_grid="expand", normalization=…, matrix_type=…, max_distance=…)` (or `bin_count=n` instead of the first two): a square matrix; bounds from `resolve_regions((chr, start, end), bin_size=b, snap_to_grid="expand")["rows"]` |
 
 Results are read as buffers (numpy arrays included) without importing numpy. A path
@@ -2577,21 +3108,24 @@ t.bigwig(pax7_reader, name="Pax7", color="rose")
 | `def_value` | 0.0 | Value of bases no record covers; NaN breaks the line there. |
 | `kind` | 'step' | `step` (a step line along the bins), `line` (through the bin centres) or `bar` (one rectangle per bin). |
 | `fill_to` | 0.0 | Fill between the signal and a value, another series of the track (colored by whichever is above), or `False`. |
-| `fill` | 0.2 | Fill (to `fill_to`): an opacity of the line color, `True` (opaque), a color, or `False`. |
+| `fill` | True | Fill (to `fill_to`): `True` (the line color), a color, or `False`. |
+| `fill_opacity` | 0.2 | Opacity of the fill, times `opacity`. |
 | `color` | — | Line color; default black alone in its track, the next palette color when overlaid. |
 | `transform` | — | A function applied to each value (log, scaling). |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `FillStyle`, `Font`.
 <!-- /settings -->
@@ -2608,13 +3142,15 @@ pl.Genes(reader, plot=None, **settings)    # Bed with kind="genes", rows expande
 (dicts, or tuples in BED order). Used columns: `chr` (when given, rows of other
 chromosomes are left out), `start`, `end`, `name`, `score`, `strand`, `thickStart`,
 `thickEnd`, `itemRgb` (`reserved` in bigBeds), `blockCount`, `blockSizes`, `blockStarts`.
+A score that is not a number (`"."`) is missing (the map's `bad` color); an interval
+ending before it starts, or blocks not matching `blockCount`, are a `ValueError`.
 `genes` draws each BED12 model as a line, thin boxes for UTRs and thick boxes for coding
 exons, chevrons on introns (`strand`), and its name in italics with a strand mark
 (`Pcsk2 ›`). Names go left of their feature and are dropped where they would collide;
-with `rows="expand"` packing leaves room for them (`names=False`: none). `name_region` names only the
+with `rows="expand"` packing leaves room for them (their measured width) (`names=False`: none). `name_region` names only the
 features overlapping it (a locus within a wider view), and packing then makes room only
 for those names. Features are outlined in their color (`outline`, `line_width`) over their
-`fill` (an opacity of their color, 0.3; `False` for outlines only), the outline inside the feature's extent: a
+`fill` (`False` for outlines only) at `fill_opacity` (0.3), the outline inside the feature's extent: a
 feature narrower than two borders is one line, `line_width` wide. `recolor` snaps the features' colors
 (`itemRgb` ones included) to the named colors (`"blue 0.4"`, §7): `True` takes the
 closest of all shades, a level such as `0.4` the closest color's shade at that level, so
@@ -2633,7 +3169,8 @@ every feature has the same lightness.
 | `name_region` | — | Only features overlapping this region (as `region` takes it) get names; `None`: all. |
 | `strand` | False | Strand chevrons on boxes and introns. |
 | `outline` | True | Outline features in their color (`line_width` wide). |
-| `fill` | 0.3 | Fill of the features: an opacity of their color (times `alpha`), `True` (opaque), a color, or `False` (outlines only). |
+| `fill` | True | Fill of the features: `True` (their color), a color, or `False` (outlines only). |
+| `fill_opacity` | 0.3 | Opacity of the fill, times `opacity`. |
 | `row_height` | '1.2em' | Height of a row; the track's automatic height is rows × it, plus the y axis padding. Length; `%`: of the font size. |
 | `name_font_size` | '0.85em' | Font size of feature names. Length; `%`: of the font size. |
 | `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
@@ -2641,15 +3178,17 @@ every feature has the same lightness.
 | `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
 | `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
-| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_width` | inherited (0.5) | Line width. Length. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `FillStyle`, `TextStyle` (`name_`), `Font`.
 <!-- /settings -->
@@ -2664,7 +3203,7 @@ Groups: `FillStyle`, `TextStyle` (`name_`), `Font`.
 | `names` | True | Feature names (`name`) left of the features, dropped where they collide. |
 | `strand` | True | Strand chevrons on boxes and introns. |
 | `outline` | False | Outline features in their color (`line_width` wide). |
-| `fill` | True | Fill of the features: an opacity of their color (times `alpha`), `True` (opaque), a color, or `False` (outlines only). |
+| `fill_opacity` | 1.0 | Opacity of the fill, times `opacity`. |
 
 Groups: `FillStyle`.
 <!-- /settings -->
@@ -2708,7 +3247,8 @@ the cells of a size (`bins="5kb"`) sit on the file's grid, those past the region
 the track's edges, and `bins=n` reads n cells over the region exactly. Its color axis' limits default
 to quantiles of the cells drawn (`color_limits="q:0.01/q:0.99"`), on a log scale
 (`color_scale="log"`; cells of 0 take the map's low end; cells without a value take
-`nan_color`, transparent), through the figure's `color_map`.
+`nan_color`, transparent), through the figure's `color_map`. A region without a finite
+positive value draws no cells, its color axis at its default limits.
 
 <!-- settings:HiC -->
 | Setting | Default | Meaning |
@@ -2728,16 +3268,18 @@ to quantiles of the cells drawn (`color_limits="q:0.01/q:0.99"`), on a log scale
 | `fit` | 'clip' | How the triangle fits a height below its own (`max_height`, or the track's `height`): `clip` keeps square cells and cuts the distances above; `squash` flattens the whole triangle. |
 | `colorbar` | False | Attach a colorbar to the track. |
 | `name` | — | Legend entry; unset: not in the legend. |
-| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
 | `text_color` | inherited ('black') | Text color. |
 | `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
-| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_family` | inherited ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | Font family. |
 | `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
 | `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
 | `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
 Groups: `Font`.
 <!-- /settings -->
@@ -2768,41 +3310,45 @@ fig = pl.Figure(style="default")
 fig = pl.Figure(style={"base": "default", "font_size": 9, "Axis.grid": True})
 fig = pl.Figure(style={"base": ["house", "talk"], "palette": ["#333", "#c00"]})
 
-pl.register_style("house", {"font_family": "Helvetica", "Legend.frame": True})
+pl.registry.styles.add("house", {"font_family": "Helvetica", "Legend.frame": True})
 pl.set_style("house")                  # figures created afterwards
 with pl.use_style({"font_size": 10}):  # figures created inside the block
     ...
-pl.styles.names()                      # registered names
-pl.styles.settings("house")            # the resolved dict (base theme included)
+pl.registry.styles.names()             # registered names
+pl.registry.styles.get("house")        # every key of the chain, DEFAULTS included
 ```
 
 * **Keys.** Names of inherited settings (`"font_size"`, `"palette"`), `"Class.name"` for
-  any setting of a class and its subclasses (`Figure`, `FigureTitle`, `Plot`, `Title`,
-  `Legend`, `Axis` (plot, color and size axes), `Colorbar`, every series class, `Series` for
-  all of them, every decoration class, `Decoration` for all of them, the genome classes),
+  any setting of a class and its subclasses (`Figure`, `FigureTitle`, `MainTitle`, `Plot`, `Title`,
+  `Legend`, `FigureLegend`, `Axis` (plot, color and size axes), `Colorbar`,
+  `FigureColorbar`, every series class, `Series` for all of them, every decoration class,
+  `Decoration` for all of them, `FigureVLine`, `FigureVSpan`, `FigureGroup`, the genome
+  classes),
   or `"Group.member"` for every embedding of a group member (`"Marker.size"`,
   `"Stroke.line_width"`, `"TextStyle.font_weight"`).
   `"Colorbar.<axis setting>"` (`"Colorbar.tick_direction"`, `"Colorbar.tick_color"`, …)
   applies to color axes (the colorbars' axes) only, and `"XAxis.<setting>"`, `"YAxis.<setting>"` to the x or
   y axis of plots only; each wins over `"Axis.<setting>"` there.
   Keys starting with `--` are custom variables (`"--accent": "#c00"`), read by
-  `var(--accent)`. Values are checked when the style is registered or set.
-* **`"base"`.** A style name or a list of names, applied left to right (later ones win);
-  the dict's own keys are applied over them. Registered styles use the same form.
-* **Resolution.** The cascade of [conventions](#1-conventions): the object's own value,
-  class rules, `"Class.name"` keys along the class hierarchy, the parent (inherited
-  settings), `"Group.member"` keys, the class and group defaults, then the bare name. The
-  effective theme is the inherited defaults (the bare names of `DEFAULTS`) with the
-  expanded style merged over it.
+  `var(--accent)`; a style has no `"Figure.style"` (its bases are `"base"`) or `vars`
+  key. Values are checked when the style is registered or set.
+* **`"base"`.** A style name or a list of names (later ones win over earlier ones); the
+  style's own keys win over its bases. Registered styles use the same form.
+* **Chain.** A figure's style, then its bases (depth first, each once), then `"default"`
+  (`DEFAULTS`). The nearer style wins; within a style, the most specific key wins: a
+  style's `"Marker.size"` beats its base's `"Line.marker_size"`. The order against the
+  object's own values and the parent is the cascade of [conventions](#1-conventions);
+  `explain` names the style a value comes from.
 * **Default.** Without `style`, a figure takes the session style current when it is
-  created (`use_style` innermost, else `set_style`), else `"default"`, which adds nothing
-  to `DEFAULTS`.
+  created (`use_style` innermost, else `set_style`), else `"default"`. `DEFAULTS` is
+  read-only and `"default"` cannot be re-registered: change defaults with a style
+  (`pl.set_style({"font_family": "Nimbus Sans Narrow"})`).
 * **`scaling`.** A figure setting (default 1, or `"Figure.scaling"` in the style) that
   multiplies every absolute length: font sizes, line widths, marker sizes, tick lengths,
   pads and gaps, from the defaults, the style or set on objects (not the figure size).
   Lengths in `em` follow the scaled font size.
 
-Bundled styles (`pl.styles.names()`), each the defaults of a library expressed in these
+Bundled styles (`pl.registry.styles.names()`), each the defaults of a library expressed in these
 settings (colors, fonts, grid, axis lines, ticks, legend and title placement, palette,
 color map, default series looks). They never change plot sizes or the minus sign
 (`style={"base": "matplotlib", "minus": "minus"}` gets matplotlib's).
@@ -2810,6 +3356,7 @@ color map, default series looks). They never change plot sizes or the minus sign
 | Style | Follows | Variants |
 |---|---|---|
 | `default` | `DEFAULTS` | — |
+| `solid` | solid bars, bar histograms, areas and violins, black-outlined boxes, markers without outline; the base of the library styles | — |
 | `matplotlib` | matplotlib ≥ 2.0 defaults (tab10, viridis, four spines, rounded legend frame) | `matplotlib-classic` (1.x: ticks in on all sides, b g r c m y k, jet) |
 | `seaborn` | seaborn darkgrid, notebook context, deep, rocket | `seaborn-darkgrid`, `-whitegrid`, `-dark`, `-white`, `-ticks`; `-paper`, `-talk`, `-poster` (scaling 0.8, 1.5, 2) |
 | `ggplot2` | `theme_grey()`: grey panel, white grid with minor lines, left title, legend outside, `hue` palette | `ggplot2-bw`, `-light`, `-minimal`, `-classic` |
@@ -2834,16 +3381,15 @@ documented default properties. What cannot be expressed: legend titles naming a
 | Exception | Raised for |
 |---|---|
 | `NoFontError` (a `ValueError`, `vec_io.text.NoFontError`) | text with no outline font available at all ([fonts](#1-conventions)) |
-| `ValueError` | unknown settings or invalid values; mismatched data lengths; grids whose ids are not rectangles; ids outside the grid or taken; a full `rows` × `cols` arrangement; `width` with `plot_width`; a grid `layout` with `rows`/`cols`; ratios of the wrong length; mixed category and numeric series on an axis; limits outside a scale's domain; a colorbar without a mapped source, or of a `ColorMap`; `color_map`, `color_limits` or `color_scale` with a shared `color_axis`; shared color axes with different limits or scales; heatmap value labels on more than 2,500 cells; unknown formats or output options, or options of another format (`dpi` for a PDF, `compress` for an image); unknown bin rules or decreasing bin edges; negative pie values; pies with axis series on one plot; `axline` slopes on non-linear axes; decoration positions that are not categories of a category axis |
+| `ValueError` | unknown settings or invalid values; mismatched data lengths; grids whose ids are not rectangles; ids outside the grid or taken; a full `rows` × `cols` arrangement; `width` with `plot_width`; a grid `layout` with `rows`/`cols`; ratios of the wrong length; mixed category and numeric series on an axis; limits outside a scale's domain; a colorbar without a mapped source, or of a `ColorMap`; `color_map`, `color_limits` or `color_scale` with a shared `color_axis`; shared color axes with different limits or scales; heatmap value labels on more than 2,500 cells; unknown formats or output options, or options of another format (`background` for a PDF, `font_hinting` for an image); unknown bin rules or decreasing bin edges; negative pie values; pies with axis series on one plot; `axline` slopes on non-linear axes; decoration positions that are not categories of a category axis; dot grids of two shapes, or two rows for one dot cell |
 
 ## 12. Modules
 
-`pl.__all__` (51 names) is the API. These modules are public too:
-`plot_io.styles` (`pl.styles`: `names`, `settings`, `register_style`, `set_style`,
-`use_style`), `plot_io.genome` (`parse_region`, `Region`), `plot_io.markers`
-(`marker_path`, `marker_area`), `plot_io.color.palettes` (`PALETTE`), and the modules of
+`pl.__all__` (47 names) is the API. These modules are public too:
+`plot_io.registry` (`Registry`, and the registries), `plot_io.genome` (`parse_region`, `Region`), `plot_io.markers`
+(`resolve`, `marker_area`), `plot_io.color.palettes` (`PALETTE`), and the modules of
 the types calls return: `plot_io.facets` (`FacetSet`, `LayerSet`), `plot_io.tables`
-(`SeriesGroup`), `plot_io.colorbar` (`Colorbar`). The others are internal: their names
+(`SeriesGroup`), `plot_io.colorbar` (`Colorbar`, `FigureColorbar`). The others are internal: their names
 may change in any release.
 
 | Module | Role |
@@ -2853,11 +3399,12 @@ may change in any release.
 | `defaults.py`, `units.py` | `DEFAULTS`; units, `var()`/`calc()`/`inherit`, `%` referents, `explain` traces |
 | `spec.py` | a render's specs (the model resolved once, frozen), layout boxes, palette colors and trained color and size axes |
 | `figure.py`, `plot.py` | `Figure` (arrangement, tracks layout, figure axes, sizes, output), `Plot`, `Title`, `Legend` |
-| `rows.py` | row labels in a band left of the plots, groups of rows (`FigureGroup`), lines and bands through rows (`FigureVLine`, `FigureVSpan`) |
+| `titles.py`, `markup.py` | the settings plot and figure titles share (`TitleBase`) and a title's text block; markup in strings read into spans |
+| `rows.py` | row labels in a band left of the plots, groups of rows (`FigureGroup`: letters, labels as figure titles), lines and bands through rows (`FigureVLine`, `FigureVSpan`) |
 | `axis.py`, `scales.py`, `limits.py`, `ticks.py` | axes, scale functions, limits syntax, tick choice and labels |
 | `states.py` | the render's state of each plot: calls, palette, axes and their limits, legend, colorbars |
 | `layout.py`, `geometry.py` | the box model: bands measured around each plot's axes, the grid solved in rounds, the frozen geometry (`layout.layout(fig, fonts)`: text shaped with a font database, no canvas) |
-| `render.py` | drawing from the geometry; the page of a px document and its outputs (`doc.to_bytes`, `page.render(…).encode`) |
+| `render.py` | drawing from the geometry; the page of a px document and its outputs (`write`: plot_io's options mapped, `vec_io.Document.write`) |
 | `mapped.py` | color and size axes (`ColorAxis`, `SizeAxis`): own and shared axes of series, their training |
 | `legend.py`, `colorbar.py` | legend (with size keys) and colorbar: measured, placed, drawn |
 | `layers/` | plot types as layers: `base.py` (`Series`, the model of a call; `data=`/`group=`), `core.py` (`Layer`, `Call`, `Table`), `stats.py` (columns from data), `positions.py` (stack, dodge, jitter, swarm, packing), `geoms.py` (the eight geoms: extent, drawing, legend symbol, occupancy, hit area), `pipeline.py` (calls per plot, palette training), `paint.py` (colors, mapped values, markers), `context.py` (drawing context, the x↔y swap); `register_layer` |
@@ -2866,10 +3413,11 @@ may change in any release.
 | `stats.py` | bins, densities, contours, LOWESS and swarm layout, adapted to plot_io's needs |
 | `kernels.py`, `_native/` | the numeric kernels (statistics, scaling, gathering) and their C library `plio`: sources, built binaries, bindings generated from `src/plio_api.h` (see `_native/README.md`) |
 | `decorations.py` | reference lines, spans, text and annotations |
-| `color/` | colors: `values.py` (the `color` validator, named color scales, palette references, alpha, saturation, luminance), `palettes.py` (palettes: the discrete colors series take in turn; registry, ggplot2's hues), `maps.py` (`ColorMap`: the gradients of color axes and the palette indices or positions of heatmap cells, evaluated in plot_io's C library), `data.py` (bundled map and palette colors) |
+| `color/` | colors: `values.py` (the `color` validator, named color scales, palette references, alpha channels, saturation, luminance), `palettes.py` (palettes: the discrete colors series take in turn; registry, ggplot2's hues), `maps.py` (`ColorMap`: the gradients of color axes and the palette indices or positions of heatmap cells, evaluated in plot_io's C library), `data.py` (bundled map and palette colors) |
 | `sizemaps.py` | `SizeMap`: the diameters of size axes |
 | `markers.py`, `lines.py`, `text.py` | marker shapes, line dash styles, one-line text through `vec_io.text`: shaped lines (memoized in the font database, rich content per render), placed runs drawn as shaped, the title's paragraphs |
-| `styles/` | style registry and expansion; bundled styles (point libraries in `pt`) |
+| `styles/` | styles and their expansion; bundled styles (point libraries in `pt`) |
+| `registry.py` | `pl.registry`: the color map, palette, marker, style and layer registries |
 | `values.py`, `density.py` | values given to `color`/`size` and their rules; `Density` (point density) |
 | `tables.py`, `facets.py` | columns of tables, `group=` splitting (`SeriesGroup`); `facet`, `FacetSet`, `LayerSet` |
 | `sharing.py`, `times.py` | shared axes; dates and times on axes |