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

package/ios/Contract/ANNLayoutNode.mm

@@ -0,0 +1,153 @@
+#import "ANNLayoutNode.h"
+
+// The column names of a split view; any other name is left out.
+static NSSet<NSString *> *ANNKnownColumnNames(void) {
+    static NSSet<NSString *> *names;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      names = [NSSet
+          setWithArray:@[ @"primary", @"secondary", @"supplementary", @"compact", @"inspector" ]];
+    });
+    return names;
+}
+
+// Only strings: anything else in a list of names counts as missing.
+static NSArray<NSString *> *ANNStrings(id value) {
+    if (![value isKindOfClass:NSArray.class]) {
+        return @[];
+    }
+    NSMutableArray<NSString *> *strings = [NSMutableArray new];
+    for (id item in (NSArray *)value) {
+        if ([item isKindOfClass:NSString.class]) {
+            [strings addObject:item];
+        }
+    }
+    return [strings copy];
+}
+
+@implementation ANNLayoutNode
+
+- (instancetype)initWithNodeId:(NSString *)nodeId
+                          type:(ANNLayoutType)type
+                          data:(NSDictionary<NSString *, id> *)data
+                      children:(NSArray<ANNLayoutNode *> *)children {
+    if (self = [super init]) {
+        _nodeId = [nodeId copy];
+        _type = type;
+        _data = [data copy];
+        _children = [children copy];
+    }
+    return self;
+}
+
+- (NSString *)typeName {
+    return ANNLayoutTypeName(_type);
+}
+
+- (NSString *)description {
+    return [NSString stringWithFormat:@"<%@ '%@'>", self.typeName, _nodeId];
+}
+
+#pragma mark - Fields of data
+
+- (NSString *)stringOf:(NSString *)field {
+    id value = _data[field];
+    return [value isKindOfClass:NSString.class] ? value : nil;
+}
+
+- (NSString *)name {
+    return [self stringOf:@"name"];
+}
+
+- (NSDictionary<NSString *, id> *)options {
+    id options = _data[@"options"];
+    return [options isKindOfClass:NSDictionary.class] ? options : @{};
+}
+
+- (NSString *)key {
+    return [self stringOf:@"key"];
+}
+
+// The props of a React screen stay in JS: only a native screen's are read.
+- (NSDictionary<NSString *, id> *)passProps {
+    if (_type != ANNLayoutTypeExternalComponent) {
+        return nil;
+    }
+    id props = _data[@"passProps"];
+    return [props isKindOfClass:NSDictionary.class] ? props : nil;
+}
+
+- (NSArray<NSString *> *)functions {
+    return _type == ANNLayoutTypeExternalComponent ? ANNStrings(_data[@"functions"]) : @[];
+}
+
+// A non-string entry counts as an empty name, so that `columns[i]` still names child i.
+- (NSArray<NSString *> *)columns {
+    id columns = _data[@"columns"];
+    if (![columns isKindOfClass:NSArray.class]) {
+        return @[];
+    }
+    NSMutableArray<NSString *> *names = [NSMutableArray new];
+    for (id column in (NSArray *)columns) {
+        [names addObject:[column isKindOfClass:NSString.class] ? column : @""];
+    }
+    return [names copy];
+}
+
++ (NSArray<NSString *> *)columnNamesOfData:(NSDictionary<NSString *, id> *)data
+                                childCount:(NSUInteger)childCount {
+    id columns = data[@"columns"];
+    NSMutableArray<NSString *> *names = [NSMutableArray new];
+    // One meaning on both platforms: without `columns` (missing, no array, or empty) the first two children are the
+    // primary and the secondary column.
+    if (![columns isKindOfClass:NSArray.class] || [(NSArray *)columns count] == 0) {
+        columns = @[ @"primary", @"secondary" ];
+    }
+    NSMutableSet<NSString *> *taken = [NSMutableSet new];
+    for (NSUInteger index = 0; index < childCount; index++) {
+        id column = index < [(NSArray *)columns count] ? ((NSArray *)columns)[index] : nil;
+        BOOL named = [column isKindOfClass:NSString.class] &&
+                     [ANNKnownColumnNames() containsObject:column] &&
+                     ![taken containsObject:column];
+        if (named) {
+            [taken addObject:column];
+        }
+        [names addObject:named ? column : @""];
+    }
+    return [names copy];
+}
+
+- (NSDictionary<NSString *, ANNLayoutNode *> *)columnChildren {
+    if (_type != ANNLayoutTypeSplitView) {
+        return @{};
+    }
+    NSArray<NSString *> *names = [ANNLayoutNode columnNamesOfData:_data childCount:_children.count];
+    NSMutableDictionary<NSString *, ANNLayoutNode *> *children = [NSMutableDictionary new];
+    for (NSUInteger index = 0; index < names.count; index++) {
+        if (names[index].length > 0) {
+            children[names[index]] = _children[index];
+        }
+    }
+    return [children copy];
+}
+
+#pragma mark - Kinds
+
+- (BOOL)isScreen {
+    return _type == ANNLayoutTypeComponent || _type == ANNLayoutTypeExternalComponent;
+}
+
+- (BOOL)isSideMenuSide {
+    return _type == ANNLayoutTypeSideMenuLeft || _type == ANNLayoutTypeSideMenuCenter ||
+           _type == ANNLayoutTypeSideMenuRight;
+}
+
+- (NSArray<ANNLayoutNode *> *)allNodes {
+    NSMutableArray<ANNLayoutNode *> *nodes = [NSMutableArray arrayWithObject:self];
+    for (ANNLayoutNode *child in _children) {
+        [nodes addObjectsFromArray:child.allNodes];
+    }
+    return [nodes copy];
+}
+
+@end

