plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/layout.py

@@ -0,0 +1,1381 @@
+"""The box model: a figure's areas measured into bands, the grid solved, every area placed
+into a frozen :class:`Geometry`.
+
+* **Measure.**  :func:`plot_io.boxes.measure` gives the :class:`~plot_io.geometry.Bands`
+  around a plot's axes of a given size, from its box tree (:mod:`plot_io.boxes`: tick
+  marks, tick labels, the label row and ×10ᵏ offsets of each axis, twin axes, attached
+  colorbars, an outside legend, the titles and the plot's ``space_above``);
+  :func:`plot_io.rows.bands` adds the row label and group letter bands, the outermost on
+  the left, aligned per grid column.  The ticks the bands hold are computed first for the
+  axes' length (:func:`plot_io.boxes.prepare`).
+* **Solve.**  The grid (ids with spans, ``fr`` and fixed sizes, ``reference`` and
+  ``align``) takes, per line between cells, the largest margin of the areas there.  Only
+  what is circular is iterated, in rounds, until no axes size changes by more than 1/3 px:
+  axis length → ticks → label sizes → axis length, ``data_ratio``, stats binned at the
+  axes' resolution (hexagon lattices, genome bins), and the lanes of figure titles wrapped
+  to their spans.
+  ``inside="auto"`` and ``"best"`` colorbars, then legends, are chosen on the occupancy
+  grid once the axes are placed, before the last round; one that finds no free place
+  inside moves out (a colorbar to the bottom of its plot, a legend to the right).
+* **Lanes.**  Figure titles, legends and colorbars are nodes on the grid's lines
+  (:class:`_Lane`: a thickness measured along their span, a placement from their lane's
+  near edge): a top title above the topmost row it covers, a bottom one below the
+  bottommost, left and right ones beside the columns; a group's label is a left title over
+  its plots; the main title (on top, unrotated, without an ``order``) is the outermost
+  lane of the top, over every plot.  The lanes of a line add to the gap there: spacing
+  between rows (or columns) plus the lanes; at the figure's edge, the margin, the lanes and
+  another margin between them and the plots (none when the main title is alone there:
+  its ``pad`` parts it from them).  On one side of a line, a title nested in another sits
+  nearer the plots, disjoint spans share a lane, overlapping ones take lanes in creation
+  order, and ``order`` overrides; a lane is as thick as its thickest node.  Over the same
+  plots, from the plots outward: legend, colorbar, title.  A figure legend shows the
+  entries of its plots, which those plots' legends then leave out; a figure colorbar
+  replaces its plots' attached colorbars of its axis.
+* **Place.**  Each area becomes a geometry record (:mod:`plot_io.geometry`; a plot's
+  nodes at the offsets their bands were measured at, :func:`plot_io.boxes.place_plot`);
+  each lane node its record (the main title the figure's title paragraph).  ``only=``
+  lays out the whole figure without the lanes and keeps one plot, at its size in the
+  figure, with its outer labels, its own titles, its whole legend and its attached
+  colorbars.
+
+All lengths are px.
+"""
+
+import dataclasses
+import math
+from typing import Any
+
+from . import rows
+from .boxes import measure, place_plot, prepare, title_font
+from .boxes import title_need as _title_need
+from .boxes import title_runs as _title_runs
+from .geometry import (Bands, FigureColorbarGeometry, FigureGeometry,
+                       FigureLegendGeometry, Rect, TitleGeometry)
+from .layers.context import DrawContext
+from .spec import current, rendering, set_boxes, warn, warnings_once
+from .states import build
+from .titles import along, block, rotation_of, rule_extent, rule_inside, rule_rect
+
+__all__ = ["Area", "Geometry", "Placed", "arrange", "prepare", "measure", "layout",
+           "context", "ROUNDS"]
+
+#: Most layout rounds spent on the axes sizes before the other decisions are made (a
+#: layout whose sizes still move by then, oscillating between tick sets, keeps the last).
+SIZE_ROUNDS = 5
+#: Most layout rounds in all (each measures every area and solves the grid).
+ROUNDS = 12
+#: Axes sizes closer than this (px) between rounds have converged.
+TOLERANCE = 1 / 3
+#: The smallest axes length (px) a figure of given size keeps: below it, the figure grows
+#: and warns.
+MIN_AXES = 8.0
+
+
+# ---------------------------------------------------------------------------
+# Areas
+# ---------------------------------------------------------------------------
+
+class Area:
+    """A plot, colorbar or size legend on cells ``[r0, r1) × [c0, c1)``, while laid out."""
+
+    def __init__(self, obj: Any, r0: int, c0: int, r1: int, c1: int) -> None:
+        self.obj = obj
+        self.r0, self.c0, self.r1, self.c1 = r0, c0, r1, c1
+        self.state: Any = None
+        self.bands: Bands | None = None
+        self.margins = (0.0, 0.0, 0.0, 0.0)      # left, right, top, bottom
+        self.axes = (0.0, 0.0, 0.0, 0.0)         # x0, y0, x1, y1
+        self.box = (0.0, 0.0, 0.0, 0.0)
+
+    @property
+    def is_bar(self) -> bool:
+        """A colorbar or a size legend: an area of fixed thickness."""
+        from .colorbar import Colorbar
+        from .legend import SizeLegend
+        return isinstance(self.obj, (Colorbar, SizeLegend))
+
+    @property
+    def is_plot(self) -> bool:
+        from .plot import Plot
+        return isinstance(self.obj, Plot)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Placed:
+    """An area placed: its cells, axes rectangle (a colorbar's bar), box, margins, bands,
+    its state in the render and its geometry record."""
+
+    obj: Any
+    r0: int
+    c0: int
+    r1: int
+    c1: int
+    axes: Rect
+    box: Rect
+    margins: tuple[float, float, float, float]
+    bands: Bands | None
+    state: Any
+    geometry: Any
+    is_bar: bool
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Geometry:
+    """A figure laid out: its size, its placed areas, the figure's own parts and the
+    number of layout rounds it took."""
+
+    width: float
+    height: float
+    areas: tuple[Placed, ...]
+    figure: FigureGeometry
+    rounds: int = 1
+
+    @property
+    def title(self) -> Any:
+        """The figure title's paragraph, or ``None``."""
+        return self.figure.title
+
+
+def arrange(fig: Any, only: Any = None) -> tuple[list[Area], int, int]:
+    """The areas of the figure and the grid size."""
+    if only is not None:
+        return [Area(only, 0, 0, 1, 1)], 1, 1
+    items = list(fig._areas.items())
+    grid = fig.explicit_grid()
+    if grid is not None:
+        areas = []
+        for k, obj in items:
+            cells = [(i, j) for i, r in enumerate(grid) for j, v in enumerate(r) if v == k]
+            if not cells:
+                raise ValueError(f"id {k!r} is not in the grid")
+            r0 = min(c[0] for c in cells)
+            c0 = min(c[1] for c in cells)
+            areas.append(Area(obj, r0, c0, max(c[0] for c in cells) + 1,
+                              max(c[1] for c in cells) + 1))
+        return areas, len(grid), len(grid[0])
+    n = len(items)
+    rows_, cols, order = fig.resolve("rows"), fig.resolve("cols"), fig.resolve("fill_order")
+    if rows_ and cols:
+        nr, nc = rows_, cols
+        by_row = order != "col"
+    elif cols:
+        nc = cols
+        nr = max(1, math.ceil(n / cols))
+        by_row = order != "col"
+    elif rows_:
+        nr = rows_
+        nc = max(1, math.ceil(n / rows_))
+        by_row = order == "row"
+    else:
+        nc = max(1, math.ceil(math.sqrt(n)))
+        nr = max(1, math.ceil(n / nc))
+        by_row = order != "col"
+    areas = []
+    for i, (_, obj) in enumerate(items):
+        r, c = (i // nc, i % nc) if by_row else (i % nr, i // nr)
+        areas.append(Area(obj, r, c, r + 1, c + 1))
+    return areas, nr, nc
+
+
+def context(a: Any) -> DrawContext:
+    """A drawing context of area ``a``'s placed axes, without a canvas (layout decisions:
+    legend placement, stats binned at the axes' resolution)."""
+    st = a.state
+    return DrawContext(None, a.obj, a.axes, st.x, st.y, st.cycle)
+
+
+# ---------------------------------------------------------------------------
+# Measure: the bands around a plot's axes
+# ---------------------------------------------------------------------------
+
+def _measure_area(a: Area, fonts: Any, w: float, h: float) -> Bands:
+    if a.is_bar:
+        m = a.state.measure(fonts, w, h)
+        return Bands((w, h), margins=m)
+    return measure(a.state, fonts, w, h)
+
+
+# ---------------------------------------------------------------------------
+# Solve: the grid
+# ---------------------------------------------------------------------------
+
+def _split(fig: Any, n: int, name: str | None) -> tuple[list[float], dict[int, tuple[float, float]]]:
+    """Ratios of the free columns (or rows) and the fixed ones as ``(a, b)``: ``a`` px +
+    ``b`` × the plots' room (`%`).  Bare numbers and ``fr`` are ratios."""
+    if name is None or fig.resolve(name) is None:
+        return [1.0] * n, {}
+    raw = fig._raw(name)
+    if len(raw) != n:
+        raise ValueError(f"{name} has {len(raw)} values for {n} "
+                         f"{'columns' if name == 'widths' else 'rows'}")
+    from .units import Dim, resolve_raw
+    from .validators import length
+    check = length(percent="room", fr=True)      # a + b × room: checked once combined
+    ratios: list[float] = []
+    fixed: dict[int, tuple[float, float]] = {}
+    for i, v in enumerate(raw):
+        if isinstance(v, (int, float)):
+            ratios.append(float(v))
+        elif isinstance(v, Dim) and v.unit == "fr":
+            ratios.append(float(v.number or 0.0))
+        else:
+            a = resolve_raw(fig, name, check, v, of=0.0)
+            fixed[i] = (a, resolve_raw(fig, name, check, v, of=1.0) - a)
+            ratios.append(0.0)
+    return ratios, fixed
+
+
+def _solve_axis(areas: list[Area], n: int, ratios: list[float], fixed_total: float | None,
+                base: float, spacing: tuple[float, float], margin: tuple[float, float],
+                align: str, ref: str, horizontal: bool, fixed_cells: dict[int, float],
+                tracks: dict[int, tuple[float, float]],
+                lanes: list[float] | None = None, apart: list[float] | None = None
+                ) -> tuple[list[float], list[float], float]:
+    """Positions and sizes of the cells along one direction, and the total length.
+
+    Cell sizes are axes sizes with ``align="axes"`` and box sizes with ``"borders"``.
+    ``fixed_total``: the figure's length (``reference="figure"``); otherwise ``base`` × the
+    ratio is the reference box of a cell: its axes (``ref="axes"``) or its plot box
+    (``"plot"``).  ``fixed_cells``: cells whose size is given (colorbar-only columns);
+    ``tracks``: cells sized ``a + b × room`` (fixed `widths`; the room: what the cells
+    share, the total less the margins, spacing, lanes and, with ``"axes"``, the plots'
+    margins; without ``fixed_total``, solved from the other cells).  ``spacing`` and ``margin``
+    are ``(a, b)`` too: ``a`` px + ``b`` × the total, solved exactly when the total is an
+    output.  ``lanes``: per line between cells, the thickness of its lanes (px): a line
+    inside the grid grows by them, an outer line by them and, where ``apart`` (per line,
+    default: with lanes), a margin between them and the plots."""
+    if horizontal:
+        def span(a): return a.c0, a.c1
+        def need(a): return a.margins[0], a.margins[1]
+    else:
+        def span(a): return a.r0, a.r1
+        def need(a): return a.margins[2], a.margins[3]
+    lanes = lanes or [0.0] * (n + 1)
+    apart = apart or lanes
+    outer = [0.0] * (n + 1)            # a margin between the outer lanes and the plots
+    fixed_cells = {i: v for i, v in fixed_cells.items() if i not in tracks}
+    free = [i for i in range(n) if i not in fixed_cells and i not in tracks]
+    lo_need = [0.0] * (n + 1)          # largest margin of the areas starting at a line
+    hi_need = [0.0] * (n + 1)          # largest margin of the areas ending at a line
+    for a in areas:
+        s0, s1 = span(a)
+        m0, m1 = need(a)
+        lo_need[s0] = max(lo_need[s0], m0)
+        hi_need[s1] = max(hi_need[s1], m1)
+
+    def cell(i: int) -> float:
+        if i in fixed_cells:
+            return fixed_cells[i]
+        size = base * ratios[i]
+        if align == "axes" and ref == "plot":
+            return max(MIN_AXES, size - lo_need[i] - hi_need[i + 1])
+        if align == "borders" and ref == "axes":
+            return size + lo_need[i] + hi_need[i + 1]
+        return size
+
+    needs = sum(hi_need[i] + lo_need[i] for i in range(n + 1)) if align == "axes" else 0.0
+    name = "widths" if horizontal else "heights"
+    pct = sum(b for _, b in tracks.values())     # the % tracks' share of the plots' room
+    if pct > 1.0 + 1e-9 or (pct >= 1.0 - 1e-9 and free):
+        raise ValueError(f"Figure setting {name!r}: its % take {pct * 100:g} % of the "
+                         f"plots' room" + ("" if pct > 1.0 + 1e-9 else
+                                           ", leaving none for the other cells"))
+    room = 0.0
+    if fixed_total is not None:
+        total = fixed_total
+    else:
+        cells = (sum(cell(i) for i in range(n) if i not in tracks)
+                 + sum(a for a, _ in tracks.values()))
+        if pct >= 1.0 - 1e-9:              # % tracks only: of the cells' reference sizes
+            room = sum(cell(i) if i in fixed_cells else
+                       _ratio_one(base, align, ref, lo_need[i], hi_need[i + 1])
+                       for i in range(n))
+        else:
+            room = cells / (1.0 - pct)
+        known = (cells + pct * room + needs + (n - 1) * spacing[0] + 2 * margin[0])
+        extra = (apart[0] > 0) + (apart[n] > 0)
+        known += sum(lanes) + extra * margin[0]
+        share = (n - 1) * spacing[1] + 2 * margin[1] + extra * margin[1]
+        if share >= 1.0:
+            raise ValueError("spacing and margin in % take 100 % or more of the figure")
+        total = known / (1.0 - share)
+    sp = spacing[0] + spacing[1] * total
+    mg = margin[0] + margin[1] * total
+    for i in (0, n):
+        if apart[i] > 0:
+            outer[i] = mg
+    gut = [hi_need[i] + lo_need[i] + (mg if i in (0, n) else sp) + lanes[i] + outer[i]
+           for i in range(n + 1)]
+    if fixed_total is not None:            # what the cells share
+        room = fixed_total - (sum(gut) if align == "axes" else
+                              2 * mg + sp * (n - 1) + sum(lanes) + outer[0] + outer[n])
+    for i, (px, per) in tracks.items():
+        if not px + per * room > 0:
+            raise ValueError(f"Figure setting {name!r}: track {i} resolves to "
+                             f"{px + per * room:g} px, expected a positive length")
+    track = {i: max(1.0, a + b * room) for i, (a, b) in tracks.items()}
+    given = {**fixed_cells, **track}
+
+    if align == "axes":
+        if fixed_total is not None:
+            avail = room - sum(given.values())
+            shares = _shares(avail, free, ratios, [MIN_AXES] * n)
+            sizes = [given[i] if i in given else shares[i] for i in range(n)]
+        else:
+            sizes = [given[i] if i in given else cell(i) for i in range(n)]
+        pos = []
+        p = gut[0]
+        for i in range(n):
+            pos.append(p)
+            p += sizes[i] + gut[i + 1]
+        _check_grown(fixed_total, p, horizontal)
+        return pos, sizes, p
+    low = [lo_need[i] + hi_need[i + 1] + MIN_AXES for i in range(n)]   # margins + axes
+    if fixed_total is not None:
+        shares = _shares(room - sum(given.values()), free, ratios, low)
+        sizes = [given[i] if i in given else shares[i] for i in range(n)]
+    else:
+        sizes = [given[i] if i in given else max(low[i], cell(i)) for i in range(n)]
+    pos = []
+    p = mg + lanes[0] + outer[0]
+    for i in range(n):
+        pos.append(p)
+        p += sizes[i] + (sp + lanes[i + 1] if i < n - 1 else 0.0)
+    p += lanes[n] + outer[n] + mg
+    _check_grown(fixed_total, p, horizontal)
+    return pos, sizes, p
+
+
+def _ratio_one(base: float, align: str, ref: str, lo: float, hi: float) -> float:
+    """A cell of ratio 1 between margins ``lo`` and ``hi``: its axes (``align="axes"``) or
+    its box, from the reference box ``base``."""
+    if align == "axes" and ref == "plot":
+        return max(MIN_AXES, base - lo - hi)
+    if align == "borders" and ref == "axes":
+        return base + lo + hi
+    return base
+
+
+def _shares(avail: float, free: list[int], ratios: list[float], low: list[float]
+            ) -> dict[int, float]:
+    """The ``free`` cells' shares of ``avail`` px by their ratios, none below its ``low``
+    (a cell held at its low, the others share the rest; their sum passes ``avail`` only
+    when the lows do)."""
+    out: dict[int, float] = {}
+    rest = list(free)
+    while rest:
+        rsum = sum(ratios[i] for i in rest) or 1.0
+        short = [i for i in rest if avail * ratios[i] / rsum < low[i]]
+        if not short:
+            break
+        for i in short:
+            out[i] = low[i]
+            avail -= low[i]
+            rest.remove(i)
+    rsum = sum(ratios[i] for i in rest) or 1.0
+    for i in rest:
+        out[i] = max(low[i], avail * ratios[i] / rsum)
+    return out
+
+
+def _check_grown(fixed: float | None, total: float, horizontal: bool) -> None:
+    """Warn when a figure of a given size (``reference="figure"``) grows to fit what is
+    around its plots."""
+    if fixed is not None and total > fixed + 0.5:
+        warn(f"the figure's {'width' if horizontal else 'height'} {fixed:g} px is too "
+             f"small for its plots' margins, titles and spacing: it is drawn {total:.4g} px",
+             key=("grown", horizontal))
+
+
+def _bar_cells(areas: list[Area], n: int, horizontal: bool, align: str) -> dict[int, float]:
+    """Cells covered only by colorbars running across this direction: their size is the
+    bar's (``axes``) or the bar's box (``borders``)."""
+    out: dict[int, float] = {}
+    for i in range(n):
+        covering = [a for a in areas
+                    if (a.c0 <= i < a.c1 if horizontal else a.r0 <= i < a.r1)]
+        if not covering or not all(a.is_bar for a in covering):
+            continue
+        sizes = []
+        for a in covering:
+            bar = a.state
+            if bar.vertical != horizontal:
+                break
+            t = bar.cell_size
+            if align == "borders":
+                m = a.margins
+                t += (m[0] + m[1]) if horizontal else (m[2] + m[3])
+            sizes.append(t)
+        else:
+            out[i] = max(sizes)
+    return out
+
+
+def _ratio_cells(areas: list[Area], sizes: dict[int, tuple[float, float]], given: str,
+                 xb: dict[int, float], yb: dict[int, float]) -> None:
+    """With only the width (height) given, rows (columns) of plots with a data ratio take
+    the height (width) it asks for: the largest in the row."""
+    for a in areas:
+        want = getattr(a.state, "aspect_want", lambda: None)()
+        if not want:
+            continue
+        w, h = sizes[id(a)]
+        if given == "width" and a.r1 - a.r0 == 1:
+            yb[a.r0] = max(yb.get(a.r0, 0.0), w * want)
+        elif given == "height" and a.c1 - a.c0 == 1:
+            xb[a.c0] = max(xb.get(a.c0, 0.0), h / want)
+
+
+class _Grid:
+    """The grid's fixed inputs: alignment, reference box, spacing, margins, the columns'
+    and rows' ratios and fixed sizes."""
+
+    def __init__(self, fig: Any, nr: int, nc: int, fixed: tuple[float, float] | None = None) -> None:
+        self.fig, self.nr, self.nc, self.fixed = fig, nr, nc, fixed
+        self.align = fig.resolve("align")
+        self.spacing = fig.resolve_linear("spacing")
+        self.margin = fig.resolve_linear("margin")
+        self.fw: float | None = None
+        self.fh: float | None = None
+        self.mx = self.my = self.margin[0]      # the margins as last solved (px)
+        #: the grid's extent along x and along y as last solved (its first and last
+        #: cells' outer edges)
+        self.cells = ([0.0, 0.0], [0.0, 0.0])
+        if fixed is not None:                   # one plot alone, at its size in the figure
+            self.cw, self.ch = fixed
+            self.ref = "axes" if self.align == "axes" else "plot"
+        else:
+            self.ref = fig.resolve("reference")
+            self.cw, self.ch = fig.reference_size()
+            if self.ref == "figure":
+                self.fw, self.fh = self.cw, self.ch
+                self.cw, self.ch = 150.0, 120.0     # first guess of a cell's axes
+        self.wr, self.wt = _split(fig, nc, "widths" if fixed is None else None)
+        self.one = fig.one_size_given() if (fixed is None and self.ref == "axes"
+                                            and self.align == "axes") else None
+
+    def place(self, areas: list[Area], sizes: dict[int, tuple[float, float]],
+              lanes: tuple[list[float], ...] | None = None) -> tuple[float, float, bool]:
+        """Place the measured ``areas`` (their margins) on the grid; ``lanes``: the
+        lanes' thickness per line between columns and between rows, and per line whether
+        a margin parts them from the plots (:func:`_lane_sizes`).  Returns the figure
+        size and whether an axes size changed by more than the tolerance (``sizes`` is
+        updated)."""
+        fig, align, fixed = self.fig, self.align, self.fixed
+        hr, ht = _split(fig, self.nr, "heights" if fixed is None else None)
+        xb = {} if (fig.is_set("widths") and fixed is None) else _bar_cells(areas, self.nc, True, align)
+        yb = {} if (fig.is_set("heights") and fixed is None) else _bar_cells(areas, self.nr, False, align)
+        if self.one is not None:
+            _ratio_cells(areas, sizes, self.one, xb, yb)
+        xl, yl, xa, ya = lanes if lanes is not None else (None, None, None, None)
+        xs, xw, W = _solve_axis(areas, self.nc, self.wr, self.fw, self.cw, self.spacing,
+                                self.margin, align, self.ref, True, xb, self.wt, xl, xa)
+        ys, yh, H = _solve_axis(areas, self.nr, hr, self.fh, self.ch, self.spacing,
+                                self.margin, align, self.ref, False, yb, ht, yl, ya)
+        self.mx = self.margin[0] + self.margin[1] * W
+        self.my = self.margin[0] + self.margin[1] * H
+        self.cells = ([xs[0], xs[-1] + xw[-1]], [ys[0], ys[-1] + yh[-1]])
+        changed = False
+        for a in areas:
+            x0 = xs[a.c0]
+            x1 = xs[a.c1 - 1] + xw[a.c1 - 1]
+            y0 = ys[a.r0]
+            y1 = ys[a.r1 - 1] + yh[a.r1 - 1]
+            left, right, top, bottom = a.margins
+            if align == "axes":
+                a.axes = (x0, y0, x1, y1)
+                a.box = (x0 - left, y0 - top, x1 + right, y1 + bottom)
+            else:
+                a.box = (x0, y0, x1, y1)
+                a.axes = (x0 + left, y0 + top, max(x0 + left + 1, x1 - right),
+                          max(y0 + top + 1, y1 - bottom))
+            if a.is_bar:
+                a.axes = a.state.bar_rect(a.axes)
+            new = (a.axes[2] - a.axes[0], a.axes[3] - a.axes[1])
+            old = sizes[id(a)]
+            if abs(new[0] - old[0]) > TOLERANCE or abs(new[1] - old[1]) > TOLERANCE:
+                changed = True
+            sizes[id(a)] = new
+        for a in areas:
+            if not a.is_bar:
+                a.axes = a.state.aspect_rect(a.axes)
+        return W, H, changed
+
+
+# ---------------------------------------------------------------------------
+# Rounds: what is circular
+# ---------------------------------------------------------------------------
+
+def _same(f: Any, g: Any) -> bool:
+    """Equal keys of a stat binned at the axes' resolution (floats within 1e-6)."""
+    if f is None or g is None or len(f) != len(g):
+        return f is g
+    for a, b in zip(f, g):
+        if isinstance(a, float) and isinstance(b, float):
+            if not abs(a - b) <= 1e-6 * max(1.0, abs(a), abs(b)):
+                return False
+        elif a != b:
+            return False
+    return True
+
+
+def _binned(a: Area) -> list[tuple[Any, list[Any]]]:
+    """The plot (and twin) states of an area with calls whose stats bin at the placed
+    axes' resolution, with those calls."""
+    if not a.is_plot:
+        return []
+    out = []
+    for st in [a.state, *a.state.twins]:
+        calls = [c for c in st.calls if c.resolution is not None]
+        if calls:
+            out.append((st, calls))
+    return out
+
+
+def _place_binned(fig: Any, areas: list[Area], rects: dict[int, Rect],
+                  lanes: list["_Lane"] | None = None) -> bool:
+    """Record the axes placed at ``rects`` (area id → rectangle) of the plots with stats
+    binned at their resolution; when a call's binning changed, train the color and size
+    axes again (the counts changed) and update the colorbars (those in the ``lanes``
+    too).  Returns whether anything changed."""
+    r = current()
+    assert r is not None
+    changed = False
+    for a in areas:
+        for st, calls in _binned(a):
+            ctx = DrawContext(None, st.plot, rects[id(a)], st.x, st.y, st.cycle)
+            old = r.placed.get(id(st.plot))
+            if old is None or any(not _same(c.resolution(ctx), c.resolution(old))
+                                  for c in calls):
+                r.placed[id(st.plot)] = ctx
+                changed = True
+    if changed:
+        from .mapped import train
+        train(fig, areas)
+        for a in areas:
+            if a.is_plot:
+                for bar in a.state.bars:
+                    bar.sync()
+            elif hasattr(a.state, "sync"):
+                a.state.sync()
+        for lt in lanes or ():
+            if lt.bar is not None:
+                lt.bar.sync()
+    return changed
+
+
+def _widths_changed(areas: list[Area]) -> bool:
+    """Whether a plot's genome data were binned for another axes width than placed."""
+    r = current()
+    assert r is not None
+    for a in areas:
+        if a.is_plot and id(a.obj) in r.widths:
+            w = a.axes[2] - a.axes[0]
+            used = r.widths[id(a.obj)]
+            if abs(w - used) > 1e-6 * max(1.0, w):
+                return True
+    return False
+
+
+def _rebuild(fig: Any, areas: list[Area], lanes: list["_Lane"], out: set[int]) -> None:
+    """The states again, from calls computed for the placed axes widths (legend choices
+    kept, the inside colorbars of ``out`` moved out again, figure legends collected
+    again)."""
+    r = current()
+    assert r is not None
+    chosen = {}
+    for a in areas:
+        if a.is_plot:
+            leg = a.state.legend
+            chosen[id(a)] = (leg.choice, leg.free)
+            w, h = a.axes[2] - a.axes[0], a.axes[3] - a.axes[1]
+            set_boxes(a.obj, axes_width=w, axes_height=h)
+    r.plots.clear()
+    r.calls.clear()
+    r.widths.clear()
+    build(fig, areas)
+    _share_legends(lanes, areas)
+    for lt in lanes:
+        if lt.bar is not None:
+            lt.bar.sync()
+    _drop_bars(lanes, areas)
+    _move_out(areas, out)
+    for a in areas:
+        if id(a) in chosen:
+            a.state.legend.choice, a.state.legend.free = chosen[id(a)]
+
+
+def _choose_legends(areas: list[Area], fonts: Any) -> bool:
+    """Choose the places of ``"auto"`` legends on the occupancy grid of the placed axes;
+    whether one moved outside (its band changes the margins)."""
+    moved = False
+    for a in areas:
+        if a.is_plot:
+            leg = a.state.legend
+            if leg.active() and leg.choice is None and not leg.moved \
+                    and leg.setting() in ("auto", "best"):
+                leg.choice = leg.choose(context(a), outside=True, fonts=fonts)
+                moved = moved or leg.choice.startswith("outside")
+    return moved
+
+
+def _choose_bars(areas: list[Area], fonts: Any, out: set[int]) -> bool:
+    """Inside colorbars with ``inside="auto"`` (or ``"best"``) larger than the axes, or
+    whose best place inside them meets a marker, a text or another guide, or covers more
+    than ``OUTSIDE_THRESHOLD`` of what is drawn: moved out, to the bottom of their plot (their
+    ids added to ``out``); whether one moved."""
+    from .guides import (BEST_CANDIDATES, CANDIDATES, CHOSEN, OUTSIDE_THRESHOLD,
+                         _drawn, anchor_box, best_anchor)
+    moved = False
+    for a in areas:
+        if not a.is_plot or not any(b.inside in CHOSEN for b in a.state.bars):
+            continue
+        ctx = context(a)
+        x0, y0, x1, y1 = ctx.rect
+        occ = _drawn(a.state, ctx, fonts)
+        for b in a.state.bars:
+            where = b.inside
+            if where is None:
+                continue
+            w, h, _ = b.content.inside_size(fonts, x1 - x0, y1 - y0)
+            pad = b.content.size("pad")
+            if where in CHOSEN:
+                where, f = best_anchor(occ, ctx.rect, w, h, pad, pad,
+                                       BEST_CANDIDATES if where == "best" else CANDIDATES)
+                box = (*anchor_box(ctx.rect, where, w, h, pad, pad), w, h)
+                if f > OUTSIDE_THRESHOLD or occ.solid_in(*box) \
+                        or occ.covered(*box, markers=True) \
+                        or w > x1 - x0 - 2 * pad or h > y1 - y0 - 2 * pad:
+                    out.add(id(b.cb))
+                    moved = True
+                    continue
+            x, y = anchor_box(ctx.rect, where, w, h, pad, pad)
+            occ.rects([x], [y], [x + w], [y + h], solid=True)
+    if moved:
+        _move_out(areas, out)
+    return moved
+
+
+def _move_out(areas: list[Area], out: set[int]) -> None:
+    """The inside colorbars of ``out`` (ids) attached at the bottom of their plots."""
+    if not out:
+        return
+    from .colorbar import Bar
+    from .guides import GuideState
+    spot = ("side", "bottom")
+    for a in areas:
+        if a.is_plot:
+            a.state.bars = [GuideState(Bar(b.cb, spot), spot)
+                            if b.inside is not None and id(b.cb) in out else b
+                            for b in a.state.bars]
+
+
+def _solve(fig: Any, areas: list[Area], grid: _Grid, fonts: Any,
+           lanes: list["_Lane"] | None = None) -> tuple[float, float, int]:
+    """Measure and place every area, round after round, until nothing circular changes.
+    ``lanes``: the nodes on the grid lines (figure titles, the main title among them,
+    legends and colorbars; those on top and bottom wrap to their span, which the placed
+    widths give).  Returns the figure size and the number of rounds."""
+    sizes = {id(a): (grid.cw, grid.ch) for a in areas}
+    W = H = 0.0
+    lanes = lanes or []
+    thick = None
+    if lanes:                              # unwrapped until the widths are placed
+        thick = _lane_sizes(fig, lanes, fonts, areas, grid, grid.fw or 0.0, placed=False)
+    first = True
+    out: set[int] = set()                  # inside colorbars moved out
+    phase = 0                              # rounds since a decision changed the inputs
+    for n in range(1, ROUNDS + 1):
+        phase += 1
+        for a in areas:
+            if a.is_plot:
+                prepare(a.state, fonts, *sizes[id(a)])
+        if first:                          # stats binned for the axes sizes measured
+            first = False
+            _place_binned(fig, areas, {id(a): (0.0, 0.0, max(sizes[id(a)][0], 1.0),
+                                               max(sizes[id(a)][1], 1.0)) for a in areas},
+                          lanes)
+        for a in areas:
+            a.bands = _measure_area(a, fonts, *sizes[id(a)])
+            a.margins = a.bands.margins
+        rows.bands(fig, areas, fonts)       # kept on the plots' states too
+        W, H, changed = grid.place(areas, sizes, thick)
+        for a in areas:
+            if a.is_plot:
+                x0, y0, x1, y1 = a.box
+                a.state.box_room = (None if grid.fw is None else x1 - x0,
+                                    None if grid.fh is None else y1 - y0)
+        if changed and phase < SIZE_ROUNDS:
+            continue
+        phase = 0
+        if _place_binned(fig, areas, {id(a): a.axes for a in areas}, lanes):
+            continue
+        if _widths_changed(areas):
+            _rebuild(fig, areas, lanes, out)
+            first = True
+            continue
+        if _choose_bars(areas, fonts, out):
+            continue
+        if _choose_legends(areas, fonts):
+            continue
+        if thick is not None:
+            now = _lane_sizes(fig, lanes, fonts, areas, grid, W)
+            if any(abs(u - v) > TOLERANCE for was, new_ in zip(thick, now)
+                   for u, v in zip(was, new_)):
+                thick = now
+                continue
+        return W, H, n
+    return W, H, ROUNDS
+
+
+# ---------------------------------------------------------------------------
+# Place: geometry records
+# ---------------------------------------------------------------------------
+
+def _place_area(a: Area, fonts: Any, figure_size: tuple[float, float]) -> Any:
+    if a.is_bar:
+        return a.state.place(fonts, a.axes)
+    return place_plot(a.state, fonts, a.axes, figure_size)
+
+
+def _freeze(fig: Any, areas: list[Area], fonts: Any, W: float, H: float, n: int,
+            main: tuple[TitleGeometry, float] | None = None,
+            titles: tuple[TitleGeometry, ...] = (),
+            legends: tuple[FigureLegendGeometry, ...] = (),
+            colorbars: tuple[FigureColorbarGeometry, ...] = ()) -> Geometry:
+    """The figure's geometry record: the areas placed, the lane nodes as placed (the
+    ``main`` title, outermost on top, with its span's length, as the figure's title)."""
+    title, title_at, width, rule = None, (0.0, 0.0), 0.0, None
+    if main is not None:
+        tg, width = main
+        title, title_at, rule = tg.paragraph, tg.at or title_at, tg.rule
+    placed = []
+    for a in areas:
+        g = _place_area(a, fonts, (W, H))
+        placed.append(Placed(a.obj, a.r0, a.c0, a.r1, a.c1, a.axes, a.box, a.margins,
+                             a.bands, a.state, g, a.is_bar))
+    spans, lines, groups = rows.place_figure(fig, fonts, placed)
+    return Geometry(W, H, tuple(placed), FigureGeometry(title, title_at, width, rule,
+                                                        spans, lines, groups, titles,
+                                                        legends, colorbars), n)
+
+
+def layout(fig: Any, fonts: Any, only: Any = None) -> Geometry:
+    """The figure laid out (``only``: one plot of it, alone); text is shaped with ``fonts``
+    (a ``FontDB``, or a canvas whose document's fonts are used)."""
+    with rendering(fig), warnings_once():
+        return _layout(fig, fonts, only)
+
+
+def _layout(fig: Any, fonts: Any, only: Any = None) -> Geometry:
+    areas, nr, nc = arrange(fig, None)
+    grid = _Grid(fig, nr, nc)
+    for a in areas:                        # what stats binned for the axes width read
+        if a.is_plot:                      # before the first round
+            set_boxes(a.obj, axes_width=max(grid.cw, 1.0), axes_height=max(grid.ch, 1.0))
+    build(fig, areas)
+    lanes = lane_titles(fig, areas, nr, nc) if only is None else []
+    W, H, n = _solve(fig, areas, grid, fonts, lanes)
+    if only is not None:
+        return _alone(fig, areas, fonts, only, n)
+    titles, legends, bars, main = _place_lanes(fig, lanes, fonts, areas, grid, W, H)
+    return _freeze(fig, areas, fonts, W, H, n, main, titles, legends, bars)
+
+
+def title_span(title: Any, areas: list[Area], name: str | None = None
+               ) -> tuple[int, int, int, int]:
+    """The grid rectangle ``(r0, c0, r1, c1)`` a figure title covers: the cells of its
+    plots; a plot inside it that the title does not name is an error (naming the title as
+    ``name``, default its repr)."""
+    plots = [a for a in areas if a.is_plot]
+    named = title.plots
+    mine = plots if named is None else [a for a in plots if any(a.obj is p for p in named)]
+    if not mine:
+        raise ValueError(f"{name or repr(title)}: its plots are not in the figure's grid")
+    r0, c0 = min(a.r0 for a in mine), min(a.c0 for a in mine)
+    r1, c1 = max(a.r1 for a in mine), max(a.c1 for a in mine)
+    for a in plots:
+        if any(a is m for m in mine):
+            continue
+        if a.r0 < r1 and r0 < a.r1 and a.c0 < c1 and c0 < a.c1:
+            over = ", ".join(repr(m.obj) for m in mine)
+            raise ValueError(f"{name or repr(title)} over plots {over}: "
+                             f"{a.obj!r} is inside their grid rectangle but not one of them")
+    return r0, c0, r1, c1
+
+
+# ---------------------------------------------------------------------------
+# Lanes: nodes on the grid lines
+# ---------------------------------------------------------------------------
+
+class _Lane:
+    """A node on a grid line: a figure title, legend or colorbar beside a set of plots.
+    Its creation number ``k``, side, grid rectangle ``span`` ``(r0, c0, r1, c1)`` and the
+    plot areas in it; the boundary it sits in (``line``: the row line above its topmost
+    row for a top node, below its bottommost for a bottom one, the column lines likewise),
+    its cells along that line ``[lo, hi)``, its lane there (0 nearest the plots) and
+    whether it wraps (``flow``: on top or bottom, a title unrotated; a legend's entries in
+    rows as wide as its span).  ``outer``: the main title on top, unrotated and without an
+    ``order``: the outermost lane of the top.  :meth:`measure` gives its content and its thickness across the line,
+    :meth:`place` its geometry record from its lane's near edge."""
+
+    __slots__ = ("obj", "k", "side", "span", "plots", "line", "lo", "hi", "lane", "flow",
+                 "outer", "legend", "bar", "drops")
+    #: over the same plots, from the plots outward: legends, colorbars, titles
+    rank = 2
+
+    def __init__(self, obj: Any, k: int, span: tuple[int, int, int, int],
+                 areas: list[Area]) -> None:
+        self.obj, self.k, self.span = obj, k, span
+        self.side = side = obj.resolve("side")
+        r0, c0, r1, c1 = span
+        self.plots = [a for a in areas if a.is_plot and r0 <= a.r0 and a.r1 <= r1
+                      and c0 <= a.c0 and a.c1 <= c1]
+        self.line = {"top": r0, "bottom": r1, "left": c0, "right": c1}[side]
+        self.lo, self.hi = (c0, c1) if side in ("top", "bottom") else (r0, r1)
+        self.lane = 0
+        self.flow = side in ("top", "bottom")
+        self.outer = False
+        self.legend: Any = None
+        self.bar: Any = None
+        self.drops: set[int] = set()
+
+    def overlaps(self, other: "_Lane") -> bool:
+        return self.lo < other.hi and other.lo < self.hi
+
+    def nearer(self, other: "_Lane") -> bool:
+        """Whether it sits nearer the plots than ``other`` by the rules: nested inside it
+        (its plots a subset of the other's), over the same plots a legend before a
+        colorbar before a title, else created first."""
+        mine = {id(a) for a in self.plots}
+        theirs = {id(a) for a in other.plots}
+        if mine != theirs and (mine <= theirs or theirs <= mine):
+            return mine < theirs
+        if mine == theirs and self.rank != other.rank:
+            return self.rank < other.rank
+        return self.k < other.k
+
+    def over(self) -> str:
+        """What it is aligned within along its side: ``"axes"``, ``"plot"`` or
+        ``"figure"``."""
+        return "axes"
+
+    def measure(self, fonts: Any, s0: float, s1: float, placed: bool) -> tuple[Any, float]:
+        """Its content laid out along its span ``[s0, s1]`` (once the areas are
+        ``placed``; before, unwrapped) and the thickness of its lane."""
+        raise NotImplementedError
+
+    def place(self, fonts: Any, near: float, s0: float, s1: float, content: Any,
+              room: tuple[float, float]) -> Any:
+        """Its geometry record: its lane's near edge at ``near`` across its side, its span
+        ``[s0, s1]``, its ``content`` as measured; ``room``: the figure's content along
+        its side (within the margins)."""
+        raise NotImplementedError
+
+
+class _TitleLane(_Lane):
+    """A figure title in a lane (the main title, others, a group's label)."""
+
+    __slots__ = ("font", "laid")
+
+    def __init__(self, obj: Any, k: int, span: tuple[int, int, int, int],
+                 areas: list[Area], main: bool = False) -> None:
+        super().__init__(obj, k, span, areas)
+        self.font = title_font(obj)
+        self.laid: tuple[float, Any] | None = None     # the last paragraph and its width
+        self.flow = self.flow and rotation_of(obj) == 0
+        self.outer = main and self.side == "top" and self.flow \
+            and obj.resolve("order") is None
+
+    def over(self) -> str:
+        return self.obj.resolve("over")
+
+    def measure(self, fonts: Any, s0: float, s1: float, placed: bool) -> tuple[Any, float]:
+        t = self.obj
+        if self.flow:
+            width = max(s1 - s0, 1.0) if placed else 1e6
+            if self.laid is None or self.laid[0] != width:
+                self.laid = (width, paragraph(fonts, t, width))
+            text = self.laid[1]
+            return text, t.resolve("pad") + text.height + rule_extent(t)
+        b = block(fonts, t.resolve("text"), self.font)
+        return b, _title_need(t, b, self.side)[0]
+
+    def place(self, fonts: Any, near: float, s0: float, s1: float, content: Any,
+              room: tuple[float, float]) -> TitleGeometry:
+        t, side = self.obj, self.side
+        sign = -1.0 if side in ("top", "left") else 1.0
+        near += sign * (t.resolve("pad") + rule_inside(t))
+        if self.flow:
+            para = content
+            across = para.height
+            y = near - across if side == "top" else near
+            x = {"start": s0, "center": (s0 + s1 - para.width) / 2,
+                 "end": s1 - para.width}[along(t)]
+            return TitleGeometry(t, side, self.lane, (x, y, para.width, para.height), (),
+                                 rule_rect(t, side, near, across, s0, s1), para, (s0, y))
+        runs, box_ = _title_runs(fonts, content, self.font, side, rotation_of(t), along(t),
+                                 near, s0, s1)
+        across = _title_need(t, content, side)[1]
+        return TitleGeometry(t, side, self.lane, box_, runs,
+                             rule_rect(t, side, near, across, s0, s1))
+
+
+class _LegendLane(_Lane):
+    """A figure legend in a lane (``legend``: its :class:`~plot_io.guides.GuideState`)."""
+
+    __slots__ = ()
+    rank = 0
+
+    def measure(self, fonts: Any, s0: float, s1: float, placed: bool) -> tuple[Any, float]:
+        w, h = self.legend.measure(fonts, max(s1 - s0, 1.0), max(s1 - s0, 1.0), placed)
+        return (w, h), self.obj.resolve("pad") + (h if self.flow else w)
+
+    def place(self, fonts: Any, near: float, s0: float, s1: float, content: Any,
+              room: tuple[float, float]) -> FigureLegendGeometry:
+        side, flat = self.side, self.flow
+        near += (-1.0 if side in ("top", "left") else 1.0) * self.obj.resolve("pad")
+        w, h = content
+        length = w if flat else h
+        start = {"start": s0, "center": (s0 + s1 - length) / 2,
+                 "end": s1 - length}[self.obj.along()]
+        start = max(room[0], min(start, room[1] - length))
+        if flat:
+            x, y = start, (near - h if side == "top" else near)
+        else:
+            x, y = (near - w if side == "left" else near), start
+        return FigureLegendGeometry(self.legend, side, self.lane,
+                                    self.legend.place(fonts, (x, y, x + w, y + h)))
+
+
+class _BarLane(_Lane):
+    """A figure colorbar in a lane (``bar``: its :class:`~plot_io.guides.GuideState`;
+    ``drops``: the ids of the attached colorbars it shows instead)."""
+
+    __slots__ = ()
+    rank = 1
+
+    def __init__(self, obj: Any, k: int, span: tuple[int, int, int, int],
+                 areas: list[Area], bar: Any) -> None:
+        super().__init__(obj, k, span, areas)
+        self.bar = bar
+        self.flow = False
+
+    def measure(self, fonts: Any, s0: float, s1: float, placed: bool) -> tuple[Any, float]:
+        return None, self.bar.measure(fonts, max(s1 - s0, 1.0), max(s1 - s0, 1.0), placed)
+
+    def place(self, fonts: Any, near: float, s0: float, s1: float, content: Any,
+              room: tuple[float, float]) -> FigureColorbarGeometry:
+        near += (-1.0 if self.side in ("top", "left") else 1.0) * self.bar.lane_pad()
+        line = (near, s0, near, s1) if self.side in ("left", "right") else (s0, near, s1, near)
+        return FigureColorbarGeometry(self.side, self.lane, self.bar.place(fonts, line))
+
+
+def lane_titles(fig: Any, areas: list[Area], nr: int, nc: int) -> list[_Lane]:
+    """The nodes on the grid lines of an ``nr`` × ``nc`` grid: the figure titles with text
+    (the main title over every plot, the whole grid without plots; the groups' labels:
+    :meth:`plot_io.rows.FigureGroup.title`), the figure legends with entries and the
+    figure colorbars, their spans checked (:func:`title_span`), each in its lane."""
+    out: list[_Lane] = []
+    plots = any(a.is_plot for a in areas)
+    for t in fig.titles:
+        if t.resolve("text") is None:
+            continue
+        main = t is fig.title
+        span = title_span(t, areas) if plots or not main else (0, 0, nr, nc)
+        out.append(_TitleLane(t, t._made, span, areas, main))
+    for g in fig.groups:
+        t = g.title()
+        if t is None:
+            continue
+        span = title_span(t, areas, f"group label {t.resolve('text')!r}")
+        out.append(_TitleLane(t, t._made, span, areas))
+    out += _legend_lanes(fig, areas)
+    out += _colorbar_lanes(fig, areas)
+    stacks: dict[tuple[str, int], list[_Lane]] = {}
+    for lt in out:
+        stacks.setdefault((lt.side, lt.line), []).append(lt)
+    for stack in stacks.values():
+        _stack(stack)
+    return out
+
+
+def _legend_lanes(fig: Any, areas: list[Area]) -> list[_Lane]:
+    """The figure legends with entries: those of ``add_legend``, then those
+    ``share_legend`` makes for its groups of plots (:func:`plot_io.sharing.groups`; a group
+    with a plot an ``add_legend`` legend covers makes none): one on the right of each row
+    (``"row"``) or of the figure (``"all"``), one at the bottom of each column
+    (``"col"``)."""
+    from .plot import FigureLegend
+    from .sharing import groups
+    lanes: list[_Lane] = [_LegendLane(g, g._made, title_span(g, areas), areas) for g in fig.legends]
+    covered = {id(a) for lt in lanes for a in lt.plots}
+    side = "bottom" if fig.resolve("share_legend") == "col" else "right"
+    for members, _ in groups(fig, areas, "legend"):
+        if any(id(a) in covered for a in members):
+            continue
+        g = FigureLegend(fig, [a.obj for a in sorted(members, key=lambda a: (a.r0, a.c0))],
+                         side=side)
+        lanes.append(_LegendLane(g, g._made, title_span(g, areas), areas))
+    _share_legends(lanes, areas)
+    return [lt for lt in lanes if lt.legend.active()]
+
+
+def _colorbar_lanes(fig: Any, areas: list[Area]) -> list[_Lane]:
+    """The figure colorbars: those of ``add_colorbar``, then one per shared color (size)
+    axis whose plots have attached colorbars (size keys) of it: per group of
+    ``share_color`` (``share_size``; on the right of a row or of the figure, at the bottom
+    of a column), then per axis shown by the attached colorbars of two plots or more
+    (``figure.color_axis()``, ``figure.size_axis()``; at the bottom of a column, else on
+    the right).  Each takes the attached colorbars of its axis out of its plots (but those
+    whose ``side`` is set); plots that are not a grid rectangle keep theirs."""
+    from .colorbar import FigureColorbar
+    from .guides import GuideState
+    from .mapped import trained
+    from .sharing import groups
+
+    def axis_of(b: Any) -> int:
+        return id(trained(b.axis))
+
+    attached = [(a, b) for a in areas if a.is_plot for b in a.state.bars
+                if not b.cb.is_set("side")]
+    lanes: list[_Lane] = [_BarLane(cb, cb._made, title_span(cb, areas), areas, GuideState.for_colorbar(cb))
+             for cb in fig.colorbars]
+    taken: set[int] = set()
+    for lt in lanes:
+        mine, shown = {id(a) for a in lt.plots}, axis_of(lt.bar)
+        lt.drops = {id(b.cb) for a, b in attached if id(a) in mine and axis_of(b) == shown}
+        taken |= lt.drops
+
+    def make(members: list[Area], pairs: list[tuple[Area, Any]], side: str) -> None:
+        first = pairs[0][1].cb
+        settings = {k: v for k, v in first._values.items()
+                    if k not in ("side", "align", "order", "pad", "orientation")}
+        plots = [a.obj for a in sorted(members, key=lambda a: (a.r0, a.c0))]
+        cb = FigureColorbar(fig, first.shown(), plots, side=side, **settings)
+        cb.marks = first.marks
+        try:
+            span = title_span(cb, areas)
+        except ValueError:                          # not a grid rectangle: kept attached
+            return
+        lt = _BarLane(cb, cb._made, span, areas, GuideState.for_colorbar(cb))
+        lt.drops = {id(b.cb) for _, b in pairs}
+        taken.update(lt.drops)
+        lanes.append(lt)
+
+    for role in ("color", "size"):
+        side = "bottom" if fig.resolve(f"share_{role}") == "col" else "right"
+        for members, _ in groups(fig, areas, role):
+            ids = {id(a) for a in members}
+            by_axis: dict[int, list[tuple[Area, Any]]] = {}
+            for a, b in attached:
+                if id(a) in ids and id(b.cb) not in taken and b.sizes == (role == "size"):
+                    by_axis.setdefault(axis_of(b), []).append((a, b))
+            for pairs in by_axis.values():
+                make(members, pairs, side)
+    by_axis = {}
+    for a, b in attached:
+        if id(b.cb) not in taken:
+            by_axis.setdefault(axis_of(b), []).append((a, b))
+    for pairs in by_axis.values():
+        members = list({id(a): a for a, _ in pairs}.values())
+        if len(members) > 1:
+            column = len({(a.c0, a.c1) for a in members}) == 1
+            make(members, pairs, "bottom" if column else "right")
+    _drop_bars(lanes, areas)
+    return lanes
+
+
+def _drop_bars(lanes: list[_Lane], areas: list[Area]) -> None:
+    """Take the attached colorbars that figure colorbars show out of their plots."""
+    drops = set().union(*(lt.drops for lt in lanes))
+    if drops:
+        for a in areas:
+            if a.is_plot:
+                a.state.bars = [b for b in a.state.bars if id(b.cb) not in drops]
+
+
+def _main_plot(plot: Any) -> Any:
+    twin = getattr(plot, "twin_of", None)
+    return twin[0] if twin else plot
+
+
+def _hidden_legend(plot: Any) -> bool:
+    lg = plot.legend
+    return lg.is_set("visible") and not lg.resolve("visible")
+
+
+def _share_legends(lanes: list[_Lane], areas: list[Area]) -> None:
+    """Collect the figure legends' entries from their plots' states (row by row, then in
+    series order; the same label and symbol once), and take them out of those plots'
+    legends unless a plot's legend has its place set (``inside``, ``side``, ``visible``);
+    a plot whose legend is hidden (``visible=False``) gives none; a size key whose series'
+    plots a figure legend covers goes into the first such legend instead of a plot
+    legend."""
+    from .guides import GuideState
+    from .legend import group_key
+    legends = sorted((lt for lt in lanes if _is_legend(lt.obj)), key=lambda lt: lt.k)
+    if not legends:
+        return
+    for lt in legends:
+        plots = sorted(lt.plots, key=lambda a: (a.r0, a.c0))
+        lt.legend = GuideState.for_figure_legend(
+            lt.obj, [a.state for a in plots if not _hidden_legend(a.obj)])
+        for a in plots:
+            if not a.obj.legend.is_placed():
+                a.state.legend.content.shared = True
+    r = current()
+    states = {id(st.plot): st for a in areas if a.is_plot for st in [a.state, *a.state.twins]}
+    for g in (r.size_keys.values() if r is not None else ()):
+        if g.plot is None:
+            continue
+        owners = {id(_main_plot(s.plot)) for s in g.listed}
+        into = next((lt for lt in legends if owners <= {id(a.obj) for a in lt.plots}), None)
+        if into is None:
+            continue
+        into.legend.keys.append(group_key(g, g.plot))
+        st = states.get(id(_main_plot(g.plot)))
+        if st is not None and not _main_plot(g.plot).legend.is_placed():
+            st.legend.content.keys = [k for k in st.legend.keys if k.series is not g.listed]
+    for lt in legends:
+        lt.legend.compose()
+    for st in states.values():
+        st.legend.compose()
+
+
+def _is_legend(obj: Any) -> bool:
+    from .plot import FigureLegend
+    return isinstance(obj, FigureLegend)
+
+
+def _pack(ordered: list[_Lane], tiers: list[Any] | None = None) -> None:
+    """Lanes in this order, from the plots outward: each title in the first lane past
+    those of the titles before it whose spans overlap its own (disjoint spans share), and
+    with ``tiers`` (one per title, ascending), past every lane of a lower tier."""
+    done: list[tuple[_Lane, Any]] = []
+    for i, lt in enumerate(ordered):
+        tier = None if tiers is None else tiers[i]
+        lt.lane = 1 + max((d.lane for d, dt in done
+                           if d.overlaps(lt) or (tier is not None and dt < tier)), default=-1)
+        done.append((lt, tier))
+
+
+def _stack(stack: list[_Lane]) -> None:
+    """The lanes of one side of one boundary: nested titles nearer the plots, overlapping
+    ones in creation order, disjoint ones side by side; then ``order`` (lower nearer, unset:
+    the lane the rules give): a title sits past every lane of a lower order, titles of
+    one order side by side where their spans are disjoint.  An ``outer`` node (the main
+    title) is past them all."""
+    outer = [t for t in stack if t.outer]
+    stack = [t for t in stack if not t.outer]
+    rest = sorted(stack, key=lambda t: t.k)
+    ordered = []
+    while rest:
+        ready = [t for t in rest
+                 if not any(s is not t and s.overlaps(t) and s.nearer(t) for s in rest)]
+        t = (ready or rest)[0]
+        ordered.append(t)
+        rest.remove(t)
+    _pack(ordered)
+    orders = [t.obj.resolve("order") for t in stack]
+    if any(o is not None for o in orders):
+        rank = {id(t): (t.lane if o is None else o, t.lane, t.k) for t, o in zip(stack, orders)}
+        ordered = sorted(stack, key=lambda t: rank[id(t)])
+        _pack(ordered, [rank[id(t)][0] for t in ordered])
+    for t in outer:
+        t.lane = 1 + max((s.lane for s in stack), default=-1)
+
+
+def _lane_span(fig: Any, lt: _Lane, W: float, H: float) -> tuple[float, float]:
+    """The span a node is aligned (and wrapped) within, along its side: from the first
+    axes it covers to the last (``over="axes"``), their boxes (``"plot"``) or the figure
+    within its margin (``"figure"``, or without plots)."""
+    over = lt.over()
+    across = lt.side in ("top", "bottom")
+    if over == "figure" or not lt.plots:
+        length = W if across else H
+        m = fig.resolve("margin", of=length)
+        return m, length - m
+    rects = [a.axes if over == "axes" else a.box for a in lt.plots]
+    if across:
+        return min(r[0] for r in rects), max(r[2] for r in rects)
+    return min(r[1] for r in rects), max(r[3] for r in rects)
+
+
+def _lane_sizes(fig: Any, lanes: list[_Lane], fonts: Any, areas: list[Area], grid: _Grid,
+                W: float, placed: bool = True) -> tuple[list[float], ...]:
+    """The lanes' thickness per line between columns and between rows: per side of a
+    line, the sum of its lanes, each as thick as its thickest node (titles and legends on
+    top and bottom wrapped to their span as ``placed``, else unwrapped).  Once ``placed``,
+    a legend longer than the figure's content along its side adds what it lacks to the
+    last line (the bottom, or the right).  Then, per line between columns and between
+    rows, 1 where a margin parts its lanes from the plots: where a node but an ``outer``
+    one is (the main title alone on top sits against the plots' boxes, past its
+    ``pad``)."""
+    thick = _thickness(fig, lanes, fonts, W, 0.0, placed)[0]
+    xs, ys = _totals(thick, grid)
+    if placed:
+        inner = _totals(thick, grid, _outer(lanes))
+        for across, totals in ((True, xs), (False, ys)):
+            need = max((_along(lt) for lt in lanes if lt.legend is not None
+                        and (lt.side in ("top", "bottom")) == across), default=0.0)
+            if need:
+                lo, hi = _extent(areas, grid, inner, across)
+                totals[-1] += max(0.0, need - (hi - lo))
+    xa = [0.0] * (grid.nc + 1)
+    ya = [0.0] * (grid.nr + 1)
+    for lt in lanes:
+        if not lt.outer:
+            (ya if lt.side in ("top", "bottom") else xa)[lt.line] = 1.0
+    return xs, ys, xa, ya
+
+
+def _outer(lanes: list[_Lane]) -> set[tuple[str, int, int]]:
+    """The lanes ``(side, line, lane)`` of the ``outer`` nodes."""
+    return {(lt.side, lt.line, lt.lane) for lt in lanes if lt.outer}
+
+
+def _totals(thick: dict[tuple[str, int], dict[int, float]], grid: _Grid,
+            skip: frozenset[tuple[str, int, int]] | set[tuple[str, int, int]] = frozenset()) -> tuple[list[float], list[float]]:
+    """The lanes' thickness summed per line between columns and between rows (but the
+    lanes in ``skip``)."""
+    xs = [0.0] * (grid.nc + 1)
+    ys = [0.0] * (grid.nr + 1)
+    for (side, line), sizes in thick.items():
+        (ys if side in ("top", "bottom") else xs)[line] += sum(
+            v for j, v in sizes.items() if (side, line, j) not in skip)
+    return xs, ys
+
+
+def _extent(areas: list[Area], grid: _Grid, totals: tuple[list[float], list[float]],
+            across: bool) -> tuple[float, float]:
+    """The figure's content along x (``across``) or y: the areas' boxes and the lanes of
+    the outer lines, with the margin between them and the plots."""
+    xs, ys = totals
+    if across:
+        lo = min(a.box[0] for a in areas) - xs[0] - (grid.mx if xs[0] else 0.0)
+        return lo, max(a.box[2] for a in areas) + xs[-1] + (grid.mx if xs[-1] else 0.0)
+    lo = min(a.box[1] for a in areas) - ys[0] - (grid.my if ys[0] else 0.0)
+    return lo, max(a.box[3] for a in areas) + ys[-1] + (grid.my if ys[-1] else 0.0)
+
+
+def _along(lt: _Lane) -> float:
+    """A legend's length along its side (as last measured)."""
+    w, h = lt.legend.size
+    return w if lt.side in ("top", "bottom") else h
+
+
+def _thickness(fig: Any, lanes: list[_Lane], fonts: Any, W: float, H: float,
+               placed: bool) -> tuple[dict[tuple[str, int], dict[int, float]],
+                                      dict[int, tuple[float, float, Any]]]:
+    """Per side and line, each lane's thickness; per node, its span and laid-out
+    content (wrapped to the span once ``placed``; before, unwrapped, but an ``outer``
+    node in a figure ``W`` wide)."""
+    thick: dict[tuple[str, int], dict[int, float]] = {}
+    texts: dict[int, tuple[float, float, Any]] = {}
+    for lt in lanes:
+        s0, s1 = _lane_span(fig, lt, W, H)
+        wrap = placed
+        if not placed and lt.outer and W > 0:      # the main title, first wrapped to a
+            m = fig.resolve("margin", of=W)         # figure's given width
+            s0, s1, wrap = m, W - m, True
+        content, need = lt.measure(fonts, s0, s1, wrap)
+        texts[id(lt)] = (s0, s1, content)
+        sizes = thick.setdefault((lt.side, lt.line), {})
+        sizes[lt.lane] = max(sizes.get(lt.lane, 0.0), need)
+    return thick, texts
+
+
+def paragraph(fonts: Any, t: Any, width: float) -> Any:
+    """Figure title ``t`` laid out ``width`` wide (``vec_io.text`` paragraphs, drawn as
+    they are)."""
+    from .text import paragraphs
+    return paragraphs(fonts, t.resolve("text"), title_font(t), max(width, 1.0), along(t))
+
+
+def _lane_edge(lt: _Lane, lanes: list[_Lane], areas: list[Area], grid: _Grid) -> float:
+    """Where a node's lanes start, across its side: the boxes of the plots on its line
+    (the outermost of them; without areas there, the grid's cells), past the figure's
+    margin on an outer line unless only ``outer`` nodes are there."""
+    side, line = lt.side, lt.line
+    on = {"top": lambda a: a.r0 == line, "bottom": lambda a: a.r1 == line,
+          "left": lambda a: a.c0 == line, "right": lambda a: a.c1 == line}[side]
+    boxes = [a.box for a in areas if on(a)] or [a.box for a in lt.plots]
+    if not boxes:
+        xs, ys = grid.cells
+        boxes = [(xs[0], ys[0], xs[-1], ys[-1])]
+    apart = any(o.side == side and o.line == line and not o.outer for o in lanes)
+    my = grid.my if apart else 0.0
+    mx = grid.mx if apart else 0.0
+    if side == "top":
+        return min(b[1] for b in boxes) - (my if line == 0 else 0.0)
+    if side == "bottom":
+        return max(b[3] for b in boxes) + (my if line == grid.nr else 0.0)
+    if side == "left":
+        return min(b[0] for b in boxes) - (mx if line == 0 else 0.0)
+    return max(b[2] for b in boxes) + (mx if line == grid.nc else 0.0)
+
+
+def _place_lanes(fig: Any, lanes: list[_Lane], fonts: Any, areas: list[Area], grid: _Grid,
+                 W: float, H: float) -> tuple[tuple[TitleGeometry, ...],
+                                              tuple[FigureLegendGeometry, ...],
+                                              tuple[FigureColorbarGeometry, ...],
+                                              tuple[TitleGeometry, float] | None]:
+    """The nodes on the grid lines placed, in creation order: each lane past the nearer
+    lanes of its side and line, each node against the
+    near edge of its lane, aligned along its span.  The main title, when ``outer``, comes
+    last, with its span's length."""
+    thick, texts = _thickness(fig, lanes, fonts, W, H, True)
+    xs, ys = _totals(thick, grid, _outer(lanes))
+    titles = []
+    legends = []
+    bars = []
+    main = None
+    for lt in sorted(lanes, key=lambda t: t.k):
+        side = lt.side
+        sizes = thick[(side, lt.line)]
+        sign = -1.0 if side in ("top", "left") else 1.0
+        near = _lane_edge(lt, lanes, areas, grid) + sign * sum(
+            sizes.get(j, 0.0) for j in range(lt.lane))
+        s0, s1, content = texts[id(lt)]
+        room = (0.0, 0.0)
+        if lt.legend is not None:          # within the figure's content and margin
+            flat = side in ("top", "bottom")
+            room = (_extent(areas, grid, (xs, ys), flat)[0],
+                    (W - grid.mx) if flat else (H - grid.my))
+        g = lt.place(fonts, near, s0, s1, content, room)
+        if isinstance(lt, _LegendLane):
+            legends.append(g)
+        elif isinstance(lt, _BarLane):
+            bars.append(g)
+        elif lt.outer and lt.obj is fig.title:
+            main = (g, s1 - s0)
+        else:
+            titles.append(g)
+    return tuple(titles), tuple(legends), tuple(bars), main
+
+
+def _alone(fig: Any, areas: list[Area], fonts: Any, only: Any, n: int) -> Geometry:
+    """Plot ``only`` of the laid-out figure, alone at its size in the figure, with its
+    outer labels and its own row label band: its axes keep their size (``align="axes"``:
+    measured once), or its box does (``"borders"``: the axes are what the margins leave,
+    in rounds as the figure's, from the box)."""
+    target = next(a for a in areas if a.obj is only)
+    rect = target.axes if fig.resolve("align") == "axes" else target.box
+    st = target.state
+    st.x.hide_labels = st.y.hide_labels = False
+    single = Area(only, 0, 0, 1, 1)
+    single.state = st
+    grid = _Grid(fig, 1, 1, fixed=(rect[2] - rect[0], rect[3] - rect[1]))
+    sizes = {id(single): (grid.cw, grid.ch)}
+    W = H = 0.0
+    for _ in range(SIZE_ROUNDS):
+        w, h = sizes[id(single)]
+        prepare(st, fonts, w, h)
+        single.bands = measure(st, fonts, w, h)
+        single.margins = single.bands.margins
+        rows.bands(fig, [single], fonts)
+        W, H, changed = grid.place([single], sizes)
+        if not changed:
+            break
+    return _freeze(fig, [single], fonts, W, H, n)