@perspective-dev/viewer 5.1.0 → 5.2.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 {

package/src/rust/config/workspace_config.rs

@@ -14,7 +14,7 @@ use std::collections::BTreeMap;
 
 use perspective_client::config::Filter;
 
-use crate::config::{PanelViewerConfig, ViewerConfigUpdate};
+use crate::config::{PanelViewerConfig, ViewerConfigInitial};
 
 /// The whole-element config format (`{version, active?, layout, panels}`) —
 /// the multi-panel counterpart of the single-panel [`ViewerConfig`] — as
@@ -59,10 +59,11 @@ pub struct WorkspaceConfig {
 }
 
 /// The parse target of a whole-element config in
-/// [`PerspectiveViewerElement::restore`]. Mirrors [`WorkspaceConfig`],
-/// but `panels` entries are full [`ViewerConfigUpdate`]s so a stray per-panel
-/// `settings` can be detected (warned, then ignored — `create_panel` strips
-/// it).
+/// [`PerspectiveViewerElement::restoreWorkspace`]. Mirrors
+/// [`WorkspaceConfig`], but `panels` entries are [`ViewerConfigInitial`]s —
+/// every entry creates a NEW panel, so `table` is required by type (a
+/// stray per-panel `settings` key is ignored; it is element-level state,
+/// carried by the top-level `active` field).
 #[derive(serde::Deserialize, ts_rs::TS)]
 pub struct WorkspaceConfigUpdate {
     #[serde(default)]
@@ -73,7 +74,7 @@ pub struct WorkspaceConfigUpdate {
     #[ts(optional)]
     pub layout: Option<crate::js::Layout>,
 
-    pub panels: BTreeMap<String, ViewerConfigUpdate>,
+    pub panels: BTreeMap<String, ViewerConfigInitial>,
 
     /// The element-level global (master/detail cross-) filters to re-apply as
     /// a transient overlay on every DETAIL panel. Restored as one

package/src/rust/custom_elements/viewer.rs

@@ -29,6 +29,8 @@ use wasm_bindgen_futures::JsFuture;
 use web_sys::HtmlElement;
 use yew::Callback;
 
+#[cfg(feature = "llm-agent")]
+use crate::agent::AgentRuntime;
 use crate::components::viewer::{PerspectiveViewerMsg, PerspectiveViewerProps};
 use crate::config::*;
 use crate::custom_events::*;
@@ -59,6 +61,16 @@ extern "C" {
     #[wasm_bindgen(typescript_type = "PanelOptions")]
     pub type JsPanelOptions;
 
+    /// `restore()` options dict
+    /// (`{ panel?: string, suppress_errors?: boolean }`).
+    #[wasm_bindgen(typescript_type = "RestoreOptions")]
+    pub type JsRestoreOptions;
+
+    /// `addPanel()` argument: a new panel's initial config — `table`
+    /// REQUIRED.
+    #[wasm_bindgen(typescript_type = "ViewerConfigInitial")]
+    pub type JsViewerConfigInitial;
+
     /// `download`/`export`/`copy` options dict
     /// (`{ method?: ExportMethod, panel?: string }`).
     #[wasm_bindgen(typescript_type = "ExportOptions")]
@@ -919,9 +931,12 @@ impl PerspectiveViewerElement {
     /// optional `{panel}` selector.
     ///
     /// If `panel` names no existing panel, a NEW panel is created with that id
-    /// and the config restored into it (an upsert), equivalent to
-    /// [`Self::addPanel`] but with a caller-chosen id. As with a created panel,
+    /// and the config restored into it (an upsert). As with a created panel,
     /// the element-level `settings`/`theme` fields are ignored in that case.
+    /// Unlike [`Self::addPanel`], the argument is a PATCH, so a `table` is
+    /// optional: creating without one yields a DEFERRED panel that the next
+    /// [`Self::load`] binds. Such a panel renders but cannot be serialized —
+    /// [`Self::save`] rejects with "Panel has no `table`" until it is bound.
     ///
     /// On an empty element with a pending [`Self::load`] whose payload is not
     /// yet classified, the active-target form (no `panel`) instead claims and
@@ -940,7 +955,15 @@ impl PerspectiveViewerElement {
     ///
     /// - `update` - The config to restore to, as returned by [`Self::save`] in
     ///   either "json", "string" or "arraybuffer" format.
-    /// - `name` - The panel to target, or `None` for the active panel.
+    /// - `options.panel` - The panel to target, or the active panel when
+    ///   omitted.
+    /// - `options.suppress_errors` - 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. The view config is
+    ///   rolled back to its pre-call value, so a rejected patch cannot re-merge
+    ///   into a later restore. Element-level state the call already applied
+    ///   (theme, title, a plugin swap) is NOT undone — restore a known-good
+    ///   config to recover those exactly.
     ///
     /// # JavaScript Examples
     ///
@@ -960,15 +983,62 @@ impl PerspectiveViewerElement {
     pub fn restore(
         &self,
         update: JsViewerConfigUpdate,
-        options: Option<JsPanelOptions>,
+        options: Option<JsRestoreOptions>,
     ) -> JsVoidPromise {
-        let PanelOptions { panel: name } = parse_options(options);
+        let RestoreOptions {
+            panel: name,
+            suppress_errors,
+        } = parse_options(options);
+
+        // `suppress_errors` failures reject the returned Promise WITHOUT
+        // committing to the viewer's visible error state — for programmatic
+        // callers (the agent's `set_view_config`) whose failed patches are
+        // caller feedback, not user-facing faults.
+        let errors = if suppress_errors.unwrap_or_default() {
+            RestoreErrors::Suppress
+        } else {
+            RestoreErrors::Publish
+        };
+
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         let fut = ApiFuture::new_throttled(async move {
             let _effect = effect;
             let id = name.map(PanelId::from);
-            let update = ViewerConfigUpdate::decode(&update)?;
+            let mut update = ViewerConfigUpdate::decode(&update)?;
+
+            // `settings` is ELEMENT-level chrome, not panel state — it
+            // rides in this object only because the legacy single-panel
+            // `restore()` has always carried it. Apply it HERE and hand
+            // the panel pipeline a purely per-panel update: the
+            // panel-CREATING branch below converts to
+            // `ViewerConfigInitial`, which has no `settings` field at
+            // all, so a `restore()` against an empty element — the first
+            // call every embedding makes — would otherwise drop it
+            // silently. Applied BEFORE the panel work so the plugin
+            // draws once, already at its final size.
+            // BOTH halves move together, or the flag and the chrome
+            // disagree: `set_settings_before_open` writes the persisted
+            // `is_settings_open` (what `save()` reports) and the host
+            // `settings` attribute, while `ToggleSettingsComplete`
+            // performs the component's own toggle. `restore_and_render`
+            // used to do the first for the panel-UPDATING path only —
+            // which the creating path never reaches, since
+            // `ViewerConfigInitial` has no `settings` field to carry.
+            let settings = std::mem::replace(&mut update.settings, OptionalUpdate::Missing);
+            if !matches!(settings, OptionalUpdate::Missing) {
+                if let OptionalUpdate::Update(open) = settings {
+                    this.presentation.set_settings_before_open(open);
+                }
+
+                let (sender, receiver) = channel::<()>();
+                this.root.borrow().as_ref().into_apierror()?.send_message(
+                    PerspectiveViewerMsg::ToggleSettingsComplete(settings, sender),
+                );
+
+                receiver.await.unwrap_or_log();
+            }
+
             match this.workspace.panel_or_active(id.as_ref()) {
                 // An existing (or the active) panel — update it in place.
                 Some(panel) => {
@@ -978,9 +1048,9 @@ impl PerspectiveViewerElement {
                         &panel.renderer,
                         &this.presentation,
                         &this.workspace,
-                        Some(&this.root),
                         RestoreMode::Existing { active },
                         update,
+                        errors,
                     )
                     .await
                 },
@@ -1007,13 +1077,25 @@ impl PerspectiveViewerElement {
                                 &panel.renderer,
                                 &this.presentation,
                                 &this.workspace,
-                                Some(&this.root),
                                 RestoreMode::Existing { active: true },
                                 update,
+                                errors,
                             )
                             .await
                         },
                         None => {
+                            // The panel-creating upsert. `restore`'s
+                            // argument is a PATCH, so a `table` is
+                            // optional here as it is everywhere else on
+                            // this path: an update carrying none creates
+                            // a deferred panel, which the next `load()`
+                            // binds (it targets `active_panel()` before
+                            // reserving one of its own). The
+                            // table-required rule belongs to the
+                            // CREATION types — `addPanel`,
+                            // `restoreWorkspace`'s `panels`, the agent's
+                            // `add_panel` — which enforce it in their
+                            // own signatures.
                             create_panel(
                                 &this.elem,
                                 &this.presentation,
@@ -1063,9 +1145,9 @@ impl PerspectiveViewerElement {
                         &renderer,
                         &presentation,
                         &workspace,
-                        None,
                         RestoreMode::Fresh,
                         config,
+                        crate::tasks::RestoreErrors::Publish,
                     )
                     .await?;
                     if workspace.is_master(&id) {
@@ -1726,27 +1808,32 @@ impl PerspectiveViewerElement {
     }
 
     /// Add a new, independent panel to this viewer's layout, rendering the
-    /// supplied [`ViewerConfigUpdate`] into it. The panel uses the default
-    /// [`perspective_client::Client`] (the first passed to [`Self::load`]) to
-    /// resolve its `table`. Returns the generated panel id.
-    ///
-    /// Element-level config fields (`settings`, `theme`) in the argument are
-    /// ignored — those are shared across the element, not per-panel.
+    /// supplied [`ViewerConfigInitial`] into it. Unlike [`Self::restore`]'s
+    /// update-shaped argument, a new panel has no prior state, so `table`
+    /// is REQUIRED — a table-less call rejects before the layout is
+    /// touched. The panel uses the default [`perspective_client::Client`]
+    /// (the first passed to [`Self::load`]) to resolve its `table`. Returns
+    /// the generated panel id.
+    ///
+    /// The element-level `settings` field does not exist on the argument
+    /// type (it is shared across the element, not per-panel).
     #[wasm_bindgen]
-    pub fn addPanel(&self, update: JsViewerConfigUpdate) -> ApiFuture<JsValue> {
+    pub fn addPanel(&self, config: JsViewerConfigInitial) -> ApiFuture<JsValue> {
         clone!(self.elem, self.presentation, self.workspace);
         let effect = workspace.effects().guard();
         let notify = self.layout_changed_notify();
         ApiFuture::new(async move {
             let _effect = effect;
-            let update = ViewerConfigUpdate::decode(&update)?;
+            // The table-required guarantee is HERE, in the argument type
+            // and this decode — `create_panel` itself takes a patch.
+            let config = ViewerConfigInitial::decode(&config)?;
             let id = create_panel(
                 &elem,
                 &presentation,
                 &workspace,
                 &notify,
                 None,
-                update,
+                config.into(),
                 None,
             )
             .await?;
@@ -1864,3 +1951,107 @@ impl PerspectiveViewerElement {
         })
     }
 }
+
+#[cfg(feature = "llm-agent")]
+#[wasm_bindgen]
+impl PerspectiveViewerElement {
+    /// Configure the embedded LLM agent (see `prompt()`), replacing any prior
+    /// configuration and conversation.
+    ///
+    /// The agent core is provider-agnostic: one OpenAI-chat-completions
+    /// protocol over primitive connection fields. Exactly one of
+    /// `config.url` or `config.engine` is required; the `providers` presets
+    /// exported by this package are plain spreadable collections of these
+    /// fields (`{...providers.anthropic, apiKey}`).
+    ///
+    /// - `config.url` - a full chat-completions endpoint URL (any
+    ///   OpenAI-compatible service: Anthropic/Gemini compatibility endpoints,
+    ///   LM Studio, Ollama, OpenRouter, a proxy...).
+    /// - `config.engine` - an in-page engine object with an OpenAI-compatible
+    ///   `chat.completions.create(request)` method (e.g. WebLLM's `MLCEngine`);
+    ///   mutually exclusive with `url`.
+    /// - `config.headers` - extra request headers, sent verbatim.
+    /// - `config.apiKey` - sugar for the `Authorization: Bearer` header.
+    /// - `config.model` - model id sent with each request; local servers and
+    ///   engines generally answer with whatever model is loaded.
+    /// - `config.name` - cosmetic label for the chat badge (presets set this).
+    /// - `config.systemPrompt` - extra system-prompt context appended to the
+    ///   agent's built-in instructions.
+    /// - `config.maxTurns` - max model turns (tool-call rounds + the final
+    ///   answer) per `prompt()` call. Defaults to 16.
+    /// - `config.docs` - the agent metadata bundle, which supplies the
+    ///   `search_docs` corpus and the rich tool parameter schemas: the packaged
+    ///   `dist/docs/perspective-docs.json` asset as a parsed object (`import
+    ///   docs from "…json" with { type: "json" }`), a `fetch()` `Response`, an
+    ///   `ArrayBuffer`, a JSON string, or a `Promise` of any of those — and/or
+    ///   an inline array of `{title?, text}` entries for host data definitions.
+    ///   Omitted, `search_docs` searches an empty corpus and the parameter
+    ///   schemas degrade to permissive objects.
+    /// - `config.systemRole` - where the preamble (plus `systemPrompt`) is
+    ///   placed: `"system"` (default) or `"user"`. Some engines refuse a system
+    ///   message alongside `tools` because they substitute their own — WebLLM's
+    ///   Hermes function calling throws `CustomSystemPromptError` on ANY system
+    ///   message — and those need `"user"`, which folds the same text into the
+    ///   opening user turn.
+    /// - `config.entitlements` - access grants limiting which tools the agent
+    ///   is offered (and may call): any of `"read_view"`, `"configure_view"`,
+    ///   `"manage_layout"`, `"read_docs"`, `"read_data"`. Omitted, all but
+    ///   `"read_data"` are granted; `["read_view", "read_docs"]` yields a
+    ///   read-only agent.
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// import { providers } from "@perspective-dev/viewer";
+    ///
+    /// viewer.agentConfig({
+    ///     ...providers.anthropic,
+    ///     apiKey: "sk-ant-...",
+    ///     docs: fetch(
+    ///         "node_modules/@perspective-dev/viewer/dist/docs/perspective-docs.json",
+    ///     ),
+    /// });
+    /// ```
+    #[wasm_bindgen(js_name = "agentConfig")]
+    pub fn agent_config(&self, config: JsValue) -> ApiResult<()> {
+        let runtime = AgentRuntime::new(&config, self.clone())?;
+        self.presentation.agent.configure(runtime);
+        Ok(())
+    }
+
+    /// Run one conversational turn of the embedded LLM agent (configured via
+    /// `agentConfig()`), resolving with the agent's final text response after
+    /// any tool calls have been applied to this element. Turns share a
+    /// conversation history (and the chat sidebar's transcript) until
+    /// `agentReset()`; a call made while a turn is already running rejects.
+    /// Tool activity is emitted as `perspective-agent-tool` CustomEvents on
+    /// this element.
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// await viewer.agentPrompt("Show me sales by region as a bar chart");
+    /// ```
+    #[wasm_bindgen(js_name = "agentPrompt")]
+    pub fn agent_prompt(&self, prompt: String) -> js_sys::Promise {
+        let presentation = self.presentation.clone();
+        let fut = ApiFuture::new(async move {
+            Ok(JsValue::from(presentation.agent.run_prompt(prompt).await?))
+        });
+
+        js_sys::Promise::from(fut)
+    }
+
+    /// Clear the agent's conversation (history and chat transcript), keeping
+    /// its configuration. Cancels any in-flight turn.
+    #[wasm_bindgen(js_name = "agentReset")]
+    pub fn agent_reset(&self) -> js_sys::Promise {
+        let presentation = self.presentation.clone();
+        let fut = ApiFuture::new(async move {
+            presentation.agent.reset().await;
+            Ok(JsValue::UNDEFINED)
+        });
+
+        js_sys::Promise::from(fut)
+    }
+}