@tellegen/svelte 0.5.0 → 0.5.2

package/README.md

@@ -231,6 +231,9 @@ The map switches to the fallback in three cases:
 - its tiles answer 401, 403 or 429;
 - tile fetches keep failing with nothing arriving.
 
+Only the basemap style's own sources count. A source the host adds to the map
+never triggers the switch, and its errors are logged to the console.
+
 Whenever an OpenFreeMap style renders, as primary or as fallback,
 `openFreeMapEdits` tunes it towards CARTO's look. Road lines start at zoom 8.
 In the dark theme, water and waterways take Dark Matter's colours and land
@@ -257,16 +260,44 @@ besides its click callbacks:
 - `extraLayers`: deck.gl layers drawn after tellegen's own, in the same
   overlay.
 - `attribution`: `'compact'` (default) or `'full'`. There is no off switch.
+- `declutterMarkers`: default `true`. At low zoom the map draws one bus
+  marker per crowded spot, about 16 pixels across. It keeps a generator
+  before a substation before any other bus, as recorded in a grid made by
+  tellegen-synth, then the bus with the most generation and demand. Zooming
+  in shows the rest. The selected bus always draws, and every bus is still
+  in the case: the bus picker finds it and a line's tooltip names it.
+  `false` draws every marker at every zoom.
 - `onMapReady(map, overlay)`: called with the MapLibre map and the deck
   overlay once they exist. It may return a cleanup, and it fires again after
   a context-loss or basemap rebuild. If it throws, the map and its window
-  and document listeners are still released when the map is torn down.
+  and document listeners are still released when the map is torn down. A
+  switch to the fallback does not call it again (see below).
 - `onBasemapFallback(reason)`: the switch to the fallback happened.
   `reason.from` and `reason.to` name the two providers.
 - `onBasemapError(reason)`: no basemap can be shown. The network layers
   still draw. `reason.from` names the provider that failed last, and
   `reason.to` is `null`.
 
+The switch to the fallback replaces the whole MapLibre style, so sources and
+layers the host added to the map are gone after it. The network,
+`extraLayers` and `projection` carry over. A host that adds its own sources
+and layers adds them on every `style.load`, not once in `onMapReady`, which
+runs before the first style loads, so one listener covers the primary and the
+fallback:
+
+```ts
+import type { Map as MapLibreMap } from "maplibre-gl";
+
+function onMapReady(map: MapLibreMap) {
+  const addFeeders = () => {
+    map.addSource("feeders", { type: "geojson", data: "/feeders.geojson" });
+    map.addLayer({ id: "feeders", type: "line", source: "feeders" });
+  };
+  map.on("style.load", addFeeders);
+  return () => map.off("style.load", addFeeders);
+}
+```
+
 `TellegenProvider` and `TellegenViewer` also take `cartoApiKey`, and pass it,
 together with `theme`, to the default shell's map. Both follow their props:
 changing either rebuilds that map in place. A SvelteKit 3 host can

package/dist/TellegenMap.svelte

@@ -31,6 +31,7 @@
 		type MapTheme
 	} from './basemap.js';
 	import { caseDeltas, caseRatings, displayMetaFor, displaySeriesFor } from './display.js';
+	import { declutterBuses, declutterZoom, withBus } from './declutter.js';
 	import {
 		type CaseState,
 		type CameraSnapshot,
@@ -56,6 +57,7 @@
 	} from './transformer-icon.js';
 	import { createGlobeHorizon, withGlobeHorizon } from './globe-horizon.js';
 	import { foldMapBounds } from './map-bounds.js';
+	import { nearestLongitude, routeBounds, unwrapLongitudePath } from './antimeridian.js';
 	import { getAppState, getController } from './context.svelte.js';
 	import { displayFmt, fmt, rgbaCss } from './format.js';
 	import { getPanelLayout } from './panels.svelte.js';
@@ -83,6 +85,7 @@
 		cartoApiKey,
 		extraLayers = [],
 		attribution = 'compact',
+		declutterMarkers = true,
 		onMapReady,
 		onBasemapFallback,
 		onBasemapError
@@ -124,9 +127,16 @@
 		/** Attribution control mode. There is no off switch: tile licences
 		 * require the credit on screen. */
 		attribution?: 'compact' | 'full';
