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

package/ios/Animations/Interpolators/ANNViewTracks.mm

@@ -0,0 +1,261 @@
+#import "ANNViewTracks.h"
+#import "ANNAnimationPropertyOptions.h"
+#import "ANNElementTransitionOptions.h"
+#import "ANNTrack.h"
+#import "ANNUtils.h"
+#import "ANNViewAnimationOptions.h"
+#import <QuartzCore/QuartzCore.h>
+
+CGFloat ANNCameraDistance(void) {
+    CGFloat scale = ANNUtils.mainScreen.scale;
+    if (scale <= 0) {
+        scale = 1;
+    }
+    return 1280.0 / (scale * sqrt(5.0));
+}
+
+// The properties of a side, in the order of `animatedProperties`.
+typedef NS_ENUM(NSInteger, ANNViewProperty) {
+    ANNViewPropertyX,
+    ANNViewPropertyY,
+    ANNViewPropertyTranslationX,
+    ANNViewPropertyTranslationY,
+    ANNViewPropertyAlpha,
+    ANNViewPropertyScaleX,
+    ANNViewPropertyScaleY,
+    ANNViewPropertyRotationX,
+    ANNViewPropertyRotationY,
+    ANNViewPropertyRotation,
+    ANNViewPropertyCount,
+};
+
+static CGFloat ANNRadians(double degrees) {
+    return (CGFloat)(degrees * M_PI / 180.0);
+}
+
+// The rotations as React Native's transforms make them (its matrices, row by row as `CATransform3D`): the same picture
+// as Android's `rotationX`, `rotationY`, `rotation` with the same degrees.
+static CATransform3D ANNRotationX(CGFloat radians) {
+    CATransform3D t = CATransform3DIdentity;
+    t.m22 = cos(radians);
+    t.m23 = sin(radians);
+    t.m32 = -sin(radians);
+    t.m33 = cos(radians);
+    return t;
+}
+
+static CATransform3D ANNRotationY(CGFloat radians) {
+    CATransform3D t = CATransform3DIdentity;
+    t.m11 = cos(radians);
+    t.m13 = -sin(radians);
+    t.m31 = sin(radians);
+    t.m33 = cos(radians);
+    return t;
+}
+
+static CATransform3D ANNRotationZ(CGFloat radians) {
+    CATransform3D t = CATransform3DIdentity;
+    t.m11 = cos(radians);
+    t.m12 = sin(radians);
+    t.m21 = -sin(radians);
+    t.m22 = cos(radians);
+    return t;
+}
+
+// A track of one property, or nil when it doesn't play (neither `from` nor `to`): the missing end is the view's value.
+static ANNTrack *ANNTrackOf(Double *from, Double *to, Double *duration, Double *delay,
+                            ANNInterpolationOptions *interpolation, double viewValue) {
+    if (!from.hasValue && !to.hasValue) {
+        return nil;
+    }
+    return [ANNTrack trackFrom:from.hasValue ? [from get] : viewValue
+                            to:to.hasValue ? [to get] : viewValue
+                durationMillis:duration
+                   delayMillis:delay
+                 interpolation:interpolation];
+}
+
+@implementation ANNViewTracks {
+    ANNTrack *_tracks[ANNViewPropertyCount];
+    // The view's place in its parent when the tracks were made (`x₀`, `y₀`).
+    CGPoint _origin;
+    CGFloat _alphaBefore;
+    CATransform3D _transformBefore;
+    BOOL _animatesTransform;
+    BOOL _tilts;
+    BOOL _wroteAlpha;
+    BOOL _wroteTransform;
+    BOOL _restored;
+    NSTimeInterval _endTime;
+}
+
+- (instancetype)initWithView:(UIView *)view
+                        side:(ANNViewAnimationOptions *)side
+                 alphaBefore:(CGFloat)alphaBefore {
+    if (self = [self initWithView:view alphaBefore:alphaBefore]) {
+        NSArray<ANNAnimationPropertyOptions *> *properties = side.animatedProperties;
+        NSInteger count = MIN((NSInteger)ANNViewPropertyCount, (NSInteger)properties.count);
+        for (NSInteger index = 0; index < count; index++) {
+            ANNAnimationPropertyOptions *property = properties[index];
+            _tracks[index] = ANNTrackOf(property.from, property.to, property.duration,
+                                        property.startDelay, property.interpolation,
+                                        [self viewValueOf:(ANNViewProperty)index]);
+        }
+        [self tracksMade];
+    }
+    return self;
+}
+
+- (instancetype)initWithView:(UIView *)view element:(ANNElementTransitionOptions *)element {
+    if (self = [self initWithView:view alphaBefore:view.alpha]) {
+        NSArray<ANNElementAnimationOptions *> *properties = element.animatedProperties;
+        NSInteger count = MIN((NSInteger)ANNViewPropertyCount, (NSInteger)properties.count);
+        for (NSInteger index = 0; index < count; index++) {
+            ANNElementAnimationOptions *property = properties[index];
+            _tracks[index] = ANNTrackOf(property.from, property.to, property.duration,
+                                        property.startDelay, property.interpolation,
+                                        [self viewValueOf:(ANNViewProperty)index]);
+        }
+        [self tracksMade];
+    }
+    return self;
+}
+
+- (instancetype)initWithView:(UIView *)view
+                    fadeFrom:(CGFloat)from
+                          to:(CGFloat)to
+                    duration:(NSTimeInterval)duration
+                 alphaBefore:(CGFloat)alphaBefore {
+    if (self = [self initWithView:view alphaBefore:alphaBefore]) {
+        _tracks[ANNViewPropertyAlpha] = [[ANNTrack alloc] initWithFrom:from
+                                                                    to:to
+                                                              duration:duration
+                                                                 delay:0
+                                                                 curve:[ANNCurve linear]];
+        [self tracksMade];
+    }
+    return self;
+}
+
+- (instancetype)initWithView:(UIView *)view alphaBefore:(CGFloat)alphaBefore {
+    if (self = [super init]) {
+        _view = view;
+        CALayer *layer = view.layer;
+        CGRect bounds = layer.bounds;
+        _origin = CGPointMake(layer.position.x - bounds.size.width * layer.anchorPoint.x,
+                              layer.position.y - bounds.size.height * layer.anchorPoint.y);
+        _alphaBefore = alphaBefore;
+        _transformBefore = layer.transform;
+    }
+    return self;
+}
+
+- (double)viewValueOf:(ANNViewProperty)property {
+    switch (property) {
+        case ANNViewPropertyX:
+            return _origin.x;
+        case ANNViewPropertyY:
+            return _origin.y;
+        case ANNViewPropertyAlpha:
+            return _alphaBefore;
+        case ANNViewPropertyScaleX:
+        case ANNViewPropertyScaleY:
+            return 1;
+        default:
+            return 0;
+    }
+}
+
+- (void)tracksMade {
+    _endTime = 0;
+    for (NSInteger index = 0; index < ANNViewPropertyCount; index++) {
+        ANNTrack *track = _tracks[index];
+        if (!track) {
+            continue;
+        }
+        _endTime = MAX(_endTime, track.endTime);
+        if (index != ANNViewPropertyAlpha) {
+            _animatesTransform = YES;
+        }
+    }
+    _tilts = _tracks[ANNViewPropertyRotationX] || _tracks[ANNViewPropertyRotationY];
+}
+
+- (BOOL)hasTracks {
+    return _animatesTransform || self.animatesAlpha;
+}
+
+- (BOOL)animatesAlpha {
+    return _tracks[ANNViewPropertyAlpha] != nil;
+}
+
+- (NSTimeInterval)endTime {
+    return _endTime;
+}
+
+- (double)valueOf:(ANNViewProperty)property at:(NSTimeInterval)time {
+    ANNTrack *track = _tracks[property];
+    return track ? [track valueAt:time] : [self viewValueOf:property];
+}
+
+- (void)applyAtTime:(NSTimeInterval)time {
+    if (_restored) {
+        return;
+    }
+    if (self.animatesAlpha) {
+        _view.alpha = (CGFloat)[_tracks[ANNViewPropertyAlpha] valueAt:time];
+        _wroteAlpha = YES;
+    }
+    if (!_animatesTransform) {
+        return;
+    }
+    CGFloat scaleX = (CGFloat)[self valueOf:ANNViewPropertyScaleX at:time];
+    CGFloat scaleY = (CGFloat)[self valueOf:ANNViewPropertyScaleY at:time];
+    // The translation wins over the place when a side has both.
+    CGFloat translationX =
+        _tracks[ANNViewPropertyTranslationX] || !_tracks[ANNViewPropertyX]
+            ? (CGFloat)[self valueOf:ANNViewPropertyTranslationX at:time]
+            : (CGFloat)([self valueOf:ANNViewPropertyX at:time] - _origin.x);
+    CGFloat translationY =
+        _tracks[ANNViewPropertyTranslationY] || !_tracks[ANNViewPropertyY]
+            ? (CGFloat)[self valueOf:ANNViewPropertyTranslationY at:time]
+            : (CGFloat)([self valueOf:ANNViewPropertyY at:time] - _origin.y);
+    // `CATransform3D` multiplies row vectors: each step below comes after the ones before it.
+    CATransform3D transform = CATransform3DMakeScale(scaleX, scaleY, 1);
+    if (_tracks[ANNViewPropertyRotationX]) {
+        CGFloat radians = ANNRadians([self valueOf:ANNViewPropertyRotationX at:time]);
+        transform = CATransform3DConcat(transform, ANNRotationX(radians));
+    }
+    if (_tracks[ANNViewPropertyRotationY]) {
+        CGFloat radians = ANNRadians([self valueOf:ANNViewPropertyRotationY at:time]);
+        transform = CATransform3DConcat(transform, ANNRotationY(radians));
+    }
+    if (_tracks[ANNViewPropertyRotation]) {
+        CGFloat radians = ANNRadians([self valueOf:ANNViewPropertyRotation at:time]);
+        transform = CATransform3DConcat(transform, ANNRotationZ(radians));
+    }
+    if (_tilts) {
+        CATransform3D perspective = CATransform3DIdentity;
+        perspective.m34 = -1.0 / ANNCameraDistance();
+        transform = CATransform3DConcat(transform, perspective);
+    }
+    transform = CATransform3DConcat(transform,
+                                    CATransform3DMakeTranslation(translationX, translationY, 0));
+    _view.layer.transform = transform;
+    _wroteTransform = YES;
+}
+
+- (void)restore {
+    if (_restored) {
+        return;
+    }
+    _restored = YES;
+    if (_wroteAlpha) {
+        _view.alpha = _alphaBefore;
+    }
+    if (_wroteTransform) {
+        _view.layer.transform = _transformBefore;
+    }
+}
+
+@end

