@perspective-dev/viewer 5.1.0 → 5.2.0

package/dist/esm/providers.d.ts

@@ -0,0 +1,79 @@
+/**
+ * LLM provider presets for `viewer.agentConfig()`. These are plain data —
+ * the agent core is provider-agnostic (one OpenAI-chat-completions protocol
+ * over primitive `url`/`headers`/`apiKey` connection fields), so a
+ * "provider" is just a spreadable collection of those fields:
+ *
+ * ```javascript
+ * import { providers } from "@perspective-dev/viewer";
+ * viewer.agentConfig({
+ *     ...providers.anthropic,
+ *     apiKey: "sk-ant-...",
+ *     model: "claude-haiku-4-5",       // spread order = override order
+ * });
+ * ```
+ *
+ * Any OpenAI-compatible service works without a preset — pass its full
+ * chat-completions `url` (and `apiKey`/`headers` as needed) directly.
+ * Cloud presets call the provider from the browser tab; suitable for local
+ * development, or route `url` through your own proxy for production.
+ */
+/**
+ * A spreadable connection preset for `viewer.agentConfig()`.
+ */
+export interface AgentProviderPreset {
+    name: string;
+    url: string;
+    headers?: Record<string, string>;
+    model?: string;
+}
+export declare const providers: {
+    /**
+     * Anthropic's OpenAI-compatibility endpoint. `apiKey` required.
+     */
+    readonly anthropic: {
+        readonly name: "anthropic";
+        readonly url: "https://api.anthropic.com/v1/chat/completions";
+        readonly headers: {
+            readonly "anthropic-dangerous-direct-browser-access": "true";
+        };
+        readonly model: "claude-opus-5";
+    };
+    /**
+     * Google Gemini's OpenAI-compatibility endpoint. `apiKey` required.
+     */
+    readonly gemini: {
+        readonly name: "gemini";
+        readonly url: "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions";
+        readonly model: "gemini-2.5-flash";
+    };
+    /**
+     * LM Studio's local developer server (enable CORS in its settings).
+     */
+    readonly lmstudio: {
+        readonly name: "lmstudio";
+        readonly url: "http://localhost:1234/v1/chat/completions";
+    };
+    /**
+     *  Local Ollama (set `OLLAMA_ORIGINS` for CORS).
+     */
+    readonly ollama: {
+        readonly name: "ollama";
+        readonly url: "http://localhost:11434/v1/chat/completions";
+    };
+    /**
+     * OpenRouter. `apiKey` required.
+     */
+    readonly openrouter: {
+        readonly name: "openrouter";
+        readonly url: "https://openrouter.ai/api/v1/chat/completions";
+    };
+    /**
+     * OpenAI. `apiKey` required.
+     */
+    readonly openai: {
+        readonly name: "openai";
+        readonly url: "https://api.openai.com/v1/chat/completions";
+        readonly model: "gpt-5.2";
+    };
+};

package/dist/esm/ts-rs/CompactDisplay.d.ts

@@ -0,0 +1,5 @@
+export type CompactDisplay = {
+    "compactDisplay": "short";
+} | {
+    "compactDisplay": "long";
+};

package/dist/esm/ts-rs/CurrencyCode.d.ts

