# Target Compatibility Guide

Current targets (Android, JVM/Desktop, iOS) and future targets (web, wasm) with constraints.

## Current Primary Targets

### Android (androidMain)

**Status:** ✅ Mature, production-ready

**Runtime:** JVM (Dalvik/ART)

**Available:**
- Android framework (Activity, Context, Intent, etc.)
- AndroidX libraries (ViewModel, Navigation, etc.)
- JVM libraries via jvmAndroid (Jackson, OkHttp)
- Platform-specific crypto: `secp256k1-kmp-jni-android` (0.23.0 in `libs.versions.toml`)

**Constraints:**
- Mobile UX paradigms (bottom navigation, vertical scroll)
- Touch-first interaction
- Limited screen space
- Battery/performance constraints

**Example code:**
```kotlin
// androidMain
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // Android-specific lifecycle
    }
}
```

---

### JVM / Desktop (jvmMain)

**Status:** ✅ Active development, functional

**Runtime:** JVM

**Available:**
- Pure JVM libraries
- JVM libraries via jvmAndroid (Jackson, OkHttp)
- Compose Desktop (Window, MenuBar, etc.)
- Platform-specific crypto: `secp256k1-kmp-jni-jvm` (same 0.23.0 line)

**Constraints:**
- Desktop UX paradigms (sidebar, menus, keyboard shortcuts)
- Keyboard + mouse interaction
- Larger screen space
- Different navigation patterns (no back stack)

**Example code:**
```kotlin
// jvmMain
fun main() = application {
    Window(
        onCloseRequest = ::exitApplication,
        title = "Amethyst"
    ) {
        MenuBar { ... }  // Desktop-specific
        NavigationRail { ... }  // Sidebar
    }
}
```

---

### iOS (iosMain + architecture targets)

**Status:** ✅ Mature — actively built and tested

**Runtime:** Native iOS

**Source sets:**
- iosMain (common iOS code)
- iosArm64Main (device - iPhone/iPad)
- iosSimulatorArm64Main (Apple Silicon simulator)
- iosX64Main (Intel simulator)
- macosArm64Main (host tooling / XCFramework build)

**Available:**
- iOS platform APIs (platform.posix, Foundation, etc.)
- Native crypto (Security framework)
- SwiftUI integration (via KMP framework)

**NOT available:**
- JVM libraries (Jackson, OkHttp)
- jvmAndroid source set
- JVM-specific APIs

**Constraints:**
- Mobile UX (similar to Android)
- Swift/Objective-C interop
- XCFramework distribution
- CocoaPods integration

**Example code:**
```kotlin
// iosMain
actual object Secp256k1Instance {
    actual fun signSchnorr(...): ByteArray {
        // Use iOS Security framework
    }
}
```

**XCFramework setup:**
```kotlin
// quartz/build.gradle.kts
kotlin {
    listOf(macosArm64(), iosArm64(), iosSimulatorArm64())
        .forEach { target ->
            target.binaries.framework {
                baseName = "quartz-kmpKit"
                isStatic = true
            }
        }
}
```

---

## Future Targets

### Web / JavaScript (jsMain)

**Status:** ❌ Not implemented, consider for future

**Runtime:** JavaScript (browser or Node.js)

**Available:**
- Kotlin/JS stdlib
- JS/DOM APIs
- kotlinx.* libraries (serialization, coroutines, datetime)
- ktor-client (HTTP)

**NOT available:**
- ❌ JVM libraries (Jackson, OkHttp)
- ❌ jvmAndroid source set
- ❌ platform.posix (no file system access like native)
- ❌ Blocking APIs (different async model - JS event loop)

**Constraints:**
- Single-threaded event loop
- No blocking calls
- Different async patterns (Promises, async/await)
- Browser security (CORS, no file system)

**Migration path from current code:**

| Current (jvmAndroid) | Web-compatible alternative |
|---------------------|---------------------------|
| Jackson JSON | kotlinx.serialization |
| OkHttp HTTP | ktor-client |
| java.math.BigDecimal | Kotlin BigDecimal (coming) |
| Blocking I/O | Suspending functions |

**Example migration:**
```kotlin
// Current: jvmAndroid
val mapper = ObjectMapper()
val event = mapper.readValue(json, Event::class.java)

// Future: commonMain (works on web)
val json = Json { ignoreUnknownKeys = true }
val event = json.decodeFromString<Event>(jsonString)
```

---

### WebAssembly (wasmMain)

**Status:** ❌ Not implemented, experimental Kotlin/Wasm

**Runtime:** WebAssembly

**Available:**
- Kotlin/Wasm stdlib
- Limited kotlinx.* libraries
- wasm-specific APIs

**NOT available:**
- ❌ JVM libraries
- ❌ Full platform.posix
- ❌ Many kotlinx libraries (limited wasm support)

