@perspective-dev/viewer 5.0.0 → 5.2.0

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));
+    }
 }

package/src/rust/config/viewer_config.rs

@@ -42,12 +42,42 @@ pub struct ViewerConfig<V: TS = String> {
 /// whole-element config format.
 #[derive(Debug, Default, Serialize, PartialEq, TS)]
 pub struct PanelViewerConfig<V: TS = String> {
+    /// The `@perspective-dev/viewer` version that wrote this config,
+    /// stamped on save and used to migrate older tokens. Callers do not
+    /// set it.
     pub version: V,
+
+    /// Per-column styling, keyed by column name. The viewer treats the
+    /// values as opaque — their shape is defined by the ACTIVE plugin,
+    /// so a config written for one plugin may carry keys another
+    /// ignores. Query the live shape with the `get_style_schema` agent
+    /// tool, or the plugin's `column_config_schema()`.
     pub columns_config: ColumnConfigMap,
+
+    /// Name of the visualization plugin, from the set registered on the
+    /// page (the `list_plugins` agent tool, or the plugin picker). This
+    /// also decides what the view fields MEAN visually: `columns` is
+    /// positional and each plugin reads the positions differently, and
+    /// `group_by`/`split_by` draw different things per plugin.
     pub plugin: String,
+
+    /// Plugin-wide settings (as opposed to the per-column
+    /// [`Self::columns_config`]). Opaque to the viewer and defined by
+    /// the active plugin; see `get_style_schema`.
     pub plugin_config: serde_json::Map<String, Value>,
-    pub table: Option<String>,
+
+    /// Name of the `Table` this panel renders, as hosted on the panel's
+    /// `Client`. Every placed panel has a table binding (creation
+    /// requires one by type — [`ViewerConfigInitial`]), so the saved
+    /// config carries it unconditionally.
+    pub table: String,
+
+    /// Selected theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid
+    /// names are the Perspective themes loaded on the page, which
+    /// `resetThemes()` re-scans. `None` selects the first available.
     pub theme: Option<String>,
+
+    /// Panel title, shown in its tab. `None` renders the default title.
     pub title: Option<String>,
 
     #[serde(flatten)]
@@ -93,41 +123,73 @@ impl Deref for PluginConfig {
 
 #[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize, TS)]
 pub struct ViewerConfigUpdate {
+    /// The `@perspective-dev/viewer` version a saved config was written
+    /// by, used to migrate older tokens. Omit it — the viewer stamps
+    /// the current version on save.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub version: VersionUpdate,
 
+    /// Name of the visualization plugin to switch to, from the set
+    /// registered on the page (the `list_plugins` agent tool, or the
+    /// plugin picker). Changing it changes what the view fields MEAN:
+    /// `columns` is positional and every plugin reads the positions
+    /// differently, and `group_by`/`split_by` draw different things per
+    /// plugin — so read the new plugin's roles before writing `columns`
+    /// for it.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub plugin: PluginUpdate,
 
+    /// Panel title, shown in its tab. `null` restores the default
+    /// title; omitting the field leaves the current one.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub title: TitleUpdate,
 
+    /// Name of the `Table` to render, as hosted on this panel's
+    /// `Client`. Rebinding an existing panel to another table keeps the
+    /// rest of the config, so column names that do not exist in the new
+    /// table will fail validation.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub table: TableUpdate,
 
+    /// Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
+    /// the Perspective themes loaded on the page, re-scanned by
+    /// `resetThemes()`. `null` selects the default.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub theme: ThemeUpdate,
 
+    /// Whether the settings sidebar is OPEN. Purely cosmetic chrome —
+    /// it does not affect what the viewer renders, and it is
+    /// element-level rather than per-panel.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub settings: SettingsUpdate,
 
+    /// Plugin-wide settings (as opposed to the per-column
+    /// [`Self::columns_config`]). The viewer passes these through
+    /// opaquely — their valid keys are defined by the ACTIVE plugin and
+    /// vary by plugin and by state, so query them with the
+    /// `get_style_schema` agent tool rather than guessing.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
     pub plugin_config: PluginConfigUpdate,
 
+    /// Per-column styling — formatting, colors, and other per-column
+    /// controls — keyed by column name. Opaque to the viewer and
+    /// plugin-defined like [`Self::plugin_config`]; `get_style_schema`
+    /// reports the valid keys for a given column under the active
+    /// plugin.
     #[serde(default)]
     #[ts(as = "Option<_>")]
     #[ts(optional)]
@@ -150,6 +212,119 @@ impl ViewerConfigUpdate {
     }
 }
 
+/// The initial configuration of a NEW panel (`addPanel`, `restore`'s
+/// panel-creating upsert, `restoreWorkspace` `panels` entries). Unlike
+/// [`ViewerConfigUpdate`] — a patch against existing state — creation has
+/// no prior state: `table` is REQUIRED (a placed panel without a table
+/// binding would be permanently blank), absent fields mean "default"
+/// rather than "leave unchanged" (so no [`OptionalUpdate`] tri-state), and
+/// there is no `settings` field (element-level, not per-panel).
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize, TS)]
+pub struct ViewerConfigInitial {
+    /// Name of the `Table` the new panel renders, as hosted on the
+    /// `Client`. REQUIRED: a placed panel with no table binding would be
+    /// permanently blank.
+    pub table: String,
+
+    /// The `@perspective-dev/viewer` version a saved config was written
+    /// by. Omit it when creating a panel.
+    #[ts(optional)]
+    pub version: Option<String>,
+
+    /// Name of the visualization plugin, from the set registered on the
+    /// page (the `list_plugins` agent tool, or the plugin picker).
+    /// Decides what the view fields MEAN: `columns` is positional and
+    /// every plugin reads the positions differently, and
+    /// `group_by`/`split_by` draw different things per plugin. Absent
+    /// uses the default plugin.
+    #[ts(optional)]
+    pub plugin: Option<String>,
+
+    /// Panel title, shown in its tab. Absent renders the default title.
+    #[ts(optional)]
+    pub title: Option<String>,
+
+    /// Theme NAME (e.g. `"Pro Dark"`) — not a CSS value. Valid names are
+    /// the Perspective themes loaded on the page. Absent uses the
+    /// default.
+    #[ts(optional)]
+    pub theme: Option<String>,
+
+    /// Plugin-wide settings (as opposed to the per-column
+    /// [`Self::columns_config`]). Opaque to the viewer and defined by
+    /// the ACTIVE plugin; query the valid keys with `get_style_schema`
+    /// rather than guessing.
+    #[ts(optional)]
+    pub plugin_config: Option<serde_json::Map<String, Value>>,
+
+    /// Per-column styling — formatting, colors, and other per-column
+    /// controls — keyed by column name. Plugin-defined like
+    /// [`Self::plugin_config`]; see `get_style_schema`.
+    #[ts(optional)]
+    pub columns_config: Option<ColumnConfigMap>,
+
+    #[serde(flatten)]
+    pub view_config: ViewConfigUpdate,
+}
+
+impl ViewerConfigInitial {
+    /// Decode a `JsValue` by auto-detecting format from JavaScript type.
+    pub fn decode(config: &JsValue) -> ApiResult<Self> {
+        Ok(config.into_serde_ext()?)
+    }
+
+    /// A default-config panel bound to `table` (the "New panel" menus).
+    /// Exhaustive on purpose — same drift alarm as the `From` impl below.
+    pub fn new(table: impl Into<String>) -> Self {
+        Self {
+            table: table.into(),
+            version: None,
+            plugin: None,
+            title: None,
+            theme: None,
+            plugin_config: None,
+            columns_config: None,
+            view_config: ViewConfigUpdate::default(),
+        }
+    }
+}
+
+fn up<T: Clone>(value: Option<T>) -> OptionalUpdate<T> {
+    match value {
+        Some(value) => OptionalUpdate::Update(value),
+        None => OptionalUpdate::Missing,
+    }
+}
+
+// Constructed EXHAUSTIVELY on purpose: a field added to
+// `ViewerConfigUpdate` breaks this impl at compile time, forcing the
+// "should creation carry it?" decision (the drift alarm).
+impl From<ViewerConfigInitial> for ViewerConfigUpdate {
+    fn from(value: ViewerConfigInitial) -> Self {
+        ViewerConfigUpdate {
+            version: up(value.version),
+            plugin: up(value.plugin),
+            title: up(value.title),
+            table: OptionalUpdate::Update(value.table),
+            theme: up(value.theme),
+            settings: OptionalUpdate::Missing,
+            plugin_config: up(value.plugin_config),
+            columns_config: up(value.columns_config),
+            view_config: value.view_config,
+        }
+    }
+}
+
+// There is deliberately NO `TryFrom<ViewerConfigUpdate>` here. Requiring a
+// `table` is a property of the CREATION ENTRY POINTS — `addPanel`'s
+// argument type, `WorkspaceConfigUpdate::panels`, and the agent's
+// `add_panel` decode — each of which already has a `ViewerConfigInitial`
+// in hand. An update→initial conversion exists only to let a route holding
+// a PATCH pretend it is creating from scratch, which is how `restore`'s
+// upsert acquired the gate and started rejecting the table-less
+// restore-then-`load` contract. Its absence is what keeps that from
+// recurring: `create_panel` takes an update, so no caller needs one.
+
 impl std::fmt::Display for ViewerConfigUpdate {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(
@@ -185,6 +360,50 @@ pub type VersionUpdate = OptionalUpdate<String>;
 pub type ColumnConfigUpdate = OptionalUpdate<ColumnConfigMap>;
 pub type PluginConfigUpdate = OptionalUpdate<serde_json::Map<String, Value>>;
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn initial_requires_a_table() {
+        let json = serde_json::json!({ "group_by": ["State"] });
+        let err = serde_json::from_value::<ViewerConfigInitial>(json).unwrap_err();
+        assert!(format!("{err}").contains("table"));
+    }
+
+    /// The creation → patch direction is the only one that exists (see the
+    /// note above the `From` impl); a `table` becomes a concrete update and
+    /// the element-level `settings` is not carried.
+    #[test]
+    fn initial_widens_to_an_update() {
+        let json = serde_json::json!({
+            "table": "superstore",
+            "plugin": "Datagrid",
+            "group_by": ["State"],
+        });
+
+        let initial: ViewerConfigInitial = serde_json::from_value(json).unwrap();
+        let update = ViewerConfigUpdate::from(initial);
+        assert!(matches!(&update.table, OptionalUpdate::Update(x) if x == "superstore"));
+        assert!(matches!(&update.settings, OptionalUpdate::Missing));
+        assert!(matches!(&update.plugin, OptionalUpdate::Update(x) if x == "Datagrid"));
+        assert_eq!(
+            update.view_config.group_by.as_deref(),
+            Some(&["State".to_owned()][..])
+        );
+    }
+
+    /// A table-less patch is a legitimate creation input now that
+    /// `create_panel` takes an update — the deferred panel a `load()`
+    /// binds. Nothing in this module may reject it.
+    #[test]
+    fn a_table_less_update_is_representable() {
+        let json = serde_json::json!({ "group_by": ["State"] });
+        let update: ViewerConfigUpdate = serde_json::from_value(json).unwrap();
+        assert!(matches!(&update.table, OptionalUpdate::Missing));
+    }
+}
+
 /// Handles `{}` when included as a field with `#[serde(default)]`.
 impl<T: Clone> Default for OptionalUpdate<T> {
     fn default() -> Self {