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

package/ios/CLAUDE.md

@@ -17,7 +17,7 @@ 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.
@@ -25,7 +25,7 @@ Swift is not used here: apps reach the core through the public headers (`Public/
 - `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`, …), the images' cache and loader (`ANNOptionImages`).
 - `Animations/`: The custom transition engine: plan, animator, wait, frame driver, rules; `Elements/` and `Interpolators/`.
@@ -42,7 +42,7 @@ 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`, `ANNScreenPlace` (the safe area of a parked screen), `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), `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`
@@ -63,27 +63,29 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - 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` (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`; an image keeps only its source). `ANNEventEmitter` moves an event from another queue
-  to the main queue.
+- **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 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`.
+- **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 (the JavaScript thread, the module's queue, the main
+  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
@@ -91,8 +93,8 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - `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

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
@@ -58,20 +59,21 @@ dispatcher.
 `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` (an image keeps its source,
    loaded through `ANNOptionImages` when an element shows it); 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
+   `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
@@ -80,7 +82,7 @@ dispatcher.
    `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, the module's queue, the main queue), so the
+   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
@@ -115,8 +117,8 @@ 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.
+- `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.
@@ -150,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/`.
@@ -174,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/ANNCommandRunner.h

@@ -3,16 +3,17 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// Reads and checks a command's layout on the module's queue: the layout read, or nil with the text of the rejection.
+/// Reads and checks a command's layout before its body, in the same task: the layout read, or nil with the text of the
+/// rejection.
 typedef id _Nullable (^ANNCommandCheck)(NSString *_Nullable *_Nonnull error);
 
-/// The command's own work on the main queue, with the layout its check read (nil without a check). It answers once,
-/// now or later; an exception it throws rejects the command, and undoing what it made by then is the body's.
+/// The command's own work, with the layout its check read (nil without a check). It answers once, now or later; an
+/// exception it throws rejects the command, and undoing what it made by then is the body's.
 typedef void (^ANNCommandBody)(id _Nullable layout, ANNCommandAnswer *answer);
 
-/// The one path of every asynchronous method of `ANNTurboModule`. On the module's queue, at once: the command takes the
-/// generation of its JavaScript and its layout is read and checked whole; a failure rejects it there and nothing is
-/// queued. Then one task on the main queue per command, in the order they came: the command does nothing when its
+/// The one path of every asynchronous method of `ANNTurboModule`, on the main queue (the module's queue), in one task
+/// per command in the order JavaScript made them: the command takes the generation of its JavaScript and its layout is
+/// read and checked whole, a failure rejecting it before anything is made; then the command does nothing when its
 /// JavaScript went, rejects when the navigation has nowhere to show screens, and runs its body inside the protection.
 @interface ANNCommandRunner : NSObject
 
@@ -27,7 +28,7 @@ typedef void (^ANNCommandBody)(id _Nullable layout, ANNCommandAnswer *answer);
         check:(nullable ANNCommandCheck)check
          body:(ANNCommandBody)body;
 
-/// A command without a promise: its body on the main queue, inside the protection; a failure is one log line.
+/// A command without a promise: its body at once, inside the protection; a failure is one log line. Main queue.
 + (void)runVoid:(NSString *)name what:(NSString *)what body:(dispatch_block_t)body;
 
 /// The log line of a command without a promise that failed: `[ApexNavigation] <name>: <text>`.

package/ios/Contract/ANNCommandRunner.mm

@@ -1,9 +1,9 @@
 #import "ANNCommandRunner.h"
+#import "ANNAssert.h"
 #import "ANNErrorHandler.h"
 #import "ANNErrorTexts.h"
 #import "ANNReloadCoordinator.h"
 #import "ApexNavigation+Internal.h"
-#import <React/RCTUtils.h>
 
 // Why an exception happened: its message, else its name.
 static NSString *ANNReasonOf(NSException *exception) {
@@ -27,6 +27,8 @@ static NSString *ANNRejectionOf(NSException *exception, NSString *what) {
        reject:(RCTPromiseRejectBlock)reject
         check:(ANNCommandCheck)check
          body:(ANNCommandBody)body {
+    // The module's methods come on the main queue: the check and the body run in this one task.
+    ANNAssertMainQueue();
     NSUInteger generation = ANNReloadCoordinator.generation;
     id layout = nil;
     if (check) {
@@ -46,36 +48,28 @@ static NSString *ANNRejectionOf(NSException *exception, NSString *what) {
                                                                   generation:generation
                                                                      resolve:resolve
                                                                       reject:reject];
-    // At once when the caller is on the main queue already; the module's queue never is.
-    RCTExecuteOnMainQueue(^{
-      if (!answer.isCurrent) {
-          return;
-      }
-      if (commandId && !ApexNavigation.mainWindow) {
-          [answer reject:ANNErrorTexts.nowhereToShow];
-          return;
-      }
-      @try {
-          body(layout, answer);
-      } @catch (NSException *exception) {
-          [answer reject:ANNRejectionOf(exception, what)];
-      }
-    });
+    if (!answer.isCurrent) {
+        return;
+    }
+    if (commandId && !ApexNavigation.mainWindow) {
+        [answer reject:ANNErrorTexts.nowhereToShow];
+        return;
+    }
+    @try {
+        body(layout, answer);
+    } @catch (NSException *exception) {
+        [answer reject:ANNRejectionOf(exception, what)];
+    }
 }
 
 // Before the navigation started a command without a promise has nothing to act on: its body finds nothing.
 + (void)runVoid:(NSString *)name what:(NSString *)what body:(dispatch_block_t)body {
-    NSUInteger generation = ANNReloadCoordinator.generation;
-    RCTExecuteOnMainQueue(^{
-      if (generation != ANNReloadCoordinator.generation) {
-          return;
-      }
-      @try {
-          body();
-      } @catch (NSException *exception) {
-          [self logFailure:name text:[ANNErrorTexts couldNot:what reason:ANNReasonOf(exception)]];
-      }
-    });
+    ANNAssertMainQueue();
+    @try {
+        body();
+    } @catch (NSException *exception) {
+        [self logFailure:name text:[ANNErrorTexts couldNot:what reason:ANNReasonOf(exception)]];
+    }
 }
 
 + (void)logFailure:(NSString *)name text:(NSString *)text {

package/ios/Contract/ANNLayoutNode.h

@@ -3,9 +3,9 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// One node of a command's layout, as `ANNLayoutReader` read and checked it on the module's queue. Immutable: made off
-/// the main queue, read on it by the command. The data stays the JSON JS sent; the accessors give its fields with the
-/// kind the contract has, or nothing.
+/// One node of a command's layout, as `ANNLayoutReader` read and checked it before the command's body. Immutable: made
+/// once, read by the command and the steps it runs later. The data stays the JSON JS sent; the accessors give its
+/// fields with the kind the contract has, or nothing.
 @interface ANNLayoutNode : NSObject
 
 /// Made by `ANNLayoutReader` only: the id as JS gave it, the type, the node's `data` (empty when missing) and its

package/ios/Contract/ANNLayoutReader.h

@@ -5,9 +5,9 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /// Reads the layout JSON of a command into `ANNLayoutNode`s and checks it whole, before any view is made. It runs on
-/// the module's queue, where the command arrives: a failure rejects the command there with the text of the first error
-/// found, and nothing goes to the main queue. It reads only the stores that are safe from any thread (the registered
-/// native screens, whether the app shows pairs).
+/// the main queue, in the command's task before its body: a failure rejects the command with the text of the first
+/// error found, and nothing is made. The stores it reads are safe from any thread (the registered native screens,
+/// whether the app shows pairs).
 ///
 /// One pass over the tree, depth first, children in order, the same order on both platforms so that the first error
 /// is the same text. At each node: a known `type` (`''` for a node that is no object or has no string type), an `id`

package/ios/Core/ANNJavaScriptCalls.h

@@ -5,28 +5,27 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /// The way of the calls JavaScript makes to `ANNTurboModule`, for a step that must come after them. A call without an
-/// answer (`mergeOptions`) leaves the JavaScript thread as it is made, goes to the module's queue (React Native's
-/// `ModuleNativeMethodCallInvoker`, a `dispatch_async` to it) and from there to the main queue (`ANNCommandRunner`):
-/// a step that takes the same three hops after them comes after them on the main queue, as each of the three runs its
-/// work in order. The module tells its call invoker and its queue when React Native made it, and that it went when
-/// React Native invalidates it (a reload). Any thread, except `afterCallsMadeSoFar:`.
+/// answer (`mergeOptions`) leaves the JavaScript thread as it is made, as a task on the main queue, the module's queue
+/// (React Native's `ModuleNativeMethodCallInvoker`, a `dispatch_async` to it), and runs whole in that task
+/// (`ANNCommandRunner`). A step sent from the JavaScript thread to the main queue after them comes after them: the
+/// JavaScript thread runs its tasks in order, and the main queue runs what it is given in the order it was given. The
+/// module tells its call invoker when React Native made it, and that it went when React Native invalidates it (a
+/// reload). Any thread, except `afterCallsMadeSoFar:`.
 @interface ANNJavaScriptCalls : NSObject
 
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
 
-/// The module of the JavaScript that runs now, its call invoker (the JavaScript thread) and its queue.
-+ (void)setCallInvoker:(nullable RCTCallInvoker *)callInvoker
-           methodQueue:(nullable dispatch_queue_t)methodQueue
-              ofModule:(id)module;
+/// The module of the JavaScript that runs now and its call invoker (the JavaScript thread).
++ (void)setCallInvoker:(nullable RCTCallInvoker *)callInvoker ofModule:(id)module;
 
 /// The module went: with no newer module told since, no JavaScript runs to wait for.
 + (void)moduleWent:(id)module;
 
 /// `block` runs on the main queue once every call JavaScript made to the module before the next task of its thread is
-/// applied on the main queue: a task on the JavaScript thread, from there one on the module's queue, from there one on
-/// the main queue. With no JavaScript to ask (none yet, a reload), at once. Main queue. A JavaScript thread that never
-/// runs the task again (its runtime went) never runs `block`: a caller that can't wait for long has a limit of its own.
+/// applied: a task on the JavaScript thread, from there one on the main queue. With no JavaScript to ask (none yet, a
+/// reload), at once. Main queue. A JavaScript thread that never runs the task again (its runtime went) never runs
+/// `block`: a caller that can't wait for long has a limit of its own.
 + (void)afterCallsMadeSoFar:(dispatch_block_t)block;
 
 @end

package/ios/Core/ANNJavaScriptCalls.mm

@@ -1,23 +1,18 @@
 #import "ANNJavaScriptCalls.h"
 #import "ANNAssert.h"
 #import <React/RCTCallInvoker.h>
-#import <React/RCTUtils.h>
 #import <ReactCommon/CallInvoker.h>
 
-// The module told last, weakly: a module that went takes its invoker and its queue with it.
+// The module told last, weakly: a module that went takes its invoker with it.
 static __weak id ANNCallsModule;
 static RCTCallInvoker *ANNCallsInvoker;
-static dispatch_queue_t ANNCallsQueue;
 
 @implementation ANNJavaScriptCalls
 
-+ (void)setCallInvoker:(RCTCallInvoker *)callInvoker
-           methodQueue:(dispatch_queue_t)methodQueue
-              ofModule:(id)module {
++ (void)setCallInvoker:(RCTCallInvoker *)callInvoker ofModule:(id)module {
     @synchronized(self) {
         ANNCallsModule = module;
         ANNCallsInvoker = callInvoker;
-        ANNCallsQueue = methodQueue;
     }
 }
 
@@ -28,33 +23,29 @@ static dispatch_queue_t ANNCallsQueue;
         }
         ANNCallsModule = nil;
         ANNCallsInvoker = nil;
-        ANNCallsQueue = nil;
     }
 }
 
 + (void)afterCallsMadeSoFar:(dispatch_block_t)block {
     ANNAssertMainQueue();
     RCTCallInvoker *callInvoker = nil;
-    dispatch_queue_t queue = nil;
     @synchronized(self) {
         if (ANNCallsModule) {
             callInvoker = ANNCallsInvoker;
-            queue = ANNCallsQueue;
         }
     }
     std::shared_ptr<facebook::react::CallInvoker> invoker =
         callInvoker ? callInvoker.callInvoker : nullptr;
-    if (!invoker || !queue) {
+    if (!invoker) {
         block();
         return;
     }
     dispatch_block_t done = [block copy];
     // The JavaScript thread runs the task after the one it runs now, which made the calls of this moment (a commit of
-    // React and its layout effects); the module's queue then has those calls before this hop, and the main queue too.
-    invoker->invokeAsync([queue, done](facebook::jsi::Runtime &) {
-        dispatch_async(queue, ^{
-          RCTExecuteOnMainQueue(done);
-        });
+    // React and its layout effects). Each of those calls went to the main queue as it was made, so this hop, sent from
+    // the same thread later, reaches the main queue behind them (a serial queue, in the order it was given).
+    invoker->invokeAsync([done](facebook::jsi::Runtime &) {
+        dispatch_async(dispatch_get_main_queue(), done);
     });
 }
 

package/ios/Core/ANNReloadCoordinator.mm

@@ -1,5 +1,4 @@
 #import "ANNReloadCoordinator.h"
-#import "ANNArrangementState.h"
 #import "ANNAssert.h"
 #import "ANNErrorTexts.h"
 #import "ANNHinge.h"
@@ -12,9 +11,8 @@
 #import "ANNPreviewInteraction.h"
 #import "ANNPreviewPush.h"
 #import "ANNRootCoordinator.h"
-#import "ANNScreenInsets.h"
+#import "ANNScreenEnvironment.h"
 #import "ANNScreenReadiness.h"
-#import "ANNScreenRegions.h"
 #import "ANNSplashViewController.h"
 #import "ANNSplitViewCommands.h"
 #import "ANNTabsPreloadWindow.h"
@@ -154,12 +152,10 @@ static BOOL ANNWatchingBundles;
     [oldScreens addObjectsFromArray:[ANNSplitViewCommands takeAllForReload]];
     // The new JavaScript counts its ids anew: nothing the safe area views of the old screens said stays ready for a new
     // screen with the same id. The old surfaces are stopped or silent. The same for what the old screens kept for
-    // JavaScript: their insets and padding, regions and arrangement states (an old screen still in a window writes no
-    // insets or regions again: its emitter is not current).
+    // JavaScript, their environment: insets and padding, regions and arrangements (an old screen still in a window
+    // writes no insets or regions again: its emitter is not current).
     [ANNScreenReadiness reset];
-    [ANNScreenInsets removeAll];
-    [ANNScreenRegions removeAll];
-    [ANNArrangementState removeAll];
+    [ANNScreenEnvironment removeAll];
     // 6. The window shows the blank screen, which counts as the splash: a reload is not a launch. The
     // reset runs from the second bundle of the process on.
     if (window) {

package/ios/Core/ApexNavigation+Internal.h

@@ -18,7 +18,7 @@ NS_ASSUME_NONNULL_BEGIN
 + (nullable ANNNativeScreenCreator)nativeScreenCreatorForName:(NSString *)name;
 
 /// Whether a native screen is registered under the name by `registerNativeScreen:creator:` (the registration of 8.x is
-/// gone). Any thread: the layout of a command is checked on the module's queue.
+/// gone). Any thread (the layout check of a command reads it on the main queue).
 + (BOOL)hasNativeScreenNamed:(NSString *)name;
 
 @end

package/ios/Layouts/Arrangement/ANNArrangementState.h

@@ -1,30 +1,15 @@
-#import "ANNEventEmitter.h"
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// The state of each screen of an arrangement (`useArrangement`): `{ placement, layout, front, hidden }`, which view of
-/// the pair it is and how the pair lies. The native side keeps it on the main queue; JavaScript reads it from its own
-/// thread for a screen's first render, and gets every change as `ANN.ArrangementChanged`.
+/// Whether the app can show pairs at all. The state of each screen of a pair (`useArrangement`) is kept for JavaScript
+/// by `ANNScreenEnvironment`.
 @interface ANNArrangementState : NSObject
 
 /// Whether the app shows arrangements (`getStartInfo().arrangements`): built with the iOS 27.1 SDK and running on
 /// iOS 27.1 or later. Without them JavaScript sends only the primary, as a screen. Any thread.
 + (BOOL)canShowArrangements;
 
-/// Keeps the screen's state and tells when it changed; nothing goes without an emitter. Main queue.
-+ (void)setState:(NSDictionary<NSString *, id> *)state
-     forScreenId:(NSString *)screenId
-    eventEmitter:(nullable ANNEventEmitter *)eventEmitter;
-
-/// The screen's state, or nil for a screen outside a pair. Any thread.
-+ (nullable NSDictionary<NSString *, id> *)stateForScreenId:(NSString *)screenId;
-
-+ (void)removeScreenId:(NSString *)screenId;
-
-/// Forgets every screen: after a reload the new JavaScript counts its ids anew. Main queue.
-+ (void)removeAll;
-
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Layouts/Arrangement/ANNArrangementState.mm

@@ -1,16 +1,8 @@
 #import "ANNArrangementState.h"
 #import "ANNArrangementViewController.h"
 
-static NSMutableDictionary<NSString *, NSDictionary<NSString *, id> *> *ANNArrangementStateById;
-
 @implementation ANNArrangementState
 
-+ (void)initialize {
-    if (self == ANNArrangementState.class) {
-        ANNArrangementStateById = [NSMutableDictionary new];
-    }
-}
-
 + (BOOL)canShowArrangements {
 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 270100
     if (@available(iOS 27.1, *)) {
@@ -20,34 +12,4 @@ static NSMutableDictionary<NSString *, NSDictionary<NSString *, id> *> *ANNArran
     return NO;
 }
 
-+ (void)setState:(NSDictionary<NSString *, id> *)state
-     forScreenId:(NSString *)screenId
-    eventEmitter:(ANNEventEmitter *)eventEmitter {
-    @synchronized(ANNArrangementStateById) {
-        if ([ANNArrangementStateById[screenId] isEqualToDictionary:state]) {
-            return;
-        }
-        ANNArrangementStateById[screenId] = state;
-    }
-    [eventEmitter sendArrangementChanged:screenId state:state];
-}
-
-+ (NSDictionary<NSString *, id> *)stateForScreenId:(NSString *)screenId {
-    @synchronized(ANNArrangementStateById) {
-        return ANNArrangementStateById[screenId];
-    }
-}
-
-+ (void)removeScreenId:(NSString *)screenId {
-    @synchronized(ANNArrangementStateById) {
-        [ANNArrangementStateById removeObjectForKey:screenId];
-    }
-}
-
-+ (void)removeAll {
-    @synchronized(ANNArrangementStateById) {
-        [ANNArrangementStateById removeAllObjects];
-    }
-}
-
 @end

package/ios/Layouts/Arrangement/ANNArrangementViewController.mm

@@ -2,10 +2,10 @@
 
 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 270100
 
-#import "ANNArrangementState.h"
 #import "ANNComponentViewController.h"
 #import "ANNEventContract.h"
 #import "ANNExternalViewController.h"
+#import "ANNScreenEnvironment.h"
 #import "ANNShownScreens.h"
 #import "ANNUtils.h"
 
@@ -298,9 +298,9 @@ static BOOL ANNIsShown(UIViewController *screen, UIArrangementViewState *state,
          ofScreen:(UIViewController *)screen
      eventEmitter:(ANNEventEmitter *)eventEmitter {
     if (ANNKeepsState(screen)) {
-        [ANNArrangementState setState:state
-                          forScreenId:screen.layoutInfo.componentId
-                         eventEmitter:eventEmitter];
+        [ANNScreenEnvironment setArrangement:state
+                                 forScreenId:screen.layoutInfo.componentId
+                                eventEmitter:eventEmitter];
     }
 }
 

package/ios/Layouts/Screen/ANNComponentViewController.h

@@ -11,8 +11,8 @@ NS_ASSUME_NONNULL_BEGIN
 ///
 /// Its view has the size of the screen of the navigation window's scene; the content sits in the root frame, by the one
 /// "under bars" rule (`ANNScreenBars`). Every recompute of the frame (a layout, a change of the safe area or the
-/// traits, `mergeOptions`, an appearance) gives the modules the screen's insets, padding and regions
-/// (`ANNScreenInsets`, `ANNScreenRegions`). Its presenter is an `ANNComponentPresenter`.
+/// traits, `mergeOptions`, an appearance) gives the store the screen's insets, padding and regions
+/// (`ANNScreenEnvironment`). Its presenter is an `ANNComponentPresenter`.
 ///
 /// The screen answers UIKit's questions about the system UI (native screens too): the status bar's style and visibility
 /// (never animated), the orientations, the home indicator, the deferred edges and the vertical bars, from its resolved