@tellegen/svelte 0.4.0 → 0.4.2

package/README.md

@@ -3,9 +3,13 @@
 Svelte components for tellegen maps, case panels, local case files, and browser solves.
 
 ```sh
-npm install @tellegen/svelte
+npm install @tellegen/svelte maplibre-gl @deck.gl/core @deck.gl/layers @deck.gl/maplibre
 ```
 
+`maplibre-gl` and the three `@deck.gl` packages are peer dependencies: the map
+shares their instances with the host through `extraLayers` and `onMapReady`, so
+the app installs them and resolves one copy of each.
+
 Import the component and stylesheet in your app:
 
 ```svelte
@@ -41,6 +45,10 @@ remain in the browser on this path.
 - `orgLabel`
 - `showFooter`, default `true`
 - `theme`, `light` (default) or `dark`
+- `cartoApiKey`, the basemap key (see [Basemap](#basemap))
+
+`theme` and `cartoApiKey` follow their props. The others are read once, when
+the viewer mounts; remount it to change them.
 
 Use `TellegenProvider` and `TellegenShell` when state should survive route changes:
 
@@ -55,6 +63,11 @@ Use `TellegenProvider` and `TellegenShell` when state should survive route chang
 </TellegenProvider>
 ```
 
+The provider owns the controller and its cases. Unmounting it disposes the
+controller, which frees every case's browser Study and multiconductor session
+in the engine worker, so a provider that should keep its cases across pages
+belongs in a layout that stays mounted.
+
 ## Panel layout
 
 The shell docks Network and Studies on the left, and Solver and Agent on the
@@ -123,6 +136,19 @@ inside `TellegenProvider`:
 <PanelFrame id="region" title="Region" side="left">...</PanelFrame>
 ```
 
+The components show data, labels and controls, not host copy. A host that
+wants a note under a local case's stats passes `ControlPanel` a `caseNote`
+snippet, which receives the case; `DropZone` renders its children under the
+drop prompt:
+
+```svelte
+<ControlPanel>
+  {#snippet caseNote(lc)}
+    <p>{lc.label} is a synthetic grid.</p>
+  {/snippet}
+</ControlPanel>
+```
+
 `ShellEnvironment` is renderless and keeps the compact-layout, pointer and
 viewport state in step, as the default shell does. `PanelHost` reads
 `--tellegen-dock-left`, `--tellegen-dock-right` and `--tellegen-dock-bottom`
@@ -193,7 +219,8 @@ besides its click callbacks:
 - `attribution`: `'compact'` (default) or `'full'`. There is no off switch.
 - `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.
+  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.
 - `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
@@ -201,7 +228,8 @@ besides its click callbacks:
   `reason.to` is `null`.
 
 `TellegenProvider` and `TellegenViewer` also take `cartoApiKey`, and pass it,
-together with `theme`, to the default shell's map. A SvelteKit 3 host can
+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
 declare the key as an optional public build-time variable:
 
 ```ts
@@ -251,13 +279,13 @@ tiles, fonts and sprites are all fetched. The engine underneath also needs
 `script-src 'wasm-unsafe-eval'` (never `'unsafe-eval'`) and `worker-src
 'self'`, since its workers are same-origin.
 
-A host that passes its own deck.gl layers in `extraLayers`, or works with the
-MapLibre map from `onMapReady`, must resolve one copy each of
-`@deck.gl/core`, `@deck.gl/layers`, `@deck.gl/maplibre` and `maplibre-gl`.
-When two deck.gl versions load, deck.gl throws "multiple versions detected".
-If the host's ranges differ from this package's (`^9.4.0` for deck.gl,
-`^6.15.0` for maplibre-gl), point both at one version with npm `overrides`
-(or `resolutions` in pnpm and Yarn).
+`@deck.gl/core`, `@deck.gl/layers`, `@deck.gl/maplibre` and `maplibre-gl`
+are peer dependencies (`^9.4.0` for deck.gl, `^6.15.0` for maplibre-gl), so
+the host's copies are the ones the map uses, including the deck.gl layers it
+passes in `extraLayers` and the MapLibre map it gets from `onMapReady`. When
+two deck.gl versions load, deck.gl throws "multiple versions detected"; if
+another dependency pulls in a second copy, point both at one version with npm
+`overrides` (or `resolutions` in pnpm and Yarn).
 
 The map needs no Vite settings, in a build or in the dev server. MapLibre's
 worker comes from a `?worker&url` import, which a production build bundles

package/dist/Sparkline.svelte

@@ -35,7 +35,7 @@
 		viewBox="0 0 {W} {H}"
 		preserveAspectRatio="none"
 		role="img"
-		aria-label="residual by solver iteration"
+		aria-label="Residual by solver iteration"
 	>
 		<line class="axis" x1={L} y1={T} x2={L} y2={H - B} />
 		<line class="axis" x1={L} y1={H - B} x2={W - R} y2={H - B} />
@@ -46,9 +46,9 @@
 			text-anchor="middle"
 			transform="rotate(-90)"
 		>
-			residual
+			Residual
 		</text>
-		<text class="axis-label x-label" x={W - R} y={H - 4} text-anchor="end">iterations</text>
+		<text class="axis-label x-label" x={W - R} y={H - 4} text-anchor="end">Iterations</text>
 		<polyline {points} pathLength="1" />
 	</svg>
 {/if}
@@ -69,7 +69,7 @@
 
 	.axis-label {
 		fill: var(--text-tertiary);
-		font-family: var(--font-mono);
+		font-family: var(--font-display);
 		font-size: 12px;
 		letter-spacing: 0;
 	}

package/dist/TellegenMap.svelte

@@ -10,8 +10,10 @@
 		MAP_PALETTE,
 		branchColor,
 		branchWidth,
+		busMarkerRadius,
 		busNeutral,
-		busRadius,
+		busRadiusFor,
+		demandColor,
 		priceColor,
 		scalarDomain,
 		sensColor,
@@ -31,7 +33,7 @@
 	} from './basemap.js';
 	import { caseDeltas, caseRatings, displayMetaFor, displaySeriesFor } from './display.js';
 	import {
-		CaseState,
+		type CaseState,
 		type CameraSnapshot,
 		type DisplayMode,
 		type LocalCase
@@ -391,6 +393,8 @@
 				if (d.previewDomain.flat) return sensFlatColor(d.previewDomain);
 				return sensColor((d.preview.get(bus.id) ?? 0) / d.previewDomain.scale);
 			}
