@tileflow/react 0.1.0-alpha.19 → 0.1.0-alpha.20

package/dist/index.js

@@ -2,154 +2,501 @@
 
 // src/map.tsx
 import {
+  useCallback,
   useEffect,
   useLayoutEffect,
   useMemo,
   useRef,
   useState
 } from "react";
-import maplibregl from "maplibre-gl";
+import { createPortal } from "react-dom";
+import {
+  attachTileflowFairUseNotice,
+  attachTileflowMapLifecycle,
+  createTileflowSessionStarter,
+  createTileflowThemeController,
+  createTileflowTransformRequest,
+  getTileflowSystemColorScheme,
+  loadTileflowStyleFonts,
+  registerTileflowContourProtocol,
+  registerTileflowWorldRequestBridge,
+  subscribeTileflowSystemColorScheme
+} from "@tileflow/core/browser";
+import { normalizeTileflowCaptureId } from "@tileflow/core/capture";
 import {
   createTileflowSessionController,
   defaultTileflowManifestUrl,
+  defaultTileflowRuntimeView,
   loadTileflowManifest,
   mergeTileflowAnalytics,
-  normalizeTileflowCaptureId,
+  normalizeTileflowRuntimeCenter,
   normalizeTileflowStaticImageSize,
   resolveTileflowManifestMap,
   resolveTileflowMapMode,
   resolveTileflowRuntimeStyle,
+  resolveTileflowRuntimeTheme,
+  resolveTileflowRuntimeView,
   resolveTileflowStaticImageUrl,
   shouldLoadTileflowManifest
-} from "@tileflow/core";
+} from "@tileflow/core/runtime";
 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,
