Auto-wire Compose ui-tooling for KMP preview rendering (#10) (#12)

On KMP modules Compose `ui-tooling` was not on the render classpath, so the
preview renderer drew a "ComposeViewAdapter" placeholder yet reported status
SUCCESS with the class only in `missingClasses` (which the plugin never parsed)
— so those placeholders were shipped as real thumbnails.

- Auto-add the consumer's own `compose.uiTooling` (their exact Compose version,
  no pinning; androidx `ui-tooling` fallback) to the KMP Android render
  classpath, skipping when it is already declared.
- Parse `missingClasses` and fail the render when `ComposeViewAdapter` is
  missing, so placeholders are rejected and an actionable hint is logged.
- Update the KMP docs + agent guide, and drop the now-redundant
  androidRuntimeClasspath(ui-tooling) lines from the KotlinConf sample.

Author: skydoves

README.md

@@ -274,7 +274,8 @@ module shape and wires the right KSP pass automatically:
 - **KMP + Android**: the graph is extracted from the Android compilation, and every screen still gets a device free
   thumbnail. A shared module has no Android resources of its own, so the renderer reuses the consuming Android app's
   merged Compose Multiplatform resources automatically. Complex Compose Multiplatform screens that Layoutlib can't
-  draw fall back to the Robolectric backend (`renderBackend` defaults to `AUTO`).
+  draw fall back to the Robolectric backend (`renderBackend` defaults to `AUTO`). The plugin auto-adds the Compose
+  `ui-tooling` that device free rendering needs on KMP, so this works with only the plugin applied.
 - **KMP without Android** (iOS/JS/wasm only): extraction runs on the common metadata pass and produces a structure
   only graph: nodes, typed arguments, and transitions, without thumbnails.
 

compose-nav-graph-gradle/src/main/kotlin/com/github/skydoves/navgraph/gradle/LayoutlibRenderTask.kt