+			if (d.scalarMode === 'demand')
+				return demandColor(((d.scalar.get(bus.id) ?? 0) - d.scalarLo) / (d.scalarHi - d.scalarLo));
 			const mid = (d.scalarLo + d.scalarHi) / 2;
 			return priceColor(((d.scalar.get(bus.id) ?? mid) - d.scalarLo) / (d.scalarHi - d.scalarLo));
 		};
@@ -706,13 +710,13 @@
 			if (info.layer.id === 'study-branches') {
 				const flow = view?.flows?.find((f) => f.branch === id);
 				return {
-					html: `<b>branch ${id}</b><br>saved state: ${esc(app.studyView.label)}${flow ? `<br>P from ${flow.pf.toFixed(3)} MW, loading ${(100 * flow.loading).toFixed(1)}%` : ''}`
+					html: `<b>Branch ${id}</b><br>Saved state: ${esc(app.studyView.label)}${flow ? `<br>P from ${flow.pf.toFixed(3)} MW<br>Loading ${(100 * flow.loading).toFixed(1)}%` : ''}`
 				};
 			}
 			const p = view?.lmp?.find((v) => v.bus === id),
 				v = view?.vm?.find((v) => v.bus === id);
 			return {
-				html: `<b>bus ${id}</b><br>saved state: ${esc(app.studyView.label)}${p ? `<br>LMP ${p.value.toFixed(4)}` : ''}${v ? `<br>voltage ${v.value.toFixed(5)} pu` : ''}`
+				html: `<b>Bus ${id}</b><br>Saved state: ${esc(app.studyView.label)}${p ? `<br>LMP ${p.value.toFixed(4)}` : ''}${v ? `<br>Voltage ${v.value.toFixed(5)} pu` : ''}`
 			};
 		}
 		if (info.layer?.id.startsWith('local-subs-')) {
@@ -722,25 +726,22 @@
 			const s = object as { number: number; name: string };
 			const named = s.name ? ` ${esc(s.name)}` : '';
 			return {
-				html: `<div class="tt"><b>substation ${Number(s.number)}</b>${named}<br><span style="opacity:0.6">.pwd diagram, approximate position</span></div>`
+				html: `<div class="tt"><b>Substation ${Number(s.number)}</b>${named}<br>Approximate position</div>`
 			};
 		}
 		const layerId = info.layer?.id;
 		if (layerId?.startsWith('multi-edges-')) {
 			const e = object as PlacedMultiEdge;
-			const state = e.kind === 'switch' ? (e.closed ? ' &#8901; closed' : ' &#8901; open') : '';
+			const state = e.kind === 'switch' ? (e.closed ? '<br>Closed' : '<br>Open') : '';
 			return {
-				html: `<div class="tt"><b>${esc(e.kind)} ${esc(e.from)}&#8201;&ndash;&#8201;${esc(e.to)}</b> ${e.n_phases}&#8202;&phi;${state}</div>`
+				html: `<div class="tt"><b>${esc(e.kind)} ${esc(e.from)}&#8201;&ndash;&#8201;${esc(e.to)}</b><br>${e.n_phases}&#8202;&phi;${state}</div>`
 			};
 		}
 		if (layerId?.startsWith('multi-buses-')) {
 			const b = object as PlacedMultiBus;
-			const roles = b.attachmentKinds.length ? b.attachmentKinds.join(', ') : 'none';
+			const roles = b.attachmentKinds.length ? b.attachmentKinds.join(', ') : 'None';
 			return {
-				html: `<div class="tt"><b>bus ${esc(b.id)}</b>
-					${b.terminals.length} terminals${b.grounded.length ? ` &#8901; ${b.grounded.length} grounded` : ''}<br>
-					load ${b.load_kw.toFixed(0)} kW &#8901; gen ${b.gen_kw.toFixed(0)} kW<br>
-					<span style="opacity:0.6">${esc(roles)}</span></div>`
+				html: `<div class="tt"><b>Bus ${esc(b.id)}</b><br>${b.terminals.length} terminals${b.grounded.length ? `, ${b.grounded.length} grounded` : ''}<br>Load ${b.load_kw.toFixed(0)} kW<br>Generation ${b.gen_kw.toFixed(0)} kW<br>Attachments: ${esc(roles)}</div>`
 			};
 		}
 		const c = caseOf(info);
@@ -749,17 +750,15 @@
 			const b = object as NetworkBranch;
 			const flow = d
 				? `${((d.loading.get(b.id) ?? 0) * 100).toFixed(0)}% of ${b.rate_mw.toFixed(0)} MW`
-				: `rate ${b.rate_mw.toFixed(0)} MW`;
+				: `Rating ${b.rate_mw.toFixed(0)} MW`;
 			return {
-				html: `<div class="tt"><b>line ${b.from}&#8201;&ndash;&#8201;${b.to}</b> ${flow}</div>`
+				html: `<div class="tt"><b>Line ${b.from}&#8201;&ndash;&#8201;${b.to}</b><br>${flow}</div>`
 			};
 		}
 		const bus = object as NetworkBus;
 		if (!c) {
 			return {
-				html: `<div class="tt"><b>bus ${bus.id}</b>
-					load ${bus.demand_mw.toFixed(0)} MW &#8901; gen ${bus.gen_mw.toFixed(0)} MW<br>
-					<span style="opacity:0.6">local file</span></div>`
+				html: `<div class="tt"><b>Bus ${bus.id}</b><br>Load ${bus.demand_mw.toFixed(0)} MW<br>Generation ${bus.gen_mw.toFixed(0)} MW</div>`
 			};
 		}
 		const price = d?.prices.get(bus.id);