+		/** At low zoom, draw one bus marker per crowded spot: a generator before
+		 * a substation before any other bus, then the larger bus. Zooming in
+		 * shows the rest, and a selected bus always draws. `false` draws every
+		 * marker at every zoom. */
+		declutterMarkers?: boolean;
 		/** Called once the map and overlay exist, with an optional cleanup. It
 		 * fires again after a context-loss or basemap remount, after the previous
-		 * cleanup ran. */
+		 * cleanup ran. It runs before the first style loads, and a switch to the
+		 * fallback basemap does not call it again: the new style drops every
+		 * source and layer the host added, so add those on each `style.load`. */
 		onMapReady?: (map: MapLibreMap, overlay: MapLibreOverlay) => void | (() => void);
 		/** The primary basemap failed and the fallback was requested. The
 		 * reason's `from` and `to` name the providers (`'carto'`,
@@ -229,6 +239,11 @@
 	let mapGen = $state(0);
 	// Cap automatic remounts so sustained GPU pressure cannot loop forever.
 	let glRebuilds = 0;
+	// The zoom the bus markers are thinned at, in quarter steps, so panning
+	// never thins them again. A zoom gesture reads it at most every
+	// MARKER_ZOOM_SAMPLE_MS, and the end of every zoom reads it at once.
+	let markerZoom = $state(declutterZoom(DEFAULT_CAMERA.zoom));
+	const MARKER_ZOOM_SAMPLE_MS = 150;
 
 	type LayerCtors = {
 		PathLayer: typeof PathLayer;
@@ -438,6 +453,52 @@
 		return primary ? attachmentColor(primary) : busNeutral;
 	}
 
+	// The buses each bus layer could draw at the current zoom: with
+	// `declutterMarkers`, one per crowded spot (see declutterBuses). A generated
+	// grid's line taps are left out before thinning, and its bus kinds rank the
+	// buses. Selection is not read here, so selecting a bus thins nothing again.
+	const thinnedMarkers = $derived.by(() => {
+		const zoom = markerZoom;
+		const thin = (buses: NetworkBus[], kinds?: ReadonlyMap<number, string>) =>
+			declutterMarkers ? declutterBuses(buses, { zoom, kinds }) : buses;
+		const sets = new Map<string, NetworkBus[]>();
+		if (app.studyView) {
+			sets.set('study-buses', thin(app.studyView.network.buses));
+			return sets;
+		}
+		for (const c of app.cases) if (c.network) sets.set(`buses-${c.id}`, thin(c.network.buses));
+		for (const c of app.localCases) {
+			if (c.view) sets.set(`local-buses-${c.id}`, thin(c.markerBuses, c.busKinds));
+		}
+		return sets;
+	});
+	// The data of each bus layer: its thinned buses, plus the selected bus when
+	// thinning (or a line tap's missing marker) left it out, so it keeps its
+	// marker and selection ring. The arrays keep their identity until the zoom
+	// bucket or the selection changes them, so deck.gl does not rebuild the
+	// layer's attributes on every redraw.
+	const busMarkers = $derived.by(() => {
+		const selected = app.selectedBus;
+		const sets = new Map<string, NetworkBus[]>();
+		const add = (id: string, all: NetworkBus[], pinned: number | null) => {
+			const shown = thinnedMarkers.get(id);
+			if (shown) sets.set(id, withBus(shown, all, pinned));
+		};
+		if (app.studyView) {
+			add('study-buses', app.studyView.network.buses, selected);
+			return sets;
+		}
+		for (const c of app.cases) {
+			if (c.network)
+				add(`buses-${c.id}`, c.network.buses, c.id === app.activeCaseId ? selected : null);
+		}
+		for (const c of app.localCases) {
+			if (c.view)
+				add(`local-buses-${c.id}`, c.view.buses, c.id === app.activeLocalId ? selected : null);
+		}
+		return sets;
+	});
+
 	// Layers whose click selects something (a bus or a branch); the overlay-level
 	// click handler must not treat those clicks as "empty map" and clear the selection.
 	function isSelectableLayer(layerId: string | undefined): boolean {
@@ -473,7 +534,12 @@
 		const branch = displayedGeometry(caseId)?.branches.find((b) => b.id === branchId);
 		const path = branch?.path.filter(([lon, lat]) => Number.isFinite(lon) && Number.isFinite(lat));
 		return branch && path && path.length >= 2
-			? { key: `${app.studyView?.id ?? caseId}-${branch.id}`, caseId, branchId: branch.id, path }
+			? {
+					key: `${app.studyView?.id ?? caseId}-${branch.id}`,
+					caseId,
+					branchId: branch.id,
+					path: unwrapLongitudePath(path)
+				}
 			: null;
 	});
 	let selectedCueEl = $state.raw<HTMLDivElement | null>(null);
@@ -496,9 +562,16 @@
 	});
 	let multiDetailEl = $state.raw<SVGSVGElement | null>(null);
 
+	/** The screen point of a coordinate in the world copy nearest the camera.
+	 * MapLibre projects a longitude in the copy it names, so a point across the
+	 * antimeridian from the camera would land a whole world width away. */
+	function projectNear(m: MapLibreMap, [lon, lat]: [number, number]) {
+		return m.project([nearestLongitude(lon, m.getCenter().lng), lat]);
+	}
+
 	function syncSelectedCue() {
 		if (!map || !selectedCueEl || !selectedBusCue) return;
-		const point = map.project([selectedBusCue.lon, selectedBusCue.lat]);
+		const point = projectNear(map, [selectedBusCue.lon, selectedBusCue.lat]);
 		const { clientWidth, clientHeight } = map.getContainer();
 		const inRange =
 			point.x >= -40 &&
@@ -522,8 +595,12 @@
 		}
 		const activeMap = map;
 		const { clientWidth, clientHeight } = activeMap.getContainer();
+		// The path is unwrapped, so one shift by whole turns moves all of it to
+		// the world copy nearest the camera without breaking it at the seam.
+		const [lon0] = selectedBranchCue.path[0];
+		const shift = nearestLongitude(lon0, activeMap.getCenter().lng) - lon0;
 		const points = selectedBranchCue.path
-			.map(([lon, lat]) => activeMap.project([lon, lat]))
+			.map(([lon, lat]) => activeMap.project([lon + shift, lat]))
 			.filter((p) => Number.isFinite(p.x) && Number.isFinite(p.y));
 		if (clientWidth === 0 || clientHeight === 0 || points.length < 2) {
 			selectedBranchCueEl.style.display = 'none';
@@ -589,14 +666,14 @@
 			return;
 		}
 		const { bus, edges } = detail;
