@apexnative/navigation 1.0.0-alpha.4 → 1.0.0-alpha.6

package/android/src/main/java/dev/apexnative/navigation/react/ScrollEvents.kt

@@ -1,25 +1,17 @@
 package dev.apexnative.navigation.react
 
-import android.content.Context
-import android.util.Log
-import com.facebook.react.ReactApplication
-import com.facebook.react.uimanager.UIManagerHelper
-import com.facebook.react.uimanager.events.Event
-import com.facebook.react.uimanager.events.EventDispatcherListener
-import com.facebook.react.views.scroll.ScrollEvent
+import android.view.ViewGroup
+import android.widget.HorizontalScrollView
+import com.facebook.react.views.scroll.ReactScrollViewHelper
 import com.facebook.react.views.scroll.ScrollEventType
-import dev.apexnative.navigation.utils.NavigationLog
-import dev.apexnative.navigation.utils.UiThread
-import dev.apexnative.navigation.viewcontrollers.viewcontroller.ScrollEventListener
-import java.lang.reflect.Field
-import java.util.Collections
-import java.util.WeakHashMap
 
 /**
- * The scroll events of React Native's lists, as the screens' scroll listeners hear them: from the event dispatcher of
- * the running React Native, every list of the app. React Native keeps the offset, the speed and the kind of a scroll
- * event in private fields: they are looked up once, with their types; if React Native renames them, one warning goes to
- * the log and the screens hear no scroll, with no error at each event.
+ * The scroll events of React Native's scroll views, as the screens' scroll listeners hear them: through React Native's
+ * public scroll listener ([ReactScrollViewHelper.addScrollListener]), which every `ReactScrollView`,
+ * `ReactHorizontalScrollView` and `ReactNestedScrollView` of the process calls on the main thread just before it
+ * dispatches the same event to JavaScript, after the same throttle. One listener serves every screen and every React
+ * context; it is added while a screen listens and removed when the last one stops. Horizontal scroll views are left
+ * out: a pager or a carousel doesn't move the bars. Main thread only.
  */
 internal object ScrollEvents {
     /** What a scroll event is. */
@@ -28,133 +20,62 @@ internal object ScrollEvents {
     /** One scroll event: the list's tag (its view's id), its kind, its vertical offset and speed, in pixels. */
     class Reading(val viewTag: Int, val kind: Kind, val offsetY: Float, val velocityY: Float)
 
-    private class Fields(val type: Field, val offsetY: Field, val velocityY: Field)
+    // One screen's listening: its own object, so that a stop takes away that listening and no other.
+    private class Listening(val handler: (Reading) -> Unit)
 
-    private var fields: Fields? = null
-    private var lookedUp = false
+    // The screens' listenings, in the order they came.
+    private val listenings = mutableListOf<Listening>()
 
-    // The screens' listeners that found no event dispatcher, held weakly until React Native has one. Main thread.
-    private val waiting: MutableSet<ScrollEventListener> = Collections.newSetFromMap(WeakHashMap())
+    // React Native holds its scroll listeners weakly: this object keeps the one it added for as long as it is added.
+    private val listener = object : ReactScrollViewHelper.ScrollListener {
+        override fun onScroll(
+            scrollView: ViewGroup?,
+            scrollEventType: ScrollEventType?,
+            xVelocity: Float,
+            yVelocity: Float,
+        ) = hear(scrollView, scrollEventType, yVelocity)
 
-    /** [listener] found no event dispatcher: it is asked to listen again once React Native has one. */
-    fun waitForDispatcher(listener: ScrollEventListener) {
-        waiting += listener
-    }
-
-    /** A React context is ready (`ReloadCoordinator`): the listeners waiting for an event dispatcher listen now. */
-    fun dispatcherReady() {
-        val listeners = waiting.toList()
-        waiting.clear()
-        listeners.forEach(ScrollEventListener::attachIfNeeded)
+        override fun onLayout(scrollView: ViewGroup?) = Unit
     }
 
     /**
-     * Calls [handler] on the main thread with each scroll event of the app's React Native, until the function returned
-     * is called. None when React Native has no event dispatcher now (around a reload, the caller asks again later) or
-     * its scroll events can't be read.
+     * Calls [handler] with each scroll event of a vertical scroll view of the app, until the function returned is
+     * called.
      */
-    fun listen(context: Context, handler: (Reading) -> Unit): (() -> Unit)? {
-        if (fields() == null) return null
-        val reactContext = (context.applicationContext as? ReactApplication)?.reactHost?.currentReactContext
-            ?: return null
-        val dispatcher = try {
-            UIManagerHelper.getEventDispatcher(reactContext)
-        } catch (e: RuntimeException) {
-            null
-        } ?: return null
-        val listener = EventDispatcherListener { event ->
-            // The event goes back to its pool after the dispatch: it is read now, on the thread that dispatches.
-            val reading = read(event) ?: return@EventDispatcherListener
-            if (UiThread.isMainThread()) handler(reading) else UiThread.post { handler(reading) }
+    fun listen(handler: (Reading) -> Unit): () -> Unit {
+        val listening = Listening(handler)
+        if (listenings.isEmpty()) ReactScrollViewHelper.addScrollListener(listener)
+        listenings += listening
+        return {
+            // By identity: the second call of a stop finds nothing to take away.
+            if (listenings.removeAll { it === listening } && listenings.isEmpty()) {
+                ReactScrollViewHelper.removeScrollListener(listener)
+            }
         }
-        dispatcher.addListener(listener)
-        return { dispatcher.removeListener(listener) }
     }
 
-    private fun read(event: Event<*>): Reading? {
-        if (event !is ScrollEvent) return null
-        val fields = fields() ?: return null
-        return try {
-            val type = fields.type.get(event) as? ScrollEventType ?: return null
-            val offsetY = readFloat(fields.offsetY, event) ?: return null
-            val velocityY = readFloat(fields.velocityY, event) ?: return null
-            Reading(event.viewTag, kindOf(type), offsetY, velocityY)
-        } catch (e: ReflectiveOperationException) {
-            null
-        } catch (e: IllegalArgumentException) {
-            null
-        }
+    /** One call of React Native's listener: the handlers listening now hear its reading, if it has one. */
+    fun hear(scrollView: ViewGroup?, type: ScrollEventType?, velocityY: Float) {
+        val reading = read(scrollView, type, velocityY) ?: return
+        listenings.toList().forEach { it.handler(reading) }
     }
 
-    private fun kindOf(type: ScrollEventType): Kind = when (type) {
+    /**
+     * The reading of one call of React Native's listener: none for a horizontal scroll view, or when React Native gives
+     * no view or no kind. The offset is the view's `scrollY` and the speed React Native's own, in pixels, as the event
+     * sent to JavaScript carries them before it converts them to dp.
+     */
+    fun read(scrollView: ViewGroup?, type: ScrollEventType?, velocityY: Float): Reading? {
+        if (scrollView == null || type == null || scrollView is HorizontalScrollView) return null
+        return Reading(scrollView.id, kindOf(type), scrollView.scrollY.toFloat(), velocityY)
+    }
+
+    /** The kind of a reading for React Native's [type]. */
+    fun kindOf(type: ScrollEventType): Kind = when (type) {
         ScrollEventType.BEGIN_DRAG -> Kind.BeginDrag
         ScrollEventType.END_DRAG -> Kind.EndDrag
         ScrollEventType.SCROLL -> Kind.Scroll
         ScrollEventType.MOMENTUM_BEGIN -> Kind.MomentumBegin
         ScrollEventType.MOMENTUM_END -> Kind.MomentumEnd
     }
-
-    @Synchronized
-    private fun fields(): Fields? {
-        if (lookedUp) return fields
-        lookedUp = true
-        fields = try {
-            val owner = ScrollEvent::class.java
-            val type = declaredField(owner, TYPE_NAMES) { ScrollEventType::class.java.isAssignableFrom(it) }
-            val offsetY = declaredField(owner, OFFSET_NAMES, ::isNumeric)
-            val velocityY = declaredField(owner, VELOCITY_NAMES, ::isNumeric)
-            if (type != null && offsetY != null && velocityY != null) Fields(type, offsetY, velocityY) else null
-        } catch (e: ReflectiveOperationException) {
-            null
-        } catch (e: SecurityException) {
-            null
-        }
-        if (fields == null) {
-            Log.w(
-                NavigationLog.TAG,
-                "[ApexNavigation] React Native's scroll events changed: hideOnScroll and the large title " +
-                    "don't follow the scroll",
-            )
-        }
-        return fields
-    }
-
-    // The names of the fields: React Native 0.87 first, then the earlier ones with the `m` prefix.
-    private val TYPE_NAMES = listOf("scrollEventType", "mScrollEventType")
-    private val OFFSET_NAMES = listOf("scrollY", "mScrollY")
-    private val VELOCITY_NAMES = listOf("yVelocity", "mYVelocity")
-
-    /**
-     * The first of the fields [names] that [owner] declares with a type [accepted] takes, made readable; none when no
-     * name fits. React Native renamed them and changed their types between versions.
-     */
-    fun declaredField(owner: Class<*>, names: List<String>, accepted: (Class<*>) -> Boolean): Field? {
-        for (name in names) {
-            val field = try {
-                owner.getDeclaredField(name)
-            } catch (e: NoSuchFieldException) {
-                continue
-            }
-            if (!accepted(field.type)) continue
-            field.isAccessible = true
-            return field
-        }
-        return null
-    }
-
-    /** A number of any kind: a primitive one (`int`, `float`, `double`, …) or a boxed one. */
-    fun isNumeric(type: Class<*>): Boolean =
-        type in PRIMITIVE_NUMBERS || Number::class.java.isAssignableFrom(type)
-
-    /** [field] of [target] as a float, whatever numeric type it has; none when it holds no number. */
-    fun readFloat(field: Field, target: Any): Float? = (field.get(target) as? Number)?.toFloat()
-
-    private val PRIMITIVE_NUMBERS = setOf<Class<*>?>(
-        Byte::class.javaPrimitiveType,
-        Short::class.javaPrimitiveType,
-        Int::class.javaPrimitiveType,
-        Long::class.javaPrimitiveType,
-        Float::class.javaPrimitiveType,
-        Double::class.javaPrimitiveType,
-    )
 }

package/android/src/main/java/dev/apexnative/navigation/react/events/AppearanceDispatcher.kt

@@ -90,7 +90,7 @@ internal object AppearanceDispatcher {
         val appearanceRecord: ScreenAppearance?
     }
 
-    /** The navigation state (`NavigationStateReporter`): one update in this pass of the main loop, or one now. */
+    /** The navigation state ([NavigationState]): one update in this pass of the main loop, or one now. */
     interface StateUpdates {
         /**
          * Asks for one update in this pass of the main loop: the calls of one pass make one, after a DidAppear or a
@@ -98,7 +98,10 @@ internal object AppearanceDispatcher {
          */
         fun setNeedsUpdate()
 
-        /** Computes the state now and sends it when it changed: before an answer, at the end of a transition. */
+        /**
+         * Computes the state now and sends it when it changed: a command's answer, once
+         * (`CommandAnswer.reportStateNow`), the end of a user's transition, a tab chosen from code.
+         */
         fun updateNow()
 
         /**
@@ -157,33 +160,6 @@ internal object AppearanceDispatcher {
             EventEmitter.current().emitSheetDetentChanged(componentId, detent)
     }
 
-    /** The state of `NavigationStateReporter`, sent through the JavaScript that runs now, when it can be. */
-    object ReporterState : StateUpdates {
-        private val handler by lazy { Handler(Looper.getMainLooper()) }
-
-        // The one posted update of a pass of the main loop, which checks the hold when it runs.
-        private val held = StateHold(
-            post = { task -> handler.post(task) },
-            generation = { ReloadCoordinator.generation },
-        ) {
-            val emitter = EventEmitter.current()
-            if (emitter.canSend) NavigationStateReporter.updateNow(emitter)
-        }
-
-        override fun setNeedsUpdate() {
-            if (EventEmitter.current().canSend) held.setNeedsUpdate()
-        }
-
-        override fun hold() = held.hold()
-
-        override fun release() = held.release()
-
-        override fun updateNow() {
-            val emitter = EventEmitter.current()
-            if (emitter.canSend) NavigationStateReporter.updateNow(emitter)
-        }
-    }
-
     /** The main thread's loop. */
     object MainScheduler : Scheduler {
         private val handler by lazy { Handler(Looper.getMainLooper()) }
@@ -198,8 +174,8 @@ internal object AppearanceDispatcher {
     /** Where the events go: [EmitterSender]; the tests put a journal here. */
     var sender: Sender = EmitterSender
 
-    /** The navigation state the sent appearance events and transitions update: [ReporterState]; a journal in tests. */
-    var state: StateUpdates = ReporterState
+    /** The navigation state the appearance events and transitions update: [NavigationState]; a journal in tests. */
+    var state: StateUpdates = NavigationState
 
     /** The clock of the hold limit: [MainScheduler]; the tests put a clock that moves when they say. */
     var scheduler: Scheduler = MainScheduler
@@ -337,12 +313,15 @@ internal object AppearanceDispatcher {
     }
 
     /**
-     * A transition ended,: what went disappears ([hiding]), what stands appears ([showing], with its WillAppear first
+     * A transition ended: what went disappears ([hiding]), what stands appears ([showing], with its WillAppear first
      * where it wasn't asked), the navigation state goes when it changed, then [events] (the transition's own:
      * `ANN.ScreenPopped`, `ANN.ModalDismissed`, and what must follow them, like stopping the content of what went),
-     * then [answer] resolves with [value] (the promise, then `ANN.CommandCompleted`). A user's action has no answer. A
-     * state that fails is logged ([log]) and the transition goes on: [events] and the answer always come. Without
-     * [reportsState] the caller sends the state itself, later (a tab switch: after `ANN.BottomTabSelected`).
+     * then [answer] resolves with [value] (the promise, then `ANN.CommandCompleted`; no second state). The state is the
+     * answer's one state step (`CommandAnswer.reportStateNow`), which sends nothing for a JavaScript that went; a
+     * user's action has no answer, and a command answered before its transition ended had its state then: the state
+     * of the end goes all the same, unless its JavaScript went. A state that fails is logged and the transition goes
+     * on: [events] and the answer always come. Without [reportsState] the caller sends the state itself, later (a tab
+     * switch: after `ANN.BottomTabSelected`; a `setRoot` with layers: from its answer).
      */
     fun endTransition(
         hiding: List<ViewController<*>>,
@@ -360,18 +339,30 @@ internal object AppearanceDispatcher {
             holdsState = false
         }
         showing.forEach { it.onViewDidAppear() }
-        if (reportsState) reportState(answer?.commandName)
+        if (reportsState) {
+            // The state before the transition's events, once per answer: the answer's own step before its promise
+            // finds it sent. Without an answer to wait for, the dispatcher sends it; nothing for a JavaScript that
+            // went.
+            when {
+                answer == null -> reportState()
+                answer.isAnswered -> if (ReloadCoordinator.isCurrent(answer.generation)) reportState()
+                else -> answer.reportStateNow()
+            }
+        }
         events?.invoke()
         answer?.resolve(value)
     }
 
-    /** The navigation state now, when it changed; a failure is logged ([log]), nothing else stops for it. */
-    fun reportState(commandName: String? = null) {
+    /**
+     * The navigation state now, when it changed, without a command's answer (a command's goes through its answer,
+     * `CommandAnswer.reportStateNow`); a failure is logged ([log]), nothing else stops for it.
+     */
+    fun reportState() {
         try {
             state.updateNow()
         } catch (e: Throwable) {
             val reason = ErrorTexts.couldNot("report the navigation state", ErrorTexts.reasonOf(e))
-            log("[ApexNavigation] ${commandName ?: "transition"}: $reason")
+            log("[ApexNavigation] transition: $reason")
         }
     }
 

package/android/src/main/java/dev/apexnative/navigation/react/events/EventEmitter.kt

@@ -6,6 +6,7 @@ import com.facebook.react.bridge.ReactContext
 import com.facebook.react.bridge.WritableMap
 import dev.apexnative.navigation.NavigationApplication
 import dev.apexnative.navigation.nativescreen.NativeScreenCalls
+import dev.apexnative.navigation.react.ReloadCoordinator
 import dev.apexnative.navigation.utils.NavigationLog
 import org.json.JSONArray
 
@@ -13,12 +14,26 @@ import org.json.JSONArray
  * Sends the events `ANN.<Name>` to the JavaScript of [reactContext] through React Native's device event emitter, in
  * the order they are sent: sent from the main thread only. Without a context, or when its React instance is gone, an
  * event is dropped with one line in the log. The names and the keys come from [EventContract], made from the types of
- * `src/interfaces/`. The core sends through [current]; modules keep making their own.
+ * `src/interfaces/`.
+ *
+ * An emitter belongs to one JavaScript, as on iOS (`ANNEventEmitter`): it takes the number of the JavaScript
+ * ([generation], `ReloadCoordinator`) when it is made and drops every event silently once that number moved. React
+ * Native keeps one context across a reload (bridgeless), so without it an event of a screen of the JavaScript that
+ * went would reach the new one, which may have a screen with the same id. The core and its modules send through
+ * [current], or [of] with the number of the JavaScript a node was made for.
  */
-class EventEmitter(private val reactContext: ReactContext?) {
-    /** Whether an event sent now reaches JavaScript. */
+class EventEmitter @JvmOverloads constructor(
+    private val reactContext: ReactContext?,
+    /** The number of the JavaScript this emitter sends to: by default the one that runs as it is made. */
+    val generation: Int = ReloadCoordinator.generation,
+) {
+    /** Whether the JavaScript of this emitter still runs: its events go only then. Any thread. */
+    val isCurrent: Boolean
+        get() = ReloadCoordinator.isCurrent(generation)
+
+    /** Whether an event sent now reaches JavaScript: its JavaScript still runs, in a live React instance. */
     val canSend: Boolean
-        get() = reactContext?.hasActiveReactInstance() == true
+        get() = isCurrent && reactContext?.hasActiveReactInstance() == true
 
     fun emitAppLaunched() = emit(EventContract.AppLaunched.EVENT, Arguments.createMap())
 
@@ -167,6 +182,8 @@ class EventEmitter(private val reactContext: ReactContext?) {
         Arguments.createMap().apply { putString(EventContract.ScreenPopped.COMPONENT_ID, componentId) }
 
     private fun emit(name: String, data: WritableMap) {
+        // The JavaScript of this emitter went: the new one never had its screens.
+        if (!isCurrent) return
         val context = reactContext
         if (context == null || !context.hasActiveReactInstance()) {
             Log.w(NavigationLog.TAG, "Could not send event $name. React context is null!")
@@ -176,10 +193,20 @@ class EventEmitter(private val reactContext: ReactContext?) {
     }
 
     companion object {
-        /** The sender to the JavaScript that runs now: the React context of the app's `ReactGateway`. */
+        /**
+         * The sender to the JavaScript that runs now: the React context of the app's `ReactGateway`. It goes silent
+         * once that JavaScript goes (a reload): one kept for later sends nothing to the next.
+         */
         @JvmStatic
-        fun current(): EventEmitter =
-            EventEmitter(NavigationApplication.instanceOrNull?.reactGatewayOrNull?.currentReactContext)
+        fun current(): EventEmitter = of(ReloadCoordinator.generation)
+
+        /**
+         * The sender to the JavaScript [generation] (a node's `jsGeneration`): the React context of the app's
+         * `ReactGateway` while that JavaScript runs, silent once it went, so an event of a screen made for the
+         * JavaScript that went never reaches the new one.
+         */
+        internal fun of(generation: Int): EventEmitter =
+            EventEmitter(NavigationApplication.instanceOrNull?.reactGatewayOrNull?.currentReactContext, generation)
 
         // The names of the events, for modules outside the library; inside it, [EventContract] has them with their
         // keys.

package/android/src/main/java/dev/apexnative/navigation/react/events/NavigationState.kt

@@ -0,0 +1,154 @@
+package dev.apexnative.navigation.react.events
+
+import android.os.Handler
+import android.os.Looper
+import dev.apexnative.navigation.react.ReloadCoordinator
+import dev.apexnative.navigation.viewcontrollers.bottomtabs.BottomTabsController
+import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
+import dev.apexnative.navigation.viewcontrollers.parent.ParentController
+import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+
+/**
+ * The one place of the navigation state JavaScript hears (`ANN.NavigationStateChanged`): the screen the user sees and
+ * the selected tab, the last state sent, the update posted for a pass of the main loop and its holds. Every change of
+ * the screen the user sees comes with a screen appearing: a push, a pop, a modal, a tab, a menu.
+ *
+ * Two ways ask for it. The dispatcher asks for one update after the events of a pass ([setNeedsUpdate], coalesced and
+ * held while a `setRoot` shows the modals and the overlays of its layout). A command's answer sends it at once
+ * ([updateNow], never held), once per answer (`CommandAnswer.reportStateNow`): at the end of its transition, else
+ * right before its promise. Each goes only when the state differs from the last one sent, through the JavaScript that
+ * runs now. Main thread only.
+ */
+internal object NavigationState : AppearanceDispatcher.StateUpdates {
+    /** What JavaScript hears: the screen the user sees (`null` for none) and the selected tab (`null` out of tabs). */
+    data class State(val screenId: String?, val screenName: String?, val tab: Int?)
+
+    private val handler by lazy { Handler(Looper.getMainLooper()) }
+
+    // The last state sent to the JavaScript that runs now; none before its first.
+    private var sent: State? = null
+
+    // The one posted update of a pass of the main loop, which checks the holds when it runs.
+    private val updates = Updates(
+        post = { task -> handler.post(task) },
+        generation = { ReloadCoordinator.generation },
+        update = ::updateNow,
+    )
+
+    override fun setNeedsUpdate() {
+        if (EventEmitter.current().canSend) updates.setNeedsUpdate()
+    }
+
+    override fun hold() = updates.hold()
+
+    override fun release() = updates.release()
+
+    /**
+     * Sends the state at once when it differs from the last one sent. A command's answer calls it once, at the end of
+     * its transition or right before its promise: the event and the resolution reach JavaScript in that order, so the
+     * state is new when the `await` of the command goes on. The update posted for the pass then finds nothing new.
+     */
+    override fun updateNow() {
+        val emitter = EventEmitter.current()
+        if (!emitter.canSend) return
+        // The navigation of the activity the commands run in (`Navigators.current`).
+        val navigator = Navigators.current()?.navigator ?: return
+        val next = stateOf(navigator.visibleLayout)
+        if (next == sent) return
+        sent = next
+        emitter.emitNavigationStateChanged(next.screenId, next.screenName, next.tab)
+    }
+
+    /** The new JavaScript has no state yet (`ANN.AppLaunched`): the next one goes to it whatever it is. */
+    fun reset() {
+        sent = null
+    }
+
+    /**
+     * The JavaScript went with its layouts: a hold its `setRoot` left, and an update wanted under it, go with it, so
+     * the new JavaScript's updates are never held by the old one's.
+     */
+    fun javaScriptWent() = updates.dropHolds()
+
+    // The top modal, or the root ([layout]), down to the screen the user sees; overlays don't count. The tab is the
+    // selected one of the nearest tabs the screen is in, the last met on the way down, in a modal too: the tabs
+    // `selectTab` acts on from it. None for a screen out of tabs.
+    internal fun stateOf(layout: ViewController<*>?): State {
+        var tab: Int? = null
+        var current = layout ?: return State(null, null, null)
+        while (current is ParentController<*>) {
+            if (current is BottomTabsController) tab = current.selectedIndex
+            current = current.currentChild ?: return State(null, null, null)
+        }
+        return State(current.id, current.currentComponentName, tab)
+    }
+
+    /**
+     * The posted update and its holds. [setNeedsUpdate] posts one update ([post]), coalesced: the asks of one pass of
+     * the main loop make one, which runs [update] in a later pass. While held, an ask, or a posted update that runs
+     * while held (asked before the hold was taken), only marks one as wanted, and the last release posts it. Released
+     * right before the answer, that update finds nothing new: the state before the answer is sent at once, never
+     * held, and an identical state is never sent twice. Every [hold] has one [release]; a release without a hold does
+     * nothing, so the count never goes below zero. An update keeps the JavaScript it was asked for ([generation]): one
+     * asked by a JavaScript that went before it runs is dropped; a newer ask of the new JavaScript still goes.
+     */
+    internal class Updates(
+        private val post: (() -> Unit) -> Unit,
+        private val generation: () -> Int = { 0 },
+        private val update: () -> Unit,
+    ) {
+        /** The holds not released yet. */
+        var count = 0
+            private set
+
+        // An update was asked while held.
+        private var wanted = false
+        // An update is posted and hasn't run yet.
+        private var scheduled = false
+        // The JavaScript the last ask was for.
+        private var askedIn = 0
+
+        /** Asks for one update in a later pass of the main loop; while held, once the last hold is released. */
+        fun setNeedsUpdate() {
+            askedIn = generation()
+            if (count > 0) wanted = true else schedule()
+        }
+
+        /** The updates asked from now on, and those posted that run from now on, wait for as many [release]s. */
+        fun hold() {
+            count++
+        }
+
+        /** One hold ends; with the last, the update asked while held is posted now. */
+        fun release() {
+            if (count == 0) return
+            count--
+            if (count > 0 || !wanted) return
+            wanted = false
+            schedule()
+        }
+
+        /**
+         * The holds and the update wanted under them go, unreleased: the JavaScript that took them went. An update
+         * already posted stays; it runs only for the JavaScript it was asked for.
+         */
+        fun dropHolds() {
+            count = 0
+            wanted = false
+        }
+
+        private fun schedule() {
+            if (scheduled) return
+            scheduled = true
+            post {
+                scheduled = false
+                // A hold taken since it was posted: the update waits for the release. The JavaScript it was asked for
+                // went: nothing goes to the new one, which hears its first state after its own changes.
+                when {
+                    count > 0 -> wanted = true
+                    askedIn == generation() -> update()
+                }
+            }
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/safearea/SafeAreaView.kt

@@ -10,7 +10,7 @@ import com.facebook.react.uimanager.StateWrapper
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.UIManagerHelper
 import com.facebook.react.views.view.ReactViewGroup
-import dev.apexnative.navigation.react.ScreenInsets
+import dev.apexnative.navigation.react.ScreenEnvironment
 import dev.apexnative.navigation.viewcontrollers.component.ScreenReadiness
 
 /**
@@ -20,7 +20,7 @@ import dev.apexnative.navigation.viewcontrollers.component.ScreenReadiness
 @SuppressLint("ViewConstructor")
 class SafeAreaView(reactContext: ThemedReactContext) : ReactViewGroup(reactContext) {
     private var stopListening: (() -> Unit)? = null
-    private var applied: ScreenInsets.Insets? = null
+    private var applied: ScreenEnvironment.Insets? = null
     private var readySent = false
     private var contentSignalled = false
 
@@ -48,7 +48,7 @@ class SafeAreaView(reactContext: ThemedReactContext) : ReactViewGroup(reactConte
             stopListening?.invoke()
             field = value
             applied = null
-            stopListening = value?.let { id -> ScreenInsets.listenToPadding(id) { applyPadding() } }
+            stopListening = value?.let { id -> ScreenEnvironment.listenToPadding(id) { applyPadding() } }
             // The screen has a safe area view: it counts as rendered once this view says so.
             value?.let(ScreenReadiness::wrapped)
             applyPadding()
@@ -56,7 +56,7 @@ class SafeAreaView(reactContext: ThemedReactContext) : ReactViewGroup(reactConte
 
     private fun applyPadding() {
         val state = stateWrapper ?: return
-        val padding = screenId?.let(ScreenInsets::padding) ?: return
+        val padding = screenId?.let(ScreenEnvironment::padding) ?: return
         if (padding == applied) return
         applied = padding
         state.updateState(
@@ -69,9 +69,9 @@ class SafeAreaView(reactContext: ThemedReactContext) : ReactViewGroup(reactConte
         )
     }
 
-    private fun paddingOf(data: ReadableMap): ScreenInsets.Insets? {
+    private fun paddingOf(data: ReadableMap): ScreenEnvironment.Insets? {
         if (!data.hasKey("top")) return null
-        return ScreenInsets.Insets(data.getDouble("top"), data.getDouble("right"), data.getDouble("bottom"),
+        return ScreenEnvironment.Insets(data.getDouble("top"), data.getDouble("right"), data.getDouble("bottom"),
             data.getDouble("left"))
     }
 
@@ -95,8 +95,9 @@ class SafeAreaView(reactContext: ThemedReactContext) : ReactViewGroup(reactConte
         val reactContext = context as? ReactContext ?: return
         val dispatcher = UIManagerHelper.getEventDispatcher(reactContext) ?: return
         readySent = true
-        dispatcher.dispatchEvent(SafeAreaReadyEvent(UIManagerHelper.getSurfaceId(this), id))
-        screenId?.let(ScreenReadiness::laidOut)
+        val surfaceId = UIManagerHelper.getSurfaceId(this)
+        dispatcher.dispatchEvent(SafeAreaReadyEvent(surfaceId, id))
+        screenId?.let { ScreenReadiness.laidOut(it, surfaceId) }
     }
 
     // The navigation tells whether this view's screen waits: a component of a bar (title, button, background, tab)
@@ -111,12 +112,13 @@ class SafeAreaView(reactContext: ThemedReactContext) : ReactViewGroup(reactConte
     }
 
     // Once, by the screen's id: the container asks the screen's view for the layout React mounts the content without.
-    // On attach too: content added before this view was attached is signalled then.
+    // On attach too: content added before this view was attached is signalled then. The signal names this view's
+    // surface: only the root that shows it takes it as its own.
     private fun signalContent() {
         if (contentSignalled) return
         val id = screenId ?: return
         contentSignalled = true
-        ScreenReadiness.contentRendered(id)
+        ScreenReadiness.contentRendered(id, UIManagerHelper.getSurfaceId(this))
     }
 
     fun drop() {