skill: compose-multiplatform

should_trigger:
  - prompt: "Set up a Kotlin Multiplatform project that shares one Compose UI across Android and iOS."
    why: Core use — shared commonMain @Composables across platforms, the center of the skill.
  - prompt: "My `expect fun` compiles fine but the iOS build complains there's no `actual` — how do I fix it?"
    why: Non-obvious — orphaned expect/actual is a CMP build trap surfacing only on the iOS target.
  - prompt: "How do I embed a native MapKit/SwiftUI view inside my shared Compose screen using UIKitView?"
    why: Non-obvious native interop — the iOS UIKitView factory / injected-interface pattern.
  - prompt: "Compartir la UI entre Android i iOS amb Kotlin, una sola base de codi."
    why: Catalan phrasing for sharing UI across Android/iOS with Kotlin — the core CMP use.
  - prompt: "Where should the platform-specific date formatter live — commonMain or androidMain/iosMain?"
    why: Source-set placement decision — the 'where does this code go' table is the skill's daily question.
  - prompt: "Add a desktop target to my Compose Multiplatform app and package it with jpackage."
    why: Desktop breadth — application {} window + packageDistributionForCurrentOS, JDK 17+ floor.

should_not_trigger:
  - prompt: "Build a native Android-only app with Jetpack Compose and publish it to the Play Store."
    route_to: kotlin-android
    why: Single-platform native Android — no shared multiplatform module, Play Store specifics.
  - prompt: "I'm writing a SwiftUI app in Xcode and need help with App Store code signing."
    route_to: swift-ios
    why: Single-platform native iOS — SwiftUI/Xcode/signing, not shared Kotlin Compose.
  - prompt: "Build a cross-platform mobile UI with Flutter widgets and the flutter CLI."
    route_to: flutter
    why: Dart/Flutter cross-platform, not Kotlin/Compose Multiplatform.
  - prompt: "Create a cross-platform desktop app with a Rust core and a web-tech UI."
    route_to: tauri
    why: Rust desktop shell with web UI, not a Kotlin/CMP shared tree.

capability:
  - scenario: "Scaffold a shared-UI KMP project (a `shared` module plus Android and iOS app hosts), add an `expect`/`actual` `platformName()`, share one @Composable greeting screen across platforms, and embed a native map via `UIKitView` injected through a common interface."
    must_include:
      - "shared module whose commonMain holds the shared @Composable greeting screen"
      - "Compose Multiplatform plugin (org.jetbrains.compose) and Kotlin 2.1.0+ in the build (2.2.x recommended; K2 floor)"
      - "expect fun platformName() in commonMain with an actual in BOTH androidMain and iosMain"
      - "no platform import (android.*, platform.UIKit) leaking into commonMain"
      - "native view embedded via UIKitView fed by an injected common interface, not a raw expect @Composable"
      - "host wiring named: ComposeUIViewController for iOS and setContent for Android"
      - "notes iOS is Stable since CMP 1.8.0 and Web is only Beta (1.9), not production"

# Evals — compose-multiplatform

`cases.yaml` is a trigger/routing harness, not an executable test suite. Run it through the repo's eval runner (or read it by hand) to confirm three things: the `should_trigger` prompts — including the non-obvious orphaned-`expect` case and the Catalan phrasing — actually fire this skill on its description; each `should_not_trigger` prompt routes to the named sibling (`kotlin-android`, `swift-ios`, `flutter`, `tauri`) instead of here; and a real skill response to the `capability` scenario satisfies every item in its `must_include` rubric. There is nothing to compile or execute — judgment is against the description and the SKILL.md body.

# iOS interop — bridge patterns

Read this before writing any iOS-specific Compose interop. iOS is **Stable** in Compose Multiplatform since 1.8.0 (May 2025). Two directions: native views inside shared Compose, and shared Compose inside SwiftUI.

## 1. Native UIKit view inside shared Compose — `UIKitView`

`UIKitView` (and `UIKitViewController` for a whole controller) takes a `factory` lambda that builds the native object. Run on the main thread; size it with the Compose `modifier`.

```kotlin
// iosMain
import androidx.compose.ui.viewinterop.UIKitView
import platform.MapKit.MKMapView

@Composable
fun NativeMap(modifier: Modifier = Modifier) {
    UIKitView(
        factory = { MKMapView() },
        modifier = modifier.fillMaxSize(),
        update = { mapView -> /* mutate mapView on state change */ },
    )
}
```

