@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.10

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

@@ -55,6 +55,10 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
     override fun mergeOptions(componentId: String, options: ReadableMap) =
         optionsCommands.mergeOptions(componentId, options)
 
+    // Development (Fast Refresh): the options an edit took out of a screen that shows; as mergeOptions without one.
+    override fun clearOptions(componentId: String, paths: ReadableArray) =
+        optionsCommands.clearOptions(componentId, paths)
+
     override fun push(commandId: String, componentId: String, layout: ReadableMap, promise: Promise) {
         val what = "push the screen '${LayoutReader.idOf(layout)}'"
         runner.run(
@@ -211,7 +215,7 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
         layout: ReadableMap,
         promise: Promise,
     ) {
-        // Android has one column to show screens in: the secondary pane (`showInColumn`).
+        // Android's split view has the primary and the secondary pane; another column rejects (`showInColumn`).
         val what = "show the screen '${LayoutReader.idOf(layout)}' in the '$column' column"
         runner.run(
             name = "showInColumn",
@@ -219,7 +223,7 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
             what = what,
             promise = promise,
             check = { LayoutReader.node(layout, context = appContext()) },
-        ) { node, answer -> navigator().stackCommands.showInColumn(componentId, node, answer, what) }
+        ) { node, answer -> navigator().stackCommands.showInColumn(componentId, column, node, answer, what) }
     }
 
     override fun setColumnShown(
@@ -236,11 +240,11 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
         check = {},
     ) { _, answer -> navigator().stackCommands.setColumnShown(componentId, column, shown, answer) }
 
-    override fun getArrangementState(componentId: String): WritableMap = ArrangementStates.get(componentId)
+    override fun getArrangementState(componentId: String): WritableMap = ScreenEnvironment.getArrangementState(componentId)
 
-    override fun getScreenInsets(componentId: String): WritableMap = ScreenInsets.get(componentId)
+    override fun getScreenInsets(componentId: String): WritableMap = ScreenEnvironment.getScreenInsets(componentId)
 
-    override fun getScreenRegions(componentId: String): WritableMap = ScreenRegions.get(componentId)
+    override fun getScreenRegions(componentId: String): WritableMap = ScreenEnvironment.getScreenRegions(componentId)
 
     // With the activity the user sees, if there is one; the hinge remembers it and goes on with the next activity
     // (`Hinge.attach`).
@@ -295,9 +299,10 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
         })
     }
 
-    // The navigation of the activity the command runs in; the runner checked there is one.
+    // The navigation of the activity the command runs in; the runner checked there is an activity. One without its
+    // navigation yet (or any more) has nowhere to show screens either: the command rejects with the runner's own text.
     private fun navigator(): Navigator =
-        requireNotNull(Navigators.current()?.navigator) { "the activity has no navigation" }
+        Navigators.current()?.navigator ?: throw LayoutException(ErrorTexts.nowhereToShow())
 
     // The app's context, which the colors of the options resolve platform colors with.
     private fun appContext(): Context = reactApplicationContext.applicationContext

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

@@ -1,8 +1,11 @@
 package dev.apexnative.navigation.react
 
 import android.content.Context
+import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
 import dev.apexnative.navigation.options.DefaultOptions
+import dev.apexnative.navigation.options.OptionPaths
 import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.options.OptionsReader
 import dev.apexnative.navigation.system.AppDirection