-  style,
-  styleUrl,
-  imageUrl,
-  styleBaseUrl,
-  themes,
-  manifestUrl = defaultTileflowManifestUrl,
-  preferLocalDev = true,
-  alt = "",
-  center,
-  zoom,
-  className,
-  height = 420,
-  imageLoading = "eager",
-  interactive,
-  mapOptions,
-  markers = defaultMarkers,
-  analytics,
-  onLoad
-}) {
+  createTileflowMapLibreDomRuntime,
+  createTileflowMapLibreInteractionCoordinator,
+  createTileflowMapLibreSemanticDomRuntime
+} from "@tileflow/interactions/maplibre";
+
+// src/annotations.ts
+import {
+  validateTileflowAnnotations
+} from "@tileflow/interactions";
+import { normalizeTileflowLegacyMarkers } from "@tileflow/interactions/maplibre";
+function prepareTileflowReactAnnotations(annotations, markers) {
+  if (annotations !== void 0 && markers !== void 0) {
+    return {
+      annotations: [],
+      diagnostics: [
+        {
+          code: "INVALID_DOCUMENT",
+          level: "error",
+          message: "Tileflow Map accepts annotations or legacy markers, not both.",
+          path: ""
+        }
+      ],
+      ok: false,
+      titles: /* @__PURE__ */ new Map()
+    };
+  }
+  const normalized = normalizeTileflowLegacyMarkers(markers ?? []);
+  const candidates = annotations ?? normalized.annotations;
+  const titles = annotations === void 0 ? normalized.titles : new Map(annotations.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 {
+  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.theme !== void 0 && input.source.kind !== "tileflow") {
+    return { error: "theme is only valid with a tileflow source", ok: false };
+  }
+  return { ok: true };
+}
+function assertTileflowMapStyleInputs(input) {
+  const validation = validateTileflowMapStyleInputs(input);
+  if (!validation.ok) {
+    throw new TypeError(`Invalid Tileflow <Map> source: ${validation.error}`);
+  }
+}
+
+// src/maplibre.ts
+var mapLibrePromise;
+function loadTileflowMapLibre() {
+  mapLibrePromise ??= import("maplibre-gl").then(resolveMapLibreModule).catch((error) => {
+    mapLibrePromise = void 0;
+    throw error;
+  });
+  return mapLibrePromise;
+}
+function resolveMapLibreModule(module) {
+  const defaultExport = module.default;
+  return defaultExport ?? module;
+}
+
+// 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,
+    markers,
+    analytics,
+    theme,
+    interactionState,
+    interactions = defaultInteractions,
+    onInteractionDiagnostic,
+    onInteractionEvent,
+    onInteractionStateChange,
+    onLoad,
+    renderMarker,
+    renderPopup,
+    renderTooltip
+  } = props;
+  const generalRenderPopup = renderPopup;
+  const generalRenderTooltip = renderTooltip;
+  const sourceKind = source.kind;
+  const sourceMap = source.kind === "tileflow" ? source.map : void 0;
+  const sourceManifestUrl = source.kind === "tileflow" ? source.manifestUrl : void 0;
+  const sourceStyle = source.kind === "maplibre" ? source.style : void 0;
+  const runtimeSource = useMemo(
+    () => sourceKind === "tileflow" ? { kind: "tileflow", manifestUrl: sourceManifestUrl, map: sourceMap } : { kind: "maplibre", style: sourceStyle },
+    [sourceKind, sourceManifestUrl, sourceMap, sourceStyle]
+  );
+  const mapName = runtimeSource.kind === "tileflow" ? runtimeSource.map : void 0;
+  const manifestUrl = runtimeSource.kind === "tileflow" ? runtimeSource.manifestUrl ?? defaultTileflowManifestUrl : defaultTileflowManifestUrl;
+  const preparedAnnotations = useMemo(
+    () => prepareTileflowReactAnnotations(annotations, markers),
+    [annotations, markers]
+  );
+  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 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 [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 shouldLoadManifest = shouldLoadTileflowManifest({
+    source: runtimeSource
+  });
+  const manifestRequestKey = shouldLoadManifest ? JSON.stringify([manifestUrl, mapName]) : "not-needed";
+  const currentManifestResolution = manifestResolution.key === manifestRequestKey ? manifestResolution : {
+    key: manifestRequestKey,
+    map: null,
+    state: shouldLoadManifest ? "loading" : "not-needed"
+  };
+  const manifestMap = currentManifestResolution.state === "ready" ? currentManifestResolution.map : null;
+  const themeResolution = useMemo(() => {
+    if (!manifestMap || runtimeSource.kind !== "tileflow") {
+      return {
+        error: false,
+        name: runtimeSource.kind === "tileflow" && theme && theme !== "system" ? theme : void 0
+      };
+    }
+    try {
+      return {
+        error: false,
+        name: resolveTileflowRuntimeTheme(manifestMap, theme, systemColorScheme).name
+      };
+    } catch {
+      return { error: true, name: void 0 };
+    }
+  }, [manifestMap, runtimeSource, systemColorScheme, theme]);
+  const resolvedThemeName = themeResolution.name;
+  const manifestView = resolveTileflowRuntimeView({ manifestMap });
+  const manifestCenter = useStableMapOptionValue(
+    normalizeTileflowRuntimeCenter(manifestView.center)
+  );
   const resolvedCenter = useStableMapOptionValue(
-    center ?? stableMapOptions?.center ?? defaultCenter
+    center ?? stableMapOptions?.center ?? manifestCenter
   );
-  const resolvedZoom = zoom ?? stableMapOptions?.zoom ?? 2;
+  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 = center ?? defaultCenter;
+  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 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 hasAdditionalInteractionConfiguration = annotations !== void 0 || defaultInteractionState !== void 0 || interactionState !== void 0 || markers !== 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 [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";
+  const declarativeInteractionDiagnostics = useMemo(
+    () => [
+      modeDiagnostic,
+      ...preparedAnnotations.diagnostics,
+      ...preparedInteractions.diagnostics,
+      ...preparedInteractionState.diagnostics
+    ].filter(
+      (diagnostic) => diagnostic !== void 0
+    ),
+    [
+      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(() => {
+    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(() => {
-    const shouldLoadManifest = shouldLoadTileflowManifest({
-      config,
-      imageMode: isImageMode,
-      imageUrl,
-      map: mapName,
-      style,
-      styleBaseUrl,
-      styleUrl
-    });
     if (!shouldLoadManifest) {
-      setManifestMap(null);
+      setManifestResolution({ key: manifestRequestKey, map: null, state: "not-needed" });
       return;
     }
     let cancelled = false;
-    setManifestMap(null);
+    setManifestResolution({ key: manifestRequestKey, map: null, state: "loading" });
     loadTileflowManifest(manifestUrl).then((manifest) => {
       if (cancelled) {
         return;
       }
-      setManifestMap(manifest && mapName ? resolveTileflowManifestMap(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, styleBaseUrl]);
+  }, [manifestRequestKey, manifestUrl, mapName, shouldLoadManifest]);
   const runtimeStyle = useMemo(() => {
-    if (isImageMode) {
+    if (isImageMode || themeResolution.error) {
       return null;
     }
     return resolveTileflowRuntimeStyle({
-      config,
+      colorScheme: systemColorScheme,
       manifestMap,
-      map: mapName,
-      preferLocalDev,
-      style,
-      styleBaseUrl,
-      styleUrl,
-      themes
+      source: runtimeSource,
+      theme: themeResolution.name
     });
-  }, [
-    config,
-    isImageMode,
-    manifestMap,
-    mapName,
-    preferLocalDev,
-    style,
-    styleBaseUrl,
-    styleUrl,
-    themes
-  ]);
+  }, [isImageMode, manifestMap, runtimeSource, systemColorScheme, themeResolution]);
+  runtimeStyleRef.current = runtimeStyle;
+  const runtimeMapIdentity = runtimeSource.kind === "tileflow" ? `${manifestUrl}\0${runtimeSource.map}` : runtimeSource.style;
+  const runtimeStyleReady = runtimeStyle !== null || themeResolution.error && mapRef.current !== null;
   const resolvedAnalytics = useMemo(
     () => mergeTileflowAnalytics(analytics, runtimeStyle?.analytics),
     [analytics, runtimeStyle]
@@ -157,11 +504,15 @@ function Map({
   useEffect(() => {
     centerRef.current = resolvedCenter;
     zoomRef.current = resolvedZoom;
+    bearingRef.current = resolvedBearing;
+    pitchRef.current = resolvedPitch;
     mapRef.current?.jumpTo({
+      bearing: resolvedBearing,
       center: resolvedCenter,
+      pitch: resolvedPitch,
       zoom: resolvedZoom
     });
-  }, [resolvedCenter, resolvedZoom]);
+  }, [resolvedBearing, resolvedCenter, resolvedPitch, resolvedZoom]);
   useEffect(() => {
     onLoadRef.current = onLoad;
   }, [onLoad]);
@@ -172,14 +523,38 @@ function Map({
     resolvedAnalyticsRef.current = resolvedAnalytics;
   }, [resolvedAnalytics]);
   const runtimeImageUrl = useMemo(
-    () => imageUrl ?? (isImageMode ? resolveTileflowStaticImageUrl({
+    () => imageUrl ?? (isImageMode && !themeResolution.error ? resolveTileflowStaticImageUrl({
       center: staticImageCenter,
+      colorScheme: systemColorScheme,
       imageSize,
       manifestMap,
-      zoom: resolvedZoom
+      theme: themeResolution.name,
+      zoom: staticImageZoom
     }) : void 0),
-    [imageSize, imageUrl, isImageMode, manifestMap, resolvedZoom, staticImageCenter]
+    [
+      imageSize,
+      imageUrl,
+      isImageMode,
+      manifestMap,
+      staticImageCenter,
+      staticImageZoom,
+      systemColorScheme,
+      themeResolution
+    ]
   );
+  const runtimeResolutionState = (() => {
+    if (shouldLoadManifest && 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);
@@ -203,91 +578,403 @@ function Map({
     };
   }, [imageUrl, isImageMode]);
   useEffect(() => {
-    if (!containerRef.current || !runtimeStyle) {
+    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);
+    }
+  }, [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);
+    }
+  }, [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 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,
-      style: runtimeStyle.style,
-      center: centerRef.current,
-      zoom: zoomRef.current,
-      interactive: resolvedInteractive,
-      attributionControl: stableMapOptions?.attributionControl ?? { compact: true },
-      transformRequest
-    });
-    mapRef.current = map;
-    const controls = resolvedInteractive ? new maplibregl.NavigationControl() : null;
-    if (controls) {
-      map.addControl(controls, "top-right");
-    }
-    const resizeObserver = new ResizeObserver(() => {
-      map.resize();
-    });
-    resizeObserver.observe(containerRef.current);
-    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();
+    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;
       }
-    });
-    return () => {
-      readinessRunRef.current += 1;
-      try {
-        lifecycle.dispose();
-      } finally {
+      const setupCleanups = [];
+      let setupDisposed = false;
+      const setupResources = {};
+      const registerCleanup = (cleanup) => setupCleanups.push(cleanup);
+      disposeMap = () => {
+        if (setupDisposed) return;
+        setupDisposed = true;
         try {
-          resizeObserver.disconnect();
+          runTileflowReactCleanups([...setupCleanups].reverse());
         } finally {
-          try {
-            markerController.clear();
-          } finally {
-            try {
-              map.remove();
-            } finally {
-              if (mapRef.current === map) mapRef.current = null;
-            }
+          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 });
+      const worldRequestBridge = registerTileflowWorldRequestBridge({
+        addProtocol: maplibregl.addProtocol,
+        onNotice: fairUseNotice.update
+      });
+      registerCleanup(() => worldRequestBridge.dispose());
+      const transformRequest = createTileflowTransformRequest({
+        always: true,
+        asyncAnalyticsTiming: "resolution",
+        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());
+      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 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;
+      if (themeController && latestRuntimeStyle && latestRuntimeStyle !== initialRuntimeStyle) {
+        setActiveRuntimeResource(latestRuntimeStyle);
+        void themeController.setTheme(latestRuntimeStyle);
+      }
+    }).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 () => {
+      cancelled = true;
+      readinessRunRef.current += 1;
+      disposeMap?.();
     };
-  }, [markerController, resolvedInteractive, runtimeStyle, stableMapOptions]);
+  }, [resolvedInteractive, runtimeMapIdentity, runtimeStyleReady, stableMapOptions]);
+  useEffect(() => {
+    const controller = themeControllerRef.current;
+    if (!controller) return;
+    if (themeResolution.error) {
+      void controller.setTheme(controller.getCurrent());
+      return;
+    }
+    if (!runtimeStyle || controller.getCurrent() === runtimeStyle) return;
+    setActiveRuntimeResource(runtimeStyle);
+    void controller.setTheme(runtimeStyle).then((result) => {
+      if (result.status === "failed") {
+        console.error("Failed to change the Tileflow map theme", result.error);
+      }
+    });
+  }, [runtimeStyle, themeResolution.error]);
   useLayoutEffect(() => {
     if (!isImageMode) return;
     readinessRunRef.current += 1;
+    setActiveRuntimeResource(runtimeImageUrl);
     setCaptureState("loading");
     const image = imageRef.current;
     if (image?.complete) {
@@ -307,17 +994,6 @@ function Map({
     }
     if (readinessRunRef.current === run) setCaptureState("idle");
   }
-  useEffect(() => {
-    const map = mapRef.current;
-    markerController.clear();
-    if (!map) {
-      return;
-    }
-    markerController.replace(map, markers);
-    return () => {
-      markerController.clear();
-    };
-  }, [markerController, markers, runtimeStyle]);
   const frameStyle = {
     height,
     minHeight: 240,
@@ -325,51 +1001,279 @@ 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(
+    return /* @__PURE__ */ jsxs(
       "div",
       {
         className,
         "data-tileflow-capture-id": resolvedCaptureId,
         "data-tileflow-map": mapName,
-        "data-tileflow-state": captureState,
+        "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%"
+        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,
+          diagnosticView
+        ]
       }
     );
   }
-  return /* @__PURE__ */ jsx(
-    "div",
-    {
-      className,
-      "data-tileflow-capture-id": resolvedCaptureId,
-      "data-tileflow-map": mapName,
-      "data-tileflow-state": captureState,
-      ref: containerRef,
-      style: frameStyle
+  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
+      );
+    })
+  ] });
+}
+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 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 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 };
+  }
+  const token = `${versionRef.current.version}:${signature}`;
+  const expectedKeysRef = useRef({ keys: [...portalKeys].sort(), token });
+  if (expectedKeysRef.current.token !== token) {
+    expectedKeysRef.current = { keys: [...portalKeys].sort(), token };
+  }
+  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;
     }