## 2. Native view factory via a common interface + Koin (preferred)

Keep the shared screen platform-agnostic. Define the contract in `commonMain`, implement it in `iosMain`, inject with Koin. The common `@Composable` never imports `platform.*`.

```kotlin
// commonMain
interface NativeViewFactory {
    @Composable
    fun MapView(modifier: Modifier)
}

@Composable
fun MapScreen(factory: NativeViewFactory = koinInject()) {
    factory.MapView(Modifier.fillMaxSize())
}
```

```kotlin
// iosMain
class IosNativeViewFactory : NativeViewFactory {
    @Composable
    override fun MapView(modifier: Modifier) {
        UIKitView(factory = { MKMapView() }, modifier = modifier)
    }
}
// bind in a platformModule: single<NativeViewFactory> { IosNativeViewFactory() }
```

Why an interface over a raw `expect @Composable`: the Android/desktop targets get their own implementation (or a no-op), and you can fake it in `commonTest`.

## 3. Shared Compose inside a SwiftUI app — `ComposeUIViewController`

Expose a factory from `iosMain`, then wrap it in a SwiftUI `UIViewControllerRepresentable`.

```kotlin
// iosMain
import androidx.compose.ui.window.ComposeUIViewController

fun MainViewController() = ComposeUIViewController { App() }
```

```swift
// iosApp (SwiftUI)
import SwiftUI
import shared

struct ComposeView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        MainViewControllerKt.MainViewController()
    }
    func updateUIViewController(_ vc: UIViewController, context: Context) {}
}

struct ContentView: View {
    var body: some View { ComposeView().ignoresSafeArea(.all) }
}
```

## 4. ViewModel lifecycle on iOS

`androidx.lifecycle.ViewModel` runs in `commonMain`, but iOS has **no built-in `ViewModelStoreOwner`**, so nothing clears the VM for you.

- Inside a Compose-hosted screen, obtain VMs with `koinViewModel { }` (from `koin-compose-viewmodel`) — they are scoped to the Compose nav entry and cleared correctly.
- When a Kotlin VM must be observed from *SwiftUI* (not a Compose host), use **KMP-ObservableViewModel** so SwiftUI sees `@Published`-style updates, and clear it from the SwiftUI view's lifecycle.

## 5. Camera / system APIs

Same pattern: a common `interface` (`CameraController`, `SecureStorage`) with an `iosMain` impl using `platform.AVFoundation` / Keychain, injected via Koin. Reserve raw `expect`/`actual` for tiny, untestable leaves (device name, locale).

# Project setup — Gradle, source sets, module layouts

Full setup for the 2026 default KMP structure. Floors: CMP 1.11.0 (Jetpack Compose 1.11.1), Kotlin 2.1.0+ (2.2.20 recommended), K2 mandatory since CMP 1.8.0, AGP 9.0.

## Version catalog (`gradle/libs.versions.toml`)

```toml
[versions]
kotlin = "2.2.20"
compose = "1.11.0"
agp = "9.0.0"
androidx-lifecycle = "2.9.0"
koin = "4.0.0"
navigation = "2.9.0"

[plugins]
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
composeMultiplatform = { id = "org.jetbrains.compose", version.ref = "compose" }
composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
androidLibrary = { id = "com.android.library", version.ref = "agp" }

[libraries]
lifecycle-viewmodel = { module = "org.jetbrains.androidx.lifecycle:lifecycle-viewmodel", version.ref = "androidx-lifecycle" }
navigation-compose = { module = "org.jetbrains.androidx.navigation:navigation-compose", version.ref = "navigation" }
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-compose-viewmodel = { module = "io.insert-koin:koin-compose-viewmodel", version.ref = "koin" }
```

## `shared/build.gradle.kts`