package/ios/Contract/ANNLayoutReader.h

@@ -0,0 +1,34 @@
+#import "ANNLayoutNode.h"
+#import "ANNLayoutRoot.h"
+#import <Foundation/Foundation.h>
+
+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).
+///
+/// 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`
+/// that is a non-empty string, the node's place under its parent (then a side only directly under a side menu), an id
+/// no other node of the layout has, a screen's `data.name` and a native screen's registration, the node's rules on the
+/// number of its children, each child whole, then its rules over the children's types (the sides of a side menu, the
+/// columns of a split view). The id of a node is taken as it is; fields the contract doesn't have are left alone.
+@interface ANNLayoutReader : NSObject
+
+/// One node with its tree: the layout of `push`, `showModal`, `showOverlay`, `showInColumn`. Nil and the text of the
+/// first error when it doesn't pass.
++ (nullable ANNLayoutNode *)nodeFrom:(nullable id)json error:(NSString *_Nullable *_Nonnull)error;
+
+/// The layout of `setRoot`: `{ root, modals, overlays }`, one layout for the check of ids.
++ (nullable ANNLayoutRoot *)rootFrom:(nullable id)json error:(NSString *_Nullable *_Nonnull)error;
+
+/// The layout of `setStackRoot`: the screens from the bottom up, one layout for the check of ids. Empty when JS sent
+/// none: the command rejects that with the id of its screen.
++ (nullable NSArray<ANNLayoutNode *> *)nodesFrom:(nullable id)json
+                                           error:(NSString *_Nullable *_Nonnull)error;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Contract/ANNLayoutReader.mm

