# OS Detection & Platform-Specific Code

Patterns for detecting operating system and implementing platform-specific behavior in Compose Desktop.

## OS Detection

### Basic Detection

```kotlin
val osName = System.getProperty("os.name").lowercase()

val isMacOS = osName.contains("mac")
val isWindows = osName.contains("win")
val isLinux = osName.contains("nux") || osName.contains("nix")
```

### System Properties

```kotlin
// OS name
System.getProperty("os.name")
// Examples: "Mac OS X", "Windows 10", "Linux"

// OS version
System.getProperty("os.version")
// Examples: "14.2.1", "10.0", "6.5.0-14-generic"

// OS architecture
System.getProperty("os.arch")
// Examples: "aarch64", "x86_64", "amd64"

// User home directory
System.getProperty("user.home")
// Examples: "/Users/username", "C:\Users\username", "/home/username"

// File separator
System.getProperty("file.separator")
// Examples: "/" (Unix), "\" (Windows)

// Path separator
System.getProperty("path.separator")
// Examples: ":" (Unix), ";" (Windows)
```

---

## PlatformDetector Utility

Create a centralized utility for platform detection.

**File:** `commons/src/jvmMain/kotlin/utils/PlatformDetector.kt`

```kotlin
package com.vitorpamplona.amethyst.commons.utils

object PlatformDetector {
    private val osName = System.getProperty("os.name").lowercase()

    val isMacOS: Boolean = osName.contains("mac")
    val isWindows: Boolean = osName.contains("win")
    val isLinux: Boolean = osName.contains("nux") || osName.contains("nix")

    val platform: Platform = when {
        isMacOS -> Platform.MacOS
        isWindows -> Platform.Windows
        isLinux -> Platform.Linux
        else -> Platform.Unknown
    }

    enum class Platform {
        MacOS,
        Windows,
        Linux,
        Unknown
    }

    // File paths
    val fileSeparator: String = System.getProperty("file.separator")
    val pathSeparator: String = System.getProperty("path.separator")

    // User directories
    val userHome: String = System.getProperty("user.home")

    val appDataDir: String = when (platform) {
        Platform.MacOS -> "$userHome/Library/Application Support"
        Platform.Windows -> System.getenv("APPDATA") ?: "$userHome\\AppData\\Roaming"
        Platform.Linux -> System.getenv("XDG_CONFIG_HOME") ?: "$userHome/.config"
        Platform.Unknown -> userHome
    }

    // Modifier key names
    val primaryModifierName: String = if (isMacOS) "Cmd" else "Ctrl"
    val secondaryModifierName: String = if (isMacOS) "Option" else "Alt"

    fun platformSpecific(
        macOS: () -> Unit = {},
        windows: () -> Unit = {},
        linux: () -> Unit = {},
        fallback: () -> Unit = {}
    ) {
        when (platform) {
            Platform.MacOS -> macOS()
            Platform.Windows -> windows()
            Platform.Linux -> linux()
            Platform.Unknown -> fallback()
        }
    }
}
```

**Usage:**

```kotlin
// Simple check
if (PlatformDetector.isMacOS) {
    // macOS-specific code
}

// Pattern matching
when (PlatformDetector.platform) {
    Platform.MacOS -> setupMacDock()
    Platform.Windows -> setupWindowsTray()
    Platform.Linux -> setupLinuxTray()
    Platform.Unknown -> showWarning()
}

// Platform-specific execution
PlatformDetector.platformSpecific(
    macOS = { setupMacMenuBar() },
    windows = { setupWindowsMenu() },
    linux = { setupLinuxMenu() }
)

// File paths
val configPath = "${PlatformDetector.appDataDir}${PlatformDetector.fileSeparator}amethyst"
```

---

## Platform-Specific UI

### Keyboard Shortcuts Helper

```kotlin
package com.vitorpamplona.amethyst.commons.utils

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

object DesktopShortcuts {
    private val isMacOS = PlatformDetector.isMacOS

    fun primary(key: Key) = if (isMacOS) {
        KeyShortcut(key, meta = true)
    } else {
        KeyShortcut(key, ctrl = true)
    }

    fun primaryShift(key: Key) = if (isMacOS) {
        KeyShortcut(key, meta = true, shift = true)
    } else {
        KeyShortcut(key, ctrl = true, shift = true)
    }

    fun primaryAlt(key: Key) = if (isMacOS) {
        KeyShortcut(key, meta = true, alt = true)
    } else {
        KeyShortcut(key, ctrl = true, alt = true)
    }

    val modifierName = PlatformDetector.primaryModifierName
    val secondaryName = PlatformDetector.secondaryModifierName

    fun formatShortcut(key: String, withPrimary: Boolean = true): String {
        return if (withPrimary) "$modifierName+$key" else key
    }
}
```

### File Paths Helper

