Implement Dispatchers.Main for Tao via MainDispatcherFactory SPI

Register TaoMainCoroutineDispatcher with loadPriority=100 to make Tao the
canonical Dispatchers.Main when nucleus.decorated-window-tao is on the
classpath. This routes all coroutine dispatches (including AndroidX Lifecycle,
Compose, animations, Ktor timeouts) onto the Tao main thread.

- Implement TaoMainCoroutineDispatcher extending MainCoroutineDispatcher + Delay
- Register TaoMainDispatcherFactory with kotlinx-coroutines service loader
- Eagerly capture Tao main thread in TaoApplication.run before native event
  loop starts, so MainDispatcherChecker resolves immediately
- Add isDispatchNeeded check against captured thread to prevent EDT/main
  thread aliasing (strict single-thread semantics)
- Include ProGuard keep rules and GraalVM reachability metadata

Author: kdroidFilter

decorated-window-tao/src/main/kotlin/dev/nucleusframework/window/tao/TaoApplication.kt

@@ -34,6 +34,13 @@ object TaoApplication {
             "nucleus_tao native library is not available — supported targets: " +
                 "macOS (arm64/x86_64), Windows (x64/aarch64), Linux (x64/aarch64)."
         }
+        // Capture the Tao main thread eagerly, before the native event loop
+        // takes over this thread. Required so `Dispatchers.Main` consumers
+        // (notably AndroidX Lifecycle's synchronous `MainDispatcherChecker`)
+        // can resolve the Tao thread immediately — a lazy capture at first
+        // pump would race the very first `NavHost.setGraph` → `addObserver`
+        // call on real apps.
+        TaoMainDispatcher.taoMainThread = Thread.currentThread()
         onLaunched = block
         NativeTaoBridge.nativeRunBlocking(EventDispatcher)
     }

decorated-window-tao/src/main/kotlin/dev/nucleusframework/window/tao/TaoMainCoroutineDispatcher.kt

