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

package/dist/internal/session.d.ts

@@ -47,7 +47,9 @@ type HostedNativeSessionErrorKind = 'terminal' | 'recoverable' | 'cancelled';
 declare class HostedNativeSessionError extends Error {
     readonly code: HostedNativeSessionErrorCode;
     readonly kind: HostedNativeSessionErrorKind;
-    constructor(code: HostedNativeSessionErrorCode);
+    /** For `NATIVE_SESSION_REJECTED`, the service's code when its answer carried one. */
+    readonly reason?: string;
+    constructor(code: HostedNativeSessionErrorCode, reason?: string);
 }
 type HostedNativeSessionAuthority = Readonly<{
     grant: string;
@@ -71,6 +73,7 @@ type HostedNativeResourcePolicy = Readonly<Pick<HostedNativeSessionAuthority, 'm
 type SafeError = Readonly<{
     code: HostedNativeSessionErrorCode;
     kind: HostedNativeSessionErrorKind;
+    reason?: string;
 }>;
 type Lifecycle = 'foreground' | 'background';
 type HostedNativeSessionState = Readonly<{

package/dist/internal/session.js

@@ -24,6 +24,8 @@ 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;
@@ -67,7 +69,8 @@ var TERMINAL_CODES = /* @__PURE__ */ new Set([
   "NATIVE_SESSION_CREDENTIAL_REJECTED",
   "NATIVE_SESSION_MAP_MISMATCH",
   "NATIVE_SESSION_MAP_NOT_FOUND",
-  "NATIVE_SESSION_QUOTA_EXCEEDED"
+  "NATIVE_SESSION_QUOTA_EXCEEDED",
+  "NATIVE_SESSION_REJECTED"
 ]);
 var ERROR_MESSAGES = {
   NATIVE_SESSION_INPUT_INVALID: "Native session configuration is invalid.",
@@ -86,13 +89,16 @@ var ERROR_MESSAGES = {
   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) {
@@ -221,10 +227,10 @@ function createHostedNativeSessionController(input) {
     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 = Object.freeze({ code: error.code, kind: error.kind });
+    retryError = safeError(error);
   }
   function rotateIfRequired(at) {
-    if (terminal) throw new HostedNativeSessionError(terminal.code);
+    if (terminal) throw errorFrom(terminal);
     if (!activeSession || binding.kind !== "hosted") return;
     if (at - activeSession.startedAt < ROTATION_AGE_MS && activeSession.requestCount < ROTATION_REQUEST_LIMIT) {
       return;
@@ -258,7 +264,7 @@ function createHostedNativeSessionController(input) {
     return current;
   }
   async function ensureAuthority(session, at) {
-    if (terminal) throw new HostedNativeSessionError(terminal.code);
+    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 };
     }
@@ -270,7 +276,7 @@ function createHostedNativeSessionController(input) {
       if (session.authority && session.authority.clockEpoch === clock.epoch && session.authority.validUntil > at) {
         return { authority: session.authority, session };
       }
-      throw new HostedNativeSessionError(retryError.code);
+      throw errorFrom(retryError);
     }
     const operationBinding = binding;
     const abort = new SessionAbortController();
@@ -297,14 +303,16 @@ function createHostedNativeSessionController(input) {
           const normalized = abort.signal.aborted ? abort.error() : normalizeError(error);
           const target = latestSession(session);
           if (normalized.kind === "terminal" && binding === operationBinding && !terminal) {
-            const failure = Object.freeze({ code: normalized.code, kind: normalized.kind });
+            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);
+            for (const pending of [...operations]) {
+              pending.abort(failure.code, failure.reason);
+            }
             if (binding === operationBinding && rejectedSession) {
               publishSession(rejectedSession, "error", failure);
             }
@@ -313,7 +321,7 @@ function createHostedNativeSessionController(input) {
             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;
@@ -339,7 +347,7 @@ 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;
@@ -349,14 +357,15 @@ function createHostedNativeSessionController(input) {
       }
       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) {
-      const failure = statusError(response.status, body);
+      const failure = statusError(response.status, body, size);
       const delay = retryAfterMs(response.headers, now);
       if (delay !== null) retryAfterDelays.set(failure, delay);
       throw failure;
@@ -494,7 +503,7 @@ function createHostedNativeSessionController(input) {
       if (bindingGeneration !== expectedGeneration) {
         throw new HostedNativeSessionError("NATIVE_SESSION_REPLACED");
       }
-      if (terminal) throw new HostedNativeSessionError(terminal.code);
+      if (terminal) throw errorFrom(terminal);
       checkedAt = readClock();
       if (resolved.authority.clockEpoch === clock.epoch && resolved.authority.validUntil > checkedAt) {
         admittedAuthorities.set(resolved.authority.public, resolved.authority);
@@ -569,7 +578,7 @@ function createHostedNativeSessionController(input) {
       if (disposed) throw new HostedNativeSessionError("NATIVE_SESSION_DISPOSED");
       lifecycle = "foreground";
       if (terminal) {
-        const error = new HostedNativeSessionError(terminal.code);
+        const error = errorFrom(terminal);
         publish(currentSnapshot());
         throw error;
       }
@@ -842,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 = "";
@@ -890,7 +899,7 @@ function decodeUtf8(bytes) {
 function hasNoStore(value) {
   return typeof value === "string" && value.split(",").some((part) => part.trim().toLowerCase() === "no-store");
 }
-function statusError(status, body) {
+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");
@@ -902,7 +911,21 @@ function statusError(status, body) {
   if (status === 408 || status >= 500 && status <= 599) {
     return new HostedNativeSessionError("NATIVE_SESSION_UNAVAILABLE");
   }
-  return new HostedNativeSessionError("NATIVE_SESSION_REJECTED");
+  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) {
@@ -952,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({
@@ -972,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 {
@@ -985,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 { x as MapSourceState } from '../contract-BaK24QZD.js';
+import { x as MapSourceState } from '../contract-BWT1jxqg.js';
 import '@maplibre/maplibre-react-native';
 import 'react';
 import 'react-native';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react-native",
-  "version": "0.1.0-alpha.7",
+  "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.42 <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,124 +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.
-
-A bootstrap ends after 10 seconds, well inside the 30-second protected transport deadline. A stalled renewal therefore fails its bridge batch, and the tickets waiting on it, instead of outliving them. A ticket whose own deadline passes while JavaScript is still answering its batch fails alone; only a batch that JavaScript does not answer within 30 seconds retires the context. When admission retires the context of a mounted Map, the Map reports `renderer-error` and opens a new context for the same source, up to three times without a successful load in between.
-
-## Session failures
-
-The controller classifies each bootstrap or renewal failure:
-
-| Response                                                                       | Result                                                  |
-| ------------------------------------------------------------------------------ | ------------------------------------------------------- |
-| 401, 403, 404                                                                  | Stops the session until `ref.retry()` or another source |
-| 429 with `COMMERCIAL_MAP_LIMIT_REACHED` or `COMMERCIAL_SPENDING_LIMIT_REACHED` | Stops the session until `ref.retry()` or another source |
-| Any other 429                                                                  | Rate limited: retries after a delay                     |
-| 408, 5xx, network failure or timeout                                           | Unavailable: retries after a delay                      |
-| Another status, or a response that breaks the session contract                 | Retries after a delay                                   |
-
-A stopped session reports `session-error` through `onError`, including when a renewal is refused after the first load. A delay starts at one second and doubles up to one minute; a `Retry-After` in seconds or as an HTTP date lengthens it, up to 15 minutes. During the delay no bootstrap leaves the device, and a grant that is still valid keeps admitting protected requests. A successful bootstrap or `ref.retry()` clears the delay.
-
-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                     |                                    10 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.

package/docs/native-configuration.md

@@ -1,210 +0,0 @@
-# Native application configuration
-
-This guide describes the private application-configuration reader used by the mounted Tileflow
-`Map` in `@tileflow/react-native`. Its root exports the mounted `Map` and public types; the
-configuration reader remains private. Mobile credentials remain application
-configuration: there is no credential prop, JavaScript setter, provider, public configuration
-object or public configuration subpath.
-
-Importing `@tileflow/react-native` does not read configuration, install networking, start a session,
-acquire admission or create a native Map. Configuration is read lazily only when a mounted source
-resolves to Hosted session delivery. Follow the [package setup](../README.md) and the
-[native admission guide](native-admission.md) for the exact native dependencies and installation
-order. No Expo config plugin is supplied.
-
-## Prerequisites and identity
-
-Hosted native production requires a claimed Tileflow account/project, a Hosted Map and its scoped,
-revocable, publishable mobile application credential. The credential authenticates the distributed
-application, not an end user. There is no Tileflow end-user login, account provider or authentication
-hook in this integration. Web deployment with allowed-domain authorization is a different mechanism.
-A compatible SDK/API pair is required; this document is not a publication or availability claim.
-
-Use only the publishable mobile credential, whose exact grammar is `tf_public_` followed by
-48 lowercase hexadecimal characters, for a total of 58 ASCII characters. A CLI, deployment,
-administration or other privileged credential must never enter application configuration.
-
-The two logical fields are `apiOrigin` and `credential`. `apiOrigin` is the API origin approved by
-the application operator, not a value copied automatically from a remote manifest. The native
-session contract has no implicit origin. The examples below use `api.example.test` and an
-intentionally invalid credential placeholder; replace both in the application build.
-
-## Configure iOS
-
-In the **application target's Info.plist**, add one `TileflowMobileConfiguration` key of type Array.
-Its two String elements are `apiOrigin=...` and `credential=...`:
-
-```xml
-<key>TileflowMobileConfiguration</key>
-<array>
-  <string>apiOrigin=https://api.example.test</string>
-  <string>credential=YOUR_PUBLISHABLE_MOBILE_CREDENTIAL</string>
-</array>
-```
-
-Place this in the final application plist, not in a pod, framework, MapLibre configuration or
-`InfoPlist.strings`. When Xcode generates the plist, ensure the resulting application target still
-contains one literal array. Application-owned build substitution may supply each string, but
-unresolved placeholders fail validation.
-
-The autolinked `TileflowNativeConfiguration` module reads only `NSBundle.mainBundle` when its
-private asynchronous reader is requested. It exports no constants or events. Constructing the
-module, importing the package and mounting a non-session Map do not perform that read.
-
-## Configure Android
-
-In the application's `android/app/src/main/res/values/tileflow.xml`, add one literal String Array:
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-  <string-array name="tileflow_mobile_configuration" translatable="false">
-    <item>apiOrigin=https://api.example.test</item>
-    <item>credential=YOUR_PUBLISHABLE_MOBILE_CREDENTIAL</item>
-  </string-array>
-</resources>
-```
-
-The array belongs to the application package. Do not use AndroidManifest metadata, BuildConfig,
-a system property, an alias or a second runtime input. Both entries must be literal strings;
-references such as `@string/...`, `@array/...`, theme attributes and styled strings are rejected.
-Build flavors may deliberately provide their own single final application configuration, but each
-resulting application must be checked independently.
-
-`TileflowNativeAdmissionPackage` autolinks the configuration reader alongside the private admission
-and surface modules. Constructing those modules does not read configuration or install networking.
-The library includes a resource-shrinker keep declaration for the dynamically located array; the
-application's optimized release build must retain it. The library ships no default configuration
-array or embedded credential.
-
-## Array and origin contract
-
-Both platforms use the same bounded list of exactly two `key=value` strings. Order is irrelevant;
-keys are case-sensitive. Split only at the first equals sign. Missing, empty, additional,
-wrong-typed or duplicate entries fail closed. Each complete entry is limited to 2,080 UTF-16 code
-units.
-
-The application-owned `apiOrigin` is at most 2,048 UTF-16 code units. Normalization is deliberately
-limited to the HTTPS scheme and ASCII hostname, omission of port 443 and removal of one optional
-root slash. For example, application configuration `HTTPS://API.Example.test:443/` becomes
-`https://api.example.test`. Port 8443 remains distinct. The grammar permits ASCII DNS labels or
-canonical dotted-decimal IPv4; IPv6 literals are outside this application-configuration grammar.
-
-Ports are decimal 1–65535 without leading zeroes. HTTP, user-info, non-root paths, query strings,
-fragments, whitespace, backslashes, percent escapes, wildcards, trailing host dots, Unicode hostname
-conversion and shortened/octal/hexadecimal/integer IPv4 forms are rejected.
-
-The **remote manifest is not normalized into trust**. Its declared `apiUrl` must already be the exact
-canonical string stored in the application snapshot. A trailing slash, explicit default port or
-case variation in the remote declaration is rejected, even if normalizing it would produce the same
-origin. Equality includes scheme, host and non-default port; there is no suffix or subdomain match.
-If both root and map-level API declarations are present, they must agree exactly.
-
-## Source-to-session boundary
-
-Use the public Native manifest URL returned by an explicit compatible
-[`deploy --with-native`](../../cli/docs/native-artifacts.md#publish-web-and-native-together):
-
-```text
-https://api.example.test/maps/map_0123456789abcdef/native/manifest.json
-```
-
-The `Map` source remains `{map, manifestUrl}`. `map` is the authored map name, not the managed Map ID.
-The initial document is bounded, one-map, version-1 public metadata. It contains theme names,
-identity, revisions and references, not Style JSON or authority. It receives no credential or grant.
-
-The private binding resolver consumes the current resolved Core source, not an executable config or
-a renderer style. Only `map.usageMode === 'session'` can request application configuration. It
-requires the declared Hosted `mapId`, exact `apiUrl`, agreement between the resolved logical map
-name and selected source, and both the original requested URL and final response URL equal to the
-canonical Hosted route for that managed Map. A redirect to another origin, Map, CDN route or query
-alias is rejected. URL identity is a selector checked against the document, not authority.
-
-A missing `usageMode` produces the existing direct binding without evaluating configuration only for
-a non-Hosted source. A document obtained from the reserved Hosted Native route cannot omit that mode
-to downgrade into direct delivery. Local, self-hosted and other non-session sources otherwise keep
-their existing account-free behavior. Unknown modes, malformed session metadata, origin mismatches
-or conflicting Map identity fail before a Hosted binding is delivered.
-
-The publishable credential is sent **only** to the application's configured API origin at
-`POST /v1/sessions/start`. The existing bootstrap transport does not follow redirects. Neither a
-manifest URL nor a manifest-declared `apiUrl` can select a different credential destination. Styles,
-TileJSON, tiles, sprites, glyphs and fonts use the existing resource grant, never that credential.
-
-The resolver itself has no renderer or resource-admission authority. The mounted Map passes the
-acknowledged binding into its private admission/session owner only after source resolution. Creating
-a resolver does not call `acquire()`, and importing the package does not construct a resolver.
-
-## Deployment revisions and stale discovery
-
-Hosted themes carry mandatory revision hashes and versioned protected style URLs of the form
-`/maps/<mapId>/native/v<deploymentVersion>/<theme>.json`. Every theme in one manifest belongs to the
-same deployment version. The server checks current deployment ownership and verifies stored style
-bytes against the revision. The mounted owner checks the returned style URL and its
-Map/theme/deployment/revision metadata before projecting resources or creating a renderer.
-
-If the root protected style cannot be read or fails this correspondence, the owner may discard its
-cached discovery document and reload the canonical manifest **once per explicit source/theme
-selection**. This recovery retains the same session and admission context. A refresh cannot switch
-Map, origin or delivery mode, or move backwards to an older deployment. Child-resource failures do
-not replenish that retry budget. A second failure uses the existing safe error or theme-rollback
-path. It never composes a new active style with stale public metadata silently.
-
-A public manifest GET, session start or Map render is not itself a commercial completion event.
-Server completion remains conditional on an eligible protected GET returning 200/206 under the
-existing admission contract. Disabled mobile delivery fails closed even for valid public references.
-
-## Mounted ownership, caching and cancellation
-
-The native reader caches one immutable application snapshot, or one safe failure, for the
-application process. It does not retain a React context. JavaScript coalesces native reads and copies
-the result into a frozen private value. Each mounted Map still owns an independent pending binding,
-session controller, admission context, callbacks and renderer lifetime. Shared immutable application
-configuration never implies shared grants, counters or source ownership.
-
-Source replacement and Map disposal invalidate that owner's in-flight binding immediately. A late
-configuration success or failure cannot deliver authority to a retired owner. Retiring one Map does
-not cancel another Map's access to the process-level immutable configuration snapshot. Configuration
-is not hot-reloaded; restart the application process after changing native values.
-
-The configuration reader installs no timeout, timer, background poller or service. One unresolved
-native read can remain pending, but every Map resolver remains independently disposable. Camera,
-resource projection and rendered-readiness logic are owned elsewhere in the mounted Map runtime;
-they are not configuration-reader responsibilities.
-
-## Public credential threat model and rotation
-
-A credential distributed inside a mobile application is extractable. Native configuration is not a
-secret vault, proof of installation authenticity or end-user authentication. This version does not
-authenticate with bundle ID, package name, signing identity or attestation. Origin binding prevents
-the SDK from forwarding its configured credential to an origin selected by an untrusted manifest;
-it does not stop a party that has copied the publishable credential from making its own requests.
-Scope, revocation and server-side authorization remain necessary.
-
-The credential crosses only the private reader/binding/bootstrap path. It is not a native grant and
-is not a resource URL, cache key, public ref field, source state, renderer event or diagnostic.
-Errors use fixed internal codes/messages rather than configured values or native causes. Do not log
-native module responses, credentials, bootstrap bodies or grant material.
-
-For rotation, issue a new credential with the intended Map scope, update the same native entries,
-rebuild and distribute the application, then retire the old credential according to the rollout
-policy. Revoking an old credential may stop installed versions that still contain it. Do not repair
-that failure with a JavaScript override or a second credential source.
-
-A future Expo plugin, if introduced, would write these same native values rather than create another
-runtime configuration channel. No plugin or end-user login is part of this integration. Selection
-presentation and foreground-location policy remain application-owned; this contract adds neither UI
-nor a location API.
-
-## Validation boundary
-
-The authored source tests cover grammar, exact origin matching, source/final URL identity, lazy reads,
-safe failures, stale results, bounded discovery recovery, independent resolvers and the absence of a
-public credential surface. Native tests cover parser boundaries, versioned style ownership,
-duplicate/wrong-typed configuration, resource literals, caching and reentrancy. Package tests protect
-autolinking, exact peers, private configuration declarations and archive contents.
-
-Those sources are not execution evidence. Local qualification must additionally exercise the final
-iOS Info.plist and Android resource extraction, resource shrinking, bridge registration, cold starts,
-concurrent mounted Maps, direct versus session sources, replacement/disposal, stale public metadata
-and corrected/revoked credentials in the pinned native host.