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

package/docs/native-location.md

@@ -0,0 +1,148 @@
+# Application-owned foreground location
+
+`@tileflow/react-native` does not own device location. A Tileflow `Map` renders normally without a
+location permission, provider, hook or native location module. The application decides whether to
+request foreground permission, which provider to use, when observation starts and stops, what fix is
+displayed, whether recentering is offered, and what status or error UI is appropriate.
+
+This guide describes a source-checkout recipe built only from the existing public `Map`, controlled
+camera and annotation contracts. It is not a new Tileflow runtime API and it does not add a location
+provider to the package.
+
+## Boundary
+
+The package deliberately does not provide any of the following:
+
+- a Tileflow location component, hook, provider or permission API;
+- an iOS or Android location permission declaration;
+- a dependency on Expo Location, a geolocation package or another location provider;
+- a background task, background permission or location-history store;
+- a credential/session field for device location;
+- a location analytics event or precise-coordinate telemetry path;
+- a GeoIP fallback for device location;
+- implicit permission requests or tracking when `Map` mounts.
+
+The application must configure any native permission strings, manifest entries and provider setup
+required by the provider it chooses. Those application settings are separate from Tileflow's native
+Hosted credential configuration.
+
+## Source-checkout recipe
+
+`../harness/ForegroundLocationExample.tsx` is a compile-only example owned by this package. Its
+provider boundary is injected:
+
+```ts
+export type ApplicationForegroundLocationAdapter = Readonly<{
+  requestPermission(): Promise<
+    'granted-precise' | 'granted-approximate' | 'denied' | 'unavailable'
+  >;
+  observe(listener: (update: ApplicationLocationObservation) => void): () => void;
+}>;
+```
+
+No concrete provider is imported. The adapter is application code: it translates the provider's
+permission and foreground observation APIs into this small recipe-specific shape. The example and
+its state helper live under `harness/`, are absent from package exports, and are excluded from
+packed runtime files.
+
+## Explicit application state
+
+The recipe models these states without unmounting the Map:
+
+| State                 | Meaning                                                      | Location annotation          |
+| --------------------- | ------------------------------------------------------------ | ---------------------------- |
+| `idle`                | The application has not requested permission.                | none                         |
+| `requesting`          | An explicit application action started a permission request. | none                         |
+| `granted-precise`     | Foreground policy allows precise observation.                | one marker after a valid fix |
+| `granted-approximate` | Foreground policy allows approximate observation.            | one marker after a valid fix |
+| `denied`              | The permission request was denied.                           | none                         |
+| `unavailable`         | Permission/provider setup failed or emitted invalid data.    | none                         |
+| `revoked`             | A previously granted observation reported revocation.        | removed immediately          |
+
+Construction is inert: it neither requests permission nor starts observation. The example's **Use
+my location** control is the only permission-request trigger. A rejected provider promise is reduced
+to the application-level `unavailable` state; raw provider exceptions are not forwarded into Map
+props or Tileflow callbacks.
+
+## Validate before Map props
+
+The adapter output is treated as untrusted runtime data even though the TypeScript adapter is typed.
+The recipe accepts only a plain record with exactly `longitude`, `latitude` and `accuracy` data
+properties. Longitude must be finite and within `[-180, 180]`, latitude finite and within
+`[-90, 90]`, and accuracy finite and nonnegative. Accessors, extra provider fields, invalid
+prototypes and non-finite values fail closed.
+
+Only a validated fix is converted to an annotation:
+
+```ts
+{
+  id: 'application-foreground-location',
+  kind: 'marker',
+  ariaLabel: 'Current location',
+  coordinate: [longitude, latitude],
+  data: {accuracyMeters: accuracy, precision: 'precise'},
+}
+```
+
+Approximate permission uses the same stable ID and an `Approximate current location` label. The
+stable ID lets the existing annotation reconciler update one marker host instead of recreating a
+new marker for every fix. Revocation, denial or provider failure removes the annotation by returning
+an empty annotation collection.
+
+The marker uses the existing accessible Tileflow annotation wrapper. This recipe does not add a
+location-specific native marker component.
+
+## Foreground observation lifetime
+
+Observation starts only when both conditions are true:
+
+1. the application is in the foreground; and
+2. its current permission state is `granted-precise` or `granted-approximate`.
+
+`AppState` is application-side orchestration in the example. Moving to background synchronously
+retires the current observation token and calls the provider cleanup. Returning to foreground
+starts a new observation only if the last application permission policy still allows it. Denied,
+revoked and unavailable states do not restart observation automatically.
+
+The React effect owns a replayable `mount()` epoch. Its cleanup immediately retires the current
+observation and any pending permission/provider callback without terminally disposing the
+controller. A StrictMode setup replay may therefore mount the same controller again; if the retained
+settled permission state is granted and the application is foregrounded, observation restarts
+without another permission prompt. If cleanup interrupted an in-flight permission request, that
+request is retired and the last settled application state is restored instead of accepting its late
+result. A real unmount or adapter replacement uses the same cleanup boundary, so late callbacks are
+inert even though no timing heuristic distinguishes them from a replay. The recipe does not persist
+fixes or observation history.
+
+`dispose()` remains a separate terminal operation for an owner that will never mount again. The
+React example does not use terminal disposal for ordinary effect cleanup.
+
+## Recenter is explicit
+
+A new fix changes only the application-owned annotation. It does **not** change camera state.
+
+The example keeps the existing complete controlled `Map` view. An explicit **Recenter** action copies
+the latest validated coordinate into that controlled view while preserving zoom, bearing and pitch.
+The recipe uses no camera animation API or duration, so it introduces no animated movement for
+reduced-motion users. Applications that later add their own animated camera affordance must apply
+their own reduced-motion policy before doing so.
+
+Gestures continue to update the same controlled view through `onViewChange`; receiving another
+location fix never overwrites that user-driven camera state.
+
+## Privacy and product scope
+
+The sample keeps only the latest in-memory fix needed for its marker. It does not store history,
+send coordinates to analytics, derive a device fix from GeoIP, start background tracking or attach
+location to Tileflow sessions/admission. Status and error presentation are application UI.
+
+Location also does not change the interaction presentation boundary. Tileflow annotations and
+semantic targets remain primitives and data; the application still owns any popup, callout,
+tooltip, sheet, panel, modal or other selection presentation.
+
+## Qualification
+
+The source files describe the intended application contract; they are not evidence that a provider,
+permission prompt, simulator/device scenario, native build, package publication or Hosted service
+was executed. Typecheck the source-checkout harness and qualify the chosen provider in the
+application that owns its permission and privacy policy.

