@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.1

package/ApexNavigation.podspec

@@ -0,0 +1,42 @@
+# The CocoaPods spec of @apexnative/navigation. It builds the same sources as ios/Package.swift (the SwiftPM target
+# 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/.
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ApexNavigation"
+  s.module_name  = "ApexNavigation"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/apexnative/navigation.git", :tag => "v#{s.version}" }
+
+  s.source_files         = "ios/**/*.{h,m,mm,cpp}"
+  s.public_header_files  = "ios/Public/ApexNavigation/*.h"
+  # The prefix header is SwiftPM's; CocoaPods makes its own with Foundation and UIKit.
+  s.exclude_files        = ["ios/build/**/*", "ios/ApexNavigation-prefix.h"]
+  s.frameworks           = "UIKit", "Foundation", "CoreGraphics"
+  s.requires_arc         = true
+  # Kept by install_modules_dependencies, which adds the folly flags after it.
+  s.compiler_flags       = "-DUSE_HERMES=1"
+
+  # A module map for the pod, so Swift apps `import ApexNavigation` (the Showcase's AppDelegate does).
+  s.pod_target_xcconfig = {
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+    "DEFINES_MODULE" => "YES",
+  }
+
+  # React Native's dependencies of a New Architecture library: React-Core, the codegen of src/ (ApexNavigationSpec),
+  # Fabric, the TurboModule headers and the header search paths they need.
+  install_modules_dependencies(s)
+  # The app's generated provider of modules and components, which ANNAppDelegate hands to React Native's factory.
+  s.dependency "ReactAppDependencyProvider"
+end

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [1.0.0-alpha.1](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.0...v1.0.0-alpha.1) (2026-10-21)
+
+
+### Features
+
+* native navigation for React Native on iOS, iPadOS and Android ([ede23be](https://github.com/apexnative/navigation/commit/ede23beebc4a09eb20cf774a90a1bca99f07923e))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artashes Bayazetyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+<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">
+</picture>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @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.
+
+> **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
+
+- **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.
+
+## Platforms
+
+iOS, iPadOS and Android, on React Native 0.85 or newer with the New Architecture. The web is not a target.
+
+## Installation
+
+```sh
+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.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE)

package/android/CLAUDE.md

@@ -0,0 +1,183 @@
+# Android core — map
+
+The Android side of `@apexnative/navigation`: the native core that owns the navigation state of an app — stacks, tabs,
+modals, overlays, side menus, split views and pairs — and is driven from JavaScript. Kotlin, package
+`dev.apexnative.navigation`, views only (no Fragments), Material 3, log tag `ApexNavigation`. React Native 0.85+ with
+the New Architecture only, minSdk 24, compileSdk 36, JDK 17. The options, the layout JSON, the commands and the events
+are the contract of `src/interfaces/`; this folder implements it and does not change it. The JavaScript end is in
+`src/ARCHITECTURE.md`.
+
+Paths below are under `android/src/main/java/dev/apexnative/navigation/` unless they start with `android/` or another
+top-level folder. Main thread only, unless a line says otherwise.
+
+## Folders
+
+- `NavigationApplication.kt`, `NavigationActivity.kt`, `NavigationPackage.kt`, `EdgeToEdgeDecision.kt`: the app-facing
+  classes: the application (React host through `ReactGateway`, native screens by name), the activity (layers, splash
+  hold, back, developer reload), the React package (`ANNTurboModule`, `ANNSlot`, `ANNSafeAreaView`), the edge-to-edge
+  rule.
+- `layout/`: `LayoutNode`, `LayoutType`, `LayoutReader` (module thread), `LayoutChecks`, `LayoutException`.
+- `options/`: one class per option group (`TopBarOptions`, `StatusBarOptions`, …), `Options` (the root),
+  `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`.
+- `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),
+  `Capabilities.kt`, `ShownChildren`, `ContainerBackground`.
+- `viewcontrollers/navigator/`: `Navigator`, `Navigators`, `LayoutFactory`, `RootCoordinator`, `WaitingLayer`,
+  `FirstRootDraw`, `BackCallbackState`.
+- `viewcontrollers/component/`: the React screen: `ComponentViewController`, `ComponentPresenter`, `ScreenFrame`,
+  `ScreenSafeArea`, `RestPlace`, `ScreenReadiness`, `ContentReadiness`, `RenderWait`, `ScreenContentFactory`,
+  `ScreenFocus`.
+- `viewcontrollers/externalcomponent/`: the native screen node (`ExternalComponentViewController`) and
+  `NativeScreens`.
+- `viewcontrollers/stack/`: `StackController`, `StackQueue`, `StackCommands`, `StackViews`, `StackDisplay`,
+  `StackTransitions`, `PreparedPushes`. `fab/`, `search/`, `topbar/` hold the bar, the FAB and the search presenters.
+- `viewcontrollers/bottomtabs/`: `BottomTabsController`, `BottomTabsPresenter` and the pure rules (`TabSelection`,
+  `TabsAttach`, `TabsRoom`, `TabBarLook`, `TabBarMotion`, `TabItems`).
+- `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`;
+  `OverlayCoordinator`, `OverlayRecord`, `OverlayViews`, `OverlayTouches`.
+- `views/`: Android views and animators, no rules: `component/`, `externalcomponent/`, `stack/` (`StackLayout`,
+  `topbar/`, `fab/`), `bottomtabs/`, `sidemenu/`, `animations/` (curves, `SideAnimator`, `AnimationRules`), `element/`
+  (element and shared-element transitions).
+- `system/`: the system UI: `SystemUiOwner`, `SystemUiLayers`, `SystemUiRules`, `SystemUiState`, `SystemUiWindow`,
+  `AppDirection`.
+- `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`).
+- `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.
+- `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`,
+  `StackFakes.kt`, …).
+
+## Where to look
+
+- Launch and the app-facing API: `NavigationApplication.kt`, `NavigationActivity.kt`, `react/ReactGateway.kt`,
+  `NavigationPackage.kt`, `EdgeToEdgeDecision.kt`, `react/ReloadCoordinator.kt` (`AppLaunched`),
+  `react/DeveloperReload.kt`.
+- Root (`setRoot`, splash, reload): `viewcontrollers/navigator/RootCoordinator.kt`, `FirstRootDraw.kt`, `Navigator.kt`;
+  `splash/SplashHold.kt`, `SplashTheme.kt`, `SplashView.kt`; `react/ReloadCoordinator.kt`.
+- Screen (React root, slot, native, insets, background, keyboard): `viewcontrollers/component/ComponentViewController.kt`,
+  `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/`.
+- 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`.
+- 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`.
+- 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`.
+- Side menu: `viewcontrollers/sidemenu/SideMenuController.kt`, `SideMenuMotion.kt`, `SideMenuRules.kt`,
+  `SideMenuPresenter.kt`; `views/sidemenu/SideMenuView.kt`.
+- 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`.
+- 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`.
+- 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`.
+- Options (parsing, merging): `options/Options.kt`, `OptionsReader.kt`, `OptionsCache.kt`, `DefaultOptions.kt`,
+  `params/`, `parsers/`; `viewcontrollers/viewcontroller/ViewController.kt` (resolution).
+- Error texts: `react/ErrorTexts.kt`.
+- 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`;
+  `viewcontrollers/externalcomponent/`.
+- Slots: `slots/SlotHost.kt`, `SlotView.kt`, `SlotScreenView.kt`, `SlotContainers.kt`, `SlotViewManager.kt`.
+- Safe area: `safearea/SafeAreaView.kt`, `SafeAreaViewManager.kt`; `viewcontrollers/component/ScreenReadiness.kt`;
+  `react/ScreenInsets.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.
+- **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.
+- **Main thread.** Everything else: the command body, nodes, views, events, the stores' writes. Any thread may read
+  `ReloadCoordinator.generation`.
+
+## Checks
+
+- `scripts/build-android.sh --lib` builds the library alone; `scripts/build-android.sh` builds the Showcase (arm64);
+  with a device serial it installs and starts it. Kotlin and Java warnings are errors
+  (`-PapexNavigationWarningsAsErrors`).
+- `scripts/test-android.sh [--tests '*SomeTest']` runs `:apexnative_navigation:testDebugUnitTest` from `example/android`.
+  The tests are plain JUnit 4 on the JVM (`unitTests.returnDefaultValues`, no Robolectric), in
+  `android/src/test/java/dev/apexnative/navigation/`, one package per main package. Coordinators and rules are written
+  to run with fakes (`StackFakes.kt`, `ModalFakes.kt`, `AppearanceFakes.kt`, `Nodes.kt`); a node that touches views in
+  its constructor can't be tested this way.
+- Gradle runs only through `scripts/android-env.sh` (JDK 17); the scripts do it.
+- A change in `ios/cpp/` is built on both platforms.
+- `scripts/check.sh` covers the TypeScript side only.
+
+## 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.
+- 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`.
+- 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.
+- 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
+  goes through its owner's guard (`StackQueue.step`, `RootCoordinator.step`, `ModalCoordinator.guarded`,
+  `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.
+- 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 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.
+- 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.
+
+## Read when needed
+
+- `android/CORE.md`: the layers, how a command flows (`push`, `setRoot`, `showModal`, `mergeOptions`), the single
+  places (which class owns which rule) and the modules. Read it when changing the core's structure, adding a module or
+  tracing a flow.
+- `android/RECIPES.md`: the steps for adding an option and for adding a command. Read it when doing exactly that.

package/android/CORE.md

@@ -0,0 +1,219 @@
+# Android core: structure
+
+The layers of the Android core, how a command flows through them, the classes that own each rule and how modules plug
+in; read it when changing the core's structure, adding a module or tracing a flow. Paths are under
+`android/src/main/java/dev/apexnative/navigation/`, as in `android/CLAUDE.md`; main thread only, unless a line says
+otherwise.
+
+## Layers
+
+```
+JS ─ ANNTurboModule (codegen NativeANNTurboModuleSpec)
+ │      sync getters answer on the JS thread from stores the main thread fills
+ │      (ScreenInsets, ScreenRegions, ArrangementStates, Hinge, StartInfo)
+ ▼ module thread
+react/NavigationTurboModule      one override per method
+ │  layout/LayoutReader ► options/OptionsReader     the whole layout read and checked, its options read
+ ▼ main thread, one task per command, in call order
+react/CommandRunner ── react/CommandAnswer ── react/ErrorTexts
+ ▼
+viewcontrollers/navigator/Navigator       one per activity: layers, registry, commands of the root,
+ │                                        modals, overlays; stackCommands for the stacks
+ ├ child/ChildControllersRegistry         id → node
+ └ navigator/LayoutFactory                LayoutNode → node (the only code that names module containers)
+ ▼
+nodes: ViewController → ChildController (screens) / ParentController (stack, tabs, side menu, split view, pair)
+ │ options: options/Options (typed tree) + OptionsCache + DefaultOptions, resolved and cached per node
+ ▼
+coordinators: RootCoordinator · StackQueue (one per stack) · ModalCoordinator · OverlayCoordinator ·
+              RenderWait + ScreenReadiness (waits for screens to render) · WaitingLayer
+ ▼
+presenters: ComponentPresenter · StackPresenter + TopBarPresenter · BottomTabsPresenter · SideMenuPresenter ·
+            SplitViewPresenter · system/SystemUiOwner (status bar, navigation bar, orientation, keyboard)
+ ▼
+react/events/AppearanceDispatcher ─► NavigationStateReporter ─► EventEmitter ─► ANN.* events ─► JS
+```
+
+- **Way in.** `NavigationTurboModule` only turns a method into a `CommandRunner` call; it holds no navigation logic. It
+  may call the runner, the readers, `Navigator`, `StackCommands` and the stores.
+- **Layout check.** `LayoutReader` reads React Native's data straight into immutable `LayoutNode`s and checks the whole
+  tree (types, ids, names, nesting, native-screen registration) before anything is queued. It calls `OptionsReader`.
+  `LayoutChecks` is its main-thread half: ids that already show.
+- **Command runner.** `CommandRunner` takes the number of the JavaScript (`ReloadCoordinator.generation`), runs the
+  check, posts one main-thread task and makes the `CommandAnswer`. It rejects, never crashes. It calls `Navigator` and
+  what the module method hands it.
+- **Registry and factory.** `ChildControllersRegistry` and `LayoutFactory` make and find nodes. The factory calls the
+  node constructors and nothing else.
+- **Nodes.** A node owns its view (made in `createView`, not in the constructor), its own options and its place in the
+  tree. It calls its parent through `ParentController` hooks and its presenter.
+- **Options.** The typed tree is immutable by convention: a resolved result is cached and read-only; code that changes
+  options copies them first.
+- **Coordinators.** Own the rules that span nodes: the order of a stack's operations, a modal's states, a root's
+  `setRoot`, the waits. They talk to views through small interfaces (`StackDisplay`, `ModalCoordinator.Views`,
+  `RootCoordinator.Layer`) and to the clock through `AppearanceDispatcher.Scheduler`, so unit tests run them with
+  fakes.
+- **Presenters.** Apply resolved options to views and to the system UI. They call views and the system UI owner, never
+  a coordinator.
+- **Dispatcher, state, emitter.** Everything JavaScript hears leaves here. Layers above call `AppearanceDispatcher`;
+  only it calls `EventEmitter` for appearance events.
+
+## How a command flows: `push` of Profile onto Home's stack
+
+1. **JS thread.** `NavigationTurboModule.push` calls `CommandRunner.run` with the command's name, its id (`push13`), a
+   `what` text for failures, the promise and a `check`.
+2. **Module thread.** `check` runs `LayoutReader.node`: the layout and the options of every node are read and checked.
+   A `LayoutException` rejects the promise with its text; nothing is queued.
+3. **Main thread.** `run` posts one task (`UiThread.post`), in call order. It drops the command if its JavaScript went
+   (`ReloadCoordinator.isCurrent`), makes the `CommandAnswer`, rejects with `ErrorTexts.nowhereToShow` without an
+   activity, else runs the body inside `CommandScope`. An exception rejects with `ErrorTexts.couldNot`.
+4. **`Navigator.stackCommands.push`** (`StackCommands`). The checks come before any node: the screen is shown, it is in
+   a stack (`ErrorTexts.notInStack`), the new id doesn't show already (`LayoutChecks.firstShownId`), `LayoutFactory`
+   can make the tree. A key of an entry goes back to it (`backToKey`).
+5. **Make and join.** `LayoutFactory.create` makes Profile (a `ComponentViewController`, registered in the
+   `ChildControllersRegistry`); `StackController.join` adds it; `StackQueue.push` accepts it as an entry.
+6. **`StackQueue`** is the only way to change a stack's children. `drain` starts the operation when nothing blocks it.
+   `startPush` decides the wait: none, `waitForRender`, or a prepared push. A wait is a `RenderWait` on Profile, and the
+   queue's `deliver` posts readiness signals to the next turn of the loop.
+7. **Begin.** `beginPush` raises Profile's view (`StackViews`), moves the bar and the tab bar
+   (`StackQueue.Host.barTransition`, `tabBarTransition`), calls `StackController` through `currentChildChanged`, then
+   `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`** (`COMPLETED_COMMANDS`). 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.
+
+- **`setRoot`** (`Navigator.setRoot`, `RootCoordinator`). Not a stack operation. The new root's view goes under the
+  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 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
+  once every older waiting modal showed or went. Dismissing sends `ModalDismissed`; a layer a full-screen modal covers
+  leaves the window.
+- **`mergeOptions`** (`OptionsCommands`, no promise). Options are read on the module thread (`runVoid` with `prepare`).
+  On main: `Navigator.findNode`, `ViewController.mergeOptions` (the own-options setter invalidates the cache; a shown
+  node's presenter applies the merge; parents run `mergeChildOptions`, a hidden stack keeps the merge per entry), then
+  `Navigator.optionsMerged` (modals, overlays, the system UI). No events, no state, no `CommandCompleted`.
+
+## The single places
+
+Each rule has one owner. Change the owner, not a caller; if a new feature needs the rule, call the owner.
+
+- **Registry.** `ChildControllersRegistry`, one per `Navigator` (one per activity). Filled by `ChildController` when a
+  node is made, emptied on destroy and by `Navigator.destroy`. `Navigator.findNode` hides nodes that go with an old
+  root. `Navigators` holds the activities weakly; `Navigators.current()` is the one commands run in.
+- **Factory.** `LayoutFactory`: one maker per `LayoutType`, `canMake` before a command makes anything. The only core
+  code that names `SplitViewController` and `ArrangementController`.
+- **Options cache.** `ViewController.resolveCurrentOptions(defaultOptions)` keeps its result while the generation of
+  `OptionsCache` and the nodes it was built along stay. `OptionsCache.optionsChanged` is called from two places only:
+  the `ViewController.options` setter and `DefaultOptions.set`. `resolveShownOptions` is what a layout shows with (the
+  options of the end of its current-child chain; a pair answers with its `OptionsScreen`).
+- **Appearance dispatcher.** `AppearanceDispatcher` is the only sender of `ComponentWillAppear`, `ComponentDidAppear`,
+  `ComponentDidDisappear`, `ScreenPopped`, `ModalDismissed`, `NativeScreenReleased` and `SlotDestroyed`. Order:
+  `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
+  `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.** `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
+  pair's primary).
+- **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`).
+- **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.
+- **Waiting place.** A root that waits lies under the current root (`RootLayerViews.place`); a pushed screen that waits
+  lies under the stack's top (`StackViews.placeWaiting`); a modal's and an overlay's container is transparent and
+  gives its touches away while it waits (`ModalContainer.isWaiting`, `OverlayContainer.isWaiting`).
+- **Waits to show.** `WaitingLayer`, kept by `Navigator` (`addWaitingLayer`, `removeWaitingLayer`, `isInWaitingLayer`).
+  The root, a waiting modal and a waiting overlay register and leave on every exit. A stack inside a waiting layer runs
+  its commands at once.
+- **What a node shows changed.** `Navigator.shownScreensChanged(node)`: tells the waiting layer, the parent stack's
+  queue (a pushed pair waits for its entry) and the modals' sheet. Called by `StackController`, `BottomTabsController`,
+  `SideMenuController`, `SplitViewController` and `ArrangementController`. The system UI is told by the presenters
+  (`SystemUiOwner.of(activity)` then `invalidate`).
+- **Modal records.** `ModalCoordinator` and `ModalRecord` (states `Waiting`, `Presenting`, `Shown`, `Dismissing`,
+  `ClosedBelow`, `WithOldRoot`, `Gone`). Nothing else keeps a list of modals. Android has no presentation gate:
+  transitions overlap.
+- **Overlays.** `OverlayCoordinator` and `OverlayRecord`; no animation, no part of the state; `OverlayTouches` decides
+  which touches an overlay takes.
+- **System UI owner.** `SystemUiOwner`, one per `Navigator`, started and released by the activity. Changes only mark it
+  (`invalidate`); before the next frame it asks `SystemUiLayers` which layer decides each group, computes the state
+  with `SystemUiRules` and writes the differences through `SystemUiWindow`, the only code that writes to the window.
+  Without edge to edge it also writes the window's soft input adjust (`layout.adjustResize: false` of the top
+  non-overlay layer: the keyboard covers the screen; else the manifest's mode).
+- **Reload.** `ReloadCoordinator`: `generation` grows when the JavaScript goes (`ReactGateway` tells it);
+  `Navigator.destroy` removes every layer silently and clears the registry; `AppLaunched` is sent once per pair of
+  activity and React context. Stores are cleared with their nodes.
+- **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.
+- **Error texts.** `ErrorTexts`: one function per text, the same words as iOS. JavaScript adds `[navigation] <command>:`.
+- **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
+  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
+  view's panes, the pair's screens) keeps its bookkeeping in `ShownChildren`, which sends the appearances through the
+  dispatcher's order (`beginTransition`, then `endTransition`: what left, then what came).
+
+## Modules
+
+Modules are the feature classes that plug into the core through its contract (the interface of
+`ARCHITECTURE.md` section 4). By area:
+
+- **Containers:** split view (`SplitViewController`, `SplitViewLayout`, `SplitPanes`), pair (`ArrangementController`,
+  `ArrangementLayout`, `ArrangementPlanner`).
+- **Presenters and bars:** search (`StackSearchPresenter`, `ScreenSearch`, `SearchPanel`), menus (`ButtonMenus`), FAB
+  (`Fab`, `FabMenu`), large title (`LargeTitleView`, `TopBarCollapseBehavior`), sheets (`ModalSheet`, `SheetOptions`),
+  custom row (`BottomTabsCustomRowOptions`).
+- **Views and helpers:** tabs bar (`BottomTabs`, `BottomTabItem`, `BottomTabsCollapseBehavior`, `scrollToTop`), slots
+  (`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`).
+
+How they plug in:
+
+- **Containers** extend `ParentController` and give the core the children it asks for: `getChildControllers`,
+  `getCurrentChild`, `visibleChildren()` (what appears with the layout; several for a side menu or two panes),
+  `waitedChildren()` (what a wait for rendering waits for) and `resolveChildOptions` / `applyChildOptions` /
+  `mergeChildOptions`. When what they show changes they call `Navigator.shownScreensChanged`; when children move in
+  or out of the window by themselves they report through `ShownChildren`.
+- **Capabilities** (`Capabilities.kt`) replace class checks; a node without one answers "no". `nodeWith<T>` finds the
+  nearest node with it:
+  `ReturnsScreenFromColumn` (a pop of a column's only screen goes back to the column before), `ScreensLeavingWithNode`
+  (a pair takes both screens out of a stack; `ScreenPopped` for each), `ChildOffsetFromRest` (a moving child counts its
+  safe area where it rests), `OptionsScreen` (the screen whose options are the node's), `KeepsStatusBarRoom` (marker:
+  the node keeps the status bar's room, its screens none), `ShowsColumns` (`showInColumn`, `setColumnShown`).
+- **Presenters** extend `Presenter` and override `applyOptions`, `mergeOptions`, `onConfigurationChanged`. The split view
+  gets options from its module; the core's `SplitViewPresenter` only hands it the new defaults after
+  `setDefaultOptions` (`setSplitOptions`).
+- **Content** is `IReactView`: `ReactView` for a React screen, `SlotScreenView` for a name starting with `slot:`
+  (`ScreenContentFactory`), and the view of a pair, which stands for its primary. The core asks only id, appearance
+  record, readiness, mounted, stop and touches.
+- **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.