@perspective-dev/viewer 4.5.1 → 5.0.0

package/src/rust/custom_elements/viewer.rs

@@ -16,15 +16,18 @@ use std::cell::RefCell;
 use std::rc::Rc;
 
 use futures::channel::oneshot::channel;
+use futures::future::join_all;
 use js_sys::{Array, JsString};
 use perspective_client::config::ViewConfigUpdate;
 use perspective_client::utils::PerspectiveResultExt;
+use perspective_js::utils::global;
 use perspective_js::{JsViewConfig, JsViewWindow, Table, View, apierror};
 use wasm_bindgen::JsCast;
 use wasm_bindgen::prelude::*;
 use wasm_bindgen_derive::try_from_js_option;
 use wasm_bindgen_futures::JsFuture;
 use web_sys::HtmlElement;
+use yew::Callback;
 
 use crate::components::viewer::{PerspectiveViewerMsg, PerspectiveViewerProps};
 use crate::config::*;
@@ -32,20 +35,59 @@ use crate::custom_events::*;
 use crate::js::*;
 use crate::presentation::*;
 use crate::queries::*;
-use crate::renderer::*;
 use crate::root::Root;
-use crate::session::{ResetOptions, Session, TableLoadState};
+use crate::session::{ResetOptions, TableLoadState};
 use crate::tasks::*;
 use crate::utils::*;
+use crate::workspace::{Panel, PanelId, Workspace};
 use crate::*;
 
 #[wasm_bindgen]
 extern "C" {
+    /// `load()` argument: a [`Client`], a (deprecated) [`Table`], or a
+    /// `Promise` resolving to either. Typed rather than `any` so callers get
+    /// completion; the `Table` forms remain runtime-deprecated.
+    #[wasm_bindgen(typescript_type = "Client | Table | Promise<Client | Table>")]
+    pub type JsClientLoad;
+
+    /// `eject()` argument dict (`{ client?: string }`).
+    #[wasm_bindgen(typescript_type = "ClientOptions")]
+    pub type JsClientOptions;
+
+    /// Panel-selector dict (`{ panel?: string }`) for the active/base
+    /// accessor methods.
+    #[wasm_bindgen(typescript_type = "PanelOptions")]
+    pub type JsPanelOptions;
+
+    /// `download`/`export`/`copy` options dict
+    /// (`{ method?: ExportMethod, panel?: string }`).
+    #[wasm_bindgen(typescript_type = "ExportOptions")]
+    pub type JsExportOptions;
+
+    /// `getTable` options dict (`{ wait?: boolean, panel?: string }`).
+    #[wasm_bindgen(typescript_type = "GetTableOptions")]
+    pub type JsGetTableOptions;
+
+    /// `getClient` options dict (`{ wait?: boolean, panel?: string }`).
+    #[wasm_bindgen(typescript_type = "GetClientOptions")]
+    pub type JsGetClientOptions;
+
+    /// `restoreWorkspace()` argument: a whole-element config update.
+    #[wasm_bindgen(typescript_type = "WorkspaceConfigUpdate")]
+    pub type JsWorkspaceConfigUpdate;
+
+    /// `saveWorkspace()` return: a whole-element config.
+    #[wasm_bindgen(typescript_type = "Promise<WorkspaceConfig>")]
+    pub type JsWorkspaceConfigPromise;
+
+    /// A `Promise<void>` return, used by the `restore` family (whose
+    /// `ApiFuture<()>` would otherwise erase to `Promise<any>`).
+    #[wasm_bindgen(typescript_type = "Promise<void>")]
+    pub type JsVoidPromise;
+
+    /// `save()` return: a single-panel config.
     #[wasm_bindgen(typescript_type = "Promise<ViewerConfig>")]
     pub type JsViewerConfigPromise;
-
-    #[wasm_bindgen(typescript_type = "ViewerConfigUpdate")]
-    pub type JsViewerConfigUpdate;
 }
 
 #[derive(serde::Deserialize, Default)]
@@ -59,6 +101,20 @@ struct ResizeDimensions {
     height: f64,
 }
 
+/// Leniently deserialize an optional JS options dict into a serde struct,
+/// 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
+where
+    T: Into<JsValue>,
+    U: Default + for<'a> serde::Deserialize<'a>,
+{
+    options
+        .and_then(|o| o.into_serde_ext().ok())
+        .unwrap_or_default()
+}
+
 /// The `<perspective-viewer>` custom element.
 ///
 /// # JavaScript Examples
