Merge pull request #416 from NucleusFramework/refactor/trayapp-stable-api

Promote TrayApp to a stable API; log instead of crashing on non-Tao backend

Author: kdroidFilter

README.md

@@ -591,7 +591,6 @@ Add the following to your ProGuard rules file:
 ## Quick Start (minimal)
 
 ```kotlin
-@OptIn(ExperimentalTrayAppApi::class)
 application {
     val trayAppState = rememberTrayAppState(
         initialWindowSize = DpSize(300.dp, 420.dp),

demo/src/jvmMain/kotlin/dev/nucleusframework/composenativetray/demo/TrayAppDemo.kt

@@ -19,7 +19,6 @@ import composenativetray.demo.generated.resources.Res
 import composenativetray.demo.generated.resources.icon
 import dev.nucleusframework.application.SingleInstanceRestoreEffect
 import dev.nucleusframework.application.nucleusApplication
-import dev.nucleusframework.composenativetray.tray.api.ExperimentalTrayAppApi
 import dev.nucleusframework.composenativetray.tray.api.TrayApp
 import dev.nucleusframework.composenativetray.tray.api.TrayWindowDismissMode
 import dev.nucleusframework.composenativetray.tray.api.rememberTrayAppState
@@ -30,7 +29,6 @@ import dev.nucleusframework.window.material.MaterialTitleBar
 import kotlinx.coroutines.launch
 import org.jetbrains.compose.resources.painterResource
 
-@OptIn(ExperimentalTrayAppApi::class)
 fun main() {
     allowComposeNativeTrayLogging = true
     nucleusApplication(dockIconFollowsWindows = true) {

src/jvmMain/kotlin/dev/nucleusframework/composenativetray/tray/api/ExperimentalTrayAppApi.kt

@@ -1,5 +1,4 @@
 @file:OptIn(
-    ExperimentalTrayAppApi::class,
     ExperimentalTransitionApi::class,
     InternalAnimationApi::class,
 )
@@ -51,6 +50,7 @@ import dev.nucleusframework.composenativetray.utils.MenuContentHash
 import dev.nucleusframework.composenativetray.utils.PersistentAnimatedVisibility
 import dev.nucleusframework.composenativetray.utils.TrayScreenGeometry
 import dev.nucleusframework.composenativetray.utils.debugln
+import dev.nucleusframework.composenativetray.utils.errorln
 import dev.nucleusframework.composenativetray.utils.getTrayWindowPosition
 import dev.nucleusframework.composenativetray.utils.getTrayWindowPositionForInstance
 import dev.nucleusframework.composenativetray.utils.isMenuBarInDarkMode
@@ -123,7 +123,6 @@ private val defaultVerticalOffset =
 
 // --------------------- Public API (overloads) ---------------------
 
-@ExperimentalTrayAppApi
 @Composable
 fun NucleusApplicationScope.TrayApp(
     icon: ImageVector,
@@ -179,7 +178,6 @@ fun NucleusApplicationScope.TrayApp(
     )
 }
 
-@ExperimentalTrayAppApi
 @Composable
 fun NucleusApplicationScope.TrayApp(
     icon: Painter,
@@ -227,7 +225,6 @@ fun NucleusApplicationScope.TrayApp(
 }
 
 /** Painter on Windows, ImageVector on macOS/Linux */
-@ExperimentalTrayAppApi
 @Composable
 fun NucleusApplicationScope.TrayApp(
     windowsIcon: Painter,
@@ -297,7 +294,6 @@ fun NucleusApplicationScope.TrayApp(
     }
 }
 
-@ExperimentalTrayAppApi
 @Composable
 fun NucleusApplicationScope.TrayApp(
     icon: DrawableResource,
@@ -341,7 +337,6 @@ fun NucleusApplicationScope.TrayApp(
     )
 }
 
-@ExperimentalTrayAppApi
 @Composable
 fun NucleusApplicationScope.TrayApp(
     windowsIcon: DrawableResource,
@@ -414,17 +409,16 @@ fun NucleusApplicationScope.TrayApp(
 // --------------------- Core implementation (Tao backend only) ---------------------
 
 /**
- * Tray icon + anchored popup. Runs exclusively on the Nucleus Tao backend —
- * call it inside `nucleusApplication(backend = NucleusBackend.Tao)` (or
- * `Auto` with `decorated-window-tao` on the classpath).
+ * Tray icon + anchored popup. Runs exclusively on the Nucleus Tao backend,
+ * which the `Auto` backend selects automatically once the
+ * `decorated-window-tao` module is on the classpath.
  *
  * On Windows + macOS the popup body is hosted in a standalone per-pixel
  * transparent, non-activating native panel — no backing window exists anywhere
  * (nothing in the taskbar/Dock, Alt-Tab or the Start task view). On Linux the
  * popup is a regular undecorated Tao window (opaque): no cross-WM transparency
  * equivalent exists.
  */
-@ExperimentalTrayAppApi
 @Composable
 fun NucleusApplicationScope.TrayApp(
     iconContent: @Composable () -> Unit,
@@ -446,10 +440,13 @@ fun NucleusApplicationScope.TrayApp(
     menu: (TrayMenuBuilder.() -> Unit)? = null,
     content: @Composable () -> Unit,
 ) {
-    require(backend == NucleusBackend.Tao) {
-        "TrayApp requires the Tao window backend. Launch with " +
-            "nucleusApplication(backend = NucleusBackend.Tao) and ship the " +
-            "nucleus.decorated-window-tao module."
+    if (backend != NucleusBackend.Tao) {
+        errorln {
+            "TrayApp requires the Tao window backend. Launch with " +
+                "nucleusApplication() and ship the " +
+                "nucleus.decorated-window-tao module."
+        }
+        return
     }
 
     // Linux gates on runtime availability: the panel is a raw X11 window,

src/jvmMain/kotlin/dev/nucleusframework/composenativetray/tray/api/TrayApp.kt

@@ -12,7 +12,6 @@ import kotlinx.coroutines.flow.asStateFlow
  * State holder for TrayApp that provides programmatic control over the tray window
  * and observability of its state changes, including window dismiss behavior.
  */
-@ExperimentalTrayAppApi
 class TrayAppState(
     initialWindowSize: DpSize = DpSize(300.dp, 200.dp),
     initiallyVisible: Boolean = false,
@@ -87,7 +86,6 @@ class TrayAppState(
 }
 
 /** Creates and remembers a TrayAppState instance */
-@ExperimentalTrayAppApi
 @Composable
 fun rememberTrayAppState(
     initialWindowSize: DpSize = DpSize(300.dp, 200.dp),

src/jvmMain/kotlin/dev/nucleusframework/composenativetray/tray/api/TrayAppState.kt

@@ -3,7 +3,6 @@ package dev.nucleusframework.composenativetray.tray.api
 /**
  * Defines how the tray window should be dismissed (hidden)
  */
-@ExperimentalTrayAppApi
 enum class TrayWindowDismissMode {
     /**
      * The window automatically hides when it loses focus or when clicking outside.