@@ -0,0 +1,282 @@
+#import "ANNLayoutReader.h"
+#import "ANNArrangementState.h"
+#import "ANNErrorTexts.h"
+#import "ApexNavigation+Internal.h"
+
+// Where a node stands: what its parent is, for the rules of its place. Nil parent: a root, a modal, an overlay, the
+// node of a command, an entry of `setStackRoot`.
+@interface ANNLayoutPlace : NSObject
+@property(nonatomic) ANNLayoutType parentType;
+@property(nonatomic, copy) NSString *parentId;
+// The side menu of a side, for a child of that side.
+@property(nonatomic, copy) NSString *menuId;
+// The column a child of a split view is, `''` when it is none.
+@property(nonatomic, copy) NSString *column;
+@end
+
+@implementation ANNLayoutPlace
+@end
+
+@implementation ANNLayoutReader
+
+#pragma mark - Commands
+
++ (ANNLayoutNode *)nodeFrom:(id)json error:(NSString **)error {
+    return [self read:json place:nil ids:[NSMutableSet new] error:error];
+}
+
+// The root, then each modal, then each overlay; one layout for the ids.
++ (ANNLayoutRoot *)rootFrom:(id)json error:(NSString **)error {
+    NSDictionary *layout = [json isKindOfClass:NSDictionary.class] ? json : nil;
+    id rootJson = layout[@"root"];
+    if (![rootJson isKindOfClass:NSDictionary.class]) {
+        *error = ANNErrorTexts.rootMissing;
+        return nil;
+    }
+    NSMutableSet<NSString *> *ids = [NSMutableSet new];
+    ANNLayoutNode *root = [self read:rootJson place:nil ids:ids error:error];
+    if (!root) {
+        return nil;
+    }
+    NSArray<ANNLayoutNode *> *modals = [self readList:layout[@"modals"] ids:ids error:error];
+    if (!modals) {
+        return nil;
+    }
+    NSArray<ANNLayoutNode *> *overlays = [self readList:layout[@"overlays"] ids:ids error:error];
+    if (!overlays) {
+        return nil;
+    }
+    return [[ANNLayoutRoot alloc] initWithRoot:root modals:modals overlays:overlays];
+}
+
++ (NSArray<ANNLayoutNode *> *)nodesFrom:(id)json error:(NSString **)error {
+    return [self readList:json ids:[NSMutableSet new] error:error];
+}
+
+// A list that is missing or no array is empty.
++ (NSArray<ANNLayoutNode *> *)readList:(id)json
+                                   ids:(NSMutableSet<NSString *> *)ids
+                                 error:(NSString **)error {
+    if (![json isKindOfClass:NSArray.class]) {
+        return @[];
+    }
+    NSMutableArray<ANNLayoutNode *> *nodes = [NSMutableArray new];
+    for (id item in (NSArray *)json) {
+        ANNLayoutNode *node = [self read:item place:nil ids:ids error:error];
+        if (!node) {
+            return nil;
+        }
+        [nodes addObject:node];
+    }
+    return [nodes copy];
+}
+
+#pragma mark - One node
+
+// One pass, depth first, in the order both platforms check: the node's type and id, its place under its parent, its id
+// against the others, a screen's name and registration, its rules on the number of children, each child whole, then its
+// rules over the children's types. The first error is the text.
++ (ANNLayoutNode *)read:(id)json
+                  place:(ANNLayoutPlace *)place
+                    ids:(NSMutableSet<NSString *> *)ids
+                  error:(NSString **)error {
+    // 1. A known type: a node that is no object, or has no string type, gives ''.
+    NSDictionary *object = [json isKindOfClass:NSDictionary.class] ? json : nil;
+    id typeName = object[@"type"];
+    ANNLayoutType type = ANNLayoutTypeFromName(typeName);
+    if (type == ANNLayoutTypeUnknown) {
+        BOOL named = [typeName isKindOfClass:NSString.class];
+        *error = [ANNErrorTexts unknownNodeType:named ? typeName : @""];
+        return nil;
+    }
+    NSString *name = ANNLayoutTypeName(type);
+    // 2. The id, taken as it is.
+    id nodeIdValue = object[@"id"];
+    if (![nodeIdValue isKindOfClass:NSString.class] || [(NSString *)nodeIdValue length] == 0) {
+        *error = [ANNErrorTexts nodeWithoutId:name];
+        return nil;
+    }
+    NSString *nodeId = nodeIdValue;
+    // 3. The place.
+    NSString *text = [self checkPlaceOf:type nodeId:nodeId place:place];
+    // 4. One id goes to one node of the layout; the ids of the sides count too (JS makes them unique).
+    if (!text && [ids containsObject:nodeId]) {
+        text = [ANNErrorTexts idGivenTwice:nodeId];
+    }
+    [ids addObject:nodeId];
+    // `data` and `children` of the wrong kind count as missing.
+    NSDictionary *data = [object[@"data"] isKindOfClass:NSDictionary.class] ? object[@"data"] : @{};
+    BOOL screen = type == ANNLayoutTypeComponent || type == ANNLayoutTypeExternalComponent;
+    id childrenValue = object[@"children"];
+    NSArray *childrenJson = [childrenValue isKindOfClass:NSArray.class] ? childrenValue : @[];
+    // 5. A screen; its children are never read.
+    if (!text && screen) {
+        text = [self checkScreen:type nodeId:nodeId data:data];
+    }
+    // 6. The number of children.
+    if (!text && !screen) {
+        text = [self checkCountOf:type nodeId:nodeId count:childrenJson.count place:place];
+    }
+    if (text) {
+        *error = text;
+        return nil;
+    }
+    // 7. Each child whole.
+    NSMutableArray<ANNLayoutNode *> *children = [NSMutableArray new];
+    if (!screen) {
+        NSArray<NSString *> *columns = type == ANNLayoutTypeSplitView
+                                           ? [ANNLayoutNode columnNamesOfData:data
+                                                                   childCount:childrenJson.count]
+                                           : nil;
+        for (NSUInteger index = 0; index < childrenJson.count; index++) {
+            ANNLayoutPlace *childPlace = [ANNLayoutPlace new];
+            childPlace.parentType = type;
+            childPlace.parentId = nodeId;
+            BOOL inSide = place.parentType == ANNLayoutTypeSideMenuRoot;
+            childPlace.menuId = inSide ? place.parentId : nil;
+            childPlace.column = columns[index];
+            ANNLayoutNode *child = [self read:childrenJson[index]
+                                        place:childPlace
+                                          ids:ids
+                                        error:error];
+            if (!child) {
+                return nil;
+            }
+            [children addObject:child];
+        }
+    }
+    ANNLayoutNode *node = [[ANNLayoutNode alloc] initWithNodeId:nodeId
+                                                           type:type
+                                                           data:data
+                                                       children:children];
+    // 8. The children's types.
+    text = [self checkChildTypesOf:node];
+    if (text) {
+        *error = text;
+        return nil;
+    }
+    return node;
+}
+
+#pragma mark - The rules
+
+// What the parent takes in this place: a "no" of the table is a rejection, a case it leaves undescribed is not. Then a
+// side stands only directly under a side menu.
++ (NSString *)checkPlaceOf:(ANNLayoutType)type
+                    nodeId:(NSString *)nodeId
+                     place:(ANNLayoutPlace *)place {
+    NSString *typeName = ANNLayoutTypeName(type);
+    BOOL screen = type == ANNLayoutTypeComponent || type == ANNLayoutTypeExternalComponent;
+    BOOL side = type == ANNLayoutTypeSideMenuLeft || type == ANNLayoutTypeSideMenuCenter ||
+                type == ANNLayoutTypeSideMenuRight;
+    if (place) {
+        NSString *parentId = place.parentId;
+        switch (place.parentType) {
+        case ANNLayoutTypeStack:
+            if (!screen && type != ANNLayoutTypeArrangement) {
+                return [ANNErrorTexts stackTakesScreens:parentId type:typeName];
+            }
+            break;
+        case ANNLayoutTypeBottomTabs:
+            if (type == ANNLayoutTypeBottomTabs) {
+                return [ANNErrorTexts tabsInTabs:parentId];
+            }
+            break;
+        case ANNLayoutTypeSideMenuRoot:
+            if (!side) {
+                return [ANNErrorTexts sideMenuChild:parentId type:typeName];
+            }
+            break;
+        case ANNLayoutTypeSideMenuLeft:
+        case ANNLayoutTypeSideMenuCenter:
+        case ANNLayoutTypeSideMenuRight:
+            if (type == ANNLayoutTypeSideMenuRoot) {
+                return [ANNErrorTexts sideMenuInSide:place.menuId ?: @""];
+            }
+            break;
+        case ANNLayoutTypeSplitView:
+            if (place.column.length > 0 && type == ANNLayoutTypeSplitView) {
+                return [ANNErrorTexts splitViewInColumn:parentId];
+            }
+            break;
+        case ANNLayoutTypeArrangement:
+            if (!screen) {
+                return [ANNErrorTexts pairNeedsTwoScreens:parentId];
+            }
+            break;
+        default:
+            break;
+        }
+    }
+    if (side && place.parentType != ANNLayoutTypeSideMenuRoot) {
+        return [ANNErrorTexts sideOutsideMenu:nodeId type:typeName];
+    }
+    return nil;
+}
+
+// A `Component` named `slot:<Name>` is a screen like any other here. A native screen's name must be registered:
+// the registry has its own lock, as an app may register from any thread.
++ (NSString *)checkScreen:(ANNLayoutType)type nodeId:(NSString *)nodeId data:(NSDictionary *)data {
+    NSString *name = [data[@"name"] isKindOfClass:NSString.class] ? data[@"name"] : nil;
+    if (name.length == 0) {
+        return [ANNErrorTexts nodeWithoutName:ANNLayoutTypeName(type) nodeId:nodeId];
+    }
+    BOOL external = type == ANNLayoutTypeExternalComponent;
+    if (external && ![ApexNavigation hasNativeScreenNamed:name]) {
+        return [ANNErrorTexts nativeScreenNotRegistered:name];
+    }
+    return nil;
+}
+
+// iOS shows more than five tabs (the More tab on iPhone): only Android rejects them. A pair needs iOS 27.1 and the
+// SDK it came with; it is checked first, as no pair shows without it.
++ (NSString *)checkCountOf:(ANNLayoutType)type
+                    nodeId:(NSString *)nodeId
+                     count:(NSUInteger)count
+                     place:(ANNLayoutPlace *)place {
+    switch (type) {
+    case ANNLayoutTypeArrangement:
+        if (!ANNArrangementState.canShowArrangements) {
+            return [ANNErrorTexts pairUnsupported:nodeId];
+        }
+        return count != 2 ? [ANNErrorTexts pairNeedsTwoScreens:nodeId] : nil;
+    case ANNLayoutTypeStack:
+        return count == 0 ? [ANNErrorTexts emptyStack:nodeId] : nil;
+    case ANNLayoutTypeBottomTabs:
+        return count == 0 ? [ANNErrorTexts emptyTabs:nodeId] : nil;
+    case ANNLayoutTypeSideMenuLeft:
+    case ANNLayoutTypeSideMenuCenter:
+    case ANNLayoutTypeSideMenuRight:
+        // A side outside a side menu failed on its place already.
+        if (count != 1) {
+            return [ANNErrorTexts sideChildCount:nodeId menuId:place.parentId ?: @""];
+        }
+        return nil;
+    default:
+        return nil;
+    }
+}
+
+// One center, at most one left and one right; a primary and a secondary column.
++ (NSString *)checkChildTypesOf:(ANNLayoutNode *)node {
+    if (node.type == ANNLayoutTypeSideMenuRoot) {
+        NSUInteger centers = 0, lefts = 0, rights = 0;
+        for (ANNLayoutNode *side in node.children) {
+            centers += side.type == ANNLayoutTypeSideMenuCenter;
+            lefts += side.type == ANNLayoutTypeSideMenuLeft;
+            rights += side.type == ANNLayoutTypeSideMenuRight;
+        }
+        if (centers != 1 || lefts > 1 || rights > 1) {
+            return [ANNErrorTexts sideMenuSides:node.nodeId];
+        }
+    }
+    if (node.type == ANNLayoutTypeSplitView) {
+        NSDictionary<NSString *, ANNLayoutNode *> *columns = node.columnChildren;
+        if (!columns[@"primary"] || !columns[@"secondary"]) {
+            return [ANNErrorTexts splitViewColumns:node.nodeId];
+        }
+    }
+    return nil;
+}
+
+@end

