Meshtastic-Android/docs/agent-playbooks/kmp-source-set-bridging-playbook.md

KMP Source-Set Bridging Playbook

Use this playbook when introducing platform-specific behavior into shared modules.

1) Decide if expect/actual is needed

Use expect/actual only when a platform API cannot be abstracted cleanly behind an interface passed from app wiring.

• Prefer interface + DI when behavior is already app-owned.
• Prefer expect/actual for small platform primitives and utilities.

Examples in current code:

• core/common/src/commonMain/kotlin/org/meshtastic/core/common/util/CommonUri.kt
• core/common/src/androidMain/kotlin/org/meshtastic/core/common/util/CommonUri.android.kt
• core/repository/src/commonMain/kotlin/org/meshtastic/core/repository/LocationRepository.kt

2) Keep source-set boundaries strict

• commonMain: business logic, shared models, coroutine/Flow orchestration.
• androidMain: Android framework integration (Context, system services, Android SDK).
• app: app bootstrap, DI root inclusion, Activity/service wiring, flavor-specific providers.

3) Resource and UI bridging rules

• Shared strings/resources must come from core:resources.
• Platform/flavor UI implementations should be injected via CompositionLocal from app.

Examples:

• Contract: core/ui/src/commonMain/kotlin/org/meshtastic/core/ui/util/MapViewProvider.kt
• Provider wiring: app/src/main/kotlin/org/meshtastic/app/MainActivity.kt

4) DI and module activation checks

• If a new feature/core module adds Koin annotations, verify it is included by app root module includes.
• App root includes are defined in app/src/main/kotlin/org/meshtastic/app/di/AppKoinModule.kt.

5) Verification checklist

• No Android-only imports in commonMain.
• expect/actual declarations compile across relevant source sets.
• Routing/DI still resolves from app startup (MeshUtilApplication).
• Run verification tasks from docs/agent-playbooks/testing-and-ci-playbook.md appropriate to touched modules.