@perspective-dev/viewer 4.5.2 → 5.1.0

package/src/rust/tasks/table_lifecycle.rs

@@ -0,0 +1,158 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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::cell::RefCell;
+use std::rc::Rc;
+
+use perspective_client::utils::PerspectiveResultExt;
+use perspective_client::{Client, clone};
+use perspective_js::utils::{ApiFuture, ApiResult, LocalPollLoop};
+use wasm_bindgen::JsValue;
+
+use super::pipeline::RunOrigin;
+use super::restore_and_render::restore_and_render;
+use crate::config::ViewerConfigUpdate;
+use crate::presentation::Presentation;
+use crate::utils::{AddListener, Subscription};
+use crate::workspace::{Panel, Workspace};
+
+/// The per-client hosted-tables-update subscriptions this element holds, for
+/// removal at `delete()`.
+pub(crate) type HostedTableSubs = Rc<RefCell<Vec<(Client, u32)>>>;
+
+/// Wire reactive table binding for an element: subscribe every registered
+/// [`Client`]'s hosted-tables updates (current and future registrations) to
+/// [`sweep_table_bindings`]. Returns the registration listener (owned for the
+/// element's lifetime) and the accumulated client subscriptions (removed at
+/// element `delete()`).
+pub(crate) fn wire_table_lifecycle(
+    workspace: &Workspace,
+    presentation: &Presentation,
+) -> (Subscription, HostedTableSubs) {
+    let subs: HostedTableSubs = Rc::default();
+    let sub = workspace.client_registered().add_listener({
+        clone!(workspace, presentation, subs);
+        move |client: Client| {
+            clone!(workspace, presentation, subs);
+            ApiFuture::spawn(async move {
+                let poll_loop = LocalPollLoop::new({
+                    clone!(workspace, presentation);
+                    move |()| {
+                        clone!(workspace, presentation);
+                        ApiFuture::spawn(async move {
+                            sweep_table_bindings(&workspace, &presentation).await
+                        });
+
+                        Ok(JsValue::UNDEFINED)
+                    }
+                });
+
+                let id = client
+                    .on_hosted_tables_update(move || {
+                        let poll_loop = poll_loop.clone();
+                        async move {
+                            poll_loop.poll(()).await;
+                        }
+                    })
+                    .await?;
+
+                subs.borrow_mut().push((client, id));
+
+                // A table created between this client's registration and the
+                // subscription above fired no callback — sweep NOW, after
+                // subscribing, so no creation can be missed.
+                sweep_table_bindings(&workspace, &presentation).await
+            })
+        }
+    });
+
+    (sub, subs)
+}
+
+/// One reconciliation pass over every panel's table binding vs. the loaded
+/// clients' hosted sets: releases first (a delete and a re-create in the same
+/// update settle as suspend-then-rebind), then completes pending binds.
+/// Per-panel failures are logged, never aborting the sweep.
+pub(crate) async fn sweep_table_bindings(
+    workspace: &Workspace,
+    presentation: &Presentation,
+) -> ApiResult<()> {
+    for panel in workspace.panels() {
+        if let Some(name) = panel.session.get_table().map(|t| t.get_name().to_owned())
+            && let Some(client) = panel.session.get_client()
+            && let Ok(hosted) = client.get_hosted_table_names().await
+            && !hosted.iter().any(|n| n == &name)
+        {
+            suspend_panel(&panel).await.unwrap_or_log();
+        }
+    }
+
+    for panel in workspace.panels() {
+        if panel.session.pending_table().is_some() {
+            bind_pending(&panel, workspace, presentation)
+                .await
+                .unwrap_or_log();
+        }
+    }
+
+    Ok(())
+}
+
+/// Suspend one panel's binding under its draw lock (see
+/// [`Session::suspend_table`]) and blank its display. The suspend re-derives
+/// the bound name inside the lock — a panel that rebound or ejected since the
+/// sweep's observation suspends its CURRENT state or no-ops.
+async fn suspend_panel(panel: &Panel) -> ApiResult<()> {
+    clone!(panel.session, panel.renderer);
+    renderer
+        .clone()
+        .render_task(|_guard| async move {
+            if let Some(reset) = session.suspend_table() {
+                reset.await?;
+                if let Some(plugin) = renderer.active_plugin() {
+                    plugin.clear().await?;
+                }
+            }
+
+            Ok(())
+        })
+        .await
+}
+
+/// Complete a PENDING panel's bind through the shared restore pipeline: the
+/// committed view config is untouched, the pending name re-derived inside the
+/// locked run (capture-free), the client federated exactly as a `restore`
+/// would. A name still un-hosted (the sweep raced a delete) simply re-pends.
+async fn bind_pending(
+    panel: &Panel,
+    workspace: &Workspace,
+    presentation: &Presentation,
+) -> ApiResult<()> {
+    restore_and_render(
+        &panel.session,
+        &panel.renderer,
+        presentation,
+        RunOrigin::Internal,
+        ViewerConfigUpdate::default(),
+        {
+            clone!(panel.session, workspace);
+            async move {
+                let Some(name) = session.pending_table() else {
+                    return Ok(());
+                };
+
+                super::restore_panel::bind_table_task(&session, &workspace, name).await
+            }
+        },
+    )
+    .await
+}

