@tileflow/dom 0.1.0-alpha.0 → 0.1.0-alpha.1

package/REFERENCE.md

@@ -73,6 +73,17 @@ with no renderer keeps the default view.
 | `getInteractionState()`, `getRenderTargets()`            | The open popup; the view elements the map handed out.                                                                                              |
 | `destroy()`                                              | Takes the map down, removes the capture attributes and stops every listener. Later calls do nothing.                                               |
 
+Use `getMap()` or the map passed to `onLoad` for application-owned MapLibre sources, layers,
+controls and events. Tileflow owns the style; theme changes may replace it, so reinstall your
+own layers on `style.load`, or use `dataSources` and `dataOverlays`. Calling the MapLibre map's
+`remove()` also stops the Tileflow controller. Prefer `destroy()` for normal application cleanup.
+Destroying during loading rejects `ready` and prevents a late response from mounting a map.
+
+If optional interactions cannot start, the map remains mounted and reports an interaction
+diagnostic. Changing their inputs retries initialization. A failed theme change keeps the
+applied theme and its system-colour-scheme following; an unknown name does not cancel a valid
+pending change. `getStatus()` reports the failure until the requested selection changes.
+
 ## `getTileflowMapInitialStatus(options, controlledInteractionState?)`
 
 The status a map with these options has before it mounts: its declarative diagnostics, `error` or

package/dist/index.js

@@ -181,6 +181,8 @@ function imageModeMapInteractionDiagnostic(annotationCount, bindingCount, hasAdd
 
 // src/maplibre.ts
 var bundlerWorkerUrlKey = /* @__PURE__ */ Symbol.for("tileflow.maplibre.workerUrl");
+var importMapLibre = () => import("maplibre-gl");
+var loadMapLibreModule = importMapLibre;
 var mapLibrePromise;
 var mapLibre;
 var workerUrl;
@@ -202,7 +204,7 @@ function configureTileflowMapLibre(configuration) {
   if (mapLibre) applyWorkerUrl(mapLibre);
 }
 function loadTileflowMapLibre() {
-  mapLibrePromise ??= import("maplibre-gl").then(resolveMapLibreModule).then(configureTileflowMapLibreModule).catch((error) => {
+  mapLibrePromise ??= loadMapLibreModule().then(resolveMapLibreModule).then(configureTileflowMapLibreModule).catch((error) => {
     mapLibrePromise = void 0;
     throw error;
   });
@@ -337,6 +339,32 @@ function throwCollected(errors, message) {
   if (errors.length > 1) throw new AggregateError(errors, message);
 }
 
+// src/scope.ts
+function createTileflowResourceScope() {
+  const cleanups = [];
+  let disposed = false;
+  const scope = {
+    add(cleanup) {
+      if (disposed) runTileflowCleanups([cleanup]);
+      else cleanups.push(cleanup);
+    },
+    child() {
+      const child = createTileflowResourceScope();
+      scope.add(() => child.dispose());
+      return child;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      runTileflowCleanups(cleanups.splice(0).reverse());
+    },
+    get disposed() {
+      return disposed;
+    }
+  };
+  return scope;
+}
+
 // src/views.ts
 function tileflowAnnotationViewContext(target, state) {
   const { annotation } = target;
@@ -547,13 +575,20 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
   let stateBridgeDiagnostic;
   let rendererBridgeDiagnostic;
   let viewBridgeDiagnostic;
+  let dataBridgeDiagnostic;
+  let interactionStartDiagnostic;
   let annotationDiagnostics = [];
   let semanticDiagnostics = [];
   let reportedDeclarativeDiagnosticKeys = /* @__PURE__ */ new Set();
   let imageSize = null;
   let managedImage = null;
   let imageReadinessRun = 0;
+  let themeMapIdentity;
+  let appliedTheme;
+  let failedTheme;
+  let validThemeSelection;
   let map = null;
+  let mounted;
   let scene;
   let themeController;
   let appearanceBinding;
@@ -644,6 +679,13 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
     }));
     const mapName = runtimeSource.map;
     const manifestUrl = runtimeSource.manifestUrl ?? defaultTileflowManifestUrl;
+    const runtimeMapIdentity = `${manifestUrl}\0${mapName}`;
+    if (themeMapIdentity !== runtimeMapIdentity) {
+      themeMapIdentity = runtimeMapIdentity;
+      appliedTheme = void 0;
+      failedTheme = void 0;
+      validThemeSelection = void 0;
+    }
     const preparedAnnotations = memo(
       "annotations",
       [annotations],
@@ -679,37 +721,75 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
     const manifestMap = currentManifest.state === "ready" ? currentManifest.map : null;
     const themeBlendKey = themeBlend ? JSON.stringify(themeBlend.themes) : void 0;
     const blendThemeName = themeBlend ? nearestTileflowBlendTheme(themeBlend) : void 0;
+    const resolveSelection = (selection) => {
+      if (!manifestMap) {
+        return {
+          error: false,
+          name: selection && selection !== "system" ? selection : void 0
+        };
+      }
+      try {
+        if (themeBlendKey) {
+          for (const name of JSON.parse(themeBlendKey)) {
+            resolveTileflowRuntimeTheme(manifestMap, name);
+          }
+        }
+        return {
+          error: false,
+          name: resolveTileflowRuntimeTheme(
+            manifestMap,
+            selection,
+            systemColorScheme,
+            themeBlendKey ? void 0 : timeOfDay
+          ).name
+        };
+      } catch (cause) {
+        return { cause, error: true, name: void 0 };
+      }
+    };
     const themeResolution = memo(
       "themeResolution",
-      [blendThemeName, manifestMap, systemColorScheme, theme, themeBlendKey, timeOfDay],
+      [
+        blendThemeName,
+        manifestMap,
+        (blendThemeName ?? theme) === "system" ? systemColorScheme : void 0,
+        theme,
+        themeBlendKey,
+        timeOfDay
+      ],
+      () => resolveSelection(blendThemeName ?? theme)
+    );
+    const themeRequestFailed = failedTheme !== void 0 && failedTheme.selection === theme && failedTheme.theme === themeResolution.name;
+    const themeChoice = memo(
+      "themeChoice",
+      [
+        failedTheme,
+        manifestMap,
+        systemColorScheme,
+        themeBlendKey,
+        themeRequestFailed,
+        themeResolution,
+        timeOfDay,
+        validThemeSelection
+      ],
       () => {
-        const selection = blendThemeName ?? theme;
-        if (!manifestMap) {
-          return {
-            error: false,
-            name: selection && selection !== "system" ? selection : void 0
-          };
+        if (blendThemeName) return { resolution: themeResolution, selection: theme };
+        if (themeRequestFailed && failedTheme) {
+          const { fallback } = failedTheme;
+          const resolution = resolveSelection(fallback.selection);
+          return resolution.error || resolution.name === failedTheme.theme ? { resolution: { error: false, name: fallback.theme }, selection: fallback.theme } : { resolution, selection: fallback.selection };
         }
-        try {
-          if (themeBlendKey) {
-            for (const name of JSON.parse(themeBlendKey)) {
-              resolveTileflowRuntimeTheme(manifestMap, name);
-            }
-          }
+        if (themeResolution.error) {
           return {
-            error: false,
-            name: resolveTileflowRuntimeTheme(
-              manifestMap,
-              selection,
-              systemColorScheme,
-              themeBlendKey ? void 0 : timeOfDay
-            ).name
+            resolution: resolveSelection(validThemeSelection),
+            selection: validThemeSelection
           };
-        } catch (cause) {
-          return { cause, error: true, name: void 0 };
         }
+        return { resolution: themeResolution, selection: theme };
       }
     );
+    const themeSelection = themeChoice.selection;
+    const shownThemeResolution = themeChoice.resolution;
     const manifestView = resolveTileflowRuntimeView({ manifestMap });
     const manifestCenter = stable(
       "manifestCenter",
@@ -750,15 +830,18 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
         preparedInteractionState
       })
     );
-    const runtimeStyle = memo(
+    const runtimeStyle = stable(
       "runtimeStyle",
-      [isImageMode, manifestMap, runtimeSource, systemColorScheme, themeResolution],
-      () => isImageMode || themeResolution.error ? null : resolveTileflowRuntimeStyle({
-        colorScheme: systemColorScheme,
-        manifestMap,
-        source: runtimeSource,
-        theme: themeResolution.name
-      })
+      memo(
+        "runtimeStyle",
+        [isImageMode, manifestMap, runtimeSource, systemColorScheme, shownThemeResolution],
+        () => isImageMode || shownThemeResolution.error ? null : resolveTileflowRuntimeStyle({
+          colorScheme: systemColorScheme,
+          manifestMap,
+          source: runtimeSource,
+          theme: shownThemeResolution.name
+        })
+      )
     );
     const blendResolution = memo(
       "blendResolution",
@@ -808,7 +891,7 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
         zoom: resolvedZoom
       }) : void 0)
     );
-    const runtimeResolutionState = currentManifest.state !== "ready" ? currentManifest.state === "error" ? "error" : "loading" : themeResolution.error ? "error" : isImageMode ? runtimeImageUrl ? "idle" : options.imageUrl === void 0 && imageSize === null ? "loading" : "error" : runtimeStyle ? "idle" : "error";
+    const runtimeResolutionState = currentManifest.state !== "ready" ? currentManifest.state === "error" ? "error" : "loading" : themeResolution.error || themeRequestFailed ? "error" : isImageMode ? runtimeImageUrl ? "idle" : options.imageUrl === void 0 && imageSize === null ? "loading" : "error" : runtimeStyle ? "idle" : "error";
     return {
       annotationClusters,
       blendResolution,
@@ -834,10 +917,14 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
       resolvedInteractive,
       resolvedPitch,
       resolvedZoom,
-      runtimeMapIdentity: `${manifestUrl}\0${runtimeSource.map}`,
+      runtimeMapIdentity,
       runtimeResolutionState,
       runtimeSource,
+      manifestReady: manifestMap !== null,
       runtimeStyle,
+      shownThemeResolution,
+      themeRequestFailed,
+      themeSelection,
       themeBlendHold: themeBlend?.hold === true,
       themeBlendKey,
       themeBlendPosition: themeBlend?.position,
@@ -964,8 +1051,14 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
         image.removeEventListener("error", fail);
       };
     });