@@ -769,8 +768,8 @@
 		const delta = caseDeltas(c)[bus.id] ?? 0;
 		const loadRow =
 			delta === 0
-				? `load ${bus.demand_mw.toFixed(0)} MW`
-				: `load ${(bus.demand_mw + delta).toFixed(0)} MW (${delta > 0 ? '+' : ''}${delta.toFixed(0)})`;
+				? `Load ${bus.demand_mw.toFixed(0)} MW`
+				: `Load ${(bus.demand_mw + delta).toFixed(0)} MW (${delta > 0 ? '+' : ''}${delta.toFixed(0)})`;
 		const sensRow =
 			sens === undefined
 				? ''
@@ -779,18 +778,15 @@
 			preview === undefined
 				? ''
 				: `<br>&Delta; LMP ${preview >= 0 ? '+' : ''}${preview.toExponential(2)} objective units/MW`;
-		const localRow =
-			c instanceof CaseState ? '' : '<br><span style="opacity:0.6">local file</span>';
+		// Demand already has its own row below, so the demand colouring shows LMP here alone.
 		const scalarRow =
-			!d || d.scalarMode === 'price'
+			!d || d.scalarMode === 'price' || d.scalarMode === 'demand'
 				? `LMP ${price === undefined ? '&mdash;' : fmt.format(price)} objective units/MW`
 				: `${d.scalarLabel} ${
 						scalar === undefined ? '&mdash;' : displayFmt(d.scalarMode, scalar)
 					} ${d.scalarUnit}<br>LMP ${price === undefined ? '&mdash;' : fmt.format(price)} objective units/MW`;
 		return {
-			html: `<div class="tt"><b>bus ${bus.id}</b>
-				${scalarRow}<br>
-				${loadRow} &#8901; gen ${bus.gen_mw.toFixed(0)} MW${sensRow}${previewRow}${localRow}</div>`
+			html: `<div class="tt"><b>Bus ${bus.id}</b><br>${scalarRow}<br>${loadRow}<br>Generation ${bus.gen_mw.toFixed(0)} MW${sensRow}${previewRow}</div>`
 		};
 	}
 