@@ -86,13 +142,13 @@ struct ResizeDimensions {
 #[derive(Clone)]
 #[wasm_bindgen]
 pub struct PerspectiveViewerElement {
-    elem: HtmlElement,
-    root: Root<components::viewer::PerspectiveViewer>,
-    resize_handle: Rc<RefCell<Option<ResizeObserverHandle>>>,
-    intersection_handle: Rc<RefCell<Option<IntersectionObserverHandle>>>,
-    pub(crate) session: Session,
-    pub(crate) renderer: Renderer,
     pub(crate) presentation: Presentation,
+    pub(crate) workspace: Workspace,
+    pub(crate) elem: HtmlElement,
+    pub(crate) root: Root<components::viewer::PerspectiveViewer>,
+    resize_handle: Rc<RefCell<Option<ResizeObserverHandle>>>,
+    intersection_handle: Rc<RefCell<Option<AutoPauseHandle>>>,
+    hosted_table_subs: HostedTableSubs,
     _subscriptions: Rc<[Subscription; 2]>,
     _custom_event_subs: Rc<Vec<Subscription>>,
 }
@@ -103,6 +159,111 @@ impl CustomElementMetadata for PerspectiveViewerElement {
         ["registerPlugin", "get_wasm_module", "get_worker_url"].as_slice();
 }
 
+impl PerspectiveViewerElement {
+    fn layout_changed_notify(&self) -> Callback<()> {
+        let root = self.root.clone();
+        Callback::from(move |_: ()| {
+            if let Some(app) = root.borrow().as_ref() {
+                app.send_message(PerspectiveViewerMsg::LayoutChanged);
+            }
+        })
+    }
+
+    fn resolve_panel(&self, name: Option<String>) -> ApiResult<Panel> {
+        let id = name.map(PanelId::from);
+        self.workspace.panel_or_active(id.as_ref()).ok_or_else(|| {
+            format!(
+                "No panel named \"{}\"",
+                id.as_ref().map(PanelId::as_str).unwrap_or_default()
+            )
+            .into()
+        })
+    }
+
+    fn layout_element(&self) -> Option<RegularLayout> {
+        self.elem
+            .shadow_root()?
+            .query_selector(RegularLayout::TAG_NAME)
+            .ok()
+            .flatten()
+            .map(|el| el.unchecked_into())
+    }
+
+    async fn workspace_config(this: Self) -> ApiResult<JsValue> {
+        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()?;
+            let config = panel
+                .renderer
+                .clone()
+                .with_lock(async {
+                    get_viewer_config(&panel.session, &panel.renderer, &this.presentation).await
+                })
+                .await?;
+
+            panels.insert(id.as_str().to_owned(), config.panel);
+        }
+
+        let active = this
+            .presentation
+            .is_settings_open()
+            .then(|| this.workspace.active_id())
+            .flatten()
+            .map(|id| id.as_str().to_owned());
+
+        let layout = this
+            .layout_element()
+            .map(|l| l.save().into_serde_ext::<crate::js::Layout>())
+            .transpose()?;
+
+        Ok(JsValue::from_serde_ext(&WorkspaceConfig {
+            version: API_VERSION.to_string(),
+            active,
+            layout,
+            panels,
+            global_filters: this.workspace.global_filters(),
+            masters: this
+                .workspace
+                .masters()
+                .iter()
+                .map(|id| id.as_str().to_owned())
+                .collect(),
+        })?)
+    }
+}
+
+fn eject_client_panels(
+    workspace: &Workspace,
+    root: &Root<crate::components::viewer::PerspectiveViewer>,
+    target: String,
+    ids: Vec<PanelId>,
+) -> ApiFuture<()> {
+    clone!(workspace, root);
+    let effect = workspace.effects().guard();
+    ApiFuture::new_throttled(async move {
+        let _effect = effect;
+        for id in ids {
+            let (completion, receiver) = Completion::new();
+            root.borrow()
+                .as_ref()
+                .into_apierror()?
+                .send_message(PerspectiveViewerMsg::ClosePanel(
+                    id.to_string(),
+                    Some(completion),
+                ));
+
+            receiver.await.map_err(|_| ApiError::new("Cancelled"))??;
+        }
+
+        workspace.remove_client(&target);
+        Ok(())
+    })
+}
+
+#[rustfmt::skip]
+const DEPRECATED_TABLE_MESSAGE: &str =
+    "`load(table)` is deprecated - use `load(client)` followed by `restore({table: \"name\"})` instead";
+
 #[wasm_bindgen]
 impl PerspectiveViewerElement {
     #[doc(hidden)]
@@ -118,58 +279,58 @@ impl PerspectiveViewerElement {
     }
 
     fn new_from_shadow(elem: web_sys::HtmlElement, shadow_root: web_sys::Element) -> Self {
-        // Application State
-        let session = Session::new();
-        let renderer = Renderer::new(&elem);
+        // Application State.
         let presentation = Presentation::new(&elem);
-        let custom_event_subs = wire_custom_events(&elem, &session, &renderer, &presentation);
+
+        // Boot with ZERO panels — an unconfigured element is a blank stage. The
+        // first `load`/`restore`/`addPanel` creates the first panel, which
+        // adopts the element's `theme` attribute when set (see
+        // `create_panel_model`'s authored-theme boot).
+        let workspace = Workspace::new();
+        let custom_event_subs = wire_element_events(&elem, &presentation, &workspace);
 
         // Create Yew App
         let props = yew::props!(PerspectiveViewerProps {
             elem: elem.clone(),
-            session: session.clone(),
-            renderer: renderer.clone(),
             presentation: presentation.clone(),
+            workspace: workspace.clone(),
         });
 
         let state = props.clone();
         let root = Root::new(shadow_root, props);
 
         // Create callbacks
-        let update_sub = session.table_updated.add_listener({
-            clone!(renderer, session);
+        let eject_sub = presentation.on_eject.add_listener({
+            let root = root.clone();
             move |_| {
-                clone!(renderer, session);
+                clone!(state.workspace, root);
                 ApiFuture::spawn(async move {
-                    renderer
-                        .update(session.get_view())
-                        .await
-                        .ignore_view_delete()
-                        .map(|_| ())
+                    if let Some(target) = workspace.active_client().map(|c| c.get_name().to_owned())
+                    {
+                        let ids = workspace.panels_for_client(&target);
+                        if ids.len() < workspace.panel_ids().len() {
+                            return eject_client_panels(&workspace, &root, target, ids).await;
+                        }
+                    }
+
+                    delete_all(&workspace, &root).await
                 })
             }
         });
 
-        let eject_sub = presentation.on_eject.add_listener({
-            let root = root.clone();
-            move |_| ApiFuture::spawn(delete_all(&state.session, &state.renderer, &root))
-        });
-
-        let resize_handle =
-            ResizeObserverHandle::new(&elem, &renderer, &session, &presentation, &root);
-
-        let intersect_handle =
-            IntersectionObserverHandle::new(&elem, &presentation, &session, &renderer);
+        let resize_handle = ResizeObserverHandle::new(&elem, &workspace, &presentation, &root);
+        let intersect_handle = AutoPauseHandle::new(&elem, &presentation, &workspace);
+        let (lifecycle_sub, hosted_table_subs) = wire_table_lifecycle(&workspace, &presentation);
 
         Self {
             elem,
             root,
-            session,
-            renderer,
             presentation,
+            workspace,
             resize_handle: Rc::new(RefCell::new(Some(resize_handle))),
             intersection_handle: Rc::new(RefCell::new(Some(intersect_handle))),
-            _subscriptions: Rc::new([update_sub, eject_sub]),
+            hosted_table_subs,
+            _subscriptions: Rc::new([eject_sub, lifecycle_sub]),
             _custom_event_subs: Rc::new(custom_event_subs),
         }
     }
@@ -255,69 +416,206 @@ impl PerspectiveViewerElement {
     /// const table = await worker.table("x\n1", {name: "table_one"});
     /// await viewer.load(table);
     /// ```
-    pub fn load(&self, table: JsValue) -> ApiResult<ApiFuture<()>> {
+    pub fn load(&self, client: JsClientLoad) -> ApiResult<ApiFuture<()>> {
+        let effect = self.workspace.effects().guard();
+        let table: JsValue = client.into();
         let promise = table
             .clone()
             .dyn_into::<js_sys::Promise>()
             .unwrap_or_else(|_| js_sys::Promise::resolve(&table));
 
-        let _plugin = self.renderer.get_active_plugin()?;
-        let reset_task = self.session.reset(ResetOptions {
-            config: true,
-            expressions: true,
-            stats: true,
-            table: Some(session::TableIntermediateState::Reloaded),
-        });
-
-        clone!(self.renderer, self.session);
-        Ok(ApiFuture::new_throttled(async move {
-            let task = async {
-                // Ignore this error, which is blown away by the table anyway.
-                let _ = reset_task.await;
-                let jstable = JsFuture::from(promise)
-                    .await
-                    .map_err(|x| apierror!(TableError(x)))?;
-
-                if let Ok(Some(table)) =
-                    try_from_js_option::<perspective_js::Table>(jstable.clone())
+        // Resolve the target panel. On an EMPTY element (zero panels):
+        //  - a synchronously-detectable `Client` registers inertly with NO panel (the
+        //    common `load(client)` — no phantom panel is left behind);
+        //  - otherwise (a resolved `Table`, or a `Promise` whose type isn't yet known)
+        //    the first panel is RESERVED synchronously here — a full panel model held
+        //    in the workspace's reservation slot, NOT placed — so its ordering position
+        //    is fixed at the call site: a `restore()` fired right after an unawaited
+        //    `load()` CLAIMS the reservation (placing it) and targets THIS panel, not a
+        //    second one. The reservation is likewise placed when the payload proves to
+        //    be a `Table` (or the load fails, surfacing its error), and discarded —
+        //    only while still unclaimed — for an inert `Client` payload. Placement and
+        //    discard are both atomic slot transfers (`Workspace::claim_reserved` /
+        //    `Workspace::take_reserved`), so an inert payload disposing a panel a
+        //    racing `restore` claimed is unrepresentable.
+        // A pre-existing active panel is used as-is (a `Client` registers
+        // inertly against it, never clearing its table).
+        let (panel, notify) = match self.workspace.active_panel() {
+            Some(panel) => (panel, None),
+            None => {
+                // Empty element — classify the payload synchronously where possible.
+                if let Ok(Some(client)) =
+                    try_from_js_option::<perspective_js::Client>(table.clone())
                 {
-                    let client = table.get_client().await;
-                    session.set_client(client.get_client().clone());
-                    let name = table.get_name().await;
-                    tracing::debug!(
-                        "Loading {:.0} rows from `Table` {}",
-                        table.size().await?,
-                        name
+                    // A resolved `Client` registers SYNCHRONOUSLY (so an unawaited
+                    // `load(client)` is visible to a `restore()` fired right after,
+                    // which creates the first panel and federates against loaded
+                    // clients) and creates NO panel — inert.
+                    self.workspace
+                        .set_default_client(client.get_client().clone());
+                    return Ok(ApiFuture::new(async { Ok(()) }));
+                }
+
+                // A resolved `Table` (or a `Promise` whose type isn't yet known)
+                // adopts the pending reservation (a second `load()` on a
+                // still-empty element), else reserves a fresh panel model.
+                let panel = self.workspace.reserved_panel().unwrap_or_else(|| {
+                    create_panel_model(
+                        &self.elem,
+                        &self.presentation,
+                        &self.workspace,
+                        None,
+                        ViewerConfigUpdate::default(),
+                        None,
+                        Placement::Reserved,
                     );
+                    self.workspace
+                        .reserved_panel()
+                        .expect("just-reserved panel is present")
+                });
+
+                // Carrying `Some(notify)` marks this load as the reservation's
+                // owner — the only call that may place or discard it below.
+                (panel, Some(self.layout_changed_notify()))
+            },
+        };
+
+        // A `Table` payload targets this panel's engines; a `Client` registers
+        // inertly against it. Selecting the panel here (not at construction)
+        // keeps the registry race safe — by `load()` time real plugins have
+        // registered.
+        let session = panel.session;
+        let renderer = panel.renderer;
+
+        // Open the pending-load window SYNCHRONOUSLY, at the call site — this
+        // is what fixes the ordering. The payload's RESET disposition (a
+        // `Table` resets the view; a `Client` does not) is unknown until the
+        // promise resolves, but the window's POSITION on the config-commit
+        // stream is fixed NOW. A `restore()` a caller fires immediately after
+        // this unawaited `load()` (the React prop-binding pattern, which has
+        // no async ordering guarantees) commits INTO this window's journal and
+        // is replayed over the reset base if the payload proves to be a
+        // `Table` — so a moved-async reset can no longer clobber a later
+        // commit. See `SESSION_CONFIG_COHERENCE_PLAN.md`.
+        let generation = session.begin_pending_load();
+
+        clone!(self.workspace, self.presentation);
+        Ok(ApiFuture::new_throttled(async move {
+            let _effect = effect;
+            renderer.set_throttle(None);
+            let _run_token = session.begin_config_run();
+            let result = {
+                clone!(session, renderer, workspace, notify);
+                renderer
+                    .clone()
+                    .render_task(|guard| async move {
+                        renderer.set_default_theme(presentation.get_default_theme_name().await);
+                        renderer.stamp_theme(None);
+                        let jstable = JsFuture::from(promise)
+                            .await
+                            .map_err(|x| apierror!(TableError(x)))?;
+
+                        if let Ok(Some(table)) =
+                            try_from_js_option::<perspective_js::Table>(jstable.clone())
+                        {
+                            tracing::warn!("{}", DEPRECATED_TABLE_MESSAGE);
+                            let Some(journal) = session.take_pending_load(generation) else {
+                                return Ok(None);
+                            };
+
+                            if let Some(notify) = &notify {
+                                place_reserved(&workspace, notify);
+                            }
 
-                    if session.set_table(name).await? {
-                        session.validate().await?.create_view().await?;
-                    }
+                            let _plugin = renderer.ensure_plugin_selected()?;
+                            let _ = renderer.mount_active_plugin();
+                            session
+                                .reset(ResetOptions {
+                                    config: true,
+                                    expressions: true,
+                                    stats: true,
+                                    table: Some(session::TableIntermediateState::Reloaded),
+                                })
+                                .await
+                                .unwrap_or_log();
+
+                            let client = table.get_client().await;
+                            let inner_client = client.get_client().clone();
+                            session.set_client(inner_client.clone());
+                            workspace.set_default_client(inner_client);
+                            let name = table.get_name().await;
+                            tracing::debug!(
+                                "Loading {:.0} rows from `Table` {}",
+                                table.size().await?,
+                                name
+                            );
+
+                            session.set_table(name).await?;
+                            for delta in journal {
+                                session.commit_view_config(delta)?;
+                            }
 
-                    Ok(session.get_view())
-                } else if let Ok(Some(client)) =
-                    wasm_bindgen_derive::try_from_js_option::<perspective_js::Client>(jstable)
-                {
-                    session.set_client(client.get_client().clone());
-                    Ok(session.get_view())
-                } else {
-                    Err(ApiError::new("Invalid argument"))
-                }
+                            session.commit_table_defaults();
+                            let (disposition, _pin) =
+                                crate::tasks::bind_snapshot(&guard, &session, &renderer).await?;
+
+                            crate::tasks::dispatch_bound(
+                                &guard,
+                                &renderer,
+                                disposition,
+                                false,
+                                crate::tasks::RunOrigin::Public,
+                            )
+                            .await?;
+
+                            Ok(None)
+                        } else if let Ok(Some(client)) = wasm_bindgen_derive::try_from_js_option::<
+                            perspective_js::Client,
+                        >(jstable)
+                        {
+                            // INERT: register the client only — never rebind or
+                            // reset the active panel (its table is preserved).
+                            // Panels bind their client lazily at table-resolution
+                            // time (`Workspace::resolve_client_for_table`). The
+                            // 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 discard = if owned_window && notify.is_some() {
+                                workspace.take_reserved()
+                            } else {
+                                None
+                            };
+
+                            workspace.set_default_client(client.get_client().clone());
+                            Ok(discard)
+                        } else {
+                            session.take_pending_load(generation);
+                            Err(ApiError::new("Invalid argument"))
+                        }
+                    })
+                    .await
             };
 
-            renderer.set_throttle(None);
-            let result = renderer.draw(task).await;
-            if let Err(e) = &result {
-                session.set_error(false, e.clone()).await?;
-            }
+            match result {
+                Err(e) => {
+                    session.take_pending_load(generation);
+                    if let Some(notify) = &notify {
+                        place_reserved(&workspace, notify);
+                    }
 
-            result
+                    session.set_error(false, e.clone()).await?;
+                    Err(e)
+                },
+                Ok(Some(panel)) => eject_panel(panel).await,
+                Ok(None) => Ok(()),
+            }
         }))
     }
 
-    /// Delete the internal [`View`] and all associated state, rendering this
+    /// Delete all internal [`View`]s and all associated state, rendering this
     /// `<perspective-viewer>` unusable and freeing all associated resources.
-    /// Does not delete the supplied [`Table`] (as this is constructed by the
+    /// Does not delete any supplied [`Table`] (as this is constructed by the
     /// callee).
     ///
     /// Calling _any_ method on a `<perspective-viewer>` after [`Self::delete`]
@@ -337,27 +635,67 @@ impl PerspectiveViewerElement {
     /// await viewer.delete();
     /// ```
     pub fn delete(self) -> ApiFuture<()> {
-        delete_all(&self.session, &self.renderer, &self.root)
+        let subs = std::mem::take(&mut *self.hosted_table_subs.borrow_mut());
+        let teardown = delete_all(&self.workspace, &self.root);
+        ApiFuture::new(async move {
+            for (client, id) in subs {
+                let _ = client.remove_hosted_tables_update(id).await;
+            }
+
+            teardown.await
+        })
     }
 
-    /// Restart this `<perspective-viewer>` to its initial state, before
-    /// `load()`.
+    /// Remove a [`Client`] from this `<perspective-viewer>` and dispose every
+    /// panel bound to it (each panel's `View` is deleted and its `Table`
+    /// reference released).
+    ///
+    /// # Arguments
     ///
-    /// Use `Self::restart` if you plan to call `Self::load` on this viewer
-    /// again, or alternatively `Self::delete` if this viewer is no longer
-    /// needed.
-    pub fn eject(&mut self) -> ApiFuture<()> {
-        if matches!(self.session.has_table(), Some(TableLoadState::Loaded)) {
+    /// - `options` - An optional `{client?: string}` dict naming the client to
+    ///   eject; the active panel's client when omitted.
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// await viewer.eject();
+    /// await viewer.eject({client: "remote"});
+    /// ```
+    pub fn eject(&mut self, options: Option<JsClientOptions>) -> ApiFuture<()> {
+        let ClientOptions { client } = parse_options(options);
+        // 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
+            .or_else(|| {
+                self.workspace
+                    .active_client()
+                    .map(|c| c.get_name().to_owned())
+            })
+            .or_else(|| {
+                self.workspace
+                    .default_client()
+                    .map(|c| c.get_name().to_owned())
+            })
+        else {
+            return ApiFuture::new_throttled(async move { Ok(()) });
+        };
+
+        let ids = self.workspace.panels_for_client(&target);
+
+        // The target client backs EVERY panel — reset the element to its
+        // pre-`load` state (dropping the client with it), as a `Workspace`
+        // must always keep at least one panel.
+        if !ids.is_empty() && ids.len() == self.workspace.panel_ids().len() {
             let mut state = Self::new_from_shadow(
                 self.elem.clone(),
                 self.elem.shadow_root().unwrap().unchecked_into(),
             );
 
             std::mem::swap(self, &mut state);
-            ApiFuture::new_throttled(state.delete())
-        } else {
-            ApiFuture::new_throttled(async move { Ok(()) })
+            return ApiFuture::new_throttled(state.delete());
         }
+
+        eject_client_panels(&self.workspace, &self.root, target, ids)
     }
 
     /// Get the underlying [`View`] for this viewer.
@@ -380,9 +718,13 @@ impl PerspectiveViewerElement {
     /// const view = await viewer.getView();
     /// ```
     #[wasm_bindgen]
-    pub fn getView(&self) -> ApiFuture<View> {
-        let session = self.session.clone();
-        ApiFuture::new(async move { Ok(session.get_view().ok_or("No table set")?.into()) })
+    pub fn getView(&self, options: Option<JsPanelOptions>) -> ApiFuture<View> {
+        let PanelOptions { panel: name } = parse_options(options);
+        let this = self.clone();
+        ApiFuture::new(async move {
+            let panel = this.resolve_panel(name)?;
+            Ok(panel.session.get_view().ok_or("No table set")?.into())
+        })
     }
 
     /// Get a copy of the [`ViewConfig`] for the current [`View`]. This is
@@ -390,21 +732,18 @@ impl PerspectiveViewerElement {
     /// [`PerspectiveViewerElement::save`]), and also makes no API calls to the
     /// server (unlike [`PerspectiveViewerElement::getView`] followed by
     /// [`View::get_config`])
-    ///
-    /// Returns the [`ViewConfig`] the currently-bound `View` was constructed
-    /// from, so the value is consistent with what the active plugin is
-    /// rendering even if a queued [`Self::restore`]/`update_and_render` has
-    /// already mutated the live config in anticipation of the next draw.
-    /// Falls back to the live session config when no `View` has yet been
-    /// created (e.g., after `load` but before the first render).
     #[wasm_bindgen]
-    pub fn getViewConfig(&self) -> ApiFuture<JsViewConfig> {
-        let session = self.session.clone();
+    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 config = if let Some(rendered) = session.get_rendered_view_config() {
+            let panel = this.resolve_panel(name)?;
+            let config = if let Some(ctx) = panel.renderer.render_context() {
+                (*ctx.view_config).clone()
+            } else if let Some(rendered) = panel.session.get_rendered_view_config() {
                 (*rendered).clone()
             } else {
-                session.get_view_config().clone()
+                panel.session.get_view_config().clone()
             };
 
             Ok(JsValue::from_serde_ext(&config)?.unchecked_into())
@@ -427,9 +766,21 @@ impl PerspectiveViewerElement {
     /// const table = await viewer.getTable();
     /// ```
     #[wasm_bindgen]
-    pub fn getTable(&self, wait_for_table: Option<bool>) -> ApiFuture<Table> {
-        let session = self.session.clone();
+    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 panel = this.resolve_panel(name)?;
+            if !wait_for_table.unwrap_or_default()
+                && let Some(ctx) = panel.renderer.render_context()
+            {
+                return Ok(ctx.table.clone().into());
+            }
+
+            let session = panel.session;
             match session.get_table() {
                 Some(table) => Ok(table.into()),
                 None if !wait_for_table.unwrap_or_default() => Err("No `Table` set".into()),
@@ -457,9 +808,24 @@ impl PerspectiveViewerElement {
     /// const client = await viewer.getClient();
     /// ```
     #[wasm_bindgen]
-    pub fn getClient(&self, wait_for_client: Option<bool>) -> ApiFuture<perspective_js::Client> {
-        let session = self.session.clone();
+    pub fn getClient(
+        &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 panel = this.resolve_panel(name)?;
+            if !wait_for_client.unwrap_or_default()
+                && let Some(ctx) = panel.renderer.render_context()
+            {
+                return Ok(ctx.client.clone().into());
+            }
+
+            let session = panel.session;
             match session.get_client() {
                 Some(client) => Ok(client.into()),
                 None if !wait_for_client.unwrap_or_default() => Err("No `Client` set".into()),
@@ -481,9 +847,11 @@ impl PerspectiveViewerElement {
     /// const {virtual_fps, actual_fps} = await viewer.getRenderStats();
     /// ```
     #[wasm_bindgen]
-    pub fn getRenderStats(&self) -> ApiResult<JsValue> {
+    pub fn getRenderStats(&self, options: Option<JsPanelOptions>) -> ApiResult<JsValue> {
+        let PanelOptions { panel: name } = parse_options(options);
+        let panel = self.resolve_panel(name)?;
         Ok(JsValue::from_serde_ext(
-            &self.renderer.render_timer().get_stats(),
+            &panel.renderer.render_timer().get_stats(),
         )?)
     }
 
@@ -506,25 +874,62 @@ impl PerspectiveViewerElement {
     /// await viewer.flush();
     /// ```
     pub fn flush(&self) -> ApiFuture<()> {
-        clone!(self.renderer);
+        let workspace = self.workspace.clone();
+        let presentation = self.presentation.clone();
         ApiFuture::new_throttled(async move {
-            // We must let two AFs pass to guarantee listeners to the DOM state
-            // have themselves triggered, or else `request_animation_frame`
-            // may finish before a `ResizeObserver` triggered before is
-            // notifiedd.
-            //
-            // https://github.com/w3c/csswg-drafts/issues/9560
-            // https://html.spec.whatwg.org/multipage/webappapis.html#update-the-rendering
-            request_animation_frame().await;
-            request_animation_frame().await;
-            renderer.clone().with_lock(async { Ok(()) }).await?;
-            renderer.with_lock(async { Ok(()) }).await
+            loop {
+                workspace.effects().settle().await;
+                let panels = workspace
+                    .reserved_panel()
+                    .into_iter()
+                    .chain(workspace.panels())
+                    .collect::<Vec<_>>();
+
+                let mut fulfilled = false;
+                for panel in &panels {
+                    panel.renderer.clone().with_lock(async { Ok(()) }).await?;
+                    panel.renderer.clone().with_lock(async { Ok(()) }).await?;
+                    panel.session.settle_dispatches().await?;
+                    if !global::document().hidden()
+                        && presentation.is_visible()
+                        && !panel.renderer.is_plugin_activated()?
+                        && panel.session.get_error().is_none()
+                        && matches!(panel.session.has_table(), Some(TableLoadState::Loaded))
+                    {
+                        set_panel_paused(&panel.session, &panel.renderer, &presentation, true)
+                            .await?;
+                        if !panel.renderer.is_plugin_activated()? {
+                            just_render(&panel.session, &panel.renderer)?.await?;
+                        }
+
+                        fulfilled = true;
+                    }
+                }
+
+                if !fulfilled && workspace.effects().is_empty() {
+                    return Ok(());
+                }
+            }
         })
     }
 
-    /// Restores this element from a full/partial
-    /// [`perspective_js::JsViewConfig`] (this element's user-configurable
-    /// state, including the `Table` name).
+    /// Restore a single panel from a full/partial
+    /// [`perspective_js::JsViewConfig`] (its user-configurable state, including
+    /// the `Table` name) — the active panel, or a specific panel via the
+    /// 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.
+    ///
+    /// 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`
+    /// map) must be applied via [`Self::restoreWorkspace`] — its `panels` /
+    /// `layout` keys are ignored here.
     ///
     /// One of the best ways to use [`Self::restore`] is by first configuring
     /// a `<perspective-viewer>` as you wish, then using either the `Debug`
@@ -535,6 +940,7 @@ 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.
     ///
     /// # JavaScript Examples
     ///
@@ -551,102 +957,199 @@ impl PerspectiveViewerElement {
     /// ```javascript
     /// await viewer.restore({group_by: ["State"]});
     /// ```
-    pub fn restore(&self, update: JsViewerConfigUpdate) -> ApiFuture<()> {
+    pub fn restore(
+        &self,
+        update: JsViewerConfigUpdate,
+        options: Option<JsPanelOptions>,
+    ) -> JsVoidPromise {
+        let PanelOptions { panel: name } = parse_options(options);
+        let effect = self.workspace.effects().guard();
         let this = self.clone();
-        ApiFuture::new_throttled(async move {
-            let decoded_update = ViewerConfigUpdate::decode(&update)?;
-            tracing::info!("Restoring {}", decoded_update);
-            let root = this.root.clone();
-            let settings = decoded_update.settings.clone();
-            let (sender, receiver) = channel::<()>();
-            root.borrow().as_ref().into_apierror()?.send_message(
-                PerspectiveViewerMsg::ToggleSettingsComplete(settings, sender),
-            );
-
-            let task = if let OptionalUpdate::Update(_) = &decoded_update.table {
-                Some(this.session.reset(ResetOptions {
-                    config: true,
-                    expressions: true,
-                    stats: true,
-                    ..ResetOptions::default()
-                }))
-            } else {
-                None
-            };
-
-            let result = restore_and_render(
-                &this.session,
-                &this.renderer,
-                &this.presentation,
-                decoded_update.clone(),
-                {
-                    clone!(this, decoded_update.table);
-                    async move {
-                        if let OptionalUpdate::Update(name) = table {
-                            if let Some(task) = task {
-                                task.await?;
-                            }
+        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()) {
+                // An existing (or the active) panel — update it in place.
+                Some(panel) => {
+                    let active = this.workspace.active_id().as_ref() == Some(&panel.id);
+                    restore_panel(
+                        &panel.session,
+                        &panel.renderer,
+                        &this.presentation,
+                        &this.workspace,
+                        Some(&this.root),
+                        RestoreMode::Existing { active },
+                        update,
+                    )
+                    .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(())
+                        },
+                    }
+                },
+            }
+        });
 
-                            this.session.set_table(name).await?;
-                            this.session
-                                .update_column_defaults(&this.renderer.metadata());
-                        };
+        js_sys::Promise::from(fut).unchecked_into()
+    }
 
-                        // Something abnormal in the DOM happened, e.g. the
-                        // element was disconnected while rendering.
-                        receiver.await.unwrap_or_log();
-                        Ok(())
+    /// Restore the ENTIRE element from a whole-element
+    /// [`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.
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// await viewer.restoreWorkspace(await otherViewer.saveWorkspace());
+    /// ```
+    pub fn restoreWorkspace(&self, update: JsWorkspaceConfigUpdate) -> JsVoidPromise {
+        let update: JsViewerConfigUpdate = update.unchecked_into();
+        let effect = self.workspace.effects().guard();
+        let this = self.clone();
+        let fut = ApiFuture::new(async move {
+            let _effect = effect;
+            let (contents, eject_tasks) = sync_update_panels(&this, update)?;
+            let results = join_all(contents.into_iter().map(|(id, session, renderer, config)| {
+                let presentation = this.presentation.clone();
+                let workspace = this.workspace.clone();
+                async move {
+                    stamp_global_overlay(&workspace, &id, &session);
+                    restore_panel(
+                        &session,
+                        &renderer,
+                        &presentation,
+                        &workspace,
+                        None,
+                        RestoreMode::Fresh,
+                        config,
+                    )
+                    .await?;
+                    if workspace.is_master(&id) {
+                        set_edit_mode(&session, &renderer, "SELECT_ROW_TREE");
                     }
-                },
-            )
+
+                    Ok(())
+                }
+            }))
             .await;
 
-            if let Err(e) = &result {
-                this.session.set_error(false, e.clone()).await?;
-            }
-            result
-        })
+            results.into_iter().collect::<ApiResult<Vec<_>>>()?;
+            join_all(eject_tasks)
+                .await
+                .into_iter()
+                .collect::<ApiResult<Vec<_>>>()?;
+
+            Ok(())
+        });
+
+        js_sys::Promise::from(fut).unchecked_into()
     }
 
     /// If this element is in an _errored_ state, this method will clear it and
     /// re-render. Calling this method is equivalent to clicking the error reset
     /// button in the UI.
     pub fn resetError(&self) -> ApiFuture<()> {
-        ApiFuture::spawn(self.session.reset(ResetOptions::default()));
-        let this = self.clone();
+        let Some(panel) = self.workspace.active_panel() else {
+            return ApiFuture::new_throttled(async move { Ok(()) });
+        };
+
+        let reset_effect = self.workspace.effects().guard();
+        let reset_task = panel.session.reset(ResetOptions::default());
+        ApiFuture::spawn(async move {
+            let _effect = reset_effect;
+            reset_task.await
+        });
+
+        let effect = self.workspace.effects().guard();
         ApiFuture::new_throttled(async move {
-            update_and_render(&this.session, &this.renderer, ViewConfigUpdate::default())?.await?;
+            let _effect = effect;
+            apply_and_render(&panel.session, &panel.renderer, ViewConfigUpdate::default())?.await?;
             Ok(())
         })
     }
 
-    /// Save this element's user-configurable state to a serialized state
-    /// object, one which can be restored via the [`Self::restore`] method.
+    /// Save a single panel's user-configurable state as a [`ViewerConfig`], one
+    /// which can be restored via [`Self::restore`] — the active panel, or a
+    /// specific panel via the optional `{panel}` selector.
+    ///
+    /// This saves a SINGLE panel; to snapshot the ENTIRE element (every panel +
+    /// layout + cross-filters) use [`Self::saveWorkspace`].
+    ///
+    /// # Arguments
+    ///
+    /// - `options` - An optional `{panel?: string}`; the panel to save, or the
+    ///   active panel when omitted.
     ///
     /// # JavaScript Examples
     ///
     /// Get the current `group_by` setting:
     ///
     /// ```javascript
-    /// const {group_by} = await viewer.restore();
+    /// const {group_by} = await viewer.save();
     /// ```
     ///
     /// Reset workflow attached to an external button `myResetButton`:
     ///
     /// ```javascript
     /// const token = await viewer.save();
-    /// myResetButton.addEventListener("clien", async () => {
+    /// myResetButton.addEventListener("click", async () => {
     ///     await viewer.restore(token);
     /// });
     /// ```
-    pub fn save(&self) -> JsViewerConfigPromise {
+    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 viewer_config = this
+            let panel = this.resolve_panel(name)?;
+            let viewer_config = panel
                 .renderer
                 .clone()
                 .with_lock(async {
-                    get_viewer_config(&this.session, &this.renderer, &this.presentation).await
+                    get_viewer_config(&panel.session, &panel.renderer, &this.presentation).await
                 })
                 .await?;
 
@@ -656,6 +1159,24 @@ 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`].
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// const token = await viewer.saveWorkspace();
+    /// await viewer.restoreWorkspace(token);
+    /// ```
+    pub fn saveWorkspace(&self) -> JsWorkspaceConfigPromise {
+        let this = self.clone();
+        let fut = ApiFuture::new(Self::workspace_config(this));
+        js_sys::Promise::from(fut).unchecked_into()
+    }
+
     /// Download this viewer's internal [`View`] data via a browser download
     /// event.
     ///
@@ -670,7 +1191,12 @@ impl PerspectiveViewerElement {
     ///     await viewer.download();
     /// })
     /// ```
-    pub fn download(&self, method: Option<JsString>) -> ApiFuture<()> {
+    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 method = if let Some(method) = method
@@ -682,10 +1208,11 @@ impl PerspectiveViewerElement {
                 ExportMethod::Csv
             };
 
+            let panel = this.resolve_panel(name)?;
             let blob =
-                export_method_to_blob(&this.session, &this.renderer, &this.presentation, method)
+                export_method_to_blob(&panel.session, &panel.renderer, &this.presentation, method)
                     .await?;
-            let is_chart = this.renderer.is_chart();
+            let is_chart = panel.renderer.is_chart();
             download(
                 format!("untitled{}", method.as_filename(is_chart)).as_ref(),
                 &blob,
@@ -711,7 +1238,12 @@ impl PerspectiveViewerElement {
     /// ```javascript
     /// const data = await viewer.export("plugin");
     /// ```
-    pub fn export(&self, method: Option<JsString>) -> ApiFuture<JsValue> {
+    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 method = if let Some(method) = method
@@ -723,7 +1255,8 @@ impl PerspectiveViewerElement {
                 ExportMethod::Csv
             };
 
-            export_method_to_jsvalue(&this.session, &this.renderer, &this.presentation, method)
+            let panel = this.resolve_panel(name)?;
+            export_method_to_jsvalue(&panel.session, &panel.renderer, &this.presentation, method)
                 .await
         })
     }
@@ -743,7 +1276,12 @@ impl PerspectiveViewerElement {
     ///     await viewer.copy();
     /// })
     /// ```
-    pub fn copy(&self, method: Option<JsString>) -> ApiFuture<()> {
+    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 method = if let Some(method) = method
@@ -755,36 +1293,64 @@ impl PerspectiveViewerElement {
                 ExportMethod::Csv
             };
 
+            let panel = this.resolve_panel(name)?;
             let js_task =
-                export_method_to_blob(&this.session, &this.renderer, &this.presentation, method);
+                export_method_to_blob(&panel.session, &panel.renderer, &this.presentation, method);
             copy_to_clipboard(js_task, MimeType::TextPlain).await
         })
     }
 
-    /// Reset the viewer's `ViewerConfig` to the default.
+    /// 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.
     ///
     /// # Arguments
     ///
     /// - `reset_all` - If set, will clear expressions and column settings as
     ///   well.
+    /// - `options` - An optional `{panel?: string}`; the panel to reset, or
+    ///   every panel when omitted.
     ///
     /// # JavaScript Examples
     ///
     /// ```javascript
-    /// await viewer.reset();
+    /// await viewer.reset();                     // every panel
+    /// await viewer.reset(true, {panel: "p1"});  // just "p1", + expressions
     /// ```
-    pub fn reset(&self, reset_all: Option<bool>) -> ApiFuture<()> {
-        tracing::debug!("Resetting config");
-        let root = self.root.clone();
+    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 (sender, receiver) = channel::<()>();
-            root.borrow()
-                .as_ref()
-                .ok_or("Already deleted")?
-                .send_message(PerspectiveViewerMsg::Reset(all, Some(sender)));
+            let _effect = effect;
+            let (completion, receiver) = Completion::new();
+            {
+                let root = this.root.borrow();
+                let app = root.as_ref().ok_or("Already deleted")?;
+                match name {
+                    // Element-level: reset every panel + the cross-filter overlay.
+                    None => {
+                        tracing::debug!("Resetting config");
+                        app.send_message(PerspectiveViewerMsg::Reset(all, Some(completion)));
+                    },
+                    // A single named panel; errors if the panel doesn't exist.
+                    Some(name) => {
+                        let panel = this.resolve_panel(Some(name))?;
+                        tracing::debug!("Resetting config ({})", panel.id);
+                        app.send_message(PerspectiveViewerMsg::ResetPanel(
+                            Some(panel.id.to_string()),
+                            all,
+                            Some(completion),
+                        ));
+                    },
+                }
+            }
 
-            Ok(receiver.await?)
+            receiver.await.map_err(|_| ApiError::new("Cancelled"))?
         })
     }
 
@@ -817,18 +1383,27 @@ impl PerspectiveViewerElement {
             .unwrap_or_default()
             .unwrap_or_default();
 
-        let state = self.clone();
+        let effect = self.workspace.effects().guard();
+        let workspace = self.workspace.clone();
         ApiFuture::new_throttled(async move {
-            if !state.renderer.is_plugin_activated()? {
-                update_and_render(&state.session, &state.renderer, ViewConfigUpdate::default())?
+            let _effect = effect;
+            // With zero panels there is nothing to resize; fan out to whatever
+            // panels exist otherwise.
+            let Some(panel) = workspace.active_panel() else {
+                resize_visible_panels(&workspace).await;
+                return Ok(());
+            };
+
+            if !panel.renderer.is_plugin_activated()? {
+                apply_and_render(&panel.session, &panel.renderer, ViewConfigUpdate::default())?
                     .await?;
             } else if let Some(dims) = opts.dimensions {
-                state
+                panel
                     .renderer
                     .resize_with_dimensions(dims.width, dims.height)
                     .await?;
             } else {
-                state.renderer.resize().await?;
+                resize_visible_panels(&workspace).await;
             }
 
             Ok(())
@@ -860,8 +1435,7 @@ impl PerspectiveViewerElement {
         if autosize {
             let handle = Some(ResizeObserverHandle::new(
                 &self.elem,
-                &self.renderer,
-                &self.session,
+                &self.workspace,
                 &self.presentation,
                 &self.root,
             ));
@@ -873,10 +1447,11 @@ impl PerspectiveViewerElement {
 
     /// Sets the auto-pause behavior of this component.
     ///
-    /// When `true`, this `<perspective-viewer>` will register an
-    /// `IntersectionObserver` on itself and subsequently skip rendering
-    /// whenever its viewport visibility changes. Auto-pause is enabled by
-    /// default.
+    /// When `true`, this `<perspective-viewer>` will skip rendering
+    /// whenever it cannot be seen — tracked via an `IntersectionObserver`
+    /// on itself (scrolled out of the viewport, `display: none`) combined
+    /// with the document's page visibility (backgrounded browser tab,
+    /// minimized window). Auto-pause is enabled by default.
     ///
     /// # Arguments
     ///
@@ -892,53 +1467,75 @@ impl PerspectiveViewerElement {
     #[wasm_bindgen]
     pub fn setAutoPause(&self, autopause: bool) -> ApiFuture<()> {
         if autopause {
-            let handle = Some(IntersectionObserverHandle::new(
+            let handle = Some(AutoPauseHandle::new(
                 &self.elem,
                 &self.presentation,
-                &self.session,
-                &self.renderer,
+                &self.workspace,
             ));
 
             *self.intersection_handle.borrow_mut() = handle;
         } else {
             *self.intersection_handle.borrow_mut() = None;
-            if self.session.set_pause(false) {
-                return ApiFuture::new(restore_and_render(
-                    &self.session,
-                    &self.renderer,
-                    &self.presentation,
-                    ViewerConfigUpdate::default(),
-                    async move { Ok(()) },
-                ));
-            }
+            let effect = self.workspace.effects().guard();
+            let workspace = self.workspace.clone();
+            let presentation = self.presentation.clone();
+            return ApiFuture::new(async move {
+                let _effect = effect;
+                for id in workspace.panel_ids() {
+                    if let Some(panel) = workspace.panel(&id) {
+                        // A failed resume is already surfaced as that
+                        // panel's error state — don't let it abort the
+                        // remaining panels' resumes.
+                        let _ =
+                            set_panel_paused(&panel.session, &panel.renderer, &presentation, true)
+                                .await;
+                    }
+                }
+
+                Ok(())
+            });
         }
 
         ApiFuture::new(async move { Ok(()) })
     }
 
     /// Return a [`perspective_js::JsViewWindow`] for the currently selected
-    /// region.
+    /// region of the named panel, or the active panel when `panel` is omitted.
     #[wasm_bindgen]
-    pub fn getSelection(&self) -> Option<JsViewWindow> {
-        self.renderer.get_selection().map(|x| x.into())
+    pub fn getSelection(&self, options: Option<JsPanelOptions>) -> ApiResult<Option<JsViewWindow>> {
+        let PanelOptions { panel: name } = parse_options(options);
+        let panel = self.resolve_panel(name)?;
+        Ok(panel.renderer.get_selection().map(|x| x.into()))
     }
 
-    /// Set the selection [`perspective_js::JsViewWindow`] for this element.
+    /// Set the selection [`perspective_js::JsViewWindow`] for the named panel,
+    /// or the active panel when `panel` is omitted.
     #[wasm_bindgen]
-    pub fn setSelection(&self, window: Option<JsViewWindow>) -> ApiResult<()> {
+    pub fn setSelection(
+        &self,
+        window: Option<JsViewWindow>,
+        options: Option<JsPanelOptions>,
+    ) -> ApiResult<()> {
+        let PanelOptions { panel: name } = parse_options(options);
         let window = window.map(|x| x.into_serde_ext()).transpose()?;
-        self.renderer.set_selection(window);
+        self.resolve_panel(name)?.renderer.set_selection(window);
         Ok(())
     }
 
-    /// Get this viewer's edit port for the currently loaded [`Table`] (see
-    /// [`Table::update`] for details on ports).
+    /// Get this viewer's edit port for the named panel's [`Table`] (see
+    /// [`Table::update`] for details on ports), or the active panel when
+    /// `panel` is omitted.
     #[wasm_bindgen]
-    pub fn getEditPort(&self) -> Result<f64, JsValue> {
-        self.session
-            .metadata()
-            .get_edit_port()
-            .ok_or_else(|| "No `Table` loaded".into())
+    pub fn getEditPort(&self, options: Option<JsPanelOptions>) -> ApiResult<f64> {
+        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
+        } else {
+            panel.session.metadata().get_edit_port()
+        };
+
+        Ok(edit_port.ok_or("No `Table` loaded")?)
     }
 
     /// Restyle all plugins from current document.
@@ -959,10 +1556,21 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn restyleElement(&self) -> ApiFuture<JsValue> {
-        clone!(self.renderer, self.session);
+        clone!(self.workspace, self.presentation);
+        let effect = workspace.effects().guard();
         ApiFuture::new(async move {
-            let view = session.get_view().into_apierror()?;
-            renderer.restyle_all(&view).await
+            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?;
+            }
+
+            Ok(JsValue::UNDEFINED)
         })
     }
 
@@ -982,8 +1590,10 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn resetThemes(&self, themes: Option<Box<[JsValue]>>) -> ApiFuture<JsValue> {
-        clone!(self.renderer, self.session, self.presentation);
+        clone!(self.workspace, self.presentation);
+        let effect = workspace.effects().guard();
         ApiFuture::new(async move {
+            let _effect = effect;
             let themes: Option<Vec<String>> = themes
                 .unwrap_or_default()
                 .iter()
@@ -991,17 +1601,37 @@ impl PerspectiveViewerElement {
                 .collect();
 
             let theme_name = presentation.get_selected_theme_name().await;
-            let mut changed = presentation.reset_available_themes(themes).await;
-            let reset_theme = presentation
-                .get_available_themes()
-                .await?
+            presentation.reset_available_themes(themes).await;
+            let available = presentation.get_available_themes().await?;
+            let reset_theme = available
                 .iter()
                 .find(|y| theme_name.as_ref() == Some(y))
                 .cloned();
 
-            changed = presentation.set_theme_name(reset_theme.as_deref()).await? || changed;
-            if changed && let Some(view) = session.get_view() {
-                return renderer.restyle_all(&view).await;
+            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?;
+                }
             }
 
             Ok(JsValue::UNDEFINED)
@@ -1027,7 +1657,14 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn setThrottle(&self, val: Option<f64>) {
-        self.renderer.set_throttle(val);
+        for panel in self
+            .workspace
+            .panel_ids()
+            .into_iter()
+            .filter_map(|id| self.workspace.panel(&id))
+        {
+            panel.renderer.set_throttle(val);
+        }
     }
 
     /// Toggle (or force) the config panel open/closed.
@@ -1044,8 +1681,10 @@ impl PerspectiveViewerElement {
     /// ```
     #[wasm_bindgen]
     pub fn toggleConfig(&self, force: Option<bool>) -> ApiFuture<JsValue> {
+        let effect = self.workspace.effects().guard();
         let root = self.root.clone();
         ApiFuture::new(async move {
+            let _effect = effect;
             let force = force.map(SettingsUpdate::Update);
             let (sender, receiver) = channel::<ApiResult<wasm_bindgen::JsValue>>();
             root.borrow().as_ref().into_apierror()?.send_message(
@@ -1061,7 +1700,10 @@ impl PerspectiveViewerElement {
     /// [`registerPlugin`] after the host has rendered for the first time.
     #[wasm_bindgen]
     pub fn getAllPlugins(&self) -> Array {
-        self.renderer.get_all_plugins().iter().collect::<Array>()
+        self.workspace
+            .active_renderer()
+            .map(|r| r.get_all_plugins().iter().collect::<Array>())
+            .unwrap_or_default()
     }
 
     /// Gets a plugin Custom Element with the `name` field, or get the active
@@ -1073,12 +1715,108 @@ impl PerspectiveViewerElement {
     ///   or `None` for the active plugin's Custom Element.
     #[wasm_bindgen]
     pub fn getPlugin(&self, name: Option<String>) -> ApiResult<JsPerspectiveViewerPlugin> {
+        let renderer = self
+            .workspace
+            .active_renderer()
+            .ok_or_else(|| ApiError::new("No active panel"))?;
         match name {
-            None => self.renderer.get_active_plugin(),
-            Some(name) => self.renderer.get_plugin(&name),
+            None => renderer.ensure_plugin_selected(),
+            Some(name) => renderer.get_plugin(&name),
         }
     }
 
+    /// 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.
+    #[wasm_bindgen]
+    pub fn addPanel(&self, update: JsViewerConfigUpdate) -> 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 id = create_panel(
+                &elem,
+                &presentation,
+                &workspace,
+                &notify,
+                None,
+                update,
+                None,
+            )
+            .await?;
+            Ok(JsValue::from_str(id.as_str()))
+        })
+    }
+
+    /// Get the ids of all panels in this viewer's layout, in insertion order.
+    #[wasm_bindgen]
+    pub fn getPanelNames(&self) -> Array {
+        self.workspace
+            .panel_ids()
+            .iter()
+            .map(|id| JsValue::from_str(id.as_str()))
+            .collect()
+    }
+
+    /// The id of the active panel — the one the settings panel and status-bar
+    /// toolbar target — or `null` when the element has zero panels.
+    #[wasm_bindgen]
+    pub fn getActivePanel(&self) -> JsValue {
+        self.workspace
+            .active_id()
+            .map(|id| JsValue::from_str(id.as_str()))
+            .unwrap_or(JsValue::NULL)
+    }
+
+    /// Make the panel with id `name` the active panel, re-targeting the
+    /// settings panel and status-bar toolbar (and the root's
+    /// session/renderer subscriptions) to its engines. Resolves after the
+    /// activation-chrome redraws on both sides of the switch have completed
+    /// (invariant I6).
+    #[wasm_bindgen]
+    pub fn setActivePanel(&self, name: String) -> ApiFuture<()> {
+        let effect = self.workspace.effects().guard();
+        let root = self.root.clone();
+        ApiFuture::new(async move {
+            let _effect = effect;
+            let (completion, receiver) = Completion::new();
+            root.borrow()
+                .as_ref()
+                .into_apierror()?
+                .send_message(PerspectiveViewerMsg::SetActivePanel(name, Some(completion)));
+
+            receiver.await.map_err(|_| ApiError::new("Cancelled"))?
+        })
+    }
+
+    /// Remove the panel with id `name` from the layout, disposing its engines
+    /// (its `View` is deleted and its `Table` reference released). The last
+    /// remaining panel cannot be removed (resolves as a no-op). Resolves
+    /// after the panel's teardown run completes, carrying any teardown
+    /// error — previously fire-and-forget and silently dropped (invariant
+    /// I6). See also [`Self::addPanel`].
+    #[wasm_bindgen]
+    pub fn removePanel(&self, name: String) -> ApiFuture<()> {
+        let effect = self.workspace.effects().guard();
+        let root = self.root.clone();
+        ApiFuture::new(async move {
+            let _effect = effect;
+            let (completion, receiver) = Completion::new();
+            root.borrow()
+                .as_ref()
+                .into_apierror()?
+                .send_message(PerspectiveViewerMsg::ClosePanel(name, Some(completion)));
+
+            receiver.await.map_err(|_| ApiError::new("Cancelled"))?
+        })
+    }
+
     /// Create a new JavaScript Heap reference for this model instance.
     #[doc(hidden)]
     #[allow(clippy::use_self)]
@@ -1094,40 +1832,31 @@ impl PerspectiveViewerElement {
     /// string}`. The CustomEvent is also fired whenever the user toggles the
     /// sidebar manually.
     #[wasm_bindgen]
-    pub fn toggleColumnSettings(&self, column_name: String) -> ApiFuture<()> {
-        clone!(self.session, self.root);
-        ApiFuture::new_throttled(async move {
-            let locator = get_column_locator(&session.metadata(), Some(column_name));
-            let (sender, receiver) = channel::<()>();
-            root.borrow().as_ref().into_apierror()?.send_message(
-                PerspectiveViewerMsg::OpenColumnSettings {
-                    locator,
-                    sender: Some(sender),
-                    toggle: true,
-                },
-            );
-
-            receiver.await.map_err(|_| ApiError::from("Cancelled"))
-        })
-    }
-
-    /// Force open the settings for a particular column. Pass `null` to close
-    /// the column settings panel. See [`Self::toggleColumnSettings`] for more.
-    #[wasm_bindgen]
-    pub fn openColumnSettings(
+    pub fn toggleColumnSettings(
         &self,
-        column_name: Option<String>,
-        toggle: Option<bool>,
+        column_name: String,
+        options: Option<JsPanelOptions>,
     ) -> ApiFuture<()> {
-        let locator = get_column_locator(&self.session.metadata(), column_name);
-        clone!(self.root);
+        let PanelOptions { panel: name } = parse_options(options);
+        let effect = self.workspace.effects().guard();
+        let this = self.clone();
         ApiFuture::new_throttled(async move {
+            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));
+            if !was_active {
+                this.root.borrow().as_ref().into_apierror()?.send_message(
+                    PerspectiveViewerMsg::SetActivePanel(panel.id.as_str().to_owned(), None),
+                );
+            }
+
             let (sender, receiver) = channel::<()>();
-            root.borrow().as_ref().into_apierror()?.send_message(
+            this.root.borrow().as_ref().into_apierror()?.send_message(
                 PerspectiveViewerMsg::OpenColumnSettings {
                     locator,
                     sender: Some(sender),
-                    toggle: toggle.unwrap_or_default(),
+                    toggle: was_active,
                 },
             );