@tileflow/react-native 0.0.0-bootstrap.0 → 0.1.0-alpha.0

package/ios/TFNativeDocumentRegistry.h

@@ -0,0 +1,28 @@
+#import "TFAdmissionEngine.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface TFNativeDocumentScope : NSObject
+@property (nonatomic, readonly, copy) NSString *context;
+@property (nonatomic, readonly, copy) TFAdmissionStartGuard active;
+@property (nonatomic, readonly, copy) TFAdmissionDelegate load;
+- (instancetype)initWithContext:(NSString *)context active:(TFAdmissionStartGuard)active load:(TFAdmissionDelegate)load;
+@end
+
+typedef id<TFAdmissionCancel> _Nonnull (^TFNativeDocumentLoad)(NSURLRequest *request, TFNativeDocumentScope *_Nullable scope, TFAdmissionStartGuard guard, TFAdmissionNetworkCompletion completion);
+
+// Calls are serialized on the native scheduler; only liveness is read by the network guard.
+@interface TFNativeDocumentRegistry : NSObject
+- (instancetype)initWithScheduler:(id<TFAdmissionScheduler>)scheduler load:(TFNativeDocumentLoad)load;
+- (NSString *)open:(NSURLRequest *)request maximumBytes:(NSUInteger)maximumBytes scope:(nullable TFNativeDocumentScope *)scope;
+- (NSString *)open:(NSURLRequest *)request maximumBytes:(NSUInteger)maximumBytes scope:(nullable TFNativeDocumentScope *)scope developmentOrigin:(nullable NSString *)developmentOrigin;
+- (void)response:(NSString *)identifier completion:(void (^)(NSDictionary *_Nullable header))completion;
+- (NSDictionary *)chunk:(NSString *)identifier maximumBytes:(NSUInteger)maximumBytes;
+- (void)cancel:(NSString *)identifier;
+- (void)retireContext:(NSString *)context;
+- (void)retireProtected;
+- (void)lifecycle:(BOOL)foreground;
+- (void)close;
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/TFNativeDocumentRegistry.mm

