@perspective-dev/viewer 5.4.0 → 5.5.1

package/src/rust/custom_elements/viewer.rs

@@ -38,7 +38,7 @@ use crate::js::*;
 use crate::presentation::*;
 use crate::queries::*;
 use crate::root::Root;
-use crate::session::{ResetOptions, TableLoadState};
+use crate::session::{Disposal, MissingTable, ResetOptions, TableLoadState};
 use crate::tasks::*;
 use crate::utils::*;
 use crate::workspace::{Panel, PanelId, Workspace};
@@ -61,11 +61,18 @@ extern "C" {
     #[wasm_bindgen(typescript_type = "PanelOptions")]
     pub type JsPanelOptions;
 
-    /// `restore()` options dict
-    /// (`{ panel?: string, suppress_errors?: boolean }`).
+    /// The `restore()` options dict.
     #[wasm_bindgen(typescript_type = "RestoreOptions")]
     pub type JsRestoreOptions;
 
+    /// The `restoreWorkspace()` options dict.
+    #[wasm_bindgen(typescript_type = "RestoreWorkspaceOptions")]
+    pub type JsRestoreWorkspaceOptions;
+
+    /// The `addPanel()` options dict.
+    #[wasm_bindgen(typescript_type = "AddPanelOptions")]
+    pub type JsAddPanelOptions;
+
     /// `addPanel()` argument: a new panel's initial config — `table`
     /// REQUIRED.
     #[wasm_bindgen(typescript_type = "ViewerConfigInitial")]
@@ -84,9 +91,9 @@ extern "C" {
     #[wasm_bindgen(typescript_type = "GetClientOptions")]
     pub type JsGetClientOptions;
 
-    /// `restoreWorkspace()` argument: a workspace config update.
-    #[wasm_bindgen(typescript_type = "WorkspaceConfigUpdate")]
-    pub type JsWorkspaceConfigUpdate;
+    /// `getView` options dict (`{ mode?: GetViewMode, panel?: string }`).
+    #[wasm_bindgen(typescript_type = "GetViewOptions")]
+    pub type JsGetViewOptions;
 
     /// `saveWorkspace()` options dict (`{ full_palette?: boolean }`).
     #[wasm_bindgen(typescript_type = "SaveWorkspaceOptions")]
@@ -121,14 +128,15 @@ struct ResizeDimensions {
 /// falling back to `Default` on absence or a malformed argument (matching the
 /// `ResizeOptions` precedent — an options bag is a best-effort convenience,
 /// not a hard-validated payload).
-fn parse_options<T, U>(options: Option<T>) -> U
+fn parse_options<T, U>(options: Option<T>) -> ApiResult<U>
 where
     T: Into<JsValue>,
     U: Default + for<'a> serde::Deserialize<'a>,
 {
-    options
-        .and_then(|o| o.into_serde_ext().ok())
-        .unwrap_or_default()
+    match options {
+        None => Ok(U::default()),
+        Some(x) => Ok(x.into_serde_ext()?),
+    }
 }
 
 /// The `<perspective-viewer>` custom element.
@@ -196,6 +204,28 @@ impl PerspectiveViewerElement {
         })
     }
 
+    /// Re-stamp the global-filter overlay on every panel not in `fresh` and
+    /// re-render those whose overlay changed.
+    async fn rerender_retained_overlays(&self, fresh: &[PanelId]) -> ApiResult<()> {
+        let retained = self
+            .workspace
+            .panels()
+            .into_iter()
+            .filter(|panel| !fresh.contains(&panel.id))
+            .filter(|panel| stamp_global_overlay(&self.workspace, &panel.id, &panel.session))
+            .collect::<Vec<_>>();
+
+        join_all(retained.iter().map(|panel| async move {
+            apply_and_render(&panel.session, &panel.renderer, ViewConfigUpdate::default())?.await?;
+            Ok(())
+        }))
+        .await
+        .into_iter()
+        .collect::<ApiResult<Vec<_>>>()?;
+
+        Ok(())
+    }
+
     fn layout_element(&self) -> Option<RegularLayout> {
         self.elem
             .shadow_root()?
@@ -518,14 +548,19 @@ impl PerspectiveViewerElement {
 
         let session = panel.session;
         let renderer = panel.renderer;
-        let generation = session.begin_pending_load();
+        let load = session.begin_pending_load();
         clone!(self.workspace, self.presentation);
         Ok(ApiFuture::new_throttled(async move {
             let _effect = effect;
+            enum Discard {
+                Unclaimed(Panel),
+                Evicted(Panel),
+            }
+
             renderer.set_throttle(None);
             let _run_token = session.begin_config_run();
             let result = {
-                clone!(session, renderer, workspace, notify);
+                clone!(session, renderer, workspace, notify, load);
                 renderer
                     .clone()
                     .render_task(|guard| async move {
@@ -539,7 +574,7 @@ impl PerspectiveViewerElement {
                             try_from_js_option::<perspective_js::Table>(jstable.clone())
                         {
                             tracing::warn!("{}", DEPRECATED_TABLE_MESSAGE);
-                            let Some(journal) = session.take_pending_load(generation) else {
+                            let Some(journal) = load.claim() else {
                                 return Ok(None);
                             };
 
@@ -600,10 +635,10 @@ impl PerspectiveViewerElement {
                             // window is discarded (not replayed): a `Client`
                             // performs no reset, and any racing `restore`'s
                             // commits already applied live (`commit_view_config`).
-                            let owned_window = session.take_pending_load(generation).is_some();
+                            let owned_window = load.claim().is_some();
                             let discard = if owned_window && notify.is_some() {
                                 match workspace.take_reserved() {
-                                    Some(panel) => Some((panel, None)),
+                                    Some(panel) => Some(Discard::Unclaimed(panel)),
                                     // The one-shot claim read: a table-less
                                     // `restore` claimed the reservation, and no
                                     // table has bound nor is pending — evict the
@@ -625,9 +660,7 @@ impl PerspectiveViewerElement {
                                             notify.emit(());
                                         }
 
-                                        evicted.map(|panel| {
-                                            (panel, Some(ApiError::new(CREATE_REQUIRES_TABLE)))
-                                        })
+                                        evicted.map(Discard::Evicted)
                                     },
                                     None => None,
                                 }
@@ -638,7 +671,7 @@ impl PerspectiveViewerElement {
                             workspace.set_default_client(client.get_client().clone());
                             Ok(discard)
                         } else {
-                            session.take_pending_load(generation);
+                            load.close();
                             Err(ApiError::new("Invalid argument"))
                         }
                     })
@@ -647,7 +680,7 @@ impl PerspectiveViewerElement {
 
             match result {
                 Err(e) => {
-                    session.take_pending_load(generation);
+                    load.close();
                     if let Some(notify) = &notify {
                         place_reserved(&workspace, notify, true);
                     }
@@ -655,12 +688,13 @@ impl PerspectiveViewerElement {
                     session.set_error(false, e.clone()).await?;
                     Err(e)
                 },
-                Ok(Some((panel, error))) => {
-                    eject_panel(panel).await?;
-                    match error {
-                        Some(e) => Err(e),
-                        None => Ok(()),
-                    }
+                Ok(Some(Discard::Unclaimed(panel))) => {
+                    eject_panel(panel, Disposal::Reject).await?;
+                    Ok(())
+                },
+                Ok(Some(Discard::Evicted(panel))) => {
+                    eject_panel(panel, Disposal::Resolve).await?;
+                    Err(ApiError::new(CREATE_REQUIRES_TABLE))
                 },
                 Ok(None) => Ok(()),
             }
@@ -716,7 +750,11 @@ impl PerspectiveViewerElement {
     /// await viewer.eject({client: "remote"});
     /// ```
     pub fn eject(&mut self, options: Option<JsClientOptions>) -> ApiFuture<()> {
-        let ClientOptions { client } = parse_options(options);
+        let ClientOptions { client } = match parse_options(options) {
+            Ok(x) => x,
+            Err(x) => return ApiFuture::new_err(x),
+        };
+
         // Default target: the active panel's client, or — when the active panel
         // is unbound (`load(Client)` is now inert) — the default client.
         let Some(target) = client
@@ -752,32 +790,59 @@ impl PerspectiveViewerElement {
         eject_client_panels(&self.workspace, &self.root, target, ids)
     }
 
-    /// Get the underlying [`View`] for this viewer.
+    /// Get a [`View`] for a panel of this viewer, as currently configured by
+    /// the user.
     ///
-    /// Use this method to get promgrammatic access to the [`View`] as currently
-    /// configured by the user, for e.g. serializing as an
-    /// [Apache Arrow](https://arrow.apache.org/) before passing to another
-    /// library.
+    /// # Arguments
     ///
-    /// The [`View`] returned by this method is owned by the
-    /// [`PerspectiveViewerElement`] and may be _invalidated_ by
-    /// [`View::delete`] at any time. Plugins which rely on this [`View`] for
-    /// their [`HTMLPerspectiveViewerPluginElement::draw`] implementations
-    /// should treat this condition as a _cancellation_ by silently aborting on
-    /// "View already deleted" errors from method calls.
+    /// - `mode` - which [`View`] to return:
+    ///   - `"live"` (default) - the panel's own [`View`], which the viewer
+    ///     replaces on every config change and deletes when auto-paused or
+    ///     [`PerspectiveViewerElement::delete`]d, so calls on it may fail with
+    ///     "View already deleted", it must never be deleted by the caller, and
+    ///     it rejects with `No View for panel "<name>"` while none is bound
+    ///     (auto-paused or not yet rendered).
+    ///   - `"clone"` - a new [`View`] built from the panel's effective config
+    ///     (global filter included), independent of the render lifecycle, which
+    ///     the caller owns and must [`View::delete`].
+    ///   - `"auto"` - `"live"` when the panel has a bound [`View`], else
+    ///     `"clone"`.
+    /// - `panel` - the target panel, or the active panel when omitted.
+    ///
+    /// Plugins which rely on the live [`View`] for their
+    /// [`HTMLPerspectiveViewerPluginElement::draw`] implementations should
+    /// treat "View already deleted" as a _cancellation_ by silently aborting.
     ///
     /// # JavaScript Examples
     ///
     /// ```javascript
     /// const view = await viewer.getView();
     /// ```
+    ///
+    /// Export every panel without borrowing the viewer's own [`View`]:
+    ///
+    /// ```javascript
+    /// for (const panel of viewer.getPanelNames()) {
+    ///     const view = await viewer.getView({ panel, mode: "clone" });
+    ///     const arrow = await view.to_arrow();
+    ///     await view.delete();
+    /// }
+    /// ```
     #[wasm_bindgen]
-    pub fn getView(&self, options: Option<JsPanelOptions>) -> ApiFuture<View> {
-        let PanelOptions { panel: name } = parse_options(options);
+    pub fn getView(&self, options: Option<JsGetViewOptions>) -> ApiFuture<View> {
         let this = self.clone();
         ApiFuture::new(async move {
+            let GetViewOptions { mode, panel: name } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
-            Ok(panel.session.get_view().ok_or("No table set")?.into())
+            match (mode.unwrap_or_default(), panel.session.get_view()) {
+                (GetViewMode::Live | GetViewMode::Auto, Some(view)) => Ok(view.into()),
+                (GetViewMode::Live, None) => {
+                    Err(format!("No View for panel \"{}\"", panel.id.as_str()).into())
+                },
+                (GetViewMode::Clone, _) | (GetViewMode::Auto, None) => {
+                    Ok(panel.session.create_detached_view().await?.into())
+                },
+            }
         })
     }
 
@@ -788,9 +853,9 @@ impl PerspectiveViewerElement {
     /// [`View::get_config`])
     #[wasm_bindgen]
     pub fn getViewConfig(&self, options: Option<JsPanelOptions>) -> ApiFuture<JsViewConfig> {
-        let PanelOptions { panel: name } = parse_options(options);
         let this = self.clone();
         ApiFuture::new(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
             let config = if let Some(ctx) = panel.renderer.render_context() {
                 (*ctx.view_config).clone()
@@ -821,12 +886,12 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn getTable(&self, options: Option<JsGetTableOptions>) -> ApiFuture<Table> {
-        let GetTableOptions {
-            wait: wait_for_table,
-            panel: name,
-        } = parse_options(options);
         let this = self.clone();
         ApiFuture::new(async move {
+            let GetTableOptions {
+                wait: wait_for_table,
+                panel: name,
+            } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
             if !wait_for_table.unwrap_or_default()
                 && let Some(ctx) = panel.renderer.render_context()
@@ -866,12 +931,12 @@ impl PerspectiveViewerElement {
         &self,
         options: Option<JsGetClientOptions>,
     ) -> ApiFuture<perspective_js::Client> {
-        let GetClientOptions {
-            wait: wait_for_client,
-            panel: name,
-        } = parse_options(options);
         let this = self.clone();
         ApiFuture::new(async move {
+            let GetClientOptions {
+                wait: wait_for_client,
+                panel: name,
+            } = parse_options(options)?;
             let panel = this.resolve_panel(name)?;
             if !wait_for_client.unwrap_or_default()
                 && let Some(ctx) = panel.renderer.render_context()
@@ -902,7 +967,7 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn getRenderStats(&self, options: Option<JsPanelOptions>) -> ApiResult<JsValue> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let panel = self.resolve_panel(name)?;
         Ok(JsValue::from_serde_ext(
             &panel.renderer.render_timer().get_stats(),
@@ -1000,12 +1065,13 @@ impl PerspectiveViewerElement {
     /// - `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.
+    ///   the returned `Promise` and rolls the view config back, leaving the
+    ///   viewer's visible error state and any element-level state the call
+    ///   already applied (theme, title, plugin, a successful `table` change)
+    ///   untouched.
+    /// - `options.wait_for_table` - when `true`, a `table` no loaded client
+    ///   hosts yet leaves the panel empty and pending until the table is
+    ///   created, instead of the default error.
     ///
     /// # JavaScript Examples
     ///
@@ -1027,20 +1093,23 @@ impl PerspectiveViewerElement {
         update: JsViewerConfigUpdate,
         options: Option<JsRestoreOptions>,
     ) -> JsVoidPromise {
-        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 RestoreOptions {
+                panel: name,
+                suppress_errors,
+                wait_for_table,
+            } = parse_options(options)?;
+
+            let errors = if suppress_errors.unwrap_or_default() {
+                RestoreErrors::Suppress
+            } else {
+                RestoreErrors::Publish
+            };
+
+            let missing = MissingTable::from_wait(wait_for_table);
+
             let _effect = effect;
             let id = name.map(PanelId::from);
             let mut update = ViewerConfigUpdate::decode(&update)?;
@@ -1074,19 +1143,6 @@ impl PerspectiveViewerElement {
             };
 
             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)),
@@ -1105,6 +1161,7 @@ impl PerspectiveViewerElement {
                         RestoreMode::Existing { active },
                         update,
                         errors,
+                        missing,
                     )
                     .await
                 },
@@ -1117,6 +1174,7 @@ impl PerspectiveViewerElement {
                         RestoreMode::Existing { active: true },
                         update,
                         errors,
+                        missing,
                     )
                     .await
                 },
@@ -1129,6 +1187,7 @@ impl PerspectiveViewerElement {
                         id,
                         *config,
                         None,
+                        missing,
                     )
                     .await?;
                     Ok(())
@@ -1139,25 +1198,47 @@ impl PerspectiveViewerElement {
         js_sys::Promise::from(fut).unchecked_into()
     }
 
-    /// 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
-    /// falls back to the single-panel path.
+    /// Apply a [`WorkspaceConfigUpdate`] to the element — the multi-panel
+    /// counterpart of [`Self::restore`] and like it a field-wise update, where
+    /// an absent field is unchanged, `null` resets and a value replaces.
+    ///
+    /// # Arguments
+    ///
+    /// - `update` - The workspace config update: a [`Self::saveWorkspace`]
+    ///   token replaces every panel (`panels` is the whole set), while a token
+    ///   without `panels` keeps them and `layout`, `active` and `masters` name
+    ///   them by their existing ids.
+    /// - `options.wait_for_table` - when `true`, a panel whose `table` no
+    ///   loaded client hosts yet is created empty and pending until the table
+    ///   is created, instead of the default error.
     ///
     /// # JavaScript Examples
     ///
     /// ```javascript
     /// await viewer.restoreWorkspace(await otherViewer.saveWorkspace());
     /// ```
-    pub fn restoreWorkspace(&self, update: JsWorkspaceConfigUpdate) -> JsVoidPromise {
-        let update: JsViewerConfigUpdate = update.unchecked_into();
+    ///
+    /// Cross-filter the current panels without re-creating them:
+    ///
+    /// ```javascript
+    /// await viewer.restoreWorkspace({ global_filters: [["Region", "==", "West"]] });
+    /// ```
+    pub fn restoreWorkspace(
+        &self,
+        update: JsWorkspaceConfigUpdate,
+        options: Option<JsRestoreWorkspaceOptions>,
+    ) -> JsVoidPromise {
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         let fut = ApiFuture::new(async move {
             let _effect = effect;
+            let RestoreWorkspaceOptions { wait_for_table } = parse_options(options)?;
+            let missing = MissingTable::from_wait(wait_for_table);
             let (contents, eject_tasks) = sync_update_panels(&this, update)?;
+            let fresh = contents
+                .iter()
+                .map(|(id, ..)| id.clone())
+                .collect::<Vec<_>>();
             let results = join_all(contents.into_iter().map(|(id, session, renderer, config)| {
                 let presentation = this.presentation.clone();
                 let workspace = this.workspace.clone();
@@ -1171,6 +1252,7 @@ impl PerspectiveViewerElement {
                         RestoreMode::Fresh,
                         config,
                         crate::tasks::RestoreErrors::Publish,
+                        missing,
                     )
                     .await?;
                     if workspace.is_master(&id) {
@@ -1183,6 +1265,7 @@ impl PerspectiveViewerElement {
             .await;
 
             results.into_iter().collect::<ApiResult<Vec<_>>>()?;
+            this.rerender_retained_overlays(&fresh).await?;
             join_all(eject_tasks)
                 .await
                 .into_iter()
@@ -1246,9 +1329,9 @@ impl PerspectiveViewerElement {
     /// });
     /// ```
     pub fn save(&self, options: Option<JsPanelOptions>) -> JsViewerConfigPromise {
-        let PanelOptions { panel: name } = parse_options(options);
         let this = self.clone();
         let fut = ApiFuture::new(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             this.workspace.effects().settle().await;
             let panel = this.resolve_panel(name)?;
             let viewer_config = panel
@@ -1282,9 +1365,12 @@ impl PerspectiveViewerElement {
         &self,
         options: Option<JsSaveWorkspaceOptions>,
     ) -> JsWorkspaceConfigPromise {
-        let SaveWorkspaceOptions { full_palette } = parse_options(options);
         let this = self.clone();
-        let fut = ApiFuture::new(Self::workspace_config(this, full_palette.unwrap_or(false)));
+        let fut = ApiFuture::new(async move {
+            let SaveWorkspaceOptions { full_palette } = parse_options(options)?;
+            Self::workspace_config(this, full_palette.unwrap_or(false)).await
+        });
+
         js_sys::Promise::from(fut).unchecked_into()
     }
 
@@ -1303,13 +1389,13 @@ impl PerspectiveViewerElement {
     /// })
     /// ```
     pub fn download(&self, options: Option<JsExportOptions>) -> ApiFuture<()> {
-        let ExportOptions {
-            method,
-            panel: name,
-        } = parse_options(options);
-        let method = method.map(|m| JsString::from(m.as_str()));
         let this = self.clone();
         ApiFuture::new_throttled(async move {
+            let ExportOptions {
+                method,
+                panel: name,
+            } = parse_options(options)?;
+            let method = method.map(|m| JsString::from(m.as_str()));
             let method = if let Some(method) = method
                 .map(|x| x.unchecked_into())
                 .map(serde_wasm_bindgen::from_value)
@@ -1350,13 +1436,14 @@ impl PerspectiveViewerElement {
     /// const data = await viewer.export("plugin");
     /// ```
     pub fn export(&self, options: Option<JsExportOptions>) -> ApiFuture<JsValue> {
-        let ExportOptions {
-            method,
-            panel: name,
-        } = parse_options(options);
-        let method = method.map(|m| JsString::from(m.as_str()));
         let this = self.clone();
         ApiFuture::new(async move {
+            let ExportOptions {
+                method,
+                panel: name,
+            } = parse_options(options)?;
+
+            let method = method.map(|m| JsString::from(m.as_str()));
             let method = if let Some(method) = method
                 .map(|x| x.unchecked_into())
                 .map(serde_wasm_bindgen::from_value)
@@ -1388,13 +1475,14 @@ impl PerspectiveViewerElement {
     /// })
     /// ```
     pub fn copy(&self, options: Option<JsExportOptions>) -> ApiFuture<()> {
-        let ExportOptions {
-            method,
-            panel: name,
-        } = parse_options(options);
-        let method = method.map(|m| JsString::from(m.as_str()));
         let this = self.clone();
         ApiFuture::new_throttled(async move {
+            let ExportOptions {
+                method,
+                panel: name,
+            } = parse_options(options)?;
+
+            let method = method.map(|m| JsString::from(m.as_str()));
             let method = if let Some(method) = method
                 .map(|x| x.unchecked_into())
                 .map(serde_wasm_bindgen::from_value)
@@ -1433,11 +1521,11 @@ impl PerspectiveViewerElement {
     /// await viewer.reset(true, {panel: "p1"});  // just "p1", + expressions
     /// ```
     pub fn reset(&self, reset_all: Option<bool>, options: Option<JsPanelOptions>) -> ApiFuture<()> {
-        let PanelOptions { panel: name } = parse_options(options);
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         let all = reset_all.unwrap_or_default();
         ApiFuture::new_throttled(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             let _effect = effect;
             let (completion, receiver) = Completion::new();
             {
@@ -1615,7 +1703,7 @@ impl PerspectiveViewerElement {
     /// region of the named panel, or the active panel when `panel` is omitted.
     #[wasm_bindgen]
     pub fn getSelection(&self, options: Option<JsPanelOptions>) -> ApiResult<Option<JsViewWindow>> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let panel = self.resolve_panel(name)?;
         Ok(panel.renderer.get_selection().map(|x| x.into()))
     }
@@ -1628,7 +1716,7 @@ impl PerspectiveViewerElement {
         window: Option<JsViewWindow>,
         options: Option<JsPanelOptions>,
     ) -> ApiResult<()> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let window = window.map(|x| x.into_serde_ext()).transpose()?;
         self.resolve_panel(name)?.renderer.set_selection(window);
         Ok(())
@@ -1639,7 +1727,7 @@ impl PerspectiveViewerElement {
     /// `panel` is omitted.
     #[wasm_bindgen]
     pub fn getEditPort(&self, options: Option<JsPanelOptions>) -> ApiResult<f64> {
-        let PanelOptions { panel: name } = parse_options(options);
+        let PanelOptions { panel: name } = parse_options(options)?;
         let panel = self.resolve_panel(name)?;
         let edit_port = if let Some(ctx) = panel.renderer.render_context() {
             ctx.edit_port
@@ -1855,13 +1943,25 @@ impl PerspectiveViewerElement {
     ///
     /// The element-level `settings` field does not exist on the argument
     /// type (it is shared across the element, not per-panel).
+    ///
+    /// # Arguments
+    ///
+    /// - `config` - The new panel's initial config, whose `table` is required.
+    /// - `options.wait_for_table` - when `true`, a `table` no loaded client
+    ///   hosts yet creates the panel empty and pending until the table is
+    ///   created, instead of the default rejection.
     #[wasm_bindgen]
-    pub fn addPanel(&self, config: JsViewerConfigInitial) -> ApiFuture<JsValue> {
+    pub fn addPanel(
+        &self,
+        config: JsViewerConfigInitial,
+        options: Option<JsAddPanelOptions>,
+    ) -> 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 AddPanelOptions { wait_for_table } = parse_options(options)?;
             let config = ViewerConfigInitial::decode(&config)?;
             let id = create_panel(
                 &elem,
@@ -1871,6 +1971,7 @@ impl PerspectiveViewerElement {
                 None,
                 config,
                 None,
+                MissingTable::from_wait(wait_for_table),
             )
             .await?;
             Ok(JsValue::from_str(id.as_str()))
@@ -1960,10 +2061,10 @@ impl PerspectiveViewerElement {
         column_name: String,
         options: Option<JsPanelOptions>,
     ) -> ApiFuture<()> {
-        let PanelOptions { panel: name } = parse_options(options);
         let effect = self.workspace.effects().guard();
         let this = self.clone();
         ApiFuture::new_throttled(async move {
+            let PanelOptions { panel: name } = parse_options(options)?;
             let _effect = effect;
             let panel = this.resolve_panel(name)?;
             let was_active = this.workspace.active_id().as_ref() == Some(&panel.id);

package/src/rust/js/plugin.rs

@@ -53,8 +53,10 @@ extern "C" {
     #[wasm_bindgen(method, catch, js_name = column_config_schema)]
     pub fn _column_config_schema(this: &JsPerspectiveViewerPlugin, view_type: &str, group: Option<&str>, column_name: &str, current_value: &JsValue, view_config: &JsValue, column_stats: &JsValue) -> ApiResult<JsValue>;
 
+    /// The plugin-level settings schema as it applies to `current_value`, the
+    /// `plugin_config` state the schema should describe.
     #[wasm_bindgen(method, catch, js_name = plugin_config_schema)]
-    pub fn _plugin_config_schema(this: &JsPerspectiveViewerPlugin, view_config: &JsValue) -> ApiResult<JsValue>;
+    pub fn _plugin_config_schema(this: &JsPerspectiveViewerPlugin, view_config: &JsValue, current_value: &JsValue) -> ApiResult<JsValue>;
 
     /// STATE TRANSFER, not rendering (dispatch semantics, rule for
     /// `restore`/`save`): deliver a `plugin_config` + `columns_config`