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

package/ios/Animations/Interpolators/ANNViewTracks.mm

@@ -2,6 +2,7 @@
 #import "ANNAnimationPropertyOptions.h"
 #import "ANNElementTransitionOptions.h"
 #import "ANNTrack.h"
+#import "ANNTransformParts.h"
 #import "ANNUtils.h"
 #import "ANNViewAnimationOptions.h"
 #import <QuartzCore/QuartzCore.h>
@@ -81,10 +82,19 @@ static ANNTrack *ANNTrackOf(Double *from, Double *to, Double *duration, Double *
     CGPoint _origin;
     CGFloat _alphaBefore;
     CATransform3D _transformBefore;
+    // The parts of the view's own transform (its React Native `transform`): what a property that doesn't play keeps,
+    // and the missing end of one that does, as Android keeps a view's own properties.
+    CGPoint _ownTranslation;
+    CGPoint _ownScale;
+    double _ownRotationX;
+    double _ownRotationY;
+    double _ownRotation;
+    CATransform3D _ownSkew;
+    CGFloat _ownPerspective;
     BOOL _animatesTransform;
     BOOL _tilts;
-    BOOL _wroteAlpha;
-    BOOL _wroteTransform;
+    BOOL _addedAlpha;
+    BOOL _addedTransform;
     BOOL _restored;
     NSTimeInterval _endTime;
 }
@@ -146,21 +156,48 @@ static ANNTrack *ANNTrackOf(Double *from, Double *to, Double *duration, Double *
                               layer.position.y - bounds.size.height * layer.anchorPoint.y);
         _alphaBefore = alphaBefore;
         _transformBefore = layer.transform;
+        [self readOwnTransform];
     }
     return self;
 }
 
