initial commit

iosApp/README.md

@@ -0,0 +1,71 @@
+# iOS App (Xcode host)
+
+Kotlin Multiplatform Compose UI runs inside a native iOS shell. Sources here are **Xcode-ready scaffolding**; building requires **macOS + Xcode**.
+
+## App Group migration
+
+| Old (Flutter) | New (KMP) |
+|---|---|
+| `group.com.zhushenwudi.lovelivemusicplayer` | **`group.top.zhushenwudi.llmp`** |
+
+Kotlin writes widget / PiP / CarPlay keys via `WidgetDataWriter` (`shared/.../IosPlatformHooks.kt`). Swift Widget + CarPlay read the same suite.
+
+## Build steps (macOS)
+
+```bash
+cd LoveLiveMusicPlayerKMP
+./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64
+# or iosArm64 for device
+```
+
+1. Open Xcode → **File → New → Project → App** (or add targets to an existing workspace).
+2. Set bundle ID **`top.zhushenwudi.llmp`** (main app).
+3. Copy `iosApp/iosApp/*` into the app target; add `WidgetExtension/*` as a Widget Extension target (`top.zhushenwudi.llmp.widget`).
+4. Link the Gradle-produced **`ComposeApp.framework`** (and embedded **`Shared.framework`** if split).
+5. Signing: enable App Groups `group.top.zhushenwudi.llmp` on **both** app + widget targets (`iosApp.entitlements`, `WidgetExtension.entitlements`).
+6. CarPlay: entitlements include `com.apple.developer.carplay-audio` and `com.apple.developer.playable-content` — **requires Apple Developer approval** before TestFlight/App Store CarPlay works.
+7. Add **`black.mp4`** (minimal black video) to the app bundle for PiP — copy from Flutter `ios/Runner` if present, or generate a 1-frame H.264 clip.
+8. Copy widget image assets from Flutter `ios/HomeWidgetExample/Assets.xcassets` (`logo`, `cd_white`, `cd_black`, favorites).
+
+Entry point:
+
+```swift
+MainViewControllerKt.MainViewController()  // ComposeApp framework
+```
+
+`MainViewController.kt` calls `installIosPlatformServices()` on startup.
+
+## Targets & layout
+
+```
+iosApp/
+  iosApp/
+    AppDelegate.swift          — lifecycle, widget shutdown, notification wiring
+    SceneDelegate.swift        — UIWindow + PiP notification handlers
+    ContentView.swift          — SwiftUI host for Compose UIViewController
+    HostBridge.swift           — share sheet, deep links, widget/CarPlay → host
+    Info.plist
+    iosApp.entitlements
+    CarPlay/CarPlaySceneDelegate.swift
+    pip/                       — desktop lyric PiP (from Flutter Runner/pip)
+  WidgetExtension/             — White/Black home widgets (from Flutter HomeWidgetExample)
+```
+
+## Kotlin ↔ Swift bridge (remaining macOS work)
+
+| Feature | Kotlin side | Swift side | Gap |
+|---|---|---|---|
+| Playback | `PlayerController.ios.kt` AVPlayer + MPRemoteCommandCenter | — | Done in Kotlin |
+| Home widget data | `IosHomeWidgetController` → UserDefaults | Widget reads keys | Wire widget tap → Kotlin player (export callback or observe `llmpHostTogglePlay`) |
+| PiP lyrics | `IosDesktopLyricController` posts notifications | `PipScreenManager` | Done via NotificationCenter |
+| Share | `IosShareBridge` posts `llmpShareRequest` | `HostBridge.presentShare` | Done |
+| Deep link `llmp://` | `IosDeepLinkHandler` | `SceneDelegate` + `HostBridge` | Handle payload in Kotlin UI layer |
+| CarPlay | `IosCarPlayHook.refreshCatalog()` writes JSON | `CarPlaySceneDelegate` | Play/group/menu callbacks need Kotlin export |
+
+## CarPlay note
+
+`CarPlaySceneDelegate` reads `carplay_*` JSON from the App Group. Full parity with Flutter `flutter_carplay` needs exported Kotlin handlers for `onPlay(musicId)` — until then, NotificationCenter events (`llmpHostCarPlayPlay`, etc.) are posted for the host to forward.
+
+## Permissions
+
+Add usage strings in Xcode as needed (camera for QR, photo library, etc.) — see Flutter `ios/Runner/Info.plist` for reference.