package/ios/TFAdmissionBootstrap.h

@@ -0,0 +1,17 @@
+#import "TFAdmissionEngine.h"
+
+NS_ASSUME_NONNULL_BEGIN
+// All registry mutations use the admission scheduler. Native networking reads
+// only immutable request data, continuous deadlines, and atomic liveness.
+@interface TFAdmissionBootstrap : NSObject
+- (instancetype)initWithInstallation:(NSString *)installation scheduler:(id<TFAdmissionScheduler>)scheduler
+	network:(id<TFAdmissionNetwork>)network owns:(TFAdmissionStartGuard)owns;
+- (void)registerContext:(NSString *)context mapId:(nullable NSString *)mapId;
+- (void)startContext:(NSString *)context request:(NSString *)request url:(NSString *)url
+	credential:(NSString *)credential body:(NSString *)body completion:(void (^)(NSDictionary *_Nullable reply))completion;
+- (void)cancelContext:(NSString *)context request:(NSString *)request;
+- (void)retire:(NSString *)context;
+- (void)lifecycle:(BOOL)foreground;
+- (void)close;
+@end
+NS_ASSUME_NONNULL_END

package/ios/TFAdmissionBootstrap.mm

@@ -0,0 +1,168 @@
+#import "TFAdmissionBootstrap.h"
+#import <atomic>
+
+static void TFBootstrapInvalid(void) {
+	[NSException raise:@"TFNativeBootstrapInvalid" format:@"Invalid native bootstrap"];
+}
+static BOOL TFBootstrapString(id value, NSUInteger limit) { return [value isKindOfClass:NSString.class] && [(NSString *)value length] <= limit; }
+static NSTextCheckingResult *TFBootstrapMatch(NSString *value, NSString *pattern) {
+	NSRegularExpression *expression = [NSRegularExpression regularExpressionWithPattern:pattern options:0 error:nil];
+	NSTextCheckingResult *match = [expression firstMatchInString:value options:0 range:NSMakeRange(0, value.length)];
+	return match && NSEqualRanges(match.range, NSMakeRange(0, value.length)) ? match : nil;
+}
+
+@interface TFBootstrapFlag : NSObject { @public std::atomic_bool value; }
+@end
+@implementation TFBootstrapFlag
+- (instancetype)init { if ((self = [super init])) value.store(true); return self; }
+@end
+
+@class TFBootstrapWork;
+@interface TFBootstrapContext : NSObject
+@property (nonatomic, copy, nullable) NSString *mapId;
+@property (nonatomic, copy, nullable) NSString *endpoint;
+@property (nonatomic, copy, nullable) NSString *credential;
+@property (nonatomic) unsigned long long lastRequest;
+@property (nonatomic) TFBootstrapFlag *alive;
+@property (nonatomic) NSMutableDictionary<NSString *, TFBootstrapWork *> *pending;
+@end
+@implementation TFBootstrapContext
+- (instancetype)init { if ((self = [super init])) { _alive = [TFBootstrapFlag new]; _pending = [NSMutableDictionary dictionary]; } return self; }
+- (NSString *)description { return @"TFBootstrapContext(redacted)"; }
+@end
+
+@interface TFBootstrapWork : NSObject
+@property (nonatomic, copy) NSString *identifier;
+@property (nonatomic) TFBootstrapContext *context;
+@property (nonatomic) TFBootstrapFlag *alive;
+@property (nonatomic) NSTimeInterval deadline;
+@property (nonatomic, copy, nullable) void (^completion)(NSDictionary *_Nullable);
+@property (nonatomic, nullable) id<TFAdmissionCancel> network;
+@property (nonatomic, nullable) id<TFAdmissionCancel> timer;
+@end
+@implementation TFBootstrapWork
+- (NSString *)description { return @"TFBootstrapWork(redacted)"; }
+@end
+
+@interface TFAdmissionBootstrap () {
+	std::atomic_bool _active;
+	std::atomic_bool _foreground;
+}
+@property (nonatomic, copy) NSString *installation;
+@property (nonatomic) id<TFAdmissionScheduler> scheduler;
+@property (nonatomic) id<TFAdmissionNetwork> network;
+@property (nonatomic, copy) TFAdmissionStartGuard owns;
+@property (nonatomic) NSMutableDictionary<NSString *, TFBootstrapContext *> *contexts;
+@property (nonatomic) NSUInteger pendingCount;
+@end
+
+@implementation TFAdmissionBootstrap
+- (instancetype)initWithInstallation:(NSString *)installation scheduler:(id<TFAdmissionScheduler>)scheduler network:(id<TFAdmissionNetwork>)network owns:(TFAdmissionStartGuard)owns {
+	if ((self = [super init])) {
+		_installation = [installation copy]; _scheduler = scheduler; _network = network; _owns = [owns copy];
+		_contexts = [NSMutableDictionary dictionary]; _active.store(true); _foreground.store(true);
+	}
+	return self;
+}
+- (NSString *)description { return @"TFAdmissionBootstrap(redacted)"; }
+- (BOOL)validContext:(NSString *)context { return TFAdmissionValidToken(context) && [context hasPrefix:[self.installation stringByAppendingString:@"."]]; }
+- (unsigned long long)sequence:(NSString *)request {
+	NSString *prefix = [self.installation stringByAppendingString:@"."];
+	if (!TFBootstrapString(request, 96) || ![request hasPrefix:prefix]) TFBootstrapInvalid();
+	NSString *suffix = [request substringFromIndex:prefix.length];
+	if (!TFBootstrapMatch(suffix, @"[1-9][0-9]{0,15}")) TFBootstrapInvalid();
+	unsigned long long value = suffix.longLongValue;
+	if (value > 9007199254740991ULL) TFBootstrapInvalid();
+	return value;
+}
+- (BOOL)owned { @try { return self.owns(); } @catch (NSException *exception) { return NO; } }
+- (void)registerContext:(NSString *)context mapId:(NSString *)mapId {
+	if (!_active.load() || ![self owned] || ![self validContext:context] || self.contexts[context] || self.contexts.count >= 16 ||
+		(mapId && (!TFBootstrapString(mapId, 64) || !TFBootstrapMatch(mapId, @"map_[A-Za-z0-9_-]{16}")))) TFBootstrapInvalid();
+	TFBootstrapContext *binding = [TFBootstrapContext new]; binding.mapId = mapId;
+	self.contexts[context] = binding;
+}
+- (void)startContext:(NSString *)contextId request:(NSString *)requestId url:(NSString *)url credential:(NSString *)credential body:(NSString *)body completion:(void (^)(NSDictionary *))completion {
+	if (![self validContext:contextId]) TFBootstrapInvalid();
+	TFBootstrapContext *context = self.contexts[contextId];
+	if (!_active.load() || !_foreground.load() || ![self owned] || !context || !context.alive->value.load() || !context.mapId || self.pendingCount >= 32) TFBootstrapInvalid();
+	unsigned long long sequence = [self sequence:requestId];
+	if (sequence <= context.lastRequest || !TFBootstrapString(credential, 58) || !TFBootstrapMatch(credential, @"tf_public_[0-9a-f]{48}") || !TFBootstrapString(body, 2048)) TFBootstrapInvalid();
+	NSTextCheckingResult *match = TFBootstrapMatch(body, @"\\{\"mapId\":\"(map_[A-Za-z0-9_-]{16})\",\"sessionId\":\"([A-Za-z0-9._:-]{1,255})\",\"surfaceId\":\"([a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?)\"\\}");
+	if (!match || ![[body substringWithRange:[match rangeAtIndex:1]] isEqual:context.mapId]) TFBootstrapInvalid();
+	for (NSUInteger index = 2; index <= 3; index++) {
+		NSString *value = [body substringWithRange:[match rangeAtIndex:index]];
+		if ([value hasPrefix:@"tf_native_"] || TFBootstrapMatch(value, @"tf_public_[0-9a-f]{48}")) TFBootstrapInvalid();
+	}
+	NSString *clean = TFAdmissionCleanURL(url);
+	if (![clean isEqual:[TFAdmissionOrigin(clean) stringByAppendingString:@"/v1/sessions/start"]] ||
+		(context.endpoint && (![context.endpoint isEqual:clean] || ![context.credential isEqual:credential]))) TFBootstrapInvalid();
+	// The controller supplies the initial validated binding; no later request
+	// may change its exact endpoint, port, or credential for this Map context.
+	context.endpoint = clean; context.credential = credential; context.lastRequest = sequence;
+	TFBootstrapWork *work = [TFBootstrapWork new];
+	work.identifier = requestId; work.context = context; work.alive = [TFBootstrapFlag new];
+	work.deadline = [self.scheduler nowMs] + 30000; work.completion = completion;
+	context.pending[requestId] = work; self.pendingCount++;
+	work.timer = [self.scheduler after:30000 perform:^{ [self finish:work reply:nil]; }];
+	NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:clean]
+		cachePolicy:NSURLRequestReloadIgnoringLocalCacheData timeoutInterval:30];
+	request.HTTPMethod = @"POST"; request.HTTPBody = [body dataUsingEncoding:NSUTF8StringEncoding];
+	request.HTTPShouldHandleCookies = NO;
+	[request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
+	[request setValue:@"no-store" forHTTPHeaderField:@"Cache-Control"];
+	[request setValue:credential forHTTPHeaderField:@"X-Tileflow-Mobile-Client"];
+	@try {
+		work.network = [self.network start:request mayStart:^BOOL { return [self mayStart:work]; } completion:^(NSHTTPURLResponse *response, NSData *bytes) {
+			[self.scheduler enqueue:^{
+				NSString *cacheControl = @"";
+				for (id name in response.allHeaderFields) {
+					if ([name isKindOfClass:NSString.class] && [(NSString *)name caseInsensitiveCompare:@"Cache-Control"] == NSOrderedSame) cacheControl = response.allHeaderFields[name];
+				}
+				BOOL valid = [self mayStart:work] && [response isKindOfClass:NSHTTPURLResponse.class] && response.statusCode >= 100 && response.statusCode <= 599 &&
+					TFBootstrapString(cacheControl, 1024) && [bytes isKindOfClass:NSData.class] && bytes.length <= 65536;
+				NSDictionary *reply = valid ? @{@"status": @(response.statusCode), @"cacheControl": cacheControl, @"bodyBase64": [bytes base64EncodedStringWithOptions:0]} : nil;
+				[self finish:work reply:reply];
+			}];
+		}];
+		if (!work.alive->value.load()) [work.network cancel];
+	} @catch (NSException *exception) { [self finish:work reply:nil]; }
+}
+- (BOOL)mayStart:(TFBootstrapWork *)work {
+	return _active.load() && _foreground.load() && work.alive->value.load() && work.context.alive->value.load() && [self.scheduler nowMs] < work.deadline && [self owned];
+}
+- (void)finish:(TFBootstrapWork *)work reply:(NSDictionary *)reply {
+	if (!work.alive->value.exchange(false)) return;
+	[work.context.pending removeObjectForKey:work.identifier]; self.pendingCount--;
+	[work.timer cancel]; work.timer = nil;
+	[work.network cancel]; work.network = nil;
+	void (^completion)(NSDictionary *) = work.completion; work.completion = nil;
+	@try { if (completion) completion(reply); } @catch (NSException *exception) { /* Consumers cannot reopen cancelled work. */ }
+}
+- (void)cancelContext:(NSString *)contextId request:(NSString *)requestId {
+	if (![self validContext:contextId]) TFBootstrapInvalid();
+	unsigned long long sequence = [self sequence:requestId];
+	TFBootstrapContext *context = self.contexts[contextId];
+	if (!context) return;
+	// Cancellation may arrive first. This bounded high-water mark prevents
+	// replay without accumulating retired-request tombstones.
+	context.lastRequest = MAX(context.lastRequest, sequence);
+	TFBootstrapWork *work = context.pending[requestId];
+	if (work) [self finish:work reply:nil];
+}
+- (void)retire:(NSString *)contextId {
+	TFBootstrapContext *context = self.contexts[contextId];
+	if (!context) return;
+	[self.contexts removeObjectForKey:contextId]; context.alive->value.store(false);
+	context.credential = nil; context.endpoint = nil;
+	for (TFBootstrapWork *work in context.pending.allValues) [self finish:work reply:nil];
+}
+- (void)lifecycle:(BOOL)foreground {
+	_foreground.store(foreground);
+	if (!foreground) for (TFBootstrapContext *context in self.contexts.allValues) for (TFBootstrapWork *work in context.pending.allValues) [self finish:work reply:nil];
+}
+- (void)close {
+	_active.store(false);
+	for (NSString *context in self.contexts.allKeys) [self retire:context];
+}
+@end

