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

package/ios/Options/Params/ImageParser.mm

@@ -0,0 +1,103 @@
+#import "ImageParser.h"
+#import "ANNOptionsReader.h"
+#import <React/RCTConvert.h>
+#import <React/RCTLog.h>
+#import <React/RCTUtils.h>
+
+@implementation ImageParser
+
++ (Image *)parse:(NSDictionary *)json key:(NSString *)key {
+    id value = [json isKindOfClass:NSDictionary.class] ? json[key] : nil;
+    if (!value || value == NSNull.null) {
+        return [[Image alloc] initWithValue:nil];
+    }
+    NSString *path = [ANNOptionsReader pathOfKey:key];
+    return [[Image alloc] initWithValue:[self imageOf:value path:path]];
+}
+
++ (UIImage *)imageOf:(id)value path:(NSString *)path {
+    if ([value isKindOfClass:NSArray.class]) {
+        RCTLogError(@"[ApexNavigation] the image of '%@' is a list of sources, which options don't support: give "
+                    @"one source",
+                    path);
+        return nil;
+    }
+    if ([value isKindOfClass:NSDictionary.class] && value[@"system"]) {
+        return [self systemImageOf:value path:path];
+    }
+    if (![value isKindOfClass:NSString.class] && ![value isKindOfClass:NSDictionary.class]) {
+        return nil;
+    }
+    return [self imageOfSource:value path:path];
+}
+
+// An SF Symbol; a name the system doesn't have takes the fallback source, read the same way.
++ (UIImage *)systemImageOf:(NSDictionary *)value path:(NSString *)path {
+    id name = value[@"system"];
+    UIImage *image = [name isKindOfClass:NSString.class] ? [UIImage systemImageNamed:name] : nil;
+    if (image) {
+        return image;
+    }
+    id fallback = value[@"fallback"];
+    return fallback && fallback != NSNull.null ? [self imageOf:fallback path:path] : nil;
+}
+
+// A resolved source, loaded synchronously as React Native's converter of images does, with the scale of the source.
++ (UIImage *)imageOfSource:(id)source path:(NSString *)path {
+    NSDictionary *fields = [source isKindOfClass:NSDictionary.class] ? source : nil;
+    id address = fields ? (fields[@"uri"] ?: fields[@"url"]) : source;
+    if (![address isKindOfClass:NSString.class] || [address length] == 0) {
+        RCTLogError(@"[ApexNavigation] the image of '%@' has no address", path);
+        return nil;
+    }
+    id bundle = fields[@"bundle"];
+    if ([bundle isKindOfClass:NSString.class]) {
+        address = [NSString stringWithFormat:@"%@.bundle/%@", bundle, address];
+    }
+    NSURL *url = [RCTConvert NSURL:address];
+    NSString *scheme = url.scheme.lowercaseString;
+    BOOL metroAsset = ANNJSONIsBoolean(fields[@"__packager_asset"]) && [fields[@"__packager_asset"] boolValue];
+    UIImage *image = nil;
+    if ([scheme isEqualToString:@"file"]) {
+        image = RCTImageFromLocalAssetURL(url) ?: RCTImageFromLocalBundleAssetURL(url);
+    } else if ([scheme isEqualToString:@"data"]) {
+        image = [UIImage imageWithData:[NSData dataWithContentsOfURL:url]];
+    } else if (([scheme isEqualToString:@"http"] || [scheme isEqualToString:@"https"]) && metroAsset) {
+        // Metro's assets in development: loaded from the dev server, synchronously.
+        image = [UIImage imageWithData:[NSData dataWithContentsOfURL:url]];
+    } else {
+        RCTLogError(@"[ApexNavigation] the image of '%@' is not loaded: remote images are not supported in options "
+                    @"(%@)",
+                    path, address);
+        return nil;
+    }
+    if (!image) {
+        RCTLogError(@"[ApexNavigation] the image of '%@' could not be loaded: %@", path, address);
+        return nil;
+    }
+    return [self image:image scaledBy:fields];
+}
+
+// The scale of the source; without it the pixel width over `width`; without both, the file's own. A size that
+// doesn't match is only logged.
++ (UIImage *)image:(UIImage *)image scaledBy:(NSDictionary *)fields {
+    id scaleValue = fields[@"scale"];
+    id widthValue = fields[@"width"];
+    id heightValue = fields[@"height"];
+    CGFloat scale = ANNJSONIsNumber(scaleValue) ? [scaleValue doubleValue] : 0;
+    CGFloat width = ANNJSONIsNumber(widthValue) ? [widthValue doubleValue] : 0;
+    CGFloat height = ANNJSONIsNumber(heightValue) ? [heightValue doubleValue] : 0;
+    if (scale <= 0 && width > 0 && image.CGImage) {
+        scale = CGImageGetWidth(image.CGImage) / width;
+    }
+    if (scale > 0 && image.CGImage && scale != image.scale) {
+        image = [UIImage imageWithCGImage:image.CGImage scale:scale orientation:image.imageOrientation];
+    }
+    if (width > 0 && height > 0 && !CGSizeEqualToSize(image.size, CGSizeMake(width, height))) {
+        RCTLogInfo(@"[ApexNavigation] an image of the options is %@, its source says %@",
+                   NSStringFromCGSize(image.size), NSStringFromCGSize(CGSizeMake(width, height)));
+    }
+    return image;
+}
+
+@end