package/ios/ApexNavigation-prefix.h

@@ -0,0 +1,6 @@
+// Included before every source file in the SwiftPM build (ios/Package.swift), as CocoaPods' generated prefix header
+// is: some sources use Foundation and UIKit without importing them.
+#ifdef __OBJC__
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+#endif

package/ios/CLAUDE.md

@@ -0,0 +1,151 @@
+# iOS core
+
+## What is here
+
+The iOS side of the navigation: Objective-C++, the pod and SwiftPM target `ApexNavigation`, class prefix `ANN`, log
+prefix `[ApexNavigation]`. iOS 15.1 and later, iPhone and iPad; React Native 0.85 and later
+with the New Architecture only (Fabric, bridgeless). Newer-OS features sit behind `@available` and, for names of an
+SDK newer than the one the app builds with, `#if __IPHONE_OS_VERSION_MAX_ALLOWED >= …` (the pair needs the iOS 27.1
+SDK). The native side owns the navigation: stacks, tabs, modals, overlays, side menus, split views and pairs are UIKit
+view controllers that JS builds from a layout and drives with commands. The options, layouts, commands and events are
+the contract of the types in `src/interfaces/`; this folder implements it.
+Swift is not used here: apps reach the core through the public headers (`Public/ApexNavigation/`).
+
+## Folders
+
+- `TurboModules/`: `ANNTurboModule` (the commands and the sync getters), `ANNTurboEventEmitter` (the events module).
+- `Contract/`: The command path: runner, answer, layout reader and nodes, validator, error texts, tree options.
+- `Core/`: The spine: node protocol and helper, registry, dispatcher, state, render wait, parking, system UI, reload, event emitter, start (`ApexNavigation.mm`, `ANNAppDelegate.mm`), and the modules `ANNKeyCommands`, `ANNDeepLinkQueue`, `ANNHinge`, `ANNSceneDelegate.mm`.
+- `Layouts/Root/`: `ANNRootCoordinator` (`setRoot`), `ANNLayoutFactory`, `ANNSplashViewController`.
+- `Layouts/Screen/`: The screen (`ANNComponentViewController`), its presenter, readiness, insets, regions, safe-area math, the main list rule, previews.
+- `Layouts/External/`: Native screens: `ANNExternalViewController`, `ANNNativeScreenCalls`.
+- `Layouts/Stack/`: `ANNStackController`, `ANNStackQueue`, `ANNStackCommands`, `ANNStackPresenter`, `ANNPreviewPush`, the swipe-back delegate.
+- `Layouts/Tabs/`: `ANNBottomTabsController`, its presenter, item builder, custom row, preload window, More delegate, long press, dots.
+- `Layouts/Modal/`: `ANNModalCoordinator`, `ANNModal`, `ANNPresentationGate`, `ANNModalPresentation`, `ANNModalTransitions`, sheets and popovers.
+- `Layouts/Overlay/`: `ANNOverlayCoordinator`, `ANNOverlayWindow`.
+- `Layouts/SideMenu/`: The side menu module and its presenter and wrapper.
+- `Layouts/SplitView/`: The split view module, plus the core's `ANNSplitViewPresenter` and `ANNSplitViewCommands`.
+- `Layouts/Arrangement/`: The pair (iOS 27.1): `ANNArrangementViewController`, `ANNArrangementState`.
+- `TopBar/`: The bar of a screen: title, buttons, back button, large title, appearance, search, toolbar, edge effects.
+- `Options/`, `Options/Params`: One `ANN<Group>Options` class per group, the field table, the value kinds and parsers (`Bool`, `Color`, `Text`, `Image`, …).
+- `Animations/`: The custom transition engine: plan, animator, wait, frame driver, rules; `Elements/` and `Interpolators/`.
+- `React/`, `React/Slots/`: React views of screens and components, the surface host, the safe area view, the slot host and slot screens.
+- `Public/ApexNavigation/`: The headers apps import: `ApexNavigation.h`, `ANNAppDelegate.h`, `ANNSceneDelegate.h`.
+- `Utils/`: Two small categories: `UIColor+ANNLuminance`, `UIView+Utils`.
+- `cpp/`: The C++ of the Fabric components `ANNSlot` and `ANNSafeAreaView` (props, state, shadow nodes, descriptors). Android builds the same files.
+
+Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder whose headers are imported by bare name),
+`ApexNavigation-prefix.h` (SwiftPM only). The pod is `ApexNavigation.podspec` at the repository root.
+
+## Where to look
+
+- Launch, the app-facing API — `Public/ApexNavigation/`; `Core/`: `ApexNavigation.mm`, `ANNAppDelegate.mm`, `ANNSceneDelegate.mm`, `ApexNavigation+Internal.h`
+- Root, splash, reload — `Layouts/Root/`: `ANNRootCoordinator`, `ANNSplashViewController`; `Core/`: `ANNReloadCoordinator`
+- Screen: React root, slot, native screen — `Layouts/Screen/`: `ANNComponentViewController`; `React/`: `ANNReactView`, `ANNReactViewCreator`, `Slots/`; `Layouts/External/`
+- Screen: insets, background, keyboard focus — `Layouts/Screen/`: `ANNScreenInsets`, `ANNScreenSafeArea`, `ANNScreenBars`, `ANNComponentPresenter` (background, status bar blur), `ANNComponentViewController` (key commands)
+- Safe area view — `React/`: `ANNSafeAreaViewComponentView`; `Layouts/Screen/`: `ANNScreenReadiness`; `cpp/`
+- Stack: queue, commands, back, gestures — `Layouts/Stack/`: `ANNStackQueue`, `ANNStackCommands`, `ANNStackController`, `InteractivePopGestureDelegate`, `ANNStackAnimatingDelegate`
+- Top bar: title, buttons, menus, large title — `TopBar/`: `ANNTopBarPresenter`, `ANNBarButtons`, `ANNBarAppearance`, `ANNLargeTitlePresenter`, `ANNBackButtonPresenter`, `ANNTitleView`, `ANNTitleGlassView`
+- Top bar: components, waits — `TopBar/`: `ANNBarComponentsWait`, `ANNBarBackgroundComponent`, `ANNTitleComponentView`, `ANNBarButtonComponentView`; `React/`: `ANNReactComponentRegistry`
+- Search — `TopBar/`: `ANNSearchPresenter`, `ANNSearchResultsViewController`
+- Toolbar — `TopBar/`: `ANNToolbarPresenter`; `Options/`: `ANNToolbarOptions`; `Layouts/Stack/`: `ANNStackPresenter`
+- Tabs — `Layouts/Tabs/`: `ANNBottomTabsController`, `ANNBottomTabsPresenter`, `ANNBottomTabItemBuilder`, `ANNBottomTabsCustomRow`
+- Modals, sheets, popovers — `Layouts/Modal/`
+- Overlays — `Layouts/Overlay/`
+- Side menu — `Layouts/SideMenu/`
+- Split view — `Layouts/SplitView/`
+- Pair (arrangement) — `Layouts/Arrangement/`
+- Preview — `Layouts/Stack/`: `ANNPreviewPush`; `Layouts/Screen/`: `ANNPreviewInteraction`
+- Animations, transitions — `Animations/` (plan and animator at the top; `Elements/` for shared elements and zoom; `Interpolators/` for curves and tracks)
+- System bars, orientation, direction — `Core/`: `ANNSystemUI`, `ANNSystemUIRules`, `ANNAppDirection`, `ANNNodePresenter` (the answers to UIKit)
+- Events and state — `Core/`: `ANNEventEmitter`, `ANNAppearanceDispatcher`, `ANNScreenAppearance`, `ANNNavigationState`; `TurboModules/`: `ANNTurboEventEmitter`
+- Options: parsing, merging, defaults — `Options/`: `ANNOptions`, `ANNOptionField`, `ANNOptionsReader`, `ANNDefaultOptions`, `ANNOptionsCache`; `Core/`: `ANNOptionsRepaint`
+- Error texts — `Contract/`: `ANNErrorTexts`; `Core/`: `ANNErrorHandler`
+- Links — `Core/`: `ANNDeepLinkQueue`; the `getLaunchLink` method of `ANNTurboModule`
+- Key commands — `Core/`: `ANNKeyCommands`; `Layouts/Screen/`: `ANNComponentViewController`
+- Hinge, regions — `Core/`: `ANNHinge`; `Layouts/Screen/`: `ANNScreenRegions`; `Layouts/Arrangement/`: `ANNArrangementState`
+- Native screens — `Layouts/External/`: `ANNExternalViewController`, `ANNNativeScreenCalls`; `Layouts/Screen/ANNNativeScreenContext.mm`
+- Slots — `React/Slots/`: `ANNSlotHost`, `ANNSlotContainers`, `ANNSlotScreenView`, `ANNSlotComponentView`; `cpp/`
+
+## Threads
+
+- **Module queue:** the layout check (`ANNLayoutReader`) and the sync getters. The check reads only stores safe from
+  any thread (`ApexNavigation hasNativeScreenNamed:`, `ANNArrangementState canShowArrangements`).
+- **Main queue:** everything else. A command body starts with `ANNAssertMainQueue()`. The options of a layout are parsed
+  here (`ANNLayoutTreeOptions`, images load while they are read). `ANNEventEmitter` moves an event from another queue
+  to the main queue.
+- **Sync getters** answer JS during a screen's first render: `getScreenInsets`, `getScreenRegions`,
+  `getArrangementState`, `getHinge`, `getStartInfo`. They read `ANNScreenInsets`, `ANNScreenRegions`,
+  `ANNArrangementState`, `ANNHinge lastValue`, written on the main queue and guarded by `@synchronized`.
+  `ANNReloadCoordinator.generation` and `ANNEventEmitter.isCurrent` are readable from any thread.
+
+## Checks
+
+- `scripts/build-ios.sh`: 0 warnings in `ios/` (warnings fail it). It builds the Showcase for the simulator.
+- A new file needs `scripts/pods.sh` first (CocoaPods globs `ios/**`). A new folder also goes into `headerFolders` of
+  `Package.swift`, because files import each other's headers by bare name.
+- There is no iOS unit-test target. `ANNSystemUIRulesSelfCheck` and `ANNCheckOptionClassesFrom` run once in DEBUG; the
+  rest is checked by the Showcase scenarios.
+- Format by hand: `.claude/rules/code-objc.md`.
+
+## Pitfalls
+
+- Native code never touches React Native's views (their subviews, their layout, their frames): Fabric owns and recycles
+  them. Read them; what a transition writes (`alpha`, `transform`, a hidden flag) goes back on every path.
+- Every change of a stack's children goes through its `ANNStackQueue`. The core's own calls to UIKit's navigation
+  come only from there; UIKit's own pops are followed (`uikitShows:`), not fought.
+- Every UIKit present and dismiss in the main window is a step in `ANNPresentationGate`. UIKit drops a transition
+  asked for while another runs, and never calls its completion.
+- Only `ANNAppearanceDispatcher` sends the appearance events. A screen's UIKit callbacks and a command's own calls
+  both reach it; whichever comes second finds the phase set. While a command drives a node, UIKit's callbacks send
+  nothing.
+- Touching `view` of a screen loads it, and `viewDidLoad` renders it. Use `isViewLoaded` or `viewIfLoaded` where a
+  render is not wanted (a parked or pending node).
+- Own options and the defaults are never changed in place. Resolved options are cached and read-only: copy before
+  changing.
+- Take a node's parent with `layoutParent`, not `parentViewController`: UIKit moves screens (More, a split view's
+  columns, a pair's screen out of the window).
+- A block that runs later keeps the emitter and the generation it was made with. After a reload the answer and the
+  events of the old JavaScript are silent; a node never asks `ApexNavigation.eventEmitter` at event time.
+- A wait sets its ready handler under a key of its own (`setReadyHandler:forKey:`) and removes only that one. A wait is
+  about `waitedComponentViewControllers`, not about the shown screens.
+- A container that changes what it shows calls `+[ANNShownScreens changedIn:]` and nothing else of its own choice.
+  A change UIKit makes by itself (a collapsed split view's back) is followed from the revealed screen's
+  `descendantDidAppear:`.
+- Hold and release of the navigation state come in pairs; a `setRoot` chain with layout modals or overlays holds it
+  until its answer.
+- Use an `@available` check for newer OS APIs, and `#if __IPHONE_OS_VERSION_MAX_ALLOWED >= …` for names of a newer SDK.
+- React Native hears of the app's light or dark style only from its hosting views in the window. A view that stands in
+  for one (`ANNSlotScreenView`, the screens of one tree) posts the trait change itself, with the window filter of
+  `ANNSurfaceHostingView`; without it `useColorScheme` keeps the old theme.
+- A step that runs later in a command (a ready handler, a timer, a transition's end) goes through the owner's guard
+  (`protect:step:`), so an exception rejects the command instead of crashing the app. So does the start of a wait
+  (the root, a modal, an overlay: their record is listed and parked by then), and the modal's end steps inside UIKit's
+  completions and delegate calls (`protectEndOf:showing:step:`, `protectBatch:step:`); the overlay's guard is
+  `protectWaitOf:step:`.
+- On iOS 26 UIKit draws a screen's large title, for a whole pop or swipe back, inside the scroll view the bar follows
+  for the top edge: a detached scroll view or a list below the bar hides it. `ANNLargeTitlePresenter` lays its title
+  host over the screen's view for the transition and fills the band behind the title from the screen's top
+  (`ANNStackController` `popReveals:leaving:on:`); keep both when changing the edge scroll view or the bar's look.
+- Under a hidden bar UIKit's swipe delegate refuses the swipes in questions of its own: `InteractivePopGestureDelegate`
+  stops passing those on while the bar is hidden (`barHidden`, set again on the recognizer at each change, from
+  `swipeBackFollowsBar`), and the core sorts the pans itself.
+- UIKit works out the safe area of the window's root view from where it is drawn: a `transform` that moves it (a
+  root's own `enter`) leaves it with no top inset, and putting the transform back doesn't work it out again. Lay the
+  root out after a restore (`+[ANNRootCoordinator stopAnimationOf:]`).
+- UIKit's `hidesBarsWhenKeyboardAppears`, once on, keeps hiding the bar after it is set back to `NO`: the stack hides
+  the bars for `topBar.hideOnKeyboard` itself (`keyboardWillShow:` / `keyboardDidHide:` of `ANNStackController`) and
+  leaves the flag off.
+- A container that stands in a stack or a tab where a screen can (a pair, a split view, a side menu) sets
+  `extendedLayoutIncludesOpaqueBars`, as a screen does: otherwise UIKit takes an opaque bar's height off its view, and
+  a tab bar in iPhone Duo's vertical strip is as tall as the window, so the container gets no height.
+- A tab opened from More shows its screens on UIKit's More navigation: the swipe delegates
+  (`installSwipeBackDelegatesOn:`), the keyboard's bar (`keyboardDidHide:`) and the direction
+  (`navigationMissedSceneDirection:`) go there too; read `shownNavigationController`, not the stack itself.
+
+## Read when needed
+
+- `ios/CORE.md`: the layers, how a command flows, the single places that own one rule each, the modules. Read it when
+  you change the core's structure, add a module or trace a flow.
+- `ios/RECIPES.md`: the steps for adding an option and for adding a command. Read it when you do exactly that.
+- `ARCHITECTURE.md` (repository root): the design both platforms follow.

package/ios/CORE.md

@@ -0,0 +1,177 @@
+# iOS core: structure
+
+The structure of the iOS core: its layers, the path of a command through them, the single places that own one
+rule, and how modules plug in. Read it when you change the core, add a module or trace a flow; the map of folders
+and files is `ios/CLAUDE.md`.
+
+## Layers
+
+```
+JS ── ANNTurboModule (codegen ApexNavigationSpec) ────────────────────────────────────────────┐ sync getters
+       │ module queue                                                                          │ read stores
+       ▼                                                                                       ▼ (@synchronized)
+  ANNCommandRunner ── ANNLayoutReader (check the whole layout) ── ANNErrorTexts ── ANNErrorHandler
+       │ one task per command on the main queue, in call order
+       ▼
+  area command (ANNStackCommands, ANNRootCoordinator, ANNModalCoordinator, ANNOverlayCoordinator, ANNSplitViewCommands)
+       │ ANNLayoutValidator · ANNLayoutTreeOptions · ANNLayoutFactory ── ANNNodeRegistry
+       ▼
+  nodes: ANNComponentViewController · ANNExternalViewController · ANNStackController · ANNBottomTabsController ·
+         ANNSideMenuViewController · ANNSplitViewController · ANNArrangementViewController   (ANNLayoutProtocol)
+       │ options: ANNOptionsReader → ANNNavigationOptions; ANNNodeHelper resolves and caches (ANNOptionsCache)
+       ▼
+  coordinators: ANNRootCoordinator · ANNStackQueue (per stack) · ANNModalCoordinator + ANNPresentationGate ·
+                ANNOverlayCoordinator · ANNRenderWait · ANNPendingLayers · ANNParking
+       ▼
+  presenters: ANNComponentPresenter · ANNTopBarPresenter · ANNStackPresenter · ANNBottomTabsPresenter ·
+              ANNSideMenuPresenter · ANNSplitViewPresenter · ANNTransitionPlan/ANNTransitionAnimator · ANNSystemUI
+       ▼
+  ANNAppearanceDispatcher → ANNNavigationState → ANNCommandAnswer ─ ANNEventEmitter → ANNTurboEventEmitter ─► ANN.* events
+```
+
+One line per layer. Each layer calls the next one down, and the answer and the events come back up through the
+dispatcher.
+
+- **Way in** (`ANNTurboModule`): the codegen methods. An async method hands its work to `ANNCommandRunner`; a sync
+  getter reads a store and never touches the main queue.
+- **Layout check** (`ANNLayoutReader`, `ANNLayoutNode`): reads the JSON into immutable nodes and checks the whole
+  tree before any view exists. The first error is the rejection text.
+- **Command runner** (`ANNCommandRunner`, `ANNCommandAnswer`): takes the generation of the JavaScript, runs the check on
+  the module queue, then runs the body on the main queue inside an exception guard. The answer resolves or rejects once.
+- **Registry and factory** (`ANNNodeRegistry`, `ANNLayoutFactory`): the factory turns a checked tree into view
+  controllers and registers every node by id.
+- **Nodes** (`ANNLayoutProtocol`, `UIViewController+LayoutProtocol`, `ANNNodeHelper`): the view controllers. Each holds
+  its layout data and its own options; the helper does the common work.
+- **Options** (`Options/`): a typed tree per node. Parsed once, merged by one rule, resolved as own + parents +
+  defaults, cached until `ANNOptionsCache` moves.
+- **Coordinators**: the rules of one area. They own queues, waits and records, never views of React Native.
+- **Presenters**: apply the resolved options to UIKit (bars, tabs, sheets, transitions, the system UI). They read
+  options and write UIKit state; they send no appearance event.
+- **Appearance dispatcher** (`ANNAppearanceDispatcher`): the only sender of the appearance events; it also ends a
+  transition in the fixed order and resolves the command's answer.
+- **Event emitter** (`ANNEventEmitter`, `ANNTurboEventEmitter`): sends `ANN.<Name>` to JS on the main queue, and drops
+  events of a JavaScript that went.
+
+## How a command flows
+
+`navigation.push('Profile')` from Home: JS builds a layout node `{ id, type: 'Component', data, children }`, and calls
+`push(commandId, componentId, layout)`.
+
+1. **`ANNTurboModule push:componentId:layout:resolve:reject:`** (module queue). Builds the failure text
+   (`could not push the screen '…'`) and calls `+[ANNCommandRunner run:…]` with a check block and a body block.
+2. **`ANNCommandRunner`** (module queue). Takes `ANNReloadCoordinator.generation`. Runs the check:
+   `+[ANNLayoutReader nodeFrom:error:]` reads and validates the whole tree into `ANNLayoutNode`s. A failure rejects here,
+   through `ANNErrorHandler`, and nothing is queued. Otherwise it makes the `ANNCommandAnswer` and hands one task to the
+   main queue.
+3. **Main queue.** The task does nothing when the JavaScript went (`answer.isCurrent`), rejects
+   `+[ANNErrorTexts nowhereToShow]` when there is no window, then runs the body in `@try`. The body finds Home in
+   `ANNNodeRegistry` and calls `+[ANNStackCommands push:componentId:what:answer:]`.
+4. **`ANNStackCommands`.** Finds the stack by walking `layoutParent`; checks `ANNLayoutValidator` (an id already shown,
+   what a stack takes); reads the options of the whole tree with `ANNLayoutTreeOptions` (images load here); checks
+   `ANNLayoutFactory canMakeTrees:`; a node with `preview.nativeID` goes to `ANNPreviewPush`; a `key` of an entry below
+   goes back to that entry; else `+[ANNLayoutFactory nodeFromLayout:options:]` makes Profile (an
+   `ANNComponentViewController` with an `ANNComponentPresenter`, content from `ANNReactViewCreator`) and registers it.
+   No view is rendered yet.
+5. **`-[ANNStackQueue push:answer:…]`.** The node joins `entries` now (every check reads `entries`), the operation is
+   queued, `runNext` starts it when the queue is at rest.
+6. **`startPush:` and `startPushTransition:`.** By `animations.push.waitForRender` the queue waits through
+   `ANNRenderWait`, for the content and the bar components or for the bar components alone (a screen that waits for its
+   content is parked unseen in the stack's view by `ANNParking`, `stackPark:`), then renders the node, drives the appearance of Home and Profile (`+[ANNAppearanceDispatcher driveAppearanceOf:]`), and calls
+   `+[ANNAppearanceDispatcher beginTransitionShowing:]`. Profile's `ComponentWillAppear` is sent now (held until its
+   content mounted, 0.5 s at most). `stackChange:` pushes in UIKit; with an own animation `ANNTransitionPlan` and
+   `ANNStackAnimatingDelegate` give UIKit the `ANNTransitionAnimator`.
+7. **The end.** `stackWhenTransitionEnds:` fires from the transition coordinator and calls `endPush:`, which calls
+   `+[ANNAppearanceDispatcher endTransitionHiding:showing:events:answer:value:]`. In this order: `ComponentDidDisappear`
+   of Home, `ComponentDidAppear` of Profile, `ANN.NavigationStateChanged` (`+[ANNNavigationState updateNow]`), the
+   transition's `events`, then `-[ANNCommandAnswer resolve:]`: the state again if it changed
+   (`reportBeforeAnswer`), the promise with Profile's id, then `ANN.CommandCompleted`. `finish:` frees the queue for
+   the next operation.
+
+Events go out through `ANNEventEmitter` on the main queue and reach JS through `ANNTurboEventEmitter`.
+
+How the others differ:
+
+- **`setRoot`** (`ANNRootCoordinator`). At most one is pending; a newer one supersedes it (last wins). The root is made,
+  rendered at the window's size and parked under the current root, waits for its render (`ANNRenderWait`, and the
+  presentation gate when a presentation runs), then replaces the window's root by a dissolve or by its own animation
+  (`ANNTransitionAnimator`). The modals and overlays of the layout show after the root, one at a time, with the
+  navigation state held (`+[ANNNavigationState holdUpdates]`) until the answer. The old root's modals go with it
+  without `ANN.ModalDismissed`.
+- **`showModal`** (`ANNModalCoordinator`). One `ANNModal` record per modal. The tree is made and rendered, the record
+  waits parked in the window, then its present is a step in `ANNPresentationGate`. `ANNModalPresentation` decides the
+  style from the options; sheets and popovers go through `ANNSheetPresenter` and `ANNPopoverPresenter`; a custom show
+  goes through `ANNModalTransitions`. The answer comes with the root's id once the modal is presented, after the state.
+- **`mergeOptions`** (no promise, `-[ANNTurboModule mergeOptions:options:]`). Runs through `runVoid:` in one Core
+  Animation transaction. The node merges the options into its own (`mergeOwnOptions:`, which bumps the options cache),
+  its presenter applies what the merge names, the merge goes up the layout parents (`mergeChildOptions:child:`), then the
+  modal and overlay of the node take it and `ANNSystemUI` asks UIKit again for the groups it names.
+
+## The single places
+
+Each of these owns one rule. Call it; do not copy it.
+
+- `ANNCommandRunner`: The one path of every async command: generation, check, main queue, exception guard. Called by: `ANNTurboModule`.
+- `ANNLayoutReader`: The layout check, depth first, the same order and texts as Android. Module queue. Called by: The runner's check blocks.
+- `ANNCommandAnswer`: The answer: state, then promise, then `ANN.CommandCompleted`; once; silent for a JavaScript that went. Called by: Every coordinator and queue.
+- `ANNNodeRegistry`: Every node by id, weakly. Filled by the factory, cleared at a reload. Called by: Commands, modules, `findViewController:`.
+- `ANNLayoutFactory`: The core code that names module classes (`ANNSplitViewController`, `ANNSideMenuViewController`, `ANNArrangementViewController`); `ANNSideMenuPresenter` is the one other file that does. One maker per layout type; registers each node. Called by: Every command that shows a layout.
+- `ANNOptionsCache`: The one invalidation point of resolved options. Called by: The setter of `ANNNodeHelper.options` and `ANNDefaultOptions` only.
+- `ANNNodeHelper resolveOptionsWithDefault`: What a node shows with: defaults, parents' own options, the node's `resolveOptions` (own, then the current child down). Cached, read-only. Called by: Presenters, coordinators.
+- `ANNAppearanceDispatcher`: The only sender of `ComponentWillAppear`, `ComponentDidAppear`, `ComponentDidDisappear`; the end-of-transition order; the events of a node that goes. Called by: Screens, queues, coordinators.
+- `ANNNavigationState`: The visible screen and the nearest tabs it is in (the last tabs met walking down); coalesced updates, holds, the state before an answer. Called by: The dispatcher, `ANNCommandAnswer`, `ANNRootCoordinator`.
+- `ANNScreenReadiness`: The signals of a screen's safe area view (has one, laid out, content rendered), sticky, by screen id. Called by: `ANNSafeAreaViewComponentView`, `ANNReactView`.
+- `ANNRenderWait`: The one wait for the render of what a command shows: content, bar components, limits, the unknown-content rule. Called by: Root, stack queue, modals, overlays, `showInColumn`.
+- `ANNParking`: Where a view waits for its content unseen: the window, a stack's view, a preview's host view. Called by: Root, stack, modals, overlays, `ANNPreviewPush`.
+- `ANNPendingLayers`: Layers that wait to show (a pending root, a modal, an overlay); a node inside counts as off screen. Called by: The layer's owner; nodes ask.
+- `ANNShownScreens`: "What a node shows changed": tells the pending layer, the modal hold and the system UI, in that order. Called by: Every container that changes what it shows.
+- `ANNModalCoordinator`, `ANNModal`: One record per modal, its states and waiting commands. Called by: Commands, root, state, repaint, reload.
+- `ANNPresentationGate`: The one queue of every UIKit present and dismiss in the main window. Called by: Modals, root, reload, search.
+- `ANNOverlayCoordinator`: Overlays, each in its own window, kept over a new root. Called by: Commands, root, reload.
+- `ANNSystemUI`: The system UI of the windows: marks groups, coalesces, asks UIKit once per turn; who decides. `ANNSystemUIRules` has the pure rules. Called by: Screens, containers, `ANNShownScreens`, `mergeOptions`.
+- `ANNReloadCoordinator`: The generation of the JavaScript; the reset after a reload. Called by: Runner, emitter, answer.
+- Stack answer id: `ANNStackAnswerIdOf(entry, command)` in `ANNStackQueue.h`: the id a stack command answers with. `push` answers the node's own id (a pair's id); every other command, the entry's options screen (a pair's primary). Called by: The queue, `ANNStackCommands`, `ANNPreviewPush`, `ANNSplitViewCommands`.
+- Waited screens: `waitedComponentViewControllers`: the screens a wait is about (a pair: the ones it puts in the window). `ANNStackScreensOfEntry` is every screen of an entry, for what means all of them. Called by: `ANNRenderWait` owners: root, stack queue, modals, overlays, `ANNSplitViewCommands`.
+- Back: The stack: `ANNStackController` (`userGoBackTo:`, `backAction`, the hold) and `InteractivePopGestureDelegate`; UIKit's own pops are followed by `ANNStackQueue uikitShows:`. Called by: UIKit, the user.
+
+## Modules
+
+Modules are the feature folders that plug into the core through the interface in
+`ARCHITECTURE.md` section 4: the node protocol and its helper, the presenter hooks, the capabilities and
+the stores. By area:
+
+- **Containers:** `ANNSideMenuViewController` and `ANNSideMenuChildViewController`;
+  `ANNSplitViewController` with `UISplitViewController+ANNOptions`;
+  `ANNArrangementViewController`; `UITabBar+utils`, `ANNBottomTabsAccessoryView`.
+- **Modals:** `ANNSheetPresenter`, `ANNPopoverPresenter`, `ANNModalSizePresenter`, `ANNModalHostViewComponentView`;
+  `ANNOverlayWindow`.
+- **Screen and bar:** `ANNPreviewInteraction`, `ANNScreenInsets`, `ANNScreenRegions`, `ANNNativeScreenContext`,
+  `ANNNativeScreenCalls`, `ANNSearchPresenter`, `ANNSearchResultsViewController`; options `ANNMenuOptions`,
+  `ANNToolbarOptions`, `ANNSheetOptions`, `ANNPopoverOptions`, `ANNBottomTabsAccessoryOptions`.
+- **React and C++:** `React/Slots/`, `ANNSafeAreaViewComponentView`, the Fabric files of `cpp/`.
+- **App start:** `Public/ApexNavigation/ApexNavigation.h`, `Core/ANNSceneDelegate.mm`, `ANNKeyCommands`,
+  `ANNDeepLinkQueue`, `ANNHinge`.
+
+What a module uses of the core:
+
+- **The node protocol** `ANNLayoutProtocol`: required methods (`getCurrentChild`, `layoutChildren`,
+  `shownComponentViewControllers`, `render`, `readyForPresentation`, `resolveOptions`, `mergeOptions:`,
+  `mergeChildOptions:child:`, `destroy`, `systemUIChild`, …) and optional ones. `UIViewController+LayoutProtocol` gives
+  every view controller safe defaults and its `nodeHelper` (`ANNNodeHelper`): data, own options, resolved options,
+  ready handlers, registry entry. A container answers the methods that differ and does the common part with its
+  helper, never through `super`. Containers cannot share a base class (they inherit UIKit's), so the protocol and the
+  helper are the shared part.
+- **Capabilities** are optional methods of the protocol; a node without one answers "no": `waitedComponentViewControllers`,
+  `waitedReadinessOfScreen:`, `drivenDescendantDidAppear:`, `descendantDidAppear:`, `childDidDisappear:`, `goBackFromColumnOf:completion:`,
+  `screensLeavingWithNode`, `childOffsetFromRest:`, `optionsScreen`, `keepsStatusBarRoom`, `viewControllerOfColumn:`,
+  `isCollapsedIntoCompact`, `showScreen:inColumn:…`. The core asks with `respondsToSelector:` rather than by class; a few class checks remain (a screen reaches its
+  stack and its tabs by class).
+- **The presenter hooks** of `ANNNodePresenter`: `applyOptions:`, `mergeOptions:resolvedOptions:`,
+  `applyDefaultOptionsChange:`, `descendantWillAppear:`, `mergeChildOptions:`, `optionsForParent:`, and the answers to
+  UIKit (status bar, orientations, home indicator, deferred edges).
+- **The stores** a module writes on the main queue and JS reads from any thread: `ANNScreenInsets`,
+  `ANNScreenRegions`, `ANNArrangementState`; and the signals `ANNScreenReadiness`, `ANNSlotContainers`.
+- **A module's options group** subclasses `ANNOptions` and overrides `initWithDict:`, `mergeOptions:` and `hasValue`.
+
+Core code that lives in a module's folder: `ANNSplitViewPresenter` (turns `splitView.*` into calls of
+the module's category) and `ANNSplitViewCommands` (`showInColumn`, `setColumnShown`). They are the
+core's; only `ANNLayoutFactory` and `ANNSideMenuPresenter` name a module class.

package/ios/Contract/ANNCommandAnswer.h

@@ -0,0 +1,38 @@
+#import <React/RCTBridgeModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The one answer of a command with a promise: the first `resolve:` or `reject:` answers, any later one does nothing,
+/// and nothing answers once the JavaScript that sent the command went. `ANNCommandRunner` makes it. Main queue.
+@interface ANNCommandAnswer : NSObject
+
+- (instancetype)initWithCommandName:(NSString *)commandName
+                          commandId:(nullable NSString *)commandId
+                         generation:(NSUInteger)generation
+                            resolve:(RCTPromiseResolveBlock)resolve
+                             reject:(RCTPromiseRejectBlock)reject NS_DESIGNATED_INITIALIZER;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The method of `ANNTurboModule`: `push`, `setColumnShown`, …
+@property(nonatomic, copy, readonly) NSString *commandName;
+/// The id JS gave the call (`push13`); `preparePush` has the id of its push, `getLaunchLink` none.
+@property(nonatomic, copy, readonly, nullable) NSString *commandId;
+/// The generation of the JavaScript the command came from (`ANNReloadCoordinator`).
+@property(nonatomic, readonly) NSUInteger generation;
+/// Whether the command answered already.
+@property(nonatomic, readonly) BOOL answered;
+/// Whether the JavaScript the command came from still runs: its work goes on only then.
+@property(nonatomic, readonly) BOOL isCurrent;
+
+/// Resolves the promise: first the state goes, then the promise, then `ANN.CommandCompleted` for a command that shows
+/// or dismisses.
+- (void)resolve:(nullable id)value;
+
+/// Rejects the promise with the text alone: no code of the navigation.
+- (void)reject:(NSString *)text;
+
+@end
+
+NS_ASSUME_NONNULL_END