feat(core): add wakeup callback for external event loop integration

packages/core/src/runtime.rs

@@ -18,6 +18,7 @@ use slab::Slab;
 use slotmap::DefaultKey;
 use std::any::Any;
 use std::collections::BTreeSet;
+use std::sync::Arc;
 use std::{
     cell::{Cell, Ref, RefCell},
     rc::Rc,
@@ -54,6 +55,12 @@ pub struct Runtime {
 
     pub(crate) sender: futures_channel::mpsc::UnboundedSender<SchedulerMsg>,
 
+    /// Optional callback invoked when async tasks wake up or scopes are marked
+    /// dirty. Allows external event loops (winit, etc.) to schedule a repaint
+    /// without polling. The callback must be `Send + Sync` since task wakers
+    /// may fire from any thread.
+    pub(crate) wakeup_callback: RefCell<Option<Arc<dyn Fn() + Send + Sync>>>,
+
     // The effects that need to be run after the next render
     pub(crate) pending_effects: RefCell<BTreeSet<Effect>>,
 
@@ -87,6 +94,7 @@ impl Runtime {
             suspended_tasks: Default::default(),
             pending_effects: Default::default(),
             dirty_tasks: Default::default(),
+            wakeup_callback: RefCell::new(None),
             elements: RefCell::new(elements),
             mounts: Default::default(),
         })

packages/core/src/tasks.rs

@@ -187,6 +187,7 @@ impl Runtime {
                     waker: futures_util::task::waker(Arc::new(LocalTaskHandle {
                         id: task_id.id,
                         tx: self.sender.clone(),
+                        wakeup: self.wakeup_callback.borrow().clone(),
                     })),
                     ty: RefCell::new(ty),
                 });
@@ -394,12 +395,16 @@ pub(crate) enum SchedulerMsg {
 struct LocalTaskHandle {
     id: slotmap::DefaultKey,
     tx: futures_channel::mpsc::UnboundedSender<SchedulerMsg>,
+    wakeup: Option<Arc<dyn Fn() + Send + Sync>>,
 }
 
 impl ArcWake for LocalTaskHandle {
     fn wake_by_ref(arc_self: &Arc<Self>) {
         _ = arc_self
             .tx
             .unbounded_send(SchedulerMsg::TaskNotified(arc_self.id));
+        if let Some(cb) = &arc_self.wakeup {
+            cb();
+        }
     }
 }

packages/core/src/virtual_dom.rs

@@ -16,6 +16,7 @@ use crate::{Task, VComponent};
 use futures_util::StreamExt;
 use slab::Slab;
 use std::collections::BTreeSet;
+use std::sync::Arc;
 use std::{any::Any, rc::Rc};
 use tracing::instrument;
 
@@ -760,6 +761,28 @@ impl VirtualDom {
         self.runtime.clone()
     }
 
+    /// Set a callback that is invoked whenever the VirtualDom has new async work
+    /// ready to be processed — for example, when a spawned future resolves or a
+    /// signal is written from outside the render cycle.
+    ///
+    /// This lets external event loops (winit, GTK, etc.) schedule a
+    /// [`render_immediate`](Self::render_immediate) call without polling. The
+    /// callback must be `Send + Sync` because Rust's async waker mechanism
+    /// requires it — task wakers may fire from any thread.
+    ///
+    /// # Example
+    ///
+    /// ```rust,ignore
+    /// // In a winit-based shell:
+    /// let proxy = event_loop.create_proxy();
+    /// dom.set_wakeup_callback(move || {
+    ///     let _ = proxy.send_event(UserEvent::NewWork);
+    /// });
+    /// ```
+    pub fn set_wakeup_callback(&self, callback: impl Fn() + Send + Sync + 'static) {
+        *self.runtime.wakeup_callback.borrow_mut() = Some(Arc::new(callback));
+    }
+
     /// Handle an event with the Virtual Dom. This method is deprecated in favor of [VirtualDom::runtime().handle_event] and will be removed in a future release.
     #[deprecated = "Use [VirtualDom::runtime().handle_event] instead"]
     pub fn handle_event(&self, name: &str, event: Rc<dyn Any>, element: ElementId, bubbling: bool) {

packages/core/tests/wakeup_callback.rs

@@ -0,0 +1,59 @@
+//! Verify that the wakeup callback fires when async tasks complete.
+
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use dioxus::prelude::*;
+
+#[tokio::test]
+async fn wakeup_callback_fires_on_task_completion() {
+
+    fn app() -> Element {
+        use_hook(|| {
+            spawn(async {
+                tokio::time::sleep(Duration::from_millis(10)).await;
+            });
+        });
+        rsx! {}
+    }
+
+    let mut dom = VirtualDom::new(app);
+
+    let count = Arc::new(AtomicUsize::new(0));
+    let count_clone = count.clone();
+    dom.set_wakeup_callback(move || {
+        count_clone.fetch_add(1, Ordering::Relaxed);
+    });
+
+    dom.rebuild(&mut dioxus_core::NoOpMutations);
+
+    tokio::select! {
+        _ = dom.wait_for_work() => {}
+        _ = tokio::time::sleep(Duration::from_millis(200)) => {}
+    };
+
+    // The callback should have fired at least once when the spawned task woke up.
+    assert!(count.load(Ordering::Relaxed) > 0, "wakeup callback should have been called");
+}
+
+#[tokio::test]
+async fn wakeup_callback_not_called_without_async_work() {
+    fn app() -> Element {
+        rsx! {}
+    }
+
+    let mut dom = VirtualDom::new(app);
+
+    let count = Arc::new(AtomicUsize::new(0));
+    let count_clone = count.clone();
+    dom.set_wakeup_callback(move || {
+        count_clone.fetch_add(1, Ordering::Relaxed);
+    });
+
+    dom.rebuild(&mut dioxus_core::NoOpMutations);
+
+    // No async work spawned — callback should not fire.
+    tokio::time::sleep(Duration::from_millis(50)).await;
+    assert_eq!(count.load(Ordering::Relaxed), 0, "wakeup callback should not fire without async work");
+}