@@ -0,0 +1 @@
+export type CurrencyCode = "AED" | "AFN" | "ALL" | "AMD" | "ANG" | "AOA" | "ARS" | "AUD" | "AWG" | "AZN" | "BAM" | "BBD" | "BDT" | "BGN" | "BHD" | "BIF" | "BMD" | "BND" | "BOB" | "BOV" | "BRL" | "BSD" | "BTN" | "BWP" | "BYR" | "BZD" | "CAD" | "CDF" | "CHE" | "CHF" | "CHW" | "CLF" | "CLP" | "CNY" | "COP" | "COU" | "CRC" | "CUC" | "CUP" | "CVE" | "CZK" | "DJF" | "DKK" | "DOP" | "DZD" | "EGP" | "ERN" | "ETB" | "EUR" | "FJD" | "FKP" | "GBP" | "GEL" | "GHS" | "GIP" | "GMD" | "GNF" | "GTQ" | "GYD" | "HKD" | "HNL" | "HRK" | "HTG" | "HUF" | "IDR" | "ILS" | "INR" | "IQD" | "IRR" | "ISK" | "JMD" | "JOD" | "JPY" | "KES" | "KGS" | "KHR" | "KMF" | "KPW" | "KRW" | "KWD" | "KYD" | "KZT" | "LAK" | "LBP" | "LKR" | "LRD" | "LSL" | "LTL" | "LVL" | "LYD" | "MAD" | "MDL" | "MGA" | "MKD" | "MMK" | "MNT" | "MOP" | "MRO" | "MUR" | "MVR" | "MWK" | "MXN" | "MXV" | "MYR" | "MZN" | "NAD" | "NGN" | "NIO" | "NOK" | "NPR" | "NZD" | "OMR" | "PAB" | "PEN" | "PGK" | "PHP" | "PKR" | "PLN" | "PYG" | "QAR" | "RON" | "RSD" | "RUB" | "RWF" | "SAR" | "SBD" | "SCR" | "SDG" | "SEK" | "SGD" | "SHP" | "SLL" | "SOS" | "SRD" | "SSP" | "STD" | "SYP" | "SZL" | "THB" | "TJS" | "TMT" | "TND" | "TOP" | "TRY" | "TTD" | "TWD" | "TZS" | "UAH" | "UGX" | "USD" | "USN" | "USS" | "UYI" | "UYU" | "UZS" | "VEF" | "VND" | "VUV" | "WST" | "XAF" | "XAG" | "XAU" | "XBA" | "XBB" | "XBC" | "XBD" | "XCD" | "XDR" | "XFU" | "XOF" | "XPD" | "XPF" | "XPT" | "XTS" | "XXX" | "YER" | "ZAR" | "ZMW";

package/dist/esm/ts-rs/CurrencyDisplay.d.ts

@@ -0,0 +1 @@
+export type CurrencyDisplay = "code" | "symbol" | "narrowSymbol" | "name";

package/dist/esm/ts-rs/CurrencyNumberFormatStyle.d.ts

@@ -0,0 +1,8 @@
+import type { CurrencyCode } from "./CurrencyCode.js";
+import type { CurrencyDisplay } from "./CurrencyDisplay.js";
+import type { CurrencySign } from "./CurrencySign.js";
+export type CurrencyNumberFormatStyle = {
+    currency: CurrencyCode;
+    currencyDisplay: CurrencyDisplay | null;
+    currencySign: CurrencySign | null;
+};

package/dist/esm/ts-rs/CurrencySign.d.ts

@@ -0,0 +1 @@
+export type CurrencySign = "standard" | "accounting";

package/dist/esm/ts-rs/CustomDatetimeFormat.d.ts

@@ -0,0 +1 @@
+export type CustomDatetimeFormat = "long" | "short" | "narrow" | "numeric" | "2-digit" | "disabled";

package/dist/esm/ts-rs/CustomDatetimeStyleConfig.d.ts

@@ -0,0 +1,54 @@
+import type { CustomDatetimeFormat } from "./CustomDatetimeFormat.js";
+import type { FormatUnit } from "./FormatUnit.js";
+/**
+ * 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.
+ */
+export type CustomDatetimeStyleConfig = {
+    format: FormatUnit;
+    /**
+     * An IANA time zone name (e.g. `"America/New_York"`); defaults to the
+     * browser's local time zone.
+     */
+    timeZone?: string | null;
+    /**
+     * Sub-second digits to display, 0-3 (0 = none).
+     */
+    fractionalSecondDigits?: number;
+    /**
+     * Defaults to `"numeric"`.
+     */
+    second?: CustomDatetimeFormat;
+    /**
+     * Defaults to `"numeric"`.
+     */
+    minute?: CustomDatetimeFormat;
+    /**
+     * Defaults to `"numeric"`.
+     */
+    hour?: CustomDatetimeFormat;
+    /**
+     * Defaults to `"numeric"`.
+     */
+    day?: CustomDatetimeFormat;
+    /**
+     * A name form (`"long"`/`"short"`/`"narrow"`); defaults to
+     * `"disabled"` (weekday not shown).
+     */
+    weekday?: CustomDatetimeFormat;
+    /**
+     * Numeric or name form; defaults to `"numeric"`.
+     */
+    month?: CustomDatetimeFormat;
+    /**
+     * Defaults to `"2-digit"`.
+     */
+    year?: CustomDatetimeFormat;
+    /**
+     * 12-hour clock; defaults to `true`.
+     */
+    hour12?: boolean;
+};

