From e081c2e36f93063583c507b533808ebf68169c9e Mon Sep 17 00:00:00 2001
From: Ray Ryan <ray@squareup.com>
Date: Fri, 3 Mar 2023 17:23:31 -0800
Subject: [PATCH] Introduces `DialogCollator`

Android notoriously give us no control over the z order of Dialog windows
other than taking care to `show()` them in the right order, so keeping a pile
of windows in sync with a list of `Overlay` rendering models is hard.

We've already solved that for individual instances of `LayeredDialogSessions`
(the delegate that does all of the work for `BodyAndOverlaysContainer`), but
it was still a problem when you nested them, e.g. in the style of the
recently introduced Nested Overlays sample. Also, the solution was kind of
nasty because we would replace any out of order Dialogs with brand new ones,
rather than preserving them by calling `dismiss()` and `show()`.

To fix all that we introduce `internal class DialogCollator`. On each view
update pass, a new `DialogCollator` instance is created by the outermost
`LayeredDialogSessions` and made available to any nested instances via the
`ViewEnvironment`. The shared collator collects a list of all existing
`DialogSession` instances, and a set of `DialogSessionUpdate` functions to be
asynchronously used to update existing instances or create new ones.

Because a `DialogCollator` has complete knowledge of all the windows managed
by the set of nested `LayerDialogSessions` instances it supports, it is able to
ensure that inserts are supported by calling `dismiss()` / `show()` on existing
windows in the sequence needed to reorder them.

One important change to note: our `SavedStateRegistry` code requires that each
window in a set has a unique name, which we derive by applying `Compatible.keyFor` to
its defining `Overlay`. We used to append to that key an `Overlay`'s position in its
`LayeredDialogSessions` list, as a poorly considered hack to simplify showing
several of the same type at once. That approach conflicts with reordering.

With this commit we no longer include the index value in `SavedStateRegistry` keys,
meaning that each `Overlay` shown by a `LayeredDialogSession` must have a unique
key -- `BackStackScreen` has long had a similar requirement. `NamedScreen`
exists to simplify that kind of thing, and in particular can be used to wrap
`ScreenOverlay.content` to meet the new requirement.

Fixes #966
---
 .../poetry/views/MayBeLoadingScreen.kt        |   6 +-
 .../nestedoverlays/NestedOverlaysAppTest.kt   | 121 ++++++--
 .../sample/nestedoverlays/ButtonBar.kt        |  29 +-
 .../nestedoverlays/NestedOverlaysWorkflow.kt  |  45 +--
 .../src/main/res/values/ids.xml               |   4 +
 .../src/main/res/values/strings.xml           |  22 +-
 .../compose/ComposeViewTreeIntegrationTest.kt |  28 +-
 .../ui/container/DialogIntegrationTest.kt     |  36 ++-
 .../androidx/KeyedSavedStateRegistryOwner.kt  |   6 +-
 .../WorkflowSavedStateRegistryAggregator.kt   |  18 +-
 .../workflow1/ui/container/CoveredByModal.kt  |   6 +-
 .../workflow1/ui/container/DialogCollator.kt  | 261 ++++++++++++++++++
 .../workflow1/ui/container/DialogSession.kt   |  69 ++++-
 .../ui/container/LayeredDialogSessions.kt     | 125 ++++-----
 .../container/OverlayDialogFactoryFinder.kt   |   6 +-
 .../container/ScreenOverlayDialogFactory.kt   |   4 +-
 workflow-ui/core-common/api/core-common.api   |   4 +-
 ...ullScreenOverlay.kt => FullScreenModal.kt} |   8 +-
 18 files changed, 630 insertions(+), 168 deletions(-)
 create mode 100644 samples/nested-overlays/src/main/res/values/ids.xml
 create mode 100644 workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogCollator.kt
 rename workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/container/{FullScreenOverlay.kt => FullScreenModal.kt} (77%)

diff --git a/benchmarks/performance-poetry/complex-poetry/src/main/java/com/squareup/benchmarks/performance/complex/poetry/views/MayBeLoadingScreen.kt b/benchmarks/performance-poetry/complex-poetry/src/main/java/com/squareup/benchmarks/performance/complex/poetry/views/MayBeLoadingScreen.kt
index bb894a163a..42a9bee0cf 100644
--- a/benchmarks/performance-poetry/complex-poetry/src/main/java/com/squareup/benchmarks/performance/complex/poetry/views/MayBeLoadingScreen.kt
+++ b/benchmarks/performance-poetry/complex-poetry/src/main/java/com/squareup/benchmarks/performance/complex/poetry/views/MayBeLoadingScreen.kt
@@ -4,11 +4,11 @@ import com.squareup.sample.container.overviewdetail.OverviewDetailScreen
 import com.squareup.sample.container.panel.ScrimScreen
 import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 import com.squareup.workflow1.ui.container.BodyAndOverlaysScreen
-import com.squareup.workflow1.ui.container.FullScreenOverlay
+import com.squareup.workflow1.ui.container.FullScreenModal
 
 @OptIn(WorkflowUiExperimentalApi::class)
 typealias MayBeLoadingScreen =
