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

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [1.0.0-alpha.6](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.5...v1.0.0-alpha.6) (2026-10-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* leave the bottom edge of a screen free by default ([#49](https://github.com/apexnative/navigation/issues/49))
+
+### Features
+
+* a sheet's back preview on android, lighter tabs and top bar, the compatibility mode on ios 27 ([#46](https://github.com/apexnative/navigation/issues/46)) ([24d333d](https://github.com/apexnative/navigation/commit/24d333dd43fc5e056786f22dc8d7f1a0ff82a1ad))
+* leave the bottom edge of a screen free by default ([#49](https://github.com/apexnative/navigation/issues/49)) ([b6bb165](https://github.com/apexnative/navigation/commit/b6bb165152114fb2886bd3c4ee55560c418f0cbe))
+* **tabs:** choose whether a tab switch animates with bottomTabs.switchAnimation ([#52](https://github.com/apexnative/navigation/issues/52)) ([c6185b6](https://github.com/apexnative/navigation/commit/c6185b6b42574cff671def1ebdf8aa4f5e4be681))
+
+
+### Bug Fixes
+
+* an explicit top edge stays free under a large title ([#53](https://github.com/apexnative/navigation/issues/53)) ([188a89e](https://github.com/apexnative/navigation/commit/188a89e8d160c071f91cc010ed43ccc0683e12b3))
+* shared elements fly turned and scaled views the same way on ios and android ([#50](https://github.com/apexnative/navigation/issues/50)) ([bf63ab6](https://github.com/apexnative/navigation/commit/bf63ab624d33ff9295af297ce6506206b1bfa0e6))
+* the custom tab row moves with its tabs on android, and tab cells get selected and badge ([#51](https://github.com/apexnative/navigation/issues/51)) ([fd8f41d](https://github.com/apexnative/navigation/commit/fd8f41d2efd108741672220c54253a86704929a5))
+
+
+### Performance Improvements
+
+* **ios:** render a preview's screen when a press on its view starts ([#48](https://github.com/apexnative/navigation/issues/48)) ([4a57d1a](https://github.com/apexnative/navigation/commit/4a57d1aee1df7690dbde4c7d08dca2a70773d1f5))
+
+## [1.0.0-alpha.5](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2026-10-23)
+
+
+### Features
+
+* android back options, a launch screen copy from UILaunchScreen, modal and back fixes ([#43](https://github.com/apexnative/navigation/issues/43)) ([29f311e](https://github.com/apexnative/navigation/commit/29f311e318134f284a0c6279e6c86e15612c9343))
+
+
+### Bug Fixes
+
+* **android:** send the state of a tab switch from code at its start ([#44](https://github.com/apexnative/navigation/issues/44)) ([34d03d0](https://github.com/apexnative/navigation/commit/34d03d0214cf09e14329d0bae51e47d46063f054))
+* **hooks:** measure agent folder scopes from the worktree a file is in ([#42](https://github.com/apexnative/navigation/issues/42)) ([d306137](https://github.com/apexnative/navigation/commit/d306137534d3ba551fab8a7346c7ad7300c0faf7))
+
 ## [1.0.0-alpha.4](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2026-10-23)
 
 

package/README.md

@@ -97,7 +97,7 @@ navigation.push('Details', { props: { title: 'Order 42' } });
   each other: tabs of stacks, a stack in a modal, tabs in a side menu.
 - **Screen UI as options:** the top bar, bar buttons, search, the toolbar and the floating action button, the status
   bar and the system bars.
-- **No safe area code:** every screen keeps its content clear of the bars, the cutout and the home indicator by itself.
+- **No safe area code:** every screen keeps its top and sides clear of the bars and the cutout by itself; the bottom is free, and a list adds `useSafeAreaInsets().bottom`.
 - **Native screens:** SwiftUI, UIKit and Compose screens are pushed, presented and put in tabs the same way as React
   screens.
 - **One React tree when you want it:** each screen is its own React root by default; with `appProvider` all screens

package/android/CLAUDE.md

@@ -22,10 +22,10 @@ top-level folder. Main thread only, unless a line says otherwise.
   `Variant`, `ThemeColour`); `parsers/` reads them tolerantly from React Native data.
 - `react/`: the way in and out: `NavigationTurboModule`, `CommandRunner`, `CommandAnswer`, `ErrorTexts`,
   `OptionsCommands`, `PendingCalls` (a task behind the calls JavaScript made), `ReloadCoordinator`, `ReactGateway`,
-  `ReactView` (a React root), the stores (`ScreenInsets`, `ScreenRegions`, `ArrangementStates`, `Hinge`, `StartInfo`),
-  `LaunchLink`, `ScrollEvents`.
+  `ReactView` (a React root), the stores (`ScreenEnvironment`: a screen's insets, padding, regions and pair state;
+  `Hinge`, `StartInfo`), `ScreenRegions` (measures a screen's regions), `LaunchLink`, `ScrollEvents`.
 - `react/events/`: `AppearanceDispatcher`, `ScreenAppearance`, `EventEmitter`, `EventContract` (made by
-  `scripts/contract.mjs`), `NavigationStateReporter`, `ComponentType`.
+  `scripts/contract.mjs`), `NavigationState`, `ComponentType`.
 - `viewcontrollers/viewcontroller/`: `ViewController` (the base of every node), `Presenter`, `IReactView` (what a
   screen shows), `ScrollEventListener`.
 - `viewcontrollers/child/`, `parent/`: `ChildController` and the registry; `ParentController` (the base of layouts),
@@ -44,7 +44,7 @@ top-level folder. Main thread only, unless a line says otherwise.
 - `viewcontrollers/sidemenu/`: `SideMenuController`, `SideMenuMotion`, `SideMenuPresenter`, `SideMenuRules`.
 - `viewcontrollers/splitview/`, `arrangement/`: the split view and the pair (modules, plus the core's
   `SplitViewPresenter`).
-- `viewcontrollers/modal/`, `overlay/`: `ModalCoordinator`, `ModalRecord`, `ModalViews`, `ModalSheet`;
+- `viewcontrollers/modal/`, `overlay/`: `ModalCoordinator`, `ModalRecord`, `ModalViews`, `ModalSheet`, `SheetBack`;
   `OverlayCoordinator`, `OverlayRecord`, `OverlayViews`, `OverlayTouches`.
 - `views/`: Android views and animators, no rules: `component/`, `externalcomponent/`, `stack/` (`StackLayout`,
   `topbar/`, `fab/`), `bottomtabs/`, `sidemenu/`, `animations/` (curves, `SideAnimator`, `AnimationRules`), `element/`
@@ -78,7 +78,8 @@ top-level folder. Main thread only, unless a line says otherwise.
   `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.
+  `stackPoppedByBack` of the layouts; of a sheet's dismissal: `viewcontrollers/modal/SheetBack.kt`,
+  `ModalCoordinator.backTargetSheet`, `ModalSheet.BackPreview`.
 - 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`;
@@ -87,7 +88,7 @@ top-level folder. Main thread only, unless a line says otherwise.
   `views/stack/topbar/search/`.
 - Tabs: `viewcontrollers/bottomtabs/BottomTabsController.kt`, `BottomTabsPresenter.kt`, `TabSelection.kt`,
   `TabItems.kt`, `TabsRoom.kt`; `views/bottomtabs/`; `customrow/BottomTabsCustomRowOptions.kt`,
-  `viewcontrollers/bottomtabs/CustomTabRowPlacer.kt`.
+  `viewcontrollers/bottomtabs/CustomTabRowGeometry.kt`.
 - Modals and sheets: `viewcontrollers/modal/ModalCoordinator.kt`, `ModalRecord.kt`, `ModalViews.kt`, `ModalSheet.kt`,
   `ModalAnimations.kt`; `options/SheetOptions.kt`.
 - Overlays: `viewcontrollers/overlay/OverlayCoordinator.kt`, `OverlayViews.kt`, `OverlayTouches.kt`.
@@ -96,36 +97,37 @@ top-level folder. Main thread only, unless a line says otherwise.
 - Split view: `viewcontrollers/splitview/SplitViewController.kt`, `SplitViewLayout.kt`, `SplitPanes.kt`,
   `SplitViewPresenter.kt`; `StackCommands.showInColumn`.
 - Pair (arrangement): `viewcontrollers/arrangement/ArrangementController.kt`, `ArrangementPlanner.kt`,
-  `ArrangementLayout.kt`, `ArrangementDefinition.kt`; `react/ArrangementStates.kt`.
+  `ArrangementLayout.kt`, `ArrangementDefinition.kt`; the pair's state in `react/ScreenEnvironment.kt`.
 - Preview, key commands: iOS only. The options are parsed and merged (`options/PreviewOptions.kt`,
   `options/KeyCommandOptions.kt`) and not applied; `dismissPreview` does nothing.
 - Animations and transitions: `views/animations/` (`AnimationRules`, `Curves`, `SideAnimator`, `ValueInterpolation`,
-  `FadeThrough`, `SystemTransition`); `views/element/` (`ElementTransitions`, `TransitionLayer`, `TargetsWait`,
-  `animators/`); `options/StackAnimationOptions.kt`, `ViewAnimationOptions.kt`.
+  `FadeThrough`, `SystemTransition`, `AnimationLayer`: the hardware layer of a fade); `views/element/`
+  (`ElementTransitions`, `TransitionLayer`, `TargetsWait`, `animators/`); `options/StackAnimationOptions.kt`,
+  `ViewAnimationOptions.kt`.
 - System bars: `system/SystemUiOwner.kt`, `SystemUiLayers.kt`, `SystemUiRules.kt`, `SystemUiWindow.kt`,
   `AppDirection.kt`; `viewcontrollers/parent/ContainerBackground.kt`.
 - Events and state: `react/events/AppearanceDispatcher.kt`, `ScreenAppearance.kt`, `EventEmitter.kt`,
-  `NavigationStateReporter.kt`; `react/CommandAnswer.kt`.
+  `NavigationState.kt`; `react/CommandAnswer.kt`.
 - Options (parsing, merging): `options/Options.kt`, `OptionsReader.kt`, `OptionsCache.kt`, `DefaultOptions.kt`,
   `params/`, `parsers/`; `viewcontrollers/viewcontroller/ViewController.kt` (resolution).
 - Error texts and answers: `react/ErrorTexts.kt` and `react/CommandContract.kt`, made by `scripts/contract.mjs` from
   `src/interfaces/contract/errors.json` and `commands.json`.
 - Links: `react/LaunchLink.kt`, `NavigationActivity.kt` (`onNewIntent`); `react/StartInfo.kt`.
-- Hinge and regions: `react/Hinge.kt`, `react/ScreenRegions.kt`, `react/ScreenInsets.kt`, `utils/WindowFolds.kt`.
+- Hinge and regions: `react/Hinge.kt`, `react/ScreenRegions.kt`, `react/ScreenEnvironment.kt`, `utils/WindowFolds.kt`.
 - Native screens: `nativescreen/NativeScreenContext.kt`, `NativeScreenCalls.kt`, `NativeScreenCreator.kt`;
   `viewcontrollers/externalcomponent/`.
 - Slots: `slots/SlotHost.kt`, `SlotView.kt`, `SlotScreenView.kt`, `SlotContainers.kt` (containers and slot views by
   slot id: a change goes straight to the views of its id, `SlotViews.kt`), `SlotViewManager.kt`.
 - Safe area: `safearea/SafeAreaView.kt`, `SafeAreaViewManager.kt`; `viewcontrollers/component/ScreenReadiness.kt`;
-  `react/ScreenInsets.kt`.
+  `react/ScreenEnvironment.kt`.
 - The C++ of `ANNSlot`, `ANNSafeAreaView`: `android/src/main/jni/CMakeLists.txt`, `ApexNavigationSpec.h`; sources in
   `ios/cpp/`.
 
 ## Threads
 
 - **JS thread.** The sync getters `getScreenInsets`, `getScreenRegions`, `getArrangementState`, `getHinge`,
-  `getStartInfo` read stores (`ConcurrentHashMap` in `ScreenInsets`, `ScreenRegions`, `ArrangementStates`; `@Volatile`
-  in `Hinge`). They never touch a node.
+  `getStartInfo` read stores (one `ConcurrentHashMap` of immutable records in `ScreenEnvironment`; `@Volatile` in
+  `Hinge`). They never touch a node.
 - **Module thread.** The `check` of every command with a promise: `LayoutReader` and, through it, `OptionsReader` (also
   for `setDefaultOptions`, `mergeOptions` and the options of `dismissModal`, in the runner's `prepare` step);
   `ReadableJson` for native-screen props. The registry of native screens is read under its lock. Images are not loaded
@@ -172,6 +174,9 @@ top-level folder. Main thread only, unless a line says otherwise.
   `cancel` it on every exit.
 - A layer that waits to show must be a `WaitingLayer` and leave on every exit (show, supersede, destroy, root gone).
 - Never resolve a promise yourself: only `CommandAnswer` knows whether its JavaScript went and sends the state first.
+- An event of a screen goes to the JavaScript the screen was made for: `EventEmitter.of(node.jsGeneration)`, or an
+  emitter kept from then (it goes silent after a reload). React Native keeps one context across a reload, so a sender
+  taken from the context at event time tells the new JavaScript about a screen it never had.
 - A signal that comes inside a layout pass or a view's attach must not move views there; the stack posts readiness
   (`deliver`).
 - A step that runs later (a timer, a readiness signal, an animator's end, a user callback) runs under no runner: it
@@ -206,6 +211,10 @@ top-level folder. Main thread only, unless a line says otherwise.
 - 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.
+- What back does (`Navigator.canHandleBack`, `keepsBackFromSystem`) is computed on events, not before each frame: a
+  new path that changes it without a command (a gesture, an animator's end, a layout's switch) calls
+  `BackCallbackState.update`, or the system's back leaves the app where it should go back. Debug builds log a missed
+  one (`BackCallbackCheck`).
 - 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

@@ -10,7 +10,7 @@ otherwise.
 ```
 JS ─ ANNTurboModule (codegen NativeANNTurboModuleSpec)
  │      sync getters answer on the JS thread from stores the main thread fills
- │      (ScreenInsets, ScreenRegions, ArrangementStates, Hinge, StartInfo)
+ │      (ScreenEnvironment, Hinge, StartInfo)
  ▼ module thread
 react/NavigationTurboModule      one override per method
  │  layout/LayoutReader ► options/OptionsReader     the whole layout read and checked, its options read
@@ -31,7 +31,7 @@ coordinators: RootCoordinator · StackQueue (one per stack) · ModalCoordinator
 presenters: ComponentPresenter · StackPresenter + TopBarPresenter · BottomTabsPresenter · SideMenuPresenter ·
             SplitViewPresenter · system/SystemUiOwner (status bar, navigation bar, orientation, keyboard)
  ▼
-react/events/AppearanceDispatcher ─► NavigationStateReporter ─► EventEmitter ─► ANN.* events ─► JS
+react/events/AppearanceDispatcher ─► NavigationState ─► EventEmitter ─► ANN.* events ─► JS
 ```
 
 - **Way in.** `NavigationTurboModule` only turns a method into a `CommandRunner` call; it holds no navigation logic. It
@@ -84,11 +84,12 @@ react/events/AppearanceDispatcher ─► NavigationStateReporter ─► EventEmi
    `AppearanceDispatcher.beginTransition`: **`ComponentWillAppear`** of Profile. The transition runs
    (`StackTransitions`, `SystemTransition`, or the screens' own animation, `AnimationRules.stackIsOwn`).
 8. **End.** `finishPush` calls `AppearanceDispatcher.endTransition`: **`ComponentDidDisappear`** of Home, then
-   **`ComponentDidAppear`** of Profile, then `reportState` (**`NavigationStateChanged`**, only if it changed), then the
-   transition's own events (none for a push), then `CommandAnswer.resolve` with Profile's id.
-9. **Answer.** `resolve` sends the state once more if it changed (`AnswerEvents.beforeAnswer`), resolves the promise,
-   then sends **`CommandCompleted`** (`CommandContract.COMPLETED`). After the task, `BackCallbackState.update` recomputes what
-   back does.
+   **`ComponentDidAppear`** of Profile, then the answer's one state step (`CommandAnswer.reportStateNow`:
+   **`NavigationStateChanged`**, only if it changed), then the transition's own events (none for a push), then
+   `CommandAnswer.resolve` with Profile's id.
+9. **Answer.** `resolve` sends the state only when no transition sent it (`reportStateNow` runs once per answer: a
+   `setRoot` with layout modals sends it here), resolves the promise, then sends **`CommandCompleted`**
+   (`CommandContract.COMPLETED`). After the task, `BackCallbackState.update` recomputes what back does.
 
 The events go from the main thread, synchronously, through `EventEmitter.current()`; the promise is answered once.
 
@@ -127,13 +128,16 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
   `beginTransition` starts the appearances; `endTransition` runs what left, then what came, then the state, then the
   transition's events, then the answer. Events asked before a screen's content is ready are held in its
   `ScreenAppearance` (until the content mounts or `HOLD_LIMIT_MILLIS`).
-- **Navigation state.** `AppearanceDispatcher.state` (`StateUpdates`) is the one way to ask for it: `StateHold`
-  coalesces the asks to one posted update per pass of the main loop and keeps it while held; the update calls
-  `NavigationStateReporter.updateNow`. `updateNow` also runs before every answer of a command that changes what shows
-  (`CommandAnswer`) and is never held. It reads the navigator through `Navigators.current()`, and `stateOf` finds the
+- **Navigation state.** `NavigationState` owns it: the last state sent, the walk (`stateOf`), the posted update and its
+  holds (`NavigationState.Updates`). `AppearanceDispatcher.state` (`StateUpdates`) is the one way to ask for it:
+  `setNeedsUpdate` coalesces the asks to one posted update per pass of the main loop and keeps it while held; the
+  update calls `updateNow`. A command's answer sends it once, at once and never held (`CommandAnswer.reportStateNow`):
+  at the end of its transition, else right before its promise for the commands that change what shows; nothing for a
+  JavaScript that went. It reads the navigator through `Navigators.current()`, and `stateOf` finds the
   `tab` as the nearest tabs of the visible screen (the last tabs met walking down from the visible layout). A `setRoot`
   with layout modals or overlays takes `AppearanceDispatcher.StateUpdates.hold()` and releases it right before its
-  answer, so JavaScript hears one state; every hold has one `release()`.
+  answer, so JavaScript hears one state; every hold has one `release()`. The holds go when the JavaScript goes
+  (`NavigationState.javaScriptWent`), so one left by its `setRoot` never holds the next JavaScript's updates.
 - **Answer.** `CommandAnswer`: resolves or rejects once, and nothing once the JavaScript went. The id a stack entry
   answers with is one rule, `StackController.answerIdOf` (the queue asks it through `StackQueue.Host.answerIdOf` with
   an `AnswerKind`): `push` answers the entry's own id (a pair's), every other command the screen it stands for (a
@@ -141,7 +145,11 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
 - **Stack queue.** `StackQueue`: every command, back and return of a container goes through it; it keeps `entries`
   (what JavaScript sees) and `shown` (what the container shows) and answers once.
 - **Screen readiness.** `ScreenReadiness` (by id; written by `SafeAreaView`) and `ContentReadiness` (the `Readiness`
-  the waits ask, through `IReactView.isReady`).
+  the waits ask, through `IReactView.isReady`). As on iOS, the signals are kept (a listener that comes later hears them
+  at once), an id has a listener per key (several roots of one bar component), and each signal carries the React
+  surface it came from: a `ReactView` takes only its own surface's, so an old root with the same id never makes a new
+  one ready. An id renders at once while a root marks it (`ReactView`'s `rendersAtOnce`); the last one takes the id's
+  signals with it. A screen's id is cleared as the screen is made and destroyed, everything on reload.
 - **Render wait.** `RenderWait`: the one wait for screens to render, used by `RootCoordinator`, `ModalCoordinator`,
   `OverlayCoordinator` and `StackQueue`; `RenderWait.waitedScreens` walks `ParentController.waitedChildren()` at every
   level. What differs between users are values (limit, bar phase, unknown-content rule), never steps.
@@ -171,7 +179,8 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
 - **Back.** `NavigationActivity.passBack` → `ReactGateway.onBackPressed` (JavaScript's `BackHandler`) →
   `invokeDefaultOnBackPressed` → `Navigator.handleBack` → `ModalCoordinator.handleBack` → the root's
   `ParentController.handleBack` → `StackController.handleBack` → `StackQueue.cut`. `BackCallbackState` keeps the
-  system callback enabled only while back has something to do.
+  system callback enabled only while back has something to do, computed again on the events that change it (its KDoc
+  lists them), never before each frame; debug builds check it (`BackCallbackCheck`).
 - **Error texts.** `ErrorTexts`: one function per text, the same words as iOS, made with iOS's from
   `src/interfaces/contract/errors.json` (`scripts/contract.mjs`). JavaScript adds `[navigation] <command>:`.
 - **Event names and keys.** `EventContract`, made from the event types of `src/interfaces/`; `EventEmitter` and the
@@ -179,7 +188,7 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
 - **Room for the bars.** A screen's room at the top and bottom is `ScreenFrame` with `ScreenSafeArea` and the
   `ParentController` room hooks (`getTopInset`, `keepsStatusBarRoomOf`, …). A screen in a pair forwards its room to
   the pair (`ScreenFrame.applyRoom`), and the pair's `getTopInset` uses the screens' rule (`ScreenFrame.topRoomOf`)
-  with the options it shows with. A view's place in the window for the safe area (the React root, the stack's header
+  with the options it shows with. The bottom edge is not padded by default (only `'bottom'` in the edges pads it); `roomPadding` still shrinks the view for an opaque navigation bar and the keyboard. A view's place in the window for the safe area (the React root, the stack's header
   bottom in `headerBottomOf`, the tabs' top in `tabsTopOf`) is `RestPlace`: from layout, without translations, a sheet
   at rest.
 - **A container's own move.** A container that moves children in or out of the window without a command (the split
@@ -200,9 +209,9 @@ Modules are the feature classes that plug into the core through its contract (th
   (`SlotHost`, `SlotView`, `SlotContainers`), safe area (`SafeAreaView`), native screens (`nativescreen/`), splash
   (`splash/`), animations (`FadeThrough`, `SystemTransition`, `TransitionTargets`, three element animators), utils
   (`MaterialTheme`, `NavigationLog`, `awaitBarComponents`, `whenDrawn`).
-- **Stores and singletons:** regions (`Hinge`, `ScreenInsets`, `ScreenRegions`, `WindowFolds`), pair state
-  (`ArrangementStates`), links (`LaunchLink`, `StartInfo`), events (`NavigationStateReporter`), commands
-  (`BackCallbackState`), stack (`PreparedFrame`).
+- **Stores and singletons:** a screen's environment (`ScreenEnvironment`: its insets and padding, its regions as
+  `ScreenRegions` measures them, its pair state), the window (`Hinge`, `WindowFolds`), links (`LaunchLink`,
+  `StartInfo`), events (`NavigationState`), commands (`BackCallbackState`), stack (`PreparedFrame`).
 
 How they plug in:
 
@@ -226,4 +235,8 @@ How they plug in:
 - **Core code in a module's folder:** `viewcontrollers/splitview/SplitViewPresenter.kt`, `slots/SlotScreenView.kt`,
   and in `views/animations/` and `views/element/` everything except the files named above.
 - **Stores** are written on the main thread by the core and read from any thread; they are cleared with their nodes and on
-  reload.
+  reload. A screen's environment is one immutable record per id in `ScreenEnvironment` (insets for JavaScript, padding,
+  regions, pair state), replaced at once; the screen's node clears it with one `remove` when it is destroyed, unless a
+  later node has its id; the padding listeners of its safe area views stay until the views stop. Their events, and
+  the search's, go through the emitter of the JavaScript the screen was made for
+  (`EventEmitter.of(node.jsGeneration)`); the hinge keeps the `EventEmitter.current()` of the call that turned it on.

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

@@ -35,6 +35,8 @@ import dev.apexnative.navigation.splash.SplashTheme
 import dev.apexnative.navigation.splash.SplashView
 import dev.apexnative.navigation.system.SystemUiWindow
 import dev.apexnative.navigation.utils.MaterialTheme
+import dev.apexnative.navigation.viewcontrollers.modal.SheetBack
+import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackCheck
 import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
@@ -71,38 +73,73 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     // 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.
+    // .BackGesture`), and one that would dismiss a sheet previews its hide as Material's sheets do (`SheetBack`), its
+    // release closing it as a drag down does; JavaScript's listeners hear back first, so with them there is no preview.
     private val backCallback = object : OnBackPressedCallback(false) {
         override fun handleOnBackStarted(backEvent: BackEventCompat) {
             backGesture = null
+            sheetGesture = null
+            val navigator = navigator ?: return
+            backCheck?.atBack(navigator)
             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)
+            val stack = navigator.stackPoppedByBack()
+            if (stack != null) {
+                backGesture = stack.startBackGesture(backEvent.swipeEdge == BackEventCompat.EDGE_LEFT, backEvent.touchY)
+                return
+            }
+            sheetGesture = navigator.sheetDismissedByBack()?.startBackPreview(backEvent)
         }
 
         override fun handleOnBackProgressed(backEvent: BackEventCompat) {
             backGesture?.progress(backEvent.progress, backEvent.touchY)
+            sheetGesture?.progress(backEvent)
         }
 
         override fun handleOnBackCancelled() {
             backGesture?.cancel()
             backGesture = null
+            sheetGesture?.cancel()
+            sheetGesture = null
+            navigator?.let(BackCallbackState::update)
         }
 
         override fun handleOnBackPressed() {
+            navigator?.let { backCheck?.atBack(it) }
             val gesture = backGesture
             backGesture = null
-            if (gesture?.commit() == true) BackCallbackState.update() else passBack()
+            val sheet = sheetGesture
+            sheetGesture = null
+            when {
+                gesture?.commit() == true -> BackCallbackState.update()
+                sheet != null && commitSheet(sheet) -> 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 {
-        navigator?.let(BackCallbackState::update)
+    // The back gesture that previews a sheet's hide now; none.
+    private var sheetGesture: SheetBack.Gesture? = null
+
+    // A sheet's preview released: the sheet goes as the user's drag down closes it, and back doesn't go on (no
+    // `passBack`, which would dismiss it a second time). A command that changed what back does since the gesture
+    // started (a push in the sheet, a modal over it, a hold) leaves it to the usual back, the sheet back in place.
+    private fun commitSheet(gesture: SheetBack.Gesture): Boolean {
+        if (navigator?.sheetDismissedByBack() !== gesture.sheet) {
+            gesture.cancel()
+            return false
+        }
+        return gesture.commit()
+    }
+
+    // Debug builds only: the check that what back does never changes without its trigger (BackCallbackState), sampled
+    // before frames and at back events. It only logs; release builds have neither the check nor the listener.
+    private val backCheck = if (BuildConfig.DEBUG) BackCallbackCheck() else null
+    private val backCheckBeforeFrame = ViewTreeObserver.OnPreDrawListener {
+        val navigator = navigator
+        if (navigator != null) backCheck?.sample(navigator, SystemClock.uptimeMillis())
         true
     }
     private var frameObserver: ViewTreeObserver? = null
@@ -143,7 +180,9 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
         SlotHost.attachIfStarted(this)
         reactGateway.onActivityCreated(this)
         onBackPressedDispatcher.addCallback(this, backCallback)
-        frameObserver = window.decorView.viewTreeObserver.also { it.addOnPreDrawListener(backBeforeFrame) }
+        if (backCheck != null) {
+            frameObserver = window.decorView.viewTreeObserver.also { it.addOnPreDrawListener(backCheckBeforeFrame) }
+        }
         // The activity's system UI: its owner remembers the theme's colors and the manifest's orientation now, before
         // anything changes them.
         navigator.systemUi.start(SystemUiWindow.of(this))
@@ -218,6 +257,8 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
         isNavigationResumed = true
         // The root, the modals and the overlays lay out again; nothing is sent.
         navigator?.onResume()
+        // A safety net: what back does changes on its own triggers, and the system asks the callback from here on.
+        navigator?.let(BackCallbackState::update)
         if (developerSupport() != null) reloadBroadcast.register()
         ReloadCoordinator.launchIfDue(this)
     }
@@ -239,6 +280,8 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     override fun onWindowFocusChanged(hasFocus: Boolean) {
         super.onWindowFocusChanged(hasFocus)
         if (reactGateway.currentReactContext != null) reactGateway.host.onWindowFocusChange(hasFocus)
+        // A safety net, as at onResume: back after a dialog or another window over the activity.
+        if (hasFocus) navigator?.let(BackCallbackState::update)
     }
 
     override fun onUserLeaveHint() {
@@ -302,9 +345,11 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
         splashHold = null
         reloadBroadcast.release()
         navigator?.let(BackCallbackState::detach)
-        // The window's observer now, and the one the listener was added to, if they differ.
-        val observers = listOfNotNull(frameObserver, window?.peekDecorView()?.viewTreeObserver).distinct()
-        observers.forEach { if (it.isAlive) it.removeOnPreDrawListener(backBeforeFrame) }
+        // The debug check's listener: from the window's observer now, and the one it was added to, if they differ.
+        if (backCheck != null) {
+            val observers = listOfNotNull(frameObserver, window?.peekDecorView()?.viewTreeObserver).distinct()
+            observers.forEach { if (it.isAlive) it.removeOnPreDrawListener(backCheckBeforeFrame) }
+        }
         frameObserver = null
         SlotHost.detach(this)
         navigator?.destroyWithActivity()
@@ -317,7 +362,9 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     /**
      * Back that JavaScript's listeners didn't take: the navigation does its step first — a stack's top leaves or holds,
      * a pane closes —; with nothing to do there, the activity's own back, as without the navigation. An app may
-     * override it (e.g. `moveTaskToBack(true)`).
+     * override it (e.g. `moveTaskToBack(true)`). The callback is off for that back only: the dispatcher's own back is
+     * the activity's, not [onBackPressed]; then it is computed again, and `hardwareBackButton.systemAnimation: false`
+     * turns it on again.
      */
     override fun invokeDefaultOnBackPressed() {
         val handled = navigator?.handleBack(CommandListenerAdapter()) == true

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

@@ -8,7 +8,7 @@ import com.facebook.react.bridge.ReadableMap
  */
 class AnimationsOptions {
     @JvmField var push = StackPushAnimationOptions()
-    @JvmField var pop = StackAnimationOptions()
+    @JvmField var pop = StackPopAnimationOptions()
     @JvmField var setStackRoot = SetStackRootAnimationOptions()
     @JvmField var setRoot = EnterExitAnimationOptions()
     @JvmField var showModal = ModalAnimationOptions()
@@ -43,7 +43,7 @@ class AnimationsOptions {
             val options = AnimationsOptions()
             if (map == null) return options
             options.push = map.group("push") { StackPushAnimationOptions.parse(it) }
-            options.pop = map.group("pop") { StackAnimationOptions.parse(it) }
+            options.pop = map.group("pop") { StackPopAnimationOptions.parse(it) }
             options.setStackRoot = map.group("setStackRoot") { SetStackRootAnimationOptions.parse(it) }
             options.setRoot = map.group("setRoot") { EnterExitAnimationOptions.parse(it) }
             options.showModal = map.group("showModal") { ModalAnimationOptions.parse(it) }

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

@@ -95,6 +95,7 @@ class BottomTabsAccessoryOptions {
 class BottomTabsOptions {
     @JvmField var visible: Bool = NullBool()
     @JvmField var animate: Bool = NullBool()
+    @JvmField var switchAnimation: Text = NullText()
     /** Selects a tab once; a whole number, truncated where it is read. */
     @JvmField var currentTabIndex: Fraction = NullFraction()
     /** Selects a tab once. */
@@ -124,18 +125,19 @@ class BottomTabsOptions {
     @JvmField var minimizeBehavior: Text = NullText()
     @JvmField var bottomAccessory = BottomTabsAccessoryOptions()
 
-    fun hasValue(): Boolean = visible.hasValue() || animate.hasValue() || currentTabIndex.hasValue() ||
-        currentTabId.hasValue() || testID.hasValue() || accessibilityLabel.hasValue() || moreTestID.hasValue() ||
-        drawBehind.hasValue() || backgroundColor.hasValue() || tabsAttachMode.hasValue() || barStyle.hasValue() ||
-        layoutStyle.hasValue() || cornerRadius.hasValue() || bottomMargin.hasValue() || translucent.hasValue() ||
-        hideShadow.hasValue() || titleDisplayMode.hasValue() || elevation.hasValue() || hideOnScroll.hasValue() ||
-        borderColor.hasValue() || borderWidth.hasValue() || shadow.hasValue() || customRow.hasValue() ||
-        sidebar.hasValue() || sidebarLayout.hasValue() || customizationId.hasValue() || minimizeBehavior.hasValue() ||
-        bottomAccessory.hasValue()
+    fun hasValue(): Boolean = visible.hasValue() || animate.hasValue() || switchAnimation.hasValue() ||
+        currentTabIndex.hasValue() || currentTabId.hasValue() || testID.hasValue() || accessibilityLabel.hasValue() ||
+        moreTestID.hasValue() || drawBehind.hasValue() || backgroundColor.hasValue() || tabsAttachMode.hasValue() ||
+        barStyle.hasValue() || layoutStyle.hasValue() || cornerRadius.hasValue() || bottomMargin.hasValue() ||
+        translucent.hasValue() || hideShadow.hasValue() || titleDisplayMode.hasValue() || elevation.hasValue() ||
+        hideOnScroll.hasValue() || borderColor.hasValue() || borderWidth.hasValue() || shadow.hasValue() ||
+        customRow.hasValue() || sidebar.hasValue() || sidebarLayout.hasValue() || customizationId.hasValue() ||
+        minimizeBehavior.hasValue() || bottomAccessory.hasValue()
 
     fun mergeWith(other: BottomTabsOptions) {
         if (other.visible.hasValue()) visible = other.visible
         if (other.animate.hasValue()) animate = other.animate
+        if (other.switchAnimation.hasValue()) switchAnimation = other.switchAnimation
         if (other.currentTabIndex.hasValue()) currentTabIndex = other.currentTabIndex
         if (other.currentTabId.hasValue()) currentTabId = other.currentTabId
         if (other.testID.hasValue()) testID = other.testID
@@ -167,6 +169,7 @@ class BottomTabsOptions {
     fun mergeWithDefault(defaults: BottomTabsOptions) {
         if (!visible.hasValue()) visible = defaults.visible
         if (!animate.hasValue()) animate = defaults.animate
+        if (!switchAnimation.hasValue()) switchAnimation = defaults.switchAnimation
         if (!currentTabIndex.hasValue()) currentTabIndex = defaults.currentTabIndex
         if (!currentTabId.hasValue()) currentTabId = defaults.currentTabId
         if (!testID.hasValue()) testID = defaults.testID
@@ -198,6 +201,7 @@ class BottomTabsOptions {
     fun copy() = BottomTabsOptions().also { it.mergeWith(this) }
 
     companion object {
+        private val SWITCH_ANIMATIONS = setOf("platform", "none")
         private val TABS_ATTACH_MODES = setOf("together", "afterInitialTab", "onSwitchToTab")
         private val BAR_STYLES = setOf("default", "black")
         private val LAYOUT_STYLES = setOf("stretch", "compact")
@@ -212,6 +216,7 @@ class BottomTabsOptions {
             if (map == null) return options
             options.visible = BoolParser.parse(map, "visible")
             options.animate = BoolParser.parse(map, "animate")
+            options.switchAnimation = TextParser.parse(map, "switchAnimation", SWITCH_ANIMATIONS)
             options.currentTabIndex = FractionParser.parse(map, "currentTabIndex")
             options.currentTabId = TextParser.parse(map, "currentTabId")
             options.testID = TextParser.parse(map, "testID")

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

@@ -15,20 +15,27 @@ class HardwareBackButtonOptions {
     @JvmField var popStackOnPress: Bool = NullBool()
     /** Internal. */
     @JvmField var dismissModalOnPress: Bool = NullBool()
+    /**
+     * `systemAnimation`: `false` keeps back in the app on the first screen too, so the system doesn't play its
+     * animation of going home; the press then does the activity's own back.
+     */
+    @JvmField var systemAnimation: Bool = NullBool()
 
     fun hasValue(): Boolean = bottomTabsOnPress.hasValue() || popStackOnPress.hasValue() ||
-        dismissModalOnPress.hasValue()
+        dismissModalOnPress.hasValue() || systemAnimation.hasValue()
 
     fun mergeWith(other: HardwareBackButtonOptions) {
         if (other.bottomTabsOnPress.hasValue()) bottomTabsOnPress = other.bottomTabsOnPress
         if (other.popStackOnPress.hasValue()) popStackOnPress = other.popStackOnPress
         if (other.dismissModalOnPress.hasValue()) dismissModalOnPress = other.dismissModalOnPress
+        if (other.systemAnimation.hasValue()) systemAnimation = other.systemAnimation
     }
 
     fun mergeWithDefault(defaults: HardwareBackButtonOptions) {
         if (!bottomTabsOnPress.hasValue()) bottomTabsOnPress = defaults.bottomTabsOnPress
         if (!popStackOnPress.hasValue()) popStackOnPress = defaults.popStackOnPress
         if (!dismissModalOnPress.hasValue()) dismissModalOnPress = defaults.dismissModalOnPress
+        if (!systemAnimation.hasValue()) systemAnimation = defaults.systemAnimation
     }
 
     fun copy() = HardwareBackButtonOptions().also { it.mergeWith(this) }
@@ -43,6 +50,7 @@ class HardwareBackButtonOptions {
             options.bottomTabsOnPress = TextParser.parse(map, "bottomTabsOnPress", BOTTOM_TABS_ON_PRESS)
             options.popStackOnPress = BoolParser.parse(map, "popStackOnPress")
             options.dismissModalOnPress = BoolParser.parse(map, "dismissModalOnPress")
+            options.systemAnimation = BoolParser.parse(map, "systemAnimation")
             return options
         }
     }

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

@@ -99,8 +99,8 @@ class BottomTabsEnterExitAnimationOptions {
 }
 
 /**
- * `StackAnimationOptions`: the animation of `pop`, and the base of `push` and `setStackRoot`; over the shared elements
- * and element transitions of [LayoutAnimation].
+ * `StackAnimationOptions`: the base of the animations of `push`, `pop` and `setStackRoot`; over the shared elements and
+ * element transitions of [LayoutAnimation].
  */
 open class StackAnimationOptions : LayoutAnimation() {
     @JvmField var enabled: Bool = NullBool()
@@ -188,6 +188,44 @@ class StackPushAnimationOptions : StackAnimationOptions() {
     }
 }
 
+/**
+ * `StackPopAnimationOptions`: the animation of `pop`, and `preview`: whether a back gesture over the stack previews the
+ * pop of its top (Android 14+); `false` pops it when the gesture is released, as on Android 13.
+ */
+class StackPopAnimationOptions : StackAnimationOptions() {
+    @JvmField var preview: Bool = NullBool()
+
+    override fun hasValue(): Boolean = super.hasValue() || preview.hasValue()
+
+    fun mergeWith(other: StackPopAnimationOptions) {
+        super.mergeWith(other)
+        if (other.preview.hasValue()) preview = other.preview
+    }
+
+    fun mergeWithDefault(defaults: StackPopAnimationOptions) {
+        super.mergeWithDefault(defaults)
+        if (!preview.hasValue()) preview = defaults.preview
+    }
+
+    override fun copy(): StackPopAnimationOptions = StackPopAnimationOptions().also { it.mergeWith(this) }
+
+    // Reads the fields of this class from [map], after those of its parent.
+    private fun readStackPopAnimationOptions(map: ReadableMap) {
+        readStackAnimationOptions(map)
+        preview = BoolParser.parse(map, "preview")
+    }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): StackPopAnimationOptions {
+            val options = StackPopAnimationOptions()
+            if (map == null) return options
+            options.readStackPopAnimationOptions(map)
+            return options
+        }
+    }
+}
+
 /** `SetStackRootAnimationOptions`: the animation of `setStackRoot`. */
 class SetStackRootAnimationOptions : StackAnimationOptions() {
     @JvmField var asPush: Bool = NullBool()