-  );
+    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]]);
+    }
+  };
+}
+function createTileflowMapLibrePoiMap(map) {
+  return {
+    getStyle: () => map.getStyle(),
+    on(event, listener) {
+      return map.on(event, listener);
+    },
+    queryRenderedFeatures(point, options) {
+      return map.queryRenderedFeatures(point, {
+        layers: [...options.layers]
+      });
+    }
+  };
+}
+function createOverlayFailureDiagnostic(message) {
+  return {
+    code: "OVERLAY_FAILURE",
+    level: "error",
+    message,
+    path: ""
+  };
+}
+function tileflowInteractionDiagnosticKey(diagnostic) {
+  return [
+    diagnostic.code,
+    diagnostic.level,
+    diagnostic.path ?? "",
+    diagnostic.target ? JSON.stringify(diagnostic.target) : "",
+    diagnostic.message
+  ].join("\0");
+}
+function runTileflowReactCleanups(cleanups) {
+  const errors = [];
+  for (const cleanup of cleanups) {
+    try {
+      cleanup();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, "Tileflow React cleanup failed.");
 }
 function useStableMapOptions(options) {
   return useStableMapOptionValue(options);
@@ -410,5 +1314,5 @@ function isPlainObject(value) {
   return prototype === Object.prototype || prototype === null;
 }
 export {
-  Map
+  Map2 as Map
 };