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

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [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),
@@ -104,7 +104,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 +144,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
@@ -166,6 +170,8 @@ top-level folder. Main thread only, unless a line says otherwise.
 - 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.

package/android/CORE.md

@@ -165,7 +165,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/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)
     }
 }

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

@@ -1,3 +1,5 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/errors.json: change that file and run the script again.
+
 package dev.apexnative.navigation.react
 
 /**
@@ -6,116 +8,129 @@ package dev.apexnative.navigation.react
  * <command>:`.
  */
 internal object ErrorTexts {
-    fun screenNotShown(id: String) = "the screen '$id' is not shown"
+    // Where the screen is.
+
+    fun screenNotShown(componentId: String) = "the screen '$componentId' is not shown"
 
-    fun notInStack(id: String) = "the screen '$id' is not in a stack"
+    fun notInStack(componentId: String) = "the screen '$componentId' is not in a stack"
 
-    fun firstScreenOfStack(id: String) = "the screen '$id' is the first screen of its stack"
+    fun firstScreenOfStack(componentId: String) = "the screen '$componentId' is the first screen of its stack"
 
-    fun notInThisStack(id: String) = "the screen '$id' is not in this stack"
+    fun notInThisStack(componentId: String) = "the screen '$componentId' is not in this stack"
 
-    fun notInModal(id: String) = "the screen '$id' is not in a modal"
+    fun notInModal(componentId: String) = "the screen '$componentId' is not in a modal"
 
-    fun notInOverlay(id: String) = "the screen '$id' is not in an overlay"
+    fun notInOverlay(componentId: String) = "the screen '$componentId' is not in an overlay"
 
-    fun notInSplitView(id: String) = "the screen '$id' is not in a split view"
+    fun notInSplitView(componentId: String) = "the screen '$componentId' is not in a split view"
 
-    fun neitherSplitViewNorStack(id: String) = "the screen '$id' is neither in a split view nor in a stack"
+    fun neitherSplitViewNorStack(componentId: String) =
+        "the screen '$componentId' is neither in a split view nor in a stack"
 
-    fun noSuchColumn(id: String, column: String) = "the split view of the screen '$id' has no '$column' column"
+    fun noSuchColumn(componentId: String, column: String) =
+        "the split view of the screen '$componentId' has no '$column' column"
 
-    fun columnIsStack(id: String, column: String) =
-        "the '$column' column of the split view of the screen '$id' is a stack: it takes a screen, not a stack"
+    fun columnIsStack(componentId: String, column: String) =
+        "the '$column' column of the split view of the screen '$componentId' is a stack: it takes a screen, not a stack"
 
-    fun columnNotStack(id: String, column: String) =
-        "the '$column' column of the split view of the screen '$id' is not a stack"
+    fun columnNotStack(componentId: String, column: String) =
+        "the '$column' column of the split view of the screen '$componentId' is not a stack"
 
-    fun noScreensForStack(id: String) = "there are no screens to put in the stack of the screen '$id'"
+    fun noScreensForStack(componentId: String) = "there are no screens to put in the stack of the screen '$componentId'"
 
-    fun alreadyShown(id: String) = "the screen '$id' shows already: an id goes to one screen"
+    fun alreadyShown(componentId: String) = "the screen '$componentId' shows already: an id goes to one screen"
 
-    fun setRootReplaced(id: String) =
-        "setRoot was replaced by a newer setRoot before the root '$id' finished showing"
+    // Root, modals, the app.
 
-    fun rootDestroyed(id: String) = "the root '$id' was destroyed before it showed"
+    fun setRootReplaced(rootId: String) =
+        "setRoot was replaced by a newer setRoot before the root '$rootId' finished showing"
 
-    fun modalWithoutRoot(id: String) = "the modal '$id' can't be dismissed: there is no root under it"
+    fun rootDestroyed(rootId: String) = "the root '$rootId' was destroyed before it showed"
+
+    fun modalWithoutRoot(componentId: String) = "the modal '$componentId' can't be dismissed: there is no root under it"
 
     fun nowhereToShow() = "the navigation has nowhere to show screens: the app has no activity or window"
 
+    // Native screens.
+
     fun nativeScreenNotRegistered(name: String) = "no native screen is registered as '$name'"
 
     fun nativeScreenNotCreated(name: String) =
         "the native screen '$name' could not be created: its creator returned nothing"
 
-    fun unknownNodeType(type: String) = "the layout has a node of unknown type '$type'"
+    /** The error of a call of a native screen whose JavaScript reloaded before it answered. */
+    fun nativeCallReloaded(name: String, componentId: String) =
+        "JavaScript reloaded before the call '$name' of the screen '$componentId' was answered"
 
-    fun nodeWithoutId(type: String) = "the layout has a node of type '$type' without an id"
+    /** The error of a call of a native screen while no JavaScript can answer it. */
+    fun nativeCallNotRunning(name: String, componentId: String) =
+        "the navigation is not running: the call '$name' of the screen '$componentId' can't be answered"
 
-    fun sideMenuChild(id: String, type: String) =
-        "the side menu '$id' has a child of type '$type': it takes SideMenuLeft, SideMenuCenter and SideMenuRight"
+    // The layout.
 
-    fun stackTakesScreens(id: String, type: String) = "the stack '$id' takes screens, not a '$type'"
+    fun unknownNodeType(type: String) = "the layout has a node of unknown type '$type'"
 
-    fun emptyStack(id: String) = "the stack '$id' has no screens"
+    fun nodeWithoutId(type: String) = "the layout has a node of type '$type' without an id"
 
-    fun emptyTabs(id: String) = "the tabs '$id' have no tabs"
+    fun sideMenuChild(menuId: String, type: String) =
+        "the side menu '$menuId' has a child of type '$type': it takes SideMenuLeft, SideMenuCenter and SideMenuRight"
 
-    fun tooManyTabs(id: String, count: Int) = "the tabs '$id' have $count tabs: Android shows at most 5"
+    fun stackTakesScreens(stackId: String, type: String) = "the stack '$stackId' takes screens, not a '$type'"
 
-    fun splitViewColumns(id: String) = "the split view '$id' needs its primary and its secondary column"
+    fun emptyStack(stackId: String) = "the stack '$stackId' has no screens"
 
-    fun pairUnsupported(id: String) = "the pair '$id' needs iOS 27.1 and an app built with its SDK"
+    fun emptyTabs(tabsId: String) = "the tabs '$tabsId' have no tabs"
 
-    fun pairNeedsTwoScreens(id: String) = "the pair '$id' needs two screens: its primary and its secondary"
+    /** Only Android checks it: its tab bar shows at most 5 tabs. */
+    fun tooManyTabs(tabsId: String, count: Int) = "the tabs '$tabsId' have $count tabs: Android shows at most 5"
 
-    fun unreadableOption(path: String, id: String) =
-        "the option '$path' of the screen '$id' has a value the navigation can't read"
+    fun splitViewColumns(splitViewId: String) =
+        "the split view '$splitViewId' needs its primary and its secondary column"
 
-    /** `setDefaultOptions` with a value it can't read; the default options before stay. */
-    fun unreadableDefaultOption(path: String) =
-        "the option '$path' of the default options has a value the navigation can't read"
+    /** Only iOS checks it: Android has pairs on every version. */
+    fun pairUnsupported(pairId: String) = "the pair '$pairId' needs iOS 27.1 and an app built with its SDK"
 
-    fun previewGone(id: String) = "the preview '$id' went without being opened"
+    fun pairNeedsTwoScreens(pairId: String) = "the pair '$pairId' needs two screens: its primary and its secondary"
 
-    /** Any other failure: [what] the command could not do, with its screen, and [reason]. */
-    fun couldNot(what: String, reason: String) = "could not $what: $reason"
+    fun nodeWithoutName(type: String, nodeId: String) = "the layout has a node '$nodeId' of type '$type' without a name"
 
-    fun nativeCallReloaded(name: String, id: String) =
-        "JavaScript reloaded before the call '$name' of the screen '$id' was answered"
+    fun rootMissing() = "the layout of setRoot has no root"
 
-    fun nativeCallNotRunning(name: String, id: String) =
-        "the navigation is not running: the call '$name' of the screen '$id' can't be answered"
+    fun tabsInTabs(tabsId: String) = "the tabs '$tabsId' have a tab of type 'BottomTabs': tabs don't go inside tabs"
 
-    /** `mergeOptions` without a navigation activity; written to the log, `mergeOptions` has no promise. */
-    fun mergeOptionsNoActivity() = nowhereToShow()
+    fun sideMenuSides(menuId: String) =
+        "the side menu '$menuId' takes one SideMenuCenter and at most one SideMenuLeft and one SideMenuRight"
 
-    /** A command whose area the native core doesn't do yet. */
-    fun notDoneYet(method: String) = "could not run '$method': the native core doesn't do it yet"
+    fun sideChildCount(sideId: String, menuId: String) =
+        "the side '$sideId' of the side menu '$menuId' needs exactly one child"
 
-    // The other cases of the layout checks: the same style.
+    fun sideMenuInSide(menuId: String) =
+        "the side menu '$menuId' has a side menu in a side: a side menu doesn't go inside a side menu"
 
-    fun nodeWithoutName(type: String, id: String) = "the layout has a node '$id' of type '$type' without a name"
+    fun sideOutsideMenu(nodeId: String, type: String) =
+        "the layout has a node '$nodeId' of type '$type' outside a side menu"
 
-    fun rootMissing() = "the layout of setRoot has no root"
+    fun splitViewInColumn(splitViewId: String) =
+        "the split view '$splitViewId' has a column of type 'SplitView': a split view doesn't go inside a split view"
 
-    fun tabsInTabs(id: String) = "the tabs '$id' have a tab of type 'BottomTabs': tabs don't go inside tabs"
+    fun idGivenTwice(nodeId: String) = "the layout gives the id '$nodeId' to two nodes"
 
-    fun sideMenuSides(id: String) =
-        "the side menu '$id' takes one SideMenuCenter and at most one SideMenuLeft and one SideMenuRight"
+    // Options, previews, any other failure.
 
-    fun sideChildCount(sideId: String, menuId: String) =
-        "the side '$sideId' of the side menu '$menuId' needs exactly one child"
+    fun unreadableOption(path: String, componentId: String) =
+        "the option '$path' of the screen '$componentId' has a value the navigation can't read"
 
-    fun sideMenuInSide(menuId: String) =
-        "the side menu '$menuId' has a side menu in a side: a side menu doesn't go inside a side menu"
+    /** An unreadable value of `setDefaultOptions`: the default options belong to no screen. */
+    fun unreadableDefaultOption(path: String) =
+        "the option '$path' of the default options has a value the navigation can't read"
 
-    fun sideOutsideMenu(id: String, type: String) = "the layout has a node '$id' of type '$type' outside a side menu"
+    fun previewGone(previewId: String) = "the preview '$previewId' went without being opened"
 
-    fun splitViewInColumn(id: String) =
-        "the split view '$id' has a column of type 'SplitView': a split view doesn't go inside a split view"
+    /** Any other failure: what could not be done and why, `could not <what>: <reason>`. */
+    fun couldNot(what: String, reason: String) = "could not $what: $reason"
 
-    fun idGivenTwice(id: String) = "the layout gives the id '$id' to two nodes"
+    /** A command whose part of the native core is not written yet. */
+    fun notDoneYet(method: String) = "could not run '$method': the native core doesn't do it yet"
 
     /** The reason of [couldNot] for an exception: its message, else the name of its class. */
     fun reasonOf(e: Throwable): String =

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

@@ -12,6 +12,7 @@ import androidx.lifecycle.LifecycleOwner
 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 dev.apexnative.navigation.utils.WindowFolds
 import java.lang.ref.WeakReference
@@ -148,7 +149,7 @@ internal object Hinge {
 
     private fun toMap(value: Value?): WritableMap = Arguments.createMap().apply {
         if (value == null) return@apply
-        putString("state", value.state)
-        value.angle?.let { putDouble("angle", it.toDouble()) }
+        putString(EventContract.HingeChanged.STATE, value.state)
+        value.angle?.let { putDouble(EventContract.HingeChanged.ANGLE, it.toDouble()) }
     }
 }

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

@@ -73,7 +73,7 @@ internal class OptionsCommands(
         prepare = { OptionsReader.read(options, context()) },
     ) { read ->
         if (!runner.hasActivity()) {
-            runner.logFailure(MERGE_OPTIONS, ErrorTexts.mergeOptionsNoActivity())
+            runner.logFailure(MERGE_OPTIONS, ErrorTexts.nowhereToShow())
             return@runVoid
         }
         val node = findNode(componentId) ?: return@runVoid

package/android/src/main/java/dev/apexnative/navigation/react/ScreenInsets.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
 
@@ -61,9 +62,9 @@ object ScreenInsets {
     }
 
     private fun toMap(value: Insets): WritableMap = Arguments.createMap().apply {
-        putDouble("top", value.top)
-        putDouble("right", value.right)
-        putDouble("bottom", value.bottom)
-        putDouble("left", value.left)
+        putDouble(EventContract.ScreenInsetsChanged.TOP, value.top)
+        putDouble(EventContract.ScreenInsetsChanged.RIGHT, value.right)
+        putDouble(EventContract.ScreenInsetsChanged.BOTTOM, value.bottom)
+        putDouble(EventContract.ScreenInsetsChanged.LEFT, value.left)
     }
 }