```kotlin
plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.composeMultiplatform)
    alias(libs.plugins.composeCompiler)
    alias(libs.plugins.androidLibrary)
}

kotlin {
    androidTarget()
    jvm("desktop")
    listOf(iosArm64(), iosSimulatorArm64()).forEach { it.binaries.framework { baseName = "shared" } }
    // wasmJs { browser() }  // Beta — enable to pilot Web only

    sourceSets {
        commonMain.dependencies {
            implementation(compose.runtime)
            implementation(compose.foundation)
            implementation(compose.material3)
            implementation(compose.components.resources)   // generated Res accessors
            implementation(libs.lifecycle.viewmodel)
            implementation(libs.navigation.compose)
            implementation(libs.koin.core)
            implementation(libs.koin.compose.viewmodel)
        }
        androidMain.dependencies { implementation(compose.preview) }
    }
}
```

## Source-set hierarchy

```text
commonMain
├── androidMain
├── desktopMain (jvm)
├── wasmJsMain (Beta)
└── iosMain (intermediate)
    ├── iosArm64
    └── iosSimulatorArm64
```

Use the intermediate `iosMain` for code shared by both iOS targets; only drop to `iosArm64`/`iosSimulatorArm64` for arch-specific cinterop.

## Module-layout variants

- **Mobile-only:** `shared` + `androidApp` + `iosApp`.
- **+ Desktop:** add `desktopApp` (`./gradlew :desktopApp:run`).
- **+ Web (Beta):** add `webApp` with the `wasmJs` target; do not promise parity.
- **Mixed native UI:** split `shared` into **`sharedLogic`** (all platforms, no Compose UI) + **`sharedUI`** (CMP platforms only). Native screens depend on `sharedLogic`; shared screens live in `sharedUI`.
- **+ Server:** add a root **`core`** module consumed by both clients and a JVM/Ktor server.

## Scaffolding

- New project: **kmp.new** or the Kotlin Multiplatform wizard (IntelliJ IDEA 2025.2.2+ / Android Studio Otter 2025.2.1+ with the KMP plugin).
- Existing Android app: Android Studio **Shared Module Template** (added May 2025) adds a KMP `shared` module in place.

## AGP 9.0 migration notes

The new default structure aligns with AGP 9.0. When migrating from the old single `composeApp` module: extract shared `@Composable`s/VMs into a `shared` library module, turn `composeApp` into a thin `androidApp` host that calls `setContent { App() }`, and move the iOS framework export into `shared`.

## Packaging

- Desktop: `./gradlew :desktopApp:packageDistributionForCurrentOS` (dmg/msi/deb). Needs **JDK 17+** for `jpackage`; desktop runtime floor is JDK 11+.
- iOS: archive the `iosApp` Xcode project (App Store signing is `swift-ios` territory).
- Web (Beta): `./gradlew :webApp:wasmJsBrowserDistribution`.

#!/usr/bin/env bash
# verify.sh — static, read-only checks for a Compose Multiplatform / KMP project.
# No Gradle/Xcode run required. Exits 0 on a clean OR empty target (no false failure).
#
# Usage: verify.sh [PROJECT_DIR]   (default: current directory)
#
# Hard failures (exit 1): missing commonMain when KMP is present, orphaned `expect`
# (no matching `actual`), platform import leaking into commonMain.
# Warnings (still exit 0): Kotlin < 2.1.0, missing Compose plugin.

set -uo pipefail

ROOT="${1:-.}"
FAIL=0
WARN=0

note()  { printf '  %s\n' "$1"; }
ok()    { printf 'PASS  %s\n' "$1"; }
bad()   { printf 'FAIL  %s\n' "$1"; FAIL=1; }
warn()  { printf 'WARN  %s\n' "$1"; WARN=1; }

if [ ! -d "$ROOT" ]; then
  echo "verify.sh: '$ROOT' is not a directory" >&2
  exit 2
fi

# Locate commonMain source dirs (KMP marker). Ignore build output dirs.
# Portable to bash 3.2 (macOS) — no mapfile.
COMMON_DIRS=()
while IFS= read -r d; do
  [ -n "$d" ] && COMMON_DIRS+=("$d")
done < <(find "$ROOT" -type d -name commonMain \
  -not -path '*/build/*' -not -path '*/.gradle/*' 2>/dev/null)

# Detect whether this looks like a KMP/CMP project at all.
HAS_KMP=0
if [ "${#COMMON_DIRS[@]}" -gt 0 ]; then HAS_KMP=1; fi
if grep -rqsl 'org.jetbrains.kotlin.multiplatform\|org.jetbrains.compose' \
     "$ROOT" --include='*.kts' --include='*.toml' 2>/dev/null; then HAS_KMP=1; fi