@@ -987,25 +983,9 @@
 
 				map = m;
 				overlay = o;
-				const detachReady = onMapReady?.(m, o);
-				// Frame the active grid once the map is ready. The initial frame request
-				// (from the case load) can fire before the async map import finishes and
-				// be lost; re-issuing it here ensures the first view is the active case,
-				// not the default world view. A rebuilt map opens at the default view
-				// too, so it restores the camera the last map saved.
-				if (restoreCamera && app.camera) m.jumpTo(app.camera);
-				else if (app.cameraSeq === handledCameraSeq)
-					app.requestFrame(app.activeCaseId ?? app.activeLocalId ?? 'all');
-				if (mapGen > 0) {
-					// This is a rebuilt map. Once it has held a live context without
-					// another loss, zero the budget so the cap only ever catches a tight
-					// loss loop, not recoveries spread across a long session.
-					stabilizeTimer = setTimeout(() => {
-						glRebuilds = 0;
-						stabilizeTimer = null;
-					}, 10000);
-				}
-
+				// Assign the teardown before host code runs: if onMapReady throws,
+				// the map and its window and document listeners are still released.
+				let detachReady: void | (() => void);
 				cleanup = () => {
 					clearRebuild();
 					clearStabilize();
@@ -1023,6 +1003,24 @@
 					map = null;
 					overlay = null;
 				};