package/ios/Options/Params/Number.h

@@ -0,0 +1,14 @@
+#import "Param.h"
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// A number (a size, a width).
+@interface Number : Param
+
+- (nullable NSNumber *)get;
+- (nullable NSNumber *)withDefault:(nullable NSNumber *)defaultValue;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/Params/Number.mm

@@ -0,0 +1,13 @@
+#import "Number.h"
+
+@implementation Number
+
+- (NSNumber *)get {
+    return [super get];
+}
+
+- (NSNumber *)withDefault:(NSNumber *)defaultValue {
+    return [super withDefault:defaultValue];
+}
+
+@end

package/ios/Options/Params/NumberParser.h

@@ -0,0 +1,13 @@
+#import "Number.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Reads `key` of the options' JSON: a finite number, kept as `NSNumber` (a boolean, `NaN` or an infinity is no
+/// value).
+@interface NumberParser : NSObject
+
++ (Number *)parse:(nullable NSDictionary *)json key:(NSString *)key;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/Params/NumberParser.mm

@@ -0,0 +1,10 @@
+#import "NumberParser.h"
+
+@implementation NumberParser
+
++ (Number *)parse:(NSDictionary *)json key:(NSString *)key {
+    id value = [json isKindOfClass:NSDictionary.class] ? json[key] : nil;
+    return [[Number alloc] initWithValue:ANNJSONIsNumber(value) ? value : nil];
+}
+
+@end

package/ios/Options/Params/Param.h

@@ -0,0 +1,16 @@
+#import "ANNParam.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// A value of any JSON type, kept as it came (a detent: a name or a height).
+@interface Param : ANNParam
+
+/// The value; nil without one and for `null`.
+- (nullable id)get;
+
+/// The value, or `defaultValue` when the options gave none; nil for `null`.
+- (nullable id)withDefault:(nullable id)defaultValue;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/Params/Param.mm

@@ -0,0 +1,13 @@
+#import "Param.h"
+
+@implementation Param
+
+- (id)get {
+    return self.isNull ? nil : self.value;
+}
+
+- (id)withDefault:(id)defaultValue {
+    return self.hasValue ? self.get : defaultValue;
+}
+
+@end

package/ios/Options/Params/Text.h

@@ -0,0 +1,17 @@
+#import "Param.h"
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// A text value.
+@interface Text : Param
+
+/// A value set by the native side, as a user choice the options keep.
++ (Text *)withValue:(nullable NSString *)value;
+
+- (nullable NSString *)get;
+- (nullable NSString *)withDefault:(nullable NSString *)defaultValue;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/Params/Text.mm

@@ -0,0 +1,17 @@
+#import "Text.h"
+
+@implementation Text
+
++ (Text *)withValue:(NSString *)value {
+    return [[Text alloc] initWithValue:value];
+}
+
+- (NSString *)get {
+    return [super get];
+}
+
+- (NSString *)withDefault:(NSString *)defaultValue {
+    return [super withDefault:defaultValue];
+}
+
+@end

