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

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

@@ -7,12 +7,13 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
 3. [Plots](#3-plots)
 4. [Axes](#4-axes)
 5. [Series](#5-series)
-6. [Colorbars](#6-colorbars)
+6. [Color and size axes](#6-color-and-size-axes)
 7. [Colors, maps and markers](#7-colors-maps-and-markers)
 8. [Output](#8-output)
-9. [Styles](#9-styles)
-10. [Errors](#10-errors)
-11. [Modules](#11-modules)
+9. [Genome tracks](#9-genome-tracks)
+10. [Styles](#10-styles)
+11. [Errors](#11-errors)
+12. [Modules](#12-modules)
 
 ## 1. Conventions
 
@@ -28,25 +29,63 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   the setting (with the nearest valid name).
 * **Inheritance.** Settings marked *inherited* in the tables (font, line width, palette,
   alpha, `rasterize`, `simplify`) are looked up series → plot → figure → style.
-* **Defaults.** Every default is in one dict, `plot_io/defaults.py`'s `DEFAULTS`
-  (`pl.defaults()` returns a copy): bare names for inherited settings (font size,
-  sans-serif, black text, line width, `simplify="auto"`, the palette, …), and
-  `"Class.name"` for the settings of each class. A class without an entry uses its base
-  class's. Entries are plain data: a default that follows another setting is written
-  with units, `var()` or `calc()` (a legend's font is `"1em"`, a minor tick `"60%"` of the
-  tick length, a fill's opacity `"calc(0.3 * var(alpha))"`). `None` and `"auto"` mean
-  "chosen when drawing", as each setting's documentation says. `"XAxis.name"` and
+* **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
+  `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`,
+  `marker_edge_color`; a box's whiskers are `whisker_color`, `whisker_width`,
+  `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, …),
+  `"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
+  another setting is written with units, `var()` or `calc()` (a legend's font is `"1em"`,
+  a minor tick `"60%"` of the tick length), and a class default of an inherited setting
+  scales the inherited value with `inherit` (a regression line is
+  `"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
+  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 (`pl.THEME`). See [Styles](#styles).
+  merged over the inherited defaults (the bare names of `DEFAULTS`). See [Styles](#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
-  `pl.Scatter(…, plot=p)`. Keywords that belong to a level above go to it:
-  `pl.Scatter(x, y, width=300, title="T")`. A name present on several levels goes to
-  the lowest.
+  `pl.Scatter(…, plot=p)`. Keywords that belong to a level above go to it when the call
+  creates that level: `pl.Scatter(x, y, width=300, title="T")` makes and sets the plot and
+  the figure. Adding to an existing plot or figure takes the new object's settings only:
+  `p.scatter(x, y, title="T")` raises `ValueError` naming `plot.set(title=…)`. A name
+  present on several levels goes to the lowest.
 * **Units.** Lengths take units (`"1.5in"`, `"0.5em"`, `"60%"`); bare numbers are CSS px
-  (1 px = 1/96 in = 0.75 pt), except slot widths (data units). See [values](#values).
+  (1 px = 1/96 in = 0.75 pt) everywhere. Slot widths (`Bar`, `Box`, `Violin`, `Strip`,
+  `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).
 * **Data.** Sequences (`None` = missing), `array.array`, or any buffer (numpy arrays are
@@ -55,7 +94,7 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   With `data=` (a table), strings in data arguments name its columns
   ([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` (pdf_io's), e.g. `["Area (m", pl.Span("2",
+  strings and `pl.Span` (vec_io's), e.g. `["Area (m", pl.Span("2",
   baseline_shift="super", font_scale=0.7), ")"]`.
 * **Named colors.** `"blue"`, `"blue 0.45"`, `"blue 45%"`: 28 scales (`red`, `orange`,
   `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`,
@@ -66,21 +105,35 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   a bare name is level 0.5. They take precedence over CSS's names (`"red"` is `#fb2c36`,
   not `#ff0000`); other CSS names (`"navy"`) keep their CSS values. `get()` returns the
   name as given, `resolve()` the hex color.
-* **Colors.** Named colors (above), any color pdf_io accepts: CSS names, `"#rrggbb[aa]"`, CSS Color 4 functions
+* **Colors.** Named colors (above), any color vec_io accepts: CSS names, `"#rrggbb[aa]"`, CSS Color 4 functions
   (`"rgb(…)"`, `"hsl(…)"`, `"hwb(…)"`, `"lab(…)"`, `"lch(…)"`, `"oklab(…)"`,
   `"oklch(64.5% 0.246 16.439)"`, `"color(display-p3 1 0 0)"`, …; colors outside sRGB are
-  gamut mapped as browsers do), tuples, `CMYK` and `Spot`; and `"C0"`, `"C1"`, … for the
+  gamut mapped as browsers do), tuples of numbers in [0, 1] (`(1, 0.5, 0)`; on the 0–255
+  scale write `"rgb(255 128 0)"`), `CMYK` and `Spot`; and `"C0"`, `"C1"`, … for the
   palette's colors.
 * **Fonts.** `font_family` is a CSS family list; weights (`font_weight`, `label_weight`,
   `tick_label_weight`) are `normal`, `bold` or 1–1000, styles `normal`, `italic`,
-  `oblique` or `"oblique 10deg"`. With a variable font (pdf_io embeds the instance used),
+  `oblique` or `"oblique 10deg"`. With a variable font (vec_io embeds the instance used),
   the weight sets `wght`, the inherited `font_stretch` (`"condensed"`, `"87.5%"`) sets
   `wdth`, the style `ital` or `slnt`, `font_optical_sizing="auto"` sets `opsz` from the
   font size, and `font_variations` (`{"GRAD": 50}`) any axis:
   `pl.Figure(font_family="Roboto Flex", font_stretch="85%", font_variations={"GRAD": 50})`.
-* **Enums.** Enum-like settings take strings; `pl.Marker`, `pl.LineStyle`,
-  `pl.Orientation`, `pl.Scale`, `pl.Position`, `pl.Order` and `pl.Align` are `str` enums
-  of the same values.
+* **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
+  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).
+* **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.
 
 ### Values
 
@@ -91,7 +144,8 @@ setting, or an expression:
 pl.Plot(width="3in", font_size="9pt", title="T")
 p.x_axis(tick_length="0.5em", minor_tick_length="50%", tick_rotation="0.125turn")
 p.bar(days, counts, width="20h")                   # a duration on a time axis
-p.errorbar(x, y, y_error=e, cap_length="0.2data")  # data units across the bar
+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)")
 fig.set(vars={"accent": "#c00"})                   # custom variables, read by var(--name)
@@ -99,28 +153,29 @@ fig.set(vars={"accent": "#c00"})                   # custom variables, read by v
 
 | Unit | Meaning |
 |---|---|
-| bare number | px (lengths), degrees (angles); data units for slot widths (`Bar`, `Box`, `Violin`, `Strip`, `Swarm` `width`) |
+| bare number | px (lengths), degrees (angles) |
 | `px` `pt` `pc` `in` `cm` `mm` `Q` | absolute lengths |
 | `em` | the object's `font_size`; in a `font_size` setting, the parent's |
 | `rem` | the figure's `font_size` |
-| `%` | of the reference the setting's table entry names: another setting (`minor_tick_length`: of `tick_length`), the font size, the axes side (`tick_length`: across the axis), the slot, the box, the radius, the data range (`padding`) |
-| `data` | along a data axis: data units on linear axes, categories on category axes, seconds on time axes; an error on log, symlog and logit axes |
+| `%` | of the reference the setting's type declares and its table entry names: another setting (`minor_tick_length`: of `tick_length`), or one of the [referents](#referents) |
+| `d`, `data` | along a data axis: data units on linear axes, categories on category axes, seconds on time axes; an error on log, symlog and logit axes. On a time axis `d` is a day |
 | `ms` `s` `min` `h` `d` `w` | durations, as data units of time axes (a `timedelta` too) |
 | `fr` | a share of the room left by fixed tracks, in `Figure.widths`/`heights` |
 | `deg` `grad` `rad` `turn` | angles |
 | `xx-small` … `xx-large`, `smaller`, `larger` | font sizes: × 0.579 … 1.728 of `rem`; ÷/× 1.2 of the parent's |
 
 * **`var(name[, fallback])`** reads another setting of the object, resolved through the
-  usual inheritance; `var()` of the setting's own name reads the parent's value
-  (`alpha="calc(var(alpha) / 2)"`). `var(--name)` reads a custom variable: from 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
   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()`.
-* **`calc()`** takes `+ - * /`, parentheses, numbers, dimensions with any unit and
-  `var()`: dimensions add to dimensions and multiply or divide by numbers.
+* **`calc()`** takes `+ - * /`, parentheses, numbers, dimensions with any unit, `var()`
+  and `inherit`: dimensions add to dimensions and multiply or divide by numbers.
 * **Layout.** `%` of the axes is exact with `reference="axes"` (the axes size is given)
-  and resolved inside the layout loop otherwise; it is known only while the figure is
-  drawn. `spacing`, `margin` and fixed `widths`/`heights` in `%` of the figure are solved
+  and resolved in each [layout](#layout) round otherwise; it is known only while the
+  figure is drawn. A render first resolves every other setting of the figure once (the values
+  drawing reads); settings set while it runs take effect at once. `spacing`, `margin` and fixed `widths`/`heights` in `%` of the figure are solved
   exactly when the figure size follows from its contents.
 * **Scaling.** `Figure.scaling` multiplies every absolute length (px and physical units)
   wherever it is given: on objects, in styles, in `DEFAULTS`; not the figure size.
@@ -130,10 +185,73 @@ fig.set(vars={"accent": "#c00"})                   # custom variables, read by v
   (`resolve(name, of=…)` for settings whose `%` reference the caller passes), and
   `explain(name)` a trace:
 
+#### Referents
+
+What `%` of a length can be of, besides another setting (the tables name it per setting):
+
+<!-- settings:referents -->
+| Key | `%` of |
+|---|---|
+| `em` | the font size |
+| `axes_width` | the axes width |
+| `axes_height` | the axes height |
+| `across` | the axes side across the axis |
+| `along` | the axes side along the axis |
+| `axes` | the axes width (across) or height (down) |
+| `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 |
+| `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 |
+| `box_width` | the box width |
+| `radius` | the radius |
+<!-- /settings -->
+
+#### 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.
+
+<!-- settings:groups -->
+| Group | Member | Under a prefix `{p}` | Default |
+|---|---|---|---|
+| `Font` | `font_size` | `{p}font_size` | inherited |
+| `Font` | `font_family` | `{p}font_family` | inherited |
+| `Font` | `font_stretch` | `{p}font_stretch` | inherited |
+| `Font` | `font_variations` | `{p}font_variations` | inherited |
+| `Font` | `font_optical_sizing` | `{p}font_optical_sizing` | 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_style` | `{p}style` | 'solid' |
+| `Stroke` | `cap` | `{p}cap` | 'butt' |
+| `Stroke` | `join` | `{p}join` | 'round' |
+| `Marker` | `marker` | `marker (never prefixed)` | 'circle' |
+| `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` | `fill` | `{p}fill` | True |
+| `Marker` | `size_basis` | `size_basis (never prefixed)` | 'area' |
+| `FillStyle` | `fill` | `{p}fill` | — |
+| `NumberFormat` | `decimal_separator` | `{p}decimal_separator` | inherited |
+| `NumberFormat` | `thousands_separator` | `{p}thousands_separator` | inherited |
+| `NumberFormat` | `minus` | `{p}minus` | inherited |
+| `NumberFormat` | `prefix` | `{p}prefix` | inherited |
+| `NumberFormat` | `suffix` | `{p}suffix` | inherited |
+| `NumberFormat` | `precision` | `{p}precision` | inherited |
+<!-- /settings -->
+
 ```
 >>> pl.Plot(style="matplotlib").x_axis.explain("tick_spacing")
-Axis.tick_spacing = (46.6667px, 33.3333px) ← ('calc(3.5 * var(tick_font_size))', 'calc(2.5 * var(tick_font_size))')  (default Axis.tick_spacing)
-  Axis.tick_font_size = 13.3333px ← '1em'  (default Axis.tick_font_size)
+Axis.tick_spacing = (46.6667px, 33.3333px) ← ('calc(3.5 * var(tick_label_font_size))', 'calc(2.5 * var(tick_label_font_size))')  (default Axis.tick_spacing)
+  Axis.tick_label_font_size = 13.3333px ← '1em'  (default Axis.tick_label_font_size)
     Axis.font_size = 13.3333px ← '10.0pt'  (inherited from Figure: style "matplotlib" font_size)
 ```
 
@@ -142,17 +260,29 @@ Axis.tick_spacing = (46.6667px, 33.3333px) ← ('calc(3.5 * var(tick_font_size))
 ```python
 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.colorbar(source, id=None, **settings)
+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.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")
+fig.vline(x, rows=None, **settings)      # through plots and the gaps between them
+fig.vspan(x0, x1=None, rows=None, **settings)
+fig.group(first, last=None, label=None, letter=None)
 fig.plots                                # plots in creation order
 ```
 
+A plot type called on the figure (`fig.scatter(…)`, `fig.hist(…)`, `fig.bigwig(…)`) makes
+a new plot holding it and returns the series: the plot's settings that the plot type
+lacks, `title`, `x_axis` and `y_axis` go to the plot.
+
 ### Arrangement
 
-* **Grid.** `grid=[[1, 1, 2], [3, 3, 2]]`: each id covers a rectangle of cells; `0` or
+* **Grid.** `layout=[[1, 1, 2], [3, 3, 2]]`: each id covers a rectangle of cells; `0` or
   `None` leaves a cell empty. An id holds a plot or a colorbar. `fig.plot()` returns the
   next id without a plot, in reading order.
-* **Automatic.** Plots take positions in creation order:
+* **Automatic** (`layout="auto"`, the default). Plots take positions in creation order:
 
 | Settings | Arrangement |
 |---|---|
@@ -161,9 +291,16 @@ fig.plots                                # plots in creation order
 | `rows=2, cols=3` | a fixed 2 × 3 grid, row by row (full: `ValueError`) |
 | neither | ⌈√n⌉ columns, row by row, chosen when drawn (adding plots can move earlier ones) |
 
-`order` (`"row"` or `"col"`) overrides the fill direction. In automatic arrangement ids
+`fill_order` (`"row"` or `"col"`) overrides the fill direction. In automatic arrangement ids
 are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 
+* **Tracks.** `layout="tracks"`: one column of plots top to bottom in creation order
+  (`cols` 1), sharing x (`share_x="all"`), `spacing` 0 and `width` 480 px unless given;
+  each row is as high as its plot's `height` (a [track](#tracks)'s: a length, a share such
+  as `"1fr"`, or from its content), other plots `1fr`. New plots are tracks
+  (`fig.plot()`, `fig.track()`, `fig.bigwig(…)`). `pl.Tracks(region)` is this layout with
+  a genome x axis ([§9](#9-genome-tracks)).
+
 ### Sizes and alignment
 
 * `width` × `height` is the size of the box `reference` names:
@@ -171,8 +308,8 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
   * `"plot"`: each cell's whole plot box (axes and decorations); the figure size follows;
   * `"figure"`: the whole figure; the cells share what the decorations leave.
 
-  With only one of `width` and `height`, `aspect_ratio` (width / height, default 4/3)
-  gives the other; with neither, the default is 3 × 2.25 in (288 × 216 px). Giving all
+  With only one of `width` and `height`, `aspect_ratio` (width / height, default 5/4)
+  gives the other; with neither, the default is 150 × 120 px. Giving all
   three raises `ValueError`. Plots with a `data_ratio` (and pies) take the other side from
   it when only `width` or only `height` is given. `widths`/`heights` are the columns' and
   rows' ratios (numbers or `fr`), or fixed lengths (`["2in", "1fr", "1fr"]`) that the
@@ -192,8 +329,38 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 * Columns (rows) holding only vertical (horizontal) colorbars are as wide as the bar,
   unless `widths` (`heights`) is given.
 * Margins come from the real text metrics of tick labels, axis labels, titles, outside
-  legends and attached colorbars. The layout repeats until the axes sizes settle (tick
-  choice depends on axis length).
+  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.
+* **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.
+* **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
+  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
+  placed on the occupancy grid of the placed axes; one moved outside takes a round more.
+* **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.
+* **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.
 
 ### Figure title
 
@@ -208,7 +375,7 @@ rightmost axes (a left-aligned title starts at the first y axis line), `"figure"
 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` (a color) draws a rule `title_rule_width` thick above the title, across its
+`title_rule_color` draws a rule `title_rule_width` thick above the title, across its
 width.
 
 <!-- settings:FigureTitle -->
@@ -216,17 +383,19 @@ width.
 |---|---|---|
 | `text` | — | Title text: a string or rich content; `\n` starts a line. |
 | `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
-| `font_weight` | 'bold' | `bold`, `normal` or a weight 1–1000. |
+| `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`. Length; `%`: of the font size. |
+| `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_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`. |
+
+Groups: `TextStyle`, `Font`.
 <!-- /settings -->
 
 ### Shared axes
@@ -241,10 +410,11 @@ q = fig.plot(share_x=p)                          # q's x axis joins p's group
 the same column span) or `"row"` (the same row span). `share` sets both; `"grid"` means x
 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.
+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)).
 
 Within a group the scale (which must be equal), the limits (from all members' series,
-then padding, `include_zero` and `nice`; one explicit `limits` applies to the group, two
+then padding, `include_zero` and `snap`; one explicit `limits` applies to the group, two
 different ones are an error), inversion, ticks and category order (first appearance, in
 plot order) are shared; titles, grid, spines and colors stay per plot. With
 `label_outer` (default for figure-level groups), tick labels and axis titles are drawn
@@ -252,52 +422,146 @@ only on the bottom plot of each column (x; top for `side="top"`) and the left pl
 each row (y; right for `side="right"`); ticks stay on every plot and inner gutters
 shrink. `Plot.save` of a member keeps the group's limits and shows its labels.
 
+### Figure axes
+
+```python
+fig.x_axis(label="Time (s)", tick_format="int")  # every plot's x axis
+fig.y_axis(scale="log10")
+```
+
+`fig.x_axis` and `fig.y_axis` hold settings that every plot's x (y) axis takes unless the
+axis has its own: they come right after the axis' own values in the cascade
+([§1](#1-conventions)), so they beat styles and defaults. Twins' axes take them too; color
+and size axes do not.
+
+### Rows
+
+```python
+p = fig.plot(y_axis={"label": "Control", "label_position": "band"})   # a row label
+fig.group(p, q, label="Treated", letter="B")    # plots p to q (creation order)
+fig.vline(0, rows=[p, q])                        # through p, q and the gap between them
+fig.vspan(-1, 1)                                 # under every plot
+```
+
+* **Row labels.** The y axis' `label` with `label_position` `"band"` (rotated) or
+  `"left"` (horizontal, right-aligned) sits in a band left of the plot instead of beside
+  the tick labels; `"inside"` puts it inside the axes at the top left; `\n` starts a line.
+  The band is as wide as the widest label of the plots starting in the same grid column,
+  and the labels line up at the widest y axis margin of that column. A plot has one y
+  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).
+* **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
+  the drawn units of the first plot's x axis. Bands are drawn under the plots, lines over
+  them. `fig.vspan(region)` takes a genome region (`"chr1:1,400,001-1,450,000"`, a
+  `(chr, start, end)` tuple) as positions, less the x axis' `origin`.
+
+FigureVLine:
+
+<!-- settings:FigureVLine -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | '#4d4d4d' | Line color. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_style` | 'dashed' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
+| `alpha` | 1.0 | Opacity. |
+
+Groups: `Stroke`.
+<!-- /settings -->
+
+FigureVSpan:
+
+<!-- settings:FigureVSpan -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | '#e5e5e5' | Fill color. |
+| `alpha` | 1.0 | Opacity. |
+<!-- /settings -->
+
+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. |
+| `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. |
+| `text_color` | inherited ('black') | Text color. |
+
+Groups: `TextStyle` (`letter_`).
+<!-- /settings -->
+
 ### Facets
 
 ```python
-fig = pl.facet(df, col="condition", row="replicate", share="grid", colorbar="right")
-fig.scatter("x", "y", c="density")               # in every panel, on its rows
-fig.map(lambda p, rows: p.hist(rows["x"]))        # anything, per panel
+fig, panels = pl.facet(df, col="condition", row="replicate", colorbar="right")
+panels.scatter("x", "y", c="density")            # one layer per panel, on its rows
+panels.hline(0, line_style="dashed")             # decorations on every panel
+panels.map(lambda p, rows: p.hist(rows["x"]))     # anything, per panel
+fig.save("facets.pdf")
 ```
 
 `pl.facet(data, col=None, row=None, wrap=None, share="grid", order=None,
-title_format="{name} = {value}", colorbar=None, **figure_settings)` returns a
-`FacetFigure` with one plot per combination of `row` and `col` values (first-appearance
-or categorical order; `order={column: [values]}`), in a grid; `wrap` wraps `col` alone
-into rows of that many panels. Panels are titled by `title_format`. Series methods on the
-figure call the same method on every panel with `data=` its rows: group levels get the same
-colors in every panel, and numbers or densities in `color` share one `ColorMap` (shown by
-the extra-column colorbar with `colorbar="right"`). `fig.map(func)` calls `func(plot,
-rows)` per panel; `fig.panels` maps facet keys (a value, or `(row value, col value)`) to
-plots, and `fig.plot(key)` returns one. Axes are shared per column and row by default,
-with outer labels only.
+title_format="{name} = {value}", colorbar=None, **figure_settings)` returns an ordinary
+`Figure`, with one plot per combination of `row` and `col` values (first-appearance or
+categorical order; `order={column: [values]}`) in a grid, and the `FacetSet` of those
+panels. `wrap` wraps `col` alone into rows of that many panels. Panels are titled by
+`title_format`.
+
+* **Layers.** A plot type called on the set (`panels.scatter(…)`, any registered one)
+  calls it on every panel with `data=` the panel's rows and returns a `LayerSet` (a list
+  of the series; `.set(**settings)` sets them all, `.plots` their plots). Group levels
+  (`group=`) get the same colors in every panel. Decorations (`hline`, `vline`, `axline`,
+  `hspan`, `vspan`, `text`, `annotate`) go on every panel.
+* **Shared axes** are the figure's ordinary options: `share` (default `"grid"`: x per
+  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.
+* `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)`.
 
 ### Settings
 
 <!-- settings:Figure -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `grid` | — | Rows of ids; each id covers a rectangle of cells, `0`/`None` leaves a cell empty. |
+| `layout` | 'auto' | `auto`: plots in automatic rows and columns (`rows`, `cols`, `fill_order`); rows of ids (`[[1, 1, 2], [3, 4, 2]]`): each id covers a rectangle of cells, `0`/`None` leaves a cell empty; `tracks`: one column of plots top to bottom in creation order, sharing x, each row as high as its plot's `height` (tracks: from their content; other plots `1fr`). |
 | `rows` | — | Automatic arrangement: rows. |
 | `cols` | — | Automatic arrangement: columns. |
-| `order` | 'auto' | Fill order of the automatic arrangement: `auto` (row by row with `cols`, column by column with `rows`), `row` or `col`. |
+| `fill_order` | 'auto' | Fill order of the automatic arrangement: `auto` (row by row with `cols`, column by column with `rows`), `row` or `col`. |
 | `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` | '3in' | Width of the `reference` box: one cell's axes, one cell's plot, or the figure. Length. |
+| `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. |
-| `aspect_ratio` | 1.3333333333333333 | Width / height of the `reference` box (16:9 → `16 / 9`), when only one of `width` and `height` is given. |
+| `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. |
-| `margin` | 5.0 | Space around the figure. Length. |
-| `background` | — | Figure background; unset: transparent (white in JPEG, which has no transparency). |
+| `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` | — | Quality (1–100), as pdf_io's: of JPEG, JPEG XL and AVIF output, and of rasterized content in PDFs (stored as JPEG). Unset: pdf_io's defaults (JPEG 90; JPEG XL, AVIF and PDF images lossless). |
-| `title_rule` | — | Color of a rule above the figure title, across its width (The Economist's red bar); default none. |
+| `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. |
 | `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`. |
 | `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"}`. |
@@ -308,11 +572,11 @@ with outer labels only.
 | `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`. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (1.25) | Default line width. Length. |
-| `palette` | inherited (10 colors) | Colors of series without one. |
+| `line_width` | inherited (0.75) | Default line width. Length. |
+| `palette` | inherited ('tab10_custom') | Colors of series without one. |
 | `alpha` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
-| `simplify` | inherited ('auto') | pdf_io's `simplify` for every series; default `"auto"`. |
+| `simplify` | inherited ('auto') | vec_io's `simplify` for every series; default `"auto"`. |
 | `data` | inherited (None) | A table whose columns the series' data arguments name. |
 | `color_map` | inherited ('rainbow_llhh') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
@@ -321,12 +585,14 @@ with outer labels only.
 | `prefix` | inherited ('') | Text before every number. |
 | `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`.
 <!-- /settings -->
 
 ## 3. Plots
 
 ```python
-pl.Plot(figure=None, id=None, **settings)   # title="…" sets the title text
+pl.Plot(figure=None, id=None, **settings)   # title="…", x_axis={…}, y_axis={…}
 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)
@@ -334,7 +600,9 @@ p.series   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. Series are drawn in `z` order (default: call order) inside the
+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":
+"log"})`, `fig.bigwig(reader, y_axis={"label": "ATAC"})`. Series are drawn in `z` order (default: call order) inside the
 axes clip.
 
 <!-- settings:Plot -->
@@ -343,7 +611,7 @@ axes clip.
 | `spines` | 'bottom left' | Axis lines drawn: any of `left`, `bottom`, `right`, `top`, or `all`, `none`. |
 | `data_ratio` | — | Data aspect ratio: 1 makes one unit as long on both axes. |
 | `background` | — | Background color of the axes area. |
-| `border` | — | Color of a frame around the axes area (drawn under the axis lines); default none. |
+| `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. |
 | `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). |
@@ -351,17 +619,18 @@ axes clip.
 | `share_y` | — | Another plot whose y axis this plot shares. |
 | `vars` | — | Custom variables, read by `var(--name)` in any setting here and below: `{"accent": "#c00"}`. |
 | `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_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`. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (1.25) | Default line width. Length. |
-| `palette` | inherited (10 colors) | Colors of series without one. |
+| `line_width` | inherited (0.75) | Default line width. Length. |
+| `palette` | inherited ('tab10_custom') | Colors of series without one. |
 | `alpha` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
-| `simplify` | inherited ('auto') | pdf_io's `simplify` for every series: `"auto"`, `True`, a dpi or `False`. |
+| `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. |
 | `data` | inherited (None) | A table (dict, pandas or polars data frame, numpy structured array): strings in the data arguments of series name its columns. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
@@ -370,6 +639,8 @@ axes clip.
 | `prefix` | inherited ('') | Text before every number. |
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`border_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ### Title
@@ -389,6 +660,8 @@ axes clip.
 | `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`. |
+
+Groups: `TextStyle`, `Font`.
 <!-- /settings -->
 
 ### Legend
@@ -398,13 +671,19 @@ swatch or box), or with `glyph="box"`, `"circle"` or `"line"` in the series colo
 `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_map` adds a size key to its
-plot's legend, below the series entries: the map's `label` (default: the `size` column
-name) as a header, then sample markers at their real size with their values (3–5 nice
-numbers inside the map's limits, or the list given as the series' `size_legend`;
-`size_legend=False` drops it). Series sharing one `SizeMap` share one key, in grey; a
-single series' key takes its color (grey when its colors are mapped). `fig.size_legend(size_map,
-id=…, values=None, title=None)` places a key in its own grid area, as colorbars do.
+**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).
+`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.
 
 `auto` chooses a position once the axes are placed. Every series marks what it draws on a
 64 × 64 grid over the axes: markers (with their size), lines and curves (along their
@@ -423,19 +702,19 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 | `position` | 'auto' | `auto`, `top_right`, `top_left`, `bottom_right`, `bottom_left`, `top`, `bottom`, `outside_right`, `outside_top`, `outside_bottom` or `none`. |
 | `columns` | 1 | Number of columns. |
 | `frame` | False | Draw a frame and background. |
-| `title` | — | Legend title; default the `group` column name. |
+| `title` | 'auto' | Legend title; `"auto"`: the `group` column name, if any. |
 | `font_size` | '1em' | Font size. Length; `%`: of the parent's font size. |
 | `color` | 'var(text_color)' | Text color. |
 | `background` | 'white' | Background of a framed legend. |
 | `frame_color` | '#999999' | Frame color. |
-| `pad` | 5.0 | Gap to the axes. Length. |
 | `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. |
 | `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` | '2em' | Width of an entry's symbol. Length; `%`: of the font size. |
+| `glyph_length` | '1.4em' | Width of an entry's symbol. Length; `%`: of the font size. |
 | `row_height` | '1.35em' | Height of an entry. Length; `%`: of the font size. |
 | `glyph_gap` | '0.5em' | Gap between a symbol and its text. Length; `%`: of the font size. |
 | `column_gap` | '1em' | Gap between columns. Length; `%`: of the font size. |
@@ -445,6 +724,8 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 | `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`. |
+
+Groups: `TextStyle`, `Stroke` (`frame_`), `Font`.
 <!-- /settings -->
 
 ### Decorations
@@ -474,15 +755,17 @@ HLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_width` | inherited (0.75) | 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; bare numbers: data units. |
-| `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; bare numbers: data units. |
+| `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. |
 | `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. |
+
+Groups: `Stroke`.
 <!-- /settings -->
 
 AxLine:
@@ -491,13 +774,15 @@ AxLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_width` | inherited (0.75) | 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. |
 | `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. |
+
+Groups: `Stroke`.
 <!-- /settings -->
 
 HSpan:
@@ -508,13 +793,15 @@ HSpan:
 | `color` | '#e5e5e5' | Fill color. |
 | `edge_color` | — | Outline color; default none. |
 | `edge_width` | 0.0 | Outline width. Length. |
-| `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; bare numbers: data units. |
-| `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; bare numbers: data units. |
+| `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. |
 | `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. |
+
+Groups: `Stroke` (`edge_`).
 <!-- /settings -->
 
 Text:
@@ -540,6 +827,8 @@ Text:
 | `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. |
+
+Groups: `TextStyle`, `Font`.
 <!-- /settings -->
 
 Annotate:
@@ -547,22 +836,6 @@ Annotate:
 <!-- settings:Annotate -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `rotation` | 0.0 | Rotation (degrees, counterclockwise). Angle (bare: degrees). |
-| `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_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`. |
-| `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. |
-| `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. |
 | `align` | 'center' | Horizontal alignment on `xytext`. |
 | `valign` | 'center' | Vertical alignment on `xytext`. |
 | `text_coords` | 'var(coords)' | Coordinates of `xytext`: as `coords`, or `offset` (px from `xy`, y up); default `coords`. |
@@ -572,6 +845,8 @@ Annotate:
 | `arrow_width` | 0.75 | Arrow line width. Length. |
 | `head_length` | 7.0 | Arrowhead length. Length. |
 | `shrink` | 3.0 | Gap left at both ends of the arrow. Length. |
+
+Groups: `Stroke` (`arrow_`).
 <!-- /settings -->
 
 ## 4. Axes
@@ -588,6 +863,12 @@ Annotate:
 | `logit` | log₁₀(p/(1 − p)) | 0 < p < 1 |
 | `time` | seconds since 1970-01-01 UTC | dates and times |
 | `category` | category index | categories |
+| `genome` | position in bp (less the axis' `origin`) | the axis' `region` |
+
+The genome scale is linear, its limits the axis' `region` without padding, its tick labels
+in `unit` (bp, kb or Mb; `unit_in` puts the unit in the label or after each tick label),
+its automatic label the chromosome; genome series set it on an x axis without a scale
+([§9](#9-genome-tracks)).
 
 Values outside the domain are missing on that axis. The three logs place data
 identically; they differ in their ticks. Box and heatmap series with labels make their
@@ -633,11 +914,15 @@ grid only when its axis asks). `p.save` includes its twins.
   `"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.
 * `include_zero=True` extends automatic limits to 0 (linear and sqrt axes) before padding
-  and `nice`; `"auto"` does so where a series on the axis asks for it, following
+  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
   boxes, never category axes or heatmaps.
-* `nice=True` extends automatic limits (after padding) to the enclosing major ticks on
-  linear and log axes, as MATLAB and Vega-Lite do; given limits stay.
+* `snap` moves automatic limits (after padding) onto major ticks, on linear and log
+  axes; given limits stay. The default `("4%", "8%")` (`(back, out)`, `%` of the axis
+  length or px) extends a limit out to the next tick when it is within 8% of the axis,
+  or pulls it back to a tick it passed by at most 4% when that tick is still outside the
+  data; other limits stay as padded. `True` always extends to the enclosing ticks, as
+  MATLAB and Vega-Lite do; `False` leaves the padded limits.
 
 ### Ticks
 
@@ -675,52 +960,58 @@ or the plot's `spines` is set.
 <!-- settings:Axis -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `label` | — | Axis title: a string or rich content. |
+| `label` | — | Axis title: a string or rich content; `\n` starts a line in a row band. |
+| `label_position` | 'axis' | Where the label of a plot's y axis goes: `axis` (beside the tick labels); in a band left of the plot, lined up with the labels of the other plots of its grid column (row labels): `band` (rotated) or `left` (horizontal, right-aligned); `inside` (top left inside the axes). |
 | `label_font_size` | '1em' | Font size of the label; default: the base font size. Length; `%`: of the font size. |
-| `scale` | — | `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog`, `logit`, `time` or `category`; default: `category` for categorical series, `time` for dates, else `linear`. |
+| `label_weight` | 'normal' | Axis title weight: `normal`, `bold` or 1–1000. |
+| `label_style` | 'normal' | Axis title style: `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `label_color` | 'var(color)' | Axis title color. |
+| `scale` | — | `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog`, `logit`, `time`, `category` or `genome`; default: `category` for categorical series, `time` for dates, `genome` for genome series, else `linear`. |
+| `region` | — | Genome scale: the region drawn, its limits: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; genome series read it. |
+| `unit` | 'auto' | Genome scale: unit of the tick labels; `auto`: with ticks about a fifth of the span apart, the largest unit in which they are at least 1 apart and at most 1000, else the largest in which they are at most 1000 with at most 3 decimals, else bp. |
+| `unit_in` | 'label' | Genome scale: where the unit is written, in the axis label (`chr2 (Mb)`) or after each tick label (`500kb`). |
+| `origin` | — | The value drawn at 0 for the axis' series (a series' own `x_origin` wins): a number, or `"center"`, `"start"`, `"end"` of the region (genome scale), else of each series' range. Values are drawn at `(v − origin) × x_scale`; limits, ticks and decorations are in the drawn units. |
 | `linthresh` | 1.0 | Half-width of the linear region of a `symlog` axis. |
 | `tz` | — | Time zone of a time axis (a `tzinfo`); default: the zone of the first aware date, else naive (UTC). |
-| `limits` | 'auto' | `"auto"`, `"lo/hi"` (`min`, `max`, numbers, `q:F`) or `(lo, hi)`. |
-| `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. |
-| `auto_padding` | '5%' | The fraction `padding="auto"` adds on each side. Length. |
+| `limits` | 'auto' | `"auto"`, `"lo/hi"` or `[lo, hi]` (a tuple too); each side a number, `"min"`, `"max"`, `"q:F"` (a quantile), a date, or `"auto"`/`None`: `"0/max"` is `[0, "max"]`. |
+| `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. |
 | `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. |
-| `tick_format` | 'auto' | Number format: `auto`, `percent`, `sci`, `eng`, `si`, `int`, a format string or a function. |
+| `tick_format` | 'auto' | Number format: `auto`, `percent`, `sci`, `eng`, `si`, `int`, a format string or a function; on a genome axis also `chr:pos` (`chr2:143,250,000`). |
 | `tick_rotation` | 'auto' | Label rotation in degrees, or `"auto"` (45° when category labels overlap). Angle (bare: degrees). |
 | `max_ticks` | 'auto' | Most major ticks; `"auto"`: one per `tick_spacing` of axis length, at least 2, at most `auto_max_ticks`. |
-| `tick_spacing` | ('3em', '2em') | Space per automatic tick, in tick label font sizes, on horizontal and vertical axes. Length; `em` and `%`: of `tick_font_size`. |
-| `time_tick_spacing` | ('5em', '2.5em') | `tick_spacing` of time axes. Length; `em` and `%`: of `tick_font_size`. |
-| `tick_label_gap` | '0.6em' | Smallest gap between neighbouring tick labels side by side: fewer numeric ticks, or category labels rotated and thinned out, below it. Length; `em` and `%`: of `tick_font_size`. |
-| `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_font_size`. |
+| `tick_spacing` | ('3em', '2em') | Space per automatic tick, in tick label font sizes, on horizontal and vertical axes. Length; `em` and `%`: of `tick_label_font_size`. |
+| `time_tick_spacing` | ('5em', '2.5em') | `tick_spacing` of time axes. Length; `em` and `%`: of `tick_label_font_size`. |
+| `tick_label_gap` | '0.6em' | Smallest gap between neighbouring tick labels side by side: fewer numeric ticks, or category labels rotated and thinned out, below it. Length; `em` and `%`: of `tick_label_font_size`. |
+| `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` | 6.0 | Tick length. Length; `%`: of the axes side across the axis. |
+| `tick_length` | 5.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_font_size` | '1em' | Font size of tick labels. Length; `%`: of the font size. |
+| `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. |
 | `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. |
-| `tick_color` | 'var(color)' | Tick color. |
-| `tick_label_color` | 'var(color)' | Tick label color. |
-| `label_color` | 'var(color)' | Axis title color. |
-| `label_weight` | 'normal' | Axis title weight: `normal`, `bold` or 1–1000. |
-| `label_style` | 'normal' | Axis title style: `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `line_width` | 0.75 | 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). |
-| `tick_label_weight` | 'normal' | Tick label weight: `normal`, `bold` or 1–1000. |
 | `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. |
 | `spine_trim` | False | Axis line from the first to the last major tick only. |
-| `include_zero` | False | Extend automatic limits to 0 (linear and sqrt scales), before padding and `nice`: `True`, or `"auto"` where a series on the axis asks for it (Vega-Lite's rule: scatter axes, the value axis of lines, areas and boxes). |
+| `include_zero` | False | Extend automatic limits to 0 (linear and sqrt scales), before padding and `snap`: `True`, or `"auto"` where a series on the axis asks for it (Vega-Lite's rule: scatter axes, the value axis of lines, areas and boxes). |
 | `zero_line` | False | A line across the plot at 0. |
 | `zero_line_color` | 'var(line_color)' | Zero line color; default `line_color`. |
 | `zero_line_width` | 'var(line_width)' | Zero line width; default `line_width`. Length. |
-| `nice` | False | Extend automatic limits to the enclosing major ticks (linear and log scales). |
-| `line_width` | 0.75 | Axis line width. Length. |
+| `snap` | ('4%', '8%') | Automatic limits on major ticks (linear and log scales): `True`, out to the enclosing ticks; `(back, out)`, out to a tick within `out` (`%` of the axis), or back to one within `back` that is still outside the data; `False`: as padded. Length; `%`: of the axis range. |
 | `grid` | False | Major grid lines across the plot. |
 | `grid_color` | '#dddddd' | Grid line color. |
 | `grid_width` | 0.5 | Grid line width. Length. |
@@ -742,6 +1033,8 @@ or the plot's `spines` is set.
 | `prefix` | inherited ('') | Text before every number. |
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `TextStyle` (`label_`), `Stroke` (`tick_`), `TextStyle` (`tick_label_`), `Stroke` (`line_`), `Stroke` (`zero_line_`), `Stroke` (`grid_`), `Stroke` (`minor_grid_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ## 5. Series
@@ -750,17 +1043,56 @@ All series take `name`, `alpha`, `z`, `rasterize` and `simplify` (see [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.
 
+* **Layers.** A series is a preset of layers: each a stat (columns computed from the
+  data: bins, densities, quartiles, fits, contours…), a position (stack, dodge, jitter,
+  swarm, rows of intervals), and one of eight geoms that draws the columns (points,
+  paths, bands, rectangles, polygons, segments, cells, text). A box plot is rectangles,
+  segments and points from one box stat; it has one legend entry. Positions run once per
+  plot over all its series, before the axes are fitted.
+* **Orientation.** Every series with x and y data takes `orientation="horizontal"`
+  (scatter, line, fill, area, bar, hist, kde, ecdf, box, violin, strip, swarm, errorbar,
+  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
+  `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
+  are registered so (`plot.bigwig(…)`, …).
+
 * **Category slots.** Box and violin series, bar series, and strip and swarm series form
   three dodge groups: the series of a group that have a category split its slot (`width`)
   side by side, in call order; `dodge=False` overlays a series; `gap` leaves part of each
-  share empty (`"10%"`). `width` is in data units (`0.8` is 80 % of a category) or `%` of
-  the slot: one category, or the smallest gap between numeric `positions`. Stacked bars count as one, and so do split violins.
+  share empty (`"10%"`). `width` is a `%` of the slot (one category, or the smallest gap
+  between numeric `positions`), a length (px), or data units (`"0.8d"`). Stacked bars
+  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.
 * **Derived data.** Histograms, densities, ECDFs, violins, 2-D bins, contours and
-  regressions compute their data once (in C, by pdf_io's array helpers) and keep it until
+  regressions compute their data once (in C, by plot_io's kernels) and keep it until
   a setting changes; `series.stats` exposes 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`
+  makes bins of 10 (−5000…5000), and `x_extent="-5000/5000"` maps the series' smallest x
+  to −5000 and its largest to 5000 (replacing origin and scale). `"center"` is the middle
+  of the series' range, `"start"`/`"end"` its smallest/largest value. Limits, ticks and
+  decorations (`p.vline(0)`) are in the drawn units. An axis' `origin`
+  (`p.x_axis(origin="center")`, `fig.x_axis(…)` for every plot) applies to every series on
+  it that has no `x_origin` of its own (on a genome axis, `"center"` is the middle of its
+  region). Category axes ignore them, and they need a linear, time or genome axis.
+
+<!-- settings:Transforms -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `x_origin` | — | The x value drawn at 0: a number, `"center"` (the middle of the series' x range), `"start"` or `"end"` (its smallest or largest x); unset: the x axis' `origin`. Values are drawn at `(x − x_origin) × x_scale`. |
+| `x_scale` | 1.0 | Factor on x values after `x_origin` (e.g. bp per bin); default 1. |
+| `x_extent` | — | The span the series' x range is drawn over, `"lo/hi"` or `[lo, hi]`: its smallest x at `lo`, its largest at `hi`; replaces `x_origin` and `x_scale`. |
+| `y_origin` | — | The y value drawn at 0: a number, `"center"` (the middle of the series' y range), `"start"` or `"end"` (its smallest or largest y); unset: the y axis' `origin`. Values are drawn at `(y − y_origin) × y_scale`. |
+| `y_scale` | 1.0 | Factor on y values after `y_origin` (e.g. bp per bin); default 1. |
+| `y_extent` | — | The span the series' y range is drawn over, `"lo/hi"` or `[lo, hi]`: its smallest y at `lo`, its largest at `hi`; replaces `y_origin` and `y_scale`. |
+<!-- /settings -->
 
 ### Tables (`data=`)
 
@@ -774,7 +1106,7 @@ p = pl.Plot(data=df); p.scatter("a", "b")       # data inherited by the plot's s
 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`,
-`order`, `x_error`, `y_error`, `weights`, `positions`, `x`, `y` or `labels` names a
+`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
 the name is also a color). Axis titles default to the column names drawn on the axes,
@@ -802,7 +1134,7 @@ groups. Missing labels (`None`, NaN) form a `"nan"` group, or are dropped with
 `group_missing="drop"`. `set()` on the group applies to every member; `group[label]` (or
 an index) is one member; `labels` lists them. For box, violin, bar, strip and swarm the
 groups are dodged within each category slot. Densities (`"density"`) are computed per
-member, and `order` sorts within each member.
+member, and `draw_order` sorts within each member.
 
 ### Scatter
 
@@ -825,30 +1157,39 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `size` | 5.0 | 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. |
+| `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` | — | Outline: as the fill color. |
-| `edge_width` | 0.5 | Outline width. Length. |
-| `filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
+| `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. |
 | `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') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `size_map` | — | How numbers in `size` become sizes: a `SizeMap` (alias `smap`); without it, numbers are sizes in px. |
-| `size_legend` | True | With a `size_map`: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
-| `order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
+| `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` | — | The sizes numbers in `size` are drawn with: a `SizeMap` (alias `smap`); without it (or `size_axis`), numbers are sizes in px. |
+| `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). |
+| `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`. |
 | `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Marker`, `Font`.
 <!-- /settings -->
 
 ### Line
@@ -859,11 +1200,16 @@ pl.Line(x, y=None, plot=None, **settings)    # y 2-D: one line per row; x omitte
 
 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` does on Scatter; the line keeps `color`, and the legend's marker takes the
+gradient's middle color.
 
 * `interpolation`: `linear`; `step-pre`, `step-post`, `step-mid`; `monotone` (a cubic
   through every point that never overshoots, Fritsch–Carlson; `spline` where x is not
   monotonic); `spline` (centripetal Catmull–Rom, may overshoot). Each segment is one exact
-  Bézier, computed on the page after the axis scales, by pdf_io in C. Steps and curves
+  Bézier, computed on the page after the axis scales, by vec_io in C. Steps and curves
   are not decimated by `simplify`.
 * `missing`: `break` (default) ends a run at a missing value (NaN, `None`, or outside the
   axis scale's domain); runs are drawn on their own and a one-point run draws nothing.
@@ -873,33 +1219,40 @@ Named line styles scale with the width. Markers (`marker`, `marker_size`,
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Line color; default: the next palette color. |
-| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_width` | inherited (0.75) | Line width. Length. |
 | `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list; named styles scale with the 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. |
 | `cap` | 'butt' | Line cap. |
 | `join` | 'round' | Line join. |
+| `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. |
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 5.0 | 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. |
+| `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` | — | Outline: as the fill color. |
-| `marker_edge_width` | 0.5 | Outline width. Length. |
-| `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
+| `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. |
 | `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. |
 | `x_error` | — | Horizontal error bars at the points. |
 | `y_error` | — | Vertical error bars at the points. |
 | `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
 
 ### Fill
@@ -909,14 +1262,17 @@ pl.Fill(x, y1, y2=0, plot=None, **settings)   # y1 may be two rows [upper, lower
 ```
 
 `interpolation` and `missing` work as for lines, on both edges (a point is missing when
-x, y1 or y2 is), so a band with the settings of its line matches it. With
-`orientation="horizontal"`, curves are drawn as straight segments.
+x, y1 or y2 is), so a band with the settings of its line matches it, horizontal ones
+included (`fill(y, x1, x2, orientation="horizontal")`: the curves run along y).
+`color_below` colors the parts where `y1` is below `y2` (a difference between two curves,
+each side in its color).
 
 <!-- settings:Fill -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Fill color; default: the next palette color. |
-| `alpha` | 'calc(0.3 * var(alpha))' | Opacity; default 0.3. |
+| `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. |
 | `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). |
@@ -925,13 +1281,15 @@ x, y1 or y2 is), so a band with the settings of its line matches it. With
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
 
 ### Box
@@ -952,44 +1310,51 @@ category.
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Box fill: a color, one per box (list or dict by category), or numbers per box (list or dict) mapped through `color_map`; default: the next palette color. |
-| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `edge_color` | 'black' | 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). |
-| `whisker_color` | — | Whisker and cap color; default `edge_color`. |
-| `whisker_style` | 'solid' | Whisker line style: `solid`, `dashed`, `dotted`, `dashdot` or a dash list (caps stay solid). Length. |
+| `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. |
+| `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. |
+| `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. |
 | `median_color` | — | Median line color; default `edge_color`. |
-| `median_width` | 1.5 | Median line width. Length. |
-| `width` | 0.8 | Width of a category's slot (category units). Length; bare numbers: data units. |
-| `cap_length` | '50%' | Whisker cap width (`%` of the box width). Length. |
+| `median_width` | 'calc(3 * var(edge_width))' | Median line width. Length. |
+| `max_width` | '60%' | 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%' | Box 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. |
+| `cap_length` | '50%' | Whisker cap width (`%` of the box width). Length; `%`: of the box width. |
 | `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`. |
 | `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`). |
 | `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
 | `dodge` | True | Box and violin series sharing a category share its slot side by side; `False` overlays them. |
-| `gap` | '10%' | Fraction of each box's part of a shared slot left empty. Length. |
+| `gap` | '10%' | Fraction of each box's part of a shared slot left empty. Length; `%`: of each series' part of a shared slot. |
 | `categories` | — | Category names of a list of arrays. |
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 4.0 | 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. |
-| `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. |
-| `marker_edge_width` | 0.5 | Outline width. Length. |
-| `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
+| `marker_size` | 3.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
+| `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. |
 | `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke` (`edge_`), `Stroke` (`whisker_`), `Stroke` (`median_`), `FillStyle`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
 
 ### Heatmap
@@ -1000,34 +1365,35 @@ pl.Heatmap(values, x=None, y=None, plot=None, **settings)
 
 `values` is 2-D, row 0 first; a 3-D `(h, w, 3|4)` grid is drawn as colors. `x`/`y`:
 `None` (cell indices), labels (a category axis), n cell centres or n + 1 edges (uneven
-spacing and any axis scale allowed). `cmap` takes a `ColorMap` or what `ColorMap()`
-takes; `color_limits` and `color_scale` override its limits and scale for this series.
-`labels=True` writes each value, formatted by `label_format` (any
+spacing and any axis scale allowed). `color_map` (alias `cmap`), `color_limits` and
+`color_scale` configure the series' [color axis](#6-color-and-size-axes).
+`value_labels=True` writes each value, formatted by `value_label_format` (any
 [number format](#number-formats); `"auto"`: 3 significant digits, the same decimals for
 all cells), in black or white, whichever contrasts more (at most 2,500 cells unless
-`labels="all"`).
+`value_labels="all"`). `kind`: `image`, `cells` or `smooth`.
 
 <!-- settings:Heatmap -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `color_map` | inherited ('rainbow_llhh') | A `ColorMap`, a map name or a list of colors. |
-| `color_limits` | — | Override of the map's limits for this series. |
-| `color_scale` | — | Override of the map's scale. |
-| `mode` | 'image' | `image` (one image pixel per cell), `cells` (rectangles) or `smooth` (interpolated). |
+| `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. |
+| `kind` | 'image' | `image` (one image pixel per cell), `cells` (rectangles) or `smooth` (interpolated). |
 | `nan_color` | — | Color of missing cells; default: the map's `bad` (transparent). |
 | `origin` | 'top' | `top`: row 0 at the top (y axis inverted); `bottom`: at the bottom. |
-| `labels` | False | Write each cell's value (`"all"` above 2,500 cells). |
-| `label_format` | 'auto' | Number format of cell labels (`auto`: 3 significant digits, the same decimals for all cells). |
-| `label_font_size` | '0.9em' | Font size of cell labels. Length; `%`: of the font size. |
+| `value_labels` | False | Write each cell's value (`"all"` above 2,500 cells). |
+| `value_label_format` | 'auto' | Number format of cell labels (`auto`: 3 significant digits, the same decimals for all cells). |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
@@ -1037,6 +1403,8 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 | `prefix` | inherited ('') | Text before every number. |
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `TextStyle` (`value_label_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ### Bar
@@ -1045,35 +1413,41 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 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, …). `labels` writes the values outside, inside or at the centre of the bars, formatted by `label_format`; `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` 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"`).
 
 <!-- settings:Bar -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Bar fill: a color, one per bar (list or dict by category), or numbers per bar (list or dict) mapped through `color_map`; default: the next palette color. |
-| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `edge_color` | — | Outline color; default none. |
-| `edge_width` | 0.0 | Outline width. Length. |
-| `width` | 0.8 | Bar width: a category's slot (category units) or data units (a `timedelta` on time axes). Length; bare numbers: data units. |
+| `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. |
+| `edge_color` | 'series' | Outline color: a color, `"series"` (each bar's own color, at `alpha`) 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`. |
+| `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. |
 | `bottom` | 0.0 | Base of the bars: a value or one per bar. |
 | `orientation` | 'vertical' | `vertical` (bars rise from the x axis) or `horizontal`. |
 | `stack` | False | `True`: on top of the previous stacked bars of the plot; `"normalize"`: stacks scaled to 1. |
 | `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. |
+| `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_color` | '#333333' | Error bar color. |
 | `error_width` | 0.75 | Error bar line width. Length. |
-| `labels` | False | Value labels: `True`/`"outside"`, `"inside"`, `"center"`. |
-| `label_format` | 'auto' | Number format of the labels. |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
@@ -1083,6 +1457,8 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `prefix` | inherited ('') | Text before every number. |
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`edge_`), `FillStyle`, `Stroke` (`error_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ### Hist
@@ -1101,7 +1477,7 @@ pl.Hist(values, plot=None, **settings)
 | `weights` | — | A weight per value (per set for several sets). |
 | `stat` | 'count' | `count`, `density` (area 1), `probability`, `percent` or `frequency` (count per unit). |
 | `cumulative` | False | Accumulate the bins. |
-| `kind` | 'bar' | `bar` (adjacent bars), `step` (outline) or `stepfilled`. |
+| `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). |
@@ -1109,19 +1485,20 @@ pl.Hist(values, plot=None, **settings)
 | `color` | — | Fill color, or one per set; default palette colors. |
 | `edge_color` | — | Bar outline color; default none. |
 | `edge_width` | 0.0 | Bar outline width. Length. |
-| `line_color` | — | Step line color; default the fill color. |
-| `line_width` | inherited (1.25) | Step line width. Length. |
+| `line_color` | — | Step and outline color; default each set's color. |
+| `line_width` | inherited (0.75) | 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. |
 | `saturation` | 1.0 | Saturation of the fills. |
-| `labels` | False | Value labels on bars. |
-| `label_format` | 'auto' | Number format of the labels. |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
@@ -1131,6 +1508,8 @@ pl.Hist(values, plot=None, **settings)
 | `prefix` | inherited ('') | Text before every number. |
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`edge_`), `Stroke` (`line_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ### Kde
@@ -1139,7 +1518,7 @@ pl.Hist(values, plot=None, **settings)
 pl.Kde(values, plot=None, **settings)
 ```
 
-A Gaussian kernel density of each set on a common grid of `grid` points, extending `cut` bandwidths past the data (within `clip`). `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`). `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`.
 
 <!-- settings:Kde -->
 | Setting | Default | Meaning |
@@ -1147,82 +1526,57 @@ A Gaussian kernel density of each set on a common grid of `grid` points, extendi
 | `bandwidth` | 'scott' | `scott`, `silverman`, or a bandwidth in data units. |
 | `adjust` | 1.0 | Factor applied to the bandwidth. |
 | `cut` | 3.0 | The curve extends this many bandwidths past the data. |
-| `clip` | — | Limits of the curve. |
-| `grid` | 512 | Number of points of the curve. |
+| `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. |
+| `fill` | False | Fill under the curve: an opacity of its color, `True` (0.25), a color, or `False` (stacked curves: 0.25). |
 | `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. |
-| `alpha` | 'auto' | Fill opacity; `"auto"`: 0.25, 1 when stacked. |
-| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_width` | inherited (0.75) | 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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `FillStyle`, `Stroke`, `Font`.
 <!-- /settings -->
 
 ### Kde2d
 
 ```python
-p.kde(x, y, levels=10, filled=False, thresh=0.05, **settings)    # or pl.Kde(x, y), pl.Kde2d(x, y)
+p.kde(x, y, levels=10, fill=False, thresh=0.05, **settings)    # or pl.Kde(x, y), pl.Kde2d(x, y)
 ```
 
 Density contours of points (seaborn's `kdeplot(x=, y=)`): the 2-D Gaussian density
 (bandwidth as [`Density`](#point-density): scipy's covariance times Scott's factor, or
-Silverman's, a number or a matrix, times `adjust`) on a `gridsize` × `gridsize` grid over
+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 series color (the
-next palette color) unless `color_map` is set; `filled=True` colors the bands through
+outermost) up; 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,
 labels, colorbar).
 
 <!-- settings:Kde2d -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `filled` | False | Fill the bands between levels. |
-| `lines` | True | Draw the iso-lines. |
-| `color_map` | inherited ('rainbow_llhh') | Color map of the levels. |
-| `colors` | — | Line color, or one per level, instead of the map. |
-| `line_width` | 'calc(0.6 * var(line_width))' | 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. |
-| `labels` | False | Write the level values on the lines. |
-| `label_format` | 'auto' | Number format of the labels. |
-| `label_font_size` | '0.8em' | Label font size. Length; `%`: of the font size. |
-| `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`: pdf_io's `simplify`. |
-| `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. |
-| `text_color` | inherited ('black') | Text color. |
-| `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`. |
-| `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). |
-| `prefix` | inherited ('') | Text before every number. |
-| `suffix` | inherited ('') | Text after every number. |
-| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
 | `levels` | 10 | A number of iso-proportion levels (contour k of n encloses k/n of the mass, above `thresh`), 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. |
 | `cut` | 3.0 | Grid extends this many bandwidths past the data. |
-| `gridsize` | 128 | Grid points per side. |
-| `color` | — | Line color of unfilled contours without a `color_map`; default the next palette color. |
+| `points` | 128 | Grid points per side. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 <!-- /settings -->
 
@@ -1242,19 +1596,21 @@ A step line through the sorted values of each set: `stat` `proportion`, `count`
 | `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 (1.25) | Line width. Length. |
+| `line_width` | inherited (0.75) | 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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke`, `Font`.
 <!-- /settings -->
 
 ### Violin
@@ -1263,39 +1619,46 @@ A step line through the sorted values of each set: `stat` `proportion`, `count`
 pl.Violin(values, positions=None, plot=None, **settings)
 ```
 
-`values` as box plots take them. Each violin is the density of its category, mirrored; `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; `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.
 
 <!-- settings:Violin -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Fill: a color, one per violin (list or dict by category), or numbers per violin mapped through `color_map`; default the next palette color. |
-| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `edge_color` | '#333333' | Outline and inner color. |
+| `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. |
+| `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. |
 | `saturation` | 1.0 | Saturation of the fills. |
-| `alpha` | 1.0 | Fill opacity. |
-| `width` | 0.8 | Width of a category's slot. Length; bare numbers: data units. |
+| `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`. |
+| `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. |
 | `adjust` | 1.0 | Factor applied to the bandwidth. |
 | `cut` | 2.0 | The density extends this many bandwidths past the data. |
-| `grid` | 512 | Points per violin outline. |
-| `scale` | 'area' | `area`: equal areas; `count`: area proportional to the number of values; `width`: equal widths. |
+| `points` | 512 | Points per violin outline. |
+| `width_scale` | 'area' | `area`: equal areas; `count`: area proportional to the number of values; `width`: equal widths. |
 | `inner` | 'box' | Inside each violin: `box` (a thin box, whiskers and a median dot), `quartiles` (dashed lines), `points`, or `False` (nothing). |
 | `split` | False | Two violin series share each slot as facing halves. |
 | `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
 | `dodge` | True | Violin and box series sharing a category share its slot side by side; `False` overlays them. |
-| `gap` | '10%' | Fraction of each part of a shared slot left empty. Length. |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke` (`edge_`), `FillStyle`, `Font`.
 <!-- /settings -->
 
 ### Strip and swarm
@@ -1311,35 +1674,44 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `size` | 5.0 | 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. |
+| `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` | — | Outline: as the fill color. |
-| `edge_width` | 0.5 | Outline width. Length. |
-| `filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
+| `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. |
 | `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') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `size_map` | — | How numbers in `size` become sizes: a `SizeMap` (alias `smap`); without it, numbers are sizes in px. |
-| `size_legend` | True | With a `size_map`: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
+| `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` | — | The sizes numbers in `size` are drawn with: a `SizeMap` (alias `smap`); without it (or `size_axis`), numbers are sizes in px. |
+| `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). |
 | `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
-| `width` | 0.8 | Width of a category's slot. Length; bare numbers: data units. |
+| `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. |
 | `dodge` | True | Point series sharing a category share its slot side by side; `False` overlays them. |
-| `gap` | 0.0 | Fraction of each part of a shared slot left empty. Length. |
+| `gap` | 0.0 | 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. |
-| `jitter` | '10%' | Half-width of the jitter (`%` of the slot width). Length. |
+| `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. |
-| `order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Marker`, `Font`.
 <!-- /settings -->
 
 ### Area
@@ -1356,21 +1728,24 @@ Layers (rows of `ys`, or a dict `{name: values}`, one legend entry each) stacked
 | `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.85 | Opacity of the fills. |
-| `edge_color` | — | Outline color of each layer's top; default none. |
+| `alpha` | 0.25 | Opacity of the fills. |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
 
 ### Errorbar
@@ -1379,36 +1754,43 @@ Layers (rows of `ys`, or a dict `{name: values}`, one legend entry each) stacked
 pl.Errorbar(x, y, plot=None, **settings)
 ```
 
-Error bars on their own (markers only with `marker=`); `y_error_style="band"` fills the band between the y error ends instead.
+Error bars on their own (markers only with `marker=`); `y_error_style="band"` fills the band between the y error ends instead. Numbers in `marker_color` map through the series' color axis, as on [Line](#line).
 
 <!-- settings:Errorbar -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | — | Marker at the points; default none. |
-| `marker_size` | 5.0 | 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. |
+| `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` | — | Outline: as the fill color. |
-| `marker_edge_width` | 0.0 | Outline width. Length. |
-| `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
+| `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. |
 | `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 (1.25) | Bar width. Length. |
-| `cap_length` | 4.0 | Cap width (`data`: in data units across the bar); 0: no caps. Length. |
+| `line_width` | inherited (0.75) | 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. |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Marker` (`marker_`), `Font`.
 <!-- /settings -->
 
 ### Stem
@@ -1417,20 +1799,24 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 pl.Stem(x, y=None, plot=None, **settings)
 ```
 
-Stems from `baseline` to each value with a marker (lollipops), and a baseline line.
+Stems from `baseline` to each value with a marker (lollipops), and a baseline line. Numbers in `marker_color` map through the series' color axis, as on [Line](#line).
 
 <!-- settings:Stem -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 7.0 | 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. |
+| `marker_size` | 5.0 | 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` | — | Outline: as the fill color. |
-| `marker_edge_width` | 0.0 | Outline width. Length. |
-| `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
+| `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. |
 | `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 (1.25) | Stem width. Length. |
+| `line_width` | inherited (0.75) | 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. |
@@ -1439,13 +1825,15 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 | `alpha` | 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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Marker` (`marker_`), `Stroke` (`baseline_`), `Font`.
 <!-- /settings -->
 
 ### Regression
@@ -1454,7 +1842,7 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 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. The points are drawn too unless `scatter=False` (marker settings with the `marker_` prefix). `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. 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 |
@@ -1465,30 +1853,37 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `ci` | 95.0 | Confidence level of the band (%); `None`: no band. |
 | `logx` | False | Fit y against log(x) (x > 0). |
 | `scatter` | True | Draw the points too. |
-| `truncate` | True | Draw the fit over the data range only (`False`: over the axis range). |
+| `range` | — | x range of the fitted polynomial (and band); default the data range. |
 | `points` | 100 | Points of the fitted curve. |
 | `color` | — | Line, band and point color; default the next palette color. |
-| `line_width` | 'calc(1.4 * var(line_width))' | Line width; default 1.4 × the plot's. Length. |
+| `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. |
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 5.0 | 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. |
+| `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` | — | Outline: as the fill color. |
-| `marker_edge_width` | 0.0 | Outline width. Length. |
-| `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
+| `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. |
 | `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. |
+| `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. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 <!-- /settings -->
 
 ### Hist2d
@@ -1502,32 +1897,6 @@ Counts in rectangular bins (even on the axis scales), drawn as a heatmap with th
 <!-- settings:Hist2d -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `color_map` | inherited ('rainbow_llhh') | A `ColorMap`, a map name or a list of colors. |
-| `color_limits` | — | Override of the map's limits for this series. |
-| `color_scale` | — | Override of the map's scale. |
-| `mode` | 'image' | `image` (one image pixel per cell), `cells` (rectangles) or `smooth` (interpolated). |
-| `nan_color` | — | Color of missing cells; default: the map's `bad` (transparent). |
-| `labels` | False | Write each cell's value (`"all"` above 2,500 cells). |
-| `label_format` | 'auto' | Number format of cell labels (`auto`: 3 significant digits, the same decimals for all cells). |
-| `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. |
-| `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`: pdf_io's `simplify`. |
-| `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. |
-| `text_color` | inherited ('black') | Text color. |
-| `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`. |
-| `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). |
-| `prefix` | inherited ('') | Text before every number. |
-| `suffix` | inherited ('') | Text after every number. |
-| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
 | `bins` | ('auto', 'auto') | Bins of both axes, or `(x bins, y bins)`: counts, edges or rules (as `Hist`). |
 | `range` | — | `((x0, x1), (y0, y1))`; default the data range. |
 | `weights` | — | A weight per point. |
@@ -1542,21 +1911,23 @@ Counts in rectangular bins (even on the axis scales), drawn as a heatmap with th
 pl.Hexbin(x, y, plot=None, **settings)
 ```
 
-Counts in regular hexagons: `gridsize` hexagons across the axes width, on a lattice laid out
-in page units once the axes are placed, so the hexagons tile exactly whatever the axes'
-aspect (and the counts depend on it). Points outside the axes are not counted. Colored by
-`cmap`; a colorbar source.
+Counts in regular hexagons: `bins` hexagons across the axes width, on a lattice laid out
+in page units for the axes the layout places, so the hexagons tile exactly whatever the
+axes' aspect. The counts depend on the axes, and the color axis on the counts: the layout
+counts again when a round places the axes differently ([layout](#layout)). Points outside
+the axes are not counted. Colored by `cmap`; a colorbar source.
 
 <!-- settings:Hexbin -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `gridsize` | 30 | Hexagons across the axes width. |
+| `bins` | 30 | Hexagons across the axes width. |
 | `weights` | — | A weight per point (sums). |
 | `stat` | 'count' | `count`, `probability` or `percent`. |
 | `min_count` | 1.0 | Hexagons below this count are not drawn. |
-| `color_map` | inherited ('rainbow_llhh') | A `ColorMap`, a map name or colors. |
-| `color_limits` | — | Override of the map's limits. |
-| `color_scale` | — | Override of the map's scale. |
+| `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. |
 | `edge_color` | — | Hexagon outline color; default none. |
 | `edge_width` | 0.0 | Outline width. Length. |
 | `colorbar` | False | Attach a colorbar to the plot. |
@@ -1564,13 +1935,15 @@ aspect (and the counts depend on it). Points outside the axes are not counted. C
 | `alpha` | 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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
+
+Groups: `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
 
 ### Contour
@@ -1579,31 +1952,34 @@ aspect (and the counts depend on it). Points outside the axes are not counted. C
 pl.Contour(values, x=None, y=None, plot=None, **settings)
 ```
 
-Iso-lines (`lines`) and filled bands (`filled`) of a grid at nodes `x`/`y`. `levels`: a number of nice values over the data, or the values. Lines take the map's colors, or `colors`; `negative_style` dashes negative levels drawn in one color; `labels` writes the levels on the lines. Bands are colored by their middle value.
+Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `levels`: a number of nice values over the data, or the values. Lines take the map's colors, or `palette` (one color, or colors per level in turn: a list or a palette name); `negative_style` dashes negative levels drawn in one color; `value_labels` writes the levels on the lines. Bands are colored by their middle value.
 
 <!-- settings:Contour -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `levels` | 10 | A number of levels (nice values over the data) or the level values. |
-| `filled` | False | Fill the bands between levels. |
+| `fill` | False | Fill the bands between levels: `True`, an opacity (0–1, times `alpha`), or `False`. |
 | `lines` | True | Draw the iso-lines. |
-| `color_map` | inherited ('rainbow_llhh') | Color map of the levels. |
-| `colors` | — | Line color, or one per level, instead of the map. |
-| `line_width` | 'calc(0.6 * var(line_width))' | Line width; default 0.6 × the plot's. Length. |
+| `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. |
+| `palette` | — | Line color, or colors taken per level in turn (a list or a palette name), instead of the map. |
+| `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. |
-| `labels` | False | Write the level values on the lines. |
-| `label_format` | 'auto' | Number format of the labels. |
-| `label_font_size` | '0.8em' | Label font size. Length; `%`: of the font size. |
+| `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. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 | `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`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
@@ -1613,6 +1989,8 @@ Iso-lines (`lines`) and filled bands (`filled`) of a grid at nodes `x`/`y`. `lev
 | `prefix` | inherited ('') | Text before every number. |
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `FillStyle`, `Stroke`, `TextStyle` (`value_label_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
 ### Pie
@@ -1621,32 +1999,34 @@ Iso-lines (`lines`) and filled bands (`filled`) of a grid at nodes `x`/`y`. `lev
 pl.Pie(values, plot=None, **settings)
 ```
 
-Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a plot drawn without axes (`Plot.axes=False`, aspect 1). `hole` makes a donut (`"40%"` of the radius), `explode` moves wedges out (`%` of the radius, one value or one per wedge). Names go outside (pushed apart so that they do not overlap), inside, or into the legend (`label_position="none"`, the legend then outside right); `value_labels` writes percents or values inside, or outside with a leader line when a wedge is too thin.
+Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a plot drawn without axes (`Plot.axes=False`, aspect 1). `hole` makes a donut (`"40%"` of the radius), `explode` moves wedges out (`%` of the radius, one value or one per wedge). Names go outside (pushed apart so that they do not overlap), inside, or into the legend (`name_position="none"`, the legend then outside right); `palette` colors them in turn; `value_labels` writes percents or values inside, or outside with a leader line when a wedge is too thin.
 
 <!-- settings:Pie -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `labels` | — | Wedge names (default: the dict's keys). |
-| `colors` | — | One color per wedge; default palette colors. |
+| `names` | — | Wedge names (default: the dict's keys). |
+| `palette` | — | Wedge colors, taken in turn: a list of colors or a palette name; default the plot's palette. |
 | `start` | 90.0 | Angle where the first wedge starts (degrees, 0: 3 o'clock, 90: 12 o'clock). Angle (bare: degrees). |
 | `counterclockwise` | True | Direction of the wedges. |
-| `hole` | 0.0 | Radius of the hole (`%` of the radius): a donut. Length. |
-| `explode` | — | Offset of the wedges from the centre (`%` of the radius): one value or one per wedge. Length. |
+| `hole` | 0.0 | Radius of the hole (`%` of the radius): a donut. Length; `%`: of the radius. |
+| `explode` | — | Offset of the wedges from the centre (`%` of the radius): one value or one per wedge. Length; `%`: of the radius. |
 | `sort` | False | Sort the wedges by decreasing value. |
-| `label_position` | 'outside' | Where the names go: `outside`, `inside` or `none` (in the legend instead). |
+| `name_position` | 'outside' | Where the names go: `outside`, `inside` or `none` (in the legend instead). |
 | `value_labels` | False | Write each wedge's `percent` or `value` inside it (outside, with a leader line, when it does not fit). |
 | `label_spacing` | '1.25em' | Smallest distance between outside labels on a side. Length; `%`: of the font size. |
-| `label_format` | 'auto' | Number format of the value labels (percentages: of 100). |
-| `edge_color` | 'white' | Wedge outline color; `none`: no outline. |
+| `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`. |
+| `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. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
-| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
+| `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. |
-| `text_color` | inherited ('black') | Text color. |
 | `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`. |
@@ -1656,65 +2036,122 @@ Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a pl
 | `prefix` | inherited ('') | Text before every number. |
 | `suffix` | inherited ('') | Text after every number. |
 | `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`edge_`), `FillStyle`, `Font`, `NumberFormat`.
+<!-- /settings -->
+
+## 6. Color and size axes
+
+Numbers given as colors (per point, per cell, per category, or a density) go through a
+**color axis** before they become colors, as positions go through an x axis: its scale
+and limits take each value to [0, 1], and its gradient (a `ColorMap`) gives the color.
+Sizes go through a **size axis** the same way, with a `SizeMap` (diameters) in place of
+the gradient. A colorbar is the guide of a color axis, a size key that of a size axis.
+
+```python
+h = p.heatmap(v, cmap="magma", color_limits="q:0.01/q:0.99", color_scale="log")
+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 = 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
+```
+
+* **Own axes.** A series that maps values has its own color axis, `series.color_axis`
+  (and size axis, `series.size_axis`). Its `scale` is the series' `color_scale`, its
+  `limits` the series' `color_limits` (axis syntax: `"auto"`, the values' range;
+  `"0/max"`, `"q:0.01/q:0.99"`, `[lo, hi]`), its gradient the series' `color_map`
+  (inherited: the plot's, the figure's, the style's). Its other settings (ticks,
+  `tick_format`, `label`, fonts) are drawn by its colorbar. A `scale` or `limits` set on
+  the axis itself wins over the series' settings.
+* **Shared axes.** `fig.color_axis(**settings)` (`fig.size_axis(**settings)`) makes an
+  axis that series take as `color_axis=` (`size_axis=`). It holds the gradient
+  (`color_map`; sizes: `size_map`), the scale and the limits; its automatic limits cover
+  every series using it, and those series take no `color_map`, `color_limits` or
+  `color_scale` of their own (an error). A `pl.ColorAxis(**settings)` made alone joins
+  the figure of the first series given it. The members of a `group=` call share one axis
+  of each kind.
+* **`share_color`.** The figure's `share_color` (`False`, `True`/`"all"`, `"col"` or
+  `"row"`, as `share_x`) makes the own color axes of each group's plots one axis: limits
+  over all their values; one `color_limits` (or scale) applies to the group, two
+  different ones are an error. Each series keeps its gradient. Facet figures share
+  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"`).
+* **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).
+
+Color and size axes have the settings of [axes](#4-axes); these differ:
+
+<!-- settings:ColorAxis -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `scale` | — | Scale of the mapped values: `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog` or `logit`; default `linear`. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+<!-- /settings -->
+
+<!-- settings:SizeAxis -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `scale` | — | Scale of the mapped values: `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog` or `logit`; default `linear`. |
+| `size_map` | — | The sizes: a `SizeMap` or a pair of diameters; default `SizeMap()`. |
 <!-- /settings -->
 
-## 6. Colorbars
+### 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                                      # an Axis: ticks, labels, format
+cb.axis                                      # the color axis shown
 ```
 
-`source` is a heatmap, a series with a `ColorMap`, or a `ColorMap` (shared by several
-series, whose `"auto"` limits then cover all of them). 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 can be given directly:
-`p.colorbar(h, label="z", tick_format="{:.0%}")`.
+`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.
 
 <!-- settings:Colorbar -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `position` | 'right' | Side of the plot an attached bar takes. |
-| `orientation` | 'auto' | Bar direction; default: vertical, or horizontal for bars attached at the top or bottom. |
-| `thickness` | 13.0 | Bar thickness (`%` of the attached axes side across it). Length. |
-| `length` | '100%' | Bar length as a fraction of the axes side (attached bars). Length. |
-| `pad` | 11.0 | Gap between the axes and an attached bar. Length. |
-| `label` | — | Bar label: a string or rich content. |
-| `extend` | 'auto' | Triangular ends in the under/over colors: `auto` shows them when the limits clip the data. |
+| `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. |
+| `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. |
 | `frame_color` | '#666666' | Outline color. |
 | `frame_width` | 0.5 | Outline width. Length. |
-| `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_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`. |
-| `text_color` | inherited ('black') | Text color. |
-| `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). |
-| `prefix` | inherited ('') | Text before every number. |
-| `suffix` | inherited ('') | Text after every number. |
-| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`frame_`).
 <!-- /settings -->
 
 ## 7. Colors, maps and markers
 
 ### Colors and palette
 
-Colors are anything pdf_io accepts (CSS names, `#hex`, `(r, g, b[, a])` floats,
+Colors are anything vec_io accepts (CSS names, `#hex`, `(r, g, b[, a])` floats,
 `CMYK`, `Spot`) or `"C0"`, `"C1"`, … for palette entries; `"none"` paints nothing. The
-default palette `pl.PALETTE` (`"okabe_ito"`) is Okabe–Ito's eight colorblind-safe colors
-plus indigo and dark brown, chosen as the pair farthest from every other color (in Oklab)
-under normal and simulated protan, deutan and tritan vision.
+default palette (`"tab10_custom"`, `plot_io.color.palettes.PALETTE`) is tab10's ten hues as named colors: sky,
+amber, emerald, rose, purple 0.4, yellow 0.7, pink 0.4, gray, lime, cyan.
 
 `palette` takes a `pl.Palette`, a registered name (`"tab10"`; `"tab10_r"` reversed), a
 list of colors (or one comma-separated string: `"red, teal 0.7"`), or a function `n -> colors`, called with the number of series of the plot
 that take a palette color.
 
 ```python
-pl.Palette(colors="okabe_ito", name=None)    # a name, colors, a Palette or n -> colors
+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()
 ```
@@ -1730,7 +2167,8 @@ parts: `palette=pl.ColorMap("viridis").to_palette(5)` for ordered categories.
 
 | Palette | Colors |
 |---|---|
-| `okabe_ito` | plot_io's default (10) |
+| `tab10_custom` | plot_io's default: tab10's hues as named colors (10) |
+| `okabe_ito` | Okabe–Ito's eight colorblind-safe colors plus indigo and dark brown, chosen as the pair farthest from every other color (in Oklab) under normal and simulated protan, deutan and tritan vision (10) |
 | `tab10` | matplotlib ≥ 2.0, d3's category10 (10) |
 | `matplotlib_classic` | matplotlib 1.x: b, g, r, c, m, y, k (7) |
 | `tableau10` | Vega-Lite's default (10) |
@@ -1750,9 +2188,8 @@ parts: `palette=pl.ColorMap("viridis").to_palette(5)` for ordered categories.
 ### Color maps
 
 ```python
-pl.ColorMap(colors="rainbow_llhh", positions=None, limits="auto", scale="linear",
-            under=None, over=None, bad=None, space=None, name=None, interpolation=None,
-            widen_colors=1, widen_sides=1.0)
+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()
 ```
@@ -1760,15 +2197,14 @@ pl.color_map_names()
 | Member | |
 |---|---|
 | `colors` | a name (`viridis`, `magma`, `inferno`, `plasma`, `cividis`, `coolwarm`, `grey`, `rocket`, `mako`, `flare`, `crest`, `vlag`, `icefire`, `jet`, `parula`, `turbo`, `ggplot2`, the rainbows, ColorBrewer's and Crameri's maps below, in any case (`"RdBu"`, `"batlowK"`); `_r` reverses), a list of colors (evenly spaced or at `positions`; or one string, comma-separated: `"violet 0.4, sky 0.4, green 0.4"`), a `ColorMap` (copied) or a function `t -> color` |
-| `limits`, `scale` | axis syntax, applied to the mapped values; `"auto"` covers every series using the map |
-| `under`, `over`, `bad` | colors below/above the limits (default: the end colors) and of missing values (default: transparent) |
+| `under`, `over`, `bad` | colors below 0 and above 1, past the color axis' limits (default: the end colors), and of missing values (default: transparent) |
 | `space` | interpolation between the colors: `"oklab"` (default, for every map: perceptually even) or `"srgb"` |
-| `interpolation` | `"linear"` (default): between neighboring colors; `"nearest"`: equal steps, one per color (`n` colors, `n` bins; with `positions`, each step starts at its position); `"smooth"`: a Bézier curve with the colors as control points, through the first and last only (no `positions`); `"spline"`: a monotone cubic curve through every color (PCHIP in Oklab: no overshoot between colors) |
+| `interpolation` | `"linear"` (default): between neighboring colors; `"nearest"`: equal steps, one per color (`n` colors, `n` bins; with `positions`, each step starts at its position; a value on an edge takes the upper step); `"smooth"`: a Bézier curve with the colors as control points, through the first and last only (no `positions`); `"spline"`: a monotone cubic curve through every color (PCHIP in Oklab: no overshoot between colors) |
 | `widen_colors`, `widen_sides` | each inner color of a list repeated `widen_colors` times, each end color `round(widen_sides × widen_colors)` times: wider bands around the colors |
-| `cm(t)`, `colors_at(ts)` | color at t ∈ [0, 1]; bulk colors (C) |
+| `cm(t)`, `colors_at(ts)` | color at t ∈ [0, 1]; bulk colors (C: continuous maps through a table of 4,096 colors, steps exactly) |
+| `table(n)`, `cells(values, lo, hi, mode)` | n colors sampled evenly; what heatmap cells hand vec_io's `draw_cells` (C): palette indices into `table(255)` (`table(253)` plus the under and over colors), or for `smooth` positions along `table(256)` (steps: the step colors and their bounds) |
 | `reversed()`, `resampled(n)`, `truncated(lo, hi)`, `with_extremes(…)` | copies: reversed; n flat steps; a part stretched to [0, 1]; new extremes |
 | `to_palette(n)` | a `Palette` of `n` colors sampled at the centers of `n` equal parts |
-| `to_pdf_io()` | the equivalent pdf_io color map (maps with fewer than 256 colors as 256 sRGB stops) |
 
 Bundled data: viridis, magma, inferno and plasma by van der Walt and Smith (CC0); cividis
 by Nuñez, Anderton and Renslow; coolwarm by Moreland; rocket, mako, flare, crest, vlag and
@@ -1792,40 +2228,51 @@ ColorBrewer's schemes by Brewer (Apache-2.0): sequential `blues`, `bugn`, `bupu`
 multi-sequential `oleron`, `bukavu`, `fes` and cyclic `romao`, `bamo`, `broco`, `corko`,
 `viko` (256 colors each);
 `ggplot2` is ggplot2's continuous default (`#132B43` → `#56B1F7`). The
-`color_map` setting (alias `cmap`; inherited, default `"rainbow_llhh"`) is the map of heatmaps,
-contours and numbers given as colors. One `ColorMap` object given to several series
-shares its `"auto"` limits.
+`color_map` setting (alias `cmap`; inherited, default `"rainbow_llhh"`) is the gradient of
+heatmaps, contours and numbers given as colors. A `ColorMap` is a gradient over [0, 1]
+only: the values' limits and scale are their [color axis](#6-color-and-size-axes)'s, so
+series given one `ColorMap` object keep limits of their own; a shared color axis shares
+limits.
 
 ### Size maps
 
 ```python
-pl.SizeMap(sizes=(2, 10), limits="auto", scale="linear", by="area",
-           under=None, over=None, bad=None)
+pl.SizeMap(sizes=(3, 13), by="area", under=None, over=None, bad=None)
 ```
 
-`sizes` are the diameters at the limits. `by="area"` moves the area linearly between
-the end areas (with `sizes=(0, d)` and `limits="0/max"`, area is proportional to the
-value); `by="diameter"` moves the diameter. `under`/`over` default to the end sizes;
-`"none"` leaves those points out. `bad` (missing values) leaves them out by default.
+`sizes` are the diameters at the limits of the [size axis](#6-color-and-size-axes).
+`by="area"` moves the area linearly between the end areas (with `sizes=(0, d)` and
+`size_limits="0/max"`, area is proportional to the value); `by="diameter"` moves the
+diameter. `under`/`over` default to the end sizes; `"none"` leaves those points out.
+`bad` (missing values) leaves them out by default. `size_map` also takes a pair of
+diameters.
 
 ### Values in color and size
 
-| Given to `color` (also `edge_color`, `marker_color`) | Meaning |
+| Given to `color` (also `edge_color`, `marker_color`, `marker_edge_color`) | Meaning |
 |---|---|
 | a color string, `CMYK`, `Spot`, or a **tuple** of 3 or 4 numbers | one color |
 | a list of colors | one color per point |
-| a **list, array or other buffer of numbers** | one value per point, mapped through `color_map` |
+| a **list, array or other buffer of numbers** | one value per point, mapped through the color axis |
 | an `(n, 3)` or `(n, 4)` buffer | one color per point |
-| `"density"` or `pl.Density(…)` | the points' density, mapped through `color_map` |
+| `"density"` or `pl.Density(…)` | the points' density, mapped through the color axis |
 | a dict `{category: number}` or `{category: color}` (box, bar, violin) | per category |
 
 A tuple of numbers is always one color and a list of numbers is always values, so
 `color=[0.2, 0.4, 0.6]` with a point count other than 3 is an error (use a tuple for one
-RGB color). A `ColorMap` goes in `color_map`, not `color`.
-
-`size` takes a diameter (a length), diameters per point (px), or values per point mapped through
-`size_map` when it is set; `"density"` uses `size_map` or `SizeMap()`. A `SizeMap` goes in
-`size_map`.
+RGB color). A `ColorMap` goes in `color_map`, not `color`. Values go through the series'
+color axis wherever a series maps them: points (Scatter, Strip, Swarm `color` and
+`edge_color`; the markers of Line, Errorbar, Stem and Regression), cells, categories (Box,
+Bar, Violin `color`). A box's outliers are computed, so its `marker_color` and
+`marker_edge_color` take colors only. A line's `color` and every `edge_color` of bars,
+boxes, violins, pies and hexagons are one color. Values elsewhere are errors that name the
+setting.
+
+`size` takes a diameter (a length), diameters per point (px), or values per point mapped
+through the size axis when the series has a `size_map` or a `size_axis`; `"density"` is
+always mapped (default sizes `SizeMap()`). A `SizeMap` goes in `size_map`. `marker_size`
+(lines, error bars, stems, regressions, box outliers) is diameters in px only: those
+series have no size axis.
 
 Aliases, on every class with the setting: `c` = `color`, `s` = `size`, `cmap` =
 `color_map`, `smap` = `size_map` (also in style keys). Giving both names is an error.
@@ -1833,7 +2280,7 @@ Aliases, on every class with the setting: `c` = `color`, `s` = `size`, `cmap` =
 ### Point density
 
 ```python
-p.scatter(x, y, c="density", order="density")            # densest points drawn last
+p.scatter(x, y, c="density", draw_order="density")       # densest points drawn last
 p.scatter(x, y, c=pl.Density(adjust=0.5, normalize="max"), cmap="magma")
 pl.Density(bandwidth="scott", adjust=1.0, normalize="pdf", method="auto", grid=512)
 ```
@@ -1847,14 +2294,15 @@ 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 `size_map`, default `SizeMap()`), `alpha` (mapped
-linearly to `alpha_range`, default (0.2, 1)) and `order`; one object computes each
+`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
+`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"`.
 
 ### Drawing order
 
-`order` on scatter, strip and swarm: `None` (call order), `"density"` (ascending: the
+`draw_order` on scatter, strip and swarm: `None` (call order), `"density"` (ascending: the
 densest points are drawn last), `"-density"`, or sort keys per point (ascending; give
 `-z` for descending). Every per-point column (positions, colors, sizes, markers, opacities)
 is reordered together; the sort is stable and NaN keys come first. Setting `color` to a
@@ -1863,7 +2311,8 @@ density does not reorder by itself.
 ### Number formats
 
 One format applies wherever a number becomes text: `tick_format` (plot and colorbar
-axes) and `label_format` (heatmaps).
+axes) and `value_label_format` (value labels of bars, histograms, heatmaps, contours and
+pies).
 
 | Format | 1234.5, 0.05, −2 as one label set |
 |---|---|
@@ -1882,7 +2331,7 @@ to the next power is written in it (`9.96` at 2 digits → `10`). NaN gives an e
 Format strings and functions get the raw value; separators, minus and affixes then apply
 to the numbers in their result (rich content is used as is).
 
-Inherited settings (figure → plot → axis, colorbar or heatmap):
+Inherited settings (figure → plot → axis; series → its color axis):
 
 | Setting | Default | Values |
 |---|---|---|
@@ -1903,59 +2352,413 @@ Inherited settings (figure → plot → axis, colorbar or heatmap):
 | `plus` | 0.51 |
 | `cross` | 0.5754 |
 
-Aliases: `triangle`, `o`, `s`, `d`, `^`, `v`, `<`, `>`, `+`, `x`. A `pdf_io.Path` or SVG
+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); `pl.marker_path(name)` returns a path
-for pdf_io's `draw_markers`; `pl.marker_area(name)` its area.
+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.
 
 ## 8. Output
 
 ```python
 fig.save(path, **options)          # .pdf, .png, .jpg/.jpeg, .jxl, .avif
 fig.to_bytes(format="pdf", **options)
-fig.draw(canvas, x=0, y=0)         # on any pdf_io canvas; returns (width, height) in px
+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
 ```
 
-Options: `dpi` (images, default 192: two image pixels per px), `background` (default the figure's; unset is
-transparent, white in JPEG), `quality` (the figure's `quality` when not given; JPEG, default 90; JPEG XL and AVIF,
-default lossless; in a PDF, of rasterized content, default lossless), and pdf_io `Document` arguments: `title`, `author`, `compress`, `compression`,
-`system_fonts`, `font_dirs`, `color_mode`, `pdf_a`, … 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. `simplify` culls hidden content in PDF output only: PNG, JPEG and
-JPEG XL output draw everything (rasterizing hidden content costs less than culling it,
-and the pixels are the same), and dense lines are still decimated. A plot
-saved alone keeps its size in the figure (axes or box, by `align`), its title, legend and
-attached colorbars; its limits come from its own series.
+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:
+
+| 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
+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
+saved alone keeps its size in the figure (axes or box, by `align`), its limits and ticks
+(those of its shared axes too), its title, legend and attached colorbars, and shows its
+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.
 
 ### Large data
 
-* Series map their data to page coordinates in C (pdf_io `arrays.scaled`) and draw with
-  one bulk pdf_io call (markers, lines, areas, segments).
-* `simplify` (series, plot or figure; default `"auto"`) is passed to pdf_io: `"auto"`
-  decimates lines with many points per pixel column and culls markers that later markers
-  hide when that pays off (pdf_io decides per call from the data); `True` or a dpi always
-  simplifies at that resolution; `False` never.
-* `rasterize=True` or a dpi draws the series as an image inside the PDF; axes and text
-  stay vectors.
+* Series map their data to page coordinates in C (`kernels.scaled`) and draw with
+  one bulk vec_io call (markers, lines, areas, segments).
+* `simplify` (series, plot or figure; default `"auto"`) goes to each of the series' vec_io
+  calls, and vec_io applies it per output. PDF: `"auto"` decimates lines with many points
+  per pixel column and culls markers that later markers hide when that pays off (vec_io
+  decides per call from the data); `True` or a dpi always simplifies at that resolution;
+  `False` never. PNG, JPEG, JPEG XL and AVIF draw everything (rasterizing hidden content
+  costs less than culling it, and the pixels are the same) and decimate lines for their
+  resolution, unless `False`.
+* `rasterize=True` or a dpi draws the series in a vec_io group the PDF holds as an image;
+  axes and text stay vectors. Image output draws the group as vectors at its own
+  resolution.
 
 Timings (`tools/bench.py`, 8 threads, PDF written):
 
 | Case | Time |
 |---|---|
-| `import plot_io` (pdf_io included) | 0.04 s |
-| empty figure, 4 plots with ticks and labels | 0.004 s |
+| `import plot_io` (vec_io included) | 0.06 s |
+| empty figure, 4 plots with ticks and labels | 0.005 s |
 | scatter, 100k points, one color | 0.02 s |
-| scatter, 1M points, colors from a `ColorMap` | 0.71 s |
-| line, 1M points (`simplify=False` / `True`) | 0.09 s / 0.07 s |
+| scatter, 1M points, colors from a `ColorMap` | 0.25 s |
+| scatter, 1M points, `c=values`, PDF / PNG at 150 dpi | 0.56 s / 0.43 s |
+| line, 1M points (`simplify=False` / `True`) | 0.08 s / 0.03 s |
 | box plots, 10 categories × 1M values | 0.09 s |
-| heatmap 1000 × 1000 (`image`) with a colorbar | 0.11 s |
-| heatmap 200 × 200, uneven cells (`cells`) | 0.03 s |
-| scatter, 1M points, `rasterize=300` | 0.66 s |
+| heatmap 1000 × 1000 (`image`) with a colorbar | 0.06 s |
+| heatmap 200 × 200, uneven cells (`cells`) | 0.04 s |
+| scatter, 1M points, `rasterize=300` | 0.22 s |
 | `simplify="auto"` on 1M points it does not cull: overhead | < 0.01 s |
 
-## 9. Styles
+## 9. Genome tracks
+
+```python
+fig = pl.Tracks("chr2:143,120,001-143,780,000", width="5in")
+fig.hic(gwseq_io.open("cells.hic"), y_axis={"label": "Hi-C"}, depth=500_000)
+fig.gtf(gwseq_io.open("gencode.gtf.gz"), gene_type="protein_coding")
+fig.bed(gwseq_io.open_peaks("sites.tsv"), y_axis={"label": "Sites"})
+sets = fig.track(stacked=True)                     # one track, a named row per file
+for c in ("con", "pio"):
+    sets.bed(gwseq_io.open_peaks(f"{c}.tsv"), name=c)
+p = fig.track(y_axis={"label": "A/B"})             # an empty track: series overlaid
+before = p.bigwig(gwseq_io.open("before.bw"), name="before", color="sky", fill_to=False)
+p.bigwig(gwseq_io.open("after.bw"), name="after", color="rose", fill_to=before)
+fig.bigwig(gwseq_io.open("atac.bw"), y_axis={"label": "ATAC"})
+fig.vline(143_400_000)                             # through every track and the gaps
+fig.save("locus.pdf")
+fig.save("other.pdf", region=("chr2", 80_000_000, 81_000_000))
+```
+
+Genome tracks are made of general pieces:
+
+* **A tracks figure.** `pl.Tracks(region, **settings)` is a `Figure` with
+  `layout="tracks"` ([§2](#arrangement)): one column of plots, top to bottom in creation
+  order, sharing x (`share_x="all"`, tick labels and the axis title under the bottom plot
+  only), `spacing` 0, `width` 480 px. Its `region`, `unit`, `unit_in` and `origin` go to
+  `fig.x_axis`, the settings of every plot's x axis ([figure axes](#figure-axes)), with
+  `scale="genome"`; the other keywords are the figure's.
+* **Tracks.** A `Track` is a plot preset: a `height` from its content, `space_above` it,
+  axis lines left and bottom (Hi-C: bottom only), at most 4 y ticks and the y axis'
+  `label` in the row band (`label_position="band"`, `label_pad="0.5em"`). `fig.track(**settings)`
+  returns an empty one; a plot type called on the figure (`fig.bigwig`, `fig.bed`,
+  `fig.genes`, `fig.gtf`, `fig.hic`, also `fig.line`, …) adds a track holding it and returns
+  the series (`.plot` is the track; the track's settings, `title`, `x_axis` and `y_axis`
+  go to it, and
+  `name` names the series, its legend entry, as everywhere). Called on a track
+  (`p.bigwig(…)`, `p.line(…)`, `p.hline(…)`), plot types overlay in it.
+* **The genome scale.** An x axis with `scale="genome"` is linear in bp: its limits are its
+  `region` (less its `origin`), without padding, its tick labels in bp, kb or Mb, its
+  automatic label the chromosome (`chr2 (Mb)`). A genome series asks its x axis for it
+  when the axis has no scale of its own, so the genome series work on any plot too
+  (`pl.Plot().bigwig(reader, region=…)`: the series' own `region`).
+* **Genome layers.** `bigwig`, `bed`, `genes`, `gtf` and `hic` are plot types like the
+  others, drawn with the shared geoms: a signal's bins as a step line, a band and bars;
+  intervals and gene models as rectangles, lines and names; contacts as a grid of cells
+  under a 45° transform.
+* **Row labels, groups, lines through rows** are figure features ([§2](#rows)):
+  the y axis' `label` is a row label lined up across the tracks, `fig.group(first, last, label=…,
+  letter=…)` labels consecutive tracks (with x tick labels under the last one), and
+  `fig.vline(x, rows=…)`, `fig.vspan(x0, x1, rows=…)` run through the tracks and the gaps.
+
+Details:
+
+* **Region.** `region` is a string, 1-based and inclusive
+  (`"chr2:143,120,001-143,780,000"`; positions may carry a unit: `"chr1:1.2M-1.5M"`,
+  `"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`
+  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
+  labels and the axis label (`chr2 (Mb)`) under the bottom track; a group's last track has
+  tick labels too; `fig.set(label_outer=False)` labels every track. `unit` (`auto`, `bp`,
+  `kb`, `Mb`) and `unit_in` (`"label"`: `chr2 (Mb)` under `143.2 143.3 …`; `"ticks"`:
+  `-500kb 0 500kb`) set the labels; `tick_format="chr:pos"` writes positions
+  (`chr2:143,250,000`, in bp with `,` between thousands unless `unit` is set:
+  `chr2:143.25Mb`), the position itself even with an `origin`, and leaves the automatic
+  label out; `fig.x_axis(label=…)` replaces the label, and in a
+  string `{chr}`, `{unit}`, `{start}`, `{end}` are filled in (`""`: none). `origin` (a
+  position, `"center"`, `"start"` or `"end"` of the region) is drawn at 0: every series on
+  the axis is drawn less it ([transforms](#5-series)), and limits, ticks and decorations
+  are distances from it (`fig.vline(0)`, `fig.vspan(-1000, 1000)`); a region given to
+  `fig.vspan` is in positions.
+* **y axis.** An interval track's y axis has a tick per named series (`fig.bed(…,
+  name=…)`; each `name` of a `stacked` track) at the middle of its rows, the name as its
+  label; without names, and on Hi-C tracks, the y axis is hidden (`y_axis(visible=True)`
+  shows it).
+* **Heights.** A track's `height`: a length, a share (`"1fr"`, of the room the fixed heights
+  leave in a figure of given height, `reference="figure"`), or `auto`: the Hi-C triangle's
+  height (square cells; `max_height`, a length or a percentage of the width such as
+  `"33%"`, caps it, and `fit` clips the distances above or squashes the triangle), the rows
+  of intervals × `row_height` plus the y axis padding above and below, or `auto_height`
+  for signals. The figure height follows. `space_above` is the space above a track:
+  `auto_space_above` above every track but the first.
+* **Stacked intervals.** A track with `stacked=True` puts each interval series on rows of
+  its own, top to bottom, named left of its rows; they take no legend entries.
+* **Bins.** `bins` of `bigwig` and `hic`: a width on the axes (`"0.5px"`, the default: two
+  bins per px of the axes width; Hi-C: the finest resolution whose cells are at least that
+  wide), a size (`"10kb"`, `"5000bp"`, `"5000d"`), or a count (`200`). A size is read on
+  the genome-wide grid of that size: the region grows outward to it
+  (`snap_to_grid="expand"`), and the first and last bins are then cut to the region. A
+  count cuts the region itself into that many bins. The bins (and Hi-C `height="auto"`, interval rows) follow the axes width the
+  layout places: with the default `reference="axes"` it is `width`, so each file is read
+  once per draw; with `reference="plot"` or `"figure"`, the data are read again for the
+  width the first round places (reads are cached by their bins).
+* **Shared y.** `share_y=other_track` on a track, or `fig.set(share_y="bigwig")` to put
+  every track with a `bigwig` series on one scale (a figure's `share_x`/`share_y` takes a
+  plot type's name).
+
+### Readers
+
+plot_io does not import gwseq_io: it reads any object with the methods of gwseq_io's
+readers, recognised by their `type` attribute (`"bigwig"`, `"bigbed"`, `"bed"`, `"peaks"`,
+`"gtf"`, `"gff3"`, `"hic"`), else by their methods. The calls, which another reader can implement:
+
+| 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` |
+| 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
+instead of a reader raises `TypeError` (open it with `gwseq_io.open`, or
+`gwseq_io.open_peaks` for a TSV of locations), as do BAM and CRAM readers (pile the reads
+up into a bigWig first). A reader's error is raised with the track's label in the
+message.
+
+### BigWig
+
+```python
+pl.BigWig(reader=None, plot=None, *, x=None, y=None, **settings)
+```
+
+A step line along the bins, filled to `fill_to`. `reader` is a signal reader, a function
+`f(chr, start, end, bins)` returning the values, or `None` with `y` (values evenly over
+the region) and optionally `x` (bin centres, or n + 1 edges, in bp). The color is black
+when the series is alone in its track, palette colors when overlaid. `fill_to=<series>`
+fills between two signals, each part in the fill color of the series on top. For more,
+the track's `fill_mode` fills between all its signals, in place of their `fill_to`:
+`"in_between(up)"` (or `"in_between"`) fills each band between two neighbouring signals
+in the color of the one just above, `"in_between(down)"` of the one just below;
+`"in_between(max)"` fills from the lowest signal to the highest in the color of the top
+one, `"in_between(min)"` of the bottom one. The colors follow wherever the order changes
+(lines get points where they cross), and 0 is not kept on the y axis:
+
+```python
+t = fig.track(y_axis={"label": "Lamin A/C"}, fill_mode="in_between(up)")
+t.bigwig(neo_reader, name="Neo", color="sky")
+t.bigwig(pax7_reader, name="Pax7", color="rose")
+```
+
+<!-- settings:BigWig -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `region` | — | The region read: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; unset: the x axis' `region`. |
+| `bins` | '0.5px' | A bin count over the region (exactly, not on a grid); a bin size (`"10kb"`, `"5000bp"`), read on the genome-wide grid of the size (the row grown to it, then cut to the region); or a bin width on the axes (`"0.5px"`: two bins per px, read as a count). |
+| `bin_mode` | 'mean' | Reduction per bin: `mean`, `max` (keeps narrow peaks), `min`, `sum`, … (gwseq_io's). |
+| `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`. |
+| `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. |
+| `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. |
+| `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_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`. |
+
+Groups: `FillStyle`, `Font`.
+<!-- /settings -->
+
+### Bed and Genes
+
+```python
+pl.Bed(reader, plot=None, **settings)
+pl.Genes(reader, plot=None, **settings)    # Bed with kind="genes", rows expanded, names on,
+                                           # filled solid without outlines
+```
+
+`reader` is an interval reader, or the columns themselves: a dict, a DataFrame, or rows
+(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`.
+`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
+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
+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
+every feature has the same lightness.
+
+<!-- settings:Bed -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `region` | — | The region read: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; unset: the x axis' `region`. |
+| `kind` | 'boxes' | `boxes` (intervals, 8/13.2 of a row high: 8 px in the default row) or `genes` (BED12 models: exons as high, UTRs half, introns). |
+| `rows` | 'collapse' | `collapse`: one row; `expand`: overlapping features (and their labels) packed onto rows. |
+| `min_width` | 0.75 | Narrowest drawn feature (1-bp sites stay visible). Length. |
+| `color` | 'black' | A color, `"item_rgb"` (the `itemRgb` column) or `"score"` (the `score` column through `color_map`). |
+| `recolor` | False | Replace each feature's color by the closest named color (`True`: the closest shade; a level 0–1: the closest color's shade at that level); `False`: as given. Not with `color="score"`. |
+| `names` | False | Feature names (`name`) left of the features, dropped where they collide. |
+| `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). |
+| `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. |
+| `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. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | 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. |
+| `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_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`. |
+
+Groups: `FillStyle`, `TextStyle` (`name_`), `Font`.
+<!-- /settings -->
+
+`Genes` (only its own defaults):
+
+<!-- settings:Genes -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `kind` | 'genes' | `boxes` (intervals, 8/13.2 of a row high: 8 px in the default row) or `genes` (BED12 models: exons as high, UTRs half, introns). |
+| `rows` | 'expand' | `collapse`: one row; `expand`: overlapping features (and their labels) packed onto rows. |
+| `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). |
+
+Groups: `FillStyle`.
+<!-- /settings -->
+
+### Gtf
+
+```python
+pl.Gtf(reader, plot=None, **settings)      # Genes from a GTF or GFF3 reader
+```
+
+`reader` is a GTF or GFF3 reader (`gwseq_io.open("gencode.gtf.gz")`, bgzipped and indexed;
+`gwseq_io.index_gtf` makes one from any GTF), or BED12 columns as `Genes` takes them. The
+transcripts overlapping the region come whole, with their exons outside it. With
+`model="gene"` each gene is one model: its transcripts' exons merged, coding from the
+first CDS start to the last CDS end (the stop codon included), named by `gene_name`;
+`model="transcript"` draws every transcript, named by `transcript_name`. An id names what
+has no name. `gene_type` and `transcript_type` keep those biotypes. A `Bed` or `Genes`
+given a GTF reader raises `TypeError` pointing here.
+
+`Gtf` (only its own settings and defaults):
+
+<!-- settings:Gtf -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `model` | 'gene' | `gene`: one model per gene, its transcripts' exons merged and coding from the first CDS start to the last CDS end, named by `gene_name`; `transcript`: one per transcript, named by `transcript_name` (ids where there is no name). |
+| `gene_type` | — | Gene biotypes kept (`"protein_coding"`, a list); `None`: all. |
+| `transcript_type` | — | Transcript biotypes kept; `None`: all. |
+<!-- /settings -->
+
+### HiC
+
+```python
+pl.HiC(reader, plot=None, **settings)
+```
+
+The upper triangle of the contact matrix, the diagonal on the x axis, each cell a
+diamond: the matrix is drawn as an image under a 45° transform and clipped to the track.
+`reader` is a Hi-C reader, or a square matrix over the region. `bins="0.5px"` (the
+default) takes the finest of the reader's `bin_sizes` whose cells are at least 0.5 px wide;
+the cells of a size (`bins="5kb"`) sit on the file's grid, those past the region cut by
+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`.
+
+<!-- settings:HiC -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `region` | — | The region read: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; unset: the x axis' `region`. |
+| `depth` | — | Largest distance shown (bp); default the region's span (the whole triangle). |
+| `bins` | '0.5px' | A bin count over the region (exactly, from the coarsest resolution giving that many); one of the reader's `bin_sizes` (`"10kb"`), read on its grid (the region grown to it, then cut by the track); or a cell width on the axes (`"0.5px"`): the finest resolution whose cells are at least that wide. |
+| `normalization` | 'none' | `"none"` or one of the reader's `normalizations`. |
+| `matrix_type` | 'observed' | `observed`, `oe` (observed / expected) or `expected`. |
+| `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` | 'q:0.01/q:0.99' | 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` | 'log' | 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. |
+| `nan_color` | — | Color of cells without a value; default: the map's `bad` (transparent). |
+| `direction` | 'up' | `up`: the apex up; `down`: the triangle hangs from the top. |
+| `max_height` | — | Largest height of the track: a percentage of its width (`"33%"`) or a length; `None`: the triangle's (square cells). |
+| `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. |
+| `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_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`. |
+
+Groups: `Font`.
+<!-- /settings -->
+
+### Tracks
+
+`pl.Tracks(region=None, **settings)` returns the figure; `Track` has the settings of `Plot`,
+these added or with other defaults:
+
+<!-- settings:Track -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `space_above` | 'auto' | Space above the track; `auto`: none for the first track, else `auto_space_above`. Length; `%`: of the font size. |
+| `height` | 'auto' | Height of the track's axes: a length, a share of the room the fixed heights leave (`"1fr"`, with the figure's height given), or `auto`: Hi-C from its `depth` (square cells), intervals rows × `row_height`, else `auto_height`. |
+| `auto_height` | '4.5em' | Height of signal and empty tracks with `height="auto"`. Length; `%`: of the font size. |
+| `auto_space_above` | '0.6em' | The space `space_above="auto"` leaves. Length; `%`: of the font size. |
+| `stacked` | False | Interval series on rows of their own, top to bottom, each named left of its rows by its `name`. |
+| `fill_mode` | — | Fill between the track's signals (replacing their `fill_to`): `"in_between(up)"` (or `"in_between"`), each band between two neighbouring signals in the fill color of the one above; `(down)`, of the one below; `(max)`, one band from the lowest signal to the highest in the color of the top one; `(min)`, of the bottom one. `None`: each signal's `fill_to`. |
+<!-- /settings -->
+
+## 10. Styles
 
 A style presets settings: `Figure(style=…)` (also accepted by `pl.Plot` and the series
 classes, which pass it to their figure). Explicit settings always win over the style.
@@ -1969,24 +2772,28 @@ pl.register_style("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()                            # registered names
-pl.style_settings("house")             # the resolved dict (base theme included)
+pl.styles.names()                      # registered names
+pl.styles.settings("house")            # the resolved dict (base theme included)
 ```
 
-* **Keys.** Names of inherited settings (`"font_size"`, `"palette"`) or `"Class.name"`
-  for any setting of a class: `Figure`, `FigureTitle`, `Plot`, `Title`, `Legend`, `Axis`
-  (plot and colorbar axes), `Colorbar`, `Scatter`, `Line`, `Fill`, `Box`, `Heatmap`.
+* **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),
+  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 colorbar axes only, and `"XAxis.<setting>"`, `"YAxis.<setting>"` to the x or
+  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.** A setting is looked up on the object, then as `"Class.name"` in the
-  figure's effective theme, then (inherited settings) up the parent chain and as
-  `"name"` in the effective theme, then `DEFAULTS`. The effective theme is `pl.THEME`
-  (the inherited defaults) with the expanded style merged over it.
+* **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.
 * **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`.
@@ -1995,7 +2802,7 @@ pl.style_settings("house")             # the resolved dict (base theme included)
   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()`), each the defaults of a library expressed in these
+Bundled styles (`pl.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).
@@ -2022,30 +2829,49 @@ Vega and Vega-Lite default configs, Chart.js's defaults, plotly's templates and
 documented default properties. What cannot be expressed: legend titles naming a variable
 (series carry no variable names).
 
-## 10. Errors
+## 11. Errors
 
 | Exception | Raised for |
 |---|---|
-| `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`; `grid` with `rows`/`cols`; ratios of the wrong length; mixed category and numeric series on an axis; limits outside a scale's domain; a `ColorMap` without `color_values`; heatmap labels on more than 2,500 cells; unknown formats or output options; 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 |
+| `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 |
+
+## 12. Modules
 
-## 11. 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
+the types calls return: `plot_io.facets` (`FacetSet`, `LayerSet`), `plot_io.tables`
+(`SeriesGroup`), `plot_io.colorbar` (`Colorbar`). The others are internal: their names
+may change in any release.
 
 | Module | Role |
 |---|---|
-| `settings.py` | `Setting`, `Settings` (validation, inheritance, themes), keyword routing, validators |
-| `figure.py`, `plot.py` | `Figure` (arrangement, sizes, output), `Plot`, `Title`, `Legend` |
+| `settings.py` | `Setting`, `Settings` (validation, the cascade, explain), class rules and `"auto"` rules, keyword routing, validators |
+| `groups.py` | setting groups (`Font`, `TextStyle`, `Stroke`, `Marker`, `FillStyle`, `NumberFormat`) and their embedding under a prefix |
+| `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`) |
 | `axis.py`, `scales.py`, `limits.py`, `ticks.py` | axes, scale functions, limits syntax, tick choice and labels |
-| `render.py` | resolution, layout and drawing |
-| `legend.py`, `colorbar.py` | legend and colorbar layout and drawing |
-| `series/` | `Series` base and the series kinds; shared marker drawing; error bars |
-| `slots.py`, `stacking.py`, `labels.py`, `shapes.py` | category slots, stacking, value labels, bulk rectangles and polygons |
-| `stats.py` | bins, densities, contours, LOWESS and swarm layout (pdf_io's C helpers) |
+| `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`) |
+| `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` |
+| `presets/` | the plot types (`Scatter`, `Box`, …): settings, and the layers each draws; error bars |
+| `labels.py`, `shapes.py`, `seams.py` | value labels, bulk rectangles and polygons, seams between touching outlines |
+| `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`: gradients numbers are mapped onto; Oklab from pdf_io), `data.py` (bundled map and palette colors) |
-| `sizemaps.py` | `SizeMap`: values to marker diameters |
-| `markers.py`, `lines.py`, `text.py` | marker shapes, line dash styles, rich one-line text |
+| `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) |
+| `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`) |
 | `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` |
+| `tables.py`, `facets.py` | columns of tables, `group=` splitting (`SeriesGroup`); `facet`, `FacetSet`, `LayerSet` |
 | `sharing.py`, `times.py` | shared axes; dates and times on axes |
-| `_backend.py` | the pdf_io calls plot_io relies on |
+| `genome/` | genome tracks: `layout.py` (`Tracks`, the `Track` preset), `scale.py` (the genome scale: tick labels, label, origin), `tracks.py` (`BigWig`, `Bed`, `Genes`, `Gtf`, `HiC`: layers over stats `region_signal`, `intervals`, `contact_matrix`; registered layers), `sources.py` (reading readers by their methods), `regions.py`, `pack.py` (rows of intervals) |
+| `_backend.py` | the vec_io calls plot_io relies on (buffer intake, font databases shared between renders, path areas) |