package/ios/TFAdmissionCatalog.h

@@ -0,0 +1,13 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Resource identity only; the session controller remains the admission authority.
+@interface TFAdmissionCatalog : NSObject
+@property (nonatomic, readonly, copy) NSDictionary<NSString *, NSDictionary *> *resources;
+- (instancetype)initWithResources:(NSArray<NSDictionary *> *)resources;
+- (TFAdmissionCatalog *)extending:(NSArray<NSDictionary *> *)resources;
+- (nullable NSDictionary *)find:(NSString *)url;
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/TFAdmissionCatalog.mm

@@ -0,0 +1,193 @@
+#import "TFAdmissionCatalog.h"
+#import "TFAdmissionEngine.h"
+#import <cmath>
+
+static void TFCatalogInvalid(void) {
+	@throw [NSException exceptionWithName:@"TFAdmissionCatalogInvalid" reason:@"Invalid native resource catalog" userInfo:nil];
+}
+static BOOL TFText(id value, NSUInteger maximum) {
+	return [value isKindOfClass:NSString.class] && [(NSString *)value length] > 0 && [(NSString *)value length] <= maximum;
+}
+static NSRegularExpression *TFPattern(NSString *pattern) {
+	NSRegularExpression *result = [NSRegularExpression regularExpressionWithPattern:pattern options:0 error:nil];
+	if (!result) TFCatalogInvalid();
+	return result;
+}
+static BOOL TFMatches(NSString *pattern, NSString *value) {
+	return [TFPattern(pattern) numberOfMatchesInString:value options:0 range:NSMakeRange(0, value.length)] == 1;
+}
+static NSDictionary<NSString *, NSString *> *TFSlots(void) {
+	NSString *decimal = @"(?:0|[1-9][0-9]{0,9})";
+	NSString *coordinate = @"-?(?:0|[1-9][0-9]{0,7})(?:\\.[0-9]{1,16})?";
+	return @{
+		@"z": @"(?:0|[1-9][0-9]?)", @"x": decimal, @"y": decimal,
+		@"ratio": @"(?:@2x|@3x)?", @"quadkey": @"[0-3]{0,30}", @"prefix": @"[0-9a-f]{2}",
+		@"bbox-epsg-3857": [@[coordinate, coordinate, coordinate, coordinate] componentsJoinedByString:@","],
+		@"fontstack": @"(?:[A-Za-z0-9_.~,+-]|%[0-9a-fA-F]{2}){1,768}",
+		@"range": [NSString stringWithFormat:@"%@-%@", decimal, decimal]
+	};
+}
+
+@interface TFAdmissionCatalogRule : NSObject
+@property (nonatomic, copy) NSDictionary *resource;
+@property (nonatomic, nullable) NSRegularExpression *pattern;
+@property (nonatomic, copy) NSArray<NSString *> *names;
+@end
+@implementation TFAdmissionCatalogRule
+- (NSString *)description { return @"TFAdmissionCatalogRule(redacted)"; }
+@end
+
+static TFAdmissionCatalogRule *TFRule(NSDictionary *input) {
+	if (![input isKindOfClass:NSDictionary.class] || input.count > 5 || !TFText(input[@"url"], 1920) ||
+		![@[@"style", @"tilejson", @"tile", @"sprite", @"glyph", @"font"] containsObject:input[@"scope"]]) TFCatalogInvalid();
+	NSString *url = [input[@"url"] copy], *scope = [input[@"scope"] copy];
+	NSString *tileset = input[@"tilesetId"], *family = input[@"template"];
+	if (([scope isEqual:@"tile"] || [scope isEqual:@"tilejson"]) && !tileset) TFCatalogInvalid();
+	if (tileset && (!TFText(tileset, 255) || !TFMatches(@"\\A[A-Za-z0-9._:-]{1,255}\\z", tileset) ||
+		[tileset.lowercaseString containsString:@"tf_native_"] || [tileset.lowercaseString containsString:@"tf_public_"])) TFCatalogInvalid();
+	NSMutableDictionary *resource = [@{@"url": url, @"scope": scope} mutableCopy];
+	if (tileset) resource[@"tilesetId"] = [tileset copy];
+	TFAdmissionCatalogRule *rule = [TFAdmissionCatalogRule new];
+	if (!family) {
+		if (input[@"fontStacks"] || [url containsString:@"{"] || [url containsString:@"}"]) TFCatalogInvalid();
+		TFAdmissionCleanURL(url);
+		rule.resource = [resource copy]; rule.names = @[];
+		return rule;
+	}
+	if (![@[@"tile", @"glyphs"] containsObject:family] || ![url hasPrefix:@"https://"]) TFCatalogInvalid();
+	NSRange path = [url rangeOfString:@"/" options:0 range:NSMakeRange(8, url.length - 8)];
+	if (path.location == NSNotFound || [[url substringToIndex:path.location] rangeOfCharacterFromSet:[NSCharacterSet characterSetWithCharactersInString:@"{}"]].location != NSNotFound) TFCatalogInvalid();
+	NSRegularExpression *placeholder = TFPattern(@"\\{([a-z0-9-]+)\\}");
+	NSArray<NSTextCheckingResult *> *matches = [placeholder matchesInString:url options:0 range:NSMakeRange(0, url.length)];
+	if (!matches.count || matches.count > 16) TFCatalogInvalid();
+	NSString *masked = [placeholder stringByReplacingMatchesInString:url options:0 range:NSMakeRange(0, url.length) withTemplate:@"native-template-slot"];
+	if ([masked containsString:@"{"] || [masked containsString:@"}"]) TFCatalogInvalid();
+	TFAdmissionCleanURL(masked);
+	NSMutableArray<NSString *> *names = [NSMutableArray array];
+	NSMutableString *pattern = [NSMutableString stringWithString:@"\\A"];
+	NSDictionary *slots = TFSlots();
+	NSUInteger cursor = 0;
+	for (NSTextCheckingResult *match in matches) {
+		NSString *name = [url substringWithRange:[match rangeAtIndex:1]];
+		if (!slots[name] || (names.count && match.range.location == cursor)) TFCatalogInvalid();
+		BOOL glyphSlot = [name isEqual:@"fontstack"] || [name isEqual:@"range"];
+		if ([family isEqual:@"glyphs"] != glyphSlot) TFCatalogInvalid();
+		[pattern appendString:[NSRegularExpression escapedPatternForString:[url substringWithRange:NSMakeRange(cursor, match.range.location - cursor)]]];
+		[pattern appendFormat:@"(%@)", slots[name]];
+		[names addObject:name]; cursor = NSMaxRange(match.range);
+	}
+	[pattern appendString:[NSRegularExpression escapedPatternForString:[url substringFromIndex:cursor]]];
+	[pattern appendString:@"\\z"];
+	if ([family isEqual:@"tile"]) {
+		if (![scope isEqual:@"tile"] || input[@"fontStacks"]) TFCatalogInvalid();
+	} else {
+		NSArray *stacks = input[@"fontStacks"];
+		if (![scope isEqual:@"glyph"] || ![names containsObject:@"fontstack"] || ![names containsObject:@"range"] ||
+			![stacks isKindOfClass:NSArray.class] || !stacks.count || stacks.count > 16) TFCatalogInvalid();
+		NSMutableArray *snapshot = [NSMutableArray array];
+		for (NSString *stack in stacks) {
+			if (!TFText(stack, 256) || [snapshot containsObject:stack] ||
+				![stack isEqual:[stack stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet]] ||
+				[stack rangeOfCharacterFromSet:NSCharacterSet.controlCharacterSet].location != NSNotFound ||
+				[stack rangeOfCharacterFromSet:[NSCharacterSet characterSetWithCharactersInString:@"\\/?#%&="]].location != NSNotFound ||
+				[stack.lowercaseString containsString:@"tf_native_"] || [stack.lowercaseString containsString:@"tf_public_"]) TFCatalogInvalid();
+			for (NSString *part in [stack componentsSeparatedByString:@","]) {
+				if (!part.length || ![part isEqual:[part stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet]]) TFCatalogInvalid();
+			}
+			[snapshot addObject:[stack copy]];
+		}
+		resource[@"fontStacks"] = [snapshot copy];
+	}
+	resource[@"template"] = [family copy];
+	rule.resource = [resource copy]; rule.pattern = TFPattern(pattern); rule.names = [names copy];
+	return rule;
+}
+
+static BOOL TFRuleMatches(TFAdmissionCatalogRule *rule, NSString *url) {
+	if (!rule.pattern) return [rule.resource[@"url"] isEqual:url];
+	NSTextCheckingResult *match = [rule.pattern firstMatchInString:url options:0 range:NSMakeRange(0, url.length)];
+	if (!match) return NO;
+	NSMutableDictionary<NSString *, NSString *> *values = [NSMutableDictionary dictionary];
+	for (NSUInteger index = 0; index < rule.names.count; index++) {
+		NSString *name = rule.names[index], *value = [url substringWithRange:[match rangeAtIndex:index + 1]];
+		if (values[name] && ![values[name] isEqual:value]) return NO;
+		values[name] = value;
+	}
+	NSUInteger zoom = values[@"z"] ? [values[@"z"] integerValue] : 30;
+	if (zoom > 30) return NO;
+	for (NSString *name in @[@"x", @"y"]) if (values[name] && [values[name] longLongValue] >= (1LL << zoom)) return NO;
+	if (values[@"quadkey"] && values[@"z"] && values[@"quadkey"].length != zoom) return NO;
+	if (values[@"bbox-epsg-3857"]) {
+		NSArray *numbers = [values[@"bbox-epsg-3857"] componentsSeparatedByString:@","];
+		for (NSString *number in numbers) if (!std::isfinite(number.doubleValue) || std::abs(number.doubleValue) > 20037508.343) return NO;
+		if ([numbers[0] doubleValue] >= [numbers[2] doubleValue] || [numbers[1] doubleValue] >= [numbers[3] doubleValue]) return NO;
+	}
+	if (values[@"range"]) {
+		NSArray *pair = [values[@"range"] componentsSeparatedByString:@"-"];
+		long long start = [pair[0] longLongValue], end = [pair[1] longLongValue];
+		if (start % 256 != 0 || end != start + 255 || end > 1114111) return NO;
+	}
+	if (values[@"fontstack"]) {
+		NSString *stack = values[@"fontstack"].stringByRemovingPercentEncoding;
+		if (!stack || ![rule.resource[@"fontStacks"] containsObject:stack]) return NO;
+	}
+	return YES;
+}
+
+static NSDictionary *TFMergeExtension(NSDictionary *previous, NSDictionary *next) {
+	if ([previous isEqual:next]) return previous;
+	if (![previous[@"scope"] isEqual:next[@"scope"]] ||
+		!((previous[@"tilesetId"] == nil && next[@"tilesetId"] == nil) || [previous[@"tilesetId"] isEqual:next[@"tilesetId"]]) ||
+		!((previous[@"template"] == nil && next[@"template"] == nil) || [previous[@"template"] isEqual:next[@"template"]]) ||
+		![previous[@"scope"] isEqual:@"glyph"] || ![previous[@"template"] isEqual:@"glyphs"]) TFCatalogInvalid();
+	NSArray *before = previous[@"fontStacks"], *after = next[@"fontStacks"];
+	if (![before isKindOfClass:NSArray.class] || ![after isKindOfClass:NSArray.class] || after.count > 16) TFCatalogInvalid();
+	for (NSString *stack in before) if (![after containsObject:stack]) TFCatalogInvalid();
+	return next;
+}
+
+@interface TFAdmissionCatalog ()
+@property (nonatomic, readwrite, copy) NSDictionary<NSString *, NSDictionary *> *resources;
+@property (nonatomic, copy) NSArray<TFAdmissionCatalogRule *> *rules;
+@end
+@implementation TFAdmissionCatalog
+- (instancetype)initWithResources:(NSArray<NSDictionary *> *)resources {
+	if ((self = [super init])) {
+		@try {
+			if (![resources isKindOfClass:NSArray.class] || resources.count > 128) TFCatalogInvalid();
+			NSMutableDictionary *snapshots = [NSMutableDictionary dictionary];
+			NSMutableArray *rules = [NSMutableArray array];
+			for (NSDictionary *resource in resources) {
+				TFAdmissionCatalogRule *rule = TFRule(resource);
+				NSString *url = rule.resource[@"url"];
+				if (snapshots[url]) TFCatalogInvalid();
+				snapshots[url] = rule.resource; [rules addObject:rule];
+			}
+			_resources = [snapshots copy]; _rules = [rules copy];
+		} @catch (NSException *exception) { TFCatalogInvalid(); }
+	}
+	return self;
+}
+- (TFAdmissionCatalog *)extending:(NSArray<NSDictionary *> *)resources {
+	TFAdmissionCatalog *incoming = [[TFAdmissionCatalog alloc] initWithResources:resources];
+	NSMutableDictionary *merged = [self.resources mutableCopy];
+	for (NSString *url in incoming.resources) {
+		NSDictionary *resource = incoming.resources[url];
+		merged[url] = merged[url] ? TFMergeExtension(merged[url], resource) : resource;
+	}
+	return [[TFAdmissionCatalog alloc] initWithResources:merged.allValues];
+}
+- (NSDictionary *)find:(NSString *)url {
+	@try { TFAdmissionCleanURL(url); } @catch (NSException *exception) { return nil; }
+	NSDictionary *found = nil;
+	for (TFAdmissionCatalogRule *rule in self.rules) {
+		if (!TFRuleMatches(rule, url)) continue;
+		if (found) TFCatalogInvalid();
+		NSMutableDictionary *identity = [@{@"url": url, @"scope": rule.resource[@"scope"]} mutableCopy];
+		if (rule.resource[@"tilesetId"]) identity[@"tilesetId"] = rule.resource[@"tilesetId"];
+		found = [identity copy];
+	}
+	return found;
+}
+- (NSString *)description { return @"TFAdmissionCatalog(redacted)"; }
+@end

