✨ integrate crosspaste-mouse as a plugin for cross-device mouse sharing

CLAUDE.md

@@ -91,6 +91,7 @@ SQLDelight manages database schema in `.sq` files:
 - **UI sizing**: When adding size/dimension constants in UI code, prefer using values defined in `com.crosspaste.ui.theme.AppUISize` instead of inline literal `dp`/`sp` values.
 - **Thread-safe collections**: In `commonMain` code, prefer thread-safe Map/Set from `io.ktor.util.collections` (e.g., `ConcurrentMap`, `ConcurrentSet`) over platform-specific concurrent collections.
 - **Coroutine `delay`**: Always pass a `Duration` to `kotlinx.coroutines.delay`, never a raw number. Write `delay(280L.milliseconds)` / `delay(2.seconds)`, not `delay(280L)` or `delay(2000)`. Add `import kotlin.time.Duration.Companion.milliseconds` (or `.seconds`) as needed. This applies to both production code and tests.
+- **Coroutine dispatchers**: Never reference `kotlinx.coroutines.Dispatchers.IO` / `.Main` / `.Default` directly. Use the project's multiplatform dispatcher vals from `com.crosspaste.utils`: `ioDispatcher`, `mainDispatcher`, `cpuDispatcher` (declared as `expect` in `DispatcherUtils.kt`, with per-platform `actual`s in `DispatcherUtils.desktop.kt` / `.native.kt`). When a class needs a dispatcher for offloading blocking work, inject it as a constructor parameter defaulting to the appropriate val (e.g. `seedDispatcher: CoroutineDispatcher = ioDispatcher`) so tests can substitute a `TestDispatcher`.
 
 ## Key Technical Details
 

app/src/desktopMain/kotlin/com/crosspaste/CrossPaste.kt

@@ -31,6 +31,7 @@ import com.crosspaste.db.DriverFactory
 import com.crosspaste.listener.GlobalListener
 import com.crosspaste.log.DesktopCrossPasteLogger
 import com.crosspaste.mcp.McpServer
+import com.crosspaste.mouse.MouseDaemonManager
 import com.crosspaste.net.PasteBonjourService
 import com.crosspaste.net.PasteClient
 import com.crosspaste.net.ResourcesClient
@@ -174,6 +175,11 @@ class CrossPaste {
                     if (configManager.getCurrentConfig().enableMcpServer) {
                         ioCoroutineDispatcher.launch { koin.get<McpServer>().start() }
                     }
+                    if (!headless) {
+                        ioCoroutineDispatcher.launch {
+                            koin.get<MouseDaemonManager>().run()
+                        }
+                    }
                     koin.get<PasteClient>()
                     koin.get<PasteBonjourService>()
                     koin.get<CleanScheduler>().start()

app/src/desktopMain/kotlin/com/crosspaste/DesktopModule.kt

@@ -184,6 +184,7 @@ class DesktopModule(
                     pasteComponentModule(),
                     uiModule(),
                     viewModelModule(),
+                    desktopMouseModule(),
                 )
             }
         }

app/src/desktopMain/kotlin/com/crosspaste/DesktopMouseModule.kt