package/ios/Options/Params/TextParser.h

@@ -0,0 +1,17 @@
+#import "Text.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Reads `key` of the options' JSON as a text.
+@interface TextParser : NSObject
+
+/// A string, or `null`: an explicit "no text" that replaces what the layers under it give.
++ (Text *)parse:(nullable NSDictionary *)json key:(NSString *)key;
+
+/// A value of an enumeration: one of `values`; an unknown string, `null` or another type is no value
+/// (the option's default applies).
++ (Text *)parse:(nullable NSDictionary *)json key:(NSString *)key values:(NSSet<NSString *> *)values;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/Params/TextParser.mm

@@ -0,0 +1,17 @@
+#import "TextParser.h"
+
+@implementation TextParser
+
++ (Text *)parse:(NSDictionary *)json key:(NSString *)key {
+    id value = [json isKindOfClass:NSDictionary.class] ? json[key] : nil;
+    BOOL readable = [value isKindOfClass:NSString.class] || value == NSNull.null;
+    return [[Text alloc] initWithValue:readable ? value : nil];
+}
+
++ (Text *)parse:(NSDictionary *)json key:(NSString *)key values:(NSSet<NSString *> *)values {
+    id value = [json isKindOfClass:NSDictionary.class] ? json[key] : nil;
+    BOOL readable = [value isKindOfClass:NSString.class] && [values containsObject:value];
+    return [[Text alloc] initWithValue:readable ? value : nil];
+}
+
+@end

package/ios/Package.swift

@@ -0,0 +1,58 @@
+// swift-tools-version: 6.0
+// SwiftPM package of @apexnative/navigation, for apps on React Native's SwiftPM setup (`npx react-native spm`).
+// React Native's autolinking uses this manifest as is and links this directory at
+// <app>/build/generated/autolinking/libs/ApexNavigation, so the paths of the React Native packages below
+// are relative to that link. CocoaPods apps use ApexNavigation.podspec instead.
+
+import PackageDescription
+
+// Folders whose headers other folders import by bare name, as the CocoaPods header map allows.
+let headerFolders = [
+    ".", "Contract", "Core", "Layouts/Root", "Layouts/Screen", "Layouts/Stack", "Layouts/Tabs", "Layouts/SideMenu",
+    "Layouts/SplitView", "Layouts/Arrangement", "Layouts/Modal", "Layouts/Overlay", "Layouts/External", "TopBar", "Options",
+    "Options/Params", "Animations", "Animations/Elements", "Animations/Interpolators", "React", "React/Slots",
+    "TurboModules", "Utils", "Public/ApexNavigation",
+]
+
+let package = Package(
+    name: "ApexNavigation",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "ApexNavigation", targets: ["ApexNavigation"]),
+    ],
+    dependencies: [
+        .package(name: "ReactNative", path: "../../../../xcframeworks"),
+        .package(name: "React-GeneratedCode", path: "../../../ios"),
+    ],
+    targets: [
+        .target(
+            name: "ApexNavigation",
+            dependencies: [
+                .product(name: "ReactHeaders", package: "ReactNative"),
+                .product(name: "ReactNativeHeaders", package: "ReactNative"),
+                .product(name: "ReactNativeDependenciesHeaders", package: "ReactNative"),
+                .product(name: "ReactAppHeaders", package: "React-GeneratedCode"),
+                .product(name: "ReactAppDependencyProvider", package: "React-GeneratedCode"),
+            ],
+            path: ".",
+            exclude: ["ARCHITECTURE.md", "CLAUDE.md", "CORE.md", "RECIPES.md", "ApexNavigation-prefix.h"],
+            // <ApexNavigation/ApexNavigation.h>, <ApexNavigation/ANNAppDelegate.h>, …
+            publicHeadersPath: "Public",
+            cSettings: headerFolders.map { .headerSearchPath($0) } + [
+                .unsafeFlags(["-include", "ApexNavigation-prefix.h"]),
+            ],
+            cxxSettings: headerFolders.map { .headerSearchPath($0) } + [
+                .unsafeFlags(["-include", "ApexNavigation-prefix.h"]),
+                // The Fabric ABI of the prebuilt React framework differs between Debug and Release.
+                .define("DEBUG", .when(configuration: .debug)),
+                .define("NDEBUG", .when(configuration: .release)),
+            ],
+            linkerSettings: [
+                .linkedFramework("UIKit"),
+                .linkedFramework("Foundation"),
+                .linkedFramework("CoreGraphics"),
+            ]
+        ),
+    ],
+    cxxLanguageStandard: .cxx20
+)

