@perspective-dev/viewer 4.5.1 → 5.0.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/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,167 @@ 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: (),
+}
+
 #[derive(Default)]
 struct DebounceMutexData {
     id: Cell<u64>,
+    held: Cell<bool>,
     mutex: Mutex<u64>,
+    parked: Cell<bool>,
+    settled_id: Cell<u64>,
+    on_settle: PubSub<()>,
+}
+
+/// 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> {
+    data: &'a DebounceMutexData,
+    next: u64,
+}
+
+impl<'a> SettleGuard<'a> {
+    fn park(data: &'a DebounceMutexData, next: u64) -> Self {
+        data.parked.set(true);
+        Self { data, next }
+    }
+}
+
+impl Drop for SettleGuard<'_> {
+    fn drop(&mut self) {
+        self.data.parked.set(false);
+        if self.data.settled_id.get() < self.next {
+            self.data.settled_id.set(self.next);
+        }
+
+        self.data.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 {
+        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 mut last = self.0.mutex.lock().await;
         let next = self.0.id.get();
-        let result = f.await;
+        let held = HeldFlag::set(&self.0.held);
+        let result = f(RenderGuard { _private: () }).await;
+        drop(held);
         *last = next;
         result
     }
 
     /// Lock and also debounce `f`, which should be cancellable.
     pub async fn debounce(&self, f: impl Future<Output = ApiResult<()>>) -> ApiResult<()> {
+        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>>,
+    {
         let next = self.0.id.get() + 1;
+        if self.0.parked.get() {
+            self.await_settled(next).await;
+            return Ok(T::default());
+        }
+
+        let settle = SettleGuard::park(&self.0, next);
         let mut last = self.0.mutex.lock().await;
-        if *last < next {
+        self.0.parked.set(false);
+        let result = if *last < next {
             let next = self.0.id.get() + 1;
             self.0.id.set(next);
-            let result = f.await;
+            let held = HeldFlag::set(&self.0.held);
+            let result = f(RenderGuard { _private: () }).await;
+            drop(held);
             if result.is_ok() {
                 *last = next;
             }
 
             result
         } else {
-            Ok(())
+            Ok(T::default())
+        };
+
+        drop(last);
+        drop(settle);
+        result
+    }
+
+    async fn await_settled(&self, next: u64) {
+        while self.0.settled_id.get() < next {
+            if self.0.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::*;

package/src/rust/utils/pending_effects.rs

@@ -0,0 +1,62 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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::Cell;
+use std::rc::Rc;
+
+use super::pubsub::PubSub;
+
+/// The element-scoped ledger of in-flight EFFECTS: every effectful public
+/// method (and the internal flows they schedule, e.g. the `before-resize`
+/// presize) registers an [`EffectGuard`] for the duration of its async
+/// work, whether or not the caller awaited it. `flush()` resolves only
+/// after the ledger drains, so "called before `flush`" implies "applied
+/// before `flush` resolves".
+#[derive(Clone, Default)]
+pub struct EffectLedger(Rc<EffectLedgerData>);
+
+#[derive(Default)]
+struct EffectLedgerData {
+    count: Cell<u32>,
+    on_drain: PubSub<()>,
+}
+
+pub struct EffectGuard(EffectLedger);
+
+impl EffectLedger {
+    pub fn guard(&self) -> EffectGuard {
+        self.0.count.set(self.0.count.get() + 1);
+        EffectGuard(self.clone())
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.0.count.get() == 0
+    }
+
+    pub async fn settle(&self) {
+        while self.0.count.get() > 0 {
+            if self.0.on_drain.read_next().await.is_err() {
+                break;
+            }
+        }
+    }
+}
+
+impl Drop for EffectGuard {
+    fn drop(&mut self) {
+        let data = &self.0.0;
+        data.count.set(data.count.get() - 1);
+        if data.count.get() == 0 {
+            data.on_drain.emit(());
+        }
+    }
+}

package/src/rust/{components/style/local_style.rs → utils/spawn.rs}

@@ -10,26 +10,24 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-use yew::prelude::*;
+use std::future::Future;
 
-use super::style_cache::*;
+use perspective_js::utils::*;
 
-#[derive(Properties)]
-pub struct LocalStyleProps {
-    pub href: (&'static str, &'static str),
-}
-
-impl PartialEq for LocalStyleProps {
-    fn eq(&self, _other: &Self) -> bool {
-        true
-    }
-}
-
-#[function_component(LocalStyle)]
-pub fn local_style(props: &LocalStyleProps) -> Html {
-    if let Some(cache) = use_context::<StyleCache>() {
-        cache.add_style(props.href.0, props.href.1);
-    }
+/// Spawn a fire-and-forget task whose ERRORS ARE OWNED: a failure lands in a
+/// `tracing::error` tagged with `tag` instead of a dangling `Promise`
+/// rejection (which `ApiFuture::spawn` produces, invisibly to callers and
+/// tests). "View already deleted" cancellations are not failures.
+///
+/// Prefer RETURNING the future so the caller owns completion and error
+/// (invariant I6); use this only at event-listener leaves where no caller
+/// exists.
+pub fn spawn_owned(tag: &'static str, fut: impl Future<Output = ApiResult<()>> + 'static) {
+    ApiFuture::spawn(async move {
+        if let Err(e) = fut.await.ignore_view_delete() {
+            tracing::error!("[{}] unhandled task error: {}", tag, e);
+        }
 
-    html! {}
+        Ok(())
+    });
 }

package/src/rust/utils/weak_scope.rs

@@ -37,13 +37,3 @@ impl<C: Component> PartialEq for WeakScope<C> {
         Rc::ptr_eq(&self.0, &other.0)
     }
 }
-
-// #[extend::ext]
-// pub impl<T: Component> Context<T> {
-//     fn context<U: Clone + PartialEq + 'static>(&self) -> U {
-//         self.link()
-//             .context::<U>(Callback::from(|_| {}))
-//             .map(|(c, _)| c)
-//             .unwrap()
-//     }
-// }