@@ -0,0 +1,165 @@
+package com.crosspaste
+
+import com.crosspaste.config.DesktopConfigManager
+import com.crosspaste.config.DevConfig
+import com.crosspaste.mouse.AwtLocalScreensProvider
+import com.crosspaste.mouse.LocalScreensProvider
+import com.crosspaste.mouse.MacosLocalScreensProvider
+import com.crosspaste.mouse.MouseDaemonBinary
+import com.crosspaste.mouse.MouseDaemonClient
+import com.crosspaste.mouse.MouseDaemonManager
+import com.crosspaste.mouse.MouseDaemonProcess
+import com.crosspaste.mouse.MouseIpcProtocol
+import com.crosspaste.mouse.MouseLayoutStore
+import com.crosspaste.mouse.Position
+import com.crosspaste.mouse.asDaemonHandle
+import com.crosspaste.path.AppPathProvider
+import com.crosspaste.platform.Platform
+import com.crosspaste.sync.SyncManager
+import com.crosspaste.ui.mouse.ScreenArrangementViewModel
+import com.crosspaste.utils.getAppEnvUtils
+import io.github.oshai.kotlinlogging.KotlinLogging
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+import kotlinx.serialization.builtins.MapSerializer
+import kotlinx.serialization.builtins.serializer
+import org.koin.core.module.Module
+import org.koin.dsl.module
+
+/**
+ * Bridges [MouseLayoutStore] to [DesktopConfigManager]-backed persistence.
+ *
+ * `mouseLayout` is stored as a JSON-encoded `Map<String, Position>` in
+ * [com.crosspaste.config.DesktopAppConfig.mouseLayout], matching the
+ * `blacklist` / `sourceExclusions` pattern: encode on write, decode on read,
+ * flow through the scalar `updateConfig(key, value)` path.
+ *
+ * Observable [flow] is derived from `configManager.config` directly — this
+ * is the single source of truth. If a save fails inside `updateConfig` and
+ * the config rolls back, the derived flow automatically reflects the
+ * rollback; observers never see a value that isn't persisted.
+ */
+class DesktopAppConfigMouseLayoutBacking(
+    private val configManager: DesktopConfigManager,
+) : MouseLayoutStore.Backing {
+
+    private val logger = KotlinLogging.logger {}
+
+    private val mapSerializer = MapSerializer(String.serializer(), Position.serializer())
+
+    private val updateLock = Any()
+
+    /**
+     * Last JSON value we already logged a decode failure for. De-duplicates
+     * warnings across the many `decode()` calls that happen while a corrupt
+     * config value keeps sitting in [DesktopConfigManager.config] — we only
+     * want one warning per distinct bad payload.
+     */
+    @Volatile
+    private var lastWarnedJson: String? = null
+
+    override fun snapshot(): Map<String, Position> = decode(configManager.config.value.mouseLayout)
+
+    override fun update(updater: (Map<String, Position>) -> Map<String, Position>) {
+        synchronized(updateLock) {
+            val current = decode(configManager.config.value.mouseLayout)
+            val next = updater(current)
+            configManager.updateConfig(
+                "mouseLayout",
+                MouseIpcProtocol.json.encodeToString(mapSerializer, next),
+            )
+        }
+    }
+
+    override fun flow(): Flow<Map<String, Position>> =
+        configManager.config
+            .map { decode(it.mouseLayout) }
+            .distinctUntilChanged()
+
+    private fun decode(json: String): Map<String, Position> =
+        runCatching { MouseIpcProtocol.json.decodeFromString(mapSerializer, json) }
+            .getOrElse { e ->
+                if (lastWarnedJson != json) {
+                    lastWarnedJson = json
+                    logger.warn(e) {
+                        "Failed to decode mouseLayout JSON; falling back to empty layout. " +
+                            "Offending value (truncated): ${json.take(200)}"
+                    }
+                }
+                emptyMap()
+            }
+}
+
+fun desktopMouseModule(): Module =
+    module {
+        single<LocalScreensProvider> {
+            val platform = get<Platform>()
+            if (platform.isMacos()) MacosLocalScreensProvider() else AwtLocalScreensProvider()
+        }
+        single<MouseLayoutStore> {
+            MouseLayoutStore(DesktopAppConfigMouseLayoutBacking(get<DesktopConfigManager>()))
+        }
+        single<MouseDaemonManager> {
+            val configManager = get<DesktopConfigManager>()
+            MouseDaemonManager(
+                enabledFlow =
+                    configManager.config
+                        .map { it.mouseEnabled }
+                        .distinctUntilChanged(),
+                portFlow =
+                    configManager.config
+                        .map { it.mouseListenPort }
+                        .distinctUntilChanged(),
+                layoutStore = get(),
+                // Source the paired-device list from SyncManager's already-shared
+                // StateFlow rather than the raw DAO flow. The DAO flow is fine to
+                // observe in isolation but conceptually mouse cares about "business
+                // peers managed by SyncManager", not about raw table rows — and
+                // SyncManager's StateFlow is the canonical multi-cast view.
+                syncRuntimeInfosFlow = get<SyncManager>().realTimeSyncRuntimeInfos,
+                clientFactory = {
+                    val platform = get<Platform>()
+                    val pathProvider = get<AppPathProvider>()
+                    val isDevelopment = getAppEnvUtils().isDevelopment()
+
+                    // Dev: developer-supplied path from development.properties.
+                    // Prod: bundled binary sits next to the app's runtime under pasteAppExePath.
+                    val candidates =
+                        if (isDevelopment) {
+                            listOfNotNull(DevConfig.mouseBinaryPath)
+                        } else {
+                            listOf(
+                                pathProvider.pasteAppExePath.resolve(MouseDaemonBinary.binaryName(platform)).toString(),
+                            )
+                        }
+
+                    val binary =
+                        MouseDaemonBinary.resolve(candidatePaths = candidates)
+                            ?: throw IllegalStateException(
+                                buildString {
+                                    append("crosspaste-mouse binary not found. Tried: ")
+                                    append(if (candidates.isEmpty()) "(no candidates)" else candidates.joinToString())
+                                    if (isDevelopment) {
+                                        append(". Set mouseBinaryPath in development.properties, ")
+                                        append("or set CROSSPASTE_MOUSE_BIN / -Dcrosspaste.mouse.binary.")
+                                    } else {
+                                        append(
+                                            ". The bundled binary is missing — please reinstall the app or " +
+                                                "report this issue.",
+                                        )
+                                    }
+                                },
+                            )
+                    MouseDaemonClient(MouseDaemonProcess.spawn(binary).asDaemonHandle())
+                },
+            )
+        }
+        factory<ScreenArrangementViewModel> {
+            ScreenArrangementViewModel(
+                events = get<MouseDaemonManager>().events,
+                layoutStore = get(),
+                localScreensProvider = get(),
+            )
+        }
+    }