@@ -0,0 +1,193 @@
+#import "TFNativeDocumentRegistry.h"
+#import "TFDocumentBounds.h"
+#import "TFNativeDocumentURL.h"
+#import <atomic>
+
+static void TFDocumentInvalid(void) {
+	@throw [NSException exceptionWithName:@"TFNativeDocumentInvalid" reason:@"Native document acquisition failed." userInfo:nil];
+}
+
+@implementation TFNativeDocumentScope
+- (instancetype)initWithContext:(NSString *)context active:(TFAdmissionStartGuard)active load:(TFAdmissionDelegate)load {
+	if ((self = [super init])) {
+		if (!TFAdmissionValidToken(context) || !active || !load) TFDocumentInvalid();
+		_context = [context copy]; _active = [active copy]; _load = [load copy];
+	}
+	return self;
+}
+- (NSString *)description { return @"TFNativeDocumentScope(redacted)"; }
+@end
+
+@interface TFNativeDocumentWork : NSObject { @public std::atomic_bool live; }
+@property (nonatomic, copy) NSString *identifier;
+@property (nonatomic, copy) NSString *origin;
+@property (nonatomic, copy, nullable) NSString *developmentOrigin;
+@property (nonatomic, copy) NSURLRequest *request;
+@property (nonatomic, strong, nullable) TFNativeDocumentScope *scope;
+@property (nonatomic) NSUInteger maximumBytes;
+@property (nonatomic) NSTimeInterval deadline;
+@property (nonatomic) BOOL nativeFinished;
+@property (nonatomic) BOOL requested;
+@property (nonatomic) NSUInteger offset;
+@property (nonatomic) NSUInteger revision;
+@property (nonatomic) NSUInteger redirects;
+@property (nonatomic, strong, nullable) id<TFAdmissionCancel> cancellation;
+@property (nonatomic, strong, nullable) id<TFAdmissionCancel> timer;
+@property (nonatomic, strong, nullable) NSMutableData *body;
+@property (nonatomic, copy, nullable) NSDictionary *header;
+@property (nonatomic, copy, nullable) void (^waiter)(NSDictionary *_Nullable);
+@end
+@implementation TFNativeDocumentWork
+- (instancetype)init { if ((self = [super init])) live.store(true); return self; }
+- (NSString *)description { return @"TFNativeDocumentWork(redacted)"; }
+@end
+
+@interface TFNativeDocumentRegistry () {
+	std::atomic_bool _foreground;
+	std::atomic_bool _closed;
+}
+@property (nonatomic, strong) id<TFAdmissionScheduler> scheduler;
+@property (nonatomic, copy) TFNativeDocumentLoad load;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, TFNativeDocumentWork *> *work;
+@end
+@implementation TFNativeDocumentRegistry
+- (instancetype)initWithScheduler:(id<TFAdmissionScheduler>)scheduler load:(TFNativeDocumentLoad)load {
+	if ((self = [super init])) {
+		if (!scheduler || !load) TFDocumentInvalid();
+		_scheduler = scheduler; _load = [load copy]; _work = [NSMutableDictionary dictionary];
+		_foreground.store(true); _closed.store(false);
+	}
+	return self;
+}
+- (BOOL)active:(TFNativeDocumentWork *)work {
+	@try {
+		return work->live.load() && !self->_closed.load() && self->_foreground.load() &&
+			[self.scheduler nowMs] < work.deadline && (!work.scope || work.scope.active());
+	} @catch (NSException *exception) { return NO; }
+}
+- (NSString *)open:(NSURLRequest *)request maximumBytes:(NSUInteger)maximumBytes scope:(TFNativeDocumentScope *)scope {
+	return [self open:request maximumBytes:maximumBytes scope:scope developmentOrigin:nil];
+}
+- (NSString *)open:(NSURLRequest *)request maximumBytes:(NSUInteger)maximumBytes scope:(TFNativeDocumentScope *)scope developmentOrigin:(NSString *)developmentOrigin {
+	if (scope && developmentOrigin) TFDocumentInvalid();
+	TFNativeDocumentCleanURL(request.URL.absoluteString, developmentOrigin);
+	if (self->_closed.load() || !self->_foreground.load() || self.work.count >= 16 || maximumBytes < 1 || maximumBytes > 8388608 ||
+		![request.HTTPMethod isEqual:@"GET"] || request.HTTPBody || request.HTTPBodyStream || request.allHTTPHeaderFields.count ||
+		(scope && !scope.active())) TFDocumentInvalid();
+	TFNativeDocumentWork *work = [TFNativeDocumentWork new];
+	work.identifier = NSUUID.UUID.UUIDString;
+	work.origin = TFNativeDocumentOrigin(request.URL.absoluteString);
+	work.developmentOrigin = developmentOrigin;
+	work.maximumBytes = maximumBytes; work.scope = scope; work.deadline = [self.scheduler nowMs] + 30000;
+	NSMutableURLRequest *copy = [request mutableCopy];
+	copy.timeoutInterval = 30; copy.cachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
+	copy.HTTPShouldHandleCookies = NO;
+	TFDocumentSetByteLimit(copy, maximumBytes);
+	work.request = copy;
+	self.work[work.identifier] = work;
+	work.timer = [self.scheduler after:30000 perform:^{ [self retireQuietly:work.identifier]; }];
+	[self issue:work];
+	return work.identifier;
+}
+- (void)issue:(TFNativeDocumentWork *)work {
+	if (![self active:work]) { [self retireQuietly:work.identifier]; return; }
+	NSUInteger revision = ++work.revision;
+	work.nativeFinished = NO;
+	@try {
+		id<TFAdmissionCancel> cancellation = self.load(work.request, work.scope, ^BOOL { return [self active:work]; }, ^(NSHTTPURLResponse *response, NSData *body) {
+			[self.scheduler enqueue:^{
+				if (revision != work.revision || work.nativeFinished) return;
+				work.nativeFinished = YES;
+				[self received:work response:response body:body];
+			}];
+		});
+		if (!cancellation) TFDocumentInvalid();
+		work.cancellation = cancellation;
+		if (!work->live.load()) [self retireQuietly:work.identifier];
+	} @catch (NSException *exception) {
+		// A throwing adapter might already have queued work. Retain the bounded
+		// reservation until its completion rather than manufacturing capacity.
+		[self retireQuietly:work.identifier];
+	}
+}
+- (void)received:(TFNativeDocumentWork *)work response:(NSHTTPURLResponse *)response body:(NSData *)body {
+	if (![self active:work] || !response || !body || response.statusCode < 100 || response.statusCode > 599 || body.length > work.maximumBytes) {
+		[self retireQuietly:work.identifier]; return;
+	}
+	NSString *url = response.URL.absoluteString;
+	@try {
+		TFNativeDocumentCleanURL(url, work.developmentOrigin);
+		if (![TFNativeDocumentOrigin(url) isEqual:work.origin]) TFDocumentInvalid();
+		if (!work.scope && [@[@301, @302, @303, @307, @308] containsObject:@(response.statusCode)]) {
+			NSString *location = [response valueForHTTPHeaderField:@"Location"];
+			if (++work.redirects > 3 || ![location isKindOfClass:NSString.class] || !location.length || location.length > 2048 || [location containsString:@"\\"]) TFDocumentInvalid();
+			NSURL *target = [NSURL URLWithString:location relativeToURL:response.URL].absoluteURL;
+			TFNativeDocumentCleanURL(target.absoluteString, work.developmentOrigin);
+			if (![TFNativeDocumentOrigin(target.absoluteString) isEqual:work.origin]) TFDocumentInvalid();
+			NSMutableURLRequest *next = [work.request mutableCopy]; next.URL = target;
+			next.timeoutInterval = MAX(0.001, (work.deadline - [self.scheduler nowMs]) / 1000);
+			work.request = next; work.cancellation = nil;
+			[self issue:work]; return;
+		}
+	} @catch (NSException *exception) { [self retireQuietly:work.identifier]; return; }
+	work.body = [body mutableCopy];
+	work.header = @{@"url": [url copy], @"status": @(response.statusCode)};
+	void (^waiter)(NSDictionary *) = work.waiter; work.waiter = nil;
+	if (waiter) waiter(work.header);
+}
+- (void)response:(NSString *)identifier completion:(void (^)(NSDictionary *_Nullable))completion {
+	TFNativeDocumentWork *work = self.work[identifier];
+	if (!work || ![self active:work] || work.requested) { completion(nil); return; }
+	work.requested = YES;
+	if (work.header) completion(work.header);
+	else work.waiter = completion;
+}
+- (NSDictionary *)chunk:(NSString *)identifier maximumBytes:(NSUInteger)maximumBytes {
+	TFNativeDocumentWork *work = self.work[identifier];
+	if (!work || ![self active:work] || !work.requested || !work.body || maximumBytes < 1 || maximumBytes > 65536) {
+		[self retireQuietly:identifier]; TFDocumentInvalid();
+	}
+	NSUInteger length = MIN(maximumBytes, work.body.length - work.offset);
+	NSData *bytes = [work.body subdataWithRange:NSMakeRange(work.offset, length)];
+	NSString *encoded = [bytes base64EncodedStringWithOptions:0];
+	work.offset += length;
+	BOOL last = work.offset == work.body.length;
+	if (last) [self cancel:identifier];
+	return @{@"bodyBase64": encoded, @"last": @(last)};
+}
+- (void)cancel:(NSString *)identifier {
+	if (!TFAdmissionValidToken(identifier)) TFDocumentInvalid();
+	TFNativeDocumentWork *work = self.work[identifier];
+	if (!work) return;
+	work->live.store(false);
+	[work.timer cancel]; work.timer = nil;
+	void (^waiter)(NSDictionary *) = work.waiter; work.waiter = nil;
+	[work.body resetBytesInRange:NSMakeRange(0, work.body.length)]; work.body = nil; work.header = nil;
+	@try {
+		if (!work.nativeFinished) [work.cancellation cancel];
+		work.cancellation = nil;
+	} @finally {
+		if (work.nativeFinished) [self.work removeObjectForKey:identifier];
+		if (waiter) waiter(nil);
+	}
+}
+- (void)retireQuietly:(NSString *)identifier {
+	@try { [self cancel:identifier]; }
+	@catch (NSException *exception) { /* Retain failed physical cleanup; continue logical retirement. */ }
+}
+- (void)retireContext:(NSString *)context {
+	for (TFNativeDocumentWork *work in self.work.allValues) if ([work.scope.context isEqual:context]) [self retireQuietly:work.identifier];
+}
+- (void)retireProtected {
+	for (TFNativeDocumentWork *work in self.work.allValues) if (work.scope) [self retireQuietly:work.identifier];
+}
+- (void)lifecycle:(BOOL)foreground {
+	self->_foreground.store(foreground);
+	if (!foreground) for (NSString *identifier in self.work.allKeys) [self retireQuietly:identifier];
+}
+- (void)close {
+	self->_closed.store(true);
+	for (NSString *identifier in self.work.allKeys) [self retireQuietly:identifier];
+}
+- (NSString *)description { return @"TFNativeDocumentRegistry(redacted)"; }
+@end

