@tileflow/react 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/index.js

@@ -1,156 +1,615 @@
+'use client';
+
 // src/map.tsx
 import {
+  useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState
 } from "react";
-import maplibregl from "maplibre-gl";
+import { createPortal } from "react-dom";
 import {
-  createStyle
-} from "@tileflow/core";
-import { jsx } from "react/jsx-runtime";
-var defaultCenter = [0, 20];
-var defaultMarkers = [];
-var defaultManifestUrl = "/tileflow/manifest.json";
-var maxStaticImageDimension = 1280;
-var maxStaticImagePixels = 1280 * 1280;
-var manifestCache = new globalThis.Map();
-function Map({
-  map: mapName,
-  mode = "interactive",
-  config,
-  style,
-  styleUrl,
-  imageUrl,
-  styleBaseUrl,
-  tileBaseUrl,
-  themes,
-  manifestUrl = defaultManifestUrl,
-  preferLocalDev = true,
-  alt = "",
-  center = defaultCenter,
-  zoom = 2,
-  className,
-  height = 420,
-  imageLoading = "eager",
-  interactive = true,
-  markers = defaultMarkers,
-  analytics,
-  onLoad
-}) {
+  attachTileflowAtmosphere,
+  attachTileflowFairUseNotice,
+  attachTileflowMapLifecycle,
+  createTileflowSessionStarter,
+  createTileflowThemeController,
+  createTileflowVegetation,
+  createTileflowTransformRequest,
+  getTileflowSystemColorScheme,
+  loadTileflowStyleFonts,
+  registerTileflowContourProtocol,
+  registerTileflowPmtilesProtocol,
+  registerTileflowWorldRequestBridge,
+  subscribeTileflowSystemColorScheme
+} from "@tileflow/core/browser";
+import { normalizeTileflowCaptureId } from "@tileflow/core/capture";
+import {
+  createTileflowSessionController,
+  defaultTileflowManifestUrl,
+  defaultTileflowRuntimeView,
+  loadTileflowManifest,
+  mergeTileflowAnalytics,
+  nearestTileflowBlendTheme,
+  normalizeTileflowRuntimeCenter,
+  normalizeTileflowStaticImageSize,
+  resolveTileflowManifestMap,
+  resolveTileflowMapMode,
+  resolveTileflowRuntimeStyle,
+  resolveTileflowRuntimeTheme,
+  resolveTileflowRuntimeThemeBlend,
+  resolveTileflowRuntimeView,
+  resolveTileflowStaticImageUrl
+} from "@tileflow/core/runtime";
+import {
+  createTileflowMapLibreDomRuntime,
+  createTileflowMapLibreInteractionCoordinator,
+  createTileflowMapLibreSemanticDomRuntime
+} from "@tileflow/interactions/maplibre";
+
+// src/annotations.ts
+import {
+  validateTileflowAnnotations
+} from "@tileflow/interactions";
+function prepareTileflowReactAnnotations(annotations) {
+  const candidates = annotations ?? [];
+  const titles = new Map(candidates.map((annotation) => [annotation.id, annotation.ariaLabel]));
+  const validation = validateTileflowAnnotations(candidates);
+  if (!validation.ok) {
+    return {
+      annotations: [],
+      diagnostics: validation.diagnostics,
+      ok: false,
+      titles
+    };
+  }
+  return {
+    // Keep caller-owned identities after validation so generic data and portal reconciliation stay
+    // stable instead of replacing application objects with a schema clone.
+    annotations: candidates,
+    diagnostics: [],
+    ok: true,
+    titles
+  };
+}
+function imageModeAnnotationDiagnostic(annotationCount) {
+  return annotationCount > 0 ? {
+    code: "UNSUPPORTED_MODE",
+    level: "error",
+    message: 'Tileflow annotations require mode="interactive"; image mode cannot render interactive overlays.',
+    path: ""
+  } : void 0;
+}
+function imageModeMapInteractionDiagnostic(annotationCount, bindingCount, hasAdditionalInteractionConfiguration = false) {
+  if (bindingCount === 0 && !hasAdditionalInteractionConfiguration) {
+    return imageModeAnnotationDiagnostic(annotationCount);
+  }
+  return {
+    code: "UNSUPPORTED_MODE",
+    level: "error",
+    message: annotationCount > 0 && bindingCount > 0 ? 'Tileflow annotations and interactions require mode="interactive"; image mode cannot render interactive overlays.' : annotationCount > 0 ? 'Tileflow annotations require mode="interactive"; image mode cannot render interactive overlays.' : bindingCount > 0 ? 'Tileflow interactions require mode="interactive"; image mode cannot render interactive overlays.' : 'Tileflow interaction state, callbacks, and renderers require mode="interactive"; image mode cannot render interactive overlays.',
+    path: ""
+  };
+}
+
+// src/interaction-bindings.ts
+import {
+  validateTileflowInteractionBindings
+} from "@tileflow/interactions";
+function prepareTileflowReactInteractionBindings(interactions) {
+  const validation = validateTileflowInteractionBindings(interactions ?? []);
+  return validation.ok ? {
+    bindings: validation.bindings,
+    diagnostics: [],
+    ok: true
+  } : {
+    diagnostics: validation.diagnostics,
+    ok: false
+  };
+}
+
+// src/interaction-state-input.ts
+import {
+  initialTileflowInteractionState,
+  tileflowInteractionStateSchema
+} from "@tileflow/interactions";
+function prepareTileflowReactInteractionState(interactionState, defaultInteractionState, controlledOwnership = interactionState !== void 0) {
+  const controlled = interactionState !== void 0;
+  if (controlled && defaultInteractionState !== void 0) {
+    return {
+      controlled,
+      diagnostics: [
+        {
+          code: "INVALID_DOCUMENT",
+          level: "error",
+          message: "Tileflow Map accepts interactionState or defaultInteractionState, not both.",
+          path: ""
+        }
+      ],
+      ok: false,
+      state: initialTileflowInteractionState
+    };
+  }
+  if (controlled !== controlledOwnership) {
+    return {
+      controlled,
+      diagnostics: [
+        {
+          code: "INVALID_DOCUMENT",
+          level: "error",
+          message: "Tileflow interaction state ownership cannot switch between controlled and uncontrolled.",
+          path: ""
+        }
+      ],
+      ok: false,
+      state: initialTileflowInteractionState
+    };
+  }
+  const statePath = controlled ? "/interactionState" : "/defaultInteractionState";
+  const parsed = tileflowInteractionStateSchema.safeParse(
+    interactionState ?? defaultInteractionState ?? initialTileflowInteractionState
+  );
+  if (parsed.success) {
+    return { controlled, diagnostics: [], ok: true, state: parsed.data };
+  }
+  return {
+    controlled,
+    diagnostics: parsed.error.issues.map((issue) => ({
+      code: "INVALID_DOCUMENT",
+      level: "error",
+      message: issue.message,
+      path: `${statePath}${issue.path.map((segment) => String(segment).replaceAll("~", "~0").replaceAll("/", "~1")).map((segment) => `/${segment}`).join("")}`
+    })),
+    ok: false,
+    state: initialTileflowInteractionState
+  };
+}
+
+// src/map-style-inputs.ts
+import {
+  validateTileflowBrowserThemeBlendSelection
+} from "@tileflow/core/browser";
+import {
+  isTileflowTimeOfDay,
+  validateTileflowRuntimeSource,
+  validateTileflowThemeSelection
+} from "@tileflow/core/runtime";
+function validateTileflowMapStyleInputs(input) {
+  const sourceValidation = validateTileflowRuntimeSource(input.source);
+  if (!sourceValidation.ok) return sourceValidation;
+  if (input.theme !== void 0 && !validateTileflowThemeSelection(input.theme)) {
+    return { error: 'theme must be a concrete portable theme name or "system"', ok: false };
+  }
+  if (input.timeOfDay !== void 0 && !isTileflowTimeOfDay(input.timeOfDay)) {
+    return { error: "timeOfDay must be day, dawn, dusk, or night", ok: false };
+  }
+  if (input.themeBlend !== void 0 && !validateTileflowBrowserThemeBlendSelection(input.themeBlend)) {
+    return {
+      error: "themeBlend must name two to eight concrete themes, a position from 0 to themes.length - 1, and an optional boolean hold",
+      ok: false
+    };
+  }
+  if (input.themeTransition !== void 0 && !isThemeTransition(input.themeTransition)) {
+    return {
+      error: "themeTransition.duration must be a number of milliseconds from 0 to 5000",
+      ok: false
+    };
+  }
+  return { ok: true };
+}
+function isThemeTransition(value) {
+  if (!value || typeof value !== "object") return false;
+  const { duration } = value;
+  return duration === void 0 || typeof duration === "number" && Number.isFinite(duration) && duration >= 0 && duration <= 5e3;
+}
+function assertTileflowMapStyleInputs(input) {
+  const validation = validateTileflowMapStyleInputs(input);
+  if (!validation.ok) {
+    throw new TypeError(`Invalid Tileflow <Map> source: ${validation.error}`);
+  }
+}
+
+// src/maplibre.ts
+var mapLibrePromise;
+var mapLibre;
+var workerUrl;
+function configureTileflowMapLibre(configuration) {
+  const nextWorkerUrl = configuration.workerUrl;
+  if (typeof nextWorkerUrl !== "string" || nextWorkerUrl.trim().length === 0) {
+    throw new TypeError("Tileflow MapLibre workerUrl must be a non-empty string.");
+  }
+  if (workerUrl !== void 0 && workerUrl !== nextWorkerUrl) {
+    throw new Error("Tileflow MapLibre workerUrl is already configured.");
+  }
+  workerUrl = nextWorkerUrl;
+  mapLibre?.setWorkerUrl(nextWorkerUrl);
+}
+function loadTileflowMapLibre() {
+  mapLibrePromise ??= import("maplibre-gl").then(resolveMapLibreModule).then(configureTileflowMapLibreModule).catch((error) => {
+    mapLibrePromise = void 0;
+    throw error;
+  });
+  return mapLibrePromise;
+}
+function resolveMapLibreModule(module) {
+  const defaultExport = module.default;
+  return defaultExport ?? module;
+}
+function configureTileflowMapLibreModule(maplibregl) {
+  if (workerUrl !== void 0) maplibregl.setWorkerUrl(workerUrl);
+  mapLibre = maplibregl;
+  return maplibregl;
+}
+
+// src/map.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var defaultInteractions = [];
+function Map2(props) {
+  assertTileflowMapStyleInputs(props);
+  const {
+    annotations,
+    captureId,
+    defaultInteractionState,
+    mode = "interactive",
+    source,
+    imageUrl,
+    alt = "",
+    center,
+    zoom,
+    className,
+    height = 420,
+    imageLoading = "eager",
+    interactive,
+    mapOptions,
+    analytics,
+    theme,
+    timeOfDay,
+    themeBlend,
+    themeTransition,
+    vegetation,
+    viewMode = "2d",
+    interactionState,
+    interactions = defaultInteractions,
+    onInteractionDiagnostic,
+    onInteractionEvent,
+    onInteractionStateChange,
+    onLoad,
+    renderMarker,
+    renderPopup,
+    renderTooltip
+  } = props;
+  const generalRenderPopup = renderPopup;
+  const generalRenderTooltip = renderTooltip;
+  const sourceMap = source.map;
+  const sourceManifestUrl = source.manifestUrl;
+  const runtimeSource = useMemo(
+    () => ({ manifestUrl: sourceManifestUrl, map: sourceMap }),
+    [sourceManifestUrl, sourceMap]
+  );
+  const mapName = runtimeSource.map;
+  const manifestUrl = runtimeSource.manifestUrl ?? defaultTileflowManifestUrl;
+  const preparedAnnotations = useMemo(
+    () => prepareTileflowReactAnnotations(annotations),
+    [annotations]
+  );
+  const preparedInteractions = useMemo(
+    () => prepareTileflowReactInteractionBindings(interactions),
+    [interactions]
+  );
+  const controlledInteractionOwnershipRef = useRef(interactionState !== void 0);
+  const preparedInteractionState = useMemo(
+    () => prepareTileflowReactInteractionState(
+      interactionState,
+      defaultInteractionState,
+      controlledInteractionOwnershipRef.current
+    ),
+    [defaultInteractionState, interactionState]
+  );
   const containerRef = useRef(null);
+  const imageRef = useRef(null);
   const mapRef = useRef(null);
-  const sessionId = useMemo(() => createSessionId(), []);
-  const [manifestMap, setManifestMap] = useState(null);
+  const vegetationRef = useRef(void 0);
+  const vegetationInputsRef = useRef({ vegetation, viewMode });
+  vegetationInputsRef.current = { vegetation, viewMode };
+  useEffect(() => {
+    vegetationRef.current?.setVisible(vegetation);
+    vegetationRef.current?.setViewMode(viewMode);
+  }, [vegetation, viewMode]);
+  const themeControllerRef = useRef(void 0);
+  const runtimeStyleRef = useRef(null);
+  const interactionRuntimeRef = useRef(
+    void 0
+  );
+  const semanticRuntimeRef = useRef(void 0);
+  const interactionCoordinatorRef = useRef(
+    void 0
+  );
+  const annotationsRef = useRef(preparedAnnotations.annotations);
+  const annotationTitlesRef = useRef(preparedAnnotations.titles);
+  const preparedInteractionsRef = useRef(preparedInteractions);
+  const coordinatedInteractionStateRef = useRef(preparedInteractionState.state);
+  const onInteractionDiagnosticRef = useRef(onInteractionDiagnostic);
+  const onInteractionEventRef = useRef(onInteractionEvent);
+  const onInteractionStateChangeRef = useRef(onInteractionStateChange);
+  const onThemeChangeRef = useRef(props.onThemeChange);
+  const renderMarkerRef = useRef(renderMarker);
+  const renderPopupRef = useRef(renderPopup);
+  const renderTooltipRef = useRef(renderTooltip);
+  const reportedDeclarativeDiagnosticKeysRef = useRef(/* @__PURE__ */ new Set());
+  const [manifestResolution, setManifestResolution] = useState({
+    key: "",
+    map: null,
+    state: "loading"
+  });
+  const [systemColorScheme, setSystemColorScheme] = useState("light");
   const [imageSize, setImageSize] = useState(null);
-  const isImageMode = mode === "image";
-  const useExplicitStyleBaseUrl = useMemo(
-    () => Boolean(!isImageMode && mapName && !style && !styleUrl && !config && styleBaseUrl),
-    [config, isImageMode, mapName, style, styleBaseUrl, styleUrl]
+  const [captureState, setCaptureState] = useState("loading");
+  const [themeTransitionState, setThemeTransitionState] = useState(
+    "idle"
+  );
+  const [activeRuntimeResource, setActiveRuntimeResource] = useState(void 0);
+  const [annotationRenderTargets, setAnnotationRenderTargets] = useState([]);
+  const [semanticRenderTargets, setSemanticRenderTargets] = useState([]);
+  const [annotationBridgeDiagnostic, setAnnotationBridgeDiagnostic] = useState();
+  const [semanticBridgeDiagnostic, setSemanticBridgeDiagnostic] = useState();
+  const [stateBridgeDiagnostic, setStateBridgeDiagnostic] = useState();
+  const [rendererBridgeDiagnostic, setRendererBridgeDiagnostic] = useState();
+  const [annotationDiagnostics, setAnnotationDiagnostics] = useState([]);
+  const [semanticDiagnostics, setSemanticDiagnostics] = useState([]);
+  const stableMapOptions = useStableMapOptions(mapOptions);
+  const resolvedCaptureId = normalizeTileflowCaptureId(captureId);
+  const resolvedMode = resolveTileflowMapMode({ mode });
+  const isImageMode = resolvedMode === "image";
+  const manifestRequestKey = JSON.stringify([manifestUrl, mapName]);
+  const currentManifestResolution = manifestResolution.key === manifestRequestKey ? manifestResolution : { key: manifestRequestKey, map: null, state: "loading" };
+  const manifestMap = currentManifestResolution.state === "ready" ? currentManifestResolution.map : null;
+  const themeBlendKey = themeBlend ? JSON.stringify(themeBlend.themes) : void 0;
+  const themeBlendPosition = themeBlend?.position;
+  const themeBlendHold = themeBlend?.hold === true;
+  const blendThemeName = themeBlend ? nearestTileflowBlendTheme(themeBlend) : void 0;
+  const themeResolution = useMemo(() => {
+    const selection = blendThemeName ?? theme;
+    if (!manifestMap) {
+      return {
+        error: false,
+        name: selection && selection !== "system" ? selection : void 0
+      };
+    }
+    try {
+      if (themeBlendKey) {
+        for (const name of JSON.parse(themeBlendKey)) {
+          resolveTileflowRuntimeTheme(manifestMap, name);
+        }
+      }
+      return {
+        error: false,
+        name: resolveTileflowRuntimeTheme(
+          manifestMap,
+          selection,
+          systemColorScheme,
+          themeBlendKey ? void 0 : timeOfDay
+        ).name
+      };
+    } catch {
+      return { error: true, name: void 0 };
+    }
+  }, [blendThemeName, manifestMap, systemColorScheme, theme, themeBlendKey, timeOfDay]);
+  const resolvedThemeName = themeResolution.name;
+  const manifestView = resolveTileflowRuntimeView({ manifestMap });
+  const manifestCenter = useStableMapOptionValue(
+    normalizeTileflowRuntimeCenter(manifestView.center)
+  );
+  const resolvedCenter = useStableMapOptionValue(
+    center ?? stableMapOptions?.center ?? manifestCenter
   );
-  const useLocalDevFallback = useMemo(
-    () => Boolean(
-      !isImageMode && mapName && !style && !styleUrl && !config && !styleBaseUrl && preferLocalDev && isLocalDevHost()
+  const resolvedZoom = zoom ?? stableMapOptions?.zoom ?? manifestView.zoom ?? defaultTileflowRuntimeView.zoom;
+  const resolvedBearing = stableMapOptions?.bearing ?? manifestView.bearing;
+  const resolvedPitch = stableMapOptions?.pitch ?? manifestView.pitch;
+  const resolvedInteractive = interactive ?? stableMapOptions?.interactive ?? true;
+  const staticImageCenter = useStableMapOptionValue(
+    normalizeTileflowRuntimeCenter(center ?? stableMapOptions?.center, manifestCenter)
+  );
+  const staticImageZoom = zoom ?? stableMapOptions?.zoom ?? manifestView.zoom ?? defaultTileflowRuntimeView.zoom;
+  const centerRef = useRef(resolvedCenter);
+  const zoomRef = useRef(resolvedZoom);
+  const bearingRef = useRef(resolvedBearing);
+  const pitchRef = useRef(resolvedPitch);
+  const onLoadRef = useRef(onLoad);
+  const mapNameRef = useRef(mapName);
+  const resolvedAnalyticsRef = useRef(void 0);
+  const readinessRunRef = useRef(0);
+  const hasAdditionalInteractionConfiguration = annotations !== void 0 || defaultInteractionState !== void 0 || interactionState !== void 0 || onInteractionDiagnostic !== void 0 || onInteractionEvent !== void 0 || onInteractionStateChange !== void 0 || renderMarker !== void 0 || renderPopup !== void 0 || renderTooltip !== void 0 || props.interactions !== void 0;
+  const modeDiagnostic = useMemo(
+    () => isImageMode ? imageModeMapInteractionDiagnostic(
+      preparedAnnotations.annotations.length,
+      interactions.length,
+      hasAdditionalInteractionConfiguration
+    ) : void 0,
+    [
+      hasAdditionalInteractionConfiguration,
+      interactions.length,
+      isImageMode,
+      preparedAnnotations.annotations.length
+    ]
+  );
+  const declarativeInteractionDiagnostics = useMemo(
+    () => [
+      modeDiagnostic,
+      ...preparedAnnotations.diagnostics,
+      ...preparedInteractions.diagnostics,
+      ...preparedInteractionState.diagnostics
+    ].filter(
+      (diagnostic) => diagnostic !== void 0
     ),
-    [config, isImageMode, mapName, preferLocalDev, style, styleBaseUrl, styleUrl]
+    [
+      modeDiagnostic,
+      preparedAnnotations.diagnostics,
+      preparedInteractions.diagnostics,
+      preparedInteractionState.diagnostics
+    ]
+  );
+  const interactionDiagnostics = [
+    ...declarativeInteractionDiagnostics,
+    ...annotationBridgeDiagnostic ? [annotationBridgeDiagnostic] : [],
+    ...semanticBridgeDiagnostic ? [semanticBridgeDiagnostic] : [],
+    ...stateBridgeDiagnostic ? [stateBridgeDiagnostic] : [],
+    ...rendererBridgeDiagnostic ? [rendererBridgeDiagnostic] : [],
+    ...annotationDiagnostics,
+    ...semanticDiagnostics
+  ];
+  const interactionDiagnostic = interactionDiagnostics.find((diagnostic) => diagnostic.level === "error") ?? interactionDiagnostics[0];
+  const hasInteractionError = interactionDiagnostics.some(
+    (diagnostic) => diagnostic.level === "error"
+  );
+  const portalKeys = useMemo(
+    () => [
+      ...annotationRenderTargets.map((target) => `annotation:${target.key}`),
+      ...semanticRenderTargets.map((target) => `semantic:${target.key}`)
+    ],
+    [annotationRenderTargets, semanticRenderTargets]
   );
+  const portalReadiness = useTileflowPortalReadiness(portalKeys);
+  const interactionReadiness = hasInteractionError ? "error" : portalReadiness.idle ? "idle" : "loading";
+  if (preparedAnnotations.ok) {
+    annotationsRef.current = preparedAnnotations.annotations;
+    annotationTitlesRef.current = preparedAnnotations.titles;
+  }
+  preparedInteractionsRef.current = preparedInteractions;
+  onInteractionDiagnosticRef.current = onInteractionDiagnostic;
+  onInteractionEventRef.current = onInteractionEvent;
+  onInteractionStateChangeRef.current = onInteractionStateChange;
+  renderMarkerRef.current = renderMarker;
+  renderPopupRef.current = renderPopup;
+  renderTooltipRef.current = renderTooltip;
+  onThemeChangeRef.current = props.onThemeChange;
   useEffect(() => {
-    const shouldLoadManifest = Boolean(
-      mapName && !config && (isImageMode && !imageUrl || !isImageMode && !style && !styleUrl && !useExplicitStyleBaseUrl)
-    );
-    if (!shouldLoadManifest) {
-      setManifestMap(null);
-      return;
+    if (theme !== "system") return;
+    setSystemColorScheme(getTileflowSystemColorScheme());
+    return subscribeTileflowSystemColorScheme(setSystemColorScheme);
+  }, [theme]);
+  useEffect(() => {
+    const previousKeys = reportedDeclarativeDiagnosticKeysRef.current;
+    const nextKeys = /* @__PURE__ */ new Set();
+    for (const diagnostic of declarativeInteractionDiagnostics) {
+      const key = tileflowInteractionDiagnosticKey(diagnostic);
+      nextKeys.add(key);
+      if (!previousKeys.has(key)) onInteractionDiagnosticRef.current?.(diagnostic);
     }
+    reportedDeclarativeDiagnosticKeysRef.current = nextKeys;
+  }, [declarativeInteractionDiagnostics]);
+  useEffect(() => {
     let cancelled = false;
-    loadManifest(manifestUrl).then((manifest) => {
+    setManifestResolution({ key: manifestRequestKey, map: null, state: "loading" });
+    loadTileflowManifest(manifestUrl).then((manifest) => {
       if (cancelled) {
         return;
       }
-      setManifestMap(manifest ? resolveManifestMap(manifest, mapName) : null);
+      const resolvedMap = manifest && mapName ? resolveTileflowManifestMap(manifest, mapName) : null;
+      setManifestResolution({
+        key: manifestRequestKey,
+        map: resolvedMap,
+        state: resolvedMap ? "ready" : "error"
+      });
     }).catch((error) => {
       if (!cancelled) {
         console.error("Failed to load Tileflow manifest", error);
-        setManifestMap(null);
+        setManifestResolution({ key: manifestRequestKey, map: null, state: "error" });
       }
     });
     return () => {
       cancelled = true;
     };
-  }, [
-    config,
-    imageUrl,
-    isImageMode,
-    manifestUrl,
-    mapName,
-    style,
-    styleUrl,
-    useExplicitStyleBaseUrl
-  ]);
+  }, [manifestRequestKey, manifestUrl, mapName]);
   const runtimeStyle = useMemo(() => {
-    if (isImageMode) {
+    if (isImageMode || themeResolution.error) {
       return null;
     }
-    if (style) {
-      return { style };
-    }
-    if (styleUrl) {
-      return {
-        analytics: inferAnalyticsFromStyleUrl(styleUrl),
-        style: styleUrl
-      };
-    }
-    if (mapName && useExplicitStyleBaseUrl) {
-      return { style: resolveStyleUrl(mapName, styleBaseUrl) };
-    }
-    if (mapName) {
-      if (manifestMap?.styleUrl) {
-        return {
-          analytics: {
-            apiUrl: manifestMap.apiUrl,
-            mapId: manifestMap.mapId,
-            styleId: manifestMap.styleId
-          },
-          style: manifestMap.styleUrl
-        };
-      }
-      if (useLocalDevFallback) {
-        return { style: resolveStyleUrl(mapName) };
-      }
+    return resolveTileflowRuntimeStyle({
+      colorScheme: systemColorScheme,
+      manifestMap,
+      source: runtimeSource,
+      theme: themeResolution.name
+    });
+  }, [isImageMode, manifestMap, runtimeSource, systemColorScheme, themeResolution]);
+  runtimeStyleRef.current = runtimeStyle;
+  const blendStyles = useMemo(() => {
+    if (isImageMode || !manifestMap || !themeBlendKey) return null;
+    try {
+      return resolveTileflowRuntimeThemeBlend({
+        blend: { position: 0, themes: JSON.parse(themeBlendKey) },
+        manifestMap,
+        source: runtimeSource
+      });
+    } catch {
       return null;
     }
-    return { style: createStyle(config, { themes, tileBaseUrl }) };
-  }, [
-    config,
-    isImageMode,
-    manifestMap,
-    mapName,
-    style,
-    styleBaseUrl,
-    styleUrl,
-    themes,
-    tileBaseUrl,
-    useExplicitStyleBaseUrl,
-    useLocalDevFallback
-  ]);
+  }, [isImageMode, manifestMap, runtimeSource, themeBlendKey]);
+  const blendRequestRef = useRef(null);
+  blendRequestRef.current = blendStyles && themeBlendPosition !== void 0 ? { hold: themeBlendHold, position: themeBlendPosition, themes: blendStyles } : null;
+  const themeTransitionRef = useRef(themeTransition);
+  themeTransitionRef.current = themeTransition;
+  const runtimeMapIdentity = `${manifestUrl}\0${runtimeSource.map}`;
+  const runtimeStyleReady = runtimeStyle !== null || themeResolution.error && mapRef.current !== null;
   const resolvedAnalytics = useMemo(
-    () => mergeAnalytics(analytics, runtimeStyle?.analytics),
+    () => mergeTileflowAnalytics(analytics, runtimeStyle?.analytics),
     [analytics, runtimeStyle]
   );
+  useEffect(() => {
+    centerRef.current = resolvedCenter;
+    zoomRef.current = resolvedZoom;
+    bearingRef.current = resolvedBearing;
+    pitchRef.current = resolvedPitch;
+    mapRef.current?.jumpTo({
+      bearing: resolvedBearing,
+      center: resolvedCenter,
+      pitch: resolvedPitch,
+      zoom: resolvedZoom
+    });
+  }, [resolvedBearing, resolvedCenter, resolvedPitch, resolvedZoom]);
+  useEffect(() => {
+    onLoadRef.current = onLoad;
+  }, [onLoad]);
+  useEffect(() => {
+    mapNameRef.current = mapName;
+  }, [mapName]);
+  useEffect(() => {
+    resolvedAnalyticsRef.current = resolvedAnalytics;
+  }, [resolvedAnalytics]);
   const runtimeImageUrl = useMemo(
-    () => imageUrl ?? (isImageMode ? resolveStaticImageUrl({
-      center,
+    () => imageUrl ?? (isImageMode && !themeResolution.error ? resolveTileflowStaticImageUrl({
+      center: staticImageCenter,
+      colorScheme: systemColorScheme,
       imageSize,
       manifestMap,
-      zoom
+      theme: themeResolution.name,
+      zoom: staticImageZoom
     }) : void 0),
-    [center, imageSize, imageUrl, isImageMode, manifestMap, zoom]
-  );
-  const transformRequest = useMemo(
-    () => createTransformRequest(resolvedAnalytics, sessionId),
-    [resolvedAnalytics, sessionId]
+    [
+      imageSize,
+      imageUrl,
+      isImageMode,
+      manifestMap,
+      staticImageCenter,
+      staticImageZoom,
+      systemColorScheme,
+      themeResolution
+    ]
   );
+  const runtimeResolutionState = (() => {
+    if (currentManifestResolution.state !== "ready") {
+      return currentManifestResolution.state === "error" ? "error" : "loading";
+    }
+    if (themeResolution.error) return "error";
+    if (isImageMode) {
+      if (runtimeImageUrl) return "idle";
+      return imageUrl === void 0 && imageSize === null ? "loading" : "error";
+    }
+    return runtimeStyle ? "idle" : "error";
+  })();
+  const currentCaptureState = activeRuntimeResource === (isImageMode ? runtimeImageUrl : runtimeStyle) ? captureState : "loading";
+  const effectiveCaptureState = currentCaptureState === "error" || interactionReadiness === "error" || runtimeResolutionState === "error" || themeTransitionState === "error" ? "error" : currentCaptureState === "idle" && interactionReadiness === "idle" && runtimeResolutionState === "idle" && themeTransitionState === "idle" ? "idle" : "loading";
   useEffect(() => {
     if (!isImageMode || imageUrl || !containerRef.current) {
       setImageSize(null);
@@ -158,7 +617,7 @@ function Map({
     }
     const element = containerRef.current;
     const updateImageSize = () => {
-      const nextSize = normalizeStaticImageSize({
+      const nextSize = normalizeTileflowStaticImageSize({
         height: element.clientHeight,
         width: element.clientWidth
       });
@@ -174,60 +633,463 @@ function Map({
     };
   }, [imageUrl, isImageMode]);
   useEffect(() => {
-    if (!containerRef.current || !runtimeStyle) {
-      return;
+    const runtime = interactionRuntimeRef.current;
+    if (!runtime || !preparedAnnotations.ok) return;
+    try {
+      setAnnotationBridgeDiagnostic(void 0);
+      runtime.reconcile(preparedAnnotations.annotations);
+    } catch (error) {
+      console.error("Failed to reconcile Tileflow annotations", error);
+      const diagnostic = createOverlayFailureDiagnostic(
+        "Tileflow annotations could not be reconciled."
+      );
+      setAnnotationBridgeDiagnostic(diagnostic);
+      onInteractionDiagnosticRef.current?.(diagnostic);
     }
-    const map = new maplibregl.Map({
-      container: containerRef.current,
-      style: runtimeStyle.style,
-      center,
-      zoom,
-      interactive,
-      attributionControl: { compact: true },
-      transformRequest
-    });
-    mapRef.current = map;
-    const controls = interactive ? new maplibregl.NavigationControl() : null;
-    if (controls) {
-      map.addControl(controls, "top-right");
+  }, [preparedAnnotations]);
+  useEffect(() => {
+    const runtime = semanticRuntimeRef.current;
+    if (!runtime || !preparedInteractions.ok) return;
+    try {
+      setSemanticBridgeDiagnostic(void 0);
+      runtime.reconcile(preparedInteractions.bindings);
+    } catch (error) {
+      console.error("Failed to reconcile Tileflow semantic interactions", error);
+      const diagnostic = createOverlayFailureDiagnostic(
+        "Tileflow semantic interactions could not be reconciled."
+      );
+      setSemanticBridgeDiagnostic(diagnostic);
+      onInteractionDiagnosticRef.current?.(diagnostic);
     }
-    const markerInstances = markers.map((marker) => {
-      const element = document.createElement("div");
-      element.className = "tileflow-marker";
-      element.style.background = marker.color ?? "#C6A15B";
-      element.title = marker.label ?? marker.id;
-      return new maplibregl.Marker({ element }).setLngLat(marker.coordinates).addTo(map);
-    });
-    const resizeObserver = new ResizeObserver(() => {
-      map.resize();
-    });
-    resizeObserver.observe(containerRef.current);
-    map.on("load", () => {
-      onLoad?.(map);
-      startSession(resolvedAnalytics, {
-        mapId: resolvedAnalytics?.mapId,
-        sessionId,
-        styleId: resolvedAnalytics?.styleId ?? (typeof runtimeStyle.style === "string" ? runtimeStyle.style : mapName)
+  }, [preparedInteractions]);
+  useEffect(() => {
+    if (!preparedInteractionState.controlled || !preparedInteractionState.ok) return;
+    try {
+      setStateBridgeDiagnostic(void 0);
+      interactionCoordinatorRef.current?.setInteractionState(preparedInteractionState.state);
+      coordinatedInteractionStateRef.current = preparedInteractionState.state;
+    } catch (error) {
+      console.error("Failed to update Tileflow interaction state", error);
+      const diagnostic = createOverlayFailureDiagnostic(
+        "Tileflow interaction state could not be updated."
+      );
+      setStateBridgeDiagnostic(diagnostic);
+      onInteractionDiagnosticRef.current?.(diagnostic);
+    }
+  }, [preparedInteractionState]);
+  useEffect(() => {
+    const annotationRuntime = interactionRuntimeRef.current;
+    const semanticRuntime = semanticRuntimeRef.current;
+    if (!annotationRuntime && !semanticRuntime) return;
+    try {
+      setRendererBridgeDiagnostic(void 0);
+      annotationRuntime?.setCustomRenderers({
+        marker: renderMarker !== void 0,
+        popup: renderPopup !== void 0,
+        tooltip: renderTooltip !== void 0
       });
+      semanticRuntime?.setCustomRenderers({
+        popup: renderPopup !== void 0,
+        tooltip: renderTooltip !== void 0
+      });
+    } catch (error) {
+      console.error("Failed to update Tileflow interaction renderers", error);
+      const diagnostic = createOverlayFailureDiagnostic(
+        "Tileflow interaction renderers could not be updated."
+      );
+      setRendererBridgeDiagnostic(diagnostic);
+      onInteractionDiagnosticRef.current?.(diagnostic);
+    }
+  }, [renderMarker, renderPopup, renderTooltip]);
+  useEffect(() => {
+    setThemeTransitionState("idle");
+    const initialRuntimeStyle = runtimeStyleRef.current;
+    if (!containerRef.current || !initialRuntimeStyle) {
+      return;
+    }
+    readinessRunRef.current += 1;
+    setActiveRuntimeResource(initialRuntimeStyle);
+    setCaptureState("loading");
+    const container = containerRef.current;
+    let cancelled = false;
+    let disposeMap;
+    void Promise.all([
+      loadTileflowMapLibre(),
+      loadTileflowStyleFonts(initialRuntimeStyle.style, {
+        fontFaces: initialRuntimeStyle.fontFaces
+      })
+    ]).then(([maplibregl]) => {
+      if (cancelled || containerRef.current !== container) {
+        return;
+      }
+      const setupCleanups = [];
+      let setupDisposed = false;
+      const setupResources = {};
+      const registerCleanup = (cleanup) => setupCleanups.push(cleanup);
+      disposeMap = () => {
+        if (setupDisposed) return;
+        setupDisposed = true;
+        try {
+          runTileflowReactCleanups([...setupCleanups].reverse());
+        } finally {
+          if (mapRef.current === setupResources.map) mapRef.current = null;
+          if (interactionRuntimeRef.current === setupResources.annotationRuntime) {
+            interactionRuntimeRef.current = void 0;
+          }
+          if (semanticRuntimeRef.current === setupResources.semanticRuntime) {
+            semanticRuntimeRef.current = void 0;
+          }
+          if (interactionCoordinatorRef.current === setupResources.coordinator) {
+            interactionCoordinatorRef.current = void 0;
+          }
+          setAnnotationDiagnostics([]);
+          setAnnotationRenderTargets([]);
+          setAnnotationBridgeDiagnostic(void 0);
+          setSemanticDiagnostics([]);
+          setSemanticRenderTargets([]);
+          setSemanticBridgeDiagnostic(void 0);
+          setStateBridgeDiagnostic(void 0);
+          setRendererBridgeDiagnostic(void 0);
+        }
+      };
+      const session = createTileflowSessionController({ source: "react" });
+      const sessionStarter = createTileflowSessionStarter({
+        getSessionId: () => session.sessionId,
+        sessionId: session.sessionId,
+        source: "react"
+      });
+      const fairUseNotice = attachTileflowFairUseNotice(container);
+      registerCleanup(() => fairUseNotice.dispose());
+      registerTileflowContourProtocol({ addProtocol: maplibregl.addProtocol });
+      registerTileflowPmtilesProtocol({ addProtocol: maplibregl.addProtocol });
+      const worldRequestBridge = registerTileflowWorldRequestBridge({
+        addProtocol: maplibregl.addProtocol,
+        onNotice: fairUseNotice.update
+      });
+      registerCleanup(() => worldRequestBridge.dispose());
+      const transformRequest = createTileflowTransformRequest({
+        getAnalytics: () => resolvedAnalyticsRef.current,
+        sessionController: session,
+        sessionId: session.sessionId,
+        transformRequest: stableMapOptions?.transformRequest ?? void 0,
+        worldRequestBridge
+      });
+      const map = new maplibregl.Map({
+        ...stableMapOptions,
+        container,
+        style: initialRuntimeStyle.style,
+        bearing: bearingRef.current,
+        center: centerRef.current,
+        pitch: pitchRef.current,
+        zoom: zoomRef.current,
+        interactive: resolvedInteractive,
+        attributionControl: stableMapOptions?.attributionControl ?? {
+          compact: true
+        },
+        transformRequest
+      });
+      mapRef.current = map;
+      setupResources.map = map;
+      registerCleanup(() => map.remove());
+      registerCleanup(attachTileflowAtmosphere(map));
+      const themeController = initialRuntimeStyle.theme === void 0 ? void 0 : createTileflowThemeController({
+        initial: initialRuntimeStyle,
+        map,
+        onTransition(transition) {
+          onThemeChangeRef.current?.(transition);
+          if (transition.phase === "preloading" || transition.phase === "applying") {
+            setThemeTransitionState("loading");
+          } else if (transition.phase === "error") {
+            setThemeTransitionState("error");
+          } else {
+            setThemeTransitionState("idle");
+          }
+        }
+      });
+      if (themeController) {
+        themeControllerRef.current = themeController;
+        registerCleanup(() => {
+          themeController.dispose();
+          if (themeControllerRef.current === themeController) {
+            themeControllerRef.current = void 0;
+          }
+        });
+      }
+      const vegetationController = createTileflowVegetation({
+        map,
+        ...themeController ? { controller: themeController } : {},
+        visible: vegetationInputsRef.current.vegetation,
+        viewMode: vegetationInputsRef.current.viewMode,
+        // Direct tile readers use HTTP, not MapLibre's custom World protocol.
+        transformRequest: createTileflowTransformRequest({
+          getAnalytics: () => resolvedAnalyticsRef.current,
+          sessionController: session,
+          sessionId: session.sessionId,
+          transformRequest: (url) => stableMapOptions?.transformRequest?.(
+            url,
+            "Tile"
+          )
+        })
+      });
+      vegetationRef.current = vegetationController;
+      registerCleanup(() => {
+        vegetationController.dispose();
+        if (vegetationRef.current === vegetationController) vegetationRef.current = void 0;
+      });
+      const browserWindow = container.ownerDocument.defaultView;
+      if (!browserWindow) {
+        throw new Error("Tileflow semantic interactions require a browser document.");
+      }
+      const interactionCoordinator = createTileflowMapLibreInteractionCoordinator({
+        ...controlledInteractionOwnershipRef.current ? { interactionState: coordinatedInteractionStateRef.current } : { defaultInteractionState: coordinatedInteractionStateRef.current },
+        onInteractionStateChange(state) {
+          if (!controlledInteractionOwnershipRef.current) {
+            coordinatedInteractionStateRef.current = state;
+          }
+          onInteractionStateChangeRef.current?.(state);
+        }
+      });
+      interactionCoordinatorRef.current = interactionCoordinator;
+      setupResources.coordinator = interactionCoordinator;
+      registerCleanup(() => interactionCoordinator.dispose());
+      const interactionRuntime = createTileflowMapLibreDomRuntime({
+        createMarker({ annotation, element }) {
+          const marker = new maplibregl.Marker({ element });
+          element.title = annotationTitlesRef.current.get(annotation.id) ?? annotation.ariaLabel;
+          return wrapMapLibrePositioned(marker);
+        },
+        createOverlay({ container: overlayContainer, kind }) {
+          const popup = new maplibregl.Popup({
+            closeButton: false,
+            closeOnClick: false,
+            closeOnMove: false,
+            focusAfterOpen: false,
+            offset: kind === "popup" ? 24 : 18
+          }).setDOMContent(overlayContainer);
+          return wrapMapLibrePositioned(popup);
+        },
+        customMarker: renderMarkerRef.current !== void 0,
+        customPopup: renderPopupRef.current !== void 0,
+        customTooltip: renderTooltipRef.current !== void 0,
+        document: container.ownerDocument,
+        interactionState: interactionCoordinator.getInteractionState(),
+        map,
+        onInteractionStateChange: interactionCoordinator.requestInteractionState,
+        onDiagnostic(diagnostic) {
+          onInteractionDiagnosticRef.current?.(diagnostic);
+        },
+        updateMarker(_marker, { annotation, element }) {
+          element.title = annotationTitlesRef.current.get(annotation.id) ?? annotation.ariaLabel;
+        }
+      });
+      interactionRuntimeRef.current = interactionRuntime;
+      setupResources.annotationRuntime = interactionRuntime;
+      registerCleanup(() => interactionRuntime.dispose());
+      const semanticRuntime = createTileflowMapLibreSemanticDomRuntime({
+        cancelFrame: (frame) => browserWindow.cancelAnimationFrame(frame),
+        createOverlay({ container: overlayContainer, kind }) {
+          const popup = new maplibregl.Popup({
+            closeButton: false,
+            closeOnClick: false,
+            closeOnMove: false,
+            focusAfterOpen: false,
+            offset: kind === "popup" ? 24 : 18
+          }).setDOMContent(overlayContainer);
+          return wrapMapLibrePositioned(popup);
+        },
+        customPopup: renderPopupRef.current !== void 0,
+        customTooltip: renderTooltipRef.current !== void 0,
+        document: container.ownerDocument,
+        interactionState: interactionCoordinator.getInteractionState(),
+        map,
+        onDiagnostic(diagnostic) {
+          onInteractionDiagnosticRef.current?.(diagnostic);
+        },
+        onInteractionStateChange: interactionCoordinator.requestInteractionState,
+        poiMap: createTileflowMapLibrePoiMap(map),
+        requestFrame: (callback) => browserWindow.requestAnimationFrame(() => callback())
+      });
+      semanticRuntimeRef.current = semanticRuntime;
+      setupResources.semanticRuntime = semanticRuntime;
+      registerCleanup(() => semanticRuntime.dispose());
+      const detachAnnotationRuntime = interactionCoordinator.attach(
+        "annotation",
+        interactionRuntime
+      );
+      registerCleanup(detachAnnotationRuntime);
+      const detachSemanticRuntime = interactionCoordinator.attach("semantic", semanticRuntime);
+      registerCleanup(detachSemanticRuntime);
+      const unsubscribeInteractionEvents = interactionRuntime.subscribeEvents((event) => {
+        onInteractionEventRef.current?.(event);
+      });
+      registerCleanup(unsubscribeInteractionEvents);
+      const unsubscribeDiagnostics = interactionRuntime.subscribeDiagnostics((diagnostics) => {
+        setAnnotationDiagnostics(diagnostics);
+      });
+      registerCleanup(unsubscribeDiagnostics);
+      const unsubscribeRenderTargets = interactionRuntime.subscribeRenderTargets((targets) => {
+        setAnnotationRenderTargets(targets);
+      });
+      registerCleanup(unsubscribeRenderTargets);
+      const unsubscribeSemanticEvents = semanticRuntime.subscribeEvents((event) => {
+        if (event.target.kind === "annotation") return;
+        onInteractionEventRef.current?.({ ...event, target: event.target });
+      });
+      registerCleanup(unsubscribeSemanticEvents);
+      const unsubscribeSemanticDiagnostics = semanticRuntime.subscribeDiagnostics(
+        (diagnostics) => {
+          setSemanticDiagnostics(diagnostics);
+        }
+      );
+      registerCleanup(unsubscribeSemanticDiagnostics);
+      const unsubscribeSemanticRenderTargets = semanticRuntime.subscribeRenderTargets(
+        (targets) => {
+          setSemanticRenderTargets(targets);
+        }
+      );
+      registerCleanup(unsubscribeSemanticRenderTargets);
+      setAnnotationDiagnostics(interactionRuntime.getDiagnostics());
+      setAnnotationRenderTargets(interactionRuntime.getRenderTargets());
+      setSemanticDiagnostics(semanticRuntime.getDiagnostics());
+      setSemanticRenderTargets(semanticRuntime.getRenderTargets());
+      try {
+        setAnnotationBridgeDiagnostic(void 0);
+        interactionRuntime.reconcile(annotationsRef.current);
+      } catch (error) {
+        console.error("Failed to reconcile Tileflow annotations", error);
+        const diagnostic = createOverlayFailureDiagnostic(
+          "Tileflow annotations could not be reconciled."
+        );
+        setAnnotationBridgeDiagnostic(diagnostic);
+        onInteractionDiagnosticRef.current?.(diagnostic);
+      }
+      const initialInteractions = preparedInteractionsRef.current;
+      if (initialInteractions.ok) {
+        try {
+          setSemanticBridgeDiagnostic(void 0);
+          semanticRuntime.reconcile(initialInteractions.bindings);
+        } catch (error) {
+          console.error("Failed to reconcile Tileflow semantic interactions", error);
+          const diagnostic = createOverlayFailureDiagnostic(
+            "Tileflow semantic interactions could not be reconciled."
+          );
+          setSemanticBridgeDiagnostic(diagnostic);
+          onInteractionDiagnosticRef.current?.(diagnostic);
+        }
+      }
+      const controls = resolvedInteractive ? new maplibregl.NavigationControl() : null;
+      if (controls) {
+        map.addControl(controls, "top-right");
+      }
+      const resizeObserver = new ResizeObserver(() => {
+        map.resize();
+      });
+      registerCleanup(() => resizeObserver.disconnect());
+      resizeObserver.observe(container);
+      const lifecycle = attachTileflowMapLifecycle({
+        getSession: () => {
+          const analyticsForLoad = resolvedAnalyticsRef.current;
+          return {
+            analytics: analyticsForLoad,
+            styleId: analyticsForLoad?.styleId ?? (typeof initialRuntimeStyle.style === "string" ? initialRuntimeStyle.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();
+        }
+      });
+      registerCleanup(() => lifecycle.dispose());
+      const latestRuntimeStyle = runtimeStyleRef.current;
+      const latestBlend = blendRequestRef.current;
+      if (themeController && latestBlend) {
+        if (latestRuntimeStyle) setActiveRuntimeResource(latestRuntimeStyle);
+        void themeController.setBlend(latestBlend, { transition: themeTransitionRef.current });
+      } else if (themeController && latestRuntimeStyle && latestRuntimeStyle !== initialRuntimeStyle) {
+        setActiveRuntimeResource(latestRuntimeStyle);
+        void themeController.setTheme(latestRuntimeStyle, {
+          transition: themeTransitionRef.current
+        });
+      }
+    }).catch((error) => {
+      try {
+        disposeMap?.();
+      } catch (cleanupError) {
+        console.error("Failed to clean up the Tileflow map runtime", cleanupError);
+      }
+      if (!cancelled) {
+        console.error("Failed to load the Tileflow map runtime", error);
+        setCaptureState("error");
+      }
     });
     return () => {
-      resizeObserver.disconnect();
-      markerInstances.forEach((marker) => marker.remove());
-      map.remove();
-      mapRef.current = null;
+      cancelled = true;
+      readinessRunRef.current += 1;
+      disposeMap?.();
     };
-  }, [
-    center,
-    interactive,
-    mapName,
-    markers,
-    onLoad,
-    resolvedAnalytics,
-    runtimeStyle,
-    sessionId,
-    transformRequest,
-    zoom
-  ]);
+  }, [resolvedInteractive, runtimeMapIdentity, runtimeStyleReady, stableMapOptions]);
+  useEffect(() => {
+    const controller = themeControllerRef.current;
+    if (!controller || themeBlendKey) return;
+    if (themeResolution.error) {
+      void controller.setTheme(controller.getCurrent());
+      return;
+    }
+    if (!runtimeStyle || controller.getCurrent() === runtimeStyle && !controller.getBlend())
+      return;
+    setActiveRuntimeResource(runtimeStyle);
+    void controller.setTheme(runtimeStyle, { transition: themeTransitionRef.current }).then((result) => {
+      if (result.status === "failed") {
+        console.error("Failed to change the Tileflow map theme", result.error);
+      }
+    });
+  }, [runtimeStyle, themeBlendKey, themeResolution.error]);
+  useEffect(() => {
+    const controller = themeControllerRef.current;
+    if (!controller || !blendStyles || themeBlendPosition === void 0) return;
+    if (runtimeStyle) setActiveRuntimeResource(runtimeStyle);
+    void controller.setBlend(
+      { hold: themeBlendHold, position: themeBlendPosition, themes: blendStyles },
+      { transition: themeTransitionRef.current }
+    ).then((result) => {
+      if (result.status === "failed") {
+        console.error("Failed to blend the Tileflow map themes", result.error);
+      }
+    });
+  }, [blendStyles, runtimeStyle, themeBlendHold, themeBlendPosition]);
+  useLayoutEffect(() => {
+    if (!isImageMode) return;
+    readinessRunRef.current += 1;
+    setActiveRuntimeResource(runtimeImageUrl);
+    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");
+  }
   const frameStyle = {
     height,
     minHeight: 240,
@@ -235,228 +1097,320 @@ function Map({
     position: "relative",
     width: "100%"
   };
+  const diagnosticView = interactionDiagnostic ? /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-tileflow-interaction-diagnostic": interactionDiagnostic.code,
+      role: "alert",
+      style: interactionDiagnosticStyle,
+      children: interactionDiagnostic.message
+    }
+  ) : null;
   if (isImageMode) {
-    return /* @__PURE__ */ jsx("div", { className, ref: containerRef, style: frameStyle, children: runtimeImageUrl ? /* @__PURE__ */ jsx(
-      "img",
+    return /* @__PURE__ */ jsxs(
+      "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-theme": resolvedThemeName,
+        "data-tileflow-state": effectiveCaptureState,
+        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,
+          diagnosticView
+        ]
       }
-    ) : null });
+    );
   }
-  return /* @__PURE__ */ jsx("div", { className, ref: containerRef, style: frameStyle });
-}
-function resolveStyleUrl(mapName, styleBaseUrl) {
-  const baseUrl = normalizeUrl(styleBaseUrl ?? getDefaultStyleBaseUrl());
-  return `${baseUrl}/styles/${mapName}.json`;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        className,
+        "data-tileflow-capture-id": resolvedCaptureId,
+        "data-tileflow-map": mapName,
+        "data-tileflow-theme": resolvedThemeName,
+        "data-tileflow-state": effectiveCaptureState,
+        style: frameStyle,
+        children: [
+          /* @__PURE__ */ jsx("div", { ref: containerRef, style: mapContainerStyle }),
+          diagnosticView
+        ]
+      }
+    ),
+    annotationRenderTargets.map((target) => {
+      const portalKey = `annotation:${target.key}`;
+      return createPortal(
+        /* @__PURE__ */ jsx(
+          TileflowAnnotationPortal,
+          {
+            onCommit: portalReadiness.markCommitted,
+            portalKey,
+            readinessToken: portalReadiness.token,
+            renderMarker,
+            renderPopup: generalRenderPopup,
+            renderTarget: target,
+            renderTooltip: generalRenderTooltip
+          }
+        ),
+        target.container,
+        portalKey
+      );
+    }),
+    semanticRenderTargets.map((target) => {
+      const portalKey = `semantic:${target.key}`;
+      return createPortal(
+        /* @__PURE__ */ jsx(
+          TileflowSemanticPortal,
+          {
+            onCommit: portalReadiness.markCommitted,
+            portalKey,
+            readinessToken: portalReadiness.token,
+            renderPopup: generalRenderPopup,
+            renderTarget: target,
+            renderTooltip: generalRenderTooltip
+          }
+        ),
+        target.container,
+        portalKey
+      );
+    })
+  ] });
 }
-function getDefaultStyleBaseUrl() {
-  const globalValue = globalThis.__TILEFLOW_STYLE_BASE_URL__;
-  return globalValue ?? "http://localhost:3333";
+var mapContainerStyle = {
+  inset: 0,
+  position: "absolute"
+};
+var interactionDiagnosticStyle = {
+  background: "#7f1d1d",
+  border: "1px solid #fecaca",
+  borderRadius: 4,
+  color: "#ffffff",
+  fontFamily: "system-ui, sans-serif",
+  fontSize: 13,
+  left: 12,
+  maxWidth: "calc(100% - 24px)",
+  padding: "8px 10px",
+  position: "absolute",
+  top: 12,
+  zIndex: 10
+};
+function TileflowAnnotationPortal({
+  onCommit,
+  portalKey,
+  readinessToken,
+  renderMarker,
+  renderPopup,
+  renderTarget,
+  renderTooltip
+}) {
+  useLayoutEffect(() => {
+    onCommit(readinessToken, portalKey);
+  }, [onCommit, portalKey, readinessToken]);
+  const { annotation } = renderTarget;
+  const content = renderTarget.kind === "marker" ? annotation.marker?.content : renderTarget.kind === "tooltip" ? annotation.tooltip?.content : annotation.popup?.content;
+  const context = {
+    annotation,
+    close: renderTarget.close,
+    ...content ? { content } : {},
+    target: {
+      annotation,
+      coordinate: annotation.coordinate,
+      kind: "annotation"
+    },
+    ...content?.kind === "view" ? { viewName: content.name } : {}
+  };
+  if (renderTarget.kind === "marker") return renderMarker?.(context) ?? null;
+  const renderer = renderTarget.kind === "tooltip" ? renderTooltip : renderPopup;
+  return renderer?.(context) ?? null;
 }
-function normalizeUrl(value) {
-  return value.replace(/\/+$/, "");
+function TileflowSemanticPortal({
+  onCommit,
+  portalKey,
+  readinessToken,
+  renderPopup,
+  renderTarget,
+  renderTooltip
+}) {
+  useLayoutEffect(() => {
+    onCommit(readinessToken, portalKey);
+  }, [onCommit, portalKey, readinessToken]);
+  const context = {
+    close: renderTarget.close,
+    content: renderTarget.content,
+    target: renderTarget.target,
+    ...renderTarget.viewName ? { viewName: renderTarget.viewName } : {}
+  };
+  const renderer = renderTarget.kind === "tooltip" ? renderTooltip : renderPopup;
+  return renderer?.(context) ?? null;
 }
-function createSessionId() {
-  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
-    return `ses_${crypto.randomUUID()}`;
+function useTileflowPortalReadiness(portalKeys) {
+  const signature = JSON.stringify([...portalKeys].sort());
+  const versionRef = useRef({ signature, version: 0 });
+  if (versionRef.current.signature !== signature) {
+    versionRef.current = { signature, version: versionRef.current.version + 1 };
   }
-  return `ses_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
-}
-function createTransformRequest(analytics, sessionId) {
-  if (!analytics || analytics.enabled === false) {
-    return void 0;
+  const token = `${versionRef.current.version}:${signature}`;
+  const expectedKeysRef = useRef({ keys: [...portalKeys].sort(), token });
+  if (expectedKeysRef.current.token !== token) {
+    expectedKeysRef.current = { keys: [...portalKeys].sort(), token };
   }
-  return (url) => {
-    const apiUrl = getAnalyticsApiUrl(analytics);
-    if (!apiUrl || !isTileflowTileUrl(url, apiUrl)) {
-      return void 0;
-    }
-    const nextUrl = new URL(url);
-    nextUrl.searchParams.set("session", sessionId);
-    if (analytics.mapId) {
-      nextUrl.searchParams.set("map", analytics.mapId);
+  const expectedKeys = expectedKeysRef.current.keys;
+  const [committed, setCommitted] = useState(() => ({
+    keys: /* @__PURE__ */ new Set(),
+    token
+  }));
+  const [readyToken, setReadyToken] = useState(token);
+  const readinessRunRef = useRef(0);
+  const markCommitted = useCallback((committedToken, portalKey) => {
+    setCommitted((current) => {
+      if (current.token !== committedToken) {
+        return { keys: /* @__PURE__ */ new Set([portalKey]), token: committedToken };
+      }
+      if (current.keys.has(portalKey)) return current;
+      return { keys: /* @__PURE__ */ new Set([...current.keys, portalKey]), token: committedToken };
+    });
+  }, []);
+  useLayoutEffect(() => {
+    setCommitted((current) => current.token === token ? current : { keys: /* @__PURE__ */ new Set(), token });
+  }, [token]);
+  useLayoutEffect(() => {
+    if (readyToken === token || committed.token !== token || !expectedKeys.every((key) => committed.keys.has(key))) {
+      return;
     }
-    if (analytics.styleId) {
-      nextUrl.searchParams.set("styleId", analytics.styleId);
+    const browserWindow = globalThis.window;
+    const run = ++readinessRunRef.current;
+    let secondFrame;
+    const firstFrame = browserWindow.requestAnimationFrame(() => {
+      secondFrame = browserWindow.requestAnimationFrame(() => {
+        if (readinessRunRef.current === run) setReadyToken(token);
+      });
+    });
+    return () => {
+      readinessRunRef.current += 1;
+      browserWindow.cancelAnimationFrame(firstFrame);
+      if (secondFrame !== void 0) browserWindow.cancelAnimationFrame(secondFrame);
+    };
+  }, [committed, expectedKeys, readyToken, token]);
+  return { idle: readyToken === token, markCommitted, token };
+}
+function wrapMapLibrePositioned(positioned) {
+  return {
+    addTo(map) {
+      positioned.addTo(map);
+    },
+    remove() {
+      positioned.remove();
+    },
+    setLngLat(coordinate) {
+      positioned.setLngLat([coordinate[0], coordinate[1]]);
     }
-    return { url: nextUrl.toString() };
   };
 }
-function startSession(analytics, input) {
-  if (!analytics || analytics.enabled === false || !input.mapId || typeof navigator === "undefined") {
-    return;
-  }
-  const endpoint = analytics.endpoint ?? `${getAnalyticsApiUrl(analytics)}/v1/sessions/start`;
-  const payload = JSON.stringify({
-    mapId: input.mapId,
-    metadata: analytics.metadata,
-    referrer: typeof document === "undefined" ? void 0 : document.referrer || "",
-    sdkVersion: analytics.sdkVersion,
-    sessionId: input.sessionId,
-    source: analytics.source ?? "react",
-    styleId: input.styleId,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString()
-  });
-  const blob = new Blob([payload], { type: "application/json" });
-  if (navigator.sendBeacon?.(endpoint, blob)) {
-    return;
-  }
-  void fetch(endpoint, {
-    body: payload,
-    credentials: "omit",
-    headers: {
-      "Content-Type": "application/json"
+function createTileflowMapLibrePoiMap(map) {
+  const poiMap = map;
+  return {
+    getStyle: () => map.getStyle(),
+    on(event, listener) {
+      return poiMap.on(event, listener);
     },
-    keepalive: true,
-    method: "POST"
-  });
-}
-function getAnalyticsApiUrl(analytics) {
-  if (analytics.apiUrl) {
-    return normalizeUrl(analytics.apiUrl);
-  }
-  if (analytics.endpoint) {
-    const url = new URL(analytics.endpoint);
-    return url.origin;
-  }
-  return "https://api.tileflow.dev";
+    queryRenderedFeatures(point, options) {
+      return map.queryRenderedFeatures(point, {
+        layers: [...options.layers]
+      });
+    }
+  };
 }
-function mergeAnalytics(userAnalytics, runtimeAnalytics) {
-  if (userAnalytics?.enabled === false) {
-    return userAnalytics;
-  }
-  if (!userAnalytics && !runtimeAnalytics?.mapId) {
-    return void 0;
-  }
+function createOverlayFailureDiagnostic(message) {
   return {
-    ...runtimeAnalytics,
-    ...userAnalytics,
-    apiUrl: userAnalytics?.apiUrl ?? runtimeAnalytics?.apiUrl,
-    mapId: userAnalytics?.mapId ?? runtimeAnalytics?.mapId,
-    styleId: userAnalytics?.styleId ?? runtimeAnalytics?.styleId
+    code: "OVERLAY_FAILURE",
+    level: "error",
+    message,
+    path: ""
   };
 }
-function isTileflowTileUrl(url, apiUrl) {
-  try {
-    const parsedUrl = new URL(url);
-    const parsedApiUrl = new URL(apiUrl);
-    return parsedUrl.origin === parsedApiUrl.origin && isTilePath(parsedUrl);
-  } catch {
-    return false;
-  }
-}
-function isTilePath(url) {
-  return url.pathname.startsWith("/tiles/") || url.pathname.startsWith("/v1/tiles/");
+function tileflowInteractionDiagnosticKey(diagnostic) {
+  return [
+    diagnostic.code,
+    diagnostic.level,
+    diagnostic.path ?? "",
+    diagnostic.target ? JSON.stringify(diagnostic.target) : "",
+    diagnostic.message
+  ].join("\0");
 }
-function isLocalDevHost() {
-  if (typeof window === "undefined") {
-    return false;
+function runTileflowReactCleanups(cleanups) {
+  const errors = [];
+  for (const cleanup of cleanups) {
+    try {
+      cleanup();
+    } catch (error) {
+      errors.push(error);
+    }
   }
-  return ["localhost", "127.0.0.1", "::1"].includes(window.location.hostname);
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, "Tileflow React cleanup failed.");
 }
-function loadManifest(url) {
-  if (!manifestCache.has(url)) {
-    manifestCache.set(
-      url,
-      fetch(url, { cache: "no-store" }).then(async (response) => {
-        if (response.status === 404) {
-          return null;
-        }
-        if (!response.ok) {
-          throw new Error(`Tileflow manifest failed: ${response.status}`);
-        }
-        return await response.json();
-      })
-    );
-  }
-  return manifestCache.get(url);
+function useStableMapOptions(options) {
+  return useStableMapOptionValue(options);
 }
-function resolveManifestMap(manifest, mapName) {
-  const entry = manifest.maps?.[mapName] ?? manifest.styles?.[mapName];
-  if (!entry) {
-    return null;
-  }
-  if (typeof entry === "string") {
-    const analytics2 = inferAnalyticsFromStyleUrl(entry);
-    return {
-      apiUrl: analytics2?.apiUrl ?? manifest.apiUrl,
-      mapId: analytics2?.mapId,
-      styleId: analytics2?.styleId,
-      styleUrl: entry
-    };
+function useStableMapOptionValue(value) {
+  const valueRef = useRef(value);
+  if (!areEquivalentMapOptionValues(valueRef.current, value)) {
+    valueRef.current = value;
   }
-  const styleUrl = entry.styleUrl ?? entry.url;
-  if (!styleUrl && !entry.mapId) {
-    return null;
-  }
-  const analytics = styleUrl ? inferAnalyticsFromStyleUrl(styleUrl) : void 0;
-  return {
-    apiUrl: entry.apiUrl ?? manifest.apiUrl ?? analytics?.apiUrl,
-    mapId: entry.mapId ?? analytics?.mapId,
-    styleId: entry.styleId ?? analytics?.styleId,
-    styleUrl
-  };
+  return valueRef.current;
 }
-function resolveStaticImageUrl(input) {
-  if (!input.manifestMap?.mapId || !input.imageSize) {
-    return void 0;
+function areEquivalentMapOptionValues(left, right, seen = /* @__PURE__ */ new WeakMap()) {
+  if (Object.is(left, right)) {
+    return true;
   }
-  const apiUrl = normalizeUrl(input.manifestMap.apiUrl ?? "https://api.tileflow.dev");
-  const url = new URL(`/maps/${input.manifestMap.mapId}/static.png`, apiUrl);
-  url.searchParams.set("center", input.center.join(","));
-  url.searchParams.set("zoom", String(input.zoom));
-  url.searchParams.set("width", String(input.imageSize.width));
-  url.searchParams.set("height", String(input.imageSize.height));
-  return url.toString();
-}
-function normalizeStaticImageSize(input) {
-  let width = clampDimension(input.width);
-  let height = clampDimension(input.height);
-  const pixelCount = width * height;
-  if (pixelCount > maxStaticImagePixels) {
-    const scale = Math.sqrt(maxStaticImagePixels / pixelCount);
-    width = clampDimension(width * scale);
-    height = clampDimension(height * scale);
+  if (!left || !right || typeof left !== "object" || typeof right !== "object") {
+    return false;
   }
-  return { height, width };
-}
-function clampDimension(value) {
-  if (!Number.isFinite(value) || value <= 0) {
-    return 640;
+  const seenRight = seen.get(left);
+  if (seenRight) {
+    return seenRight === right;
   }
-  return Math.max(64, Math.min(maxStaticImageDimension, Math.round(value)));
-}
-function inferAnalyticsFromStyleUrl(styleUrl) {
-  try {
-    const url = new URL(styleUrl, getLocationOrigin());
-    const match = url.pathname.match(/\/(?:v1\/)?maps\/([^/]+)\/style\.json$/);
-    if (!match?.[1]) {
-      return void 0;
-    }
-    return {
-      apiUrl: url.origin,
-      mapId: match[1],
-      styleId: url.toString()
-    };
-  } catch {
-    return void 0;
+  seen.set(left, right);
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => areEquivalentMapOptionValues(value, right[index], seen));
   }
-}
-function getLocationOrigin() {
-  if (typeof window === "undefined") {
-    return "http://localhost";
+  if (!isPlainObject(left) || !isPlainObject(right)) {
+    return false;
   }
-  return window.location.origin;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return leftKeys.length === rightKeys.length && leftKeys.every(
+    (key) => Object.hasOwn(right, key) && areEquivalentMapOptionValues(left[key], right[key], seen)
+  );
+}
+function isPlainObject(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
 }
 export {
-  Map
+  Map2 as Map,
+  configureTileflowMapLibre
 };