**Constraints:**
- Even more limited than JS
- Experimental Kotlin support
- Limited library ecosystem

**Recommendation:** Focus on web (jsMain) first, wasm later.

---

## Cross-Target Compatibility Matrix

| Feature | Android | JVM/Desktop | iOS | Web (JS) | wasm |
|---------|---------|-------------|-----|----------|------|
| Pure Kotlin | ✅ | ✅ | ✅ | ✅ | ✅ |
| kotlinx.coroutines | ✅ | ✅ | ✅ | ✅ | ⚠️ |
| kotlinx.serialization | ✅ | ✅ | ✅ | ✅ | ⚠️ |
| kotlinx.datetime | ✅ | ✅ | ✅ | ✅ | ⚠️ |
| ktor-client | ✅ | ✅ | ✅ | ✅ | ❌ |
| Jackson JSON | ✅ (jvmAndroid) | ✅ (jvmAndroid) | ❌ | ❌ | ❌ |
| OkHttp | ✅ (jvmAndroid) | ✅ (jvmAndroid) | ❌ | ❌ | ❌ |
| platform.posix | ❌ | ❌ | ✅ | ❌ | ⚠️ |
| Compose Multiplatform | ✅ | ✅ | ⚠️ (experimental) | ⚠️ (experimental) | ❌ |

Legend:
- ✅ Full support
- ⚠️ Limited/experimental
- ❌ Not available

---

## Future-Proofing Recommendations

### For Web Compatibility

**DO:**
- ✅ Use kotlinx.serialization instead of Jackson
- ✅ Use ktor-client instead of OkHttp
- ✅ Use kotlinx.datetime instead of java.time
- ✅ Use suspending functions (non-blocking)
- ✅ Keep business logic in commonMain

**DON'T:**
- ❌ Put JVM libraries in commonMain
- ❌ Use platform.posix for critical features
- ❌ Use blocking I/O
- ❌ Depend on threading (use coroutines)

**Example:**
```kotlin
// ❌ NOT web-compatible
// jvmAndroid
fun parseJson(json: String): Event {
    val mapper = ObjectMapper()  // Jackson - JVM only
    return mapper.readValue(json, Event::class.java)
}

// ✅ Web-compatible
// commonMain
@Serializable
data class Event(...)

fun parseJson(json: String): Event {
    return Json.decodeFromString<Event>(json)  // Works everywhere
}
```

### Current Migration Priorities

**High priority:** (Needed for web)
1. Migrate Jackson → kotlinx.serialization
2. Migrate OkHttp → ktor-client
3. Move business logic to commonMain

**Medium priority:** (Nice to have)
1. Abstract date/time handling → kotlinx.datetime
2. Remove platform.posix usage where possible
3. Use suspending functions over blocking

**Low priority:** (Future optimization)
1. wasm-specific optimizations
2. Platform-specific performance tuning

---

## Platform-Specific Patterns

### Android vs iOS Differences

| Aspect | Android | iOS |
|--------|---------|-----|
| **Activity/ViewController** | Activity | UIViewController |
| **Navigation** | Compose Navigation | UINavigationController |
| **Lifecycle** | onCreate, onResume, etc. | viewDidLoad, viewWillAppear |
| **Permissions** | Runtime permissions | Info.plist + runtime |
| **Crypto** | secp256k1-android | Security framework |
| **Storage** | Room, SharedPreferences | Core Data, UserDefaults |

### Desktop vs Mobile Differences

| Aspect | Desktop | Mobile |
|--------|---------|--------|
| **Navigation** | Sidebar | Bottom nav |
| **Input** | Keyboard + mouse | Touch |
| **Screen** | Large, landscape | Small, portrait |
| **Windows** | Multi-window | Single app |
| **Shortcuts** | Keyboard shortcuts (Ctrl+N) | None |
| **Menus** | MenuBar | Bottom sheets |

---

## Testing Strategy

### Per-Target Testing

**Android:**
- Unit tests: androidTest
- Instrumented: androidInstrumentedTest
- Device/emulator testing

**Desktop:**
- Unit tests: jvmTest
- Manual desktop app testing

**iOS:**
- Unit tests: iosTest (iosArm64Test, etc.)
- Simulator/device testing

**Web (future):**
- Unit tests: jsTest
- Browser testing (Selenium, Playwright)

### Shared Testing

**commonTest:**
- Business logic tests
- Pure Kotlin code
- Works on all platforms

```kotlin
// commonTest
class EventParsingTest {
    @Test
    fun parseTextNoteEvent() {
        // Tests run on all platforms
    }
}
```

---

## Summary

**Current Focus:** Android, JVM/Desktop, iOS (active development)

**Future Considerations:** Web (requires migration from Jackson/OkHttp)

**Key Decision:** Prefer kotlinx.* libraries over JVM-specific libs for future web compatibility.