package/ios/Contract/ANNLayoutRoot.h

@@ -0,0 +1,26 @@
+#import "ANNLayoutNode.h"
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The layout of `setRoot`, read and checked: the new root, then the modals to show over it in order, then the
+/// overlays. Immutable.
+@interface ANNLayoutRoot : NSObject
+
+- (instancetype)initWithRoot:(ANNLayoutNode *)root
+                      modals:(NSArray<ANNLayoutNode *> *)modals
+                    overlays:(NSArray<ANNLayoutNode *> *)overlays NS_DESIGNATED_INITIALIZER;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+@property(nonatomic, strong, readonly) ANNLayoutNode *root;
+@property(nonatomic, copy, readonly) NSArray<ANNLayoutNode *> *modals;
+@property(nonatomic, copy, readonly) NSArray<ANNLayoutNode *> *overlays;
+
+/// The root, the modals and the overlays, in that order.
+- (NSArray<ANNLayoutNode *> *)trees;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Contract/ANNLayoutRoot.mm

@@ -0,0 +1,21 @@
+#import "ANNLayoutRoot.h"
+
+@implementation ANNLayoutRoot
+
+- (instancetype)initWithRoot:(ANNLayoutNode *)root
+                      modals:(NSArray<ANNLayoutNode *> *)modals
+                    overlays:(NSArray<ANNLayoutNode *> *)overlays {
+    if (self = [super init]) {
+        _root = root;
+        _modals = [modals copy];
+        _overlays = [overlays copy];
+    }
+    return self;
+}
+
+- (NSArray<ANNLayoutNode *> *)trees {
+    NSArray<ANNLayoutNode *> *trees = [@[ _root ] arrayByAddingObjectsFromArray:_modals];
+    return [trees arrayByAddingObjectsFromArray:_overlays];
+}
+
+@end