if [ "$HAS_KMP" -eq 0 ]; then
  echo "verify.sh: no KMP/CMP project detected under '$ROOT' — nothing to check."
  exit 0
fi

# 1) commonMain must exist.
if [ "${#COMMON_DIRS[@]}" -eq 0 ]; then
  bad "no commonMain source set found (a shared module is the core of CMP)"
else
  ok "commonMain present (${#COMMON_DIRS[@]} found)"
fi

# 2) Every `expect` in commonMain needs a matching `actual` somewhere.
#    Match on the declared symbol name to catch orphans cheaply.
ORPHANS=0
for cm in ${COMMON_DIRS[@]+"${COMMON_DIRS[@]}"}; do
  # collect expect declarations: fun/class/val/var/object/interface
  while IFS= read -r decl; do
    [ -z "$decl" ] && continue
    name="$decl"
    if grep -rqs "actual[[:space:]].*\b${name}\b" "$ROOT" \
         --include='*.kt' 2>/dev/null \
         | grep -qv "commonMain" 2>/dev/null; then
      :
    elif grep -rs "actual[[:space:]]" "$ROOT" --include='*.kt' 2>/dev/null \
           | grep -q "\b${name}\b"; then
      :
    else
      bad "orphaned expect '${name}' has no matching actual in any platform source set"
      ORPHANS=$((ORPHANS+1))
    fi
  done < <(grep -rhsoE '^[[:space:]]*expect[[:space:]]+(fun|class|val|var|object|interface)[[:space:]]+[A-Za-z_][A-Za-z0-9_]*' \
             "$cm" --include='*.kt' 2>/dev/null \
             | sed -E 's/.*(fun|class|val|var|object|interface)[[:space:]]+([A-Za-z_][A-Za-z0-9_]*).*/\2/')
done
[ "$ORPHANS" -eq 0 ] && ok "no orphaned expect declarations"

# 3) Compose plugin + Kotlin version.
if grep -rqs 'org.jetbrains.compose' "$ROOT" \
     --include='*.kts' --include='*.toml' 2>/dev/null; then
  ok "Compose Multiplatform plugin (org.jetbrains.compose) present"
else
  warn "Compose Multiplatform plugin (org.jetbrains.compose) not found"
fi

KVER=$(grep -rhsoE 'kotlin[^=]*=[[:space:]]*"?([0-9]+\.[0-9]+\.[0-9]+)' \
         "$ROOT" --include='*.toml' --include='*.kts' 2>/dev/null \
         | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -V | tail -1)
if [ -n "$KVER" ]; then
  MAJ=${KVER%%.*}; REST=${KVER#*.}; MIN=${REST%%.*}
  if [ "$MAJ" -gt 2 ] || { [ "$MAJ" -eq 2 ] && [ "$MIN" -ge 1 ]; }; then
    ok "Kotlin $KVER (>= 2.1.0 K2 floor)"
  else
    warn "Kotlin $KVER is below 2.1.0 — CMP 1.8+ requires K2 (Kotlin 2.1.0+); bump to 2.2.x"
  fi
else
  warn "could not detect a Kotlin version in version catalog / build scripts"
fi

# 4) No platform-only imports leaking into commonMain.
FORBIDDEN='^import[[:space:]]+(android\.|androidx\.activity|platform\.UIKit|platform\.Foundation|java\.awt|javax\.swing|org\.w3c\.dom)'
LEAKS=0
for cm in ${COMMON_DIRS[@]+"${COMMON_DIRS[@]}"}; do
  while IFS= read -r line; do
    [ -z "$line" ] && continue
    bad "platform import in commonMain: $line"
    LEAKS=$((LEAKS+1))
  done < <(grep -rhsnE "$FORBIDDEN" "$cm" --include='*.kt' 2>/dev/null)
done
[ "$LEAKS" -eq 0 ] && ok "commonMain free of platform-only imports"

echo "----"
if [ "$FAIL" -ne 0 ]; then
  echo "RESULT: FAIL"
  exit 1
fi
if [ "$WARN" -ne 0 ]; then
  echo "RESULT: PASS (with warnings)"
else
  echo "RESULT: PASS"
fi
echo "(Optional: if ./gradlew exists, ':shared:compileKotlinMetadata' compiles the common metadata.)"
exit 0