@perspective-dev/viewer 5.1.0 → 5.2.0

package/src/rust/components/window_editor.rs

@@ -13,9 +13,7 @@
 use std::collections::HashSet;
 use std::rc::Rc;
 
-use perspective_client::config::{
-    ColumnType, WindowAggregate, WindowFrame, WindowSort, WindowSortDir, WindowSpec,
-};
+use perspective_client::config::{ColumnType, WindowFrame, WindowSort, WindowSortDir, WindowSpec};
 use wasm_bindgen::JsCast;
 use web_sys::{DragEvent, HtmlInputElement, MouseEvent};
 use yew::prelude::*;
@@ -30,63 +28,33 @@ use crate::presentation::Presentation;
 use crate::session::{Session, SessionMetadataRc};
 use crate::utils::{AddListener, DragEffect, DragTarget, Subscription};
 
-fn op_label(op: WindowAggregate) -> &'static str {
-    match op {
-        WindowAggregate::Sum => "sum",
-        WindowAggregate::Avg => "avg",
-        WindowAggregate::Count => "count",
-        WindowAggregate::Min => "min",
-        WindowAggregate::Max => "max",
-        WindowAggregate::Stddev => "stddev",
-        WindowAggregate::Var => "var",
-        WindowAggregate::First => "first",
-        WindowAggregate::Last => "last",
-        WindowAggregate::Lag => "lag",
-        WindowAggregate::Lead => "lead",
-        WindowAggregate::Diff => "diff",
-        WindowAggregate::Rate => "rate",
-        WindowAggregate::Ema => "ema",
-    }
-}
-
-fn op_from_label(label: &str) -> Option<WindowAggregate> {
-    Some(match label {
-        "sum" => WindowAggregate::Sum,
-        "avg" => WindowAggregate::Avg,
-        "count" => WindowAggregate::Count,
-        "min" => WindowAggregate::Min,
-        "max" => WindowAggregate::Max,
-        "stddev" => WindowAggregate::Stddev,
-        "var" => WindowAggregate::Var,
-        "first" => WindowAggregate::First,
-        "last" => WindowAggregate::Last,
-        "lag" => WindowAggregate::Lag,
-        "lead" => WindowAggregate::Lead,
-        "diff" => WindowAggregate::Diff,
-        "rate" => WindowAggregate::Rate,
-        "ema" => WindowAggregate::Ema,
-        _ => return None,
-    })
+/// The declared capabilities of one window aggregate, for a `source` column
+/// type. Which controls an aggregate needs is the data model's to state - the
+/// editor cannot infer it from a name it has never seen.
+fn op_spec(
+    metadata: &SessionMetadataRc,
+    source: &str,
+    op: &str,
+) -> Option<perspective_client::proto::WindowAggregateArgs> {
+    let ty = metadata.get_column_table_type(source)?;
+    metadata.get_window_aggregate(ty, op)
 }
 
-fn is_aggregating(op: WindowAggregate) -> bool {
-    matches!(
-        op,
-        WindowAggregate::Sum
-            | WindowAggregate::Avg
-            | WindowAggregate::Count
-            | WindowAggregate::Min
-            | WindowAggregate::Max
-            | WindowAggregate::Stddev
-            | WindowAggregate::Var
-    )
+/// The editor's frame-type labels, as the `frames` a declaration lists.
+fn frame_label(frame: &str) -> &'static str {
+    match frame {
+        "rows" => "Rows",
+        "range" => "Range",
+        _ => "Cumulative",
+    }
 }
 
-fn is_positional(op: WindowAggregate) -> bool {
-    matches!(
-        op,
-        WindowAggregate::Lag | WindowAggregate::Lead | WindowAggregate::Diff
-    )
+fn frame_name(label: &str) -> &'static str {
+    match label {
+        "Rows" => "rows",
+        "Range" => "range",
+        _ => "cumulative",
+    }
 }
 
 fn is_orderable_for_range(ty: ColumnType) -> bool {
@@ -182,7 +150,7 @@ impl WindowDraft {
         };
 
         Self {
-            op: op_label(spec.aggregate).to_string(),
+            op: spec.aggregate.clone(),
             source: spec.column.clone(),
             order_by: spec
                 .order_by
@@ -212,7 +180,7 @@ impl WindowDraft {
     }
 
     fn validate(&self, metadata: &SessionMetadataRc) -> Result<WindowSpec, String> {
-        let op = op_from_label(&self.op).ok_or("Unknown op")?;
+        let op = self.op.clone();
 
         // Every slot takes true `Table` columns ONLY - expression aliases
         // and other window columns would create dependency cycles (and
@@ -245,18 +213,13 @@ impl WindowDraft {
 
         // Backstop for API-authored specs opened in the editor - the op
         // menu only offers the feature-declared set, so this is
-        // unreachable from the UI.
-        let available = metadata
-            .get_features()
-            .map(|x| x.get_window_aggregates(source_ty))
-            .unwrap_or_default();
-
-        if !available.contains(&op) {
-            return Err(format!(
-                "\"{}\" is not a supported window aggregate for this column",
-                op_label(op)
-            ));
-        }
+        // unreachable from the UI. The declaration also supplies the
+        // controls this op takes, below.
+        let declared = metadata
+            .get_window_aggregate(source_ty, &op)
+            .ok_or_else(|| {
+                format!("\"{op}\" is not a supported window aggregate for this column")
+            })?;
 
         // An EMPTY order slot is valid when the backend has a natural row
         // order to fall back on (primary key order in the engine, `rowid`
@@ -300,11 +263,15 @@ impl WindowDraft {
 
         // The numeric fields are typed and input-clamped to their domains,
         // so no parse or range errors are reachable here.
-        let frame = if is_aggregating(op) || op == WindowAggregate::Rate {
+        let frame = if declared.frames.is_empty() {
+            None
+        } else {
+            let chosen = frame_name(&self.frame_type);
+            if !declared.frames.iter().any(|x| x == chosen) {
+                return Err(format!("\"{op}\" does not support a {chosen} frame"));
+            }
+
             match self.frame_type.as_str() {
-                "Rows" | "Cumulative" if op == WindowAggregate::Rate => {
-                    return Err("\"rate\" requires a range frame".to_string());
-                },
                 "Rows" => Some(WindowFrame::Rows(self.frame_rows)),
                 "Range" => {
                     // The natural-order fallback has no units, so `range`
@@ -323,15 +290,13 @@ impl WindowDraft {
                 },
                 _ => None,
             }
-        } else {
-            None
         };
 
         // Emit `None` at the engine default so a spec saved without an
         // explicit `offset` round-trips unchanged (the name-stripped
         // change-detection baseline compares specs structurally).
-        let offset = (is_positional(op) && self.offset != 1).then_some(self.offset);
-        let alpha = (op == WindowAggregate::Ema).then_some(self.alpha);
+        let offset = (declared.offset && self.offset != 1).then_some(self.offset);
+        let alpha = declared.alpha.then_some(self.alpha);
 
         let mut partition_by = self.partition_by.clone();
         partition_by.retain(|col| !col.is_empty());
@@ -676,12 +641,10 @@ impl Component for WindowEditor {
                             })
                             .unwrap_or_default();
 
-                        if !op_from_label(&self.draft.op)
-                            .map(|op| available.contains(&op))
-                            .unwrap_or_default()
+                        if !available.iter().any(|x| x.name == self.draft.op)
                             && let Some(first) = available.first()
                         {
-                            self.draft.op = op_label(*first).to_string();
+                            self.draft.op = first.name.clone();
                         }
                     },
                     DragTarget::WindowOrderBy => self.draft.order_by = column,
@@ -698,11 +661,19 @@ impl Component for WindowEditor {
             WindowEditorMsg::SetOp(op) => {
                 self.draft.op = op;
 
-                // Keep the frame coherent as the op class changes (`rate`
-                // requires a Range frame; the frame-type dropdown omits the
-                // rest).
-                if op_from_label(&self.draft.op) == Some(WindowAggregate::Rate) {
-                    self.draft.frame_type = "Range".to_string();
+                // Keep the frame coherent as the op changes - an op that
+                // does not accept the current frame kind coerces to its
+                // first declared one (the dropdown omits the rest).
+                if let Some(declared) =
+                    op_spec(&ctx.props().metadata, &self.draft.source, &self.draft.op)
+                    && !declared.frames.is_empty()
+                    && !declared
+                        .frames
+                        .iter()
+                        .any(|x| x == frame_name(&self.draft.frame_type))
+                    && let Some(first) = declared.frames.first()
+                {
+                    self.draft.frame_type = frame_label(first).to_string();
                 }
             },
             WindowEditorMsg::ClearSource => self.draft.source = String::default(),
@@ -745,7 +716,7 @@ impl Component for WindowEditor {
     }
 
     fn view(&self, ctx: &Context<Self>) -> Html {
-        let op = op_from_label(&self.draft.op);
+        let declared = op_spec(&ctx.props().metadata, &self.draft.source, &self.draft.op);
 
         // The op selector renders the FEATURE-DECLARED window aggregates
         // for the source column's type, in the server's declared order -
@@ -763,7 +734,7 @@ impl Component for WindowEditor {
                 })
                 .unwrap_or_default()
                 .into_iter()
-                .map(|x| SelectItem::Option(op_label(x).to_string()))
+                .map(|x| SelectItem::Option(x.name.clone()))
                 .collect(),
         );
 
@@ -782,17 +753,16 @@ impl Component for WindowEditor {
         };
 
         // Frame type as a dropdown; like the op selector, invalid choices
-        // are omitted rather than disabled (`rate` requires a Range frame,
-        // and `SetOp` already coerces the draft there).
+        // are omitted rather than disabled - the declared `frames` are the
+        // menu, and `SetOp` already coerces the draft into them.
         let frame_types: Rc<Vec<SelectItem<String>>> = Rc::new(
-            if op == Some(WindowAggregate::Rate) {
-                vec!["Range"]
-            } else {
-                vec!["Rows", "Range", "Cumulative"]
-            }
-            .into_iter()
-            .map(|x| SelectItem::Option(x.to_string()))
-            .collect(),
+            declared
+                .as_ref()
+                .map(|x| x.frames.clone())
+                .unwrap_or_default()
+                .iter()
+                .map(|x| SelectItem::Option(frame_label(x).to_string()))
+                .collect(),
         );
 
         // Slots take true `Table` columns ONLY - expression aliases and
@@ -927,10 +897,12 @@ impl Component for WindowEditor {
             </DragDropList<WindowEditor, PivotColumn, WindowPartitionByContext>>
         };
 
-        let show_frame =
-            op.map(is_aggregating).unwrap_or_default() || op == Some(WindowAggregate::Rate);
-        let show_offset = op.map(is_positional).unwrap_or_default();
-        let show_alpha = op == Some(WindowAggregate::Ema);
+        let show_frame = declared
+            .as_ref()
+            .map(|x| !x.frames.is_empty())
+            .unwrap_or_default();
+        let show_offset = declared.as_ref().map(|x| x.offset).unwrap_or_default();
+        let show_alpha = declared.as_ref().map(|x| x.alpha).unwrap_or_default();
 
         html! {
             <>

package/src/rust/config/datetime_column_style/custom.rs

@@ -62,14 +62,22 @@ const fn numeric_default() -> u32 {
     0
 }
 
+/// A datetime column's `date_format` in its `Custom` form: per-part
+/// `Intl.DateTimeFormatOptions` overrides, discriminated from the `Simple`
+/// preset form by the required `format: "custom"` key. Each part is a
+/// [`CustomDatetimeFormat`] variant valid for that `Intl` option;
+/// `"disabled"` omits the part from the formatted output entirely.
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize, TS)]
 pub struct CustomDatetimeStyleConfig {
     format: FormatUnit,
 
+    /// An IANA time zone name (e.g. `"America/New_York"`); defaults to the
+    /// browser's local time zone.
     #[serde(default)]
     #[serde(rename = "timeZone", skip_serializing_if = "Option::is_none")]
     pub time_zone: Option<String>,
 
+    /// Sub-second digits to display, 0-3 (0 = none).
     #[serde(
         skip_serializing_if = "is_zero",
         rename = "fractionalSecondDigits",
@@ -77,27 +85,36 @@ pub struct CustomDatetimeStyleConfig {
     )]
     pub fractional_seconds: u32,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub second: CustomDatetimeFormat,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub minute: CustomDatetimeFormat,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub hour: CustomDatetimeFormat,
 
+    /// Defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub day: CustomDatetimeFormat,
 
+    /// A name form (`"long"`/`"short"`/`"narrow"`); defaults to
+    /// `"disabled"` (weekday not shown).
     #[serde(skip_serializing_if = "is_disabled", default = "weekday_default")]
     pub weekday: CustomDatetimeFormat,
 
+    /// Numeric or name form; defaults to `"numeric"`.
     #[serde(skip_serializing_if = "is_numeric", default = "second_default")]
     pub month: CustomDatetimeFormat,
 
+    /// Defaults to `"2-digit"`.
     #[serde(skip_serializing_if = "is_two_digit", default = "year_default")]
     pub year: CustomDatetimeFormat,
 
+    /// 12-hour clock; defaults to `true`.
     #[serde(skip_serializing_if = "is_true", default = "hour12_default")]
     pub hour12: bool,
 }

package/src/rust/config/datetime_column_style/simple.rs

@@ -23,12 +23,20 @@ const fn time_style_default() -> SimpleDatetimeFormat {
     SimpleDatetimeFormat::Medium
 }
 
+/// A datetime column's `date_format` in its `Simple` preset form:
+/// `Intl.DateTimeFormatOptions`' `dateStyle`/`timeStyle` presets. This is
+/// the default form (no `format` key); setting `format: "custom"` selects
+/// the per-part `CustomDatetimeStyleConfig` instead.
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize, TS)]
 pub struct SimpleDatetimeStyleConfig {
+    /// An IANA time zone name (e.g. `"America/New_York"`); defaults to the
+    /// browser's local time zone.
     #[serde(default)]
     #[serde(rename = "timeZone", skip_serializing_if = "Option::is_none")]
     pub time_zone: Option<String>,
 
+    /// Date preset breadth, or `"disabled"` to omit the date entirely;
+    /// defaults to `"short"`.
     #[serde(
         default = "date_style_default",
         rename = "dateStyle",
@@ -36,6 +44,8 @@ pub struct SimpleDatetimeStyleConfig {
     )]
     pub date_style: SimpleDatetimeFormat,
 
+    /// Time preset breadth, or `"disabled"` to omit the time entirely;
+    /// defaults to `"medium"`.
     #[serde(
         default = "time_style_default",
         rename = "timeStyle",

package/src/rust/config/number_string_format.rs

@@ -16,6 +16,11 @@ use serde::{Deserialize, Serialize};
 use strum::{Display, EnumIter};
 use ts_rs::TS;
 
+/// The `style` family of a numeric column's `number_format` — serialized
+/// FLATTENED into [`CustomNumberFormatConfig`]'s object, discriminated by
+/// the `style` key (`"decimal"` default, `"currency"` + `currency`/
+/// `currencyDisplay`/`currencySign`, `"percent"`, `"unit"` + `unit`/
+/// `unitDisplay`), mirroring `Intl.NumberFormat` options.
 #[derive(Serialize, Deserialize, Default, Debug, PartialEq, Clone, TS)]
 #[serde(rename_all = "camelCase", tag = "style")]
 pub enum NumberFormatStyle {
@@ -127,6 +132,11 @@ pub enum TrailingZeroDisplay {
     StripIfInteger,
 }
 
+/// The `notation` family of a numeric column's `number_format` —
+/// serialized FLATTENED into [`CustomNumberFormatConfig`]'s object,
+/// discriminated by the `notation` key (`"standard"` default,
+/// `"scientific"`, `"engineering"`, `"compact"` + `compactDisplay`),
+/// mirroring `Intl.NumberFormat` options.
 #[derive(Serialize, Deserialize, Default, Debug, PartialEq, Clone, TS)]
 #[serde(rename_all = "camelCase", tag = "notation")]
 pub enum Notation {
@@ -169,6 +179,14 @@ pub enum SignDisplay {
     Never,
 }
 
+/// A numeric column's `number_format` (`columns_config` value) —
+/// `Intl.NumberFormat`-shaped options, written by the Style tab's number
+/// format editor and read by `createNumberFormatter`. The `style` and
+/// `notation` families ([`NumberFormatStyle`] / [`Notation`]) are serde-
+/// FLATTENED into this object but `#[ts(skip)]`'d (ts-rs cannot flatten
+/// `Option<enum>`) — the package's `NumberFormatConfig` re-composes the
+/// full wire type as `CustomNumberFormatConfig & Partial<NumberFormatStyle>
+/// & Partial<Notation>` (see `column-format.ts`).
 #[derive(Serialize, Deserialize, Debug, Default, PartialEq, Clone, TS)]
 #[serde(rename_all = "camelCase")]
 pub struct CustomNumberFormatConfig {
@@ -181,33 +199,42 @@ pub struct CustomNumberFormatConfig {
     // these min/max props can all be specified but it results in possible conflicts
     // may consider making them distinct options
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub minimum_integer_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub minimum_fraction_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub maximum_fraction_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub minimum_significant_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub maximum_significant_digits: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub rounding_priority: Option<RoundingPriority>,
 
     // specific values https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingincrement
     // Only available with automatic rounding priority
     // Cannot be mixed with sigfig rounding. (Does this mean max/min sigfig must be unset?)
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub rounding_increment: Option<f64>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub rounding_mode: Option<RoundingMode>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub trailing_zero_display: Option<TrailingZeroDisplay>,
 
     #[serde(flatten)]
@@ -215,10 +242,16 @@ pub struct CustomNumberFormatConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub _notation: Option<Notation>,
 
+    /// NOTE (audit 2026-08-05): serialized values are the STRINGS
+    /// `"always"`/`"auto"`/`"min2"` or the untagged BOOLEAN `false` —
+    /// the former hand-written TS `useGrouping?: boolean` was wrong for
+    /// the string cases.
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub use_grouping: Option<UseGrouping>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[ts(optional, as = "Option<_>")]
     pub sign_display: Option<SignDisplay>,
 }
 

package/src/rust/config/options.rs

@@ -28,6 +28,24 @@ pub struct PanelOptions {
     pub panel: Option<String>,
 }
 
+/// Options for the `restore()` method.
+#[derive(Deserialize, Default, TS)]
+pub struct RestoreOptions {
+    /// The target panel; the active panel when omitted.
+    #[ts(optional)]
+    pub panel: Option<String>,
+
+    /// When `true`, a failed restore only REJECTS the returned `Promise` —
+    /// the error is not committed to the viewer's visible error state, and
+    /// the session remains usable for subsequent calls. For programmatic
+    /// callers (e.g. the LLM agent's `set_view_config` tool) for whom a
+    /// failed config patch is feedback rather than a user-facing fault.
+    /// The config may be partially applied on failure; restore a
+    /// known-good config to recover exactly.
+    #[ts(optional)]
+    pub suppress_errors: Option<bool>,
+}
+
 /// The `eject` argument: the loaded client to remove by name; the active
 /// panel's client when omitted.
 #[derive(Deserialize, Default, TS)]

package/src/rust/config/plugin_static_config.rs

@@ -10,7 +10,7 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-use perspective_client::config::GroupRollupMode;
+use perspective_client::config::{GroupRollupMode, SplitRollupMode};
 use serde::Deserialize;
 use ts_rs::TS;
 
@@ -103,6 +103,13 @@ pub struct PluginStaticConfig {
     #[ts(optional)]
     pub group_rollup_modes: Option<Vec<GroupRollupMode>>,
 
+    /// Split-rollup modes the plugin accepts, in preference order.
+    /// The first entry that matches a feature flag becomes the default.
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub split_rollup_modes: Option<Vec<SplitRollupMode>>,
+
     /// Plugin load priority. Higher numbers win; ties resolve in
     /// registration order. The highest-priority plugin is loaded by
     /// default unless `restore({ plugin })` overrides it.
@@ -120,15 +127,70 @@ pub struct PluginStaticConfig {
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub can_render_column_styles: bool,
+
+    /// What `group_by` MEANS visually for this plugin, e.g. `"X Axis"`
+    /// for the Y-series charts or `"Hierarchy"` for treemap/sunburst.
+    /// `None` where the field has no visual role of its own and is a
+    /// plain aggregation key (the X/Y charts, whose axes both come from
+    /// `columns`).
+    ///
+    /// This is the `group_by` counterpart of [`Self::config_column_names`]:
+    /// the same declaration that names the positional `columns` slots
+    /// should say what the other view fields draw, so that consumers —
+    /// the settings UI's field labels, and the agent's `list_plugins`
+    /// contract — read one source instead of restating the mapping.
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub group_by_role: Option<String>,
+
+    /// What `split_by` MEANS visually for this plugin, e.g. `"Series"`.
+    /// See [`Self::group_by_role`].
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub split_by_role: Option<String>,
+
+    /// `true` when this plugin CONNECTS its points in row order, so the
+    /// `View`'s row order is visible in the drawing: an unsorted config
+    /// renders the table's natural order, which reads as a tangle unless
+    /// the rows already arrive ordered along the axis. Declared rather
+    /// than inferred, because "unsorted" is not itself a mistake — a
+    /// pre-ordered table needs no `sort`, and the point plugins
+    /// (scatter, density) do not care at all.
+    #[serde(default)]
+    #[ts(as = "Option<_>")]
+    #[ts(optional)]
+    pub connects_row_order: bool,
 }
 
 impl PluginStaticConfig {
+    /// The number of leading `columns` slots that are POSITIONAL: a drop
+    /// there swaps with the column already present, and the slot's
+    /// meaning is fixed by [`Self::config_column_names`]. Everything from
+    /// this index on is the insert TAIL, which repeats the last named
+    /// role — which is why a `Y Line` (named slots: `["Y Axis"]`) takes
+    /// any number of columns as additional Y series, while an
+    /// `X/Y Line` (`["X Axis", "Y Axis", "Tooltip"]`) pins its two axes
+    /// and treats the rest as further tooltips.
+    ///
+    /// The single definition of that rule: [`Self::is_swap`] and the
+    /// agent's `list_plugins` contract both derive from it, so the
+    /// convention cannot be read two different ways.
+    pub fn positional_columns(&self) -> usize {
+        self.config_column_names.len().saturating_sub(1)
+    }
+
+    /// The role that `columns` past the positional slots repeat, i.e.
+    /// the last named slot. `None` when the plugin names no slots.
+    pub fn tail_column_role(&self) -> Option<&str> {
+        self.config_column_names.last().map(|x| x.as_str())
+    }
+
     /// `true` if dropping a column at `index` should swap with the
-    /// column already there rather than insert. Only the named slots
-    /// (`config_column_names[..len()-1]`) participate in swap behaviour;
-    /// the trailing unnamed tail inserts.
+    /// column already there rather than insert.
     pub fn is_swap(&self, index: usize) -> bool {
-        !self.config_column_names.is_empty() && index < self.config_column_names.len() - 1
+        !self.config_column_names.is_empty() && index < self.positional_columns()
     }
 
     pub fn get_group_rollups(&self, rollup_features: &[GroupRollupMode]) -> Vec<GroupRollupMode> {
@@ -141,4 +203,57 @@ impl PluginStaticConfig {
             })
             .unwrap_or_default()
     }
+
+    pub fn get_split_rollups(&self, rollup_features: &[SplitRollupMode]) -> Vec<SplitRollupMode> {
+        self.split_rollup_modes
+            .clone()
+            .map(|x| {
+                x.into_iter()
+                    .filter(|y| rollup_features.is_empty() || rollup_features.contains(y))
+                    .collect()
+            })
+            .unwrap_or_default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn plugin(names: &[&str]) -> PluginStaticConfig {
+        PluginStaticConfig {
+            config_column_names: names.iter().map(|x| (*x).to_owned()).collect(),
+            ..Default::default()
+        }
+    }
+
+    /// The tail rule has ONE definition: `is_swap` and the role a
+    /// trailing column repeats must never disagree about where the
+    /// positional slots end.
+    #[test]
+    fn positional_slots_and_tail_agree() {
+        // `Y Line` — the only named slot IS the tail, so every column
+        // is another Y series and none of them swap.
+        let y_line = plugin(&["Y Axis"]);
+        assert_eq!(y_line.positional_columns(), 0);
+        assert_eq!(y_line.tail_column_role(), Some("Y Axis"));
+        assert!(!y_line.is_swap(0));
+
+        // `X/Y Line` — two pinned axes, then tooltips.
+        let xy_line = plugin(&["X Axis", "Y Axis", "Tooltip"]);
+        assert_eq!(xy_line.positional_columns(), 2);
+        assert_eq!(xy_line.tail_column_role(), Some("Tooltip"));
+        assert!(xy_line.is_swap(0));
+        assert!(xy_line.is_swap(1));
+        assert!(!xy_line.is_swap(2));
+
+        for index in 0..4 {
+            assert_eq!(xy_line.is_swap(index), index < xy_line.positional_columns());
+        }
+
+        let unnamed = plugin(&[]);
+        assert_eq!(unnamed.positional_columns(), 0);
+        assert_eq!(unnamed.tail_column_role(), None);
+        assert!(!unnamed.is_swap(0));
+    }
 }