@sjvair/monitor-map 3.3.0 → 3.4.0

package/README.md

@@ -1,58 +1,167 @@
-# create-svelte
+# @sjvair/monitor-map
 
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
+SJVAir's interactive air quality monitor map, built with Svelte 5, Vite, and MapTiler
+SDK. It ships two ways:
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+- **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 `v3-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.
 
-## Creating a project
-
-If you're seeing this, you've probably already done this step. Congrats!
+## Installation
 
 ```bash
-# create a new project in the current directory
-npx sv create
-
-# create a new project in my-app
-npx sv create my-app
+npm install @sjvair/monitor-map
 ```
 
-## Developing
+## Usage
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+### Full-page map, via `sv-router`
 
-```bash
-npm run dev
+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
+uses `sv-router`:
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+```ts
+// router.ts
+import { createRouter } from "sv-router";
+import { monitorMapRoutes } from "@sjvair/monitor-map";
+
+export const { route, navigate, p, isActive, Router } = createRouter({
+	"/my-map": monitorMapRoutes
+	// ...the host app's own routes
+});
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+```svelte
+<!-- app root -->
+<script>
+	import { provideMonitorMapRouter } from "@sjvair/monitor-map";
+	import { route, navigate, p, isActive, Router } from "./router";
 
-## Building
+	provideMonitorMapRouter({ route, navigate, p, isActive, basePath: "/my-map" });
+</script>
 