package/ios/TFNativeDocumentURL.h

@@ -0,0 +1,6 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+NSString *TFNativeDocumentCleanURL(NSString *url, NSString *_Nullable developmentOrigin);
+NSString *TFNativeDocumentOrigin(NSString *url);
+NS_ASSUME_NONNULL_END

package/ios/TFNativeSurfaceState.h

@@ -0,0 +1,28 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// UI-queue confined. Native object identity, not a delayed JS callback, binds frame evidence.
+@interface TFNativeSurfaceState : NSObject
+@property (nonatomic, readonly) BOOL active;
+@property (nonatomic, readonly) NSUInteger pendingCount;
+@property (nonatomic, readonly, nullable) NSNumber *awaitingSequence;
+- (instancetype)initWithSurface:(NSString *)surface emit:(void (^)(NSDictionary *event))emit;
+- (void)expect:(NSString *)token;
+- (void)layout:(BOOL)visible;
+- (void)loaded:(NSString *)token identity:(id)identity;
+- (NSUInteger)commit:(NSString *)token;
+- (void)request:(NSString *)token;
+- (void)frameStart:(nullable id)identity;
+- (void)frameEnd:(nullable id)identity fully:(BOOL)fully;
+- (NSUInteger)beginCommand:(NSUInteger)command;
+- (void)cancelCommand:(NSUInteger)command;
+- (void)gestureStart:(NSDictionary *)view;
+- (void)gestureChange:(NSDictionary *)view;
+- (void)gestureEnd:(NSDictionary *)view;
+- (void)acknowledge:(NSUInteger)sequence;
+- (void)fail;
+- (void)close;
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/TFNativeSurfaceState.mm