-    effect("systemColorScheme", [options.theme], () => {
-      if (options.theme !== "system") return;
+    if (d.manifestReady && !d.themeResolution.error && !d.themeRequestFailed) {
+      validThemeSelection = options.theme;
+    }
+    if (failedTheme && (failedTheme.selection !== options.theme || failedTheme.theme !== d.themeResolution.name)) {
+      failedTheme = void 0;
+    }
+    effect("systemColorScheme", [d.themeSelection], () => {
+      if (d.themeSelection !== "system") return;
       systemColorScheme = getTileflowSystemColorScheme();
       invalidate();
       return subscribeTileflowSystemColorScheme((scheme) => {
@@ -1040,7 +1133,25 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
       "reconcileData",
       [d.annotationClusters, d.dataOverlays, d.dataSources, d.preparedAnnotations],
       () => {
-        dataRuntime?.reconcile(dataInput);
+        if (dataRuntime) reconcileData(dataRuntime);
+      }
+    );
+    effect(
+      "restartInteractions",
+      [
+        d.annotationClusters,
+        d.dataOverlays,
+        d.dataSources,
+        d.hasMarkerRenderer,
+        d.hasPopupRenderer,
+        d.hasTooltipRenderer,
+        d.preparedAnnotations,
+        d.preparedInteractions
+      ],
+      () => {
+        if (interactionStartDiagnostic && mounted && !mounted.scope.disposed) {
+          attachInteractions(mounted);
+        }
       }
     );
     effect("reconcileInteractions", [d.preparedInteractions], () => {
@@ -1100,23 +1211,13 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
       ],
       () => d.isImageMode ? void 0 : mountMap()
     );
-    effect("theme", [d.runtimeStyle, d.themeBlendKey, d.themeResolution.error], () => {
+    effect("theme", [d.runtimeStyle, d.themeBlendKey], () => {
       const controller = themeController;
       if (!controller || d.themeBlendKey) return;
-      if (d.themeResolution.error) {
-        void controller.setTheme(controller.getCurrent());
-        return;
-      }
       if (!d.runtimeStyle || controller.getCurrent() === d.runtimeStyle && !controller.getBlend()) {
         return;
       }
-      activeRuntimeResource = d.runtimeStyle;
-      invalidate();
-      void controller.setTheme(d.runtimeStyle, { transition: options.themeTransition }).then((result) => {
-        if (result.status === "failed") {
-          reportError("theme", result.error ?? new Error("The map theme could not be changed."));
-        }
-      });
+      requestTheme(controller, d.runtimeStyle, d.themeSelection);
     });
     const themeResolutionCause = d.themeResolution.error ? d.themeResolution.cause : void 0;
     effect("themeError", [d.themeResolution.error, themeResolutionCause], () => {
@@ -1172,6 +1273,19 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
     }
     invalidate();
   }
+  function reconcileData(runtime) {
+    try {
+      dataBridgeDiagnostic = void 0;
+      runtime.reconcile(dataInput);
+    } catch (error) {
+      console.error("Failed to reconcile Tileflow data layers", error);
+      dataBridgeDiagnostic = createOverlayFailureDiagnostic(
+        "Tileflow data layers could not be reconciled."
+      );
+      reportDiagnostic(dataBridgeDiagnostic);
+    }
+    invalidate();
+  }
   function reconcileInteractions(runtime, bindings) {
     try {
       semanticBridgeDiagnostic = void 0;
@@ -1203,10 +1317,10 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
     if (!initialRuntimeStyle) return void 0;
     activeRuntimeResource = initialRuntimeStyle;
     captureState = "loading";
-    let cancelled = false;
-    let disposeMap;
-    const { mapOptions, resolvedInteractive } = current;
+    const scope = createTileflowResourceScope();
+    const { mapOptions } = current;
     const resourceLifetime = new AbortController();
+    scope.add(() => resourceLifetime.abort());
     const session = createTileflowSessionController({ source: sessionSource });
     const resourceTransform = createTileflowTransformRequest({
       getAnalytics: () => current.resolvedAnalytics,
@@ -1228,337 +1342,400 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
         return prepared;
       })
     ]).then(([maplibregl, prepared]) => {
-      if (cancelled || destroyed) return;
-      const setupCleanups = [];
-      let setupDisposed = false;
-      const registerCleanup = (cleanup) => setupCleanups.push(cleanup);
-      disposeMap = () => {
-        if (setupDisposed) return;
-        setupDisposed = true;
-        try {
-          runTileflowCleanups([...setupCleanups].reverse());
-        } finally {
-          map = null;
-          interactionRuntime = void 0;
-          semanticRuntime = void 0;
-          interactionCoordinator = void 0;
-          annotationDiagnostics = [];
-          annotationRenderTargets = [];
-          annotationBridgeDiagnostic = void 0;
-          semanticDiagnostics = [];
-          semanticRenderTargets = [];
-          semanticBridgeDiagnostic = void 0;
-          stateBridgeDiagnostic = void 0;
-          rendererBridgeDiagnostic = void 0;
-          invalidate();
-        }
-      };
-      const sessionStarter = createTileflowSessionStarter({
-        getSessionId: () => session.sessionId,
-        sessionId: session.sessionId,
-        source: sessionSource
-      });
-      const fairUseNotice = attachTileflowFairUseNotice(container);
-      registerCleanup(() => fairUseNotice.dispose());
-      registerTileflowContourProtocol({ addProtocol: maplibregl.addProtocol });
-      registerTileflowPathGroundProtocol({ addProtocol: maplibregl.addProtocol });
-      registerTileflowPmtilesProtocol({ addProtocol: maplibregl.addProtocol });
-      const worldRequestBridge = registerTileflowWorldRequestBridge({
-        addProtocol: maplibregl.addProtocol,
-        onNotice: fairUseNotice.update
-      });
-      registerCleanup(() => worldRequestBridge.dispose());
-      const contourRequestScope = createTileflowContourRequestScope({
-        transformRequest: (url, resourceType) => transformRequest(
-          url,
-          resourceType
-        )
-      });
-      registerCleanup(() => contourRequestScope.dispose());
-      const transformRequest = createTileflowTransformRequest({
-        contourRequestScope,
-        getAnalytics: () => current.resolvedAnalytics,
-        sessionController: session,
-        sessionId: session.sessionId,
-        transformRequest: mapOptions?.transformRequest ?? void 0,
-        worldRequestBridge
-      });
-      const mapLibreMap = new maplibregl.Map({
-        ...mapOptions,
-        canvasContextAttributes: tileflowCanvasContextAttributes(
-          mapOptions?.canvasContextAttributes
-        ),
-        container,
-        style: prepared.style,
-        bearing: current.resolvedBearing,
-        center: current.resolvedCenter,
-        pitch: current.resolvedPitch,
-        zoom: current.resolvedZoom,
-        interactive: resolvedInteractive,
-        attributionControl: mapOptions?.attributionControl ?? { compact: true },
-        // Tileflow's compiled styles are validated when they are built.
-        validateStyle: mapOptions?.validateStyle ?? false,
-        maxPitch: mapOptions?.maxPitch ?? tileflowMaxPitch,
-        transformRequest
-      });
-      map = mapLibreMap;
-      registerCleanup(() => mapLibreMap.remove());
-      registerCleanup(attachTileflowAtmosphere(mapLibreMap));
-      registerCleanup(attachTileflowBranding(mapLibreMap));
-      registerCleanup(attachTileflowNotices(mapLibreMap));
-      registerCleanup(attachTileflowNauticalLights(mapLibreMap));
-      registerCleanup(attachTileflowLabelPlacement(mapLibreMap));
-      registerCleanup(attachTileflowHorizonQueries(mapLibreMap));
-      const controller = initialRuntimeStyle.theme === void 0 ? void 0 : createTileflowThemeController({
-        initial: prepared.family ? prepared : initialRuntimeStyle,
-        initialStyle: prepared.style,
-        styleLoadOptions,
-        map: mapLibreMap,
-        onTransition(transition) {
-          options.onThemeChange?.(transition);
-          themeTransitionState = transition.phase === "preloading" || transition.phase === "applying" ? "loading" : transition.phase === "error" ? "error" : "idle";
-          invalidate();
-        }
-      });
-      if (controller) {
-        themeController = controller;
-        registerCleanup(() => {
-          controller.dispose();
-          if (themeController === controller) themeController = void 0;
-        });
-        const appearance = createTileflowAppearanceBinding({
-          controller,
-          // CSS variables in `colors` are read where the map sits.
-          element: container,
-          map: mapLibreMap,
-          onError: (error, part) => reportError(part, error)
-        });
-        appearanceBinding = appearance;
-        registerCleanup(() => {
-          appearance.dispose();
-          if (appearanceBinding === appearance) appearanceBinding = void 0;
-        });
-        appearance.update(
-          { colors: options.colors, emphasis: options.emphasis },
-          { transition: { duration: 0 } }
-        );
+      if (scope.disposed || destroyed) return;
+      createMap(scope, maplibregl, prepared, { initialRuntimeStyle, session, styleLoadOptions });
+    }).catch((error) => {
+      const cancelled = scope.disposed || destroyed;
+      try {
+        scope.dispose();
+      } catch (cleanupError) {
+        console.error("Failed to release a Tileflow map that could not start", cleanupError);
       }
-      const mapScene = attachTileflowMap3D({
-        map: mapLibreMap,
-        ...controller ? { controller } : {},
-        vegetation: options.vegetation,
-        viewMode: options.viewMode ?? "3d",
-        load: () => import("@tileflow/core/3d"),
-        onError: (error) => reportError("scene", error),
-        // Direct tile readers use HTTP, not MapLibre's custom World protocol.
-        transformRequest: createTileflowTransformRequest({
-          getAnalytics: () => current.resolvedAnalytics,
-          sessionController: session,
-          sessionId: session.sessionId,
-          transformRequest: (url) => mapOptions?.transformRequest?.(
-            url,
-            "Tile"
-          )
-        })
-      });
-      scene = mapScene;
-      registerCleanup(() => {
-        mapScene.dispose();
-        if (scene === mapScene) scene = void 0;
-      });
-      const coordinator = createTileflowMapLibreInteractionCoordinator({
-        ...controlledInteractionOwnership ? { interactionState: coordinatedInteractionState } : { defaultInteractionState: coordinatedInteractionState },
-        onInteractionStateChange(state) {
-          if (!controlledInteractionOwnership) coordinatedInteractionState = state;
-          options.onInteractionStateChange?.(state);
+      if (cancelled) return;
+      reportError("runtime", error);
+      captureState = "error";
+      invalidate();
+    });
+    return () => scope.dispose();
+  }
+  function createMap(scope, maplibregl, prepared, context) {
+    const { initialRuntimeStyle, session, styleLoadOptions } = context;
+    const { mapOptions, resolvedInteractive } = current;
+    scope.add(() => {
+      map = null;
+      mounted = void 0;
+      appliedTheme = void 0;
+      invalidate();
+    });
+    const sessionStarter = createTileflowSessionStarter({
+      getSessionId: () => session.sessionId,
+      sessionId: session.sessionId,
+      source: sessionSource
+    });
+    const fairUseNotice = attachTileflowFairUseNotice(container);
+    scope.add(() => fairUseNotice.dispose());
+    registerTileflowContourProtocol({ addProtocol: maplibregl.addProtocol });
+    registerTileflowPathGroundProtocol({ addProtocol: maplibregl.addProtocol });
+    registerTileflowPmtilesProtocol({ addProtocol: maplibregl.addProtocol });
+    const worldRequestBridge = registerTileflowWorldRequestBridge({
+      addProtocol: maplibregl.addProtocol,
+      onNotice: fairUseNotice.update
+    });
+    scope.add(() => worldRequestBridge.dispose());
+    const contourRequestScope = createTileflowContourRequestScope({
+      transformRequest: (url, resourceType) => transformRequest(
+        url,
+        resourceType
+      )
+    });
+    scope.add(() => contourRequestScope.dispose());
+    const transformRequest = createTileflowTransformRequest({
+      contourRequestScope,
+      getAnalytics: () => current.resolvedAnalytics,
+      sessionController: session,
+      sessionId: session.sessionId,
+      transformRequest: mapOptions?.transformRequest ?? void 0,
+      worldRequestBridge
+    });
+    const mapLibreMap = new maplibregl.Map({
+      ...mapOptions,
+      canvasContextAttributes: tileflowCanvasContextAttributes(mapOptions?.canvasContextAttributes),
+      container,
+      style: prepared.style,
+      bearing: current.resolvedBearing,
+      center: current.resolvedCenter,
+      pitch: current.resolvedPitch,
+      zoom: current.resolvedZoom,
+      interactive: resolvedInteractive,
+      attributionControl: mapOptions?.attributionControl ?? { compact: true },
+      // Tileflow's compiled styles are validated when they are built.
+      validateStyle: mapOptions?.validateStyle ?? false,
+      maxPitch: mapOptions?.maxPitch ?? tileflowMaxPitch,
+      transformRequest
+    });
+    map = mapLibreMap;
+    let removedByMapLibre = false;
+    scope.add(() => {
+      if (!removedByMapLibre) mapLibreMap.remove();
+    });
+    const handleRemove = () => {
+      removedByMapLibre = true;
+      if (map !== mapLibreMap) return;
+      map = null;
+      queueMicrotask(teardown);
+    };
+    mapLibreMap.on("remove", handleRemove);
+    scope.add(() => mapLibreMap.off("remove", handleRemove));
+    scope.add(attachTileflowAtmosphere(mapLibreMap));
+    scope.add(attachTileflowBranding(mapLibreMap));
+    scope.add(attachTileflowNotices(mapLibreMap));
+    scope.add(attachTileflowNauticalLights(mapLibreMap));
+    scope.add(attachTileflowLabelPlacement(mapLibreMap));
+    scope.add(attachTileflowHorizonQueries(mapLibreMap));
+    let lifecycle;
+    const controller = initialRuntimeStyle.theme === void 0 ? void 0 : createTileflowThemeController({
+      initial: prepared.family ? prepared : initialRuntimeStyle,
+      initialStyle: prepared.style,
+      styleLoadOptions,
+      map: mapLibreMap,
+      onTransition(transition) {
+        if (themeController !== controller) return;
+        if (transition.phase === "ready") {
+          lifecycle?.invalidate("loading");
+          mapLibreMap.triggerRepaint();
         }
+        options.onThemeChange?.(transition);
+        themeTransitionState = transition.phase === "preloading" || transition.phase === "applying" ? "loading" : transition.phase === "error" ? "error" : "idle";
+        invalidate();
+      }
+    });
+    if (controller) {
+      themeController = controller;
+      scope.add(() => {
+        controller.dispose();
+        if (themeController === controller) themeController = void 0;
       });
-      interactionCoordinator = coordinator;
-      registerCleanup(() => coordinator.dispose());
-      const createOverlay = ({
-        container: overlayContainer,
-        kind
-      }) => wrapMapLibrePositioned(
-        new maplibregl.Popup({
-          closeButton: false,
-          closeOnClick: false,
-          closeOnMove: false,
-          focusAfterOpen: false,
-          offset: kind === "popup" ? 24 : 18
-        }).setDOMContent(overlayContainer)
-      );
-      const annotationRuntime = createTileflowMapLibreDomRuntime({
-        createMarker({ annotation, element }) {
-          const marker = new maplibregl.Marker({ element });
-          element.title = annotationTitles.get(annotation.id) ?? annotation.ariaLabel;
-          return wrapMapLibrePositioned(marker);
-        },
-        createOverlay,
-        customMarker: current.hasMarkerRenderer,
-        customPopup: current.hasPopupRenderer,
-        customTooltip: current.hasTooltipRenderer,
-        document: container.ownerDocument,
-        interactionState: coordinator.getInteractionState(),
+      appliedTheme = { selection: current.themeSelection, theme: initialRuntimeStyle.theme };
+      const appearance = createTileflowAppearanceBinding({
+        controller,
+        // CSS variables in `colors` are read where the map sits.
+        element: container,
         map: mapLibreMap,
-        onInteractionStateChange: coordinator.requestInteractionState,
-        onDiagnostic: reportDiagnostic,
-        updateMarker(_marker, { annotation, element }) {
-          element.title = annotationTitles.get(annotation.id) ?? annotation.ariaLabel;
+        onError: (error, part) => {
+          if (appearanceBinding === appearance) reportError(part, error);
         }
       });
-      interactionRuntime = annotationRuntime;
-      registerCleanup(() => annotationRuntime.dispose());
-      const mapDataRuntime = createTileflowMapLibreDataRuntime({
-        createMarker: ({ element }) => wrapMapLibrePositioned(new maplibregl.Marker({ element })),
-        document: container.ownerDocument,
-        map: mapLibreMap,
-        onDiagnostic: reportDiagnostic,
-        onInteractionEvent(event) {
-          options.onInteractionEvent?.(event);
-        },
-        setHiddenAnnotations: annotationRuntime.setHiddenAnnotations
+      appearanceBinding = appearance;
+      scope.add(() => {
+        appearance.dispose();
+        if (appearanceBinding === appearance) appearanceBinding = void 0;
       });
-      dataRuntime = mapDataRuntime;
-      registerCleanup(() => {
-        mapDataRuntime.dispose();
-        if (dataRuntime === mapDataRuntime) dataRuntime = void 0;
-      });
-      const featureRuntime = createTileflowMapLibreSemanticDomRuntime({
-        cancelFrame: (frame) => browserWindow.cancelAnimationFrame(frame),
-        createOverlay,
-        customPopup: current.hasPopupRenderer,
-        customTooltip: current.hasTooltipRenderer,
-        document: container.ownerDocument,
-        interactionState: coordinator.getInteractionState(),
-        map: mapLibreMap,
-        onDiagnostic: reportDiagnostic,
-        onInteractionStateChange: coordinator.requestInteractionState,
-        poiMap: createTileflowMapLibrePoiMap(mapLibreMap),
-        requestFrame: (callback) => browserWindow.requestAnimationFrame(() => callback())
-      });
-      semanticRuntime = featureRuntime;
-      registerCleanup(() => featureRuntime.dispose());
-      registerCleanup(coordinator.attach("annotation", annotationRuntime));
-      registerCleanup(coordinator.attach("semantic", featureRuntime));
-      registerCleanup(
-        annotationRuntime.subscribeEvents((event) => options.onInteractionEvent?.(event))
-      );
-      registerCleanup(
-        annotationRuntime.subscribeDiagnostics((diagnostics) => {
-          annotationDiagnostics = diagnostics;
-          invalidate();
-        })
-      );
-      registerCleanup(
-        annotationRuntime.subscribeRenderTargets((targets) => {
-          annotationRenderTargets = targets;
-          invalidate();
-        })
-      );
-      registerCleanup(
-        featureRuntime.subscribeEvents((event) => {
-          if (event.target.kind === "annotation") return;
-          options.onInteractionEvent?.({ ...event, target: event.target });
-        })
-      );
-      registerCleanup(
-        featureRuntime.subscribeDiagnostics((diagnostics) => {
-          semanticDiagnostics = diagnostics;
-          invalidate();
-        })
-      );
-      registerCleanup(
-        featureRuntime.subscribeRenderTargets((targets) => {
-          semanticRenderTargets = targets;
-          invalidate();
-        })
+      appearance.update(
+        { colors: options.colors, emphasis: options.emphasis },
+        { transition: { duration: 0 } }
       );
-      annotationDiagnostics = annotationRuntime.getDiagnostics();
-      annotationRenderTargets = annotationRuntime.getRenderTargets();
-      semanticDiagnostics = featureRuntime.getDiagnostics();
-      semanticRenderTargets = featureRuntime.getRenderTargets();
-      reconcileAnnotations(annotationRuntime, annotationsForRuntime);
-      mapDataRuntime.reconcile(dataInput);
-      const initialInteractions = current.preparedInteractions;
-      if (initialInteractions.ok)
-        reconcileInteractions(featureRuntime, initialInteractions.bindings);
-      const navigation = createTileflowNavigationControlBinding({
-        createControl: (controlOptions) => new maplibregl.NavigationControl(controlOptions),
-        map: mapLibreMap
-      });
-      navigationBinding = navigation;
-      registerCleanup(() => {
-        navigation.dispose();
-        if (navigationBinding === navigation) navigationBinding = void 0;
-      });
-      navigation.update(current.resolvedInteractive ? options.navigationControl : false);
-      const initialFit = current.cameraFit;
-      appliedCameraFitKey = initialFit.key;
-      if (initialFit.error) reportError("camera", new Error(initialFit.error));
-      if (initialFit.fit) fitCameraTo(mapLibreMap, initialFit.fit, 0);
-      const resizeObserver = new ResizeObserver(() => mapLibreMap.resize());
-      registerCleanup(() => resizeObserver.disconnect());
-      resizeObserver.observe(container);
-      const lifecycle = attachTileflowMapLifecycle({
-        getSession: () => {
-          const analyticsForLoad = current.resolvedAnalytics;
-          return {
-            analytics: analyticsForLoad,
-            styleId: analyticsForLoad?.styleId ?? (typeof initialRuntimeStyle.style === "string" ? initialRuntimeStyle.style : current.mapName)
-          };
-        },
-        map: mapLibreMap,
-        onLoad: (loadedMap) => {
-          settleReady({ map: loadedMap });
-          options.onLoad?.(loadedMap);
-        },
-        scheduler: {
-          cancelFrame: (frame) => browserWindow.cancelAnimationFrame(frame),
-          requestFrame: (callback) => browserWindow.requestAnimationFrame(callback)
-        },
-        sessionStarter,
-        setState: (state) => {
-          captureState = state;
-          invalidate();
-        },
-        subscribe: (subscribedMap, event, listener) => {
-          const subscription = subscribedMap.on(event, listener);
-          return () => subscription.unsubscribe();
-        }
-      });
-      registerCleanup(() => lifecycle.dispose());
-      const latestRuntimeStyle = current.runtimeStyle;
-      const latestBlend = current.blendResolution.styles && current.themeBlendPosition !== void 0 ? {
-        hold: current.themeBlendHold,
-        position: current.themeBlendPosition,
-        themes: current.blendResolution.styles
-      } : null;
-      if (controller && latestBlend) {
-        if (latestRuntimeStyle) activeRuntimeResource = latestRuntimeStyle;
-        void controller.setBlend(latestBlend, { transition: options.themeTransition });
-      } else if (controller && latestRuntimeStyle && latestRuntimeStyle !== initialRuntimeStyle) {
-        activeRuntimeResource = latestRuntimeStyle;
-        void controller.setTheme(latestRuntimeStyle, { transition: options.themeTransition });
+    }
+    const mapScene = attachTileflowMap3D({
+      map: mapLibreMap,
+      ...controller ? { controller } : {},
+      vegetation: options.vegetation,
+      viewMode: options.viewMode ?? "3d",
+      load: () => import("@tileflow/core/3d"),
+      onError: (error) => {
+        if (scene === mapScene) reportError("scene", error);
+      },
+      // Direct tile readers use HTTP, not MapLibre's custom World protocol.
+      transformRequest: createTileflowTransformRequest({
+        getAnalytics: () => current.resolvedAnalytics,
+        sessionController: session,
+        sessionId: session.sessionId,
+        transformRequest: (url) => mapOptions?.transformRequest?.(
+          url,
+          "Tile"
+        )
+      })
+    });
+    scene = mapScene;
+    scope.add(() => {
+      mapScene.dispose();
+      if (scene === mapScene) scene = void 0;
+    });
+    mounted = { map: mapLibreMap, maplibregl, scope };
+    attachInteractions(mounted);
+    const navigation = createTileflowNavigationControlBinding({
+      createControl: (controlOptions) => new maplibregl.NavigationControl(controlOptions),
+      map: mapLibreMap
+    });
+    navigationBinding = navigation;
+    scope.add(() => {
+      navigation.dispose();
+      if (navigationBinding === navigation) navigationBinding = void 0;
+    });
+    navigation.update(current.resolvedInteractive ? options.navigationControl : false);
+    const initialFit = current.cameraFit;
+    appliedCameraFitKey = initialFit.key;
+    if (initialFit.error) reportError("camera", new Error(initialFit.error));
+    if (initialFit.fit) fitCameraTo(mapLibreMap, initialFit.fit, 0);
+    const resizeObserver = new ResizeObserver(() => mapLibreMap.resize());
+    scope.add(() => resizeObserver.disconnect());
+    resizeObserver.observe(container);
+    const mapLifecycle = attachTileflowMapLifecycle({
+      getSession: () => {
+        const analyticsForLoad = current.resolvedAnalytics;
+        return {
+          analytics: analyticsForLoad,
+          styleId: analyticsForLoad?.styleId ?? (typeof initialRuntimeStyle.style === "string" ? initialRuntimeStyle.style : current.mapName)
+        };
+      },
+      map: mapLibreMap,
+      onLoad: (loadedMap) => {
+        settleReady({ map: loadedMap });
+        options.onLoad?.(loadedMap);
+      },
+      scheduler: {
+        cancelFrame: (frame) => browserWindow.cancelAnimationFrame(frame),
+        requestFrame: (callback) => browserWindow.requestAnimationFrame(callback)
+      },
+      sessionStarter,
+      setState: (state) => {
+        if (map !== mapLibreMap) return;
+        captureState = state;
+        invalidate();
+      },
+      subscribe: (subscribedMap, event, listener) => {
+        const subscription = subscribedMap.on(event, listener);
+        return () => subscription.unsubscribe();
       }
+    });
+    lifecycle = mapLifecycle;
+    scope.add(() => {
+      lifecycle = void 0;
+      mapLifecycle.dispose();
+    });
+    const latestRuntimeStyle = current.runtimeStyle;
+    const latestBlend = current.blendResolution.styles && current.themeBlendPosition !== void 0 ? {
+      hold: current.themeBlendHold,
+      position: current.themeBlendPosition,
+      themes: current.blendResolution.styles
+    } : null;
+    if (controller && latestBlend) {
+      if (latestRuntimeStyle) activeRuntimeResource = latestRuntimeStyle;
+      void controller.setBlend(latestBlend, { transition: options.themeTransition });
+    } else if (controller && latestRuntimeStyle && latestRuntimeStyle !== initialRuntimeStyle) {
+      requestTheme(controller, latestRuntimeStyle, current.themeSelection);
+    }
+    invalidate();
+  }
+  function attachInteractions(target) {
+    const { map: mapLibreMap, maplibregl } = target;
+    const scope = target.scope.child();
+    scope.add(() => {
+      interactionRuntime = void 0;
+      semanticRuntime = void 0;
+      interactionCoordinator = void 0;
+      dataRuntime = void 0;
+      annotationDiagnostics = [];
+      annotationRenderTargets = [];
+      annotationBridgeDiagnostic = void 0;
+      semanticDiagnostics = [];
+      semanticRenderTargets = [];
+      semanticBridgeDiagnostic = void 0;
+      stateBridgeDiagnostic = void 0;
+      rendererBridgeDiagnostic = void 0;
+      dataBridgeDiagnostic = void 0;
       invalidate();
-    }).catch((error) => {
-      resourceLifetime.abort();
+    });
+    try {
+      startInteractions(scope, mapLibreMap, maplibregl);
+      interactionStartDiagnostic = void 0;
+    } catch (error) {
+      console.error("Failed to start Tileflow map interactions", error);
       try {
-        disposeMap?.();
+        scope.dispose();
       } catch (cleanupError) {
-        reportError("runtime", cleanupError);
+        console.error("Failed to release Tileflow map interactions", cleanupError);
       }
-      if (!cancelled && !destroyed) {
-        reportError("runtime", error);
-        captureState = "error";
+      interactionStartDiagnostic = createOverlayFailureDiagnostic(
+        "Tileflow map interactions could not start."
+      );
+      reportDiagnostic(interactionStartDiagnostic);
+    }
+    invalidate();
+  }
+  function startInteractions(scope, mapLibreMap, maplibregl) {
+    const coordinator = createTileflowMapLibreInteractionCoordinator({
+      ...controlledInteractionOwnership ? { interactionState: coordinatedInteractionState } : { defaultInteractionState: coordinatedInteractionState },
+      onInteractionStateChange(state) {
+        if (interactionCoordinator !== coordinator) return;
+        if (!controlledInteractionOwnership) coordinatedInteractionState = state;
+        options.onInteractionStateChange?.(state);
+      }
+    });
+    interactionCoordinator = coordinator;
+    scope.add(() => coordinator.dispose());
+    const createOverlay = ({
+      container: overlayContainer,
+      kind
+    }) => wrapMapLibrePositioned(
+      new maplibregl.Popup({
+        closeButton: false,
+        closeOnClick: false,
+        closeOnMove: false,
+        focusAfterOpen: false,
+        offset: kind === "popup" ? 24 : 18
+      }).setDOMContent(overlayContainer)
+    );
+    const annotationRuntime = createTileflowMapLibreDomRuntime({
+      createMarker({ annotation, element }) {
+        const marker = new maplibregl.Marker({ element });
+        element.title = annotationTitles.get(annotation.id) ?? annotation.ariaLabel;
+        return wrapMapLibrePositioned(marker);
+      },
+      createOverlay,
+      customMarker: current.hasMarkerRenderer,
+      customPopup: current.hasPopupRenderer,
+      customTooltip: current.hasTooltipRenderer,
+      document: container.ownerDocument,
+      interactionState: coordinator.getInteractionState(),
+      map: mapLibreMap,
+      onInteractionStateChange: coordinator.requestInteractionState,
+      onDiagnostic: reportDiagnostic,
+      updateMarker(_marker, { annotation, element }) {
+        element.title = annotationTitles.get(annotation.id) ?? annotation.ariaLabel;
+      }
+    });
+    interactionRuntime = annotationRuntime;
+    scope.add(() => annotationRuntime.dispose());
+    const mapDataRuntime = createTileflowMapLibreDataRuntime({
+      createMarker: ({ element }) => wrapMapLibrePositioned(new maplibregl.Marker({ element })),
+      document: container.ownerDocument,
+      map: mapLibreMap,
+      onDiagnostic: reportDiagnostic,
+      onInteractionEvent(event) {
+        options.onInteractionEvent?.(event);
+      },
+      setHiddenAnnotations: annotationRuntime.setHiddenAnnotations
+    });
+    dataRuntime = mapDataRuntime;
+    scope.add(() => mapDataRuntime.dispose());
+    const featureRuntime = createTileflowMapLibreSemanticDomRuntime({
+      cancelFrame: (frame) => browserWindow.cancelAnimationFrame(frame),
+      createOverlay,
+      customPopup: current.hasPopupRenderer,
+      customTooltip: current.hasTooltipRenderer,
+      document: container.ownerDocument,
+      interactionState: coordinator.getInteractionState(),
+      map: mapLibreMap,
+      onDiagnostic: reportDiagnostic,
+      onInteractionStateChange: coordinator.requestInteractionState,
+      poiMap: createTileflowMapLibrePoiMap(mapLibreMap),
+      requestFrame: (callback) => browserWindow.requestAnimationFrame(() => callback())
+    });
+    semanticRuntime = featureRuntime;
+    scope.add(() => featureRuntime.dispose());
+    scope.add(coordinator.attach("annotation", annotationRuntime));
+    scope.add(coordinator.attach("semantic", featureRuntime));
+    scope.add(annotationRuntime.subscribeEvents((event) => options.onInteractionEvent?.(event)));
+    scope.add(
+      annotationRuntime.subscribeDiagnostics((diagnostics) => {
+        annotationDiagnostics = diagnostics;
+        invalidate();
+      })
+    );
+    scope.add(
+      annotationRuntime.subscribeRenderTargets((targets) => {
+        annotationRenderTargets = targets;
         invalidate();
+      })
+    );
+    scope.add(
+      featureRuntime.subscribeEvents((event) => {
+        if (event.target.kind === "annotation") return;
+        options.onInteractionEvent?.({ ...event, target: event.target });
+      })
+    );
+    scope.add(
+      featureRuntime.subscribeDiagnostics((diagnostics) => {
+        semanticDiagnostics = diagnostics;
+        invalidate();
+      })
+    );
+    scope.add(
+      featureRuntime.subscribeRenderTargets((targets) => {
+        semanticRenderTargets = targets;
+        invalidate();
+      })
+    );
+    annotationDiagnostics = annotationRuntime.getDiagnostics();
+    annotationRenderTargets = annotationRuntime.getRenderTargets();
+    semanticDiagnostics = featureRuntime.getDiagnostics();
+    semanticRenderTargets = featureRuntime.getRenderTargets();
+    reconcileAnnotations(annotationRuntime, annotationsForRuntime);
+    reconcileData(mapDataRuntime);
+    const initialInteractions = current.preparedInteractions;
+    if (initialInteractions.ok) reconcileInteractions(featureRuntime, initialInteractions.bindings);
+  }
+  function requestTheme(controller, style, selection) {
+    const requested = { selection: options.theme, theme: current.themeResolution.name };
+    const standingIn = current.themeRequestFailed || current.themeResolution.error;
+    activeRuntimeResource = style;
+    invalidate();
+    void controller.setTheme(style, { transition: options.themeTransition }).then((result) => {
+      if (destroyed || themeController !== controller) return;
+      if (result.status === "applied") {
+        appliedTheme = { selection, theme: result.theme };
+        if (!standingIn) failedTheme = void 0;
+      } else if (result.status === "failed") {
+        const shown = controller.getCurrent().theme;
+        const applied = appliedTheme ?? { selection: shown, theme: shown };
+        failedTheme = {
+          ...requested,
+          fallback: standingIn ? { selection: applied.theme, theme: applied.theme } : applied
+        };
+        reportError("theme", result.error ?? new Error("The map theme could not be changed."));
       }
+      invalidate();
     });
-    return () => {
-      cancelled = true;
-      resourceLifetime.abort();
-      disposeMap?.();
-    };
   }
   function computeStatus() {
     const d = current;
@@ -1569,6 +1746,8 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
       ...stateBridgeDiagnostic ? [stateBridgeDiagnostic] : [],
       ...rendererBridgeDiagnostic ? [rendererBridgeDiagnostic] : [],
       ...viewBridgeDiagnostic ? [viewBridgeDiagnostic] : [],
+      ...dataBridgeDiagnostic ? [dataBridgeDiagnostic] : [],
+      ...interactionStartDiagnostic ? [interactionStartDiagnostic] : [],
       ...annotationDiagnostics,
       ...semanticDiagnostics
     ];
@@ -1585,7 +1764,7 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
     return {
       diagnostics,
       readiness: parts.includes("error") ? "error" : parts.every((part) => part === "idle") ? "idle" : "loading",
-      theme: d.themeResolution.name,
+      theme: d.shownThemeResolution.name,
       imageUrl: d.isImageMode ? d.runtimeImageUrl : void 0
     };
   }
@@ -1619,27 +1798,31 @@ function createTileflowMap(container, initialOptions, createOptions = {}) {
     }
     reconcile();
   }
+  function teardown() {
+    if (destroyed) return;
+    destroyed = true;
+    settleReady({ error: new DOMException("The Tileflow map was destroyed.", "AbortError") });
+    try {
+      runTileflowCleanups([() => viewHost.dispose(), () => reconciler.dispose()]);
+    } catch (error) {
+      console.error("Failed to release a Tileflow map", error);
+    } finally {
+      map = null;
+      mounted = void 0;
+      if (statusElement) {
+        for (const attribute of statusAttributes) statusElement.removeAttribute(attribute);
+      }
+    }
+  }
   reconcile();
   return {
     container,
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      settleReady({ error: new DOMException("The Tileflow map was destroyed.", "AbortError") });
-      try {
-        viewHost.dispose();
-        reconciler.dispose();
-      } finally {
-        if (statusElement) {
-          for (const attribute of statusAttributes) statusElement.removeAttribute(attribute);
-        }
-      }
-    },
+    destroy: teardown,
     getInteractionState: () => interactionCoordinator?.getInteractionState() ?? coordinatedInteractionState,
     getMap: () => map,
     getRenderTargets: () => lastRenderTargets,
     getStatus: () => lastStatus ?? computeStatus(),
-    getThemeController: () => themeController ?? null,
+    getThemeController: () => map ? themeController ?? null : null,
     ready,
     setAnnotations: (annotations) => update({ annotations }),
     setBounds: (bounds, fitBoundsOptions) => update(fitBoundsOptions === void 0 ? { bounds } : { bounds, fitBoundsOptions }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dom",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "license": "Apache-2.0",
   "description": "Mount a Tileflow map in any DOM element, without a framework.",
   "type": "module",
@@ -40,8 +40,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.50 <0.1.0-beta.0",
-    "@tileflow/interactions": ">=0.1.0-alpha.9 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.51 <0.1.0-beta.0",
+    "@tileflow/interactions": ">=0.1.0-alpha.10 <0.1.0-beta.0"
   },
   "peerDependencies": {
     "maplibre-gl": ">=6.4.1 <7"