@sjvair/monitor-map 4.2.0 → 5.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Central California Asthma Collaborative (SJVAir)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,27 +1,43 @@
 # @sjvair/monitor-map
 
-SJVAir's interactive air quality monitor map, built with Svelte 5, Vite, and MapTiler
-SDK. It ships two ways:
+SJVAir's interactive air quality monitor map, built with Svelte 5, Vite and
+`@sjvair/map-sdk`. It ships two ways:
 
 - **A code-split widget** (`npm run build`), embedded via a `<div id="SJVAirMonitorMap">`
   in a Django template on sjvair.com.
 - **A component library** (`npm run build:lib`, published to npm as
-  `@sjvair/monitor-map`), imported by the `sjvair-mobile` Capacitor app and by other SJVAir
-  projects (e.g. `data-dashboard`) that want to embed the map or reuse its map-display
-  logic against their own data.
+  `@sjvair/monitor-map`), imported by the `sjvair-mobile` Capacitor app.
 
 ## Installation
 
 ```bash
-npm install @sjvair/monitor-map
+npm install @sjvair/monitor-map "@sjvair/sdk@npm:@jsr/sjvair__sdk@^5.0.0-beta.3"
+```
+
+`@sjvair/sdk` (5.x) is a peer dependency, so the host and the map share one copy and the host's
+`setOrigin` covers both. It is published on JSR, so the host's `.npmrc` needs
+`@jsr:registry=https://npm.jsr.io` (and `allow-remote=root` on npm 12). `@sjvair/map-sdk` and
+`@maptiler/sdk` are ordinary dependencies.
+
+The 5.0 betas are on the `next` dist-tag: `npm install @sjvair/monitor-map@next`.
+
+## Keys
+
+The library reads no keys. Call `configureMonitorMap` once at startup, before the map or the EV
+layer is used:
+
+```ts
+import { configureMonitorMap } from "@sjvair/monitor-map/core";
+
+configureMonitorMap({ maptilerKey: "...", nrelKey: "..." });
 ```
 
 ## Usage
 
 ### Full-page map, via `sv-router`
 