package/ios/Contract/ANNLayoutTreeOptions.h

@@ -0,0 +1,22 @@
+#import "ANNLayoutNode.h"
+#import "ANNNavigationOptions.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The options of a command's layout, read on the main queue before any view is made. Every command with a layout calls
+/// it first: node by node, depth first in the order of the layout, so the first unreadable value is the same on iOS and
+/// Android.
+@interface ANNLayoutTreeOptions : NSObject
+
+/// The options of every node of `tree` by its id (the ids of one command are unique). Nil when a value can't be read:
+/// `rejection` gets `unreadableOption(path, nodeId)` of the first one, which the command rejects with.
++ (nullable NSDictionary<NSString *, ANNNavigationOptions *> *)optionsOfTree:(ANNLayoutNode *)tree
+                                                                    rejection:(NSString *_Nullable *_Nonnull)rejection;
+
+/// The same for several trees in order (`setRoot`: the root, the modals, the overlays; `setStackRoot`: its screens).
++ (nullable NSDictionary<NSString *, ANNNavigationOptions *> *)optionsOfTrees:(NSArray<ANNLayoutNode *> *)trees
+                                                                     rejection:(NSString *_Nullable *_Nonnull)rejection;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Contract/ANNLayoutTreeOptions.mm

@@ -0,0 +1,32 @@
+#import "ANNLayoutTreeOptions.h"
+#import "ANNAssert.h"
+#import "ANNErrorTexts.h"
+#import "ANNOptionsReader.h"
+
+@implementation ANNLayoutTreeOptions
+
++ (NSDictionary<NSString *, ANNNavigationOptions *> *)optionsOfTree:(ANNLayoutNode *)tree
+                                                           rejection:(NSString **)rejection {
+    return [self optionsOfTrees:@[ tree ] rejection:rejection];
+}
+
++ (NSDictionary<NSString *, ANNNavigationOptions *> *)optionsOfTrees:(NSArray<ANNLayoutNode *> *)trees
+                                                            rejection:(NSString **)rejection {
+    ANNAssertMainQueue();
+    *rejection = nil;
+    NSMutableDictionary<NSString *, ANNNavigationOptions *> *optionsById = [NSMutableDictionary new];
+    for (ANNLayoutNode *tree in trees) {
+        for (ANNLayoutNode *node in tree.allNodes) {
+            NSString *unreadablePath = nil;
+            ANNNavigationOptions *options = [ANNOptionsReader optionsFrom:node.options unreadablePath:&unreadablePath];
+            if (unreadablePath) {
+                *rejection = [ANNErrorTexts unreadableOption:unreadablePath componentId:node.nodeId];
+                return nil;
+            }
+            optionsById[node.nodeId] = options;
+        }
+    }
+    return optionsById;
+}
+
+@end

