adapters: route pointer events by cell rect

adapters/glfw/glfw_host.hpp

@@ -121,18 +121,21 @@ class Host {
   /// `plot_` is then untouched by any of this.
   void set_figure(Figure* figure) noexcept;
   Figure* figure() noexcept { return figure_; }
-  /// One figure row's controller -- the one a gesture on that row reaches -- or
-  /// null while no figure is set or the row does not exist. A host reads a drag
+  /// One figure plot's controller -- the one a gesture on that plot reaches -- or null
+  /// while no figure is set or it does not exist. `row` is the **flattened plot index**
+  /// (`Figure::plot_count()` of them: the row count when no row holds several cells). A host reads a drag
   /// mode or a hover out of it (`controller()` is the single-plot loop's, and is
   /// not the one figure gestures go to).
   input::Controller* row_controller(u32 row) noexcept;
   /// The controller an event at framebuffer pixel (x, y) belongs to: `controller_` --
   /// the single-plot loop -- while no figure is set, and the controller of the figure
-  /// row that pixel lands in otherwise. The row rects come from the cache
+  /// plot (cell) that pixel lands in otherwise -- x and y both pick it, as a row may hold
+  /// several cells side by side. The cell rects come from the cache
   /// `refresh_row_rects()` fills -- the same ones the renderer draws -- so a gesture
   /// lands on the row it was aimed at and no event lays the figure out; a pixel
-  /// inside no row -- the row gap a host asked for with `Figure::set_row_gap()`,
-  /// or a margin -- is the *nearest* row rather than dropped or defaulted, so a drag
+  /// inside no cell -- the row or column gap a host asked for with
+  /// `Figure::set_row_gap()`/`set_col_gap()`, or a margin -- is the *nearest* cell rather than
+  /// dropped or defaulted, so a drag
   /// that leaves the data area still ends where it should.
   ///
   /// It also hands that row its own viewport, which is what keeps the controller's
@@ -217,11 +220,12 @@ class Host {
   void on_scroll(f64 dx, f64 dy) noexcept;
   void on_key(int key, int action, int mods) noexcept;
 
-  /// The index of the row of `rows` a framebuffer y belongs to: the row it is in, or the nearest
-  /// row when it is in none (a row gap, a margin outside the figure). One rule, shared by the event
-  /// routing and the crosshair sync -- and taking the rects rather than reading them, so a caller
-  /// that has just laid the figure out does not make it lay out again for this.
-  static u32 row_in(const std::vector<Rect>& rows, f32 y) noexcept;
+  /// The index of the cell of `rows` (the figure's flattened cell rects) a framebuffer pixel
+  /// belongs to: the cell it is in, or the nearest cell when it is in none (a row or column gap,
+  /// a margin outside the figure). One rule, shared by the event routing and the crosshair sync
+  /// -- and taking the rects rather than reading them, so a caller that has just laid the figure
+  /// out does not make it lay out again for this.
+  static u32 row_in(const std::vector<Rect>& rows, f32 x, f32 y) noexcept;
 
   /// The controller a pointer event at (x, y) belongs to, applying the button capture:
   /// a press claims the row it landed in (`captured_row_` + `captured_button_`) and
@@ -231,10 +235,10 @@ class Host {
   input::Controller& pointer_target(f32 x, f32 y, input::Button button, bool pressed,
                                     bool released) noexcept;
 
-  /// The row the pointer's events currently go to: the captured row while a drag owns
-  /// the button, the row under the pointer otherwise. The run loop uses it to clear
-  /// every *other* row's hot handles, so a row the pointer left cannot keep drawing a
-  /// hover or a grab it last published.
+  /// The plot (flattened index) the pointer's events currently go to: the captured one
+  /// while a drag owns the button, the one under the pointer otherwise. The run loop uses
+  /// it to clear every *other* plot's hot handles, so one the pointer left cannot keep
+  /// drawing a hover or a grab it last published.
   u32 pointer_row(const std::vector<Rect>& rows) noexcept;
 
   /// Spreads the hover over a whole `Figure` (spec §15).
@@ -292,7 +296,7 @@ class Host {
   u32 captured_row_ = 0u;
   input::Button captured_button_ = input::Button::Left;
 
-  /// The figure's row rects as of the last `refresh_row_rects()` -- the cache the
+  /// The figure's cell rects (one per plot, flattened; the row rects when no row is split) as of the last `refresh_row_rects()` -- the cache the
   /// event routing reads instead of laying the figure out per event (R7). Filled by
   /// `set_figure()` and once per frame by the run loop; empty while no figure is
   /// set, which is the state `controller_at()`/`pointer_target()` fall back to the