@tileflow/react-native 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/internal/session.js

@@ -19,6 +19,13 @@ var REFRESH_MARGIN_MS = 3e4;
 var ROTATION_AGE_MS = 6 * 60 * 60 * 1e3;
 var ROTATION_REQUEST_LIMIT = 1e4;
 var FUTURE_ISSUE_SKEW_MS = 3e4;
+var RETRY_INITIAL_MS = 1e3;
+var RETRY_LIMIT_MS = 6e4;
+var RETRY_AFTER_LIMIT_MS = 15 * 60 * 1e3;
+var RETRY_AFTER_SECONDS = /^\d{1,10}$/u;
+var QUOTA_CODES = /* @__PURE__ */ new Set(["COMMERCIAL_MAP_LIMIT_REACHED", "COMMERCIAL_SPENDING_LIMIT_REACHED"]);
+var SERVICE_CODE = /^[A-Z][A-Z0-9_]{0,63}$/u;
+var SERVICE_CODE_BODY_LIMIT = 4096;
 var MOBILE_CREDENTIAL = /^tf_public_[0-9a-f]{48}$/u;
 var MAP_ID = /^map_[A-Za-z0-9_-]{16}$/u;
 var CREDENTIAL_ID = /^key_[A-Za-z0-9_-]{8,80}$/u;
@@ -57,6 +64,14 @@ var SUCCESS_KEYS = /* @__PURE__ */ new Set([
   "tilesetIds"
 ]);
 var RESTART_KEYS = /* @__PURE__ */ new Set(["code", "error", "retryWithNewSession", "sessionId"]);
+var TERMINAL_CODES = /* @__PURE__ */ new Set([
+  "NATIVE_SESSION_INPUT_INVALID",
+  "NATIVE_SESSION_CREDENTIAL_REJECTED",
+  "NATIVE_SESSION_MAP_MISMATCH",
+  "NATIVE_SESSION_MAP_NOT_FOUND",
+  "NATIVE_SESSION_QUOTA_EXCEEDED",
+  "NATIVE_SESSION_REJECTED"
+]);
 var ERROR_MESSAGES = {
   NATIVE_SESSION_INPUT_INVALID: "Native session configuration is invalid.",
   NATIVE_SESSION_RESPONSE_TOO_LARGE: "Native session response exceeded its byte limit.",
@@ -68,18 +83,22 @@ var ERROR_MESSAGES = {
   NATIVE_SESSION_MAP_NOT_FOUND: "Native session Map was not found.",
   NATIVE_SESSION_QUOTA_EXCEEDED: "Native session quota was exceeded.",
   NATIVE_SESSION_REJECTED: "Native session request was rejected.",
+  NATIVE_SESSION_RATE_LIMITED: "Native session requests are rate limited.",
   NATIVE_SESSION_UNAVAILABLE: "Native session service is unavailable.",
   NATIVE_SESSION_REPLACED: "Native session binding was replaced.",
   NATIVE_SESSION_DISPOSED: "Native session controller is disposed."
 };
 var HostedNativeSessionError = class extends Error {
-  constructor(code) {
+  constructor(code, reason) {
     super(ERROR_MESSAGES[code]);
     __publicField(this, "code");
     __publicField(this, "kind");
     this.name = "HostedNativeSessionError";
     this.code = code;
     this.kind = errorKind(code);
+    if (code === "NATIVE_SESSION_REJECTED" && typeof reason === "string" && SERVICE_CODE.test(reason)) {
+      this.reason = reason;
+    }
   }
 };
 function createHostedNativeSessionController(input) {
@@ -189,7 +208,29 @@ function createHostedNativeSessionController(input) {
       })
     );
   }
