/desktop-expert

name: desktop-expert
description: Compose Multiplatform Desktop patterns for the `desktopApp/` module. Use when working with (1) Desktop-only APIs (Window, WindowState, Tray, MenuBar, Dialog), (2) keyboard shortcuts and menu systems with OS-aware conventions (Cmd vs Ctrl, isMacOS branching), (3) desktop navigation (NavigationRail/sidebar vs Android bottom nav, multi-window), (4) file system integration (file pickers, drag-and-drop, Desktop.getDesktop()), (5) OS-specific behavior on macOS/Windows/Linux, (6) desktop UX principles (keyboard-first, tooltips). Delegates shared composables to compose-expert, build/packaging to gradle-expert, and source-set structure to kotlin-multiplatform.

Desktop Expert

Expert in Compose Multiplatform Desktop development for AmethystMultiplatform. Covers Desktop-specific APIs, OS conventions, navigation patterns, and UX principles.

When to Use This Skill

**Auto-invoke when:**

• Working with `desktopApp/` module files
• Using Desktop-only APIs: `Window`, `Tray`, `MenuBar`, `Dialog`
• Implementing keyboard shortcuts, menu systems
• Desktop navigation (NavigationRail, multi-window)
• File system operations (file pickers, drag-drop)
• OS-specific behavior (macOS, Windows, Linux)
• Desktop UX patterns (keyboard-first, tooltips)

**Delegate to:**

• **kotlin-multiplatform**: Shared code questions, `jvmMain` source set structure
• **gradle-expert**: All `build.gradle.kts` issues, dependency conflicts
• **compose-expert**: General Compose patterns, `@Composable` best practices, Material3

Scope

**In scope:**

• Desktop-only Compose APIs
• Window management, positioning, state
• MenuBar + keyboard shortcuts (OS-specific)
• System Tray integration
• Desktop navigation patterns (NavigationRail)
• File dialogs, Desktop.getDesktop()
• OS conventions (macOS vs Windows vs Linux)
• Desktop UX principles

**Out of scope:**

• Build configuration → **gradle-expert**
• Shared composables → **compose-expert**
• KMP structure → **kotlin-multiplatform**

---

1. Desktop Entry Point

application {} DSL

Desktop apps start with the `application {}` block:

// desktopApp/src/jvmMain/kotlin/Main.kt
fun main() = application {
    val windowState = rememberWindowState(
        width = 1200.dp,
        height = 800.dp,
        position = WindowPosition.Aligned(Alignment.Center)
    )

    Window(
        onCloseRequest = ::exitApplication,
        state = windowState,
        title = "Amethyst"
    ) {
        MenuBar { /* ... */ }
        App()
    }
}

**Key points:**

• `application {}` is the root composable (JVM-only)
• `Window()` creates the main window
• `rememberWindowState()` manages size/position
• `onCloseRequest` handles window close

**See:** `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt` — grep for `fun main()`, `application {`, the top-level `Window`, and `MenuBar {` (the file is large and line numbers drift; navigate by symbol).

---

2. Window Management

WindowState

val windowState = rememberWindowState(
    width = 1200.dp,
    height = 800.dp,
    position = WindowPosition.Aligned(Alignment.Center)
)

Window(
    state = windowState,
    title = "My App",
    resizable = true,
    onCloseRequest = ::exitApplication
) {
    // Content
}

Multiple Windows

fun main() = application {
    var showSettings by remember { mutableStateOf(false) }

    Window(onCloseRequest = ::exitApplication, title = "Main") {
        Button(onClick = { showSettings = true }) {
            Text("Open Settings")
        }
    }

    if (showSettings) {
        Window(
            onCloseRequest = { showSettings = false },
            title = "Settings"
        ) {
            // Settings UI
        }
    }
}

**Pattern:** Use state to control window visibility conditionally.

---

3. MenuBar System

Basic MenuBar

Window(onCloseRequest = ::exitApplication, title = "App") {
    MenuBar {
        Menu("File") {
            Item("New Note", onClick = { /* ... */ })
            Separator()
            Item("Quit", onClick = ::exitApplication)
        }
        Menu("Edit") {
            Item("Copy", onClick = { /* ... */ })
            Item("Paste", onClick = { /* ... */ })
        }
    }
    App()
}

Keyboard Shortcuts (OS-Aware)

**Current state:** `Main.kt` already branches on `isMacOS` (declared at L120) for every menu shortcut — `if (isMacOS) { KeyShortcut(..., meta = true) } else { KeyShortcut(..., ctrl = true) }` (see L239, L249, L286, L313, L325, L335, L347, L358, L374, L384, L400, L416, L449). When adding a new shortcut, follow the same branching pattern rather than hardcoding `ctrl = true`.

**OS-specific shortcuts:**

import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.KeyShortcut

// Detect OS
val isMacOS = System.getProperty("os.name").lowercase().contains("mac")

MenuBar {
    Menu("File") {
        Item(
            "New Note",
            shortcut = if (isMacOS) {
                KeyShortcut(Key.N, meta = true)  // Cmd+N on macOS
            } else {
                KeyShortcut(Key.N, ctrl = true)   // Ctrl+N on Win/Linux
            },
            onClick = { /* ... */ }
        )
        Item(
            "Settings",
            shortcut = if (isMacOS) {
                KeyShortcut(Key.Comma, meta = true)  // Cmd+, on macOS
            } else {
                KeyShortcut(Key.Comma, ctrl = true)   // Ctrl+, on Win/Linux
            },
            onClick = { /* ... */ }
        )
        Separator()
        Item(
            "Quit",
            shortcut = if (isMacOS) {
                KeyShortcut(Key.Q, meta = true)  // Cmd+Q on macOS
            } else {
                KeyShortcut(Key.Q, ctrl = true)   // Ctrl+Q on Win/Linux
            },
            onClick = ::exitApplication
        )
    }
}

**Standard shortcuts:**

| Action | macOS | Windows/Linux | |--------|-------|---------------| | New | Cmd+N |