@tileflow/react 0.1.0-alpha.14 → 0.1.0-alpha.17

package/README.md

@@ -55,4 +55,18 @@ 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`.
 
+## Headless capture readiness
+
+Use `captureId` to disambiguate multiple maps with the same configured name:
+
+```tsx
+<Map map="madrid" captureId="checkout-map" />
+```
+
+The root element exposes `data-tileflow-map`, optional `data-tileflow-capture-id`, and
+`data-tileflow-state="loading|idle|error"`. Interactive mode becomes idle after MapLibre is idle
+and two animation frames; style/data work returns it to loading. Image mode waits for decode or a
+successful load fallback, including cached hydration. `tileflow capture` uses these markers for
+application scenes and requires exactly one target.
+
 Docs: https://tileflow.dev/docs

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { TileflowConfig, MapLibreStyle, TileflowProjectThemes, TileflowMapMarker
 type MapMarker = TileflowMapMarker;
 type TileflowMapOptions = Omit<MapOptions, 'container' | 'style'>;
 type MapProps = {
+    captureId?: string;
     map?: string;
     mode?: 'interactive' | 'image';
     config?: TileflowConfig;
@@ -29,6 +30,6 @@ type MapProps = {
     analytics?: TileflowAnalytics;
     onLoad?: (map: Map$1) => void;
 };
-declare function Map({ map: mapName, mode, config, style, styleUrl, imageUrl, styleBaseUrl, tileBaseUrl, themes, manifestUrl, preferLocalDev, alt, center, zoom, className, height, imageLoading, interactive, mapOptions, markers, analytics, onLoad, }: MapProps): react.JSX.Element;
+declare function Map({ captureId, map: mapName, mode, config, style, styleUrl, imageUrl, styleBaseUrl, tileBaseUrl, themes, manifestUrl, preferLocalDev, alt, center, zoom, className, height, imageLoading, interactive, mapOptions, markers, analytics, onLoad, }: MapProps): react.JSX.Element;
 
 export { Map, type MapMarker, type MapProps, type TileflowMapOptions };

package/dist/index.js

@@ -3,6 +3,7 @@
 // src/map.tsx
 import {
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState
@@ -13,19 +14,25 @@ import {
   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 = [];
 function Map({
+  captureId,
   map: mapName,
   mode = "interactive",
   config,
@@ -50,8 +57,8 @@ function Map({
   onLoad
 }) {
   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
@@ -64,10 +71,33 @@ 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 sessionStarter = useMemo(
+    () => createTileflowSessionStarter({ sessionId, source: "react" }),
+    [sessionId]
+  );
+  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");
+  const resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   const resolvedMode = resolveTileflowMapMode({ imageUrl, mode, preferLocalDev });
   const isImageMode = resolvedMode === "image";
   useEffect(() => {
@@ -159,11 +189,13 @@ function Map({
     [imageSize, imageUrl, isImageMode, manifestMap, resolvedZoom, staticImageCenter]
   );
   const transformRequest = useMemo(
-    () => createTransformRequest(
-      () => resolvedAnalyticsRef.current,
+    () => createTileflowTransformRequest({
+      always: true,
+      asyncAnalyticsTiming: "resolution",
+      getAnalytics: () => resolvedAnalyticsRef.current,
       sessionId,
-      stableMapOptions?.transformRequest
-    ),
+      transformRequest: stableMapOptions?.transformRequest ?? void 0
+    }),
     [sessionId, stableMapOptions?.transformRequest]
   );
   useEffect(() => {
@@ -192,6 +224,8 @@ function Map({
     if (!containerRef.current || !runtimeStyle) {
       return;
     }
+    readinessRunRef.current += 1;
+    setCaptureState("loading");
     const map = new maplibregl.Map({
       ...stableMapOptions,
       container: containerRef.current,
@@ -211,50 +245,90 @@ 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();
       }
     });
     return () => {
-      resizeObserver.disconnect();
-      clearMarkers(markerInstancesRef.current);
-      markerInstancesRef.current = [];
-      map.remove();
-      mapRef.current = null;
+      readinessRunRef.current += 1;
+      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,
+    sessionStarter,
+    stableMapOptions,
+    transformRequest
+  ]);
+  useLayoutEffect(() => {
+    if (!isImageMode) return;
+    readinessRunRef.current += 1;
+    setCaptureState("loading");
+    const image = imageRef.current;
+    if (image?.complete) {
+      if (image.naturalWidth === 0) setCaptureState("error");
+      else void markImageReady(image);
+    }
+  }, [isImageMode, runtimeImageUrl]);
+  async function markImageReady(image) {
+    const run = ++readinessRunRef.current;
+    try {
+      if (typeof image.decode === "function") await image.decode();
+    } catch {
+      if (!image.complete || image.naturalWidth === 0) {
+        if (readinessRunRef.current === run) setCaptureState("error");
+        return;
+      }
+    }
+    if (readinessRunRef.current === run) setCaptureState("idle");
+  }
   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,
@@ -263,48 +337,50 @@ function Map({
     width: "100%"
   };
   if (isImageMode) {
-    return /* @__PURE__ */ jsx("div", { className, ref: containerRef, style: frameStyle, children: runtimeImageUrl ? /* @__PURE__ */ jsx(
-      "img",
+    return /* @__PURE__ */ jsx(
+      "div",
       {
-        alt,
-        decoding: "async",
-        loading: imageLoading,
-        src: runtimeImageUrl,
-        style: {
-          display: "block",
-          height: "100%",
-          objectFit: "cover",
-          width: "100%"
-        }
+        className,
+        "data-tileflow-capture-id": resolvedCaptureId,
+        "data-tileflow-map": mapName,
+        "data-tileflow-state": captureState,
+        ref: containerRef,
+        style: frameStyle,
+        children: runtimeImageUrl ? /* @__PURE__ */ jsx(
+          "img",
+          {
+            alt,
+            decoding: "async",
+            loading: imageLoading,
+            onError: () => {
+              readinessRunRef.current += 1;
+              setCaptureState("error");
+            },
+            onLoad: (event) => void markImageReady(event.currentTarget),
+            ref: imageRef,
+            src: runtimeImageUrl,
+            style: {
+              display: "block",
+              height: "100%",
+              objectFit: "cover",
+              width: "100%"
+            }
+          }
+        ) : null
       }
-    ) : null });
+    );
   }
-  return /* @__PURE__ */ jsx("div", { className, ref: containerRef, style: frameStyle });
-}
-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 /* @__PURE__ */ jsx(
+    "div",
+    {
+      className,
+      "data-tileflow-capture-id": resolvedCaptureId,
+      "data-tileflow-map": mapName,
+      "data-tileflow-state": captureState,
+      ref: containerRef,
+      style: frameStyle
     }
-    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

@@ -5,11 +5,12 @@ import { StaticSceneInput, StaticMapResult } from '@tileflow/static';
 type StaticMapBaseProps = StaticSceneInput & {
     alt?: string;
     className?: string;
+    captureId?: string;
     imageStyle?: CSSProperties;
     keepPreviousImage?: boolean;
-    loading?: ImgHTMLAttributes<HTMLImageElement>["loading"];
+    loading?: ImgHTMLAttributes<HTMLImageElement>['loading'];
     onError?: (error: Error) => void;
-    onImageLoad?: ImgHTMLAttributes<HTMLImageElement>["onLoad"];
+    onImageLoad?: ImgHTMLAttributes<HTMLImageElement>['onLoad'];
     onReady?: (result: StaticMapResult) => void;
     style?: CSSProperties;
 };
@@ -22,6 +23,6 @@ type StaticMapCreateProps = {
     imageUrl?: never;
 };
 type StaticMapProps = StaticMapBaseProps & (StaticMapCreateProps | StaticMapImageProps);
-declare function StaticMap({ alt, camera, className, 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, keepPreviousImage, loading, map, onError, onImageLoad, onReady, overlays, size, style, }: StaticMapProps): react.JSX.Element;
 
 export { StaticMap, type StaticMapProps };

package/dist/static.js

@@ -3,16 +3,19 @@
 // src/static-map.tsx
 import {
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState
 } from "react";
+import { normalizeTileflowCaptureId } from "@tileflow/core";
 import { jsx } from "react/jsx-runtime";
 var inFlightRequests = /* @__PURE__ */ new Map();
 function StaticMap({
   alt = "",
   camera,
   className,
+  captureId,
   createUrl,
   imageStyle,
   imageUrl,
@@ -30,6 +33,10 @@ function StaticMap({
     imageUrl ? imageResult(imageUrl) : null
   );
   const [error, setError] = useState(null);
+  const [captureState, setCaptureState] = useState("loading");
+  const imageLoadRunRef = useRef(0);
+  const imageRef = useRef(null);
+  const resolvedCaptureId = normalizeTileflowCaptureId(captureId);
   const onErrorRef = useRef(onError);
   const onReadyRef = useRef(onReady);
   const sceneKey = useMemo(
@@ -37,6 +44,27 @@ function StaticMap({
     [camera, map, overlays, size]
   );
   const requestKey = imageUrl ? `image:${imageUrl}` : `create:${createUrl}:${sceneKey}`;
+  useLayoutEffect(() => {
+    imageLoadRunRef.current += 1;
+    setCaptureState("loading");
+    const image = imageRef.current;
+    if (image?.complete) {
+      if (image.naturalWidth === 0) setCaptureState("error");
+      else void markImageReady(image);
+    }
+  }, [requestKey]);
+  async function markImageReady(image) {
+    const runId = ++imageLoadRunRef.current;
+    try {
+      if (typeof image.decode === "function") await image.decode();
+    } catch {
+      if (!image.complete || image.naturalWidth === 0) {
+        if (runId === imageLoadRunRef.current) setCaptureState("error");
+        return;
+      }
+    }
+    if (runId === imageLoadRunRef.current) setCaptureState("idle");
+  }
   useEffect(() => {
     onErrorRef.current = onError;
     onReadyRef.current = onReady;
@@ -77,6 +105,8 @@ function StaticMap({
         setResult(null);
       }
       setError(normalizedError);
+      imageLoadRunRef.current += 1;
+      setCaptureState("error");
       onErrorRef.current?.(normalizedError);
     });
     return () => {
@@ -88,6 +118,9 @@ function StaticMap({
     {
       "aria-busy": !result && !error,
       className,
+      "data-tileflow-capture-id": resolvedCaptureId,
+      "data-tileflow-map": map,
+      "data-tileflow-state": captureState,
       style: {
         aspectRatio: `${size.width} / ${size.height}`,
         background: "#f4f4f2",
@@ -104,9 +137,15 @@ function StaticMap({
           onError: () => {
             const imageError = new Error("Static map image failed to load");
             setError(imageError);
+            imageLoadRunRef.current += 1;
+            setCaptureState("error");
             onErrorRef.current?.(imageError);
           },
-          onLoad: onImageLoad,
+          onLoad: (event) => {
+            onImageLoad?.(event);
+            void markImageReady(event.currentTarget);
+          },
+          ref: imageRef,
           src: result.imageUrl,
           style: {
             display: "block",

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@tileflow/react",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.17",
   "description": "React components for rendering Tileflow maps with MapLibre.",
   "type": "module",
   "sideEffects": false,
   "homepage": "https://tileflow.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tileflow/tileflow.git",
+    "url": "git+https://github.com/tileflow/tileflow-sdk.git",
     "directory": "packages/react"
   },
   "bugs": {
-    "url": "https://github.com/tileflow/tileflow/issues"
+    "url": "https://github.com/tileflow/tileflow-sdk/issues"
   },
   "keywords": [
     "tileflow",
@@ -41,8 +41,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": "0.1.0-alpha.14",
-    "@tileflow/static": "0.1.0-alpha.14"
+    "@tileflow/core": ">=0.1.0-alpha.17 <0.1.0-beta.0",
+    "@tileflow/static": ">=0.1.0-alpha.16 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=5",