package/src/rust/tasks/update_theme.rs

@@ -10,31 +10,63 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-//! Theme reset / set task. Replaces the inlined StatusBar callback that
-//! reached into `Session::get_view()` for the post-update restyle.
+//! Theme reset / set task.
 
+use futures::future::join_all;
 use perspective_js::utils::*;
 
 use crate::presentation::Presentation;
 use crate::renderer::Renderer;
-use crate::session::Session;
+use crate::workspace::Workspace;
 
-/// Apply a theme change and restyle the active view.
+/// Re-seed every panel renderer's cached registry default theme from the
+/// (awaited, so initialized) theme registry, returning the default name.
+/// Every consumer of `Renderer::needs_restyle` after a registry-affecting
+/// change must run this first — a cold cache compares against `None`.
+pub(crate) async fn seed_default_themes(
+    presentation: &Presentation,
+    workspace: &Workspace,
+) -> Option<String> {
+    let default = presentation.get_default_theme_name().await;
+    for panel in workspace.panels() {
+        panel.renderer.set_default_theme(default.clone());
+    }
+
+    default
+}
+
+/// Apply a theme change and restyle the affected panel's view.
 ///
 /// `theme = None` resets to the first available theme; `theme = Some(name)`
-/// sets the named theme. In both cases the post-update path is the same:
-/// fetch the current view from the session and ask the renderer to
-/// re-style it. Components dispatch this task instead of reading
+/// sets the named theme. The `theme` is recorded on the active `renderer`
+/// (per-panel state) and mirrored onto the host `theme` attribute (driving
+/// the shared chrome). Components dispatch this task instead of reading
 /// `Session::get_view()` themselves.
