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

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

@@ -0,0 +1,11 @@
+import { TileflowNativeSourceState } from '@tileflow/core/native';
+import { v as MapSourceState } from '../contract-DWs-lDPo.js';
+import '@maplibre/maplibre-react-native';
+import 'react';
+import 'react-native';
+import '@tileflow/interactions';
+
+/** Read only a canonical Core snapshot; never expose its URLs, style body or Error instance. */
+declare function projectMapSourceState(state: TileflowNativeSourceState | undefined): MapSourceState | undefined;
+
+export { projectMapSourceState };

package/dist/internal/source-state.js

@@ -0,0 +1,26 @@
+// src/source-state.ts
+function projectMapSourceState(state) {
+  if (!state) return void 0;
+  if (state.status === "loading")
+    return Object.freeze({ status: "loading", generation: state.generation });
+  if (state.status === "error") {
+    return Object.freeze({
+      status: "error",
+      generation: state.generation,
+      error: Object.freeze({
+        code: state.error.code,
+        field: state.error.field,
+        kind: state.error.kind
+      })
+    });
+  }
+  return Object.freeze({
+    status: "ready",
+    generation: state.generation,
+    map: state.map.name,
+    theme: Object.freeze({ name: state.theme.name, colorScheme: state.theme.colorScheme })
+  });
+}
+export {
+  projectMapSourceState
+};

package/dist/native-admission-contract-k7LKE1vW.d.ts

@@ -0,0 +1,89 @@
+import { NativeSessionResourceScope } from './internal/session.js';
+
+type NativeAdmissionResource = Readonly<{
+    url: string;
+    scope: NativeSessionResourceScope;
+    tilesetId?: string;
+    template?: 'tile' | 'glyphs';
+    fontStacks?: readonly string[];
+}>;
+type NativeAdmissionCode = 'NATIVE_ADMISSION_INVALID' | 'NATIVE_ADMISSION_CANCELLED' | 'NATIVE_ADMISSION_EXPIRED' | 'NATIVE_ADMISSION_DENIED' | 'NATIVE_ADMISSION_OWNERSHIP' | 'NATIVE_ADMISSION_UNAVAILABLE';
+type NativeAdmissionTicket = Readonly<{
+    ticket: string;
+    url: string;
+}>;
+type NativeAdmissionResult = Readonly<{
+    ticket: string;
+    kind: 'grant';
+    validForMs: number;
+    authority: Readonly<{
+        grant: string;
+        mapId: string;
+        resourceOrigins: readonly string[];
+        resourceScopes: readonly NativeSessionResourceScope[];
+        tilesetIds: readonly string[];
+    }>;
+}> | Readonly<{
+    ticket: string;
+    kind: 'delegate';
+}> | Readonly<{
+    ticket: string;
+    kind: 'reject';
+    code: NativeAdmissionCode;
+}>;
+type ContextEvent = Readonly<{
+    installation: string;
+    context: string;
+    generation: number;
+}>;
+type NativeAdmissionEvent = (ContextEvent & Readonly<{
+    kind: 'batch';
+    batch: string;
+    tickets: readonly NativeAdmissionTicket[];
+}>) | (ContextEvent & Readonly<{
+    kind: 'cancel';
+    tickets: readonly string[];
+}>) | (ContextEvent & Readonly<{
+    kind: 'retired';
+    code: NativeAdmissionCode;
+}>) | (ContextEvent & Readonly<{
+    kind: 'response';
+    status: number;
+}>) | Readonly<{
+    kind: 'lifecycle';
+    installation: string;
+    foreground: boolean;
+}> | Readonly<{
+    kind: 'ownershipLost';
+    installation: string;
+}>;
+type NativeContextAck = Readonly<{
+    context: string;
+    generation: number;
+}>;
+type NativeRemovalAck = Readonly<{
+    removed: boolean;
+    ownershipLost: boolean;
+}>;
+type NativeAdmissionBridge = Readonly<{
+    subscribe(listener: (event: NativeAdmissionEvent) => void): () => void;
+    install(): Promise<Readonly<{
+        installation: string;
+    }>>;
+    registerContext(installation: string, registration: Readonly<{
+        mapId: string | null;
+        resources: readonly NativeAdmissionResource[];
+    }>): Promise<NativeContextAck>;
+    extendContext?(installation: string, context: string, resources: readonly NativeAdmissionResource[]): Promise<Readonly<{
+        resources: number;
+    }>>;
+    retireContext(installation: string, context: string): Promise<Readonly<{
+        retired: true;
+    }>>;
+    completeBatch(installation: string, context: string, generation: number, batch: string, results: readonly NativeAdmissionResult[]): Promise<Readonly<{
+        accepted: number;
+    }>>;
+    remove(installation: string): Promise<NativeRemovalAck>;
+}>;
+
+export type { NativeAdmissionEvent as N, NativeAdmissionResource as a, NativeContextAck as b, NativeAdmissionResult as c, NativeRemovalAck as d, NativeAdmissionCode as e, NativeAdmissionBridge as f };

