@perspective-dev/viewer 5.1.0 → 5.3.0

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")]
@@ -72,11 +84,15 @@ extern "C" {
     #[wasm_bindgen(typescript_type = "GetClientOptions")]
     pub type JsGetClientOptions;
 
-    /// `restoreWorkspace()` argument: a whole-element config update.
+    /// `restoreWorkspace()` argument: a workspace config update.
     #[wasm_bindgen(typescript_type = "WorkspaceConfigUpdate")]
     pub type JsWorkspaceConfigUpdate;
 
-    /// `saveWorkspace()` return: a whole-element config.
+    /// `saveWorkspace()` options dict (`{ full_palette?: boolean }`).
+    #[wasm_bindgen(typescript_type = "SaveWorkspaceOptions")]
+    pub type JsSaveWorkspaceOptions;
+
+    /// `saveWorkspace()` return: a workspace config.
     #[wasm_bindgen(typescript_type = "Promise<WorkspaceConfig>")]
     pub type JsWorkspaceConfigPromise;
 
@@ -189,7 +205,8 @@ impl PerspectiveViewerElement {
             .map(|el| el.unchecked_into())
     }
 
-    async fn workspace_config(this: Self) -> ApiResult<JsValue> {
+    async fn workspace_config(this: Self, full_palette: bool) -> ApiResult<JsValue> {
+        this.workspace.effects().settle().await;
         let mut panels: std::collections::BTreeMap<String, PanelViewerConfig> = Default::default();
         for id in &this.workspace.panel_ids() {
             let panel = this.workspace.panel(id).into_apierror()?;
@@ -204,6 +221,26 @@ impl PerspectiveViewerElement {
             panels.insert(id.as_str().to_owned(), config.panel);
         }
 
+        let mut palette = palette_set(&this.workspace, &this.presentation);
+        let mut referenced = std::collections::BTreeSet::new();
+        for (id, item) in styles_in_use(&this.workspace) {
+            let Some(name) = palette_name_for(&palette, item.kind, &item.literal) else {
+                continue;
+            };
+
+            if let Some(entry) = panels
+                .get_mut(id.as_str())
+                .and_then(|panel| panel.columns_config.get_mut(&item.column))
+            {
+                entry.insert(item.key, serde_json::Value::String(format_var_ref(&name)));
+                referenced.insert(name);
+            }
+        }
+
+        if !full_palette {
+            palette.retain(|name, _| referenced.contains(name));
+        }
+
         let active = this
             .presentation
             .is_settings_open()
@@ -228,6 +265,7 @@ impl PerspectiveViewerElement {
                 .iter()
                 .map(|id| id.as_str().to_owned())
                 .collect(),
+            palette,
         })?)
     }
 }
