@apexnative/navigation 1.0.0-alpha.2 → 1.0.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.0.0-alpha.3](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.2...v1.0.0-alpha.3) (2026-10-22)
+
+
+### Features
+
+* **android:** system stack transitions, an opaque default screen background and predictive back ([#26](https://github.com/apexnative/navigation/issues/26)) ([9f28969](https://github.com/apexnative/navigation/commit/9f28969a30a8902c1512cd2a24c3ddf5439f4642))
+
+
+### Bug Fixes
+
+* **android:** center the back button and the bar buttons in the row ([#35](https://github.com/apexnative/navigation/issues/35)) ([c908971](https://github.com/apexnative/navigation/commit/c9089716ea4e3b3f4bcdc42b16e57134018d76c0))
+* **android:** fade through on a tab switch, a new tab's first frame in place ([#29](https://github.com/apexnative/navigation/issues/29)) ([60d69b6](https://github.com/apexnative/navigation/commit/60d69b618a97c8f7da974fbdf6f427461960d672))
+* **android:** let an overlay cover the status bar ([#27](https://github.com/apexnative/navigation/issues/27)) ([2632194](https://github.com/apexnative/navigation/commit/26321945cf0c457780b3eb7bba1f3d988dad4d96))
+* **android:** match each modal presentation style to its Android equivalent ([#31](https://github.com/apexnative/navigation/issues/31)) ([54ab265](https://github.com/apexnative/navigation/commit/54ab2651f3139e869a2d99a43465b33bfb171414))
+* **android:** move the top bar with its screen in transitions of their own ([#34](https://github.com/apexnative/navigation/issues/34)) ([4d12ee6](https://github.com/apexnative/navigation/commit/4d12ee6d6ec26a04e529bdef8b8111d20e5116aa))
+* close the side menu as a pick in it changes the center ([#28](https://github.com/apexnative/navigation/issues/28)) ([c4b3e81](https://github.com/apexnative/navigation/commit/c4b3e81ba44d2edb6d93d3ddc906eca165d46e29))
+
+
+### Performance Improvements
+
+* **android:** render the modals of a setRoot's layout together with its root ([#32](https://github.com/apexnative/navigation/issues/32)) ([cf3e1d9](https://github.com/apexnative/navigation/commit/cf3e1d98ff7c5d2a05aba6485203e6fe35a3423d))
+
 ## [1.0.0-alpha.2](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.1...v1.0.0-alpha.2) (2026-10-22)
 
 

package/android/CLAUDE.md

@@ -73,8 +73,10 @@ top-level folder. Main thread only, unless a line says otherwise.
   `ScreenFrame.kt` (bars' room, window insets, keyboard), `ScreenSafeArea.kt`, `ComponentPresenter.kt` (background),
   `ScreenContentFactory.kt`, `ScreenFocus.kt`; `react/ReactView.kt`; `views/component/ComponentLayout.kt`.
 - Stack (queue, commands, back): `viewcontrollers/stack/StackQueue.kt`, `StackCommands.kt`, `StackController.kt`,
-  `StackViews.kt`, `StackTransitions.kt`, `PreparedPushes.kt`; `views/stack/StackLayout.kt`; back:
-  `NavigationActivity.kt`, `viewcontrollers/navigator/BackCallbackState.kt`.
+  `StackViews.kt`, `StackTransitions.kt`, `PreparedPushes.kt`; `views/stack/StackLayout.kt`, `ScreenEdge.kt` (the edge
+  a moving screen extends); back: `NavigationActivity.kt`, `viewcontrollers/navigator/BackCallbackState.kt`; the
+  preview of a pop during the back gesture (Android 14+): `StackController.BackGesture`, `BackPreview.kt`,
+  `stackPoppedByBack` of the layouts.
 - Stack FAB: `viewcontrollers/stack/fab/FabPresenter.kt`, `FabPlan.kt`, `FabPlacement.kt`; `views/stack/fab/`.
 - Top bar (title, buttons, menus, large title): `viewcontrollers/stack/topbar/TopBarPresenter.kt`, `TopBarRoom.kt`,
   `TopBarVisibility.kt`, `BarComponents.kt`, `ButtonPlaces.kt`, `LargeTitleCollapse.kt`, `BarRowTransition.kt`;
@@ -167,6 +169,9 @@ top-level folder. Main thread only, unless a line says otherwise.
   `OverlayCoordinator.guarded`), which rejects the open answer and ends the record, or an exception ends the app and
   the command never answers.
 - A node makes its view in `createView`, never in its constructor.
+- Whether a node keeps the status bar's room (its margin, its background band) goes through
+  `StatusBarOptions.isHiddenOrDrawBehind(node.isInOverlay)`: an overlay covers the whole window, and a rule that reads
+  `drawBehind` alone puts a light band over an overlay's dimmed backdrop.
 - Only `SystemUiWindow` writes to the window. A presenter that changes a bar option calls `SystemUiOwner.invalidate`.
 - The core names a module container only in `LayoutFactory`; elsewhere use a capability or `visibleChildren()`.
 - A hidden stack keeps a `mergeOptions` per entry; applying it for the wrong entry paints the wrong screen's bar.
@@ -177,6 +182,20 @@ top-level folder. Main thread only, unless a line says otherwise.
   offset that `ScrollEventListener.lastOffset` keeps, never to 0, or it comes back expanded over a scrolled list.
 - A view's place in the window while a modal slides or a sheet is dragged comes from layout (`RestPlace`), never from
   `getLocationInWindow`, which counts the translations of the animation.
+- The bar measures to its children: a picture laid into it for a transition that is taller than the bar the incoming
+  screen gives holds the bar at that height to the end (the row's picture of a pop from a large title). What doesn't
+  stay in the bar rides with the leaving screen (`TopBarPresenter.pictureUnderRow`).
+- A `Toolbar` centers its navigation button and its menu in `min(minimumHeight, height)` (`buttonGravity` is top):
+  the row's toolbars take the row's height as their minimum (`TitleBar`); 0 pins the buttons to the row's top.
+- A screen's overlay is clipped to the screen, and a screen without a large title is laid out under the bar (its `top`
+  is the bar's height): a picture of the bar in its overlay doesn't show. The bar's picture in a transition of the
+  stack's own is drawn by the stack's view with the screen's transform (`StackLayout.barTravels`).
+- A React screen without `layout.backgroundColor` is opaque with the theme's `android:colorBackground`
+  (`ComponentPresenter`): a push keeps the covered screen under the new one until it ends, and a transparent screen
+  shows it. Only an explicit `'transparent'` / `null` (overlays, see-through modals) lets it through.
+- The back gesture's preview shows the screen under the top outside any operation of the queue: it may only reveal
+  it and put it back, and its release goes through `StackQueue.cut(gesture = true)`. A command that comes meanwhile
+  stops it through `StackDisplay.stop`, like any transition it takes over.
 - Without edge to edge the window resizes for the keyboard by the manifest's soft input mode, so
   `layout.adjustResize: false` goes through the system UI owner's keyboard group (`SystemUiWindow.setKeyboardCovers`),
   not through the screen's padding.

package/android/CORE.md

@@ -91,7 +91,9 @@ The events go from the main thread, synchronously, through `EventEmitter.current
   current root in the root layer, transparent (`RootLayerViews.place`), so its React roots start while the old root keeps
   the touches. It waits (`RenderWait`, by `animations.setRoot.enter.waitForRender`), then fades through or plays its own
   animation, the old root is destroyed with its `ComponentDidDisappear`, `NativeScreenReleased` and `SlotDestroyed`, and
-  the end steps and answer are the same. The layout's modals and overlays show after it, one by one, before the answer.
+  the end steps and answer are the same. The layout's modals and overlays show after it, one by one, before the answer;
+  its modals are made with the root and render unseen in the modals layer, held (`ModalCoordinator.hold`), so each
+  shows in its turn without a wait of its own.
   The last `setRoot` wins: an older one is rejected (`ErrorTexts.setRootReplaced`) or finished at once.
 - **`showModal`** (`Navigator.showModal`, `ModalCoordinator.show`). One `ModalRecord` per modal; it joins the modals
   layer unseen (`ModalViews`), waits with its own `RenderWait`, then slides in (or opens as a `ModalSheet`). It shows

package/android/src/main/java/dev/apexnative/navigation/NavigationActivity.kt

@@ -11,6 +11,7 @@ import android.view.View
 import android.view.ViewGroup
 import android.view.ViewTreeObserver
 import android.widget.EditText
+import androidx.activity.BackEventCompat
 import androidx.activity.OnBackPressedCallback
 import androidx.activity.SystemBarStyle
 import androidx.activity.enableEdgeToEdge as enableActivityEdgeToEdge
@@ -37,6 +38,7 @@ import dev.apexnative.navigation.utils.MaterialTheme
 import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 
 /**
  * The activity of an app with the navigation: its content holds, bottom to top, the copy of the splash and the layers
@@ -67,10 +69,36 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     private val reloadBroadcast = ReloadBroadcast(this) { reloadFromDeveloperTools() }
 
     // Enabled while back has something to do in the app (BackCallbackState); otherwise the system does its own back.
+    // From Android 14, where the app hears the progress of the back gesture, a gesture that would pop a stack with the
+    // default transition previews the pop as the system previews back between activities (`StackController
+    // .BackGesture`); JavaScript's listeners hear back first, so with them there is no preview.
     private val backCallback = object : OnBackPressedCallback(false) {
-        override fun handleOnBackPressed() = passBack()
+        override fun handleOnBackStarted(backEvent: BackEventCompat) {
+            backGesture = null
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE || BackCallbackState.hasJsListeners) return
+            val stack = navigator?.stackPoppedByBack() ?: return
+            backGesture = stack.startBackGesture(backEvent.swipeEdge == BackEventCompat.EDGE_LEFT, backEvent.touchY)
+        }
+
+        override fun handleOnBackProgressed(backEvent: BackEventCompat) {
+            backGesture?.progress(backEvent.progress, backEvent.touchY)
+        }
+
+        override fun handleOnBackCancelled() {
+            backGesture?.cancel()
+            backGesture = null
+        }
+
+        override fun handleOnBackPressed() {
+            val gesture = backGesture
+            backGesture = null
+            if (gesture?.commit() == true) BackCallbackState.update() else passBack()
+        }
     }
 
+    // The back gesture that previews a pop now; none.
+    private var backGesture: StackController.BackGesture? = null
+
     // Before each frame of the window: what back does may have changed, and the system decides at the start of a
     // gesture whether the app takes it.
     private val backBeforeFrame = ViewTreeObserver.OnPreDrawListener {

package/android/src/main/java/dev/apexnative/navigation/options/StatusBarOptions.kt

@@ -22,9 +22,13 @@ class StatusBarOptions {
     @JvmField var hideWithTopBar: Bool = NullBool()
     @JvmField var blur: Bool = NullBool()
 
-    /** The status bar is hidden, or the screen is drawn under it: the screen keeps no room for it. */
-    val isHiddenOrDrawBehind: Boolean
-        get() = visible.isFalse || drawBehind.isTrue
+    /**
+     * The status bar is hidden, or the screen is drawn under it: the screen keeps no room for it. Without `drawBehind`, a
+     * screen or a layout in an overlay ([inOverlay]) is drawn under it: an overlay covers the whole window, its dimmed
+     * backdrop the status bar too.
+     */
+    fun isHiddenOrDrawBehind(inOverlay: Boolean): Boolean =
+        visible.isFalse || if (drawBehind.hasValue()) drawBehind.isTrue else inOverlay
 
     fun hasValue(): Boolean = visible.hasValue() || style.hasValue() || backgroundColor.hasValue() ||
         drawBehind.hasValue() || translucent.hasValue() || animate.hasValue() || hideWithTopBar.hasValue() ||

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/arrangement/SecondaryScreenPresenter.kt

@@ -2,24 +2,25 @@ package dev.apexnative.navigation.viewcontrollers.arrangement
 
 import android.app.Activity
 import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.viewcontrollers.component.ComponentPresenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 
 /**
  * The presenter of the secondary screen of a pair ([ArrangementController]). The status bar, the navigation bar and
- * the orientation are the primary's, as the top bar is: the secondary applies only its background, and brought to the
- * front it gives them back to the primary.
+ * the orientation are the primary's, as the top bar is: the secondary applies only its background (the theme's
+ * without `layout.backgroundColor`, as any React screen), and brought to the front it gives them back to the primary.
  */
 internal class SecondaryScreenPresenter(activity: Activity, defaultOptions: Options) :
     Presenter(activity, defaultOptions) {
 
     override fun applyOptions(view: ViewController<*>, options: Options) =
-        applyBackgroundColor(view, options.copy().withDefaultOptions(defaultOptions))
+        applyBackground(view, options.copy().withDefaultOptions(defaultOptions))
 
     override fun mergeOptions(viewController: ViewController<*>, options: Options) {
         if (!options.layout.backgroundColor.hasValue()) return
         val merged = viewController.resolveCurrentOptions().copy().mergeWith(options)
-        applyBackgroundColor(viewController, merged.withDefaultOptions(defaultOptions))
+        applyBackground(viewController, merged.withDefaultOptions(defaultOptions))
     }
 
     override fun onViewBroughtToFront(viewController: ViewController<*>, options: Options) {
@@ -27,5 +28,12 @@ internal class SecondaryScreenPresenter(activity: Activity, defaultOptions: Opti
     }
 
     override fun onConfigurationChanged(controller: ViewController<*>, options: Options) =
-        applyBackgroundColor(controller, options.copy().withDefaultOptions(defaultOptions))
+        applyBackground(controller, options.copy().withDefaultOptions(defaultOptions))
+
+    // `layout.backgroundColor`, else the theme's background (`ComponentPresenter.themeBackgroundOf`).
+    private fun applyBackground(view: ViewController<*>, options: Options) {
+        if (options.layout.backgroundColor.hasValue()) return applyBackgroundColor(view, options)
+        val color = ComponentPresenter.themeBackgroundOf(activity) ?: return
+        view.peekView()?.setBackgroundColor(color)
+    }
 }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/bottomtabs/BottomTabsController.kt

@@ -1,5 +1,8 @@
 package dev.apexnative.navigation.viewcontrollers.bottomtabs
 
+import android.animation.Animator
+import android.animation.AnimatorListenerAdapter
+import android.animation.AnimatorSet
 import android.app.Activity
 import android.graphics.Color
 import android.util.Log
@@ -33,6 +36,7 @@ import dev.apexnative.navigation.viewcontrollers.stack.fab.FabPlacement
 import dev.apexnative.navigation.viewcontrollers.stack.topbar.BarComponents
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.animations.FadeThrough
 import dev.apexnative.navigation.views.bottomtabs.BottomTabItem
 import dev.apexnative.navigation.views.bottomtabs.BottomTabsLayout
 import dev.apexnative.navigation.views.bottomtabs.CustomBottomTabItemView
@@ -68,6 +72,8 @@ class BottomTabsController(
     private var cells: List<CustomBottomTabItemView> = emptyList()
     // `ANN.BottomTabSelected` of a press that waits for the new tab's screen to appear.
     private var pendingSelected: (() -> Unit)? = null
+    // Ends the fade through of a switch still running, with its events.
+    private var endSwitch: (() -> Unit)? = null
     // The bar goes with a stack's transition: the options of the new top don't move it themselves.
     private var riding = false
     private var restAttached = false
@@ -150,8 +156,11 @@ class BottomTabsController(
         /** The view of [tab] joins, or is there already: [visible], or invisible but laid out. */
         fun attach(tab: ViewController<*>, visible: Boolean)
 
-        /** The view of [shown] becomes visible and that of [hidden] invisible: the switch, at once. */
-        fun switch(shown: ViewController<*>, hidden: ViewController<*>)
+        /**
+         * The view of [shown] becomes visible and that of [hidden] invisible: at once, or with Material's fade through
+         * when [animated]; then [onEnd]. The function returned ends a switch still running at once, [onEnd] included.
+         */
+        fun switch(shown: ViewController<*>, hidden: ViewController<*>, animated: Boolean, onEnd: () -> Unit): () -> Unit
     }
 
     /** The views of the tabs; none before the tabs' view is made. */
@@ -166,9 +175,43 @@ class BottomTabsController(
             tab.view.visibility = if (visible) View.VISIBLE else View.INVISIBLE
         }
 
-        override fun switch(shown: ViewController<*>, hidden: ViewController<*>) {
-            shown.view.visibility = View.VISIBLE
-            hidden.peekView()?.visibility = View.INVISIBLE
+        override fun switch(
+            shown: ViewController<*>,
+            hidden: ViewController<*>,
+            animated: Boolean,
+            onEnd: () -> Unit,
+        ): () -> Unit {
+            val coming = shown.view
+            coming.visibility = View.VISIBLE
+            val going = hidden.peekView()
+            if (!animated || going == null) {
+                going?.visibility = View.INVISIBLE
+                onEnd()
+                return {}
+            }
+            val exit = FadeThrough.exit(going)
+            // Faded out, the tab that goes takes no more touches and no accessibility focus.
+            exit.addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: Animator) {
+                    going.visibility = View.INVISIBLE
+                }
+            })
+            val set = AnimatorSet()
+            set.playTogether(exit, FadeThrough.enter(coming))
+            set.addListener(object : AnimatorListenerAdapter() {
+                override fun onAnimationEnd(animation: Animator) {
+                    set.removeAllListeners()
+                    // The tab that went keeps its look for its next selection; only its visibility hides it.
+                    going.visibility = View.INVISIBLE
+                    going.alpha = 1f
+                    coming.alpha = 1f
+                    coming.scaleX = 1f
+                    coming.scaleY = 1f
+                    onEnd()
+                }
+            })
+            set.start()
+            return set::end
         }
     }
 
@@ -302,10 +345,9 @@ class BottomTabsController(
     }
 
     /**
-     * Selects the tab at [index]: what it shows appears, the tab it left disappears — at once, one container invisible
-     * and the other visible —, then for a press `ANN.BottomTabSelected` right after the new screen's DidAppear and the
-     * left tab's `popToRootOnBlur`, with the state as one update after them; from code and by back, `popToRootOnBlur`
-     * and the state at once. The history of back follows.
+     * Selects the tab at [index]: the bar shows it at once; on screen the tab it left fades through to it (Material's
+     * fade through), off screen one container becomes invisible and the other visible at once; then [switched]. The
+     * history of back follows.
      */
     private fun select(index: Int, how: How) {
         if (index == selectedIndex || index !in tabs.indices || isDestroyed) return
@@ -328,10 +370,27 @@ class BottomTabsController(
         // A layer that waits for the tabs waits for the tab they show now.
         navigator?.shownScreensChanged(this)
         if (onScreen) AppearanceDispatcher.beginTransition(listOf(shown))
-        views?.switch(shown, left)
+        if (views == null) return switched(index, previous, how, onScreen, hasViews = false)
+        endSwitch = views.switch(shown, left, animated = onScreen) {
+            endSwitch = null
+            if (!isDestroyed) switched(index, previous, how, onScreen, hasViews = true)
+        }
+    }
+
+    /**
+     * The switch to the tab at [index] from [previous] ended: what went disappears, what came appears — unless the tabs
+     * stopped showing during the fade (a modal over them): it appears when they show again; then for a press
+     * `ANN.BottomTabSelected` right after the new screen's DidAppear and the left tab's `popToRootOnBlur`, with the state
+     * as one update after them; from code and by back, `popToRootOnBlur` and the state at once. [onScreen]: the switch
+     * started on screen.
+     */
+    private fun switched(index: Int, previous: Int, how: How, onScreen: Boolean, hasViews: Boolean) {
+        val left = tabs[previous]
+        val shown = tabs[index]
         if (onScreen) {
-            AppearanceDispatcher.endTransition(listOf(left), listOf(shown), null, null, null, reportsState = false)
-        } else if (views != null) {
+            val showing = if (isOnScreen) listOf(shown) else emptyList()
+            AppearanceDispatcher.endTransition(listOf(left), showing, null, null, null, reportsState = false)
+        } else if (hasViews) {
             // Not on screen: the bar takes the new tab's options as they are, without appearance events.
             val options = resolveShownOptions(DefaultOptions.current)
             bar.applyBar(options.bottomTabs, directionOf(options))
@@ -358,8 +417,10 @@ class BottomTabsController(
         if (screen == null) finish() else AppearanceDispatcher.afterDidAppear(screen, finish)
     }
 
-    // A press's `ANN.BottomTabSelected` still waiting goes before anything newer on these tabs.
+    // A switch still running ends at once and a press's `ANN.BottomTabSelected` still waiting goes, before anything
+    // newer on these tabs.
     private fun flushPendingSelected() {
+        endSwitch?.invoke()
         pendingSelected?.invoke()
     }
 
@@ -621,6 +682,8 @@ class BottomTabsController(
         if (isDestroyed) return
         pendingSelected = null
         super.destroy()
+        // A switch still running ends with its views at rest, without events: the tabs are gone.
+        endSwitch?.invoke()
         peekView()?.let { layout ->
             layout.bar.destroyCustomItemViews()
             layout.row?.let(CustomTabRowPlacer::forget)

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/component/ComponentPresenter.kt

@@ -6,6 +6,7 @@ import android.graphics.drawable.ColorDrawable
 import android.graphics.drawable.Drawable
 import android.graphics.drawable.LayerDrawable
 import android.view.View
+import com.google.android.material.color.MaterialColors
 import dev.apexnative.navigation.options.DefaultOptions
 import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.options.params.ThemeColour
@@ -15,9 +16,9 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 
 /**
- * The presenter of a screen, React or native: its background — the screen's view takes `layout.backgroundColor`, kept
- * out of the status bar's height where the status bar shows over it, and the React content takes
- * `layout.componentBackgroundColor` over it —, its room for the bars, and its safe area again on `mergeOptions`
+ * The presenter of a screen, React or native: its background — the screen's view takes `layout.backgroundColor` (a
+ * React screen without it the theme's background), kept out of the status bar's height where the status bar shows over
+ * it, and the React content takes `layout.componentBackgroundColor` over it —, its room for the bars, and its safe area again on `mergeOptions`
  * (`mergeOptions` step 4). It applies as the screen appears, on `mergeOptions` of what it covers, and again with new
  * default options or after a light/dark switch from the resolved options it is given, which it never writes. Each
  * appearance tells the activity's system UI owner, which follows the screen on top. Main thread only.
@@ -49,8 +50,8 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
         applyBackground(controller, options)
 
     /**
-     * The colors of [screen] from its resolved [options]: `layout.backgroundColor` on the screen's view, none without
-     * it (the window shows); `layout.componentBackgroundColor` on its React content.
+     * The colors of [screen] from its resolved [options]: `layout.backgroundColor` on the screen's view, without it the
+     * theme's background for a React screen ([defaultColorOf]); `layout.componentBackgroundColor` on its React content.
      */
     fun applyBackground(screen: ViewController<*>, options: Options) {
         val view = screen.peekView() ?: return
@@ -59,11 +60,11 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
     }
 
     private fun screenBackground(screen: ViewController<*>, options: Options): Drawable? {
-        val color = colorOf(options.layout.backgroundColor) ?: return null
+        val color = colorOf(options.layout.backgroundColor) ?: defaultColorOf(screen) ?: return null
         val frame = frameOf(screen) ?: return ColorDrawable(color)
         val band = ScreenSafeArea.backgroundBand(
             statusBarHeight = frame.statusBarHeight,
-            hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind,
+            hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind(screen.isInOverlay),
             inSideMenu = screen.isInSideMenu,
             inSheet = screen.isInSheet,
             inPair = frame.isInPair,
@@ -79,6 +80,15 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
     private fun colorOf(colour: ThemeColour): Int? =
         if (colour.hasValue()) colour.get(activity, Color.TRANSPARENT) ?: Color.TRANSPARENT else null
 
+    // A React screen is opaque without a color of its own, as iOS gives it the system background: the screen under it
+    // never shows through, also while a push slides it aside. The app theme's `android:colorBackground`, read now, so a
+    // light/dark switch takes the new mode's. A screen of a sheet shows the sheet's surface; a native screen paints its
+    // own view.
+    private fun defaultColorOf(screen: ViewController<*>): Int? {
+        if (screen !is ComponentViewController || screen.isInSheet) return null
+        return themeBackgroundOf(activity)
+    }
+
     private fun frameOf(screen: ViewController<*>): ScreenFrame? = when (screen) {
         is ComponentViewController -> screen.frame
         is ExternalComponentViewController -> screen.frame
@@ -87,4 +97,15 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
 
     // The view under the React content: the React root, or the container of a slot screen. A native screen has none.
     private fun contentOf(screen: ViewController<*>): View? = (screen as? ComponentViewController)?.content?.asView()
+
+    internal companion object {
+        /**
+         * The background of a React screen without `layout.backgroundColor`: `android:colorBackground` of [activity]'s
+         * theme now. None for an activity without a theme (the unit tests' fakes).
+         */
+        fun themeBackgroundOf(activity: Activity): Int? {
+            if (activity.theme == null) return null
+            return MaterialColors.getColor(activity, android.R.attr.colorBackground, Color.WHITE)
+        }
+    }
 }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/component/ScreenFrame.kt

@@ -143,7 +143,7 @@ internal class ScreenFrame(
             val parent = node.parentController
             val statusBar = ScreenSafeArea.statusBarRoom(
                 statusBarHeight = statusBarHeight,
-                hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind,
+                hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind(node.isInOverlay),
                 inSheet = node.isInSheet,
                 inSideMenu = node.isInSideMenu,
                 keptAround = parent?.keepsStatusBarRoomOf(node) == true,

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalAnimations.kt

@@ -1,40 +1,38 @@
 package dev.apexnative.navigation.viewcontrollers.modal
 
-import kotlin.math.PI
-import kotlin.math.cos
+import dev.apexnative.navigation.views.animations.Curves
 
 /**
- * The default animations of a modal on Android, as values: it comes up from the bottom of the window by the window's
- * height (in a split screen or a window, the window's, not the display's) and fades in, [DURATION] with a deceleration
- * at the end; it goes down and fades out in the same time, accelerating and decelerating (the system's cosine, not the
- * option's `accelerateDecelerate`). A sheet moves only by the Material sheet's own motion. Pure arithmetic.
+ * The default animations of a modal over the whole screen on Android, as values: the system's motion of a window that
+ * opens over the one below it (`activity_translucent_open_enter` and `activity_translucent_close_exit` of the
+ * platform, which Android 16 plays for a translucent activity). The modal comes up from the bottom of the window by the
+ * window's height (in a split screen or a window, the window's, not the display's) in [SHOW_DURATION], slowing down at
+ * the end; it goes down in [DISMISS_DURATION], speeding up. It doesn't fade: the screen below is seen only around it,
+ * as under a translucent activity. A sheet moves only by the Material sheet's own motion. Pure arithmetic.
  */
 internal object ModalAnimations {
-    /** How long the default show and the default dismissal last (ms). */
-    const val DURATION = 300L
+    /** How long the default show lasts (ms): `activity_translucent_open_enter`. */
+    const val SHOW_DURATION = 300L
+
+    /** How long the default dismissal lasts (ms): `activity_translucent_close_exit`. */
+    const val DISMISS_DURATION = 250L
+
+    // `linear_out_slow_in` of the platform: the path (0, 0) (0, 0) (0.2, 1) (1, 1).
+    private val linearOutSlowIn = Curves.CubicBezier(0.0, 0.0, 0.2, 1.0)
 
     /** How far a modal comes up and goes down: the window's height ([windowHeight]), or the display's while it is 0. */
     fun distance(windowHeight: Int, displayHeight: Int): Float =
         (if (windowHeight > 0) windowHeight else displayHeight).toFloat()
 
-    /** The curve of the show: a deceleration, 1 − (1 − p)². */
-    fun decelerate(progress: Float): Float = 1f - (1f - progress) * (1f - progress)
+    /** The curve of the show: the platform's `linear_out_slow_in`, fast at first and slow at the end. */
+    fun linearOutSlowIn(progress: Float): Float = linearOutSlowIn.getInterpolation(progress)
 
-    /** The curve of the dismissal: an acceleration then a deceleration, cos((p + 1)π) / 2 + 0.5. */
-    fun accelerateDecelerate(progress: Float): Float = (cos((progress + 1) * PI) / 2 + 0.5).toFloat()
+    /** The curve of the dismissal: the platform's `accelerate_quad`, p². */
+    fun accelerate(progress: Float): Float = progress.coerceIn(0f, 1f).let { it * it }
 
-    /** Where a modal is at [progress] (0 … 1, in time) of its show over [distance]: its translation and its alpha. */
-    fun show(progress: Float, distance: Float): Frame {
-        val value = decelerate(progress)
-        return Frame(translationY = distance * (1f - value), alpha = value)
-    }
+    /** Where a modal is at [progress] (0 … 1, in time) of its show over [distance]: its translation. */
+    fun show(progress: Float, distance: Float): Float = distance * (1f - linearOutSlowIn(progress))
 
     /** Where a modal is at [progress] of its dismissal over [distance], from where it rests. */
-    fun dismiss(progress: Float, distance: Float): Frame {
-        val value = accelerateDecelerate(progress)
-        return Frame(translationY = distance * value, alpha = 1f - value)
-    }
-
-    /** A modal's place in its animation. */
-    data class Frame(val translationY: Float, val alpha: Float)
+    fun dismiss(progress: Float, distance: Float): Float = distance * accelerate(progress)
 }