app/src/desktopMain/kotlin/com/crosspaste/app/DesktopAppWindowManager.kt

@@ -164,6 +164,17 @@ abstract class DesktopAppWindowManager(
 
     fun isBubbleWindowVisible(): Boolean = _bubbleWindowInfo.value.show
 
+    private val _mouseSettingsWindowVisible = MutableStateFlow(false)
+    val mouseSettingsWindowVisible: StateFlow<Boolean> = _mouseSettingsWindowVisible
+
+    fun showMouseSettingsWindow() {
+        _mouseSettingsWindowVisible.value = true
+    }
+
+    fun hideMouseSettingsWindow() {
+        _mouseSettingsWindowVisible.value = false
+    }
+
     abstract suspend fun focusBubbleWindow()
 
     abstract fun startWindowService()

app/src/desktopMain/kotlin/com/crosspaste/config/DesktopAppConfig.kt

@@ -66,6 +66,13 @@ data class DesktopAppConfig(
     // Highest app version whose changelog the user has already seen. Empty until seeded on
     // first launch; drives the highlight badge on the changelog menu entry after an upgrade.
     val lastSeenChangelogVersion: String = "",
+    // Mouse daemon (crosspaste-mouse plugin)
+    val mouseEnabled: Boolean = false,
+    val mouseListenPort: Int = 4243,
+    // JSON-encoded Map<String, Position> (deviceId → virtual-desktop offset).
+    // Stored as a String so it flows through the scalar copy(key, value) path,
+    // matching the blacklist / sourceExclusions / useNetworkInterfaces pattern.
+    val mouseLayout: String = "{}",
 ) : AppConfig {
     override fun copy(
         key: String,
@@ -180,5 +187,8 @@ data class DesktopAppConfig(
                 } else {
                     lastSeenChangelogVersion
                 },
+            mouseEnabled = if (key == "mouseEnabled") toBoolean(value) else mouseEnabled,
+            mouseListenPort = if (key == "mouseListenPort") toInt(value) else mouseListenPort,
+            mouseLayout = if (key == "mouseLayout") toString(value) else mouseLayout,
         )
 }

app/src/desktopMain/kotlin/com/crosspaste/config/DevConfig.kt

@@ -11,4 +11,6 @@ object DevConfig {
     val pasteUserPath: String? = development.getProperty("pasteUserPath")
 
     val marketingMode: Boolean = development.getProperty("marketingMode")?.toBoolean() == true
+
+    val mouseBinaryPath: String? = development.getProperty("mouseBinaryPath")?.takeIf { it.isNotBlank() }
 }

app/src/desktopMain/kotlin/com/crosspaste/mouse/LocalScreensProvider.kt

@@ -0,0 +1,42 @@
+package com.crosspaste.mouse
+
+import java.awt.GraphicsEnvironment
+
+/**
+ * Source of truth for "what monitors does this machine have right now."
+ *
+ * The mouse daemon emits [IpcEvent.Initialized] with the same information,
+ * but only after it has been spawned. Until then — and across the brief
+ * window before the [com.crosspaste.ui.mouse.ScreenArrangementViewModel]
+ * starts collecting — we still want the canvas to render the local
+ * screens so the user has a visual baseline.
+ *
+ * Implementations must be safe to call on any thread; the default AWT
+ * implementation just queries the JVM graphics environment.
+ */
+fun interface LocalScreensProvider {
+    fun snapshot(): List<ScreenInfo>
+}
+
+class AwtLocalScreensProvider : LocalScreensProvider {
+    override fun snapshot(): List<ScreenInfo> {
+        val env =
+            runCatching { GraphicsEnvironment.getLocalGraphicsEnvironment() }.getOrNull()
+                ?: return emptyList()
+        if (env.isHeadlessInstance) return emptyList()
+        val primary = env.defaultScreenDevice
+        return env.screenDevices.mapIndexed { index, device ->
+            val config = device.defaultConfiguration
+            val bounds = config.bounds
+            ScreenInfo(
+                id = index,
+                width = bounds.width,
+                height = bounds.height,
+                x = bounds.x,
+                y = bounds.y,
+                scaleFactor = config.defaultTransform.scaleX.takeIf { it > 0.0 } ?: 1.0,
+                isPrimary = device == primary,
+            )
+        }
+    }
+}

app/src/desktopMain/kotlin/com/crosspaste/mouse/MacosLocalScreensProvider.kt

@@ -0,0 +1,79 @@
+package com.crosspaste.mouse
+
+import com.crosspaste.platform.macos.api.MacosApi
+import io.github.oshai.kotlinlogging.KotlinLogging
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.builtins.ListSerializer
+import kotlinx.serialization.json.Json
+
+/**
+ * Reads the local monitor list from `NSScreen` via the Swift dylib so we
+ * can include each display's marketing name (e.g. "DELL U2725QE",
+ * "LG SDQHD"). AWT's `GraphicsDevice` doesn't expose that — the only place
+ * macOS surfaces it through a stable public API is `NSScreen.localizedName`
+ * (10.15+).
+ *
+ * If the native call fails for any reason (dylib missing, JSON corrupted,
+ * security context restricted), we fall back to the AWT provider so the
+ * canvas still renders rectangles — names will just be missing.
+ */
+class MacosLocalScreensProvider(
+    private val fallback: LocalScreensProvider = AwtLocalScreensProvider(),
+) : LocalScreensProvider {
+
+    private val logger = KotlinLogging.logger {}
+    private val json = Json { ignoreUnknownKeys = true }
+
+    override fun snapshot(): List<ScreenInfo> {
+        val raw =
+            runCatching { MacosApi.getString(MacosApi.INSTANCE.getLocalScreensJson()) }
+                .getOrElse { e ->
+                    logger.warn(e) { "getLocalScreensJson native call failed; falling back to AWT" }
+                    null
+                }
+                ?: return fallback.snapshot()
+        val parsed =
+            runCatching { json.decodeFromString(ListSerializer(MacosScreenJson.serializer()), raw) }
+                .getOrElse { e ->
+                    logger.warn(e) { "failed to parse getLocalScreensJson output; falling back to AWT" }
+                    null
+                } ?: return fallback.snapshot()
+        if (parsed.isEmpty()) return fallback.snapshot()
+        return parsed.map { it.toScreenInfo().withWallpaper() }
+    }
+
+    private fun ScreenInfo.withWallpaper(): ScreenInfo {
+        val path =
+            runCatching { MacosApi.getString(MacosApi.INSTANCE.getDesktopWallpaperPng(id)) }
+                .getOrElse { e ->
+                    logger.warn(e) { "getDesktopWallpaperPng failed for displayId=$id" }
+                    null
+                }
+        return copy(wallpaperPath = path?.takeIf { it.isNotBlank() })
+    }
+
+    @Serializable
+    private data class MacosScreenJson(
+        val id: Int,
+        val name: String? = null,
+        val x: Int,
+        val y: Int,
+        val width: Int,
+        val height: Int,
+        @SerialName("scaleFactor") val scaleFactor: Double,
+        @SerialName("isPrimary") val isPrimary: Boolean,
+    ) {
+        fun toScreenInfo(): ScreenInfo =
+            ScreenInfo(
+                id = id,
+                width = width,
+                height = height,
+                x = x,
+                y = y,
+                scaleFactor = scaleFactor,
+                isPrimary = isPrimary,
+                name = name?.takeIf { it.isNotBlank() },
+            )
+    }
+}