@perspective-dev/viewer 5.3.1 → 5.5.0

package/src/rust/session.rs

@@ -24,6 +24,7 @@ use std::ops::Deref;
 use std::rc::Rc;
 
 use perspective_client::config::*;
+use perspective_client::proto::ViewDimensionsResp;
 use perspective_client::{Client, ClientError, ReconnectCallback, View};
 use perspective_js::apierror;
 use perspective_js::utils::*;
@@ -56,11 +57,7 @@ pub struct SessionHandle {
     pub table_loaded: PubSub<()>,
     pub table_unloaded: PubSub<bool>,
 
-    /// Fires when a `View` was CREATED — literally: `bind_view`'s REBUILD
-    /// path constructed and bound a new engine `View`. Nothing else may
-    /// emit this (a SKIP/REUSE/paused reconcile is [`Self::commit_reconciled`],
-    /// which REBUILD also emits) — overloading it broke consumers that
-    /// relied on the name's meaning (see `UPDATE_COUNT_REGRESSION_PLAN.md`).
+    /// Fires when a `View` was CREATED — literally.
     pub view_created: PubSub<()>,
 
     /// Fires exactly once per locked run that RECONCILED the committed
@@ -74,43 +71,23 @@ pub struct SessionHandle {
     pub view_config_changed: PubSub<()>,
     pub title_changed: PubSub<Option<String>>,
 
-    /// Count of in-flight CONFIG-DRIVEN pipeline runs (commit → run
-    /// settled), incremented by [`Session::begin_config_run`] and
-    /// decremented when the returned [`ConfigRunToken`] drops. Drives the
-    /// `StatusIndicator` "updating" spinner via [`Self::run_state_changed`].
-    /// Pure redraws (resize, activation nudges, `just_render`) do NOT
-    /// count — the spinner means "a config requery is in flight".
+    /// Count of in-flight CONFIG-DRIVEN pipeline runs.
     in_flight_config_runs: Cell<u32>,
 
     /// Fires with the ABSOLUTE [`Self::in_flight_config_runs`] count after
-    /// every change. LEVEL-triggered by design: subscribers ASSIGN the
-    /// payload rather than accumulate deltas, so a dropped or reordered
-    /// notification is corrected by the next one — the delta-counting
-    /// (`view_config_changed`+1 / `view_created`−1) design this replaces
-    /// drifted whenever those streams weren't perfectly paired (see
-    /// `UPDATE_COUNT_REGRESSION_PLAN.md`).
+    /// every change.
     pub run_state_changed: PubSub<u32>,
 
     /// Fires when the user clicks the status indicator while in
-    /// [`StatusIconState::Normal`]. `wire_panel_events` is the only
-    /// listener and fans this out as the `perspective-status-indicator-click`
-    /// `CustomEvent`.
+    /// [`StatusIconState::Normal`].
     pub status_indicator_clicked: PubSub<()>,
 
-    /// Per-column numeric stats cache. Populated by the
-    /// `fetch_column_abs_max` task and consumed by the schema-query
-    /// path so plugins emit gradient defaults without
-    /// per-render `View::get_min_max` round trips. Cleared
-    /// synchronously inside [`Session::commit_view_config`].
+    /// Per-column numeric stats cache.
     column_stats: RefCell<HashMap<String, ColumnStats>>,
 
     /// Memoized snapshots used by [`Session::to_props`] to keep
     /// `PtrEqRc` identity stable across repeated `to_props()` calls
-    /// when the underlying value hasn't changed. Without this, every
-    /// `PubSub` fire (including `column_stats_changed`) produces a
-    /// fresh `Rc` for `config` / `metadata`, triggering downstream
-    /// `use_effect_with(view_config, ...)` effects to spuriously
-    /// refire — closing a loop with the stats fetch path.
+    /// when the underlying value hasn't changed.
     cached_config: RefCell<Option<PtrEqRc<ViewConfig>>>,
     cached_metadata: RefCell<Option<SessionMetadataRc>>,
 
@@ -131,18 +108,7 @@ pub struct SessionHandle {
     load_generation: Cell<u32>,
 
     /// Open between a `load()` call and its payload's classification as
-    /// `Table`/`Client` ([`PendingLoad`]). While `Some` the payload type is
-    /// unknown, so its RESET/no-RESET disposition cannot be decided yet — but
-    /// the window's POSITION on the config-commit stream is fixed at the
-    /// `load()` call site. During the window, config commits still apply live
-    /// (so `save()` stays coherent — I1) but ALSO append their raw delta to
-    /// the journal, and config-driven binds DEFER ([`Session::snapshot`]'s
-    /// caller [`crate::tasks::bind_snapshot`]) — the incoming config must
-    /// never draw against the still-bound outgoing table (hold the last
-    /// frame). Classified as `Table` the journal replays over a reset base
-    /// (`reset ∘ Δ₁ ∘ Δ₂ …`, the program-order result the old synchronous
-    /// reset guaranteed); as `Client` it is dropped (no reset — live already
-    /// carries every Δ). See `SESSION_CONFIG_COHERENCE_PLAN.md`.
+    /// `Table`/`Client` ([`PendingLoad`]).
     pending_load: RefCell<Option<PendingLoad>>,
 
     /// Coalesces `view_config_changed`: multiple synchronous commits in one
@@ -165,8 +131,11 @@ pub struct SessionHandle {
     /// new value.
     pub column_stats_changed: PubSub<()>,
 
-    /// Injected callback from the root component, replacing the former
-    /// `stats_changed: PubSub` field.  Fires when view stats are updated.
+    /// Fires when view stats are updated.
+    pub stats_changed: PubSub<()>,
+
+    /// Injected callback from the root component, driving
+    /// `session_props.has_table_cells` for the active panel.
     pub on_stats_changed: RefCell<Option<Callback<()>>>,
 
     /// Injected callback from the root component, replacing the former
@@ -183,6 +152,51 @@ impl Deref for SessionHandle {
     }
 }
 
+/// What an un-hosted `table` name means to a bind, per the `wait_for_table`
+/// option.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum MissingTable {
+    /// A hard error that leaves the panel as it was.
+    Error,
+
+    /// The panel waits unbound and binds when the name is hosted.
+    Pend,
+}
+
+impl MissingTable {
+    /// Decode the `wait_for_table` option (absent = `false` = `Error`).
+    pub fn from_wait(wait_for_table: Option<bool>) -> Self {
+        if wait_for_table.unwrap_or_default() {
+            Self::Pend
+        } else {
+            Self::Error
+        }
+    }
+}
+
+/// Open `name` on `client`, returning `Ok(None)` when the name is not hosted
+/// and `missing` is [`MissingTable::Pend`].
+pub(crate) async fn probe_table(
+    client: &Client,
+    name: &str,
+    missing: MissingTable,
+) -> ApiResult<Option<perspective_client::Table>> {
+    match client.open_table(name.to_owned()).await {
+        Ok(table) => Ok(Some(table)),
+        Err(e) => {
+            let hosted = client.get_hosted_table_names().await.unwrap_or_default();
+            if hosted.iter().any(|n| n == name) {
+                return Err(e.into());
+            }
+
+            match missing {
+                MissingTable::Pend => Ok(None),
+                MissingTable::Error => Err(ApiError::new(format!("Unknown table \"{name}\""))),
+            }
+        },
+    }
+}
+
 /// Mutable state for `Session`.
 #[derive(Default)]
 pub struct SessionData {
@@ -279,13 +293,7 @@ pub struct ResetOptions {
 #[derive(Clone)]
 pub struct Session(Rc<SessionHandle>);
 
-/// RAII spinner accounting for one config-driven pipeline run (see
-/// [`Session::begin_config_run`] and `UPDATE_COUNT_REGRESSION_PLAN.md`):
-/// created when the run is scheduled — immediately after its commit — and
-/// moved INTO the run future, so `Drop` settles the count on every exit
-/// path: completion, error, cancellation, and runs that never reach
-/// `bind_view` (the deferred-draw restore). A stranded count is
-/// unrepresentable; there is no other writer.
+/// RAII spinner accounting for one config-driven pipeline run.
 pub struct ConfigRunToken(Session);
 
 impl Drop for ConfigRunToken {
@@ -346,6 +354,7 @@ impl Session {
     /// `Session`.
     pub fn reset(&self, options: ResetOptions) -> impl Future<Output = ApiResult<()>> + use<> {
         let view = self.0.borrow_mut().view_sub.take();
+        let had_table = self.borrow().table.is_some();
         let err = self.get_error();
         self.borrow_mut().error = None;
         if options.stats {
@@ -365,11 +374,13 @@ impl Session {
                 self.borrow_mut().is_loading = false;
                 self.borrow_mut().table = None;
                 self.borrow_mut().pending_table = None;
+                self.borrow_mut().metadata = SessionMetadata::default();
             },
             Some(TableIntermediateState::Reloaded) => {
                 self.borrow_mut().is_loading = true;
                 self.borrow_mut().table = None;
                 self.borrow_mut().pending_table = None;
+                self.borrow_mut().metadata = SessionMetadata::default();
             },
             _ => {
                 self.borrow_mut().is_loading = false;
@@ -390,7 +401,7 @@ impl Session {
         let session = self.clone();
         async move {
             let res = view.delete().await;
-            if options.table.is_some() {
+            if options.table.is_some() && had_table {
                 session.table_unloaded.emit(true)
             }
 
@@ -447,6 +458,8 @@ impl Session {
             Some(TableLoadState::Loaded)
         } else if data.is_loading {
             Some(TableLoadState::Loading)
+        } else if data.pending_table.is_some() {
+            Some(TableLoadState::Pending)
         } else {
             None
         }
@@ -507,10 +520,8 @@ impl Session {
     /// `table_name` is unique per `Client`, so if this value has not changed,
     /// `Session::set_table` does nothing and returns `Ok(false)`.
     ///
-    /// A name NO loaded client hosts (yet) is not an error: the session
-    /// records it PENDING ([`SessionData::pending_table`]) and returns
-    /// `Ok(false)`; the element's hosted-tables subscription
-    /// (`tasks::table_lifecycle`) re-runs the bind when the table is created.
+    /// A name no loaded client hosts pends ([`MissingTable::Pend`]) and
+    /// returns `Ok(false)` until the table lifecycle re-runs the bind.
     pub async fn set_table(&self, table_name: String) -> ApiResult<bool> {
         if Some(table_name.as_str()) == self.0.borrow().table.as_ref().map(|x| x.get_name()) {
             self.0.borrow_mut().pending_table = None;
@@ -518,60 +529,68 @@ impl Session {
         }
 
         let client = self.0.borrow().client.clone().into_apierror()?;
-        let table = match client.open_table(table_name.clone()).await {
-            Ok(table) => table,
-            Err(e) => {
-                // Distinguish "not hosted (yet)" — which PENDS — from a real
-                // open failure by the hosted set, not the error's text.
-                let hosted = client.get_hosted_table_names().await.unwrap_or_default();
-                if hosted.iter().any(|n| n == &table_name) {
-                    return Err(e.into());
-                }
-
-                self.0.borrow_mut().pending_table = Some(table_name);
-                return Ok(false);
+        match probe_table(&client, &table_name, MissingTable::Pend).await? {
+            Some(table) => match self.bind_table(table).await {
+                Ok(()) => Ok(true),
+                Err(err) => self.set_error(false, err).await.map(|_| false),
             },
-        };
+            None => {
+                self.pend_table(table_name).await?;
+                Ok(false)
+            },
+        }
+    }
 
-        match SessionMetadata::from_table(&table).await {
-            Ok(metadata) => {
-                let client = table.get_client();
-                let on_error = self.on_table_errored.borrow().clone();
-                let session = self.clone();
-                let poll_loop = LocalPollLoop::new(move |(message, reconnect): (ApiError, _)| {
-                    session.borrow_mut().error = Some(TableErrorState(message, reconnect));
-                    if let Some(cb) = &on_error {
-                        cb.emit(());
-                    }
-                    if let Some(sub) = session.borrow_mut().view_sub.take() {
-                        sub.dismiss();
-                    }
+    /// Bind an opened `Table`, replacing any previous binding and announcing
+    /// `table_loaded`.
+    pub(crate) async fn bind_table(&self, table: perspective_client::Table) -> ApiResult<()> {
+        let metadata = SessionMetadata::from_table(&table).await?;
+        let client = table.get_client();
+        let on_error = self.on_table_errored.borrow().clone();
+        let session = self.clone();
+        let poll_loop = LocalPollLoop::new(move |(message, reconnect): (ApiError, _)| {
+            session.borrow_mut().error = Some(TableErrorState(message, reconnect));
+            if let Some(cb) = &on_error {
+                cb.emit(());
+            }
+            if let Some(sub) = session.borrow_mut().view_sub.take() {
+                sub.dismiss();
+            }
 
-                    Ok(JsValue::UNDEFINED)
-                });
-
-                let _callback_id = client
-                    .on_error(Box::new(move |message: ClientError, reconnect| {
-                        let poll_loop = poll_loop.clone();
-                        async move {
-                            poll_loop.poll((message.into(), reconnect)).await;
-                            Ok(())
-                        }
-                    }))
-                    .await?;
+            Ok(JsValue::UNDEFINED)
+        });
 
-                let sub = self.borrow_mut().view_sub.take();
-                self.borrow_mut().metadata = metadata;
-                self.borrow_mut().table = Some(table);
-                self.borrow_mut().pending_table = None;
-                self.borrow_mut().is_loading = false;
-                self.borrow_mut().last_validated_expressions = None;
-                sub.delete().await?;
-                self.table_loaded.emit(());
-                Ok(true)
-            },
-            Err(err) => self.set_error(false, err).await.map(|_| false),
-        }
+        let _callback_id = client
+            .on_error(Box::new(move |message: ClientError, reconnect| {
+                let poll_loop = poll_loop.clone();
+                async move {
+                    poll_loop.poll((message.into(), reconnect)).await;
+                    Ok(())
+                }
+            }))
+            .await?;
+
+        let sub = self.borrow_mut().view_sub.take();
+        self.borrow_mut().metadata = metadata;
+        self.borrow_mut().table = Some(table);
+        self.borrow_mut().pending_table = None;
+        self.borrow_mut().is_loading = false;
+        self.borrow_mut().last_validated_expressions = None;
+        sub.delete().await?;
+        self.table_loaded.emit(());
+        Ok(())
+    }
+
+    /// Record `name` as pending, dropping any bound `Table` so nothing binds
+    /// against the outgoing table while the name waits for a host.
+    pub(crate) async fn pend_table(&self, name: String) -> ApiResult<()> {
+        let sub = self.borrow_mut().view_sub.take();
+        self.borrow_mut().table = None;
+        self.borrow_mut().metadata = SessionMetadata::default();
+        self.borrow_mut().pending_table = Some(name);
+        self.borrow_mut().is_loading = false;
+        self.borrow_mut().last_validated_expressions = None;
+        sub.delete().await
     }
 
     pub async fn set_error(&self, reset_table: bool, err: ApiError) -> ApiResult<()> {
@@ -664,10 +683,27 @@ impl Session {
             .map(|sub| sub.get_view().clone())
     }
 
+    /// The bound `View` together with its latest known dimensions, read under
+    /// one borrow so they always belong together.
+    pub fn get_view_with_dimensions(&self) -> Option<(View, Option<ViewDimensionsResp>)> {
+        self.borrow()
+            .view_sub
+            .as_ref()
+            .map(|sub| (sub.get_view().clone(), sub.dimensions()))
+    }
+
     pub(crate) fn get_table_stats(&self) -> Option<ViewStats> {
         self.borrow().stats.clone()
     }
 
+    /// Whether the stats snapshot carries table dimensions.
+    pub(crate) fn has_table_cells(&self) -> bool {
+        self.borrow()
+            .stats
+            .as_ref()
+            .is_some_and(|s| s.num_table_cells.is_some())
+    }
+
     pub fn get_view_config(&'_ self) -> Ref<'_, ViewConfig> {
         Ref::map(self.borrow(), |x| &x.config)
     }
@@ -924,15 +960,6 @@ impl Session {
     /// Emit `view_config_changed` coalesced to one event per microtask batch.
     /// Stats are cleared synchronously per commit (idempotent — an
     /// already-empty cache no-ops, so rapid commit sequences fetch once).
-    ///
-    /// CONTRACT: this channel is COALESCED and DEFERRED — N same-batch
-    /// commits produce ONE emission, on a microtask AFTER the mutation.
-    /// Subscribers must be batch-tolerant snapshot refreshers (they re-read
-    /// live state; today: the root `SessionProps` snapshot and the debug
-    /// panel). It is NOT suitable for per-commit accounting — pairing its
-    /// edges against any other event stream WILL drift (the stuck-spinner
-    /// regression, `UPDATE_COUNT_REGRESSION_PLAN.md`); run accounting is
-    /// [`Self::begin_config_run`]'s RAII token instead.
     fn notify_view_config_changed(&self) {
         self.clear_column_stats();
         if !self.0.config_event_scheduled.replace(true) {
@@ -1123,31 +1150,7 @@ impl Session {
             .clone()
             .ok_or("`restore()` called before `load()`")?;
 
-        // Populate the aggregates with defaults as a courtesy to the
-        // virtual server api. Snapshot-local — never written back.
-        let mut view_config = (*effective).clone();
-        for col in view_config
-            .columns
-            .iter()
-            .flatten()
-            .chain(view_config.sort.iter().map(|x| &x.0))
-        {
-            if !view_config.aggregates.contains_key(col.as_str()) {
-                let agg = self
-                    .metadata()
-                    .get_column_aggregates(col.as_str())
-                    .and_then(|mut aggs| aggs.next())
-                    .into_apierror();
-
-                match agg {
-                    Err(_) => {
-                        tracing::warn!("No default aggregate for column '{}' found, skipping", col)
-                    },
-                    Ok(agg) => _ = view_config.aggregates.insert(col.to_string(), agg),
-                };
-            }
-        }
-
+        let view_config = self.with_default_aggregates(&effective);
         let view = table.view(Some(view_config.into())).await?;
         let view_schema = view.schema().await?;
         self.metadata_mut().update_view_schema(&view_schema)?;
@@ -1179,6 +1182,43 @@ impl Session {
         }
     }
 
+    /// The engine config for a `View` built from `effective`, per-column
+    /// default aggregates filled in as a courtesy to the virtual server API.
+    fn with_default_aggregates(&self, effective: &ViewConfig) -> ViewConfig {
+        let mut view_config = effective.clone();
+        for col in view_config
+            .columns
+            .iter()
+            .flatten()
+            .chain(view_config.sort.iter().map(|x| &x.0))
+        {
+            if !view_config.aggregates.contains_key(col.as_str()) {
+                let agg = self
+                    .metadata()
+                    .get_column_aggregates(col.as_str())
+                    .and_then(|mut aggs| aggs.next())
+                    .into_apierror();
+
+                match agg {
+                    Err(_) => {
+                        tracing::warn!("No default aggregate for column '{}' found, skipping", col)
+                    },
+                    Ok(agg) => _ = view_config.aggregates.insert(col.to_string(), agg),
+                };
+            }
+        }
+
+        view_config
+    }
+
+    /// Build a caller-owned `View` from the effective config outside the
+    /// render pipeline, with no subscription and no interaction with pause.
+    pub async fn create_detached_view(&self) -> ApiResult<View> {
+        let table = self.borrow().table.clone().ok_or("No `Table` set")?;
+        let view_config = self.with_default_aggregates(&self.effective_view_config());
+        Ok(table.view(Some(view_config.into())).await?)
+    }
+
     /// Record a failed pipeline run: error state plus a reconnect affordance
     /// that resets the config (the error screen's reset button). Replaces
     /// the old `validate()` error path — the committed config is NOT rolled
@@ -1218,6 +1258,8 @@ impl Session {
         if let Some(cb) = self.on_stats_changed.borrow().as_ref() {
             cb.emit(());
         }
+
+        self.stats_changed.emit(());
     }
 
     fn all_columns(&self) -> Vec<String> {
@@ -1258,11 +1300,16 @@ impl Session {
 
         SessionProps {
             config,
-            stats: data.stats.clone(),
+            has_table_cells: data
+                .stats
+                .as_ref()
+                .is_some_and(|s| s.num_table_cells.is_some()),
             has_table: if data.table.is_some() {
                 Some(TableLoadState::Loaded)
             } else if data.is_loading {
                 Some(TableLoadState::Loading)
+            } else if data.pending_table.is_some() {
+                Some(TableLoadState::Pending)
             } else {
                 None
             },
@@ -1290,15 +1337,7 @@ pub struct ConfigSnapshot {
 pub struct ValidatedSnapshot(ConfigSnapshot);
 
 /// Type-state witness that a `View` is NEW for the plugin about to render
-/// it — `plugin.draw()`'s contract (see `PLUGIN_DRAW_INVARIANT_PLAN.md`:
-/// `draw` fires iff there is a new `View`, never otherwise). Minted in
-/// exactly two places: [`Session::bind_view`]'s REBUILD arm (a new engine
-/// `View` was constructed) and
-/// [`crate::renderer::Renderer::promote_first_paint`] (a freshly-selected
-/// plugin owes its first paint of the bound `View`). Do NOT construct it
-/// anywhere else — `Renderer::draw_fresh` is the only consumer, and this
-/// witness is what makes "full draw without a new `View`" (the stacked-chart
-/// activation regression) uncompilable.
+/// it.
 pub struct FreshView(View);
 
 impl FreshView {

package/src/rust/tasks/create_panel.rs

@@ -17,7 +17,7 @@ use crate::config::*;
 use crate::custom_events::wire_panel_events;
 use crate::presentation::*;
 use crate::renderer::*;
-use crate::session::{ResetOptions, Session};
+use crate::session::{MissingTable, ResetOptions, Session};
 use crate::tasks::*;
 use crate::utils::*;
 use crate::workspace::{Panel, PanelId, PanelPhase, Workspace};
@@ -60,7 +60,7 @@ fn wire_panel_render_sub(session: &Session, renderer: &Renderer) -> Subscription
             clone!(renderer, session);
             ApiFuture::spawn(async move {
                 renderer
-                    .update_lazy(async move { Ok(session.get_view()) })
+                    .update_lazy(async move { Ok(session.get_view_with_dimensions()) })
                     .await
                     .ignore_view_delete()
                     .map(|_| ())
@@ -76,6 +76,7 @@ fn wire_panel_render_sub(session: &Session, renderer: &Renderer) -> Subscription
 /// one. `theme` is stripped (element-level, not per-panel) and `client` —
 /// or the element's default client when `None` — is bound so the config's
 /// `table` resolves against it.
+#[allow(clippy::too_many_arguments)]
 pub(crate) async fn create_panel(
     elem: &HtmlElement,
     presentation: &Presentation,
@@ -84,6 +85,7 @@ pub(crate) async fn create_panel(
     id: Option<PanelId>,
     config: ViewerConfigInitial,
     client: Option<perspective_client::Client>,
+    missing: MissingTable,
 ) -> ApiResult<PanelId> {
     let (id, session, renderer, update) = create_panel_model(
         elem,
@@ -120,6 +122,7 @@ pub(crate) async fn create_panel(
         RestoreMode::Fresh,
         update,
         crate::tasks::RestoreErrors::Publish,
+        missing,
     )
     .await;
 

package/src/rust/tasks/dismiss_render_warning.rs

@@ -28,7 +28,7 @@ pub fn dismiss_render_warning_callback(session: &Session, renderer: &Renderer) -
         ApiFuture::spawn(async move {
             renderer.disable_active_plugin_render_warning();
             renderer
-                .update_lazy(async move { Ok(session.get_view()) })
+                .update_lazy(async move { Ok(session.get_view_with_dimensions()) })
                 .await
         });
     })

package/src/rust/tasks/eject.rs

@@ -34,6 +34,7 @@ pub fn delete_all<T: Component>(workspace: &Workspace, root: &Root<T>) -> ApiFut
         let panels = workspace
             .take_reserved()
             .into_iter()
+            .chain(workspace.take_all_closing())
             .chain(
                 workspace
                     .panel_ids()