@@ -10,9 +13,9 @@ import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 
 /**
- * The commands of the options, `setDefaultOptions` and `mergeOptions`: both without a promise. Their options are read
- * on the module thread, in the runner's step before the main task; the main task stores and applies them. What can't be
- * read is logged (`[ApexNavigation] <method>: <text>`); the app goes on.
+ * The commands of the options, `setDefaultOptions`, `mergeOptions` and `clearOptions`: all without a promise. Their
+ * options and paths are read on the module thread, in the runner's step before the main task; the main task stores
+ * and applies them. What can't be read is logged (`[ApexNavigation] <method>: <text>`); the app goes on.
  */
 internal class OptionsCommands(
     private val runner: CommandRunner,
@@ -30,6 +33,11 @@ internal class OptionsCommands(
      * system UI follows (`Navigator.optionsMerged`, `mergeOptions` step 5). Main thread.
      */
     private val merged: (ViewController<*>, Options) -> Unit = { _, _ -> },
+    /**
+     * Repaints what shows in the current navigation activity, as [repaint] does without new default options
+     * (`Navigator.repaint`), after `clearOptions`. Main thread.
+     */
+    private val repaintCurrent: () -> Unit = {},
 ) {
     constructor(runner: CommandRunner, context: () -> Context?) : this(
         runner = runner,
@@ -40,6 +48,7 @@ internal class OptionsCommands(
             Navigators.all().forEach { it.navigator?.defaultOptionsChanged(direction) }
         },
         merged = { node, options -> Navigators.current()?.navigator?.optionsMerged(node, options) },
+        repaintCurrent = { Navigators.current()?.navigator?.repaint() },
     )
 
     /**
@@ -73,7 +82,7 @@ internal class OptionsCommands(
         prepare = { OptionsReader.read(options, context()) },
     ) { read ->
         if (!runner.hasActivity()) {
-            runner.logFailure(MERGE_OPTIONS, ErrorTexts.mergeOptionsNoActivity())
+            runner.logFailure(MERGE_OPTIONS, ErrorTexts.nowhereToShow())
             return@runVoid
         }
         val node = findNode(componentId) ?: return@runVoid
@@ -82,8 +91,37 @@ internal class OptionsCommands(
         merged(node, read.options)
     }
 
+    /**
+     * `clearOptions` (development: Fast Refresh, after an edit took options out of a screen that shows): the values at
+     * [paths] (`topBar.subtitle`; a group's path for the whole group) leave the own options of the node [componentId]
+     * names, through `ViewController.changeOptions` ([OptionPaths.clear]), so it resolves to what the layouts around it
+     * and the defaults give there; the user layer stays. The stack it is in writes its back arrow's visibility into
+     * them again (`StackController.ownOptionsCleared`), then what shows is repainted as after `setDefaultOptions`. No
+     * node with that id, or no path that names an option: nothing, not even a log line. Without an activity: one log
+     * line, as `mergeOptions`.
+     */
+    fun clearOptions(componentId: String, paths: ReadableArray) = runner.runVoid(
+        name = CLEAR_OPTIONS,
+        what = "clear the options of the screen '$componentId'",
+        prepare = {
+            (0 until paths.size()).filter { paths.getType(it) == ReadableType.String }.mapNotNull(paths::getString)
+        },
+    ) { read ->
+        if (!runner.hasActivity()) {
+            runner.logFailure(CLEAR_OPTIONS, ErrorTexts.nowhereToShow())
+            return@runVoid
+        }
+        val node = findNode(componentId) ?: return@runVoid
+        val known = read.filter { OptionPaths.find(node.options, it) != null }
+        if (known.isEmpty()) return@runVoid
+        node.changeOptions { own -> known.forEach { OptionPaths.clear(own, it) } }
+        node.findParentStack()?.ownOptionsCleared(node)
+        repaintCurrent()
+    }
+
     private companion object {
         const val SET_DEFAULT_OPTIONS = "setDefaultOptions"
         const val MERGE_OPTIONS = "mergeOptions"
+        const val CLEAR_OPTIONS = "clearOptions"
     }
 }

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

@@ -0,0 +1,48 @@
+package dev.apexnative.navigation.react
+
+import dev.apexnative.navigation.NavigationApplication
+import dev.apexnative.navigation.utils.UiThread
+
+/**
+ * The calls JavaScript made to the module that may not have reached the main thread yet: [after] runs a task on the
+ * main thread behind every one of them. A screen's first mount reaches the main thread from Fabric while a
+ * `mergeOptions` of the same React commit (its layout effects: `useScreenOptions`) may still be on its way: an
+ * asynchronous method goes from the JavaScript thread to the module's thread (`BridgelessNativeMethodCallInvoker`),
+ * which reads its options there and posts its body to the main thread ([CommandRunner]). The task goes the same way: a
+ * turn of the JavaScript thread, which comes after the task of the commit with its layout effects; then the module's
+ * thread, behind the calls that task made; then the main thread, behind their bodies. Each of the three runs its queue
+ * in order, so every call JavaScript made before the mount has applied when the task runs.
+ *
+ * Without JavaScript (none yet, a reload, a queue that ended) the task is posted to the main thread at once: nothing is
+ * on its way. A queue that ends while the task is on it drops it, and a wait with no limit of its own (a push with
+ * `waitForRender: true` whose content has mounted: the task is its only end) would not end; a queue ends only as the
+ * JavaScript goes (a reload, the host destroyed), and then the layouts go with it (`ReloadCoordinator`), the stack
+ * and its waiting push too. Main thread.
+ */
+internal object PendingCalls {
+    /** A queue the task goes through: it runs what it takes in order, and says false when it ended and took nothing. */
+    fun interface Queue {
+        fun run(task: Runnable): Boolean
+    }
+
+    /** Runs [task] on the main thread, on a later turn, after every call JavaScript made so far has applied there. */
+    fun after(task: () -> Unit) {
+        val context = NavigationApplication.instanceOrNull?.reactGatewayOrNull?.currentReactContext
+            ?.takeIf { it.hasActiveReactInstance() }
+        val js = context?.jsMessageQueueThread?.let { Queue(it::runOnQueue) }
+        val module = context?.nativeModulesMessageQueueThread?.let { Queue(it::runOnQueue) }
+        after(js, module, UiThread::post, task)
+    }
+
+    /**
+     * The way of [after] over the queues given: [js], then [module], then [main]; straight to [main] without one of
+     * them, or from where a queue refused it. The unit tests run it over their own queues.
+     */
+    fun after(js: Queue?, module: Queue?, main: (Runnable) -> Unit, task: () -> Unit) {
+        val onMain = Runnable(task)
+        if (js == null || module == null) return main(onMain)
+        val toMain = Runnable { main(onMain) }
+        val toModule = Runnable { if (!module.run(toMain)) main(onMain) }
+        if (!js.run(toModule)) main(onMain)
+    }
+}

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

@@ -3,6 +3,7 @@ package dev.apexnative.navigation.react
 import android.annotation.SuppressLint
 import android.content.Context
 import android.os.Bundle
+import android.util.Size
 import android.view.MotionEvent
 import android.view.ViewGroup
 import android.widget.FrameLayout
@@ -23,11 +24,17 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.ScrollEventListe
  * is made with the view, from the app's React host, and fills it; it starts once, as the view joins a window, and stops
  * once, on the main thread, as the view is destroyed.
  *
- * Ready once the safe area view of the screen told [ScreenReadiness] that the content rendered into it; a screen
- * without a safe area view (no view ever told anything of its id) once the root view of its surface has children, read
- * on this view's own layout passes. Ready once, ready for good; what waits for it ([whenReady]) runs then, once.
- * Without either, the limits of what waits decide: the view has no timer of its own. It owns the record of its
- * appearance, which the dispatcher of the appearance events holds until the content is ready (`AppearanceDispatcher`).
+ * Ready once the safe area view of the screen, in this view's own surface, told [ScreenReadiness] that the content
+ * rendered into it: the signal of another root with the same id (an old one, another live root of a bar component)
+ * never makes this one ready. A screen without a safe area view (no view ever told anything of its id) is ready once
+ * the root view of its surface has children, read on this view's own layout passes. A root that renders at once
+ * ([rendersAtOnce]: a component of a bar, a tab's cell) marks its id so from before its surface starts until it stops.
+ * Ready once, ready for good; what waits for it ([whenReady]) runs then, once. Its content measures without a height
+ * limit ([contentSize], `ContentHeights`), and the handlers of [setOnContentMounted] hear each mount of Fabric while
+ * the view is in a window.
+ * Without a signal or children, the limits of what waits decide: the view has no timer of its own. It owns the
+ * record of its appearance, which the dispatcher of the appearance events holds until the content is ready
+ * (`AppearanceDispatcher`).
  */
 @SuppressLint("ViewConstructor")
 class ReactView @JvmOverloads constructor(
@@ -36,6 +43,8 @@ class ReactView @JvmOverloads constructor(
     override val componentName: String,
     /** Props given by the native side, over `componentId`: the state of a tab's cell. */
     initialProps: Bundle? = null,
+    /** The root renders at once, without waiting for its layout: a component of a bar or a tab's cell. */
+    private val rendersAtOnce: Boolean = false,
 ) : FrameLayout(context), IReactView {
     private val scrollEventListener = ScrollEventListener()
     private var destroyed = false
@@ -44,7 +53,15 @@ class ReactView @JvmOverloads constructor(
     // What waited for the readiness was told; a question of isReady alone tells nothing, so nothing runs inside it.
     private var readyTold = false
     private val readyListeners = mutableListOf<Runnable>()
-    private var readinessListener: ScreenReadiness.Listener? = null
+    private var listening = false
+    private val mounts = ContentMounts { !destroyed && isAttachedToWindow }
+
+    // What this root hears of its id: only the signals of its own surface.
+    private val readiness = object : ScreenReadiness.Listener {
+        override fun accepts(source: Int): Boolean = ownSource()?.let { it == source } ?: true
+
+        override fun onContentRendered() = checkReadiness()
+    }
 
     // None without the app's host (the unit tests).
     private val surface: ReactSurface?
@@ -59,8 +76,17 @@ class ReactView @JvmOverloads constructor(
      */
     internal var contentChildCount: () -> Int = { (surface?.view as? ViewGroup)?.childCount ?: 0 }
 
+    /**
+     * The id of this root's React surface, which the signals of its safe area view carry: React Native gives it as
+     * the surface starts (none matches before) and never gives it again. Null without a surface: every signal of the
+     * id is its own. The unit tests give their own.
+     */
+    internal var ownSource: () -> Int? = { surface?.surfaceID }
+
     init {
         require(componentId.isNotEmpty()) { "a React root needs the id of its screen" }
+        // Before the surface exists, so its safe area view never asks before the mark is there.
+        if (rendersAtOnce) ScreenReadiness.setRendersAtOnce(componentId, this, true)
         val props = Bundle().apply {
             initialProps?.let(::putAll)
             putString(COMPONENT_ID, componentId)
@@ -90,6 +116,16 @@ class ReactView @JvmOverloads constructor(
     override val touchRoot: ViewGroup?
         get() = surface?.view as? ViewGroup
 
+    override fun contentSize(maxWidth: Int): Size? {
+        val surface = surface ?: return null
+        val height = ContentHeights.surfaceHeight(context, surface, maxWidth) ?: return null
+        return Size(maxWidth, height)
+    }
+
+    override fun setOnContentMounted(key: String, handler: Runnable?) {
+        if (!destroyed) mounts.set(key, handler)
+    }
+
     override fun isReady(): Boolean {
         if (!ready && hasRendered()) ready = true
         return ready
@@ -103,14 +139,9 @@ class ReactView @JvmOverloads constructor(
         if (readyTold) return listener.run()
         readyListeners += listener
         if (isReady()) return checkReadiness()
-        if (readinessListener != null) return
-        val readiness = object : ScreenReadiness.Listener {
-            override fun onLaidOut() = Unit
-
-            override fun onContentRendered() = checkReadiness()
-        }
-        readinessListener = readiness
-        ScreenReadiness.setListener(componentId, readiness)
+        if (listening) return
+        listening = true
+        ScreenReadiness.addListener(componentId, this, readiness)
     }
 
     /**
@@ -126,30 +157,33 @@ class ReactView @JvmOverloads constructor(
         waiting.forEach(Runnable::run)
     }
 
-    // The safe area view said so; without one, the root view of the surface has children.
-    private fun hasRendered(): Boolean = when (ScreenReadiness.isContentRendered(componentId)) {
+    // The safe area view of this root's surface said so; without one, the root view of the surface has children.
+    private fun hasRendered(): Boolean = when (ScreenReadiness.isContentRendered(componentId, readiness)) {
         true -> true
         false -> false
         null -> contentChildCount() > 0
     }
 
     private fun stopListening() {
-        val readiness = readinessListener ?: return
-        readinessListener = null
-        ScreenReadiness.removeListener(componentId, readiness)
+        if (!listening) return
+        listening = false
+        ScreenReadiness.removeListener(componentId, this)
     }
 
     /**
      * Stops the content, once, on the main thread: its appearance ends first (DidDisappear if its WillAppear went,
      * else what is held goes with it), then the surface stops and leaves the host, so a reload doesn't start it again
-     * in the new JavaScript.
+     * in the new JavaScript. A root that renders at once takes its mark away: the last one of its id takes what was
+     * said of the id with it.
      */
     override fun destroy() {
         if (destroyed) return
         AppearanceDispatcher.didDisappear(appearance)
         destroyed = true
         readyListeners.clear()
+        mounts.clear()
         stopListening()
+        if (rendersAtOnce) ScreenReadiness.setRendersAtOnce(componentId, this, false)
         val surface = surface ?: return
         if (started) surface.stop()
         surface.detach()

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

@@ -4,7 +4,7 @@ import com.facebook.react.bridge.ReactContext
 import dev.apexnative.navigation.NavigationActivity
 import dev.apexnative.navigation.nativescreen.NativeScreenCalls
 import dev.apexnative.navigation.react.events.EventEmitter
-import dev.apexnative.navigation.react.events.NavigationStateReporter
+import dev.apexnative.navigation.react.events.NavigationState
 import dev.apexnative.navigation.utils.UiThread
 import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
@@ -39,7 +39,7 @@ internal object ReloadCoordinator {
     /**
      * The JavaScript goes (a reload, or the host is destroyed). Any thread: the number grows at once; the layouts of
      * every navigation activity go on the main thread, with the "reloading" mark, and so do the listeners of the
-     * JavaScript that went (back, hinge).
+     * JavaScript that went (back, hinge) and the holds of the navigation state its `setRoot` left.
      */
     fun onJavaScriptGoes() {
         advance()
@@ -48,6 +48,7 @@ internal object ReloadCoordinator {
             launches.contextGone()
             try {
                 Navigators.all().forEach { it.onReload() }
+                NavigationState.javaScriptWent()
                 BackCallbackState.setJsListeners(false)
                 Hinge.setEnabled(Navigators.current(), false)
             } finally {
@@ -59,13 +60,15 @@ internal object ReloadCoordinator {
     /**
      * The developer tools of [activity] reload the JavaScript ("R R", the reload broadcast): the number grows first, so
      * the navigation of the activity goes without a word to the JavaScript that goes, then its layers go
-     * ([NavigationActivity.onReload]). The host's own reset follows as the reload destroys it. Main thread.
+     * ([NavigationActivity.onReload]) with the holds of the navigation state. The host's own reset follows as the
+     * reload destroys it. Main thread.
      */
     fun resetForDeveloperReload(activity: NavigationActivity) {
         advance()
         Navigator.setReloading(true)
         try {
             activity.onReload()
+            NavigationState.javaScriptWent()
         } finally {
             Navigator.setReloading(false)
         }
@@ -79,8 +82,6 @@ internal object ReloadCoordinator {
         UiThread.runOnMain {
             launches.contextReady(context)
             NativeScreenCalls.failAll { name, componentId -> ErrorTexts.nativeCallReloaded(name, componentId) }
-            // Scroll listeners that found no event dispatcher listen now.
-            ScrollEvents.dispatcherReady()
             Navigators.all().filter { it.isNavigationResumed }.forEach(::launchIfDue)
         }
     }
@@ -92,7 +93,7 @@ internal object ReloadCoordinator {
      */
     fun launchIfDue(activity: NavigationActivity) {
         val context = launches.takeDue(activity, activity.isNavigationResumed) ?: return
-        NavigationStateReporter.reset()
+        NavigationState.reset()
         EventEmitter(context).emitAppLaunched()
     }
 }

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

@@ -0,0 +1,177 @@
+package dev.apexnative.navigation.react
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import dev.apexnative.navigation.react.events.EventContract
+import dev.apexnative.navigation.react.events.EventEmitter
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * What JavaScript knows of each screen's place, by the screen's id, in one record: its safe area (the insets JavaScript
+ * gets and the padding of its safe area view, `useSafeAreaInsets`), its reserved regions (`useReservedRegions`) and,
+ * in a pair, its arrangement (`useArrangement`). The core measures them (`ScreenSafeArea`, [ScreenRegions], the pair's
+ * plan) on the main thread and keeps them here; JavaScript reads them from its own thread for a screen's first render
+ * and gets every change as an event. The record is immutable and replaced at once, so a reader on another thread sees
+ * one whole record. When the screen goes, [remove] clears all of it. As on iOS (`ANNScreenEnvironment`).
+ */
+internal object ScreenEnvironment {
+    /** How much covers each edge of a screen's content, in dp. */
+    data class Insets(val top: Double, val right: Double, val bottom: Double, val left: Double)
+
+    /** A reserved region, in dp from the top left of the screen's content. */
+    data class Region(val x: Double, val y: Double, val width: Double, val height: Double)
+
+    /** Where a screen divides (`division`) and where hardware covers it (`occlusion`). */
+    data class Regions(val division: List<Region>, val occlusion: List<Region>) {
+        val isEmpty: Boolean get() = division.isEmpty() && occlusion.isEmpty()
+    }
+
+    /** Which screen of its pair a screen is, how the pair lies, whether it lies over the other one and is hidden. */
+    data class Arrangement(val placement: String, val layout: String, val front: Boolean, val hidden: Boolean)
+
+    /** Where the changes JavaScript hears go: the events of the screen's JavaScript, or a test's record. */
+    interface Changes {
+        fun insetsChanged(screenId: String, insets: Insets)
+
+        fun regionsChanged(screenId: String, regions: Regions)
+
+        fun arrangementChanged(screenId: String, arrangement: Arrangement)
+    }
+
+    // One screen's record; null for a fact not known yet (not laid out, outside a pair).
+    private data class Record(
+        val insets: Insets? = null,
+        val padding: Insets? = null,
+        val regions: Regions? = null,
+        val arrangement: Arrangement? = null,
+    )
+
+    private val NO_REGIONS = Regions(emptyList(), emptyList())
+    private val records = ConcurrentHashMap<String, Record>()
+    // Main thread only.
+    private val paddingListeners = HashMap<String, MutableSet<() -> Unit>>()
+
+    /**
+     * Keeps the screen's [insets] for JavaScript (what still covers its content) and the [padding] of its safe area
+     * view. Calls the screen's padding listeners when the padding changed, then tells JavaScript when the insets did.
+     * Main thread only.
+     */
+    fun setInsets(screenId: String, insets: Insets, padding: Insets, changes: Changes) {
+        val before = update(screenId) { it.copy(insets = insets, padding = padding) }
+        if (before?.padding != padding) paddingListeners[screenId]?.toList()?.forEach { it() }
+        if (before?.insets != insets) changes.insetsChanged(screenId, insets)
+    }
+
+    /**
+     * Keeps the screen's [regions], and tells JavaScript when they changed; none at first is what JavaScript reads
+     * before the first layout, so it isn't told. Main thread only.
+     */
+    fun setRegions(screenId: String, regions: Regions, changes: Changes) {
+        val before = update(screenId) { it.copy(regions = regions) }?.regions
+        if (before == regions || (before == null && regions.isEmpty)) return
+        changes.regionsChanged(screenId, regions)
+    }
+
+    /** Keeps the screen's [arrangement], and tells JavaScript when it changed and [notify] holds. Main thread only. */
+    fun setArrangement(screenId: String, arrangement: Arrangement, notify: Boolean, changes: Changes) {
+        val before = update(screenId) { it.copy(arrangement = arrangement) }?.arrangement
+        if (before == arrangement || !notify) return
+        changes.arrangementChanged(screenId, arrangement)
+    }
+
+    /** The padding of the screen's safe area view; none before the screen was laid out. Any thread. */
+    fun padding(screenId: String): Insets? = records[screenId]?.padding
+
+    /** The insets JavaScript gets; none before the screen was laid out. Any thread. */
+    fun insets(screenId: String): Insets? = records[screenId]?.insets
+
+    /** The screen's reserved regions; none before its first layout. Any thread. */
+    fun regions(screenId: String): Regions? = records[screenId]?.regions
+
+    /** The screen's arrangement; none outside a pair. Any thread. */
+    fun arrangement(screenId: String): Arrangement? = records[screenId]?.arrangement
+
+    /**
+     * Calls `listener` when the padding of the screen changes; returns the function that stops it. Main thread only.
+     */
+    fun listenToPadding(screenId: String, listener: () -> Unit): () -> Unit {
+        paddingListeners.getOrPut(screenId) { LinkedHashSet() }.add(listener)
+        return {
+            paddingListeners[screenId]?.let {
+                it.remove(listener)
+                if (it.isEmpty()) paddingListeners.remove(screenId)
+            }
+        }
+    }
+
+    /**
+     * Forgets everything kept for the screen. Its padding listeners stay: a live safe area view keeps listening while
+     * it keeps the id, and stops itself.
+     */
+    fun remove(screenId: String) {
+        records.remove(screenId)
+    }
+
+    /** `getScreenInsets`: `{ top, right, bottom, left }`, empty before the screen was laid out. Any thread. */
+    fun getScreenInsets(screenId: String): WritableMap = insets(screenId)?.let(::toMap) ?: Arguments.createMap()
+
+    /** `getScreenRegions`: `{ division, occlusion }`, empty lists before the first layout. Any thread. */
+    fun getScreenRegions(screenId: String): WritableMap = toMap(regions(screenId) ?: NO_REGIONS)
+
+    /** `getArrangementState`: `{ placement, layout, front, hidden }`, empty outside a pair. Any thread. */
+    fun getArrangementState(screenId: String): WritableMap =
+        arrangement(screenId)?.let(::toMap) ?: Arguments.createMap()
+
+    /** The changes as events through [emitter], the one of the JavaScript the screen was made for. */
+    fun changesOf(emitter: EventEmitter): Changes = object : Changes {
+        override fun insetsChanged(screenId: String, insets: Insets) =
+            emitter.emitScreenInsetsChanged(screenId, toMap(insets))
+
+        override fun regionsChanged(screenId: String, regions: Regions) =
+            emitter.emitScreenRegionsChanged(screenId, toMap(regions))
+
+        override fun arrangementChanged(screenId: String, arrangement: Arrangement) =
+            emitter.emitArrangementChanged(screenId, toMap(arrangement))
+    }
+
+    // Replaces the screen's record at once with [change] of it; returns the record before, null for a new screen.
+    private fun update(screenId: String, change: (Record) -> Record): Record? {
+        var before: Record? = null
+        records.compute(screenId) { _, old ->
+            before = old
+            change(old ?: Record())
+        }
+        return before
+    }
+
+    private fun toMap(value: Insets): WritableMap = Arguments.createMap().apply {
+        putDouble(EventContract.ScreenInsetsChanged.TOP, value.top)
+        putDouble(EventContract.ScreenInsetsChanged.RIGHT, value.right)
+        putDouble(EventContract.ScreenInsetsChanged.BOTTOM, value.bottom)
+        putDouble(EventContract.ScreenInsetsChanged.LEFT, value.left)
+    }
+
+    private fun toMap(value: Regions): WritableMap = Arguments.createMap().apply {
+        putArray(EventContract.ScreenRegionsChanged.DIVISION, toArray(value.division))
+        putArray(EventContract.ScreenRegionsChanged.OCCLUSION, toArray(value.occlusion))
+    }
+
+    private fun toArray(regions: List<Region>): WritableArray = Arguments.createArray().apply {
+        for (region in regions) {
+            pushMap(Arguments.createMap().apply {
+                putDouble(EventContract.ScreenRegionRect.X, region.x)
+                putDouble(EventContract.ScreenRegionRect.Y, region.y)
+                putDouble(EventContract.ScreenRegionRect.WIDTH, region.width)
+                putDouble(EventContract.ScreenRegionRect.HEIGHT, region.height)
+            })
+        }
+    }
+
+    private fun toMap(value: Arrangement): WritableMap = Arguments.createMap().apply {
+        putString(EventContract.ArrangementChanged.PLACEMENT, value.placement)
+        putString(EventContract.ArrangementChanged.LAYOUT, value.layout)
+        putBoolean(EventContract.ArrangementChanged.FRONT, value.front)
+        putBoolean(EventContract.ArrangementChanged.HIDDEN, value.hidden)
+    }
+}