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

package/README.md

@@ -1,6 +1,6 @@
 # @tileflow/react-native
 
-`@tileflow/react-native` provides a Tileflow `Map` backed by MapLibre Native on iOS and Android. It is pre-release. The first alpha release requires the bootstrap and Trusted Publisher checks in the [publishing guide](https://github.com/tileflow/tileflow-sdk/blob/main/PUBLISHING.md).
+`@tileflow/react-native` provides a Tileflow `Map` backed by MapLibre Native on iOS and Android. It is pre-release. Publication requires the repository’s protected release workflow.
 
 The package targets exactly React 19.2.0, React Native 0.83.10 and `@maplibre/maplibre-react-native` 11.5.0, with MapLibre Native Android 13.6.1 and iOS 6.31.0 through the pinned integration below. Expo consumers use Expo 55.0.31 with a native development build; Expo Go does not contain the required native modules.
 
@@ -99,7 +99,40 @@ Theme and `timeOfDay` changes cross-fade over 450 ms by default: a snapshot of t
 <Map source={source} themeBlend={{themes: ['night', 'dusk', 'day'], position}} style={{flex: 1}} />
 ```
 
-The first blend of a set of themes prepares every theme's style and replaces the native style once; moving `position` later changes the map without loading. Removing `themeBlend` returns to `theme`. Both keep the same native Map, context and session, and `ready` events wait for the fade. The device's reduce-motion setting changes at once. See [theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md#react-native) for what follows the position on native maps.
+The first blend of a set of themes prepares every theme's style and replaces the native style once; moving `position` later changes the map without loading. Removing `themeBlend` returns to `theme`. Both keep the same native Map, context and session, and `ready` events wait for the fade. The device's reduce-motion setting changes at once. See [theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md) for what follows the position on native maps.
+
+## Boundary choropleths
+
+A map that declares `boundaryAreas` and a `boundaryChoropleth()` without compiled `values` reads
+its colors from feature-state. `boundaryFeatureState` sets that state from the application, with
+the same rows and options as `useBoundaryFeatureState` on the web: rows keyed by the source's
+feature ID (`id`, or `ref` when the map promotes it), `labels` and `state`:
+
+<!-- docs:check -->
+
+```tsx
+import {Map, type MapSource} from '@tileflow/react-native';
+import {useMemo} from 'react';
+
+export function UnemploymentMap({
+  source,
+  rates,
+}: {
+  source: MapSource;
+  rates: ReadonlyMap<number, number>;
+}) {
+  // Memoize the values: each new object replaces the previous ones.
+  const values = useMemo(
+    () => ({joinBy: 'id' as const, rows: [...rates].map(([key, value]) => ({key, value}))}),
+    [rates],
+  );
+  return <Map source={source} boundaryFeatureState={{values}} style={{flex: 1}} />;
+}
+```
+
+Values survive theme changes: they are set again once the new style has loaded. `values: null`
+removes them. Rows keyed by codes the polygons do not carry are joined before they reach the app,
+on a server or at build time.
 
 ## Camera
 
@@ -144,16 +177,12 @@ Relative URLs are resolved with Core's native URL policy. Protected resources ar
 
 Glyph templates use a finite set of exact font-stack expansions. A later theme may extend that same template only through an acknowledged append-only finite union; it cannot change the resource scope, origin or identity.
 
-See [Private native resource admission](./docs/native-admission.md) for the transport and security boundaries.
-
 ## Hosted mobile application configuration
 
 Hosted native session delivery uses a scoped, revocable, publishable **mobile application credential** configured once in the native application. It authenticates the distributed application, not its end user. The manifest supplies `mapId`, `apiUrl` and `usageMode`; Tileflow requires the manifest API origin to exactly match the configured canonical HTTPS origin before bootstrap.
 
 There is intentionally no credential prop, JS setter, Provider, client object, package-name/bundle-ID authentication or attestation path in this version.
 
-See [Native application configuration](./docs/native-configuration.md) for the exact Android resource and iOS Info.plist keys, credential grammar, origin normalization, rotation/revocation guidance and threat model.
-
 ## Map options and presentation
 
 The public `mapOptions` object remains a positive allowlist. It includes the currently supported gesture/control options only. Style inputs, request transformation, headers and upstream lifecycle callbacks remain owned by Tileflow. Runtime validation rejects forged extra keys without reflecting their values.
@@ -169,10 +198,44 @@ The public lifecycle surface remains:
 - `onReadinessChange`;
 - `onThemeChange`;
 - controlled `onViewChange`;
-- `ref.getSourceState()`.
+- `ref.getSourceState()`;
+- `ref.retry()`.
 
 `getSourceState()` returns only the last safe projected source snapshot. Errors use existing bounded codes/fields/kinds. No URL, response body, native event, credential, grant, session object, native handle or raw cause enters public callbacks, refs or serializable state.
 
+`onError` reports `source-error`, `renderer-error` and, for Hosted session delivery, `session-error`. A `session-error` means Tileflow refused the session: the mobile credential was rejected (`NATIVE_SESSION_CREDENTIAL_REJECTED`), it does not authorize the Map (`NATIVE_SESSION_MAP_MISMATCH`), the Map was not found (`NATIVE_SESSION_MAP_NOT_FOUND`), its view or spending limit was reached (`NATIVE_SESSION_QUOTA_EXCEEDED`), or the service refused the session for another reason that trying again cannot change (`NATIVE_SESSION_REJECTED`), such as a Map that does not use session delivery. For `NATIVE_SESSION_REJECTED`, `event.error.reason` is the service's code when it sent one, for example `MOBILE_SESSION_MODE_REQUIRED`; it is a bounded identifier, never a message or response body. A `session-error` can arrive after the first load, when a renewal is refused. The map keeps what it has drawn but loads nothing new until you call `ref.retry()` or change the source:
+
+```tsx
+import {Map, type MapRef} from '@tileflow/react-native';
+import {useRef} from 'react';
+
+export function StoreMap() {
+  const map = useRef<MapRef>(null);
+  return (
+    <Map
+      ref={map}
+      source={{map: 'stores', manifestUrl: 'https://maps.example.com/tileflow/manifest.json'}}
+      onError={(event) => {
+        if (
+          event.type === 'session-error' &&
+          event.error.code === 'NATIVE_SESSION_QUOTA_EXCEEDED'
+        ) {
+          // Show your own notice; call map.current?.retry() once the limit is raised.
+        } else if (
+          event.type === 'session-error' &&
+          event.error.code === 'NATIVE_SESSION_REJECTED'
+        ) {
+          // event.error.reason, such as 'MOBILE_SESSION_MODE_REQUIRED', names the cause.
+        }
+      }}
+      style={{flex: 1}}
+    />
+  );
+}
+```
+
+Service outages, timeouts and rate limiting are not session errors. The map keeps using its current grant while it is valid and requests another after an increasing delay, from one second up to one minute, or after the `Retry-After` the service sends. A first load that failed this way prepares again on its own. `ref.retry()` also loads again after a source or renderer error, and changes nothing while the map is shown.
+
 ## Native integration
 
 Autolinking registers the private Android/iOS modules used by the mounted lifecycle. Android depends on the exact MapLibre React Native project and MapLibre Native 13.6.1. iOS uses the existing MapLibre React Native CocoaPod plus the exact MapLibre Native 6.31.0 Swift Package Manager product.
@@ -184,7 +247,7 @@ $MLRN.post_install(installer)
 tileflow_native_admission_post_install(installer)
 ```
 
-Do not add a second MapLibre Native CocoaPod. See [Private native resource admission](./docs/native-admission.md) for installation-order and teardown details.
+Do not add a second MapLibre Native CocoaPod.
 
 ## Source-checkout harness
 
@@ -213,8 +276,7 @@ remain in native vector or GeoJSON layers and are selected through semantic rend
 queries rather than thousands of React marker views.
 
 The application owns persistent selection and its presentation. The SDK emits normalized
-annotation or POI targets but no popup, callout, tooltip, sheet, panel or modal renderer. See
-[Native interaction contract](./docs/native-interactions.md).
+annotation or POI targets but no popup, callout, tooltip, sheet, panel or modal renderer.
 
 ## Current boundary
 
@@ -234,7 +296,3 @@ Source and tests describe contracts; they do not establish that a native build,
 fix arrives. Applications can compose a validated foreground fix through the existing accessible
 annotation and controlled-camera contracts while keeping permission, provider lifetime, privacy
 policy, status UI and recenter controls outside Tileflow.
-
-See [Application-owned foreground location](./docs/native-location.md) for the package-owned
-source-checkout recipe. The recipe is excluded from package exports and packed runtime files and
-imports no concrete location provider.

package/android/src/main/java/dev/tileflow/reactnative/AdmissionBootstrap.kt

@@ -6,7 +6,10 @@ internal object AdmissionBootstrapLimits {
 	const val QUEUE = 32
 	const val REQUEST_BYTES = 2048
 	const val RESPONSE_BYTES = 65536
-	const val TIMEOUT_MS = 30000L
+	const val RETRY_AFTER_CHARACTERS = 64
+	// Well inside the 30 s ticket and batch deadlines, so a stalled renewal fails its batch
+	// instead of letting the context retire under it.
+	const val TIMEOUT_MS = 10000L
 }
 
 internal class AdmissionBootstrapRequest(
@@ -18,7 +21,7 @@ internal class AdmissionBootstrapRequest(
 	override fun toString() = "AdmissionBootstrapRequest(redacted)"
 }
 
-internal class AdmissionBootstrapReply(val status: Int, val cacheControl: String, val body: ByteArray) {
+internal class AdmissionBootstrapReply(val status: Int, val cacheControl: String, val body: ByteArray, val retryAfter: String = "") {
 	override fun toString() = "AdmissionBootstrapReply(redacted)"
 }
 
@@ -86,7 +89,8 @@ internal class AdmissionBootstrap(
 			work.network = network.start(AdmissionBootstrapRequest(url, credential, body) { mayStart(work) }) { reply ->
 				scheduler.dispatch {
 					val valid = mayStart(work) && reply != null && reply.status in 100..599 &&
-						reply.cacheControl.length <= 1024 && reply.body.size <= AdmissionBootstrapLimits.RESPONSE_BYTES
+						reply.cacheControl.length <= 1024 && reply.retryAfter.length <= AdmissionBootstrapLimits.RETRY_AFTER_CHARACTERS &&
+						reply.body.size <= AdmissionBootstrapLimits.RESPONSE_BYTES
 					finish(work, if (valid) reply else null)
 				}
 			}

package/android/src/main/java/dev/tileflow/reactnative/AdmissionBootstrapOkHttpNetwork.kt

@@ -55,6 +55,8 @@ internal class AdmissionBootstrapOkHttpNetwork : AdmissionBootstrapNetwork {
 					val reply = try {
 						response.use {
 							val cacheControl = it.header("cache-control") ?: ""
+							// An oversized Retry-After is ignored rather than failing the reply.
+							val retryAfter = (it.header("retry-after") ?: "").takeIf { value -> value.length <= AdmissionBootstrapLimits.RETRY_AFTER_CHARACTERS } ?: ""
 							val body = it.body
 							if (cacheControl.length > 1024 || body == null || body.contentLength() > AdmissionBootstrapLimits.RESPONSE_BYTES) throw IOException("Invalid bootstrap response")
 							val bytes = ByteArrayOutputStream()
@@ -67,7 +69,7 @@ internal class AdmissionBootstrapOkHttpNetwork : AdmissionBootstrapNetwork {
 									bytes.write(buffer, 0, count)
 								}
 							}
-							AdmissionBootstrapReply(it.code, cacheControl, bytes.toByteArray())
+							AdmissionBootstrapReply(it.code, cacheControl, bytes.toByteArray(), retryAfter)
 						}
 					} catch (_: Exception) { null }
 					complete(reply)

package/android/src/main/java/dev/tileflow/reactnative/AdmissionEngine.kt

@@ -155,8 +155,10 @@ internal class AdmissionEngine(
 			work = item
 			context.work[item.id] = item
 			item.timer = scheduler.after(AdmissionLimits.WAIT_MS) {
-				if (context.batch?.tickets?.contains(item.id) == true) retire(context.id)
-				else fail(item)
+				// 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.batch?.tickets?.contains(item.id) == true) event(context, "cancel", mapOf("tickets" to listOf(item.id)))
+				fail(item)
 			}
 			scheduler.dispatch { drain(context) }
 		}

package/android/src/main/java/dev/tileflow/reactnative/TileflowNativeAdmissionModule.kt

@@ -125,7 +125,7 @@ class TileflowNativeAdmissionModule(context: ReactApplicationContext) : ReactCon
 				(bootstrapRequests ?: invalid()).start(context, request, url, credential, body) { reply ->
 					if (reply == null) reject(promise)
 					else promise.resolve(Arguments.makeNativeMap(mapOf(
-						"status" to reply.status, "cacheControl" to reply.cacheControl,
+						"status" to reply.status, "cacheControl" to reply.cacheControl, "retryAfter" to reply.retryAfter,
 						"bodyBase64" to Base64.encodeToString(reply.body, Base64.NO_WRAP))))
 				}
 			} catch (_: Exception) { reject(promise) }

package/dist/{contract-By3URNxS.d.ts → contract-BWT1jxqg.d.ts}

@@ -1,7 +1,7 @@
 import { MapProps as MapProps$1 } from '@maplibre/maplibre-react-native';
 import { ReactElement, ReactNode, Ref } from 'react';
 import { ViewProps } from 'react-native';
-import { TileflowNativeInitialView, TileflowNativeInitialViewOptions, TileflowNativeSource, TileflowNativeSourceOptions, TileflowNativeSourceState, TileflowNativeSourceError } from '@tileflow/core/native';
+import { TileflowNativeInitialView, TileflowNativeInitialViewOptions, TileflowNativeSource, TileflowNativeSourceOptions, TileflowBoundaryValues, TileflowBoundaryFamily, TileflowNativeSourceState, TileflowNativeSourceError } from '@tileflow/core/native';
 import { TileflowAnnotation, TileflowInteractionBinding, TileflowInteractionEvent, TileflowResolvedAnnotationTarget, TileflowResolvedPoiFeatureTarget, TileflowInteractionDiagnostic, TileflowAnnotationViewContext } from '@tileflow/interactions';
 
 /** Marker composition only. Selection presentation and native handles are not part of this context. */
@@ -58,6 +58,22 @@ type MapSourceProps = Readonly<{
      */
     themeBlend?: MapThemeBlend;
 }>;
+/**
+ * Application values on the map's Boundaries areas, for a choropleth that reads them with
+ * `feature-state`. The same rows and options as `useBoundaryFeatureState` on the web: rows keyed by
+ * the source's feature ID (`id`, or `ref` when the map promotes it), joined with
+ * `joinBoundaryRows` when the data carries other codes. Values survive theme changes; `null`
+ * removes them.
+ */
+type MapBoundaryFeatureState = Readonly<{
+    values: TileflowBoundaryValues | null;
+    /** Defaults to `boundaries`. */
+    family?: TileflowBoundaryFamily;
+    /** Also set the values on `boundary_label` points, for labels styled by value. */
+    labels?: boolean;
+    /** Feature-state key; it must match the choropleth's `state`. Defaults to `value`. */
+    state?: string;
+}>;
 type AllowedMapOptions = 'dragPan' | 'touchZoom' | 'doubleTapZoom' | 'doubleTapHoldZoom' | 'touchRotate' | 'touchPitch' | 'compass' | 'compassHiddenFacingNorth' | 'scaleBar';
 type OwnedMapOptions = Exclude<keyof MapProps$1, AllowedMapOptions> | 'container' | 'styleURL' | 'styleUrl' | 'transformRequest' | 'requestTransform' | 'requestHeaders';
 /** A positive allowlist. Style, interception, view and lifecycle remain adapter-owned. */
@@ -69,6 +85,7 @@ type MapPresentationProps = Readonly<{
     style?: ViewProps['style'];
     testID?: ViewProps['testID'];
     mapOptions?: MapOptions;
+    boundaryFeatureState?: MapBoundaryFeatureState;
 }>;
 type TileflowReady = Extract<TileflowNativeSourceState, {
     status: 'ready';
@@ -92,9 +109,29 @@ type MapSourceState = Readonly<{
     generation: number;
     error: MapSourceError;
 }>;
-/** A synchronous read of the last source snapshot. Does not trigger loading or native commands. */
+/**
+ * The Hosted session stopped: its credential, Map or quota was rejected, or Tileflow refused the
+ * session for another reason that trying again will not change (`NATIVE_SESSION_REJECTED`). The map
+ * keeps what it has drawn and loads nothing new until `ref.retry()` or another source. Service
+ * outages and rate limits retry on their own and are not reported.
+ */
+type MapSessionError = Readonly<{
+    code: 'NATIVE_SESSION_CREDENTIAL_REJECTED' | 'NATIVE_SESSION_MAP_MISMATCH' | 'NATIVE_SESSION_MAP_NOT_FOUND' | 'NATIVE_SESSION_QUOTA_EXCEEDED' | 'NATIVE_SESSION_REJECTED' | 'NATIVE_SESSION_INPUT_INVALID';
+    kind: 'terminal';
+    /**
+     * For `NATIVE_SESSION_REJECTED`, the service's code when its answer carried one, such as
+     * `MOBILE_SESSION_MODE_REQUIRED`. A bounded identifier, never a message or response body.
+     */
+    reason?: string;
+}>;
 type MapRef = Readonly<{
+    /** A synchronous read of the last source snapshot. Does not trigger loading or native commands. */
     getSourceState(): MapSourceState | undefined;
+    /**
+     * Loads again a map that stopped: after a `session-error` once its cause is resolved, for
+     * example a raised quota, or after a source or renderer error. A shown map is unaffected.
+     */
+    retry(): void;
 }>;
 /** The current style was accepted by the renderer; this alone does not establish a rendered frame. */
 type MapLoadEvent = Readonly<{
@@ -110,6 +147,10 @@ type MapErrorEvent = Readonly<{
 }> | Readonly<{
     type: 'renderer-error';
     generation: number;
+}> | Readonly<{
+    type: 'session-error';
+    generation: number;
+    error: MapSessionError;
 }>;
 /** The renderer owner must confirm readiness; a ready manifest alone is insufficient. */
 type MapReadinessChangeEvent = Readonly<{
@@ -168,4 +209,4 @@ type MapCameraProps = Readonly<{
 /** Complete Tileflow source, presentation, mount-stable camera and portable interaction inputs. */
 type MapProps<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = MapBaseProps & MapCameraProps & MapInteractionProps<TAnnotation>;
 
-export type { MapThemeTransition as A, MapView as M, MapViewChangeEvent as a, MapInitialViewInputs as b, MapCameraProps as c, MapProps as d, MapBaseProps as e, MapColorScheme as f, MapErrorEvent as g, MapEventHandlers as h, MapInteractionEvent as i, MapInteractionProps as j, MapLoadEvent as k, MapMarkerRenderContext as l, MapMarkerRenderer as m, MapOptions as n, MapPresentationProps as o, MapReadinessChangeEvent as p, MapRef as q, MapSelection as r, MapSource as s, MapSourceError as t, MapSourceProps as u, MapSourceState as v, MapTheme as w, MapThemeBlend as x, MapThemeChangeEvent as y, MapThemeSelection as z };
+export type { MapThemeChangeEvent as A, MapThemeSelection as B, MapThemeTransition as C, MapView as M, MapViewChangeEvent as a, MapInitialViewInputs as b, MapCameraProps as c, MapProps as d, MapBaseProps as e, MapBoundaryFeatureState as f, MapColorScheme as g, MapErrorEvent as h, MapEventHandlers as i, MapInteractionEvent as j, MapInteractionProps as k, MapLoadEvent as l, MapMarkerRenderContext as m, MapMarkerRenderer as n, MapOptions as o, MapPresentationProps as p, MapReadinessChangeEvent as q, MapRef as r, MapSelection as s, MapSessionError as t, MapSource as u, MapSourceError as v, MapSourceProps as w, MapSourceState as x, MapTheme as y, MapThemeBlend as z };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { ReactElement } from 'react';
 import { TileflowAnnotation } from '@tileflow/interactions';
 export { TileflowAnnotation, TileflowInteractionBinding, TileflowInteractionCoordinate, TileflowInteractionDiagnostic, TileflowPoiCategory, TileflowResolvedAnnotationTarget, TileflowResolvedPoiFeatureTarget } from '@tileflow/interactions';
-import { d as MapProps } from './contract-By3URNxS.js';
-export { e as MapBaseProps, c as MapCameraProps, f as MapColorScheme, g as MapErrorEvent, h as MapEventHandlers, b as MapInitialViewInputs, i as MapInteractionEvent, j as MapInteractionProps, k as MapLoadEvent, l as MapMarkerRenderContext, m as MapMarkerRenderer, n as MapOptions, o as MapPresentationProps, p as MapReadinessChangeEvent, q as MapRef, r as MapSelection, s as MapSource, t as MapSourceError, u as MapSourceProps, v as MapSourceState, w as MapTheme, x as MapThemeBlend, y as MapThemeChangeEvent, z as MapThemeSelection, A as MapThemeTransition, M as MapView, a as MapViewChangeEvent } from './contract-By3URNxS.js';
+import { d as MapProps } from './contract-BWT1jxqg.js';
+export { e as MapBaseProps, f as MapBoundaryFeatureState, c as MapCameraProps, g as MapColorScheme, h as MapErrorEvent, i as MapEventHandlers, b as MapInitialViewInputs, j as MapInteractionEvent, k as MapInteractionProps, l as MapLoadEvent, m as MapMarkerRenderContext, n as MapMarkerRenderer, o as MapOptions, p as MapPresentationProps, q as MapReadinessChangeEvent, r as MapRef, s as MapSelection, t as MapSessionError, u as MapSource, v as MapSourceError, w as MapSourceProps, x as MapSourceState, y as MapTheme, z as MapThemeBlend, A as MapThemeChangeEvent, B as MapThemeSelection, C as MapThemeTransition, M as MapView, a as MapViewChangeEvent } from './contract-BWT1jxqg.js';
 import '@maplibre/maplibre-react-native';
 import 'react-native';
 import '@tileflow/core/native';