@@ -509,7 +547,7 @@ impl PerspectiveViewerElement {
                 renderer
                     .clone()
                     .render_task(|guard| async move {
-                        renderer.set_default_theme(presentation.get_default_theme_name().await);
+                        seed_panel_theme(&presentation, &renderer).await;
                         renderer.stamp_theme(None);
                         let jstable = JsFuture::from(promise)
                             .await
@@ -524,7 +562,7 @@ impl PerspectiveViewerElement {
                             };
 
                             if let Some(notify) = &notify {
-                                place_reserved(&workspace, notify);
+                                place_reserved(&workspace, notify, true);
                             }
 
                             let _plugin = renderer.ensure_plugin_selected()?;
@@ -582,7 +620,35 @@ impl PerspectiveViewerElement {
                             // commits already applied live (`commit_view_config`).
                             let owned_window = session.take_pending_load(generation).is_some();
                             let discard = if owned_window && notify.is_some() {
-                                workspace.take_reserved()
+                                match workspace.take_reserved() {
+                                    Some(panel) => Some((panel, None)),
+                                    // The one-shot claim read: a table-less
+                                    // `restore` claimed the reservation, and no
+                                    // table has bound nor is pending — evict the
+                                    // panel `CREATE_REQUIRES_TABLE` forbids.
+                                    None if workspace
+                                        .resolve_claim()
+                                        .is_some_and(|has_table| !has_table)
+                                        && session.get_table().is_none()
+                                        && session.pending_table().is_none() =>
+                                    {
+                                        let evicted = renderer
+                                            .slot_name()
+                                            .map(PanelId::from)
+                                            .and_then(|id| workspace.remove_panel(&id));
+
+                                        if evicted.is_some()
+                                            && let Some(notify) = &notify
+                                        {
+                                            notify.emit(());
+                                        }
+
+                                        evicted.map(|panel| {
+                                            (panel, Some(ApiError::new(CREATE_REQUIRES_TABLE)))
+                                        })
+                                    },
+                                    None => None,
+                                }
                             } else {
                                 None
                             };
@@ -601,13 +667,19 @@ impl PerspectiveViewerElement {
                 Err(e) => {
                     session.take_pending_load(generation);
                     if let Some(notify) = &notify {
-                        place_reserved(&workspace, notify);
+                        place_reserved(&workspace, notify, true);
                     }
 
                     session.set_error(false, e.clone()).await?;
                     Err(e)
                 },
-                Ok(Some(panel)) => eject_panel(panel).await,
+                Ok(Some((panel, error))) => {
+                    eject_panel(panel).await?;
+                    match error {
+                        Some(e) => Err(e),
+                        None => Ok(()),
+                    }
+                },
                 Ok(None) => Ok(()),
             }
         }))
@@ -919,15 +991,18 @@ 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,
-    /// the element-level `settings`/`theme` fields are ignored in that case.
+    /// and the config restored into it (an upsert). Creation REQUIRES a
+    /// `table` — the same rule [`Self::addPanel`] enforces in its argument
+    /// type — and a would-create call without one REJECTS before any state
+    /// (including `settings`) is applied: with no panel to target and no
+    /// `table`, the patch has no data arrival path. In particular, on an
+    /// element with zero panels every `restore` must carry a `table`.
     ///
     /// On an empty element with a pending [`Self::load`] whose payload is not
     /// yet classified, the active-target form (no `panel`) instead claims and
     /// restores into that load's reserved first panel — see [`Self::load`].
     ///
-    /// This restores a SINGLE panel; a whole-element config (with a `panels`
+    /// This restores a SINGLE panel; a workspace config (with a `panels`
     /// map) must be applied via [`Self::restoreWorkspace`] — its `panels` /
     /// `layout` keys are ignored here.
     ///
@@ -940,7 +1015,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,73 +1043,113 @@ 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);
+
+        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)?;
-            match this.workspace.panel_or_active(id.as_ref()) {
+            let mut update = ViewerConfigUpdate::decode(&update)?;
+            let settings = std::mem::replace(&mut update.settings, OptionalUpdate::Missing);
+            enum Target {
+                Existing { panel: Panel, active: bool },
+                Claimed(Panel),
+                Create(Box<ViewerConfigInitial>),
+            }
+
+            let notify = this.layout_changed_notify();
+            let target = match this.workspace.panel_or_active(id.as_ref()) {
                 // An existing (or the active) panel — update it in place.
                 Some(panel) => {
                     let active = this.workspace.active_id().as_ref() == Some(&panel.id);
+                    Target::Existing { panel, active }
+                },
+                None => {
+                    let has_table = matches!(&update.table, OptionalUpdate::Update(_));
+                    match id
+                        .is_none()
+                        .then(|| place_reserved(&this.workspace, &notify, has_table))
+                        .flatten()
+                    {
+                        Some(panel) => Target::Claimed(panel),
+                        None => Target::Create(Box::new(ViewerConfigInitial::try_from(
+                            std::mem::take(&mut update),
+                        )?)),
+                    }
+                },
+            };
+
+            if !matches!(settings, OptionalUpdate::Missing) {
+                // Through `ToggleSettingsInit` — the SAME full choreography
+                // the toolbar toggle drives (presize every visible plugin
+                // to its post-toggle box, then the exactness-finalizer
+                // resize) — NOT the bare `ToggleSettingsComplete` leaf,
+                // which only re-renders the pane. The pane is the outer
+                // `SplitPanel` (no `before-resize` event) and the host box
+                // is unchanged, so a leaf-only toggle left every canvas
+                // plugin CSS-stretched at its old backing size.
+                //
+                // No `set_settings_before_open` here: `is_settings_open` is
+                // Init's toggle-vs-no-op DISPATCH state, so pre-writing the
+                // target makes every call resolve as a no-op. Init owns the
+                // write, as it does for the toolbar and `toggleConfig`.
+                let (sender, receiver) = channel::<ApiResult<JsValue>>();
+                this.root.borrow().as_ref().into_apierror()?.send_message(
+                    PerspectiveViewerMsg::ToggleSettingsInit(Some(settings), false, Some(sender)),
+                );
+
+                receiver.await.map_err(|_| ApiError::new("Cancelled"))??;
+            }
+
+            match target {
+                Target::Existing { panel, active } => {
                     restore_panel(
                         &panel.session,
                         &panel.renderer,
                         &this.presentation,
                         &this.workspace,
-                        Some(&this.root),
                         RestoreMode::Existing { active },
                         update,
+                        errors,
                     )
                     .await
                 },
-                // No existing panel matched. The active-target form
-                // (`panel: None`) CLAIMS a pending `load()`'s reserved panel
-                // — placing it and restoring into it — so a `restore` fired
-                // right after an unawaited `load(promise)` configures the
-                // panel that load's payload will bind, per the call-site
-                // ordering contract in [`Self::load`]. Named upserts and
-                // reservation-less elements create a fresh panel instead,
-                // routing through the shared `create_panel`
-                // (`RestoreMode::Fresh`) pipeline so the new panel's id is
-                // the requested `panel`.
-                None => {
-                    let notify = this.layout_changed_notify();
-                    let claimed = id
-                        .is_none()
-                        .then(|| place_reserved(&this.workspace, &notify))
-                        .flatten();
-                    match claimed {
-                        Some(panel) => {
-                            restore_panel(
-                                &panel.session,
-                                &panel.renderer,
-                                &this.presentation,
-                                &this.workspace,
-                                Some(&this.root),
-                                RestoreMode::Existing { active: true },
-                                update,
-                            )
-                            .await
-                        },
-                        None => {
-                            create_panel(
-                                &this.elem,
-                                &this.presentation,
-                                &this.workspace,
-                                &notify,
-                                id,
-                                update,
-                                None,
-                            )
-                            .await?;
-                            Ok(())
-                        },
-                    }
+                Target::Claimed(panel) => {
+                    restore_panel(
+                        &panel.session,
+                        &panel.renderer,
+                        &this.presentation,
+                        &this.workspace,
+                        RestoreMode::Existing { active: true },
+                        update,
+                        errors,
+                    )
+                    .await
+                },
+                Target::Create(config) => {
+                    create_panel(
+                        &this.elem,
+                        &this.presentation,
+                        &this.workspace,
+                        &notify,
+                        id,
+                        *config,
+                        None,
+                    )
+                    .await?;
+                    Ok(())
                 },
             }
         });