-To build your library:
+<Router />
+```
 
-```bash
-npm run package
+This is what the sjvair.com widget and `v3-mobile` use today, via `MonitorMapLayout`
+(the thin wrapper `monitorMapRoutes` points to).
+
+### 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 display-options
+menu. 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, monitorsMapIntegration, monitorsManager, Menu } from "@sjvair/monitor-map";
+
+	monitorsManager.init();
+</script>
+
+<MapShell
+	integrations={[monitorsMapIntegration]}
+	ready={monitorsManager.initialized}
+	panelOpen={false}
+	routerEscapeHatch={false}
+>
+	{#snippet menu()}
+		<Menu>
+			<!-- display options for the integrations you included -->
+		</Menu>
+	{/snippet}
+</MapShell>
 ```
 
-To create a production version of your showcase app:
+See `src/lib/MonitorMapLayout.svelte` for the reference example of wiring a manager, an
+integration list, and menu/overlay content into `MapShell`.
 
-```bash
-npm run build
+**`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;
+}
 ```
 
-You can preview the production build with `npm run preview`.
+`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:
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+```ts
+import { MonitorsMapIntegration, type MonitorsDataSource } from "@sjvair/monitor-map";
 
-## Publishing
+const myDataSource: MonitorsDataSource = /* ... */;
+const monitorsMapIntegration = new MonitorsMapIntegration(myDataSource);
+```
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+This reuses all of the existing map-rendering work instead of forking it — see
+`CLAUDE.md`'s "Monitor Data Flow" section for more detail.
 
-To publish your library to [npm](https://www.npmjs.com):
+## Development
 
 ```bash
-npm publish
+npm run dev          # Start development server
+npm run build        # Widget build (vite build, code-split ES modules)
+npm run build:lib    # Library build (svelte-package), what gets published to npm
+npm run preview      # Preview widget build
+npm run check        # Type-check Svelte components
+npm run check:watch  # Type-check in watch mode
+npm run lint         # Prettier check + ESLint
+npm run format       # Auto-format with Prettier
 ```
+
+No test framework is currently configured.
+
+## 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). Bump `version` in `package.json` before cutting the
+release.

package/dist/lib/MonitorMapLayout.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import type { Snippet } from "svelte";
-	import { onDestroy } from "svelte";
+	import { onDestroy, untrack } from "svelte";
 	import MapShell from "./map/MapShell.svelte";
 	import MonitorsDisplayOptions from "./monitors/components/MonitorsDisplayOptions.svelte";
 	import MapLayersDisplayOptions from "./components/MapLayersDisplayOptions.svelte";
@@ -54,10 +54,15 @@
 	// applies a later "?pollutant=" change (e.g. navigating in from elsewhere) to an already-running manager.
 	$effect(() => {
 		const urlPollutant = route.search.pollutant;
+		// Read monitorsManager.pollutant via untrack: this effect must only react to the URL
+		// changing (e.g. navigating in from elsewhere), not to monitorsManager.pollutant itself.
+		// Tracking it here would make a UI-driven pollutant change (e.g. the display-options
+		// toggle) re-trigger this effect before the manager->URL effect below can sync the URL,
+		// so this effect would see the still-stale URL and immediately revert the user's change.
 		if (
 			monitorsManager.initialized &&
 			(urlPollutant === "pm25" || urlPollutant === "o3") &&
-			monitorsManager.pollutant !== urlPollutant
+			untrack(() => monitorsManager.pollutant) !== urlPollutant
 		) {
 			monitorsManager.pollutant = urlPollutant;
 		}

package/dist/lib/collocation-sites/collocations-map-integration.svelte.js

@@ -17,7 +17,7 @@ function collocationTooltip(evt) {
 class CollocationSitesMapIntegration extends MapIconLayerIntegration {
     referenceId = "collocation-sites";
     enabled = $state(false);
-    icons = new CollocationIconManager();
+    icons = new CollocationIconManager(monitorsManager);
     tooltipManager = new TooltipManager();
     features = $derived.by(() => {
         if (!monitorsManager.meta ||

package/dist/lib/index.d.ts

@@ -36,7 +36,7 @@ export { hmsManager } from "./hms/hms.svelte";
 export type { HMSManager } from "./hms/hms.svelte";
 export { mapManager, DefaultMapStyle, initializeMap } from "./map/map.svelte";
 export type { MapManager } from "./map/map.svelte";
-export { monitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
+export { monitorsMapIntegration, MonitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
 export { collocationSitesMapIntegration } from "./collocation-sites/collocations-map-integration.svelte";
 export { evStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
 export { windMapIntegration } from "./wind/wind.svelte";
@@ -58,12 +58,11 @@ export { MapIntegration } from "./map/integrations/map-integration.svelte";
 export { MapLayerIntegration } from "./map/integrations/map-layer-integration.svelte";
 export { MapIconLayerIntegration as MapGeoJSONIntegration } from "./map/integrations/map-geojson-integration.svelte";
 export type { SomeMapIntegration } from "./map/integrations/types";
-export type { MonitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
 export type { WindMapIntegration } from "./wind/wind.svelte";
 export type { EvStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
 export type { HMSFireMapIntegration } from "./hms/hms-fire-map-integration.svelte";
 export type { HMSSmokeMapIntegration } from "./hms/hms-smoke-map-integration.svelte";
 export type { HMSFireGroup } from "./hms/hms.svelte";
-export type { MonitorMapFeature, MonitorMarkerProperties, MonitorClusterMapFeature, MonitorClusterMarkerProperties } from "./monitors/types";
+export type { MonitorMapFeature, MonitorMarkerProperties, MonitorClusterMapFeature, MonitorClusterMarkerProperties, MonitorsDataSource, MonitorsPollutant } from "./monitors/types";
 export type { CollocationSiteMapFeature, CollocationSiteMarkerProperties } from "./collocation-sites/types";
 export type { EvStation, EvStationMarkerProperties, EvStationMapFeature, EvStationClusterMapFeature } from "./ev-stations/types";

package/dist/lib/index.js

@@ -33,7 +33,7 @@ export { evStationsManager } from "./ev-stations/ev-stations.svelte";
 export { hmsManager } from "./hms/hms.svelte";
 export { mapManager, DefaultMapStyle, initializeMap } from "./map/map.svelte";
 // Map integrations
-export { monitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
+export { monitorsMapIntegration, MonitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
 export { collocationSitesMapIntegration } from "./collocation-sites/collocations-map-integration.svelte";
 export { evStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
 export { windMapIntegration } from "./wind/wind.svelte";

package/dist/lib/map/MapShell.svelte

@@ -70,8 +70,12 @@
 	const TRANSITION_MS = 300;
 
 	$effect(() => {
+		// mapManager.map is only ever assigned once its own initial "load" has
+		// already fired (see initializeMap in map.svelte.ts), so by the time this
+		// effect sees a non-null map, it's already safe to reveal — waiting for a
+		// further "idle" event here is unreliable since one may never fire again.
 		if (mapManager.map && ready) {
-			mapManager.map.once("idle", () => disableLoadScreen());
+			disableLoadScreen();
 		}
 	});
 

package/dist/lib/map/map.svelte.js

@@ -42,7 +42,7 @@ export const initializeMap = (container) => {
             preset: "milkyway"
         }
     });
-    map.once("idle", () => {
+    map.once("load", () => {
         mapManager.map = map;
     });
     return () => map.remove();

package/dist/lib/monitors/monitors-icon-manager.svelte.d.ts

@@ -1,11 +1,13 @@
 import type { MonitorData, SJVAirEntryLevel } from "@sjvair/sdk";
 import { MapIconManager } from "../map/integrations/map-icon-manager";
+import type { MonitorsDataSource } from "./types";
 export declare function getIconId<T extends MonitorData>(monitor: T, level: SJVAirEntryLevel): string;
 export declare abstract class MonitorShapeIconManager extends MapIconManager {
+    private dataSource;
     protected abstract get idPrefix(): string;
     protected abstract transformSvg(svg: string): string;
     protected get iconSize(): number;
-    constructor();
+    constructor(dataSource: Pick<MonitorsDataSource, "levels">);
 }
 export declare class MonitorsIconManager extends MonitorShapeIconManager {
     protected get idPrefix(): string;

package/dist/lib/monitors/monitors-icon-manager.svelte.js

@@ -1,7 +1,6 @@
 import { asDataURI, circle, square, triangle } from "../map/icons";
 import { MapIconManager } from "../map/integrations/map-icon-manager";
 import { mapManager } from "../map/map.svelte";
-import { monitorsManager } from "./monitors.svelte";
 const MONITOR_ICONS = { circle, square, triangle };
 const MONITOR_ICON_BORDER_WIDTH = 2;
 const MONITOR_ICON_DEFAULT_COLOR = "#969696"; // light gray
@@ -26,16 +25,18 @@ export function getIconId(monitor, level) {
     }
 }
 export class MonitorShapeIconManager extends MapIconManager {
+    dataSource;
     get iconSize() {
         return 24;
     }
-    constructor() {
+    constructor(dataSource) {
         super();
+        this.dataSource = dataSource;
         $effect.root(() => {
             $effect(() => {
-                if (monitorsManager.levels) {
+                if (this.dataSource.levels) {
                     const iconLevels = [
-                        ...monitorsManager.levels,
+                        ...this.dataSource.levels,
                         { name: "default", color: MONITOR_ICON_DEFAULT_COLOR },
                         { name: "display", color: MONITOR_ICON_DISPLAY_COLOR }
                     ];

package/dist/lib/monitors/monitors-map-integration.svelte.d.ts

@@ -4,8 +4,9 @@ import { MapIconLayerIntegration } from "../map/integrations/map-geojson-integra
 import { MonitorsIconManager } from "./monitors-icon-manager.svelte";
 import { TooltipManager } from "../map/integrations/tooltip.svelte";
 import { MapDisplayOption } from "../map/integrations/map-display-option.svelte";
-import type { MonitorMapFeature, MonitorMarkerProperties } from "./types";
+import type { MonitorMapFeature, MonitorMarkerProperties, MonitorsDataSource } from "./types";
 declare class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProperties> {
+    private dataSource;
     referenceId: string;
     enabled: boolean;
     clustered: boolean;
@@ -33,10 +34,10 @@ declare class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMark
     clusterIconThresholds: Array<SJVAirEntryLevel>;
     get mapLayer(): Parameters<MaptilerMap["addLayer"]>[0];
     get mapSource(): Parameters<MaptilerMap["addSource"]>[1];
-    constructor();
+    constructor(dataSource?: MonitorsDataSource);
     apply(): void;
     remove(): void;
     private applySelectedState;
 }
 export declare const monitorsMapIntegration: MonitorsMapIntegration;
-export type { MonitorsMapIntegration };
+export { MonitorsMapIntegration };

package/dist/lib/monitors/monitors-map-integration.svelte.js

@@ -20,10 +20,11 @@ const filters = {
     }
 };
 class MonitorsMapIntegration extends MapIconLayerIntegration {
+    dataSource;
     referenceId = "monitors";
     enabled = $state(true);
     clustered = $state(true);
-    icons = new MonitorsIconManager();
+    icons;
     tooltipManager = new TooltipManager();
     renderer = new MonitorsClusterRenderer(this);
     displayOptions = $derived.by(() => ({
@@ -58,11 +59,11 @@ class MonitorsMapIntegration extends MapIconLayerIntegration {
         });
     };
     features = $derived.by(() => {
-        if (!monitorsManager.meta || !monitorsManager.latest || !monitorsManager.pollutant) {
+        if (!this.dataSource.meta || !this.dataSource.latest || !this.dataSource.pollutant) {
             return [];
         }
-        const levels = monitorsManager.meta.entryType(monitorsManager.pollutant).asIter.levels;
-        return Array.from(monitorsManager.latest.values().map((m) => {
+        const levels = this.dataSource.meta.entryType(this.dataSource.pollutant).asIter.levels;
+        return Array.from(this.dataSource.latest.values().map((m) => {
             const feature = {
                 type: "Feature",
                 properties: {
@@ -145,9 +146,9 @@ class MonitorsMapIntegration extends MapIconLayerIntegration {
         return byType;
     });
     clusterIconThresholds = $derived.by(() => {
-        if (!monitorsManager.meta || !monitorsManager.pollutant)
+        if (!this.dataSource.meta || !this.dataSource.pollutant)
             return [];
-        return monitorsManager.meta.entryType(monitorsManager.pollutant).asIter.levels ?? [];
+        return this.dataSource.meta.entryType(this.dataSource.pollutant).asIter.levels ?? [];
     });
     get mapLayer() {
         return {
@@ -175,8 +176,10 @@ class MonitorsMapIntegration extends MapIconLayerIntegration {
             }
         };
     }
-    constructor() {
+    constructor(dataSource = monitorsManager) {
         super();
+        this.dataSource = dataSource;
+        this.icons = new MonitorsIconManager(dataSource);
         $effect.root(() => {
             // Push filter changes to the active layer(s) imperatively
             $effect(() => {
@@ -284,3 +287,4 @@ class MonitorsMapIntegration extends MapIconLayerIntegration {
     }
 }
 export const monitorsMapIntegration = new MonitorsMapIntegration();
+export { MonitorsMapIntegration };

package/dist/lib/monitors/monitors.svelte.d.ts

@@ -1,7 +1,8 @@
 import { type MonitorData, type MonitorLatestType, type MonitorsMeta, type SJVAirEntryLevel } from "@sjvair/sdk";
 import { XMap } from "@tstk/builtin-extensions";
 import { Interval } from "@tstk/utils";
-declare class MonitorsManager {
+import type { MonitorsDataSource } from "./types";
+declare class MonitorsManager implements MonitorsDataSource {
     autoUpdate: Interval;
     initialized: boolean;
     latest: XMap<string, MonitorLatestType<"pm25" | "o3">> | null;

package/dist/lib/monitors/monitors.svelte.js

@@ -1,4 +1,4 @@
-import { getMonitors, getMonitorsLatest, getMonitorsMeta } from "@sjvair/sdk";
+import { getMonitors, getMonitorsList, getMonitorsMeta } from "@sjvair/sdk";
 import { XMap } from "@tstk/builtin-extensions";
 import { Interval } from "@tstk/utils";
 class MonitorsManager {
@@ -12,7 +12,7 @@ class MonitorsManager {
     async init(urlPollutant) {
         if (this.initialized)
             return;
-        [this.list, this.meta] = await Promise.all([getMonitors(), getMonitorsMeta()]);
+        [this.list, this.meta] = await Promise.all([getMonitorsList(), getMonitorsMeta()]);
         this.pollutant =
             urlPollutant === "pm25" || urlPollutant === "o3" ? urlPollutant : this.meta.default_pollutant;
         this.latest = await getMonitorsLatestMap(this.pollutant);
@@ -23,13 +23,13 @@ class MonitorsManager {
         if (!this.initialized)
             return;
         [this.list, this.latest] = await Promise.all([
-            getMonitors(),
+            getMonitorsList(),
             getMonitorsLatestMap(this.pollutant || this.meta?.default_pollutant || "pm25")
         ]);
     }
 }
 async function getMonitorsLatestMap(pollutant) {
-    const monitors = await getMonitorsLatest(pollutant);
+    const monitors = await getMonitors(pollutant);
     const latest = new XMap();
     for (const monitor of monitors) {
         latest.set(monitor.id, monitor);

package/dist/lib/monitors/types.d.ts

@@ -1,6 +1,7 @@
 import type { Feature, Geometry } from "geojson";
-import type { MonitorType } from "@sjvair/sdk";
+import type { MonitorLatestType, MonitorsMeta, MonitorType, SJVAirEntryLevel } from "@sjvair/sdk";
 import type { MapGeoJSONFeature } from "@maptiler/sdk";
+import type { XMap } from "@tstk/builtin-extensions";
 export type MonitorMapFeature = Feature<Geometry, MonitorMarkerProperties>;
 export interface MonitorClusterMapFeature extends MapGeoJSONFeature {
     properties: MonitorClusterMarkerProperties;
@@ -24,3 +25,18 @@ export interface MonitorClusterMarkerProperties {
     sumValues: number;
     countValues: number;
 }
+/** The pollutants monitorsMapIntegration/monitorsIconManager can render. */
+export type MonitorsPollutant = "pm25" | "o3";
+/**
+ * The reactive data a monitors map display needs: which monitors exist, their
+ * per-monitor "latest" value for the active pollutant, and the entry-level metadata
+ * used to color icons. `monitorsManager` (live, auto-polling) is the default
+ * implementation; a host app can supply its own (e.g. one backed by historical
+ * summaries instead of live readings) to reuse the map rendering with different data.
+ */
+export interface MonitorsDataSource {
+    readonly meta: MonitorsMeta | null;
+    readonly pollutant: MonitorsPollutant | null;
+    readonly latest: XMap<string, MonitorLatestType<MonitorsPollutant>> | null;
+    readonly levels: Array<SJVAirEntryLevel> | null;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@sjvair/monitor-map",
 	"description": "SJVAir's interactive monitor map",
-	"version": "3.3.0",
+	"version": "3.4.0",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/SJVAir/monitor-map"
@@ -71,7 +71,7 @@
 		"@lucide/svelte": "^1.28.0",
 		"@maptiler/sdk": "^4.1.0",
 		"@maptiler/weather": "^3.1.1",
-		"@sjvair/sdk": "npm:@jsr/sjvair__sdk@^3.2.0",
+		"@sjvair/sdk": "npm:@jsr/sjvair__sdk@^4.0.0",
 		"@tstk/builtin-extensions": "npm:@jsr/tstk__builtin-extensions@^1.0.8",
 		"@tstk/utils": "npm:@jsr/tstk__utils@^1.1.2",
 		"@turf/area": "^7.4.0",

package/src/lib/MonitorMapLayout.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import type { Snippet } from "svelte";
-	import { onDestroy } from "svelte";
+	import { onDestroy, untrack } from "svelte";
 	import MapShell from "$lib/map/MapShell.svelte";
 	import MonitorsDisplayOptions from "$lib/monitors/components/MonitorsDisplayOptions.svelte";
 	import MapLayersDisplayOptions from "$lib/components/MapLayersDisplayOptions.svelte";
@@ -54,10 +54,15 @@
 	// applies a later "?pollutant=" change (e.g. navigating in from elsewhere) to an already-running manager.
 	$effect(() => {
 		const urlPollutant = route.search.pollutant;
+		// Read monitorsManager.pollutant via untrack: this effect must only react to the URL
+		// changing (e.g. navigating in from elsewhere), not to monitorsManager.pollutant itself.
+		// Tracking it here would make a UI-driven pollutant change (e.g. the display-options
+		// toggle) re-trigger this effect before the manager->URL effect below can sync the URL,
+		// so this effect would see the still-stale URL and immediately revert the user's change.
 		if (
 			monitorsManager.initialized &&
 			(urlPollutant === "pm25" || urlPollutant === "o3") &&
-			monitorsManager.pollutant !== urlPollutant
+			untrack(() => monitorsManager.pollutant) !== urlPollutant
 		) {
 			monitorsManager.pollutant = urlPollutant;
 		}

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

@@ -22,7 +22,7 @@ class CollocationSitesMapIntegration extends MapIconLayerIntegration<Collocation
 	referenceId: string = "collocation-sites";
 	enabled: boolean = $state(false);
 
-	icons: CollocationIconManager = new CollocationIconManager();
+	icons: CollocationIconManager = new CollocationIconManager(monitorsManager);
 	tooltipManager: TooltipManager = new TooltipManager();
 
 	features: Array<CollocationSiteMapFeature> = $derived.by(() => {

package/src/lib/index.ts

@@ -45,7 +45,10 @@ export { mapManager, DefaultMapStyle, initializeMap } from "./map/map.svelte";
 export type { MapManager } from "./map/map.svelte";
 
 // Map integrations
-export { monitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
+export {
+	monitorsMapIntegration,
+	MonitorsMapIntegration
+} from "./monitors/monitors-map-integration.svelte";
 export { collocationSitesMapIntegration } from "./collocation-sites/collocations-map-integration.svelte";
 export { evStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
 export { windMapIntegration } from "./wind/wind.svelte";
@@ -78,7 +81,6 @@ export { MapIconLayerIntegration as MapGeoJSONIntegration } from "./map/integrat
 
 // Types
 export type { SomeMapIntegration } from "./map/integrations/types";
-export type { MonitorsMapIntegration } from "./monitors/monitors-map-integration.svelte";
 export type { WindMapIntegration } from "./wind/wind.svelte";
 export type { EvStationsMapIntegration } from "./ev-stations/ev-stations-map-integration.svelte";
 export type { HMSFireMapIntegration } from "./hms/hms-fire-map-integration.svelte";
@@ -88,7 +90,9 @@ export type {
 	MonitorMapFeature,
 	MonitorMarkerProperties,
 	MonitorClusterMapFeature,
-	MonitorClusterMarkerProperties
+	MonitorClusterMarkerProperties,
+	MonitorsDataSource,
+	MonitorsPollutant
 } from "./monitors/types";
 export type {
 	CollocationSiteMapFeature,

package/src/lib/map/MapShell.svelte

@@ -70,8 +70,12 @@
 	const TRANSITION_MS = 300;
 
 	$effect(() => {
+		// mapManager.map is only ever assigned once its own initial "load" has
+		// already fired (see initializeMap in map.svelte.ts), so by the time this
+		// effect sees a non-null map, it's already safe to reveal — waiting for a
+		// further "idle" event here is unreliable since one may never fire again.
 		if (mapManager.map && ready) {
-			mapManager.map.once("idle", () => disableLoadScreen());
+			disableLoadScreen();
 		}
 	});
 

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

@@ -61,7 +61,7 @@ export const initializeMap: Attachment<HTMLDivElement> = (container: string | HT
 		}
 	});
 
-	map.once("idle", () => {
+	map.once("load", () => {
 		mapManager.map = map;
 	});
 

package/src/lib/monitors/monitors-icon-manager.svelte.ts

@@ -2,7 +2,7 @@ import type { MonitorData, SJVAirEntryLevel } from "@sjvair/sdk";
 import { asDataURI, circle, square, triangle } from "$lib/map/icons";
 import { MapIconManager } from "$lib/map/integrations/map-icon-manager";
 import { mapManager } from "$lib/map/map.svelte";
-import { monitorsManager } from "./monitors.svelte";
+import type { MonitorsDataSource } from "./types";
 
 const MONITOR_ICONS = { circle, square, triangle };
 const MONITOR_ICON_BORDER_WIDTH = 2;
@@ -42,14 +42,14 @@ export abstract class MonitorShapeIconManager extends MapIconManager {
 		return 24;
 	}
 
-	constructor() {
+	constructor(private dataSource: Pick<MonitorsDataSource, "levels">) {
 		super();
 
 		$effect.root(() => {
 			$effect(() => {
-				if (monitorsManager.levels) {
+				if (this.dataSource.levels) {
 					const iconLevels = [
-						...monitorsManager.levels,
+						...this.dataSource.levels,
 						{ name: "default", color: MONITOR_ICON_DEFAULT_COLOR },
 						{ name: "display", color: MONITOR_ICON_DISPLAY_COLOR }
 					];

package/src/lib/monitors/monitors-map-integration.svelte.ts

@@ -15,7 +15,7 @@ import { TooltipManager } from "$lib/map/integrations/tooltip.svelte";
 import { MapDisplayOption } from "$lib/map/integrations/map-display-option.svelte";
 import { getCurrentLevel, getOrder } from "./monitor-utils";
 import { MonitorsClusterRenderer, monitorTooltip } from "./monitors-cluster-renderer";
-import type { MonitorMapFeature, MonitorMarkerProperties } from "./types";
+import type { MonitorMapFeature, MonitorMarkerProperties, MonitorsDataSource } from "./types";
 
 const filters = {
 	monitor(deviceType: MonitorType): ExpressionSpecification {
@@ -34,7 +34,7 @@ class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProper
 	enabled: boolean = $state(true);
 	clustered: boolean = $state(true);
 
-	icons: MonitorsIconManager = new MonitorsIconManager();
+	icons: MonitorsIconManager;
 	tooltipManager: TooltipManager = new TooltipManager();
 	private renderer: MonitorsClusterRenderer = new MonitorsClusterRenderer(this);
 
@@ -72,13 +72,13 @@ class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProper
 	};
 
 	features: Array<MonitorMapFeature> = $derived.by(() => {
-		if (!monitorsManager.meta || !monitorsManager.latest || !monitorsManager.pollutant) {
+		if (!this.dataSource.meta || !this.dataSource.latest || !this.dataSource.pollutant) {
 			return [];
 		}
-		const levels = monitorsManager.meta.entryType(monitorsManager.pollutant).asIter.levels;
+		const levels = this.dataSource.meta.entryType(this.dataSource.pollutant).asIter.levels;
 
 		return Array.from(
-			monitorsManager.latest.values().map((m) => {
+			this.dataSource.latest.values().map((m) => {
 				const feature: MonitorMapFeature = {
 					type: "Feature",
 					properties: {
@@ -163,8 +163,8 @@ class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProper
 	});
 
 	clusterIconThresholds: Array<SJVAirEntryLevel> = $derived.by(() => {
-		if (!monitorsManager.meta || !monitorsManager.pollutant) return [];
-		return monitorsManager.meta.entryType(monitorsManager.pollutant).asIter.levels ?? [];
+		if (!this.dataSource.meta || !this.dataSource.pollutant) return [];
+		return this.dataSource.meta.entryType(this.dataSource.pollutant).asIter.levels ?? [];
 	});
 
 	get mapLayer(): Parameters<MaptilerMap["addLayer"]>[0] {
@@ -195,8 +195,9 @@ class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProper
 		};
 	}
 
-	constructor() {
+	constructor(private dataSource: MonitorsDataSource = monitorsManager) {
 		super();
+		this.icons = new MonitorsIconManager(dataSource);
 
 		$effect.root(() => {
 			// Push filter changes to the active layer(s) imperatively
@@ -304,4 +305,4 @@ class MonitorsMapIntegration extends MapIconLayerIntegration<MonitorMarkerProper
 }
 
 export const monitorsMapIntegration = new MonitorsMapIntegration();
-export type { MonitorsMapIntegration };
+export { MonitorsMapIntegration };

package/src/lib/monitors/monitors.svelte.ts

@@ -1,6 +1,6 @@
 import {
 	getMonitors,
-	getMonitorsLatest,
+	getMonitorsList,
 	getMonitorsMeta,
 	type MonitorData,
 	type MonitorLatestType,
@@ -9,8 +9,9 @@ import {
 } from "@sjvair/sdk";
 import { XMap } from "@tstk/builtin-extensions";
 import { Interval } from "@tstk/utils";
+import type { MonitorsDataSource } from "./types";
 
-class MonitorsManager {
+class MonitorsManager implements MonitorsDataSource {
 	autoUpdate: Interval = new Interval(async () => await this.update(), 2 * 60 * 1000);
 	initialized: boolean = $state(false);
 
@@ -28,7 +29,7 @@ class MonitorsManager {
 	async init(urlPollutant?: string | number | boolean): Promise<void> {
 		if (this.initialized) return;
 
-		[this.list, this.meta] = await Promise.all([getMonitors(), getMonitorsMeta()]);
+		[this.list, this.meta] = await Promise.all([getMonitorsList(), getMonitorsMeta()]);
 
 		this.pollutant =
 			urlPollutant === "pm25" || urlPollutant === "o3" ? urlPollutant : this.meta.default_pollutant;
@@ -41,7 +42,7 @@ class MonitorsManager {
 		if (!this.initialized) return;
 
 		[this.list, this.latest] = await Promise.all([
-			getMonitors(),
+			getMonitorsList(),
 			getMonitorsLatestMap(this.pollutant || this.meta?.default_pollutant || "pm25")
 		]);
 	}
@@ -50,7 +51,7 @@ class MonitorsManager {
 async function getMonitorsLatestMap(
 	pollutant: "pm25" | "o3"
 ): Promise<XMap<string, MonitorLatestType<"pm25" | "o3">>> {
-	const monitors = await getMonitorsLatest(pollutant);
+	const monitors = await getMonitors(pollutant);
 	const latest = new XMap<string, MonitorLatestType<"pm25" | "o3">>();
 
 	for (const monitor of monitors) {

package/src/lib/monitors/types.ts

@@ -1,6 +1,7 @@
 import type { Feature, Geometry } from "geojson";
-import type { MonitorType } from "@sjvair/sdk";
+import type { MonitorLatestType, MonitorsMeta, MonitorType, SJVAirEntryLevel } from "@sjvair/sdk";
 import type { MapGeoJSONFeature } from "@maptiler/sdk";
+import type { XMap } from "@tstk/builtin-extensions";
 
 export type MonitorMapFeature = Feature<Geometry, MonitorMarkerProperties>;
 
@@ -28,3 +29,20 @@ export interface MonitorClusterMarkerProperties {
 	sumValues: number;
 	countValues: number;
 }
+
+/** The pollutants monitorsMapIntegration/monitorsIconManager can render. */
+export type MonitorsPollutant = "pm25" | "o3";
+
+/**
+ * The reactive data a monitors map display needs: which monitors exist, their
+ * per-monitor "latest" value for the active pollutant, and the entry-level metadata
+ * used to color icons. `monitorsManager` (live, auto-polling) is the default
+ * implementation; a host app can supply its own (e.g. one backed by historical
+ * summaries instead of live readings) to reuse the map rendering with different data.
+ */
+export interface MonitorsDataSource {
+	readonly meta: MonitorsMeta | null;
+	readonly pollutant: MonitorsPollutant | null;
+	readonly latest: XMap<string, MonitorLatestType<MonitorsPollutant>> | null;
+	readonly levels: Array<SJVAirEntryLevel> | null;
+}