package/ios/Public/ApexNavigation/ANNAppDelegate.h

@@ -0,0 +1,66 @@
+#import <UIKit/UIKit.h>
+
+@class RCTDefaultReactNativeFactoryDelegate;
+@class RCTReactNativeFactory;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * The app delegate of an app on the navigation. It makes React Native's factory and host with `reactNativeDelegate`,
+ * starts the navigation and owns its window; the screens come from JS (`setRoot`). An app's delegate inherits it,
+ * sets `reactNativeDelegate` (its subclass of `RCTDefaultReactNativeFactoryDelegate`, which gives the bundle URL) and
+ * registers its native screens in `application(_:didFinishLaunchingWithOptions:)` before calling `super`.
+ *
+ * ```swift
+ * @main
+ * class AppDelegate: ANNAppDelegate {
+ *   override func application(
+ *     _ application: UIApplication,
+ *     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+ *   ) -> Bool {
+ *     self.reactNativeDelegate = ReactNativeDelegate()
+ *     return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+ *   }
+ * }
+ * ```
+ */
+@interface ANNAppDelegate : UIResponder <UIApplicationDelegate>
+
+/// The navigation's window.
+@property(nonatomic, strong, nullable) UIWindow *window;
+
+/// Gives React Native the bundle URL and the app's settings; set it before `super`'s
+/// `application:didFinishLaunchingWithOptions:`.
+@property(nonatomic, strong, nullable) RCTDefaultReactNativeFactoryDelegate *reactNativeDelegate;
+
+/// React Native's factory, made at launch with `reactNativeDelegate`.
+@property(nonatomic, strong, nullable) RCTReactNativeFactory *reactNativeFactory;
+
+/**
+ * Hands a deep link to React Native's `Linking`; the link that launched the app is the latest one dispatched by the
+ * time its scene connected. Any thread; nil does nothing.
+ */
+- (void)dispatchDeepLinkURL:(nullable NSURL *)url NS_SWIFT_NAME(dispatchDeepLinkURL(_:));
+
+- (BOOL)application:(UIApplication *)application
+    didFinishLaunchingWithOptions:(nullable NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions;
+
+/// `ANNSceneDelegate` for the app's scene, unless the Info.plist names a scene delegate of its own.
+- (UISceneConfiguration *)application:(UIApplication *)application
+    configurationForConnectingSceneSession:(UISceneSession *)connectingSceneSession
+                                   options:(UISceneConnectionOptions *)options;
+
+/// The URL goes to `dispatchDeepLinkURL:`.
+- (BOOL)application:(UIApplication *)application
+            openURL:(NSURL *)url
+            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options;
+
+/// A web link (`NSUserActivityTypeBrowsingWeb`) goes to `dispatchDeepLinkURL:`; other activities are not taken.
+- (BOOL)application:(UIApplication *)application
+    continueUserActivity:(NSUserActivity *)userActivity
+      restorationHandler:
+          (void (^)(NSArray<id<UIUserActivityRestoring>> *_Nullable restorableObjects))restorationHandler;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Public/ApexNavigation/ANNSceneDelegate.h

@@ -0,0 +1,19 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Scene delegate for apps on the UIScene life cycle, which apps built with the iOS 27 SDK must use.
+ *
+ * `ANNAppDelegate` assigns it to the app's scene unless the Info.plist names a scene delegate of its own.
+ * When the scene connects, the navigation window moves into it. URLs, user activities and foreground/background
+ * changes that UIKit now delivers to the scene are forwarded to the app delegate's usual methods, so
+ * the deep links (`dispatchDeepLinkURL:`) and app delegate overrides keep working.
+ */
+@interface ANNSceneDelegate : UIResponder <UIWindowSceneDelegate>
+
+@property(nonatomic, strong, nullable) UIWindow *window;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Public/ApexNavigation/ApexNavigation.h

@@ -0,0 +1,92 @@
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+@class RCTHost;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// What a native screen gets when JS opens it, for as long as it is open.
+NS_SWIFT_NAME(NativeScreenContext)
+@interface ANNNativeScreenContext : NSObject
+
+/// The screen's layout id: `externalComponent.id`, or the one JS generated.
+@property(nonatomic, copy, readonly) NSString *componentId;
+
+/// The props: those of the command that showed the screen, with what its `useProps` returns over them. Plain data;
+/// they change while the screen is open, and `onPropsChange` tells when.
+@property(nonatomic, copy, readonly) NSDictionary<NSString *, id> *props;
+
+/// The names of the functions in the props, which `call(_:arguments:)` runs in JS.
+@property(nonatomic, copy, readonly) NSSet<NSString *> *functions;
+
+/// Called on the main thread with the new props, each time they change.
+@property(nonatomic, copy, nullable) void (^onPropsChange)(NSDictionary<NSString *, id> *props);
+
+/**
+ * Runs a function of the props in JS. `completion` gets, on the main thread, what it returned (for a promise, what it
+ * resolved with) as plain data, or the error: a function the props don't have, one that threw, a screen gone.
+ *
+ * ```swift
+ * let saved = try await context.call("onSave", arguments: ["Ann"])
+ * ```
+ */
+- (void)call:(NSString *)function
+     arguments:(NSArray *)arguments
+    completion:(nullable void (^)(id _Nullable_result value, NSError *_Nullable error))completion
+    NS_SWIFT_NAME(call(_:arguments:completion:));
+
+/**
+ * Runs a command of the navigation from this screen in JS, as `useNavigation()` of a React screen does: push, pop,
+ * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, dismissOverlay, setOptions, selectTab, setTabBadge.
+ * `arguments` are those of the JS command; `completion` gets what it resolved with.
+ *
+ * ```swift
+ * try await context.navigate("push", arguments: ["Details", ["props": ["id": 1]]])
+ * ```
+ */
+- (void)navigate:(NSString *)command
+       arguments:(NSArray *)arguments
+      completion:(nullable void (^)(id _Nullable_result value, NSError *_Nullable error))completion
+    NS_SWIFT_NAME(navigate(_:arguments:completion:));
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+@end
+
+/// Makes the view controller of a native screen: a UIKit one, or a SwiftUI view in a `UIHostingController`.
+typedef UIViewController *_Nonnull (^ANNNativeScreenCreator)(ANNNativeScreenContext *context)
+    NS_SWIFT_NAME(NativeScreenCreator);
+
+@interface ApexNavigation : NSObject
+
++ (void)bootstrapWithHost:(RCTHost *)host;
+
+/**
+ * Registers a native screen that JS opens with `externalComponent: { name, passProps }`. Call it any time before
+ * JS opens the screen, for example in `application(_:didFinishLaunchingWithOptions:)`.
+ *
+ * ```swift
+ * ApexNavigation.registerNativeScreen("Profile") { context in
+ *   UIHostingController(rootView: ProfileView(props: context.props))
+ * }
+ * ```
+ */
++ (void)registerNativeScreen:(NSString *)name
+                     creator:(ANNNativeScreenCreator)creator NS_SWIFT_NAME(registerNativeScreen(_:creator:));
+
++ (nullable RCTHost *)getHost;
+
++ (nullable UIViewController *)findViewController:(NSString *)componentId;
+
+/**
+ * Moves the navigation window into `windowScene` and shows it. `ANNSceneDelegate` does this when the app's
+ * scene connects; call it from your own `UIWindowSceneDelegate` if the app has one, in
+ * `scene(_:willConnectTo:options:)`. Forward the connection options' `urlContexts` and `userActivities` to the app
+ * delegate in that same method: the link that launched the app is the latest URL dispatched by the time it returns.
+ */
++ (UIWindow *)attachToWindowScene:(UIWindowScene *)windowScene;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Public/module.modulemap

@@ -0,0 +1,8 @@
+// The ApexNavigation module for SwiftPM builds: the three public headers. CocoaPods generates its own
+// module map from public_header_files.
+module ApexNavigation {
+    header "ApexNavigation/ApexNavigation.h"
+    header "ApexNavigation/ANNAppDelegate.h"
+    header "ApexNavigation/ANNSceneDelegate.h"
+    export *
+}

package/ios/RECIPES.md

@@ -0,0 +1,41 @@
+# iOS recipes
+
+The steps for the two changes that touch many files on iOS: adding an option and adding a command. Read it when
+you do exactly that; the map is `ios/CLAUDE.md`.
+
+## Adding an option
+
+1. **The type and its JSDoc** in `src/interfaces/Options.ts` (the JSDoc is the reference docs). A new root
+   option also goes into the `options` of its section in `docs/sections.json`.
+2. **The options class.** The group's `ANN<Group>Options` in `Options/`: declare the field once in `+optionFields`
+   (`boolField:`, `colorField:`, `enumField:values:`, `groupField:class:`, …). Parsing, merging, copying and `hasValue`
+   come from `ANNOptions`. A new group is a new `ANN<Group>Options` pair, added to its parent's fields with
+   `groupField:class:`. The DEBUG check `ANNCheckOptionClassesFrom` walks the field tables once.
+3. **The presenter that applies it.** Read the value from the resolved options (`resolveOptionsWithDefault`) in the
+   presenter of its area: at the screen's creation, at each appearance, in `mergeOptions:resolvedOptions:` (apply only
+   what the merge names) and in `applyDefaultOptionsChange:`. A system-UI option also goes into
+   `+[ANNSystemUI groupsNamedBy:onlyRead:]`; a bar-placement option into `ANNOptionsChangeScreenBars`.
+4. **The cache.** Never invalidate by hand. Own options change through `ANNNodeHelper` (`mergeOwnOptions:`,
+   `changeOwnOptions:`) and defaults through `+[ANNDefaultOptions setCurrent:]`; both call
+   `+[ANNOptionsCache optionsChanged]`. A presenter or module that keeps a choice of the user writes it with
+   `changeOwnOptions:`, never into the options in place.
+5. **Android** reads the same JSON and has unit tests of parsing and merging; the iOS side has none (see Checks in `ios/CLAUDE.md`).
+6. **The rule:** an option does what its name promises, with the same meaning on both platforms
+   (`.claude/rules/general.md`, `.claude/rules/options.md`). A platform that can't, says so in the JSDoc.
+
+## Adding a command
+
+1. The method in the codegen spec `src/adapters/NativeANNTurboModule.ts`; the engine side in `src/engine/commands.ts`
+   (`.claude/rules/native-contract.md`).
+2. **`ANNTurboModule`:** the method. Call `+[ANNCommandRunner run:…]` with a `check` block that reads the layout
+   (`ANNLayoutReader`) and a `body` block that calls the area class. A command without a promise uses `runVoid:`.
+3. **The area class** does the work on the main queue and answers once. Its checks come before any node is made, in the
+   same order on both platforms; read the stack as JS sees it (`ANNStackQueue.entries`).
+4. **The layout check:** a new node type goes into `ANNLayoutType` and `ANNLayoutReader` (its place, its children), and
+   gets a maker in `ANNLayoutFactory`.
+5. **Error texts** come from `ANNErrorTexts`, one sentence per case, the same as Android; a text deep in a maker is
+   thrown with `+[ANNErrorTexts rejection:]`.
+6. **The answer:** end through `ANNAppearanceDispatcher` (`endTransitionHiding:…answer:value:`) or call
+   `-[ANNCommandAnswer resolve:]`; the state and `ANN.CommandCompleted` follow by themselves for the names in
+   `ANNCompletedCommandNames`. Add the name there when the command shows or dismisses.
+7. **Android** gets the same command; its tests check the texts.