package/ios/Contract/ANNLayoutType.h

@@ -0,0 +1,44 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The `type` of a node of the layout JSON. A name the contract doesn't have reads as `ANNLayoutTypeUnknown`, which no
+/// valid layout holds.
+typedef NS_ENUM(NSInteger, ANNLayoutType) {
+    ANNLayoutTypeUnknown = -1,
+    ANNLayoutTypeComponent = 0,
+    ANNLayoutTypeExternalComponent,
+    ANNLayoutTypeStack,
+    ANNLayoutTypeBottomTabs,
+    ANNLayoutTypeSideMenuRoot,
+    ANNLayoutTypeSideMenuLeft,
+    ANNLayoutTypeSideMenuCenter,
+    ANNLayoutTypeSideMenuRight,
+    ANNLayoutTypeSplitView,
+    ANNLayoutTypeArrangement,
+};
+
+/// The names JS sends, in the order of `ANNLayoutType`.
+NS_INLINE NSArray<NSString *> *ANNLayoutTypeNames(void) {
+    return @[
+        @"Component", @"ExternalComponent", @"Stack", @"BottomTabs", @"SideMenuRoot",
+        @"SideMenuLeft", @"SideMenuCenter", @"SideMenuRight", @"SplitView", @"Arrangement"
+    ];
+}
+
+/// The type a name stands for; `ANNLayoutTypeUnknown` for any other value, a non-string too.
+NS_INLINE ANNLayoutType ANNLayoutTypeFromName(id _Nullable name) {
+    if (![name isKindOfClass:NSString.class]) {
+        return ANNLayoutTypeUnknown;
+    }
+    NSUInteger index = [ANNLayoutTypeNames() indexOfObject:name];
+    return index == NSNotFound ? ANNLayoutTypeUnknown : (ANNLayoutType)index;
+}
+
+/// The name JS gives the type; an empty string for `ANNLayoutTypeUnknown`.
+NS_INLINE NSString *ANNLayoutTypeName(ANNLayoutType type) {
+    NSArray<NSString *> *names = ANNLayoutTypeNames();
+    return type >= 0 && (NSUInteger)type < names.count ? names[(NSUInteger)type] : @"";
+}
+
+NS_ASSUME_NONNULL_END

