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

package/lib/typescript/interfaces/options/sideMenu.d.ts

@@ -18,8 +18,8 @@ export interface SideMenuSide {
     visible?: boolean;
     /**
      * Whether the opening or closing that `visible` asks for is animated. With `false` it happens at once and the
-     * screens of the menu get the same appearance events in the same order, except that on Android a menu that opens at
-     * once sends its screens DidAppear without WillAppear. It acts only together with `visible` in the same merge.
+     * screens of the menu get the same appearance events in the same order: WillAppear, then DidAppear. It acts only
+     * together with `visible` in the same merge.
      * @default true
      */
     animate?: boolean;
@@ -32,15 +32,16 @@ export interface SideMenuSide {
     enabled?: boolean;
     /**
      * The width of the menu, in points on iOS and dp on Android. It is capped at the width of the side menu (iOS) and at
-     * that width less 64 dp (Android). On iOS a change applies at once, also to an open menu. On Android it applies the
-     * next time a screen in the side menu appears, the center's or a menu's.
+     * that width less 64 dp (Android). A change in `mergeOptions` applies at once, also to an open menu. A width set by
+     * a screen of the center acts while that screen shows.
      * Without it, 280 points on iOS and the width of the side menu less 64 dp on Android (the least gap the Material
      * drawer leaves).
      */
     width?: number;
     /**
-     * (Android) The height of the menu in dp; a menu lower than the container is pinned to the top. It is read only when
-     * the side menu is created. Without it, the menu takes the full height under the status bar. iOS doesn't read it.
+     * (Android) The height of the menu in dp; a menu lower than the container is pinned to the top. A change in
+     * `mergeOptions` applies at once, also to an open menu. Without it, the menu takes the full height under the status
+     * bar. iOS doesn't read it.
      */
     height?: number;
     /**

package/lib/typescript/interfaces/options/sideMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sideMenu.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/sideMenu.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC;IAC1C;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,cAAc,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,OAAO,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"sideMenu.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/sideMenu.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC;IAC1C;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,cAAc,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,OAAO,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/lib/typescript/interfaces/options/system.d.ts

@@ -165,9 +165,10 @@ export interface OptionsStatusBar {
      */
     hideWithTopBar?: boolean;
     /**
-     * (iOS) Whether a blur shows under the status bar, drawn over the screen in the frame the status bar has when the
-     * option applies. It applies when the screen appears and through `mergeOptions`; `false` removes it. The blur does
-     * not follow a rotation or a change of window size.
+     * (iOS) Whether a blur shows under the status bar, drawn over the screen in the status bar's frame. It applies when
+     * the screen appears and through `mergeOptions`; `false` removes it. The blur follows the status bar's frame as it
+     * changes: a rotation, a new window size, the status bar hidden or shown. Android has no blur under the status bar,
+     * so it does nothing there.
      * @default false
      */
     blur?: boolean;

package/lib/typescript/interfaces/options/system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAU,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,SAAS,GACT,UAAU,GACV,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,iBAAiB,GACjB,gBAAgB,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,KAAK,CAAC;IACjC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC;IACrC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qHAAqH;AACrH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjG;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,+GAA+G;IAC/G,SAAS,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACxC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../../../src/interfaces/options/system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAU,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,SAAS,GACT,UAAU,GACV,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,iBAAiB,GACjB,gBAAgB,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,KAAK,CAAC;IACjC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC;IACrC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qHAAqH;AACrH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjG;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,+GAA+G;IAC/G,SAAS,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACxC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apexnative/navigation",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "Native navigation for React Native: platform stacks, tabs, modals and side menus on iOS, iPadOS and Android",
   "keywords": [
     "react-native",

package/src/ARCHITECTURE.md

@@ -63,7 +63,8 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
   `LinkParams`, `PendingLink`, …). `linkPaths.ts`: a URL into its path and query (`parseLink`), the patterns ordered
   (`compileRoutes`) and matched (`matchLink`). `linking.ts`: the links of the app — the launch link, the `url` events
   of React Native's `Linking`, the routes run, the pending link opened after `setContext`. `pendingLinks.ts`: the one
-  waiting link and its listeners, which `navigation` and `usePendingLink` read.
+  waiting link and its listeners, which `navigation` and `usePendingLink` read. `dispatchedLinks.ts` (iOS): hands
+  `Linking` the links of `ANN.DeepLinkDispatched`.
 - `events/` — `navigationEvents.ts`: the events by name, the native event behind each, `onNavigationEvent`,
   `listeners`. `screenLifecycle.ts`: what goes when a screen unmounts, `whenScreenUnmounts`. `tabPresses.ts`: the
   handlers of `useTabPress`.
@@ -268,7 +269,9 @@ its push, which the hook ignores.
   given once; JS asks only with `linking`) and `getStartInfo` (synchronous: `coldStart`, true for the whole life of
   the first JavaScript runtime of the process, and `splashLogo`, the size of the native splash's logo the CLI wrote,
   or null; `arrangements`, whether it shows pairs). The links that come while the app runs reach JS through React Native's
-  `Linking`, not through `ANN.*` events.
+  `Linking`, not through `ANN.*` events. One exception, iOS only: a link the app dispatched (`dispatchDeepLinkURL`) that
+  `Linking` doesn't take from the native side (React Native 0.88 and newer, with a scene delegate) comes as
+  `ANN.DeepLinkDispatched`, and `src/api/linking/dispatchedLinks.ts` hands it to `Linking` as a `url` event.
 - Events: `ANN.AppLaunched`, `ANN.ComponentWillAppear`, `ANN.ComponentDidAppear`, `ANN.ComponentDidDisappear`,
   `ANN.NavigationButtonPressed`, `ANN.BottomTabSelected`, `ANN.BottomTabPressed`, `ANN.BottomTabLongPressed`,
   `ANN.ModalDismissed`, `ANN.ModalAttemptedToDismiss`, `ANN.ScreenPopped`, `ANN.SearchBarUpdated`,
@@ -276,8 +279,8 @@ its push, which the hook ignores.
   `ANN.NavigationStateChanged`, `ANN.SlotDestroyed`, `ANN.ScreenInsetsChanged`, `ANN.TitleRenamed`,
   `ANN.BottomAccessoryPlacementChanged`, `ANN.SheetDetentChanged`, `ANN.SplitViewDisplayModeChanged`,
   `ANN.KeyCommandPressed`, `ANN.NativeScreenCall`, `ANN.NativeScreenReleased`, `ANN.ScreenRegionsChanged`,
-  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`. Their payloads are typed in
-  `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
+  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`, `ANN.DeepLinkDispatched` (iOS). Their
+  payloads are typed in `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
   (`CommandCompletedEvent`), which nothing in JS listens to.
 - Native components: `ANNSlot` (`src/api/slots`) and `ANNSafeAreaView` (`src/api/safeArea`), with C++ of their own in
   `ios/cpp`, which Android builds too (their states hold a size and a padding; the first one comes from the props

package/src/api/app/createNavigation.ts

@@ -43,6 +43,7 @@ import {
 import { launchState } from '../../engine/launchState';
 import { watchBackListeners } from '../../engine/backListeners';
 import { resolveRoot, type RootsMap, type RootTarget, type UsesOfRootValue } from './roots';
+import { listenToDispatchedLinks } from '../linking/dispatchedLinks';
 import {
   launchLink,
   launchRoot,
@@ -501,6 +502,7 @@ export function createNavigation<
       if (config.context !== undefined) setAppContext(config.context);
       if (config.appProvider) enableSlots(config.appProvider);
       listenToNavigationState();
+      listenToDispatchedLinks();
       watchSideMenus();
       listenToNativeScreens();
       listenToSplitViews();

package/src/api/linking/dispatchedLinks.ts

@@ -0,0 +1,18 @@
+import { DeviceEventEmitter, Platform } from 'react-native';
+import { onNativeEvent } from '../../engine/native';
+import type { DeepLinkDispatchedEvent } from '../../interfaces/Events';
+
+let listening = false;
+
+/**
+ * (iOS) Hands `Linking` the links the app dispatched that it didn't take from the native side: on React Native 0.88
+ * and newer, in an app with a scene delegate, it takes only the links a scene opened. `Linking` listens to its `url`
+ * events through `DeviceEventEmitter`, so every listener of the app gets them, the navigation's links too.
+ */
+export function listenToDispatchedLinks() {
+  if (listening || Platform.OS !== 'ios') return;
+  listening = true;
+  onNativeEvent<DeepLinkDispatchedEvent>('DeepLinkDispatched', ({ url }) => {
+    DeviceEventEmitter.emit('url', { url });
+  });
+}

package/src/interfaces/Events.ts

@@ -105,6 +105,16 @@ export interface SplitViewColumnsStackedEvent {
   stacked: boolean;
 }
 
+/**
+ * (iOS) A link the app dispatched (`dispatchDeepLinkURL`) that React Native's `Linking` doesn't take from the native
+ * side: on React Native 0.88 and newer, in an app whose Info.plist names a scene delegate, it takes only the links a
+ * scene opened. JavaScript hands it to `Linking` as a `url` event.
+ */
+export interface DeepLinkDispatchedEvent {
+  /** The link. */
+  url: string;
+}
+
 /**
  * A screen of the single React tree was destroyed and the slot still belongs to it: JavaScript removes the slot from
  * its tree. It is not sent for a prepared screen that was never pushed, nor when JavaScript reloads.

package/src/interfaces/contract/errors.json

@@ -0,0 +1,275 @@
+{
+  "description": "Every text the native side rejects a command with, or logs for a command without a promise: one sentence per case, the values in single quotes, {name} for a parameter. scripts/contract.mjs makes ios/Contract/ANNErrorTexts.{h,mm} and android/.../react/ErrorTexts.kt from it; `platforms` limits a text to one platform.",
+  "groups": [
+    {
+      "title": "Where the screen is",
+      "texts": [
+        {
+          "name": "screenNotShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not shown"
+        },
+        {
+          "name": "notInStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a stack"
+        },
+        {
+          "name": "firstScreenOfStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is the first screen of its stack"
+        },
+        {
+          "name": "notInThisStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in this stack"
+        },
+        {
+          "name": "notInModal",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a modal"
+        },
+        {
+          "name": "notInOverlay",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in an overlay"
+        },
+        {
+          "name": "notInSplitView",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a split view"
+        },
+        {
+          "name": "neitherSplitViewNorStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is neither in a split view nor in a stack"
+        },
+        {
+          "name": "noSuchColumn",
+          "params": ["componentId", "column"],
+          "text": "the split view of the screen '{componentId}' has no '{column}' column"
+        },
+        {
+          "name": "columnIsStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is a stack: it takes a screen, not a stack"
+        },
+        {
+          "name": "columnNotStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is not a stack"
+        },
+        {
+          "name": "noScreensForStack",
+          "params": ["componentId"],
+          "text": "there are no screens to put in the stack of the screen '{componentId}'"
+        },
+        {
+          "name": "alreadyShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' shows already: an id goes to one screen"
+        }
+      ]
+    },
+    {
+      "title": "Root, modals, the app",
+      "texts": [
+        {
+          "name": "setRootReplaced",
+          "params": ["rootId"],
+          "text": "setRoot was replaced by a newer setRoot before the root '{rootId}' finished showing"
+        },
+        {
+          "name": "rootDestroyed",
+          "params": ["rootId"],
+          "text": "the root '{rootId}' was destroyed before it showed"
+        },
+        {
+          "name": "modalWithoutRoot",
+          "params": ["componentId"],
+          "text": "the modal '{componentId}' can't be dismissed: there is no root under it"
+        },
+        {
+          "name": "nowhereToShow",
+          "params": [],
+          "text": "the navigation has nowhere to show screens: the app has no activity or window"
+        }
+      ]
+    },
+    {
+      "title": "Native screens",
+      "texts": [
+        {
+          "name": "nativeScreenNotRegistered",
+          "params": ["name"],
+          "text": "no native screen is registered as '{name}'"
+        },
+        {
+          "name": "nativeScreenNotCreated",
+          "params": ["name"],
+          "text": "the native screen '{name}' could not be created: its creator returned nothing"
+        },
+        {
+          "name": "nativeCallReloaded",
+          "params": ["name", "componentId"],
+          "text": "JavaScript reloaded before the call '{name}' of the screen '{componentId}' was answered",
+          "doc": "The error of a call of a native screen whose JavaScript reloaded before it answered."
+        },
+        {
+          "name": "nativeCallNotRunning",
+          "params": ["name", "componentId"],
+          "text": "the navigation is not running: the call '{name}' of the screen '{componentId}' can't be answered",
+          "doc": "The error of a call of a native screen while no JavaScript can answer it."
+        }
+      ]
+    },
+    {
+      "title": "The layout",
+      "texts": [
+        {
+          "name": "unknownNodeType",
+          "params": ["type"],
+          "text": "the layout has a node of unknown type '{type}'"
+        },
+        {
+          "name": "nodeWithoutId",
+          "params": ["type"],
+          "text": "the layout has a node of type '{type}' without an id"
+        },
+        {
+          "name": "sideMenuChild",
+          "params": ["menuId", "type"],
+          "text": "the side menu '{menuId}' has a child of type '{type}': it takes SideMenuLeft, SideMenuCenter and SideMenuRight"
+        },
+        {
+          "name": "stackTakesScreens",
+          "params": ["stackId", "type"],
+          "text": "the stack '{stackId}' takes screens, not a '{type}'"
+        },
+        {
+          "name": "emptyStack",
+          "params": ["stackId"],
+          "text": "the stack '{stackId}' has no screens"
+        },
+        {
+          "name": "emptyTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have no tabs"
+        },
+        {
+          "name": "tooManyTabs",
+          "params": [
+            "tabsId",
+            {
+              "name": "count",
+              "type": "int"
+            }
+          ],
+          "text": "the tabs '{tabsId}' have {count} tabs: Android shows at most 5",
+          "doc": "Only Android checks it: its tab bar shows at most 5 tabs."
+        },
+        {
+          "name": "splitViewColumns",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' needs its primary and its secondary column"
+        },
+        {
+          "name": "pairUnsupported",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs iOS 27.1 and an app built with its SDK",
+          "doc": "Only iOS checks it: Android has pairs on every version."
+        },
+        {
+          "name": "pairNeedsTwoScreens",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs two screens: its primary and its secondary"
+        },
+        {
+          "name": "nodeWithoutName",
+          "params": ["type", "nodeId"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' without a name"
+        },
+        {
+          "name": "rootMissing",
+          "params": [],
+          "text": "the layout of setRoot has no root"
+        },
+        {
+          "name": "tabsInTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have a tab of type 'BottomTabs': tabs don't go inside tabs"
+        },
+        {
+          "name": "sideMenuSides",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' takes one SideMenuCenter and at most one SideMenuLeft and one SideMenuRight"
+        },
+        {
+          "name": "sideChildCount",
+          "params": ["sideId", "menuId"],
+          "text": "the side '{sideId}' of the side menu '{menuId}' needs exactly one child"
+        },
+        {
+          "name": "sideMenuInSide",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' has a side menu in a side: a side menu doesn't go inside a side menu"
+        },
+        {
+          "name": "sideOutsideMenu",
+          "params": ["nodeId", "type"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' outside a side menu"
+        },
+        {
+          "name": "splitViewInColumn",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' has a column of type 'SplitView': a split view doesn't go inside a split view"
+        },
+        {
+          "name": "idGivenTwice",
+          "params": ["nodeId"],
+          "text": "the layout gives the id '{nodeId}' to two nodes"
+        }
+      ]
+    },
+    {
+      "title": "Options, previews, any other failure",
+      "texts": [
+        {
+          "name": "unreadableOption",
+          "params": ["path", "componentId"],
+          "text": "the option '{path}' of the screen '{componentId}' has a value the navigation can't read"
+        },
+        {
+          "name": "unreadableDefaultOption",
+          "params": ["path"],
+          "text": "the option '{path}' of the default options has a value the navigation can't read",
+          "doc": "An unreadable value of `setDefaultOptions`: the default options belong to no screen."
+        },
+        {
+          "name": "previewGone",
+          "params": ["previewId"],
+          "text": "the preview '{previewId}' went without being opened"
+        },
+        {
+          "name": "couldNot",
+          "params": ["what", "reason"],
+          "text": "could not {what}: {reason}",
+          "doc": "Any other failure: what could not be done and why, `could not <what>: <reason>`."
+        },
+        {
+          "name": "notDoneYet",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core doesn't do it yet",
+          "doc": "A command whose part of the native core is not written yet."
+        },
+        {
+          "name": "notAnswered",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core let it go without an answer",
+          "doc": "A command that nothing in the native core answered: what took it let it go, or nothing took it.",
+          "platforms": ["ios"]
+        }
+      ]
+    }
+  ]
+}

package/src/interfaces/options/animations.ts

@@ -254,13 +254,14 @@ export type ElementAnimation = AppearingElementAnimation | DisappearingElementAn
 /**
  * An animation of one view of a screen that moves together with the transition, with or without a counterpart on the
  * other screen. The view is found by its `nativeID`, first on the screen that goes, then on the one that comes; one
- * that is not found is skipped while the rest plays. The transition waits until it is found. Without an animation of
- * the screens of its own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the
- * elements. When the transition ends or is cancelled, the element gets its own values back. `x` and `y` are the
- * position in the parent of the element on both platforms. As on a side of a screen, don't set `x` with `translationX`
- * or `y` with `translationY` on one element: the translation plays and the position doesn't. (Android) A view whose
- * parent is a React view with `removeClippedSubviews` turned on, such as a child of a clipping list, is not moved: it
- * counts as not found.
+ * that is not found is skipped while the rest plays. The transition waits until it is found. An element that fails on
+ * the way (an error in its animation) is skipped too, with a warning in the log: it shows and hides with its screen,
+ * and the transition and its command go on. Without an animation of the screens of its own, the screen that comes fades
+ * in (or the one that goes fades out) in 300 ms around the elements. When the transition ends or is cancelled, the
+ * element gets its own values back. `x` and `y` are the position in the parent of the element on both platforms. As on
+ * a side of a screen, don't set `x` with `translationX` or `y` with `translationY` on one element: the translation
+ * plays and the position doesn't. (Android) A view whose parent is a React view with `removeClippedSubviews` turned on,
+ * such as a child of a clipping list, is not moved: it counts as not found.
  */
 export interface ElementTransition {
   /** The `nativeID` of the view to animate. */
@@ -288,12 +289,15 @@ export interface ElementTransition {
 }
 
 /**
- * A view that flies from the screen that goes to the screen that comes, changing its place, size, corners and look
- * on the way. A pair whose view is not found on either screen is skipped while the rest plays, and the transition
- * waits until the views are found. Without an animation of the screens of its own, the screen that comes fades in (or
- * the one that goes fades out) in 300 ms around the pair. Text keeps its proportions and changes its picture within a
- * quarter of the flight. (Android) A picture that doesn't load within a second drops out of the transition, and so does
- * a pair with a view whose parent is a React view with `removeClippedSubviews` turned on: it counts as not found.
+ * A view that flies from the screen that goes to the screen that comes, changing its place, size, corners and look on
+ * the way. A pair whose view is not found on either screen is skipped while the rest plays, and the transition waits
+ * until the views are found. A pair that fails on the way (an error in its start or its flight) is skipped too, with a
+ * warning in the log: its views show and hide with their screens, and the transition and its command go on. (iOS) So is
+ * a pair with a view without a size, or one whose picture can't be taken. Without an animation of the screens of its
+ * own, the screen that comes fades in (or the one that goes fades out) in 300 ms around the pair. Text keeps its
+ * proportions and changes its picture within a quarter of the flight. (Android) A picture that doesn't load within a
+ * second drops out of the transition, and so does a pair with a view whose parent is a React view with
+ * `removeClippedSubviews` turned on: it counts as not found.
  */
 export interface SharedElementTransition {
   /** The `nativeID` of the view on the screen that goes. */

package/src/interfaces/options/modals.ts

@@ -32,9 +32,11 @@ export type OptionsModalPresentationStyle =
  * (iOS) The system transition a modal comes and goes with: `'coverVertical'` (from below), `'crossDissolve'` (a fade),
  * `'flipHorizontal'` (a flip) or `'partialCurl'`. It is read when the modal shows and doesn't change afterwards;
  * `animations.showModal` with values of its own, and the zoom of iOS 18, go over it. UIKit flips only a modal over the
- * whole screen (`'fullScreen'`, `'overFullScreen'`): a sheet comes in as usual and flips only on its way out, and
- * `'partialCurl'` is accepted by UIKit only for a full-screen modal. An unknown string means `'coverVertical'`. Android
- * doesn't read it.
+ * whole screen (`'fullScreen'`, `'overFullScreen'`): a sheet comes in as usual and flips only on its way out. UIKit
+ * curls only a `'fullScreen'` modal over a screen that fills the window, so `'partialCurl'` with any other
+ * `modalPresentationStyle` (or without one), or over a modal that doesn't fill the screen, shows as `'coverVertical'`.
+ * A modal shown with `'partialCurl'` can't show another modal over it: that `showModal` rejects. An unknown string
+ * means `'coverVertical'`. Android doesn't read it.
  */
 export type OptionsModalTransitionStyle =
   'coverVertical' | 'crossDissolve' | 'flipHorizontal' | 'partialCurl';
@@ -59,18 +61,20 @@ export type OptionsModalSheetDetent = 'medium' | 'large' | 'content' | number;
  */
 export interface OptionsModalSheet {
   /**
-   * The stops the sheet can rest on, and the user drags it between. On Android they are sorted by height and repeats
-   * dropped; the Material sheet has three resting places at most: the lowest stop of the list, the highest, and
-   * `'medium'` between them when the list has both `'medium'` and `'large'`. A stop without a place is dropped. On iOS
-   * the stops are handed to UIKit in the order given, which wants them from the lowest to the highest; a list left
-   * empty by unsupported values gives `['large']`.
+   * The stops the sheet can rest on, and the user drags it between, in any order: on both platforms they are sorted by
+   * height and repeats dropped. On iOS `'medium'` counts as half of `'large'` there, and `'content'` takes its place by
+   * the height of the content, again whenever that changes; a list left empty by unsupported values gives
+   * `['large']`. On Android the Material sheet has three resting places at most: the lowest stop of the list, the
+   * highest, and `'medium'` between them when the list has both `'medium'` and `'large'`. A stop without a place is
+   * dropped.
    * @default ['large']
    */
   detents?: OptionsModalSheetDetent[];
   /**
-   * The stop the sheet opens on; a new value in `mergeOptions` moves the sheet there with an animation, and doesn't
-   * send `sheetDetentChanged`. A value that isn't among `detents` opens on the lowest stop on iOS and is ignored on
-   * Android.
+   * The stop the sheet opens on; a `mergeOptions` that names it moves the sheet there with an animation, and doesn't
+   * send `sheetDetentChanged`. Nothing else moves the sheet off the stop it stands at, the one the user dragged it to
+   * included: a `mergeOptions` without it, a new layout or new content. A value that isn't among `detents` opens on
+   * the lowest stop on iOS and is ignored on Android.
    * Without it, the lowest stop.
    */
   selectedDetent?: OptionsModalSheetDetent;

package/src/interfaces/options/sideMenu.ts

@@ -18,8 +18,8 @@ export interface SideMenuSide {
   visible?: boolean;
   /**
    * Whether the opening or closing that `visible` asks for is animated. With `false` it happens at once and the
-   * screens of the menu get the same appearance events in the same order, except that on Android a menu that opens at
-   * once sends its screens DidAppear without WillAppear. It acts only together with `visible` in the same merge.
+   * screens of the menu get the same appearance events in the same order: WillAppear, then DidAppear. It acts only
+   * together with `visible` in the same merge.
    * @default true
    */
   animate?: boolean;
@@ -32,15 +32,16 @@ export interface SideMenuSide {
   enabled?: boolean;
   /**
    * The width of the menu, in points on iOS and dp on Android. It is capped at the width of the side menu (iOS) and at
-   * that width less 64 dp (Android). On iOS a change applies at once, also to an open menu. On Android it applies the
-   * next time a screen in the side menu appears, the center's or a menu's.
+   * that width less 64 dp (Android). A change in `mergeOptions` applies at once, also to an open menu. A width set by
+   * a screen of the center acts while that screen shows.
    * Without it, 280 points on iOS and the width of the side menu less 64 dp on Android (the least gap the Material
    * drawer leaves).
    */
   width?: number;
   /**
-   * (Android) The height of the menu in dp; a menu lower than the container is pinned to the top. It is read only when
-   * the side menu is created. Without it, the menu takes the full height under the status bar. iOS doesn't read it.
+   * (Android) The height of the menu in dp; a menu lower than the container is pinned to the top. A change in
+   * `mergeOptions` applies at once, also to an open menu. Without it, the menu takes the full height under the status
+   * bar. iOS doesn't read it.
    */
   height?: number;
   /**

package/src/interfaces/options/system.ts

@@ -177,9 +177,10 @@ export interface OptionsStatusBar {
    */
   hideWithTopBar?: boolean;
   /**
-   * (iOS) Whether a blur shows under the status bar, drawn over the screen in the frame the status bar has when the
-   * option applies. It applies when the screen appears and through `mergeOptions`; `false` removes it. The blur does
-   * not follow a rotation or a change of window size.
+   * (iOS) Whether a blur shows under the status bar, drawn over the screen in the status bar's frame. It applies when
+   * the screen appears and through `mergeOptions`; `false` removes it. The blur follows the status bar's frame as it
+   * changes: a rotation, a new window size, the status bar hidden or shown. Android has no blur under the status bar,
+   * so it does nothing there.
    * @default false
    */
   blur?: boolean;