Completely rewrite the internals and most of the APIs.

buildSrc/src/main/java/default-android-config.gradle.kts

@@ -23,7 +23,10 @@ configure<BaseExtension> {
     testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
   }
 
-  buildFeatures.compose = true
+  buildFeatures.apply {
+    buildConfig = false
+    compose = true
+  }
 
   composeOptions {
     kotlinCompilerVersion = Versions.kotlin

compose-backstack-viewer/api/compose-backstack-viewer.api

@@ -2,13 +2,6 @@ public final class com/zachklipp/compose/backstack/viewer/BackstackViewerAppKt {
 	public static final fun BackstackViewerApp (Ljava/util/List;Ljava/util/List;Landroidx/compose/runtime/Composer;II)V
 }
 
-public final class com/zachklipp/compose/backstack/viewer/BuildConfig {
-	public static final field BUILD_TYPE Ljava/lang/String;
-	public static final field DEBUG Z
-	public static final field LIBRARY_PACKAGE_NAME Ljava/lang/String;
-	public fun <init> ()V
-}
-
 public final class com/zachklipp/compose/backstack/viewer/ComposableSingletons$AppScreenKt {
 	public static final field INSTANCE Lcom/zachklipp/compose/backstack/viewer/ComposableSingletons$AppScreenKt;
 	public static field lambda-1 Lkotlin/jvm/functions/Function2;

compose-backstack-viewer/build.gradle.kts

@@ -17,6 +17,7 @@ dependencies {
   compileOnly(Dependencies.Compose.tooling)
 
   api(project(":compose-backstack"))
+  api(project(":compose-backstack-xray"))
 
   implementation(Dependencies.AndroidX.appcompat)
   implementation(Dependencies.Compose.icons)

compose-backstack-viewer/src/main/java/com/zachklipp/compose/backstack/viewer/BackstackViewerApp.kt

@@ -42,7 +42,9 @@ import com.zachklipp.compose.backstack.Backstack
 import com.zachklipp.compose.backstack.BackstackTransition
 import com.zachklipp.compose.backstack.BackstackTransition.Crossfade
 import com.zachklipp.compose.backstack.BackstackTransition.Slide
-import com.zachklipp.compose.backstack.InspectionGestureDetector
+import com.zachklipp.compose.backstack.defaultBackstackAnimation
+import com.zachklipp.compose.backstack.rememberTransitionController
+import com.zachklipp.compose.backstack.xray.xrayed
 
 private val DEFAULT_BACKSTACKS = listOf(
     listOf("one"),
@@ -143,31 +145,29 @@ private fun AppControls(model: AppModel) {
 @Composable
 private fun AppScreens(model: AppModel) {
   val animation = if (model.slowAnimations) {
-    remember {
-      TweenSpec<Float>(durationMillis = 2000)
-    }
+    remember { TweenSpec<Float>(durationMillis = 2000) }
   } else null
 
   MaterialTheme(colors = lightColors()) {
-    InspectionGestureDetector(enabled = model.inspectionEnabled) { inspectionParams ->
       Backstack(
         backstack = model.currentBackstack,
-        transition = model.selectedTransition.second,
-        animationBuilder = animation,
+        frameController = rememberTransitionController<String>(
+          transition = model.selectedTransition.second,
+          animationSpec = animation ?: defaultBackstackAnimation(),
+          onTransitionStarting = { from, to, direction ->
+            println(
+              """
+                Transitioning $direction:
+                  from: $from
+                    to: $to
+              """.trimIndent()
+            )
+          },
+          onTransitionFinished = { println("Transition finished.") }
+        ).xrayed(model.inspectionEnabled),
         modifier = Modifier
           .fillMaxSize()
           .border(width = 3.dp, color = Color.Red),
-        inspectionParams = inspectionParams,
-        onTransitionStarting = { from, to, direction ->
-          println(
-            """
-              Transitioning $direction:
-                from: $from
-                  to: $to
-            """.trimIndent()
-          )
-        },
-          onTransitionFinished = { println("Transition finished.") }
       ) { screen ->
         AppScreen(
             name = screen,
@@ -178,7 +178,6 @@ private fun AppScreens(model: AppModel) {
       }
     }
   }
-}
 
 @Composable
 private fun RadioButton(

compose-backstack-xray/README.md

@@ -0,0 +1 @@
+Workaround for Dokka bug. See https://github.com/Kotlin/dokka/issues/1265.

compose-backstack-xray/api/compose-backstack-xray.api

@@ -0,0 +1,4 @@
+public final class com/zachklipp/compose/backstack/xray/XrayControllerKt {
+	public static final fun xrayed (Lcom/zachklipp/compose/backstack/FrameController;ZLandroidx/compose/runtime/Composer;I)Lcom/zachklipp/compose/backstack/FrameController;
+}
+

compose-backstack-xray/build.gradle.kts

@@ -0,0 +1,27 @@
+plugins {
+  id("com.android.library")
+  id("default-android-config")
+  kotlin("android")
+  id("org.jetbrains.dokka")
+  id("publish-to-maven")
+}
+
+android {
+  lintOptions {
+    // Workaround for lint bug.
+    disable += "InvalidFragmentVersionForActivityResult"
+  }
+}
+
+dependencies {
+  api(project(":compose-backstack"))
+
+  implementation(Dependencies.Compose.foundation)
+  implementation(Dependencies.Compose.tooling)
+
+  testImplementation(Dependencies.Test.junit)
+  testImplementation(Dependencies.Test.truth)
+
+  androidTestImplementation(Dependencies.AndroidX.junitExt)
+  androidTestImplementation(Dependencies.Compose.test)
+}

compose-backstack-xray/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

compose-backstack-xray/src/androidTest/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.zachklipp.compose.backstack.xray.test">
+
+    <application>
+        <activity android:name="android.app.Activity" android:theme="@style/TestTheme"/>
+    </application>
+</manifest>

compose-backstack-xray/src/androidTest/res/values/styles.xml

@@ -0,0 +1,9 @@
+<resources>
+    <style name="TestTheme" parent="@android:style/Theme.Material.Light.NoActionBar">
+        <item name="android:windowActionBar">false</item>
+        <item name="android:windowAnimationStyle">@null</item>
+        <item name="android:windowContentOverlay">@null</item>
+        <item name="android:windowFullscreen">true</item>
+        <item name="android:windowNoTitle">true</item>
+    </style>
+</resources>

compose-backstack-xray/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest package="com.zachklipp.compose.backstack.xray" />

compose-backstack-xray/src/main/java/com/zachklipp/compose/backstack/xray/XrayController.kt

@@ -0,0 +1,125 @@
+package com.zachklipp.compose.backstack.xray
+
+import androidx.compose.foundation.gestures.detectTransformGestures
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.derivedStateOf
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.DefaultCameraDistance
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.unit.dp
+import com.zachklipp.compose.backstack.FrameController
+import com.zachklipp.compose.backstack.FrameController.BackstackFrame
+import com.zachklipp.compose.backstack.NoopFrameController
+import kotlin.math.sin
+
+/**
+ * Returns a [FrameController] that wraps this [FrameController] and, when [enabled], displays all
+ * the screens in the backstack in pseudo-3D space. The 3D stack can be navigated via touch
+ * gestures.
+ */
+@Composable fun <T : Any> FrameController<T>.xrayed(enabled: Boolean): FrameController<T> =
+  remember { XrayController<T>() }.also {
+    it.enabled = enabled
+    it.wrappedController = this
+  }
+
+private class XrayController<T : Any> : FrameController<T> {
+
+  var enabled: Boolean by mutableStateOf(false)
+  var wrappedController: FrameController<T> by mutableStateOf(NoopFrameController())
+
+  private var offsetDpX by mutableStateOf(500.dp)
+  private var offsetDpY by mutableStateOf(10.dp)
+  private var rotationX by mutableStateOf(0f)
+  private var rotationY by mutableStateOf(10f)
+  private var scaleFactor by mutableStateOf(.5f)
+  private var alpha by mutableStateOf(.4f)
+  private var overlayAlpha by mutableStateOf(.2f)
+
+  private var activeKeys by mutableStateOf(emptyList<T>())
+
+  private val controlModifier = Modifier.pointerInput(Unit) {
+    detectTransformGestures { _, pan, zoom, _ ->
+      scaleFactor *= zoom
+      // Dragging left-and-right rotates around the vertical Y axis.
+      rotationY += pan.x / 5f
+    }
+  }
+
+  // Use derivedStateOf to cache the mapped list.
+  override val activeFrames by derivedStateOf {
+    if (!enabled) wrappedController.activeFrames else {
+      activeKeys.mapIndexed { index, key ->
+        val modifier = Modifier.modifierForFrame(index, activeKeys.size, 1f)
+        return@mapIndexed BackstackFrame(key, modifier)
+      }
+    }
+  }
+
+  override fun updateBackstack(keys: List<T>) {
+    activeKeys = keys
+    wrappedController.updateBackstack(keys)
+  }
+
+  /**
+   * Calculates a [Modifier] to apply to a screen when in inspection mode.
+   *
+   * The top screen will be drawn without any transformations.
+   * All other screens will be drawn as a 3D stack.
+   */
+  private fun Modifier.modifierForFrame(
+    frameIndex: Int,
+    frameCount: Int,
+    visibility: Float
+  ): Modifier {
+    // Draw the top screen as an overlay so it's clear where touch targets are. Once
+    // compose supports transforming inputs as well as outputs, the top screen can
+    // participate in scaling/rotation too.
+    val isTop = frameIndex == frameCount - 1
+    return graphicsLayer {
+      // drawLayer will scale around the center of the bounds, so we need to offset relative
+      // to that so the entire stack stays centered.
+      val centerOffset =
+        // Don't need to adjust the pivot point if there's only one screen.
+        if (frameCount == 1) 0f
+        // Add -1 + visibility so new screens animate "out of" the previous one.
+        else (frameIndex - 1f + visibility) - frameCount / 3f
+
+      val scale = if (isTop) 1f else scaleFactor
+      scaleX = scale
+      scaleY = scale
+
+      translationX = (if (isTop) 0.dp else {
+        // Adjust by screenCount to squeeze more in as the count increases.
+        val densityFactor = 10f / frameCount
+        // Adjust X offset by sin(rotation) so it looks 3D.
+        val xRotation = sin(Math.toRadians(this@XrayController.rotationY.toDouble())).toFloat()
+        (offsetDpX * centerOffset * scale * densityFactor * xRotation)
+      }).toPx()
+      translationY = (if (isTop) 0.dp else offsetDpY * centerOffset * scale).toPx()
+
+      rotationX = if (isTop) 0f else this@XrayController.rotationX
+      rotationY = if (isTop) 0f else this@XrayController.rotationY
+
+      // This is the only transformation applied to the top screen, so it has some extra logic.
+      alpha = when {
+        // If there's only one screen in the stack, don't transform it at all.
+        frameCount == 1 -> 1f
+        isTop -> overlayAlpha
+        else -> this@XrayController.alpha
+        // Adjust alpha by visibility to make transition less jarring when adding/removing
+        // screens.
+      } * visibility
+
+      cameraDistance = DefaultCameraDistance * 3
+    }.then(
+      // This is the top screen, it's the overlay and holds the control gesture.
+      if (isTop) controlModifier else Modifier
+    )
+  }
+}