package/dist/esm/ts-rs/CustomNumberFormatConfig.d.ts

@@ -0,0 +1,34 @@
+import type { RoundingMode } from "./RoundingMode.js";
+import type { RoundingPriority } from "./RoundingPriority.js";
+import type { SignDisplay } from "./SignDisplay.js";
+import type { TrailingZeroDisplay } from "./TrailingZeroDisplay.js";
+import type { UseGrouping } from "./UseGrouping.js";
+/**
+ * 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`).
+ */
+export type CustomNumberFormatConfig = {
+    minimumIntegerDigits?: number | null;
+    minimumFractionDigits?: number | null;
+    maximumFractionDigits?: number | null;
+    minimumSignificantDigits?: number | null;
+    maximumSignificantDigits?: number | null;
+    roundingPriority?: RoundingPriority | null;
+    roundingIncrement?: number | null;
+    roundingMode?: RoundingMode | null;
+    trailingZeroDisplay?: TrailingZeroDisplay | null;
+    /**
+     * 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.
+     */
+    useGrouping?: UseGrouping | null;
+    signDisplay?: SignDisplay | null;
+};

package/dist/esm/ts-rs/DatetimeColorMode.d.ts

@@ -0,0 +1 @@
+export type DatetimeColorMode = "none" | "foreground" | "background";

package/dist/esm/ts-rs/DatetimeFormatType.d.ts

@@ -0,0 +1,6 @@
+import type { CustomDatetimeStyleConfig } from "./CustomDatetimeStyleConfig.js";
+import type { SimpleDatetimeStyleConfig } from "./SimpleDatetimeStyleConfig.js";
+/**
+ * `Simple` case has all default-able keys and must be last!
+ */
+export type DatetimeFormatType = CustomDatetimeStyleConfig | SimpleDatetimeStyleConfig;

package/dist/esm/ts-rs/FormatMode.d.ts

@@ -0,0 +1 @@
+export type FormatMode = "none" | "link" | "bold" | "italics";

package/dist/esm/ts-rs/FormatUnit.d.ts

@@ -0,0 +1 @@
+export type FormatUnit = "custom";

package/dist/esm/ts-rs/Notation.d.ts

@@ -0,0 +1,17 @@
+import type { CompactDisplay } from "./CompactDisplay.js";
+/**
+ * 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.
+ */
+export type Notation = {
+    "notation": "standard";
+} | {
+    "notation": "scientific";
+} | {
+    "notation": "engineering";
+} | {
+    "notation": "compact";
+} & CompactDisplay;

package/dist/esm/ts-rs/NumberFormatStyle.d.ts

@@ -0,0 +1,18 @@
+import type { CurrencyNumberFormatStyle } from "./CurrencyNumberFormatStyle.js";
+import type { UnitNumberFormatStyle } from "./UnitNumberFormatStyle.js";
+/**
+ * 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.
+ */
+export type NumberFormatStyle = {
+    "style": "decimal";
+} | {
+    "style": "currency";
+} & CurrencyNumberFormatStyle | {
+    "style": "percent";
+} | {
+    "style": "unit";
+} & UnitNumberFormatStyle;

package/dist/esm/ts-rs/PanelViewerConfig.d.ts

@@ -4,6 +4,7 @@ import type { Filter } from "./Filter.js";
 import type { FilterReducer } from "./FilterReducer.js";
 import type { GroupRollupMode } from "./GroupRollupMode.js";
 import type { Sort } from "./Sort.js";