@@ -0,0 +1,128 @@
+#import "TFNativeSurfaceState.h"
+#import "TFAdmissionEngine.h"
+
+@interface TFNativeSurfaceState ()
+@property (nonatomic, copy) NSString *surface;
+@property (nonatomic, copy) NSString *token;
+@property (nonatomic, copy) void (^emit)(NSDictionary *);
+@property (nonatomic, strong, nullable) id style;
+@property (nonatomic, strong, nullable) id frame;
+@property (nonatomic) NSUInteger frameLayout;
+@property (nonatomic) NSUInteger layoutEpoch;
+@property (nonatomic) NSUInteger committed;
+@property (nonatomic) NSUInteger requested;
+@property (nonatomic) NSUInteger sequence;
+@property (nonatomic) NSUInteger command;
+@property (nonatomic) NSUInteger gestureSequence;
+@property (nonatomic) NSUInteger gesture;
+@property (nonatomic) BOOL visible;
+@property (nonatomic) BOOL closed;
+@property (nonatomic) BOOL failed;
+@property (nonatomic) BOOL reported;
+@property (nonatomic, strong) NSMutableArray<NSDictionary *> *pending;
+@property (nonatomic, readwrite, nullable) NSNumber *awaitingSequence;
+- (NSUInteger)enqueue:(NSString *)kind fields:(NSDictionary *)fields;
+@end
+
+@implementation TFNativeSurfaceState
+- (instancetype)initWithSurface:(NSString *)surface emit:(void (^)(NSDictionary *))emit {
+	if ((self = [super init])) {
+		_surface = [surface copy]; _emit = [emit copy]; _token = @"";
+		_layoutEpoch = 1; _pending = [NSMutableArray array];
+	}
+	return self;
+}
+- (BOOL)active { return !self.closed && !self.failed; }
+- (NSUInteger)pendingCount { return self.pending.count; }
+- (void)expect:(NSString *)token {
+	if (self.closed || !TFAdmissionValidToken(token)) [self invalid];
+	self.token = token; self.style = nil; self.frame = nil; self.committed = 0;
+	self.requested = 0; self.reported = NO; self.failed = NO; self.gesture = 0;
+}
+- (void)layout:(BOOL)visible {
+	if (self.closed) return;
+	self.visible = visible;
+	if (self.layoutEpoch >= 9007199254740991ULL) { [self fail]; return; }
+	self.layoutEpoch++; self.committed = 0; self.requested = 0; self.frame = nil;
+	self.reported = NO; self.gesture = 0;
+	[self enqueue:@"invalidate" fields:@{}];
+}
+- (void)loaded:(NSString *)token identity:(id)identity {
+	if (!self.active || ![token isEqual:self.token] || self.style == identity) return;
+	self.style = identity; self.requested = 0; self.frame = nil; self.reported = NO;
+	[self enqueue:@"style" fields:@{}];
+}
+- (NSUInteger)commit:(NSString *)token {
+	if (!self.active || !self.visible || ![token isEqual:self.token] || !self.style) [self invalid];
+	self.committed = self.layoutEpoch; self.requested = 0; self.frame = nil; self.reported = NO;
+	return self.committed;
+}
+- (void)request:(NSString *)token {
+	if (!self.active || !self.visible || ![token isEqual:self.token] || !self.style ||
+		self.committed != self.layoutEpoch || self.reported) [self invalid];
+	self.requested = self.layoutEpoch; self.frame = nil;
+}
+- (void)frameStart:(id)identity {
+	self.frame = self.active && self.visible && identity == self.style && self.committed == self.layoutEpoch && self.requested == self.layoutEpoch ? identity : nil;
+	self.frameLayout = self.layoutEpoch;
+}
+- (void)frameEnd:(id)identity fully:(BOOL)fully {
+	id captured = self.frame; self.frame = nil;
+	if (!self.active || self.reported || !self.visible || !fully || !captured ||
+		captured != identity || captured != self.style || self.frameLayout != self.layoutEpoch || self.committed != self.layoutEpoch || self.requested != self.layoutEpoch) return;
+	self.reported = YES; self.requested = 0; [self enqueue:@"render" fields:@{}];
+}
+- (NSUInteger)beginCommand:(NSUInteger)command {
+	if (!self.active || !self.visible || !self.style || self.gesture || command <= self.command || command > 9007199254740991ULL) return 0;
+	self.command = command; self.committed = 0; self.requested = 0; self.frame = nil; self.reported = NO;
+	return [self enqueue:@"invalidate" fields:@{}];
+}
+- (void)cancelCommand:(NSUInteger)command { if (command > self.command && command <= 9007199254740991ULL) self.command = command; }
+- (void)gestureStart:(NSDictionary *)view {
+	if (!self.active || !self.visible || !self.style || self.gesture) return;
+	if (self.gestureSequence >= 9007199254740991ULL) { [self fail]; return; }
+	self.requested = 0; self.frame = nil; self.gesture = ++self.gestureSequence;
+	[self enqueue:@"gesture-start" fields:@{@"gesture": @(self.gesture), @"view": view}];
+}
+- (void)gestureChange:(NSDictionary *)view {
+	if (self.active && self.gesture) [self enqueue:@"gesture-change" fields:@{@"gesture": @(self.gesture), @"view": view}];
+}
+- (void)gestureEnd:(NSDictionary *)view {
+	if (!self.active || !self.gesture) return;
+	NSUInteger completed = self.gesture; self.gesture = 0;
+	[self enqueue:@"gesture-end" fields:@{@"gesture": @(completed), @"view": view}];
+}
+- (void)fail {
+	if (self.closed || self.failed) return;
+	self.failed = YES; self.committed = 0; self.requested = 0; self.frame = nil; self.gesture = 0;
+	[self enqueue:@"error" fields:@{}];
+}
+- (NSUInteger)enqueue:(NSString *)kind fields:(NSDictionary *)fields {
+	if (self.closed || !self.token.length || self.sequence >= 9007199254740991ULL) return 0;
+	NSDictionary *last = self.pending.lastObject;
+	if (([kind isEqual:@"gesture-change"] || [kind isEqual:@"invalidate"]) && [last[@"kind"] isEqual:kind] &&
+		[last[@"style"] isEqual:self.token] && (last[@"gesture"] == fields[@"gesture"] || [last[@"gesture"] isEqual:fields[@"gesture"]])) [self.pending removeLastObject];
+	BOOL overflow = self.pending.count >= 32;
+	if (overflow) {
+		[self.pending removeAllObjects]; self.failed = YES; self.frame = nil; self.committed = 0;
+		self.requested = 0; self.gesture = 0; kind = @"error"; fields = @{};
+	}
+	NSUInteger emitted = ++self.sequence;
+	NSMutableDictionary *event = [@{@"surface": self.surface, @"style": self.token, @"layout": @(self.layoutEpoch), @"sequence": @(emitted), @"kind": kind} mutableCopy];
+	[event addEntriesFromDictionary:fields]; [self.pending addObject:[event copy]]; [self drain];
+	return overflow ? 0 : emitted;
+}
+- (void)drain {
+	if (self.closed || self.awaitingSequence || !self.pending.count) return;
+	NSDictionary *event = self.pending.firstObject; [self.pending removeObjectAtIndex:0];
+	self.awaitingSequence = event[@"sequence"];
+	@try { self.emit(event); } @catch (NSException *exception) { [self close]; }
+}
+- (void)acknowledge:(NSUInteger)sequence {
+	if (!self.awaitingSequence || self.awaitingSequence.unsignedLongLongValue != sequence) return;
+	self.awaitingSequence = nil; [self drain];
+}
+- (void)close { self.closed = YES; self.style = nil; self.frame = nil; self.committed = 0; self.requested = 0; self.gesture = 0; [self.pending removeAllObjects]; self.awaitingSequence = nil; }
+- (NSString *)description { return @"TFNativeSurfaceState"; }
+- (void)invalid { @throw [NSException exceptionWithName:@"TFNativeSurfaceInvalid" reason:@"Native surface operation failed." userInfo:nil]; }
+@end

