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

package/ApexNavigation.podspec

@@ -2,7 +2,8 @@
 # ApexNavigation): the Objective-C++ core and modules under ios/, with the public headers of ios/Public/ApexNavigation
 # (<ApexNavigation/ApexNavigation.h>, <ApexNavigation/ANNAppDelegate.h>, <ApexNavigation/ANNSceneDelegate.h>). Other
 # headers stay private to the pod and are imported by bare name. The C++ of the Fabric components ANNSlot and
-# ANNSafeAreaView is header-only, under ios/cpp, next to the code React Native's codegen makes from src/.
+# ANNSafeAreaView is under ios/cpp, next to the code React Native's codegen makes from src/: headers, and one source
+# file with the store of the slots' measured heights.
 require "json"
 
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # Changelog
 
+## [1.0.0-alpha.11](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.10...v1.0.0-alpha.11) (2026-10-31)
+
+
+### Features
+
+* a pair's primary can take the trailing side or the bottom of a split ([#73](https://github.com/apexnative/navigation/issues/73)) ([90ddcd3](https://github.com/apexnative/navigation/commit/90ddcd3c62fa5878cc98651ca7a2cfcdf4645197))
+
+
+### Bug Fixes
+
+* **ios:** a pair and its insets settle at once when iPhone Duo folds or unfolds ([#71](https://github.com/apexnative/navigation/issues/71)) ([ad87ce1](https://github.com/apexnative/navigation/commit/ad87ce1669b55dfb6ad65bedfb8e119f08abb04e))
+
+## [1.0.0-alpha.10](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.9...v1.0.0-alpha.10) (2026-10-30)
+
+
+### Bug Fixes
+
+* **ios:** insets reach JavaScript once a fold of iPhone Duo settles ([#69](https://github.com/apexnative/navigation/issues/69)) ([7831546](https://github.com/apexnative/navigation/commit/78315463a69af5c683cfaffc7d4fd56fd20f3096))
+
+## [1.0.0-alpha.9](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.8...v1.0.0-alpha.9) (2026-10-30)
+
+
+### Features
+
+* side menus can be created after the center or at their first open ([#67](https://github.com/apexnative/navigation/issues/67)) ([a4a0ecf](https://github.com/apexnative/navigation/commit/a4a0ecfdc04ccd13d2c96b5799b45e510113a7e8))
+
+
+### Bug Fixes
+
+* **android:** the room beside a moving screen goes on with what its edge shows ([#64](https://github.com/apexnative/navigation/issues/64)) ([eb0936f](https://github.com/apexnative/navigation/commit/eb0936f15d8d157d31621917920814df2c725ff1))
+* **ios:** tabs not shown yet render their screens before they show ([#68](https://github.com/apexnative/navigation/issues/68)) ([cf34a09](https://github.com/apexnative/navigation/commit/cf34a09a772865a8e3ff377b053c968e306f4972))
+
+## [1.0.0-alpha.8](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.7...v1.0.0-alpha.8) (2026-10-29)
+
+
+### Bug Fixes
+
+* group options reach the screens that show, and the android bar hides as it shows ([#63](https://github.com/apexnative/navigation/issues/63)) ([474ca8a](https://github.com/apexnative/navigation/commit/474ca8aae53e5284d64a5d90dd852fdbdcbabcac))
+* **ios:** overlays and preloaded tabs take the scheme the app set with Appearance.setColorScheme ([#61](https://github.com/apexnative/navigation/issues/61)) ([232d7e0](https://github.com/apexnative/navigation/commit/232d7e038b53cd9656e59c7cfa5cbf0f52f9b587))
+
+## [1.0.0-alpha.7](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.6...v1.0.0-alpha.7) (2026-10-29)
+
+
+### Features
+
+* own android sheet and bar row, ios transitions in core animation, fast refresh of screens ([#56](https://github.com/apexnative/navigation/issues/56)) ([3113b42](https://github.com/apexnative/navigation/commit/3113b42a466f59490faaca181178a7840dab2826))
+
+## [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)
+
+
+### Bug Fixes
+
+* **ci:** keep a closed React Native issue instead of opening a second one ([#37](https://github.com/apexnative/navigation/issues/37)) ([242030c](https://github.com/apexnative/navigation/commit/242030c8559a6fe186f44781ada85d09970c8318))
+* **ios:** lay a waiting screen out in its place, so the large title comes in with it ([#41](https://github.com/apexnative/navigation/issues/41)) ([85bfaa8](https://github.com/apexnative/navigation/commit/85bfaa877d3775264c1ba1114942cf875f890f29))
+* one native contract, options as layers and pushes that wait for the first render ([#39](https://github.com/apexnative/navigation/issues/39)) ([888f21e](https://github.com/apexnative/navigation/commit/888f21eb2b3e1aec413413bbdab9546a7a8f5a6b))
+
+## [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 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
+  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

@@ -21,10 +21,12 @@ top-level folder. Main thread only, unless a line says otherwise.
   `OptionsReader`, `OptionsCache`, `DefaultOptions`. `params/` has the value types (`Bool`, `Text`, `Fraction`,
   `Variant`, `ThemeColour`); `parsers/` reads them tolerantly from React Native data.
 - `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`.
+  `OptionsCommands`, `PendingCalls` (a task behind the calls JavaScript made), `ReloadCoordinator`, `ReactGateway`,
+  `ReactView` (a React root), `ContentHeights` (content measured without a height limit, through JNI), 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`), `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),
@@ -43,7 +45,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/`
@@ -53,10 +55,12 @@ top-level folder. Main thread only, unless a line says otherwise.
 - `slots/`, `safearea/`, `nativescreen/`: the views of `ANNSlot` and `ANNSafeAreaView`, the slot screen, the
   native-screen context and calls.
 - `splash/`, `customrow/`, `utils/`: the splash hold, theme and copy; the tabs' custom row options; helpers
-  (`UiThread`, `ImageLoader`, `MaterialTheme`, `TestIds`, `WindowFolds`, `DevelopmentLog`).
+  (`UiThread`, `ImageLoader` with `OptionImages`, `ImageKey`, `ImageRequests`, `MaterialTheme`, `TestIds`, `WindowFolds`,
+  `DevelopmentLog`).
 - `android/src/main/jni/`: `CMakeLists.txt` builds the codegen target with the C++ of `ios/cpp` (the slot's and the
   safe area view's shadow nodes); `ApexNavigationSpec.h` replaces the generated header so autolinking sees their
-  descriptors.
+  descriptors; `ANNContentHeights.cpp` measures React content without a height limit for `react/ContentHeights.kt`
+  (a sheet's `'content'` detent).
 - `android/src/main/res/`: theme `Theme.ApexNavigation` (and `values-night`), `attrs.xml` (splash attributes),
   `ids.xml`, `dimens*.xml`, text colors, icons.
 - `android/src/test/java/…`: unit tests, one package per main package; fakes beside them (`Fakes.kt`,
@@ -73,17 +77,24 @@ 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`.
-- Stack FAB: `viewcontrollers/stack/fab/FabPresenter.kt`, `FabPlan.kt`, `FabPlacement.kt`; `views/stack/fab/`.
+  `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; of a sheet's dismissal: `viewcontrollers/modal/SheetBack.kt`,
+  `ModalCoordinator.backTargetSheet`, `ModalSheet.BackPreview`.
+- Stack FAB: `viewcontrollers/stack/fab/FabPresenter.kt`, `FabPlan.kt`, `FabPlacement.kt`, `FabMotion.kt` (how it goes
+  with a transition); `views/stack/fab/` (`FabCopy`: the picture of a FAB that leaves).
 - Top bar (title, buttons, menus, large title): `viewcontrollers/stack/topbar/TopBarPresenter.kt`, `TopBarRoom.kt`,
   `TopBarVisibility.kt`, `BarComponents.kt`, `ButtonPlaces.kt`, `LargeTitleCollapse.kt`, `BarRowTransition.kt`;
-  `views/stack/topbar/TopBar.kt`, `TitleBar.kt`, `titlebar/ButtonBar.kt`, `titlebar/ButtonMenus.kt`.
+  `views/stack/topbar/TopBar.kt`, `TitleBar.kt`, `titlebar/ButtonRow.kt` (the views of a side: back, buttons,
+  magnifier, "⋮"), `titlebar/ButtonBar.kt` (the buttons from the options, "⋮"'s popup), `titlebar/BarButtonView.kt`,
+  `titlebar/BarMenu.kt` (the bar's menus: a `ListPopupWindow` with the theme's popup style and the options' colors),
+  `titlebar/ButtonMenus.kt` (menu options to its items).
 - Search: `viewcontrollers/stack/search/StackSearchPresenter.kt`, `ScreenSearch.kt`, `SearchPanel.kt`;
   `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`.
@@ -92,38 +103,45 @@ 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: `react/ErrorTexts.kt`.
+- 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`, `SlotViewManager.kt`.
+- 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
-  here; `ImageLoader` loads them when the options apply, on main.
+  here; they load when the options apply, through the one cache of `utils/OptionImages` (by `ImageKey`): at once on
+  main where the first frame needs them (`ImageLoader`: the top bar's buttons, menus, back button and search
+  suggestions; a tab's first icon; a new FAB), on its background thread for a file or a drawable of the app where the
+  view takes them when ready (`ImageRequests`: a changed tab icon or one that didn't load, a FAB's changed icon, the
+  icon of a FAB hidden with `visible: false`, the FAB menu's actions).
 - **Main thread.** Everything else: the command body, nodes, views, events, the stores' writes. Any thread may read
   `ReloadCoordinator.generation`.
 
@@ -144,18 +162,27 @@ 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 start, its animator, a flight's start and frames in `MoveAnimator`) runs
+  in `elementStep`, and the layer draws each copy on its own: 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
   `onViewWillAppear` / `onViewDidAppear` / `onViewDisappear` sends the events in the wrong order.
-- Never change a resolved options object: it is cached and shared. Copy it, or write through `changeOptions`.
+- Never change a resolved options object: it is cached and shared. Copy it, or write through `changeOptions`; a
+  user's choice goes through `changeChoices` (the user layer), never into own options, or the next `mergeOptions`
+  wipes it.
 - A new option field that is not in `mergeWith`, `mergeWithDefault`, `copy` or the fixture is dropped silently somewhere
   in the chain; `WholeTreeTest` exists to catch it.
 - A new wait is a new `RenderWait` value, not a new timer. A wait that survives a destroy or a supersede hangs a promise;
   `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
@@ -163,14 +190,40 @@ 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`).
+- The bar's buttons are plain views of the row (`ButtonRow`), not a toolbar's menu: a button keeps its view while its id
+  stays, and its `testID` is set when it is bound. They copy a Material 3 toolbar's look through the theme's
+  attributes (`actionButtonStyle`, `actionMenuTextAppearance`, `actionOverflowButtonStyle`,
+  `toolbarNavigationButtonStyle`) and its `maxButtonHeight` of 56 dp; the count of places is AppCompat's
+  (`ButtonPlaces.maxActionButtons`).
+- 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.
+- 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.