-  BodyAndOverlaysScreen<ScrimScreen<OverviewDetailScreen>, FullScreenOverlay<LoaderSpinner>>
+  BodyAndOverlaysScreen<ScrimScreen<OverviewDetailScreen>, FullScreenModal<LoaderSpinner>>
 
 @OptIn(WorkflowUiExperimentalApi::class)
 fun MayBeLoadingScreen(
@@ -17,6 +17,6 @@ fun MayBeLoadingScreen(
 ): MayBeLoadingScreen {
   return BodyAndOverlaysScreen(
     ScrimScreen(baseScreen, dimmed = loaders.isNotEmpty()),
-    loaders.map { FullScreenOverlay(it) }
+    loaders.map { FullScreenModal(it) }
   )
 }
diff --git a/samples/nested-overlays/src/androidTest/java/com/squareup/sample/nestedoverlays/NestedOverlaysAppTest.kt b/samples/nested-overlays/src/androidTest/java/com/squareup/sample/nestedoverlays/NestedOverlaysAppTest.kt
index c616d62a14..2dabf7bd89 100644
--- a/samples/nested-overlays/src/androidTest/java/com/squareup/sample/nestedoverlays/NestedOverlaysAppTest.kt
+++ b/samples/nested-overlays/src/androidTest/java/com/squareup/sample/nestedoverlays/NestedOverlaysAppTest.kt
@@ -3,9 +3,12 @@ package com.squareup.sample.nestedoverlays
 import androidx.test.espresso.Espresso.onView
 import androidx.test.espresso.ViewInteraction
 import androidx.test.espresso.action.ViewActions.click
+import androidx.test.espresso.action.ViewActions.typeText
 import androidx.test.espresso.assertion.ViewAssertions.doesNotExist
 import androidx.test.espresso.assertion.ViewAssertions.matches
+import androidx.test.espresso.matcher.RootMatchers.isDialog
 import androidx.test.espresso.matcher.ViewMatchers.isDisplayed
+import androidx.test.espresso.matcher.ViewMatchers.withId
 import androidx.test.espresso.matcher.ViewMatchers.withParent
 import androidx.test.espresso.matcher.ViewMatchers.withParentIndex
 import androidx.test.espresso.matcher.ViewMatchers.withText
@@ -36,17 +39,17 @@ class NestedOverlaysAppTest {
     onBottomCoverEverything().assertDisplayed()
 
     onTopCoverBody().perform(click())
-    onView(withText("Close")).perform(click())
+    onView(withText("❌")).perform(click())
     onTopCoverEverything().perform(click())
-    onView(withText("Close")).perform(click())
+    onView(withText("❌")).perform(click())
 
-    onView(withText("Hide Top Bar")).perform(click())
+    onView(withText("Hide Top")).perform(click())
     onTopCoverBody().assertNotDisplayed()
     onTopCoverEverything().assertNotDisplayed()
     onBottomCoverBody().assertDisplayed()
     onBottomCoverEverything().assertDisplayed()
 
-    onView(withText("Hide Bottom Bar")).perform(click())
+    onView(withText("Hide Bottom")).perform(click())
     onTopCoverBody().assertNotDisplayed()
     onTopCoverEverything().assertNotDisplayed()
     onBottomCoverBody().assertNotDisplayed()
@@ -56,25 +59,109 @@ class NestedOverlaysAppTest {
   // https://github.com/square/workflow-kotlin/issues/966
   @Test fun canInsertDialog() {
     onTopCoverEverything().perform(click())
-    onView(withText("Hide Top Bar")).check(doesNotExist())
-    onView(withText("Cover Body")).perform(click())
 
-    // This line fails due to https://github.com/square/workflow-kotlin/issues/966
-    // onView(withText("Hide Top Bar")).check(doesNotExist())
+    // Cannot see the inner dialog.
+    onView(withText("Hide Top")).inRoot(isDialog()).check(doesNotExist())
+
+    // Click the outer dialog's button to show the inner dialog.
+    onView(withText("Cover Body")).inRoot(isDialog()).perform(click())
+    // Inner was created below outer, so we still can't see it.
+    onView(withText("Hide Top")).inRoot(isDialog()).check(doesNotExist())
+
+    // Close the outer dialog.
+    onView(withText("❌")).inRoot(isDialog()).perform(click())
+    // Now we can see the inner.
+    onView(withText("Hide Top")).inRoot(isDialog()).check(matches(isDisplayed()))
+    // Close it to confirm it really works.
+    onView(withText("❌")).inRoot(isDialog()).perform(click())
+    onTopCoverEverything().check(matches(isDisplayed()))
+  }
+
+  @Test fun canInsertAndRemoveCoveredDialog() {
+    // Show the outer dialog
+    onTopCoverEverything().perform(click())
+    // Show the inner dialog behind it
+    onView(withText("Cover Body")).inRoot(isDialog()).perform(click())
+    // Close the (covered) inner dialog and don't crash. :/
+    onView(withText("Reveal Body")).inRoot(isDialog()).perform(click())
+    // Close the outer dialog
+    onView(withText("❌")).inRoot(isDialog()).perform(click())
+    // We can see the activity window again
+    onTopCoverEverything().check(matches(isDisplayed()))
+  }
+
+  @Test fun whenReorderingViewStateIsPreserved() {
+    // Show the outer dialog
+    onTopCoverEverything().perform(click())
+
+    // Type something on it
+    onView(withId(R.id.button_bar_text)).inRoot(isDialog())
+      .perform(typeText("banana"))
+
+    // Click the outer dialog's button to show the inner dialog.
+    onView(withText("Cover Body")).inRoot(isDialog()).perform(click())
+
+    // The original outer dialog was destroyed and replaced.
+    // Check that the text we entered made it to the replacement dialog via view state.
+    onView(withId(R.id.button_bar_text)).inRoot(isDialog())
+      .check(matches(withText("banana")))
+  }
+
+  // https://github.com/square/workflow-kotlin/issues/314
+  @Test fun whenBodyAndOverlaysStopsBeingRenderedDialogsAreDismissed() {
+    onBottomCoverBody().perform(click())
+    onView(withText("💣")).inRoot(isDialog()).perform(click())
+
+    onBottomCoverBody().check(doesNotExist())
+    onView(withText("Reset")).perform(click())
 
-    // Should continue to close the top sheet and assert that the inner sheet is visible.
+    onBottomCoverBody().perform(click())
+    onView(withText("💣")).inRoot(isDialog()).check(matches(isDisplayed()))
   }
 
-  // So far can't express this in Espresso. Considering move to Maestro
-  // @Test fun canClickPastInnerWindow() {
-  //   onView(allOf(withText("Cover Everything"), withParent(withParentIndex(0))))
+  // So far can't express this in Espresso, because it refuses to work
+  // w/a root that lacks window focus. Considering move to Maestro.
+  // In the meantime I'd like to keep this commented out block around
+  // as a reminder.
+
+  // @Test fun canCoverDialogAndRemoveItWhileCovered() {
+  //   // Show the inner dialog
+  //   onTopCoverBody().perform(click())
+  //
+  //   lateinit var activity: Activity
+  //   scenarioRule.scenario.onActivity { activity = it }
+  //
+  //   // Show the outer dialog
+  //   onTopCoverEverything()
+  //     .inRoot(
+  //       allOf(
+  //         withDecorView(Matchers.`is`(activity.window.decorView)),
+  //         Matchers.not(hasWindowFocus())
+  //       )
+  //     )
   //     .perform(click())
   //
-  //   scenario.onActivity { activity ->
-  //     onView(allOf(withText("Cover Everything"), withParent(withParentIndex(0))))
-  //       .inRoot(withDecorView(not(`is`(activity.window.decorView))))
-  //       .perform(click())
-  //   }
+  //   // Close the (covered) inner dialog
+  //   onView(withText("Reveal Body")).inRoot(isDialog()).perform(click())
+  //   // Close the outer dialog
+  //   onView(withText("❌")).inRoot(isDialog()).perform(click())
+  //   // We can see the activity window again
+  //   onTopCoverEverything().check(matches(isDisplayed()))
+  // }
+  //
+  // /**
+  //  * Like the private (why?) `hasWindowFocus` method in Espresso, but
+  //  * built into a `Matcher<Root>` rather than a `Matcher<View>` (since
+  //  * that was our only use case).
+  //  */
+  // fun hasWindowFocus(): Matcher<Root> {
+  //   return withDecorView(object : TypeSafeMatcher<View>() {
+  //     override fun describeTo(description: Description) {
+  //       description.appendText("has window focus (Square fork)")
+  //     }
+  //
+  //     override fun matchesSafely(item: View): Boolean = item.hasWindowFocus()
+  //   })
   // }
 
   private fun ViewInteraction.assertNotDisplayed() {
diff --git a/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/ButtonBar.kt b/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/ButtonBar.kt
index 37f9f7726f..3f44b75377 100644
--- a/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/ButtonBar.kt
+++ b/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/ButtonBar.kt
@@ -2,6 +2,9 @@ package com.squareup.sample.nestedoverlays
 
 import android.graphics.drawable.ColorDrawable
 import android.view.Gravity
+import android.view.View.GONE
+import android.view.View.VISIBLE
+import android.widget.EditText
 import android.widget.LinearLayout
 import androidx.annotation.ColorRes
 import androidx.annotation.StringRes
@@ -21,23 +24,33 @@ data class Button(
 class ButtonBar(
   vararg buttons: Button?,
   @ColorRes val color: Int = -1,
+  val showEditText: Boolean = false,
 ) : AndroidScreen<ButtonBar> {
   private val buttons: List<Button> = buttons.filterNotNull().toList()
 
   override val viewFactory =
     ScreenViewFactory.fromCode<ButtonBar> { _, initialEnvironment, context, _ ->
       LinearLayout(context).let { view ->
-        @Suppress("DEPRECATION")
-        if (color > -1) view.background = ColorDrawable(view.resources.getColor(color))
+        // Child 0 is always an EditText, which may or may not be visible.
+        val editText = EditText(context)
+        editText.id = R.id.button_bar_text
+        view.addView(editText)
 
         view.gravity = Gravity.CENTER
 
-        ScreenViewHolder(initialEnvironment, view) { bar, _ ->
-          val existing = view.childCount
+        ScreenViewHolder(initialEnvironment, view) { newBar, _ ->
+          @Suppress("DEPRECATION")
+          view.background =
+            if (newBar.color > -1) ColorDrawable(view.resources.getColor(newBar.color)) else null
 
-          bar.buttons.forEachIndexed { index, button ->
-            val buttonView = if (index < existing) {
-              view[index] as ButtonView
+          editText.visibility = if (newBar.showEditText) VISIBLE else GONE
+
+          // After the EditText, an arbitrary number of ButtonView.
+          val existingButtonCount = view.childCount - 1
+
+          newBar.buttons.forEachIndexed { index, button ->
+            val buttonView = if (index < existingButtonCount) {
+              view[index + 1] as ButtonView
             } else {
               ButtonView(context).also { view.addView(it) }
             }
@@ -46,7 +59,7 @@ class ButtonBar(
               setOnClickListener { button.onClick() }
             }
           }
-          for (i in bar.buttons.size until view.childCount) view.removeViewAt(i)
+          for (i in newBar.buttons.size + 1 until view.childCount) view.removeViewAt(i)
         }
       }
     }
diff --git a/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/NestedOverlaysWorkflow.kt b/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/NestedOverlaysWorkflow.kt
index 837faea903..54f8d879a4 100644
--- a/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/NestedOverlaysWorkflow.kt
+++ b/samples/nested-overlays/src/main/java/com/squareup/sample/nestedoverlays/NestedOverlaysWorkflow.kt
@@ -8,20 +8,15 @@ import com.squareup.workflow1.StatefulWorkflow
 import com.squareup.workflow1.ui.Screen
 import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 import com.squareup.workflow1.ui.container.BodyAndOverlaysScreen
-import com.squareup.workflow1.ui.container.FullScreenOverlay
-import com.squareup.workflow1.ui.container.Overlay
+import com.squareup.workflow1.ui.container.FullScreenModal
 
-typealias NestedOverlaysRendering = BodyAndOverlaysScreen<
-  TopAndBottomBarsScreen<BodyAndOverlaysScreen<Screen, Overlay>>,
-  Overlay
-  >
-
-object NestedOverlaysWorkflow : StatefulWorkflow<Unit, State, Nothing, NestedOverlaysRendering>() {
+object NestedOverlaysWorkflow : StatefulWorkflow<Unit, State, Nothing, Screen>() {
   data class State(
     val showTopBar: Boolean = true,
     val showBottomBar: Boolean = true,
     val showInnerSheet: Boolean = false,
-    val showOuterSheet: Boolean = false
+    val showOuterSheet: Boolean = false,
+    val nuked: Boolean = false
   )
 
   override fun initialState(
@@ -33,28 +28,33 @@ object NestedOverlaysWorkflow : StatefulWorkflow<Unit, State, Nothing, NestedOve
     renderProps: Unit,
     renderState: State,
     context: RenderContext
-  ): NestedOverlaysRendering {
+  ): Screen {
+    if (renderState.nuked) {
+      return ButtonBar(Button(R.string.reset, context.eventHandler { state = State() }))
+    }
+
     val toggleTopBarButton = Button(
-      name = if (renderState.showTopBar) R.string.HIDE_TOP else R.string.SHOW_TOP,
+      name = if (renderState.showTopBar) R.string.hide_top else R.string.show_top,
       onClick = context.eventHandler { state = state.copy(showTopBar = !state.showTopBar) }
     )
 
     val toggleBottomBarButton = Button(
-      name = if (renderState.showBottomBar) R.string.HIDE_BOTTOM else R.string.SHOW_BOTTOM,
+      name = if (renderState.showBottomBar) R.string.hide_bottom else R.string.show_bottom,
       onClick = context.eventHandler { state = state.copy(showBottomBar = !state.showBottomBar) }
     )
 
     val outerSheet = if (!renderState.showOuterSheet) {
       null
     } else {
-      FullScreenOverlay(
+      FullScreenModal(
         ButtonBar(
           Button(
-            name = R.string.CLOSE,
+            name = R.string.close,
             onClick = context.eventHandler { state = state.copy(showOuterSheet = false) }
           ),
           context.toggleInnerSheetButton(renderState),
-          color = android.R.color.holo_green_light
+          color = android.R.color.holo_green_light,
+          showEditText = true
         )
       )
     }
@@ -62,15 +62,20 @@ object NestedOverlaysWorkflow : StatefulWorkflow<Unit, State, Nothing, NestedOve
     val innerSheet = if (!renderState.showInnerSheet) {
       null
     } else {
-      FullScreenOverlay(
+      FullScreenModal(
         ButtonBar(
           Button(
-            name = R.string.CLOSE,
+            name = R.string.close,
             onClick = context.eventHandler { state = state.copy(showInnerSheet = false) }
           ),
           toggleTopBarButton,
           toggleBottomBarButton,
-          color = android.R.color.holo_red_light
+          Button(
+            name = R.string.nuke,
+            onClick = context.eventHandler { state = State(nuked = true) }
+          ),
+          color = android.R.color.holo_red_light,
+          showEditText = true
         )
       )
     }
@@ -98,14 +103,14 @@ object NestedOverlaysWorkflow : StatefulWorkflow<Unit, State, Nothing, NestedOve
   ) = ButtonBar(
     toggleInnerSheetButton(renderState),
     Button(
-      name = R.string.COVER_ALL,
+      name = R.string.cover_all,
       onClick = eventHandler { state = state.copy(showOuterSheet = true) }
     )
   )
 
   private fun RenderContext.toggleInnerSheetButton(renderState: State) =
     Button(
-      name = if (renderState.showInnerSheet) R.string.REVEAL_BODY else R.string.COVER_BODY,
+      name = if (renderState.showInnerSheet) R.string.reveal_body else R.string.cover_body,
       onClick = eventHandler {
         state = state.copy(showInnerSheet = !state.showInnerSheet)
       }
diff --git a/samples/nested-overlays/src/main/res/values/ids.xml b/samples/nested-overlays/src/main/res/values/ids.xml
new file mode 100644
index 0000000000..e1c29a5adc
--- /dev/null
+++ b/samples/nested-overlays/src/main/res/values/ids.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <item name="button_bar_text" type="id"/>
+</resources>
diff --git a/samples/nested-overlays/src/main/res/values/strings.xml b/samples/nested-overlays/src/main/res/values/strings.xml
index 5323fbc978..e792114e02 100644
--- a/samples/nested-overlays/src/main/res/values/strings.xml
+++ b/samples/nested-overlays/src/main/res/values/strings.xml
@@ -1,13 +1,15 @@
 <resources>
+  <string name="body">body</string>
+  <string name="bottom">bottom</string>
+  <string name="close">❌</string>
+  <string name="cover_all">Cover Everything</string>
+  <string name="cover_body">Cover Body</string>
+  <string name="hide_bottom">Hide Bottom</string>
+  <string name="hide_top">Hide Top</string>
+  <string name="nuke">💣</string>
+  <string name="reset">Reset</string>
+  <string name="reveal_body">Reveal Body</string>
+  <string name="show_bottom">Show Bottom Bar</string>
+  <string name="show_top">Show Top Bar</string>
   <string name="app_name">Nested Overlays</string>
-  <string name="BODY">body</string>
-  <string name="COVER_BODY">Cover Body</string>
-  <string name="BOTTOM">bottom</string>
-  <string name="HIDE_BOTTOM">Hide Bottom Bar</string>
-  <string name="SHOW_BOTTOM">Show Bottom Bar</string>
-  <string name="HIDE_TOP">Hide Top Bar</string>
-  <string name="SHOW_TOP">Show Top Bar</string>
-  <string name="REVEAL_BODY">Reveal Body</string>
-  <string name="COVER_ALL">Cover Everything</string>
-  <string name="CLOSE">Close</string>
 </resources>
diff --git a/workflow-ui/compose/src/androidTest/java/com/squareup/workflow1/ui/compose/ComposeViewTreeIntegrationTest.kt b/workflow-ui/compose/src/androidTest/java/com/squareup/workflow1/ui/compose/ComposeViewTreeIntegrationTest.kt
index 2898e8ea31..333ab33559 100644
--- a/workflow-ui/compose/src/androidTest/java/com/squareup/workflow1/ui/compose/ComposeViewTreeIntegrationTest.kt
+++ b/workflow-ui/compose/src/androidTest/java/com/squareup/workflow1/ui/compose/ComposeViewTreeIntegrationTest.kt
@@ -26,6 +26,7 @@ import androidx.compose.ui.test.performClick
 import com.google.common.truth.Truth.assertThat
 import com.squareup.workflow1.ui.AndroidScreen
 import com.squareup.workflow1.ui.Compatible
+import com.squareup.workflow1.ui.NamedScreen
 import com.squareup.workflow1.ui.Screen
 import com.squareup.workflow1.ui.ScreenViewFactory
 import com.squareup.workflow1.ui.ScreenViewHolder
@@ -390,7 +391,7 @@ internal class ComposeViewTreeIntegrationTest {
   }
 
   @Test fun composition_is_restored_in_multiple_modals_after_config_change() {
-    val firstScreen: Screen = TestComposeRendering(compatibilityKey = "key") {
+    val firstScreen: Screen = TestComposeRendering(compatibilityKey = "0") {
       var counter by rememberSaveable { mutableStateOf(0) }
       BasicText(
         "Counter: $counter",
@@ -400,9 +401,7 @@ internal class ComposeViewTreeIntegrationTest {
       )
     }
 
-    // Use the same compatibility key – these screens are in different modals, so they won't
-    // conflict.
-    val secondScreen: Screen = TestComposeRendering(compatibilityKey = "key") {
+    val secondScreen: Screen = TestComposeRendering(compatibilityKey = "1") {
       var counter by rememberSaveable { mutableStateOf(0) }
       BasicText(
         "Counter2: $counter",
@@ -412,9 +411,7 @@ internal class ComposeViewTreeIntegrationTest {
       )
     }
 
-    // Use the same compatibility key – these screens are in different modals, so they won't
-    // conflict.
-    val thirdScreen: Screen = TestComposeRendering(compatibilityKey = "key") {
+    val thirdScreen: Screen = TestComposeRendering(compatibilityKey = "2") {
       var counter by rememberSaveable { mutableStateOf(0) }
       BasicText(
         "Counter3: $counter",
@@ -492,7 +489,10 @@ internal class ComposeViewTreeIntegrationTest {
         BodyAndOverlaysScreen(
           EmptyRendering,
           TestModal(BackStackScreen(EmptyRendering, layer0Screen0)),
-          TestModal(BackStackScreen(EmptyRendering, layer1Screen0)),
+          // A SavedStateRegistry is set up for each modal. Each registry needs a unique name,
+          // and these names default to their `Compatible.keyFor` value. When we show two
+          // of the same type at the same time, we need to give them unique names.
+          TestModal(NamedScreen(BackStackScreen(EmptyRendering, layer1Screen0), "another")),
         )
       )
     }
@@ -515,7 +515,12 @@ internal class ComposeViewTreeIntegrationTest {
         BodyAndOverlaysScreen(
           EmptyRendering,
           TestModal(BackStackScreen(EmptyRendering, layer0Screen0, layer0Screen1)),
-          TestModal(BackStackScreen(EmptyRendering, layer1Screen0, layer1Screen1)),
+          // A SavedStateRegistry is set up for each modal. Each registry needs a unique name,
+          // and these names default to their `Compatible.keyFor` value. When we show two
+          // of the same type at the same time, we need to give them unique names.
+          TestModal(
+            NamedScreen(BackStackScreen(EmptyRendering, layer1Screen0, layer1Screen1), "another")
+          ),
         )
       )
     }
@@ -552,7 +557,10 @@ internal class ComposeViewTreeIntegrationTest {
         BodyAndOverlaysScreen(
           EmptyRendering,
           TestModal(BackStackScreen(EmptyRendering, layer0Screen0)),
-          TestModal(BackStackScreen(EmptyRendering, layer1Screen0)),
+          // A SavedStateRegistry is set up for each modal. Each registry needs a unique name,
+          // and these names default to their `Compatible.keyFor` value. When we show two
+          // of the same type at the same time, we need to give them unique names.
+          TestModal(NamedScreen(BackStackScreen(EmptyRendering, layer1Screen0), "another")),
         )
       )
     }
diff --git a/workflow-ui/core-android/src/androidTest/java/com/squareup/workflow1/ui/container/DialogIntegrationTest.kt b/workflow-ui/core-android/src/androidTest/java/com/squareup/workflow1/ui/container/DialogIntegrationTest.kt
index fcc20fe9ad..b256af0711 100644
--- a/workflow-ui/core-android/src/androidTest/java/com/squareup/workflow1/ui/container/DialogIntegrationTest.kt
+++ b/workflow-ui/core-android/src/androidTest/java/com/squareup/workflow1/ui/container/DialogIntegrationTest.kt
@@ -114,24 +114,52 @@ internal class DialogIntegrationTest {
     }
   }
 
+  // Some of us are stuck with integration setups that cache
+  // ViewEnvironment when they really shouldn't. Make sure `DialogCollator`
+  // is reusable.
+  @Test fun toleratesCachedDialogCollator() {
+    val stickyEnvironment = ViewEnvironment.EMPTY + (DialogCollator to DialogCollator())
+
+    val oneDialog = BodyAndOverlaysScreen(
+      ContentRendering("body"),
+      DialogRendering("dialog", ContentRendering("content"))
+    ).withEnvironment(stickyEnvironment)
+
+    lateinit var root: WorkflowLayout
+
+    scenario.onActivity { activity ->
+      root = WorkflowLayout(activity)
+      root.show(oneDialog)
+    }
+
+    val dialog2 = DialogRendering("dialog2", ContentRendering("content2"))
+    val twoDialogs = BodyAndOverlaysScreen(
+      ContentRendering("body"),
+      DialogRendering("dialog1", ContentRendering("content1")),
+      dialog2
+    ).withEnvironment(stickyEnvironment)
+
+    scenario.onActivity {
+      root.show(twoDialogs)
+      val lastOverlay = latestDialog?.overlay
+      assertThat(lastOverlay).isEqualTo(dialog2)
+    }
+  }
+
   @Test fun closingAnUpstreamDialogPreservesDownstream() {
     val body = ContentRendering("body")
     val overlayZero = DialogRendering("dialog0", ContentRendering("content"))
     val overlayOne = DialogRendering("dialog1", ContentRendering("content"))
-
     val showingBoth = BodyAndOverlaysScreen(body, overlayZero, overlayOne)
     lateinit var root: WorkflowLayout
     lateinit var originalDialogOne: Dialog
-
     scenario.onActivity { activity ->
       root = WorkflowLayout(activity)
       root.show(showingBoth)
       originalDialogOne = latestDialog!!
       assertThat(originalDialogOne.overlayOrNull).isSameInstanceAs(overlayOne)
     }
-
     val closedZero = BodyAndOverlaysScreen(body, overlayOne)
-
     scenario.onActivity {
       root.show(closedZero)
       assertThat(latestDialog!!.overlayOrNull).isSameInstanceAs(overlayOne)
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/KeyedSavedStateRegistryOwner.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/KeyedSavedStateRegistryOwner.kt
index dc2bb3346d..9b01eff68c 100644
--- a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/KeyedSavedStateRegistryOwner.kt
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/KeyedSavedStateRegistryOwner.kt
@@ -25,10 +25,14 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
  */
 @WorkflowUiExperimentalApi
 internal class KeyedSavedStateRegistryOwner internal constructor(
-  public val key: String,
+  val key: String,
   lifecycleOwner: LifecycleOwner
 ) : SavedStateRegistryOwner, LifecycleOwner by lifecycleOwner {
   internal val controller: SavedStateRegistryController = SavedStateRegistryController.create(this)
   override val savedStateRegistry: SavedStateRegistry
     get() = controller.savedStateRegistry
+
+  override fun toString(): String {
+    return "KeyedSavedStateRegistryOwner(key='$key', controller=$controller)"
+  }
 }
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/WorkflowSavedStateRegistryAggregator.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/WorkflowSavedStateRegistryAggregator.kt
index 429a4d2f51..05cfeb81f3 100644
--- a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/WorkflowSavedStateRegistryAggregator.kt
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/androidx/WorkflowSavedStateRegistryAggregator.kt
@@ -99,11 +99,17 @@ public class WorkflowSavedStateRegistryAggregator {
       // We don't care about the lifecycle anymore, we've got what we need.
       source.lifecycle.removeObserver(this)
 
-      // These properties are guaranteed to be non-null because this observer is only registered
-      // while attached, and these properties are always non-null while attached.
-      restoreFromBundle(
-        parentRegistryOwner!!.savedStateRegistry.consumeRestoredStateForKey(parentKey!!)
-      )
+      val restoredState: Bundle?
+      try {
+        restoredState =
+          // These properties are guaranteed to be non-null because this observer is only registered
+          // while attached, and these properties are always non-null while attached.
+          parentRegistryOwner!!.savedStateRegistry.consumeRestoredStateForKey(parentKey!!)
+      } catch (e: IllegalStateException) {
+        // Exception thrown by SavedStateRegistryOwner is pretty useless.
+        throw IllegalStateException("Error consuming $parentKey from $parentRegistryOwner", e)
+      }
+      restoreFromBundle(restoredState)
     }
   }
 
@@ -235,7 +241,7 @@ public class WorkflowSavedStateRegistryAggregator {
    */
   public fun saveAndPruneChildRegistryOwner(key: String) {
     children.remove(key)?.let { saveIfOwnerReady(it) }
-      ?: throw IllegalArgumentException("No such child: $key")
+      ?: throw IllegalArgumentException("No such child: $key, on parent $parentKey")
   }
 
   private fun saveIfOwnerReady(child: KeyedSavedStateRegistryOwner) {
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/CoveredByModal.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/CoveredByModal.kt
index 163d5779cc..d805a44d1a 100644
--- a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/CoveredByModal.kt
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/CoveredByModal.kt
@@ -5,7 +5,11 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 
 /**
  * True in views managed by [BodyAndOverlaysScreen] when their events are being blocked
- * by a [ModalOverlay].
+ * by a [ModalOverlay], giving covered views a signal that they should ignore events.
+ * This is necessary so that we can ignore events that happen in the time between calls
+ * to `Dialog.show()` and the actual appearance of the Dialog window.
+ *
+ * https://stackoverflow.com/questions/2886407/dealing-with-rapid-tapping-on-buttons
  */
 @WorkflowUiExperimentalApi
 internal object CoveredByModal : ViewEnvironmentKey<Boolean>(type = Boolean::class) {
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogCollator.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogCollator.kt
new file mode 100644
index 0000000000..4f70d98030
--- /dev/null
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogCollator.kt
@@ -0,0 +1,261 @@
+package com.squareup.workflow1.ui.container
+
+import com.squareup.workflow1.ui.ViewEnvironment
+import com.squareup.workflow1.ui.ViewEnvironmentKey
+import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
+import com.squareup.workflow1.ui.container.DialogCollator.IdAndSessions
+import java.util.UUID
+
+/**
+ * Helper provided to [DialogSessionUpdate.doUpdate] to give access
+ * to an existing [DialogSession] able to display a given [Overlay].
+ */
+@WorkflowUiExperimentalApi
+internal fun interface OldSessionFinder {
+  /**
+   * Returns the existing [DialogSession] that can be [updated][DialogSession.show]
+   * to display [overlay], or `null` if there is none.
+   */
+  fun find(overlay: Overlay): DialogSession?
+}
+
+/**
+ * Provided by [LayeredDialogSessions] to [DialogCollator.scheduleUpdates].
+ * Knows how to create a [DialogSession] for [overlay], or to update an existing
+ * one.
+ *
+ * @param overlay rendering to be shown in a new or existing Dialog window
+ *
+ * @param doUpdate function to create or update a [DialogSession] to display
+ * [overlay]. Provided with an [OldSessionFinder] instance that gives access to the
+ * existing session, if any, and a `covered: Boolean` param that indicates
+ * if there is a [ModalOverlay] above [overlay]
+ */
+@WorkflowUiExperimentalApi
+internal class DialogSessionUpdate(
+  val overlay: Overlay,
+  val doUpdate: (
+    oldSessionFinder: OldSessionFinder,
+    covered: Boolean
+  ) -> DialogSession
+)
+
+/**
+ * Init method called at the start of [LayeredDialogSessions.update].
+ * Ensures that there is a single [DialogCollator] instance shared by
+ * an entire recursive hierarchy of [LayeredDialogSessions] for each
+ * update pass.
+ *
+ * Each call to [establishDialogCollator] must be matched with a call to
+ * [DialogCollator.scheduleUpdates]. This balance lets us know when a set of recursive
+ * [LayeredDialogSessions.update] calls is complete, so that we can manage
+ * the entire set of [Dialog][android.app.Dialog] windows.
+ *
+ * Returns a new [ViewEnvironment] with a [DialogCollator]
+ * value if none was found, otherwise returns self. Either way,
+ * the given [existingSessions] set is added to the pool
+ * that will be processed by the new or existing [DialogCollator].
+ *
+ * @param id unique runtime-only id used to pair calls to [establishDialogCollator]
+ * and [DialogCollator.scheduleUpdates]
+ *
+ * @param existingSessions [DialogSession] instances that were running before the pending update
+ */
+@WorkflowUiExperimentalApi
+internal fun ViewEnvironment.establishDialogCollator(
+  id: UUID,
+  existingSessions: List<DialogSession>
+): ViewEnvironment {
+  val collatorOrNull = map[DialogCollator]
+  val collator = (collatorOrNull as? DialogCollator) ?: DialogCollator()
+
+  collator.expectedUpdates++
+  collator.establishedSessions.add(
+    IdAndSessions(id, existingSessions)
+  )
+
+  return if (collatorOrNull == null) this + (DialogCollator to collator) else this
+}
+
+/**
+ * Singleton resource shared by a recursive set of [LayeredDialogSessions], used to
+ * ensure that the windows they manage are stacked in the correct order and stay that
+ * way across updates.
+ *
+ * Android notoriously doesn't give us any control over the z order of windows
+ * other than taking care to [show][android.app.Dialog.show] them in the right
+ * order, so keeping a pile of windows in sync with the shifting order of the
+ * defining list of [Overlay] rendering models is hard. [DialogCollator] manages
+ * that process.
+ *
+ * When a workflow UI tree is updated (that is, each time
+ * [WorkflowLayout][com.squareup.workflow1.ui.WorkflowLayout.show] is called), a shared
+ * [DialogCollator] is used across nested [LayeredDialogSessions] to coordinate their work.
+ * Specifically, a [DialogCollator] instance is put in place in the [ViewEnvironment]
+ * when [LayeredDialogSessions.update] calls [ViewEnvironment.establishDialogCollator].
+ * The [LayeredDialogSessions] then loads its [DialogCollator] with functions to create or update
+ * managed [Dialog][android.app.Dialog] instances, by calling [scheduleUpdates].
+ *
+ * Any recursive calls to [LayeredDialogSessions.update] receive the same [DialogCollator]
+ * when they make their own calls to [ViewEnvironment.establishDialogCollator], and so
+ * enqueue their updates in the same place.
+ *
+ * When control returns to the outermost [scheduleUpdates] stack frame, all of the
+ * updates that were enqueued with the shared [DialogCollator] are executed in a single
+ * pass. Because this [DialogCollator] has complete knowledge of the existing stack
+ * of `Dialog` windows and all updates, it is able to decide if any existing instances need to be
+ * [dismissed][android.app.Dialog.dismiss] and [re-shown][android.app.Dialog.show]
+ * to keep them in the correct order.
+ */
+@WorkflowUiExperimentalApi
+internal class DialogCollator {
+  /**
+   * Set of [DialogSession] instances registered by a specific [LayeredDialogSessions],
+   * via [establishDialogCollator].
+   */
+  internal class IdAndSessions(
+    val id: UUID,
+    val sessions: List<DialogSession>
+  )
+
+  /**
+   * The [IdAndSessions] sets accumulated by all calls to [ViewEnvironment.establishDialogCollator].
+   * Can be flattened to the current list of [DialogSession]s / `Dialog`s.
+   */
+  internal val establishedSessions = mutableListOf<IdAndSessions>()
+
+  /**
+   * The number of calls that have been made to [ViewEnvironment.establishDialogCollator].
+   * Decremented when [scheduleUpdates] is called. When this returns to `0`,
+   * [doUpdate] is called.
+   */
+  internal var expectedUpdates = 0
+
+  /**
+   * Set of [DialogSessionUpdate] functions registered by a specific [LayeredDialogSessions],
+   * via [scheduleUpdates].
+   */
+  private class IdAndUpdates(
+    val id: UUID,
+    val updates: List<DialogSessionUpdate>,
+    val onSessionsUpdated: (List<DialogSession>) -> Unit
+  )
+
+  /**
+   * The [IdAndUpdates] instances accumulated by all calls to [scheduleUpdates].
+   * Can be flattened to the list of [Overlay] representing the
+   * `Dialog` windows that will be in place when we're done updating.
+   */
+  private val allUpdates = mutableListOf<IdAndUpdates>()
+
+  /**
+   * Follow up call to [ViewEnvironment.establishDialogCollator]. Adds a set
+   * of update operations to be applied to the [DialogSession] set provided
+   * to that call. The updates are not applied until a matching call
+   * to [scheduleUpdates] has been received for each call to [establishDialogCollator].
+   *
+   * @param id unique runtime-only id used to pair calls to [establishDialogCollator]
+   * and [DialogCollator.scheduleUpdates]
+   *
+   * @param updates list of [DialogSessionUpdate] to be applied to the [DialogSession]
+   * previously registered with [establishedSessions]. This is a list of
+   * [Overlay]s to show, each paired with a function to create or update a
+   * [DialogSession] to show it.
+   *
+   * @param onSessionsUpdated called immediately after the given [updates] are applied.
+   * Provides the updated list of [DialogSession] that should replace those that
+   * were provided to [establishDialogCollator].
+   */
+  internal fun scheduleUpdates(
+    id: UUID,
+    updates: List<DialogSessionUpdate>,
+    onSessionsUpdated: (List<DialogSession>) -> Unit
+  ) {
+    check(expectedUpdates > 0) {
+      "Each update() call must be preceded by a call to ViewEnvironment.establishDialogCollator, " +
+        "but expectedUpdates is $expectedUpdates"
+    }
+
+    this.allUpdates.add(IdAndUpdates(id, updates, onSessionsUpdated))
+    if (--expectedUpdates == 0) doUpdate()
+  }
+
+  private fun doUpdate() {
+    // Flatten establishedSessions into an Iterator across the existing sessions from
+    // bottom to top, each paired with the id of the LayeredDialogSessions that registered it.
+    val establishedSessionsIterator: Iterator<Pair<UUID, DialogSession>> =
+      establishedSessions.asReversed()
+        .asSequence()
+        .flatMap { it.sessions.map { session -> Pair(it.id, session) } }
+        .iterator()
+
+    // Collects members of establishedSessions that are dismissed because they
+    // are out of order, so that we can try to show them again.
+    val hiddenSessions = mutableListOf<Pair<UUID, DialogSession>>()
+
+    // Z index of the uppermost ModalOverlay.
+    val topModalIndex = allUpdates.asSequence()
+      .flatMap { it.updates.asSequence().map { update -> update.overlay } }
+      .indexOfLast { it is ModalOverlay }
+
+    // Z index of the dialog session being updated.
+    var updatingSessionIndex = 0
+
+    allUpdates.forEach { idAndUpdates ->
+      val updatedSessions = mutableListOf<DialogSession>()
+
+      // We're building an object that the next LayeredDialogSessions can use to
+      // find an existing dialog that matches a given Overlay. Any
+      // incompatible dialog that we skip on the way to find a match is dismissed.
+      // If we later find a match for one of the dismissed dialogs, it is re-shown --
+      // which moves it to the front, ensuring the correct Z order.
+      val oldSessionFinder = OldSessionFinder { overlay ->
+
+        // First we iterate through the existing windows to find one that belongs
+        // to this group and matches the overlay.
+        while (establishedSessionsIterator.hasNext()) {
+          val (id, session) = establishedSessionsIterator.next()
+          if (idAndUpdates.id == id && session.canShow(overlay)) return@OldSessionFinder session
+
+          // Can't update this session from this Overlay. Dismiss it (via Dialog.dismiss
+          // under the hood), but hold on to it in case it can except a later Overlay.
+          session.setVisible(false)
+          hiddenSessions.add(Pair(id, session))
+          continue
+        }
+
+        // There are no established windows left. See if any of the ones that were
+        // dismissed because they were out of order can be shown again.
+        return@OldSessionFinder hiddenSessions.indexOfFirst { (hiddenId, dialogSession) ->
+          idAndUpdates.id == hiddenId && dialogSession.canShow(overlay)
+        }.takeUnless { it == -1 }?.let { compatibleIndex ->
+          val restoredSession = hiddenSessions.removeAt(compatibleIndex).second
+          restoredSession.apply { setVisible(true) }
+        }
+      }
+
+      idAndUpdates.updates.forEach { update ->
+        val covered = updatingSessionIndex < topModalIndex
+        updatedSessions += update.doUpdate(oldSessionFinder, covered)
+        updatingSessionIndex++
+      }
+      idAndUpdates.onSessionsUpdated(updatedSessions)
+    }
+
+    establishedSessions.clear()
+    allUpdates.clear()
+  }
+
+  override fun toString(): String {
+    return "DialogCollator(" +
+      "updates=$allUpdates, " +
+      "establishedSessions=$establishedSessions, " +
+      "expectedUpdates=$expectedUpdates" +
+      ")"
+  }
+
+  companion object : ViewEnvironmentKey<DialogCollator>(DialogCollator::class) {
+    override val default: DialogCollator
+      get() = error("Call ViewEnvironment.establishDialogCollator first.")
+  }
+}
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogSession.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogSession.kt
index 0eadc4e45f..d5fa1a0400 100644
--- a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogSession.kt
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/DialogSession.kt
@@ -15,6 +15,7 @@ import androidx.core.view.doOnDetach
 import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
 import com.squareup.workflow1.ui.Compatible
+import com.squareup.workflow1.ui.ViewEnvironment
 import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 import com.squareup.workflow1.ui.androidx.WorkflowLifecycleOwner
 import com.squareup.workflow1.ui.androidx.WorkflowSavedStateRegistryAggregator
@@ -26,7 +27,7 @@ import com.squareup.workflow1.ui.androidx.WorkflowSavedStateRegistryAggregator
  */
 @WorkflowUiExperimentalApi
 internal class DialogSession(
-  index: Int,
+  private val stateRegistryAggregator: WorkflowSavedStateRegistryAggregator,
   initialOverlay: Overlay,
   holder: OverlayDialogHolder<Overlay>
 ) {
@@ -55,8 +56,8 @@ internal class DialogSession(
    *   is initialized before it is shown
    * - It is dangerous to call `decorView` before `Dialog.show`.
    *
-   * Fix is that [OverlayDialogHolder.canShow] does not update `Dialog.overlay` if
-   * peekDecorView is null. Which means we have to bootstrap it into place when
+   * Fix is that [OverlayDialogHolder.canShow] does not read `Dialog.overlay` if
+   * peekDecorView is null. Which means we have to bootstrap it into place after
    * we call `Dialog.show`.
    *
    * We keep this nullable pointer to the very first [Overlay] so that we can put it
@@ -67,7 +68,7 @@ internal class DialogSession(
   /**
    * Wrap the given dialog holder to maintain [allowEvents] on each update.
    */
-  val holder: OverlayDialogHolder<Overlay> = OverlayDialogHolder(
+  private val holder: OverlayDialogHolder<Overlay> = OverlayDialogHolder(
     holder.environment,
     holder.dialog,
     holder.onUpdateBounds,
@@ -77,15 +78,26 @@ internal class DialogSession(
     holder.show(overlay, environment)
   }
 
-  val savedStateRegistryKey = Compatible.keyFor(initialOverlay, index.toString())
+  /**
+   * Key used for view state persistence, both classic ([save]) and
+   * newfangled ([stateRegistryAggregator]).
+   */
+  val savedStateKey = Compatible.keyFor(initialOverlay)
 
   private val KeyEvent.isBackPress: Boolean
     get() = (keyCode == KEYCODE_BACK || keyCode == KEYCODE_ESCAPE) && action == ACTION_UP
 
-  fun showDialog(
+  fun initAndShowDialog(
     parentLifecycleOwner: LifecycleOwner,
-    stateRegistryAggregator: WorkflowSavedStateRegistryAggregator
+    initialEnvironment: ViewEnvironment
   ) {
+    // Prime the pump, make the first call to OverlayDialogHolder.show to update
+    // the newly created Dialog to reflect the first rendering. Note that below
+    // in this method we also have to apply initialOverlay to the Dialog itself
+    // _after_ it is shown for the first time. See kdoc on initialOverlay for sordid
+    // details.
+    holder.show(initialOverlay!!, initialEnvironment)
+
     val dialog = holder.dialog
 
     dialog.window?.let { window ->
@@ -115,6 +127,8 @@ internal class DialogSession(
     }
 
     dialog.show()
+    // Fix for https://github.com/square/workflow-kotlin/issues/863, can't set this
+    // until after show() is called. See kdoc in initialOverlay.
     initialOverlay?.let {
       dialog.overlay = it
       initialOverlay = null
@@ -133,7 +147,7 @@ internal class DialogSession(
       // so views in each dialog layer don't clash with other layers.
       stateRegistryAggregator.installChildRegistryOwnerOn(
         view = decorView,
-        key = savedStateRegistryKey
+        key = savedStateKey
       )
 
       decorView.doOnAttach {
@@ -159,11 +173,40 @@ internal class DialogSession(
     }
   }
 
+  fun canShow(overlay: Overlay): Boolean = holder.canShow(overlay)
+
+  fun show(
+    overlay: Overlay,
+    environment: ViewEnvironment
+  ) {
+    check(initialOverlay == null) {
+      "initAndShowDialog() must be called first. show() is for updates only."
+    }
+    holder.show(overlay, environment)
+  }
+
+  /**
+   * Used by [DialogCollator] to *temporarily* [dismiss][android.app.Dialog.dismiss] or
+   * [show][android.app.Dialog.show] an existing [DialogSession] without triggering the
+   * other side effects of [dismiss], as a tool to update its z-index.
+   */
+  fun setVisible(visible: Boolean) {
+    if (visible) {
+      holder.dialog.show()
+    } else {
+      holder.dialog.dismiss()
+    }
+  }
+
+  /**
+   * We are never going to use this `Dialog` again. Tear down our lifecycle hooks
+   * and dismiss it.
+   */
   fun dismiss() {
-    // The dialog's views are about to be detached, and when that happens we want to transition
-    // the dialog view's lifecycle to a terminal state even though the parent is probably still
-    // alive.
     with(holder.dialog) {
+      // The dialog's views are about to be detached, and when that happens we want to transition
+      // the dialog view's lifecycle to a terminal state even though the parent is probably still
+      // alive.
       window?.decorView?.let(WorkflowLifecycleOwner::get)?.destroyOnDetach()
       dismiss()
     }
@@ -171,11 +214,11 @@ internal class DialogSession(
 
   internal fun save(): KeyAndBundle? {
     val saved = holder.dialog.window?.saveHierarchyState() ?: return null
-    return KeyAndBundle(savedStateRegistryKey, saved)
+    return KeyAndBundle(savedStateKey, saved)
   }
 
   internal fun restore(keyAndBundle: KeyAndBundle) {
-    if (savedStateRegistryKey == keyAndBundle.compatibilityKey) {
+    if (savedStateKey == keyAndBundle.compatibilityKey) {
       holder.dialog.window?.restoreHierarchyState(keyAndBundle.bundle)
     }
   }
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/LayeredDialogSessions.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/LayeredDialogSessions.kt
index 6065c3e3c5..5172fe6ad4 100644
--- a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/LayeredDialogSessions.kt
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/LayeredDialogSessions.kt
@@ -23,12 +23,14 @@ import com.squareup.workflow1.ui.androidx.WorkflowSavedStateRegistryAggregator
 import com.squareup.workflow1.ui.container.DialogSession.KeyAndBundle
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
+import java.util.UUID
 
 /**
  * Does the bulk of the work of maintaining a set of [Dialog][android.app.Dialog]s
- * to reflect lists of [Overlay]. Can be used to create custom [Overlay]-based
- * layouts if [BodyAndOverlaysScreen] or the default [BodyAndOverlaysContainer] bound
- * to it are too restrictive.
+ * to reflect lists of [Overlay], constrained to cover only the bounds of a single
+ * [View]. This is the work modeled by [BodyAndOverlaysScreen] and executed
+ * by [BodyAndOverlaysContainer]. This class is public to allow implementation of
+ * custom [Overlay]-based layouts if [BodyAndOverlaysContainer] is too restrictive.
  *
  * - Provides an [allowEvents] field that reflects the presence or absence of Dialogs driven
  *   by [ModalOverlay]
@@ -40,11 +42,16 @@ import kotlinx.coroutines.flow.StateFlow
  *   both for classic [View.onSaveInstanceState] and
  *   Jetpack [SavedStateRegistry][androidx.savedstate.SavedStateRegistry].
  *
+ * Supports recursion (e.g. nesting a smaller [BodyAndOverlaysScreen] in the
+ * [body][BodyAndOverlaysScreen.body] field of another) by sharing a single [DialogCollator]
+ * instance across multiple instances of [LayeredDialogSessions]. See [DialogCollator] for
+ * details.
+ *
  * ## Lifecycle of a managed [Dialog][android.app.Dialog]
  *
  * When [update] is called with an [Overlay] that is not [Compatible] with an
- * existing Dialog at the same index, the appropriate [OverlayDialogFactory] instance
- * is fetched from the [ViewEnvironment]. That factory builds (but does not
+ * existing Dialog, the appropriate [OverlayDialogFactory] instance is fetched from
+ * the [ViewEnvironment]. That factory builds (but does not
  * [show][android.app.Dialog.show]) a new Dialog, wrapped in an [OverlayDialogHolder].
  * The holder in turn is held by a [DialogSession] instance. There is a 1:1:1 relationship
  * between the Dialog, the [OverlayDialogHolder] which can [update it][OverlayDialogHolder.show],
@@ -67,7 +74,7 @@ import kotlinx.coroutines.flow.StateFlow
  *
  * The [DialogSession] is maintained (and its two flavors of View state are recorded
  * as prompted by the Android runtime) so long as [update] is called with a
- * [Compatible] [Overlay] rendering in the same position.
+ * [Compatible] [Overlay] rendering.
  *
  * When [update] is called without a matching [Overlay], or the
  * [parent Lifecycle][getParentLifecycleOwner] ends, the [DialogSession] ends,
@@ -92,6 +99,12 @@ public class LayeredDialogSessions private constructor(
   private val cancelEvents: () -> Unit,
   private val getParentLifecycleOwner: () -> LifecycleOwner
 ) {
+  /**
+   * My unique ID in the [DialogCollator] shared with any other [LayeredDialogSessions]
+   * with a shared ancestor.
+   */
+  private val idInCollator = UUID.randomUUID()
+
   /**
    * Provides a new `SavedStateRegistryOwner` for each dialog,
    * which will save to the `SavedStateRegistryOwner` of this container view.
@@ -117,71 +130,62 @@ public class LayeredDialogSessions private constructor(
    * can use [ViewTreeLifecycleOwner][androidx.lifecycle.ViewTreeLifecycleOwner] as
    * usual.
    *
-   * @param updateBase function to be called before updating the dialogs.
-   * The [ViewEnvironment] passed to that function is enhanced with a [CoveredByModal]
-   * as appropriate, to ensure proper behavior of [allowEvents] of nested containers.
+   * @param updateBase function to be called before updating the dialogs, presumably
+   * to update the base view beneath the dialogs. The [ViewEnvironment] passed to the
+   * given function is enhanced with a [CoveredByModal] as appropriate, to ensure proper
+   * behavior of [allowEvents] of nested containers.
    */
   public fun update(
     overlays: List<Overlay>,
     viewEnvironment: ViewEnvironment,
     updateBase: (environment: ViewEnvironment) -> Unit
   ) {
-    val modalIndex = overlays.indexOfFirst { it is ModalOverlay }
-    val showingModals = modalIndex > -1
+    // Set up a ViewEnvironment with the single DialogCollator instance that handles
+    // this entire view hierarchy. See that class for details.
+    val envWithDialogManager =
+      viewEnvironment.establishDialogCollator(idInCollator, sessions)
+    val collator = envWithDialogManager[DialogCollator]
 
+    val showingModals = overlays.any { it is ModalOverlay }
     allowEvents = !showingModals
 
     updateBase(
-      if (showingModals) viewEnvironment + (CoveredByModal to true) else viewEnvironment
+      if (showingModals) envWithDialogManager + (CoveredByModal to true) else envWithDialogManager
     )
 
-    val envPlusBounds = viewEnvironment + OverlayArea(bounds)
-
-    // On each update we build a new list of the running dialogs, both the
-    // existing ones and any new ones. We need this so that we can compare
-    // it with the previous list, and see what dialogs close.
-    val updatedSessions = mutableListOf<DialogSession>()
-    val oldSessionIterator = sessions.iterator()
-
-    for ((i, overlay) in overlays.withIndex()) {
-      val covered = i < modalIndex
-      val dialogEnv = if (covered) envPlusBounds + (CoveredByModal to true) else envPlusBounds
-
-      // We can't insert new dialogs in front of existing ones b/c there is no
-      // API to control z order of windows. But we can at least close lower dialogs
-      // that disappear from the list while preserving those that remain -- that is,
-      // updating [overlay1, overlay2] to [overlay2, overlay3] should preserve the
-      // dialog that was already created for overlay2. So for each entry in overlays,
-      // we advance to the first compatible old session, if any, and reuse it.
-      // The ones that we skip will be discarded and dismissed.
-
-      val oldSessionOrNull = oldSessionIterator.firstCompatible(overlay)
-
-      updatedSessions += oldSessionOrNull?.also { it.holder.show(overlay, dialogEnv) }
-        ?: overlay.toDialogFactory(dialogEnv)
-          .buildDialog(overlay, dialogEnv, context)
-          .let { holder ->
-            holder.onUpdateBounds?.let { updateBounds ->
-              holder.dialog.maintainBounds(holder.environment) { b -> updateBounds(b) }
+    val envPlusBounds = envWithDialogManager + OverlayArea(bounds)
+    val updates = mutableListOf<DialogSessionUpdate>()
+    overlays.forEach { overlay ->
+      updates += DialogSessionUpdate(overlay) { oldSessions, covered ->
+        val dialogEnv = if (covered) envPlusBounds + (CoveredByModal to true) else envPlusBounds
+        val oldSessionOrNull = oldSessions.find(overlay)
+
+        oldSessionOrNull
+          // If there is already a matching session, it may have been hidden b/c out of order.
+          ?.also { session -> session.show(overlay, dialogEnv) }
+          // This is a new Overlay, create and show its Dialog.
+          ?: overlay.toDialogFactory(dialogEnv)
+            .buildDialog(overlay, dialogEnv, context)
+            .let { holder ->
+              holder.onUpdateBounds?.let { updateBounds ->
+                holder.dialog.maintainBounds(holder.environment) { b -> updateBounds(b) }
+              }
+
+              DialogSession(stateRegistryAggregator, overlay, holder).also { newSession ->
+                newSession.initAndShowDialog(getParentLifecycleOwner(), dialogEnv)
+              }
             }
-
-            DialogSession(i, overlay, holder).also { newSession ->
-              // Prime the pump, make the first call to OverlayDialog.show to update
-              // the new dialog to reflect the first rendering.
-              newSession.holder.show(overlay, dialogEnv)
-              // And now start the lifecycle machinery and show the dialog window itself.
-              newSession.showDialog(getParentLifecycleOwner(), stateRegistryAggregator)
-            }
-          }
+      }
+    }
+    collator.scheduleUpdates(idInCollator, updates) { updatedSessions ->
+      (sessions - updatedSessions.toSet()).forEach { it.dismiss() }
+      // Drop the state registries for any keys that no longer exist since the last save.
+      // Or really, drop everything except the remaining ones.
+      stateRegistryAggregator.pruneAllChildRegistryOwnersExcept(
+        keysToKeep = updatedSessions.map { it.savedStateKey }
+      )
+      sessions = updatedSessions
     }
-
-    (sessions - updatedSessions.toSet()).forEach { it.dismiss() }
-    // Drop the state registries for any keys that no longer exist since the last save.
-    // Or really, drop everything except the remaining ones.
-    stateRegistryAggregator.pruneAllChildRegistryOwnersExcept(
-      keysToKeep = updatedSessions.map { it.savedStateRegistryKey }
-    )
-    sessions = updatedSessions
   }
 
   /**
@@ -348,11 +352,4 @@ public class LayeredDialogSessions private constructor(
       }
     }
   }
-
-  private fun Iterator<DialogSession>.firstCompatible(overlay: Overlay): DialogSession? {
-    while (hasNext()) {
-      next().takeIf { it.holder.canShow(overlay) }?.let { return it }
-    }
-    return null
-  }
 }
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/OverlayDialogFactoryFinder.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/OverlayDialogFactoryFinder.kt
index d0b357db02..81e91a0325 100644
--- a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/OverlayDialogFactoryFinder.kt
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/OverlayDialogFactoryFinder.kt
@@ -10,7 +10,7 @@ import kotlin.reflect.KClass
 /**
  * [ViewEnvironment] service object used by [Overlay.toDialogFactory] to find the right
  * [OverlayDialogFactory]. The default implementation makes [AndroidOverlay]
- * work, and provides default bindings for [AlertOverlay] and [FullScreenOverlay].
+ * work, and provides default bindings for [AlertOverlay] and [FullScreenModal].
  */
 @WorkflowUiExperimentalApi
 public interface OverlayDialogFactoryFinder {
@@ -26,8 +26,8 @@ public interface OverlayDialogFactoryFinder {
       ?: (rendering as? AlertOverlay)?.let {
         AlertOverlayDialogFactory() as OverlayDialogFactory<OverlayT>
       }
-      ?: (rendering as? FullScreenOverlay<Screen>)?.let {
-        ScreenOverlayDialogFactory(FullScreenOverlay::class as KClass<FullScreenOverlay<Screen>>)
+      ?: (rendering as? FullScreenModal<Screen>)?.let {
+        ScreenOverlayDialogFactory(FullScreenModal::class as KClass<FullScreenModal<Screen>>)
           as OverlayDialogFactory<OverlayT>
       }
       ?: throw IllegalArgumentException(
diff --git a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/ScreenOverlayDialogFactory.kt b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/ScreenOverlayDialogFactory.kt
index 7f2705ac80..60faad54bb 100644
--- a/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/ScreenOverlayDialogFactory.kt
+++ b/workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/container/ScreenOverlayDialogFactory.kt
@@ -19,9 +19,9 @@ import kotlin.reflect.KClass
 
 /**
  * Extensible base implementation of [OverlayDialogFactory] for [ScreenOverlay]
- * types. Also serves as the default factory for [FullScreenOverlay].
+ * types. Also serves as the default factory for [FullScreenModal].
  * (Use a custom [OverlayDialogFactoryFinder] to customize the presentation
- * of [FullScreenOverlay].)
+ * of [FullScreenModal].)
  *
  * Dialogs built by this class are compatible with
  * [View.backPressedHandler][com.squareup.workflow1.ui.backPressedHandler],
diff --git a/workflow-ui/core-common/api/core-common.api b/workflow-ui/core-common/api/core-common.api
index 9e843889c1..65670738d9 100644
--- a/workflow-ui/core-common/api/core-common.api
+++ b/workflow-ui/core-common/api/core-common.api
@@ -248,7 +248,7 @@ public final class com/squareup/workflow1/ui/container/EnvironmentScreenKt {
 	public static final fun withRegistry (Lcom/squareup/workflow1/ui/Screen;Lcom/squareup/workflow1/ui/ViewRegistry;)Lcom/squareup/workflow1/ui/container/EnvironmentScreen;
 }
 
-public final class com/squareup/workflow1/ui/container/FullScreenOverlay : com/squareup/workflow1/ui/container/ScreenOverlay {
+public final class com/squareup/workflow1/ui/container/FullScreenModal : com/squareup/workflow1/ui/container/ModalOverlay, com/squareup/workflow1/ui/container/ScreenOverlay {
 	public fun <init> (Lcom/squareup/workflow1/ui/Screen;)V
 	public fun asSequence ()Lkotlin/sequences/Sequence;
 	public fun getCompatibilityKey ()Ljava/lang/String;
@@ -256,7 +256,7 @@ public final class com/squareup/workflow1/ui/container/FullScreenOverlay : com/s
 	public synthetic fun getContent ()Ljava/lang/Object;
 	public synthetic fun map (Lkotlin/jvm/functions/Function1;)Lcom/squareup/workflow1/ui/Container;
 	public synthetic fun map (Lkotlin/jvm/functions/Function1;)Lcom/squareup/workflow1/ui/Wrapper;
-	public fun map (Lkotlin/jvm/functions/Function1;)Lcom/squareup/workflow1/ui/container/FullScreenOverlay;
+	public fun map (Lkotlin/jvm/functions/Function1;)Lcom/squareup/workflow1/ui/container/FullScreenModal;
 	public synthetic fun map (Lkotlin/jvm/functions/Function1;)Lcom/squareup/workflow1/ui/container/ScreenOverlay;
 }
 
diff --git a/workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/container/FullScreenOverlay.kt b/workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/container/FullScreenModal.kt
similarity index 77%
rename from workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/container/FullScreenOverlay.kt
rename to workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/container/FullScreenModal.kt
index a6b8f41bf7..24f62a9a6c 100644
--- a/workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/container/FullScreenOverlay.kt
+++ b/workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/container/FullScreenModal.kt
@@ -9,9 +9,9 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
  * UI kits are expected to provide handling for this class by default.
  */
 @WorkflowUiExperimentalApi
-public class FullScreenOverlay<C : Screen>(
+public class FullScreenModal<C : Screen>(
   public override val content: C
-) : ScreenOverlay<C> {
-  override fun <D : Screen> map(transform: (C) -> D): FullScreenOverlay<D> =
-    FullScreenOverlay(transform(content))
+) : ScreenOverlay<C>, ModalOverlay {
+  override fun <D : Screen> map(transform: (C) -> D): FullScreenModal<D> =
+    FullScreenModal(transform(content))
 }