@@ -0,0 +1,111 @@
+package dev.nucleusframework.window.tao
+
+import kotlinx.coroutines.CancellableContinuation
+import kotlinx.coroutines.Delay
+import kotlinx.coroutines.DisposableHandle
+import kotlinx.coroutines.InternalCoroutinesApi
+import kotlinx.coroutines.MainCoroutineDispatcher
+import kotlinx.coroutines.Runnable
+import java.util.concurrent.Executors
+import java.util.concurrent.ScheduledExecutorService
+import java.util.concurrent.TimeUnit
+import kotlin.coroutines.CoroutineContext
+
+/**
+ * `Dispatchers.Main` implementation for the Tao backend.
+ *
+ * Routes coroutine dispatches onto the Tao main thread via [TaoMainDispatcher],
+ * which is drained on every `MAIN_EVENTS_CLEARED` native event tick. The
+ * "main thread" predicate is intentionally strict: only the captured Tao main
+ * thread is considered already-on-Main. The AWT EDT is **not** treated as a
+ * Main alias — under the Tao backend the EDT may not be running at all, and
+ * conflating the two leads to silent state splits and false negatives in
+ * AndroidX Lifecycle's thread checker.
+ *
+ * Implements [Delay] (via a daemon [ScheduledExecutorService] that re-posts
+ * resume callbacks through [dispatch]) so that `DefaultDelay` routes all
+ * process-wide `delay()` calls back onto the Tao main thread instead of
+ * silently parking them when the Tao runtime is the resolved
+ * `Dispatchers.Main`. Without this, `Dispatchers.Main as Delay` would crash or
+ * stall every `delay`/`withTimeout` in the process — including Compose
+ * runtime, RepeatOnLifecycle, animation timers, and Ktor request timeouts.
+ *
+ * Discovered through [TaoMainDispatcherFactory] (`loadPriority = 100`) via the
+ * standard `META-INF/services/kotlinx.coroutines.internal.MainDispatcherFactory`
+ * service loader, mirroring `kotlinx-coroutines-swing`.
+ */
+@OptIn(InternalCoroutinesApi::class)
+internal sealed class TaoMainCoroutineDispatcher : MainCoroutineDispatcher(), Delay {
+    override fun dispatch(
+        context: CoroutineContext,
+        block: Runnable,
+    ) {
+        TaoMainDispatcher.dispatch(context, block)
+    }
+
+    override fun isDispatchNeeded(context: CoroutineContext): Boolean {
+        val taoMain = TaoMainDispatcher.taoMainThread
+        return taoMain == null || Thread.currentThread() !== taoMain
+    }
+
+    override fun scheduleResumeAfterDelay(
+        timeMillis: Long,
+        continuation: CancellableContinuation<Unit>,
+    ) {
+        val future =
+            DelayScheduler.schedule(
+                {
+                    // Resume on the Tao main thread, undispatched, so the
+                    // resumed continuation runs synchronously in the next
+                    // pump tick rather than re-entering the dispatcher.
+                    dispatch(
+                        continuation.context,
+                        Runnable { with(continuation) { resumeUndispatched(Unit) } },
+                    )
+                },
+                timeMillis,
+                TimeUnit.MILLISECONDS,
+            )
+        continuation.invokeOnCancellation { future.cancel(false) }
+    }
+
+    override fun invokeOnTimeout(
+        timeMillis: Long,
+        block: Runnable,
+        context: CoroutineContext,
+    ): DisposableHandle {
+        val future =
+            DelayScheduler.schedule(
+                { dispatch(context, block) },
+                timeMillis,
+                TimeUnit.MILLISECONDS,
+            )
+        return DisposableHandle { future.cancel(false) }
+    }
+
+    override fun toString(): String = "Dispatchers.Main[Tao]"
+}
+
+internal object ImmediateTaoMainDispatcher : TaoMainCoroutineDispatcher() {
+    override val immediate: MainCoroutineDispatcher get() = this
+}
+
+/**
+ * Shared scheduler for [Delay] callbacks. Single daemon thread — Tao's own
+ * native timer source isn't exposed at the JVM level, so we rely on a small
+ * background scheduler that re-posts the timer firing back into the Tao main
+ * thread via [TaoMainCoroutineDispatcher.dispatch]. The scheduler thread
+ * itself only schedules — it never runs user code.
+ */
+private object DelayScheduler {
+    private val executor: ScheduledExecutorService =
+        Executors.newSingleThreadScheduledExecutor { r ->
+            Thread(r, "Nucleus-Tao-Delay").apply { isDaemon = true }
+        }
+
+    fun schedule(
+        command: Runnable,
+        delay: Long,
+        unit: TimeUnit,
+    ) = executor.schedule(command, delay, unit)
+}

decorated-window-tao/src/main/kotlin/dev/nucleusframework/window/tao/TaoMainDispatcher.kt

