@sjvair/monitor-map 4.1.0 → 4.2.0

package/src/lib/MonitorDetailPanel.svelte

@@ -1,11 +1,14 @@
 <script lang="ts">
-	import type { ComponentProps } from "svelte";
+	import { untrack, type ComponentProps } from "svelte";
 	import type { SJVAirEntryLevel } from "@sjvair/sdk";
 	import DataBox from "$lib/components/DataBox.svelte";
+	import LoadError from "$lib/LoadError.svelte";
 	import MonitorWidgetModal from "$lib/monitors/components/MonitorWidgetModal.svelte";
 	import MonitorSubscriptionManager from "$lib/monitors/components/MonitorSubscriptionManager.svelte";
 	import DataChart from "$lib/data-chart/DataChart.svelte";
 	import { monitorsManager } from "$lib";
+	import { MonitorDetailsState } from "$lib/monitors/monitor-details.svelte";
+	import { choosePanelPollutant } from "$lib/monitors/panel-pollutant";
 	import { useMonitorMapRouter } from "./router-context";
 	import { fetchTempByCoords } from "$lib/weather";
 	import { Colors, valueToColor } from "$lib/colors";
@@ -21,24 +24,75 @@
 	}
 	const { route, navigate, basePath } = useMonitorMapRouter();
 
-	const monitor = $derived(monitorsManager.latest?.get(route.params.id ?? ""));
+	// The panel fetches its own monitor: the map's readings only hold monitors that have a
+	// current reading for the map's pollutant.
+	const details = new MonitorDetailsState();
+	const meta = $derived(monitorsManager.meta);
+	// Shown only once the metadata is in too; labels and levels come from it.
+	const monitor = $derived(details.status === "ready" && meta ? details.monitor : null);
+
+	// Through a $derived: the router replaces `route.params` on every navigation, including
+	// a search-only change or Back to the same monitor, which must not reload the panel.
+	const routeId = $derived(route.params.id);
+	$effect(() => {
+		const id = routeId;
+		if (id) untrack(() => details.load(id));
+	});
+
+	// 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);
+
+	$effect(() => {
+		const latest = monitorsManager.latest;
+		// Null while a pollutant change is loading; wait for the readings that follow.
+		if (!latest || latest === seenLatest) return;
+		// The first readings of a cold load arrive alongside this panel's own request.
+		const first = seenLatest === null;
+		seenLatest = latest;
+		if (first) return;
+		untrack(() => {
+			details.refresh();
+			refreshTick++;
+		});
+	});
+
+	const panel = $derived(
+		monitor && meta ? choosePanelPollutant(monitorsManager.pollutant, 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;
+		const label = meta.entryType(mapPollutant).label;
+		// Mid-sentence: lowercase a plain word ("Ozone"), keep a symbol ("PM2.5") as written.
+		const missing = /^[A-Z][a-z]+$/.test(label) ? label.toLowerCase() : label;
+		return `Showing ${shown}. This monitor has no ${missing} readings.`;
+	});
+
 	let tempData: TempDataBox | undefined = $state();
 	const entryData: ComponentProps<typeof DataBox> | undefined = $derived.by(() => {
-		if (!monitor || !monitorsManager.meta) return;
+		if (!monitor || !meta || !panel?.pollutant || !reading) return;
 
-		const entryType = monitorsManager.meta.entryType(monitor.latest.entry_type);
+		const entryType = meta.entryType(panel.pollutant);
 		const level: SJVAirEntryLevel | undefined = getCurrentLevel(
-			monitor.latest.value,
+			reading.value,
 			entryType.asIter.levels!
 		);
 
-		const updateDuration = monitorsManager.meta.monitorType(monitor.type).expected_interval;
+		const updateDuration = meta.monitorType(monitor.type).expected_interval;
 
 		return {
 			color: level?.color ?? "",
 			header: entryType.label,
 			subheading: `(${updateDuration} avg)`,
-			value: Math.round(parseInt(monitor.latest.value, 10)).toString()
+			value: Math.round(parseInt(reading.value, 10)).toString()
 		};
 	});
 