package/docs/native-admission.md

@@ -0,0 +1,108 @@
+# 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.3.10, MapLibre Native Android 13.2.0 and MapLibre Native iOS 6.26.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.26.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.

package/docs/native-configuration.md

@@ -0,0 +1,210 @@
+# 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.

package/docs/native-interactions.md

@@ -0,0 +1,161 @@
+# Native interaction contract
+
+The React Native `Map` accepts portable annotations, semantic interaction bindings, activation
+callbacks and an optional marker renderer. It exposes normalized targets and bounded data. The
+application owns persistent selection and its presentation. Tileflow does not render a popup,
+callout, tooltip, sheet, panel or modal.
+
+The mounted implementation uses a private renderer-neutral foundation. It reuses schemas, target
+types and diagnostics from the ordinary `@tileflow/interactions` root without
+importing its browser adapter, DOM implementation or `maplibre-gl`. Native map handles, style
+proofs, query ports and owners are not exported by `@tileflow/react-native`.
+
+## Public Map inputs
+
+`Map` is generic over the supplied annotation type, so application data remains typed in
+`renderMarker` and `onInteractionEvent`. `annotations` and `interactions` are complete portable
+documents, not patches. The shared annotation and binding validators still accept web presentation
+metadata, but mobile does not use `popup` or `tooltip` fields.
+
+`renderMarker` composes marker content only. Tileflow retains the native marker host, coordinate,
+stable key, activation and authoritative accessibility wrapper. Without a renderer, Tileflow shows
+a bounded default marker. Each marker has the annotation label, a 44-by-44-point minimum touch
+target, button semantics and disabled accessibility state. Custom marker content does
+not create another accessible target.
+
+`onInteractionEvent` receives `target:activate` events for annotations and semantic POIs.
+`onInteractionDiagnostic` receives fixed structured diagnostics. There is no mobile selection-state
+prop, state callback or popup event. The application can retain the selected target in its own
+state and choose what, if anything, to render.
+
+## Input ownership and validation
+
+One owner receives complete annotation and interaction-binding inputs. Omitted collections mean
+empty collections, not partial document patches.
+
+The owner uses the portable validators before planning any annotation changes. Invalid annotation
+or binding replacements preserve the entire previous valid collection. The initial fallback is an
+empty collection.
+
+Inputs are copied and frozen before they become committed values. The portable JSON perimeter
+rejects accessors, unsupported prototypes, non-finite numbers, unsafe keys, cycles, shared object
+references and oversized documents. The native foundation uses the same portable bounds: at most
+1,000 annotations, 100 bindings, 256,000 JSON bytes, depth 64, 20,000 nodes and 50,000 properties per
+document. It does not expand large feature sets into annotation hosts.
+
+Diagnostics retain the portable code, level and a fixed bounded message. They do not include raw
+validator paths, input values, physical layer identifiers, style JSON, URLs or native error causes.
+Replacing callbacks alone does not change snapshots or annotation identities.
+
+## Annotation reconciliation
+
+The private annotation plan contains `create`, `update`, `retain`, `remove` and final `order`.
+Planning uses stable validated annotation IDs. An existing marker ID retains its future host when
+coordinates, data or declarative surfaces change. Its update entry contains the old and new
+validated definitions. New IDs create entries; absent IDs produce removals in previous order.
+Unchanged IDs are retained, and final order follows the new document.
+
+An invalid replacement produces no partial creates, updates or removals. The mounted adapter uses
+the annotation ID as the React and native marker identity, so updates and reordering retain the
+compatible host while removal retires it.
+
+## Activation without selection ownership
+
+A valid annotation activation emits one normalized `target:activate` event with annotation data,
+coordinate and optional binding ID. A semantic POI activation emits the same event type with a
+bounded POI target. No event changes or clears application selection. The application decides how
+to handle removed entities, style changes and dismissal.
+
+A syntactically invalid annotation or binding replacement retains the last valid collection. New
+touches, source/style replacement, backgrounding and unmount discard pending semantic queries, so
+late results cannot activate a target from a retired map or style.
+
+## Finalized-style query port
+
+The semantic adapter receives a private lease for exactly one finalized style on one native Map.
+The lease supplies its style description, an ownership check and a cancelable asynchronous query
+operation. Its ownership check must establish the exact current native style and map, not merely
+compare style JSON. Style replacement must invalidate the old lease before another query can use
+it.
+
+Each query receives an immutable request containing the touch point, the relevant declared layer
+IDs and a result limit. A result envelope must echo the identical private request object. The
+platform adapter may construct that envelope only after rechecking native map/style ownership.
+Native handles never cross this neutral boundary. The adapter rejects a response associated with
+another request or Map even when the physical URLs or layer names happen to match.
+
+The mounted adapter uses the existing public query on the pinned MapLibre React Native Map. Because
+its iOS and Android serializers omit physical provenance, Tileflow queries one verified semantic
+layer at a time in finalized topmost order. The exact single-layer filter supplies the physical
+layer, source and source-layer identity that the neutral adapter verifies again. Results preserve
+their within-layer order and share one global 512-feature bound. This adds no Swift, Kotlin or
+public query API.
+
+A lease becomes current only after the private Tileflow native-surface owner accepts the matching
+style token. A JavaScript style-loaded callback or equal style JSON is insufficient. A newer touch
+rotates the query lease; style or source replacement, backgrounding and unmount permanently retire
+the old proof. Upstream queries have no abort handle, so cancellation is logical: Tileflow settles
+the old operation as stale immediately, stops issuing further layer queries and ignores late
+results.
+
+## Semantic POI rules
+
+Only finalized `tileflow:interaction-manifest` metadata with exact version 2 is accepted. The
+adapter checks the POI identity convention, deduplication tuple, representation-priority list,
+field mapping, category vocabulary, rendered-topmost ordering and pointer-coordinate anchors.
+The artifact's `animation-frame` frequency field is its existing version-2 vocabulary; it does not
+introduce hover or JavaScript-frame scheduling into the native adapter.
+
+Every declared semantic layer must exist exactly once in that same style and match its declared
+source and source-layer. The source must exist. All declared POI representations share one
+source/source-layer feature-ID namespace. The adapter bounds the physical style inventory at 4,096
+layers and the semantic inventory at 256 declared layers. Missing or inconsistent metadata fails
+closed with `SEMANTIC_MANIFEST_MISMATCH`.
+
+Queries include only declared layers relevant to the current POI bindings and category filters.
+The port must supply rendered-topmost results. Duplicate representations of one stable feature ID
+use the manifest's representation priority, then layer priority, while retaining the earliest
+rendered position of that identity. Numeric and string IDs are distinct. Features from undeclared
+layers are excluded; an owned feature with a mismatched source or source-layer invalidates the
+query rather than being relabeled.
+
+A query processes at most 512 returned features. The port must report overflow rather than silently
+truncate a result whose omitted features could change representation selection. The native
+boundary emits only the existing semantic POI target shape, without physical layer identities.
+Properties are restricted to category, filter rank, size rank, icon, name and type. Category and
+rank ranges follow the portable contract; icon/type use bounded snake-case values and text uses the
+portable 4,096-character limit. Unknown fields and unsafe property accessors are not forwarded.
+
+Touch is the only activation modality in this adapter. There is no inferred hover, tooltip,
+long-press or keyboard behavior. An activation without a stable feature ID can still emit a target
+event. When present, feature IDs are safe integers or nonempty strings of at most 128 characters;
+no property-based fallback ID is invented.
+
+## Retirement and observation
+
+Each mounted Map has independent inputs, annotation plans, style proofs,
+query tickets and subscribers. No authority, Map identity or asynchronous operation is shared
+between Maps. Marker and map delivery for one touch share one claim, so a marker activation cannot
+also activate a semantic feature underneath it.
+
+Ownership is checked again after asynchronous results and before event publication. Late results
+from disposed owners or retired styles are inert. Reentrant cancellation, observer replacement,
+exceptions and rejected observer promises cannot transfer ownership to another Map. Disposal is
+idempotent and exposes a final safe empty snapshot plus the annotation removal plan.
+
+Selection presentation remains outside this contract. The application owns its layout, focus,
+dismissal and accessibility behavior. Device location is also separate and requires an explicit
+application-owned permission and provider flow.
+
+## Location composes as an ordinary application annotation
+
+Foreground device location does not extend the interaction owner or semantic query port. An
+application that chooses to display its latest validated fix can provide one stable-ID annotation
+through the existing `annotations` input, and remove that annotation when permission is revoked or
+the provider becomes unavailable. Tileflow does not request permission, start observation or
+recenter the camera when that annotation changes.
+
+See [Application-owned foreground location](./native-location.md) for the source-checkout recipe.
+The application remains responsible for provider lifetime, privacy policy, recenter controls and
+status/error UI, and the recipe does not alter the rule that all selection presentation remains
+application-owned.