@@ -22,6 +22,20 @@ import kotlin.coroutines.CoroutineContext
 internal object TaoMainDispatcher : CoroutineDispatcher() {
     private val pending = ConcurrentLinkedQueue<Runnable>()
 
+    /**
+     * Thread reference for the Tao main thread. Captured eagerly from
+     * [TaoApplication.run] before [NativeTaoBridge.nativeRunBlocking] takes the
+     * thread over, so it is non-null as soon as user composition runs.
+     *
+     * Consumed by [TaoMainCoroutineDispatcher.isDispatchNeeded] and by
+     * downstream `Dispatchers.Main` resolvers (most notably AndroidX
+     * Lifecycle's `MainDispatcherChecker`) to recognise the Tao main thread as
+     * the canonical UI thread.
+     */
+    @Volatile
+    @JvmField
+    internal var taoMainThread: Thread? = null
+
     /**
      * Coalesces native wake calls within a single pump cycle. Set on the
      * first dispatch after pump opened the gate, cleared in [pump] right

decorated-window-tao/src/main/kotlin/dev/nucleusframework/window/tao/TaoMainDispatcherFactory.kt

@@ -0,0 +1,45 @@
+package dev.nucleusframework.window.tao
+
+import kotlinx.coroutines.InternalCoroutinesApi
+import kotlinx.coroutines.MainCoroutineDispatcher
+import kotlinx.coroutines.internal.MainDispatcherFactory
+
+/**
+ * `MainDispatcherFactory` that routes `Dispatchers.Main` to the Tao main
+ * thread when `nucleus.decorated-window-tao` is on the classpath.
+ *
+ * Discovered through the standard
+ * `META-INF/services/kotlinx.coroutines.internal.MainDispatcherFactory`
+ * service file. With [loadPriority] = `100`, it deterministically wins the
+ * ServiceLoader pick against:
+ *
+ * - `kotlinx-coroutines-swing` (`SwingDispatcherFactory.loadPriority = 0`)
+ * - `kotlinx-coroutines-javafx` (`JavaFxDispatcherFactory.loadPriority = 1`)
+ *
+ * `Int.MAX_VALUE` is reserved for `AndroidDispatcherFactory` and
+ * `Int.MAX_VALUE - 1` for `TestMainDispatcherFactory`. `100` sits well clear
+ * of both while staying ahead of any reasonable third-party factory.
+ *
+ * [createDispatcher] is intentionally cheap and side-effect-free: it only
+ * returns the [ImmediateTaoMainDispatcher] singleton, with no JNI / native
+ * interaction. The Tao runtime is initialised separately by
+ * `nucleusApplication { … }`, which captures the main thread reference
+ * eagerly via [TaoMainDispatcher.taoMainThread]. This shape is required by
+ * `kotlinx-coroutines-test`'s [TestMainDispatcherFactory], which wraps the
+ * resolved dispatcher as the delegate of `TestMainDispatcher`; if the factory
+ * touched native code here, every test JVM would fail to initialise
+ * `Dispatchers.Main`.
+ */
+@OptIn(InternalCoroutinesApi::class)
+internal class TaoMainDispatcherFactory : MainDispatcherFactory {
+    override val loadPriority: Int = 100
+
+    override fun createDispatcher(allFactories: List<MainDispatcherFactory>): MainCoroutineDispatcher =
+        ImmediateTaoMainDispatcher
+
+    override fun hintOnError(): String =
+        "Tao backend's Dispatchers.Main is not initialised. Either call " +
+            "nucleusApplication(args) { … } from your main() before touching " +
+            "Dispatchers.Main, or use Dispatchers.setMain(StandardTestDispatcher()) " +
+            "from kotlinx-coroutines-test in unit tests."
+}

decorated-window-tao/src/main/resources/META-INF/proguard/nucleus-decorated-window-tao.pro

@@ -0,0 +1,15 @@
+# Keep the MainDispatcherFactory implementation — ServiceLoader discovers it
+# reflectively from META-INF/services and Compose Desktop's ProGuard pass
+# would otherwise strip it as unreferenced, dropping `Dispatchers.Main` back
+# to kotlinx-coroutines-swing and breaking AndroidX Lifecycle / Navigation
+# under the Tao backend.
+-keep class dev.nucleusframework.window.tao.TaoMainDispatcherFactory {
+    <init>(...);
+    public *;
+}
+-keepnames class dev.nucleusframework.window.tao.TaoMainCoroutineDispatcher
+-keepnames class dev.nucleusframework.window.tao.ImmediateTaoMainDispatcher
+
+# kotlinx-coroutines' MainDispatcherLoader resolves the factory via the
+# service file — keep it from being renamed or removed.
+-keep class kotlinx.coroutines.internal.MainDispatcherFactory

decorated-window-tao/src/main/resources/META-INF/services/kotlinx.coroutines.internal.MainDispatcherFactory

@@ -0,0 +1 @@
+dev.nucleusframework.window.tao.TaoMainDispatcherFactory