@apexnative/navigation 1.0.0-alpha.5 → 1.0.0-alpha.6

package/src/ARCHITECTURE.md

@@ -248,10 +248,14 @@ name and on one id for two screens.
 
 `usePreview(nativeID, { screen, props, actions })` works on iOS only. It arms a `pushPreview` from its screen: a push
 with an id of its own (`Preview14`) and a `preview` option (`nativeID`, `commit`, the menu without its handlers, a
-size). The native side builds the screen and gives the view with that `nativeID` a context menu that previews it. A tap
-on the preview pushes the screen, the push resolves, and the hook arms the next one. A press of a menu item comes as
-`buttonPressed` of the preview's id, and the hook calls its `onPress`. A preview that goes without being shown rejects
-its push, which the hook ignores.
+size). The native side makes the screen's node at once and gives the view with that `nativeID` a context menu that
+previews it; a React screen gets its own root and renders when a press starts (the menu's configuration call, about
+0.5 s before the preview), so a hundred previews hold no rendered screens until one is pressed. A screen of the one
+tree (`appProvider`) and a native screen render at once. A tap on the preview pushes the screen, the push resolves, and
+the hook arms the next one. A press of a menu item comes as `buttonPressed` of the preview's id, and the hook calls its
+`onPress`. A preview that goes without being shown rejects its push, which the hook ignores. One that goes before its
+first press never mounted a root, so the engine forgets what the push noted for it (`forgetUnmountedPreview` in
+`src/engine/commands.ts`, after 1 s, unless a root of it mounted by then).
 
 ## The native side's contract
 

package/src/api/app/createNavigation.ts

@@ -151,9 +151,9 @@ interface BaseConfig<
   /** The look of the navigation: colors of the bars, tabs and backgrounds; `navigation.setTheme` changes it. */
   theme?: NavigationTheme;
   /**
-   * The edges on which every screen keeps its content out of its safe area. Without it: all four on Android; on iOS
-   * every edge but those where the content goes under a bar that shows. A screen gives its own with `safeArea(...)`
-   * in its options.
+   * The edges on which every screen keeps its content out of its safe area. Without it: the top and the sides, but
+   * those where the content goes under a bar (`layout.safeAreaEdges`); the bottom is free and a list keeps clear of it
+   * with `useSafeAreaInsets()`. A screen gives its own with `safeArea(...)` in its options.
    */
   safeArea?: { edges: SafeAreaEdge[] };
   /** (iOS) The app's window, behind the screens: seen around a modal as it comes in. */

package/src/api/hooks/useSafeAreaInsets.ts

@@ -5,13 +5,14 @@ import { useScreen } from './screenHooks';
 /**
  * How much of this screen's content the bars and the system still cover on each side, past what the screen keeps its
  * content off itself (`layout.safeAreaEdges`): 0 on an edge the screen pads, the whole inset on an edge its content goes
- * under — under a top bar, under the vertical bar at the side of iPhone Duo, every edge with `safeAreaEdges: []`. A list
- * adds exactly this to its own padding. The native side measures every screen on its own, also the screens of
+ * under — the bottom by default (the home indicator, the navigation bar, a tab bar or toolbar the screen goes under),
+ * under a top bar, under the vertical bar at the side of iPhone Duo, every edge with `safeAreaEdges: []`. A list adds
+ * exactly this to its own padding. The native side measures every screen on its own, also the screens of
  * `appProvider`.
  *
  * @example
  * const insets = useSafeAreaInsets();
- * <ScrollView contentContainerStyle={{ paddingLeft: 16 + insets.left, paddingRight: 16 + insets.right }} />
+ * <ScrollView contentContainerStyle={{ paddingBottom: 16 + insets.bottom }} />
  */
 export function useSafeAreaInsets(): EdgeInsets {
   const { id } = useScreen();

package/src/api/options/OptionsChain.ts

@@ -68,8 +68,8 @@ export abstract class OptionsChain {
 
   /**
    * The edges on which the screen keeps its content out of its safe area (bars, status bar, home indicator, cutout);
-   * none with no edge. Without it: all four on Android, and on iOS every edge but those where the content goes under
-   * a bar. On iOS a large title leaves the top out by itself.
+   * none with no edge. Without it: the top and the sides, but those where the content goes under a bar; the bottom is
+   * free, and a list keeps clear of it with `useSafeAreaInsets()`. A large title leaves the top out by itself.
    */
   safeArea(...edges: SafeAreaEdge[]): this {
     return this.layout({ safeAreaEdges: edges });

package/src/engine/commands.ts

@@ -17,7 +17,7 @@ import {
   rootGoesOut,
   sentRoot,
 } from './rememberedOptions';
-import { afterLoading } from './screens';
+import { afterLoading, hasRoot, isReactScreen } from './screens';
 import { holdSlot, isSlotName, removeSlots, showSlot, type SlotFrame } from './slots';
 import { forgetTabsScreen, showScreensFrom } from './tabs';
 
@@ -229,16 +229,40 @@ export function push(
         layoutsOf(componentId)
       );
       return whenNativeScreensReady([node], () =>
-        sendPush(commandId, componentId, node, prepares, wanted, goneOut).then((shownId) => {
-          // A screen with a key went back to the one with the same key: the new screen never shows.
-          if (shownId !== node.id) forgetNeverShown(node.id);
-          return shownId;
-        })
+        sendPush(commandId, componentId, node, prepares, wanted, goneOut).then(
+          (shownId) => {
+            // A screen with a key went back to the one with the same key: the new screen never shows.
+            if (shownId !== node.id) forgetNeverShown(node.id);
+            return shownId;
+          },
+          (error: unknown) => {
+            if (rendersAtPress(node)) forgetUnmountedPreview(node.id);
+            throw error;
+          }
+        )
       );
     })
   );
 }
 
