@tileflow/react 0.1.0-alpha.16 → 0.1.0-alpha.18

package/README.md

@@ -38,7 +38,7 @@ manifest:
 Or bypass the manifest and load a hosted style directly:
 
 ```tsx
-<Map styleUrl="https://api.tileflow.dev/v1/styles/acme/madrid.json" />
+<Map styleUrl="https://api.tileflow.dev/maps/map_1234567890abcdef/style.json" />
 ```
 
 For simple hosted static images, use image mode:
@@ -55,6 +55,35 @@ the production image behavior locally.
 For full static scenes with bounds, overlays, and server-side precache, use
 `StaticMap` from `@tileflow/react/static` or helpers from `@tileflow/static`.
 
+```tsx
+import {StaticMap} from '@tileflow/react/static';
+import {useState} from 'react';
+import {createStaticMapIdempotencyKey} from '@tileflow/static';
+
+export function Preview() {
+  const [idempotencyKey] = useState(createStaticMapIdempotencyKey);
+
+  return (
+    <StaticMap
+      map="madrid"
+      camera={{type: 'center', center: [-3.7038, 40.4168], zoom: 12}}
+      size={{width: 1200, height: 800}}
+      createUrl="/api/static-maps"
+      idempotencyKey={idempotencyKey}
+    />
+  );
+}
+```
+
+`idempotencyKey` is required in create mode. Keep one key for one intentional create action and
+reuse it across retries and remounts. Concurrent React consumers share work only when URL,
+normalized scene, and idempotency key all identify the same operation; unmounting the final
+consumer aborts its in-flight request.
+
+Hosted interactive maps automatically preflight a short-lived commercial session grant before
+eligible resources. Setting `analytics={{enabled: false}}` disables the optional beacon only; it
+does not remove hosted authorization or override a user `mapOptions.transformRequest` callback.
+
 ## Headless capture readiness
 
 Use `captureId` to disambiguate multiple maps with the same configured name:

package/dist/index.js

@@ -10,20 +10,24 @@ import {
 } from "react";
 import maplibregl from "maplibre-gl";
 import {
-  createTileflowSessionId,
+  createTileflowSessionController,
   defaultTileflowManifestUrl,
   loadTileflowManifest,
   mergeTileflowAnalytics,
   normalizeTileflowCaptureId,
   normalizeTileflowStaticImageSize,
-  resolveTileflowAnalyticsRequestUrl,
   resolveTileflowManifestMap,
   resolveTileflowMapMode,
   resolveTileflowRuntimeStyle,
   resolveTileflowStaticImageUrl,
-  shouldLoadTileflowManifest,
-  startTileflowSession
+  shouldLoadTileflowManifest
 } from "@tileflow/core";
+import {
+  attachTileflowMapLifecycle,
+  createTileflowMarkerController,
+  createTileflowSessionStarter,
+  createTileflowTransformRequest
+} from "@tileflow/core/browser";
 import { jsx } from "react/jsx-runtime";
 var defaultCenter = [0, 20];
 var defaultMarkers = [];
