@perspective-dev/viewer 4.5.1 → 5.0.0

package/src/rust/tasks/restore_and_render.rs

@@ -11,11 +11,13 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 //! Apply a full [`ViewerConfigUpdate`] (settings, theme, title, plugin,
-//! plugin_config, columns_config, view_config) and re-draw.
+//! plugin_config, columns_config, view_config) and re-draw, on the snapshot
+//! pipeline (see `tasks/pipeline.rs` / `SESSION_CONFIG_COHERENCE_PLAN.md`).
 
 use futures::Future;
 use perspective_client::clone;
 
+use super::pipeline::{RunOrigin, RunSpec, locked_run};
 use crate::config::{OptionalUpdate, ViewerConfigUpdate};
 use crate::presentation::Presentation;
 use crate::renderer::Renderer;
@@ -25,10 +27,24 @@ use crate::*;
 /// Apply a full [`ViewerConfigUpdate`] (theme, title, plugin selection,
 /// plugin config, columns config, view config) to the engines and re-draw.
 /// Returns an [`ApiFuture<()>`] which resolves when the draw completes.
+///
+/// `origin` says who initiated the restore ([`RunOrigin`]): a `Public`
+/// element-API call keeps the no-op-restore refresh affordance (an
+/// `Unchanged` reconcile still repaints via `update`); an `Internal`
+/// restore that reconciles `Unchanged` and changes no plugin state
+/// dispatches nothing.
+///
+/// This function owns the PRE-LOCK prologue only (element-level settings /
+/// title / host-theme mirror, plugin resolution, the synchronous config
+/// commit and spinner token); the run itself is
+/// [`locked_run`] with the caller's `task` awaited inside the lock. The
+/// `update`'s `table` field is NOT applied here — table binding is the
+/// `task`'s job (see `restore_panel` / `table_lifecycle`).
 pub fn restore_and_render(
     session: &Session,
     renderer: &Renderer,
     presentation: &Presentation,
+    origin: RunOrigin,
     ViewerConfigUpdate {
         plugin,
         plugin_config,
@@ -54,103 +70,81 @@ pub fn restore_and_render(
             session.set_title(None);
         }
 
-        let needs_restyle = match theme_name {
+        // Mirror a config-carried theme onto the host attribute (the shared
+        // chrome). The restyle a theme change requires is owned by the
+        // MUTATION SITES (`restorePanel`'s own-theme tail, the theme-picker
+        // task), not here — this run's own draw below already stamps the new
+        // effective theme before the plugin's first style read.
+        match theme_name {
             OptionalUpdate::SetDefault => {
                 let current_name = presentation.get_selected_theme_name().await;
                 if current_name.is_some() {
                     presentation.set_theme_name(None).await?;
-                    true
-                } else {
-                    false
                 }
             },
             OptionalUpdate::Update(x) => {
-                let current_name = presentation.get_selected_theme_name().await;
-                if current_name.is_some() && current_name.as_ref().unwrap() != &x {
-                    presentation.set_theme_name(Some(&x)).await?;
-                    true
-                } else {
-                    false
-                }
+                // No pre-resolution gate: `set_theme_name` stamps the host
+                // attribute SYNCHRONOUSLY before its registry await and
+                // no-ops on literal equality itself. The old
+                // `get_selected_theme_name().await` guard was precisely
+                // the former-theme window on a cold registry — the host
+                // held the old attribute until stylesheet parsing (and
+                // everything queued behind it) resolved.
+                presentation.set_theme_name(Some(&x)).await?;
             },
-            _ => false,
+            _ => {},
         };
 
-        if let Some(metadata) = renderer.get_next_plugin_metadata(&plugin) {
-            session.set_update_column_defaults(&mut view_config, &metadata);
+        // Resolve the target plugin here (pure — needed now for
+        // `set_update_column_defaults`), but COMMIT it only inside the locked
+        // run below, atomically with the view rebind it belongs to. No swap
+        // intent may exist outside that run: an unrelated run that wins the
+        // lock first (e.g. a `table_updated` redraw) must observe either the
+        // fully-old or fully-new world, never a staged half of this one.
+        let resolved_plugin = renderer.resolve_plugin_update(&plugin);
+        if let Some((_, metadata)) = &resolved_plugin {
+            session.set_update_column_defaults(&mut view_config, metadata);
+        } else {
+            // Same-plugin (or plugin-less) restore: `resolve_plugin_update`
+            // returns `None`, but the plugin-advised `group_rollup_mode`
+            // must STILL be enforced against the active plugin's metadata —
+            // `restorePanel`'s table-change reset wipes the committed mode,
+            // and nothing else on this path would restore it, leaving a
+            // flat-only chart (Treemap / Sunburst) rendering rollup
+            // subtotal rows. Rollup only; the full column-defaults pass is
+            // reserved for plugin swaps, where `columns` genuinely needs
+            // re-defaulting.
+            session.set_update_rollup_defaults(&mut view_config, &renderer.metadata());
         }
 
-        session.update_view_config(view_config)?;
-        let draw_task = renderer.draw(async {
-            task.await?;
-            let plugin_swapped = renderer.apply_pending_plugin()?;
-            let plugin = renderer.get_active_plugin()?;
-
-            // The previous call which acquired the lock errored, so skip this render
-            if let Some(error) = session.get_error() {
-                return Err(error);
-            }
-
-            // Validate + create the view BEFORE applying
-            // columns_config / plugin_config updates, so the
-            // strip-on-write and materialize passes see fresh
-            // `expression_schema` and `view_schema`, and the
-            // materialize warm step can call `View::get_min_max`
-            // against a view that knows about any new expression
-            // columns. Previously this happened after the strip,
-            // which silently dropped any `columns_config` entry
-            // keyed by a new expression column.
-            let view = session.validate().await?.create_view().await?;
-
-            // Apply incoming updates into the now-active plugin's
-            // bucket on `Renderer`. Per-plugin storage means no
-            // schema filter is needed before restore — foreign keys
-            // cannot appear in the bucket by construction. The
-            // renderer methods also strip schema-default entries so
-            // restored maps containing default values produce an
-            // empty bucket (correct: bucket-empty ⇒ reads-default).
-            let view_config_snapshot = session.get_view_config().clone();
-            let plugin_config_changed =
-                renderer.update_plugin_config(&view_config_snapshot, plugin_config);
-            let columns_config_changed =
-                renderer.update_columns_configs(&view_config_snapshot, &session, columns_config);
-            let changed = plugin_config_changed || columns_config_changed;
-
-            // Force a materialized restore when the plugin just
-            // swapped — `commit_plugin_idx` already restored from the
-            // raw bucket, but the materialized restore is needed for
-            // schema-revealed `include: true` defaults to reach the
-            // plugin before its first draw.
-            if changed || plugin_swapped {
-                let plugin_config_snapshot = renderer.get_plugin_config();
-                let plugin_update =
-                    wasm_bindgen::JsValue::from_serde_ext(&plugin_config_snapshot).unwrap();
-                let columns_config = renderer
-                    .all_columns_configs_materialized(&view_config_snapshot, &session)
-                    .await;
-                plugin.restore(&plugin_update, Some(&columns_config))?;
-                if plugin_config_changed {
-                    renderer.plugin_config_changed.emit(plugin_config_snapshot);
-                }
-            }
-
-            if !presentation.is_visible() {
-                Ok(None)
-            } else {
-                Ok(view)
-            }
-        });
-
-        draw_task.await?;
-
-        // TODO this should be part of the API for `draw()` above, such that
-        // the plugin need not render twice when a theme is provided.
-        if needs_restyle
-            && presentation.is_visible()
-            && let Some(view) = session.get_view()
-        {
-            renderer.restyle_all(&view).await?;
-        }
+        let plugin_idx = resolved_plugin.map(|(idx, _)| idx);
+
+        // The config COMMIT: synchronous, validated, atomic (I1/I4). Under
+        // I2/I3 committing before the lock is safe — whichever queued run
+        // snapshots next picks it up, and this run's own snapshot (taken
+        // inside the lock below) can only be this commit or fresher.
+        session.commit_view_config(view_config)?;
+
+        // Spinner accounting (RAII): held to the end of this restore —
+        // INCLUDING the deferred-draw exit (no table yet → no
+        // `bind_snapshot`), which under the old edge-counted scheme
+        // stranded the `StatusIndicator` spinner permanently.
+        let _run_token = session.begin_config_run();
+
+        // Awaits theme-registry init, so the stamp below can never observe a
+        // pre-init (empty) theme set on a cold first load. Seeds this
+        // panel's renderer default-theme cache, which every locked draw
+        // stamps the effective theme from.
+        renderer.set_default_theme(presentation.get_default_theme_name().await);
+        locked_run(&session, &renderer, RunSpec {
+            origin,
+            plugin_idx,
+            plugin_config,
+            columns_config,
+            task: Some(Box::pin(task)),
+            presentation: Some(presentation.clone()),
+        })
+        .await?;
 
         Ok(())
     })

package/src/rust/tasks/restore_panel.rs

@@ -0,0 +1,145 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use futures::channel::oneshot::channel;
+use perspective_client::clone;
+use perspective_client::utils::PerspectiveResultExt;
+
+use crate::components::viewer::{PerspectiveViewer, PerspectiveViewerMsg};
+use crate::config::*;
+use crate::presentation::Presentation;
+use crate::renderer::Renderer;
+use crate::root::Root;
+use crate::session::{ResetOptions, Session};
+use crate::tasks::*;
+use crate::workspace::Workspace;
+use crate::*;
+
+/// How a [`restore_panel`] call reached the pipeline — the only two genuine
+/// forks between updating a live panel and materializing a freshly-created one.
+pub(crate) enum RestoreMode {
+    Existing { active: bool },
+    Fresh,
+}
+
+pub(crate) async fn bind_table_task(
+    session: &Session,
+    workspace: &Workspace,
+    name: String,
+) -> ApiResult<()> {
+    let current = session.get_client();
+    if let Some(client) = workspace
+        .resolve_client_for_table(&name, current.as_ref())
+        .await
+    {
+        session.set_client(client);
+    }
+
+    session.set_table(name).await?;
+    session.commit_table_defaults();
+    Ok(())
+}
+
+/// Apply a [`ViewerConfigUpdate`] to a single panel and re-draw — the one
+/// pipeline shared by `restorePanel` (an existing panel), whole-element
+/// `restoreWorkspace`, and `addPanel` (both fresh panels).
+pub(crate) async fn restore_panel(
+    session: &Session,
+    renderer: &Renderer,
+    presentation: &Presentation,
+    workspace: &Workspace,
+    root: Option<&Root<PerspectiveViewer>>,
+    mode: RestoreMode,
+    mut update: ViewerConfigUpdate,
+) -> ApiResult<()> {
+    let active = matches!(mode, RestoreMode::Existing { active: true });
+    let fresh = matches!(mode, RestoreMode::Fresh);
+    match &update.theme {
+        OptionalUpdate::Update(theme) => renderer.set_theme_stamped(Some(theme.clone())),
+        OptionalUpdate::SetDefault => renderer.set_theme_stamped(None),
+        OptionalUpdate::Missing => {},
+    }
+
+    if !active {
+        update.theme = OptionalUpdate::Missing;
+    }
+
+    if !fresh {
+        tracing::info!("Restoring {update}");
+    }
+
+    let (sender, receiver) = channel::<()>();
+    match (active, root) {
+        (true, Some(root)) => {
+            root.borrow().as_ref().into_apierror()?.send_message(
+                PerspectiveViewerMsg::ToggleSettingsComplete(update.settings.clone(), sender),
+            );
+        },
+        _ => {
+            let _ = sender.send(());
+        },
+    }
+
+    let table_changed = !fresh
+        && matches!(&update.table, OptionalUpdate::Update(name)
+            if session.get_table().map(|t| t.get_name() != name.as_str()).unwrap_or(true));
+
+    let errored_recovery =
+        session.is_errored() && matches!(&update.table, OptionalUpdate::Update(_));
+
+    let reset = (table_changed || errored_recovery).then(|| {
+        session.reset(ResetOptions {
+            config: true,
+            expressions: true,
+            stats: true,
+            ..ResetOptions::default()
+        })
+    });
+
+    let result = restore_and_render(
+        session,
+        renderer,
+        presentation,
+        RunOrigin::Public,
+        update.clone(),
+        {
+            clone!(session, update.table, workspace);
+            async move {
+                if let OptionalUpdate::Update(name) = table {
+                    if let Some(reset) = reset {
+                        reset.await?;
+                    }
+
+                    bind_table_task(&session, &workspace, name).await?;
+                }
+
+                receiver.await.unwrap_or_log();
+                Ok(())
+            }
+        },
+    )
+    .await;
+
+    if let Err(e) = &result {
+        session.set_error(false, e.clone()).await?;
+    }
+
+    result?;
+
+    if fresh {
+        renderer.resize().await.unwrap_or_log();
+    } else if renderer.needs_restyle() {
+        renderer.restyle_all().await?;
+    }
+
+    Ok(())
+}

package/src/rust/tasks/send_column_config.rs

@@ -44,10 +44,13 @@ pub fn send_column_config(
         let plugin_token =
             wasm_bindgen::JsValue::from_serde_ext(&renderer.get_plugin_config()).unwrap();
         renderer
-            .get_active_plugin()?
+            .ensure_plugin_selected()?
             .restore(&plugin_token, Some(&columns_configs))?;
 
-        renderer.update(session.get_view()).await?;
+        clone!(session);
+        renderer
+            .update_lazy(async move { Ok(session.get_view()) })
+            .await?;
         renderer.column_style_changed.emit(columns_configs);
         Ok(())
     })

package/src/rust/tasks/send_plugin_config.rs

@@ -40,9 +40,12 @@ pub fn send_plugin_config(session: &Session, renderer: &Renderer, update: Column
                 .all_columns_configs_materialized(&view_config_snapshot, &session)
                 .await;
             renderer
-                .get_active_plugin()?
+                .ensure_plugin_selected()?
                 .restore(&plugin_token, Some(&columns_configs))?;
-            renderer.update(session.get_view()).await?;
+            clone!(session);
+            renderer
+                .update_lazy(async move { Ok(session.get_view()) })
+                .await?;
             renderer.plugin_config_changed.emit(plugin_config);
         }
 

package/src/rust/tasks/set_edit_mode.rs

@@ -0,0 +1,59 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use perspective_client::clone;
+use perspective_js::utils::*;
+
+use crate::config::*;
+use crate::renderer::Renderer;
+use crate::session::Session;
+
+/// Set the active plugin's `edit_mode`, persisting it in the [`Renderer`]'s
+/// plugin bucket and re-`restore`+rendering (the same merged-token path as
+/// [`super::send_plugin_config`], so column styles/sizes survive).
+///
+/// Master/detail uses this to put a master into `SELECT_ROW_TREE` (the mode
+/// in which the datagrid emits `perspective-global-filter` selections) and to
+/// restore `READ_ONLY` on demotion. Plugins with no `edit_mode` schema field
+/// (e.g. charts) schema-gate the key out in [`Renderer::update_plugin_config`],
+/// making this a no-op for them.
+pub fn set_edit_mode(session: &Session, renderer: &Renderer, mode: &str) {
+    let view_config = session.get_view_config().clone();
+    let mut map = serde_json::Map::new();
+    map.insert(
+        "edit_mode".to_owned(),
+        serde_json::Value::String(mode.to_owned()),
+    );
+
+    let changed = renderer.update_plugin_config(&view_config, OptionalUpdate::Update(map));
+    clone!(session, renderer);
+    ApiFuture::spawn(async move {
+        if changed {
+            let plugin_config = renderer.get_plugin_config();
+            let plugin_token = wasm_bindgen::JsValue::from_serde_ext(&plugin_config).unwrap();
+            let view_config_snapshot = session.get_view_config().clone();
+            let columns_configs = renderer
+                .all_columns_configs_materialized(&view_config_snapshot, &session)
+                .await;
+            renderer
+                .ensure_plugin_selected()?
+                .restore(&plugin_token, Some(&columns_configs))?;
+            clone!(session);
+            renderer
+                .update_lazy(async move { Ok(session.get_view()) })
+                .await?;
+            renderer.plugin_config_changed.emit(plugin_config);
+        }
+
+        Ok(())
+    })
+}

package/src/rust/tasks/sync_update_panels.rs

@@ -0,0 +1,152 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use std::collections::HashMap;
+
+use wasm_bindgen::prelude::*;
+
+use crate::components::viewer::PerspectiveViewerMsg;
+use crate::config::*;
+use crate::renderer::*;
+use crate::session::Session;
+use crate::tasks::*;
+use crate::workspace::PanelId;
+use crate::*;
+
+#[wasm_bindgen]
+extern "C" {
+    #[wasm_bindgen(typescript_type = "ViewerConfigUpdate")]
+    pub type JsViewerConfigUpdate;
+}
+
+pub type SyncUpdatePanelsResult = (
+    Vec<(PanelId, Session, Renderer, ViewerConfigUpdate)>,
+    std::vec::Vec<perspective_js::utils::ApiFuture<()>>,
+);
+
+/// Update the panel state to match a `WorkspaceConfigUpdate`.
+///
+/// This method must be synchronous.
+pub fn sync_update_panels(
+    this: &PerspectiveViewerElement,
+    update: JsViewerConfigUpdate,
+) -> ApiResult<SyncUpdatePanelsResult> {
+    let WorkspaceConfigUpdate {
+        active,
+        layout,
+        panels,
+        global_filters,
+        masters,
+    } = update.into_serde_ext()?;
+
+    let old_ids = this.workspace.panel_ids();
+
+    // Phase 1 — models only, NO renders and NO draws
+    let mut id_map: HashMap<String, String> = Default::default();
+    let mut fallback_fresh: Option<String> = None;
+    let mut active_fresh: Option<String> = None;
+    let mut contents = Vec::new();
+    for (saved_id, config) in panels {
+        if !matches!(config.settings, OptionalUpdate::Missing) {
+            #[rustfmt::skip]
+            tracing::warn!(
+                "`settings` on panel \"{saved_id}\" is ignored in a whole-element config; use the top-level `active` field"
+            );
+        }
+
+        let (fresh, session, renderer, config) = create_panel_model(
+            &this.elem,
+            &this.presentation,
+            &this.workspace,
+            None,
+            config,
+            None,
+            Placement::Placed,
+        );
+
+        if active.as_deref() == Some(saved_id.as_str()) {
+            active_fresh = Some(fresh.as_str().to_owned());
+        }
+
+        fallback_fresh.get_or_insert_with(|| fresh.as_str().to_owned());
+        id_map.insert(saved_id, fresh.as_str().to_owned());
+        contents.push((fresh, session, renderer, config));
+    }
+
+    if contents.is_empty() {
+        let (fresh, session, renderer, config) = create_panel_model(
+            &this.elem,
+            &this.presentation,
+            &this.workspace,
+            None,
+            ViewerConfigUpdate::default(),
+            None,
+            Placement::Placed,
+        );
+
+        fallback_fresh = Some(fresh.as_str().to_owned());
+        contents.push((fresh, session, renderer, config));
+    }
+
+    let mut eject_tasks = Vec::new();
+    if let Some(panel) = this.workspace.take_reserved() {
+        eject_tasks.push(eject_panel(panel));
+    }
+
+    for old in old_ids {
+        if let Some(panel) = this.workspace.remove_panel(&old) {
+            eject_tasks.push(eject_panel(panel));
+        }
+    }
+
+    // Phase 2 — stage the remapped layout tree on the Workspace
+    if let Some(layout) = layout {
+        this.workspace
+            .set_pending_layout(layout.remap(&|name| id_map.get(name).cloned()));
+    }
+
+    // Phase 3 — the single visible commit
+    if let Some(saved) = &active
+        && active_fresh.is_none()
+    {
+        tracing::warn!("`active` names unknown panel \"{saved}\"");
+    }
+
+    let sidebar_open = active_fresh.is_some();
+    if let Some(target) = active_fresh.or(fallback_fresh)
+        && let Some(app) = this.root.borrow().as_ref()
+    {
+        app.send_message(PerspectiveViewerMsg::CommitWorkspaceRestore(target));
+    }
+
+    if let Some(app) = this.root.borrow().as_ref() {
+        app.send_message(PerspectiveViewerMsg::ToggleSettingsInit(
+            Some(SettingsUpdate::Update(sidebar_open)),
+            None,
+        ));
+    }
+
+    let masters = masters
+        .into_iter()
+        .filter_map(|saved| match id_map.get(&saved) {
+            Some(fresh) => Some(PanelId::from(fresh.as_str())),
+            None => {
+                tracing::warn!("`masters` names unknown panel \"{saved}\"");
+                None
+            },
+        })
+        .collect::<Vec<_>>();
+
+    this.workspace.set_masters(masters);
+    this.workspace.set_global_filters(global_filters);
+    Ok((contents, eject_tasks))
+}