+				detachReady = onMapReady?.(m, o);
+				// Frame the active grid once the map is ready. The initial frame request
+				// (from the case load) can fire before the async map import finishes and
+				// be lost; re-issuing it here ensures the first view is the active case,
+				// not the default world view. A rebuilt map opens at the default view
+				// too, so it restores the camera the last map saved.
+				if (restoreCamera && app.camera) m.jumpTo(app.camera);
+				else if (app.cameraSeq === handledCameraSeq)
+					app.requestFrame(app.activeCaseId ?? app.activeLocalId ?? 'all');
+				if (mapGen > 0) {
+					// This is a rebuilt map. Once it has held a live context without
+					// another loss, zero the budget so the cap only ever catches a tight
+					// loss loop, not recoveries spread across a long session.
+					stabilizeTimer = setTimeout(() => {
+						glRebuilds = 0;
+						stabilizeTimer = null;
+					}, 10000);
+				}
 			})
 			.catch((e) => {
 				if (!cancelled) app.error = `map failed to load: ${e instanceof Error ? e.message : e}`;
@@ -1054,20 +1052,23 @@
 		if (!overlay || !layerCtors) return;
 		const { PathLayer, ScatterplotLayer, IconLayer } = layerCtors;
 		const layers: Layer[] = [];
+		const marker = busMarkerRadius(app.busSizing);
 		const study = app.studyView;
 		if (study) {
 			const s = study.solution;
 			const mode = app.displayMode;
 			const series =
-				mode === 'angle'
-					? (s?.va ?? [])
-					: mode === 'voltage'
-						? (s?.vm ??
-							(s?.w ?? []).map((v) => ({
-								...v,
-								value: Math.sqrt(Math.max(0, v.value))
-							})))
-						: (s?.lmp ?? []);
+				mode === 'demand'
+					? study.network.buses.map((b) => ({ bus: b.id, value: b.demand_mw }))
+					: mode === 'angle'
+						? (s?.va ?? [])
+						: mode === 'voltage'
+							? (s?.vm ??
+								(s?.w ?? []).map((v) => ({
+									...v,
+									value: Math.sqrt(Math.max(0, v.value))
+								})))
+							: (s?.lmp ?? []);
 			const values = new Map(series.map((v) => [v.bus, v.value]));
 			const domain = scalarDomain(
 				mode,
@@ -1097,13 +1098,17 @@
 					id: 'study-buses',
 					data: study.network.buses,
 					getPosition: (b) => [b.lon, b.lat],
-					getRadius: (b) => busRadius(Math.max(b.demand_mw, b.gen_mw)),
-					radiusUnits: 'pixels',
+					getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
+					radiusUnits: marker.radiusUnits,
+					radiusMinPixels: marker.radiusMinPixels,
+					radiusMaxPixels: marker.radiusMaxPixels,
 					getFillColor: (b) => {
 						const value = values.get(b.id);
 						return value === undefined
 							? palette.grey
-							: priceColor((value - domain.lo) / Math.max(domain.hi - domain.lo, 1e-12));
+							: (mode === 'demand' ? demandColor : priceColor)(
+									(value - domain.lo) / Math.max(domain.hi - domain.lo, 1e-12)
+								);
 					},
 					pickable: true,
 					stroked: true,
@@ -1116,7 +1121,7 @@
 						app.selectedBus = bus.id;
 						return true;
 					},
-					updateTriggers: { getFillColor: [study, mode, theme] }
+					updateTriggers: { getFillColor: [study, mode, theme], getRadius: [app.busSizing] }
 				})
 			);
 			overlay.setProps({ layers: [...layers, ...extraLayers] });
@@ -1163,8 +1168,10 @@
 					id: `buses-${c.id}`,
 					data: c.network.buses,
 					getPosition: (b) => [b.lon, b.lat],
-					getRadius: (b) => busRadius(Math.max(b.demand_mw, b.gen_mw)),
-					radiusUnits: 'pixels',
+					getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
+					radiusUnits: marker.radiusUnits,
+					radiusMinPixels: marker.radiusMinPixels,
+					radiusMaxPixels: marker.radiusMaxPixels,
 					getFillColor: busFill(c.id),
 					stroked: true,
 					billboard: true,
