@tileflow/vue 0.1.0-alpha.18 → 0.1.0-alpha.20

package/dist/index.js

@@ -1,5 +1,4 @@
 // src/index.ts
-import maplibregl from "maplibre-gl";
 import {
   computed,
   defineComponent,
@@ -7,44 +6,197 @@ import {
   nextTick,
   onBeforeUnmount,
   onMounted,
+  onUpdated,
   ref,
   shallowRef,
-  watch
+  Teleport,
+  watch,
+  watchEffect
 } from "vue";
+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";
-var defaultCenter = [0, 20];
-var defaultZoom = 2;
+  initialTileflowInteractionState
+} from "@tileflow/interactions";
+import {
+  createTileflowMapLibreDomRuntime,
+  createTileflowMapLibreInteractionCoordinator,
+  createTileflowMapLibreSemanticDomRuntime
+} from "@tileflow/interactions/maplibre";
+
+// src/interactions.ts
+import {
+  tileflowInteractionStateSchema,
+  validateTileflowAnnotations,
+  validateTileflowInteractionBindings
+} from "@tileflow/interactions";
+import { normalizeTileflowLegacyMarkers } from "@tileflow/interactions/maplibre";
+function resolveTileflowVueAnnotations({
+  annotations,
+  markers
+}) {
+  if (annotations !== void 0 && markers !== void 0) {
+    return {
+      annotations: [],
+      diagnostics: [
+        createTileflowVueInteractionDiagnostic(
+          "INVALID_DOCUMENT",
+          "The annotations and legacy markers props are mutually exclusive."
+        )
+      ],
+      legacyTitles: /* @__PURE__ */ new Map(),
+      ok: false
+    };
+  }
+  const normalizedLegacyMarkers = normalizeTileflowLegacyMarkers(markers ?? []);
+  const legacyTitles = markers === void 0 ? /* @__PURE__ */ new Map() : normalizedLegacyMarkers.titles;
+  const candidates = annotations ?? normalizedLegacyMarkers.annotations;
+  const validation = validateTileflowAnnotations(candidates);
+  if (!validation.ok) {
+    return {
+      annotations: [],
+      diagnostics: validation.diagnostics,
+      legacyTitles,
+      ok: false
+    };
+  }
+  return {
+    // Validation deliberately does not replace application data with a schema clone. Slot
+    // contexts keep the caller's typed annotation and data identities.
+    annotations: candidates,
+    diagnostics: [],
+    legacyTitles,
+    ok: true
+  };
+}
+function resolveTileflowVueInteractionBindings(interactions) {
+  const candidates = interactions ?? [];
+  const validation = validateTileflowInteractionBindings(candidates);
+  if (!validation.ok) {
+    return { bindings: [], diagnostics: validation.diagnostics, ok: false };
+  }
+  return {
+    // As with annotations, validation must not replace caller-owned objects: bindings can be
+    // compared by identity by framework consumers even though their runtime shape is JSON-safe.
+    bindings: candidates,
+    diagnostics: [],
+    ok: true
+  };
+}
+function validateTileflowVueInteractionState(interactionState, defaultInteractionState) {
+  if (interactionState !== void 0 && defaultInteractionState !== void 0) {
+    return [
+      createTileflowVueInteractionDiagnostic(
+        "INVALID_DOCUMENT",
+        "interactionState and defaultInteractionState are mutually exclusive."
+      )
+    ];
+  }
+  const candidate = interactionState ?? defaultInteractionState;
+  if (candidate === void 0) return [];
+  const statePath = interactionState === void 0 ? "/defaultInteractionState" : "/interactionState";
+  const parsed = tileflowInteractionStateSchema.safeParse(candidate);
+  if (parsed.success) return [];
+  return parsed.error.issues.map(
+    (issue) => createTileflowVueInteractionDiagnostic(
+      "INVALID_DOCUMENT",
+      issue.message,
+      `${statePath}${jsonPointer(issue.path)}`
+    )
+  );
+}
+function createTileflowVueInteractionDiagnostic(code, message, path) {
+  return {
+    code,
+    level: "error",
+    message,
+    ...path === void 0 ? {} : { path }
+  };
+}
+function jsonPointer(path) {
+  return path.map((segment) => String(segment).replaceAll("~", "~0").replaceAll("/", "~1")).map((segment) => `/${segment}`).join("");
+}
+
+// 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/style-source.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 TileflowMap source: ${validation.error}`);
+  }
+}
+
+// src/index.ts
 var TileflowMap = defineComponent({
   name: "TileflowMap",
   inheritAttrs: false,
+  slots: Object,
   props: {
     alt: {
       default: "",
       type: String
     },
     analytics: Object,
+    annotations: Array,
     center: Array,
     captureId: String,
     className: String,
-    config: Object,
+    defaultInteractionState: Object,
     height: {
       default: 420,
       type: [Number, String]
@@ -58,129 +210,364 @@ var TileflowMap = defineComponent({
       default: void 0,
       type: Boolean
     },
-    manifestUrl: {
-      default: defaultTileflowManifestUrl,
-      type: String
-    },
-    map: String,
+    interactions: Array,
+    interactionState: Object,
     mapOptions: Object,
-    mapStyle: Object,
-    markers: {
-      default: () => [],
-      type: Array
-    },
+    markers: Array,
     mode: {
       default: "interactive",
       type: String
     },
-    preferLocalDev: {
-      default: true,
-      type: Boolean
+    source: {
+      required: true,
+      type: Object
     },
-    styleBaseUrl: String,
-    styleUrl: String,
-    themes: Object,
-    tileBaseUrl: String,
+    theme: String,
     zoom: Number
   },
   emits: {
-    load: (_map) => true
+    interactionDiagnostic: (_diagnostic) => true,
+    interactionEvent: (_event) => true,
+    load: (_map) => true,
+    themeChange: (_transition) => true,
+    "update:interactionState": (_state) => true
   },
-  setup(props, { attrs, emit }) {
+  setup(props, { attrs, emit, slots }) {
     const containerRef = ref(null);
-    const manifestMap = shallowRef(null);
+    const loadedManifestMap = shallowRef(null);
+    const manifestResolutionKey = ref("");
+    const manifestResolutionState = ref("loading");
     const imageSize = shallowRef(null);
     const mapRef = shallowRef(null);
-    const captureState = ref("loading");
-    const markerController = createTileflowMarkerController({
-      attach(markerInstance, map, marker) {
-        markerInstance.setLngLat(marker.coordinates).addTo(map);
-        markerInstance.getElement().title = marker.label ?? marker.id;
-      },
-      create: (marker) => new maplibregl.Marker({
-        color: marker.color ?? "#C6A15B"
-      }),
-      remove: (marker) => marker.remove()
-    });
+    const systemColorScheme = ref("light");
+    const mapCaptureState = ref("loading");
+    const themeTransitionState = ref("idle");
+    const activeRuntimeResource = shallowRef(void 0);
+    const interactionCaptureState = ref("idle");
+    const annotationRenderTargets = shallowRef([]);
+    const semanticRenderTargets = shallowRef(
+      []
+    );
+    const controlledInteractionOwnership = props.interactionState !== void 0;
+    let annotationRuntime = null;
+    let semanticRuntime = null;
+    let interactionRuntimesDisposing = false;
+    let initializeSemanticRuntime = null;
+    let annotationRuntimeDiagnosticsUnsubscribe = null;
+    let annotationRuntimeCoordinatorDetach = null;
+    let annotationRuntimeEventsUnsubscribe = null;
+    let annotationRuntimeTargetsUnsubscribe = null;
+    let semanticRuntimeDiagnosticsUnsubscribe = null;
+    let semanticRuntimeCoordinatorDetach = null;
+    let semanticRuntimeEventsUnsubscribe = null;
+    let semanticRuntimeTargetsUnsubscribe = null;
+    let activeAnnotationDiagnosticKeys = /* @__PURE__ */ new Set();
+    let activeSemanticDiagnosticKeys = /* @__PURE__ */ new Set();
+    let annotationRuntimeDiagnostics = [];
+    let semanticRuntimeDiagnostics = [];
+    let legacyTitles = /* @__PURE__ */ new Map();
     let imageResizeObserver = null;
+    let mapFairUseNotice = null;
     let mapLifecycle = null;
     let mapResizeObserver = null;
+    let mapWorldRequestBridge = null;
+    let themeController = null;
+    let unsubscribeSystemColorScheme = null;
+    let mapLoadId = 0;
     let manifestLoadId = 0;
     let readinessRunId = 0;
-    const resolvedMode = computed(
-      () => resolveTileflowMapMode({
-        imageUrl: props.imageUrl,
-        mode: props.mode,
-        preferLocalDev: props.preferLocalDev
+    let interactionReadinessRunId = 0;
+    let interactionReadinessFrames = [];
+    let interactionOverlayFailed = false;
+    let interactionInputDiagnosticSignature = "";
+    const resolvedMode = computed(() => resolveTileflowMapMode({ mode: props.mode }));
+    const isImageMode = computed(() => resolvedMode.value === "image");
+    const annotationResolution = computed(
+      () => resolveTileflowVueAnnotations({
+        annotations: props.annotations,
+        markers: props.markers
       })
     );
-    const isImageMode = computed(() => resolvedMode.value === "image");
-    const imageCenter = computed(() => props.center ?? defaultCenter);
-    const imageZoom = computed(() => props.zoom ?? defaultZoom);
+    const interactionBindingResolution = computed(
+      () => resolveTileflowVueInteractionBindings(props.interactions)
+    );
+    const interactionStateDiagnostics = computed(() => {
+      const diagnostics = [
+        ...validateTileflowVueInteractionState(
+          props.interactionState,
+          props.defaultInteractionState
+        )
+      ];
+      if (props.interactionState !== void 0 !== controlledInteractionOwnership) {
+        diagnostics.push(
+          createTileflowVueInteractionDiagnostic(
+            "INVALID_DOCUMENT",
+            "Tileflow interaction state ownership cannot switch between controlled and uncontrolled."
+          )
+        );
+      }
+      return diagnostics;
+    });
+    const hasInteractionConfiguration = computed(
+      () => props.annotations !== void 0 || props.markers !== void 0 || props.interactions !== void 0 || props.interactionState !== void 0 || props.defaultInteractionState !== void 0 || slots.marker !== void 0 || slots.popup !== void 0 || slots.tooltip !== void 0
+    );
+    const interactionInputDiagnostics = computed(() => {
+      const diagnostics = [
+        ...annotationResolution.value.diagnostics,
+        ...interactionBindingResolution.value.diagnostics,
+        ...interactionStateDiagnostics.value
+      ];
+      if (isImageMode.value && hasInteractionConfiguration.value) {
+        diagnostics.push(
+          createTileflowVueInteractionDiagnostic(
+            "UNSUPPORTED_MODE",
+            "Annotations, semantic interactions, and interaction state are unavailable in image mode."
+          )
+        );
+      }
+      return diagnostics;
+    });
+    const initialInteractionState = validateTileflowVueInteractionState(props.interactionState, props.defaultInteractionState).length === 0 ? props.interactionState ?? props.defaultInteractionState ?? initialTileflowInteractionState : initialTileflowInteractionState;
+    const interactionCoordinator = createTileflowMapLibreInteractionCoordinator({
+      onInteractionStateChange(nextState) {
+        if (interactionRuntimesDisposing) return;
+        emit("update:interactionState", nextState);
+      },
+      ...controlledInteractionOwnership ? { interactionState: initialInteractionState } : { defaultInteractionState: initialInteractionState }
+    });
+    const mapName = computed(
+      () => props.source.kind === "tileflow" ? props.source.map : void 0
+    );
+    const manifestUrl = computed(
+      () => props.source.kind === "tileflow" ? props.source.manifestUrl ?? defaultTileflowManifestUrl : defaultTileflowManifestUrl
+    );
+    const shouldLoadManifest = computed(
+      () => shouldLoadTileflowManifest({
+        source: props.source
+      })
+    );
+    const manifestRequestKey = computed(
+      () => shouldLoadManifest.value ? JSON.stringify([manifestUrl.value, mapName.value]) : "not-needed"
+    );
+    const currentManifestResolutionState = computed(
+      () => manifestResolutionKey.value === manifestRequestKey.value ? manifestResolutionState.value : shouldLoadManifest.value ? "loading" : "not-needed"
+    );
+    const manifestMap = computed(
+      () => manifestResolutionKey.value === manifestRequestKey.value && manifestResolutionState.value === "ready" ? loadedManifestMap.value : null
+    );
+    const themeResolution = computed(() => {
+      if (!manifestMap.value || props.source.kind !== "tileflow") {
+        return {
+          error: false,
+          name: props.source.kind === "tileflow" && props.theme && props.theme !== "system" ? props.theme : void 0
+        };
+      }
+      try {
+        return {
+          error: false,
+          name: resolveTileflowRuntimeTheme(manifestMap.value, props.theme, systemColorScheme.value).name
+        };
+      } catch {
+        return { error: true, name: void 0 };
+      }
+    });
+    const resolvedThemeName = computed(() => themeResolution.value.name);
+    const manifestView = computed(
+      () => resolveTileflowRuntimeView({ manifestMap: manifestMap.value })
+    );
+    const manifestCenter = computed(
+      () => normalizeTileflowRuntimeCenter(manifestView.value.center)
+    );
+    const imageCenter = computed(
+      () => normalizeTileflowRuntimeCenter(
+        props.center ?? props.mapOptions?.center,
+        manifestCenter.value
+      )
+    );
+    const imageZoom = computed(
+      () => props.zoom ?? props.mapOptions?.zoom ?? manifestView.value.zoom ?? defaultTileflowRuntimeView.zoom
+    );
     const resolvedCenter = computed(
-      () => props.center ?? props.mapOptions?.center ?? defaultCenter
+      () => props.center ?? props.mapOptions?.center ?? manifestCenter.value
     );
-    const resolvedZoom = computed(() => props.zoom ?? props.mapOptions?.zoom ?? defaultZoom);
+    const resolvedZoom = computed(
+      () => props.zoom ?? props.mapOptions?.zoom ?? manifestView.value.zoom ?? defaultTileflowRuntimeView.zoom
+    );
+    const resolvedBearing = computed(() => props.mapOptions?.bearing ?? manifestView.value.bearing);
+    const resolvedPitch = computed(() => props.mapOptions?.pitch ?? manifestView.value.pitch);
     const resolvedInteractive = computed(
       () => props.interactive ?? props.mapOptions?.interactive ?? true
     );
     const runtimeStyle = computed(
-      () => isImageMode.value ? null : resolveTileflowRuntimeStyle({
-        config: props.config,
+      () => isImageMode.value || themeResolution.value.error ? null : resolveTileflowRuntimeStyle({
+        colorScheme: systemColorScheme.value,
         manifestMap: manifestMap.value,
-        map: props.map,
-        preferLocalDev: props.preferLocalDev,
-        style: props.mapStyle,
-        styleBaseUrl: props.styleBaseUrl,
-        styleUrl: props.styleUrl,
-        themes: props.themes,
-        tileBaseUrl: props.tileBaseUrl
+        source: props.source,
+        theme: themeResolution.value.name
       })
     );
     const resolvedAnalytics = computed(
       () => mergeTileflowAnalytics(props.analytics, runtimeStyle.value?.analytics)
     );
     const runtimeImageUrl = computed(
-      () => props.imageUrl ?? (isImageMode.value ? resolveTileflowStaticImageUrl({
+      () => props.imageUrl ?? (isImageMode.value && !themeResolution.value.error ? resolveTileflowStaticImageUrl({
         center: imageCenter.value,
+        colorScheme: systemColorScheme.value,
         imageSize: imageSize.value,
         manifestMap: manifestMap.value,
+        theme: themeResolution.value.name,
         zoom: imageZoom.value
       }) : void 0)
     );
+    const runtimeResolutionState = computed(() => {
+      if (shouldLoadManifest.value && currentManifestResolutionState.value !== "ready") {
+        return currentManifestResolutionState.value === "error" ? "error" : "loading";
+      }
+      if (themeResolution.value.error) return "error";
+      if (isImageMode.value) {
+        if (runtimeImageUrl.value) return "idle";
+        return props.imageUrl === void 0 && imageSize.value === null ? "loading" : "error";
+      }
+      return runtimeStyle.value ? "idle" : "error";
+    });
+    const currentMapCaptureState = computed(
+      () => activeRuntimeResource.value === (isImageMode.value ? runtimeImageUrl.value : runtimeStyle.value) ? mapCaptureState.value : "loading"
+    );
+    const captureState = computed(() => {
+      if (currentMapCaptureState.value === "error" || interactionCaptureState.value === "error" || runtimeResolutionState.value === "error" || themeTransitionState.value === "error") {
+        return "error";
+      }
+      if (currentMapCaptureState.value === "loading" || interactionCaptureState.value === "loading" || runtimeResolutionState.value === "loading" || themeTransitionState.value === "loading") {
+        return "loading";
+      }
+      return "idle";
+    });
     const frameStyle = computed(() => ({
-      height: formatHeight(props.height),
+      height: formatHeight(props.height ?? 420),
       minHeight: "240px",
       overflow: "hidden",
       position: "relative",
       width: "100%"
     }));
     const resolvedCaptureId = computed(() => normalizeTileflowCaptureId(props.captureId));
-    const refreshManifest = async () => {
-      const shouldLoad = shouldLoadTileflowManifest({
-        config: props.config,
-        imageMode: isImageMode.value,
-        imageUrl: props.imageUrl,
-        map: props.map,
-        style: props.mapStyle,
-        styleBaseUrl: props.styleBaseUrl,
-        styleUrl: props.styleUrl
+    const emitInteractionDiagnostics = (diagnostics) => {
+      for (const diagnostic of diagnostics) emit("interactionDiagnostic", diagnostic);
+    };
+    const hasInteractionErrors = () => interactionOverlayFailed || interactionInputDiagnostics.value.some(({ level }) => level === "error") || annotationRuntimeDiagnostics.some(({ level }) => level === "error") || semanticRuntimeDiagnostics.some(({ level }) => level === "error");
+    const invalidateInteractionReadiness = () => {
+      interactionReadinessRunId += 1;
+      if (typeof cancelAnimationFrame === "function") {
+        for (const frame of interactionReadinessFrames) cancelAnimationFrame(frame);
+      }
+      interactionReadinessFrames = [];
+    };
+    const settleInteractionReadiness = () => {
+      invalidateInteractionReadiness();
+      if (hasInteractionErrors()) {
+        interactionCaptureState.value = "error";
+        return;
+      }
+      const runId = interactionReadinessRunId;
+      interactionCaptureState.value = "loading";
+      void nextTick().then(() => {
+        if (runId !== interactionReadinessRunId || hasInteractionErrors()) return;
+        const view = containerRef.value?.ownerDocument.defaultView;
+        if (!view) {
+          interactionCaptureState.value = "idle";
+          return;
+        }
+        const firstFrame = view.requestAnimationFrame(() => {
+          interactionReadinessFrames = interactionReadinessFrames.filter(
+            (frame) => frame !== firstFrame
+          );
+          if (runId !== interactionReadinessRunId || hasInteractionErrors()) return;
+          const secondFrame = view.requestAnimationFrame(() => {
+            interactionReadinessFrames = interactionReadinessFrames.filter(
+              (frame) => frame !== secondFrame
+            );
+            if (runId !== interactionReadinessRunId || hasInteractionErrors()) return;
+            interactionCaptureState.value = "idle";
+          });
+          interactionReadinessFrames.push(secondFrame);
+        });
+        interactionReadinessFrames.push(firstFrame);
       });
+    };
+    let renderTargetKeySignature = "";
+    const syncInteractionRenderTargetReadiness = () => {
+      const nextSignature = JSON.stringify([
+        ...annotationRenderTargets.value.map(({ key }) => `annotation:${key}`),
+        ...semanticRenderTargets.value.map(({ key }) => `semantic:${key}`)
+      ]);
+      if (nextSignature === renderTargetKeySignature) return;
+      renderTargetKeySignature = nextSignature;
+      settleInteractionReadiness();
+    };
+    const syncRuntimeDiagnostics = (source, diagnostics) => {
+      const previouslyActiveKeys = /* @__PURE__ */ new Set([
+        ...activeAnnotationDiagnosticKeys,
+        ...activeSemanticDiagnosticKeys
+      ]);
+      const nextKeys = new Set(diagnostics.map(interactionDiagnosticKey));
+      if (source === "annotation") {
+        activeAnnotationDiagnosticKeys = nextKeys;
+        annotationRuntimeDiagnostics = diagnostics;
+      } else {
+        activeSemanticDiagnosticKeys = nextKeys;
+        semanticRuntimeDiagnostics = diagnostics;
+      }
+      emitInteractionDiagnostics(
+        diagnostics.filter(
+          (diagnostic) => !previouslyActiveKeys.has(interactionDiagnosticKey(diagnostic))
+        )
+      );
+      settleInteractionReadiness();
+    };
+    const reportOverlayFailure = (message) => {
+      interactionOverlayFailed = true;
+      interactionCaptureState.value = "error";
+      emitInteractionDiagnostics([
+        createTileflowVueInteractionDiagnostic("OVERLAY_FAILURE", message)
+      ]);
+    };
+    watchEffect(() => {
+      assertTileflowMapStyleInputs({ source: props.source, theme: props.theme });
+    });
+    watchEffect(() => {
+      const diagnostics = interactionInputDiagnostics.value;
+      const signature = JSON.stringify(diagnostics);
+      if (signature !== interactionInputDiagnosticSignature) {
+        interactionInputDiagnosticSignature = signature;
+        emitInteractionDiagnostics(diagnostics);
+      }
+      settleInteractionReadiness();
+    });
+    const refreshManifest = async () => {
+      const shouldLoad = shouldLoadManifest.value;
+      const requestKey = manifestRequestKey.value;
       if (!shouldLoad) {
-        manifestMap.value = null;
+        manifestLoadId += 1;
+        loadedManifestMap.value = null;
+        manifestResolutionKey.value = requestKey;
+        manifestResolutionState.value = "not-needed";
         return;
       }
       const loadId = ++manifestLoadId;
-      manifestMap.value = null;
+      loadedManifestMap.value = null;
+      manifestResolutionKey.value = requestKey;
+      manifestResolutionState.value = "loading";
       try {
-        const manifest = await loadTileflowManifest(props.manifestUrl);
+        const manifest = await loadTileflowManifest(manifestUrl.value);
         if (loadId === manifestLoadId) {
-          manifestMap.value = manifest && props.map ? resolveTileflowManifestMap(manifest, props.map) : null;
+          const resolvedMap = manifest && mapName.value ? resolveTileflowManifestMap(manifest, mapName.value) : null;
+          loadedManifestMap.value = resolvedMap;
+          manifestResolutionState.value = resolvedMap ? "ready" : "error";
         }
       } catch (error) {
         if (loadId === manifestLoadId) {
           console.error("Failed to load Tileflow manifest", error);
-          manifestMap.value = null;
+          loadedManifestMap.value = null;
+          manifestResolutionState.value = "error";
         }
       }
     };
@@ -204,70 +591,303 @@ var TileflowMap = defineComponent({
       updateImageSize();
     };
     const destroyMap = () => {
+      mapLoadId += 1;
       readinessRunId += 1;
+      invalidateInteractionReadiness();
       const lifecycle = mapLifecycle;
+      const fairUseNotice = mapFairUseNotice;
       const resizeObserver = mapResizeObserver;
       const map = mapRef.value;
+      const controller = themeController;
+      const annotationInteractionsForMap = annotationRuntime;
+      const semanticInteractionsForMap = semanticRuntime;
+      const worldRequestBridge = mapWorldRequestBridge;
+      const teardownSteps = [
+        annotationRuntimeCoordinatorDetach,
+        semanticRuntimeCoordinatorDetach,
+        annotationRuntimeTargetsUnsubscribe,
+        annotationRuntimeDiagnosticsUnsubscribe,
+        annotationRuntimeEventsUnsubscribe,
+        semanticRuntimeTargetsUnsubscribe,
+        semanticRuntimeDiagnosticsUnsubscribe,
+        semanticRuntimeEventsUnsubscribe,
+        () => annotationInteractionsForMap?.dispose(),
+        () => semanticInteractionsForMap?.dispose(),
+        () => worldRequestBridge?.dispose(),
+        () => fairUseNotice?.dispose(),
+        () => lifecycle?.dispose(),
+        () => controller?.dispose(),
+        () => resizeObserver?.disconnect(),
+        () => map?.remove()
+      ];
+      annotationRuntime = null;
+      semanticRuntime = null;
+      initializeSemanticRuntime = null;
+      annotationRuntimeCoordinatorDetach = null;
+      annotationRuntimeDiagnosticsUnsubscribe = null;
+      annotationRuntimeEventsUnsubscribe = null;
+      annotationRuntimeTargetsUnsubscribe = null;
+      semanticRuntimeDiagnosticsUnsubscribe = null;
+      semanticRuntimeCoordinatorDetach = null;
+      semanticRuntimeEventsUnsubscribe = null;
+      semanticRuntimeTargetsUnsubscribe = null;
+      annotationRenderTargets.value = [];
+      semanticRenderTargets.value = [];
+      activeAnnotationDiagnosticKeys = /* @__PURE__ */ new Set();
+      activeSemanticDiagnosticKeys = /* @__PURE__ */ new Set();
+      annotationRuntimeDiagnostics = [];
+      semanticRuntimeDiagnostics = [];
+      renderTargetKeySignature = "";
+      mapFairUseNotice = null;
       mapLifecycle = null;
       mapResizeObserver = null;
       mapRef.value = null;
-      try {
-        lifecycle?.dispose();
-      } finally {
+      mapWorldRequestBridge = null;
+      themeController = null;
+      interactionRuntimesDisposing = true;
+      let teardownError;
+      for (const teardown of teardownSteps) {
         try {
-          resizeObserver?.disconnect();
-        } finally {
-          try {
-            markerController.clear();
-          } finally {
-            map?.remove();
-          }
+          teardown?.();
+        } catch (error) {
+          teardownError ??= error;
         }
       }
+      interactionRuntimesDisposing = false;
+      interactionCaptureState.value = hasInteractionErrors() ? "error" : "idle";
+      if (teardownError) {
+        console.error("Failed to fully dispose the Tileflow map runtime", teardownError);
+      }
+    };
+    const syncAnnotationRuntime = () => {
+      const resolution = annotationResolution.value;
+      legacyTitles = new Map(resolution.legacyTitles);
+      if (!annotationRuntime) return;
+      try {
+        annotationRuntime.reconcile(
+          resolution.ok && !isImageMode.value ? resolution.annotations : []
+        );
+      } catch {
+        reportOverlayFailure("Unable to reconcile the Tileflow annotation runtime.");
+      }
+    };
+    const syncSemanticRuntime = () => {
+      const resolution = interactionBindingResolution.value;
+      const bindings = resolution.ok && !isImageMode.value ? resolution.bindings : [];
+      if (bindings.length > 0 && !semanticRuntime) initializeSemanticRuntime?.();
+      if (!semanticRuntime) return;
+      try {
+        semanticRuntime.reconcile(bindings);
+      } catch {
+        reportOverlayFailure("Unable to reconcile the Tileflow semantic interaction runtime.");
+      }
     };
-    const recreateMap = () => {
+    const syncCustomRenderers = () => {
+      try {
+        annotationRuntime?.setCustomRenderers({
+          marker: slots.marker !== void 0,
+          popup: slots.popup !== void 0,
+          tooltip: slots.tooltip !== void 0
+        });
+        semanticRuntime?.setCustomRenderers({
+          popup: slots.popup !== void 0,
+          tooltip: slots.tooltip !== void 0
+        });
+      } catch {
+        reportOverlayFailure("Unable to update the Tileflow interaction renderers.");
+      }
+    };
+    const recreateMap = async () => {
       destroyMap();
-      captureState.value = "loading";
-      if (!containerRef.value || !runtimeStyle.value || isImageMode.value) {
+      interactionOverlayFailed = false;
+      settleInteractionReadiness();
+      mapCaptureState.value = "loading";
+      themeTransitionState.value = "idle";
+      if (isImageMode.value) {
+        await resetImageReadiness();
         return;
       }
+      activeRuntimeResource.value = runtimeStyle.value;
+      if (!containerRef.value || !runtimeStyle.value) {
+        return;
+      }
+      const loadId = mapLoadId;
+      const container = containerRef.value;
       const runtime = runtimeStyle.value;
-      const analyticsForMap = resolvedAnalytics.value;
+      let maplibregl;
+      try {
+        [maplibregl] = await Promise.all([
+          loadTileflowMapLibre(),
+          loadTileflowStyleFonts(runtime.style, {
+            fontFaces: runtime.fontFaces
+          })
+        ]);
+      } catch (error) {
+        if (loadId === mapLoadId) {
+          console.error("Failed to load the Tileflow map runtime", error);
+          mapCaptureState.value = "error";
+        }
+        return;
+      }
+      if (loadId !== mapLoadId || containerRef.value !== container || isImageMode.value) {
+        return;
+      }
       const session = createTileflowSessionController({ source: "vue" });
       const sessionStarter = createTileflowSessionStarter({
         getSessionId: () => session.sessionId,
         sessionId: session.sessionId,
         source: "vue"
       });
+      mapFairUseNotice = attachTileflowFairUseNotice(container);
+      registerTileflowContourProtocol({ addProtocol: maplibregl.addProtocol });
+      mapWorldRequestBridge = registerTileflowWorldRequestBridge({
+        addProtocol: maplibregl.addProtocol,
+        onNotice: mapFairUseNotice.update
+      });
       const map = new maplibregl.Map({
         ...props.mapOptions,
-        attributionControl: props.mapOptions?.attributionControl ?? { compact: true },
+        attributionControl: props.mapOptions?.attributionControl ?? {
+          compact: true
+        },
+        bearing: resolvedBearing.value,
         center: resolvedCenter.value,
-        container: containerRef.value,
+        container,
         interactive: resolvedInteractive.value,
+        pitch: resolvedPitch.value,
         style: runtime.style,
         transformRequest: createTileflowTransformRequest({
-          getAnalytics: () => analyticsForMap,
+          getAnalytics: () => resolvedAnalytics.value,
           sessionController: session,
           sessionId: session.sessionId,
-          transformRequest: props.mapOptions?.transformRequest ?? void 0
+          transformRequest: props.mapOptions?.transformRequest ?? void 0,
+          worldRequestBridge: mapWorldRequestBridge
         }),
         zoom: resolvedZoom.value
       });
       mapRef.value = map;
+      themeController = runtime.theme === void 0 ? null : createTileflowThemeController({
+        initial: runtime,
+        map,
+        onTransition(transition) {
+          emit("themeChange", transition);
+          if (transition.phase === "preloading" || transition.phase === "applying") {
+            themeTransitionState.value = "loading";
+          } else if (transition.phase === "error") {
+            themeTransitionState.value = "error";
+          } else {
+            themeTransitionState.value = "idle";
+          }
+        }
+      });
+      try {
+        const mapInteractions = createTileflowMapLibreDomRuntime({
+          createMarker({ annotation, element }) {
+            element.title = legacyTitles.get(annotation.id) ?? annotation.ariaLabel;
+            return new maplibregl.Marker({ element });
+          },
+          customMarker: slots.marker !== void 0,
+          customPopup: slots.popup !== void 0,
+          customTooltip: slots.tooltip !== void 0,
+          createOverlay({ container: overlayContainer, kind }) {
+            return new maplibregl.Popup({
+              closeButton: false,
+              closeOnClick: false,
+              closeOnMove: false,
+              focusAfterOpen: false,
+              offset: kind === "popup" ? 24 : 18
+            }).setDOMContent(overlayContainer);
+          },
+          document: container.ownerDocument,
+          interactionState: interactionCoordinator.getInteractionState(),
+          map,
+          onInteractionStateChange: interactionCoordinator.requestInteractionState,
+          updateMarker(_marker, { annotation, element }) {
+            element.title = legacyTitles.get(annotation.id) ?? annotation.ariaLabel;
+          }
+        });
+        annotationRuntime = mapInteractions;
+        annotationRuntimeCoordinatorDetach = interactionCoordinator.attach(
+          "annotation",
+          mapInteractions
+        );
+        annotationRuntimeDiagnosticsUnsubscribe = mapInteractions.subscribeDiagnostics(
+          (diagnostics) => syncRuntimeDiagnostics("annotation", diagnostics)
+        );
+        annotationRuntimeEventsUnsubscribe = mapInteractions.subscribeEvents((event) => {
+          if (!interactionRuntimesDisposing) emit("interactionEvent", event);
+        });
+        syncRuntimeDiagnostics("annotation", mapInteractions.getDiagnostics());
+        annotationRuntimeTargetsUnsubscribe = mapInteractions.subscribeRenderTargets((targets) => {
+          annotationRenderTargets.value = targets;
+          syncInteractionRenderTargetReadiness();
+        });
+        annotationRenderTargets.value = mapInteractions.getRenderTargets();
+        syncInteractionRenderTargetReadiness();
+        syncAnnotationRuntime();
+      } catch {
+        reportOverlayFailure("Unable to initialize the Tileflow annotation runtime.");
+      }
+      initializeSemanticRuntime = () => {
+        if (semanticRuntime || interactionRuntimesDisposing || mapRef.value !== map) return;
+        try {
+          const semanticInteractions = createTileflowMapLibreSemanticDomRuntime({
+            cancelFrame: (frame) => cancelAnimationFrame(frame),
+            createOverlay({ container: overlayContainer, kind }) {
+              return new maplibregl.Popup({
+                closeButton: false,
+                closeOnClick: false,
+                closeOnMove: false,
+                focusAfterOpen: false,
+                offset: kind === "popup" ? 24 : 18
+              }).setDOMContent(overlayContainer);
+            },
+            customPopup: slots.popup !== void 0,
+            customTooltip: slots.tooltip !== void 0,
+            document: container.ownerDocument,
+            interactionState: interactionCoordinator.getInteractionState(),
+            map,
+            onInteractionStateChange: interactionCoordinator.requestInteractionState,
+            poiMap: createTileflowVuePoiMap(map),
+            requestFrame: (callback) => requestAnimationFrame(callback)
+          });
+          semanticRuntime = semanticInteractions;
+          semanticRuntimeCoordinatorDetach = interactionCoordinator.attach(
+            "semantic",
+            semanticInteractions
+          );
+          semanticRuntimeDiagnosticsUnsubscribe = semanticInteractions.subscribeDiagnostics(
+            (diagnostics) => syncRuntimeDiagnostics("semantic", diagnostics)
+          );
+          semanticRuntimeEventsUnsubscribe = semanticInteractions.subscribeEvents((event) => {
+            if (!interactionRuntimesDisposing) emit("interactionEvent", event);
+          });
+          syncRuntimeDiagnostics("semantic", semanticInteractions.getDiagnostics());
+          semanticRuntimeTargetsUnsubscribe = semanticInteractions.subscribeRenderTargets(
+            (targets) => {
+              semanticRenderTargets.value = targets;
+              syncInteractionRenderTargetReadiness();
+            }
+          );
+          semanticRenderTargets.value = semanticInteractions.getRenderTargets();
+          syncInteractionRenderTargetReadiness();
+        } catch {
+          reportOverlayFailure("Unable to initialize the Tileflow semantic interaction runtime.");
+        }
+      };
+      syncSemanticRuntime();
       if (resolvedInteractive.value) {
         map.addControl(new maplibregl.NavigationControl(), "top-right");
       }
       mapResizeObserver = new ResizeObserver(() => {
         map.resize();
       });
-      mapResizeObserver.observe(containerRef.value);
+      mapResizeObserver.observe(container);
       mapLifecycle = attachTileflowMapLifecycle({
         getSession: () => {
           const analyticsForLoad = resolvedAnalytics.value;
           return {
             analytics: analyticsForLoad,
-            styleId: analyticsForLoad?.styleId ?? (typeof runtime.style === "string" ? runtime.style : props.map)
+            styleId: analyticsForLoad?.styleId ?? (typeof runtime.style === "string" ? runtime.style : mapName.value)
           };
         },
         map,
@@ -278,121 +898,174 @@ var TileflowMap = defineComponent({
         },
         sessionStarter,
         setState: (state) => {
-          captureState.value = state;
+          mapCaptureState.value = state;
         },
         subscribe: (subscribedMap, event, listener) => {
           const subscription = subscribedMap.on(event, listener);
           return () => subscription.unsubscribe();
         }
       });
-      syncMarkers();
+      if (themeController && runtimeStyle.value && runtimeStyle.value !== runtime) {
+        activeRuntimeResource.value = runtimeStyle.value;
+        void themeController.setTheme(runtimeStyle.value);
+      }
+    };
+    const switchTheme = () => {
+      if (!themeController) return;
+      if (themeResolution.value.error) {
+        void themeController.setTheme(themeController.getCurrent());
+        return;
+      }
+      const next = runtimeStyle.value;
+      if (!next) return;
+      activeRuntimeResource.value = next;
+      void themeController.setTheme(next).then((result) => {
+        if (result.status === "failed") {
+          console.error("Failed to change the Tileflow map theme", result.error);
+        }
+      });
+    };
+    const syncSystemColorSchemeSubscription = () => {
+      unsubscribeSystemColorScheme?.();
+      unsubscribeSystemColorScheme = null;
+      if (props.theme !== "system") return;
+      systemColorScheme.value = getTileflowSystemColorScheme();
+      unsubscribeSystemColorScheme = subscribeTileflowSystemColorScheme((scheme) => {
+        systemColorScheme.value = scheme;
+      });
     };
     const syncView = () => {
       mapRef.value?.jumpTo({
+        bearing: resolvedBearing.value,
         center: resolvedCenter.value,
+        pitch: resolvedPitch.value,
         zoom: resolvedZoom.value
       });
     };
-    const syncMarkers = () => {
-      const map = mapRef.value;
-      if (!map) {
-        markerController.clear();
-        return;
-      }
-      markerController.replace(map, props.markers);
-    };
     const markImageReady = async (image) => {
       const runId = ++readinessRunId;
       try {
         if (typeof image.decode === "function") await image.decode();
       } catch {
         if (!image.complete || image.naturalWidth === 0) {
-          if (runId === readinessRunId) captureState.value = "error";
+          if (runId === readinessRunId) mapCaptureState.value = "error";
           return;
         }
       }
-      if (runId === readinessRunId) captureState.value = "idle";
+      if (runId === readinessRunId) {
+        mapCaptureState.value = "idle";
+      }
     };
     const resetImageReadiness = async () => {
       if (!isImageMode.value) return;
       const runId = ++readinessRunId;
-      captureState.value = "loading";
+      activeRuntimeResource.value = runtimeImageUrl.value;
+      if (hasInteractionConfiguration.value) {
+        mapCaptureState.value = "idle";
+        return;
+      }
+      mapCaptureState.value = "loading";
       await nextTick();
       if (runId !== readinessRunId) return;
       const image = containerRef.value?.querySelector("img");
       if (!image?.complete) return;
       if (image.naturalWidth === 0) {
-        captureState.value = "error";
+        mapCaptureState.value = "error";
         return;
       }
       await markImageReady(image);
     };
     onMounted(() => {
+      syncSystemColorSchemeSubscription();
       void refreshManifest();
       updateImageResizeObserver();
-      recreateMap();
+      void recreateMap();
       void resetImageReadiness();
     });
     onBeforeUnmount(() => {
+      unsubscribeSystemColorScheme?.();
       imageResizeObserver?.disconnect();
       destroyMap();
+      interactionCoordinator.dispose();
+    });
+    onUpdated(() => {
+      syncCustomRenderers();
     });
     watch(
-      () => [
-        props.config,
-        props.imageUrl,
-        props.manifestUrl,
-        props.map,
-        props.mapStyle,
-        props.mode,
-        props.preferLocalDev,
-        props.styleBaseUrl,
-        props.styleUrl
-      ],
+      () => [props.imageUrl, props.mode, props.source],
       () => {
         void refreshManifest();
       }
     );
     watch(
-      () => [isImageMode.value, runtimeImageUrl.value],
+      () => props.theme,
+      () => syncSystemColorSchemeSubscription()
+    );
+    watch(
+      () => runtimeStyle.value,
+      () => switchTheme(),
+      { flush: "post" }
+    );
+    watch(
+      () => [hasInteractionConfiguration.value, isImageMode.value, runtimeImageUrl.value],
       () => {
         void resetImageReadiness();
       },
       { flush: "post" }
     );
     watch(
-      () => [props.imageUrl, props.mode, props.preferLocalDev],
+      () => [props.imageUrl, props.mode],
       () => updateImageResizeObserver(),
       { flush: "post" }
     );
     watch(
       () => [
-        props.config,
         props.analytics,
         props.interactive,
-        props.map,
         props.mapOptions,
-        props.mapStyle,
         props.mode,
-        props.preferLocalDev,
-        props.styleBaseUrl,
-        props.styleUrl,
-        props.themes,
-        props.tileBaseUrl,
+        props.source,
         manifestMap.value
       ],
-      () => recreateMap(),
+      () => void recreateMap(),
       { flush: "post" }
     );
     watch(
-      () => [props.center, props.zoom, props.mapOptions?.center, props.mapOptions?.zoom],
+      () => [
+        props.center,
+        props.zoom,
+        props.mapOptions?.bearing,
+        props.mapOptions?.center,
+        props.mapOptions?.pitch,
+        props.mapOptions?.zoom,
+        manifestMap.value?.view
+      ],
       () => syncView(),
       { flush: "post" }
     );
     watch(
-      () => props.markers,
-      () => syncMarkers(),
-      { flush: "post" }
+      () => [props.annotations, props.markers],
+      () => syncAnnotationRuntime(),
+      { deep: true, flush: "post" }
+    );
+    watch(
+      () => props.interactions,
+      () => syncSemanticRuntime(),
+      { deep: true, flush: "post" }
+    );
+    watch(
+      () => props.interactionState,
+      (nextState) => {
+        if (!controlledInteractionOwnership || nextState === void 0 || interactionStateDiagnostics.value.length > 0) {
+          return;
+        }
+        try {
+          interactionCoordinator.setInteractionState(nextState);
+        } catch {
+          reportOverlayFailure("Unable to apply Tileflow interaction state.");
+        }
+      },
+      { deep: true, flush: "post" }
     );
     return () => {
       const rootAttrs = { ...attrs };
@@ -400,34 +1073,66 @@ var TileflowMap = defineComponent({
       const styleValue = [attrs.style, frameStyle.value];
       delete rootAttrs.class;
       delete rootAttrs.style;
+      const image = isImageMode.value && runtimeImageUrl.value ? h("img", {
+        alt: props.alt,
+        decoding: "async",
+        loading: props.imageLoading,
+        onError: () => {
+          readinessRunId += 1;
+          mapCaptureState.value = "error";
+        },
+        onLoad: (event) => void markImageReady(event.currentTarget),
+        src: runtimeImageUrl.value,
+        style: {
+          display: "block",
+          height: "100%",
+          objectFit: "cover",
+          width: "100%"
+        }
+      }) : void 0;
+      const annotationTeleports = annotationRenderTargets.value.flatMap((target) => {
+        const slot = target.kind === "marker" ? slots.marker : target.kind === "tooltip" ? slots.tooltip : slots.popup;
+        if (!slot) return [];
+        const content = target.annotation[target.kind]?.content;
+        const context = {
+          annotation: target.annotation,
+          close: target.close,
+          content,
+          target: {
+            annotation: target.annotation,
+            coordinate: target.annotation.coordinate,
+            kind: "annotation"
+          },
+          viewName: content?.kind === "view" ? content.name : void 0
+        };
+        return [
+          h(Teleport, { key: `annotation:${target.key}`, to: target.container }, slot(context))
+        ];
+      });
+      const semanticTeleports = semanticRenderTargets.value.flatMap((target) => {
+        const slot = target.kind === "tooltip" ? slots.tooltip : slots.popup;
+        if (!slot) return [];
+        const context = {
+          close: target.close,
+          content: target.content,
+          target: target.target,
+          viewName: target.viewName
+        };
+        return [h(Teleport, { key: `semantic:${target.key}`, to: target.container }, slot(context))];
+      });
       return h(
         "div",
         {
           ...rootAttrs,
           class: classValue,
           "data-tileflow-capture-id": resolvedCaptureId.value,
-          "data-tileflow-map": props.map,
+          "data-tileflow-map": mapName.value,
+          "data-tileflow-theme": resolvedThemeName.value,
           "data-tileflow-state": captureState.value,
           ref: containerRef,
           style: styleValue
         },
-        isImageMode.value && runtimeImageUrl.value ? h("img", {
-          alt: props.alt,
-          decoding: "async",
-          loading: props.imageLoading,
-          onError: () => {
-            readinessRunId += 1;
-            captureState.value = "error";
-          },
-          onLoad: (event) => void markImageReady(event.currentTarget),
-          src: runtimeImageUrl.value,
-          style: {
-            display: "block",
-            height: "100%",
-            objectFit: "cover",
-            width: "100%"
-          }
-        }) : void 0
+        [image, ...annotationTeleports, ...semanticTeleports]
       );
     };
   }
@@ -436,6 +1141,26 @@ var index_default = TileflowMap;
 function formatHeight(height) {
   return typeof height === "number" ? `${height}px` : height;
 }
+function interactionDiagnosticKey(diagnostic) {
+  return JSON.stringify([diagnostic.code, diagnostic.message, diagnostic.path, diagnostic.target]);
+}
+function createTileflowVuePoiMap(map) {
+  return {
+    getStyle: () => map.getStyle(),
+    on: (event, listener) => map.on(event, listener),
+    queryRenderedFeatures(point, options) {
+      return map.queryRenderedFeatures(point, {
+        layers: [...options.layers]
+      }).map((feature) => ({
+        ...feature.id === void 0 ? {} : { id: feature.id },
+        layer: { id: feature.layer.id },
+        ...feature.properties === null ? {} : { properties: feature.properties },
+        ...feature.source === void 0 ? {} : { source: feature.source },
+        ...feature.sourceLayer === void 0 ? {} : { sourceLayer: feature.sourceLayer }
+      }));
+    }
+  };
+}
 export {
   TileflowMap,
   index_default as default