@@ -55,7 +59,6 @@ function Map({
   const containerRef = useRef(null);
   const imageRef = useRef(null);
   const mapRef = useRef(null);
-  const markerInstancesRef = useRef([]);
   const stableMapOptions = useStableMapOptions(mapOptions);
   const resolvedCenter = useStableMapOptionValue(
     center ?? stableMapOptions?.center ?? defaultCenter
@@ -68,9 +71,24 @@ function Map({
   const onLoadRef = useRef(onLoad);
   const mapNameRef = useRef(mapName);
   const resolvedAnalyticsRef = useRef(void 0);
-  const sessionStartsRef = useRef(/* @__PURE__ */ new Set());
   const readinessRunRef = useRef(0);
-  const sessionId = useMemo(() => createTileflowSessionId(), []);
+  const markerController = useMemo(
+    () => createTileflowMarkerController({
+      attach(markerInstance, map, marker) {
+        markerInstance.setLngLat(marker.coordinates).addTo(map);
+        markerInstance.getElement().title = marker.label ?? marker.id;
+      },
+      create(marker) {
+        return new maplibregl.Marker({
+          color: marker.color ?? "#C6A15B"
+        });
+      },
+      remove(markerInstance) {
+        markerInstance.remove();
+      }
+    }),
+    []
+  );
   const [manifestMap, setManifestMap] = useState(null);
   const [imageSize, setImageSize] = useState(null);
   const [captureState, setCaptureState] = useState("loading");
@@ -165,14 +183,6 @@ function Map({
     }) : void 0),
     [imageSize, imageUrl, isImageMode, manifestMap, resolvedZoom, staticImageCenter]
   );
-  const transformRequest = useMemo(
-    () => createTransformRequest(
-      () => resolvedAnalyticsRef.current,
-      sessionId,
-      stableMapOptions?.transformRequest
-    ),
-    [sessionId, stableMapOptions?.transformRequest]
-  );
   useEffect(() => {
     if (!isImageMode || imageUrl || !containerRef.current) {
       setImageSize(null);
@@ -199,25 +209,22 @@ function Map({
     if (!containerRef.current || !runtimeStyle) {
       return;
     }
-    const setLoading = () => {
-      readinessRunRef.current += 1;
-      setCaptureState("loading");
-    };
-    const setError = () => {
-      readinessRunRef.current += 1;
-      setCaptureState("error");
-    };
-    const setIdleAfterFrames = () => {
-      const run = ++readinessRunRef.current;
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          if (readinessRunRef.current === run && mapRef.current === map) {
-            setCaptureState("idle");
-          }
-        });
-      });
-    };
-    setLoading();
+    readinessRunRef.current += 1;
+    setCaptureState("loading");
+    const session = createTileflowSessionController({ source: "react" });
+    const sessionStarter = createTileflowSessionStarter({
+      getSessionId: () => session.sessionId,
+      sessionId: session.sessionId,
+      source: "react"
+    });
+    const transformRequest = createTileflowTransformRequest({
+      always: true,
+      asyncAnalyticsTiming: "resolution",
+      getAnalytics: () => resolvedAnalyticsRef.current,
+      sessionController: session,
+      sessionId: session.sessionId,
+      transformRequest: stableMapOptions?.transformRequest ?? void 0
+    });
     const map = new maplibregl.Map({
       ...stableMapOptions,
       container: containerRef.current,
@@ -237,36 +244,50 @@ function Map({
       map.resize();
     });
     resizeObserver.observe(containerRef.current);
-    map.on("load", () => {
-      const analyticsForLoad = resolvedAnalyticsRef.current;
-      const styleId = analyticsForLoad?.styleId ?? (typeof runtimeStyle.style === "string" ? runtimeStyle.style : mapNameRef.current);
-      onLoadRef.current?.(map);
-      if (analyticsForLoad?.mapId) {
-        const sessionKey = `${sessionId}:${analyticsForLoad.mapId}:${styleId ?? ""}`;
-        if (!sessionStartsRef.current.has(sessionKey)) {
-          sessionStartsRef.current.add(sessionKey);
-          startTileflowSession(analyticsForLoad, {
-            mapId: analyticsForLoad.mapId,
-            sessionId,
-            source: "react",
-            styleId
-          });
-        }
+    const lifecycle = attachTileflowMapLifecycle({
+      getSession: () => {
+        const analyticsForLoad = resolvedAnalyticsRef.current;
+        return {
+          analytics: analyticsForLoad,
+          styleId: analyticsForLoad?.styleId ?? (typeof runtimeStyle.style === "string" ? runtimeStyle.style : mapNameRef.current)
+        };
+      },
+      map,
+      onLoad: (loadedMap) => {
+        onLoadRef.current?.(loadedMap);
+      },
+      scheduler: {
+        cancelFrame: (frame) => cancelAnimationFrame(frame),
+        requestFrame: (callback) => requestAnimationFrame(callback)
+      },
+      sessionStarter,
+      setState: setCaptureState,
+      subscribe: (subscribedMap, event, listener) => {
+        const subscription = subscribedMap.on(event, listener);
+        return () => subscription.unsubscribe();
       }
     });
-    map.on("dataloading", setLoading);
-    map.on("styledataloading", setLoading);
-    map.on("idle", setIdleAfterFrames);
-    map.on("error", setError);
     return () => {
       readinessRunRef.current += 1;
-      resizeObserver.disconnect();
-      clearMarkers(markerInstancesRef.current);
-      markerInstancesRef.current = [];
-      map.remove();
-      mapRef.current = null;
+      try {
+        lifecycle.dispose();
+      } finally {
+        try {
+          resizeObserver.disconnect();
+        } finally {
+          try {
+            markerController.clear();
+          } finally {
+            try {
+              map.remove();
+            } finally {
+              if (mapRef.current === map) mapRef.current = null;
+            }
+          }
+        }
+      }
     };
-  }, [resolvedInteractive, runtimeStyle, sessionId, stableMapOptions, transformRequest]);
+  }, [markerController, resolvedInteractive, runtimeStyle, stableMapOptions]);
   useLayoutEffect(() => {
     if (!isImageMode) return;
     readinessRunRef.current += 1;
@@ -291,23 +312,15 @@ function Map({
   }
   useEffect(() => {
     const map = mapRef.current;
-    clearMarkers(markerInstancesRef.current);
-    markerInstancesRef.current = [];
+    markerController.clear();
     if (!map) {
       return;
     }
-    markerInstancesRef.current = markers.map((marker) => {
-      const markerInstance = new maplibregl.Marker({
-        color: marker.color ?? "#C6A15B"
-      }).setLngLat(marker.coordinates).addTo(map);
-      markerInstance.getElement().title = marker.label ?? marker.id;
-      return markerInstance;
-    });
+    markerController.replace(map, markers);
     return () => {
-      clearMarkers(markerInstancesRef.current);
-      markerInstancesRef.current = [];
+      markerController.clear();
     };
-  }, [markers, runtimeStyle]);
+  }, [markerController, markers, runtimeStyle]);
   const frameStyle = {
     height,
     minHeight: 240,
@@ -361,31 +374,6 @@ function Map({
     }
   );
 }
-function createTransformRequest(getAnalytics, sessionId, userTransformRequest) {
-  return (url, resourceType) => {
-    const request = userTransformRequest?.(url, resourceType);
-    if (isPromiseLike(request)) {
-      return request.then(
-        (resolvedRequest) => applyTileflowAnalyticsRequest(url, resolvedRequest, getAnalytics(), sessionId) ?? resolvedRequest
-      );
-    }
-    return applyTileflowAnalyticsRequest(url, request, getAnalytics(), sessionId);
-  };
-}
-function applyTileflowAnalyticsRequest(url, request, analytics, sessionId) {
-  const requestUrl = request?.url ?? url;
-  const nextUrl = resolveTileflowAnalyticsRequestUrl(requestUrl, analytics, sessionId);
-  if (!nextUrl) {
-    return request;
-  }
-  return request ? { ...request, url: nextUrl } : { url: nextUrl };
-}
-function isPromiseLike(value) {
-  return Boolean(value && typeof value.then === "function");
-}
-function clearMarkers(markerInstances) {
-  markerInstances.forEach((marker) => marker.remove());
-}
 function useStableMapOptions(options) {
   return useStableMapOptionValue(options);
 }

package/dist/static.d.ts

@@ -16,13 +16,15 @@ type StaticMapBaseProps = StaticSceneInput & {
 };
 type StaticMapImageProps = {
     createUrl?: never;
+    idempotencyKey?: never;
     imageUrl: string;
 };
 type StaticMapCreateProps = {
     createUrl: string;
+    idempotencyKey: string;
     imageUrl?: never;
 };
 type StaticMapProps = StaticMapBaseProps & (StaticMapCreateProps | StaticMapImageProps);
-declare function StaticMap({ alt, camera, className, captureId, createUrl, imageStyle, imageUrl, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, }: StaticMapProps): react.JSX.Element;
+declare function StaticMap({ alt, camera, className, captureId, createUrl, imageStyle, imageUrl, idempotencyKey, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, }: StaticMapProps): react.JSX.Element;
 
 export { StaticMap, type StaticMapProps };

package/dist/static.js

@@ -9,8 +9,181 @@ import {
   useState
 } from "react";
 import { normalizeTileflowCaptureId } from "@tileflow/core";
-import { jsx } from "react/jsx-runtime";
+import {
+  validateStaticMapIdempotencyKey
+} from "@tileflow/static";
+
+// src/static-map-request.ts
+import {
+  staticMapProcessingResultSchema,
+  staticMapReadyResultSchema
+} from "@tileflow/static";
 var inFlightRequests = /* @__PURE__ */ new Map();
+function createStaticMapRequestKey(input) {
+  return stableStringify(input);
+}
+async function resolveStaticMap(input) {
+  throwIfAborted(input.signal);
+  let entry = inFlightRequests.get(input.requestKey);
+  if (!entry) {
+    const controller = new AbortController();
+    const promise = requestStaticMapUntilReady({ ...input, signal: controller.signal });
+    const created = {
+      controller,
+      consumers: 0,
+      promise,
+      settled: false
+    };
+    const settle = () => {
+      created.settled = true;
+      if (inFlightRequests.get(input.requestKey) === created) {
+        inFlightRequests.delete(input.requestKey);
+      }
+    };
+    void promise.then(settle, settle);
+    inFlightRequests.set(input.requestKey, created);
+    entry = created;
+  }
+  entry.consumers += 1;
+  try {
+    return await raceWithAbort(entry.promise, input.signal);
+  } finally {
+    entry.consumers -= 1;
+    if (entry.consumers === 0 && !entry.settled) {
+      if (inFlightRequests.get(input.requestKey) === entry) {
+        inFlightRequests.delete(input.requestKey);
+      }
+      entry.controller.abort();
+    }
+  }
+}
+async function requestStaticMapUntilReady(input) {
+  const maxWaitMs = input.maxWaitMs ?? 3e4;
+  if (!Number.isSafeInteger(maxWaitMs) || maxWaitMs < 1 || maxWaitMs > 12e4) {
+    throw new Error("Static map maxWaitMs must be an integer from 1 to 120000");
+  }
+  return runWithinBudget(maxWaitMs, input.signal, async (signal) => {
+    const body = JSON.stringify(input.scene);
+    const fetcher = input.fetch ?? fetch;
+    let operationId = null;
+    while (true) {
+      const response = await fetcher(input.createUrl, {
+        body,
+        headers: {
+          "Content-Type": "application/json",
+          "Idempotency-Key": input.idempotencyKey
+        },
+        method: "POST",
+        signal
+      });
+      throwIfAborted(signal);
+      if (!response.ok) throw new Error(`Static map endpoint failed: ${response.status}`);
+      let value;
+      try {
+        value = await response.json();
+      } catch {
+        throw new Error("Static map endpoint returned invalid JSON");
+      }
+      throwIfAborted(signal);
+      if (response.status !== 202) {
+        const ready = staticMapReadyResultSchema.safeParse(value);
+        if (!ready.success) throw new Error("Static map endpoint returned an invalid response");
+        assertStaticMapOperationIdentity(operationId, ready.data.operationId);
+        return ready.data;
+      }
+      const pending = staticMapProcessingResultSchema.safeParse(value);
+      if (!pending.success) throw new Error("Static map endpoint returned an invalid response");
+      assertStaticMapOperationIdentity(operationId, pending.data.operationId);
+      operationId ??= pending.data.operationId;
+      await delay(pending.data.retryAfterMs, signal);
+    }
+  });
+}
+function stableStringify(value) {
+  return JSON.stringify(sortJson(value));
+}
+function assertStaticMapOperationIdentity(expected, actual) {
+  if (expected !== null && actual !== expected) {
+    throw new Error("Static map endpoint changed operation identity while polling");
+  }
+}
+async function runWithinBudget(maxWaitMs, externalSignal, operation) {
+  const controller = new AbortController();
+  const timeoutError = new Error(`Static map request timed out after ${maxWaitMs}ms`);
+  const abortFromConsumer = () => controller.abort(externalSignal?.reason);
+  if (externalSignal?.aborted) abortFromConsumer();
+  else externalSignal?.addEventListener("abort", abortFromConsumer, { once: true });
+  const timeout = setTimeout(() => controller.abort(timeoutError), maxWaitMs);
+  try {
+    throwIfAborted(controller.signal);
+    const pending = operation(controller.signal);
+    return await raceWithAbort(pending, controller.signal);
+  } finally {
+    clearTimeout(timeout);
+    externalSignal?.removeEventListener("abort", abortFromConsumer);
+  }
+}
+function delay(milliseconds, signal) {
+  if (milliseconds === 0) {
+    throwIfAborted(signal);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, milliseconds);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(abortReason(signal));
+    };
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function raceWithAbort(operation, signal) {
+  if (!signal) return operation;
+  if (signal.aborted) return Promise.reject(abortReason(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(abortReason(signal));
+    };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      }
+    );
+  });
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortReason(signal);
+}
+function abortReason(signal) {
+  if (signal.reason instanceof Error) return signal.reason;
+  const error = new Error("Static map request was aborted");
+  error.name = "AbortError";
+  return error;
+}
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, sortJson(entry)])
+    );
+  }
+  return value;
+}
+
+// src/static-map.tsx
+import { jsx } from "react/jsx-runtime";
 function StaticMap({
   alt = "",
   camera,
@@ -19,6 +192,7 @@ function StaticMap({
   createUrl,
   imageStyle,
   imageUrl,
+  idempotencyKey,
   keepPreviousImage = false,
   loading = "lazy",
   map,
@@ -43,7 +217,7 @@ function StaticMap({
     () => stableStringify({ camera, map, overlays, size }),
     [camera, map, overlays, size]
   );
-  const requestKey = imageUrl ? `image:${imageUrl}` : `create:${createUrl}:${sceneKey}`;
+  const intentKey = imageUrl ? `image:${imageUrl}` : `create:${createUrl}:${idempotencyKey ?? ""}:${sceneKey}`;
   useLayoutEffect(() => {
     imageLoadRunRef.current += 1;
     setCaptureState("loading");
@@ -52,7 +226,7 @@ function StaticMap({
       if (image.naturalWidth === 0) setCaptureState("error");
       else void markImageReady(image);
     }
-  }, [requestKey]);
+  }, [intentKey]);
   async function markImageReady(image) {
     const runId = ++imageLoadRunRef.current;
     try {
@@ -81,14 +255,31 @@ function StaticMap({
     if (!createUrl) {
       return;
     }
+    const validation = validateStaticMapIdempotencyKey(idempotencyKey ?? "");
+    if (!validation.ok) {
+      const keyError = new Error(`Invalid Static Maps idempotency key: ${validation.error}`);
+      if (!keepPreviousImage) setResult(null);
+      setError(keyError);
+      imageLoadRunRef.current += 1;
+      setCaptureState("error");
+      onErrorRef.current?.(keyError);
+      return;
+    }
     if (!keepPreviousImage) {
       setResult(null);
     }
     setError(null);
+    const requestController = new AbortController();
     resolveStaticMap({
       createUrl,
-      requestKey,
-      scene: JSON.parse(sceneKey)
+      idempotencyKey: validation.key,
+      requestKey: createStaticMapRequestKey({
+        createUrl,
+        idempotencyKey: validation.key,
+        sceneKey
+      }),
+      scene: JSON.parse(sceneKey),
+      signal: requestController.signal
     }).then((nextResult) => {
       if (cancelled) {
         return;
@@ -111,8 +302,9 @@ function StaticMap({
     });
     return () => {
       cancelled = true;
+      requestController.abort();
     };
-  }, [createUrl, imageUrl, keepPreviousImage, requestKey, sceneKey]);
+  }, [createUrl, idempotencyKey, imageUrl, intentKey, keepPreviousImage, sceneKey]);
   return /* @__PURE__ */ jsx(
     "div",
     {
@@ -159,50 +351,17 @@ function StaticMap({
     }
   );
 }
-async function resolveStaticMap(input) {
-  const existing = inFlightRequests.get(input.requestKey);
-  if (existing) {
-    return existing;
-  }
-  const promise = fetch(input.createUrl, {
-    body: JSON.stringify(input.scene),
-    headers: {
-      "Content-Type": "application/json"
-    },
-    method: "POST"
-  }).then(async (response) => {
-    if (!response.ok) {
-      throw new Error(`Static map endpoint failed: ${response.status}`);
-    }
-    return await response.json();
-  }).finally(() => {
-    inFlightRequests.delete(input.requestKey);
-  });
-  inFlightRequests.set(input.requestKey, promise);
-  return promise;
-}
 function imageResult(imageUrl) {
   return {
     cached: true,
     hash: "",
     imageUrl,
-    status: "ready"
+    operationId: null,
+    remainingUnits: null,
+    status: "ready",
+    unitCost: 0
   };
 }
-function stableStringify(value) {
-  return JSON.stringify(sortJson(value));
-}
-function sortJson(value) {
-  if (Array.isArray(value)) {
-    return value.map(sortJson);
-  }
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, sortJson(entry)])
-    );
-  }
-  return value;
-}
 export {
   StaticMap
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "description": "React components for rendering Tileflow maps with MapLibre.",
   "type": "module",
   "sideEffects": false,
@@ -41,8 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": "0.1.0-alpha.16",
-    "@tileflow/static": "0.1.0-alpha.16"
+    "@tileflow/core": ">=0.1.0-alpha.18 <0.1.0-beta.0",
+    "@tileflow/static": ">=0.1.0-alpha.17 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5",