package/ios/TFAdmissionDocumentScope.h

@@ -0,0 +1,7 @@
+#import "TFNativeDocumentRegistry.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+FOUNDATION_EXPORT TFNativeDocumentScope *TFCreateAdmissionDocumentScope(TFAdmissionEngine *engine, NSString *context);
+
+NS_ASSUME_NONNULL_END

package/ios/TFAdmissionDocumentScope.mm

@@ -0,0 +1,45 @@
+#import "TFAdmissionDocumentScope.h"
+#import <atomic>
+
+@interface TFAdmissionDocumentOperation : NSObject <TFAdmissionCancel> {
+	std::atomic_bool _finished;
+}
+@property (nonatomic, strong, nullable) id<TFAdmissionCancel> request;
+@property (nonatomic, copy, nullable) TFAdmissionNetworkCompletion completion;
+- (void)finish:(nullable NSHTTPURLResponse *)response body:(nullable NSData *)body;
+@end
+@implementation TFAdmissionDocumentOperation
+- (instancetype)init { if ((self = [super init])) _finished.store(false); return self; }
+- (void)finish:(NSHTTPURLResponse *)response body:(NSData *)body {
+	if (_finished.exchange(true)) return;
+	TFAdmissionNetworkCompletion completion = self.completion; self.completion = nil;
+	if (completion) completion(response, body);
+}
+- (void)cancel {
+	@try { [self.request cancel]; }
+	@finally {
+		// The admission network owns physical cleanup; this is the document's logical result.
+		[self finish:nil body:nil];
+	}
+}
+- (NSString *)description { return @"TFAdmissionDocumentOperation(redacted)"; }
+@end
+
+TFNativeDocumentScope *TFCreateAdmissionDocumentScope(TFAdmissionEngine *engine, NSString *context) {
+	TFAdmissionStartGuard active = [engine contextGuard:context];
+	return [[TFNativeDocumentScope alloc] initWithContext:context active:active load:^id<TFAdmissionCancel>(NSURLRequest *request, TFAdmissionNetworkCompletion completion) {
+		NSString *url = TFAdmissionCleanURL(request.URL.absoluteString);
+		NSMutableURLRequest *tagged = [request mutableCopy];
+		tagged.URL = [NSURL URLWithString:[url stringByAppendingFormat:@"%@__tf_native_context=%@", [url containsString:@"?"] ? @"&" : @"?", context]];
+		TFAdmissionDocumentOperation *operation = [TFAdmissionDocumentOperation new];
+		operation.completion = completion;
+		operation.request = [engine request:tagged response:^(NSHTTPURLResponse *response, NSData *body) {
+			[operation finish:response body:body];
+		} failure:^{ [operation finish:nil body:nil]; } delegate:^id<TFAdmissionCancel>(NSURLRequest *request, TFAdmissionNetworkCompletion completion) {
+			// Unprotected preparation uses the independent credential-free document channel.
+			completion(nil, nil);
+			return [TFAdmissionDocumentOperation new];
+		}];
+		return operation;
+	}];
+}

