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

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [1.0.0-alpha.3](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.2...v1.0.0-alpha.3) (2026-10-22)
+
+
+### Features
+
+* **android:** system stack transitions, an opaque default screen background and predictive back ([#26](https://github.com/apexnative/navigation/issues/26)) ([9f28969](https://github.com/apexnative/navigation/commit/9f28969a30a8902c1512cd2a24c3ddf5439f4642))
+
+
+### Bug Fixes
+
+* **android:** center the back button and the bar buttons in the row ([#35](https://github.com/apexnative/navigation/issues/35)) ([c908971](https://github.com/apexnative/navigation/commit/c9089716ea4e3b3f4bcdc42b16e57134018d76c0))
+* **android:** fade through on a tab switch, a new tab's first frame in place ([#29](https://github.com/apexnative/navigation/issues/29)) ([60d69b6](https://github.com/apexnative/navigation/commit/60d69b618a97c8f7da974fbdf6f427461960d672))
+* **android:** let an overlay cover the status bar ([#27](https://github.com/apexnative/navigation/issues/27)) ([2632194](https://github.com/apexnative/navigation/commit/26321945cf0c457780b3eb7bba1f3d988dad4d96))
+* **android:** match each modal presentation style to its Android equivalent ([#31](https://github.com/apexnative/navigation/issues/31)) ([54ab265](https://github.com/apexnative/navigation/commit/54ab2651f3139e869a2d99a43465b33bfb171414))
+* **android:** move the top bar with its screen in transitions of their own ([#34](https://github.com/apexnative/navigation/issues/34)) ([4d12ee6](https://github.com/apexnative/navigation/commit/4d12ee6d6ec26a04e529bdef8b8111d20e5116aa))
+* close the side menu as a pick in it changes the center ([#28](https://github.com/apexnative/navigation/issues/28)) ([c4b3e81](https://github.com/apexnative/navigation/commit/c4b3e81ba44d2edb6d93d3ddc906eca165d46e29))
+
+
+### Performance Improvements
+
+* **android:** render the modals of a setRoot's layout together with its root ([#32](https://github.com/apexnative/navigation/issues/32)) ([cf3e1d9](https://github.com/apexnative/navigation/commit/cf3e1d98ff7c5d2a05aba6485203e6fe35a3423d))
+
+## [1.0.0-alpha.2](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.1...v1.0.0-alpha.2) (2026-10-22)
+
+
+### Bug Fixes
+
+* **android:** fractional option sizes, sheet stops, live side menu size and menu appear events ([#18](https://github.com/apexnative/navigation/issues/18)) ([3ed8913](https://github.com/apexnative/navigation/commit/3ed8913126d83f5d75a265d22e3f80e581d329b8))
+* **cli:** set up and make apps on React Native 0.88's template ([#23](https://github.com/apexnative/navigation/issues/23)) ([3c24f04](https://github.com/apexnative/navigation/commit/3c24f042f4d6a6a2660768a7443cc5eeba004235))
+* **ios:** hand sheet detents to UIKit sorted by height and without repeats ([#15](https://github.com/apexnative/navigation/issues/15)) ([d1c1004](https://github.com/apexnative/navigation/commit/d1c10043353f45b452e7200d2c179515b6989737))
+* **ios:** hide the dismissal of the old root's modals when a new root shows without animation ([#14](https://github.com/apexnative/navigation/issues/14)) ([b639232](https://github.com/apexnative/navigation/commit/b639232e8b73c38bf8599b7bac24ecc5c7104ca6))
+* **ios:** keep deep links working on React Native 0.88 in apps with a scene delegate ([#24](https://github.com/apexnative/navigation/issues/24)) ([7f690cd](https://github.com/apexnative/navigation/commit/7f690cdac41be774b55cf7186105faa605249bc2))
+* **ios:** keep the status bar blur in the status bar's frame as it changes ([#17](https://github.com/apexnative/navigation/issues/17)) ([d5051e9](https://github.com/apexnative/navigation/commit/d5051e9c30fc0040e726d12ef352da7cc43f2a8c))
+* **ios:** log instead of calling a command's nil promise block ([#22](https://github.com/apexnative/navigation/issues/22)) ([b2ed4ca](https://github.com/apexnative/navigation/commit/b2ed4ca2cb76207b24747e78bf702ef1ab02146b))
+* **ios:** reject a command whose answer goes away unanswered ([#12](https://github.com/apexnative/navigation/issues/12)) ([0914c03](https://github.com/apexnative/navigation/commit/0914c03ec465ae8273d736d1b12e5faef2ba4a52))
+* **ios:** show a partialCurl modal as coverVertical when it isn't full screen ([#16](https://github.com/apexnative/navigation/issues/16)) ([404b3be](https://github.com/apexnative/navigation/commit/404b3be98beac73069bfc16bb3903f583aa9b844))
+* keep a transition running when one element fails, and find its elements in one walk ([#21](https://github.com/apexnative/navigation/issues/21)) ([5dd1179](https://github.com/apexnative/navigation/commit/5dd1179834211abc985ffffbd2bd9622530be1dc))
+
 ## [1.0.0-alpha.1](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.0...v1.0.0-alpha.1) (2026-10-21)
 
 

package/README.md

@@ -1,34 +1,131 @@
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/navigation-banner-dark.png">
-  <img alt="@apexnative/navigation: native navigation for React Native on iOS, iPadOS and Android" src=".github/assets/navigation-banner-light.png">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/apexnative/navigation/main/.github/assets/navigation-banner-dark.png">
+  <img alt="@apexnative/navigation: native navigation for React Native on iOS, iPadOS and Android" src="https://raw.githubusercontent.com/apexnative/navigation/main/.github/assets/navigation-banner-light.png">
 </picture>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@apexnative/navigation"><img alt="npm version" src="https://img.shields.io/npm/v/@apexnative/navigation?label=npm&color=cb3837"></a>
+  <a href="https://www.npmjs.com/package/@apexnative/navigation"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@apexnative/navigation"></a>
+  <a href="https://github.com/apexnative/navigation/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/apexnative/navigation/ci.yml?branch=main&label=CI"></a>
+  <img alt="Platforms: iOS, iPadOS, Android" src="https://img.shields.io/badge/platforms-iOS%20%7C%20iPadOS%20%7C%20Android-informational">
+  <img alt="React Native 0.85 or newer, New Architecture" src="https://img.shields.io/badge/React%20Native-0.85%2B%20%C2%B7%20New%20Architecture-61dafb">
+  <img alt="TypeScript types included" src="https://img.shields.io/npm/types/@apexnative/navigation">
+  <a href="https://github.com/apexnative/navigation/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/npm/l/@apexnative/navigation"></a>
+</p>
+
+<p align="center">
+  <a href="https://navigation.apexnative.dev/docs/start/introduction"><b>Documentation</b></a> ·
+  <a href="https://navigation.apexnative.dev/docs/start/quick-start">Quick start</a> ·
+  <a href="https://navigation.apexnative.dev/api/starting-the-app/createNavigation">API reference</a> ·
+  <a href="https://github.com/apexnative/navigation/releases">Releases</a>
+</p>
+
 # @apexnative/navigation
 
-Native navigation for React Native on iOS, iPadOS and Android. Stacks, tabs, modals, side
-menus and overlays are real platform containers — `UINavigationController`,
-`UITabBarController`, Material components — owned by the native side and driven from JS.
+**The platform owns the navigation. React describes it.**
+
+`@apexnative/navigation` gives a React Native app the navigation of the platform itself. Stacks, tabs, modals, side
+menus, split views and overlays are the real containers of iOS and Android: `UINavigationController`,
+`UITabBarController`, sheets with detents, `UISplitViewController`, the Android back stack and the Material components.
+You describe the screens and how they are arranged in TypeScript; the native side shows them and reports back.
 
 > **Status:** a pre-release on npm; the API can still change before 1.0. The current version is on the
 > [releases page](https://github.com/apexnative/navigation/releases).
 
-## Principles
+## Why
+
+**The platform already knows how to navigate.** iOS and Android hold years of decisions about gestures,
+accessibility, every screen size, memory and multitasking. A router that keeps its own model of the navigation has to
+mirror all of that in JavaScript and catch up with every OS release. This library gives React the platform's own
+containers instead of replacing them, so a new tab bar or toolbar of the OS arrives with its beta, not a year later.
+
+**Native behavior, not only a native look.** The swipe back, the back button and dragging a sheet are the system's
+own, with the same transitions, accessibility and memory use as in an app written in Swift or Kotlin. Nothing is
+replayed into a copy of the state in React: JavaScript reads the state of the platform through events and hooks.
+
+**Describe, don't command.** Native navigation usually speaks in JSON layouts and string ids, so a wrong screen name
+or a missing prop shows up at run time. Here screens, props and roots are typed, and the same mistake is an error in
+the editor.
+
+|                        | A router in the React tree                    | Native navigation by commands | This library                                      |
+| ---------------------- | --------------------------------------------- | ----------------------------- | ------------------------------------------------- |
+| **Who owns the state** | an object in the React tree                   | the OS                        | the OS                                            |
+| **Gestures**           | native or drawn in JS, synced back into React | the system's own              | the system's own                                  |
+| **How you navigate**   | navigator components or files as URLs         | JSON layouts and screen ids   | `Stack`, `Tabs`, `SideMenu`; commands without ids |
+| **Types**              | typed route params                            | strings, props unchecked      | names, props and roots checked                    |
+
+## A quick look
+
+A screen is a component with its options:
+
+```tsx
+import { Text } from 'react-native';
+import { defineScreen } from '@apexnative/navigation';
+
+function Details({ title }: { title?: string }) {
+  return <Text>{title ?? 'Details'}</Text>;
+}
 
-- **The platform leads.** Native stacks, tabs, sheets and gestures rather than a web-style
-  router; a URL is one entry point among push notifications, widgets and shortcuts.
-- **Native is the source of truth.** Navigation state, screen lifecycle, safe areas, keyboard
-  and theme come from the OS.
-- **App lifecycle is first-class.** Cold start, splash, session restore, background and
-  process death are explicit steps.
-- **New OS features, fast.** Support for new iOS and Android releases lands with the betas.
-- **Customization without losing native behavior.** Options on system components first, your
-  own native components inside native containers next, custom JS UI only as a last resort.
-- **Performance is a requirement.** Transitions and gestures run natively; JS stays off the
-  critical path, and we measure it in CI.
+export const DetailsScreen = defineScreen({
+  component: Details,
+  options: (s, props) => s.title(props.title ?? 'Details'),
+});
+```
+
+The navigation names the screens and the root:
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
 
-## Platforms
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Details: DetailsScreen },
+  root: 'Home',
+});
+```
+
+Any screen opens another one with the platform's own transition:
 
-iOS, iPadOS and Android, on React Native 0.85 or newer with the New Architecture. The web is not a target.
+```ts
+const navigation = useNavigation();
+navigation.push('Details', { props: { title: 'Order 42' } });
+// navigation.push('Detail') or a prop Details doesn't take: a TypeScript error
+```
+
+## What's in it
+
+- **Containers:** native stacks, tabs, modals and sheets, side menus, split views on iPad, and overlays, nested in
+  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.
+- **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
+  share one tree.
+- **The app's lifecycle:** cold start, the splash screen, deep links, notifications and switching roots on sign-in
+  and sign-out.
+- **A CLI**, `apex-navigation`: sets up an app, checks it (`doctor`), adds screens, deep links, icons and the splash
+  screen, upgrades the navigation, migrates an app from another navigation library, and serves the commands and the
+  docs to AI coding agents (`mcp`).
+
+## When it fits
+
+- Apps that should look and behave like the platform, on iPhone, iPad and Android.
+- Apps with native screens, or a team that also writes Swift or Kotlin.
+- Apps where startup, transitions and memory matter.
+
+It doesn't fit an app that also ships to the web, or one that draws the same fully custom UI on every platform in
+JavaScript.
+
+## Requirements
+
+|                |                                                               |
+| -------------- | ------------------------------------------------------------- |
+| React Native   | 0.85 or newer, with the New Architecture (bridgeless, Fabric) |
+| iOS and iPadOS | 15.1 or newer                                                 |
+| Android        | 7.0 or newer (minSdk 24)                                      |
+| Expo           | not supported by `setup` yet                                  |
+| Web            | not a target                                                  |
 
 ## Installation
 
@@ -37,41 +134,40 @@ npm install @apexnative/navigation
 npx apex-navigation setup
 ```
 
-`setup` shows what it changes in the app and asks before writing, then installs the pods on a Mac:
-
-- `MainApplication.kt` extends `NavigationApplication`, which loads React Native itself.
-- `MainActivity.kt` extends `NavigationActivity`.
-- `AndroidManifest.xml`: `android:enableOnBackInvokedCallback="true"`, so on the first screen the system plays its
-  own back animation to the home screen (Android 16 turns it on for apps targeting SDK 36).
-- `AppDelegate.swift` extends `ANNAppDelegate`, which creates the window and starts React Native.
-- `Info.plist`: `UIViewControllerBasedStatusBarAppearance` is `true`, so each screen sets the status bar.
-- `index.js` starts the app through the navigation; a new `Navigation.ts` shows `App` as the first screen.
-- `navigation-env.d.ts` ties the commands to the screens of `Navigation.ts`, so names and props are checked.
-
-`--dry-run` shows the changes without writing them, `--yes` applies them without asking, `--skip-pods` leaves
-the pods for later. A file changed by hand stays as it is, and `setup` prints what to change in it. Expo apps
-aren't supported by `setup` yet. A new app starts with `npx @apexnative/navigation init MyApp`.
-
-`npx apex-navigation doctor` checks what the navigation needs in the app and on the machine: the files `setup`
-sets up, the typed commands, React Native loaded twice, the screens and links of the app, JDK 17, the Android
-SDK the app builds with, Xcode, CocoaPods, pods of an older navigation, a simulator and adb to run the app on,
-another navigation in the app. Each problem comes with its fix; `--fix` makes the ones the CLI has, for errors
-and warnings (`setup`, `links`, `icons`, `codegen`, `pod install`), asking before each, and `--json` prints the
-checks for CI and tools. It exits with 1 when it finds an error.
-
-The other commands: `screen` and `codegen` add screens, React or native; `links` declares deep links natively;
-`icons` and `splash` make the app icon and the splash screen; `upgrade` upgrades the navigation; `migrate` moves
-an app from another navigation library; `info` prints the versions for an issue; `mcp` serves
-the commands and the docs to AI coding agents.
-
-Edge-to-edge on Android follows the platform: always on Android 16+ for apps targeting SDK 36, and on
-Android 15 for apps targeting SDK 35. With `edgeToEdgeEnabled=true` in `android/gradle.properties` (the
-default of new React Native apps) it's on for every Android version.
+`setup` shows what it changes in the native files and in `index.js`, asks before writing, and installs the pods on a
+Mac. A new app starts with `npx @apexnative/navigation init MyApp`, and `npx apex-navigation doctor` checks an app
+and the machine and fixes what it can. The [installation guide](https://navigation.apexnative.dev/docs/start/installation)
+has the details, and the [quick start](https://navigation.apexnative.dev/docs/start/quick-start) builds a first app
+with two screens.
+
+Coming from another library: [React Navigation](https://navigation.apexnative.dev/docs/migration/from-react-navigation),
+[Expo Router](https://navigation.apexnative.dev/docs/migration/from-expo-router),
+[react-native-navigation](https://navigation.apexnative.dev/docs/migration/from-react-native-navigation).
+
+## Principles
+
+1. **The platform leads.** Native stacks, tabs, sheets and gestures, not a web-style router. A URL is one entry point
+   among push notifications, widgets and shortcuts.
+2. **Native is the source of truth.** Navigation state, screen lifecycle, safe areas, keyboard and theme come from the
+   OS.
+3. **App lifecycle is first-class.** Cold start, splash, session restore, background and process death are explicit
+   steps.
+4. **New OS features, fast.** Support for new iOS and Android releases lands with the betas.
+5. **Customization without losing native behavior.** Options of system components first, your own native components
+   inside native containers next, custom JS UI last.
+6. **Performance is a requirement.** Transitions and gestures run natively; JavaScript stays off the critical path.
+7. **Rendering and logic apart.** React renders screens. The logic of the app (a socket, a session, services) lives
+   outside the render tree: `navigation` works outside React, and `willMount` prepares the app before the first
+   screen.
+
+When two of them pull apart, the order decides.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md).
+The [Showcase app](https://github.com/apexnative/navigation/tree/main/example) runs every feature as a scenario.
+See [CONTRIBUTING.md](https://github.com/apexnative/navigation/blob/main/CONTRIBUTING.md) and the
+[code of conduct](https://github.com/apexnative/navigation/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/apexnative/navigation/blob/main/LICENSE)

package/android/CLAUDE.md

@@ -23,8 +23,8 @@ top-level folder. Main thread only, unless a line says otherwise.
 - `react/`: the way in and out: `NavigationTurboModule`, `CommandRunner`, `CommandAnswer`, `ErrorTexts`,
   `OptionsCommands`, `ReloadCoordinator`, `ReactGateway`, `ReactView` (a React root), the stores (`ScreenInsets`,
   `ScreenRegions`, `ArrangementStates`, `Hinge`, `StartInfo`), `LaunchLink`, `ScrollEvents`.
-- `react/events/`: `AppearanceDispatcher`, `ScreenAppearance`, `EventEmitter`, `NavigationStateReporter`,
-  `ComponentType`.
+- `react/events/`: `AppearanceDispatcher`, `ScreenAppearance`, `EventEmitter`, `EventContract` (made by
+  `scripts/contract.mjs`), `NavigationStateReporter`, `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),
@@ -73,8 +73,10 @@ top-level folder. Main thread only, unless a line says otherwise.
   `ScreenFrame.kt` (bars' room, window insets, keyboard), `ScreenSafeArea.kt`, `ComponentPresenter.kt` (background),
   `ScreenContentFactory.kt`, `ScreenFocus.kt`; `react/ReactView.kt`; `views/component/ComponentLayout.kt`.
 - Stack (queue, commands, back): `viewcontrollers/stack/StackQueue.kt`, `StackCommands.kt`, `StackController.kt`,
-  `StackViews.kt`, `StackTransitions.kt`, `PreparedPushes.kt`; `views/stack/StackLayout.kt`; back:
-  `NavigationActivity.kt`, `viewcontrollers/navigator/BackCallbackState.kt`.
+  `StackViews.kt`, `StackTransitions.kt`, `PreparedPushes.kt`; `views/stack/StackLayout.kt`, `ScreenEdge.kt` (the edge
+  a moving screen extends); back: `NavigationActivity.kt`, `viewcontrollers/navigator/BackCallbackState.kt`; the
+  preview of a pop during the back gesture (Android 14+): `StackController.BackGesture`, `BackPreview.kt`,
+  `stackPoppedByBack` of the layouts.
 - Stack FAB: `viewcontrollers/stack/fab/FabPresenter.kt`, `FabPlan.kt`, `FabPlacement.kt`; `views/stack/fab/`.
 - Top bar (title, buttons, menus, large title): `viewcontrollers/stack/topbar/TopBarPresenter.kt`, `TopBarRoom.kt`,
   `TopBarVisibility.kt`, `BarComponents.kt`, `ButtonPlaces.kt`, `LargeTitleCollapse.kt`, `BarRowTransition.kt`;
@@ -104,7 +106,7 @@ top-level folder. Main thread only, unless a line says otherwise.
   `NavigationStateReporter.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: `react/ErrorTexts.kt`.
+- Error texts: `react/ErrorTexts.kt`, made by `scripts/contract.mjs` from `src/interfaces/contract/errors.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`.
 - Native screens: `nativescreen/NativeScreenContext.kt`, `NativeScreenCalls.kt`, `NativeScreenCreator.kt`;
@@ -144,7 +146,11 @@ top-level folder. Main thread only, unless a line says otherwise.
 ## Pitfalls
 
 - Native code never touches React Native's views (their children, their layout): Fabric owns and recycles them. Move
-  content through `SlotContainers` and `SlotView`, and find views by `nativeID` only through React Native's own search.
+  content through `SlotContainers` and `SlotView`, and find views by `nativeID` only through React Native's own search
+  or its tag (`ReactR.id.view_tag_native_id`); a transition's elements in one walk per screen (`TransitionViews`).
+- Each step of a transition's element (its move into the layer, its animator, a flight's start and frames in
+  `MoveAnimator`) runs in `elementStep`: an exception skips that element only. A new step of an element goes there
+  too, or one bad element takes the whole transition down.
 - Every change of a stack's children goes through its `StackQueue`; a direct change of `shown` or of the container
   skips the table that decides interrupts and answers.
 - Every event of an appearance goes through `AppearanceDispatcher`. A container with its own loop of
@@ -163,14 +169,33 @@ top-level folder. Main thread only, unless a line says otherwise.
   `OverlayCoordinator.guarded`), which rejects the open answer and ends the record, or an exception ends the app and
   the command never answers.
 - A node makes its view in `createView`, never in its constructor.
+- Whether a node keeps the status bar's room (its margin, its background band) goes through
+  `StatusBarOptions.isHiddenOrDrawBehind(node.isInOverlay)`: an overlay covers the whole window, and a rule that reads
+  `drawBehind` alone puts a light band over an overlay's dimmed backdrop.
 - Only `SystemUiWindow` writes to the window. A presenter that changes a bar option calls `SystemUiOwner.invalidate`.
 - The core names a module container only in `LayoutFactory`; elsewhere use a capability or `visibleChildren()`.
 - A hidden stack keeps a `mergeOptions` per entry; applying it for the wrong entry paints the wrong screen's bar.
+- A `mergeOptions` moves or resizes only by what the merge names: the resolved options still hold the values of the
+  show, and acting on them undoes what the user did since (a dragged sheet snapped back to `selectedDetent`).
 - A sync getter reads a store, never a node; the store is written on main and cleared with its node.
 - A re-apply of the large title (a pop back, a light/dark switch, `mergeOptions`) collapses it to the list's last
   offset that `ScrollEventListener.lastOffset` keeps, never to 0, or it comes back expanded over a scrolled list.
 - A view's place in the window while a modal slides or a sheet is dragged comes from layout (`RestPlace`), never from
   `getLocationInWindow`, which counts the translations of the animation.
+- The bar measures to its children: a picture laid into it for a transition that is taller than the bar the incoming
+  screen gives holds the bar at that height to the end (the row's picture of a pop from a large title). What doesn't
+  stay in the bar rides with the leaving screen (`TopBarPresenter.pictureUnderRow`).
+- A `Toolbar` centers its navigation button and its menu in `min(minimumHeight, height)` (`buttonGravity` is top):
+  the row's toolbars take the row's height as their minimum (`TitleBar`); 0 pins the buttons to the row's top.
+- A screen's overlay is clipped to the screen, and a screen without a large title is laid out under the bar (its `top`
+  is the bar's height): a picture of the bar in its overlay doesn't show. The bar's picture in a transition of the
+  stack's own is drawn by the stack's view with the screen's transform (`StackLayout.barTravels`).
+- A React screen without `layout.backgroundColor` is opaque with the theme's `android:colorBackground`
+  (`ComponentPresenter`): a push keeps the covered screen under the new one until it ends, and a transparent screen
+  shows it. Only an explicit `'transparent'` / `null` (overlays, see-through modals) lets it through.
+- The back gesture's preview shows the screen under the top outside any operation of the queue: it may only reveal
+  it and put it back, and its release goes through `StackQueue.cut(gesture = true)`. A command that comes meanwhile
+  stops it through `StackDisplay.stop`, like any transition it takes over.
 - Without edge to edge the window resizes for the keyboard by the manifest's soft input mode, so
   `layout.adjustResize: false` goes through the system UI owner's keyboard group (`SystemUiWindow.setKeyboardCovers`),
   not through the screen's padding.

package/android/CORE.md

@@ -91,7 +91,9 @@ The events go from the main thread, synchronously, through `EventEmitter.current
   current root in the root layer, transparent (`RootLayerViews.place`), so its React roots start while the old root keeps
   the touches. It waits (`RenderWait`, by `animations.setRoot.enter.waitForRender`), then fades through or plays its own
   animation, the old root is destroyed with its `ComponentDidDisappear`, `NativeScreenReleased` and `SlotDestroyed`, and
-  the end steps and answer are the same. The layout's modals and overlays show after it, one by one, before the answer.
+  the end steps and answer are the same. The layout's modals and overlays show after it, one by one, before the answer;
+  its modals are made with the root and render unseen in the modals layer, held (`ModalCoordinator.hold`), so each
+  shows in its turn without a wait of its own.
   The last `setRoot` wins: an older one is rejected (`ErrorTexts.setRootReplaced`) or finished at once.
 - **`showModal`** (`Navigator.showModal`, `ModalCoordinator.show`). One `ModalRecord` per modal; it joins the modals
   layer unseen (`ModalViews`), waits with its own `RenderWait`, then slides in (or opens as a `ModalSheet`). It shows
@@ -165,7 +167,10 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
   `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.
-- **Error texts.** `ErrorTexts`: one function per text, the same words as iOS. JavaScript adds `[navigation] <command>:`.
+- **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
+  builders of payloads use it, never a string.
 - **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`)

package/android/RECIPES.md

@@ -29,11 +29,12 @@ The steps for adding an option and for adding a command to the Android core; rea
 3. The body goes to the owner of the area: `Navigator` (root, modals, overlays), `StackCommands` (stacks), a
    coordinator. A stack operation is a `StackQueue` operation.
 4. New layout fields are read and checked in `LayoutReader`; checks against what shows are in `LayoutChecks` or in the
-   command, before any node is made. Every rejection text is a function in `ErrorTexts` (same words as iOS).
+   command, before any node is made. Every rejection text is a function in `ErrorTexts` (same words as iOS),
+   made by `node scripts/contract.mjs` from `src/interfaces/contract/errors.json`: a new text goes there.
 5. The answer goes through `CommandAnswer`: add the name to `COMPLETED_COMMANDS` when the command changes what shows
    (then the state, the promise and `CommandCompleted` follow in that order). A transition ends through
    `AppearanceDispatcher.endTransition`.
 6. Tests: `CommandRunnerTest`, `CommandAnswerTest`, `ErrorTextsTest`, `LayoutReaderTest`; a stack operation also needs a
    case in the queue tests (`StackQueueHarness`).
-7. A new event: `EventEmitter` (`emit…`), the payload type in `src/interfaces`, and for an appearance event the
-   `AppearanceDispatcher.Sender`.
+7. A new event: the payload type in `src/interfaces`, then `node scripts/contract.mjs` for its name and keys in
+   `EventContract`; `EventEmitter` (`emit…`) with those, and for an appearance event the `AppearanceDispatcher.Sender`.

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

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

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

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

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

@@ -4,6 +4,7 @@ import android.content.Context
 import com.facebook.react.ReactApplication
 import com.facebook.react.bridge.Arguments
 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
 
@@ -33,9 +34,9 @@ internal object ArrangementStates {
     }
 
     private fun toMap(state: State): WritableMap = Arguments.createMap().apply {
-        putString("placement", state.placement)
-        putString("layout", state.layout)
-        putBoolean("front", state.front)
-        putBoolean("hidden", state.hidden)
+        putString(EventContract.ArrangementChanged.PLACEMENT, state.placement)
+        putString(EventContract.ArrangementChanged.LAYOUT, state.layout)
+        putBoolean(EventContract.ArrangementChanged.FRONT, state.front)
+        putBoolean(EventContract.ArrangementChanged.HIDDEN, state.hidden)
     }
 }