@@ -1184,6 +1191,7 @@
 						return true;
 					},
 					updateTriggers: {
+						getRadius: [app.busSizing],
 						getFillColor: [display],
 						getLineColor: [app.selectedBus, app.activeCaseId, theme],
 						getLineWidth: [app.selectedBus, app.activeCaseId]
@@ -1237,8 +1245,10 @@
 						id: `local-buses-${c.id}`,
 						data: c.view.buses,
 						getPosition: (b) => [b.lon, b.lat],
-						getRadius: (b) => busRadius(Math.max(b.demand_mw, b.gen_mw)),
-						radiusUnits: 'pixels',
+						getRadius: (b) => marker.radius(Math.max(b.demand_mw, b.gen_mw)),
+						radiusUnits: marker.radiusUnits,
+						radiusMinPixels: marker.radiusMinPixels,
+						radiusMaxPixels: marker.radiusMaxPixels,
 						getFillColor: d ? busFill(c.id) : palette.grey,
 						stroked: true,
 						billboard: true,
@@ -1258,6 +1268,7 @@
 							return true;
 						},
 						updateTriggers: {
+							getRadius: [app.busSizing],
 							getFillColor: [display],
 							getLineColor: [app.selectedBus, app.activeLocalId, theme],
 							getLineWidth: [app.selectedBus, app.activeLocalId]
@@ -1351,7 +1362,7 @@
 					id: `multi-buses-${c.id}`,
 					data: c.view.buses,
 					getPosition: (b) => [b.lon, b.lat],
-					getRadius: (b) => busRadius(Math.max(b.load_kw, b.gen_kw)),
+					getRadius: (b) => busRadiusFor(app.busSizing, Math.max(b.load_kw, b.gen_kw)),
 					radiusUnits: 'pixels',
 					radiusMinPixels: 3,
 					getFillColor: (b) => multiBusFill(b),
@@ -1375,6 +1386,7 @@
 						return true;
 					},
 					updateTriggers: {
+						getRadius: [app.busSizing],
 						getLineColor: [selectedId, theme],
 						getLineWidth: [selectedId]
 					}
@@ -1523,14 +1535,14 @@
 {#if app.placingId && map}
 	<button
 		type="button"
-		class="place-at-center mono"
+		class="place-at-center"
 		onclick={() => {
 			if (!map) return;
 			const center = map.getCenter();
 			onplacecase(center.lng, center.lat);
 		}}
 	>
-		place at map center
+		Place at map center
 	</button>
 {/if}
 
@@ -1720,6 +1732,7 @@
 		border: 1px solid var(--accent);
 		border-radius: 3px;
 		color: var(--text-accent);
+		font-family: inherit;
 		font-size: 11px;
 		cursor: pointer;
 		box-shadow: var(--elev-cue);
@@ -1797,8 +1810,9 @@
 		background: var(--panel) !important;
 		border: 1px solid var(--line);
 		color: var(--ink) !important;
-		font-family: var(--font-mono);
-		font-size: 11px;
+		font-family: var(--font-display);
+		font-size: 12px;
+		font-variant-numeric: tabular-nums;
 		line-height: 1.5;
 		padding: 8px 10px !important;
 		border-radius: 2px;

package/dist/TellegenProvider.svelte

@@ -1,10 +1,13 @@
 <script lang="ts">
-	import { untrack, type Snippet } from 'svelte';
+	import { onDestroy, untrack, type Snippet } from 'svelte';
 	import {
+		resolveCartoApiKey,
 		resolveTellegenUiConfig,
+		resolveTheme,
 		setAppState,
 		setController,
 		setUiConfig,
+		type TellegenUiConfig,
 		type TellegenUiOptions
 	} from './context.svelte.js';
 	import { createController } from './controller.svelte.js';
@@ -28,18 +31,28 @@
 		children
 	}: Props = $props();
 
