kmp-boundaries

Kotlin Multiplatform Boundary Design

Core rules for any KMP boundary:

• Keep commonMain semantic — describe what the product needs, not Android/iOS mechanics: currentRegion(), never currentRegionFromAndroidLocale(context).
• Split by capability — Clipboard, ShareSheet, Haptics, Biometrics as separate interfaces, not one Platform god object.
• Keep actuals thin — they translate, they don't decide; a business if/when inside an actual belongs in common, tested with a fake.
• Prefer a common interface + per-platform binding over expect class whenever you need fakes / DI / lifecycle / runtime selection.
• Introduce an intermediate source set (skikoMain, appleMain) only when two platforms genuinely share an actual.

Two boundaries get the most detail below: the Activity-owned platform-UI boundary, and the AGP-9 KMP-library constraints.

Related: android-skills:kmp-ktor (network boundary), compose/references/multiplatform.md (Compose-MP mechanics), android-skills:kotlin-coroutines (scope ownership). For the iOS↔Swift bridge — Kotlin→Swift naming, type widths (Int is 32-bit), SKIE suspend→async / Flow→AsyncSequence, sealed-class exhaustiveness, SwiftUI embedding — load references/ios-interop.md when authoring the iOS-side actual.

Platform-UI bindings are Activity-owned, not Context-owned

The single most common Android boundary mistake: passing applicationContext / LocalContext.current into a binding that actually needs an Activity, then papering over the lifecycle gap with Intent.FLAG_ACTIVITY_NEW_TASK. That flag is a smell — it hides that this is a foreground-UI operation. Hold an Activity instead.

// commonMain — semantic interface; DOCUMENT what `suspend` means
interface ShareSheet {
    /** Launches the system share sheet. Returns when the sheet is PRESENTED — not when the user
     *  completes or cancels. (Otherwise callers write incorrect retry/confirmation logic.) */
    suspend fun shareText(text: String)
}

// androidMain — thin: build the intent and launch it. Activity-owned.
class AndroidShareSheet(private val activity: Activity) : ShareSheet {
    override suspend fun shareText(text: String) {
        activity.startActivity(Intent.createChooser(
            Intent(Intent.ACTION_SEND).setType("text/plain").putExtra(Intent.EXTRA_TEXT, text), null,
        ))
    }
}