+// A preview's React screen with a root of its own renders only once the view is pressed (iOS): one whose preview went
+// before that never mounts. A screen of the one tree mounts with its slot, a native screen has no root.
+function rendersAtPress(node: LayoutNode): boolean {
+  return node.data.options?.preview?.nativeID !== undefined && isReactScreen(node.data.name ?? '');
+}
+
+// A root started at a press that came just before the preview went can reach JavaScript after its push failed: without
+// its props it would render the screen with none. Its notes go after this time, when no root of it has mounted by
+// then; one that has clears them as it unmounts.
+const PREVIEW_FORGET_DELAY = 1000;
+
+function forgetUnmountedPreview(screenId: string): void {
+  if (hasRoot(screenId)) return;
+  setTimeout(() => {
+    if (!hasRoot(screenId)) forgetNeverShown(screenId);
+  }, PREVIEW_FORGET_DELAY);
+}
+
 // Everything a push noted for a screen that never mounts, which an unmount would clear.
 function forgetNeverShown(screenId: string): void {
   forgetProps(screenId);

package/src/engine/screens.tsx

@@ -52,8 +52,15 @@ export type EngineScreen =
 /** What the root of a React screen renders: the screen's id, and the props the command gave it. */
 export type ScreenRootProps = { componentId: string } & Record<string, unknown>;
 
+/**
+ * What React Native gives the root of a React screen: the screen's id, its root tag (none in a slot of the app's one
+ * tree), and the props the native side gives that root, a tab cell's `tabIndex`, `selected`, `badge`, `dot` and
+ * `dotColor`.
+ */
+export type NativeRootProps = { componentId: string; rootTag?: number } & Record<string, unknown>;
+
 const screens = new Map<string, EngineScreen>();
-const roots = new Map<string, ComponentType<{ componentId: string; rootTag?: number }>>();
+const roots = new Map<string, ComponentType<NativeRootProps>>();
 let unmounted: ((screenId: string) => void) | undefined;
 // The React roots mounted under each id, by their root tags. One id can have several: after a JavaScript reload React
 // Native starts the roots of the old screens again in the new runtime, under the ids the new screens get too, and
@@ -62,6 +69,11 @@ let unmounted: ((screenId: string) => void) | undefined;
 // has no tag: while the one tree shows a screen with the id, no root of that id lets it go.
 const owners = new Map<string, Set<number>>();
 
+/** Whether a React root of the screen with the id is mounted now (a slot of the app's one tree doesn't count). */
+export function hasRoot(componentId: string): boolean {
+  return owners.has(componentId);
+}
+
 /** What runs when the root of a screen unmounts: the screen is gone. */
 export function onScreenUnmounted(listener: (screenId: string) => void): void {
   unmounted = listener;
@@ -193,20 +205,29 @@ export function isReactScreen(name: string): boolean {
   return screen !== undefined && 'component' in screen;
 }
 
+/**
+ * The props a screen's component renders with: those a command left under its id ([stored]), the props the native side
+ * gave its root over them ([root]: a tab cell's state, which the docs promise arrives on top of `passProps`), and its
+ * id. The root tag stays with the root.
+ */
+export function screenProps(stored: object, root: NativeRootProps): ScreenRootProps {
+  const props: ScreenRootProps = { ...stored, ...root, componentId: root.componentId };
+  delete props.rootTag;
+  return props;
+}
+
 /**
  * The root a React screen runs in: the screen with the props a command left for it under its id, and the new ones when
- * options give its id new props. React Native gives a root only its id (and its own root props, which stay here); the
- * slot of the app's one tree renders the same root.
+ * options give its id new props, under the props the native side gives the root ([screenProps]). The slot of the app's
+ * one tree renders the same root.
  */
-export function screenRoot(
-  name: string
-): ComponentType<{ componentId: string; rootTag?: number }> | undefined {
+export function screenRoot(name: string): ComponentType<NativeRootProps> | undefined {
   const screen = screens.get(name);
   if (!screen || !('component' in screen)) return undefined;
   let root = roots.get(name);
   if (!root) {
     const Screen = screen.component();
-    root = function ScreenRoot(rootProps: { componentId: string; rootTag?: number }) {
+    root = function ScreenRoot(rootProps: NativeRootProps) {
       // In the app's one tree the slot renders the root, without a tag of its own.
       const { componentId, rootTag } = rootProps;
       const watch = useCallback(
@@ -240,7 +261,7 @@ export function screenRoot(
           unmounted?.(componentId);
         };
       }, [componentId, rootTag]);
-      return <Screen {...props} componentId={componentId} />;
+      return <Screen {...screenProps(props, rootProps)} />;
     };
     root.displayName = `ScreenRoot(${name})`;
     roots.set(name, root);

package/src/interfaces/options/animations.ts

@@ -258,10 +258,12 @@ export type ElementAnimation = AppearingElementAnimation | DisappearingElementAn
  * 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.
+ * element gets its own values back. The element's own `transform` counts: a property that doesn't animate keeps the
+ * element's value, and a missing end is that value (a turn read from −180° to 180°, as React Native draws it). `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. */
@@ -295,9 +297,12 @@ export interface ElementTransition {
  * 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.
+ * proportions and changes its picture within a quarter of the flight. A view turned or scaled by its own `transform` or
+ * by a parent's flies from where it shows, and its angle goes to the other view's along the shorter arc. The angle is
+ * the one React Native draws, from −180° to 180°: `rotate: '270deg'` turns back a quarter, and no pair spins a full
+ * turn. (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 skew and a tilt
+ * (`skewX`, `rotateX`, …) don't fly: the view flies without them and has them again at the end.
  */
 export interface SharedElementTransition {
   /** The `nativeID` of the view on the screen that goes. */

package/src/interfaces/options/bottomTabs.ts

@@ -73,8 +73,10 @@ export interface OptionsBottomTabsAccessoryComponent {
 /**
  * (iOS 26+) The accessory above the tab bar, like the mini player of a music app. The system sizes it (48 points high)
  * and the component fills that size. It is placed above the bar, or beside the bar when the bar is minimized; on an
- * iPad with the bar at the top it sits at the bottom over the full width, always above the bar. The accessory stops
- * together with the tabs. Android has no accessory.
+ * iPad with the bar at the top it sits at the bottom over the full width, always above the bar. A hidden accessory
+ * (`visible: false`, or no name) keeps its React root and its state, and shows again with them. When another accessory
+ * (another `componentId`) shows, the replaced one stops once it has left the window and its state is gone. The last
+ * accessory stops together with the tabs. Android has no accessory.
  */
 export interface OptionsBottomTabsAccessory {
   /**
@@ -155,6 +157,16 @@ export interface OptionsBottomTabs {
    * @default true
    */
   animate?: boolean;
+  /**
+   * How the content changes when another tab is selected on screen, by a press, by back or from code. `'platform'`
+   * does what the platform does: on Android the tab that goes fades out and the new one fades in and grows (Material's
+   * fade through, 300 ms), on iOS the content changes at once. `'none'` changes it at once on both platforms. The
+   * appear events of a switch and `ANN.BottomTabSelected` come at its end, so with `'none'` right away. The tab that is
+   * selected decides: the value of the screen it shows, over its own, the tabs' and the default options. A
+   * `mergeOptions` applies from the next switch. Off screen the content always changes at once.
+   * @default 'platform'
+   */
+  switchAnimation?: 'platform' | 'none';
   /**
    * The tab to select, as an index from 0. It selects once, when the options arrive, at creation (the first tab to
    * show) or in `mergeOptions`; it is not kept. An index out of range selects nothing (or the first tab at creation)
@@ -188,8 +200,9 @@ export interface OptionsBottomTabs {
   drawBehind?: boolean;
   /**
    * The background color of the bar; `null` gives the default one. On Android the default is the surface color of the
-   * Material 3 theme. Before iOS 26 (and with `UIDesignRequiresCompatibility`) the bar is opaque with the color, or
-   * system opaque without it, and a transparent color makes it transparent. On iOS 26 with glass the color is ignored
+   * Material 3 theme. Before iOS 26, and in the compatibility mode (`UIDesignRequiresCompatibility` in Info.plist: iOS 26, and iOS 27
+   * only for an app built with an SDK before iOS 27), the bar is opaque with the color, or system opaque without it,
+   * and a transparent color makes it transparent. On iOS 26 and later with glass the color is ignored
    * with one warning, since the system has no color for glass, while a transparent color gives a transparent bar. The
    * theme color `bar` is its default option.
    */
@@ -396,7 +409,7 @@ export interface OptionsBottomTab {
   selectedFontSize?: number;
   /**
    * (iOS) The insets of the icon. Each side is independent. They apply before iOS 26 only; iOS 26 and the compatibility
-   * mode ignore them, and so does a system role before iOS 18.
+   * mode (see `backgroundColor`) ignore them, and so does a system role before iOS 18.
    */
   iconInsets?: IconInsets;
   /**

package/src/interfaces/options/buttons.ts

@@ -60,7 +60,7 @@ export interface IconInsets {
  * a color the other fields are ignored.
  *
  * On iOS the icon is drawn onto the shape and the button becomes a button of its own (the back button keeps its
- * history menu), without the glass capsule on iOS 26 by default. On Android the icon sits on the shape, mirrored in a
+ * history menu), without the glass capsule (glass design, iOS 26+) by default. On Android the icon sits on the shape, mirrored in a
  * right-to-left layout. Layers merge differently: on iOS an object merges field by field like any other, on Android
  * an `iconBackground` that has a `color` replaces the earlier one as a whole.
  */
@@ -189,7 +189,7 @@ export interface OptionsTopBarButton {
    */
   icon?: ImageResource;
   /**
-   * (iOS) The space around the image of `icon`; the button becomes a button of its own, without a capsule on iOS 26.
+   * (iOS) The space around the image of `icon`; the button becomes a button of its own, without a capsule with the glass design (iOS 26+, see `UIDesignRequiresCompatibility`).
    */
   iconInsets?: IconInsets;
   /**
@@ -238,14 +238,14 @@ export interface OptionsTopBarButton {
   disabledColor?: Color;
   /**
    * A shape behind the icon. It works with an `icon` image and a `color` of the shape; on iOS the button becomes a
-   * button of its own without menu, toggle or style, and without a capsule on iOS 26 by default. The color of a whole
+   * button of its own without menu, toggle or style, and without a capsule with the glass design by default. The color of a whole
    * side is `leftButtonBackgroundColor` / `rightButtonBackgroundColor`.
    */
   iconBackground?: IconBackgroundOptions;
   /**
-   * (iOS) `'plain'` or `'prominent'`, the main action of the bar (Done, Send). On iOS 26 a prominent button is a
+   * (iOS) `'plain'` or `'prominent'`, the main action of the bar (Done, Send). With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) a prominent button is a
    * capsule in the button's tint with bold text or icon on it (the tint is `color`, the bar's tint without it);
-   * before iOS 26 it is the system's done style with bold text. Not for component buttons, buttons with
+   * without it, it is the system's done style with bold text. Not for component buttons, buttons with
    * `iconBackground`, and `showText` buttons.
    * @default 'plain'
    */
@@ -257,7 +257,7 @@ export interface OptionsTopBarButton {
    */
   testID?: string;
   /**
-   * (iOS 26+) Whether the button has no glass capsule under it; neighbors keep theirs. By default `true` for
+   * (iOS 26+, glass design) Whether the button has no glass capsule under it; neighbors keep theirs. By default `true` for
    * component buttons and for icon buttons with a background or insets, `false` for the rest. In a `group` of several
    * buttons the capsule is shared and this has no effect. A change by `mergeOptions` builds the buttons anew.
    */
@@ -270,8 +270,8 @@ export interface OptionsTopBarButton {
    */
   showText?: boolean;
   /**
-   * (iOS 26+) Buttons next to each other with the same group share one capsule; a button without a group has its
-   * own. Before iOS 26 it does nothing, on iOS 15 there are no groups. A side that has a group of several buttons
+   * (iOS 26+, glass design) Buttons next to each other with the same group share one capsule; a button without a group has its
+   * own. Without the glass design it does nothing, on iOS 15 there are no groups. A side that has a group of several buttons
    * doesn't animate button changes. The toolbar has no groups: only icons share a capsule there. For center buttons
    * the group is a section of the overflow menu, and its name is the id the customization is saved under.
    */

package/src/interfaces/options/system.ts

@@ -34,12 +34,15 @@ export interface OptionsLayout {
    * indicator or navigation bar, the camera cutout. `[]` lets the content reach every edge. The array replaces the
    * one from a lower layer. The screen adds the padding itself; `useSafeAreaInsets()` returns what is still covered,
    * which is 0 on an edge the screen keeps and the whole covered size on an edge where the content goes under a bar.
-   * Edges listed here always win, also for a screen with a large title.
+   * Edges listed here win, but the top under a large title: there the list keeps its first rows clear of the bar
+   * itself and scrolls under it, which collapses the title, so a `'top'` listed here counts for nothing.
    *
-   * Without it, on iOS: every edge except those where the content goes under a bar that shows (the top bar, a tab
-   * bar or toolbar at the bottom, the side of a vertical bar); a screen with a large title keeps the top free so its
-   * list can scroll under the bar. On Android: all four edges, except the top under a top bar that hides on scroll
-   * or under a large title, and the bottom under tabs that hide on scroll.
+   * Without it the screen keeps the top and the sides, and its content goes down to the bottom: under the home
+   * indicator or the navigation bar, and under a tab bar or toolbar it goes under. A list keeps its last rows clear
+   * with `useSafeAreaInsets().bottom`. The top is free where the content goes under a top bar: on iOS under a bar
+   * that shows, on Android under a bar that hides on scroll; on both under a large title, so the list scrolls under
+   * the bar. On iOS the side of a vertical bar is free too. To have the screen keep the bottom, list every edge it
+   * keeps: listed edges replace the default.
    */
   safeAreaEdges?: SafeAreaEdge[];
   /**

package/src/interfaces/options/toolbar.ts

@@ -4,7 +4,7 @@ import type { OptionsTopBarButton } from './buttons';
 export interface OptionsToolbarSpace {
   /**
    * `'flexibleSpace'` takes the free width and pushes the next buttons to the far edge; `'fixedSpace'` is a gap of zero
-   * width that starts a new capsule on iOS 26.
+   * width that starts a new capsule with the glass design (iOS 26+).
    */
   systemItem: 'flexibleSpace' | 'fixedSpace';
 }
@@ -36,7 +36,7 @@ export interface OptionsToolbar {
    * The buttons from the leading edge, in the format of the bar buttons: text, icon, SF Symbol, `systemItem`, a
    * component (drawn before the screen shows), `enabled`, `color`, `style`, `menu` (it opens upward), `toggle`,
    * `showText`, `group`; also spaces and the search field. A press sends a button press. The color of a side doesn't
-   * apply to them, and badges are not drawn. On iOS 26 each button has its own capsule, neighbor icons with the same
+   * apply to them, and badges are not drawn. With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) each button has its own capsule, neighbor icons with the same
    * `group` share one (the toolbar has no real groups, so text buttons never share), and a zero-width space is put
    * between neighbors of different groups unless an explicit space is there. The list is replaced as a whole;
    * `mergeOptions` animates it.

package/src/interfaces/options/topBar.ts

@@ -50,7 +50,7 @@ export interface OptionsTopBarTitleDocument {
 export interface OptionsTopBarTitle {
   /**
    * The text of the title. Setting it removes a React title. On iOS it is the title of the screen's navigation item,
-   * the label the system shows on the next screen's back button before iOS 26, and what Rename edits. On Android it
+   * the label the system shows on the next screen's back button without the glass design, and what Rename edits. On Android it
    * is one line cut with an ellipsis, and also the text of the large title; a title component set together with the
    * text drops the text and the subtitle (with a warning in development).
    */
@@ -94,9 +94,9 @@ export interface OptionsTopBarTitle {
    */
   document?: OptionsTopBarTitleDocument;
   /**
-   * (iOS 26+) Puts the title on a Liquid Glass capsule like the buttons: `'regular'` or `'clear'`; `'none'` and any
+   * (iOS 26+, glass design) Puts the title on a Liquid Glass capsule like the buttons: `'regular'` or `'clear'`; `'none'` and any
    * other value mean no capsule. A text title and the subtitle are two lines on the capsule; a component title sits on
-   * it as it is, the capsule taking its size. Before iOS 26 and on Android it does nothing.
+   * it as it is, the capsule taking its size. Without the glass design (see `UIDesignRequiresCompatibility`) and on Android it does nothing.
    */
   glass?: 'regular' | 'clear' | 'none';
   /** (Android) The height of the row of title and buttons, in dp. By default 64, regardless of `topBar.height`. */
@@ -118,15 +118,15 @@ export interface OptionsTopBarTitle {
 /** The subtitle: a second line under the title. */
 export interface OptionsTopBarSubtitle {
   /**
-   * The text of the second line. An empty text removes it. On iOS 26 it is the system subtitle, under the title, the
-   * large title and the collapsed bar, and on the capsule when the title has `glass`; a React title hides it. Before
-   * iOS 26 it makes a two-line title view, only without a large title or a React title. On Android it is the line under
+   * The text of the second line. An empty text removes it. With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) it is the system subtitle, under the title, the
+   * large title and the collapsed bar, and on the capsule when the title has `glass`; a React title hides it. Without
+   * it, it makes a two-line title view, only without a large title or a React title. On Android it is the line under
    * the title, hidden when empty and dropped when the title is a component.
    */
   text?: string;
   /**
-   * The size of the font. On iOS 26 only what is set goes to the system subtitle, and any font option sets the whole
-   * font; before iOS 26 the size is 12. On Android it is in sp, 14 by default.
+   * The size of the font. With the glass design only what is set goes to the system subtitle, and any font option sets the whole
+   * font; without it the size is 12. On Android it is in sp, 14 by default.
    */
   fontSize?: number;
   /** The color of the subtitle. On Android the theme's on-surface-variant color by default. */
@@ -177,14 +177,14 @@ export interface OptionsTopBarBackButton {
    */
   visible?: boolean;
   /**
-   * (iOS) The text of the back button. On iOS 26 the system button without it is an arrow alone, since the title of
-   * the screen below is never shown; before iOS 26 it is that title while it fits. It is set on the screen below, as
+   * (iOS) The text of the back button. With the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) the system button without it is an arrow alone,
+   * since the title of the screen below is never shown; without it, it is that title while it fits. It is set on the screen below, as
    * its back button title.
    */
   title?: string;
   /**
    * (iOS) `true` shows the title of the screen below (or `title`), `false` shows an arrow alone (the minimal mode).
-   * Without it the system decides; on iOS 26 that is the arrow.
+   * Without it the system decides; with the glass design that is the arrow.
    */
   showTitle?: boolean;
   /**
@@ -207,7 +207,7 @@ export interface OptionsTopBarBackButton {
   /**
    * A shape behind the icon, as for a button. It takes effect with a `color` of the shape. On iOS the icon (the
    * chevron by default) is drawn on it and the back button becomes an own button that keeps the history menu unless
-   * `enableMenu` is `false`; without a capsule on iOS 26 by default. On Android the arrow sits on the shape.
+   * `enableMenu` is `false`; without a capsule with the glass design by default. On Android the arrow sits on the shape.
    */
   iconBackground?: IconBackgroundOptions;
   /**
@@ -228,7 +228,7 @@ export interface OptionsTopBarBackButton {
    */
   displayMode?: 'default' | 'generic' | 'minimal';
   /**
-   * (iOS 26+) Whether the Liquid Glass capsule under the back button is hidden. It works only for an own button with
+   * (iOS 26+, glass design) Whether the Liquid Glass capsule under the back button is hidden. It works only for an own button with
    * an `iconBackground`, where the shape is already drawn into the icon; the system button ignores it.
    * @default true
    */
@@ -245,9 +245,9 @@ export interface OptionsTopBarBackButton {
 /** The background of the bar: a color, a component, translucency and blur. */
 export interface OptionsTopBarBackground {
   /**
-   * The color of the bar. On iOS it fills both the standard look and the one at the scroll edge; on iOS 26 the bar is
-   * then solid in this color instead of glass. A transparent color makes a transparent bar. It beats `blur` and
-   * `translucent`. With a large title on iOS 26 the color is drawn into the list under the title, and the collapsed bar
+   * The color of the bar. On iOS it fills both the standard look and the one at the scroll edge; with the glass design the bar is
+   * then solid in this color instead of glass; without it (`UIDesignRequiresCompatibility`) it is the opaque bar of before iOS 26. A transparent color makes a transparent bar. It beats `blur` and
+   * `translucent`. With a large title and the glass design the color is drawn into the list under the title, and the collapsed bar
    * paints itself. On Android it is the background of the bar with the status bar strip, by default the theme's
    * surface color, changing at once on push and pop. Together with `component` the color lies under the component.
    */
@@ -266,8 +266,8 @@ export interface OptionsTopBarBackground {
    */
   component?: OptionsTopBarBackgroundComponent;
   /**
-   * (iOS) Whether content shows through the bar. By default `true` on iOS 26 (glass) and `false` before. With `true`
-   * the bar is glass on iOS 26 and the system translucent bar before; with `false` it is solid in the system color.
+   * (iOS) Whether content shows through the bar. By default `true` with the glass design (iOS 26+, see `UIDesignRequiresCompatibility`) and `false` without it. With `true`
+   * the bar is glass with the glass design and the system translucent bar without it; with `false` it is solid in the system color.
    * `color` and `blur` beat it. Only an explicit `true` puts the screen under the bar.
    */
   translucent?: boolean;
@@ -301,7 +301,7 @@ export interface OptionsTopBarBackgroundComponent {
 export interface OptionsTopBarScrollEdgeAppearanceTitle {
   /** The size of the font, handled like `topBar.title.fontSize`. */
   fontSize?: number;
-  /** The color of the title at the edge. On iOS 26 it is fixed during a push, like the usual title color. */
+  /** The color of the title at the edge. With the glass design it is fixed during a push, like the usual title color. */
   color?: Color;
   /** The font family, handled like `topBar.title.fontFamily`. */
   fontFamily?: FontFamily;
@@ -327,7 +327,7 @@ export interface OptionsTopBarScrollEdgeAppearanceBackground {
 
 /**
  * (iOS) How the bar looks while the list is at its top edge. Without `active` the edge looks as the usual bar, except
- * for the transparency under a large title on iOS 26; the title and the border at the edge still come from the fields
+ * for the transparency under a large title with the glass design; the title and the border at the edge still come from the fields
  * here or from the usual ones. Android doesn't read it.
  */
 export interface OptionsTopBarScrollEdgeAppearance {
@@ -337,7 +337,7 @@ export interface OptionsTopBarScrollEdgeAppearance {
   background?: OptionsTopBarScrollEdgeAppearanceBackground;
   /**
    * Whether the bar has a background of its own at the edge (`background`). With it the edge isn't made transparent
-   * under a large title, and on iOS 26 an opaque color covers the large title. A change by `mergeOptions` applies at
+   * under a large title, and with the glass design an opaque color covers the large title. A change by `mergeOptions` applies at
    * once.
    * @default false
    */
@@ -373,7 +373,7 @@ export interface OptionsTopBarLargeTitle {
    * Whether the large title collapses into the bar as the list scrolls. With `false` on iOS the bar follows an empty
    * scroll view instead of the list, so the title stays as at the top of the list; under the row it then needs a
    * background (`background.color`, else a system blur), and `searchBar.hideOnScroll` doesn't work. On Android `false`
-   * leaves the bar as it is and stops listening to the list. On iOS 26 in a right-to-left layout nothing collapses.
+   * leaves the bar as it is and stops listening to the list. With the glass design in a right-to-left layout nothing collapses.
    * @default true
    */
   collapseOnScroll?: boolean;
@@ -637,7 +637,7 @@ export interface OptionsTopBar {
   /**
    * The shape color behind the icons of the left buttons that have an `icon` image and no `iconBackground.color`; the
    * size and corners come from the button's `iconBackground`, or the icon's size without corners. On iOS only image
-   * buttons, not SF Symbols, and without a capsule on iOS 26. A color sent by `mergeOptions` repaints all the side's
+   * buttons, not SF Symbols, and without a capsule with the glass design. A color sent by `mergeOptions` repaints all the side's
    * image buttons, those with their own shape color too.
    */
   leftButtonBackgroundColor?: Color;
@@ -815,12 +815,15 @@ export interface OptionsScrollEdge {
 
 /**
  * (iOS 26+) The scroll edge effect of the scroll views of a screen: how the content fades or blurs where it scrolls
- * under a bar. The scroll views draw it, and only where content goes under a bar. It applies to every scroll view in
- * the view of the screen when the screen appears; after React mounts it applies to the main list of the screen only; on
- * `mergeOptions` all is reset and applied again. Other scroll views mounted later get it at the next appearance or
- * `mergeOptions`. When the screen leaves, its scroll views get the system effect back. Under a bar with
- * `background.color` or `background.component` there is no effect at the top unless the screen sets one for the top or
- * for all edges. Before iOS 26 and on Android it does nothing.
+ * under a bar. The scroll views draw it, and only where content goes under a bar. When the screen appears, it applies
+ * to the vertical lists and text views (a multi-line `TextInput`) in the view of the screen, except in hidden views
+ * (`display: none`). A list inside another vertical list gets none (UIKit draws no edge effect there); a scroll view
+ * that doesn't scroll vertically, like a pager, is searched for its lists. A list nested very deep in the screen's
+ * views may not get it. After React mounts, the main list of the screen gets it; a list mounted later gets it at the
+ * next appearance, or at a `mergeOptions` of `scrollEdgeEffect` or of the bar's background. The lists get the system
+ * effect back when the screen leaves or is destroyed, and a list React removes from the screen gets it back too. Under
+ * a bar with `background.color` or `background.component` there is no effect at the top unless the screen sets one for
+ * the top or for all edges. Before iOS 26 and on Android it does nothing.
  */
 export interface OptionsScrollEdgeEffect {
   /** Whether the effect is hidden on all four edges. The value of an edge beats it. */

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

@@ -1,42 +0,0 @@
-package dev.apexnative.navigation.react
-
-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
-
-/**
- * The state of each screen of a pair (`useArrangement`): which screen of the pair it is, how the pair lies, whether it
- * lies over the other one and whether it is out of the window. Set on the main thread as the pair lays out; JavaScript
- * reads it from its own thread for a screen's first render, and gets every change as `ANN.ArrangementChanged`. A
- * screen outside a pair has none.
- */
-internal object ArrangementStates {
-    data class State(val placement: String, val layout: String, val front: Boolean, val hidden: Boolean)
-
-    private val states = ConcurrentHashMap<String, State>()
-
-    /**
-     * Keeps the screen's state, and tells JavaScript when it changed and [notify] holds, through [emitter], the one of
-     * the JavaScript the screen was made for: silent once it went. Main thread only.
-     */
-    fun set(screenId: String, state: State, notify: Boolean, emitter: EventEmitter) {
-        if (states.put(screenId, state) == state || !notify) return
-        emitter.emitArrangementChanged(screenId, toMap(state))
-    }
-
-    /** `{ placement, layout, front, hidden }`, empty for a screen outside a pair. Any thread. */
-    fun get(screenId: String): WritableMap = states[screenId]?.let(::toMap) ?: Arguments.createMap()
-
-    fun remove(screenId: String) {
-        states.remove(screenId)
-    }
-
-    private fun toMap(state: State): WritableMap = Arguments.createMap().apply {
-        putString(EventContract.ArrangementChanged.PLACEMENT, state.placement)
-        putString(EventContract.ArrangementChanged.LAYOUT, state.layout)
-        putBoolean(EventContract.ArrangementChanged.FRONT, state.front)
-        putBoolean(EventContract.ArrangementChanged.HIDDEN, state.hidden)
-    }
-}