@@ -1034,8 +1157,8 @@ impl PerspectiveViewerElement {
         js_sys::Promise::from(fut).unchecked_into()
     }
 
-    /// Restore the ENTIRE element from a whole-element
-    /// [`WorkspaceConfigUpdate`] (`{version, active?, layout, panels, ...}`) —
+    /// Restore the ENTIRE element from a [`WorkspaceConfigUpdate`]
+    /// (`{version, active?, layout, panels, ...}`) —
     /// the multi-panel counterpart of [`Self::restore`]. Every existing panel
     /// is replaced by the `panels` entries, and the layout tree + master/detail
     /// cross-filter state re-applied. Unlike [`Self::restore`], this never
@@ -1063,9 +1186,9 @@ impl PerspectiveViewerElement {
                         &renderer,
                         &presentation,
                         &workspace,
-                        None,
                         RestoreMode::Fresh,
                         config,
+                        crate::tasks::RestoreErrors::Publish,
                     )
                     .await?;
                     if workspace.is_master(&id) {
@@ -1144,6 +1267,7 @@ impl PerspectiveViewerElement {
         let PanelOptions { panel: name } = parse_options(options);
         let this = self.clone();
         let fut = ApiFuture::new(async move {
+            this.workspace.effects().settle().await;
             let panel = this.resolve_panel(name)?;
             let viewer_config = panel
                 .renderer
@@ -1159,11 +1283,12 @@ impl PerspectiveViewerElement {
         js_sys::Promise::from(fut).unchecked_into()
     }
 
-    /// Save the ENTIRE element to a whole-element [`WorkspaceConfig`]
-    /// (`{version, active?, layout, panels, ...}`) — the multi-panel
-    /// counterpart of [`Self::save`]. Unlike [`Self::save`] (which emits a
-    /// single `ViewerConfig` for one panel), this ALWAYS emits the
-    /// whole-element format, restorable via [`Self::restoreWorkspace`].
+    /// Save the ENTIRE element to a [`WorkspaceConfig`]
+    /// (`{version, active?, layout, panels, palette?, ...}`) — the
+    /// multi-panel counterpart of [`Self::save`]. Unlike [`Self::save`]
+    /// (which emits a single `ViewerConfig` for one panel), this ALWAYS
+    /// emits the workspace format, restorable via
+    /// [`Self::restoreWorkspace`].
     ///
     /// # JavaScript Examples
     ///
@@ -1171,9 +1296,13 @@ impl PerspectiveViewerElement {
     /// const token = await viewer.saveWorkspace();
     /// await viewer.restoreWorkspace(token);
     /// ```
-    pub fn saveWorkspace(&self) -> JsWorkspaceConfigPromise {
+    pub fn saveWorkspace(
+        &self,
+        options: Option<JsSaveWorkspaceOptions>,
+    ) -> JsWorkspaceConfigPromise {
+        let SaveWorkspaceOptions { full_palette } = parse_options(options);
         let this = self.clone();
-        let fut = ApiFuture::new(Self::workspace_config(this));
+        let fut = ApiFuture::new(Self::workspace_config(this, full_palette.unwrap_or(false)));
         js_sys::Promise::from(fut).unchecked_into()
     }
 
@@ -1303,9 +1432,10 @@ impl PerspectiveViewerElement {
     /// Reset a panel's `ViewerConfig` to its data-relative default.
     ///
     /// Without a `panel`, this is ELEMENT-LEVEL: EVERY panel is reset and the
-    /// cross-filter overlay cleared (symmetric with whole-element
-    /// [`Self::save`] / [`Self::restore`]). With `{panel}`, only that panel is
-    /// reset — the other panels and the overlay are left untouched.
+    /// cross-filter overlay cleared (symmetric with
+    /// [`Self::saveWorkspace`] / [`Self::restoreWorkspace`]). With `{panel}`,
+    /// only that panel is reset — the other panels and the overlay are left
+    /// untouched.
     ///
     /// # Arguments
     ///
@@ -1556,17 +1686,15 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn restyleElement(&self) -> ApiFuture<JsValue> {
-        clone!(self.workspace, self.presentation);
+        clone!(self.workspace);
         let effect = workspace.effects().guard();
         ApiFuture::new(async move {
             let _effect = effect;
-            let default = presentation.get_default_theme_name().await;
             for panel in workspace
                 .panel_ids()
                 .into_iter()
                 .filter_map(|id| workspace.panel(&id))
             {
-                panel.renderer.set_default_theme(default.clone());
                 panel.renderer.restyle_all().await?;
             }
 
@@ -1574,6 +1702,21 @@ impl PerspectiveViewerElement {
         })
     }
 
+    #[wasm_bindgen]
+    pub fn getThemes(&self) -> ApiFuture<JsValue> {
+        clone!(self.presentation);
+        ApiFuture::new(async move {
+            let x = presentation
+                .get_available_themes()
+                .await?
+                .iter()
+                .cloned()
+                .collect::<Vec<_>>();
+
+            Ok(JsValue::from(x))
+        })
+    }
+
     /// Set the available theme names available in the status bar UI.
     ///
     /// Calling [`Self::resetThemes`] may cause the current theme to switch,
@@ -1594,46 +1737,41 @@ impl PerspectiveViewerElement {
         let effect = workspace.effects().guard();
         ApiFuture::new(async move {
             let _effect = effect;
-            let themes: Option<Vec<String>> = themes
-                .unwrap_or_default()
-                .iter()
-                .map(|x| x.as_string())
-                .collect();
+            // `None` (re-parse the document) must survive the conversion —
+            // mapping BEFORE defaulting is what keeps that branch reachable
+            // from JavaScript at all.
+            let themes: Option<Vec<String>> = match themes {
+                None => None,
+                Some(themes) => themes.iter().map(|x| x.as_string()).collect(),
+            };
 
-            let theme_name = presentation.get_selected_theme_name().await;
-            presentation.reset_available_themes(themes).await;
+            let previous = presentation.active_theme_name_sync();
+            let active = presentation.reset_themes(themes).await?;
             let available = presentation.get_available_themes().await?;
-            let reset_theme = available
-                .iter()
-                .find(|y| theme_name.as_ref() == Some(y))
-                .cloned();
-
-            presentation.set_theme_name(reset_theme.as_deref()).await?;
-            let new_default = presentation.get_default_theme_name().await;
             for panel in workspace
                 .panel_ids()
                 .into_iter()
                 .filter_map(|id| workspace.panel(&id))
             {
-                // Availability applies to PANELS too: a panel pinned to a
-                // theme outside the new set follows the host — clear the pin
-                // so it renders (and `save`s) the new registry default, the
-                // same keep-if-available-else-default rule applied to the
-                // host selection above.
-                if panel
-                    .renderer
-                    .theme()
-                    .is_some_and(|t| !available.contains(&t))
-                {
-                    panel.renderer.set_theme(None);
-                }
-
-                panel.renderer.set_default_theme(new_default.clone());
-                if panel.renderer.needs_restyle() {
-                    panel.renderer.restyle_all().await?;
+                let theme = panel.renderer.theme();
+
+                // A panel follows the host only when it was TRACKING it (it
+                // holds the host's previous theme, which is how every panel
+                // born without an explicit one starts — and what keeps the
+                // active panel and the host in agreement), or when its own
+                // theme has left the registry. A panel explicitly set to a
+                // different, still-available theme is untouched: re-ordering
+                // alone must repaint nothing.
+                let stale = theme.as_ref().is_none_or(|x| !available.contains(x));
+                if (stale || theme == previous) && theme != active {
+                    panel.renderer.set_theme(active.clone());
+                    if panel.renderer.needs_restyle() {
+                        panel.renderer.restyle_all().await?;
+                    }
                 }
             }
 
+            presentation.publish_theme_config().await?;
             Ok(JsValue::UNDEFINED)
         })
     }
@@ -1688,7 +1826,7 @@ impl PerspectiveViewerElement {
             let force = force.map(SettingsUpdate::Update);
             let (sender, receiver) = channel::<ApiResult<wasm_bindgen::JsValue>>();
             root.borrow().as_ref().into_apierror()?.send_message(
-                PerspectiveViewerMsg::ToggleSettingsInit(force, Some(sender)),
+                PerspectiveViewerMsg::ToggleSettingsInit(force, true, Some(sender)),
             );
 
             receiver.await.map_err(|_| JsValue::from("Cancelled"))?
@@ -1726,27 +1864,30 @@ 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)?;
+            let config = ViewerConfigInitial::decode(&config)?;
             let id = create_panel(
                 &elem,
                 &presentation,
                 &workspace,
                 &notify,
                 None,
-                update,
+                config,
                 None,
             )
             .await?;
@@ -1844,7 +1985,12 @@ impl PerspectiveViewerElement {
             let _effect = effect;
             let panel = this.resolve_panel(name)?;
             let was_active = this.workspace.active_id().as_ref() == Some(&panel.id);
-            let locator = get_column_locator(&panel.session.metadata(), Some(column_name));
+            let target = {
+                let config = panel.session.get_view_config();
+                let metadata = panel.session.metadata();
+                classify_column(&column_name, &config, &metadata)
+                    .map(|_| crate::presentation::ColumnSettingsTarget::Column(column_name))
+            };
             if !was_active {
                 this.root.borrow().as_ref().into_apierror()?.send_message(
                     PerspectiveViewerMsg::SetActivePanel(panel.id.as_str().to_owned(), None),
@@ -1854,7 +2000,7 @@ impl PerspectiveViewerElement {
             let (sender, receiver) = channel::<()>();
             this.root.borrow().as_ref().into_apierror()?.send_message(
                 PerspectiveViewerMsg::OpenColumnSettings {
-                    locator,
+                    target,
                     sender: Some(sender),
                     toggle: was_active,
                 },
@@ -1864,3 +2010,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)
+    }
+}