+///
+/// Every panel's plugin carries its own stamped `theme` attribute (effective
+/// theme = its own, else the registry default — see `Renderer::stamp_theme`),
+/// and the theme rules provide a COMPLETE var set for `perspective-viewer
+/// [theme="X"]` descendants (no inheritance from the host attribute), so a
+/// pick changes ONLY the picked panel's effective theme — the host flip
+/// restyles nothing else. Restyle (an expensive full `restyle_all`, which
+/// also redraws) is therefore scoped to panels whose captured CSS is
+/// actually STALE (`Renderer::needs_restyle` — effective theme vs. the one
+/// stamped at the plugin's last capture): the picked panel when the value
+/// is genuinely new, and never a panel that has yet to first-paint.
 pub fn update_theme(
-    session: &Session,
     renderer: &Renderer,
     presentation: &Presentation,
+    workspace: &Workspace,
     theme: Option<String>,
 ) {
-    let session = session.clone();
-    let renderer = renderer.clone();
+    // Per-panel: record the theme on the (active) renderer so this panel keeps
+    // it independent of which panel is active. `set_theme_name` below mirrors
+    // the same value onto the host `theme` attribute (driving the chrome), and
+    // MainPanel inlines this renderer's theme on its frame only when it
+    renderer.set_theme_stamped(theme.clone());
+
     let presentation = presentation.clone();
+    let workspace = workspace.clone();
     ApiFuture::spawn(async move {
         match theme {
             Some(name) => {
@@ -45,7 +77,19 @@ pub fn update_theme(
             },
         }
 
-        let view = session.get_view().into_apierror()?;
-        renderer.restyle_all(&view).await
+        seed_default_themes(&presentation, &workspace).await;
+        let panels = workspace.panels();
+        join_all(panels.iter().map(|panel| async move {
+            if panel.renderer.needs_restyle() {
+                panel.renderer.restyle_all().await?;
+            }
+
+            ApiResult::<()>::Ok(())
+        }))
+        .await
+        .into_iter()
+        .collect::<ApiResult<Vec<_>>>()?;
+
+        Ok(())
     });
 }

package/src/rust/utils/browser/dragdrop.rs

@@ -17,6 +17,18 @@ pub enum DragTarget {
     SplitBy,
     Sort,
     Filter,
+    WindowSource,
+    WindowOrderBy,
+    WindowPartitionBy,
+}
+
+impl DragTarget {
+    pub fn is_staged(&self) -> bool {
+        matches!(
+            self,
+            Self::WindowSource | Self::WindowOrderBy | Self::WindowPartitionBy
+        )
+    }
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]

package/src/rust/utils/browser/tests/debounce.rs

@@ -86,6 +86,55 @@ pub async fn test_lock_seq() {
     assert_eq!(cell.get(), 10);
 }
 
+/// A dedicated [`DebounceSlot`]'s task must RUN even when the default slot
+/// has a parked runner — coalescing is scoped per slot. Pre-slot (one
+/// shared parked flag), `t4` would resolve via `t2`'s settle without its
+/// closure ever running: the resize-eaten-by-parked-update bug.
+#[wasm_bindgen_test]
+pub async fn test_slot_isolated_from_default_coalescing() {
+    let debounce_mutex = DebounceMutex::default();
+    let slot = debounce_mutex.slot();
+    let defaults: Rc<Cell<u32>> = Rc::new(Cell::new(0));
+    let slots: Rc<Cell<u32>> = Rc::new(Cell::new(0));
+
+    let t1 = debounce_mutex.lock(async {
+        set_timeout(10).await.unwrap();
+    });
+
+    let t2 = {
+        let defaults = defaults.clone();
+        debounce_mutex.debounce(async move {
+            defaults.set(defaults.get() + 1);
+            Ok(())
+        })
+    };
+
+    let t3 = {
+        let defaults = defaults.clone();
+        debounce_mutex.debounce(async move {
+            defaults.set(defaults.get() + 100);
+            Ok(())
+        })
+    };
+
+    let t4 = {
+        let slots = slots.clone();
+        slot.debounce_with(|_| async move {
+            slots.set(slots.get() + 1);
+            Ok(())
+        })
+    };
+
+    let (_, r2, r3, r4) = futures::join!(t1, t2, t3, t4);
+    r2.unwrap();
+    r3.unwrap();
+    r4.unwrap();
+
+    // `t3` coalesced onto the parked `t2`; `t4` ran its own closure.
+    assert_eq!(defaults.get(), 1);
+    assert_eq!(slots.get(), 1);
+}
+
 #[wasm_bindgen_test]
 pub async fn test_debounce_seq() {
     let debounce_mutex = DebounceMutex::default();

package/src/rust/utils/completion.rs

@@ -0,0 +1,56 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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::future::Future;
+
+use futures::channel::oneshot;
+use perspective_js::utils::*;
+
+/// A completion handle for message-based public API methods (invariant I6 —
+/// see `SESSION_CONFIG_COHERENCE_PLAN.md`): its ONLY resolution API is
+/// [`Completion::resolve_after`], which takes a run future — so resolving a
+/// public method's promise at message-handling time (before the renders it
+/// caused have drawn) is unwritable, not merely discouraged. Dropping an
+/// unresolved `Completion` rejects the caller as cancelled.
+pub struct Completion(Option<oneshot::Sender<ApiResult<()>>>);
+
+impl Completion {
+    #[allow(clippy::new_ret_no_self)]
+    pub fn new() -> (Self, oneshot::Receiver<ApiResult<()>>) {
+        let (sender, receiver) = oneshot::channel();
+        (Self(Some(sender)), receiver)
+    }
+
+    /// Resolve this completion with `run`'s result when it settles. The
+    /// caller relinquishes the handle — one run, one resolution.
+    pub fn resolve_after(mut self, run: impl Future<Output = ApiResult<()>> + 'static) {
+        let sender = self.0.take().unwrap();
+        ApiFuture::spawn(async move {
+            let _ = sender.send(run.await);
+            Ok(())
+        });
+    }
+}
+
+impl std::fmt::Debug for Completion {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Completion").finish()
+    }
+}
+
+impl Drop for Completion {
+    fn drop(&mut self) {
+        if let Some(sender) = self.0.take() {
+            let _ = sender.send(Err(ApiError::new("Cancelled")));
+        }
+    }
+}

package/src/rust/utils/custom_element.rs

@@ -16,6 +16,11 @@ use wasm_bindgen::prelude::*;
 
 #[wasm_bindgen(inline_js = r#"
     export function bootstrap(psp, name, clsname, statics) {
+        if (customElements.get(name)) {
+            console.warn(`Custom element "${name}" is already registered; skipping duplicate registration (Perspective was loaded more than once on this page).`);
+            return;
+        }
+
         const cls = psp[clsname];
         const proto = cls.prototype;
         class x extends HTMLElement {

package/src/rust/utils/debounce.rs

@@ -17,44 +17,216 @@ use std::rc::Rc;
 use async_lock::Mutex;
 use perspective_js::utils::ApiResult;
 
+use super::pubsub::PubSub;
+
+/// Proof that the bearer is executing inside a [`DebounceMutex`]-locked task.
+///
+/// Every plugin-dispatching function (`draw_view`, `activate_plugin`, the
+/// restyle/resize/export wrappers) and the snapshot pipeline
+/// (`bind_snapshot`) require `&RenderGuard`, so an unlocked plugin call or
+/// out-of-pipeline render is a missing witness — a compile error, not a
+/// review rule. Constructed ONLY by [`DebounceMutex::lock_with`] /
+/// [`DebounceMutex::debounce_with`], after the lock is acquired; it is not
+/// `Clone`, so it cannot be stashed for use outside the task that received
+/// it.
+pub struct RenderGuard {
+    _private: (),
+}
+
+/// The per-slot debounce bookkeeping: one running + one parked evaluation,
+/// with coalesced callers awaiting the parked runner's settle. Kept
+/// per-[`DebounceSlot`] so coalescing is only expressible WITHIN a kind —
+/// a caller can never be absorbed by a parked runner of a different kind
+/// whose work does not subsume it (the resize-eaten-by-parked-update bug).
 #[derive(Default)]
-struct DebounceMutexData {
+struct SlotState {
     id: Cell<u64>,
-    mutex: Mutex<u64>,
+    last: Cell<u64>,
+    parked: Cell<bool>,
+    settled_id: Cell<u64>,
+    on_settle: PubSub<()>,
+}
+
+#[derive(Default)]
+struct DebounceMutexData {
+    held: Cell<bool>,
+    mutex: Mutex<()>,
+    default_slot: Rc<SlotState>,
+}
+
+/// Clears the `held` flag on drop, so cancellation of a locked task (its
+/// future dropped mid-await) can't leave [`DebounceMutex::is_held`] stuck
+/// `true`.
+struct HeldFlag<'a>(&'a Cell<bool>);
+
+impl<'a> HeldFlag<'a> {
+    fn set(cell: &'a Cell<bool>) -> Self {
+        cell.set(true);
+        Self(cell)
+    }
+}
+
+impl Drop for HeldFlag<'_> {
+    fn drop(&mut self) {
+        self.0.set(false);
+    }
+}
+
+/// RAII for the parked debounce runner: clears `parked` and broadcasts the
+/// runner's settle on drop. Running through `Drop` (not a happy-path call)
+/// makes the release unconditional — a runner cancelled mid-park or
+/// mid-run still frees the parked slot and releases its coalesced waiters,
+/// so they can never be stranded awaiting a settle that no task will emit.
+struct SettleGuard<'a> {
+    state: &'a SlotState,
+    next: u64,
+}
+
+impl<'a> SettleGuard<'a> {
+    fn park(state: &'a SlotState, next: u64) -> Self {
+        state.parked.set(true);
+        Self { state, next }
+    }
+}
+
+impl Drop for SettleGuard<'_> {
+    fn drop(&mut self) {
+        self.state.parked.set(false);
+        if self.state.settled_id.get() < self.next {
+            self.state.settled_id.set(self.next);
+        }
+
+        self.state.on_settle.emit(());
+    }
 }
 
 /// An async `Mutex` type specialized for Perspective's rendering, which