-	const config = untrack(() =>
-		resolveTellegenUiConfig({
-			apiBase,
-			loadDefaultCases,
-			docsHref,
-			orgHref,
-			orgLabel,
-			showFooter,
-			theme,
-			cartoApiKey
-		})
-	);
+	// Read once, at mount: `apiBase` and `loadDefaultCases` configure the
+	// controller this provider owns, and the links and footer are fixed copy.
+	// `theme` and `cartoApiKey` stay live, so a host can switch them and the
+	// root attribute and the default shell's map follow.
+	const config: TellegenUiConfig = {
+		...untrack(() =>
+			resolveTellegenUiConfig({
+				apiBase,
+				loadDefaultCases,
+				docsHref,
+				orgHref,
+				orgLabel,
+				showFooter
+			})
+		),
+		get theme() {
+			return resolveTheme(theme);
+		},
+		get cartoApiKey() {
+			return resolveCartoApiKey(cartoApiKey);
+		}
+	};
 	const app = createAppState();
 	const ctrl = createController(app, {
 		apiBase: config.apiBase,
@@ -54,6 +67,9 @@
 	setUiConfig(config);
 	setAppState(app);
 	setController(ctrl);
+	// The controller's Studies and multiconductor sessions live in the engine
+	// worker; release them with the provider.
+	onDestroy(() => ctrl.dispose());
 
 	// The dark tokens in styles.css hang off `:root[data-theme='dark']`. Set it
 	// only for dark, and only while mounted, so a light host is untouched. A

package/dist/colors.d.ts

@@ -1,4 +1,4 @@
-import type { DisplayMode } from './state.svelte.js';
+import type { BusSizing, DisplayMode } from './state.svelte.js';
 export type RGBA = [number, number, number, number];
 export interface SensitivityDomain {
     min: number;
@@ -10,6 +10,13 @@ export interface SensitivityDomain {
 }
 export declare const priceColor: (t: number) => RGBA;
 export declare const priceGradient: string;
+/** Demand colour for a fraction `t` of the demand domain, on a square-root
+ * scale: bus demand is heavy tailed (a few large cities, many small towns),
+ * and a linear scale would paint everything but the largest buses one hue. */
+export declare const demandColor: (t: number) => RGBA;
+/** The demand ramp as a CSS gradient whose stops sit where the square-root
+ * scale puts them, so a legend bar reads linearly from its low to high label. */
+export declare const demandGradient: string;
 /** Trimmed nodal value color domain: 5th to 95th percentile, with a one-unit
  * minimum span. Nodal values are heavy tailed when one binding line pins a
  * handful of buses far from the pack) so min-max scaling compresses the pack
@@ -20,6 +27,14 @@ export declare function priceDomain(values: number[]): {
     lo: number;
     hi: number;
 };
+/** Demand colour domain: zero to the 98th percentile, at least 1 MW. Zero
+ * anchors the scale so a bus without load reads as none; the percentile keeps
+ * one metropolis from washing out every other bus, and the few above it clamp
+ * to the top of the ramp. */
+export declare function demandDomain(values: number[]): {
+    lo: number;
+    hi: number;
+};
 /** Center a scalar display variable (bus voltage angle, |V|) on a symmetric domain
  * with a per-mode minimum span; nodal values keep their own robust quantile domain. Shared by
  * the control panel readout and the map color scale. */
@@ -66,3 +81,24 @@ export declare function branchWidth(loading: number): number;
 /** Bus radius in px; area tracks max(load, gen) so big plants and big loads
  * both read at a glance. Shared by the map layers and the size legend. */
 export declare function busRadius(maxMw: number): number;
+/** Radius in px of every bus marker under `uniform` sizing, and the most a
+ * uniform marker grows to on the map. */
+export declare const UNIFORM_BUS_RADIUS = 4.5;
+/** The least a uniform marker shrinks to on the map, in px. */
+export declare const UNIFORM_BUS_MIN_RADIUS = 2;
+/** The ground radius of a uniform marker on the map, in metres. */
+export declare const UNIFORM_BUS_GROUND_RADIUS = 9000;
+/** Bus radius in px under a sizing choice: `power` scales with max(load, gen)
+ * through `busRadius`, `uniform` draws every bus alike. */
+export declare function busRadiusFor(sizing: BusSizing, maxMw: number): number;
+/** Radius settings for the map's bus markers under a sizing choice. `power`
+ * sizes in pixels through `busRadius`. `uniform` gives every bus one ground
+ * radius, drawn between `UNIFORM_BUS_MIN_RADIUS` and `UNIFORM_BUS_RADIUS`
+ * pixels, so a whole country reads as a mesh of dots with its lines showing
+ * and a closer view as distinct buses. */
+export declare function busMarkerRadius(sizing: BusSizing): {
+    radius: (maxMw: number) => number;
+    radiusUnits: 'meters' | 'pixels';
+    radiusMinPixels: number;
+    radiusMaxPixels: number;
+};