package/ios/React/ANNComponentType.h

@@ -0,0 +1,22 @@
+#import <Foundation/Foundation.h>
+
+/// What a React view of the navigation shows: a screen, or a component of the options (bar title, button, background).
+/// The lifecycle events name it by this type (`componentType`).
+typedef NS_ENUM(NSInteger, ANNComponentType) {
+    /// A screen, `Component` in the events.
+    ANNComponentTypeComponent,
+    /// The same as a screen, by the name the views of screens use.
+    ANNReactComponentTypeScreen = ANNComponentTypeComponent,
+    ANNComponentTypeTopBarTitle,
+    ANNComponentTypeTopBarButton,
+    ANNComponentTypeTopBarBackground,
+    /// A cell of the tabs' custom row (`bottomTab.component`): it renders at once and sends no appearance events on
+    /// iOS.
+    ANNComponentTypeBottomTabItem,
+    /// The tabs' bottom accessory (iOS 26, `bottomTabs.bottomAccessory.component`): it waits for its layout like a
+    /// screen and sends no appearance events.
+    ANNComponentTypeBottomTabsAccessory,
+};
+
+/// The type as the views of screens name it.
+typedef ANNComponentType ANNReactComponentType;

package/ios/React/ANNComponentViewCreator.h

@@ -0,0 +1,18 @@
+#import "ANNReactView.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// How the core makes the views of screens and of the components of the options; a layout node gets it at creation.
+@protocol ANNComponentViewCreator <NSObject>
+
+/// The content of the screen or component `name` with the id `componentId`: a React view, or the slot screen view for
+/// a name with `ANNSlotPrefix`.
+- (UIView<ANNComponentProtocol> *)createComponentView:(NSString *)name
+                                          componentId:(NSString *)componentId
+                                        componentType:(ANNComponentType)componentType
+                                  reactViewReadyBlock:
+                                      (nullable ANNReactViewReadyCompletionBlock)reactViewReadyBlock;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/React/ANNReactComponentRegistry.h