-/// debounces calls in addition to providing exclusivity. Calling `debounce`
-/// with a _cancellable_ [`Future`] will resolve only after at least one
-/// _complete_ evaluation of a call awaiting the lock.
+/// debounces calls in addition to providing exclusivity. Calling
+/// [`Self::debounce`] resolves only after at least one complete evaluation
+/// of a call that began no earlier than this one — either by running the
+/// caller's own future, or by coalescing onto the single parked trailing
+/// runner. At most TWO debounce evaluations are ever outstanding (one
+/// running, one parked); every additional concurrent caller resolves
+/// without queueing on the lock.
 #[derive(Clone, Default)]
 pub struct DebounceMutex(Rc<DebounceMutexData>);
 
 impl DebounceMutex {
+    /// `true` while a locked task is executing. Used by lock-acquiring
+    /// public API methods to emit a debug-build warning when they are about
+    /// to queue behind an in-flight run — legitimate for app callers, a
+    /// guaranteed deadlock when reached synchronously from a plugin's render
+    /// (the render-callable contract on `js::plugin` forbids it).
+    pub fn is_held(&self) -> bool {
+        self.0.held.get()
+    }
+
     /// Lock like a normal `Mutex`.
     pub async fn lock<T>(&self, f: impl Future<Output = T>) -> T {
-        let mut last = self.0.mutex.lock().await;
-        let next = self.0.id.get();
-        let result = f.await;
-        *last = next;
+        self.lock_with(|_| f).await
+    }
+
+    /// Lock, passing a [`RenderGuard`] witness into the task builder. The
+    /// task future is CONSTRUCTED after the lock is acquired — a guard can
+    /// never exist outside a locked section.
+    pub async fn lock_with<T, F, Fut>(&self, f: F) -> T
+    where
+        F: FnOnce(RenderGuard) -> Fut,
+        Fut: Future<Output = T>,
+    {
+        let guard = self.0.mutex.lock().await;
+        let held = HeldFlag::set(&self.0.held);
+        let result = f(RenderGuard { _private: () }).await;
+        drop(held);
+        drop(guard);
         result
     }
 
     /// Lock and also debounce `f`, which should be cancellable.
     pub async fn debounce(&self, f: impl Future<Output = ApiResult<()>>) -> ApiResult<()> {
-        let next = self.0.id.get() + 1;
-        let mut last = self.0.mutex.lock().await;
-        if *last < next {
-            let next = self.0.id.get() + 1;
-            self.0.id.set(next);
-            let result = f.await;
+        self.debounce_with(|_| f).await
+    }
+
+    /// [`Self::debounce`] with a [`RenderGuard`] witness (see
+    pub async fn debounce_with<T, F, Fut>(&self, f: F) -> ApiResult<T>
+    where
+        T: Default,
+        F: FnOnce(RenderGuard) -> Fut,
+        Fut: Future<Output = ApiResult<T>>,
+    {
+        DebounceSlot {
+            mutex: self.clone(),
+            state: self.0.default_slot.clone(),
+        }
+        .debounce_with(f)
+        .await
+    }
+
+    /// A NEW debounce slot over this mutex: its tasks serialize against
+    /// every other locked task, but coalesce only among themselves.
+    pub fn slot(&self) -> DebounceSlot {
+        DebounceSlot {
+            mutex: self.clone(),
+            state: Default::default(),
+        }
+    }
+}
+
+/// One debounce KIND over a shared [`DebounceMutex`]. Execution is
+/// exclusive across the whole mutex; coalescing (a caller resolving via a
+/// parked runner instead of queueing) is scoped to the slot. A coalesced
+/// caller's work must be subsumable by any same-slot runner that runs no
+/// earlier than the call — which is why parameterized tasks sharing a slot
+/// must read their parameters at RUN time (e.g. the [`Renderer`] geometry
+/// command cell), never capture them at call time.
+#[derive(Clone)]
+pub struct DebounceSlot {
+    mutex: DebounceMutex,
+    state: Rc<SlotState>,
+}
+
+impl DebounceSlot {
+    pub async fn debounce_with<T, F, Fut>(&self, f: F) -> ApiResult<T>
+    where
+        T: Default,
+        F: FnOnce(RenderGuard) -> Fut,
+        Fut: Future<Output = ApiResult<T>>,
+    {
+        let state = &self.state;
+        let next = state.id.get() + 1;
+        if state.parked.get() {
+            self.await_settled(next).await;
+            return Ok(T::default());
+        }
+
+        let settle = SettleGuard::park(state, next);
+        let guard = self.mutex.0.mutex.lock().await;
+        state.parked.set(false);
+        let result = if state.last.get() < next {
+            let next = state.id.get() + 1;
+            state.id.set(next);
+            let held = HeldFlag::set(&self.mutex.0.held);
+            let result = f(RenderGuard { _private: () }).await;
+            drop(held);
             if result.is_ok() {
-                *last = next;
+                state.last.set(next);
             }
 
             result
         } else {
-            Ok(())
+            Ok(T::default())
+        };
+
+        drop(guard);
+        drop(settle);
+        result
+    }
+
+    async fn await_settled(&self, next: u64) {
+        while self.state.settled_id.get() < next {
+            if self.state.on_settle.read_next().await.is_err() {
+                break;
+            }
         }
     }
 }

package/src/rust/utils/mod.rs

@@ -17,27 +17,33 @@
 //! reference other `crate::utils` modules when it helps reduce boiler-plate.
 
 mod browser;
+mod completion;
 mod custom_element;
 mod datetime;
 mod debounce;
 mod hooks;
 mod modal_position;
 mod number_format;
+mod pending_effects;
 mod ptr_eq_rc;
 mod pubsub;
+mod spawn;
 mod weak_scope;
 
 #[cfg(test)]
 mod tests;
 
 pub use browser::*;
+pub use completion::*;
 pub use custom_element::*;
 pub use datetime::*;
 pub use debounce::*;
 pub use hooks::*;
 pub use modal_position::*;
 pub use number_format::*;
+pub use pending_effects::*;
 pub use perspective_client::clone;
 pub use ptr_eq_rc::*;
 pub use pubsub::*;
+pub use spawn::*;
 pub use weak_scope::*;