package/ios/TileflowNativeAdmission.h

@@ -0,0 +1,9 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+@class TFNativeDocumentScope;
+@class TileflowNativeDocuments;
+
+@interface TileflowNativeAdmission : RCTEventEmitter <RCTBridgeModule>
+- (TFNativeDocumentScope *)documentScopeForInstallation:(NSString *)installation context:(NSString *)context documents:(TileflowNativeDocuments *)documents;
+@end

package/ios/TileflowNativeAdmission.mm

@@ -0,0 +1,184 @@
+#import "TileflowNativeAdmission.h"
+#import "TFAdmissionInstallation.h"
+#import "TFAdmissionBootstrap.h"
+#import "TFAdmissionDocumentScope.h"
+#import "TFAdmissionNetwork.h"
+#import "TileflowNativeDocuments.h"
+#import <UIKit/UIKit.h>
+#import <cmath>
+
+@interface TileflowNativeAdmission ()
+@property (nonatomic, strong, nullable) TFAdmissionInstallation *installation;
+@property (nonatomic, strong, nullable) TFAdmissionBootstrap *bootstrapRequests;
+@property (nonatomic, strong, nullable) TFAdmissionURLSessionNetwork *bootstrapNetwork;
+@property (nonatomic, weak, nullable) TileflowNativeDocuments *documents;
+@property (nonatomic, copy, nullable) NSString *lastRemoved;
+@property (nonatomic, copy, nullable) NSDictionary *lastRemoval;
+@property (nonatomic) BOOL observing;
+@property (nonatomic) BOOL invalidated;
+@end
+
+@implementation TileflowNativeAdmission
+RCT_EXPORT_MODULE(TileflowNativeAdmission)
++ (BOOL)requiresMainQueueSetup { return YES; }
+- (dispatch_queue_t)methodQueue { return dispatch_get_main_queue(); }
+- (NSArray<NSString *> *)supportedEvents { return @[@"TileflowNativeAdmissionEvent"]; }
+- (void)startObserving { self.observing = YES; }
+- (void)stopObserving { self.observing = NO; }
+- (instancetype)init {
+	if ((self = [super init])) {
+		NSNotificationCenter *center = NSNotificationCenter.defaultCenter;
+		[center addObserver:self selector:@selector(background:) name:UIApplicationWillResignActiveNotification object:nil];
+		[center addObserver:self selector:@selector(foreground:) name:UIApplicationDidBecomeActiveNotification object:nil];
+	}
+	return self;
+}
+- (void)dealloc { [NSNotificationCenter.defaultCenter removeObserver:self]; }
+
+RCT_REMAP_METHOD(install, installWithResolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	BOOL started = NO;
+	@try {
+		if (self.invalidated || self.installation || !self.observing) [self invalid];
+		started = YES;
+		__weak TileflowNativeAdmission *weakSelf = self;
+		self.installation = [[TFAdmissionInstallation alloc] initWithEmitter:^(NSDictionary *event) {
+			TileflowNativeAdmission *strongSelf = weakSelf;
+			if ([event[@"kind"] isEqual:@"retired"]) {
+				[strongSelf.bootstrapRequests retire:event[@"context"]];
+				[strongSelf.documents retireNativeContext:event[@"context"]];
+			} else if ([event[@"kind"] isEqual:@"ownershipLost"]) {
+				[strongSelf.bootstrapRequests close];
+				[strongSelf.documents retireProtectedDocuments];
+			} else if ([event[@"kind"] isEqual:@"lifecycle"]) [strongSelf.bootstrapRequests lifecycle:[event[@"foreground"] boolValue]];
+			if (!strongSelf || strongSelf.invalidated || !strongSelf.observing) [NSException raise:@"TFNativeAdmissionListener" format:@"Native admission listener is unavailable"];
+			[strongSelf sendEventWithName:@"TileflowNativeAdmissionEvent" body:event];
+		}];
+		self.bootstrapNetwork = [self createBootstrapNetwork];
+		if (!self.installation || !self.bootstrapNetwork) [self invalid];
+		// The network guard may run off the main queue. Capture its original
+		// engine instead of reading the module's mutable installation pointer.
+		TFAdmissionEngine *admission = self.installation.engine;
+		self.bootstrapRequests = [[TFAdmissionBootstrap alloc] initWithInstallation:self.installation.identifier scheduler:[TFContinuousAdmissionScheduler new]
+			network:self.bootstrapNetwork owns:^BOOL { return [admission isOwner]; }];
+		if (!self.bootstrapRequests) [self invalid];
+		[admission lifecycle:UIApplication.sharedApplication.applicationState == UIApplicationStateActive];
+		if (![admission isOwner]) [self invalid];
+		resolve(@{@"installation": self.installation.identifier});
+	} @catch (NSException *exception) {
+		// Do not roll back an existing installation rejected by the guard.
+		if (started) {
+			@try { [self shutdown]; } @catch (NSException *cleanupError) { /* No successful acknowledgement. */ }
+		}
+		[self reject:reject];
+	}
+}
+- (TFAdmissionURLSessionNetwork *)createBootstrapNetwork {
+	NSURLSessionConfiguration *configuration = NSURLSessionConfiguration.ephemeralSessionConfiguration;
+	configuration.protocolClasses = @[];
+	configuration.URLCache = nil; configuration.HTTPCookieStorage = nil; configuration.URLCredentialStorage = nil;
+	configuration.HTTPShouldSetCookies = NO; configuration.HTTPAdditionalHeaders = nil;
+	configuration.requestCachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
+	configuration.HTTPMaximumConnectionsPerHost = 4;
+	return [[TFAdmissionURLSessionNetwork alloc] initWithConfiguration:configuration followsRedirects:NO responseByteLimit:65536 queueDepth:32 concurrency:4];
+}
+RCT_REMAP_METHOD(registerContext, registerInstallation:(NSString *)identifier registration:(NSDictionary *)registration resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		TFAdmissionInstallation *installation = [self current:identifier];
+		if (![registration isKindOfClass:NSDictionary.class] || registration.count > 2) [self invalid];
+		NSString *mapId = registration[@"mapId"] == NSNull.null ? nil : registration[@"mapId"];
+		NSArray *resources = registration[@"resources"];
+		if (![resources isKindOfClass:NSArray.class] || resources.count > 128) [self invalid];
+		NSString *context = [installation.engine registerMap:mapId resources:resources];
+		@try {
+			if (!self.bootstrapRequests) [self invalid];
+			[self.bootstrapRequests registerContext:context mapId:mapId];
+		} @catch (NSException *exception) { [installation.engine retire:context]; @throw; }
+		resolve(@{@"context": context, @"generation": @1});
+	} @catch (NSException *exception) { [self reject:reject]; }
+}
+RCT_REMAP_METHOD(extendContext, extendInstallation:(NSString *)identifier context:(NSString *)context resources:(NSArray<NSDictionary *> *)resources resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		TFAdmissionInstallation *installation = [self current:identifier];
+		if (!TFAdmissionValidToken(context) || ![resources isKindOfClass:NSArray.class] || resources.count > 128) [self invalid];
+		resolve(@{@"resources": @([installation.engine extendContext:context resources:resources])});
+	} @catch (NSException *exception) { [self reject:reject]; }
+}
+- (TFNativeDocumentScope *)documentScopeForInstallation:(NSString *)identifier context:(NSString *)context documents:(TileflowNativeDocuments *)documents {
+	if (!documents || !TFAdmissionValidToken(context)) [self invalid];
+	TFAdmissionInstallation *installation = [self current:identifier];
+	if (self.documents && self.documents != documents) [self invalid];
+	self.documents = documents;
+	return TFCreateAdmissionDocumentScope(installation.engine, context);
+}
+RCT_REMAP_METHOD(retireContext, retireInstallation:(NSString *)identifier context:(NSString *)context resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		if (!TFAdmissionValidToken(context)) [self invalid];
+		if ([self.installation.identifier isEqual:identifier]) {
+			[self.bootstrapRequests retire:context]; [self.installation.engine retire:context];
+		} else if (![self.lastRemoved isEqual:identifier]) [self invalid];
+		resolve(@{@"retired": @YES});
+	} @catch (NSException *exception) { [self reject:reject]; }
+}
+RCT_REMAP_METHOD(bootstrap, bootstrapInstallation:(NSString *)identifier context:(NSString *)context request:(NSString *)request url:(NSString *)url credential:(NSString *)credential body:(NSString *)body resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		[self current:identifier];
+		if (!self.bootstrapRequests) [self invalid];
+		[self.bootstrapRequests startContext:context request:request url:url credential:credential body:body completion:^(NSDictionary *reply) {
+			if (reply) resolve(reply);
+			else reject(@"NATIVE_ADMISSION_UNAVAILABLE", @"Native resource admission failed", nil);
+		}];
+	} @catch (NSException *exception) { [self reject:reject]; }
+}
+RCT_REMAP_METHOD(cancelBootstrap, cancelBootstrapInstallation:(NSString *)identifier context:(NSString *)context request:(NSString *)request resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		if (!TFAdmissionValidToken(context) || !TFAdmissionValidToken(request)) [self invalid];
+		if ([self.installation.identifier isEqual:identifier]) [self.bootstrapRequests cancelContext:context request:request];
+		else if (![self.lastRemoved isEqual:identifier]) [self invalid];
+		resolve(@{@"cancelled": @YES});
+	} @catch (NSException *exception) { [self reject:reject]; }
+}
+RCT_REMAP_METHOD(completeBatch, completeInstallation:(NSString *)identifier context:(NSString *)context generation:(double)generation batch:(NSString *)batch results:(NSArray<NSDictionary *> *)results resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		TFAdmissionInstallation *installation = [self current:identifier];
+		if (!TFAdmissionValidToken(context) || !TFAdmissionValidToken(batch) || generation != 1.0 || ![results isKindOfClass:NSArray.class] || results.count > 8) [self invalid];
+		// Bound the envelope before the engine holds any authority. This data
+		// is ephemeral bridge input, never a log, event, error or snapshot.
+		if (![NSJSONSerialization isValidJSONObject:results]) [self invalid];
+		NSData *wire = [NSJSONSerialization dataWithJSONObject:results options:0 error:nil];
+		if (!wire || wire.length > 524288) [self invalid];
+		NSUInteger accepted = [installation.engine completeContext:context generation:1 batch:batch results:results];
+		resolve(@{@"accepted": @(accepted)});
+	} @catch (NSException *exception) { [self reject:reject]; }
+}
+RCT_REMAP_METHOD(remove, removeInstallation:(NSString *)identifier resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		if (!self.installation && [self.lastRemoved isEqual:identifier]) { resolve(self.lastRemoval); return; }
+		if (![self.installation.identifier isEqual:identifier]) [self invalid];
+		resolve([self shutdown]);
+	} @catch (NSException *exception) { [self reject:reject]; }
+}
+- (NSDictionary *)shutdown {
+	if (!self.installation) return self.lastRemoval ?: @{@"removed": @NO, @"ownershipLost": @NO};
+	[self.bootstrapRequests close]; [self.bootstrapNetwork close];
+	NSDictionary *ack = [self.installation remove];
+	self.lastRemoved = self.installation.identifier; self.lastRemoval = ack;
+	self.installation = nil; self.bootstrapRequests = nil; self.bootstrapNetwork = nil;
+	return ack;
+}
+- (TFAdmissionInstallation *)current:(NSString *)identifier {
+	if (self.invalidated || ![self.installation.identifier isEqual:identifier] || ![self.installation.engine isOwner]) [self invalid];
+	return self.installation;
+}
+- (void)background:(NSNotification *)notification { [self.installation.engine lifecycle:NO]; }
+- (void)foreground:(NSNotification *)notification { [self.installation.engine lifecycle:YES]; }
+- (void)invalidate {
+	[NSNotificationCenter.defaultCenter removeObserver:self];
+	dispatch_async(dispatch_get_main_queue(), ^{
+		self.invalidated = YES;
+		@try { [self shutdown]; } @catch (NSException *exception) { /* Retain failed cleanup for retry. */ }
+	});
+	[super invalidate];
+}
+- (void)reject:(RCTPromiseRejectBlock)reject { reject(@"NATIVE_ADMISSION_UNAVAILABLE", @"Native resource admission failed", nil); }
+- (void)invalid { [NSException raise:@"TFNativeAdmissionInvalid" format:@"Invalid native admission"]; }
+@end