@@ -49,15 +103,26 @@
 		{ min: 95, color: Colors.red }
 	];
 
+	// Re-run for each refreshed copy of the monitor, as before, but never show one monitor's
+	// temperature on another: cleared when the id changes, and a late answer is dropped.
+	let tempMonitorId: string | undefined;
 	$effect(() => {
-		if (monitor && monitor.position) {
-			fetchTempByCoords(monitor.position.coordinates).then((temperature) => {
+		const current = monitor;
+		const id = current?.id;
+		if (id !== tempMonitorId) {
+			tempMonitorId = id;
+			tempData = undefined;
+		}
+		if (!current?.position) return;
+		fetchTempByCoords(current.position.coordinates)
+			.then((temperature) => {
+				if (untrack(() => monitor?.id) !== id) return;
 				tempData = {
 					value: `${temperature}°F`,
 					color: valueToColor(temperature, tempColors)
 				};
-			});
-		}
+			})
+			.catch(console.error);
 	});
 </script>
 
@@ -104,24 +169,37 @@
 				{@render badge("location-on", monitor.county)}
 				{@render badge("location-searching", monitor.location)}
 			</div>
+			{#if pollutantNote}
+				<p class="text-center text-sm text-gray-600">{pollutantNote}</p>
+			{:else if panel && !panel.hasReading}
+				<p class="text-center text-sm text-gray-600">This monitor has no current readings.</p>
+			{/if}
 		{/if}
 	</div>
 
 	<div class="tall:overflow-y-auto flex flex-col items-center gap-12 p-5 pt-10">
-		{#if monitor}
-			<div class="flex w-full justify-around">
-				{#if tempData}
-					<DataBox color={tempData.color} header="Temperature" value={tempData.value} />
-				{/if}
-				{#if entryData}
-					<DataBox
-						color={entryData.color}
-						header={entryData.header}
-						subheading={entryData.subheading}
-						value={entryData.value}
-					/>
-				{/if}
-			</div>
+		{#if details.status === "not-found"}
+			<p class="text-gray-700" role="alert">Monitor not found.</p>
+		{:else if details.status === "failed"}
+			<LoadError message="Couldn't load this monitor." onretry={() => details.retry()} />
+		{:else if !monitor || !panel}
+			<p class="text-sm text-gray-500">Loading…</p>
+		{:else}
+			{#if tempData || entryData}
+				<div class="flex w-full justify-around">
+					{#if tempData}
+						<DataBox color={tempData.color} header="Temperature" value={tempData.value} />
+					{/if}
+					{#if entryData}
+						<DataBox
+							color={entryData.color}
+							header={entryData.header}
+							subheading={entryData.subheading}
+							value={entryData.value}
+						/>
+					{/if}
+				</div>
+			{/if}
 
 			<div class="tall:block hidden">
 				<MonitorWidgetModal monitorId={monitor.id} />
@@ -131,9 +209,11 @@
 				<MonitorSubscriptionManager monitorId={monitor.id} />
 			{/if}
 
-			<div class="w-full">
-				<DataChart {monitor} />
-			</div>
+			{#if panel.pollutant}
+				<div class="w-full">
+					<DataChart {monitor} pollutant={panel.pollutant} {refreshTick} />
+				</div>
+			{/if}
 
 			<div class="w-full">
 				<h3 class="font-semibold">Data Provided Courtesy Of:</h3>

package/src/lib/MonitorMapLayout.svelte

@@ -14,6 +14,7 @@
 		currentSelection,
 		parsePollutantParam
 	} from "$lib/options/pollutant-param";
+	import LoadError from "$lib/LoadError.svelte";
 	import Legend from "$lib/legend/Legend.svelte";
 	import {
 		fireSmokeLegendSections,
@@ -61,7 +62,19 @@
 		monitorsMapIntegration.enabled = false;
 	}
 
-	monitorsManager.init(route.search.pollutant);
+	// The load screen stays up until the monitors load, so a failure has to be shown on it.
+	let loadFailed = $state(false);
+
+	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;
+		});
+	}
+
+	loadMonitors();
 	// A previous instance of this layout stopped polling in onDestroy; init() is a no-op by now.
 	monitorsManager.resumeAutoUpdate();
 	collocationSitesManager.init();
@@ -129,6 +142,11 @@
 	knownRoutes={[`${basePath}/monitor/`]}
 	{basePath}
 >
+	{#snippet loadError()}
+		{#if loadFailed}
+			<LoadError message="Couldn't load air monitors." onretry={loadMonitors} />
+		{/if}
+	{/snippet}
 	{#snippet menu()}
 		<OptionsGroup>
 			<PollutantMenu />

package/src/lib/core.ts

@@ -13,5 +13,5 @@ export {
 	type MonitorMapRouterApi
 } from "./router-context";
 export { monitorsManager } from "./monitors/monitors.svelte.js";
-export type { MonitorsManager } from "./monitors/monitors.svelte.js";
+export type { MonitorsManager, MonitorsInitOptions } from "./monitors/monitors.svelte.js";
 export type { MonitorsDataSource, MonitorsPollutant } from "./monitors/types";

package/src/lib/data-chart/DataChart.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
+	import { untrack } from "svelte";
 	import type { Attachment } from "svelte/attachments";
-	import type { MonitorLatestType } from "@sjvair/sdk";
 	import type { DateRange as CalendarRange } from "bits-ui";
 	import { parseAbsolute } from "@internationalized/date";
 	import { Maximize, SquareX } from "@lucide/svelte";
@@ -9,13 +9,23 @@
 	import { getMonitorEntriesCSVUrl } from "@sjvair/sdk/monitors";
 	import { format, parseISO } from "date-fns";
 	import { RangeCalendar } from "$lib/components/ui/range-calendar";
+	import type { PanelPollutant } from "../monitors/panel-pollutant";
+	import { monitorsManager } from "../monitors/monitors.svelte";
 	import { DataChartManager } from "./data-chart.svelte";
-	import { createDateRange } from "./DateRange";
-	import { fetchChartData } from "./requests";
+	import { createDateRange, extendToNow, includesToday } from "./DateRange";
+	import { fetchChartData, type ChartMonitor } from "./requests";
 	import { getChartConfig } from "./chart-utils";
-	import { monitorsManager } from "../monitors/monitors.svelte";
+	import { levelColors } from "./level-colors";
+
+	interface Props {
+		monitor: ChartMonitor;
+		/** The pollutant to chart. Independent of the pollutant the map is coloring by. */
+		pollutant: PanelPollutant;
+		/** Bumped by the owner whenever fresh data may exist; see the effect below. */
+		refreshTick?: number;
+	}
 
-	let { monitor }: { monitor: MonitorLatestType<"pm25" | "o3"> } = $props();
+	let { monitor, pollutant, refreshTick = 0 }: Props = $props();
 
 	const chartManager = new DataChartManager();
 	let expanded = $state(false);
@@ -34,7 +44,8 @@
 			format(parseISO(chartManager.dateRange.end), "MMM d, yyyy")
 	);
 
-	const noChartData = $derived(!chartManager.chartData.length);
+	// A request with no entries still resolves to [[], []], so test the x axis, not the tuple.
+	const noChartData = $derived(!chartManager.chartData[0]?.length);
 	const message = $derived(
 		chartManager.loading
 			? "Loading Data"
@@ -42,10 +53,38 @@
 				? "No Data Available For Selected Date Range"
 				: ""
 	);
-	const pollutantLabel = $derived(monitorsManager.pollutant === "pm25" ? "PM 2.5" : "Ozone");
+	const pollutantLabel = $derived(pollutant === "pm25" ? "PM 2.5" : "Ozone");
+	// Level definitions are shared metadata, not the map's current selection.
+	const colors = $derived(
+		levelColors(monitorsManager.meta?.entryType(pollutant).asIter.levels ?? [])
+	);
 
+	// Reload for another monitor or pollutant, not for a new object describing the same one.
+	// Both go through a $derived: the owner recomputes what it passes on every refresh, and a
+	// prop read directly would re-run this effect even when the value is unchanged.
+	const monitorId = $derived(monitor.id);
+	const chartPollutant = $derived(pollutant);
 	$effect(() => {
-		if (monitor) loadChartData();
+		void monitorId;
+		void chartPollutant;
+		untrack(() => loadChartData());
+	});
+
+	// Whether the chosen range ended on the day it was chosen, so it should follow the present.
+	// Remembered, not re-tested per tick: a panel left open past midnight keeps following.
+	let live = includesToday(chartManager.dateRange);
+	let seenTick = untrack(() => refreshTick);
+
+	// A range that ended in the past cannot gain entries, so only a live one reloads.
+	$effect(() => {
+		const tick = refreshTick;
+		if (tick === seenTick) return;
+		seenTick = tick;
+		if (!live) return;
+		untrack(() => {
+			chartManager.dateRange = extendToNow(chartManager.dateRange);
+			loadChartData({ silent: true });
+		});
 	});
 
 	$effect(() => {
@@ -82,7 +121,7 @@
 			instance?.destroy?.();
 			el.innerHTML = "";
 			const maxDiff = Math.max(...flatData) - Math.min(...flatData);
-			const opts = getChartConfig(monitor.type, maxDiff, width, height);
+			const opts = getChartConfig(monitor.type, maxDiff, width, height, colors, pollutantLabel);
 			instance = new uPlot(opts, chartManager.chartData, el);
 		};
 
@@ -103,9 +142,19 @@
 		};
 	};
 
-	async function loadChartData() {
-		chartManager.loading = true;
-		chartManager.chartData = await fetchChartData(monitor, chartManager.dateRange);
+	let chartRequest = 0;
+
+	// `silent` keeps the current chart on screen while a timed refresh loads.
+	async function loadChartData({ silent = false } = {}) {
+		const request = ++chartRequest;
+		if (!silent) chartManager.loading = true;
+		const data = await fetchChartData(monitor, chartManager.dateRange, pollutant);
+		// A newer request (another range, monitor, pollutant or refresh) owns the chart now.
+		if (request !== chartRequest) return;
+		// A failed request resolves to [] (an empty range is [[], []]); a background refresh
+		// that failed keeps the chart already on screen.
+		if (silent && data.length === 0) return;
+		chartManager.chartData = data;
 		chartManager.loading = false;
 	}
 
@@ -113,6 +162,7 @@
 		if (calendarValue?.start && calendarValue?.end) {
 			dataRange = calendarValue;
 			chartManager.dateRange = createDateRange(dataRange.start, dataRange.end);
+			live = includesToday(chartManager.dateRange);
 			calendarOpen = false;
 			loadChartData();
 		}
@@ -121,7 +171,7 @@
 	function downloadCSV() {
 		const url = getMonitorEntriesCSVUrl({
 			monitorId: monitor.id,
-			entryType: monitorsManager.pollutant ?? "pm25",
+			entryType: pollutant,
 			timestampGte: chartManager.dateRange.start,
 			timestampLte: chartManager.dateRange.end
 		});

package/src/lib/data-chart/DateRange.ts

@@ -1,4 +1,4 @@
-import { subDays, startOfDay, endOfDay, isToday } from "date-fns";
+import { subDays, startOfDay, endOfDay, isToday, parseISO } from "date-fns";
 import type { DateValue } from "@internationalized/date";
 
 export type DateRange = { start: string; end: string };
@@ -20,3 +20,13 @@ export function createDateRange(start?: DateValue, end?: DateValue): DateRange {
 		end: endDate.toISOString()
 	};
 }
+
+/** Whether the range ends on the current calendar day, i.e. it can still gain entries. */
+export function includesToday(range: DateRange): boolean {
+	return isToday(parseISO(range.end));
+}
+
+/** The same range with its end moved to the present. */
+export function extendToNow(range: DateRange): DateRange {
+	return { start: range.start, end: new Date().toISOString() };
+}

package/src/lib/data-chart/chart-utils.ts

@@ -1,4 +1,4 @@
-import { monitorsManager } from "../monitors/monitors.svelte";
+import type { LevelColors } from "./level-colors";
 import { tooltipsPlugin, uPlotCursorConfig } from "./tooltip";
 import { fromUnixTime, getUnixTime, isToday, isAfter } from "date-fns";
 import type uPlot from "uplot";
@@ -6,15 +6,6 @@ import type { MonitorType } from "@sjvair/sdk";
 
 const PM25_AVG_60_STROKE = "3572b0";
 
-function getColors(): Array<[number, string]> {
-	const levels = monitorsManager.levels ?? [];
-	const colors = levels.map((level) => [level.range[0], level.color.replace(/^#/, "")]) as Array<
-		[number, string]
-	>;
-	colors.push([Infinity, "000000"]);
-	return colors;
-}
-
 const baseXSeriesConfig = {};
 
 const baseYSeriesConfig = {
@@ -23,26 +14,33 @@ const baseYSeriesConfig = {
 	width: 1
 };
 
-const pm25SeriesConfig = {
+/** The level stops plus a final black stop, so values above the top level still get a color. */
+function gradientStops(colors: LevelColors): LevelColors {
+	return [...colors, [Infinity, "000000"]];
+}
+
+const pm25SeriesConfig = (stops: LevelColors) => ({
 	...baseYSeriesConfig,
 	label: "Real Time",
 	width: 2,
-	stroke: (u: uPlot) => scaleGradient(u, "y", 1, getColors(), true)
-};
+	stroke: (u: uPlot) => scaleGradient(u, "y", 1, stops, true)
+});
 
-const pm25Avg60SeriesConfig = {
+const pm25Avg60SeriesConfig = (stops: LevelColors) => ({
 	...baseYSeriesConfig,
 	label: "60 Minute Average",
-	stroke: (u: uPlot) => autograd(u, PM25_AVG_60_STROKE)
-};
+	stroke: (u: uPlot) => autograd(u, PM25_AVG_60_STROKE, stops)
+});
 
 export function getChartConfig(
 	sourceName: MonitorType,
 	maxDiff: number,
 	width: number,
-	height: number
+	height: number,
+	colors: LevelColors,
+	label: string
 ): uPlot.Options {
-	const series: Array<uPlot.Series> = getSeriesConfigs(sourceName);
+	const series: Array<uPlot.Series> = getSeriesConfigs(sourceName, gradientStops(colors));
 	const getStroke = (u: uPlot, sIdx: number): string => {
 		const stroke = series[sIdx].stroke! as (u: uPlot, sIdx: number) => string | CanvasGradient;
 		return stroke(u, sIdx) as string;
@@ -51,7 +49,7 @@ export function getChartConfig(
 	return {
 		width,
 		height,
-		cursor: uPlotCursorConfig.get(),
+		cursor: uPlotCursorConfig.get(colors),
 		// @ts-expect-error: select missing pseudo "required" options
 		select: {
 			show: false
@@ -94,7 +92,7 @@ export function getChartConfig(
 				}
 			},
 			{
-				label: monitorsManager.pollutant === "pm25" ? "PM 2.5" : "Ozone",
+				label,
 				side: 3,
 				values: (_: uPlot, ticks: number[]) =>
 					ticks.map((v: number) => v.toFixed(maxDiff < 5 ? 1 : 0))
@@ -106,9 +104,8 @@ export function getChartConfig(
 	};
 }
 
-function getSeriesConfigs(monitorType: MonitorType) {
-	const singleSeriesConfig = Object.assign({}, pm25Avg60SeriesConfig);
-	singleSeriesConfig.width = 2;
+function getSeriesConfigs(monitorType: MonitorType, stops: LevelColors) {
+	const singleSeriesConfig = { ...pm25Avg60SeriesConfig(stops), width: 2 };
 
 	switch (monitorType) {
 		case "airnow":
@@ -120,15 +117,15 @@ function getSeriesConfigs(monitorType: MonitorType) {
 
 		case "airgradient":
 		case "purpleair":
-			return [baseXSeriesConfig, pm25SeriesConfig];
+			return [baseXSeriesConfig, pm25SeriesConfig(stops)];
 	}
 }
 
-function autograd(u: uPlot, fallback: string) {
+function autograd(u: uPlot, fallback: string, stops: LevelColors) {
 	if (u.series.length > 2) {
 		return fallback;
 	}
-	return scaleGradient(u, "y", 1, getColors(), true);
+	return scaleGradient(u, "y", 1, stops, true);
 }
 
 function scaleGradient(

package/src/lib/data-chart/level-colors.ts

@@ -0,0 +1,13 @@
+/** Color stops for a chart: each level's lower bound and its hex color without the `#`. */
+export type LevelColors = Array<[number, string]>;
+
+// `range` is loose on purpose: the SDK types it as a tuple with an open tail, and only its
+// first member (the level's lower bound) is read.
+export function levelColors(
+	levels: ReadonlyArray<{
+		range: readonly [number, ...unknown[]] | readonly number[];
+		color: string;
+	}>
+): LevelColors {
+	return levels.map((level) => [level.range[0], level.color.replace(/^#/, "")]);
+}

package/src/lib/data-chart/requests.ts

@@ -1,14 +1,18 @@
-import { getMonitorEntries, type MonitorEntry, type MonitorLatestType } from "@sjvair/sdk";
+import { getMonitorEntries, type MonitorDetails, type MonitorEntry } from "@sjvair/sdk";
 import { getUnixTime, parseISO, differenceInMinutes, addMinutes } from "date-fns";
-import { monitorsManager } from "../monitors/monitors.svelte";
+import type { PanelPollutant } from "../monitors/panel-pollutant";
 import type { DateRange } from "./DateRange";
 
+/** The monitor fields the chart reads. */
+export type ChartMonitor = Pick<MonitorDetails, "id" | "name" | "type" | "data_source">;
+
 export async function fetchChartData(
-	m: MonitorLatestType<"pm25" | "o3">,
-	d: DateRange
+	m: ChartMonitor,
+	d: DateRange,
+	entryType: PanelPollutant
 ): Promise<uPlot.AlignedData> {
 	return await getMonitorEntries({
-		entryType: monitorsManager.pollutant ?? "pm25",
+		entryType,
 		monitorId: m.id,
 		timestampGte: d.start,
 		timestampLte: d.end

package/src/lib/data-chart/tooltip.ts

@@ -1,12 +1,5 @@
 import { format, fromUnixTime } from "date-fns";
-import { monitorsManager } from "../monitors/monitors.svelte";
-
-function getColors(): Array<[number, string]> {
-	return (monitorsManager.levels ?? []).map((level) => [
-		level.range[0],
-		level.color.replace(/^#/, "")
-	]) as Array<[number, string]>;
-}
+import type { LevelColors } from "./level-colors";
 
 let cursLeft = -100;
 let cursTop = -100;
@@ -16,7 +9,7 @@ export const uPlotCursorConfig = {
 		cursLeft = left;
 		cursTop = top;
 	},
-	get: (): uPlot.Cursor => ({
+	get: (colors: LevelColors): uPlot.Cursor => ({
 		left: cursLeft,
 		top: cursTop,
 		y: false,
@@ -24,7 +17,6 @@ export const uPlotCursorConfig = {
 			size: 7,
 			fill: (u: uPlot, sIdx: number) => {
 				const xIdx = u.cursor.idxs![sIdx];
-				const colors = getColors();
 
 				if (xIdx != null && u.series.length >= 2 && sIdx === 1) {
 					const val = u.data[sIdx][xIdx]!;

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

@@ -188,8 +188,9 @@ class EvStationsMapIntegration
 			clickManager.unregister([this.referenceId]);
 			this.tooltipManager.disable();
 			this.renderer.remove();
-			this.icons.loadIcons().then(() => {
-				if (mapManager.styleLoading) return;
+			// Clustering may be toggled again before the icons arrive; only the latest apply runs.
+			this.supersedePending();
+			this.whenIconsLoad(() => {
 				this.renderer.apply(this.handleStationClick);
 				this.tooltipManager.enable();
 			});
@@ -198,8 +199,7 @@ class EvStationsMapIntegration
 			this.tooltipManager.disable();
 			clickManager.unregister([this.referenceId]);
 			super.apply();
-			this.icons.loadIcons().then(() => {
-				if (mapManager.styleLoading) return;
+			this.whenIconsLoad(() => {
 				clickManager.register([this.referenceId], this.handleStationClick);
 				this.tooltipManager.enable();
 			});

package/src/lib/index.ts

@@ -39,7 +39,7 @@ export {
 
 // State managers
 export { monitorsManager } from "./monitors/monitors.svelte";
-export type { MonitorsManager } from "./monitors/monitors.svelte";
+export type { MonitorsManager, MonitorsInitOptions } from "./monitors/monitors.svelte";
 export { collocationSitesManager } from "./collocation-sites/collocations.svelte";
 export type { CollocationSitesManager } from "./collocation-sites/collocations.svelte";
 export { evStationsManager } from "./ev-stations/ev-stations.svelte";

package/src/lib/lazy-chunks.ts

@@ -0,0 +1,7 @@
+import { sharedLoad } from "./shared-load";
+
+// The heavy chunks behind the lazy routes entry (`./lazy-routes.ts`). They are imported here,
+// not in the wrapper components that await them: sv-router treats any function whose source
+// contains `() => import(...)` as a lazy route, and a compiled component is such a function.
+export const loadMonitorMapLayout = sharedLoad(() => import("./MonitorMapLayout.svelte"));
+export const loadMonitorDetailPanel = sharedLoad(() => import("./MonitorDetailPanel.svelte"));

package/src/lib/lazy-routes.ts

@@ -1,15 +1,20 @@
 import type { Routes } from "sv-router";
+import LazyMapLayout from "./LazyMapLayout.svelte";
+import LazyMonitorDetailPanel from "./LazyMonitorDetailPanel.svelte";
+import MainMapView from "./MainMapView.svelte";
 
 /**
  * Lazy routes entry (`@sjvair/monitor-map/routes`): the same route tree as the main entry's
- * `monitorMapRoutes`, but the layout and every route load on demand, so a host router can
- * reference it at startup without loading the map.
+ * `monitorMapRoutes`, but the map layout and the monitor panel load on demand, so a host
+ * router can reference it at startup without loading the map.
  *
- * Each component must stay a literal `() => import(...)`: sv-router recognises lazy
- * components by matching the function's source text, so a helper wrapper would break it.
+ * The components here are light wrappers that load the real ones themselves
+ * (`./lazy-chunks.ts`) and show the load screen meanwhile. They are deliberately not
+ * `() => import(...)` routes: sv-router renders nothing for a route until every lazy component
+ * on it has loaded, which left the outlet empty on a cold link into the map.
  */
 export const monitorMapRoutes: Routes = {
-	layout: () => import("./MonitorMapLayout.svelte"),
-	"/": () => import("./MainMapView.svelte"),
-	"/monitor/:id": () => import("./MonitorDetailPanel.svelte")
+	layout: LazyMapLayout,
+	"/": MainMapView,
+	"/monitor/:id": LazyMonitorDetailPanel
 };