+// A transform that can't be split (a scale of 0) counts as none, as before the view's own transform was kept.
+- (void)readOwnTransform {
+    _ownScale = CGPointMake(1, 1);
+    _ownSkew = CATransform3DIdentity;
+    ANNTransformParts parts;
+    if (!ANNTransformPartsOf(_transformBefore, &parts)) {
+        return;
+    }
+    _ownTranslation = CGPointMake((CGFloat)parts.translate[0], (CGFloat)parts.translate[1]);
+    _ownScale = CGPointMake((CGFloat)parts.scale[0], (CGFloat)parts.scale[1]);
+    ANNRotationDegreesOf(parts, &_ownRotationX, &_ownRotationY, &_ownRotation);
+    _ownSkew = ANNSkewTransformOf(parts);
+    _ownPerspective = (CGFloat)parts.perspective[2];
+}
+
 - (double)viewValueOf:(ANNViewProperty)property {
     switch (property) {
         case ANNViewPropertyX:
-            return _origin.x;
+            return _origin.x + _ownTranslation.x;
         case ANNViewPropertyY:
-            return _origin.y;
+            return _origin.y + _ownTranslation.y;
+        case ANNViewPropertyTranslationX:
+            return _ownTranslation.x;
+        case ANNViewPropertyTranslationY:
+            return _ownTranslation.y;
         case ANNViewPropertyAlpha:
             return _alphaBefore;
         case ANNViewPropertyScaleX:
+            return _ownScale.x;
         case ANNViewPropertyScaleY:
-            return 1;
+            return _ownScale.y;
+        case ANNViewPropertyRotationX:
+            return _ownRotationX;
+        case ANNViewPropertyRotationY:
+            return _ownRotationY;
+        case ANNViewPropertyRotation:
+            return _ownRotation;
         default:
             return 0;
     }
@@ -198,17 +235,9 @@ static ANNTrack *ANNTrackOf(Double *from, Double *to, Double *duration, Double *
     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;
-    }
+// The view's transform at `time`: every property of the transform at its value then, the ones that don't play at the
+// view's own.
+- (CATransform3D)transformAtTime:(NSTimeInterval)time {
     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.
@@ -221,28 +250,69 @@ static ANNTrack *ANNTrackOf(Double *from, Double *to, Double *duration, Double *
             ? (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]) {
+    CATransform3D transform =
+        CATransform3DConcat(CATransform3DMakeScale(scaleX, scaleY, 1), _ownSkew);
+    if (_tracks[ANNViewPropertyRotationX] || _ownRotationX != 0) {
         CGFloat radians = ANNRadians([self valueOf:ANNViewPropertyRotationX at:time]);
         transform = CATransform3DConcat(transform, ANNRotationX(radians));
     }
-    if (_tracks[ANNViewPropertyRotationY]) {
+    if (_tracks[ANNViewPropertyRotationY] || _ownRotationY != 0) {
         CGFloat radians = ANNRadians([self valueOf:ANNViewPropertyRotationY at:time]);
         transform = CATransform3DConcat(transform, ANNRotationY(radians));
     }
-    if (_tracks[ANNViewPropertyRotation]) {
+    if (_tracks[ANNViewPropertyRotation] || _ownRotation != 0) {
         CGFloat radians = ANNRadians([self valueOf:ANNViewPropertyRotation at:time]);
         transform = CATransform3DConcat(transform, ANNRotationZ(radians));
     }
-    if (_tilts) {
+    // A tilt that plays gets the camera's perspective unless the view has its own; a view's own tilt keeps the
+    // perspective it had, none without one, as React Native draws it.
+    if (_tilts || _ownPerspective != 0) {
         CATransform3D perspective = CATransform3DIdentity;
-        perspective.m34 = -1.0 / ANNCameraDistance();
+        perspective.m34 = _ownPerspective != 0 ? _ownPerspective : -1.0 / ANNCameraDistance();
         transform = CATransform3DConcat(transform, perspective);
     }
-    transform = CATransform3DConcat(transform,
-                                    CATransform3DMakeTranslation(translationX, translationY, 0));
-    _view.layer.transform = transform;
-    _wroteTransform = YES;
+    return CATransform3DConcat(transform,
+                               CATransform3DMakeTranslation(translationX, translationY, 0));
+}
+
+- (void)addAnimationsWithLength:(NSTimeInterval)length {
+    if (_restored || !self.hasTracks) {
+        return;
+    }
+    // Every track's start and end is a sample, so a track that starts late or ends early does it on time.
+    NSMutableArray<NSNumber *> *marks = [NSMutableArray new];
+    for (NSInteger index = 0; index < ANNViewPropertyCount; index++) {
+        ANNTrack *track = _tracks[index];
+        if (track) {
+            [marks addObject:@(track.delay)];
+            [marks addObject:@(track.endTime)];
+        }
+    }
+    NSArray<NSNumber *> *times = ANNSampleTimes(_endTime, length, marks);
+    CALayer *layer = _view.layer;
+    if (self.animatesAlpha) {
+        NSMutableArray<NSNumber *> *values = [NSMutableArray arrayWithCapacity:times.count];
+        for (NSNumber *time in times) {
+            [values addObject:@([_tracks[ANNViewPropertyAlpha] valueAt:time.doubleValue])];
+        }
+        CAKeyframeAnimation *animation = ANNKeyframes(@"opacity", values, times, length);
+        if (animation) {
+            [layer addAnimation:animation forKey:ANNAnimationKey(@"opacity")];
+            _addedAlpha = YES;
+        }
+    }
+    if (_animatesTransform) {
+        NSMutableArray<NSValue *> *values = [NSMutableArray arrayWithCapacity:times.count];
+        for (NSNumber *time in times) {
+            CATransform3D transform = [self transformAtTime:time.doubleValue];
+            [values addObject:[NSValue valueWithCATransform3D:transform]];
+        }
+        CAKeyframeAnimation *animation = ANNKeyframes(@"transform", values, times, length);
+        if (animation) {
+            [layer addAnimation:animation forKey:ANNAnimationKey(@"transform")];
+            _addedTransform = YES;
+        }
+    }
 }
 
 - (void)restore {
@@ -250,11 +320,11 @@ static ANNTrack *ANNTrackOf(Double *from, Double *to, Double *duration, Double *
         return;
     }
     _restored = YES;
-    if (_wroteAlpha) {
-        _view.alpha = _alphaBefore;
+    if (_addedAlpha) {
+        [_view.layer removeAnimationForKey:ANNAnimationKey(@"opacity")];
     }
-    if (_wroteTransform) {
-        _view.layer.transform = _transformBefore;
+    if (_addedTransform) {
+        [_view.layer removeAnimationForKey:ANNAnimationKey(@"transform")];
     }
 }
 

package/ios/CLAUDE.md

@@ -17,17 +17,17 @@ Swift is not used here: apps reach the core through the public headers (`Public/
 - `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/Screen/`: The screen (`ANNComponentViewController`), its presenter, readiness, its environment for JS (`ANNScreenEnvironment`), 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/Tabs/`: `ANNBottomTabsController`, its presenter, item builder, custom row, 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`.
+- `Layouts/Arrangement/`: The pair (iOS 27.1): `ANNArrangementViewController`, `ANNArrangementState` (whether pairs can show).
 - `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`, …).
+- `Options/`, `Options/Params`: One `ANN<Group>Options` class per group, the field table, the value kinds and parsers (`Bool`, `Color`, `Text`, `Image`, …), the images' cache and loader (`ANNOptionImages`).
 - `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`.
@@ -42,9 +42,9 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - 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)
+- Screen: insets, background, keyboard focus — `Layouts/Screen/`: `ANNScreenEnvironment`, `ANNScreenSafeArea`, `ANNScreenBars`, `ANNScreenPlace` (the safe area of a parked screen), `ANNScreenSettling` (iPhone Duo: the insets wait while a fold settles), `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`
+- Stack: queue, commands, back, gestures — `Layouts/Stack/`: `ANNStackQueue`, `ANNStackCommands`, `ANNStackController`, `InteractivePopGestureDelegate`, `ANNStackAnimatingDelegate`, `ANNSwipePopInteraction`
 - 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`
@@ -58,40 +58,57 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - 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`
+- Events and state — `Core/`: `ANNEventEmitter`, `ANNEventContract` (names and keys, made by `scripts/contract.mjs`), `ANNAppearanceDispatcher`, `ANNScreenAppearance`, `ANNNavigationState`; `TurboModules/`: `ANNTurboEventEmitter`
 - Options: parsing, merging, defaults — `Options/`: `ANNOptions`, `ANNOptionField`, `ANNOptionsReader`, `ANNDefaultOptions`, `ANNOptionsCache`; `Core/`: `ANNOptionsRepaint`
-- Error texts — `Contract/`: `ANNErrorTexts`; `Core/`: `ANNErrorHandler`
+- Error texts and answers — `Contract/`: `ANNErrorTexts` and `ANNCommandContract` (made from `src/interfaces/contract/errors.json` and `commands.json` by `scripts/contract.mjs`); `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`
+- Hinge, regions, arrangement — `Core/`: `ANNHinge`; `Layouts/Screen/`: `ANNScreenRegions` (the measuring), `ANNScreenEnvironment` (what JS reads); `Layouts/Arrangement/`: `ANNArrangementState`
 - Native screens — `Layouts/External/`: `ANNExternalViewController`, `ANNNativeScreenCalls`; `Layouts/Screen/ANNNativeScreenContext.mm`
-- Slots — `React/Slots/`: `ANNSlotHost`, `ANNSlotContainers`, `ANNSlotScreenView`, `ANNSlotComponentView`; `cpp/`
+- Slots — `React/Slots/`: `ANNSlotHost`, `ANNSlotContainers` (containers and slot views by slot id: a change goes
+  straight to the views of its id), `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`.
+- **Main queue:** everything but the sync getters and the images. `ANNTurboModule`'s method queue is the main queue,
+  as `ANNTurboEventEmitter`'s: an async method comes there from the JavaScript thread, and `ANNCommandRunner` runs the
+  layout check (`ANNLayoutReader`) and the body in that one task. A command body starts with `ANNAssertMainQueue()`.
+  The options of a layout are parsed here (`ANNLayoutTreeOptions`; an image keeps only its source). `ANNEventEmitter`
+  moves an event from another queue to the main queue.
+- **The images' queue** (`ANNOptionImages`, `Options/Params`): every option image decodes there, through one cache.
+  An element that shows an image asks for it when it applies and waits for it (the first frame needs it); only a tab
+  item's new icon on the bar that shows comes later (`ANNBottomTabsPresenter`), the last build of the item winning.
+- **Sync getters** answer JS on the JavaScript thread (React Native calls them there whatever the module's queue)
+  during a screen's first render: `getScreenInsets`, `getScreenRegions`, `getArrangementState`, `getHinge`,
+  `getStartInfo`. They read `ANNScreenEnvironment` (one record per screen id: insets, padding, regions, arrangement)
+  and `ANNHinge lastValue`, written on the main queue and guarded by `@synchronized`. The environment's padding
+  listeners are main-queue only.
   `ANNReloadCoordinator.generation` and `ANNEventEmitter.isCurrent` are readable from any thread.
+- **After the calls of JavaScript:** `ANNJavaScriptCalls afterCallsMadeSoFar:` runs a step on the main queue after
+  every call JavaScript made by then, by the calls' own way (a task on the JavaScript thread, then one on the main
+  queue). A push's wait ends through it, so the `mergeOptions` of its screen's first commit come first.
 
 ## 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.
+- There is no iOS unit-test target. `ANNSystemUIRulesSelfCheck`, `ANNCheckOptionClassesFrom` and `ANNCheckSameValues`
+  (the options' value equality) 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.
+- A screen parked by a wait for its content (`ANNParking`) has no parent, and UIKit gives its view no safe area: it lays
+  out with the safe area of its place (`ANNScreenPlace`, measured on a navigation controller of the core's), or its
+  list would move as the push starts and UIKit would show the large title only after the transition. On iOS 26 its
+  large title also keeps a place of the core's for the push (`arrivesByPushOn:`). Check Showcase 1.4 (with a font
+  size), every section panel and 12.6 on push, pop and swipe after any change to waits, parking or the large title.
+  A tab rendered before it shows keeps its parent, yet UIKit gives its views no safe area either: it renders parked
+  in the tabs' view with places measured in the shown tab's view, then leaves the parking, since the core takes a view
+  in a window for one on screen (`isInUnseenTab:`); its screens keep that place until they appear.
 - 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
@@ -114,15 +131,33 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
   `descendantDidAppear:`.
 - Hold and release of the navigation state come in pairs; a `setRoot` chain with layout modals or overlays holds it
   until its answer.
+- UIKit draws a dismissal without animation too (a sheet's dim goes a frame before its card): what goes out of sight
+  that way goes under a snapshot of the window (the old root's modals at `setRoot`, `startTransitionOf:done:`).
 - 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.
+  `ANNSurfaceHostingView`; without it `useColorScheme` keeps the old theme. `Appearance.setColorScheme` sets the style
+  only on the windows there are at that moment: every window the core makes but the main window comes from
+  `+[ANNUtils makeWindowOfClass:]`, which gives it the main window's style. A window of the system's style would draw
+  its screens in the other theme, and its hosting views would switch the app's theme in JS.
 - 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:`.
+- Each step of a transition's element (a pair's start and take-off, an element's start, its animations and restore
+  through `ANNIsolatedElement`) runs in `ANNElementStep`: an exception skips that element only. A new step of an
+  element goes there too, or one bad element stops the transition. The elements of a transition are found in one walk
+  per screen (`ANNTransitionViews`).
+- A custom transition runs in Core Animation (`ANNFrameDriver`): each client samples its values once, at the start,
+  into keyframe animations under the core's keys (`ANNAnimationKey`), and `restore` removes them. It never writes a
+  view's own alpha or transform for a frame; a value the core writes for the transition (the arriving view's hide, a
+  hidden flag, a depth) goes back as before. A pop that follows the swipe back also stops the time of the transition's
+  container (`startPausedOn:done:`), and the container gets its time back before the clients restore. UIKit runs its
+  swipe back without asking the navigation's delegate for a transition (iOS 26 checked), so that pop follows the
+  stack's own swipe from the leading edge, and UIKit's swipes stand aside meanwhile (`swipeBackTakes:`).
+- An `ANNCommandAnswer` that goes away unanswered rejects (`notAnswered:`), but only once nothing holds it: a record,
+  list or queue that keeps an answer still answers it on every exit, or the promise waits as long as the record lives.
 - 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
@@ -130,9 +165,10 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - 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 works out the safe area of the window's root view from where it is: a `transform` written on it that moves it
+  leaves it with no top inset, and putting the transform back doesn't work it out again. A root's own `enter` moves
+  only what Core Animation draws; the root is still laid out after a restore (`+[ANNRootCoordinator stopAnimationOf:]`).
+  While it animates, the new root takes no touches: it is drawn elsewhere than where it is.
 - 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.

package/ios/CORE.md

@@ -8,10 +8,10 @@ and files is `ios/CLAUDE.md`.
 
 ```
 JS ── ANNTurboModule (codegen ApexNavigationSpec) ────────────────────────────────────────────┐ sync getters
-       │ module queue                                                                          │ read stores
+       │ main queue (the module's queue), one task per command, in call order                  │ read stores
        ▼                                                                                       ▼ (@synchronized)
   ANNCommandRunner ── ANNLayoutReader (check the whole layout) ── ANNErrorTexts ── ANNErrorHandler
-       │ one task per command on the main queue, in call order
+       │ the check passed: the body, in the same task
        ▼
   area command (ANNStackCommands, ANNRootCoordinator, ANNModalCoordinator, ANNOverlayCoordinator, ANNSplitViewCommands)
        │ ANNLayoutValidator · ANNLayoutTreeOptions · ANNLayoutFactory ── ANNNodeRegistry
@@ -32,12 +32,13 @@ JS ── ANNTurboModule (codegen ApexNavigationSpec) ────────
 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.
+- **Way in** (`ANNTurboModule`): the codegen methods. Its method queue is the main queue: an async method comes there
+  from the JavaScript thread and hands its work to `ANNCommandRunner`; a sync getter runs on the JavaScript thread,
+  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.
+- **Command runner** (`ANNCommandRunner`, `ANNCommandAnswer`): takes the generation of the JavaScript, runs the check,
+  then the body inside an exception guard, both in the command's one task on the main queue. 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
@@ -50,42 +51,48 @@ dispatcher.
 - **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.
+  events of a JavaScript that went. The names and keys come from `ANNEventContract`, made from the event types of
+  `src/interfaces/` (`scripts/contract.mjs`).
 
 ## 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:
+1. **`ANNTurboModule push:componentId:layout:resolve:reject:`** (main queue, the module's queue: React Native sends
+   the call there from the JavaScript thread). Builds the failure text (`could not push the screen '…'`) and calls
+   `+[ANNCommandRunner run:…]` with a check block and a body block.
+2. **`ANNCommandRunner`** (the same task). 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
+   through `ANNErrorHandler`, and nothing is made. Otherwise it makes the `ANNCommandAnswer`.
+3. **The body.** The runner 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
+   what a stack takes); reads the options of the whole tree with `ANNLayoutTreeOptions` (an image keeps its source,
+   loaded through `ANNOptionImages` when an element shows it); checks `ANNLayoutFactory canMakeTrees:`; a node with
+   `preview.nativeID` goes to `ANNPreviewPush` (it makes the node at once; a React screen with a root of its own
+   renders at the press, in the configuration call of `ANNPreviewInteraction`, other screens at once); 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
+   `ANNRenderWait`: unset, for the content at most 0.5 s, with `true` as long as it takes, then for the bar components
+   (their limits from the wait's start when unset, from the content's end with `true`; the screen is parked unseen in
+   the stack's view by `ANNParking`, `stackPark:`); the content's end, content there already too, waits for the calls
+   JavaScript made by then (`ANNJavaScriptCalls`: the JavaScript thread, then the main queue), so the
+   options of the screen's first commit are in the bar; with `false` nothing. Then it 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.
+   of Home, `ComponentDidAppear` of Profile, `ANN.NavigationStateChanged` (`-[ANNCommandAnswer reportStateNow]`, the
+   answer's one state step), the transition's `events`, then `-[ANNCommandAnswer resolve:]`: the promise with
+   Profile's id, then `ANN.CommandCompleted`. A command answered without a transition's end (`setRoot` with layout
+   modals) sends its state from `resolve:`. `finish:` frees the queue for the next operation.
 
 Events go out through `ANNEventEmitter` on the main queue and reach JS through `ANNTurboEventEmitter`.
 
@@ -110,28 +117,29 @@ How the others differ:
 
 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.
+- `ANNCommandRunner`: The one path of every async command: main queue (the module's queue), generation, check, exception guard. Called by: `ANNTurboModule`.
+- `ANNLayoutReader`: The layout check, depth first, the same order and texts as Android. Main queue, before the body. Called by: The runner's check blocks.
+- `ANNCommandAnswer`: The answer: state (one step per answer, `reportStateNow`, asked by the end of its transition or by `resolve:`), 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.
+- `ANNOptionsCache`: The one invalidation point of resolved options. Called by: The setters of `ANNNodeHelper.options` and of its user layer (`setUserChoice:forKey:`), and `ANNDefaultOptions`, only.
+- `ANNNodeHelper resolveOptionsWithDefault`: What a node shows with: defaults, parents' own options (each with its user layer), the node's `resolveOptions` (own, its user layer, 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`.
+- `ANNNavigationState`: The visible screen and the nearest tabs it is in (the last tabs met walking down); coalesced updates, holds, the state now. Called by: The dispatcher, `ANNCommandAnswer`, `ANNRootCoordinator`, `ANNModalCoordinator`, `ANNBottomTabsController`.
 - `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`.
+- `ANNParking`: Where a view waits for its content unseen: the window, a stack's view, a preview's host view, the tabs' view. Called by: Root, stack, modals, overlays, `ANNPreviewPush`, tabs (a tab rendered before it shows).
+- `ANNScreenPlace`: The safe area a parked screen lays out with, measured where it will show on top of a stack. Called by: `ANNStackController` (`stackPark:`), `ANNSplitViewCommands` (`showInColumn`), the tabs (a tab rendered before it shows, measured in the shown tab's view), through `placeWhileParked` of the screen.
 - `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`.
+- `ANNSystemUI`: The system UI of the windows: marks groups, coalesces, asks UIKit once per turn; who decides; after a status bar ask, the screens' status bar blurs take its frame. `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.
+- Back: The stack: `ANNStackController` (`userGoBackTo:`, `backAction`, the hold) and `InteractivePopGestureDelegate`; UIKit's own pops are followed by `ANNStackQueue uikitShows:`. A top whose own pop is `interactive` gets the stack's own swipe from the leading edge instead of UIKit's (UIKit runs its swipe without asking the delegate for a transition): `swipeBackTakes:` picks the swipe, `ownSwipeBack:` pops, and `swipeAnimatorFrom:to:` and `ANNSwipePopInteraction` play the pop under the finger. Called by: UIKit, the user.
 
 ## Modules
 
@@ -144,7 +152,7 @@ the stores. By area:
   `ANNArrangementViewController`; `UITabBar+utils`, `ANNBottomTabsAccessoryView`.
 - **Modals:** `ANNSheetPresenter`, `ANNPopoverPresenter`, `ANNModalSizePresenter`, `ANNModalHostViewComponentView`;
   `ANNOverlayWindow`.
-- **Screen and bar:** `ANNPreviewInteraction`, `ANNScreenInsets`, `ANNScreenRegions`, `ANNNativeScreenContext`,
+- **Screen and bar:** `ANNPreviewInteraction`, `ANNScreenEnvironment`, `ANNScreenRegions`, `ANNNativeScreenContext`,
   `ANNNativeScreenCalls`, `ANNSearchPresenter`, `ANNSearchResultsViewController`; options `ANNMenuOptions`,
   `ANNToolbarOptions`, `ANNSheetOptions`, `ANNPopoverOptions`, `ANNBottomTabsAccessoryOptions`.
 - **React and C++:** `React/Slots/`, `ANNSafeAreaViewComponentView`, the Fabric files of `cpp/`.
@@ -168,8 +176,10 @@ What a module uses of the core:
 - **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`.
+- **The stores** a module writes on the main queue and JS reads from any thread: `ANNScreenEnvironment`, one record
+  per screen id (insets and padding, regions, arrangement) under one lock, cleared with one call when the screen goes
+  (`removeScreenId:`, only once no node holds the id) and at a reload (`removeAll`); 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

package/ios/Contract/ANNCommandAnswer.h

@@ -3,14 +3,15 @@
 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.
+/// and nothing answers once the JavaScript that sent the command went. One that goes away unanswered while its
+/// JavaScript runs rejects `[ANNErrorTexts notAnswered:]`. `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;
+                            resolve:(nullable RCTPromiseResolveBlock)resolve
+                             reject:(nullable RCTPromiseRejectBlock)reject NS_DESIGNATED_INITIALIZER;
 
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
@@ -26,8 +27,15 @@ NS_ASSUME_NONNULL_BEGIN
 /// 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.
+/// The navigation state now, sent when it changed, once per answer: the end of the command's transition asks for it
+/// after the `DidAppear` it sends and before the transition's own events (`ANNAppearanceDispatcher`); otherwise
+/// `resolve:` asks for it before the promise. A later call sends nothing, and nothing goes for a JavaScript that went.
+/// A failure of the step is logged and costs only the state.
+- (void)reportStateNow;
+
+/// Resolves the promise: first the state, when the command changes what shows (`ANNCommandContract`) and its
+/// transition didn't send it already (`reportStateNow`), 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.