package/ios/TFAdmissionEngine.h

@@ -0,0 +1,57 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol TFAdmissionCancel <NSObject>
+- (void)cancel;
+@end
+
+@protocol TFAdmissionScheduler <NSObject>
+- (NSTimeInterval)nowMs;
+- (void)enqueue:(dispatch_block_t)block;
+- (id<TFAdmissionCancel>)after:(NSTimeInterval)milliseconds perform:(dispatch_block_t)block;
+@end
+
+typedef BOOL (^TFAdmissionStartGuard)(void);
+typedef void (^TFAdmissionNetworkCompletion)(NSHTTPURLResponse *_Nullable response, NSData *_Nullable body);
+typedef id<TFAdmissionCancel> _Nonnull (^TFAdmissionDelegate)(NSURLRequest *request, TFAdmissionNetworkCompletion completion);
+
+@protocol TFAdmissionNetwork <NSObject>
+- (id<TFAdmissionCancel>)start:(NSURLRequest *)request
+	mayStart:(TFAdmissionStartGuard)guard
+	completion:(TFAdmissionNetworkCompletion)completion;
+@end
+
+// Internal per-installation registry. Only the JavaScript controller admits
+// commercial requests; native sequence values identify transport messages.
+@interface TFAdmissionEngine : NSObject
+- (instancetype)initWithInstallation:(NSString *)installation
+	scheduler:(id<TFAdmissionScheduler>)scheduler
+	network:(id<TFAdmissionNetwork>)network
+	owns:(TFAdmissionStartGuard)owns
+	emit:(void (^)(NSDictionary *event))emit;
+- (NSString *)registerMap:(nullable NSString *)mapId resources:(NSArray<NSDictionary *> *)resources;
+- (NSUInteger)extendContext:(NSString *)context resources:(NSArray<NSDictionary *> *)resources;
+- (TFAdmissionStartGuard)contextGuard:(NSString *)context;
+- (id<TFAdmissionCancel>)request:(NSURLRequest *)request
+	response:(void (^)(NSHTTPURLResponse *response, NSData *body))response
+	failure:(dispatch_block_t)failure
+	delegate:(TFAdmissionDelegate)delegate;
+- (NSUInteger)completeContext:(NSString *)context generation:(NSUInteger)generation
+	batch:(NSString *)batch results:(NSArray<NSDictionary *> *)results;
+- (void)retire:(NSString *)context;
+- (void)lifecycle:(BOOL)foreground;
+- (void)close;
+- (BOOL)isOwner;
+@end
+
+FOUNDATION_EXPORT NSString *const TFAdmissionGrantHeader;
+FOUNDATION_EXPORT BOOL TFAdmissionHasReservedContext(NSString *url);
+FOUNDATION_EXPORT NSDictionary<NSString *, NSString *> *TFAdmissionStripContext(NSString *url);
+FOUNDATION_EXPORT NSString *TFAdmissionCleanURL(NSString *url);
+FOUNDATION_EXPORT NSString *TFAdmissionOrigin(NSString *url);
+FOUNDATION_EXPORT BOOL TFAdmissionStyleMatchesMap(NSString *url, NSString *mapId);
+FOUNDATION_EXPORT BOOL TFAdmissionValidToken(id value);
+FOUNDATION_EXPORT NSError *TFAdmissionSafeError(void);
+
+NS_ASSUME_NONNULL_END