package/ios/Contract/ANNLayoutValidator.h

@@ -0,0 +1,23 @@
+#import "ANNLayoutNode.h"
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The checks of a layout that need what shows now, made by a command on the main queue before it makes any view. Each
+/// command calls those it needs. Main queue.
+@interface ANNLayoutValidator : NSObject
+
+/// The first id of the tree, depth first, that names a node the app has already (shown, or made and waiting to
+/// show) and that `allowed` doesn't excuse; nil when there is none. The sides of side menus don't count: they are
+/// places, not nodes. The command rejects with `[ANNErrorTexts alreadyShown:]`: `push`, `showModal`, `setRoot` (against
+/// the modals and overlays that stay), `setStackRoot` (the ids of its own stack allowed).
++ (nullable NSString *)firstShownIdIn:(ANNLayoutNode *)tree
+                              allowed:(nullable BOOL (^)(ANNLayoutNode *node))allowed;
+
+/// The text when the stack `stackId` can't take the node a `push` or `setStackRoot` brings: anything but a screen or
+/// a pair. Nil when it can.
++ (nullable NSString *)checkStackChild:(ANNLayoutNode *)node stackId:(NSString *)stackId;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Contract/ANNLayoutValidator.mm

@@ -0,0 +1,28 @@
+#import "ANNLayoutValidator.h"
+#import "ANNAssert.h"
+#import "ANNErrorTexts.h"
+#import "ANNNodeRegistry.h"
+
+@implementation ANNLayoutValidator
+
++ (NSString *)firstShownIdIn:(ANNLayoutNode *)tree allowed:(BOOL (^)(ANNLayoutNode *node))allowed {
+    ANNAssertMainQueue();
+    for (ANNLayoutNode *node in tree.allNodes) {
+        if (node.isSideMenuSide || ![ANNNodeRegistry nodeForComponentId:node.nodeId]) {
+            continue;
+        }
+        if (!allowed || !allowed(node)) {
+            return node.nodeId;
+        }
+    }
+    return nil;
+}
+
++ (NSString *)checkStackChild:(ANNLayoutNode *)node stackId:(NSString *)stackId {
+    if (node.isScreen || node.type == ANNLayoutTypeArrangement) {
+        return nil;
+    }
+    return [ANNErrorTexts stackTakesScreens:stackId type:node.typeName];
+}
+
+@end