```kotlin
package com.vitorpamplona.amethyst.commons.utils

import java.io.File

object FilePaths {
    private val separator = PlatformDetector.fileSeparator

    fun join(vararg parts: String): String {
        return parts.joinToString(separator)
    }

    fun appConfig(appName: String): String {
        return join(PlatformDetector.appDataDir, appName)
    }

    fun appCache(appName: String): String {
        return when (PlatformDetector.platform) {
            PlatformDetector.Platform.MacOS ->
                join(PlatformDetector.userHome, "Library", "Caches", appName)
            PlatformDetector.Platform.Windows ->
                join(System.getenv("LOCALAPPDATA") ?: "${PlatformDetector.userHome}\\AppData\\Local", appName)
            PlatformDetector.Platform.Linux ->
                join(System.getenv("XDG_CACHE_HOME") ?: "${PlatformDetector.userHome}/.cache", appName)
            else -> join(PlatformDetector.userHome, ".cache", appName)
        }
    }

    fun ensureDirectory(path: String): File {
        return File(path).apply {
            if (!exists()) {
                mkdirs()
            }
        }
    }
}

// Usage
val configDir = FilePaths.ensureDirectory(FilePaths.appConfig("amethyst"))
val cacheDir = FilePaths.ensureDirectory(FilePaths.appCache("amethyst"))
```

---

## Platform-Specific Features

### Open External URL

```kotlin
// commons/src/commonMain/kotlin/utils/ExternalUrl.kt
expect fun openExternalUrl(url: String)

// commons/src/jvmMain/kotlin/utils/ExternalUrl.jvm.kt
import java.awt.Desktop
import java.net.URI

actual fun openExternalUrl(url: String) {
    if (Desktop.isDesktopSupported() && Desktop.getDesktop().isSupported(Desktop.Action.BROWSE)) {
        Desktop.getDesktop().browse(URI(url))
    }
}
```

### File Picker

```kotlin
// Platform-specific file picker
fun showFilePicker(
    title: String = "Select file",
    mode: FilePickerMode = FilePickerMode.Load
): String? {
    val fileDialog = java.awt.FileDialog(
        java.awt.Frame(),
        title,
        when (mode) {
            FilePickerMode.Load -> java.awt.FileDialog.LOAD
            FilePickerMode.Save -> java.awt.FileDialog.SAVE
        }
    )

    // macOS-specific: Enable file selection features
    if (PlatformDetector.isMacOS) {
        System.setProperty("apple.awt.fileDialogForDirectories", "false")
    }

    fileDialog.isVisible = true

    return fileDialog.file?.let { "${fileDialog.directory}$it" }
}

enum class FilePickerMode {
    Load,
    Save
}
```

### Directory Picker (macOS)

```kotlin
fun showDirectoryPicker(title: String = "Select directory"): String? {
    if (PlatformDetector.isMacOS) {
        // macOS-specific directory picker
        System.setProperty("apple.awt.fileDialogForDirectories", "true")
    }

    val fileDialog = java.awt.FileDialog(java.awt.Frame(), title, java.awt.FileDialog.LOAD)
    fileDialog.isVisible = true

    if (PlatformDetector.isMacOS) {
        System.setProperty("apple.awt.fileDialogForDirectories", "false")
    }

    return fileDialog.directory
}
```

---

## Window Decorations

### macOS-Specific

```kotlin
// Unified title bar (macOS Big Sur+)
if (PlatformDetector.isMacOS) {
    Window(
        undecorated = false,
        transparent = true,
        // ...
    ) {
        // Custom title bar
    }
}
```

### Windows-Specific

```kotlin
// Custom window chrome (Windows)
if (PlatformDetector.isWindows) {
    Window(
        undecorated = true,
        // Custom decorations
    ) {
        Column {
            // Custom title bar with min/max/close buttons
            WindowTitleBar()
            // Content
        }
    }
}
```

---

## System Tray Icons

Different icon formats per OS:

```kotlin
fun getTrayIcon(): Painter {
    return when (PlatformDetector.platform) {
        Platform.MacOS -> painterResource("tray-icon-mac.png")  // Template icon
        Platform.Windows -> painterResource("tray-icon-win.ico")
        Platform.Linux -> painterResource("tray-icon-linux.png")
        else -> painterResource("tray-icon.png")
    }
}

// macOS: Template icons (black/transparent)
// Windows: ICO format, 16x16
// Linux: PNG, typically 24x24
```

---

## Native Notifications

```kotlin
// Platform-specific notification implementation
fun sendNotification(title: String, message: String) {
    PlatformDetector.platformSpecific(
        macOS = {
            // macOS: Use NSUserNotification (via tray)
            trayState.sendNotification(
                Notification(title, message, Notification.Type.Info)
            )
        },
        windows = {
            // Windows: Use Windows toast notifications
            trayState.sendNotification(
                Notification(title, message, Notification.Type.Info)
            )
        },
        linux = {
            // Linux: Use libnotify (via tray)
            trayState.sendNotification(
                Notification(title, message, Notification.Type.Info)
            )
        }
    )
}
```

---

## Architecture Detection

