@tileflow/interactions 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -1,6 +1,6 @@
 # @tileflow/interactions
 
-Portable annotations, tooltips, popups, state, and interaction bindings for Tileflow maps.
+Portable annotations, clusters, tooltips, popups, state, and interaction bindings for Tileflow maps.
 
 The package has two boundaries:
 
@@ -58,6 +58,17 @@ Every new annotation needs a stable `id`, singular `coordinate`, and non-empty `
 Coordinates use `[longitude, latitude]`. Optional `data` must be recursively JSON-safe. Call `validateTileflowAnnotations` at an untrusted
 boundary to receive atomic validation and structured JSON-Pointer diagnostics.
 
+## Clusters, heatmaps, and drawing
+
+Group up to 1,000 annotations with the `annotationClusters` prop of a framework adapter. Each group
+is a focusable button that zooms in. For larger sets, pass GeoJSON through `dataSources` and
+`dataOverlays`, using `geojsonSource()`, `clusterOverlay()`, and `heatmapOverlay()` from Tileflow
+Core. Polygon drawing is a documented Terra Draw integration.
+
+The [interactions reference](https://github.com/tileflow/tileflow-sdk/blob/main/packages/interactions/REFERENCE.md)
+covers each path, events, and what React Native does not support. `REFERENCE.md` is also included in
+the installed package.
+
 ## Popup state
 
 <!-- docs:check -->
@@ -114,6 +125,3 @@ Direct MapLibre consumers can use `createTileflowMapLibreDomRuntime` for annotat
 objects and schedulers are injected at attach time, so both subpath imports remain SSR-safe.
 `createTileflowMapLibreInteractionCoordinator` joins them around one controlled or uncontrolled
 popup state and commits the closing runtime before the opening runtime.
-
-See [`docs/contracts/map-interactions.md`](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/map-interactions.md) for lifecycle,
-accessibility, security, capture, and framework parity requirements.

package/REFERENCE.md

@@ -0,0 +1,185 @@
+# Interactions reference: clusters, heatmaps, and drawing
+
+Public contracts for grouping application points and drawing on a mounted map. Option and layer
+names follow the [MapLibre style specification](https://maplibre.org/maplibre-style-spec/) and match
+Mapbox: `cluster`, `clusterRadius`, `clusterMaxZoom`, `clusterMinPoints`, `clusterProperties`,
+`point_count`, `point_count_abbreviated`, and `cluster_id`.
+
+## Choose a path
+
+| Data                                     | Use                                                     | Limit                          |
+| ---------------------------------------- | ------------------------------------------------------- | ------------------------------ |
+| Up to 1,000 points with popups           | `annotations` with `annotationClusters`                 | 1,000 annotations              |
+| Thousands of points, filtered at runtime | `dataSources` with `dataOverlays`                       | MapLibre's GeoJSON worker      |
+| Fixed points or a design in config       | `geojsonSource()` and `clusterOverlay()` in `defineMap` | 512,000 bytes inline, or a URL |
+| Density of points                        | `heatmapOverlay()` over GeoJSON or a vector tileset     | Vector tilesets cannot cluster |
+
+## Runtime data
+
+`dataSources` and `dataOverlays` take the same values as `sources` and `overlays` in `defineMap`, so
+a map on an official style needs no config. Import the helpers from `@tileflow/core/runtime`.
+
+<!-- docs:check -->
+
+```ts
+import {clusterOverlay, geojsonSource, heatmapOverlay} from '@tileflow/core/runtime';
+
+const data = {
+  type: 'FeatureCollection',
+  features: [
+    {
+      type: 'Feature',
+      id: 'store-42',
+      geometry: {type: 'Point', coordinates: [-3.7038, 40.4168]},
+      properties: {name: 'Sol', revenue: 1200},
+    },
+  ],
+} as const;
+
+export const dataSources = {
+  stores: geojsonSource({
+    cluster: true,
+    clusterProperties: {revenue: ['+', ['get', 'revenue']]},
+    clusterRadius: 50,
+    data,
+  }),
+};
+
+export const dataOverlays = {
+  demand: heatmapOverlay({id: 'demand', placement: 'below-labels', source: 'stores'}),
+  stores: clusterOverlay({id: 'stores', placement: 'above-labels', source: 'stores'}),
+};
+```
+
+Pass both to the map component of `@tileflow/react`, `@tileflow/vue`, or `@tileflow/svelte`:
+
+- A key the compiled style already declares is filled with `setData` and keeps its compiled options.
+  An overlay layer the style already draws keeps its compiled form.
+- A key the style does not declare is added at the overlay's semantic `placement`. Sources and
+  overlays return after a theme change.
+- New `data` replaces the source's contents. Keep the value stable between renders, because each new
+  reference is sent to the worker. Changing a cluster option rebuilds the source.
+- Pass plain data. Svelte `$state` proxies cannot reach a worker, so use `$state.raw`.
+- Remove a key to remove what it added.
+
+A problem is reported through the interaction diagnostic callback with code `INVALID_DATA_LAYER`
+and a JSON Pointer such as `/dataOverlays/stores/source`.
+
+## Cluster overlays
+
+`clusterOverlay({id, source, placement})` draws three layers: `<id>-clusters`, `<id>-cluster-count`,
+and `<id>-points`. Options are `colors`, `radii`, `steps`, `pointColor`, `textColor`, `font`, and
+`expandOnClick`. The count uses the map's label font unless `font` names another stack. For anything
+else, write the layers with `maplibreOverlay()` and the same `point_count` expressions.
+
+Web adapters find these layers through their metadata, in compiled and runtime styles alike:
+
+- Clicking or tapping a bubble eases to `getClusterExpansionZoom()` unless `expandOnClick` is false.
+- The interaction event callback receives `target:activate` with a `cluster` target: `clusterId`,
+  `coordinate`, `pointCount`, `properties`, and `source`.
+- A separate point arrives as a `style-feature` target with its `feature.id` and `properties`.
+- A click a cluster takes does not also open a semantic POI below it.
+
+Read a cluster's members from the map with `map.getSource(source).getClusterLeaves(clusterId)`.
+Points at one coordinate separate only above `clusterMaxZoom`, so keep that below the map's maximum
+zoom. Tileflow clusters are WebGL features and cannot take keyboard focus: use annotation clusters,
+or a list beside the map, when each point must be reachable by keyboard.
+
+## Annotation clusters
+
+```tsx
+<Map annotations={stores} annotationClusters={{clusterRadius: 60}} source={source} />
+```
+
+`annotationClusters` accepts `clusterRadius`, `clusterMaxZoom`, `clusterMinPoints`, `expandOnClick`,
+and `formatAriaLabel(count)`. Each group is a real `button.tileflow-interaction-cluster`, so it takes
+focus and Enter, and the map needs no glyphs or extra source. The default accessible name is
+`12 places`; localize it with `formatAriaLabel`. Set the colour with
+`--tileflow-interaction-cluster-color`, or restyle the class.
+
+The `cluster` target also carries `annotationIds`. A marker hidden by a cluster keeps its annotation
+and state. An open popup keeps its marker visible. Focus moves to the map when the button pressed
+is replaced.
+
+## Heatmaps
+
+`heatmapOverlay({id, source, placement})` accepts `weight`, `radius`, `intensity`, `opacity`,
+`colors`, `maxZoom`, and `sourceLayer`. `weight`, `radius`, `intensity`, and `opacity` also take
+MapLibre expressions. Use `maxZoom` with a cluster overlay to hand over from density to points.
+Put heatmaps at `below-labels` so that labels stay readable.
+
+## Polygon drawing
+
+Tileflow does not include a drawing tool. Use [Terra Draw](https://terradraw.io) (MIT): vertex
+editing, snapping, touch, and self-intersection rules are a product of their own, and Terra Draw
+keeps them maintained behind a MapLibre adapter. The map component already gives you the map.
+
+```sh
+npm install terra-draw terra-draw-maplibre-gl-adapter
+```
+
+```tsx
+import {TerraDraw, TerraDrawPolygonMode, TerraDrawSelectMode} from 'terra-draw';
+import {TerraDrawMapLibreGLAdapter} from 'terra-draw-maplibre-gl-adapter';
+
+// A theme change replaces the style, so keep Terra Draw's own sources and layers.
+const mapOptions = {
+  transformStyle(previous, next) {
+    if (!previous) return next;
+    const keep = (id) => id.startsWith('td-');
+    return {
+      ...next,
+      layers: [...next.layers, ...previous.layers.filter(({id}) => keep(id))],
+      sources: {
+        ...next.sources,
+        ...Object.fromEntries(Object.entries(previous.sources).filter(([id]) => keep(id))),
+      },
+    };
+  },
+};
+
+<Map
+  mapOptions={mapOptions}
+  onLoad={(map) => {
+    const draw = new TerraDraw({
+      adapter: new TerraDrawMapLibreGLAdapter({map}),
+      modes: [new TerraDrawPolygonMode(), new TerraDrawSelectMode()],
+    });
+    draw.start();
+    draw.setMode('polygon');
+    draw.on('finish', (id) => savePolygon(draw.getSnapshotFeature(id)));
+  }}
+  source={source}
+/>;
+```
+
+The result is GeoJSON, which `geojsonSource()` can draw and an API can store. Create Terra Draw once
+per map, in `onLoad` (Vue `@load`, Svelte `on:load`), and call `draw.stop()` before unmounting.
+
+## Support by surface
+
+| Capability                                | React, Vue, Svelte | `tileflow preview`, `capture` | React Native |
+| ----------------------------------------- | ------------------ | ----------------------------- | ------------ |
+| Compiled GeoJSON clusters and heatmaps    | Yes                | Yes                           | Yes          |
+| Click or tap to expand a compiled cluster | Yes                | No                            | Yes          |
+| `dataSources`, `dataOverlays`             | Yes                | No                            | Yes          |
+| `annotationClusters`                      | Yes                | No                            | Yes          |
+| Terra Draw                                | Yes                | No                            | No           |
+
+`mode="image"` draws no runtime layers and reports `UNSUPPORTED_MODE`.
+
+React Native takes the same three props and reports the same `cluster` and `style-feature` targets
+through `onInteractionEvent`. It differs in four ways:
+
+- Data reaches MapLibre React Native's own `GeoJSONSource`, which reuses a compiled source of the
+  same ID and returns after a theme change. A reused source keeps its compiled cluster options.
+- A tapped point reports the first point layer of its source as `layerId`.
+- A map with a controlled `view` reports the cluster but does not move the camera, because the
+  application owns the view. Use the target's coordinate to set it.
+- Annotation clusters are native buttons with `accessibilityRole="button"`, grouped by the same
+  `createTileflowAnnotationClusterIndex` as the web, so both platforms split at the same zooms.
+
+Terra Draw is a GL JS library and has no native equivalent here.
+
+Direct MapLibre consumers use `createTileflowMapLibreDataRuntime` from
+`@tileflow/interactions/maplibre`.

package/dist/index.d.ts

@@ -1,11 +1,18 @@
-import { T as TileflowInteractionState, a as TileflowInteractionAction, b as TileflowInteractionTargetRef } from './validation-Cy6Tz3lz.js';
-export { c as TileflowAnnotation, d as TileflowAnnotationInteractionEvent, e as TileflowAnnotationMarker, f as TileflowAnnotationSurface, g as TileflowAnnotationValidationResult, h as TileflowAnnotationViewContext, i as TileflowInteractionBinding, j as TileflowInteractionBindingValidationResult, k as TileflowInteractionContent, l as TileflowInteractionCoordinate, m as TileflowInteractionDiagnostic, n as TileflowInteractionDiagnosticCode, o as TileflowInteractionEvent, p as TileflowInteractionEventType, q as TileflowInteractionFieldContent, r as TileflowInteractionInputModality, s as TileflowInteractionJsonPrimitive, t as TileflowInteractionJsonValue, u as TileflowInteractionTarget, v as TileflowInteractionTextContent, w as TileflowInteractionViewContent, x as TileflowInteractionViewContext, y as TileflowPoiCategory, z as TileflowPoiFilterRank, A as TileflowPoiProperties, B as TileflowPoiSizeRank, C as TileflowResolvedAnnotationTarget, D as TileflowResolvedInteractionTarget, E as TileflowResolvedMapTarget, F as TileflowResolvedPoiFeature, G as TileflowResolvedPoiFeatureTarget, H as TileflowResolvedSemanticFeature, I as TileflowResolvedSemanticFeatureTarget, J as TileflowResolvedStyleFeatureTarget, K as tileflowAnnotationSchema, L as tileflowAnnotationsSchema, M as tileflowInteractionActionSchema, N as tileflowInteractionBindingSchema, O as tileflowInteractionBindingsSchema, P as tileflowInteractionContentSchema, Q as tileflowInteractionJsonValueSchema, R as tileflowInteractionLimits, S as tileflowInteractionSchemaVersion, U as tileflowInteractionStateSchema, V as tileflowInteractionTargetRefSchema, W as tileflowInteractionTargetSchema, X as tileflowPoiCategories, Y as validateTileflowAnnotations, Z as validateTileflowInteractionBindings } from './validation-Cy6Tz3lz.js';
+import { T as TileflowInteractionState, a as TileflowInteractionAction, b as TileflowInteractionTargetRef } from './validation-DBRKrV__.js';
+export { c as TileflowAnnotation, d as TileflowAnnotationCluster, e as TileflowAnnotationClusterIndex, f as TileflowAnnotationClusterOptions, g as TileflowAnnotationClusterView, h as TileflowAnnotationInteractionEvent, i as TileflowAnnotationMarker, j as TileflowAnnotationSurface, k as TileflowAnnotationValidationResult, l as TileflowAnnotationViewContext, m as TileflowInteractionBinding, n as TileflowInteractionBindingValidationResult, o as TileflowInteractionContent, p as TileflowInteractionCoordinate, q as TileflowInteractionDiagnostic, r as TileflowInteractionDiagnosticCode, s as TileflowInteractionEvent, t as TileflowInteractionEventType, u as TileflowInteractionFieldContent, v as TileflowInteractionInputModality, w as TileflowInteractionJsonPrimitive, x as TileflowInteractionJsonValue, y as TileflowInteractionTarget, z as TileflowInteractionTextContent, A as TileflowInteractionViewContent, B as TileflowInteractionViewContext, C as TileflowPoiCategory, D as TileflowPoiFilterRank, E as TileflowPoiProperties, F as TileflowPoiSizeRank, G as TileflowResolvedAnnotationTarget, H as TileflowResolvedClusterTarget, I as TileflowResolvedInteractionTarget, J as TileflowResolvedMapTarget, K as TileflowResolvedPoiFeature, L as TileflowResolvedPoiFeatureTarget, M as TileflowResolvedSemanticFeature, N as TileflowResolvedSemanticFeatureTarget, O as TileflowResolvedStyleFeatureTarget, P as createTileflowAnnotationClusterIndex, Q as tileflowAnnotationSchema, R as tileflowAnnotationsSchema, S as tileflowInteractionActionSchema, U as tileflowInteractionBindingSchema, V as tileflowInteractionBindingsSchema, W as tileflowInteractionContentSchema, X as tileflowInteractionJsonValueSchema, Y as tileflowInteractionLimits, Z as tileflowInteractionSchemaVersion, _ as tileflowInteractionStateSchema, $ as tileflowInteractionTargetRefSchema, a0 as tileflowInteractionTargetSchema, a1 as tileflowPoiCategories, a2 as validateTileflowAnnotations, a3 as validateTileflowInteractionBindings } from './validation-DBRKrV__.js';
 import 'zod/mini';
 
 declare const initialTileflowInteractionState: TileflowInteractionState;
 declare function reduceTileflowInteractionState(state: TileflowInteractionState, action: TileflowInteractionAction): TileflowInteractionState;
 declare function tileflowInteractionTargetRefsEqual(left: TileflowInteractionTargetRef | null, right: TileflowInteractionTargetRef | null): boolean;
 
+type Json = Readonly<Record<string, unknown>>;
+/**
+ * Gives a `clusterOverlay()` count layer the style's label font. Other layers and counts with their
+ * own font return unchanged; `undefined` means the style has no label font to share.
+ */
+declare function withTileflowClusterLabelFont<TLayer extends Json>(layer: TLayer, styleLayers: readonly Json[]): TLayer | undefined;
+
 /** Compact machine-readable vocabulary for agents and code generators. */
 declare const tileflowInteractionReference: Readonly<{
     readonly actions: readonly ["open-popup", "close-popup"];
@@ -50,4 +57,4 @@ declare const tileflowInteractionReference: Readonly<{
     readonly version: 1;
 }>;
 
-export { TileflowInteractionAction, TileflowInteractionState, TileflowInteractionTargetRef, initialTileflowInteractionState, reduceTileflowInteractionState, tileflowInteractionReference, tileflowInteractionTargetRefsEqual };
+export { TileflowInteractionAction, TileflowInteractionState, TileflowInteractionTargetRef, initialTileflowInteractionState, reduceTileflowInteractionState, tileflowInteractionReference, tileflowInteractionTargetRefsEqual, withTileflowClusterLabelFont };

package/dist/index.js

@@ -398,6 +398,74 @@ function tileflowInteractionTargetRefsEqual(left, right) {
   }
 }
 
+// src/annotation-clusters.ts
+import Supercluster from "supercluster";
+function createTileflowAnnotationClusterIndex(annotations, options = {}) {
+  const index = new Supercluster({
+    extent: 512,
+    maxZoom: Math.floor(options.clusterMaxZoom ?? 14),
+    minPoints: options.clusterMinPoints ?? 2,
+    radius: options.clusterRadius ?? 50
+  }).load(
+    annotations.map(({ coordinate, id }) => ({
+      geometry: { coordinates: [coordinate[0], coordinate[1]], type: "Point" },
+      properties: { id },
+      type: "Feature"
+    }))
+  );
+  const views = /* @__PURE__ */ new Map();
+  return Object.freeze({
+    at(zoom) {
+      const level = Math.max(0, Math.floor(Number.isFinite(zoom) ? zoom : 0));
+      const cached = views.get(level);
+      if (cached) return cached;
+      const hidden = new Set(annotations.map(({ id }) => id));
+      const clusters = [];
+      for (const feature of index.getClusters([-180, -90, 180, 90], level)) {
+        const properties = feature.properties;
+        if (!properties.cluster) {
+          hidden.delete(properties.id);
+          continue;
+        }
+        const clusterId = properties.cluster_id;
+        const [longitude, latitude] = feature.geometry.coordinates;
+        clusters.push(
+          Object.freeze({
+            annotationIds: Object.freeze(
+              index.getLeaves(clusterId, Infinity).map((leaf) => leaf.properties.id)
+            ),
+            clusterId,
+            coordinate: Object.freeze([longitude, latitude]),
+            expansionZoom: index.getClusterExpansionZoom(clusterId),
+            label: String(properties.point_count_abbreviated),
+            pointCount: properties.point_count
+          })
+        );
+      }
+      const view = Object.freeze({ clusters: Object.freeze(clusters), hiddenAnnotationIds: hidden });
+      views.set(level, view);
+      return view;
+    }
+  });
+}
+
+// src/cluster-label-font.ts
+var clusterMetadataKey = "tileflow:cluster";
+var lineBackgroundStack = / lines-v1-t\d+-l\d+-p\d+$/u;
+function withTileflowClusterLabelFont(layer, styleLayers) {
+  const metadata = layer.metadata;
+  const layout = layer.layout ?? {};
+  if (metadata?.[clusterMetadataKey]?.role !== "count") return layer;
+  if (layout["text-font"] !== void 0) return layer;
+  for (const candidate of styleLayers) {
+    const font = candidate.layout?.["text-font"];
+    if (Array.isArray(font) && font.length > 0 && font.every((face) => typeof face === "string" && !lineBackgroundStack.test(face))) {
+      return { ...layer, layout: { ...layout, "text-font": font } };
+    }
+  }
+  return void 0;
+}
+
 // src/reference.ts
 var tileflowInteractionReference = Object.freeze({
   actions: ["open-popup", "close-popup"],
@@ -617,6 +685,7 @@ function jsonPointer(path) {
   return path.map((segment) => String(segment).replaceAll("~", "~0").replaceAll("/", "~1")).map((segment) => `/${segment}`).join("");
 }
 export {
+  createTileflowAnnotationClusterIndex,
   initialTileflowInteractionState,
   reduceTileflowInteractionState,
   tileflowAnnotationSchema,
@@ -635,5 +704,6 @@ export {
   tileflowInteractionTargetSchema,
   tileflowPoiCategories,
   validateTileflowAnnotations,
-  validateTileflowInteractionBindings
+  validateTileflowInteractionBindings,
+  withTileflowClusterLabelFont
 };

package/dist/maplibre-entry.d.ts

@@ -1,4 +1,4 @@
-import { m as TileflowInteractionDiagnostic, T as TileflowInteractionState, c as TileflowAnnotation, d as TileflowAnnotationInteractionEvent, i as TileflowInteractionBinding, G as TileflowResolvedPoiFeatureTarget, r as TileflowInteractionInputModality, o as TileflowInteractionEvent, I as TileflowResolvedSemanticFeatureTarget, k as TileflowInteractionContent } from './validation-Cy6Tz3lz.js';
+import { q as TileflowInteractionDiagnostic, T as TileflowInteractionState, c as TileflowAnnotation, h as TileflowAnnotationInteractionEvent, f as TileflowAnnotationClusterOptions, s as TileflowInteractionEvent, m as TileflowInteractionBinding, L as TileflowResolvedPoiFeatureTarget, v as TileflowInteractionInputModality, N as TileflowResolvedSemanticFeatureTarget, o as TileflowInteractionContent } from './validation-DBRKrV__.js';
 import 'zod/mini';
 
 /**
@@ -135,6 +135,8 @@ type TileflowMapLibreDomRuntime<TAnnotation extends TileflowAnnotation = Tileflo
     openPopup: (annotationId: string) => boolean;
     reconcile: (annotations: readonly TAnnotation[]) => void;
     setCustomRenderers: (renderers: TileflowMapLibreDomCustomRenderers) => void;
+    /** Hide markers that a cluster stands in for. An open popup keeps its own marker visible. */
+    setHiddenAnnotations: (annotationIds: ReadonlySet<string>) => void;
     setInteractionState: (state: TileflowInteractionState) => void;
     subscribeEvents: (listener: (event: TileflowAnnotationInteractionEvent<TAnnotation>) => void) => () => void;
     subscribeDiagnostics: (listener: TileflowMapLibreDomDiagnosticListener) => () => void;
@@ -149,6 +151,94 @@ type TileflowMapLibreDomRuntime<TAnnotation extends TileflowAnnotation = Tileflo
  */
 declare function createTileflowMapLibreDomRuntime<TMap, TMarker extends TileflowMapLibrePositioned<TMap>, TOverlay extends TileflowMapLibrePositioned<TMap>, TAnnotation extends TileflowAnnotation = TileflowAnnotation>(options: TileflowMapLibreDomRuntimeOptions<TMap, TMarker, TOverlay, TAnnotation>): TileflowMapLibreDomRuntime<TAnnotation>;
 
+type Json = Readonly<Record<string, unknown>>;
+/** A `geojsonSource()` value from `@tileflow/core`. */
+type TileflowMapLibreDataSource = Json & Readonly<{
+    data: unknown;
+    kind: 'geojson';
+}>;
+/** A `clusterOverlay()`, `heatmapOverlay()` or `maplibreOverlay()` value from `@tileflow/core`. */
+type TileflowMapLibreDataOverlay = Readonly<{
+    kind: 'maplibre-overlay';
+    layers: readonly (Json & Readonly<{
+        id: string;
+        type: string;
+    }>)[];
+    placement: string;
+    source: string;
+}>;
+type TileflowMapLibreDataInput<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    annotationClusters?: TileflowAnnotationClusterOptions | undefined;
+    annotations?: readonly TAnnotation[] | undefined;
+    dataOverlays?: Readonly<Record<string, TileflowMapLibreDataOverlay>> | undefined;
+    dataSources?: Readonly<Record<string, TileflowMapLibreDataSource>> | undefined;
+}>;
+type TileflowMapLibreDataFeature = Readonly<{
+    geometry?: unknown;
+    id?: number | string;
+    layer: Readonly<{
+        id: string;
+    }>;
+    properties?: Json | null;
+    source?: string;
+}>;
+/** The MapLibre methods the runtime uses; a `maplibregl.Map` satisfies this. */
+type TileflowMapLibreDataMap = Readonly<{
+    addLayer: (layer: never, beforeId?: string) => unknown;
+    addSource: (id: string, source: never) => unknown;
+    easeTo: (options: {
+        center: [number, number];
+        zoom: number;
+    }) => unknown;
+    getCanvas: () => Readonly<{
+        style: {
+            cursor: string;
+        };
+        focus?: (o?: FocusOptions) => void;
+    }>;
+    getLayer: (id: string) => Readonly<{
+        metadata?: unknown;
+    }> | undefined;
+    getLayersOrder: () => readonly string[];
+    getSource: (id: string) => unknown;
+    getStyle: () => unknown;
+    getZoom: () => number;
+    isStyleLoaded: () => boolean | void;
+    off: (event: never, listener: never) => unknown;
+    on: (event: never, listener: never) => unknown;
+    queryRenderedFeatures: (point: never, options: Readonly<{
+        layers: string[];
+    }>) => readonly TileflowMapLibreDataFeature[];
+    removeLayer: (id: string) => unknown;
+    removeSource: (id: string) => unknown;
+}>;
+type TileflowMapLibreDataRuntimeOptions<TMap, TMarker extends TileflowMapLibrePositioned<TMap>> = Readonly<{
+    /** Builds the marker that carries one annotation cluster's button. */
+    createMarker: (input: Readonly<{
+        element: HTMLElement;
+    }>) => TMarker;
+    document: Pick<Document, 'createElement'>;
+    map: TMap & TileflowMapLibreDataMap;
+    onDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
+    onInteractionEvent?: (event: TileflowInteractionEvent) => void;
+    /** Receives the annotation IDs a cluster stands in for. */
+    setHiddenAnnotations?: (annotationIds: ReadonlySet<string>) => void;
+}>;
+type TileflowMapLibreDataRuntime<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    dispose: () => void;
+    reconcile: (input: TileflowMapLibreDataInput<TAnnotation>) => void;
+}>;
+/**
+ * Keeps application GeoJSON, its overlays and clustered annotations on a mounted map.
+ *
+ * Runtime sources and overlays take the same `geojsonSource()` and overlay values as a map's config.
+ * A source the compiled style already declares is filled rather than added, and an overlay layer
+ * it already draws keeps its compiled form. Both return after a style change, which removes
+ * whatever the new style does not declare. Layers built by `clusterOverlay()` are found through
+ * their metadata, so compiled and runtime clusters expand the same way.
+ */
+declare function createTileflowMapLibreDataRuntime<TMap, TMarker extends TileflowMapLibrePositioned<TMap>, TAnnotation extends TileflowAnnotation = TileflowAnnotation>(options: TileflowMapLibreDataRuntimeOptions<TMap, TMarker>): TileflowMapLibreDataRuntime<TAnnotation>;
+
 type TileflowMapLibreInteractionParticipantKind = 'annotation' | 'semantic';
 type TileflowMapLibreInteractionParticipant = Readonly<{
     setInteractionState: (state: TileflowInteractionState) => void;
@@ -287,4 +377,4 @@ type TileflowMapLibreSemanticDomRuntime = Readonly<{
  */
 declare function createTileflowMapLibreSemanticDomRuntime<TMap, TOverlay extends TileflowMapLibrePositioned<TMap>>(options: TileflowMapLibreSemanticDomRuntimeOptions<TMap, TOverlay>): TileflowMapLibreSemanticDomRuntime;
 
-export { type TileflowAnnotationRegistry, type TileflowAnnotationRegistryAdapter, type TileflowAnnotationRegistryEntry, type TileflowMapLibreDomCustomRenderers, type TileflowMapLibreDomDiagnosticListener, type TileflowMapLibreDomDocument, type TileflowMapLibreDomInteractionStateListener, type TileflowMapLibreDomMarkerFactoryInput, type TileflowMapLibreDomOverlayFactoryInput, type TileflowMapLibreDomOverlayKind, type TileflowMapLibreDomRenderTarget, type TileflowMapLibreDomRenderTargetKind, type TileflowMapLibreDomRenderTargetListener, type TileflowMapLibreDomRuntime, type TileflowMapLibreDomRuntimeOptions, type TileflowMapLibreDomStateChangeReason, type TileflowMapLibreInteractionCoordinator, type TileflowMapLibreInteractionCoordinatorOptions, type TileflowMapLibreInteractionParticipant, type TileflowMapLibreInteractionParticipantKind, type TileflowMapLibrePoiController, type TileflowMapLibrePoiControllerOptions, type TileflowMapLibrePoiFeature, type TileflowMapLibrePoiMap, type TileflowMapLibrePoiMatch, type TileflowMapLibrePoiPointerEvent, type TileflowMapLibrePositioned, type TileflowMapLibreSemanticDomOverlayFactoryInput, type TileflowMapLibreSemanticDomRenderTarget, type TileflowMapLibreSemanticDomRuntime, type TileflowMapLibreSemanticDomRuntimeOptions, type TileflowOverlayState, type TileflowOverlayStateChangeReason, type TileflowOverlayStateController, type TileflowOverlayStateListener, createTileflowAnnotationRegistry, createTileflowMapLibreDomRuntime, createTileflowMapLibreInteractionCoordinator, createTileflowMapLibrePoiController, createTileflowMapLibreSemanticDomRuntime, createTileflowOverlayStateController };
+export { TileflowAnnotationClusterOptions, type TileflowAnnotationRegistry, type TileflowAnnotationRegistryAdapter, type TileflowAnnotationRegistryEntry, type TileflowMapLibreDataFeature, type TileflowMapLibreDataInput, type TileflowMapLibreDataMap, type TileflowMapLibreDataOverlay, type TileflowMapLibreDataRuntime, type TileflowMapLibreDataRuntimeOptions, type TileflowMapLibreDataSource, type TileflowMapLibreDomCustomRenderers, type TileflowMapLibreDomDiagnosticListener, type TileflowMapLibreDomDocument, type TileflowMapLibreDomInteractionStateListener, type TileflowMapLibreDomMarkerFactoryInput, type TileflowMapLibreDomOverlayFactoryInput, type TileflowMapLibreDomOverlayKind, type TileflowMapLibreDomRenderTarget, type TileflowMapLibreDomRenderTargetKind, type TileflowMapLibreDomRenderTargetListener, type TileflowMapLibreDomRuntime, type TileflowMapLibreDomRuntimeOptions, type TileflowMapLibreDomStateChangeReason, type TileflowMapLibreInteractionCoordinator, type TileflowMapLibreInteractionCoordinatorOptions, type TileflowMapLibreInteractionParticipant, type TileflowMapLibreInteractionParticipantKind, type TileflowMapLibrePoiController, type TileflowMapLibrePoiControllerOptions, type TileflowMapLibrePoiFeature, type TileflowMapLibrePoiMap, type TileflowMapLibrePoiMatch, type TileflowMapLibrePoiPointerEvent, type TileflowMapLibrePositioned, type TileflowMapLibreSemanticDomOverlayFactoryInput, type TileflowMapLibreSemanticDomRenderTarget, type TileflowMapLibreSemanticDomRuntime, type TileflowMapLibreSemanticDomRuntimeOptions, type TileflowOverlayState, type TileflowOverlayStateChangeReason, type TileflowOverlayStateController, type TileflowOverlayStateListener, createTileflowAnnotationRegistry, createTileflowMapLibreDataRuntime, createTileflowMapLibreDomRuntime, createTileflowMapLibreInteractionCoordinator, createTileflowMapLibrePoiController, createTileflowMapLibreSemanticDomRuntime, createTileflowOverlayStateController };

package/dist/maplibre-entry.js

@@ -330,6 +330,12 @@ function createTileflowMapLibreDomRuntime(options) {
   let disposeStarted = false;
   let disposeComplete = false;
   let overlaySequence = 0;
+  let hiddenAnnotations = /* @__PURE__ */ new Set();
+  const applyAnnotationVisibility = (instance, annotationId) => {
+    const hidden = hiddenAnnotations.has(annotationId) && activePopup?.annotation.id !== annotationId;
+    if (hidden) closeTooltipVisual(annotationId);
+    instance.element.style.display = hidden ? "none" : "";
+  };
   const emit = (type, annotation, inputModality2) => {
     const event = Object.freeze({
       coordinate: annotation.coordinate,
@@ -388,6 +394,7 @@ function createTileflowMapLibreDomRuntime(options) {
     }
     marker?.element.setAttribute("aria-expanded", "false");
     marker?.element.removeAttribute("aria-controls");
+    if (marker) applyAnnotationVisibility(marker, current.annotation.id);
     const errors = safelyRunAll([() => current.overlay.remove(), () => current.shell.remove()]);
     publishRenderTargets();
     emit("popup:close", current.annotation, inputModality2);
@@ -537,6 +544,7 @@ function createTileflowMapLibreDomRuntime(options) {
     clearOverlayFailure(entry.definition.id, "popup");
     entry.instance.element.setAttribute("aria-controls", shell.id);
     entry.instance.element.setAttribute("aria-expanded", "true");
+    applyAnnotationVisibility(entry.instance, annotationId);
     publishRenderTargets();
     emit("popup:open", entry.definition, inputModality2);
     closeButton.focus({ preventScroll: true });
@@ -766,6 +774,7 @@ function createTileflowMapLibreDomRuntime(options) {
     container.className = "tileflow-interaction-marker-content";
     element.append(container);
     configureAnnotationElement({ annotation, container, element }, annotation);
+    if (hiddenAnnotations.has(annotation.id)) element.style.display = "none";
     const marker = options.createMarker({ annotation, element });
     const instance = {
       annotation,
@@ -1021,6 +1030,11 @@ function createTileflowMapLibreDomRuntime(options) {
         publishRenderTargets();
       }
     },
+    setHiddenAnnotations(annotationIds) {
+      assertRuntimeActive(disposeStarted);
+      hiddenAnnotations = annotationIds;
+      for (const entry of registry.entries()) applyAnnotationVisibility(entry.instance, entry.key);
+    },
     setInteractionState(state) {
       assertRuntimeActive(disposeStarted);
       const popupId = getAnnotationPopupId(state);
@@ -1180,6 +1194,455 @@ function throwCollectedErrors(errors, message) {
   throw new AggregateError(errors, message);
 }
 
+// src/annotation-clusters.ts
+import Supercluster from "supercluster";
+function createTileflowAnnotationClusterIndex(annotations, options = {}) {
+  const index = new Supercluster({
+    extent: 512,
+    maxZoom: Math.floor(options.clusterMaxZoom ?? 14),
+    minPoints: options.clusterMinPoints ?? 2,
+    radius: options.clusterRadius ?? 50
+  }).load(
+    annotations.map(({ coordinate, id }) => ({
+      geometry: { coordinates: [coordinate[0], coordinate[1]], type: "Point" },
+      properties: { id },
+      type: "Feature"
+    }))
+  );
+  const views = /* @__PURE__ */ new Map();
+  return Object.freeze({
+    at(zoom) {
+      const level = Math.max(0, Math.floor(Number.isFinite(zoom) ? zoom : 0));
+      const cached = views.get(level);
+      if (cached) return cached;
+      const hidden = new Set(annotations.map(({ id }) => id));
+      const clusters = [];
+      for (const feature of index.getClusters([-180, -90, 180, 90], level)) {
+        const properties = feature.properties;
+        if (!properties.cluster) {
+          hidden.delete(properties.id);
+          continue;
+        }
+        const clusterId = properties.cluster_id;
+        const [longitude, latitude] = feature.geometry.coordinates;
+        clusters.push(
+          Object.freeze({
+            annotationIds: Object.freeze(
+              index.getLeaves(clusterId, Infinity).map((leaf) => leaf.properties.id)
+            ),
+            clusterId,
+            coordinate: Object.freeze([longitude, latitude]),
+            expansionZoom: index.getClusterExpansionZoom(clusterId),
+            label: String(properties.point_count_abbreviated),
+            pointCount: properties.point_count
+          })
+        );
+      }
+      const view = Object.freeze({ clusters: Object.freeze(clusters), hiddenAnnotationIds: hidden });
+      views.set(level, view);
+      return view;
+    }
+  });
+}
+
+// src/cluster-label-font.ts
+var clusterMetadataKey = "tileflow:cluster";
+var lineBackgroundStack = / lines-v1-t\d+-l\d+-p\d+$/u;
+function withTileflowClusterLabelFont(layer, styleLayers) {
+  const metadata = layer.metadata;
+  const layout = layer.layout ?? {};
+  if (metadata?.[clusterMetadataKey]?.role !== "count") return layer;
+  if (layout["text-font"] !== void 0) return layer;
+  for (const candidate of styleLayers) {
+    const font = candidate.layout?.["text-font"];
+    if (Array.isArray(font) && font.length > 0 && font.every((face) => typeof face === "string" && !lineBackgroundStack.test(face))) {
+      return { ...layer, layout: { ...layout, "text-font": font } };
+    }
+  }
+  return void 0;
+}
+
+// src/maplibre-data.ts
+var clusterMetadataKey2 = "tileflow:cluster";
+var overlayMetadataKey = "tileflow:overlay";
+var placementMetadataKey = "tileflow:overlay-placement-manifest";
+function createTileflowMapLibreDataRuntime(options) {
+  const map = options.map;
+  const overlays = /* @__PURE__ */ new Map();
+  const sources = /* @__PURE__ */ new Map();
+  const clusterMarkers = /* @__PURE__ */ new Map();
+  const reported = /* @__PURE__ */ new Set();
+  let input = {};
+  let annotationClusterKey = "";
+  let index;
+  let renderedZoom;
+  let clusterLayers = [];
+  let pointLayers = [];
+  let hovered = [];
+  let cursorOwned = false;
+  let applying = false;
+  let disposed = false;
+  const on = (event, listener) => {
+    map.on(event, listener);
+    return () => map.off(event, listener);
+  };
+  const onLayers = (event, layers, listener) => {
+    map.on(
+      event,
+      [...layers],
+      listener
+    );
+    return () => map.off(
+      event,
+      [...layers],
+      listener
+    );
+  };
+  const report = (message, path) => {
+    if (reported.has(message)) return;
+    reported.add(message);
+    options.onDiagnostic?.({ code: "INVALID_DATA_LAYER", level: "error", message, path });
+  };
+  const removeOverlay = (id) => {
+    for (const layer of overlays.get(id)?.layers ?? []) {
+      if (map.getLayer(layer)) map.removeLayer(layer);
+    }
+    overlays.delete(id);
+  };
+  const removeSource = (id) => {
+    for (const [overlayId, overlay] of [...overlays]) {
+      if (overlay.source === id) removeOverlay(overlayId);
+    }
+    if (map.getSource(id)) map.removeSource(id);
+    sources.delete(id);
+  };
+  const syncSources = () => {
+    for (const id of sources.keys()) {
+      if (!input.dataSources?.[id]) removeSource(id);
+    }
+    for (const [id, source] of Object.entries(input.dataSources ?? {}).sort(compareEntries)) {
+      const { data, kind: _kind, ...definition } = source;
+      const signature = JSON.stringify(definition);
+      const owned = sources.get(id);
+      if (owned && owned.signature !== signature) removeSource(id);
+      const current = map.getSource(id);
+      if (!current) {
+        map.addSource(id, { ...definition, data, type: "geojson" });
+        sources.set(id, { signature });
+      } else if (typeof current.setData !== "function") {
+        report(`Source "${id}" already exists and is not GeoJSON.`, `/dataSources/${id}`);
+      } else if (current.serialize?.().data !== data) {
+        current.setData(data);
+      }
+    }
+  };
+  const syncOverlays = () => {
+    for (const id of overlays.keys()) {
+      if (!input.dataOverlays?.[id]) removeOverlay(id);
+    }
+    const style = map.getStyle();
+    const anchors = style?.metadata?.[placementMetadataKey]?.anchors;
+    for (const [id, overlay] of Object.entries(input.dataOverlays ?? {}).sort(compareEntries)) {
+      const path = `/dataOverlays/${id}`;
+      if (overlay.kind !== "maplibre-overlay") {
+        report(`Overlay "${id}" is not a Tileflow overlay.`, path);
+        continue;
+      }
+      if (!map.getSource(overlay.source)) {
+        report(`Overlay "${id}" references unknown source "${overlay.source}".`, `${path}/source`);
+        continue;
+      }
+      const signature = JSON.stringify(overlay);
+      if (overlays.get(id)?.signature !== signature) removeOverlay(id);
+      const anchor = anchors?.[overlay.placement];
+      const beforeId = typeof anchor === "string" && map.getLayer(anchor) ? anchor : void 0;
+      const owned = overlays.get(id)?.layers ?? [];
+      for (const layer of overlay.layers) {
+        if (map.getLayer(layer.id)) continue;
+        const prepared = withTileflowClusterLabelFont(layer, style?.layers ?? []);
+        if (!prepared) {
+          report(`Layer "${layer.id}" needs font: the style has no label font.`, path);
+          continue;
+        }
+        const metadata = { ...layer.metadata, [overlayMetadataKey]: id };
+        map.addLayer({ ...prepared, metadata, source: overlay.source }, beforeId);
+        if (!owned.includes(layer.id)) owned.push(layer.id);
+      }
+      overlays.set(id, { layers: owned, signature, source: overlay.source });
+    }
+  };
+  const syncClusterLayers = () => {
+    const clusters = [];
+    const points = [];
+    for (const id of map.getLayersOrder()) {
+      const metadata = map.getLayer(id)?.metadata;
+      const cluster = metadata?.[clusterMetadataKey2];
+      if (cluster?.role === "cluster") clusters.push(id);
+      if (cluster?.role === "point") points.push(id);
+    }
+    clusterLayers = clusters;
+    pointLayers = points;
+    const interactive = [...clusters, ...points];
+    if (interactive.join("\0") === hovered.join("\0")) return;
+    stopHover();
+    hovered = interactive;
+    if (interactive.length === 0) return;
+    const enter = () => {
+      cursorOwned = true;
+      map.getCanvas().style.cursor = "pointer";
+    };
+    const leave = () => {
+      if (cursorOwned) map.getCanvas().style.cursor = "";
+      cursorOwned = false;
+    };
+    const stops2 = [
+      onLayers("mouseenter", interactive, enter),
+      onLayers("mouseleave", interactive, leave)
+    ];
+    stopHover = () => {
+      for (const stop of stops2) stop();
+      leave();
+      stopHover = () => void 0;
+    };
+  };
+  let stopHover = () => void 0;
+  const syncStyle = () => {
+    if (applying || disposed) return;
+    applying = true;
+    try {
+      syncSources();
+      syncOverlays();
+      syncClusterLayers();
+    } catch (error) {
+      if (map.isStyleLoaded() === true) {
+        report(error instanceof Error ? error.message : "Tileflow data layers failed.", "");
+      }
+    } finally {
+      applying = false;
+    }
+  };
+  const activateCluster = (target, modality) => options.onInteractionEvent?.({
+    coordinate: target.coordinate,
+    inputModality: modality,
+    target,
+    type: "target:activate"
+  });
+  const expand = (center, zoom) => map.easeTo({ center: [center[0], center[1]], zoom });
+  const handleClick = (event) => {
+    const layers = [...clusterLayers, ...pointLayers];
+    if (disposed || layers.length === 0 || !event.point) return;
+    const feature = map.queryRenderedFeatures(event.point, { layers })[0];
+    if (!feature) return;
+    event.preventDefault?.();
+    const properties = jsonProperties(feature.properties);
+    const modality = pointerModality(event);
+    const coordinate = pointCoordinate(feature.geometry) ?? eventCoordinate(event);
+    if (!coordinate) return;
+    if (!clusterLayers.includes(feature.layer.id)) {
+      options.onInteractionEvent?.({
+        coordinate,
+        inputModality: modality,
+        target: {
+          coordinate,
+          feature: { ...feature.id === void 0 ? {} : { id: feature.id }, properties },
+          kind: "style-feature",
+          layerId: feature.layer.id
+        },
+        type: "target:activate"
+      });
+      return;
+    }
+    const clusterId = properties.cluster_id;
+    if (typeof clusterId !== "number" || !feature.source) return;
+    activateCluster(
+      {
+        clusterId,
+        coordinate,
+        kind: "cluster",
+        pointCount: typeof properties.point_count === "number" ? properties.point_count : 0,
+        properties,
+        source: feature.source
+      },
+      modality
+    );
+    const metadata = map.getLayer(feature.layer.id)?.metadata;
+    if (metadata?.[clusterMetadataKey2]?.expandOnClick === false) return;
+    const source = map.getSource(feature.source);
+    void source?.getClusterExpansionZoom?.(clusterId).then(
+      (zoom) => {
+        if (!disposed) expand(coordinate, zoom);
+      },
+      () => void 0
+    );
+  };
+  const isFocused = ({ element }) => element.ownerDocument?.activeElement === element;
+  const hasFocusedClusterMarker = () => [...clusterMarkers.values()].some(isFocused);
+  const removeClusterMarker = (id, entry) => {
+    entry.element.removeEventListener("click", entry.listener);
+    entry.marker.remove();
+    entry.element.remove();
+    clusterMarkers.delete(id);
+  };
+  const clusterLabel = (count) => input.annotationClusters?.formatAriaLabel?.(count) ?? `${count} places`;
+  const createClusterMarker = (cluster) => {
+    const element = options.document.createElement("button");
+    element.type = "button";
+    element.className = "tileflow-interaction-cluster";
+    element.textContent = cluster.label;
+    element.setAttribute("aria-label", clusterLabel(cluster.pointCount));
+    element.setAttribute("data-tileflow-interaction", "cluster");
+    configureClusterStyles(element);
+    const listener = (event) => {
+      activateCluster(
+        {
+          annotationIds: cluster.annotationIds,
+          clusterId: cluster.clusterId,
+          coordinate: cluster.coordinate,
+          kind: "cluster",
+          pointCount: cluster.pointCount,
+          properties: { point_count: cluster.pointCount }
+        },
+        // Browsers report a click from Enter or Space with a detail of zero.
+        event.detail === 0 ? "keyboard" : "pointer"
+      );
+      if (input.annotationClusters?.expandOnClick !== false) {
+        expand(cluster.coordinate, cluster.expansionZoom);
+      }
+    };
+    element.addEventListener("click", listener);
+    const marker = options.createMarker({ element });
+    marker.setLngLat([cluster.coordinate[0], cluster.coordinate[1]]);
+    marker.addTo(map);
+    clusterMarkers.set(cluster.clusterId, {
+      element,
+      listener,
+      marker,
+      pointCount: cluster.pointCount
+    });
+  };
+  const renderAnnotationClusters = () => {
+    if (disposed) return;
+    if (!index) {
+      for (const [id, entry] of [...clusterMarkers]) removeClusterMarker(id, entry);
+      options.setHiddenAnnotations?.(/* @__PURE__ */ new Set());
+      renderedZoom = void 0;
+      return;
+    }
+    const zoom = Math.floor(map.getZoom());
+    renderedZoom = zoom;
+    const view = index.at(zoom);
+    const clusters = new Map(view.clusters.map((cluster) => [cluster.clusterId, cluster]));
+    let focusLost = false;
+    for (const [id, entry] of [...clusterMarkers]) {
+      if (clusters.has(id)) continue;
+      focusLost ||= isFocused(entry);
+      removeClusterMarker(id, entry);
+    }
+    for (const [id, cluster] of clusters) {
+      if (!clusterMarkers.has(id)) createClusterMarker(cluster);
+    }
+    options.setHiddenAnnotations?.(view.hiddenAnnotationIds);
+    if (focusLost) map.getCanvas().focus?.({ preventScroll: true });
+  };
+  const handleZoom = () => {
+    if (index && Math.floor(map.getZoom()) !== renderedZoom) renderAnnotationClusters();
+  };
+  const syncAnnotationClusters = () => {
+    const settings = input.annotationClusters;
+    let focusLost = false;
+    if (!settings) {
+      index = void 0;
+    } else {
+      index = createTileflowAnnotationClusterIndex(input.annotations ?? [], settings);
+      focusLost = hasFocusedClusterMarker();
+      for (const [id, entry] of [...clusterMarkers]) removeClusterMarker(id, entry);
+    }
+    renderAnnotationClusters();
+    if (focusLost) map.getCanvas().focus?.({ preventScroll: true });
+  };
+  const refreshClusterLabels = () => {
+    for (const { element, pointCount } of clusterMarkers.values()) {
+      element.setAttribute("aria-label", clusterLabel(pointCount));
+    }
+  };
+  const stops = [
+    on("style.load", syncStyle),
+    on("styledata", syncStyle),
+    on("click", handleClick),
+    on("zoom", handleZoom)
+  ];
+  return Object.freeze({
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const stop of stops) stop();
+      stopHover();
+      for (const [id, entry] of [...clusterMarkers]) removeClusterMarker(id, entry);
+      try {
+        if (index) options.setHiddenAnnotations?.(/* @__PURE__ */ new Set());
+      } catch {
+      }
+      try {
+        for (const id of [...overlays.keys()]) removeOverlay(id);
+        for (const id of [...sources.keys()]) removeSource(id);
+      } catch {
+      }
+    },
+    reconcile(next) {
+      if (disposed) return;
+      const key = clusterInputKey(next);
+      const changed = key !== annotationClusterKey;
+      annotationClusterKey = key;
+      input = next;
+      reported.clear();
+      syncStyle();
+      if (changed) syncAnnotationClusters();
+      else refreshClusterLabels();
+    }
+  });
+}
+function clusterInputKey(input) {
+  if (!input.annotationClusters) return "";
+  const positions = (input.annotations ?? []).map(({ coordinate, id }) => [id, ...coordinate]);
+  return JSON.stringify([input.annotationClusters, positions]);
+}
+function compareEntries([left], [right]) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function pointerModality(event) {
+  const original = event.originalEvent;
+  return original?.pointerType === "touch" || original?.touches !== void 0 ? "touch" : "pointer";
+}
+function eventCoordinate(event) {
+  return event.lngLat ? [event.lngLat.lng, event.lngLat.lat] : void 0;
+}
+function pointCoordinate(geometry) {
+  const value = geometry;
+  const coordinates = value?.coordinates;
+  return value?.type === "Point" && Array.isArray(coordinates) && typeof coordinates[0] === "number" && typeof coordinates[1] === "number" ? [coordinates[0], coordinates[1]] : void 0;
+}
+function jsonProperties(properties) {
+  return Object.fromEntries(
+    Object.entries(properties ?? {}).filter(([, value]) => value !== void 0)
+  );
+}
+function configureClusterStyles(element) {
+  element.style.alignItems = "center";
+  element.style.background = "var(--tileflow-interaction-cluster-color, #2563eb)";
+  element.style.borderColor = "var(--tileflow-interaction-border-color, #ffffff)";
+  element.style.borderRadius = "9999px";
+  element.style.borderStyle = "solid";
+  element.style.borderWidth = "2px";
+  element.style.boxShadow = "var(--tileflow-interaction-shadow, 0 1px 4px rgb(0 0 0 / 0.25))";
+  element.style.color = "var(--tileflow-interaction-foreground, #ffffff)";
+  element.style.cursor = "pointer";
+  element.style.display = "inline-flex";
+  element.style.justifyContent = "center";
+  element.style.minHeight = "2.25rem";
+  element.style.minWidth = "2.25rem";
+  element.style.padding = "0.25rem";
+}
+
 // src/reducer.ts
 var initialTileflowInteractionState = Object.freeze({
   popup: null
@@ -1789,7 +2252,9 @@ function createTileflowMapLibrePoiController(options) {
   };
   const handleClick = (value) => {
     const event = parsePointerEvent(value);
-    if (!event || disposed) return;
+    if (!event || disposed || value.defaultPrevented === true) {
+      return;
+    }
     const modality = inputModality(event);
     const match = hitTest(event);
     if (!match) return;
@@ -2888,6 +3353,7 @@ function unsubscribe(values, value) {
 }
 export {
   createTileflowAnnotationRegistry,
+  createTileflowMapLibreDataRuntime,
   createTileflowMapLibreDomRuntime,
   createTileflowMapLibreInteractionCoordinator,
   createTileflowMapLibrePoiController,

package/dist/{validation-Cy6Tz3lz.d.ts → validation-DBRKrV__.d.ts}

@@ -152,7 +152,20 @@ type TileflowResolvedMapTarget = {
     coordinate: TileflowInteractionCoordinate;
     kind: 'map';
 };
-type TileflowResolvedInteractionTarget<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = TileflowResolvedAnnotationTarget<TAnnotation> | TileflowResolvedSemanticFeatureTarget | TileflowResolvedStyleFeatureTarget | TileflowResolvedMapTarget;
+/** One clustered group of annotations or GeoJSON points. */
+type TileflowResolvedClusterTarget = {
+    /** The annotations inside the group, when annotations were clustered. */
+    annotationIds?: readonly string[];
+    clusterId: number;
+    coordinate: TileflowInteractionCoordinate;
+    kind: 'cluster';
+    pointCount: number;
+    /** Cluster properties, including any `clusterProperties` aggregates. */
+    properties: Readonly<Record<string, TileflowInteractionJsonValue>>;
+    /** The GeoJSON source, when a source was clustered. */
+    source?: string;
+};
+type TileflowResolvedInteractionTarget<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = TileflowResolvedAnnotationTarget<TAnnotation> | TileflowResolvedClusterTarget | TileflowResolvedSemanticFeatureTarget | TileflowResolvedStyleFeatureTarget | TileflowResolvedMapTarget;
 type TileflowAnnotationViewContext<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = {
     annotation: TAnnotation;
     close: () => void;
@@ -427,10 +440,10 @@ declare const tileflowInteractionTargetRefSchema: z.ZodMiniDiscriminatedUnion<[z
     kind: z.ZodMiniLiteral<"annotation">;
 }, z.core.$strict>, z.ZodMiniObject<{
     domain: z.ZodMiniString<string>;
-    featureId: z.ZodMiniUnion<readonly [z.ZodMiniNumberFormat, z.ZodMiniString<string>]>;
+    featureId: z.ZodMiniUnion<readonly [z.ZodMiniInt, z.ZodMiniString<string>]>;
     kind: z.ZodMiniLiteral<"semantic-feature">;
 }, z.core.$strict>, z.ZodMiniObject<{
-    featureId: z.ZodMiniUnion<readonly [z.ZodMiniNumberFormat, z.ZodMiniString<string>]>;
+    featureId: z.ZodMiniUnion<readonly [z.ZodMiniInt, z.ZodMiniString<string>]>;
     kind: z.ZodMiniLiteral<"style-feature">;
     layerId: z.ZodMiniString<string>;
 }, z.core.$strict>, z.ZodMiniObject<{
@@ -443,10 +456,10 @@ declare const tileflowInteractionStateSchema: z.ZodMiniObject<{
         kind: z.ZodMiniLiteral<"annotation">;
     }, z.core.$strict>, z.ZodMiniObject<{
         domain: z.ZodMiniString<string>;
-        featureId: z.ZodMiniUnion<readonly [z.ZodMiniNumberFormat, z.ZodMiniString<string>]>;
+        featureId: z.ZodMiniUnion<readonly [z.ZodMiniInt, z.ZodMiniString<string>]>;
         kind: z.ZodMiniLiteral<"semantic-feature">;
     }, z.core.$strict>, z.ZodMiniObject<{
-        featureId: z.ZodMiniUnion<readonly [z.ZodMiniNumberFormat, z.ZodMiniString<string>]>;
+        featureId: z.ZodMiniUnion<readonly [z.ZodMiniInt, z.ZodMiniString<string>]>;
         kind: z.ZodMiniLiteral<"style-feature">;
         layerId: z.ZodMiniString<string>;
     }, z.core.$strict>, z.ZodMiniObject<{
@@ -460,10 +473,10 @@ declare const tileflowInteractionActionSchema: z.ZodMiniDiscriminatedUnion<[z.Zo
         kind: z.ZodMiniLiteral<"annotation">;
     }, z.core.$strict>, z.ZodMiniObject<{
         domain: z.ZodMiniString<string>;
-        featureId: z.ZodMiniUnion<readonly [z.ZodMiniNumberFormat, z.ZodMiniString<string>]>;
+        featureId: z.ZodMiniUnion<readonly [z.ZodMiniInt, z.ZodMiniString<string>]>;
         kind: z.ZodMiniLiteral<"semantic-feature">;
     }, z.core.$strict>, z.ZodMiniObject<{
-        featureId: z.ZodMiniUnion<readonly [z.ZodMiniNumberFormat, z.ZodMiniString<string>]>;
+        featureId: z.ZodMiniUnion<readonly [z.ZodMiniInt, z.ZodMiniString<string>]>;
         kind: z.ZodMiniLiteral<"style-feature">;
         layerId: z.ZodMiniString<string>;
     }, z.core.$strict>, z.ZodMiniObject<{
@@ -475,7 +488,44 @@ declare const tileflowInteractionActionSchema: z.ZodMiniDiscriminatedUnion<[z.Zo
     type: z.ZodMiniLiteral<"close-popup">;
 }, z.core.$strict>], "type">;
 
-type TileflowInteractionDiagnosticCode = 'DUPLICATE_ANNOTATION_ID' | 'INVALID_FIELD' | 'INVALID_ANNOTATION' | 'INVALID_DOCUMENT' | 'LIMIT_EXCEEDED' | 'MISSING_VIEW' | 'OVERLAY_FAILURE' | 'SEMANTIC_MANIFEST_MISMATCH' | 'STALE_TARGET' | 'UNSTABLE_FEATURE_IDENTITY' | 'UNSUPPORTED_MODE' | 'UNSUPPORTED_TARGET';
+type TileflowAnnotationClusterOptions = Readonly<{
+    /** The last zoom that clusters; annotations are separate above it. Defaults to 14. */
+    clusterMaxZoom?: number;
+    /** The fewest annotations that form a cluster. Defaults to 2. */
+    clusterMinPoints?: number;
+    /** Cluster radius in CSS pixels or density-independent points. Defaults to 50. */
+    clusterRadius?: number;
+    /** Zoom in when a cluster is activated. Defaults to true. */
+    expandOnClick?: boolean;
+    /** The accessible name of a cluster. Defaults to `${count} places`. */
+    formatAriaLabel?: (count: number) => string;
+}>;
+type TileflowAnnotationCluster = Readonly<{
+    annotationIds: readonly string[];
+    clusterId: number;
+    coordinate: TileflowInteractionCoordinate;
+    /** The zoom at which this cluster splits. */
+    expansionZoom: number;
+    /** `point_count_abbreviated`, such as `1.2k`. */
+    label: string;
+    pointCount: number;
+}>;
+type TileflowAnnotationClusterView = Readonly<{
+    clusters: readonly TileflowAnnotationCluster[];
+    /** Annotations a cluster stands in for at this zoom. */
+    hiddenAnnotationIds: ReadonlySet<string>;
+}>;
+type TileflowAnnotationClusterIndex = Readonly<{
+    /** Groups for one map zoom. Results depend on its integer part only. */
+    at: (zoom: number) => TileflowAnnotationClusterView;
+}>;
+/**
+ * Groups annotations the way a clustering GeoJSON source groups points, with the same option names.
+ * It is pure, so web and native renderers share one result.
+ */
+declare function createTileflowAnnotationClusterIndex(annotations: readonly TileflowAnnotation[], options?: TileflowAnnotationClusterOptions): TileflowAnnotationClusterIndex;
+
+type TileflowInteractionDiagnosticCode = 'DUPLICATE_ANNOTATION_ID' | 'INVALID_FIELD' | 'INVALID_ANNOTATION' | 'INVALID_DATA_LAYER' | 'INVALID_DOCUMENT' | 'LIMIT_EXCEEDED' | 'MISSING_VIEW' | 'OVERLAY_FAILURE' | 'SEMANTIC_MANIFEST_MISMATCH' | 'STALE_TARGET' | 'UNSTABLE_FEATURE_IDENTITY' | 'UNSUPPORTED_MODE' | 'UNSUPPORTED_TARGET';
 type TileflowInteractionDiagnostic = {
     code: TileflowInteractionDiagnosticCode;
     level: 'error' | 'warning';
@@ -503,4 +553,4 @@ type TileflowInteractionBindingValidationResult = {
 declare function validateTileflowAnnotations(input: unknown): TileflowAnnotationValidationResult;
 declare function validateTileflowInteractionBindings(input: unknown): TileflowInteractionBindingValidationResult;
 
-export { type TileflowPoiProperties as A, type TileflowPoiSizeRank as B, type TileflowResolvedAnnotationTarget as C, type TileflowResolvedInteractionTarget as D, type TileflowResolvedMapTarget as E, type TileflowResolvedPoiFeature as F, type TileflowResolvedPoiFeatureTarget as G, type TileflowResolvedSemanticFeature as H, type TileflowResolvedSemanticFeatureTarget as I, type TileflowResolvedStyleFeatureTarget as J, tileflowAnnotationSchema as K, tileflowAnnotationsSchema as L, tileflowInteractionActionSchema as M, tileflowInteractionBindingSchema as N, tileflowInteractionBindingsSchema as O, tileflowInteractionContentSchema as P, tileflowInteractionJsonValueSchema as Q, tileflowInteractionLimits as R, tileflowInteractionSchemaVersion as S, type TileflowInteractionState as T, tileflowInteractionStateSchema as U, tileflowInteractionTargetRefSchema as V, tileflowInteractionTargetSchema as W, tileflowPoiCategories as X, validateTileflowAnnotations as Y, validateTileflowInteractionBindings as Z, type TileflowInteractionAction as a, type TileflowInteractionTargetRef as b, type TileflowAnnotation as c, type TileflowAnnotationInteractionEvent as d, type TileflowAnnotationMarker as e, type TileflowAnnotationSurface as f, type TileflowAnnotationValidationResult as g, type TileflowAnnotationViewContext as h, type TileflowInteractionBinding as i, type TileflowInteractionBindingValidationResult as j, type TileflowInteractionContent as k, type TileflowInteractionCoordinate as l, type TileflowInteractionDiagnostic as m, type TileflowInteractionDiagnosticCode as n, type TileflowInteractionEvent as o, type TileflowInteractionEventType as p, type TileflowInteractionFieldContent as q, type TileflowInteractionInputModality as r, type TileflowInteractionJsonPrimitive as s, type TileflowInteractionJsonValue as t, type TileflowInteractionTarget as u, type TileflowInteractionTextContent as v, type TileflowInteractionViewContent as w, type TileflowInteractionViewContext as x, type TileflowPoiCategory as y, type TileflowPoiFilterRank as z };
+export { tileflowInteractionTargetRefSchema as $, type TileflowInteractionViewContent as A, type TileflowInteractionViewContext as B, type TileflowPoiCategory as C, type TileflowPoiFilterRank as D, type TileflowPoiProperties as E, type TileflowPoiSizeRank as F, type TileflowResolvedAnnotationTarget as G, type TileflowResolvedClusterTarget as H, type TileflowResolvedInteractionTarget as I, type TileflowResolvedMapTarget as J, type TileflowResolvedPoiFeature as K, type TileflowResolvedPoiFeatureTarget as L, type TileflowResolvedSemanticFeature as M, type TileflowResolvedSemanticFeatureTarget as N, type TileflowResolvedStyleFeatureTarget as O, createTileflowAnnotationClusterIndex as P, tileflowAnnotationSchema as Q, tileflowAnnotationsSchema as R, tileflowInteractionActionSchema as S, type TileflowInteractionState as T, tileflowInteractionBindingSchema as U, tileflowInteractionBindingsSchema as V, tileflowInteractionContentSchema as W, tileflowInteractionJsonValueSchema as X, tileflowInteractionLimits as Y, tileflowInteractionSchemaVersion as Z, tileflowInteractionStateSchema as _, type TileflowInteractionAction as a, tileflowInteractionTargetSchema as a0, tileflowPoiCategories as a1, validateTileflowAnnotations as a2, validateTileflowInteractionBindings as a3, type TileflowInteractionTargetRef as b, type TileflowAnnotation as c, type TileflowAnnotationCluster as d, type TileflowAnnotationClusterIndex as e, type TileflowAnnotationClusterOptions as f, type TileflowAnnotationClusterView as g, type TileflowAnnotationInteractionEvent as h, type TileflowAnnotationMarker as i, type TileflowAnnotationSurface as j, type TileflowAnnotationValidationResult as k, type TileflowAnnotationViewContext as l, type TileflowInteractionBinding as m, type TileflowInteractionBindingValidationResult as n, type TileflowInteractionContent as o, type TileflowInteractionCoordinate as p, type TileflowInteractionDiagnostic as q, type TileflowInteractionDiagnosticCode as r, type TileflowInteractionEvent as s, type TileflowInteractionEventType as t, type TileflowInteractionFieldContent as u, type TileflowInteractionInputModality as v, type TileflowInteractionJsonPrimitive as w, type TileflowInteractionJsonValue as x, type TileflowInteractionTarget as y, type TileflowInteractionTextContent as z };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@tileflow/interactions",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "license": "Apache-2.0",
-  "description": "Portable annotation and interaction contracts for Tileflow maps.",
+  "description": "Portable annotation, clustering and interaction contracts for Tileflow maps.",
   "type": "module",
   "sideEffects": false,
   "homepage": "https://tileflow.dev",
@@ -24,7 +24,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    "REFERENCE.md"
   ],
   "exports": {
     ".": {
@@ -43,7 +44,8 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^4.4.3"
+    "supercluster": "^8.0.1",
+    "zod": "^4.6.7"
   },
   "peerDependencies": {
     "maplibre-gl": ">=6.4.1 <7"
@@ -53,6 +55,10 @@
       "optional": true
     }
   },
+  "devDependencies": {
+    "@types/supercluster": "^7.1.3",
+    "maplibre-gl": "6.16.0"
+  },
   "scripts": {
     "build": "tsup src/index.ts src/maplibre-entry.ts --format esm --dts --clean --no-splitting",
     "verify": "pnpm run build && tsx --test test/*.test.ts",