+  let terminal = null;
+  let failures = 0;
+  let retryAt = null;
+  let retryError = null;
+  function clearRetry() {
+    failures = 0;
+    retryAt = null;
+    retryError = null;
+  }
+  function delayRetry(error) {
+    let at;
+    try {
+      at = readClock();
+    } catch {
+      return;
+    }
+    if (retryAt === null || at >= retryAt) failures = Math.min(failures + 1, 16);
+    const backoff = Math.min(RETRY_INITIAL_MS * 2 ** (failures - 1), RETRY_LIMIT_MS);
+    retryAt = Math.max(retryAt ?? at, at + Math.max(backoff, retryAfterDelays.get(error) ?? 0));
+    retryError = safeError(error);
+  }
   function rotateIfRequired(at) {
+    if (terminal) throw errorFrom(terminal);
     if (!activeSession || binding.kind !== "hosted") return;
     if (at - activeSession.startedAt < ROTATION_AGE_MS && activeSession.requestCount < ROTATION_REQUEST_LIMIT) {
       return;
@@ -223,6 +264,7 @@ function createHostedNativeSessionController(input) {
     return current;
   }
   async function ensureAuthority(session, at) {
+    if (terminal) throw errorFrom(terminal);
     if (session.authority && session.authority.clockEpoch === clock.epoch && session.authority.validUntil - at > REFRESH_MARGIN_MS) {
       return { authority: session.authority, session };
     }
@@ -230,20 +272,28 @@ function createHostedNativeSessionController(input) {
     if (binding.kind !== "hosted") {
       throw new HostedNativeSessionError("NATIVE_SESSION_REPLACED");
     }
+    if (retryAt !== null && retryError && at < retryAt) {
+      if (session.authority && session.authority.clockEpoch === clock.epoch && session.authority.validUntil > at) {
+        return { authority: session.authority, session };
+      }
+      throw errorFrom(retryError);
+    }
     const operationBinding = binding;
     const abort = new SessionAbortController();
     operations.add(abort);
     const operation = {
       abort,
       promise: Promise.resolve().then(async () => {
-        session.error = null;
-        publishSession(session, "loading");
-        if (abort.signal.aborted) throw abort.error();
         try {
+          if (abort.signal.aborted) throw abort.error();
+          session.error = null;
+          publishSession(session, "loading");
+          if (abort.signal.aborted) throw abort.error();
           const result = await bootstrap(session, operationBinding, abort, true, true);
           if (abort.signal.aborted) throw abort.error();
           result.session.authority = result.authority;
           result.session.error = null;
+          if (binding === operationBinding) clearRetry();
           if (activeSession === result.session) {
             publishSession(result.session, "ready");
             if (abort.signal.aborted) throw abort.error();
@@ -252,8 +302,26 @@ function createHostedNativeSessionController(input) {
         } catch (error) {
           const normalized = abort.signal.aborted ? abort.error() : normalizeError(error);
           const target = latestSession(session);
+          if (normalized.kind === "terminal" && binding === operationBinding && !terminal) {
+            const failure = safeError(normalized);
+            terminal = failure;
+            const rejectedSession = activeSession;
+            if (rejectedSession) {
+              rejectedSession.authority = null;
+              rejectedSession.error = failure;
+            }
+            for (const pending of [...operations]) {
+              pending.abort(failure.code, failure.reason);
+            }
+            if (binding === operationBinding && rejectedSession) {
+              publishSession(rejectedSession, "error", failure);
+            }
+          }
+          if (normalized.kind === "recoverable" && binding === operationBinding && !terminal) {
+            delayRetry(normalized);
+          }
           if (normalized.code !== "NATIVE_SESSION_REPLACED" && normalized.code !== "NATIVE_SESSION_DISPOSED") {
-            target.error = Object.freeze({ code: normalized.code, kind: normalized.kind });
+            target.error = safeError(normalized);
             publishSession(target, "error", target.error);
           }
           throw normalized;
@@ -279,20 +347,29 @@ function createHostedNativeSessionController(input) {
     if (abort.signal.aborted) throw abort.error();
     const expectedSurfaceId = session.authority?.public.surfaceId ?? session.requestedSurfaceId;
     const response = await fetchResponse(hostedBinding, session, expectedSurfaceId, abort);
-    const source = await readBoundedResponse(response, abort);
+    const { source, size } = await readBoundedResponse(response, abort);
     let body;
     try {
       body = source.length ? JSON.parse(source) : null;
     } catch {
-      throw new HostedNativeSessionError("NATIVE_SESSION_RESPONSE_JSON_INVALID");
+      if (response.status === 201) {
+        throw new HostedNativeSessionError("NATIVE_SESSION_RESPONSE_JSON_INVALID");
+      }
+      body = null;
     }
-    if (response.status === 409 && allowRestart && isExactRestart(body, session.sessionId)) {
+    if (response.status === 409 && isExactRestart(body, session.sessionId)) {
+      if (!allowRestart) throw new HostedNativeSessionError("NATIVE_SESSION_UNAVAILABLE");
       assertCurrentSession(session, hostedBinding);
       const replacement = redirectSession(session, readClock());
       if (abort.signal.aborted) throw abort.error();
       return bootstrap(replacement, hostedBinding, abort, false, false);
     }
-    if (response.status !== 201) throw statusError(response.status);
+    if (response.status !== 201) {
+      const failure = statusError(response.status, body, size);
+      const delay = retryAfterMs(response.headers, now);
+      if (delay !== null) retryAfterDelays.set(failure, delay);
+      throw failure;
+    }
     if (!hasNoStore(response.headers.get("cache-control"))) {
       throw new HostedNativeSessionError("NATIVE_SESSION_RESPONSE_INVALID");
     }
@@ -365,6 +442,16 @@ function createHostedNativeSessionController(input) {
     if (binding.kind === "direct" || !activeSession) {
       return Object.freeze({ status: "idle", source: "direct", lifecycle });
     }
+    if (terminal) {
+      return Object.freeze({
+        status: "error",
+        source: "hosted",
+        lifecycle,
+        mapId: binding.mapId,
+        sessionId: activeSession.sessionId,
+        error: terminal
+      });
+    }
     if (activeSession.operation) {
       return Object.freeze({
         status: "loading",
@@ -416,6 +503,7 @@ function createHostedNativeSessionController(input) {
       if (bindingGeneration !== expectedGeneration) {
         throw new HostedNativeSessionError("NATIVE_SESSION_REPLACED");
       }
+      if (terminal) throw errorFrom(terminal);
       checkedAt = readClock();
       if (resolved.authority.clockEpoch === clock.epoch && resolved.authority.validUntil > checkedAt) {
         admittedAuthorities.set(resolved.authority.public, resolved.authority);
@@ -470,7 +558,7 @@ function createHostedNativeSessionController(input) {
       }
     },
     transportBudget(authority) {
-      if (disposed || lifecycle !== "foreground") return 0;
+      if (disposed || terminal || lifecycle !== "foreground") return 0;
       const stored = admittedAuthorities.get(authority);
       if (!stored || stored.bindingGeneration !== bindingGeneration) return 0;
       try {
@@ -489,6 +577,11 @@ function createHostedNativeSessionController(input) {
     async resume() {
       if (disposed) throw new HostedNativeSessionError("NATIVE_SESSION_DISPOSED");
       lifecycle = "foreground";
+      if (terminal) {
+        const error = errorFrom(terminal);
+        publish(currentSnapshot());
+        throw error;
+      }
       if (binding.kind === "direct" || !activeSession) {
         publish(currentSnapshot());
         return;
@@ -511,9 +604,27 @@ function createHostedNativeSessionController(input) {
       bindingGeneration += 1;
       for (const operation of operations) operation.abort("NATIVE_SESSION_REPLACED");
       binding = next;
+      terminal = null;
+      clearRetry();
       activeSession = next.kind === "hosted" ? createSession(next.surfaceId, readClock()) : null;
       publish(snapshotIdle(binding, activeSession, lifecycle));
     },
+    retry() {
+      if (disposed) throw new HostedNativeSessionError("NATIVE_SESSION_DISPOSED");
+      if (!terminal && retryAt === null) return;
+      terminal = null;
+      clearRetry();
+      if (activeSession && !activeSession.operation) activeSession.error = null;
+      publish(currentSnapshot());
+    },
+    retryDelay() {
+      if (disposed || terminal || retryAt === null) return null;
+      try {
+        return Math.max(0, Math.ceil(retryAt - readClock()));
+      } catch {
+        return null;
+      }
+    },
     subscribe(listener) {
       if (typeof listener !== "function") {
         throw new HostedNativeSessionError("NATIVE_SESSION_INPUT_INVALID");
@@ -608,7 +719,8 @@ function parseSuccess(value, binding, expectedSessionId, expectedSurfaceId) {
   const issuedAtMs = parseExactIso(value.issuedAt);
   const serverTimeMs = parseExactIso(value.serverTime);
   const expiresAtMs = parseExactIso(value.expiresAt);
-  if (issuedAtMs > serverTimeMs + FUTURE_ISSUE_SKEW_MS || expiresAtMs <= serverTimeMs || expiresAtMs <= issuedAtMs || expiresAtMs - issuedAtMs > MAX_GRANT_LIFETIME_MS || expiresAtMs - issuedAtMs > MAX_GRANT_LIFETIME_MS) {
+  if (issuedAtMs > serverTimeMs + FUTURE_ISSUE_SKEW_MS || expiresAtMs <= serverTimeMs || expiresAtMs <= issuedAtMs || expiresAtMs - issuedAtMs > MAX_GRANT_LIFETIME_MS || // The local deadline is derived from serverTime, so this also bounds the transport budget.
+  expiresAtMs - serverTimeMs > MAX_GRANT_LIFETIME_MS) {
     throw new HostedNativeSessionError("NATIVE_SESSION_RESPONSE_INVALID");
   }
   const authority = {
@@ -739,7 +851,7 @@ async function readBoundedResponse(response, abort) {
     bytes.set(chunk, offset);
     offset += chunk.byteLength;
   }
-  return decodeUtf8(bytes);
+  return { source: decodeUtf8(bytes), size };
 }
 function decodeUtf8(bytes) {
   let result = "";
@@ -787,18 +899,60 @@ function decodeUtf8(bytes) {
 function hasNoStore(value) {
   return typeof value === "string" && value.split(",").some((part) => part.trim().toLowerCase() === "no-store");
 }
-function statusError(status) {
+function statusError(status, body, size) {
   if (status === 401) return new HostedNativeSessionError("NATIVE_SESSION_CREDENTIAL_REJECTED");
   if (status === 403) return new HostedNativeSessionError("NATIVE_SESSION_MAP_MISMATCH");
   if (status === 404) return new HostedNativeSessionError("NATIVE_SESSION_MAP_NOT_FOUND");
-  if (status === 429) return new HostedNativeSessionError("NATIVE_SESSION_QUOTA_EXCEEDED");
-  if (status === 503) return new HostedNativeSessionError("NATIVE_SESSION_UNAVAILABLE");
-  return new HostedNativeSessionError("NATIVE_SESSION_REJECTED");
+  if (status === 429) {
+    return new HostedNativeSessionError(
+      isRecord(body) && typeof body.code === "string" && QUOTA_CODES.has(body.code) ? "NATIVE_SESSION_QUOTA_EXCEEDED" : "NATIVE_SESSION_RATE_LIMITED"
+    );
+  }
+  if (status === 408 || status >= 500 && status <= 599) {
+    return new HostedNativeSessionError("NATIVE_SESSION_UNAVAILABLE");
+  }
+  if (status >= 400 && status <= 499) {
+    return new HostedNativeSessionError(
+      "NATIVE_SESSION_REJECTED",
+      size <= SERVICE_CODE_BODY_LIMIT && isRecord(body) && typeof body.code === "string" ? body.code : void 0
+    );
+  }
+  return new HostedNativeSessionError("NATIVE_SESSION_RESPONSE_INVALID");
+}
+function safeError(error) {
+  return Object.freeze(
+    error.reason === void 0 ? { code: error.code, kind: error.kind } : { code: error.code, kind: error.kind, reason: error.reason }
+  );
+}
+function errorFrom(error) {
+  return new HostedNativeSessionError(error.code, error.reason);
+}
+var retryAfterDelays = /* @__PURE__ */ new WeakMap();
+function retryAfterMs(headers, now) {
+  let value;
+  try {
+    value = headers.get("retry-after");
+  } catch {
+    return null;
+  }
+  if (typeof value !== "string" || value.length > 64) return null;
+  const text = value.trim();
+  let delay;
+  if (RETRY_AFTER_SECONDS.test(text)) delay = Number(text) * 1e3;
+  else {
+    const date = Date.parse(text);
+    if (!Number.isFinite(date)) return null;
+    try {
+      delay = date - readWallClock(now);
+    } catch {
+      return null;
+    }
+  }
+  return Math.min(Math.max(0, delay), RETRY_AFTER_LIMIT_MS);
 }
 function errorKind(code) {
   if (code === "NATIVE_SESSION_DISPOSED" || code === "NATIVE_SESSION_REPLACED") return "cancelled";
-  if (code === "NATIVE_SESSION_UNAVAILABLE") return "recoverable";
-  return "terminal";
+  return TERMINAL_CODES.has(code) ? "terminal" : "recoverable";
 }
 function normalizeError(error, fallback = "NATIVE_SESSION_RESPONSE_INVALID") {
   return error instanceof HostedNativeSessionError ? error : new HostedNativeSessionError(fallback);
@@ -821,12 +975,13 @@ async function cancelResponse(response) {
   } catch {
   }
 }
-var _aborted, _code, _listeners;
+var _aborted, _code, _reason, _listeners;
 var SessionAbortController = class {
   constructor() {
     __publicField(this, "signal");
     __privateAdd(this, _aborted, false);
     __privateAdd(this, _code, "NATIVE_SESSION_REPLACED");
+    __privateAdd(this, _reason);
     __privateAdd(this, _listeners, /* @__PURE__ */ new Set());
     const isAborted = () => __privateGet(this, _aborted);
     this.signal = Object.freeze({
@@ -841,9 +996,10 @@ var SessionAbortController = class {
       }
     });
   }
-  abort(code) {
+  abort(code, reason) {
     if (__privateGet(this, _aborted)) return;
     __privateSet(this, _code, code);
+    __privateSet(this, _reason, reason);
     __privateSet(this, _aborted, true);
     for (const listener of [...__privateGet(this, _listeners)]) {
       try {
@@ -854,11 +1010,12 @@ var SessionAbortController = class {
     __privateGet(this, _listeners).clear();
   }
   error() {
-    return new HostedNativeSessionError(__privateGet(this, _code));
+    return new HostedNativeSessionError(__privateGet(this, _code), __privateGet(this, _reason));
   }
 };
 _aborted = new WeakMap();
 _code = new WeakMap();
+_reason = new WeakMap();
 _listeners = new WeakMap();
 function raceWithAbort(promise, controller) {
   if (controller.signal.aborted) return Promise.reject(controller.error());

package/dist/internal/source-state.d.ts

@@ -1,5 +1,5 @@
 import { TileflowNativeSourceState } from '@tileflow/core/native';
-import { v as MapSourceState } from '../contract-By3URNxS.js';
+import { x as MapSourceState } from '../contract-BWT1jxqg.js';
 import '@maplibre/maplibre-react-native';
 import 'react';
 import 'react-native';

package/ios/TFAdmissionBootstrap.mm

@@ -102,11 +102,13 @@ static NSTextCheckingResult *TFBootstrapMatch(NSString *value, NSString *pattern
 	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;
+	// Well inside the 30 s ticket and batch deadlines, so a stalled renewal fails its batch
+	// instead of letting the context retire under it.
+	work.deadline = [self.scheduler nowMs] + 10000; work.completion = completion;
 	context.pending[requestId] = work; self.pendingCount++;
-	work.timer = [self.scheduler after:30000 perform:^{ [self finish:work reply:nil]; }];
+	work.timer = [self.scheduler after:10000 perform:^{ [self finish:work reply:nil]; }];
 	NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:clean]
-		cachePolicy:NSURLRequestReloadIgnoringLocalCacheData timeoutInterval:30];
+		cachePolicy:NSURLRequestReloadIgnoringLocalCacheData timeoutInterval:10];
 	request.HTTPMethod = @"POST"; request.HTTPBody = [body dataUsingEncoding:NSUTF8StringEncoding];
 	request.HTTPShouldHandleCookies = NO;
 	[request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
@@ -115,13 +117,17 @@ static NSTextCheckingResult *TFBootstrapMatch(NSString *value, NSString *pattern
 	@try {
 		work.network = [self.network start:request mayStart:^BOOL { return [self mayStart:work]; } completion:^(NSHTTPURLResponse *response, NSData *bytes) {
 			[self.scheduler enqueue:^{
-				NSString *cacheControl = @"";
+				NSString *cacheControl = @"", *retryAfter = @"";
 				for (id name in response.allHeaderFields) {
-					if ([name isKindOfClass:NSString.class] && [(NSString *)name caseInsensitiveCompare:@"Cache-Control"] == NSOrderedSame) cacheControl = response.allHeaderFields[name];
+					if (![name isKindOfClass:NSString.class]) continue;
+					if ([(NSString *)name caseInsensitiveCompare:@"Cache-Control"] == NSOrderedSame) cacheControl = response.allHeaderFields[name];
+					if ([(NSString *)name caseInsensitiveCompare:@"Retry-After"] == NSOrderedSame) retryAfter = response.allHeaderFields[name];
 				}
+				// An oversized Retry-After is ignored rather than failing the reply.
+				if (!TFBootstrapString(retryAfter, 64)) retryAfter = @"";
 				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;
+				NSDictionary *reply = valid ? @{@"status": @(response.statusCode), @"cacheControl": cacheControl, @"retryAfter": retryAfter, @"bodyBase64": [bytes base64EncodedStringWithOptions:0]} : nil;
 				[self finish:work reply:reply];
 			}];
 		}];

package/ios/TFAdmissionEngine.mm

@@ -168,8 +168,10 @@ static BOOL TFGrantShape(NSString *value) {
 		work.response = response; work.failure = failure; work.delegate = delegate; work.releaseReservation = release;
 		context.work[work.identifier] = work; [context.order addObject:work.identifier];
 		work.timer = [self.scheduler after:30000 perform:^{
-			if ([context.batchTickets containsObject:work.identifier]) [self retire:context.identifier];
-			else [self fail:work];
+			// A slow renewal fails only this request. JavaScript still answers its batch, and the
+			// batch deadline alone retires a context whose JavaScript stopped answering.
+			if ([context.batchTickets containsObject:work.identifier]) [self event:context kind:@"cancel" fields:@{@"tickets": @[work.identifier]}];
+			[self fail:work];
 		}];
 		[self.scheduler enqueue:^{ [self drain:context]; }];
 	}];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react-native",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "license": "Apache-2.0",
   "description": "Tileflow maps, camera control and semantic interactions for React Native.",
   "type": "module",
@@ -18,7 +18,6 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs",
     "android/build.gradle",
     "android/src/main",
     "ios/*.h",
@@ -36,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.40 <0.1.0-beta.0",
-    "@tileflow/interactions": ">=0.1.0-alpha.6 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.43 <0.1.0-beta.0",
+    "@tileflow/interactions": ">=0.1.0-alpha.7 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "@maplibre/maplibre-react-native": "11.5.0",

package/docs/native-admission.md

@@ -1,108 +0,0 @@
-# Private native resource admission
-
-This guide describes the private native networking boundary used by the mounted Tileflow `Map` in `@tileflow/react-native`. The transport, session controller, resource catalog, configuration reader and native bridge are **not a public API**. The package root exports the Tileflow `Map` and public Map types only; it does not export grants, credentials, session objects, admission handles, native renderer handles or request interception controls.
-
-The mounted owner prepares a **bounded Style/TileJSON resource closure** before native rendering. It covers the current owned style document, one TileJSON edge per tile source, tile templates, sprite leaves, glyph templates, native-v1 managed font faces and supported base assets represented by the current contracts. It does not recursively trust arbitrary remote graphs. Ambiguous, unsafe, oversized or incomplete protected graphs fail closed, while foreign/unowned resources remain unchanged.
-
-## Exact native dependencies
-
-The source targets React 19.2.0, React Native 0.83.10, MapLibre React Native 11.5.0, MapLibre Native Android 13.6.1 and MapLibre Native iOS 6.31.0. Android's HTTP dependency is OkHttp 4.12.0. These pins and the existence of source tests are **not evidence** of a successful build, device run, Hosted service or app-store acceptance; qualify the exact revision in the intended host.
-
-Android's library build uses the host's Android Gradle/Kotlin plugins and SDK settings. `react-native.config.cjs` autolinks `TileflowNativeAdmissionPackage`, which registers the private admission, document, configuration and surface modules. The library depends on the autolinked `:maplibre_maplibre-react-native` project and rejects conflicting MapLibre Native versions rather than selecting another version silently.
-
-On iOS, the `TileflowNativeAdmission` pod depends on the exact React and MapLibre React Native pods. MapLibre Native itself is the existing pinned Swift Package Manager product, not a second MapLibre CocoaPod. Retain the host's React Native post-install work and MapLibre setup, then invoke:
-
-```ruby
-$MLRN.post_install(installer)
-tileflow_native_admission_post_install(installer)
-```
-
-The helper requires the MapLibre distribution reference with `exactVersion` 6.31.0 and reuses that product for the Tileflow pod/test targets. It does not add another SDK or change the pin.
-
-## Installation ownership
-
-Tileflow owns the MapLibre networking seam in explicit installation order. Android captures the previous `ModuleProvider`, wraps `createHttpRequest()` and delegates unowned traffic to the previous provider. iOS adds `TFNativeAdmissionURLProtocol` only to MapLibre's session configuration and uses an independent internal URLSession; it never registers an application-global protocol.
-
-Installation/removal are acknowledged operations. Partial installation rolls back only state still owned by that attempt. A later incompatible provider/configuration replacement makes protected work fail closed; removal never overwrites a later owner. This is not a guarantee for arbitrary third-party mutation chains.
-
-The process-level installation may be shared by mounted Maps, but that is the only shared ownership. Each real Map owns a distinct source generation, Hosted binding/session/controller, native context, catalog, queue, tickets and callbacks. One Map's retirement or cleanup failure cannot spend, remove or reuse another Map's authority.
-
-## Mounted Map lifecycle
-
-A native Map is created only after source resolution and context acknowledgement. If the resolved manifest uses Hosted session delivery, application configuration must first yield a binding whose canonical API origin exactly matches the manifest. Non-session delivery does not read the mobile credential or bootstrap Hosted authority.
-
-Theme transactions keep the same native Map, context, session and camera. Resource additions are append-only and become usable only after native `extendContext` acknowledgement. Glyph templates may extend their finite font-stack allowlist across themes by an acknowledged union; the template URL, origin, class and scope cannot change. A logical source/Map replacement retires the previous context before opening the next one.
-
-Retirement is idempotent and cancels queue, JavaScript wait, admitted work, document acquisition and late native completions. Removal acknowledgements are retryable. Strict Mode unmount/remount therefore cannot revive the old generation or share its context with the replacement.
-
-## Resource identity and projection
-
-Every protected resource is canonical HTTPS and belongs to one explicit class: `style`, `tilejson`, `tile`, `sprite`, `glyph` or `font`. Tile and TileJSON entries also preserve exact tileset identity. Tile templates use only the bounded native placeholder grammar. Glyph templates require both `{fontstack}` and `{range}` and a finite exact font-stack set.
-
-Style preparation resolves relative URLs through Core's native URL policy. A style may discover at most one bounded TileJSON document for a declared tile source; TileJSON cannot recursively point to another TileJSON. Sprite base URLs are admitted through their concrete JSON/PNG 1x/2x leaves before the style receives its transient context discriminator. Native-v1 font-face arrays preserve family/style/weight attributes while only their admitted URL is rewritten.
-
-Owned URLs must match the exact Hosted origin/path rules and the session policy's scope/tileset set. A resource on a foreign origin remains unmodified. An URL on an owned origin but outside a known resource path fails closed instead of inheriting authority merely because its origin matches.
-
-The non-secret `__tf_native_context` discriminator selects one Map context. It is stripped before HTTP and never conveys authority. Unknown, malformed, stale, duplicate or retired reserved context values are rejected rather than delegated as third-party traffic. Other URL identity is preserved.
-
-## Admission accounting
-
-Every eligible protected request produces one logical controller `acquire()` result. A bounded bridge batch may carry several tickets but never shares one acquire, preallocates grants, counts chunks or maintains a native commercial counter. Direct/non-session contexts delegate without commercial acquisition.
-
-The controller preserves the 10,000-request and six-hour rotation semantics: the 10,000th acquisition remains in its session and the next rotates. Bootstrap/refresh are single-flight where allowed. Native cancellation does not refund a logical acquisition already made. HTTP response observation does not confirm or undo server-owned commercial completion.
-
-`X-Tileflow-Native-Grant` is the only protected-resource grant carrier. It is attached only after resource/context/session policy checks and never enters query strings, URLs, cache keys, public state, events, errors or logs.
-
-## Independent bootstrap and expiry
-
-Bootstrap uses an independent OkHttp client or ephemeral URLSession channel. It sends the bounded session-start POST to the configured canonical API origin and carries the publishable mobile credential only in `X-Tileflow-Mobile-Client`. Cookies, ambient credentials and automatic redirects are disabled.
-
-Each context binds its validated bootstrap endpoint/credential. Retiring that context cancels its bootstrap without cancelling another Map. TypeScript alone parses session authority and makes admission decisions.
-
-The controller's private transport budget remains anchored to its existing local `validUntil`. Native never reconstructs a fresh lifetime from server timestamps. The budget is bounded by the earlier ticket-enqueue time, the native wait deadline and a safety margin, and is rechecked immediately before network start and redirects. Backgrounding, clock rollback, source replacement, disposal and expiry invalidate stale authority.
-
-No synchronous network hook, main thread or OkHttp interceptor waits for JavaScript. Suspended JavaScript therefore cannot authorize stale protected work.
-
-## Redirects and observation
-
-Protected redirects are handled by the adapter, not by automatic credential forwarding. Same-origin targets must still satisfy catalog, path/class, tileset, context and ticket validity. Cross-origin, different-port, uncataloged or conflicting-context targets receive no forwarded grant. A redirect does not consume another admission for the same ticket.
-
-iOS does not rely on MapLibre forwarding `didReceiveResponse` to a configuration delegate. The adapter observes its own response. Native observation events contain only bounded identifiers/status and are private; they are not renderer readiness or commercial completion events.
-
-## Renderer readiness
-
-Admission success is not Map readiness. The private surface adapter requires current style acceptance, committed positive native layout and a fully rendered native map/frame after that layout. Background, layout loss, camera gesture/command epochs and style replacement invalidate the evidence. Resume re-arms native evidence; JavaScript animation frames and sleeps are not readiness proof.
-
-Camera commands carry private monotonically correlated tokens. A successful public controller command is acknowledged only after the native target is applied, not merely queued by the upstream React Native bridge. User gestures are classified from native gesture reasons and remain separate from programmatic commands.
-
-## Fixed transport bounds
-
-| Boundary                               |                                         Limit |
-| -------------------------------------- | --------------------------------------------: |
-| Live Map contexts per installation     |                                            16 |
-| Catalog resources per context          |                                           128 |
-| Native engine ingress per installation |                                         2,048 |
-| Protected work per context             |                                           128 |
-| Tickets per bridge batch               |                                             8 |
-| Resource URL                           | 2,048 characters including discriminator room |
-| Admission bridge payload               |                                 524,288 bytes |
-| Grant                                  |                             24,576 characters |
-| Protected transport deadline           |                       30 seconds from enqueue |
-| Validity safety margin                 |                                      1 second |
-| Protected redirects                    |                                             3 |
-| Protected response body                |                               8,388,608 bytes |
-| Pending bootstrap bridge work          |                                            32 |
-| Bootstrap request / response           |                          2,048 / 65,536 bytes |
-| Bootstrap deadline                     |                                    30 seconds |
-
-Cancellation retains transport capacity until the corresponding native cleanup boundary. Capacity bounds are transport safety limits, not product quotas or billing counters.
-
-## Application configuration
-
-The publishable mobile application credential and trusted API origin are configured through native application configuration only. They are not component props or JavaScript globals. See [Native application configuration](./native-configuration.md) for exact iOS/Android keys, credential grammar, origin normalization, rotation/revocation and the end-user threat-model boundary.
-
-## Local qualification
-
-The source-checkout [mounted Map harness](../harness/README.md) uses the real public Tileflow component in an existing development host and is excluded from package exports/packed files. It creates no service, runner or deployment.
-
-Before accepting a revision, qualify package build/types/tests, the exact Android and iOS native test suites, CocoaPods/SPM integration, two concurrent Maps, Strict Mode replay, source replacement during each asynchronous phase, theme success/rollback, controlled camera gestures/commands, background/resume, readiness ordering, redirects, ownership mutation and teardown retries. Inspect only secret-free fixture assertions and public events. Authored source and tests are not evidence that these checks passed.