-		const busPt = m.project([bus.lon, bus.lat]);
+		const busPt = projectNear(m, [bus.lon, bus.lat]);
 
 		const STRAND_SPACING = 5;
 		let strands = '';
 		for (const e of edges) {
 			const selectedIsFrom = e.from === bus.id;
 			const other = selectedIsFrom ? e.path[e.path.length - 1] : e.path[0];
-			const b = m.project(other);
+			const b = projectNear(m, other);
 			const dx = b.x - busPt.x;
 			const dy = b.y - busPt.y;
 			const len = Math.hypot(dx, dy) || 1;
@@ -677,7 +754,7 @@
 	}
 
 	function branchBounds(path: [number, number][]): LngLatBoundsLike | null {
-		return foldMapBounds(path);
+		return routeBounds(path);
 	}
 
 	function prefersReducedMotion(): boolean {
@@ -948,6 +1025,18 @@
 					if (document.visibilityState === 'visible') repaint();
 				};
 				const syncCues = () => scheduleCueSync();
+				let zoomTimer: ReturnType<typeof setTimeout> | null = null;
+				const readZoom = () => {
+					if (zoomTimer !== null) {
+						clearTimeout(zoomTimer);
+						zoomTimer = null;
+					}
+					markerZoom = declutterZoom(m.getZoom());
+				};
+				const sampleZoom = () => {
+					zoomTimer ??= setTimeout(readZoom, MARKER_ZOOM_SAMPLE_MS);
+				};
+				readZoom();
 				const saveCamera = () => {
 					const center = m.getCenter();
 					app.camera = {
@@ -1005,6 +1094,9 @@
 				m.on('load', syncCues);
 				m.on('move', syncCues);
 				m.on('resize', syncCues);
+				// 'zoom' does not fire while the camera only pans.
+				m.on('zoom', sampleZoom);
+				m.on('zoomend', readZoom);
 
 				map = m;
 				overlay = o;
@@ -1020,6 +1112,9 @@
 					m.off('load', syncCues);
 					m.off('move', syncCues);
 					m.off('resize', syncCues);
+					m.off('zoom', sampleZoom);
+					m.off('zoomend', readZoom);
+					if (zoomTimer !== null) clearTimeout(zoomTimer);
 					m.off('style.load', applyStyleExtras);
 					detachFallback();
 					detachReady?.();
@@ -1077,6 +1172,12 @@
 	// Sync deck.gl layers with app state. New layer instances diff cheaply;
 	// updateTriggers tell deck.gl when accessor outputs changed. Host layers
 	// (`extraLayers`) draw after tellegen's own at both exits.
+	//
+	// Stored routes keep longitudes in [-180, 180], so a route across the
+	// antimeridian is unwrapped before drawing and each segment takes the
+	// short way. On the globe deck.gl ignores `wrapLongitude` and needs the
+	// unwrapped path itself; on the flat map `wrapLongitude` cuts the path at
+	// ±180 so both halves draw in every world copy.
 	$effect(() => {
 		if (!overlay || !layerCtors) return;
 		const { PathLayer, ScatterplotLayer, IconLayer } = layerCtors;
@@ -1108,7 +1209,8 @@
 				new PathLayer<NetworkBranch>({
 					id: 'study-branches',
 					data: study.network.branches,
-					getPath: (b) => b.path,
+					getPath: (b) => unwrapLongitudePath(b.path),
+					wrapLongitude: true,
 					getColor: (b) => branchColor(flows.get(b.id) ?? 0, b.status === 1),
 					getWidth: (b) => branchWidth(flows.get(b.id) ?? 0),
 					widthUnits: 'pixels',
@@ -1125,7 +1227,7 @@
 				}),
 				new ScatterplotLayer<NetworkBus>({
 					id: 'study-buses',
-					data: study.network.buses,
+					data: busMarkers.get('study-buses') ?? study.network.buses,
 					getPosition: (b) => [b.lon, b.lat],
 					getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
 					radiusUnits: marker.radiusUnits,
@@ -1163,7 +1265,8 @@
 				new PathLayer<NetworkBranch>({
 					id: `branches-${c.id}`,
 					data: c.network.branches,
-					getPath: (b) => b.path,
+					getPath: (b) => unwrapLongitudePath(b.path),
+					wrapLongitude: true,
 					// The selected branch draws in the selection blue of the bus halo cue,
 					// wider, so the price-rating source line reads at a glance.
 					getColor: (b) =>
@@ -1195,7 +1298,7 @@
 				}),
 				new ScatterplotLayer<NetworkBus>({
 					id: `buses-${c.id}`,
-					data: c.network.buses,
+					data: busMarkers.get(`buses-${c.id}`) ?? c.network.buses,
 					getPosition: (b) => [b.lon, b.lat],
 					getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
 					radiusUnits: marker.radiusUnits,
@@ -1230,7 +1333,9 @@
 		}
 		// Local cases are grey until the browser solve returns. A .pwd display
 		// file contributes substation points only, in a cooler slate so they
-		// read as diagram derived positions.
+		// read as diagram derived positions. A generated grid's line taps draw
+		// no marker, as their lines show them, unless one is the selected bus
+		// (see busMarkers).
 		for (const c of app.localCases) {
 			if (c.view) {
 				const d = display.get(c.id);
@@ -1238,7 +1343,8 @@
 					new PathLayer<NetworkBranch>({
 						id: `local-branches-${c.id}`,
 						data: c.view.branches,
-						getPath: (b) => b.path,
+						getPath: (b) => unwrapLongitudePath(b.path),
+						wrapLongitude: true,
 						getColor: (b) =>
 							c.id === app.activeLocalId && b.id === app.selectedBranch
 								? [47, 111, 187, 255]
@@ -1272,7 +1378,7 @@
 					}),
 					new ScatterplotLayer<NetworkBus>({
 						id: `local-buses-${c.id}`,
-						data: c.view.buses,
+						data: busMarkers.get(`local-buses-${c.id}`) ?? c.markerBuses,
 						getPosition: (b) => [b.lon, b.lat],
 						getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
 						radiusUnits: marker.radiusUnits,
@@ -1343,7 +1449,8 @@
 				new PathLayer<PlacedMultiEdge>({
 					id: `multi-edges-${c.id}`,
 					data: c.view.edges,
-					getPath: (e) => e.path,
+					getPath: (e) => unwrapLongitudePath(e.path),
+					wrapLongitude: true,
 					// The selected edge draws in the selection blue of the branch cue,
 					// wider, so its panel detail has an obvious source on the map.
 					getColor: (e) =>

package/dist/TellegenMap.svelte.d.ts

@@ -42,9 +42,16 @@ type $$ComponentProps = {
     /** Attribution control mode. There is no off switch: tile licences
      * require the credit on screen. */
     attribution?: 'compact' | 'full';
+    /** At low zoom, draw one bus marker per crowded spot: a generator before
+     * a substation before any other bus, then the larger bus. Zooming in
+     * shows the rest, and a selected bus always draws. `false` draws every
+     * marker at every zoom. */
+    declutterMarkers?: boolean;
     /** Called once the map and overlay exist, with an optional cleanup. It
      * fires again after a context-loss or basemap remount, after the previous
-     * cleanup ran. */
+     * cleanup ran. It runs before the first style loads, and a switch to the
+     * fallback basemap does not call it again: the new style drops every
+     * source and layer the host added, so add those on each `style.load`. */
     onMapReady?: (map: MapLibreMap, overlay: MapLibreOverlay) => void | (() => void);
     /** The primary basemap failed and the fallback was requested. The
      * reason's `from` and `to` name the providers (`'carto'`,

package/dist/antimeridian.d.ts

@@ -0,0 +1,21 @@
+/** Coordinate helpers for geographic paths drawn across the antimeridian.
+ *
+ * Stored longitudes stay in [-180, 180]. A drawn path is unwrapped so each
+ * vertex lies within 180° of the one before, and every segment takes the
+ * short way across ±180 instead of crossing the whole map.
+ */
+import { type MapBounds } from './map-bounds.js';
+export type LngLat = readonly [number, number];
+/** `lon` moved by whole turns of 360° to lie within 180° of `reference`.
+ * Returned unchanged when either value is not finite. */
+export declare function nearestLongitude(lon: number, reference: number): number;
+/** Return a display path whose consecutive longitudes differ by at most 180°.
+ * The returned longitudes may lie outside [-180, 180]; use only for drawing,
+ * never for serialization or exported GeoJSON. A vertex whose longitude is
+ * not finite is copied as it is and does not anchor the next one. */
+export declare function unwrapLongitudePath(path: readonly LngLat[]): [number, number][];
+/** Bounds of a stored route around its short arc, so a seam-crossing route
+ * frames the few degrees it spans rather than the whole world. West may lie
+ * below -180 or east above 180. Vertices `foldMapBounds` ignores are ignored
+ * here too. */
+export declare function routeBounds(path: readonly LngLat[]): MapBounds | null;

package/dist/antimeridian.js

@@ -0,0 +1,40 @@
+/** Coordinate helpers for geographic paths drawn across the antimeridian.
+ *
+ * Stored longitudes stay in [-180, 180]. A drawn path is unwrapped so each
+ * vertex lies within 180° of the one before, and every segment takes the
+ * short way across ±180 instead of crossing the whole map.
+ */
+import { isMapPoint, spanBounds } from './map-bounds.js';
+/** `lon` moved by whole turns of 360° to lie within 180° of `reference`.
+ * Returned unchanged when either value is not finite. */
+export function nearestLongitude(lon, reference) {
+    const delta = lon - reference;
+    if (!Number.isFinite(delta) || Math.abs(delta) <= 180)
+        return lon;
+    return lon - 360 * Math.round(delta / 360);
+}
+/** Return a display path whose consecutive longitudes differ by at most 180°.
+ * The returned longitudes may lie outside [-180, 180]; use only for drawing,
+ * never for serialization or exported GeoJSON. A vertex whose longitude is
+ * not finite is copied as it is and does not anchor the next one. */
+export function unwrapLongitudePath(path) {
+    const out = [];
+    let previous = null;
+    for (const [rawLongitude, latitude] of path) {
+        if (!Number.isFinite(rawLongitude)) {
+            out.push([rawLongitude, latitude]);
+            continue;
+        }
+        const longitude = previous === null ? rawLongitude : nearestLongitude(rawLongitude, previous);
+        out.push([longitude, latitude]);
+        previous = longitude;
+    }
+    return out;
+}
+/** Bounds of a stored route around its short arc, so a seam-crossing route
+ * frames the few degrees it spans rather than the whole world. West may lie
+ * below -180 or east above 180. Vertices `foldMapBounds` ignores are ignored
+ * here too. */
+export function routeBounds(path) {
+    return spanBounds(unwrapLongitudePath(path.filter(isMapPoint)));
+}

package/dist/basemap.d.ts

@@ -157,6 +157,10 @@ export interface BasemapMapLike {
     }): unknown;
     /** MapLibre types this `boolean | void`; only `true` counts as loaded. */
     isStyleLoaded(): boolean | void;
+    /** Read at every `style.load` to learn which sources the basemap style
+     * brings, before a host adds its own. Without it, every source counts as
+     * the basemap's. */
+    getStyle?(): StyleSpecification | undefined;
 }
 export interface BasemapFallbackHandlers {
     /** The primary failed and the fallback style was requested. `from` is the
@@ -185,6 +189,12 @@ export interface BasemapFallbackOptions {
  * 5. everything else is logged the way MapLibre logs an unhandled error,
  *    because registering this listener silences that default.
  *
+ * Rules 2 and 3 only count errors from the basemap style's own sources: the
+ * sources `map.getStyle()` lists when that style's `style.load` reaches this
+ * listener, so attach it before any listener that adds sources. A source the
+ * host adds later, through `onMapReady` for instance, falls under rule 5 and
+ * never switches the basemap.
+ *
  * After the switch the same rules report `onFailure` instead of switching
  * again, as they do when `spec.fallback` is `null`. Returns a detach
  * function. */

package/dist/basemap.js

@@ -169,6 +169,12 @@ function errorStatus(error) {
  * 5. everything else is logged the way MapLibre logs an unhandled error,
  *    because registering this listener silences that default.
  *
+ * Rules 2 and 3 only count errors from the basemap style's own sources: the
+ * sources `map.getStyle()` lists when that style's `style.load` reaches this
+ * listener, so attach it before any listener that adds sources. A source the
+ * host adds later, through `onMapReady` for instance, falls under rule 5 and
+ * never switches the basemap.
+ *
  * After the switch the same rules report `onFailure` instead of switching
  * again, as they do when `spec.fallback` is `null`. Returns a detach
  * function. */
@@ -176,7 +182,14 @@ export function attachBasemapFallback(map, spec, handlers = {}, options = {}) {
     const now = options.now ?? (() => Date.now());
     const primaryProvider = spec.primaryProvider ?? 'custom';
     const fallbackProvider = spec.fallback === null ? null : (spec.fallbackProvider ?? 'custom');
+    /** The source ids of the style on screen, or `null` while unknown, when
+     * every source counts as the basemap's. */
+    const styleSources = () => {
+        const style = map.getStyle?.();
+        return style ? new Set(Object.keys(style.sources ?? {})) : null;
+    };
     let styleLoaded = map.isStyleLoaded() === true;
+    let basemapSources = styleLoaded ? styleSources() : null;
     let fellBack = false;
     let failed = false;
     let tileFailures = 0;
@@ -196,6 +209,7 @@ export function attachBasemapFallback(map, spec, handlers = {}, options = {}) {
         }
         fellBack = true;
         styleLoaded = false;
+        basemapSources = null;
         tileFailures = 0;
         tileArrived = false;
         handlers.onFallback?.({ ...reason, from: primaryProvider, to: fallbackProvider });
@@ -206,6 +220,7 @@ export function attachBasemapFallback(map, spec, handlers = {}, options = {}) {
     };
     const onStyleLoad = () => {
         styleLoaded = true;
+        basemapSources = styleSources();
     };
     const onSourceData = (event) => {
         if (event?.tile || event?.isSourceLoaded === true)
@@ -227,6 +242,11 @@ export function attachBasemapFallback(map, spec, handlers = {}, options = {}) {
             passThrough(event);
             return;
         }
+        // A host's own source failing says nothing about the basemap.
+        if (basemapSources !== null && !basemapSources.has(sourceId)) {
+            passThrough(event);
+            return;
+        }
         if ((status !== undefined && FORBIDDEN_STATUSES.has(status)) ||
             FORBIDDEN_MESSAGE.test(message)) {
             fallBack({ kind: 'source-forbidden', message, status: status ?? 0, sourceId });

package/dist/bus-kinds.d.ts

@@ -0,0 +1,15 @@
+import type { NetworkBus } from './api.js';
+/** Each bus's kind as a generated grid records it, by bus id: `generator`,
+ * `substation`, `converter`, `load` or `tap`. tellegen-synth writes the kind
+ * in each bus row's `extras.tellegen_synth.kind`; the map view does not carry
+ * it. Empty for any other module, and for text that does not parse. */
+export declare function readBusKinds(moduleJson: string | null | undefined): ReadonlyMap<number, string>;
+/** Ids of the buses in `kinds` that are line taps: points where a line is
+ * tapped, with no load or machine. */
+export declare function tapsOf(kinds: ReadonlyMap<number, string>): ReadonlySet<number>;
+/** Ids of the buses a generated grid marks as line taps. Empty for any other
+ * module, and for text that does not parse. */
+export declare function tapBusIds(moduleJson: string | null | undefined): ReadonlySet<number>;
+/** `buses` less the taps, the ones the map draws as markers. The same array
+ * when there is no tap to drop, so the map layer keeps its data. */
+export declare function withoutTaps(buses: NetworkBus[], taps: ReadonlySet<number>): NetworkBus[];

package/dist/bus-kinds.js

@@ -0,0 +1,47 @@
+/** The `extras` key under which tellegen-synth records each element's
+ * annotation in the modules it writes. */
+const SYNTH_EXTRAS = 'tellegen_synth';
+/** Each bus's kind as a generated grid records it, by bus id: `generator`,
+ * `substation`, `converter`, `load` or `tap`. tellegen-synth writes the kind
+ * in each bus row's `extras.tellegen_synth.kind`; the map view does not carry
+ * it. Empty for any other module, and for text that does not parse. */
+export function readBusKinds(moduleJson) {
+    const kinds = new Map();
+    // Only a module tellegen-synth wrote is parsed a second time.
+    if (!moduleJson?.includes(`"${SYNTH_EXTRAS}"`))
+        return kinds;
+    let buses;
+    try {
+        buses = JSON.parse(moduleJson)?.value?.data?.buses;
+    }
+    catch {
+        return kinds;
+    }
+    if (!Array.isArray(buses))
+        return kinds;
+    for (const bus of buses) {
+        const kind = bus?.extras?.[SYNTH_EXTRAS]?.kind;
+        if (typeof bus?.id === 'number' && typeof kind === 'string')
+            kinds.set(bus.id, kind);
+    }
+    return kinds;
+}
+/** Ids of the buses in `kinds` that are line taps: points where a line is
+ * tapped, with no load or machine. */
+export function tapsOf(kinds) {
+    const ids = new Set();
+    for (const [id, kind] of kinds)
+        if (kind === 'tap')
+            ids.add(id);
+    return ids;
+}
+/** Ids of the buses a generated grid marks as line taps. Empty for any other
+ * module, and for text that does not parse. */
+export function tapBusIds(moduleJson) {
+    return tapsOf(readBusKinds(moduleJson));
+}
+/** `buses` less the taps, the ones the map draws as markers. The same array
+ * when there is no tap to drop, so the map layer keeps its data. */
+export function withoutTaps(buses, taps) {
+    return taps.size === 0 ? buses : buses.filter((b) => !taps.has(b.id));
+}

package/dist/declutter.d.ts

@@ -0,0 +1,52 @@
+/** Bus fields the declutter reads. `NetworkBus` has all of them. */
+export interface DeclutterBus {
+    id: number;
+    lon: number;
+    lat: number;
+    demand_mw: number;
+    gen_mw: number;
+}
+export interface DeclutterOptions {
+    /** Map zoom the cells are laid out at. Pass a bucketed zoom
+     * (`declutterZoom`) so small camera moves keep the same result. */
+    zoom: number;
+    /** Cell side in CSS pixels. Each cell keeps one bus. */
+    cellPx?: number;
+    /** Bus kinds by id, as tellegen-synth records them (`generator`,
+     * `substation`, `converter`, `load`, `tap`). Without them, buses rank by
+     * power alone. */
+    kinds?: ReadonlyMap<number, string>;
+}
+/** Default cell side in CSS pixels: about twice the diameter of the marker
+ * for a bus of up to about 10 MW. */
+export declare const DECLUTTER_CELL_PX = 16;
+/** Zoom step the map lays its cells out at. */
+export declare const DECLUTTER_ZOOM_STEP = 0.25;
+/** `zoom` rounded down to a whole `step`, so panning and small zooms land on
+ * the same value and leave the thinned markers as they are. */
+export declare function declutterZoom(zoom: number, step?: number): number;
+/** How strongly a bus kind claims its cell: a generator before a substation
+ * or converter station, before anything else. */
+export declare function kindRank(kind: string | undefined): number;
+/** The buses a map at `zoom` draws markers for, so that a crowded grid does
+ * not cover the map. Each bus is placed in Web Mercator world pixels (at a
+ * MapLibre zoom the world is 512·2^zoom CSS pixels square) and binned into
+ * square cells of `cellPx`; each cell keeps its strongest bus. A generator
+ * outranks a substation or converter, which outranks any other bus. Then the
+ * larger |generation| + |demand| wins, then the lower id, so the result does
+ * not depend on the input order. The selection is not an input: `withBus`
+ * adds a selected bus back on top, so selecting one never hides another.
+ *
+ * The kept buses come back in input order. When no two buses share a cell,
+ * the input array itself comes back, so a map layer keeps its data. Longitudes
+ * wrap, so 190 and -170 share a cell, and the cells tile the world with ±180
+ * on a cell edge, so the seam thins like any other place. Latitudes clamp to
+ * the Mercator limit. A bus without finite coordinates is kept, as there is no
+ * cell to place it in. */
+export declare function declutterBuses<T extends DeclutterBus>(buses: T[], options: DeclutterOptions): T[];
+/** `shown` with bus `id` from `all` added at the end when it is missing, so a
+ * selected bus that the map thinned out, or a line tap it never draws, still
+ * gets its marker. `shown` itself when there is nothing to add. */
+export declare function withBus<T extends {
+    id: number;
+}>(shown: T[], all: readonly T[], id: number | null | undefined): T[];

package/dist/declutter.js

@@ -0,0 +1,95 @@
+/** Default cell side in CSS pixels: about twice the diameter of the marker
+ * for a bus of up to about 10 MW. */
+export const DECLUTTER_CELL_PX = 16;
+/** Zoom step the map lays its cells out at. */
+export const DECLUTTER_ZOOM_STEP = 0.25;
+// The Web Mercator world is this many CSS pixels across at zoom 0, as MapLibre
+// and deck.gl lay it out.
+const WORLD_PX = 512;
+// Web Mercator's latitude limit, where the square world ends.
+const MAX_LAT = 85.0511287798066;
+/** `zoom` rounded down to a whole `step`, so panning and small zooms land on
+ * the same value and leave the thinned markers as they are. */
+export function declutterZoom(zoom, step = DECLUTTER_ZOOM_STEP) {
+    // Snap first, so 4.75 / 0.25 does not land a hair under 19.
+    return Math.floor(Math.round((zoom / step) * 1e6) / 1e6) * step;
+}
+/** How strongly a bus kind claims its cell: a generator before a substation
+ * or converter station, before anything else. */
+export function kindRank(kind) {
+    if (kind === 'generator')
+        return 2;
+    if (kind === 'substation' || kind === 'converter')
+        return 1;
+    return 0;
+}
+function busPower(bus) {
+    const power = Math.abs(bus.gen_mw) + Math.abs(bus.demand_mw);
+    return Number.isFinite(power) ? power : 0;
+}
+/** The buses a map at `zoom` draws markers for, so that a crowded grid does
+ * not cover the map. Each bus is placed in Web Mercator world pixels (at a
+ * MapLibre zoom the world is 512·2^zoom CSS pixels square) and binned into
+ * square cells of `cellPx`; each cell keeps its strongest bus. A generator
+ * outranks a substation or converter, which outranks any other bus. Then the
+ * larger |generation| + |demand| wins, then the lower id, so the result does
+ * not depend on the input order. The selection is not an input: `withBus`
+ * adds a selected bus back on top, so selecting one never hides another.
+ *
+ * The kept buses come back in input order. When no two buses share a cell,
+ * the input array itself comes back, so a map layer keeps its data. Longitudes
+ * wrap, so 190 and -170 share a cell, and the cells tile the world with ±180
+ * on a cell edge, so the seam thins like any other place. Latitudes clamp to
+ * the Mercator limit. A bus without finite coordinates is kept, as there is no
+ * cell to place it in. */
+export function declutterBuses(buses, options) {
+    const { zoom, cellPx = DECLUTTER_CELL_PX, kinds } = options;
+    if (buses.length < 2 || !Number.isFinite(zoom) || !(cellPx > 0))
+        return buses;
+    const world = WORLD_PX * 2 ** zoom;
+    // A whole number of columns, so the cells tile the world without a sliver
+    // at the seam.
+    const columns = Math.max(1, Math.round(world / cellPx));
+    // Past about zoom 21 a 16 px cell is under a metre across, and its key
+    // would outgrow exact integers. Nothing needs thinning there.
+    if (!Number.isSafeInteger(columns * columns))
+        return buses;
+    const cell = world / columns;
+    const rank = (bus) => (kinds ? kindRank(kinds.get(bus.id)) : 0);
+    const outranks = (a, b) => {
+        const byKind = rank(a) - rank(b);
+        if (byKind !== 0)
+            return byKind > 0;
+        const byPower = busPower(a) - busPower(b);
+        if (byPower !== 0)
+            return byPower > 0;
+        return a.id < b.id;
+    };
+    const winners = new Map();
+    for (const bus of buses) {
+        const { lon, lat } = bus;
+        if (!Number.isFinite(lon) || !Number.isFinite(lat))
+            continue;
+        const x = ((((lon + 180) % 360) + 360) % 360) / 360;
+        const phi = (Math.max(-MAX_LAT, Math.min(MAX_LAT, lat)) * Math.PI) / 180;
+        const y = 0.5 - Math.log(Math.tan(Math.PI / 4 + phi / 2)) / (2 * Math.PI);
+        const column = Math.floor((x * world) / cell) % columns;
+        const row = Math.min(columns - 1, Math.max(0, Math.floor((y * world) / cell)));
+        const key = row * columns + column;
+        const held = winners.get(key);
+        if (!held || outranks(bus, held))
+            winners.set(key, bus);
+    }
+    const kept = new Set(winners.values());
+    const shown = buses.filter((bus) => kept.has(bus) || !Number.isFinite(bus.lon) || !Number.isFinite(bus.lat));
+    return shown.length === buses.length ? buses : shown;
+}
+/** `shown` with bus `id` from `all` added at the end when it is missing, so a
+ * selected bus that the map thinned out, or a line tap it never draws, still
+ * gets its marker. `shown` itself when there is nothing to add. */
+export function withBus(shown, all, id) {
+    if (id === null || id === undefined || shown.some((bus) => bus.id === id))
+        return shown;
+    const bus = all.find((b) => b.id === id);
+    return bus ? [...shown, bus] : shown;
+}

package/dist/map-bounds.d.ts

@@ -1,5 +1,13 @@
 export type MapBounds = [[number, number], [number, number]];
+/** Whether a point can be framed on a Web Mercator map: finite, longitude in
+ * [-180, 180], latitude inside the projection's ±85.05° limit. */
+export declare function isMapPoint([lon, lat]: readonly [number, number]): boolean;
 /** Fold finite Web Mercator coordinates into map bounds. Invalid points are
  * ignored so one malformed row cannot hide an otherwise usable network, and a
  * single surviving point still yields a box `fitBounds` can frame. */
 export declare function foldMapBounds(points: Iterable<readonly [number, number]>): MapBounds | null;
+/** The box around points already checked, or `null` when there are none. An
+ * axis that collapsed to a single value is padded so `fitBounds` can frame
+ * it. Longitudes are taken as they are, so an unwrapped route may give a west
+ * edge below -180 or an east edge above 180. */
+export declare function spanBounds(points: Iterable<readonly [number, number]>): MapBounds | null;

package/dist/map-bounds.js

@@ -2,23 +2,36 @@
  * zero-span box makes `fitBounds` divide by zero, clamp to the map's maximum
  * zoom, and slam the camera onto one point instead of framing it. */
 const DEGENERATE_PAD_DEGREES = 0.005;
+/** Whether a point can be framed on a Web Mercator map: finite, longitude in
+ * [-180, 180], latitude inside the projection's ±85.05° limit. */
+export function isMapPoint([lon, lat]) {
+    return (Number.isFinite(lon) &&
+        Number.isFinite(lat) &&
+        lon >= -180 &&
+        lon <= 180 &&
+        lat >= -85.05 &&
+        lat <= 85.05);
+}
 /** Fold finite Web Mercator coordinates into map bounds. Invalid points are
  * ignored so one malformed row cannot hide an otherwise usable network, and a
  * single surviving point still yields a box `fitBounds` can frame. */
 export function foldMapBounds(points) {
+    const kept = [];
+    for (const point of points)
+        if (isMapPoint(point))
+            kept.push(point);
+    return spanBounds(kept);
+}
+/** The box around points already checked, or `null` when there are none. An
+ * axis that collapsed to a single value is padded so `fitBounds` can frame
+ * it. Longitudes are taken as they are, so an unwrapped route may give a west
+ * edge below -180 or an east edge above 180. */
+export function spanBounds(points) {
     let minLon = Infinity;
     let minLat = Infinity;
     let maxLon = -Infinity;
     let maxLat = -Infinity;
     for (const [lon, lat] of points) {
-        if (!Number.isFinite(lon) ||
-            !Number.isFinite(lat) ||
-            lon < -180 ||
-            lon > 180 ||
-            lat < -85.05 ||
-            lat > 85.05) {
-            continue;
-        }
         minLon = Math.min(minLon, lon);
         minLat = Math.min(minLat, lat);
         maxLon = Math.max(maxLon, lon);

package/dist/state.svelte.d.ts

@@ -95,6 +95,15 @@ export declare class LocalCase {
     coordsKind: CoordsKind | undefined;
     /** Map geometry when the file carried or received coordinates. */
     view: LocalView | null;
+    /** Each bus's kind in a generated grid, by bus id (`generator`,
+     * `substation`, `converter`, `load`, `tap`); empty for any other case. At
+     * low zoom the map keeps generators and substations over other buses. */
+    readonly busKinds: ReadonlyMap<number, string>;
+    /** Buses a generated grid marks as line taps. The map draws no marker for
+     * them; the bus picker and the selection still reach them. */
+    readonly tapBuses: ReadonlySet<number>;
+    /** `view.buses` less the line taps: the buses the map draws as markers. */
+    readonly markerBuses: NetworkBus[];
     syntheticCenter: {
         lon: number;
         lat: number;

package/dist/state.svelte.js

@@ -1,4 +1,5 @@
 import { DEFAULT_MC_PF_OPTIONS, summarizeMcExcludedIslands } from '@tellegen/engine';
+import { readBusKinds, tapsOf, withoutTaps } from './bus-kinds.js';
 import { DEFAULT_FORMULATION } from '@tellegen/engine';
 import { DiagnosticLog, errorEntry } from './log.svelte.js';
 import { graphInputs } from './diagram/graph-inputs.js';
@@ -27,6 +28,15 @@ export class LocalCase {
     coordsKind = $state.raw(undefined);
     /** Map geometry when the file carried or received coordinates. */
     view = $state.raw(null);
+    /** Each bus's kind in a generated grid, by bus id (`generator`,
+     * `substation`, `converter`, `load`, `tap`); empty for any other case. At
+     * low zoom the map keeps generators and substations over other buses. */
+    busKinds = $derived(readBusKinds(this.studyInputJson));
+    /** Buses a generated grid marks as line taps. The map draws no marker for
+     * them; the bus picker and the selection still reach them. */
+    tapBuses = $derived(tapsOf(this.busKinds));
+    /** `view.buses` less the line taps: the buses the map draws as markers. */
+    markerBuses = $derived(withoutTaps(this.view?.buses ?? [], this.tapBuses));
     syntheticCenter = $state.raw(undefined);
     diagram = $state.raw(null);
     displayMode = $state('geographic');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellegen/svelte",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Svelte components for tellegen power system maps, local case files, and browser solves.",
   "keywords": [
     "svelte",
@@ -67,7 +67,7 @@
     "pack:dry-run": "npm pack --dry-run --cache ../../node_modules/.cache/npm-pack"
   },
   "dependencies": {
-    "@tellegen/engine": "^0.5.0"
+    "@tellegen/engine": "^0.6.0"
   },
   "peerDependencies": {
     "@deck.gl/core": "^9.4.0",
@@ -77,16 +77,16 @@
     "svelte": ">=5.30 <6"
   },
   "devDependencies": {
-    "@deck.gl/core": "^9.4.0",
-    "@deck.gl/layers": "^9.4.0",
-    "@deck.gl/maplibre": "^9.4.0",
-    "@sveltejs/package": "^3.0.1",
+    "@deck.gl/core": "^9.4.1",
+    "@deck.gl/layers": "^9.4.1",
+    "@deck.gl/maplibre": "^9.4.1",
+    "@sveltejs/package": "^3.0.2",
     "@sveltejs/vite-plugin-svelte": "^7.3.1",
-    "maplibre-gl": "^6.15.0",
-    "svelte": "^5.57.2",
-    "svelte-check": "^4.7.7",
+    "maplibre-gl": "^6.16.0",
+    "svelte": "^5.57.3",
+    "svelte-check": "^4.7.8",
     "typescript": "^6.0.3",
     "vite": "^8.3.1",
-    "vitest": "^5.0.2"
+    "vitest": "^5.1.0"
   }
 }