@@ -0,0 +1,53 @@
+#import "ANNComponentOptions.h"
+#import "ANNComponentViewCreator.h"
+#import "ANNReactView.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The React roots of the components in one screen's options (bar title, buttons, background, search results), by the
+/// id of the component. Each screen owns one, made with its creator: the same `name` and `componentId` give the same
+/// root while the screen keeps it; another `name` with the id replaces it, and the old root stops. The registry holds
+/// its roots until they are removed or the screen goes (`stopAll`): none is left to stop in `dealloc`. A new JavaScript
+/// never finds an old root: its screens have registries of their own. Main queue.
+@interface ANNReactComponentRegistry : NSObject
+
+- (instancetype)initWithCreator:(id<ANNComponentViewCreator>)creator;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The search module's call: the React view of the component, made at the first call for its id; nil when the
+/// component has no name or id, or when its content is not a React view of its own.
+- (nullable ANNReactView *)createComponentIfNotExists:(ANNComponentOptions *)component
+                                    parentComponentId:(NSString *)parentComponentId
+                                        componentType:(ANNComponentType)componentType
+                                  reactViewReadyBlock:
+                                      (nullable ANNReactViewReadyCompletionBlock)reactViewReadyBlock;
+
+/// The root of `component`, made at the first call for its id (a root with the same id and another name stops and is
+/// replaced); nil when the component has no name or no id (`topBar.title.component.name`).
+- (nullable UIView<ANNComponentProtocol> *)componentView:(ANNComponentOptions *)component
+                                                    type:(ANNComponentType)componentType;
+
+/// The root kept for the id; nil when none.
+- (nullable UIView<ANNComponentProtocol> *)existingComponent:(NSString *)componentId;
+
+/// Whether the root of the id rendered (its ready signal went).
+- (BOOL)isComponentReady:(NSString *)componentId;
+
+/// `handler` runs once when the root of the id is ready: at once when it is already, never when no root has the id or
+/// the root goes first.
+- (void)whenComponentReady:(NSString *)componentId do:(dispatch_block_t)handler;
+
+/// The component goes: its root stops at once (once, on the main queue).
+- (void)removeChildComponent:(NSString *)childId;
+
+/// Every root still alive stops (the screen's destroy).
+- (void)stopAll;
+
+/// The roots alive now.
+@property(nonatomic, readonly) NSArray<UIView<ANNComponentProtocol> *> *allComponents;
+
+@end
+
+NS_ASSUME_NONNULL_END