package/ios/TileflowNativeConfiguration.mm

@@ -0,0 +1,41 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTInvalidating.h>
+#import "TFMobileConfiguration.h"
+
+@interface TileflowNativeConfiguration : NSObject <RCTBridgeModule, RCTInvalidating>
+@end
+
+@implementation TileflowNativeConfiguration {
+	BOOL _invalidated;
+}
+RCT_EXPORT_MODULE(TileflowNativeConfiguration)
++ (BOOL)requiresMainQueueSetup { return NO; }
+
+RCT_REMAP_METHOD(readConfiguration,
+	readConfigurationWithResolver:(RCTPromiseResolveBlock)resolve
+	rejecter:(RCTPromiseRejectBlock)reject) {
+	@synchronized (self) {
+		if (_invalidated) {
+			reject(@"NATIVE_CONFIGURATION_UNAVAILABLE", @"Native application configuration is unavailable.", nil);
+			return;
+		}
+		static TFMobileConfigurationCache *applicationConfiguration;
+		static dispatch_once_t once;
+		dispatch_once(&once, ^{ applicationConfiguration = [TFMobileConfigurationCache new]; });
+		TFMobileConfiguration *configuration = [applicationConfiguration read:^{
+			NSBundle *bundle = NSBundle.mainBundle;
+			return [TFMobileConfiguration fromInfo:bundle.infoDictionary localized:bundle.localizedInfoDictionary error:nil];
+		} error:nil];
+		if (!configuration) {
+			reject(@"NATIVE_CONFIGURATION_INVALID", @"Native application configuration is invalid.", nil);
+			return;
+		}
+		// One bounded private promise, never constants, notifications or renderer events.
+		resolve(@{@"apiOrigin": configuration.apiOrigin, @"credential": configuration.credential});
+	}
+}
+
+- (void)invalidate {
+	@synchronized (self) { _invalidated = YES; }
+}
+@end

package/ios/TileflowNativeDocuments.h

@@ -0,0 +1,12 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTInvalidating.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Private preparation channel. Methods are serialized with admission on the main queue.
+@interface TileflowNativeDocuments : NSObject <RCTBridgeModule, RCTInvalidating>
+- (void)retireNativeContext:(NSString *)context;
+- (void)retireProtectedDocuments;
+@end
+
+NS_ASSUME_NONNULL_END