+import type { SplitRollupMode } from "./SplitRollupMode.js";
 import type { Windows } from "./Windows.js";
 import type { JsonValue } from "./serde_json/JsonValue.js";
 /**
@@ -12,24 +13,63 @@ import type { JsonValue } from "./serde_json/JsonValue.js";
  * whole-element config format.
  */
 export type PanelViewerConfig<V = string> = {
+    /**
+     * The `@perspective-dev/viewer` version that wrote this config,
+     * stamped on save and used to migrate older tokens. Callers do not
+     * set it.
+     */
     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()`.
+     */
     columns_config: {
         [key in string]?: {
             [key in string]?: JsonValue;
         };
     };
+    /**
+     * 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.
+     */
     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`.
+     */
     plugin_config: {
         [key in string]?: JsonValue;
     };
-    table: string | null;
+    /**
+     * 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.
+     */
+    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.
+     */
     theme: string | null;
+    /**
+     * Panel title, shown in its tab. `None` renders the default title.
+     */
     title: string | null;
     group_by: Array<string>;
     split_by: Array<string>;
     sort: Array<Sort>;
     filter: Array<Filter>;
     group_rollup_mode: GroupRollupMode;
+    split_rollup_mode: SplitRollupMode;
     filter_op?: FilterReducer;
     expressions: Expressions;
     windows?: Windows;

package/dist/esm/ts-rs/PluginStaticConfig.d.ts

@@ -1,5 +1,6 @@
 import type { ColumnSelectMode } from "./ColumnSelectMode.js";
 import type { GroupRollupMode } from "./GroupRollupMode.js";
+import type { SplitRollupMode } from "./SplitRollupMode.js";
 /**
  * Static, immutable configuration for a plugin.
  *
@@ -60,6 +61,11 @@ export type PluginStaticConfig = {
      * The first entry that matches a feature flag becomes the default.
      */
     group_rollup_modes?: Array<GroupRollupMode> | null;
+    /**
+     * Split-rollup modes the plugin accepts, in preference order.
+     * The first entry that matches a feature flag becomes the default.
+     */
+    split_rollup_modes?: Array<SplitRollupMode> | null;
     /**
      * Plugin load priority. Higher numbers win; ties resolve in
      * registration order. The highest-priority plugin is loaded by
@@ -74,4 +80,33 @@ export type PluginStaticConfig = {
      * is shown.
      */
     can_render_column_styles?: boolean;
+    /**
+     * 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.
+     */
+    group_by_role?: string | null;
+    /**
+     * What `split_by` MEANS visually for this plugin, e.g. `"Series"`.
+     * See [`Self::group_by_role`].
+     */
+    split_by_role?: string | null;
+    /**
+     * `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.
+     */
+    connects_row_order?: boolean;
 };

package/dist/esm/ts-rs/RestoreOptions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Options for the `restore()` method.
+ */
+export type RestoreOptions = {
+    /**
+     * The target panel; the active panel when omitted.
+     */
+    panel?: 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.
+     */
+    suppress_errors?: boolean;
+};

package/dist/esm/ts-rs/RoundingMode.d.ts

@@ -0,0 +1 @@
+export type RoundingMode = "ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven";

package/dist/esm/ts-rs/RoundingPriority.d.ts

@@ -0,0 +1 @@
+export type RoundingPriority = "auto" | "morePrecision" | "lessPrecision";

package/dist/esm/ts-rs/SignDisplay.d.ts

@@ -0,0 +1 @@
+export type SignDisplay = "auto" | "always" | "exceptZero" | "negative" | "never";

package/dist/esm/ts-rs/SimpleDatetimeFormat.d.ts

@@ -0,0 +1 @@
+export type SimpleDatetimeFormat = "full" | "long" | "medium" | "short" | "disabled";

package/dist/esm/ts-rs/SimpleDatetimeStyleConfig.d.ts

@@ -0,0 +1,24 @@
+import type { SimpleDatetimeFormat } from "./SimpleDatetimeFormat.js";
+/**
+ * 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.
+ */
+export type SimpleDatetimeStyleConfig = {
+    /**
+     * An IANA time zone name (e.g. `"America/New_York"`); defaults to the
+     * browser's local time zone.
+     */
+    timeZone?: string | null;
+    /**
+     * Date preset breadth, or `"disabled"` to omit the date entirely;
+     * defaults to `"short"`.
+     */
+    dateStyle?: SimpleDatetimeFormat;
+    /**
+     * Time preset breadth, or `"disabled"` to omit the time entirely;
+     * defaults to `"medium"`.
+     */
+    timeStyle?: SimpleDatetimeFormat;
+};