-The default integration path mounts a complete map (all integrations: monitors,
-collocation sites, wind, HMS smoke/fire, EV stations) as a route in a host app that
+The default integration path mounts a complete map (monitors, collocation sites,
+wind, HMS smoke/fire, EV stations) as a route in a host app that
 uses `sv-router`:
 
 ```ts
@@ -106,123 +122,35 @@ parameter: the panel shows the map's pollutant when the monitor reports it and o
 one it does report, saying so. An inactive monitor gets a panel with its past data and a
 note that it has no current readings; an unknown id gets "Monitor not found."
 
-### Embedding `MapShell` directly, with a reduced integration set
-
-`MonitorMapLayout` is an opinionated wrapper around the lower-level `MapShell`
-component: it wires up every integration, every manager, and the full options toolbar and
-legend. A host that only wants some of that — say, just the monitors integration, with no
-EV stations/wind/HMS — should compose `MapShell` directly instead:
-
-```svelte
-<script>
-	import {
-		MapShell,
-		MonitorsMenu,
-		OptionsGroup,
-		PollutantMenu,
-		monitorsMapIntegration,
-		monitorsManager
-	} from "@sjvair/monitor-map";
-
-	let failed = $state(false);
-	function load() {
-		failed = false;
-		monitorsManager.init().catch(() => (failed = true));
-	}
-	load();
-</script>
-
-<MapShell
-	integrations={[monitorsMapIntegration]}
-	ready={monitorsManager.initialized}
-	panelOpen={false}
-	routerEscapeHatch={false}
->
-	{#snippet menu()}
-		<OptionsGroup>
-			<PollutantMenu />
-			<MonitorsMenu />
-		</OptionsGroup>
-	{/snippet}
-	{#snippet loadError()}
-		{#if failed}
-			<button onclick={load}>Couldn't load air monitors. Try again</button>
-		{/if}
-	{/snippet}
-</MapShell>
-```
-
-The `menu` snippet renders inside the options toolbar; compose `OptionsGroup` with the
-exported menus (`PollutantMenu`, `MonitorsMenu`, `LayersMenu`, `OverlaysMenu`,
-`SettingsMenu`), or `OptionsMenu` with the row components for a custom data source. The
-optional `loadError` snippet renders on the load screen, under the logo, which stays up
-until `ready` is true; use it to show a failed initial load with a retry.
-
-See `src/lib/MonitorMapLayout.svelte` for the reference example of wiring a manager, an
-integration list, and menu/overlay content into `MapShell`.
-
-**`routerEscapeHatch`**: `MapShell` defaults to `routerEscapeHatch={true}`, which
-intercepts clicks and forces full-page navigation for links outside the map's own
-routes — correct for a full-page map, wrong for a map embedded alongside a host app's
-own navigation. A host with its own routing (like `data-dashboard`) **must** pass
-`routerEscapeHatch={false}`, which also skips `useMonitorMapRouter()` entirely, so no
-`provideMonitorMapRouter(...)` ancestor is required. Pass `basePath` if you need the
-escape-hatch's "known route" prefix without going through `provideMonitorMapRouter`.
-
-Mount at most one `MapShell` per app instance — its underlying map/load-screen/
-integration-registration state is module-level singleton state shared across the whole
-page.
-
-## Extending
-
-### Adding a new map feature
-
-Map features are a plugin system built on a few abstract base classes, exported from the
-package root:
-
-- `MapIntegration` — base apply/remove lifecycle
-- `MapLayerIntegration` — adds MapTiler layer management
-- `MapGeoJSONIntegration` — adds GeoJSON data-source management, plus a
-  `MapIconManager` for sprite icons (this is `src/lib/map/integrations/
-map-geojson-integration.svelte.ts`'s `MapIconLayerIntegration`, exported under this
-  name)
-
-Extend one of these rather than manipulating the MapTiler map instance directly. Look
-at `src/lib/monitors/monitors-map-integration.svelte.ts` or `src/lib/wind/wind.svelte.ts`
-as reference implementations.
-
-### Reusing the monitors map display with different data (`MonitorsDataSource`)
-
-`MonitorsMapIntegration` (and the icon-generation base class behind
-`MonitorsIconManager`/`CollocationIconManager`) don't hardcode the live `monitorsManager`
-singleton — they accept a `MonitorsDataSource` via their constructor:
-
-```ts
-export interface MonitorsDataSource {
-	readonly meta: MonitorsMeta | null;
-	readonly pollutant: "pm25" | "o3" | null;
-	readonly latest: XMap<string, MonitorLatestType<"pm25" | "o3">> | null;
-	readonly levels: Array<SJVAirEntryLevel> | null;
-}
-```
-
-`monitorsManager` (auto-polling, always-current readings) is the default when no data
-source is given, so existing consumers are unaffected. A host app that wants the same
-clustering/icon-rendering/filtering/tooltip logic driven by different data — for
-example, `data-dashboard`'s Monitors tab, which colors monitors by the **average of
-historical summary data over a selected date range** rather than a live reading —
-implements its own `MonitorsDataSource` (no polling, populated from
-`getMonitorSummariesDaily`/etc.) and constructs its own instance:
-
-```ts
-import { MonitorsMapIntegration, type MonitorsDataSource } from "@sjvair/monitor-map";
-
-const myDataSource: MonitorsDataSource = /* ... */;
-const monitorsMapIntegration = new MonitorsMapIntegration(myDataSource);
-```
-
-This reuses all of the existing map-rendering work instead of forking it — see
-`CLAUDE.md`'s "Monitor Data Flow" section for more detail.
+### Cancelling requests
+
+`monitorsManager.init()` takes `{ signal }` (an `AbortSignal`). Aborting rejects that call with
+the signal's reason. The run is shared: aborting your signal stops only your wait, and the run
+itself is cancelled only when every caller waiting on it has aborted. The panel, chart and
+subscription status cancel their own superseded requests; that work resolves quietly.
+
+## Migrating from 4.x
+
+- **Keys:** pass the MapTiler and NREL keys with `configureMonitorMap({ maptilerKey, nrelKey })`
+  (from `@sjvair/monitor-map` or `/core`). The library no longer reads them from the build
+  environment.
+- **`@sjvair/sdk` is a peer dependency** (`^5.0.0-beta.3` for the betas): install it in the host.
+  `@sjvair/map-sdk` and `@maptiler/sdk` are ordinary dependencies; add neither.
+- **Svelte `^5.57.0`:** the `svelte` peer range was `^5.0.0`.
+- **`meta` is SDK 5.0's:** `meta.levels` is gone; read `meta.scale`.
+- **`/routes`** is unchanged: `monitorMapRoutes` with the map at `/` and a monitor at
+  `/monitor/:id`, lazy as before.
+- **`/core`** keeps `provideMonitorMapRouter`, `useMonitorMapRouter`, `ROUTER_KEY`,
+  `MonitorMapRouterApi` and `monitorsManager` (`init(pollutant?, { autoUpdate?, signal? })`,
+  `initialized`, `meta`, `list`), and adds `configureMonitorMap` and `monitorMapConfig`.
+- **Tailwind:** add `@source "../node_modules/@sjvair/map-sdk/dist";` and
+  `@import "@sjvair/map-sdk/theme.css";` beside the existing monitor-map `@source`. The host
+  defines the theme tokens map-sdk needs (`--background` to `--radius`, plus `--popover` and
+  `--accent`).
+- **Removed exports:** everything from `.` except `monitorMapRoutes`, the router context,
+  `monitorsManager`, `configureMonitorMap` and `monitorMapConfig` (and their types). That includes
+  `MapShell`, the options menus, the integration classes, `MonitorsDataSource` and the other
+  managers.
 
 ## Development
 
@@ -237,11 +165,18 @@ npm run lint         # Prettier check + ESLint
 npm run format       # Auto-format with Prettier
 npm test             # Vitest (specs in tests/**)
 npm run test:bundle  # build:lib, then check the light entries keep maplibre off the eager path
+npm run map-sdk:pack # Optional: pack ../map-sdk into vendor/ to try an unreleased map-sdk
 ```
 
+`@sjvair/map-sdk` is the published npm version, pinned exactly in `package.json`. To try an
+unreleased map-sdk, run `npm run map-sdk:pack`, then `npm install` the tarball path it prints;
+do not commit that change.
+
 ## Publishing
 
 Publishing to npm (`@sjvair/monitor-map`) happens via GitHub Actions
 (`.github/workflows/release-package.yml`) whenever a GitHub Release is published (or the
 workflow is triggered manually). The workflow runs `npm test` and `npm run test:bundle`
-before publishing. Bump `version` in `package.json` before cutting the release.
+before publishing. Bump `version` in `package.json` before cutting the release. A version with a
+`-` (such as `5.0.0-beta.0`) is published to the `next` dist-tag, not `latest`; mark its GitHub
+Release as a pre-release.

package/dist/lib/MonitorDetailPanel.svelte

@@ -1,18 +1,17 @@
 <script lang="ts">
 	import { untrack, type ComponentProps } from "svelte";
-	import type { SJVAirEntryLevel } from "@sjvair/sdk";
 	import DataBox from "./components/DataBox.svelte";
 	import LoadError from "./LoadError.svelte";
 	import MonitorWidgetModal from "./monitors/components/MonitorWidgetModal.svelte";
 	import MonitorSubscriptionManager from "./monitors/components/MonitorSubscriptionManager.svelte";
 	import DataChart from "./data-chart/DataChart.svelte";
-	import { monitorsManager } from "./";
+	import { monitorsManager } from "./monitors/monitors.svelte.js";
 	import { MonitorDetailsState } from "./monitors/monitor-details.svelte";
-	import { choosePanelPollutant } from "./monitors/panel-pollutant";
+	import { choosePanelPollutant, PANEL_POLLUTANTS } from "./monitors/panel-pollutant";
 	import { useMonitorMapRouter } from "./router-context";
 	import { fetchTempByCoords } from "./weather";
 	import { Colors, valueToColor } from "./colors";
-	import { getCurrentLevel } from "./monitors/monitor-utils";
+	import { NEUTRAL_LEVEL_COLOR, readingDisplay, readingLevel } from "./levels";
 
 	type TempDataBox = Pick<ComponentProps<typeof DataBox>, "color" | "value">;
 
@@ -28,6 +27,10 @@
 	// current reading for the map's pollutant.
 	const details = new MonitorDetailsState();
 	const meta = $derived(monitorsManager.meta);
+	// The map's pollutant, when it is one the panel can show.
+	const mapPollutant = $derived(
+		PANEL_POLLUTANTS.find((p) => p === monitorsManager.pollutant) ?? null
+	);
 	// Shown only once the metadata is in too; labels and levels come from it.
 	const monitor = $derived(details.status === "ready" && meta ? details.monitor : null);
 
@@ -42,14 +45,15 @@
 	// Bumped whenever the map's readings are replaced, i.e. its 2-minute refresh ran. The data
 	// box follows it; the chart decides for itself whether its date range can have new entries.
 	let refreshTick = $state(0);
-	let seenLatest = untrack(() => monitorsManager.latest);
+	let seenLatest = untrack(() => monitorsManager.store.latest);
 
 	$effect(() => {
-		const latest = monitorsManager.latest;
-		// Null while a pollutant change is loading; wait for the readings that follow.
-		if (!latest || latest === seenLatest) return;
+		const latest = monitorsManager.store.latest;
+		// Empty before the first load and while a pollutant change is loading; wait for the
+		// readings that follow.
+		if (latest.size === 0 || latest === seenLatest) return;
 		// The first readings of a cold load arrive alongside this panel's own request.
-		const first = seenLatest === null;
+		const first = seenLatest.size === 0;
 		seenLatest = latest;
 		if (first) return;
 		untrack(() => {
@@ -59,14 +63,13 @@
 	});
 
 	const panel = $derived(
-		monitor && meta ? choosePanelPollutant(monitorsManager.pollutant, monitor, meta) : null
+		monitor && meta ? choosePanelPollutant(mapPollutant, monitor, meta) : null
 	);
 	const reading = $derived(
 		monitor && panel?.pollutant && panel.hasReading ? monitor.latest[panel.pollutant] : undefined
 	);
 	// Set when the panel shows a different pollutant than the map is coloring by.
 	const pollutantNote = $derived.by(() => {
-		const mapPollutant = monitorsManager.pollutant;
 		if (!meta || !panel?.pollutant || !panel.hasReading || !mapPollutant) return;
 		if (panel.pollutant === mapPollutant) return;
 		const shown = meta.entryType(panel.pollutant).label;
@@ -81,18 +84,15 @@
 		if (!monitor || !meta || !panel?.pollutant || !reading) return;
 
 		const entryType = meta.entryType(panel.pollutant);
-		const level: SJVAirEntryLevel | undefined = getCurrentLevel(
-			reading.value,
-			entryType.asIter.levels!
-		);
+		const level = readingLevel(reading.value, entryType.scale);
 
 		const updateDuration = meta.monitorType(monitor.type).expected_interval;
 
 		return {
-			color: level?.color ?? "",
+			color: level?.color ?? NEUTRAL_LEVEL_COLOR,
 			header: entryType.label,
 			subheading: `(${updateDuration} avg)`,
-			value: Math.round(parseInt(reading.value, 10)).toString()
+			value: readingDisplay(reading.value)
 		};
 	});
 
@@ -201,9 +201,12 @@
 				</div>
 			{/if}
 
-			<div class="tall:block hidden">
-				<MonitorWidgetModal monitorId={monitor.id} />
-			</div>
+			<!-- The widget shows current readings, and errors for an inactive monitor. -->
+			{#if panel.hasReading}
+				<div class="tall:block hidden">
+					<MonitorWidgetModal monitorId={monitor.id} />
+				</div>
+			{/if}
 			<!-- eslint-disable-next-line @typescript-eslint/no-explicit-any -->
 			{#if (globalThis as any).USER?.is_authenticated}
 				<MonitorSubscriptionManager monitorId={monitor.id} />

package/dist/lib/MonitorMapLayout.svelte

@@ -1,38 +1,44 @@
 <script lang="ts">
 	import type { Snippet } from "svelte";
-	import { onDestroy, untrack } from "svelte";
+	import { onDestroy, onMount, untrack } from "svelte";
 	import { searchParams } from "sv-router";
+	import {
+		collocationSitesPlugin,
+		hmsFirePlugin,
+		hmsSmokePlugin,
+		monitorsPlugin
+	} from "@sjvair/map-sdk";
+	import { windPlugin } from "./wind/wind-plugin.js";
+	import { evPlugin } from "./ev-stations/ev-plugin.svelte.js";
+	import { createEvStore } from "./ev-stations/ev-store.svelte.js";
+	import { stationPopups } from "./ev-stations/station-popup.svelte.js";
 	import MapShell from "./map/MapShell.svelte";
+	import { createLiveMap } from "./map/live-map.svelte.js";
+	import { syncPlugins } from "./map/sync-plugins.svelte.js";
+	import LoadError from "./LoadError.svelte";
+	import { retryMonitorsLoad } from "./monitors/retry-load.js";
+	import { monitorsManager } from "./monitors/monitors.svelte.js";
+	import { filteredMonitors } from "./monitors/filtered-source.svelte.js";
+	import Legend from "./legend/Legend.svelte";
+	import {
+		collocationSitesStore,
+		hmsFireStore,
+		hmsSmokeStore,
+		monitorsStore
+	} from "./stores.svelte.js";
 	import OptionsGroup from "./options/OptionsGroup.svelte";
 	import PollutantMenu from "./options/menus/PollutantMenu.svelte";
 	import MonitorsMenu from "./options/menus/MonitorsMenu.svelte";
 	import LayersMenu from "./options/menus/LayersMenu.svelte";
 	import OverlaysMenu from "./options/menus/OverlaysMenu.svelte";
 	import SettingsMenu from "./options/menus/SettingsMenu.svelte";
+	import { mapOptions } from "./options/map-options.svelte.js";
+	import { wantedPlugins } from "./options/plugin-order";
 	import {
 		applyPollutantSelection,
 		currentSelection,
 		parsePollutantParam
 	} from "./options/pollutant-param";
-	import LoadError from "./LoadError.svelte";
-	import Legend from "./legend/Legend.svelte";
-	import {
-		fireSmokeLegendSections,
-		pollutantLegendSection,
-		type LegendSection
-	} from "./legend/legend-data";
-	import { monitorsManager } from "./monitors/monitors.svelte";
-	import { monitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
-	import { windMapIntegration } from "./wind/wind.svelte";
-	import { baseLayerSeperator } from "./map/integrations/base-layer-seperator";
-	import type { SomeMapIntegration } from "./map/integrations/types";
-	import { collocationSitesManager } from "./collocation-sites/collocations.svelte";
-	import { collocationSitesMapIntegration } from "./collocation-sites/collocations-map-integration.svelte";
-	import { evStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
-	import { hmsManager } from "./hms/hms.svelte";
-	import { hmsFireMapIntegration } from "./hms/hms-fire-map-integration.svelte";
-	import { FIRE_LEGEND_CATEGORIES } from "./hms/hms-fire-icon-manager";
-	import { hmsSmokeMapIntegration, SMOKE_LEGEND } from "./hms/hms-smoke-map-integration.svelte";
 	import Search from "./search/Search.svelte";
 	import { useMonitorMapRouter } from "./router-context";
 
@@ -44,51 +50,105 @@
 
 	const { route, navigate, basePath } = useMonitorMapRouter();
 
-	const integrations: Array<SomeMapIntegration> = [
-		baseLayerSeperator,
-		collocationSitesMapIntegration,
-		windMapIntegration,
-		hmsSmokeMapIntegration,
-		hmsFireMapIntegration,
-		monitorsMapIntegration,
-		evStationsMapIntegration
-	];
+	// The map's state lives as long as this layout; MapView attaches the GL map when it mounts.
+	const map = createLiveMap();
 
-	const pollutantTargets = { manager: monitorsManager, integration: monitorsMapIntegration };
-
-	// "?pollutant=none" must disable monitors before the effects below first run, so the
-	// state->URL effect never sees enabled monitors and overwrites the param.
+	// "?pollutant=none" must turn monitors off before the effects below first run, so the
+	// state->URL effect never sees monitors on and overwrites the param.
 	if (parsePollutantParam(route.search.pollutant) === "none") {
-		monitorsMapIntegration.enabled = false;
+		mapOptions.monitorsOn = false;
 	}
 
 	// The load screen stays up until the monitors load, so a failure has to be shown on it.
-	let loadFailed = $state(false);
+	const loadFailed = $derived(monitorsStore.dataSource.status.state === "error");
 
 	function loadMonitors() {
-		loadFailed = false;
 		// A rejected init() can be retried: a later call starts a fresh run.
-		monitorsManager.init(route.search.pollutant).catch((error) => {
-			console.error(error);
-			loadFailed = true;
-		});
+		monitorsManager.init(route.search.pollutant).catch((error) => console.error(error));
 	}
 
 	loadMonitors();
-	// A previous instance of this layout stopped polling in onDestroy; init() is a no-op by now.
-	monitorsManager.resumeAutoUpdate();
-	collocationSitesManager.init();
-	hmsManager.init();
-	monitorsMapIntegration.onMonitorClick = (id: string) => {
-		navigate(`${basePath}/monitor/:id`, { params: { id } }).catch(console.error);
-	};
 
-	let panelOpen = $derived(route.pathname.startsWith(`${basePath}/monitor/`));
+	const panelOpen = $derived(route.pathname.startsWith(`${basePath}/monitor/`));
+	const selectedId = $derived(panelOpen ? route.params.id : undefined);
+
+	// The monitors the Monitors menu's filters let through; clusters are built from these.
+	const monitorsSource = filteredMonitors(monitorsStore.dataSource, mapOptions);
+
+	// EV chargers: each level is fetched the first time it is wanted. A failure shows in the legend
+	// with a retry.
+	const evStore = createEvStore();
+	const evPopups = stationPopups(map);
+	$effect(() => {
+		const wanted = wantedPlugins(mapOptions, monitorsManager.pollutant);
+		for (const [key, level] of [
+			["ev-l2", "lvl2"],
+			["ev-l3", "lvl3"]
+		] as const) {
+			if (wanted.has(key)) untrack(() => evStore.load(level)).catch(console.error);
+		}
+	});
+
+	// The options decide which plugins are on the map, in DRAW_ORDER. `clustered` is fixed when a
+	// plugin is built, so a change rebuilds it.
+	syncPlugins(
+		map,
+		() => wantedPlugins(mapOptions, monitorsManager.pollutant),
+		{
+			monitors: () => ({
+				plugin: monitorsPlugin({
+					id: "monitors",
+					source: monitorsSource,
+					layerLabel: "Monitors",
+					selectable: true,
+					selectedStyle: "enlarge",
+					clustered: mapOptions.clustered
+				}),
+				// A removed plugin forgets its mode and selection, so each add passes them again.
+				options: {
+					selectionMode: "single",
+					selection: selectedId ? { kind: "monitors", ids: [selectedId] } : null
+				}
+			}),
+			"ev-l2": () =>
+				evPlugin("lvl2", evStore.dataSource("lvl2"), { clustered: mapOptions.clustered }),
+			"ev-l3": () =>
+				evPlugin("lvl3", evStore.dataSource("lvl3"), { clustered: mapOptions.clustered })
+		},
+		() => mapOptions.clustered
+	);
+
+	// Wind, Fire & Smoke and collocation sites take no build-time option, so they sit in their own call
+	// without `deps`: a Marker Clusters change rebuilds only the monitors above. DRAW_ORDER still
+	// holds across the two calls because `syncPlugins` reads `map.plugins` (every plugin on the
+	// map, whichever call added it) to find the plugin to add before.
+	syncPlugins(map, () => wantedPlugins(mapOptions, monitorsManager.pollutant), {
+		wind: () => windPlugin(),
+		"hms-smoke": () =>
+			hmsSmokePlugin({
+				id: "hms-smoke",
+				source: hmsSmokeStore.dataSource,
+				layerLabel: "Smoke"
+			}),
+		"hms-fire": () =>
+			hmsFirePlugin({
+				id: "hms-fire",
+				source: hmsFireStore.groups,
+				hotspots: hmsFireStore.hotspots,
+				layerLabel: "Fires"
+			}),
+		"collocation-sites": () =>
+			collocationSitesPlugin({
+				id: "collocation-sites",
+				source: collocationSitesStore.dataSource,
+				layerLabel: "Collocation sites"
+			})
+	});
 
 	// Keep the Pollutant menu's selection (pm25 / o3 / none) and the "pollutant" URL param in
-	// sync, both directions. init() only seeds the pollutant on the manager's first-ever
+	// sync, both directions. init() only seeds the pollutant on the store's first-ever
 	// initialization; this effect applies a later "?pollutant=" change (e.g. navigating in from
-	// elsewhere) to an already-running map.
+	// elsewhere, or back/forward) to an already-running map.
 	$effect(() => {
 		const selection = parsePollutantParam(route.search.pollutant);
 		if (!monitorsManager.initialized || !selection) return;
@@ -96,47 +156,54 @@
 		// state here would make a UI-driven change re-trigger this effect before the effect below
 		// syncs the URL, so it would see the stale URL and revert the user's change.
 		untrack(() => {
-			if (
-				currentSelection(monitorsManager.pollutant, monitorsMapIntegration.enabled) !== selection
-			) {
-				applyPollutantSelection(selection, pollutantTargets);
+			if (currentSelection(monitorsManager.pollutant, mapOptions.monitorsOn) !== selection) {
+				applyPollutantSelection(selection, { manager: monitorsManager, options: mapOptions });
 			}
 		});
 	});
 
 	// ...and the reverse: reflect UI-driven changes back to the URL.
 	$effect(() => {
-		const selection = currentSelection(monitorsManager.pollutant, monitorsMapIntegration.enabled);
+		const selection = currentSelection(monitorsManager.pollutant, mapOptions.monitorsOn);
 		if (selection && searchParams.get("pollutant") !== selection) {
 			searchParams.set("pollutant", selection);
 		}
 	});
 
-	// Clear selected icon scale when the detail panel closes
-	$effect(() => {
-		if (panelOpen) return;
-		monitorsMapIntegration.selectedMonitorId = null;
+	onMount(() => {
+		// A failed load leaves its layer empty (map-sdk's legend shows the status); log it once.
+		for (const store of [hmsSmokeStore, hmsFireStore, collocationSitesStore]) {
+			store.init().catch(console.error);
+		}
+		// A previous instance of this layout paused polling in onDestroy; init() is a no-op by now.
+		monitorsManager.resumeAutoUpdate();
+		return map.on("featureclick", ({ pluginId, ref, lngLat }) => {
+			// A station clicked on the map or picked from the list: its popup.
+			if ((pluginId === "ev-l2" || pluginId === "ev-l3") && ref.kind === "feature") {
+				const station = evStore.station(ref.id);
+				if (station) evPopups.open(pluginId, station, lngLat);
+				return;
+			}
+			if (pluginId !== "monitors" || ref.kind !== "monitor") return;
+			navigate(`${basePath}/monitor/:id`, { params: { id: ref.id } }).catch(console.error);
+			map.easeTo({ center: lngLat, minZoom: 12 });
+		});
 	});
 
-	const legendSections: Array<LegendSection> = $derived.by(() => {
-		const sections: Array<LegendSection> = [];
-		if (monitorsMapIntegration.enabled && monitorsManager.pollutant && monitorsManager.levels) {
-			const pollutant = pollutantLegendSection(monitorsManager.pollutant, monitorsManager.levels);
-			if (pollutant) sections.push(pollutant);
-		}
-		if (hmsFireMapIntegration.enabled && hmsSmokeMapIntegration.enabled) {
-			sections.push(...fireSmokeLegendSections(FIRE_LEGEND_CATEGORIES, SMOKE_LEGEND));
-		}
-		return sections;
+	// The selected monitor follows the route: the open panel's monitor, none once it closes.
+	$effect(() => {
+		const id = selectedId;
+		map.setSelection("monitors", id ? { kind: "monitors", ids: [id] } : null);
 	});
 
 	onDestroy(() => {
-		monitorsManager.autoUpdate.stop();
+		monitorsManager.pauseAutoUpdate();
+		map.destroy();
 	});
 </script>
 
 <MapShell
-	{integrations}
+	{map}
 	ready={monitorsManager.initialized}
 	{panelOpen}
 	knownRoutes={[`${basePath}/monitor/`]}
@@ -144,7 +211,10 @@
 >
 	{#snippet loadError()}
 		{#if loadFailed}
-			<LoadError message="Couldn't load air monitors." onretry={loadMonitors} />
+			<LoadError
+				message="Couldn't load air monitors."
+				onretry={() => retryMonitorsLoad(monitorsStore, loadMonitors)}
+			/>
 		{/if}
 	{/snippet}
 	{#snippet menu()}
@@ -155,16 +225,16 @@
 		<OptionsGroup>
 			<LayersMenu />
 			<OverlaysMenu />
-			<SettingsMenu />
+			<SettingsMenu {map} />
 		</OptionsGroup>
 	{/snippet}
-	{#snippet search()}
-		<Search />
-	{/snippet}
 	{#snippet overlays()}
 		<div class="pointer-events-none absolute bottom-4 left-4 z-10">
-			<Legend sections={legendSections} />
+			<Legend {map} />
 		</div>
 	{/snippet}
+	{#snippet search()}
+		<Search {map} />
+	{/snippet}
 	{@render children()}
 </MapShell>