@sjvair/monitor-map 3.6.3 → 4.0.0

package/src/lib/collocation-sites/collocations-map-integration.svelte.ts

@@ -25,6 +25,11 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 	icons: CollocationIconManager = new CollocationIconManager(monitorsManager);
 	tooltipManager: TooltipManager = new TooltipManager();
 
+	/** The option only applies while monitors are shown with PM2.5. */
+	get available(): boolean {
+		return monitorsMapIntegration.enabled && monitorsManager.pollutant === "pm25";
+	}
+
 	features: Array<CollocationSiteMapFeature> = $derived.by(() => {
 		if (
 			!monitorsManager.meta ||
@@ -93,8 +98,10 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 				mapManager.setDataSource(this.referenceId, features);
 			});
 
+			// Remove the layer while the option is unavailable (Ozone or Pollutant = None); restore
+			// it when it becomes available again if the user still has it checked.
 			$effect(() => {
-				if (monitorsManager.pollutant === "o3") {
+				if (!this.available) {
 					untrack(() => this.remove());
 				} else if (untrack(() => this.enabled)) {
 					untrack(() => this.apply());
@@ -104,6 +111,10 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 	}
 
 	apply() {
+		if (!this.available) {
+			this.remove();
+			return;
+		}
 		if (!mapManager.map) return;
 
 		if (!this.tooltipManager.has(this.referenceId)) {
@@ -114,6 +125,11 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 
 		super.apply();
 	}
+
+	remove() {
+		this.tooltipManager.disable();
+		super.remove();
+	}
 }
 
 export const collocationSitesMapIntegration = new CollocationSitesMapIntegration();

package/src/lib/ev-stations/ev-stations-map-integration.svelte.ts

@@ -26,7 +26,7 @@ class EvStationsMapIntegration
 	implements EvStationsClusterContext
 {
 	referenceId: string = "ev-stations";
-	enabled: boolean = $state(true);
+	enabled: boolean = $state(false);
 	clustered: boolean = $state(true);
 
 	icons: EvStationIconManager = new EvStationIconManager();
@@ -35,8 +35,8 @@ class EvStationsMapIntegration
 	private currentPopup: Popup | null = null;
 
 	displayOptions = $derived.by(() => ({
-		lvl2: new MapDisplayOption("Level 2", false, this.icons.get("ev-station-lvl2")!),
-		lvl3: new MapDisplayOption("Level 3", false, this.icons.get("ev-station-lvl3")!)
+		lvl2: new MapDisplayOption("Level 2", true, this.icons.get("ev-station-lvl2")!),
+		lvl3: new MapDisplayOption("Level 3", true, this.icons.get("ev-station-lvl3")!)
 	}));
 
 	features: Array<EvStationMapFeature> = $derived.by(() => {
@@ -115,23 +115,38 @@ class EvStationsMapIntegration
 		super();
 
 		$effect.root(() => {
-			// Lazy-fetch level data when integration is enabled and level is toggled on
+			// Lazy-fetch level data only once the integration is enabled and the level is on
 			$effect(() => {
-				if (this.displayOptions.lvl2.value && evStationsManager.lvl2Stations === undefined) {
+				if (
+					this.enabled &&
+					this.displayOptions.lvl2.value &&
+					evStationsManager.lvl2Stations === undefined
+				) {
 					evStationsManager.loadLvl2Stations();
 				}
 			});
 
 			$effect(() => {
-				if (this.displayOptions.lvl3.value && evStationsManager.lvl3Stations === undefined) {
+				if (
+					this.enabled &&
+					this.displayOptions.lvl3.value &&
+					evStationsManager.lvl3Stations === undefined
+				) {
 					evStationsManager.loadLvl3Stations();
 				}
 			});
 
+			// Every effect below early-returns while disabled so a data refresh can't re-add the layer.
+			// `enabled` is read untracked: the base class's own effect already applies/removes on
+			// enabled changes, and tracking it here would apply twice. The guard comes after each
+			// effect's tracked reads so its dependencies are always collected; returning before
+			// reading anything would leave the effect permanently dead.
+
 			// Push filter changes to the unclustered layer
 			$effect(() => {
 				const filter = this.filters;
 				if (!mapManager.map || this.clustered) return;
+				if (!untrack(() => this.enabled)) return;
 				if (mapManager.map.getLayer(this.referenceId)) {
 					mapManager.map.setFilter(this.referenceId, filter);
 				}
@@ -141,6 +156,7 @@ class EvStationsMapIntegration
 			$effect(() => {
 				const features = this.features;
 				if (!mapManager.map || this.clustered) return;
+				if (!untrack(() => this.enabled)) return;
 				mapManager.setDataSource(this.referenceId, features);
 			});
 
@@ -148,6 +164,7 @@ class EvStationsMapIntegration
 			$effect(() => {
 				void this.featuresByLevel;
 				if (!mapManager.map || !this.clustered) return;
+				if (!untrack(() => this.enabled)) return;
 				this.renderer.syncFeatures();
 			});
 
@@ -156,6 +173,7 @@ class EvStationsMapIntegration
 				void this.clustered;
 				const hasFeatures = Object.keys(this.featuresByLevel).length > 0;
 				if (!untrack(() => mapManager.map) || !hasFeatures) return;
+				if (!untrack(() => this.enabled)) return;
 				untrack(() => this.apply());
 			});
 		});
@@ -171,6 +189,7 @@ class EvStationsMapIntegration
 			this.tooltipManager.disable();
 			this.renderer.remove();
 			this.icons.loadIcons().then(() => {
+				if (mapManager.styleLoading) return;
 				this.renderer.apply(this.handleStationClick);
 				this.tooltipManager.enable();
 			});
@@ -180,6 +199,7 @@ class EvStationsMapIntegration
 			clickManager.unregister([this.referenceId]);
 			super.apply();
 			this.icons.loadIcons().then(() => {
+				if (mapManager.styleLoading) return;
 				clickManager.register([this.referenceId], this.handleStationClick);
 				this.tooltipManager.enable();
 			});

package/src/lib/hms/hms-fire-icon-manager.ts

@@ -1,9 +1,10 @@
 import { asDataURI, fireIcon } from "$lib/map/icons";
 import { MapIconManager } from "$lib/map/integrations/map-icon-manager";
+import type { LegendCategory } from "$lib/legend/legend-data";
 
-type FRPTier = "sm" | "md" | "lg" | "xl" | "xxl";
+export type FRPTier = "sm" | "md" | "lg" | "xl" | "xxl";
 
-const FRP_TIERS: Record<FRPTier, { color: string; size: number }> = {
+export const FRP_TIERS: Record<FRPTier, { color: string; size: number }> = {
 	sm: { color: "#FFD700", size: 20 },
 	md: { color: "#FF8C00", size: 24 },
 	lg: { color: "#FF4500", size: 28 },
@@ -11,6 +12,19 @@ const FRP_TIERS: Record<FRPTier, { color: string; size: number }> = {
 	xxl: { color: "#8B0000", size: 36 }
 };
 
+const FRP_TIER_LABELS: Record<FRPTier, string> = {
+	sm: "<10",
+	md: "10-49",
+	lg: "50-149",
+	xl: "150-349",
+	xxl: "≥350"
+};
+
+/** Fire legend blocks (MW), in tier order, using the same colors as the map icons. */
+export const FIRE_LEGEND_CATEGORIES: Array<LegendCategory> = (
+	Object.keys(FRP_TIERS) as Array<FRPTier>
+).map((tier) => ({ color: FRP_TIERS[tier].color, label: FRP_TIER_LABELS[tier] }));
+
 export function getTierIconId(frp: number): string {
 	if (frp < 10) return "hms-fire-sm";
 	if (frp < 50) return "hms-fire-md";

package/src/lib/hms/hms-fire-map-integration.svelte.ts

@@ -89,7 +89,7 @@ class HMSFireMapIntegration extends MapIconLayerIntegration<FireProperties> {
 		this.icons
 			.loadIcons()
 			.then(() => {
-				if (!mapManager.map || !this.enabled) return;
+				if (!mapManager.map || !this.enabled || mapManager.styleLoading) return;
 				this.remove();
 				this.zoomedIn = mapManager.map.getZoom() >= ZOOM_THRESHOLD;
 				mapManager.map.addSource(this.referenceId, this.mapSource);

package/src/lib/hms/hms-smoke-map-integration.svelte.ts

@@ -4,6 +4,16 @@ import type { HMSSmokeGeoJSON } from "@sjvair/sdk/hms";
 import { mapManager } from "$lib/map/map.svelte";
 import { MapGeoJSONIntegration } from "$lib/map/integrations/map-geojson-integration.svelte";
 import { hmsManager } from "./hms.svelte";
+import type { SmokeDensityStyle } from "$lib/legend/legend-data";
+
+/** Smoke fill styles, shared by the map layer and the legend so they can't drift apart. */
+export const SMOKE_DENSITY_STYLES = {
+	light: { label: "Light", color: "#bfc8c3", opacity: 0.2 },
+	medium: { label: "Medium", color: "#757b78", opacity: 0.3 },
+	heavy: { label: "Heavy", color: "#333634", opacity: 0.4 }
+} satisfies Record<string, SmokeDensityStyle>;
+
+export const SMOKE_LEGEND: Array<SmokeDensityStyle> = Object.values(SMOKE_DENSITY_STYLES);
 
 type SmokeProperties = {
 	id: string;
@@ -36,20 +46,28 @@ class HMSSmokeMapIntegration extends MapGeoJSONIntegration<SmokeProperties> {
 					"match",
 					["get", "density"],
 					"light",
-					"#bfc8c3",
+					SMOKE_DENSITY_STYLES.light.color,
+					"medium",
+					SMOKE_DENSITY_STYLES.medium.color,
+					SMOKE_DENSITY_STYLES.heavy.color
+				],
+				"fill-opacity": [
+					"match",
+					["get", "density"],
+					"light",
+					SMOKE_DENSITY_STYLES.light.opacity,
 					"medium",
-					"#757b78",
-					"#333634"
+					SMOKE_DENSITY_STYLES.medium.opacity,
+					SMOKE_DENSITY_STYLES.heavy.opacity
 				],
-				"fill-opacity": ["match", ["get", "density"], "light", 0.2, "medium", 0.3, 0.4],
 				"fill-outline-color": [
 					"match",
 					["get", "density"],
 					"light",
-					"#bfc8c3",
+					SMOKE_DENSITY_STYLES.light.color,
 					"medium",
-					"#757b78",
-					"#333634"
+					SMOKE_DENSITY_STYLES.medium.color,
+					SMOKE_DENSITY_STYLES.heavy.color
 				]
 			}
 		};

package/src/lib/index.ts

@@ -59,7 +59,6 @@ export { hmsSmokeMapIntegration } from "./hms/hms-smoke-map-integration.svelte";
 // Components
 export { default as Map } from "./map/Map.svelte";
 export { default as MapShell, type MapShellProps } from "./map/MapShell.svelte";
-export { default as Menu } from "./map/Menu.svelte";
 export {
 	default as LoadScreen,
 	loadScreenState,
@@ -67,12 +66,37 @@ export {
 	disable as disableLoadScreen
 } from "./LoadScreen.svelte";
 export type { LoadScreenState } from "./LoadScreen.svelte";
-export { default as MonitorsDisplayOptions } from "./monitors/components/MonitorsDisplayOptions.svelte";
-export { default as EvStationsDisplayOptions } from "./ev-stations/components/EvStationsDisplayOptions.svelte";
-export { default as MapLayersDisplayOptions } from "./components/MapLayersDisplayOptions.svelte";
-export { default as MapStyleDisplayOptions } from "./map/MapStyleDisplayOptions.svelte";
-export { default as ToggleSwitch } from "./components/ToggleSwitch.svelte";
-export { default as SegmentedControl } from "./components/SegmentedControl.svelte";
+
+// Options toolbar / panel (compose these inside MapShell's `menu` snippet)
+export { default as OptionsBar } from "./options/OptionsBar.svelte";
+export { default as OptionsGroup } from "./options/OptionsGroup.svelte";
+export { default as OptionsMenu } from "./options/OptionsMenu.svelte";
+export { default as CheckboxRow } from "./options/rows/CheckboxRow.svelte";
+export { default as RadioRow } from "./options/rows/RadioRow.svelte";
+export { default as SubmenuRow } from "./options/rows/SubmenuRow.svelte";
+export { default as GroupRow } from "./options/rows/GroupRow.svelte";
+export { default as MarkerIcon } from "./options/rows/MarkerIcon.svelte";
+export { default as PollutantMenu } from "./options/menus/PollutantMenu.svelte";
+export { default as MonitorsMenu } from "./options/menus/MonitorsMenu.svelte";
+export { default as LayersMenu } from "./options/menus/LayersMenu.svelte";
+export { default as OverlaysMenu } from "./options/menus/OverlaysMenu.svelte";
+export { default as SettingsMenu } from "./options/menus/SettingsMenu.svelte";
+export { resetMapOptions } from "./options/reset-map-options";
+export { mapStyleState } from "./map/map-style-state.svelte.js";
+export type { MapStyleState } from "./map/map-style-state.svelte.js";
+
+// Legend
+export { default as Legend } from "./legend/Legend.svelte";
+export { default as LegendBar } from "./legend/LegendBar.svelte";
+export {
+	pollutantLegendSection,
+	fireSmokeLegendSections,
+	type LegendSection,
+	type LegendBarData,
+	type LegendCategory
+} from "./legend/legend-data";
+export { FIRE_LEGEND_CATEGORIES } from "./hms/hms-fire-icon-manager";
+export { SMOKE_LEGEND } from "./hms/hms-smoke-map-integration.svelte";
 
 // Integration base classes (extend these to add custom map features)
 export { MapIntegration } from "./map/integrations/map-integration.svelte";

package/src/lib/legend/Legend.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+	import { ChevronDownIcon, InfoIcon } from "@lucide/svelte";
+	import LegendBar from "./LegendBar.svelte";
+	import type { LegendSection } from "./legend-data";
+
+	let { sections }: { sections: Array<LegendSection> } = $props();
+
+	// Independent of which sections are active, so toggling a layer doesn't reset it.
+	let collapsed = $state(false);
+</script>
+
+{#if sections.length}
+	<div class="pointer-events-auto w-84 max-w-[calc(100vw-2rem)] rounded-md bg-white shadow">
+		<button
+			type="button"
+			class="flex w-full cursor-pointer items-center gap-2 px-4 py-2 font-semibold"
+			aria-expanded={!collapsed}
+			onclick={() => (collapsed = !collapsed)}
+		>
+			<InfoIcon size={18} class="text-gray-500" />
+			<span class="flex-1 text-left">Legend</span>
+			<ChevronDownIcon size={18} class="transition-transform {collapsed ? '-rotate-90' : ''}" />
+		</button>
+		{#if !collapsed}
+			<div class="flex flex-col gap-3 border-t border-gray-200 px-4 py-3">
+				{#each sections as section (section.id)}
+					<div>
+						<p class="mb-2 text-center text-sm font-semibold">
+							{section.title}
+							{#if section.unit}
+								<span class="text-xs font-normal text-gray-500">({section.unit})</span>
+							{/if}
+						</p>
+						<LegendBar bar={section.bar} />
+					</div>
+				{/each}
+			</div>
+		{/if}
+	</div>
+{/if}

package/src/lib/legend/LegendBar.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+	import {
+		blocksBackground,
+		gradientBackground,
+		tickPosition,
+		type LegendBarData
+	} from "./legend-data";
+
+	let { bar }: { bar: LegendBarData } = $props();
+
+	const background = $derived(
+		bar.kind === "gradient"
+			? gradientBackground(bar.colors)
+			: blocksBackground(bar.categories.map((category) => category.color))
+	);
+
+	// Labels placed on exact stop positions: gradient ticks, or block breakpoints.
+	const positioned = $derived(bar.kind === "gradient" ? bar.ticks : (bar.breakpoints ?? null));
+</script>
+
+<div class="h-3 rounded" style:background></div>
+{#if positioned}
+	<div class="relative mt-1 h-4 text-xs">
+		{#each positioned as label, i (i)}
+			{@const isFirst = i === 0}
+			{@const isLast = i === positioned.length - 1}
+			<span
+				class={[
+					"absolute top-0 whitespace-nowrap",
+					isFirst && "left-0",
+					isLast && "right-0",
+					!isFirst && !isLast && "-translate-x-1/2"
+				]}
+				style:left={!isFirst && !isLast ? `${tickPosition(i, positioned.length)}%` : undefined}
+				>{label}</span
+			>
+		{/each}
+	</div>
+{:else if bar.kind === "blocks"}
+	<div class="mt-1 flex text-xs">
+		{#each bar.categories as category, i (i)}
+			<span class="min-w-0 flex-1 text-center break-words">{category.label ?? ""}</span>
+		{/each}
+	</div>
+{/if}

package/src/lib/legend/legend-data.ts

@@ -0,0 +1,101 @@
+import type { SJVAirEntryLevel } from "@sjvair/sdk";
+import { mix } from "color2k";
+import type { MonitorsPollutant } from "$lib/monitors/types";
+
+export interface LegendCategory {
+	color: string;
+	label?: string;
+}
+
+export type LegendBarData =
+	| { kind: "gradient"; colors: Array<string>; ticks: Array<string> }
+	| { kind: "blocks"; categories: Array<LegendCategory>; breakpoints?: Array<string> };
+
+export interface LegendSection {
+	id: string;
+	title: string;
+	unit?: string;
+	bar: LegendBarData;
+}
+
+export interface SmokeDensityStyle {
+	label: string;
+	color: string;
+	opacity: number;
+}
+
+const POLLUTANT_TITLES: Record<MonitorsPollutant, { title: string; unit: string }> = {
+	pm25: { title: "PM2.5", unit: "µg/m³" },
+	o3: { title: "Ozone", unit: "ppb" }
+};
+
+/**
+ * Pollutant legend built from the monitors meta levels — the same levels the map markers are
+ * colored by, so the two can never disagree. One tick per level, at that level's color stop.
+ */
+export function pollutantLegendSection(
+	pollutant: MonitorsPollutant,
+	levels: ReadonlyArray<Pick<SJVAirEntryLevel, "color" | "range">>
+): LegendSection | null {
+	if (levels.length === 0) return null;
+	return {
+		id: "pollutant",
+		...POLLUTANT_TITLES[pollutant],
+		bar: {
+			kind: "gradient",
+			colors: levels.map((level) => level.color),
+			ticks: levels.map((level) => String(Math.floor(level.range[0])))
+		}
+	};
+}
+
+/** Fire & Smoke share one toggle, so they render as two independent bars. */
+export function fireSmokeLegendSections(
+	fireTiers: ReadonlyArray<LegendCategory>,
+	smoke: ReadonlyArray<SmokeDensityStyle>
+): Array<LegendSection> {
+	return [
+		{ id: "fire", title: "Fire", unit: "MW", bar: { kind: "blocks", categories: [...fireTiers] } },
+		{
+			id: "smoke",
+			title: "Smoke Density",
+			bar: {
+				kind: "blocks",
+				categories: smoke.map(({ label, color, opacity }) => ({
+					label,
+					color: swatchOverWhite(color, opacity)
+				}))
+			}
+		}
+	];
+}
+
+/** Approximates how a translucent fill layer looks over a light basemap. */
+export function swatchOverWhite(color: string, opacity: number): string {
+	return mix("#ffffff", color, opacity);
+}
+
+export function gradientBackground(colors: ReadonlyArray<string>): string {
+	if (colors.length === 0) return "none";
+	if (colors.length === 1) return colors[0];
+	return `linear-gradient(to right, ${colors.join(", ")})`;
+}
+
+/** Hard-edged equal-width blocks: each color repeated at both edges of its own share. */
+export function blocksBackground(colors: ReadonlyArray<string>): string {
+	const count = colors.length;
+	if (count === 0) return "none";
+	const stops = colors.map(
+		(color, i) => `${color} ${percent(i / count)}, ${color} ${percent((i + 1) / count)}`
+	);
+	return `linear-gradient(to right, ${stops.join(", ")})`;
+}
+
+/** Percent position of the index-th of `count` evenly spaced labels. */
+export function tickPosition(index: number, count: number): number {
+	return count <= 1 ? 0 : (index / (count - 1)) * 100;
+}
+
+function percent(fraction: number): string {
+	return `${(fraction * 100).toFixed(2)}%`;
+}

package/src/lib/map/MapShell.svelte

@@ -19,8 +19,10 @@
 		 * trigger the escape-hatch full-page navigation below.
 		 */
 		knownRoutes?: Array<string>;
-		/** Rendered inside the display-options menu toggle */
+		/** Menus (OptionsGroup/OptionsMenu) rendered inside the options toolbar/panel */
 		menu?: Snippet;
+		/** Rendered last in the toolbar (wide) or beside the menu button (narrow) */
+		search?: Snippet;
 		/** Freeform absolutely-positioned content over the map (legend, search, etc.) */
 		overlays?: Snippet;
 		/** The routed detail panel content */
@@ -50,7 +52,7 @@
 <script lang="ts">
 	import LoadScreen, { disable as disableLoadScreen } from "$lib/LoadScreen.svelte";
 	import Map from "$lib/map/Map.svelte";
-	import Menu from "$lib/map/Menu.svelte";
+	import OptionsBar from "$lib/options/OptionsBar.svelte";
 	import { mapManager } from "$lib/map/map.svelte";
 	import { useMonitorMapRouter } from "$lib/router-context";
 
@@ -60,6 +62,7 @@
 		panelOpen,
 		knownRoutes = [],
 		menu,
+		search,
 		overlays,
 		children,
 		basePath: providedBasePath,
@@ -124,10 +127,8 @@
 	<div class="relative flex-1 overflow-hidden">
 		<Map {integrations} />
 		{@render overlays?.()}
-		{#if menu}
-			<div class="absolute top-4 left-4 z-10">
-				<Menu>{@render menu()}</Menu>
-			</div>
+		{#if menu || search}
+			<OptionsBar {search}>{@render menu?.()}</OptionsBar>
 		{/if}
 	</div>
 	<div

package/src/lib/map/basemap.ts

@@ -0,0 +1,24 @@
+/** The slices of MapTiler's MapStyleVariant / ReferenceMapStyle this module needs. */
+export interface StyleVariantLike {
+	getType(): string;
+}
+
+export interface ReferenceStyleLike<V extends StyleVariantLike> {
+	hasVariant(type: string): boolean;
+	getVariant(type: string): V;
+	getDefaultVariant(): V;
+}
+
+/**
+ * Variant to show after switching basemaps: the same variant type (e.g. "DARK") when the new
+ * basemap offers it, otherwise the new basemap's default.
+ */
+export function variantForStyle<V extends StyleVariantLike>(
+	style: ReferenceStyleLike<V>,
+	previous: StyleVariantLike | null
+): V {
+	if (previous && style.hasVariant(previous.getType())) {
+		return style.getVariant(previous.getType());
+	}
+	return style.getDefaultVariant();
+}

package/src/lib/map/integrations/map-geojson-integration.svelte.ts

@@ -11,7 +11,18 @@ export abstract class MapGeoJSONIntegration<
 	abstract mapSource: Parameters<MaptilerMap["addSource"]>[1];
 
 	remove() {
-		super.remove();
+		this.removeLayerAndSource();
+	}
+
+	/**
+	 * Removes only this integration's own layer and source. Non-virtual on purpose: `apply()`
+	 * paths call it to clear stale map state before re-adding, without triggering a subclass's
+	 * `remove()` override (which also tears down tooltips/click handlers that apply just set up).
+	 */
+	protected removeLayerAndSource(): void {
+		if (mapManager.map?.getLayer(this.referenceId)) {
+			mapManager.map.removeLayer(this.referenceId);
+		}
 		if (mapManager.map?.getSource(this.referenceId)) {
 			mapManager.map.removeSource(this.referenceId);
 		}
@@ -27,7 +38,9 @@ export abstract class MapIconLayerIntegration<
 		if (!mapManager.map) return;
 
 		this.icons.loadIcons().then(() => {
-			this.remove();
+			// A basemap change started while icons loaded; the refresh on "style.load" re-applies.
+			if (mapManager.styleLoading) return;
+			this.removeLayerAndSource();
 			mapManager.map?.addSource(this.referenceId, this.mapSource);
 			super.apply();
 		});

package/src/lib/map/integrations/map-layer-integration.svelte.ts

@@ -14,12 +14,15 @@ export abstract class MapLayerIntegration extends MapIntegration {
 		// Each integration manages its own lifecycle. Tracking both mapManager.map and
 		// this.enabled means apply/remove fire automatically on map load and on enabled
 		// changes. untrack on the call itself prevents reactive reads inside apply/remove
-		// from leaking back into this effect's dependency graph.
+		// from leaking back into this effect's dependency graph. While a new basemap style is
+		// loading nothing is applied or removed: the refresh on "style.load" does both.
 		$effect.root(() => {
 			$effect(() => {
-				if (mapManager.map && this.enabled) {
+				const enabled = this.enabled;
+				if (!mapManager.map || mapManager.styleLoading) return;
+				if (enabled) {
 					untrack(() => this.apply());
-				} else if (mapManager.map && !this.enabled) {
+				} else {
 					untrack(() => this.remove());
 				}
 			});

package/src/lib/map/map-style-state.svelte.ts

@@ -0,0 +1,42 @@
+import type { MapStyleVariant, ReferenceMapStyle } from "@maptiler/sdk";
+import { DefaultMapStyle, mapManager } from "./map.svelte";
+import { integrationsManager } from "./integrations/integrations-manager";
+import { variantForStyle } from "./basemap";
+
+/** Basemap + theme selection, shared so the Settings menu and Reset Map Options agree. */
+class MapStyleState {
+	referenceStyle: ReferenceMapStyle = $state.raw(DefaultMapStyle.getReferenceStyle());
+	variant: MapStyleVariant = $state.raw(DefaultMapStyle);
+	private applied: MapStyleVariant = DefaultMapStyle;
+
+	selectReferenceStyle(style: ReferenceMapStyle): void {
+		this.referenceStyle = style;
+		this.selectVariant(variantForStyle(style, this.variant));
+	}
+
+	selectVariant(variant: MapStyleVariant): void {
+		this.variant = variant;
+		this.apply();
+	}
+
+	reset(): void {
+		this.referenceStyle = DefaultMapStyle.getReferenceStyle();
+		this.selectVariant(DefaultMapStyle);
+	}
+
+	private apply(): void {
+		const map = mapManager.map;
+		if (!map || this.variant === this.applied) return;
+		this.applied = this.variant;
+		// setStyle wipes every custom source/layer; re-add enabled integrations once it loads.
+		map.once("style.load", () => {
+			mapManager.styleLoading = false;
+			integrationsManager.refresh();
+		});
+		mapManager.styleLoading = true;
+		map.setStyle(this.variant);
+	}
+}
+
+export const mapStyleState = new MapStyleState();
+export type { MapStyleState };

package/src/lib/map/map.svelte.ts

@@ -15,6 +15,12 @@ const excludeLayers = ["Sport", "Tourism", "Culture", "Shopping", "Food", "Trans
 
 class MapManager {
 	map: MaptilerMap | null = $state(null);
+	/**
+	 * True between `setStyle()` and the new style's "style.load". Plain (non-reactive) on purpose:
+	 * integrations skip touching the style while it's set, and the `integrationsManager.refresh()`
+	 * that runs on "style.load" applies/removes every integration afterwards.
+	 */
+	styleLoading: boolean = false;
 
 	setDataSource(sourceId: string, features: Array<Feature<Geometry, GeoJsonProperties>>): void {
 		const source = mapManager.map?.getSource(sourceId);