@@ -97,6 +97,12 @@ public abstract class LayoutlibRenderTask : DefaultTask() {
   @get:Input
   public abstract val apiLevel: Property<String>
 
+  /** Whether this module is Kotlin Multiplatform — only tailors the actionable hint when the preview host
+   *  ([COMPOSE_VIEW_ADAPTER]) is missing from the render classpath (KMP fixes it on the Android runtime classpath,
+   *  plain Android via `debugImplementation`). */
+  @get:Input
+  public abstract val kmpModule: Property<Boolean>
+
   /** Scratch dir for the generated JSON + raw PNGs + results.json (not the consumed thumbnails). */
   @get:Internal
   public abstract val workDir: DirectoryProperty
@@ -137,8 +143,13 @@ public abstract class LayoutlibRenderTask : DefaultTask() {
           } else {
             add(
               Shot(
-                node.id, pv.previewName, pv.primary, method, "nav${i++}",
-                pv.previewParameters, pv.locale,
+                node.id,
+                pv.previewName,
+                pv.primary,
+                method,
+                "nav${i++}",
+                pv.previewParameters,
+                pv.locale,
               ),
             )
           }
@@ -304,6 +315,13 @@ public abstract class LayoutlibRenderTask : DefaultTask() {
             "missing classes on the render classpath — " +
               "${res.brokenClasses.joinToString()}"
 
+          res.missingClasses.any { it.endsWith("ComposeViewAdapter") } ->
+            "the preview host '$COMPOSE_VIEW_ADAPTER' is missing from the render classpath"
+
+          res.missingClasses.isNotEmpty() ->
+            "missing classes on the render classpath — " +
+              "${res.missingClasses.joinToString()}"
+
           res.problems.isNotEmpty() -> "render problem — ${res.problems.first()}"
 
           res.message != null -> res.message
@@ -317,6 +335,23 @@ public abstract class LayoutlibRenderTask : DefaultTask() {
     }
     indexFile.writeText(index.toString())
 
+    // ComposeViewAdapter (Compose `ui-tooling`) absent from the render classpath ⇒ the renderer emits a placeholder
+    // for EVERY preview (issue #10, typically KMP). navgraph auto-adds ui-tooling; if it couldn't (autoDependencies
+    // = false, or an undetectable Compose setup), tell the consumer exactly what to add.
+    if (byId.values.any { r -> r.missingClasses.any { it.endsWith("ComposeViewAdapter") } }) {
+      val fix = if (kmpModule.getOrElse(false)) {
+        "add it to the Android runtime classpath: " +
+          "androidRuntimeClasspath(compose.uiTooling) (Compose Multiplatform) or " +
+          "androidRuntimeClasspath(\"androidx.compose.ui:ui-tooling:<version>\")"
+      } else {
+        "add debugImplementation(\"androidx.compose.ui:ui-tooling:<version>\")"
+      }
+      logger.warn(
+        "navgraph: previews can't render — the preview host '$COMPOSE_VIEW_ADAPTER' " +
+          "(Compose 'ui-tooling') is missing from the render classpath. $fix",
+      )
+    }
+
     if (ok == 0) {
       logger.warn(
         "navgraph: layoutlib rendered 0/${shots.size} thumbnail(s) in ${elapsed}s ($exitInfo). " +

compose-nav-graph-gradle/src/main/kotlin/com/github/skydoves/navgraph/gradle/LayoutlibResults.kt

@@ -18,6 +18,8 @@ package com.github.skydoves.navgraph.gradle
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.contentOrNull
 import kotlinx.serialization.json.jsonObject
 import java.io.File
 
@@ -31,24 +33,35 @@ internal data class ShotResult(
   val imagePath: String?,
   val status: String?,
   val brokenClasses: List<String>,
+  val missingClasses: List<String>,
   val problems: List<String>,
   val message: String?,
 )
 
+/** The renderer's preview host. When it isn't on the render classpath the renderer emits a gray
+ *  "…ComposeViewAdapter" placeholder yet still reports `status:SUCCESS` (with the class in `missingClasses`), so it
+ *  must be detected explicitly. Absent on KMP modules when Compose `ui-tooling` isn't on the render classpath. */
+internal const val COMPOSE_VIEW_ADAPTER: String = "androidx.compose.ui.tooling.ComposeViewAdapter"
+
 /**
  * Whether [result] is a real, full-fidelity render. The renderer reports `status:SUCCESS` even with an empty
  * error object, so success additionally requires: no broken classes (a placeholder image), no `problems` (e.g.
- * "View measure failed" wrapping a `Resources$NotFoundException` → a 1×1 blank), and a non-empty PNG on disk.
+ * "View measure failed" wrapping a `Resources$NotFoundException` → a 1×1 blank), the preview host
+ * [COMPOSE_VIEW_ADAPTER] not among `missingClasses` (its absence ⇒ a placeholder the renderer mislabels SUCCESS),
+ * and a non-empty PNG on disk.
  */
 internal fun isLayoutlibSuccess(result: ShotResult?, image: File?): Boolean =
   result != null && (result.status == null || result.status == "SUCCESS") &&
     result.brokenClasses.isEmpty() && result.problems.isEmpty() &&
+    result.missingClasses.none { it.endsWith("ComposeViewAdapter") } &&
     image != null && image.isFile && image.length() > 0L
 
 /**
  * Parse the renderer's `results.json` (`screenshotResults[]`) → `previewId` → image + render status. The `error`
  * object is present even on success (status SUCCESS); `brokenClasses` lists classes Layoutlib failed to load
- * (⇒ an error placeholder, not a real render), and `problems` carries non-fatal-looking layout/measure failures.
+ * (⇒ an error placeholder, not a real render), `missingClasses` lists classes the renderer couldn't find at all
+ * (the preview host [COMPOSE_VIEW_ADAPTER] lands here), and `problems` carries non-fatal-looking layout/measure
+ * failures.
  */
 internal fun readLayoutlibResults(file: File): Map<String, ShotResult> {
   if (!file.isFile) return emptyMap()
@@ -65,6 +78,13 @@ internal fun readLayoutlibResults(file: File): Map<String, ShotResult> {
         (it as? JsonObject)?.str("className")
       }
         ?: emptyList()
+    // The renderer reports an absent class (incl. the preview host ComposeViewAdapter) here — as bare strings, NOT
+    // in `brokenClasses` — and still reports SUCCESS with a placeholder image, so this field must be parsed too.
+    val missing =
+      (err?.get("missingClasses") as? JsonArray)?.mapNotNull {
+        (it as? JsonPrimitive)?.contentOrNull ?: (it as? JsonObject)?.str("className")
+      }
+        ?: emptyList()
     val problems = (err?.get("problems") as? JsonArray)?.mapNotNull { p ->
       (p as? JsonObject)?.let {
         it.str("stackTrace")?.lineSequence()?.firstOrNull()?.takeIf { l -> l.isNotBlank() }
@@ -74,6 +94,6 @@ internal fun readLayoutlibResults(file: File): Map<String, ShotResult> {
     val message =
       err?.str("message")?.takeIf { it.isNotBlank() }
         ?: err?.str("stackTrace")?.takeIf { it.isNotBlank() }
-    id to ShotResult(o.str("imagePath"), err?.str("status"), broken, problems, message)
+    id to ShotResult(o.str("imagePath"), err?.str("status"), broken, missing, problems, message)
   }.toMap()
 }

compose-nav-graph-gradle/src/main/kotlin/com/github/skydoves/navgraph/gradle/NavGraphGradlePlugin.kt

@@ -182,6 +182,30 @@ public class NavGraphGradlePlugin : Plugin<Project> {
         }
       }
 
+      // Layoutlib renders `@NavPreview` through `androidx.compose.ui.tooling.ComposeViewAdapter`, in Compose
+      // `ui-tooling`. For KMP+Android the render classpath is the androidMain runtime — `androidRuntimeClasspath`
+      // (new `androidLibrary {}`) / `debugRuntimeClasspath` (legacy `androidTarget()`), see registerLayoutlibRender —
+      // and ui-tooling isn't on it by default, so the renderer emits a "…ComposeViewAdapter" placeholder for every
+      // preview (issue #10). (Plain Android already gets ui-tooling on its variant runtime via the conventional
+      // debugImplementation, so only KMP needs this.) Add the consumer's OWN ui-tooling notation — the exact string
+      // they'd write as `compose.uiTooling`, so version+flavor match their screens (no NoSuchMethodError), honoring
+      // the no-pin rule above. CMP plugin → read it reflectively; else derive from a declared `androidx.compose.ui:ui`.
+      val layoutlib = ext.renderBackend.get() != RenderBackend.ROBOLECTRIC
+      if (kmp && android && layoutlib && ext.renderThumbnails.get()) {
+        val runtimeCfg = listOf("androidRuntimeClasspath", "debugRuntimeClasspath")
+          .firstOrNull { configurations.findByName(it) != null }
+        if (runtimeCfg != null && !uiToolingAlreadyDeclared()) {
+          val notation = composeUiToolingNotation()
+            ?: androidxComposeUiVersion()?.let { "androidx.compose.ui:ui-tooling:$it" }
+          if (notation != null) {
+            dependencies.add(runtimeCfg, notation)
+            logger.info(
+              "navgraph: added '$notation' to '$runtimeCfg' so Layoutlib can render KMP previews.",
+            )
+          }
+        }
+      }
+
       if (!pluginManager.hasPlugin("com.google.devtools.ksp")) {
         logger.error(
           "navgraph: the KSP plugin 'com.google.devtools.ksp' is not applied, so navgraph can't " +
@@ -302,6 +326,53 @@ public class NavGraphGradlePlugin : Plugin<Project> {
     }.getOrNull()
   }
 
+  /** The consumer's own Compose `ui-tooling` dependency notation (`org.jetbrains.compose.ui:ui-tooling:<their CMP
+   *  version>`) — the exact string they'd write as `compose.uiTooling` — read off the `org.jetbrains.compose`
+   *  plugin's `compose` extension reflectively (no Compose-Gradle-plugin compile dependency). Because it carries the
+   *  consumer's own version + flavor, adding it to the render classpath can't skew the Compose API (NoSuchMethodError).
+   *  Null when the JetBrains Compose plugin isn't applied (androidx-Compose consumers use [androidxComposeUiVersion]). */
+  private fun Project.composeUiToolingNotation(): String? {
+    if (!plugins.hasPlugin("org.jetbrains.compose")) return null
+    val compose = extensions.findByName("compose") ?: return null
+    fun Any.uiTooling(): String? =
+      runCatching { javaClass.getMethod("getUiTooling").invoke(this) as? String }.getOrNull()
+    // `compose.uiTooling` is sugar for either ComposeExtension.getUiTooling() or its getDependencies().getUiTooling().
+    return (
+      compose.uiTooling()
+        ?: runCatching {
+          compose.javaClass.getMethod("getDependencies").invoke(compose)
+        }.getOrNull()
+          ?.uiTooling()
+      )?.takeIf(String::isNotBlank)
+  }
+
+  /** The version of an already-DECLARED `androidx.compose.ui:ui`, scanned from the common declarable configs (never
+   *  the runtime classpath we add to, so nothing is resolved). The androidx-Compose fallback for
+   *  [composeUiToolingNotation]. Null when absent or version-less (e.g. pinned only by a BOM). */
+  private fun Project.androidxComposeUiVersion(): String? =
+    sequenceOf("commonMainImplementation", "androidMainImplementation", "implementation")
+      .mapNotNull { configurations.findByName(it) }
+      .flatMap { it.dependencies.asSequence() }
+      .firstOrNull { it.group == "androidx.compose.ui" && it.name == "ui" }
+      ?.version?.takeIf(String::isNotBlank)
+
+  /** Whether Compose `ui-tooling` (either flavor) is already DECLARED on the render/impl configs — checked against
+   *  declared dependencies only (no resolution), so we never add a duplicate/conflicting coordinate when the consumer
+   *  already wired it by hand. */
+  private fun Project.uiToolingAlreadyDeclared(): Boolean = sequenceOf(
+    "androidRuntimeClasspath",
+    "debugRuntimeClasspath",
+    "commonMainImplementation",
+    "androidMainImplementation",
+    "implementation",
+  )
+    .mapNotNull { configurations.findByName(it) }
+    .flatMap { it.dependencies.asSequence() }
+    .any {
+      (it.group == "org.jetbrains.compose.ui" || it.group == "androidx.compose.ui") &&
+        it.name == "ui-tooling"
+    }
+
   /** Registers the pipeline tasks for the detected variant (Android Layoutlib render vs KMP structure-only). */
   private fun wire(
     project: Project,
@@ -851,6 +922,7 @@ public class NavGraphGradlePlugin : Plugin<Project> {
         workDir.set(scratchDir)
         this.thumbsDir.set(thumbsOut)
         previewIndex.set(indexOut)
+        kmpModule.set(kmp)
         dependsOn(kspTaskName, setup.prepare)
 
         if (kmp) {

docs/kotlin-multiplatform.md

@@ -37,6 +37,26 @@ module, the renderer runs against that app's fully merged Compose Multiplatform
 module's, and every transitive dependency's). Your `composeResources` images, fonts, and strings all show up in the
 thumbnails.
 
+!!! note "Compose `ui-tooling` on the render classpath"
+
+    Layoutlib renders a `@Preview` through `androidx.compose.ui.tooling.ComposeViewAdapter`, which ships in Compose
+    `ui-tooling`. On a KMP module the device free render runs against the **Android target's runtime classpath**
+    (`androidRuntimeClasspath`), where `ui-tooling` isn't present by default — without it the renderer emits a
+    placeholder for every preview. The plugin **auto-adds it for you** when the JetBrains Compose plugin
+    (`org.jetbrains.compose`) is applied — the usual Compose Multiplatform case — at your project's own Compose
+    version, so there's nothing to configure. Add it by hand only when auto-wiring can't apply (`autoDependencies =
+    false`, or a module on AndroidX Compose without the `org.jetbrains.compose` plugin):
+
+    ```kotlin
+    dependencies {
+        androidRuntimeClasspath(compose.uiTooling) // Compose Multiplatform
+        // androidx Compose: androidRuntimeClasspath("androidx.compose.ui:ui-tooling:<your compose version>")
+    }
+    ```
+
+    A plain `debugImplementation(…ui-tooling)` is **not** enough on KMP — the render reads the Android *runtime*
+    classpath, not a debug runtime.
+
 Two render backends cooperate (see [`renderBackend`](gradle-plugin/configuration.md#renderbackend)):
 
 - **Layoutlib** (device free, fast): the same engine Android Studio uses for `@Preview`. Most screens render here.

plugin-agent-guides.md

@@ -193,6 +193,27 @@ If a build reports `SDK location not found`, create `local.properties` with `sdk
 Android SDK on this machine (for example `sdk.dir=/Users/<you>/Library/Android/sdk`). The file is
 gitignored.
 
+### 4.7 Kotlin Multiplatform: device free rendering needs Compose ui-tooling
+
+Layoutlib renders a `@Preview` through `androidx.compose.ui.tooling.ComposeViewAdapter`, which ships in Compose
+`ui-tooling`. On a KMP module the device free render runs against the Android target's runtime classpath
+(`androidRuntimeClasspath`), and `ui-tooling` is not on it by default — without it the renderer produces a
+placeholder for every preview. The plugin auto-adds it for you when the JetBrains Compose plugin
+(`org.jetbrains.compose`) is applied — the usual Compose Multiplatform case — so you do nothing. Add it by hand only
+when auto-wiring cannot apply: you set `navgraph { autoDependencies.set(false) }`, or the module uses AndroidX
+Compose directly with no `org.jetbrains.compose` plugin.
+
+```kotlin
+dependencies {
+  androidRuntimeClasspath(compose.uiTooling) // Compose Multiplatform
+  // androidx Compose instead: androidRuntimeClasspath("androidx.compose.ui:ui-tooling:<your compose version>")
+}
+```
+
+If KMP previews come back as placeholders and the build log says `ComposeViewAdapter` is missing from the render
+classpath, this is the fix. A plain `debugImplementation(...ui-tooling)` is not enough on KMP: the render reads the
+Android target's runtime classpath, not a debug runtime.
+
 ---
 
 ## 5. Choose destinations and edges
@@ -358,6 +379,7 @@ Multiplatform modules are excluded from aggregation automatically and always use
 | `@Composable` or `@Preview` does not resolve | the module is not set up for Compose | apply the Compose compiler plugin and add material3 plus the Compose preview tooling |
 | KSP task missing, or an empty `nav-graph.json` | the KSP plugin is not applied, or its version does not match Kotlin | apply `com.google.devtools.ksp` at the version that matches your Kotlin version |
 | thumbnails are blank and all the same size | a preview crashed because it was not DI free, or a runtime class was missing | make every preview DI free; for a Compose Multiplatform app set ROBOLECTRIC |
+| KMP previews are all an identical "ComposeViewAdapter" placeholder | Compose `ui-tooling` is not on the KMP Android render classpath | auto-added for `org.jetbrains.compose` projects; otherwise add `androidRuntimeClasspath(compose.uiTooling)` (see 4.7) |
 | the plugin cannot be resolved | `mavenCentral()` is missing from the plugin repositories | add it to `pluginManagement { repositories }` |
 | Compose Multiplatform screens never render under Layoutlib | Layoutlib cannot draw those screens | set the backend to ROBOLECTRIC |
 | a minSdk merge conflict from a transitive library | a dependency wants a higher minSdk than the consumer | add `tools:overrideLibrary` to the unit test or debug manifest |

samples/sample-kotlinconf/app/shared/build.gradle.kts

@@ -146,11 +146,6 @@ kotlin {
     jvmToolchain(21)
 }
 
-// Android-based preview support
-dependencies {
-    androidRuntimeClasspath(libs.compose.ui.tooling)
-}
-
 compose.resources {
     packageOfResClass = "org.jetbrains.kotlinconf.generated.resources"
 }

samples/sample-kotlinconf/app/ui-components/build.gradle.kts

@@ -86,8 +86,3 @@ compose.resources {
     nameOfResClass = "UiRes"
     packageOfResClass = "org.jetbrains.kotlinconf.ui.generated.resources"
 }
-
-// Android-based preview support
-dependencies {
-    androidRuntimeClasspath(libs.compose.ui.tooling)
-}