package/dist/esm/ts-rs/SplitRollupMode.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `split_by` corollary to [`GroupRollupMode`]. `Flat` (the default,
+ * matching this crate's historical behavior) emits only full-depth split
+ * combinations as columns; `Rollup` additionally emits grand-total and
+ * subtotal column groups in "totals before" order. There is no `Total`
+ * variant - an empty `split_by` already expresses a single grand-total
+ * column group.
+ */
+export type SplitRollupMode = "flat" | "rollup";

package/dist/esm/ts-rs/StringColorMode.d.ts

@@ -0,0 +1 @@
+export type StringColorMode = "none" | "foreground" | "background" | "series";

package/dist/esm/ts-rs/TrailingZeroDisplay.d.ts

@@ -0,0 +1 @@
+export type TrailingZeroDisplay = "auto" | "stripIfInteger";

package/dist/esm/ts-rs/Unit.d.ts

@@ -0,0 +1 @@
+export type Unit = "acre" | "bit" | "byte" | "celsius" | "centimeter" | "day" | "degree" | "fahrenheit" | "fluid-ounce" | "foot" | "gallob" | "gigabit" | "gigabyte" | "gram" | "hectare" | "hour" | "inch" | "kilobit" | "kilobyte" | "kilogram" | "kilometer" | "liter" | "megabit" | "megabyte" | "meter" | "microsecond" | "mile" | "mile-scandinavian" | "milliliter" | "millimeter" | "millisecond" | "minute" | "month" | "nanosecond" | "ounce" | "percent" | "petabyte" | "pound" | "second" | "stone" | "terabit" | "terabyte" | "week" | "yard" | "year";

package/dist/esm/ts-rs/UnitDisplay.d.ts

@@ -0,0 +1 @@
+export type UnitDisplay = "short" | "narrow" | "long";

package/dist/esm/ts-rs/UnitNumberFormatStyle.d.ts

@@ -0,0 +1,6 @@
+import type { Unit } from "./Unit.js";
+import type { UnitDisplay } from "./UnitDisplay.js";
+export type UnitNumberFormatStyle = {
+    unit: Unit;
+    unitDisplay: UnitDisplay | null;
+};

package/dist/esm/ts-rs/UseGrouping.d.ts

@@ -0,0 +1 @@
+export type UseGrouping = "always" | "auto" | "min2" | boolean;

package/dist/esm/ts-rs/ViewerConfig.d.ts

@@ -4,6 +4,7 @@ import type { Filter } from "./Filter.js";
 import type { FilterReducer } from "./FilterReducer.js";
 import type { GroupRollupMode } from "./GroupRollupMode.js";
 import type { Sort } from "./Sort.js";
+import type { SplitRollupMode } from "./SplitRollupMode.js";
 import type { Windows } from "./Windows.js";
 import type { JsonValue } from "./serde_json/JsonValue.js";
 /**
@@ -16,24 +17,63 @@ import type { JsonValue } from "./serde_json/JsonValue.js";
  */
 export type ViewerConfig<V = string> = {
     settings: boolean;
+    /**
+     * The `@perspective-dev/viewer` version that wrote this config,
+     * stamped on save and used to migrate older tokens. Callers do not
+     * set it.
+     */
     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()`.
+     */
     columns_config: {
         [key in string]?: {
             [key in string]?: JsonValue;
         };
     };
+    /**
+     * 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.
+     */
     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`.
+     */
     plugin_config: {
         [key in string]?: JsonValue;
     };
-    table: string | null;
+    /**
+     * 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.
+     */
+    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.
+     */
     theme: string | null;
+    /**
+     * Panel title, shown in its tab. `None` renders the default title.
+     */
     title: string | null;
     group_by: Array<string>;
     split_by: Array<string>;
     sort: Array<Sort>;
     filter: Array<Filter>;
     group_rollup_mode: GroupRollupMode;
+    split_rollup_mode: SplitRollupMode;
     filter_op?: FilterReducer;
     expressions: Expressions;
     windows?: Windows;