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

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.
 
@@ -91,7 +91,7 @@ Add `timeOfDay="dusk"` beside `theme` to select a map's optional `day`, `dawn`,
 `night` preset. For Streets, `theme="light"` with this preset selects the existing `dusk` palette.
 Maps without this capability ignore the option; omitting it keeps the selected theme unchanged.
 Changing it uses the existing theme transition. `themeBlend` takes precedence. See the
-[authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md#style-with-themes-and-semantic-modules).
+[authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/REFERENCE.md#style-with-themes-and-semantic-modules).
 
 Theme and `timeOfDay` changes cross-fade over 450 ms by default: a snapshot of the drawn map covers it, follows the camera and fades out once the new theme is drawn. Use `themeTransition={{duration: 700}}` to customize the duration, or `duration: 0` for an immediate change. `themeBlend={{themes: ['night', 'dusk', 'day'], position}}` shows a continuous blend of the map's themes instead of `theme`; position 0 is the first theme and 1.5 is halfway from the second to the third:
 
@@ -99,7 +99,7 @@ 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
 
@@ -132,8 +132,7 @@ export function UnemploymentMap({
 
 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; see
-[boundary areas and choropleths](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/boundary-areas-and-choropleths.md#join-by-codes-the-polygons-do-not-carry).
+on a server or at build time.
 
 ## Camera
 
@@ -178,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.
@@ -208,7 +203,7 @@ The public lifecycle surface remains:
 
 `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`) or its view or spending limit was reached (`NATIVE_SESSION_QUOTA_EXCEEDED`). It 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:
+`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';
@@ -226,6 +221,11 @@ export function StoreMap() {
           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}}
@@ -247,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
 
@@ -275,9 +275,15 @@ wrapper. A bounded accessible marker is rendered when `renderMarker` is omitted.
 remain in native vector or GeoJSON layers and are selected through semantic rendered-feature
 queries rather than thousands of React marker views.
 
+`Map` also takes the web adapters' `dataSources`, `dataOverlays` and `annotationClusters`, with
+`geojsonSource()`, `clusterOverlay()` and `heatmapOverlay()` from `@tileflow/core/native`. Tapping a
+cluster zooms in unless the application controls `view`, and reports a `cluster` target through
+`onInteractionEvent`. Compiled clusters and heatmaps are checked by
+`tileflow validate --renderer native`. Polygon drawing with Terra Draw is web-only. See the
+[interactions reference](https://github.com/tileflow/tileflow-sdk/blob/main/packages/interactions/REFERENCE.md).
+
 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
 
@@ -297,7 +303,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/dist/{contract-BaK24QZD.d.ts → contract-BWCbfMOx.d.ts}

@@ -1,8 +1,8 @@
 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, TileflowBoundaryValues, TileflowBoundaryFamily, TileflowNativeSourceState, TileflowNativeSourceError } from '@tileflow/core/native';
-import { TileflowAnnotation, TileflowInteractionBinding, TileflowInteractionEvent, TileflowResolvedAnnotationTarget, TileflowResolvedPoiFeatureTarget, TileflowInteractionDiagnostic, TileflowAnnotationViewContext } from '@tileflow/interactions';
+import { TileflowMapLibreOverlay, TileflowGeoJsonSource, TileflowNativeInitialView, TileflowNativeInitialViewOptions, TileflowNativeSource, TileflowNativeSourceOptions, TileflowBoundaryValues, TileflowBoundaryFamily, TileflowNativeSourceState, TileflowNativeSourceError } from '@tileflow/core/native';
+import { TileflowAnnotation, TileflowAnnotationClusterOptions, TileflowInteractionBinding, TileflowInteractionEvent, TileflowResolvedAnnotationTarget, TileflowResolvedClusterTarget, TileflowResolvedPoiFeatureTarget, TileflowResolvedStyleFeatureTarget, TileflowInteractionDiagnostic, TileflowAnnotationViewContext } from '@tileflow/interactions';
 
 /** Marker composition only. Selection presentation and native handles are not part of this context. */
 type MapMarkerRenderContext<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<Pick<TileflowAnnotationViewContext<TAnnotation>, 'annotation' | 'target' | 'content' | 'viewName'>>;
@@ -10,11 +10,17 @@ type MapMarkerRenderContext<TAnnotation extends TileflowAnnotation = TileflowAnn
 type MapMarkerRenderer<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = (context: MapMarkerRenderContext<TAnnotation>) => ReactElement;
 /** Mobile reports activation; the application owns any persistent selection. */
 type MapInteractionEvent<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<Omit<TileflowInteractionEvent<TAnnotation>, 'target' | 'type'> & {
-    target: TileflowResolvedAnnotationTarget<TAnnotation> | TileflowResolvedPoiFeatureTarget;
+    target: TileflowResolvedAnnotationTarget<TAnnotation> | TileflowResolvedClusterTarget | TileflowResolvedPoiFeatureTarget | TileflowResolvedStyleFeatureTarget;
     type: 'target:activate';
 }>;
 type MapInteractionProps<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    /** Group `annotations` into accessible native cluster buttons. Up to 1,000 annotations. */
+    annotationClusters?: TileflowAnnotationClusterOptions;
     annotations?: readonly TAnnotation[];
+    /** Overlays drawn over `dataSources` or compiled sources, keyed as in `defineMap`. */
+    dataOverlays?: Readonly<Record<string, TileflowMapLibreOverlay>>;
+    /** Application GeoJSON, keyed as in `defineMap`. A compiled source of the same key is filled. */
+    dataSources?: Readonly<Record<string, TileflowGeoJsonSource>>;
     interactions?: readonly TileflowInteractionBinding[];
     onInteractionEvent?: (event: MapInteractionEvent<TAnnotation>) => void;
     onInteractionDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
@@ -110,13 +116,19 @@ type MapSourceState = Readonly<{
     error: MapSourceError;
 }>;
 /**
- * The Hosted session stopped: its credential, Map or quota was 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.
+ * 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_INPUT_INVALID';
+    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. */

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-BaK24QZD.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-BaK24QZD.js';
+import { d as MapProps } from './contract-BWCbfMOx.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-BWCbfMOx.js';
 import '@maplibre/maplibre-react-native';
 import 'react-native';
 import '@tileflow/core/native';