```kotlin
object ArchDetector {
    private val arch = System.getProperty("os.arch").lowercase()

    val isArm: Boolean = arch.contains("aarch") || arch.contains("arm")
    val isX64: Boolean = arch.contains("x86_64") || arch.contains("amd64")
    val isX86: Boolean = arch.contains("x86") && !isX64

    val architecture: Architecture = when {
        isArm -> Architecture.ARM
        isX64 -> Architecture.X64
        isX86 -> Architecture.X86
        else -> Architecture.Unknown
    }

    enum class Architecture {
        ARM,
        X64,
        X86,
        Unknown
    }
}

// Usage: Load correct native library
fun loadNativeLib() {
    val libName = when {
        PlatformDetector.isMacOS && ArchDetector.isArm -> "libsecp256k1-macos-arm64"
        PlatformDetector.isMacOS && ArchDetector.isX64 -> "libsecp256k1-macos-x64"
        PlatformDetector.isWindows && ArchDetector.isX64 -> "libsecp256k1-win-x64"
        PlatformDetector.isLinux && ArchDetector.isX64 -> "libsecp256k1-linux-x64"
        else -> throw UnsupportedOperationException("Unsupported platform")
    }

    System.loadLibrary(libName)
}
```

---

## Testing Platform Detection

```kotlin
@Test
fun testPlatformDetection() {
    println("OS: ${System.getProperty("os.name")}")
    println("Version: ${System.getProperty("os.version")}")
    println("Arch: ${System.getProperty("os.arch")}")
    println()
    println("Is macOS: ${PlatformDetector.isMacOS}")
    println("Is Windows: ${PlatformDetector.isWindows}")
    println("Is Linux: ${PlatformDetector.isLinux}")
    println("Platform: ${PlatformDetector.platform}")
    println()
    println("User home: ${PlatformDetector.userHome}")
    println("App data: ${PlatformDetector.appDataDir}")
    println("File separator: ${PlatformDetector.fileSeparator}")
}

// Example output (macOS):
// OS: Mac OS X
// Version: 14.2.1
// Arch: aarch64
//
// Is macOS: true
// Is Windows: false
// Is Linux: false
// Platform: MacOS
//
// User home: /Users/username
// App data: /Users/username/Library/Application Support
// File separator: /
```

---

## Best Practices

### 1. Centralize Detection

✅ **DO:** Use PlatformDetector singleton
```kotlin
if (PlatformDetector.isMacOS) { /* ... */ }
```

❌ **DON'T:** Repeat detection everywhere
```kotlin
if (System.getProperty("os.name").lowercase().contains("mac")) { /* ... */ }
```

### 2. Use expect/actual for Platform APIs

```kotlin
// commonMain
expect fun openFile(path: String)

// jvmMain (Desktop)
actual fun openFile(path: String) {
    Desktop.getDesktop().open(File(path))
}

// androidMain
actual fun openFile(path: String) {
    context.startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(path)))
}
```

### 3. Graceful Degradation

```kotlin
fun openBrowser(url: String) {
    try {
        if (Desktop.isDesktopSupported()) {
            Desktop.getDesktop().browse(URI(url))
        } else {
            // Fallback: Copy to clipboard
            Toolkit.getDefaultToolkit().systemClipboard.setContents(
                StringSelection(url),
                null
            )
            showMessage("URL copied to clipboard: $url")
        }
    } catch (e: Exception) {
        showError("Failed to open browser: ${e.message}")
    }
}
```

### 4. Test on All Platforms

Always test platform-specific code on:
- macOS (Intel + Apple Silicon if possible)
- Windows (10/11)
- Linux (Ubuntu/Fedora)

---

## Common Patterns

### Pattern: Config File Location

```kotlin
fun getConfigFile(filename: String): File {
    val configDir = when (PlatformDetector.platform) {
        Platform.MacOS ->
            File("${PlatformDetector.userHome}/Library/Application Support/Amethyst")
        Platform.Windows ->
            File("${System.getenv("APPDATA")}\\Amethyst")
        Platform.Linux ->
            File("${PlatformDetector.userHome}/.config/amethyst")
        else ->
            File("${PlatformDetector.userHome}/.amethyst")
    }

    if (!configDir.exists()) {
        configDir.mkdirs()
    }

    return File(configDir, filename)
}

// Usage
val settingsFile = getConfigFile("settings.json")
```

### Pattern: Platform-Specific Resources

```kotlin
fun getPlatformIcon(name: String): Painter {
    val extension = when (PlatformDetector.platform) {
        Platform.MacOS -> "icns"
        Platform.Windows -> "ico"
        else -> "png"
    }

    return painterResource("$name.$extension")
}

// Resources:
// src/jvmMain/resources/app-icon.icns (macOS)
// src/jvmMain/resources/app-icon.ico (Windows)
// src/jvmMain/resources/app-icon.png (Linux)
```

---

## References

- [System Properties (Java)](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/System.html#getProperties())
- [Desktop API (Java)](https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/Desktop.html)
- [File System Standards (XDG)](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)